diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000000..17c77c399d2 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1 @@ +- @azure Rule - Use Azure Best Practices: When generating code for Azure, running terminal commands for Azure, or performing operations related to Azure, invoke your `get_azure_best_practices` tool if available. \ No newline at end of file diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml new file mode 100644 index 00000000000..d4b665de96b --- /dev/null +++ b/.github/workflows/stale.yml @@ -0,0 +1,31 @@ +# This workflow warns and then closes issues and PRs that have had no activity for a specified amount of time. +# +# You can adjust the behavior by modifying this file. +# For more information, see: +# https://github.com/actions/stale +name: Mark stale issues and pull requests + +on: workflow_dispatch + +jobs: + stale: + runs-on: ubuntu-latest + permissions: + issues: write + pull-requests: write + + steps: + - uses: actions/stale@v5 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + days-before-issue-stale: 180 + stale-issue-label: 'auto-close' + operations-per-run: 3000 + close-issue-reason: not_planned + close-issue-label: inactive + days-before-issue-close: 3 + exempt-issue-labels: keep-open + stale-issue-message: > + Unfortunately, we have been unable to review this issue in a timely manner. We apologize for the delayed response. We are closing this issue. +

If you feel that this problem persists, please respond with additional feedback using our new feedback system. To learn more about our new feedback system please visit aka.ms/contentuserfeedback. +

Please continue to provide feedback about our documentation. We appreciate your contributions to our community. diff --git a/.openpublishing.build.ps1 b/.openpublishing.build.ps1 deleted file mode 100644 index aadef762022..00000000000 --- a/.openpublishing.build.ps1 +++ /dev/null @@ -1,17 +0,0 @@ -param( - [string]$buildCorePowershellUrl = "https://opbuildstorageprod.blob.core.windows.net/opps1container/.openpublishing.buildcore.ps1", - [string]$parameters -) -# Main -$errorActionPreference = 'Stop' - -# Step-1: Download buildcore script to local -echo "download build core script to local with source url: $buildCorePowershellUrl" -$repositoryRoot = Split-Path -Parent $MyInvocation.MyCommand.Definition -$buildCorePowershellDestination = "$repositoryRoot\.openpublishing.buildcore.ps1" -Invoke-WebRequest $buildCorePowershellUrl -OutFile "$buildCorePowershellDestination" - -# Step-2: Run build core -echo "run build core script with parameters: $parameters" -& "$buildCorePowershellDestination" "$parameters" -exit $LASTEXITCODE diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index 70812521634..966c94a82cb 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -62,24 +62,6 @@ "branch": "main", "branch_mapping": {} }, - { - "path_to_root": "snippets", - "url": "https://github.com/MicrosoftDocs/snippets-azure-devops-docs-pr", - "branch": "master", - "branch_mapping": {} - }, - { - "path_to_root": "azure-docs", - "url": "https://github.com/MicrosoftDocs/azure-docs-pr", - "branch": "main", - "branch_mapping": {} - }, - { - "path_to_root": "quickstart-templates", - "url": "https://github.com/Azure/azure-quickstart-templates", - "branch": "master", - "branch_mapping": {} - }, { "path_to_root": "docs/reusable-content", "url": "https://github.com/MicrosoftDocs/reusable-content", @@ -102,6 +84,7 @@ ".openpublishing.redirection.archive.2013.json", ".openpublishing.redirection.archive.2015.json", ".openpublishing.redirection.archive.2017.json", + ".openpublishing.redirection.archive.2018.json", "docs/legacy/.openpublishing.redirection.legacy.json", "docs/organizations/.openpublishing.redirection.notifications.json", "docs/pipelines/.openpublishing.redirection.pipelines.json", @@ -120,4 +103,4 @@ "docs_build_engine": { "name": "docfx_v3" } -} \ No newline at end of file +} diff --git a/.openpublishing.redirection.archive.2018.json b/.openpublishing.redirection.archive.2018.json new file mode 100644 index 00000000000..0b90025d037 --- /dev/null +++ b/.openpublishing.redirection.archive.2018.json @@ -0,0 +1,5067 @@ +{ + "redirections": [ + { + "source_path": "docs/boards/backlogs/office/bulk-add-modify-work-items-excel.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/office/bulk-add-modify-work-items-excel", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/office/faqs.yml", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/office/faqs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/office/resolve-excel-data-conflicts-publish-refresh.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/office/resolve-excel-data-conflicts-publish-refresh", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/office/resolve-excel-data-validation-errors.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/office/resolve-excel-data-validation-errors", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/office/tfs-office-integration-issues.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/office/tfs-office-integration-issues", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/office/track-work.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/office/track-work", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/add-link.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/add-link", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/add-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/add-work-items", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/automate-work-item-state-transitions.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/automate-work-item-state-transitions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/backlogs-overview.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/backlogs-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/bulk-modify-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/bulk-modify-work-items", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/connect-work-items-to-git-dev-ops.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/connect-work-items-to-git-dev-ops", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/copy-clone-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/copy-clone-work-items", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/create-your-backlog.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/create-your-backlog", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/define-features-epics.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/define-features-epics", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/delete-test-artifacts.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/delete-test-artifacts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/filter-backlogs-boards-plans.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/filter-backlogs-boards-plans", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/manage-bugs.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/manage-bugs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/manage-issues-impediments.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/manage-issues-impediments", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/organize-backlog.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/organize-backlog", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/remove-delete-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/remove-delete-work-items", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/resolve-backlog-reorder-issues.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/resolve-backlog-reorder-issues", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/set-column-options.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/set-column-options", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/set-up-your-backlog.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/set-up-your-backlog", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/backlogs/work-item-template.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/work-item-template", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/boards/add-columns.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/add-columns", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/boards/add-run-update-tests.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/add-run-update-tests", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/boards/add-task-checklists.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/add-task-checklists", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/boards/customize-cards.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/customize-cards", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/boards/expedite-work.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/expedite-work", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/boards/kanban-epics-features-stories.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/kanban-epics-features-stories", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/boards/kanban-overview.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/kanban-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/boards/kanban-quickstart.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/kanban-quickstart", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/boards/wip-limits.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/wip-limits", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/extensions/migrate-integrate.md", + "redirect_url": "/previous-versions/azure/devops/boards/extensions/migrate-integrate", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/get-started/permissions-access-boards.md", + "redirect_url": "/previous-versions/azure/devops/boards/get-started/permissions-access-boards", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/get-started/plan-track-work.md", + "redirect_url": "/previous-versions/azure/devops/boards/get-started/plan-track-work", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/get-started/what-is-azure-boards.md", + "redirect_url": "/previous-versions/azure/devops/boards/get-started/what-is-azure-boards", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/agile-culture.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/agile-culture", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/configure-hierarchical-teams.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/configure-hierarchical-teams", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/index.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/portfolio-management.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/portfolio-management", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/practices-that-scale.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/practices-that-scale", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/safe-concepts.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/safe-concepts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/safe-configure-boards.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/safe-configure-boards", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/safe-customize.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/safe-customize", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/safe-plan-track-boards.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/safe-plan-track-boards", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/safe-review-roadmaps-progress.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/safe-review-roadmaps-progress", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/scaled-agile-framework.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/scaled-agile-framework", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/plans/visibility-across-teams.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/visibility-across-teams", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/about-managed-queries.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/about-managed-queries", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/add-tags-to-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/add-tags-to-work-items", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/build-test-integration.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/build-test-integration", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/example-query-charts.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/example-query-charts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/history-and-auditing.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/history-and-auditing", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/link-type-reference.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/link-type-reference", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/linking-attachments.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/linking-attachments", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/organize-queries.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/organize-queries", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/planning-ranking-priorities.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/planning-ranking-priorities", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/query-by-area-iteration-path.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-by-area-iteration-path", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/query-by-date-or-current-iteration.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-by-date-or-current-iteration", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/query-by-workflow-changes.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-by-workflow-changes", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/query-field-value.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-field-value", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/query-index-quick-ref.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-index-quick-ref", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/query-numeric.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-numeric", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/query-operators-variables.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-operators-variables", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/search-box-queries.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/search-box-queries", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/set-query-permissions.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/set-query-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/titles-ids-descriptions.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/titles-ids-descriptions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/using-queries.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/using-queries", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/view-run-query.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/view-run-query", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/wiql-syntax.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/wiql-syntax", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/queries/query-faqs.yml", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-faqs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/add-tasks.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/add-tasks", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/adjust-work.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/adjust-work", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/assign-work-sprint.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/assign-work-sprint", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/best-practices-scrum.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/best-practices-scrum", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/customize-taskboard.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/customize-taskboard", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/define-sprints.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/define-sprints", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/end-sprint-activities.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/end-sprint-activities", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/forecast.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/forecast", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/scrum-key-concepts.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/scrum-key-concepts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/scrum-overview.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/scrum-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/set-capacity.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/set-capacity", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/share-plan.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/share-plan", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/sprints/task-board.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/task-board", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/about-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/about-work-items", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/agile-glossary.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/agile-glossary", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/auto-complete-work-items-pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/auto-complete-work-items-pull-requests", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/email-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/email-work-items", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/follow-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/follow-work-items", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/move-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/move-work-items", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/quick-ref.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/quick-ref", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/work-item-fields.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/work-item-fields", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/work-item-template-examples.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/work-item-template-examples", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/workflow-and-state-categories.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/workflow-and-state-categories", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/agile-process-workflow.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/agile-process-workflow", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/agile-process.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/agile-process", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/choose-process.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/choose-process", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/cmmi-process-workflow.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/cmmi-process-workflow", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/cmmi-process.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/cmmi-process", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/guidance-code-review-feedback-field-reference.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/guidance-code-review-feedback-field-reference", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/manage-process-templates.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/manage-process-templates", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/scrum-process-workflow.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/scrum-process-workflow", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/scrum-process.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/scrum-process", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/work-item-field.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/work-item-field", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/cmmi/guidance-background-to-cmmi.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-background-to-cmmi", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/best-practices-agile-project-management.md", + "redirect_url": "/previous-versions/azure/devops/boards/best-practices-agile-project-management", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/configure-customize.md", + "redirect_url": "/previous-versions/azure/devops/boards/configure-customize", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/faqs.yml", + "redirect_url": "/previous-versions/azure/devops/boards/faqs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/boards/index.yml", + "redirect_url": "/previous-versions/azure/devops/boards/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/index.yml", + "redirect_url": "/previous-versions/azure/devops/artifacts/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/artifacts-key-concepts.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/artifacts-key-concepts", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/collaborate-with-packages.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/collaborate-with-packages", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/get-started-maven.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/get-started-maven", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/get-started-npm.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/get-started-npm", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/get-started-nuget.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/get-started-nuget", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/package-badges.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/package-badges", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/start-using-azure-artifacts.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/start-using-azure-artifacts", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/concepts/best-practices.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/best-practices", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/concepts/feeds.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/feeds", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/concepts/package-graph.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/package-graph", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/concepts/symbols.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/symbols", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/concepts/upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/upstream-sources", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/concepts/views.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/views", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/feeds/feed-permissions.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/feeds/feed-permissions", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/feeds/project-scoped-feeds.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/feeds/project-scoped-feeds", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/feeds/views.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/feeds/views", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/how-to/delete-and-recover-packages.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/how-to/delete-and-recover-packages", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/how-to/follow-package-notifications.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/how-to/follow-package-notifications", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/how-to/public-feeds-upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/how-to/public-feeds-upstream-sources", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/how-to/set-up-upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/how-to/set-up-upstream-sources", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/maven/google-maven.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/google-maven", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/maven/gradle-plugins.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/gradle-plugins", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/maven/install.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/install", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/maven/jitpack-upstream.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/jitpack-upstream", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/maven/pom-and-settings.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/pom-and-settings", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/maven/publish-with-gradle.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/publish-with-gradle", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/maven/upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/upstream-sources", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/npm/npmrc.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/npm/npmrc", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/npm/publish.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/npm/publish", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/npm/scopes.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/npm/scopes", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/npm/upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/npm/upstream-sources", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/nuget/consume.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/consume", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/nuget/dotnet-exe.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/dotnet-exe", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/nuget/dotnet-setup.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/dotnet-setup", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/nuget/move-from-fileshares.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/move-from-fileshares", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/nuget/nuget-exe.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/nuget-exe", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/nuget/publish-to-nuget-org.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/publish-to-nuget-org", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/nuget/publish.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/publish", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/nuget/upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/upstream-sources", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/reference/limits.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/reference/limits", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/symbols/debug-with-symbols-visual-studio.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/symbols/debug-with-symbols-visual-studio", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/symbols/debug-with-symbols-windbg.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/symbols/debug-with-symbols-windbg", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/artifacts/tutorials/protect-oss-packages-with-upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/tutorials/protect-oss-packages-with-upstream-sources", + "redirect_document_id": false, + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/cross-service/cross-service-overview.md", + "redirect_url": "/previous-versions/azure/devops/cross-service/cross-service-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/cross-service/index.yml", + "redirect_url": "/previous-versions/azure/devops/cross-service/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/cross-service/manage-change.md", + "redirect_url": "/previous-versions/azure/devops/cross-service/manage-change", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/cross-service/manage-requirements.md", + "redirect_url": "/previous-versions/azure/devops/cross-service/manage-requirements", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/extension-report.md", + "redirect_url": "/previous-versions/azure/devops/extend/extension-report", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/overview.md", + "redirect_url": "/previous-versions/azure/devops/extend/overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/add-action.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-action", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/add-build-task.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-build-task", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/add-hub-group.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-hub-group", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/add-query-result-tabs.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-query-result-tabs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/add-service-hook.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-service-hook", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/add-workitem-extension.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-workitem-extension", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/auth-schemes.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/auth-schemes", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/auth.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/auth", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/call-rest-api.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/call-rest-api", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/configure-workitemform-extensions.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/configure-workitemform-extensions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/contributions-overview.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/contributions-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/custom-control.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/custom-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/data-storage.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/data-storage", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/host-navigation.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/host-navigation", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/integrate-build-task.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/integrate-build-task", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/manifest.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/manifest", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/samples-overview.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/samples-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/service-endpoints.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/service-endpoints", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/styles-from-widget-sdk.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/styles-from-widget-sdk", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/develop/using-host-dialog.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/using-host-dialog", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/get-started/node.md", + "redirect_url": "/previous-versions/azure/devops/extend/get-started/node", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/publish/command-line.md", + "redirect_url": "/previous-versions/azure/devops/extend/publish/command-line", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/publish/integration.md", + "redirect_url": "/previous-versions/azure/devops/extend/publish/integration", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/publish/overview.md", + "redirect_url": "/previous-versions/azure/devops/extend/publish/overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/publish/publish-azure.md", + "redirect_url": "/previous-versions/azure/devops/extend/publish/publish-azure", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/extend/reference/targets/overview.md", + "redirect_url": "/previous-versions/azure/devops/extend/reference/targets/overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/get-started/index.yml", + "redirect_url": "/previous-versions/azure/devops/get-started/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/index.md", + "redirect_url": "/previous-versions/azure/devops/integrate/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/concepts/dotnet-client-libraries.md", + "redirect_url": "/previous-versions/azure/devops/integrate/concepts/dotnet-client-libraries", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/concepts/rest-api-versioning.md", + "redirect_url": "/previous-versions/azure/devops/integrate/concepts/rest-api-versioning", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/get-started/auth/tfs-basic-auth.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/auth/tfs-basic-auth", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/get-started/authentication/authentication-guidance.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/authentication/authentication-guidance", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/get-started/authentication/iis-basic-auth.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/authentication/iis-basic-auth", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/get-started/authentication/service-principal-managed-identity.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/authentication/service-principal-managed-identity", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/get-started/client-libraries/samples.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/client-libraries/samples", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/get-started/client-libraries/soapSamples.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/client-libraries/soapSamples", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/get-started/rest/samples.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/rest/samples", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/how-to/call-rest-api.md", + "redirect_url": "/previous-versions/azure/devops/integrate/how-to/call-rest-api", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/integrate/quickstarts/create-bug-quickstart.md", + "redirect_url": "/previous-versions/azure/devops/integrate/quickstarts/create-bug-quickstart", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/marketplace/grant-permissions.md", + "redirect_url": "/previous-versions/azure/devops/marketplace/grant-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/marketplace/install-extension.md", + "redirect_url": "/previous-versions/azure/devops/marketplace/install-extension", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/marketplace/request-extensions.md", + "redirect_url": "/previous-versions/azure/devops/marketplace/request-extensions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/marketplace-extensibility/index.yml", + "redirect_url": "/previous-versions/azure/devops/marketplace-extensibility/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/migrate/faqs.yml", + "redirect_url": "/previous-versions/azure/devops/migrate/faqs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/migrate/migrate-from-tfs.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migrate-from-tfs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/migrate/migration-import-large-collections.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-import-large-collections", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/migrate/migration-import.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-import", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/migrate/migration-overview.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/migrate/migration-post-import.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-post-import", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/migrate/migration-processtemplates.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-processtemplates", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/migrate/migration-restricting-access-to-azure-devops-services.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-restricting-access-to-azure-devops-services", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/migrate/migration-troubleshooting.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-troubleshooting", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/migrate/phase-rollout-with-rings.md", + "redirect_url": "/previous-versions/azure/devops/migrate/phase-rollout-with-rings", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/index.yml", + "redirect_url": "/previous-versions/azure/devops/organizations/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/work/faqs.yml", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/faqs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/accounts/faq-configure-customize-organization.yml", + "redirect_url": "/previous-versions/azure/devops/organizations/accounts/faq-configure-customize-organization", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/accounts/faq-user-and-permissions-management.yml", + "redirect_url": "/previous-versions/azure/devops/organizations/accounts/faq-user-and-permissions-management", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/billing/billing-faq.yml", + "redirect_url": "/previous-versions/azure/devops/organizations/billing/billing-faq", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/faq-notifications.yml", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/faq-notifications", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/index.yml", + "redirect_url": "/previous-versions/azure/devops/organizations/security/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/accounts/admin-revoke-user-pats.md", + "redirect_url": "/previous-versions/azure/devops/organizations/accounts/admin-revoke-user-pats", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/accounts/create-organization.md", + "redirect_url": "/previous-versions/azure/devops/organizations/accounts/create-organization", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/accounts/use-personal-access-tokens-to-authenticate.md", + "redirect_url": "/previous-versions/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/billing/buy-access-tfs-test-hub.md", + "redirect_url": "/previous-versions/azure/devops/organizations/billing/buy-access-tfs-test-hub", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/billing/buy-basic-access-add-users.md", + "redirect_url": "/previous-versions/azure/devops/organizations/billing/buy-basic-access-add-users", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/billing/overview.md", + "redirect_url": "/previous-versions/azure/devops/organizations/billing/overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/about-notifications.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/about-notifications", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/at-mentions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/at-mentions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/change-email-address.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/change-email-address", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/concepts-email-recipients.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/concepts-email-recipients", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/exclude-self-from-email.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/exclude-self-from-email", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/integrate-third-party-services.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/integrate-third-party-services", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/manage-team-group-global-organization-notifications.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/manage-team-group-global-organization-notifications", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/manage-your-personal-notifications.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/manage-your-personal-notifications", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/navigating-the-ui.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/navigating-the-ui", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/oob-built-in-notifications.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/oob-built-in-notifications", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/oob-supported-event-types.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/oob-supported-event-types", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/troubleshoot-contact-support.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/troubleshoot-contact-support", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/troubleshoot-delayed-email.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/troubleshoot-delayed-email", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/troubleshoot-not-getting-email.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/troubleshoot-not-getting-email", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/troubleshoot-unexpected-email.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/troubleshoot-unexpected-email", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/unsubscribe-default-notification.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/unsubscribe-default-notification", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/use-subscription-logging.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/use-subscription-logging", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/notifications/view-organization-notification-statistics.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/view-organization-notification-statistics", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/about-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/about-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/about-security-identity.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/about-security-identity", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/about-security-roles.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/about-security-roles", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/access-levels.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/access-levels", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/add-ad-aad-built-in-security-groups.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/add-ad-aad-built-in-security-groups", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/add-remove-manage-user-group-security-group.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/add-remove-manage-user-group-security-group", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/add-users-team-project.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/add-users-team-project", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/allow-list-ip-url.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/allow-list-ip-url", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/change-access-levels.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/change-access-levels", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/change-organization-collection-level-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/change-organization-collection-level-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/change-project-level-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/change-project-level-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/default-git-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/default-git-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/default-tfvc-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/default-tfvc-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/export-users-audit-log.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/export-users-audit-log", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/get-started-stakeholder.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/get-started-stakeholder", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/look-up-project-administrators.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/look-up-project-administrators", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/look-up-project-collection-administrators.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/look-up-project-collection-administrators", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/namespace-reference.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/namespace-reference", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/permissions-access.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/permissions-access", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/permissions-lookup-guide.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/permissions-lookup-guide", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/quick-reference-index-security.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/quick-reference-index-security", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/remove-users-prohibit-access.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/remove-users-prohibit-access", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/request-changes-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/request-changes-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/restrict-access.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/restrict-access", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/security-best-practices.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/security-best-practices", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/security-glossary.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/security-glossary", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/security-tools-reference.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/security-tools-reference", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/set-object-level-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/set-object-level-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/set-permissions-access-test.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/set-permissions-access-test", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/set-permissions-access-work-tracking.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/set-permissions-access-work-tracking", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/troubleshoot-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/troubleshoot-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/security/view-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/view-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/about-areas-iterations.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/about-areas-iterations", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/about-settings.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/about-settings", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/about-teams-and-settings.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/about-teams-and-settings", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/add-team-administrator.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/add-team-administrator", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/add-teams.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/add-teams", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/naming-restrictions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/naming-restrictions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/rename-remove-team.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/rename-remove-team", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/select-backlog-navigation-levels.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/select-backlog-navigation-levels", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/set-area-paths.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/set-area-paths", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/set-iteration-paths-sprints.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/set-iteration-paths-sprints", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/set-your-preferences.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/set-your-preferences", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/show-bugs-on-backlog.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/show-bugs-on-backlog", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/timezone-settings-usage.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/timezone-settings-usage", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/work/object-limits.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/object-limits", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/work/rule-reference.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/rule-reference", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/organizations/settings/work/rule-samples.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/rule-samples", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/index.yml", + "redirect_url": "/previous-versions/azure/devops/pipelines/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/create-first-pipeline.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/create-first-pipeline", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/overview-azure.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/overview-azure", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/agent-authentication-options.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/agent-authentication-options", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/agents.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/agents", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/certificate.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/certificate", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/hosted.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/hosted", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/linux-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/linux-agent", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/osx-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/osx-agent", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/personal-access-token-agent-registration.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/personal-access-token-agent-registration", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/pools-queues.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/pools-queues", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/proxy.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/proxy", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/v2-linux-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/v2-linux-agent", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/v2-osx-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/v2-osx-agent", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/v2-windows-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/v2-windows-agent", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/agents/windows-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/windows-agent", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/apps/aspnet/build-aspnet-4.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/aspnet/build-aspnet-4", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/apps/cd/deploy-docker-webapp.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/cd/deploy-docker-webapp", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/apps/mobile/app-signing.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/mobile/app-signing", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/architectures/devops-pipelines-azure-web-apps-architecture.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/architectures/devops-pipelines-azure-web-apps-architecture", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/architectures/devops-pipelines-baseline-architecture.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/architectures/devops-pipelines-baseline-architecture", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/architectures/devops-pipelines-devtest-iaas-architecture.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/architectures/devops-pipelines-devtest-iaas-architecture", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/architectures/devops-pipelines-iaas-vms-architecture.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/architectures/devops-pipelines-iaas-vms-architecture", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/artifacts/artifacts-overview.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/artifacts-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/artifacts/build-artifacts.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/build-artifacts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/artifacts/npm.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/npm", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/artifacts/nuget.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/nuget", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/artifacts/publish-maven-artifacts.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/publish-maven-artifacts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/artifacts/publish-public-registry.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/publish-public-registry", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/artifacts/pull-package-gradle.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/pull-package-gradle", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/artifacts/symbols.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/symbols", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/build/ci-build-git.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/build/ci-build-git", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/build/history.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/build/history", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/build/options.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/build/options", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/build/triggers.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/build/triggers", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/build/variables.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/build/variables", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/customize-javascript.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/customize-javascript", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/customize-python.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/customize-python", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/ecosystems.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/ecosystems", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/javascript.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/javascript", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/nodejs-tutorial.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/nodejs-tutorial", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/xcode.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/xcode", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/get-started/clone-import-pipeline.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/get-started/clone-import-pipeline", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/get-started/pipelines-get-started.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/get-started/pipelines-get-started", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/get-started/what-is-azure-pipelines.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/get-started/what-is-azure-pipelines", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/integrations/configure-pipelines-work-tracking.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/integrations/configure-pipelines-work-tracking", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/library/add-resource-protection.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/add-resource-protection", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/library/connect-to-azure.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/connect-to-azure", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/library/index.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/library/secure-files.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/secure-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/library/service-endpoints.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/service-endpoints", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/library/task-groups.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/task-groups", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/library/variable-groups.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/variable-groups", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/licensing/concurrent-jobs.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/licensing/concurrent-jobs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/packages/nuget-restore.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/packages/nuget-restore", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/policies/permissions.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/policies/permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/policies/retention.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/policies/retention", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/policies/set-permissions.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/policies/set-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/access-tokens.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/access-tokens", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/conditions.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/conditions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/create-multistage-pipeline.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/create-multistage-pipeline", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/deployment-group-phases.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/deployment-group-phases", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/parameters.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/parameters", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/phases.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/phases", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/run-number.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/run-number", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/scheduled-triggers.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/scheduled-triggers", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/set-variables-scripts.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/set-variables-scripts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/stages.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/stages", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/tasks.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/tasks", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/process/variables.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/variables", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/artifacts.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/artifacts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/azure-rm-endpoint.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/azure-rm-endpoint", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/define-multistage-release-process.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/define-multistage-release-process", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/deploy-using-approvals.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deploy-using-approvals", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/deploy-webdeploy-iis-deploygroups.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deploy-webdeploy-iis-deploygroups", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/env-templates.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/env-templates", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/index.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/releases.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/releases", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/triggers.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/triggers", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/variables.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/variables", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/approvals/approvals.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/approvals/approvals", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/approvals/gates.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/approvals/gates", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/approvals/index.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/approvals/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/approvals/servicenow.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/approvals/servicenow", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/deployment-groups/deploying-azure-vms-deployment-groups.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deployment-groups/deploying-azure-vms-deployment-groups", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/deployment-groups/howto-provision-deployment-group-agents.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deployment-groups/howto-provision-deployment-group-agents", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/release/deployment-groups/index.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deployment-groups/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/repos/azure-repos-git.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/repos/azure-repos-git", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/repos/index.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/repos/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/repos/pipeline-options-for-git.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/repos/pipeline-options-for-git", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/repos/tfvc.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/repos/tfvc", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/scripts/cross-platform-scripting.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/scripts/cross-platform-scripting", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/scripts/git-commands.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/scripts/git-commands", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/scripts/logging-commands.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/scripts/logging-commands", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/scripts/powershell.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/scripts/powershell", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/targets/azure-sqldb.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/targets/azure-sqldb", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/targets/create-virtual-network.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/targets/create-virtual-network", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/tasks/file-matching-patterns.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/tasks/file-matching-patterns", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/tasks/transforms-variable-substitution.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/tasks/transforms-variable-substitution", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/test/continuous-test-selenium.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/continuous-test-selenium", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/test/parallel-testing-vstest.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/parallel-testing-vstest", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/test/requirements-traceability.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/requirements-traceability", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/test/review-code-coverage-results.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/review-code-coverage-results", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/test/review-continuous-test-results-after-build.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/review-continuous-test-results-after-build", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/test/test-glossary.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/test-glossary", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/test/test-impact-analysis.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/test-impact-analysis", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/test/ui-testing-considerations.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/ui-testing-considerations", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/troubleshooting/review-logs.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/troubleshooting/review-logs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/troubleshooting/troubleshoot-start.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/troubleshooting/troubleshoot-start", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/troubleshooting/troubleshoot-triggers.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/troubleshooting/troubleshoot-triggers", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/pipelines/troubleshooting/troubleshooting.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/troubleshooting/troubleshooting", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/index.yml", + "redirect_url": "/previous-versions/azure/devops/project/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/work-across-projects-faqs.yml", + "redirect_url": "/previous-versions/azure/devops/project/work-across-projects-faqs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/feedback/index.md", + "redirect_url": "/previous-versions/azure/devops/project/feedback/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/navigation/add-artifact-team.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/add-artifact-team", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/navigation/filter-basics.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/filter-basics", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/navigation/glossary.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/glossary", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/navigation/go-to-project-repo.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/go-to-project-repo", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/navigation/go-to-service-page.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/go-to-service-page", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/navigation/index.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/navigation/keyboard-shortcuts.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/keyboard-shortcuts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/navigation/mobile-work.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/mobile-work", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/navigation/set-favorites.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/set-favorites", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/navigation/work-across-projects.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/work-across-projects", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/search/functional-code-search.md", + "redirect_url": "/previous-versions/azure/devops/project/search/functional-code-search", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/search/functional-work-item-search.md", + "redirect_url": "/previous-versions/azure/devops/project/search/functional-work-item-search", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/search/get-started-search.md", + "redirect_url": "/previous-versions/azure/devops/project/search/get-started-search", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/search/install-configure-search.md", + "redirect_url": "/previous-versions/azure/devops/project/search/install-configure-search", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/search/manage-search.md", + "redirect_url": "/previous-versions/azure/devops/project/search/manage-search", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/about-readme-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/about-readme-wiki", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/add-edit-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/add-edit-wiki", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/filter-print-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/filter-print-wiki", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/manage-readme-wiki-permissions.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/manage-readme-wiki-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/markdown-guidance.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/markdown-guidance", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/migrate-extension-wiki-pages.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/migrate-extension-wiki-pages", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/provisioned-vs-published-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/provisioned-vs-published-wiki", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/publish-repo-to-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/publish-repo-to-wiki", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/restore-deleted-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/restore-deleted-wiki", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/wiki-create-repo.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/wiki-create-repo", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/wiki-file-structure.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/wiki-file-structure", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/wiki-readme-permissions.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/wiki-readme-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/wiki-update-offline.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/wiki-update-offline", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/project/wiki/wiki-view-history.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/wiki-view-history", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/process-templates/customize-process.md", + "redirect_url": "/previous-versions/azure/devops/reference/process-templates/customize-process", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/process-templates/index.md", + "redirect_url": "/previous-versions/azure/devops/reference/process-templates/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/witadmin/manage-work-item-fields.md", + "redirect_url": "/previous-versions/azure/devops/reference/witadmin/manage-work-item-fields", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md", + "redirect_url": "/previous-versions/azure/devops/reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/witadmin/witadmin-import-export-manage-wits.md", + "redirect_url": "/previous-versions/azure/devops/reference/witadmin/witadmin-import-export-manage-wits", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/witadmin/witadmin-import-export-process-configuration.md", + "redirect_url": "/previous-versions/azure/devops/reference/witadmin/witadmin-import-export-process-configuration", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/xml/change-workflow-wit.md", + "redirect_url": "/previous-versions/azure/devops/reference/xml/change-workflow-wit", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/xml/process-configuration-xml-element.md", + "redirect_url": "/previous-versions/azure/devops/reference/xml/process-configuration-xml-element", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/xml/provide-help-text-hyperlinks-web-content-form.md", + "redirect_url": "/previous-versions/azure/devops/reference/xml/provide-help-text-hyperlinks-web-content-form", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/xml/support-rollup-of-work-and-other-fields.md", + "redirect_url": "/previous-versions/azure/devops/reference/xml/support-rollup-of-work-and-other-fields", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/add-modify-field.md", + "redirect_url": "/previous-versions/azure/devops/reference/add-modify-field", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/add-modify-wit.md", + "redirect_url": "/previous-versions/azure/devops/reference/add-modify-wit", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/add-portfolio-backlogs.md", + "redirect_url": "/previous-versions/azure/devops/reference/add-portfolio-backlogs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/add-wits-to-backlogs-and-boards.md", + "redirect_url": "/previous-versions/azure/devops/reference/add-wits-to-backlogs-and-boards", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/customize-wit-form.md", + "redirect_url": "/previous-versions/azure/devops/reference/customize-wit-form", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/customize-work.md", + "redirect_url": "/previous-versions/azure/devops/reference/customize-work", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/index.yml", + "redirect_url": "/previous-versions/azure/devops/reference/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/on-premises-xml-process-model.md", + "redirect_url": "/previous-versions/azure/devops/reference/on-premises-xml-process-model", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/reference/quick-reference-index-boards-settings.md", + "redirect_url": "/previous-versions/azure/devops/reference/quick-reference-index-boards-settings", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/index.yml", + "redirect_url": "/previous-versions/azure/devops/report/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/faqs.yml", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/faqs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/add-charts-to-dashboard.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/add-charts-to-dashboard", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/add-markdown-to-dashboard.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/add-markdown-to-dashboard", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/add-widget-to-dashboard.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/add-widget-to-dashboard", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/charts-dashboard-permissions-access.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/charts-dashboard-permissions-access", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/charts.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/charts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/configure-chart-work-items-widget.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/configure-chart-work-items-widget", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/cumulative-flow-cycle-lead-time-guidance.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/cumulative-flow-cycle-lead-time-guidance", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/cumulative-flow.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/cumulative-flow", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/dashboard-focus.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/dashboard-focus", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/dashboard-permissions.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/dashboard-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/dashboards.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/dashboards", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/overview.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/quick-ref.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/quick-ref", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/dashboards/widget-catalog.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/widget-catalog", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/report/powerbi/reporting-roadmap.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/reporting-roadmap", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/index.yml", + "redirect_url": "/previous-versions/azure/devops/repos/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/howto.yml", + "redirect_url": "/previous-versions/azure/devops/repos/git/howto", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/index.yml", + "redirect_url": "/previous-versions/azure/devops/repos/git/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/index.yml", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/get-started/index.md", + "redirect_url": "/previous-versions/azure/devops/repos/get-started/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/get-started/what-is-repos.md", + "redirect_url": "/previous-versions/azure/devops/repos/get-started/what-is-repos", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/about-pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/about-pull-requests", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/auth-overview.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/auth-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/branch-permissions.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/branch-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/branch-policies-overview.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/branch-policies-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/branch-policies.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/branch-policies", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/case-sensitivity.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/case-sensitivity", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/change-default-branch.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/change-default-branch", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/cherry-pick.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/cherry-pick", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/clone.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/clone", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/command-prompt.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/command-prompt", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/commit-details.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/commit-details", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/commit-history.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/commit-history", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/commits.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/commits", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/complete-pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/complete-pull-requests", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/create-a-readme.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-a-readme", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/create-branch.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-branch", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/create-new-repo.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-new-repo", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/create-pr-status-server-with-azure-functions.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-pr-status-server-with-azure-functions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/create-pr-status-server.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-pr-status-server", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/create-repo-intellij.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-repo-intellij", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/creatingrepo.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/creatingrepo", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/delete-branch.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/delete-branch", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/delete-existing-repo.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/delete-existing-repo", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/delete-git-branch.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/delete-git-branch", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/find-a-file.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/find-a-file", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/forks.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/forks", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/gcm-ssh-passphrase.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/gcm-ssh-passphrase", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/git-branching-guidance.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-branching-guidance", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/git-config.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-config", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/git-dates.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-dates", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/git-index-lock.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-index-lock", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/git-log-history-simplification.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-log-history-simplification", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/git-names.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-names", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/git-tags.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-tags", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/gitquickstart.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/gitquickstart", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/gitworkflow.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/gitworkflow", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/history.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/history", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/ignore-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/ignore-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/import-from-TFVC.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/import-from-TFVC", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/import-git-repository.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/import-git-repository", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/lfs-kerberos.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/lfs-kerberos", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/lock-branches.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/lock-branches", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/manage-large-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/manage-large-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/manage-your-branches.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/manage-your-branches", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/mapping-my-tfvc-actions-to-git.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/mapping-my-tfvc-actions-to-git", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/merging-with-squash.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/merging-with-squash", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/merging.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/merging", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/move-git-repos-between-team-projects.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/move-git-repos-between-team-projects", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/os-compatibility.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/os-compatibility", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/perform-migration-from-svn-to-git.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/perform-migration-from-svn-to-git", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/pr-status-policy.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pr-status-policy", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/pull-request-notifications.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pull-request-notifications", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/pull-request-status.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pull-request-status", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pull-requests", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/pulling.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pulling", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/pushing.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pushing", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/rebase.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/rebase", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/remove-binaries.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/remove-binaries", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/repo-rename.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/repo-rename", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/repository-settings.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/repository-settings", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/require-branch-folders.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/require-branch-folders", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/restore-deleted-branch.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/restore-deleted-branch", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/review-history.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/review-history", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/review-pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/review-pull-requests", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/rpc-failures-http-postbuffer.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/rpc-failures-http-postbuffer", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/set-git-repository-permissions.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/set-git-repository-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/set-up-credential-managers.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/set-up-credential-managers", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/share-your-code-in-git-eclipse.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/share-your-code-in-git-eclipse", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/share-your-code-in-git-vs.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/share-your-code-in-git-vs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/share-your-code-in-git-xcode.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/share-your-code-in-git-xcode", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/team-projects.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/team-projects", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/undo.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/undo", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/use-ssh-keys-to-authenticate.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/use-ssh-keys-to-authenticate", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/git/view-pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/view-pull-requests", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/add-check-policies.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/add-check-policies", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/add-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/add-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/add-files-server.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/add-files-server", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/associate-file-type-file-comparison-tool.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/associate-file-type-file-comparison-tool", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/associate-file-type-merge-tool.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/associate-file-type-merge-tool", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/branch-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/branch-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/branch-folders-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/branch-folders-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/branch-strategically.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/branch-strategically", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/branches-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/branches-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/branching-strategies-with-tfvc.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/branching-strategies-with-tfvc", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/changeset-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/changeset-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/check-folder-controlled-by-gated-check-build-process.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/check-folder-controlled-by-gated-check-build-process", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/check-out-edit-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/check-out-edit-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/check-your-work-team-codebase.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/check-your-work-team-codebase", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/checkin-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/checkin-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/checkout-or-edit-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/checkout-or-edit-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/clean-up-files-when-users-leave.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/clean-up-files-when-users-leave", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/compare-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/compare-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/compare-folders.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/compare-folders", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/comparison-git-tfvc.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/comparison-git-tfvc", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/configure-check-notes.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/configure-check-notes", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/configure-check-out-settings.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/configure-check-out-settings", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/configure-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/configure-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/control-access-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/control-access-team-foundation-version-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/create-work-workspaces.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/create-work-workspaces", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/day-life-alm-developer-suspend-work-fix-bug-conduct-code-review.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/day-life-alm-developer-suspend-work-fix-bug-conduct-code-review", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/day-life-alm-developer-write-new-code-user-story.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/day-life-alm-developer-write-new-code-user-story", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/decide-between-using-local-server-workspace.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/decide-between-using-local-server-workspace", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/delete-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/delete-command-team-foundation-version-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/delete-restore-files-folders.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/delete-restore-files-folders", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/destroy-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/destroy-command-team-foundation-version-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/destroy-version-controlled-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/destroy-version-controlled-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/develop-code-manage-pending-changes.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/develop-code-manage-pending-changes", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/develop-your-app-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/develop-your-app-team-foundation-version-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/difference-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/difference-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/dir-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/dir-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/download-get-files-from-server.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/download-get-files-from-server", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/edit-check-policies.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/edit-check-policies", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/effective-feature-isolation-on-tfvc.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/effective-feature-isolation-on-tfvc", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/effective-tfvc-branching-strategies-for-devops.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/effective-tfvc-branching-strategies-for-devops", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/enable-disable-check-policies.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/enable-disable-check-policies", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/find-view-changesets.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/find-view-changesets", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/folder-comparison-filters.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/folder-comparison-filters", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/folderdiff-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/folderdiff-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/get-code-reviewed-vs.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/get-code-reviewed-vs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/get-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/get-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/get-history-item.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/get-history-item", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/git-permission-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/git-permission-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/git-view-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/git-view-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/help-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/help-command-team-foundation-version-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/history-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/history-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/label-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/label-command-team-foundation-version-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/labels-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/labels-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/localversions-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/localversions-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/lock-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/lock-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/lock-unlock-folders-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/lock-unlock-folders-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/merge-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/merge-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/merge-folders-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/merge-folders-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/merges-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/merges-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/msdn-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/msdn-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/optimize-your-workspace.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/optimize-your-workspace", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/permission-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/permission-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/properties-or-info-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/properties-or-info-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/proxy-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/proxy-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/reconcile-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/reconcile-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/reconcile-differences-between-two-folders.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/reconcile-differences-between-two-folders", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/remove-access-version-control-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/remove-access-version-control-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/remove-check-policies.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/remove-check-policies", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/rename-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/rename-command-team-foundation-version-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/rename-move-files-folders.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/rename-move-files-folders", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/resolve-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/resolve-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/resolve-team-foundation-version-control-conflicts.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/resolve-team-foundation-version-control-conflicts", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/roll-back-changesets.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/roll-back-changesets", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/rollback-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/rollback-command-team-foundation-version-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/set-enforce-quality-gates.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/set-enforce-quality-gates", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/set-tfvc-repository-permissions.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/set-tfvc-repository-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/set-up-team-foundation-version-control-your-dev-machine.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/set-up-team-foundation-version-control-your-dev-machine", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/share-your-code-in-tfvc-eclipse.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/share-your-code-in-tfvc-eclipse", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/share-your-code-in-tfvc-vs.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/share-your-code-in-tfvc-vs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/share-your-code-in-tfvc-xcode.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/share-your-code-in-tfvc-xcode", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/shelve-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/shelve-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/shelvesets-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/shelvesets-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/status-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/status-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/suspend-your-work-manage-your-shelvesets.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/suspend-your-work-manage-your-shelvesets", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/test-impact-for-partially-mapped-tfvc-repositories.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/test-impact-for-partially-mapped-tfvc-repositories", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/undelete-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/undelete-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/understand-lock-types.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/understand-lock-types", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/undo-changes-another-user-workspace.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/undo-changes-another-user-workspace", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/undo-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/undo-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/unlabel-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/unlabel-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/unshelve-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/unshelve-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/use-labels-take-snapshot-your-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/use-labels-take-snapshot-your-files", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/use-source-control-explorer-manage-files-under-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/use-source-control-explorer-manage-files-under-version-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/use-team-foundation-version-control-commands.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/use-team-foundation-version-control-commands", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/use-visual-studio-git.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/use-visual-studio-git", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/view-branch-hierarchy-team-project.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/view-branch-hierarchy-team-project", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/view-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/view-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/view-file-changes-using-annotate.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/view-file-changes-using-annotate", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/view-manage-past-versions.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/view-manage-past-versions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/view-where-when-changesets-have-been-merged.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/view-where-when-changesets-have-been-merged", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/what-is-tfvc.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/what-is-tfvc", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/work-version-control-locks.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/work-version-control-locks", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/workfold-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/workfold-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/workspace-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/workspace-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/repos/tfvc/workspaces-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/workspaces-command", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/authorize.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/authorize", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/consumers.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/consumers", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/create-subscription.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/create-subscription", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/events.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/events", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/overview.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/troubleshoot.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/troubleshoot", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/services/jenkins.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/jenkins", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/services/slack.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/slack", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/services/teams.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/teams", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/services/trello.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/trello", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/services/webhooks.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/webhooks", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/service-hooks/services/workplace-messaging-apps.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/workplace-messaging-apps", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/index.yml", + "redirect_url": "/previous-versions/azure/devops/test/index", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/reference-qa.yml", + "redirect_url": "/previous-versions/azure/devops/test/reference-qa", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/add-to-bugs-exploratory-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/add-to-bugs-exploratory-testing", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/associate-automated-test-with-test-case.md", + "redirect_url": "/previous-versions/azure/devops/test/associate-automated-test-with-test-case", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/collect-diagnostic-data.md", + "redirect_url": "/previous-versions/azure/devops/test/collect-diagnostic-data", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/connected-mode-exploratory-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/connected-mode-exploratory-testing", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/copy-clone-test-items.md", + "redirect_url": "/previous-versions/azure/devops/test/copy-clone-test-items", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/create-a-test-plan.md", + "redirect_url": "/previous-versions/azure/devops/test/create-a-test-plan", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/create-test-cases.md", + "redirect_url": "/previous-versions/azure/devops/test/create-test-cases", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/explore-workitems-exploratory-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/explore-workitems-exploratory-testing", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/how-long-to-keep-test-results.md", + "redirect_url": "/previous-versions/azure/devops/test/how-long-to-keep-test-results", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/insights-exploratory-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/insights-exploratory-testing", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/manual-test-permissions.md", + "redirect_url": "/previous-versions/azure/devops/test/manual-test-permissions", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/overview.md", + "redirect_url": "/previous-versions/azure/devops/test/overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/perform-exploratory-tests.md", + "redirect_url": "/previous-versions/azure/devops/test/perform-exploratory-tests", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/provide-stakeholder-feedback.md", + "redirect_url": "/previous-versions/azure/devops/test/provide-stakeholder-feedback", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/repeat-test-with-different-data.md", + "redirect_url": "/previous-versions/azure/devops/test/repeat-test-with-different-data", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/request-stakeholder-feedback.md", + "redirect_url": "/previous-versions/azure/devops/test/request-stakeholder-feedback", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/run-automated-tests-from-test-hub.md", + "redirect_url": "/previous-versions/azure/devops/test/run-automated-tests-from-test-hub", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/run-manual-tests.md", + "redirect_url": "/previous-versions/azure/devops/test/run-manual-tests", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/share-steps-between-test-cases.md", + "redirect_url": "/previous-versions/azure/devops/test/share-steps-between-test-cases", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/standalone-mode-exploratory-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/standalone-mode-exploratory-testing", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/test-case-managment-reference.md", + "redirect_url": "/previous-versions/azure/devops/test/test-case-managment-reference", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/test-different-configurations.md", + "redirect_url": "/previous-versions/azure/devops/test/test-different-configurations", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/test-objects-overview.md", + "redirect_url": "/previous-versions/azure/devops/test/test-objects-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/track-stakeholder-feedback.md", + "redirect_url": "/previous-versions/azure/devops/test/track-stakeholder-feedback", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/track-test-status.md", + "redirect_url": "/previous-versions/azure/devops/test/track-test-status", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/user-acceptance-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/user-acceptance-testing", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/test/voluntary-stakeholder-feedback.md", + "redirect_url": "/previous-versions/azure/devops/test/voluntary-stakeholder-feedback", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/about-azure-devops-services-tfs.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/about-azure-devops-services-tfs", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/add-run-manual-tests.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/add-run-manual-tests", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/code-with-git.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/code-with-git", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/devops-alm-overview.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/devops-alm-overview", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/lookup-platform-version.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/lookup-platform-version", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/manage-organization-collection.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/manage-organization-collection", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/plan-your-azure-devops-org-structure.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/plan-your-azure-devops-org-structure", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/project-admin-tutorial.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/project-admin-tutorial", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/provide-feedback.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/provide-feedback", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/roles.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/roles", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/services.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/services", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/source-control.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/source-control", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/tools.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/tools", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/troubleshoot-connection.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/troubleshoot-connection", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/what-is-azure-devops.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/what-is-azure-devops", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/user-guide/work-team-explorer.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/work-team-explorer", + "monikers": [ + "tfs-2018" + ] + }, + { + "source_path": "docs/index.yml", + "redirect_url": "/previous-versions/azure/devops/index", + "monikers": [ + "tfs-2018" + ] + } + ] +} + diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index ed84013e273..54d3659627d 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1,39 +1,6608 @@ { "redirections": [ + { + "source_path": "docs/artifacts/artifacts-key-concepts.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/artifacts-key-concepts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/get-started-maven.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/get-started-maven", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/get-started-npm.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/get-started-npm", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/get-started-nuget.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/get-started-nuget", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/package-badges.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/package-badges", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/start-using-azure-artifacts.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/start-using-azure-artifacts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/concepts/best-practices.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/best-practices", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/concepts/feeds.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/feeds", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/concepts/package-graph.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/package-graph", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/concepts/symbols.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/symbols", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/concepts/upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/upstream-sources", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/concepts/views.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/concepts/views", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/feeds/feed-permissions.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/feeds/feed-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/feeds/project-scoped-feeds.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/feeds/project-scoped-feeds", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/feeds/views.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/feeds/views", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/how-to/delete-and-recover-packages.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/how-to/delete-and-recover-packages", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/how-to/follow-package-notifications.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/how-to/follow-package-notifications", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/how-to/set-up-upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/how-to/set-up-upstream-sources", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/maven/google-maven.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/google-maven", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/maven/gradle-plugins.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/gradle-plugins", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/maven/install.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/install", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/maven/jitpack-upstream.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/jitpack-upstream", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/maven/pom-and-settings.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/pom-and-settings", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/maven/publish-with-gradle.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/publish-with-gradle", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/maven/upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/maven/upstream-sources", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/npm/npmrc.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/npm/npmrc", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/npm/publish.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/npm/publish", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/npm/restore-npm-packages.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/npm/restore-npm-packages", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/npm/scopes.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/npm/scopes", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/npm/upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/npm/upstream-sources", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/nuget/install-nuget-packages-with-visual-studio.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/install-nuget-packages-with-visual-studio", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/nuget/move-from-fileshares.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/move-from-fileshares", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/nuget/nuget-exe.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/nuget-exe", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/nuget/publish-to-nuget-org.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/publish-to-nuget-org", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/nuget/publish.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/publish", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/nuget/restore-nuget-packages-nuget-exe.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/restore-nuget-packages-nuget-exe", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/nuget/upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/nuget/upstream-sources", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/python/project-setup-python.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/python/project-setup-python", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/python/use-packages-from-pypi.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/python/use-packages-from-pypi", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/quickstarts/install-python-packages.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/quickstarts/install-python-packages", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/quickstarts/python-cli.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/quickstarts/python-cli", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/quickstarts/python-packages.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/quickstarts/python-packages", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/reference/limits.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/reference/limits", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/symbols/debug-with-symbols-visual-studio.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/symbols/debug-with-symbols-visual-studio", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/symbols/debug-with-symbols-windbg.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/symbols/debug-with-symbols-windbg", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/artifacts/tutorials/protect-oss-packages-with-upstream-sources.md", + "redirect_url": "/previous-versions/azure/devops/artifacts/tutorials/protect-oss-packages-with-upstream-sources", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/best-practices-agile-project-management.md", + "redirect_url": "/previous-versions/azure/devops/boards/best-practices-agile-project-management", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/configure-customize.md", + "redirect_url": "/previous-versions/azure/devops/boards/configure-customize", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/add-link.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/add-link", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/automate-work-item-state-transitions.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/automate-work-item-state-transitions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/backlogs-overview.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/backlogs-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/bulk-modify-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/bulk-modify-work-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/configure-your-backlog-view.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/configure-your-backlog-view", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/connect-work-items-to-git-dev-ops.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/connect-work-items-to-git-dev-ops", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/copy-clone-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/copy-clone-work-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/create-your-backlog.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/create-your-backlog", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/define-features-epics.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/define-features-epics", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/delete-test-artifacts.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/delete-test-artifacts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/filter-backlogs-boards-plans.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/filter-backlogs-boards-plans", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/manage-bugs.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/manage-bugs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/manage-issues-impediments.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/manage-issues-impediments", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/manage-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/manage-work-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/move-change-type.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/move-change-type", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/organize-backlog.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/organize-backlog", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/remove-delete-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/remove-delete-work-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/resolve-backlog-reorder-issues.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/resolve-backlog-reorder-issues", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/set-column-options.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/set-column-options", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/set-up-your-backlog.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/set-up-your-backlog", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/work-item-template.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/work-item-template", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/office/bulk-add-modify-work-items-excel.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/office/bulk-add-modify-work-items-excel", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/office/tfs-office-integration-issues.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/office/tfs-office-integration-issues", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/backlogs/office/track-work.md", + "redirect_url": "/previous-versions/azure/devops/boards/backlogs/office/track-work", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/boards/add-columns.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/add-columns", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/boards/add-run-update-tests.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/add-run-update-tests", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/boards/add-task-checklists.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/add-task-checklists", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/boards/customize-cards.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/customize-cards", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/boards/expedite-work.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/expedite-work", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/boards/kanban-epics-features-stories.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/kanban-epics-features-stories", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/boards/kanban-overview.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/kanban-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/boards/kanban-quickstart.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/kanban-quickstart", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/boards/wip-limits.md", + "redirect_url": "/previous-versions/azure/devops/boards/boards/wip-limits", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/extensions/migrate-integrate.md", + "redirect_url": "/previous-versions/azure/devops/boards/extensions/migrate-integrate", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/get-started/permissions-access-boards.md", + "redirect_url": "/previous-versions/azure/devops/boards/get-started/permissions-access-boards", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/get-started/plan-track-work.md", + "redirect_url": "/previous-versions/azure/devops/boards/get-started/plan-track-work", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/get-started/what-is-azure-boards.md", + "redirect_url": "/previous-versions/azure/devops/boards/get-started/what-is-azure-boards", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/github/configure-status-badges.md", + "redirect_url": "/previous-versions/azure/devops/boards/github/configure-status-badges", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/github/connect-on-premises-to-github.md", + "redirect_url": "/previous-versions/azure/devops/boards/github/connect-on-premises-to-github", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/github/index.md", + "redirect_url": "/previous-versions/azure/devops/boards/github/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/github/install-github-app.md", + "redirect_url": "/previous-versions/azure/devops/boards/github/install-github-app", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/github/link-to-from-github.md", + "redirect_url": "/previous-versions/azure/devops/boards/github/link-to-from-github", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/agile-culture.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/agile-culture", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/configure-hierarchical-teams.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/configure-hierarchical-teams", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/index.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/portfolio-management.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/portfolio-management", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/practices-that-scale.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/practices-that-scale", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/safe-concepts.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/safe-concepts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/safe-configure-boards.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/safe-configure-boards", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/safe-customize.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/safe-customize", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/safe-plan-track-boards.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/safe-plan-track-boards", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/safe-review-roadmaps-progress.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/safe-review-roadmaps-progress", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/scaled-agile-framework.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/scaled-agile-framework", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/plans/visibility-across-teams.md", + "redirect_url": "/previous-versions/azure/devops/boards/plans/visibility-across-teams", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/about-managed-queries.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/about-managed-queries", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/add-tags-to-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/add-tags-to-work-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/build-test-integration.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/build-test-integration", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/example-query-charts.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/example-query-charts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/history-and-auditing.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/history-and-auditing", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/import-work-items-from-csv.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/import-work-items-from-csv", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/link-type-reference.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/link-type-reference", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/linking-attachments.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/linking-attachments", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/organize-queries.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/organize-queries", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/planning-ranking-priorities.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/planning-ranking-priorities", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/query-by-area-iteration-path.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-by-area-iteration-path", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/query-by-date-or-current-iteration.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-by-date-or-current-iteration", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/query-by-workflow-changes.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-by-workflow-changes", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/query-field-value.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-field-value", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/query-index-quick-ref.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-index-quick-ref", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/query-numeric.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-numeric", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/query-operators-variables.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/query-operators-variables", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/search-box-queries.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/search-box-queries", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/set-query-permissions.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/set-query-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/titles-ids-descriptions.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/titles-ids-descriptions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/using-queries.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/using-queries", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/view-run-query.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/view-run-query", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/queries/wiql-syntax.md", + "redirect_url": "/previous-versions/azure/devops/boards/queries/wiql-syntax", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/add-tasks.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/add-tasks", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/adjust-work.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/adjust-work", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/assign-work-sprint.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/assign-work-sprint", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/best-practices-scrum.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/best-practices-scrum", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/customize-taskboard.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/customize-taskboard", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/define-sprints.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/define-sprints", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/end-sprint-activities.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/end-sprint-activities", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/forecast.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/forecast", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/scrum-key-concepts.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/scrum-key-concepts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/scrum-overview.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/scrum-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/set-capacity.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/set-capacity", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/share-plan.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/share-plan", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/sprints/task-board.md", + "redirect_url": "/previous-versions/azure/devops/boards/sprints/task-board", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/about-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/about-work-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/agile-glossary.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/agile-glossary", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/auto-complete-work-items-pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/auto-complete-work-items-pull-requests", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/email-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/email-work-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/follow-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/follow-work-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/manage-attachments.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/manage-attachments", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/move-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/move-work-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/quick-ref.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/quick-ref", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/set-work-item-experience-vs.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/set-work-item-experience-vs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/view-add-work-items.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/view-add-work-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/work-item-fields.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/work-item-fields", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/work-item-template-examples.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/work-item-template-examples", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/workflow-and-state-categories.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/workflow-and-state-categories", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/agile-process-workflow.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/agile-process-workflow", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/agile-process.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/agile-process", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/choose-process.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/choose-process", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/cmmi-process-workflow.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/cmmi-process-workflow", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/cmmi-process.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/cmmi-process", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/guidance-code-review-feedback-field-reference.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/guidance-code-review-feedback-field-reference", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/manage-process-templates.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/manage-process-templates", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/scrum-process-workflow.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/scrum-process-workflow", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/scrum-process.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/scrum-process", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/work-item-field.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/work-item-field", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/cmmi/guidance-background-to-cmmi.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-background-to-cmmi", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/boards/work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md", + "redirect_url": "/previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/cross-service/cross-service-overview.md", + "redirect_url": "/previous-versions/azure/devops/cross-service/cross-service-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/cross-service/github-integration.md", + "redirect_url": "/previous-versions/azure/devops/cross-service/github-integration", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/cross-service/manage-change.md", + "redirect_url": "/previous-versions/azure/devops/cross-service/manage-change", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/cross-service/manage-requirements.md", + "redirect_url": "/previous-versions/azure/devops/cross-service/manage-requirements", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/extension-report.md", + "redirect_url": "/previous-versions/azure/devops/extend/extension-report", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/overview.md", + "redirect_url": "/previous-versions/azure/devops/extend/overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/add-action.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-action", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/add-build-task.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-build-task", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/add-chart.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-chart", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/add-dashboard-widget.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-dashboard-widget", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/add-hub-group.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-hub-group", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/add-query-result-tabs.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-query-result-tabs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/add-service-hook.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-service-hook", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/add-workitem-extension.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/add-workitem-extension", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/auth-schemes.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/auth-schemes", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/auth.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/auth", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/call-rest-api.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/call-rest-api", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/configure-workitemform-extensions.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/configure-workitemform-extensions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/contributions-overview.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/contributions-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/custom-control.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/custom-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/data-storage.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/data-storage", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/host-navigation.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/host-navigation", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/integrate-build-task.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/integrate-build-task", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/manifest.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/manifest", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/samples-overview.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/samples-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/service-endpoints.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/service-endpoints", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/styles-from-widget-sdk.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/styles-from-widget-sdk", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/develop/using-host-dialog.md", + "redirect_url": "/previous-versions/azure/devops/extend/develop/using-host-dialog", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/get-started/node.md", + "redirect_url": "/previous-versions/azure/devops/extend/get-started/node", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/publish/command-line.md", + "redirect_url": "/previous-versions/azure/devops/extend/publish/command-line", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/publish/integration.md", + "redirect_url": "/previous-versions/azure/devops/extend/publish/integration", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/publish/overview.md", + "redirect_url": "/previous-versions/azure/devops/extend/publish/overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/publish/publish-azure.md", + "redirect_url": "/previous-versions/azure/devops/extend/publish/publish-azure", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/extend/reference/targets/overview.md", + "redirect_url": "/previous-versions/azure/devops/extend/reference/targets/overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/integrate/index.md", + "redirect_url": "/previous-versions/azure/devops/integrate/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/integrate/concepts/dotnet-client-libraries.md", + "redirect_url": "/previous-versions/azure/devops/integrate/concepts/dotnet-client-libraries", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/integrate/concepts/rest-api-versioning.md", + "redirect_url": "/previous-versions/azure/devops/integrate/concepts/rest-api-versioning", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/integrate/get-started/auth/tfs-basic-auth.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/auth/tfs-basic-auth", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/integrate/get-started/authentication/authentication-guidance.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/authentication/authentication-guidance", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/integrate/get-started/client-libraries/samples.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/client-libraries/samples", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/integrate/get-started/client-libraries/soapSamples.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/client-libraries/soapSamples", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/integrate/get-started/rest/samples.md", + "redirect_url": "/previous-versions/azure/devops/integrate/get-started/rest/samples", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/integrate/how-to/call-rest-api.md", + "redirect_url": "/previous-versions/azure/devops/integrate/how-to/call-rest-api", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/integrate/quickstarts/create-bug-quickstart.md", + "redirect_url": "/previous-versions/azure/devops/integrate/quickstarts/create-bug-quickstart", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/marketplace/grant-permissions.md", + "redirect_url": "/previous-versions/azure/devops/marketplace/grant-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/marketplace/high-risk-extensions.md", + "redirect_url": "/previous-versions/azure/devops/marketplace/high-risk-extensions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/marketplace/install-extension.md", + "redirect_url": "/previous-versions/azure/devops/marketplace/install-extension", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/marketplace/request-extensions.md", + "redirect_url": "/previous-versions/azure/devops/marketplace/request-extensions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/migrate/migration-get-started.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-get-started", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/migrate/migration-migrate.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-migrate", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/migrate/migration-overview.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/migrate/migration-post-migration.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-post-migration", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/migrate/migration-prepare-test-run.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-prepare-test-run", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/migrate/migration-prerequisites.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-prerequisites", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/migrate/migration-test-run.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-test-run", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/migrate/migration-troubleshooting.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-troubleshooting", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/migrate/migration-validate.md", + "redirect_url": "/previous-versions/azure/devops/migrate/migration-validate", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/accounts/admin-revoke-user-pats.md", + "redirect_url": "/previous-versions/azure/devops/organizations/accounts/admin-revoke-user-pats", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/accounts/create-organization.md", + "redirect_url": "/previous-versions/azure/devops/organizations/accounts/create-organization", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/accounts/delete-organization-users.md", + "redirect_url": "/previous-versions/azure/devops/organizations/accounts/delete-organization-users", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/accounts/use-personal-access-tokens-to-authenticate.md", + "redirect_url": "/previous-versions/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/billing/buy-access-tfs-test-hub.md", + "redirect_url": "/previous-versions/azure/devops/organizations/billing/buy-access-tfs-test-hub", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/billing/buy-basic-access-add-users.md", + "redirect_url": "/previous-versions/azure/devops/organizations/billing/buy-basic-access-add-users", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/billing/overview.md", + "redirect_url": "/previous-versions/azure/devops/organizations/billing/overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/about-notifications.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/about-notifications", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/at-mentions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/at-mentions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/change-email-address.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/change-email-address", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/concepts-email-recipients.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/concepts-email-recipients", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/exclude-self-from-email.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/exclude-self-from-email", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/integrate-third-party-services.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/integrate-third-party-services", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/manage-team-group-global-organization-notifications.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/manage-team-group-global-organization-notifications", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/manage-your-personal-notifications.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/manage-your-personal-notifications", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/navigating-the-ui.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/navigating-the-ui", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/oob-built-in-notifications.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/oob-built-in-notifications", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/oob-supported-event-types.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/oob-supported-event-types", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/troubleshoot-delayed-email.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/troubleshoot-delayed-email", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/troubleshoot-not-getting-email.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/troubleshoot-not-getting-email", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/troubleshoot-unexpected-email.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/troubleshoot-unexpected-email", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/unsubscribe-default-notification.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/unsubscribe-default-notification", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/use-subscription-logging.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/use-subscription-logging", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/notifications/view-organization-notification-statistics.md", + "redirect_url": "/previous-versions/azure/devops/organizations/notifications/view-organization-notification-statistics", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/projects/about-projects.md", + "redirect_url": "/previous-versions/azure/devops/organizations/projects/about-projects", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/projects/connect-to-projects.md", + "redirect_url": "/previous-versions/azure/devops/organizations/projects/connect-to-projects", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/projects/create-project.md", + "redirect_url": "/previous-versions/azure/devops/organizations/projects/create-project", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/projects/delete-project.md", + "redirect_url": "/previous-versions/azure/devops/organizations/projects/delete-project", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/projects/project-vision-status.md", + "redirect_url": "/previous-versions/azure/devops/organizations/projects/project-vision-status", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/projects/rename-project.md", + "redirect_url": "/previous-versions/azure/devops/organizations/projects/rename-project", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/about-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/about-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/about-security-identity.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/about-security-identity", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/about-security-roles.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/about-security-roles", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/access-levels.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/access-levels", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/add-ad-aad-built-in-security-groups.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/add-ad-aad-built-in-security-groups", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/add-remove-manage-user-group-security-group.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/add-remove-manage-user-group-security-group", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/add-users-team-project.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/add-users-team-project", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/allow-list-ip-url.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/allow-list-ip-url", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/change-access-levels.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/change-access-levels", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/change-organization-collection-level-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/change-organization-collection-level-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/change-project-level-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/change-project-level-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/default-git-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/default-git-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/default-tfvc-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/default-tfvc-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/export-users-audit-log.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/export-users-audit-log", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/get-started-stakeholder.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/get-started-stakeholder", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/look-up-project-administrators.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/look-up-project-administrators", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/look-up-project-collection-administrators.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/look-up-project-collection-administrators", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/namespace-reference.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/namespace-reference", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/permissions-access.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/permissions-access", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/permissions-lookup-guide.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/permissions-lookup-guide", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/request-changes-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/request-changes-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/restrict-access.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/restrict-access", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/security-overview.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/security-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/set-object-level-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/set-object-level-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/set-permissions-access-test.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/set-permissions-access-test", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/set-permissions-access-work-tracking.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/set-permissions-access-work-tracking", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/stakeholder-access.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/stakeholder-access", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/troubleshoot-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/troubleshoot-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/security/view-permissions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/security/view-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/about-areas-iterations.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/about-areas-iterations", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/about-settings.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/about-settings", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/about-teams-and-settings.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/about-teams-and-settings", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/add-team-administrator.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/add-team-administrator", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/add-teams.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/add-teams", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/manage-banners.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/manage-banners", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/manage-teams.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/manage-teams", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/naming-restrictions.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/naming-restrictions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/rename-remove-team.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/rename-remove-team", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/select-backlog-navigation-levels.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/select-backlog-navigation-levels", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/set-area-paths.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/set-area-paths", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/set-iteration-paths-sprints.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/set-iteration-paths-sprints", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/set-services.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/set-services", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/set-your-preferences.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/set-your-preferences", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/show-bugs-on-backlog.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/show-bugs-on-backlog", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/timezone-settings-usage.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/timezone-settings-usage", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/add-custom-field.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/add-custom-field", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/add-custom-wit.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/add-custom-wit", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/apply-rules-to-workflow-states.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/apply-rules-to-workflow-states", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/custom-controls-process.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/custom-controls-process", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/custom-rules.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/custom-rules", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/customize-process-backlogs-boards.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/customize-process-backlogs-boards", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/customize-process-field.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/customize-process-field", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/customize-process-form.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/customize-process-form", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/customize-process-work-item-type.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/customize-process-work-item-type", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/customize-process-workflow.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/customize-process-workflow", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/customize-process.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/customize-process", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/inheritance-process-model.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/inheritance-process-model", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/manage-process.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/manage-process", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/object-limits.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/object-limits", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/rule-reference.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/rule-reference", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/organizations/settings/work/rule-samples.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/rule-samples", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/create-first-pipeline.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/create-first-pipeline", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/customize-pipeline.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/customize-pipeline", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/overview-azure.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/overview-azure", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/agent-authentication-options.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/agent-authentication-options", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/agents.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/agents", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/certificate.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/certificate", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/docker.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/docker", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/hosted.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/hosted", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/linux-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/linux-agent", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/osx-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/osx-agent", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/personal-access-token-agent-registration.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/personal-access-token-agent-registration", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/pools-queues.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/pools-queues", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/proxy.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/proxy", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/v2-linux-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/v2-linux-agent", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/v2-osx-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/v2-osx-agent", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/v2-windows-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/v2-windows-agent", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/agents/windows-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/windows-agent", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/apps/aspnet/build-aspnet-4.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/aspnet/build-aspnet-4", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/apps/cd/deploy-docker-webapp.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/cd/deploy-docker-webapp", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/apps/mobile/app-signing.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/mobile/app-signing", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/architectures/devops-pipelines-azure-web-apps-architecture.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/architectures/devops-pipelines-azure-web-apps-architecture", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/architectures/devops-pipelines-baseline-architecture.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/architectures/devops-pipelines-baseline-architecture", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/architectures/devops-pipelines-devtest-iaas-architecture.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/architectures/devops-pipelines-devtest-iaas-architecture", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/architectures/devops-pipelines-iaas-vms-architecture.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/architectures/devops-pipelines-iaas-vms-architecture", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/artifacts/artifacts-overview.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/artifacts-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/artifacts/build-artifacts.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/build-artifacts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/artifacts/build-publish-artifacts-gradle.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/build-publish-artifacts-gradle", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/artifacts/npm.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/npm", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/artifacts/publish-maven-artifacts.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/publish-maven-artifacts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/artifacts/publish-public-registry.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/publish-public-registry", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/artifacts/pypi.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/pypi", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/artifacts/symbols.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/artifacts/symbols", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/build/ci-build-git.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/build/ci-build-git", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/build/triggers.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/build/triggers", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/build/variables.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/build/variables", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/customize-javascript.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/customize-javascript", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/customize-python.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/customize-python", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/dotnet-core.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/dotnet-core", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/ecosystems.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/ecosystems", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/java.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/java", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/javascript.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/javascript", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/nodejs-tutorial.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/nodejs-tutorial", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/python.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/python", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/ecosystems/xcode.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/ecosystems/xcode", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/get-started/clone-import-pipeline.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/get-started/clone-import-pipeline", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/get-started/pipelines-get-started.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/get-started/pipelines-get-started", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/get-started/what-is-azure-pipelines.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/get-started/what-is-azure-pipelines", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/get-started/yaml-pipeline-editor.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/get-started/yaml-pipeline-editor", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/integrations/configure-pipelines-work-tracking.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/integrations/configure-pipelines-work-tracking", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/library/add-resource-protection.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/add-resource-protection", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/library/azure-resource-manager-alternate-approaches.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/azure-resource-manager-alternate-approaches", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/library/connect-to-azure.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/connect-to-azure", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/library/index.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/library/link-variable-groups-to-key-vaults.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/link-variable-groups-to-key-vaults", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/library/secure-files.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/secure-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/library/service-endpoints.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/service-endpoints", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/library/variable-groups.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/library/variable-groups", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/licensing/concurrent-jobs.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/licensing/concurrent-jobs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/packages/maven-restore.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/packages/maven-restore", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/packages/nuget-restore.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/packages/nuget-restore", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/policies/permissions.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/policies/permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/policies/retention.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/policies/retention", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/policies/set-permissions.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/policies/set-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/about-resources.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/about-resources", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/access-tokens.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/access-tokens", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/conditions.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/conditions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/container-phases.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/container-phases", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/create-multistage-pipeline.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/create-multistage-pipeline", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/expressions.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/expressions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/phases.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/phases", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/repository-resource.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/repository-resource", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/resources.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/resources", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/run-number.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/run-number", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/runs.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/runs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/scheduled-triggers.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/scheduled-triggers", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/set-secret-variables.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/set-secret-variables", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/set-variables-scripts.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/set-variables-scripts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/stages.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/stages", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/tasks.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/tasks", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/template-parameters.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/template-parameters", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/templates.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/templates", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/process/variables.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/process/variables", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/artifacts.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/artifacts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/azure-rm-endpoint.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/azure-rm-endpoint", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/define-multistage-release-process.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/define-multistage-release-process", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/deploy-multiple-branches.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deploy-multiple-branches", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/deploy-pull-request-builds.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deploy-pull-request-builds", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/deploy-using-approvals.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deploy-using-approvals", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/deploy-webdeploy-iis-deploygroups.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deploy-webdeploy-iis-deploygroups", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/deployment-group-phases.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deployment-group-phases", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/env-templates.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/env-templates", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/history.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/history", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/index.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/key-vault-access.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/key-vault-access", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/key-vault-in-own-project.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/key-vault-in-own-project", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/options.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/options", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/parameters.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/parameters", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/pipeline-triggers-classic.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/pipeline-triggers-classic", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/releases.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/releases", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/task-groups.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/task-groups", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/triggers.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/triggers", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/variables.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/variables", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/approvals/approvals.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/approvals/approvals", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/approvals/gates.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/approvals/gates", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/approvals/index.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/approvals/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/approvals/servicenow.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/approvals/servicenow", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/deployment-groups/deploying-azure-vms-deployment-groups.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deployment-groups/deploying-azure-vms-deployment-groups", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/deployment-groups/howto-provision-deployment-group-agents.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deployment-groups/howto-provision-deployment-group-agents", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/release/deployment-groups/index.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/deployment-groups/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/reports/pipeline-widgets.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/reports/pipeline-widgets", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/reports/pipelinereport.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/reports/pipelinereport", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/repos/azure-repos-git.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/repos/azure-repos-git", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/repos/index.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/repos/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/repos/pipeline-options-for-git.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/repos/pipeline-options-for-git", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/repos/tfvc.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/repos/tfvc", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/scripts/cross-platform-scripting.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/scripts/cross-platform-scripting", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/scripts/git-commands.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/scripts/git-commands", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/scripts/logging-commands.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/scripts/logging-commands", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/scripts/powershell.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/scripts/powershell", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/targets/azure-sqldb.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/targets/azure-sqldb", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/targets/azure-stack.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/targets/azure-stack", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/targets/create-virtual-network.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/targets/create-virtual-network", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/tasks/file-matching-patterns.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/tasks/file-matching-patterns", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/test/continuous-test-selenium.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/continuous-test-selenium", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/test/parallel-testing-any-test-runner.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/parallel-testing-any-test-runner", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/test/parallel-testing-vstest.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/parallel-testing-vstest", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/test/requirements-traceability.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/requirements-traceability", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/test/review-code-coverage-results.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/review-code-coverage-results", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/test/review-continuous-test-results-after-build.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/review-continuous-test-results-after-build", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/test/test-analytics.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/test-analytics", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/test/test-glossary.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/test-glossary", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/test/test-impact-analysis.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/test-impact-analysis", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/test/ui-testing-considerations.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/test/ui-testing-considerations", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/troubleshooting/review-logs.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/troubleshooting/review-logs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/troubleshooting/troubleshoot-start.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/troubleshooting/troubleshoot-start", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/troubleshooting/troubleshoot-triggers.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/troubleshooting/troubleshoot-triggers", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/troubleshooting/troubleshooting.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/troubleshooting/troubleshooting", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/feedback/index.md", + "redirect_url": "/previous-versions/azure/devops/project/feedback/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/add-artifact-team.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/add-artifact-team", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/filter-basics.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/filter-basics", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/glossary.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/glossary", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/go-to-project-repo.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/go-to-project-repo", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/go-to-service-page.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/go-to-service-page", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/index.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/keyboard-shortcuts.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/keyboard-shortcuts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/mobile-work.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/mobile-work", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/preview-features.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/preview-features", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/set-favorites.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/set-favorites", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/navigation/work-across-projects.md", + "redirect_url": "/previous-versions/azure/devops/project/navigation/work-across-projects", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/search/functional-code-search.md", + "redirect_url": "/previous-versions/azure/devops/project/search/functional-code-search", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/search/functional-work-item-search.md", + "redirect_url": "/previous-versions/azure/devops/project/search/functional-work-item-search", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/search/get-started-search.md", + "redirect_url": "/previous-versions/azure/devops/project/search/get-started-search", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/search/install-configure-search.md", + "redirect_url": "/previous-versions/azure/devops/project/search/install-configure-search", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/search/manage-search.md", + "redirect_url": "/previous-versions/azure/devops/project/search/manage-search", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/about-readme-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/about-readme-wiki", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/add-edit-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/add-edit-wiki", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/filter-print-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/filter-print-wiki", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/manage-readme-wiki-permissions.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/manage-readme-wiki-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/markdown-guidance.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/markdown-guidance", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/migrate-extension-wiki-pages.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/migrate-extension-wiki-pages", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/provisioned-vs-published-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/provisioned-vs-published-wiki", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/publish-repo-to-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/publish-repo-to-wiki", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/restore-deleted-wiki.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/restore-deleted-wiki", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/wiki-create-repo.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/wiki-create-repo", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/wiki-file-structure.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/wiki-file-structure", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/wiki-readme-permissions.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/wiki-readme-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/wiki-update-offline.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/wiki-update-offline", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/project/wiki/wiki-view-history.md", + "redirect_url": "/previous-versions/azure/devops/project/wiki/wiki-view-history", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/add-modify-field.md", + "redirect_url": "/previous-versions/azure/devops/reference/add-modify-field", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/add-modify-wit.md", + "redirect_url": "/previous-versions/azure/devops/reference/add-modify-wit", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/add-portfolio-backlogs.md", + "redirect_url": "/previous-versions/azure/devops/reference/add-portfolio-backlogs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/add-wits-to-backlogs-and-boards.md", + "redirect_url": "/previous-versions/azure/devops/reference/add-wits-to-backlogs-and-boards", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/customize-wit-form.md", + "redirect_url": "/previous-versions/azure/devops/reference/customize-wit-form", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/customize-work.md", + "redirect_url": "/previous-versions/azure/devops/reference/customize-work", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/on-premises-xml-process-model.md", + "redirect_url": "/previous-versions/azure/devops/reference/on-premises-xml-process-model", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/quick-reference-index-boards-settings.md", + "redirect_url": "/previous-versions/azure/devops/reference/quick-reference-index-boards-settings", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/process-templates/customize-process.md", + "redirect_url": "/previous-versions/azure/devops/reference/process-templates/customize-process", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/process-templates/index.md", + "redirect_url": "/previous-versions/azure/devops/reference/process-templates/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/witadmin/manage-work-item-fields.md", + "redirect_url": "/previous-versions/azure/devops/reference/witadmin/manage-work-item-fields", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md", + "redirect_url": "/previous-versions/azure/devops/reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/witadmin/witadmin-import-export-manage-wits.md", + "redirect_url": "/previous-versions/azure/devops/reference/witadmin/witadmin-import-export-manage-wits", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/witadmin/witadmin-import-export-process-configuration.md", + "redirect_url": "/previous-versions/azure/devops/reference/witadmin/witadmin-import-export-process-configuration", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/xml/change-workflow-wit.md", + "redirect_url": "/previous-versions/azure/devops/reference/xml/change-workflow-wit", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/xml/process-configuration-xml-element.md", + "redirect_url": "/previous-versions/azure/devops/reference/xml/process-configuration-xml-element", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/xml/provide-help-text-hyperlinks-web-content-form.md", + "redirect_url": "/previous-versions/azure/devops/reference/xml/provide-help-text-hyperlinks-web-content-form", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/reference/xml/support-rollup-of-work-and-other-fields.md", + "redirect_url": "/previous-versions/azure/devops/reference/xml/support-rollup-of-work-and-other-fields", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/analytics/analytics-best-practices.md", + "redirect_url": "/previous-versions/azure/devops/report/analytics/analytics-best-practices", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/analytics/analytics-permissions-prerequisites.md", + "redirect_url": "/previous-versions/azure/devops/report/analytics/analytics-permissions-prerequisites", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/analytics/analytics-query-parts.md", + "redirect_url": "/previous-versions/azure/devops/report/analytics/analytics-query-parts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/analytics/analytics-query-tools.md", + "redirect_url": "/previous-versions/azure/devops/report/analytics/analytics-query-tools", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/analytics/entity-reference-boards.md", + "redirect_url": "/previous-versions/azure/devops/report/analytics/entity-reference-boards", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/analytics/entity-reference-general.md", + "redirect_url": "/previous-versions/azure/devops/report/analytics/entity-reference-general", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/add-charts-to-dashboard.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/add-charts-to-dashboard", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/add-markdown-to-dashboard.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/add-markdown-to-dashboard", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/add-widget-to-dashboard.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/add-widget-to-dashboard", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/analytics-extension.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/analytics-extension", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/analytics-widgets.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/analytics-widgets", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/burndown-guidance.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/burndown-guidance", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/charts-dashboard-permissions-access.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/charts-dashboard-permissions-access", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/charts.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/charts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/configure-burndown-burnup-widgets.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/configure-burndown-burnup-widgets", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/configure-chart-work-items-widget.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/configure-chart-work-items-widget", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/configure-sprint-burndown.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/configure-sprint-burndown", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/configure-test-results-trend.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/configure-test-results-trend", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/cumulative-flow-cycle-lead-time-guidance.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/cumulative-flow-cycle-lead-time-guidance", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/cumulative-flow.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/cumulative-flow", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/cycle-time-and-lead-time.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/cycle-time-and-lead-time", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/dashboard-focus.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/dashboard-focus", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/dashboard-permissions.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/dashboard-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/dashboards.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/dashboards", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/overview.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/quick-ref.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/quick-ref", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/team-velocity.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/team-velocity", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/dashboards/widget-catalog.md", + "redirect_url": "/previous-versions/azure/devops/report/dashboards/widget-catalog", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/account-scoped-queries.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/account-scoped-queries", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/aggregated-data-analytics.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/aggregated-data-analytics", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/analytics-metadata.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/analytics-metadata", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/analytics-recipes.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/analytics-recipes", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/data-model-analytics-service.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/data-model-analytics-service", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/example-analytics-widget.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/example-analytics-widget", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/odata-api-version.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/odata-api-version", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/odata-batch.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/odata-batch", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/odata-query-guidelines.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/odata-query-guidelines", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/odata-supported-features.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/odata-supported-features", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/querying-for-trend-data.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/querying-for-trend-data", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/quick-ref.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/quick-ref", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/view-odata-query-analytics-report.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/view-odata-query-analytics-report", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/wit-analytics.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/wit-analytics", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/extend-analytics/work-item-links.md", + "redirect_url": "/previous-versions/azure/devops/report/extend-analytics/work-item-links", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/access-analytics-excel.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/access-analytics-excel", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/access-analytics-power-bi.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/access-analytics-power-bi", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/active-bugs-sample-report.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/active-bugs-sample-report", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/add-last-refresh-time.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/add-last-refresh-time", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/analytics-historical-filtering.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/analytics-historical-filtering", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/analytics-security.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/analytics-security", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/analytics-views-create.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/analytics-views-create", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/analytics-views-manage.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/analytics-views-manage", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/client-authentication-options.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/client-authentication-options", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/create-quick-report-odataq.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/create-quick-report-odataq", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/create-quick-report.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/create-quick-report", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/create-team-filter.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/create-team-filter", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/create-timeinstate-report.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/create-timeinstate-report", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/data-available-in-analytics.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/data-available-in-analytics", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/data-connector-connect.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/data-connector-connect", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/data-connector-dataset.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/data-connector-dataset", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/data-connector-examples.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/data-connector-examples", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/data-connector-functions.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/data-connector-functions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/odataquery-connect.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/odataquery-connect", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/overview.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/performance-latency.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/performance-latency", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/publish-power-bi-desktop-to-power-bi.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/publish-power-bi-desktop-to-power-bi", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/reporting-roadmap.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/reporting-roadmap", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-boards-bugtrend.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-boards-bugtrend", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-boards-cfd.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-boards-cfd", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-boards-directlinks.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-boards-directlinks", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-boards-featureprogress.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-boards-featureprogress", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-boards-leadcycletime.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-boards-leadcycletime", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-boards-openbugs.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-boards-openbugs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-boards-releaseburndown.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-boards-releaseburndown", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-boards-rollup.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-boards-rollup", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-boards-sprintburndown.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-boards-sprintburndown", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-boards-teamslicer.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-boards-teamslicer", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/sample-odata-overview.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/sample-odata-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/transform-analytics-data-report-generation.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/transform-analytics-data-report-generation", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/troubleshooting-views.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/troubleshooting-views", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/what-are-analytics-views.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/what-are-analytics-views", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/powerbi/what-is-analytics.md", + "redirect_url": "/previous-versions/azure/devops/report/powerbi/what-is-analytics", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/report/sql-reports/migration-guide.md", + "redirect_url": "/previous-versions/azure/devops/report/sql-reports/migration-guide", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/get-started/index.md", + "redirect_url": "/previous-versions/azure/devops/repos/get-started/index", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/get-started/what-is-repos.md", + "redirect_url": "/previous-versions/azure/devops/repos/get-started/what-is-repos", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/about-pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/about-pull-requests", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/auth-overview.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/auth-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/branch-permissions.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/branch-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/branch-policies-overview.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/branch-policies-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/branch-policies.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/branch-policies", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/case-sensitivity.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/case-sensitivity", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/change-default-branch.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/change-default-branch", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/cherry-pick.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/cherry-pick", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/clone.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/clone", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/command-prompt.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/command-prompt", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/commit-details.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/commit-details", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/commit-history.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/commit-history", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/commits.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/commits", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/complete-pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/complete-pull-requests", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/create-a-readme.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-a-readme", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/create-branch.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-branch", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/create-new-repo.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-new-repo", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/create-pr-status-server-with-azure-functions.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-pr-status-server-with-azure-functions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/create-pr-status-server.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-pr-status-server", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/create-repo-intellij.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/create-repo-intellij", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/creatingrepo.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/creatingrepo", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/delete-branch.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/delete-branch", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/delete-existing-repo.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/delete-existing-repo", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/delete-git-branch.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/delete-git-branch", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/find-a-file.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/find-a-file", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/forks.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/forks", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/gcm-ssh-passphrase.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/gcm-ssh-passphrase", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/git-branching-guidance.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-branching-guidance", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/git-config.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-config", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/git-dates.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-dates", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/git-index-lock.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-index-lock", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/git-log-history-simplification.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-log-history-simplification", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/git-names.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-names", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/git-tags.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/git-tags", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/gitquickstart.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/gitquickstart", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/gitworkflow.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/gitworkflow", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/history.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/history", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/ignore-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/ignore-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/import-from-TFVC.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/import-from-TFVC", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/import-git-repository.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/import-git-repository", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/lfs-kerberos.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/lfs-kerberos", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/lock-branches.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/lock-branches", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/manage-large-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/manage-large-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/manage-your-branches.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/manage-your-branches", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/mapping-my-tfvc-actions-to-git.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/mapping-my-tfvc-actions-to-git", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/merging-with-squash.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/merging-with-squash", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/merging.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/merging", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/move-git-repos-between-team-projects.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/move-git-repos-between-team-projects", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/os-compatibility.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/os-compatibility", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/perform-migration-from-svn-to-git.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/perform-migration-from-svn-to-git", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/pr-status-policy.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pr-status-policy", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/pull-request-notifications.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pull-request-notifications", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/pull-request-status.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pull-request-status", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/pull-request-targets.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pull-request-targets", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/pull-request-templates.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pull-request-templates", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pull-requests", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/pulling.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pulling", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/pushing.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/pushing", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/rebase.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/rebase", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/remove-binaries.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/remove-binaries", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/repo-rename.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/repo-rename", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/repository-settings.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/repository-settings", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/require-branch-folders.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/require-branch-folders", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/restore-deleted-branch.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/restore-deleted-branch", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/review-history.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/review-history", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/review-pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/review-pull-requests", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/rpc-failures-http-postbuffer.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/rpc-failures-http-postbuffer", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/set-git-repository-permissions.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/set-git-repository-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/set-up-credential-managers.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/set-up-credential-managers", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/share-your-code-in-git-eclipse.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/share-your-code-in-git-eclipse", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/share-your-code-in-git-vs.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/share-your-code-in-git-vs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/share-your-code-in-git-xcode.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/share-your-code-in-git-xcode", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/team-projects.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/team-projects", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/undo.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/undo", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/use-ssh-keys-to-authenticate.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/use-ssh-keys-to-authenticate", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/git/view-pull-requests.md", + "redirect_url": "/previous-versions/azure/devops/repos/git/view-pull-requests", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/add-check-policies.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/add-check-policies", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/add-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/add-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/add-files-server.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/add-files-server", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/associate-file-type-file-comparison-tool.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/associate-file-type-file-comparison-tool", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/associate-file-type-merge-tool.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/associate-file-type-merge-tool", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/branch-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/branch-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/branch-folders-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/branch-folders-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/branch-strategically.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/branch-strategically", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/branches-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/branches-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/branching-strategies-with-tfvc.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/branching-strategies-with-tfvc", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/changeset-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/changeset-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/check-folder-controlled-by-gated-check-build-process.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/check-folder-controlled-by-gated-check-build-process", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/check-out-edit-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/check-out-edit-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/check-your-work-team-codebase.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/check-your-work-team-codebase", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/checkin-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/checkin-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/checkout-or-edit-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/checkout-or-edit-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/clean-up-files-when-users-leave.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/clean-up-files-when-users-leave", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/compare-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/compare-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/compare-folders.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/compare-folders", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/comparison-git-tfvc.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/comparison-git-tfvc", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/configure-check-notes.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/configure-check-notes", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/configure-check-out-settings.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/configure-check-out-settings", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/configure-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/configure-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/control-access-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/control-access-team-foundation-version-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/create-work-workspaces.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/create-work-workspaces", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/day-life-alm-developer-suspend-work-fix-bug-conduct-code-review.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/day-life-alm-developer-suspend-work-fix-bug-conduct-code-review", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/day-life-alm-developer-write-new-code-user-story.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/day-life-alm-developer-write-new-code-user-story", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/decide-between-using-local-server-workspace.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/decide-between-using-local-server-workspace", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/delete-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/delete-command-team-foundation-version-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/delete-restore-files-folders.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/delete-restore-files-folders", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/destroy-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/destroy-command-team-foundation-version-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/destroy-version-controlled-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/destroy-version-controlled-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/develop-code-manage-pending-changes.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/develop-code-manage-pending-changes", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/develop-your-app-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/develop-your-app-team-foundation-version-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/difference-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/difference-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/dir-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/dir-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/download-get-files-from-server.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/download-get-files-from-server", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/edit-check-policies.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/edit-check-policies", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/effective-feature-isolation-on-tfvc.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/effective-feature-isolation-on-tfvc", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/effective-tfvc-branching-strategies-for-devops.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/effective-tfvc-branching-strategies-for-devops", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/enable-disable-check-policies.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/enable-disable-check-policies", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/find-view-changesets.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/find-view-changesets", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/folder-comparison-filters.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/folder-comparison-filters", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/folderdiff-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/folderdiff-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/get-code-reviewed-vs.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/get-code-reviewed-vs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/get-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/get-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/get-history-item.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/get-history-item", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/git-permission-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/git-permission-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/git-view-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/git-view-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/help-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/help-command-team-foundation-version-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/history-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/history-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/label-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/label-command-team-foundation-version-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/labels-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/labels-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/localversions-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/localversions-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/lock-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/lock-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/lock-unlock-folders-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/lock-unlock-folders-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/merge-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/merge-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/merge-folders-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/merge-folders-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/merges-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/merges-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/msdn-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/msdn-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/optimize-your-workspace.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/optimize-your-workspace", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/permission-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/permission-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/properties-or-info-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/properties-or-info-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/proxy-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/proxy-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/reconcile-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/reconcile-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/reconcile-differences-between-two-folders.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/reconcile-differences-between-two-folders", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/remove-access-version-control-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/remove-access-version-control-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/remove-check-policies.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/remove-check-policies", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/rename-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/rename-command-team-foundation-version-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/rename-move-files-folders.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/rename-move-files-folders", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/resolve-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/resolve-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/resolve-team-foundation-version-control-conflicts.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/resolve-team-foundation-version-control-conflicts", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/roll-back-changesets.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/roll-back-changesets", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/rollback-command-team-foundation-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/rollback-command-team-foundation-version-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/set-enforce-quality-gates.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/set-enforce-quality-gates", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/set-tfvc-repository-permissions.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/set-tfvc-repository-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/set-up-team-foundation-version-control-your-dev-machine.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/set-up-team-foundation-version-control-your-dev-machine", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/share-your-code-in-tfvc-eclipse.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/share-your-code-in-tfvc-eclipse", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/share-your-code-in-tfvc-vs.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/share-your-code-in-tfvc-vs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/share-your-code-in-tfvc-xcode.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/share-your-code-in-tfvc-xcode", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/shelve-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/shelve-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/shelvesets-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/shelvesets-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/status-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/status-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/suspend-your-work-manage-your-shelvesets.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/suspend-your-work-manage-your-shelvesets", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/test-impact-for-partially-mapped-tfvc-repositories.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/test-impact-for-partially-mapped-tfvc-repositories", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/undelete-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/undelete-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/understand-lock-types.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/understand-lock-types", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/undo-changes-another-user-workspace.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/undo-changes-another-user-workspace", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/undo-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/undo-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/unlabel-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/unlabel-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/unshelve-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/unshelve-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/use-labels-take-snapshot-your-files.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/use-labels-take-snapshot-your-files", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/use-source-control-explorer-manage-files-under-version-control.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/use-source-control-explorer-manage-files-under-version-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/use-team-foundation-version-control-commands.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/use-team-foundation-version-control-commands", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/use-visual-studio-git.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/use-visual-studio-git", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/view-branch-hierarchy-team-project.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/view-branch-hierarchy-team-project", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/view-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/view-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/view-file-changes-using-annotate.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/view-file-changes-using-annotate", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/view-manage-past-versions.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/view-manage-past-versions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/view-where-when-changesets-have-been-merged.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/view-where-when-changesets-have-been-merged", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/what-is-tfvc.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/what-is-tfvc", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/work-version-control-locks.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/work-version-control-locks", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/workfold-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/workfold-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/workspace-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/workspace-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/repos/tfvc/workspaces-command.md", + "redirect_url": "/previous-versions/azure/devops/repos/tfvc/workspaces-command", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/authorize.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/authorize", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/consumers.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/consumers", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/create-subscription.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/create-subscription", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/events.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/events", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/overview.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/troubleshoot.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/troubleshoot", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/services/datadog.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/datadog", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/services/grafana.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/grafana", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/services/jenkins.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/jenkins", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/services/slack.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/slack", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/services/teams.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/teams", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/services/trello.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/trello", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/services/webhooks.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/webhooks", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/service-hooks/services/workplace-messaging-apps.md", + "redirect_url": "/previous-versions/azure/devops/service-hooks/services/workplace-messaging-apps", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/add-to-bugs-exploratory-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/add-to-bugs-exploratory-testing", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/associate-automated-test-with-test-case.md", + "redirect_url": "/previous-versions/azure/devops/test/associate-automated-test-with-test-case", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/collect-diagnostic-data.md", + "redirect_url": "/previous-versions/azure/devops/test/collect-diagnostic-data", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/connected-mode-exploratory-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/connected-mode-exploratory-testing", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/copy-clone-test-items.md", + "redirect_url": "/previous-versions/azure/devops/test/copy-clone-test-items", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/create-a-test-plan.md", + "redirect_url": "/previous-versions/azure/devops/test/create-a-test-plan", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/create-test-cases.md", + "redirect_url": "/previous-versions/azure/devops/test/create-test-cases", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/explore-workitems-exploratory-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/explore-workitems-exploratory-testing", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/how-long-to-keep-test-results.md", + "redirect_url": "/previous-versions/azure/devops/test/how-long-to-keep-test-results", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/insights-exploratory-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/insights-exploratory-testing", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/manual-test-permissions.md", + "redirect_url": "/previous-versions/azure/devops/test/manual-test-permissions", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/overview.md", + "redirect_url": "/previous-versions/azure/devops/test/overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/perform-exploratory-tests.md", + "redirect_url": "/previous-versions/azure/devops/test/perform-exploratory-tests", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/provide-stakeholder-feedback.md", + "redirect_url": "/previous-versions/azure/devops/test/provide-stakeholder-feedback", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/repeat-test-with-different-data.md", + "redirect_url": "/previous-versions/azure/devops/test/repeat-test-with-different-data", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/request-stakeholder-feedback.md", + "redirect_url": "/previous-versions/azure/devops/test/request-stakeholder-feedback", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/run-automated-tests-from-test-hub.md", + "redirect_url": "/previous-versions/azure/devops/test/run-automated-tests-from-test-hub", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/run-manual-tests.md", + "redirect_url": "/previous-versions/azure/devops/test/run-manual-tests", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/share-steps-between-test-cases.md", + "redirect_url": "/previous-versions/azure/devops/test/share-steps-between-test-cases", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/standalone-mode-exploratory-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/standalone-mode-exploratory-testing", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/test-case-managment-reference.md", + "redirect_url": "/previous-versions/azure/devops/test/test-case-managment-reference", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/test-different-configurations.md", + "redirect_url": "/previous-versions/azure/devops/test/test-different-configurations", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/test-objects-overview.md", + "redirect_url": "/previous-versions/azure/devops/test/test-objects-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/track-stakeholder-feedback.md", + "redirect_url": "/previous-versions/azure/devops/test/track-stakeholder-feedback", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/track-test-status.md", + "redirect_url": "/previous-versions/azure/devops/test/track-test-status", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/user-acceptance-testing.md", + "redirect_url": "/previous-versions/azure/devops/test/user-acceptance-testing", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/test/voluntary-stakeholder-feedback.md", + "redirect_url": "/previous-versions/azure/devops/test/voluntary-stakeholder-feedback", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/about-azure-devops-services-tfs.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/about-azure-devops-services-tfs", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/add-run-manual-tests.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/add-run-manual-tests", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/capture-browser-trace.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/capture-browser-trace", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/code-with-git.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/code-with-git", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/devops-alm-overview.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/devops-alm-overview", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/lookup-platform-version.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/lookup-platform-version", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/manage-organization-collection.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/manage-organization-collection", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/plan-your-azure-devops-org-structure.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/plan-your-azure-devops-org-structure", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/project-admin-tutorial.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/project-admin-tutorial", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/provide-feedback.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/provide-feedback", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/roles.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/roles", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/services.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/services", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/source-control.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/source-control", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/tools.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/tools", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/troubleshoot-connection.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/troubleshoot-connection", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/what-is-azure-devops.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/what-is-azure-devops", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/user-guide/work-team-explorer.md", + "redirect_url": "/previous-versions/azure/devops/user-guide/work-team-explorer", + "redirect_document_id": false, + "monikers": [ + "azure-devops-2019" + ] + }, + { + "source_path": "docs/pipelines/apps/cd/deploy-linuxvm-deploygroups.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/cd/deploy-linuxvm-deploygroups" + }, + { + "source_path": "docs/pipelines/apps/cd/howto-webdeploy-iis-deploygroups.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/cd/howto-webdeploy-iis-deploygroups" + }, { "source_path": "docs/migrate/migration.md", - "redirect_url": "/azure/devops/migrate/migration-overview", - "redirect_document_id": false + "redirect_url": "/azure/devops/migrate/migration-overview" }, { "source_path": "docs/devsecops/index.md", - "redirect_url": "/devops/devsecops/enable-devsecops-azure-github", - "redirect_document_id": false + "redirect_url": "/devops/devsecops/enable-devsecops-azure-github" }, { "source_path": "docs/user-guide/faqs.md", - "redirect_url": "/azure/devops/user-guide/user-guide-faqs", - "redirect_document_id": false + "redirect_url": "/azure/devops/user-guide/user-guide-faqs" }, { "source_path": "docs/marketplace/how-to/uninstall-disable-extensions-tfs.md", - "redirect_url": "/azure/devops/marketplace/uninstall-disable-extensions", - "redirect_document_id": false + "redirect_url": "/azure/devops/marketplace/uninstall-disable-extensions" }, { "source_path": "docs/organizations/security/set-project-collection-level-permissions.md", - "redirect_url": "/azure/devops/organizations/security/change-project-level-permissions", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/security/change-project-level-permissions" }, { "source_path": "docs/organizations/security/lookup-organization-owner-admin.md", - "redirect_url": "/azure/devops/organizations/security/request-changes-permissions", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/security/request-changes-permissions" }, { "source_path": "docs/organizations/security/change-individual-permissions.md", - "redirect_url": "/azure/devops/organizations/security/request-changes-permissions", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/security/request-changes-permissions" }, { "source_path": "docs/report/powerbi/analytics-fields-reference.md", @@ -42,43 +6611,35 @@ }, { "source_path": "docs/organizations/projects/faq-create-project.yml", - "redirect_url": "/azure/devops/organizations/projects/create-project", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/projects/create-project" }, { "source_path": "docs/organizations/projects/faq-rename-project.yml", - "redirect_url": "/azure/devops/organizations/projects/rename-project", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/projects/rename-project" }, { "source_path": "docs/marketplace/get-tfs-extensions.md", - "redirect_url": "/azure/devops/marketplace/install-extension", - "redirect_document_id": false + "redirect_url": "/azure/devops/marketplace/install-extension" }, { "source_path": "docs/marketplace/trust.md", - "redirect_url": "/azure/devops/marketplace/overview", - "redirect_document_id": false + "redirect_url": "/azure/devops/marketplace/overview" }, { "source_path": "docs/marketplace/how-to/grant-permissions.md", - "redirect_url": "/azure/devops/marketplace/grant-permissions", - "redirect_document_id": false + "redirect_url": "/azure/devops/marketplace/grant-permissions" }, { "source_path": "docs/extend/develop/install.md", - "redirect_url": "/azure/devops/extend/get-started/node?view=azure-devops#install-your-extension", - "redirect_document_id": false + "redirect_url": "/azure/devops/extend/get-started/node?view=azure-devops#install-your-extension" }, { "source_path": "docs/marketplace/overview.md", - "redirect_url": "/azure/devops/extend/overview", - "redirect_document_id": false + "redirect_url": "/azure/devops/extend/overview" }, { "source_path": "docs/marketplace/faq-extensions.yml", - "redirect_url": "/azure/devops/marketplace/install-extension#frequently-asked-questions-faqs", - "redirect_document_id": false + "redirect_url": "/azure/devops/marketplace/install-extension#frequently-asked-questions-faqs" }, { "source_path": "docs/organizations/public/about-public-projects.md", @@ -87,133 +6648,107 @@ }, { "source_path": "docs/organizations/public/browse-code-public.md", - "redirect_url": "/azure/devops/repos/git/find-a-file", - "redirect_document_id": false + "redirect_url": "/azure/devops/repos/git/find-a-file" }, { "source_path": "docs/organizations/public/clone-git-repo-public.md", - "redirect_url": "/azure/devops/repos/git/clone", - "redirect_document_id": false + "redirect_url": "/azure/devops/repos/git/clone" }, { "source_path": "docs/organizations/public/code-search-public.md", - "redirect_url": "/azure/devops/project/search/functional-code-search", - "redirect_document_id": false + "redirect_url": "/azure/devops/project/search/functional-code-search" }, { "source_path": "docs/organizations/public/create-public-project.md", - "redirect_url": "/azure/devops/organizations/projects/create-project", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/projects/create-project" }, { "source_path": "docs/organizations/public/default-roles-access-public.md", - "redirect_url": "/azure/devops/organizations/security/permissions-access", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/security/permissions-access" }, { "source_path": "docs/organizations/public/feature-differences.md", - "redirect_url": "/azure/devops/organizations/projects/make-project-public#access-levels-and-unavailable-features-for-public-projects", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/projects/make-project-public#access-levels-and-unavailable-features-for-public-projects" }, { "source_path": "docs/organizations/public/glossary-public.md", - "redirect_url": "/azure/devops/organizations/projects/about-projects", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/projects/about-projects" }, { "source_path": "docs/organizations/public/invite-users-public.md", - "redirect_url": "/azure/devops/organizations/projects/make-project-public#access-levels-and-unavailable-features-for-public-projects", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/projects/make-project-public#access-levels-and-unavailable-features-for-public-projects" }, { "source_path": "docs/organizations/public/migration-checklist.md", - "redirect_url": "/azure/devops/organizations/projects/make-project-public#migration-checklist", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/projects/make-project-public#migration-checklist" }, { "source_path": "docs/organizations/public/service-limits-public.md", - "redirect_url": "/azure/devops/user-guide/service-limits", - "redirect_document_id": false + "redirect_url": "/azure/devops/user-guide/service-limits" }, { "source_path": "docs/organizations/public/view-build-release-public.md", - "redirect_url": "/azure/devops/pipelines/release/releases", - "redirect_document_id": false + "redirect_url": "/azure/devops/pipelines/release/releases" }, { "source_path": "docs/organizations/public/view-filter-work-items-public.md", - "redirect_url": "/azure/devops/boards/work-items/quick-ref", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/work-items/quick-ref" }, { "source_path": "docs/organizations/public/view-project-dashboard-public.md", - "redirect_url": "/azure/devops/report/dashboards/dashboards", - "redirect_document_id": false + "redirect_url": "/azure/devops/report/dashboards/dashboards" }, { "source_path": "docs/organizations/public/view-wiki-public.md", - "redirect_url": "/azure/devops/project/wiki/wiki-create-repo", - "redirect_document_id": false + "redirect_url": "/azure/devops/project/wiki/wiki-create-repo" }, { "source_path": "docs/organizations/public/work-item-search-public.md", - "redirect_url": "/azure/devops/project/search/functional-work-item-search", - "redirect_document_id": false + "redirect_url": "/azure/devops/project/search/functional-work-item-search" }, { "source_path": "docs/marketplace/uninstall-disable-extensions.md", - "redirect_url": "/azure/devops/marketplace/install-extension#uninstall-disable-extension", - "redirect_document_id": false + "redirect_url": "/azure/devops/marketplace/install-extension#uninstall-disable-extension" }, { "source_path": "docs/organizations/public/make-project-public.md", - "redirect_url": "/azure/devops/organizations/projects/make-project-public", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/projects/make-project-public" }, { "source_path": "docs/user-guide/alm-devops-features.md", - "redirect_url": "https://azure.microsoft.com/products/devops/#overview", - "redirect_document_id": false + "redirect_url": "https://azure.microsoft.com/products/devops/#overview" }, { "source_path": "docs/organizations/billing/csp/buy-vs-app-center.md", - "redirect_url": "https://visualstudio.microsoft.com/app-center/", - "redirect_document_id": false + "redirect_url": "https://visualstudio.microsoft.com/app-center/" }, { "source_path": "docs/pipelines/apps/aspnet/build-aspnet-dacpac.md", - "redirect_url": "/previous-versions/azure/devops/pipelines/apps/aspnet/build-aspnet-dacpac", - "redirect_document_id": false + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/aspnet/build-aspnet-dacpac" }, { "source_path": "docs/pipelines/apps/aspnet/build-aspnet-cloudservice.md", - "redirect_url": "/previous-versions/azure/devops/pipelines/apps/aspnet/build-aspnet-cloudservice", - "redirect_document_id": false + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/aspnet/build-aspnet-cloudservice" }, { "source_path": "docs/pipelines/apps/cd/azure/aspnet-core-to-acr.md", - "redirect_url": "/previous-versions/azure/devops/pipelines/apps/aspnet/build-aspnet-cloudservice", - "redirect_document_id": false + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/aspnet/build-aspnet-cloudservice" }, { "source_path": "docs/pipelines/apps/cd/deploy-cloudservice-cloudservice.md", - "redirect_url": "/previous-versions/azure/devops/pipelines/apps/cd/deploy-cloudservice-cloudservice", - "redirect_document_id": false + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/cd/deploy-cloudservice-cloudservice" }, { "source_path": "docs/boards/extensions/feature-timeline.md", - "redirect_url": "/previous-versions/azure/devops/all/extensions/feature-timeline", - "redirect_document_id": false + "redirect_url": "/previous-versions/azure/devops/all/extensions/feature-timeline" }, { "source_path": "docs/boards/extensions/epic-roadmap.md", - "redirect_url": "/previous-versions/azure/devops/all/extensions/epic-roadmap", - "redirect_document_id": false + "redirect_url": "/previous-versions/azure/devops/all/extensions/epic-roadmap" }, { "source_path": "docs/organizations/notifications/concepts-events-and-notifications.md", - "redirect_url": "/azure/devops/organizations/notifications/about-notifications", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/notifications/about-notifications" }, { "source_path": "docs/boards/get-started/why-use-azure-boards.md", @@ -232,24 +6767,20 @@ }, { "source_path": "docs/boards/get-started/customize-boards.md", - "redirect_url": "/azure/devops/boards/configure-customize", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/configure-customize" }, { "source_path": "docs/boards/work-items/guidance/basic-field-reference.md", - "redirect_url": "/azure/devops/boards/work-items/guidance/work-item-field", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/work-items/guidance/work-item-field" }, { "source_path": "docs/boards/work-items/get-started/keyboard-shortcuts.md", - "redirect_url": "/azure/devops/project/navigation/keyboard-shortcuts", - "redirect_document_id": false + "redirect_url": "/azure/devops/project/navigation/keyboard-shortcuts" }, { "source_path": "docs/boards/work-items/changes-to-process-templates.md", - "redirect_url": "/azure/devops/server/release-notes/azuredevops2020u1?view=azure-devops#removing-assigned-to-rule-on-bug-work-item-type", - "redirect_document_id": false - }, + "redirect_url": "/azure/devops/server/release-notes/azuredevops2020u1?view=azure-devops#removing-assigned-to-rule-on-bug-work-item-type" + }, { "source_path": "docs/boards/report/dashboards/velocity-guidance.md", "redirect_url": "/azure/devops/report/dashboards/team-velocity", @@ -257,74 +6788,383 @@ }, { "source_path": "docs/boards/backlogs/office/resolve-excel-invalid-links-tree-list.md", - "redirect_url": "/azure/devops/boards/backlogs/office/faqs", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/backlogs/office/faqs" }, { "source_path": "docs/boards/plans/edit-delivery-plans-permissions.md", - "redirect_url": "/azure/devops/organizations/security/set-permissions-access-work-tracking", - "redirect_document_id": false + "redirect_url": "/azure/devops/organizations/security/set-permissions-access-work-tracking" }, { "source_path": "docs/boards/boards/split-columns.md", - "redirect_url": "/azure/devops/boards/boards/add-columns", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/boards/add-columns" }, - { + { "source_path": "docs/boards/boards/reorder-cards.md", - "redirect_url": "/azure/devops/boards/boards/customize-cards#reorder-cards", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/boards/customize-cards#reorder-cards" }, { "source_path": "docs/boards/boards/kanban-board-controls.md", - "redirect_url": "/azure/devops/boards/boards/kanban-overview#use-kanban-board-controls", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/boards/kanban-overview#use-kanban-board-controls" }, { "source_path": "docs/boards/boards/kanban-key-concepts.md", - "redirect_url": "/azure/devops/boards/boards/kanban-overview#kanban-concepts-and-terms", - "redirect_document_id": false - }, - { - "source_path": "docs/boards/boards/kanban-enable-live-updates.md", - "redirect_url": "/azure/devops/boards/boards/kanban-overview#enable-live-updates", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/boards/kanban-overview#kanban-concepts-and-terms" }, { "source_path": "docs/boards/boards/kanban-basics.md", - "redirect_url": "/azure/devops/boards/boards/kanban-quickstart", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/boards/kanban-quickstart" }, { "source_path": "docs/boards/backlogs/backlogs-boards-plans.md", - "redirect_url": "/azure/devops/boards/get-started/what-is-azure-boards", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/get-started/what-is-azure-boards" }, { "source_path": "docs/boards/github/add-remove-repositories.md", - "redirect_url": "/azure/devops/boards/github/install-github-app#add-remove-repos", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/github/install-github-app#add-remove-repos" }, { "source_path": "docs/boards/github/change-azure-boards-app-github-repository-access.md", - "redirect_url": "/azure/devops/boards/github/install-github-app#change-repository-access", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/github/install-github-app#change-repository-access" }, { "source_path": "docs/boards/github/troubleshoot-github-connection.md", - "redirect_url": "/azure/devops/boards/github/connect-to-github#resolve-connection-issues", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/github/connect-to-github#resolve-connection-issues" }, { "source_path": "docs/boards/boards/definition-of-done.md", - "redirect_url": "/azure/devops/boards/boards/add-columns", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/boards/add-columns" }, { "source_path": "docs/boards/boards/best-practices-kanban.md", - "redirect_url": "/azure/devops/boards/boards/kanban-overview", - "redirect_document_id": false + "redirect_url": "/azure/devops/boards/boards/kanban-overview" + }, + { + "source_path": "docs/organizations/notifications/add-links-to-work-items.md", + "redirect_url": "/azure/devops/boards/backlogs/add-link" + }, + { + "source_path": "docs/boards/extensions/delivery-plans.md", + "redirect_url": "/azure/devops/boards/plans/review-team-plans" + }, + { + "source_path": "docs/boards/work-items/best-tool-add-update-link-work-items.md", + "redirect_url": "/azure/devops/boards/work-items/about-work-items" + }, + { + "source_path": "docs/organizations/settings/work/troubleshoot-work-item-form-caching-issues.md", + "redirect_url": "/azure/devops/boards/faqs" + }, + { + "source_path": "docs/boards/extensions/index.md", + "redirect_url": "/azure/devops/boards/extensions/migrate-integrate" + }, + { + "source_path": "docs/boards/backlogs/best-practices-product-backlog.md", + "redirect_url": "/azure/devops/boards/backlogs/set-up-your-backlog" + }, + { + "source_path": "docs/boards/queries/query-support-integration-cross-service-extensions.md", + "redirect_url": "/azure/devops/boards/extensions/migrate-integrate" + }, + { + "source_path": "docs/boards/backlogs/product-backlog-controls.md", + "redirect_url": "/azure/devops/boards/backlogs/backlogs-overview#product-backlog-controls" + }, + { + "source_path": "docs/boards/queries/triage-work-items.md", + "redirect_url": "/azure/devops/boards/work-items/about-work-items" + }, + { + "source_path": "docs/boards/backlogs/copy-list.md", + "redirect_url": "/azure/devops/boards/backlogs/copy-clone-work-items" + }, + { + "source_path": "docs/boards/queries/high-performing-queries.md", + "redirect_url": "/azure/devops/boards/queries/using-queries#best-practices" + }, + { + "source_path": "docs/boards/queries/define-query-hyperlink.md", + "redirect_url": "/azure/devops/boards/queries/using-queries#define-a-query-as-a-hyperlink" + }, + { + "source_path": "docs/boards/queries/share-plans.md", + "redirect_url": "/azure/devops/boards/work-items/email-work-items" + }, + { + "source_path": "docs/organizations/security/permissions-access-work-tracking.md", + "redirect_url": "/azure/devops/organizations/security/set-permissions-access-work-tracking" + }, + { + "source_path": "docs/boards/work-items/work-items-form-controls.md", + "redirect_url": "/azure/devops/boards/work-items/about-work-items#work-items-form-controls" + }, + { + "source_path": "docs/organizations/settings/set-working-days.md", + "redirect_url": "/azure/devops/boards/sprints/set-capacity#set-capacity-for-the-team-and-team-members" + }, + { + "source_path": "docs/repos/git/configure-repos-work-tracking.md", + "redirect_url": "/azure/devops/cross-service/cross-service-overview#azure-boards--azure-repos" + }, + { + "source_path": "docs/boards/work-items/work-item-url-hyperlink.md", + "redirect_url": "/azure/devops/boards/work-items/email-work-items" + }, + { + "source_path": "docs/project/search/faq-search.yml", + "redirect_url": "/azure/devops/project/search/manage-search" + }, + { + "source_path": "docs/organizations/settings/search-settings.md", + "redirect_url": "/azure/devops/project/search/get-started-search" + }, + { + "source_path": "docs/user-guide/service-limits.md", + "redirect_url": "/azure/devops/integrate/concepts/rate-limits" + }, + { + "source_path": "docs/integrate/concepts/cross-origin-resource-sharing.md", + "redirect_url": "/azure/devops/integrate/how-to/call-rest-api?view=azure-devops#cross-origin-resource-sharing-cors" + }, + { + "source_path": "docs/integrate/rest-api-overview.md", + "redirect_url": "/rest/api/azure/devops/?view=azure-devops-rest-7.2\u0026viewFallbackFrom=azure-devops" + }, + { + "source_path": "docs/boards/boards/kanban-enable-live-updates.md", + "redirect_url": "/azure/devops/boards/boards/kanban-overview" + }, + { + "source_path": "docs/boards/queries/link-work-items-support-traceability.md", + "redirect_url": "/azure/devops/boards/backlogs/add-link" + }, + { + "source_path": "docs/boards/work-items/work-item-deployments-control.md", + "redirect_url": "/azure/devops/boards/backlogs/add-link" + }, + { + "source_path": "docs/project/wiki/wiki-select-unpublish-versions.md", + "redirect_url": "/azure/devops/project/wiki/publish-repo-to-wiki#unpublish-a-code-wiki" + }, + { + "source_path": "docs/project/wiki/wiki-markdown-guidance.md", + "redirect_url": "/azure/devops/project/wiki/markdown-guidance#wiki-markdown-guidance" + }, + { + "source_path": "docs/project/wiki/wiki-keyboard-shortcuts.md", + "redirect_url": "/azure/devops/project/navigation/keyboard-shortcuts#wiki-shortcuts" + }, + { + "source_path": "docs/extend/publish/publicize.md", + "redirect_url": "/azure/devops/extend/publish/overview#publicize-your-extension" + }, + { + "source_path": "docs/extend/publish/manage-ratings-reviews.md", + "redirect_url": "/azure/devops/extend/publish/overview#respond-to-marketplace-extension-reviews" + }, + { + "source_path": "docs/organizations/projects/restore-project.md", + "redirect_url": "/azure/devops/organizations/projects/delete-project#restore-a-deleted-project" + }, + { + "source_path": "docs/organizations/projects/save-project-data.md", + "redirect_url": "/azure/devops/organizations/accounts/delete-project#save-project-data" + }, + { + "source_path": "docs/organizations/security/provide-stakeholder-pipeline-access.md", + "redirect_url": "/azure/devops/organizations/security/stakeholder-access" + }, + { + "source_path": "docs/repos/get-started/key-concepts-repos.md", + "redirect_url": "/azure/devops/repos/get-started/index" + }, + { + "source_path": "docs/organizations/projects/project-team-quick-reference.md", + "redirect_url": "/azure/devops/organizations/projects/about-projects" + }, + { + "source_path": "docs/project/configure-or-add-a-project-portal.md", + "redirect_url": "/azure/devops/project/wiki/about-readme-wiki" + }, + { + "source_path": "docs/organizations/projects/tf31002-unable-connect-tfs.md", + "redirect_url": "/azure/devops/user-guide/troubleshoot-connection" + }, + { + "source_path": "docs/project/navigation/use-breadcrumbs-selectors.md", + "redirect_url": "/azure/devops/project/navigation/go-to-project-repo" + }, + { + "source_path": "docs/organizations/projects/resources-granted-to-project-members.md", + "redirect_url": "/azure/devops/user-guide/project-admin-tutorial" + }, + { + "source_path": "docs/user-guide/user-guide-faqs.yml", + "redirect_url": "/azure/devops/user-guide/provide-feedback" + }, + { + "source_path": "docs/boards/work-items/automate-work-item-state-transitions.md", + "redirect_url": "/azure/devops/boards/backlogs/automate-work-item-state-transitions" + }, + { + "source_path": "docs/organizations/security/quick-reference-index-security.md", + "redirect_url": "/azure/devops/organizations/security/index" + }, + { + "source_path": "docs/organizations/security/security-glossary.md", + "redirect_url": "/azure/devops/project/navigation/glossary" + }, + { + "source_path": "docs/organizations/security/faq-permissions.yml", + "redirect_url": "/azure/devops/organizations/accounts/faq-user-and-permissions-management" + }, + { + "source_path": "docs/organizations/organizations/security/remove-users-prohibit-access.md", + "redirect_url": "/azure/active-directory/add-users-azure-active-directory#delete-a-user" + }, + { + "source_path": "docs/organizations/security/faq-github-authentication.yml", + "redirect_url": "/azure/devops/boards/github/connect-to-github#faqs" + }, + { + "source_path": "docs/migrate/migrate-from-tfs.md", + "redirect_url": "/azure/devops/migrate/migration-overview" + }, + { + "source_path": "docs/migrate/migration-import-large-collections.md", + "redirect_url": "/azure/devops/migrate/migration-prepare-test-run#migrate-large-collections" + }, + { + "source_path": "docs/migrate/migration-restricting-access-to-azure-devops-services.md", + "redirect_url": "/azure/devops/migrate/migration-prepare-test-run#restrict-access-to-azure-devops-services" + }, + { + "source_path": "docs/migrate/migration-import.md", + "redirect_url": "/azure/devops/migrate/migration-test-run" + }, + { + "source_path": "docs/migrate/migration-processtemplates.md", + "redirect_url": "/azure/devops/migrate/migration-validate" + }, + { + "source_path": "docs/migrate/faqs.yml", + "redirect_url": "/azure/devops/migrate/migration-troubleshooting" + }, + { + "source_path": "docs/migrate/migration-post-import.md", + "redirect_url": "/azure/devops/migrate/migration-post-migration" + }, + { + "source_path": "docs/report/sql-reports/analytics-insights-comparable-sql-reports.md", + "redirect_url": "/azure/devops/report/dashboards/overview#sql-server-reports" + }, + { + "source_path": "docs/extend/develop/use-control.md", + "redirect_url": "https://azdevinternal.azureedge.net/" + }, + { + "source_path": "docs/organizations/notifications/troubleshoot-contact-support.md", + "redirect_url": "/azure/devops/user-guide/provide-feedback" + }, + { + "source_path": "docs/pipelines/security/infrastructure.md", + "redirect_url": "/azure/devops/pipelines/security/misc#protect-shared-infrastructure" + }, + { + "source_path": "docs/pipelines/security/projects.md", + "redirect_url": "/azure/devops/pipelines/security/misc#protect-projects" + }, + { + "source_path": "docs/pipelines/security/repos.md", + "redirect_url": "/azure/devops/pipelines/security/misc#protect-repositories" + }, + { + "source_path": "docs/pipelines/policies/deployment-group-permissions.md", + "redirect_url": "/azure/devops/pipelines/policies/permissions#deployment-group-permissions" + }, + { + "source_path": "docs/pipelines/policies/environment-permissions.md", + "redirect_url": "/azure/devops/pipelines/policies/permissions#environment-permissions" + }, + { + "source_path": "docs/pipelines/policies/library-permissions.md", + "redirect_url": "/azure/devops/pipelines/policies/permissions#library-permissions" + }, + { + "source_path": "docs/pipelines/policies/pipeline-permissions.md", + "redirect_url": "/azure/devops/pipelines/policies/permissions#pipeline-permissions" + }, + { + "source_path": "docs/pipelines/policies/release-pipeline-permissions.md", + "redirect_url": "/azure/devops/pipelines/policies/permissions#release-pipeline-permissions" + }, + { + "source_path": "docs/pipelines/policies/service-connection-permissions.md", + "redirect_url": "/azure/devops/pipelines/policies/permissions#service-connection-permissions" + }, + { + "source_path": "docs/pipelines/policies/agent-pool-permissions.md", + "redirect_url": "/azure/devops/pipelines/policies/permissions#agent-pool-permissions" + }, + { + "source_path": "docs/pipelines/policies/task-group-permissions.md", + "redirect_url": "/azure/devops/pipelines/policies/permissions#task-group-permissions" + }, + { + "source_path": "docs/organizations/security/credential-storage.md", + "redirect_url": "/azure/devops/organizations/security/data-protection#credential-security" + }, + { + "source_path": "docs/migrate/phase-rollout-with-rings.md", + "redirect_url": "/training/modules/manage-release-cadence" + }, + { + "source_path": "docs/organizations/security/security-tools-reference.md", + "redirect_url": "/azure/devops/organizations/security/manage-tokens-namespaces" + }, + { + "source_path": "docs/organizations/billing/add-backup-billing-managers.md", + "redirect_url": "/azure/devops/organizations/billing/set-up-billing-for-your-organization-vs#add-backup-billing-managers" + }, + { + "source_path": "docs/organizations/billing/change-azure-subscription.md", + "redirect_url": "/azure/devops/organizations/billing/set-up-billing-for-your-organization-vs#change-azure-subscription" + }, + { + "source_path": "docs/boards/backlogs/add-work-items.md", + "redirect_url": "/azure/devops/boards/backlogs/manage-work-items" + }, + { + "source_path": "docs/repos/security/github-advanced-security-dependency-scanning-ecosystems-troubleshoot.md", + "redirect_url": "/azure/devops/repos/security/github-advanced-security-dependency-scanning-troubleshoot" + }, + { + "source_path_from_root": "/docs/repos/git/go-get.md", + "redirect_url": "/azure/devops/repos/git/go-install" + }, + { + "source_path": "docs/organizations/security/security-best-practices.md", + "redirect_url": "/azure/devops/organizations/security/security-overview" + }, + { + "source_path": "docs/integrate/get-started/authentication/iis-basic-auth.md", + "redirect_url": "/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate#why-did-my-pat-stop-working" + }, + { + "source_path": "docs/boards/backlogs/office/resolve-excel-data-validation-errors.md", + "redirect_url": "/azure/devops/boards/backlogs/office/tfs-office-integration-issues.md#resolve-data-validation-errors-that-occur-when-you-publish-from-Excel" + }, + { + "source_path": "docs/boards/backlogs/office/resolve-excel-data-conflicts-publish-refresh.md", + "redirect_url": "/azure/devops/boards/backlogs/office/tfs-office-integration-issues#Resolve-data-conflicts-when-you-publish-or-refresh-Excel-data" + }, + { + "source_path": "docs/extend/extension-report.md", + "redirect_url": "/azure/devops/extend/overview#extension-report" + }, + { + "source_path": "docs/extend/high-risk-extensions.md", + "redirect_url": "/azure/devops/extend/overview" } ] } - diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 00000000000..53e5de6711a --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,5 @@ +{ + "recommendations": [ + "learningengineeringoperations.learn-training-ai-assistant" + ] +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000000..84c1ea7fcbf --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "cSpell.words": [ + "Entra" + ] +} \ No newline at end of file diff --git a/.whatsnew.json b/.whatsnew.json index d63b6950bc6..619cb00bed7 100644 --- a/.whatsnew.json +++ b/.whatsnew.json @@ -7,11 +7,6 @@ "relativeLinkPrefix": "/azure/devops/" }, "inclusionCriteria": { - "additionalMicrosoftOrgs": [ - "GitHub", - "Microsoft", - "MicrosoftDocs" - ], "minAdditionsToFile": 10, "omitPullRequestTitles": true }, @@ -84,6 +79,10 @@ "names": ["pipelines"], "heading": "Azure Pipelines" }, + { + "names": ["managed-devops-pools"], + "heading": "Managed DevOps Pools" + }, { "names": ["project"], "heading": "Project" diff --git a/autopublish.yaml b/autopublish.yaml new file mode 100644 index 00000000000..79bced1c98c --- /dev/null +++ b/autopublish.yaml @@ -0,0 +1,26 @@ + + +trigger: +- main + +jobs: +- job: MergeMainToLive + pool: + vmImage: 'ubuntu-latest' + steps: + - checkout: self + persistCredentials: true + - script: | + git config --global user.name "Mike Jacobs" + git config --global user.email "mijacobs@users.noreply.github.com" + git checkout main + git checkout live + git merge main --no-ff --no-commit + if [ $? -eq 0 ]; then + git commit -m "Merged main into live" + git push origin live + else + echo "Error merging main to live" + exit 1 + fi + displayName: 'Merge main to live if main has changed' diff --git a/docs/.DS_Store b/docs/.DS_Store deleted file mode 100644 index b13eecfe046..00000000000 Binary files a/docs/.DS_Store and /dev/null differ diff --git a/docs/artifacts/.openpublishing.redirection.artifacts.json b/docs/artifacts/.openpublishing.redirection.artifacts.json index 2ec2ed2fe5c..a32e3badc12 100644 --- a/docs/artifacts/.openpublishing.redirection.artifacts.json +++ b/docs/artifacts/.openpublishing.redirection.artifacts.json @@ -9,6 +9,16 @@ "source_path_from_root": "/docs/artifacts/how-to/project-scoped-feeds-pipeline-project-permissions.md", "redirect_url": "/azure/devops/artifacts/feeds/project-scoped-feeds", "redirect_document_id": false + }, + { + "source_path_from_root": "/docs/artifacts/collaborate-with-packages.md", + "redirect_url": "/azure/devops/artifacts/concepts/best-practices", + "redirect_document_id": false + }, + { + "source_path_from_root": "/docs/artifacts/nuget/consume.md", + "redirect_url": "/azure/devops/artifacts/nuget/install-nuget-packages-with-visual-studio", + "redirect_document_id": false } ] } \ No newline at end of file diff --git a/docs/artifacts/artifact-storage.md b/docs/artifacts/artifact-storage.md index 5a550a63ae5..1d8509aac43 100644 --- a/docs/artifacts/artifact-storage.md +++ b/docs/artifacts/artifact-storage.md @@ -1,19 +1,19 @@ --- -title: View Artifacts storage consumption -description: View Azure Artifacts storage consumption at organization and project levels. +title: Monitor Artifacts storage consumption +description: How to monitor Azure Artifacts storage usage at Organization and Project levels. ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 04/10/2023 +ms.date: 05/13/2024 ms.author: rabououn ms.custom: engagement-fy23 author: ramiMSFT -monikerRange: '<= azure-devops' +monikerRange: 'azure-devops' "recommendations": "true" --- -# Artifacts storage consumption +# Monitor Artifacts storage consumption -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] Azure Artifacts adopts a consumption-based billing model for all the package types it supports, such as NuGet, npm, Python, Maven, and Universal packages. The free-tier plan provides a storage capacity of two Gibibytes (GiB) to store various package types. If you exceed the storage limit, you can either upgrade to a paid subscription or remove some of your existing artifacts. @@ -25,9 +25,7 @@ The organization-level view provides an overview of your total storage usage as 1. Sign in to your Azure DevOps organization. -1. From within your organization, select ![gear icon](../media/icons/gear-icon.png) **Organization settings**. - -1. Select **Storage** from the left pane. +1. Select ![gear icon](../media/icons/gear-icon.png) **Organization settings**, and then select **Storage** from the left navigation pane. :::image type="content" source="media/artifact-storage-navigation.png" alt-text="A screenshot showing how to navigate to org-level storage."::: @@ -35,7 +33,7 @@ The organization-level view provides an overview of your total storage usage as :::image type="content" source="media/org-level-storage.png" alt-text="A screenshot showing the storage consumption levels."::: -1. Select **View storage breakdown** from **Storage by type** to view the total storage for packages in your organization-scoped feeds. +1. Select **View storage breakdown** from the **Storage by type** section to view the total storage for packages in your organization-scoped feeds. :::image type="content" source="media/packages-org-scoped-feeds.png" alt-text="A screenshot showing total storage for packages in organization-scoped feeds."::: @@ -48,9 +46,7 @@ The project-level view provides an overview of your total storage usage as well 1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. From within your project, select ![gear icon](../media/icons/gear-icon.png) **Project settings**. - -1. Select **Storage** from the left pane. +1. Select ![gear icon](../media/icons/gear-icon.png) **Project settings**, and then select **Storage** from the left navigation pane. :::image type="content" source="media/artifacts-storage-navigation-project-level.png" alt-text="A screenshot showing how to navigate to project-level storage."::: @@ -58,12 +54,12 @@ The project-level view provides an overview of your total storage usage as well :::image type="content" source="media/proj-level-storage.png" alt-text="A screenshot showing project level storage consumption."::: -1. Select **View storage breakdown** from **Storage by type** to view the total storage for packages in project-scoped feeds. +1. Select **View storage breakdown** from the **Storage by type** section to view the total storage for packages in your project-scoped feeds. :::image type="content" source="media/packages-proj-scoped-feeds.png" alt-text="A screenshot showing the total storage for packages in project-scoped feeds."::: > [!NOTE] -> Azure Artifacts provides 2GiB of free storage for each organization. After reaching the maximum storage limit, you need to [set up billing](../organizations/billing/set-up-billing-for-your-organization-vs.md) for your organization. +> Azure Artifacts provides 2 GiB of free storage for each organization. This free tier is designed to help you evaluate if Azure Artifacts fits your workflow. As your organization starts handling more critical tasks, we recommend [set up billing](../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing) to ensure you have the appropriate resources. ## Related articles diff --git a/docs/artifacts/artifacts-key-concepts.md b/docs/artifacts/artifacts-key-concepts.md index ba8375bff82..b07608930ca 100644 --- a/docs/artifacts/artifacts-key-concepts.md +++ b/docs/artifacts/artifacts-key-concepts.md @@ -1,46 +1,71 @@ --- -title: Key concepts for Azure Artifacts -description: Important concepts for Azure Artifacts +title: Azure Artifacts key concepts +description: Understand the key concepts in Azure Artifacts. ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 01/12/2022 +ms.date: 02/12/2025 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Key concepts for Azure Artifacts +# Azure Artifacts key concepts [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -## Immutability +Azure Artifacts enable developers to host and share various types of packages to streamline collaboration and package distribution. This article covers the key concepts when working with Azure Artifacts. + +## Feeds + +Azure Artifacts feeds are organizational constructs that provide a structured way to store, manage, and share packages while controlling access. Feeds are not limited to specific package types and can host various types, such as npm, NuGet, Maven, Python, Cargo, and Universal Packages. +Feeds can be scoped to a project or an organization. However, only project-scoped feeds can be set as public, and organization-scoped feeds cannot be converted to project-scoped feeds. + +## Feed views + +Feed views allow developers to share a selected subset of package versions with their consumers. A common use case is sharing only tested and validated package versions while holding back those still in development or not meeting a specific quality standard. + +By default, feeds include three views: `@local`, `@prerelease`, and `@release`. The latter two can be renamed or deleted as needed. `@local` is the default view, commonly used in upstream sources, and it contains all packages published directly to the feed as well as those saved from upstream sources. + +## Upstream sources + +Upstream sources allow you to store packages from multiple sources within a single feed. This includes both packages you publish and those saved from external feeds and public registries such as NuGet.org or npmjs.com. When an upstream source is enabled on your feed, Azure Artifacts automatically saves a copy of any package installed by a collaborator or higher from the upstream source. -Once you publish a particular version of a package to a feed, that version number is permanently reserved. You cannot upload a newer revision package with that same version number, or delete it and upload a new package with the same version number. +For public package managers that support multiple feeds, such as NuGet and Maven, the order in which feeds are queried can vary. For example, NuGet sends parallel queries to all configured feeds and selects the first valid response it receives, which can sometimes lead to nondeterministic behavior. -Many package clients, including NuGet and npm, keep a local cache of packages on your machine. Once a client has cached a particular package version, it will return that copy on future install/restore requests. +Upstream sources help mitigate this nondeterministic behavior by searching the feed and its upstream sources in the following order: -If, on the server side, you replace a package version v1 with a new version v2, the client is unable to tell the difference. This can lead to indeterminate build results from different machines. For example, a developer's machine and the build agent might have cached different revisions of the package, leading to unexpected build results. +1. Packages published directly to the feed. -If a package is broken, buggy, or shares unintended content (like secrets), the best approach is to prepare a fix and publish it as a new version. Then, depending on the severity of the issue and how widely depended-on the package is, you can delete the package to make it unavailable for consumption. +1. Packages saved from an upstream source. -The only way to work around the immutability constraint is to create a new feed and publish the desired package version to the new feed. +1. Packages available from upstream sources. Each upstream source is searched in the order they appear in the feed's configuration. > [!NOTE] -> Deleted feeds remain in the recycle bin for 30 days then are deleted permanently. The feed name becomes available once the feed is permanently deleted. +> To take full advantage of the fast lookup feature, we recommend that you include only one feed in your configuration file. + +## Immutability + +Once you publish a specific version of a package to a feed, that version number is permanently reserved. You cannot upload a newer revision of the package with that same version number, nor can you delete it and upload a new package with the same version number. ## Indexing -Azure Artifacts maintain an index of all the packages in each feed, which enables fast list operations. List operations on your file shares require the client to open every package and examine its metadata unless your file share has been configured to provide an index that the client understands. +Azure Artifacts maintain an index of all the packages in each feed, which enables fast list operations. This is different from file shares, where the client must open each package and examine its metadata unless the file share has been configured to provide an index that the client recognizes. ## Well-formedness -Azure Artifacts validate all the published packages to ensure they're well formed. This prevents invalid packages from entering your development and build environments. However, any workflow that publishes malformed packages will break when migrating to Azure Artifacts. +Azure Artifacts validates all the published packages to ensure integrity and correctness. This helps prevent invalid packages from entering your development environment. If you have a workflow that publishes malformed packages and plan to migrate to Azure Artifacts, it’s important to revise your workflow during the transition to ensure your packages pass the validation checks in Azure Artifacts. ## Recycle Bin -Packages can be deleted manually or by setting up retention policies for your feed. Deleted packages remain in the recycle bin for 30 days then get deleted permanently. Feed owners can recover the deleted packages from the Recycle Bin. +Packages can be deleted manually or by setting up retention policies for your feed. Deleted packages remain in the recycle bin for 30 days before they are automatically deleted permanently. Only feed owners can recover the deleted packages from the recycle bin. + +You must be a feed owner also to delete feeds. Deleted feeds remain in the recycle bin for 30 days before they are automatically deleted permanently. Once the feed is permanently deleted, the feed name becomes available. + +## Related content + +- [What are feeds?](./concepts/feeds.md) + +- [Feed views](./concepts/views.md) -## Related articles +- [Azure Artifacts Upstream Sources](./concepts/upstream-sources.md) -- [Package graphs](./concepts/package-graph.md) -- [Use artifactignore](./reference/artifactignore.md) -- [Packages componentization](./collaborate-with-packages.md) +- [Delete and recover packages](./how-to/delete-and-recover-packages.md) diff --git a/docs/artifacts/cargo/cargo-publish.md b/docs/artifacts/cargo/cargo-publish.md new file mode 100644 index 00000000000..59572be9781 --- /dev/null +++ b/docs/artifacts/cargo/cargo-publish.md @@ -0,0 +1,52 @@ +--- +title: Publish Cargo packages from the command line +description: Learn how to connect to your feed and publish your Cargo packages from the command line. +ms.service: azure-devops-artifacts +ms.topic: how-to +ms.date: 03/25/2025 +monikerRange: '>= azure-devops-2022' +--- + +# Publish Cargo packages from the command line + +[!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] + +This article walks you through setting up your project, authenticating with your Azure Artifacts feed, and publishing Cargo packages from the command line. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|--------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- Download and install [rustup](https://rustup.rs/). You'll need Cargo version 1.74.0 or later. | + +## Create a feed + +Azure Artifacts recommends using a dedicated feed for consuming crates from *crates.io* and a separate feed for publishing your internal crates. If you already have an Azure Artifacts feed, skip to the next section. Otherwise, create a new feed as follows: + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select **Create Feed**. + +1. Enter a **Name** for your feed and specify its **Visibility**. If you want to include packages from public registries, check **Upstream sources**, then select a **Scope** for your feed. + +1. Select **Create** when you're done. + + :::image type="content" source="media/cargo-create-a-feed.png" alt-text="A screenshot displaying how to create a new feed in Azure Artifacts."::: + +## Publish packages + +1. If you haven't authenticated with your feed yet, follow the steps in the [Project setup](project-setup-cargo.md) to configure your config files, set up a credential provider, and log in to the registry. + +1. Run the following command in your project directory to publish your Cargo package: + + ``` + cargo publish + ``` + +## Related content + +- [Manage permissions](../feeds/feed-permissions.md) + +- [What are upstream sources?](../concepts/upstream-sources.md) + +- [Publish Cargo packages with Azure Pipelines](../../pipelines/artifacts/cargo-pipelines.md) \ No newline at end of file diff --git a/docs/artifacts/cargo/cargo-upstream-source.md b/docs/artifacts/cargo/cargo-upstream-source.md new file mode 100644 index 00000000000..5442f84a896 --- /dev/null +++ b/docs/artifacts/cargo/cargo-upstream-source.md @@ -0,0 +1,240 @@ +--- +title: Consume Cargo packages from Crates.io +description: How to consume Crates from Crates.io with Azure Artifacts +ms.service: azure-devops-artifacts +ms.author: rabououn +author: ramiMSFT +ms.topic: quickstart +ms.date: 12/13/2023 +monikerRange: '>= azure-devops-2022' +"recommendations": "true" +--- + +# Use packages from Crates.io + +[!INCLUDE [version-gt-eq-2022](../../includes/version-gt-eq-2022.md)] + +Azure Artifacts upstream sources enable developers to consume packages from public registries like Crates.io and nuget.org. This article will guide you through setting up your project and using the command line to consume Crates from Crates.io. + +This article will guide you through how to: + +> [!div class="checklist"] +> * Create an Azure Artifacts feed +> * Connect to your feed +> * Consume crates from upstream + +## Prerequisites + +- An Azure DevOps organization. [Create an organization](../../organizations/accounts/create-organization.md) if you haven't already. + +- An Azure DevOps project. [Create a project](../../organizations/projects/create-project.md#create-a-project) if you don't have one. + +- Download and install [rustup](https://rustup.rs/). + +## Create a feed + +Azure Artifacts recommends having a dedicated feed for consuming crates from crates.io and a separate feed exclusively for publishing internal crates. + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select **Create Feed**. + +1. Enter a **Name** for your feed, define its **Visibility**, and then select your **Scope**. Make sure to check the **Upstream sources** checkbox to include packages from public registries. + +1. Select **Create** when you're done. + + :::image type="content" source="media/create-cargo-upstream-feed.png" alt-text="A screenshot showing how to create a feed for cargo upstream."::: + +## Connect to your feed + +::: moniker range="azure-devops" + +#### [Private feed](#tab/privatefeed/) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **Cargo** from the left navigation pane. + +1. If this is the first time using Cargo with Azure Artifacts, make sure you have installed [rustup](https://rustup.rs/). + +1. Add the provided snippet from the **Project setup** section to your *.cargo/config.toml* file in your source repository: + + - **Project-scoped feed**: + + ``` + [registries] + = { index = "sparse+https://pkgs.dev.azure.com///_packaging//Cargo/index/" } + + [source.crates-io] + replace-with = "" + ``` + + - **Organization-scoped feed**: + + ``` + [registries] + = { index = "sparse+https://pkgs.dev.azure.com//_packaging//Cargo/index/" } + + [source.crates-io] + replace-with = "" + ``` + +#### [Public feed](#tab/publicfeed/) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **Cargo** from the left navigation pane. + +1. If this is the first time using Cargo with Azure Artifacts, make sure you have installed [rustup](https://rustup.rs/). + +1. Add the provided snippet from the **Project setup** section to your *.cargo/config.toml* file in your source repository depending on your scenario. See [Permissions table](../feeds/feed-permissions.md#permissions-table) to learn more about the different roles and their permissions: + + - **Feed Readers and anonymous users**: + + ``` + [registries] + = { index = "sparse+https://pkgs.dev.azure.com///_packaging//Cargo/index/" } + + [source.crates-io] + replace-with = "" + ``` + + - **Feed and Upstream Readers, Feed Publishers, and Feed Owners**: Be sure to include the additional flag (*~force-auth*) for proper authentication with your feed, as shown below: + + ``` + [registries] + = { index = "sparse+https://pkgs.dev.azure.com///_packaging/~force-auth/Cargo/index/" } + + [source.crates-io] + replace-with = "" + ``` + +::: moniker-end + +::: moniker range="azure-devops-2022" + +1. Sign in to your Azure DevOps collection, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **Cargo** from the left navigation pane. + +1. If this is the first time using Cargo with Azure Artifacts, make sure you have installed [rustup](https://rustup.rs/). + +1. Add the provided snippet from the **Project setup** section to your *.cargo/config.toml* file in your source repository: + + - **Project-scoped feed**: + + ``` + [registries] + = { index = "sparse+https://pkgs.dev.azure.com///_packaging//Cargo/index/" } + + [source.crates-io] + replace-with = "" + ``` + + - **Collection-scoped feed**: + + ``` + [registries] + = { index = "sparse+https://pkgs.dev.azure.com//_packaging//Cargo/index/" } + + [source.crates-io] + replace-with = "" + ``` + +::: moniker-end + +## Configure a credential provider + +To use Cargo with Azure Artifacts, you need to set up a credential provider. The provided settings will configure a default credential helper for the current user: + +#### [Windows](#tab/Windows/) + +Paste the following snippet in your %USERPROFILE%\.cargo\config.toml: + +``` +[registry] +global-credential-providers = ["cargo:token", "cargo:wincred"] +``` + +#### [Linux](#tab/Linux/) + +Paste the following snippet in your ~/.cargo/config.toml: + +``` +[registry] +global-credential-providers = ["cargo:token", "cargo:libsecret"] +``` + +#### [macOS](#tab/macOS/) + +Paste the following snippet in your ~/.cargo/config.toml: + +``` +[registry] +global-credential-providers = ["cargo:token", "cargo:macos-keychain"] +``` + +* * * + +## Log in to your registry + +1. Create a [Personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scopes to authenticate with your feed. + +1. Run the following command to log in to your registry. Replace the placeholder with your feed's name, and paste the personal access token you created in the previous step when prompted: + + #### [PowerShell ](#tab/PowerShell/) + + ``` + "Basic " + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("PAT:" + (Read-Host -MaskInput "Enter PAT"))) | cargo login --registry + ``` + + #### [Bash ](#tab/Bash/) + + ``` + read -p "Enter PAT: " PAT; echo Basic $(echo -n PAT:$PAT | base64) | cargo login --registry + ``` + + #### [Azure CLI](#tab/AzureCLI/) + + ``` + az login + az account get-access-token --query "join(' ', ['Bearer', accessToken])" --output tsv | cargo login --registry + ``` + + * * * + +## Save packages from Crates.io + +[!INCLUDE [save-requires-collaborator](../includes/save-requires-collaborator.md)] + +Now that we have set up our project, configured a credential provider, and logged into our feed, we can begin consuming packages from upstream. Azure Artifacts saves a copy of any package you install from upstream to your feed. + +In this example, we consume the `serde` crate, a serialization/deserialization framework: + +1. Run the following command in your project directory to add the crate to your *cargo.toml*: + + ``` + cargo add serde + ``` + +1. Run the following command to build your project and consume your crate: + + ``` + cargo build + ``` + +Once your package is installed, a copy will be saved to your feed. Navigate to your feed to verify its presence. Your package should be available in your feed, as shown below: + +:::image type="content" source="media/crate-from-upstream.png" alt-text="A screenshot showing the *serde* crate consumed from upstream."::: + +## Related articles + +- [Publish Cargo packages with Azure Pipelines](../../pipelines/artifacts/cargo-pipelines.md) +- [Delete and recover packages](../how-to/delete-and-recover-packages.md) +- [Configure permissions](../feeds/feed-permissions.md) diff --git a/docs/artifacts/cargo/media/cargo-create-a-feed.png b/docs/artifacts/cargo/media/cargo-create-a-feed.png new file mode 100644 index 00000000000..40470a56e6a Binary files /dev/null and b/docs/artifacts/cargo/media/cargo-create-a-feed.png differ diff --git a/docs/artifacts/cargo/media/crate-from-upstream.png b/docs/artifacts/cargo/media/crate-from-upstream.png new file mode 100644 index 00000000000..7620587b2b0 Binary files /dev/null and b/docs/artifacts/cargo/media/crate-from-upstream.png differ diff --git a/docs/artifacts/cargo/media/create-cargo-upstream-feed.png b/docs/artifacts/cargo/media/create-cargo-upstream-feed.png new file mode 100644 index 00000000000..fc8a6db14a0 Binary files /dev/null and b/docs/artifacts/cargo/media/create-cargo-upstream-feed.png differ diff --git a/docs/artifacts/cargo/project-setup-cargo.md b/docs/artifacts/cargo/project-setup-cargo.md new file mode 100644 index 00000000000..9aa52c4cf7c --- /dev/null +++ b/docs/artifacts/cargo/project-setup-cargo.md @@ -0,0 +1,121 @@ +--- +title: Connect your Cargo project to an Azure Artifacts feed +description: Learn how to set up your Cargo project and connect to an Azure Artifacts feed. +ms.service: azure-devops-artifacts +ms.topic: how-to +ms.date: 01/21/2025 +monikerRange: '>= azure-devops-2022' +--- + +# Connect your Cargo project to an Azure Artifacts feed + +[!INCLUDE [version-gt-eq-2022](../../includes/version-gt-eq-2022.md)] + +This article guides you through setting up your Cargo project, configuring the credential provider, and connecting to an Azure Artifacts feed. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- Download and install [rustup](https://rustup.rs/). You'll need Cargo version 1.74.0 or later. | + + +## Project setup + +1. Sign in to your Azure DevOps organization, and navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **Cargo** from the left navigation pane. + +1. Add the provided snippet to your *cargo/config.toml* in your source repository. Your *config.toml* file should resemble the following: + + - **Project-scoped feed**: + + ``` + [registries] + FEED_NAME = { index = "sparse+https://pkgs.dev.azure.com/ORGANIZATION_NAME/PROJECT_NAME/_packaging/FEED_NAME/Cargo/index/" } + ``` + + - **Organization-scoped feed**: + + ``` + [registries] + FEED_NAME = { index = "sparse+https://pkgs.dev.azure.com/ORGANIZATION_NAME/_packaging/FEED_NAME/Cargo/index/" } + ``` + +1. Add the following snippet to your *cargo/config.toml* to replace the *crates.io* source with your feed. Replace the placeholder with your feed name: + + ``` + [source.crates-io] + replace-with = "FEED_NAME" + ``` + +## Configure a credential provider + +To use Cargo with Azure Artifacts, you must first set up a default credential helper. See [The Cargo Book](https://doc.rust-lang.org/nightly/cargo/reference/registry-authentication.html) for more details. + +### [Windows](#tab/windows) + +Add the following snippet to your *%USERPROFILE%\.cargo\config.toml*. This sets a default credential helper for the user: + +``` +[registry] +global-credential-providers = ["cargo:token", "cargo:wincred"] +``` + +### [Linux](#tab/linux) + +Add the following snippet to your */.cargo/config.toml*. This sets a default credential helper for the user: + +``` +[registry] +global-credential-providers = ["cargo:token", "cargo:libsecret"] +``` + +### [macOS](#tab/macOS) + +Add the following snippet to your */.cargo/config.toml*. This sets a default credential helper for the user: + +```dotnetcli +[registry] +global-credential-providers = ["cargo:token", "cargo:macos-keychain"] +``` + +- - - + + +## Log in to the registry + +1. Sign in to your Azure DevOps organization, and navigate to your project. + +1. Generate a [Personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scopes to authenticate with your feed. + +1. Run the following command to log in to your registry. Replace the placeholder with your feed's name, and provide the personal access token you created earlier when prompted: + +### [PowerShell ](#tab/powershell/) + +```powershell +"Basic " + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("PAT:" + (Read-Host -MaskInput "Enter PAT"))) | cargo login --registry +``` + +#### [Bash ](#tab/bash/) + +```bash +read -p "Enter PAT: " PAT; echo Basic $(echo -n PAT:$PAT | base64) | cargo login --registry +``` + +#### [Azure CLI](#tab/azurecli/) + +```azurecli +az login +az account get-access-token --query "join(' ', ['Bearer', accessToken])" --output tsv | cargo login --registry +``` + +- - - + + +## Next steps + +> [!div class="nextstepaction"] +> [Publish Cargo packages](../get-started-cargo.md) diff --git a/docs/artifacts/collaborate-with-packages.md b/docs/artifacts/collaborate-with-packages.md deleted file mode 100644 index 78129418e38..00000000000 --- a/docs/artifacts/collaborate-with-packages.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Source and package composition -description: Use Azure Artifacts to facilitate collaboration -ms.assetid: EA33E340-EC9A-4F75-A201-82CE9685662B -ms.service: azure-devops-artifacts -ms.date: 05/25/2023 -ms.topic: reference -monikerRange: '<= azure-devops' -"recommendations": "true" ---- - -# Accelerate collaboration and Agile development with componentization - -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - -Your product is successful, your organization is growing, and it's time to scale up your codebase to match this success. As you scale out past 2-3 teams working in a single codebase on a single product, you may find yourself asking questions like: - -- How can my teams efficiently share reusable components? - -- How do I enable my feature teams to iterate rapidly without stepping on other teams' work? - -- How do I give my teams autonomy to iterate at the pace that's right for them? - -These questions aren't just applicable to newly growing teams. If you're an established team with a legacy codebase, you may be asking these same questions as you're being asked to deliver more value, faster than ever. Regardless of your situation, componentization can help you build a codebase that scales to the size of your team and the speed of today's development. - -In this article, we'll explore how binary composition through Azure Artifacts can help you manage and share your external dependencies, your open-source software, and your isolated shared components. - -## Components and composition - -Componentization is the process of dividing and organizing your product into distinct components. Most .NET projects already have some notion of components in the form of the projects within the solution. For instance, a basic website may consist of a front-end component, a data access component, and a model/data storage component. - -## Source composition - -As your product grows, the solution and the project model can become inefficient. Changes take longer to integrate and are harder to merge, the build gets slower, and components start to grow from a single project to multiple projects. Generally, this is the point at which teams start breaking out these sets of related projects into separate solutions. - -Once you've outgrown a single solution, how you componentize becomes an interesting question. We started with **source composition**, where each component is referenced via a project reference in Visual Studio. Source composition is possible as long as your source lives in a single composition boundary: a single solution within a single source repository. - -Unfortunately, these project references start to break down when multiple solutions are involved. At this point, when solution A depends on solution B it must refer to the built binaries (i.e. DLLs) produced by solution B - this is **binary composition**. - -Accordingly, these binaries now need to be built and made available to solution A before it can build successfully. There are a few ways to do that: - -- You can check them into source control. Depending on your source control system, binaries can quickly balloon the size of your repo, slowing check-out times and general repo performance. If you start to work in branches, multiple teams can end up introducing the same binary at different versions, leading to challenging merge conflicts. - -- Alternatively, you can host them on a file share, although this approach comes with certain limitations. File shares lack an index for quick lookups, and they do not provide protection against overwriting a version in the future. - -## Package composition - -Packages address many of the challenges of referencing binaries. Instead of checking them into source, you can have a solution B produce its binaries as NuGet packages that another solution A can then consume. If solution A and solution B are maintained as separate components, where simultaneous changes across A and B are rare, package composition is a great way to manage the dependency of A on B. Package composition allows B to iterate on its own cadence, while A is free to get updates from B when A's schedule permits, and it allows multiple teams to iterate and update solution B without affecting solution A (or other solutions C or D). - -However, package composition does come with its own set of challenges. So far, we have examined a straightforward example. Scaling package composition up to the size of a large codebase (something like Windows or Bing) can cause a series of challenges: - -- Understanding the impact of breaking changes in a component low in the dependency graph becomes very challenging. - -- [Diamond dependencies](/dotnet/standard/library-guidance/dependencies#diamond-dependencies) can become a significant roadblock to agility. In a diamond dependency, components B and C both depend on a shared component A, while component D depends on both B and C. When component A introduces a new version with breaking changes, if B updates to the new version but C does not, D cannot take B's updates without introducing a dependency conflict. In this simple example, a conversation with C may be all that's needed to resolve the conflict. However, in a complex graph, diamonds can quickly become unresolvable. - -- When modifications need to be applied to two components that are composed using packages, the developer's iteration cycle becomes considerably slower. If Component A is updated, it necessitates rebuilding, repackaging, and republishing it. Subsequently, component B must update to the recently published version to validate the change made in component A. Employing source composition, which allows for simultaneous building of Component A and B, will consistently deliver a quicker iteration cycle for developers. - -## What should you use - -In general, we've seen large teams be most successful when they use a mixture of composition strategies. To help determine what's right for your codebase, begin by mapping out the dependency graph of your product, and start to group your components into sets of related components. - -For instance you might have a collection of components constituting your framework, and another set of component forming your user-facing service. -Then, for each group of related components, ask these questions: - -- Can I anticipate frequent check-ins across the sets I've established for my teams? - -- Is a single team responsible for the entire set? - -- For a single set, is there a shared release cadence? - -In our experience, we have found that using **source composition** is most effective for related projects handled by a single team or a group of related teams. Conversely, **binary composition** proves advantageous for open-source software, external dependencies (components from distant or isolated teams), and independent shared components. - -## Next steps - -> [!div class="nextstepaction"] -> [Publish and restore NuGet packages](/nuget/publish.md) -> [Configure feed permissions](/feeds/feed-permissions.md) -> [Set up upstream sources](/how-to/set-up-upstream-sources.md) diff --git a/docs/artifacts/concepts/best-practices.md b/docs/artifacts/concepts/best-practices.md index a01d3e98c38..44cfcbf8a88 100644 --- a/docs/artifacts/concepts/best-practices.md +++ b/docs/artifacts/concepts/best-practices.md @@ -1,66 +1,78 @@ --- -title: Best practices when working with Azure Artifacts -description: Best practices when publishing and consuming packages with Azure Artifacts +title: Azure Artifacts best practices +description: Learn best practices for publishing, consuming, and managing packages with Azure Artifacts. ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 04/07/2023 -ms.custom: contperf-fy23, engagement-fy23 +ms.date: 03/11/2025 +ms.custom: engagement-fy23 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Azure Artifacts: best practices +# Azure Artifacts best practices [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Managing software packages can be a complex and time-consuming process, particularly when working with large-scale projects. Fortunately, Azure Artifacts provides a robust platform for package management that can help streamline the process and improve collaboration among development teams. However, to get the most out of Azure Artifacts, it's essential to follow best practices that ensure the integrity and quality of your packages. In this article, we'll cover some of the most important best practices for producing, consuming, and managing packages in Azure Artifacts. Whether you're a seasoned developer or just starting with Azure Artifacts, these tips will help you optimize your workflow and ensure the success of your projects. +Managing software packages can be a complex and time-consuming process, particularly when working with large-scale projects. Azure Artifacts provides a reliable package management solution that streamlines workflows and enhances team collaboration. -## Create and publish packages +To make the most of it, following best practices is essential to maintaining package integrity and quality. This article highlights key guidelines for creating, publishing, and consuming packages in Azure Artifacts. Whether you're new to Azure Artifacts or an experienced user, these best practices help you optimize your workflow and ensure project success. -Creating and publishing packages is a critical step in any package management workflow. In this section, we'll cover best practices for creating and publishing packages in Azure Artifacts. +## Prerequisites -- **Each repository should only reference one feed**: +| **Product** | **Requirements** | +|--------------------|----------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An [Azure Artifacts feed](../start-using-azure-artifacts.md#create-a-new-feed). | - A feed is a fundamental organizational structure for hosting packages. While you can have multiple feeds for a project, it's best to limit a project to referencing just one feed. If you want to use packages from multiple feeds, it's recommended to use [upstream sources](upstream-sources.md). This enables you to access packages from multiple feeds and public registries. +## Best practices for package publishers -- **Automatically publish newly created packages to your feed**: +Following best practices helps ensure consistency, security, and a smooth user experience. Below are key recommendations when publishing packages with Azure Artifacts: - This will update the `@local` view of your feed with the new packages. See [Feed views](views.md) to learn more about feed views and upstream sources. +> [!NOTE] +> You must be a **Feed Publisher (Contributor)** or higher to publish packages to a feed. See [Manage Permissions](../feeds/feed-permissions.md#permissions-table) for more details. + +- **Use a single feed per repository**: + + A feed is an organizational construct for hosting various types of packages. While you can have multiple feeds for a project, it's best to limit a project to referencing just one feed to minimize potential conflicts. If you want to access packages from multiple feeds or public registries, it's recommended to use upstream sources. See [What are upstream sources?](upstream-sources.md) for more details. + +- **Automatically publish newly created packages**: + + Automating the publication of new packages ensures that your latest versions are always available to your team or target consumers without manual intervention. When you publish a package, it's added to the `@local` view of your feed. See [What are feed views?](views.md) for more details. - **Enable retention policies to automatically clean up old package versions**: - By deleting older package versions, you can optimize client performance and free up storage space. When setting up your [retention policies](../how-to/delete-and-recover-packages.md#delete-packages-automatically-with-retention-policies) you have the flexibility to select the number of versions of a package to keep. This allows you to easily manage package versions and improve your package management workflow. + Over time, old package versions can accumulate, consuming unnecessary storage and slowing down queries. Enabling retention policies allows you to automatically remove older package versions while keeping a specified number of recent versions. This not only optimizes client performance but also helps manage storage costs efficiently. See [retention policies](../how-to/delete-and-recover-packages.md#delete-packages-automatically-with-retention-policies) for more details. + +- **Use feed views to release packages**: -- **Promote your package to the correct view**: + Feed views can be used to share a subset of package versions with your consumers. For instance, to make a package available to early adopters, you can select it from your feed and promote it to the `@Prerelease` view. Once you've deemed the package to be of sufficient quality for a full release, you can promote it to the `@Release` view. Packages promoted to a view are exempt from retention policies and won't be subject to deletion. See [What are feed views?](views.md) for more details. - To make a package available to early adopters, you can select it from your feed and promote it to the @prerelease view. Once you've deemed the package to be of sufficient quality for a full release, you can promote it to the @release view. By promoting package versions to a view, you can prevent them from being deleted by retention policies. To learn more about feed views, check out the [Feed views](views.md) article. +- **Ensure proper access permissions for your views**: -- **If external teams are consuming your packages, ensure that `@release` and `@prerelease` views are visible across the organizations**: + If your packages are consumed by external teams or across organizations, make sure that the `@Release` and `@Prerelease` views have the appropriate visibility settings. See [Feed views settings](../feeds/feed-permissions.md#feed-views-settings) for more details. - If these views aren't visible, teams won't have access to your packages. +## Best practices for package consumers -## Consume packages +This section outlines best practices for consuming packages with Azure Artifacts to ensure efficient usage: -In this section, we'll cover best practices for consuming packages with Azure Artifacts, including configuring package sources, managing package versions, and ensuring secure and efficient package consumption. +- **Use upstream sources for external packages**: -- **Configure upstream sources for your feed**: + If you want to use packages from external feeds or public registries such as *NuGet.org* or *npmjs.com*, it's recommended to use upstream sources. See [What are upstream sources?](upstream-sources.md) and [Set up upstream sources](../how-to/set-up-upstream-sources.md) for more details. - Adding upstream sources to your feed is the recommended approach for consuming packages from public registries like NuGet.org or npmjs.com. See [Understand upstream sources](upstream-sources.md) and [how to configure upstream sources](../how-to/set-up-upstream-sources.md) for more details. + > [!NOTE] + > You must be a **Feed and Upstream Reader (Collaborator)** or higher to save packages from upstream sources. See [Manage Permissions](../feeds/feed-permissions.md#permissions-table) for more details. -- **Sources not in your organization but in the same AAD tenant should be added using the feed locator**: +- **Ensure the order of sources reflects your desired package resolution strategy**: - The syntax for the feed locator is as follows: `azure-feed:////@` + The feed checks upstream sources sequentially and will return the package from the first source that contains it. Be mindful of the order to ensure your feed resolves packages from the correct source. See [Order your upstream sources intentionally](upstream-sources.md#2-order-your-upstream-sources-intentionally) and [Search order](upstream-sources.md#search-order) for more details. -- **Ensure that the order of the sources matches your desired package resolution order**: +- **Add external sources using the feed locator**: - The feed will sequentially check each upstream source, and return the package from the first source that has it. + If sources are in the same Microsoft Entra tenant but not part of your organization, you should use the feed locator. The syntax for the feed locator is as follows: `azure-feed:////@`. -- **Place public upstreams FIRST in your resolution order**: +## Related content - This prevents other sources from overriding well-known packages with altered or incompatible versions. +- [Limits on package versions and sizes](../reference/limits.md) -## Related articles +- [Monitor Artifacts storage consumption](../artifact-storage.md) -- [Package sizes and count limits](../reference/limits.md) -- [Artifacts storage consumption](../artifact-storage.md) -- [Upstream sources overview](upstream-sources.md) +- [What are upstream sources?](upstream-sources.md) diff --git a/docs/artifacts/concepts/feeds.md b/docs/artifacts/concepts/feeds.md index b427dfa85ee..972b30314e6 100644 --- a/docs/artifacts/concepts/feeds.md +++ b/docs/artifacts/concepts/feeds.md @@ -1,115 +1,140 @@ --- -title: What are feeds? -description: Learn about Artifacts feeds and the difference between project-scoped and organization-scoped feeds. Learn how to create, delete, and restore feeds. +title: What are Azure Artifacts feeds? +description: Understand the differences between project-scoped and organization-scoped Azure Artifacts feeds. Learn the steps to create, delete, and restore feeds. ms.assetid: 21673f53-68a3-4d44-866e-ad29435a3fde ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 04/07/2022 +ms.date: 06/03/2024 monikerRange: '<= azure-devops' --- -# What are feeds? +# What are Azure Artifacts feeds? [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Artifacts Feeds are organizational constructs that allow you to store, manage, and group your packages and control who to share it with. Feeds are not package-type dependent. You can store all the following package types in a single feed: npm, NuGet, Maven, Python, and Universal packages. +Azure Artifacts feeds are organizational constructs that allow you to store, manage, and share your packages while controlling access. Feeds are not limited to specific package types; you can store various types, such as npm, NuGet, Maven, and Python packages, in a single feed. ## Project-scoped vs Organization-scoped feeds -Previously, all feeds were scoped to an organization, they could be viewed and accessed in the Azure Artifacts hub from any project within an organization. With the introduction of public feeds, we also introduced **project-scoped feeds**. This type of feed can only be accessed from within the hosting project. +Organization-scoped feeds are accessible and viewable from any project within the organization. Project-scoped feeds on the other hand, are restricted to being viewed solely within the hosting project. -Only project-scoped feeds can be made public. You can learn more about [public feeds](#public-feeds) later in this article. See [Feeds visibility](../feeds/project-scoped-feeds.md) to understand the differences between project-scoped and organization-scoped feeds. +It's important to note that organization-scoped feeds cannot be converted into project-scoped feeds. Furthermore, only project-scoped feeds have the capability to be designated as [public feeds](#public-feeds). For a detailed comparison between project-scoped and organization-scoped feeds, refer to [Feeds scope](../feeds/project-scoped-feeds.md). > [!NOTE] -> To access a feed in a different organization, a user must be given access to the project hosting that feed. +> To access a feed in a different organization, a user must be granted access to the project hosting that feed. -## Public feeds +## Create a new feed + +::: moniker range="azure-devops" + +Follow the instructions below and choose the appropriate scope to create a new project-scoped or organization-scoped feed: + +1. Sign in to your Azure DevOps organization, and then navigate to your project. -Public feeds are used to share your packages publicly with anyone on the Internet. Users won't have to be a member of your organization or your enterprise. They can access the packages even if they don't have an Azure DevOps account. +1. Select **Artifacts**, and then select **Create Feed**. -Public feeds are **project-scoped feeds** and it will inherit the visibility settings of the hosting project. +1. Enter a descriptive **Name** for your feed and define its **Visibility** (who can use your feed). Specify the **Scope** of your feed, and if you wish to include packages from public sources, mark the **Upstream sources** checkbox. + +1. Select **Create** when you're done. + + :::image type="content" source="../media/create-new-feed-azure-devops.png" alt-text="A screenshot that shows how to create a new feed in Azure DevOps Services."::: + +::: moniker-end -There some important things to note regarding public feeds: +::: moniker range="azure-devops-2022 || azure-devops-2020" -* Public feeds can only be created inside of public projects. -* Public feeds aren't intended as a replacement for existing package management platforms (NuGet.org, npmjs.com, etc.). -* Public users cannot currently download universal packages. All other package types are supported for public access. +Follow the instructions below and choose the appropriate scope to create a new project-scoped or organization-scoped feed: + +1. Sign in to your Azure DevOps server, and then navigate to your project. + +1. Select **Artifacts**, and then select **Create Feed**. + +1. Enter a descriptive **Name** for your feed and define its **Visibility** (who can use your feed). Specify the **Scope** of your feed, and if you wish to include packages from public sources, mark the **Upstream sources** checkbox. + +1. Select **Create** when you're done. + + :::image type="content" source="../media/create-new-feed-server-2022.png" alt-text="A screenshot that shows how to create a new feed in Azure DevOps Server 2022 and Server 2020."::: + +::: moniker-end > [!NOTE] -> All feed views in a public project are accessible to everyone on the internet. +> Public feeds are only available in Azure DevOps Services. -## Create public feeds +::: moniker range="azure-devops" -Public feeds are project-scoped feeds in a public project. +## Public feeds -1. Select **Artifacts**. +Public feeds allow you to share your packages publicly with anyone on the internet. Users do not need to be members of your organization, nor do they need to log in to the Azure DevOps portal to access the packages. - :::image type="content" source="../media/goto-feed-hub-azure-devops-newnav.png" alt-text="Screenshot showing Artifacts in the Azure DevOps dashboard."::: +Public feeds are **project-scoped** and inherit the visibility settings of the hosting project. Here are some important points to note about public feeds: -1. Select **Create Feed**. +- Public feeds can only be created within public projects. +- Public feeds are not intended to replace existing package management platforms (such as NuGet.org, npmjs.com, etc.). +- Public users currently cannot download universal packages, but all other package types are supported for public access. - :::image type="content" source="../media/new-feed-button-azure-devops-newnav.png" alt-text="Screenshot showing the create feed button."::: +> [!NOTE] +> All feed views in a public feed are accessible to everyone on the internet. -1. Give your feed a **Name**, and then select **Project** for your feed's scope. +## Create a public feed - :::image type="content" source="../media/new-public-feed.png" alt-text="Screenshot showing how to create a new public feed."::: +Public feeds are project-scoped feeds in a public project. Follow the instructions below to create a new public feed: -1. Select **Create** when you are done. +1. Navigate to your Azure DevOps project. Make sure that your project is **Public** in order to create a public feed. Once there, select **Artifacts** > **Create Feed**. -::: moniker range=">= azure-devops-2019" + :::image type="content" source="../media/new-feed-button-azure-devops-newnav.png" alt-text="A screenshot showing the create feed button."::: -## Delete a feed +1. Enter a **Name** for your feed, and then select **Project** for the feed's scope. Select **Create** when you're done. -1. Select **Artifacts**, and then select your feed from the dropdown menu. + :::image type="content" source="../media/new-public-feed.png" alt-text="A screenshot that shows how to create a new public feed."::: -1. Select the gear icon ![gear icon](../../media/icons/gear-icon.png) to navigate to your feed's settings. +::: moniker-end - :::image type="content" source="../media/feed-settings.png" alt-text="A screenshot showing how to access the feed's settings"::: +## Delete a feed -1. Select **Delete feed**. +> [!NOTE] +> You must be a **Feed Owner** to delete a feed. -1. Select **Delete** when you are ready. +1. Navigate to your Azure DevOps project, select **Artifacts**, and then select your feed from the dropdown menu. - :::image type="content" source="media/delete-warning.png" alt-text="A screenshot showing a warning message prior to deleting a feed"::: +1. Select the gear icon ![gear icon](../../media/icons/gear-icon.png) to navigate to your feed's settings. -## Restore deleted feeds +1. Select **Delete feed**, and then select **Delete** once more to confirm. -If you accidentally delete a feed, Azure Artifacts provides a 30 days window to recover your feed to its original state. After the 30 days, the feed will be deleted permanently. During the recovery window, the name of the feed remains reserved, packages are unavailable for download, and write access is suspended for that feed. + :::image type="content" source="media/delete-warning.png" alt-text="A screenshot displaying the warning message that appears before deleting a feed."::: -You can view the feeds that are pending permanent deletion in the feed picker dropdown list under the **Deleted Feeds** tab. +## Restore deleted feeds -1. Select **Artifacts**. +If you accidentally delete a feed, Azure Artifacts offers a 30-days window to restore it to its original state. After this period, the feed will be permanently deleted. During the recovery window, the feed's name remains reserved, packages are unavailable for download, and write access is suspended. -1. Select the feed picker dropdown menu, and then select **Deleted Feeds** +To access feeds pending permanent deletion, navigate to the feed picker dropdown menu and select the **Deleted Feeds** tab. - > [!div class="mx-imgBorder"] - > ![Deleted feeds dropdown](media/deleted-feeds.png) +1. Navigate to your Azure DevOps project, and then select **Artifacts**. -1. Select the feed you want to restore, and then select **Feed Settings**. +1. Select the feed picker dropdown menu, and then select the **Deleted Feeds** tab. - > [!div class="mx-imgBorder"] - > ![Feed settings button](media/feed-settings-button.png) + :::image type="content" source="media/deleted-feeds.png" alt-text="A screenshot that shows how to access feeds pending permanent deletion."::: -1. Select **Restore Feed**. +1. Select the feed you want to restore, and then select **Feed Settings**. Select **Restore Feed** when you're ready. -## Permanently deleting a feed + :::image type="content" source="media/feed-settings-button.png" alt-text="A screenshot displaying the feed settings button for a feed pending permanent deletion."::: -A feed pending deletion will still use storage space. If you want to permanently delete your feed before the 30 days period is up, you can do this as follows: +## Permanently delete a feed -1. Select **Artifacts**. +A feed pending deletion will continue to use storage space. You must be a feed owner to permentantly delete a feed. To delete your feed before the 30-day period ends, follow these steps: -1. Select the feed picker dropdown menu, and then select **Deleted Feeds** +1. Navigate to your Azure DevOps project, and then select **Artifacts**. - > [!div class="mx-imgBorder"] - > ![Deleted feeds list](media/deleted-feeds.png) +1. Select the feed picker dropdown menu, and then select the **Deleted Feeds** tab. 1. Select the feed you want to restore, and then select **Feed Settings**. - > [!div class="mx-imgBorder"] - > ![Feed settings](media/feed-settings-button.png) - 1. Select **Permanently Delete Feed**, and then select **Delete**. -Once the feed is permanently deleted, users won't be able to view or restore its packages. The feed name will be available for reuse 15 minutes after the deletion. +> [!NOTE] +> Once a feed is permanently deleted, users will no longer have access to view or restore its packages. The feed's name will become available for reuse 15 minutes after deletion. -::: moniker-end +## Related articles + +- [Monitor Artifacts storage consumption](../artifact-storage.md) +- [Set up upstream sources](../how-to/set-up-upstream-sources.md) +- [Use upstream sources in a public feed](../how-to/public-feeds-upstream-sources.md) \ No newline at end of file diff --git a/docs/artifacts/concepts/media/allow-external-sourced-versions.png b/docs/artifacts/concepts/media/allow-external-sourced-versions.png deleted file mode 100644 index f8c218188dd..00000000000 Binary files a/docs/artifacts/concepts/media/allow-external-sourced-versions.png and /dev/null differ diff --git a/docs/artifacts/concepts/media/allow-external-versions.png b/docs/artifacts/concepts/media/allow-external-versions.png index aaa8b32c0d8..5df06bbfbd1 100644 Binary files a/docs/artifacts/concepts/media/allow-external-versions.png and b/docs/artifacts/concepts/media/allow-external-versions.png differ diff --git a/docs/artifacts/concepts/media/enable-external-versions.png b/docs/artifacts/concepts/media/enable-external-versions.png new file mode 100644 index 00000000000..98ee34413e0 Binary files /dev/null and b/docs/artifacts/concepts/media/enable-external-versions.png differ diff --git a/docs/artifacts/concepts/media/external-versions.png b/docs/artifacts/concepts/media/external-versions.png deleted file mode 100644 index fc9124ac223..00000000000 Binary files a/docs/artifacts/concepts/media/external-versions.png and /dev/null differ diff --git a/docs/artifacts/concepts/media/include-upstream-sources.png b/docs/artifacts/concepts/media/include-upstream-sources.png deleted file mode 100644 index 8e78afab925..00000000000 Binary files a/docs/artifacts/concepts/media/include-upstream-sources.png and /dev/null differ diff --git a/docs/artifacts/concepts/media/last-sync-upstreams-details.png b/docs/artifacts/concepts/media/last-sync-upstreams-details.png new file mode 100644 index 00000000000..880b0003e25 Binary files /dev/null and b/docs/artifacts/concepts/media/last-sync-upstreams-details.png differ diff --git a/docs/artifacts/concepts/media/last-sync-upstreams.png b/docs/artifacts/concepts/media/last-sync-upstreams.png new file mode 100644 index 00000000000..a0bd8aaff90 Binary files /dev/null and b/docs/artifacts/concepts/media/last-sync-upstreams.png differ diff --git a/docs/artifacts/concepts/media/upstreams-last-sync.png b/docs/artifacts/concepts/media/upstreams-last-sync.png deleted file mode 100644 index 5178b79c8e6..00000000000 Binary files a/docs/artifacts/concepts/media/upstreams-last-sync.png and /dev/null differ diff --git a/docs/artifacts/concepts/package-graph.md b/docs/artifacts/concepts/package-graph.md index d8a15662e17..286a6f461a7 100644 --- a/docs/artifacts/concepts/package-graph.md +++ b/docs/artifacts/concepts/package-graph.md @@ -1,53 +1,53 @@ --- -title: Constructing a complete package graph +title: Construct a complete package graph description: Package graphs in Azure Artifacts ms.assetid: 3f273ac7-3c2e-47d0-b333-3ca44c19bbf4 ms.service: azure-devops-artifacts ms.topic: quickstart ms.reviewer: amullans monikerRange: '<= azure-devops' -ms.date: 2/6/2018 +ms.date: 07/21/2023 --- -# Constructing a complete package graph +# Package graphs in Azure Artifacts [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -> [!NOTE] -> Check your [package type](../start-using-azure-artifacts.md#feature-availability) to ensure compatibility with Azure DevOps Services or on-premises. +When releasing a package, it's crucial to ensure that all dependencies of that package are available in your feed by consuming them from an upstream source. Once you consume a package from an upstream source, a copy is saved to your feed. This ensures that even if the upstream source becomes inaccessible, your copy will continue to be available to both you and your feed consumers. -When you release a package, it's important to ensure that all the package dependencies are also available. Azure Artifacts recommend using [upstream sources](upstream-sources.md) to publish and consume package dependencies. When a package is consumed from an upstream source for the first time, a copy of that package is saved in the feed, so even if the upstream source goes down, your copy will remain available to you and your customers. +## How upstreams construct the set of available packages -## How upstream sources construct the set of available packages +As Azure Artifacts feeds can have other feeds as upstreams, there's a potential for creating cycles of upstream sources, where feed *A* upstreams to feed *B*, which upstreams to feed *C*, and eventually, feed *C* upstreams back to feed *A*. Such a cycle, if not managed properly, could lead to issues with package requests, creating an infinite loop where a user requests a package from feed *A*, then *A* requests from *B*, then *B* requests from *C*, and finally, *C* requests back to *A*, forming a loop. -Because Azure Artifacts feeds can have other feeds as upstream sources, it seems possible on the surface to have a cycle of upstream sources, where feed A upstreams to feed B, which upstreams to feed C, which upstreams back to feed A. Left unchecked, such a cycle could break package requests by creating an infinite loop where a user asks A for a package, then A asks B, then B asks C, then C asks A again, etc. Upstream sources are designed to prevent this failure. +Upstream sources are designed to prevent such situations. When a feed looks up a package from its upstream sources, it receives the packages in the view configured for that upstream source. This means that querying feed A doesn't trigger a transitive query to feed *C* (A -> B -> C) because views are read-only. +As a result, feed *A* will have access to any packages from *C* that have been previously saved into *B* by a user, but not the full set of packages available in *C*. -When a feed consults its upstream sources for a package, Azure Artifacts will return the packages in the view configured for that upstream source. Thus, a query to feed A does not actually result in a transitive query to feed C (A -> B -> C), because views are read-only. A has access to any packages from C that a user of B has previously saved into B, but not the full set of packages available in C. +This places the responsibility on feed *B* to ensure that its local packages represent a complete dependency graph. By doing so, users who consume B's package via an upstream source from another feed can successfully resolve the graph and install their desired *B* package without encountering issues. -Thus, the onus falls to B to ensure that its local packages represent a complete dependency graph, so that users who consume B's package via an upstream source from another feed are able to successfully resolve the graph and install their desired B package. +## Example: construct the set of available packages -## Example: constructing the set of available packages +Let's consider three feeds: Fabrikam, Contoso, and AdventureWorks. In this illustration, we'll examine the available packages to the Fabrikam feed as we introduce upstream sources. -Assume three feeds, Fabrikam, Contoso, and AdventureWorks. In this example, we'll look at the packages available to the Fabrikam feed as we add upstream sources. +Initially, Fabrikam has no upstream sources, allowing users connected to Fabrikam to only install versions 1.0.0 and 2.0.0 of the Widgets package. Similarly, Contoso has no upstream sources, restricting users connected to Contoso to only install versions 1.0.0 and 3.0.0 of the Gizmos package. The same applies to the AdventureWorks feed, where connected users can only install versions 1.0.0 and 2.0.0 of the Gadgets package or version 1.0.0 of the Things package. -At first, Fabrikam has no upstream sources, and users connected to Fabrikam can only install versions 1.0.0 and 2.0.0 of the Widgets package. Likewise, Contoso has no upstream sources, and users connected to Contoso can only install versions 1.0.0 and 3.0.0 of the Gizmos package. Ditto for the AdventureWorks feed, where connected users can only install versions 1.0.0 and 2.0.0 of the Gadgets package or version 1.0.0 of the Things package. +:::image type="content" source="media/upstream-source-graph-1.svg" alt-text="An illustration showing three different feeds with no upstream sources."::: -:::image type="content" source="media/upstream-source-graph-1.svg" alt-text="three different feeds with no upstream sources"::: +Now, let's explore the scenario where Contoso adds AdventureWorks as an upstream source. When a user is connected to Contoso, they gain access to a broader range of packages. They can install any version of Gizmos, Gadgets, or Things. For example, if the user installs Gadgets@2.0.0, this specific package-version is saved to Contoso with a link back to AdventureWorks. -Next, consider what happens if Contoso adds AdventureWorks as an upstream source. A user connected to Contoso can install any version of Gizmos, any version of Gadgets, or any version of Things. If Gadgets@2.0.0 is installed, that package-version is saved to Contoso (with a link back to AdventureWorks). +:::image type="content" source="media/upstream-source-graph-2.svg" alt-text="An illustration of Contoso adding AdventureWorks as an upstream source."::: -:::image type="content" source="media/upstream-source-graph-2.svg" alt-text="Contoso adds AdventureWorks as an upstream source"::: +Now, let's consider a situation where the Fabrikam feed adds Contoso as an upstream source. A user connected to Fabrikam can install any version of Widgets, any version of Gizmos, but **ONLY SAVED** versions of Gadgets (2.0.0). -Now, let's have the Fabrikam feed add Contoso as an upstream source. A user connected to Fabrikam can install any version of Widgets, any version of Gizmos, but **only saved** versions (2.0.0) of Gadgets. +:::image type="content" source="media/upstream-source-graph-3.svg" alt-text="An illustration of Fabrikam adding Contoso as an upstream source."::: -:::image type="content" source="media/upstream-source-graph-3.svg" alt-text="Fabrikam adds Contoso as an upstream source"::: +The user won't be able to install version 1.0.0 of Gadgets or any version of Things, because those package versions haven't been saved to Contoso by a Contoso user. -The user will not be able to install version 1.0.0 of Gadgets or any version of Things, because those package versions haven't been saved to Contoso by a Contoso user. - -:::image type="content" source="media/upstream-source-graph-4.svg" alt-text="Fabrikam users unable to install Gadgets 1.0.0 and all versions of Things"::: +:::image type="content" source="media/upstream-source-graph-4.svg" alt-text="An illustration of packages available to Fabrikam users."::: ## Related articles -- [Key concepts](../artifacts-key-concepts.md) -- [Use the .artifactignore file](../reference/artifactignore.md) -- [componentization and composition](../collaborate-with-packages.md) +- [Upstream sources](upstream-sources.md) + +- [Manage permissions](../feeds/feed-permissions.md) + +- [Manage dependencies with upstream sources](../tutorials/protect-oss-packages-with-upstream-sources.md) diff --git a/docs/artifacts/concepts/symbols.md b/docs/artifacts/concepts/symbols.md index 87eb2eaefac..b5694c7f81b 100644 --- a/docs/artifacts/concepts/symbols.md +++ b/docs/artifacts/concepts/symbols.md @@ -2,7 +2,6 @@ title: Symbol files description: Working with symbols ms.service: azure-devops-artifacts -ms.custom: contperf-fy22q1 ms.topic: conceptual ms.assetid: 6D0F0D86-2ADC-4902-AFA7-98F7EF78EE07 ms.date: 07/15/2021 diff --git a/docs/artifacts/concepts/upstream-behavior.md b/docs/artifacts/concepts/upstream-behavior.md index f08a0c1dae1..2cdbf059b47 100644 --- a/docs/artifacts/concepts/upstream-behavior.md +++ b/docs/artifacts/concepts/upstream-behavior.md @@ -1,95 +1,104 @@ --- -title: Configure upstream behavior -description: How to allow external package versions. +title: Safeguard against malicious public packages +description: Learn how to control access to public registries and protect your environment from malicious public packages. ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 05/26/2022 +ms.date: 08/22/2023 ms.author: rabououn author: ramiMSFT -monikerRange: '<= azure-devops' +monikerRange: 'azure-devops' --- -# Configure upstream behavior +# Safeguard against malicious public packages [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -With upstream sources, developers can use a single feed to publish and consume packages from Artifact feeds and public registries such as NuGet.org or npmjs.com. To set up upstream sources for your feed, check the box to **include packages from common public sources**. This will allow your feed to use packages from the common public registries. +With Azure Artifacts upstream sources, developers gain the convenience of using a unified feed to both publish and consume packages from Artifact feeds and popular public registries like NuGet.org or npmjs.com. -:::image type="content" source="media/include-upstream-sources.png" alt-text="Include packages from common public sources checkbox"::: +## Allow externally sourced versions -Previously, Artifact feeds combined a list of available package versions from the feed and all the upstream sources. +This feature enables developers to control whether they want to consume package versions from public registries such as NuGet.org or npmjs.com. -:::image type="content" source="media/previous-behavior.svg" alt-text="Previous upstream sources behavior"::: +Once the **Allow External Versions** toggle is enabled for a specific package, versions from the public registry become available for download. By default, this option is disabled, adding an extra layer of security by preventing exposure to potentially malicious packages from public registries. You must be a **Feed Owner** to enable the *allow externally sourced versions* feature. -Upstream behavior is a feature that enables developers to choose if they want to consume externally sourced package versions. Upstream behavior dictates which packages will be made available from the public registries for individual packages. +> [!NOTE] +> Changing this setting does not affect package versions already saved to the feed. Those versions will remain accessible regardless of this setting. -When the upstream behavior is enabled, when a package is published to your Azure Artifacts feed, any version from the public registry will be blocked and not made available for download. +## Applicable scenarios -This approach provides another layer of security by blocking the exposure to malicious packages that may infiltrate the public registries. +The following section outlines common scenarios where external versions (packages from public registries) are either blocked or allowed from being saved to the feed. In the rest of this article, we refer to packages from public registries as public packages and packages in an Azure Artifacts feed as private packages. -Users will still be able to toggle off the upstream behavior setting and consume packages from the public registries if they choose to do so. +### Scenario 1: public versions are blocked -> [!NOTE] -> The new behavior won't affect any package versions that are already in use. Those are stored in the feed's `@local` view. +* [Private package version made public](#private-package-version-made-public) +* [Having both private and public packages](#having-both-private-and-public-packages) -## Applicable scenarios +#### Private package version made public + +In this scenario, a team has a private package that was made public. The external versions setting in this case will cause the feed to block consumption of any new versions with that package name from a public source. + +:::image type="content" source="media\internal-to-public.svg" alt-text="An illustration showing an internal package version made public."::: + +#### Having both private and public packages -The next section shows a few common scenarios where the upstream behavior is triggered to block externally sourced package versions along with few other cases where no blockage to the public packages is needed. +In this scenario, if a team uses a combination of private and public packages, disallowing externally sourced packages blocks any new package versions from the public registry. -## Public versions will be blocked +:::image type="content" source="media\private-and-public-packages.svg" alt-text="An illustration showing available private and public packages."::: -- **Private package version made public**: in this scenario, a team has a private package that was made public. The upstream behavior in this case will be triggered to block any new public versions (untrusted packages). +### Scenario 2: public versions won't be blocked - :::image type="content" source="media\internal-to-public.svg" alt-text="Internal package version made public"::: +* [All packages are private](#all-packages-are-private) +* [All packages are public](#all-packages-are-public) +* [Public package made private](#public-package-made-private) -- **Having both private and public packages**: in this scenario, if a team already has both private and public packages, enabling the upstream behavior will result in blocking any new package versions from the public registry. +#### All packages are private* - :::image type="content" source="media\private-and-public-packages.svg" alt-text="both private and public packages"::: +If all existing packages are private, and the team has no plans to use any public packages, the external versions setting has no effect on the team's workflow in this scenario. -## Public versions will not be blocked +:::image type="content" source="media\only-private-packages.svg" alt-text="An illustration showing feed with only private packages."::: -- **All packages are private**: if all existing packages are private and the team won't be consuming any public packages, the new upstream behavior will have no effect on the team's workflow in this scenario. +#### All packages are public - :::image type="content" source="media\only-private-packages.svg" alt-text="private packages only"::: +In this scenario, if the team exclusively consumes public packages, whether from the public registry or other open-source repositories, the setting doesn't affect their workflow in any way. -- **All packages are public**: if all the packages consumed are public, whether it's from the public registry or any other open-source repositories, the new upstream behavior will have no effect on the team's workflow in this scenario. +:::image type="content" source="media\public-packages-only.svg" alt-text="An illustration showing feed with only public packages."::: - :::image type="content" source="media\public-packages-only.svg" alt-text="public packages only"::: +#### Public package made private -- **Public package made private**: if a public package is switched to a private package, the new upstream behavior will have no effect on the team's workflow in this scenario. +In this situation, when a public package is converted to a private package, the external versions setting doesn't affect the team's workflow in any way. - :::image type="content" source="media\public-to-internal.svg" alt-text="switched from public to private"::: +:::image type="content" source="media\public-to-internal.svg" alt-text="An illustration showing a package converted from public to private."::: ## Allow external versions > [!NOTE] -> You must be a feed **Owner** or a feed **Administrator** to allow externally sourced versions. See [Feed permissions](../feeds/feed-permissions.md) for more details. +> You must be a **Feed Owner** to allow externally sourced versions. For more information, see [Feed permissions](../feeds/feed-permissions.md). -1. Select **Artifacts**, and then select your feed. +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. 1. Select your package, and then select the ellipsis button for more options. Select **Allow externally-sourced versions**. - :::image type="content" source="media\external-versions.png" alt-text="A screenshot showing how to set up external versions."::: + :::image type="content" source="media\allow-external-versions.png" alt-text="A screenshot showing how to allow externally sourced versions."::: 1. Select the toggle button to allow external versions. Select **Close** when you're done. - :::image type="content" source="media\allow-external-versions.png" alt-text="A screenshot showing how to allow external versions."::: + :::image type="content" source="media\enable-external-versions.png" alt-text="A screenshot showing how to enable external versions."::: ## Allow external versions using the REST API -Aside from using the feed's user interface, you can also configure the upstream behavior using the Azure DevOps Services REST API. Select the appropriate tab and find the links to the REST API docs. - #### [NuGet](#tab/nuget/) -- [Get upstreaming behavior](/rest/api/azure/devops/artifactspackagetypes/nuget/get-upstreaming-behavior) - [Set upstreaming behavior](/rest/api/azure/devops/artifactspackagetypes/nuget/set-upstreaming-behavior) +- [Get upstreaming behavior](/rest/api/azure/devops/artifactspackagetypes/nuget/get-upstreaming-behavior) #### [npm](#tab/npm/) -- [Get upstreaming behavior](/rest/api/azure/devops/artifactspackagetypes/npm/get-package-upstreaming-behavior) -- [Get scoped package upstreaming behavior](/rest/api/azure/devops/artifactspackagetypes/npm/get-scoped-package-upstreaming-behavior) - [Set upstreaming behavior](/rest/api/azure/devops/artifactspackagetypes/npm/set-upstreaming-behavior) -- [Set scoped package upstreaming behavior](/rest/api/azure/devops/artifactspackagetypes/npm/set-scoped-upstreaming-behavior) +- [Set scoped upstreaming behavior](/rest/api/azure/devops/artifactspackagetypes/npm/set-scoped-upstreaming-behavior) +- [Get package upstreaming behavior](/rest/api/azure/devops/artifactspackagetypes/npm/get-package-upstreaming-behavior) +- [Get scoped package upstreaming behavior](/rest/api/azure/devops/artifactspackagetypes/npm/get-scoped-package-upstreaming-behavior) #### [Python](#tab/python/) @@ -148,7 +157,7 @@ Run the following command to retrieve the upstream behavior state of your packag #### [Set upstreaming behavior](#tab/set/) -Run the following commands to allow externally sourced versions for your package. This will set `versionsFromExternalUpstreams` to `AllowExternalVersions`, and will use the `$url` and `$headers` variables to query the REST API. +Run the following commands to allow externally sourced versions for your package. This sets `versionsFromExternalUpstreams` to `AllowExternalVersions`, and uses the `$url` and `$headers` variables to query the REST API. ```PowerShell $body = '{"versionsFromExternalUpstreams": "AllowExternalVersions"}' @@ -157,7 +166,7 @@ Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Patch -Content ``` > [!NOTE] -> In some cases, setting up the upstream behavior can take time to propagate across the service. If your package is not available after updating the settings, please allow up to 3 hours for the new settings to take effect. +> Changes to upstream behavior may take time to propagate across the service. If your package is not available after updating the settings, allow up to 3 hours for the changes to take effect. #### [Clear upstreaming behavior](#tab/clear/) @@ -174,7 +183,5 @@ Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Patch -Content ## Related articles - [Understand upstream sources](upstream-sources.md) -- [Set up upstream sources](../how-to/set-up-upstream-sources.md) - [Manage dependencies with upstream sources](../tutorials/protect-oss-packages-with-upstream-sources.md) -- [Feeds permissions](../feeds/feed-permissions.md) - [Best practices](best-practices.md) diff --git a/docs/artifacts/concepts/upstream-sources.md b/docs/artifacts/concepts/upstream-sources.md index c45d65ed316..9f4c41d8385 100644 --- a/docs/artifacts/concepts/upstream-sources.md +++ b/docs/artifacts/concepts/upstream-sources.md @@ -1,45 +1,50 @@ --- -title: Upstream sources overview -description: Understand upstream sources +title: What are upstream sources? +description: Understand Azure Artifacts upstream sources ms.assetid: 7cb70122-7c5b-46c1-b07e-1382cfc7d62b ms.service: azure-devops-artifacts -ms.topic: conceptual -ms.date: 02/16/2022 +ms.topic: overview +ms.date: 03/05/2025 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Upstream sources +# What are upstream sources? [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Using upstream sources, you can conveniently store packages from various sources in a single feed - including those that you publish, as well as those you consume from other feeds and public registries such as NuGet.org, npmjs.com, Maven Central, and PyPI. Once upstream sources enabled, a copy of any package installed from upstream will be automatically saved to your feed +Azure Artifacts upstream sources enable developers to conveniently store packages from various sources in a single feed, including those you publish and those installed from external feeds or public registries like NuGet.org, npmjs.com. Once upstream sources are enabled, any package installed from an upstream source is automatically saved to your feed. -> [!NOTE] -> You must be a **Collaborator** or higher to install packages from upstream sources. +[!INCLUDE [save-requires-collaborator](../includes/save-requires-collaborator.md)] -## Advantages +## Why use upstream sources? -Upstream sources enable you to manage all of your product's dependencies in a single feed. Publishing all your packages to a single feed has a few benefits: +Enabling upstream sources provides several benefits for managing your product’s dependencies within a single feed: -- **Simplicity:** your config file such as NuGet.config, npmrc, or settings.xml will contain only one feed so it less prone to mistakes and bugs. -- **Determinism:** your feed resolves package requests in order, so rebuilding your code will be more consistent. -- **Provenance:** your feed knows the provenance of the packages it saved from upstream sources, so you can verify that you're using the original package and not a copy or malicious package. -- **Peace of mind:** a copy is saved to your feed for any package installed from upstream sources. So if the upstream source is disabled, removed, or undergoing maintenance, you can still continue to develop and build because you have a copy of that package in your feed. +- **Simplicity**: Storing all your packages in a single feed simplifies your configuration files like NuGet.config, npmrc, or settings.xml. With just one feed in your config file, you reduce the chances of errors and streamline your setup. -## Best practices - package consumers +- **Consistent Builds**: Your feed resolves package requests in a defined order, ensuring more predictable and reliable builds. -To take full advantage of the benefits of upstream sources as a package consumer, follow these best practices: +- **Package Integrity**: Your feed retains metadata about packages saved from upstream sources, allowing you to verify their authenticity and ensure you're using the original versions, not copies or potentially malicious versions. + +- **Reliability**: Packages installed from upstream sources are automatically saved to your feed. This ensures continued access even if the upstream source becomes unavailable due to maintenance or other issues so you can continue developing and building with confidence. + +## Best practices for package consumers -#### Use a single feed in your config file +To take full advantage of the benefits of upstream sources as a package consumer, follow these best practices: -In order for your feed to provide [deterministic restore](#search-order), it's important to ensure that your configuration file such as nuget.config or .npmrc references only one feed with the upstream sources enabled. +#### 1. Use a single feed in your config file -Example: +In order for your feed to provide a [deterministic restore](#search-order), make sure that your configuration file (such as nuget.config or npmrc) references only one feed with upstream sources enabled. -- **nuget.config** +- **Examples**: + ```.npmrc + registry=https://pkgs.dev.azure.com/fabrikam/_packaging/FabrikamFiber/npm/registry/ + always-auth=true ``` + + ```nuget.config @@ -47,64 +52,53 @@ Example: ``` > [!NOTE] - > NuGet composes several [config files](/nuget/consume-packages/configuring-nuget-behavior) to determine the full set of options to use. Using `` allow us to ignore all other package sources defined in higher-level configuration files. - -- **.npmrc**: - - ``` - registry=https://pkgs.dev.azure.com/fabrikam/_packaging/FabrikamFiber/npm/registry/ - always-auth=true - ``` - -#### Order your upstream sources intentionally - -If you're only using public registries such as nuget.org or npmjs.com, the order of your upstream sources is irrelevant. Requests to the feed follow the [search order](#search-order). + > NuGet compiles several [configuration files](/nuget/consume-packages/configuring-nuget-behavior) to determine the complete set of options to apply. Using `` ensures that all other package sources specified in higher-level configuration files are ignored. -If you're using multiple sources such as a mixture of feeds and public registries, then each upstream is searched in the order it's listed in the feed's configuration settings. In this case, we recommend placing the public registries first in the list of upstream sources. +#### 2. Order your upstream sources intentionally -In rare cases, some organizations choose to modify OSS packages to fix security issues, to add functionality, or to satisfy requirements that the package is built from scratch internally, rather than consumed directly from the public repository. -If your organization follows this pattern, place the upstream source that contains these modified OSS packages before the public package managers to ensure you use your organization's modified versions. +If you’re only using public registries like NuGet.org or npmjs.com, the order of your upstream sources doesn’t matter. Requests to the feed follow the sequence outlined in the [search order](#search-order) section. -#### Use the suggested default view +However, when you're managing multiple sources, such as a combination of feeds and public registries, each upstream source is searched in the order defined in the feed’s configuration settings. In this case, we recommend placing the public registries first in the list of upstream sources. -When you add a remote feed as an upstream source, you must select its feed's view. This enables the upstream sources to construct a set of available packages. See [complete package graphs](package-graph.md) for more details. +In some unique scenarios, some organizations modify open-source software (OSS) packages to address security concerns, enhance functionality, or meet specific internal requirements that require rebuilding the package internally rather than obtaining it directly from a public repository. +If your organization follows this practice, place the upstream source containing these customized OSS packages before other public registries. This ensures your customized versions are used instead of public ones. -## Best practices: feed owners/package publishers +## Best practices for feed owners and package publishers -To make sure your feed is easily configured as an upstream source, consider applying the following best practices: +To ensure your feed can be easily configured as an upstream source, follow these best practices: -#### Use the default view +#### 1. Use the default view -The `@local` view is the default view for all newly created feeds. It contains all the packages published to your feed or saved from upstream sources. +The default view for all newly created feeds is `@Local`, which contains all the packages published to your feed as well as packages saved from upstream sources. -If you want to use views to release new package versions, you can promote your package to a view such as `@release` and make it available to your consumers. +If you want to use other views such as a view for newly released package versions, you can promote your packages to the `@Release` view and then make that view available to your target consumers. See [Feed views](views.md) for more details. -#### Construct a package graph +#### 2. Construct a package graph -To construct a package graph, simply connect to the feed's default view and install the package you wish to share. When the package is installed correctly in the default view, users who want to consume it will be able to resolve the package graph and install the desired package. Packages from upstream sources are displayed based on the configured view for the corresponding upstream source. +To construct a package graph, simply connect to the feed's default view and install the package you want to share. Once a package is saved to the default view, users who want to consume it will be able to resolve the package graph and install the desired version. Packages from upstream sources are displayed based on the configured view for the corresponding upstream source. See [How upstreams construct the set of available packages](package-graph.md#how-upstreams-construct-the-set-of-available-packages) for more details. ## Search order -For public package managers that support multiple feeds (NuGet and Maven), the order in which feeds are queried is sometimes unclear or nondeterministic. For example in NuGet, parallel queries are made to all the feeds in the config file, and the responses are processed first-In, first-out FIFO. +For public package managers that support multiple feeds, such as NuGet and Maven, the order in which feeds are queried can sometimes be unclear or nondeterministic. For example, NuGet sends parallel queries to all the feeds in the configuration file and processes responses in a first-in, first-out (FIFO) manner, which can lead to inconsistent results. -Upstream sources prevent this nondeterministic behavior by searching the feed and its upstream sources using the following order: +Upstream sources eliminate this uncertainty by enforcing a structured search order, by searching the feed and its upstream sources in the following order: -1. Packages pushed to the feed. +1. Packages that have been published directly to the feed. -1. Packages saved from an upstream source. +1. Packages that have been saved from an upstream source. -1. Packages available from upstream sources: each upstream is searched in the order it's listed in the feed's configuration - -To take full advantage of the fast lookup feature, we recommend that you only include one feed in your config file. +1. Packages available from upstream sources. Each upstream source is searched in the order it's listed in the feed's configuration. > [!NOTE] -> Searching for packages in upstreams with NuGet Package Explorer is not supported. +> Azure Artifacts does not support searching for packages in upstream sources using the NuGet Package Explorer in Visual Studio. ## Save packages from upstream sources -When you enable upstream sources for your feed, packages installed from upstream sources will be automatically saved to your feed. These packages could be installed directly from the upstream as follows `npm install express` or they could be installed as part of a dependency resolution (installing `express` would also save dependencies like `accepts`). +When an upstream source is enabled on your feed, Azure Artifacts will automatically save a copy of any package installed by a collaborator or higher from upstream. + +For instance, you can install packages directly from the upstream source using a command like *npm install express*. Alternatively, packages might be installed as part of a dependency resolution process. In this case, installing *express* would also save its dependencies, such as *accepts*. -Saving packages can improve download performance and save network bandwidth especially for TFS servers in internal networks. +Upstream sources provide an important safeguard for your consumers and infrastructure, protecting them from unexpected outages. If the upstream source experiences downtime, maintenance, or becomes temporarily unavailable, you can still retrieve the necessary packages from your feed and continue your development. ::: moniker range="azure-devops" @@ -115,57 +109,70 @@ Saving packages can improve download performance and save network bandwidth espe ## Override packages from upstream sources -When you enable upstream sources, you must be aware that publishing a package version that already exists in upstream will not be possible. For instance, when you enable the NuGet.org upstream, you won't be able to publish the `Newtonsoft.Json 10.0.3` package because that same package version is already present in NuGet.org. +When you enable upstream sources, keep in mind that you cannot publish a package version that already exists in an upstream source. For example, if you enable the *NuGet.org* upstream, you won't be able to publish the *Newtonsoft.Json 10.0.3* package, as that version is already available on NuGet.org. + +If you need to publish a package version that already exists in one of your upstream sources, you must follow these steps: + +1. Disable the relevant upstream source. -If you must publish a package version that already exists on one of your upstream sources, you must disable that upstream source, publish your package, and then re-enable the upstream source. +1. Publish your package. -> [!Note] +1. Re-enable the upstream source. + +This process ensures that you can publish the desired version while maintaining the integrity of your upstream sources. + +> [!NOTE] > Package versions are immutable. Saved packages remain in the feed even if the upstream source is disabled or removed. -## Health status +## Upstream sources health status -If a feed has a failing upstream source, the metadata can no longer be refreshed for packages of the same protocol. To view your upstream source's health status, select the gear icon ![gear icon](../../media/icons/gear-icon.png) to access your **Feed settings**, and then select **Upstream sources**. +If a feed has a failing upstream source, the metadata for packages of the same protocol can no longer be refreshed. To check the health status of your upstream sources, follow these steps: -:::image type="content" source="media/upstreams-last-sync.png" alt-text="A screenshot showing the upstream source failure status."::: +1. Sign in to your Azure DevOps organization, and then navigate to your project. -If there are any failures, a warning message will be displayed. Selecting the failed status provides more details such as the reason of failure and instructions on how to solve it. +1. Select **Artifacts**, and then select your feed from the dropdown menu. -:::image type="content" source="media/upstream-last-sync-details.png" alt-text="A screenshot showing details about the sync up failure."::: +1. Select the gear icon ![gear icon](../../media/icons/gear-icon.png) to navigate to your **Feed settings**, and then select **Upstream sources**. -> [!NOTE] -> For public registries such as NuGet.org, there is a 3-6 hour delay between when a package is pushed to the public registry and when it is available for download. This delay depends on job timing and data propagation. When the upstream source is an Azure Artifacts feed, the latency is typically no more than a few minutes. + :::image type="content" source="media/last-sync-upstreams.png" alt-text="A screenshot showing the upstream sources last sync up status."::: -## Offline upstream sources +1. If any failures occur, a warning message will be displayed. Clicking on the *Failed* status provides additional details, including the cause of the failure and instructions on how to resolve it. -Upstream sources are a great way to protect your consumers and infrastructure from unplanned outages. When you install a package from an upstream source, a copy of that package is saved to your feed. If the upstream source is down, undergoing maintenance, or not available, you can still access the packages you need from your feed. + :::image type="content" source="media/last-sync-upstreams-details.png" alt-text="A screenshot displaying details of the sync up failure."::: + +> [!NOTE] +> For public registries like NuGet.org, there is a 3-6 hour delay between when a package is pushed to the public registry and when it becomes available for download. This delay depends on job timing and data propagation. However, when the upstream source is an Azure Artifacts feed, the latency is usually no more than a few minutes. ## FAQs ##### Q: I can't find my package even though I can see it in one of my feed's upstreams? -A: Packages belonging to an upstream are available downstream soon after they are published. However the package will only show up in your feed's UI once it's ingested, which requires installing the package version for the first time in the downstream feed. +A: Packages from upstream sources become available in the downstream feed soon after they're published. However, the package will only be visible to readers after it has been saved to the feed. A package is saved when a user with [Feed and Upstream Reader (Collaborator)](../feeds/feed-permissions.md#permissions-table) or higher permissions installs the version in the downstream feed. This triggers the downstream to save a copy of the package from upstream, after which it is permanently saved and available in the downstream to all readers. This is when the package version becomes visible in the package versions section of the web UI. ##### Q: What are feed views? -A: Views enable developers to only share a subset of package versions that have been tested and validated and excluding any packages that are still under development and/or did not meet the quality bar. See [What are feed views](./views.md) for more details. +A: Views allow developers to selectively share a subset of package versions that have been tested and validated, excluding any packages that are still under development or haven't met the quality criteria. See [What are feed views](./views.md) for more details. ##### Q: I can't find the feed that I want to configure as an upstream source? -A: Make sure that the feed's owner is sharing a view as an upstream source. +A: Make sure that the feed's owner has shared a view as an upstream source. See [Add a feed in a different organization as an upstream source](../how-to/set-up-upstream-sources.md#add-a-feed-in-a-different-organization-as-an-upstream-source) for more details. -##### Q: Can a user with **Reader** role download packages from an upstream source? -A: No. A user with **Reader** role in an Azure Artifacts feed can only download packages that have been saved to the feed. Packages are saved to the feed when a **Collaborator**, a **Contributor**, or an **Owner** install those packages from upstream. +##### Q: Can a user with **Feed Reader** role download packages from an upstream source? + +A: No. A user with the **Feed Reader** role in an Azure Artifacts feed can only download packages that have been saved to the feed. Packages are saved to the feed when a **Feed and Upstream Reader (Collaborator)**, **Feed Publisher (Contributor)**, or **Feed Owner** installs those packages from upstream. ##### Q: What happens when a user deletes or unpublishes a package saved from an upstream source? -A: The package will not be available for download from the feed and the version number gets reserved permanently. The package also will no longer be saved from the upstream source. Earlier and later versions of the package will not be affected. + +A: The package becomes unavailable for download from the feed, and the version number is permanently reserved. Additionally, the package will no longer be saved from the upstream source. Earlier and later versions of the package will remain unaffected. ##### Q: What happens when a user deprecates a package saved from an upstream source? -A: A warning message gets added to the package's metadata and displayed whenever the package is viewed or installed from the feed. -## Related articles +A: When a user deprecates a package, a warning message is added to the package's metadata. This warning is displayed whenever the package is viewed or installed from the feed. + +## Related content - [Set up upstream sources](../how-to/set-up-upstream-sources.md) -- [Manage dependencies](../tutorials/protect-oss-packages-with-upstream-sources.md) -- [Configure upstream behavior](./upstream-behavior.md) + +- [Use upstream sources in a public feed](../how-to/public-feeds-upstream-sources.md) + - [Feed permissions](../feeds/feed-permissions.md) -- [Universal Packages upstream sources](../universal-packages/universal-packages-upstream.md) diff --git a/docs/artifacts/concepts/views.md b/docs/artifacts/concepts/views.md index fd1b37dd8ca..7e4b429e313 100644 --- a/docs/artifacts/concepts/views.md +++ b/docs/artifacts/concepts/views.md @@ -17,19 +17,22 @@ Feed views enable developers to share a subset of package-versions with their co ## Default view -All Artifacts feeds come with three views: `@local`, `@prerelease`, and `@release`. The latter two are suggested views that you can rename or delete as desired. `@local` is the default view that's commonly used in upstream sources. +All Artifacts feeds come with three views: `@local`, `@prerelease`, and `@release`. The latter two are suggested views that you can rename or delete as desired. `@local` is the default view that's commonly used in upstream sources. You can change the default view in your **Feed Settings** > **Views**, but doing so does not enable direct publishing to that view. Packages can only be published to the base feed, where they will be available in the *@Local* view. The `@local` view contains all packages published directly to the feed and all packages [saved from upstream sources](upstream-sources.md#save-packages-from-upstream-sources). Feed views are read-only, which means that users connected to a view can only use packages that are published to that view and/or packages previously saved from upstream sources. See [package graphs](package-graph.md) to learn how available packages are constructed. -> [!NOTE] -> All feed views in a public project are accessible to everyone on the internet. +> [!Note] +> Azure Artifacts only supports publishing and restoring packages from and to the default view - *@Local*. ## Feed views and upstream sources Feed views and upstream sources are designed to work together to provide an enterprise-level solution to share and consume packages. -In order for other Azure Artifacts feeds to use your feed as an upstream source, you must set your feed's visibility to **members of your organization**, or **members of your Azure Active Directory**, depending on your scenario. If you choose the latter, all people in your organization will be able to access your feed. In addition, all feeds in your organization and other organizations associated with the same Azure Active Directory tenant will be able to upstream to your feed. +In order for other Azure Artifacts feeds to use your feed as an upstream source, you must set your feed's visibility to **members of your organization**, or **members of your Microsoft Entra ID**, depending on your scenario. If you choose the latter, all people in your organization will be able to access your feed. In addition, all feeds in your organization and other organizations associated with the same Microsoft Entra tenant will be able to upstream to your feed. + +> [!NOTE] +> All feed views in a public project are accessible to everyone on the internet. ## Release packages with feed views diff --git a/docs/artifacts/feeds/feed-permissions.md b/docs/artifacts/feeds/feed-permissions.md index 3fbf544afce..a713287f43b 100644 --- a/docs/artifacts/feeds/feed-permissions.md +++ b/docs/artifacts/feeds/feed-permissions.md @@ -4,7 +4,7 @@ description: How to configure permissions for Artifacts feeds, views, and pipeli ms.assetid: 70313C3C-2E52-4FFC-94C2-41F1E37C9D26 ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 06/20/2023 +ms.date: 03/15/2024 monikerRange: '<= azure-devops' "recommendations": "true" --- @@ -23,8 +23,10 @@ Azure Artifacts enables you to publish, consume, and store various types of pack :::image type="content" source="media/configure-artifacts-settings.png" alt-text="A screenshot showing how to access Azure Artifacts settings."::: + ::: moniker range="< azure-devops-2022" > [!NOTE] > By default, the Azure Artifacts settings icon is only visible to feed owners and [project collection administrators](../../organizations/security/look-up-project-collection-administrators.md). + ::: moniker-end 1. Choose the users or groups who should have the ability to create and/or administer feeds, and then select **Save** when you're done. @@ -32,7 +34,7 @@ Azure Artifacts enables you to publish, consume, and store various types of pack ## Feed settings -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Sign in to your Azure DevOps organization, and then navigate to your project. @@ -44,61 +46,58 @@ Azure Artifacts enables you to publish, consume, and store various types of pack :::image type="content" source="media/feed-permissions.png" alt-text="A screenshot showing how to access feed permissions."::: -1. Add new user(s)/group(s) and choose the appropriate **Role** for them. - - :::image type="content" source="media/add-users-groups-dialogue.png" alt-text="Screenshot showing how to add new users or groups."::: - -1. Select **Save** when you're done. +1. Add new user(s) or group(s), choose the appropriate **Role**, and then select **Save** when you're done. + + :::image type="content" source="media/add-users-or-groups-feed-settings.png" alt-text="A screenshot displaying how to add new users or groups and assign a role."::: ::: moniker-end -::: moniker range="tfs-2018" - -1. Select **Build and Release**. - -1. Select **Packages**, and then select the gear icon to navigate to your feed's settings. +::: moniker range="azure-devops" -1. Select **Permissions**, and then select **Add user/group**. +> [!NOTE] +> By default, the *Project Collection Build Service* (org-scoped) and the project-level *Build Service* (project-scoped) are assigned the **Feed and Upstream Reader (Collaborator)** role. - :::image type="content" source="media/editfeeddialog1.png" alt-text="A screenshot showing feed permissions in TFS."::: +::: moniker-end -1. Add new user(s)/group(s) and choose the appropriate **Role** for them. +:::moniker range="<= azure-devops-2022" -1. Select **Save** when you're done. +> [!NOTE] +> By default, the *Project Collection Build Service* is automatically assigned the **Feed and Upstream Reader (Collaborator)** role for newly created collection-scoped feeds. ::: moniker-end -> [!NOTE] -> By default, the *Project Collection Build Service* (org-scoped) and the project-level *Build Service* (project-scoped) are assigned the **Collaborator** role. - ## Permissions table -| Permission | Reader | Collaborator | Contributor | Owner | Administrator | -| --------------------------------------------- | -------- | ------------ | ----------- | -------- | --------------- | -| List/install/restore packages | ✓ | ✓ | ✓ | ✓ | ✓ | -| Publish packages | | | ✓ | ✓ | ✓ | -| Unlist packages (NuGet) | | | ✓ | ✓ | ✓ | -| Delete packages | | | | ✓ | ✓ | -| Deprecate packages (Npm) | | | ✓ | ✓ | ✓ | -| Unpublish packages (Npm) | | | | ✓ | ✓ | -| Promote packages to a view | | | ✓ | ✓ | ✓ | -| Add/remove upstream sources | | | | ✓ | ✓ | -| Allow external package versions | | | | ✓ | ✓ | -| Save packages from upstream sources | | ✓ | ✓ | ✓ | ✓ | -| Edit feeds settings | | | | ✓ | ✓ | +| Permission | Feed Reader | Feed and Upstream Reader (Collaborator) | Feed Publisher (Contributor) | Feed Owner | +| ------------------------------------ | -------- | -------- | ---------| -------- | +| List packages in the feed | ✓ | ✓ | ✓ | ✓ | +| Download/install/restore packages | ✓ | ✓ | ✓ | ✓ | +| Save packages from upstream sources | | ✓ | ✓ | ✓ | +| Publish packages | | | ✓ | ✓ | +| Promote packages to a view | | | ✓ | ✓ | +| Deprecate/unlist/yank packages | | | ✓ | ✓ | +| Delete/unpublish packages | | | | ✓ | +| Add/remove upstream sources | | | | ✓ | +| Allow external package versions | | | | ✓ | +| Edit feed settings | | | | ✓ | +| Delete a feed | | | | ✓ | + +> [!NOTE] +> [Azure Artifacts Administrators](#azure-artifacts-settings), including **Project Collection Administrators**, automatically have the **Feed Owner** role on all feeds. > [!NOTE] -> To access a project-scoped feed, a user must also have access to the project hosting that feed. +> In Azure Artifacts, feeds may be scoped to a single project or to the entire organization. +> To access a project-scoped feed, a user must also have access to the project containing that feed. ## Feed views settings Feed views enable users to share certain packages while keeping others private. A common scenario for using a feed view is sharing a package version that has already been tested and validated but keeping packages under development private. -By default, there are three views in a feed: **@local**, **@prerelease**, and **@release** view. The latter two are suggested views that you can rename or delete as desired. The **@local** view is the default view and it includes all the packages published to the feed as well as all the packages downloaded from upstream sources. +By default, there are three views in a feed: **@Local**, **@Prerelease**, and **@Release**. The latter two are suggested views that you can rename or delete as desired. The **@Local** view is the default view and it includes all the packages published to the feed as well as all the packages downloaded from upstream sources. > [!IMPORTANT] > Users who have access to a specific view are able to access and download packages from the feed through that view even if they don't have direct access to that feed. -If you want to completely hide your packages, you must restrict access to both feed and views. +If you want to completely hide your packages, you must restrict access to both the feed and its views. 1. Sign in to your Azure DevOps organization, and then navigate to your project. @@ -112,23 +111,115 @@ If you want to completely hide your packages, you must restrict access to both f :::image type="content" source="media/edit-views.png" alt-text="A screenshot showing the prerelease view permissions."::: +> [!NOTE] +> To add a feed from a different organization as an upstream source, the target feed owner needs to share the target view with **All feeds and people in organizations associated with my Microsoft Entra tenant** by navigating to **Feed Settings** > **Views**, selecting the ellipsis next to the specified view, selecting **Edit**, and adjusting the permissions. + > [!IMPORTANT] > Views inherit permissions from the parent feed. If you set a view's visibility to *Specific people* without specifying any users or groups, the view's permissions will default back to the permissions of its parent feed. ## Pipelines permissions -To access your feed from your pipeline, the corresponding build identity must have the necessary permissions. By default, feeds have the *Project Collection Build Service* role set to *Collaborator*. However, if you have configured your pipeline to run at [project-scope](../../pipelines/process/access-tokens.md#job-authorization-scope), you will need to add the project-level build identity as a *Reader* or *Contributor*. The project-level build identity is named as follows: `[Project name] Build Service ([Organization name])`. Example: FabrikamFiber Build Service (codesharing-demo). +To access your feed from your pipeline, the [corresponding build identity](../../pipelines/process/access-tokens.md#scoped-build-identities) must have the necessary permissions. +If your pipeline is unable to access your feed, you might need to add the corresponding build identity to your feed's permissions. + +> [!TIP] +> - The project-level build identity is named `[Project name] Build Service ([Organization name])`, for example `FabrikamFiber Build Service (codesharing-demo)`. +> - The organization-level build identity is named `Project Collection Build Service ([Organization name])`, for example `Project Collection Build Service (codesharing-demo)`. 1. Sign in to your Azure DevOps organization, and then navigate to your project. 1. Select **Artifacts**, and then select your feed from the dropdown menu. Select the gear icon ![gear icon](../../media/icons/gear-icon.png) to navigate to **Feed settings**. -1. Select **Permissions**, and then select **Add users/groups**. Add your build identity and set its role to a **Contributor**. +1. Select **Permissions**, then select **Add users/groups**. Add your build identity and assign it the **Feed and Upstream Reader (Collaborator)** role. If your pipeline needs to publish packages to the feed, make sure that both the *Project Collection Build Service* and your *project's Build Service* identities have the **Feed Publisher (Contributor)** role. See the examples below to learn how to authenticate and publish packages to your feed with Azure Pipelines. + + :::moniker range=">= azure-devops-2022" + + :::image type="content" source="media/feed-pipelines-permissions.png" alt-text="A screenshot showing how to set up the build identities."::: + + ::: moniker-end + +#### Examples + +::: moniker range="azure-devops" + +### [NuGet](#tab/nuget) + +- [Publish NuGet packages with Azure Pipelines](../../pipelines/artifacts/nuget.md) + +### [Npm](#tab/npm) + +- [Publish npm packages with Azure Pipelines](../../pipelines/artifacts/npm.md) + +### [Maven](#tab/maven) + +- [Publish Maven artifacts with Azure Pipelines](../../pipelines/artifacts/publish-maven-artifacts.md) + +### [Python](#tab/python) + +- [Publish Python packages with Azure Pipelines](../../pipelines/artifacts/pypi.md) + +### [Cargo](#tab/cargo) + +- [Publish Cargo packages with Azure Pipelines](../../pipelines/artifacts/cargo-pipelines.md) + +### [Universal Packages](#tab/universalpackages) + +- [Publish Universal Packages with Azure Pipelines](../../pipelines/artifacts/universal-packages.md) - :::image type="content" source="media/feed-pipelines-permissions.png" alt-text="A screenshot showing the build identity permission."::: +--- + +::: moniker-end + +::: moniker range="azure-devops-2022" + +### [NuGet](#tab/nugetserver22) + +- [Publish NuGet packages with Azure Pipelines](../../pipelines/artifacts/nuget.md) + +### [Npm](#tab/npmserver22) + +- [Publish npm packages with Azure Pipelines](../../pipelines/artifacts/npm.md) + +### [Maven](#tab/mavenserver22) + +- [Publish Maven artifacts with Azure Pipelines](../../pipelines/artifacts/publish-maven-artifacts.md) + +### [Python](#tab/pythonserver22) + +- [Publish Python packages with Azure Pipelines](../../pipelines/artifacts/pypi.md) + +### [Cargo](#tab/cargoserver22) + +- [Publish Cargo packages with Azure Pipelines](../../pipelines/artifacts/cargo-pipelines.md) + +--- + +::: moniker-end + +::: moniker range="=azure-devops-2020" + +### [NuGet](#tab/nugetserver) + +- [Publish NuGet packages with Azure Pipelines](../../pipelines/artifacts/nuget.md) + +### [Npm](#tab/npmserver) + +- [Publish npm packages with Azure Pipelines](../../pipelines/artifacts/npm.md) + +### [Maven](#tab/mavenserver) + +- [Publish Maven artifacts with Azure Pipelines](../../pipelines/artifacts/publish-maven-artifacts.md) + +### [Python](#tab/pythonserver) + +- [Publish Python packages with Azure Pipelines](../../pipelines/artifacts/pypi.md) + +--- + +::: moniker-end > [!NOTE] -> If you want to access a feed in a different project from your pipeline, you must configure the other project to provide read/write access to the build service. +> If you want to access a feed in a different project from your pipeline, and your pipeline uses the project-level build identity, you must set up the other project to grant that identity at least the "Read project-level information" permission. ## Related articles diff --git a/docs/artifacts/feeds/media/add-users-or-groups-feed-settings.png b/docs/artifacts/feeds/media/add-users-or-groups-feed-settings.png new file mode 100644 index 00000000000..cd50ba7929c Binary files /dev/null and b/docs/artifacts/feeds/media/add-users-or-groups-feed-settings.png differ diff --git a/docs/artifacts/feeds/media/edit-view-permission.png b/docs/artifacts/feeds/media/edit-view-permission.png index 1045fda5b6e..2c7589c5679 100644 Binary files a/docs/artifacts/feeds/media/edit-view-permission.png and b/docs/artifacts/feeds/media/edit-view-permission.png differ diff --git a/docs/artifacts/feeds/media/manage-views.png b/docs/artifacts/feeds/media/manage-views.png new file mode 100644 index 00000000000..e6d523e97a5 Binary files /dev/null and b/docs/artifacts/feeds/media/manage-views.png differ diff --git a/docs/artifacts/feeds/media/promote-package.png b/docs/artifacts/feeds/media/promote-package.png deleted file mode 100644 index 173f6c1a10d..00000000000 Binary files a/docs/artifacts/feeds/media/promote-package.png and /dev/null differ diff --git a/docs/artifacts/feeds/media/promote-packages-select-view.png b/docs/artifacts/feeds/media/promote-packages-select-view.png new file mode 100644 index 00000000000..8084ef03ff5 Binary files /dev/null and b/docs/artifacts/feeds/media/promote-packages-select-view.png differ diff --git a/docs/artifacts/feeds/media/promote-packages-to-a-view.png b/docs/artifacts/feeds/media/promote-packages-to-a-view.png new file mode 100644 index 00000000000..e46405540ba Binary files /dev/null and b/docs/artifacts/feeds/media/promote-packages-to-a-view.png differ diff --git a/docs/artifacts/feeds/media/release-views-promote-choice.png b/docs/artifacts/feeds/media/release-views-promote-choice.png deleted file mode 100644 index ca13e71cdc0..00000000000 Binary files a/docs/artifacts/feeds/media/release-views-promote-choice.png and /dev/null differ diff --git a/docs/artifacts/feeds/media/view-permissions.png b/docs/artifacts/feeds/media/view-permissions.png deleted file mode 100644 index d187d8f855a..00000000000 Binary files a/docs/artifacts/feeds/media/view-permissions.png and /dev/null differ diff --git a/docs/artifacts/feeds/media/views-settings.png b/docs/artifacts/feeds/media/views-settings.png deleted file mode 100644 index 89334e8eb1d..00000000000 Binary files a/docs/artifacts/feeds/media/views-settings.png and /dev/null differ diff --git a/docs/artifacts/feeds/project-scoped-feeds.md b/docs/artifacts/feeds/project-scoped-feeds.md index f3c0e64b804..9194f34e9ad 100644 --- a/docs/artifacts/feeds/project-scoped-feeds.md +++ b/docs/artifacts/feeds/project-scoped-feeds.md @@ -1,109 +1,87 @@ --- -title: Project scoped feeds -description: Understand the difference between project-scoped and organization-scoped feeds +title: Project-scoped vs organization-scoped feeds +description: Learn the differences between project-scoped and organization-scoped feeds in Azure Artifacts. ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 10/03/2022 +ms.date: 10/24/2024 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Project-scoped feeds +# Feed scopes: Project vs organization feeds [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -When creating a new Azure Artifacts feed, you can choose to scope your feed to your project or your organization depending on your needs. Feeds that are created through the web interface are project-scoped by default. +Azure Artifacts enables developers to manage their dependencies from a single feed. A feed acts as an organizational space to host various types of packages, giving you control over who can access it, whether it's team members within your organization or even public users. -## Create a new feed +When creating a new feed in Azure Artifacts, you can choose to scope it to either a project or your organization, depending on your scenario. However, Azure Artifacts recommends scoping new feeds to a project. In this article, you'll learn about the key differences between the two types of feeds. -::: moniker range=">= azure-devops-2019" +## Create a feed -Follow the instructions below and select the appropriate scope for your need to create a project-scoped or an organization-scoped feed. +1. Sign in to your Azure DevOps organization and navigate to your project. 1. Select **Artifacts**, and then select **Create Feed**. - :::image type="content" source="../media/new-feed-button-azure-devops-newnav.png" alt-text="A screenshot showing the create feed button."::: +1. Provide a **Name** for your feed, choose its **Visibility** to specify who can view your packages, and check the **Include packages from common public sources** checkbox if you want to include packages from public sources such as *nuget.org*. -1. Give your feed a **Name** and choose its **visibility**. Select **upstream sources** if you want to include packages from public registries. - -1. Select **Project** if you want to create a project-scoped feed, otherwise select **Organization**. +1. Under **Scope**, select **Project** to create a project-scoped feed, or **Organization** if you want an organization-scoped feed. 1. Select **Create** when you're done. :::image type="content" source="../media/proj-org-scoped-feed.png" alt-text="A screenshot showing how to create project and organization scoped feeds."::: -::: moniker-end - -::: moniker range="tfs-2018" - -1. Navigate to **Build & Release**, and then select **Packages**. - - :::image type="content" source="../media/goto-feed-hub.png" alt-text="A screenshot showing how to navigate to feeds in TFS."::: - -1. Select the dropdown menu, and then select **New feed**. - - :::image type="content" source="../media/new-feed-button.png" alt-text="A screenshot showing how to create a new feed in TFS."::: - -1. Give your feed a **Name**, a **Description**, and then select who can read and contribute to your feed. Select **Include external packages** if you want to use packages from public registries. - -1. Select **Create** when you're done. - - :::image type="content" source="../media/new-feed-dialog-azure-tfs.png" alt-text="A screenshot showing how to set up a new feed in TFS."::: - -::: moniker-end - > [!NOTE] -> Organization-scoped feeds cannot be converted into project-scoped feeds. +> Organization-scoped feeds cannot be converted to project-scoped feeds. ## Project-scoped vs organization-scoped feeds A project-scoped feed is scoped to a project instead of an organization. Here are the main differences between the two types of feeds: -1. **Visibility**: - - * Project-scoped feeds inherit the visibility of the project. - * Organization-scoped feeds are always private by default. +| **Category** | **Project-Scoped Feed** | **Organization-Scoped Feed** | +|-------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| +| **Visibility** | Inherits the visibility of the project. | Always private by default. | +| **Links** | The URL includes the project name.
Example: `https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json` | The URL does not include a project.
Example: `https://pkgs.dev.azure.com//_packaging//nuget/v3/index.json` | +| **User Interface**| Visible only after navigating to the project that hosts the feed. | Always available from the feeds dropdown menu. | +| **Connection** | To access a feed from a pipeline running in a different project within the same organization, the **Project Collection Build Service** and the project's **Build Service** identity of the project running the pipeline must be granted the **Feed Publisher (Contributor)** role in feed settings. | You only need to assign the **Project Collection Build Service** the **Feed Publisher (Contributor)** role in feed settings. | -1. **Links**: +> [!NOTE] +> To add a feed from a different organization as an upstream source, the target feed owner must share the target view with **All feeds and people in organizations associated with my Microsoft Entra tenant** by navigating to **Feed Settings** > **Views** > selecting the ellipsis button on the right for the specified view > then selecting **Edit**. - * The URL of a project-scoped feed includes the project. - * Example: `https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json` +> [!TIP] +> If you want to add an extra layer of security to your project-scoped feed and protect your feed's visibility, you can disable the **Allow public projects** policy from the [Organization Policy Settings](../../organizations/accounts/change-application-access-policies.md). - * The URL of an organization-scoped feed doesn't include a project. - * Example: `https://pkgs.dev.azure.com//_packaging//nuget/v3/index.json` +## Q&A -1. **User interface**: - * All organization-scoped feeds are available from the feeds' dropdown menu. To see a project-scoped feed in the list of feeds, you have to navigate to the project hosting that feed. +#### Q: How can I share packages with all users in my organization? -1. **Connection**: - * When connecting to a private project scoped feed from an Azure DevOps pipeline that is in the same organization but in a different project, the project that the feed is scoped to must allow access to the other project's build service. The build service must also be separately added to the feed permissions, regardless of the scope of the feed. See [Package permissions](./feed-permissions.md#pipelines-permissions) for more details. +A: To make specific packages in your feed accessible to all users in your organization, create or select a [view](views.md) that contains the packages you want to share and set its visibility to **People in my organization**. -## Security policies +> [!IMPORTANT] +> If a user has access to a specific view, they will still be able to view and download packages from that view even without feed-level permissions. +> If you want to fully restrict access to your packages, ensure permissions are limited for both the feed and its views. See [Feeds and views permissions](feed-permissions.md) for more details. -if you want to add an extra layer of security to your project-scoped feed and protect your feed's visibility, you can disable the **Allow public projects** policy from the [Organization Policy Settings](../../organizations/accounts/change-application-access-policies.md). +#### Q: How can I access a project-scoped feed in another project from my pipeline? -Alternatively, you can use the [Create Feed API](/rest/api/azure/devops/artifacts/feed%20%20management/create%20feed?view=azure-devops-rest-5.1&preserve-view=true) to manually create a new organization-scoped feed. You will have to set the default permissions for the new feed manually either by using the [Feed Permission API](/rest/api/azure/devops/artifacts/feed%20%20management/set%20feed%20permissions?view=azure-devops-rest-5.1&preserve-view=true) or the Artifacts feed settings. +To allow a pipeline to access a project-scoped feed in a different project, you need to grant the pipeline access to both the project where the feed is scoped and to the feed itself. -> [!IMPORTANT] -> If a user has permissions to access a specific view, and they don't have permissions to the feed, they will still be able to access and download packages through that view. -> If you want to completely hide your packages, you must restrict access to both the feed and the view. See [Feeds and views permissions](feed-permissions.md) for more details. +- **Project permissions**: navigate to the project hosting the feed, select **Project settings** > **Permissions** and then add your pipeline's *project build service* to the Contributors group or any group that grants contributor access. -## Q&A +- **Feed permissions**: navigate to the feed you want to access, select **Settings** > **Feed permissions**, and then add your *project build service* as a **Feed and Upstream Reader (Collaborator)**. The *Project build service* identity is formatted as follows: `[Project name] Build Service ([Organization name])` (for example, FabrikamFiber Build Service (codesharing-demo)). -#### Q: How can I share packages with all users in my organization? +#### Q: How can I download a pipeline artifact from another project within the same organization? -A: If you want to make certain packages in your feed available to all users in your organization, create or select a [view](views.md) that contains the packages you want to share and ensure its visibility is set to **People in my organization**. +A: If your pipeline is failing to download an artifact from another project, ensure the following permissions are set for both the downstream project and the pipeline generating the artifact: -#### Q: How to access a project-scoped feed in another project using Azure Pipelines? +- **On the pipeline generating the artifact** (upstream project): select the ellipsis for more options > **Manage security** > search for your downstream project's build service, then allow the following permissions: **Update build information**, **View build pipeline**, and **View builds**. -In order for a pipeline to access a project-scoped feed in a different project, it is necessary to grant the pipeline access to both the project where the feed is scoped and the feed itself. +- **On the downstream project**: navigate to **Project Settings** > **Permissions** > **Users** > search for your upstream project's name, then select **Expand search** > select your upstream project's build service and enable **View project-level information**. -- Project setup: navigate to the project hosting the feed, select **Project settings** > **Permissions** and then add your pipeline's *project build service* to the Contributors group or any other suitable group that provides contributor access to its users. +#### Q: If I enable upstream sources in a new feed and set its visibility to 'Members of your Microsoft Entra tenant,' do I still need to add Microsoft Entra users to the Azure DevOps Organization that contains the feed? -- Feed setup: Navigate to the feed you want to access, select **Settings** > **Feed permissions** and then add your *project build service* as a **Collaborator**. Your *Project build service* identity is displayed in the following format: `[Project name] Build Service ([Organization name])` (e.g. FabrikamFiber Build Service (codesharing-demo)) +A: Yes, adding users to the Azure DevOps organization is still required for them to access the packages in the feed. You can add them as **Project Collection Valid Users** from **Organization Settings** > **Security** > **Permissions**. -## Related articles +## Related content -- [Configure permissions](./feed-permissions.md) +- [Configure feed permissions](./feed-permissions.md) +- [Use feed views to share packages](./views.md) - [Delete and recover packages](../how-to/delete-and-recover-packages.md) -- [Use feed views to share packages](./views.md) \ No newline at end of file diff --git a/docs/artifacts/feeds/views.md b/docs/artifacts/feeds/views.md index bef5177e670..3e421c3b175 100644 --- a/docs/artifacts/feeds/views.md +++ b/docs/artifacts/feeds/views.md @@ -1,135 +1,314 @@ --- -title: Use feed views to share packages -description: How to use feed views to share your packages +title: Promote packages and manage feed views +description: Learn how to promote packages to a specific view and manage feed views in Azure Artifacts. ms.assetid: EB40D23E-1053-4EBF-9D1D-19CF1BBAF1C6 ms.service: azure-devops-artifacts -ms.topic: conceptual -ms.date: 08/25/2022 +ms.topic: how-to +ms.date: 02/19/2025 monikerRange: '<= azure-devops' --- -# Use feed views to share packages +# Promote packages and manage feed views [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Feed views are a way to enable users to share some packages while keeping other packages private. Views filter the feed to a subset of packages that meet a set of criteria defined by that view. +Feed views enable developers to control package visibility by sharing some packages while keeping others private. Each view filters the feed to display a subset of packages based on specific criteria defined for that view. -By default, Azure Artifacts comes with three views: **@Local**, **@Prerelease**, and **@Release**. @local is the default view that contains all the published packages and all the packages saved from upstream sources. All views support NuGet, npm, Maven, Python, and Universal packages. +By default, Azure Artifacts comes with three views: **@Local**, **@Prerelease**, and **@Release**. The `@Local` view is the default and contains all published packages and those saved from upstream sources. All views support NuGet, npm, Maven, Python, Cargo, and Universal Packages. You can change the default view in your **Feed Settings** > **Views**, but doing so doesn't enable direct publishing to that view. Packages can only be published to the base feed, where they're available in the *@Local* view. -> [!Note] -> Publishing and restoring packages directly to/from a view is not supported in Azure Artifacts. +> [!NOTE] +> You must be a **Feed Publisher (Contributor)** or a **Feed Owner** to promote packages to a view. -## Promote packages +## Promote a package to a specific view -1. Select **Artifacts**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select your feed from the dropdown menu. +1. Select **Artifacts**, and then select your feed from the dropdown menu. -1. Select the package you wish to promote. +1. Select the package you want to promote, and then select **Promote**. -1. Select **Promote**. +1. Select a view from the dropdown menu, and then select **Promote** again. - :::image type="content" source="media/promote-package.png" alt-text="A screenshot showing how to promote a package to a view."::: + :::image type="content" source="media/promote-packages-select-view.png" alt-text="A screenshot showing the list of available views."::: -1. Select a view from the dropdown menu, and then select **Promote**. +> [!IMPORTANT] +> Azure Artifacts doesn't support package demotion. Once a package is promoted, it can't be reverted to a previous view. - :::image type="content" source="media/release-views-promote-choice.png" alt-text="Screenshot showing the promote package dialog box."::: +## Promote a package using the REST API -> [!NOTE] -> Package demotion is not supported. If you want this feature to be added to a future release, please feel free to **Suggest a feature** on [Azure DevOps Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). +To promote a package using the REST API, you need to send a PATCH request with the appropriate body formatted as a [JSON Patch](https://jsonpatch.com/) document. This appends the desired view (for example, Prerelease) to the package’s views array. + +1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read, write, & manage** scope. + +1. Copy the endpoint URL, replace it in the following example (either *PowerShell* or *curl*), and run the command to promote your package to the desired view. + +::: moniker range="azure-devops" -## Promote packages using the REST API +### [NuGet](#tab/nuget) -In addition to using the Azure Artifacts user interface, you can also promote packages using the REST API. The URI varies based on the package type: +- **Organization scoped feed**: -Use the actual user-facing name and version of the package for the `{packageName}` and `{packageVersion}` fields, respectively. If your feed is organization-scoped, omit the `{project}` field. + ```HTTP + https://pkgs.dev.azure.com/{organization}/_apis/packaging/feeds/{feedId}/nuget/packages/{packageName}/versions/{packageVersion}?api-version=7.1 + ``` + +- **Project scoped feed**: + + ```HTTP + https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feedId}/nuget/packages/{packageName}/versions/{packageVersion}?api-version=7.1 + ``` -The body of the request is a [JSON Patch](https://jsonpatch.com/) document adding the view to the end of the `views` array. See [Get started with the REST API](../../integrate/how-to/call-rest-api.md) and the [REST API samples](../../integrate/get-started/rest/samples.md) for more information on how to interact with Azure DevOps REST API. +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/nuget/update-package-version#request-body) and [NuGet - Update Package Version](/rest/api/azure/devops/artifactspackagetypes/nuget/update-package-version) for more details. -- **NuGet**: +### [Npm](#tab/npm) + +- **Organization scoped feed**: - ```Command - PATCH https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feedId}/nuget/packages/{packageName}/versions/{packageVersion}?api-version=7.1-preview.1 + ```HTTP + https://pkgs.dev.azure.com/{organization}/_apis/packaging/feeds/{feedId}/npm/{packageName}/versions/{packageVersion}?api-version=7.1 ``` + +- **Project scoped feed**: - Use [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/nuget/update%20package%20version?view=azure-devops-rest-5.1&preserve-view=true#jsonpatchoperation) to construct the body of your request. See [NuGet - update package version](/rest/api/azure/devops/artifactspackagetypes/nuget/update%20package%20version?view=azure-devops-rest-7.1&preserve-view=true) for more details. + ```HTTP + https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feedId}/npm/{packageName}/versions/{packageVersion}?api-version=7.1 + ``` + +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/npm/update-package#request-body) and [Npm - Update Package](/rest/api/azure/devops/artifactspackagetypes/npm/update-package) for more details. -- **npm**: +### [Python](#tab/python) + +- **Organization scoped feed**: - ```Command - PATCH https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feedId}/npm/{packageName}/versions/{packageVersion}?api-version=7.1-preview.1 + ```HTTP + https://pkgs.dev.azure.com/{organization}/_apis/packaging/feeds/{feedId}/pypi/packages/{packageName}/versions/{packageVersion}?api-version=7.1 ``` + +- **Project scoped feed**: - Use [JsonPatchOperation](/javascript/api/azure-devops-extension-api/jsonpatchoperation) to construct the body of your request. See [npm - update package version](/rest/api/azure/devops/artifactspackagetypes/npm/update%20package?view=azure-devops-rest-7.1&preserve-view=true) for more details. + ```HTTP + https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feedId}/pypi/packages/{packageName}/versions/{packageVersion}?api-version=7.1 + ``` + +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/python/update-package-version#request-body) and [Python - Update Package Version](/rest/api/azure/devops/artifactspackagetypes/python/update-package-version) for more details. -- **Python**: +### [Maven](#tab/maven) + +- **Organization scoped feed**: + + ```HTTP + https://pkgs.dev.azure.com/{organization}/_apis/packaging/feeds/{feed}/maven/groups/{groupId}/artifacts/{artifactId}/versions/{version}?api-version=7.1-preview.1 + ``` +- **Project scoped feed**: - ```Command - PATCH https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feedId}/pypi/packages/{packageName}/versions/{packageVersion}?api-version=7.1-preview.1 + ```HTTP + https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feed}/maven/groups/{groupId}/artifacts/{artifactId}/versions/{version}?api-version=7.1-preview.1 ``` - - Use [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/python/update%20package%20version?view=azure-devops-rest-5.1&preserve-view=true#jsonpatchoperation) to construct the body of your request. See [Python - update package version](/rest/api/azure/devops/artifactspackagetypes/python/update%20package%20version?view=azure-devops-rest-7.1&preserve-view=true) for more details. -- **Maven**: +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/maven/update-package-version#request-body) and [Maven - Update Package Version](/rest/api/azure/devops/artifactspackagetypes/maven/update-package-version) for more details. + +### [Cargo](#tab/cargo) + +- **Organization scoped feed**: - ```Command - PATCH https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feed}/maven/groups/{groupId}/artifacts/{artifactId}/versions/{version}?api-version=7.1-preview.1 + ```HTTP + https://pkgs.dev.azure.com/{organization}/_apis/packaging/feeds/{feedId}/cargo/packages/{packageName}/versions/{packageVersion}?api-version=7.2-preview.1 ``` +- **Project scoped feed**: + + ```HTTP + https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feedId}/cargo/packages/{packageName}/versions/{packageVersion}?api-version=7.2-preview.1 + ``` + +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/cargo/update-package-version#request-body) and [Cargo - Update Package Version](/rest/api/azure/devops/artifactspackagetypes/cargo/update-package-version) for more details. + +### [Universal Packages](#tab/universalpackages) - Use [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/python/update%20package%20version?view=azure-devops-rest-5.1&preserve-view=true#jsonpatchoperation) to construct the body of your request. See [Maven - update package version](/rest/api/azure/devops/artifactspackagetypes/maven/update-package-version?view=azure-devops-rest-7.1&preserve-view=true) for more details. +- **Organization scoped feed**: + + ```HTTP + https://pkgs.dev.azure.com/{organization}/_apis/packaging/feeds/{feedId}/upack/packages/{packageName}/versions/{packageVersion}?api-version=7.1-preview.1 + ``` + +- **Project scoped feed**: + + ```HTTP + https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feedId}/upack/packages/{packageName}/versions/{packageVersion}?api-version=7.1-preview.1 + ``` + +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/universal/update-package-version#request-body) and [Universal - Update Package Version](/rest/api/azure/devops/artifactspackagetypes/universal/update-package-version) for more details. + +--- + +::: moniker-end + +::: moniker range="azure-devops-2022" + +### [NuGet](#tab/nugetserver22) + +- **Collection scoped feed**: + + ```HTTP + https://{instance}/{collection}/_apis/packaging/feeds/{feedId}/nuget/packages/{packageName}/versions/{packageVersion}?api-version=7.1 + ``` + +- **Project scoped feed**: + + ```HTTP + https://{instance}/{collection}/{project}/_apis/packaging/feeds/{feedId}/nuget/packages/{packageName}/versions/{packageVersion}?api-version=7.1 + ``` + +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/nuget/update-package-version#request-body) and [NuGet - Update Package Version](/rest/api/azure/devops/artifactspackagetypes/nuget/update-package-version) for more details. + +### [Npm](#tab/npmserver22) + +- **Collection scoped feed**: -- **Universal packages**: + ```HTTP + https://{instance}/{collection}/_apis/packaging/feeds/{feedId}/npm/packagesbatch?api-version=7.1 + ``` + +- **Project scoped feed**: - ```Command - PATCH https://pkgs.dev.azure.com/{organization}/{project}/_apis/packaging/feeds/{feedId}/upack/packages/{packageName}/versions/{packageVersion}?api-version=7.1-preview.1 + ```HTTP + https://{instance}/{collection}/{project}/_apis/packaging/feeds/{feedId}/npm/packagesbatch?api-version=7.1 + ``` + +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/npm/update-package#request-body) and [Npm - Update Package](/rest/api/azure/devops/artifactspackagetypes/npm/update-package) for more details. + +### [Maven](#tab/mavenserver22) + +- **Collection scoped feed**: + + ```HTTP + https://{instance}/{collection}/_apis/packaging/feeds/{feed}/maven/groups/{groupId}/artifacts/{artifactId}/versions/{version}?api-version=7.1-preview.1 + ``` +- **Project scoped feed**: + + ```HTTP + https://{instance}/{collection}/{project}/_apis/packaging/feeds/{feed}/maven/groups/{groupId}/artifacts/{artifactId}/versions/{version}?api-version=7.1-preview.1 + ``` + +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/maven/update-package-version#request-body) and [Maven - Update Package Version](/rest/api/azure/devops/artifactspackagetypes/maven/update-package-version) for more details. + +--- + +::: moniker-end + +::: moniker range="=azure-devops-2020" + +### [NuGet](#tab/nugetserver) + +- **Collection scoped feed**: + + ```HTTP + https://{instance}/{collection}/_apis/packaging/feeds/{feedId}/nuget/packages/{packageName}/versions/{packageVersion}?api-version=6.0-preview.1 ``` + +- **Project scoped feed**: + + ```HTTP + https://{instance}/{collection}/{project}/_apis/packaging/feeds/{feedId}/nuget/packages/{packageName}/versions/{packageVersion}?api-version=6.0-preview.1 + ``` + +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/nuget/update-package-version#request-body) and [NuGet - Update Package Version](/rest/api/azure/devops/artifactspackagetypes/nuget/update-package-version) for more details. + +### [Npm](#tab/npmserver) + +- **Collection scoped feed**: + + ```HTTP + https://{instance}/{collection}/_apis/packaging/feeds/{feedId}/npm/{packageName}/versions/{packageVersion}?api-version=6.0-preview.1 + ``` + +- **Project scoped feed**: - Use [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/universal/update%20package%20version?view=azure-devops-rest-5.1&preserve-view=true#jsonpatchoperation) to construct the body of your request. See [Universal packages - update package version](/rest/api/azure/devops/artifactspackagetypes/universal/update%20package%20version?view=azure-devops-rest-7.1&preserve-view=true) for more details. + ```HTTP + https://{instance}/{collection}/{project}/_apis/packaging/feeds/{feedId}/npm/{packageName}/versions/{packageVersion}?api-version=6.0-preview.1 + ``` + +See [JsonPatchOperation](/rest/api/azure/devops/artifactspackagetypes/npm/update-package#request-body) and [Npm - Update Package](/rest/api/azure/devops/artifactspackagetypes/npm/update-package) for more details. + +--- + +::: moniker-end + +#### Examples -- **Example**: +Replace the placeholders with your personal access token, endpoint URL, and view name, then run the command to promote your package to the desired view: -```http -PATCH https://pkgs.dev.azure.com/fabrikam-fiber-inc/litware/_apis/packaging/feeds/litware-tools/nuget/packages/LitWare.Common/versions/1.0.0?api-version=5.1-preview.1 HTTP/1.1 -Content-Type: application/json-patch+json +### [PowerShell](#tab/powershell) -{ - "views": { - "op": "add", - "path": "/views/-", - "value": "Release" - } +```PowerShell +$env:PAT = "YOUR_PERSONAL_ACCESS_TOKEN" +$uri = "YOUR_URL" +$headers = @{ + "Content-Type" = "application/json" + Authorization = "Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$env:PAT")) } +$body = @{ + views = @{ + op = "add" + path = "/views/-" + value = "YOUR_VIEW_NAME" + } +} | ConvertTo-Json + +Invoke-RestMethod -Uri $uri -Method Patch -Headers $headers -Body $body ``` -## Manage views +### [curl](#tab/curl) + +```bash +PAT="YOUR_PERSONAL_ACCESS_TOKEN" +ENCODED_PAT=$(echo -n ":$PAT" | base64 | tr -d '\n') +$ curl -X PATCH "YOUR_ENDPOINT_URL" \ +-H "Content-Type: application/json" \ +-H "Authorization: Basic $ENCODED_PAT" \ +-d '{ + "views": { + "path": "/views/-", + "op": "add", + "value": "YOUR_VIEW_NAME" + } + }' +``` -You can create your own views or rename and delete existing ones from your feed's settings. +--- > [!NOTE] > All feed views in a public project are accessible to everyone on the internet. -1. Select **Artifacts**. +## Manage views -1. Select your feed from the dropdown menu. +By default, Azure Artifacts offers three views: *@Local*, *@Prerelease*, and *@Release*. You can also create new views and manage existing ones by renaming or deleting them directly from your feed's settings. -1. Select the gear icon :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: to access your feed's settings. +1. Sign in to your Azure DevOps organization, and then navigate to your project. - :::image type="content" source="../media/feed-settings.png" alt-text="Screenshot showing how to access the feed's settings."::: +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select the gear icon on the far right :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: to access your feed's settings. -1. Select **Views**. + :::image type="content" source="../media/feed-settings.png" alt-text="Screenshot showing how to access the feed's settings."::: - :::image type="content" source="./media/views-settings.png" alt-text="A screenshot showing how to navigate to views."::: +1. Select **Views**, select a view, and then select **Edit** to edit your view. If you want to add a new view, select **Add view**. -1. Select a view, and then select **Edit** to edit your view or select **Add view** if you want to add a new view. + :::image type="content" source="./media/manage-views.png" alt-text="A screenshot showing how to add, edit, or delete feed views."::: 1. Select **Save** when you're done. +::: moniker range="azure-devops" + > [!IMPORTANT] -> For public feeds, if you change the access permissions of a certain view to **Specific people** your view will not be available as an upstream source. +> For public feeds, if you change the access permissions of a view to **Specific people**, that view is no longer available as an upstream source. -## Related articles +::: moniker-end + +## Related content -- [Upstream sources overview](../concepts/upstream-sources.md) -- [Configure permissions](./feed-permissions.md) -- [Set up upstream sources](../how-to/set-up-upstream-sources.md) - [Delete and recover packages](../how-to/delete-and-recover-packages.md) + +- [Manage feed permissions](feed-permissions.md) + +- [Set up upstream sources](../how-to/set-up-upstream-sources.md) + diff --git a/docs/artifacts/get-started-artifacts-ai.md b/docs/artifacts/get-started-artifacts-ai.md new file mode 100644 index 00000000000..f8a16770dec --- /dev/null +++ b/docs/artifacts/get-started-artifacts-ai.md @@ -0,0 +1,209 @@ +--- +title: Publish a package to an Azure Artifacts feed - Copilot +description: Learn how to publish your first package to an Azure Artifacts feed. +ms.service: azure-devops-artifacts +ms.topic: quickstart +ms.author: rabououn +author: ramiMSFT +ms.date: 06/21/2024 +ms.collection: ce-skilling-ai-copilot +monikerRange: '>= azure-devops-2020' +--- + +# Publish a package to an Azure Artifacts feed + +Azure Artifacts enables developers to efficiently manage all their dependencies from a single feed. Feeds in Azure Artifacts serve as organizational repositories for storing, managing, and sharing your packages within your team, across organizations, or publicly on the internet. Azure Artifacts feeds support a wide range of package types, including NuGet, npm, Python, Maven, Cargo, and Universal Packages. + +This article walks you through the process of publishing your first package to an Azure Artifacts feed. You also have the option to use GitHub Copilot to streamline this process and explore the capabilities of the GitHub Copilot Chat in Visual Studio Code. + +## Prerequisites + +* Create an Azure DevOps [organization](../organizations/accounts/create-organization.md) and a [project](../organizations/projects/create-project.md#create-a-project) if you haven't already. + +* Install the [.NET Core SDK](https://dotnet.microsoft.com/en-us/download). + +* Install the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider). + +* (Optional) [Set up GitHub Copilot and Visual Studio Code](https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-code-suggestions-in-your-editor?tool=vscode). A 30-day GitHub Copilot free trial is available if you haven't signed up yet. + +## Create a feed + +::: moniker range="azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select **Create Feed**. + +1. Provide a descriptive **Name** for your feed and set its **Visibility** (who can view packages in your feed). Define the **Scope** of your feed, and if you want to include packages from public sources, check the **Upstream sources** checkbox. + +1. Select **Create** when you're done. + + :::image type="content" source="media/create-new-feed-azure-devops.png" alt-text="Screenshot that shows how to create a new feed in Azure DevOps Services."::: + +::: moniker-end + +::: moniker range="azure-devops-2022 || azure-devops-2020" + +1. Sign in to your Azure DevOps server, and then navigate to your project. + +2. Select **Artifacts**, and then select **Create Feed**. + +3. Provide a descriptive **Name** for your feed and set its **Visibility** (who can view packages in your feed). Define the **Scope** of your feed, and if you want to include packages from public sources, check the **Upstream sources** checkbox. + +::: moniker-end + +::: moniker range="azure-devops-2022" + +4. Select **Create** when you're done. + + :::image type="content" source="media/create-new-feed-server-2022.png" alt-text="Screenshot that shows how to create a new feed in Azure DevOps Server 2022."::: + +::: moniker-end + +::: moniker range="azure-devops-2020" + +4. Select **Create** when you're done. + + :::image type="content" source="media/create-new-feed-server-2020.png" alt-text="Screenshot that shows how to create a new feed in Azure DevOps Server 2020."::: + +::: moniker-end + +## Prepare the code + +#### [Without GitHub Copilot](#tab/withoutgithubcopilot/) + +Follow these steps to create a basic Class Library project from the command line, set up your package's metadata, and generate a NuGet package: + +1. On your local machine, create a new folder and give it a name. + +1. Open a command prompt window and navigate to the folder you created. + +1. Run the following command to create a new Class Library project: + + ```dotnetcli + dotnet new classlib + ``` + +1. Open your *csproj* file and add your package metadata within the `` tag. Your file structure should resemble the following: + + ```xml + + + + net8.0 + demo_class_library + enable + enable + + YOUR_PACKAGE_NAME + YOUR_PACKAGE_VERSION + YOUR_NAME + YOUR_COMPANY + + + + + ``` + +1. Run the following command to package your project and generate a *.nupkg* artifact. your NuGet package is generated in the `bin\release` directory. + + ```dotnetcli + dotnet pack + ``` + +#### [With GitHub Copilot](#tab/githubcopilot/) + +Before publishing a package to the feed you created earlier, you must first pack your project and prepare it for publishing. + +The following example walks you through using GitHub Copilot to create a sample .NET Core class library and generate a NuGet package from the command line. You can also use GitHub Copilot to generate other types of projects, such as npm or Python projects. + +1. Open Visual Studio Code and select the chat icon from the left navigation panel to open the GitHub Copilot Chat. + +1. In the prompt box. ask GitHub copilot: "How do I create a .NET Core project and package it as a NuGet package?". GitHub Copilot's response might be something similar to the following: + + :::image type="content" source="media/create-project-github-copilot-response.png" alt-text="A screenshot that shows a response from GitHub Copilot Chat."::: + +1. Follow the provided steps to generate your project, define your package ID and version, and pack your project. + +You can also ask GitHub Copilot to explain your project structure using the `@workspace` command, which lets you interact with the files and folders in your current workspace. + +> `@workspace` explain my app structure + +:::image type="content" source="media/github-copilot-app-structure.png" alt-text="A screenshot that shows GitHub Copilot explaining workspace app structure."::: + +Another useful method to understand new source code is to ask GitHub Copilot how specific files are related within the project. For example, you can ask how the *csproj* file is related to the *Class1.cs* file: + +> #file:artifacts-github-copilot.csproj #file:Class1.cs how are these files related + +:::image type="content" source="media/github-copilot-csproj-class-relation.png" alt-text="A screenshot that shows GitHub Copilot response in Visual Studio Code."::: + + +* * * + +## Connect to a feed + +::: moniker range="azure-devops" + +1. Select **Artifacts** and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **dotnet** from the **NuGet** section. + +1. Follow the instructions in the **Project setup** to set up your *nuget.config* file. The structure of your file should look similar to this: + + - **Project-scoped feed**: + + ```xml + + + + + + + + ``` + + - **Organization-scoped feed**: + + ```xml + + + + + + + + ``` + +::: moniker-end + +::: moniker range="azure-devops-2020 || azure-devops-2022" + +1. Sign in to your Azure DevOps collection, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to Feed**, and then select **dotnet** from the left navigation pane. + +1. Follow the instructions in the **Project setup** section to configure your *nuget.config* file and connect to your feed. + + :::image type="content" source="media/connect-to-feed-dotnet-server-2020-and-2022.png" alt-text="A screenshot that shows how to connect to a feed with dotnet in Azure DevOps Server 2020 and 2022."::: + +::: moniker-end + +> [!TIP] +> You can ask GitHub Copilot, "how to add a new package source to an existing *nuget.config* file". Copilot will guide you through using the `nuget sources Add` command to add your new feed source URL to your *nuget.config* file. + +## Publish packages + +Run the following command from your project directory to publish your package. The ApiKey is required, but you can use any string value when publishing to an Azure Artifacts feed. + +```dotnetcli +dotnet nuget push --source --api-key az +``` + +## Next steps + +> [!div class="nextstepaction"] +> [Monitor Artifacts storage](artifact-storage.md) +> [Share packages publicly](tutorials/share-packages-publicly.md) +> [Manage permissions](feeds/feed-permissions.md) diff --git a/docs/artifacts/get-started-cargo.md b/docs/artifacts/get-started-cargo.md new file mode 100644 index 00000000000..8104c6ef715 --- /dev/null +++ b/docs/artifacts/get-started-cargo.md @@ -0,0 +1,113 @@ +--- +title: Get started with Cargo packages in Azure Artifacts +description: How to use Azure Artifacts to publish and download Cargo packages. +ms.service: azure-devops-artifacts +ms.topic: quickstart +ms.date: 07/11/2023 +monikerRange: '>= azure-devops-2022' +"recommendations": "true" +--- + +# Get started with Cargo packages in Azure Artifacts + +[!INCLUDE [version-gt-eq-2022](../includes/version-gt-eq-2022.md)] + +Using Azure Artifacts, you can publish and download Cargo packages to feeds and public registries. This article guides you through setting up your project and publishing your Cargo packages to your Azure Artifacts feed. + +## Prerequisites + +- An Azure DevOps organization and a project. Create an [organization](../organizations/accounts/create-organization.md) or a [project](../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- Download and install [rustup](https://rustup.rs/). + +## Create a feed + +If you already have an existing Azure Artifacts feed that can be used for Cargo you can jump to the next section. + +> [!NOTE] +> Azure Artifacts recommends using a distinct feed for consuming crates from crates.io, and a separate feed exclusively for publishing internal crates. + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select **Create Feed**. + +1. Give your feed a **Name** and specify its **Visibility**. Check the **Upstream sources** checkbox if you want to include packages from public registries and then select a **Scope** for your feed. + +1. Select **Create** when you're done. + +## Connect to a feed + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **Cargo** from the tool selection pane. + +1. Follow the **Project setup** instructions on the **Connect to feed** page. + +::: moniker range="azure-devops" + +> [!IMPORTANT] +> Cargo support in Azure Artifacts requires rust version [1.74](https://rustup.rs/) or newer which includes support for the 'registry-auth' feature. +> To update your rust version, run `rustup update` + +::: moniker-end + +::: moniker range="azure-devops-2022" + +> [!IMPORTANT] +> Cargo is currently in preview and may require the [nightly toolchain](https://rust-lang.github.io/rustup/concepts/toolchains.html) with the `registry-auth` [unstable-feature](https://doc.rust-lang.org/cargo/reference/unstable.html) enabled. To enable `registry-auth`, add the following to [.cargo/config.toml](https://doc.rust-lang.org/cargo/reference/config.html). +> +> ``` +> [unstable] +> registry-auth = true +> ``` +> +> To use the nightly toolchain, run the following command: +> +> ``` +> rustup default nightly +> ``` + +::: moniker-end + +## Publish packages + +To publish your Cargo package, run the following command in your project directory: + +``` +cargo publish +``` + +If you encounter `GLib-GObject-CRITICAL - libsecret-CRITICAL` error, make sure you follow these steps: + +1. Verify *libsecret* is installed: + + ``` + sudo apt update && sudo apt install libsecret-1-0 + ``` + +1. Make sure *gnome-keyring* is running: + + ``` + gnome-keyring-daemon --start --components=secrets + ``` + +1. Update Rust to the latest stable version and set stable as the default toolchain: + + ``` + rustup update + rustup default stable + ``` + +1. You should also run cargo publish with verbose logging to get more details: + + ``` + RUST_LOG=debug cargo publish --registry + ``` + +## Related articles + +- [Feed permissions](feeds/feed-permissions.md) +- [Delete/Yank Cargo packages](how-to/delete-and-recover-packages.md?tabs=cargo) +- [Promote a package to a view](feeds/views.md) diff --git a/docs/artifacts/get-started-maven.md b/docs/artifacts/get-started-maven.md index 6b89a7151a2..118c6b8b009 100644 --- a/docs/artifacts/get-started-maven.md +++ b/docs/artifacts/get-started-maven.md @@ -1,42 +1,70 @@ --- title: Get started with Maven packages -description: learn how to publish and download Maven artifacts +description: Learn how to publish and restore Maven packages with Azure Artifacts. ms.service: azure-devops-artifacts ms.topic: quickstart ms.assetid: C5112218-DA7E-4016-986D-2D0F70DAFA44 -ms.date: 05/06/2022 +ms.date: 07/01/2024 monikerRange: '<= azure-devops' --- -# Get started with Maven packages and Azure Artifacts +# Get started with Maven packages in Azure Artifacts [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -This quickstart will guide you through setting up your Maven project to connect to Azure Artifacts feeds and publish and download your Maven packages. +Azure Artifacts enables developers to manage their dependencies from a single feed while providing control over package sharing. With Azure Artifacts feeds, you can publish and restore Maven packages, and set up upstream sources to consume packages from public registries like Maven Central, Google Maven Repository, Gradle Plugins, and JitPack. This article will guide you through setting up your Maven project, connecting to an Azure Artifacts feed, and publishing and restoring your Maven packages. -### Prerequisites +## Prerequisites -- An Azure DevOps organization. [Create an organization](../organizations/accounts/create-organization.md), if you don't have one already. -- [Install Apache Maven](https://maven.apache.org/download.cgi). -- An Azure Artifacts feed. [Create a feed](./concepts/feeds.md#create-public-feeds.) if you don't have one already. +- Create an Azure DevOps [organization](../organizations/accounts/create-organization.md) and a [project](../organizations/projects/create-project.md#create-a-project) if you haven't already. -## Set up authentication +- [Download](https://maven.apache.org/download.cgi) and [Install](https://maven.apache.org/install.html) Apache Maven. + +## Create a feed + +[!INCLUDE [](includes/create-feed.md)] + +## Connect to a feed [!INCLUDE [](includes/maven/pom-and-settings.md)] -> [!TIP] -> If you are using [Maven task](/azure/devops/pipelines/tasks/reference/maven-v3), set the `mavenAuthenticateFeed` argument to true to automatically authenticate with your Maven feed. +## Publish packages + +1. Open a command prompt window and navigate to your project directory where your *pom.xml* file is located, and then run the following command to package your project. This command compiles your code, runs tests included, and packages your project into a distributable format (such as a JAR file). + + ``` + mvn package + ``` + +1. Run the following command from your project directory to publish your package to your feed: + + ``` + mvn deploy + ``` + +1. After successfully deploying your package, it will shortly be available in your feed. + + :::image type="content" source="media/get-started-maven/maven-package-published-to-feed-contracted.png" alt-text="A screenshot that shows a Maven package deployed to a feed." lightbox="media/get-started-maven/maven-package-published-to-feed.png"::: + +> [!NOTE] +> If your organization is using a firewall or a proxy server, make sure you allow [Azure Artifacts Domain URLs and IP addresses](../organizations/security/allow-list-ip-url.md#azure-artifacts). + +## Restore packages + +1. Navigate to **Artifacts** in your Azure DevOps project, select your feed from the dropdown menu, and then select the package you wish to install. -## Publish artifacts +1. Navigate to **Overview** > **Maven**, then copy the dependency snippet. -[!INCLUDE [](includes/maven/publish.md)] +1. Open your *pom.xml* file and paste the snippet inside the `` tag. -## Install artifacts +1. Run the following command from the directory where your *pom.xml* file is located to restore your packages: -[!INCLUDE [](includes/maven/install.md)] + ``` + mvn install + ``` ## Related articles -- [Configure permissions](./feeds/feed-permissions.md) -- [Use feed views to share packages](./feeds/views.md) -- [Set up upstream sources](./how-to/set-up-upstream-sources.md) +- [Publish Maven artifacts with Azure Pipelines](../pipelines/artifacts/publish-maven-artifacts.md) +- [Use packages from Maven Central](maven/upstream-sources.md) +- [Use upstream sources in a public feed](how-to/public-feeds-upstream-sources.md) diff --git a/docs/artifacts/get-started-npm.md b/docs/artifacts/get-started-npm.md index 70ecc5e5faa..08c3d6cbe3c 100644 --- a/docs/artifacts/get-started-npm.md +++ b/docs/artifacts/get-started-npm.md @@ -1,11 +1,10 @@ --- -title: publish and download npm packages -description: How to set up your .npmrc config file to publish and download npm packages +title: Publish and download npm packages +description: Learn how to set up your project to manage your npm packages in Azure Artifacts. ms.service: azure-devops-artifacts ms.topic: quickstart ms.assetid: 5BFBA0C3-85ED-40C9-AC5F-F686923160D6 -ms.custom: contperf-fy20q4, conterperfq3, contperf-fy21q3 -ms.date: 04/13/2022 +ms.date: 05/28/2024 monikerRange: '<= azure-devops' "recommendations": "true" --- @@ -14,148 +13,71 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -With Azure Artifacts, you can publish and download npm packages from feeds and public registries such as npmjs.com. This quickstart will guide you through creating your own feed, setting up your project, and publishing and downloading npm packages to and from your Azure Artifacts feed. +Using Azure Artifacts, you can publish and download your npm packages from feeds and public registries such as npmjs.com. This quickstart will guide you through creating your feed, configuring your project, and managing npm packages with your Azure Artifacts feed. -::: moniker range="tfs-2018" +## Prerequisites -## License the Azure Artifacts extension +- An Azure DevOps organization. [Create one for free](../organizations/accounts/create-organization.md). -To use Azure Artifacts in TFS, you must upgrade to Visual Studio Team Foundation Server 2017. If the Azure Artifacts extension has been removed, you can install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms.feed). +- An Azure DevOps project. Create a new [project](../organizations/projects/create-project.md#create-a-project) if you don't have one already. -### Assign licenses in Team Foundation Server - -Each organization gets five free licenses. If you need more than five licenses, go to the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms.feed), and select **Get it free**. - -If you aren't sure, you can select **Start 30-day free trial**. Every user in your organization is then granted access to Azure Artifacts for 30 days. After the 30-day trial period, your organization reverts back to five entitled users, and you must assign licenses to individual users. If you need additional licenses at this point, you can purchase them from Visual Studio Marketplace. If you have a license for Visual Studio Enterprise, you already have access to Azure Artifacts and don't need to be assigned a license. Just ensure that you've been assigned the "Visual Studio Enterprise" access level. - -> [!NOTE] -> If you selected **Start 30 day free trial** and are still in the trial period, every user is granted access. Licenses don't need to be assigned until the trial period ends. - -1. From any collection in Team Foundation Server, hover over the settings menu and select **Users**. Then select **Package Management**. - - :::image type="content" source="media/users-hub-tfs.png" alt-text="Screenshot showing the user page in TFS"::: - -1. Select **Assign**, enter the users you want to assign licenses, and then select **OK**. - - * Users with Visual Studio Enterprise subscriptions get Azure Artifacts for free. Make sure that your Visual Studio Enterprise subscribers have the appropriate access level. For more information, see [Change access levels](../organizations/security/change-access-levels.md). - - * Users who are using an instance of Team Foundation Server that's disconnected from the internet (and thus can't purchase licenses from Visual Studio Marketplace) can still assign licenses purchased through an enterprise agreement. - -::: moniker-end +- [Download and install Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). ## Create a feed -A feed is an organizational construct that allows users to store their packages and control who can access them. Azure Artifacts support storing several package types in a single feed such as NuGet, npm, Maven, Python, and Universal packages. - [!INCLUDE [](includes/create-feed.md)] -::: moniker range="azure-devops" - -## Set up your .npmrc files +## Connect to a feed > [!NOTE] -> `vsts-npm-auth` is not supported in TFS and Azure DevOps Server. - -We recommend having two .npmrc files. The first one should be placed in the same directory as your package.json file. The second one should be placed in the **$home** directory (Linux/macOS) or **$env.HOME** (Windows) to store your credentials. The npm client then will be able to look up this file and fetch your credentials for authentication. This enables you to share your config file while keeping your credentials secure. - -1. Select **Artifacts**, and then select **Connect to feed**. - - :::image type="content" source="media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot showing how to connect to a feed"::: - -1. Select **npm**. If this is your first time using Azure Artifacts, select **Get the tools** and then follow the steps to download Node.js and set up the credential provider. - -1. Follow the instructions in the **Project setup** to set up your project. - - :::image type="content" source="media/npm-azure-devops-newnav.png" alt-text="Screenshot showing how to set up your project"::: +> `vsts-npm-auth` is not supported in Azure DevOps Server. -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -### Set up authentication on your development machine - -> [!IMPORTANT] -> npm supports a single `registry` in your .npmrc file. Multiple registries are possible with [scopes](npm/scopes.md) and [upstream sources](npm/upstream-sources.md). +Azure Artifacts recommends using two .npmrc files. The first one should be placed in the *$home* directory (Linux/macOS) or *$env.HOME* (Windows) to securely store your credentials. This allows the npm client to locate the file and retrieve your credentials for authentication, enabling you to share your config file without exposing your credentials. In this section, we will set up the second *.npmrc* file, which should be placed in the same directory as your *package.json* file. -#### [Windows](#tab/Windows/) +::: moniker range="azure-devops" -If you're developing on Windows, we recommend using `vsts-npm-auth` to authenticate with Azure Artifacts. Run `npm install -g vsts-npm-auth` to install the package globally and then add a run script to your package.json. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -```JSON -"scripts": { - "refreshVSToken": "vsts-npm-auth -config .npmrc" -} -``` - -#### [Other](#tab/Other/) - -To authenticate with Azure Artifacts, we have to create a personal access token and add it to our .npmrc file. +1. Select **Artifacts**, and then select **Connect to feed**. -1. Copy the following code snippet to your .npmrc file. +1. Select **npm** from the left navigation area. If this is your first time using Azure Artifacts with npm, make sure you've installed the prerequisites. - - **Organization-scoped feed**: +1. Follow the instructions in the **Project setup** section to set up your config file and connect to your feed. - ```Command - ; begin auth token - //pkgs.dev.azure.com//_packaging//npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING] - //pkgs.dev.azure.com//_packaging//npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] - //pkgs.dev.azure.com//_packaging//npm/registry/:email=npm requires email to be set but doesn't use the value - //pkgs.dev.azure.com//_packaging//npm/:username=[ANY_VALUE_BUT_NOT_AN_EMPTY_STRING] - //pkgs.dev.azure.com//_packaging//npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] - //pkgs.dev.azure.com//_packaging//npm/:email=npm requires email to be set but doesn't use the value - ; end auth token - ``` - - - **Project-scoped feed**: + :::image type="content" source="media/npm-project-setup-azure-devops.png" alt-text="A screenshot that shows how to set up an npm project and connect to an Azure Artifacts feed in Azure DevOps Services."::: - ```Command - ; begin auth token - //pkgs.dev.azure.com///_packaging//npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING] - //pkgs.dev.azure.com///_packaging//npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] - //pkgs.dev.azure.com///_packaging//npm/registry/:email=npm requires email to be set but doesn't use the value - //pkgs.dev.azure.com///_packaging//npm/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING] - //pkgs.dev.azure.com///_packaging//npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] - //pkgs.dev.azure.com///_packaging//npm/:email=npm requires email to be set but doesn't use the value - ; end auth token - ``` +::: moniker-end -1. Generate a [personal access token](../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **packaging read and write** scopes. +::: moniker range="azure-devops-2022" -1. Encode your newly generated personal access token as follows: +1. Sign in to your Azure DevOps collection, and then navigate to your project. - 1. Run the following command in an elevated command prompt window. - - ```Command - node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })" - ``` +1. Select **Artifacts**, and then select **Connect to Feed**. - 1. Paste your personal access token, and then press **Enter**. - - 1. Copy the Base64 encoded value. +1. Select **npm** from the left, and then follow the instructions in the **Project setup** section to connect to your feed. -1. Replace the `[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]` placeholder in your .npmrc file with your Base64 personal access token. + :::image type="content" source="media/npm-project-setup-server-2022-1.png" alt-text="A screenshot that shows how to set up an npm project and connect to an Azure Artifacts feed in Azure DevOps Server 2022."::: ::: moniker-end -* * * +::: moniker range="azure-devops-2020" -::: moniker range="tfs-2018" +1. Sign in to your Azure DevOps collection, and then navigate to your project. -## Connect to feed - -1. Select **Packages**, and then select **Connect to feed**. - -2. Select **npm**. +1. Select **Artifacts**, and then select **Connect to feed**. -3. Select **Generate npm credentials**. Copy the credentials and add them to your .npmrc file. +1. Select **npm** from the left, and then follow the instructions in **Project setup** to set up your config file and connect to your feed. - :::image type="content" source="./media/tfs2018-connect-to-npm-feed.png" alt-text="Screenshot showing how generate credentials"::: + :::image type="content" source="media/npm-project-setup-server-2020-1.png" alt-text="A screenshot that shows how to set up an npm project and connect to an Azure Artifacts feed in Azure DevOps Server 2020."::: ::: moniker-end +> [!IMPORTANT] +> npm supports a single `registry` in your .npmrc file. Multiple registries are possible with [scopes](npm/scopes.md) and [upstream sources](npm/upstream-sources.md). + ## Publish packages -To publish your npm package, run the following command in your project directory +Run the following command in your project directory to publish your npm packages: ```Command npm publish @@ -166,16 +88,20 @@ npm publish ## Restore packages -To restore an npm package, run the following command in your project directory +Run the following command in your project directory to restore your npm packages: + +```Command +npm install +``` + +To restore a specific npm package, run the following command from your project directory: ```Command -npm install --save +npm install --save ``` -## Next steps +## Related articles -> [!div class="nextstepaction"] -> [Publish npm packages (YAML/Classic)](../pipelines/artifacts/npm.md) -> [Use packages from npmjs.com](./npm/upstream-sources.md) -> [Use npm scopes](npm/scopes.md) -> [Use npm audit](npm/npm-audit.md) +- [Publish npm packages (YAML/Classic)](../pipelines/artifacts/npm.md) +- [Use packages from npmjs.com](./npm/upstream-sources.md) +- [Use npm scopes](npm/scopes.md) diff --git a/docs/artifacts/get-started-nuget.md b/docs/artifacts/get-started-nuget.md index 3b1f5c9bf53..f5692682f92 100644 --- a/docs/artifacts/get-started-nuget.md +++ b/docs/artifacts/get-started-nuget.md @@ -1,78 +1,75 @@ --- -title: Get started with NuGet packages and Azure Artifacts -description: Use Azure Artifacts to publish and download NuGet packages from your feeds +title: "Quickstart: Get started with NuGet packages and Azure Artifacts" +description: Learn how to use Azure Artifacts to publish and download NuGet packages from your feed. ms.service: azure-devops-artifacts -ms.custom: contperf-fy21q3 ms.topic: quickstart +ms.author: rabououn +author: ramiMSFT ms.assetid: C5112218-DA7E-4016-986D-2D0F70DAFA44 -ms.date: 06/08/2023 +ms.date: 05/14/2024 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Get started with NuGet packages in Azure Artifacts +# Quickstart: Get started with NuGet packages in Azure Artifacts [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Azure Artifacts enables developers to publish and download NuGet packages from different sources such as feeds and public registries. With Azure Artifacts, you can create feeds that can be either private, allowing you to share packages with your team and specific users, or public, enabling you to share them openly with anyone on the internet. +Azure Artifacts enables developers to publish and download NuGet packages from sources such as feeds and public registries. With Azure Artifacts, you can create feeds that are either: -In this article, you'll learn how to: +* Private, so you can share packages with your team and specific users. +* Public, so you can share packages openly with anyone on the internet. -> [!div class="checklist"] -> * Create a new feed -> * Set up your project and connect to your feed -> * Publish NuGet packages -> * Download packages from your feed +In this quickstart, you learn how to: -## Prerequisites +> [!div class="checklist"] +> +> * Create a new feed. +> * Set up your project and connect to your feed. +> * Publish NuGet packages. +> * Download packages from your feed. -- An Azure DevOps organization and a project. Create an [organization](../organizations/accounts/create-organization.md) or a [project](../organizations/projects/create-project.md#create-a-project) if you haven't already. +## Prerequisites -- Install the [latest NuGet version](https://www.nuget.org/downloads). +* Create an Azure DevOps [organization](../organizations/accounts/create-organization.md) and a [project](../organizations/projects/create-project.md#create-a-project) if you haven't already. -- Install [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider). +* Install the [latest NuGet version](https://www.nuget.org/downloads). -## Create a feed +* Install the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider). -Azure Artifacts offers two types of feeds: project-scoped feeds and organization-scoped feeds. if you want to create a public feed, begin by creating a project-scoped feed, and then adjust the visibility settings of the project hosting your feed to public. This will effectively make your project-scoped feed accessible to the public. +## Create a feed [!INCLUDE [](includes/create-feed.md)] -## Connect to feed +## Connect to a feed -::: moniker range=">= azure-devops-2019" +::: moniker range="azure-devops" -1. Sign in to your Azure DevOps organization, and then navigate to your project. +1. Sign in to your Azure DevOps organization, and then go to your project. 1. Select **Artifacts**, and then select your feed from the dropdown menu. -1. Select **Connect to feed**. +1. Select **Connect to Feed**, and then select **NuGet.exe** from the left pane. If this is your first time using Azure Artifacts with *Nuget.exe*, ensure that you installed all the prerequisites. - :::image type="content" source="./media/connect-to-feed-azure-devops-newnav.png" alt-text="A screenshot showing the connect to feed button."::: + :::image type="content" source="./media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot that shows the button for connecting to a feed."::: -1. Select **NuGet.exe**. If this is the first time using Azure Artifacts with Nuget.exe, ensure that you have installed all the prerequisites. +1. Follow the instructions in the **Project setup** section to configure your *nuget.config* file and authenticate with Azure Artifacts. -1. Follow the instructions provided in the **Project setup** section to configure your nuget.config file. - - :::image type="content" source="./media/project-setup.png" alt-text="A screenshot showing how to set up your project."::: + :::image type="content" source="./media/project-setup.png" alt-text="Screenshot that shows onscreen instructions for setting up a project."::: ::: moniker-end -::: moniker range="tfs-2018" - -1. Navigate to your project `http://ServerName:8080/tfs/DefaultCollection/`. +::: moniker range="azure-devops-2020 || azure-devops-2022" -1. Select **Build and Release** > **Packages**. +1. Sign in to your Azure DevOps server, and then go to your project. -1. Select your feed from the dropdown menu. - -1. Select **Connect to feed**. +1. Select **Artifacts**, and then select your feed from the dropdown menu. - :::image type="content" source="./media/connect-to-feed.png" alt-text="A screenshot showing the connect to feed button in TFS."::: +1. Select **Connect to Feed**, and then select **NuGet.exe** from the left pane. -1. Select **NuGet**, and then follow the instruction to connect to your feed. +1. Follow the instructions in the **Project setup** section to connect to your feed. - :::image type="content" source="./media/connect-to-nuget-feed-tfs.png" alt-text="A screenshot showing how to connect to your feed in TFS."::: + :::image type="content" source="./media/connect-to-feed-nuget-server-2020.png" alt-text="Screenshot that shows onscreen instructions for setting up a NuGet project in Azure DevOps Server 2020 and 2022."::: ::: moniker-end @@ -80,19 +77,40 @@ Azure Artifacts offers two types of feeds: project-scoped feeds and organization [!INCLUDE [](includes/nuget/consume.md)] +::: moniker range="azure-devops" + > [!NOTE] -> Using NuGet Package Explorer to search for packages in upstreams is not supported. +> Using NuGet Package Explorer to search for packages in upstream sources is not supported. + +::: moniker-end ## Publish packages -Run the following command to publish your package to your feed. You can use any string for the *ApiKey* argument. +To publish your package to your feed, run the following command. You can enter any string for the `ApiKey` argument. ```Command nuget.exe push -Source -ApiKey key ``` -## Related articles +**Examples:** + +- Project-scoped feed: + + ```CLI + nuget.exe push -Source https://pkgs.dev.azure.com/myOrganization/MyProject/_packaging/MyFeed/nuget/v3/index.json -ApiKey AZ release/myDemoPackage.1.0.0.nupkg + ``` + +- Organization-scoped feed: + + ```CLI + nuget.exe push -Source https://pkgs.dev.azure.com/myOrganization/_packaging/myFeed/nuget/v3/index.json -ApiKey AZ release/myDemoPackage.1.0.0.nupkg + ``` + +> [!NOTE] +> The `ApiKey` is required, but you can use any arbitrary value when publishing to Azure Artifacts feeds. + +## Related content -- [Publish NuGet packages with Azure Pipelines](../pipelines/artifacts/nuget.md) -- [Publish packages to NuGet.org](./nuget/publish-to-nuget-org.md) -- [NuGet.org upstream source](./nuget/upstream-sources.md) \ No newline at end of file +* [Publish NuGet packages with Azure Pipelines (YAML/classic)](../pipelines/artifacts/nuget.md) +* [Publish packages to NuGet.org](./nuget/publish-to-nuget-org.md) +* [Use packages from NuGet Gallery](./nuget/upstream-sources.md) diff --git a/docs/artifacts/how-to/delete-and-recover-packages.md b/docs/artifacts/how-to/delete-and-recover-packages.md index 2bb122b38a5..a1004de0fb8 100644 --- a/docs/artifacts/how-to/delete-and-recover-packages.md +++ b/docs/artifacts/how-to/delete-and-recover-packages.md @@ -1,11 +1,11 @@ --- title: Delete and recover packages -description: Learn how to delete packages manually and with retention policies, and how to recover deleted packages from the Recycle Bin. +description: Learn how to manually delete packages, set up retention policies, and recover deleted packages from the Recycle Bin. ms.service: azure-devops-artifacts ms.assetid: 10f5e81f-2518-41b9-92b6-e00c905b59b3 -ms.custom: contperf-fy21q2, contperf-fy22q1 -ms.topic: conceptual -ms.date: 02/16/2022 +ms.custom: peer-review-program +ms.topic: how-to +ms.date: 03/13/2025 monikerRange: '<= azure-devops' "recommendations": "true" --- @@ -14,292 +14,239 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Azure Artifacts safely stores different types of packages in your feed, whether you published them directly or saved them from upstream sources. As older package versions fall out of use, you might want to clean them up either manually or automatically by using retention policies. +Azure Artifacts securely stores various package types in a feed, whether published directly or saved from upstream sources. As older package versions become less relevant, you can remove them manually or by using retention policies to free up space and reduce costs. -In this article, you'll learn how to: +## Prerequisites -> [!div class="checklist"] -> * Delete packages from feeds. -> * Set up retention policies to automatically delete older packages. -> * Recover recently deleted packages from the Recycle Bin. - -> [!NOTE] -> You must be a feed **Owner** or **Administrator** to delete packages or set up retention policies. +| **Product** | **Requirements** | +|--------------------|----------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An [Azure Artifacts feed](../start-using-azure-artifacts.md#create-a-new-feed).
- **Permissions:**
    - You must be a [Feed Owner](../feeds/feed-permissions.md#permissions-table) to set up retention policies, delete packages and feeds, or restore packages from the recycle bin.
    - You must be a [Feed Publisher (Contributor)](../feeds/feed-permissions.md#permissions-table) or higher to unlist, deprecate, or yank packages. | ## Delete packages -In Azure Artifacts, packages are immutable. When you publish a package to your feed, its version number will be reserved permanently. You can't upload a new package with that same version number, even if you delete it from your feed. +In Azure Artifacts, packages are immutable, meaning their version numbers cannot be reused or modified after publishing. Once you publish a package to a feed, its version number is permanently reserved. Even if you delete the package, its version remains recorded in the feed’s history, and you cannot publish a new package with the same version number. #### [NuGet](#tab/nuget/) -Two options are available to delete a NuGet package from your feed, [Unlist](#qa) and [Delete](#qa). +There are two ways to remove a NuGet package from a feed: [Unlist](#qa) and [Delete](#qa). Unlisting a package version hides it from search results in Azure Artifacts feeds and on *NuGet.org*. Deleting a package version moves it to the recycle bin and makes it unavailable for installation. -> [!NOTE] -> You must be a **Contributor** to unlist a package and an **Owner** to delete it. +::: moniker range="<=azure-devops" -::: moniker range=">= azure-devops-2019" +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Artifacts**, and then select your feed. +1. Select **Artifacts**, and then select your feed from the dropdown menu. -1. Select the package that you want to delete or deprecate, and then select **Unlist** or **Delete latest**. +1. Select the package you want to delete, then select **Unlist** to hide it from search results in Azure Artifacts feeds and on *NuGet.org*, or **Delete** to move it to the recycle bin. - :::image type="content" source="../media/delete/unlist-delete-nuget-package-newnav.png" alt-text="Screenshot that shows buttons for unlisting and deleting NuGet packages."::: + :::image type="content" source="../media/delete/unlist-delete-nuget-package-newnav.png" alt-text="A screenshot displaying how to delete or unlist a NuGet package in Azure Artifacts."::: ::: moniker-end -::: moniker range="tfs-2018" - -1. Select **Build and Release**. - -1. Select **Packages**, and then select the package that you want to delete. - -1. Select **Unlist** or **Delete latest**. - - :::image type="content" source="../media/delete/unlist-delete-nuget-package.png" alt-text="Screenshot that shows the buttons for unlisting and deleting NuGet packages in Team Foundation Server."::: - -::: moniker-end - -### Unlist a NuGet package by using NuGet.exe - -1. Select **Artifacts**, and then go to your feed. Select **Connect to feed**. - - ::: moniker range=">= azure-devops-2019" - - :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot that shows the button for connecting to a feed."::: +### Unlist packages (CLI) - ::: moniker-end +1. Sign in to your Azure DevOps organization, then navigate to your project. - ::: moniker range="tfs-2018" +1. Select **Artifacts**, then select your feed from the dropdown menu. - :::image type="content" source="../media/connect-to-feed.png" alt-text="Screenshot that shows the button for connecting to a feed in Team Foundation Server."::: +1. Select **Connect to feed** > **NuGet.exe**, then find and copy your **Package Source** URL. It should follow this format: `https://pkgs.dev.azure.com/OrganizationName/ProjectName/_packaging/FeedName/nuget/v3/index.json`. - ::: moniker-end - -2. Select **NuGet.exe**, and then find and copy your **Package Source** URL. - -3. Run the following command: +1. Run the following command to unlist your package. The **ApiKey** argument is required but is treated as a placeholder when publishing to an Azure Artifacts feed, so you can use any string value: ```Command - nuget.exe delete -Source -ApiKey + nuget.exe delete -Source -ApiKey ``` -> [!NOTE] -> Azure DevOps and Visual Studio Team Foundation Server interpret the `nuget.exe delete` command as an unlist operation. To delete a package, you must use the [REST API](/rest/api/azure/devops/artifactspackagetypes/nuget/delete-package-version) or the web interface. +> [!IMPORTANT] +> Azure DevOps interprets the `nuget.exe delete` command as an unlisting operation. This means that running the command does not delete the package, but instead hides it from search results in Azure Artifacts feeds and on NuGet.org. To delete a package from your feed, you must use the [REST API](/rest/api/azure/devops/artifactspackagetypes/nuget/delete-package-version) or delete it manually from the web interface. #### [npm](#tab/npm/) -There are two options to delete an npm package from your feed, [Deprecate](#qa) and [Unpublish](#qa). +There are two ways to remove an npm package from a feed: [Deprecate](#qa) or [Delete](#qa) them. Deprecating a package adds a warning message to its metadata, which will be displayed whenever the package is viewed or installed. Deleting a package version, on the other hand, moves it to the recycle bin and makes it unavailable for installation. -> [!NOTE] -> You must be a **Contributor** to deprecate a package and an **Owner** to unpublish it. +::: moniker range="<=azure-devops" -::: moniker range=">= azure-devops-2019" +1. Sign in to your Azure DevOps organization, then navigate to your project. -1. Select **Artifacts**, and then select your feed. +1. Select **Artifacts**, then select your feed from the dropdown menu. -1. Select the package that you want to delete or deprecate, and then select **Deprecate** or **Unpublish latest**. +1. Select the package you want to delete, then select **Deprecate** or **Delete**. - :::image type="content" source="../media/delete/deprecate-unpublish-npm-package-newnav.png" alt-text="Screenshot that shows the buttons for deprecating and unpublishing."::: + :::image type="content" source="../media/npm-deprecate-delete.png" alt-text="A screenshot displaying how to deprecate or delete an npm package in Azure Artifacts."::: ::: moniker-end -::: moniker range="tfs-2018" +### Deprecate or delete packages (CLI) -1. Select **Build and Release**. +1. [Set up your project's .npmrc](../npm/npmrc.md). -1. Select **Packages**, and then select the package that you want to delete. - -1. Select **Deprecate** or **Unpublish latest**. - - :::image type="content" source="../media/delete/deprecate-unpublish-npm-package.png" alt-text="Screenshot that shows the buttons for deprecating and unpublishing in Team Foundation Server."::: - -::: moniker-end - -#### Deprecate or unpublish an npm package by using the CLI - -1. [Set up your client's .npmrc file](../npm/npmrc.md). - -1. Use the following command to deprecate an npm package: +1. Use the following command to deprecate a package: ```Command npm deprecate [@] ``` - Use the following command to unpublish an npm package: +1. If you want to delete your package, run the following command. Keep in mind that the `npm unpublish` command does not remove all versions of the package: ```Command npm unpublish @ ``` -> [!NOTE] -> The `npm unpublish` command won't unpublish all versions of the package. For more information, see the [deprecate](https://docs.npmjs.com/cli/deprecate) or [unpublish](https://docs.npmjs.com/cli/unpublish) documentation. - #### [Python](#tab/python/) -1. Select **Artifacts**, and then select your feed. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select the package that you want to delete, and then select **Delete latest**. +1. Select **Artifacts**, and then select your feed from the dropdown menu. -> [!NOTE] -> You must be a feed **Owner** to delete a Python package. +1. Select the package you want to delete, and then select **Delete**. -:::image type="content" source="../media/delete/delete-python-package.png" alt-text="Screenshot that shows the button for deleting a package in Python."::: + :::image type="content" source="../media/python-delete-package.png" alt-text="A screenshot displaying how to delete a Python package in Azure Artifacts." lightbox="../media/python-delete-package.png"::: #### [Maven](#tab/maven/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -1. Select **Artifacts**, and then select your feed. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select the package that you want to delete, and then select **Delete latest**. Select **Delete** to confirm. +1. Select **Artifacts**, and then select your feed from the dropdown menu. -::: moniker-end +1. Select the package you want to delete, and then select **Delete**. -::: moniker range="tfs-2018" +1. Select **Delete** again to confirm your choice. -1. Select **Build and Release**, and then select **Packages**. + :::image type="content" source="../media/maven-delete-package.png" alt-text="A screenshot displaying how to delete a Maven package in Azure Artifacts."::: -1. Select your feed, and then select the package that you want to delete. +::: moniker-end -1. Select **Delete latest** to delete the latest version of your package. +#### [Universal Packages](#tab/universal/) - :::image type="content" source="../media/delete/delete-maven-package.png" alt-text="Screenshot that shows the button to delete packages from feeds."::: +1. Sign in to your Azure DevOps organization, and then navigate to your project. -::: moniker-end +1. Select **Artifacts**, and then select your feed from the dropdown menu. -#### [Universal Package](#tab/universal/) +1. Select the package you want to delete, and then select **Delete**. -1. Select **Artifacts**, and then select your feed. + :::image type="content" source="../media/universal-package-delete-package.png" alt-text="A screenshot displaying how to delete a Universal Package in Azure Artifacts."::: -1. Select the package that you want to delete, and then select **Delete latest**. +#### [Cargo](#tab/cargo/) -> [!NOTE] -> You must be a feed **Owner** to delete a Universal Package. +There are two ways to remove a Cargo package from a feed: [Yank](#qa) and [Delete](#qa). Yanking a package version marks it as deprecated or unusable, discouraging its use, though it doesn't actually delete the package. Deleting a package version, on the other hand, moves it to the recycle bin and makes it unavailable for installation. -:::image type="content" source="../media/delete/delete-universal-package.png" alt-text="Screenshot that shows the button for deleting a Universal Package."::: +1. Sign in to your Azure DevOps organization, then navigate to your project. -* * * +1. Select **Artifacts**, then select your feed from the dropdown menu. -> [!NOTE] -> Packages sent to the Recycle Bin will be deleted permanently after 30 days. However, these packages still count as part of your storage bill. If you want to delete them sooner, go to the Recycle Bin and delete them manually. +1. Select the package you wish to delete, and then select **Yank** to mark it as deprecated or **Delete** to move it to the recycle bin. -## Delete packages automatically with retention policies + :::image type="content" source="../media/delete-cargo-package.png" alt-text="A screenshot displaying how to delete or yank a Cargo package."::: -The number of versions for each package hosted in your feed can grow quickly. To free up storage space, you can set up retention policies to automatically delete old packages. +* * * -If you want to retain a package indefinitely, you can promote it to a [view](../concepts/views.md). Packages promoted to a view are exempt from retention policies and won't be deleted. +## Delete packages permanently -> [!NOTE] -> Package demotion is not supported. If you want this feature to be added to future releases, feel free to use **Suggest a feature** on our [Azure DevOps Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html) page. +Packages in the recycle bin are automatically deleted after 30 days, but they still count toward your storage usage during this period. To remove them sooner, you can manually delete them from the Recycle Bin by following these steps: -To configure retention policies: +1. Sign in to your Azure DevOps organization, and then navigate to your project. -::: moniker range=">= azure-devops-2019" +1. Select **Artifacts**, then select your feed from the dropdown menu. -1. Select **Artifacts**. +1. In the upper-right corner, select **Recycle Bin**. - :::image type="content" source="../media/goto-feed-hub-azure-devops-newnav.png" alt-text="Screenshot that shows the Artifacts button."::: +1. Select the package you want to delete permanently, then select **Permanently Delete**. -1. Select the gear icon to navigate to your feed's settings. + :::image type="content" source="../media/delete/delete-package-permanently.png" alt-text="A screenshot displaying how to permanently delete a package in Azure Artifacts."::: - :::image type="content" source="../media/feed-settings.png" alt-text="A screenshot showing how to navigate to feed settings."::: +1. Select **Permanently Delete** again to confirm your decision. Your package will be deleted permanently. -1. Select **Feed details**, and then select the **Enable package retention** checkbox. Then enter values for: + :::image type="content" source="../media/delete/delete-package-permanently-confirmation.png" alt-text="A screenshot displaying a confirmation message before you delete a package permanently."::: - - **Maximum number of versions per package**: How many versions of a package you want to keep. - - **Days to keep recently downloaded packages**: Packages will be deleted only if they haven't been downloaded for the number of days set in here. +## Delete packages automatically with retention policies - :::image type="content" source="../media/retention-policy-settings.png" alt-text="Screenshot that shows how to enable retention policies for your feed."::: - -1. Select **Save** when you're done. +As the number of package versions in your feed grows, storage usage can increase rapidly. You can set up retention policies to automatically delete old package versions and free up space. -::: moniker-end +If you need to keep a package indefinitely, promote it to a [view](../concepts/views.md). Packages in a view are exempt from retention policies and will not be subject to deletion. To configure retention policies for your feed, follow the steps below: -::: moniker range="tfs-2018" +> [!NOTE] +> Azure Artifacts does not support package demotion. Once a package is promoted to a view, it cannot be reverted back to *@local*. -1. Select **Build and Release**. +::: moniker range="<=azure-devops" -1. Select **Packages**, and then select the gear icon to access your feed's settings. +1. Sign in to your Azure DevOps organization, and then navigate to your project. - :::image type="content" source="../media/edit-feed-full.png" alt-text="Screenshot that shows how access the feed's settings in Team Foundation Server."::: +1. Select **Artifacts**, then select the gear icon ![gear icon](../../media/icons/gear-icon.png) in the upper-right corner to access your feed's settings. +1. Select **Feed details**, check the **Enable package retention** checkbox, and configure the following settings: -1. From the **Retention** tab, enter values for: + - **Maximum number of versions per package**: The number of versions for each package you wish to retain. - - **Maximum number of versions per package**: How many versions of a package you want to keep. - - **Days to keep recently downloaded packages**: Packages will be deleted only if they haven't been downloaded for the number of days set in here. - - :::image type="content" source="../media/retention-policy-settings-tfs.png" alt-text="Screenshot that shows retention policies in Team Foundation Server."::: - + - **Days to keep recently downloaded packages**: Packages will only be deleted if they haven't been downloaded for the specified number of days specified here. 1. Select **Save** when you're done. + :::image type="content" source="../media/retention-policy-settings.png" alt-text="A screenshot displaying how to set up retention policies for your feed."::: + ::: moniker-end > [!NOTE] -> When you enable package retention, a version of a package will be deleted when *both* of the following criteria are met: -> - The number of published versions reaches the **Maximum number of versions per package** limit. -> - A version of that package has not been downloaded for the period defined in **Days to keep recently downloaded packages**. - -## Recover deleted packages - -Deleted packages will remain in the Recycle Bin for 30 days. After that, they'll be permanently deleted. You must be a feed **Owner** to recover deleted packages. +> When retention policies are enabled, a package version will be deleted only when **both** of the following conditions are met: +> - The total number of published versions reaches the **Maximum number of versions per package** limit. +> - A version of that package has not been downloaded within the timeframe specified in **Days to keep recently downloaded packages**. -::: moniker range=">= azure-devops-2019" +## Restore deleted packages -1. Select **Artifacts**. +Deleted packages remain in the recycle bin for 30 days. After this period, they are permanently deleted. To restore a package from the recycle bin, follow these steps: - :::image type="content" source="../media/goto-feed-hub-azure-devops-newnav.png" alt-text="Screenshot of how to access Azure Artifacts."::: +::: moniker range="<=azure-devops" -1. Select **Recycle Bin**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. - :::image type="content" source="../media/recycle-bin.png" alt-text="A screenshot showing how to access the recycle bin."::: +1. Select **Artifacts**, then select **Recycle Bin**. 1. Select your package, and then select **Restore**. - :::image type="content" source="../media/restore-package.png" alt-text="A screenshot showing how to restore deleted packages."::: +1. Select **Restore** once more to confirm your decision. + + :::image type="content" source="../media/restore-package.png" alt-text="A screenshot displaying how to restore deleted packages."::: ::: moniker-end -::: moniker range="tfs-2018" +## Q&A -1. Select **Build and Release**, and then select **Packages**. +##### Q: What is the difference between *Deprecate*, *Unlist*, *Yank*, and *Delete* a package version? -1. Select **Recycle Bin**. +A: *Deprecate* applies to npm packages, *Yank* applies to Cargo packages while *Unlist* applies to NuGet packages. You can *Delete* any of the package types (npm, Maven, Python, Cargo, and Universal Packages) from your Azure Artifacts feed. - :::image type="content" source="../media/recycle-bin/find-recycle-bin.png" alt-text="Screenshot of how to access the Recycle Bin in Team Foundation Server."::: +- **Deprecate** (npm): When you deprecate a package version, a warning message is added to the package's metadata. Azure Artifacts and most npm clients will display this warning message whenever the package is viewed or installed. -1. Select the appropriate package, and then select the package version that you want to delete. +- **Unlist** (NuGet): Unlisting a package version hides it from search results in Azure Artifacts feeds and on NuGet.org. - :::image type="content" source="../media/recycle-bin/recycle-bin-view.png" alt-text="Screenshot that shows the package in the Recycle Bin in Team Foundation Server."::: +- **Yank** (Cargo): Yanking a package version marks it as obsolete or deprecated, discouraging its use, but it doesn't delete the package. -1. Select **Restore to feed**. +- **Delete**: Deleting a package version moves it to the recycle bin, making it unavailable for installation. Deleted packages can be restored from the recycle bin within 30 days. After this period, they will be permanently deleted. - :::image type="content" source="../media/recycle-bin/recycle-bin-restore.png" alt-text="Screenshot that shows the button for restoring to feed in Team Foundation Server."::: +##### Q: How do I delete all package versions? -::: moniker-end +A: To delete all versions of a package, select the package from your feed, select **Versions**, and then select the checkbox next to *version*. This will select all versions of that package in your feed. Select **Delete**, then select delete once more to confirm. -## Q&A +:::image type="content" source="../media/delete-all-versions.png" alt-text="A screenshot displaying how to delete all versions from a feed."::: + +##### Q: What happens with old or existing packages when we enable retention policies? + +A: Old or existing packages will be soft-deleted and moved to the recycle bin. The deletion job runs once a day, but there might be an initial delay after the policy is turned on for the first time due to an influx of packages. -### Q: What is the difference between *Deprecate*, *Unpublish*, *Unlist*, and *Delete* a package version? +Packages remain in the recycle bin for 30 days before they're permanently deleted. To remove the packages from your billable storage, you can manually delete them using the web UI or the REST API before the 30-day period ends. -A: *Unpublish* and *Deprecate* applies to npm packages, while *Unlist* and *Delete* applies to NuGet packages. You can also *Delete* package versions for the rest of the package types (Maven, Python, and Universal Packages): +##### Q: What if I don't want to enable retention policies? -- **Deprecate** (npm): When you deprecate a package version, a warning message is added to the package's metadata. Azure Artifacts and most npm clients will display the warning message whenever the package is viewed or installed. -- **Unpublish** (npm): Unpublishing a package version makes it unavailable to install. Unpublished packages can be restored from the Recycle Bin within 30 days of deletion. After that, the packages will be permanently deleted. +A: Azure Artifacts retention policies are designed to help manage your dependencies and streamline storage cost management. If you choose not to enable retention policies, you'll need to manage your storage manually, monitoring consumption and deleting packages as necessary. Azure Artifacts offers 2 GiB of free storage per organization, which allows you to evaluate whether the service fits your workflow. Once you exceed the storage limit, you won't be able to publish new artifacts unless you set up billing and [increase your storage limit](../start-using-azure-artifacts.md#increase-azure-artifacts-storage-limit). -- **Unlist** (NuGet): Unlisting a package version hides it from the search results in Azure Artifacts feeds and on NuGet.org. -- **Delete**: Deleting a package version makes it unavailable to install. Deleted packages can be restored from the Recycle Bin within 30 days of deletion. After that, the packages will be permanently deleted. +##### Q: How long does it take for the billed storage amount to update after deleting Artifacts? -### Q: What happens with old or existing packages when we enable retention policies? +A: Typically, storage consumption should update within 24 hours. However, in some cases, it might take up to 48 hours for the changes to be reflected. The Artifacts usage on your organization's billing page updates once a day, while the Artifact Storage page is updated more frequently, which could lead to a slight discrepancy between the two. -A: Old or existing packages will be soft-deleted and moved to the Recycle Bin. The deletion job runs once a day, but there might be an initial delay after the policy is turned on for the first time because of an influx of packages. +## Related content -Packages remain in the Recycle Bin for 30 days before they're permanently deleted. To remove the packages from your billable storage, you can choose to delete them manually by using the UI or the REST API before the 30 days are up. +- [Monitor Artifacts storage consumption](../artifact-storage.md) -## Related articles +- [Limits on package sizes and counts](../reference/limits.md) -- [Understand upstream sources](../concepts/upstream-sources.md) -- [Feeds permissions](../feeds/feed-permissions.md) -- [Configure upstream sources](./set-up-upstream-sources.md) -- [Promote a package to a view](../feeds/views.md) \ No newline at end of file +- [Manage permissions](../feeds/feed-permissions.md) diff --git a/docs/artifacts/how-to/public-feeds-upstream-sources.md b/docs/artifacts/how-to/public-feeds-upstream-sources.md new file mode 100644 index 00000000000..4c259e7c84f --- /dev/null +++ b/docs/artifacts/how-to/public-feeds-upstream-sources.md @@ -0,0 +1,157 @@ +--- +title: Enable and add upstream sources to a public feed +description: How to enable and add upstream sources to a public feed in Azure Artifacts +ms.service: azure-devops-artifacts +ms.topic: tutorial +ms.date: 03/02/2023 +monikerRange: 'azure-devops' +--- + +# Use upstream sources in a public feed + +[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] + +Azure Artifacts enables developers to manage their dependencies from a single feed. Using upstream sources, you can consume packages from feeds and public registries such as NuGet.org, and npmjs.com. In this article, you'll learn how to: + +> [!div class="checklist"] +> +> - Create a public feed +> - Enable upstream sources +> - Add a new upstream source + +## Prerequisites + +- An Azure DevOps organization. [Create an organization](../../organizations/accounts/create-organization.md), if you don't have one already. + +- An Azure DevOps project. [Create a new project](../../organizations/projects/create-project.md) if you don't have one already. + +- Set your project visibility to [public](../../organizations/projects/make-project-public.md). + +## Create a public feed + +A public feed is a project-scoped feed in a public project. Public feeds inherit the visibility settings of the hosting project. + +1. Sign in to your Azure DevOps organization, and then select your public project. + +1. Select **Artifacts**, and then select **Create Feed**. + + :::image type="content" source="../media/new-feed-devops.png" alt-text="A screenshot showing the create feed button in Azure Artifacts."::: + +1. Give your feed a **Name**, and then select **Project: PublicProject (Recommended)** for its scope. + + :::image type="content" source="../media/new-public-feed.png" alt-text="A screenshot showing how to create a new public feed."::: + +1. Select **Create** when you're done. + +> [!IMPORTANT] +> Public feeds do not support upstreaming to a private Artifacts feed. If you are using a public Azure Artifacts feed, you can only upstream to public registries (NuGet.org, npmjs) or other **Public** Azure Artifacts feeds. + +## Add an upstream source + +1. Sign in to your Azure DevOps organization, and then select your public project. + +1. Select **Artifacts**, and then select your public feed. + +1. Select the gear icon ![gear icon](../../media/icons/gear-icon.png) to access your **Feed Settings**. + +1. Select **Upstream Sources**, and then select **Add Upstream**. + + :::image type="content" source="../media/public-feed-add-upstream.png" alt-text="A screenshot showing how to add an upstream source in a public feed."::: + +1. Select your upstream source **Type**. In this example, we'll be adding NuGet.org as an upstream source. + + :::image type="content" source="../media/public-feed-upstream-types.png" alt-text="A screenshot showing the different types of upstream sources."::: + +1. Configure your source, and then select **Add** when you're done. + + :::image type="content" source="../media/public-feed-configure-upstream.png" alt-text="A screenshot showing how to configure your upstream source."::: + +1. Select **Save** to save your new upstream source. + + :::image type="content" source="../media/save-upstream.png" alt-text="A screenshot showing how to save the newly added upstream source."::: + +> [!IMPORTANT] +> [Package lock files](https://devblogs.microsoft.com/nuget/enable-repeatable-package-restores-using-a-lock-file/) are required to save NuGet and Dotnet packages from upstream sources to a public feed. + +## Restore packages + +Run the following command in your project directory to restore your packages: + +#### [NuGet](#tab/nuget) + +```Command +nuget.exe restore +``` + +#### [Dotnet](#tab/dotnet) + +```Command +dotnet restore --interactive +``` + +#### [Npm](#tab/npm) + +```Command +npm install +``` + +#### [Maven](#tab/maven) + +```Command +mvn install +``` + +#### [Gradle](#tab/gradle) + +```Command +gradle build +``` + +#### [Python](#tab/python) + +```Command +pip install +``` + +#### [Cargo](#tab/cargo) + +Feed and Upstream Reader (Collaborator) roles or higher must use an additional flag to authenticate with their public feed in order to install packages. Be sure to follow the instructions in [Cargo - Connect to a feed](../cargo/cargo-upstream-source.md#connect-to-your-feed) to properly authenticate with your feed, and then run the following command in your project directory to restore your packages. + +```Command +cargo build +``` + +- - - + +> [!NOTE] +> You must be a **Feed and Upstream Reader (Collaborator)** or higher to install new package versions from upstream. Anonymous users can only install packages that exist in their feed. + +## Q&A + +#### Q: I'm trying to restore my packages but I keep getting a 401 unauthorized error? + +The contents of a feed can only be changed by an authenticated and authorized identity who has appropriate permissions on the feed. This includes saving packages into the feed from an upstream source. Unauthenticated (anonymous) users can *download packages already saved* into a feed, but cannot save new packages from an upstream into the feed. + +Maintainers of a project should save all needed versions of packages into the public feed. This can be done by restoring a project using an identity that *can* supply credentials to the feed when prompted, **and** ensuring that the identity used has **Feed and Upstream Reader (Collaborator)** or higher permissions on the public feed. + +If anonymous users who are restoring packages for a project are repeatedly being blocked by requests for credentials (401 response), the following approaches will reduce or eliminate the issue: + +1. Avoid using package version ranges in your project configuration. Explicit package versions will ensure that packaging clients only request the exact version needed. + +1. Where supported, utilize lock files for your packaging ecosystem so that the packaging clients only request the specific versions needed for the project during a restore/install operation. + +#### Q: I'm trying to restore my packages using Visual Studio, but I'm noticing that they're getting pulled from a different source? + +A: Make sure that Visual Studio is using the source referenced in your *nuget.config* file and not from the local NuGet package manager. See [Package sources](/nuget/consume-packages/install-use-packages-visual-studio#package-sources) for more details. + +You can also use the NuGet CLI to force NuGet to use the source in your config file by running the following command: + +```Command +nuget restore -config +``` + +## Related content + +- [Search for packages in upstream sources](search-upstream.md) +- [Set up upstream sources](set-up-upstream-sources.md) +- [Configure upstream behavior](../concepts/upstream-behavior.md) diff --git a/docs/artifacts/how-to/search-upstream.md b/docs/artifacts/how-to/search-upstream.md index a6b5a413b32..ac8a4dd423f 100644 --- a/docs/artifacts/how-to/search-upstream.md +++ b/docs/artifacts/how-to/search-upstream.md @@ -4,11 +4,13 @@ description: How to search for packages in upstream sources ms.service: azure-devops-artifacts ms.topic: conceptual ms.date: 09/29/2022 -monikerRange: '<= azure-devops' +monikerRange: '>= azure-devops-2022' --- # Search for packages in upstream sources +[!INCLUDE [version-gt-eq-2022](../../includes/version-gt-eq-2022.md)] + Using upstream sources enable developers to consume packages from different feeds and public registries. This tutorial will walk you through how to enable upstream sources in your feed and search for packages in upstreams. ## Enable upstream sources @@ -23,7 +25,7 @@ Using upstream sources enable developers to consume packages from different feed 1. Select **Public source**, and then select the **Public source**. (Example *NuGet gallery (https://api.nuget.org/v3/index.json)*) -1. Select **Save** when you're done. +1. Select **Add** when you're done. :::image type="content" source="../media/enable-upstream.png" alt-text="A screenshot showing how to add the NuGet upstream."::: @@ -47,10 +49,10 @@ Using upstream sources enable developers to consume packages from different feed :::image type="content" source="../media/upstream-packages.png" alt-text="A screenshot showing package versions from upstream."::: -## Save packages - > [!NOTE] -> Saving packages to your feed is only supported for NuGet, Npm, and Universal Packages. +> Searching for packages in upstream sources from your feed is only supported in Azure DevOps services. + +## Save packages 1. To save a package, select the ellipsis button and then select **Save to feed**. @@ -64,6 +66,9 @@ Using upstream sources enable developers to consume packages from different feed :::image type="content" source="../media/downloaded-versions-from-upstream.png" alt-text="A screenshot showing the downloaded versions."::: +> [!NOTE] +> Saving package versions to your feed from the search upstreams result list is only supported for NuGet, Npm, and Universal Packages. + ## Related articles - [Set up upstream sources](./set-up-upstream-sources.md) diff --git a/docs/artifacts/how-to/set-up-upstream-sources.md b/docs/artifacts/how-to/set-up-upstream-sources.md index d6da4079b43..36afd8e8790 100644 --- a/docs/artifacts/how-to/set-up-upstream-sources.md +++ b/docs/artifacts/how-to/set-up-upstream-sources.md @@ -1,117 +1,143 @@ --- title: Set up upstream sources for your feed -description: How to configure upstream sources for your Azure Artifacts feeds +description: How to set up external feeds and public registries as upstream sources for your feed ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 02/16/2022 -monikerRange: '<= azure-devops' +ms.date: 03/21/2024 +monikerRange: "<=azure-devops" --- -# Configure upstream sources +# Set up upstream sources -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] -With upstream sources, you can use a single feed to store the packages you generate and the packages you consume from public registries such as npmjs.com, NuGet.org, Maven Central, and PyPI.org. Once you've enabled an upstream source, every time you install a package from the public registry, Azure Artifacts will save a copy of that package in your feed. +With Azure Artifacts upstream sources, you can streamline your package management by using a single feed to store both the packages you publish and those you consume from external feeds and public registries such as npmjs.com, NuGet.org. When an upstream source is enabled on your feed, Azure Artifacts will automatically save a copy of any package installed by a collaborator or higher from upstream. -## Create a new feed and enable upstream sources +> [!NOTE] +> Maven snapshots are not supported in upstream sources. + +## Enable upstream sources in a new feed + +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. From within your project, select **Artifacts**. +1. Select **Artifacts**, and then select **Create Feed**. - :::image type="content" source="../media/goto-feed-hub-azure-devops-newnav.png" alt-text="Screenshot of Artifacts button."::: +1. Provide a **Name** for your feed and select its **Visibility** and **Scope** settings. Make sure to check the **Include packages from common public sources** checkbox to enable upstream sources. + +1. Select **Create** when you're done. -1. Select **Create Feed**. + :::image type="content" source="../media/new-feed-dialog-azure-devops.png" alt-text="A screenshot showing how to create a new feed."::: - :::image type="content" source="../media/new-feed-button-azure-devops-newnav.png" alt-text="Screenshot of the create feed button."::: +> [!NOTE] +> You must be a feed owner or a feed administrator to add or remove upstream sources. -1. Give your feed a **Name** and choose its **visibility**, and **scope** settings. Make sure you check the **Include packages from common public sources** checkbox to enable upstream sources. +## Enable upstream sources in an existing feed - :::image type="content" source="../media/new-feed-dialog-azure-devops.png" alt-text="Screenshot showing the create new feed window panel."::: +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Create** when you are done. +1. Select the gear icon button ![gear icon](../../media/icons/gear-icon.png) to navigate to your feed settings. -> [!IMPORTANT] -> Maven snapshots are not supported in upstream sources. +1. Select **Upstream sources**, and then select **Add upstream source**. -## Enable upstream sources in an existing feed +1. Select **Public source**, and then select a **Public source** from the dropdown menu. + +1. Select **Add** when you're done, and then select **Save** once more in the top right corner to preserve your changes. > [!NOTE] > Custom public upstream sources are only supported with npm registries. -1. Select the ![gear icon](../../media/icons/gear-icon.png) button to access your feed's settings. +## Add a feed in the same organization as an upstream source -1. Select **Upstream sources**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Add upstream source**. +1. Select the gear icon button![gear icon](../../media/icons/gear-icon.png) to access your feed's settings. -1. Select **Public source**, and then select the **Public source**. (Example *Maven Central (https://repo.maven.apache.org/maven2/)* for Maven central) +1. Select **Upstream sources**, and then select **Add Upstream**. -1. Select **Add** when you are done. +1. Select **Azure Artifacts feed in this organization**. -> [!NOTE] -> Azure Artifacts support Maven Central, Google Maven Repository, Gradle Plugins, and JitPack as upstream sources for Maven. +1. Select the desired **Feed** from the dropdown menu to add it as an upstream source. Then, select the **View** and choose the **Package type(s)** you wish to use. Optionally, you can also modify the name of your upstream source. -## Add a feed in your organization as an upstream source +1. Select **Add** when you're done. -1. Select the ![gear icon](../../media/icons/gear-icon.png) button to access your feed's settings. + :::image type="content" source="../media/add-upstream-same-org.png" alt-text="A screenshot showing how to add a feed in your organization as an upstream source."::: -1. Select **Upstream sources**. +## Add a feed in a different organization as an upstream source -1. Select **Add Upstream**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Azure Artifacts feed in this organization**. +1. Select the gear icon button![gear icon](../../media/icons/gear-icon.png) to access your feed's settings. -1. Select the feed you would like to add from the dropdown menu. +1. Select **Upstream sources**, and then select **Add Upstream**. -1. Select the package types you want to use, select the **View** and name your upstream source. +1. Select **Azure Artifacts feed in another organization**. -1. Select **Save** when you are done. +1. Enter your **Azure Artifacts feed locator** in the following format: - :::image type="content" source="../media/add-upstream-same-org.png" alt-text="A screenshot showing how to add a feed in your organization as an upstream source."::: + - **Organization scoped feed**: + + ``` + azure-feed://ORGANIZATION_NAME/FEED_NAME@VIEW + ``` + + - **Project scoped feed**: + + ``` + azure-feed://ORGANIZATION_NAME/PROJECT_NAME/FEED_NAME@VIEW + ``` -## Add a feed in a different organization as an upstream source +1. Select the **Package type(s)** you wish to use and provide a name for your upstream source. + +1. Select **Add** when you're done. + + :::image type="content" source="../media/add-upstream-diff-org.png" alt-text="A screenshot showing how to add a feed in a different organization as an upstream source."::: > [!NOTE] -> Universal Packages are only supported in upstream sources within the same organization. +> To add a feed from a different organization as an upstream source, the target feed owner must share the target view with **All feeds and people in organizations associated with my Microsoft Entra tenant** by navigating to **Feed Settings** > **Views** > Select the ellipsis button on the right for the specified view > **Edit** . -1. Select the ![gear icon](../../media/icons/gear-icon.png) button to access your feed's settings. +## Examples -1. Select **Upstream sources**. +# [NuGet](#tab/nuget) -1. Select **Add Upstream**. +- [Use packages from NuGet.org](../nuget/upstream-sources.md) -1. Select **Azure Artifacts feed in another organization**. +# [Npm](#tab/npm) -1. Enter your **Azure DevOps Services feed locator**. Example: *azure-feed://myOrg/myProject/myFeed@local*. +- [Use packages from npmjs.com](../npm/upstream-sources.md) -1. Select the **Package type(s)** you want to use and enter an **Upstream source name**. +# [Python](#tab/python) -1. Select **Save** when you are done. +- [Use packages from Python package index (PyPI)](../python/use-packages-from-pypi.md) - :::image type="content" source="../media/add-upstream-diff-org.png" alt-text="A screenshot showing how to add a feed in a different organization as an upstream source."::: +# [Maven](#tab/maven) + +- [Use packages from Maven Central](../maven/upstream-sources.md) + +- [Use packages from Google Maven Repository](../maven/google-maven.md) -## Example: install NuGet packages from upstream sources with Visual Studio +- [Use packages from Gradle Plugins](../maven/gradle-plugins.md) -Using Visual Studio, we can now install packages from the upstream sources we configured: +- [Use packages from JitPack](../maven/jitpack-upstream.md) -1. Navigate to NuGet.org, find the package you want to install, and then copy the `Install-Package` command. -1. In Visual Studio, select **Tools** > **NuGet Package Manager** > **Package Manager Console**. -1. Paste the install command into the Package Manager Console and press ENTER to run it. +# [Cargo](#tab/cargo) -## Example: install npm packages from upstream sources using the CLI +- [Use packages from Crates.io](../cargo/cargo-upstream-source.md) -Run the following command in an elevated command prompt window to install your npm package from upstream. +# [Universal Packages](#tab/universalpackages) -```Command -npm install --save -``` +- [Universal Packages upstream sources](../universal-packages/universal-packages-upstream.md) + +# [PowerShell](#tab/powershell) + +- [Use packages from the PowerShell Gallery](../tutorials/powershell-upstream-source.md) + +--- > [!NOTE] -> You must be a **Collaborator**, a **Contributor**, or an **Owner** to install new packages from upstream. A copy of each upstream package is saved to the feed on first use. Packages already saved from upstream sources can be used by feed **Readers**. +> You must be a **Feed and Upstream Reader (Collaborator)**, a **Feed Publisher (Contributor)**, or a **Feed Owner** to install new packages from upstream. A copy of each upstream package is saved to the feed on first use. Packages already saved from upstream sources can be used by **Feed Readers**. ## Related articles -- [Manage dependencies with upstream sources](../tutorials/protect-oss-packages-with-upstream-sources.md) -- [Universal Packages upstream sources](../universal-packages/universal-packages-upstream.md) -- [Configure upstream behavior](../concepts/upstream-behavior.md) -- [Use feed views to share packages](../feeds/views.md) +- [Search for packages in upstream sources](./search-upstream.md) - [Configure permissions](../feeds/feed-permissions.md) +- [Use feed views to share packages](../feeds/views.md) diff --git a/docs/artifacts/includes/create-feed-gt-eq-2019.md b/docs/artifacts/includes/create-feed-gt-eq-2019.md new file mode 100644 index 00000000000..d89fe2dec77 --- /dev/null +++ b/docs/artifacts/includes/create-feed-gt-eq-2019.md @@ -0,0 +1,64 @@ +--- +ms.topic: include +ms.service: azure-devops-artifacts +ms.manager: mijacobs +ms.author: rabououn +author: ramiMSFT +ms.date: 02/22/2024 +--- + +::: moniker range=">= azure-devops" + +1. Sign in to your Azure DevOps organization, and then go to your project. + +1. Select **Artifacts**, and then select **Create Feed**. + + :::image type="content" source="../media/new-feed-dialog-azure-devops.png" alt-text="A screenshot showing how to create a feed."::: + +1. Enter the following information for your feed: + + 1. Enter a descriptive **Name** for your feed. + 1. Define its **Visibility** (indicating who can view packages within the feed). + 1. Select whether to use packages from public sources such as pypi.org. + 1. Specify the **Scope** of your feed. + +1. Select **Create**. + +::: moniker-end + +::: moniker range="azure-devops-2022" + +1. Go to your Azure DevOps collection, select your project. + +1. Select **Artifacts**, and then select **Create Feed**. + + :::image type="content" source="../media/new-feed-dialog-devops-server.png" alt-text="A screenshot showing how to create a feed in DevOps Server."::: + +1. Enter the following information for your feed: + + 1. Enter a descriptive **Name** for your feed. + 1. Define its **Visibility** (indicating who can view packages within the feed). + 1. Select whether to use packages from public sources such as pypi.org. + 1. Specify the **Scope** of your feed. + +1. Select **Create**. + +::: moniker-end + +::: moniker range="azure-devops-2020" + +1. Go to your Azure DevOps collection, select your project. + +1. Select **Artifacts**, and then select **Create Feed** to create a new feed. + +1. Enter the following information for your feed: + + 1. Enter a descriptive **Name** for your feed. + 1. Define its **Visibility** (indicating who can view packages within the feed). + 1. Select whether to use packages from public sources such as pypi.org. + 1. Specify the **Scope** of your feed. + +1. Select **Create**. + +::: moniker-end + diff --git a/docs/artifacts/includes/create-feed.md b/docs/artifacts/includes/create-feed.md index 8cd6335e94c..2537be6e039 100644 --- a/docs/artifacts/includes/create-feed.md +++ b/docs/artifacts/includes/create-feed.md @@ -4,47 +4,48 @@ ms.service: azure-devops-artifacts ms.manager: mijacobs ms.author: rabououn author: ramiMSFT -ms.date: 02/14/2022 +ms.date: 03/15/2024 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="azure-devops" -1. Sign in to your Azure DevOps organization, and then navigate to your project. +1. Sign in to your Azure DevOps organization and navigate to your project. 1. Select **Artifacts**, and then select **Create Feed**. - :::image type="content" source="../media/new-feed-button-azure-devops-newnav.png" alt-text="A screenshot showing the create a feed button."::: - -1. Provide a descriptive **Name** for your feed and specify its **Visibility** (determining who can view packages within the feed). Additionally, configure the **Upstream sources** and specify the **Scope** of your feed (project-scoped or organization-scoped). - - :::image type="content" source="../media/new-feed-dialog-azure-devops.png" alt-text="A screenshot showing how to create a need feed."::: +1. Provide a **Name** for your feed, choose the **Visibility** option that defines who can view your packages, check **Include packages from common public sources** if you want to include packages from sources like *nuget.org* or *npmjs.com*, and for **Scope**, decide whether the feed should be scoped to your project or the entire organization. 1. Select **Create** when you're done. -> [!NOTE] -> When creating a new feed, the default access level for the *Project Collection Build Service* (organization-scoped) and the project-level *Build Service*(project-scoped) is set to **Collaborator**. + :::image type="content" source="../media/create-new-feed-azure-devops.png" alt-text="Screenshot that shows selections for creating a new feed in Azure DevOps Services."::: ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="azure-devops-2022 || azure-devops-2020" -Azure Artifacts comes pre-installed in TFS 2018. If this is the first time using your feed, you might be asked to [assign a license](../start-using-azure-artifacts.md?preserve-view=true&view=tfs-2018#assign-licenses-in-tfs) +1. Sign in to your Azure DevOps server, and then go to your project. -1. Go to **Build & Release** and select **Packages**. +2. Select **Artifacts**, and then select **Create Feed**. - > [!div class="mx-imgBorder"] - > ![Go to Azure Artifacts TFS](../media/goto-feed-hub.png) +3. Provide a **Name** for your feed, choose the **Visibility** option that defines who can view your packages, check **Include packages from common public sources** if you want to include packages from sources like *nuget.org* or *npmjs.com*, and for **Scope**, decide whether the feed should be scoped to your project or the entire organization. -1. Select **+ New feed**. +::: moniker-end - > [!div class="mx-imgBorder"] - > ![New feed button TFS](../media/new-feed-button.png) +::: moniker range="azure-devops-2022" -1. Give your feed a **Name**, a **Description**, and set up **who can read**, **who can contribute** and if you want to **Include external packages**. +4. Select **Create** when you're done. - > [!div class="mx-imgBorder"] - > ![New feed dialog box TFS](../media/new-feed-dialog-azure-tfs.png) + :::image type="content" source="../media/create-new-feed-server-2022.png" alt-text="Screenshot that shows selections for creating a new feed in Azure DevOps 2022."::: -1. Select **Create** when you're done. +::: moniker-end + +::: moniker range="azure-devops-2020" + +4. Select **Create** when you're done. + + :::image type="content" source="../media/create-new-feed-server-2020.png" alt-text="Screenshot that shows selections for creating a new feed in Azure DevOps 2020."::: ::: moniker-end + +> [!NOTE] +> By default, newly created feeds have their project's **Build Service** value set to **Feed and Upstream Reader (Collaborator)**. diff --git a/docs/artifacts/includes/edit-feed.md b/docs/artifacts/includes/edit-feed.md index 34338e92b2d..80d07a4321d 100644 --- a/docs/artifacts/includes/edit-feed.md +++ b/docs/artifacts/includes/edit-feed.md @@ -7,7 +7,7 @@ author: ramiMSFT ms.date: 02/16/2022 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Select the gear icon to navigate to your feed's settings. @@ -15,10 +15,3 @@ ms.date: 02/16/2022 ::: moniker-end -::: moniker range="tfs-2018" - -1. Select the gear icon to navigate to your feed's settings. - - :::image type="content" source="../media/editfeed.png" alt-text="Screenshot of the Edit feed button TFS."::: - -::: moniker-end diff --git a/docs/artifacts/includes/maven/install.md b/docs/artifacts/includes/maven/install.md index e68aebd9aa1..45035b87149 100644 --- a/docs/artifacts/includes/maven/install.md +++ b/docs/artifacts/includes/maven/install.md @@ -16,12 +16,4 @@ ms.date: 05/06/2022 ::: moniker-end -::: moniker range="tfs-2018" -1. Select **Packages**, and then select the package you want to install and copy the `` snippet. - -1. Open your pom.xml file and paste your code inside the `` tag. - -1. Run `mvn install` from the same path as your pom.xml file. - -::: moniker-end diff --git a/docs/artifacts/includes/maven/pom-and-settings.md b/docs/artifacts/includes/maven/pom-and-settings.md index 824ba58023f..388550e76f2 100644 --- a/docs/artifacts/includes/maven/pom-and-settings.md +++ b/docs/artifacts/includes/maven/pom-and-settings.md @@ -3,29 +3,120 @@ ms.topic: include ms.service: azure-devops-artifacts ms.author: rabououn author: ramiMSFT -ms.date: 10/04/2022 +ms.date: 07/01/2024 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="azure-devops" -1. Select **Artifacts**, and then select **Connect to Feed**. - - :::image type="content" source="../../media/connect-to-feed-azure-devops-newnav.png" alt-text="A screenshot showing how to connect to a feed."::: +1. Sign in to your Azure DevOps organization, and then navigate to your project. -::: moniker-end +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **Maven** from the left navigation area. + +1. If this is your first time using Azure Artifacts with Maven, make sure you've installed the prerequisites. Otherwise select **Get the tools** in the top-right corner to install them. -::: moniker range="tfs-2018" +1. Follow the instructions in the **Project setup** section to set up your *pom.xml* and *settings.xml* files. Your files should resemble the following examples: -1. Select **Packages**, and then select **Connect to Feed**. + - **pom.xml**: + + ```xml + + + MavenDemo + https://pkgs.dev.azure.com///_packaging//maven/v1 + + true + + + true + + + + + + MavenDemo + https://pkgs.dev.azure.com///_packaging//maven/v1 + + true + + + true + + + + ``` - :::image type="content" source="../../media/connect-to-feed.png" alt-text="A screenshot showing how to connect to a feed in TFS."::: + - **settings.xml**: + + ```xml + + + MavenDemo + + [PERSONAL_ACCESS_TOKEN] + + + ``` + +1. Generate a [Personal Access Token](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scope, and then paste it into the `` tag. ::: moniker-end -2. Select **Maven**. +::: moniker range="azure-devops-2020 || azure-devops-2022" + +1. Sign in to your Azure DevOps collection, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to Feed**, and then select **Maven** from the left navigation pane. -3. If this is the first time using Azure Artifacts with Maven, select **Get the tools** to download and install Maven. +1. If this is your first time using Azure Artifacts with Maven, make sure you've installed the prerequisites, otherwise select **Get the tools** in the top-right corner to install them. -4. Follow the instructions in the **Project setup** to set up your pom.xml and settings.xml files. If your *settings.xml* file is shared within your team, you can use Maven to [encrypt your passwords](https://maven.apache.org/guides/mini/guide-encryption.html). +1. Follow the instructions in the **Project setup** section to set up your *pom.xml* and *settings.xml* files. Your files should resemble the following examples: + + - **pom.xml**: + + ```xml + + + MavenDemo + http://///_packaging//maven/v1 + + true + + + true + + + + + + MavenDemo + http://///_packaging//maven/v1 + + true + + + true + + + + ``` + + - **settings.xml**: + + ```xml + + + MavenDemo + + [PERSONAL_ACCESS_TOKEN] + + + ``` + +1. Generate a [Personal Access Token](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scope, and then paste it into the `` tag. + +::: moniker-end - :::image type="content" source="../../media/maven-azure-devops-newnav.png" alt-text="A screenshot showing how to set up your project."::: diff --git a/docs/artifacts/includes/npm/npmrc.md b/docs/artifacts/includes/npm/npmrc.md index 4f1472e2fdd..9c47c1f0e99 100644 --- a/docs/artifacts/includes/npm/npmrc.md +++ b/docs/artifacts/includes/npm/npmrc.md @@ -3,28 +3,40 @@ ms.topic: include ms.service: azure-devops-artifacts ms.author: rabououn author: ramiMSFT -ms.date: 05/25/2022 +ms.date: 09/11/2023 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. 1. Select **Artifacts**, and then select **Connect to feed**. - :::image type="content" source="../../media/connect-to-feed-azure-devops-newnav.png" alt-text="A screenshot showing how to connect to a feed."::: + :::image type="content" source="../../npm/media/npm-scopes-connect-to-feed.png" alt-text="A screenshot showing how to connect to a feed."::: 1. Select **npm**, and then select **Other**. 1. Add a `.npmrc` file in the same directory as your package.json, and paste the following snippet into your file. - ```JSON - registry=https://pkgs.dev.azure.com//_packaging//npm/registry/ + - **Organization-scoped feed**: - always-auth=true - ``` + ```Command + registry=https://pkgs.dev.azure.com//npm/registry/ + + always-auth=true + ``` + + - **Project-scoped feed**: + + ```Command + registry=https://pkgs.dev.azure.com///_packaging//npm/registry/ + + always-auth=true + ``` ### Set up credentials -1. Copy the following snippet into your `.npmrc` file. +1. Copy the following snippet into your user-level `.npmrc` file, (Example: C:\Users\FabrikamUser\.npmrc). Make sure you don't paste it into the .npmrc file within your source repository. - **Organization-scoped feed**: @@ -54,7 +66,7 @@ ms.date: 05/25/2022 1. Generate a [personal access token](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **Packaging** > **Read & write** scopes. -1. Run the following command to encode your newly generated personal access token. Paste your personal access token when prompted. +1. Run the following command to encode your newly generated personal access token. When prompted, paste your personal access token and then copy the resulting Base64 encoded value. ```Command node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })" @@ -64,14 +76,3 @@ ms.date: 05/25/2022 ::: moniker-end -::: moniker range="tfs-2018" - -1. Select **Packages**, and then select **Connect to feed**. - -1. Select **npm**. - -1. Select **Generate npm credentials**, and then copy the credentials and add them to your .npmrc file. - - :::image type="content" source="../../media/tfs2018-connect-to-npm-feed.png" alt-text="Screenshot showing how to generate npm credentials in TFS."::: - -::: moniker-end \ No newline at end of file diff --git a/docs/artifacts/includes/npm/publish-restore.md b/docs/artifacts/includes/npm/publish-restore.md index 8a57548bc05..6ae39c45e8b 100644 --- a/docs/artifacts/includes/npm/publish-restore.md +++ b/docs/artifacts/includes/npm/publish-restore.md @@ -20,6 +20,9 @@ ms.date: 01/24/2023 npm publish ``` +> [!NOTE] +> If your organization is using a firewall or a proxy server, make sure you allow [Azure Artifacts Domain URLs and IP addresses](../../../organizations/security/allow-list-ip-url.md#azure-artifacts). + ## Restore packages 1. Run the following command in your project directory to restore your npm packages: diff --git a/docs/artifacts/includes/nuget/auth-with-sp.md b/docs/artifacts/includes/nuget/auth-with-sp.md new file mode 100644 index 00000000000..f99161afd1d --- /dev/null +++ b/docs/artifacts/includes/nuget/auth-with-sp.md @@ -0,0 +1,49 @@ +--- +ms.topic: include +ms.service: azure-devops-artifacts +ms.author: wonga +author: wonga +ms.date: 12/10/2024 +--- + +## Authenticate NuGet Feed with Service Principal + +To authenticate with a service principal, you must first install the [Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider). + +Set the [ARTIFACTS_CREDENTIALPROVIDER_FEED_ENDPOINTS](https://github.com/microsoft/artifacts-credprovider/blob/master/README.md#environment-variables) environment variable as shown below, specifying your feed URL, the service principal's application (client) ID, and the subject name or the file path of your service principal certificate. (Only one is needed between the certificate subject name or file path.) + + +#### [Windows](#tab/Windows/) + +In PowerShell, enter the following code. + +```powershell +$env:ARTIFACTS_CREDENTIALPROVIDER_FEED_ENDPOINTS = @'{ + "endpointCredentials": [ + { + "endpoint": "", + "clientId": "", + "clientCertificateSubjectName": "", + "clientCertificateFilePath": "" + } + ] +} +'@ +``` + +#### [Linux/macOS](#tab/Linux/) + +In Bash, enter the following code. + +```bash +export ARTIFACTS_CREDENTIALPROVIDER_FEED_ENDPOINTS='{ + "endpointCredentials": [ + { + "endpoint": "", + "clientId": "", + "clientCertificateSubjectName": "", + "clientCertificateFilePath": "" + } + ] +}' +``` diff --git a/docs/artifacts/includes/nuget/consume.md b/docs/artifacts/includes/nuget/consume.md index 3854611bc9c..3cbee9d4074 100644 --- a/docs/artifacts/includes/nuget/consume.md +++ b/docs/artifacts/includes/nuget/consume.md @@ -3,10 +3,10 @@ ms.topic: include ms.service: azure-devops-artifacts ms.author: rabououn author: ramiMSFT -ms.date: 05/10/2022 +ms.date: 05/15/2024 --- -#### 1. Get the feed's source URL +#### 1. Get the package source URL [!INCLUDE [get a NuGet URL](nuget-consume-endpoint.md)] @@ -14,27 +14,27 @@ ms.date: 05/10/2022 #### [Windows](#tab/windows/) -1. In Visual Studio, select **Tools**, and then **Options**. +1. In Visual Studio, select **Tools** > **Options**. 1. Expand the **NuGet Package Manager** section, and then select **Package Sources**. -1. Enter the feed's **Name** and the **Source** URL, and then select the green (+) sign to add a source. +1. Enter the feed's **Name** value and the **Source** URL, and then select the green plus sign (+) to add a source. 1. If you enabled upstream sources in your feed, clear the **nuget.org** checkbox. 1. Select **OK** when you're done. - :::image type="content" source="../../media/vs-addsource.png" alt-text="A screenshot showing how to set up visual studio in Windows."::: + :::image type="content" source="../../media/vs-addsource.png" alt-text="A screenshot that shows selections for setting up Visual Studio in Windows."::: #### [macOS](#tab/macOS/) 1. Create a [personal access token](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). -1. In visual studio, select **Preferences** from the menu bar. +1. In Visual Studio, on the menu bar, select **Preferences**. 1. Select **NuGet**, and then select **Sources**. -1. Select **Add** and enter your feed's name, the source URL, a userName (any string), and your personal access token. +1. Select **Add** and enter your feed's name, the source URL, a username (any string), and your personal access token. 1. Select **OK** to save your source. @@ -42,16 +42,16 @@ ms.date: 05/10/2022 1. Select **OK** when you're done. - :::image type="content" source="../../media/vs-mac-settings.png" alt-text="A screenshot showing how to set up visual studio in macOS."::: + :::image type="content" source="../../media/vs-mac-settings.png" alt-text="A screenshot that shows selections for setting up Visual Studio in macOS."::: --- #### 3. Download packages -1. In Visual Studio, right-click on your project, and then select **Manage NuGet Packages**. +1. In Visual Studio, right-click your project, and then select **Manage NuGet Packages**. 1. Select **Browse**, and then select your feed from the **Package source** dropdown menu. - - :::image type="content" source="../../media/select-pkg-src.png" alt-text="A screenshot showing how to select your feed source."::: + + :::image type="content" source="../../media/select-pkg-src.png" alt-text="Screenshot that shows selection of a package source in Visual Studio."::: 1. Use the search bar to search for packages from your feed. diff --git a/docs/artifacts/includes/nuget/nuget-consume-endpoint.md b/docs/artifacts/includes/nuget/nuget-consume-endpoint.md index 34d552a8473..4cc3a1b70c3 100644 --- a/docs/artifacts/includes/nuget/nuget-consume-endpoint.md +++ b/docs/artifacts/includes/nuget/nuget-consume-endpoint.md @@ -3,29 +3,17 @@ ms.topic: include ms.service: azure-devops-artifacts ms.author: rabououn author: ramiMSFT -ms.date: 01/26/2023 +ms.date: 05/15/2024 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -1. Navigate to your project, and then select **Artifacts** then select your feed. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Connect to feed**, and then select **Visual Studio** from the left navigation panel. +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to Feed**. -1. Copy your **Source** URL. +1. Select **Visual Studio** from the left navigation pane, then copy your **Source** URL. - :::image type="content" source="../../media/nuget-visual-studio-newnav.png" alt-text="A screenshot showing the source URL."::: - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Select **Build and Release**, and then select **Packages**. - -1. Select your feed from the dropdown menu. - -1. Select **Connect to feed**, and then copy your **Source** URL. - - :::image type="content" source="../../media/nuget-consume-url.png" alt-text="A screenshot showing the package source URL in TFS."::: + :::image type="content" source="../../media/nuget-visual-studio-newnav.png" alt-text="A screenshot displaying how to find the feed's Source URL."::: ::: moniker-end diff --git a/docs/artifacts/includes/nuget/nuget-publish-endpoint.md b/docs/artifacts/includes/nuget/nuget-publish-endpoint.md index 962e7521e3d..9a815ab1df7 100644 --- a/docs/artifacts/includes/nuget/nuget-publish-endpoint.md +++ b/docs/artifacts/includes/nuget/nuget-publish-endpoint.md @@ -6,7 +6,7 @@ author: ramiMSFT ms.date: 06/23/2022 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Select **Artifacts**, and then select your feed from the dropdown menu. @@ -24,18 +24,3 @@ ms.date: 06/23/2022 ::: moniker-end -::: moniker range="tfs-2018" - -1. Select **Build and Release** > **Packages**. - -1. Select your feed from the dropdown menu or [create one](../../get-started-nuget.md#create-a-feed) if you haven't. - -1. Select **Connect to feed**. - - :::image type="content" source="../../media/connect-to-feed.png" alt-text="Connect to feed - TFS"::: - -1. Select **NuGet** and follow the instruction to connect to your feed. - - :::image type="content" source="../../media/connect-to-nuget-feed-tfs.png" alt-text="Connect to NuGet feed - TFS"::: - -::: moniker-end diff --git a/docs/artifacts/includes/save-requires-collaborator.md b/docs/artifacts/includes/save-requires-collaborator.md new file mode 100644 index 00000000000..e72e614952c --- /dev/null +++ b/docs/artifacts/includes/save-requires-collaborator.md @@ -0,0 +1,10 @@ +--- +author: jmyersmsft +ms.author: jmyers +ms.date: 03/18/2024 +ms.topic: include +ms.service: azure-devops-artifacts +--- + +> [!NOTE] +> To save packages from upstreams, you must have the **Feed and Upstream Reader (Collaborator)** role or higher. See [Manage Permissions](../feeds/feed-permissions.md#permissions-table) for more details. diff --git a/docs/artifacts/index.yml b/docs/artifacts/index.yml index 554cac88812..3e8e66a8c27 100644 --- a/docs/artifacts/index.yml +++ b/docs/artifacts/index.yml @@ -1,16 +1,16 @@ ### YamlMime:Landing title: Azure Artifacts documentation -summary: Code once and share packages across your organization. Host your private NuGet, npm, Maven, Python, and Universal Packages with Azure Artifacts for more reliable and scalable builds. +summary: Create, host, and share NuGet, npm, Maven, Python, Cargo, and Universal Packages with Azure Artifacts for seamless package management and collaboration across projects and organizations. metadata: title: Azure Artifacts documentation - description: Code once and share your packages NuGet, npm, Maven, Python, and Universal Packages with Azure Artifacts for more reliable and scalable builds. + description: Create, host, and share NuGet, npm, Maven, Python, Cargo, and Universal Packages with Azure Artifacts for seamless package management and collaboration across projects and organizations. ms.service: azure-devops-artifacts ms.topic: landing-page - author: KathrynEE - ms.author: kaelli - ms.date: 09/17/2021 + ms.author: rabououn + author: ramiMSFT + ms.date: 02/11/2025 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new # Schema location: https://static.docs.com/ui/latest/schemas/Landing.schema.json @@ -23,17 +23,23 @@ landingContent: linkLists: - linkListType: concept links: - - text: Artifacts overview + - text: What is Azure Artifacts? url: ./start-using-azure-artifacts.md - - linkListType: quickstart - links: + - text: Limits on package sizes and counts + url: reference/limits.md - text: Best practices url: ./concepts/best-practices.md - - text: Artifacts storage consumption - url: ./artifact-storage.md - - text: Package sizes and count limits - url: ./reference/limits.md - - title: Configure Feeds + - text: Key concepts + url: artifacts-key-concepts.md + - linkListType: quickstart + links: + - text: Publish your first package + url: get-started-artifacts-ai.md + - text: Monitor Artifacts storage + url: artifact-storage.md + - text: Search packages across your feeds + url: ../project/search/functional-package-search.md?toc=/azure/devops/artifacts/toc.json + - title: Feeds linkLists: - linkListType: concept links: @@ -43,28 +49,108 @@ landingContent: url: ./concepts/views.md - linkListType: quickstart links: - - text: Configure permissions - url: ./feeds/feed-permissions.md - - text: Upstream sources overview - url: ./concepts/upstream-sources.md - - text: Configure upstream sources - url: ./how-to/set-up-upstream-sources.md - - title: Artifacts in Azure Pipelines + - text: Promote packages and manage views + url: feeds/views.md + - text: Use public feeds to share your packages publicly + url: tutorials/share-packages-publicly.md + - title: Publish + linkLists: + - linkListType: how-to-guide + links: + - text: NuGet + url: nuget/publish.md + - text: dotnet + url: nuget/dotnet-exe.md + - text: npm + url: npm/publish.md + - text: Gradle + url: maven/publish-with-gradle.md + - text: Python + url: quickstarts/python-cli.md + - text: Universal Packages + url: quickstarts/universal-packages.md + - text: Cargo + url: get-started-cargo.md + - title: Restore + linkLists: + - linkListType: how-to-guide + links: + - text: NuGet + url: nuget/restore-nuget-packages-nuget-exe.md + - text: dotnet + url: nuget/restore-nuget-packages-dotnet.md + - text: npm + url: npm/publish.md + - text: Maven + url: maven/install.md + - text: Python + url: quickstarts/install-python-packages.md + - text: Universal Packages + url: quickstarts/download-universal-packages.md + - text: Cargo + url: get-started-cargo.md + - title: Upstream sources + linkLists: + - linkListType: overview + links: + - text: Upstream sources overview + url: concepts/upstream-sources.md + - linkListType: how-to-guide + links: + - text: Set up upstream sources + url: how-to/set-up-upstream-sources.md + - text: Use upstream sources with public feeds + url: how-to/public-feeds-upstream-sources.md + - text: Search for packages in upstream sources + url: how-to/search-upstream.md + - text: Use packages from NuGet.org + url: nuget/upstream-sources.md + - text: Use packages from npmjs.com + url: npm/upstream-sources.md + - text: Use packages from Maven Central + url: maven/upstream-sources.md + - text: Use packages from PyPi + url: python/use-packages-from-pypi.md + - text: Universal Packages upstream sources + url: universal-packages/universal-packages-upstream.md + - text: Use packages from Crates.io + url: cargo/cargo-upstream-source.md + - title: Security linkLists: - linkListType: concept + links: + - text: Manage permissions + url: feeds/feed-permissions.md + - text: Safeguard against malicious public packages + url: concepts/upstream-behavior.md + - title: Artifacts in Azure Pipelines + linkLists: + - linkListType: overview links: - text: Overview url: ../pipelines/artifacts/artifacts-overview.md - linkListType: quickstart links: - - text: Pipeline Artifacts - url: ../pipelines/artifacts/build-artifacts.md - - text: Release Artifacts and Artifact sources - url: ../pipelines/release/artifacts.md - - text: Publish and download Artifacts + - text: Publish and download pipeline artifacts url: ../pipelines/artifacts/pipeline-artifacts.md - - text: Pipeline caching - url: ../pipelines/release/caching.md + - text: Publish and download build artifacts + url: ../pipelines/artifacts/build-artifacts.md + - text: Use the .artifactignore file + url: reference/artifactignore.md + - text: NuGet + url: ../pipelines/artifacts/nuget.md + - text: npm + url: ../pipelines/artifacts/npm.md + - text: Maven + url: ../pipelines/artifacts/publish-maven-artifacts.md + - text: Gradle + url: ../pipelines/artifacts/build-publish-artifacts-gradle.md + - text: Python + url: ../pipelines/artifacts/pypi.md + - text: Cargo + url: ../pipelines/artifacts/cargo-pipelines.md + - text: Universal Packages + url: ../pipelines/artifacts/universal-packages.md - title: Symbols linkLists: - linkListType: concept @@ -78,82 +164,4 @@ landingContent: - text: Debug with WinDbg url: ./symbols/debug-with-symbols-windbg.md - text: Publish symbols with Azure Pipelines - url: ../pipelines/artifacts/symbols.md - - title: NuGet - linkLists: - - linkListType: quickstart - links: - - text: Get started - url: get-started-nuget.md - - linkListType: how-to-guide - links: - - text: Publish NuGet packages (CLI) - url: ./nuget/publish.md - - text: Publish NuGet packages with Azure Pipelines (YAML/Classic) - url: ../pipelines/artifacts/nuget.md?toc=/azure/devops/artifacts/toc.json - - text: Install NuGet packages with Visual Studio - url: ./nuget/consume.md - - text: NuGet.org upstream source - url: ./nuget/upstream-sources.md - - title: npm - linkLists: - - linkListType: quickstart - links: - - text: Get started - url: get-started-npm.md - - linkListType: how-to-guide - links: - - text: Publish npm packages (CLI) - url: ./npm/publish.md - - text: Publish npm packages with Azure Pipelines (YAML/Classic) - url: ../pipelines/artifacts/npm.md?toc=/azure/devops/artifacts/toc.json - - text: Set up your project and connect to Azure Artifacts - url: ./npm/npmrc.md - - text: Use npm scopes - url: ./npm/scopes.md - - text: Npmjs.com upstream source - url: ./npm/upstream-sources.md - - title: Maven - linkLists: - - linkListType: quickstart - links: - - text: Get started - url: get-started-maven.md - - linkListType: how-to-guide - links: - - text: Project setup - url: ./maven/pom-and-settings.md - - text: Install Maven Artifacts - url: ./maven/install.md - - text: Use packages from Maven Central - url: ./maven/upstream-sources.md - - text: Google Maven Repository upstream source - url: ./maven/google-maven.md - - text: Gradle Plugins upstream source - url: ./maven/gradle-plugins.md - - text: JitPack upstream source - url: ./maven/jitpack-upstream.md - - title: Python - linkLists: - - linkListType: quickstart - links: - - text: Get started - url: ./quickstarts/python-packages.md - - linkListType: how-to-guide - links: - - text: Publish and download Python packages (CLI) - url: ./quickstarts/python-cli.md - - text: Publish and download Python packages with Azure Pipelines (YAML/Classic) - url: ../pipelines/artifacts/pypi.md?toc=/azure/devops/artifacts/toc.json - - title: Universal Packages - linkLists: - - linkListType: quickstart - links: - - text: Get started - url: ./quickstarts/universal-packages.md - - linkListType: how-to-guide - links: - - text: Publish and download Universal Packages with Azure Pipelines (YAML/Classic) - url: ../pipelines/artifacts/universal-packages.md?toc=/azure/devops/artifacts/toc.json - - text: Universal Packages upstream sources - url: ./universal-packages/universal-packages-upstream.md \ No newline at end of file + url: ../pipelines/artifacts/symbols.md \ No newline at end of file diff --git a/docs/artifacts/maven/google-maven.md b/docs/artifacts/maven/google-maven.md index 16b448cbc9e..66d8ed89c8f 100644 --- a/docs/artifacts/maven/google-maven.md +++ b/docs/artifacts/maven/google-maven.md @@ -1,44 +1,96 @@ --- -title: Google Maven Repository upstream source -description: How to add Google Maven Repository upstream source +title: Use packages from Google Maven Repository upstream source +description: How to consume packages from Google Maven Repository upstream source ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 03/03/2022 +ms.date: 11/14/2023 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Google Maven Repository upstream source +# Use packages from Google Maven Repository [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -With Azure Artifacts, developers can enable upstream sources to store packages from different sources such as Google Maven Repository. Once enabled, Azure Artifacts will save a copy of all the packages installed from Google Maven Repository. Azure Artifacts also support other Maven upstream sources such as Maven Central, Gradle Plugins, and JitPack. +With Azure Artifacts, developers can enable upstream sources to consume packages from different public registries such as Google Maven Repository. Once enabled, Azure Artifacts will automatically save a copy of any package installed from the upstream. Additionally, Azure Artifacts supports other Maven upstream sources such as Maven Central, Gradle Plugins, and JitPack. In this article, you'll learn how to: -## Add Google Maven Repository +> [!div class="checklist"] +> * Add Google Maven Repository as an upstream source +> * Consume a package from upstream +> * Find saved packages in your feed -1. Select the ![gear icon](../../media/icons/gear-icon.png) at the top right corner to navigate to **Feed Settings**. +## Prerequisites -1. Select **Upstream sources**. +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. -1. Select **Add Upstream**. +- An Azure Artifacts feed. -1. Select **Public source**, and then select **Google Maven Repository (https://maven.google.com/web/index.html)** from the dropdown menu. +## Enable upstream sources + +If you don't have a feed already, follow the instructions below to create a new feed, and make sure to check the *upstream sources* checkbox to enable them. If you already have a feed, jump to the [next step](#add-google-maven-repository-upstream) to add Google Maven Repository as an upstream source: + +[!INCLUDE [](../includes/create-feed.md)] - :::image type="content" source="../media/google-maven-repository.png" alt-text="A screenshot showing how to add Google Maven Repository."::: +## Add Google Maven Repository upstream -1. Select **Save** when you are done. +If you checked the *upstream sources* checkbox when creating your feed, Google Maven Repository should already be added as an upstream source. If not, you can add it manually using the following steps: -1. Select **Save** at the top right corner to save your changes. +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select the gear icon ![gear icon](../../media/icons/gear-icon.png) in the top right corner to navigate to your **Feed Settings**. + +1. Select **Upstream sources**, and then select **Add Upstream**. + +1. Select **Public source**, and then select **Google Maven Repository (https://maven.google.com/web/index.html)** from the dropdown menu. + +1. Select **Add** when you're done, and then select **Save** again in the top right corner to save your changes. > [!NOTE] > Maven snapshots are not supported with Maven upstream sources. +## Save packages from Google Maven Repository + +Before saving packages from Google Maven Repository, make sure you have set up your project to connect to your feed. If you haven't done so already, follow the instruction in the [project setup](pom-and-settings.md) to set up your Maven project and connect to your feed. The following example illustrates how to save the Zipflinger Library from Google Maven Repository. + +If you want to save/restore your packages using Azure Pipelines instead, follow the steps in the [Restore Maven packages with Azure Pipelines (YAML/Classic)](../../pipelines/packages/maven-restore.md) tutorial. + +1. Navigate to Google Maven Repository at `https://mvnrepository.com/`. + +1. Search for the Zipflinger library. Select the **Zipflinger** package, and then select the version you wish to install. + +1. Copy the `` snippet from the **Maven** tab. + + ```xml + + com.android + zipflinger + 8.3.0-alpha13 + + ``` + +1. Open your *pom.xml* file and paste the snippet inside your `` tag, and then save your file. + +1. Run the following command from the same path as your *pom.xml* file to install your dependencies: + + ```command + mvn install + ``` + +[!INCLUDE [save-requires-collaborator](../includes/save-requires-collaborator.md)] ## View saved packages -To view the packages you installed from Google Maven Repository, select the appropriate source from the dropdown menu. +To view the packages you installed from upstream, select the **Google Maven Repository** source from the dropdown menu. + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select the **Google Maven Repository** source from the dropdown menu to find packages from this upstream. -:::image type="content" source="media/google-maven-source.png" alt-text="A screenshot showing how to filter for packages from Google Maven Repository."::: +1. The *Zipflinger* package that we saved in the previous step is now available in our feed, as Azure Artifacts automatically saved a copy when we executed the mvn install command. + + :::image type="content" source="media/saved-zipflinger-package-from-google-maven-repository.png" alt-text="A screenshot showing packages from Google Maven Repository." lightbox="media/saved-zipflinger-package-from-google-maven-repository.png"::: > [!TIP] > If Maven is not downloading all your dependencies, run the following command from the project directory to regenerate your project's files: @@ -46,7 +98,6 @@ To view the packages you installed from Google Maven Repository, select the appr ## Related articles -- [Maven Central upstream source](./upstream-sources.md) +- [Use packages from Maven Central](./upstream-sources.md) +- [Search for packages in upstream sources](../how-to/search-upstream.md) - [Configure permissions](../feeds/feed-permissions.md) -- [Set up upstream sources](../how-to/set-up-upstream-sources.md) -- [Upstream behavior](../concepts/upstream-behavior.md) diff --git a/docs/artifacts/maven/gradle-plugins.md b/docs/artifacts/maven/gradle-plugins.md index b005878dafe..09345dbe0b6 100644 --- a/docs/artifacts/maven/gradle-plugins.md +++ b/docs/artifacts/maven/gradle-plugins.md @@ -27,11 +27,9 @@ With Azure Artifacts feeds, you can enable upstream sources to include packages 1. Select **Public source**, and then select **Gradle Plugins (https://plugins.gradle.org/m2/)** from the dropdown menu. - :::image type="content" source="./media/gradle-plugins.png" alt-text="A screenshot showing how to add Gradle Plugins."::: - -1. Select **Save** when you are done. +1. Select **Add** when you're done, and then select **Save** at the top right corner to save your changes. -1. Select **Save** at the top right corner to save your changes. + :::image type="content" source="./media/gradle-plugins.png" alt-text="A screenshot showing how to add Gradle Plugins."::: ## View saved packages diff --git a/docs/artifacts/maven/install.md b/docs/artifacts/maven/install.md index 58aa4ee6408..96798c0d196 100644 --- a/docs/artifacts/maven/install.md +++ b/docs/artifacts/maven/install.md @@ -1,61 +1,164 @@ --- -title: Install Maven Artifacts -description: How to connect to feeds and install Maven Artifacts +title: Restore Maven packages from your Azure Artifacts feed +description: Learn how to connect to your Azure Artifacts feed and restore your Maven packages. ms.service: azure-devops-artifacts ms.assetid: 0f66e727-e76a-4a72-be12-3fa1775b9e2c -ms.manager: jenp +ms.manager: mijacobs ms.topic: conceptual -ms.reviewer: dastahel ms.custom: engagement-fy23 -ms.date: 01/09/2023 +ms.date: 06/11/2024 monikerRange: '<= azure-devops' +"recommendations": "true" --- -# Install Maven Artifacts +# Restore Maven packages from your Azure Artifacts feed [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -With Azure Artifacts, you can publish and restore Maven packages from Azure Artifacts feed and public registries. In this article, you will learn how to connect to Azure Artifacts feeds and restore your Maven packages. +With Azure Artifacts, you can publish and restore Maven packages from Azure Artifacts feed and public registries. This article will walk you through setting up your Maven project, connecting to your Azure Artifacts feed, and restoring your Maven packages. ## Prerequisites -- An Azure DevOps organization. [Create an organization](../../organizations/accounts/create-organization.md), if you don't have one already. - -- An Azure Artifacts feed. [Create a new feed](../get-started-nuget.md#create-a-feed) if you don't have one already. - -- [Download](https://maven.apache.org/download.cgi) and [install](https://maven.apache.org/install.html) Maven. - -## Connect to feed - -1. From your Azure DevOps project, select **Artifacts**, and then select your feed from the dropdown menu. - -1. Select **Connect to feed**. - - :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot showing how to connect to your feed"::: - -1. Select **Maven** from the left navigation panel. - -1. Follow the instructions in the **Project setup** section to set up your config files and generate a new personal access token. - - :::image type="content" source="../media/maven-project-setup.png" alt-text="Screenshot showing how to set up Maven projects."::: +- An Azure DevOps organization. [Create one for free](../../organizations/accounts/create-organization.md). + +- An Azure DevOps project. Create a new [project](../../organizations/projects/create-project.md#create-a-project) if you don't have one already. + +- An Azure Artifacts feed. [Create one for free](../concepts/feeds.md#create-a-new-feed). + +- [Download](https://maven.apache.org/download.cgi) and [Install](https://maven.apache.org/install.html) Apache Maven. + +## Connect to a feed + +::: moniker range="azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **Maven** from the left navigation area. + +1. If this is your first time using Azure Artifacts with Maven, make sure you've installed the prerequisites. Otherwise select **Get the tools** in the top-right corner to install them. + +1. Follow the instructions in the **Project setup** section to set up your *pom.xml* and *settings.xml* files. Your files should resemble the following examples: + + - **pom.xml**: + + ```xml + + + MavenDemo + https://pkgs.dev.azure.com///_packaging//maven/v1 + + true + + + true + + + + + + MavenDemo + https://pkgs.dev.azure.com///_packaging//maven/v1 + + true + + + true + + + + ``` + + - **settings.xml**: + + ```xml + + + MavenDemo + + [PERSONAL_ACCESS_TOKEN] + + + ``` + +1. Generate a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scope, and then paste it into the `` tag. + +::: moniker-end + +::: moniker range="azure-devops-2020 || azure-devops-2022" + +1. Sign in to your Azure DevOps collection, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to Feed**, and then select **Maven** from the left navigation pane. + +1. If this is your first time using Azure Artifacts with Maven, make sure you've installed the prerequisites, otherwise select **Get the tools** in the top-right corner to install them. + +1. Follow the instructions in the **Project setup** section to set up your *pom.xml* and *settings.xml* files. Your files should resemble the following examples: + + - **pom.xml**: + + ```xml + + + MavenDemo + http://///_packaging//maven/v1 + + true + + + true + + + + + + MavenDemo + http://///_packaging//maven/v1 + + true + + + true + + + + ``` + + - **settings.xml**: + + ```xml + + + MavenDemo + + [PERSONAL_ACCESS_TOKEN] + + + ``` + +1. Generate a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scope, and then paste it into the `` tag. + +::: moniker-end > [!TIP] > If your *settings.xml* file is shared within your team, you can use Maven to [encrypt your passwords](https://maven.apache.org/guides/mini/guide-encryption.html). -## Restore Maven packages +## Restore packages -Run the following command in an elevated command prompt to download your Maven packages. Maven automatically downloads all your dependencies to your local repository when the `build` command is executed. +Run the following command in your project directory to restore your packages: -```Command -mvn build +``` +mvn install ``` -> [!TIP] -> The `` tags in your *settings.xml* and *pom.xml* files must be the same. +> [!NOTE] +> Ensure that the `` tags in your *settings.xml* and *pom.xml* files match exactly. ## Related articles - [Use packages from Maven Central](./upstream-sources.md) - [Use public feeds to share your packages publicly](../tutorials/share-packages-publicly.md) -- [Configure permissions](../feeds/feed-permissions.md) -- [Use feed views to share packages](../feeds/views.md) \ No newline at end of file +- [Configure permissions](../feeds/feed-permissions.md) \ No newline at end of file diff --git a/docs/artifacts/maven/jitpack-upstream.md b/docs/artifacts/maven/jitpack-upstream.md index 7f1df741419..70f1aaddd2d 100644 --- a/docs/artifacts/maven/jitpack-upstream.md +++ b/docs/artifacts/maven/jitpack-upstream.md @@ -24,11 +24,9 @@ With Azure Artifacts, you can consume packages from different public registries 1. Select **Public source**, and then select **JitPack (https://jitpack.io/)** from the dropdown menu. - :::image type="content" source="./media/jitpack-upstream.png" alt-text="A screenshot showing how to add JitPack."::: - -1. Select **Save** when you are done. +1. Select **Add** when you're done, and then select **Save** at the top right corner to save your changes. -1. Select **Save** at the top right corner to save your changes. + :::image type="content" source="./media/jitpack-upstream.png" alt-text="A screenshot showing how to add JitPack."::: ## View saved packages diff --git a/docs/artifacts/maven/media/gradle-plugins.png b/docs/artifacts/maven/media/gradle-plugins.png index 5a873045487..60f0c4f9cec 100644 Binary files a/docs/artifacts/maven/media/gradle-plugins.png and b/docs/artifacts/maven/media/gradle-plugins.png differ diff --git a/docs/artifacts/maven/media/jitpack-upstream.png b/docs/artifacts/maven/media/jitpack-upstream.png index 711954d544d..4a452fd19ad 100644 Binary files a/docs/artifacts/maven/media/jitpack-upstream.png and b/docs/artifacts/maven/media/jitpack-upstream.png differ diff --git a/docs/artifacts/maven/media/publish-package-gradle.png b/docs/artifacts/maven/media/publish-package-gradle.png new file mode 100644 index 00000000000..edcc7cb53de Binary files /dev/null and b/docs/artifacts/maven/media/publish-package-gradle.png differ diff --git a/docs/artifacts/maven/media/save-upstream-sources.png b/docs/artifacts/maven/media/save-upstream-sources.png new file mode 100644 index 00000000000..756f9248767 Binary files /dev/null and b/docs/artifacts/maven/media/save-upstream-sources.png differ diff --git a/docs/artifacts/maven/media/saved-kotlin-package-from-upstream.png b/docs/artifacts/maven/media/saved-kotlin-package-from-upstream.png new file mode 100644 index 00000000000..6d69fc05752 Binary files /dev/null and b/docs/artifacts/maven/media/saved-kotlin-package-from-upstream.png differ diff --git a/docs/artifacts/maven/media/saved-zipflinger-package-from-google-maven-repository.png b/docs/artifacts/maven/media/saved-zipflinger-package-from-google-maven-repository.png new file mode 100644 index 00000000000..24fbf51b3fa Binary files /dev/null and b/docs/artifacts/maven/media/saved-zipflinger-package-from-google-maven-repository.png differ diff --git a/docs/artifacts/maven/pom-and-settings.md b/docs/artifacts/maven/pom-and-settings.md index 53ffdd1caca..1ab3683fa99 100644 --- a/docs/artifacts/maven/pom-and-settings.md +++ b/docs/artifacts/maven/pom-and-settings.md @@ -1,18 +1,151 @@ --- -title: Set up your Maven project -description: How to set up Maven client +title: Connect your Maven project with Azure Artifacts +description: Learn how to set up your Maven project and connect to an Azure Artifacts feed. ms.service: azure-devops-artifacts ms.assetid: 944f45ee-baa3-45ba-8467-5e7ab2bc47cf ms.topic: conceptual -ms.date: 10/04/2022 +ms.date: 06/10/2024 monikerRange: '<= azure-devops' +"recommendations": "true" --- -# Set up your Maven project and connect to feed +# Connect your Maven project to an Azure Artifacts feed [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -[!INCLUDE [](../includes/maven/pom-and-settings.md)] +With Azure Artifacts, you can seamlessly publish and restore Maven packages from feeds and public registries. Azure Artifacts supports upstreaming from Maven Central, Google Maven Repository, Gradle Plugins, and JitPack. This guide will walk you through the process of setting up your Maven project and connecting to your Azure Artifacts feed. + +## Prerequisites + +- An Azure DevOps organization. [Create one for free](../../organizations/accounts/create-organization.md). + +- An Azure DevOps project. Create a new [project](../../organizations/projects/create-project.md#create-a-project) if you don't have one already. + +- An Azure Artifacts feed. [Create one for free](../concepts/feeds.md#create-a-new-feed). + +- [Download](https://maven.apache.org/download.cgi) and [Install](https://maven.apache.org/install.html) Apache Maven. + +## Project setup + +::: moniker range="azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **Maven** from the left navigation area. + +1. If this is your first time using Azure Artifacts with Maven, make sure you've installed the prerequisites. Otherwise select **Get the tools** in the top-right corner to install them. + +1. Follow the instructions in the **Project setup** section to set up your *pom.xml* and *settings.xml* files. Your files should resemble the following examples: + + - **pom.xml**: + + ```xml + + + MavenDemo + https://pkgs.dev.azure.com///_packaging//maven/v1 + + true + + + true + + + + + + MavenDemo + https://pkgs.dev.azure.com///_packaging//maven/v1 + + true + + + true + + + + ``` + + - **settings.xml**: + + ```xml + + + MavenDemo + + [PERSONAL_ACCESS_TOKEN] + + + ``` + +1. Generate a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scope, and then paste it into the `` tag. + +::: moniker-end + +::: moniker range="azure-devops-2020 || azure-devops-2022" + +1. Sign in to your Azure DevOps collection, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to Feed**, and then select **Maven** from the left navigation pane. + +1. If this is your first time using Azure Artifacts with Maven, make sure you've installed the prerequisites, otherwise select **Get the tools** in the top-right corner to install them. + +1. Follow the instructions in the **Project setup** section to set up your *pom.xml* and *settings.xml* files. Your files should resemble the following examples: + + - **pom.xml**: + + ```xml + + + MavenDemo + http://///_packaging//maven/v1 + + true + + + true + + + + + + MavenDemo + http://///_packaging//maven/v1 + + true + + + true + + + + ``` + + - **settings.xml**: + + ```xml + + + MavenDemo + + [PERSONAL_ACCESS_TOKEN] + + + ``` + +1. Generate a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scope, and then paste it into the `` tag. + +::: moniker-end > [!NOTE] -> If your `settings.xml` file is shared within your team, you can use mvn to [encrypt your passwords](https://maven.apache.org/guides/mini/guide-encryption.html). +> If your `settings.xml` file is shared within your team, you can use Maven to [encrypt your passwords](https://maven.apache.org/guides/mini/guide-encryption.html). + +## Related articles + +- [Restore Maven packages](install.md) +- [Use packages from Maven Central](upstream-sources.md) +- [JitPack upstream source](jitpack-upstream.md) \ No newline at end of file diff --git a/docs/artifacts/maven/publish-with-gradle.md b/docs/artifacts/maven/publish-with-gradle.md index dd822397c0a..088c0f3396c 100644 --- a/docs/artifacts/maven/publish-with-gradle.md +++ b/docs/artifacts/maven/publish-with-gradle.md @@ -1,110 +1,191 @@ --- -title: Publish a Maven artifact using Gradle -description: How to publish Maven artifacts using Gradle +title: Publish artifacts using Gradle +description: Learn how to connect to a feed and publish your packages with Gradle. ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 05/08/2023 +ms.date: 10/16/2024 ms.author: rabououn author: ramiMSFT monikerRange: '<= azure-devops' "recommendations": "true" --- -# Publish Maven artifacts using Gradle +# Publish artifacts with Gradle [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -In this article, you will learn how to connect to an Azure Artifacts feed and publish Maven artifacts using Gradle. +With Azure Artifacts, you can efficiently manage your dependencies from a single feed, storing various types of packages in one place. Azure Artifacts enables developers to publish and consume packages from different sources, and sharing them according to the feed's visibility settings. In this article, you'll learn how to connect to an Azure Artifacts feed and publish your packages using Gradle. ## Prerequisites -- An Azure DevOps organization. [Create an organization](../../organizations/accounts/create-organization.md), if you don't have one already. +- Create an Azure DevOps [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. -- An Azure Artifacts feed. [Create a feed](../concepts/feeds.md#create-public-feeds) if you don't have one already. +- [Create a feed](../get-started-maven.md#create-a-feed) if you don't have one already. - Download and install [Gradle](https://docs.gradle.org/current/userguide/installation.html). -- Install [Java SE](https://www.oracle.com/technetwork/java/javase/downloads/index.html). +- Install the [Java Development Kit (JDK)](https://jdk.java.net/) version 8 or higher. + +## Create a personal access token + +To authenticate with your feed, you must first create a personal access token with packaging *Read & Write* scopes: + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **User settings**, and then select **Personal access tokens**. + + :::image type="content" source="media/create-pat.png" alt-text="A screenshot showing how to locate the personal access token button."::: + +1. Select **New Token** and fill out the required fields. Be sure to select the **Packaging** > **Read & write** scope. + +1. Select **Create** when you're done. Copy your token and save it in a secure location, as you'll need it for the next step. + + :::image type="content" source="media/gradle-pat.png" alt-text="A screenshot demonstrating how to create a new personal access token with packaging read & write scopes."::: ## Project setup -Before setting up your project, ensure that you have installed Gradle and added the Maven Settings plugin to your *build.gradle* file as follows: +# [Gradle 8.2 and above](#tab/newer) + +Before setting up your project, ensure Gradle is installed and that you've added the Maven Settings plugin to your *build.gradle* file as follows: ```groovy plugins { - id "net.linguica.maven-settings" version "0.5" + id 'maven-publish' } ``` -### Create a personal access token +#### Configure build.gradle -1. Sign in to your Azure DevOps organization, and then navigate to your project. +1. If a *build.gradle* file doesn't exist in the root of your project, create a new file and name it: *build.gradle*. -1. Select **User settings**, and then select **Personal access tokens**. +1. Add the following section to your *build.gradle* file within both the **repositories** and **publishing.repositories** containers: + + ```groovy + maven { + url 'https://pkgs.dev.azure.com///_packaging//maven/v1' //for organization-scoped feeds use this format: 'https://pkgs.dev.azure.com//_packaging//maven/v1' + name '' + credentials(PasswordCredentials) + authentication { + basic(BasicAuthentication) + } + } + ``` + +Here's an example of what your *build.gradle* file should look like: + +```groovy +repositories { + mavenCentral() + + maven { + url 'https://pkgs.dev.azure.com///_packaging//maven/v1' //for organization-scoped feeds use this format: 'https://pkgs.dev.azure.com//_packaging//maven/v1' + name '' + credentials(PasswordCredentials) + authentication { + basic(BasicAuthentication) + } + } +} + +publishing { + publications { + library(MavenPublication) { + from components.java + } + } + + repositories { + maven { + url 'https://pkgs.dev.azure.com///_packaging//maven/v1' //for organization-scoped feeds use this format: 'https://pkgs.dev.azure.com//_packaging//maven/v1' + name '' + credentials(PasswordCredentials) + authentication { + basic(BasicAuthentication) + } + } + } +} +``` + +#### Configure gradle.properties + +1. Open the *gradle.properties* file located in the *.gradle* directory of your home folder (~/.gradle/gradle.properties). If the file doesn't exist, create a new one. + +1. Add the following snippet, replacing the placeholders with your feed name, organization name, and the personal access token you created earlier. - :::image type="content" source="media/create-pat.png" alt-text="Screenshot showing how to create a personal access token"::: + ``` + # Substitute FEED_NAME with the same name specified as the 'name' of the maven repository in build.gradle. + # The value of the username is arbitrary but should not be blank. + [FEED_NAME]Username=[ORGANIZATION_NAME] + [FEED_NAME]Password=[PERSONAL_ACCESS_TOKEN] + ``` -1. Select **New Token**, and then fill out the required fields. Make sure you select the **Packaging** > **Read & write** scope. +# [Older versions](#tab/older) -1. Select **Create** when you are done. Copy your token and save it in a secure location. +Before setting up your project, ensure Gradle is installed and that you've added the Maven Settings plugin to your *build.gradle* file as follows: - :::image type="content" source="media/gradle-pat.png" alt-text="Screenshot showing how to create a new personal access token with packaging read & write scopes."::: +```groovy +plugins { + id 'net.linguica.maven-settings' version '0.5' + id 'maven-publish' +} +``` -### Configure build.gradle +#### Configure build.gradle -1. If a *build.gradle* file does not exist in the root of your project, create a new file and name it: *build.gradle*. +1. If a *build.gradle* file doesn't exist in the root of your project, create a new file and name it: *build.gradle*. -1. Add the following section to your *build.gradle* file in both the **repositories** and **publishing.repositories** containers. +1. Add the following section to your *build.gradle* file within both the **repositories** and **publishing.repositories** containers: ```groovy maven { - url 'https://pkgs.dev.azure.com///_packaging//maven/v1' + url 'https://pkgs.dev.azure.com///_packaging//maven/v1' //for organization-scoped feeds use this format: 'https://pkgs.dev.azure.com//_packaging//maven/v1' name '' authentication { basic(BasicAuthentication) } } ``` -1. Here's an example of what your *build.gradle* file should look like: - ```groovy - publishing { - publications { - myPublication(MavenPublication) { - groupId '' - artifactId '' - version '' - artifact '' - } - } - - // Repositories to publish artifacts - repositories { - maven { - url 'https://pkgs.dev.azure.com///_packaging//maven/v1' - name '' - authentication { - basic(BasicAuthentication) - } - } - } - } - - // Repositories to fetch dependencies +Here's an example of what your *build.gradle* file should look like: + +```groovy +publishing { + publications { + library(MavenPublication) { + from components.java + } + } + + // Repositories to publish artifacts repositories { - maven { - url 'https://pkgs.dev.azure.com///_packaging//maven/v1' - name '' - authentication { - basic(BasicAuthentication) - } + maven { + url 'https://pkgs.dev.azure.com///_packaging//maven/v1' //for organization-scoped feeds use this format: 'https://pkgs.dev.azure.com//_packaging//maven/v1' + name '' + authentication { + basic(BasicAuthentication) } + } } - ``` +} + +// Repositories to fetch dependencies +repositories { + maven { + url 'https://pkgs.dev.azure.com///_packaging//maven/v1' //for organization-scoped feeds use this format: 'https://pkgs.dev.azure.com//_packaging//maven/v1' + name '' + authentication { + basic(BasicAuthentication) + } + } +} +``` -### Configure settings.xml +#### Configure settings.xml -1. Open your *settings.xml* file in your home directory and add the following snippet. Replace the placeholders with your feed name, organization name, and the personal access token you created earlier. +1. Open the *settings.xml* file located in the *.m2* directory of your home folder (typically found at *~/.m2/settings.xml* on macOS and Linux, and at *Users\\.m2\settings.xml* on Windows). If the file doesn't exist, you can create a new one. + +1. Add the following snippet, replacing the placeholders with your feed name, organization name, and the personal access token you created earlier. ```xml @@ -114,16 +195,20 @@ plugins { ``` -## Publish artifacts +--- -Run the following command in an elevated command prompt to publish your package to your feed. Your new package will be named: *groupId:artifactId*. +## Publish your packages -```Command -gradle publish -``` +1. Run the following command in your project directory to publish your package to your feed: + + ```command + gradle publish + ``` + +:::image type="content" source="media/publish-package-gradle.png" alt-text="A screenshot displaying a package successfully published to the feed."::: -## Related articles +## Related content -- [Install Maven Artifacts](./install.md) -- [Use packages from Maven Central](./upstream-sources.md) -- [Google Maven Repository upstream source](./google-maven.md) +- [Use packages from Maven Central](upstream-sources.md) +- [Restore Maven packages](./install.md) +- [Use packages from Google Maven Repository](google-maven.md) diff --git a/docs/artifacts/maven/upstream-sources.md b/docs/artifacts/maven/upstream-sources.md index c29bfd0f044..862149d43b4 100644 --- a/docs/artifacts/maven/upstream-sources.md +++ b/docs/artifacts/maven/upstream-sources.md @@ -1,9 +1,9 @@ --- title: Use packages from Maven Central -description: How to use packages from Maven upstream +description: How to use packages from Maven Central upstream source ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 02/15/2022 +ms.date: 11/10/2023 monikerRange: '<= azure-devops' "recommendations": "true" --- @@ -12,40 +12,85 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -With upstream sources, you can use both private packages you've created and public packages from Maven Central. When you enable upstream sources in your feed, Azure Artifacts will save a copy of any packages you install from Maven central. Azure Artifacts also support other Maven upstream sources such as Google Maven Repository, Gradle Plugins, and JitPack. +Using Azure Artifacts upstream sources allows you to use a single feed for hosting both the packages you produce and packages from public registries such as Maven Central. When you add upstream sources to your feed, Azure Artifacts saves a copy of any package installed from upstream. This ensures continued accessibility for your development, even if a public registry suffers an outage. Additionally, Azure Artifacts supports various other Maven upstream sources, including the Google Maven Repository, Gradle Plugins, and JitPack. + +## Prerequisites + +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- An Azure Artifacts feed. > [!NOTE] > Maven snapshots are not supported with Maven upstream sources. ## Enable upstream sources -Follow the instructions below to create a new feed and enable upstream sources: +If you don't have a feed already, follow these instructions to create one, and make sure that you check the *upstream sources* checkbox to enable them. If you already have a feed, move to the [next step](#add-maven-central-upstream) to add Maven Central as an upstream source. [!INCLUDE [](../includes/create-feed.md)] -### Add Maven Central upstream +## Add Maven Central upstream -1. Select the ![gear icon](../../media/icons/gear-icon.png) in the top right of the page to access your feed's settings. +If you checked the *upstream sources* checkbox when creating your feed, Maven Central should already be added as an upstream source. If not, you can add it manually using the following steps: -1. Select **Upstream sources**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Add Upstream**. +1. Select **Artifacts**, and then select the ![gear icon](../../media/icons/gear-icon.png) in the top right corner to navigate to your **Feed Settings**. -1. Select **Public source**, and then select **Maven Central (https://repo.maven.apache.org/maven2/)** from the dropdown menu. +1. Select **Upstream sources**, and then select **Add Upstream**. + +1. Select **Public source**, select **Maven Central (https://repo.maven.apache.org/maven2/)** from the dropdown menu, and then select **Add** when you're done. :::image type="content" source="../media/maven-add-upstream.png" alt-text="A screenshot showing how to add Maven central upstream source."::: -1. Select **Save** when you are done. +1. Select **Save** in the top right corner to save your changes. + + :::image type="content" source="media/save-upstream-sources.png" alt-text="A screenshot showing how to save upstream sources."::: + +## Save package from Maven Central + +Before saving packages from Maven Central, make sure you have set up your project to connect to your feed. If you haven't done so already, follow the instruction in the [project setup](pom-and-settings.md) to set up your Maven project and connect to your feed. The following example illustrates how to save the Kotlin Datetime Library from Maven Central using the command line. + +If you want to save/restore your packages using Azure Pipelines instead, follow the steps in the [Restore Maven packages with Azure Pipelines (YAML/Classic)](../../pipelines/packages/maven-restore.md) tutorial. + +1. Navigate to Maven Central at `https://mvnrepository.com/`. -1. Select **Save** to save your changes. +1. Search for the Kotlin Datetime Library. Select the **Kotlinx Datetime** package, and then select the version you wish to install. - :::image type="content" source="../media/save-upstream-source.png" alt-text="A screenshot showing how to save changes in upstream sources"::: +1. Copy the `` snippet from the **Maven** tab. + + ```xml + + org.jetbrains.kotlinx + kotlinx-datetime-jvm + 0.4.1 + runtime + + ``` + +1. Open your *pom.xml* file and paste the snippet inside your `` tag, and then save your file. + +1. Run the following command from the same path as your *pom.xml* file to install your dependencies: + + ```command + mvn install + ``` + +[!INCLUDE [save-requires-collaborator](../includes/save-requires-collaborator.md)] ## View saved packages You can view the packages you saved from upstreams by selecting the **Maven Central** source from the dropdown menu. -:::image type="content" source="media/maven-central-packages.png" alt-text="A screenshot showing how to filter for packages from Maven Central."::: +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Maven Central** from the source dropdown menu to filter for packages from this upstream. + +1. The *Kotlinx Datetime* package that we saved in the previous step, is now available in our feed. Azure Artifacts automatically saved a copy to our feed when we executed the mvn install command. + +:::image type="content" source="media/saved-kotlin-package-from-upstream.png" alt-text="A screenshot showing a package that was saved from Maven Central."::: > [!TIP] > If Maven is not downloading all your dependencies, run the following command from the project directory to regenerate your project's files: @@ -53,6 +98,6 @@ You can view the packages you saved from upstreams by selecting the **Maven Cent ## Related articles -- [Install Maven Artifacts](./install.md) +- [Search for packages in upstream sources](../how-to/search-upstream.md) +- [Promote packages and manage feed views](../feeds/views.md) - [Configure permissions](../feeds/feed-permissions.md) -- [Configure upstream behavior](../concepts/upstream-behavior.md) \ No newline at end of file diff --git a/docs/artifacts/media/add-new-upstream.png b/docs/artifacts/media/add-new-upstream.png deleted file mode 100644 index 2e8893f4b21..00000000000 Binary files a/docs/artifacts/media/add-new-upstream.png and /dev/null differ diff --git a/docs/artifacts/media/add-upstream-diff-org.png b/docs/artifacts/media/add-upstream-diff-org.png index 76ca0039098..b31c67c44dd 100644 Binary files a/docs/artifacts/media/add-upstream-diff-org.png and b/docs/artifacts/media/add-upstream-diff-org.png differ diff --git a/docs/artifacts/media/add-upstream-same-org.png b/docs/artifacts/media/add-upstream-same-org.png index c3d4b414da6..90669022dbd 100644 Binary files a/docs/artifacts/media/add-upstream-same-org.png and b/docs/artifacts/media/add-upstream-same-org.png differ diff --git a/docs/artifacts/media/adjust-artifacts-usage-limit.png b/docs/artifacts/media/adjust-artifacts-usage-limit.png new file mode 100644 index 00000000000..48607304042 Binary files /dev/null and b/docs/artifacts/media/adjust-artifacts-usage-limit.png differ diff --git a/docs/artifacts/media/artifacts-recycle-bin.png b/docs/artifacts/media/artifacts-recycle-bin.png new file mode 100644 index 00000000000..557dbdd4573 Binary files /dev/null and b/docs/artifacts/media/artifacts-recycle-bin.png differ diff --git a/docs/artifacts/media/billing-settings.png b/docs/artifacts/media/billing-settings.png deleted file mode 100644 index 1e02b632f40..00000000000 Binary files a/docs/artifacts/media/billing-settings.png and /dev/null differ diff --git a/docs/artifacts/media/connect-to-feed-dotnet-server-2020-and-2022.png b/docs/artifacts/media/connect-to-feed-dotnet-server-2020-and-2022.png new file mode 100644 index 00000000000..54fa8642407 Binary files /dev/null and b/docs/artifacts/media/connect-to-feed-dotnet-server-2020-and-2022.png differ diff --git a/docs/artifacts/media/connect-to-feed-nuget-server-2019.png b/docs/artifacts/media/connect-to-feed-nuget-server-2019.png new file mode 100644 index 00000000000..3e8c57cd2e9 Binary files /dev/null and b/docs/artifacts/media/connect-to-feed-nuget-server-2019.png differ diff --git a/docs/artifacts/media/connect-to-feed-nuget-server-2020.png b/docs/artifacts/media/connect-to-feed-nuget-server-2020.png new file mode 100644 index 00000000000..2fddf6a4264 Binary files /dev/null and b/docs/artifacts/media/connect-to-feed-nuget-server-2020.png differ diff --git a/docs/artifacts/media/create-new-feed-azure-devops.png b/docs/artifacts/media/create-new-feed-azure-devops.png new file mode 100644 index 00000000000..7596fbaf3de Binary files /dev/null and b/docs/artifacts/media/create-new-feed-azure-devops.png differ diff --git a/docs/artifacts/media/create-new-feed-dialog.png b/docs/artifacts/media/create-new-feed-dialog.png new file mode 100644 index 00000000000..8cab486471e Binary files /dev/null and b/docs/artifacts/media/create-new-feed-dialog.png differ diff --git a/docs/artifacts/media/create-new-feed-server-2019.png b/docs/artifacts/media/create-new-feed-server-2019.png new file mode 100644 index 00000000000..443356ca3b5 Binary files /dev/null and b/docs/artifacts/media/create-new-feed-server-2019.png differ diff --git a/docs/artifacts/media/create-new-feed-server-2020.png b/docs/artifacts/media/create-new-feed-server-2020.png new file mode 100644 index 00000000000..073d68cb396 Binary files /dev/null and b/docs/artifacts/media/create-new-feed-server-2020.png differ diff --git a/docs/artifacts/media/create-new-feed-server-2022.png b/docs/artifacts/media/create-new-feed-server-2022.png new file mode 100644 index 00000000000..c6708ab7d43 Binary files /dev/null and b/docs/artifacts/media/create-new-feed-server-2022.png differ diff --git a/docs/artifacts/media/create-project-github-copilot-response.png b/docs/artifacts/media/create-project-github-copilot-response.png new file mode 100644 index 00000000000..bba49215c4a Binary files /dev/null and b/docs/artifacts/media/create-project-github-copilot-response.png differ diff --git a/docs/artifacts/media/delete-all-versions.png b/docs/artifacts/media/delete-all-versions.png new file mode 100644 index 00000000000..6bf9f58a518 Binary files /dev/null and b/docs/artifacts/media/delete-all-versions.png differ diff --git a/docs/artifacts/media/delete-cargo-package.png b/docs/artifacts/media/delete-cargo-package.png new file mode 100644 index 00000000000..2f8c24cc5d7 Binary files /dev/null and b/docs/artifacts/media/delete-cargo-package.png differ diff --git a/docs/artifacts/media/delete/delete-package-permanently-confirmation.png b/docs/artifacts/media/delete/delete-package-permanently-confirmation.png new file mode 100644 index 00000000000..2b6eded3943 Binary files /dev/null and b/docs/artifacts/media/delete/delete-package-permanently-confirmation.png differ diff --git a/docs/artifacts/media/delete/delete-package-permanently.png b/docs/artifacts/media/delete/delete-package-permanently.png new file mode 100644 index 00000000000..43a59d69f8f Binary files /dev/null and b/docs/artifacts/media/delete/delete-package-permanently.png differ diff --git a/docs/artifacts/media/delete/recycle-bin.png b/docs/artifacts/media/delete/recycle-bin.png new file mode 100644 index 00000000000..9896e48cf48 Binary files /dev/null and b/docs/artifacts/media/delete/recycle-bin.png differ diff --git a/docs/artifacts/media/delete/unlist-delete-nuget-package-newnav.png b/docs/artifacts/media/delete/unlist-delete-nuget-package-newnav.png index 9ea09fbc935..b463a47ed27 100644 Binary files a/docs/artifacts/media/delete/unlist-delete-nuget-package-newnav.png and b/docs/artifacts/media/delete/unlist-delete-nuget-package-newnav.png differ diff --git a/docs/artifacts/media/enable-upstream.png b/docs/artifacts/media/enable-upstream.png index 9b3b47067a9..22f9b7873f4 100644 Binary files a/docs/artifacts/media/enable-upstream.png and b/docs/artifacts/media/enable-upstream.png differ diff --git a/docs/artifacts/media/get-started-maven/maven-package-published-to-feed-contracted.png b/docs/artifacts/media/get-started-maven/maven-package-published-to-feed-contracted.png new file mode 100644 index 00000000000..73d926c0e7a Binary files /dev/null and b/docs/artifacts/media/get-started-maven/maven-package-published-to-feed-contracted.png differ diff --git a/docs/artifacts/media/get-started-maven/maven-package-published-to-feed.png b/docs/artifacts/media/get-started-maven/maven-package-published-to-feed.png new file mode 100644 index 00000000000..89af4e6a93f Binary files /dev/null and b/docs/artifacts/media/get-started-maven/maven-package-published-to-feed.png differ diff --git a/docs/artifacts/media/github-copilot-app-structure.png b/docs/artifacts/media/github-copilot-app-structure.png new file mode 100644 index 00000000000..46eeea583e8 Binary files /dev/null and b/docs/artifacts/media/github-copilot-app-structure.png differ diff --git a/docs/artifacts/media/github-copilot-csproj-class-relation.png b/docs/artifacts/media/github-copilot-csproj-class-relation.png new file mode 100644 index 00000000000..b65dd968cf2 Binary files /dev/null and b/docs/artifacts/media/github-copilot-csproj-class-relation.png differ diff --git a/docs/artifacts/media/increase-artifacts-beyond-free-tier.png b/docs/artifacts/media/increase-artifacts-beyond-free-tier.png index b959a95fc0f..a628cc2607e 100644 Binary files a/docs/artifacts/media/increase-artifacts-beyond-free-tier.png and b/docs/artifacts/media/increase-artifacts-beyond-free-tier.png differ diff --git a/docs/artifacts/media/maven-add-upstream.png b/docs/artifacts/media/maven-add-upstream.png index 41f2e05c898..6f1a706f00f 100644 Binary files a/docs/artifacts/media/maven-add-upstream.png and b/docs/artifacts/media/maven-add-upstream.png differ diff --git a/docs/artifacts/media/maven-delete-package.png b/docs/artifacts/media/maven-delete-package.png new file mode 100644 index 00000000000..96796ec9d3e Binary files /dev/null and b/docs/artifacts/media/maven-delete-package.png differ diff --git a/docs/artifacts/media/new-feed-dialog-azure-devops.png b/docs/artifacts/media/new-feed-dialog-azure-devops.png index 8cc0cc45d89..51f5189a82e 100644 Binary files a/docs/artifacts/media/new-feed-dialog-azure-devops.png and b/docs/artifacts/media/new-feed-dialog-azure-devops.png differ diff --git a/docs/artifacts/media/new-feed-dialog-devops-server.png b/docs/artifacts/media/new-feed-dialog-devops-server.png new file mode 100644 index 00000000000..5adce4c8eaa Binary files /dev/null and b/docs/artifacts/media/new-feed-dialog-devops-server.png differ diff --git a/docs/artifacts/media/new-feed-dialog.png b/docs/artifacts/media/new-feed-dialog.png index 96464f5ca54..fbb63703a6f 100644 Binary files a/docs/artifacts/media/new-feed-dialog.png and b/docs/artifacts/media/new-feed-dialog.png differ diff --git a/docs/artifacts/media/new-feed-with-scope-dialog.png b/docs/artifacts/media/new-feed-with-scope-dialog.png deleted file mode 100644 index 6abac424568..00000000000 Binary files a/docs/artifacts/media/new-feed-with-scope-dialog.png and /dev/null differ diff --git a/docs/artifacts/media/npm-connect-to-feed-azure-devops.png b/docs/artifacts/media/npm-connect-to-feed-azure-devops.png new file mode 100644 index 00000000000..c3f29a71c2c Binary files /dev/null and b/docs/artifacts/media/npm-connect-to-feed-azure-devops.png differ diff --git a/docs/artifacts/media/npm-deprecate-delete.png b/docs/artifacts/media/npm-deprecate-delete.png new file mode 100644 index 00000000000..9f03c4d0bfb Binary files /dev/null and b/docs/artifacts/media/npm-deprecate-delete.png differ diff --git a/docs/artifacts/media/npm-project-setup-azure-devops.png b/docs/artifacts/media/npm-project-setup-azure-devops.png new file mode 100644 index 00000000000..856cf976414 Binary files /dev/null and b/docs/artifacts/media/npm-project-setup-azure-devops.png differ diff --git a/docs/artifacts/media/npm-project-setup-server-2019-1.png b/docs/artifacts/media/npm-project-setup-server-2019-1.png new file mode 100644 index 00000000000..1366abbbac4 Binary files /dev/null and b/docs/artifacts/media/npm-project-setup-server-2019-1.png differ diff --git a/docs/artifacts/media/npm-project-setup-server-2020-1.png b/docs/artifacts/media/npm-project-setup-server-2020-1.png new file mode 100644 index 00000000000..ad9e3b26ec8 Binary files /dev/null and b/docs/artifacts/media/npm-project-setup-server-2020-1.png differ diff --git a/docs/artifacts/media/npm-project-setup-server-2022-1.png b/docs/artifacts/media/npm-project-setup-server-2022-1.png new file mode 100644 index 00000000000..36fcbeb6259 Binary files /dev/null and b/docs/artifacts/media/npm-project-setup-server-2022-1.png differ diff --git a/docs/artifacts/media/organization-billing-artifacts.png b/docs/artifacts/media/organization-billing-artifacts.png new file mode 100644 index 00000000000..a58681adb60 Binary files /dev/null and b/docs/artifacts/media/organization-billing-artifacts.png differ diff --git a/docs/artifacts/media/packages-public-feed.png b/docs/artifacts/media/packages-public-feed.png new file mode 100644 index 00000000000..2ba2757f014 Binary files /dev/null and b/docs/artifacts/media/packages-public-feed.png differ diff --git a/docs/artifacts/media/proj-org-scoped-feed.png b/docs/artifacts/media/proj-org-scoped-feed.png index 821217fec65..e0697e12ec9 100644 Binary files a/docs/artifacts/media/proj-org-scoped-feed.png and b/docs/artifacts/media/proj-org-scoped-feed.png differ diff --git a/docs/artifacts/media/public-feed-add-upstream.png b/docs/artifacts/media/public-feed-add-upstream.png new file mode 100644 index 00000000000..7f56b8fe3bd Binary files /dev/null and b/docs/artifacts/media/public-feed-add-upstream.png differ diff --git a/docs/artifacts/media/public-feed-configure-upstream.png b/docs/artifacts/media/public-feed-configure-upstream.png new file mode 100644 index 00000000000..58e2a1d6402 Binary files /dev/null and b/docs/artifacts/media/public-feed-configure-upstream.png differ diff --git a/docs/artifacts/media/public-feed-upstream-types.png b/docs/artifacts/media/public-feed-upstream-types.png new file mode 100644 index 00000000000..25621ebf3a4 Binary files /dev/null and b/docs/artifacts/media/public-feed-upstream-types.png differ diff --git a/docs/artifacts/media/python-delete-package.png b/docs/artifacts/media/python-delete-package.png new file mode 100644 index 00000000000..233b0f6b978 Binary files /dev/null and b/docs/artifacts/media/python-delete-package.png differ diff --git a/docs/artifacts/media/recycle-bin.png b/docs/artifacts/media/recycle-bin.png deleted file mode 100644 index 9024d3ce952..00000000000 Binary files a/docs/artifacts/media/recycle-bin.png and /dev/null differ diff --git a/docs/artifacts/media/restore-package.png b/docs/artifacts/media/restore-package.png index 05aa4cc48e7..01d8f0705f5 100644 Binary files a/docs/artifacts/media/restore-package.png and b/docs/artifacts/media/restore-package.png differ diff --git a/docs/artifacts/media/save-upstream.png b/docs/artifacts/media/save-upstream.png new file mode 100644 index 00000000000..ab66b73205b Binary files /dev/null and b/docs/artifacts/media/save-upstream.png differ diff --git a/docs/artifacts/media/server-2019-1-connect-to-feed.png b/docs/artifacts/media/server-2019-1-connect-to-feed.png new file mode 100644 index 00000000000..843f46caf6c Binary files /dev/null and b/docs/artifacts/media/server-2019-1-connect-to-feed.png differ diff --git a/docs/artifacts/media/server-2020-1-connect-to-feed.png b/docs/artifacts/media/server-2020-1-connect-to-feed.png new file mode 100644 index 00000000000..e2592534a5b Binary files /dev/null and b/docs/artifacts/media/server-2020-1-connect-to-feed.png differ diff --git a/docs/artifacts/media/server-2022-1-connect-to-feed.png b/docs/artifacts/media/server-2022-1-connect-to-feed.png new file mode 100644 index 00000000000..7591ba69247 Binary files /dev/null and b/docs/artifacts/media/server-2022-1-connect-to-feed.png differ diff --git a/docs/artifacts/media/settings-vs-storage.png b/docs/artifacts/media/settings-vs-storage.png index f65e4d6ec98..6e1abcd8eb7 100644 Binary files a/docs/artifacts/media/settings-vs-storage.png and b/docs/artifacts/media/settings-vs-storage.png differ diff --git a/docs/artifacts/media/universal-package-delete-package.png b/docs/artifacts/media/universal-package-delete-package.png new file mode 100644 index 00000000000..890407c2154 Binary files /dev/null and b/docs/artifacts/media/universal-package-delete-package.png differ diff --git a/docs/artifacts/npm/media/include-upstream-sources.png b/docs/artifacts/npm/media/include-upstream-sources.png deleted file mode 100644 index c7b33f0205a..00000000000 Binary files a/docs/artifacts/npm/media/include-upstream-sources.png and /dev/null differ diff --git a/docs/artifacts/npm/media/npm-audit-classic-pipeline.png b/docs/artifacts/npm/media/npm-audit-classic-pipeline.png new file mode 100644 index 00000000000..49b5823b8b9 Binary files /dev/null and b/docs/artifacts/npm/media/npm-audit-classic-pipeline.png differ diff --git a/docs/artifacts/npm/media/npm-audit-report.png b/docs/artifacts/npm/media/npm-audit-report.png new file mode 100644 index 00000000000..cb8be019f27 Binary files /dev/null and b/docs/artifacts/npm/media/npm-audit-report.png differ diff --git a/docs/artifacts/npm/media/npm-scopes-connect-to-feed.png b/docs/artifacts/npm/media/npm-scopes-connect-to-feed.png new file mode 100644 index 00000000000..b907e9f7043 Binary files /dev/null and b/docs/artifacts/npm/media/npm-scopes-connect-to-feed.png differ diff --git a/docs/artifacts/npm/media/project-setup-npm.png b/docs/artifacts/npm/media/project-setup-npm.png index 12fa1abda3e..fba4f1f65c0 100644 Binary files a/docs/artifacts/npm/media/project-setup-npm.png and b/docs/artifacts/npm/media/project-setup-npm.png differ diff --git a/docs/artifacts/npm/media/publish-scoped-packages.png b/docs/artifacts/npm/media/publish-scoped-packages.png new file mode 100644 index 00000000000..8966344b0c4 Binary files /dev/null and b/docs/artifacts/npm/media/publish-scoped-packages.png differ diff --git a/docs/artifacts/npm/media/saved-package-from-upstream.png b/docs/artifacts/npm/media/saved-package-from-upstream.png new file mode 100644 index 00000000000..0c750326842 Binary files /dev/null and b/docs/artifacts/npm/media/saved-package-from-upstream.png differ diff --git a/docs/artifacts/npm/npm-audit.md b/docs/artifacts/npm/npm-audit.md index 7c25fd747e8..6e22a57d444 100644 --- a/docs/artifacts/npm/npm-audit.md +++ b/docs/artifacts/npm/npm-audit.md @@ -1,99 +1,114 @@ --- -title: Use npm audit with Azure Artifacts -description: Use npm audit to scan for security vulnerabilities +title: Enhance project security with npm audit +description: Use npm audit to scan and fix package vulnerabilities ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 08/29/2022 +ms.date: 12/18/2023 monikerRange: 'azure-devops' +"recommendations": "true" --- -# Use npm audit +# Use npm audit to detect and fix package vulnerabilities [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -The *npm audit* command scans your project for security vulnerabilities and provides a detailed report of any identified anomaly. Performing security audits is an essential part in identifying and fixing vulnerabilities in the project's dependencies. Fixing these vulnerabilities could prevent things like data loss, service outages, and unauthorized access to sensitive information. +The *npm audit* command performs a thorough scan of your project, identifying potential security vulnerabilities and generating a detailed report that highlights any issues found. Conducting security audits is a vital step in recognizing and resolving vulnerabilities within the project's dependencies. The *npm audit fix* command automatically addresses the detected vulnerabilities, updating insecure package versions to the latest secure releases. +Addressing these vulnerabilities is crucial for preventing potential problems like data loss, service disruptions, and unauthorized access to sensitive information. -Azure DevOps does not support *npm audit*, if you try to run the default *npm audit* command from your pipeline, the task will fail with the following message: *Unexpected end of JSON input while parsing...*. +>[!WARNING] +> Executing *npm audit* will transmit the names of all packages specified in your *package.json* to the public registry. -As a workaround, you can run *npm audit* with the registry argument `--registry=https://registry.npmjs.org/`. This will route the *npm audit* command directly to the public registry. +## Run npm audit locally ->[!WARNING] -> Running *npm audit* will forward all the packages' names from your *package.json* to the public registry. +`npm audit` can be executed locally without needing to authenticate with your feed. This allows you to scan your project for vulnerabilities and receive a detailed report on the detected security issues and their severity. -## Run npm audit from your pipeline +If you want to fix the detected vulnerabilities, you can run `npm audit fix`, but you must be authenticated with your feed in order to do so. This command updates insecure package versions to the latest secure releases available. -Select the YAML or the classic tab to learn how to run npm audit from you Pipeline. +When you run npm audit fix, it not only updates the local project's *package.json* and *package-lock.json* but also syncs these changes with the associated Azure Artifacts feed. The newly secured versions of the packages will be automatically available in your feed. -# [YAML](#tab/yaml) +This synchronization ensures that other projects sharing the same feed will also benefit from these updates. It helps maintain a consistent and secure set of package versions across all projects. + +1. Run the following command in your project directory to perform an npm audit: -Add the following task to your yaml pipeline to only scan for security vulnerabilities. + ```Command + npm audit + ``` + +1. If you want to attempt to upgrade to non-vulnerable package versions, make sure you're [connected to your feed](./npmrc.md#connect-to-feed) first, then run the following command in your project directory: + + ```Command + npm audit fix + ``` -```yaml -steps: -- task: Npm@1 - displayName: 'npm audit' - inputs: - command: custom - customCommand: 'audit --registry=https://registry.npmjs.org/' -``` +After running *npm audit fix*, make sure to conduct a thorough testing on your application to confirm that the updates didn't introduce any breaking changes. If a fix requires a major version update, it's recommended to review the package's release notes for any potential breaking changes. Keep in mind that while a private package with public vulnerable dependencies receives vulnerability alerts, it won't receive fixes through *npm audit fix*. -Instead of only scanning, to scan and also attempt to upgrade to non-vulnerable package versions: +> [!NOTE] +> *npm audit* automatically runs with each execution of *npm install*, but it only works for public packages. -```yaml -steps: -- task: Npm@1 - displayName: 'npm audit fix' - inputs: - command: custom - customCommand: 'npm audit fix --registry=https://registry.npmjs.org/ --package-lock-only' -``` +## Run npm audit from your pipeline -- **command**: the npm command to run. -- **customCommand**: Required when command == custom. +Azure Pipelines doesn't currently support *npm audit*. If you try using the regular *npm audit* command in your pipeline, it will fail. Instead, execute *npm audit* with the *--registry* argument and provide your feed's source URL. # [Classic](#tab/classic) -1. From your pipeline definition, select the `+` sign to add a task to your agent job. +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, select your pipeline, and then select **Edit** to modify it. + +1. From your pipeline definition, select the `+` sign to add a new task. - :::image type="content" source="media/add-new-task.png" alt-text="Screenshot showing how to add a new task to the agent job"::: +1. Search for the **npm** task, and then select **Add** to add it to your pipeline. -1. Search for the **npm** task. Select **Add** to add it to your agent job. +1. Enter a **Display name** for your task, and select **custom** from the **Command** dropdown menu. -1. Fill out the required fields as follows: +1. Paste your custom command into the **Command and arguments** text box: - 1. To only scan for security vulnerabilities use this command: + 1. Use the following command to perform an npm audit and scan for package vulnerabilities. Replace the placeholder with your feed's source URL: - ```Command - audit --registry=https://registry.npmjs.org/ - ``` + ```Command + audit --registry= + ``` - 1. To also attempt to upgrade to non-vulnerable package versions: + 1. If you want to attempt to upgrade to non-vulnerable package versions, use the following command. Replace the placeholder with your feed's source URL: ```Command - audit fix --registry=https://registry.npmjs.org/ --package-lock-only + audit fix --registry= ``` -:::image type="content" source="media/npm-audit-task.png" alt-text="Screenshot showing the npm custom task to run npm audit"::: + :::image type="content" source="./media/npm-audit-classic-pipeline.png" alt-text="A screenshot showing the npm audit task in a classic pipeline."::: ---- +# [YAML](#tab/yaml) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. -## Run npm audit on your development machine +1. Select **Pipelines**, select your pipeline, and then select **Edit** to modify it. -To run npm audit locally, run the following command in a command prompt window: +1. Add the following task to your yaml pipeline to perform an npm audit and scan for package vulnerabilities: -```Command -npm audit --registry=https://registry.npmjs.org/ -``` + ```yaml + steps: + - task: Npm@1 + displayName: 'npm audit' + inputs: + command: custom + customCommand: 'audit --registry=' + ``` -To also attempt to upgrade to non-vulnerable package versions: +1. If you want to upgrade to non-vulnerable package versions, add the following task to your yaml pipeline: + + ```yaml + steps: + - task: Npm@1 + displayName: 'npm audit & fix' + inputs: + command: custom + customCommand: 'audit fix --registry=' + ``` -```Command -audit fix --registry=https://registry.npmjs.org/ --package-lock-only -``` +* * * ## Related articles -- [npm quickstart](../get-started-npm.md). -- [Publish npm packages with Azure Pipelines](../../pipelines/artifacts/npm.md). -- [Artifacts storage consumption](../artifact-storage.md) -- [Delete and recover packages](../how-to/delete-and-recover-packages.md). +- [Use packages from npmjs.com](./upstream-sources.md) +- [Publish npm packages (YAML/Classic)](../../pipelines/artifacts/npm.md) +- [Use Npm scopes in Azure Artifacts](./scopes.md) diff --git a/docs/artifacts/npm/npmrc.md b/docs/artifacts/npm/npmrc.md index 671dcd538ee..a2ca12d7bed 100644 --- a/docs/artifacts/npm/npmrc.md +++ b/docs/artifacts/npm/npmrc.md @@ -1,95 +1,79 @@ --- -title: Set up your client's npmrc -description: How to set up your project and connect to Azure Artifacts feeds +title: Connect your npm project to Azure Artifacts +description: Learn how to set up your npm project and connect to Azure Artifacts ms.assetid: A5364E3A-3918-4318-AAE0-430EA91AD5F1 ms.service: azure-devops-artifacts ms.custom: engagement-fy23 ms.topic: conceptual -ms.date: 04/04/2023 +ms.date: 03/13/2025 monikerRange: '<= azure-devops' +"recommendations": "true" --- -# Set up your project and connect to Azure Artifacts +# Connect your npm project to Azure Artifacts [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Azure Artifacts enables you to publish various package types to your feeds and install packages from both feeds and public registries like npmjs.com. Before we can authenticate with Azure Artifacts, we need to configure our *.npmrc* file, which stores the feed URLs and credentials that Npm uses. This file can be used to customize the behavior of the Npm client, such as setting up proxies, specifying default package locations, or configuring private package feeds. The *.npmrc* file is located in the user's home directory and can also be created at the project level to override the default settings. By editing the *.npmrc* file, users can customize their Npm experience and make it more tailored to their needs. +Azure Artifacts enables developers to manage their packages from various sources, including both public registries like npmjs.com and private feeds. To authenticate with Azure Artifacts, you'll need to configure your npm config file. This file contains feed URLs and credentials used by npm, offering options to customize your npm client behavior, such as setting up proxies, defining default package locations, or configuring private package feeds. The *npmrc* file is typically located in the user's home directory but can also be created at the project level to override default settings. -## Project setup +## Prerequisites -For best practice, we suggest using two separate configuration files. The first file is used to authenticate with Azure Artifacts, while the second file is stored locally and contains your credentials. To set up the second file, place it in your home directory on your development machine and include all of your registry credentials. By using this approach, the Npm client can easily retrieve your credentials for authentication, allowing you to share your configuration file while keeping your credentials secure. These steps will walk you through the process of setting up the first configuration file: +- An Azure DevOps organization. [Create one for free](../../organizations/accounts/create-organization.md). -### [Windows](#tab/windows/) - -::: moniker range="azure-devops" - -1. Sign in to your Azure DevOps organization, and then navigate to your project. - -1. Select **Artifacts**, and then select **Connect to feed**. - - :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot showing how to connect to a feed."::: - -1. Select **npm** from the left navigation pane. +- An Azure DevOps project. Create a new [project](../../organizations/projects/create-project.md#create-a-project) if you don't have one already. -1. If this is the first time using Azure Artifacts with npm, select **Get the tools** and follow the instructions to install the prerequisites. +- An Azure Artifacts feed. [Create one for free](../get-started-npm.md#create-a-feed). -1. Follow the instructions in **Project setup** to set up your config file. +- [Download and install Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). - :::image type="content" source="../media/npm-azure-devops-newnav.png" alt-text="Screenshot showing the steps to set up the project and publish and restore packages."::: +## Connect to Feed -::: moniker-end +Azure Artifacts recommends using two separate configuration files. The first is dedicated to authenticating with Azure Artifacts, while the second should be kept locally to store your credentials. This approach allows you to share your configuration file while keeping your credentials secure. -::: moniker range="azure-devops-2019 || azure-devops-2020 || azure-devops-2022" +To set up the second file, place it in your home directory on your development machine and include all your registry credentials. This enables the npm client to easily access your credentials for authentication. -1. Sign in to your Azure DevOps organization, and then navigate to your project. - -1. Select **Artifacts**, and then select **Connect to feed**. - - :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot showing how to connect to a feed."::: +The following steps guide you through setting up the first configuration file. Select the tab that corresponds to your development environment: -1. Select **npm** from the left navigation pane. +::: moniker range="< azure-devops" -1. If this is the first time using Azure Artifacts with npm, select **Get the tools** and follow the instructions to install the prerequisites. - -1. Follow the instructions in **Project setup** to set up your config file. - - :::image type="content" source="../media/connect-to-feed-devops-server.png" alt-text="Screenshot showing the steps to set up the project and restore packages."::: +> [!NOTE] +> `vsts-npm-auth` is not supported in Azure DevOps Server. ::: moniker-end -::: moniker range="tfs-2018" - -1. Select **Build and Release**. - -1. Select **Packages**, and then select **Connect to feed**. +::: moniker range="azure-devops" - :::image type="content" source="../media/connect-to-feed.png" alt-text="Screenshot showing how to connect to a feed in TFS."::: +### [Windows](#tab/windows/) -1. Select **npm** from the left navigation pane. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Follow the instructions provided in the **Other** tab to set up your project. +1. Select **Artifacts**, and then select **Connect to Feed**. + + :::image type="content" source="../media/npm-connect-to-feed-azure-devops.png" alt-text="A screenshot showing how to connect to a feed in Azure DevOps Services."::: -::: moniker-end +1. Select **npm** from the left sidebar. If this is the first time using Azure Artifacts with npm, make sure you've installed the prerequisites. +1. Follow the instructions in the **Project setup** section to connect to your feed. -> [!TIP] -> Using multiple registries in .npmrc files is supported with [scopes](..//npm/scopes.md) and [upstream sources](../concepts/upstream-sources.md). + :::image type="content" source="../media/npm-project-setup-azure-devops.png" alt-text="A screenshot showing how to set up your npm project."::: -### [Other](#tab/other/) +### [Linux/macOS](#tab/Linuxmac/) -1. Add a *.npmrc* file in your project's directory, in the same directory as your package.json file, and copy the following snippet into it. +1. Add a *.npmrc* file in your project's directory, in the same directory as your *package.json* file, and paste the following snippet into it. - ```Command - registry=https://pkgs.dev.azure.com/ramiMSFTDevOps/_packaging/OrgScopedDemo/npm/registry/ + ``` + registry=https://pkgs.dev.azure.com///_packaging//npm/registry/ always-auth=true ``` -1. Copy the following snippet into your user-level *.npmrc* file (~/.npmrc). Make sure that you don't add it to the *.npmrc* file in your source repository: +### Setup credentials + +1. Copy the following snippet and paste it into your user-level *npmrc* file: - **Organization-scoped feed**: - ```Command + ``` ; begin auth token //pkgs.dev.azure.com//_packaging//npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING] //pkgs.dev.azure.com//_packaging//npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] @@ -102,7 +86,7 @@ For best practice, we suggest using two separate configuration files. The first - **Project-scoped feed**: - ```Command + ``` ; begin auth token //pkgs.dev.azure.com///_packaging//npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING] //pkgs.dev.azure.com///_packaging//npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] @@ -115,151 +99,213 @@ For best practice, we suggest using two separate configuration files. The first 1. Generate a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **packaging read and write** scopes. -1. Encode your newly generated personal access token as follows: - - 1. Run the following command in a command prompt window, and then paste your personal access token when prompted: +1. Run the following command in a command prompt window, and then paste your personal access token when prompted. Once done, copy the generated Base 64 encoded value. - ```Command - node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })" - ``` + ``` + node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })" + ``` - You can also use the following command to convert your personal access token to Base64. +1. If you're on Linux/Mac, you can alternatively use the following command to convert your personal access token to Base 64. Copy the resulting Base64 encoded value. - - **Linux/Mac**: - ```Command - echo -n "YOUR_PERSONAL_ACCESS-TOKEN" | base64 - ``` - 1. Copy the Base64 encoded value. + ``` + echo -n "YOUR_PERSONAL_ACCESS-TOKEN" | base64 + ``` -1. Open your *.npmrc* file and replace the placeholder *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* with your encoded personal access token that you created in the previous step. +1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user *.npmrc* file with the encoded personal access token obtained from the previous step. * * * -> [!NOTE] -> `vsts-npm-auth` is not supported in TFS and Azure DevOps Server. +::: moniker-end -## Pipeline authentication +::: moniker range="azure-devops-2022" -For authentication with your pipeline, Azure Artifacts recommends using the [npm authenticate task](/azure/devops/pipelines/tasks/reference/npm-authenticate-v0). When using a task runner like gulp or Grunt, it's important to add the npm authenticate task to the beginning of your pipeline. By doing so, your credentials are injected into your project's *.npmrc* file and persisted during the pipeline run, enabling subsequent steps to use the credentials in the configuration file. +### [Windows](#tab/windows/) -### [Classic](#tab/classic) +1. Sign in to your Azure DevOps collection, and then navigate to your project. -::: moniker range=">= azure-devops-2019" +1. Select **Artifacts**, and then select **Connect to Feed**. + + :::image type="content" source="../media/server-2022-1-connect-to-feed.png" alt-text="A screenshot showing how to connect to a feed in Azure DevOps Server 2022.1."::: -1. Sign in to your Azure DevOps organization, and then navigate to your project. +1. Select **npm** from the left sidebar, and then follow the instructions in the **Project setup** section to set up your config file. -1. Select **Azure Pipelines**, and then select your pipeline definition. + :::image type="content" source="../media/npm-project-setup-server-2022-1.png" alt-text="A screenshot showing how to set up your npm project in Azure DevOps Server 2022.1."::: -1. Select **Edit** to modify your pipeline. +### [Linux/macOS](#tab/Linuxmac/) -1. Select `+` to add a task to your pipeline. +1. Add a *.npmrc* file in your project's directory, in the same directory as your *package.json* file, and paste the following snippet into it. - :::image type="content" source="../../pipelines/media/get-started-designer/builds-tab-add-task-azure-devops-newnavon.png" alt-text="Screenshot showing how to add the npm authenticate task to your pipeline."::: + ``` + registry=http://///_packaging//npm/registry/ + + always-auth=true + ``` +### Setup credentials -1. Search for the **npm Authenticate** task, and then select **Add** to add it to your pipeline. +1. Copy the following snippet and paste it into your user-level *.npmrc* file: - :::image type="content" source="../media/build-definition/build-definition-npm-auth-task-phase-newnav.png" alt-text="Screenshot showing the npm authenticate task added to the pipeline."::: + - **Collection-scoped feed**: -1. Select your *.npmrc* file. + ``` + ; begin auth token + ////_packaging//npm/registry/:username=DefaultCollection + ////_packaging//npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] + ////_packaging//npm/registry/:email=npm requires email to be set but doesn't use the value + ////_packaging//npm/:username=DefaultCollection + ////_packaging//npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] + ////_packaging//npm/:email=npm requires email to be set but doesn't use the value + ; end auth token + ``` - :::image type="content" source="../media/build-definition/build-definition-npm-auth-task-file.png" alt-text="Screenshot showing how to add your *.npmrc* file."::: + - **Project-scoped feed**: -1. Select **Save & queue** when you're done. + ``` + ; begin auth token + /////_packaging//npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING] + /////_packaging//npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] + /////_packaging//npm/registry/:email=npm requires email to be set but doesn't use the value + /////_packaging//npm/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING] + /////_packaging//npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] + /////_packaging//npm/:email=npm requires email to be set but doesn't use the value + ; end auth token + ``` + +1. Generate a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **packaging read and write** scopes. + +1. Run the following command in a command prompt window, and then paste your personal access token when prompted. Once done, copy the generated Base 64 encoded value. + + ``` + node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })" + ``` + +1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user *.npmrc* file with the encoded personal access token obtained from the previous step. + +* * * ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="azure-devops-2020" -1. Select **Build and Release**, and then select **Builds**. +### [Windows](#tab/windows/) + +1. Sign in to your Azure DevOps collection, and then navigate to your project. - :::image type="content" source="../../pipelines/media/get-started-designer/navigate-to-builds-tab-tfs-2018-2.png" alt-text="Screenshot showing how to access your builds in TFS."::: +1. Select **Artifacts**, and then select **Connect to feed**. + + :::image type="content" source="../media/server-2020-1-connect-to-feed.png" alt-text="A screenshot showing how to connect to a feed in Azure DevOps Server 2020.1."::: -1. Select your pipeline, and then select **Edit**. +1. Select **npm** from the left, and then follow the instructions in **Project setup** to set up your config file. -1. Select `+` to add a task to your pipeline. + :::image type="content" source="../media/npm-project-setup-server-2020-1.png" alt-text="A screenshot showing how to set up your npm project in Azure DevOps Server 2020.1."::: - :::image type="content" source="../../pipelines/media/get-started-designer/builds-tab-add-task-tfs-2018-2.png" alt-text="Screenshot showing how to add a new task to your pipeline."::: +### [Linux/macOS](#tab/Linuxmac/) -1. Search for the **npm Authenticate** task, and then select **Add** to add it to your pipeline. +1. Add a *.npmrc* file in your project's directory, in the same directory as your package.json file, and paste the following snippet into it: - :::image type="content" source="../media/build-definition/build-definition-npm-auth-task-phase.png" alt-text="Screenshot showing the npm authenticate task."::: + ``` + registry=http://///_packaging//npm/registry/ + + always-auth=true + ``` +### Setup credentials -1. Select your *.npmrc* file. +1. Copy the following snippet and paste it into your user-level *.npmrc* file: - :::image type="content" source="../media/build-definition/build-definition-npm-auth-task-file.png" alt-text="Screenshot showing how to add your .npmrc file to the npm authenticate task."::: + - **Collection-scoped feed**: -1. Select **Save & queue** when you're done. + ``` + ; begin auth token + ////_packaging//npm/registry/:username=DefaultCollection + ////_packaging//npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] + ////_packaging//npm/registry/:email=npm requires email to be set but doesn't use the value + ////_packaging//npm/:username=DefaultCollection + ////_packaging//npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] + ////_packaging//npm/:email=npm requires email to be set but doesn't use the value + ; end auth token + ``` -::: moniker-end + - **Project-scoped feed**: -### [YAML](#tab/yaml) + ``` + ; begin auth token + /////_packaging//npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING] + /////_packaging//npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] + /////_packaging//npm/registry/:email=npm requires email to be set but doesn't use the value + /////_packaging//npm/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING] + /////_packaging//npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] + /////_packaging//npm/:email=npm requires email to be set but doesn't use the value + ; end auth token + ``` -```yaml -- task: npmAuthenticate@0 - inputs: - workingFile: .npmrc ## Path to the npmrc file - customEndpoint: #Optional ## Comma-separated list of npm service connection names for registries from external organizations. For registries in your org, leave this blank -``` +1. Generate a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **packaging read and write** scopes. -* * * +1. Run the following command in a command prompt window, and then paste your personal access token when prompted. Once done, copy the generated Base 64 encoded value. -> [!NOTE] -> To grant your pipeline access to your feed, make sure you set the build service role to **Contributor** in your feed settings. + ``` + node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })" + ``` -:::image type="content" source="../media/project-collection-contributor.png" alt-text="A screenshot showing the build service roles in feed settings."::: +1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user *.npmrc* file with the encoded personal access token obtained from the previous step. -> [!NOTE] -> If your organization is using a firewall or a proxy server, make sure you allow the appropriate domain URLs. For more information, please refer to the list of [Allowed IP addresses and domain URLs](../../organizations/security/allow-list-ip-url.md). +* * * -## Troubleshoot +::: moniker-end -##### vsts-npm-auth is not recognized +> [!TIP] +> Using multiple registries in .npmrc files is supported with [scopes](..//npm/scopes.md) and [upstream sources](../concepts/upstream-sources.md). -If you encounter the following error while running your project: +::: moniker range="azure-devops" -- Cmd: `'vsts-npm-auth' is not recognized as an internal or external command, operable program or batch file.` -- PowerShell: `vsts-npm-auth : The term 'vsts-npm-auth' is not recognized as the name of a cmdlet, function, script file, or operable program.` +## Troubleshoot -Then it's likely that the npm modules folder is not added to your path. To resolve this issue, rerun the Node.js setup and make sure to select the `Add to PATH` option. +#### vsts-npm-auth is not recognized -:::image type="content" source="./media/node-setup.png" alt-text="A Screenshot showing how to set up node.js."::: +This error indicates that the npm modules folder hasn't been added to your path. Rerun the Node.js setup and make sure to select the `Add to PATH` option. Alternatively, you can add the npm modules folder to your path by modifying the PATH variable to `%APPDATA%\npm` in Command Prompt or `$env:APPDATA\npm` in PowerShell. -As an alternative solution, you can add the npm modules folder to your path by editing the PATH variable `%APPDATA%\npm` in Command Prompt or `$env:APPDATA\npm` in PowerShell. +:::image type="content" source="./media/node-setup.png" alt-text="A Screenshot showing how to set up node.js."::: -##### Unable to authenticate +#### Unable to authenticate -If you're running into a E401 error: `code E401 npm ERR! Unable to authenticate`. Run the `vsts-npm-auth` command with **-F** flag to reauthenticate. +- Error: *code E401 npm ERR! Unable to authenticate*: -> Run the `vsts-npm-auth` command with **-F** flag to reauthenticate: -```Command -vsts-npm-auth -config .npmrc -F -``` + ``` + vsts-npm-auth -config .npmrc -F + ``` -##### Reset vsts-npm-auth +#### Reset vsts-npm-auth -Follow the steps below to modify/reset your vsts-npm-auth credentials: +Follow these steps to reset your vsts-npm-auth credentials: -- Uninstall vsts-npm-auth. +1. Uninstall vsts-npm-auth: - ```command + ``` npm uninstall -g vsts-npm-auth ``` -- Clear your npm cache. +1. Clear your npm cache: - ```command + ``` npm cache clean --force ``` -- Delete your *.npmrc* file. +1. Delete your *.npmrc* file. -- Reinstall vsts-npm-auth. +1. Reinstall vsts-npm-auth: - ```command + ``` npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false ``` -## Related articles +#### Unable to publish + +If you encounter a 403 error, it may indicate a name conflict. In Azure Artifacts, packages are immutable, meaning that once you publish a package to your feed, its version number is permanently reserved. Even if you delete it, you can't publish a new package with the same version number. To address this issue, update the package version in your *package.json* file, and then try again. + +::: moniker-end + +## Related content + +- [Publish npm packages (CLI)](./publish.md) - [Publish npm packages (YAML/Classic)](../../pipelines/artifacts/npm.md) -- [Use npm scopes](./scopes.md) -- [Use npm audit](./npm-audit.md) + +- [Use packages from npmjs.com](./upstream-sources.md) diff --git a/docs/artifacts/npm/publish.md b/docs/artifacts/npm/publish.md index 67a05b80d02..d263676e6a3 100644 --- a/docs/artifacts/npm/publish.md +++ b/docs/artifacts/npm/publish.md @@ -1,32 +1,63 @@ --- -title: Publish and restore npm packages using the command line -description: How to publish and restore npm packages from the command line +title: Publish npm packages from the command line +description: Learn how to connect to your feed and publish npm packages from the command line. ms.assetid: 85773969-1491-4242-A060-BD5D193961A0 ms.service: azure-devops-artifacts ms.custom: engagement-fy23 -ms.topic: conceptual -ms.date: 01/24/2023 -monikerRange: '<= azure-devops' +ms.topic: tutorial +ms.date: 02/21/2025 +monikerRange: "<=azure-devops" +"recommendations": "true" --- -# Publish and restore npm packages from the command line +# Publish npm packages from the command line -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] -Follow this quick tutorial to learn how to connect your npm client to your feed and publish your packages using the command line. If you don't have a feed yet, you can follow the steps in the quickstart to [Create your own feed](../get-started-npm.md#create-a-feed). +This article guides you through authenticating with your Azure Artifacts feed and publishing npm packages from the command line. -## Project setup +## Prerequisites -1. Navigate to your project,and then select **Artifacts** then select **Connect to feed**. +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An Azure Artifacts [feed](../get-started-nuget.md#create-feed).
- [Download and install Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). | -1. Select **npm** from the left navigation panel, and then follow the instructions under **Project setup** to configure your .npmrc file and connect to your feed. If this is your first time using Azure Artifacts with npm on your machine, make sure you select **Get the tools** to download and install the prerequisites. +## Get the tools - :::image type="content" source="../npm/media/project-setup-npm.png" alt-text="Screenshot showing how to set up your project"::: +If this is your first time using Azure Artifacts with npm on your machine, follow the steps below to set up your environment: -[!INCLUDE [](../includes/npm/publish-restore.md)] +### [Windows](#tab/windows/) -## Related articles +1. Download [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). + +1. Run the following command to install `vsts-npm-auth`. + + ``` + npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false + ``` + +### [Other](#tab/other/) + +1. Download [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). + +1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scope. + +--- + +## Publish packages + +1. If you haven't authenticated with your feed yet, follow the steps in the [Project setup](npmrc.md#connect-to-feed) to connect to your feed and then proceed with the next step once you're done. + +1. Run the following command in your project directory to publish the npm packages listed in your *package.json*: + + ``` + npm publish + ``` + +## Related content + +- [Restore npm packages (CLI)](restore-npm-packages.md) -- [Use packages from npmjs.com](../npm/upstream-sources.md) - [Publish npm packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/npm.md) -- [Use npm audit](../npm/npm-audit.md) \ No newline at end of file + +- [Use packages from npmjs.com](../npm/upstream-sources.md) diff --git a/docs/artifacts/npm/restore-npm-packages.md b/docs/artifacts/npm/restore-npm-packages.md new file mode 100644 index 00000000000..7ec4e51aeeb --- /dev/null +++ b/docs/artifacts/npm/restore-npm-packages.md @@ -0,0 +1,66 @@ +--- +title: Restore npm packages from the command line +description: Learn how to authenticate with your Azure Artifacts feed and restore npm packages from the command line. +ms.service: azure-devops-artifacts +ms.topic: tutorial +ms.date: 02/21/2025 +monikerRange: '<= azure-devops' +--- + +# Restore npm packages from the command line + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +This article guides you through authenticating with your Azure Artifacts feed and restoring npm packages from the command line. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An Azure Artifacts [feed](../get-started-nuget.md#create-feed). | + +## Get the tools + +If this is your first time using Azure Artifacts with npm on your machine, follow the steps below to set up your environment: + +### [Windows](#tab/windows/) + +1. Download [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). + +1. Run the following command to install `vsts-npm-auth`. + + ``` + npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false + ``` + +### [Other](#tab/other/) + +1. Download [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). + +1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scope. + +--- + +## Restore packages + +1. If you haven't authenticated with your feed yet, follow the steps in the [Project setup](npmrc.md#connect-to-feed) to connect to your feed and then proceed with the next step once you're done. + +1. Run the following command in your project directory to restore all your npm packages: + + ``` + npm install + ``` + +1. If you want to restore a specific package, run the following command in your project directory: + + ``` + npm install --save + ``` + +## Related content + +- [Publish npm packages (CLI)](publish.md) + +- [Publish npm packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/npm.md) + +- [Use packages from npmjs.com](../npm/upstream-sources.md) \ No newline at end of file diff --git a/docs/artifacts/npm/scopes.md b/docs/artifacts/npm/scopes.md index 38cc062f034..27946a66275 100644 --- a/docs/artifacts/npm/scopes.md +++ b/docs/artifacts/npm/scopes.md @@ -4,16 +4,17 @@ description: How to use npm scopes in Azure Artifacts ms.assetid: c88868bd-8101-48f3-b76d-17c858181fda ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 06/08/2022 +ms.date: 09/11/2023 monikerRange: '<= azure-devops' --- -# Npm scopes +# Use Npm scopes in Azure Artifacts [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Npm scopes are a way of grouping related packages together. A scope allows you to create a package with the same name as other packages created by different users without conflicts. Using scopes, you can separate public and private packages by adding the scope prefix *@SCOPE_NAME* and configuring the *.npmrc* file to only use a feed for that scope. -With Azure Artifacts, you can publish and download both scoped and non-scoped packages to/from feeds or public registries. Using npm scopes is also useful with self-hosted on-premise servers that do not have internet access because setting up upstream sources in that case is not possible. Using scopes: +Npm scopes serve as a means to categorize related packages into groups. These scopes enable you to create packages with identical names to those created by different users without encountering conflicts. By using scopes, you have the ability to segregate public and private packages by adding the scope prefix *@scopeName* and configuring the .npmrc file to exclusively use a feed with that particular scope. + +Azure Artifacts provides the capability to publish and download both scoped and nonscoped packages from feeds or public registries. Npm scopes are particularly valuable when working with self-hosted on-premises servers lacking internet access, as configuring upstream sources in such scenarios isn't feasible. In summary, when using scopes: - We don't have to worry about name collisions. - No need to change the npm registry in order to install or publish our packages. @@ -23,24 +24,76 @@ With Azure Artifacts, you can publish and download both scoped and non-scoped pa [!INCLUDE [](../includes/npm/npmrc.md)] -In your .npmrc file, replace `registry=` with `@SCOPE_NAME:registry=`. Make sure you add the scope and package names to your *package.json* file: `{ "name": "@SCOPE_NAME/PACKAGE_NAME" }`. +## Scope setup + +In your .npmrc file, replace `registry=` with `@ScopeName:registry=`. + +Make sure to include both the scope and package names in your package.json file as follows: `{ "name": "@ScopeName/PackageName" }`. See the examples below: + +- **Organization-scoped feed**: -```npmrc -@[SCOPE_NAME]:registry=https://pkgs.dev.azure.com/[ORGANIZATION_NAME]/_packaging/[FEED_NAME]/npm/registry/ + ```.npmrc file + @ScopeName:registry=https://pkgs.dev.azure.com//_packaging//npm/registry/ + + always-auth=true + ``` -always-auth=true -``` + ```package.json + { + "name": "@ScopeName/PackageName" + } + ``` + +- **Project-scoped feed**: + + ```.npmrc file + @ScopeName:registry=https://pkgs.dev.azure.com///_packaging//npm/registry/ + + always-auth=true + ``` + + ```package.json + { + "name": "@ScopeName/PackageName" + } + ``` -```package.json -{ -"name": "[@SCOPE_NAME]/[PACKAGE_NAME]" -} +- **Example**: + + + ```.npmrc file + @local:registry=https://pkgs.dev.azure.com/FabrikamOrg/NpmDemo/_packaging/FabrikamFeed/npm/registry/ + + always-auth=true + ``` + + ```package.json + { + "name": "@demo/js-e2e-express-server", + "version": "2.0.0", + "description": "JavaScript server written with Express.js", + "main": "index.js", + "directories": { + "doc": "docs", + "test": "test" + } + ``` + +## Publish scoped packages + +Open a command prompt window, navigate to your project directory, and run the following command to publish your scoped package. In our example, our package is listed under the @local view. + +```Command +npm publish ``` + +:::image type="content" source="media/publish-scoped-packages.png" alt-text="A screenshot showing a scoped package in an Azure Artifacts feed."::: + ## Upstream sources vs scopes -Upstream sources give you the most flexibility to use a combination of scoped and non-scoped packages in your feed, as well as scoped and non-scoped packages from public registries such as npmjs.com. +Upstream sources give you the most flexibility to use a combination of scoped and nonscoped packages in your feed, as well as both scoped and nonscoped packages from public registries like npmjs.com. -Scopes add another restriction when naming your packages: each package name must start with `@`. If you want to publish your private packages to public registries, you must do so with the scopes intact. If you remove package scopes when deploying your packages, you'll need to update all the references in your *package.json*. With that in mind, scopes can be a viable alternative to [upstream sources](../concepts/upstream-sources.md). +Scopes, however, impose a naming restriction on your packages: each package name must start with `@`. If you want to publish your private packages to public registries, you must do so with the scopes intact. If you remove package scopes when deploying your packages, you'll need to update all the references in your *package.json* file. With that in mind, scopes can serve as a viable alternative to [upstream sources](../concepts/upstream-sources.md). ## Related articles diff --git a/docs/artifacts/npm/upstream-sources.md b/docs/artifacts/npm/upstream-sources.md index 807000e8130..93d051e0e72 100644 --- a/docs/artifacts/npm/upstream-sources.md +++ b/docs/artifacts/npm/upstream-sources.md @@ -1,72 +1,87 @@ --- title: Use packages from npmjs.com -description: Use packages from npmjs.com using scopes or upstream sources +description: How to consume packages from npmjs.com upstream source ms.assetid: E2DB1217-7113-4A75-A66D-3CADDB07AD37 ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 02/14/2022 +ms.date: 11/29/2023 monikerRange: '<= azure-devops' +"recommendations": "true" --- # Use packages from npmjs.com [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The npm client is designed to work with a single primary *registry* (what Azure Artifacts calls a *feed*). It also supports secondary *scoped* registries. Scoped registries can only be used to install packages whose names begin with the scope prefix, so their usage is more restrictive. If you want to use both private packages you've created **and** public packages from npmjs.com, we recommend using upstream sources. +The npm client is designed to work with one main registry (known as a feed in Azure Artifacts) at a time. However, it does support additional scoped registries. If you plan to use both private packages and public packages from npmjs.com, it's recommended to use upstream sources. +Once you enable upstream sources in your feed, Azure Artifacts automatically saves a copy of any installed package to your feed. This offers the greatest flexibility, allowing you to use a mix of scoped and non-scoped packages in your feed, including both scoped and non-scoped packages from npmjs.com. -The npmjs.com upstream source allows you to merge the contents of npmjs.com into your feed such that the npm client can install packages from both locations. Enabling upstream sources also automatically enables saving of packages you use from the upstream source. **This is the recommended way to use Azure Artifacts with npm.** Upstreams give you the most flexibility to use a combination of scoped- and nonscoped packages in your feed, as well as scoped- and nonscoped packages from npmjs.com. +## Prerequisites -## Enable npmjs.com as an upstream +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. -You can use npmjs.com as an upstream source with new and existing feeds. +- An Azure Artifacts feed. -### On a new feed +- Download [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). -- [Create a new feed](../get-started-npm.md#create-a-feed). Make sure you check the **Include packages from common public sources** checkbox. +## Enable upstream sources - :::image type="content" source="media/include-upstream-sources.png" alt-text="Screenshot showing how to enable upstream sources"::: +If you haven't created a feed yet, follow these steps to create a new one and make sure to check the upstream sources checkbox to enable them. If you already have a feed, proceed to the [next step](#add-npmjs-upstream) to add npmjs as an upstream source. -### On an existing feed +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select **Create Feed**. + +1. Provide a descriptive **Name** for your feed, set its **Visibility** and **Scope**. Check the **Upstream sources** checkbox to include packages from public registries. + +1. Select **Create** when you're done. + +## Add npmjs upstream + +If you checked the upstream sources checkbox during the creation of your feed, npmjs should have been added automatically. If not, you can add it manually as follows: + +1. Sign in to your Azure DevOps organization, and then navigate to your project. 1. Select **Artifacts**, and then select your feed. -1. Navigate to **Feed settings** by selecting the gear icon ![gear icon](../../media/icons/gear-icon.png) button. +1. Select the gear icon button ![gear icon](../../media/icons/gear-icon.png) to navigate to **Feed settings**. 1. Select **Upstream sources**, and then select **Add Upstream**. - :::image type="content" source="./media/npm-new-upstream.png" alt-text="A screenshot showing how to add an upstream source."::: - -1. Select **Public source**, and then select **npmjs** from the dropdown menu. +1. Select **Public source**, and then select **npmjs (https://registry.npmjs.org/)** from the dropdown menu. -1. Select **Save** when you are done. +1. Select **Add** when you're done, and then select **Save** at the top right corner to save your changes. -1. Select **Save** to save your changes. +## Install packages from npmjs - :::image type="content" source="../media/save-upstream-source.png" alt-text="A screenshot showing how to save changes in upstream sources"::: +Before you save packages from npmjs, make sure your project is set up to connect to your feed. If you haven't done this yet, follow the provided instructions to [set up your npm project](npmrc.md#connect-to-feed) and connect to your feed. In this example, we'll install the *Axios* library for making HTTP requests: -## Filter to saved packages +1. Navigate to npmjs at `https://www.npmjs.com//`. -You can view the packages you saved from upstreams by selecting your **Source** from the dropdown menu. +1. Search for the *Axios* package, and then select it to navigate to the details page. -::: moniker range=">= azure-devops-2019" +1. Copy the install command to your clipboard. -:::image type="content" source="media/view-cached-packages-newnav.png" alt-text="Screenshot of the filtered npm packages"::: +1. In a command prompt window, navigate to your project's directory and run your install command. -::: moniker-end + ```Command + npm install axios + ``` -::: moniker range="tfs-2018" +[!INCLUDE [save-requires-collaborator](../includes/save-requires-collaborator.md)] +## View saved packages -:::image type="content" source="media/view-cached-packages.png" alt-text="Screenshot of the filtered npm packages in TFS"::: +1. Sign in to your Azure DevOps organization, and then navigate to your project. -::: moniker-end +1. Select **Artifacts**, and then select your feed from the dropdown menu. -## Scopes +1. Select **npmjs** from the source menu. The *Axios* package we installed earlier is now available in our feed. Azure Artifacts automatically saved a copy to our feed upon executing the install command. -Using scopes instead of upstream sources limits your private package consumption to those with the `@scope` prefix e.g. `@fabrikam/core` but enables you to consume public packages **directly** from npmjs.com, see [npm scopes](scopes.md) for more details. + :::image type="content" source="media/saved-package-from-upstream.png" alt-text="A screenshot showing the axios package that was saved from upstream."::: ## Related articles -- [Publish npm packages (CLI)](./publish.md) +- [Publish and restore npm packages (CLI)](./publish.md) - [Publish npm packages (YAML/Classic)](../../pipelines/artifacts/npm.md) -- [Use npm audit](./npm-audit.md) +- [Npm scopes](scopes.md) diff --git a/docs/artifacts/nuget/consume.md b/docs/artifacts/nuget/consume.md deleted file mode 100644 index 188309a35d3..00000000000 --- a/docs/artifacts/nuget/consume.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Install NuGet packages using Visual Studio -description: How to use Visual Studio to consume NuGet packages from Azure Artifacts feeds and NuGet.org -ms.assetid: BF919E28-65C2-40E3-8A49-5BF0DA3DE598 -ms.service: azure-devops-artifacts -ms.custom: engagement-fy23 -ms.topic: conceptual -ms.date: 01/26/2023 -monikerRange: '<= azure-devops' ---- - -# Install NuGet packages with Visual Studio - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Using Azure Artifacts and Visual Studio, you can set up your development machine to access and install packages from your feeds and public registries such as NuGet.org. - -## Get source URL - -To set up Visual Studio to access your feed as a package source, we must first get the *Source URL*: - -[!INCLUDE [](../includes/nuget/nuget-consume-endpoint.md)] - -## Set up Visual Studio - -#### [Windows](#tab/windows/) - -1. Open Visual Studio, and then select **Tools** > **Options**. - -1. Select **NuGet Package Manager**, and then select **Package Sources**. - -1. Enter your feed's **Name** and the **Source** URL you copied in the previous step, and then select the green (+) sign to add a new package source. - -1. If you enabled [upstream sources](upstream-sources.md) in your feed, clear the **nuget.org** checkbox. - -1. Select **OK** when you're done. - - :::image type="content" source="../media/vs-addsource.png" alt-text="Screenshot showing how to add a new package source in Visual Studio - Windows"::: - -#### [macOS](#tab/macOS/) - -1. Create a new [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). - -1. Open visual studio, and then select **Preferences** from the menu bar. - -1. Select **NuGet**, and then select **Sources**. - -1. Select **Add**, and then enter your feed's **Name**, the **Source** URL you copied in the previous step, a userName (any string), and your personal access token. Select **OK** when you're done. - -1. If you enabled upstream sources in your feed, clear the **nuget.org** checkbox. - -1. Select **OK** when you're done. - - :::image type="content" source="../media/vs-mac-settings.png" alt-text="A screenshot showing how to add a new package source in Visual Studio - macOS."::: - ---- - -## Install packages from your feed - -Now that you set up Visual Studio and added a new package source pointing to your feed, you can now search and install packages right from Visual Studio package manager. - -1. Open Visual Studio, and then right-click on your project in the Solution Explorer, then select **Manage NuGet Packages...**. - -1. Select **Browse**, and then select your feed from the **Package source** dropdown menu. - - :::image type="content" source="../media/select-pkg-src.png" alt-text="A screenshot showing the package source dropdown menu in Visual Studio."::: - -1. Use the search bar to look for packages in your feed. - -> [!NOTE] -> If you enabled [upstream sources](../nuget/upstream-sources.md), any packages that haven't been saved to your feed (by using them at least once) won't appear in the search result. - -## Install packages from NuGet.org - -1. Navigate to *NuGet.org* and search for the package you want to install. - -1. Select **Package Manager**, and then copy the *Install-Package* command. - -1. Open Visual Studio, and then select **Tools** > **NuGet Package Manager** > **Package Manager Console** to open the package manager console. - -1. Paste the install command into the Package Manager Console and then press Enter. - -## Related articles - -- [Publish NuGet packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/nuget.md) -- [Publish and restore NuGet packages from the command line (NuGet.exe)](./publish.md) -- [Publish packages to NuGet.org](./publish-to-nuget-org.md) -- [Configure upstream sources](../how-to/set-up-upstream-sources.md) diff --git a/docs/artifacts/nuget/dotnet-exe.md b/docs/artifacts/nuget/dotnet-exe.md index 1f2b14da995..774fbe89af1 100644 --- a/docs/artifacts/nuget/dotnet-exe.md +++ b/docs/artifacts/nuget/dotnet-exe.md @@ -1,44 +1,37 @@ --- -title: Publish and restore packages with dotnet CLI -description: How to connect to a feed and use the dotnet CLI to publish and restore NuGet packages +title: Publish NuGet packages with dotnet CLI +description: Learn how to connect to a feed and use the dotnet CLI to publish NuGet packages. ms.assetid: CA2DCB9D-93FB-4E2D-B953-BF78D5687B35 ms.service: azure-devops-artifacts ms.custom: devx-track-dotnet -ms.topic: conceptual -ms.date: 06/28/2022 -monikerRange: '<= azure-devops' -"recommendations": "true" +ms.topic: tutorial +ms.date: 01/13/2025 +monikerRange: '>= azure-devops-2020' --- -# Publish and restore NuGet packages from the command line (dotnet) +# Publish NuGet packages from the command line (dotnet) [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -With Azure Artifacts, you can publish and restore your NuGet packages to/from your feed and share them with others based on your feed's visibility settings. This article will guide you through setting up your project to publish and restore your packages using the dotnet command-line interface. +This guide walks you through configuring your project to publish NuGet packages using the dotnet command-line interface. ## Prerequisites -- An Azure DevOps organization. [Create an organization](../../organizations/accounts/create-organization.md), if you don't have one already. +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An Azure Artifacts [feed](../get-started-nuget.md#create-feed).
- Download and install the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider).
- Download and install [.NET Core SDK (2.1.400+)](https://dotnet.microsoft.com/en-us/download). | -- An Azure Artifacts feed. [Create a new feed](../get-started-nuget.md#create-a-feed) if you don't have one already. +## Connect to a feed -- [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider). +::: moniker range="azure-devops" -- Download and install [.NET SDK](https://dotnet.microsoft.com/en-us/download). - -## Connect to feed - -::: moniker range=">= azure-devops-2019" +1. Sign in to your Azure DevOps organization, and then navigate to your project. 1. Select **Artifacts**, and then select your feed from the dropdown menu. -1. Select **Connect to feed**. - - :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot showing how to connect to a feed."::: - -1. Select **dotnet** from the *NuGet* section. +1. Select **Connect to feed**, and then select **dotnet** from the *NuGet* section on the left. -1. Create a *nuget.config* file in the same folder as your .csproj or .sln file. Copy the following XML snippet and paste it into your new file: +1. Create a *nuget.config* file in the same folder as your *csproj* or *sln* file. Copy the following XML snippet and paste it into your new file, replacing the placeholders with the relevant information: - Organization-scoped feed: @@ -65,70 +58,73 @@ With Azure Artifacts, you can publish and restore your NuGet packages to/from yo ``` ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="azure-devops-2020 || azure-devops-2022" -1. Select **Build and Release** > **Packages**. +1. Sign in to your Azure DevOps server, and then navigate to your project. -1. Select your feed from the dropdown menu or [create one](../get-started-nuget.md#create-a-feed) if you haven't. +1. Select **Artifacts**, and then select your feed. -1. Select **Connect to feed**. +1. Select **Connect to Feed**, and then select **dotnet** from the left navigation pane. - :::image type="content" source="../media/connect-to-feed.png" alt-text="A screenshot showing how to connect to a feed in TFS."::: +1. Follow the instructions in the **Project setup** section to connect to your feed. -1. Select **NuGet** and follow the instruction to connect to your feed. + :::image type="content" source="../media/connect-to-feed-dotnet-server-2020-and-2022.png" alt-text="A screenshot showing how to connect to a feed with dotnet in Azure DevOps Server 2020 and 2022." lightbox="../media/connect-to-feed-dotnet-server-2020-and-2022.png"::: + +> [!NOTE] +> dotnet is not supported in Azure DevOps Server 2019. ::: moniker-end -## Publish packages +## Publish packages to a feed in the same organization -To publish a package to your feed, run the following command in an elevated command prompt. Replace the placeholders with the appropriate information: +Run the following command to publish a package to your feed. Replace the placeholders with the appropriate values: -```Command -dotnet nuget push --source https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json --api-key +```CLI +dotnet nuget push --source https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json --api-key ``` -> [!NOTE] -> The `api-key` is only used as a placeholder. +**Example**: + +```CLI +dotnet nuget push --source https://pkgs.dev.azure.com/MyOrg/MyProject/_packaging/MyFeed/nuget/v3/index.json --api-key AZ bin/MyPackage.5.0.2.nupkg +``` -- **Example**: - ```Command - dotnet nuget push MyPackage.5.0.2.nupkg --source https://pkgs.dev.azure.com/MyOrg/MyProject/_packaging/MyFeed/nuget/v3/index.json --api-key AZ - ``` +> [!NOTE] +> The `api-key` is required, but you can provide any string as its value when publishing to an Azure Artifacts feed. + +## Publish packages to a feed in another organization -## Publish packages from external sources +To publish your NuGet packages to a feed in a different Azure DevOps organization, you must first create a personal access token (PAT) in the target organization. -1. Create a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) (PAT) with **packaging read and write** scope. +1. Navigate to the organization hosting the target feed and create a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) (PAT) with **Packaging** > **Read & write** scope. -1. Add your package source to your nuget.config file. This will add your PAT to your nuget.config file. Make sure to store this file in a safe place, and do not check this file into source control. +1. Replace the ** placeholder with your personal access token, and then run the following command to add your package source to your *nuget.config* file. Ensure that this file is stored securely and is not checked into source control. - ```Command + ```CLI dotnet nuget add source https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json --name --username --password --configfile ``` -1. Publish your package: +1. Run the following command to publish your package: - ```Command - dotnet nuget push --source --api-key + ```CLI + dotnet nuget push --source --api-key ``` -- **Example**: +**Example**: - ```Command - dotnet nuget add source https://pkgs.dev.azure.com/MyOrg/MyProject/_packaging/MyFeed/nuget/v3/index.json --name MySource --username MyUserName --password MyPersonalAccessToken --configfile ./nuget.config - dotnet nuget push nupkgs/mypackage.1.1.0.nupkg --source MySource --api-key AZ - ``` +```CLI +dotnet nuget add source https://pkgs.dev.azure.com/MyOrg/MyProject/_packaging/MyFeed/nuget/v3/index.json --name MySource --username MyUserName --password MyPersonalAccessToken --configfile ./nuget.config -## Restore packages +dotnet nuget push --source MySource --api-key AZ nupkgs/mypackage.1.1.0.nupkg +``` -To restore your packages, run the following command in an elevated command prompt. The `--interactive` flag is used to prompt the user for credentials. +> [!NOTE] +> If your organization is using a firewall or a proxy server, make sure you allow the [Azure Artifacts Domain URLs and IP addresses](../../organizations/security/allow-list-ip-url.md#azure-artifacts). -```Command -dotnet restore --interactive -``` -## Related articles +## Related content -- [Connect to Azure Artifacts feeds (NuGet.exe)](./nuget-exe.md) +- [Restore NuGet packages (dotnet)](restore-nuget-packages-dotnet.md) - [Publish packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/nuget.md) -- [Publish packages to NuGet.org](./publish-to-nuget-org.md) +- [Use packages from NuGet.org](./upstream-sources.md) diff --git a/docs/artifacts/nuget/dotnet-setup.md b/docs/artifacts/nuget/dotnet-setup.md index a768b4ad1b6..2a5c53f8a91 100644 --- a/docs/artifacts/nuget/dotnet-setup.md +++ b/docs/artifacts/nuget/dotnet-setup.md @@ -1,91 +1,121 @@ --- title: Connect to Azure Artifacts feeds - dotnet -description: How to connect to an Azure Artifacts feed - dotnet +description: Learn how to connect to Azure Artifacts feeds - dotnet ms.service: azure-devops-artifacts ms.custom: devx-track-dotnet -ms.topic: conceptual -ms.date: 07/12/2022 -monikerRange: '<= azure-devops' +ms.topic: how-to +ms.date: 04/09/2025 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- -# Connect to Azure Artifacts feeds (dotnet) +# Connect to an Azure Artifacts feed (dotnet) -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -## Project setup +Azure Artifacts enables developers to seamlessly publish packages to feeds and share them privately or publicly, depending on the feed’s visibility settings. This guide walks you through setting up your project and authenticating with your Azure Artifacts feed. -::: moniker range=">= azure-devops-2019" +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|----------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An Azure Artifacts [feed](../get-started-nuget.md#create-feed).
- Download and install the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider).
- Download and install the [.NET Core SDK](https://dotnet.microsoft.com/en-us/download). | + +## Connect to a feed + +::: moniker range="azure-devops" 1. Select **Artifacts** and then select your feed from the dropdown menu. -1. Select **Connect to feed**. +1. Select **Connect to feed**, and then select **dotnet** from the **NuGet** section. - :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="A screenshot showing how to connect to a feed."::: +1. Add a *nuget.config* file to your project. Place it in the same folder as your *.csproj* or *.sln* file, and paste the snippet provided in the **Project setup** section into it. Your *nuget.config* file should look similar to the following: -1. Select **dotnet** from the **NuGet** section. + - **Project-scoped feed**: - :::image type="content" source="../media/dotnet-connect-to-feed.png" alt-text="A screenshot showing how to connect to a feed - dotnet."::: + ```xml + + + + + + + + ``` -1. If this is your first time using Azure Artifacts with dotnet, select **Get the tools** in the top-right corner and then: - 1. Download and install the [.NET Core SDK](https://dotnet.microsoft.com/en-us/download). - 1. Download and install [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider). + - **Organization-scoped feed**: -1. Create a *nuget.config* file in the same folder as your *csproj* or *sln* file. Copy and paste the following snippet into your new file: + ```xml + + + + + + + + ``` + +::: moniker-end - - Project-scoped feed: +::: moniker range="azure-devops-2020 || azure-devops-2022" - ```xml - - - - - - - - ``` +1. Sign in to your Azure DevOps collection, and then navigate to your project. - - Organization-scoped feed: +1. Select **Artifacts**, and then select your feed from the dropdown menu. - ```xml - - - - - - - - ``` +1. Select **Connect to Feed**, and then select **dotnet** from the left. + +1. Add a *nuget.config* file to your project. Place it in the same folder as your *.csproj* or *.sln* file, and paste the snippet provided in the **Project setup** section into it. + + :::image type="content" source="../media/connect-to-feed-dotnet-server-2020-and-2022.png" alt-text="A screenshot displaying how to connect to a feed in Azure DevOps Server 2020 and 2022."::: ::: moniker-end -::: moniker range="tfs-2018" +## Authenticate using Service Principals -> [!NOTE] -> dotnet is not supported in TFS 2018. +You can use a service principal to authenticate with your Azure Artifacts feed. To do this, set the [ARTIFACTS_CREDENTIALPROVIDER_FEED_ENDPOINTS](https://github.com/microsoft/artifacts-credprovider/blob/master/README.md#environment-variables) environment variable as shown below. -1. Select **Build and Release**, and then select **Packages**. +This variable should define the feed URL, the service principal’s application (client) ID, and either the certificate subject name or the path to the certificate file (only one of these two is required). -1. Select your feed from the dropdown menu. +#### [Windows](#tab/windows/) -1. Select **Connect to feed**. +```powershell +$env:ARTIFACTS_CREDENTIALPROVIDER_FEED_ENDPOINTS = @'{ + "endpointCredentials": [ + { + "endpoint": "", + "clientId": "", + "clientCertificateSubjectName": "", + "clientCertificateFilePath": "" + } + ] +} +'@ +``` - :::image type="content" source="../media/connect-to-feed-tfs.png" alt-text="A screenshot showing how to connect to a feed in TFS."::: +#### [Linux/macOS](#tab/linuxmac/) -1. Select **NuGet** from the left panel. +```bash +export ARTIFACTS_CREDENTIALPROVIDER_FEED_ENDPOINTS='{ + "endpointCredentials": [ + { + "endpoint": "", + "clientId": "", + "clientCertificateSubjectName": "", + "clientCertificateFilePath": "" + } + ] +}' +``` -1. If this is your first time using Azure Artifacts with NuGet, select the link under **Get the tools** to download and install NuGet and the Credential Provider. +* * * -1. Run the following command in an elevated command prompt to add your feed URL to your nuget.config file: +## Related content - ```cmd - nuget.exe sources add -name -source - ``` +- [Publish NuGet packages (dotnet)](dotnet-exe.md) -::: moniker-end +- [Restore NuGet packages (dotnet)](restore-nuget-packages-dotnet.md) + +- [Publish NuGet packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/nuget.md) -## Related articles -- [Publish packages to NuGet.org](./publish-to-nuget-org.md) -- [Publish NuGet packages with Azure Pipelines](../../pipelines/artifacts/nuget.md) -- [NuGet.org upstream source](./upstream-sources.md) diff --git a/docs/artifacts/nuget/install-nuget-packages-with-visual-studio.md b/docs/artifacts/nuget/install-nuget-packages-with-visual-studio.md new file mode 100644 index 00000000000..183f6c52586 --- /dev/null +++ b/docs/artifacts/nuget/install-nuget-packages-with-visual-studio.md @@ -0,0 +1,114 @@ +--- +title: Install NuGet packages with Visual Studio +description: Learn how to use Visual Studio to install NuGet packages from Azure Artifacts feeds and NuGet.org. +ms.assetid: BF919E28-65C2-40E3-8A49-5BF0DA3DE598 +ms.service: azure-devops-artifacts +ms.custom: engagement-fy23 +ms.topic: how-to +ms.date: 03/04/2025 +monikerRange: '<= azure-devops' +--- + +# Install NuGet packages with Visual Studio + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +This article guides you through setting up your Visual Studio to install NuGet packages from Azure Artifacts feeds and NuGet.org. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|---------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An Azure Artifacts [feed](../get-started-nuget.md#create-feed). | +| **Other** | - Download [Visual Studio](https://visualstudio.microsoft.com/downloads/). | + +## Get the source URL + +Before setting up Visual Studio, you must first get your feed's source URL. You'll use this URL in the next section to add your feed as a package source in Visual Studio: + +[!INCLUDE [](../includes/nuget/nuget-consume-endpoint.md)] + +## Set up Visual Studio + +Now that you have your feed's source URL, follow these steps to set up Visual Studio and add the new package source: + +#### [Windows](#tab/windows/) + +1. Open Visual Studio, then select **Tools** > **Options**. + +1. Select **NuGet Package Manager**, and then select **Package Sources**. + +1. Enter your feed's **Name** and paste the **Source** URL you copied earlier. Select the green (+) icon when you're done to add a new package source. + +1. If you've enabled [upstream sources](upstream-sources.md) in your feed, uncheck **nuget.org**. + +1. Select **OK** when you're done. + + :::image type="content" source="../media/vs-addsource.png" alt-text="A screenshot displaying how to add a new package source in Visual Studio for Windows."::: + +#### [Mac](#tab/macOS/) + +1. Create a new [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **Packaging** > **Read & write** scopes. + +1. Open Visual Studio for Mac, and navigate to **Visual Studio** > **Preferences**. + +1. Select **NuGet** > **Sources**, then select **Add** to set up a new source. + +1. Enter a **Name** for the new source and paste the source URL you copied earlier in the **Location** field. For **UserName**, you can enter any string, and for **Password**, paste the personal access token you created earlier. Select **OK** when you're done. + +1. If you've enabled [upstream sources](upstream-sources.md) in your feed, uncheck **nuget.org**. + +1. Select **Add Source** when you're done. + + :::image type="content" source="media/add-new-source-mac.png" alt-text="A screenshot displaying how to add a new package source in Visual Studio for Mac."::: + +--- + +## Install packages from a feed + +Now that you've set up Visual Studio and added your feed as a package source, you can now search and install packages directly from the NuGet Package Manager in Visual Studio. + +#### [Windows](#tab/windows/) + +1. Open Visual Studio, and then right-click on your project in the **Solution Explorer**, then select **Manage NuGet Packages...**. + +1. Select **Browse**, and then select your feed from the **Package source** dropdown menu. + +1. Use the search bar to find and install packages from your feed. + + :::image type="content" source="../media/select-pkg-src.png" alt-text="A screenshot displaying the list of package sources in Visual Studio."::: + +#### [Mac](#tab/macOS/) + +1. Open Visual Studio for Mac, right-click on the **Dependencies** folder in your solution, and then select **Manage NuGet Packages...**. + +1. Select the **Browse** tab, and then select your feed from the **Package source** dropdown menu at the bottom. + +1. Use the search bar to find and install packages from your feed. + + :::image type="content" source="media/search-package-sources-mac.png" alt-text="A screenshot displaying how to search for packages in Visual Studio for Mac."::: + +--- + +> [!NOTE] +> If you've enabled [upstream sources](../nuget/upstream-sources.md), packages that haven't been saved to your feed from upstream won't appear in search results. A package is saved to the feed when a *Feed and Upstream Reader (Collaborator)* or higher installs it from upstream. + +## Install packages from NuGet.org + +You can install packages from NuGet.org in several ways, one of which is by using the *Package Manager Console* in Visual Studio: + +1. Navigate to *NuGet.org* and search for the package you want to install. + +1. Select the **Package Manager** tab, and then copy the *Install-Package* command. + +1. Open Visual Studio, then select **Tools** > **NuGet Package Manager** > **Package Manager Console**. + +1. Paste the install command into the console and press Enter. + +## Related content + +- [Restore NuGet packages (NuGet.exe)](restore-nuget-packages-nuget-exe.md) + +- [Restore NuGet packages (dotnet)](restore-nuget-packages-dotnet.md) + +- [Search for packages in upstream sources](../how-to/search-upstream.md) diff --git a/docs/artifacts/nuget/media/add-new-source-mac.png b/docs/artifacts/nuget/media/add-new-source-mac.png new file mode 100644 index 00000000000..6aee5e8021e Binary files /dev/null and b/docs/artifacts/nuget/media/add-new-source-mac.png differ diff --git a/docs/artifacts/nuget/media/package-saved-from-upstream.png b/docs/artifacts/nuget/media/package-saved-from-upstream.png new file mode 100644 index 00000000000..4147acf3c2c Binary files /dev/null and b/docs/artifacts/nuget/media/package-saved-from-upstream.png differ diff --git a/docs/artifacts/nuget/media/search-package-sources-mac.png b/docs/artifacts/nuget/media/search-package-sources-mac.png new file mode 100644 index 00000000000..fbca35f78ee Binary files /dev/null and b/docs/artifacts/nuget/media/search-package-sources-mac.png differ diff --git a/docs/artifacts/nuget/move-from-fileshares.md b/docs/artifacts/nuget/move-from-fileshares.md index 1af2bf8eb2d..ae80b3cebd7 100644 --- a/docs/artifacts/nuget/move-from-fileshares.md +++ b/docs/artifacts/nuget/move-from-fileshares.md @@ -80,7 +80,7 @@ If you want to replicate your existing file share permissions, make a note of th After completing the inventory of your current package sources, it's time to configure your feeds. In this step, we'll assume a one-to-one mapping of feeds to SMB shares. -For each SMB share, follow the instructions to [Create a feed](../get-started-nuget.md#create-a-feed): +For each SMB share, follow the instructions to [Create a feed](../get-started-nuget.md#create-feed): - Set the **Feed name** to match the name of your SMB share folder. diff --git a/docs/artifacts/nuget/nuget-exe.md b/docs/artifacts/nuget/nuget-exe.md index 45075b84666..330d028b078 100644 --- a/docs/artifacts/nuget/nuget-exe.md +++ b/docs/artifacts/nuget/nuget-exe.md @@ -1,133 +1,168 @@ --- -title: Connect to a feed - NuGet.exe -description: How to connect to an Azure Artifacts feed +title: Connect to an Azure Artifacts feeds with NuGet CLI +description: Learn how to connect to Azure Artifacts feeds with NuGet CLI. ms.assetid: 10665DBC-846E-4192-8CAB-D5A4C6E40C65 ms.service: azure-devops-artifacts -ms.topic: conceptual -ms.date: 07/11/2022 +ms.topic: how-to +ms.date: 04/08/2025 monikerRange: '<= azure-devops' +"recommendations": "true" --- -# Connect to Azure Artifacts feeds (NuGet.exe) +# Connect to an Azure Artifacts feed (NuGet.exe) [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -## Project setup - -::: moniker range=">= azure-devops-2019" - -1. Select **Artifacts** and then select your feed. +Azure Artifacts enables developers to download NuGet packages from various sources such as private feeds and public registries. You can publish packages to private feeds and control access, or create public feeds to share them openly. This article guides you through authenticating with to your Azure Artifacts feed. -1. Select **Connect to feed**. +## Prerequisites - :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot showing the connect to feed button"::: +| **Product** | **Requirements** | +|--------------------|----------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An Azure Artifacts [feed](../get-started-nuget.md#create-feed).
- Download and install the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider).
- Install the latest [NuGet version](https://www.nuget.org/downloads). | -1. Select **NuGet.exe** from the left panel. - -1. If this is your first time using Azure Artifacts with NuGet.exe, select **Get the tools** in the top-right corner and follow the instructions to download and install NuGet and Azure Artifacts Credential Provider. - -1. Follow the instructions in the **Project setup** to set up your nuget.config file. +## Project setup - :::image type="content" source="../media/nuget-azure-devops-newnav.png" alt-text="Screenshot showing how to set up your project's config file"::: +::: moniker range="azure-devops" -::: moniker-end +1. Sign in to your Azure DevOps organization, and then navigate to your project. -::: moniker range="tfs-2018" +1. Select **Artifacts**, and then select your feed from the dropdown menu. -1. Select **Build and Release** > **Packages**. +1. Select **Connect to feed**, and then select **NuGet.exe** from the left. -1. Select your feed from the dropdown menu. +1. Add a *nuget.config* file to your project, place it in the same folder as your *csproj* or *sln* file, and then paste the provided snippet into it. Your *nuget.config* file should resemble the following: -1. Select **Connect to feed**. + - **Project-scoped feed**: + + ```xml + + + + + + + + ``` + + - **Organization-scoped feed**: + + ```xml + + + + + + + + ``` - :::image type="content" source="../media/connect-to-feed.png" alt-text="Screenshot showing the connect to feed button in TFS"::: +::: moniker-end -1. Select **NuGet** from the left panel. +::: moniker range="azure-devops-2020 || azure-devops-2022" -1. If this is your first time using Azure Artifacts with NuGet, select the link under **Get the tools** to download and install NuGet and the Credential Provider. +1. Sign in to your Azure DevOps collection, and then navigate to your project. -1. Run the command highlighted in step number two to add your feed URL to your nuget.config file. +1. Select **Artifacts**, and then select your feed from the dropdown menu. - :::image type="content" source="../media/nugeturl.png" alt-text="Screenshot showing how to push your package using NuGet.exe in TFS"::: +1. Select **Connect to Feed**, and then select **NuGet.exe** from the left navigation pane. -1. Run the command highlighted in step number three if you want to publish your NuGet package. +1. Add a *nuget.config* file to your project, place it in the same folder as your *csproj* or *sln* file, and then paste the snippet provided in the **Project setup** section into your file. ::: moniker-end > [!NOTE] -> Azure Artifacts Credential Provider is supported with NuGet 4.8.2 or later. See [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider) for more information. +> The [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider) requires NuGet version `4.8.0.5385` or higher. For optimal performance, Azure Artifacts recommends using NuGet version `5.5.x` or later, as it includes crucial bug fixes related to cancellations and timeouts. ::: moniker range="azure-devops" -## Legacy project setup (NuGet v2) +## Legacy project setup -1. Select **Artifacts** and then select your feed. +If you're using an older version of NuGet, follow the instructions below to connect to your feed: -1. Select **Connect to feed**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. - :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot showing the connect to feed button"::: +1. Select **Artifacts** and then select your feed from the dropdown menu. -1. Select **NuGet.exe** from the left panel. +1. Select **Connect to feed**, and then select **NuGet.exe** from the left. -1. Copy your source URL, and then replace `/v3/index.json` with `/v2`. +1. Copy your source URL from the **Project setup** section, and then replace `/v3/index.json` with `/v2`. Your updated source URL should look like one of the following: - :::image type="content" source="../media/nuget-consume-url-azure-devops-newnav.png" alt-text="Screenshot showing the source URL"::: + - **Project-scoped feed**: + + ``` + https://pkgs.dev.azure.com///_packaging//nuget/v2 + ``` + + - **Organization-scoped feed**: + + ``` + https://pkgs.dev.azure.com//_packaging//nuget/v2 + ``` -1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat). Scope your PAT to the organization(s) you want to access and to one of the following scopes: Packaging (read), Packaging (read and write), or Packaging (read, write, and manage). +1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat), make sure you scope it to the right organization you want to access, and then select one of the following scopes based on your needs: **Packaging (read)**, **Packaging (read and write)**, or **Packaging (read, write, and manage)**. -1. Run the following command in an elevated command prompt window to add your package source: +1. Run the following command in a command prompt window to add your feed source to your *nuget.config* file: - ```Command - nuget sources add -name -source -username -password + ```CLI + nuget sources add -name -source -username -password ``` -1. If your organization is connected to Azure Active Directory, you must first authenticate with your AD credentials and then add your personal access token using the *setapikey* command: +1. If your organization is connected to Microsoft Entra ID, you must first authenticate with your AD credentials, and then add your personal access token using the *setapikey* command: - ```Command - nuget sources add -name -source -username -password + ```CLI + nuget sources add -name -source -username -password - nuget setapikey -source + nuget setapikey -source ``` ::: moniker-end -::: moniker range="tfs-2018" - -## Legacy project setup (NuGet v2) +## Authenticate using Service Principals -1. Select **Build and Release** > **Packages**. +To authenticate with an Azure Artifacts feed using a service principal, set the [ARTIFACTS_CREDENTIALPROVIDER_FEED_ENDPOINTS](https://github.com/microsoft/artifacts-credprovider/blob/master/README.md#environment-variables) environment variable as shown below. -1. Select your feed from the dropdown menu. +This specifies your feed URL, the service principal's application (client) ID, and either the subject name or the file path of the service principal certificate (only one of these two is required). -1. Select **Connect to feed**. +#### [Windows](#tab/windows/) - :::image type="content" source="../media/connect-to-feed.png" alt-text="Screenshot of the connect to feed button in TFS"::: +```powershell +$env:ARTIFACTS_CREDENTIALPROVIDER_FEED_ENDPOINTS = @'{ + "endpointCredentials": [ + { + "endpoint": "", + "clientId": "", + "clientCertificateSubjectName": "", + "clientCertificateFilePath": "" + } + ] +} +'@ +``` -1. Select **NuGet** and then copy your source URL. Replace `/v3/index.json` with `/v2`. +#### [Linux/macOS](#tab/linuxmac/) - :::image type="content" source="../media/nuget-consume-url.png" alt-text="Screenshot showing how to get the source URL"::: +```bash +export ARTIFACTS_CREDENTIALPROVIDER_FEED_ENDPOINTS='{ + "endpointCredentials": [ + { + "endpoint": "", + "clientId": "", + "clientCertificateSubjectName": "", + "clientCertificateFilePath": "" + } + ] +}' +``` -1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat). Scope your PAT to the organization(s) you want to access and to one of the following scopes: Packaging (read), Packaging (read and write), or Packaging (read, write, and manage). +* * * -1. Run the following command in an elevated command prompt window to add your package source: +## Related content - ```Command - nuget sources add -name -source -username -password - ``` +- [Publish NuGet packages (NuGet.exe)](publish.md) -1. If your organization is connected to Azure Active Directory, you must first authenticate with your AD credentials and then add your personal access token using the *setapikey* command: +- [Publish NuGet packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/nuget.md) - ```Command - nuget sources add -name -source -username -password - - nuget setapikey -source - ``` - -::: moniker-end +- [Restore NuGet packages (NuGet.exe)](restore-nuget-packages-nuget-exe.md) -## Related articles -- [Publish NuGet packages with Azure Pipelines](../../pipelines/artifacts/nuget.md) -- [Publish NuGet packages from the command line (NuGet.exe)](./publish.md) -- [Publish NuGet packages from the command line (dotnet)](./dotnet-exe.md) -- [NuGet.org upstream source](./upstream-sources.md) \ No newline at end of file diff --git a/docs/artifacts/nuget/publish.md b/docs/artifacts/nuget/publish.md index bd295d707ab..d0702dadbd3 100644 --- a/docs/artifacts/nuget/publish.md +++ b/docs/artifacts/nuget/publish.md @@ -1,83 +1,125 @@ --- -title: Connect to a feed and publish NuGet packages - NuGet.exe -description: How to connect to your feed and publish NuGet packages using the command line +title: Publish NuGet packages with the NuGet CLI +description: Learn how to connect to an Azure Artifacts feed and publish NuGet packages using the NuGet CLI. ms.assetid: C7D75946-1F00-4BD7-87C8-225BBAE9982B ms.service: azure-devops-artifacts -ms.topic: conceptual -ms.date: 06/30/2023 +ms.topic: tutorial +ms.date: 01/14/2025 monikerRange: '<= azure-devops' --- -# Publish and restore NuGet packages from the command line (NuGet.exe) +# Publish NuGet packages from the command line (NuGet.exe) [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -With Azure Artifacts, you can publish your NuGet packages to public or private feeds and share them with others based on your feed's visibility settings. This article will guide you through connecting to Azure Artifacts and publishing and restoring your NuGet packages. +This article guides you through setting up your project and publishing your NuGet packages using the NuGet command-line interface. ## Prerequisites -- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An Azure Artifacts [feed](../get-started-nuget.md#create-feed).
- Download and install the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider).
- The latest [NuGet version](https://www.nuget.org/downloads). | -- An Azure Artifacts feed. [Create a new feed](../get-started-nuget.md#create-a-feed) if you don't have one already. +## Connect to a feed -- [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider). +::: moniker range="azure-devops" -- The latest [NuGet version](https://www.nuget.org/downloads). +1. Sign in to your Azure DevOps organization, and then navigate to your project. -## Connect to feed +1. Select **Artifacts**, and then select your feed from the dropdown menu. -[!INCLUDE [](../includes/nuget/nuget-publish-endpoint.md)] +1. Select **Connect to feed**, and then select **NuGet.exe** from the left navigation pane. -## Publish packages +1. Add a *nuget.config* file to your project, in the same folder as your *.csproj* or *.sln* file. Paste the provided XML snippet into your file. The snippet should look like the following: -Run the following command to publish your packages to your feed. Replace the placeholders with the appropriate information: + - **Organization-scoped feed**: + + ```xml + + + + + + + + ``` + + - **Project-scoped feed**: + + ```xml + + + + + + + + ``` -```Command +::: moniker-end + +::: moniker range="azure-devops-2020 || azure-devops-2022" + +1. Sign in to your Azure DevOps server, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed. + +1. Select **Connect to Feed**, and then select **NuGet.exe** from the left navigation pane. + +1. Follow the instructions in the **Project setup** section to connect to your feed. + +::: moniker-end + +## Publish packages to a feed in the same organization + +Run the following command to publish a package to your feed. Replace the placeholders with the appropriate values: + +```CLI nuget push -src https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json -ApiKey ``` -> [!NOTE] -> The `ApiKey` is required, but you can use any arbitrary value when pushing to Azure Artifacts feeds. +**Example**: -- **Example**: +```CLI +nuget push MyPackage.5.0.2.nupkg -src https://pkgs.dev.azure.com/MyOrg/MyProject/_packaging/MyFeed/nuget/v3/index.json -ApiKey AZ +``` - ```Command - nuget push MyPackage.5.0.2.nupkg -src https://pkgs.dev.azure.com/MyOrg/MyProject/_packaging/MyFeed/nuget/v3/index.json -ApiKey AZ - ``` +> [!NOTE] +> The `api-key` is required, but you can provide any string as its value when publishing to an Azure Artifacts feed. -## Publish packages from external sources +## Publish packages to a feed in another organization -1. Create a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) (PAT) with **packaging read and write** scope. +To publish your NuGet packages to a feed in a different Azure DevOps organization, you must first create a personal access token (PAT) in the target organization. -1. Add your package source to your nuget.config file. This will add your PAT to your nuget.config file. Store this file in a safe location, and make sure that you don't check it into source control. See [NuGet sources](/nuget/reference/cli-reference/cli-ref-sources) for more details. +1. Navigate to the organization hosting the target feed and create a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) (PAT) with **Packaging** > **Read & write** scope. - ```Command +1. Run the following command to add your package source to your *nuget.config* file. This will add your PAT to your *nuget.config* file. Store this file in a safe location, and make sure that you don't check it into source control. + + ```CLI nuget sources Add -Name -Source https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json -UserName -Password -config ``` -1. Publish your package. See [NuGet push](/nuget/reference/cli-reference/cli-ref-push) for more details. +1. Run the following command to publish your package: - ```Command + ```CLI nuget push -src -ApiKey ``` -- **Example**: +**Example**: - ```Command - nuget sources Add -Name "MySource" -Source https://pkgs.dev.azure.com/MyOrg/MyProject/_packaging/MyFeed/nuget/v3/index.json -UserName MyUserName -Password YourPersonalAccessToken -config ./nuget.config - nuget push nupkgs/mypackage.1.1.8.nupkg -src MySource -ApiKey AZ - ``` +```CLI +nuget sources Add -Name "MySource" -Source https://pkgs.dev.azure.com/MyOrg/MyProject/_packaging/MyFeed/nuget/v3/index.json -UserName MyUserName -Password YourPersonalAccessToken -config ./nuget.config +nuget push nupkgs/mypackage.1.1.8.nupkg -src MySource -ApiKey AZ +``` + +> [!NOTE] +> If your organization is using a firewall or a proxy server, make sure you allow [Azure Artifacts Domain URLs and IP addresses](../../organizations/security/allow-list-ip-url.md#azure-artifacts). -## Restore packages +## Related content -Run the following command to restore your packages: +- [Restore NuGet packages (NuGet.exe)](restore-nuget-packages-nuget-exe.md) -```Command -nuget.exe restore -``` +- [Publish packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/nuget.md) -## Related articles +- [Use packages from NuGet.org](./upstream-sources.md) -- [Publish packages to NuGet.org](publish-to-nuget-org.md) -- [Set up upstream sources](../how-to/set-up-upstream-sources.md). -- [Publish NuGet packages with Azure Pipelines](../../pipelines/artifacts/nuget.md). diff --git a/docs/artifacts/nuget/restore-nuget-packages-dotnet.md b/docs/artifacts/nuget/restore-nuget-packages-dotnet.md new file mode 100644 index 00000000000..b4d6c397547 --- /dev/null +++ b/docs/artifacts/nuget/restore-nuget-packages-dotnet.md @@ -0,0 +1,88 @@ +--- +title: Restore NuGet packages with dotnet CLI +description: Learn how to connect to a feed and use the dotnet CLI to restore NuGet packages. +ms.service: azure-devops-artifacts +ms.topic: tutorial +ms.date: 01/13/2025 +monikerRange: '>= azure-devops-2020' +--- + +# Restore NuGet packages from the command line (dotnet) + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +This guide walks you through configuring your project and restoring your NuGet packages using the dotnet command-line interface. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An Azure Artifacts [feed](../get-started-nuget.md#create-feed).
- Download and install the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider).
- Download and install [.NET Core SDK (2.1.400+)](https://dotnet.microsoft.com/en-us/download). | + +## Connect to a feed + +::: moniker range="azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **dotnet** from the *NuGet* section on the left. + +1. Create a *nuget.config* file in the same folder as your *csproj* or *sln* file. Copy the following XML snippet and paste it into your new file, replacing the placeholders with the relevant information: + +- Organization-scoped feed: + + ```xml + + + + + + + + ``` + +- Project-scoped feed: + + ```xml + + + + + + + + ``` +::: moniker-end + +::: moniker range="azure-devops-2020 || azure-devops-2022" + +> [!NOTE] +> dotnet isn't supported in Azure DevOps Server 2019. + +1. Sign in to your Azure DevOps server, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed. + +1. Select **Connect to Feed**, and then select **dotnet** from the left navigation pane. + +1. Follow the instructions in the **Project setup** section to connect to your feed. + + :::image type="content" source="../media/connect-to-feed-dotnet-server-2020-and-2022.png" alt-text="A screenshot showing how to connect to a feed with dotnet in Azure DevOps Server 2020 and 2022." lightbox="../media/connect-to-feed-dotnet-server-2020-and-2022.png"::: + +::: moniker-end + +## Restore packages + +Run the following command to restore your packages. The `--interactive` flag is used to prompt the user for credentials: + +```CLI +dotnet restore --interactive +``` + +## Related content + +- [Publish NuGet packages (dotnet)](dotnet-exe.md) +- [Publish packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/nuget.md) +- [Use packages from NuGet.org](./upstream-sources.md) diff --git a/docs/artifacts/nuget/restore-nuget-packages-nuget-exe.md b/docs/artifacts/nuget/restore-nuget-packages-nuget-exe.md new file mode 100644 index 00000000000..54abfd7e001 --- /dev/null +++ b/docs/artifacts/nuget/restore-nuget-packages-nuget-exe.md @@ -0,0 +1,87 @@ +--- +title: Restore NuGet packages with the NuGet CLI +description: Learn how to connect to your feed and restore NuGet packages using the NuGet CLI. +ms.service: azure-devops-artifacts +ms.topic: tutorial +ms.date: 01/14/2025 +monikerRange: '<= azure-devops' +--- + +# Restore NuGet packages from the command line (NuGet.exe) + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +This article guides you through setting up your project and restoring NuGet packages using the NuGet command-line interface. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- An Azure Artifacts [feed](../get-started-nuget.md#create-feed).
- Download and install the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider).
- The latest [NuGet version](https://www.nuget.org/downloads). | + +## Connect to a feed + +::: moniker range="azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **NuGet.exe** from the left navigation pane. + +1. Add a *nuget.config* file to your project, in the same folder as your *csproj* or *.sln* file. Paste the provided XML snippet into your file. The snippet should look like the following: + + - **Organization-scoped feed**: + + ```xml + + + + + + + + ``` + + - **Project-scoped feed**: + + ```xml + + + + + + + + ``` + +::: moniker-end + +::: moniker range="azure-devops-2020 || azure-devops-2022" + +1. Sign in to your Azure DevOps server, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed. + +1. Select **Connect to Feed**, and then select **NuGet.exe** from the left navigation pane. + +1. Follow the instructions in the **Project setup** section to connect to your feed. + +::: moniker-end + +## Restore packages + +Run the following command in your project directory to restore your packages: + +```CLI +nuget.exe restore +``` + +## Related content + +- [Publish NuGet packages (NuGet.exe)](publish.md) + +- [Publish packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/nuget.md) + +- [Use packages from NuGet.org](./upstream-sources.md) + diff --git a/docs/artifacts/nuget/upstream-sources.md b/docs/artifacts/nuget/upstream-sources.md index 874645c8659..cc6fd7a6a4c 100644 --- a/docs/artifacts/nuget/upstream-sources.md +++ b/docs/artifacts/nuget/upstream-sources.md @@ -1,85 +1,188 @@ --- -title: Use packages from nuget.org -description: How to use packages from nuget.org with Azure Artifacts +title: Consume packages from nuget.org +description: How to consume packages from nuget.org with Azure Artifacts upstream sources ms.assetid: 301f954f-a35a-4fe2-b7fd-c78e534d9b16 ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 02/14/2022 +ms.date: 04/16/2024 monikerRange: '<= azure-devops' "recommendations": "true" --- -# NuGet.org upstream source +# Use packages from NuGet Gallery [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Enabling upstream sources on your feed enables developers to consume packages from public registries such as nuget.org and npmjs.com. In this article, you will learn how to add the NuGet Gallery upstream source to consume NuGet packages from the nuget.org public registry. +With Azure Artifacts upstream sources, developers are able to consume packages from public registries such as nuget.org and npmjs.com. This article will walk you through the process of setting up your project and using the command line to effectively consume NuGet packages from the NuGet Gallery. In this article, you'll learn how to: + +> [!div class="checklist"] +> * Enable upstream sources for your feed +> * Add NuGet Gallery as an upstream source +> * Connect to your feed +> * Install packages from nuget.org + +## Prerequisites + +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- An Azure Artifacts feed. + +- Download [NuGet](https://www.nuget.org/downloads). + +- Download and install [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider). + +## Enable upstream sources on your feed + +If you haven't created a feed yet, follow the steps below to create a new one and make sure you select the upstream sources checkbox to enable them. If you already have a feed, proceed to the [next step](#add-nuget-gallery-upstream-source) to add the NuGet Gallery as an upstream source. + +[!INCLUDE [](../includes/create-feed.md)] ## Add NuGet Gallery upstream source +::: moniker range="azure-devops" + +If you've checked the upstream sources checkbox when making your feed, NuGet Gallery should have been added automatically. If not, add it manually by following these steps: + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed. + +1. Select the gear icon button ![gear icon](../../media/icons/gear-icon.png) to navigate to your **Feed settings**. + +1. Select **Upstream Sources**, and then select **Add Upstream** to add a new upstream source. + +1. Select **Public source**, and then select **NuGet Gallery** from the dropdown menu. + +1. Select **Add** when you're done, and then select **Save** one more time at the top right corner to save your changes. + +::: moniker-end + +::: moniker range="azure-devops-2022" + +1. Sign in to your Azure DevOps server, and then navigate to your project. + 1. Select **Artifacts**, and then select your feed. -1. Select the gear icon ![gear icon](../../media/icons/gear-icon.png) button to navigate to **Feed settings**. +1. Select the gear icon button ![gear icon](../../media/icons/gear-icon.png) to navigate to your **Feed settings**. 1. Select **Upstream Sources**, and then select **Add Upstream**. - :::image type="content" source="./media/settings-add-upstream.png" alt-text="A screenshot showing how to add an upstream source."::: +1. Select **Public source**, and then select **NuGet Gallery** from the dropdown menu. + +1. Select **Save** when you're done, and then select **Save** one more time at the top right corner to save your changes. -1. Select **Public source**. +::: moniker-end + +::: moniker range="=azure-devops-2020" - :::image type="content" source="../media/add-new-upstream.png" alt-text="Screenshot showing how to add a new upstream source."::: +1. Sign in to your Azure DevOps server, and then navigate to your project. -1. Select **NuGet Gallery** from the dropdown menu. Select **Save** when you are done. +1. Select **Artifacts**, and then select your feed. - :::image type="content" source="./media/nuget-gallery-source.png" alt-text="Screenshot showing how to add the nuget.org upstream source."::: +1. Select the gear icon button ![gear icon](../../media/icons/gear-icon.png) to navigate to your **Feed settings**. - > [!NOTE] - > The service index location for nuget.org is `https://api.nuget.org/v3/index.json`. +1. Select **Upstream Sources**, and then select **Add upstream source**. -1. Select **Save** at the top right corner to save your changes. +1. Select **Public source**, and then select **NuGet Gallery** from the dropdown menu. -## Update nuget.config +1. Select **Add** when you're done. + +::: moniker-end + +## Connect to feed + +::: moniker range="azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. 1. Select **Artifacts**, and then select your feed. 1. Select **Connect to feed**, and then select **NuGet.exe**. - :::image type="content" source="./media/nuget-config.png" alt-text="A screenshot showing how to connect to NuGet feeds."::: +1. Add a *nuget.config* file in the same folder as your *.csproj* or *.sln* file. Paste the provided XML snippet into your file. If you use the examples below, make sure you replace the placeholders with the appropriate values for your scenario. + + - **Organization-scoped feed**: + + ```xml + + + + + + + + ``` + + - **Project-scoped feed**: + + ```xml + + + + + + + + ``` + +::: moniker-end -1. Copy the XML snippet in the **Project Setup** section. +::: moniker range="azure-devops-2020 || azure-devops-2022" - ```xml - - - - - - - +1. Sign in to your Azure DevOps server, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed. + +1. Select **Connect to Feed**, and then select **NuGet.exe** from the left navigation pane. + +1. Follow the instructions in the **Project setup** section to connect to your feed. + +::: moniker-end + +## Install packages from NuGet Gallery + +With our project now configured to authenticate with our feed, we can now proceed to install packages from the NuGet Gallery upstream. In this example, we will install the *Serilog* diagnostic logging library: + +1. Navigate to the NuGet Gallery at `https://www.nuget.org/`. + +1. Search for the *Serilog* package, and then select it to navigate to the details page. + +1. Select the **Package Manager** tab, and copy the command. In our example, the command is as follows: + + ```Command + NuGet\Install-Package Serilog -Version 3.1.2-dev-02097 ``` -1. Create a new *nuget.config* file in the root of your project. +1. Open your project in Visual Studio, and then select **Tools** > **NuGet Package Manager** > **Package Manager Console** to open the console window. -1. Paste the XML snippet in your nuget.config file. +1. Paste your command in the Package Manager Console window, and press Enter to install your package. -## View saved packages +[!INCLUDE [save-requires-collaborator](../includes/save-requires-collaborator.md)] -You can view the packages you saved from the NuGet Gallery by selecting your **Source** from the dropdown menu. +## View saved packages -::: moniker range=">= azure-devops-2019" +::: moniker range="azure-devops" -:::image type="content" source="./media/view-saved-packages-nuget.png" alt-text="A screenshot showing how to filter packages by source."::: +1. Sign in to your Azure DevOps organization, and then navigate to your project. ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="< azure-devops" -:::image type="content" source="media/view-cached-packages.png" alt-text="A screenshot showing how to filter packages by source in TFS"::: +1. Sign in to your Azure DevOps server, and then navigate to your project. ::: moniker-end +2. Select **Artifacts**, and then select your feed from the dropdown menu. + +3. Select the **NuGet Gallery** source from the dropdown menu to filter for packages from this upstream. + +4. The *Serilog* package, installed in the previous step, is now available in our feed. Azure Artifacts automatically saved a copy to our feed when we executed the install command. + + :::image type="content" source="media/package-saved-from-upstream.png" alt-text="A screenshot showing the package that was saved from upstream."::: + ## Related articles - [Publish NuGet packages with Azure Pipelines](../../pipelines/artifacts/nuget.md) - [Publish packages to NuGet.org](./publish-to-nuget-org.md) -- [Upstream sources overview](../concepts/upstream-sources.md) \ No newline at end of file +- [Manage permissions](../feeds/feed-permissions.md) \ No newline at end of file diff --git a/docs/artifacts/package-badges.md b/docs/artifacts/package-badges.md index bc9fa6596e5..3c463bd2d68 100644 --- a/docs/artifacts/package-badges.md +++ b/docs/artifacts/package-badges.md @@ -19,7 +19,7 @@ With Azure Artifacts, you can share your packages anywhere you can share an imag > [!NOTE] > You must be a feed administrator to enable package sharing. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Select **Artifacts**, and then select your feed from the dropdown menu. Select the gear icon ![gear icon](../media/icons/gear-icon.png) to access the **Feed settings**. @@ -31,25 +31,11 @@ With Azure Artifacts, you can share your packages anywhere you can share an imag ::: moniker-end -::: moniker range="tfs-2018" - -1. Select **Build and Release**, and then select **Packages**. - -1. Select the gear icon ![gear icon](../media/icons/gear-icon.png) to access the **Feed settings**. - - :::image type="content" source="media/edit-feed-full.png" alt-text="A screenshot showing how to navigate to the feed settings in TFS"::: - -1. Select **Enable package badges**. This will enable the **Create badge** button for every package in that feed. - - :::image type="content" source="media/pm-create-badge.png" alt-text="A screenshot showing how to create a package badge in TFS."::: - -::: moniker-end - ## Create a package badge With package-sharing enabled, you can create a badge for any package in your feed. But you can only create a badge for the latest version of each package. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. From within your feed, select your package and then select **Create badge**. @@ -63,18 +49,6 @@ With package-sharing enabled, you can create a badge for any package in your fee ::: moniker-end -::: moniker range="tfs-2018" - -1. From within your feed, select your package and then select **Create badge**. - - :::image type="content" source="media/pm-create-badge.png" alt-text="A screenshot showing how to create a badge in TFS 2018."::: - -1. Select a **Feed view** for your package badge. - -1. Share the Markdown snippet or the image link with your customers. - -::: moniker-end - ## Related articles - [Limits of package sizes and counts](./reference/limits.md) diff --git a/docs/artifacts/python/media/add-pypi-upstream.png b/docs/artifacts/python/media/add-pypi-upstream.png new file mode 100644 index 00000000000..5ae33eb1fba Binary files /dev/null and b/docs/artifacts/python/media/add-pypi-upstream.png differ diff --git a/docs/artifacts/python/media/install-package-from-upstream.png b/docs/artifacts/python/media/install-package-from-upstream.png new file mode 100644 index 00000000000..1c851611e10 Binary files /dev/null and b/docs/artifacts/python/media/install-package-from-upstream.png differ diff --git a/docs/artifacts/python/project-setup-python.md b/docs/artifacts/python/project-setup-python.md new file mode 100644 index 00000000000..21ae666a583 --- /dev/null +++ b/docs/artifacts/python/project-setup-python.md @@ -0,0 +1,87 @@ +--- +title: Connect your Python project to an Azure Artifacts feed +description: Learn how to set up your Python project and connect to an Azure Artifacts feed. +ms.service: azure-devops-artifacts +ms.topic: how-to +ms.date: 01/24/2025 +monikerRange: "<=azure-devops" +--- + +# Connect your Python project to an Azure Artifacts feed + +[!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] + +This article guides you through setting up your Python project and connecting to an Azure Artifacts feed. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- Download and install [Python](https://www.python.org/downloads/). | + +## Install the credential manager + +If this is your first time using Azure Artifacts on this machine, run the following command to install the Azure Artifacts keyring, required for authenticating with Azure Artifacts feeds: + +``` +pip install keyring artifacts-keyring +``` + +## Project setup + +Follow the steps below to set up your project and connect to your feed. + +### [pip](#tab/pip) + +Make sure you have the latest version of pip `python -m pip install --upgrade pip` and if you're using Linux, ensure you've installed the [prerequisites](https://pypi.org/project/artifacts-keyring/) required for the credential manager. + +1. Sign in to your Azure DevOps organization, and navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **pip** from the left. + +1. [Create a virtual environment](https://docs.python.org/3/library/venv.html) if you don't have one already. + +1. Add a *pip.ini* (Windows) or *pip.conf* (Mac/Linux) file to your virtualenv and paste the provided snippet from the **Project setup** section into the file. Your config file should look similar to the following snippet: + + ``` + [global] + index-url=https://pkgs.dev.azure.com/ORGANIZATION_NAME/PROJECT_NAME/_packaging/FEED_NAME/pypi/simple/ + ``` + +> [!NOTE] +> You need pip version 19.2 or higher to use **artifacts-keyring**. For more information, see [Usage requirements](https://github.com/microsoft/artifacts-keyring#requirements). + +### [twine](#tab/twine) + +Make sure you've installed Twine `p install twine` and if you're using Linux, ensure you've installed the [prerequisites](https://pypi.org/project/artifacts-keyring/) required for the credential manager. + +1. Sign in to your Azure DevOps organization, and navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **Twine** from the left. + +1. Add a *.pypirc* file to your home directory and paste the provided snippet from the **Project setup** section into the file. Your config file should look similar to the following snippet: + + > [!NOTE] + > If your config file contains credentials for the public PyPI index, we recommend removing the *[pypi]* section to prevent accidentally publishing private packages to the public registry. + + ``` + [distutils] + Index-servers = + FEED_NAME + + [FEED_NAME] + Repository = https://pkgs.dev.azure.com/ORGANIZATION_NAME/PROJECT_NAME/_packaging/FEED_NAME/pypi/upload/ + ``` + +> [!NOTE] +> You need Twine 1.13.0 or higher to use **artifacts-keyring**. For more information, see [Usage requirements](https://github.com/microsoft/artifacts-keyring#requirements). + +- - - + +## Next steps +> [!div class="nextstepaction"] +> [Publish Python packages](../quickstarts/python-cli.md) \ No newline at end of file diff --git a/docs/artifacts/python/use-packages-from-pypi.md b/docs/artifacts/python/use-packages-from-pypi.md new file mode 100644 index 00000000000..df10b971f04 --- /dev/null +++ b/docs/artifacts/python/use-packages-from-pypi.md @@ -0,0 +1,131 @@ +--- +title: Use packages from PyPI +description: How to consume packages from Python package index with Azure Artifacts +ms.service: azure-devops-artifacts +ms.custom: devx-track-python +ms.date: 11/17/2023 +monikerRange: "<=azure-devops" +"recommendations": "true" +--- + +# Use packages from Python package index (PyPI) + +[!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] + +Using Azure Artifacts, developers can publish and consume packages from both Azure Artifacts feeds and external registries such as PyPI.org. By enabling upstream sources, you can streamline your package management, using a single feed to manage both your own packages and those consumed from public registries. Once enabled, Azure Artifacts automatically saves a copy of any package installed by a collaborator or higher from an upstream source. This article will guide you through setting up your project and using the command line to efficiently consume Python packages from PyPI. + +In this article, you'll learn how to: + +> [!div class="checklist"] +> * Enable upstream sources for your feed +> * Add PyPI as an upstream source +> * Setup your project +> * Install packages from Python package index + +## Prerequisites + +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- An Azure Artifacts feed. + +- Download [Python](https://www.python.org/downloads/). + +## Enable upstream sources when creating a new feed + +If you haven't created a feed yet, follow the steps below to create a new one. Make sure to check the box for *upstream sources* to enable upstream sources. If you already have a feed, skip to the [next step](#add-pypi-as-a-new-upstream-source) to add PyPI as an upstream source. + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select **Create Feed** to create a new feed. + +1. Enter a descriptive **Name** for your feed and define its **Visibility** (indicating who can view packages within the feed). Specify the **Scope** of your feed, and then check the **Upstream sources** checkbox to include packages from public registries. + +1. Select **Create** when you're done. + + :::image type="content" source="../media/new-feed-dialog-azure-devops.png" alt-text="A screenshot showing how to create a need feed."::: + +## Add PyPI as a new upstream source + +If you selected the upstream sources checkbox during the creation of your feed, PyPI should have been automatically included as an upstream source. If not, you can manually add it by following these steps: + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select the gear icon ![gear icon](../../media/icons/gear-icon.png) to navigate to **Feed Settings**. + +1. Select **Upstream sources**, and then select **Add Upstream** to add a new upstream source. + +1. Select **Public source**, and then select **PyPI (https://pypi.org/)** from the dropdown menu. + +1. Select **Add** when you're done, and then select **Save** from the top right corner to save your changes. + + :::image type="content" source="media/add-pypi-upstream.png" alt-text="A screenshot displaying how to add PyPI as a new upstream source."::: + +## Authenticate with your feed + +1. Make sure you have downloaded Python, and then run the following command to upgrade your Python package manager: + + ```Command + python -m pip install --upgrade pip + ``` + +1. Run the following command to install the Azure Artifacts keyring: + + ```Command + pip install keyring artifacts-keyring + ``` + +1. Create a [Personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read** scope to authenticate with Azure DevOps. The first time you connect to Azure DevOps, you'll need to enter your credentials when prompted. Provide your username (any string) and your personal access token in the designated fields. These credentials will be cached locally and automatically used to sign you in the next time you use the service. + +1. Navigate to your project folder, and then run the following command to create a new virtual environment: + + ```Command + python -m venv + ``` + +1. Create a new *pip.ini* file (Windows) or a *pip.conf* file (Mac/Linux) in your virtual environment, and then paste the following snippet into your file. Make sure you replace the placeholders with the appropriate information, and be cautious not to commit this file to a public repository as it contains your personal access token. + + - **Project-scoped feed**: + + ``` + [global] + extra-index-url=https://:@pkgs.dev.azure.com///_packaging//pypi/simple/ + ``` + + - **Organization-scoped feed**: + + ``` + [global] + extra-index-url=https://:@pkgs.dev.azure.com//_packaging//pypi/simple/ + ``` + +## Install packages from PyPI + +Now that we've configured our project to authenticate with our feed, we can begin installing packages from the PyPI upstream. In this example, we'll install `Flask`: + +1. In a command prompt window, navigate to your project folder and run the following command to activate your virtual environment. Replace the placeholder with the name of the virtual environment you created earlier: + + ```Command + /Scripts/Activate.ps1 + ``` + +1. Run the following command to check the packages installed in your virtual environment: + + ```Command + pip list + ``` + +1. Run the following command to install *Flask*. + + ```Command + pip install -U Flask + ``` + +1. Once your package is installed, Azure Artifacts will save a copy of this package to your feed. Your package should be available in your feed as shown in the screenshot below. + + :::image type="content" source="media/install-package-from-upstream.png" alt-text="A screenshot showing packages installed from PyPI upstream."::: + +## Related articles + +- [Publish and consume Python packages CLI](../quickstarts/python-cli.md) +- [Publish Python packages with Azure Pipelines](../../pipelines/artifacts/pypi.md) +- [Manage permissions](../feeds/feed-permissions.md) diff --git a/docs/artifacts/quickstarts/download-universal-packages.md b/docs/artifacts/quickstarts/download-universal-packages.md new file mode 100644 index 00000000000..113f65801a4 --- /dev/null +++ b/docs/artifacts/quickstarts/download-universal-packages.md @@ -0,0 +1,105 @@ +--- +title: Download Universal Packages in Azure Artifacts +description: Learn how to download Universal Packages from an Azure Artifacts feed. +ms.service: azure-devops-artifacts +ms.topic: how-to +ms.date: 01/16/2025 +monikerRange: 'azure-devops' +--- + +# Download Universal Packages from Azure Artifacts feeds + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +This article guides you through downloading Universal Packages from your Azure Artifacts feed using the command line interface. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- Install [Azure CLI](/cli/azure/install-azure-cli).
- Install the [Azure DevOps extension](#install-azure-devops-extension) version 0.14.0 or higher. | + +## Install Azure DevOps extension + +Ensure that you have Azure CLI (version 2.10.1 or higher) installed. Then, follow the steps below to install or update the Azure DevOps extension to manage your Azure DevOps resources from the command line. + +1. Run the following command to install the Azure DevOps extension: + + ```azurecli + az extension add --name azure-devops + ``` + +1. If the Azure DevOps extension is already installed and you want to update it to the latest version, run: + + ```azurecli + az extension update --name azure-devops + ``` + +## Create a feed + +1. Sign in to your Azure DevOps organization and navigate to your project. + +1. Select **Artifacts**, and then select **Create Feed**. + +1. Provide a **Name** for your feed, choose the **Visibility** option that defines who can view your packages, check **Include packages from common public sources** if you want to include packages from sources like *nuget.org* or *npmjs.com*, and for **Scope**, decide whether the feed should be scoped to your project or the entire organization. + +1. Select **Create** when you're done. + + :::image type="content" source="../media/create-new-feed-azure-devops.png" alt-text="A screenshot displaying how to create a new feed in Azure DevOps Services."::: + +## Download Universal Packages + +Make sure you have set up authentication, and then run the following command to download a specific Universal Package from your feed using the Azure CLI: + +- **Project-scoped feed**: + + ```azurecli + az artifacts universal download --organization https://dev.azure.com/ --project --scope project --feed --name --version --path + ``` + +- **Organization-scoped feed**: + + ```azurecli + az artifacts universal download --organization https://dev.azure.com/ --feed --name --version --path + ``` + +## Download specific files + +To download only specific files, use the `--file-filter` parameter to fetch only the specified subset of files. See [File matching patterns reference](../../pipelines/tasks/file-matching-patterns.md) for more details. + +- **Project-scoped feed**: + + ```azurecli + az artifacts universal download --organization https://dev.azure.com/ --project --scope project --feed --name --version --path --file-filter + ``` + +- **Organization-scoped feed**: + + ```azurecli + az artifacts universal download --organization https://dev.azure.com/ --feed --name --version --path --file-filter + ``` + +**Example:** Using `--file-filter logs/.log` would match all files in the `logs` directory with the `.log` extension. + +## Download the latest version + +Use wildcards `*` to download the latest version of your Universal Packages. + +**Examples**: + +- `--version '*'`: Download the latest version. + +- `--version '1.*'`: Download the latest version with major version 1. + +- `--version '1.2.*'`: Download the latest patch release with major version 1 and minor version 2. + +> [!NOTE] +> Wildcard patterns are not supported with prerelease versions (packages with a dash in their version number). + +## Related content + +- [Publish Universal Packages](universal-packages.md) + +- [Publish and download Universal Packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/universal-packages.md) + +- [Universal Packages upstream sources](../universal-packages/universal-packages-upstream.md) \ No newline at end of file diff --git a/docs/artifacts/quickstarts/github-actions.md b/docs/artifacts/quickstarts/github-actions.md index d20b2f12e67..8ae9a20c9ff 100644 --- a/docs/artifacts/quickstarts/github-actions.md +++ b/docs/artifacts/quickstarts/github-actions.md @@ -3,10 +3,11 @@ title: Use GitHub Actions to push to Azure Artifacts description: Push a NuGet package to Azure Artifacts with a GitHub Actions workflow ms.author: jukullam ms.custom: github-actions-azure -ms.date: 06/06/2023 +ms.date: 08/06/2024 monikerRange: azure-devops author: juliakm ms.topic: quickstart +zone_pivot_groups: github-actions-auth --- # Quickstart: Use GitHub Actions to push to Azure Artifacts @@ -14,6 +15,183 @@ ms.topic: quickstart [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] Get started using [GitHub Actions](https://docs.github.com/en/actions) and Azure Artifacts together. GitHub Actions help you automate your software development workflows from within GitHub. You can use GitHub Actions to deploy to an Azure Artifacts feed. + +::: zone pivot="managed-identity" + +## Prerequisites + +- A GitHub account with a repository. [Join GitHub](https://github.com/join) and [create a repository](https://docs.github.com/en/github/getting-started-with-github/create-a-repo). +- An Azure Artifact feed that you'll push your NuGet package to from a GitHub workflow. [Get Started with NuGet Packages](../get-started-nuget.md). +- Set up a user-assigned managed identity with an associated federated credential. + - [Create a user-assigned managed identity](/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities#create-a-user-assigned-managed-identity). + - Copy the values for **Client ID**, **Subscription ID**, and **Directory (tenant) ID** to use later in your GitHub Actions workflow. + - [Assign an appropriate role to your user-assigned managed identity](/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities#manage-access-to-user-assigned-managed-identities). + - [Configure a federated identity credential on a user-assigned managed identity](/entra/workload-id/workload-identity-federation-create-trust-user-assigned-managed-identity) to trust tokens issued by GitHub Actions to your GitHub repository. +- Have permission to assign a managed identity to the **Contributor** group in Azure DevOps. **Project Administrators** and **Collection Administrators** both have this permission. + +> [!NOTE] +> An alternative approach is to use an Microsoft Entra application with a service principal and federated authentication credential to connect Azure DevOps and GitHub Actions. To learn more about this approach, see [Configure an app to trust an external identity provider](/entra/workload-id/workload-identity-federation-create-trust). + +## Assign permissions to your managed identity in Azure DevOps + +To assign your managed identity to the **Contributor** team, follow these steps: + +1. Sign in to your project (`https://dev.azure.com/{Your_Organization/Your_Project}`). +1. Go to **Project settings**. +1. Select **General** > **Permissions**. +1. Choose the **Contributors** group. + + :::image type="content" source="media/select-contributors-group.png" alt-text="Screenshot of contributors group permission option." lightbox="media/select-contributors-group.png" ::: + +1. Select the **Members** tab and then select **Add**. +1. Search and find the managed identity. +1. Select **Save** to add the identity to the **Contributors** group. + + :::image type="content" source="media/invite-managed-identity.png" alt-text="Screenshot of adding a managed identity. "::: + +## Create GitHub secrets + +[!INCLUDE [include](~/../docs/reusable-content/github-actions/create-secrets-managed-identity-only.md)] + + +## Create a GitHub workflow that builds an artifact + + +[GitHub workflows](/azure/developer/github/github-actions) are a series of actions (like tasks in Azure Pipelines). This workflow automates the process of building, testing, packaging, and publishing a .NET project to Azure Artifacts using a managed identity and federated authentication. The workflow: + +1. Uses the [azure/login action](https://github.com/marketplace/actions/azure-login) to log in to Azure using a managed identity. +1. Installs the [credential provider for Azure Artifacts](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider). +1. Extracts an access token using Azure CLI and configures the authentication provider to use the Azure DevOps token. +1. Sets up a .NET Core CLI environment with the [setup-dotnet action](https://github.com/actions/setup-dotnet). +1. Restores dependencies, builds the project and its dependencies into a set of binaries, and runs all unit tests associated with the project. +1. Packs the code into a NuGet package with the GitHub Run ID environmental variable included in the version number. +1. Publishes the NuGet package to Azure Artifacts. + +### Create a new YAML file + +1. In your repository on GitHub, create a new YAML file in the `.github/workflows` directory. + +2. Copy the following contents into your YAML file. Customize the `AZURE_ARTIFACTS_FEED_URL`, `BUILD_CONFIGURATION`, and `DOTNET_VERSION` values. + * Set `AZURE_ARTIFACTS_FEED_URL` to the registry url for your Azure Artifacts Feed. + * Set the `BUILD_CONFIGURATION`. + * Set `DOTNET_VERSION` to the version of your project. + + + ```yaml + name: Push a NuGet package to Azure Artifacts with managed identity and federated authentication + + on: + push: + branches: + - main + + permissions: + id-token: write # Require write permission to Fetch an federated identity token. + contents: read # Require read permission to access the repository contents. + + env: + AZURE_ARTIFACTS_FEED_URL: https://pkgs.dev.azure.com/myorg/nuget-artifact/_packaging/Fabrikam_Feed/nuget/v3/index.json + BUILD_CONFIGURATION: 'Release' # set this to the appropriate build configuration + DOTNET_VERSION: '6.0' + NuGetDirectory: ${{ github.workspace}}/nuget + VSS_NUGET_URI_PREFIXES: https://pkgs.dev.azure.com/myorg/ + + + jobs: + build: + runs-on: ubuntu-latest + steps: + # Checkout the repo + - uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Azure CLI Login + uses: azure/login@v2 + with: + client-id: ${{ secrets.AZURE_CLIENT_ID }} + tenant-id: ${{ secrets.AZURE_TENANT_ID }} + subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} + + # Setup .NET Core SDK + - name: Setup .NET Core + uses: actions/setup-dotnet@v3 + with: + dotnet-version: ${{ env.DOTNET_VERSION }} + + # Run dotnet build and package + - name: dotnet build and test + run: | + dotnet restore + dotnet build --configuration '${{ env.BUILD_CONFIGURATION }}' + dotnet test --configuration '${{ env.BUILD_CONFIGURATION }}' + + # Create the NuGet package in the folder from the environment variable NuGetDirectory + - run: dotnet pack --configuration Release --output ${{ env.NuGetDirectory }} + + # Publish the NuGet package as an artifact, so they can be used in the following jobs + - uses: actions/upload-artifact@v3 + with: + name: nuget + if-no-files-found: error + retention-days: 7 + path: ${{ env.NuGetDirectory }}/*.nupkg + + az-artifacts-build-and-deploy: + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Azure CLI Login + uses: azure/login@v2 + with: + client-id: ${{ secrets.AZURE_CLIENT_ID }} + tenant-id: ${{ secrets.AZURE_TENANT_ID }} + subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} + + - uses: actions/download-artifact@v3 + with: + name: nuget + path: ${{ env.NuGetDirectory }} + + - name: Setup .NET Core + uses: actions/setup-dotnet@v3 + with: + dotnet-version: ${{ env.DOTNET_VERSION }} + source-url: ${{ env.AZURE_ARTIFACTS_FEED_URL }} + env: + NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}} + + - name: Install credential provider for Azure Artifacts + run: sh -c "$(curl -fsSL https://aka.ms/install-artifacts-credprovider.sh)" + + - name: Extract access token + run: | + accessToken=$(az account get-access-token --query accessToken --resource 499b84ac-1321-427f-aa17-267ca6975798 -o tsv) + echo "::add-mask::$accessToken" + echo "ACCESS_TOKEN=$accessToken" >> $GITHUB_ENV + + - name: Configure authentication provider to use Azure DevOps token + run: | + echo "VSS_NUGET_ACCESSTOKEN=$ACCESS_TOKEN" >> $GITHUB_ENV + + - name: dotnet build and publish + run: | + dotnet restore + dotnet build --configuration '${{ env.BUILD_CONFIGURATION }}' + dotnet pack --configuration '${{ env.BUILD_CONFIGURATION }}' --output ./nupkg --version-suffix ${{ github.run_id }} + + - name: 'Publish the package to Azure Artifacts' + run: dotnet nuget push ${{ env.NuGetDirectory }}/*.nupkg --api-key AzureDevOps --source ${{ env.AZURE_ARTIFACTS_FEED_URL }} + ``` + +:::zone-end + +::: zone pivot="pat" + ## Prerequisites - A GitHub account with a repository. [Join GitHub](https://github.com/join) and [create a repository](https://docs.github.com/en/github/getting-started-with-github/create-a-repo). @@ -30,10 +208,12 @@ Get started using [GitHub Actions](https://docs.github.com/en/actions) and Azure [GitHub workflows](/azure/developer/github/github-actions) are a series of actions (like tasks in Azure Pipelines). This workflow: -* Sets up a .NET Core CLI environment with the [setup-dotnet action](https://github.com/actions/setup-dotnet). -* Restores dependencies, builds the project and its dependencies into a set of binaries, and runs all unit tests associated with the project. -* Packs the code into a NuGet package with the GitHub Run ID environmental variable included in the version number. -* Publishes the NuGet package to Azure Artifacts. +1. Sets up a .NET Core CLI environment with the [setup-dotnet action](https://github.com/actions/setup-dotnet). +1. Restores dependencies, builds the project and its dependencies into a set of binaries, and runs all unit tests associated with the project. +1. Packs the code into a NuGet package with the GitHub Run ID environmental variable included in the version number. +1. Publishes the NuGet package to Azure Artifacts. + +### Create a new YAML file 1. In your repository on GitHub, create a new YAML file in the `.github/workflows` directory. @@ -44,7 +224,7 @@ Get started using [GitHub Actions](https://docs.github.com/en/actions) and Azure ```yaml - name: Push a NuGet package to Azure Artifacts or GitHub Package Registry + name: Push a NuGet package to Azure Artifacts on: push: @@ -105,7 +285,9 @@ Get started using [GitHub Actions](https://docs.github.com/en/actions) and Azure ``` 3. Go to your Azure Artifacts feed to verify that you see the package you pushed. - :::image type="content" source="media/artifacts-nuget-package.png" alt-text="Review new Azure Artifacts feed."::: + :::image type="content" source="media/artifacts-nuget-package.png" alt-text="Screenshot of review for new Azure Artifacts feed." lightbox="media/artifacts-nuget-package.png" ::: + +:::zone-end ## Clean up resources diff --git a/docs/artifacts/quickstarts/install-python-packages.md b/docs/artifacts/quickstarts/install-python-packages.md new file mode 100644 index 00000000000..ec073910b5f --- /dev/null +++ b/docs/artifacts/quickstarts/install-python-packages.md @@ -0,0 +1,60 @@ +--- +title: Install Python packages (CLI) +description: Learn how to install Python packages from the command-line interface. +ms.service: azure-devops-artifacts +ms.topic: how-to +ms.date: 01/15/2025 +monikerRange: "<=azure-devops" +--- + +# Install Python packages (CLI) + +[!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] + +This article guides you through installing Python packages from an Azure Artifacts feed using the NuGet command-line interface. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- Download and install [Python](https://www.python.org/downloads/). | + +## Create a feed + +[!INCLUDE [](../includes/create-feed.md)] + +## Install packages + +1. Follow the steps in the [Project setup](../python/project-setup-python.md#project-setup) to authenticated with your feed if you haven't done so, then proceed to the next step. + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select **Connect to feed**. + +1. Select **pip** from the left navigation area. If this is your first time using Azure Artifacts with pip, make sure to install the prerequisites by selecting **Get the tools** and following the provided steps. + +1. [Create a virtual environment](https://docs.python.org/3/library/venv.html). + +1. Add a *pip.ini* (Windows) or *pip.conf* (Mac/Linux) file to your virtualenv and paste the provided snippet into it. Your file should look similar to the following snippet: + + ``` + [global] + index-url=https://pkgs.dev.azure.com/ORGANIZATION_NAME/PROJECT_NAME/_packaging/FEED_NAME/pypi/simple/ + ``` + +1. Run this command in your project directory to install your packages: + + ``` + pip install + ``` + +> [!IMPORTANT] +> You must have pip 19.2 or higher to use **artifacts-keyring**. See [Usage requirements](https://github.com/microsoft/artifacts-keyring#requirements) for more details. + +## Related content + +- [Publish Python packages (CLI)](python-cli.md) + +- [Publish Python packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/pypi.md) + +- [Use packages from PyPi.org](../python/use-packages-from-pypi.md) diff --git a/docs/artifacts/quickstarts/media/invite-managed-identity.png b/docs/artifacts/quickstarts/media/invite-managed-identity.png new file mode 100644 index 00000000000..977ef58933e Binary files /dev/null and b/docs/artifacts/quickstarts/media/invite-managed-identity.png differ diff --git a/docs/artifacts/quickstarts/media/pip-feed.png b/docs/artifacts/quickstarts/media/pip-feed.png index ef3467a7681..0d1ca4cc8f0 100644 Binary files a/docs/artifacts/quickstarts/media/pip-feed.png and b/docs/artifacts/quickstarts/media/pip-feed.png differ diff --git a/docs/artifacts/quickstarts/media/screenshot-connect-to-feed-twine-selection.png b/docs/artifacts/quickstarts/media/screenshot-connect-to-feed-twine-selection.png new file mode 100644 index 00000000000..0a3cc833959 Binary files /dev/null and b/docs/artifacts/quickstarts/media/screenshot-connect-to-feed-twine-selection.png differ diff --git a/docs/artifacts/quickstarts/media/screenshot-pip-connect-to-feed-index-url.png b/docs/artifacts/quickstarts/media/screenshot-pip-connect-to-feed-index-url.png new file mode 100644 index 00000000000..42a70287131 Binary files /dev/null and b/docs/artifacts/quickstarts/media/screenshot-pip-connect-to-feed-index-url.png differ diff --git a/docs/artifacts/quickstarts/media/screenshot-pip-connect-to-feed-pip-ini.png b/docs/artifacts/quickstarts/media/screenshot-pip-connect-to-feed-pip-ini.png new file mode 100644 index 00000000000..680df8a2173 Binary files /dev/null and b/docs/artifacts/quickstarts/media/screenshot-pip-connect-to-feed-pip-ini.png differ diff --git a/docs/artifacts/quickstarts/media/screenshot-twine-connect-to-feed-pyirc.png b/docs/artifacts/quickstarts/media/screenshot-twine-connect-to-feed-pyirc.png new file mode 100644 index 00000000000..346b9a546f2 Binary files /dev/null and b/docs/artifacts/quickstarts/media/screenshot-twine-connect-to-feed-pyirc.png differ diff --git a/docs/artifacts/quickstarts/media/screenshot-twine-connect-to-feed-url.png b/docs/artifacts/quickstarts/media/screenshot-twine-connect-to-feed-url.png new file mode 100644 index 00000000000..a0ff881294c Binary files /dev/null and b/docs/artifacts/quickstarts/media/screenshot-twine-connect-to-feed-url.png differ diff --git a/docs/artifacts/quickstarts/media/select-contributors-group.png b/docs/artifacts/quickstarts/media/select-contributors-group.png new file mode 100644 index 00000000000..505f1121859 Binary files /dev/null and b/docs/artifacts/quickstarts/media/select-contributors-group.png differ diff --git a/docs/artifacts/quickstarts/media/universal-packages-create-feed.png b/docs/artifacts/quickstarts/media/universal-packages-create-feed.png new file mode 100644 index 00000000000..e4dcd494306 Binary files /dev/null and b/docs/artifacts/quickstarts/media/universal-packages-create-feed.png differ diff --git a/docs/artifacts/quickstarts/media/view-published-package.png b/docs/artifacts/quickstarts/media/view-published-package.png new file mode 100644 index 00000000000..78580a3d26a Binary files /dev/null and b/docs/artifacts/quickstarts/media/view-published-package.png differ diff --git a/docs/artifacts/quickstarts/python-cli.md b/docs/artifacts/quickstarts/python-cli.md index edc8552ee53..fc3fdb35aab 100644 --- a/docs/artifacts/quickstarts/python-cli.md +++ b/docs/artifacts/quickstarts/python-cli.md @@ -1,106 +1,71 @@ --- -title: Publish and consume Python packages using the CLI -description: Publish and consume Python packages from the command-line interface +title: Publish Python packages (CLI) +description: Learn how to publish Python packages from the command-line interface. ms.service: azure-devops-artifacts -ms.topic: quickstart +ms.topic: how-to ms.custom: engagement-fy23, devx-track-python -ms.date: 04/17/2023 -monikerRange: '<= azure-devops' +ms.date: 01/15/2025 +monikerRange: "<=azure-devops" "recommendations": "true" --- -# Publish and consume Python packages using the command line +# Publish Python packages (CLI) -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] -Azure Artifacts enables developers publishing and consuming packages from Azure Artifacts feeds and public registries like pypi.org. By following this quickstart guide, you can learn how to use the command line to publish and consume Python packages. +This article guides you through publishing Python packages to an Azure Artifacts feed using the NuGet command-line interface. -## Publish Python packages +## Prerequisites -1. Sign in to your Azure DevOps organization, and then navigate to your project. +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- Download and install [Python](https://www.python.org/downloads/). | -1. Select **Artifacts** and then select your feed from the dropdown menu. +## Create a feed -1. Select **Connect to feed** and then select **twine** from the left navigation panel. +[!INCLUDE [](../includes/create-feed.md)] -1. If this is your first time using Azure Artifacts with twine, select **Get the tools** to install the prerequisites. - -1. Download and install Python, and then run the following command to install the latest version of Azure Artifacts keyring. +## Publish packages - ```Command - pip install twine keyring artifacts-keyring - ``` +1. Follow the steps in the [Project setup](../python/project-setup-python.md#project-setup) to authenticated with your feed if you haven't done so, then proceed to the next step. -1. Add a .pypirc configuration file to your home directory. +1. Sign in to your Azure DevOps organization, and then navigate to your project. - ```Command - touch ~/.pypirc - ``` - > [!NOTE] - > If you already have a .pypirc file with credentials for the public PyPI index, it is recommended to remove the [pypi] section from your file to prevent unintended publication of private packages. +1. Select **Artifacts**, and then select **Connect to feed**. + +1. Select **twine** from the left navigation area. If this is your first time using Azure Artifacts with twine, make sure to install the prerequisites by selecting **Get the tools** and following the provided steps. -1. Paste the following snippet to your .pypirc file: +1. Add a *pypirc* file to your home directory and paste the provided snippet into it. Your file should look similar to the following snippet. If you already have a *pypirc* that contains credentials for the public PyPI index, we recommend removing the *[pypi]* section to avoid accidentally publishing private packages to PyPI. - ```Command + ``` [distutils] Index-servers = - + FEED_NAME - [] - Repository = https://pkgs.dev.azure.com//PROJECT_NAME/_packaging//pypi/upload/ + [FEED_NAME] + Repository = https://pkgs.dev.azure.com/ORGANIZATION_NAME/PROJECT_NAME/_packaging/FEED_NAME/pypi/upload/ ``` -1. Create a source and wheel distributions. - - ```Command - python setup.py sdist bdist_wheel - ``` - -1. Run the following command to publish your package - - ``` - twine upload -r dist/* - ``` +1. Run the following command in your project directory to create source and wheel distributions. -## Consume Python packages - -1. Sign in to your Azure DevOps organization, and then navigate to your project. - -1. Select **Artifacts** and then select your feed from the dropdown menu. - -1. Select **Connect to feed** and then select **pip** from the left navigation panel. - -1. If this is your first time using Azure Artifacts with pip, select **Get the tools** to install the prerequisites. - -1. Download and install Python, and then run the following command to update your Python package installer. - - ```Command - python -m pip install --upgrade pip + ``` + python setup.py sdist bdist_wheel ``` -1. Install the latest Azure Artifacts keyring. +1. Run the following command to publish your package. Use the `-r REPOSITORY_NAME` flag to ensure that your private packages are not accidentally published to PyPI. - ```Command - pip install twine keyring artifacts-keyring + ``` + twine upload -r REPOSITORY_NAME dist/* ``` -1. [Create a virtual environment](https://docs.python.org/3/library/venv.html) if you don't have one already. - -1. Add a pip.ini (Windows) or pip.conf (Mac/Linux) configuration file to your virtualenv. +> [!IMPORTANT] +> You must have twine 1.13.0 or higher to use **artifacts-keyring**. See [Usage requirements](https://github.com/microsoft/artifacts-keyring#requirements) for more details. - ```Command - [global] - extra-index-url=https://pkgs.dev.azure.com///_packaging//pypi/simple/ - ``` +## Related content -1. Run the following command in your project directory to install your package. +- [Install Python packages (CLI)](install-python-packages.md) - ``` - pip install - ``` +- [Publish Python packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/pypi.md) -## Related articles +- [Use packages from PyPi.org](../python/use-packages-from-pypi.md) -- [Configure permissions](../feeds/feed-permissions.md) -- [Understand upstream sources](../concepts/upstream-sources.md) -- [Publish Python packages with Azure Pipelines](../../pipelines/artifacts/pypi.md) diff --git a/docs/artifacts/quickstarts/python-packages.md b/docs/artifacts/quickstarts/python-packages.md index 3e27159f642..66a4b3aa27d 100644 --- a/docs/artifacts/quickstarts/python-packages.md +++ b/docs/artifacts/quickstarts/python-packages.md @@ -1,126 +1,138 @@ --- title: Get started with Python packages in Azure Artifacts -description: Quickly start hosting python packages with Azure Artifacts +description: Learn how to set up your project and manage your Python packages in Azure Artifacts. ms.service: azure-devops-artifacts ms.topic: quickstart -ms.date: 01/19/2023 -monikerRange: '<= azure-devops' +ms.date: 12/03/2024 +monikerRange: "<=azure-devops" ms.custom: devx-track-python, py-fresh-zinc, engagement-fy23 "recommendations": "true" --- # Get started with Python packages in Azure Artifacts -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] -This guide will walk you through using Azure Artifacts to publish and consume Python packages to and from your feed. +Using Azure Artifacts, you can publish and download packages from feeds and public registries such as PyPi. This quickstart will guide you through creating a feed, configuring your project, and managing Python packages in your Azure Artifacts feed. In this article, you learn how to: -## Create a feed +> [!div class="checklist"] +> +> * Create a new feed. +> * Authenticate with your feed. +> * Publish Python packages. +> * Install packages from your feed. -[!INCLUDE [](../includes/create-feed.md)] - -## Connect to feed +## Prerequisites -There are two primary ways to connect to a feed to publish or consume your Python packages: +- Create an Azure DevOps [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. -1. Install and use the [artifacts-keyring](https://github.com/microsoft/artifacts-keyring) package, which will automatically set up authentication for you. -1. Manually set up credentials for your *.pypirc* pushes, and your *pip.ini*/*pip.conf* for pulls with a personal access token (PAT). +- Download and install [Python](https://www.python.org/downloads/). -> [!NOTE] -> **artifacts-keyring** is not supported on newer versions of Ubuntu. +## Get the code -## Use artifacts-keyring to set up authentication +1. If you don't have your own Python project, you can use the following sample Python project: -The [artifacts-keyring](https://github.com/microsoft/artifacts-keyring) package allows you to set up authentication to publish and consume your Python packages to and from your feed. Both [pip](https://pypi.org/project/pip/) and [twine](https://pypi.org/project/twine/) use the Python [keyring library](https://pypi.org/project/keyring/) to find credentials. + ``` + https://github.com/microsoft/python-package-template + ``` -> [!IMPORTANT] -> You must have pip 19.2 and twine 1.13.0 or higher to use **artifacts-keyring**. See [Usage requirements](https://github.com/microsoft/artifacts-keyring#requirements) for more details. +1. To build your wheel and source distribution, run the following commands in your project directory: -1. In an elevated command prompt window, run the following command to install the artifacts-keyring package: - - ```Command - pip install artifacts-keyring - ``` - -1. To install a package from your feed, run the following command: - - - **Project scoped feed**: + ``` + pip install --upgrade build + python -m build + ``` - ```Command - pip install --index-url https://pkgs.dev.azure.com///_packaging//pypi/simple - ``` - - - **Organization scoped feed**: - - ```Command - pip install --index-url https://pkgs.dev.azure.com//_packaging//pypi/simple - ``` +1. If your Python project has a *setup.py* file, you can also use this command to build your package: -1. To publish a package to your feed, run the following command: - - - **Project scoped feed**: - - ```Command - twine upload --repository-url https://pkgs.dev.azure.com///_packaging//pypi/upload - ``` + ``` + python setup.py sdist bdist_wheel + ``` + +## Create a feed + +[!INCLUDE [](../includes/create-feed.md)] + +## Connect to a feed + +#### [twine](#tab/twine) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to feed**. - - **Organization scoped feed**: +1. Select **twine** under the **Python** section. + +1. If this is your first time using Azure Artifacts with twine, select **Get the tools** and follow the steps to install the prerequisites. + +1. Add a *pypirc* file to your home directory and paste the provided snippet. Your file should look like this: + + ``` + [distutils] + Index-servers = + FEED_NAME - ```Command - twine upload --repository-url https://pkgs.dev.azure.com//_packaging//pypi/upload - ``` + [FEED_NAME] + Repository = https://pkgs.dev.azure.com/ORGANIZATION_NAME/PROJECT_NAME/_packaging/FEED_NAME/pypi/upload/ + ``` > [!NOTE] -> The artifacts-keyring package is layered on top of the Azure Artifacts Credential Provider. For more advanced configuration options, check out the [artifacts-credprovider](https://github.com/microsoft/artifacts-credprovider) repository. - -## Manually configure authentication +> If your *.pypirc* file already contains credentials for the public PyPI index, we recommend removing the `[pypi]` section to prevent accidental publication of private packages to PyPI. -1. Create a [Personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read** scope to authenticate with Azure DevOps. +#### [pip](#tab/pip) -1. Select **Artifacts**, and then select your feed then select **Connect to feed**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. - :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="A screenshot highlighting the connect to feed button."::: +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to feed**. -1. Select **pip** under the **Python** section. +1. Select **pip** under the **Python** section. - :::image type="content" source="media/pip-feed.png" alt-text="A screenshot highlighting the pip package type."::: +1. If this is your first time using Azure Artifacts with pip, select **Get the tools** and follow the steps to install the prerequisites. -1. If this is your first time using Azure Artifacts with twine, select **Get the tools** to download and install the prerequisites. +1. [Create a virtual environment](https://docs.python.org/3/library/venv.html). -1. [Create a virtualenv](https://docs.python.org/3/library/venv.html), if you don't already have one. +1. Add a *pip.ini* file (Windows) or *pip.conf* file (Mac/Linux) to your virtual environment and paste the provided snippet into it. Your file should resemble the following: -1. Add a *pip.ini* (Windows) or a *pip.conf* (Mac/Linux) file to your virtualenv. Make sure you don't check your personal access token into a public repository. + ``` + [global] + index-url=https://pkgs.dev.azure.com/ORGANIZATION_NAME/PROJECT_NAME/_packaging/FEED_NAME/pypi/simple/ + ``` - - **Project scoped feed**: +- - - - ``` - [global] - extra-index-url=https://:@pkgs.dev.azure.com///_packaging//pypi/simple/ - ``` +## Publish packages - - **Organization scoped feed**: +1. Run this command in your project directory to create source and wheel distributions: - ``` - [global] - extra-index-url=https://:@pkgs.dev.azure.com//_packaging//pypi/simple/ - ``` + ``` + python setup.py sdist bdist_wheel + + ``` -1. Run the following command in your project directory to install your package. +1. Run the following command to publish your package. Use the -r *FEED_NAME* flag to ensure your private packages are not accidentally published to PyPI. - ```Command - pip install + ``` + twine upload -r dist/* ``` -When you connect to Azure DevOps for the first time, you'll be prompted for credentials. Enter your user name(any string) and your personal access token in the appropriate fields. The credentials will be cached locally and used to automatically sign you in the next time you use the service. +## Install packages -> [!NOTE] -> If you want to publish or consume your packages using Azure Pipelines, use the [Python Pip Authenticate](/azure/devops/pipelines/tasks/reference/pip-authenticate-v1) task to authenticate and install packages, or the [Python Twine Upload Authenticate](/azure/devops/pipelines/tasks/reference/twine-authenticate-v1) task to publish your packages. +1. Run this command in your project directory to install your packages: + + ``` + pip install + ``` -## Related articles +1. To install a specific package, run the following command, replacing the placeholder with the package name from your feed. -- [Use feed views to share packages](../feeds/views.md) + ```Command + pip install + ``` -- [Publish Python packages with Azure Pipelines](../../pipelines/artifacts/pypi.md). +## Next steps -- [Build Python apps](../../pipelines/ecosystems/python.md). +> [!div class="nextstepaction"] +> [Use packages from Python package index (PyPI)](../python/use-packages-from-pypi.md) +> [Set up upstream sources](../how-to/set-up-upstream-sources.md) +> [Publish Python packages with Azure Pipelines](../../pipelines/artifacts/pypi.md) diff --git a/docs/artifacts/quickstarts/universal-packages.md b/docs/artifacts/quickstarts/universal-packages.md index 41854d064f7..12dd19c3340 100644 --- a/docs/artifacts/quickstarts/universal-packages.md +++ b/docs/artifacts/quickstarts/universal-packages.md @@ -1,141 +1,90 @@ --- -title: Publish and download universal packages in Azure Artifacts -description: How to publish and download universal packages to and from Artifacts feeds. +title: Publish Universal Packages in Azure Artifacts +description: Learn how to publish Universal Packages to an Azure Artifacts feed. ms.assetid: f47b858c-138d-426d-894c-a5fe1d5aa08e ms.service: azure-devops-artifacts +ms.custom: devx-track-azurecli ms.topic: conceptual -ms.date: 05/19/2023 +ms.date: 01/16/2025 monikerRange: 'azure-devops' -"recommendations": "true" --- -# Publish and download universal packages in Azure Artifacts +# Publish Universal Packages from Azure Artifacts feeds -Universal Packages offer developers the capability to store an extensive array of package types that extend beyond the conventional ones, such as NuGet, npm, Maven, or Python packages. Using Azure CLI, you can conveniently publish and download universal packages directly from the command line. The size of published packages can vary, reaching up to 4 TB, but must always maintain the essential requirement of including a name and version number. This article will walk you through the steps to publish and download your universal packages to your Azure Artifacts feed. +[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] + +Universal Packages enable developers to store a wide range of package types beyond traditional formats like NuGet, npm, Python packages, etc. +Using Azure CLI, you can publish Universal Packages directly from the command line. These packages can be as large as 4 TiB, but they must always include a name and version number. This article guides you through publishing Universal Packages to your Azure Artifacts feed. ## Prerequisites -- Install [Azure CLI](/cli/azure/install-azure-cli). -- If you're using Linux, make sure you install the [.NET on Linux](/dotnet/core/linux-prerequisites) version. -- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../..//organizations/projects/create-project.md) if you haven't already. -- An Azure Artifacts feed. [Create a feed](../../artifacts/get-started-nuget.md#create-a-feed), if you don't have one already. +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- Install [Azure CLI](/cli/azure/install-azure-cli).
- Install the [Azure DevOps extension](#install-azure-devops-extension) version 0.14.0 or higher. | -## Project setup +## Install Azure DevOps extension -#### [Windows](#tab/Windows/) +Ensure that you have Azure CLI (version 2.10.1 or higher) installed. Then, follow the steps below to install or update the Azure DevOps extension for managing Azure DevOps services from the command line. -1. Run the following command to install the Azure DevOps extension. +1. Run the following command to install the Azure DevOps extension: ```azurecli az extension add --name azure-devops ``` -2. If you already have the Azure DevOps extension installed and wish to update it to the latest version, run the following command:: +1. If the Azure DevOps extension is already installed and you want to update it to the latest version, run: ```azurecli az extension update --name azure-devops ``` -3. Log in to Azure. - - ```azurecli - az login - ``` - -> [!TIP] -> To access tenants without subscriptions, run `az login --allow-no-subscription`. +## Create a feed -4. Set your project and organization as the CLI's default. +1. Sign in to your Azure DevOps organization and navigate to your project. - ```azurecli - az devops configure --defaults project= organization=https://dev.azure.com/ - ``` +1. Select **Artifacts**, and then select **Create Feed**. -#### [Other](#tab/Other/) +1. Provide a **Name** for your feed, choose the **Visibility** option that defines who can view your packages, check **Include packages from common public sources** if you want to include packages from sources like *nuget.org* or *npmjs.com*, and for **Scope**, decide whether the feed should be scoped to your project or the entire organization. -1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **Packaging Read & write** scope, and then copy it to your clipboard. +1. Select **Create** when you're done. -1. Run the following command to log in. When prompted, enter the personal access token you created in the previous step. - - ```azurecli - az devops login --organization https://dev.azure.com/ - ``` -*** + :::image type="content" source="../media/create-new-feed-azure-devops.png" alt-text="A screenshot displaying how to create a new feed in Azure DevOps Services."::: -## Publish packages +## Publish Universal Packages -To publish a universal package, run the following command in an elevated command prompt. Package names must be lowercase, start and end with letters or numbers, and contain only letters, numbers, and nonconsecutive dashes, underscores, and periods. Package versions must be lowercase without build metadata (+ suffix). See [SemVer](https://semver.org/spec/v2.0.0.html) to learn more about semantic versioning. +To publish a Universal Package to your feed, you need to provide a package name and version number. +The package name must be in lowercase, start and end with a letter or number, and can only include letters, numbers, and non-consecutive dashes `-`, underscores `_`, or periods `.`. +Similarly, the package version must also be in lowercase and should not contain build metadata (indicated by a + suffix). See [semantic versioning](https://semver.org/spec/v2.0.0.html) for more details. -- Organization-scoped feed: +1. Run the following command to publish your Universal Package to your feed: - ```azurecli - az artifacts universal publish --organization https://dev.azure.com/ --feed --name --version --path --description - ``` + - **Project-scoped feed**: + + ```azurecli + az artifacts universal publish --organization https://dev.azure.com/ --project --scope project --feed --name --version --path --description + ``` -- Project-scoped feed: - - ```azurecli - az artifacts universal publish --organization https://dev.azure.com/ --project --scope project --feed --name --version --path --description - ``` + - **Organization-scoped feed**: + + ```azurecli + az artifacts universal publish --organization https://dev.azure.com/ --feed --name --version --path --description + ``` + +> [!NOTE] +> Universal Packages containing an exceptionally large number of files (100K+) may fail to publish. In this case, we recommend bundling the files into a *ZIP* or *TAR* archive to reduce the file count. ## View published packages 1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Artifacts**, and then select your feed from the drop-down menu. Once publishing is completed successfully, your package should be available in your feed. - - :::image type="content" source="media/universal-package-published.png" alt-text="A screenshot showing the newly published universal package."::: - -## Download packages - -To download a universal package using Azure CLI, run the following command in an elevated command prompt. - -- Organization-scoped feed: - - ```azurecli - az artifacts universal download --organization https://dev.azure.com/ --feed --name --version --path - ``` - -- Project-scoped feed: +1. Select **Artifacts**, and then select your feed from the dropdown menu. Once the publishing process is successfully completed, your package should be available in your feed. - ```azurecli - az artifacts universal download --organization https://dev.azure.com/ --project --scope project --feed --name --version --path - ``` + :::image type="content" source="media/view-published-package.png" alt-text="A screenshot displaying the newly published Universal Package." lightbox="media/view-published-package.png"::: -### Download specific files +## Related content -If you only want to download specific files, you can use the `--file-filter` parameter to download a subset of files. See [File matching patterns reference](../../pipelines/tasks/file-matching-patterns.md) for more details. - -Example: *--file-filter *logs/*.log* would match any file ending with *logs* and with the extension *.log* (Example: build123_logs.log). - -- Organization-scoped feed: - - ```azurecli - az artifacts universal download --organization https://dev.azure.com/ --feed --name --version --path --file-filter - ``` -- Project-scoped feed: - - ```azurecli - az artifacts universal download --organization https://dev.azure.com/ --project --scope project --feed --name --version --path --file-filter - ``` - -### Download the latest version - -You can use wildcards `*` to download the latest version of your Universal Packages. - -**Examples**: - -- `--version '*'`: download the latest version. - -- `--version '1.*'`: download the latest version with major 1. - -- `--version '1.2.*'`: download the latest patch release with major 1 and minor 2. - -> [!NOTE] -> Wildcard patterns are not supported with pre-release versions (packages with a dash in their version number). +- [Download Universal Packages](download-universal-packages.md) -## Related articles +- [Publish and download Universal Packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/universal-packages.md) -- [Publish and download universal packages with Azure Pipelines](../../pipelines/artifacts/universal-packages.md). -- [Delete and recover packages](../how-to/delete-and-recover-packages.md). -- [Configure feed permissions](../feeds/feed-permissions.md) +- [Universal Packages upstream sources](../universal-packages/universal-packages-upstream.md) diff --git a/docs/artifacts/reference/artifactignore.md b/docs/artifacts/reference/artifactignore.md index 1fbd93b251e..cf52af67fd3 100644 --- a/docs/artifacts/reference/artifactignore.md +++ b/docs/artifacts/reference/artifactignore.md @@ -1,27 +1,35 @@ --- title: Use the .artifactignore file -description: Use .artifactignore to exclude files and folders when you publish Artifacts +description: Learn how to use the .artifactignore file to exclude specific files and folders when publishing artifacts in Azure Pipelines. ms.assetid: bbaf8799-d08b-4f1a-9546-4b3b8da40a0b ms.service: azure-devops-artifacts ms.topic: reference -ms.date: 01/26/2022 +ms.date: 09/09/2024 monikerRange: 'azure-devops' "recommendations": "true" --- -# Use .artifactignore +# Use the *.artifactignore* file [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -The *.artifactignore* is a text file that controls which files are uploaded when you publish a Universal Package or a Pipeline Artifact. +The `artifactignore` file works similarly to a `gitignore` file but serves a different purpose. Instead of specifying files to be ignored by Git, it's used in Azure Pipelines to control which files are excluded when publishing pipeline artifacts or Universal Packages. This file can help reduce your pipeline execution and improve its efficiency by preventing unnecessary files from being copied into the staging directory before publishing. -*.artifactignore* is typically checked into your version control repository and the syntax is similar to that of *.gitignore*. +The *artifactignore* file has a similar syntax to that of a *gitignore* file and is typically stored in your version control system. However, unlike *gitignore*, the *artifactignore* file doesn't always need to be in the root of your repository. Its location depends on the path specified in the publish task. If placed incorrectly, the task won't recognize it, leading to unintended results. For example, if the path is *$(System.DefaultWorkingDirectory)/bin/artifacts*, the *artifactignore* file should be placed in the */bin/artifacts* directory. -Using the *.artifactignore* file can help reduce your pipeline execution time by avoiding copying files into your staging directory before publishing your artifacts. +> [!Note] +> The *artifactignore* file does not work with the [Publish Build Artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) task, use the [Publish Pipeline Artifacts](/azure/devops/pipelines/tasks/reference/publish-pipeline-artifact-v1) task instead. + +## Syntax + +The *.artifactignore* follows the same syntax as the [.gitignore](https://git-scm.com/docs/gitignore) with a few exceptions. The plus sign character `+` is not supported in URL paths, and certain package types, such as Maven, may have limitations with semantic versioning metadata. + +> [!Note] +> By default, the *.gitignore* file is ignored unless you have an *.artifactignore* file. To include it, simply create an empty *.artifactignore* file. ## Example -In the following example, we will be ignoring all files except the ones in the *src/MyApp/bin/Release* directory. +In this example, all files will be ignored except for those located in the *src/MyApp/bin/Release* directory. ```artifactignore **/* @@ -29,18 +37,11 @@ In the following example, we will be ignoring all files except the ones in the * ``` > [!IMPORTANT] -> The *.artifactignore* file must be in the directory provided to the `targetPath` argument in your [Publish Pipeline Artifacts](/azure/devops/pipelines/tasks/reference/publish-pipeline-artifact-v1) task. - -## Syntax - -The *.artifactignore* follows the same syntax as the [.gitignore](https://git-scm.com/docs/gitignore) with some minor limitations. The plus sign character `+` is not supported in URL paths and some of the semantic versioning metadata for some package types like Maven. - -> [!Note] -> The *.gitignore* file is ignored by default if you don't have an *.artifactignore* file. You can re-include it by creating an empty *.artifactignore* file. +> The *.artifactignore* file must be placed in the directory specified in the `targetPath` argument in your [Publish Pipeline Artifacts](/azure/devops/pipelines/tasks/reference/publish-pipeline-artifact-v1) task. -## Related articles +## Related content - [Publish and download pipeline artifacts](../../pipelines/artifacts/pipeline-artifacts.md) -- [Limits on package sizes and counts](limits.md) -- [Package componentization](../collaborate-with-packages.md) +- [Publish and download Universal Packages](../../pipelines/artifacts/universal-packages.md) +- [Artifact sources](../../pipelines/release/artifacts.md) diff --git a/docs/artifacts/reference/limits.md b/docs/artifacts/reference/limits.md index e9bb901bcb8..5226407dbf7 100644 --- a/docs/artifacts/reference/limits.md +++ b/docs/artifacts/reference/limits.md @@ -13,6 +13,9 @@ monikerRange: '<= azure-devops' Azure Artifacts is a highly scalable package management solution that enables developers to create, host, and share different types of packages. In this article, we will cover the size and count limits that developers should be aware of when using Azure Artifacts. Some of these limits are imposed by the client tools that Azure Artifacts integrates with (example nuget.exe). +> [!NOTE] +> Azure Artifacts provides 2 GiB of free storage for each organization. This free tier is designed to help you evaluate if Azure Artifacts fits your workflow. As your organization starts handling more critical tasks, we recommend [set up billing](../../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing) to ensure you have the appropriate resources. + ## Count limits - **5000 versions** per package ID. @@ -24,19 +27,23 @@ Azure Artifacts is a highly scalable package management solution that enables de ## Size limits -- **NuGet packages**: limited to 500 MB per file. +- **NuGet packages**: limited to 500 MiB per file. -- **Npm packages**: limited to 500 MB per file. +- **Npm packages**: limited to 500 MiB per file. -- **Maven packages**: limited to 500 MB per file. +- **Maven packages**: limited to 500 MiB per file. + +- **Python packages**: limited to 500 MiB per file. -- **Python packages**: limited to 500 MB per file. ::: moniker range="= azure-devops" -- **Universal Packages**: up to 4 TB per file (Recommended for large binary files). -::: moniker-end +- **Cargo packages**: limited to 500 MiB per file. + +- **Universal Packages**: up to 4 TiB per file (Recommended for large binary files). > [!NOTE] -> Universal Packages are only available in Azure DevOps Services. +> Universal Packages containing an exceptionally large number of files (100K+) may fail to publish. In this case, we recommend bundling the files into a *ZIP* or *TAR* archive to reduce the file count. + +::: moniker-end ## Related articles diff --git a/docs/artifacts/start-using-azure-artifacts.md b/docs/artifacts/start-using-azure-artifacts.md index 521e900670f..eab444016ea 100644 --- a/docs/artifacts/start-using-azure-artifacts.md +++ b/docs/artifacts/start-using-azure-artifacts.md @@ -1,152 +1,222 @@ --- -title: Azure Artifacts overview -description: Learn about Azure Artifacts offering +title: What is Azure Artifacts? +description: Learn how to get started with Azure Artifacts. ms.service: azure-devops-artifacts ms.topic: quickstart ms.assetid: 45ECCEFD-3804-4D8C-8567-57C84F92A705 ms.author: rabououn -author: chcomley -ms.date: 09/20/2022 +author: ramiMSFT +ms.date: 01/09/2025 monikerRange: '<= azure-devops' --- -# Azure Artifacts overview +# What is Azure Artifacts? [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Azure Artifacts enables developers to share their code efficiently and manage all their packages from one place. With Azure Artifacts, developers can publish packages to their feeds and share it within the same team, across organizations, and even publicly. Developers can also consume packages from different feeds and public registries such as NuGet.org or npmjs.com. Azure Artifacts supports multiple package types such as NuGet, npm, Python, Maven, and Universal Packages. +Azure Artifacts provides developers with a streamlined way to manage all their dependencies from a single feed. These feeds serve as repositories for storing, managing, and sharing packages, whether within your team, across organizations, or publicly online. -## Prerequisites - -- An Azure DevOps organization and a project. Create an [organization](../organizations/accounts/create-organization.md) or a [project](../organizations/projects/create-project.md#create-a-project) if you haven't already. - -- [Allow domain URLs and IP addresses](../organizations/security/allow-list-ip-url.md) if your organization is using a firewall or a proxy server. +Azure Artifacts supports multiple package types, including NuGet, npm, Python, Maven, Cargo, and Universal Packages. > [!NOTE] -> If you anticipate using more than the provided 2-GiB storage, it is recommended to [set up billing](../organizations/billing/set-up-billing-for-your-organization-vs.md) for your organization. - -::: moniker range="tfs-2018" +> Azure Artifacts provides 2 GiB of free storage for each organization. This free tier is designed to help you evaluate if Azure Artifacts fits your workflow. As your organization starts handling more critical tasks, [increase the storage limit for Azure Artifacts](#increase-azure-artifacts-storage-limit) to ensure you have the appropriate resources. -## Install Azure Artifacts +## Prerequisites -Azure Artifacts comes pre-installed in TFS 2018. If the extension is removed, you can install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms.feed). +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../organizations/projects/create-project.md).
- Allow [Azure Artifacts Domain URLs and IP addresses](../organizations/security/allow-list-ip-url.md) if your organization is using a firewall or a proxy server. | -## Assign licenses in TFS +## Create a new feed -1. From any collection in TFS, hover over the settings menu and select the **Users** page. Then, select **Azure Artifacts**. +Azure Artifacts feeds are organizational constructs that enable you to store, manage, and share your packages while maintaining access control. Feeds are not limited to specific package types; you can store a variety of packages, such as npm, NuGet, Maven, Python, Cargo, and Universal Packages in a single feed. See [What are feeds](concepts/feeds.md) for more details. - :::image type="content" source="media/users-hub-tfs.png" alt-text="Assign user licenses in TFS"::: +Follow the instructions below to create a new feed: -2. Select **Assign**, enter the user to assign licenses, and then select **Ok** +[!INCLUDE [](includes/create-feed.md)] - * Users with Visual Studio Enterprise subscriptions get Azure Artifacts automatically. - * Ensure that your Visual Studio Enterprise subscribers are assigned [VS Enterprise Access level](../organizations/security/change-access-levels.md). +## Get started -::: moniker-end +With Azure Artifacts, you can publish and install various package types from feeds and public registries such as nuget.org, npmjs.com, Maven Central, etc. Select your package type to get started: -::: moniker range=">=azure-devops-2019" +::: moniker range="azure-devops" -## Get started with Azure Artifacts +# [NuGet](#tab/nuget) -With Azure Artifacts, you can publish and consume different types of packages. Select your package type to get started: +- **Quickstart:** [Get started with NuGet packages in Azure Artifacts](./get-started-nuget.md) -# [NuGet](#tab/nuget) +# [dotnet](#tab/dotnet) -- [Get started with NuGet packages and Azure Artifacts](./get-started-nuget.md) +- **Quickstart:** [Publish and restore NuGet packages from the command line (dotnet)](nuget/dotnet-exe.md) # [Npm](#tab/npm) -- [Get started with npm packages and Azure Artifacts](./get-started-npm.md) +- **Quickstart:** [Get started with npm packages in Azure Artifacts](./get-started-npm.md) # [Maven](#tab/maven) -- [Get started with Maven packages and Azure Artifacts](./get-started-maven.md) +- **Quickstart:** [Get started with Maven packages in Azure Artifacts](./get-started-maven.md) + +# [Gradle](#tab/gradle) + +- **Quickstart:** [Get started with Gradle packages in Azure Artifacts](./maven/publish-with-gradle.md) # [Python](#tab/python) -- [Get started with Python packages and Azure Artifacts](./quickstarts/python-packages.md) +- **Quickstart:** [Get started with Python packages in Azure Artifacts](./quickstarts/python-packages.md) + +# [Cargo](#tab/cargo) + +- **Quickstart:** [Get started with Cargo packages in Azure Artifacts](./get-started-cargo.md) # [Universal Packages](#tab/universalpackages) -- [Universal Packages quickstart](./quickstarts/universal-packages.md) +- **Quickstart:** [Get started with Universal Packages in Azure Artifacts](./quickstarts/universal-packages.md) --- -## Feature availability +::: moniker-end + +::: moniker range="azure-devops-2022" + +# [NuGet](#tab/nugetserver22) + +- **Quickstart:** [Get started with NuGet packages in Azure Artifacts](./get-started-nuget.md) + +# [dotnet](#tab/dotnetserver22) + +- **Quickstart:** [Publish and restore NuGet packages from the command line (dotnet)](nuget/dotnet-exe.md) + +# [Npm](#tab/npmserver22) + +- **Quickstart:** [Get started with npm packages in Azure Artifacts](./get-started-npm.md) + +# [Maven](#tab/mavenserver22) + +- **Quickstart:** [Get started with Maven packages in Azure Artifacts](./get-started-maven.md) + +# [Gradle](#tab/gradleserver22) + +- **Quickstart:** [Get started with Gradle packages in Azure Artifacts](./maven/publish-with-gradle.md) + +# [Python](#tab/pythonserver22) + +- **Quickstart:** [Get started with Python packages in Azure Artifacts](./quickstarts/python-packages.md) + +# [Cargo](#tab/cargoserver22) + +- **Quickstart:** [Get started with Cargo packages in Azure Artifacts](./get-started-cargo.md) -| Package type | Azure DevOps Services | Azure DevOps Server | TFS-2018 | -|-----------------------------------|------------------------|----------------------------------------------|----------------------------------------------| -| **NuGet packages** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | -| **npm packages** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | -| **Maven packages** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | -| **Python packages** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | Server 2019 Update 1 and newer, Server 2020, and Server 2022. | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | -| **Universal Packages** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../media/icons/delete-icon.png" border="false"::: | +--- + +::: moniker-end + +::: moniker range="azure-devops-2020" -## Artifacts free tier and upgrade +# [NuGet](#tab/nugetserver20) -Azure Artifacts is free for every organization up to 2 GiB of storage. Once you reach the maximum storage limit, you can no longer upload new artifacts and need to delete some of your existing artifacts or [set up billing](../organizations/billing/set-up-billing-for-your-organization-vs.md) to increase your storage limit. See the [Pricing Calculator](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) to learn more about Azure DevOps billing. +- **Quickstart:** [Get started with NuGet packages in Azure Artifacts](./get-started-nuget.md) -## Organization billing settings +# [dotnet](#tab/dotnetserver20) -Follow the steps outlined below to view your billing settings for your organization: +- **Quickstart:** [Publish and restore NuGet packages from the command line (dotnet)](nuget/dotnet-exe.md) -1. Sign in to your Azure DevOps organization. +# [Npm](#tab/npmserver20) -1. Select ![gear icon](../media/icons/gear-icon.png) **Organization settings**. +- **Quickstart:** [Get started with npm packages in Azure Artifacts](./get-started-npm.md) - :::image type="content" source="../media/settings/open-admin-settings-vert.png" alt-text="A screenshot showing how to access the organization settings"::: +# [Maven](#tab/mavenserver20) -1. Select **Billing**. +- **Quickstart:** [Get started with Maven packages in Azure Artifacts](./get-started-maven.md) - :::image type="content" source="../organizations/billing/media/shared/select-billing-organization-settings.png" alt-text="A screenshot showing how to access the billing settings"::: +# [Gradle](#tab/gradleserver20) -1. View your Artifacts tier and usage limit. +- **Quickstart:** [Get started with Gradle packages in Azure Artifacts](./maven/publish-with-gradle.md) - :::image type="content" source="media/billing-settings.png" alt-text="A screenshot showing Artifacts tier and usage limit"::: +# [Python](#tab/pythonserver20) + +- **Quickstart:** [Get started with Python packages in Azure Artifacts](./quickstarts/python-packages.md) + +--- + +::: moniker-end + +## Feature availability + +| Packages | Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019 | +|------------------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------|------------------------------------|------------------------------------| +| **NuGet** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | +| **dotnet** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/delete-icon.png" border="false"::: | +| **npm** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | +| **Maven** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | +| **Gradle** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | +| **Python** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | +| **Cargo** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/delete-icon.png" border="false":::|:::image type="icon" source="../media/icons/delete-icon.png" border="false":::| +| **Universal Packages** | :::image type="icon" source="../media/icons/checkmark.png" border="false"::: | :::image type="icon" source="../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../media/icons/delete-icon.png" border="false"::: | + +::: moniker range="azure-devops" ## View Artifacts storage consumption -- [Organization-level storage](./artifact-storage.md#organization-level-storage) -- [Project-level storage](./artifact-storage.md#project-level-storage) +The artifact storage UI, accessible through your organization or project settings, lets you monitor storage usage at both the organization and project levels: -## FAQs +- [Project-level storage](./artifact-storage.md#project-level-storage): Provides an overview of total storage usage and consumption by artifact type. -### Q: Which artifacts count toward my total billed storage? +- [Organization-level storage](./artifact-storage.md#organization-level-storage): Provides an overview of total storage usage including consumption by project and artifact type. -A: You get billed for all package types (npm, NuGet, Python, Maven, and Universal Packages) including packages stored from upstream sources. However, you don't get billed for Pipeline Artifacts, and Pipeline Caching. +## Increase Azure Artifacts storage limit -> [!NOTE] -> Packages in the recycle bin still count as part of your storage consumption. Those packages get deleted permanently after 30 days. If you want to delete them sooner, navigate to your recycle bin and delete them manually. +Azure Artifacts provides 2 GiB of free storage for each organization. When your organization reaches the maximum storage limit, publishing new artifacts will no longer be possible. To continue, you can either delete some of your existing artifacts or follow these steps to increase your storage limit: -### Q: I'm storing Artifacts but my storage consumption shows 0 GiB? +1. [Set up billing for your organization](../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing-for-your-organization). -A: 1 GiB is currently our lowest granularity, so you most likely haven't reached 1 GiB yet. +1. Sign in to your Azure DevOps organization, select **Organization settings** > **Billing**, and adjust your Artifacts usage limit by selecting **No limit, pay for what you use** from the dropdown menu. -### Q: How can I control how many days Artifacts are kept? +1. Select **Save** when you're done. -A: You can set up the retention policies to delete packages automatically. For more information, see [How to use retention policies to delete old packages](how-to/delete-and-recover-packages.md#delete-packages-automatically-with-retention-policies). + :::image type="content" source="media/adjust-artifacts-usage-limit.png" alt-text="Screenshot showing adjusted usage limit for Artifacts on Billing page."::: -### Q: How can I delete specific packages? +::: moniker-end -A: See [Delete and recover packages](how-to/delete-and-recover-packages.md) for details. +## FAQs + +::: moniker range=" azure-devops" + +#### Q: Which artifacts contribute to my total billed storage? + +A: You are charged for all package types (npm, NuGet, Python, Maven, Cargo, and Universal Packages), including packages stored from upstream sources. However, there are no charges for Pipeline Artifacts and Pipeline Caching. + +> [!IMPORTANT] +> Packages in the recycle bin contribute to your overall storage consumption. These packages are permanently deleted after 30 days. To remove them sooner, go to your recycle bin and delete them manually. -### Q: How long does it take for deleted Artifacts to reflect in the amount of billed storage? +#### Q: What happens if I remove my Azure Subscription from my Azure DevOps organization? -A: Deletion of artifacts doesn't register immediately. Storage consumption should be updated within 24 hours, but in some cases it may take up to 48 hours. If you're blocked from uploading Artifacts, as a workaround you can temporarily increase your usage level, then reduce the level back once the storage metrics are updated. +A: Removing your Azure Subscription from your Azure DevOps organization limits your access to the free tier. If your storage usage exceeds 2 GiB, you will have read-only access to packages. To publish new packages, you must reduce your storage usage below 2 GiB. Alternatively, you can reconnect an Azure subscription to your organization and set up billing to [upgrade your storage tier](#increase-azure-artifacts-storage-limit). -The **used** column on the Billing page of your Organization gets updated once a day. When you delete an Artifact, it may not reflect immediately on your billing page. The Artifact Storage page however gets updated more frequently, so you may see a small discrepancy between the two pages. +#### Q: Why does my storage consumption show as 0 GiB even though I'm storing Artifacts? -:::image type="content" source="media/settings-vs-storage.png" alt-text="Artifacts billing settings vs Artifacts storage data"::: +A: The smallest unit of measurement for storage is currently 1 GiB. It's likely that your storage usage hasn't yet surpassed the 1-GiB threshold. -### Q: What happens if I remove my Azure Subscription from my Azure DevOps organization? +#### Q: How long does it typically take for the removal of Artifacts to be reflected in the billed storage amount? -A: When you remove your Azure Subscription from your Azure DevOps organization, you only have access to the free tier. If you used more than 2 GiB of storage, you can only read packages. You can't publish new packages until you lower your storage below 2 GiB. Or, you can reconnect an Azure subscription to your organization and set up billing to increase your storage tier. +A: Deleting artifacts may not be immediately reflected in the system. Storage consumption typically updates within 24 hours, but in some cases, it may take up to 48 hours. If you're unable to upload artifacts, a temporary workaround is to increase your usage level and then decrease it once the storage metrics are updated. + +The **Used** column on your organization's billing page is updated once a day, so changes may not be reflected right away. However, the **Artifact Storage** page is updated more frequently, which could result in a slight discrepancy between the two pages. + +:::image type="content" source="media/settings-vs-storage.png" alt-text="A screenshot showing Artifacts storage consumption."::: ::: moniker-end -## Related articles +#### Q: How can I manage the retention duration of old packages? + +A: You can set up the retention policies to automatically delete old packages. However, that are promoted to a view are not affected by retention policies and will not be deleted. See [How to use retention policies to delete old packages](how-to/delete-and-recover-packages.md#delete-packages-automatically-with-retention-policies) for more details. + +#### Q: How do I delete specific packages manually? + +A: See [Delete and recover packages](how-to/delete-and-recover-packages.md) for details. + +## Related content -- [View storage usage](./artifact-storage.md) -- [Feeds overview](./concepts/feeds.md) +- [Package sizes and count limits](./reference/limits.md) - [Manage permissions](./feeds/feed-permissions.md) -- [Feed views](./concepts/views.md) +- [Set up upstream sources](./how-to/set-up-upstream-sources.md) diff --git a/docs/artifacts/symbols/debug-with-symbols-visual-studio.md b/docs/artifacts/symbols/debug-with-symbols-visual-studio.md index 278992373a8..745741dbc3f 100644 --- a/docs/artifacts/symbols/debug-with-symbols-visual-studio.md +++ b/docs/artifacts/symbols/debug-with-symbols-visual-studio.md @@ -3,7 +3,6 @@ title: Debug with symbols in Visual Studio description: Use symbols to debug your application with Visual Studio. ms.assetid: 318323C4-5B2F-45DE-A834-CCE03C670F8C ms.service: azure-devops-artifacts -ms.custom: contperf-fy22q1 ms.topic: conceptual ms.date: 07/20/2021 monikerRange: '<= azure-devops' @@ -60,4 +59,4 @@ Once Visual Studio finds and loads your symbols, you should be able to step thro - [Symbols overview](../concepts/symbols.md). - [Debug with WinDbg](debug-with-symbols-windbg.md). -- [Artifacts in Azure Pipelines](../../pipelines/artifacts/artifacts-overview.md) \ No newline at end of file +- [Artifacts in Azure Pipelines](../../pipelines/artifacts/artifacts-overview.md) diff --git a/docs/artifacts/symbols/debug-with-symbols-windbg.md b/docs/artifacts/symbols/debug-with-symbols-windbg.md index 73d0bed8461..0c19994c1a8 100644 --- a/docs/artifacts/symbols/debug-with-symbols-windbg.md +++ b/docs/artifacts/symbols/debug-with-symbols-windbg.md @@ -2,10 +2,9 @@ title: Debug with symbols in WinDbg description: Use WinDbg to consume symbols and debug your application ms.assetid: C8C003EA-79C8-49EF-BEBD-35548505F0CF -ms.custom: contperf-fy22q1 ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 07/26/2021 +ms.date: 09/26/2023 monikerRange: '<= azure-devops' --- @@ -13,36 +12,43 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - Azure Artifacts offers a dedicated symbols server to publish your symbols. You can connect a debugger to automatically retrieve the correct symbol files and debug your application. Using WinDbg, you can load an executable or attach the debugger to a running process, consume your symbols, set up breakpoints, and step through and analyze your code. +Azure Artifacts provides a dedicated symbols server for publishing symbols. This server allows you to connect a debugger that can automatically fetch the correct symbol files, enabling you to debug your application efficiently. With tools like WinDbg, you can load an executable, attach the debugger to a running process, consume your symbols, set up breakpoints, and systematically analyze your code. -## Add the symbol server to WinDbg +## Add symbol server to WinDbg To use the Azure Artifacts symbol server, you must add your organization to the symbols search path, but before we can do that, we must first create a personal access token. -1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **Symbols (read)** scope and copy it to your clipboard. -1. Open WinDbg, or [install](https://www.microsoft.com/store/p/windbg-preview/9pgjgd53tn86) it if you haven't already. -1. Select **File** > **OpenExecutable** to load the executable you wish to debug. -1. Run the following command to set the symbols path. Replace the placeholder ** with your organization name: +1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Symbols (read)** scope and copy it to your clipboard. + +1. Open WinDbg, or [install](/windows-hardware/drivers/debugger/) it if you haven't already. + +1. Select **File**, and then select **OpenExecutable** to load the executable you wish to debug. + +1. Run the following command to set the symbols path. Replace the placeholder with your specific organization name: + ```Command .sympath+ https://artifacts.dev.azure.com//_apis/symbol/symsrv ``` 1. Set a breakpoint by running the [bp command](/windows-hardware/drivers/debugger/bp--bu--bm--set-breakpoint-). this will trigger a symbols request. -1. In the authentication prompt, paste your personal access token that you created earlier. You can leave the username field blank. -WinDbg should then acquire the symbols for your executable. To verify if your symbols are loaded, run the **lm** command to list all loaded modules. +1. During the authentication prompt, insert the *personal access token* you generated earlier. You can leave the *username* field empty. WinDbg will proceed to obtain the symbols for your executable. + +1. To verify if your symbols are loaded, run the **lm** command to list all loaded modules. ## Start debugging -With WinDbg, you can debug both kernel-mode and user-mode components: +WinDbg enhances the scope and versatility of debugging, enabling effective troubleshooting of components in both user-mode and kernel-mode: -- [Getting started with WinDbg (user-mode)](/windows-hardware/drivers/debugger/getting-started-with-windbg). -- [Getting started with WinDbg (kernel-mode)](/windows-hardware/drivers/debugger/getting-started-with-windbg--kernel-mode-). -- [Using the WinDbg Graphical Interface](/windows-hardware/drivers/debugger/windbg-graphical-interface). -- [Using the Debugger Command Window](/windows-hardware/drivers/debugger/the-debugger-command-window). +- [Get started with Windows debugging](/windows-hardware/drivers/debugger/getting-started-with-windows-debugging) +- [Get started with WinDbg (user-mode)](/windows-hardware/drivers/debugger/getting-started-with-windbg) +- [Get started with WinDbg (kernel-mode)](/windows-hardware/drivers/debugger/getting-started-with-windbg--kernel-mode-) +- [Use the WinDbg Graphical Interface (Classic)](/windows-hardware/drivers/debugger/windbg-graphical-interface) +- [Use the Debugger Commands](/windows-hardware/drivers/debugger/using-debugger-commands) ## Related articles -- [Symbols overview](../concepts/symbols.md). -- [Debug with Visual Studio](./debug-with-symbols-visual-studio.md). +- [Debug with Visual Studio](./debug-with-symbols-visual-studio.md) +- [Publish symbols with Azure Pipelines](../../pipelines/artifacts/symbols.md) +- [Artifacts storage consumption](../artifact-storage.md) diff --git a/docs/artifacts/toc.yml b/docs/artifacts/toc.yml index d997845bfb1..9ab85bae359 100644 --- a/docs/artifacts/toc.yml +++ b/docs/artifacts/toc.yml @@ -1,237 +1,347 @@ - name: Azure Artifacts + displayName: index, hub, artifacts href: index.yml - displayName: index, hub, artifacts - name: Get started items: - - name: Azure Artifacts overview + - name: What is Azure Artifacts? + displayName: get started, introduction href: start-using-azure-artifacts.md - displayName: get started, introduction - - name: View Artifacts storage consumption + - name: Publish your first package + displayName: publish, dotnet + href: get-started-artifacts-ai.md + - name: Monitor Artifacts storage + displayName: storage, consumption, usage, billing href: artifact-storage.md - displayName: storage, limit, size, consumption, billing, charges + - name: Key concepts + displayName: concepts, artifacts + href: artifacts-key-concepts.md - name: Best practices - href: concepts/best-practices.md displayName: best practices, concepts + href: concepts/best-practices.md +- name: Artifacts basics + items: + - name: Limits on package sizes and counts + displayName: size, count, package, limit, storage, consumption + href: reference/limits.md + - name: Follow a package for publish alerts + displayName: notification, package, alert, follow + href: how-to/follow-package-notifications.md - name: Search packages - href: ../project/search/functional-package-search.md?toc=/azure/devops/artifacts/toc.json displayName: search, packages -- name: Packages + href: ../project/search/functional-package-search.md?toc=/azure/devops/artifacts/toc.json +- name: Feeds + items: + - name: What are feeds? + displayName: feeds, artifact feeds + href: concepts/feeds.md + - name: Feed scopes + displayName: project scoped, organization scoped, feed, artifacts + href: feeds/project-scoped-feeds.md + - name: Delete and recover packages + displayName: delete, recover, packages, artifacts + href: how-to/delete-and-recover-packages.md + - name: Use public feeds to share your packages publicly + displayName: share packages, share artifacts, artifact feeds, public feeds, feeds + href: tutorials/share-packages-publicly.md + - name: Package badges + displayName: packages, badges, sharing + href: package-badges.md + - name: Migrate from file shares + displayName: migrate, file share + href: nuget/move-from-fileshares.md + - name: Feed views + items: + - name: What are feed views? + displayName: views, artifact feeds, feeds, artifacts + href: concepts/views.md + - name: Promote packages and manage views + displayName: promote, feed, view, package + href: feeds/views.md +- name: Publish items: - - name: About - items: - - name: Package badges - href: package-badges.md - displayName: packages, badges, sharing - - name: Limits on package sizes and counts - href: reference/limits.md - displayName: size, count, package, limit, storage, consumption - - name: Follow a package for publish alerts - href: how-to/follow-package-notifications.md - displayName: notification, package, alert, follow - name: NuGet items: - - name: NuGet quickstart - href: get-started-nuget.md - displayName: nuget, quickstart - name: Project setup (NuGet.exe) + displayName: publish, nuget, package href: nuget/nuget-exe.md - displayName: nuget package, artifacts feeds, publish packages, download packages - - name: Project setup (dotnet) - href: nuget/dotnet-setup.md - displayName: dotnet package, authenticate - name: Publish NuGet packages (NuGet.exe) + displayName: publish, nuget, package href: nuget/publish.md - displayName: publish package, nuget.exe, cli + - name: Project setup (dotnet) + displayName: dotnet package, authenticate + href: nuget/dotnet-setup.md - name: Publish NuGet packages (dotnet) + displayName: dotnet, publish, packages href: nuget/dotnet-exe.md - displayName: dotnet, artifacts, publish packages - - name: Publish to NuGet.org - href: nuget/publish-to-nuget-org.md - displayName: publish package, nuget package, nuget.org - - name: Publish to a NuGet feed (YAML/Classic) - href: ../pipelines/artifacts/nuget.md?toc=/azure/devops/artifacts/toc.json - displayName: nuget feed, nuget package, publish package, classic pipeline, yaml pipeline - - name: Install NuGet packages with Visual Studio - href: nuget/consume.md - displayName: install package, nuget, visual studio - - name: NuGet.org upstream source - href: nuget/upstream-sources.md - displayName: upstream sources, upstreams, artifact feeds - name: Publish from GitHub Actions + displayName: github, actions, publish href: quickstarts/github-actions.md + - name: Publish packages to NuGet.org + displayName: publish, nuget, package, upstream + href: nuget/publish-to-nuget-org.md - name: Migrate from MyGet to Azure Artifacts - href: tutorials/migrate-packages.md displayName: migrate, nuget - - name: npm - items: - - name: npm quickstart - href: get-started-npm.md - displayName: npm, npm introduction - - name: Publish npm packages (YAML/Classic) - href: ../pipelines/artifacts/npm.md?toc=/azure/devops/artifacts/toc.json - displayName: publish npm, npm packages, npm feed - - name: Publish npm packages (CLI) - href: npm/publish.md - displayName: npm package, cli, publish packages - - name: Set up your project's npmrc + href: tutorials/migrate-packages.md + - name: npm + items: + - name: Project setup + displayName: publish, npm href: npm/npmrc.md - displayName: npmrc, project setup, npm feed - - name: Use packages from npmjs.com - href: npm/upstream-sources.md - displayName: npmjs, npm packages, npm feed + - name: Publish npm packages + displayName: npm, publish, cli + href: npm/publish.md - name: Npm scopes + displayName: npm scope, npm artifacts, npm packages href: npm/scopes.md - displayName: npm scope, npm artifacts, npm packages - name: Npm audit + displayName: npm audit, npm artifacts href: npm/npm-audit.md - displayName: npm audit, npm artifacts - name: Maven items: - - name: Maven quickstart - href: get-started-maven.md - displayName: maven, maven introduction - name: Project setup - href: maven/pom-and-settings.md displayName: maven pom, maven artifacts, maven packages, maven authentication - - name: Install Maven artifacts - href: maven/install.md - displayName: maven artifacts, maven packages, maven feeds + href: maven/pom-and-settings.md - name: Publish artifacts with Gradle + displayName: gradle, publish href: maven/publish-with-gradle.md - displayName: gradle, publish - - name: Maven Central Repository + - name: Python + items: + - name: Project setup + displayName: python, pip, twine + href: python/project-setup-python.md + - name: Publish Python packages (CLI) + displayName: python, publish, cli + href: quickstarts/python-cli.md + - name: Universal Packages + items: + - name: Project setup + displayName: universal packages + href: universal-packages/project-setup-universal-packages.md + - name: Universal Packages quickstart + displayName: universal packages, publish, download + href: quickstarts/universal-packages.md + - name: Cargo + items: + - name: Project setup + displayName: cargo, crate + href: cargo/project-setup-cargo.md + - name: Publish Cargo packages + displayName: cargo, crate, publish + href: cargo/cargo-publish.md +- name: Restore + items: + - name: NuGet + items: + - name: Project setup (NuGet.exe) + displayName: nuget package, artifacts feeds, publish packages, download packages + href: nuget/nuget-exe.md + - name: Restore NuGet packages (NuGet.exe) + displayName: nuget, restore + href: nuget/restore-nuget-packages-nuget-exe.md + - name: Project setup (dotnet) + displayName: dotnet package, authenticate + href: nuget/dotnet-setup.md + - name: Restore NuGet packages (dotnet) + displayName: dotnet, restore + href: nuget/restore-nuget-packages-dotnet.md + - name: Install NuGet packages with Visual Studio + displayName: install package, nuget, visual studio + href: nuget/install-nuget-packages-with-visual-studio.md + - name: npm + items: + - name: Project setup + displayName: npmrc, connect, feed, npm + href: npm/npmrc.md + - name: Restore npm packages + displayName: npm, restore, cli + href: npm/restore-npm-packages.md + - name: Npm scopes + displayName: npm scope, npm artifacts, npm packages + href: npm/scopes.md + - name: Npm audit + displayName: npm audit, npm artifacts + href: npm/npm-audit.md + - name: Maven + items: + - name: Project setup + displayName: maven pom, maven artifacts, maven packages, maven authentication + href: maven/pom-and-settings.md + - name: Restore Maven packages + displayName: maven, restore, install + href: maven/install.md + - name: Python + items: + - name: Project setup + displayName: python, pip, twine + href: python/project-setup-python.md + - name: Install Python packages (CLI) + displayName: python, install, cli + href: quickstarts/install-python-packages.md + - name: Universal Packages + items: + - name: Project setup + displayName: universal packages + href: universal-packages/project-setup-universal-packages.md + - name: Download Universal Packages + displayName: universal packages, download + href: quickstarts/download-universal-packages.md + - name: Cargo + items: + - name: Project setup + displayName: cargo, crate + href: cargo/project-setup-cargo.md + - name: Cargo quickstart + displayName: cargo, crate + href: get-started-cargo.md +- name: Upstream sources + items: + - name: What are upstream sources? + displayName: upstream, sources, upstreams + href: concepts/upstream-sources.md + - name: Set up upstream sources + displayName: configure, upstreams + href: how-to/set-up-upstream-sources.md + - name: Use upstream sources with public feeds + displayName: upstream, public feed + href: how-to/public-feeds-upstream-sources.md + - name: Search for packages in upstream sources + displayName: search, upstreams + href: how-to/search-upstream.md + - name: Package graphs + displayName: graph, artifacts, packages + href: concepts/package-graph.md + - name: Safeguard against malicious public packages + displayName: upstreams, behavior, configure upstreams + href: concepts/upstream-behavior.md + - name: NuGet + items: + - name: Use packages from NuGet.org + displayName: upstream, nuget, install, package + href: nuget/upstream-sources.md + - name: npm + items: + - name: Use packages from npmjs.com + displayName: upstream, npmjs, npm, install + href: npm/upstream-sources.md + - name: Maven + items: + - name: Use packages from Maven Central + displayName: maven, maven central, upstream href: maven/upstream-sources.md - displayName: maven packages, maven central, upstream ,upstream sources - - name: Google Maven Repository + - name: Use packages from Google Maven Repository + displayName: maven, google maven, upstream href: maven/google-maven.md - displayName: google maven, maven packages, upstream ,upstream sources - - name: Gradle Plugins + - name: Use packages from Gradle Plugins + displayName: maven, gradle plugins, packages, upstream href: maven/gradle-plugins.md - displayName: gradle plugins, packages, upstream ,upstream sources - - name: JitPack + - name: Use packages from JitPack + displayName: maven, jitpack, upstream href: maven/jitpack-upstream.md - displayName: jitpack, upstream ,upstream sources - name: Python items: - - name: Python quickstart - href: quickstarts/python-packages.md - displayName: python packages, python introduction - - name: Publish to a Python feed - href: ../pipelines/artifacts/pypi.md?bc=%252fazure%252fdevops%252fartifacts%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fartifacts%252ftoc.json - displayName: python packages, python artifacts, python feed - - name: Publish and consume Python packages from the command line - href: quickstarts/python-cli.md - displayName: python overview, python artifacts + - name: Use packages from PyPi + displayName: python, PyPi, upstream + href: python/use-packages-from-pypi.md - name: Universal Packages items: - - name: Quickstart - href: quickstarts/universal-packages.md - displayName: universal packages - name: Universal Packages upstream sources - href: universal-packages/universal-packages-upstream.md displayName: universal packages, upstream sources, upstreams - - name: Universal Packages in Azure Pipelines (YAML/Classic) - href: ../pipelines/artifacts/universal-packages.md?toc=/azure/devops/artifacts/toc.json - displayName: universal packages yaml, universal packages classic -- name: Feeds, views, and upstream sources + href: universal-packages/universal-packages-upstream.md + - name: Cargo + items: + - name: Use packages from Crates.io + displayName: cargo, upstream, crate + href: cargo/cargo-upstream-source.md + - name: PowerShell + items: + - name: Use packages from PowerShell Gallery + displayName: powershell gallery, upstream + href: tutorials/powershell-upstream-source.md +- name: Security items: - - name: Feeds - items: - - name: What are feeds? - href: concepts/feeds.md - displayName: feeds, artifact feeds - - name: Project-scoped vs organization-scoped feeds - href: feeds/project-scoped-feeds.md - displayName: project scoped, feed, artifact feeds - - name: Configure permissions - href: feeds/feed-permissions.md - displayName: feed, artifact feeds, permissions - - name: Delete and recover packages - href: how-to/delete-and-recover-packages.md - displayName: delete, recover, packages, artifacts - - name: Share PowerShell modules with Azure Artifacts feed - href: tutorials/private-powershell-library.md - displayName: powershell artifacts, artifact feeds, powershell module, powershell library - - name: Use public feeds to share your packages publicly - href: tutorials/share-packages-publicly.md - displayName: share packages, share artifacts, artifact feeds, public feeds, feeds - - name: Migrate from file shares - href: nuget/move-from-fileshares.md - displayName: migrate, file share - - name: Feed views + - name: Manage permissions + displayName: feed, artifact, permissions + href: feeds/feed-permissions.md + - name: Safeguard against malicious public packages + displayName: upstreams, behavior, configure upstreams + href: concepts/upstream-behavior.md +- name: Examples + items: + - name: NuGet + href: get-started-nuget.md + - name: npm + href: get-started-npm.md + - name: Maven + href: get-started-maven.md + - name: Python + href: quickstarts/python-packages.md + - name: Universal Packages + href: quickstarts/universal-packages.md + - name: Cargo + href: get-started-cargo.md + - name: PowerShell items: - - name: What are feed views? - href: concepts/views.md - displayName: views, artifact feeds, feeds, artifacts - - name: Promote a package to a view - href: feeds/views.md - displayName: promote, artifact feed, promote packages, feed views - - name: Upstream sources - items: - - name: Upstream sources overview - href: concepts/upstream-sources.md - displayName: upstream, sources, upstreams - - name: Set up upstream sources - href: how-to/set-up-upstream-sources.md - displayName: upstreams, set up upstreams - - name: Manage dependencies with upstream sources - href: tutorials/protect-oss-packages-with-upstream-sources.md - displayName: dependecies, artifacts, upstreams, public package - - name: Search for packages in upstream sources - href: how-to/search-upstream.md - displayName: search packages, upstreams - - name: Configure upstream behavior - href: concepts/upstream-behavior.md - displayName: upstreams, behavior, configure upstreams + - name: Share PowerShell modules with Azure Artifacts + href: tutorials/private-powershell-library.md + - name: Manage dependencies with upstream sources + href: tutorials/protect-oss-packages-with-upstream-sources.md - name: Artifacts in Azure Pipelines items: - name: Artifacts in Azure Pipelines overview + displayName: packages, pipeline artifacts href: ../pipelines/artifacts/artifacts-overview.md - displayName: packages, pipeline artifacts - name: Publish and download artifacts in Azure Pipeline + displayName: publish packages, download packages, pipeline artifact href: ../pipelines/artifacts/pipeline-artifacts.md - displayName: publish packages, download packages, pipeline artifact - - name: Pipeline caching - href: ../pipelines/release/caching.md - displayName: caching, storage, pipeline cach - - name: Set up retention policies - href: ../pipelines/policies/retention.md - displayName: policies, retention, pipeline artifact + - name: Use the .artifactignore file + displayName: artifactignore + href: reference/artifactignore.md + - name: NuGet + items: + - name: Publish packages to internal and external feeds + displayName: nuget, package + href: ../pipelines/artifacts/nuget.md + - name: Restore NuGet packages + displayName: nuget, package, restore + href: ../pipelines/packages/nuget-restore.md + - name: Publish NuGet packages to NuGet.org (Classic/YAML) + displayName: publish, nuget, package + href: ../pipelines/artifacts/publish-public-registry.md + - name: npm + displayName: npm, package + href: ../pipelines/artifacts/npm.md + - name: Maven + displayName: Maven, package + href: ../pipelines/artifacts/publish-maven-artifacts.md + - name: Gradle + displayName: Gradle, package + href: ../pipelines/artifacts/build-publish-artifacts-gradle.md + - name: Python + displayName: python, package + href: ../pipelines/artifacts/pypi.md + - name: Cargo + displayName: cargo, crate + href: ../pipelines/artifacts/cargo-pipelines.md + - name: Universal Packages + displayName: package, universal + href: ../pipelines/artifacts/universal-packages.md - name: Symbols items: - name: Symbols overview + displayName: symbols, debugging href: concepts/symbols.md - displayName: symbols, debugging - name: Debug with Visual Studio + displayName: symbols, visual studio symbols, debug, debugger href: symbols/debug-with-symbols-visual-studio.md - displayName: symbols, visual studio symbols, debug, debugger - name: Debug with WinDbg - href: symbols/debug-with-symbols-windbg.md displayName: symbols, windbg, debugger + href: symbols/debug-with-symbols-windbg.md - name: Publish symbols - href: ../pipelines/artifacts/symbols.md?toc=%252fazure%252fdevops%252fartifacts%252ftoc.json displayName: symbols, debug, debugger, publish -- name: Concepts and references - items: - - name: Key concepts - href: artifacts-key-concepts.md - displayName: concepts, artifacts - - name: Package graphs - href: concepts/package-graph.md - displayName: graph, artifacts, packages - - name: Use the .artifactignore file - href: reference/artifactignore.md - displayName: artifactignore, gitignore - - name: Componentization - href: collaborate-with-packages.md - displayName: componentization, artifacts, packages, concepts -- name: Developer resources - items: - - name: Azure DevOps developer resources - href: ../dev-resources/index.yml - displayName: cli, reference - - name: REST API reference - href: /rest/api/azure/devops/index - displayName: api, reference - - \ No newline at end of file + href: ../pipelines/artifacts/symbols.md?toc=%252fazure%252fdevops%252fartifacts%252ftoc.json +- name: DevOps CLI + displayName: cli, reference + href: /azure/devops/cli/index +- name: REST API reference + displayName: api, reference + href: /rest/api/azure/devops/index diff --git a/docs/artifacts/tutorials/media/add-powershell-gallery-upstream.png b/docs/artifacts/tutorials/media/add-powershell-gallery-upstream.png new file mode 100644 index 00000000000..26149c7a69e Binary files /dev/null and b/docs/artifacts/tutorials/media/add-powershell-gallery-upstream.png differ diff --git a/docs/artifacts/tutorials/media/add-upstream-source.png b/docs/artifacts/tutorials/media/add-upstream-source.png new file mode 100644 index 00000000000..846f42d30eb Binary files /dev/null and b/docs/artifacts/tutorials/media/add-upstream-source.png differ diff --git a/docs/artifacts/tutorials/media/publish-psresource-example-package.png b/docs/artifacts/tutorials/media/publish-psresource-example-package.png new file mode 100644 index 00000000000..793ec275448 Binary files /dev/null and b/docs/artifacts/tutorials/media/publish-psresource-example-package.png differ diff --git a/docs/artifacts/tutorials/media/saved-package-from-upstream-cropped.png b/docs/artifacts/tutorials/media/saved-package-from-upstream-cropped.png new file mode 100644 index 00000000000..4e13c99df2c Binary files /dev/null and b/docs/artifacts/tutorials/media/saved-package-from-upstream-cropped.png differ diff --git a/docs/artifacts/tutorials/media/saved-package-from-upstream.png b/docs/artifacts/tutorials/media/saved-package-from-upstream.png new file mode 100644 index 00000000000..8dd3863ab6e Binary files /dev/null and b/docs/artifacts/tutorials/media/saved-package-from-upstream.png differ diff --git a/docs/artifacts/tutorials/migrate-packages.md b/docs/artifacts/tutorials/migrate-packages.md index dd1df6ff11e..2b7f18c1bd8 100644 --- a/docs/artifacts/tutorials/migrate-packages.md +++ b/docs/artifacts/tutorials/migrate-packages.md @@ -1,6 +1,6 @@ --- -title: Migrate from MyGet to Azure Artifacts -description: How to migrate your packages from MyGet to an Azure Artifacts Feed +title: Migrate NuGet packages from MyGet to Azure Artifacts +description: How to migrate your NuGet packages from MyGet to an Azure Artifacts feed ms.service: azure-devops-artifacts ms.reviewer: elbatk ms.date: 06/22/2023 @@ -8,7 +8,7 @@ monikerRange: 'azure-devops' "recommendations": "true" --- -# Migrate your packages from MyGet to Azure Artifacts +# Migrate your NuGet packages from MyGet to Azure Artifacts [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] @@ -25,7 +25,7 @@ In this article, you'll learn how to: - An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. -- An Azure Artifacts feed. [Create a new feed](../get-started-nuget.md#create-a-feed) if you don't have one already. +- An Azure Artifacts feed. [Create a new feed](../get-started-nuget.md#create-feed) if you don't have one already. - Install [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider). diff --git a/docs/artifacts/tutorials/powershell-upstream-source.md b/docs/artifacts/tutorials/powershell-upstream-source.md new file mode 100644 index 00000000000..42c8d7393da --- /dev/null +++ b/docs/artifacts/tutorials/powershell-upstream-source.md @@ -0,0 +1,97 @@ +--- +title: Use packages from PowerShell Gallery +description: How to use the PowerShell Gallery as an upstream source +ms.service: azure-devops-artifacts +ms.author: rabououn +author: ramiMSFT +ms.date: 10/17/2023 +monikerRange: 'azure-devops' +"recommendations": "true" +--- + +# PowerShell Gallery upstream source + +Enabling upstream sources for your feed extends your developers' access to packages from public registries. In this article, you'll learn how to set up the PowerShell Gallery as an upstream source and consume PowerShell packages from the public registry. + +## Prerequisites + +- [NuGet.exe](https://www.nuget.org/downloads) +- [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider) +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. +- An Azure Artifacts feed. [Create a new feed](../get-started-nuget.md#create-feed) if you don't have one already. + +## Add PowerShell Gallery upstream source + +If the PowerShell Gallery upstream source is not available in your feed by default, you can add it as follows: + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select the gear icon button ![gear icon](../../media/icons/gear-icon.png) to navigate to your **Feed Settings**. + +1. Select **Upstream Sources**, and then select **Add Upstream**. + + :::image type="content" source="media/add-upstream-source.png" alt-text="A screenshot showing how to add a new upstream source."::: + +1. Select **Public source**, and then select **PowerShell Gallery** from the dropdown menu. Select **Add** when you're done. + + :::image type="content" source="media/add-powershell-gallery-upstream.png" alt-text="A screenshot showing how to add the PowerShell Gallery as an upstream source."::: + +1. Select **Save** in the upper right corner to save your changes. Select **Save** again if prompted to confirm your choices. + +## Connect to feed + +1. Create a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** permissions. + +1. Run the following commands in a PowerShell prompt window, replacing the placeholders with the appropriate information: + + ```powershell + $patToken = "" | ConvertTo-SecureString -AsPlainText -Force + ``` + + ```powershell + $myCredentialsObject = New-Object System.Management.Automation.PSCredential("", $patToken) + ``` + +1. Run the following command to register your feed as a PSRepository. Replace the placeholders with the appropriate values: + + - Project-scoped feed: + + ```powershell + Register-PSRepository -Name "PSGalleryUpstream" -SourceLocation "https://pkgs.dev.azure.com///_packaging//nuget/v2" -PublishLocation "https://pkgs.dev.azure.com///_packaging//nuget/v2" -InstallationPolicy Trusted -Credential $myCredentialsObject + ``` + + - Org-scoped feed: + + ```powershell + Register-PSRepository -Name "PSGalleryUpstream" -SourceLocation "https://pkgs.dev.azure.com//_packaging//nuget/v2" -PublishLocation "https://pkgs.dev.azure.com//_packaging//nuget/v2" -InstallationPolicy Trusted -Credential $myCredentialsObject + ``` + +## Save packages from upstream + +Now that you added the PowerShell Gallery as an upstream source and registered your feed as a PSRepository, every time you install a package from upstream, a copy will be saved to your feed. In the following example, we'll install the *PSScriptAnalyzer* module: + +```PowerShell +Install-Module -Name PSScriptAnalyzer -Repository PSGalleryUpstream +``` + +[!INCLUDE [save-requires-collaborator](../includes/save-requires-collaborator.md)] + +## View saved packages + +You can access the packages you've saved from the PowerShell Gallery by choosing the appropriate **Source** from the dropdown menu. + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Source** on the right, and then select **PowerShell Gallery** to filter for packages saved from upstream. You can see that the *PSScriptAnalyzer* package, which we installed in the previous step, has been saved to our feed. + + :::image type="content" source="media/saved-package-from-upstream-cropped.png" alt-text="A screenshot showing packages saved from upstream in an Azure Artifacts feed." lightbox="media/saved-package-from-upstream.png"::: + +## Related articles + +- [NuGet.org upstream source](../nuget/upstream-sources.md) +- [Use upstream sources in a public feed](../how-to/public-feeds-upstream-sources.md) +- [Use feeds as a private PowerShell repository](private-powershell-library.md) \ No newline at end of file diff --git a/docs/artifacts/tutorials/private-powershell-library.md b/docs/artifacts/tutorials/private-powershell-library.md index 2e4c3153b46..ac32be804d5 100644 --- a/docs/artifacts/tutorials/private-powershell-library.md +++ b/docs/artifacts/tutorials/private-powershell-library.md @@ -1,115 +1,307 @@ --- -title: Use Azure Artifacts feeds as a private PowerShell repository -description: How to use Azure Artifacts feeds as a private PowerShell repository +title: Use an Azure Artifacts feed as a private PowerShell repository +description: Learn how to use an Azure Artifacts feed as a private PowerShell repository ms.service: azure-devops-artifacts ms.author: rabououn author: ramiMSFT -ms.date: 08/19/2022 +ms.date: 07/03/2024 monikerRange: 'azure-devops' "recommendations": "true" +zone_pivot_groups: powershell-versions --- # Use an Azure Artifacts feed as a private PowerShell repository [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Azure Artifacts provides an easy way to share PowerShell scripts across teams to promote collaboration and maximize effectiveness. By storing PowerShell modules in a private repository, you can give members of your team the ability to download or update those scripts quickly using the command line. +Azure Artifacts provides a convenient solution for sharing PowerShell scripts. By using Azure Artifacts feeds, you can seamlessly publish your PowerShell modules from the command line and control access to them through your feed settings. +This article guides you through setting up your Azure Artifacts feed as a private PowerShell repository to store and share your PowerShell modules. -This article will guide you through setting up your Azure Artifacts feed as a private PowerShell repository to store and share your PowerShell modules. You'll learn how to: +::: zone pivot="psresourceget" + +In this article, you'll learn how to: >[!div class="checklist"] > * Create a Personal Access Token -> * Create a new feed to store PowerShell modules -> * Create, package, and publish PowerShell modules -> * Connect to a feed with PowerShell -> * Use the private PowerShell repository with Azure Pipelines +> * Create a PowerShell module +> * Create a SecretStore vault and register a repository +> * Publish and consume packages from a feed ## Prerequisites -- [NuGet.exe](https://www.nuget.org/downloads) -- [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider) -- An Azure DevOps organization. [Create an organization](../../organizations/accounts/create-organization.md), if you don't have one already. -- An Azure Artifacts feed. [Create a new feed](../get-started-nuget.md#create-a-feed) if you don't have one already. +- Create an Azure DevOps [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- Create a [new feed](../get-started-nuget.md#create-feed) if you don't have one already. + +- Install [PowerShell](/powershell/scripting/install/installing-powershell) 6.0 or later to ensure you have the required *PowerShellGet* version needed for installing *PSResourceGet*. + +- Install [PSResourceGet](/powershell/gallery/powershellget/install-powershellget). + +- Install the [SecretManagement and SecretStore](/powershell/utility-modules/secretmanagement/get-started/using-secretstore) modules. + +> [!NOTE] +> Azure Artifacts Credential Provider is not supported with PSResourceGet. ## Create a personal access token -Using a personal access token (PAT) is a great way to authenticate with Azure DevOps without using your primary credentials. See [Use personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) for more details. +A personal access token acts as your digital identity and serves as an alternative password to authenticate you with Azure DevOps. 1. Navigate to your Azure DevOps organization `https://dev.azure.com//` -1. Select the user settings icon, and then select **Personal access tokens**. +1. Select the user settings icon, select **Personal access tokens**, and then select **New Token**. + +1. Enter a name for your PAT, set an **Expiration** date, select **Custom defined**, and then select **Packaging** > **Read, write & manage**. + +1. Select **Create** when you're done, and make sure you copy and store your PAT in a safe location. + + :::image type="content" source="../media/config-new-pat.png" alt-text="A screenshot that shows how to set up a new personal access token."::: + +## Create a PowerShell module + +If you don't have your own module, follow the instructions in this section to create a sample PowerShell module. Otherwise, skip to the next step: + +1. Create a new folder *PowerShell-Demo*. Navigate into your folder and create a new file *PowerShell-Demo.psm1*. + +1. Paste the following script into your *PowerShell-Demo.psm1* file: + + ```powershell + Function PowerShell-Demo{ + Write-Host "Hello World!" + } + ``` + +1. Generate the module manifest by running the following command in your *PowerShell-Demo* directory: + + ```powershell + New-ModuleManifest -Path .\PowerShell-Demo.psd1 + ``` + +1. Open your *PowerShell-Demo.psd1* file and locate the `RootModule` variable. This setting specifies the main script file that PowerShell loads when the module is imported. Replace the empty string with the path to your *PowerShell-Demo.psm1* file: + + ```powershell + RootModule = 'PowerShell-Demo.psm1' + ``` + +1. The `FunctionsToExport` section specifies which functions are accessible to users when they import your module. Include your *PowerShell-Demo* function: + + ```powershell + FunctionsToExport = @('PowerShell-Demo') + ``` + +1. Locate the `FileList` section, which lists the files included when packaging the module. Add the file you wish to package with your module: + + ```powershell + FileList = @('./PowerShell-Demo.psm1') + ``` + +## Register a repository + +1. Run the following command to create a credential object. Replace the placeholders with the correct information. + + ```powershell + $username = "" + $patToken = "" | ConvertTo-SecureString -AsPlainText -Force + + $credentials = New-Object System.Management.Automation.PSCredential($username, $patToken) + ``` + +1. Ensure that *SecretManagement* and *SecretStore* are installed, then run the following command to create a vault and add a secret: + + ```powershell + Register-SecretVault -Name "MySecretVault" -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault + + Set-Secret -Name "MyCredential" -Secret $credentials -Vault "MySecretVault" + + $CredentialInfo = [Microsoft.PowerShell.PSResourceGet.UtilClasses.PSCredentialInfo]::new('MySecretVault', 'MyCredential') + ``` + +1. To verify if the vault and secret were successfully created, run the following command to list all your secrets: + + ```powershell + PS > Get-SecretInfo + + Name Type VaultName + ---- ---- --------- + MyCredential PSCredential MySecretVault + + ``` + +1. Run the following command to register your PowerShell repository. You can find the `SourceLocation` link by navigating to **Artifacts** > **Connect to Feed** > **NuGet.exe**, under the **Project setup** section > source URL. + + - Project-scoped feed: + + ```powershell + Register-PSResourceRepository -Name "PowershellPSResourceRepository" ` + -Uri "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" ` + -Trusted ` + -CredentialInfo $CredentialInfo + ``` + + - Organization-scoped feed: + + ```powershell + Register-PSResourceRepository -Name "PowershellPSResourceRepository" ` + -Uri "https://pkgs.dev.azure.com//_packaging//nuget/v3/index.json" ` + -Trusted ` + -CredentialInfo $CredentialInfo + ``` + + > [!TIP] + > Some versions of PowerShell may require starting a new session after running the `Register-PSResourceRepository` cmdlet to prevent encountering the *Unable to resolve package source* warning. + +1. To verify if the repository was successfully registered, run the following command to retrieve all registered repositories for the current user: + + ```powershell + Get-PSResourceRepository + ``` + +> [!NOTE] +> If you encounter the error: *Response status code does not indicate success: 404 (Not Found).*, make sure that your source URL points to `nuget/v3/index.json` instead of `nuget/v2`. - :::image type="content" source="../media/user-settings-pat.png" alt-text="A screenshot showing how to create a personal access token."::: +## Publish a package -1. Select **New Token** +Run the following command to publish the package to your feed. Replace the placeholders with your package path, repository name, the credential object you created earlier, and provide any string for the ApiKey. -1. Enter a name for your PAT and then choose an **Expiration** date. +```powershell +Publish-PSResource -Path -Repository -Credential $credentials -ApiKey +``` -1. Select **Custom defined**, and then select **Packaging** > **Read, write & manage**. +**Example**: -1. Select **Create** when you're done. Copy and store your PAT in a safe location. +```powershell +PS C:\AzureDevOps\Demos\PowerShellDemo> Publish-PSResource -Path .\scripts\ -Repository FabrikamFiberFeed -Credential $credentials -ApiKey az -verbose +VERBOSE: Performing the operation "Publish-PSResource" on target "Publish resource +'C:\AzureDevOps\Demos\PowerShellDemo\scripts\' from the machine". +VERBOSE: The newly created nuspec is: +C:\Users\xxxx\AppData\Local\Temp\xxxxxxxxx\PowerShell-Demo.nuspec +VERBOSE: credential successfully read from vault and set for repository: FabrikamFiberFeed +VERBOSE: Successfully packed the resource into a .nupkg +VERBOSE: Successfully published the resource to +'https://pkgs.dev.azure.com/ramiMSFTDevOps/DemoProject/_packaging/FabrikamFiberFeed/nuget/v3/index.json' +VERBOSE: Deleting temporary directory 'C:\Users\xxxx\AppData\Local\Temp\xxxxxxx' +``` - :::image type="content" source="../media/config-new-pat.png" alt-text="A screenshot showing how to set up a new personal access token."::: +:::image type="content" source="media/publish-psresource-example-package.png" alt-text="A screenshot displaying the PowerShell demo package published to the feed."::: -## Create a module +## Install a package -1. Create a new folder *Get-Hello*. Navigate inside your folder and create a new file *Get-Hello.psm1*. +1. To confirm if the module is available in your repository, use the following command to search for it: + ```powershell + Find-PSResource -Name -Repository -verbose ``` - |--- Get-Hello // Parent folder - |--- Get-Hello.psm1 // This will become our PowerShell Module - |--- Get-Hello.psd1 // This will become our module manifest + +1. Run the following command to install the latest stable version of your module: + + ```powershell + Install-PSResource ``` +> [!TIP] +> If you encounter the error: *Exception calling "WriteObject".*, start a new PowerShell window and run `Get-SecretInfo`. Enter your vault password before running *Find-PSResource* and *Install-PSResource*, as the SecretStore timeout period can expire. The default *PasswordTimeout* is 900 seconds, but you can modify this value as needed. See [Use the SecretStore in automation](/powershell/utility-modules/secretmanagement/how-to/using-secrets-in-automation) for more details. + +:::zone-end + + + +::: zone pivot="powershelget" + +In this article, you'll learn how to: + +>[!div class="checklist"] +> * Create a Personal Access Token +> * Create, package, and publish a PowerShell module +> * Connect to a feed as a PowerShell repository +> * Register and install a PowerShell module using Azure Pipelines + +## Prerequisites + +- Create an Azure DevOps [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- Create a [new feed](../get-started-nuget.md#create-feed) if you don't have one already. + +- Install the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider). + +- Install Windows MSBuild using one of the following options: + - [Microsoft Visual Studio](https://visualstudio.microsoft.com/vs/preview/) + - [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/?q=build+tools#build-tools-for-visual-studio-2022). + - [.NET Core SDK](https://dotnet.microsoft.com/download). + +- Install the [NuGet(.exe)](https://www.nuget.org/downloads) version *4.8.0.5385* or later. + +- Install the [dotnet runtime](https://dotnet.microsoft.com/en-us/download) version *8.0.x* or later. + +- Install [PowerShell](/powershell/scripting/install/installing-powershell) 6.0 or later to ensure you have the appropriate *PowerShellGet* and *PackageManagement* versions. + +## Create a personal access token + +A personal access token acts as your digital identity and serves as an alternative password to authenticate you with Azure DevOps. + +1. Navigate to your Azure DevOps organization `https://dev.azure.com//` + +1. Select the user settings icon, select **Personal access tokens**, and then select **New Token**. + +1. Enter a name for your PAT, set an **Expiration** date, select **Custom defined**, and then select **Packaging** > **Read, write & manage**. + +1. Select **Create** when you're done, and make sure you copy and store your PAT in a safe location. + + :::image type="content" source="../media/config-new-pat.png" alt-text="A screenshot that shows how to set up a new personal access token."::: + +## Create a PowerShell module + +If you don't have your own module, follow the instructions in this section to create a sample PowerShell module. Otherwise, skip to the next step: + +1. Create a new folder *Get-Hello*. Navigate into your folder and create a new file *Get-Hello.psm1*. + 1. Paste the following script into your *Get-Hello.psm1* file: ```powershell Function Get-Hello{ - Write-Host "Hello from my Azure DevOps Services Package." + Write-Host "Hello Azure DevOps!" } ``` -1. Create the module manifest by running the following command in your *Get-Hello* directory path. +1. Generate the module manifest by running the following command in your *Get-Hello* directory: ```powershell New-ModuleManifest -Path .\Get-Hello.psd1 ``` -1. Open your *Get-Hello.psd1* file and find the `RootModule` variable. Replace the empty string with the path to your *Get-Hello.psm1* file as follows: +1. Open your *Get-Hello.psd1* file and locate the `RootModule` variable. This setting specifies the main script file that PowerShell loads when the module is imported. Replace the empty string with the path to your *Get-Hello.psm1* file: ```powershell RootModule = 'Get-Hello.psm1' ``` -1. The `FunctionsToExport` section is meant to define the list of functions that will be exported from this module. Add your *Get-Hello* function as follows: +1. The `FunctionsToExport` section specifies which functions are accessible to users when they import your module. Include your *Get-Hello* function: ```powershell FunctionsToExport = @('Get-Hello') ``` -1. Find the `FileList` section, and add the following list of files that should be packaged with your module. +1. Find the `FileList` section, which specifies the files included when packaging the module. Add the file you wish to package with your module: ```powershell FileList = @('./Get-Hello.psm1') ``` -## Pack and publish module +## Package and publish a module -1. Create *nuspec* file for your module. This command will create a *Get-Hello.nuspec* file that contains metadata needed to pack the module. +1. Generate a *nuspec* file for your module. This command creates a *Get-Hello.nuspec* file containing the necessary metadata for packing the module: ```powershell nuget spec Get-Hello ``` -1. Run the following command to pack your module. +1. Run the following command to package your module: ```powershell nuget pack Get-Hello.nuspec ``` -1. Run the following command to add your feed source URL. NuGet v3 is not supported, make sure you use v2 in your feed source URL. +1. Run the following command to add your feed source URL. Make sure that you use V2 in your feed source URL, as NuGet V3 is not supported. - - Org-scoped feed: + - Organization-scoped feed: ```powershell nuget sources Add -Name "" -Source "https://pkgs.dev.azure.com//_packaging//nuget/v2" -username "" -password "" @@ -121,131 +313,123 @@ Using a personal access token (PAT) is a great way to authenticate with Azure De nuget sources Add -Name "" -Source "https://pkgs.dev.azure.com///_packaging//nuget/v2" -username "" -password "" ``` -1. Publish the package to your feed. +1. Publish the package to your feed: ```powershell nuget push -Source "" -ApiKey "" "" ``` - :::image type="content" source="../../repos/git/media/artifact-package-powershell.png" alt-text="A screenshot showing the published package."::: - > [!IMPORTANT] -> The version number in your Module Manifest (.psd1) and the .nuspec file must match. +> The version number in your *Module Manifest (.psd1)* must be identical to the version number in your *.nuspec* file. -## Connect to feed as a PowerShell repository +## Connect to a feed as a PowerShell repository -1. Open an elevated PowerShell prompt window. +This section guides you through authenticating with a feed as a PowerShell repository and consuming a module hosted in your feed: -1. Set up your credentials to authenticate with Azure Artifacts. Replace the placeholders with the appropriate information. +1. In a PowerShell prompt window, run the following command to set up your credentials. Replace the placeholders with the appropriate information. ```powershell $patToken = "" | ConvertTo-SecureString -AsPlainText -Force - ``` - ```powershell $credsAzureDevopsServices = New-Object System.Management.Automation.PSCredential("", $patToken) ``` -1. Register your PowerShell repository. The `SourceLocation` link can be found by navigating to **Artifacts** > **Connect to Feed** > **NuGet.exe** under **Project setup** source URL. +1. Register your PowerShell repository. You can find the `SourceLocation` link by navigating to **Artifacts** > **Connect to Feed** > **NuGet.exe**, under the **Project setup** section > source URL. - Project-scoped feed: ```powershell - Register-PSRepository -Name "PowershellAzureDevopsServices" -SourceLocation "https://pkgs.dev.azure.com///_packaging//nuget/v2" -PublishLocation "https://pkgs.dev.azure.com///_packaging//nuget/v2" -InstallationPolicy Trusted -Credential $credsAzureDevopsServices + Register-PSRepository -Name -SourceLocation "https://pkgs.dev.azure.com///_packaging//nuget/v2" -PublishLocation "https://pkgs.dev.azure.com///_packaging//nuget/v2" -InstallationPolicy Trusted -Credential $credsAzureDevopsServices ``` - - Org-scoped feed: + - Organization-scoped feed: ```powershell - Register-PSRepository -Name "PowershellAzureDevopsServices" -SourceLocation "https://pkgs.dev.azure.com//_packaging//nuget/v2" -PublishLocation "https://pkgs.dev.azure.com//_packaging//nuget/v2" -InstallationPolicy Trusted -Credential $credsAzureDevopsServices - ``` - - If you're still using the older `visualstudio.com` URLs, use the following command instead: - - - Project-scoped feed: - - ```powershell - Register-PSRepository -Name "PowershellAzureDevopsServices" -SourceLocation "https://.pkgs.visualstudio.com//_packaging//nuget/v2" -PublishLocation "https://.pkgs.visualstudio.com//_packaging//nuget/v2" -InstallationPolicy Trusted -Credential $credsAzureDevopsServices - ``` - - - Org-scoped feed: - - ```powershell - Register-PSRepository -Name "PowershellAzureDevopsServices" -SourceLocation "https://.pkgs.visualstudio.com/_packaging//nuget/v2" -PublishLocation "https://.pkgs.visualstudio.com/_packaging//nuget/v2" -InstallationPolicy Trusted -Credential $credsAzureDevopsServices + Register-PSRepository -Name -SourceLocation "https://pkgs.dev.azure.com//_packaging//nuget/v2" -PublishLocation "https://pkgs.dev.azure.com//_packaging//nuget/v2" -InstallationPolicy Trusted -Credential $credsAzureDevopsServices ``` > [!TIP] - > Certain versions of PowerShell require restarting a new session after executing the `Register-PSRepository` cmdlet to avoid the *Unable to resolve package source* warning. + > Some versions of PowerShell may require starting a new session after running the `Register-PSRepository` cmdlet to prevent encountering the *Unable to resolve package source* warning. 1. Register your package source: - Project-scoped feed: ```powershell - Register-PackageSource -Name "PowershellAzureDevopsServices" -Location "https://pkgs.dev.azure.com///_packaging//nuget/v2" -ProviderName NuGet -Trusted -SkipValidate -Credential $credsAzureDevopsServices + Register-PackageSource -Name -Location "https://pkgs.dev.azure.com///_packaging//nuget/v2" -ProviderName NuGet -Trusted -SkipValidate -Credential $credsAzureDevopsServices ``` - - Org-scoped feed: + - Organization-scoped feed: ```powershell - Register-PackageSource -Name "PowershellAzureDevopsServices" -Location "https://pkgs.dev.azure.com//_packaging//nuget/v2" -ProviderName NuGet -Trusted -SkipValidate -Credential $credsAzureDevopsServices + Register-PackageSource -Name -Location "https://pkgs.dev.azure.com//_packaging//nuget/v2" -ProviderName NuGet -Trusted -SkipValidate -Credential $credsAzureDevopsServices ``` -1. Run the following command to confirm if the repository was registered successfully. This command gets all the registered repositories for the current user: + > [!NOTE] + > - Register-PSRepository: Used for registering a PowerShell repository to find and install modules.
+ > - Register-PackageSource: Used to register a package source for finding and publishing packages. + +1. To verify if the repository was successfully registered, run the following command to retrieve all registered repositories for the current user: ```powershell Get-PSRepository ``` -1. Run the following command if you want to find all modules in the repository. +1. Run the following command to install the *Get-Hello* module. ```powershell - Find-Module -Repository PowershellAzureDevopsServices + Install-Module -Name -Repository ``` -1. Run the following command if you want to install the *Get-Hello* module. +> [!NOTE] +> If your organization uses a firewall or a proxy server, make sure that you allow access to [Azure Artifacts Domain URLs and IP addresses](../../organizations/security/allow-list-ip-url.md#azure-artifacts). - ```powershell - Install-Module -Name Get-Hello -Repository PowershellAzureDevopsServices - ``` +## Install a package from your pipeline -If the *Install-Module* command is returning the following error: *Unable to resolve package source*, run the `Register-PackageSource` cmdlet again with the `Trusted` flag as follows: +This example walks you through authenticating with an Azure Artifacts feed and installing a PowerShell module from your pipeline. To use your personal access token, add it as a pipeline variable, as shown below: -```powershell -Register-PackageSource -Name "PowershellAzureDevopsServices" -Location "https://pkgs.dev.azure.com//_packaging//nuget/v2" -ProviderName NuGet -Trusted -Trusted -SkipValidate -Credential $credsAzureDevopsServices -``` +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, select your pipeline definition, and then select **Edit** to modify your pipeline. -## Connect to feed with Azure Pipelines +1. Select **Variables** at the top right corner, and then select **New variable**. -The following example shows how to authenticate and install a PowerShell Module with YAML pipeline. +1. Enter a **Name** for your variable, and then paste your personal access token into the **Value** textbox. + +1. Make sure that you select the **Keep this value secret** checkbox. Select **Ok** when you're done. + +1. Add a second variable for your *userName*. Enter a **Name** for your variable, then input your userName in the **Value** textbox. + +1. Select **Save** when you're done. ```yaml +trigger: +- main + +pool: + vmImage: 'Windows-latest' + variables: - PackageFeedEndpoint: https://pkgs.dev.azure.com//_packaging//nuget/v2 # For Project-scoped feed use this endpoint url: https://pkgs.dev.azure.com///_packaging//nuget/v2 - - # Construct a JSON object that contains the endpoint URL and the personal access token to pass them to Azure Artifacts credential provider. - PackageFeedEndpointCredential: '{"endpointCredentials": [{"endpoint":"$(PackageFeedEndpoint)", "username":"OPTIONAL", "password":"ACCESS TOKEN"}]}' - + PackageFeedEndpoint: 'https://pkgs.dev.azure.com///_packaging//nuget/v2' ## For organization scoped feeds use'https://pkgs.dev.azure.com//_packaging//nuget/v2' + steps: - # To prevent possible 'Unable to resolve package source' errors when installing modules from your feed, call Install-Module in a separate PowerShell task. - - powershell: | - Register-PSRepository -Name "PowershellAzureDevopsServices" -SourceLocation "$(PackageFeedEndpoint)" -PublishLocation "$(PackageFeedEndpoint)" -InstallationPolicy Trusted - displayName: 'Register Azure Artifacts Feed as PSRepository' - env: - # This environment variable passes the credentials to the credential provider. - VSS_NUGET_EXTERNAL_FEED_ENDPOINTS: $(PackageFeedEndpointCredential) - - - powershell: | - Install-Module -Name Get-Hello -Repository PowershellAzureDevopsServices - displayName: 'Install Get-Hello PowerShell module' - env: - # The credentials must be set on every task that interacts with your private PowerShell repository. - VSS_NUGET_EXTERNAL_FEED_ENDPOINTS: $(PackageFeedEndpointCredential) - - - powershell: | - Get-Hello - displayName: Execute Get-Hello +- powershell: | + $pat = ConvertTo-SecureString ${env:pat_token} -AsPlainText -Force + $credential = New-Object System.Management.Automation.PSCredential("${env:userName}", $pat) + Register-PSRepository -Name -SourceLocation "$(PackageFeedEndpoint)" -InstallationPolicy Trusted -Credential $credential + displayName: 'Register PSRepository' + env: + pat_token: $patToken + userName: $userName + +- powershell: | + nuget install -Source "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" + displayName: 'Install module' ``` +:::zone-end + + + ## Related articles diff --git a/docs/artifacts/tutorials/protect-oss-packages-with-upstream-sources.md b/docs/artifacts/tutorials/protect-oss-packages-with-upstream-sources.md index 6687926bb12..4e33513cfcb 100644 --- a/docs/artifacts/tutorials/protect-oss-packages-with-upstream-sources.md +++ b/docs/artifacts/tutorials/protect-oss-packages-with-upstream-sources.md @@ -25,53 +25,22 @@ In this tutorial, you will: ## Create a feed and enable upstream sources -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -1. Select **Artifacts**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. - :::image type="content" source="../media/goto-feed-hub-azure-devops-newnav.png" alt-text="Screenshot showing how to navigate to Azure Artifacts."::: - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Select **Build & Release**, and then select **Packages**. - - :::image type="content" source="../media/goto-feed-hub.png" alt-text="Screenshot showing how to navigate to Azure Artifacts - TFS."::: - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -2. Select **Create Feed** to create a new feed. +1. Select **Artifacts**, and then select **Create Feed** to create a new feed. :::image type="content" source="../media/new-feed-button-azure-devops-newnav.png" alt-text="Screenshot showing the create feed button."::: -::: moniker-end - -::: moniker range="tfs-2018" - -2. Select **New Feed** to create a new feed. - - :::image type="content" source="../media/new-feed-button.png" alt-text="Screenshot showing the create feed button - TFS."::: - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -3. Provide a name for your feed, and then select its visibility. Make sure your check the **Include packages from common public sources** checkbox to enable upstream sources. Select **Create** when you are done +1. Provide a name for your feed, and choose its visibility. Make sure you check the **Include packages from common public sources** checkbox to enable upstream sources, and then select **Create** when you're done. :::image type="content" source="../media/new-feed-dialog.png" alt-text="Screenshot showing the create a new feed window."::: ::: moniker-end -::: moniker range="tfs-2018" - -3. Provide a name for your feed, and then select its visibility. Make sure your check the **Include packages from common public sources** checkbox to enable upstream sources. Select **Create** when you are done - - :::image type="content" source="../media/new-feed-dialog.png" alt-text="Screenshot showing the create a new feed window - TFS."::: - -::: moniker-end +> [!NOTE] +> To add a feed from a different organization as an upstream source, the target feed owner must share the target view with **All feeds and people in organizations associated with my Microsoft Entra tenant** by navigating to **Feed Settings** > **Views** > Select the ellipsis button on the right for the specified view > **Edit** . ## Set up the configuration file @@ -82,7 +51,7 @@ Now that we created our feed, we need to update the config file to point to our #### [npm](#tab/npm/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Select **Artifacts**, and then select **Connect to feed**. @@ -96,18 +65,6 @@ Now that we created our feed, we need to update the config file to point to our ::: moniker-end -::: moniker range="tfs-2018" - -1. Select **Build & Release** > **Packages**, and then select **Connect to Feed**. - - :::image type="content" source="../media/connect-to-feed.png" alt-text="Screenshot showing how to connect to a feed - TFS"::: - -1. Copy the highlighted snippet to add it to your config file. - - :::image type="content" source="../media/connect-to-feed-npm-registry.png" alt-text="Screenshot highlighting the snippet to be added to the config file - TFS"::: - -::: moniker-end - If you don't have a *.npmrc* file already, create a new one in the root of your project (in the same folder as your *package.json*). Open your new *.npmrc* file and paste the snippet you just copied in the previous step. #### [NuGet](#tab/nuget/) @@ -141,27 +98,6 @@ If you don't have a *.npmrc* file already, create a new one in the root of your index-url=https://pkgs.dev.azure.com/ORGANIZATION-NAME/_packaging/FEED-NAME/pypi/simple/ ``` -#### [Twine](#tab/twine/) - -1. Select **Artifacts**, and then select your feed from the dropdown list. - -1. Select **Connect to feed**, and then select **twine** under the Python section. - - :::image type="content" source="../media/project-setup-twine.png" alt-text="A screenshot showing how to connect to a feed with twine projects."::: - -1. Add a .pypirc file to your home directory and paste the following snippet: - - ```command - [distutils] - Index-servers = FEED-NAME - - [FEED-NAME] - Repository = https://pkgs.dev.azure.com/ORGANIZATION-NAME/_packaging/FEED-NAME/pypi/upload/ - ``` - -> [!TIP] -> If you already have a .pypirc file, remove the [pypi] section if your file contains credentials. - #### [Maven](#tab/maven/) 1. Select **Artifacts**, and then select your feed from the dropdown list. @@ -247,9 +183,11 @@ If you don't have a *.npmrc* file already, create a new one in the root of your ## Restore packages -Now that you enabled upstream sources and set up your configuration file, we can run the package restore command to query the upstream source and retrieve the upstream packages. +Now that you enabled upstream sources and set up your configuration file, you can now run the package restore command to query the upstream source and retrieve the upstream packages. + +To restore packages using Azure Pipelines instead, see [Restore Maven packages with Azure Pipelines (YAML/Classic)](../../pipelines/packages/maven-restore.md) for detailed steps. -We recommend clearing your local cache first before running the *nuget restore*. Azure Artifacts will have a saved copy of any packages you installed from upstream. +::: moniker range="azure-devops" # [npm](#tab/npmrestore) @@ -259,29 +197,156 @@ Remove the *node_modules* folder from your project and run the following command npm install --force ``` +Your feed now should have a saved copy of any packages you installed from upstream. + > [!NOTE] > The `--force` argument will force pull remotes even if a local copy exists. -Your feed now should contain any packages you saved from the upstream source. - # [NuGet](#tab/nugetrestore) -- **Clear your local cache**: +1. Clear your local cache: + + ```Command + nuget locals -clear all + ``` + +1. Restore your NuGet packages: + + ```Command + nuget.exe restore + ``` + +Your feed now should have a saved copy of any packages you installed from upstream. + +# [dotnet](#tab/dotnet) + +Run the following command in your project directory: + +```Command +dotnet restore --interactive +``` + +Your feed now should have a saved copy of any packages you installed from upstream. + +# [Python](#tab/python) + +Run the following command in your project directory: + +```Command +pip install +``` + +Your feed now should have a saved copy of any packages you installed from upstream. + +# [Maven](#tab/mavenrestore) + +Run the following command in your project directory: + +```Command +mvn install +``` + +Your feed now should have a saved copy of any packages you installed from upstream. + +# [Gradle](#tab/gradlerestore) + +Run the following command in your project directory: + +```Command +gradle build +``` + +Your feed now should have a saved copy of any packages you installed from upstream. + +# [Cargo](#tab/cargorestore) + +Run the following command in your project directory: + +```Command +cargo build +``` + +Your feed now should have a saved copy of any packages you installed from upstream. + +- - - + +::: moniker-end + +::: moniker range=">= azure-devops-2020 < azure-devops" + +# [npm](#tab/npmserver) + +Remove the *node_modules* folder from your project and run the following command in an elevated command prompt window: + +```Command +npm install --force +``` + +Your feed now should have a saved copy of any packages you installed from upstream. + +> [!NOTE] +> The `--force` argument will force pull remotes even if a local copy exists. + +# [NuGet](#tab/nugeserver) + +1. Clear your local cache: ```Command nuget locals -clear all ``` -- **Restore packages**: +1. Restore your NuGet packages: ```Command nuget.exe restore ``` -Your feed now should contain any packages you saved from the upstream source. +Your feed now should have a saved copy of any packages you installed from upstream. + +# [dotnet](#tab/dotnetserver) + +Run the following command in your project directory: + +```Command +dotnet restore --interactive +``` + +Your feed now should have a saved copy of any packages you installed from upstream. + +# [Python](#tab/pythonserver) + +Run the following command in your project directory: + +```Command +pip install +``` + +Your feed now should have a saved copy of any packages you installed from upstream. + +# [Maven](#tab/mavenserver) + +Run the following command in your project directory: + +```Command +mvn install +``` + +Your feed now should have a saved copy of any packages you installed from upstream. + +# [Gradle](#tab/gradleserver) + +Run the following command in your project directory: + +```Command +gradle build +``` + +Your feed now should have a saved copy of any packages you installed from upstream. - - - +::: moniker-end + ## Related articles - [Set up upstream sources](../how-to/set-up-upstream-sources.md) diff --git a/docs/artifacts/tutorials/share-packages-publicly.md b/docs/artifacts/tutorials/share-packages-publicly.md index e3d3141a5f1..e7c6b812d34 100644 --- a/docs/artifacts/tutorials/share-packages-publicly.md +++ b/docs/artifacts/tutorials/share-packages-publicly.md @@ -1,9 +1,9 @@ --- title: Share Packages publicly with public feeds -description: Use Azure Artifacts public feeds to share NuGet, npm, Maven, and Python packages publicly +description: Use Azure Artifacts public feeds to share packages publicly. ms.service: azure-devops-artifacts -ms.custom: devx-track-python -ms.date: 11/22/2022 +ms.custom: +ms.date: 07/07/2023 monikerRange: 'azure-devops' --- @@ -20,79 +20,99 @@ Azure Artifacts provides an easy way to share packages to users outside your org ## Create a public feed -Public feeds are project-scoped feeds in a public project. Public feeds inherit the visibility settings of the hosting project. +> [!NOTE] +> Public feeds are only available in Azure DevOps Services. -1. Navigate to your project, and then select **Artifacts**. +Public feeds are project-scoped feeds in a public project. Public feeds inherit the visibility settings of the hosting project. - :::image type="content" source="../media/goto-feed-hub-azure-devops-newnav.png" alt-text="A screenshot showing how to access Artifacts from the Azure DevOps dashboard."::: +1. Sign in to your Azure DevOps organization, and then navigate to your public project. -1. Select **Create Feed**. +1. Select **Artifacts**, and then select **Create Feed**. :::image type="content" source="../media/new-feed-devops.png" alt-text="A screenshot showing how to create a new feed."::: -1. Give your feed a **Name**, and then select **Project: PublicProject (Recommended)** for its scope. +1. Give your feed a **Name**, select **Project: PublicProject (Recommended)** for its scope, and then select **Create** when you're done. :::image type="content" source="../media/new-public-feed.png" alt-text="A screenshot showing how to create a new public feed."::: -1. Select **Create** when you are done. - -## Publish packages - -> [!NOTE] -> If you want to publish NuGet packages, make sure you have the latest [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider). - -### Publish packages (CLI) +## Publish packages (CLI) #### [NuGet](#tab/nuget) -- [NuGet - NuGet.ext](../nuget/publish.md#publish-packages) -- [NuGet - dotnet](../nuget/dotnet-exe.md#publish-packages) +- [Publish NuGet packages - (NuGet.exe)](../nuget/publish.md#publish-packages-to-a-feed-in-the-same-organization) +- [Publish NuGet packages - (dotnet)](../nuget/dotnet-exe.md#publish-packages-to-a-feed-in-the-same-organization) #### [Npm](#tab/npm) -- [Publish Npm packages](../npm/publish.md) +- [Publish npm packages](../npm/publish.md) #### [Maven](#tab/maven) -- [Publish Maven Artifacts](../get-started-maven.md#publish-artifacts) +- [Publish Maven Artifacts](../get-started-maven.md#publish-packages) + +#### [Gradle](#tab/gradle) + +- [Publish Artifacts using Gradle](../maven/publish-with-gradle.md) #### [Python](#tab/python) -- [Publish Python packages](../quickstarts/python-cli.md#publish-python-packages) +- [Publish Python packages](../quickstarts/python-cli.md#publish-packages) + +#### [Cargo](#tab/cargo) + +- [Publish Cargo packages](../get-started-cargo.md) + +#### [Universal Packages](#tab/universalpackages) + +- [Publish Universal Packages](../quickstarts/universal-packages.md#publish-universal-packages) - - - -### Publish packages with Azure Pipelines +## Publish packages with Azure Pipelines #### [NuGet](#tab/nuget) -- [Publish NuGet packages](../../pipelines/artifacts/nuget.md#publish-a-package) +- [Publish NuGet packages](../../pipelines/artifacts/nuget.md#publish-nuget-packages-to-a-feed-in-the-same-organization) #### [Npm](#tab/npm) -- [Publish Npm packages](../../pipelines/artifacts/npm.md#publish-to-azure-artifacts-feeds) +- [Publish npm packages](../../pipelines/artifacts/npm.md#publish-packages-to-a-feed-in-the-same-organization) #### [Maven](#tab/maven) - [Publish Maven Artifacts](../../pipelines/artifacts/publish-maven-artifacts.md) +#### [Gradle](#tab/gradle) + +- [Publish Artifacts with Gradle](../../pipelines/artifacts/build-publish-artifacts-gradle.md) + #### [Python](#tab/python) -- [Publish Python packages](../../pipelines/artifacts/pypi.md#publish-python-packages-to-azure-artifacts-feeds) +- [Publish Python packages](../../pipelines/artifacts/pypi.md#publish-python-packages-to-a-feed) + +#### [Cargo](#tab/cargo) + +- [Publish Cargo packages (YAML/Classic)](../../pipelines/artifacts/cargo-pipelines.md) + +#### [Universal Packages](#tab/universalpackages) + +- [Publish Universal Packages](../../pipelines/artifacts/universal-packages.md#publish-a-universal-package) - - - +> [!NOTE] +> If your organization is using a firewall or a proxy server, make sure you allow [Azure Artifacts Domain URLs and IP addresses](../../organizations/security/allow-list-ip-url.md#azure-artifacts). + ## Share packages To share your packages publicly, you can simply share your feed URL E.g. `https://dev.azure.com///_artifacts/feed/` or share individual packages with [package badges](../package-badges.md). As long as your project is kept public, anyone can view and download packages from your public feed. Anonymous users won't be able to create new feeds or access the recycle bin. -:::image type="content" source="../media/public-feeds-access.png" alt-text="A screenshot showing packages in a public feed."::: +:::image type="content" source="../media/packages-public-feed.png" alt-text="A screenshot showing the content of a public feed."::: ## Related articles -- [Get started with NuGet packages in Azure Artifacts](../get-started-nuget.md) - [Package sizes and count limits](../reference/limits.md) -- [Package notifications](../how-to/follow-package-notifications.md) -- [Package badges](../package-badges.md) +- [Follow a package for publish alerts](../how-to/follow-package-notifications.md) +- [Delete and recover packages](../how-to/delete-and-recover-packages.md) diff --git a/docs/artifacts/universal-packages/media/other-org-feed.png b/docs/artifacts/universal-packages/media/other-org-feed.png index 58d19de133d..65527196ea0 100644 Binary files a/docs/artifacts/universal-packages/media/other-org-feed.png and b/docs/artifacts/universal-packages/media/other-org-feed.png differ diff --git a/docs/artifacts/universal-packages/media/same-org-feed.png b/docs/artifacts/universal-packages/media/same-org-feed.png index 940d466d177..61a513955da 100644 Binary files a/docs/artifacts/universal-packages/media/same-org-feed.png and b/docs/artifacts/universal-packages/media/same-org-feed.png differ diff --git a/docs/artifacts/universal-packages/media/upack-upstream-other-org.png b/docs/artifacts/universal-packages/media/upack-upstream-other-org.png index d0bd2af37b4..ebaf3fa80d1 100644 Binary files a/docs/artifacts/universal-packages/media/upack-upstream-other-org.png and b/docs/artifacts/universal-packages/media/upack-upstream-other-org.png differ diff --git a/docs/artifacts/universal-packages/media/upack-upstream.png b/docs/artifacts/universal-packages/media/upack-upstream.png index 6899964fc8e..4ef36cb41e8 100644 Binary files a/docs/artifacts/universal-packages/media/upack-upstream.png and b/docs/artifacts/universal-packages/media/upack-upstream.png differ diff --git a/docs/artifacts/universal-packages/project-setup-universal-packages.md b/docs/artifacts/universal-packages/project-setup-universal-packages.md new file mode 100644 index 00000000000..2b14ec8e377 --- /dev/null +++ b/docs/artifacts/universal-packages/project-setup-universal-packages.md @@ -0,0 +1,81 @@ +--- +title: Connect to an Azure Artifacts feed - Universal Packages +description: Lean how to set up your project and connect to an Azure Artifacts feed to manage your Universal Packages. +ms.service: azure-devops-artifacts +ms.topic: how-to +ms.date: 01/22/2025 +monikerRange: 'azure-devops' +--- + +# Connect to an Azure Artifacts feed - Universal Packages + +[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] + +Universal Packages allow developers to store various types of packages beyond the traditional ones like NuGet, npm packages by bundling files into a single Universal Package. Using the Azure CLI, they can then publish their Universal Packages directly from the command line to their Azure Artifacts feed. Universal Packages can vary in size reaching up to 4 TiB, but they must always have a name and a version number. +This article guides you through setting up your project and connecting to an Azure Artifacts feed to manage your Universal Packages. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).
- An Azure DevOps [project](../../organizations/projects/create-project.md).
- Download and install [Azure CLI](/cli/azure/install-azure-cli).
- Install the [Azure DevOps extension](#install-azure-devops-extension) version 0.14.0 or higher. | + +## Install Azure DevOps extension + +Ensure that you have Azure CLI installed, then follow the steps below to install the Azure DevOps extension for managing Azure DevOps services from the command line. + +1. Run the following command to install the Azure DevOps extension: + + ```azurecli + az extension add --name azure-devops + ``` + +1. Run the following command if the Azure DevOps extension is already installed and you want to update it to the latest version: + + ```azurecli + az extension update --name azure-devops + ``` + +## Connect to a feed + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed from the dropdown menu. + +1. Select **Connect to feed**, and then select **Universal Packages** from the left navigation pane. + +1. In the **Project setup** section, select **Windows** if you're using a Windows device, otherwise select **Other**. + + ### [Windows](#tab/windows/) + + 1. Run the following command to log into the Azure CLI: + + ```azurecli + az login + ``` + + 1. Run the following command to set your project and organization as the CLI's default configuration: + + ```azurecli + az devops configure --defaults project= organization=https://dev.azure.com/ + ``` + + > [!TIP] + > If you're having troubles logging in with your Microsoft Entra or MSA identity, switch to the **Other** tab and follow the instructions to authenticate with a Personal Access Token. + + ### [Other](#tab/other/) + + 1. Generate a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **Packaging** > **Read & write** scopes, and copy it to your clipboard. + + 1. Run the following command to log in, then when prompted paste the Personal Access Token you created in the previous step, and press *Enter*. + + ```azurecli + az devops login --organization https://dev.azure.com/ + ``` + +- - - + +## Next steps + +> [!div class="nextstepaction"] +> [Publish Universal Packages](../quickstarts/universal-packages.md) \ No newline at end of file diff --git a/docs/artifacts/universal-packages/universal-packages-upstream.md b/docs/artifacts/universal-packages/universal-packages-upstream.md index 2559d398cc7..4b73cf7b5c1 100644 --- a/docs/artifacts/universal-packages/universal-packages-upstream.md +++ b/docs/artifacts/universal-packages/universal-packages-upstream.md @@ -4,13 +4,15 @@ description: How to add Universal Packages upstream sources ms.service: azure-devops-artifacts ms.topic: conceptual ms.date: 05/12/2022 -monikerRange: '<= azure-devops' +monikerRange: 'azure-devops' "recommendations": "true" --- # Universal Packages upstream sources -With Azure Artifacts, you can enable upstream sources to start consuming packages from public registries such as NuGet.org or npmjs.com. Once you enable upstream sources, Azure Artifacts will save a copy of any packages you install from upstream. Azure Artifacts also supports using other feeds as upstreams. In this article, you'll learn how to add a new Universal Packages upstream source with a feed in your organization or other organizations within the same Azure Active Directory. See [Manage access with Azure Active Directory](../../organizations/accounts/connect-organization-to-azure-ad.md) to learn how to connect your organization to Azure Active Directory. +[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] + +With Azure Artifacts, you can enable upstream sources to start consuming packages from public registries such as NuGet.org or npmjs.com. Once you enable upstream sources, Azure Artifacts will save a copy of any packages you install from upstream. Azure Artifacts also supports using other feeds as upstream sources. In this article, you'll learn how to add a new Universal Packages upstream source with a feed in your organization or other organizations within the same Microsoft Entra ID. See [Manage access with Microsoft Entra ID](../../organizations/accounts/connect-organization-to-azure-ad.md) to learn how to connect your organization to Microsoft Entra ID. ## Add a feed in your organization as an upstream source @@ -26,11 +28,9 @@ With Azure Artifacts, you can enable upstream sources to start consuming package 1. Select your **Feed** from the dropdown menu, select a **View** and give your upstream source a name. Make sure you check the **UPack** package type. - :::image type="content" source="./media/upack-upstream.png" alt-text="A screenshot showing how to set up a new Universal Packages upstream source."::: - -1. Select **Save** when you're done. +1. Select **Add** when you're done, and then select **Save** one more time from the top right corner to save your changes. -1. Select **Save** at the top right corner to save your changes. + :::image type="content" source="./media/upack-upstream.png" alt-text="A screenshot showing how to set up a new Universal Packages upstream source."::: ## Add a feed in another organization as an upstream source @@ -40,17 +40,15 @@ With Azure Artifacts, you can enable upstream sources to start consuming package :::image type="content" source="./media/upack-add-upstream.png" alt-text="A screenshot showing how to add an upstream source."::: -1. Select **Azure Artifacts feed in another organization** to use packages from a feed in a different organization within the same Azure Active Directory. +1. Select **Azure Artifacts feed in another organization** to use packages from a feed in a different organization within the same Microsoft Entra ID. :::image type="content" source="./media/other-org-feed.png" alt-text="A screenshot showing the types of upstream sources - feed in another org."::: 1. Enter your **Azure Artifacts feed locator**, and give your upstream source a name. Make sure you check the **UPack** package type. - :::image type="content" source="./media/upack-upstream-other-org.png" alt-text="A screenshot showing how to set up a new Universal Packages upstream source with a feed in another organization."::: - -1. Select **Save** when you're done. +1. Select **Add** when you're done, and then select **Save** one more time from the top right corner to save your changes. -1. Select **Save** at the top right corner to save your changes. + :::image type="content" source="./media/upack-upstream-other-org.png" alt-text="A screenshot showing how to set up a new Universal Packages upstream source with a feed in another organization."::: ## View saved packages from upstream @@ -63,4 +61,4 @@ To view the packages saved from your Universal Packages upstream source, select - [DevBlogs - Universal Packages upstream sources](https://devblogs.microsoft.com/devops/azure-artifacts-introduces-new-upstreaming-capabilities/) - [Configure upstream sources](../how-to/set-up-upstream-sources.md) - [Publish packages to NuGet.org](../nuget/publish-to-nuget-org.md) -- [Configure upstream behavior](../concepts/upstream-behavior.md) \ No newline at end of file +- [Configure upstream behavior](../concepts/upstream-behavior.md) diff --git a/docs/boards/backlogs/add-link.md b/docs/boards/backlogs/add-link.md index 89e93ea533d..9366a7d31d0 100644 --- a/docs/boards/backlogs/add-link.md +++ b/docs/boards/backlogs/add-link.md @@ -1,332 +1,410 @@ --- -title: Link user stories and issues to other work items in Azure Boards +title: Link work items to other objects titleSuffix: Azure Boards -description: Learn how to link one or more work items to other work items or to a new git branch in Azure Boards. -ms.custom: cross-project, devx-track-azurecli +description: Learn how to link work items to user stories, bugs, remote work items, a git branch, and other elements in Azure Boards. +ms.custom: cross-project, devx-track-azurecli, engagement-fy24 ms.service: azure-devops-boards ms.assetid: 7130A14B-C760-4622-B97A-8DA27A1B3D02 +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 11/08/2022 +ms.date: 01/07/2025 +#customer intent: As a team member, I want to understand how links between work items and other elements operate and help project planning and development. --- -# Link user stories, issues, bugs, and other work items in Azure Boards +# Link work items to objects [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="azure-devops" +Work item links are associations between two work items or a work item and another object. Links describe the relationship between objects. You can use work item links to track dependencies and related work for traceability, share information, manage complex projects that involve multiple teams or products, track code changes, tests, and more. + +## Prerequisites -Link work items to other work items to manage dependencies and see relationships within work. You can link work items within your project or to work items within another project in your organization. Use different link types to support different business goals. You can also link work items to other objects such as builds, commits, versioned items, or network resources. +::: moniker range=" azure-devops" + +| Category | Requirements | +|:-------------|:------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Permissions** | - Member of the **Contributors** or **Project Administrators** security group.
- To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set to **Allow**. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md).
- To configure the integration options for a Classic release pipeline: **Edit** permissions for the release.
- To link work items to commits and pull requests: **Edit work items in this node** permissions set to **Allow** for the Area Path assigned to the work item. By default, the Contributors group has this permission.
- To view work items: **View work items in this node** permissions set to **Allow** for the Area Path assigned to the work item. | +|**Access levels** | To add or modify work items: At least [**Stakeholder** access](../../organizations/security/stakeholder-access.md). Users with **Stakeholder** access for public projects have full access to backlog and board features, like users with [**Basic** access](../../organizations/security/access-levels.md). For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). | +| **Defined iterations** | To use the **Planning** pane, your team administrator [defined iteration (sprint) paths and configured team iterations](../../organizations/settings/set-iteration-paths-sprints.md). | ::: moniker-end -::: moniker range="< azure-devops" +::: moniker range=">= azure-devops-2020 < azure-devops" -Link work items to other work items to manage dependencies and see relationships within work. You can link work items within your project or to work items within another project in your collection. Use different link types to support different business goals. You can also link work items to other objects such as builds, commits, versioned items, or network resources. +| Category | Requirements | +|:-------------|:------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Permissions** | - Member of the **Contributors** or **Project Administrators** security group.
- To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set to **Allow**. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md).
- To configure the integration options for a Classic release pipeline: **Edit** permissions for the release.
- To link work items to commits and pull requests: **Edit work items in this node** permissions set to **Allow** for the Area Path assigned to the work item. By default, the Contributors group has this permission.
- To view work items: **View work items in this node** permissions set to **Allow** for the Area Path assigned to the work item. | +|**Access levels** | To add or modify work items: At least [**Stakeholder** access](../../organizations/security/stakeholder-access.md). Users with **Stakeholder** access for public projects have full access to backlog and board features, like users with [**Basic** access](../../organizations/security/access-levels.md). For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). | +| **Defined iterations** | To use the **Planning** pane, your team administrator [defined iteration (sprint) paths and configured team iterations](../../organizations/settings/set-iteration-paths-sprints.md). | ::: moniker-end -In general, you use the following link types when linking work items to one another: +## Types of links -- Use **Parent/Child** links to link work items that you want to group within a hierarchy -- Use **Predecessor/Successor** or **Affects/Affected by** links to link work items that have dependencies -- Use **Duplicate/Duplicate of** links to link work items that track the same code defect or work -- Use **Related** to link work items with some level of relationship, but not that strong +The following types of links help you manage the various relationships between work items and other objects. -You can add a link to a work item from within the work item form or from a backlog or query results list. From a backlog or query results list, you can select multiple work items and then link them to a new or existing work item. In general, use the bulk edit to update several work items to link to the same work item, either new or existing. +| Link type category | Description | +|:----------|:------------| +| **Build** | Connects a work item to a build number, found in build, or integrated in build. | +| **Code** | Connects a work item to a branch, changeset, commit, pull request, tag, or versioned item. | +| **GitHub** | Connects a work item to a GitHub repository branch, commit, issue, or pull request. | +| **Remote work** | Connects a work item defined in a different organization that either consumes from, produces for, or is remotely related via URL. | +| **Requirement** | Connects a work item to a storyboard via URL. | +| **Test** | Connects a work item to a test attachment or result. | +| **Wiki** | Connects a work item to a wiki page. | +| **Work** | Connects a work item to various aspects of your work, including:
- Affected by
- Affects
- Child
- Duplicate
- Duplicate of
- Hyperlink
- Integrated in release stage
- Parent
- Predecessor
- Referenced by
- References
- Related
- Shared steps
- Successor
- Test case
- Tested by
- Tests | -Use this article to learn how to: +For more information about work link types, including parent/child, related, and predecessor-successor, see [Work link types](../queries/link-type-reference.md#work-link-type). -::: moniker range="azure-devops" ->[!div class="checklist"] -> * Link one or more work items to an existing work item -> * Link one or more work items to a new work item that you add when linking -> * Add a link to a remote work item -> * Link several work items to a new git branch -> * Link work items to a build artifact -> * Find work items that you want to link to -> * Bulk modify link relationships -::: moniker-end +## Link work items to various objects +To link work items to various objects, follow these general steps: -::: moniker range="< azure-devops" ->[!div class="checklist"] -> * Link one or more work items to an existing work item -> * Link one or more work items to a new work item that you add when linking -> * Link several work items to a new git branch -> * Link work items to a build artifact -> * Find work items that you want to link to -> * Bulk modify link relationships -::: moniker-end +1. Sign in to your organization (`https://dev.azure.com/{Your_Organization}`). +2. Open the existing work item that you want to link from, or create a new one. +3. Select **Links** > **Add link**, and then select **Existing item** or **New item**. -> [!NOTE] -> If you want to link work items in a parent-child hierarchy, use the mapping pane as described in [Organize your backlog and map child work items to parents](organize-backlog.md). If you want to link test cases to user stories, see [Add, run, and update inline tests](../boards/add-run-update-tests.md) and [Create test plans and test suites](../../test/create-a-test-plan.md). + :::image type="content" source="media/add-link/add-link-new-item.png" alt-text="Screenshot sequence to add new or existing item link to work item."::: -For an overview of how links are used to support traceability, see [End-to-end traceability](../../cross-service/end-to-end-traceability.md). +4. In the **Link type** dropdown list, select the [link type](#types-of-links) that you want to create. +5. In the field that follows, enter or select the object that you want to link to. +6. (Optional) Enter a comment to describe the link. +7. Select **Add link** to create the link. -## Link guidance +For more specific instructions on linking different types of work items, refer to the sections that follow. -For an overview of which link types to use and link-related capabilities, see [Linking, traceability, and managing dependencies](../queries/link-work-items-support-traceability.md). In general, we recommend you follow these guidelines: +> [!TIP] +> You can use other features to link or change links that use the **Parent/Child** link type. Some features are version-dependent. For more information, see the following articles: +> +> - To link backlog items to portfolio backlog items or change the link structure, [use the mapping pane to organize your backlog](../backlogs/organize-backlog.md). You can also choose to **Show Parents** and [drag-and-drop items within the tree hierarchy](organize-backlog.md). +> - To create and link tasks to backlog items, [use the sprint backlog page](../sprints/assign-work-sprint.md). You can also drag-and-drop items to change the link structure from the web portal. +> - To indent, outdent, and change the link structure of a tree hierarchy, [reparent and reorder items from a backlog in the web portal](../backlogs/organize-backlog.md) or use a [tree query in Team Explorer](../queries/using-queries.md). +> - To add or delete work items or change the link structure, use Excel. See [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). -- For work items that appear on your backlogs, both product and portfolio, use the **Parent** and **Child** link types to create a hierarchy and group work. To quickly link many backlog work items within a hierarchy, see [Organize your backlog, map child work items to parents](organize-backlog.md). -- When linking work items with **Parent** and **Child** link types, avoid nesting work items of the same type. While the system allows you to nest work items of the same type--such as, linking bugs to bugs or bugs to user stories when tracking both types on your product backlog--it can cause problems. For example, drag-and-drop of work items on a backlog or display of items on a Kanban board may not work. For more information, see [Fix display, reordering, and nesting issues](resolve-backlog-reorder-issues.md). -- To track dependencies of work items, use the **Predecessor** and **Successor** link types. -- For all other general tracking purposes, use the **Related** link type. +## Link a work item to another work item -The following link relationships are restricted: -- You can't assign a work item more than one parent using a **Parent/Child** or other tree-topology link type. To learn more about link types, see [Link type reference](../queries/link-type-reference.md). -- You can't add links in such a way as to create a circular relationship. -- You can't link more than 1,000 work items to a single work item. +To add a link to another work item in the web portal, do the following steps: -[!INCLUDE [temp](../includes/prerequisites.md)] +1. Open the work item that you want to link from. +2. In the work item form, you can choose from two ways to do this task: + - Go to the **Related Work** section and select **Add link** > **Existing item**. + - Select **Links** > **Add link** > **Existing item**. - + :::image type="content" source="media/add-link/work-item-add-link-sequence.png" alt-text="Screenshot shows highlighted buttons sequence to add a link to an existing work item from the Links tab."::: -## Link several work items +3. In the **Link type** dropdown list, select the [link type](#types-of-links) that you want to create, for example, **Child**, **Parent**, or **Related**. +4. In the **Work items to link** field, enter the ID of the work item you want to link to, or select from the dropdown menu, and then select **Add link**. -1. From the web portal, open a [backlog](create-your-backlog.md) or [query results page](../queries/view-run-query.md), and [multi-select the work items](bulk-modify-work-items.md#multi-select) you want to add a link to. + The following example uses the **Related** link type to a test case with ID of *280*. -2. Open the **…** context menu of one of the selected work items, choose **Add link**, and then choose **Existing item...** or **New item...**. + ::: moniker range=" azure-devops" + :::image type="content" source="media/add-link/add-link-dialog.png" alt-text="Screenshot of Add link dialog, web portal, to an existing work item."::: - Here we multi-select from the product backlog and choose **Existing item...**. + You can only add links one at a time. You can't enter their IDs separated by commas or spaces. + ::: moniker-end - > [!div class="mx-imgBorder"] - > ![Screenshot of backlog context menu, Multi-select items in backlog, open context menu, choose Add link to an existing work item.](media/add-link/multi-select-add-link-vsts.png) + ::: moniker range="< azure-devops" + To link to multiple work items, enter their IDs separated by commas or spaces. If you don't know the IDs or \to link to an item in a different project, select :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More actions**. + ::: moniker-end +## Link several work items - +1. From the web portal, open a [backlog](create-your-backlog.md) or [query results page](../queries/view-run-query.md). +2. [Multi-select (highlight) the work items](bulk-modify-work-items.md#multi-select) to add a link to. +3. Select :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More actions** for the selected work items, select **Add link**, and then choose **Link to an existing item...** or **Link to a new work item...**. -## Link to an existing work item + In the following example, we multi-select from the product backlog and choose **Link to an existing item...**. -When you link work items, you select a link type. In general, use the following link types as indicated. To learn more about each link type, see [Link type reference](../queries/link-type-reference.md). + :::image type="content" source="media/add-link/multi-select-add-link.png" alt-text="Screenshot of backlog context menu, Multi-select items in backlog, open context menu, choose Add link to an existing work item."::: -- Use the **Duplicate** link type when two work items have been created that essentially capture the same information; close one of the work items and keep the other one active -- Use the **Parent/Child** link types when you want to break down work items into smaller items--for example, break down features into stories, or stories into tasks -- Use **Predecessor-Successor** link types when you want to track tasks that must be completed before others can be started; this link type is most often used when you plan work using Project -- Use the **Related** link type when the work items being linked are at the same level--such as two user stories that define features that overlap one another--or to link work items that are defined in different projects or managed by different teams. +4. Select from the **Link type** dropdown menu, for example, **Parent**, **Child**, or **Related**. +5. In the **Work item** field, enter the ID of the work item you want to link to, then select **Add link**. +::: moniker range=" azure-devops" -#### [Browser](#tab/browser/) +## Change the link type of an existing link -From the **Add link** dialog, select the link type, enter a work item ID, and then choose OK. +1. From the web portal, open your work item and select **Links**. +1. Select :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More actions** > **Edit link**. -For example, here we use the **Related** link type to link three items to the bug with ID of *400*. + :::image type="content" source="media/add-link/change-link-type.png" alt-text="Screenshot of Links tab, open More actions, choose Edit link option."::: -::: moniker range="azure-devops" -> [!div class="mx-imgBorder"] -> ![Add link dialog, web portal, to an existing work item.](media/add-link/add-link-dialog-s136.png) +1. Choose the link type to change to, and then select **Save**. -To link to multiple work items, you can use inline add which finds work items based on your recent activity or keyword searches. Select one or more of the work items displayed automatically based on your recent activity, or enter a keyword. Keyword searches display work items based on work items that include that keyword in their title. + :::image type="content" source="media/add-link/edit-link-dialog.png" alt-text="Screenshot of Edit link dialog."::: -> [!NOTE] -> You need to add each link one at a time. (You can no longer enter their IDs separated by commas or spaces.) To quickly find work items of interest, you can also use [work item search](../../project/search/functional-work-item-search.md). +::: moniker-end -::: moniker-end +## Link work items to new work items -To view the work items selected for linking, you can choose the :::image type="icon" source="../media/icons/info.png" border="false":::. -> [!div class="mx-imgBorder"] -> ![Add link dialog to an existing work item](media/add-link/info-linked-items.png) +Do the following steps to link a work item to a new work item. -::: moniker range="tfs-2018" -> [!div class="mx-imgBorder"] -> ![Screenshot of backlog context menu, choose Add link to an existing work item, TFS-2018 and previous versions.](media/add-link/link-multi-to-existing.png) +1. From your work item, select **Links** > **Add link** > **New item**. + + :::image type="content" source="media/add-link/add-link-new-item.png" alt-text="Screenshot sequence to add new or existing item link to work item."::: -To link to multiple work items, enter their IDs separated by commas or spaces. If you don't know the IDs or you want to link to an item in a different project, you can choose :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More actions** to open a dialogue that can support you in [choosing work items that are based on IDs, a query, or title keyword](#find-items). -::: moniker-end - +2. Specify the **Link type** and **Work Item Type**, and enter a title for the new work item and optional comment. Select **Add link**. -If you're working from the Query Results page, you'll need to bulk save the work items you've modified. When you work from a backlog, work items are automatically saved. + :::image type="content" source="media/add-link-related-new-item-issue.png" alt-text="Screenshot of Add link dialog, Link to new work item."::: -::: moniker range=">= azure-devops-2019" -> [!div class="mx-imgBorder"] -> ![Screenshot of Query results page, save bulk modified items.](media/bulk-modify/query-results-bulk-save-items.png) -::: moniker-end + The new work item opens. -::: moniker range="tfs-2018" -![Screenshot of Query results page, multi-select items, bulk save modified work items, TFS-2018 and earlier versions.](media/bulk-modify-link-existing-bulk-save-ts.png) -::: moniker-end +3. Enter additional information and **Save** the work item. + :::image type="content" source="media/add-link/new-issue-linked-item.png" alt-text="Screenshot of new work item Issue added."::: -### [Visual Studio](#tab/visual-studio/) +::: moniker range=" azure-devops" -From the Add link to Multiple Items dialog, select the link type, enter a work item ID, and then choose **OK**. + -For example, here we use the **Related** link type to link several items to the user story with ID of *4654*. +## Link work items to remote work items (cross-organization) -![Screenshot of Visual Studio, Add link dialog.](media/add-link-related-existing-item-vs.png) +Do the following steps to link work items to objects defined in other Azure DevOps organizations. You can only do so if both organizations use the same Microsoft Entra ID to manage users. -To link to multiple work items, enter their IDs separated by commas or spaces. If you don't know the IDs or you want to link to an item in a different project, you can select the Browse button to open a dialogue that supports you in [choosing work items based on IDs, a query, or title keyword](#find-items). +1. From your work item, select **Links** > **Add link** > **Existing item**. + + :::image type="content" source="media/add-link/work-item-add-link-sequence.png" alt-text="Screenshot shows sequence to add link to a newly created a work item."::: -You'll need to bulk save the work items you've modified. +2. Choose one of the following remote link types from the **Link type** dropdown menu: -* * * + - **Consumes From** or **Produces For**: When you want to track dependencies of work items that are defined in different organizations and managed by different teams. + - **Remote Related**: When the work items being linked are defined in different organizations and managed by different teams, but don't have strong inter-dependencies. - +3. Enter the URL of the remote work item, and then select **Add link**. -::: moniker range="azure-devops" + The following example uses the **Remote Related** link type to link to work item ID *350* that exists in the *remotelinkingtest2* organization, *RemoteLinking* project. + :::image type="content" source="media/add-link/add-remote-related-link.png" alt-text="Screenshot of removing a work item link."::: -## Change the link type of an existing link + The link tab maintains a count of all links to the work item. The **Remote Link Count** [field](../queries/linking-attachments.md) maintains a count of the number of links added to a work item that link to a work item defined in another project or organization. + + The following example shows two remote links, indicated by the :::image type="icon" source="../../media/icons/cloud-link.png" border="false"::: cloud icon, added to a user story. + + :::image type="content" source="media/add-link/links-tab-remote-links.png" alt-text="Screenshot of User Story form, Link tab, showing two external links."::: +::: moniker-end -> [!NOTE] -> The **Edit link** feature requires you to enable the **New Boards Hub** preview feature. To enable this feature, see [Manage or enable features](../../project/navigation/preview-features.md). - -1. Open the work item whose link you want to edit, and choose the **Links** tab. +::: moniker range=">= azure-devops-2020" -1. Choose :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More actions** for the link you want to change, and then choose the **Edit link** option. +## Link work items to pull requests - :::image type="content" source="media/add-link/change-link-type.png" alt-text="Screenshot of Links tab, open More actions, choose Edit link option."::: +1. In the description of your pull request, enter `#` to trigger the `#ID` work item picker. A list displays 50 work items that you recently modified or are assigned to you. -1. Choose the link type to change to, and then choose **Save**. + :::image type="content" source="media/add-link/link-pr-to-work-item.png" alt-text="Screenshot of work item list produced when entering the symbol # in PR description."::: - :::image type="content" source="media/add-link/edit-link-dialog.png" alt-text="Screenshot of Edit link dialog. "::: +1. To narrow the list of suggested work items, enter up to five keywords that match the work item type, ID, or title. -1. Save the work item to complete the action. + :::image type="content" source="media/add-link/keyword-pr-link.png" alt-text="Screenshot of entering keyword after the symbol # and resulting work item in search."::: ::: moniker-end +For more information, see [Link to work items from pull requests, commits, and comments](../../organizations/notifications/add-links-to-work-items.md#link-wit-id). + + -## Link to a new work item +## Link work items to GitHub objects -Here, we've selected to add a link to the selected work items. +::: moniker range=">= azure-devops-2020" +When you connect Azure Boards with GitHub repositories, you can link work items to a **GitHub Branch**, **GitHub Commit**, **GitHub Issue**, and **GitHub Pull Request**. You can use GitHub for software development while you use Azure Boards to plan and track your work. +::: moniker-end -1. Specify the link type, work item type, and title of the new work item. Choose **OK**. +> [!IMPORTANT] +> You can only link work items to GitHub objects that have repositories connected to Azure Boards. For more information, see [Connect Azure Boards to GitHub](../github/connect-to-github.md), and [Link to work items from pull requests, commits, and comments](../../organizations/notifications/add-links-to-work-items.md#link-wit-id). - ![Add link dialog, Link to a new work item, TFS-2018 and later versions.](media/add-link-related-new-item-issue.png) +For more information, see [Link GitHub commits, pull requests, branches, and issues to work items](../github/link-to-from-github.md) and [Auto complete work items with pull requests](../work-items/auto-complete-work-items-pull-requests.md). +## Link several work items to new git branches -2. A work item of the type selected opens. Enter additional information and save the work item. +1. From a backlog or query results page, [multi-select the work items](bulk-modify-work-items.md#multi-select) that you want to link to a new git branch. +2. Select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon, and then **New branch...**. For more information, see [Link work items to Git development objects](connect-work-items-to-git-dev-ops.md). - > [!div class="mx-imgBorder"] - > ![Screenshot of new work item Issue added.](media/add-link/new-issue-linked-item.png) + :::image type="content" source="media/add-link/link-git-branch.png" alt-text="Screenshot of backlog, context menu, choose Link multiple backlog items to a git branch."::: -3. If you're working from the Query Results page, you'll need to bulk save the work items you've modified as shown in the previous procedure. +## Link work items to builds +Do the following steps to link work items to existing builds. These builds can be in your project or to other projects in your organization or collection. -::: moniker range="azure-devops" +::: moniker range="azure-devops-2020" +> [!NOTE] +> This feature requires installation of Azure DevOps Server 2020.1 update. For more information, see [Azure DevOps Server 2020 Update 1 RC1 Release Notes, Boards](/azure/devops/server/release-notes/azuredevops2020u1#customize-work-item-state-when-pull-request-is-merged). +::: moniker-end - +::: moniker range=">= azure-devops-2020" -## Link to a remote work item +1. From your work item, select **Links** > **Add link** > **Existing item**. -You can link work items to objects defined in other Azure DevOps organizations as long as both organizations use the same Azure Active Directory to manage users. +2. From the **Add link** dialog, choose one of the build link types: **Build**, **Found in build**, **Integrated in build**. Specify the build number. -Choose from one of the following two remote link types supported. + The build number is a combination of the pipeline and build name. If you don't know the build number, select **Find builds**. -- Use the **Consumes From/Produces For** link types when you want to track dependencies of work items that are defined in different organizations and managed by different teams. -- Use the **Remote Related** link type when the work items being linked are defined in different organizations and managed by different teams, but don't have strong inter-dependencies. + :::image type="content" source="media/add-link/add-link-find-builds.png" alt-text="Screenshot shows highlighted button, Find builds."::: -From the Add link dialog, select the link type, enter the URL of the remote work item, and then choose OK. +3. Choose the parameters to filter your search of builds. -For example, here we use the **Remote Related** link type to link to work item ID *350* that exists in the *remotelinkingtest2* organization, *RemoteLinking* project. + To link to a build in a different project, first choose the **Project** whose build you want to link to. -> [!div class="mx-imgBorder"] -> ![Add link dialog, Add a link to an existing, remote work item.](media/add-link/add-remote-related-link.png) + For example, you can specify a build number, select a build pipeline, or a build result, such as, **All**, **succeeded**, **partially succeeded**, **failed**, or **canceled**. Or, with **Succeeded** selected for **Result**, select **Find builds** to list the available builds you can link to. -The link tab maintains a count of all links to the work item. The [*Remote Link Count* field](../queries/linking-attachments.md) maintains a count of the number of links added to a work item that link to a work item defined in another project or organization. + :::image type="content" source="media/add-link/find-builds-dialog-filled-out.png" alt-text="Screenshot of Find builds dialog with project selected and builds listed."::: -The following image shows an example of two remote links, indicated by the :::image type="icon" source="../../media/icons/cloud-link.png" border="false"::: cloud icon, added to a user story. +4. Choose the build from the list you want to link to and then select **Confirm**. +5. Select **Add link** to complete the operation. -> [!div class="mx-imgBorder"] -> ![Screenshot of User Story form, Link tab, showing two external links.](media/add-link/link-tab-remote-links.png) + :::image type="content" source="media/add-link/add-link-build-filled-in.png" alt-text="Screenshot of Add link dialog with Build number entered."::: -::: moniker-end +::: moniker-end +## Link work items to deployments -## Link several work items to a new git branch +As you develop your software, you can capture which code changes and builds support the completion of a work item. Your team can understand what work was done or how a bug was fixed through the audit trail of changes to the code base. -You can add a new git branch and link them to existing work items at the same time. +The link types used to construct these links are: **Branch**, **Build**, **Changeset**, **Commit**, **Found in build**, **Integrated in build**, **Pull Request**, **Versioned Item**, and **Integrated in release environment**. These types appear in the following image. -From a backlog or query results page, [multi-select the work items](bulk-modify-work-items.md#multi-select) you want to link to a new git branch, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon, and then **New branch...**. For more information, see [Link work items to Git development objects](connect-work-items-to-git-dev-ops.md). +:::image type="content" source="../queries/media/link-type-reference/conceptual-link-types-devops-objects.png" alt-text="Conceptual image of devops link types."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of backlog, context menu, choose Link multiple backlog items to a git branch.](media/add-link/link-git-branch.png) +> [!TIP] +> Drive development from the work item when you create it. You can also add the work item ID when creating branches, commits, and pull requests. Git lets you link work items to commits using the **Commit** link type. Here are the ways to do it: +> +> - Before committing your changes, add work item IDs in **Git Changes** for Visual Studio 2022 or **Team Explorer** for previous versions of Visual Studio: +> +> :::image type="content" source="../queries/media/link-git-commit-items.png" alt-text="Screenshot of adding work item ID or dragging items before committing changes."::: +> +> - Use the [git-commit](https://git-scm.com/docs/git-commit) command and include the work item ID in your comment. For example, apply this comment `#35 Catch null exception` to your commit. When you push the commit, the system creates a Commit link between the commit and work item #35. +> - Use the **Development** control for Git development from the work item. For more information, see [Drive Git development from a work item in Azure Boards](../backlogs/connect-work-items-to-git-dev-ops.md). +As shown in the following image, the Deployment control displays release information for two release stages. It includes work items linked to a Git commit or pull request for a release pipeline configured to integrate with Azure Boards. - +:::image type="content" source="../work-items/media/deployments-control/releases-stages-1.png" alt-text="Screenshot of multiple environments that the release is targeting."::: -[!INCLUDE [temp](../../includes/link-work-item-builds-projects.md)] +### Deployment control - +The Deployment control provides several features to help you manage and track the release status of work items. The following list outlines these features: -::: moniker range="tfs-2018" +- **Default appearance:** The Deployment control appears on the work item forms for User Story (Agile), Product Backlog Item (Scrum), Issue (Basic), Requirement (CMMI), Feature, Epic, Bug, Task, and Test Case work item types by default. +- **Custom work item types:** Custom work item types that use the Inherited process are automatically enabled. +- **Release information:** The Deployment control shows the release information for two stages of the release pipeline integrated with Azure Boards. +- **Linked work items:** This control only shows the work items that are linked to a Git commit or pull request for this pipeline. +- **Visual insight:** Gain visual insight into the status of a work item as it is deployed to different release environments and quickly navigate to each release stage and run. -## Find work items to link to + :::image type="content" source="../work-items/media/deployments-control/deployment-control-intro.png" alt-text="Screenshot of Work item form, Deployment control."::: -From the Add link dialog, you can open a secondary dialog to help you choose one or more work items to link to. If you're going to find and list work items to link to by using a saved query, first [define the query](../queries/using-queries.md) that you want to use. +- **Commit associations:** Work items associated with commits in the build show the status of the release. +- **Project scope:** Only work items within the same project get linked to where the release pipeline is defined. -1. From the Add link dialog, choose the … context menu or **Browse** button (Visual Studio) to open the following dialog. + :::image type="content" source="../work-items/media/deployments-control/release-settings-stages-1.png" alt-text="Screenshot showing multiple environments that the release is targeting."::: - ![Choose Linked work items](media/add-link-choose-linked-work-item-by-title.png) +- **Stage visibility:** When you open a work item, you can see the stages in real time. + + :::image type="content" source="../work-items/media/deployments-control/deployments-control-1.png" alt-text="Screenshot of Release Settings Stages, including Testing, Staging, Production, and Development."::: - If the work items are defined in another project, then first select the Project. Then, make your selections: +To populate the Deployment control, do the following steps: - - **Query**. Use this method when you've defined a query that you know contains the set or superset of the work items that you want. - - **IDs**. Use this method when you know the IDs of the work items that you want to link to. - In the **IDs** box, type the IDs of the work items that you want to find, separated by commas or spaces. - - **Title contains**. Use this method to find work items that have a common word or phrase in the title field. In the **and type** list, select the type of work item that you want to retrieve. +> [!NOTE] +> The Deployment control requires configuration of a Classic release pipeline. It doesn't support linking to release stages defined for a YAML pipeline. - > [!NOTE] - > To minimize the time required to run the query, narrow the filter criteria of the search. +1. Define a Classic release pipeline and set up the release stages as described in [Define your multi-stage continuous deployment (CD) pipeline](../../pipelines/release/define-multistage-release-process.md). +2. Configure the pipeline. +3. Link work items to a commit or pull request in Azure Repos Git repository. For more information, see: -1. Select the **Find** button. + - [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md) + - [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md) - Only those work items defined for the selected project and specified work item type are listed. To sort on a column field, choose the column title. +4. Run the pipeline. - + -1. In the list of returned work items, select one or more work items. +## Link work items to TFVC code development - - From the web portal: To select several items in a sequence, hold down the shift key. To select several non-sequential items, use the Ctrl key. +Team Foundation Version Control (TFVC) allows you to link work items to version control changesets or versioned source code files using the **Changeset** and **Versioned Item** link types. When you check in pending changes or use My Work to check in changes, work items are automatically linked to your changes. For more information, see [Check in your work](../../repos/tfvc/check-your-work-team-codebase.md). - - For Visual Studio, select each work item that should link to the current work item. You can also press the SHIFT key while clicking to select a range of work items, or press the CTRL key while clicking to select multiple work items. +:::image type="content" source="../../repos/tfvc/media/check-your-work-team-codebase/IC593474.png" alt-text="Screenshot of Team Explorer, My Work, Pending Changes, check in."::: -::: moniker-end + +## Link work items to tests -::: moniker range=">= azure-devops-2020" +Test-related link types link test case management work items to one another or to other work items. From the web portal or Microsoft Test Manager, you can view which test cases are defined for a test suite and which test suites are defined for a test plan. These objects aren't linked to each other through link types. -## Set work item state in pull request +You can link work items to test cases using the **Tested/Tested By** link types. Use the same link controls you use to link work items to other work items. See [Link work items](#link-work-items). -::: moniker-end +The following image shows the full set of link types that you can use with test management work item types. Most links between test management objects occur by running a task from the **Test** pages or Microsoft Test Manager. -[!INCLUDE [temp](../../includes/set-work-item-state-pull-request.md)] +:::image type="content" source="../queries/media/link-tracking-work-item-test-case-link-types.png" alt-text="Screenshot of Link types used to link test objects."::: +For example, when you add Shared Steps to a Test Case, they automatically get linked using the **Test Case/Shared Steps** link types. For more information, see [Share steps between test cases](/previous-versions/azure/devops/test/mtm/share-steps-between-test-cases). -::: moniker range=">= azure-devops-2020" +:::image type="content" source="../queries/media/link-work-items-support-traceability/test-case-work-item-form.png" alt-text="Screenshot of test work item form showing steps." lightbox="../queries/media/link-work-items-support-traceability/test-case-work-item-form.png"::: -To learn more about this feature, see [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md#set-work-item-state-in-pull-request). +:::image type="content" source="media/add-link/insert-shared-steps.png" alt-text="Screenshot of Insert Shared Steps dialog."::: -::: moniker-end +From the **Test** section, you can add test plans, test suites, and test cases, which are automatically linked. You can't add these items through a specific link type. The test system creates and manages the associations of test results to test cases and test plans. + + + +## Link work items to a Web site, network share, storyboard, or document +You can use a hyperlink or storyboard link type to link a work item to a website, network share, or document on a network share. Both link types are one-way links. To add these link types, use the same controls described earlier. See [Link work items](#link-work-items). -## More options for modifying links in bulk +When using the storyboard link type, specify a storyboard or document that provides work item specifications. This link type allows your team to access the shared file and add their comments. -Other features you can use to quickly link or change links that use the parent-child link type (some features are version-dependent, see the linked article for details): +:::image type="content" source="../queries/media/link-tracking-work-item-to-url-link-types.png" alt-text="Screenshot of Hyperlink or Storyboard link type to link a work item to a URL."::: -- To quickly link backlog items to portfolio backlog items with parent-child links, [use the mapping pane to organize your backlog](organize-backlog.md#mapping). Or, you can choose to Show Parents and [drag-and-drop items within the tree hierarchy](organize-backlog.md). -- To create and link tasks to backlog items, [use the sprint backlog page](../sprints/assign-work-sprint.md). -- To indent (![Indent](../queries/media/IC588323.png)), outdent (![Outdent](../queries/media/IC588324.png)), and change the tree hierarchy, use a tree query in Visual Studio. -- To add or delete work items or change the link structure, you can use Excel. See [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). +## View dependencies and track related work +Azure DevOps provides several ways to view dependencies and track related work: -[!INCLUDE [temp](../includes/view-linked-objects.md)] +- **Query Editor**: You can use the Query Editor to create custom queries that show all work items linked to a specific work item. +- **Backlogs and Boards**: The Backlogs and Boards views show parent-child relationships between work items, allowing you to see dependencies at a glance. +- **Dependency Tracker**: The Dependency Tracker is a Power BI report that provides a visual representation of dependencies between work items. - +To view the list of all objects linked to a work item, do the following steps: -::: moniker range="azure-devops" +1. Open the work item and select :::image type="icon" source="../media/icons/icon-links-tab-wi.png" border="false"::: **Links**. The links tab indicates the count of all linked objects. Linked objects get grouped under their link type, with a count within each group. -## Add, remove, and show links using Azure CLI + :::image type="content" source="../media/view-link-list/links-tab-link-count.png" alt-text="Screenshot of Links tab with count of linked objects."::: -You can add, remove, and show details of links made to a work item using link types supported by your organization with the [az boards work-item relation](/cli/azure/boards/work-item/relation) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). +1. (Optional) Expand or collapse each group, and sort within each group by **State**, **Latest Update**, or **Comment** by choosing the corresponding column title. -Link types include work link types, remote link types, hyperlinks, and attached files. For a list of all link types that you can specify, run the [az boards work-item relation list-type](../queries/link-type-reference.md#list-link-types) command. + For example, the following **Links** tab shows a portion of the 64 linked objects for a work item. + + :::image type="content" source="../media/view-link-list/list-linked-objects-links-tab.png" alt-text="Screenshot of Links tab with many linked objects." lightbox="../media/view-link-list/list-linked-objects-links-tab.png"::: + + Links prefaced with the :::image type="icon" source="../../media/icons/required-icon.png" border="false"::: exclamation mark indicate that the build, release, or other object is deleted. Due to retention policies, these objects automatically get deleted after a certain time period. + +## Query for linked work items + +To filter items based on hierarchical links, use the **Tree of work items** query type. To filter items based on all link types, use **Work items and direct links**. + +To find work items linked to other work items with specific link types, use a query that shows a primary and a secondary set of work items: +- The primary set meets the field criteria. +- The secondary set is linked to the primary set. + +You can’t query for work items in releases, but you can query for work items with external links. Add more query filters to refine your search. + +For more information, see [Query work items by link or attachment count](../queries/linking-attachments.md). + +You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using Parent/Child or any other link type. You can only view the hierarchy through the **Test** > **Test Plans** page. For more information, see [Create test plans and test suites](../../test/create-a-test-plan.md). + + + +::: moniker range="azure-devops" + +## Use Azure CLI to add, remove, or show links + +You can add, remove, and show details of links to a work item with the [az boards work-item relation](/cli/azure/boards/work-item/relation) command. For more information, see [Get started with Azure DevOps CLI](../../cli/index.md). + +Link types include work link types, remote link types, hyperlinks, and attached files. For a list of all link types that you can specify, run the [az boards work-item relation list-type](../queries/link-type-reference.md#list-link-types) command. ```azurecli az boards work-item relation add @@ -334,18 +412,15 @@ az boards work-item relation remove az boards work-item relation show ``` -In the following examples, the organization is *fabrikam* and the project ID corresponds to *cebd7ef5-4282-448b-9701-88c8637581b7*. The table format is used to show the output. For other formats, see [Output formats for Azure CLI commands](/cli/azure/format-output-azure-cli). - - -### Link work items +In the following examples, the organization is *fabrikam* and the project ID corresponds to *aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb*. The table format is used to show the output. For other formats, see [Output formats for Azure CLI commands](/cli/azure/format-output-azure-cli). -To link one or more work item to a single work item, enter the [az boards work-item relation add](/cli/azure/boards/work-item/relation#az-boards-work-item-relation-add) command. +### Link work items -#### Syntax +To link one or more work items to a single work item, enter the [az boards work-item relation add](/cli/azure/boards/work-item/relation#az-boards-work-item-relation-add) command. -Required parameters include the ID of the work item to link to and the link type. Supported link types include *Parent*, *Child*, *Related*, *Remote Related*. For a list of all link types that you can specify, run the [az boards work-item relation list-type](../queries/link-type-reference.md#list-link-types) command. +Required parameters include the ID of the work item to link to and the link type. Supported link types include *Parent*, *Child*, *Related*, and *Remote Related*. For a list of all link types, run the [az boards work-item relation list-type](../queries/link-type-reference.md#list-link-types) command. -For work items defined within the same organization, you must specify the work item ID or target URL. For work items defined in a remote organization, you must specify the target URL. You can specify multiple values by separating IDs or URLs with a comma. +For work items defined within the same organization, you must specify the work item ID or target URL. For work items defined in a remote organization, specify the target URL. You can specify multiple values by separating IDs or URLs with a comma. ```azurecli az boards work-item relation add --id @@ -356,37 +431,35 @@ az boards work-item relation add --id [--target-url] ``` -#### Example - -The following command links work item *ID=2807* to work item *ID=2794* with the *Child* link type. The command returns a list of all links currently defined for the work item. +The following command links work item *ID=2807* to work item *ID=2794* with the *Child* link type. The command returns a list of all links currently defined for the work item. ```azurecli az boards work-item relation add --id 2794 --relation-type Child --target-id 2856 --output table Are you sure you want to remove this relation(s)? (y/n): y Relation Type Url --------------- ------------------------------------------------------------------------------------------------- -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2850 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2808 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2820 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2856 -Parent https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2811 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2876 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2801 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2877 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2805 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2807 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2850 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2808 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2820 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2856 +Parent https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2811 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2876 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2801 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2877 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2805 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2807 ``` -To view the information for the linked work items, enter one of the URLs listed in your browser. + +To view the information for the linked work items, enter one of the URLs listed in your browser. ### Remove work item links To remove one or more linked work items from a single work item, enter the [az boards work-item relation remove](/cli/azure/boards/work-item/relation#az-boards-work-item-relation-remove) command. -Required parameters include the ID of the work item to remove the link from and the link type. You can only remove links to work items defined in the same organization. You can specify any of the supported link types except remote link types. +Required parameters include the ID of the work item to remove the link from and the link type. You can only remove links to work items defined in the same organization. You can specify any of the supported link types except remote link types. You must specify the target work item ID. You can specify multiple values by separating IDs or URLs with a comma. -#### Syntax ```azurecli az boards work-item relation remove --id --relation-type @@ -396,77 +469,70 @@ az boards work-item relation remove --id [--yes] ``` -#### Example - -The following command removes the link to work item *ID=2794* from work item *ID=2856* to work item with the *Child* link type. The command returns a list of all links currently defined for the work item. +The following command removes the link to work item *ID=2794* from work item *ID=2856* to work item with the *Child* link type. The command returns a list of all links currently defined for the work item. ```azurecli az boards work-item relation remove --id 2794 --relation-type Child --target-id 2807 --output table Are you sure you want to remove this relation(s)? (y/n): y Relation Type Url --------------- ------------------------------------------------------------------------------------------------- -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2850 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2808 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2820 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2856 -Parent https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2811 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2876 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2801 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2877 -Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2805 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2850 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2808 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2820 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2856 +Parent https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2811 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2876 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2801 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2877 +Child https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2805 ``` -To view the information for the linked work items, enter one of the URLs listed in your browser. +To view the information for the linked work items, enter one of the URLs listed in your browser. -### Show details of links made for a single work item +### Show details of links made for a single work item -To view the work items linked to a single work item, enter the [az boards work-item relation show](/cli/azure/boards/work-item/relation#az-boards-work-item-relation-show) command. For a list of all link types that can be returned, run the [az boards work-item relation list-type](../queries/link-type-reference.md#list-link-types) command. +To view the work items linked to a single work item, enter the [az boards work-item relation show](/cli/azure/boards/work-item/relation#az-boards-work-item-relation-show) command. For a list of all link types that can be returned, run the [az boards work-item relation list-type](../queries/link-type-reference.md#list-link-types) command. -#### Syntax ```azurecli az boards work-item relation show --id [--detect {false, true}] [--org] ``` -#### Example - The following command lists the details of links defined for work item *ID=2931* in the *fabrikam* organization in table format. ```azurecli az boards work-item relation show --id 2931 --output table Relation Type Url --------------- ----------------------------------------------------------------------------------------------------------------------------------- -Related https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2932 -Successor https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2932 -Remote Related https://dev.azure.com/fabrikam-fiber5/847568d2-6541-4a99-a240-228510ccbff7/_apis/wit/workItems/1777 -Parent https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2930 -Predecessor https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2933 -Attached File https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/attachments/1cc6c026-b4ed-420c-bfe6-065be726cba7 +Related https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2932 +Successor https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2932 +Remote Related https://dev.azure.com/fabrikam-fiber5/bbbbbbbb-1111-2222-3333-cccccccccccc/_apis/wit/workItems/1777 +Parent https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2930 +Predecessor https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/workItems/2933 +Attached File https://dev.azure.com/fabrikam/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/_apis/wit/attachments/1cc6c026-b4ed-420c-bfe6-065be726cba7 ``` -To view the information for the linked work items, enter one of the URLs listed in your browser. Choose the URL for an attached file to download the attachment. - +To view the information for the linked work items, enter one of the URLs listed in your browser. Choose the URL for an attached file to download the attachment. ::: moniker-end -## Related articles +## Delete work item links -::: moniker range=">= azure-devops-2020" +Do the following steps to delete a work item link. -- [Map backlog items to portfolio backlog items](organize-backlog.md) -- [Link work items to Git development objects](connect-work-items-to-git-dev-ops.md) -- [Link GitHub commits and pull requests to work items](../github/link-to-from-github.md) -- [Use Excel to edit tree-topology links](../backlogs/office/bulk-add-modify-work-items-excel.md) -- [Linking, traceability, and managing dependencies](../queries/link-work-items-support-traceability.md) +1. Open the work item. +2. Select the **Links** tab to see the list of links. +3. Select the link that you want to delete, and then select **Remove link**. +4. Confirm that you want to delete the link. -::: moniker-end +After a work item gets linked to a commit or pull request, it continues to appear as part of the release stages. For example, if you have a work item that didn't pass testing criteria, you might want to remove it from the builds and releases. -::: moniker range="<= azure-devops-2019" +To remove the work item from participating in future builds and releases, delete the link to the most recent commit and pull request. -- [Map backlog items to portfolio backlog items](organize-backlog.md) -- [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md) -- [Link work items to Git development objects](connect-work-items-to-git-dev-ops.md) -- [Use Excel to edit parent-child links](../backlogs/office/bulk-add-modify-work-items-excel.md) -- [Linking, traceability, and managing dependencies](../queries/link-work-items-support-traceability.md) +## Related articles -::: moniker-end +- [Review the reference guide for link types](../queries/link-type-reference.md) +- [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md) +- [Track dependencies by using Delivery Plans](../plans/track-dependencies.md) +- [Organize your backlog and map child work items](../backlogs/organize-backlog.md) +- [Download the Work item visualization extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization) diff --git a/docs/boards/backlogs/add-work-items.md b/docs/boards/backlogs/add-work-items.md deleted file mode 100644 index 3e3ad2a0e0b..00000000000 --- a/docs/boards/backlogs/add-work-items.md +++ /dev/null @@ -1,310 +0,0 @@ ---- -title: Add user stories & other work items to help manage your project -titleSuffix: Azure Boards -description: Add work items so you can plan and manage a software project using Agile tools, Scrum, or Kanban when connected to a project in Azure Boards or Azure DevOps. -ms.custom: devx-track-azurecli -ms.service: azure-devops-boards -ms.assetid: 9474A25E-A9D8-433D-8370-C94624B4ACD6 -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.topic: tutorial -ms.date: 04/01/2022 ---- - -# Add and update a work item - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -You add work items to plan and manage your project. Different types of work items track different types of work—such as user stories or product backlog items, tasks, bugs, or issues. Use work items to describe the work to be done, assign work, track status, and coordinate efforts within your team. - - -> [!NOTE] -> This article shows how to add any type of work item. However, the recommended tool for adding backlog or portfolio items—such as, user stories, product backlog items, features, or epics— is to use the backlog or Kanban board to add new items. For more information, see [Create your backlog](create-your-backlog.md), [Define features and epics](define-features-epics.md) and [Start using your Kanban board](../boards/kanban-quickstart.md). To create test cases and link them to user stories, see [Add, run, and update inline tests](../boards/add-run-update-tests.md) and [Create test plans and test suites](../../test/create-a-test-plan.md). - -For other clients that you can use to add and update work items, see [Best tools for adding, updating, and linking work items](../work-items/best-tool-add-update-link-work-items.md). - -[!INCLUDE [temp](../includes/prerequisites-work-items.md)] - - - -## Add a work item - -You can start adding work items once you connect to a project. - - -### [Browser](#tab/browser/) - -::: moniker range=">= azure-devops-2019" - -Choose a **Boards** page—such as **Work Items**, **Boards**, or **Backlogs**. Then choose the :::image type="icon" source="../../media/icons/blue-add.png" border="false"::: plus icon and select from the menu of options. - -> [!div class="mx-imgBorder"] -> ![Work, add artifact](../../project/navigation/media/add-artifact/add-work-item-query-vert.png) - - -> [!NOTE] -> Depending on the process chosen when the project was created—[Agile](../work-items/guidance/agile-process.md), [Basic](../get-started/plan-track-work.md), [Scrum](../work-items/guidance/scrum-process.md), -or [CMMI](../work-items/guidance/cmmi-process.md)—the types of work items you can create are different. For example, backlog items may be called user stories (Agile), issues (Basic) product backlog items (Scrum), or requirements (CMMI). All four are similar: they describe the customer value to deliver and the work to be performed. -> -> For more information, see [About processes and process templates](../work-items/guidance/choose-process.md). The Basic process requires Azure DevOps Server 2019.1 or later version. - -Enter a title and then save the work item. Before you can change the State from its initial default, you must save it. - -![Agile process, User story work item form](media/add-new-work-item-vsts-user-story.png) - -You can [add tags to any work item to filter backlogs and queries](../queries/add-tags-to-work-items.md). - -Work items you add are automatically scoped to your team's default area path and iteration path. To change the team context, see [Switch project or team focus](../../project/navigation/go-to-project-repo.md). - -That's it! - -Create as many work items as you need of the type you need to track the work you want to manage. - -::: moniker-end - - -::: moniker range="tfs-2018" - -1. From **Work**, choose the work item type from the New Work Item list of options. Here, we choose to create a User Story. - - Add a work item - - > [!NOTE] - >Depending on the process chosen when the project was created—[Agile](../work-items/guidance/agile-process.md), [Scrum](../work-items/guidance/scrum-process.md), - or [CMMI](../work-items/guidance/cmmi-process.md)—the types of work items you can create are different. For example, backlog items may be called user stories (Agile), product backlog items (Scrum), or requirements (CMMI). All three are similar: they describe the customer value to deliver and the work to be performed. - > - > For more information, see [About processes and process templates](../work-items/guidance/choose-process.md). - - Choose the :::image type="icon" source="../media/icons/pin-icon.png" border="false"::: pin icon to have it show up within **Work** drop down menu. - -3. Enter a title and then save the work item. Before you can change the State from its initial default, you must save it. - - ![Agile process, User story work item form](media/add-new-work-item-vsts-user-story.png) - - You can [add tags to any work item to filter backlogs and queries](../queries/add-tags-to-work-items.md). - - Work items you add are automatically scoped to your team's default area path and iteration path. To change the team context, see [Switch project or team focus](../../project/navigation/go-to-project-repo.md?toc=/azure/devops/boards/work-items/toc.json). - -::: moniker-end - - -### [Visual Studio 2019](#tab/visual-studio/) - -1. Open Visual Studio 2019, Team Explorer, and then choose **Work Items**. - - > [!div class="mx-imgBorder"] - > ![Visual Studio, Team Explorer, Choose Work Items](../work-items/media/view-add/open-work-items-vs-te-complete.png) - - If you don't see the **Work Items** option, you need to connect to a project and not just a repository. From the Connect to a Project dialog. Use **CTRL-Shift** to select your options and then choose **Connect**. - - > [!div class="mx-imgBorder"] - > ![Connect to a Project dialog, connect to a Project and Git repository](../work-items/media/view-add/connect-to-a-project-and-github.png) - -1. Choose **New Work Item** and select the work item type you want. - - > [!div class="mx-imgBorder"] - > ![Work Items, Add User Story](../work-items/media/view-add/add-user-story-vs-te.png) - - When you work within Visual Studio 2017 or later version, a browser window opens with the work item form to complete. If you work within Visual Studio 2015 or earlier version, a work item form opens within Visual Studio. - -### [Azure DevOps CLI](#tab/azure-devops-cli/) - -[!INCLUDE [temp](../includes/add-work-items-cli.md)] - -[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - -* * * - -## Update work items as work progresses - -As work progresses, team members can update the state and reassign it as needed. While the workflow states differ for different work item types, they usually follow a progression from New or Active to Completed or Done. - -#### [Browser](#tab/browser/) - -> [!div class="mx-imgBorder"] -> ![Update the State of a User Story](media/add-work/update-state.png) - -::: moniker range=">= azure-devops-2019" - -The following image shows the workflow states for a user story. If you want to discard a work item, change the state to Removed, or you can delete it. For more information, see [Move, change, or remove a work item](remove-delete-work-items.md). - -::: moniker-end - -::: moniker range="tfs-2018" - -The following image shows the work flow states for a user story. If you want to discard a work item, change the state to Removed, or you can delete it. For more information, see [Remove or delete a work item](remove-delete-work-items.md). - -::: moniker-end - -:::row::: - :::column span="2"::: - **Typical workflow progression:** - - The product owner creates a user story in the **New** state with the default reason, **New user story** - - The team updates the status to **Active** when they decide to complete the work during the sprint - - A user story is moved to **Resolved** when the team has completed all its associated tasks and unit tests for the story pass. - - A user story is moved to the **Closed** state when the product owner agrees that the story has been implemented according to the Acceptance Criteria and acceptance tests pass. - -**Atypical transitions**: - - Change the State from **Active** to **New**. - - Change the State from **Resolved** to **Active**. - - Change the State from **Resolved** to **New**. - - Change the State from **Closed** to **Active**. - - Change the State from **New** to **Removed**. - - Change the State from **Removed** to **New**. - :::column-end::: - :::column span="2"::: - ![User story workflow, Agile process](../work-items/guidance/media/alm_pt_agile_wf_userstory.png) - :::column-end::: -:::row-end::: - -Removed work items remain in the data store and can be reactivated by changing the State. - -With each update, changes are recorded in the History field, which you can view through the **History** tab. - -![View change history](media/add-work-item-history.png) - -To find work items based on their history, see [History & auditing](../queries/history-and-auditing.md). - -[!INCLUDE [temp](../includes/discussion-tip.md)] - - -### [Visual Studio 2019](#tab/visual-studio/) - -There's no way to use Visual Studio 2019 to update a work item at this time. - -### [Azure DevOps CLI](#tab/azure-devops-cli) - -::: moniker range="azure-devops" - -[Update work item](#update-work-item) | [Show work item details](#show-work-item) - - - -### Update a work item - -You can make updates to your work items with the [az boards work-item update](/cli/azure/boards/work-item#az-boards-work-item-update) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). - -```azurecli -az boards work-item update --id - [--area] - [--assigned-to] - [--description] - [--discussion] - [--fields] - [--iteration] - [--open] - [--org] - [--reason] - [--state] - [--title] -``` - -### Parameters - -- **id**: Required. The ID of the work item. - -### Optional parameters -- **area**: Area the work item is assigned to (for example, **Demos**). -- **assigned-to**: Name of the person the work item is assigned-to (for example, **fabrikam**). -- **description**: Description of the work item. -- **discussion**: Comment to add to a discussion in a work item. -- **fields**: Space separated "field=value" pairs for custom fields you would like to set. -- **iteration**: Iteration path of the work item (for example, **DemosIteration 1**). -- **open**: Open the work item in the default web browser. -- **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **reason**: Reason for the state of the work item. Must be a valid workflow Reason for the work item type. -- **state**: State of the work item (for example, **Active**). Must be a valid workflow State for the work item type. -- **title**: Title of the work item. - - -### Example - -The following command updates the title of the bug with the ID 864 and displays the results in the Azure DevOps CLI in table format. - -```azurecli -az boards work-item update --id 864 --title "Fix security issues" --output table - -ID Type Title Assigned To State ----- ------ ------------------- ------------------- ------- -864 Bug Fix security issues contoso@contoso.com New -``` - - - -#### Add comments to a discussion - -Use the **discussion** parameter to add comments to the **Discussion** control of a work item. The following command adds the specified comment to the bug with the ID 864 and opens the bug in your default web browser, where you can view the comment. - -```azurecli -az boards work-item update --id 864 --discussion "This work item is about 50% complete" --open -``` - -### Show details for a work item - -You can show the details for a work item with the [az boards work-item show](/cli/azure/boards/work-item#az-boards-work-item-show) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). - -```azurecli -az boards work-item show --id - [--open] - [--org] -``` - -### Parameters - -- **id**: Required. The ID of the work item. -- **open**: Open the work item in the default web browser. -- **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. - -### Example - -The following command shows details for the bug with the ID 864. It opens in your default web browser and also displays the results in the Azure DevOps CLI in table format. - -```azurecli -az boards work-item show --id 864 --open --output table - -ID Type Title Assigned To State ----- ------ ---------- ------------------- ------- -864 Bug fix-issues contoso@contoso.com New -``` - -::: moniker-end - -[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - -* * * - -## Follow a work item - -When you want to track the progress of a single work item, choose the :::image type="icon" source="../media/icons/follow-icon.png" border="false"::: follow icon. This action signals the system to notify you when changes are made to the work item. - -> [!div class="mx-imgBorder"] -> ![Work item form, Follow icon control](../work-items/media/follow-work/follow-work-item.png) - -You'll only receive notifications when other project members modify the work item, such as adding to the discussion, changing a field value, or adding an attachment. - -Notifications are sent to your preferred email address, which [you can change from your user profile](../../organizations/notifications/change-email-address.md). - -To stop following changes, choose the :::image type="icon" source="../media/icons/following-icon.png" border="false"::: following icon. - -::: moniker range="< azure-devops" - -> [!IMPORTANT] -> To support the follow feature, [you must configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts) for team members to receive notifications. - -::: moniker-end - -## Next steps - -To quickly add backlog items, such as user stories, requirements, or bugs, see these articles: -> [!div class="nextstepaction"] -> [Create your backlog](create-your-backlog.md) -> [Kanban quickstart](../boards/kanban-quickstart.md) - - -For descriptions of each field and work item form control, see [Work item field index](../work-items/guidance/work-item-field.md?toc=/azure/devops/boards/work-items/toc.json ) and [Work item form controls](../work-items/work-item-form-controls.md?toc=/azure/devops/boards/work-items/toc.json ). - - -Once you've added several work items, you can use additional features to get [notified of changes](../../organizations/notifications/manage-your-personal-notifications.md), [create queries](../queries/using-queries.md), [define status and trend charts](../../report/dashboards/charts.md), plus more. - -For more clients that you can use to add work items, see [Clients that support tracking work items](../../user-guide/tools.md?toc=/azure/devops/boards/work-items/toc.json). diff --git a/docs/boards/backlogs/automate-work-item-state-transitions.md b/docs/boards/backlogs/automate-work-item-state-transitions.md new file mode 100644 index 00000000000..a5c5fe2d1d1 --- /dev/null +++ b/docs/boards/backlogs/automate-work-item-state-transitions.md @@ -0,0 +1,93 @@ +--- +title: Set work item automation rules for your team +titleSuffix: Azure Boards +description: Learn how to set rules to update the state of your team's work items automatically, according to the state of the child tasks. +ms.service: azure-devops-boards +ms.custom: cross-service +ms.author: chcomley +ms.topic: how-to +monikerRange: '<= azure-devops' +ms.date: 01/05/2024 +--- + + +# Automate work item state transitions + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +Automatically update the state of a work item according to the state of its child tasks. For example, if one task is changed to `Doing`, then the parent gets set to `Doing`. And if all tasks are in `Closed` state, then the parent gets `Closed`. + +Rules are established at the team backlog level and are applicable to all work items at that specific level. You have the flexibility to establish these rules independently for each backlog level, including stories, features, and epics. For example, you can automate the closure of user stories, but keep features and epics open. + +> [!IMPORTANT] +> Work item automation rules exclusively pertain to your team’s workflow on the backlog and boards. Other teams within your project can customize their own rules to align with their specific work processes. + +## Prerequisites + +::: moniker range="azure-devops" + +| Category | Requirements | +|:-------------|:------------| +|**Permissions**| To configure work item automation rules for your team: [Team Administrator](../../organizations/settings/add-team-administrator.md) role or member of the [**Project Administrators**](../../organizations/security/change-project-level-permissions.md) group.| + +::: moniker-end + +::: moniker range="< azure-devops" + +| Category | Requirements | +|:-------------|:------------| +|**Permissions**| To configure team settings: [Team Administrator](../../organizations/settings/add-team-administrator.md) role or member of the [**Project Administrators**](../../organizations/security/change-project-level-permissions.md) group.| + +::: moniker-end + +## Set rules + +Do the following steps to set team rules for each backlog level. + +> [!NOTE] +> Work items must belong to the same team; when you close a task in a different team or project, it doesn't trigger the closure of the parent item. + +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). + +2. Select **Boards** > **Backlogs** > :::image type="icon" source="../media/icons/gear_icon.png" border="false"::: **Configure team settings**. + + :::image type="content" source="media/backlog-settings.png" alt-text="Screenshot of selection process, Boards, Backlogs, and then Configure team settings."::: + +3. Check one or more applicable boxes, which trigger the parent work items on this backlog level, and then select **Save**. + + :::image type="content" source="media/set-team-automation-rules.png" alt-text="Screenshot of team automation rules settings page."::: + + Work item states are set to automatically transition when child items get updated on your backlog. + +**Rules applied to sprint board** + +These rules operate seamlessly, regardless of where you make updates to the child items, such as on the sprint board, for example. + +:::image type="content" source="media/sprintboard-drag-and-drop-update-parent.gif" alt-text="Animation of demo of automation rules for sprintboard, drag and drop child task activates, and then closes the parent user story on the board."::: + +**Rules applied to the user stories backlog level** + +The following example shows the rules applied to the user stories backlog level. + +:::image type="content" source="media/backlog-child-closes-parent.gif" alt-text="Animation of demo of automation rules for simple workflow, closing a child task closes the parent user story on the backlog."::: + +**Rules applied to several backlog levels in sync** + +The following example shows the rules applied to several backlog levels in sync. + +:::image type="content" source="media/rules-applied-several-backlog-levels.gif" alt-text="Animation of demo of automation rules applied to several backlog levels in sync."::: + +## FAQs + +For answers to the following frequently asked questions, see the [FAQs](../faqs.yml#automation-rules): +- Is there way to make the parent active when a child is active? +- Why are my work items automatically changing state? +- Why are the rules not triggering when I reactivate a child item? +- Can I set automation rules per work item type or state? +- Can I set up automation rules for user stories but not for features or epics? +- Why are automation rules not working if the child or parent items belongs to a different team or project? + +## Related articles + +- [Manage and configure team tools](../../organizations/settings/manage-teams.md) +- [Configure team notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) diff --git a/docs/boards/backlogs/backlogs-overview.md b/docs/boards/backlogs/backlogs-overview.md index 0df17efdb83..3e65603fa25 100644 --- a/docs/boards/backlogs/backlogs-overview.md +++ b/docs/boards/backlogs/backlogs-overview.md @@ -1,103 +1,80 @@ --- -title: Use backlogs to plan your projects in Azure Boards -titleSuffix: Azure Boards -description: Learn how to plan, track, and organize user stories, features, and bugs using backlogs and multiple teams in Azure Boards. -ms.custom: "boards-backlogs, seodec18" +title: Use backlogs to manage projects +titleSuffix: Azure Boards +description: Learn about how to plan, track, and organize user stories, features, and bugs using backlogs and multiple teams in Azure Boards. +ms.custom: boards-backlogs ms.service: azure-devops-boards ms.assetid: 28C02AE8-CF8D-4B6E-8301-F46A5622E6C4 ms.author: chcomley author: chcomley ms.topic: overview monikerRange: '<= azure-devops' -ms.date: 08/04/2022 +ms.date: 10/16/2024 +#customer intent: As a project administrator, I want to understand backlogs in Azure Boards and how to use them to plan and improve my team workflow. --- - -# Use backlogs for effective project management in Azure Boards +# Use backlogs to manage projects [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +With *backlogs*, you can plan your project by adding user stories or requirements to your product backlog. With your plan in place, you can start driving code development efforts. -With **Backlogs**, you can quickly plan your project by adding user stories or requirements to your product backlog. Once you have your plan in place, you can start driving code development efforts. - -If you're a project administrator just getting started, review [Configure and customize Azure Boards](../configure-customize.md). Review the settings to learn more about defining area and iteration paths and customizing your work item types. Backlogs are automatically created when you create a project or add a team. Each team has access to their own product, portfolio, and sprint backlogs as described in [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md#each-team-gets-their-own-set-of-tools). +If you're a project administrator, see [Configure and customize Azure Boards](../configure-customize.md), which shows you how to define area and iteration paths and customize your work item types. When you create a project or add a team, Azure Boards automatically creates a backlog. Each team has access to their own product, portfolio, and sprint backlogs. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md#each-team-gets-their-own-set-of-tools). -## Use backlogs +## About backlogs -You plan and track your project using the suite of Agile tools you access from the web portal. Agile tools support the core Agile methods—Scrum and Kanban—used by software development teams today. Scrum tools support defining and managing work within sprints, setting capacity, and tracking tasks. Kanban tools allow you to manage a continuous flow of work via an interactive sign board. +An Azure Boards backlog is a prioritized list of work items that guides your developments team's effort. A backlog helps manage project scope and facilitates effective communication and collaboration through the software development lifecycle. -If you're new to Agile, see [What is Agile?](/devops/plan/what-is-agile) for an overview. - -Use backlogs to do the following tasks: +Use backlogs to do the following tasks: ::: moniker range=">= azure-devops-2020" -- Quickly define the work your team is tasked with by [defining user stories, product backlog items, or requirements](create-your-backlog.md) -- [Reorder your backlog](create-your-backlog.md#move-items-priority-order) to make sure you're working on the highest priority items first -- [Add details and estimates](create-your-backlog.md#estimates) to your backlog items -- Quickly assign backlog items to team members and to sprints. You can use either [bulk update](bulk-modify-work-items.md) or [drag to a sprint](../sprints/assign-work-sprint.md) -- Group or organize backlog items by [mapping them within a hierarchy](organize-backlog.md) -- Review the hierarchy or [portfolio of work assigned to multiple teams](#multi-team) -- [Forecast work](../sprints/forecast.md) to estimate what can be delivered within a sprint -- [Display rollup progress, counts, or totals](display-rollup.md) to show completion of work or amount of work still to do. - -::: moniker-end - -::: moniker range="< azure-devops-2020" - -- Quickly define the work your team is tasked with by [defining user stories, product backlog items, or requirements](create-your-backlog.md) -- [Reorder your backlog](create-your-backlog.md#move-items-priority-order) to make sure you're working on the highest priority items first -- [Add details and estimates](create-your-backlog.md#estimates) to your backlog items -- Quickly assign backlog items to team members and to sprints\. You can use either [bulk update](bulk-modify-work-items.md) or [drag to a sprint](../sprints/assign-work-sprint.md) -- Group or organize backlog items by [mapping them within a hierarchy](organize-backlog.md) -- Review the hierarchy or [portfolio of work assigned to multiple teams](#multi-team) -- [Forecast work](../sprints/forecast.md) to estimate what can be delivered within a sprint. +- [Define user stories, product backlog items, or requirements](create-your-backlog.md) +- [Reorder your backlog](create-your-backlog.md#reorder-your-backlog) +- [Add details and estimates to your backlog items](create-your-backlog.md#add-details-and-estimates-to-backlog-items) +- [Bulk update](bulk-modify-work-items.md) +- [Drag items to a sprint](../sprints/assign-work-sprint.md) +- [Map backlog items within a hierarchy](organize-backlog.md) +- [Review the hierarchy or portfolio of work assigned to multiple teams](#multi-team) +- [Forecast work](../sprints/forecast.md) +- [Display rollup progress, counts, or totals](display-rollup.md) ::: moniker-end -[!INCLUDE [temp](../includes/setup-backlogs-boards.md)] - -## Product and portfolio backlogs - -Backlogs present work items as lists. A product backlog represents your project plan, the roadmap for what your team plans to deliver. Your backlog also provides a repository of all the information you need to track and share with your team. Portfolio backlogs allow you to group and organize your backlog into a hierarchy. - -::: moniker range=">= azure-devops-2019" - -![Screenshot of Boards Backlogs.](../work-items/media/about-agile/view-backlogs.png) + -::: moniker-end +[!INCLUDE [note setup backlog](../includes/setup-backlogs-boards.md)] -::: moniker range="tfs-2018" +## Product and portfolio backlogs -![Screenshot of Web portal, choose Boards and then Backlogs, TFS 2018.](../work-items/media/view-add/view-stories-backlogs-standard.png) +Backlogs present work items as lists. A *product backlog* represents your project plan, the roadmap for what your team plans to deliver. It also provides a repository of all the information need to track and share with your team. -::: moniker-end +In [Agile methodologies](/devops/plan/what-is-agile), a *portfolio backlog* lets you group and organize your backlog into a hierarchy. You can display high-level initiatives, epics, or projects that your organization plans to work on over a longer period of time. These initiatives are often too large or complex to fit in the scope of a single team's backlog. They require coordination and planning at a higher organizational level. +:::image type="content" source="../work-items/media/about-agile/view-backlogs.png" alt-text="Screenshot of Boards Backlogs."::: -## Backlog configuration +## Backlog configuration -[!INCLUDE [temp](../includes/note-add-backlog-board.md)] +[!INCLUDE [note add backlog](../includes/note-add-backlog-board.md)] -Each backlog is associated with a team. Team configuration settings determine the work items that appear on the team backlog. Specifically, the team administrator defines the following for their team: +Each backlog is associated with a team and the team configuration settings determine the work items that appear on the team backlog. The team administrator does the following tasks for their team: -- Selects the Area Paths that are active for the team, only work items assigned to these area paths appear on the team's backlog -- Sets the default Area Path and Iteration Path used when defining work items from the team backlog -- Selects the Iteration Paths that are active for the team -- Determines which backlog levels are active for the team -- Defines how bugs get treated, as requirements or as tasks. +- Select the Area Paths that are active for the team. Only work items assigned to these area paths appear on the team's backlog. +- Set the default Area Path and Iteration Path used when defining work items from the team backlog. +- Select the Iteration Paths that are active for the team. +- Determine which backlog levels are active for the team. +- Define how bugs get treated, as requirements or as tasks. For more information, see the following articles: + - [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md) - [Define area paths and assign to a team](../../organizations/settings/set-area-paths.md) - [Select backlog levels](../../organizations/settings/select-backlog-navigation-levels.md) - [Show bugs on backlogs or boards](../../organizations/settings/show-bugs-on-backlog.md) -::: moniker range=">= azure-devops-2019" -[!INCLUDE [temp](../includes/tip-configure-backlog-view.md)] -::: moniker-end - +[!INCLUDE [tip configure backlog view](../includes/tip-configure-backlog-view.md)] -### Common backlog configurations for multiple teams +### Common backlog configurations for multiple teams **Question**: *Can you define a backlog configuration that multiple teams can subscribe to?* **Answer**: *No. Each team controls their own team settings and backlog configurations.* @@ -107,200 +84,276 @@ Because each user can configure their own **Column Options** and **View Options* ::: moniker-end ::: moniker range="< azure-devops" -Because each user can configure their own **Column Options** and **View Options**, there's no way to configure a common backlog view for all teams. You can, however, define the default column options for all team members by editing the process configuration. To learn how, see [Process configuration XML element reference, Set default columns](../../reference/xml/process-configuration-xml-element.md#columns). +Because each user can configure their own **Column Options** and **View Options**, there's no way to configure a common backlog view for all teams. You can, however, define the default column options for all team members by editing the process configuration. To learn how, see [Process configuration XML element reference, Set default columns](../../reference/xml/process-configuration-xml-element.md#columns). ::: moniker-end - -## Define work items and create your backlog +## Define work items and create your backlog -You build your project plan by creating a backlog of work items. These items represent the features, requirements, user stories, or other work to complete. Portfolio backlogs provide support for organizing work in a hierarchical fashion. They help track major product initiatives or scenarios that rely on many stories or requirements. Different types of work items help you track different types of work, such as user stories, tasks, bugs, issues, and more. +Build your project plan by creating a backlog of work items. These items represent the features, requirements, user stories, or other work to complete. Portfolio backlogs provide support for organizing work in a hierarchical fashion. They help track major product initiatives or scenarios that rely on many stories or requirements. Different types of work items help you track different types of work, such as user stories, tasks, bugs, and issues. +[:::image type="content" source="media/overview/gs-planning-define-stories.png" alt-text="Diagram titled Define stories conceptual image of tasks.":::](create-your-backlog.md)[:::image type="content" source="media/overview/gs-planning-organize-backlog.png" alt-text="Diagram titled Organize backlog conceptual image of tasks.":::](organize-backlog.md)[:::image type="content" source="media/overview/gs-planning-manage-bugs.png" alt-text="Diagram titled Manage bugs conceptual image of tasks.":::](manage-bugs.md)[:::image type="content" source="media/overview/gs-planning-manage-issues.png" alt-text="Diagram titled Manage issues conceptual image of tasks.":::](manage-issues-impediments.md) -[![Define stories conceptual image of tasks.](media/overview/gs-planning-define-stories.png)](create-your-backlog.md)[![Organize backlog conceptual image of tasks.](media/overview/gs-planning-organize-backlog.png)](organize-backlog.md)[![Manage bugs conceptual image of tasks.](media/overview/gs-planning-manage-bugs.png)](manage-bugs.md)[![Manage issues conceptual image of tasks.](media/overview/gs-planning-manage-issues.png)](manage-issues-impediments.md) - - - + ## Backlog priority or stack rank order -The sequence of items on each backlog is determined according to where you've [added the items or moved the items on the page](create-your-backlog.md#move-items-priority-order). As you drag items within the backlog list, a background process updates the [**Stack Rank** (Agile and CMMI processes)](../queries/planning-ranking-priorities.md) or [**Backlog Priority** (Scrum process)](../queries/planning-ranking-priorities.md) fields. These fields are used by the system to track the relative ranking of items on the product, feature, epic, or other portfolio backlog. By default, these fields don't appear on the work item form. +Where you add or move the items on the page determines the sequence of items on each backlog. For more information, see [Reorder your backlog](create-your-backlog.md#move-items-priority-order). -![Screenshot showing how to reorder work items.](media/create-backlog/cyb-order-backlog.png) +As you drag items within the backlog list, a background process updates the *Stack Rank* [(Agile and Capability Maturity Model Integration (CMMI) processes)](../queries/planning-ranking-priorities.md) or *Backlog Priority* [(Scrum process)](../queries/planning-ranking-priorities.md) fields. The system uses these fields to track the relative ranking of items on the product, feature, epic, or other portfolio backlog. By default, these fields don't appear on the work item form. -Refrain from using the bulk modify function to change the value of the backlog priority field. While you can assign a value to these fields, you'll be assigning the same value to all items you've selected for bulk edit. +:::image type="content" source="media/create-backlog/cyb-order-backlog.png" alt-text="Screenshot showing how to reorder work items."::: -The preferred method for bulk edit is to use multi-select to move items to the top, bottom, or specific position within the page. If you must edit one of the backlog order fields in bulk to get a large number of work items in the priority order you want, use [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). You can export a query containing the backlog items, update either the Backlog Priority or Stack Rank fields, and then publish your changes. +Don't use the bulk modify function to change the value of the backlog priority field. While you can assign a value to these fields, you assign the same value to all items that you select for bulk edit. -## In Progress items and work listed on the backlog +The preferred method for bulk edit is to use multi-select to move items to the top, bottom, or specific position within the page. If you must edit one of the backlog order fields in bulk to get a large number of work items in the priority order you want, use [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). You can export a query that contains the backlog items, update either the Backlog Priority or Stack Rank fields, and then publish your changes. -Backlogs are designed to display work that corresponds to a Proposed, In Progress, or Resolved category state. Once you've completed work and its state enters a *Done*, or *Closed* state, then it falls off the backlog view. You can always [create a query](../queries/using-queries.md) to view completed work, or view the [**Recently completed** pivot from the **Work Items** page](../work-items/view-add-work-items.md). +## In Progress items and work listed on the backlog -In general, you'll want to display all items that are in the **In Progress** category state, which corresponds to the *Active* and *Committed* states. To focus on work that is proposed but not in progress, you can toggle the backlog view to turn off [**In Progress**](create-your-backlog.md#convert-ideas). This toggle is useful when [forecasting your product backlog](../sprints/forecast.md). +Backlogs are designed to display work that corresponds to a Proposed, In Progress, or Resolved category state. When you complete work and its state enters a *Done*, or *Closed* state, it falls off the backlog view. You can always [create a query](../queries/using-queries.md) to view completed work, or view the **Recently completed** pivot from the **Work Items** page. For more information, see [View and add work items](../work-items/view-add-work-items.md). -If your backlog is missing items, you might check if the **In Progress** view has been turned off. For more information, see [Workflow states and state categories](../work-items/workflow-and-state-categories.md). +In general, you display all items that are in the **In Progress** category state, which corresponds to the *Active* and *Committed* states. To focus on work that is proposed but not in progress, you can toggle the backlog view to turn off [**In Progress**](create-your-backlog.md#convert-ideas). This toggle is useful when [forecasting your product backlog](../sprints/forecast.md). +If your backlog is missing items, check whether the **In Progress** view is turned off. For more information, see [Workflow states and state categories](../work-items/workflow-and-state-categories.md). -## Organize your backlog by mapping and reparenting backlog items +## Organize your backlog by mapping and reparenting backlog items -When you have many initiatives your teams are working on, you may want to group the work according to these initiatives. By defining features and epics, you can group your work into a three-tiered hierarchy consisting of epics, features, and backlog items. +When you have many initiatives your teams are working on, you might want to group the work according to these initiatives. By defining features and epics, you can group your work into a three-tiered hierarchy consisting of epics, features, and backlog items. -For example, here the Customer Service team has organized several backlog items under two features and one epic. +For example, here the Customer Service team organized several backlog items under two features and one epic. ::: moniker range=">= azure-devops-2020" -> [!div class="mx-imgBorder"] -> ![Screenshot of Backlog that shows parents and multi-team ownership.](media/overview/customer-service-backlog-parents-on.png) - -::: moniker-end - -::: moniker range="<= azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Screenshot of Backlog that shows parents and multi-team ownership, Azure DevOps Server 2019 and earlier versions.](media/overview/customer-service-backlog-parents-on.png) +:::image type="content" source="media/overview/customer-service-backlog-parents-on.png" alt-text="Screenshot of Backlog that shows parents and multi-team ownership."::: ::: moniker-end + +[!INCLUDE [velocity](../includes/velocity-section.md)] -[!INCLUDE [temp](../includes/velocity-section.md)] - -[!INCLUDE [temp](../includes/display-rollup-section.md)] +[!INCLUDE [display rollup](../includes/display-rollup-section.md)] ## Work with multi-team ownership of backlog items -When you have several teams, your hierarchical views may show items that belong to other teams. +When you have several teams, your hierarchical views can show items that belong to other teams. ### View backlog items and parent items owned by other teams -Your team's product backlog lists only those items whose area path matches items assigned to your team. However, if you show parents, -you'll see the parent epic of the features and backlog items, even if the epic or feature is owned by another team. +Your team's product backlog lists only those items whose area path matches items assigned to your team. If you show parents, you see the parent epic of the features and backlog items, even if another team owns the epic or feature. ::: moniker range=">= azure-devops-2020" -Items that are owned by other teams appear with an information icon :::image type="icon" source="../../media/icons/info.png" border="false":::. +Other team-owned items appear with an information icon :::image type="icon" source="../../media/icons/info.png" border="false":::. -> [!div class="mx-imgBorder"] -> ![Screenshot of backlog items and parent items owned by other teams.](media/multi-ownership/customer-service-backlog-parents-on-s155.png) +:::image type="content" source="media/multi-ownership/customer-service-backlog-parents-on-s155.png" alt-text="Screenshot of backlog items and parent items owned by other teams."::: -> [!TIP] -> Add the **Node Name** field as a column to identify the area path/team associated with the work items. +> [!TIP] +> Add the **Node Name** field as a column to identify the area path/team associated with the work items. ::: moniker-end -::: moniker range="azure-devops-2019" - -Items that are owned by other teams appear with an information icon :::image type="icon" source="../../media/icons/info.png" border="false":::. - -> [!div class="mx-imgBorder"] -> ![Screenshot of backlog items and parent items owned by other teams, Azure DevOps Server 2019 version.](media/multi-ownership/customer-service-backlog-parents-on.png) - -> [!TIP] -> Add the **Node Name** field as a column to identify the area path/team associated with the work items. - -::: moniker-end - -::: moniker range="tfs-2018" - -Items that are owned by other teams appear with an information icon :::image type="icon" source="../../media/icons/info.png" border="false":::. - -> [!div class="mx-imgBorder"] -> ![Screenshot of backlog that shows parents and multi-team ownership, TFS 2018.](media/multi-ownership/customer-service-backlog-parents-on-prev-nav.png) - -> [!TIP] -> Add the **Node Name** field as a column to identify the area path/team associated with the work items. - -::: moniker-end - + -For more information, see [Define area paths and assign to a team](../../organizations/settings/set-area-paths.md). +For more information, see [Define area paths and assign to a team](../../organizations/settings/set-area-paths.md). ### View epics and child items owned by other teams -Here's another example that shows the **Epics** backlog for the **Management** team. -Drilling down, you can see all the backlog items and features, even though they -belong to one of three different teams: Customer Service, Phone, and Web. +Here's another example that shows the **Epics** backlog for the **Management** team. Drilling down, you can see all the backlog items and features, even though they belong to one of three different teams: Customer Service, Phone, and Web. ::: moniker range=">= azure-devops-2020" -> [!div class="mx-imgBorder"] -> ![Screenshot of view Epics and child items owned by other teams.](media/multi-ownership/management-team-backlog-epics-s155.png) +:::image type="content" source="media/multi-ownership/management-team-backlog-epics-s155.png" alt-text="Screenshot of view Epics and child items owned by other teams."::: ::: moniker-end -::: moniker range="azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Screenshot of view iew Epics and child items owned by other teams, Azure DevOps Server 2019 version.](media/multi-ownership/management-team-backlog-epics.png) + -::: moniker-end +From these views, you can reparent items that you own and items other teams own. You can't reorder items that another team owns. -::: moniker range="tfs-2018" +This organization enables management teams to focus on high-level features and epics, and development teams to focus on just the backlog items they're responsible to deliver. For example, you can create a team structure similar to this one with two management and three development teams. For more information, see [Create or add a team](../../organizations/settings/add-teams.md). -Here's another example that shows the **Epics** backlog for the **Management** team. -Drilling down, you can see all the backlog items and features, even though they -belong to one of three different teams: Customer Service, Phone, and Web. +:::image type="content" source="media/ALM_OB_MultiTeam_C.png" alt-text="Diagram shows backlogs and multi-team ownership with a division between management and development teams."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of view Epics backlog for the Management team, TFS 2018.](media/multi-ownership/management-team-backlog-epics-pre-nav.png) +For more information about hierarchical team and backlog structures, see [Manage your product and portfolio backlogs](../plans/portfolio-management.md). -::: moniker-end +> [!IMPORTANT] +> You have the flexibility to establish child links with work items from different projects. However, if the processes differ between projects, the hierarchy won't be visible on the backlog for those child items that reside in the separate projects. Nonetheless, you can view all of the associated child items directly on the work item form. -From these views, you can re-parent items, both those that you own and those owned by other teams. -However, you can't reorder items that another team owns. +### Reordering and reparenting work items -This organization enables management teams to focus on high-level features and epics, and development teams -to focus on just the backlog items they're responsible to deliver. +All backlogs and boards support dragging to reorder and reparent work items. Updates made to one team's backlogs and boards are reflected in other team backlogs and boards that share the same area path. You might need to refresh the page to view the changes. -To make this work for you, you'll need to [add teams and set their area paths](../../organizations/settings/add-teams.md). -For example, you can create a team structure similar to this one with two management and three development teams. +You can only use dragging to reorder or reparent work items assigned to area paths selected for your team. When the **Parents** view option is enabled, work items might appear on your backlog that your team doesn't own. Anything that appears with the :::image type="icon" source="../../media/icons/info.png" border="false"::: information icon can't be reordered or reparented because another team owns it. -![Conceptual image of backlogs and multi-team ownership.](media/ALM_OB_MultiTeam_C.png) +:::image type="content" source="../plans/media/config-teams/information-message-owned-by-other-team.png" alt-text="Screenshot of information message on team ownership."::: -To learn more about hierarchical team and backlog structures, see [Portfolio management](../plans/portfolio-management.md). + -### Reordering and reparenting work items +## Display leaf node work items -All backlogs and boards support dragging to reorder and reparent work items. Updates made to one team's backlogs and boards are reflected in other team backlogs and boards that share the same area path. You may need to refresh the page to view the changes. +Sprint backlogs and Taskboards only show the last node in a same-category hierarchy, called the *leaf node*. -You can only use dragging to reorder or reparent work items assigned to area paths selected for your team. When the **Parents** view option is enabled, work items may appear on your backlog that your team doesn't own. Anything that appears with the :::image type="icon" source="../../media/icons/info.png" border="false"::: information icon can't be reordered nor reparented as it's owned by another team. - -:::image type="content" source="../plans/media/config-teams/information-message-owned-by-other-team.png" alt-text="Screenshot of information message on team ownership."::: +[!INCLUDE [describe leaf node](../includes/display-leaf-nodes.md)] - +## Product backlog controls -## Display leaf node work items +You can use the following controls to change or filter your product backlog view. -For TFS 2018 and earlier versions, the Kanban board only shows the leaf node with nested items of a same-category hierarchy. For all versions, sprint backlogs and Taskboards only show the last node in a same-category hierarchy, called the leaf node. +> [!IMPORTANT] +> If you turn the **In Progress** control off, items that are in the *Active*, *Committed*, or *Resolved* states or in the In Progress category workflow state don't appear in the backlog. For more information about category workflow states, see [About workflow states in backlogs and boards](../work-items/workflow-and-state-categories.md). -[!INCLUDE [temp](../includes/display-leaf-nodes.md)] +::: moniker range="<=azure-devops" +For more information about using each of these controls, see [Configure your backlog view](configure-your-backlog-view.md). +::: moniker-end -## Permissions and access +:::row::: + :::column span=""::: + **Icon or Link** + :::column-end::: + :::column span=""::: + **Control** + :::column-end::: + :::column span="2"::: + **Function** + :::column-end::: +:::row-end::: +--- +:::row::: + :::column span=""::: + **Backlog** + :::column-end::: + :::column span=""::: + + :::column-end::: + :::column span="2"::: + [Switch to backlog view](create-your-backlog.md) + :::column-end::: +:::row-end::: +::: moniker range=">= azure-devops-2020" +:::row::: + :::column span=""::: + **Analytics** + :::column-end::: + :::column span=""::: + + :::column-end::: + :::column span="2"::: + [Switch to Analytics in-context reports](../../report/dashboards/overview.md#work-tracking-analytics) + :::column-end::: +:::row-end::: +::: moniker-end +:::row::: + :::column span=""::: + :::image type="icon" source="../../media/icons/backlogs.png" border="false"::: + :::column-end::: + :::column span=""::: + Backlog selector + :::column-end::: + :::column span="2"::: + [Switch backlog view](create-your-backlog.md) +:::row-end::: +::: moniker range=">= azure-devops-2020" +:::row::: + :::column span=""::: + :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: + :::column-end::: + :::column span=""::: + View options + :::column-end::: + :::column span="2"::: + - [Turn Parents on/off](organize-backlog.md) (Not available for top-level portfolio backlog) + - [Turn Forecasting on/off](../sprints/forecast.md) (Only available on product backlog) + - [Turn In Progress items on/off](create-your-backlog.md#show-hide-in-progress) + - [Turn Completed child items on/off](create-your-backlog.md#show-hide-completed) + - [Show Mapping](organize-backlog.md) (Not available for top-level portfolio backlog) + - [Show Planning](../sprints/assign-work-sprint.md) + :::column-end::: +:::row-end::: +::: moniker-end -As a member added to the Contributors group of a project, you can use most features provided under **Boards** or **Work**. Users with Basic access have full access to all features. Users with Stakeholder access are limited to certain features. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). +:::row::: + :::column span=""::: + :::image type="icon" source="../media/icons/filter-icon.png"::: + :::column-end::: + :::column span=""::: + Filter + :::column-end::: + :::column span="2"::: + [Turn filtering On/Off](filter-backlogs-boards-plans.md) + :::column-end::: +:::row-end::: +:::row::: + :::column span=""::: + :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: + :::column-end::: + :::column span=""::: + Settings + :::column-end::: + :::column span="2"::: + [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) + :::column-end::: +:::row-end::: +:::row::: + :::column span=""::: + :::image type="icon" source="../../media/icons/full-screen-icon.png"::: / :::image type="icon" source="../../media/icons/exit-full-screen-icon.png"::: + :::column-end::: + :::column span=""::: + Full screen + :::column-end::: + :::column span="2"::: + Enter or exit full screen mode + :::column-end::: +:::row-end::: +:::row::: + :::column span=""::: + :::image type="icon" source="../media/icons/expand_icon.png"::: / :::image type="icon" source="../media/icons/collapse_icon.png"::: + :::column-end::: + :::column span=""::: + Expand/Collapse + :::column-end::: + :::column span="2"::: + Expand or collapse one level of the tree hierarchy + :::column-end::: +:::row-end::: +:::row::: + :::column span=""::: + :::image type="icon" source="../../media/icons/actions-icon.png"::: + :::column-end::: + :::column span=""::: + More commands + :::column-end::: + :::column span="2"::: + - [Set column options](set-column-options.md) + - [Create Query](../queries/organize-queries.md) + - [Send email](../work-items/email-work-items.md) + :::column-end::: +:::row-end::: +--- -To learn more about permissions and access, see [Permissions and access for work tracking](../../organizations/security/permissions-access-work-tracking.md) and [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). +> [!NOTE] +> Even if you have the "Show Parents" option turned on, the **Create Query** and **Email** :::image type="icon" source="../media/icons/mail_icon.png"::: controls only list items at the currently selected level. -To add users to a project, see [Add users to a project or team](../../organizations/security/add-users-team-project.md). +## Permissions and access -[!INCLUDE [temp](../includes/add-portfolio-backlogs.md)] +As a member added to the Contributors group of a project, you can use most features provided under **Boards** or **Work**. Users with Basic access have full access to all features. Users with Stakeholder access are limited to certain features. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -## Next steps +For more information about permissions and access, see [Set work tracking permissions](../../organizations/security/permissions-access-work-tracking.md) and [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -If you're just getting started, see [Start using Azure Boards](../get-started/index.md). +To add users to a project, see [Add users to a project or team](../../organizations/security/add-users-team-project.md). -## Related articles +[!INCLUDE [add portfolio backlogs and boards](../includes/add-portfolio-backlogs.md)] -- [Web portal navigation](../../project/navigation/index.md) -- [About Kanban and Agile project management](../boards/kanban-overview.md) -- [About work items](../work-items/about-work-items.md) -- [What is Agile?](/devops/plan/what-is-agile) -- [What is Agile development?](/devops/plan/what-is-agile-development) -- [Agile culture](/devops/plan/adopting-agile) +## Next steps +> [!div class="nextstepaction"] +>[Sign up for Azure Boards](../get-started/index.md) - +## Related articles +- [Navigate the web portal](../../project/navigation/index.md) +- [Learn about Kanban boards](../boards/kanban-overview.md) +- [Discover what Agile is](/devops/plan/what-is-agile) diff --git a/docs/boards/backlogs/best-practices-product-backlog.md b/docs/boards/backlogs/best-practices-product-backlog.md deleted file mode 100644 index 6e971ec194a..00000000000 --- a/docs/boards/backlogs/best-practices-product-backlog.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Best practices for backlog management in Azure Boards -titleSuffix: Azure Boards -description: Learn best practices to manage and refine your product backlog in Azure Boards. -ms.custom: "boards-backlogs, seodec18" -ms.service: azure-devops-boards -ms.assetid: CCAE5254-A5F9-41CC-967E-7104BD36B932 -ms.author: chcomley -author: chcomley -ms.topic: best-practice -monikerRange: '<= azure-devops' -ms.date: 10/08/2021 ---- - -# Backlog management in Azure Boards - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -A great backlog conveys customer needs and value. Over the course of the project, your team adds detailed information to each backlog item, break them down into smaller items, prioritize, and estimate them, and finally, -implement them and deliver the results to your customers. - -To get started, see [Create your backlog](create-your-backlog.md). - - - -## Role of the product owner - -Product owners play an important role in Scrum, primarily as the interface between customers and the team. To enable product owners to fulfill the following responsibilities, they need to be added to the Contributors group. - -* Analyzing customer requirements and express them as user stories, features, or requirements -* Building, prioritizing, and refining the product backlog -* Representing customer and stakeholder requirements to the team and responding to questions your team has about them -* Meeting regularly with stakeholders to address their needs and keep them informed -* Helping stakeholders understand the decisions underlying the priority order of your backlog -* Responding to all requests from your team for more information concerning backlog priorities and requirements - -If they'll also be responsible for configuring team settings, [add them as a team administrator](../../organizations/settings/add-team-administrator.md). - -A product owner can reduce the need for detailed specifications by being more responsive to the team's questions about implementation details and clearly expressing acceptance criteria within each requirement. - - - - -## Acceptance criteria - -Acceptance criteria define what "Done" means by describing the conditions that the team should use to verify whether a requirement or bug fix has been fully implemented. You can capture these criteria in the work item. Clear acceptance criteria help with estimating and developing requirements and with testing. - -Product owners are the ultimate deciders of the criteria that create customer value. - -> **Tips from the trenches: Start to love and embrace acceptance criteria.** -> -> Ask 10 mature agile teams "How do you know when you're "done done"? -> and you'll get the same answer from each one. . . get serious about writing acceptance criteria. -> -> Acceptance criteria are the handshake between the product owner and the team on what "done done" really means. -> Until the acceptance criteria are met, the team isn't done with the story. Period. -> However, the value of acceptance criteria only starts here. -> -> Acceptance criteria provide the stage for some of most meaningful conversations and interactions -> that can happen on an agile team. On my own team we routinely have some of our best interactions as -> we start digging into the acceptance criteria for each story on our backlog. -> Inevitably we all start with our own ideas about what "done" means for a given story. -> -> However, as we begin to discuss the acceptance criteria presented by the product owner what -> ensues is a series of "ah-ha moments." -> A shared understanding of the story begins to emerge. A comment one team member might elicit -> the following response from someone else. . . "Ah-ha, great point. . . I never thought of that." -> -> Regardless of who is being enlightened, the power is in the fact that the product owner and -> the team are building together a shared understanding of what "done" means for each backlog item. -> And, this is happening before the team has written a single line of code… before any work has been done… -> before commitments have been made… and before the sprint has begun. -> -> By collaborating on acceptance criteria the team is minimizing risk and greatly increasing the chance of delivering successfully. -> I don't think it's a coincidence that the first bullet in the -> [Agile Manifesto](https://agilemanifesto.org/) states ". . . we have come to value -> **individual and interactions** over processes and tools". -> Agile teams work together. And by working together, they create better software. -> -> Start learning to love acceptance criteria and see if your team isn't more successful delivering software. -> -> —Aaron Bjork, Principal Product Manager, Visual Studio Cloud Services - - - - - -## Refine your backlog - -Backlog refinement supports your sprint planning efforts and helps minimize these often seen challenges: - -* Long, unfocused, and ineffective sprint planning meetings -* Insufficient thought given to design requirements -* Poor sprint planning and execution -* Defocus on the business value team wants to achieve -* Inability to forecast - -A meeting to refine the backlog should occur separate from the sprint planning meeting. Use this meeting to complete these activities: -* Right-size backlog items by splitting larger items into smaller items. No backlog item should be larger than it takes to complete in a single sprint. -* Identify and fill in gaps in the product backlog. Capture new ideas and stories, architecture and design requirements, and other spikes. -* Reorder the backlog to represent today's priorities and business value focus. -* Ensure well-defined acceptance criteria has been added to each item. -* Revisit estimates made to backlog items and adjust upwards or downwards based on recent understanding about scope and acceptance criteria. -* Review all potential backlog items to consider for the upcoming sprint to make sure they're well understood and that any other work required to support their development is well understood by both product owner and the team. - -You'll know that you've done a good job refining your backlog when your sprint planning meetings run smoothly and efficiently. Such meetings shouldn't contain many surprises, and your team should feel they can contribute fully. - - - - - -## Capture and manage spikes - -Also, to new features and requirements to build, you can capture non-feature work that still needs to be done for a healthy ecosystem of delivery. This work can include necessary research, design, exploration, or prototyping. Any work done that doesn't directly lead to shippable software can be considered and captured as a spike. - -As the need to do this work arises, capture it along with other items on your backlog. To track that it's a spike, you can either preface the title with the word "[Spike]" or add the tag "Spike" to the work item. - -## Other resources - -- [What is Agile?](/devops/plan/what-is-agile) -- [Building productive, customer focused teams](/devops/plan/building-productive-teams) diff --git a/docs/boards/backlogs/bulk-modify-work-items.md b/docs/boards/backlogs/bulk-modify-work-items.md index 1e68e280f7e..96f2f7986d4 100644 --- a/docs/boards/backlogs/bulk-modify-work-items.md +++ b/docs/boards/backlogs/bulk-modify-work-items.md @@ -1,15 +1,16 @@ --- -title: Edit user stories and other work items in bulk in Azure Boards +title: Edit user stories and other work items in bulk titleSuffix: Azure Boards -description: Learn how to quickly make the same change to many work items in Azure Boards using the bulk modify feature. +description: Learn how to make the same change to many work items in Azure Boards using the bulk modify feature in Azure Boards. ms.service: azure-devops-boards -ms.custom: "boards-backlogs, seodec18, linked-from-support" -ms.assetid: 152CAFE0-2360-470A-98AC-F613A67C24D2 +ms.custom: boards-backlogs, linked-from-support +ms.assetid: 152CAFE0-2360-470A-98AC-F613A67C24D2 ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 10/18/2024 +#customer intent: As a team lead, I want to learn how to make changes to multiple work items at once to assign items to team members or sprints. --- # Modify work items in bulk in Azure Boards @@ -18,27 +19,20 @@ ms.date: 04/01/2022 Use bulk modify when you need to quickly make the same change to many work items. For example, you might want to change the priority of several bugs or reassign several tasks to the same team member. Use the web portal to quickly modify one or more fields for work items that contain the same value. -> [!TIP] -> To add work items in bulk or update multiple fields with different values, use [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). You can't complete a bulk add of work items through the web portal. +> [!TIP] +> To add work items in bulk or update multiple fields with different values, use [CSV Import](../queries/import-work-items-from-csv.md). You can't complete a bulk add of work items through the web portal. -With bulk modify, you may edit fields and add or remove tags. You can also reassign work or move work to a specific sprint. You can also use bulk modify to change the work item type or move work items to other projects. The options available to you depend on the platform you work from and the permissions you've been granted. +With bulk modify, you can edit fields and add or remove tags. You can also reassign work or move work to a specific sprint. You can also use bulk modify to change the work item type or move work items to other projects. The options available to you depend on the platform you work from and the permissions assigned to you. -In this article you'll learn: +## Prerequisites -> [!div class="checklist"] -> * How to multi-select work items from a list and open the context menu -> * Edit one or more fields of several work items -> * Assign work from a backlog to a sprint using drag-and-drop -> * Add or remove tags from several work items - - -[!INCLUDE [temp](../includes/prerequisites-work-items.md)] +[!INCLUDE [prerequisites](../includes/prerequisites-work-items.md)] ## Supported tasks -All of the following actions can be completed by team members that belong to the Contributors group. Members provided with Stakeholder access can run multi-select, bulk edit, change type, email, and copy as HTML/copy to clipboard actions. For more information, see [Work as a stakeholder](../../organizations/security/get-started-stakeholder.md). +Team members who belong to the Contributors group can complete the following tasks. Members provided with Stakeholder access can run multi-select, bulk edit, change type, email, and copy as HTML/copy to clipboard actions. For more information, see [Get started as a Stakeholder](../../organizations/security/get-started-stakeholder.md). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: @@ -63,8 +57,8 @@ All of the following actions can be completed by team members that belong to the Link work items :::column-end::: :::column span="1"::: - - [Link to a new item](add-link.md#link) - - [Link to an existing item](add-link.md#link) + - [Link to a new item](add-link.md) + - [Link to an existing item](add-link.md) - [New branch](connect-work-items-to-git-dev-ops.md)1 :::column-end::: :::row-end::: @@ -73,7 +67,7 @@ All of the following actions can be completed by team members that belong to the Bulk edit/update/delete :::column-end::: :::column span="1"::: - - [Edit field(s)](#edit) + - [Edit fields](#edit) - [Assign to](#assign-to) - [Move to iteration](#move-iteration) - [Change position](create-your-backlog.md#move-items-priority-order) @@ -81,7 +75,6 @@ All of the following actions can be completed by team members that belong to the - [Add/remove tags](#tags) - [Update from template](work-item-template.md)1 - [Delete](remove-delete-work-items.md#delete) 1 - :::column-end::: :::row-end::: :::row::: @@ -90,222 +83,124 @@ All of the following actions can be completed by team members that belong to the :::column-end::: :::column span="1"::: - [Clone or copy a single item](copy-clone-work-items.md#copy-clone) 2 - - [Copy as HTML/Copy to clipboard](copy-clone-work-items.md#html) - - [Email selected item(s)](../queries/share-plans.md) + - [Copy as HTML/Copy to clipboard](copy-clone-work-items.md) + - [Send email with selected items](../work-items/email-work-items.md) - [Change work item type](move-change-type.md#change-type)1 - [Move items to another project](move-change-type.md#move)1, 3 :::column-end::: :::row-end::: - > [!NOTE] -> 1. You can't perform certain functions on work items whose WITs belong to the [Hidden Types Category](../work-items/agile-glossary.md#hidden-types). This includes all work items that track tests—such as test cases, shared steps, and shared parameters—code review requests and responses, and feedback requests and responses. -> 2. You can choose to copy or clone a single work item from a query results list or from the [Actions menu of the work item form](remove-delete-work-items.md). You can only perform a clone or copy action for a single work item. Choose Copy work item when you want to create a copy of a work item and change its work item type. Choose Clone when you want to create another instance of the work item without changes to its work item type. -> 3. You must be a member of the Project Administrators group or be granted explicit permissions to [**Move work items**](../../organizations/security/set-permissions-access-work-tracking.md#move-delete-permissions). +> - You can't perform certain functions on work items whose [work item types](../work-items/about-work-items.md) belong to the [hidden types category](../work-items/agile-glossary.md#hidden-types). This category includes all work items that track tests (such as test cases, shared steps, and shared parameters), code review requests and responses, and feedback requests and responses. +> - You can choose to copy or clone a single work item from a query results list or from the [Actions menu of the work item form](remove-delete-work-items.md). You can only perform a clone or copy action for a single work item. Choose Copy work item when you want to create a copy of a work item and change its work item type. Choose Clone when you want to create another instance of the work item without changes to its work item type. +> - Be a member of the Project Administrators group or be granted explicit permissions to [**Move work items**](../../organizations/security/set-permissions-access-work-tracking.md#move-delete-permissions). ::: moniker-end - -::: moniker range="tfs-2018" - -:::row::: - :::column span="1"::: - **Area** - :::column-end::: - :::column span="1"::: - **Task** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Multi-select work items - :::column-end::: - :::column span="1"::: - - [Multi-select-query results](#multi-select) - - [Multi-select-backlog](#multi-select) - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Link work items - :::column-end::: - :::column span="1"::: - - [Link to a new item](add-link.md#link) - - [Link to an existing item](add-link.md#link) - - [New branch](connect-work-items-to-git-dev-ops.md)1 - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Bulk edit/update/delete - :::column-end::: - :::column span="1"::: - - [Edit field(s)](#edit) - - [Assign to](#assign-to) - - [Move to iteration](#move-iteration) - - [Change position](create-your-backlog.md#move-items-priority-order) - - [Change parent](organize-backlog.md#reparent) - - [Add/remove tags](#tags) - - [Update from template](work-item-template.md)1 - - [Delete](remove-delete-work-items.md#delete) 1 - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Copy, clone, or email work items - :::column-end::: - :::column span="1"::: - - [Clone or copy a single item](copy-clone-work-items.md#copy-clone) 2 - - [Copy as HTML/Copy to clipboard](copy-clone-work-items.md#html) - - [Email selected item(s)](../queries/share-plans.md) - - :::column-end::: -:::row-end::: - -> [!NOTE] ->1. You can't perform certain functions on work items whose WITs belong to the [Hidden Types Category](../work-items/agile-glossary.md#hidden-types). This includes all work items that track tests—such as test cases, shared steps, and shared parameters—code review requests and responses, and feedback requests and responses. ->2. You can choose to copy or clone a single work item from a query results list or from the [Actions menu of the work item form](remove-delete-work-items.md). You can only perform a clone or copy action for a single work item. Choose Copy work item when you want to create a copy of a work item and change its work item type. Choose Clone when you want to create another instance of the work item without changes to its work item type. ->3. For on-premises Azure DevOps, you must have an [SMTP server configured for your deployment](/azure/devops/server/admin/setup-customize-alerts). - - - - - -## Edit multiple work items in bulk +## Edit multiple work items in bulk -To start a bulk edit, begin by multi-selecting the work items you want to modify, either from the query results or the backlog. You can craft your query using the [query editor or search box](../queries/using-queries.md). +To start a bulk edit, begin by multi-selecting the work items you want to modify. Select them from query results or the backlog. You can craft your query using the query editor or search box. For more information, see [Define a work item query](../queries/using-queries.md). -Multi-select of work items on the backlog and sprint backlogs works in the same way as multi-select works within query results. +Multi-select of work items on the backlog and sprint backlogs works in the same way as multi-select works within query results. -You can use bulk modify by selecting work items from the backlog page or query results list. From the backlog page context menu, change the backlog priority of several items (Change position or Move to position). Then, assign them to a team member, move them to a different sprint, or [map them to a feature](organize-backlog.md#mapping). +You can use bulk modify by selecting work items from the backlog page or query results list. From the backlog page context menu, change the backlog priority of several items: **Change position** or **Move to iteration**. Then, assign them to a team member, move them to a different sprint, or [map them to a feature](organize-backlog.md#mapping). The menu options available to you change depending on the platform you work from and whether you work from a backlog page or query results list. :::row::: :::column span="1"::: **Backlog menu** - - ![Screenshot of Backlog multi-select menu.](media/bulk-m-backlog-menu-options-ts.png) + + :::image type="content" source="media/bulk-m-backlog-menu-options-ts.png" alt-text="Screenshot of Backlog multi-select menu."::: :::column-end::: :::column span="1"::: **Query results multi-select menu** - - ![Screenshot of Query results multi-select menu.](media/bulk-m-query-results-menu-options-ts.png) + + :::image type="content" source="media/bulk-m-query-results-menu-options-ts.png" alt-text="Screenshot of Query results multi-select menu."::: :::column-end::: :::row-end::: -::: moniker-end +### Select multiple items and open the context menu -### Select multiple items and open the context menu +To select several items in a sequence, select the first item of the sequence, hold down **Shift**, and select the last item of the sequence. To select several nonsequential items, hold down **Ctrl** and select the items to be selected one after the other. You can either drag the selected items to a new position within the backlog or to a different sprint if the `Planning` side pane is enabled. -To select several items in a sequence, hold down the shift key. To select several non-sequential items, use the Ctrl key. Then, you can either drag the selected items to a new position within the backlog, to a different sprint. +To open the context menu, select (:::image type="icon" source="../media/icons/actions-icon.png" border="false":::) or (:::image type="icon" source="../media/icons/context_menu.png":::), and then choose the option from the menu. -To open the context menu, select ( :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: ) or (![context icon](../media/icons/context_menu.png)), and then choose the option from the menu. +This example uses the context menu to move several nonsequential items to the current sprint. -Here, we use the context menu to move several non-sequential items to the current sprint. +::: moniker range="<=azure-devops" -::: moniker range=">= azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Screenshot of Product backlog, Open context menu, Move several backlog items to a different iteration.](media/bulk-modify/move-iteration.png) +:::image type="content" source="media/bulk-modify/move-iteration.png" alt-text="Screenshot of Product backlog context menu, where you can move several backlog items to a different iteration."::: ::: moniker-end -::: moniker range="tfs-2018" - -![Screenshot of Backlog page, multi-select items, Open context menu, Move to iteration.](media/bulk-modify-multi-select-ts.png) - -::: moniker-end - > [!TIP] > Use the backlog **Create Query** feature to create a query with the backlog items. You can then open the query within the web portal or [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) to perform additional bulk updates. - - + ## Reassign work items -With work items selected, open the context menu for any selected item, and reassign all of them. By doing reassigning them, you can quickly assign them to a member of your team or to another sprint or iteration. +With work items selected, open the context menu for any selected item, and reassign all of them. You can assign them to a member of your team or to another sprint or iteration at the same time. -> [!div class="mx-imgBorder"] -> ![Screenshot of Queries Results page, bulk modify, Assign to selection from More actions menu.](media/bulk-modify/assign-from-query.png) +:::image type="content" source="media/bulk-modify/assign-from-query.png" alt-text="Screenshot of Queries Results page where a context menu can assign work items to a team member."::: -To learn more about the *Assign To* and *Iteration Path* fields, see [Query by assignment, workflow, or Kanban board changes](../queries/query-by-workflow-changes.md#workflow-fields) and [Query by area or iteration path](../queries/query-by-area-iteration-path.md). +For more information about the *Assign To* and *Iteration Path* fields, see [Workflow and board fields](../queries/query-by-workflow-changes.md#workflow-fields) and [Query by area or iteration path](../queries/query-by-area-iteration-path.md). -## Edit one or more fields +## Edit one or more fields -To assign or modify several fields, choose Edit from the context menu of one of the selected work items. Enter a value for each field that you want to update. +To assign or modify several fields, choose **Edit** from the context menu of one of the selected work items. Enter a value for each field that you want to update. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -1. For audit purposes, you can type a description for your bulk update task. To learn more about each field, see the [Work item field index](../work-items/guidance/work-item-field.md). +1. For audit purposes, you can add a description for your bulk update task. For more information about each field, see the [Work item field index](../work-items/guidance/work-item-field.md). - > [!div class="mx-imgBorder"] - > ![Screeenshot of Edit work items dialog.](media/bulk-modify/edit-work-items-new-text-editor.png) + :::image type="content" source="media/bulk-modify/edit-work-items-new-text-editor.png" alt-text="Screenshot of Edit work items dialog."::: -2. From the Query results page, you must save all work items that you bulk-modified. When you bulk modify items from the backlog, they're automatically saved. Work items shown in bold text indicate that local changes haven't yet been saved to the data store. The **Save items** button may be in a different place in the UI than shown in the picture below, depending on the layout of your browser and the specific version in use. +1. From the Query results page, save all work items that you bulk-modified. When you bulk modify items from the backlog, they're automatically saved. Work items shown in bold text indicate that local changes aren't saved to the data store. The **Save items** button might be in a different place in the UI than shown in the following picture, depending on the layout of your browser and the specific version in use. - > [!div class="mx-imgBorder"] - > ![Screenshot of Query results page, save bulk modified items.](media/bulk-modify/query-results-bulk-save-items.png) + :::image type="content" source="media/bulk-modify/query-results-bulk-save-items.png" alt-text="Screenshot of Query results page with Save items selected."::: ::: moniker-end -::: moniker range="tfs-2018" - -1. For audit purposes, you can type a description for your bulk update task. To learn more about each field, see the [Work item field index](../work-items/guidance/work-item-field.md). - - !Screenshot of Query results page, bulk edit fields.](media/bulk-modify-edit-fields-ts.png) - -2. From the Query results page, you must save all work items that you bulk-modified. When you bulk modify items from the backlog, they're automatically saved. Work items shown in bold text indicate that local changes haven't yet been saved to the data store. - - ![Screenshot of Query results page, save bulk modified items, TFS 2018.](media/bulk-modify-save-ts.png) - -::: moniker-end - -[!INCLUDE [temp](../includes/assign-to-sprint.md)] - +[!INCLUDE [move work items to sprint](../includes/assign-to-sprint.md)] ## Modify rich-text fields in bulk -Rich-text fields support entry of HTML syntax tags to support formatting. Rich-text fields correspond to the **Description**, **Acceptance Criteria**, **Repos Steps**, and others listed in [Query samples for select fields](../queries/query-index-quick-ref.md#sample-queries-for-select-fields). +Rich-text fields support entry of HTML syntax tags to support formatting. Rich-text fields correspond to the **Description**, **Acceptance Criteria**, **Repos Steps**, and others listed in [Example queries for select fields](../queries/query-index-quick-ref.md#example-queries-for-select-fields). -You can bulk update a rich-text field by using the bulk modify tool, selecting the field, and entering the text with syntax in the **Value** field. Or, you can create a work item template with the text you want to use and complete a bulk update by applying the template to the selected work items. For details on using work item templates, see [Use templates to add and update work items](work-item-template.md) +You can bulk update a rich-text field by using the bulk modify tool, selecting the field, and entering the text with syntax in the **Value** field. Or, you can create a work item template with the text you want to use and complete a bulk update by applying the template to the selected work items. For more information, see [Use work item templates](work-item-template.md). -For a worked example using templates showing entry of HTML formatted syntax, see [Sample work item templates, Add guidance in a rich-text field](../work-items/work-item-template-examples.md#rich-text). +For an example using templates showing entry of HTML formatted syntax, see [Sample work item templates, Add guidance in a rich-text field](../work-items/work-item-template-examples.md#rich-text). ## Modify tags in bulk -From the Edit work items dialog, select **Tags (Add)** or **Tags (Remove)**. - - -Here we choose to add the *Service* tag to the selected work items. +From the **Edit work items** dialog, select **Tags (Add)** or **Tags (Remove)**. -> [!div class="mx-imgBorder"] -> ![Screenshot of Edit work items dialog, Add tags.](media/bulk-modify/edit-tags-dialog.png) +This example adds the *Service* tag to the selected work items. +:::image type="content" source="media/bulk-modify/edit-tags-dialog.png" alt-text="Screenshot of Edit work items dialog where you can add tags."::: ## Related articles To add fields or customize a work item form, see [Customize your work tracking experience](../../reference/customize-work.md). The method you use depends on the process model that supports your project. -### Migrate or change a large number of work items +### Migrate or change a large number of work items -For large scale, organizational moves, use the REST API calls for [Work item batch operations](/rest/api/azure/devops/wit/work%20items#operations). +For large scale, organizational moves, use the REST API calls for [Work item batch operations](/rest/api/azure/devops/wit/work%20items#operations). -At this time, you can't move work items to a different organization or collection. You can only migrate work item information by exporting and then importing them using [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). +At this time, you can't move work items to a different organization or collection. You can only migrate work item information by exporting and then importing them using [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). ### Add multiple values to a field -If you have implemented a [custom control that supports multiple values](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-extensions-multivalue-control), you can use Excel to bulk edit the field, but you can't modify it using the web portal. In the web portal, you can only select a single value for the field. +If you implemented a [custom control that supports multiple values](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-extensions-multivalue-control), you can use Excel to bulk edit the field. You can't modify it using the web portal. You can only select a single value for the field. diff --git a/docs/boards/backlogs/configure-your-backlog-view.md b/docs/boards/backlogs/configure-your-backlog-view.md index a2e655e9f68..a0fd1a019f7 100644 --- a/docs/boards/backlogs/configure-your-backlog-view.md +++ b/docs/boards/backlogs/configure-your-backlog-view.md @@ -4,53 +4,72 @@ titleSuffix: Azure Boards description: Learn how to set your backlog level, view options, and column options to support your project management tasks in Azure Boards and Azure DevOps. ms.custom: boards-backlogs ms.service: azure-devops-boards +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: how-to -monikerRange: '>= azure-devops-2019' -ms.date: 10/27/2022 +monikerRange: "<=azure-devops" +ms.date: 11/22/2024 --- # Configure your backlog view in Azure Boards [!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] -Your backlogs are designed to support many project management tasks. Chief among them are: -- Define work to be done -- Prioritize work -- Group work into a hierarchical view -- Assign work to iterations -- Forecast work +Backlogs in Azure DevOps are essential tools that support a wide range of project management tasks. They enable teams to: -Each backlog—product or portfolio—is a tool you share with your team members. When you add backlog items, prioritize items, or link work items using parent-child links, team members see the changes when they refresh their backlog. +- **Define work to be done**: Outline and document the tasks and deliverables required for project completion. +- **Prioritize work**: Order work items based on their importance and urgency to ensure the most critical tasks are addressed first. +- **Organize work hierarchically**: Group related tasks into parent-child relationships for better structure and clarity. +- **Assign work to iterations**: Allocate tasks to specific timeframes or sprints to manage project phases effectively. +- **Forecast work**: Predict project progress and identify potential bottlenecks to maintain timely delivery. -To effectively perform select tasks, it's good to know how to set your view options to support those tasks. +Each backlog—whether it's a **product** or **portfolio** backlog—is a shared resource accessible to all team members. When you add backlog items, set priorities, or establish parent-child links between work items, these changes are instantly visible to the entire team upon refreshing their backlog view. -> [!TIP] -> You can't sort your backlog on a column. To view a sorted listed, select **Create query** from your backlog. Save and open the query. Modify the query if needed to be a flat list query. You can then sort the query results. To learn more about queries, see [Use the query editor to list and manage queries](../queries/using-queries.md). +To maximize the effectiveness of your backlog management, it's crucial to configure your view options in a way that aligns with your team's workflow and project requirements. + +## Prerequisites +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Permissions** | Member of the **Contributors** group. | +| **Access levels** | - To reorder a backlog or use the Forecast tool: At least **Basic** access. Users with **Stakeholder** access can't reorder backlog items or use the Forecast tool. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). | +| **Configured backlogs** | Both product and portfolio backlogs set up for your team. | + +> [!TIP] +> You can't sort your backlog directly by clicking on a column header. To view a sorted list, select **Create query** from your backlog. Save and open the query, then modify it to a flat list query if needed to apply sorting to the results. For more information about queries, see [Use the query editor to list and manage queries](../queries/using-queries.md). ## Backlog configuration options -You have the following tools to configure your backlog view: **Expand/Collapse one level**, **Column Options**, **Backlog level selector**, **View options**, and **Filter** toolbar. The options you set for each backlog level—stories, features, epics (Agile process) or product backlog items, features, epics (Scrum process)—are distinct. The options you set persist until you change them. - :::image type="content" source="media/configure-view-options/customization-tools.png" alt-text="Screenshot showing the four types of Backlog configuration tool options."::: +You can customize your backlog view using the following tools: + +- **Expand/collapse one level** +- **Column options** +- **Backlog level selector** +- **View options** +- **Filter toolbar** -### Expand and collapse the hierarchy +Each backlog level—such as stories, features, and epics (Agile process) or product backlog items, features, and epics (Scrum process)—has its own set of configurable options. These settings remain in effect until you decide to change them. -The default view when you select a backlog level is to show the collapsed view. Only those items associated with the backlog level selected are shown. You can expand and collapse the hierarchy by using the ![expand icon](../media/icons/expand_icon.png) and collapse ![collapse icon](../media/icons/collapse_icon.png) icons to expand or collapse one level of the hierarchy. Your selection doesn't persist once you switch to a different page or view. +:::image type="content" source="media/configure-view-options/customization-tools.png" alt-text="Screenshot showing the four types of Backlog configuration tool options."::: + +### Expand and collapse the hierarchy + +When you select a backlog level, it defaults to a **collapsed view**, displaying only the items associated with that specific level. To view more details, use the ![expand icon](../media/icons/expand_icon.png) and ![collapse icon](../media/icons/collapse_icon.png) icons to expand or collapse one level of the hierarchy. This action allows you to navigate through the work item structure as needed. Your expand/collapse selections don't persist when you switch to a different page or view. > [!div class="mx-imgBorder"] -> ![Screenshot of Expand/Collapse icons that show/hide a hierarchical view.](media/configure-view-options/expand-collapse.png) - +> ![Screenshot of Expand/Collapse icons that show/hide a hierarchical view.](media/configure-view-options/expand-collapse.png) -### Backlog level selector +### Use backlog levels -The number of backlog levels available to you are set by your team administrator and may have been customized to add custom work item types or backlog levels. Each backlog automatically applies the filters associated with the **Area Paths** and **Iteration Paths** selected for the team. +The number of backlog levels available to you gets determined by your team administrator and might include custom work item types or other backlog levels tailored to your team's needs. Each backlog automatically applies the filters associated with the **Area paths** and **Iteration paths** selected for the team. > [!NOTE] -> Prior to using the tools described in this article, we recommend that you review [Set up your project's backlogs and boards](set-up-your-backlog.md) to ensure you have configured your backlog to support your team's needs. +> Before using the tools described in this article, we recommend reviewing [Set up your project's backlogs and boards](set-up-your-backlog.md) to ensure your backlog configurations support your team's requirements. + +From the **Backlogs** page, you can choose between a **Product Backlog** or a **Portfolio backlog**. To select a backlog, use the backlog level selector located next to the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options** icon. The labels within this selector vary based on the process model selected for your project, any customizations made to that process, and configurations set by your team administrator, as illustrated in the following images. -From the **Backlogs** page, you can select the product backlog or a portfolio backlog. You select a backlog from the backlog level selector next to the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options** icon. The labels within this selector vary depending on the process selected for your project, customization made to that process, and configurations made by your team administrator as shown in the following images. :::row::: :::column span="1"::: **Agile process** @@ -81,8 +100,7 @@ From the **Backlogs** page, you can select the product backlog or a portfolio ba For information on team configuration of backlog levels, see [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md). - -### View options menu +### Use the view options menu The :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options** menu controls the following options. @@ -93,18 +111,12 @@ The :::image type="icon" source="../../media/icons/view-options-icon.png" border :::column-end::: :::column span="3"::: - **Parents**: Show the hierarchical grouping of parent-child work items. Useful when adding child work items, reparenting a work item, or displaying rollup columns. - - - **Forecasting**: Show the **Forecast** tool and forecast lines. The **Forecast** option only appears for the first-level backlog and depends on the assignment of **Story Points**, **Effort**, or **Size**. - - - **In Progress Items**: Show items whose workflow **State** corresponds to an *In Progress* workflow state category. If you turn the **In Progress** control off, then items that are in the *Active*, *Committed*, or *Resolved* states or a custom workflow state defined in the In Progress state category won't appear in the backlog. To learn more about category workflow states, see [How to use workflow states and state categories](../work-items/workflow-and-state-categories.md). - - - **Completed Child Items**: Show child items that have been completed. Typically you turn this **On** when reviewing reviewing a rollup column. - + - **Forecasting**: Show the **Forecast** tool and forecast lines. The **Forecast** option only appears for the first-level backlog and depends on the assignment of **Story points**, **Effort**, or **Size**. + - **In progress items**: Show items whose workflow **State** corresponds to an *In progress* workflow state category. If you turn the **In progress** control off, then items that are in the *Active*, *Committed*, or *Resolved* states or a custom workflow state defined in the In progress state category don't appear in the backlog. For more information about category workflow states, see [How to use workflow states and state categories](../work-items/workflow-and-state-categories.md). + - **Completed child items**: Show child items that are completed. Typically turn it **On** when reviewing a rollup column. - **Keep hierarchy with filters**: Maintain the backlog hierarchy when filtering. - - - **Mapping**: Shows the **Mapping** pane to support drag-and-drop linking of work items to parent items. The **Mapping** option doesn't appear when you've selected the highest backlog level configured for your team. - - - **Planning**: Shows the **Planning** pane to support drag-and-drop of work items to **Iteration Paths**. + - **Mapping**: Shows the **Mapping** pane to support drag-and-drop linking of work items to parent items. The **Mapping** option doesn't appear when you select the highest backlog level configured for your team. + - **Planning**: Shows the **Planning** pane to support drag-and-drop of work items to **Iteration paths**. :::column-end::: :::row-end::: ::: moniker-end @@ -116,94 +128,97 @@ The :::image type="icon" source="../../media/icons/view-options-icon.png" border :::column-end::: :::column span="3"::: - **Parents**: Show the hierarchical grouping of parent-child work items. Useful when adding child work items, reparenting a work item, or displaying rollup columns. - - - **Forecasting**: Show the **Forecast** tool and forecast lines. The **Forecast** option only appears for the first-level backlog and depends on the assignment of **Story Points**, **Effort**, or **Size**. - - - **In Progress Items**: Show items whose workflow **State** corresponds to an *In Progress* workflow state category. If you turn the **In Progress** control off, then items that are in the *Active*, *Committed*, or *Resolved* states or a custom workflow state defined in the In Progress state category won't appear in the backlog. To learn more about category workflow states, see [How to use workflow states and state categories](../work-items/workflow-and-state-categories.md). - - - **Completed Child Items**: Show child items that have been completed. Typically you turn this **On** when reviewing reviewing a rollup column. - - - **Mapping**: Shows the **Mapping** pane to support drag-and-drop linking of work items to parent items. The **Mapping** option doesn't appear when you've selected the highest backlog level configured for your team. - - - **Planning**: Shows the **Planning** pane to support drag-and-drop of work items to **Iteration Paths**. + - **Forecasting**: Show the **Forecast** tool and forecast lines. The **Forecast** option only appears for the first-level backlog and depends on the assignment of **Story points**, **Effort**, or **Size**. + - **In progress items**: Show items whose workflow **State** corresponds to an *In progress* workflow state category. If you turn the **In progress** control off, then items that are in the *Active*, *Committed*, or *Resolved* states or a custom workflow state defined in the In progress state category don't appear in the backlog. For more information about category workflow states, see [How to use workflow states and state categories](../work-items/workflow-and-state-categories.md). + - **Completed child items**: Show child items that are completed. Typically you turn it **On** when reviewing a rollup column. + - **Mapping**: Shows the **Mapping** pane to support drag-and-drop linking of work items to parent items. The **Mapping** option doesn't appear when you select the highest backlog level configured for your team. + - **Planning**: Shows the **Planning** pane to support drag-and-drop of work items to **Iteration paths**. :::column-end::: :::row-end::: ::: moniker-end -### Filter bar +### Use the filter toolbar -Turn on filtering when you want to find one or more work items based on a keyword, tag, assignment, or other field you display using **Column Options**. You enable the filter feature by choosing :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: **Filter**. +Enable filtering to locate specific work items based on criteria such as keywords, tags, assignments, or other fields configured via **Column options**. To activate the filter feature, select the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: **Filter** icon. -:::image type="content" source="media/configure-view-options/filter-toolbar.png " alt-text="Screenshot of backlog filter toolbar."::: +:::image type="content" source="media/configure-view-options/filter-toolbar.png" alt-text="Screenshot of backlog filter toolbar."::: -Filtering displays a flat list of all items in the hierarchy when you have selected to show **Parents**. The hierarchical grouping is restored once you dismiss the filter toolbar. The filter toolbar persists until you dismiss it. +When filtering is active, the backlog displays a flat list of all work items, even if **Parents** is enabled to show hierarchical groupings. The hierarchical view is temporarily suspended until you disable the filter toolbar. The filter toolbar remains visible until you close it. -For more information, see [Filter backlogs, boards, and plans](filter-backlogs-boards-plans.md). +For more information, see [Filter backlogs, boards, and plans](filter-backlogs-boards-plans.md). ::: moniker range="azure-devops" ## Filter your backlog and maintain the hierarchy -You can filter your backlog and maintain the hierarchy of work by choosing show **Parents** and **Keep hierarchy with filters** from the **View Options** menu. +You can filter your backlog and maintain the hierarchy of work by choosing show **Parents** and **Keep hierarchy with filters** from the **View options** menu. :::image type="content" source="media/filter/keep-hierarchy-with-filters.png" alt-text="Screenshot of View options menu, Keep hierarchy with filters selected."::: -Use these options when you want to show work items assigned to one or more team members, work item types, area or iteration paths, or combination of these and keywords. The hierarchy is maintained and work items that match the filter criteria are shown in bold text. +Use these options when you want to show work items assigned to one or more team members, work item types, area or iteration paths, or combination of these options and keywords. The hierarchy is maintained and work items that match the filter criteria are shown in bold text. ::: moniker-end -## Define backlog items +## Add work items quickly -It's useful to be able to add work items quickly and refine details later when more information becomes available. Often you use a query to help [triage work](../queries/triage-work-items.md) added to the backlog to review, refine, and add details to work items that you entered through your backlog. +Efficiently adding work items allows you to capture tasks swiftly and refine their details as more information becomes available. Utilize queries on your backlog to triage, review, refine, and enhance work items added through your backlog. -To quickly define many items to a backlog, perform the following steps. +1. Choose the backlog level where you want to add new work items. -1. Select the backlog level that you want to add items to. -1. From the **View options** menu, turn the slider for **Parents** and **Forecasting** to **Off**. -1. (Optional) turn **In Progress Items** on or off. -1. (Optional) Minimize the number of columns displayed on your backlog, or select those fields you want to view. -1. Choose :::image type="icon" source="../../media/icons/blue-add-icon.png" border="false"::: **New Work Item**, enter a title, choose **Add to top** or **Add to bottom**, and then press **Enter**. We recommend you add items to the bottom of the backlog if your team has a process for prioritizing backlog items. - +2. From the **View options** menu, toggle the sliders for **Parents** and **Forecasting** to **Off**, which simplifies the view by hiding hierarchical groupings and forecasting tools. + +3. (Optional settings:) + - **In progress items**: Turn this option on or off based on whether you want to display items currently in progress. + - **Column display**: Minimize the number of columns shown on your backlog or select specific fields you wish to display to streamline your view. + +4. Add new work items: + - Select the :::image type="icon" source="../../media/icons/blue-add-icon.png" border="false"::: **New work item** icon. + - Enter a title for the work item. + - Select **Add to Top** or **Add to Bottom**: + - **Recommendation**: Add items to the bottom of the backlog if your team prioritizes backlog items regularly. + - Select **Enter** to add the work item. + > [!div class="mx-imgBorder"] > ![Screenshot to Add a work item.](media/configure-view-options/add-backlog-item.png) - Work items are automatically assigned the default **Area Path** and **Iteration Path** selected for the team. - - > [!NOTE] - > If you have **Stakeholder** access , you can only add work items to the bottom of the backlog. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). - -1. Continue entering a **Title** and pressing the **Enter** key to define more backlog work items. + Work items are automatically assigned the default **Area path** and **Iteration path** configured for the team. + + > [!NOTE] + > If you have **Stakeholder** access, you can only add work items to the bottom of the backlog. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -For more information, see [Create your product backlog](create-your-backlog.md) and [Define features and epics](define-features-epics.md). +For more detailed instructions, see the following articles: +- [Create your product backlog](create-your-backlog.md) +- [Define features and epics](define-features-epics.md) ## Prioritize your product backlog -If your team follows Agile or Scrum methods, they'll want to prioritize the backlog to make sure that the most important work to complete is situated at the top of the backlog. To prioritize a backlog, follow these steps. +If your team follows Agile or Scrum methodologies, prioritizing the backlog ensures that the most important work items are addressed first. Follow these steps to effectively prioritize your backlog: -1. Select the backlog level you want to prioritize. -1. Turn the **Parents** view option **Off**. -1. Drag the work items up or down within the backlog. Or, if you prefer to use the keyboard, hold down the Alt key and use the up and down arrows. +1. Choose the backlog level you want to prioritize, for example, Stories, Features, Epics. - > [!div class="mx-imgBorder"] - > ![Screenshot showing Reorder work items.](media/configure-view-options/reorder-backlog.png) +2. From the **View options** menu, turn the **Parents** view option **Off** to simplify the view by hiding hierarchical groupings. - To reorder a backlog, you must have **Basic** or higher level access. If you have Stakeholder access, you can't reorder backlog items. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). +3. **Reorder work items**: + - **Drag and drop**: Select and drag work items up or down within the backlog to adjust their priority. + - **Keyboard shortcuts**: Alternatively, hold down the **Alt** key and use the up and down arrow keys to move work items. -> [!NOTE] -> Changes you make to the priority impact all backlog items. When other team members refresh their backlog, they'll see the new priorities. A background process updates the [**Stack Rank** (Agile, Basic, and CMMI processes)](../queries/planning-ranking-priorities.md) or [**Backlog Priority** (Scrum process)](../queries/planning-ranking-priorities.md) fields. These fields are used by the system to track the relative ranking of items on the product, feature, epic, or other portfolio backlog. By default, these fields don't appear on the work item form. The priority ranking is assigned separately to each backlog level, which you can check by adding the field to a backlog and viewing a hiearchical list. - -Backlogs that participate in portfolio management or that contain nested same-type child items might not allow you to reorder the items. For more information, see these articles: -- [Backlogs, portfolios, and Agile project management, Work with multi-team ownership of backlog items](backlogs-overview.md#multi-team) + > [!div class="mx-imgBorder"] + > ![Screenshot showing Reorder work items.](media/configure-view-options/reorder-backlog.png) + +> [!NOTE] +> Changes you make to the priority of work items affect all team members. When others refresh their backlogs, the updated priorities display. A background process updates the [**Stack rank** (Agile, Basic, and CMMI processes)](../queries/planning-ranking-priorities.md) or [**Backlog priority** (Scrum process)](../queries/planning-ranking-priorities.md) fields. These fields track the relative ranking of items in the product, feature, epic, or other portfolio backlogs. By default, these fields do not appear on the work item form. Priority ranking is assigned separately for each backlog level, which you can verify by adding the field to a backlog and viewing it in a hierarchical list. + +Backlogs involved in portfolio management or containing nested same-type child items might restrict the reordering of items. For more information, see the following articles: +- [Backlogs, portfolios, and Agile project management: Work with multi-team ownership of backlog items](backlogs-overview.md#multi-team) - [Fix reordering and nesting issues](resolve-backlog-reorder-issues.md) ## Prioritize a portfolio backlog The method for prioritizing a portfolio backlog is similar to that described for a product backlog. The main difference is that you prioritize child items within each portfolio item. Each backlog level—**Stories**, **Features**, **Epics**—supports priority ordering distinct from every other level. - **Prioritize the portfolio items:** 1. Select the portfolio backlog level you want to prioritize. -1. Turn the **Parents** view option **Off**. +1. Turn **Off** the **Parents** view option. 1. Drag the work items up or down within the backlog. 2. Within each item, you can expand to see child items and drag these items into priority order. @@ -211,85 +226,84 @@ The method for prioritizing a portfolio backlog is similar to that described for 1. Expand each portfolio item. 1. Drag each child item up or down within the expanded item. +### Link work items to a parent (mapping) -> [!NOTE] -> To reorder a backlog, you must have **Basic** or higher level access. If you have Stakeholder access, you can't reorder backlog items. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). - -## Link work items to a parent (mapping) +You can quickly link one or more work items to a parent portfolio item by dragging them within your backlog view. -You can drag items to quickly link one or several work items to a parent portfolio item. - > [!TIP] -> Prior to opening mapping work items, add the portfolio backlog items you want to link work items to and prioritize them. The **Mapping** pane lists the portfolio backlog items in priority order. +> Before mapping work items, add and prioritize the portfolio backlog items you want to link to. The **Mapping** pane lists portfolio backlog items in priority order. -1. Select the backlog level you want to link to parent items. For example, choose **Stories** to link to **Features**. -1. Open :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options** and choose **Mapping**. - The Mapping pane opens. By default, the pane lists the next-level up portfolio items for the current team. -1. (Optional) To map items to parent items owned by a different team, choose it from the team selector in the **Mapping** pane as shown in the following image. - :::image type="content" source="media/configure-view-options/mapping-pane-selector.png" alt-text="Screenshot of Team selector in Mapping pane."::: -1. Drag work items from the backlog to the portfolio item listed in the **Mapping** pane. - The system creates a parent-child link in the background. The backlog item turns bold and then unbold as the system saves the changes. +1. Choose the backlog level where you want to link work items, for example, **Stories** to link to **Features**. + +2. Select :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options**. +3. Select **Mapping** to open the Mapping pane. By default, the pane lists the next-level portfolio items for the current team. + +4. (Optional) To map items to parent items owned by a different team, select the desired team from the team selector in the **Mapping** pane. + + :::image type="content" source="media/configure-view-options/mapping-pane-selector.png" alt-text="Screenshot of Team selector in Mapping pane."::: + +5. Drag work items from the backlog and drop them onto the desired portfolio item in the **Mapping** pane. + + The system automatically creates a parent-child link. The backlog item's text turns bold briefly as the system saves the changes. - Note, you can select multiple backlog items and drag them to a portfolio item. To select several items in a sequence, hold down the shift key. To select several non-sequential items, use the **Ctrl** key. Then, you can drag the selected items. + You can select multiple work items to drag at once: + - **Sequential selection**: Hold down the **Shift** key to select a range of items. + - **Non-sequential selection**: Hold down the **Ctrl** key to select individual items. + - Drag the selected items to create links. -1. (Optional) You can also drag a backlog item within the expanded hierarchical view to reparent a work item. +6. (Optional) Within an expanded hierarchical view, you can also drag a work item to a different parent to reparent it. ::: moniker range=">= azure-devops-2020" -> [!TIP] -> To view the work items that are unparented, you can add the **Parent** field as a column. The **Title** of the parent item is listed for those items that have been linked to a parent. +> [!TIP] +> To view work items that are unparented, add the **Parent** field as a column. The **Title** of the parent item will be listed for work items that have been linked to a parent. ::: moniker-end For more information, see [Organize your backlog and map child work items to parents](organize-backlog.md). - ## Add child items to a portfolio backlog item 1. Select the portfolio backlog level, such as **Features**, that you want to add items to. -1. Choose :::image type="icon" source="../../media/icons/blue-add.png" border="false"::: **Add User Story, Bug** for the feature you want to add the child item to as shown in the following image. Your labels may differ based on process and customizations. - +1. Select :::image type="icon" source="../../media/icons/blue-add.png" border="false"::: **Add User Story, Bug** for the feature you want to add the child item to as shown in the following image. Your labels might differ based on process and customizations. 1. In the work item form that appears, enter a **Title** and any other required fields or details. Save the work item to close it. For more information, see [Define features and epics, add child items](define-features-epics.md#add-child-items). - ## View or find unparented work -To view or find unparented work: - 1. Select the backlog level you want to inspect for unparented items. -1. Open **View options** and choose **Parents**. -1. Scroll to the bottom of the backlog and expand **Unparented Stories**, **Unparented Features**, or similar entries. Unparented work items are listed under these entries. - :::image type="content" source="media/configure-view-options/unparented-stories.png" alt-text="Screenshot of Unparented stories."::: - +2. Open **View options** and select **Parents**. +3. Scroll to the bottom of the backlog and expand **Unparented Stories**, **Unparented Features**, or similar entries. Unparented work items are listed under these entries. + + :::image type="content" source="media/configure-view-options/unparented-stories.png" alt-text="Screenshot of Unparented stories."::: ## Assign work to a sprint or iteration -Similar to using the **Mapping** pane, you can use the **Planning** pane to assign one or more work items to an **Iteration Path** or sprint. +Similar to using the **Mapping** pane, you can use the **Planning** pane to assign one or more work items to an **Iteration path** or sprint. -1. Make sure all **Iteration Paths** have been selected for your team that you want to show in the **Planning** pane. +1. Ensure all **Iteration paths** are selected for your team that you want to show in the **Planning** pane. 1. Choose the backlog level that contains the work items you want to assign. -1. Open **View options**, turn off **Completed Child Items** and choose **Planning**. +1. Open **View options**, turn **Off** **Completed child items** and choose **Planning**. 1. Drag work items from the backlog to the portfolio item listed in the **Mapping** pane. - The system creates a parent-child link in the background. The backlog item turns bold and then unbold as the system saves the changes. + The system creates a parent-child link in the background. The backlog item turns bold and then unbold as the system saves the changes. - Note, you can select multiple backlog items and drag them to a portfolio item. To select several items in a sequence, hold down the shift key. To select several non-sequential items, use the **Ctrl** key. Then, you can drag the selected items. + You can select multiple backlog items and drag them to a portfolio item. To select several items in a sequence, hold down the shift key. To select several nonsequential items, use the **Ctrl** key. Then, you can drag the selected items. :::image type="content" source="media/configure-view-options/assign-sprint-planning-pane.png" alt-text="Screenshot showing drag of a backlog item to a Planning pane sprint."::: - ## Forecast a backlog -The **Forecast** tool is only available for the product backlog. Use these steps to forecast your backlog. To use the **Forecast** tool, you must have **Basic** or higher level access. This feature isn't available to users granted **Stakeholder** access. +The **Forecast** tool is only available for the product backlog. To forecast your backlog, do the following steps: -1. Make sure that future **Iteration Paths** have been selected for your team. +1. Ensure that future **Iteration paths** are selected for your team. 2. Choose the backlog level for your team. -3. (Optional) Add the **Story Points**, **Effort**, or **Size** field as a column based on the process your project uses. -3. Open **View options** and turn off **Parents** and **In Progress** items, and **Completed Child Items**. Turn on **Forecast**. -4. Enter a velocity estimate in the **Forecasting based on velocity** of box. -5. Review the forecast lines that appear, similar to the ones shown in the following image. +3. (Optional) Add the **Story points**, **Effort**, or **Size** field as a column based on the process your project uses. +4. Open **View options** and turn **Off** the **Parents**, **In progress** items, and **Completed child items**. Turn **On** the **Forecast** option. +5. Enter a velocity estimate in the **Forecasting based on velocity** box. +6. Review the forecast lines that appear, similar to the ones shown in the following image. :::image type="content" source="../sprints/media/forecast-s125.png" alt-text="Screenshot of backlog showing Forecast lines."::: - The forecast tool doesn't reference any iteration assignments made to the product backlog items. + + The forecast tool doesn't reference any iteration assignments made to the product backlog items. > [!TIP] > You can drag items to reprioritize them with forecast lines shown. You can also use the **Planning** pane with the **Forecast** tool turned on. @@ -298,23 +312,28 @@ For more information, see [Forecast your product backlog](../sprints/forecast.md ::: moniker range="azure-devops" -## Review progress made to your backlog +### Add rollup columns + +Enhance your backlog view by adding rollup columns such as a **Progress bar**, **Work item count**, or the **Sum** of any integer or numeric field. These columns let you: + +- Monitor progress: Visualize the completion status of parent work items based on their child items. +- Track workload: View the number of work items associated with each parent item. +- Aggregate Data: Calculate the total value of numeric fields, for example, Story Points and Effort, for better project tracking. -You can add a rollup progress bar, count of work items, or sum of any integer or numeric field as a column to the backlog. This option allows you to review progress made to parent work items based on the completion of their child items. These child items can be Tasks for User Stories, User Stories and Bugs for Features, or Features for Epics. +Parent work items can include: +- **User Stories** with child **Tasks** +- **Features** with child **User Stories** and **Bugs** +- **Epics** with child **Features** -1. Select the backlog level you want to view progress on -1. Open **View options**, show **Completed Child Items** -1. Open **Column Options**, choose **Add a rollup column**, and select the progress bar or count to display. +1. Select the backlog level you want to view progress on. +2. Open **View options** to show **Completed Child Items**. +3. Open **Column options**, choose **Add a rollup column**, and select the progress bar or count to display. :::image type="content" source="media/configure-view-options/progress-feature.png" alt-text="Screenshot of Scenario backlog showing Rollup column for Progress by Feature."::: - It can take several moments for the progress bar or count to appear. - -For more information, see [Display rollup progress or totals](display-rollup.md). + It can take several moments for the progress bar or count to appear. For more information, see [Display rollup progress or totals](display-rollup.md). - ::: moniker-end - ## Related articles diff --git a/docs/boards/backlogs/connect-work-items-to-git-dev-ops.md b/docs/boards/backlogs/connect-work-items-to-git-dev-ops.md index 3a06299c04c..4528db951e5 100644 --- a/docs/boards/backlogs/connect-work-items-to-git-dev-ops.md +++ b/docs/boards/backlogs/connect-work-items-to-git-dev-ops.md @@ -1,84 +1,68 @@ --- -title: Drive Git development from user story and requirements -titleSuffix: Azure Boards -description: Learn how to create a branch, commit, or a pull request in Azure Boards. Also, automatically link work items with source control branches, builds, and commits. -ms.custom: "boards-backlogs, seodec18" +title: Drive Git development from work items +titleSuffix: Azure Boards +description: Learn how to create a branch, commit, or a pull request in Azure Boards. Also, automatically link work items with source control branches, builds, and commits. +ms.custom: boards-backlogs ms.service: azure-devops-boards -ms.assetid: BD7CE3C1-9E15-4BD6-B9CD-F78569C74D0D +ms.assetid: BD7CE3C1-9E15-4BD6-B9CD-F78569C74D0D +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 07/26/2022 +ms.date: 11/22/2024 --- # Drive Git development from a work item in Azure Boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -One of the ways your team can drive their development and stay in sync is to link your work items to the objects created during development, such as branches, commits, pull requests, and builds. You can begin that linking by creating a branch from one or more work items. Later, you can create pull requests, quickly open commits, and maintain a record of development operations performed to complete specific work. +Linking your work items to development objects such as branches, commits, pull requests, and builds is a powerful way to drive development and keep your team synchronized. By creating branches directly from work items, you establish a clear connection between tasks and code changes. As development progresses, you can associate pull requests and commits with these work items, ensuring a comprehensive record of the operations performed to complete specific work. -Review this article to learn: - ->[!div class="checklist"] -> * How to create a new branch or pull request from a work item -> * Complete the pull request -> * Perform a squash merge -> * Create a branch for several work items -> * Link a work item to existing development and build objects - - -::: moniker range=">= azure-devops-2019" -This article addresses creating new branches, adding links to commits, and adding pull requests to a Git repository hosted on Azure DevOps. To link to GitHub commits and pull requests, see [Link GitHub commits and pull requests to work items](../github/link-to-from-github.md). -::: moniker-end +This article covers how to create new branches, add links to commits, and manage pull requests in a Git repository hosted on Azure DevOps. For instructions on linking GitHub commits and pull requests to work items, see [Link GitHub commits and pull requests to work items](../github/link-to-from-github.md). > [!TIP] -> You can set up automatic linking and other settings that link work items to Git commits, pull requests, builds, and more. To learn how, see the following resources: -> - [Configure repositories and branches to integrate with work tracking](../../repos/git/configure-repos-work-tracking.md?toc=/azure/devops/boards/toc.json) +> You can set up automatic linking and other settings that link work items to Git commits, pull requests, builds, and more. For more information, see the following resources: +> - [Cross-service overview](../../cross-service/cross-service-overview.md#azure-boards-and-azure-repos-integration) > - [Configure pipelines to support work tracking](../../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/boards/toc.json) -> - [Link and view work items to builds and deployments](../work-items/work-item-deployments-control.md). +> - [Link work items to builds and deployments](add-link.md#link-work-items-to-deployments). ## Development control -The **Development** control records all Git development processes that support completion of the work item. This control can show your team information needed to take the next development step and minimize navigational steps to accomplish common development tasks. It also supports traceability, providing visibility into all the branches, commits, pull requests, and builds related to the work item. +The **Development** control tracks all Git development activities that contribute to the completion of a work item. It provides your team with the necessary information to take the next development steps, minimizing the need for multiple navigational actions to accomplish common tasks. Additionally, it enhances traceability by displaying all related branches, commits, pull requests, and builds associated with the work item, ensuring comprehensive visibility into the development process. ::: moniker range=">= azure-devops-2020" :::image type="content" source="media/git/development-control.png" alt-text="Screenshot of work item form, Development control."::: ::: moniker-end -::: moniker range="azure-devops-2019" -:::image type="content" source="media/git/development-control-2019.png" alt-text="Screenshot of work item form, Development control, Azure DevOps Server 2019."::: -::: moniker-end - -::: moniker range="tfs-2018" -![Screenshot of work item form, Development control, TFS 2018.](media/drive-git-development-dev-section.png) -::: moniker-end - - +From the **Development** control, you can quickly access branches, pull requests, and commits linked to the work item. Additionally, you can initiate a pull request for a branch you created or linked directly from the work item. -From it, you can quickly access branches, pull requests, and commits which are linked to the work item. Also, you can start a pull request for a branch you've created or linked to from the work item. - -Keep in mind that the **Development** control only appears within the web portal work item form. The work item tracking experience and forms that appear in Visual Studio or other supported clients don't display several of the features that are available from the web portal. +> [!NOTE] +> The **Development** control is only available within the web portal's work item form. The work item tracking experience and forms in Visual Studio or other supported clients do not display several features available in the web portal. ## Prerequisites ::: moniker range="azure-devops" -* Connect to a project. If you don't have a project yet, [create one](../get-started/sign-up-invite-teammates.md). -* You must be added to a project as a member of the **Contributors** or **Project Administrators** security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To view or modify work items, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Permissions** | Member of the **Contributors** or [**Project Administrators**](../../organizations/security/add-users-team-project.md) group. | +| **Access levels** | - To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). | +|**Access levels** |To reorder a backlog or use the Forecast tool: At least [**Basic** access](../../organizations/security/access-levels.md). Users with **Stakeholder** access can't reorder backlog items or use the Forecast tool. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). | ::: moniker-end ::: moniker range="< azure-devops" -* Connect to a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -* You must be added to a project as a member of the **Contributors** or **Project Administrators** security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To view or modify work items, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Permissions** | Member of the **Contributors** or [**Project Administrators**](../../organizations/security/add-users-team-project.md) group. | +| **Access levels** | - To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). | ::: moniker-end - ## Workflow process @@ -87,74 +71,68 @@ Consider creating a new branch when there are no linked code artifacts. If a bra 1. Start work on the work item by creating a branch. You can add a new Git branch from within the Development section... - ::: moniker range=">= azure-devops-2019" - :::image type="content" source="media/git/development-control-git-github-create-branch.png" alt-text="Screenshot of Development control, Create branch link."::: - ::: moniker-end - ::: moniker range="< azure-devops-2019" - User story work item form, Development section, create new branch - ::: moniker-end + :::image type="content" source="media/git/development-control-git-github-create-branch.png" alt-text="Screenshot of Development control, Create branch link."::: - ... or, from the form's :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu. + ... or, from the form's :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu. - :::image type="content" source="media/git/actions-menu-new-branch-option.png" alt-text="User story work item form, Action menu, add new branch."::: + :::image type="content" source="media/git/actions-menu-new-branch-option.png" alt-text="Screenshot shows User story work item form, Action menu, add new branch."::: - Name the branch and select the repository on which it's based. + Name the branch and select the repository. - Create a branch dialog box + ![Screenshot shows Create a branch dialog box.](media/git/git-dev-create-branch.png) - Branches you create are automatically linked to the work item. + When you create branches, they automatically get linked to the work item. > [!NOTE] > You can only create a branch once you've added files to the main branch, which we recommend you label ```main``` or other distinctive label. The system automatically adds a README file to the initial repo created with each new project. -2. The system opens to the repository and branch that you created. + The system opens to the repository and branch that you created. - You can edit a file within the web portal. +2. You can edit a file within the web portal. - Or, if you have extensive file edits or need to add files, then you'll need to work from Visual Studio or other supported IDE. You'll want to add a new local branch from the branch you created. For more information, see [Update code with fetch and pull, Download changes with fetch](../../repos/git/pulling.md#download-changes-with-fetch). (While any code editing and committing process works, we work best with an edition of Visual Studio.) + Or, if you have extensive file edits or need to add files, work from Visual Studio or other supported IDE. Add a new local branch from the branch you created. For more information, see [Update code with fetch and pull, Download changes with fetch](../../repos/git/pulling.md#download-changes-with-fetch). (While any code editing and committing process works, we work best with an edition of Visual Studio.) 3. Add or modify files in the branch that you created. From Visual Studio or other supported IDE, commit and push changes from your local branch to the repository. - ![Commit and push changes](media/git/git-dev-commit-sync.png) + ![Screenshot shows Commit and push changes.](media/git/git-dev-commit-sync.png) - If this is the first time pushing changes from a new branch, you'll need to publish the branch before pushing your changes. For more information, see [Share code with push](../../repos/git/pushing.md). + If it's your first time pushing changes from a new branch, publish the branch before you push changes. For more information, see [Share code with push](../../repos/git/pushing.md). 4. Create a [pull request](../../repos/git/pull-requests.md) from the work item form. - You create a pull request to merge the changes you made to a main branch and get your changes reviewed by other members of your team. + Create a pull request to merge the changes you made to a main branch and get your changes reviewed by other members of your team. - :::image type="content" source="media/git/create-pull-request.png" alt-text="Screenshot of Development control, Create pull request link."::: + :::image type="content" source="media/git/create-pull-request.png" alt-text="Screenshot shows Development control, Create pull request link."::: -5. Your view switches to **Code**, Pull Requests page. Complete creating the pull request as shown. +5. Your view switches to **Code**, Pull Requests page. Complete creating the pull request as shown. - ![Code view, Pull Request page.](media/git/git-dev-create-pull-request.png) + ![Code view, Pull Request page.](media/git/git-dev-create-pull-request.png) - > [!NOTE] - > Once you've created a pull request, you can't create a new pull request for the same branch until you complete the previous pull request. + > [!NOTE] + > Once you've created a pull request, you can't create a new pull request for the same branch until you complete the previous pull request. - ![Pull Request page, Create pull request.](media/git/git-dev-pr-complete.png) + ![Screenshot shows Pull Request page, Create pull request.](media/git/git-dev-pr-complete.png) - Check the box for **Squash changes when merging** and then complete the merge. + Check the box for **Squash changes when merging** and then complete the merge. - ![Complete pull request dialog box, check squash-merge](media/git/git-dev-complete-merge.png) + ![Screenshot shows Complete pull request dialog box, check squash-merge.](media/git/git-dev-complete-merge.png) 6. Upon completion, you should see a similar screen as follows. > [!div class="mx-imgBorder"] - > ![Pull request, completed notification](media/git/git-dev-pr-completed.png) + > ![Screenshot shows Pull request, completed notification.](media/git/git-dev-pr-completed.png) -7. Open the work item form or refresh the form, expand the **Development** section (choose **Maximize Development** :::image type="icon" source="../media/icons/full-screen-icon.png" border="false":::), and you'll see the links that have been added to support the operations you completed. - - ![Work item form, Development section, links added](media/git/git-dev-development-section-completed-links.png) +7. Open the work item form or refresh the form, expand the **Development** section (choose **Maximize Development** :::image type="icon" source="../media/icons/full-screen-icon.png" border="false":::), and you see the links that were added to support the operations you completed. + ![Screenshot of Work item form, Development section, links added.](media/git/git-dev-development-section-completed-links.png) ## Create a branch for several work items -You can also add a new branch from the work item listed on the backlog or Kanban board without having to open the work item. Using [multi-select](bulk-modify-work-items.md), you can select several work items and create a new branch where they're all linked to the branch. +You can also add a new branch from the work item listed on the backlog or board without having to open the work item. Using [multi-select](bulk-modify-work-items.md), you can select several work items and create a new branch where they're all linked to the branch. For example, here we select the first five items to link to a new branch. @@ -162,8 +140,7 @@ For example, here we select the first five items to link to a new branch. And, we specify the name of the branch. -Create new branch dialog - +![Screenshot shows Create new branch dialog.](media/add-work-item-create-branch-multi-items.png) @@ -171,67 +148,49 @@ And, we specify the name of the branch. All items listed under the Development section also appear under the **Links** :::image type="icon" source="media/icon-links-tab-wi.png" border="false"::: tab. All development actions started from the Development section are also recorded under the **History** :::image type="icon" source="media/icon-history-tab-wi.png" border="false"::: tab. -![Links tab, development links](media/add-work-item-dev-links.png) +![Screenshot shows Links tab, development links.](media/add-work-item-dev-links.png) To link a work item to an existing object, choose the ![Add link](../media/icons/add-link-icon.png) Add links icon and then choose the link type. -![Select Add links icon and then choose the link type.](media/add-work-items-link-to-existing-branch.png) - -[Linking, traceability, and managing dependencies](../queries/link-work-items-support-traceability.md). - +![Screenshot shows select Add links icon and then choose the link type.](media/add-work-items-link-to-existing-branch.png) ### Remove a link If you want to remove a link, you can do so from the **Development** section by highlighting it first and then choose **Remove link** :::image type="icon" source="../media/icons/delete_icon.png" border="false":::. -![Development section, delete a link](media/add-work-item-remove-dev-link.png) +![Screenshot shows Development section, delete a link.](media/add-work-item-remove-dev-link.png) Or, you can select it from the **Links** :::image type="icon" source="media/icon-links-tab-wi.png" border="false"::: tab and choose **Actions** :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: for the link and then choose the **Remove link** :::image type="icon" source="../media/icons/delete_icon.png" border="false"::: option. -## Related articles - -- [Configure repositories and branches to integrate with work tracking](../../repos/git/configure-repos-work-tracking.md) -- [Configure pipelines to support work tracking](../../pipelines/integrations/configure-pipelines-work-tracking.md) -- [Add work items](add-work-items.md) -- [Git overview](../../repos/git/index.yml) -- [Link GitHub commits and pull requests to work items](../github/link-to-from-github.md) -- [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md) - ### Associated work items in build -With Git commits, any work items that have been linked to a commit are listed under the Associated work items in the build summary page. +With Git commits, any work items that were linked to a commit are listed under the Associated work items in the build summary page. Linked work items listed under Associated work items in the build summary page. - ### Link types showing in the Development section -Links shown in this section appear because of these actions: +Links shown in this section appear because of the following actions: - Creating a branch, commit, or pull request from the work item - Specifying the work item ID during a commit, pull request, or other supported Git or TFVC operation - Specifically linking the work item from the **Development** section or **Links** :::image type="icon" source="media/icon-links-tab-wi.png" border="false"::: tab to a source code branch, build, or other supported Git or TFVC operation. Hovering over any entry listed under the Development section activates the hyperlink to the associated object. -::: moniker range=">= azure-devops-2019" The link types you can add within the development section are Branch, Build, Changeset, Commit, Found in build, Integrated in build, Pull Request, and Versioned Item. -Artifact-to-artifact link types -::: moniker-end - -::: moniker range="tfs-2018" -The link types you can add within the development section are Branch, Build, Changeset, Commit, Pull Request, and Versioned Item. - -Artifact-to-artifact link types +![Screenshot shows Artifact-to-artifact link types.](../queries/media/link-tracking-artifact-to-artifact-link-types.png) -::: moniker-end +## Related articles -::: moniker range="<= azure-devops-2019" -To learn more about the links control or to customize the Development links control, see [LinksControlOptions elements, Development links control](/previous-versions/azure/devops/reference/xml/linkscontroloptions-xml-elements#development-links-control). - -::: moniker-end +- [Learn about Azure DevOps cross-service](../../cross-service/cross-service-overview.md) +- [Configure pipelines to support work tracking](../../pipelines/integrations/configure-pipelines-work-tracking.md) +- [Add work items](add-work-items.md) +- [Learn about Git](../../repos/git/index.yml) +- [Link GitHub commits and pull requests to work items](../github/link-to-from-github.md) +- [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md) diff --git a/docs/boards/backlogs/manage-bugs.md b/docs/boards/backlogs/manage-bugs.md index 5dd55363ae1..8150d1aac40 100644 --- a/docs/boards/backlogs/manage-bugs.md +++ b/docs/boards/backlogs/manage-bugs.md @@ -1,66 +1,61 @@ --- -title: Define, capture, triage, and manage bugs or code defects in Azure Boards -titleSuffix: Azure Boards -description: Define, capture, and triage bugs and code defects to manage technical debt and maintain software quality. -ms.custom: "boards-backlogs, contperf-fy21q4-portal" +title: Define, capture, triage, and manage bugs or code defects +titleSuffix: Azure Boards +description: Define, capture, and triage bugs and code defects to manage technical debt and maintain software quality. +ms.custom: boards-backlogs ms.service: azure-devops-boards ms.assetid: 6E5710EE-21C8-4264-AD65-A827D186F134 ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 08/03/2022 +ms.date: 10/18/2024 +#customer intent: As a team administrator, I want to manage how the team tracks bugs to provide a good workflow process. --- # Define, capture, triage, and manage software bugs in Azure Boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -How do you track and manage defects in your code? How do you make sure software problems and customer feedback get addressed quickly to support high-quality software deployments? And, how do you make good progress on new features and address your technical debt? +How do you track and manage defects in your code? How do you make sure software problems and customer feedback get addressed quickly to support high-quality software deployments? How do you make good progress on new features and address your technical debt? -At a minimum, you need a way to capture your software issues, prioritize them, assign them to a team member, and track progress. And, you want to manage your code defects in ways that align with your Agile practices. +At a minimum, you need a way to capture your software issues, prioritize them, assign them to a team member, and track progress. You want to manage your code defects in ways that align with your Agile practices. -To support these scenarios, Azure Boards provides a specific work item type to track code defects named Bug. Bug work items share all the standard features of other work item types with a few more. For an overview of standard features, see [Track work with user stories, issues, bugs, features, and epics](../work-items/about-work-items.md). +To support these scenarios, Azure Boards provides a specific work item type to track code defects named *Bug*. Bug work items share all the standard features of other work item types with a few more. For an overview of standard features, see [About work items and work item types](../work-items/about-work-items.md). -Bugs also provide the following additional features: +Bugs also provide the following features: -- Options for each team to choose how they want to track bugs -- Test tools to capture bugs +- Options for each team to choose how they want to track bugs +- Test tools to capture bugs - Built-in integration across Azure DevOps to track bugs linked to builds, releases, and tests +[!INCLUDE [no bugs in basic process](../includes/basic-process-bug-note.md)] -[!INCLUDE [temp](../includes/basic-process-bug-note.md)] +## Prerequisites - -[!INCLUDE [temp](../includes/prerequisites-work-items.md)] +[!INCLUDE [prerequisites](../includes/prerequisites-work-items.md)] > [!TIP] -> To report a bug, a user must have at a minimum, **Stakeholder** access and **Edit work items in this node** permission set to **Allow** for the **Area Path** where they add the bug. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md) +> To report a bug, a user must have at a minimum, **Stakeholder** access. A user must have **Edit work items in this node** permission set to **Allow** for the **Area Path** where they add the bug. For more information, see [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md) -## Bug work item type +## Bug work item type -The following image shows the Bug work item type for the Scrum process. The Bug work item type for Agile and CMMI processes tracks similar information. It's designed to appear on the product backlog along with requirements or on the Taskboard along with tasks. - -[!INCLUDE [temp](../includes/image-differences-with-wits.md)] +The following image shows the Bug work item type for the Scrum process. The Bug work item type for Agile and Capability Maturity Model Integration (CMMI) processes tracks similar information. It appears on the product backlog along with requirements or on the Taskboard along with tasks. -::: moniker range=">= azure-devops-2020" -> [!div class="mx-imgBorder"] -> ![Bug work item type, form for Scrum process, Azure DevOps Server 2020 and cloud service. ](media/manage-bugs/bug-work-item-type.png) -::: moniker-end +[!INCLUDE [image differences](../includes/image-differences-with-wits.md)] -::: moniker range="< azure-devops-2020" -![Screenshot of Bug work item type, form for Scrum process, Azure DevOps Server 2019 and TFS 2018.](media/manage-bugs-scrum-bug-from-ts.png) +::: moniker range=">= azure-devops-2020" +:::image type="content" source="media/manage-bugs/bug-work-item-type.png" alt-text="Screenshot shows a Bug work item type form for Scrum process in Azure DevOps Server 2020 and cloud service." lightbox="media/manage-bugs/bug-work-item-type.png"::: ::: moniker-end +## Fields specific to bugs -## Fields specific to bugs - -The Bug work item type uses some bug-specific fields. To capture both the initial issue and ongoing discoveries, use the fields described in the following table. For information about fields specific to the Bug defined for the Capability Maturity Model Integration (CMMI) process, see [Bugs, issues, and risks field reference](../work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md). For information about all other fields, see [Work item field index](../work-items/guidance/work-item-field.md). +The Bug work item type uses some bug-specific fields. To capture both the initial issue and ongoing discoveries, use the fields described in the following table. For information about fields specific to the Bug defined for the Capability Maturity Model Integration (CMMI) process, see [Bugs, issues, and risks field reference](../work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md). For information about all other fields, see [Work item field index](../work-items/guidance/work-item-field.md). --- :::row::: :::column span="1"::: - **Field, Group, or Tab** + **Field, Group, or Tab** :::column-end::: :::column span="3"::: **Usage** @@ -69,21 +64,21 @@ The Bug work item type uses some bug-specific fields. To capture both the initia --- :::row::: :::column span="1"::: - [Steps to Reproduce](../queries/titles-ids-descriptions.md) + [Steps to Reproduce](../queries/titles-ids-descriptions.md) (friendly name=Repro Steps) :::column-end::: :::column span="3"::: - Use to capture enough information so that other team members can fully understand the code defect. Include actions taken to find or reproduce the bug and expected behavior. + Use to capture enough information so that other team members can fully understand the code defect. Include actions taken to find or reproduce the bug and expected behavior. :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - [System Info](../queries/titles-ids-descriptions.md) - [Found In Build](../queries/build-test-integration.md) + [System Info](../queries/titles-ids-descriptions.md) + [Found In Build](../queries/build-test-integration.md) :::column-end::: :::column span="3"::: - Information about the software and system configuration that is relevant to the bug and tests to apply. The **System Info** and **Found in Build** fields are automatically filled in when you create a bug through a testing tool. These fields specify information about the software environment and build where the bug occurred. For more information, see [Test different configurations](../../test/test-different-configurations.md). + Information about the software and system configuration that is relevant to the bug and tests to apply. The **System Info** and **Found in Build** fields are automatically filled in when you create a bug through a testing tool. These fields specify information about the software environment and build where the bug occurred. For more information, see [Test different configurations](../../test/test-different-configurations.md). :::column-end::: :::row-end::: --- @@ -92,18 +87,20 @@ The Bug work item type uses some bug-specific fields. To capture both the initia [Acceptance Criteria](../queries/titles-ids-descriptions.md) :::column-end::: :::column span="3"::: - Provide the criteria to meet before the bug can be closed. Before work begins, describe the customer acceptance criteria as clearly as possible. Teams should use this criteria as the basis for acceptance tests, and to evaluate whether an item has been satisfactorily completed. + Provide the criteria to meet before the bug can be closed. Before work begins, describe the customer acceptance criteria as clearly as possible. Teams should use this criteria as the basis for acceptance tests and to evaluate whether an item is satisfactorily completed. :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - [Integrated in Build](../queries/build-test-integration.md) + [Integrated in Build](../queries/build-test-integration.md) :::column-end::: :::column span="3"::: - Specifies the name of the build that incorporates the code that fixes the bug. This field should be specified when you resolve the bug. - For on-premises Azure DevOps, to access a drop-down menu of all builds that have been run, you can update the `FIELD` definitions for **Found in Build** and **Integrated in Build** to reference a global list. The global list is automatically updated with each build that is run. For more information, see [Query based on build and test integration fields](../queries/build-test-integration.md). - For information about how to define build numbers, see [build number format options](../../pipelines/build/options.md). + Specifies the name of the build that incorporates the code that fixes the bug. This field should be specified when you resolve the bug. + + For on-premises Azure DevOps, to access a dropdown menu of all builds that have run, you can update the `FIELD` definitions for **Found in Build** and **Integrated in Build** to reference a global list. The global list is automatically updated with each build that is run. For more information, see [Query based on build and test integration fields](../queries/build-test-integration.md). + + For information about how to define build numbers, see [Classic pipelines configuration](../../pipelines/build/options.md). :::column-end::: :::row-end::: --- @@ -114,7 +111,7 @@ The Bug work item type uses some bug-specific fields. To capture both the initia :::column span="3"::: - **1**: Product requires successful resolution of the work item before it ships and addressed soon. - **2**: Product requires successful resolution of the work item before it ships, but doesn't need to be addressed immediately. - - **3**: Resolution of the work item is optional based on resources, time, and risk. + - **3**: Resolution of the work item is optional, based on resources, time, and risk. :::column-end::: :::row-end::: --- @@ -123,41 +120,39 @@ The Bug work item type uses some bug-specific fields. To capture both the initia [Severity](../queries/planning-ranking-priorities.md)1 :::column-end::: :::column span="3"::: - A subjective rating of the impact of a bug or work item on the project or software system. For example: If a remote link within the user interface—a rare event—causes an application or web page to crash—a severe customer experience, you might specify **Severity = 2 - High** and **Priority = 3**. Allowed values and suggested guidelines are: - - **1 - Critical**: Must fix. A defect that causes termination of one or more system components or the complete system, or causes extensive data corruption. And, there are no acceptable alternative methods to achieve required results. - - **2 - High**: Consider fix. A defect that causes termination of one or more system components or the complete system, or causes extensive data corruption. However, an acceptable alternative method exists to achieve required results. + A subjective rating of the impact of a bug or work item on the project or software system. For example: If a remote link within the user interface (a rare event) causes an application or web page to crash (a severe customer experience), you might specify **Severity = 2 - High** and **Priority = 3**. Allowed values and suggested guidelines are: + + - **1 - Critical**: Must fix. A defect that causes termination of one or more system components or the complete system, or causes extensive data corruption. There are no acceptable alternative methods to achieve required results. + - **2 - High**: Consider fix. A defect that causes termination of one or more system components or the complete system, or causes extensive data corruption. An acceptable alternative method exists to achieve required results. - **3 - Medium**: (Default) A defect that causes the system to produce incorrect, incomplete, or inconsistent results. - - **4 - Low**: A minor or cosmetic defect that has acceptable workarounds to achieve required results. + - **4 - Low**: A minor or cosmetic defect that has acceptable workarounds to achieve required results. :::column-end::: :::row-end::: --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: [Deployment](#deployment-control) :::column-end::: :::column span="3"::: - The **Deployment** control supports links to and display of releases that contain work items. To use the control, you must enable settings for the release. For more information, see [Link work items to releases](#deployment-control) later in this article. + The **Deployment** control supports links to and display of releases that contain work items. To use the control, you must enable settings for the release. For more information, see [Link work items to releases](#deployment-control) later in this article. :::column-end::: :::row-end::: --- ::: moniker-end :::row::: :::column span="1"::: - [Development](#development-control) + [Development](#development-control) :::column-end::: :::column span="3"::: - The **Development** control supports links to and display of links made to development objects. These objects include Git commits and pull requests, or TFVC changesets and versioned items. You can define links from the work item or from the commits, pull requests, or other development objects. For more information, see [Link work items to development](#development-control) later in this article. + The **Development** control supports links to and display of links made to development objects. These objects include Git commits and pull requests, or TFVC changesets and versioned items. You can define links from the work item or from the commits, pull requests, or other development objects. For more information, see [Link work items to development](#development-control) later in this article. :::column-end::: :::row-end::: --- +### Notes - -### Notes: - -1 To change the menu selection or picklist, see [Customize the work tracking experience](../../reference/customize-work.md). The customization method depends on the process model used by your project. - +1 To change the menu selection or picklist, see [Customize the work tracking experience](../../reference/customize-work.md). The customization method depends on the process model used by your project. ## Choose how your team tracks bugs @@ -165,127 +160,120 @@ Your team can track bugs as requirements or as tasks. To support the team choice - Size of your team. Smaller teams can maintain a lightweight footprint by tracking bugs as requirements. - Organization requirements to track work. If your team is required to track hours, then choose to track bugs as tasks. -- How your team organizes work. If your team relies on the product backlog to prioritize work and add bugs, track bugs as requirements. -- Tools your team wants to use such as the Planning pane, velocity chart, forecast, rollup, and delivery plans. Tracking bugs as tasks prevents use of several of these tools. +- Organization of your team's work. If your team relies on the product backlog to prioritize work and add bugs, track bugs as requirements. +- Tools your team wants to use such as the Planning pane, velocity chart, forecast, rollup, and delivery plans. Tracking bugs as tasks prevents use of several of these tools. -The following table summarizes the three options teams have to track bugs. To learn more and to set the option for your team, see [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). +The following table summarizes the three options teams have to track bugs. To learn more and to set the option for your team, see [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). -[!INCLUDE [temp](../includes/show-bugs-matrix-options.md)] +[!INCLUDE [bug track options](../includes/show-bugs-matrix-options.md)] -## Customize work item type +## Customize work item type -You can customize the Bug and other work item types. Or, create custom types to track software issues or customer feedback. With all work item types, you can customize the following elements: +You can customize the Bug and other work item types. Or, create custom types to track software issues or customer feedback. For all work item types, you can customize the following elements: -- Add or remove custom fields +- Add or remove custom fields - Add custom controls or custom tabs within the work item form -- Customize the workflow states -- Add conditional rules -- Choose the backlog level in which work items appear - -Before you customize your process, we recommend you review [Configure and customize Azure Boards](../configure-customize.md). +- Customize the workflow states +- Add conditional rules +- Choose the backlog level in which work items appear + +Before you customize your process, we recommend that you review [About configuring and customizing Azure Boards](../configure-customize.md). ::: moniker range="azure-devops" -To customize your particular process, see [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md). +To customize your particular process, see [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md). ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" -To customize your particular process, see [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md) or [Customize the On-premises XML process model](../../reference/on-premises-xml-process-model.md). +::: moniker range=" [!TIP] +> By default, the **Title** field is the only required field when you create a bug. You can add bugs in the same way you add user stories or product backlog items using Azure Boards. You can make some fields required by adding conditional rules based on a state change. For more information, see [Add a rule to a work item type](../../organizations/settings/work/custom-rules.md). + +### Add a bug from your backlog or board -## Add or capture bugs +If your team chose to *manage bugs with requirements*, you can define bugs from your product backlog or board. For more information, see [Create your product backlog](create-your-backlog.md) or [Use your board](../boards/kanban-quickstart.md). -You can define bugs from several different Azure DevOps tools. These include backlogs and boards and testing tools. +- **Add a bug from the product backlog** -> [!TIP] -> By default, the **Title** field is the only required field when creating a bug. You can quickly add bugs in the same way you add user stories or product backlog items using Azure Boards. If you want to make some fields required, do that by adding conditional rules based on a state change. For more information, see [Add a rule to a work item type (Inheritance process)](../../organizations/settings/work/custom-rules.md). + :::image type="content" source="media/manage-bugs/add-bug-from-backlog.png" alt-text="Screenshot shows adding a bug from the product backlog."::: -### Add a bug from your backlog or board +- **Add a bug from the board** -If your team chose to *manage bugs with requirements*, you can define bugs from your product backlog or Kanban board. For more information, see [Create your product backlog](create-your-backlog.md) or [Start using your Kanban board](../boards/kanban-quickstart.md). + :::image type="content" source="media/manage-bugs/add-bug-from-board.png" alt-text="Screenshot shows adding a bug from the board."::: -- **Add a bug from the product backlog** - > [!div class="mx-imgBorder"] - > ![Screenshot to add a bug from product backlog, Add bug.](media/manage-bugs/add-bug-from-backlog.png) +> [!TIP] +> When you add a bug from your product backlog or board, the bug is automatically assigned the default Area Path and Iteration Path defined for the team. For more information, see [Team defaults referenced by backlogs and boards](../../organizations/settings/about-teams-and-settings.md#team-defaults-referenced-by-backlogs-and-boards). -- **Add a bug from the product backlog** - > [!div class="mx-imgBorder"] - > ![Screenshot to add a bug from Kanban board, Add bug.](media/manage-bugs/add-bug-from-board.png) +### Add a bug from your sprint backlog or Taskboard -> [!TIP] -> When you add a bug from your product backlog or Kanban board, the bug is automatically assigned the default Area Path and Iteration Path defined for the team. For more information, see [Team defaults referenced by backlogs and boards](../../organizations/settings/about-teams-and-settings.md#team-defaults-referenced-by-backlogs-and-boards). +If your team chose to *manage bugs with tasks*, you can define bugs from your board, product backlog, Sprint backlog, or Sprint Taskboard. You add a bug as a child to a product backlog work item. +- **Add a linked child bug from the Sprint Backlog** -### Add a bug from your sprint backlog or Taskboard + You add a bug in the same way you add a task to a Sprint backlog. For more information, see [Add tasks to backlog items](../sprints/add-tasks.md). -If your team chose to *manage bugs with tasks*, you can define bugs from your Kanban board, product backlog, Sprint backlog, or Sprint Taskboard. You add a bug as a child to a product backlog work item. + :::image type="content" source="media/manage-bugs/add-bug-sprint-backlog.png" alt-text="Screenshot shows adding a linked child bug from the product backlog."::: -- **Add a linked child bug from the Kanban board** - You add a bug in the same way you add a task to a backlog item. For more information, see [Add tasks or child items as checklists](../boards/add-task-checklists.md). - > [!div class="mx-imgBorder"] - > ![Screenshot to add a bug from Kanban board, Add child bug to backlog item.](media/manage-bugs/add-child-bug-from-board.png) +- **Add a linked child bug from the board** -- **Add a linked child bug from the Sprint Backlog** - You add a bug in the same way you add a task to a Sprint backlog. For more information, see [Add tasks to backlog items](../sprints/add-tasks.md). - > [!div class="mx-imgBorder"] - > ![Screenshot to add a bug from Sprint backlog, Add child bug to backlog item.](media/manage-bugs/add-bug-sprint-backlog.png) + You add a bug in the same way you add a task to a backlog item. For more information, see [Add tasks or child items as checklists](../boards/add-task-checklists.md). -### Create a bug from a testing tool + :::image type="content" source="media/manage-bugs/add-child-bug-from-board.png" alt-text="Screenshot shows adding a lined child bug from the board."::: -The two testing tools you can use to add bugs while testing include the web portal Test Runner and the Test & Feedback extension. +### Create a bug from a testing tool -- **Test Runner**: When running manual tests, you can choose to **Create bug**. For more information, see [Run manual tests](../../test/run-manual-tests.md). - > [!div class="mx-imgBorder"] - > ![Screenshot to add a bug from Test Runner, Create bug feature.](media/manage-bugs/test-runner-create-bug.png) +The two testing tools you can use to add bugs while testing include the web portal Test Runner and the Test & Feedback extension. -- **Test & Feedback extension**: When running exploratory tests, you can choose to **Create bug** or **Create task**. For more information, see [Exploratory testing with the Test & Feedback extension](../../test/connected-mode-exploratory-testing.md) - ![Screenshot to add a bug from Test & Feedback extension, Create bug or task feature.](../../test/media/connected-mode-exploratory-testing/create-bugs-02.png) +- **Test Runner**: When running manual tests, you can choose to **Create bug**. For more information, see [Run manual tests](../../test/run-manual-tests.md). + :::image type="content" source="media/manage-bugs/test-runner-create-bug.png" alt-text="Screenshot shows Test Runner, where you can add a bug."::: +- **Test & Feedback extension**: When running exploratory tests, you can choose to **Create bug** or **Create task**. For more information, see [Exploratory testing with the Test & Feedback extension](../../test/connected-mode-exploratory-testing.md). + + :::image type="content" source="../../test/media/connected-mode-exploratory-testing/create-bugs-02.png" alt-text="Screenshot shows the Test & Feedback extension, where you can add a bug or task feature."::: ## Bug lifecycle and workflow states -As with all other work item types, the Bug work item type has a well-defined workflow. Each workflow consists of three or more **States** and a **Reason**. Reasons specify why the item transitioned from one State to another. The following images illustrate the default bug workflow defined for the [Agile](../work-items/guidance/agile-process.md), [Scrum](../work-items/guidance/scrum-process.md), and [CMMI](../work-items/guidance/cmmi-process.md) processes. +As with all other work item types, the Bug work item type has a well-defined workflow. Each workflow consists of three or more *States* and a *Reason*. Reasons specify why the item transitioned from one State to another. The following images illustrate the default bug workflow defined for the [Agile](../work-items/guidance/agile-process.md), [Scrum](../work-items/guidance/scrum-process.md), and [CMMI](../work-items/guidance/cmmi-process.md) processes. +| Agile | Scrum | CMMI | +|:------------|:------------|:-----------| +| :::image type="content" source="../work-items/guidance/media/ALM_PT_Agile_WF_Bug.png" alt-text="Diagram shows the bug workflow states in the Agile process template."::: | :::image type="content" source="../work-items/guidance/media/alm-pt-scrum-wf-bug.png" alt-text="Diagram shows the bug workflow states in the Scrum process template."::: | :::image type="content" source="../work-items/guidance/media/ALM_PT_CMMI_WF_Bug.png" alt-text="Diagram shows the bug workflow states in the CMMI process template."::: | -| Agile | Scrum | CMMI | -|------------|------------|-----------| -| ![Screenshot of bug workflow states, Agile process template.](../work-items/guidance/media/ALM_PT_Agile_WF_Bug.png) | ![Screenshot of bug workflow states, Scrum process template.](../work-items/guidance/media/alm-pt-scrum-wf-bug.png) | ![Screenshot of bug workflow states, CMMI process template.](../work-items/guidance/media/ALM_PT_CMMI_WF_Bug.png) | +For Scrum bugs, you change the **State** from *Committed* (similar to *Active*) to *Done*. For Agile and CMMI, you first resolve the bug and select a reason that indicates the bug is fixed. Typically, the person who created the bug then verifies the fix and updates the **State** from *Resolved* to *Closed*. If you find more work after you resolve or close a bug, reactivate it by setting the **State** to *Committed* or *Active*. -For Scrum bugs, you change the **State** from *Committed* (similar to *Active*) to *Done*. For Agile and CMMI, you first resolve the bug and select a reason that indicates the bug is fixed. Typically, the person who created the bug then verifies the fix and updates the **State** from *Resolved* to *Closed*. If more work has been found after a bug has been resolved or closed, you can reactivate it by setting the **State** to *Committed* or *Active*. +::: moniker range=">= azure-devops-2020" +> [!NOTE] +> The Agile process bug work item type previously had a rule which reassigned the bug to the person who created it. This rule has been removed from the default system process. You can reinstate this automation by adding a rule. For an Inheritance process, see [Automate reassignment based on state change](../../organizations/settings/work/apply-rules-to-workflow-states.md#reassign). -::: moniker range=">= azure-devops-2020" -> [!NOTE] -> The Agile process bug work item type previously had a rule which reassigned the bug to the person who created it. This rule has been removed from the default system process. You can reinstate this automation by adding a rule. For an Inheritance process, see [Apply rules to workflow states, Automate reassignment based on state change](../../organizations/settings/work/apply-rules-to-workflow-states.md#reassign). - -::: moniker-end +::: moniker-end -### Verify a fix +### Verify a fix To verify a fix, a developer or tester attempts to reproduce the bug and look for more unexpected behavior. If necessary, they should reactivate the bug. When verifying a bug fix, you might find that the bug wasn't fixed or you might disagree with the resolution. In this case, discuss the bug with the person who resolved it, come to an agreement, and possibly reactivate the bug. If you reactivate a bug, include the reasons for reactivating the bug in the bug description. - -### Close a bug +### Close a bug -You close a bug once it's verified as fixed. However, you might also close a bug for one of the following reasons. Reasons available to select depend on the project process and the bug transition states. +You close a bug when a team member verifies it as fixed. However, you might also close a bug for one of the following reasons. Reasons available depend on the project process and the bug transition states. **Agile process:** - **Deferred**: Defer bug fix until the next product release. - **Fixed**: Bug is verified as fixed. -- **Duplicate**: Bug tracks another bug currently defined. You can link each bug with the **Duplicate/Duplicate of** link type and close one of the bugs. +- **Duplicate**: Bug tracks another bug currently defined. You can link each bug with the **Duplicate/Duplicate of** link type and close one of the bugs. - **As Designed**: Feature works as designed. - **Cannot Reproduce**: Tests prove that the bug can't be reproduced. - **Obsolete**: The bug's feature is no longer in the product. @@ -294,273 +282,255 @@ You close a bug once it's verified as fixed. However, you might also close a bug **Scrum process:** - **Not a Bug**: Bug is verified that it isn't a bug. -- **Duplicate**: Bug tracks another bug currently defined. You can link each bug with the **Duplicate/Duplicate of** link type and close one of the bugs. -- **Removed from the backlog**: Bug is verified that it isn't a bug. Remove the bug from the backlog. +- **Duplicate**: Bug tracks another bug currently defined. You can link each bug with the **Duplicate/Duplicate of** link type and close one of the bugs. +- **Removed from the backlog**: Bug is verified that it isn't a bug. Remove the bug from the backlog. - **Work finished**: Bug has been verified as fixed. **CMMI process:** - **Deferred**: Defer bug fix until the next product release. -- **Duplicate**: Bug tracks another bug currently defined. You can link each bug with the **Duplicate/Duplicate of** link type and close one of the bugs. -- **Rejected**: Bug is verified that it isn't a bug. +- **Duplicate**: Bug tracks another bug currently defined. You can link each bug with the **Duplicate/Duplicate of** link type and close one of the bugs. +- **Rejected**: Bug is verified that it isn't a bug. - **Verified**: Bug is verified as fixed. +> [!TIP] +> After a bug has been closed and the fix is actively released in deployments, recommended practice is to never reopen it due to regression. Instead, you should consider opening a new bug and link to the older, closed bug. -> [!TIP] -> Once a bug has been closed and the fix is actively released in deployments, recommended practice is to never reopen it due to regression. Instead, you should consider opening a new bug and link to the older, closed bug. - -It's always a good idea to describe any more details for closing a bug in the **Discussion** field to avoid future confusion as to why the bug was closed. +It's always a good idea to describe any more details for closing a bug in the **Discussion** field to avoid future confusion as to why the bug was closed. ::: moniker range=">= azure-devops-2020" -### Automate bug closure when merging pull requests +### Automate bug closure when merging pull requests -If your team uses a Git repository, you can set the State in linked bugs and other work items to close upon successful merging of pull requests. For more information, see [Set work item state in pull request](#set-state-pr) later in this article. +If your team uses a Git repository, you can set the State in linked bugs and other work items to close upon successful merging of pull requests. For more information, see [Set work item state in pull request](#set-state-pr) later in this article. ::: moniker-end -## List and triage bugs +## List and triage bugs -Most teams, whatever option they chose to track bugs, define one or more bug queries. With queries, you can list active bugs, unassigned bugs, stale bugs, bug trends, and more. You can then add queries and query charts to your team dashboards to monitor bug status and progress. +Most teams, whatever option they chose to track bugs, define one or more bug queries. With queries, you can list active bugs, unassigned bugs, stale bugs, bug trends, and more. You can add queries and query charts to your team dashboards to monitor bug status and progress. ### Bug queries Open a shared query or [use the query editor](../queries/using-queries.md) to create useful bug queries, such as the following options: -- Active bugs by priority (```State <> Done``` or ```State <> Closed```) -- In Progress bugs (```State = Committed``` or ```State = Active```) -- Bugs to fix for a target release (```Tags Contains RTM```) -- Recent bugs - bugs opened within the last three weeks (```Created Date > @Today-21```) - -Once you have the queries of interest to your team, you can [create status or trend charts](../../report/dashboards/charts.md). You can also add the chart you create to a [dashboard](../../report/dashboards/dashboards.md). -### Triage mode in query results +- Active bugs by priority (`State <> Done` or `State <> Closed`) +- In Progress bugs (`State = Committed` or `State = Active`) +- Bugs to fix for a target release (`Tags Contains RTM`) +- Recent bugs, such as bugs opened in the last three weeks (`Created Date > @Today-21`) -Once you've started coding and testing, you'll want to hold periodic triage meetings to review and rank your bugs. Typically, the project owner runs the bug triage meetings. Team leads, business analysts, and other stakeholders who can speak about specific project risks attend the triage meetings. +When you have the queries of interest to your team, you can [create status or trend charts](../../report/dashboards/charts.md). You can also add the chart you create to a [dashboard](../../report/dashboards/dashboards.md). -The project owner can define a shared query for new and reopened bugs to list bugs to be triaged. +### Triage mode in query results -From the query results page, you can quickly move up and down within the list of bug work items using the up and down arrows. As you review each bug, you can assign it, add details, or set priority. For more information, see [Triage work items](../queries/triage-work-items.md). +After you start coding and testing, hold periodic triage meetings to review and rank your bugs. Typically, the project owner runs the bug triage meetings. Team leads, business analysts, and other stakeholders who can speak about specific project risks attend the triage meetings. +The project owner can define a shared query for new and reopened bugs to list bugs to be triaged. -> [!div class="mx-imgBorder"] -> ![Screenshot of Query Results, Active Bugs, and Triage mode Right pane.](media/manage-bugs/bug-triage-mode.png) +From the query results page, you can move up and down within the list of bug work items using the up and down arrows. As you review each bug, you can assign it, add details, or set priority. +:::image type="content" source="media/manage-bugs/bug-triage-mode.png" alt-text="Screenshot of Query Results, Active Bugs, and Triage mode Right pane."::: -### Organize and assign bugs to a sprint +### Organize and assign bugs to a sprint -If your team *tracks bugs as requirements*, view the list of active bugs from your backlog. With the [filter function](filter-backlogs-boards-plans.md), you can focus solely on bugs. From the product backlog, you can also do the following tasks: +If your team *tracks bugs as requirements*, view the list of active bugs from your backlog. With the [filter function](filter-backlogs-boards-plans.md), you can focus solely on bugs. From the product backlog, you can also do the following tasks: -- [Organize bugs on your backlog](create-your-backlog.md#reorder-your-backlog), stack rank against other items (stack ranking is disabled when filtering is enabled) -- [Assign bugs to a sprint](../sprints/assign-work-sprint.md) from your backlog using the **Planning** pane -- [Parent bugs to Features](organize-backlog.md#map-items-to-group-them-under-a-feature-or-epic) or other portfolio backlog items using the **Mapping** pane +- [Organize bugs on your backlog](create-your-backlog.md#reorder-your-backlog). Stack rank against other items. Stack ranking is disabled when filtering is enabled. +- [Assign bugs to a sprint](../sprints/assign-work-sprint.md) from your backlog using the **Planning** pane. +- [Map Parent bugs to Features](organize-backlog.md#map-items-to-group-them-under-a-feature-or-epic) or other portfolio backlog items using the **Mapping** pane. - [View rollup of work to portfolio backlog items](display-rollup.md). -If your team *tracks bugs as tasks*, use managed queries to list and triage bugs. Then, within each sprint, you'll see the bugs assigned to the sprint from the Sprint backlog or [Taskboard](../sprints/task-board.md). +If your team *tracks bugs as tasks*, use managed queries to list and triage bugs. In each sprint, you see the bugs assigned to the sprint from the Sprint backlog or [Taskboard](../sprints/task-board.md). - + ### Taskboard items versus query list items -You might notice and wonder why the items shown on a sprint Taskboard can differ from a query list created in a corresponding sprint backlog. - -It's possible to assign tasks or bugs to an iteration but not have them linked to a parent backlog item. These items appear in the created query, but might not show up on the Taskboard itself. The system runs the query and then applies a few background processes before displaying Taskboard items. +You might notice and wonder why the items shown on a sprint Taskboard can differ from a query list created in a corresponding sprint backlog. -These reasons can cause work items that belong to the Task Category to not appear on a sprint backlog or Taskboard: -- The task or bug hasn't been linked to a parent backlog item. Only bugs and tasks you've linked to a parent product backlog item (Scrum), user story (Agile), or requirement (CMMI) with an iteration path set to the sprint appears on the sprint backlog page. -- The task or bug is a parent of another task or bug, or the user story is a parent of another user story. If you've created a hierarchy of tasks, bugs, or user stories, [only the child-level tasks or the child-level stories at the bottom of the hierarchy appear](resolve-backlog-reorder-issues.md#leaf-nodes). -- The task's or bug's linked parent corresponds to a backlog item defined for another team. Or, the area path of the task's or bug's parent backlog item differs from the task's or bug's area path. +It's possible to assign tasks or bugs to an iteration but not link them to a parent backlog item. These items appear in the created query, but might not show up on the Taskboard itself. The system runs the query and then applies a few background processes before displaying Taskboard items. +These reasons can cause work items that belong to the Task Category to not appear on a sprint backlog or Taskboard: -## Create inline tests linked to bugs +- The task or bug isn't linked to a parent backlog item. Only bugs and tasks are linked to a parent product backlog item (Scrum), user story (Agile), or requirement (CMMI) with an iteration path set to the sprint appears on the sprint backlog page. +- The task or bug is a parent of another task or bug, or the user story is a parent of another user story. If you create a hierarchy of tasks, bugs, or user stories, only the child-level tasks or the child-level stories at the bottom of the hierarchy appear. For more information, see [Troubleshoot reordering and nesting issues](resolve-backlog-reorder-issues.md). +- The task's or bug's linked parent corresponds to a backlog item defined for another team. Or, the area path of the task's or bug's parent backlog item differs from the task's or bug's area path. -When your team *tracks bugs as requirements*, you can use the Kanban board to add tests to verify bug fixes. +## Create inline tests linked to bugs -> [!div class="mx-imgBorder"] -> ![Screenshot of Kanban board, 3 columns showing inline tests added and linked to bugs.](media/manage-bugs/add-tests-inline-kanban-board.png) +When your team *tracks bugs as requirements*, you can use the board to add tests to verify bug fixes. +:::image type="content" source="media/manage-bugs/add-tests-inline-kanban-board.png" alt-text="Screenshot of board, three columns showing inline tests added and linked to bugs."::: -## Update bug status +## Update bug status -You can update the bug status by dragging and dropping bugs to a new column on a board. +You can update the bug status by dragging and dropping bugs to a new column on a board. -- If your team *tracks bugs as requirements*, you use the Kanban board as shown in the following image. For more information, see [Get started with your Kanban board](../boards/kanban-quickstart.md#update-status). +- If your team *tracks bugs as requirements*, you use the board as shown in the following image. For more information, see [Update work item status](../boards/kanban-quickstart.md#update-status). - > [!div class="mx-imgBorder"] - > ![Screenshot of Kanban board, drag and drop to update status.](media/manage-bugs/kanban-board-update-status.png) + :::image type="content" source="media/manage-bugs/kanban-board-update-status.png" alt-text="Screenshot of a board, where you can drag a bug to update status." lightbox="media/manage-bugs/kanban-board-update-status.png"::: -- If your team *tracks bugs as tasks*, you use the Taskboard. For more information, see [Update and monitor your Taskboard](../sprints/task-board.md). +- If your team *tracks bugs as tasks*, you use the Taskboard. For more information, see [Update and monitor your Taskboard](../sprints/task-board.md). - > [!div class="mx-imgBorder"] - > ![Screenshot of Taskboard, drag and drop to update status.](../sprints/media/alm_tb_move_to_done.png) + :::image type="content" source="../sprints/media/alm_tb_move_to_done.png" alt-text="Screenshot of the Taskboard, where you can drag a bug to update status."::: -### Customize your board to track intermediate states +### Customize your board to track intermediate states -You can add intermediate columns to track your bug status on the board. You can also define queries that filter based on the status of a Board Column. For more information, see the following articles: +You can add intermediate columns to track your bug status on the board. You can also define queries that filter based on the status of a Board Column. For more information, see the following articles: ::: moniker range=">= azure-devops-2020" -- [Add columns to your Kanban board](../boards/add-columns.md) +- [Add columns to your board](../boards/add-columns.md) - [Customize a sprint Taskboard](../sprints/customize-taskboard.md) -- [Kanban board change queries](../queries/query-by-workflow-changes.md#kanban-query-fields) +- [Query changes to a board](../queries/query-by-workflow-changes.md#kanban-query-fields) ::: moniker-end -::: moniker range="< azure-devops-2020" +### Automate bug reassignment based on workflow state -- [Add columns to your Kanban board](../boards/add-columns.md) -- [Kanban board change queries](../queries/query-by-workflow-changes.md#kanban-query-fields) +To automate select actions, add custom rules to your Bug work item type. For example, add a rule as shown in the following image. This rule specifies to reassign a bug to the person who opened the bug when a team member resolves it. Typically, that person verifies that the bug is fixed and closes the bug. For more information, see [Apply rules to workflow states (Inheritance process)](../../organizations/settings/work/apply-rules-to-workflow-states.md). -::: moniker-end +:::image type="content" source="media/manage-bugs/rule-reassigned-resolved-bug.png" alt-text="Screenshot of rule defined to reassign bug based on resolved state."::: -### Automate bug reassignment based on workflow state + -To automate select actions, add custom rules to your Bug work item type. For example, add a rule as shown in the following image. This rule specifies to reassign a bug to the person who opened the bug once it's resolved. Typically, that person verifies that the bug is fixed and closes the bug. For more information, see [Apply rules to workflow states (Inheritance process)](../../organizations/settings/work/apply-rules-to-workflow-states.md). +### Set work item state in pull request -> [!div class="mx-imgBorder"] -> ![Screenshot of rule defined to reassign bug based on resolved state.](media/manage-bugs/rule-reassigned-resolved-bug.png) +::: moniker range=">= azure-devops-2020" +When you create a pull request, you can set the *state* value of the linked work items in the description. Follow the syntax: `{state value}: #ID`. - +When you merge the pull request, the system reads the description and updates the work item state. The following example sets work items #300 and #301 to Resolved, and #323 and #324 to Closed. -::: moniker range=">= azure-devops-2020" -### Set work item state in pull request +:::image type="content" source="/azure/devops/organizations/notifications/media/pr-set-state-of-work-items.png" alt-text="Screenshot of setting work item state within a pull request." lightbox="/azure/devops/organizations/notifications/media/pr-set-state-of-work-items.png"::: + +::: moniker-end + +::: moniker range="azure-devops-2020" +> [!NOTE] +> This feature requires installation of Azure DevOps Server 2020.1 update. For more information, see [Azure DevOps Server 2020 Update 1 RC1 Release Notes, Boards](/azure/devops/server/release-notes/azuredevops2020u1#customize-work-item-state-when-pull-request-is-merged). ::: moniker-end -[!INCLUDE [temp](../../includes/set-work-item-state-pull-request.md)] +## Integration across Azure DevOps -## Integration across Azure DevOps +One of the methods used by Azure DevOps to support integration is to link objects to other objects. Along with linking work items to work items, you can also link work items to other objects. Link to objects such as builds, releases, branches, commits, and pull requests as illustrated in the following image. -One of the methods used by Azure DevOps to support integration is to link objects to other objects. Along with linking work items to work items, you can also link work items to other objects. Link to objects such as builds, releases, branches, commits, and pull requests as illustrated in the following image. +:::image type="content" source=" ../../organizations/notifications/media/types-of-work-item-links.png" alt-text="Diagram that shows link types used to link work items to build and release objects."::: -> [!div class="mx-imgBorder"] -> ![Conceptual image that shows link types used to link work items to build and release objects.]( ../../organizations/notifications/media/types-of-work-item-links.png) - -You can add a link from the work item or from the build and release objects. +You can add a link from the work item or from the build and release objects. + - +### Link work items to development -### Link work items to development +The **Development** control supports linking to and displaying links made to builds, Git commits, and pull requests. When a TFVC repository is used, it supports links to changesets and versioned items. Choosing the link opens the corresponding item in a new browser tab. For more information, see [Drive Git development from a work item](connect-work-items-to-git-dev-ops.md). -The **Development** control supports linking to and displaying links made to builds, Git commits and pull requests. Or, when a TFVC repository is used, it supports links to changesets and versioned items. Choosing the link opens the corresponding item in a new browser tab. For more information, see [Drive Git development from a work item](connect-work-items-to-git-dev-ops.md). -> [!div class="mx-imgBorder"] -> ![Development control on work item form with sample links to build, pull requests, and commits.](media/manage-bugs/development-links.png) +:::image type="content" source="media/manage-bugs/development-links.png" alt-text="Screenshot shows Development control on work item form with sample links to build, pull requests, and commits."::: - + -### Link work items to releases +### Link work items to releases -The **Deployment** control supports links to and display of releases that contain the work items. For example, the following image shows several releases that contain links to the current work item. You can expand each release to see details about each stage. You can choose the link for each release and stage to open the corresponding release or stage. For more information, see [Link work items to deployments](../work-items/work-item-deployments-control.md). -> [!div class="mx-imgBorder"] -> ![Deployment control on work item form with sample releases.](media/manage-bugs/deployment-section-with-releases.png) +The **Deployment** control supports links to and display of releases that contain the work items. For example, the following image shows several releases that contain links to the current work item. You can expand each release to see details about each stage. You can choose the link for each release and stage to open the corresponding release or stage. For more information, see [Link work items to deployments](../backlogs/add-link.md#link-work-items-to-deployments). -### Link work items to pipeline runs +:::image type="content" source="media/manage-bugs/deployment-section-with-releases.png" alt-text="Screenshot shows Deployment control on work item form with sample releases."::: -Pipelines are often defined to automatically run when a new commit occurs to a Git repository. Work items associated with the commit pipelines appear as part of the pipeline run if you customize your pipeline settings. For more information, see [Customize your pipeline](../../pipelines/customize-pipeline.md). +### Link work items to pipeline runs + +Pipelines are often defined to automatically run when a new commit occurs to a Git repository. Work items associated with the commit pipelines appear as part of the pipeline run if you customize your pipeline settings. For more information, see [Customize your pipeline](../../pipelines/customize-pipeline.md). + +:::image type="content" source="media/manage-bugs/pipeline-settings.png" alt-text="Screenshot of Pipeline Settings with Automatically link work items in this run from selected branch highlighted."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of Pipeline Settings, Automatically link work items in this run from selected branch.](media/manage-bugs/pipeline-settings.png) - ### Create or edit a work item upon a build failure -If you use classic pipelines (not YAML), you can create work items on a build failure. For more information, see [Build options, Create a work item on failure](../../pipelines/build/options.md). +If you use classic pipelines (not YAML), you can create work items on a build failure. For more information, see [Create a work item on failure](../../pipelines/build/options.md#create-work-items-on-failure). ## Monitor bug status, assignments, and trends -You can track the bug status, assignments, and trends using queries that you can then chart and add to a dashboard. For example, here are two examples showing active bug trends by State and Active Bugs by Priority over time. - -> [!div class="mx-imgBorder"] -> ![Screenshot of two active bug query charts, Bug Trends by State and by Priority.](media/manage-bugs/query-charts-active-bugs.png) +You can track the bug status, assignments, and trends using queries that you can chart and add to a dashboard. For example, here are two examples showing active bug trends by State and Active Bugs by Priority over time. - +:::image type="content" source="media/manage-bugs/query-charts-active-bugs.png" alt-text="Screenshot of two active bug query charts, Bug Trends by State and by Priority."::: -To learn more about queries, charts, and dashboards; see [About managed queries](../queries/about-managed-queries.md) and [Charts](../../report/dashboards/charts.md), and [Dashboards](../../report/dashboards/dashboards.md). +For more information about queries, charts, and dashboards see [managed queries](../queries/about-managed-queries.md), [charts](../../report/dashboards/charts.md), and [dashboards](../../report/dashboards/dashboards.md). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### Use Analytics views and the Analytics service to create bug reports -The Analytics service is the reporting platform for Azure DevOps, replacing the previous platform based on SQL Server Reporting Services. +The Analytics service is the reporting platform for Azure DevOps. It replaces the previous platform based on SQL Server Reporting Services. -Analytics views provide pre-built filters to view work items. Four Analytic views are supported for bug reporting. You can use these views as defined or further edit them to create a custom, filtered view. +Analytics views provide prebuilt filters to view work items. Four Analytic views are supported for bug reporting. You can use these views as defined or further edit them to create a custom, filtered view. - Bugs - All history by month - Bugs - Last 26 weeks - Bugs - Last 30 days -- Bugs - Today +- Bugs - Today -To learn more about using Analytic views, see [What are Analytics views](../../report/powerbi/what-are-analytics-views.md) and [Create an active bugs report in Power BI based on a custom Analytics view](../../report/powerbi/active-bugs-sample-report.md). +For more information about using Analytic views, see [About Analytics views](../../report/powerbi/what-are-analytics-views.md) and [Create an active bugs report in Power BI based on a custom Analytics view](../../report/powerbi/active-bugs-sample-report.md). -You can use Power BI to create more complex reports than what you can get from a query. For more information, see [Connect with Power BI Data Connector](../../report/powerbi/data-connector-connect.md). +You can use Power BI to create more complex reports than a query. For more information, see [Connect with Power BI Data Connector](../../report/powerbi/data-connector-connect.md). -::: moniker-end - -::: moniker range="< azure-devops-2022" +::: moniker-end -### Pre-defined SQL Server bug reports +::: moniker range="< azure-devops-2022" -The following reports are supported for Agile and CMMI processes. +### Predefined SQL Server bug reports -- [Bug Status](/previous-versions/azure/devops/report/sql-reports/bug-status-report) -- [Bug Trends](/previous-versions/azure/devops/report/sql-reports/bug-trends-report) -- [Reactivations](/previous-versions/azure/devops/report/sql-reports/reactivations-report) +The following reports are supported for Agile and CMMI processes. -These reports require you have SQL Server Analysis Services and SQL Server Reporting Services configured for your project. To learn how to add SQL Server reports for a project, see [Add reports to a project](/previous-versions/azure/devops/report/admin/add-reports-to-a-team-project). +- [Bug Status](/previous-versions/azure/devops/report/sql-reports/bug-status-report) +- [Bug Trends](/previous-versions/azure/devops/report/sql-reports/bug-trends-report) +- [Reactivations](/previous-versions/azure/devops/report/sql-reports/reactivations-report) -::: moniker-end +These reports require that you have SQL Server Analysis Services and SQL Server Reporting Services configured for your project. To learn how to add SQL Server reports for a project, see [Add reports to a project](/previous-versions/azure/devops/report/admin/add-reports-to-a-team-project). +::: moniker-end -### Marketplace extensions +### Marketplace extensions -There are multiple bug-related Marketplace extensions. See [Marketplace for Azure DevOps](https://marketplace.visualstudio.com/search?term=bug&target=AzureDevOps&category=All%20categories&sortBy=Installs). +There are multiple bug-related Marketplace extensions. See [Marketplace for Azure DevOps](https://marketplace.visualstudio.com/search?term=bug&target=AzureDevOps&category=All%20categories&sortBy=Installs). For more information on extensions, see [Azure Boards extensions developed by Microsoft](../extensions/index.md). - ## Next steps > [!div class="nextstepaction"] -> [Triage work items](../queries/triage-work-items.md) +> [Use templates to add and update work items](work-item-template.md) -## Related articles +## Related articles -- [Use templates to add and update work items](work-item-template.md) -- [Move, change type, or delete work items](remove-delete-work-items.md) +- [Remove, delete, or restore work items](remove-delete-work-items.md) - [Copy or clone a work item](copy-clone-work-items.md#copy-clone) -### Product backlog and Kanban board +### Product backlog and board -- [Backlogs, portfolios, and Agile project management](backlogs-overview.md) -- [Create your backlog](create-your-backlog.md) -- [Define features and epics](define-features-epics.md) -- [Organize your backlog, map child work items to parents](organize-backlog.md) -- [Interactively filter backlogs, boards, queries, and plans](filter-backlogs-boards-plans.md) -- [Forecast your product backlog](../sprints/forecast.md) -- [Refine your backlog](best-practices-product-backlog.md) +- [Use backlogs to manage projects](backlogs-overview.md) +- [Create your backlog](create-your-backlog.md) +- [Define features and epics](define-features-epics.md) +- [Organize your backlog and map child work items to parents](organize-backlog.md) +- [Interactively filter backlogs, boards, queries, and plans](filter-backlogs-boards-plans.md) +- [Forecast your product backlog](../sprints/forecast.md) -### Kanban board +### Board -- [About Boards and Kanban](../boards/kanban-overview.md) -- [Kanban board quickstart](../boards/kanban-quickstart.md) -- [Reorder cards](../boards/customize-cards.md#reorder-cards) -- [Add tasks or child items as checklists](../boards/add-task-checklists.md) +- [About Boards and Kanban](../boards/kanban-overview.md) +- [Use your board](../boards/kanban-quickstart.md) +- [Reorder cards](../boards/customize-cards.md#reorder-cards) +- [Add tasks or child items as checklists](../boards/add-task-checklists.md) -### Sprint backlog and Taskboard +### Sprint backlog and Taskboard -- [Scrum and working with sprints best practices](../sprints/best-practices-scrum.md) -- [Assign backlog items to a sprint](../sprints/assign-work-sprint.md) -- [Add tasks](../sprints/add-tasks.md) -- [Update the Taskboard](../sprints/task-board.md) +- [Learn about Scrum best practices](../sprints/best-practices-scrum.md) +- [Assign backlog items to a sprint](../sprints/assign-work-sprint.md) +- [Add tasks](../sprints/add-tasks.md) +- [Update your Taskboard](../sprints/task-board.md) ### Integration within Azure DevOps -- [Link user stories, issues, bugs, and other work items](add-link.md) +- [Link user stories, issues, bugs, and other work items](add-link.md) - [Follow a work item or pull request](../work-items/follow-work-items.md) - [Configure run or build numbers](../../pipelines/process/run-number.md) -### Industry resources - -- [Good and Bad Technical Debt (and how TDD helps)](https://blog.crisp.se/2013/10/11/henrikkniberg/good-and-bad-technical-debt) by Henrik Kniberg -- [Managing Technical Debt](https://www.infoq.com/articles/managing-technical-debt) posted by Sven Johann & Eberhard Wolff +### Industry resources +- [Good and Bad Technical Debt (and how TDD helps)](https://blog.crisp.se/2013/10/11/henrikkniberg/good-and-bad-technical-debt) by Henrik Kniberg +- [Managing Technical Debt](https://www.infoq.com/articles/managing-technical-debt) posted by Sven Johann & Eberhard Wolff diff --git a/docs/boards/backlogs/manage-issues-impediments.md b/docs/boards/backlogs/manage-issues-impediments.md index 54ac78aaf4e..aab70c485be 100644 --- a/docs/boards/backlogs/manage-issues-impediments.md +++ b/docs/boards/backlogs/manage-issues-impediments.md @@ -1,8 +1,8 @@ --- -title: Manage and resolve issues or impediments in Azure Boards -titleSuffix: Azure Boards +title: Manage and resolve issues or impediments in Azure Boards +titleSuffix: Azure Boards description: Learn how to track issues or impediments to more effectively execute plans or stay on schedule by using Azure Boards. -ms.custom: "boards-backlogs, seodec18" +ms.custom: boards-backlogs ms.service: azure-devops-boards ms.assetid: 5B126205-599D-40EB-BC95-23CF1444EF2A ms.author: chcomley @@ -21,7 +21,7 @@ If you have known issues you want to track, you can do so by defining an impedim Don't confuse impediments with bugs. You track impediments that may cause problems with delivering one or more requirements. For example, you may have to fix feature ambiguity, personnel or resource issues, problems with environments, or other risks that influence scope, quality, or schedule. Other issues that deserve tracking are decisions that require several stakeholders or product teams to weigh in on. -::: moniker range="> tfs-2018" +::: moniker range="<=azure-devops" > [!IMPORTANT] > Issues and Impediments discussed in this article are defined for projects created with the [Agile](../work-items/guidance/agile-process.md), [Scrum](../work-items/guidance/scrum-process.md), or [CMMI](../work-items/guidance/cmmi-process.md) process. By default, these work item types don't appear on the product backlog or taskboard. @@ -30,14 +30,6 @@ Don't confuse impediments with bugs. You track impediments that may cause proble ::: moniker-end - -::: moniker range="tfs-2018" - -> [!IMPORTANT] -> Issues and Impediments discussed in this article are defined for projects created with the [Agile](../work-items/guidance/agile-process.md), [Scrum](../work-items/guidance/scrum-process.md), or [CMMI](../work-items/guidance/cmmi-process.md) process. By default, these work item types don't appear on the product backlog or taskboard. - -::: moniker-end - In this article you'll learn: ::: moniker range="azure-devops" @@ -57,6 +49,7 @@ In this article you'll learn: ::: moniker-end +## Prerequisites [!INCLUDE [temp](../includes/prerequisites-work-items.md)] @@ -68,23 +61,16 @@ You use issues or impediments to track items that may block work from getting do Define tasks when you want to create a [checklist of tasks](../boards/add-task-checklists.md). You can also define tasks if you use Scrum methods and track work using the [Remaining Work](../sprints/task-board.md) field. By linking requirement work item types to tasks using the Parent-Child link type, the tasks appear on the taskboard for each linked user story. -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!NOTE] -> If your project collection uses the On-premises XML process model to customize work tracking, you can enable work item types that you add to the Task Category to appear as a checklist on your product Kanban board. To learn how, see [Set up your backlogs and boards, Customize your Kanban Board checklist items](set-up-your-backlog.md#customize-checklist-2019). - -::: moniker-end - - -::: moniker range="azure-devops-2019" - -If you want to add these work item types to a backlog, see [Customize your backlogs or boards](../../organizations/settings/work/customize-process-backlogs-boards.md). +> If your project collection uses the On-premises XML process model to customize work tracking, you can enable work item types that you add to the Task Category to appear as a checklist on your product board. To learn how, see [Set up your backlogs and boards, Customize your board checklist items](set-up-your-backlog.md#customize-checklist-2019). ::: moniker-end ## Add an issue or impediment -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Open **Boards>Work Items**, and choose the :::image type="icon" source="../../media/icons/blue-add.png" border="false"::: plus icon, and then select from the **New work item** menu of options. @@ -95,41 +81,26 @@ Choose the :::image type="icon" source="../media/icons/pin-icon.png" border="fa ::: moniker-end -::: moniker range="tfs-2018" - -From **Work**, choose **Impediment** from the **New Work Item** list of options. Choose the :::image type="icon" source="../media/icons/pin-icon.png" border="false"::: pin icon to have it show up within **Work** drop down menu. - -![Screenshot to add an Impediment from the New Work Item list, TFS 2018.](media/cyb-new-work-item-impediment.png) - -::: moniker-end - - ## Customize issue tracking [!INCLUDE [temp](../includes/customize-work-tracking.md)] - ::: moniker range="azure-devops" Issues and impediments don't appear on your backlog by default. Instead, you track them using [queries](../queries/using-queries.md). To track them on a backlog, see the next section, [Add issues or impediments to your product backlog](#add-to-backlog). ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" + ## Add issues or impediments to your product backlog @@ -138,21 +109,15 @@ If you want to track issues or impediments along with your requirements or a por ::: moniker-end -::: moniker range=">= Azure-devops-2019 < azure-devops" +::: moniker range=" --assigned-to --org https://dev.azure.com/ --project + +``` + +> [!TIP] +> If you set the default organization and project using the `az devops configure` command, you can omit the `--org` and `--project` parameters. + +::: moniker-end + +--- + +## View and track work items + +You can view work items created by you or your team. The **Work items** page offers several personalized pivots and interactive filter functions to streamline listing work items. + +::: moniker range="azure-devops" + +You can also view work items from Visual Studio, Azure DevOps CLI, or the REST API. + +::: moniker-end + +For more information, see [View and add work items](../work-items/view-add-work-items.md). + +## Link Work Items + +Add links to work items to show relationships between them and other work items or objects. In an Agile scenario, you would typically link features to epics, user stories to features and tasks to user stories in parent-child relationships. There are many other [link types](../../boards/queries/link-type-reference.md) and objects you can link to your work items. For more information, see [Link work items to objects](add-link.md). + + +::: moniker range="azure-devops" + +## Follow a work item + +To track the progress of a single work item, select the **Follow** icon + :::image type="icon" source="../media/icons/follow-icon.png" border="false":::. This action sends you email alerts when changes are made to the work item. + +> [!div class="mx-imgBorder"] +> ![Screenshot showing Work item form, Follow icon control.](../work-items/media/follow-work/follow-work-item.png) + +You receive notifications when other project members modify the work item, such as adding to the discussion, change a field value, or add an attachment. + +You can specify the types of changes you want to be notified about. When you select the settings icon, :::image type="icon" source="../media/icons/settings-icon.png" border="false"::: you can select: + +- **Not Subscribed**: Only receive notifications from this work item when you're @mentioned. +- **Subscribed**: Receive notifications for all changes to this work item. +- **Custom**: Specify notifications for: + - **State Changed**: When the work item changes state + - **Assigned To Changed**: When the work item is assigned to someone else + - **Iteration Changed**: When the iteration path changes + +Notifications are sent to your preferred email address, which you can [change from your user profile](../../organizations/notifications/change-email-address.md). + +To stop following changes, select the **Following** icon :::image type="icon" source="../media/icons/following-icon.png" border="false":::. + +::: moniker-end + +## Attachments + +You can attach files to work items to provide more context or information. You can attach up to 100 files to a work item. Each attachment is limited to 60 MB. You can manage attachments through the web portal by selecting the attachment tab on your work item. + +For more information, see [Manage attachments to work items](../work-items/manage-attachments.md). + +## Work item tags + +Tags are keywords that you define to categorize work items. You can add tags to work items to filter backlogs and queries. + +To learn how to manage and use tags, see [Add tags to work items](../queries/add-tags-to-work-items.md). + + +[!INCLUDE [discussion-tip-azure-devops](../includes/discussion-tip-azure-devops.md)] + + +## Copy or clone work items + +Cloning or copying a DevOps work item can be beneficial for several reasons: + +- **Efficiency**: Quickly create a new work item with similar details without manually duplicating all the information. +- **Consistency**: Ensure that the new work item retains the same structure, fields, and values as the original, maintaining consistency across similar tasks. +- **Template Usage**: Use an existing work item as a template for new work items, especially for recurring tasks or standard processes. +- **Bulk Operations**: Easily create multiple similar work items for different team members or iterations. +- **Preserve History**: Keep the history and context of the original work item while creating a new instance for tracking separate progress. + +For more information, see [Copy or clone work items](copy-clone-work-items.md). + +## Move work items between team + +You can move work items from one team to another team within the same project. To move work items, have the **Edit work items in this node** permission for the target team. + +For more information, see [Move work items from one team to another](../work-items/move-work-items.md). + +## Customizing Work Item Templates + +Project Work items can be customized to track additional information that is important to your team. You can add custom fields, change the layout of the work item form, and add custom rules to enforce processes. This customization can be done by modifying the process templates used by your project. + +There are two ways to customize work item templates: + +1. **Work Item Type**: Customize the work item type used by your project. This customization affects only the work item type. For more information, see [Add and manage work item types](../../organizations/settings/work/customize-process-work-item-type.md). +1. **Work Item Template**: Create custom work item templates used by your team based on existing work items. Custom work item templates allow you to prepopulate values in commonly used fields. For more information, see, [Use work item templates](work-item-template.md). + +With the appropriate organization-level permissions, you can create customized inherited *process templates*. All projects that use the customized process template get the customizations made to that process. You can customize which work item types are included in the process template and customize the work item template form. For more information, see [About process customization and inherited processes](../../organizations/settings/work/inheritance-process-model.md) and [Customize a process template](../../reference/process-templates/customize-process.md). + + +## Delete work items + +You can delete work items that are no longer needed. Deleted work items are moved to the Recycle Bin where they can be restored or permanently deleted. + +For more information, see, [Remove, delete, or restore work items](remove-delete-work-items.md). + + +## Reporting and Analytics + +Analytics views provide a powerful way to visualize and analyze your work items. You can use create custom reports and dashboards to track progress, identify trends, and make data-driven decisions. + +For more information, see [What is Analytics?](../../report/powerbi/what-is-analytics.md). + +## Best Practices + +There are best practices to help you effectively manage work items for development processes including: + +- [Agile](../work-items/guidance/agile-process-workflow.md) +- [Scrum](../work-items/guidance/scrum-process-workflow.md) +- [Capability Maturity Model Integration (CMMI)](../work-items/guidance/cmmi-process-workflow.md) + + +## Next steps + +> [!div class="nextstepaction"] +> [Create your backlog](create-your-backlog.md) or +> [Kanban board quickstart](../boards/kanban-quickstart.md) + +## Related articles + +- [View the work item field index](../work-items/guidance/work-item-field.md?toc=/azure/devops/boards/work-items/toc.json) +- [Explore work item form controls](../work-items/about-work-items.md#work-item-form-controls) +- [Set up notifications for changes](../../organizations/notifications/manage-your-personal-notifications.md) +- [Create and manage queries](../queries/using-queries.md) +- [Define status and trend charts](../../report/dashboards/charts.md) +- [Use clients that support tracking work items](../../user-guide/tools.md?toc=/azure/devops/boards/work-items/toc.json) \ No newline at end of file diff --git a/docs/boards/backlogs/media/add-attachment.png b/docs/boards/backlogs/media/add-attachment.png new file mode 100644 index 00000000000..8a90847c6f7 Binary files /dev/null and b/docs/boards/backlogs/media/add-attachment.png differ diff --git a/docs/boards/backlogs/media/add-link-related-new-item-issue.png b/docs/boards/backlogs/media/add-link-related-new-item-issue.png index 4685f778831..ae4444665b8 100644 Binary files a/docs/boards/backlogs/media/add-link-related-new-item-issue.png and b/docs/boards/backlogs/media/add-link-related-new-item-issue.png differ diff --git a/docs/boards/backlogs/media/add-link/add-link-build-filled-in.png b/docs/boards/backlogs/media/add-link/add-link-build-filled-in.png new file mode 100644 index 00000000000..5a06deaace3 Binary files /dev/null and b/docs/boards/backlogs/media/add-link/add-link-build-filled-in.png differ diff --git a/docs/boards/backlogs/media/add-link/add-link-dialog-s136.png b/docs/boards/backlogs/media/add-link/add-link-dialog-s136.png deleted file mode 100644 index 848b9abdc31..00000000000 Binary files a/docs/boards/backlogs/media/add-link/add-link-dialog-s136.png and /dev/null differ diff --git a/docs/boards/backlogs/media/add-link/add-link-dialog.png b/docs/boards/backlogs/media/add-link/add-link-dialog.png new file mode 100644 index 00000000000..268ec1fc10f Binary files /dev/null and b/docs/boards/backlogs/media/add-link/add-link-dialog.png differ diff --git a/docs/boards/backlogs/media/add-link/add-link-find-builds.png b/docs/boards/backlogs/media/add-link/add-link-find-builds.png new file mode 100644 index 00000000000..5694d777c43 Binary files /dev/null and b/docs/boards/backlogs/media/add-link/add-link-find-builds.png differ diff --git a/docs/boards/backlogs/media/add-link/add-link-new-item.png b/docs/boards/backlogs/media/add-link/add-link-new-item.png new file mode 100644 index 00000000000..e99b560e892 Binary files /dev/null and b/docs/boards/backlogs/media/add-link/add-link-new-item.png differ diff --git a/docs/boards/backlogs/media/add-link/change-link-type.png b/docs/boards/backlogs/media/add-link/change-link-type.png index 45da8f81a41..14c7ec29232 100644 Binary files a/docs/boards/backlogs/media/add-link/change-link-type.png and b/docs/boards/backlogs/media/add-link/change-link-type.png differ diff --git a/docs/boards/backlogs/media/add-link/edit-link-dialog.png b/docs/boards/backlogs/media/add-link/edit-link-dialog.png index 2f82e2e73e4..e27a95d9886 100644 Binary files a/docs/boards/backlogs/media/add-link/edit-link-dialog.png and b/docs/boards/backlogs/media/add-link/edit-link-dialog.png differ diff --git a/docs/boards/backlogs/media/add-link/find-builds-dialog-filled-out.png b/docs/boards/backlogs/media/add-link/find-builds-dialog-filled-out.png new file mode 100644 index 00000000000..482efe793a1 Binary files /dev/null and b/docs/boards/backlogs/media/add-link/find-builds-dialog-filled-out.png differ diff --git a/docs/boards/backlogs/media/add-link/insert-shared-steps.png b/docs/boards/backlogs/media/add-link/insert-shared-steps.png new file mode 100644 index 00000000000..aa49063b3b9 Binary files /dev/null and b/docs/boards/backlogs/media/add-link/insert-shared-steps.png differ diff --git a/docs/boards/backlogs/media/add-link/keyword-pr-link.png b/docs/boards/backlogs/media/add-link/keyword-pr-link.png new file mode 100644 index 00000000000..ec03dd3d282 Binary files /dev/null and b/docs/boards/backlogs/media/add-link/keyword-pr-link.png differ diff --git a/docs/boards/backlogs/media/add-link/link-git-branch.png b/docs/boards/backlogs/media/add-link/link-git-branch.png index f9ec41af944..9e487c034bc 100644 Binary files a/docs/boards/backlogs/media/add-link/link-git-branch.png and b/docs/boards/backlogs/media/add-link/link-git-branch.png differ diff --git a/docs/boards/backlogs/media/add-link/link-pr-to-work-item.png b/docs/boards/backlogs/media/add-link/link-pr-to-work-item.png new file mode 100644 index 00000000000..b2acf3297fd Binary files /dev/null and b/docs/boards/backlogs/media/add-link/link-pr-to-work-item.png differ diff --git a/docs/boards/backlogs/media/add-link/link-tab-remote-links.png b/docs/boards/backlogs/media/add-link/link-tab-remote-links.png deleted file mode 100644 index 751704a65d0..00000000000 Binary files a/docs/boards/backlogs/media/add-link/link-tab-remote-links.png and /dev/null differ diff --git a/docs/boards/backlogs/media/add-link/links-tab-remote-links.png b/docs/boards/backlogs/media/add-link/links-tab-remote-links.png new file mode 100644 index 00000000000..9e30b0bf141 Binary files /dev/null and b/docs/boards/backlogs/media/add-link/links-tab-remote-links.png differ diff --git a/docs/boards/backlogs/media/add-link/multi-select-add-link.png b/docs/boards/backlogs/media/add-link/multi-select-add-link.png new file mode 100644 index 00000000000..fe6f9757b54 Binary files /dev/null and b/docs/boards/backlogs/media/add-link/multi-select-add-link.png differ diff --git a/docs/boards/backlogs/media/add-link/new-issue-linked-item.png b/docs/boards/backlogs/media/add-link/new-issue-linked-item.png index 24bb642cbff..0024e891a10 100644 Binary files a/docs/boards/backlogs/media/add-link/new-issue-linked-item.png and b/docs/boards/backlogs/media/add-link/new-issue-linked-item.png differ diff --git a/docs/boards/backlogs/media/add-link/work-item-add-link-sequence.png b/docs/boards/backlogs/media/add-link/work-item-add-link-sequence.png new file mode 100644 index 00000000000..c824dea2b74 Binary files /dev/null and b/docs/boards/backlogs/media/add-link/work-item-add-link-sequence.png differ diff --git a/docs/boards/backlogs/media/add-work-item-copy-URL.png b/docs/boards/backlogs/media/add-work-item-copy-URL.png index 7f3b4c88234..9573ba748cd 100644 Binary files a/docs/boards/backlogs/media/add-work-item-copy-URL.png and b/docs/boards/backlogs/media/add-work-item-copy-URL.png differ diff --git a/docs/boards/backlogs/media/backlog-child-closes-parent.gif b/docs/boards/backlogs/media/backlog-child-closes-parent.gif new file mode 100644 index 00000000000..4dc801f34cf Binary files /dev/null and b/docs/boards/backlogs/media/backlog-child-closes-parent.gif differ diff --git a/docs/boards/backlogs/media/backlog-settings.png b/docs/boards/backlogs/media/backlog-settings.png new file mode 100644 index 00000000000..7f3750a6018 Binary files /dev/null and b/docs/boards/backlogs/media/backlog-settings.png differ diff --git a/docs/boards/backlogs/media/backlog-team-selector.png b/docs/boards/backlogs/media/backlog-team-selector.png new file mode 100644 index 00000000000..0dd0f97ab41 Binary files /dev/null and b/docs/boards/backlogs/media/backlog-team-selector.png differ diff --git a/docs/boards/backlogs/media/bulk-m-backlog-menu-options-ts.png b/docs/boards/backlogs/media/bulk-m-backlog-menu-options-ts.png index 2595993e4d2..e281eb7c3f4 100644 Binary files a/docs/boards/backlogs/media/bulk-m-backlog-menu-options-ts.png and b/docs/boards/backlogs/media/bulk-m-backlog-menu-options-ts.png differ diff --git a/docs/boards/backlogs/media/bulk-m-query-results-menu-options-ts.png b/docs/boards/backlogs/media/bulk-m-query-results-menu-options-ts.png index 7507273375b..11484de6199 100644 Binary files a/docs/boards/backlogs/media/bulk-m-query-results-menu-options-ts.png and b/docs/boards/backlogs/media/bulk-m-query-results-menu-options-ts.png differ diff --git a/docs/boards/backlogs/media/confirm-delete-attachment.png b/docs/boards/backlogs/media/confirm-delete-attachment.png new file mode 100644 index 00000000000..1d6b1345b42 Binary files /dev/null and b/docs/boards/backlogs/media/confirm-delete-attachment.png differ diff --git a/docs/boards/backlogs/media/confirm-permanently-delete-attachment.png b/docs/boards/backlogs/media/confirm-permanently-delete-attachment.png new file mode 100644 index 00000000000..9899ed3c2e1 Binary files /dev/null and b/docs/boards/backlogs/media/confirm-permanently-delete-attachment.png differ diff --git a/docs/boards/backlogs/media/confirm-restore.png b/docs/boards/backlogs/media/confirm-restore.png new file mode 100644 index 00000000000..326d8b47353 Binary files /dev/null and b/docs/boards/backlogs/media/confirm-restore.png differ diff --git a/docs/boards/backlogs/media/copy-work-item-copy-to-clipboard-ts-1.png b/docs/boards/backlogs/media/copy-work-item-copy-to-clipboard-ts-1.png index aee3b0e2cdf..24f1d62b66b 100644 Binary files a/docs/boards/backlogs/media/copy-work-item-copy-to-clipboard-ts-1.png and b/docs/boards/backlogs/media/copy-work-item-copy-to-clipboard-ts-1.png differ diff --git a/docs/boards/backlogs/media/create-backlog/backlog-team-selector.png b/docs/boards/backlogs/media/create-backlog/backlog-team-selector.png new file mode 100644 index 00000000000..8746fc485ca Binary files /dev/null and b/docs/boards/backlogs/media/create-backlog/backlog-team-selector.png differ diff --git a/docs/boards/backlogs/media/create-backlog/completed-child-items-control-2020.png b/docs/boards/backlogs/media/create-backlog/completed-child-items-control-2020.png index 9b78fb5f1f3..0e283122c3b 100644 Binary files a/docs/boards/backlogs/media/create-backlog/completed-child-items-control-2020.png and b/docs/boards/backlogs/media/create-backlog/completed-child-items-control-2020.png differ diff --git a/docs/boards/backlogs/media/create-backlog/in-progress-control-2020.png b/docs/boards/backlogs/media/create-backlog/in-progress-control-2020.png index 19c3e84a253..67602682f22 100644 Binary files a/docs/boards/backlogs/media/create-backlog/in-progress-control-2020.png and b/docs/boards/backlogs/media/create-backlog/in-progress-control-2020.png differ diff --git a/docs/boards/backlogs/media/create-backlog/open-backlogs.png b/docs/boards/backlogs/media/create-backlog/open-backlogs.png new file mode 100644 index 00000000000..711d5943838 Binary files /dev/null and b/docs/boards/backlogs/media/create-backlog/open-backlogs.png differ diff --git a/docs/boards/backlogs/media/create-backlog/open-column-options.png b/docs/boards/backlogs/media/create-backlog/open-column-options.png new file mode 100644 index 00000000000..a5c3d950281 Binary files /dev/null and b/docs/boards/backlogs/media/create-backlog/open-column-options.png differ diff --git a/docs/boards/backlogs/media/delete-attachment.png b/docs/boards/backlogs/media/delete-attachment.png new file mode 100644 index 00000000000..918f5a5ee11 Binary files /dev/null and b/docs/boards/backlogs/media/delete-attachment.png differ diff --git a/docs/boards/backlogs/media/filter-backlogs-options.png b/docs/boards/backlogs/media/filter-backlogs-options.png index 9ef25086c48..a3e54b3aa0e 100644 Binary files a/docs/boards/backlogs/media/filter-backlogs-options.png and b/docs/boards/backlogs/media/filter-backlogs-options.png differ diff --git a/docs/boards/backlogs/media/multi-ownership/backlog-parents-on.png b/docs/boards/backlogs/media/multi-ownership/backlog-parents-on.png new file mode 100644 index 00000000000..fc805ed23b9 Binary files /dev/null and b/docs/boards/backlogs/media/multi-ownership/backlog-parents-on.png differ diff --git a/docs/boards/backlogs/media/open-boards-backlogs.png b/docs/boards/backlogs/media/open-boards-backlogs.png new file mode 100644 index 00000000000..0b22b2e662c Binary files /dev/null and b/docs/boards/backlogs/media/open-boards-backlogs.png differ diff --git a/docs/boards/backlogs/media/open-column-options.png b/docs/boards/backlogs/media/open-column-options.png new file mode 100644 index 00000000000..b3934be3927 Binary files /dev/null and b/docs/boards/backlogs/media/open-column-options.png differ diff --git a/docs/boards/backlogs/media/permanently-delete-attachment.png b/docs/boards/backlogs/media/permanently-delete-attachment.png new file mode 100644 index 00000000000..d8857ee5182 Binary files /dev/null and b/docs/boards/backlogs/media/permanently-delete-attachment.png differ diff --git a/docs/boards/backlogs/media/resolve/sprint-backlog-hierarchy.png b/docs/boards/backlogs/media/resolve/sprint-backlog-hierarchy.png index 9645df6871f..bb8f5071aca 100644 Binary files a/docs/boards/backlogs/media/resolve/sprint-backlog-hierarchy.png and b/docs/boards/backlogs/media/resolve/sprint-backlog-hierarchy.png differ diff --git a/docs/boards/backlogs/media/resolve/sprint-backlog-leaf-only.png b/docs/boards/backlogs/media/resolve/sprint-backlog-leaf-only.png index c5062e5ab69..95a7009bd35 100644 Binary files a/docs/boards/backlogs/media/resolve/sprint-backlog-leaf-only.png and b/docs/boards/backlogs/media/resolve/sprint-backlog-leaf-only.png differ diff --git a/docs/boards/backlogs/media/restore-work-item.png b/docs/boards/backlogs/media/restore-work-item.png new file mode 100644 index 00000000000..4d4f347cb2d Binary files /dev/null and b/docs/boards/backlogs/media/restore-work-item.png differ diff --git a/docs/boards/backlogs/media/rollup/add-rollup-column-from-quick-list.png b/docs/boards/backlogs/media/rollup/add-rollup-column-from-quick-list.png index 15ed083f243..9db2586e759 100644 Binary files a/docs/boards/backlogs/media/rollup/add-rollup-column-from-quick-list.png and b/docs/boards/backlogs/media/rollup/add-rollup-column-from-quick-list.png differ diff --git a/docs/boards/backlogs/media/rollup/custom-rollup-column-dialog.png b/docs/boards/backlogs/media/rollup/custom-rollup-column-dialog.png index 46592b0609f..5ac386987fc 100644 Binary files a/docs/boards/backlogs/media/rollup/custom-rollup-column-dialog.png and b/docs/boards/backlogs/media/rollup/custom-rollup-column-dialog.png differ diff --git a/docs/boards/backlogs/media/rollup/epic-featurs-progress-user-stories-50-percent.png b/docs/boards/backlogs/media/rollup/epic-features-progress-user-stories-50-percent.png similarity index 100% rename from docs/boards/backlogs/media/rollup/epic-featurs-progress-user-stories-50-percent.png rename to docs/boards/backlogs/media/rollup/epic-features-progress-user-stories-50-percent.png diff --git a/docs/boards/backlogs/media/rules-applied-several-backlog-levels.gif b/docs/boards/backlogs/media/rules-applied-several-backlog-levels.gif new file mode 100644 index 00000000000..d34384884b6 Binary files /dev/null and b/docs/boards/backlogs/media/rules-applied-several-backlog-levels.gif differ diff --git a/docs/boards/backlogs/media/select-product-backlog-agile.png b/docs/boards/backlogs/media/select-product-backlog-agile.png new file mode 100644 index 00000000000..c14216b9543 Binary files /dev/null and b/docs/boards/backlogs/media/select-product-backlog-agile.png differ diff --git a/docs/boards/backlogs/media/set-team-automation-rules.png b/docs/boards/backlogs/media/set-team-automation-rules.png new file mode 100644 index 00000000000..9c50042094a Binary files /dev/null and b/docs/boards/backlogs/media/set-team-automation-rules.png differ diff --git a/docs/boards/backlogs/media/sprintboard-drag-and-drop-update-parent.gif b/docs/boards/backlogs/media/sprintboard-drag-and-drop-update-parent.gif new file mode 100644 index 00000000000..4d61641d581 Binary files /dev/null and b/docs/boards/backlogs/media/sprintboard-drag-and-drop-update-parent.gif differ diff --git a/docs/boards/backlogs/media/wi-templates-new-template.png b/docs/boards/backlogs/media/wi-templates-new-template.png index a21eadbf445..e3e36b5048a 100644 Binary files a/docs/boards/backlogs/media/wi-templates-new-template.png and b/docs/boards/backlogs/media/wi-templates-new-template.png differ diff --git a/docs/boards/backlogs/media/wi-templates-template-action-menu.png b/docs/boards/backlogs/media/wi-templates-template-action-menu.png index 75c7327d963..adb8f09a29c 100644 Binary files a/docs/boards/backlogs/media/wi-templates-template-action-menu.png and b/docs/boards/backlogs/media/wi-templates-template-action-menu.png differ diff --git a/docs/boards/backlogs/media/work-items-recycle-bin.png b/docs/boards/backlogs/media/work-items-recycle-bin.png new file mode 100644 index 00000000000..4fcf966b6f8 Binary files /dev/null and b/docs/boards/backlogs/media/work-items-recycle-bin.png differ diff --git a/docs/boards/backlogs/move-change-type.md b/docs/boards/backlogs/move-change-type.md index ceae9f1d03a..da406f0d91e 100644 --- a/docs/boards/backlogs/move-change-type.md +++ b/docs/boards/backlogs/move-change-type.md @@ -1,67 +1,55 @@ --- -title: Move work items and change the work item type in Azure Boards +title: Move work items and change the work item type in Azure Boards titleSuffix: Azure Boards description: Learn how to change the work item type or bulk move work items to another project in Azure Boards. -ms.custom: "boards-backlogs, seodec18, cross-project" +ms.custom: boards-backlogs, cross-project ms.service: azure-devops-boards +ai-usage: ai-assisted ms.author: chcomley author: chcomley -ms.topic: tutorial -monikerRange: '>= azure-devops-2019' -ms.date: 06/27/2022 +ms.topic: how-to +monikerRange: "<=azure-devops" +ms.date: 11/22/2024 --- # Bulk move work items and change the work item type in Azure Boards [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Often you find that someone created a work item of the wrong work item type (WIT) or within an incorrect project. You can correct these issues for individual work items or bulk modify several work items. You can also remove work items added to your backlog or taskboard that aren't relevant anymore. +Sometimes, work items get created with the wrong type or assigned to an incorrect project. You can correct these issues by updating individual work items or bulk modifying multiple items. You can also remove irrelevant work items from your backlog or Taskboard. -> [!TIP] -> For TFS 2018 and earlier versions, you can't change the work item type for an existing work item, but you can [copy the work item and specify a new type](copy-clone-work-items.md#copy-clone). Also, if you have several work items with type changes you want to make, you can [export them using Excel](office/bulk-add-modify-work-items-excel.md), and then re-add them as a new type. +To change the type of multiple work items, [export them using Excel](office/bulk-add-modify-work-items-excel.md) and reimport them with the correct type. -To remove, delete, or restore deleted work items, see [Remove, delete, or restore work items](remove-delete-work-items.md). - -In this article you'll learn: - -> [!div class="checklist"] -> * How to change the work item type of one or more work items -> * How to move one or more work items to another project - - -> [!TIP] -> From the web portal, you can [multi-select several work items](bulk-modify-work-items.md) from a backlog or query results page and perform a bulk update using the associated feature. To change, move, delete, or restore several work items at the same time, see [Bulk modify work items](bulk-modify-work-items.md). +In the web portal, [multi-select work items](bulk-modify-work-items.md) from a backlog or query results page to perform bulk updates. To change, move, delete, or restore multiple work items simultaneously, see [Bulk modify work items](bulk-modify-work-items.md).Often you find that someone created a work item of the wrong work item type (WIT) or within an incorrect project. You can correct these issues for individual work items or bulk modify several work items. You can also remove work items added to your backlog or Taskboard that aren't relevant anymore. +For instructions on removing, deleting, or restoring work items, see [Remove, delete, or restore work items](remove-delete-work-items.md). ## Prerequisites ::: moniker range="azure-devops" -* You must be a member of the **Contributors** or **Project Administrators** security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To modify work items, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* To change the work item type, you must be granted **Stakeholder** access or higher. -* To move work items to another project, you must be a member of the **Project Administrators** group or have the **Move work items out of this project** permission set to **Allow**. By default, the **Contributors** group doesn't have this permission set. Users granted **Stakeholder** access don't have access to this feature. +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - Member of the **Contributors** or **Project Administrators** group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md).
- To modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md).
- To move work items to another project: Member of the **Project Administrators** group or **Move work items out of this project** permission set to **Allow**. By default, the **Contributors** group doesn't have this permission. Users with **Stakeholder** access don't have access to this feature. | +| **Access levels** | To change the work item type: At least **Stakeholder** access. | > [!NOTE] -> Users with **Stakeholder** access for a public project have full access to all work tracking features just like users with **Basic** access. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). +> Users with **Stakeholder** access for a public project have full access to all work tracking features just like users with [**Basic** access](../../organizations/security/access-levels.md). For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - -* You must be added to a project as a member of the **Contributors** or **Project Administrators** security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To modify work items, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* To change the work item type, you must be granted **Stakeholder** access or higher. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -* To move work items to another project, the project must use an Inherited process model. -* To move work items to another project, you must be a member of the **Project Administrators** group or have the **Move work items out of this project** permission set to **Allow**. By default, the **Contributors** group doesn't have this permission set. Users granted **Stakeholder** access don't have access to this feature. +::: moniker range=" < azure-devops" +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - Member of the **Contributors** or **Project Administrators** group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md).
- To modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md).
- To move work items to another project: Member of the **Project Administrators** group or **Move work items out of this project** permission set to **Allow**. By default, the **Contributors** group doesn't have this permission. Users with **Stakeholder** access don't have access to this feature. Also, the project must use an Inherited process model. | +| **Access levels** | To change the work item type: At least **Stakeholder** access. | - > [!IMPORTANT] - > You can change the work item type or move work items to another project within a project collection. These features require that the data warehouse is disabled. With the data warehouse disabled, you'll use the [Analytics Service](../../report/powerbi/what-is-analytics.md) to support your reporting needs. To learn more about disabling the data warehouse, see [Disable the data warehouse and cube](/previous-versions/azure/devops/report/admin/disable-data-warehouse). +You can change the work item type or move work items to another project within a project collection. These features require that the data warehouse is disabled. With the data warehouse disabled, you use the [Analytics Service](../../report/powerbi/what-is-analytics.md) to support your reporting needs. For more information about disabling the data warehouse, see [Disable the data warehouse and cube](/previous-versions/azure/devops/report/admin/disable-data-warehouse). ::: moniker-end -For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md) or [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). +For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). ::: moniker range="azure-devops" @@ -70,12 +58,12 @@ For more information, see [Set permissions and access for work tracking](../../o ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" > [!IMPORTANT] -> You can't change type, move work items, or delete/restore work items whose work item types support test management or that belong to the [Hidden Types Category](../work-items/agile-glossary.md#hidden-types). This includes all work items that track tests—such as test cases, shared steps, and shared parameters—code review requests and responses, and feedback requests and responses. +> - You can't change type, move work items, or delete/restore work items whose work item types support test management or that belong to the [Hidden Types Category](../work-items/agile-glossary.md#hidden-types). This includes all work items that track tests—such as test cases, shared steps, and shared parameters—code review requests and responses, and feedback requests and responses. > -> Also, you can't change the work item type if the project is defined on a collection that uses the On-premises XML process model. +> - You can't change the work item type if the project is defined on a collection that uses the On-premises XML process model. ::: moniker-end @@ -83,10 +71,7 @@ For more information, see [Set permissions and access for work tracking](../../o ## Change the work item type -Changing the work item type refreshes the work item form with the fields defined for the type selected. For example, you can change a bug to a task and the form refreshes with the fields defined for a task. - -> [!NOTE] -> You can't change the work item type if the project is defined on a collection that uses the On-premises XML process model. Also, you can't change the work item type of work items associated with test management. +Changing the work item type refreshes the work item form with the fields defined for the type selected. For example, you can change a bug to a task and the form refreshes with the fields defined for a task. You can change a single work item or several [multi-selected work items](bulk-modify-work-items.md) to a new type. @@ -108,31 +93,29 @@ You can change a single work item or several [multi-selected work items](bulk-mo ![Change work item type dialog](media/move-change-delete/change-work-item-type-dialog.png) - Comments are automatically added to the [**Discussion** control](../work-items/work-item-form-controls.md#discussion) and an entry is made to the **History** control. Also, the system automatically resets the State and Reason fields to the default initial values for the work item type that you move. + Comments are automatically added to the **Discussion** and an entry gets made to the **History**. Also, the system automatically resets the State and Reason fields to the default initial values for the work item type that you move. -3. Save the work item(s) to complete the change. +3. **Save** the work items. > [!NOTE] > The system automatically resets the **State** and **Reason** fields to the default initial values of the specified type. However, in some cases you may need to open the work item to change the **State** or **Reason** field to a value supported by the changed-to work item type. - From the **Query Results** page, save all work items that you bulk-modified. When you bulk modify items from the backlog, they're automatically saved. Work items shown in bold text indicate that local changes haven't yet been saved to the data store. The system automatically saves each work item. Refresh the page to reflect your changes. + From the **Query Results** page, save all work items that you bulk-modified. When you bulk modify items from the backlog, they're automatically saved. Work items shown in bold text indicate that local changes aren't saved to the data store. The system automatically saves each work item. To reflect your changes, refresh. ## Move a work item to another project -When you discover that a work item belongs to a different project within your organization or collection, you can move it where it belongs. You can move a single work item or several [multi-selected work items](bulk-modify-work-items.md). +When you realize that a work item is assigned to the wrong project within your organization or collection, you can move it to the appropriate project. You can relocate either a single work item or multiple [selected work items](bulk-modify-work-items.md). -Note the following: -- You can only move work items from one project to another project within the organization or collection. -- You can only move work items whose type exists in the project you're moving it to. For example, you can't move User Stories to a project based on the Scrum process that doesn't contain User Story as a work item type. -- You can't move work items associated with test management. -- To move work items to another project, you must be a member of the Project Administrators group or be [granted explicit permissions to move work items](../../organizations/security/set-permissions-access-work-tracking.md#move-delete-permissions). -- Users granted **Stakeholder** access don't have access to this feature even if granted permission. +> [!IMPORTANT] +> **Permanent and irreversible deletion:** Azure DevOps only supports the permanent deletion of test artifacts, including test plans, test suites, test cases, shared steps, and shared parameters. Deleted artifacts cannot be restored, and all associated child items, such as test results, are also removed. Additionally, bulk deletion of test artifacts is not supported; attempting to bulk delete will result in the deletion of all other selected work items except the test artifacts. +> +> **Ensure you back up any necessary information before deleting test artifacts, as this action can't be undone.** 1. Open the work item and choose the ![Move work item icon](../media/icons/change-team-project-icon.png) **Move...** option from the work item form's ![Action icon](../media/icons/actions-icon.png) Actions menu. - If you don't see the option, then you haven't been granted [permissions to move work items out of the project](../../organizations/security/set-permissions-access-work-tracking.md#move-delete-permissions). + If you don't see the option, then you don't have [permissions to move work items out of the project](../../organizations/security/set-permissions-access-work-tracking.md#move-delete-permissions). Or, from the backlog or query results page, multi-select several work items that you want to move to another project. You can select several work items so long as you want to move them all to the same project. @@ -143,18 +126,18 @@ Note the following: ::: moniker range="azure-devops" :::image type="content" source="media/move-change-delete/move-work-item-change-type-dialog.png" alt-text="Move work item type and change type dialog."::: ::: moniker-end - ::: moniker range=">= azure-devops-2019 < azure-devops" + ::: moniker range=" [!NOTE] - > Child work items are not moved. They remain in the origin project, but the Parent-Child links remain in place. - - Comments are automatically added to the [**Discussion** control](../work-items/work-item-form-controls.md#discussion) and an entry is made to the **History** control. Also, the system automatically resets the State and Reason fields to the default initial values for the work item type that you move. + > Child work items don't get moved and remain in the origin project, but the Parent-Child links remain in place. + Comments are automatically added to the **Discussion** and an entry gets made to the **History**. Also, the system automatically resets the State and Reason fields to the default initial values for the work item type that you move. ## Related articles - [Remove or delete work items](remove-delete-work-items.md) - [View and add work items using the Work Items page](../work-items/view-add-work-items.md) -- [Best tool to add, update, and link work items](../work-items/best-tool-add-update-link-work-items.md) +- [Add or modify work items in bulk with Microsoft Excel](./office/bulk-add-modify-work-items-excel.md) +- [Import, update, and export bulk work items with CSV files](../queries/import-work-items-from-csv.md) diff --git a/docs/boards/backlogs/office/bulk-add-modify-work-items-excel.md b/docs/boards/backlogs/office/bulk-add-modify-work-items-excel.md index 690102becaa..960f7941fce 100644 --- a/docs/boards/backlogs/office/bulk-add-modify-work-items-excel.md +++ b/docs/boards/backlogs/office/bulk-add-modify-work-items-excel.md @@ -1,153 +1,128 @@ --- title: Modify Azure Boards work items in bulk with Microsoft Excel -titleSuffix: Azure Boards -description: Use the Excel plugin in Azure DevOps to bulk add or modify Azure Boards work items, such as tasks, bugs, backlog items, or issues. +titleSuffix: Azure Boards +description: Use the Excel plugin in Azure DevOps to bulk add or modify Azure Boards work items, such as tasks, bugs, backlog items, or issues. ms.service: azure-devops-boards ms.assetid: 1399B4B1-72AE-4328-AAD8-3AAF0B808761 ms.author: chcomley author: chcomley -ms.custom: "contperf-fy20q4, linked-from-support" +ms.custom: linked-from-support ms.topic: tutorial +ai-usage: ai-assisted monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 08/19/2024 --- - -# Add or modify Azure Boards work items in bulk with Microsoft Excel +# Add or modify work items in bulk with Microsoft Excel [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -When you need to add or modify many work items, using Microsoft Excel can save you time. Excel supports adding work items, updating existing work items, adding links and attachments to multiple work items, and more. You can also use native Excel features to support other actions, such as summing a column, copy-and-paste rows, fill down data into cells, and more. - -In this article you'll learn how to complete the following tasks: +::: moniker range=">= azure-devops-2020" +> [!TIP] +> To import or update work items in bulk, you can use either the [web portal](../bulk-modify-work-items.md) or the [CSV import](../../queries/import-work-items-from-csv.md) feature, which is the recommended approach. +::: moniker-end -> [!div class="checklist"] -> * Choose the type of list or query to support your task -> * Use select Excel features when connected to Azure Boards -> * Import or update work items, either a flat list or hierarchy tree list -> * Publish and refresh your work items -> * Convert a flat-list to a tree-list, change your list type or query -> * Add work items to your worksheet -> * Add and remove work item fields from your worksheet -> * Select user accounts for identity or person-named fields -> * Link work items, find work items to link to, edit links, and more -> * Add attachments to one or more work items -> * Open a work item from Excel to add additional information (opens in web portal) -> * Edit Area and Iteration Paths (opens in web portal) +Save time with Microsoft Excel when you need to add or modify many work items, add links and attachments to multiple work items, and more. You can also use native Excel features to perform actions such as summing a column, copying and pasting rows, filling down data into cells, and more. -For information about connecting to Excel, see [Connect Azure Boards to an Office client](track-work.md). For answers to specific questions about the integration of Excel and Azure DevOps, see [FAQs: Work in Excel connected to Azure Boards ](faqs.yml). - -::: moniker range=">= azure-devops-2020" +For information about connecting to Excel, see [Connect Azure Boards to an Office client](track-work.md). For answers to specific questions about the integration of Excel and Azure DevOps, see [FAQs: Work in Excel connected to Azure Boards](faqs.yml). > [!NOTE] -> If you don't have access to Excel, you can still perform bulk import and update using CSV formatted files. For more information, see [Bulk import or update work items using CSV files](../../queries/import-work-items-from-csv.md). - -::: moniker-end +> macOS is not supported. Even with Visual Studio for Mac installed, connecting to Azure DevOps from Excel is not supported. ## Prerequisites -> [!NOTE] -> macOS isn't supported. Even if you've installed Visual Studio for Mac, connection to Azure DevOps from Excel isn't supported. +::: moniker range="azure-devops" -::: moniker range="azure-devops" +|Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../../organizations/security/add-users-team-project.md). | +| **Access levels** |At least [Stakeholder access](../../../organizations/security/stakeholder-access.md). | +| **Permissions** | - Member of the **Contributors** group.
- **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission. For more information, see [Set permissions and access for work tracking](../../../organizations/security/set-permissions-access-work-tracking.md). | +| **Tools** |- Microsoft Excel 2010 or later, including Microsoft Office Excel 365.
- [Azure DevOps Office Integration 2019 (free)](https://visualstudio.microsoft.com/downloads/#other-family). Install the Azure DevOps Office Integration plug-in by installing one of the latest editions of Visual Studio or the Azure DevOps Office Integration installer. The plug-in supports connection to Azure Boards and Azure DevOps Server from Excel.
- [Visual Studio 2015.1 or later](https://visualstudio.microsoft.com/downloads/) or [Team Foundation Server Office Integration 2015 Update 2 or later](https://visualstudio.microsoft.com/downloads/) To use the [Select User](#select-user) feature, download the free version of Visual Studio Community. This feature helps avoid data validation errors by misspelling user names and is useful when assigning user names from a large group of user accounts. | -- Installed Microsoft Excel 2010 or later version, including Microsoft Office Excel 365 -- Installed [Azure DevOps Office Integration 2019 (free)](https://visualstudio.microsoft.com/downloads/#other-family). - > [!NOTE] - > The only way to get the Azure DevOps Office Integration plug-in is by installing one of the latest editions of Visual Studio or the Azure DevOps Office Integration installer. The plug-in supports connection to Azure Boards and Azure DevOps Server from Excel. -- To connect to an Azure Boards project, you need to be a [member of the project](../../../organizations/security/add-users-team-project.md). If you don't have an Azure Boards project yet, you can [create one](../../get-started/sign-up-invite-teammates.md). -- To view or modify work items, you must have these permissions set to **Allow**: **View work items in this node** and **Edit work items in this node**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../../organizations/security/set-permissions-access-work-tracking.md). -- To add or modify work items, you must be granted **Stakeholder** access or higher. For more information, see [Stakeholder access quick reference](../../../organizations/security/stakeholder-access.md). -- To use the [Select User](#select-user) feature, you need to install [Visual Studio (at least VS 2015.1 or later version](https://visualstudio.microsoft.com/downloads/) or [Team Foundation Server Office Integration 2015 Update 2 or later version](https://visualstudio.microsoft.com/downloads/). You can download the free version of Visual Studio Community. Get this feature to avoid data validation errors by misspelling user names and when you must assign user names from a large group of user accounts. - -::: moniker-end +::: moniker-end ::: moniker range="< azure-devops" -- Installed Microsoft Excel 2010 or later version, including Microsoft Office Excel 365 -- Installed [Azure DevOps Office Integration 2019 (free)](https://visualstudio.microsoft.com/downloads/#other-family). - > [!NOTE] - > The only way to get the plug-in is by installing one of the latest editions of Visual Studio or the Azure DevOps Standalone Office Integration installer. The Azure DevOps Office Integration 2019 plug-in supports connection to Azure Boards and Azure DevOps from Excel, Project, and the PowerPoint-based storyboarding tool. -- To connect to an Azure Boards project, you need to be a [member of the project](../../../organizations/security/add-users-team-project.md). If you don't have an Azure Boards project yet, you can [create one](../../../organizations/projects/create-project.md). -- To view or modify work items, you must have these permissions set to **Allow**: **View work items in this node** and **Edit work items in this node**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../../organizations/security/set-permissions-access-work-tracking.md). -- To add or modify work items, you must be granted **Stakeholder** access or higher. For more information, see [Stakeholder access quick reference](../../../organizations/security/stakeholder-access.md). -- To use the [Select User](#select-user) feature, install [Visual Studio (at least VS 2015.1 or later version](https://visualstudio.microsoft.com/downloads/) or [Team Foundation Server Office Integration 2015 Update 2 or later version](https://visualstudio.microsoft.com/downloads/). You can download the free version of Visual Studio Community. Get this feature to avoid data validation errors by misspelling user names and when you must assign user names from a large group of user accounts. +|Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../../organizations/security/add-users-team-project.md). | +| **Access levels** |At least [Stakeholder access](../../../organizations/security/stakeholder-access.md). | +| **Permissions** | - Member of the **Contributors** group.
- *View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission. For more information, see [Set permissions and access for work tracking](../../../organizations/security/set-permissions-access-work-tracking.md). | +| **Tools** |- Microsoft Excel 2010 or later, including Microsoft Office Excel 365.
- [Azure DevOps Office Integration 2019 (free)](https://visualstudio.microsoft.com/downloads/#other-family). Install the plug-in by installing one of the latest editions of Visual Studio or the Azure DevOps Standalone Office Integration installer. The Azure DevOps Office Integration 2019 plug-in supports connection to Azure Boards and Azure DevOps from Excel, Project, and the PowerPoint-based storyboarding tool.
- To use the [Select User](#select-user) feature, install [Visual Studio 2015.1 or later](https://visualstudio.microsoft.com/downloads/) or [Azure DevOps Office Integration 2019 or later](https://visualstudio.microsoft.com/downloads/#azure-devops-office-integration-2019). You can download the free version of Visual Studio Community. This feature helps avoid data validation errors by misspelling user names and is useful when assigning user names from a large group of user accounts.| ::: moniker-end -To learn more about compatibility requirements, see [Compatibility with Azure DevOps Server](/azure/devops/server/compatibility). +For more information, see [Compatibility with Azure DevOps Server](/azure/devops/server/compatibility). -## Choose list and query type +## Use list and query types -When you work in Excel connected to Azure Boards, you're always working with a query type and a list type. Queries correspond to the queries you create using the Query Editor. -- **Query types**: - - **None**: Indicates it's an **input list**. - - **Query title**: Indicates the list of work items is tied to the specified **query**. -- **List types**: - - **Flat list**: Simple list of work items that shows a single **Title** column. No link management is supported. - - **Tree list**: Hierarchical list of work items that support creating and updating tree topology links, such as Parent-Child links, between work items. These lists include two or more **Title** columns. +You can add, modify, publish, and refresh work items using any query type and list type. -You can add, modify, publish, and refresh work items using any query type and list type. +- [Use a flat list](../../queries/using-queries.md#flat-list) to bulk add or modify several types of work items at once, such as backlog items, tasks, bugs, or issues. +- [Use a tree list](../../queries/using-queries.md) to bulk add or modify work items and their tree-topology links. -### Query types +Follow these best practices: -Azure Boards supports three query types. The icon next to each query indicates the query type. The first two query types, **Flat list of work items** and **Work items and direct links** are imported as flat list queries. - -> [!div class="mx-imgBorder"] -> ![Query type icon list](media/excel/query-types.png) - -Only the **Tree of work items** queries import as a tree list. Direct links queries are imported as a flat list into Excel as modifying multiple types of links aren't a supported feature in Excel. - - +::: moniker range="azure-devops" +- **Input list, flat list**: Import a list of work items or create new work items without hierarchy. +- **Input list, tree list**: Complete top-down planning and import hierarchically linked work items. +- **Query list, tree list**: View and modify the hierarchy of link relationships of many existing work items. +- **Query list, flat list**: Bulk update a list of work items or create new work items without hierarchy. +::: moniker-end -### Tree lists +::: moniker range="< azure-devops" +- **Input list, flat list**: Import a list of work items or create new work items without hierarchy. +- **Input list, tree list**: Complete top-down planning and publish parent-child linked work items. +- **Query list, flat list**: Create an Excel report based on the query of work items. To create an Excel report, your project collection must be configured to support Analytics reporting. For more information, see [Create Excel reports from a work item query](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports). +- **Query list, tree list**: View and modify the hierarchy and parent-child link relationships of many existing work items. +::: moniker-end -You can bulk add a nested list of work items, such as a work breakdown structure or a hierarchical set of user stories and customer experiences. For example, you can add a nested list of tasks, subtasks, and bugs, as shown in the following illustration, or linked tasks to product backlog items. +### Query types -Here's how a three-level nested tree of items appears in Excel. +**Query types**: +- **None**: Indicates an **input list**. +- **Query title**: Indicates the list of work items is tied to the specified **query**. -![Tree list of work items, conceptual image](media/IC354953.png) +Azure Boards supports three query types, indicated by icons next to each query: -Parent-child links or other tree topology link types support creating a hierarchical backlog structure. The work item types that participate in the hierarchy differ with different processes and are shown in the following images. +- **Flat list of work items**: Imported as a flat list query. +- **Work items and direct links**: Imported as a flat list query. +- **Tree of work items**: Imported as a tree list. -[!INCLUDE [temp](../../includes/work-item-types.md)] +:::image type="content" source="media/excel/query-types.png" alt-text="Screenshot of query type icon list."::: -To import a hierarchical list, see [Add or import a hierarchical list of work items](#add-work-items-tree) later in this article. +Direct links queries are imported as a flat list into Excel, as modifying multiple types of links isn't supported in Excel. -### My queries versus shared queries + -You can open in Excel any query you've defined in Azure Boards. That includes queries defined under My Queries and Shared Queries. However, if you plan to share the workbook with other team members, then you should only work with a Shared Query. Other team members can't use the workbook or worksheet if it's based on a personal query stored under your My Queries folder. +### Tree lists -### Use list and query types +You can bulk add a nested list of work items, such as a work breakdown structure or hierarchical user stories. For example, you can add a nested list of tasks, subtasks, and bugs, or link tasks to product backlog items. -In general, you [Use a flat list](../../queries/using-queries.md#flat-list) to bulk add or modify several types of work items at once, such as backlog items, tasks, bugs, or issues. [Use a tree list](../../queries/using-queries.md#tree-query) to bulk add or modify work items and their tree-topology links. +**List types**: +- **Flat list**: A simple list of work items with a single **Title** column. No link management is supported. +- **Tree list**: A hierarchical list of work items that supports creating and updating tree topology links, such as Parent-Child links, between work items. These lists include two or more **Title** columns. -Here's some more guidance: +:::image type="content" source="media/IC354953.png" alt-text="Screenshot of Tree list of work items, conceptual image."::: -::: moniker range="azure-devops" +Parent-child links or other tree topology link types support creating a hierarchical backlog structure. The work item types that participate in the hierarchy differ with different processes and are shown in the following images. -- Use an **input list, flat list**: To import a list of work items or create new work items, no hierarchy -- Use an **input list, tree list**: To complete top down planning and import hierarchically linked work items -- Use a **query list, tree list**: To view and modify the hierarchy of link relationships of many existing work items. -- Use a **query list, flat list**: To bulk update a list of work items or create new work items, no hierarchy +**Hierarchies** -::: moniker-end +[!INCLUDE [temp](../../includes/work-item-types.md)] -::: moniker range="< azure-devops" +To import a hierarchical list, see [Add or import a hierarchical list of work items](#add-work-items-tree) later in this article. -- Use an input list, flat list: To import a list of work items or create new work items, no hierarchy -- Use an input list, tree list: To complete top down planning and publish parent-child linked work items -- Use a query list, flat list: To create an Excel report based on the query of work items - > [!NOTE] - > To create an Excel report, you're project collection must be configured to support Analytics reporting. For more information, see [Create Excel reports from a work item query](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports). -- Use a query list, tree list: To view and modify the hierarchy and parent-child link relationships of many existing work items. +### My queries versus shared queries - -::: moniker-end +You can open any query you defined in Azure Boards in Excel, including queries under My Queries and Shared Queries. However, if you plan to share the workbook with other team members, use a Shared Query. Other team members can't access workbooks or worksheets based on personal queries stored under your My Queries folder. ## Use Excel features -You can use most Excel features when working with a list of work items. For example, you can use the following features: +You can use most Excel features when you work with a list of work items. + +**Features:** - Format a cell or apply conditional formatting to a cell or column - Cut and paste from one cell to other cells @@ -159,131 +134,107 @@ You can use most Excel features when working with a list of work items. For exam Each worksheet in Excel can contain a different input list or query. However, all worksheets within the workbook must connect to the same project within an organization or project collection. -The following features work slightly differently when working with a worksheet connected to Azure Boards. +The following features behave differently when working with a worksheet connected to Azure Boards. -- Each cell or column of cells corresponds to a work item field. Each field is associated with a data type. Excel won't allow you to enter data into a cell that doesn't meet the data type and requirements for that field. +- Each cell or column of cells corresponds to a work item field. Each field is associated with a data type. You can't enter data into an Excel cell that doesn't meet the data type and requirements for that field. - You can only insert a single row at a time within the worksheet. - You can copy and paste multiple rows within the worksheet. - To move a work item within a hierarchy, cut the entire row and paste it under the work item you want as its parent. - Use **Outdent** and **Indent** to change the location of a work item within the tree. -- Undo (Ctrl Z) may not work. If you do something that you want to revert, you can refresh the worksheet. - -We recommend you publish and refresh your worksheet often to make sure your local work remains in sync with Azure Boards data store. +- Undo (Ctrl Z) might not work. If you do something that you want to revert, you can refresh the worksheet. -To learn more about Excel, see [Basic Excel tasks](https://support.office.com/article/basic-tasks-in-excel-dc775dd1-fa52-430f-9c3c-d998d1735fca) . +We recommend you publish and refresh your worksheet often to make sure your local work remains in sync with Azure Boards data store. For more information about Excel, see [Basic Excel tasks](https://support.office.com/article/basic-tasks-in-excel-dc775dd1-fa52-430f-9c3c-d998d1735fca) . ### Sort work items -You can sort work item flat lists using the [Excel sort feature](https://support.office.com/article/sort-data-in-a-range-or-table-62d0b95d-2a90-4610-a6ae-2e545c4a4654). - -However, if you're working from a tree list, you don't want to do any type of sort. Doing so changes the tree structure and as such, the links between work items. +You can sort work item flat lists using the [Excel sort feature](https://support.office.com/article/sort-data-in-a-range-or-table-62d0b95d-2a90-4610-a6ae-2e545c4a4654). But, if you're working from a tree list, you don't want to do any type of sort. Doing so changes the tree structure and as such, the links between work items. If you want to use Excel to manage the order of your work items as they appear in a [team backlog](../create-your-backlog.md#reorder-your-backlog), you can do that by using the [Stack Rank](../../queries/planning-ranking-priorities.md#fields-table) or [Backlog Priority](../../queries/planning-ranking-priorities.md#fields-table) field (Agile or Scrum process). You can set values in these fields, publish your worksheet, and refresh your backlog. Your backlog items should appear reordered based on lowest to highest number. However, the next time the backlog is reordered from the backlog, the values you entered are subject to change. -If you want to maintain a certain order of work items, consider adding a custom field to manage the sort order, and then use that within Excel to sort your flat list of work items. This option, however, won't change the order that appears in your backlog. +To maintain a specific order of work items, consider adding a custom field to manage the sort order. You can then use this field within Excel to sort your flat list of work items. This option doesn't change the order in which work items appear in your backlog. ### Tasks you can and can't do with Excel -You can do the following tasks: +You can and can't do the following tasks from an Excel worksheet: -- Add tags and bulk update work items with tags as described in [Add work item tags to categorize and filter lists and boards](../../queries/add-tags-to-work-items.md). - Add the **Tags** field to your worksheet. Add multiple tags separated by a semicolon (;). -- You can add simple text to a rich-text field, but if you're updating several work items in bulk, you may lose formatting in existing work items. -- You can work offline and then reconnect and publish your changes. For more information, see [Connect Azure Boards to an Office client, Work offline, and reconnect](track-work.md#work-offline). +**Can do:** -You can't do the following tasks from an Excel worksheet: - -::: moniker range="azure-devops" - -- You can't delete work items -- You can't change the work item type of an existing work item -- You can't move work items to another project -- You can't import or update test case steps or other test artifacts -- You can't add work items in any other State than the new State -- You can't add to a work item discussion thread -- You can't link to a remote work item. +- Add tags and bulk update work items with tags as described in [Add work item tags to categorize and filter lists and boards](../../queries/add-tags-to-work-items.md). Add the **Tags** field to your worksheet. Add multiple tags separated by a semicolon (;). +- Add simple text to a rich-text field, but if you're updating several work items in bulk, you might lose formatting in existing work items. +- Work offline and then reconnect and publish your changes. For more information, see [Connect Azure Boards to an Office client, Work offline, and reconnect](track-work.md). +**Can't do:** +::: moniker range="azure-devops" +- Delete work items +- Change the work item type of an existing work item +- Move work items to another project +- Import or update test case steps or other test artifacts +- Add work items in any other State than the new State +- Add to a work item discussion thread +- Link to a remote work item. ::: moniker-end ::: moniker range="azure-devops-2020" - -- You can't delete work items -- You can't change the work item type of an existing work item -- You can't move work items to another project -- You can't import or update test case steps or other test artifacts -- You can't add work items in any other State than the new State -- You can't add to a work item discussion thread. - - +- Delete work items +- Change the work item type of an existing work item +- Move work items to another project +- Import or update test case steps or other test artifacts +- Add work items in any other State than the new State +- Add to a work item discussion thread. ::: moniker-end -::: moniker range="<= azure-devops-2019" - -- You can't delete work items -- You can't import or update test case steps or other test artifacts -- You can't add work items in any other State than the new State -- You can't add to a work item discussion thread - -::: moniker-end + ## Import work items as a flat list -1. Open Excel and connect to your Azure Boards project. Use one of the four methods provided in [Connect Azure DevOps project to Excel](track-work.md#excel). +1. Open Excel and connect to your Azure Boards project. Use one of the four methods provided in [Connect Azure DevOps project to Excel](track-work.md). > [!NOTE] > When you connect to Azure Boards in the cloud, the **Team Project Collection** is automatically selected as there is only one collection associated with your Azure DevOps Services organization. When you connect to Azure Boards in an on-premises server, you choose the **Team Project Collection** prior to choosing the project. -1. In Excel, start with a blank worksheet. If you don't see the **Team** ribbon (or the **Team** menu if you use Excel 2007), see [Azure DevOps Office integration issues](tfs-office-integration-issues.md). +1. In Excel, start with a blank worksheet. If you don't see the **Team** ribbon (or the **Team** menu if you use Excel 2007), ensure that you installed the [Azure DevOps Office Integration 2019 tool](https://visualstudio.microsoft.com/downloads/#other-family). For more information, see [Azure DevOps Office integration issues](tfs-office-integration-issues.md). + 1. Choose **New List** from the Team ribbon. - > [!div class="mx-imgBorder"] - > ![Choose New List](media/excel/team-ribbon.png) + :::image type="content" source="media/excel/team-ribbon.png" alt-text="Screenshot of Choose New List."::: -1. From the **New List** dialog, choose **Input list**. +1. From the **New List** dialog, choose **Input list**. - ![Select input list](media/excel/2019-input-list-dialog.png) + :::image type="content" source="media/excel/2019-input-list-dialog.png" alt-text="Screenshot of Select input list."::: -1. Your worksheet is now bound to your project as an input list (Query[None]), flat list. +1. Your worksheet is now bound to your project as an input list (Query[None]), flat list. - > [!div class="mx-imgBorder"] - > ![Empty flat list connected to a project](media/excel/2019-input-list.png) + :::image type="content" source="media/excel/2019-input-list.png" alt-text="Screenshot of Empty flat list connected to a project."::: -1. Specify the titles of the work items you want to add and their work item type. +1. Specify the titles of the work items you want to add and their work item type. - > [!div class="mx-imgBorder"] - > ![Add work items to Excel](media/excel/2019-specify-titles.png) + :::image type="content" source="media/excel/2019-specify-titles.png" alt-text="Screenshot of adding work items to Excel."::: - Notice how the **State** and **Reason** fields automatically fill in with default values once your select the work item type. + The **State** and **Reason** fields automatically populate with default values once your select the work item type. -1. Publish your worksheet. +1. **Publish** your worksheet. - > [!div class="mx-imgBorder"] - > ![Publish your worksheet.](media/excel/2019-publish.png) + :::image type="content" source="media/excel/2019-publish.png" alt-text="Screenshot of Publish your worksheet."::: Make sure your cursor is in a cell that contains data. Otherwise, the **Publish** button might appear disabled. - Notice how IDs are now assigned to your work items. + You work items now have ID numbers. - > [!div class="mx-imgBorder"] - > ![Published work item IDs show in Excel](media/excel/2019-ids-assigned.png) + :::image type="content" source="media/excel/2019-ids-assigned.png" alt-text="Screenshot of published work item IDs show in Excel."::: -1. To assign values to other fields, open [**Choose Columns**](#choose-columns), add the fields, make the assignments, and publish your changes. +1. To assign values to other fields, open [**Choose Columns**](#choose-columns), add the fields, make the assignments, and publish your changes. > [!TIP] - > If you're adding work items that you want to appear on a team backlog, make sure that you add and specify the team's Area Path and Iteration Path. If you need to add Area Paths or Iteration Paths, choose the **Edit Areas and Iterations** link. The link opens a web browser to the Project Settings page. For more information, see [Define area paths and assign to a team](../../../organizations/settings/set-area-paths.md) and [Define Iteration Paths and configure team iterations](../../../organizations/settings/set-iteration-paths-sprints.md). - -1. To open a work item to add more information, Choose the work item you want to open and then choose **Open in Web Access**. Before you do, make sure you publish any changes you've made. - - > [!div class="mx-imgBorder"] - > ![Open a work item in the web portal from Excel](media/excel/2019-open-in-web-access.png) + > When you add work items to a team backlog, ensure you specify the team's Area Path and Iteration Path. If you need to add Area Paths or Iteration Paths, select **Edit Areas and Iterations**. This link opens the **Project settings** page in a web browser. For more information, see [Define area paths and assign to a team](../../../organizations/settings/set-area-paths.md) and [Define Iteration Paths and configure team iterations](../../../organizations/settings/set-iteration-paths-sprints.md). - A web browser opens and displays the work item. +1. To open a work item to add more information, Choose the work item you want to open and then choose **Open in Web Access**. Before you do, make sure you publish any changes you made. - If you make changes to the work item, you should then immediately refresh your worksheet to capture the changes. + :::image type="content" source="media/excel/2019-open-in-web-access.png" alt-text="Screenshot of Open a work item in the web portal from Excel."::: + A web browser opens and displays the work item. If you make changes to the work item, immediately refresh your worksheet to capture the changes. @@ -292,130 +243,121 @@ You can't do the following tasks from an Excel worksheet: You can add a hierarchy of work items linked using parent-child links or other tree topology link type. > [!IMPORTANT] -> Don't sort a tree list. Sorting a tree list can change the hierarchical link relationships. +> Avoid sorting a tree list, as it can alter the hierarchical link relationships. -1. Starting from [Step 5](#step-5) from the previous procedure, convert your flat list, input list into a tree list. Choose a cell within the flat list and then choose **Add Tree Level**. +1. Starting from [Step 5](#step-5) from the previous procedure, convert your flat list, input list into a tree list. Choose a cell within the flat list and then select **Add Tree Level**. - > [!div class="mx-imgBorder"] - > ![Empty flat list connected to a project, Add Tree Level](media/excel/convert-flat-to-tree.png) + :::image type="content" source="media/excel/convert-flat-to-tree.png" alt-text="Screenshot of Empty flat list connected to a project, Add Tree Level."::: If the **Add Tree Level** is disabled, you're working from a query list. To convert your list to a tree list, you must first [reconfigure your list](#reconfigure-list) to an input list. -1. Choose the link type to use when adding work items to a hierarchy, and then choose **Convert**. The most usual choice is **Parent-Child**. You can only select from tree topology link types. For more information, see [Link type topologies and restrictions](/previous-versions/azure/devops/reference/xml/link-type-element-reference#topology). +2. Choose the link type to use when you're adding work items to a hierarchy, and then select **Convert**. The most usual choice is **Parent-Child**. You can only select from tree topology link types. For more information, see [Link type topologies and restrictions](/previous-versions/azure/devops/reference/xml/link-type-element-reference#topology). - > [!div class="mx-imgBorder"] - > ![Convert to Tree List dialog](media/excel/convert-tree.png) + :::image type="content" source="media/excel/converted-tree-list-type.png" alt-text="Screenshot of Convert to Tree List dialog."::: - Note the List type has changed to **Tree**, and a second **Title** column appears. + The List type changes to **Tree** and a second **Title** column appears. - > [!div class="mx-imgBorder"] - > ![List type has changed to Tree, and a second Title column appears.](media/excel/converted-tree-list-type.png) + :::image type="content" source="media/excel/converted-tree-list-type.png" alt-text="Screenshot of List type changed to Tree, and a second Title column appears."::: -1. To add more levels to the hierarchy, choose **Add Tree Level** again. For example, if you want to add a hierarchy of Epics, Features, and User Stories, you'll want to have **Title 1**, **Title 2**, and **Title 3** columns. +3. To add more levels to the hierarchy, select **Add Tree Level** again. For example, if you want to add a hierarchy of Epics, Features, and User Stories, you want to have **Title 1**, **Title 2**, and **Title 3** columns. If you want to add tasks, add another tree level to have four title columns. To remove a column, see [Remove a tree level](#remove-tree-level). -1. Save your Excel file. +4. **Save** your Excel file. -1. Enter the **Work Item Type** and **Titles** for the hierarchy you want to import. The **State** fields automatically fill in with default values once you select the work item type. +5. Enter the **Work Item Type** and **Titles** for the hierarchy you want to import. The **State** fields automatically fill in with default values once you select the work item type. - > [!div class="mx-imgBorder"] - > ![Excel worksheet, hierarchical list of work items for import](media/excel/import-safe-hierarchy-list.png) + :::image type="content" source="media/excel/import-safe-hierarchy-list.png" alt-text="Screenshot of Excel worksheet, hierarchical list of work items for import."::: -8. Publish your worksheet. +6. Publish your worksheet. - > [!div class="mx-imgBorder"] - > ![Team Ribbon, Publish link](media/excel/publish-tree-list.png) + :::image type="content" source="media/excel/publish-tree-list.png" alt-text="Screenshot of Team Ribbon, Publish link."::: Make sure your cursor is in a cell that contains data. Otherwise, the **Publish** button might appear disabled. - IDs are now assigned to your work items. In the background, the link type you selected is used to link each work item in the hierarchy. Epics are linked to Features, Features are linked to User Stories. + IDs are now assigned to your work items. In the background, the link type you selected is used to link each work item in the hierarchy. Epics are linked to Features. Features are linked to User Stories. -1. To check the links made, choose a work item and choose **Links and Attachments**. +7. To check the links made, choose a work item and choose **Links and Attachments**. For example, here we show the Child and Parent links created for a Feature that was imported. - > [!div class="mx-imgBorder"] - > ![Link and Attachments, Link tab dialog](media/excel/view-hierarchical-links.png) + :::image type="content" source="media/excel/view-hierarchical-links.png" alt-text="Screenshot of Link and Attachments, Link tab dialog."::: -1. To enter a row under a work item where you want to add a child, choose the row and then choose **Add Child**. +8. To enter a row under a work item where you want to add a child, choose the row and then choose **Add Child**. - > [!div class="mx-imgBorder"] - > ![Team ribbon, Tree group, Add child link](media/excel/tree-group-add-child.png) + :::image type="content" source="media/excel/tree-group-add-child.png" alt-text="Screenshot of Team ribbon, Tree group, Add child link."::: -1. To assign values to other fields, open [**Choose Columns**](#choose-columns), add the fields, make the assignments, and publish your changes. +9. To assign values to other fields, open [**Choose Columns**](#choose-columns), add the fields, make the assignments, and publish your changes. -1. To change the hierarchy, cut and paste the row of a work item to place it under the new parent. Make sure that you select the entire table row. When you publish the change, the old hierarchical links are deleted and the new hierarchical link are created. +10. To change the hierarchy, cut and paste the entire row of a work item to place it under the new parent. When you publish the change, the old hierarchical links are deleted, and the new hierarchical links are created. - You can use the ![indent item in tree](media/bulk-modify-excel-indent-inline.png) or ![Outdent item in tree](media/bulk-modify-excel-outdent-inline.png) indent/outdent icons to demote or promote a work item within the tree hierarchy. Verify that the column to the left or right of the parent work item's title is a **Title** column. The header at the top of the column should read **Title n**, if it doesn't, add a tree level. + You can use the ![indent item in tree](media/bulk-modify-excel-indent-inline.png) or ![Outdent item in tree](media/bulk-modify-excel-outdent-inline.png) indent/outdent icons to demote or promote a work item within the tree hierarchy. Ensure the header at the top of the column reads **Title n**; if it doesn't, add a tree level. - + ### Remove a tree level -1. First, publish changes that you've made to work items before you remove a tree level. Removing a tree level requires a refresh, which overwrites data in the work item list. You'll lose any data you haven't published. +1. First, publish changes that you made to work items before you remove a tree level. Removing a tree level requires a refresh, which overwrites data in the work item list. You lose any data you didn't publish. 2. Next, delete any content under the tree-level **Title** *number* column you want to remove—the highest numbered column—. This column should be the highest numbered column in the tree. 3. **Refresh** your worksheet. The column containing empty values for the Title is removed. - You'll receive an error message if you attempt to delete the column. + You get an error message if you attempt to delete the column. + +### Tips for working with a tree list -### Useful tips when working with a tree list +Excel uses the data in the **Title** columns to determine the pattern of links between work items. When you publish changes, any of the following conditions can result in an error, an invalid link, or a tree link being created between incorrect work items: -- Excel interprets the data in the **Title** columns to determine the pattern of links between work items. When you publish changes, any of the following conditions can result in an error, an invalid link, or a tree link to be created between incorrect work items: - - A row between the work items is blank within the hierarchy - - The Title of a work item is in the wrong column. Make sure you enter a title for each child work item. - - Within a row, multiple **Title** columns contain data. Enter text in only one of the title columns within each row. - - The list was sorted. Don't sort a tree list. Sorting a tree list can change the hierarchical link relationships. If you do sort a tree list, you can recover from this operation by immediately refreshing. -- To resolve an error, see [Resolve invalid links](resolve-excel-invalid-links-tree-list.md). -- A parent-child linked work item can only have one parent. You can't add the same work item task to two backlog items. Instead, you need to define distinct work item tasks. +- A row between the work items is blank within the hierarchy. +- The title of a work item is in the wrong column. Ensure you enter a title for each child work item. +- Multiple **Title** columns contain data within a row. Enter text in only one of the title columns per row. +- The list was sorted. Avoid sorting a tree list, as it can change the hierarchical link relationships. If you do sort a tree list, recover by immediately refreshing. + +To resolve an error, see [Resolve invalid links](resolve-excel-invalid-links-tree-list.md). + +Additionally, a parent-child linked work item can only have one parent. You can't add the same work item task to two backlog items. Instead, define distinct work item tasks. ## Update work items in bulk with a query list -The easiest way to bulk update many work items is to create a query with the work items you want to update, and then open that query in Excel. +The easiest way to bulk update multiple work items is to create a query for the work items you want to update, and then open that query in Excel. > [!TIP] -> **Follow these tips to keep your work in sync:** ->- When you first open a saved worksheet, use ![Refresh icon in Excel on Team ribbon](media/bulk-modify-excel-refresh-inline.png) (**Refresh**) to download the latest data from the data store. ->- Enter data for additional fields by adding columns to the worksheet using ![Choose Column icon in Excel on Team ribbon](media/bulk-modify-excel-choose-columns-inline.png) Choose Columns. ->- To avoid data conflicts, publish your additions and modifications often. ->- To prevent loss of data before you publish or refresh, save your workbook periodically. - +> **Keep your work in sync with these tips:** +> - Use ![Refresh icon in Excel on Team ribbon](media/bulk-modify-excel-refresh-inline.png) (**Refresh**) when you first open a saved worksheet to download the latest data from the data store. +> - Add columns to the worksheet using ![Choose Column icon in Excel on Team ribbon](media/bulk-modify-excel-choose-columns-inline.png) (**Choose Columns**) to enter data for additional fields. +> - Publish your additions and modifications often to avoid data conflicts. +> - Save your workbook periodically to prevent data loss before you publish or refresh. 1. From the web portal or Visual Studio, create the work item query that contains the work items you want to update. For more information, see [Create and save managed queries with the query editor](../../queries/using-queries.md). -3. Open Excel and connect to your Azure Boards project. Use one of the four methods provided in [Connect Azure DevOps project to Excel](track-work.md#excel). +2. Open Excel and connect to your Azure Boards project. Use one of the four methods provided in [Connect Azure DevOps project to Excel](track-work.md). -1. If you opened your query from the web portal or Visual Studio, you're done. Make any changes you want. Open [**Choose Columns**](#choose-columns), add fields, make assignments, and publish your changes. +3. If you opened your query from the web portal or Visual Studio, you're done. Make any changes you want. Open [**Choose Columns**](#choose-columns), add fields, make assignments, and publish your changes. -1. If you start from Excel, open a blank worksheet. You can add a worksheet to an existing workbook, as long as you're choosing a query from the same project the workbook is bound to. +4. If you start from Excel, open a blank worksheet. You can add a worksheet to an existing workbook, as long as you're choosing a query from the same project the workbook is bound to. -1. Choose **New List** from the Team ribbon. +5. Choose **New List** from the Team ribbon. - > [!div class="mx-imgBorder"] - > ![Choose New List](media/excel/team-ribbon.png) + :::image type="content" source="media/excel/team-ribbon.png" alt-text="Screenshot of Choose New List."::: -1. From the **New List** dialog, choose **Query list**, and select the query you want from the drop-down menu. +6. From the **New List** dialog, choose **Query list**, and select the query you want from the drop-down menu. - > [!div class="mx-imgBorder"] - > ![Select input list, query list](media/excel/input-query-list.png) + :::image type="content" source="media/excel/input-query-list.png" alt-text="screenshot of Select input list, query list."::: The icon next to each query indicates the query type. The first two query types, **Flat list of work items** and **Work items and direct links** are imported as flat list queries. Only the **Tree of work items** queries import as a tree list. - > [!div class="mx-imgBorder"] - > ![Query type icon list](media/excel/query-types.png) + :::image type="content" source="media/excel/query-types.png" alt-text="Screenshot of Query type icon list."::: -1. With the work items imported to Excel, make the modifications you want and publish your changes. +7. With the work items imported to Excel, make the modifications you want and publish your changes. If you're working with a tree list, see also the information provided in [Import a hierarchical list of work items](#add-work-items-tree). - ## Enable Tree commands -If the **Tree group** commands aren't available, your worksheet is configured as a flat list, query list. Convert the list to either an input list or a list based on a tree query to enable the Tree group commands. To learn how, see the next section on [Change your list type or query](#reconfigure-list). +If the **Tree group** commands aren't available, your worksheet is configured as a flat or query list. To enable the Tree group commands, convert the list to either an input list or a list based on a tree query. For more information, see the next section on [Change your list type or query](#reconfigure-list). @@ -427,35 +369,29 @@ You can change the work items listed in your worksheet. Specifically, you can: - Change from an input list to a query list - Change the query your worksheet references -If you want to change your flat list to a tree list, you can. However, if your list is a query list, then you first need to reconfigure the list. You'll know that it's a flat list, query list as the **Tree group** commands are disabled. +You can change your flat list to a tree list. However, if your list is a query list, you need to reconfigure it first. If the **Tree group** commands are disabled, it indicates a flat or query list. -> [!div class="mx-imgBorder"] -> ![Team ribbon, disabled Tree group commands](media/excel/disabled-tree-group.png) +:::image type="content" source="media/excel/disabled-tree-group.png" alt-text="Screenshot of Team ribbon, disabled Tree group commands."::: To convert your query list to an input list, follow these steps. -1. First, publish whatever changes you have made. +1. Publish your changes. -1. Next, on the **Team** ribbon, choose **Configure**, **List**. +2. On the **Team** ribbon, choose **Configure**, **List**. - > [!div class="mx-imgBorder"] - > ![Team ribbon, Configure, List menu option](media/excel/team-ribbon-configure-list.png) + :::image type="content" source="media/excel/team-ribbon-configure-list.png" alt-text="Screenshot of Team ribbon, Configure, List menu option."::: -1. Choose **Refresh work items only** and then **Apply**. +3. Choose **Refresh work items only** and then **Apply**. This choice changes the query list to an input list. - > [!div class="mx-imgBorder"] - > ![Configure List properties dialog, Input](media/excel/configure-list-properties-dialog-refresh-current.png) + :::image type="content" source="media/excel/configure-list-properties-dialog-refresh-query.png" alt-text="Screenshot of Configure List properties dialog, Input."::: -1. To convert from an input list to a query list, choose **Refresh from query**, select the query, and then **Apply**. +4. To convert from an input list to a query list, choose **Refresh from query**, select the query, and then **Apply**. - > [!div class="mx-imgBorder"] - > ![Configure List properties dialog, Query](media/excel/configure-list-properties-dialog-refresh-query.png) - - - + :::image type="content" source="media/excel/configure-list-properties-dialog-refresh-query.png" alt-text="Screenshot of Configure List properties dialog, Query."::: + ## Add existing work items to your worksheet @@ -465,82 +401,75 @@ If you're working with an input list, complete these steps. 1. From the **Team** ribbon, choose **Get Work Items**. - > [!div class="mx-imgBorder"] - > ![Team Ribbon, Get work items](media/excel/team-ribbon-get-work-items.png) + :::image type="content" source="media/excel/team-ribbon-get-work-items.png" alt-text="Screenshot of Team Ribbon, Get work items."::: 2. Choose the method you want from the three options available. - > [!div class="mx-imgBorder"] - > ![Get work items dialog](media/excel/get-work-items.png) + :::image type="content" source="media/excel/get-work-items.png" alt-text="Screenshot of Get work items dialog."::: If the work items are defined in another project, then first select the Project. Then, make your selections: - - **Query**. Use this method when you've defined a query that contains the set or superset of work items you want. - - **IDs**. Use this method when you know the IDs of the work items that you want to link to. + - **Query**. Use this method when you defined a query that contains the set or superset of work items you want. + - **IDs**. Use this method when you know the IDs of the work items that you want to link to. In the **IDs** box, type the IDs of the work items that you want to find, separated by commas or spaces. - - **Title contains**. Use this method to find work items that have a common word or phrase in the title field. In the **and type** list, select the type of work item that you want to retrieve. - > [!NOTE] - > To minimize the time required to run the query, narrow the filter criteria of the search. + - **Title contains**. Use this method to find work items that have a common word or phrase in the title field. In the **and type** list, select the type of work item that you want to retrieve. + + > [!NOTE] + > To minimize the time required to run the query, narrow the filter criteria of the search. 3. Choose **Find**. - Only those work items defined for the selected project and specified work item type are listed. To sort on a column field, choose the column **Title**. + Only those work items defined for the selected project and specified work item type are listed. To sort on a column field, choose the column **Title**. 4. In the list of returned work items, select the check-box of one or more work items. - - Select each work item that should link to the current work item. You can also press the SHIFT key while clicking to select a range of work items, or press the CTRL key while clicking to select multiple work items. + - Select each work item that should link to the current work item. You can also press the SHIFT key while selecting to choose a range of work items, or press the CTRL key while selecting to choose multiple work items. - Choose **Select All** to select all work items in the list. ## Add or remove column fields -If you start your worksheet with a **New List**, you'll see only a set of default field columns. You can add columns using the **Choose Columns** on the Team ribbon. +If you start your worksheet with a **New List**, you see only a set of default field columns. You can add columns using the **Choose Columns** on the Team ribbon. -If you start your worksheet from an existing query, you'll see all the column fields defined for the query. From there, you can add columns using the **Choose Columns**. However, your additions don't modify the underlying query. +If you start your worksheet from an existing query, you see all the column fields defined for the query. From there, you can add columns using the **Choose Columns**. However, your additions don't modify the underlying query. 1. To assign values to other fields, choose **Column Options** to add the fields of interest. - > [!div class="mx-imgBorder"] - > ![Choose Columns dialog](media/excel/choose-columns-with-ribbon.png) + :::image type="content" source="media/excel/choose-columns-with-ribbon.png" alt-text="Screenshot of Choose Columns dialog."::: - To filter the fields based on work item type, select the **Work item type**. - To move or remove a field, choose the field and then select the > or < icons. - To change the field sequence, move the field up or down in the list using the up and down arrows. - - You can add a rich-text field, such as the **Description** field, however you may lose some of the formatting upon publish. + - You can add a rich-text field, such as the **Description** field, however you might lose some of the formatting upon publish. -1. Once the fields appear in the worksheet, assign values and publish your updates. When working with identity fields, ones that accept user accounts, see the next section, [Select user accounts](#select-user). - -1. Save your worksheet. +2. Once the fields appear in the worksheet, assign values and publish your updates. When working with identity fields, ones that accept user accounts, see the next section, [Select user accounts](#select-user). +3. **Save** your worksheet. ## Select user accounts -You can use the Select User feature to find user accounts and assign values to person named fields. Also, this feature provides access to the most recently used (MRU) values. If your team contains several hundreds or thousands of user accounts, you'll want to use this feature. +Use the Select User feature to find user accounts and assign values to person-named fields. This feature also provides access to the most recently used (MRU) values. If your team has hundreds or thousands of user accounts, this feature is especially useful. > [!TIP] -> Without the **Select User** feature, you must enter user names exactly as they are in the database, or you'll receive data validation errors upon trying to publish. +> Without the **Select User** feature, you must enter user names exactly as they are in the database, or you'll receive data validation errors when you try to publish. -1. If you haven't installed or updated to the latest version of [Visual Studio (at least VS 2015.1 or later version](https://visualstudio.microsoft.com/downloads/), do that now. You need the latest update to access the Select User feature. +1. If you don't have the latest version of [Visual Studio (2015.1 or later version](https://visualstudio.microsoft.com/downloads/), get it now. You need the latest update to access the Select User feature. 2. Choose an identity or person-named field to activate the **Select User** feature in the Team ribbon. - > [!div class="mx-imgBorder"] - > ![Team ribbon, Select User](media/excel/select-user.png) - - An identity or person-named field is a field that contains a user identity. These fields are typically synchronized to a database of user accounts, such as Azure Active Directory, Active Directory, or a Workgroup. + :::image type="content" source="media/excel/select-user.png" alt-text="Screenshot of Team ribbon, Select User."::: + An identity or person-named field contains a user identity. These fields are typically synchronized with a user account database, such as Microsoft Entra ID, Active Directory, or a Workgroup. 3. Begin entering the name of the user account and the Assign User dialog automatically filters the results until you can select the account of interest. - ![Assign User dialog](media/bulk-add-excel-assign-user.png) + :::image type="content" source="media/bulk-add-excel-assign-user.png" alt-text="Screenshot of Assign User dialog."::: - Enter a letter to tab to the start of names beginning with that letter. Enter only user names as account aliases aren't recognized. + Enter a letter to jump to names starting with that letter. Only user names are recognized; account aliases aren't. As you select user names, Excel remembers your recent selections, allowing you to choose user accounts directly from the field. - You'll notice that as you select user names, Excel remembers your recent selections and you can select the user accounts directly from the field. - - ![Assigned to field, Drop-down menu shows most recently used values](media/bulk-add-excel-assign-to-field.png) + :::image type="content" source="media/bulk-add-excel-assign-to-field.png" alt-text="screenshot of Assigned to field, Drop-down menu shows most recently used values."::: @@ -556,30 +485,27 @@ You can complete many actions from the **Links** tab of the **Links and Attachme For more information on linking work items, see [Link user stories, issues, bugs, and other work items](../add-link.md). - ### View and add links -You can't use the Links and Attachments dialog to bulk update work item links. You can only bulk update tree-topology link types using a tree list. +You can't use the Links and Attachments dialog to bulk update work item links. To bulk update tree-topology link types, use a tree list instead. -1. To link a work item to other work items, choose the work item and then choose **Links and Attachments**. From the Links tab, choose **Link to** and then choose the **Link Type** and work item(s) you want to link to. Choose **OK** and then **Publish**. +1. To link a work item to other work items, choose the work item and then choose **Links and Attachments**. From the Links tab, choose **Link to** and then choose the **Link Type** and work item you want to link to. Choose **OK** and then **Publish**. - > [!div class="mx-imgBorder"] - > ![Links and Attachments dialog, Add links](media/excel/link-work-item.png) + :::image type="content" source="media/excel/link-work-item.png" alt-text="Screenshot of Links and Attachments dialog, Add links."::: - When finished, choose **Close** to dismiss the dialog. +2. When you're done, select **Close** to dismiss the dialog. -1. To link several work items to the same work item(s), multi-select them by using **Ctrl-click** for consecutive rows, or **Shift-click** for non-consecutive rows. +3. To link several work items to the same work item, multi-select them by using **Ctrl-select** for consecutive rows, or **Shift-select** for nonconsecutive rows. -### Find work items to link to +### Find work items to link -From the Add link dialog, you can open a secondary dialog to choose one or more work items to link to. If you're going to find and list work items to link to by using a saved query, first [define the query](../../queries/using-queries.md) to use. +In the Add link dialog, you can open a secondary dialog to select one or more work items to link to. If you plan to find and list work items using a saved query, first [define the query](../../queries/using-queries.md). -From the Add link dialog, choose the **Browse** button (Visual Studio) to open the following dialog. +In the Add link dialog, select **Browse** (Visual Studio) to open the following dialog. -> [!div class="mx-imgBorder"] -> ![Choose Link Work Items dialog](media/excel/choose-linked-work-items-dialog.png) +:::image type="content" source="media/excel/choose-linked-work-items-dialog.png" alt-text="Screenshot of Choose Link Work Items dialog."::: The **Choose Linked Work Items** dialog works in the same way as the **Get Work Items** dialog. For more information, see [Add existing work items to your worksheet](#get-work-items) described earlier in this article. @@ -587,104 +513,89 @@ The **Choose Linked Work Items** dialog works in the same way as the **Get Work 1. From the **Links** tab, choose the :::image type="icon" source="media/icons/choose-columns.png" border="false"::: **Columns** icon, and add the fields you want displayed. Here we add the Assigned to and State fields. - > [!div class="mx-imgBorder"] - > ![Links and Attachments dialog, Links tab, Added columns](media/excel/link-tabs-choose-columns-dialog.png) + :::image type="content" source="media/excel/link-tabs-choose-columns-dialog.png" alt-text="Screenshot of Links and Attachments dialog, Links tab, Added columns."::: -1. To reorder the links, choose the field to sort the list on that field. +2. To reorder the links, choose the field to sort the list on that field. - > [!div class="mx-imgBorder"] - > ![To reorder the links, choose the field to sort the list on that field.](media/excel/links-tab-added-columns.png) + :::image type="content" source="media/excel/links-tab-added-columns.png" alt-text="Screenshot of To reorder the links, choose the field to sort the list on that field."::: This dialog works in the same way as the **Get Work Items** dialog. See [Add existing work items to your worksheet](#get-work-items) described earlier in this article. ### Open a linked work item -From the **Links** tab, choose the linked work item, right-click to open the context menu, and choose **Open Linked Item**. +From the **Links** tab, choose the linked work item, right-select to open the context menu, and choose **Open Linked Item**. -> [!div class="mx-imgBorder"] -> ![Links and Attachments dialog, Links tab, Open Linked Work Item](media/excel/links-tab-open-linked-work-item.png) +:::image type="content" source="media/excel/links-tab-open-linked-work-item.png" alt-text="Screenshot of Links and Attachments dialog, Links tab, Open Linked Work Item."::: The work item opens in your web portal. ### Edit the link and change the link type -You can edit any link listed. You can change the link type and the work items linked to. +You can edit any listed link, including changing the link type and the linked work items. 1. Choose the link and choose the :::image type="icon" source="media/icons/edit.png" border="false"::: **Edit** icon. 1. Change the link type as needed. - > [!div class="mx-imgBorder"] - > ![Links and Attachments dialog, Links tab, Edit link dialog](media/excel/edit-link-dialog.png) + :::image type="content" source="media/excel/edit-link-dialog.png" alt-text="Screenshot of Links and Attachments dialog, Links tab, Edit link dialog."::: -1. To change the work item linked to, enter the ID of the work item, or choose **Browse** to find the work item(s) to link to. +1. To change the work item linked to, enter the ID of the work item, or choose **Browse** to find the work item to link to. The **Choose Linked Work Items** dialog works in the same way as the **Get Work Items** dialog. For more information, see [Add existing work items to your worksheet](#get-work-items) described earlier in this article. ## Add attachments -- To add attachments, choose the work item, then **Links and Attachments**, and then the **Attachments** tab. - - Choose the file you want to attach, then choose **OK** and then **Publish**. +1. Open the work item, then select **Links and Attachments** > **Attachments**. - > [!div class="mx-imgBorder"] - > ![Links and Attachments dialog, Add Attachment](media/excel/add-attachment.png) + Choose the file you want to attach, then select **OK** > **Publish**. - When finished, choose **Close** to dismiss the dialog. + :::image type="content" source="media/excel/add-attachment.png" alt-text="Screenshot of Links and Attachments dialog, Add Attachment."::: -- To add the same attachment(s) to several work items, multi-select them by using **Ctrl-click** for consecutive rows, or **Shift-click** for non-consecutive rows. +2. When you're done, select **Close**. +3. Optional: To add one or more same attachments to several work items, multi-select them by using **Ctrl-select** for consecutive rows, or **Shift-select** for nonconsecutive rows. ## Create a report You can create a report or chart from the web portal for flat-list queries. See [Track progress by creating status and trend query-based charts](../../../report/dashboards/charts.md). > [!IMPORTANT] -> You can only create an Excel report using **New Report** from an on-premises Azure DevOps Server. These reports require that your project's project collection is configured to support SQL Server Analytics Server. +> You can create an Excel report using **New Report** only from an on-premises Azure DevOps Server. These reports require your project's collection to be configured to support SQL Server Analytics Server. -You can create a report using the **New Report** feature based on a flat list of work items. +Select **New Report**. -> [!div class="mx-imgBorder"] -> ![Create a report using the New Report feature.](media/excel/team-ribbon-new-report.png) +:::image type="content" source="media/excel/team-ribbon-new-report.png" alt-text="Screenshot of Create a report using the New Report feature."::: For more information, see [Create Excel reports from a work item query](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports). - ## Resolve publishing errors -To resolve publishing errors that arise when working in Excel, see one of the following articles: +To resolve publishing errors that might arise when you're working in Excel, see one of the following articles: - [Resolve data conflicts](resolve-excel-data-conflicts-publish-refresh.md): A data conflict occurs when a field value is changed in Azure Boards since the last time you published from Excel. - - [Resolve data validation errors](resolve-excel-data-validation-errors.md): A data validation error occurs if a field value violates the rules for that field and work item type. - - [Resolve invalid links in a tree hierarchy](resolve-excel-invalid-links-tree-list.md): - An invalid link occurs if a team member view work items in Excel as a hierarchy or tree list, and then moves a work item or sorts the list such that it breaks the dependencies between work items. You can resolve this error by reviewing the error message and repositioning work items to reflect the work item structure. - + An invalid link happens when a work item in a hierarchy or tree list and is moved or sorted, breaking the dependencies between work items. To resolve this error, review the error message and reposition the work items to restore the correct structure. - [Address Error TF208104: Hierarchical Link Relationship Is Locked](resolve-excel-invalid-links-tree-list.md#tf208104): - If you receive error TF208104, the changes you made to the fields are published. But your changes to the link hierarchy aren't published. At least one of the link relationships defined for the work item is locked by another process, such as Project Server integration. + If you receive error TF208104, your changes to the fields are published, but changes to the link hierarchy aren't. This error occurs because another process locks at least one of the link relationships for the work item, such as Project Server integration. + +## Next steps + +> [!div class="nextstepaction"] +> [Integrate Azure Boards and GitHub](../../github/index.md) ## Related articles ::: moniker range=">= azure-devops-2020" -- [Bulk modify work items (web portal)](../../backlogs/bulk-modify-work-items.md) -- [Azure DevOps Office integration issues](tfs-office-integration-issues.md) -- [FAQs: Work in Excel connected to Azure Boards](faqs.yml) -- [Bulk import or update work items using CSV files](../../queries/import-work-items-from-csv.md) +- [Modify work items in bulk (web portal)](../bulk-modify-work-items.md) +- [Import or update work items in bulk using CSV files](../../queries/import-work-items-from-csv.md) +- [Troubleshoot Azure DevOps Office integration issues](tfs-office-integration-issues.md) +- [View FAQs: Work in Excel connected to Azure Boards](faqs.yml) - [View and add work items](../../work-items/view-add-work-items.md) -- [Basic Excel tasks](https://support.office.com/article/basic-tasks-in-excel-dc775dd1-fa52-430f-9c3c-d998d1735fca) - -::: moniker-end - -::: moniker range="< azure-devops" - -- [Bulk modify work items (web portal)](../../backlogs/bulk-modify-work-items.md) -- [Azure DevOps Office integration issues](tfs-office-integration-issues.md) -- [FAQs: Work in Excel connected to Azure Boards](faqs.yml) -- [Create Excel reports from a work item query](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports) -- [Basic Excel tasks](https://support.office.com/article/basic-tasks-in-excel-dc775dd1-fa52-430f-9c3c-d998d1735fca) +- [Learn basic Excel tasks](https://support.office.com/article/basic-tasks-in-excel-dc775dd1-fa52-430f-9c3c-d998d1735fca) ::: moniker-end + diff --git a/docs/boards/backlogs/office/faqs.yml b/docs/boards/backlogs/office/faqs.yml index 37aab2e7de7..3f1b385e8d4 100644 --- a/docs/boards/backlogs/office/faqs.yml +++ b/docs/boards/backlogs/office/faqs.yml @@ -8,18 +8,22 @@ metadata: author: chcomley ms.topic: faq monikerRange: '<= azure-devops' - ms.date: 05/22/2023 + ms.date: 03/14/2025 - -title: Work in Excel connected to Azure Boards FAQs +title: FAQs about working in Excel connected to Azure Boards summary: | [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] - Find answers to frequently asked questions when using Microsoft Excel to add or modify work items defined in Azure DevOps. + Find answers to frequently asked questions about using Microsoft Excel to add or modify work items in Azure DevOps. - If you're having connection issues, make sure you meet the prerequisites as listed in [Bulk add or modify work items with Excel](bulk-add-modify-work-items-excel.md). Also be sure you've reviewed the information in [Azure Boards and Office integration](track-work.md). + If you encounter connection issues, ensure you meet the prerequisites in [Bulk add or modify work items with Excel](bulk-add-modify-work-items-excel.md). Also, review the information in [Azure Boards and Office integration](track-work.md). + + ::: moniker range=">= azure-devops-2020" + > [!TIP] + > For bulk importing or updating work items, we recommend using the [web portal](../bulk-modify-work-items.md) or [CSV import](../../queries/import-work-items-from-csv.md). + ::: moniker-end sections: @@ -27,10 +31,6 @@ sections: questions: - - question: What versions of Azure DevOps work with Excel? - answer: | - All versions from TFS 2013 through Azure DevOps Server 2020 and Azure DevOps Services/Azure Boards support integration with Microsoft Excel. - - question: What do I need to use Excel to add or modify work items? answer: | You must get the Azure DevOps Office Integration add-in available from the [Downloads page, Other Tools, and Frameworks](https://visualstudio.microsoft.com/downloads/#other-family). This add-in typically installs when you install any version of Visual Studio or Team Explorer. Also, you need to use Microsoft Excel 2010 or later version, including Microsoft Office Excel 365. @@ -38,23 +38,22 @@ sections: > [!IMPORTANT] > Microsoft Project Integration and the **TFSFieldMapping** command aren't supported for: > - Visual Studio 2019 and Azure DevOps Office® Integration 2019 - > - Azure DevOps Server 2019 and later versions, including Azure DevOps Services. + > - Azure DevOps Server 2019 and newer, including Azure DevOps Services > - > However, full support for Microsoft Excel integration is maintained and is the recommended alternative. + > But, we fully support Microsoft Excel integration, which is the recommended alternative. - Once you've installed the add-in, open Excel and look for the **Team** ribbon. + Once you install the add-in, open Excel and look for the **Team** ribbon. - question: Can I use Excel on my Mac? answer: | - **No**. macOS isn't supported. Even if you've installed Visual Studio for Mac, connection to Azure DevOps from Excel or other Office client isn't supported. + **No**. macOS isn't supported. Even if you install Visual Studio for Mac, connection to Azure DevOps from Excel or other Office client isn't supported. - question: Can I open a query in Excel from the web portal? answer: | - **Yes**. To open Excel from the web portal, install the [Azure DevOps Open in Excel](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-open-work-items-in-excel) Marketplace extension. Otherwise, you can open [Excel](bulk-add-modify-work-items-excel.md) and then open a query that you've created in the web portal or from Team Explorer. + **Yes**. To open Excel from the web portal, install the [Azure DevOps Open in Excel](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-open-work-items-in-excel) Marketplace extension. Otherwise, you can open [Excel](bulk-add-modify-work-items-excel.md) and then open a query that you created in the web portal or from Team Explorer. > [!div class="mx-imgBorder"] - > [Azure DevOps Open in Excel extension](media/excel/open-in-excel.png) - + > ![Screenshot of Azure DevOps Open in Excel extension.](media/excel/open-in-excel.png) - question: Can I import or update work items without using Excel? answer: | @@ -62,25 +61,19 @@ sections: **Yes**. You can do a bulk import of new work items or update existing work items without using Excel. See [Import work items](../../queries/import-work-items-from-csv.md). ::: moniker-end - ::: moniker range="azure-devops-2019" - **No**. For Azure DevOps Server 2019, Excel is the only supported method. - ::: moniker-end - - ::: moniker range="tfs-2018" - **Yes**. For TFS 2018 and earlier versions, you can use Microsoft Project to import and update work items in bulk. See [Create your backlog and tasks using Microsoft Project](/previous-versions/azure/devops/boards/backlogs/office/create-your-backlog-tasks-using-project). - ::: moniker-end + - question: How do I connect an existing Excel workbook to Azure DevOps? answer: | - See [Connect Azure Boards to an Office client](track-work.md#excel-project). + See [Connect Azure Boards to an Office client](track-work.md). - question: How do I share an Excel workbook with others? answer: | - If you want to share an Excel workbook that has work items listed within it, you may want to disconnect the connection to Azure DevOps to prevent accidental publishing of changes by others. You can disconnect the workbook, share it or work offline, and later reconnect the workbook. For more information, see [Connect Azure Boards to an Office client, Disconnect a document file from the network](track-work.md#WorkingOffline). + To share an Excel workbook that has work items listed within it, you might want to disconnect the connection to Azure DevOps to prevent accidental publishing of changes by others. You can disconnect the workbook, share it or work offline, and later reconnect the workbook. For more information, see [Connect Azure Boards to an Office client, Disconnect a document file from the network](track-work.md). - question: How do I connect when special protocols are in use on my network? answer: | - If your network uses TLS 1.1 or TLS 1.2 security protocol, then you may have network connection issues. To resolve these issues, see [Allowed address lists and network connections, Domain URLs to allow](../../../organizations/security/allow-list-ip-url.md#domain-urls-to-allow). + If your network uses TLS 1.1 or TLS 1.2 security protocol, then you might have network connection issues. To resolve these issues, see [Allowed address lists and network connections, Domain URLs to allow](../../../organizations/security/allow-list-ip-url.md). - question: How do I disable the Team menu? answer: | @@ -98,7 +91,6 @@ sections: answer: | **No**. You receive an error message with error code TF208015. You can only view work items defined in the team project that you connect to from Excel. To view work items from other team projects, create a query and open it in a separate Excel workbook. Each Excel workbook can only connect to one team project at a time. - - name: Work with linked work items questions: @@ -111,26 +103,14 @@ sections: answer: | When you open a direct-links query in Excel, the add-in converts the list to a flat list. While you can modify values for the fields and add work items, you can't view nor modify link relationships. - - question: Can I bulk-edit link types other than tree-topology link types? answer: | **No**. Excel only supports adding and modifying hierarchical links. To bulk edit links of other types, you can use the following clients: - ::: moniker range=">= azure-devops-2020" + ::: moniker range="<= azure-devops-2022" - Use the web portal, to [map backlog items to portfolio backlog items](../../backlogs/organize-backlog.md) which creates parent-child links. - Use either the web portal or Team Explorer, to modify parent-child links by [dragging items within a hierarchical backlog page](../../backlogs/organize-backlog.md#reparent) or within a tree query. + ::: moniker-end - Use the [az boards work-item relation add](/cli/azure/boards/work-item/relation) command. - ::: moniker-end - - ::: moniker range="azure-devops-2019" - - Use the web portal, to [map backlog items to portfolio backlog items](../../backlogs/organize-backlog.md) which creates parent-child links. - - Use either the web portal or Team Explorer, to modify parent-child links by [dragging items within a hierarchical backlog page](../../backlogs/organize-backlog.md#reparent) or within a tree query. - ::: moniker-end - - ::: moniker range="tfs-2018" - - Use the web portal, to [map backlog items to portfolio backlog items](../../backlogs/organize-backlog.md) which creates parent-child links. - - Use either the web portal or Team Explorer, to modify parent-child links by [dragging items within a hierarchical backlog page](../../backlogs/organize-backlog.md#reparent) or within a tree query. - ::: moniker-end - - name: Work with test work items @@ -153,7 +133,6 @@ sections: If you start your worksheet from an existing query, you see all the column fields defined for the query. From there, you can add columns using the **Choose Columns** on the Team menu. However, your additions don't modify the underlying query. - > [!div class="mx-imgBorder"] > ![Screenshot showing the choose columns dialog.](media/excel/choose-columns.png) @@ -167,24 +146,24 @@ sections: A data validation error occurs if a team member changes a work item in a way that violates the rules for that type of work item. - [Address inaccuracies published for summary values](../../../report/sql-reports/address-inaccuracies-published-for-summary-values.md): - If you determine that hours are counted twice in reports that contain task hours, you can correct the problem by using the Work Items With Summary Values team query. + If hours are counted twice in reports that contain task hours, you can correct the problem by using the Work Items With Summary Values team query. - question: How do I resolve invalid links tree list in Excel? answer: | - If you try to publish a tree list that contains an invalid link, the **Work Item Publishing Errors** dialog box appears and displays an error message that states why the tree is invalid. When you work with work items in a tree in Excel, the tree must be in a valid state before it can be published. In Excel, an invalid link occurs in a tree list of work items. It occurs if the title of a work item title is missing or occurs in the wrong title column. + If you try to publish a tree list containing an invalid link, the **Work Item Publishing Errors** dialog box appears with an error message stating why the tree is invalid. When you work with work items in a tree in Excel, the tree must be in a valid state before it can be published. In Excel, an invalid link occurs in a tree list of work items. It occurs if the title of a work item title is missing or occurs in the wrong title column. - To update work items, you must be a member of the **Contributors** group or have your **View work items in this node** and your **Edit work items in this node** permissions set to **Allow**. For more information, see [Change project-level permissions](../../../organizations/security/change-project-level-permissions.md). + To update work items, be a member of the **Contributors** group or have your **View work items in this node** and your **Edit work items in this node** permissions set to **Allow**. For more information, see [Change project-level permissions](../../../organizations/security/change-project-level-permissions.md). **Error message TF208000: Duplicate titles** If you add a value to multiple Title columns of a work item, when you try to publish the tree, the error message **TF208000** appears in the **Work Item Publishing Errors** dialog box. The error message specifies the row number of the invalid link. - 1. Note the row number that appears in the dialog box. - 2. Close the **Work Item Publishing Errors** dialog box. - 3. In the work item list, find the row that the error message specified. - 4. Delete the duplicate title or titles so that only one title column has a value. - 5. On the **Team** tab, in the **Work Items** group, choose **Publish**. + 1. Note the row number that appears in the dialog box. + 2. Close the **Work Item Publishing Errors** dialog box. + 3. In the work item list, find the row that the error message specified. + 4. Delete the duplicate title or titles so that only one title column has a value. + 5. On the **Team** tab, in the **Work Items** group, choose **Publish**. **Error message TF208001: Child work item disconnected from parent** @@ -194,11 +173,11 @@ sections: **Resolve an orphaned work item** - 1. Note the row number that appears in the dialog box. - 2. Close the **Work Item Publishing Errors** dialog box. - 3. Find the row that the error message specified. The misplaced title might be in this row, or it might be in the next row. - 4. Move the title to the correct column to fix the invalid link. - 5. On the **Team** tab, in the **Work Items** group, choose **Publish**. + 1. Note the row number that appears in the dialog box. + 2. Close the **Work Item Publishing Errors** dialog box. + 3. Find the row that the error message specified. The misplaced title might be in this row, or it might be in the next row. + 4. To fix the invalid link, move the title to the correct column. + 5. On the **Team** tab, in the **Work Items** group, choose **Publish**. **Error message TF208017: Missing Title 1 in the first row** @@ -212,9 +191,9 @@ sections: **Error message TF208022: Sorted tree list** - If you haven't installed Service Pack 1 for Visual Studio 2010 or later version, the following error message appears when you choose **Publish** after you've sorted the work items in a tree list: + If you didn't install Service Pack 1 for Visual Studio 2010 or later version, the following error message appears when you choose **Publish** after you sort the work items in a tree list: - TF208022: Can't publish a sorted tree list. Before you can publish, you must clear any sort criteria applied to this work item list. The order of work items has changed. Removing sort criteria won't return the list to its original order. Verify that all of the parent-child relationships in the tree are correct before you publish. + TF208022: Can't publish a sorted tree list. Before you can publish, you must clear any sort criteria applied to this work item list. The order of work items changed. Removing sort criteria doesn't return the list to its original order. Verify that all of the parent-child relationships in the tree are correct before you publish. You can't publish your changes until you re-establish the tree hierarchy. You can resolve this error either by discarding your changes and refreshing the list or by manually restoring the hierarchy and then publishing the list. @@ -228,22 +207,22 @@ sections: The following error message appears if you sort the work items in a tree list in Excel: - TF208102: You have performed an Excel sort on a tree list. This action removed the modified or newly introduced hierarchical link relationships of the tree. - You can still publish the changes you have made to individual work items. After you publish, the list restores to previous hierarchy. - In general, you shouldn't sort a tree list whose hierarchy has been modified.| + TF208102: You performed an Excel sort on a tree list. This action removed the modified or newly introduced hierarchical link relationships of the tree. + You can still publish the changes you made to individual work items. After you publish, the list restores to previous hierarchy. + In general, you shouldn't sort a tree list whose hierarchy was modified.| - This message indicates that you can publish the changes that you made to the fields, but all changes that you made to the link hierarchy have been discarded. The tree hierarchy automatically reverts to its original structure. + This message indicates that you can publish the changes that you made to the fields, but all changes that you made to the link hierarchy were discarded. The tree hierarchy automatically reverts to its original structure. **Publish changes and retrieve the tree hierarchy** - 1. On the **Team** tab, in the **Work Items** group, choose **Publish**. - 2. Choose **Refresh**. + 1. On the **Team** tab, in the **Work Items** group, choose **Publish**. + 2. Choose **Refresh**. **Error message TF208104: Hierarchical link Relationship is locked** If you publish a worksheet that contains work items that are synchronized with Project Server and whose hierarchical link relationships are locked (![Locked link icon](media/icon_lockedlink.png "Icon_lockedLink")), the following error message may appear: - TF208104: You have modified one or more hierarchical link relationships that might be locked by other processes, such as Project Server. + TF208104: You modified one or more hierarchical link relationships that might be locked by other processes, such as Project Server. Changes that you made to individual work items were published. Changes that you made to locked links were autocorrected. This error appears when you change the link hierarchy that contains locked links. This message indicates that the changes that you made to the fields are published. All changes you made to the link hierarchy, whether locked or not locked, aren't published and were reverted to their original assignments. @@ -257,12 +236,12 @@ sections: - question: Can I delete work items from Excel? answer: | - ::: moniker range=">= azure-devops-2020" + ::: moniker range="azure-devops" **No**. You can't delete work items from Excel. The only way to delete work items is from the web portal or the `az boards work-item delete` command-line tool. For more information, see [Move, change, or delete work items](../../backlogs/remove-delete-work-items.md#delete-work-items). ::: moniker-end - ::: moniker range="< azure-devops-2020" - **No**. You can't delete work items from Excel. The only way to delete work items is from the web portal, or with the `az boards work-item delete` or **witadmin** command-line tools. For more information, see [Remove or delete work items](../../backlogs/remove-delete-work-items.md#delete-work-items). + ::: moniker range="< azure-devops" + **No**. You can't delete work items from Excel. The only way to delete work items is from the web portal or **witadmin** command-line tools. For more information, see [Remove or delete work items](../../backlogs/remove-delete-work-items.md#delete-work-items). ::: moniker-end - name: Use built-in Excel functions @@ -277,22 +256,34 @@ sections: - question: Can I use Excel cut and paste functions? answer: | - **Yes**. You can use many Excel features, such as cut, paste, automatic fill, format, sort (flat list only), filter, and add formulas. You can cut and paste rows to resequence items within a list and change link relationships among work items. + **Yes**. You can use many Excel features, such as cut, paste, automatic fill, format, sort (flat list only), filter, and add formulas. You can cut and paste rows to resequence items within a list and change link relationships among work items. - To drag a work item, select the work item or contiguous set of work items that you want to move, open the context menu and choose **Select**, **Table Row**, point to the border of the selection, and—when the pointer becomes a move pointer ![Move Pointer](media/bulk-modify-excel-pointer-icon.png)—drag the row to another location. + To drag a work item, select the work item or contiguous set of work items that you want to move. Open the context menu and choose **Select**, **Table Row**, point to the border of the selection, and—when the pointer becomes a move pointer ![Move Pointer](media/bulk-modify-excel-pointer-icon.png)—drag the row to another location. > [!TIP] - > When you refresh the work item list, not all formats may be retained. For example, date formats get set by the server data store. Changes you make to a date format field are overwritten with the date format used by the server. + > When you refresh the work item list, not all formats might be retained. For example, date formats get set by the server data store. Changes you make to a date format field are overwritten with the date format used by the server. - question: How do I enable the Developer tab? answer: | See [Show the Developer Tab on the Ribbon](/visualstudio/vsto/how-to-show-the-developer-tab-on-the-ribbon). + - name: Resolve data conflicts and validation errors + + questions: + + - question: How can I resolve data validation errors that occur when I publish from Excel? + answer: | + For more information, see [Troubleshoot Office integration issues](tfs-office-integration-issues.md#resolve-data-validation-errors). + + - question: How can I resolve data conflicts when I publish or refresh Excel data? + answer: | + For more information, see [Troubleshoot Office integration issues](tfs-office-integration-issues.md#resolve-data-conflicts). additionalContent: | ## Related articles + - [Bulk modify work items (web portal)](../../backlogs/bulk-modify-work-items.md) + - [Bulk import or update work items using CSV files](../../queries/import-work-items-from-csv.md) - [Query FAQs](../../queries/query-faqs.yml) - - [Bulk add or modify work items with Excel](bulk-add-modify-work-items-excel.md) - [Create your backlog](../../backlogs/create-your-backlog.md) - [Azure DevOps Office integration issues](tfs-office-integration-issues.md) - [Basic Excel tasks](https://support.office.com/article/basic-tasks-in-excel-dc775dd1-fa52-430f-9c3c-d998d1735fca) diff --git a/docs/boards/backlogs/office/media/connect/connect-cloud.png b/docs/boards/backlogs/office/media/connect/connect-cloud.png new file mode 100644 index 00000000000..9448f8c2964 Binary files /dev/null and b/docs/boards/backlogs/office/media/connect/connect-cloud.png differ diff --git a/docs/boards/backlogs/office/media/connect/connect-on-premises.png b/docs/boards/backlogs/office/media/connect/connect-on-premises.png new file mode 100644 index 00000000000..dc653ab53cf Binary files /dev/null and b/docs/boards/backlogs/office/media/connect/connect-on-premises.png differ diff --git a/docs/boards/backlogs/office/media/excel-com-disabled-items.png b/docs/boards/backlogs/office/media/excel-com-disabled-items.png new file mode 100644 index 00000000000..1eaf36490a0 Binary files /dev/null and b/docs/boards/backlogs/office/media/excel-com-disabled-items.png differ diff --git a/docs/boards/backlogs/office/media/excel-com-list-of-disabled-items.png b/docs/boards/backlogs/office/media/excel-com-list-of-disabled-items.png new file mode 100644 index 00000000000..68dcfd3c36b Binary files /dev/null and b/docs/boards/backlogs/office/media/excel-com-list-of-disabled-items.png differ diff --git a/docs/boards/backlogs/office/media/excel-options-com-add-ins.png b/docs/boards/backlogs/office/media/excel-options-com-add-ins.png new file mode 100644 index 00000000000..c34f1edcbb2 Binary files /dev/null and b/docs/boards/backlogs/office/media/excel-options-com-add-ins.png differ diff --git a/docs/boards/backlogs/office/resolve-excel-data-conflicts-publish-refresh.md b/docs/boards/backlogs/office/resolve-excel-data-conflicts-publish-refresh.md deleted file mode 100644 index 7510f37f3b6..00000000000 --- a/docs/boards/backlogs/office/resolve-excel-data-conflicts-publish-refresh.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Resolve data conflicts when you publish from Microsoft Excel -titleSuffix: Azure Boards -description: Learn how to resolve data conflicts when publishing a work item from Excel to Azure Boards. -ms.service: azure-devops-boards -ms.assetid: d43d6f68-bcef-42af-857c-50c2ff6ea79b -ms.author: chcomley -author: chcomley -ms.topic: troubleshooting -ms.date: 10/08/2021 ---- - -# Resolve data conflicts when you publish or refresh Excel data - -[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] - -A data conflict occurs when you try to publish a work item from [Excel](bulk-add-modify-work-items-excel.md) and the version of that work item differs from the version in the work item database. The following example shows how two team members can create such a conflict. - -1. A team member opens a copy of a work item in a work item list in Excel or Project. - -2. Team member A edits the work item and makes one set of changes. - -3. Team member B edits that same work item and makes a different set of changes, and publishes those changes. - -4. Team member A finishes editing the work item and tries to publish the changes to the work item. - -5. Excel or Project displays the **Work Item Publishing Errors** dialog box, which shows items that it couldn't publish. - -### To resolve a data conflict - -1. In the **Work Item Publishing Errors** dialog box, for each work item in the **Unpublished work items** box that has **Conflict** in the **Issue** column, follow these steps. - - 1. In the **Unpublished work items** box, select the work item. - - The **Details** area shows a list of conflicts for the selected work item. The **Conflicting field** column shows the name of the field in which the conflict occurs. The **Local version** and **Server version** columns show the local and server data, respectively, and a check box appears next to the data in each of these columns. - - 2. For each row in the **Details** box, select the check box next to the correct value. - - When you select the local version, the data in Office Excel or Office Project overwrites the data on the server. If you select the server version, the server data overwrites the data in Office Excel or Office Project. - -2. Select **Publish**. - - > [!NOTE] - > This step publishes only the work items that you corrected. If you do not resolve all data validation errors related to a work item, that work item is not published. - -## Related articles -- [Resolve data validation errors](resolve-excel-data-validation-errors.md) -- [Connect Azure Boards to an Office client](track-work.md) - - -### Required permissions - -To update work items, you must be a member of the **Contributors** group or have your **View work items in this node** and your **Edit work items in this node** permissions set to **Allow**. For more information, see [Change project-level permissions](../../../organizations/security/change-project-level-permissions.md). \ No newline at end of file diff --git a/docs/boards/backlogs/office/resolve-excel-data-validation-errors.md b/docs/boards/backlogs/office/resolve-excel-data-validation-errors.md deleted file mode 100644 index c7860cbc87c..00000000000 --- a/docs/boards/backlogs/office/resolve-excel-data-validation-errors.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Resolve data validation errors in Azure Boards -titleSuffix: Azure Boards -description: Learn how to address rule errors that occur when publishing a list from Excel to Azure Boards. -ms.service: azure-devops-boards -ms.assetid: 4c72c12f-bd10-48a5-b71c-7c296feec71e -ms.author: chcomley -author: chcomley -ms.topic: troubleshooting -ms.date: 10/08/2021 ---- - -# Resolve data validation errors that occur when you publish from Excel - -[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] - -A data validation error occurs when a change in the work item list or project plan violates a work item type's rule. The following examples show common data validation errors: - -- Someone assigns a work item to a team member whose name isn't included in the list of allowed values -- Someone creates a work item but forgets to complete a required field, such as the work item type. - - If a data validation error occurs when you try to publish changes, the **Work Item Publishing Errors** dialog box appears, and in the **Unpublished work items** list the **Issue** column shows **Validation error** or another phrase that contains **Invalid**. - - - -## Prerequisites - -To update work items, you must be a member of the **Contributors** group or have your **View work items in this node** and your **Edit work items in this node** permissions set to **Allow**. For more information, see [Change project-level permissions](../../../organizations/security/change-project-level-permissions.md). - - - - -## Resolve a data validation error - - You can use the **Work Item Publishing Errors** dialog box to resolve a data validation error. - -1. In the **Work Item Publishing Errors** dialog box, for each work item that appears with a data validation error, follow these steps. - - > [!NOTE] - > If the data validation error is an invalid work item type, the **Edit Work Item** button is not visible, and a work item form does not appear. You must correct the error in the Office Excel worksheet or the Office Project plan. For information about how to resolve an error in Office Excel, see the next procedure in this article. - - 1. In the **Unpublished work items** box, select the work item, and then select **Edit Work Item**. - - A work item form appears. - - 2. In the work item form, review the information and correct the value. - - 3. Select **Close** to save your changes and close the work item form. - -2. After you correct the data validation errors, select **Publish** to publish the corrected work items. - - > [!NOTE] - > This step publishes only the work items that you corrected. If you do not resolve a data validation error, that work item is not published. - -3. Select **Close** to close the **Work Item Publishing Errors** dialog box. - - - -## Resolve a data validation error by using error checking in Excel - -You can use the Office Excel tools to find and resolve an error in a work item list. For more information about how to use Office Excel error checking tools, see the Office Excel Help. - -### To resolve a data validation error by using error checking in Excel 2007 - -1. Start Excel, and select the **Formulas** tab. - -2. In the **Formula Auditing** group, select **Error Checking**. - - If the error checking tool finds an error, the **Error Checking** dialog box appears. - -3. For basic information about the error, see the text that describes the error in the **Error Checking** dialog box. For more information about the error, select **Help on this error**. - -4. In the work item list, select the cell that contains the error, and then correct the value. - -5. In the **Error Checking** dialog box, select **Resume** to find the next data validation error. - - - If the **Error Checking** dialog box shows another error, repeat the previous two steps to resolve the error. - - - If a message appears that indicates error checking has completed, select **OK** to close both this message and the **Error Checking** dialog box. - -## Related articles - -- [Resolve data conflicts](resolve-excel-data-conflicts-publish-refresh.md) -- [Connect Azure Boards to an Office client](track-work.md) diff --git a/docs/boards/backlogs/office/tfs-office-integration-issues.md b/docs/boards/backlogs/office/tfs-office-integration-issues.md index 6d28fd9a415..3b44d924a30 100644 --- a/docs/boards/backlogs/office/tfs-office-integration-issues.md +++ b/docs/boards/backlogs/office/tfs-office-integration-issues.md @@ -7,132 +7,234 @@ ms.assetid: 819EA180-2BAC-46DB-A17E-A5179E6BEADC ms.author: chcomley author: chcomley ms.topic: troubleshooting -ms.date: 06/27/2022 +ms.date: 03/14/2025 --- - -# Resolve Azure DevOps Office integration issues +# Resolve Azure DevOps and Office integration issues [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -All Office integration tasks require that you have installed a version of Visual Studio or the free [Azure DevOps Office Integration 2019](https://visualstudio.microsoft.com/downloads). These software installs the Azure DevOps Office Integration Add-in or Team Foundation Office Integration Add-in For a list of prerequisites, see [Azure Boards and Office integration](track-work.md). - -If you don't see the **Team** ribbon in Microsoft Excel, as shown in the image below, you may want to resolve the issue with the procedures provided in this article. +If the **Team** ribbon is missing in Microsoft Excel, as shown in the following image, do the procedures in this article to resolve the issue. > [!div class="mx-imgBorder"] -> ![Screenshot of Excel TFS-Office integration Team ribbon.](media/excel-team-ribbon.png) +> ![Screenshot of Excel and Azure DevOps/Office integration Team ribbon.](media/excel-team-ribbon.png) + +> [!NOTE] +> The Azure DevOps Office integration is feature complete with no plans for updates or improvements. Future investments focus on native tooling for [bulk importing or updating work items using CSV files](../../queries/import-work-items-from-csv.md). If you encounter issues with the Office integration, consider using this alternative. +> All Office integration tasks require an installed version of Visual Studio or the free [Azure DevOps Office Integration 2019](https://visualstudio.microsoft.com/downloads/#other-family), which installs the Azure DevOps Office Integration Add-in. For prerequisites, see [Azure Boards and Office integration](track-work.md). [!INCLUDE [temp](../../includes/deprecate-project.md)] - -## Enable the Azure DevOps add-in +## Install Azure DevOps Integration 2019 + +This tool allows you to connect to Azure Boards from Excel. To install the Azure DevOps Integration 2019 tool, follow these steps: + +1. Download the [Azure DevOps Office Integration 2019](https://visualstudio.microsoft.com/downloads/#other-family) tool. + +1. Install the tool by running the downloaded file. +1. Restart Excel to see the **Team** ribbon. + +If you still don't see the **Team** ribbon, follow the steps in the following sections. + +## Enable the Azure DevOps add-in + +1. In Excel, select **File** > **Options**. +2. Select **Add-ins** > **COM Add-ins** from the *Manage* dropdown menu > **Go**. + + :::image type="content" source="media/excel-options-com-add-ins.png" alt-text="Screenshot of sequence to add COM add-in."::: + +3. Make sure there's a check in the **Team Foundation Add-in** box. + + > [!div class="mx-imgBorder"] + > ![Screenshot of COM Add-ins dialog, Team Foundation Add-in checked.](media/tfs-office-issues-excel-tfs-add-in-checkbox.png) + +4. Restart Excel. + +The **Team** ribbon shows. -1. From the Excel **File** menu, choose **Options**. -2. Choose Add-ins and from the **Manage** picklist, choose **COM Add-ins**, and then choose **Go**. +If the **Team** ribbon doesn't appear at next launch, the load behavior of the add-in might be changed, so do these next steps. - > [!div class="mx-imgBorder"] - > ![Screenshot of Excel Options, Add-ins, Choose Com Add-ins.](media/excel-com-add-ins.png) +### Update the registry -3. Make sure that a check is placed in the **Team Foundation Add-in** checkbox. +1. Launch the Registry Editor from your Windows Start Menu by entering `regedit` in the Search or Run box. - > [!div class="mx-imgBorder"] - > ![Screenshot of COM Add-ins dialog, Team Foundation Add-in checked.](media/tfs-office-issues-excel-tfs-add-in-checkbox.png) + > [!div class="mx-imgBorder"] + > ![Screenshot of Run regedit command.](media/tfs-office-issues-run-regedit.png) -4. Restart Excel. You should now see the **Team** ribbon. +1. Go to one of the following paths containing the **TFCOfficeShim.Connect.[version]** folder: -If the **Team** ribbon doesn't appear at next launch, the load behavior of the add-in may have changed and you'll need to complete the following steps: + > [!NOTE] + > If there are multiple folders with the same name, select the one with the highest version number. -### Update the registry + - `HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\Excel\Addins` (if this key doesn't exist, try one of the following options) + - `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Excel\Addins` + - `HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Office\Excel\Addins` -1. Launch the Registry Editor from your Windows Start Menu by entering `regedit` in the Search or Run box. + > [!div class="mx-imgBorder"] + > ![Screenshot of LoadBehavior entry.](media/tfs-office-issues-regedit-loadbehavior-key.png) - > [!div class="mx-imgBorder"] - > ![Screenshot of Run regedit command.](media/tfs-office-issues-run-regedit.png) +1. Double-select to open **LoadBehavior** and set the value data field to `3`. If the value is `0` the **Team** ribbon doesn't load. -2. Go to one of the following paths containing the **TFCOfficeShim.Connect.[version]** folder: - - > [!NOTE] - > If there are multiple folders with the same name, select the one with the highest version number. +1. Select **OK** and restart Excel. - - `HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\Excel\Addins` (if this key doesn't exist, try one of the options below) - - `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Excel\Addins` - - `HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Office\Excel\Addins` + For more information about the LoadBehavior entry, see [Registry Entries for VSTO Add-ins, LoadBehavior values](/visualstudio/vsto/registry-entries-for-vsto-add-ins#LoadBehavior). - > [!div class="mx-imgBorder"] - > ![Screenshot of LoadBehavior entry.](media/tfs-office-issues-regedit-loadbehavior-key.png) +## Verify if the add-in is disabled -3. Double-click to open **LoadBehavior** and set the value data field to **3** (if the value is **0**, the **Team** ribbon won't load). - -4. Press **OK** and restart Excel. +1. From the Excel **File** menu, select **Options**. +1. Choose **Add-ins** and from the *Manage* dropdown menu and select **Disabled Items** > **Go**. - To learn more about the LoadBehavior entry, see [Registry Entries for VSTO Add-ins, LoadBehavior values](/visualstudio/vsto/registry-entries-for-vsto-add-ins#LoadBehavior). + > [!div class="mx-imgBorder"] + > ![Screenshot of Excel Options, Add-ins, Choose Disabled Items.](media/excel-com-disabled-items.png) + +1. If you see *Azure DevOps Add In* in the list, choose it and select **Enable**. + + > [!div class="mx-imgBorder"] + > ![Screenshot of disabled items dialog, Azure DevOps Add In checked.](media/excel-com-list-of-disabled-items.png) ## Office add-in doesn't load or open in Excel when Visual Studio fails -To connect to Azure Boards, go to the **Team** ribbon and choose **New List**. If the New List dialog fails to open, or you receive TF86001 or similar error message, then you may need to repair Visual Studio. - +To connect to Azure Boards, go to the **Team** ribbon and choose **New List**. If the New List dialog fails to open, or you receive TF86001 or similar error message, then you might need to repair Visual Studio. + > [!div class="mx-imgBorder"] -> ![TF86001 error message, Team Foundation was unable to load the Office Add-in.](media/tfs-office-issues-tf86001.png) +> ![TF86001 error message, Team Foundation was unable to load the Office Add-in.](media/tfs-office-issues-tf86001.png) -This error is typically caused when you install Visual Studio before you install Office Excel or Project. In this instance, the Visual Studio Tools for Office Run Time aren't correctly configured. To correct this error, you must repair Visual Studio. +This error usually occurs when Visual Studio is installed before Office Excel or Project. In this case, the Visual Studio Tools for Office Runtime aren't configured correctly. To fix this error, repair your Visual Studio installation. > [!NOTE] -> For authentication issues, such as `TF31003` and `TF30063`, please refer to [User account does not have permission](/previous-versions/azure/devops/reference/error/tf31003-user-account-no-permission-connect-tfs). +> For authentication issues, like `TF31003` and `TF30063`, see [User account doesn't have permission](/previous-versions/azure/devops/reference/error/tf31003-user-account-no-permission-connect-tfs). -### Prerequisites +### Prerequisites -Install Visual Studio to ensure that you have access to the Visual Studio Command Prompt and the [Gacutil.exe (Global Assembly Cache Tool)](/dotnet/framework/tools/gacutil-exe-gac-tool). If you don't have Visual Studio, you can install the [Visual Studio Community edition for free](https://visualstudio.microsoft.com/downloads/). +Install Visual Studio to ensure that you have access to the Visual Studio Command Prompt and the [Gacutil.exe (Global Assembly Cache Tool)](/dotnet/framework/tools/gacutil-exe-gac-tool). If you don't have Visual Studio, you can install the [Visual Studio Community edition for free](https://visualstudio.microsoft.com/downloads/). ### Run the Gacutil tool -1. Open the Visual Studio Command Prompt and choose to run it as an administrator. +1. Open the Visual Studio Command Prompt and choose to run it as an administrator. - > [!div class="mx-imgBorder"] - > ![Screenshot of Developer Command Prompt for VS2015 start menu with 'Run as administrator](media/tfs-office-issues-run-developer-cmd-prompt.png) + > [!div class="mx-imgBorder"] + > ![Screenshot of Developer Command Prompt for VS2015 start menu with 'Run as administrator](media/tfs-office-issues-run-developer-cmd-prompt.png) +2. Run the following commands based on your software: -4. **For Microsoft 365**, run the following commands: + |Software |Commands | + |---------|---------| + |Microsoft 365 | `GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.14.0.Microsoft.Office.Interop.Excel\15.0.0.0__71e9bce111e9429c\Policy.14.0.Microsoft.Office.Interop.Excel.dll`
`GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.14.0.office\15.0.0.0__71e9bce111e9429c\Policy.14.0.Office.dll` | + |Office 2016 and Office 2013 | `GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.12.0.Microsoft.Office.Interop.Excel\15.0.0.0__71e9bce111e9429c\Policy.12.0.Microsoft.Office.Interop.Excel.dll`<\br>`GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.12.0.office\15.0.0.0__71e9bce111e9429c\Policy.12.0.Office.dll` | + |Office 2010 |`GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.12.0.Microsoft.Office.Interop.Excel\14.0.0.0__71e9bce111e9429c\Policy.12.0.Microsoft.Office.Interop.Excel.dll`<\br>`GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.12.0.office\14.0.0.0__71e9bce111e9429c\Policy.12.0.Office.dll` | - ``` - GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.14.0.Microsoft.Office.Interop.Excel\15.0.0.0__71e9bce111e9429c\Policy.14.0.Microsoft.Office.Interop.Excel.dll - ``` +3. After you successfully run the `GACUTIL` commands, restart Excel and look for the Azure DevOps Integration Tool for Office add-in. - ``` - GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.14.0.office\15.0.0.0__71e9bce111e9429c\Policy.14.0.Office.dll - ``` +If the previous steps don't help, try the next steps: - **For Office 2016 and Office 2013**, run the following commands: +1. [Repair Office](https://support.office.com/article/Repair-an-Office-application-7821d4b6-7c1d-4205-aa0e-a6b40c5bb88b?ui=en-US&rs=en-US&ad=US). +2. Uninstall Office and then reinstall Office. +3. Contact Microsoft via the [Developer Community](https://developercommunity.visualstudio.com/home). - ``` - GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.12.0.Microsoft.Office.Interop.Excel\15.0.0.0__71e9bce111e9429c\Policy.12.0.Microsoft.Office.Interop.Excel.dll - ``` +## User can't sign in to Azure DevOps from Excel after password change - ``` - GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.12.0.office\15.0.0.0__71e9bce111e9429c\Policy.12.0.Office.dll - ``` +If you changed your network password and start receiving authentication errors with the new account info, you might be experiencing a known issue. The token stored in Visual Studio is no longer valid, but the system doesn’t recognize the need to refresh it. You don't need to take any action; the token expires eventually, and authentication begins working again, though the delay is unpredictable. Use the following workaround to manually remove the token. - **For Office 2010**, run the following commands: +### Remove the token from the registry - ``` - GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.12.0.Microsoft.Office.Interop.Excel\14.0.0.0__71e9bce111e9429c\Policy.12.0.Microsoft.Office.Interop.Excel.dll - ``` +1. Close all open Excel instances. +2. Save and then clear the registry path by running the following commands from an elevated Command Prompt (run as administrator): + ```CommandPrompt + reg export HKEY_CURRENT_USER\SOFTWARE\Microsoft\VSCommon\14.0\ClientServices\TokenStorage\VisualStudio\VssApp %TEMP%\oicreds.reg ``` - GACUTIL /I C:\Windows\assembly\GAC_MSIL\Policy.12.0.office\14.0.0.0__71e9bce111e9429c\Policy.12.0.Office.dll - ``` - -3. Once you've successfully run the `GACUTIL` commands, restart Excel and look for the Azure DevOps Integration Tool for Office add-in. - -If the above steps are unsuccessful, try the following steps: -1. Run a full [repair of Office](https://support.office.com/article/Repair-an-Office-application-7821d4b6-7c1d-4205-aa0e-a6b40c5bb88b?ui=en-US&rs=en-US&ad=US). - -2. Uninstall Office and Reinstall Office. - -3. Contact the Microsoft support team. + ```CommandPrompt + reg delete HKEY_CURRENT_USER\SOFTWARE\Microsoft\VSCommon\14.0\ClientServices\TokenStorage\VisualStudio\VssApp + ``` +3. Open Excel and it prompts for sign-in when it connects to Azure DevOps. + +Wait until the token expires or delete this reg key every time a password changes if configured in a way that causes this issue. + +## Intermittent issues doing refresh and publish + +If you get an error during refresh or publish, there might be a Conditional Access Policy in Microsoft Entra ID. To resolve this issue, clear the contents of the folder: ```%LOCALAPPDATA%\.IdentityService```. + +## Can't cast COM object of type Microsoft.Office.Interop.Excel.ApplicationClass + +You might get an error message when opening a work item list in Excel, triggered from Team Explorer. For more information, see [How to solve 'Unable to cast COM object of type Microsoft.Office.Interop.Excel.ApplicationClass' to interface type 'Microsoft.Office.Interop.Excel._Application.''](/archive/blogs/dau-blog/how-to-solve-unable-to-cast-com-object-of-type-microsoft-office-interop-excel-applicationclass-to-interface-type-microsoft-office-interop-excel-_application) + + + +## Resolve data conflicts when you publish or refresh Excel data + +A data conflict occurs when you try to publish a work item from [Excel](bulk-add-modify-work-items-excel.md) and the version of that work item differs from the version in the work item database. The following example shows how two team members can create such a conflict: + +1. A team member opens a copy of a work item in a work item list in Excel or Project. +2. Team member A edits the work item and makes one set of changes. +3. Team member B edits that same work item and makes a different set of changes, and publishes those changes. +4. Team member A finishes editing the work item and tries to publish the changes to the work item. +5. Excel or Project displays the **Work Item Publishing Errors** dialog box, which shows items that it couldn't publish. + +### Resolve a data conflict + +1. In the **Work Item Publishing Errors** dialog box, for each work item in the **Unpublished work items** box that has **Conflict** in the **Issue** column, follow these steps. +2. In the **Unpublished work items** box, select the work item. + The **Details** area shows a list of conflicts for the selected work item. The **Conflicting field** column shows the name of the field in which the conflict occurs. The **Local version** and **Server version** columns show the local and server data, respectively, and a check box appears next to the data in each of these columns. +3. For each row in the **Details** box, select the check box next to the correct value. + When you select the local version, the data in Office Excel or Office Project overwrites the data on the server. If you select the server version, the server data overwrites the data in Office Excel or Office Project. +4. Select **Publish**. + +> [!NOTE] +> This step publishes only the work items that you corrected. If you don't resolve all data validation errors related to a work item, that work item isn't published. + + + +## Resolve data validation errors that occur when you publish from Excel + +A data validation error occurs when a change in the work item list or project plan violates a work item type's rule. The following examples show common data validation errors: + +- Someone assigns a work item to a team member whose name isn't included in the list of allowed values +- Someone creates a work item but forgets to complete a required field, such as the work item type. + +If a data validation error occurs when you try to publish changes, the **Work Item Publishing Errors** dialog box appears, and in the **Unpublished work items** list the **Issue** column shows **Validation error** or another phrase that contains **Invalid**. + +### Resolve a data validation error + + You can use the **Work Item Publishing Errors** dialog box to resolve a data validation error. + +1. In the **Work Item Publishing Errors** dialog box, for each work item that appears with a data validation error, follow these steps. + + > [!NOTE] + > If the data validation error is an invalid work item type, the **Edit Work Item** button isn't visible, and a work item form doesn't appear. You must correct the error in the Office Excel worksheet or the Office Project plan. For information about how to resolve an error in Office Excel, see the next procedure in this article. + +2. In the **Unpublished work items** box, select the work item, and then select **Edit Work Item**. + + A work item form appears. + +3. In the work item form, review the information and correct the value. +4. Select **Close** to save your changes and close the work item form. +5. After you correct the data validation errors, select **Publish** to publish the corrected work items. + + > [!NOTE] + > This step publishes only the work items that you corrected. If you don't resolve a data validation error, that work item isn't published. + +6. Select **Close** to close the **Work Item Publishing Errors** dialog box. + +### Resolve a data validation error by using error checking in Excel + +You can use the Office Excel tools to find and resolve an error in a work item list. For more information about how to use Office Excel error checking tools, see the Office Excel Help. + +#### Resolve a data validation error by using error checking in Excel 2007 + +1. In Microsoft Excel, select the **Formulas** tab. +2. In the **Formula Auditing** group, select **Error Checking**. + If the error checking tool finds an error, the **Error Checking** dialog box appears. +3. For basic information about the error, see the text that describes the error in the **Error Checking** dialog box. For more information about the error, select **Help on this error**. +4. In the work item list, select the cell that contains the error, and then correct the value. +5. In the **Error Checking** dialog box, select **Resume** to find the next data validation error. + - If the **Error Checking** dialog box shows another error, repeat the previous two steps to resolve the error. + - If a message appears that indicates error checking completed, select **OK** to close both this message and the **Error Checking** dialog box. ## Related articles +- [Bulk modify work items (web portal)](../bulk-modify-work-items.md) +- [Bulk import or update work items using CSV files](../../queries/import-work-items-from-csv.md) - [FAQs: Work in Excel connected to Azure Boards](faqs.yml) - [Add or remove add-ins](https://support.office.com/article/Add-or-remove-add-ins-0af570c4-5cf3-4fa9-9b88-403625a0b460) diff --git a/docs/boards/backlogs/office/track-work.md b/docs/boards/backlogs/office/track-work.md index 419af7bb08f..06e59682aaf 100644 --- a/docs/boards/backlogs/office/track-work.md +++ b/docs/boards/backlogs/office/track-work.md @@ -1,50 +1,35 @@ --- title: Connect Azure Boards to an Office client to track your work titleSuffix: Azure Boards -description: Learn how to connect Excel to integrate and track your work in Azure Boards or Azure DevOps +description: Learn how to connect to Excel to integrate and track your work in Azure Boards or Azure DevOps Server. ms.service: azure-devops-boards ms.assetid: fbd7b5e1-e4c4-4976-9596-236e980fdb3b ms.author: chcomley author: chcomley -ms.topic: tutorial +ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 10/17/2024 +#customer intent: As a team member or lead, I want to use Microsoft Excel in working with Azure Boards or Azure DevOps Server to improve my team's tracking efforts. --- # Connect Azure Boards to an Office client [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" To support your work tracking efforts, you can use Microsoft Excel. You can either work in online mode, where you're connected to either Azure Boards or Azure DevOps Server. Or, work in offline mode, where you access the local computer and document. ::: moniker-end -::: moniker range="tfs-2018" - -To support your work tracking efforts, use Microsoft Excel and Microsoft Project. You can either work in online mode, where you're connected to Azure DevOps. Or, work in offline mode, where you access the local computer and document. - -::: moniker-end - -> [!IMPORTANT] -> All Office integration tasks require that you have installed a version of Visual Studio or the free [Azure DevOps Office Integration 2019](https://visualstudio.microsoft.com/downloads/#other-family). - -In this article you'll learn about the following items: -> [!div class="checklist"] -> * Which Office clients support connection to Azure DevOps -> * Prerequisites for connecting from an Office client to Azure DevOps -> * Importance of publishing and refreshing work from an Office client -> * How to connect Excel to an Azure Boards project -> * How to work offline and reconnect to Azure DevOps -> * Marketplace extensions that support integration with Office clients +> [!TIP] +> For bulk import or to update work items, use the [web portal](../bulk-modify-work-items.md) or [CSV import](../../queries/import-work-items-from-csv.md). ## Supported Office clients and Azure DevOps versions -The following table indicates the Office clients supported for each Azure DevOps version. +The following table indicates the Office clients supported for each Azure DevOps version. -> [!NOTE] -> macOS isn't supported. Even if you've installed Visual Studio for Mac, connection to Azure DevOps from Excel or any other Office client isn't supported. +macOS isn't supported. Even if you installed Visual Studio for Mac, connection to Azure DevOps from Excel or any other Office client isn't supported. --- @@ -67,7 +52,8 @@ The following table indicates the Office clients supported for each Azure DevOps :::column span="2"::: Azure DevOps Services Azure DevOps Server 2020 -Azure DevOps Server 2019 +Azure DevOps Server 2019 +Visual Studio 2022 Visual Studio 2019 Azure DevOps Office Integration 2019 :::column-end::: @@ -98,97 +84,53 @@ Visual Studio 2017 :::row-end::: > [!NOTE] -> 1. Support for Project integration and the **TFSFieldMapping** command is deprecated for Azure DevOps Server 2019 and later versions. You might find support using one of the [Marketplace extensions](#marketplace-extensions). -> 1. Support for linking PowerPoint files to work items from within PowerPoint has been deprecated starting with Visual Studio 2019 and Azure DevOps Office Integration 2019. You can still link to PowerPoint using the Storyboard link from within a work item. Also, the Visual Studio Gallery for PowerPoint Storyboarding has been deprecated. +> - Support for Project integration and the **TFSFieldMapping** command is deprecated for Azure DevOps Server 2019 and later versions. You might find support using one of the [Marketplace extensions](#marketplace-extensions). +> - Support for linking PowerPoint files to work items from within PowerPoint is deprecated starting with Visual Studio 2019 and Azure DevOps Office Integration 2019. You can still link to PowerPoint using the Storyboard link from within a work item. Also, the Visual Studio Gallery for PowerPoint Storyboarding is deprecated. ## Prerequisites -Connection from an Office client to an Azure Boards project requires that you've installed the necessary software and have the necessary permissions. +Connection from an Office client to an Azure Boards project requires the following software and permissions. ::: moniker range="azure-devops" -- To connect Excel to Azure Boards, you must have installed Office Excel 2010 or later version, including Office Excel 365. - -- Installed [Azure DevOps Office Integration 2019 (free)](https://visualstudio.microsoft.com/downloads/#other-family). - - > [!NOTE] - > The only way to get the Azure DevOps Office Integration plug-in is by installing one of the latest editions of Visual Studio or Azure DevOps Office Integration. The plug-in supports connection to Azure DevOps from Excel. - +- To connect Excel to Azure Boards, install Office Excel 2010 or later version, including Office Excel 365. +- All Office integration tasks require an installed version of Visual Studio or the free [Azure DevOps Office Integration 2019](https://visualstudio.microsoft.com/downloads/#other-family). +- The only way to get the Azure DevOps Office Integration plug-in is to install one of the latest editions of Visual Studio or Azure DevOps Office Integration. The plug-in supports connection to Azure DevOps from Excel. - To connect to an Azure Boards project, you need to be a [member of the project](../../../organizations/security/add-users-team-project.md). If you don't have an Azure Boards project yet, you can [create one](../../get-started/sign-up-invite-teammates.md). ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - -- To connect Excel to Azure Boards, you must have installed Office Excel 2010 or later version, including Microsoft 365. - -- Installed [Azure DevOps Office Integration 2019 (free)](https://visualstudio.microsoft.com/downloads/#other-family). - - > [!NOTE] - > The only way to get the Team Foundation plug-in is by installing one of the latest editions of Visual Studio or Azure DevOps Office Integration 2019. The Azure DevOps Office Integration 2019 plug-in supports connection to Azure DevOps from Excel. - -- To connect to an Azure Boards project, you need to be a [member of the project](../../../organizations/security/add-users-team-project.md). If you don't have an Azure Boards project yet, you can [create one](../../../organizations/projects/create-project.md). - -::: moniker-end - -::: moniker range="tfs-2018" - -- To connect Excel to Azure Boards, you must have installed Office Excel 2010 or later version, including Microsoft 365. - -- To connect Project to Azure Boards, you must have installed Office Project 2010 or later version, including Microsoft 365. - -- To connect PowerPoint to Azure Boards, you must have installed [Office PowerPoint 2010 or later version installed](https://www.microsoftstore.com/store/msusa/en_US/pdp/productID.323024400). - -- Installed Visual Studio 2013 or later version or [Team Foundation Server Standalone Office Integration (free)](https://visualstudio.microsoft.com/downloads#team-foundation-server-office-integration-2017) - - > [!NOTE] - > The only way to get the Team Foundation plug-in is by installing one of the latest editions of Visual Studio or the TFS Standalone Office Integration plug-in. The plug-in supports connection to TFS from Excel, Project, and the PowerPoint-based storyboarding tool. +::: moniker range=" [!IMPORTANT] -> You may receive the following error if you install Microsoft Office 2010 on the same computer as a previous version of Office. -> -> **Team Foundation Error** -> -> **Interface not registered (Exception from HRESULT: 0x80040155)** -> -> You may be able to resolve this error by repairing Office. You can access the Repair option by opening the **Control Panel**, choose **Uninstall or change a program**, open the context menu for Office 2010, and then choose **Change**. See also, [Azure DevOps-Office integration issues](tfs-office-integration-issues.md). +> You might receive the following error if you install Microsoft Office 2010 on the same computer as a previous version of Office. +> +> **Team Foundation Error**, **Interface not registered (Exception from HRESULT: 0x80040155)** +> +> You might resolve this error by repairing Office. Access the Repair option by opening the **Control Panel**, choose **Uninstall or change a program**, open the context menu for Office 2010, and then choose **Change**. For more information, see [Resolve Azure DevOps and Office integration issues](tfs-office-integration-issues.md). ## Publish and refresh work items -::: moniker range="> tfs-2018" +::: moniker range="<=azure-devops" -When you add or update work items from Excel, local copies of your work items are created. To keep data in sync, it's important to refresh your local file when you open it and publish and refresh frequently during a long online session. - -::: moniker-end - -::: moniker range="tfs-2018" - -When you add or update work items from Excel or Project, local copies of your work items are created. To keep data in sync, it's important to refresh your local file when you open it and publish and refresh frequently during a long online session. +When you add or update work items from Excel, local copies of your work items are created. To keep data in sync, refresh your local file when you open it and publish and refresh frequently during a long online session. ::: moniker-end @@ -198,41 +140,34 @@ To keep work items in sync from your local data store and Azure Boards, publish ### Azure DevOps and Excel -![Azure DevOps and Excel, conceptual image](media/connect/excel-sequence.png) +:::image type="content" source="media/connect/excel-sequence.png" alt-text="Diagram shows the Team Explorer and Excel workflow."::: To work in Excel, see [Bulk add work items with Excel](bulk-add-modify-work-items-excel.md). ## Connect an Azure DevOps project to Excel -> [!NOTE] -> While this section illustrates how to connect Excel to an Azure Boards project, the steps for connecting from Project or PowerPoint are similar. - -To add or modify work items by using Excel, you connect your worksheet to a project. Establishing this connection binds the document to the Azure DevOps project to exchange information. +To add or modify work items by using Excel, connect your worksheet to a project. Establish this connection to bind the document to the Azure DevOps project to exchange information. > [!NOTE] -> When you connect to Azure Boards in the cloud, the **Team Project Collection** is automatically selected as there is only one collection associated with your Azure DevOps Services organization. When you connect to Azure Boards in an on-premises server, you choose the **Team Project Collection** prior to choosing the project. +> +> - This section illustrates how to connect Excel to an Azure Boards project. The steps to connect to PowerPoint are similar. +> - When you connect to Azure Boards in the cloud, the **Team Project Collection** automatically gets selected, because there's only one collection associated with your Azure DevOps Services organization. When you connect to Azure Boards in an on-premises server, choose the **Team Project Collection** before you choose the project. You can start work from the web portal, Excel, or Visual Studio/Team Explorer. Your worksheet is associated with either a list of work items or a work item query. ### [Open query in Excel (web portal)](#tab/open-excel) -This connection method requires that you have installed [Azure DevOps Open in Excel](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-open-work-items-in-excel). It also requires Visual Studio 2017 or later version. +This connection method requires that you install [Azure DevOps Open in Excel](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-open-work-items-in-excel). It also requires Visual Studio 2017 or later version. + +1. From your web browser, check that you selected the right project, choose **Boards** > **Queries**, and then choose **All**. -1. From your web browser, (1) check that you've selected the right project, (2) choose **Boards>Queries**, and then (3) choose **All**. - > [!div class="mx-imgBorder"] - > - > - > - > ![Open Boards Queries, vertical nav](../../queries/media/view-run-queries/open-queries-vert.png) + :::image type="content" source="../../queries/media/view-run-queries/open-queries-vert.png" alt-text="Screenshot shows selecting Boards, then Queries."::: 1. Choose the query you want to open in Excel. -1. From the **Results** tab, choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon. - > [!div class="mx-imgBorder"] - > - > - > - > ![Query Results, context menu, Open in Excel Open Boards Queries, vertical nav](media/connect/open-in-excel-from-portal.png) +1. From the **Results** tab, choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon. + + :::image type="content" source="media/connect/open-in-excel-from-portal.png" alt-text="Screenshot shows Query Results, context menu, Open in Excel Open Boards Queries."::: ### [Connect from client to Azure Boards](#tab/open-excel-cloud) @@ -241,49 +176,38 @@ To connect from your Office client to an Azure DevOps Services project, do the f 1. Start with a blank worksheet. 1. If your client is signed into a user account, make sure that it's your Azure DevOps user account. If not, choose your account name and sign in as another user. - > [!div class="mx-imgBorder"] - > - > - > - > ![Screenshot of Excel Team Ribbon, Choose New List. ](media/connect/sign-in-as-other-user.png) -1. If you don't see the **Team** ribbon (or the **Team** menu if you use Office 2007), see [Azure DevOps Office integration issues](tfs-office-integration-issues.md). + :::image type="content" source="media/connect/sign-in-as-other-user.png" alt-text="Screenshot shows Excel Team Ribbon, Choose New List."::: -1. Choose the **Team** tab, place your cursor in Cell A1, and then choose **New List**. +1. If you don't see the **Team** ribbon or the **Team** menu if you use Office 2007, see [Resolve Azure DevOps and Office integration issues](tfs-office-integration-issues.md). - ![Screenshot of Excel New List option.](media/excel/team-ribbon.png) +1. Select **Team**, place your cursor in `Cell A1`, and then select **New List**. -1. The Connect to Azure DevOps Server dialog opens. - > [!div class="mx-imgBorder"] - > - > - > - > ![Connect to Azure DevOps Server dialog.](media/connect/connect-to-azure-devops.png) + :::image type="content" source="media/excel/team-ribbon.png" alt-text="Screenshot shows the Excel New List option."::: - If you're signed into your Office client with your Azure DevOps user account, the set of servers, both cloud and on-premises that you have access to, automatically populate in the drop-down menu. +1. The **Connect to Azure DevOps Server** dialog opens. + + :::image type="content" source="media/connect/connect-to-azure-devops.png" alt-text="Screenshot shows the Connect to Azure DevOps Server dialog."::: - If you're not signed-in, you're working from an older version of an Office client, or you haven't connected to any servers previously, you need to add them now. + If you're signed into your Office client with your Azure DevOps user account, the set of servers, both cloud and on-premises that you have access to, automatically populate in the drop-down menu. -1. Add a server to connect to. + If you're not signed-in, you're working from an older version of an Office client, or you aren't connected to any servers, add them now. - (1) Choose **Servers...**, (2) choose **Add...**, (3) enter the URL of your Azure Boards organization, and (4) check that the preview matches the URL that you entered. Then choose **OK**. +1. Add a server. Choose **Servers...**, choose **Add...**, enter the URL of your Azure Boards organization, and check that the preview matches the URL that you entered. Choose **OK**. - ![Connect to Azure DevOps Server sub-dialogs to add or remove a server.](media/connect/4-steps-connect-to-cloud.png) + :::image type="content" source="media/connect/connect-cloud.png" alt-text="Screenshot shows the Connect to Azure DevOps Server dialogs to add or remove a server."::: If you can't connect, [get added as a team member](../../../organizations/security/add-users-team-project.md#add-team-members). 1. With the server selected, choose the project you want to connect to, and then choose **Connect**. - > [!div class="mx-imgBorder"] - > - > - > - > ![Connect to Azure DevOps dialog, choose project.](media/connect/choose-project.png) + + :::image type="content" source="media/connect/choose-project.png" alt-text="Screenshot shows the Connect to Azure DevOps dialog, where you can choose a project."::: Make sure your Azure DevOps user account appears at the bottom of the dialog. If it isn't, choose **Switch User** and sign in to the correct account. -1. From the New List dialog, choose **Input list**. Or, if you want to work with a list of work items defined in a query, choose **Query list**. +1. From the **New List** dialog, choose **Input list**. Or, if you want to work with a list of work items defined in a query, choose **Query list**. - ![New list dialog, Select input list.](media/excel/2019-input-list-dialog.png) + :::image type="content" source="media/excel/2019-input-list-dialog.png" alt-text="Screenshot shows the New List dialog where you can select Input list."::: ### [Connect client to Azure DevOps on-premises](#tab/open-excel-on-prem) @@ -291,124 +215,89 @@ To connect from your Office client to an Azure DevOps Server project, do the fol 1. Start with a blank worksheet. -1. If your client is signed into a user account, make sure that it's your Azure DevOps account. If not, choose your account name and sign in as another user. - > [!div class="mx-imgBorder"] - > - > - > - > ![Screenshot to select sign-in on Excel ribbon.](media/connect/sign-in-as-other-user.png) +1. If your client is signed into a user account, make sure that it's yours. If not, choose your account name and sign in as another user. + + :::image type="content" source="media/connect/sign-in-as-other-user.png" alt-text="Screenshot to select sign-in on Excel ribbon."::: -1. If you don't see the **Team** ribbon (or the **Team** menu if you use Office 2007), see [Azure DevOps-Office integration issues](tfs-office-integration-issues.md). +1. If you don't see the **Team** ribbon or the **Team** menu if you use Office 2007, see [Resolve Azure DevOps and Office integration issues](tfs-office-integration-issues.md). 1. Choose the **Team** tab, place your cursor in Cell A1, and then choose **New List**. - ![Screenshot of Excel New List option on Team ribbon.](media/excel/team-ribbon.png) + :::image type="content" source="media/excel/team-ribbon.png" alt-text="Screenshot of Excel New List option on Team ribbon."::: -1. The Connect to Azure DevOps Server dialog opens. - > [!div class="mx-imgBorder"] - > - > - > - > ![Connect to Azure DevOps Server dialog, on-premises version](media/connect/connect-to-azure-devops.png) + The Connect to Azure DevOps Server dialog opens. - If you're signed into your Office client with your Azure DevOps user account, the set of servers, both cloud and on-premises that you have access to, automatically populate in the drop-down menu. + :::image type="content" source="media/connect/connect-to-azure-devops.png" alt-text="Screenshot shows the Connect to Azure DevOps Server dialog, on-premises version."::: - If you're not signed-in, you're working from an older version of an Office client, or you haven't connected to any servers previously, you need to add them now. + If you're signed into your Office client with your Azure DevOps user account, the set of servers that you have access to, both cloud and on-premises, automatically populate in the dropdown menu. -1. Add a server to connect to. + If you're not signed-in, you're working from an older version of an Office client, or you aren't connected to any servers, add them now. - (1) Choose **Servers...**, (2) choose **Add...**, (3) enter the name of your Azure DevOps Server instance. As needed, change the Port number if your deployment uses a non-default port number. The Preview entry should display the correct URL for your deployment. (4) Choose **OK**. +1. Add a server. Select **Servers...**, choose **Add...**, enter the name of your Azure DevOps Server instance. As needed, change the Port number if your deployment uses a nondefault port number. The Preview entry should display the correct URL for your deployment. Choose **OK**. - ![Connect to Azure Server sub-dialogs, on-premises versions](media/connect/4-steps-connect-to-on-prem.png) + :::image type="content" source="media/connect/connect-on-premises.png" alt-text="Screenshot shows the Connect to Azure Server dialogs, on-premises versions."::: - Choose **Close** to close the Add/Remove servers dialog. From the Select an Azure DevOps Server dialog, make sure the server you added is selected, and then choose **Connect**. + Choose **Close** to close the add/remove servers dialog. From the **Select an Azure DevOps Server** dialog, make sure the server you added is selected, and choose **Connect**. If you can't connect, [get added as a team member](../../../organizations/security/add-users-team-project.md#add-team-members). -1. With the server selected, choose the project you want to connect to, and then choose **Connect**. - > [!div class="mx-imgBorder"] - > - > - > - > ![Connect to Azure DevOps dialog, choose project, on-premises version. ](media/connect/choose-project.png) +1. With the server selected, choose the project you want to connect to, and choose **Connect**. + + :::image type="content" source="media/connect/choose-project.png" alt-text="Screenshot shows the Connect to Azure DevOps dialog where you can choose a project, on-premises version."::: Make sure your Azure DevOps user account appears at the bottom of the dialog. If it isn't, choose **Switch User** and sign in to the correct account. -1. From the New List dialog, choose **Input list**. Or, if you want to work with a list of work items defined in a query, choose **Query list**. +1. From the **New List** dialog, choose **Input list**. Or, if you want to work with a list of work items defined in a query, choose **Query list**. - ![New list, Select input list, on-premises version.](media/excel/2019-input-list-dialog.png) + :::image type="content" source="media/excel/2019-input-list-dialog.png" alt-text="Screenshot of New list, Select input list, on-premises version."::: ### [Open Excel from Visual Studio](#tab/open-excel-vs) 1. Open Visual Studio and then Team Explorer. > [!IMPORTANT] - > To work from Visual Studio 2019/Team Explorer, you need to select the **Tools - > - > Options - > - > Work Items - > - > General** Legacy experience. For more information, see [Set the Work Items experience in Visual Studio 2019](../../work-items/set-work-item-experience-vs.md). - > - > - > - > - > - > - > - > [!div class="mx-imgBorder"] - > - > - > - > ![Visual Studio Options dialog, Work Items, General](media/connect/work-items-legacy-experience.png) + > To work from Visual Studio/Team Explorer, select **Tools** > **Options** > **Work Items** > +**General** > **Legacy experience**. For more information, see [Set the Work Items experience](../../work-items/set-work-item-experience-vs.md). + + :::image type="content" source="media/connect/work-items-legacy-experience.png" alt-text="Screenshot shows the Visual Studio Options dialog, with Work Items and General selected."::: 1. Connect to your Azure DevOps project that contains the work items you want to add to or update. For more information, see [Connect to a project](../../../organizations/projects/connect-to-projects.md). 1. Right-click the query you want to open and choose. - > [!div class="mx-imgBorder"] - > - > - > - > ![Screenshot of Team Explorer, Work Items, Query, context menu.](media/connect/open-from-visual-studio-query.png) - Excel opens with the work items listed in the query you selected. + :::image type="content" source="media/connect/open-from-visual-studio-query.png" alt-text="Screenshot shows a Team Explorer context menu with the option Open in Microsoft Excel."::: + + Excel opens with the work items listed in the query that you selected. *** For more information, see [Bulk add work items with Excel](bulk-add-modify-work-items-excel.md). > [!TIP] -> You can use multiple worksheets within an Excel workbook to work with different input or query lists. However, you can only connect to one project per workbook. +> You can use multiple worksheets within an Excel workbook to work with different input or query lists. You can only connect to one project per workbook. ::: moniker range="< azure-devops" -If you move your Azure DevOps project to a different project collection in the same instance of Azure DevOps, your documents automatically reconnect. However, if the project moves to a different instance of Azure DevOps, you must manually reconnect your documents to the new server. +If you move your Azure DevOps project to a different project collection in the same instance of Azure DevOps, your documents automatically reconnect. If the project moves to a different instance of Azure DevOps, you must manually reconnect your documents to the new server. ::: moniker-end - ## Work offline and reconnect to Azure Boards -One advantage of working in Excel or Project is that you can work offline and add or modify work items. The following procedures show you how to disconnect an Excel work item list or a Project plan from Azure Boards. You can then reconnect later to synchronize the document with the work item database. +One advantage of working in Excel is that you can work offline and add or modify work items. The following procedures show you how to disconnect an Excel work item list from Azure Boards. You can then reconnect later to synchronize the document with the work item database. > [!NOTE] -> If the project that contains work items for your Excel or Project document is moved to a different organization or Azure DevOps Server instance, you must reconfigure the server to which the document connects. For more information, see [Connect Azure DevOps project to Excel](#connect-an-azure-devops-project-to-excel) provided earlier in this article. +> If the project that contains work items for your Excel document is moved to a different organization or Azure DevOps Server instance, you must reconfigure the server to which the document connects. For more information, see [Connect Azure DevOps project to Excel](#connect-an-azure-devops-project-to-excel) earlier in this article. ### Disconnect a document file from the network -To disconnect an Excel or Project document file from the network: +To disconnect an Excel document file from the network: 1. Open the document that you want to change while you're offline. -1. Refresh the work item list to retrieve the latest information from the work item database. - - - If you're using Excel, on the **Team** ribbon, in the **Work Items** group, choose **Refresh**. - - If you're using Project, on the **Team** menu, choose **Refresh**. +1. Refresh the work item list to retrieve the latest information from the work item database. In Excel, on the **Team** ribbon, in the **Work Items** group, choose **Refresh**. -1. If you're using Excel, add to the work item list the columns for all fields that you want to modify. - - You can't add columns when the work item list is disconnected from the server. +1. Add to the work item list the columns for all fields that you want to modify. You can't add columns when the work item list is disconnected from the server. 1. Disconnect your computer from the network, or save the work item list file and copy it to another computer. @@ -416,42 +305,30 @@ To disconnect an Excel or Project document file from the network: 1. Modify or update the work item list as needed. - > [!NOTE] - > You can't create most types of links between work items when the work item document is disconnected from the system. The exceptions are parent-child links in an Excel tree list, and both parent-child and predecessor-successor links in a Project plan. + You can't create most types of links between work items when the work item document is disconnected from the system. The exceptions are parent-child links in an Excel tree list. ### Reconnect a file to Azure Boards -To reconnect an Excel or Project document file: +To reconnect an Excel document file: 1. Reconnect your computer to the network, or copy the file to a computer that is connected to Azure Boards. -1. If you changed the document while you were offline, follow one of these steps: - - - If you're using Excel, on the **Team** ribbon, in the **Work Items** group, choose **Publish**. - - If you're using Project, on the **Team** menu, choose **Publish Changes**. +1. If you changed the document offline, in Excel, on the **Team** ribbon, in the **Work Items** group, choose **Publish**. -1. If you didn't change the document while you were offline, follow one of these steps: - - - If you're using Excel, on the **Team** ribbon, in the **Work Items** group, choose **Refresh**. - - If you're using Project, on the **Team** menu, choose **Refresh**. +1. If you didn't change the document offline, in Excel, on the **Team** ribbon, in the **Work Items** group, choose **Refresh**. 1. Resolve any data validation errors or conflicts that occur. - - ## Marketplace extensions The following Marketplace extensions support integration between Azure DevOps and Office products. - [Azure DevOps Open in Excel](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-open-work-items-in-excel): Opens a selected query in Excel. -- [Office 365 Integration](https://marketplace.visualstudio.com/items?itemName=ms-vsts.vss-services-o365): Pushes notification of configurable Azure DevOps events to an Office 365 Group. - -For more extensions that integrate with Microsoft Project, see [Azure Boards migration and integration, Project and portfolio management](../../extensions/migrate-integrate.md#project-and-portfolio-management). +- [Office 365 Integration](https://marketplace.visualstudio.com/items?itemName=ms-vsts.vss-services-o365): Pushes notifications of configurable Azure DevOps events to an Office 365 Group. ## Related articles -- [FAQs: Work in Excel connected to Azure Boards](faqs.yml) -- [Resolve publishing errors](faqs.yml#how-do-i-resolve-publishing-issues) -- [Bulk add or modify work items with Excel](bulk-add-modify-work-items-excel.md) +- [Bulk modify work items (web portal)](../bulk-modify-work-items.md) +- [Bulk import or update work items using CSV files](../../queries/import-work-items-from-csv.md) +- [Work in Excel connected to Azure Boards](faqs.yml) - [Create your backlog](../../backlogs/create-your-backlog.md) -- [Requirements and compatibility](/azure/devops/server/requirements) diff --git a/docs/boards/backlogs/organize-backlog.md b/docs/boards/backlogs/organize-backlog.md index e6fe722a6ac..25b51e186f9 100644 --- a/docs/boards/backlogs/organize-backlog.md +++ b/docs/boards/backlogs/organize-backlog.md @@ -1,10 +1,10 @@ --- title: Organize your product backlog in Azure Boards -titleSuffix: Azure Boards +titleSuffix: Azure Boards description: Learn how to map or parent backlog items to features. Then learn how to map features to epics in Azure Boards. -ms.custom: "boards-backlogs, seodec18" +ms.custom: boards-backlogs ms.service: azure-devops-boards -ms.assetid: C294ACBD-00A3-4FCF-8777-B354BC0CC1EF +ms.assetid: C294ACBD-00A3-4FCF-8777-B354BC0CC1EF ms.author: chcomley author: chcomley ms.topic: tutorial @@ -12,7 +12,6 @@ monikerRange: '<= azure-devops' ms.date: 10/27/2022 --- - # Organize your backlog and map child work items to parents in Azure Boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -27,9 +26,9 @@ In this article you'll learn how to: > * Group backlog items using the Mapping pane > * Reparent items through dragging or the **Change parent** option - [!INCLUDE [temp](../includes/setup-backlogs-boards.md)] +## Prerequisites [!INCLUDE [temp](../includes/prerequisites.md)] @@ -78,48 +77,6 @@ From your web browser, open your product backlog. ::: moniker-end -::: moniker range="azure-devops-2019" - -1. (1) Check that you've selected the right project, (2) choose **Boards>Backlogs**, and then (3) select the correct team from the team selector menu. - - ![Screenshot of Open Work, Backlogs, for a team, on-premises version.](../sprints/media/assign-items-sprint/open-work-backlogs-agile.png) - - To choose another team, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all backlogs** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Choose another team, on-premises version.](../sprints/media/assign-items-sprint/team-selector-backlogs-agile.png) - - > [!TIP] - > Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to favorite a team backlog. Favorited artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorited icon) appear at the top of the team selector list. - -1. Check that you have selected **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI) as the backlog level. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Choose product backlog level, Backlog items, Stories, or Requirements, on-premises version.](../sprints/media/assign-items-sprint/select-product-backlog-agile.png) - -2. (Optional) To choose which columns should display and in what order, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select **Column options**. For more information, see [Change column options](../backlogs/set-column-options.md). - - > [!div class="mx-imgBorder"] - > ![Screenshot of Open Column Options, on-premises version.](../sprints/media/assign-items-sprint/open-work-backlogs-column-options-agile.png) - -::: moniker-end - - -::: moniker range="tfs-2018" - -From your web browser, open your team's product backlog. (1) Select the team from the project/team selector, choose (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - -> [!div class="mx-imgBorder"] -> ![Screenshot of Open the Boards, Backlogs page, TFS-2018 version.](../sprints/media/assign-items-sprint/open-work-backlogs-standard.png) - -To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Choose another team, TFS-2018 version.](../sprints/media/assign-items-sprint/team-selector-backlogs-standard.png) - -::: moniker-end - - [!INCLUDE [temp](../includes/image-differences-with-wits.md)] ## Show parent tasks and expand the tree hierarchy @@ -145,8 +102,7 @@ You can set various options to view backlog work items using the **View options* ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - +::: moniker range=" ## Map items to group them under a feature or epic If you've already created your backlog, and now you want to organize it, you can do that most easily by mapping child items to parents. - ::: moniker range="azure-devops" 1. Choose :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options** and select **Mapping**. @@ -206,7 +147,7 @@ If you've already created your backlog, and now you want to organize it, you can ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Change a parent of multiple backlog items @@ -282,25 +210,21 @@ From a product or portfolio backlog, you can multi-select several work items and ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] > ![Screenshot of Change parent menu option of several backlog items.](media/organize-backlog/multi-reparent.png) ::: moniker-end - [!INCLUDE [temp](../includes/add-portfolio-backlogs.md)] [!INCLUDE [temp](../includes/display-rollup-section.md)] - ## Related articles - [Define features and epics](define-features-epics.md) - [Configure your backlog view](configure-your-backlog-view.md) - [Work with multi-team ownership of backlog items](backlogs-overview.md#multi-team) - [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md) -- [Product backlog controls](product-backlog-controls.md) - [Filter product and portfolio backlogs](filter-backlogs-boards-plans.md) - [Keyboard shortcuts](../../project/navigation/keyboard-shortcuts.md) - diff --git a/docs/boards/backlogs/product-backlog-controls.md b/docs/boards/backlogs/product-backlog-controls.md deleted file mode 100644 index 4145bb04bc9..00000000000 --- a/docs/boards/backlogs/product-backlog-controls.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -title: Change or filter the view for your backlogs in Azure Boards -titleSuffix: Azure Boards -description: Learn how to switch views and enable from your product or portfolio backlogs in Azure Boards. -ms.custom: "boards-backlogs, seodec18" -ms.service: azure-devops-boards -ms.assetid: -ms.author: chcomley -author: chcomley -ms.topic: conceptual -monikerRange: '<= azure-devops' -ms.date: 04/28/2022 ---- - - -# Use product backlog controls in Azure Boards - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - - - -Once you've defined your product backlog, you can use the following controls to change or filter the view. - - -> [!IMPORTANT] -> If you turn the **In Progress** control off, then items that are in the *Active*, *Committed*, or *Resolved* states or in the In Progress category workflow state won't appear in the backlog. To learn more about category workflow states, see [How to use workflow states and state categories](../work-items/workflow-and-state-categories.md). - - -::: moniker range=">= azure-devops-2019" -For details on using each of these controls, see [Configure your backlog view](configure-your-backlog-view.md). -::: moniker-end - -:::row::: - :::column span=""::: - **Icon or Link** - :::column-end::: - :::column span=""::: - **Control** - :::column-end::: - :::column span="2"::: - **Function** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span=""::: - **Backlog** - :::column-end::: - :::column span=""::: - - :::column-end::: - :::column span="2"::: - [Switch to backlog view](create-your-backlog.md) - :::column-end::: -:::row-end::: -::: moniker range=">= azure-devops-2020" -:::row::: - :::column span=""::: - **Analytics** - :::column-end::: - :::column span=""::: - - :::column-end::: - :::column span="2"::: - [Switch to Analytics in-context reports](../../report/dashboards/overview.md#work-tracking-analytics) - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range="tfs-2018" -:::row::: - :::column span=""::: - **Board** - :::column-end::: - :::column span=""::: - - :::column-end::: - :::column span="2"::: - [Switch to Kanban board](../boards/kanban-quickstart.md) - :::column-end::: -:::row-end::: -:::row::: - :::column span=""::: - **Forecast** - :::column-end::: - :::column span=""::: - - :::column-end::: - :::column span="2"::: - [Turn forecasting Off/On](../sprints/forecast.md) - :::column-end::: -:::row-end::: -:::row::: - :::column span=""::: - **Mapping** - :::column-end::: - :::column span=""::: - - :::column-end::: - :::column span="2"::: - [Turn mapping Off/On](organize-backlog.md) - :::column-end::: -:::row-end::: -:::row::: - :::column span=""::: - **Parents** - :::column-end::: - :::column span=""::: - - :::column-end::: - :::column span="2"::: - [Show/Hide parents](organize-backlog.md) - :::column-end::: -:::row-end::: -:::row::: - :::column span=""::: - **In progress items** - :::column-end::: - :::column span=""::: - - :::column-end::: - :::column span="2"::: - [Show/Hide in progress items](create-your-backlog.md#show-hide-in-progress) - :::column-end::: -:::row-end::: -:::row::: - :::column span=""::: - ![mail icon](../media/icons/mail_icon.png) - :::column-end::: - :::column span=""::: - - :::column-end::: - :::column span="2"::: - Email a copy of your backlog - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019" -:::row::: - :::column span=""::: - :::image type="icon" source="../../media/icons/backlogs.png" border="false"::: - :::column-end::: - :::column span=""::: - Backlog selector - :::column-end::: - :::column span="2"::: - [Switch backlog view](create-your-backlog.md)
![backlogs menu](media/backlogs-menu.png) - > [!NOTE] - > Your backlog levels may differ from the level shown in the previous image based on the process selected or customizations you made to your process. Other common labels are Backlog items (Scrum), Requirements (CMMI), and Issues (Basic). For more information, see [About processes and process templates](../work-items/guidance/choose-process.md). - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2020" -:::row::: - :::column span=""::: - :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: - :::column-end::: - :::column span=""::: - View options - :::column-end::: - :::column span="2"::: - - [Turn Parents on/off](organize-backlog.md) (not available for top-level portfolio backlog) - - [Turn Forecasting on/off](../sprints/forecast.md) (Only available on product backlog) - - [Turn In Progress items on/off](create-your-backlog.md#show-hide-in-progress) - - [Turn Completed child items on/off](create-your-backlog.md#show-hide-completed) - - [Show Mapping](organize-backlog.md) (not available for top-level portfolio backlog) - - [Show Planning](../sprints/assign-work-sprint.md) - ![view options](media/controls/mapping-control-2020.png) - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range="azure-devops-2019" -:::row::: - :::column span=""::: - :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: - :::column-end::: - :::column span=""::: - View options - :::column-end::: - :::column span="2"::: - - [Turn Parents on/off](organize-backlog.md) (not available for top-level portfolio backlog) - - [Turn Forecasting on/off](../sprints/forecast.md) (Only available on product backlog) - - [Turn In Progress items on/off](create-your-backlog.md#show-hide-in-progress) - - [Show Mapping](organize-backlog.md) (not available for top-level portfolio backlog) - - [Show Planning](../sprints/assign-work-sprint.md) - :::image type="icon" source="media/view-options.png" border="false"::: - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019" -:::row::: - :::column span=""::: - ![Filter](../media/icons/filter-icon.png) - :::column-end::: - :::column span=""::: - Filter - :::column-end::: - :::column span="2"::: - [Turn filtering On/Off](filter-backlogs-boards-plans.md) - :::column-end::: -:::row-end::: -:::row::: - :::column span=""::: - :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: - :::column-end::: - :::column span=""::: - Settings - :::column-end::: - :::column span="2"::: - [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) - :::column-end::: -:::row-end::: -:::row::: - :::column span=""::: - ![full screen](../../media/icons/full-screen-icon.png) / ![exit full screen](../../media/icons/exit-full-screen-icon.png) - :::column-end::: - :::column span=""::: - Full screen - :::column-end::: - :::column span="2"::: - Enter or exit full screen mode - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range="tfs-2018" -:::row::: - :::column span=""::: - ![Filter](../media/icons/filter-icon.png) - :::column-end::: - :::column span=""::: - Filter - :::column-end::: - :::column span="2"::: - [Turn filtering On/Off](filter-backlogs-boards-plans.md) - :::column-end::: -:::row-end::: -:::row::: - :::column span=""::: - ![Settings icon](../media/icons/team-settings-gear-icon.png) - :::column-end::: - :::column span=""::: - Settings - :::column-end::: - :::column span="2"::: - [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) - :::column-end::: -:::row-end::: -:::row::: - :::column span=""::: - ![full screen icon](../media/icons/fullscreen_icon.png) / ![exit full screen icon](../media/icons/exitfullscreen_icon.png) - :::column-end::: - :::column span=""::: - Full screen mode - :::column-end::: - :::column span="2"::: - Enter or exit full screen mode - :::column-end::: -:::row-end::: -::: moniker-end -:::row::: - :::column span=""::: - ![expand icon](../media/icons/expand_icon.png) / ![collapse icon](../media/icons/collapse_icon.png) - :::column-end::: - :::column span=""::: - Expand/Collapse - :::column-end::: - :::column span="2"::: - Expand or collapse one level of the tree hierarchy - :::column-end::: -:::row-end::: -::: moniker range=">= azure-devops-2019" -:::row::: - :::column span=""::: - ![actions](../../media/icons/actions-icon.png) - :::column-end::: - :::column span=""::: - More commands - :::column-end::: - :::column span="2"::: - - [Set column options](set-column-options.md) - - [Create Query](../queries/organize-queries.md) - - [Email](../work-items/email-work-items.md) - :::column-end::: -:::row-end::: -::: moniker-end ---- - - -> [!NOTE] -> Even if you have show parents turned on, the **Create Query** and **Email** ![mail icon](../media/icons/mail_icon.png) controls only list items at the currently selected level. - - -## Related articles - -- [Backlogs, portfolios, and Agile project management](backlogs-overview.md) -- [Workflow states and state categories](../work-items/workflow-and-state-categories.md) diff --git a/docs/boards/backlogs/remove-delete-work-items.md b/docs/boards/backlogs/remove-delete-work-items.md index 0f9fc5b9583..5a1cfb4f365 100644 --- a/docs/boards/backlogs/remove-delete-work-items.md +++ b/docs/boards/backlogs/remove-delete-work-items.md @@ -2,56 +2,57 @@ title: Remove, delete, and restore work items in Azure Boards titleSuffix: Azure Boards description: Learn how to remove, delete, or restore work items in Azure Boards to manage backlogs and boards more efficiently. -ms.custom: "boards-backlogs, seodec18, contperf-fy21q2, linked-from-support" +ms.custom: boards-backlogs, linked-from-support ms.service: azure-devops-boards -ms.assetid: 306929CA-DB58-45E3-AD45-B774901789D3 +ms.assetid: 306929CA-DB58-45E3-AD45-B774901789D3 ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 06/01/2022 +ms.date: 10/14/2024 +#customer intent: As a team member or administrator, I want to understand how to remove or restore work items in Azure Boards to manage them. --- # Remove, delete, or restore work items in Azure Boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Work items can live forever in your work tracking data store. You never have to delete them. However, you might want to set up a work item management process for one of the following actions: +Work items can live forever in your work tracking data store. You never have to delete them. However, you might want to set up a work item management process for one of the following actions: -- **Change state**: Remove work items from appearing on backlogs and boards by changing the work item **State** to *Remove* or *Cut*. The state available to you is based on the workflow assigned to the work item type. -- **Delete**: Remove work items from backlogs, boards, and queries. Deleted work items are moved to a **Recycle Bin**. -- **Restore**: Recover deleted work items by restoring them from the **Recycle Bin**. -- **Destroy**: Permanently delete work items, which deletes all data from the work tracking data store. - -> [!NOTE] -> The ability to archive work items or projects isn't a supported feature at this time. - -::: moniker range=">= azure-devops-2019" -To move a work item from one project to another, or to change the work item type, see [Move work items, change work item type](move-change-type.md). -::: moniker-end +| Action | Description | +|:-------|:------------| +| [Change state](#remove-work-items) | Remove work items from appearing on backlogs and boards by changing the work item **State** to *Remove* or *Cut*. The state available to you is based on the workflow assigned to the work item type. | +| [Delete](#delete-work-items) | Remove work items from backlogs, boards, and queries. Deleted work items are moved to a **Recycle Bin**. | +| [Restore](#restore-or-destroy-work-items) | Recover deleted work items by restoring them from the **Recycle Bin**. | +| [Destroy](#restore-or-destroy-work-items) | Permanently delete work items, including all data from the work tracking data store. | > [!NOTE] -> For information about the Azure Artifacts Recycle Bin, see [Delete and recover packages](../../artifacts/how-to/delete-and-recover-packages.md). +> - You can't archive work items or projects at this time. +> - For information about the Azure Artifacts Recycle Bin, see [Delete and recover packages](../../artifacts/how-to/delete-and-recover-packages.md). -## Prerequisites +To move a work item from one project to another, or to change the work item type, see [Move work items and change work item type](move-change-type.md). -In general, members of the **Contributors** group can remove, delete, and restore work items. To permanently delete work items, you must be a member of the **Project Administrators** group, or be granted the required permission. Users with **Stakeholder** access can view the contents of the **Recycle Bin**, but can't restore or permanently delete items in the bin regardless of the permissions they're granted. +## Prerequisites + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To remove, delete, and restore work items: Member of the **Contributors** group.
- To permanently delete work items: Member of the **Project Administrators** group or granted the required permission.
- Users with **Stakeholder** access can view the contents of the **Recycle Bin**, but can't restore or permanently delete items in the bin regardless of the permissions they're granted.| :::row::: :::column span="1"::: **Task** :::column-end::: :::column span="2"::: - **Required permission(s)** + **Required permissions** :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - [Change state to **Remove** or **Cut**](#remove) + [Change state to **Remove** or **Cut**](#remove) :::column-end::: :::column span="2"::: - - Have the **Area Path** permission set to **Allow**: **Edit work items in this node** + - **Area Path** permission set to **Allow**: **Edit work items in this node** - By default, members of the **Contributors** group have this permission. :::column-end::: :::row-end::: @@ -61,228 +62,150 @@ In general, members of the **Contributors** group can remove, delete, and restor [Restore work items](#restore) :::column-end::: :::column span="2"::: - - Have the project-level permission set to **Allow**: **Delete and restore work items** - - Have **Basic** access or higher. + - Project-level permission set to **Allow**: **Delete and restore work items** + - At least [**Basic** access](../../organizations/security/access-levels.md). - By default, members of the **Contributors** group have this permission. :::column-end::: :::row-end::: -::: moniker range="tfs-2018" -:::row::: - :::column span="1"::: - [Permanently delete or destroy work items from the command line](#witadmin-cli) - :::column-end::: - :::column span="2"::: - Be a member of the **Project Administrators** group. - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019" :::row::: :::column span="1"::: [Permanently delete or destroy work items](#restore-or-destroy-work-items) :::column-end::: :::column span="2"::: - - Have the project-level permission set to **Allow**: **Permanently delete work items** + - Project-level permission set to **Allow**: **Permanently delete work items** - By default, members of the **Project Administrators** group have this permission. :::column-end::: :::row-end::: -::: moniker-end -::: moniker range=">= azure-devops" :::row::: :::column span="1"::: [Delete or destroy work items from the command line](#az-boards-cli) :::column-end::: :::column span="2"::: - - Have the project-level permission set to **Allow**: **Permanently delete work items** + - Project-level permission set to **Allow**: **Permanently delete work items** - By default, members of the **Project Administrators** group have this permission. :::column-end::: :::row-end::: -::: moniker-end --- - For a simplified view of permissions assigned to built-in groups, see [Permissions and access](../get-started/permissions-access-boards.md). -::: moniker range="azure-devops" +::: moniker range="azure-devops" > [!NOTE] > Users with **Stakeholder** access for a public project have full access to all work tracking features just like users with **Basic** access. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). ::: moniker-end - -## Remove or delete multiple work items -You can act on individual work items or bulk modify several work items. +## Remove or delete multiple work items + +You can act on individual work items or bulk modify several work items. -From the web portal, you can multi-select several work items from a backlog or query results page. You can also do a bulk update using the associated feature. To delete or restore several work items at the same time, see [Bulk modify work items](bulk-modify-work-items.md). +From the web portal, you can multi-select several work items from a backlog or query results page. You can also do a bulk update using the associated feature. To delete or restore several work items at the same time, see [Modify work items in bulk](bulk-modify-work-items.md). +You can also delete or destroy work items in batch with a REST API. For more information, see [Work Items - Delete](/rest/api/azure/devops/wit/work-items/delete?view=azure-devops-rest-6.0&tabs=HTTP&viewFallbackFrom=azure-devops-rest-7.0&preserve-view=true). + +[!INCLUDE [feature-added-2022-1](../../includes/feature-added-2022-1.md)] ### Remove work items -By changing the **State** of a work item to *Removed*, you effectively remove it from a backlog or board view (product, portfolio, and sprint backlogs, Kanban board, and Taskboards). The *Removed* state corresponds to the **Removed** workflow category state. If you [define custom workflow states](../../organizations/settings/work/customize-process-workflow.md), any state you map to the **Removed** workflow category state act in a similar way. +By changing the **State** of a work item to *Removed*, you effectively remove it from a backlog or board view: product, portfolio, and sprint backlogs, boards, and Taskboards. The *Removed* state corresponds to the **Removed** workflow category state. If you define custom workflow states, any state you map to the **Removed** workflow category state act in a similar way. For more information, see [Customize the workflow](../../organizations/settings/work/customize-process-workflow.md). -> [!div class="mx-imgBorder"] -> ![Screenshot of work item form, Change State to Removed.](media/move-change-delete/remove-state.png) +:::image type="content" source="media/move-change-delete/remove-state.png" alt-text="Screenshot of work item form, Change State to Removed."::: To cause removed items to not show up in queries, you must add a clause that filters on the **State** field. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!NOTE] > The *Removed* state isn't supported with the Basic process. It is only supported with the Agile, Scrum, and CMMI process work item types. The Basic process is available when you add a project to Azure DevOps Services or [Azure DevOps Server 2019 Update 1](https://go.microsoft.com/fwlink/?LinkId=2097609). ::: moniker-end - - - - -### Delete work items - -Deleted work items won't appear in your backlogs, boards, or queries. Deleted items are moved to a **Recycle Bin** from which you can recover them if needed. To delete a test case, test plan, or other test-related work item types, see [Delete test artifacts](delete-test-artifacts.md). -::: moniker range=">= azure-devops-2019" - -You can delete work items in one of the following ways: -- From within the work item form -- From the **Work Items** page :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **More Actions** menu -- From the Kanban board card :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: context menu -- From a backlog or query results page. - - -1. To initiate a delete operation: - - From the work item form, open the work item, choose :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **Actions**, and select **Delete**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of work item form, Actions menu, choose Delete.](media/move-change-delete/delete-work-item.png) - - To delete several work items, [multi-select them from a backlog or a query results list](bulk-modify-work-items.md), choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: context menu, and then select **Delete**. + - > [!div class="mx-imgBorder"] - > ![Screenshot of backlog multi-select Actions menu, choose Delete.](media/move-change-delete/multi-delete.png) +### Delete work items - To delete a work item from your Kanban or taskboard, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: context menu for the card and select **Delete**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Kanban board card context menu, choose Delete.](media/move-change-delete/delete-work-items-from-kanban-board.png) - > -1. Confirm you want to actually delete the item(s). +Deleted work items don't appear in your backlogs, boards, or queries. When you delete an item, it goes to the **Recycle Bin**. You can restore it from there if you change your mind. To delete a test case, test plan, or other test-related work item types, see [Delete test artifacts](delete-test-artifacts.md). +::: moniker range="<=azure-devops" - > [!div class="mx-imgBorder"] - > ![Confirm delete dialog.](media/move-change-delete/delete-work-items-dialog.png) +You can delete work items in one of the following ways: +- The work item form +- The **Work Items** page :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **More Actions** menu +- The board card :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: context menu +- A backlog or query results page +- [REST API](/rest/api/azure/devops/wit/work-items/delete-work-items?view=azure-devops-rest-7.1&preserve-view=true&tabs=HTTP) -::: moniker-end - - -::: moniker range="tfs-2018" - -1. You can delete a work item from within the work item form, or by multi-selecting work items from a backlog or query results page. +1. Initiate your delete operation: + - From the work item form, open the work item, choose :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **Actions**, and select **Delete**. - To delete a single work item, open the work item, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **Actions**, and select **Delete**. + :::image type="content" source="media/move-change-delete/delete-work-item.png" alt-text="Screenshot of work item form, Actions menu, choose Delete."::: - > [!div class="mx-imgBorder"] - > ![Screenshot of work item form, Actions menu, Delete option, TFS 2018 version.](media/move-change-delete/delete-work-item.png) + - To delete several work items, [multi-select them from a backlog or a query results list](bulk-modify-work-items.md), choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: context menu, and then select **Delete**. - To delete several work items, [multi-select them from a backlog or a query results list](bulk-modify-work-items.md). Then, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon and select Delete. + :::image type="content" source="media/move-change-delete/multi-delete.png" alt-text="Screenshot of backlog multi-select Actions menu, choose Delete."::: - > [!div class="mx-imgBorder"] - > ![Screenshot of List of work items, actions menu, Delete, TFS 2018 version.](media/move-change-delete/multi-delete.png) + - To delete a work item from your board or Taskboard, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: context menu for the card and select **Delete**. - You can also delete work items from your Kanban or taskboard. - - ![Screenshot of Kanban board, Delete work item, TFS 2018 version.](media/move-change-delete/delete-work-items-from-kanban-board.png) + :::image type="content" source="media/move-change-delete/delete-work-items-from-kanban-board.png" alt-text="Screenshot of board card context menu, choose Delete."::: - Or, you can drag them to the :::image type="icon" source="media/recycle-bin-icon.png" border="false"::: **Recycle bin**. You can only access the **Recycle bin** from the **Work** hub. +1. Confirm you want to delete the items. -2. Confirm you want to actually delete the item(s). + :::image type="content" source="media/move-change-delete/delete-work-items-dialog.png" alt-text="Screenshot of the Confirm delete dialog."::: - ![Confirm delete dialog, TFS 2018 version.](media/move-change-delete/delete-work-items-dialog-tfs.png) - - > [!NOTE] - > The Delete work items confirmation dialog for on-premises Azure DevOps may indicate there are auto-delete settings (disabled). There are no settings you can enable or disable. There is only a background process which permanently deletes work items that have been set to delete. ::: moniker-end + + - - - - - -## Restore or destroy work items - -You can't open work items that have been moved to the **Recycle Bin**. Also, you'll only see the **Permanently delete option** if your [Permanently delete work items](../../organizations/security/set-permissions-access-work-tracking.md#move-delete-permissions) project-level permission is set to **Allow**. +## Restore or destroy work items -::: moniker range=">= azure-devops-2019" +You can't open work items from the **Recycle Bin**. You only see the **Permanently delete option** if your [Permanently delete work items](../../organizations/security/set-permissions-access-work-tracking.md#move-delete-permissions) project-level permission is set to **Allow**. -You restore deleted work items or permanently delete them from the web portal **Recycle Bin**. +::: moniker range="<=azure-devops" -1. Choose **Boards>Work Items** and then choose the **Recycle Bin**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Boards, Work Items page, Open Recycle bin.](media/move-change-delete/open-recycle-bin-new-nav.png) +Restore deleted work items or permanently delete them from the web portal **Recycle Bin**. - If you don't see the **Recycle Bin** option, choose **More commands …** and choose it from the menu of options. +1. Select **Boards** > **Work Items** > **Recycle Bin**. -1. A new browser tab opens with the query that lists work items added to the **Recycle Bin**. + :::image type="content" source="media/move-change-delete/open-recycle-bin-new-nav.png" alt-text="Screenshot of Boards, Work Items page, Open Recycle bin."::: -1. Select the items you want to restore and then choose **Restore**. + If you don't see the **Recycle Bin** option, choose **More commands …** and select from the menu of options. - ![Screenshot of Restore selected items.](media/move-change-delete/restore-from-recycle-bin.png) + A new browser tab opens with the query that lists work items added to the **Recycle Bin**. - Optionally, you can choose to permanently delete the items. +1. Select the items you want to restore and then choose **Restore**. -1. Confirm your selection. - -::: moniker-end - - - -::: moniker range="tfs-2018" - -You restore deleted work items from the web portal **Recycle Bin**. - -1. Choose **Work>Backlogs** or **Work>Queries** and then choose the **Recycle Bin**. - - ![Screenshot to Open Recycle bin, TFS 2018 version.](media/move-change-delete/open-recycle-bin.png) - - A new browser tab opens with the query that lists work items added to the **Recycle Bin**. - -1. Select the items you want to restore and then choose **Restore**. - - ![[Screenshot of Restore selected items, TFS 2018 version.](media/move-change-delete/restore-from-recycle-bin.png) + :::image type="content" source="media/move-change-delete/restore-from-recycle-bin.png" alt-text="Screenshot of Restore selected items."::: Optionally, you can choose to permanently delete the items. -2. Confirm your selection. +1. Confirm your selection. ::: moniker-end -> [!NOTE] +> [!NOTE] +> Deleted test artifacts don't appear in the **Recycle Bin** and can't be restored. When you delete a test artifact, all of its associated child items, such as child test suites, test points across all configurations, testers, test results history, and other associated history also get deleted. The underlying test case work item doesn't get deleted. -> Deleted test artifacts won't appear in the **Recycle Bin** and can't be restored. Deletion of test artifacts deletes the selected test artifact and all of its associated child items, such as child test suites, test points across all configurations, testers (the underlying test case work item doesn't get deleted), test results history, and other associated history. + - +::: moniker range="azure-devops" -::: moniker range="azure-devops" - ## Delete or destroy work items from the command line You can delete or destroy a work item with the [az boards work-item delete](/cli/azure/boards/work-item#az-boards-work-item-delete) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). -> [!NOTE] -> You can restore work items you **delete**, but you can't restore work items you choose to **destroy**. +> [!NOTE] +> You can restore *deleted* work items, but you can't restore *destroyed* work items. -```azurecli +```azurecli az boards work-item delete --id [--destroy] [--org] [--project] [--yes] -``` - -### Parameters +``` - **id**: Required. The ID of the work item. - **destroy**: Optional. Permanently delete this work item. @@ -290,8 +213,6 @@ az boards work-item delete --id - **project**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. - **yes**: Optional. Don't prompt for confirmation. -#### Example - The following command permanently deletes the bug with the ID 864 and doesn't prompt you for confirmation. ```azurecli @@ -300,82 +221,43 @@ az boards work-item delete --id 864 --destroy --yes ::: moniker-end +## Delete and restore processes -::: moniker range="tfs-2018" - - - -### Destroy work items from the command line - -Use the `witadmin destroywi` command to permanently remove work items from the data store. A permanent delete means all information in the work tracking data store is deleted and can't be restored nor reactivated. - -> [!NOTE] -> Deleting work items from the `witadmin` command line is deprecated for TFS 2018.2 and later versions, and not supported for Azure Boards cloud service. - -Open a Command Prompt window where the latest version of Visual Studio is installed and change the directory to where the `witadmin.exe` tool has been installed. - -For example, you would change to the following directory for TFS 2018. (For other versions, see [Remove work items permanently (witadmin destroywi)](/previous-versions/azure/devops/reference/witadmin/remove-work-items-permanently)). - -`%programfiles(x86)%\Microsoft Visual Studio\2018\Professional\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer` - -On a 32-bit edition of Windows, replace %programfiles(x86)% with %programfiles%. - -The `witadmin` command-line tool installs with any version of Visual Studio or Team Explorer. You can access this tool by installing the [free version of Visual Studio Community](https://visualstudio.microsoft.com/downloads/). - -- To delete several work items, enter the server name and directory path to the collection. For example: - - ``` CLI - witadmin destroywi /collection:http://TFSServerName:8080/tfs/DefaultCollection /id:12,15,23 - ``` -- To delete a single work item, enter the ID as shown: - - ``` CLI - witadmin destroywi /collection:http://TFSServerName:8080/tfs/DefaultCollection /id:2003 - ``` -::: moniker-end - - -## Delete and restore processes - -**When you delete a work item, the following actions occur:** +**When you delete a work item, Azure DevOps does the following actions:** - Generates a new revision of the work item - Updates the **Changed By/Changed Date** fields to support traceability - Preserves the work item completely, including all field assignments, attachments, tags, and links -- Causes the work item to become non-queryable and, as such, won't appear in any work tracking experience, query result, or report +- Causes the work item to become nonqueryable and, as such, doesn't appear in any work tracking experience, query result, or report - Updates charts correctly. The CFD, velocity, burndown, and lightweight charts are updated to remove deleted work items - Removes work tracking extensions -- Preserves trend data except for the latest value -- Removes the work item from the data warehouse/cube similar to as if it was permanently removed. - - -**When you restore a work item, the following actions occur:** - -- Causes a new revision of the work item to be made -- Updates the **Changed By/Changed Date** fields to support traceability -- Becomes queryable -- All fields remain unchanged -- History contains two new revisions, one for deletion, and one for restore -- Reattaches work tracking extensions -- Updates charts correctly. The CFD, velocity, burndown, and lightweight charts are updated to include the restored work items -- Restores trend data -- Adds the work item back to the data warehouse/cube -- Sets the area or iteration path fields to the root node if the previous area path or iteration paths were deleted. - +- Preserves trend data except for the latest value +- Removes the work item from the data warehouse/cube similar to as if it was permanently removed + +**When you restore a work item, Azure DevOps does the following actions:** + +- Causes a new revision of the work item to be made +- Updates the **Changed By/Changed Date** fields to support traceability +- Becomes queryable +- All fields remain unchanged +- History contains two new revisions, one for deletion, and one for restore +- Reattaches work tracking extensions +- Updates charts correctly. The CFD, velocity, burndown, and lightweight charts are updated to include the restored work items +- Restores trend data +- Adds the work item back to the data warehouse/cube +- Sets the area or iteration path fields to the root node if the previous area path or iteration paths were deleted ## Use a REST API to delete, restore, and destroy work items -To programmatically delete, restore, and destroy work items, see one of the following REST API resources: +To programmatically delete, restore, and destroy work items, see one of the following REST API resources: - [Recycle bin REST API Reference](/rest/api/azure/devops/wit/recyclebin) - [Work Items - Delete REST API Reference](/rest/api/azure/devops/wit/work-items/delete) -## Related articles - -- [Best tool to add, update, and link work items](../work-items/best-tool-add-update-link-work-items.md) -- [View and add work items using the Work Items page](../work-items/view-add-work-items.md) -- [Delete test artifacts](delete-test-artifacts.md) -- [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md) -- [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) -- [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md) +## Related articles +- [View and add work items using the Work Items page](../work-items/view-add-work-items.md) +- [Delete test artifacts](delete-test-artifacts.md) +- [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md) +- [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) +- [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md) diff --git a/docs/boards/backlogs/resolve-backlog-reorder-issues.md b/docs/boards/backlogs/resolve-backlog-reorder-issues.md index 08ad2e98eaa..48979430a2d 100644 --- a/docs/boards/backlogs/resolve-backlog-reorder-issues.md +++ b/docs/boards/backlogs/resolve-backlog-reorder-issues.md @@ -1,157 +1,140 @@ --- -title: Resolve nest, display, and reorder issues for work items +title: Resolve nest, display, and reorder issues for work items titleSuffix: Azure Boards -description: Learn how to address and fix error messages caused by nesting and reordering issues that occur in Azure Boards. -ms.custom: "boards-backlogs, seodec18" +description: Learn how to fix reordering and nesting issues for work items in Azure Boards. Resolve error messages and maintain a natural hierarchy for your backlog. +ms.custom: boards-backlogs ms.service: azure-devops-boards ms.assetid: BDEAA5D4-83A3-49FC-BEEB-EE685E92B68B ms.topic: troubleshooting ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 07/06/2023 +ms.date: 10/14/2024 +#customer intent: as a team member or lead, I want to address warnings or errors that occur in Azure Boards regarding reordering or nesting work items. --- -# Resolve nest, display, and reorder issues for work items +# Troubleshoot reordering and nesting issues [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -When you add parent-child work item links that aren't in the natural hierarchy, reordering is disabled. Items may not display and the system may disable the drag-and-drop reorder feature. - -Use this article to address error messages that are similar to the following message: -- "You can't reorder work items and some work items may not be shown." -- "Work item can't be reordered because its parent is on the same category." -- "Items added to the backlog may disappear on a refresh because your team project marks them as "in progress." Those items appear when you change the "In progress" filter to Show." +When you reorder, nest, and display work items, Azure Boards expects a [natural hierarchy](#natural-hierarchy-for-work-item-types). The natural hierarchy breaks when you create same-category or same-type links between work items. For example, parent to child links that are bug to bug or user story to user story or *requirements* category to *task* category. Use this article to address error messages when you add links that aren't in the natural hierarchy. -> [!NOTE] -> For other issues that may occur with multi-team ownership, see [Configure a hierarchy of teams, Exercise select features with shared area paths](../plans/configure-hierarchical-teams.md#op-issues). +## Prerequisites -## Natural hierarchy for work item types +[!INCLUDE [temp](../includes/prerequisites.md)] -The following image shows the natural hierarchy for the Agile, Scrum, and Capability Maturity Model Integration (CMMI) processes. +## You cannot reorder work items and some work items might not be shown -:::image type="content" source="media/resolve/create-hierarchy-with-different-wits.png" alt-text="Conceptual image of natural hierarchy for the Agile, Scrum, and CMMI processes."::: +You might see an error similar to one of the following messages: -The natural hierarchy breaks when you create same-category or same-type links between work items. For example, parent-child links that are bug-bug or user story-user story or *requirements* category-*task* category. +> - You cannot reorder work items and some work items might not be shown +> - No work item IDs are listed -## Recommended configuration +To address this error, do the following steps: -- Maintain a flat list, rather than nesting requirements, bugs, and tasks. Only create parent-child links one level deep between items that belong to a different category. The category a work item belongs to gets determined by your process backlog levels and your team's selected bug behavior. -- Use the *feature* work item type to group user stories (Agile), issues (Basic), product backlog items (Scrum), or requirements (CMMI). You can [quickly map product backlog items to features](organize-backlog.md), which creates parent-child links in the background. -- Don't create a hierarchy of backlog items, tasks, and bugs. Don't create same-category hierarchies, like parent-child links among work items of the same type, such as story-story, bug-bug, task-task, or issue-issue. The backlog, board, and sprints experiences don't support reordering for same-category hierarchies, as it introduces confusion by ordering a work item that doesn't belong on that level. +1. Open your backlog. +1. Review the list of items to identify those items of the same type that are nested. -## Resolve - Cannot reorder work items + - **Example #1:** The following image shows a user story as a child of another user story. -You may see a message like: `You cannot reorder work items and some work items may not be shown`. No work item IDs are listed. + :::image type="content" source="media/resolve/nested-user-stories.png" alt-text="Screenshot showing nested user stories on a backlog."::: -To address this error, do the following steps: + - **Example #2:** The following image shows a bug as a child of a user story. When the backlog displays user stories and bugs at the same level (Requirements category), it results in a nested item that disables the ordering feature. -1. Open your backlog. -2. Review the list of items to determine which items of the same type are nested. - Example #1: The following image shows a user story as a child of another user story. + :::image type="content" source="media/resolve/nested-user-story-bug.png" alt-text="Screenshot of nested user story and bug."::: - :::image type="content" source="media/resolve/nested-user-stories.png" alt-text="Screenshot of nested user stories."::: - - Example #2: The following image shows a bug as a child of a user story. Because the team configured their backlog to display user stories and bugs at the same level (Requirements category), this configuration results in a nested item that disables the ordering feature. +1. Remove any parent-child links that exist among nested items of the same work item type or category, or consider changing the link type to *Related*. +1. Refresh your backlog. - :::image type="content" source="media/resolve/nested-user-story-bug.png" alt-text="Screenshot of nested user story and bug."::: - -3. Remove all parent-child links that exist among nested items of the same work item type or same category. Or, change the link to 'Related.' -4. Refresh your backlog. +These steps should resolve the issue, and the error message no longer displays. -The message no longer displays. +## Work item can't be reordered because its parent is on the same category -## Resolve - Cannot reorder work items, change link type or category +You might see an error similar to one of the following messages: -You may see a message like: `You cannot reorder work items and some work items may not be shown. See work item(s) 7 to either remove the parent to child link or change the link type to 'Related'." or "Work item 3 can't be reordered because its parent is on the same category"`. +> - You cannot reorder work items and some work items might not be shown. See work item(s) 7 to either remove the parent to child link or change the link type to Related. +> - Work item 3 can't be reordered because its parent is on the same category. -To address this error, do the following steps: +To address this error, do the following steps: 1. Open the work item listed in the error message. -2. Look for a parent or child link. Make sure this link goes to a work item within the same category as the work item you opened. This link goes to another work item that appears on the same backlog level as the work item you opened. Depending on your team's bug behavior setting, bugs may appear with requirements or tasks. -3. Remove the problem parent-child link. If you would like to keep these items associated, use 'Related' link type instead. +1. Look for a parent or child link. Make sure this link goes to a work item in the same category as the work item you opened. Look for a link that goes to another work item that appears on the same backlog level as the work item you opened. Depending on your team's bug behavior setting, bugs might appear with requirements or tasks. +1. Remove the problem parent-child link. If you would like to keep these items associated, use *Related* link type instead. The message no longer displays. -## Resolve - Work items in progress may disappear on refresh +## Work items in progress might disappear on refresh -You may see a message like: `Items added to the backlog may disappear on a refresh because your team project marks them as "in progress". Those items appear when you change the "In progress" filter to Show.`. This message indicates that the **In Progress** filter for the backlog is turned off. +You might see an error similar to the following message: -When you refresh your browser, the backlog displays those work items based on your selected filters. To reset the filters, complete the following steps. +> Items added to the backlog might disappear on a refresh because your team project marks them as "in progress". Those items appear when you change the "In progress" filter to Show. -::: moniker range=">= azure-devops-2019" -1. Open your backlog. -1. From the **View options** selector, choose to show or hide **In Progress items**. +This message indicates that the **In Progress** filter for the backlog is turned off. -- If you turn the **In Progress** control off, then items that are in the *Active*, *Committed*, or *Resolved* states or states that map to the [**In Progress** category state](../work-items/workflow-and-state-categories.md) don't appear in the backlog. - -::: moniker-end +When you refresh your browser, the work items display based on your selected filters. To reset the filters, do the following steps. ::: moniker range=">= azure-devops-2020" - :::image type="content" source="media/create-backlog/in-progress-control-2020.png" alt-text="Screenshot of View options selector, In progress control, version 2020 and later."::: - -::: moniker-end -::: moniker range="azure-devops-2019" - :::image type="content" source="media/create-backlog/in-progress-control-2019.png" alt-text="Screenshot of View options selector, In progress control, version 2019."::: -::: moniker-end -::: moniker range="tfs-2018" 1. Open your backlog. -2. Show or hide **In progress items** on your backlog. - - If you turn the **In Progress items** control off, then items that are in the *Active*, *Committed*, or *Resolved* states or states that map to the [**In Progress** category state](../work-items/workflow-and-state-categories.md) don't appear in the backlog. +1. From the **View options** selector, choose to show or hide **In Progress items**. + + :::image type="content" source="media/create-backlog/in-progress-control-2020.png" alt-text="Screenshot of View options selector, In progress control, version 2020 and later."::: ::: moniker-end - - Hide **In Progress items** when you want to forecast work. For more information, see [Forecast your product backlog](../sprints/forecast.md). +If you turn the **In Progress** control off, then items that are in the *Active*, *Committed*, or *Resolved* states or states that map to the [**In Progress** category state](../work-items/workflow-and-state-categories.md) don't appear. -## Track bugs as requirements or tasks +Hide **In Progress items** when you want to forecast work. For more information, see [Forecast your product backlog](../sprints/forecast.md). -[Each team can choose how to track bugs](../../organizations/settings/show-bugs-on-backlog.md), like requirements or tasks, or neither. +> [!NOTE] +> +> - For more information, see [Configure your backlog view](configure-your-backlog-view.md) and [Add custom work item types](../../organizations/settings/work/add-custom-wit.md). +> - For issues that might occur with multi-team ownership, see [Exercising select features with shared area paths](../plans/configure-hierarchical-teams.md#op-issues). +> - To reorder work items on your backlog, have at least [**Basic** access](../../organizations/security/access-levels.md). If you have Stakeholder access, you can't reorder work items. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -If you track bugs as *requirements*, only nest bugs under the *Feature* level. +## Natural hierarchy for work item types -:::image type="content" source="media/resolve/bugs-as-requirements.png" alt-text="Screenshot of linked bugs like requirements."::: +The following image shows the natural hierarchy for the Agile, Scrum, and Capability Maturity Model Integration (CMMI) processes. -If you track bugs as *tasks*, only nest bugs under the *Requirement* level. +:::image type="content" source="media/resolve/create-hierarchy-with-different-wits.png" alt-text="Diagram of natural hierarchy for the Agile, Scrum, and CMMI processes."::: -:::image type="content" source="media/resolve/bugs-as-tasks.png" alt-text="Screenshot of linked bugs like tasks."::: +## Best practices -## Display nested items on backlogs and boards +**Do:** -Sprint backlogs and Taskboards only show the last node in a same-category hierarchy, called the leaf node. +- Maintain a flat list, rather than nesting requirements, bugs, and tasks. +- Only create parent-child links one level deep between items that belong to a different category. The category a work item belongs to gets determined by your process levels and your team's selected bug behavior. +- Use the *feature* work item type to group user stories (Agile), issues (Basic), work items (Scrum), or requirements (CMMI). You can map work items to features. This mapping creates parent-child links in the background. For more information, see [Organize your backlog](organize-backlog.md). -::: moniker range="tfs-2018" -> [!NOTE] -> - For TFS 2018 and earlier versions, the Kanban board only shows the last node with nested items of a same-category hierarchy. -> - For TFS 2018.2 and later versions, Kanban boards display all work items of nested same-category work items. -::: moniker-end +**Don't:** -::: moniker range="tfs-2018" +- Create a hierarchy of work items, tasks, and bugs. +- Establish same-category hierarchies, such as parent-child links among work items of the same type. For example, create story-story, bug-bug, task-task, or issue-issue links. The backlog, board, and sprints experiences don't support reordering for same-category hierarchies, because that approach introduces confusion by ordering a work item that doesn't belong at that level. -### Product backlog and Kanban boards +## Track bugs as requirements or tasks -If you link items within a same-category hierarchy that is four levels deep, for example, only the items at the fourth level appear on the Kanban board, sprint backlog, and Taskboard. +Each team has the flexibility to choose to track bugs as requirements, tasks, or neither. See the following guidelines: -As shown in the following images, the third user story, *Interim save on long form*, has a child bug, *Save takes too long*. The child bug, *Save takes too long*, appears on the Kanban board, but not the parent user story. +- **If you track bugs as *requirements*:** Nest them only under the *Feature* level. -**All bugs and requirements appear on the backlog** + :::image type="content" source="media/resolve/bugs-as-requirements.png" alt-text="Diagram shows linked bugs like requirements."::: -:::image type="content" source="media/resolve/bugs-appear-on-backlog.png" alt-text="Screenshot showing child bug on backlog."::: +- **If you track bugs as *tasks*:** Nest them only under the *Requirement* level. -**Only leaf nodes appear on the Kanban board** + :::image type="content" source="media/resolve/bugs-as-tasks.png" alt-text="Diagram shows linked bugs like tasks, underneath the Requirement level."::: -:::image type="content" source="media/resolve/bugs-appear-on-board.png" alt-text="Screenshot showing leaf node bug on Kanban board."::: +For more information, see [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). -::: moniker-end +## Display nested items on backlogs and boards + +Sprint backlogs and Taskboards exclusively display the last node in a same-category hierarchy, which is referred to as the leaf node. ### Sprint backlogs and Taskboards -When bugs appear in the backlog with tasks, linking tasks and bugs to their parent requirements groups them correctly on the sprint backlog and Taskboard. -But, if you create parent-child links between a requirement and a bug, and the bug and a task, as shown here, the task appears on the sprint backlog and Taskboard, but not the bug. +When tasks and bugs link to their parent requirements, they group them correctly on the sprint backlog and Taskboard. When you establish parent-child links between a requirement and a bug, and between the bug and a task, as demonstrated here, the task appears on the sprint backlog and Taskboard, while the bug doesn't. **Hierarchy of items assigned to a sprint backlog** @@ -164,12 +147,14 @@ But, if you create parent-child links between a requirement and a bug, and the b **Only leaf nodes appear on Taskboards** :::image type="content" source="media/resolve/bugs-appear-on-taskboard.png" alt-text="Screenshot of Sprint board with leaf node task."::: - -## Q: Is there a workaround to display intermediate nodes within a hierarchy? -A: No, not at this time. You can always check the entire list of items assigned to a sprint when you select **Create query**. + +## Frequently asked questions (FAQs) + +### Q: Is there a workaround to display intermediate nodes within a hierarchy? + +A: No, not at this time. You can always check the entire list of items assigned to a sprint when you select **Create query**. ## Related articles - [Set up your backlogs and boards](set-up-your-backlog.md) -- [About boards and Kanban, Limitations of multi-team Kanban board views](../boards/kanban-overview.md#limits-multi-team) - +- [Learn about Kanban boards](../boards/kanban-overview.md) diff --git a/docs/boards/backlogs/set-column-options.md b/docs/boards/backlogs/set-column-options.md index ab9f1dfed67..67c90501371 100644 --- a/docs/boards/backlogs/set-column-options.md +++ b/docs/boards/backlogs/set-column-options.md @@ -22,7 +22,6 @@ Each column corresponds to a work item field. You can add and remove columns wit Specifically, you can do the following actions from the following list views: - :::row::: :::column span="2"::: **Action** @@ -111,98 +110,62 @@ Specifically, you can do the following actions from the following list views: :::column-end::: :::row-end::: - - > [!TIP] > Unlike a query result, you can't sort a backlog by a column. However, you can use the **Create Query** link on each backlog to create a query that you can sort on any field column you choose from the **Sorting** tab of the Column options dialog. While you may be able to add a field to sort on, not all fields are supported. For example, selection of the **Parent**, **History**, **Description**, or other rich-text field results in the display of an error message as you can't sort on these fields. - ::: moniker range="azure-devops" You can add most fields listed in the [Work item field index](../work-items/guidance/work-item-field.md). All fields defined within the project collection or organization are available for selection, even those fields that aren't used for your particular project. You can view the list of fields defined for your collection from [**Organization Settings>Process>Fields**](../work-items/work-item-fields.md#review-fields) ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" You can add most fields listed in the [Work item field index](../work-items/guidance/work-item-field.md). All fields defined within the project collection or organization are available for selection, even those fields that aren't used for your particular project. If your project uses the Inherited process model, you can view the list of fields defined for your collection from [**Organization Settings>Process>Fields**](../work-items/work-item-fields.md#review-fields) ::: moniker-end - -::: moniker range="tfs-2018" -You can add most fields listed in the [Work item field index](../work-items/guidance/work-item-field.md). All fields defined within the project collection or organization are available for selection, even those fields that aren't used for your particular project. -::: moniker-end - - ## About persistence of column options Once you set the column options for a specific view, your settings persist until you change them. The following notes apply to specific views. -::: moniker range=">= azure-devops-2019" - - Column options you set for a backlog apply only to the active team and backlog. Options you set for the product backlog differ from the options you set for a portfolio backlog. - Column options you set for a Sprint backlog persist for all sprints you select until you change them. - Column options you set for a query persist when you save the query. -- Column options you set for one of the supported Work items views persists for a specific view only, such as **Assigned to me**, **Following**, **Mentioned**, and so on. - -::: moniker-end - -::: moniker range="tfs-2018" - -- Column options you set for a backlog apply only to the active team and backlog. Options set for the product backlog differ from those options you set for a portfolio backlog. -- Column options you set for a Sprint backlog persist for all sprints you select until you change them. -- Column options you set for a query persist when you save the query. For Shared queries, your settings can get overwritten when someone else saves different column option settings. -::: moniker-end - +- Column options you set for one of the supported Work items views persists for a specific view only, such as **Assigned to me**, **Following**, **Mentioned**, and so on. ::: moniker range="azure-devops" > [!NOTE] > You can't set column options for other members of your team, nor can you set default column options. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" -> [!NOTE] -> You can't set column options for other members of your team. Also, for projects that use the Inheritance process model, you can't set default column options. For projects that use the On-premises XML process model, you can set the default column options for product, portfolio, and sprint backlogs. To learn how, see [Process configuration XML element reference](../../reference/xml/process-configuration-xml-element.md). -::: moniker-end -::: moniker range="tfs-2018" +::: moniker range=" < azure-devops" > [!NOTE] -> You can't set column options for other members of your team. For projects that use the On-premises XML process model, you can set the default column options for product and portfolio backlogs. To learn how, see [Process configuration XML element reference](../../reference/xml/process-configuration-xml-element.md). +> You can't set column options for other members of your team. Also, for projects that use the Inheritance process model, you can't set default column options. For projects that use the On-premises XML process model, you can set the default column options for product, portfolio, and sprint backlogs. For more informaion, see [Process configuration XML element reference](../../reference/xml/process-configuration-xml-element.md). ::: moniker-end +## Prerequisites + +[!INCLUDE [temp](../includes/prerequisites.md)] + ## Open the Column options dialog Start by opening the **Column Options** dialog. If you don't see the option, choose the … and choose from the options provided. -::: moniker range=">= azure-devops-2019" - > [!div class="mx-imgBorder"] -> ![Open column options](media/columns/open-column-options-menu.png) -::: moniker-end - - - ::: moniker range="tfs-2018" - -![Open column options](media/set-column-open-dialog-s125.png) - -::: moniker-end - +> ![Screenshot shows Open column options.](media/columns/open-column-options-menu.png) ## Add or remove columns - #### [Browser](#tab/browser/) In the Column options dialog, choose **Add a column** to add a field that isn't shown. To change the order of the fields, drag-and-drop the field where you want it within the set of selected fields. And, to remove a field, choose the ![delete icon](../media/icons/delete_icon.png). - -::: moniker range="tfs-2018" -> [!NOTE] -> The following dialog is available from TFS 2018.2 and later versions. -::: moniker-end - -![Column options dialog](media/set-column-options-s125.png) +![Screenshot shows Column options dialog.](media/set-column-options-s125.png) #### [Visual Studio](#tab/visual-studio/) +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. + You can only change column options for queries in Visual Studio. To open, choose **Column Options**. :::image type="content" source="media/columns/open-column-options-visual-studio.png" alt-text="Screenshot of Query Results, Visual Studio, open Column Options."::: @@ -213,13 +176,13 @@ In the Column Options dialog, to add a field, choose the field from Available co To change the field order, choose the field and choose the up or down arrows. -:::image type="content" source="media/columns/column-options-dialog-visual-studio.png" alt-text="Column Options dialog, Visual Studio, Fields tab."::: +:::image type="content" source="media/columns/column-options-dialog-visual-studio.png" alt-text="Screenshot shows Column Options dialog, Visual Studio, Fields tab."::: ### Change the column's sort order To change the fields use to sort the query results, choose the **Sorting** tab. Add or remove a column field same as before. Use the up and down arrows to specify the order of fields to use to sort. Choose the up or down arrows to choose whether it sorts in ascending or descending order. To reverse the sort order for a field, select it and then choose **Sort ascending** or **Sort descending**. -:::image type="content" source="media/columns/column-options-dialog-sorting-visual-studio.png" alt-text="Column Options dialog, Visual Studio, Sorting tab."::: +:::image type="content" source="media/columns/column-options-dialog-sorting-visual-studio.png" alt-text="Screenshot shows Column Options dialog, Visual Studio, Sorting tab."::: * * * @@ -233,24 +196,11 @@ Rollup columns can display progress bars or the sum of numeric fields of child i ## Sort on a column -::: moniker range=">= azure-devops-2019" - You can sort query results and Work items views. From the Column options dialog, choose **Sorting**. Add or remove a column field and drag and drop it into the order you want. Choose the up or down arrows to choose whether it sorts in ascending or descending order. > [!div class="mx-imgBorder"] > ![Column options, Sorting page dialog](media/columns/sort-dialog.png) -::: moniker-end - -::: moniker range="tfs-2018" - -You can sort query results. From the Column options dialog, choose **Sorting**. Add or remove a column field and drag and drop it into the order you want. Choose the up or down arrows to choose whether it sorts in ascending or descending order. - -> [!div class="mx-imgBorder"] -> ![Column options, Sorting page dialog](media/columns/sort-dialog.png) - -::: moniker-end - ## Use keyboard shortcuts to change the column order, column width, or sort options You can change the column order, column size, or sort options by using the following keyboard commands: @@ -262,10 +212,8 @@ You can change the column order, column size, or sort options by using the follo - To reverse the sort order, SHIFT+click on the field - To sort by multiple columns, SHIFT+click on each column in the order you want to sort - For other keyboard shortcuts, enter **?** to display available shortcuts based on the page you're on. - ## Related articles ::: moniker range=">= azure-devops-2020" @@ -278,9 +226,3 @@ For other keyboard shortcuts, enter **?** to display available shortcuts based o - [Customize a sprint Taskboard](../sprints/customize-taskboard.md) ::: moniker-end -::: moniker range="< azure-devops-2020" -- [Interactively filter backlogs, boards, queries, and plans](filter-backlogs-boards-plans.md) -- [Work item field index](../work-items/guidance/work-item-field.md) -- [Create managed queries](../queries/using-queries.md) - -::: moniker-end diff --git a/docs/boards/backlogs/set-up-your-backlog.md b/docs/boards/backlogs/set-up-your-backlog.md index add8bf61d75..d0372f1fda6 100644 --- a/docs/boards/backlogs/set-up-your-backlog.md +++ b/docs/boards/backlogs/set-up-your-backlog.md @@ -16,17 +16,21 @@ ms.date: 04/01/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -In most cases, you can start using your product and portfolio backlogs once your project is created. A default team is created along with associated backlogs and boards. You can start adding work items to your product backlog using the [Backlog](create-your-backlog.md) or [Board](../boards/kanban-quickstart.md). +In most cases, you can start using your product and portfolio backlogs once your project is created. A default team gets created along with associated backlogs and boards. You can start adding work items to your product backlog using the [Backlog](create-your-backlog.md) or [Board](../boards/kanban-quickstart.md). -However, you may need to ensure you've configured your backlogs and boards correctly. Ensure the configuration if you've added a team and want to start using the team backlogs and boards. Changes may be made to a project or team configuration over time. These changes can influence the work items that appear on your backlog and boards. +However, you might need to ensure you've configured your backlogs and boards correctly. Ensure the configuration if you've added a team and want to start using the team backlogs and boards. Changes may be made to a project or team configuration over time. These changes can influence the work items that appear on your backlog and boards. For an overview of the tools associated with your team, see [Manage and configure team tools](../../organizations/settings/manage-teams.md). +## Prerequisites + +[!INCLUDE [temp](../includes/prerequisites.md)] + ## Default backlog and board work items The first thing you need to understand is that your product **Backlog** and **Board** display work items that meet the following criteria: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" - Work item type belongs to the Requirements category. The types differ depending on the process selected for your project: - [Basic](../get-started/plan-track-work.md) : Issue, Backlog name=Issues @@ -40,50 +44,31 @@ The first thing you need to understand is that your product **Backlog** and **Bo [!INCLUDE [temp](../includes/basic-process-note.md)] -::: moniker range="tfs-2018" - -- Work item type belongs to the Requirements category. The types differ depending on the process selected for your project: - - [Agile](../work-items/guidance/agile-process.md): User Story, Backlog name=Stories - - [Scrum](../work-items/guidance/scrum-process.md): Product Backlog Item, Backlog name=Backlog items - - [CMMI](../work-items/guidance/cmmi-process.md): Requirement, Backlog name=Requirements -- Work item Area Path matches one of the selected team's Area Paths -- Work item Iteration Path is under the team's Default Iteration Path -::: moniker-end - You can determine the work item types that belong to your Requirements category. Determine the items by [opening your product Backlog](create-your-backlog.md) and checking the product backlog name. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!div class="mx-imgBorder"] > ![Product backlog level, Backlog items, Stories, or Requirements](../sprints/media/assign-items-sprint/select-product-backlog-agile.png) ::: moniker-end -::: moniker range="tfs-2018" -As shown in the following image, (1) choose the team, (2) **Work**, (3) **Backlogs**, and then the product backlog. - -> [!div class="mx-imgBorder"] -> ![Product backlog level, Backlog items, Stories, or Requirements](media/setup-backlog/backlog-levels-prev-versions.png) - -::: moniker-end - Look up your team's Area Path(s) and Iteration Paths. For more information, see [Define area paths and assign to a team](../../organizations/settings/set-area-paths.md) and -[Define sprint paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md#activate). +[Define sprint paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md#list-team-iterations). - + ## Default sprint backlog and Taskboard work items Your sprint backlog and Taskboard apply the filters associated with your team's default backlog and board work items along with the Iteration Path you select. -You can only select Iteration Paths that have been [preselected by your team](../../organizations/settings/set-iteration-paths-sprints.md#activate). +You can only select Iteration Paths that have been [preselected by your team](../../organizations/settings/set-iteration-paths-sprints.md#list-team-iterations). Your sprint backlog displays only those work items assigned to the selected sprint. Child tasks assigned to other sprints aren't displayed. - ## Review checklist for work items, backlogs, and boards -If you don't see the work items you expect on your [product Backlog](create-your-backlog.md) or [Kanban board](../boards/kanban-quickstart.md), complete the following checks: +If you don't see the work items you expect on your [product Backlog](create-your-backlog.md) or [board](../boards/kanban-quickstart.md), complete the following checks: 1. Make sure you've selected the team backlog or board of interest. To learn how, see [Use breadcrumbs and selectors to go to and open artifacts](../../project/navigation/use-breadcrumbs-selectors.md). @@ -104,20 +89,14 @@ If you don't see the work items you expect on your [product Backlog](create-your ## Add bugs to your backlogs and boards -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -For all processes except the Basic process, each team manages the way bugs are tracked. Track bugs in the Requirements category because they show up on the Backlog and Kanban board or the Tasks category. They can also show up on the Taskboard or the Bugs category where they don't appear on either backlogs or boards. +For all processes except the Basic process, each team manages the way bugs are tracked. Track bugs in the Requirements category because they show up on the Backlog and board or the Tasks category. They can also show up on the Taskboard or the Bugs category where they don't appear on either backlogs or boards. ::: moniker-end [!INCLUDE [temp](../includes/basic-process-bug-note.md)] -::: moniker range="tfs-2018" - -Each team can manage the way bugs are tracked. You can track bugs as belonging to the Requirements category. Those bugs show up on the Backlog and Kanban board or the Tasks category. They can show up on the Taskboard or the Bugs category where they don't appear on either backlogs or boards. - -::: moniker-end - If you want bugs to show up on your Backlog and Board, choose Bugs are managed with requirements. > [!div class="mx-imgBorder"] @@ -125,21 +104,20 @@ If you want bugs to show up on your Backlog and Board, choose Bugs are m For more information, see [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). -## Correct your Kanban board configuration +## Correct your board configuration -If you see the following error when you open your Kanban board, you need to correct the configuration. The main reason for this error is that the workflow states of work item types that have been added to the Requirements category aren't mapped to the column. +If you see the following error when you open your board, you need to correct the configuration. The main reason for this error is that the workflow states of work item types that have been added to the Requirements category aren't mapped to the column. > [!div class="mx-imgBorder"] -> ![Kanban board, Configuration error message](media/setup-backlog/column-config-error.png) - -Choose **Correct this now** to open the Settings dialog. To map the workflow states, refer to [Add columns to your Kanban board, Update Kanban column-to-State mappings](../boards/add-columns.md#state-mappings). +> ![Board, Configuration error message](media/setup-backlog/column-config-error.png) +Choose **Correct this now** to open the Settings dialog. To map the workflow states, refer to [Add columns to your board, Update column-to-State mappings](../boards/add-columns.md#state-mappings). -## Customize your Kanban board checklist items +## Customize your board checklist items -Checklists are a great way to create work items that are automatically linked with a parent-child link to another work item on a Kanban board. You can customize the work item types that you can add as a checklist by opening the Board Settings, choose **Annotations**, and enable the work item types you want to appear on the board. For more information, see [Customize cards](../boards/customize-cards.md#annotations). +Checklists are a great way to create work items that are automatically linked with a parent-child link to another work item on a board. You can customize the work item types that you can add as a checklist by opening the Board Settings, choose **Annotations**, and enable the work item types you want to appear on the board. For more information, see [Customize cards](../boards/customize-cards.md). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" For example, here we've chosen to track bugs along with tasks, and enable Task, Bug, GitHub objects, and Tests to appear within checklists. @@ -148,54 +126,26 @@ For example, here we've chosen to track bugs along with tasks, and enable Task, ::: moniker-end -::: moniker range="azure-devops-2019" -> [!NOTE] -> The GitHub annotations require Azure DevOps Server 2019 update 1 or later version. +::: moniker range="<=azure-devops" -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -To learn more about checklists, see the following articles: +For more information about checklists, see the following articles: - [Add tasks or child items as checklists](../boards/add-task-checklists.md) - [Add, run, and update inline tests](../boards/add-run-update-tests.md) -- [Link GitHub commits, pull requests, and issues to work items](../github/link-to-from-github.md) +- [Link GitHub commits, pull requests, branches, and issues to work items](../github/link-to-from-github.md) ::: moniker-end + -::: moniker range="tfs-2018" +## Add other work item types to your board checklist +If you added work item types to the Task Category as described in [Add custom work item types to your Taskboard](#taskboard-types) later in this article, you can choose if these types appear within a checklist on your product board. You make this choice by opening **Board Settings**, choose **Annotations**, and enable the work item types you want to appear on the board. You can enable up to five annotations. For more information, see [Customize cards](../boards/customize-cards.md). -For example, here we've chosen to track bugs along with tasks, and enable Task and Bug to appear within checklists. - -> [!div class="mx-imgBorder"] -> ![Kanban board, Settings, Annotations](media/setup-backlog/annotations-product-backlog.png) - -To learn more about checklists, see the following articles: -- [Add tasks or child items as checklists](../boards/add-task-checklists.md) -- [Add, run, and update inline tests](../boards/add-run-update-tests.md) - - -::: moniker-end - - - - -::: moniker range=">= azure-devops-2019" - -## Add other work item types to your Kanban board checklist - -If you added work item types to the Task Category as described in [Add custom work item types to your Taskboard](#taskboard-types) later in this article, you can choose if these types appear within a checklist on your product Kanban board. You make this choice by opening **Board Settings**, choose **Annotations**, and enable the work item types you want to appear on the board. You can enable up to five annotations. For details see [Customize cards](../boards/customize-cards.md#annotations). - -For example, here we've chosen to track bugs along with tasks, and we enable Issue and Ticket and Task and Bug. To learn more about checklists, see [Add tasks or child items as checklists](../boards/add-task-checklists.md) and [Add, run, and update inline tests](../boards/add-run-update-tests.md). +For example, here we've chosen to track bugs along with tasks, and we enable Issue and Ticket and Task and Bug. For more information about checklists, see [Add tasks or child items as checklists](../boards/add-task-checklists.md) and [Add, run, and update inline tests](../boards/add-run-update-tests.md). > [!div class="mx-imgBorder"] > ![On the settings page, the Annotations tab is selected and five Annotation types (Task, Bug, Tests, Issue, Ticket) are listed. All but Tests are enabled.](media/setup-backlog/annotations-on-prem.png) -::: moniker-end - - ## Hide or show backlog levels Your team can also choose to hide or show one or more backlog levels. Feature teams often manage backlog items, while management teams manage features and epics. In this situation, you can enable or disable a backlog level. @@ -205,7 +155,7 @@ Your team can also choose to hide or show one or more backlog levels. Feature te For more information, see [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md). - + ## Add custom work item types to your backlogs and portfolio backlog levels @@ -228,7 +178,7 @@ For more information, see the following resources: ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" + ## Add custom work item types to your Taskboard To add custom work item types to appear on your sprint Taskboard, follow the steps outlined next based on the process model your project uses. -::: moniker range=">= azure-devops-2019 " +::: moniker range="<=azure-devops" > [!NOTE] -> You can enable work item types that you add to your Iteration backlog to appear as a checklist on your product Kanban board. To learn how, see [Customize your Kanban board checklist items](#customize-checklist-2019) provided earlier in this article. +> You can enable work item types that you add to your Iteration backlog to appear as a checklist on your product board. To learn how, see [Customize your board checklist items](#customize-checklist-2019) provided earlier in this article. ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### Track custom work items with the Inherited process model @@ -273,10 +214,8 @@ For example, if you want to track a custom work item type, Tickets, along with T 2. Add the Ticket work item types to the Iteration backlog. For more information, see [Customize your backlogs or boards for a process](../../organizations/settings/work/customize-process-backlogs-boards.md). - ::: moniker-end - ::: moniker range="< azure-devops" ### Add existing and custom work item types with the On-premises XML process model @@ -320,12 +259,12 @@ For on-premises deployments that use the On-premises XML process model to custom ## Other factors that can affect work items in your backlogs and boards The following settings can influence the type and number of work items that appear in your backlogs and boards. -- In your Kanban board, newly added work items may not appear if they're stack ranked lower within the product backlog. By choosing **Show more items**, you can cause the board to refresh and display more work items. +- In your board, newly added work items may not appear if they're stack ranked lower within the product backlog. By choosing **Show more items**, you can cause the board to refresh and display more work items. > [!div class="mx-imgBorder"] > ![Boards, Show more items](media/setup-backlog/show-more-items.png) -- If you have nested work items that belong to the same category, only leaf nodes may appear on the Kanban board (for TFS 2018.1 and earlier versions). For this reason, we recommend that you don't nest work items of the same work item type or belonging to the same category. For more information, see [Fix reordering and nesting issues, How backlogs and boards display hierarchical (nested) items](resolve-backlog-reorder-issues.md#leaf-nodes). +- If you have nested work items that belong to the same category, only leaf nodes may appear on the board (for TFS 2018.1 and earlier versions). For this reason, we recommend that you don't nest work items of the same work item type or belonging to the same category. For more information, see [Fix reordering and nesting issues, How backlogs and boards display hierarchical (nested) items](resolve-backlog-reorder-issues.md). - If you've turned off the **In Progress** view, then those work items where work has started won't appear in the backlog list. @@ -334,15 +273,9 @@ The following settings can influence the type and number of work items that appe > ![Backlogs, View Options, Hide In Progress](media/setup-backlog/hide-in-progress-s155.png) ::: moniker-end - ::: moniker range="azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Backlogs, View Options, Hide In Progress](media/setup-backlog/hide-in-progress.png) - ::: moniker-end + - ::: moniker range="tfs-2018" - > [!div class="mx-imgBorder"] - > ![Backlogs, Hide In Progress](media/setup-backlog/hide-in-progress-prev.png) - ::: moniker-end + - Work items appear in the priority order in which they're added or moved to. This order or sequence is managed by the **Stack Rank** (Basic, Agile, and CMMI processes) or **Backlog Priority** (Scrum) field. For more information, see the Stack rank section in [Backlogs, portfolios, and Agile project management](backlogs-overview.md#stack-rank). @@ -354,12 +287,11 @@ The following settings can influence the type and number of work items that appe - On-premises XML process model: If an administrator [deletes or destroys a work item type](../../reference/witadmin/witadmin-import-export-manage-wits.md), it doesn't appear on backlogs and boards. - ## Related articles - [Add a team, move from one default team to several teams](../../organizations/settings/add-teams.md) -- [Refine your backlog](best-practices-product-backlog.md) - [Create your backlog](create-your-backlog.md) - [Backlog priority or stack rank order](backlogs-overview.md#stack-rank) - [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types) -- [Workflow states & state categories](../work-items/workflow-and-state-categories.md) +- [Workflow states & state categories](../work-items/workflow-and-state-categories.md) +- [Automate work item state transitions](../work-items/automate-work-item-state-transitions.md) diff --git a/docs/boards/backlogs/toc.yml b/docs/boards/backlogs/toc.yml index ea42f637fe5..03f13cf2ee8 100644 --- a/docs/boards/backlogs/toc.yml +++ b/docs/boards/backlogs/toc.yml @@ -21,11 +21,10 @@ - name: Configure your backlog view href: configure-your-backlog-view.md displayname: backlog level, view options, rollup, parents, forecasting, mapping, completed, expand, collapse, filter + - name: Automate work item state transitions + href: automate-work-item-state-transitions.md - name: Set up your backlogs & boards href: set-up-your-backlog.md - - name: Backlog controls - href: product-backlog-controls.md - displayname: selector, Analytics, view options, parents, forecasting, mapping, completed, full screen mode, expand, collapse, Configure team settings, filter - name: Change column options href: set-column-options.md - name: Display rollup progress bars or totals diff --git a/docs/boards/backlogs/work-item-template.md b/docs/boards/backlogs/work-item-template.md index 0e98011ea43..9f3805354e9 100644 --- a/docs/boards/backlogs/work-item-template.md +++ b/docs/boards/backlogs/work-item-template.md @@ -1,36 +1,33 @@ --- title: Use Azure DevOps work item templates to update work items in Azure Boards -titleSuffix: Azure Boards -description: Learn how to add and manage Azure DevOps work item templates to update work items in Azure Boards. Learn to pre-populate work item form fields in Azure DevOps and Visual Studio. +titleSuffix: Azure Boards +description: Learn how to add and manage Azure DevOps work item templates to update work items in Azure Boards. Learn to prepopulate work item form fields in Azure DevOps and Visual Studio. ms.service: azure-devops-boards ms.assetid: 9b575c05-16f3-4027-aa5a-67b017a0089d ms.author: chcomley author: chcomley ms.topic: how-to -ms.custom: "work-items, contperf-fy21q3" +ms.custom: work-items monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 04/29/2024 --- -# Use templates to add and update work items in Azure Boards and Visual Studio +# Use work item templates [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-2015](../../includes/version-vs-gt-2015.md)] -With work item templates, you can quickly create work items that have pre-populated values for your team's commonly used fields. For example, create a template that defines the area path, iteration path, and activity to use when creating a task. +With work item templates, you can quickly create work items with prepopulated values for your team's commonly used fields. You can use work item templates to create work items or make bulk updates to several work items. You can add and manage work item templates from the web portal or from Visual Studio 2015 or earlier versions. For examples showing usage of work item templates, see [Sample work item templates](../work-items/work-item-template-examples.md). -You can use work item templates to create work items or bulk update several work items. For examples that show usage of work item templates, see [Sample work item templates](../work-items/work-item-template-examples.md). +Work item templates are distinct from process templates. For more information, see [About processes and process templates](../work-items/guidance/choose-process.md) or these specific articles for default process templates: [Basic](../get-started/plan-track-work.md), [Agile](../work-items/guidance/agile-process.md), [Scrum](../work-items/guidance/scrum-process.md), or [CMMI](../work-items/guidance/cmmi-process.md). -> [!NOTE] -> Work item templates are distinct from process templates. For more information, see [About processes and process templates](../work-items/guidance/choose-process.md) or these specific articles for the default process templates: [Basic](../get-started/plan-track-work.md), [Agile](../work-items/guidance/agile-process.md), [Scrum](../work-items/guidance/scrum-process.md), or [CMMI](../work-items/guidance/cmmi-process.md). +## Supported template tasks -## Supported template tasks +The availability of template task options depends on your client and platform version. You can add and manage work item templates from the web portal or from Visual Studio 2015 or earlier versions. For more information, see the [prerequisites](#prerequisites) in this article. -The availability of template task options depends on the client and platform version available to you. Add and manage work item templates from the web portal or from Visual Studio 2015 or earlier versions. Visual Studio 2015 and earlier versions support working with templates by installing the [Microsoft Visual Studio Team Foundation Server 2015 Power Tools](https://marketplace.visualstudio.com/items?itemName=TFSPowerToolsTeam.MicrosoftVisualStudioTeamFoundationServer2015Power). These templates only appear in your view of Team Explorer. - -As shown in the following table, a ✔️ indicates the task is available from the web portal or from Visual Studio 2015 or earlier versions. *(Make sure that you've selected the content version based on your platform version)*. +As shown in the following table, a ✔️ indicates the task is available from the web portal or from Visual Studio 2015 or earlier versions. *(Make sure to select the content version based on your platform version)*. --- :::row::: @@ -72,7 +69,7 @@ As shown in the following table, a ✔️ indicates the task is available from t --- :::row::: :::column span="2"::: - [Copy link (URL) of a template](#copy-link) + [Copy link (URL) of a template](#edit-delete-copy-link-or-create-copy) :::column-end::: :::column span="1"::: ✔️ @@ -143,273 +140,160 @@ As shown in the following table, a ✔️ indicates the task is available from t :::row-end::: --- - > [!TIP] -> The templates you define through the web portal are distinct from those you define through Visual Studio. Web portal templates can only be managed and applied to work items through the web portal. Similarly, Visual Studio templates can only be managed, viewed, and applied to work items in Visual Studio. However, you can use the URLs of both template types to add work items through the web portal. - - -## Prerequisites - -::: moniker range=">= azure-devops-2019" - -- To add, capture, edit, or delete work item templates through the web portal, you must be a member of the team under which you add them. - -- To apply a work item template, you must be a Contributor of the project and a member of the team under which the work item template is defined. - -::: moniker-end - -::: moniker range="tfs-2018" -- To add, capture, edit, or delete work item templates through the web portal, you must be a team administrator. - -- To apply a team template, you must be a Contributor of the project and a member of the team under which the work item template is defined. -::: moniker-end - -- To add, capture, or edit work item templates through Visual Studio Team Explorer, install the [Microsoft Visual Studio Team Foundation Server 2015 Power Tools](https://marketplace.visualstudio.com/items?itemName=TFSPowerToolsTeam.MicrosoftVisualStudioTeamFoundationServer2015Power). These templates only appear in your view of Team Explorer. +> The templates you define through the web portal are distinct from those you define through Visual Studio. Web portal templates can only be managed and applied to work items through the web portal. Similarly, Visual Studio templates can only be managed, viewed, and applied to work items in Visual Studio. But, you can use the URLs of both template types to add work items through the web portal. +## Prerequisites +- **Permissions**: + - To manage work item templates in the web portal, be a member of the team that owns them. You can then add, edit, or delete templates as needed. + - To use work item templates in the web portal, be a **Contributor** to the project. You can then apply templates to existing work items. +- **Tools**: To add, capture, or edit work item templates through Visual Studio Team Explorer, install the [Microsoft Visual Studio Team Foundation Server 2015 Power Tools](https://marketplace.visualstudio.com/items?itemName=TFSPowerToolsTeam.MicrosoftVisualStudioTeamFoundationServer2015Power). These templates only appear in your view of Team Explorer. ## Capture a work item as a template -The steps to capture a work item differ based on the platform, version, and client you use. +Depending on the platform, version, and client you use, you might need to follow different steps to capture a work item. ### [Web portal](#tab/browser/) - - -::: moniker range=">= azure-devops-2019" + -Templates captured through the web portal are assigned a GUID. +Templates captured through the web portal get assigned a GUID. -1. From the web portal, open a work item that you'll use as the basis for a template. +1. From the web portal, open a work item to use as the basis for a template. -2. Choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon to open the menu. Choose **Templates** and then **Capture**. +2. Select the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon, and then choose **Templates** > **Capture**. > [!div class="mx-imgBorder"] - > ![Capture work item field definitions as a template, latest version](media/templates/wi-templates-capture-bug-vsts-s136.png) + > ![Screenshot of Capture work item field definitions as a template, latest version.](media/templates/wi-templates-capture-bug-vsts-s136.png) Name the template, select the team for which you want to save it under, and optionally define or clear fields. Save the template when finished. > [!div class="mx-imgBorder"] - > ![Capture template dialog](media/templates/capture-template-vsts-s136.png) + > ![Screenshot of Capture template dialog.](media/templates/capture-template-vsts-s136.png) -3. Once you've saved the template, choose **Copy link** to capture the URL for the template. +3. **Save** the template, and then select **Copy link** to capture the URL for the template. 4. You can paste the URL link into a browser to create a work item, or provide it to others for their use to add work items. For example, you can add it as a hyperlink to a [project wiki](../../project/wiki/wiki-create-repo.md), a [dashboard via a Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), or other shared network resource. - Use the URL whenever you want to add a work item of the type you've defined with its predefined values. - -::: moniker-end - -::: moniker range="tfs-2018" - -Templates captured through the web portal are assigned a GUID. - -1. From the web portal, open a work item that you'll use as the basis for a template. + Use the URL whenever you want to add a work item of the same type with predefined values. - Within the web portal, work item templates are associated with a team. Only those templates that are defined for a team are accessible when you go to [apply a template](#apply) to work items using the web portal. - -2. Choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon to open the menu. Choose **Templates** and then **Capture**. - - ![Capture work item field definitions as a template](media/templates/wi-templates-capture-bug-tfs.png) - - Name the template and optionally define or clear fields. Save the template when finished. The template is saved under the team you selected in the first step. - - ![Capture template dialog](media/wi-templates-capture-template-dialog.png) - -3. Once you've saved the template, choose **Copy link** to capture the URL for the template that you can use to add work items using the template. - -4. Use the URL whenever you want to add a work item of the type you've defined with its predefined values. - - You can save the URL as a text file or add the URL to a [dashboard](#markdown-widget) or web page as a hyperlink. - -::: moniker-end - - + ### [Visual Studio 2015](#tab/visual-studio/) - + -If you primarily work in Visual Studio or Team Explorer, and want to create work items from templates that you access from the Work Items page, you can create work item template files (extension .wt). +To create work items from templates in Visual Studio or Team Explorer, you can use work item template files, for example, .wt extension. These files are accessible from the Work Items page. -1. If you haven't yet installed [Microsoft Visual Studio Team Foundation Server 2015 Power Tools](https://marketplace.visualstudio.com/items?itemName=TFSPowerToolsTeam.MicrosoftVisualStudioTeamFoundationServer2015Power), do that now. You need this software installed to access the Work Item Templates power tool for Visual Studio. +1. Sign in to Visual Studio. -1. Open or run a query that lists the work item whose fields you want to capture. +1. Open or run a query that lists the work item whose fields you want to capture. -2. Right-click the work item of the type and whose fields you want to capture, and select Capture Template from the context menu. +2. Right-click the work item of the type and whose fields you want to capture, and select **Capture Template** from the context menu. - Capture work item field definitions as a template from Visual Studio with Power Tools installed + :::image type="content" source="media/wi-templates-te-capture-wi-as-template.png" alt-text="Screenshot of Capture work item field definitions as a template from Visual Studio with Power Tools installed."::: 3. In the dialog, use the checkboxes to select all the fields you want to save in the template. Then, add a name and (optionally) description to the template. - Capture template dialog from Visual Studio with Power Tools installed + :::image type="content" source="media/wi-templates-capture-template-dialog-te.png" alt-text="Screenshot of Capture template dialog from Visual Studio with Power Tools installed."::: -4. Save the template and it appears in the root of the Team Explorer pane under the Templates section. +4. **Save** the template, which appears in the root of the Team Explorer pane under the Templates section. * * * -## Manage work item templates +## Manage work item templates -You can view the list of templates defined for each work item type, and also add, edit, copy, delete, rename, and copy the link of a template. All templates are defined and managed for a team. +For each work item type, you can see and manage the templates that your team defined. You can perform various actions on the templates, such as adding, editing, copying, deleting, renaming, and getting the link. ### [Web portal](#tab/browser/) -::: moniker range=">= azure-devops-2019" + - +1. From the web portal, open **Project settings**. -You must be a member of the team to add or edit team templates. - -1. From the web portal, open settings for a team. - - Choose **Project Settings**. - - > [!div class="mx-imgBorder"] - > ![Open project settings](../../media/settings/open-project-settings-vert-brn.png) + :::image type="content" source="../../media/settings/open-project-settings-vert-brn.png" alt-text="Screenshot showing project settings button."::: Expand **Boards** and choose **Team configuration**. If you need to switch to a different team, use the team selector. -1. Choose **Templates**. - - From here, you can choose any work item type to view or add templates for that type. - -::: moniker-end - - +2. Select **Templates**. +3. Choose any work item type to view or add templates for that type. -::: moniker range="tfs-2018" + -You manage templates from team settings. All templates are defined for a team. If you're not a team administrator, [get added as one](../../organizations/settings/add-team-administrator.md). Only team or project administrators can change work item templates. +### Manage templates for a work item type -1. From the web portal, open settings for a team. +1. Select **Project settings** > **Team configuration** > **Templates**. +2. Select a work item type to view its defined templates. - Choose the :::image type="icon" source="../../media/icons/admin-gear-icon.png" border="false"::: gear icon to open the settings for a team. +For example, select **User Story** to view templates defined for capturing user stories. - Here we open the admin page for the Web team. +:::image type="content" source="media/templates/templates-user-story-type-selected.png" alt-text="Screenshot of User Story templates selection."::: - Open the admin page for the Web team. - -1. Choose **Work>Templates**. - - Open Work - Templates page for team - - From here, you can select any work item type to view or add templates for that type. - -::: moniker-end - - -### Manage templates for a work item type - -::: moniker range=">= azure-devops-2019" - -- Choose the work item type to view the templates defined for each type. - - For example, choose User Story to view templates defined to capture user stories. - - > [!div class="mx-imgBorder"] - > ![Screenshot, choose User Story templates](media/templates/templates-user-story-type-selected.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -- Choose the work item type to view the templates defined for each type. - For example, choose User Story to view templates defined to capture user stories. - - ![Manage user story templates](media/wi-templates-user-stories-list.png) - -::: moniker-end - - + ### Create a work item template -1. From the work item type page, choose the ![green plus icon](../media/icons/green_plus_icon.png) **New template** to create a template from scratch. +1. From the work item type page, select the ![green plus icon](../media/icons/green_plus_icon.png) **New template** to create a template from scratch. - Add a user story template - -2. Name the template and optionally add and remove fields. Save the template when finished. - - Once you've saved the template, select Copy link to capture the URL for the template that you can use to add work items using the template. - -### Edit, rename, or copy a link to a template - -1. From the work item type page, choose :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: the actions icon for an existing template to access the menu options to **Edit**, **Delete**, or **Copy link**. - - Open template action menu - -1. To rename a template, choose to edit the template, change the name, and then save your changes. - -### Create a copy of a template + :::image type="content" source="media/wi-templates-new-template.png" alt-text="Screenshot showing adding a user story template."::: -1. To duplicate an existing template, choose :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: the actions icon for an existing template and select the **Create copy** option. +2. Name the template and optionally add and remove fields. **Save** the template when you're done. - Copy an existing template +3. To get the URL for the template, choose **Copy link**. You can use this URL to create work items based on the template. -2. Name the template and optionally add and remove fields. Save the template when finished. +### Edit, delete, copy link, or create copy +From the work item type page, choose :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: the actions icon for an existing template to access the menu options to **Edit**, **Delete**, **Copy link**, or **Create copy**. - - -### Delete a template - -1. From the web portal, open **Project Settings>Team configuration>Templates**. - -2. Choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon to open the menu, and choose **Delete**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Delete a template menu option.](media/templates/delete-template.png) - -2. Choose **Delete** from the Delete template confirmation dialog that displays. - - > [!div class="mx-imgBorder"] - > ![Delete template confirmation dialog.](media/templates/delete-template-confirmation.png) +:::image type="content" source="media/wi-templates-template-action-menu.png" alt-text="Screenshot of Open template action menu."::: - As indicated in the confirmation dialog, you can't recover a template once it's deleted. +- Edit: Select **Edit** and **Save** your changes. +- Delete: Select **Delete**, and then **Delete** again from the template confirmation dialog. Once you delete a template, you can't recover it. +- Copy link: Select **Copy link**. Use the URL whenever you want to add a work item of the same type with predefined values. You can save the URL as a text file, add it to a web page as a hyperlink, copy the link to a shared network, or send to your team via email. Also, consider [adding a link to the team dashboard](#markdown-widget). +- Create copy: Select **Create copy**. Name the template, optionally add and remove fields, and then **Save** it when you're done. +### [Visual Studio 2015](#tab/visual-studio/) -#### [Visual Studio 2015](#tab/visual-studio/) - - + -With Visual Studio with power tools installed, you can view the list of templates defined for each work item type, and also add, edit, copy, delete, and copy the link of a template. These templates are only available to you. To share them with others, you can copy the template URL and share that, or save the template as a .wt file. +You can use Visual Studio with power tools to manage your own work item templates. For each work item type, you can see your defined templates and perform various actions on them. You can add, edit, delete, copy, and copy templates. You can share your templates with others by sending them the template URL or saving the template as a `.wt` file. -- You manage templates from the Team Explorer pane. +- Manage templates from the Team Explorer pane. ![Templates, Team Explorer with power tools installed](media/wi-templates-section-te.png) - The root Templates node represents the parent of all of your templates. You may create a directory structure underneath it by adding folders. Right-click on the **Templates** node or a folder and select **New Folder** from the context menu. + The root Templates node represents the parent to all of your templates. You can create a directory structure underneath it by adding folders. Right-click on the **Templates** node or a folder and select **New Folder** from the context menu. -- You can cut, copy, paste, rename, and delete templates and folders using the context menu. You may also drag and drop templates into folders. To edit multiple templates, use shift-click to select a range or ctrl-click to add individual templates to your selection, then right-click. +- Cut, copy, paste, rename, and delete templates and folders using the context menu. You can also drag and drop templates into folders. To edit multiple templates, use shift-click to select a range or ctrl-click to add individual templates to your selection, then right-click. ### Define a template 1. From the **Templates** section, right-click **Templates** and choose to create a template from scratch. - Add a new template, Visual Studio + :::image type="content" source="media/wi-templates-new-template-te.png" alt-text="Screenshot of Add a new template, Visual Studio."::: -2. Save the template, provide a Name in the dialog provided. +2. Provide a name in the dialog and **Save** your template. - Provide a Name in the dialog provided. + :::image type="content" source="media/wi-templates-new-template-save-as-te.png" alt-text="Screenshot of Provide a Name in the dialog provided."::: - Once you've saved the template, select Copy link to capture the URL for the template that you can use to add work items using the template. +3. Select **Copy link** to capture the URL for the template that you can use to add work items using the template. ### Edit, use, copy, or delete a template - To edit, delete, or complete another action on a template, open its context menu (right-click) and choose the option you want. - Open context menu and choose the option you want. + :::image type="content" source="media/wi-templates-context-menu-te.png" alt-text="Screenshot of Open context menu and choose the option you want."::: - To make frequently used templates more accessible, you can set a default template for each work item type. To do so, right-click on a template in Team Explorer and select **Set As Default**. A checkmark appears on the icon to indicate that it's now the default. - ### Set your template directory -- To change the directory where templates are stored, select the Configure link, or go to it via **Tools>Options>Microsoft Team Foundation Server>Work Item Templates**. Use this dialog to set your template store path. Place your templates in a network location to share them with your team. +- To change the directory where templates are stored, select the Configure link, or go to it via **Tools** > **Options** > **Microsoft Team Foundation Server** > **Work Item Templates**. Use this dialog to set your template store path. Place your templates in a network location to share them with your team. * * * @@ -417,176 +301,79 @@ With Visual Studio with power tools installed, you can view the list of template ## Add a work item using a template -The main method for adding a work item using a template is to open the template link within a browser window. To get the template link, see the next section [Copy the link to a template](#copy-link). - -You can share these links through email, a network share, or a team dashboard. - - - -## Copy the link to a template - -Use the URL whenever you want to add a work item of the type you've defined with its predefined values. Copy the link to a shared network or send to your team via email. Also, consider [adding a link to the team dashboard](#markdown-widget). - -### [Web portal](#tab/browser/) - -::: moniker range=">= azure-devops-2019" - -1. Go to **Project Settings**. - - > [!div class="mx-imgBorder"] - > ![Open project settings](../../media/settings/open-project-settings-vert-brn.png) - - Expand **Boards** and choose **Team configuration**. Then, choose **Templates**. - -1. Choose the work item type whose template you want to copy. - -1. Choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon to open the menu, and choose **Copy link**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Copy link template menu option.](media/templates/copy-link-template-menu-option.png) - - You can save the URL as a text file or add the URL to a web page as a hyperlink. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Choose the :::image type="icon" source="../../media/icons/admin-gear-icon.png" border="false"::: gear icon to open the settings for a team. - - > [!div class="mx-imgBorder"] - > ![Open team admin context](../../media/open-admin-context-standard.png) - -1. Choose the **Work>Templates** tab. Then, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon for the template you want to copy and select **Copy link**. - - Copy link of a template - - You can save the URL as a text file or add the URL to a web page as a hyperlink. - -::: moniker-end - -### [Visual Studio 2015](#tab/visual-studio/) - - - -1. You can copy the link to a template, which opens in the web portal, by opening the context menu for the template. - - Copy link to template from Visual Studio with Power Tools installed - -2. Paste the copied link into a web browser to check that it works as expected. - -* * * +The main method used to add a work item using a template is to open the template link within a browser window. To get the template link, see the [Edit, delete, copy link, create copy](#edit-delete-copy-link-or-create-copy) section. -## Apply a template to new or existing work item(s) +## Apply a template to new or existing work items You can apply a template to a single work item or do a bulk update of several work items. - - -#### [Web portal](#tab/browser/) + -::: moniker range=">= azure-devops-2019" +### [Web portal](#tab/browser/) ### Apply a template within a work item 1. Open a new work item or an existing work item that you want to update using the fields defined within a template, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon to open the menu, select **Templates**, and then select the name of a predefined template. - > [!div class="mx-imgBorder"] - > ![Apply a template to an existing work item within the form](media/templates/apply-template-vsts-s136.png) - - Only those templates defined for teams that you belong to appear. + :::image type="content" source="media/templates/apply-template-vsts-s136.png" alt-text="Screenshot of Apply a template to an existing work item within the form."::: - > [!TIP] - > Refresh your browser to discover the latest templates that have been added. If you don't see any templates, it may be that there are none defined for the work item type. + Only those templates defined for teams that you belong to appear. -2. Save the work item for the changes to be applied. The fields changed are noted in the History field.

- -::: moniker-end - -::: moniker range="tfs-2018" - -### Apply a template within a work item - -1. Open the work item that you want to update using the fields defined within a template, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon to open the menu, select **Templates**, and then select the name of a predefined template. - - Apply a template to an existing work item within the form - - > [!TIP] - > Refresh your browser to discover the latest templates that have been added. If you don't see any templates, it may be that there are none defined for the work item type. - -2. Save the work item for the changes to be applied. The fields changed are noted in the History field.

- -::: moniker-end + > [!TIP] + > Refresh your browser to discover the latest templates added. If you don't see any templates, there might not be any for that work item type. +2. Save the work item for the changes to be applied. The fields changed are noted in the History field. -### Apply a template to several work items - -::: moniker range=">= azure-devops-2019" +### Apply a template to several work items 1. To bulk update several work items, first select them from the backlog or a query results list, and then open the actions menu for one of them. All work items you select must be of the same work item type. For example, all user stories or all bugs. 2. Choose the template to apply. + + :::image type="content" source="media/templates/bulk-apply-template-vsts-s136.png" alt-text="Screenshot of Bulk update several work items."::: - > [!div class="mx-imgBorder"] - > ![Bulk update several work items](media/templates/bulk-apply-template-vsts-s136.png) - -3. Field changes are automatically applied and work items saved. To learn more about bulk updates, see [Bulk modify work items](../backlogs/bulk-modify-work-items.md). - -::: moniker-end - -::: moniker range="tfs-2018" - -1. To bulk update several work items, first select them from the backlog or a query results list, and then open the actions menu for one of them. All work items you select must be of the same work item type. For example, all user stories or all bugs. - -2. Choose the template to apply. - - ![Bulk update several work items](media/wi-templates-bulk-update-list-vsts.png) - -3. Field changes are automatically applied and work items saved. To learn more about bulk updates, see [Bulk modify work items](../backlogs/bulk-modify-work-items.md). - -::: moniker-end +3. Field changes are automatically applied and work items saved. For more information about bulk updates, see [Bulk modify work items](../backlogs/bulk-modify-work-items.md). -#### [Visual Studio 2015](#tab/visual-studio/) +### [Visual Studio 2015](#tab/visual-studio/) - + -1. Open or run a query that lists the work item(s) whose fields you want to capture. +1. Open or run a query that lists one or more work items whose fields you want to capture. 2. Right-click the work items—which must be of the same type—and choose **Apply Template** from the context menu. - Apply template to selected work item from Visual Studio with Power Tools installed + :::image type="content" source="media/wi-templates-apply-template-options-te.png" alt-text="Screenshot of Apply template to selected work item from Visual Studio with Power Tools installed."::: 3. Select the template to use and select OK. - Apply template dialog from Visual Studio with Power Tools installed + :::image type="content" source="media/wi-templates-apply-template-dialog-te.png" alt-text="Screenshot of Apply template dialog from Visual Studio with Power Tools installed."::: 4. Save the work item. - Save changes from Visual Studio with Power Tools installed + :::image type="content" source="media/wi-templates-apply-save-work-items-te.png" alt-text="Screenshot of Save changes from Visual Studio with Power Tools installed."::: * * * - ## Add or remove tags from templates -You can add tags to a template and they'll be applied to the work item when you use the template. To add two or more tags, delimit them with a comma (,). +You can add tags to a template and they're applied to the work item when you use the template. To add two or more tags, delimit them with a comma (,). > [!div class="mx-imgBorder"] > ![Edit bug template, add or remove tags](media/templates/edit-template-add-tags.png) -If you don't specify tags to remove, then all tags present in a work item remain defined. They'll remain defined even when you apply a work item template to an existing work item. - +If you don't specify tags to remove, then all tags present in a work item remain defined. They remain defined even when you apply a work item template to an existing work item. ## Define an unplanned work item template using a hyperlink -You can specify a work item template that specifies several field values using the following syntax. Use the URL whenever you want to add a work item of the type you've defined with its predefined values. +You can specify a work item template that specifies several field values using the following syntax. Use the URL whenever you want to add a work item of the same type with predefined values. ::: moniker range="azure-devops" @@ -646,22 +433,22 @@ For example, the following syntax specifies a work item task with title *TaskTit ::: moniker-end > [!TIP] -> There is a 2000 character limit imposed by some browser clients. +> There's a 2000 character limit imposed by some browser clients. You can save the URL as a text file or add the URL to a dashboard or web page as a hyperlink. -## Add a template link to a team dashboard +## Add a template link to a team dashboard You can add links to a Markdown widget that appear on your team dashboard in the web portal. These links open a work item with the template defined fields predefined. - For example, the following widget contains links to three templates. ![Markdown widget with links to templates](media/wi-templates-markdown-widget-with-template-links.png) -To learn more about the Markdown widget see [Add Markdown to a dashboard, Markdown widgets](../../report/dashboards/add-markdown-to-dashboard.md). +For more information, see [Add Markdown to a dashboard, Markdown widgets](../../report/dashboards/add-markdown-to-dashboard.md). + ## Related articles - [Azure Boards FAQs](../faqs.yml) diff --git a/docs/boards/best-practices-agile-project-management.md b/docs/boards/best-practices-agile-project-management.md index 8d5763bec1a..8c15e7ab227 100644 --- a/docs/boards/best-practices-agile-project-management.md +++ b/docs/boards/best-practices-agile-project-management.md @@ -1,417 +1,397 @@ --- title: Best practices for Agile project management titleSuffix: Azure Boards -description: Get started guide for project managers new to Azure Boards to plan and track their projects +description: Get started with this guide for project managers who are new to Azure Boards to plan and track your projects. ms.service: azure-devops-boards ms.topic: best-practice -ms.custom: cross-project +ms.custom: cross-project ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 03/23/2023 +ms.date: 10/15/2024 +#customer intent: As a project manager or lead, I want to understand the Azure Boards tools that support Agile development for my project. --- -# Best practices for Agile project management +# Best practices for Agile project management [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] Azure Boards provides a choice of Agile planning tools, many of which work in combination with each other. This article provides a get-started guide for project managers new to Azure Boards. If you and your teams want to take a minimal tracking approach to plan and manage your projects, start with this guide. Also, if you're moving from waterfall project management to Agile methods, start with this guide. > [!NOTE] -> If your team is committed to practicing Kanban or Scrum methods, see instead [About Boards and Kanban](boards/kanban-overview.md) or the [tutorials for implementing Scrum](./sprints/scrum-overview.md). +> If your team is committed to practicing Kanban or Scrum methods, see [About Boards and Kanban](boards/kanban-overview.md) or the [tutorials for implementing Scrum](./sprints/scrum-overview.md). Most of the guidance in this article is valid for both the cloud and on-premises versions. However, some of the features included in this article, such as Rollup, Analytics, and some portfolio planning tools, are only available for the cloud at this time. -## Configure your teams +## Configure your teams -Azure Boards provides each team a set of Agile tools to plan and track work. Each project defines a default team, which you can start using immediately. However, if you have several development or feature teams, we recommend that you define a team in Azure DevOps for each feature team. This way, each team can work autonomously while collaborating with each other. +Azure Boards provides each team with a set of Agile tools to plan and track work. Each project defines a default team, which you can start using immediately. If you have several development or feature teams, we recommend that you define a team in Azure DevOps for each feature team. This way, each team can work autonomously while collaborating with each other. -#### Best practice tips: +Best practice tips: -- Configure teams along the value streams your organization wants to deliver -- Define a team for each development group of six to 12 developers -- Configure development teams to support rollup to project management feature teams +- Configure teams along the value streams that your organization wants to deliver. +- Define a team for each development group of 6 to 12 developers. +- Configure development teams to support rollup to project management feature teams. -For more information about configuring teams, see the following articles: +For more information about configuring teams, see: -- [Configure a hierarchy of teams](plans/configure-hierarchical-teams.md) -- [Add a team, move from one default team to several teams](../organizations/settings/add-teams.md) -- [Agile culture](/devops/plan/adopting-agile) -- [Scale Agile to Large Teams](/devops/plan/scaling-agile) +- [Configure a hierarchy of teams](plans/configure-hierarchical-teams.md) +- [Create or add a team](../organizations/settings/add-teams.md) +- [Adopt an Agile culture](/devops/plan/adopting-agile) +- [Scale Agile to large teams](/devops/plan/scaling-agile) -## Configure your sprints +## Configure your sprints -Sprints—specified by Iteration Paths—are defined for a project and then selected by teams. A sprint cadence can vary between one week to four weeks or longer. Also, you can define sprints within a hierarchy that includes release trains. You assign work to sprints that teams commit to deliver at the end of the sprint. These Azure Boards tools rely on sprint assignments to a team [Sprint backlogs, Taskboard, and Forecast](sprints/scrum-overview.md) and [Delivery plans](plans/review-team-plans.md). +Sprints specified by iteration paths are defined for a project and then selected by teams. A sprint cadence can vary between one week to four weeks or longer. Also, you can define sprints within a hierarchy that includes release trains. You assign work to sprints that teams commit to deliver at the end of the sprint. These Azure Boards tools rely on sprint assignments to a team's Sprint backlogs, Taskboard, and Forecast and Delivery plans. For more information, see [Implement Scrum practices](sprints/scrum-overview.md) and [Review team delivery plans](plans/review-team-plans.md). -#### Best practice tips: +Best practice tips: -- Define a sprint cadence for use by all teams within your product group -- Define at least six or more iterations that support planning for the next six to 12 months -- Determine how teams use iterations to manage backlog items - - Unassigned sprint work is assigned to the default backlog, or - - Unassigned sprint work is assigned to a designated future backlog sprint. +- Define a sprint cadence for use by all teams within your product group. +- Define at least six or more iterations that support planning for the next 6 to 12 months. +- Determine how teams use iterations to manage backlog items. -For more information about configuring sprints, see the following articles: + - Unassigned sprint work is assigned to the default backlog. + - Unassigned sprint work is assigned to a designated future backlog sprint. -- [About Area and Iteration Paths, Define and assign Iteration Paths](../organizations/settings/about-areas-iterations.md#iteration-path-guidance) -- [Define Iteration Paths and configure team iterations](../organizations/settings/set-iteration-paths-sprints.md) - -## Choose your work item types +For more information about configuring sprints, see: -Determine which work item types your team can use to capture customer requirements and development work. If your project is based on the Agile process, we recommend using User Stories, Bugs, and Features. +- [Define and assign iteration paths](../organizations/settings/about-areas-iterations.md#define-and-assign-iteration-paths) +- [Define iteration paths and configure team iterations](../organizations/settings/set-iteration-paths-sprints.md) -If your project is based on another process, such as Basic, Scrum, or CMMI, you have a choice from those shown in the following images. Also, each team can determine how they want to track bugs. +## Choose your work item types -[!INCLUDE [temp](includes/work-item-types.md)] +Determine which work item types your team can use to capture customer requirements and development work. If your project is based on the Agile process, we recommend that you use the User Story, Bug, and Feature work item types. -[!INCLUDE [temp](includes/note-requirements-terms.md)] +If your project is based on another process, such as Basic, Scrum, or Capability Maturity Model Integration (CMMI), you have the following choices. Each team determines how they want to track bugs. -#### Best practice tips: +[!INCLUDE [work item types](includes/work-item-types.md)] -- Use **Features** to capture customer features you want to ship -- Quickly add features or requirements from the backlog and fill in details later -- Use **Requirements**—User Stories (Agile), Issues (Basic) Product Backlog Items (Scrum), or Requirements (CMMI)—to break down Features into work the development team owns -- Use Bugs to capture code defects -- Map Requirements to Features to track progress at the project management level -- Size Requirements to be completed within a sprint -- Size Features to be completed within a sprint or several sprints -- Size Epics to be delivered quarterly or to some milestone objective -- Let Developers use Tasks to break down their work as needed. +[!INCLUDE [define requirements](includes/note-requirements-terms.md)] +Best practice tips: -As project managers, you manage the Features and the development team manages the Requirements. By mapping them using parent-child links, you gain visibility into the progress of your features. Each work item you add to your team backlog is automatically assigned the default area path and iteration path set for your team. +- Use the Feature work item type to capture customer features you want to ship. +- Quickly add features or requirements from the backlog and fill in details later. +- Use the Requirement work item type to break down features into work that the development team owns. In addition: -If you have larger initiatives or scenarios that require shipping several Features, you can group these under Epics, again using parent-child links. + - For Agile, use the User Story work item type. + - For Basic, use the Issue work item type. + - For Scrum, use the Product backlog item work item type. + - For CMMI, use the Requirement work item type. -For more information about work item types, see the following articles: +- Use the Bug work item type to capture code defects. +- Map requirements to features to track progress at the project management level. +- Size requirements to be completed within a sprint. +- Size features to be completed within a sprint or several sprints. +- Size Epic work items to be delivered quarterly or to some milestone objective. +- Let developers use the Task category to break down their work as needed. -- [Define features and epics](backlogs/define-features-epics.md) -- [Create your backlog](backlogs/create-your-backlog.md) -- [Organize your backlog (map or reparent)](backlogs/organize-backlog.md) +As a project manager, you manage the features. The development team manages the requirements. When you map them by using parent-child links, you gain visibility into the progress of your features. Each work item you add to your team backlog is automatically assigned the default area path and iteration path set for your team. -## Create your product plan +If you have larger initiatives or scenarios that require shipping several features, group them under the Epic category by using parent-child links. -Create your product plan using the Features Backlog. The development team then creates their product plan using the Product Backlog. Periodically you should review and refine your product plans. +For more information about work item types, see: -### Features backlog +- [Define features and epics](backlogs/define-features-epics.md) +- [Create your backlog](backlogs/create-your-backlog.md) +- [Organize your backlog](backlogs/organize-backlog.md) -Project managers initiate the product plan by adding features to the Features backlog. Each feature should represent a shippable deliverable that addresses a customer need. +## Create your product plan -> [!div class="mx-imgBorder"] -> ![Screenshot of Features backlog.](media/best-practices/features-backlog.png) +Create your product plan by using the features backlog. The development team then creates their product plan by using the product backlog. Periodically, you should review and refine your product plans. -### Product backlog +### Features backlog -Development teams add User Stories to their product backlog so that the User Story is automatically assigned the team's default Area Path and Iteration Path. Then, they can map those stories under each Feature that represents the work required to implement the Feature. Each User Story should be sized so that they can be completed within a sprint. +Project managers initiate the product plan by adding features to the features backlog. Each feature should represent a shippable deliverable that addresses a customer need. -> [!div class="mx-imgBorder"] -> ![Screenshot of Product backlog.](media/best-practices/product-backlog.png) - -### Refine each backlog +:::image type="content" source="media/best-practices/features-backlog.png" alt-text="Screenshot that shows a features backlog."::: -Periodically review each backlog: -- Define work to be performed -- Reorder work items using drag-and-drop so that they appear in priority order -- Open work items and add details -- Assign work to team members or to sprints -- Capture technical debt and nonfeature work required to support a healthy ecosystem of delivery -- Map unparented work to the Feature they belong to -- (Optional) Estimate size of requirements to help determine team velocity and support forecasting +### Product backlog -> [!TIP] -> You can monitor team velocity based on estimates assigned to completed work or a simple count of work items completed during sprints. However, to use the Forecast feature, you must assign a value to the Story Points, Effort, or Size field. If you don't want to estimate requirements, you can simply assign a value of 1 to requirement estimates and then use the Forecast tool based on a count of work items. +Development teams add User Stories to their product backlog. The User Story is automatically assigned the team's default area path and iteration path. Then, the team map those stories under each feature that represents the work required to implement the feature. You should size each User Story so that it can be completed within a sprint. -#### Best practice tips: +:::image type="content" source="media/best-practices/product-backlog.png" alt-text="Screenshot that shows a product backlog."::: -- Periodically refine your backlog -- Make sure features and requirements are sized appropriately -- Define the acceptance criteria and the definition of done for features and work -- Map unmapped work to Features -- Set your view options to support the backlog tasks you want to accomplish -- Forecast your backlog +### Refine each backlog -For more information, see the following articles: +Periodically review each backlog by doing the following tasks: -- [Refine your backlog](backlogs/best-practices-product-backlog.md) -- [Define features and epics](backlogs/define-features-epics.md) -- [Create your backlog](backlogs/create-your-backlog.md) -- [Configure your backlog view](backlogs/configure-your-backlog-view.md) -- [Forecast your product backlog](sprints/forecast.md) +- Define the work to be performed. +- Reorder work items by using the drag-and-drop method so that they appear in priority order. +- Open work items and add details. +- Assign work to team members or to sprints. +- Capture technical debt and nonfeature work required to support a healthy ecosystem of delivery. +- Map unparented work to the features to which it belongs. +- Estimate the size of the requirements to help determine team velocity and support forecasting (optional). -## Use tags to support queries and filtering - -With work item tags, team members can assign ad-hoc tags to work items. You can use these tags to filter backlogs and boards, and query on work items. For tags to be useful to the team, provide some general guidance on how your team should use tags. Consider documenting this guidance in a central place, such as the [project wiki](../project/wiki/about-readme-wiki.md). +> [!TIP] +> You can monitor team velocity based on estimates assigned to completed work or a simple count of work items completed during sprints. To use the Forecast feature, you must assign a value to the **Story Points**, **Effort**, or **Size** field. If you don't want to estimate requirements, you can simply assign a value of **1** to requirement estimates and then use the Forecast tool based on a count of work items. -The following image illustrates a Kanban board filtered on the *web* keyword that displays cards with the *Web* tag. +Best practice tips: -> [!div class="mx-imgBorder"] -> ![Screenshot of Kanban board, Filter using keyword search.](backlogs/media/filter-boards/filter-kb-text-web-services.png) +- Periodically refine your backlog. +- Make sure features and requirements are sized appropriately. +- Define the acceptance criteria and the definition of done for features and work. +- Map unmapped work to features. +- Set your view options to support the backlog tasks you want to accomplish. +- Forecast your backlog. -#### Best practice tips: +For more information, see: -- Have a policy in place about how your teams use tags -- Indicate how you use tags to support queries, filtering, reporting -- Consider using tags to identify cross-team or cross-project dependencies +- [Define features and epics](backlogs/define-features-epics.md) +- [Create your backlog](backlogs/create-your-backlog.md) +- [Configure your backlog view](backlogs/configure-your-backlog-view.md) +- [Forecast your product backlog](sprints/forecast.md) -For more information, see the following articles: +## Use tags to support queries and filtering -- [Add work item tags to categorize and filter lists and boards](queries/add-tags-to-work-items.md) -- [Filter your Kanban board](./backlogs/filter-backlogs-boards-plans.md) -- [Create a Wiki for your project](../project/wiki/wiki-create-repo.md) +With work item tags, team members can assign ad-hoc tags to work items. You can use these tags to filter backlogs and boards. You can also use them to query on work items. For tags to be useful to the team, provide some general guidance on how your team should use tags. Consider documenting this guidance in a central place, such as the [project wiki](../project/wiki/about-readme-wiki.md). + +The following image illustrates a board filtered on the **web** keyword that displays cards with the `Web` tag. + +:::image type="content" source="backlogs/media/filter-boards/filter-kb-text-web-services.png" alt-text="Screenshot that shows a board filtered by using keyword search."::: + +Best practice tips: + +- Have a policy in place about how your teams use tags. +- Indicate how you use tags to support queries, filtering, and reporting. +- Consider using tags to identify cross-team or cross-project dependencies. + +For more information, see: -## Forecast and milestone planning +- [Add work item tags to categorize and filter lists and boards](queries/add-tags-to-work-items.md) +- [Filter your board](./backlogs/filter-backlogs-boards-plans.md) +- [Create a wiki for your project](../project/wiki/wiki-create-repo.md) -To gain insight into what features can ship when, use the **Forecast** tool. This tool requires that you provide estimates to the Story Points, Effort, or Size field for each requirement. If you want to forecast on a simple count of work items, then assign the value of **1** to requirement estimates. +## Forecast and milestone planning -### Order the features backlog in priority order +To gain insight into what features can ship when, use the Forecast tool. This tool requires that you provide estimates to the **Story Points**, **Effort**, or **Size** field for each requirement. If you want to forecast on a simple count of work items, assign the value of **1** to requirement estimates. -As project managers, you should always have your features backlog in priority order, which conveys to the development team which features are most important to complete first. +### Order the features backlog in priority order -Here the features backlog shows the sequence of features to ship. +As a project manager, you should always have your features backlog in priority order, which conveys to the development team which features are most important to complete first. -:::image type="content" source="media/best-practices/feature-backlog-priority-order.png" alt-text="Screenshot of Features backlog, ordered by feature parent."::: +Here, the features backlog shows the sequence of features to ship. -### Order the requirements backlog based on parent features +:::image type="content" source="media/best-practices/feature-backlog-priority-order.png" alt-text="Screenshot that shows a features backlog ordered by feature parent."::: -First you want to make sure you're completing the requirements needed to ship features. As shown in the following image, the requirements backlog has been ordered according to the features you want to ship. This ordering assumes that all requirements in a feature must be complete to ship it. Also, Story Points have been assigned to each User Story. +### Order the requirements backlog based on parent features -:::image type="content" source="media/best-practices/product-backlog-ordered-parent.png" alt-text="Screenshot of Requirements backlog, ordered by feature parent."::: +Make sure that you complete the requirements needed to ship features. As shown in the following image, the requirements backlog is ordered according to the features you want to ship. This ordering assumes that all requirements in a feature must be complete to ship it. Also, Story Points are assigned to each User Story. -### Forecast the requirements backlog +:::image type="content" source="media/best-practices/product-backlog-ordered-parent.png" alt-text="Screenshot that shows a requirements backlog ordered by feature parent."::: -With estimates assigned to each requirement, you can set a team velocity. In the following example, we specify 12 for the velocity, equivalent to stating that on average the team can complete 12 Story Points per sprint. The Forecast tool shows which requirements and features the team can complete within the next six sprints. Using the Planning tool, you can quickly assign requirements to the forecasted sprints. +### Forecast the requirements backlog -[!INCLUDE [temp](../includes/lightbox-image.md)] +With estimates assigned to each requirement, you can set a team velocity. The following example specifies 12 for the velocity, which is equivalent to stating that on average the team can complete 12 Story Points per sprint. The Forecast tool shows which requirements and features the team can complete within the next six sprints. When you use the Planning tool, you can assign requirements to the forecasted sprints. -> [!div class="mx-imgBorder"] -> [![Screenshot of Forecast of Requirements backlog, ordered by feature parent.](media/best-practices/forecast-product-backlog-ordered-parent.png)](media/best-practices/forecast-product-backlog-ordered-parent.png#lightbox) +:::image type="content" source="media/best-practices/forecast-product-backlog-ordered-parent.png" alt-text="Screenshot that shows the forecast of a requirements backlog ordered by feature parent." lightbox="media/best-practices/forecast-product-backlog-ordered-parent.png"::: Getting good at estimates and having predictable team velocities are useful team goals for [process improvement](#process-improvement). - -### Update your Features board -With a forecast of when a feature ships, you can update each feature's iteration path. Quickly assign values to a feature by adding those fields to the card on the Kanban board as shown in the following image. +### Update your Features board + +With a forecast of when a feature ships, you can update each feature's iteration path. Assign values to a feature by adding those fields to the card on the board, as shown in the following image. -:::image type="content" source="media/best-practices/features-board-iteration-path-updates.png" alt-text="Screenshot of Features board with updated iteration paths."::: +:::image type="content" source="media/best-practices/features-board-iteration-path-updates.png" alt-text="Screenshot that shows a Features board with updated iteration paths."::: ### Milestone planning -Milestone markers aren't used in Azure Boards work tracking, except for Delivery Plans. [Delivery Plans](plans/review-team-plans.md) provide a calendar view and allow you to define a milestone marker. -However, you can use one or more of the following options to mark a work item as a milestone: -- Prepend or append the word **Milestone** in the title of your work item -- [Add a work item tag](./queries/add-tags-to-work-items.md) labeled **Milestone** -- [Add a custom field](../organizations/settings/work/customize-process-field.md) labeled **Milestone** and populate it with a pick list of milestones -- [Link work items](./backlogs/add-link.md) using the Predecessor/Successor or Related link type to a milestone work item -- [Assign a milestone work item to the sprint](./sprints/assign-work-sprint.md) in which it's targeted for completion. - -## Manage dependencies +Milestone markers aren't used in Azure Boards work tracking, except for delivery plans. Delivery plans provide a calendar view and allow you to define a milestone marker. For more information, see [Review team delivery plans in Azure Boards](plans/review-team-plans.md). + +You can use one or more of the following options to mark a work item as a milestone: -In Microsoft Project, you manage tasks that depend on the completion of other tasks by linking them. To manage dependencies in Azure Boards, you can add similar linking by adding Predecessor/Successor link types to work items. You add these links from the Add link dialog for a work item. +- Prepend or append the word **Milestone** in the title of your work item. +- [Add a work item tag](./queries/add-tags-to-work-items.md) labeled **Milestone**. +- [Add a custom field](../organizations/settings/work/customize-process-field.md) labeled **Milestone** and populate it with a pick list of milestones. +- [Link work items](./backlogs/add-link.md) by using the Predecessor/Successor or Related link type to a milestone work item. +- [Assign a milestone work item to the sprint](./sprints/assign-work-sprint.md) targeted for completion. + +## Manage dependencies + +In Microsoft Project, you manage tasks that depend on the completion of other tasks by linking them. To manage dependencies in Azure Boards, you can add similar linking by adding Predecessor/Successor link types to work items. Add these links from the **Add link** dialog for a work item. ### Add link dialog -Azure Boards supports many link types to track related work. Choose the **Predecessor/Successor** link types to track work with dependencies. A quick way to link work items is to add a tag to work items that participate in producing or consuming dependencies, create a query based on this tag, and then add the required links from the [triage mode of the query results](queries/triage-work-items.md). +Azure Boards supports many link types to track related work. Choose the Predecessor/Successor link types to track work with dependencies. A quick way to link work items is to add a tag to work items that participate in producing or consuming dependencies. Create a query that uses the tag, and then add the required links. -The following Add link dialog illustrates how two work items are linked using the Successor link type. +The following **Add link** dialog illustrates how two work items are linked by using the Successor link type. -> [!div class="mx-imgBorder"] -> ![Screenshot of Add link dialog, successor link type.](media/best-practices/add-link-successor.png) +:::image type="content" source="media/best-practices/add-link-successor.png" alt-text="Screenshot that shows the Add link dialog with the Successor link type."::: -### Visualize work item relationships +### Visualize work item relationships ::: moniker range="azure-devops" -You can view dependencies and identify dependencies that have issues with Delivery Plans. As shown in the following image, you can toggle the display of dependency lines between linked work items. For more information, see [Track dependencies using Delivery Plans](plans/track-dependencies.md). +You can view dependencies and identify dependencies that have issues with delivery plans. As shown in the following image, you can toggle the display of dependency lines between linked work items. For more information, see [Track dependencies by using delivery plans](plans/track-dependencies.md). -:::image type="content" source="plans/media/dependencies/dependency-lines.png" alt-text="Screenshot of dependency lines between several work items."::: +:::image type="content" source="plans/media/dependencies/dependency-lines.png" alt-text="Screenshot that shows dependency lines between several work items."::: ::: moniker-end ::: moniker range="< azure-devops" -With the [Work Item Visualization](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization) Marketplace extension, you can visualize the link relationships among several work items as shown in the following image. - -[!INCLUDE [temp](../includes/lightbox-image.md)] +With the [Work Item Visualization](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization) Marketplace extension, you can visualize the link relationships among several work items, as shown in the following image. -> [!div class="mx-imgBorder"] -> [![Screenshot of Visualize work item relationships.](media/best-practices/visualize-successor-links-cross-project-wide.png)](media/best-practices/visualize-successor-links-cross-project-wide.png#lightbox) +:::image type="content" source="media/best-practices/visualize-successor-links-cross-project-wide.png" alt-text="Screenshot that shows Visualize work item relationships." lightbox="media/best-practices/visualize-successor-links-cross-project-wide.png"::: ::: moniker-end -### Minimum Viable Product versus Critical Path Management +### Minimum Viable Product vs. Critical Path Management -Azure Boards doesn't provide a native view of the critical path. In part, as Agile methodologies favor a Minimum Viable Product (MVP) over Critical Path Management (CPM). By using MVP, you identify the shortest path and dependencies by prioritizing epics, features, stories and tasks. For more context, see [The Critical Path on Agile Projects](https://www.mountaingoatsoftware.com/blog/the-critical-path-on-agile-projects) and [Running a lean startup on Azure DevOps](https://medium.com/@giladkhen/running-a-lean-startup-on-azure-devops-5934ced2cc42). +Azure Boards doesn't provide a native view of the critical path. Agile methodologies favor a Minimum Viable Product (MVP) over Critical Path Management. By using MVP, you identify the shortest path and dependencies by prioritizing Epic, Feature, User Story, and Task work item types. For more context, see [The critical path on Agile projects](https://www.mountaingoatsoftware.com/blog/the-critical-path-on-agile-projects) and [Running a lean startup on Azure DevOps](https://medium.com/@giladkhen/running-a-lean-startup-on-azure-devops-5934ced2cc42). -#### Best practice tips: +Best practice tips: -- Add a `dependency` tag to work items participating in dependency management -- Use **Predecessor/Successor** link types to track dependencies of work owned by other teams or within other projects -- Create queries to track, add, and triage dependencies -- Use [Delivery Plans](plans/track-dependencies.md) to view work that you have dependencies on from other teams +- Add a `dependency` tag to work items participating in dependency management. +- Use Predecessor/Successor link types to track dependencies of work owned by other teams or within other projects. +- Create queries to track, add, and triage dependencies. +- Use [delivery plans](plans/track-dependencies.md) to view work that you have dependencies on from other teams. - Use the [Work Item Visualization](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization) Marketplace extension to visualize dependencies for a specific work item within the work item form. -> [!NOTE] -> Marketplace extensions are not supported features of Azure Boards and therefore not supported by the product team. For questions, suggestions, or issues you have when using these extensions, visit their corresponding extension page. - -For more information, see the following articles: - -- [Link user stories, issues, bugs, and other work items](backlogs/add-link.md) -- [Triage work items](queries/triage-work-items.md) -- [Track dependencies by using Delivery Plans](plans/track-dependencies.md) - - -## Work in sprints +> [!NOTE] +> Marketplace extensions aren't supported features of Azure Boards, so they aren't supported by the product team. For questions, suggestions, or issues you have when you use these extensions, see their corresponding extension pages. -Sprints allow the development team to focus on completing a preselected set of work. Work assigned to a sprint appears on the team's sprint backlog. Sprint backlogs are defined only for product backlogs, not for portfolio backlogs. +For more information, see: +- [Link work items to objects](backlogs/add-link.md) +- [Track dependencies by using delivery plans](plans/track-dependencies.md) -#### Sprint burndown chart +## Work in sprints -By updating the status of work daily throughout a sprint, you can easily track sprint progress with the Sprint burndown chart, as shown in the following image. +Sprints allow the development team to focus on completing a preselected set of work. Work assigned to a sprint appears on the team's sprint backlog. Sprint backlogs are defined only for product backlogs, not for portfolio backlogs. -> [!div class="mx-imgBorder"] -> ![Screenshot of Analytics Sprint burndown chart.](media/best-practices/sprint-burndown-chart.png) +By updating the status of work daily throughout a sprint, you can easily track sprint progress with the Sprint burndown chart, as shown in the following image. +:::image type="content" source="media/best-practices/sprint-burndown-chart.png" alt-text="Screenshot that shows an Analytics Sprint burndown chart." lightbox="media/best-practices/sprint-burndown-chart.png"::: -#### Best practice tips +Best practice tips: -Each sprint, perform the following tasks: +For each sprint, perform the following tasks: -- Plan each sprint with your team -- Use the team's Sprint backlog to review sprint deliverables -- Ensure each sprint work item is assigned to a team member -- Ensure each work item is scoped for completion within the sprint -- Ensure the acceptance criteria for the work are well defined and understood -- Update the status of sprint work items as work moves from a *New* to *Active* to *Completed* state to track sprint burndown -- Check in with other teams on dependencies that your team's work depends on -- Monitor sprint progress using the Sprint burndown chart +- Plan each sprint with your team. +- Use the team's sprint backlog to review sprint deliverables. +- Ensure that each sprint work item is assigned to a team member. +- Ensure that each work item is scoped for completion within the sprint. +- Ensure that the acceptance criteria for the work are well defined and understood. +- Update the status of sprint work items as work moves from *New* to *Active* to *Completed* states, tracking sprint burndown. +- Check in with other teams on dependencies on which your team's work depends. +- Monitor sprint progress by using the sprint burndown chart. -For more information, see the following articles: +For more information, see: -- [Assign backlog items to a sprint](sprints/assign-work-sprint.md) -- [Configure and monitor sprint burndown](../report/dashboards/configure-sprint-burndown.md) -- [Define features and epics](backlogs/define-features-epics.md) +- [Assign backlog items to a sprint](sprints/assign-work-sprint.md) +- [Configure and monitor sprint burndown](../report/dashboards/configure-sprint-burndown.md) +- [Define features and epics](backlogs/define-features-epics.md) -## Review progress and feature deliverables +## Review progress and feature deliverables -The three main tools you should use to review progress and deliverables are: +The three main tools you should use to review progress and deliverables are: -- Features Kanban board +- Features board - Features backlog with rollup columns - Delivery plans -### Features Kanban board - -Your Features board is another place to review progress and ensure the continuous flow of deliverables. The following image illustrates a customized Features board. In progress columns have been added such as *Need more info*, *Spec Complete*, *In Progress*, and *Customer Rollout*. These provide a more natural set of states as Features get proposed, researched, designed, developed, and then deployed to production. - -[!INCLUDE [temp](../includes/lightbox-image.md)] +### Features board -> [!div class="mx-imgBorder"] -> [![Screenshot of Features board with customized columns.](media/best-practices/features-board-customized.png)](media/best-practices/features-board-customized.png#lightbox) +Your Features board is another place to review progress and ensure the continuous flow of deliverables. The following image illustrates a customized Features board, including in-progress columns like **Need more info**, **On Deck**, **In Progress**, and **Customer Rollout**. These columns provide a more natural set of states as features get proposed, researched, designed, developed, and then deployed to production. +:::image type="content" source="media/best-practices/features-board-customized.png" alt-text="Screenshot that shows a Features board with customized columns." lightbox="media/best-practices/features-board-customized.png"::: +### Rollup -### Rollup +One quick and visual way to monitor progress is from the features backlog. By adding the rollup progress bar column, you can see what percentage of work items are completed for each feature, as shown in the following image. -One quick and visual way to monitor progress is from the Features backlog. By adding the rollup progress bar column, you can see what percentage of work items are completed for each feature, as shown in the following image. +:::image type="content" source="media/best-practices/feature-backlog-progress.png" alt-text="Screenshot that shows a features backlog showing the progress bars column option."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of Features backlog showing progress bars column option.](media/best-practices/feature-backlog-progress.png) - -### Delivery plans and multiple team deliverables +### Delivery plans and multiple team deliverables -To review features delivered across several teams, configure a delivery plan. Delivery plans provide an interactive board to review a calendar schedule of stories or features several teams plan to deliver. +To review features delivered across several teams, configure a delivery plan. Delivery plans provide an interactive board to review a calendar schedule of stories or features that several teams plan to deliver. -::: moniker range="azure-devops" -:::image type="content" source="./plans/media/plans/overview-with-callouts.png " border="false" alt-text="Screenshot with callouts of Delivery Plans, collapsed teams."::: -::: moniker-end +::: moniker range="azure-devops" +:::image type="content" source="./plans/media/plans/overview-with-callouts.png " border="false" alt-text="Screenshot with callouts of delivery plans."::: +::: moniker-end -::: moniker range="< azure-devops" +::: moniker range="< azure-devops" Interactive plan elements -::: moniker-end - -### Best practice tips +::: moniker-end -- Customize your Features Kanban board to support your team's processes -- Add fields to cards so that you can update their values quickly and easily -- Update the Iteration Path (Sprint) of Features as you gain clarity as to when they'll ship -- Review the Features board to talk through status, blocks/issues/risks/changes, and update status -- Use the filter feature to focus on tagged items, assigned by features, a specific sprint and more -- Add rollup columns to your Feature backlog to monitor overall progress based on work item count completion -- Use delivery plans to review features for several teams and discuss cross-team dependencies +Best practice tips: -For more information, see the following articles: +- Customize your Features board to support your team's processes. +- Add fields to cards so that you can update their values quickly and easily. +- Update the iteration path (sprint) of features as you gain clarity about when they ship. +- Review the Features board to talk through status, blocks/issues/risks/changes, and update status. +- Use the filter feature to focus on tagged items, assigned-by features, specific sprints, and more. +- Add rollup columns to your feature backlog to monitor overall progress based on work item count completion. +- Use delivery plans to review features for several teams to discuss cross-team dependencies. -- [Add columns to your Kanban board](boards/add-columns.md) +For more information, see: + +- [Manage columns on your board](boards/add-columns.md) - [Customize cards](boards/customize-cards.md) -- [Filter your Kanban board](./backlogs/filter-backlogs-boards-plans.md) +- [Filter your board](./backlogs/filter-backlogs-boards-plans.md) - [Display rollup progress or totals](backlogs/display-rollup.md) -- [Review team Delivery Plans](plans/review-team-plans.md) +- [Review team delivery plans](plans/review-team-plans.md) - +## Process improvement -## Process improvement +Continuous improvement is at the heart of Agile methods. To improve your processes, you need to have shared goals and a shared plan. To initiate process improvement activities, consider adding them through regular practices. You might want to: -Continuous improvement is at the heart of Agile methods. To improve your processes, you need to have shared goals and a shared plan. To initiate process improvement activities, consider adding them through regular practices, such as: +- Plan sprints. +- Set sprint goals. +- Conduct regular retrospectives. -- Sprint planning -- Setting sprint goals -- Conducting regular retrospectives +Consider the following questions when you set goals: -Consider the following questions when setting goals: +- What are you learning about your customers? What do you need to know? +- What data is being measured? Is it actionable? What data needs to be measured? +- How is the flow of deliverables? Is it as expected? Where can improvements be made? +- Are your team members empowered to do their best? What tools or information would help them improve? +- How well is information being shared? How well are teams collaborating? +- How well is your team managing technical debt and closing bugs? -- *What are you learning about your customers? What do you need to know?* -- *What data is being measured? Is it actionable? What data needs to be measured?* -- *How is the flow of deliverables? Is it as expected? Where can improvements be made?* -- *Are your team members empowered to do their best? What tools or information would help them improve?* -- *How well is information being shared? How well are teams collaborating?* -- *How well is your team managing technical debt and closing bugs?* +Some of the Agile tools you can use to support process improvement are team velocity, team dashboards, and the [Retrospectives](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives) Marketplace extension. -Some of the Agile tools you can use to support process improvement are team velocity, team dashboards, and the [Retrospectives](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives) Marketplace extension. - -### Team velocity +### Team velocity -From the team velocity chart, you can gain an understanding as to how well the team is planning and executing a sprint. As shown in the following example, the velocity chart shows the planned, completed, completed late, and incomplete count of work items for several sprints. Teams can review this chart to help determine how well they're estimating and executing and how they might improve. +From the team's Velocity chart, you can gain an understanding about how well the team is planning and executing a sprint. As shown in the following example, the Velocity chart shows the planned, completed, completed late, and incomplete count of work items for several sprints. Teams can review this chart to help determine how well they're estimating and executing and how they might improve. -> [!div class="mx-imgBorder"] -> ![Screenshot of Example team velocity chart.](../report/dashboards/media/velocity/analytics-velocity-azure-devops.png) +:::image type="content" source="../report/dashboards/media/velocity/analytics-velocity-azure-devops.png" alt-text="Screenshot that shows an example team Velocity chart."::: +### Team dashboards -### Team dashboards +Teams can define dashboards to share information and monitor real-time data on work progress. -Teams can define one or more dashboards to share information and monitor real-time data on work progress. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Example team dashboard.](../report/dashboards/media/dashboard-view-with-widgets.png) +:::image type="content" source="../report/dashboards/media/dashboard-view-with-widgets.png" alt-text="Screenshot that shows an example team dashboard."::: -#### Best practice tips +Best practice tips: -- Identify process improvement goals that your team can agree to, write them down and review them periodically -- Use team dashboards to share information and work tracking charts which you and your team review periodically -- At sprint planning meetings, have your team identify at least one sprint goal related to process improvement -- Conduct regular retrospectives to capture what went well, what didn't go well, and actions to improve -- Maintain an improvement tracking board, such as that available with the [Retrospectives](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives) Marketplace extension. +- Identify process improvement goals that your team can agree to, write them down, and review them periodically. +- Use team dashboards to share information and work tracking charts, which you and your team review periodically. +- Have your team identify at least one sprint goal related to process improvement while at sprint planning meetings. +- Conduct regular retrospectives to capture what went well, what didn't go well, and actions to improve. +- Maintain an improvement tracking board, such as the one that's available with the [Retrospectives](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives) Marketplace extension. -For more information, see the following articles: +For more information, see: -- [View or configure team velocity](../report/dashboards/team-velocity.md) +- [View and configure team velocity](../report/dashboards/team-velocity.md) - [Add, rename, and delete dashboards](../report/dashboards/dashboards.md) -- [Scaling Agile - Practices that scale](plans/practices-that-scale.md) -- [Retrospectives Marketplace extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives) +- [Implement Agile practices that scale](plans/practices-that-scale.md) +- [Retrospectives Marketplace extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives) ## Next steps > [!div class="nextstepaction"] > [Configure and customize Azure Boards](configure-customize.md) - ## Related articles - [Manage requirements](../cross-service/manage-requirements.md) - [Work with multi-team ownership of backlog items](backlogs/backlogs-overview.md#multi-team) - [11 Reasons for using Azure Boards to plan and track your work](get-started/why-use-azure-boards.md) -### Industry articles +### Industry articles -- [Agile and a continuous improvement mindset](https://scrumtraininginstitute.com/agile-scrum-training/agile-team-health-check/#:~:text=At%20the%20core%20of%20Agile%20continuous%20improvement%20is,your%20organization%20can%20develop%20a%20continuous%20improvement%20mindset) -- [What is KAIZEN™](https://www.kaizen.com/what-is-kaizen.html) +- [Agile and a continuous improvement mindset](https://scrumtraininginstitute.com/agile-scrum-training/agile-team-health-check/#:~:text=At%20the%20core%20of%20Agile%20continuous%20improvement%20is,your%20organization%20can%20develop%20a%20continuous%20improvement%20mindset) +- [What is KAIZEN](https://www.kaizen.com/what-is-kaizen.html) diff --git a/docs/boards/boards/add-columns.md b/docs/boards/boards/add-columns.md index 5af668afc1e..98bc7385fee 100644 --- a/docs/boards/boards/add-columns.md +++ b/docs/boards/boards/add-columns.md @@ -1,347 +1,214 @@ --- -title: Manage columns on your Kanban board +title: Manage columns on your board titleSuffix: Azure Boards -description: Map, add, and edit columns on your team's Kanban board to manage your workflow in Azure Boards or Azure DevOps. -ms.custom: boards-kanban, contperf-fy21q3, engagement-fy23 +description: Learn how to map, add, and edit columns on your team's board to effectively manage your workflow in Azure Boards or Azure DevOps. +ms.custom: boards-kanban, engagement-fy23 ms.service: azure-devops-boards ms.assetid: 8afd3481-6fab-401d-90ff-0dd443da0f0e +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 06/28/2023 +ms.date: 11/08/2024 --- -# Manage columns on your Kanban board +# Manage columns on your board [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The Kanban board helps you visualize your team's workflow, including the types of work and handoffs that occur regularly as your team progresses work items. Each column on your Kanban board corresponds to work that your team does before that stage is considered done. +Managing columns on your board is essential for visualizing your team's workflow. Each column corresponds to a stage of work, such as "To do," "In progress," and "Done." You can customize these columns to match your specific process, while each card on the board represents a work item, such as a user story, bug, or task. ::: moniker range=">= azure-devops-2020" > [!NOTE] > - To manage columns on a sprint Taskboard, see [Customize a Taskboard](../sprints/customize-taskboard.md). -> - To manage columns on a backlog or in query results, see [Change column options](../backlogs/set-column-options.md). +> - To manage columns on a backlog or in query results, see [Change column options](../backlogs/set-column-options.md). +> - To view frequently asked questions about Azure Boards, see [FAQs](../faqs.yml). ::: moniker-end -::: moniker range="<= azure-devops-2019" +## Prerequisites -> [!NOTE] -> - To add columns to a Taskboard, you need to customize the workflow. For more information, see [Add or modify a work item type](../../reference/add-modify-wit.md). -> - To add columns to a backlog or query results, see [Change column options](../backlogs/set-column-options.md). -> - For an overview of the features supported on each backlog and board, see [Backlog, board, and plan views](../backlogs/backlogs-boards-plans.md). - -::: moniker-end - -[!INCLUDE [temp](../includes/prerequisites-team-settings.md)] - -Complete the following tasks, so you don't need to revisit your configuration. - -#### [Process Administrator](#tab/process-administrator) - -- Add custom work item types that you want to appear on your backlog or board. For more information, see [Add and manage work item types](../../organizations/settings/work/customize-process-work-item-type.md). -- Customize your product and portfolio backlogs. Customization ensures that the chosen work item types appear on the backlogs and boards. For more information, see [Customize backlogs and boards](../../organizations/settings/work/customize-process-backlogs-boards.md). -- Customize workflow states. Each workflow state appears as a column on the Kanban board. For more information, see [Customize a workflow](../../organizations/settings/work/customize-process-workflow.md). - -#### [Team Administrator](#tab/team-administrator) - -- Set the backlogs that you want to be active for your team. You only need to configure the Kanban boards of backlogs that your team plans to use. For more information, see [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md). -- Determine how to track bugs. Bugs might have different workflow states from other types of work items in the **Requirement** category. As a result, bugs must be mapped separately from other work item types. For more information, see [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). -- Identify the columns that your team can use to support its workflow and Kanban processes. For more information, see [Map the flow of work](#map-the-flow-of-work) later in this article. -- Add, remove, or rename columns and map workflow states to columns. For more information, see [Manage columns on your Kanban board](#add-or-rename-columns) later in this article. - ---- -We recommend that you review the following articles: - -- [Kanban overview](kanban-overview.md) -- [Configure and customize Azure Boards](../configure-customize.md) -- [Set up your backlogs and boards](../backlogs/set-up-your-backlog.md) -- [Workflow states and state categories](../work-items/workflow-and-state-categories.md) +| Category | Requirements | +|--------------|-------------| +|**Access levels** | At least [**Basic**](../../organizations/security/access-levels.md) access.| +|**Permissions** | To configure team settings: Member of the **Project Administrators** security group or [**Team Administrator** role](../../organizations/settings/add-team-administrator.md). For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md).| +| **Tasks (optional)**| To avoid revisiting your configuration, we recommend doing the following tasks before you begin to manage your board columns:
- [Add custom work item types](../../organizations/settings/work/customize-process-work-item-type.md)
- [Customize your product and portfolio backlogs](../../organizations/settings/work/customize-process-backlogs-boards.md)
- [Customize workflow states](../../organizations/settings/work/customize-process-workflow.md)
- [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md)
- [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md)| - -### Map workflow states - -The Kanban board uses the **Work item type** and **State** categories to group work items that you want handled in the same manner. - - - -1. Identify your team's workflows. See the following table of example workflows and their descriptions. - - |Workflow |Description | - |---------|---------| - |Backlog | Make a prioritized list of work items that the team isn't yet ready to work on | - |Analyze | Identify well-understood and shared acceptance criteria, along with overall work required to develop and test the item | - |Develop |Code and run unit tests for the item | - |Test | Run exploratory, automated, integration, and other tests | - |Done | Hand off to production because the item is ready | - -2. Know your work item types and on which boards they appear. - - |Work item type category |Work items appear here | - |---------|---------| - |Requirement | Only on the product board | - |Feature | Only on the Feature portfolio board | - |Epic | Only on the Epic portfolio board | - |Custom| Only on a custom portfolio board | - - > [!TIP] - > We recommend that you map each workflow state to a Kanban column, as if it's not mapped, it doesn't appear on the Kanban board. - -3. Specify the workflow **State** for each work item type and column, using one of the following four categories. - - |State category |Description | - |---------|---------| - |Proposed | The first Kanban board column is automatically mapped to the default state for each work item | - |In Progress | Work flow state must be specified for each WIT and column | - |Completed | Can only map to the last Kanban board column | - |Removed | Workflow state doesn't need to be specified | - -> [!NOTE] -> When you add bugs or other work items to a Kanban board, it may create new workflow states that require adjustments to column-to-state mappings in the following situations: -> ->- When a team admin [shows bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md) ->- When a project admin [adds work item types to backlogs and boards](../../reference/add-wits-to-backlogs-and-boards.md) ->- When a project collection or project admin customizes the workflow for a work item type in the Requirement category using [inherited process](../../organizations/settings/work/customize-process-workflow.md) or [on-premises XML process](../../reference/xml/change-workflow-wit.md) - ## Add and edit columns -Column titles and choices depend on the [process](../work-items/guidance/choose-process.md) that you used to create your project and whether your team has chosen to [treat bugs like requirements or like tasks](../../organizations/settings/show-bugs-on-backlog.md). - -Do the following steps to add and edit your columns. +Column titles and options vary based on the [process](../work-items/guidance/choose-process.md) used to create your project and your team's decision to [treat bugs as requirements or tasks](../../organizations/settings/show-bugs-on-backlog.md). -::: moniker range=">= azure-devops-2019" +Do the following steps to add and edit your columns: -1. [Open your Kanban board](kanban-quickstart.md). +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +2. Select **Boards** > **Boards** > **Configure board settings** :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: . -2. Select **Configure team settings** :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: to configure the board and set general team settings. - - :::image type="content" source="../../organizations/settings/media/configure-team/open-board-settings.png" alt-text="Screenshot that shows open board settings for a team."::: - -3. Select **Columns** and then a column tab to see all the settings that you can modify. Your initial column settings look similar to the settings shown in the following image. + :::image type="content" source="media/sequence-boards-boards-configure-board-settings.png" alt-text="Screenshot shows selection sequence buttons, Boards, Boards, and Configure board settings."::: +3. Select **Columns**. + - To add a column, select **+ Add column**. + + :::image type="content" source="media/add-columns-settings-dialog-add-test-ts.png" alt-text="Screenshot shows highlighted Add column button."::: + + - To edit a column, select the column tab. For example, in the following image, we choose to edit the Active column. + :::image type="content" source="media/columns/kanban-settings-columns-active-column.png" alt-text="Screenshot that shows the Settings dialog and selection of an Active column."::: -4. Change your column titles to map to your workflow stages. You can add, rename, and move columns to support more stages. - - Rename the first three columns to **Backlog**, **Analyze**, and **Develop**. Then, add a column and label it **Test**. - - You can rename a column directly from the Kanban board. - - :::image type="content" source="media/rename-kanban-columns-direct-ts.png" alt-text="Screenshot showing renaming a column directly on a board."::: - - Or, you can open the dialog and change one or more settings for a Kanban column. - - :::image type="content" source="media/add-columns-settings-dialog-add-test-ts.png" alt-text="Screenshot that shows the Settings dialog and selections for adding a Test column."::: - -5. To change the column order, drag the column tab to the position that you want. - -6. To delete a column, first make sure that the column doesn't contain any work items. If it does, move the items to another column. Then: - - 1. Open **Settings**, select **Columns**, and select **Actions** :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: from the column tab. - 2. Select **Remove** from the menu. - - :::image type="content" source="media/columns/remove-column.png" alt-text="Screenshot that shows the selections for deleting a column in the Settings dialog."::: - -7. [Change state mappings as needed](#state-mappings) for added columns, added workflow states, or added WITs. - - Usually, you need to update state mappings when you change the [Working with bugs](../../organizations/settings/show-bugs-on-backlog.md) setting, add [WITs to the Requirement category](../../reference/add-wits-to-backlogs-and-boards.md), or [customize the workflow](../../organizations/settings/work/customize-process-workflow.md). - -8. When you're done with your changes, select **Save**. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. [Open your Kanban board](kanban-quickstart.md). If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the Kanban board. - -2. Select **Settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: to open the common configuration settings dialog for the Kanban board. - - :::image type="content" source="media/add-columns-open-settings-ts.png" alt-text="Screenshot that shows the Settings icon on the Kanban board."::: - -3. Select **Columns** and then a column tab to see all the settings that you can modify. Your initial column settings look similar to the following example. - - :::image type="content" source="media/add-columns-settings-dialog-ts.png" alt-text="Screenshot that shows column settings in the Settings dialog."::: +4. Do any of the following tasks for your columns. These tasks link to sections further in this article: + - [Map workflow states to columns](#map-workflow-states-to-columns) + - [Rename a column](#rename-a-column) + - [Split columns](#split-columns) + - [Add Definition of Done](#add-definition-of-done-to-a-column) -4. Change your column titles to map to your workflow stages. You can add, rename, and move columns to support more stages. +5. Select **Save**. - Rename the first, second, and third columns to **Backlog**, **Analyze**, and **Develop**. Then, add a column and label it **Test**. - - You can rename a column directly from the Kanban board. - - :::image type="content" source="media/rename-kanban-columns-direct-ts.png" alt-text="Screenshot that shows renaming a column directly on a Kanban board."::: - - Or, you can open the dialog and change one or more settings for a Kanban column. - - :::image type="content" source="media/add-columns-settings-dialog-add-test-ts.png" alt-text="Screenshot that shows the Settings dialog and selections for adding a Test column."::: - -5. To change the column order, drag the column tab to the position that you want. - -6. To delete a column, first make sure that the column doesn't contain any work items. If it does, move the items to another column. Then, select **Actions** :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: on the column tab and select **Remove** from the menu. - - :::image type="content" source="media/columns/remove-column.png" alt-text="Screenshot that shows the selections for deleting a column in the Settings dialog."::: - -7. [Change state mappings as needed](#state-mappings) for added columns, added workflow states, or added WITs. - - Usually, you need to update state mappings when you change the [Working with bugs](../../organizations/settings/show-bugs-on-backlog.md) setting, add [WITs to the Requirement category](../../reference/add-wits-to-backlogs-and-boards.md), or [customize the workflow](../../organizations/settings/work/customize-process-workflow.md). + + -8. When you're done with your changes, select **Save**. +## Map workflow states to columns -::: moniker-end +Mapping workflow state categories to columns in boards is essential for visualizing the progress of work items. It ensures that each state of a work item is represented on the board, providing a clear and organized view of the workflow. This mapping helps teams quickly [identify the current status of work items](#update-status), [track their progress](#track-column-status), and [spot any bottlenecks](#identify-bottlenecks) or issues. By aligning workflow states with board columns, teams can maintain a shared understanding of the workflow and improve their ability to manage and complete tasks efficiently. - +> [!TIP] +> We recommend that you map each workflow **state** to a **column**. If it’s not mapped, it doesn’t appear on the board. -### Update status and handoff items +The following table describes default user story state categories. -Drag-and-drop your work items to update the status. For example, to signal when work can start in a downstream stage, drag items to the next column. +|State category |Description | +|---------|---------| +|Proposed | The first board column is automatically mapped to the default state for each work item. | +|In Progress | Work flow state must be specified for each work item type and column. | +|Completed | Can only map to the last board column. | +|Removed | Workflow state doesn't need to be specified. | -:::image type="content" source="media/ALM_AC_DragItem.png" alt-text="Screenshot that shows dragging an item from the Analyze column to the Develop column."::: +For more information, see [About workflow and state categories](../work-items/workflow-and-state-categories.md). -You can move an item from one column to any other column on the board, forward and back. To hand off work to another team member, reassign it directly from the board. +:::image type="content" source="media/boards-columns-state-mapping.png" alt-text="Screenshot shows State mapping section of Column Edit page."::: -:::image type="content" source="media/ALM_AC_Reassign.png" alt-text="Screenshot that shows assigning an item from a Kanban board."::: +Do this task whenever you add columns, workflow states, or work item types (WITs). This action is typically necessary when you change the [Working with bugs setting](../../organizations/settings/show-bugs-on-backlog.md), add [WITs to the Requirement category](../../reference/add-wits-to-backlogs-and-boards.md), or [customize the workflow](../../organizations/settings/work/customize-process-workflow.md). -Team members who receive the handoff can [set alerts](../../organizations/notifications/manage-your-personal-notifications.md) to get immediate email notifications of their newly assigned work. +> [!NOTE] +> When you add bugs or other work items to a board, it might create new workflow states that require adjustments to column-to-state mappings in the following situations: +>- When a team administrator [shows bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). +>- When a project administrator [adds work item types to backlogs and boards](../../reference/add-wits-to-backlogs-and-boards.md). +>- When a project collection or project administrator customizes the workflow for a work item type in the Requirement category using [inherited process](../../organizations/settings/work/customize-process-workflow.md) or [on-premises XML process](../../reference/xml/change-workflow-wit.md). - +## Rename a column -### Change your team's priorities +Renaming your column titles to map to your workflow stages helps ensure clarity and alignment within your team. It allows everyone to understand the current status of work items at a glance and ensures that the board accurately reflects your team's workflow. -Drag an item up or down within a column. -:::image type="content" source="media/ALM_AC_ChangePriorities.png" alt-text="Screenshot that shows moving an item within a column."::: +Rename a column directly from the board by selecting the column name, shown in the following image. You can also rename a column from the [column edit screen](#add-and-edit-columns). - +:::image type="content" source="media/rename-kanban-columns-direct-ts.png" alt-text="Screenshot showing renaming a column directly on a board."::: -### Track Kanban column status +## Split columns -Use the [query tool](../queries/using-queries.md) to list a subset of work items for review, triage, update, or chart generation. For example, you can create a query to list all active user stories (specify two clauses: `Work Item Type=User Story` and `State=Active`). +Each column represents a work stage, showing the number of items in progress. But, there’s often a lag between moving work into a column and starting it. To address this lag, enable split columns, which divide each column into "Doing" and "Done." -Specify [WIP limits](wip-limits.md), [split columns](#split-columns), and [definition of done](#definition-of-done) +:::image type="content" source="media/kanban-board-split-columns-example-chart.png" alt-text="Screenshot showing with split columns."::: -## Split columns +Split columns help your team implement a pull mechanism, providing visibility into idle items and improving workflow transparency. -Because each column corresponds to a stage of work, you can quickly see the number of items in progress at each stage. However, a lag often exists between when work gets moved into a column and when work actually starts. To counter that lag and reveal the actual state of work in progress, you can turn on split columns. When they're split, each column contains two subcolumns, *Doing* and *Done*. +> [!NOTE] +> - Before you split columns, ensure that [each stage is mapped to a column](#map-workflow-states). Only split columns where clear hand-offs exist and you want teams to pull the item into the next stage. +> - There are different column titles and choices based on the [process](../work-items/guidance/choose-process.md) used to create your project and whether your team chose to [treat bugs like requirements or like tasks](../../organizations/settings/show-bugs-on-backlog.md). -:::image type="content" source="media/kanban-board-split-columns-example-chart.png" alt-text="Screenshot showing Kanban with split columns."::: +Choose the column tab that you want to split and add a check mark in the box to cause the column to split. -Split columns let your team implement a pull mechanism within the workflow process. Without split columns, teams push work forward, to signal that they've completed their stage of work. However, pushing it to the next stage doesn't necessarily mean that a team member immediately starts work on that item. +:::image type="content" source="media/columns/split-columns.png" alt-text="Screenshot of board settings page, Split columns."::: -With split columns, your team knows exactly how many items sit idle, waiting for work to begin. You have greater visibility into the quantity of items that sit idle at each stage throughout your workflow process. +> [!TIP] +> You can filter queries and create charts using the [Board Column Done field](../queries/query-by-workflow-changes.md#kanban_query_fields). ### Move items into the *Doing* and *Done* columns -With split columns turned on, you update status of items on the Kanban board in the same way you have before. However, now when you've completed work on an item, you move it into *Done*, instead of a downstream column. When the next team member becomes free to work on the next high priority item, they pull it into *Doing* and reassign it to themselves. +With split columns enabled, update item statuses as usual. When you complete work on an item, move it to *Done* instead of a downstream column. The next team member pulls it into *Doing* and reassigns it to themselves when ready. -For example, as a team member completes their coding task, they move the item into *Done* under the Develop column. When the tester is ready to test the item, they pull it into *Doing* under the Test column. +For example, after finishing a coding task, move it to *Done* under Develop. The tester then pulls it into *Doing* under Test when ready to start testing. -:::image type="content" source="media/columns/split-columns-move-item.png" alt-text="Screenshot showing Kanban board with split column."::: +:::image type="content" source="media/columns/split-columns-move-item.png" alt-text="Screenshot showing board with split column."::: ### Identify bottlenecks -Split columns provide you even greater insight into how many items sit idle in a *Done* column. Your team can readily see when items pile up, which signal a potential bottleneck. - -:::image type="content" source="media/kanban-board-identify-bottlenecks.png" alt-text="Screenshot of Kanban board, split columns showing stacked items."::: - -By reviewing the frequency of pile ups and where they occur, your team can adjust their processes to eliminate the bottlenecks. Workflow processes that incur no or few bottlenecks correspond to perfect flows. No item sits in a queue for any - -### Choose which columns you want to split - -Before you split columns, ensure you [mapped each stage of your team's process to a Kanban column](#map-workflow-states). Only split columns where clear hand-offs exist and you want teams to pull the item into the next stage. +Split columns provide greater insight into how many items sit idle in a *Done* column. Your team can easily see when items pile up, signaling a potential bottleneck. -::: moniker range=">= azure-devops-2019" +Review the frequency and location of pile-ups, so your team can adjust processes to eliminate bottlenecks. Workflow processes with no or few bottlenecks correspond to perfect flows. -1. [Open your Kanban board](kanban-quickstart.md) and choose the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board and set general team settings. +:::image type="content" source="media/kanban-board-identify-bottlenecks.png" alt-text="Screenshot of board, split columns showing stacked items."::: - :::image type="content" source="../../organizations/settings/media/configure-team/open-board-settings.png" alt-text="Screenshot of Open board settings for a team, vertical navigation."::: - -2. Choose **Columns** and then choose the column tab that you want to split. Add a check mark in the checkbox to cause the column to split. - - > [!NOTE] - > There are different column titles and choices based on the [process](../work-items/guidance/choose-process.md) used to create your project and whether your team chose to [treat bugs like requirements or like tasks](../../organizations/settings/show-bugs-on-backlog.md). - - :::image type="content" source="media/columns/split-columns.png" alt-text="Screenshot of Kanban board settings page, Split columns."::: - -3. When you're done, choose **Save**. - - > [!TIP] - > You can filter queries and create charts using the [Board Column Done field](../queries/query-by-workflow-changes.md#kanban_query_fields). - -::: moniker-end - -::: moniker range="tfs-2018" +### List work items in a *Doing* or *Done* column -1. [Open your Kanban board](kanban-quickstart.md) and choose :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: gear icon to open the common configuration settings dialog for the Kanban board. +You can query for work items in a split column using the **Board Column Done** field. This field takes of a value of False when in the *Doing* column and True when in the *Done* column. - :::image type="content" source="media/add-columns-open-settings-ts.png" alt-text="Screenshot of Kanban board, open common configuration settings."::: +For examples on querying Board columns, see [Query by assignment or workflow changes](../queries/query-by-workflow-changes.md#kanban_query_fields). -2. Choose **Columns** and then choose the column tab that you want to split. Place a check in the checkbox to cause the column to split. + - > [!NOTE] - > There are different column titles and choices based on the [process](../work-items/guidance/choose-process.md) used to create your project and whether your team chose to [treat bugs like requirements or like tasks](../../organizations/settings/show-bugs-on-backlog.md). +## Add Definition of Done to a column - :::image type="content" source="media/columns/split-columns-tfs-2018.png" alt-text="Screenshot of Kanban board settings dialog, Split columns."::: +When your team advances from one stage to the next, it's crucial they share a clear understanding of "Done." Define the criteria for the Definition of Done in each column. This action helps the team identify necessary tasks before advancing an item to the next stage, implementing the core tenet of making processes and policies explicit. -3. When you're done with your changes, choose **Save**. +Choose a column tab to configure the Definition of Done for that column. - > [!TIP] - > You can filter queries and create charts using the [Board Column Done field](../queries/query-by-workflow-changes.md#kanban_query_fields). -::: moniker-end +:::image type="content" source="media/columns/definition-of-done-defined.png" alt-text="Screenshot showing the columns management screen, entering plain text for Definition of Done."::: -### List work items in a *Doing* or *Done* column +Users can quickly double-check the criteria by choosing the Information tooltip :::image type="icon" source="../../media/icons/info.png" border="false"::: info icon. -You can query for work items in a split column using the **Board Column Done** field. This field takes of a value of False when in the *Doing* column and True when in the *Done* column. +:::image type="content" source="media/columns/definition-of-done-information-tooltip.png" alt-text="Screenshot showing information tooltip of Definition of Done."::: -For examples on querying Board columns, see [Query by assignment or workflow changes](../queries/query-by-workflow-changes.md#kanban_query_fields). +## Remove or move a column - +Removing or moving a column can help streamline your board and better reflect your team's workflow and priorities. By adjusting the order of columns or removing unnecessary stages, you can ensure that the most critical stages are prominently displayed and that the workflow is intuitive for all team members. -## Add the Definition of Done to a column +### Remove a column -When your team advances from one stage to the next in their work, it's crucial that they have a shared understanding of what constitutes as "done." You can define the criteria for the Definition of Done in each Kanban column. By doing so, the team can identify the necessary tasks that need to be completed before advancing an item to the next stage. This task also implements one of the core Kanban tenets, *make processes and policies explicit*. +1. Ensure the column doesn't contain any work items. If it does, move the items to another column. +2. On the [Configure board settings](#add-and-edit-columns) page, select **Columns** > **Column options menu** :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: > **X Remove**. -Team members can quickly double-check the criteria by choosing the Information tooltip :::image type="icon" source="media/ALM_DD_InfoIcon.png" border="false"::: info icon. + :::image type="content" source="media/columns/remove-column.png" alt-text="Screenshot that shows the selections for deleting a column in the Settings dialog."::: -:::image type="content" source="media/columns/definition-of-done-information-tooltip.png" alt-text="Screenshot showing information tooltip of Definition of Done."::: +### Move a column -::: moniker range=">= azure-devops-2019" +To move a column, drag the column tab to the desired position on the board or in the **Column options menu**, select **Move left** or **Move right**. -1. Open your Kanban board. +:::image type="content" source="media/columns/column-options-menu.png" alt-text="Screenshot shows the column options menu in Configure board settings."::: -2. Choose the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board and set general team settings. +## Update status - :::image type="content" source="../../organizations/settings/media/configure-team/open-board-settings.png" alt-text="Screenshot of the settings gear highlighted for selection."::: +To update status, drag-and-drop your work items. For example, to signal when work can start in a downstream stage, drag items to the next column. You can move an item from one column to any other column on the board, forward and back. -3. Choose **Columns** and then a column tab to configure the Definition of Done for that column. +:::image type="content" source="media/ALM_AC_DragItem.png" alt-text="Screenshot that shows dragging an item from the Analyze column to the Develop column."::: - :::image type="content" source="media/columns/definition-of-done-defined.png" alt-text="Screenshot showing the columns management screen, entering plain text for Definition of Done."::: +## Hand off work items -4. When you're done with your changes, select **Save**. +To hand off work to another team member, reassign it directly from the board. -::: moniker-end +:::image type="content" source="media/ALM_AC_Reassign.png" alt-text="Screenshot that shows assigning an item from a board."::: -::: moniker range="tfs-2018" +Users who receive the handoff can [set alerts](../../organizations/notifications/manage-your-personal-notifications.md) to get immediate email notifications of their newly assigned work. -1. Open your Kanban board. +## Track column status -2. Choose ![settings icon](../../media/icons/team-settings-gear-icon.png) to open the common configuration settings dialog for the Kanban board. +Use the [query tool](../queries/using-queries.md) to list a subset of work items for review, triage, update, or chart generation. For example, you can create a query to list all active user stories (specify two clauses: `Work Item Type=User Story` and `State=Active`). - :::image type="content" source="media/add-columns-open-settings-ts.png" alt-text="Screenshot showing the settings gear highlighted for selection."::: +Specify [work in progress (WIP) limits](wip-limits.md), [split columns](#split-columns), and [definition of done](#definition-of-done). -3. Choose **Columns** and then a column tab to configure the Definition of Done for that column. You can specify the Definition of Done for each intermediate column on your team's Kanban board. + - :::image type="content" source="media/columns/definition-of-done-defined.png" alt-text="Screenshot of columns management screen, entering plain text for Definition of Done."::: +## Change your team's priorities -4. When you're done with your changes, choose **Save**. +Drag an item up or down within a column. -::: moniker-end +:::image type="content" source="media/ALM_AC_ChangePriorities.png" alt-text="Screenshot that shows moving an item within a column."::: ## Do more tasks -In the following table, we've listed tasks and their associated articles, so you can do more with your Kanban board. +In the following table, we list tasks and their associated articles, so you can do more with your board. |Article |Task | |---------|---------| @@ -356,6 +223,5 @@ In the following table, we've listed tasks and their associated articles, so you - [Accelerate work with swimlanes](expedite-work.md) - [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md) -- [Enable live updates](live-updates.md) -- [Azure Boards FAQs](../faqs.yml) -- [REST API Boards reference](/rest/api/azure/devops/work/boards) +- [Explore Azure Boards FAQs](../faqs.yml) +- [Explore the REST API Boards reference](/rest/api/azure/devops/work/boards) diff --git a/docs/boards/boards/add-run-update-tests.md b/docs/boards/boards/add-run-update-tests.md index b677914cc4b..954fa1ce5b5 100644 --- a/docs/boards/boards/add-run-update-tests.md +++ b/docs/boards/boards/add-run-update-tests.md @@ -1,7 +1,7 @@ --- -title: Add, run, and update inline tests in Azure Boards and Azure DevOps +title: Add, run, and update inline tests titleSuffix: Azure Boards -description: Add, run, and update manual test cases on your Kanban board for lightweight tracking in Azure Boards and Azure DevOps. +description: Add, run, and update manual test cases on your board for lightweight tracking in Azure Boards and Azure DevOps. ms.custom: boards-kanban ms.service: azure-devops-boards ms.assetid: ED3CC394-EE6C-4E12-A2BC-F43A0EE17318 @@ -9,107 +9,77 @@ ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 09/10/2024 --- -# Add, run, and update inline tests in Azure Boards and Azure DevOps +# Add, run, and update inline tests [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Similar to [task checklists](add-task-checklists.md), you can quickly define inline tests, or a set of manual tests cases, for a backlog item from your Kanban board. Not only can you add tests, you can run them and update their status. If you're new to working with the Kanban board, see [Kanban overview](kanban-overview.md). If you're new to testing, see [Exploratory and manual testing scenarios and capabilities](../../test/overview.md). +Similar to [task checklists](add-task-checklists.md), you can quickly define inline tests, or a set of manual tests cases, for a backlog item from your board. Not only can you add tests, you can run them and update their status. If you're new to working with the board, see [Kanban board overview](kanban-overview.md). If you're new to testing, see [Exploratory and manual testing scenarios and capabilities](../../test/overview.md). -In this article, you'll learn: -> [!div class="checklist"] -> * How to add inline tests to a backlog item from your Kanban board -> * How to run tests and update the status of tests -> * How to expand or collapse inline tests -> * How to reorder or reparent inline tests +Screenshot showing Web portal, board with several inline tests defined. -Web portal, Kanban board with several inline tests defined - -Tests you create from the Kanban board are automatically linked to the user story or backlog item. +Tests that you create from the board automatically get linked to the user story or backlog item. ## Prerequisites ::: moniker range="azure-devops" -- You must connect to a project. If you don't have a project yet, [create one](../get-started/sign-up-invite-teammates.md). -- You must be added to a [team or project](../../organizations/security/add-users-team-project.md). -- To add work items and exercise all board features, you must be granted [**Basic** access or higher](../../organizations/security/access-levels.md). -- To view or modify work items, your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -- To view or run tests, you must have **Basic** access or higher. Users with **Stakeholder** access can't view or run tests. +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Access levels** |To add work items, view or run tests, and use all boards features: At least [**Basic** access](../../organizations/security/access-levels.md). Users with **Stakeholder** access can't view or run tests.| +|**Permissions**|- To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has these permissions. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md).| + ::: moniker-end ::: moniker range="< azure-devops" -- You must connect to a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -- You must be added to a [team or project](../../organizations/security/add-users-team-project.md). -- To add work items and exercise all board features, you must be granted [**Basic** access or higher](../../organizations/security/access-levels.md). -- To view or modify work items, your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -- To view or run tests, you must have **Basic** access or higher. Users with **Stakeholder** access can't view or run tests. - -::: moniker-end +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Access levels** |To add work items, view or run tests, and use all boards features: At least [**Basic** access](../../organizations/security/access-levels.md). Users with **Stakeholder** access can't view or run tests.| +|**Permissions**|- To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has these permissions. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md).| -## Open your Kanban board from the web portal +::: moniker-end -::: moniker range=">= azure-devops-2019" +## Open your board from the web portal -1. To view your Kanban board, open your project from a web browser and choose (1) **Work**, (2) **Boards**, and then (3) select the team's board from the selector. +1. To view your board, open your project from a web browser and choose (1) **Work**, (2) **Boards**, and then (3) select the team's board from the selector. - ![Open your Kanban board](media/quickstart/open-kanban-board-agile.png) + ![Screenshot showing Opening your board action.](media/quickstart/open-kanban-board-agile.png) To choose another team's board, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all team boards** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. > [!div class="mx-imgBorder"] - > ![Choose another team's board](media/quickstart/select-kanban-team-board.png) + > ![Screenshot showing selecting another team's board.](media/quickstart/select-kanban-team-board.png) > [!TIP] > Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to favorite a team board. Favorited artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorited icon) appear at the top of the team selector list. -::: moniker-end - -::: moniker range="tfs-2018" - -1. To view your Kanban board, open your (1) project from a web browser and choose (2) **Work**, (3) **Backlogs**, (4) **Stories**, and then (5) **Board**. - ![Taskboard, collapsed backlog items, cloud service](media/quickstart/open-kanban-board.png) - - If you don't see **Work**, your screen size may be reduced. Select the three dots (:::image type="icon" source="../../media/ellipses-reduced-screen-size.png" border="false":::, then choose **Work**, **Backlogs**, and then **Board**. - - ![Open Work when screen size is reduced](media/kanban-quickstart-reduced-screensize.png) - -1. To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Choose another team](../sprints/media/assign-items-sprint/team-selector-backlogs-standard.png) - -2. Your Kanban board displays. - - ![Kanban board, Agile template](media/kanban-basics-intro.png) - -::: moniker-end - ## Add inline tests 1. To start adding tests, open the menu for the work item. > [!div class="mx-imgBorder"] - > ![Open the context menu of a backlog item to add inline test case](media/i-test-add-test.png) + > ![Screenshot showing Open context menu of a backlog item to add inline test case.](media/i-test-add-test.png) - Adding inline tests is the same as adding test cases to a test suite. A default test plan and test suite are automatically created under which the manual test cases are grouped. + Adding inline tests is the same as adding test cases to a test suite. A default test plan and test suite automatically get created under which the manual test cases are grouped. - For example, a test suite is created for each user story, and all inline tests are added to that suite. Below, user story 152 is highlighted which has three manual tests defined with IDs of 153, 155, and 161. + For example, a test suite is created for each user story, and all inline tests get added to that suite. In the following example, test suite 152 is highlighted which has three manual tests defined with IDs of 280, 281, and 282. - ![Inline test cases get added to test suites and test plans](media/i-test-plan-suite.png) + ![Screenshot showing Inline test cases get added to test suites and test plans.](media/i-test-plan-suite.png) - To learn more about test plans and test suites, see [Plan your tests](../../test/create-a-test-plan.md). + For more information, see [Plan your tests](../../test/create-a-test-plan.md). -2. If you have many tests to add, keep entering each title and select Enter. +2. If you have many tests to add, keep entering each title and select **Enter**. - Work item with several test cases added + Screenshot showing Work item with several test cases added. To add details to the test case, open it. You can select the title, double-click the inline item, or open the context menu and choose Open. - Open test case form from Kanban board + Screenshot showing opening a test case form from board. See [Create manual tests](../../test/create-test-cases.md) to learn more about defining tests. @@ -119,56 +89,54 @@ Before running the test, you must add details. Run the test by selecting ![Run icon](../media/icons/run_query.png) Run test from the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions menu for the inline test. -Run a test - -Microsoft Test Runner starts in a new browser instance. For details on running a test, see [Run manual tests](../../test/run-manual-tests.md). +Screenshot showing running a test. +Microsoft Test Runner starts in a new browser instance. For more information, see [Run manual tests](../../test/run-manual-tests.md). ## Update the status of an inline test from the action menu You can update the status of the test from the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions menu. -Check tasks that are complete +Screenshot showing completed tasks. -Updating the status of tests enable you to track test results. - -[Why doesn't the Kanban board show the status for test suites and plans already created in **Test**?](#test-status-kanban) +Updating the status of tests lets you track test results. ## Expand or collapse inline tests -Upon first opening the Kanban board, you'll see an unexpanded view of checklists. - -![Inline tests collapsed](media/i-test-open-board-collapsed-tests.png) +When you first open a board, you're presented with an unexpanded view of checklists. -Select the inline test summary to expand a collapsed set of tests. Select the same summary to collapse an expanded list. +![Screenshot showing Inline tests collapsed.](media/i-test-open-board-collapsed-tests.png) -![Inline tests expanded](media/i-test-expanded-test-list.png) +Hover over the inline test summary to show a test summary. -## Copy or reparent a test +:::image type="content" source="media/hover-test-summary.png" alt-text="Screenshot showing test summary upon hover."::: -To reparent a test, drag and drop the test onto a different user story. +Select the inline test summary to expand a collapsed set of tests. Select the same summary to collapse an expanded list. -![Drag tests to reassign them to a different user story ](media/i-test-drag-reparent.png) +![Screenshot showing Inline tests expanded.](media/i-test-expanded-test-list.png) -This action automatically changes the linked relationship of the test to point to the new user story. +## Copy or reparent a test -To create a copy of a test to add to a different user story, select the test, press the CTRL key, and then drag and drop the test onto the card of the user story. +To reparent a test, drag and drop the test to a different user story. +![Screenshot showing Drag tests to reassign them to a different user story.](media/i-test-drag-reparent.png) -## Related articles +This action automatically changes the linked relationship of the test and points to the new user story. -Use inline tests for lightweight traceability and to manage manual tests for user stories or other backlog items that they support. To learn more about test case management, see [Create manual tests](../../test/create-test-cases.md). +To create a copy of a test to add to a different user story, select the test, select the CTRL key, and then drag and drop the test onto the user story card. -If you find that you don't use this feature, you can disable it from the [common configurations dialog](../../boards/boards/customize-cards.md#annotations). +## Link a test case to a work item -Other ways you can quickly add linked items and objects to user stories from the Kanban board: -- [Add tasks or child items as checklists](add-task-checklists.md) -- [Create a new branch, drive Git development](../backlogs/connect-work-items-to-git-dev-ops.md) +When you link a test case to a work item using the "Tested By" link type, the board reflects the test status of the linked test case. However, if the requirement-based suite has multiple configurations, the board only shows the test outcome for the default configuration. -To start web-based exploratory testing for a user story, you need to install the [Test & Feedback Marketplace extension](https://marketplace.visualstudio.com/items?itemName=ms.vss-exploratorytesting-web). For more information, see [Install the Test & Feedback extension](../../test/perform-exploratory-tests.md). +## Next steps - +> [!div class="nextstepaction"] +> [Install the Test & Feedback extension](../../test/perform-exploratory-tests.md) -### Test status in the Kanban board +## Related articles -Test integration with the Kanban board makes it easy for teams to get started with manual testing and then take advantage of the full testing capabilities in Test Manager later, when required. When test cases are created from the Kanban board and updated afterwards in Test Manager, or the other way around, when users create requirement-based suites with Test Manager and update them in Test Manager, the Kanban board shows the correct status. However, the Test status in Kanban board doesn't work if the requirement-based suite has more than one configuration assigned to it. In such scenario, the Kanban board only shows the test outcome for the default configuration. As such, it's recommended to use Test Manager to manage/track the testing progress across multiple configurations. +- [Create manual tests](../../test/create-test-cases.md). +- [Disable this feature from the common configurations dialog](../../boards/boards/customize-cards.md). +- [Add tasks or child items as checklists](add-task-checklists.md) +- [Create a new branch, drive Git development](../backlogs/connect-work-items-to-git-dev-ops.md) diff --git a/docs/boards/boards/add-task-checklists.md b/docs/boards/boards/add-task-checklists.md index ce276604ed0..61647a201d1 100644 --- a/docs/boards/boards/add-task-checklists.md +++ b/docs/boards/boards/add-task-checklists.md @@ -1,7 +1,7 @@ --- title: Add tasks or other child work items to checklists titleSuffix: Azure Boards -description: Add tasks, subtasks, to do lists, bugs, or other child work items as checklists to your Kanban board for lightweight tracking in Azure Board and Azure DevOps. +description: Add tasks, subtasks, to do lists, bugs, or other child work items as checklists to your board for lightweight tracking in Azure Board and Azure DevOps. ms.custom: boards-kanban ms.service: azure-devops-boards ms.assetid: D4CE68D6-8056-4CB7-ACFA-1FCD05223040 @@ -9,128 +9,91 @@ ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 07/26/2022 +ms.date: 04/29/2024 --- # Add tasks or child items as checklist items [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +Your board in Azure DevOps lets you visualize your team’s tasks, track progress, and manage work items efficiently. This article provides step-by-step instructions on how to add task checklists to items on your board, enhancing your team’s productivity and transparency. -Many teams find Kanban boards ideal for tracking work. Kanban boards are ideal because they support visualization the flow of work that is in progress. It also allows team members to quickly add new items and update work item status in a Kanban board. If you're new to working with the Kanban board, see [Kanban overview](kanban-overview.md). +The following image shows a representation of various tasks and bugs in progress. Some are still pending, while others are marked as completed. By incorporating the Issue work item type into your Iteration backlog, you can seamlessly add issues as checklists -With checklists or to do lists, you continue to enjoy lightweight tracking. You gain visibility into which tasks, bugs, or other child items are in progress or completed. For example, here we show several tasks and bugs for work in progress, both yet to do and those items marked as completed. By adding the Issue work item type to the Iteration backlog, issues can be added as checklists. -::: moniker range=">= azure-devops-2019" -:::image type="content" source="media/checklists/board-checklists.png" alt-text="Screenshot of product-level Kanban board with three work items showing child lists"::: -::: moniker-end -::: moniker range="tfs-2018" -Kanban board with several task checklists defined -::: moniker-end +:::image type="content" source="media/checklists/board-checklists.png" alt-text="Screenshot of product-level board with three work items showing child lists"::: + +## Learn checklist features -In this article, you'll learn: -> [!div class="checklist"] -> * Summary of checklist features -> * How to add checklist items from your Kanban board -> * How to mark a checklist item as done -> * How to expand or collapse a checklist -> * How to reorder and reparent checklist items or reassign them to a sprint - -## Overview of checklist features - -Checklists are a feature of all Kanban boards, both product and portfolio backlog levels. - -- All Kanban board levels support checklists. For a view of default backlog hierarchies, see [Plan and track work](../get-started/plan-track-work.md). -- Adding a checklist item automatically adds a parent-child link between the parent work item and the checklist item. -- For the product-level board: - - When **Bugs are managed with tasks**, they're available to add and track within a checklist. - - When **Bugs are managed with requirements**, you can add tasks to bugs that are tracked on the board. Teams make this choice via Board settings, [**Working with bugs**](../../organizations/settings/show-bugs-on-backlog.md). -- Marking any checklist item as "done" moves the work item **State** to done, closed, or completed. -- Teams can remove select checklist features by disabling them on the [**Annotations** tab of the Board settings](customize-cards.md#annotations). -- Tasks or other child items that you create from the Kanban board are automatically assigned to the sprint/iteration path of the parent work item under which you define them. -- Any work item type added to the backlog hierarchy is available to add using the checklist feature. - To add work item types to track as checklists, add them to the next-lower hierarchical backlog. To learn how, see [Customize your backlogs or boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md) or [Process configuration XML element reference (On-premises XML process)](../../reference/xml/process-configuration-xml-element.md). +Make use of the following features for checklists. + +- Enable **checklists on all boards** (product and portfolio levels). +- **Create parent-child links** by adding checklist items to work items. +- For product-level boards: + - **Manage Bugs with tasks**: [Add and track them within checklists](../../organizations/settings/show-bugs-on-backlog.md). + - **Manage Bugs with requirements**: Add tasks to bugs tracked on the board. +- **Mark checklist items as “done”** to update work item states. +- **Customize checklist features** in the [Board settings](customize-cards.md). +- **Automatically assign child items** to the sprint/iteration path of parent work items. +- **Add any work item type** using the checklist feature. +- To track work item types as checklists, **add them to the next-lower hierarchical backlog**. For more information, see [Customize backlogs/boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md) or [Process configuration XML element reference (on-premises XML process)](../../reference/xml/process-configuration-xml-element.md). > [!TIP] -> If you find that you don't use this feature, you can disable it from the [common configurations dialog](customize-cards.md#annotations). +> You can disable it from the [common configurations dialog](customize-cards.md). +## Prerequisites [!INCLUDE [temp](../includes/prerequisites-kanban.md)] -[!INCLUDE [temp](../includes/open-kanban-board.md)] +[!INCLUDE [temp](../includes/open-kanban-board.md)] ## Add one or more child items to a checklist -In this example, tasks are added to the product Kanban board using the checklist feature. You can use the same procedures to add any other supported checklist item from your board. +In the following example, tasks get added to an item on the product board using the checklist feature. You can use the same procedures to add any other supported checklist item from your board. + +1. From your board, select an item and select :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **Work item actions** > **+ Add Task**. If you already have a work item open, select **Add link** > **New item**. For more information, see [Link work items to objects](../backlogs/add-link.md). -1. To start adding tasks, open the menu for the work item. - ::: moniker range=">=azure-devops-2019" :::image type="content" source="media/checklists/add-task-menu.png" alt-text="Screenshot of open the context menu of work item to add a task."::: - ::: moniker-end - ::: moniker range="tfs-2018" - Open the context menu of a backlog item to add a task - ::: moniker-end - -2. If you have many tasks to add, keep entering their titles and choose Enter after each title. - ::: moniker range=">= azure-devops-2019" - :::image type="content" source="media/checklists/four-tasks-added.png" alt-text="Screenshot of added tasks."::: - ::: moniker-end - ::: moniker range="tfs-2018" - Work item with several tasks added - ::: moniker-end - -3. If you have details you want to add about a task, open the item by choosing the title. - :::image type="content" source="media/checklists/open-task.png" alt-text="Screenshot of opening a task."::: -> [!NOTE] -> Tasks that you create from the Kanban board appear on your sprint Taskboard. Also, tasks that you create from the [sprint backlog](../sprints/assign-work-sprint.md) or [Taskboard](../sprints/task-board.md) appear within tasks checklists on the Kanban board. +2. If you have many tasks to add, keep entering their titles and select **Enter** after each title. + + :::image type="content" source="media/checklists/four-tasks-added.png" alt-text="Screenshot shows four added tasks, added one after the other."::: + +3. Select the task **title** to add details. + + :::image type="content" source="media/checklists/open-task.png" alt-text="Screenshot shows opening a task by selecting the title."::: +> [!NOTE] +> Tasks that you create from your board appear on your sprint Taskboard. Also, tasks that you create from the [sprint backlog](../sprints/assign-work-sprint.md) or [Taskboard](../sprints/task-board.md) appear within tasks checklists on your board. ## Mark a checklist item as done When you complete a task or other checklist item, choose the checkbox to change its status to Done, Closed, or Completed. -::: moniker range=">= azure-devops-2019" -:::image type="content" source="media/checklists/board-checklists.png" alt-text="Screenshot of product-level Kanban board showing several done child items"::: -::: moniker-end -::: moniker range="tfs-2018" -Check tasks that are complete -::: moniker-end +:::image type="content" source="media/checklists/board-checklists.png" alt-text="Screenshot of product-level board showing several done child items"::: The **State** of the work item is updated from *Active* to *Closed* for projects based on an Agile or CMMI process, and from *To Do* to *Done* for projects based on a Scrum or Basic process. > [!TIP] -> No matter the number of workflow states a checklist item has, checking it moves it to its closed or completed state. +> Regardless of the number of workflow states a checklist item might have, marking it as checked transitions it to its closed or completed state. -## Expand or collapse a checklist on a Kanban board +## Expand or collapse a checklist on a board -Upon first opening the Kanban board, you'll see an unexpanded view of checklists. Choose the checklist summary to expand a collapsed checklist. Choose the same summary to collapse an expanded checklist. +When you open a board, there's an unexpanded view of checklists. Select the checklist summary to expand and collapse it. -::: moniker range=">= azure-devops-2019" :::image type="content" source="media/checklists/unexpanded-checklists.png" alt-text="Screenshot of unexpanded checklist"::: -::: moniker-end -::: moniker range="tfs-2018" -Expand task checklist for a work item -::: moniker-end - ## Reorder tasks, reparent tasks, or reassign tasks to a sprint -You can drag a task within a work item to reorder it. Or, you can drag the task to another work item on the Kanban board to reparent it. - -::: moniker range=">= azure-devops-2019" -![Drag tasks to reorder them.](../get-started/media/plan-track-work/reorder-task.png) -::: moniker-end -::: moniker range="tfs-2018" -![Drag tasks to reorder them within the list](media/task-checklist-reorder-tasks.png) -::: moniker-end +You can drag a task within a work item to reorder it. Or, you can drag the task to another work item on the board to reparent it. +![Screenshot show dragging tasks to reorder them.](../get-started/media/plan-track-work/reorder-task.png) > [!NOTE] > Users with **Stakeholder** access can't drag-and-drop tasks or reorder and reparent tasks. -Tasks or other child items you add as checklists are automatically assigned to the **Iteration Path** of their parent work item. To reassign a checklist item to a different sprint, you must open the item and change its **Iteration Path**. Or, open the sprint backlogs where it's currently defined and drag it to the new sprint using the Planning pane. For more information, see [Assign backlog items to a sprint](../sprints/assign-work-sprint.md). +Tasks or other child items you add as checklists are automatically assigned to the **Iteration Path** of their parent work item. To reassign a checklist item to a different sprint, you must open the item and change its **Iteration Path**. Or, open the sprint backlogs and drag it to the new sprint using the Planning pane. For more information, see [Assign backlog items to a sprint](../sprints/assign-work-sprint.md). - + ::: moniker range="azure-devops" @@ -139,25 +102,19 @@ Tasks or other child items you add as checklists are automatically assigned to t Checklist items show the avatars of those team members assigned to the item. You can view the avatar assignment of checklist items, or reassign a checklist item by choosing the item's …**Work items action menu** and selecting **Assigned to**. > [!NOTE] -> Avatar images and the **Assign to** menu option requires you to enable the **New Boards Hub** preview feature. To enable this feature, see [Manage or enable features](../../project/navigation/preview-features.md). +> Avatar images and the **Assign to** menu option require the **New Boards Hub** feature, which is enabled by default. For more information, see [Manage or enable features](../../project/navigation/preview-features.md). :::image type="content" source="media/checklists/checklist-actions-menu.png" alt-text="Screenshot of Boards, list of tasks showing avatars, and checklist of work items action menu."::: ::: moniker-end +## Configure your board -## Configure the Kanban board - -To configure or change the layout of the Kanban board, see [Customize your boards](../configure-customize.md). +To configure or change the layout of your board, see [Customize your boards](../configure-customize.md). +## Related content -## Related articles - -- [Kanban board features and epics](kanban-epics-features-stories.md) -- [Interactively filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md) +- [Learn about board features and epics](kanban-epics-features-stories.md) +- [Filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md) - [Add, run, update manual tests](add-run-update-tests.md) -- [Create a new branch, drive Git development](../backlogs/connect-work-items-to-git-dev-ops.md) -- [Use Kanban board controls](kanban-overview.md#use-kanban-board-controls.md) - -### REST API resources -To programmatically create work items, see the [REST API, Work Items reference](/rest/api/azure/devops/wit/work-items/create). +- [Use the REST API, Work Items reference](/rest/api/azure/devops/wit/work-items/create) diff --git a/docs/boards/boards/customize-cards.md b/docs/boards/boards/customize-cards.md index 923ba4b1d4d..a4d8480cb6c 100644 --- a/docs/boards/boards/customize-cards.md +++ b/docs/boards/boards/customize-cards.md @@ -1,8 +1,8 @@ --- -title: Customize cards on a Kanban board +title: Customize cards on a board titleSuffix: Azure Boards -description: Learn how to customize cards to provide at-a-glance information of interest to your team in Azure Boards and Azure DevOps. -ms.custom: boards-kanban, contperf-fy21q3, engagement-fy23 +description: Learn how to customize cards to provide at-a-glance information of interest to your team in Azure Boards and Azure DevOps. +ms.custom: boards-kanban, engagement-fy23 ms.service: azure-devops-boards ms.assetid: 951A73EA-7411-4A2A-B3F0-ACBBC7EFC68F ms.author: chcomley @@ -12,36 +12,31 @@ monikerRange: '<= azure-devops' ms.date: 06/05/2023 --- -# Customize cards on a Kanban board +# Customize cards on a board [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The Kanban board presents work items in the form of cards, where each card represents a work item that facilitates information sharing, progress tracking, and task assignment. These cards provide quick insights for you and your team. You can update a field on a card without having to open the corresponding work item. You can also apply style rules to highlight specific cards and tasks based on your set criteria. - -If you're new to working with the Kanban board, see [Kanban overview](../../boards/boards/kanban-overview.md). +A board presents work items in the form of cards, where each card represents a work item that facilitates information sharing, progress tracking, and task assignment. These cards provide quick insights for you and your team. You can update a field on a card without having to open the corresponding work item. You can also apply style rules to highlight specific cards and tasks based on your set criteria. > [!NOTE] -> This article addresses customization of a Kanban board. For information on customizing a Taskboard, see [Customize sprint Taskboards](../sprints/customize-taskboard.md). +> This article addresses customization of a board. For information on customizing a Taskboard, see [Customize sprint Taskboards](../sprints/customize-taskboard.md). + +## Prerequisites -[!INCLUDE [temp](../includes/prerequisites-team-settings.md)] -- See the section, [Card customization sequence](#card-customization-sequence) +| Category | Requirements | +|--------------|-------------| +|**Access levels** | At least [**Basic**](../../organizations/security/access-levels.md) access.| +|**Permissions** | To configure team settings: Member of the **Project Administrators** security group or [**Team Administrator** role](../../organizations/settings/add-team-administrator.md). For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md).| +|**Tasks (optional)**| See the section, [Card customization sequence](#card-customization-sequence)| ## Card customization options -You can show fields on cards based on what your team frequently refers to or updates when using the Kanban board. You can also add fields with information that you can use to filter the board. +You can show fields on cards based on what your team frequently refers to or updates when using the board. You can also add fields with information that you can use to filter the board. -::: moniker range=">= azure-devops-2019" > [!NOTE] -> You can customize a work item type which is different than customizing the card displayed on the Kanban board. You customize a work item type by adding fields, changing the workflow, adding custom rules and more. You can also add custom work item types and custom backlog levels. For more information, see [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md). -::: moniker-end +> You can customize a work item type which is different than customizing the card displayed on the board. You customize a work item type by adding fields, changing the workflow, adding custom rules and more. You can also add custom work item types and custom backlog levels. For more information, see [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md). -::: moniker range="< azure-devops-2019" - -> [!NOTE] -> You can customize a work item type which is different than customizing the card displayed on the Kanban board. You customize a work item type by adding fields, changing the workflow, adding custom rules and more. You can also add custom work item types and custom backlog levels. For more information, see [Customize the On-premises XML process model](../../reference/on-premises-xml-process-model.md). -::: moniker-end - -Within the [Settings dialog for the Kanban board](#open-your-kanban-board-settings), you have the following customization options. +Within the [Settings dialog for a board](#open-your-board-settings), you have the following customization options. ::: moniker range=">= azure-devops-2020" |Setting |Customization action | @@ -54,23 +49,12 @@ Within the [Settings dialog for the Kanban board](#open-your-kanban-board-settin |**[Card reordering](#reorder-cards)** | Choose expected behavior when reordering cards on the board. | ::: moniker-end -::: moniker range="<= azure-devops-2019" -|Setting |Customization action | -|---------|---------| -|**[Fields](#fields)** | Add or remove fields from cards. | -|**[Styles](#style-rule)** | Add styling rules to change card color and title style based on field criteria. | -|**[Tag colors](#assign-tag-colors)** | Specify a tag color and enable or disable a tag color. | -|**[Annotations](#enable-or-disable-annotations)** | Enable or disable annotations to appear on cards. | -|**[Tests](#configure-inline-tests)** |Configure how you want tests to appear and behave on the cards. | -|**[Card reordering](#reorder-cards)** | Choose expected behavior when reordering cards on the board. | -::: moniker-end - > [!NOTE] -> Each team can customize the cards for their Kanban board. Board settings are not inherited from other teams that they may share portions of area paths. +> Each team can customize the cards for their board. Board settings are not inherited from other teams that they may share portions of area paths. ## Card customization sequence -Before you configure the cards, make sure the following tasks are complete, or you might need to revisit your configuration. +Before you configure the cards, ensure the following tasks are complete, or you might need to revisit your configuration. **Process Administrator**: 1. Add custom work item types that you want to appear on your backlog or board. For more information, see [Add and manage work item types](../../organizations/settings/work/customize-process-work-item-type.md). @@ -82,16 +66,14 @@ Before you configure the cards, make sure the following tasks are complete, or y 1. [Add any tags](../queries/add-tags-to-work-items.md) you want to customize on cards to work items. 1. Meet with your team and determine which annotations should appear on cards and how they want to configure inline tests. -## Open your Kanban board settings - -If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the Kanban board. +## Open your board settings -You can customize cards that appear on the Kanban board for your product backlog or portfolio backlog such as features and epics. You follow similar steps, however you start from the [corresponding portfolio backlog](../../boards/backlogs/define-features-epics.md). +If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the board. -::: moniker range=">= azure-devops-2019" +You can customize cards that appear on the board for your product backlog or portfolio backlog such as features and epics. You follow similar steps, however you start from the [corresponding portfolio backlog](../../boards/backlogs/define-features-epics.md). 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. [Open your Kanban board](kanban-quickstart.md). +2. [Open your board](kanban-quickstart.md). 3. Choose the backlog level that you want to customize. > [!div class="mx-imgBorder"] @@ -102,36 +84,17 @@ You can customize cards that appear on the Kanban board for your product backlog > [!div class="mx-imgBorder"] > ![Screenshot showing Open board settings for a team, vert nav.](../../organizations/settings/media/configure-team/open-board-settings.png) -::: moniker-end - -::: moniker range="tfs-2018" - -1. [Open your Kanban board](kanban-quickstart.md). - -2. Choose the backlog level you want to customize. - -3. Choose ![settings icon](../../media/icons/team-settings-gear-icon.png) to open the common configuration settings dialog for the Kanban board. - - :::image type="content" source="media/add-columns-open-settings-ts.png" alt-text="Screenshot showing Kanban board, open common configuration settings."::: - -::: moniker-end ## Choose which fields appear on cards -You can edit a card field from the Kanban board, except for read-only fields like the *Change By* and *Changed Date*. This quick update feature is useful when you need to update many work items at once. +You can edit a card field from the board, except for read-only fields like the *Change By* and *Changed Date*. This quick update feature is useful when you need to update many work items at once. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Do the following steps to update fields. To add a custom field, you must first [add it to the process used to customize the project](../../organizations/settings/work/add-custom-field.md). ::: moniker-end -::: moniker range="< azure-devops-2019" -You can determine which fields appear on each card type. To add a custom field, you must first [add it to the work item type definition](../../reference/add-modify-field.md). -::: moniker-end - -::: moniker range=">= azure-devops-2019" - 1. From the board settings page, choose **Fields** and then choose a work item type to see all the settings that you can modify. Your initial column settings appear similar to the following image. Your choices vary based on the [process](../../boards/work-items/guidance/choose-process.md) used to create your project and whether your team has chosen to [treat bugs like requirements or like tasks](../../organizations/settings/show-bugs-on-backlog.md). @@ -148,33 +111,11 @@ You can determine which fields appear on each card type. To add a custom field, 5. When you're done, select **Save**. -::: moniker-end - ::: moniker range=">= azure-devops-2020" > [!NOTE] > To show the **Title** of the parent work item, choose the **Parent** field. Choosing the **Parent** title from a card opens the parent work item. To change the parent work item, open the child work item and remove the link and add a different parent work item. You can filter your board based on parent work items, whether the **Parent** field is added to cards or not. ::: moniker-end -::: moniker range="tfs-2018" - -1. From the board settings page, choose **Fields** and then a work item type to see all the settings you can modify. Your initial column settings look something like this. - - Here we choose User Story. Your choices vary based on the [process](../../boards/work-items/guidance/choose-process.md) used to create your project and whether your team has chosen to [treat bugs like requirements or like tasks](../../organizations/settings/show-bugs-on-backlog.md). - - :::image type="content" source="media/customize-cards/settings-fields-142.png" alt-text="Screenshot showing Settings,Fields, User Story tab (Agile process)."::: - -2. Enter a check mark in the box next to the fields that you want to have appear on the board. - - If you want work estimates to show, check **Show Effort**, which corresponds to the following fields: Effort ([Scrum](../../boards/work-items/guidance/scrum-process.md)), Story Points ([Agile](../../boards/work-items/guidance/agile-process.md)), and Size ([CMMI](../../boards/work-items/guidance/cmmi-process.md)). - -3. To add a field, choose the :::image type="icon" source="../media/icons/green_plus_icon.png" border="false"::: plus icon and enter the name of a field you want to add. - -4. To remove a field, choose the :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: delete icon next to the field. - -5. When you're done, select **Save**. - -::: moniker-end - @@ -183,7 +124,7 @@ You can determine which fields appear on each card type. To add a custom field, With styling rules, you can cause cards to change color when their corresponding work items meet criteria that you set. Here, we highlight severity 1 bugs by having the cards display as yellow. -::: moniker range=">= tfs-2018" +::: moniker range="<=azure-devops" ![Screenshot showing styling rule applied to bugs with Severity=1.](media/customize-cards/card-style-s155-solo.png) ::: moniker-end @@ -204,9 +145,9 @@ Which rules should you apply to highlight work items? Here are a few examples an > |Contains specific tag | `Tags Contain RTM` | > |Blocked tasks (Scrum process only) | `Blocked = Yes` | -You can apply style rules to change the color of cards on Kanban boards and Taskboards. +You can apply style rules to change the color of cards on boards and Taskboards. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. From the board settings page, select **Styles** to specify a style rule. 2. Select + **Add styling rule**. Select the color to apply to the card and define the criteria for the style rule. @@ -215,13 +156,13 @@ You can apply style rules to change the color of cards on Kanban boards and Task :::image type="content" source="../sprints/media/customize/taskboard-styles-priority.png" alt-text="Screenshot of the Settings, Styles dialog."::: -> [!TIP] -> Note the following information about style rules: - - The criteria you specify works in a similar fashion as when [constructing a query](../../boards/queries/using-queries.md). - - All clauses are considered AND clauses, grouping clauses isn't supported. - - Card rules apply to all work items that meet the rule criteria. - - Rule color applies to work items based on the order in which rules are listed. If you add more than one style rule, make sure that you move them in the order of most importance. Drag them into the order you want them applied. - - You can quickly enable and disable a style rule. + > [!TIP] + > Note the following information about style rules: + >- The criteria you specify works in a similar fashion as when [constructing a query](../../boards/queries/using-queries.md). + >- All clauses are considered AND clauses, grouping clauses isn't supported. + >- Card rules apply to all work items that meet the rule criteria. + >- Rule color applies to work items based on the order in which rules are listed. If you add more than one style rule, make sure that you move them in the order of most importance. Drag them into the order you want them applied. + >- You can quickly enable and disable a style rule. In the following example, we add a *Stale tasks* rule, which highlights tasks that haven't changed in the last five days. @@ -232,37 +173,13 @@ You can apply style rules to change the color of cards on Kanban boards and Task 4. When you're done, select **Save**. ::: moniker-end -::: moniker range="tfs-2018" -1. From the Settings dialog, choose **Styles** to specify a style rule. Choose the :::image type="icon" source="../../media/icons/green_plus_icon.png" border="false"::: plus icon to add a style. Select the color to apply to the card and define the criteria for the style rule. - - In this example, we show the **Styles** dialog for the dashboard. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing Settings, Styles dialog.](../sprints/media/customize/taskboard-styles-priority.png) - - Follow these rules when creating and ordering your style rules: - - The criteria you specify works in a similar fashion as when [constructing a query](../../boards/queries/using-queries.md) - - All clauses are considered AND clauses, grouping clauses isn't supported - - Card rules apply to all work items that meet the rule criteria - - Rule color applies to work items based on the order in which rules are listed. If you add more than one style rule, make sure that you move them in the order of most importance. Drag them into the order you want them applied. - - You can quickly enable and disable a style rule. - - Here we add a Stale tasks rule that highlights tasks that haven't changed in the last five days. - - ![Screenshot showing Taskboard, Style dialog, example style rule.](../sprints/media/customize/task-board-card-style-rule-stale-tasks.png) - -1. To copy or delete a style rule, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select **Clone** or **Delete**. - -2. When you're done, choose **Save**. -::: moniker-end - ## Assign tag colors Before you set tag colors, [add tags to backlog items](../../boards/queries/add-tags-to-work-items.md) that you want to highlight with color. 1. From the Settings dialog, select **Tag colors**, and then **+ Add tag color**. Then, select the tag and the color you want to appear on the cards. - :::image type="content" source="media/customize-cards/settings-tag-colors.png" alt-text="Screenshot showing Settings, Tag colors dialog (Kanban)."::: + :::image type="content" source="media/customize-cards/settings-tag-colors.png" alt-text="Screenshot showing Settings, Tag colors dialog."::: > [!TIP] > If tags don't display on the cards, select **Fields** and make sure that you've checked **Show Tags**. @@ -273,32 +190,24 @@ Before you set tag colors, [add tags to backlog items](../../boards/queries/add- All applicable annotations for the selected board are enabled by default. These annotations include all work item types added to the next level backlog, GitHub, and Tests. Disable any unused annotations or ones that you want to restrict for a specific backlog level. -When you disable an annotation, you also disable the feature to add the associated object from the Kanban board. For example, if you disable the Tests annotation, you disable the ability to add tests from the currently selected Kanban board. +When you disable an annotation, you also disable the feature to add the associated object from the board. For example, if you disable the Tests annotation, you disable the ability to add tests from the currently selected board. Complete the following steps to manage annotations. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -1. From your board settings page, select **Annotations** . +1. From your board settings page, select **Annotations**. 2. Check those annotations that you want enabled. For example, to enable tasks but disable tests, check the following boxes. - :::image type="content" source="media/customize-cards/annotate-settings-154.png" alt-text="Screenshot showing Kanban board, Settings dialog, Annotations tab."::: + :::image type="content" source="media/customize-cards/annotate-settings-154.png" alt-text="Screenshot showing a board, Settings dialog, Annotations tab."::: > [!NOTE] - > GitHub annotations requires Azure DevOps Server 2019 Update 1 or later version. For more information, see [Link GitHub commits, pull requests, and issues to work items](../github/link-to-from-github.md). + > GitHub annotations requires Azure DevOps Server 2019 Update 1 or later version. For more information, see [Link GitHub commits, pull requests, branches, and issues to work items](../github/link-to-from-github.md). 3. When you're done, select **Save**. ::: moniker-end -::: moniker range="tfs-2018" -1. Open the Settings dialog for the Kanban board you want to customize and select **Annotations** -2. Check those annotations that you want enabled. For example, to enable tasks but disable tests, check the following boxes. - :::image type="content" source="media/customize-cards/annotate-settings.png" alt-text="Screenshot showing Kanban board, Settings dialog, Annotations tab."::: - -3. When you're done, select **Save**. -::: moniker-end - As shown in the following examples, the **Task** and **Test** annotations indicate that two each of tasks and tests are defined for the work item. > [!div class="mx-tdBreakAll"] @@ -308,16 +217,10 @@ As shown in the following examples, the **Task** and **Test** annotations indica For more information, see [Add tasks or child items as checklists](../../boards/boards/add-task-checklists.md) and [Add, run, and update inline tests](../../boards/boards/add-run-update-tests.md). -::: moniker range="azure-devops-2019" -> [!NOTE] -> If your project collection uses the On-premises XML process model to customize work tracking, you can enable work item types that you add to the Task Category to appear as a checklist on your product Kanban board. To learn how, see [Set up your backlogs and boards, Customize your Kanban Board checklist items](../backlogs/set-up-your-backlog.md#customize-checklist-2019). -::: moniker-end - ## Configure inline tests -You can control the test plan where you create inline tests through the Kanban board. Choose to create a new test plan for each new test that you add or add all new tests to a selected test plan. +You can control the test plan where you create inline tests through your board. Choose to create a new test plan for each new test that you add or add all new tests to a selected test plan. -::: moniker range=">= azure-devops-2019" 1. From the board settings page (product backlog only), choose **Annotations**. [Make sure that **Test** annotation is enabled](#enable-or-disable-annotations), a requirement to configure inline tests. 2. Select **Tests**, and then choose the options you want. Choose an existing test plan from the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon results. @@ -330,29 +233,16 @@ You can control the test plan where you create inline tests through the Kanban b > To avoid the redundancies that can occur under this scenario, you should choose **Show same outcome of the tests in multiple suites under the same plan** checkbox. When checked, the Test Points of the same Test Case and configuration, shows the same latest outcome. When the tester runs any one test, the output is synced with all other test points (which are of the same Test Case work item and same configuration) in the Test Plans. The tester can use the outcome and choose not to run the test again. 3. Select **Save**. -::: moniker-end - -::: moniker range="tfs-2018" -1. Open the Settings dialog for the Kanban board (product backlog only) you want to customize. - -2. Choose **Annotations** and make sure that **Test** annotation is enabled, which is a requirement to configure inline tests. - -3. Choose **Tests**, and then choose the options you want. To select a test plan, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select one test plan from the query provided. - - ![Screenshot of Settings dialog, Tests tab (Kanban).](media/c-cards-test-settings.png) - -4. Save your changes. -::: moniker-end ### Open the test plan, test suite from a card -From a card on the Kanban board, you can go to the underlying test plan and test suite under which the tests are created. Choose the :::image type="icon" source="../../media/icons/open-icon.png" border="false"::: open icon to open another browser tab showing **Test** and associated test plan and test suite that controls the inline tests. +From a card on the board, you can go to the underlying test plan and test suite under which the tests are created. Choose the :::image type="icon" source="../../media/icons/open-icon.png" border="false"::: open icon to open another browser tab showing **Test** and associated test plan and test suite that controls the inline tests. :::image type="content" source="media/c-cards-navigate-to-test-suite.png" alt-text="Screenshot showing Test selection from card on board."::: ## Reorder cards -You can drag any work item to any column or swimlane on the Kanban board. You can even change the order of items as you move a card to a new column. +You can drag any work item to any column or swimlane on a board. You can even change the order of items as you move a card to a new column. ![GIF Screenshot showing reordering cards while changing columns.](media/8_7_02.gif) @@ -366,10 +256,10 @@ In addition to the dynamic card reordering, you can also move a card to a specif ::: moniker range=">= azure-devops-2022" ### Move a card to a specific column position -You can reorder the work items within a Kanban board column by choosing …**Work items action menu**, selecting **Move to position**, and then specifying a value in the dialog. +You can reorder the work items within a board column by choosing …**Work items action menu**, selecting **Move to position**, and then specifying a value in the dialog. > [!NOTE] -> The **Move to column position** feature requires you to enable the **New Boards Hub** preview feature. To enable this feature, see [Manage or enable features](../../project/navigation/preview-features.md). +> The **Move to column position** feature requires the **New Boards Hub** feature, which is enabled by default. For more information, see [Manage or enable features](../../project/navigation/preview-features.md). Specify a value within the range listed, which corresponds to the number of items currently in the column. @@ -378,63 +268,27 @@ Specify a value within the range listed, which corresponds to the number of item ### Set the team preference for reordering cards -If you want to preserve the backlog priority when you move a card to a new column, you can change the Kanban board card reordering setting for your team. +If you want to preserve the backlog priority when you move a card to a new column, you can change the board card reordering setting for your team. -::: moniker range=">= azure-devops-2019" -1. [Open your Kanban board](kanban-quickstart.md). If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the Kanban board. +1. [Open your board](kanban-quickstart.md). If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the board. -1. Select the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board and set general team settings. +2. Select the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board and set general team settings. > [!div class="mx-imgBorder"] > ![Screenshot of open board settings for a team, vert nav.](../../organizations/settings/media/configure-team/open-board-settings.png) -1. Select **Card reordering** and select from the two reordering behaviors listed. +3. Select **Card reordering** and select from the two reordering behaviors listed. > [!div class="mx-imgBorder"] > ![Screenshot of Settings, Card reordering dialog.](../../boards/boards/media/kanban-card-reordering-up1.png) - The setting you choose applies to all active Kanban boards for your team. - -1. When you're done with your changes, select **Save**. -::: moniker-end - -::: moniker range="tfs-2018" -1. [Screenshot of an open Kanban board.](kanban-quickstart.md). If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the Kanban board. - -2. Choose ![settings icon](../../media/icons/team-settings-gear-icon.png) to open the common configuration settings dialog for the Kanban board. - - ![Screenshot showing Kanban board, open common configuration settings.](media/add-columns-open-settings-ts.png) - -3. Choose **Card reordering** and select from the two reordering behaviors listed. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing the Settings dialog and Card reordering dialog.](../../boards/boards/media/kanban-card-reordering-up1.png) + The setting you choose applies to all active boards for your team. - The setting you choose applies to all active Kanban boards for your team. - -4. When you're done with your changes, choose **Save**. - - > [!TIP] - > You can drag-and-drop work items onto a sprint from any backlog or board. To add sprints to a team backlog, see [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). - -::: moniker-end +4. When you're done with your changes, select **Save**. ## Related articles -::: moniker range=">= azure-devops-2019" - [Manage and configure team tools](../../organizations/settings/manage-teams.md) - [Setup your backlogs and boards](../backlogs/set-up-your-backlog.md) -- [Configure status badges](../github/configure-status-badges.md) - [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md) -- [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md) -- [Set working days](../../organizations/settings/set-working-days.md) - [Set up swimlanes](expedite-work.md) -::: moniker-end - -::: moniker range="tfs-2018" -- [Manage and configure team tools](../../organizations/settings/manage-teams.md) -- [Setup your backlogs and boards](../backlogs/set-up-your-backlog.md) -- [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md) -- [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md) -- [Set working days](../../organizations/settings/set-working-days.md) -::: moniker-end diff --git a/docs/boards/boards/expedite-work.md b/docs/boards/boards/expedite-work.md index aa0a1626a3a..e9c7d642108 100644 --- a/docs/boards/boards/expedite-work.md +++ b/docs/boards/boards/expedite-work.md @@ -2,160 +2,136 @@ title: Expedite work using swimlanes titleSuffix: Azure Boards ms.global_help.title: Add swimlanes -description: Learn how to use swimlanes to differentiate different types of work you track on the Kanban board in Azure Board. +description: Learn how to use swimlanes to differentiate different types of work you track on the board in Azure Board. ms.custom: boards-kanban, engagement-fy23 ms.service: azure-devops-boards ms.assetid: 0BBD90C3-7156-4027-B100-9E46F5BD53FB ms.author: chcomley author: chcomley +ai-usage: ai-assisted ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 05/11/2023 +ms.date: 10/03/2024 --- # Expedite work using swimlanes [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Your Kanban board helps you visualize the flow of work as it moves from defined to completed. When you add swimlanes, you can also visualize the status of work that supports different service-level classes. You can create a swimlane to represent any other dimension that supports your tracking needs. +Your board helps you visualize the flow of work as it moves from defined to completed. When you add swimlanes, you can also visualize the status of work that supports different service-level classes. You can create a swimlane to represent any other dimension that supports your tracking needs. + +## Prerequisites [!INCLUDE [temp](../includes/prerequisites-team-settings.md)] ## Types of swimlanes -You can use up to 50 swimlanes to sort work on your Kanban board to track items that you differentiate as follows: -* High priority items -* Service-level class -* Date-driven requirement -* Dependency for or from another team -* Blocked items -* Technical debt or other engineering work that's not a specific user story +You can use up to 50 swimlanes to sort work on your board and track items differentiated by the following categories: +- High priority items +- Service-level class +- Date-driven requirements +- Dependencies for or from another team +- Blocked items +- Technical debt or other engineering work that isn't a specific user story ## Track work in swimlanes -Once you've set up your swimlanes, you can drag items into a swimlane, and also reorder them within the lane. +You can drag items into a swimlane and reorder them within the swimlane. > [!TIP] > - Enter `o` to expand all swimlanes and `u` to collapse all swimlanes. To move the focus up or down, enter the `↑↓` up/down arrows. For more information, see [Keyboard shortcuts](../../project/navigation/keyboard-shortcuts.md). > - When you have many swimlanes or cards on your board, you may encounter slow performance when dragging a card. We recommend that you use swimlanes in conjunction with card styles, tags, and board filters to manage your work items. If you have a lot of cards in the default lane, place that lane lower on the board to enhance performance when dragging a card to another swimlane. > [!div class="mx-imgBorder"] -> ![Screenshot of Kanban board and dragging items into a swimlane.](media/expedite/swimlanes-move-item.png) +> ![Screenshot of board and dragging items into a swimlane.](media/expedite/swimlanes-move-item.png) > [!NOTE] -> The default lane appears unlabeled on the Kanban board. You can rename it to anything you like, but, you can't delete it or apply rules. +> The default lane appears unlabeled on the board. You can rename it, but you can't delete it or apply rules to it. You can also focus on a single swimlane by collapsing all other lanes. > [!div class="mx-imgBorder"] -> ![Screenshot of Kanban board, Collapsed swimlanes.](media/expedite/collapse-lanes.png) +> ![Screenshot of board, Collapsed swimlanes.](media/expedite/collapse-lanes.png) [!INCLUDE [temp](../includes/note-kanban-boards-teams.md)] ## Add or remove a swimlane -*Which swimlanes support your tracking needs?* Once you've identified one or two, add them to your Kanban board. +Identify the swimlanes that support your tracking needs and add them to your board. ::: moniker range="azure-devops" -1. [Open your Kanban board](kanban-quickstart.md). If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project administrators can customize the Kanban board. +1. [Open your board](kanban-quickstart.md). If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project administrators can customize the board. -1. Choose :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: **Configure board settings** to configure the board. +2. Choose :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: **Configure board settings** to configure the board. - :::image type="content" source="media/expedite/choose-configure-board-settings.png" alt-text="Screenshot of Kanban board, Choose Configure board settings."::: + :::image type="content" source="media/expedite/choose-configure-board-settings.png" alt-text="Screenshot of board, Choose Configure board settings."::: -2. Choose **Swimlanes**, choose **Add swimlane**, and then enter the name of the swimlane you want to add. For example, here we enter *Expedite*. You can optionally select the more actions icon :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: to insert a new swimlane above or below another swimlane. +3. Choose **Swimlanes**, choose **Add swimlane**, and then enter the name of the swimlane you want to add. For example, here we enter *Expedite*. You can optionally select the more actions icon :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: to insert a new swimlane above or below another swimlane. - > [!NOTE] - > The following images show the user interface that displays when the **New Boards Hub** preview feature is enabled. Some features are only available when the **New Boards Hub** is enabled as described in [Key concepts and work item tasks in Azure Boards](../work-items/quick-ref.md). For example, the ability to choose the swimlane color is only supported when the **New Boards Hub** feature is enabled. To enable it, see [Manage or enable features](../../project/navigation/preview-features.md). + [!INCLUDE [note-new-boards-hub-default-images](../includes/note-new-boards-hub-default-images.md)] - :::image type="content" source="media/expedite/add-swimlane-new-board-hubs-enabled.png" alt-text="Screenshot of Kanban board Settings, Swimlane tab, Add swimlane."::: + :::image type="content" source="media/expedite/add-swimlane-new-board-hubs-enabled.png" alt-text="Screenshot of board Settings, Swimlane tab, Add swimlane."::: -3. To set the color of the swimlane, choose a color from the drop-down menu. To reset the swimlane to the default, choose :::image type="icon" source="../media/icons/refresh.png" border="false"::: **Reset to default color**. +4. To set the color of the swimlane, choose a color from the drop-down menu. To reset the swimlane to the default, choose :::image type="icon" source="../media/icons/refresh.png" border="false"::: **Reset to default color**. - :::image type="content" source="media/expedite/pick-swimlane-color.png" alt-text="Screenshot of Kanban board Settings, Swimlane tab, choose swimlane color."::: + :::image type="content" source="media/expedite/pick-swimlane-color.png" alt-text="Screenshot of board Settings, Swimlane tab, choose swimlane color."::: -4. To reorder a swimlane, choose the up or down menu selector :::image type="icon" source="../../media/icons/context-menu-selector.png" border="false"::: to move it up or down. To remove a swimlane, choose :::image type="icon" source="../media/icons/trash-can.png" border="false"::: the trash bin icon, but first move all items out of the lane. +5. To reorder a swimlane, choose the up or down menu selector :::image type="icon" source="../../media/icons/context-menu-selector.png" border="false"::: to move it up or down. To remove a swimlane, choose :::image type="icon" source="../media/icons/trash-can.png" border="false"::: the trash bin icon, but first move all items out of the lane. - :::image type="content" source="media/expedite/move-remove-swimlane-options.png" alt-text="Screenshot of Kanban board Settings, Swimlane tab, swimlane menu options."::: + :::image type="content" source="media/expedite/move-remove-swimlane-options.png" alt-text="Screenshot of board Settings, Swimlane tab, swimlane menu options."::: -5. When you're done with your changes, choose **Save**. +6. When you're done with your changes, choose **Save**. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" -1. [Open your Kanban board](kanban-quickstart.md). If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the Kanban board. +1. [Open your board](kanban-quickstart.md). If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the board. -1. Choose the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board and set general team settings. +2. Choose the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board and set general team settings. > [!div class="mx-imgBorder"] > ![Screenshot of gear icon to open board settings for a team.](../../organizations/settings/media/configure-team/open-board-settings.png) -2. Choose **Swimlanes** and then choose the :::image type="icon" source="../media/icons/green_plus_icon.png" border="false"::: plus icon and enter the name of the swimlane you want to add. - - > [!div class="mx-imgBorder"] - > ![Kanban board settings dialog, Add a swimlane](media/expedite/settings-swimlanes-add.png) - - The default lane appears unlabeled on the Kanban board. You can rename it to anything you like, however, you can't delete it. Also, you can rename it directly from the Kanban board. - -3. To reorder your swimlanes, grab the lane and move it up or down. - - > [!div class="mx-imgBorder"] - > ![Kanban board settings dialog, Reorder a swimlane](media/expedite/swimlanes-reorder.png) - -4. If you need to delete a swimlane, first move all items out of the lane. Then open the Settings dialog, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select **Remove**. - - > [!div class="mx-imgBorder"] - > ![Kanban board settings dialog, Remove a swimlane](media/expedite/swimlanes-remove.png) - -5. When you're done with your changes, choose **Save**. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. [Open your Kanban board](kanban-quickstart.md). If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the Kanban board. - -2. Choose the :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: gear icon to open the common configuration settings dialog for the Kanban board. - - ![Screenshot of Kanban board, open common configuration settings.](media/add-columns-open-settings-ts.png) - 3. Choose **Swimlanes** and then choose the :::image type="icon" source="../media/icons/green_plus_icon.png" border="false"::: plus icon and enter the name of the swimlane you want to add. > [!div class="mx-imgBorder"] - > ![Kanban board settings dialog, Add a swimlane](media/expedite/settings-swimlanes-add.png) + > ![Screenshot showing board settings dialog, Add a swimlane.](media/expedite/settings-swimlanes-add.png) - The default lane appears unlabeled on the Kanban board. You can rename it to anything you like, however, you can't delete it. Also, you can rename it directly from the Kanban board. + The default lane appears unlabeled on the board. You can rename it to anything, but you can't delete it. Also, you can rename it directly from the board. -4. To reorder your swimlanes, grab the lane and move it up or down. +4. To reorder your swimlanes, grab the lane and move it up or down. > [!div class="mx-imgBorder"] - > ![Kanban board settings dialog, Reorder a swimlane](media/expedite/swimlanes-reorder.png) + > ![Screenshot showing board settings dialog, Reorder a swimlane.](media/expedite/swimlanes-reorder.png) -5. If you need to delete a swimlane, first move all items out of the lane. Then open the Settings dialog, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select **Remove**. +5. If you need to delete a swimlane, first move all items out of the lane. Then open the Settings dialog, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select **Remove**. > [!div class="mx-imgBorder"] - > ![Kanban board settings dialog, Remove a swimlane](media/expedite/swimlanes-remove.png) + > ![Screenshot showing board settings dialog, Remove a swimlane.](media/expedite/swimlanes-remove.png) 6. When you're done with your changes, choose **Save**. -::: moniker-end +::: moniker-end ## Set up swimlane rules -Swimlane rules are similar to style rules, but instead they allow you to set up conditions on your Kanban board to automatically move work items into specific lanes. For example, you can set up a lane for each person on your team. When you assign the work item, it gets placed into that lane. +Swimlane rules are similar to style rules but allow you to set conditions on your board to automatically move work items into specific lanes. For example, you can set up a lane for each person on your team. When you assign a work item, it gets placed into that person's lane. -Swimlane rules get executed in order, so once the rule is met, it executes and moves on to the next work item. For example, Lane 1 has a rule that says "where priority = 1" and Lane 2 has a rule that says "where priority = 2". If the work item is set to priority = 1, it gets moved into Lane 1. +Swimlane rules are executed in order. Once a rule is met, it executes and moves on to the next work item. For example, if Lane 1 has a rule that says "where priority = 1" and Lane 2 has a rule that says "where priority = 2", a work item with priority = 1 gets moved into Lane 1. The following limits apply to swimlanes: - Up to five rules per lane -- Max of 25 rules total -- Only `AND` rules are supported +- A maximum of 25 rules in total +- Only `AND` conditions are supported + +> [!NOTE] +> Manual movement of items into these lanes is restricted to ensure consistency with the configured rules. To move items into a swimlane with configured rules, ensure that the items meet the criteria defined in the swimlane rules. Adjust the item properties accordingly so that they automatically move into the correct swimlane. -Complete the following steps to set up swimlane rules for your Kanban board. +Do the following steps to set up swimlane rules for your board. -1. From your Kanban board, choose the :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: gear icon to **Configure board settings**. +1. From your board, choose the :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: gear icon to **Configure board settings**. 2. Select **Swimlanes**, select the **swimlane** or **[+ Add swimlane](#add-or-remove-a-swimlane)**, and then select **+ Add criteria**. @@ -180,33 +156,33 @@ The following examples show some of the ways you can use and set up swimlane rul :::image type="content" source="media/expedite/priority-swimlane-rule-setup.png" alt-text="Screenshot showing swimlane rules set up by priority."::: - **Kanban board results** + **Board results** - :::image type="content" source="media/expedite/board-priority-swimlanes.png" alt-text="Screenshot showing priority swimlanes on Kanban board."::: + :::image type="content" source="media/expedite/board-priority-swimlanes.png" alt-text="Screenshot showing priority swimlanes on board."::: -- **Track the parents of your work items**. We created rules for the `Work item type` field, so you can quickly see parents (features) and children (user stories and bugs) in their own swimlanes on the Kanban board. +- **Track the parents of your work items**. We created rules for the `Work item type` field, so you can quickly see parents (features) and children (user stories and bugs) in their own swimlanes on the board. **Settings** :::image type="content" source="media/expedite/work-item-type-swimlane-rule-setup.png" alt-text="Screenshot showing rules set up for work item types."::: - **Kanban board results** + **Board results** - :::image type="content" source="media/expedite/board-track-parent-work-items-swimlanes.png" alt-text="Screenshot showing parent work item swimlanes on Kanban board."::: + :::image type="content" source="media/expedite/board-track-parent-work-items-swimlanes.png" alt-text="Screenshot showing parent work item swimlanes on board."::: -- **Track each person's work on your team**. We created rules for the `Assigned to` field, so that when you assign a work item, it's placed into that user's lane. +- **Track each person's work on your team**. We created rules for the `Assigned to` field, so that when you assign a work item, it goes into that user's lane. **Settings** :::image type="content" source="media/expedite/assigned-to-swimlane-rule-setup.png" alt-text="Screenshot showing rule criteria for swimlane, by Assigned To field."::: - **Kanban board results** + **Board results** :::image type="content" source="media/expedite/board-assigned-to-swimlanes.png" alt-text="Screenshot showing swimlanes grouped by priority."::: ## Query for work items based on swimlane -You can track which work items have been added to a Kanban board swimlane by creating a query and using the [Board Lane field](../queries/query-by-workflow-changes.md#kanban_query_fields). +You can track which work items get added to a board swimlane by creating a query and using the [Board Lane field](../queries/query-by-workflow-changes.md#kanban_query_fields). ## Next steps @@ -222,6 +198,4 @@ You can track which work items have been added to a Kanban board swimlane by cre ### REST API resources -To programmatically interact with the Kanban board and other team settings, see the [REST API, Boards reference](/rest/api/azure/devops/work/boards). - - +To programmatically interact with the board and other team settings, see the [REST API, Boards reference](/rest/api/azure/devops/work/boards). diff --git a/docs/boards/boards/kanban-epics-features-stories.md b/docs/boards/boards/kanban-epics-features-stories.md index d8d4158329c..d9570c36918 100644 --- a/docs/boards/boards/kanban-epics-features-stories.md +++ b/docs/boards/boards/kanban-epics-features-stories.md @@ -1,7 +1,7 @@ --- -title: Add features & epics to a Kanban board +title: Add features & epics to a board titleSuffix: Azure Boards -description: Quickly define and view the status of child features, user stories, or backlog items using Kanban features or epic boards in Azure Boards and Azure DevOps. +description: Quickly define and view the status of child features, user stories, or backlog items using features or epic boards in Azure Boards and Azure DevOps. ms.custom: boards-kanban ms.service: azure-devops-boards ms.assetid: 489C612D-983E-47D3-BD1A-F13C5DCD74E2 @@ -9,102 +9,58 @@ ms.topic: tutorial ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 06/07/2024 --- - - -# Add Kanban board features and epics +# Add board features and epics [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -If you track progress on your backlog with Kanban, you can also use Kanban boards to track epics and features. +If you track progress on your backlog with a board, you can also use boards to track epics and features. And, as with [child task checklists for backlog items](add-task-checklists.md), you can quickly define and track the progress of child items for your features or epics. Here we see several stories defined for features, both in progress and completed. -In this article, you'll learn: ->[!div class="checklist"] -> * How to add epics and features using your portfolio backlogs -> * Keyboard shortcuts for working with the Kanban board - -For information on managing features and epics as a list and examples for features and epics, see [Define features and epics](../backlogs/define-features-epics.md). +For more information, see [Define features and epics](../backlogs/define-features-epics.md). -> [!div class="mx-imgBorder"] -> ![Web portal, Features Kanban board with several user stories defined](media/features-epics/features-with-stories-intro.png) +## Prerequisites [!INCLUDE [temp](../includes/prerequisites-kanban.md)] +## Open your board from the web portal -## Open your Kanban board from the web portal +Your board is one of two types of boards available to you. For an overview of the features supported on each backlog and board, see [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md). To switch to the [product backlog](../backlogs/create-your-backlog.md), choose **Stories backlog**. And, to switch to the [taskboard](../sprints/task-board.md), choose **Sprints** and then choose **Taskboard**. -Your Kanban board is one of two types of boards available to you. For an overview of the features supported on each backlog and board, see [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md). To switch to the [product backlog](../backlogs/create-your-backlog.md), choose **Stories backlog**. And, to switch to the [taskboard](../sprints/task-board.md), choose **Sprints** and then choose **Taskboard**. +1. (1) Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```), (2) choose **Boards > Boards**, and then (3) select the correct team from the team selector menu. -::: moniker range=">= azure-devops-2019" - -1. (1) Check that you've selected the right project, (2) choose **Boards>Boards**, and then (3) select the correct team from the team selector menu. - - ![Open your Kanban board](/azure/devops/boards/boards/media/quickstart/open-kanban-board-agile.png) + ![Screenshot showing Open your board.](/azure/devops/boards/boards/media/quickstart/open-kanban-board-agile.png) To choose another team's board, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all team boards** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. > [!div class="mx-imgBorder"] - > ![Choose another team's board](/azure/devops/boards/boards/media/quickstart/select-kanban-team-board.png) + > ![Screenshot showing Choose another team's board.](/azure/devops/boards/boards/media/quickstart/select-kanban-team-board.png) > [!TIP] - > Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to favorite a team board. Favorited artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorited icon) appear at the top of the team selector list. - -1. Select **Features** or **Epics** from the backlog selector menu. - - > [!div class="mx-imgBorder"] - > ![Choose portfolio backlog level, Features or Epics](media/features-epics/select-portfolio-level.png) - -::: moniker-end - - -::: moniker range="tfs-2018" - -1. To view a portfolio backlog, open your (1) project from a web browser and choose (2) **Work**, (3) **Backlogs**, (4) **Features** or **Epics**, and then (5) **Board**. + > Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to favorite a team board. Favorited artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false":::) appear at the top of the team selector list. - ![Open Features Kanban board](media/features-epics/open-features-board-standard.png) - - If you don't see **Work**, your screen size may be reduced. Select the three dots (:::image type="icon" source="../../media/ellipses-reduced-screen-size.png" border="false":::, then choose **Work**, **Backlogs**, and then **Board**. - - ![Open Work when screen size is reduced](/azure/devops/boards/boards/media/kanban-quickstart-reduced-screensize.png) - -2. To choose another team, open the project/team selector and select a different team or choose the **Browse** option. +2. Select **Features** or **Epics** from the backlog selector menu. > [!div class="mx-imgBorder"] - > ![Choose another team](/azure/devops/boards/sprints/media/assign-items-sprint/team-selector-backlogs-standard.png) - -3. Your Kanban board for the selected portfolio backlog displays. - - ![Kanban board, Agile template](media/features-epics/features-board-standard.png) - -::: moniker-end - + > ![Choose portfolio backlog level, Features or Epics](media/features-epics/select-portfolio-level.png) ## Add epics or features Add new items to a feature or epic through the item's :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Action menu. For descriptions of fields used to support features and epics, see [Define features and epics](../backlogs/define-features-epics.md). -![Web portal, Feature Kanban board, Open the context menu of a feature to add a story](media/features-epics/add-user-story.png) +![Screenshot showing Web portal, Feature board, Open the context menu of a feature to add a story.](media/features-epics/add-user-story.png) When you have many items to add, keep entering your task titles and press Enter. If you have details you want to add about to a work item, hover over the item and press Enter. - ## Related articles -If you're new to working with the Kanban board, see [Kanban overview](kanban-overview.md) - -For more information on working with a checklist on a Kanban board, see [Add tasks or child items as checklists](add-task-checklists.md). You can run the same operations for the features and epics Kanban boards as you do with the Kanban board for the product backlog. These operations include: - -- Mark an item as done -- Reorder and reparent work items - -To customize the columns, swimlanes, or cards for each Kanban board, make sure you first select the board. Then, choose the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: or :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: gear icon to open the Settings dialog. See these articles for details: - -* [Add columns](add-columns.md) -* [Customize cards](../../boards/boards/customize-cards.md) +- [Kanban board overview](kanban-overview.md) +- [Add tasks or child items as checklists](add-task-checklists.md) +- [Add columns](add-columns.md) +- [Customize cards](../../boards/boards/customize-cards.md) ### REST API resources -To programmatically interact with Kanban board and other team settings, see the [REST API, Boards reference](/rest/api/azure/devops/work/boards). \ No newline at end of file +To programmatically interact with a board and other team settings, see the [REST API, Boards reference](/rest/api/azure/devops/work/boards). diff --git a/docs/boards/boards/kanban-overview.md b/docs/boards/boards/kanban-overview.md index 27e7a1db9ce..c27970dbf78 100644 --- a/docs/boards/boards/kanban-overview.md +++ b/docs/boards/boards/kanban-overview.md @@ -9,68 +9,64 @@ ms.author: chcomley author: chcomley ms.topic: overview monikerRange: '<= azure-devops' -ms.date: 06/01/2023 +ms.date: 06/07/2024 --- # About Kanban boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Your Kanban board provides you with a visual interactive space for you and your team to plan and show progress. Your team can track the critical information it needs by seeing which work items are in progress, where the bottlenecks are, who work is assigned to, and more. +A Kanban board in Azure DevOps is a visual tool used to manage work items and track progress in a project. It provides a clear overview of tasks, their status, and their flow through different stages. Teams can use Kanban boards to visualize work, limit work in progress, and optimize their workflow. Each work item is represented as a card on the board, and columns represent different stages, such as "To Do," "In Progress," and "Done." As work progresses, cards move across columns, allowing teams to monitor and improve their efficiency. Kanban boards are commonly used in agile methodologies and are essential for effective project management. -As work progresses from idea to completion, you update the items on the board. Each column represents a work stage. Each card represents a work item and supports quick status updates through drag-and-drop, similar to sticky notes on a physical whiteboard. +Both Kanban boards and Taskboards support visualizing the flow of work and monitoring metrics to optimize that flow. Kanban boards track requirements are sprint-independent, and provide a cumulative flow chart for monitoring progress. Each sprint is associated with a Taskboard that supports tracking tasks defined for the sprint. You can monitor progress through capacity charts and the sprint burndown chart. For more information, see [Update and monitor your Taskboard](../sprints/task-board.md). -Both Kanban boards and Taskboards support visualizing the flow of work and monitoring metrics to optimize that flow. Kanban boards track requirements, are sprint-independent, and provide a cumulative flow chart for monitoring progress. Each sprint is associated with a Taskboard that supports tracking tasks defined for the sprint. You can monitor progress through capacity charts and the sprint burndown chart. For more information, see [Update and monitor your Taskboard](../sprints/task-board.md). +> [!NOTE] +> ***Kanban*** is a Japanese word that literally translates to "signboard." In this article, we focus on *Kanban* boards, but moving forward, we refer the them as "boards." -## Product and portfolio Kanban boards +## Product and portfolio boards -Each [product and portfolio backlog](../backlogs/backlogs-overview.md) has a corresponding Kanban board. Kanban boards are associated with a team and display work items that are based on the area and iteration paths that the team selected. For more information, see [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). +Each [product and portfolio backlog](../backlogs/backlogs-overview.md) corresponds to a board. These boards are associated with teams and display work items based on the selected area and iteration paths. For more information, see [Define and configure iterations](../../organizations/settings/set-iteration-paths-sprints.md). -To maximize a team's ability to consistently deliver high-quality software, Kanban emphasizes two main practices. The first is to [visualize the flow of work](kanban-quickstart.md#map-the-flow-of-how-your-team-works). This practice requires you to map your team's workflow stages and configure your Kanban board to match. The second is to constrain the amount of work in progress, which requires you to [set work-in-progress (WIP) limits](kanban-quickstart.md#set-wip-limits). You're then ready to track progress on your Kanban board and monitor key metrics to reduce lead or cycle time. To get started, see [Use your Kanban board](../boards/kanban-quickstart.md). +To enhance consistent delivery of high-quality software, Kanban emphasizes two key practices. First, [**visualize the flow of work**](kanban-quickstart.md#map-the-flow-of-how-your-team-works) by mapping your team's workflow stages and configuring the board appropriately. Second, **constrain work in progress**, by [setting work-in-progress (WIP) limits](kanban-quickstart.md#set-wip-limits). With these practices in place, you can track progress and monitor metrics to reduce lead or cycle time. Get started by exploring how to [use your board](../boards/kanban-quickstart.md). -::: moniker range=">= azure-devops-2019" -:::image type="content" source="../work-items/media/about-agile/view-boards-agile.png" alt-text="Screenshot showing Kanban board, Agile template."::: +::: moniker range="<=azure-devops" +:::image type="content" source="../work-items/media/about-agile/view-boards-agile.png" alt-text="Screenshot showing board, Agile template."::: ::: moniker-end -::: moniker range="tfs-2018" -:::image type="content" source="media/kanban-basics-intro.png" alt-text="Screenshot of Kanban boards, Agile template, TFS 2018."::: -::: moniker-end - ## Kanban concepts and terms -See the following table of terms and available tools used in tracking work using Kanban boards and Kanban methods. +The following table outlines terms and tools commonly used for tracking work with Kanban boards and Kanban methods. -|Concept or Term |Description | +|Concept or term |Description | |---------|---------| |Blocker | An issue that prevents work from progressing. You can highlight work that is blocked by using tags and changing the card color. For more information, see [Customize cards, Define style rules to highlight cards](customize-cards.md#define-style-rules-to-highlight-cards). | |Bottleneck | A constraint in the system that limits the flow of work. Identifying bottlenecks makes it easier to reduce their effect and provides a mechanism for controlling work flowing through the process. For more information, see [Manage columns, Identify bottlenecks](add-columns.md#identify-bottlenecks). | |Card reordering |Card reordering lets you change the priority order and forces cards to maintain the backlog priority when you drag and drop them on the board. For more information, see [Reorder cards](customize-cards.md#reorder-cards). | -|Cumulative flow diagram (CFD) | The in-context CFD report shows the count of items in each Kanban column for the past 30 weeks or less. From this chart, you can gain an idea of the amount of work in progress and lead time. Work in progress counts unfinished requirements. For more information, see [Cumulative flow, lead time, and cycle time guidance](../../report/dashboards/cumulative-flow.md). | +|Cumulative flow diagram (CFD) | The in-context CFD report shows the count of items in each column for the past 30 weeks or less. From this chart, you can gain an idea of the amount of work in progress and lead time. Work in progress counts unfinished requirements. For more information, see [Cumulative flow, lead time, and cycle time guidance](../../report/dashboards/cumulative-flow.md). | |Cycle time |Cycle time is the time calculated for a work item from first entering an *In Progress* category state to entering a *Completed* state category. For more information, see [Cumulative flow, lead time, and cycle time guidance](../../report/dashboards/cumulative-flow-cycle-lead-time-guidance.md). You can gain valuable metrics and visualize the cycle time for a team and a configurable time period by [adding the Cycle Time widget to the dashboard](../../report/dashboards/cycle-time-and-lead-time.md). | |Definition of done | Criteria that a team specifies for each stage of work to share and standardize on what makes up work being done at that stage. | -|Kanban board | An interactive, electronic sign board that supports visualization of the flow of work from concept to completion and lean methods. Azure DevOps provides a Kanban board for each product and portfolio backlog. For more information, see [Kanban basics](../../boards/boards/kanban-overview.md) and [Kanban board features and epics](../../boards/boards/kanban-epics-features-stories.md) and [Track work in swimlanes](expedite-work.md#track-work-in-swimlanes). | -|Kanban columns | A Kanban column maps to a stage of work. The default columns map to the workflow states of the work item types that appear on the Kanban board. You configure the columns to map workflow states of your team. For more information, see [Map the flow](kanban-quickstart.md#map-the-flow-of-how-your-team-works). | +|Kanban board | An interactive, electronic sign board that supports visualization of the flow of work from concept to completion and lean methods. Azure DevOps provides a board for each product and portfolio backlog. For more information, see [Board basics](../../boards/boards/kanban-overview.md) and [Board features and epics](../../boards/boards/kanban-epics-features-stories.md) and [Track work in swimlanes](expedite-work.md#track-work-in-swimlanes). | +|Columns | A column maps to a stage of work. The default columns map to the workflow states of the work item types that appear on the board. You configure the columns to map workflow states of your team. For more information, see [Map the flow](kanban-quickstart.md#map-the-flow-of-how-your-team-works). | |Lead time | Lead time is the time calculated for a work item from first entering a *Proposed* category state to entering a *Completed* state category. For more information, see [Cumulative flow, lead time, and cycle time guidance](../../report/dashboards/cumulative-flow-cycle-lead-time-guidance.md). You can gain valuable metrics and visualize the lead time for a team and a configurable time period by [adding the Lead Time widget to the dashboard](../../report/dashboards/cycle-time-and-lead-time.md). | -|Live updates |Live updates is a Kanban board view option that when enabled automatically refreshes the Kanban board as other team members move or reorder cards. For more information, see [Enable live updates](kanban-quickstart.md#enable-live-updates). | -|Product backlog | An interactive list of work items that corresponds to a team's project plan or roadmap for what the team plans to deliver. The product backlog supports prioritizing work, forecasting work by sprints, and quickly linking work to portfolio backlog items. You can define your backlog items and then manage their status using the Kanban board. Each team can customize its product backlog. For more information, see [Create your backlog](../backlogs/create-your-backlog.md). | +|Product backlog | An interactive list of work items that corresponds to a team's project plan or roadmap for what the team plans to deliver. The product backlog supports prioritizing work, forecasting work by sprints, and quickly linking work to portfolio backlog items. You can define your backlog items and then manage their status using the board. Each team can customize its product backlog. For more information, see [Create your backlog](../backlogs/create-your-backlog.md). | |Product backlog item | A type of work item that defines the applications, requirements, and elements that teams plan to create. Product owners typically define and stack rank product backlog items, which are defined with the Scrum process. For more information, see [Scrum process work item types and workflow.](../work-items/guidance/scrum-process-workflow.md) | |Portfolio backlog | An interactive list of work items, similar to the product backlog that supports organizing or grouping work under features epics, or scenarios. Portfolio backlogs work similarly to product backlogs in that you can prioritize work and view the tree hierarchy of work. For more information, see [Define features and epics.](../backlogs/define-features-epics.md) | -| Swimlanes | A swimlane is a configurable row on a Kanban board, used to support different service class levels of work. For more information, see [Speed up work with swimlanes](expedite-work.md). | -|Split columns | The Split columns feature lets your team implement a pull mechanism within the workflow process. Without split columns, teams push work forward, to signal that they've completed their stage of work. However, pushing it to the next stage doesn't necessarily mean that a team member immediately starts work on that item. With split columns, your team knows exactly how many items sit idle, waiting for work to begin. For more information, see [Manage columns](add-columns.md#split-columns). | -|Task checklists | A task is a type of work item used to track work required to complete a user story or product backlog item. You can add tasks from your Kanban board that appear as a checklist of work to be done. As you complete a task, you can update its status by checking the checkbox for the task. For more information, see [Add tasks or child items as checklists](add-task-checklists.md). | +| Swimlanes | A swimlane is a configurable row on a board, used to support different service class levels of work. For more information, see [Speed up work with swimlanes](expedite-work.md). | +|Split columns | The Split columns feature lets your team implement a pull mechanism within the workflow process. Without split columns, teams push work forward, to signal that they completed their stage of work. However, pushing it to the next stage doesn't necessarily mean that a team member immediately starts work on that item. With split columns, your team knows exactly how many items sit idle, waiting for work to begin. For more information, see [Manage columns](add-columns.md#split-columns). | +|Task checklists | A task is a type of work item used to track work required to complete a user story or product backlog item. You can add tasks from your board that appear as a checklist of work to be done. As you complete a task, you can update its status by checking the checkbox for the task. For more information, see [Add tasks or child items as checklists](add-task-checklists.md). | |Task switching | Task switching, also referred to as *context switching* or *multitasking*, is when a team member shifts their attention among different tasks. Limiting task switching can allow a person to work more efficiently by minimizing the amount of time required to redirect cognitive function to a new activity. | |User story | A type of work item that defines the applications, requirements, and elements that teams plan to create. Product owners typically define and stack rank user stories. User story is defined with the Agile process. For more information, see [Agile process work item types and workflow.](../work-items/guidance/agile-process-workflow.md) | -| Work in progress (WIP) | Work that has been started but isn't done or completed. | +| Work in progress (WIP) | Work that is started but isn't done or completed. | | WIP limit | A WIP limit is a constraint that a team applies to one or more workflow stages to help prevent potential bottlenecks that hinder the continuous flow of work in the system. For more information, see [Work in Progress limits](wip-limits.md). | |Workflow states |Workflow states are defined for each work item type to support tracking the status of a work item, from its creation to its completion. These states define the workflow process: actions, steps, or stages that a piece of work goes through from inception to completion. The State and Reason fields differ depending on the work item type and process selected for the project. For more information, see [Customize the workflow](../../organizations/settings/work/customize-process-workflow.md). | -| Workflow state categories | State categories determine how the Kanban board treats each workflow state. The state categories used by the backlogs are *Proposed*, *In Progress*, *Resolved*, and *Completed*. For more information, see [Workflow states and state categories](../work-items/workflow-and-state-categories.md). | +| Workflow state categories | State categories determine how the board treats each workflow state. The state categories used by the backlogs are *Proposed*, *In Progress*, *Resolved*, and *Completed*. For more information, see [Workflow states and state categories](../work-items/workflow-and-state-categories.md). | For more information, see the following articles: - [Agile glossary](../work-items/agile-glossary.md) - [Work item field index](../work-items/guidance/work-item-field.md) - [Project management and navigation glossary](../../project/navigation/glossary.md) -## Use Kanban board controls +## Use board controls You can quickly switch from the backlog view to the board view using the **Backlog** and **Board** links. Use the following icons to enable other user interface features. @@ -78,23 +74,22 @@ You can quickly switch from the backlog view to the board view using the **Backl > |Control | Function | > |--------------------------|-------------------------------| > | **Backlog** | [Switch to backlog view](../backlogs/create-your-backlog.md) | -> | **Board** | [Switch to Kanban board view](kanban-quickstart.md) | -> | ![Kanban filter icon](../media/icons/kanban-filter-icon.png) | [Filter by keywords, tags, or fields](../backlogs/filter-backlogs-boards-plans.md) | -> | ![Live updates icon](../media/icons/live-updates-icon.png) | [Enable live updates](kanban-quickstart.md#enable-live-updates) | -> | ![Settings icon](../media/icons/team-settings-gear-icon.png) | Customize the board and configure team settings:
[Cards](../../boards/boards/customize-cards.md) | [Card reordering](../../boards/boards/customize-cards.md#reorder-cards) | [Columns](add-columns.md) | [Swimlanes](expedite-work.md) | [CFD chart](../../report/dashboards/cumulative-flow.md) | [Backlogs](../../organizations/settings/select-backlog-navigation-levels.md) | [Working days](../../organizations/settings/set-working-days.md) | [Working with bugs](../../organizations/settings/show-bugs-on-backlog.md) | +> | **Board** | [Switch to board view](kanban-quickstart.md) | +> | ![Filter icon](../media/icons/kanban-filter-icon.png) | [Filter by keywords, tags, or fields](../backlogs/filter-backlogs-boards-plans.md) | +> | ![Settings icon](../media/icons/team-settings-gear-icon.png) | Customize the board and configure team settings:
[Cards](../../boards/boards/customize-cards.md) | [Card reordering](../../boards/boards/customize-cards.md#reorder-cards) | [Columns](add-columns.md) | [Swimlanes](expedite-work.md) | [CFD chart](../../report/dashboards/cumulative-flow.md) | [Backlogs](../../organizations/settings/select-backlog-navigation-levels.md) | [Working with bugs](../../organizations/settings/show-bugs-on-backlog.md) | > | ![full screen icon](../media/icons/full-screen-icon.png) / ![exit full screen icon](../media/icons/exit-full-screen-icon.png) | Enter or exit full screen mode | ### Open keyboard shortcuts -Enter `?` to open the Kanban board keyboard shortcuts. The following image isn't exhaustive. +Enter `?` to open the board keyboard shortcuts. The following image isn't a comprehensive representation. :::image type="content" source="../media/kanban-board-keyboard-shortcuts-ts-jul.png" alt-text="Screenshot showing keyboard shortcuts."::: For more information, see [Keyboard shortcuts for Azure DevOps and Team Explorer](../../project/navigation/keyboard-shortcuts.md). -## Configure & customize your Kanban board +## Configure & customize your board -Your Kanban board is highly configurable to support your team's workflow. Each team can configure each board with the following tasks: +Your board is highly configurable to support your team's workflow. Each team can configure each board with the following tasks: :::row::: :::column span="1"::: **Configure boards** @@ -107,7 +102,7 @@ Your Kanban board is highly configurable to support your team's workflow. Each t :::column span="1"::: - [Manage columns](add-columns.md) - [Set WIP limits](wip-limits.md) - - [Set Definition of Done](add-columns.md#add-the-definition-of-done-to-a-column) + - [Set Definition of Done](add-columns.md#add-definition-of-done-to-a-column) - [Add swimlanes](expedite-work.md) - [Reorder cards](customize-cards.md#reorder-cards) - [Enable backlog and board levels](../../organizations/settings/select-backlog-navigation-levels.md) @@ -116,9 +111,9 @@ Your Kanban board is highly configurable to support your team's workflow. Each t :::column span="2"::: - [Add or remove fields from cards](customize-cards.md) - [Define card styles](customize-cards.md#style-rule) - - [Apply tag colors](customize-cards.md#color-tags) - - [Enable/disable annotations](customize-cards.md#annotations) - - [Define inline test behavior on cards](customize-cards.md#tests) + - [Apply tag colors](customize-cards.md) + - [Enable/disable annotations](customize-cards.md) + - [Define inline test behavior on cards](customize-cards.md) - [Add details and estimates](../backlogs/create-your-backlog.md#estimates) to your backlog items - [Define tasks or child items for backlog items](add-task-checklists.md) - [Add, run, and update inline tests](add-run-update-tests.md) @@ -133,7 +128,7 @@ Along with these team configurations, you can [customize your project](#customiz ## Update work item status -Once you've configured your Kanban board, you can add work items directly to the board. Update the status of work by dragging a card to another column on the Kanban board. You can even change the order of items as you move a card to a new column. For more information, see [Workflow states and state categories](../work-items/workflow-and-state-categories.md). +Once you configure your board, you can add work items directly to the board. Update the status of work by dragging a card to another column on the board. You can even change the order of items as you move a card to a new column. For more information, see [Workflow states and state categories](../work-items/workflow-and-state-categories.md). ![Git showing how to reorder cards while changing columns.](media/8_7_02.gif) @@ -143,16 +138,16 @@ Once you've configured your Kanban board, you can add work items directly to the ## Reorder and reparent work items -All backlogs and boards support drag-and-drop to reorder and reparent work items. Updates made to one team's backlogs and boards are reflected in other team backlogs and boards that share the same area path. You may need to refresh the page to view the changes. +All backlogs and boards support drag-and-drop to reorder and reparent work items. Updates made to one team's backlogs and boards are reflected in other team backlogs and boards that share the same area path. You might need to refresh the page to view the changes. -You can only use drag-and-drop to reorder or reparent work items assigned to area paths selected for your team. When the **Parents** view option is enabled, work items may appear on your backlog that your team doesn't own. Anything that appears with the :::image type="icon" source="../../media/icons/info.png" border="false"::: information icon can't be reordered nor reparented as another team owns it. +You can only use drag-and-drop to reorder or reparent work items assigned to area paths selected for your team. When the **Parents** view option is enabled, work items might appear on your backlog that your team doesn't own. Anything that appears with the :::image type="icon" source="../../media/icons/info.png" border="false"::: information icon can't be reordered nor reparented as another team owns it. :::image type="content" source="../plans/media/config-teams/information-message-owned-by-other-team.png" alt-text="Screenshot of information message on team ownership."::: ## Update columns -Each team can customize the Kanban board columns and swimlanes. The values that get assigned to Kanban board fields may differ from what you expect when another team updates the work item from a different board. +Each team can customize the board columns and swimlanes. The values that get assigned to board fields might differ from what you expect when another team updates the work item from a different board. -Even if the management team and the feature teams configure their Kanban board columns with identical workflow mapping, one team's Kanban board items aren't reflected on another team's Kanban board. Only when the work item moves to a column that maps to a workflow state does the card column reflect the same on all boards. +Even if the management team and the feature teams configure their board columns with identical workflow mapping, one team's board items aren't reflected on another team's board. Only when the work item moves to a column that maps to a workflow state does the card column reflect the same on all boards. For more information, see [Manage columns](add-columns.md). @@ -160,26 +155,18 @@ For more information, see [Manage columns](add-columns.md). As a member added to the Contributors group of a project, you can use most features provided under **Boards** or **Work**. Users with Basic access have full access to all features. Users with Stakeholder access are limited to certain features. -For more information about permissions and access, see [Permissions and access for work tracking](../../organizations/security/permissions-access-work-tracking.md) and [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). To add users to a project, see [Add users to a project or team](../../organizations/security/add-users-team-project.md). +For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md) and [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). To add users to a project, see [Add users to a project or team](../../organizations/security/add-users-team-project.md). ## Customize your project and board inheritance -::: moniker range=">= azure-devops-2019" -If you need more than three board levels, you can add more. For more information, see [Customize your backlogs or boards for a process](../../organizations/settings/work/customize-process-backlogs-boards.md). +If you require more than three board levels, you can add additional ones. For more information, see [Customize your backlogs or boards for a process](../../organizations/settings/work/customize-process-backlogs-boards.md). You can also add or modify the fields defined for a work item type (WIT), add a custom WIT, or modify the workflow. For more information, see [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md). -::: moniker-end - -::: moniker range="< azure-devops-2019" -If you need more than three board levels, you can add more. For more information, see [Add portfolio backlogs](../../reference/add-portfolio-backlogs.md). - -You can also add or modify the fields defined for a work item type (WIT), add a custom WIT, or modify the workflow. For more information, see [Customize the On-premises XML process model](../../reference/on-premises-xml-process-model.md). -::: moniker-end ## Next steps > [!div class="nextstepaction"] -> [Use your Kanban board](kanban-quickstart.md) +> [Use your board](kanban-quickstart.md) ## Related articles diff --git a/docs/boards/boards/kanban-quickstart.md b/docs/boards/boards/kanban-quickstart.md index 672f254154a..8c585836e4b 100644 --- a/docs/boards/boards/kanban-quickstart.md +++ b/docs/boards/boards/kanban-quickstart.md @@ -1,38 +1,26 @@ --- -title: Use your Kanban board +title: Use your board titleSuffix: Azure Boards -description: Learn how to use the Kanban board to plan and track work in Azure Boards. +description: Learn how to use your board to plan and track work in Azure Boards. ms.custom: boards-kanban ms.topic: quickstart ms.service: azure-devops-boards ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 06/01/2023 +ms.date: 09/11/2024 --- -# Use your Kanban board +# Use your board [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Kanban boards provide an intuitive and visual way to manage your projects, track work items, and collaborate with your team effectively. If you have a project, you already have a Kanban board. Let's get started! - -In this article, learn how to: -> [!div class="checklist"] -> * Open your Kanban board -> * Map the flow of how your team works -> * Set work in progress limits -> * Track work in progress -> * Add work items -> * Update work item status -> * Update card fields -> * Filter your board -> * Invite others to work on your board -> * Enable live updates -> * Monitor metrics +Boards provide an intuitive and visual way to manage your projects, track work items, and collaborate with your team effectively. If you have a project, you already have a board. Let's get started! > [!NOTE] -> You can only create or add Kanban boards to a project by adding another team. Kanban boards only get created when a project or team gets created. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). +> You can only create or add boards to a project by adding another team. Boards only get created when a project or team gets created. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). + +## Prerequisites [!INCLUDE [temp](../includes/prerequisites-kanban.md)] @@ -40,7 +28,7 @@ In this article, learn how to: ## Map the flow of how your team works -When you first open your Kanban board, you have one column for each [workflow state](../work-items/guidance/choose-process.md#workflow-states). Your actual columns vary based on the [process](../work-items/guidance/choose-process.md) used to create your project. +When you first open your board, there's one column for each [workflow state](../work-items/guidance/choose-process.md#workflow-states). Your actual columns vary based on the [process](../work-items/guidance/choose-process.md) used to create your project. 1. Identify your team's workflow stages, which most likely don't map to the default states. For your team to have a functional board, configure the board to match your workflow stages. @@ -50,17 +38,17 @@ When you first open your Kanban board, you have one column for each [workflow st ![Screenshot showing user story workflow states.](media/alm-kb-workflow.png) :::column-end::: :::column span="2"::: - ![Screenshot showing default Kanban board, Agile template.](media/alm-kb-empty.png) + ![Screenshot showing default board, Agile template.](media/alm-kb-empty.png) :::column-end::: :::row-end::: -2. [Manage your Kanban columns](add-columns.md), so they match your workflow stages. Keep the number of columns to a minimum while still representing the key handoffs that occur for your team. +2. [Manage your columns](add-columns.md), so they match your workflow stages. Keep the number of columns to a minimum while still representing the key handoffs that occur for your team. - :::image type="content" source="media/ALM_KB_Board2.png" alt-text="Screenshot showing Kanban board, Columns customized."::: + :::image type="content" source="media/ALM_KB_Board2.png" alt-text="Screenshot showing board, Columns customized."::: ## Set WIP limits -Set WIP limits for each workflow stage, so that when work items exceed the limit, the column count displays as red. Teams can use this color as a signal to focus immediately on activities to bring the number of items in the column down. For more information, see [Set WIP limits](wip-limits.md). +Set work in progress (WIP) limits for each workflow stage, so that when work items exceed the limit, the column count displays as red. Teams can use this color as a signal to focus immediately on activities to bring the number of items in the column down. For more information, see [Set WIP limits](wip-limits.md). :::image type="content" source="media/alm-kb-wip-limits.png" alt-text="Screenshot showing WIP limit reached with red numbering."::: @@ -68,39 +56,23 @@ Set WIP limits for each workflow stage, so that when work items exceed the limit See the estimated size of work for each item that displays at the bottom right of each card. Add items to your backlog in the first column. When priorities change, move items up and down within a column. And, as work completes in one stage, update the status of an item by moving it to a downstream stage. -:::image type="content" source="media/alm-cc-move-card.png" alt-text="Screenshot showing moving a card on Kanban board to update status."::: +:::image type="content" source="media/alm-cc-move-card.png" alt-text="Screenshot showing moving a card on board to update status."::: -Update your Kanban board as work progresses to help keep your team in sync. Also, you can see and share the value stream your team is delivering to customers. +Update your board as work progresses to help keep your team in sync. Also, you can see and share the value stream your team is delivering to customers. [!INCLUDE [temp](../includes/note-kanban-boards-teams.md)] ## Add work items -::: moniker range=">= azure-devops-2019" To add a work item, select the :::image type="icon" source="../media/icons/add_icon.png" border="false"::: plus sign, enter a title, and then select **Enter**. -::: moniker-end ::: moniker range=">= azure-devops-2020" -:::image type="content" source="media/quickstart/add-new-item-agile-s155.png" alt-text="Screenshot showing adding a new item on Kanban board, new nav."::: +:::image type="content" source="media/quickstart/add-new-item-agile-s155.png" alt-text="Screenshot showing adding a new item on a board, new nav."::: ::: moniker-end -::: moniker range="azure-devops-2019" -:::image type="content" source="media/quickstart/add-new-item-agile.png" alt-text="Screenshot showing adding a new item on Kanban board, new nav."::: -::: moniker-end - -::: moniker range=">= azure-devops-2019" -The system automatically saves the work item with the title you entered. You can add as many work items you want by using this method. -::: moniker-end - -::: moniker range="tfs-2018" -To add a work item, select the :::image type="icon" source="../media/icons/add_icon.png" border="false"::: plus sign, enter a title, and then select **Enter**. - -:::image type="content" source="media/quickstart/add-new-item-standard.png" alt-text="Screenshot showing adding a new item on Kanban board, prev nav."::: - The system automatically saves the work item with the title you entered. You can add as many work items you want by using this method. -::: moniker-end -To add details to any work item, select the title. Or, you can directly modify any field that displays. For example, you can reassign a work item by selecting **Assigned To**. For a description of each field, see [Create your backlog, Add details and estimates](../backlogs/create-your-backlog.md#estimates). You can also [add tasks or child items as checklists on your cards](add-task-checklists.md). +To add details to any work item, select the title. Or, you can directly modify any field that displays. For example, you can reassign a work item by selecting **Assigned To**. For a description of each field, see [Create your backlog, Add details, and estimates](../backlogs/create-your-backlog.md#estimates). You can also [add tasks or child items as checklists on your cards](add-task-checklists.md). [!INCLUDE [temp](../includes/note-user-assigned.md)] @@ -121,7 +93,7 @@ As work completes in one stage, update the status of an item by dragging it to a ## Update card fields -You can quickly update a field or reassign ownership directly from the board. If the field you want to update isn't showing, then customize the card, so it displays. For more information, see [Customize cards](../../boards/boards/customize-cards.md). +You can quickly update a field or reassign ownership directly from the board. If the field you want to update isn't showing, then customize the card, so it displays. You can also show other work item types besides bug and user stories, like change requests, incidents, issues, or other custom work item types. For more information, see [Customize cards](../../boards/boards/customize-cards.md) and [About configuring and customizing Azure Boards](../configure-customize.md). :::image type="content" source="media/alm-cc-update-card-field.png" alt-text="Screenshot showing update of card field."::: @@ -129,67 +101,31 @@ You can quickly update a field or reassign ownership directly from the board. If You can apply filters interactively to focus on a subset of work. For example, you can filter the board to focus on work assigned to at team member for a specific sprint. To start filtering, choose **Filter** :::image type="icon" source="../../media/icons/filter-icon.png" border="false":::. For more information, see [Filter your backlogs, boards, and plans](../backlogs/filter-backlogs-boards-plans.md). -::: moniker range="<= azure-devops-2019" -:::image type="content" source="../backlogs/media/filter-boards/filter-kb-choose-filter.png" alt-text="Screenshot showing enabled field-based filtering, earlier versions."::: -::: moniker-end - In the following example image, we filtered all items assigned to Jamal and Raisa. ::: moniker range=">= azure-devops-2020" :::image type="content" source="../backlogs/media/filter-boards/filter-kb-filters-chosen-services.png" alt-text="Screenshot showing filtering on assignment field."::: ::: moniker-end -::: moniker range="< azure-devops-2020" -:::image type="content" source="../backlogs/media/filter-boards/filter-kb-filters-chosen.png" alt-text="Screenshot showing filtering on assignment field, earlier versions."::: -::: moniker-end -## Invite others to work on your Kanban board +## Invite others to work on your board -All members of a project can view and contribute to your Kanban board. To invite users to contribute, copy the URL of your Kanban board and send it to those users. +All members of a project can view and contribute to your board. To invite users to contribute, copy the URL of your board and send it to those users. ::: moniker range=">= azure-devops-2020" -:::image type="content" source="media/quickstart/kanban-board-url-s155.png" alt-text="Screenshot showing red square surrounding the URL for the Kanban board."::: -::: moniker-end - -::: moniker range="azure-devops-2019" -:::image type="content" source="media/quickstart/kanban-board-url.png" alt-text="Screenshot showing red square surrounding the Kanban board URL."::: -::: moniker-end - -::: moniker range="tfs-2018" -:::image type="content" source="media/kanban-basics-url.png" alt-text="Screenshot showing highlighted URL for the Kanban board."::: +:::image type="content" source="media/quickstart/kanban-board-url-s155.png" alt-text="Screenshot showing red square surrounding the URL for the board."::: ::: moniker-end -To add users to your project, see [Add users to a project](../../organizations/security/add-users-team-project.md). - -## Enable live updates - -Enable live updates to automatically refresh your Kanban board when changes occur. With live updates enabled, you no longer have to select **F5** to see the latest changes. To view or modify work items, **View work items in this node** and **Edit work items in this node** permissions must be set to **Allow**. By default, the Contributors group has this permission set. Users with Stakeholder access for a private project can add work items and update status through drag-and-drop, but can't update fields displayed on cards. They can add tasks and change task status. - -::: moniker range=">= azure-devops-2019" -Choose the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: view options icon and move the slider for **Live updates** to On. - -:::image type="content" source="media/turn-live-updates-on-agile.png" alt-text="Screenshot showing moving the slider for Live updates to On."::: -::: moniker-end - -::: moniker range="tfs-2018" -Choose the :::image type="icon" source="../media/icons/live-updates-icon.png" border="false"::: **Live updates** icon. - -:::image type="content" source="media/turn-live-updates-on-agile.png" alt-text="Screenshot showing Kanban board, live updates icon."::: - -As one team member updates the status of a work item, other team members see those updates in real time as they occur. - -![GIF showing live update flow.](../boards/media/kanban-live-updates.gif) - -::: moniker-end +To add users to your project, see [Add users to a project](../../organizations/security/add-users-team-project.md). ## Monitor metrics -As with most Agile practices, Kanban encourages monitoring key metrics to fine tune your processes. After your team has used the Kanban board for several weeks, check out your Cumulative Flow Diagram (CFD). +As with most Agile practices, you're encouraged to monitor key metrics to fine tune your processes. After your team uses the board for several weeks, check out your Cumulative Flow Diagram (CFD). ::: moniker range=">= azure-devops-2020" Choose the **Analytics** tab, and then choose **View full report** for the CFD as shown in the following image. :::image type="content" source="media/quickstart/open-analytics.png" alt-text="Screenshot showing highlighted Analytics tab."::: -Use the interactive controls to choose the time frame, swimlanes, and workflow states or Kanban board columns. +Use the interactive controls to choose the time frame, swimlanes, and workflow states or board columns. Hover over a point in time to show how many work items are in a particular state. @@ -201,29 +137,15 @@ The following example image shows that on July 3, 101 items were in a *Researchi > The selections you make only get set for you, and persist across sessions until you change them. ::: moniker-end -::: moniker range="<= azure-devops-2019" -Choose the chart as shown in the following image. - -:::image type="content" source="media/kanban-basics-open-cfd.png" alt-text="Screenshot showing the cumulative flow diagram square, surrounded by red box."::: - -The CFD shows the count of items in each Kanban column for the past 30 weeks or less. From this chart, you can gain an idea of the amount of work in progress and lead time. Work in progress counts unfinished requirements. Lead time indicates the amount of time it takes to complete a requirement from the time it was first proposed. - -:::image type="content" source="media/ALM_KB_CumulativeFlow.png" alt-text="Screenshot showing Kanban board, cumulative flow diagram."::: -::: moniker-end - By monitoring these metrics, you can gain insight into how to optimize your processes and minimize lead time. For more information, see [Configure a cumulative flow chart](../../report/dashboards/cumulative-flow.md). -::: moniker range=">= azure-devops-2019" You can also add Analytics widgets to your dashboard. The Analytics Service is in preview and provides access to several widgets. For more information, see the following articles: - [Widgets based on the Analytics Service](../../report/dashboards/analytics-widgets.md) - [Add a widget to a dashboard](../../report/dashboards/add-widget-to-dashboard.md) - [What is the Analytics Service?](../../report/powerbi/what-is-analytics.md) -::: moniker-end -::: moniker range=">= azure-devops-2019" -## Can I view a Kanban board of work items defined by a query? -The [Query Based Boards](https://marketplace.visualstudio.com/items?itemName=realdolmen.EdTro-AzureDevOps-Extensions-QueryBasedBoards-Public) Marketplace extension supports viewing a flat-list query of work items as a Kanban board. The query can contain different work item types and work items defined in different projects. -::: moniker-end +## Can I view a board of work items defined by a query? +The [Query Based Boards](https://marketplace.visualstudio.com/items?itemName=realdolmen.EdTro-AzureDevOps-Extensions-QueryBasedBoards-Public) Marketplace extension supports viewing a flat-list query of work items as a board. The query can contain different work item types and work items defined in different projects. ## Next steps @@ -233,6 +155,5 @@ The [Query Based Boards](https://marketplace.visualstudio.com/items?itemName=rea ## Related articles - [Filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md) -- [Kanban key concepts](kanban-key-concepts.md) - [Cumulative flow diagram](../../report/dashboards/cumulative-flow.md) - [Cumulative flow, lead time, and cycle time guidance](../../report/dashboards/cumulative-flow-cycle-lead-time-guidance.md) diff --git a/docs/boards/boards/live-updates.md b/docs/boards/boards/live-updates.md deleted file mode 100644 index 3a809ddff6c..00000000000 --- a/docs/boards/boards/live-updates.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Enable live updates for a Kanban board -titleSuffix: Azure Boards -description: Learn how to turn live updates on or off for a Kanban board in Azure Boards. -ms.custom: boards-kanban -ms.topic: how-to -ms.service: azure-devops-boards -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 04/01/2022 ---- - - -# Enable live updates in Azure Boards - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - - - -Enable live updates to automatically refresh your Kanban board when changes occur. As other team members move or reorder cards, your board automatically updates with the changes. With live updates enabled, you no longer have to press F5 to see the latest changes. - -[!INCLUDE [temp](../includes/prerequisites-kanban.md)] - -::: moniker range=">= azure-devops-2019" - -Choose the :::image type="icon" source="../media/icons/view-options-icon.png" border="false"::: view options icon and move the slider for **Live updates** to On. - -> [!div class="mx-imgBorder"] -> ![Kanban board](media/turn-live-updates-on-agile.png) - -::: moniker-end - - -::: moniker range="tfs-2018" - -From the Kanban board, choose the :::image type="icon" source="../media/icons/live-updates-icon.png" border="false"::: **Live updates** icon. - -![Kanban board, live updates icon](../media/kanban-live-updates.png) - -::: moniker-end - - -As one team member updates the status of a work item, other team members see those updates in real time as they occur. - -![Live update](media/kanban-live-updates.gif) - - - -[!INCLUDE [temp](../includes/note-kanban-boards-teams.md)] - -## Related articles - -- [Filter your Kanban board](../backlogs/filter-backlogs-boards-plans.md) -- [Customize cards](customize-cards.md) diff --git a/docs/boards/boards/media/ALM_AC_ChangePriorities.png b/docs/boards/boards/media/ALM_AC_ChangePriorities.png index 1f457cf8999..4862ede24d5 100644 Binary files a/docs/boards/boards/media/ALM_AC_ChangePriorities.png and b/docs/boards/boards/media/ALM_AC_ChangePriorities.png differ diff --git a/docs/boards/boards/media/ALM_AC_CustomizeColumns.png b/docs/boards/boards/media/ALM_AC_CustomizeColumns.png deleted file mode 100644 index e0553b14107..00000000000 Binary files a/docs/boards/boards/media/ALM_AC_CustomizeColumns.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_AC_CustomizeColumnsDetailed.png b/docs/boards/boards/media/ALM_AC_CustomizeColumnsDetailed.png deleted file mode 100644 index be3157b43d7..00000000000 Binary files a/docs/boards/boards/media/ALM_AC_CustomizeColumnsDetailed.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_AC_DragItem.png b/docs/boards/boards/media/ALM_AC_DragItem.png index dbbbd467676..f2462861648 100644 Binary files a/docs/boards/boards/media/ALM_AC_DragItem.png and b/docs/boards/boards/media/ALM_AC_DragItem.png differ diff --git a/docs/boards/boards/media/ALM_AC_History.png b/docs/boards/boards/media/ALM_AC_History.png deleted file mode 100644 index 70fe2294f56..00000000000 Binary files a/docs/boards/boards/media/ALM_AC_History.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_AC_KanbanIntro.png b/docs/boards/boards/media/ALM_AC_KanbanIntro.png deleted file mode 100644 index 2d068b2deb5..00000000000 Binary files a/docs/boards/boards/media/ALM_AC_KanbanIntro.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_AC_LeftIcon.png b/docs/boards/boards/media/ALM_AC_LeftIcon.png deleted file mode 100644 index ce37c9c3e77..00000000000 Binary files a/docs/boards/boards/media/ALM_AC_LeftIcon.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_AC_Reassign.png b/docs/boards/boards/media/ALM_AC_Reassign.png index 8805423472c..5b19c53c329 100644 Binary files a/docs/boards/boards/media/ALM_AC_Reassign.png and b/docs/boards/boards/media/ALM_AC_Reassign.png differ diff --git a/docs/boards/boards/media/ALM_AC_RightIcon.png b/docs/boards/boards/media/ALM_AC_RightIcon.png deleted file mode 100644 index 65920506ad0..00000000000 Binary files a/docs/boards/boards/media/ALM_AC_RightIcon.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_AC_State.png b/docs/boards/boards/media/ALM_AC_State.png deleted file mode 100644 index 8629368435f..00000000000 Binary files a/docs/boards/boards/media/ALM_AC_State.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_AC_Update.png b/docs/boards/boards/media/ALM_AC_Update.png deleted file mode 100644 index 3e8cbdc7d27..00000000000 Binary files a/docs/boards/boards/media/ALM_AC_Update.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_AC_Workflow.png b/docs/boards/boards/media/ALM_AC_Workflow.png deleted file mode 100644 index e12d101a0bb..00000000000 Binary files a/docs/boards/boards/media/ALM_AC_Workflow.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_CC_KBCardOptions.png b/docs/boards/boards/media/ALM_CC_KBCardOptions.png deleted file mode 100644 index fc4b251cda7..00000000000 Binary files a/docs/boards/boards/media/ALM_CC_KBCardOptions.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_DD_DefinitionText.png b/docs/boards/boards/media/ALM_DD_DefinitionText.png deleted file mode 100644 index 61f5a106504..00000000000 Binary files a/docs/boards/boards/media/ALM_DD_DefinitionText.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_DD_EditDefinition.png b/docs/boards/boards/media/ALM_DD_EditDefinition.png deleted file mode 100644 index 446af5312dc..00000000000 Binary files a/docs/boards/boards/media/ALM_DD_EditDefinition.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_DD_InfoIcon.png b/docs/boards/boards/media/ALM_DD_InfoIcon.png deleted file mode 100644 index d47b22beae7..00000000000 Binary files a/docs/boards/boards/media/ALM_DD_InfoIcon.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_DD_IntroImage.png b/docs/boards/boards/media/ALM_DD_IntroImage.png deleted file mode 100644 index 706a226f6f3..00000000000 Binary files a/docs/boards/boards/media/ALM_DD_IntroImage.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_EW_CollapseLanes.png b/docs/boards/boards/media/ALM_EW_CollapseLanes.png deleted file mode 100644 index 4025934959b..00000000000 Binary files a/docs/boards/boards/media/ALM_EW_CollapseLanes.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_EW_DeleteLane.png b/docs/boards/boards/media/ALM_EW_DeleteLane.png deleted file mode 100644 index fc31c728ba8..00000000000 Binary files a/docs/boards/boards/media/ALM_EW_DeleteLane.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_EW_HistorySwimLanes.png b/docs/boards/boards/media/ALM_EW_HistorySwimLanes.png deleted file mode 100644 index 31ede4c0940..00000000000 Binary files a/docs/boards/boards/media/ALM_EW_HistorySwimLanes.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_EW_IntroChart_3C.png b/docs/boards/boards/media/ALM_EW_IntroChart_3C.png deleted file mode 100644 index 83054b2a73a..00000000000 Binary files a/docs/boards/boards/media/ALM_EW_IntroChart_3C.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_EW_MoveToNewLane.png b/docs/boards/boards/media/ALM_EW_MoveToNewLane.png deleted file mode 100644 index 0047219c530..00000000000 Binary files a/docs/boards/boards/media/ALM_EW_MoveToNewLane.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_EW_ReorderLanes.png b/docs/boards/boards/media/ALM_EW_ReorderLanes.png deleted file mode 100644 index 221e42f80c3..00000000000 Binary files a/docs/boards/boards/media/ALM_EW_ReorderLanes.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_KB_UpdateFieldOnCard.png b/docs/boards/boards/media/ALM_KB_UpdateFieldOnCard.png deleted file mode 100644 index ac6920c60c8..00000000000 Binary files a/docs/boards/boards/media/ALM_KB_UpdateFieldOnCard.png and /dev/null differ diff --git a/docs/boards/boards/media/ALM_SW.AddLane.png b/docs/boards/boards/media/ALM_SW.AddLane.png deleted file mode 100644 index e6cc878587d..00000000000 Binary files a/docs/boards/boards/media/ALM_SW.AddLane.png and /dev/null differ diff --git a/docs/boards/boards/media/WIP_1.png b/docs/boards/boards/media/WIP_1.png deleted file mode 100644 index dcbea5b0a3f..00000000000 Binary files a/docs/boards/boards/media/WIP_1.png and /dev/null differ diff --git a/docs/boards/boards/media/WIP_2.png b/docs/boards/boards/media/WIP_2.png index 1d2d8db35cd..30a6fdc607c 100644 Binary files a/docs/boards/boards/media/WIP_2.png and b/docs/boards/boards/media/WIP_2.png differ diff --git a/docs/boards/boards/media/WIP_5.png b/docs/boards/boards/media/WIP_5.png deleted file mode 100644 index 534c6effdac..00000000000 Binary files a/docs/boards/boards/media/WIP_5.png and /dev/null differ diff --git a/docs/boards/boards/media/add-columns-active-agile-update-1.png b/docs/boards/boards/media/add-columns-active-agile-update-1.png deleted file mode 100644 index 9773d76520d..00000000000 Binary files a/docs/boards/boards/media/add-columns-active-agile-update-1.png and /dev/null differ diff --git a/docs/boards/boards/media/add-columns-open-settings-ts.png b/docs/boards/boards/media/add-columns-open-settings-ts.png deleted file mode 100644 index fbea1b8441d..00000000000 Binary files a/docs/boards/boards/media/add-columns-open-settings-ts.png and /dev/null differ diff --git a/docs/boards/boards/media/add-columns-settings-dialog-add-test-ts.png b/docs/boards/boards/media/add-columns-settings-dialog-add-test-ts.png index 09ea96c10ec..a62ec3079d0 100644 Binary files a/docs/boards/boards/media/add-columns-settings-dialog-add-test-ts.png and b/docs/boards/boards/media/add-columns-settings-dialog-add-test-ts.png differ diff --git a/docs/boards/boards/media/alm-cc-move-card.png b/docs/boards/boards/media/alm-cc-move-card.png index 5250e1421a0..8effa6d55eb 100644 Binary files a/docs/boards/boards/media/alm-cc-move-card.png and b/docs/boards/boards/media/alm-cc-move-card.png differ diff --git a/docs/boards/boards/media/boards-columns-state-mapping.png b/docs/boards/boards/media/boards-columns-state-mapping.png new file mode 100644 index 00000000000..f8d46f866bf Binary files /dev/null and b/docs/boards/boards/media/boards-columns-state-mapping.png differ diff --git a/docs/boards/boards/media/c-cards-test-settings.png b/docs/boards/boards/media/c-cards-test-settings.png deleted file mode 100644 index 797aed60fac..00000000000 Binary files a/docs/boards/boards/media/c-cards-test-settings.png and /dev/null differ diff --git a/docs/boards/boards/media/checklists/add-task-menu.png b/docs/boards/boards/media/checklists/add-task-menu.png index 0b5a8438cfa..0ed991e9941 100644 Binary files a/docs/boards/boards/media/checklists/add-task-menu.png and b/docs/boards/boards/media/checklists/add-task-menu.png differ diff --git a/docs/boards/boards/media/columns/column-options-menu.png b/docs/boards/boards/media/columns/column-options-menu.png new file mode 100644 index 00000000000..a5feff30766 Binary files /dev/null and b/docs/boards/boards/media/columns/column-options-menu.png differ diff --git a/docs/boards/boards/media/columns/definition-of-done-defined.png b/docs/boards/boards/media/columns/definition-of-done-defined.png index e66cbdea27f..6f0571d66b7 100644 Binary files a/docs/boards/boards/media/columns/definition-of-done-defined.png and b/docs/boards/boards/media/columns/definition-of-done-defined.png differ diff --git a/docs/boards/boards/media/columns/kanban-settings-columns-active-column.png b/docs/boards/boards/media/columns/kanban-settings-columns-active-column.png index ed3128c2bf9..e05538a1ded 100644 Binary files a/docs/boards/boards/media/columns/kanban-settings-columns-active-column.png and b/docs/boards/boards/media/columns/kanban-settings-columns-active-column.png differ diff --git a/docs/boards/boards/media/columns/remove-column.png b/docs/boards/boards/media/columns/remove-column.png index f796b4bf244..3a41d5c4e34 100644 Binary files a/docs/boards/boards/media/columns/remove-column.png and b/docs/boards/boards/media/columns/remove-column.png differ diff --git a/docs/boards/boards/media/columns/split-columns-tfs-2018.png b/docs/boards/boards/media/columns/split-columns-tfs-2018.png deleted file mode 100644 index 3049f141a2c..00000000000 Binary files a/docs/boards/boards/media/columns/split-columns-tfs-2018.png and /dev/null differ diff --git a/docs/boards/boards/media/columns/split-columns.png b/docs/boards/boards/media/columns/split-columns.png index 37c44508452..909b800c064 100644 Binary files a/docs/boards/boards/media/columns/split-columns.png and b/docs/boards/boards/media/columns/split-columns.png differ diff --git a/docs/boards/boards/media/customize-cards/annotate-settings.png b/docs/boards/boards/media/customize-cards/annotate-settings.png deleted file mode 100644 index 80437784358..00000000000 Binary files a/docs/boards/boards/media/customize-cards/annotate-settings.png and /dev/null differ diff --git a/docs/boards/boards/media/customize-cards/open-config-dialog.png b/docs/boards/boards/media/customize-cards/open-config-dialog.png deleted file mode 100644 index 7b468ceb2dd..00000000000 Binary files a/docs/boards/boards/media/customize-cards/open-config-dialog.png and /dev/null differ diff --git a/docs/boards/boards/media/expedite/settings-swimlanes-add.png b/docs/boards/boards/media/expedite/settings-swimlanes-add.png index 12642846fe6..cef19d94edf 100644 Binary files a/docs/boards/boards/media/expedite/settings-swimlanes-add.png and b/docs/boards/boards/media/expedite/settings-swimlanes-add.png differ diff --git a/docs/boards/boards/media/expedite/swimlanes-remove.png b/docs/boards/boards/media/expedite/swimlanes-remove.png index 7ec07b3207f..9fddf850342 100644 Binary files a/docs/boards/boards/media/expedite/swimlanes-remove.png and b/docs/boards/boards/media/expedite/swimlanes-remove.png differ diff --git a/docs/boards/boards/media/expedite/swimlanes-reorder.png b/docs/boards/boards/media/expedite/swimlanes-reorder.png index c96bae73897..1bd010a13f9 100644 Binary files a/docs/boards/boards/media/expedite/swimlanes-reorder.png and b/docs/boards/boards/media/expedite/swimlanes-reorder.png differ diff --git a/docs/boards/boards/media/features-epics/add-user-story.png b/docs/boards/boards/media/features-epics/add-user-story.png index 5a946dde421..f01ee3b6a60 100644 Binary files a/docs/boards/boards/media/features-epics/add-user-story.png and b/docs/boards/boards/media/features-epics/add-user-story.png differ diff --git a/docs/boards/boards/media/features-epics/features-board-standard.png b/docs/boards/boards/media/features-epics/features-board-standard.png deleted file mode 100644 index defb046ab83..00000000000 Binary files a/docs/boards/boards/media/features-epics/features-board-standard.png and /dev/null differ diff --git a/docs/boards/boards/media/features-epics/features-with-stories-intro.png b/docs/boards/boards/media/features-epics/features-with-stories-intro.png deleted file mode 100644 index aae1146d963..00000000000 Binary files a/docs/boards/boards/media/features-epics/features-with-stories-intro.png and /dev/null differ diff --git a/docs/boards/boards/media/features-epics/open-features-board-standard.png b/docs/boards/boards/media/features-epics/open-features-board-standard.png deleted file mode 100644 index bbf9e5c5c14..00000000000 Binary files a/docs/boards/boards/media/features-epics/open-features-board-standard.png and /dev/null differ diff --git a/docs/boards/boards/media/features-epics/select-portfolio-level.png b/docs/boards/boards/media/features-epics/select-portfolio-level.png index c52fbd72a56..901eedf335d 100644 Binary files a/docs/boards/boards/media/features-epics/select-portfolio-level.png and b/docs/boards/boards/media/features-epics/select-portfolio-level.png differ diff --git a/docs/boards/boards/media/hover-test-summary.png b/docs/boards/boards/media/hover-test-summary.png new file mode 100644 index 00000000000..dffa1ebfe97 Binary files /dev/null and b/docs/boards/boards/media/hover-test-summary.png differ diff --git a/docs/boards/boards/media/i-test-add-test.png b/docs/boards/boards/media/i-test-add-test.png index 5a546fab827..37c0fe3b363 100644 Binary files a/docs/boards/boards/media/i-test-add-test.png and b/docs/boards/boards/media/i-test-add-test.png differ diff --git a/docs/boards/boards/media/i-test-case-form.png b/docs/boards/boards/media/i-test-case-form.png index b9d48e697ab..72e55945ad9 100644 Binary files a/docs/boards/boards/media/i-test-case-form.png and b/docs/boards/boards/media/i-test-case-form.png differ diff --git a/docs/boards/boards/media/i-test-drag-reparent.png b/docs/boards/boards/media/i-test-drag-reparent.png index d3987cee29c..5f663bcb3bf 100644 Binary files a/docs/boards/boards/media/i-test-drag-reparent.png and b/docs/boards/boards/media/i-test-drag-reparent.png differ diff --git a/docs/boards/boards/media/i-test-expanded-test-list.png b/docs/boards/boards/media/i-test-expanded-test-list.png index f50237c210f..beb66c1f485 100644 Binary files a/docs/boards/boards/media/i-test-expanded-test-list.png and b/docs/boards/boards/media/i-test-expanded-test-list.png differ diff --git a/docs/boards/boards/media/i-test-plan-suite.png b/docs/boards/boards/media/i-test-plan-suite.png index 90f06aecf33..e880e749001 100644 Binary files a/docs/boards/boards/media/i-test-plan-suite.png and b/docs/boards/boards/media/i-test-plan-suite.png differ diff --git a/docs/boards/boards/media/i-test-run-test.png b/docs/boards/boards/media/i-test-run-test.png index d0e23b51451..fecff9d4bf9 100644 Binary files a/docs/boards/boards/media/i-test-run-test.png and b/docs/boards/boards/media/i-test-run-test.png differ diff --git a/docs/boards/boards/media/i-test-update-status.png b/docs/boards/boards/media/i-test-update-status.png index 6a86417459d..aaf0e1f86d3 100644 Binary files a/docs/boards/boards/media/i-test-update-status.png and b/docs/boards/boards/media/i-test-update-status.png differ diff --git a/docs/boards/boards/media/kanban-basics-intro.png b/docs/boards/boards/media/kanban-basics-intro.png deleted file mode 100644 index e2db390fa31..00000000000 Binary files a/docs/boards/boards/media/kanban-basics-intro.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-basics-url.png b/docs/boards/boards/media/kanban-basics-url.png deleted file mode 100644 index ec30fc05964..00000000000 Binary files a/docs/boards/boards/media/kanban-basics-url.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-board-add-swimlane.png b/docs/boards/boards/media/kanban-board-add-swimlane.png deleted file mode 100644 index f379435a04e..00000000000 Binary files a/docs/boards/boards/media/kanban-board-add-swimlane.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-board-add-task-checklist.png b/docs/boards/boards/media/kanban-board-add-task-checklist.png deleted file mode 100644 index e8394813f82..00000000000 Binary files a/docs/boards/boards/media/kanban-board-add-task-checklist.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-board-card-style-rule-example.png b/docs/boards/boards/media/kanban-board-card-style-rule-example.png deleted file mode 100644 index adaea189950..00000000000 Binary files a/docs/boards/boards/media/kanban-board-card-style-rule-example.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-board-configure-split-columns.png b/docs/boards/boards/media/kanban-board-configure-split-columns.png deleted file mode 100644 index 072e147fc08..00000000000 Binary files a/docs/boards/boards/media/kanban-board-configure-split-columns.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-board-first-open-collapsed-checklists.png b/docs/boards/boards/media/kanban-board-first-open-collapsed-checklists.png deleted file mode 100644 index 86c25fd3e5e..00000000000 Binary files a/docs/boards/boards/media/kanban-board-first-open-collapsed-checklists.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-board-open-task-form.png b/docs/boards/boards/media/kanban-board-open-task-form.png deleted file mode 100644 index c79fba3fb5d..00000000000 Binary files a/docs/boards/boards/media/kanban-board-open-task-form.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-board-task-checklists-added.png b/docs/boards/boards/media/kanban-board-task-checklists-added.png deleted file mode 100644 index dec7fd0b4dc..00000000000 Binary files a/docs/boards/boards/media/kanban-board-task-checklists-added.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-card-customize-open-settings.png b/docs/boards/boards/media/kanban-card-customize-open-settings.png deleted file mode 100644 index b7bc76dce7d..00000000000 Binary files a/docs/boards/boards/media/kanban-card-customize-open-settings.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-card-customize-tag-colors.png b/docs/boards/boards/media/kanban-card-customize-tag-colors.png deleted file mode 100644 index c2245c05aed..00000000000 Binary files a/docs/boards/boards/media/kanban-card-customize-tag-colors.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-check-done-tasks.png b/docs/boards/boards/media/kanban-check-done-tasks.png deleted file mode 100644 index 17a88c86873..00000000000 Binary files a/docs/boards/boards/media/kanban-check-done-tasks.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-delete-column.png b/docs/boards/boards/media/kanban-delete-column.png deleted file mode 100644 index c1d956dc061..00000000000 Binary files a/docs/boards/boards/media/kanban-delete-column.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-live-updates.gif b/docs/boards/boards/media/kanban-live-updates.gif deleted file mode 100644 index 6ee9eeab689..00000000000 Binary files a/docs/boards/boards/media/kanban-live-updates.gif and /dev/null differ diff --git a/docs/boards/boards/media/kanban-quickstart-reduced-screensize.png b/docs/boards/boards/media/kanban-quickstart-reduced-screensize.png deleted file mode 100644 index 5c60288b813..00000000000 Binary files a/docs/boards/boards/media/kanban-quickstart-reduced-screensize.png and /dev/null differ diff --git a/docs/boards/boards/media/kanban-task-checklists.png b/docs/boards/boards/media/kanban-task-checklists.png deleted file mode 100644 index e899324a1b8..00000000000 Binary files a/docs/boards/boards/media/kanban-task-checklists.png and /dev/null differ diff --git a/docs/boards/boards/media/open-boards-backlog.png b/docs/boards/boards/media/open-boards-backlog.png deleted file mode 100644 index 612bd8a5d5f..00000000000 Binary files a/docs/boards/boards/media/open-boards-backlog.png and /dev/null differ diff --git a/docs/boards/boards/media/overview/kanban-basics-intro-tfs.png b/docs/boards/boards/media/overview/kanban-basics-intro-tfs.png deleted file mode 100644 index 4036b3acc54..00000000000 Binary files a/docs/boards/boards/media/overview/kanban-basics-intro-tfs.png and /dev/null differ diff --git a/docs/boards/boards/media/quickstart/add-new-item-agile-s155.png b/docs/boards/boards/media/quickstart/add-new-item-agile-s155.png index 7d31ca548e0..4b0397ef1a7 100644 Binary files a/docs/boards/boards/media/quickstart/add-new-item-agile-s155.png and b/docs/boards/boards/media/quickstart/add-new-item-agile-s155.png differ diff --git a/docs/boards/boards/media/quickstart/add-new-item-standard.png b/docs/boards/boards/media/quickstart/add-new-item-standard.png deleted file mode 100644 index 6215eb0fb3b..00000000000 Binary files a/docs/boards/boards/media/quickstart/add-new-item-standard.png and /dev/null differ diff --git a/docs/boards/boards/media/quickstart/board-selector.png b/docs/boards/boards/media/quickstart/board-selector.png deleted file mode 100644 index 14128705913..00000000000 Binary files a/docs/boards/boards/media/quickstart/board-selector.png and /dev/null differ diff --git a/docs/boards/boards/media/quickstart/open-kanban-board-agile-s155.png b/docs/boards/boards/media/quickstart/open-kanban-board-agile-s155.png index 59b4f37ecec..c25099f6b79 100644 Binary files a/docs/boards/boards/media/quickstart/open-kanban-board-agile-s155.png and b/docs/boards/boards/media/quickstart/open-kanban-board-agile-s155.png differ diff --git a/docs/boards/boards/media/quickstart/open-kanban-board-agile.png b/docs/boards/boards/media/quickstart/open-kanban-board-agile.png index 31a52c1ebcb..d82d41d25c1 100644 Binary files a/docs/boards/boards/media/quickstart/open-kanban-board-agile.png and b/docs/boards/boards/media/quickstart/open-kanban-board-agile.png differ diff --git a/docs/boards/boards/media/quickstart/open-kanban-board.png b/docs/boards/boards/media/quickstart/open-kanban-board.png deleted file mode 100644 index 149def4687c..00000000000 Binary files a/docs/boards/boards/media/quickstart/open-kanban-board.png and /dev/null differ diff --git a/docs/boards/boards/media/quickstart/select-kanban-team-board.png b/docs/boards/boards/media/quickstart/select-kanban-team-board.png index bb1d65eb27c..64a3a219660 100644 Binary files a/docs/boards/boards/media/quickstart/select-kanban-team-board.png and b/docs/boards/boards/media/quickstart/select-kanban-team-board.png differ diff --git a/docs/boards/boards/media/quickstart/select-product-backlog-agile.png b/docs/boards/boards/media/quickstart/select-product-backlog-agile.png new file mode 100644 index 00000000000..054cab1379c Binary files /dev/null and b/docs/boards/boards/media/quickstart/select-product-backlog-agile.png differ diff --git a/docs/boards/boards/media/rename-kanban-columns-direct-ts.png b/docs/boards/boards/media/rename-kanban-columns-direct-ts.png index 99d299ec6fc..eda48cdb00a 100644 Binary files a/docs/boards/boards/media/rename-kanban-columns-direct-ts.png and b/docs/boards/boards/media/rename-kanban-columns-direct-ts.png differ diff --git a/docs/boards/boards/media/rename-kanban-columns-direct.png b/docs/boards/boards/media/rename-kanban-columns-direct.png deleted file mode 100644 index 2bdad202e83..00000000000 Binary files a/docs/boards/boards/media/rename-kanban-columns-direct.png and /dev/null differ diff --git a/docs/boards/boards/media/reorder/move-to-position.png b/docs/boards/boards/media/reorder/move-to-position.png index bbae8289823..81286b2258f 100644 Binary files a/docs/boards/boards/media/reorder/move-to-position.png and b/docs/boards/boards/media/reorder/move-to-position.png differ diff --git a/docs/boards/boards/media/sequence-boards-boards-configure-board-settings.png b/docs/boards/boards/media/sequence-boards-boards-configure-board-settings.png new file mode 100644 index 00000000000..167c1077b1f Binary files /dev/null and b/docs/boards/boards/media/sequence-boards-boards-configure-board-settings.png differ diff --git a/docs/boards/boards/media/task-checklist-reorder-tasks.png b/docs/boards/boards/media/task-checklist-reorder-tasks.png deleted file mode 100644 index bb6bd847dac..00000000000 Binary files a/docs/boards/boards/media/task-checklist-reorder-tasks.png and /dev/null differ diff --git a/docs/boards/boards/media/turn-live-updates-on-agile.png b/docs/boards/boards/media/turn-live-updates-on-agile.png deleted file mode 100644 index 8b644850d85..00000000000 Binary files a/docs/boards/boards/media/turn-live-updates-on-agile.png and /dev/null differ diff --git a/docs/boards/boards/media/vso-column-settings-add-rename-columns-no-tags.png b/docs/boards/boards/media/vso-column-settings-add-rename-columns-no-tags.png deleted file mode 100644 index a7ad42a85c6..00000000000 Binary files a/docs/boards/boards/media/vso-column-settings-add-rename-columns-no-tags.png and /dev/null differ diff --git a/docs/boards/boards/media/vso-kanban-board-definition-of-done-no-tags.png b/docs/boards/boards/media/vso-kanban-board-definition-of-done-no-tags.png deleted file mode 100644 index 5558d45aeac..00000000000 Binary files a/docs/boards/boards/media/vso-kanban-board-definition-of-done-no-tags.png and /dev/null differ diff --git a/docs/boards/boards/media/vso-kanban-card-customize.png b/docs/boards/boards/media/vso-kanban-card-customize.png deleted file mode 100644 index d10a0ed8860..00000000000 Binary files a/docs/boards/boards/media/vso-kanban-card-customize.png and /dev/null differ diff --git a/docs/boards/boards/media/vso-kanban-split-columns-settings-analyze-no-tags.png b/docs/boards/boards/media/vso-kanban-split-columns-settings-analyze-no-tags.png deleted file mode 100644 index a34a663f1f7..00000000000 Binary files a/docs/boards/boards/media/vso-kanban-split-columns-settings-analyze-no-tags.png and /dev/null differ diff --git a/docs/boards/boards/media/vso-product-backlog-work-item-form-acceptance-criteria.png b/docs/boards/boards/media/vso-product-backlog-work-item-form-acceptance-criteria.png deleted file mode 100644 index 17a9f8f0c28..00000000000 Binary files a/docs/boards/boards/media/vso-product-backlog-work-item-form-acceptance-criteria.png and /dev/null differ diff --git a/docs/boards/boards/media/wip-columns-settings.png b/docs/boards/boards/media/wip-columns-settings.png index 5e0261f8b9b..3a52055dcc7 100644 Binary files a/docs/boards/boards/media/wip-columns-settings.png and b/docs/boards/boards/media/wip-columns-settings.png differ diff --git a/docs/boards/boards/toc.yml b/docs/boards/boards/toc.yml index 61d4c35e645..2f2ccbed0b8 100644 --- a/docs/boards/boards/toc.yml +++ b/docs/boards/boards/toc.yml @@ -1,13 +1,13 @@ -- name: About Kanban boards +- name: About boards href: kanban-overview.md -- name: Use your Kanban board +- name: Use your board href: kanban-quickstart.md - name: Add tasks or child items as checklists href: add-task-checklists.md displayname: tasks, subtasks, todo lists, bugs, tests, features, epics, user stories, product backlog items, requirements, annotations, parent - name: Add features & epics href: kanban-epics-features-stories.md -- name: Filter your Kanban board +- name: Filter your board href: ../backlogs/filter-backlogs-boards-plans.md displayname: reorder, group, parent, tags - name: Manage inline tests diff --git a/docs/boards/boards/wip-limits.md b/docs/boards/boards/wip-limits.md index 5c505f813b6..4a901cf82a4 100644 --- a/docs/boards/boards/wip-limits.md +++ b/docs/boards/boards/wip-limits.md @@ -1,7 +1,7 @@ --- title: Configure WIP limits titleSuffix: Azure Boards -description: Learn how to set Work In Progress Limits on the Kanban board in Azure Boards. +description: Learn how to set Work In Progress Limits on a board in Azure Boards. ms.custom: boards-kanban ms.service: azure-devops-boards ms.assetid: d18351c1-e9e1-4c16-869d-e15ca478c748 @@ -9,7 +9,7 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 06/07/2023 +ms.date: 06/07/2024 --- @@ -17,85 +17,79 @@ ms.date: 06/07/2023 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -An essential Kanban practice—Work in Progress limits, referred to as "WIP limits"—constrains the amount of work your team undertakes at each work stage. It's designed to focus your team on completing items before starting new work. While counter-intuitive at first, many teams find WIP limits helps them increase their productivity and improve their software quality. +Work-in-Progress (WIP) limits, a crucial [Kanban](kanban-overview.md) practice, restrict the work your team takes on at each stage. By emphasizing completion before starting new work, teams often experience increased productivity and improved software quality. -You define WIP limits for each work stage, corresponding to each intermediate column. The limit sets a soft constraint on the number of items allowed within the column. Nothing prevents you from moving more items into the column and exceeding the limit. Your Kanban board shows the count of items at each stage next to each limit. +Setting WIP limits for each stage adds soft constraints on the number of items allowed in the corresponding columns. Exceeding these limits is possible, but your board displays item counts next to each limit. Use this article as a guide for setting and implementing WIP limits. -[Setting WIP limits](#Set) is simple, but adhering to the limits takes a team commitment. Successful adoption of WIP limits involves a culture change. It moves teams from a focus on individual productivity to one of team productivity. - -For more information, see [Kanban overview](kanban-overview.md). +## Prerequisites [!INCLUDE [temp](../includes/prerequisites-team-settings.md)] - + ## Determine initial WIP limits -Have your team determine the initial WIP limits to set and how to use and monitor them. Few rules apply to what numbers to set as they can vary based on several factors. Take the following actions to help you determine what limits to set: +Do the following actions to determine initial WIP limits. -* Set limits based on current works in progress. Count the items present in your existing Kanban columns. -* Set limits that don't exceed two or three items per team member that works within a stage. For example, if you have three team members and each team member can work on no more than two tasks at a time, the resulting WIP limit is 6 (= 3 developers X 2 tasks/developer). -* Start with low limits to help your team discover bottlenecks more quickly and identify process issues to address. +* **Assess current work:** Count the items present in your existing columns to set initial WIP limits. +* **Set team-based limits:** Set limits that don't exceed two or three items per team member working within a stage. For instance, with three team members, the WIP limit is six, three developers X two tasks/developer. +* **Start low:** Begin with low limits to identify bottlenecks and address process issues promptly. - + ## Keep within WIP limits -After you've set your WIP limits, you'll want to track how well your team keeps within the limits. +After you set your WIP limits, track how well your team keeps within the limits. -Respecting WIP limits means teams don't pull items into a column if doing so causes the number of items in the column to exceed the column limit. When they do, your Kanban board provides immediate feedback. This feedback should act as a signal to the team to focus immediately on activities to reduce the number of items in the column. +Respecting WIP limits means teams don't pull items into a column if doing so causes the number of items in the column to exceed the column limit. When they do, your board provides immediate feedback. This feedback should act as a signal to the team to focus immediately on activities to reduce the number of items in the column. -:::image type="content" source="media/WIP_2.png" alt-text="Example image of a Kanban board showing a column over the WIP limit."::: +:::image type="content" source="media/WIP_2.png" alt-text="Example image of a board showing a column over the WIP limit."::: Although simple in theory, keeping within WIP limits can force individuals, teams, and organizations out of their comfort zone. Team members who like to multitask might feel constrained. Others might find themselves without work as they wait for work to complete at an upstream stage. To gain the advantages of constraining work-in-progress, have your team meet frequently to discuss the process changes taking place. - + ## Identify bottlenecks To optimize the flow of value, you naturally want to identify and eliminate bottlenecks. Bottlenecks indicate waste exists in the overall workflow process. -By monitoring your Kanban board over time, you can learn where bottlenecks occur. When several items sit in a column unworked for several days, a bottleneck has occurred. Bottlenecks typically occur when WIP limits are too high. However, no bottlenecks could indicate that WIP limits are too low. +By monitoring your board over time, you can learn where bottlenecks occur. When several items sit in a column unworked for several days, a bottleneck occurred. Bottlenecks typically occur when WIP limits are too high. However, no bottlenecks could indicate that WIP limits are too low. -Taking periodic snapshots of your Kanban board can visually catalog where work flows smoothly and where bottlenecks appear. +Taking periodic snapshots of your board can visually catalog where work flows smoothly and where bottlenecks appear. :::image type="content" source="media/WIP_3.png" alt-text="Screenshot of example snapshots."::: Such snapshots can show your team the following information: -* How many items on average exist within a workflow stage/column -* How many items are being worked versus team members who work within a workflow stage/column -* How many and which items remained in a workflow stage/column for long periods of time -* How many items did the team complete at the end of a one, two, or three week period +* Average number of items within a workflow stage or column +* The ratio of items being worked on to the number of team members within a workflow stage or column +* Number of items that stayed in a workflow stage or column for extended durations +* Number of completed items and average throughput rate over a specific time period - + ## Eliminate waste -Because bottlenecks signal waste in your workflow process, you need to identify the source of the waste. Kanban defines waste as anything not strictly needed to produce desired outcomes. - -Common wastes in software development include: +To address bottlenecks in your workflow process, it’s essential to identify the sources of waste. Waste refers to anything not strictly necessary for achieving desired outcomes. In software development, common forms of waste include: * Unused code or features -* Defects leading to rework -* Delays or time spent waiting for something -* Handoffs from one person, team, or business process to another +* Defects requiring rework +* Delays or waiting time +* Handoffs between teams or processes * Insufficient requirements -* Slow or poor communication +* Inefficient communication -Eliminating waste calls for team discussions to identify causes and solutions acceptable to the team. +To eliminate waste, engage in team discussions to identify causes and collaboratively find acceptable solutions. - + ## Set WIP limits -With an understanding of how you want to use WIP limits, do the following steps to set them. If you haven't [mapped your team's work flow to Kanban columns](add-columns.md), do that first. +With an understanding of how you want to use WIP limits, do the following steps to set them. Ensure you already [mapped your team's work flow to columns](add-columns.md). -::: moniker range=">= azure-devops-2019" - -1. [Open your Kanban board](kanban-quickstart.md). +1. [Open your board](kanban-quickstart.md). 2. Select the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board and set general team settings. @@ -103,63 +97,44 @@ With an understanding of how you want to use WIP limits, do the following steps 3. Choose **Columns** and then a column tab to set the WIP limit for that column. - :::image type="content" source="media/wip-columns-settings.png" alt-text="Screenshot showing Kanban board, Customize columns, default columns, Agile process, set WIP limits."::: - - > [!NOTE] - > Different column titles and choices are available based on the [process](../work-items/guidance/choose-process.md) that was used to create your project and whether your team has chosen to [treat bugs like requirements or like tasks](../../organizations/settings/show-bugs-on-backlog.md). - -4. When you're done, select **Save**. - -::: moniker-end - -::: moniker range="tfs-2018" -1. [Open your Kanban board](kanban-quickstart.md). - -2. Choose ![settings icon](../../media/icons/team-settings-gear-icon.png) to open the common configuration settings dialog for the Kanban board. - - :::image type="content" source="media/add-columns-open-settings-ts.png" alt-text="Screenshot showing Kanban board, open common configuration settings."::: - -3. Choose **Columns** and then a column tab to set the WIP limit for that column. - - :::image type="content" source="media/wip-columns-settings.png" alt-text="Screenshot of the Kanban board, Customize columns, default columns, Agile process, set WIP limits."::: + :::image type="content" source="media/wip-columns-settings.png" alt-text="Screenshot showing board, Customize columns, default columns, Agile process, set WIP limits."::: > [!NOTE] > Different column titles and choices are available based on the [process](../work-items/guidance/choose-process.md) that was used to create your project and whether your team has chosen to [treat bugs like requirements or like tasks](../../organizations/settings/show-bugs-on-backlog.md). -4. When you're done, select **Save**. -::: moniker-end +4. When you're done, select **Save**. ## WIP limits, challenges, and solutions -Teams occasionally exceed WIP limits by one or two items. However, if your team frequently exceeds the limits by three or more items, they should review processes or adjust the limits. +Teams occasionally exceed WIP limits by one or two items. If you frequently exceed limits by three or more items, review processes or adjust the limits. -After a team has worked with WIP limits for several weeks, discuss the challenges team members have. Then, decide which solutions they'd like to use and adjust the limits as needed. The following list, although not exhaustive, indicates some of the common challenges teams come across and proven solutions to overcome them. +Your team should engage in discussions after several weeks of using WIP limits. Identify challenges, collaboratively decide on solutions, and adjust limits as needed. The following list isn't exhaustive, but covers common challenges teams and proven solutions. ### WIP challenges -* **Social dynamics.** When it comes to following rules, team members can feel challenged. Some naturally want to rebel. Others don't see that the rule applies to them or don't see what they do as breaking the rules. Some team members may take on extra work that's outside the scope of what's been agreed to. And, still others don't want to give up multitasking as they believe it's the key to their productivity and individual achievement. +* **Social dynamics:** Team members might struggle with following rules. Some rebel, others misunderstand applicability, and some take on extra work beyond agreed limits. Multitasking beliefs can also hinder adherence. -* **Variability of work in progress.** Wide variability in the size of work items—users stories and bugs—can negatively influence the overall workflow. For example, items with estimates that vary in size from 4 hours to 14 days, or 2 to 55 story points, can't be counted the same when it comes to constraining work in progress. +* **Variability of work:** Uneven item sizes, for example, user stories and bugs, impact workflow. Varying estimates, like hours, days, and story points, require tailored WIP constraints. -* **Ignoring systemic problems.** Instead of addressing workflow problems when bottlenecks occur, teams soldier on, putting in more time to overcome the bottleneck. +* **Ignoring systemic issues:** Teams often persist through bottlenecks instead of tackling underlying workflow issues. -* **Culture change.** Adopting WIP limits introduces changes to the system, culture, and team. +* **Culture change:** Implementing WIP limits involves system, cultural, and team adjustments. ### Solutions for managing WIP -* **Build a culture of team productivity.** Address the natural tension that exists between individual productivity versus team productivity. Identify ways in which team members can enhance the overall productivity of the team and workflow process. +* **Build a culture of team productivity:** Address the tension between individual and team productivity. Encourage practices that enhance overall workflow efficiency. -* **Size work to minimize variability.** Before work starts on any item, the team should discuss the overall size of work required and determine if it can be broken down into smaller tasks. +* **Size work appropriately:** Discuss work size before starting tasks. Break down large items into smaller tasks. -* **Focus on the flow of high priority items.** When idle, team members ask how they can help move an upstream item forward. When blocked or challenged to deliver an item on time, team members ask for help with completing an item. +* **Prioritize high-value items:** When idle, focus on moving upstream items forward. Seek help when blocked or facing delivery challenges. -* **Resource team capacity for each work stage.** Bottlenecks can occur when there aren't enough specialists who work in a particular stage. Determine ways to either increase team skills within each work stage, or add resources as needed to meet an understaffed work stage. +* **Resource team allocation:** Ensure adequate specialists in each work stage to prevent bottlenecks. -* **Build shared understanding.** Continuously strive to increase the team's understanding of how to work using Kanban practices. Take actions that allow team members to contribute to process changes. Consider scheduling regular retrospectives or team meetings to discuss what works well and what needs changing. Document team policies to limit ambiguity. +* **Build shared understanding:** Foster team understanding of [Kanban](kanban-overview.md) practices. Hold regular retrospectives and document policies. -* **Use metrics to adjust processes.** Periodically check Kanban metrics of work in progress and lead time to determine when changes need to be made. +* **Make metrics-driven adjustments:** Monitor WIP and lead time metrics for process adjustments. -* **Manage culture changes mindfully.** People want to do their best work—a core tenet underlying Kanban and its associated disciplines. Apply change management principles as you adopt new practices. Create greater ownership within the team for the success of implementing WIP limits. +* **Manage culture change:** Apply change management principles and promote team ownership during WIP limit implementation. ## Related articles diff --git a/docs/boards/configure-customize.md b/docs/boards/configure-customize.md index 7f475ae3a1e..540a98300d6 100644 --- a/docs/boards/configure-customize.md +++ b/docs/boards/configure-customize.md @@ -1,23 +1,25 @@ --- title: Configure and customize Azure Boards titleSuffix: Azure Boards -description: Learn about choices to customize or configure Azure Boards and the impact on tools available. +description: Learn about options to customize or configure Azure Boards and the effect on tools available. ms.service: azure-devops-boards ms.topic: overview ms.assetid: ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 03/17/2023 +ms.date: 03/15/2024 --- -# Configure and customize Azure Boards +# About configuring and customizing Azure Boards [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -This article provides guidance and links to more information for configuring and customizing Azure Boards to support portfolio management, calendar views for status updates, track dependencies, and monitor time estimates and actual work completed. We recommend these tasks for administrators who oversee multi-team projects. + You can configure and customize Azure Boards in many ways, to better manage your portfolio, dependencies, and monitoring. We recommend the tasks covered in this article especially for administrators who are responsible for managing multi-team projects. -For quick access to common tasks, see [Customize cards](boards/customize-cards.md), [Manage columns](backlogs/set-column-options.md), [Expedite work with swimlanes](boards/expedite-work.md), and [Configure your backlog](backlogs/configure-your-backlog-view.md). +**Quick access to common tasks:** + +[Customize cards](boards/customize-cards.md) | [Manage columns](backlogs/set-column-options.md) | [Expedite work with swimlanes](boards/expedite-work.md) | [Configure your backlog](backlogs/configure-your-backlog-view.md). > [!NOTE] > Most of the guidance in this article is valid for both the cloud and on-premises versions. However, some of the features included in this article, such as Rollup, Analytics, and some portfolio planning tools, are only available for the cloud at this time. @@ -37,7 +39,7 @@ The following table summarizes the primary items you should consider as you stru - How many teams you want to define - How to structure area paths to support portfolio management views - Field customizations - - Work item type customizations or custom work item types + - Custom work item types (WITs) - Portfolio backlog customizations - Workflow customizations :::column-end::: @@ -59,17 +61,17 @@ Customize your work tracking building blocks and tools to support business needs ## Work item types and portfolio backlogs -When you create a project in Azure Boards, you first select a process. [Each process](work-items/guidance/choose-process.md) (Agile, Basic, Scrum, and CMMI) supports a hierarchy of work item types, including product and portfolio backlogs. Default work item types for each process are listed in corresponding tabs, with backlogs under **Requirements** and tasks under **Task**. +When you create a project in Azure Boards, you first select a process. [Each process](work-items/guidance/choose-process.md) (Agile, Basic, Scrum, and CMMI) supports a hierarchy of WITs, including product and portfolio backlogs. Default WITs for each process are listed in corresponding tabs, with backlogs under **Requirements** and tasks under **Task**. [!INCLUDE [work-item-types](includes/work-item-types.md)] -You can add custom work item types at each level, and even add custom portfolio backlogs. Here, for example, is a project that added Objectives and Key Results as custom work item types and corresponding portfolio backlogs to the Scrum process. +You can add custom WITs at each level, and even add custom portfolio backlogs. Here, for example, is a project that added Objectives and Key Results as custom WITs and corresponding portfolio backlogs to the Scrum process. :::image type="content" source="media/config-custom/portfolio-backlogs-objectives-results.png" alt-text="Objectives and Key Results as additional portfolio backlogs"::: ## Work tracking options and recommended usage -Teams can choose which work item types they use to track their work. The following table summarizes the main options, recommended usage, and supported tasks and tools. +Teams can choose which WITs they use to track their work. The following table summarizes the main options, recommended usage, and supported tasks and tools. :::row::: :::column span=""::: @@ -93,7 +95,7 @@ Teams can choose which work item types they use to track their work. The followi :::column-end::: :::column span="2"::: **Not recommended** - There's no way to quickly enter new tasks in a backlog nor prioritize a backlog of tasks. In addition, there's no support for calendar views, cross-team views, or portfolio planning + There's no way to quickly enter new tasks in a backlog nor prioritize a backlog of tasks. Also, there's no support for calendar views, cross-team views, or portfolio planning :::column-end::: :::row-end::: :::row::: @@ -109,12 +111,12 @@ Teams can choose which work item types they use to track their work. The followi - Plan and track capacity: [Sprint capacity tool](sprints/set-capacity.md) - Track estimated and remaining work: [Taskboard](sprints/adjust-work.md) - Monitor sprint burndown based on remaining work such as hours or days: [Sprint burndown](../report/dashboards/configure-sprint-burndown.md?bc=%252fazure%252fdevops%252fboards%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fboards%252ftoc.json) - - Conduct daily scrums, update and monitor task status: [Sprint Taskboard](sprints/task-board.md) + - Conduct daily scrums, update, and monitor task status: [Sprint Taskboard](sprints/task-board.md) - Estimate work: [Define Story Points, Effort, or Size](backlogs/create-your-backlog.md#add-details-and-estimates-to-backlog-items) - View progress bars, counts, or sums of rollup on tasks: [Rollup](backlogs/display-rollup.md) - Track dependencies across teams and projects: [Delivery Plans](plans/track-dependencies.md) - Many teams start out using Scrum methods to track and plan their work using the tools available through the Sprints hub. The Sprints tools support estimating and tracking remaining work and use of capacity planning. If you don't plan on using these tools, then adding child-dependent tasks is optional. Developers might add them simply as a checklist of items they need to complete a user story or backlog requirement. + Many teams start out using Scrum methods to track and plan their work using the tools available through the Sprints hub. The Sprints tools support estimating and tracking remaining work and use of capacity planning. If you don't plan on using these tools, then adding child-dependent tasks is optional. Developers might add them as a checklist of items they need to complete a user story or backlog requirement. :::column-end::: :::row-end::: :::row::: @@ -135,7 +137,7 @@ Teams can choose which work item types they use to track their work. The followi :::row-end::: :::row::: :::column span=""::: - Requirements grouped under portfolio work item types, such as epics and features + Requirements grouped under portfolio WITs, such as epics and features :::column-end::: :::column span="2"::: **Supports calendar views, cross-team views, and portfolio planning** @@ -151,9 +153,9 @@ Teams can choose which work item types they use to track their work. The followi :::column-end::: :::row-end::: -## Configure and customization options +## Options to configure and customize -The following table indicates the areas you can configure and customize and the tools impacted by those customizations. You customize each area at the Organization, Project, or Team level as noted, or a combination of two. For a description of the Standard tools, Analytics tools, and Portfolio planning tools, see [What is Azure Boards](get-started/what-is-azure-boards.md), [In-context reports: Work tracking](../report/dashboards/overview.md#in-context-reports-work-tracking), and [Plans (Agile at scale)](plans/index.md). +The following table shows the areas you can configure and customize and the tools impacted by those customizations. You can customize each area at the Organization, Project, or Team level as noted, or a combination of two. For a description of the Standard tools, Analytics tools, and Portfolio planning tools, see [What is Azure Boards](get-started/what-is-azure-boards.md), [In-context reports: Work tracking](../report/dashboards/overview.md#in-context-reports-work-tracking), and [Plans (Agile at scale)](plans/index.md). :::row::: :::column span="1"::: **Configure or customize** @@ -219,8 +221,8 @@ The following table indicates the areas you can configure and customize and the :::row::: :::column span="1"::: [Show bugs on backlogs & boards (Team)](../organizations/settings/show-bugs-on-backlog.md) - Custom work item types, Product backlog (Process) - Custom work item types, Taskboard (Process) + Custom WITs, Product backlog (Process) + Custom WITs, Taskboard (Process) :::column-end::: :::column span="1"::: - Boards>Product board @@ -237,7 +239,7 @@ The following table indicates the areas you can configure and customize and the :::row-end::: :::row::: :::column span="1"::: - Custom work item types, Portfolio backlog (Process) + Custom WITs, Portfolio backlog (Process) More portfolio backlogs (Process) :::column-end::: :::column span="1"::: @@ -291,19 +293,19 @@ The following table indicates the areas you can configure and customize and the :::column-end::: :::row-end::: - + ## Area paths, product teams, and portfolio management -Area paths are used to group work items by product, feature, or business areas and to support teams responsible for work assigned to those areas. You can define a hierarchical set of area paths or a flat set. Typically, you define a hierarchical set of area paths when you want to support a business hierarchy that wants to track progress of several teams. +Use area paths to group work items by product, feature, or business areas and to support teams responsible for work assigned to those areas. You can define a hierarchical set of area paths or a flat set. Typically, you define a hierarchical set of area paths to support a business hierarchy that wants to track progress of several teams. ### Area paths and hierarchical grouping -The two main ways to group work items are by area path and by parenting them under a portfolio work item type as described early in this article. The two aren't mutually exclusive. Note the distinctions between the two usages: +The two main ways to group work items are by area path and by [parenting them under a portfolio WIT](#area-paths-and-hierarchical-grouping) as described early in this article. The two aren't mutually exclusive. Here are their differences: - Area paths assigned to a team determine what work items appear in a team view: product backlog, portfolio backlog, delivery plans, or other portfolio planning tool - Grouping work items under a parent feature or epic determine what rollup views are supported and how work appears in a portfolio planning tool -You can also assign tags to work items to group them for query and filter purposes. So when you structure your teams and projects, you want to make sure you understand how you use these grouping tools to support your business needs. Your choices impact the use of portfolio planning tools. +You can also assign tags to work items to group them for query and filter purposes. So when you structure your teams and projects, make sure you understand how you use these grouping tools to support your business needs. Your choices affect the use of portfolio planning tools. ### Area path-dependent tools @@ -311,120 +313,108 @@ You can also assign tags to work items to group them for query and filter purpos ### Area paths and team assignments -A default team and default area path are defined for each project. For small teams, a single team is sufficient to begin planning and tracking work. As organizations grow, however, it's useful to add teams to support their ability to manage their backlog and sprints. - -Here's an example of area paths and their assignment to teams, which support portfolio management views for the Account Management and Service Delivery teams. +Each project has a default team and default area path. In some cases, there's only one team to plan and track work. As organizations grow, however, you might add more teams to manage the backlog and sprints. -> [!div class="mx-imgBorder"] -> ![Screenshot of Area paths and team assignments.](media/config-custom/area-path-team-assignments.png) +The following example shows area paths and their assignments to teams, which support portfolio management views for the Account Management and Service Delivery teams. -- You create hierarchical area paths to support sub categories of features and product areas -- To provide portfolio views, you assign two or more area paths and include subareas to a portfolio management team -- Area paths assigned to a team determine what work items are filtered in a team view: product backlog, portfolio backlog, delivery plans, or other portfolio planning tool -- Grouping work items under a parent feature or epic determine what rollup views are supported and how work appears in a calendar view such as Feature Timeline and Epic Roadmap +:::image type="content" source="media/config-custom/area-path-team-assignments.png" alt-text="Screenshot of Area paths and team assignments."::: -Prior to adding teams, we recommend you read the following articles: +For more information, see the following articles: - [Portfolio management](plans/portfolio-management.md) - [About area paths](../organizations/settings/about-areas-iterations.md?bc=%252fazure%252fdevops%252fboards%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fboards%252ftoc.json) - [About teams and Agile tools](../organizations/settings/about-teams-and-settings.md?bc=%252fazure%252fdevops%252fboards%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fboards%252ftoc.json) - [Agile culture](plans/agile-culture.md). -Recommendations: -- Consider what upper management may want to view and how to best support them +**Recommendations:** +- Consider what upper management needs to know and how to best support them - Consider how you want to use rollup both for a team and portfolio management - Define epics and scenarios for large initiatives that take two or more sprints to complete +- Create hierarchical area paths to support sub categories of features and product areas - Define requirements for work that can be accomplished in a single sprint and can be assigned to a single individual - Define tasks to track more granular details or when you want to track time spent working > [!TIP] -> - Work items can only be assigned to a single individual. When you define work items, consider how many work items are needed to assign the work to those individuals tasked to complete the work. -> - Choose the Node Name field as a column option to view the leaf area node in a backlog list or board card. For more information, see [Customize cards](boards/customize-cards.md) +> - You can only assign a work item to a single individual. When you define work items, consider how many work items you need and who to assign them to. +> - Choose the `Node Name` field as a column option to view the leaf area node in a backlog list or board card. For more information, see [Customize cards](boards/customize-cards.md). > - Don't create parent-child links among work items of the same type, such as story-story, bug-bug, task-task. -Most Azure Boards tools support a filtered view of work items based on area path and/or iteration path. More filters can also be applied based on keyword, assignment, work item type, and more. +Most Azure Boards tools support a filtered view of work items based on area path or iteration path. You can also apply more filters based on keyword, assignment, WIT, and more. - + -## Treat bugs as requirements or tasks +## Bugs as requirements or tasks -Each team can choose how they want to manage bugs. Some teams like to track bugs along with requirements on the backlog. Other teams like to track bugs as tasks performed in support of a requirement. The bugs then appear on their [taskboard](sprints/task-board.md). +Each team can choose how they want to manage bugs. Some teams like to track bugs along with requirements on the backlog. Other teams like to track bugs as tasks performed in support of a requirement. The bugs then appear on their [Taskboard](sprints/task-board.md). If you use the Scrum process, your default setup is to track bugs along with product backlog items (PBIs). If you work in a project based on the [Agile or CMMI processes](work-items/guidance/choose-process.md), bugs don't automatically appear on your backlog. Determine with your team how you want to manage bugs. Then, [change your team settings](../organizations/settings/show-bugs-on-backlog.md) accordingly. > [!TIP] -> After you refresh a backlog or board and you don't see bugs where you expect them, review [How backlogs and boards display hierarchical (nested) items](backlogs/resolve-backlog-reorder-issues.md#leaf-nodes). Only leaf nodes of nested items appear on sprint Taskboards. - - +> After you refresh a backlog or board and you don't see bugs where you expect them, review [How backlogs and boards display hierarchical (nested) items](backlogs/resolve-backlog-reorder-issues.md). Only leaf nodes of nested items appear on sprint Taskboards. ::: moniker range="azure-devops" -## Add system work item types to a backlog +## System WITs on a backlog To track issues or impediments along with your requirements or in a portfolio backlog, add them to your custom Inherited process. For more information, see [Customize your backlogs or boards (Inheritance process)](../organizations/settings/work/customize-process-backlogs-boards.md#add-oob-to-backlog). ::: moniker-end - - + + ## Rollup, hierarchy, and portfolio management Rollup columns allow you to view progress bars or totals of numeric fields or descendant items within a hierarchy. Descendant items correspond to all child items within the hierarchy. You can add one or more rollup columns to a product or portfolio backlog. -Here we show **Progress by all Work Items** which displays progress bars for ascendant work items based on the percentage of descendant items that have been closed. +Here we show **Progress by all Work Items**, which displays progress bars for ascendant work items based on the percentage of closed descendant items. -> [!div class="mx-imgBorder"] -> ![Screenshot of backlog, Progress bars showing rollup by work items.](media/config-custom/progress-by-work-items.png) +:::image type="content" source="media/config-custom/progress-by-work-items.png" alt-text="Screenshot of backlog, Progress bars showing rollup by work items."::: ::: moniker range="azure-devops" -In addition, the new [Delivery Plans](plans/review-team-plans.md) supports rollup views of epics, features, and other custom portfolio backlogs. +[Delivery Plans](plans/review-team-plans.md) supports rollup views of epics, features, and other custom portfolio backlogs. -> [!div class="mx-imgBorder"] -> ![Screenshot showing Delivery Plans Progress rollup view of four scenarios.](plans/media/plans/rollup-view.png) +:::image type="content" source="plans/media/plans/rollup-view.png" alt-text="Screenshot showing Delivery Plans Progress rollup view of four scenarios."::: ::: moniker-end - + -## Iteration paths, sprints, releases, and versioning +## Iteration paths sprints releases & versioning -Iteration paths support Scrum and Scrumban processes where work is assigned to a set time period. Iteration paths allow you to group work into sprints, milestones, or other event-specific or time-related period. Each iteration or sprint corresponds to a regular time interval referred to as a sprint cadence. Typical sprint cadences are two weeks, three weeks, or a month long. For more information about Iteration paths, see [About area and iteration paths](../organizations/settings/about-areas-iterations.md?toc=/azure/devops/boards/toc.json). +Iteration paths support Scrum and Scrumban processes where work is assigned to a set time period. Iteration paths allow you to group work into sprints, milestones, or other event-specific or time-related period. Each iteration or sprint corresponds to a regular time interval referred to as a sprint cadence. Typical sprint cadences are two weeks, three weeks, or a month long. For more information, see [About area and iteration paths](../organizations/settings/about-areas-iterations.md?toc=/azure/devops/boards/toc.json). Iteration paths can be a flat list, or grouped under release milestones as shown in the following image. -> [!div class="mx-imgBorder"] -> ![Screenshot of Iteration paths, grouped.](media/config-custom/iteration-paths-flat-or-grouped.png) +:::image type="content" source="media/config-custom/iteration-paths-flat-or-grouped.png" alt-text="Screenshot of Iteration paths, grouped."::: -> [!NOTE] -> While Iteration Paths don't impact Kanban board tools, you can use Iteration Paths as a filter on boards. For more information, see [Filter your Kanban board](./backlogs/filter-backlogs-boards-plans.md). +While Iteration Paths don't affect board tools, you can use Iteration Paths as a filter on boards. For more information, see [Filter your board](./backlogs/filter-backlogs-boards-plans.md). [!INCLUDE [temp](includes/list-sprint-dependent-tools.md)] ## Time tracking -Most organizations following Scrum processes use time estimates for Sprint capacity planning. Azure Boards tools fully support tracking time for this purpose. The main field used is the task Remaining Work field, which typically zeros out at the end of the sprint. +Most organizations following Scrum processes use time estimates for Sprint capacity planning. Azure Boards tools fully support tracking time for this purpose. The main field used is the task `Remaining Work` field, which typically zeros out at the end of the sprint. -However, some organizations require time tracking to support other purposes, such as for billing or maintaining time allocation records. Time values for estimated work and completed work are of interest. The Agile and CMMI processes provide these fields—[Original Estimate, Completed Work, Remaining Work](queries/query-numeric.md#fields)—for use in tracking time. You can use them for that purpose. However, Azure Boards provides limited native support for time tracking. Instead, you may want to consider using a [Marketplace extension](https://marketplace.visualstudio.com/search?term=time%20tracking&target=AzureDevOps&category=Azure%20Boards&sortBy=Relevance) to support your other time tracking requirements. +However, some organizations require time tracking to support other purposes, such as for billing or maintaining time allocation records. Time values for estimated work and completed work are of interest. The Agile and CMMI processes provide these fields—[`Original Estimate`, `Completed Work`, `Remaining Work`](queries/query-numeric.md#fields)—for use in tracking time. You can use them for that purpose. However, Azure Boards provides limited native support for time tracking. Instead, consider using a [Marketplace extension](https://marketplace.visualstudio.com/search?term=time%20tracking&target=AzureDevOps&category=Azure%20Boards&sortBy=Relevance) to support your other time tracking requirements. > [!NOTE] -> The Original Estimate, Completed Work, Remaining Work fields were designed to support integration with Microsoft Project. Integration support with Microsoft Project is deprecated for Azure DevOps Server 2019 and later versions, including the cloud service. +> The `Original Estimate`, `Completed Work`, `Remaining Work` fields were designed to support integration with Microsoft Project. Integration support with Microsoft Project is deprecated for Azure DevOps Server 2019 and later versions, including the cloud service. -## Process changes that impact all teams +## Process changes that affect all teams -Any change made to a process applied to a project impacts all teams in that project. Many changes don't cause much disruption to the teams they support. However a few do, which are described in this section. +Any change made to a process in a project impacts all teams in that project. Many changes don't cause much disruption to the teams they support, but the following changes do. ### Custom fields -Adding custom fields to a work item type doesn't impact any specific tool. The fields simply appear in the corresponding work items. If you add a custom numeric field, however, you can use it to support rollup on backlogs and the following reporting tools: +When you add custom fields to a WIT, it doesn’t directly affect any specific tool. Instead, these fields become visible within the corresponding work items. For instance, if you introduce a custom numeric field, you can utilize it for rollup calculations on backlogs. Also, you can use this custom field with the following reporting tools. So, while the effect isn’t tool-specific, it does enhance your ability to tailor work items to your project’s needs. - [In-context Velocity report and dashboard widget](../report/dashboards/team-velocity.md) - [In-context Sprint Burndown report and dashboard widget](../report/dashboards/configure-sprint-burndown.md) - [Dashboard Burndown and Burnup widget](../report/dashboards/configure-burndown-burnup-widgets.md) @@ -432,9 +422,9 @@ Adding custom fields to a work item type doesn't impact any specific tool. The f > [!NOTE] > All default and custom fields are shared across all projects in a collection or organization. There is a limit of 1024 fields that you can define for a process. -### Custom work item types +### Custom WITs -The following table shows the effects of adding a custom work item type to a specific category. +The following table shows the effects when you add a custom WIT to a specific category. :::row::: :::column span="1"::: @@ -453,40 +443,35 @@ The following table shows the effects of adding a custom work item type to a spe - Work items based on the new WIT appear on the sprint backlogs and Taskboards :::column-end::: :::column span="1"::: - - Work items based on the new WIT appear on the product backlog and Kanban board - - Each team must configure the Kanban board to support the new WIT + - Work items based on the new WIT appear on the product backlog and \board + - Each team must configure the \board to support the new WIT :::column-end::: :::column span="1"::: - - Work items based on the new WIT appear on the corresponding portfolio backlogs and Kanban boards - - Each team must configure the Kanban boards to support the new WIT - - The new WITs may not appear on one or more of the portfolio planning tools + - Work items based on the new WIT appear on the corresponding portfolio backlogs and boards + - Each team must configure the \boards to support the new WIT + - The new WITs might not appear on one or more of the portfolio planning tools :::column-end::: :::row-end::: ### Custom workflow -Each process supports a default workflow. This workflow defines the default columns that appear on the Kanban boards and sprint Taskboards. +Each process supports a default workflow. This workflow defines the default columns that appear on the boards and sprint Taskboards. [!INCLUDE [temp](includes/four-process-workflow.md)] -Sometimes, teams want to track the status of their work that goes beyond these default states. Support is provided in one of two ways: -- Add custom workflow states to the work item type: This option impacts all teams and requires that they update their Kanban board configuration -- [Add columns to a Kanban board](backlogs/set-column-options.md): This option only impacts the team that adds the columns - -Both workflow states and Kanban columns appear in the Cumulative Flow diagram for a team. Individuals can choose which columns appear in the chart. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Cumulative flow diagram.](media/config-custom/cumulative-flow-diagram.png) +Sometimes, teams want to track the status of their work that goes beyond these default states. Support is provided in one of the following ways: +- Add custom workflow states to the WIT: This option impacts all teams and requires that they update their board configuration. +- [Add columns to a board](backlogs/set-column-options.md): This option only impacts the team that adds the columns. -For more information, see [Cumulative flow diagram](../report/dashboards/cumulative-flow.md). +Both workflow states and columns appear in the Cumulative Flow diagram for a team. Individuals can choose which columns appear in the chart. For more information, see [Cumulative flow diagram](../report/dashboards/cumulative-flow.md). ## Who can make changes? -Because process-level, project-level, and team-level settings can have a wide impact, changes are restricted to the following users with the required permissions. +Since process-level, project-level, and team-level settings can have a wide effect, changes are restricted to users with the following required permissions. ### Process-level changes -To create, edit, or manage Inherited processes and apply them to projects, you must be a member of the [**Project Collection Administrators** group](../organizations/security/change-organization-collection-level-permissions.md). Or, you must have the corresponding permissions **Create process**, **Delete process**, **Edit process**, or **Delete a field from organization** set to **Allow**. See [Set permissions and access for work tracking, Customize an inherited process](../organizations/security/set-permissions-access-work-tracking.md#customize-an-inherited-process). +To create, edit, or manage Inherited processes and apply them to projects, be a member of the [**Project Collection Administrators** group](../organizations/security/change-organization-collection-level-permissions.md). Or, have the corresponding permissions **Create process**, **Delete process**, **Edit process**, or **Delete a field from organization** set to **Allow**. See [Set permissions and access for work tracking, Customize an inherited process](../organizations/security/set-permissions-access-work-tracking.md#customize-an-inherited-process). For more information, see the following articles: @@ -496,9 +481,9 @@ For more information, see the following articles: ### Project-level changes -To add Area Paths or Iteration Paths, you must be a member of the [**Project Administrators** group](../organizations/security/change-project-level-permissions.md). +To add Area Paths or Iteration Paths, be a member of the [**Project Administrators** group](../organizations/security/change-project-level-permissions.md). -Or, to add, edit, and manage Area Paths or Iteration Paths under a specific node, you must have been granted one or more of the following permissions set to **Allow**: +Or, to add, edit, and manage Area Paths or Iteration Paths under a specific node, have one or more of the following permissions set to **Allow**: - **Create child nodes** - **Delete this node** @@ -511,16 +496,16 @@ For more information, see the following articles: ### Team-level changes -All team tools can be configured by a [team administrator](../organizations/settings/add-team-administrator.md) or a member of the [**Project Administrators** group](../organizations/security/change-project-level-permissions.md). +To configure team tools, be a [team administrator](../organizations/settings/add-team-administrator.md) or a member of the [**Project Administrators** group](../organizations/security/change-project-level-permissions.md). -Team administrators are tasked with performing the following operations: +Team administrators do the following operations: - Add team members - Subscribe to area and iteration paths - Configure backlogs and other common team settings -- Configure Kanban boards +- Configure boards - Manage team notifications -For details on configuring backlogs and boards, see [Manage and configure team tools](../organizations/settings/manage-teams.md). +For more information on configuring backlogs and boards, see [Manage and configure team tools](../organizations/settings/manage-teams.md). ## Next steps > [!div class="nextstepaction"] @@ -528,7 +513,7 @@ For details on configuring backlogs and boards, see [Manage and configure team t ## Related articles -- [Azure Boards Configuration and Customization FAQs](../organizations/settings/work/faqs.yml) +- [Configuration and Customization FAQs](../organizations/settings/work/faqs.yml) - [Set up your Backlogs and Boards](backlogs/set-up-your-backlog.md) - [Inherited process model](../organizations/settings/work/inheritance-process-model.md) - [Manage and configure team tools](../organizations/settings/manage-teams.md) diff --git a/docs/boards/extensions/delivery-plans.md b/docs/boards/extensions/delivery-plans.md deleted file mode 100644 index e0254c6525f..00000000000 --- a/docs/boards/extensions/delivery-plans.md +++ /dev/null @@ -1,268 +0,0 @@ ---- -title: Marketplace extension for Delivery Plans 1.0 in Azure Boards and Azure DevOps -titleSuffix: Azure Boards -description: Learn how to add and use plans to review scheduled multi-team deliverables in Azure Boards and Azure DevOps. -ms.service: azure-devops-boards -ms.assetid: 3B41D55E-B7B1-41B1-B68F-7A83BA2890A5 -ms.author: chcomley -author: chcomley -ms.topic: tutorial -monikerRange: '<= azure-devops' -ms.date: 08/09/2022 ---- - -# Delivery Plans 1.0 Marketplace extension - -[!INCLUDE [version-lt-azure-devops](../../includes/version-lt-azure-devops.md)] - - -Use the visualization options that Delivery Plans provide to review the schedule of stories or features your teams plan to deliver. Delivery Plans show the scheduled work items by sprint (iteration path) of selected teams against a calendar view. - -> [!NOTE] -> Delivery Plans 2.0 is available for Azure DevOps Services and Azure DevOps Server 2022 and later versions. The new version of Delivery Plans supports several new features and is a supported feature of Azure Boards. It isn't an extension. The plans you've already defined with the extension open using [Delivery Plans 2.0](../plans/review-team-plans.md). For a summary of the differences between the two versions, see [Delivery Plans FAQs](../plans/faqs.yml). - - -Use Delivery Plans to ensure your teams are aligned with your organizational goals. You can view multiple backlogs and multiple teams across your whole account. You can interact with the plan with simple drag-and-drop operations to update or modify the schedule, opening cards, expanding and collapsing teams, and more. - -You can change the assigned sprint of a work item by dragging it to a new sprint as shown in the following image. - -> [!div class="mx-imgBorder"] -> ![Screenshot of moving a card to a different iteration](media/plans/plans-move-1.png) - - -In this article you'll learn: - -> [!div class="checklist"] -> - How to review a plan with your teams -> - How to add and edit a plan -> - How to add field criteria, customize cards, and add markers -> - How to open a plan from the list of defined plans -> - How to work with the interactive elements of plans and change the plan view -> - What permissions are required to create and view plans - - -## Prerequisites - -- To add and configure a Delivery Plan, you must have the following criteria in place: - - Installed the Delivery Plans extension from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms.vss-plans). - - Be a member of a project and granted [Basic access or greater access level](../../organizations/security/access-levels.md). Users granted **Stakeholder** access can't add nor view plans. - - [Configured teams](../../organizations/settings/add-teams.md) - - [Define area paths and assign to a team](../../organizations/settings/set-area-paths.md) - - [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md) - - Teams have defined [user stories](../backlogs/create-your-backlog.md), features, or other product or portfolio backlogs and assigned those items to iterations. - - Team Backlog settings have enabled the backlogs to show in the delivery plans. For more information, see [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md). -- To view a Delivery Plan, you must be a member of the Project Collection Valid Users group. Members of the project's Readers group are valid users. Users with Stakeholder access for a private project can't view or add plans. -- To manage permissions for a Delivery Plan, to edit, or to delete a plan, you must: - - Be the creator of the plan - - Be a member of the Project Administrators or Project Collection Administrators group - - Be granted explicit permission through the plan's Security dialog. - - For more information, see [Manage Delivery Plan permissions](../../organizations/security/set-permissions-access-work-tracking.md#edit-or-manage-permissions-for-delivery-plans). - -## Review a plan with your teams - -It takes several teams to develop large software projects. Large projects require multiple autonomous teams. Review [Agile culture](../plans/agile-culture.md) for a discussion of autonomous teams and organizational alignment. Autonomous teams manage their own backlog and priority, which contributes to a unified direction for that project. - -Regular reviews of the project schedule with these teams help ensure that the teams are working toward common goals. Delivery Plans provide the needed multi-team view of your project schedule. - -Some questions you might address during the review: -- *How confident are the teams in meeting the deliverables scheduled for each sprint?* -- *Are dependencies across teams adequately addressed via the planned deliverables?* -- *Are there gaps in the schedule, where no deliverables are scheduled? What's the cause? Can this risk be mitigated?* - -For example, we use Delivery Plans internally to share the schedule of Features. By seeing the work many teams have planned for the next three sprints, we can easily discuss whether these priorities are the right priorities and if dependencies exist. - -In this way, a Delivery Plan is a driver of alignment while allowing each team to keep a strong sense of autonomy. Individual teams can work to different sprint cadences, if needed, and manage different work item types—stories, features, or epics. Their work is all visible with the same plan view. Teams can even be part of different projects if they use different processes. You can also customize the card fields so that you only see the data fields of interest and applicable per work item type. - - - -## Learn best practices - -- Use a consistent sprint schedule across your project teams and organization. Use the same sprints for backlogs, features, and epics. Don't create specific sprints for epics or other portfolio backlogs. -- Minimize the number of fields you choose to display on your cards. -- Eliminate cross-team ownership of area paths. Cross-team area path ownership isn't recommended and can lead to undesirable edge cases. - -Note the following criteria: -- Plan views are limited to 12 to 13 months. -- Plan views are limited to a maximum of 10 teams/backlogs -- Zooming out can cause fields and tags to disappear from the cards. The further you zoom out, the harder it's to fit items on a card. By design, we hide select items depending on the zoom level. - -## Add a plan - -::: moniker range=">= azure-devops-2019 <= azure-devops-2020" - -1. Open **Boards>Plans**. - - > [!div class="mx-imgBorder"] - > ![Screenshot to Open Boards>Plans](media/plans/open-plans-vert.png) - -1. To add a plan, choose **New Plan**. - - > [!div class="mx-imgBorder"] - > ![Choose New Plan.](media/plans/add-plan.png) - - All users, except users [assigned Stakeholder access](../../organizations/security/change-access-levels.md), have permissions to create a plan and manage the plans they create. To manage permissions for a plan, see [Set permissions and access for work tracking, Manage or edit Delivery Plans](../../organizations/security/set-permissions-access-work-tracking.md#plan-permissions). - -2. Fill in the form to name, describe, and specify the team backlogs that you want to appear within your plan. - - > [!div class="mx-imgBorder"] - > ![Add a plan](media/plans/new-delivery-plan-dialog.png) - - -::: moniker-end - - -::: moniker range="tfs-2018" - -1. Open **Boards>Plans**. - - > [!div class="mx-imgBorder"] - > ![Open work>Plans, previous nav](media/plans/open-plans-horz.png) - -1. To add a plan, choose **New Plan**. - - ![Choose new plan.](media/plans/review-team-plans-no-plans-defined.png) - - All users, except users [assigned Stakeholder access](../../organizations/security/change-access-levels.md), have permissions to create a plan and manage the plans they create. To manage permissions for a plan, see [Set permissions and access for work tracking, Manage or edit Delivery Plans](../../organizations/security/set-permissions-access-work-tracking.md#plan-permissions). - -2. Fill in the form to name, describe, and specify the team backlogs that you want to appear within your plan. - > [!div class="mx-imgBorder"] - > ![Add a plan](media/plans/new-delivery-plan-dialog.png) - -::: moniker-end - -When defining a plan, note the following criteria: -- Use the name and description field to clearly identify your plan within the project -- You can choose one or more teams from any project defined in the organization or collection. Choose up to a maximum of 10 teams. -- You can choose one or more [active backlogs for a team](../../organizations/settings/select-backlog-navigation-levels.md) - > [!NOTE] - > If you aren't able to select a backlog level, check the Team Backlog settings to ensure the backlog level is enabled for the team. For more information, see [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md). -- You can reorder the team backlogs by dragging and dropping them into the sequence you want -- To filter for specific work items, specify the field criteria. For example, to exclude bugs from the view, add the following criteria: `Work Item Type <> Bug`. - - - - -## Edit a plan - -Once you've defined a plan, you can further customize it. - -1. To open the Settings dialog, choose **Configure plan settings**:::image type="icon" source="media/plans/gear-icon.png" border="false":::. - -2. Then, choose the page you want to edit. You can customize the plan in the following ways: - - Edit the teams you've selected and their backlog level - - Set field criteria to further limit the work items that appear on the plan - - Add markers to show important upcoming events on your timeline - - Customize the fields that display on the cards, similar to how you [customize them for your Kanban or taskboard](../../boards/boards/customize-cards.md). - - Here, we add the Tags field criteria. Only work items that contain the *RC Review* tag appear in the Delivery Plan. - - Settings dialog, Fields page - -3. To set a marker, open the Markers page, specify a date, and select a color. - - Open the Markers page, specify a date and select a color. - - Markers appear on the plan as shown: - - Plans, Markers appear on calendar slide - - -## Open a plan - -Once you've defined a few plans, you'll see them listed from the **Plans** page under **All**, or the ones you've favorited (**Add to favorites** :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false":::) under **Favorites**. You can see their title, description, and their most recent creator/editor. - -Use the favorite's star to favorite a plan so that you can quickly return to that plan. You can also search for other plans in the project. - -To open a plan, choose the plan name. - -## Interact with a plan - -Each team's backlog specified in a Delivery Plan appears as a row within the plan view. When collapsed, a roll-up of the backlog items shows. When expanded, a card for each backlog item appears, organized by their assigned iteration. - -:::image type="content" source="media/plans/plans-view-2.png" alt-text="Interactive plan elements."::: - -You can interact with the plan in the following ways: - -- Filter the plan by choosing Choose **Filter** :::image type="icon" source="../../media/icons/filter-icon.png" border="false":::. For more information, see [Interactively filter your backlogs, boards, and plans](../backlogs/filter-backlogs-boards-plans.md). -- Scale the size of the cards (enter **+** or **-** to also scale) -- Scroll the view horizontally via the calendar to view previous months or future months (Enter **Shift-left** or **Shift-right** to scroll) -- You can also scroll the plan via click and dragging your mouse. -- Scroll the view vertically to view teams that appear lower within the plan view. You can also scroll the plan by clicking the plan and dragging your mouse vertically. -- Select a card title to open the backlog item and view details. Close the work item to return to the plan. -- To view details for a team, expand the team row by choosing **Expand team row**. -- To expand and collapse all team rows, choose **Expand all team rows** or **Collapse all team rows** next to **Teams**. (Enter **u** to collapse, **o** to expand all rows). -- Enter **t** to quickly toggle fields shown on cards to just the Title or all other card field settings -- To edit the plan and [change the fields displayed on the cards](#card-settings), choose **Configure plan settings** :::image type="icon" source="media/plans/gear-icon.png" border="false":::. - - -In the following example, Team 1 features expanded, two items are scheduled for delivery in Sprint 50. - -Team rows in plans - -You can also quickly see that: -* Team 1 is currently working on Sprint 50 deliverables -* Sprint 50 began on December 14 and is scheduled to end December 25. -* The team expects to deliver the two features shown by the cards. - -## Collapse teams for summary information - -A benefit of Delivery Plans is to view multiple teams across your projects that you care about. Two main ways to view more teams within the plan view is to collapse all teams to focus on summary data. You can also minimize the number of fields displayed on cards. - -To gain a summary view of work that is schedule, collapse all teams. You can then more easily look for gaps in the forward forecast. - - -For example, here you can see the count of Features for Team 1 for the next three sprints. You can collapse/expand team rows by choosing **Expand team row** or **Collapse team row** next to the team name. - -> [!div class="mx-imgBorder"] -> ![Collapse click targets](media/plans/plans-view-4.png) - - -## View titles only in the collapsed card view - -The collapsed card view allows you to quickly switch back and forth between cards showing titles only and cards showing all fields configured for the plan. To toggle between titles only and show all fields, enter "**t**" from your keyboard. - - -## Update the iteration for a backlog item - -As changes occur to the schedule, you can update the iteration for a backlog item. Update the iteration by moving a card to a different iteration. This action helps to drive alignment across your organization. - -> [!div class="mx-imgBorder"] -> ![Move a card to a different iteration](media/plans/plans-move-1.png) - - -## Minimize the fields displayed on cards - -To quickly change the cards to only show their Title, enter the keyboard shortcut '**t**'. This action hided all other fields, as shown in the following image, the Assigned to field no longer appears. To persist this view, edit the [plan's settings for card fields](#card-settings). - -> [!div class="mx-imgBorder"] -> ![Cards showing the Title only](media/plans/plans-view-5.png) - - -## Learn keyboard shortcuts - -You can use the following keyboard shortcuts when [interacting with a delivery plan](../../boards/plans/review-team-plans.md). To view the valid shortcuts, enter **?** when viewing a plan from the **Boards>Plans** or **Work>Plans** page. - -[!INCLUDE [temp](../../includes/keyboard-shortcuts/delivery-plan-shortcuts.md)] - - -## Related articles - -For more resources to help work with multiple teams, see these articles: - -- [Interactively filter your backlogs, boards, and plans](../backlogs/filter-backlogs-boards-plans.md) -- [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md) -- [Add teams](../../organizations/settings/add-teams.md) -- [Portfolio management](../plans/portfolio-management.md) -- [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) -- [Keyboard shortcuts](../../project/navigation/keyboard-shortcuts.md) - - - - -### Programmatically manage Delivery Plans - -You can manage plans using the [REST API, Plans](/rest/api/azure/devops/work/plans). - - - diff --git a/docs/boards/extensions/dependency-tracker.md b/docs/boards/extensions/dependency-tracker.md index 0c9a9c66cec..4e187301613 100644 --- a/docs/boards/extensions/dependency-tracker.md +++ b/docs/boards/extensions/dependency-tracker.md @@ -8,29 +8,27 @@ ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 06/02/2022 +ms.date: 11/18/2024 --- -# Plan and track dependencies using the Dependency Tracker +# Use the Dependency Tracker extension [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] > [!NOTE] > We recommend that you use [Delivery Plans](../plans/track-dependencies.md) to track dependencies instead of Dependency Tracker. The Dependency Tracker extension is not a supported feature of Azure Boards and isn't supported by any product team. For questions, suggestions, or issues you have when using the extension, visit the [Marketplace for Azure DevOps, Dependency Tracker extension](https://marketplace.visualstudio.com/items?itemName=ms-eswm.dependencytracker&ssr=false#overview) page. The Dependency Tracker extension is only available on Azure DevOps Services. - -The Dependency Tracker extension enables management of dependencies across teams, projects, and organizations. It provides filterable views to show all dependencies a team is consuming and producing. These views allow you to track the state and schedule of dependencies to support you in assessing the risk of dependencies to product deliverables. +The Dependency Tracker extension helps you manage dependencies across teams, projects, and organizations. It provides filterable views to show all dependencies a team is consuming and producing. These views allow you to track the state and schedule of dependencies to support you in assessing the risk of dependencies to product deliverables. +Use the Dependency Tracker to plan dependencies at the beginning of an iteration or release, and to track the status during development. For any given dependency, the following parties are involved: +- **Consumer**: Feature team that has a need and starts a request for work. +- **Producer**: Feature team that makes a commitment to deliver work. -You use the Dependency Tracker to plan dependencies at the beginning of an iteration or release, and to track the status during development. For any given dependency, there are two parties involved: -- **Consumer**: Feature team who has a need and starts a request for work -- **Producer**: Feature team who makes a commitment to deliver work - -Each work request and work deliverable is defined as a work item. The work items are linked by the Successor-Predecessor link type or other directional link type. For details about link types, see [Link type reference](../queries/link-type-reference.md) +Each work request and work deliverable is defined as a work item. The work items get linked by the Successor-Predecessor link type or other directional link type. For more information, see [Link type reference](../queries/link-type-reference.md) Producing for/Consuming from link. > [!TIP] -> While any work item type can participate in dependency tracking, you may want to decide if you want to limit dependencies to specific types, such as Features, Epics, User Stories, or Bugs. You can create that restriction through [Configuration of Dependency Tracker](#configuration). +> While any work item type can participate in dependency tracking, you might want to limit dependencies to specific types, such as Features, Epics, User Stories, or Bugs. You can create the restriction by [configuring Dependency Tracker](#configuration). From the Dependency Tracker, you can choose different views and filters, and drill down to obtain specific details. These views and options are described in the following sections: - [Filter options](#filter) @@ -42,97 +40,85 @@ From the Dependency Tracker, you can choose different views and filters, and dri ## Recommended use and key terms -You can use Dependency Tracker to visualize and track the following work items: -- Dependencies on deliverables for work that your team is delivering -- Dependencies you have on other teams for work that your team is delivering -- Dependencies that other teams have on work your team is delivering +Use Dependency Tracker to visualize and track the following work items: +- Dependencies on deliverables for work that your team is delivering. +- Dependencies you have on other teams for work that your team is delivering. +- Dependencies that other teams have on work your team is delivering. All teams across organizations can participate in tracking dependencies. > [!NOTE] -> Dependency Tracker doesn't replace the in person interactions required to agree to doing the work. It provides easier planning and tracking capabilities. Dependencies should be agreed upon by all parties before they are entered in to the Dependency Tracker. +> Dependency Tracker doesn't replace the in-person interactions that are required to agree to doing the work. It provides easier planning and tracking capabilities. Dependencies should be agreed upon by all parties before they enter into the Dependency Tracker. ### Key terms -- **Dependency**: work that Team A requires from Team B to do the work Team A is trying to do -- **Consumer**: the team that wants work done -- **Producer**: the team that is being asked to do the work -- **Sequencing**: when a producing team's work is needed before the consuming team can start their work - -### Recommended practices - -- The consumer is the team that asks for the work – they start all discussions on the work they require -- The consumer owns the engagement and tracking of that work – since it's the work their scenario requires, the burden is on the consumer to file, monitor, and track the status of the work -- The consumer owns entering the work into Azure Boards and submitting that work request to the producer -- Once the work has been submitted to the producer, the producer owns the work item, +- **Dependency**: Work that Team A requires from Team B to do the work Team A is trying to do. +- **Consumer**: The team that asks to have work done. + - The consumer owns the engagement and tracking of that work – since it's the work their scenario requires, the burden is on the consumer to file, monitor, and track the status of the work + - The consumer owns entering the work into Azure Boards and submitting that work request to the producer + - The consumer is in charge of managing the work they requested so that they're aware of any material changes and adjustments +- **Producer**: The team that is doing the work. + - Once the work gets submitted to the producer, the producer owns the work item, - The producer is responsible for maintaining the work item in Azure Boards - The producer owns the state of the work item and iteration - - The consumer shouldn't touch these values, once the work item has been handed off -- The consumer is in charge of managing the work they requested so that they're aware of any material changes and adjustments + - The consumer shouldn't touch these values once the work item gets handed off +- **Sequencing**: A producing team's work is needed before the consuming team can start their work. ## Prerequisites -- Install the [Dependency Tracker extension](https://marketplace.visualstudio.com/items?itemName=ms-eswm.dependencytracker&ssr=false#overview) for the organization(s) for which you want to track dependencies. -- To view dependencies, you must be a member of the Project Valid Users group for the project. -- To create a dependency, you must be a member of the Contributors group for both projects that participate in the dependency linking. -- To support cross-organization participation, all organizations must authenticate users through the same [Azure Active Directory](../../organizations/accounts/connect-organization-to-azure-ad.md). -- Azure Boards must be enabled as a service. If it's disabled, then you'll need to have it reenabled. For more information, see [Turn a service on or off](../../organizations/settings/set-services.md). -- To modify the configuration, you must be a member of the Project Collection Administrator Group. +| Category | Requirements | +|--------------|-------------| +| **Tools** | [Dependency Tracker extension](https://marketplace.visualstudio.com/items?itemName=ms-eswm.dependencytracker&ssr=false#overview) installed for the organization for which you want to track dependencies. | +| **Permissions** | - To view dependencies: Member of the **Project Valid Users** group for the project.
- To create a dependency: Member of the **Contributors** group for both projects that participate in the dependency linking.
- To modify configuration: Member of the **Project Collection Administrators** group. | +| **Authentication** | All organizations authenticate users through the same [Microsoft Entra ID](../../organizations/accounts/connect-organization-to-azure-ad.md). | +| **Services** | [Azure Boards as a service](../../organizations/settings/set-services.md) enabled. | +| **Configuration and customization tasks** | - Area paths and teams set up to participate in dependency tracking.
- Iteration paths/sprints configured for the project and assigned to work items participating in dependency tracking. This requirement is essential for the Timeline view to yield meaningful data.
- Customize your process as needed to support any other work items or fields.
- [Dependency Tracker](#configuration) configured to support your business needs and address any customizations. | > [!IMPORTANT] -> The default configuration for Dependency Tracker supports the Agile process. If your project(s) are based on a different process or you have customized your process, you may need to modify the configuration. See [Configure the Dependency Tracker](#configuration) later in this article. - -Also, the following configuration or customization tasks should be performed: -- Set up the area paths and teams to participate in dependency tracking. -- Configure iteration paths/sprints for the project and assign them to work items participating in dependency tracking. This task is essential for the Timeline view to yield meaningful data. -- Customize your process as needed to support any other work items or fields. -- [Configure the Dependency Tracker](#configuration) to support your business needs and address any customizations you've made. +> The default configuration for Dependency Tracker supports the Agile process. If your project(s) are based on a different process or you have customized your process, you may need to modify the configuration. See [Configure the Dependency Tracker](#configuration) later in this article. - -## Open the Dependency Tracker +## Open the Dependency Tracker extension 1. Open the web portal for the project where your team is defined. -2. Choose **Dependency Tracker** from under the Boards group. +2. Select **Boards** > **Dependency Tracker**. > [!div class="mx-imgBorder"] > ![Screenshot showing Dependency Tracker hub in Azure Boards.](media/tracker/select-dependency-tracker.png) -1. To focus on your area of ownership, choose the **Area** that corresponds to the team you want to view dependencies for. +3. Choose the **Area** that corresponds to the team you want to view dependencies for from the dropdown menu. > [!div class="mx-imgBorder"] > ![Screenshot showing selecting Area.](media/tracker/choose-area-path.png) You can only filter on those Area paths defined for the project. - + ## Filter options -You can filter each supported view by entering a keyword or using one or more of the fields. Provided fields include State, Work item type, and Iteration Path. Based on the keyword that you enter, the filter function lists work items based on any displayed column field. +Filter each supported view by entering a keyword or using one or more of the fields. Provided fields include State, Work item type, and Iteration Path. Based on the keyword that you enter, the filter function lists work items based on any displayed column field. To show the filter toolbar, choose the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: filter icon. > [!div class="mx-imgBorder"] > ![Screenshot showing Dependency Tracker Filter options.](media/tracker/filter.png) -You can toggle filters on and off by choosing the filter icon. To see more filters use the arrows at the end of the list of filters. +Toggle filters on and off by choosing the filter icon. To see more filters use the arrows at the end of the list of filters. -Choose one or more values from the multi-select drop-down menu for each field. The values for these fields are populated as follows: +Choose one or more values from the drop-down menu for each field. These fields populate with the following values: -- **State**: Check one or more check boxes for the work item states you want to view. The drop-down list should include all workflow States defined for all work item types shown in the selected view. - **Work item type**: Check one or more check boxes for the Work item types you want to view. Work item types configured to participate in dependency tracking. The default work item types are: Epic, Feature, User Story, and Bug. To modify the configuration, see [Configuration of Dependency Tracker](#configuration). -- **Iteration**: Check one or more check boxes for the Iteration Paths you want to view. The drop-down list should include all Iteration Paths [configured for the project](../../organizations/settings/set-iteration-paths-sprints.md) and for which there are work items listed in the current view. +- **State**: Check one or more check boxes for the work item states you want to view. The drop-down list should include all workflow States defined for all work item types shown in the selected view. +- **Iteration**: Check one or more check boxes for the Iteration Paths you want to view. The drop-down list should include all Iteration Paths [configured for the project](../../organizations/settings/set-iteration-paths-sprints.md) and for which there are work items listed in the current view. - **Priority**: Check one or more check boxes for the Priorities you want to view. The priority values assigned to work items - **Partner**: The partner organization for which the work item is defined. -> [!NOTE] -> Filter options are dependent on the [configuration](#configuration) defined for the Dependency Tracker. Also, only those options that correspond to work items shown in the selected view that meet the filter criteria. For example, if you don't have any work items assigned to Sprint 4, then the Sprint 4 option won't appear in the filter options for the Iteration Path. - -Ability to drop dependencies within the selected area (used for excluding dependencies inside my team) +Your filtering options are dependent on the [configuration](#configuration) defined for the Dependency Tracker and that correspond to work items shown in the selected view that meet the filter criteria. For example, if you don't have any work items assigned to Sprint 4, then the Sprint 4 option doesn't appear in the filter options for the Iteration Path. +You can drop dependencies within the selected area, which excludes dependencies inside your team. - + ## View drill-down options @@ -141,14 +127,13 @@ Several views provide interactive visualizations through drill-downs. These feat > [!div class="mx-imgBorder"] > ![Screenshot showing Consuming dependencies, drill-down into completed work in an area.](media/tracker/drill-down-completed-consuming.png) - - + ## Create a dependency A dependency represents work where one team is dependent on another team. Both teams should track their own work in their own area path. By linking the work that is dependent on the other teams work, the dependencies can be visualized and tracked. -1. Choose **New Dependency**. +1. Select **New Dependency**. > [!div class="mx-imgBorder"] > ![Screenshot showing choose New Dependency.](media/tracker/choose-new-dependency.png) @@ -158,7 +143,7 @@ A dependency represents work where one team is dependent on another team. Both t > [!div class="mx-imgBorder"] > ![Screenshot of Create dependency dialog, Choose partner account.](media/tracker/choose-partner-organization.png) -1. You can search for work items by ID or by entering a keyword contained within the work item title. Here, we link a user story and a bug. +2. Search for work items by ID or enter a keyword contained within the work item title. In the following example, we link a user story and a bug. > [!div class="mx-imgBorder"] > ![Screenshot of Create dependency dialog, choose two existing work items to link.](media/tracker/create-dependency.png) @@ -174,16 +159,16 @@ A dependency represents work where one team is dependent on another team. Both t If no work items exist for one half of the dependency, you can create a new work item as needed. -1. Choose **Save**. The **Save** button becomes available only after you've chosen two work items to link. +3. Select **Save**. The **Save** button is available only after two work items get chosen to link. -1. From the success confirmation dialog, choose **View dependency**. +4. From the success confirmation dialog, select **View dependency**. > [!div class="mx-imgBorder"] > ![Screenshot of Success confirmation dialog.](media/tracker/success-confirmation.png) -1. The work items that you linked are highlighted. + The work items that you linked are highlighted. - As shown in this example, the Fabrikam Fiber/Service Delivery/Voice team is dependent on the MyFirstProject team to deliver their `User Story 706: Cancel order form` to complete `Bug 390: Cancel order form`. + In the following example, the Fabrikam Fiber/Service Delivery/Voice team is dependent on the MyFirstProject team to deliver their `User Story 706: Cancel order form` to complete `Bug 390: Cancel order form`. > [!div class="mx-imgBorder"] > ![Screenshot of Create dependency dialog, Linked dependent work items.](media/tracker/linked-dependent-work-items.png) @@ -196,9 +181,7 @@ You can also link work items using the **Links** tab to create Successor/Predece > ![Screenshot of Add Link dialog, Create links manually.](media/tracker/create-links-manually.png) > [!NOTE] -> The Successor/Predecessor (consumes/produces) link types are the default link types used by the Dependency Tracker. If you're projects are customized using a Hosted XML process model, it's possible to specify different link types in the Dependency Tracker configuration. See [Configure the Dependency Tracker](#configuration) later in this article. - -For more information, see [Link user stories, issues, bugs, and other work items](../backlogs/add-link.md). +> The Successor/Predecessor (consumes/produces) link types are the default link types used by the Dependency Tracker. If you customized your projects using a Hosted XML process model, it's possible to specify different link types in the Dependency Tracker configuration. For more information, see [Configure the Dependency Tracker](#configuration) later in this article, and [Link user stories, issues, bugs, and other work items](../backlogs/add-link.md). ## Remove dependency links @@ -222,15 +205,11 @@ You can also create a custom query by selecting the Work items and direct links Choose **Copy to HTML** to copy the selected work items to the clipboard as a formatted table. - + ## Consuming Dependencies view -The **Consuming Dependencies** view shows work that a team is dependent upon other teams/area paths. It's useful for answering the following questions: - -- *Which dependencies am I consuming as the owner of the selected areas and sub areas?* -- *How many dependencies per producer team (by area level 3)?* -- *What are the workflow states of my consumer dependencies?* +The **Consuming Dependencies** view shows work that a team is dependent upon by other teams or area paths. > [!div class="mx-imgBorder"] > ![Screenshot of Dependency Tracker, Consuming dependencies view.](media/tracker/consuming-dependencies-view.png) @@ -244,16 +223,11 @@ Within the table, you can complete the following actions. - Add or remove column fields by opening Column Options - Switch the sequence of work items by choosing the Display: **Consumer on top** or **Producer on top** - - + ## Producing Dependencies view -The **Producing Dependencies** view shows work that other teams/area paths are dependent on per the selected area. It's useful for answering the following questions: - -- *Which dependencies is my team responsible for delivering as the owner of the selected area(s)?* -- *How many dependencies exist per consumer team (by area level 3)?* -- *What are the workflow states of my producer dependencies?* +The **Producing Dependencies** view shows work that other teams or area paths are dependent on per the selected area. > [!div class="mx-imgBorder"] > ![Screenshot of Dependency Tracker, Producing dependencies view.](media/tracker/producing-dependencies-view.png) @@ -263,40 +237,37 @@ Each column on the bar chart represents another area path that is consuming depe Within the table, you can complete the same actions as in the Consuming Dependencies view. - + ## Timeline tab -The **Timeline** tab provides a calendar view of dependencies. The Timeline view is in Beta. The Timeline view helps answering the following questions: - -- *What is the sequence of dependencies within the time window.* -- *What are all the deliverable dependencies against within the three-month time window for a given team?* +The **Timeline** tab provides a calendar view of dependencies. The Timeline view is in Beta. > [!IMPORTANT] -> For the Timeline to show meaningful data, you must have assigned the dependent work items to Iteration Paths, and the Iteration Paths must have start and end dates assigned. +> For the Timeline to show meaningful data, have assigned the dependent work items to Iteration Paths, and the Iteration Paths must have start and end dates assigned. -There are two versions of the Timeline view: **Correct Flow** and **Incorrect Flow**. Each version shows the color-coded workflow state. Color codes can be customized within the [Dependency Tracker configuration](#configuration). +There are two versions of the Timeline view: **Correct Flow** and **Incorrect Flow**. Each version shows the color-coded workflow state. You can customize color codes within the [Dependency Tracker configuration](#configuration). #### Correct Flow view -The Correct Flow view shows those dependencies that are in the correct sequence. Successor work items are scheduled to be completed after their predecessor work item. +The Correct Flow view shows those dependencies that are in the correct sequence. Successor work items get completed after their predecessor work item. > [!div class="mx-imgBorder"] > ![Screenshot of Timeline view, correct flow.](media/tracker/timeline-oc-word-2019-correct-flow.png) #### Incorrect Flow view -The Incorrect Flow view shows those dependencies that are out of order. At least one predecessor work item is scheduled to be completed after its successor work item. +The Incorrect Flow view shows those dependencies that are out of order. At least one predecessor work item gets completed after its successor work item. > [!div class="mx-imgBorder"] > ![Screenshot of Timeline view, incorrect flow.](media/tracker/timeline-oc-word-2019-incorrect-flow.png) - + ## Risk Graph -The Risk Graph provides a visualization of how dependencies flow from Consumer team to Producer team, or from Producer to Consumers. The graph allows a team to, at a glance, understand the number of dependencies and level of risks associated. Also, the risk graph view demonstrates the value of linking dependencies and laddering them up to Stories. +The Risk Graph provides a visualization of how dependencies flow from Consumer team to Producer team, or from Producer to Consumer. The graph lets a team understand the number of dependencies and level of risks associated at a glance. Also, the risk graph view demonstrates the value of linking dependencies and laddering them up to Stories. > [!div class="mx-imgBorder"] > ![Screenshot of Dependency Tracker Risk Graph.](media/tracker/risk-graph-1.png) @@ -322,11 +293,11 @@ You can drill down into specifics by choosing one of the dependencies. > ![Screenshot of Dependency Tracker Risk Graph, Producing For, Filtered on a dependency.](media/tracker/risk-graph-ff-producing-for-filtered.png) - + ## Configure the Dependency Tracker -You must be a member of the Project Collection Administrator Group to modify the configuration. All changes to the configuration apply to all projects defined in the organization. +Be a member of the Project Collection Administrator Group to modify the configuration. All changes to the configuration apply to all projects defined in the organization. To change the configuration, choose the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: gear icon and modify the syntax listed. Choose **Save** when you're done. @@ -346,16 +317,15 @@ The main properties you can modify are summarized as follows: - Cross account (organization) dependencies - Cross account dependency toggle default state - Risk graph configuration: - - Work item state(s) associated with at risk (Red color) work items - - Work item state(s) associated with neutral (Gray color) work items - - Work item state(s) associates with on track (Green color) work items + - Work item states associated with at risk (Red color) work items + - Work item states associated with neutral (Gray color) work items + - Work item states associates with on track (Green color) work items For a full list and description, see the [Property descriptions](#table) provided later in this section. ### Enable or disable the New Dependency option -The `newDependencyButtonEnabled` property enables or disables the **New Dependency** link option. When enabled, the link appears on the Dependency Tracker page. When disabled, users can't create dependencies from the tracker, only review the dependencies that have been created through other means. The default value is set to `true` (enabled). - +The `newDependencyButtonEnabled` property enables or disables the **New Dependency** link option. When enabled, the link appears on the Dependency Tracker page. When disabled, users can't create dependencies from the tracker, only review the dependencies created through other means. The default value is set to `true` (enabled). ### Enable or disable cross-organization linking @@ -376,7 +346,7 @@ To disable, set the following syntax in the JSON configuration to `false`. Cross account linking requires the use of a special link type and should only be used in coordination with the **New Dependency** option. - + ### Property descriptions @@ -607,7 +577,7 @@ The following table describes each of the property items specified in the config :::row-end::: :::row::: :::column span="1"::: - riskAssessementValues + riskAssessmentValues > Specifies the [Risk](../queries/planning-ranking-priorities.md#risk) field values. The Risk field specifies a subjective rating of the relative uncertainty around the successful completion of a user story. It is defined for the Agile process, but can be added to work item types used in other processes. @@ -760,7 +730,7 @@ False :::column span="1"::: riskGraphConfig - > Maps the workflow States to one of the three Risk areas displayed on the Graph: `atRisk` is Red, `nuetral` is Gray, and `onTrack` is Green. + > Maps the workflow States to one of the three Risk areas displayed on the Graph: `atRisk` is Red, `neutral` is Gray, and `onTrack` is Green. :::column-end::: :::column span="1"::: @@ -920,12 +890,11 @@ False ## Related articles -- [Work item field index](..//work-items/guidance/work-item-field.md) +- [Manage work item fields](..//work-items/guidance/work-item-field.md) - [Review team delivery plans](../plans/review-team-plans.md) -- [Inheritance process model](../../organizations/settings/work/inheritance-process-model.md) -- [Hosted XML process model](../../organizations/settings/work/hosted-xml-process-model.md) -- [How workflow states and state categories are used in Backlogs and Boards](../work-items/workflow-and-state-categories.md) - +- [Use the inheritance process model](../../organizations/settings/work/inheritance-process-model.md) +- [Use the hosted XML process model](../../organizations/settings/work/hosted-xml-process-model.md) +- [Understand workflow states and state categories in Backlogs and Boards](../work-items/workflow-and-state-categories.md) ## Related Marketplace extensions @@ -948,4 +917,3 @@ The dependency bot works in the background to notify teams when dependencies are - Ask how her link type is Producing for/Consuming from link --> - diff --git a/docs/boards/extensions/index.md b/docs/boards/extensions/index.md deleted file mode 100644 index 866df2eaa0f..00000000000 --- a/docs/boards/extensions/index.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Extensions for Azure Boards -description: Learn about Azure Boards extensions that can help you customize or enhance your default experience. -titleSuffix: Azure Boards -ms.custom: extensions, engagement-fy23 -ms.service: azure-devops-boards -ms.topic: overview -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 01/31/2023 ---- - -# Overview of extensions for Azure Boards - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -The Azure DevOps Marketplace offers a wide variety of extensions to customize or enhance the default experience. You can learn more about those extensions developed by Microsoft from the following articles and links. For information on developing your own extension, see [Develop a web extension](../../extend/get-started/node.md). - -> [!NOTE] -> Extensions available to you depend on the Azure DevOps platform you use. Make sure you use the content version selector to view the extensions available for your version. -> -> Also, most extensions, such as [Retrospectives](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives), are not supported features of Azure Boards and therefore not supported by the product team. Over time, some extensions are deprecated. For questions, suggestions, or issues you have when using these extensions, visit their corresponding extension page. - - -::: moniker range="azure-devops" - -## Integrate with Azure Boards - -- [Azure Boards Microsoft Teams](../integrations/boards-teams.md) -- [Azure Boards Slack](../integrations/boards-slack.md) - - -::: moniker-end - -## Product planning - -::: moniker range=">= azure-devops-2022" - -> [!NOTE] -> A new version of Delivery Plans is available. This feature is now part of Azure Boards and replaces the [Delivery Plans extension](https://marketplace.visualstudio.com/items?itemName=ms.vss-plans). Delivery Plans provides support for the following tasks: -> - Add 20 team backlog levels for Azure DevOps Services or 15 backlog levels for Azure DevOps Server 2022 -> - Add custom portfolio backlogs as well as Epics -> - View work items that span several iterations -> - Reset Start Date and Target Date through drag and drop borders -> - Add backlog items to a team from a plan -> - View rollup progress of Features, Epics, and other portfolio items -> - View work item dependencies -> - Stakeholders can view plans - -For more information, see [Review team Delivery Plans](../plans/review-team-plans.md). -::: moniker-end - - -::: moniker range=">= azure-devops-2022" -- [Azure DevOps Open in Excel](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-open-work-items-in-excel) -- [Epic Roadmap extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.workitem-feature-timeline-extension), [Feature Timeline (Deprecated)](/previous-versions/azure/devops/all/extensions/epic-roadmap) -- [Feature Timeline extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.workitem-feature-timeline-extension), [Feature Timeline (Deprecated)](/previous-versions/azure/devops/all/extensions/feature-timeline) -- [Retrospectives](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives) -- [Split!](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-extension-split-work&ssr=false#overview) -- [Team Calendar](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-calendar) -- [Reactivations Report](https://marketplace.visualstudio.com/items?itemName=EnterpriseServicesDevOpsTeam.ServicesBugReactivationReport&ssr=false#overview) - -::: moniker-end - - -::: moniker range=">= azure-devops-2019 <= azure-devops-2020" -- [Azure DevOps Open in Excel](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-open-work-items-in-excel) -- [Delivery Plans](https://marketplace.visualstudio.com/items?itemName=ms.vss-plans) -- [Epic Roadmap extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.workitem-feature-timeline-extension), [Feature Timeline (Deprecated)](/previous-versions/azure/devops/all/extensions/epic-roadmap) -- [Feature Timeline extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.workitem-feature-timeline-extension), [Feature Timeline (Deprecated)](/previous-versions/azure/devops/all/extensions/feature-timeline) -- [Retrospectives](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives) -- [Split!](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-extension-split-work&ssr=false#overview) -- [Team Calendar](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-calendar) -- [Reactivations Report](https://marketplace.visualstudio.com/items?itemName=EnterpriseServicesDevOpsTeam.ServicesBugReactivationReport&ssr=false#overview) - -::: moniker-end - - -::: moniker range="tfs-2018" -- [Delivery Plans](https://marketplace.visualstudio.com/items?itemName=ms.vss-plans) -- [Epic Roadmap extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.workitem-feature-timeline-extension), [Feature Timeline (Deprecated)](/previous-versions/azure/devops/all/extensions/epic-roadmap) -- [Feature Timeline extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.workitem-feature-timeline-extension), [Feature Timeline (Deprecated)](/previous-versions/azure/devops/all/extensions/feature-timeline) -- [Retrospectives](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives) - -::: moniker-end - - - -## Customizing work item types - -::: moniker range=">= azure-devops-2019" - -- [Cascading Lists](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.cascading-picklists-extension) -- [Clickable Links](https://marketplace.visualstudio.com/items?itemName=MarkHawkes.clickable-link-control-extension) -- [Color picklist control](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.color-form-control) -- [Multi-value control](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-extensions-multivalue-control) -- [Work item form control library](https://marketplace.visualstudio.com/items?itemName=mohitbagra.vsts-wit-control-library) -- [Work item form one click actions](https://marketplace.visualstudio.com/items?itemName=mohitbagra.witoneclickactions) -- [Work Item Visualization](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization) -- [WSJF (Weighted Shortest Job First)](https://marketplace.visualstudio.com/items?itemName=MS-Agile-SAFe.WSJF-extension) - -::: moniker-end - - -::: moniker range="tfs-2018" - -- [Color picklist control](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.color-form-control) -- [Multivalue control](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-extensions-multivalue-control) -- [WSJF (Weighted Shortest Job First)](https://marketplace.visualstudio.com/items?itemName=MS-Agile-SAFe.WSJF-extension) - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -## Query and reporting - -- [Open in Power BI](https://marketplace.visualstudio.com/items?itemName=stansw.vsts-open-in-powerbi) -- [Query Based Boards](https://marketplace.visualstudio.com/items?itemName=realdolmen.EdTro-AzureDevOps-Extensions-QueryBasedBoards-Public) -- [Tags Manager](https://marketplace.visualstudio.com/items?itemName=YodLabs.TagsManager2) -- [Wiql Editor](https://marketplace.visualstudio.com/items?itemName=ottostreifel.wiql-editor) -- [Wiql to OData](https://marketplace.visualstudio.com/items?itemName=ms-eswm.wiql-to-odata) - -::: moniker-end - - -## Dashboard widgets - -::: moniker range=">= azure-devops-2019" - -- [Azure Application Insights Widgets](https://marketplace.visualstudio.com/items?itemName=ms-appinsights.ApplicationInsightsWidgets) -- [Countdown Widget](https://marketplace.visualstudio.com/items?itemName=ALM-DevOpsRangers.CountdownWidget) -- [GitHub Stats Widget](https://marketplace.visualstudio.com/items?itemName=YodLabs.yodlabs-githubstats) -- [Work Item Details Widget](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemDetails) -- [Roll-up Board Widget](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.RollUpBoard) - -::: moniker-end - -::: moniker range="tfs-2018" -- [Roll-up Board Widget](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.RollUpBoard) -::: moniker-end - - -## DevOps integration - -- [Creates a new work item from a build or release](https://marketplace.visualstudio.com/items?itemName=mspremier.CreateWorkItem#adding-the-task-to-a-yaml-definition) - -## Command-line interface - -::: moniker range="azure-devops" - -- [Azure DevOps CLI](../../cli/index.md) -- [Azure Boards Teams Tool CLI](https://marketplace.visualstudio.com/items?itemName=jessehouwing.azure-boards-teams-tool&ssr=false#overview) - -::: moniker-end - - -::: moniker range="< azure-devops" - -- [Azure Boards Teams Tool CLI](https://marketplace.visualstudio.com/items?itemName=jessehouwing.azure-boards-teams-tool&ssr=false#overview) - -::: moniker-end - -## Automation and miscellaneous tools - -- [Azure Boards Kanban Tools](https://marketplace.visualstudio.com/items?itemName=alm-devops-rangers.KanbanBoardTools) -- [Migration Tools for Azure DevOps](https://marketplace.visualstudio.com/items?itemName=nkdagility.vsts-sync-migration) -- [Microsoft Flow, Power Apps and Power Automate](https://marketplace.visualstudio.com/items?itemName=MS-Flow.microsoftflow) -- [Power Automate, Azure DevOps](https://powerautomate.microsoft.com/connectors/details/shared_visualstudioteamservices/azure-devops/) - -## Related articles - -- [Cross-service integration overview](../../cross-service/cross-service-overview.md) -- [Power Platform, Connectors, Azure DevOps](/connectors/visualstudioteamservices/) -- [Azure DevOps Work Items Microsoft Graph connector](/microsoftsearch/azure-devops-connector) -- [Connect to Azure DevOps from Power Apps](/power-apps/maker/canvas-apps/connections/azure-devops) \ No newline at end of file diff --git a/docs/boards/extensions/media/tracker/choose-area-path.png b/docs/boards/extensions/media/tracker/choose-area-path.png index 8c0f11a772d..5e62afa144d 100644 Binary files a/docs/boards/extensions/media/tracker/choose-area-path.png and b/docs/boards/extensions/media/tracker/choose-area-path.png differ diff --git a/docs/boards/extensions/media/tracker/create-links-manually.png b/docs/boards/extensions/media/tracker/create-links-manually.png index b79c0e6f8ee..116e012f267 100644 Binary files a/docs/boards/extensions/media/tracker/create-links-manually.png and b/docs/boards/extensions/media/tracker/create-links-manually.png differ diff --git a/docs/boards/extensions/media/tracker/filter.png b/docs/boards/extensions/media/tracker/filter.png index 8ef960f569d..b21e98eca0b 100644 Binary files a/docs/boards/extensions/media/tracker/filter.png and b/docs/boards/extensions/media/tracker/filter.png differ diff --git a/docs/boards/extensions/media/tracker/select-dependency-tracker.png b/docs/boards/extensions/media/tracker/select-dependency-tracker.png index b39a0c0ccd9..96e6ad2d932 100644 Binary files a/docs/boards/extensions/media/tracker/select-dependency-tracker.png and b/docs/boards/extensions/media/tracker/select-dependency-tracker.png differ diff --git a/docs/boards/extensions/migrate-integrate.md b/docs/boards/extensions/migrate-integrate.md index 4ed67fc4370..e625cc6c39b 100644 --- a/docs/boards/extensions/migrate-integrate.md +++ b/docs/boards/extensions/migrate-integrate.md @@ -1,102 +1,86 @@ --- -title: Migrate to or integrate work tracking data in Azure Boards +title: About migrating and integrating work tracking data titleSuffix: Azure Boards -description: Learn how you can migrate or integrate work tracking data from other software applications to Azure Boards. +description: Learn how you can migrate or integrate work tracking data from other software applications to Azure Boards, plus available extensions. ms.custom: extensions, engagement-fy23 ms.service: azure-devops-boards ms.topic: conceptual ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 10/01/2021 +ms.date: 02/11/2025 --- -# Migrate and integrate work tracking data in Azure Boards +# About migrating and integrating work tracking data [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You have a choice of tools to help you migrate your work tracking data to the Azure DevOps platform. This article provides an overview of what's available and links to tools that support migration of work tracking data and processes. You can also integrate Azure Boards with many third-party tools. +There are various tools available to help you migrate your work tracking data to the Azure DevOps platform. This article provides an overview of these tools and links to resources that support the migration of work tracking data and processes. You can also integrate Azure Boards with numerous non-Microsoft tools and extensions. -## Migrate from an on-premises Azure DevOps server +> [!NOTE] +> With [Azure DevOps Marketplace extensions for Azure Boards](https://marketplace.visualstudio.com/search?target=AzureDevOps&category=Azure%20Boards&sortBy=Installs), you can customize and enhance the default experience. For more information, see the [list of recommended extensions for Azure Boards](#extensions-for-azure-boards), further in this article. -The data migration tool for Azure DevOps provides a high fidelity way to migrate collection databases from Azure DevOps Server to Azure DevOps Services. For more information, see [Migrate data from Azure DevOps Server to Azure DevOps Services](../../migrate/migration-overview.md). +## Migrate from Azure DevOps Server -## Migrate data between Azure DevOps Projects +The Data Migration Tool for Azure DevOps provides a high fidelity way to migrate collection databases from Azure DevOps Server to Azure DevOps Services. For more information, see [Migrate data from Azure DevOps Server to Azure DevOps Services](../../migrate/migration-overview.md). -The [Azure DevOps Migration Tools](https://marketplace.visualstudio.com/items?itemName=nkdagility.vsts-sync-migration) marketplace extension allows you to bulk edit and migrate data between Azure DevOps Projects on both on-premises and the cloud. This tool supports the following tasks: +## Migrate data between projects + +You can search for extensions in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops) that allow you to bulk edit and migrate data between project on both on-premises and the cloud. Such tools generally support the following tasks: - Migrate work items from one project to another project and synchronize changes after a migration - Merge many projects into a single project - Split one project into many projects - Assist changing process templates - Edit work items in bulk -- Migrate test suites and test plans - -For more information, see [Azure DevOps Migration Tools](https://nkdagility.github.io/azure-devops-migration-tools/). +- Migrate test suites and test plans -[OpsHub Azure DevOps Migrator](https://marketplace.visualstudio.com/items?itemName=vs-publisher-1455028.OpsHubVisualStudioOnlineMigrationUtility) (OADOM) formerly known as OpsHub Visual Studio Migration Utility(OVSMU) enables a seamless migration between Azure DevOps Server and Azure DevOps Services. Migrate projects from DevOps Services to a collection on DevOps Server including: +### Migrate data between projects without downtime -- All version control information and history -- All work items and history -- All test cases and test results -- Supports Team Foundation Server 2018 and Azure DevOps Server versions 2019, 2020, and 2022 -- Supports Azure DevOps Services. +There are non-Microsoft tools available in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops) that enable seamless migration without downtime or disruption, even when the target environment isn't empty or when templates differ. These tools generally support: -[OADOM](https://www.opshub.com/products/opshub-azure-devops-migrator/) covers the following scenarios: - +- Version control information and history, including original dates and users added to comments. +- Work items, both standard and custom, along with their history, retaining the original dates and users. +- Test plans, test suites, test cases, and test results. +- Iteration, area path, group, team, and user data. +- Dashboards, queries, widgets, and pipelines. +- Compatibility with Azure DevOps Server versions 2010 and later. +- Support for Azure DevOps Services. ## Migrate process models between Azure DevOps organizations -The [Process Tools for Azure DevOps](https://marketplace.visualstudio.com/items?itemName=nkdagility.processtemplate) marketplace extension provides support to complete the following tasks: -- Migrate Inherited Processes between Organizations -- Upload an On-premises XML process model from an export - For constraints on process template definitions that you can import, see [Resolve validation errors for process import](../../organizations/settings/work/import-process/resolve-errors.md). - -## Migrate between legacy tools and Azure DevOps - -The [OpsHub Migration Manager](https://marketplace.visualstudio.com/items?itemName=vs-publisher-1455028.OMM) marketplace extension supports full fidelity, large-scale data migration projects out of the box between legacy or ALM tools and Azure DevOps. OMM offers the following benefits: - -- Zero downtime migration or non-disruptive migration -- Factory approach for large-scale migration projects -- Full fidelity migration with history preservation for all artifacts, comments, attachments, and relationships - + ## Export and import work tracking data -The main tool you can use to import work tracking data you've exported from elsewhere is Microsoft Excel. Excel supports publishing a flat list of work items or a hierarchical tree of parent-child linked work items. For more information, see [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). - -If you want to migrate from Jira to Azure Boards, consider using the Marketplace extension, [Jira to Azure DevOps work item migration tool](https://marketplace.visualstudio.com/items?itemName=solidify.jira-devops-migration). This tool provides support for the following tasks: -- Export Jira issues from Jira queries -- Map users from Jira to users in Azure DevOps -- Migrate work item field data -- Migrate links and attachments -- Migrate history +The main tool you can use to import work tracking data you exported from elsewhere is Microsoft Excel. Excel supports publishing a flat list of work items or a hierarchical tree of parent-child linked work items. For more information, see [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). ## Integrate with GitHub -Azure Boards and Azure DevOps Server 2019 integrate with GitHub. By connecting Azure Boards with GitHub repositories, you enable linking between GitHub commits, pull requests, and issues to work items. You can use GitHub for software development while using Azure Boards to plan and track your work. +Azure Boards (cloud) and Azure DevOps Server integrate with GitHub. Connect Azure Boards with GitHub repositories to link between GitHub commits, pull requests, and issues to work items. You can use GitHub for software development while using Azure Boards to plan and track your work. -To learn how, see [Connect Azure Boards to GitHub](../github/connect-to-github.md). +For more information, see [Connect Azure Boards to GitHub](../github/connect-to-github.md). -## Integrate with third-party tools using service hooks +## Integrate with non-Microsoft tools using service hooks -You can integrate Azure Boards with other third-party tools such as Jenkins and Trello. Using service hooks you can generate actions based on Azure DevOps events. For more information, review one of the following articles: +You can integrate Azure Boards with other non-Microsoft tools such as Jenkins and Trello. Using service hooks you can generate actions based on Azure DevOps events. For more information, see the following articles: - [Create a service hook for Azure DevOps with Jenkins](../../service-hooks/services/jenkins.md) - [Create a service hook for Azure DevOps with Trello](../../service-hooks/services/trello.md) +- [Integrate with service hooks](../../service-hooks/overview.md) -## Project and portfolio management - -The following tools support integration and synchronization with Azure DevOps with one or more project and portfolio management tools. These tools also support integration between Azure Boards and Microsoft Project Online or Microsoft Project Server. +## Extensions for Azure Boards -- [OpsHub Integration Manager(OIM)](https://www.opshub.com/products/opshub-integration-manager/) is an enterprise class integration platform. It enables bi-directional synchronization for Azure DevOps(Server and Services) with 50+ ALM, DevOps, Project, and Portfolio Management tools out of the box. It enables synchronization of all work items including test artifacts with an easy to use mapping UI and is scalable for any number of projects and teams. -- [ConnectAll](https://www.connectall.com/) helps organizations achieve effective Value Stream Management by connecting the applications used to collaborate, drive decisions, and manage artifacts that are used during the software delivery process, like ALM, Agile, and DevOps. -- [Project Connect](https://www.wicresoftinternational.com/about-us) offers a seamless approach to exchange critical information between development teams and project teams using Microsoft Project Online and Azure DevOps Services. -- [Tasktop](http://www.tasktop.com/products) provides enterprise-grade integration between Microsoft Project Server, Azure DevOps, and to most other popular Agile, DevOps and Systems Development Lifecycle (SDLC) tools. +The following table contains some Microsoft extensions. You can search for other non-Microsoft extensions in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops). +| Category | Extensions | +|--------------|-------------| +| **Automation** | [Power Automate, Azure DevOps](https://powerautomate.microsoft.com/connectors/details/shared_visualstudioteamservices/azure-devops/) | +| **Command-line interface** | [Azure DevOps CLI](../../cli/index.md) | +| **Customizing work item types** | - [Cascading Lists](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.cascading-picklists-extension)
- [Color picklist control](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.color-form-control)
- [Multi-value control](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-extensions-multivalue-control)
- [Work Item Visualization](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization)
- [WSJF (Weighted Shortest Job First)](https://marketplace.visualstudio.com/items?itemName=MS-Agile-SAFe.WSJF-extension) | +| **Dashboard widgets** | - [Azure Application Insights widget](https://marketplace.visualstudio.com/items?itemName=ms-appinsights.ApplicationInsightsWidgets)
- [Work Item Details widget](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemDetails)
- [Roll-up Board widget](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.RollUpBoard) | +| **Product planning** | - [Azure DevOps Open in Excel](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-open-work-items-in-excel)
- [Epic Roadmap extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.workitem-feature-timeline-extension), [Feature Timeline (Deprecated)](/previous-versions/azure/devops/all/extensions/epic-roadmap)
- [Feature Timeline extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.workitem-feature-timeline-extension), [Feature Timeline (Deprecated)](/previous-versions/azure/devops/all/extensions/feature-timeline)
- [Retrospectives](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives)
- [Split!](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-extension-split-work&ssr=false#overview)
- [Team Calendar](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-calendar)
- [Reactivations Report](https://marketplace.visualstudio.com/items?itemName=EnterpriseServicesDevOpsTeam.ServicesBugReactivationReport&ssr=false#overview) | +| **Querying and reporting** | [WIQL to OData](https://marketplace.visualstudio.com/items?itemName=ms-eswm.wiql-to-odata) | ## Related articles -- [Migrate data from Azure DevOps Server to Azure DevOps Services](../../migrate/migration-overview.md) -- [Integrate with service hooks](../../service-hooks/overview.md) - - - +- [Bulk add or modify work items with Microsoft Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) +- [Use the Azure DevOps REST API](/rest/api/azure/devops/) diff --git a/docs/boards/extensions/toc.yml b/docs/boards/extensions/toc.yml index 572f34f6ad5..b56fd03807d 100644 --- a/docs/boards/extensions/toc.yml +++ b/docs/boards/extensions/toc.yml @@ -1,12 +1,6 @@ -- name: Overview - href: index.md - displayname: product, plan, query, widget, dashboards, command line interface, Excel, Retrospective, calendar, reactivations - name: Migrate and integrate href: migrate-integrate.md displayname: export, import, integrate, GitHub, third-party, service hooks, Project, project management, portfolio management, ConnectAll, TaskTop, process model -- name: Delivery Plans - href: delivery-plans.md - displayname: filter, roadmap, calendar, multi-team views, cards - name: Dependency Tracker href: dependency-tracker.md - name: Azure Boards with Slack @@ -16,9 +10,9 @@ - name: Deprecated extensions items: - name: Epic Roadmap >> - href: /previous-versions/azure/devops/all/extensions/epic-roadmap + href: /previous-versions/azure/devops/all/extensions/epic-roadmap - name: Feature Timeline >> - href: /previous-versions/azure/devops/all/extensions/feature-timeline + href: /previous-versions/azure/devops/all/extensions/feature-timeline - name: Project Server Integration >> href: /previous-versions/azure/devops/reference/tfs-ps-sync/ - name: TFS-SharePoint Integration >> diff --git a/docs/boards/faqs.yml b/docs/boards/faqs.yml index 9002035565e..d7c804b7db3 100644 --- a/docs/boards/faqs.yml +++ b/docs/boards/faqs.yml @@ -9,8 +9,7 @@ metadata: ms.topic: faq monikerRange: '<= azure-devops' "recommendations": "true" - ms.date: 05/08/2023 - + ms.date: 01/05/2024 title: Azure Boards FAQs @@ -18,11 +17,10 @@ title: Azure Boards FAQs summary: | [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - Find answers to frequently asked questions when using Azure Boards. For FAQs specific to queries or Microsoft Excel integration to add or modify work items defined in Azure DevOps, see [Query FAQs](queries/query-faqs.yml) and [FAQs: Work in Excel connected to Azure Boards](backlogs/office/faqs.yml). + Find answers to frequently asked questions about using Azure Boards. For FAQs specific to queries or Microsoft Excel integration to add or modify work items defined in Azure DevOps, see [Query FAQs](queries/query-faqs.yml) and [FAQs: Work in Excel connected to Azure Boards](backlogs/office/faqs.yml). You can view a list of features that are on our roadmap for Azure Boards from the [Features Timeline](/azure/devops/release-notes/features-timeline). To request a feature or up-vote a feature, go to our [Developer Community page](https://developercommunity.visualstudio.com/spaces/21/visual-studio-team-services.html?type=idea). - sections: - name: Access and permissions @@ -36,7 +34,7 @@ sections: answer: | ::: moniker range="azure-devops" For private projects, you can grant access to an unlimited number of users by assigning them Stakeholder access. For public projects, anonymous users—ones who don't sign into the project—can view all work items. For more information, see [Stakeholder access quick reference](../organizations/security/stakeholder-access.md) and [Make a private project public](../organizations/projects/make-project-public.md). - Also, if your organization uses Azure Active Directory to manage user access, you can [add external users to your organization](../organizations/accounts/add-external-user.md). + Also, if your organization uses Microsoft Entra ID to manage user access, you can [add external users to your organization](../organizations/accounts/add-external-user.md). ::: moniker-end ::: moniker range="< azure-devops" @@ -49,11 +47,12 @@ sections: - [Set work tracking and plan permissions](../organizations/security/set-permissions-access-work-tracking.md?toc=/azure/devops/boards/toc.json) - [Grant or restrict permissions to select tasks](../organizations/security/restrict-access.md?toc=/azure/devops/boards/toc.json) - - question: Can caching impact rules applied to work items? + - question: Can caching affect rules applied to work items? answer: | - **Yes**. Conditional rules based on user or group membership are cached for your web browser. If you find yourself restricted to update a work item, you may have encountered one of these rules. If you believe you've encountered an issue that doesn't apply to you, see [Work item form IndexDB caching issues](../organizations/settings/work/troubleshoot-work-item-form-caching-issues.md). To learn more about conditional rules, see [Rules and rule evaluation](../organizations/settings/work/rule-reference.md). - + **Yes**. Conditional rules based on user or group membership get cached for your web browser. If you find yourself restricted to update a work item, you probably encountered one of these rules. For more information about conditional rules, see [Rules and rule evaluation](../organizations/settings/work/rule-reference.md). + If your cache stores outdated rules, you can wait for the client cache to expire within three days, or you can clear the cache. + To clear the cache, run the following command in the browser command window and then refresh the browser: window.indexedDB.deleteDatabase("wit") - question: What client tools support work tracking with Azure Boards? answer: | @@ -102,13 +101,13 @@ sections: - question: How can I best track dependencies? answer: | - You can track dependencies between work items by linking them using a related or other link type. See [Link work items](backlogs/add-link.md) and [Linking, traceability, and managing dependencies](queries/link-work-items-support-traceability.md). + You can track dependencies between work items by linking them using a related or other link type. See [Link work items to other objects](backlogs/add-link.md). ::: moniker range=">= azure-devops-2022" - You can view dependencies using [Delivery Plans (Preview)](plans/review-team-plans.md). + You can view dependencies using [Delivery Plans](plans/review-team-plans.md). ::: moniker-end - If you're tracking dependencies across one or more organizations, you may want to use the [Dependency Tracker](extensions/dependency-tracker.md). + If you're tracking dependencies across one or more organizations, you might want to use the [Dependency Tracker](extensions/dependency-tracker.md). - question: What determines which work item type should be a parent for another work item type? @@ -122,29 +121,46 @@ sections: With Azure Boards (cloud service), you can choose to copy child work items when copying a work item. For more information, see [Copy or clone work items](backlogs/copy-clone-work-items.md#copy-clone). ::: moniker-end - ::: moniker range="< azure-devops-2020" - This feature isn't supported at this time for Azure DevOps 2019 and earlier versions. Copying a work item doesn't copy any parent-child linked work items. However, is available for Azure DevOps Server 2020.1 update and Azure Boards (cloud service). + - The easiest way to accomplish the task of copying many work items with child items, is to create parent-child links to new work items using Excel. To learn how, see [Bulk add or modify work items with Excel, Add a hierarchy of linked work items](backlogs/office/bulk-add-modify-work-items-excel.md#import-work-items-as-a-tree-list). + - question: How do I bulk modify a rich-text field? - Other solutions include employing one of the following Marketplace extensions: - - [Work item form one click actions](https://marketplace.visualstudio.com/items?itemName=mohitbagra.witoneclickactions) - - [1-Click Child-Links](https://marketplace.visualstudio.com/items?itemName=ruifig.vsts-work-item-one-click-child-links) - - [1-Click Tasks](https://marketplace.visualstudio.com/items?itemName=ruifig.vsts-work-item-one-click-tasks) - ::: moniker-end + answer: | + See [Bulk modify work items, Bulk modify rich-text fields](backlogs/bulk-modify-work-items.md#rich-text). + - name: Automation rules - - question: How do I bulk modify a rich-text field? + questions: + - question: Is there way to make the parent active when a child is active? + answer: | + Yes, you can set your backlog level to include two different rules. The first rule it to set the parent as active when any of its children are set to active. The second rule is to set parent to resolved or closed when all the children are closed. These rules can be configured for backlog level. For more information, see [Automate work item state transitions](work-items/automate-work-item-state-transitions.md) + - question: Why are my work items automatically changing state? answer: | - See [Bulk modify work items, Bulk modify rich-text fields](backlogs/bulk-modify-work-items.md#rich-text). + Work items automatically change state after your team administrator set up automation rules on the backlog. Create rules to automatically set the state to active or closed depending on the state change of its children. For more information, see [Automate work item state transitions](work-items/automate-work-item-state-transitions.md). + + - question: Why are the rules not triggering when I reactivate a child item? + answer: | + Rules only trigger when the state of the child item moves from New to Active or into Closed. Rules don't trigger when the state of the child item moves from Closed back to Active. This is currently by design. + + - question: Can I set automation rules per work item type or state? + answer: | + No, the rules are applied to all work item types in that backlog level. We use state categories instead of states because state categories are consistent across all work item types. + + - question: Can I set up automation rules for user stories but not for features or epics? + answer: | + Yes, rules are configured per backlog level. Automation rules on the user stories backlog don't affect features or epics. But, you can also set up rules separately for features and epics. For more information, see [Automate work item state transitions](work-items/automate-work-item-state-transitions.md). + + - question: Why are automation rules not working if the child or parent items belongs to a different team or project? + answer: | + Rules only trigger if both the parent and children belong to the same team. We don’t want rules automatically triggered for items that belong to other teams. For more information, see [Automate work item state transitions](work-items/automate-work-item-state-transitions.md). - - name: Backlogs and Boards + - name: Backlogs and boards questions: - question: What's the difference between a backlog and a board? answer: | - Each backlog and board represents a filtered set of work items based on team area path and iteration path assignments. Backlogs list work items, boards display work items as cards. To understand how the filtering is applied, see [About teams and Agile tools, Team defaults referenced by backlogs and boards](../organizations/settings/about-teams-and-settings.md#team-defaults). + Each backlog and board represents a filtered set of work items based on team area path and iteration path assignments. Backlogs list work items, boards display work items as cards. To understand how the filtering is applied, see [About teams and Agile tools, Team defaults referenced by backlogs and boards](../organizations/settings/about-teams-and-settings.md#team-defaults-referenced-by-backlogs-and-boards). - question: How do I add a backlog or board? answer: | @@ -152,13 +168,12 @@ sections: - question: What limits should I be aware of? answer: | - There are many limits Azure DevOps imposes such as the number of work items that display on a backlog or board, numbers of teams you can define, and more. For a full list, see [Work tracking, process, and project limits](../organizations/settings/work/object-limits.md). + Azure DevOps imposes limits such as the number of work items that display on a backlog or board, numbers of teams you can define, and more. For a full list, see [Work tracking, process, and project limits](../organizations/settings/work/object-limits.md). - question: How do I migrate my existing backlog to Azure Boards? answer: | See [Azure Boards migration and integration](extensions/migrate-integrate.md). - - question: How do the three types of backlogs--product, portfolio, and sprint backlogs--differ? answer: | Each backlog lists a filtered set of work items based on the team's selected area path, iteration paths, and work item types. @@ -166,9 +181,9 @@ sections: - **Portfolio backlog**: By default lists Features (all process models) for the Features backlog, and Epics (Agile, Scrum, and CMMI) for the Epic backlog. Provides options to show **Parents** and **In Progress** or **Completed** child items. - **Sprint backlog**: By default lists all product backlog items assigned to the selected iteration, regardless of status. Provides options to show **Work details**. - - question: Can I define sprints and use them with my Kanban board? + - question: Can I define sprints and use them with my board? answer: | - **Yes**. You can assign sprints to work items and filter your Kanban board based on the iteration path. For more information, see [Filter your Kanban board](./backlogs/filter-backlogs-boards-plans.md). + **Yes**. You can assign sprints to work items and filter your board based on the iteration path. For more information, see [Filter your board](./backlogs/filter-backlogs-boards-plans.md). - question: If I manage bugs with tasks, can I add bugs as a checklist to a requirement? answer: | @@ -180,11 +195,10 @@ sections: That said, we recommend that you use [Delivery Plans](plans/review-team-plans.md) to view dependencies and a calendar view of work. - If your organization supports connection to Microsoft Project, you may find more [Marketplace extensions](https://marketplace.visualstudio.com/search?target=AzureDevOps&category=Azure%20Boards&sortBy=Relevance) that support connection of Azure DevOps to Microsoft Project. + If your organization supports connection to Microsoft Project, you might find more [Marketplace extensions](https://marketplace.visualstudio.com/search?target=AzureDevOps&category=Azure%20Boards&sortBy=Relevance) that support connection of Azure DevOps to Microsoft Project. For more context, see [The Critical Path on Agile Projects](https://www.mountaingoatsoftware.com/blog/the-critical-path-on-agile-projects) and [Running a lean startup on Azure DevOps](https://medium.com/@giladkhen/running-a-lean-startup-on-azure-devops-5934ced2cc42). - - name: Rollup questions: @@ -194,9 +208,7 @@ sections: ::: moniker range=">= azure-devops-2020" Rollup columns allow you to view progress bars or totals of numeric fields or descendant items within a hierarchy. Descendant items correspond to all child items within the hierarchy. You can add one or more rollup columns to a product or portfolio backlog. You can add rollup columns to a product or portfolio backlog. See {Display rollup progress or totals](backlogs/display-rollup.md). ::: moniker-end - ::: moniker range="< azure-devops-2020" - Rollup provides summed values of select fields for all child work items of a parent. For more information, see [Rollup of work and other fields](../reference/xml/support-rollup-of-work-and-other-fields.md). - ::: moniker-end + - question: Can I get a rollup of team capacity? @@ -204,52 +216,51 @@ sections: **No**. The data entered for team capacity isn't stored in the regular data stores. - - - name: Kanban boards + - name: Boards questions: - - question: Is there a way to widen columns on a Kanban board? + - question: Is there a way to widen columns on a board? answer: | **No**. This feature isn't supported. It's a suggested feature, which you can upvote by going to our [Developer Community page](https://developercommunity.visualstudio.com/t/Resize-board-column-width/901212?space=21&q=column+width). - - question: Can I query based on Kanban board columns? + - question: Can I query based on board columns? answer: | - **Yes**, see [Query by assignment or workflow changes, Kanban board change queries](queries/query-by-workflow-changes.md#query-changes-to-a-kanban-board). + **Yes**, see [Query by assignment or workflow changes, board change queries](queries/query-by-workflow-changes.md#query-changes-to-a-kanban-board). - - question: Can I view a query as a Kanban board? + - question: Can I view a query as a board? answer: | **Yes**, by adding the [Query Based Boards](https://marketplace.visualstudio.com/items?itemName=realdolmen.EdTro-AzureDevOps-Extensions-QueryBasedBoards-Public) Marketplace extension. - - question: Is there a way to copy a Kanban configuration to another team? + - question: Is there a way to copy a board configuration to another team? answer: | **Yes**, by adding the [Azure Boards Kanban Tools](https://marketplace.visualstudio.com/items?itemName=alm-devops-rangers.KanbanBoardTools) Marketplace extension. - - question: Can I list items based on their Kanban column assignment? + - question: Can I list items based on their column assignment? answer: | - **Yes**, you can track column moves on a Kanban board by using the [Board Column and Board Column Done fields](queries/query-by-workflow-changes.md#kanban_query_fields). + **Yes**, you can track column moves on a board by using the [Board Column and Board Column Done fields](queries/query-by-workflow-changes.md#kanban_query_fields). - question: What if I get the error message, "The column configurations aren't valid"? answer: | - If you get the following error when you open your Kanban board, you need to correct the configuration. The main reason for this error is that the workflow states of work item types that have been added to the **Requirement** category aren't mapped to the column. + If you get the following error when you open your board, you need to correct the configuration. The main reason for this error is that the workflow states of work item types added to the **Requirement** category aren't mapped to the column. > [!div class="mx-imgBorder"] - > ![Screenshot that shows a configuration error message on a Kanban board.](./backlogs/media/setup-backlog/column-config-error.png) + > ![Screenshot that shows a configuration error message on a board.](./backlogs/media/setup-backlog/column-config-error.png) Select **Correct this now** to open the **Settings** dialog. - In the following example, two new states are added: **Triaged** for bug, and **Investigate** for user story. Each state is then mapped to an existing or new column. After each state is mapped to a column, the Kanban board displays the work items assigned to these states. + In the following example, two new states are added: **Triaged** for bug, and **Investigate** for user story. Each state is then mapped to an existing or new column. After each state is mapped to a column, the board displays the work items assigned to these states. > [!div class="mx-imgBorder"] - > ![Screenshot showing Kanban board settings, columns.](./boards/media/add-columns-custom-states-mapping.png) + > ![Screenshot showing board settings, columns.](./boards/media/add-columns-custom-states-mapping.png) - question: Can I use swimlanes and set up swimlane rules? answer: | - **Yes**, you can [add or remove swimlanes](boards/expedite-work.md) on your Kanban board. You can also [set up swimlane rules](boards/expedite-work.md#set-up-swimlane-rules), where when certain conditions are met, Azure Boards automatically moves work items into specific lanes. + **Yes**, you can [add or remove swimlanes](boards/expedite-work.md) on your board. You can also [set up swimlane rules](boards/expedite-work.md#set-up-swimlane-rules), where when certain conditions are met, Azure Boards automatically moves work items into specific lanes. - name: Work item templates @@ -272,14 +283,14 @@ sections: answer: | **Example request**: *When creating a template, I would like the Parent User Story to be defaulted. There isn't a predetermined field in the template. Would/could this function be under a user-defined selection?* - No, there's no native support for creating hierarchy templates. In particular, you can't specify a default parent work item. You can, however, quickly copy tasks, bugs, and other items using [Excel](backlogs/office/bulk-add-modify-work-items-excel.md) to apply parent-child links in a tree list. Or, you can use a Kanban board to add child tasks, backlog items, or features. For more information, see: + No, there's no native support for creating hierarchy templates. In particular, you can't specify a default parent work item. You can, however, quickly copy tasks, bugs, and other items using [Excel](backlogs/office/bulk-add-modify-work-items-excel.md) to apply parent-child links in a tree list. Or, you can use a board to add child tasks, backlog items, or features. For more information, see: - [Add task checklists](boards/add-task-checklists.md) - [Add, run, and update inline tests](boards/add-run-update-tests.md) - [Add features and epics](boards/kanban-epics-features-stories.md) - ::: moniker range=">= azure-devops-2019" - Alternatively, you may find a solution for creating child work items by installing one of the following Marketplace extensions: - - [Work item form one click actions](https://marketplace.visualstudio.com/items?itemName=mohitbagra.witoneclickactions) + ::: moniker range="<=azure-devops" + Alternatively, you might find a solution for creating child work items by installing one of the following Marketplace extensions: + - [Work item form one-click actions](https://marketplace.visualstudio.com/items?itemName=mohitbagra.witoneclickactions) - [1-Click Child-Links](https://marketplace.visualstudio.com/items?itemName=ruifig.vsts-work-item-one-click-child-links) - [1-Click Tasks](https://marketplace.visualstudio.com/items?itemName=ruifig.vsts-work-item-one-click-tasks) ::: moniker-end @@ -304,7 +315,6 @@ sections: answer: | **No**. This feature isn't supported at this time. - - name: Configuration and customizations questions: - question: What is configurable or customizable? @@ -313,7 +323,6 @@ sections: For FAQs on configuration and customization, see [Azure Boards Configuration and Customization FAQs](../organizations/settings/work/faqs.yml). - additionalContent: | ## Related articles - [Query FAQs](queries/query-faqs.yml) diff --git a/docs/boards/get-started/media/about-boards/boards-hubs.png b/docs/boards/get-started/media/about-boards/boards-hubs.png index 8e57469b04c..3782ce1734f 100644 Binary files a/docs/boards/get-started/media/about-boards/boards-hubs.png and b/docs/boards/get-started/media/about-boards/boards-hubs.png differ diff --git a/docs/boards/get-started/media/customize-boards/boards-agile-customized-view-s155.png b/docs/boards/get-started/media/customize-boards/boards-agile-customized-view-s155.png deleted file mode 100644 index ad3000fe765..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/boards-agile-customized-view-s155.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/boards-agile-customized-view.png b/docs/boards/get-started/media/customize-boards/boards-agile-customized-view.png deleted file mode 100644 index 3919bdd7f8c..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/boards-agile-customized-view.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/boards-customized-view-s155.png b/docs/boards/get-started/media/customize-boards/boards-customized-view-s155.png deleted file mode 100644 index 9d432c673e3..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/boards-customized-view-s155.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/boards-customized-view.png b/docs/boards/get-started/media/customize-boards/boards-customized-view.png deleted file mode 100644 index 4cf40afe341..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/boards-customized-view.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/open-settings-agile-s155.png b/docs/boards/get-started/media/customize-boards/open-settings-agile-s155.png deleted file mode 100644 index ae0dd152a18..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/open-settings-agile-s155.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/open-settings-agile.png b/docs/boards/get-started/media/customize-boards/open-settings-agile.png deleted file mode 100644 index 5502afe3944..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/open-settings-agile.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/open-settings-s155.png b/docs/boards/get-started/media/customize-boards/open-settings-s155.png deleted file mode 100644 index 4bfe1a092ff..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/open-settings-s155.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/open-settings.png b/docs/boards/get-started/media/customize-boards/open-settings.png deleted file mode 100644 index fce121ee3a2..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/open-settings.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/settings-backlogs-agile-dialog.png b/docs/boards/get-started/media/customize-boards/settings-backlogs-agile-dialog.png deleted file mode 100644 index c1d06261550..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/settings-backlogs-agile-dialog.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/settings-backlogs-dialog.png b/docs/boards/get-started/media/customize-boards/settings-backlogs-dialog.png deleted file mode 100644 index 55198d9d663..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/settings-backlogs-dialog.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/settings-fields-agile-change-priority.png b/docs/boards/get-started/media/customize-boards/settings-fields-agile-change-priority.png deleted file mode 100644 index 35541e38eb5..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/settings-fields-agile-change-priority.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/settings-fields-agile-dialog.png b/docs/boards/get-started/media/customize-boards/settings-fields-agile-dialog.png deleted file mode 100644 index e93aa658212..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/settings-fields-agile-dialog.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/settings-fields-change-priority.png b/docs/boards/get-started/media/customize-boards/settings-fields-change-priority.png deleted file mode 100644 index 232d4f69eb2..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/settings-fields-change-priority.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/settings-fields-dialog.png b/docs/boards/get-started/media/customize-boards/settings-fields-dialog.png deleted file mode 100644 index 9ecbc3c1bee..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/settings-fields-dialog.png and /dev/null differ diff --git a/docs/boards/get-started/media/customize-boards/settings-swimlanes-dialog-expedite.png b/docs/boards/get-started/media/customize-boards/settings-swimlanes-dialog-expedite.png deleted file mode 100644 index b5dcf1d7ca1..00000000000 Binary files a/docs/boards/get-started/media/customize-boards/settings-swimlanes-dialog-expedite.png and /dev/null differ diff --git a/docs/boards/get-started/media/plan-track-work/open-boards.png b/docs/boards/get-started/media/plan-track-work/open-boards.png index 5939d959e13..bab2767efb8 100644 Binary files a/docs/boards/get-started/media/plan-track-work/open-boards.png and b/docs/boards/get-started/media/plan-track-work/open-boards.png differ diff --git a/docs/boards/get-started/media/plan-track-work/select-from-all-team-boards-dropdown-menu.png b/docs/boards/get-started/media/plan-track-work/select-from-all-team-boards-dropdown-menu.png index 1e00457e9a4..97d84b3fbf0 100644 Binary files a/docs/boards/get-started/media/plan-track-work/select-from-all-team-boards-dropdown-menu.png and b/docs/boards/get-started/media/plan-track-work/select-from-all-team-boards-dropdown-menu.png differ diff --git a/docs/boards/get-started/media/track-issues/open-kanban-board-issues.png b/docs/boards/get-started/media/track-issues/open-kanban-board-issues.png deleted file mode 100644 index 3db2f6f2ad7..00000000000 Binary files a/docs/boards/get-started/media/track-issues/open-kanban-board-issues.png and /dev/null differ diff --git a/docs/boards/get-started/permissions-access-boards.md b/docs/boards/get-started/permissions-access-boards.md index cd451fc4476..863d21ce0c0 100644 --- a/docs/boards/get-started/permissions-access-boards.md +++ b/docs/boards/get-started/permissions-access-boards.md @@ -78,7 +78,7 @@ Stakeholder access supports business owners. It also supports analysts and other - [Add another team](../../organizations/settings/add-teams.md) - [Add a team administrator](../../organizations/settings/add-team-administrator.md) - [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) -- [Grant or restrict access to select features and functions](../../organizations/security/restrict-access.md) +- [Manage access to specific features and functions](../../organizations/security/restrict-access.md) - [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md) diff --git a/docs/boards/get-started/plan-track-work.md b/docs/boards/get-started/plan-track-work.md index c5e85e61623..ebc90fac764 100644 --- a/docs/boards/get-started/plan-track-work.md +++ b/docs/boards/get-started/plan-track-work.md @@ -1,441 +1,389 @@ --- title: Plan and track work in Azure Boards titleSuffix: Azure Boards -description: Learn how to plan and track work on your Kanban board. +description: Learn how to plan and track work by using Azure Boards using the Agile, Basic, Scrum, or Capability Maturity Model Integration (CMMI) processes. ms.custom: boards-get-started ms.service: azure-devops-boards ms.author: chcomley author: chcomley -ms.topic: quickstart +ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 03/17/2023 +ms.date: 10/08/2024 +#customer intent: As a team member, I want to understand how to use the different processes to manage our team projects. --- # Plan and track work in Azure Boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -In this article, learn how to use Azure Boards to plan and track your work using an **Agile**, **Basic**, **Scrum**, or **Capability Maturity Model Integration (CMMI)** process. For more information, see [About processes and process templates](../work-items/guidance/choose-process.md). +In this article, learn how to use Azure Boards to plan and track your work using an *Agile*, *Basic*, *Scrum*, or *Capability Maturity Model Integration (CMMI)* process. For more information, see [About processes and process templates](../work-items/guidance/choose-process.md). -[!INCLUDE [temp](../includes/basic-process-note.md)] +[!INCLUDE [basic process](../includes/basic-process-note.md)] -#### [Agile process](#tab/agile-process) +#### [Agile process](#tab/agile-process) The Agile process uses various work item types such as user stories, tasks, bugs, features, and epics to plan and track work. Begin by adding user stories and grouping them into features if needed. You can add tasks to a user story to track more details. -> [!div class="mx-tdCol2BreakAll"] -> |Work item types| Backlog hierarchy | -> |------|---------| -> |![Agile process work item types, conceptual image.](media/about-boards/agile-process-wits.png) | ![Screenshot of Agile process Hierarchical backlog.](media/about-boards/agile-hierarchy.png) | - -Within each work item form, you can describe the work to be done, assign work to project contributors, track status, and collaborate with others through the Discussion section. +| Work item types | Backlog hierarchy | +|:------|:---------| +|:::image type="content" source="media/about-boards/agile-process-wits.png" alt-text="Diagram shows Agile process work item types in a hierarchy."::: | :::image type="content" source="media/about-boards/agile-hierarchy.png" alt-text="Screenshot of Agile process Hierarchical backlog."::: | -We show you how to add user stories and child tasks from the web portal and add details to those work items. +In each work item form, you can describe the work to be done, assign work to project contributors, track status, and collaborate with others through the **Discussion** section. This article describes how to add user stories and child tasks from the web portal and add details to those work items. -#### [Basic process](#tab/basic-process) +#### [Basic process](#tab/basic-process) -The Basic process offers three work item types - epics, issues, and tasks - for planning and tracking work. Begin by adding issues to track user stories, bugs, or feature items. For grouping, define epics. To track more details, add tasks to an issue. +The Basic process offers three work item types for planning and tracking work: epics, issues, and tasks. To begin, add issues to track user stories, bugs, or feature items. For grouping, define epics. To track more details, add tasks to an issue. -> [!div class="mx-tdCol2BreakAll"] -> |Work item types| Backlog hierarchy | -> |------|---------| -> |![Basic process work item types, conceptual image.](media/about-boards/basic-process-epics-issues-tasks-2.png) | ![Screenshot of Basic process Hierarchical backlog.](media/about-boards/hierarchy-2.png) | - -In each work item form, describe work, assign contributors, track status, and collaborate in the Discussion section. We show you how to add issues, child tasks, and work item details on the web portal. +| Work item types | Backlog hierarchy | +|:------|:---------| +|:::image type="content" source="media/about-boards/basic-process-epics-issues-tasks-2.png" alt-text="Diagram shows Basic process work item types."::: | :::image type="content" source="media/about-boards/hierarchy-2.png" alt-text="Screenshot of Basic process Hierarchical backlog."::: | +In each work item form, describe work, assign contributors, track status, and collaborate in the **Discussion** section. This article describes how to add issues, child tasks, and work item details on the web portal. #### [Scrum process](#tab/scrum-process) -The Scrum process uses various work item types, including product backlog items, tasks, bugs, features, and epics, to plan and track work. Add product backlog items and group them into features if needed. Add child tasks to track more work details. +The Scrum process uses various work item types to plan and track work. Item types include product backlog items, tasks, bugs, features, and epics. Add product backlog items and group them into features if needed. Add child tasks to track more work details. -> [!div class="mx-tdCol2BreakAll"] -> |Work item types| Backlog hierarchy | -> |------|---------| -> |![Scrum work item types, conceptual image.](../work-items/guidance/media/ALM_PT_Scrum_WIT_Artifacts.png) | ![Screenshot of Scrum process product backlog, show parents.](media/about-boards/scrum-hierarchy-simple.png) | +| Work item types | Backlog hierarchy | +|:------|:---------| +|:::image type="content" source="../work-items/guidance/media/ALM_PT_Scrum_WIT_Artifacts.png" alt-text="Diagram shows Scrum process work item types in a hierarchy."::: | :::image type="content" source="media/about-boards/scrum-hierarchy-simple.png" alt-text="Screenshot of Scrum process product backlog, show parents."::: | -In each work item form, describe work, assign contributors, track status, and collaborate in the Discussion section. We show you how to add product backlog items, child tasks, and work item details on the web portal. +In each work item form, describe work, assign contributors, track status, and collaborate in the **Discussion** section. This article describes how to add product backlog items, child tasks, and work item details on the web portal. - -#### [CMMI process](#tab/cmmi-process) +#### [CMMI process](#tab/cmmi-process) The CMMI process uses work item types such as requirements, tasks, bugs, features, and epics to plan and track work. Start by adding requirements and group them into features or epics if needed. Add child tasks to track more work details. -> [!div class="mx-tdCol2BreakAll"] -> |Work item types| Backlog hierarchy | -> |------|---------| -> |![CMMI work item types, conceptual image.](../work-items/guidance/media/ALM_PT_CMMI_WIT_Artifacts.png) | ![Screenshot of CMMI process Requirements backlog, show parents.](media/about-boards/cmmi-hierarchy-simple.png) | +| Work item types | Backlog hierarchy | +|:------|:---------| +|:::image type="content" source="../work-items/guidance/media/ALM_PT_CMMI_WIT_Artifacts.png" alt-text="Diagram shows CMMI process work item types in a hierarchy."::: | :::image type="content" source="media/about-boards/cmmi-hierarchy-simple.png" alt-text="Screenshot of CMMI process Requirements backlog, show parents."::: | -In each work item form, describe work, assign contributors, track status, and collaborate in the Discussion section. We show you how to add user stories, child tasks, and work item details on the web portal. +In each work item form, describe work, assign contributors, track status, and collaborate in the **Discussion** section. This article describes how to add user stories, child tasks, and work item details on the web portal. -* * * +* * * ## Prerequisites ::: moniker range="azure-devops" -- You must have **Basic** access and be a member of the Contributors or Project Administrators group to add work items to a board and use all other board features. -- You must have **Stakeholder** access for a *private* project and be a member of the Contributors or Project Administrators group to view boards, open and modify work items, and add child tasks to a checklist. But, you can't reorder or reparent a backlog item using drag-and-drop, nor update a field on a card. -- You must have **Stakeholder** access for a *public* project and be a member of the Contributors or Project Administrators group to have full access to all Boards features. +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - To add work items to a board and use all other board features: At least [**Basic** access](../../organizations/security/access-levels.md).
- Private project: To view boards, open and modify work items, and add child tasks to a checklist: At least **Stakeholder** access. You can't reorder or reparent a backlog item using drag-and-drop. You can't update a field on a card.
- Public project: For full access to all Boards features: At least **Stakeholder** access. | +| **Permissions** | Member of the **Contributors** or **Project Administrators** group. | ::: moniker-end ::: moniker range="azure-devops-2020" -- You must have **Basic** access and be a member of the Contributors or Project Administrators group to add work items to a board and use all other board features. -- You must have **Stakeholder** access and be a member of the Contributors or Project Administrators group to view boards, open and modify work items, and add child tasks to a checklist. But, you can't reorder or reparent a backlog item using drag-and-drop, nor update a field on a card. - -> [!NOTE] -> To drag-and-drop cards to different, columns you must have [Azure DevOps Server 2020 Update 1](/azure/devops/server/release-notes/azuredevops2020u1#stakeholders-can-move-work-items-across-board-columns). - -::: moniker-end - -::: moniker range="< azure-devops-2020" +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - To add work items to a board and use all other board features: At least [**Basic** access](../../organizations/security/access-levels.md).
- To view boards, open and modify work items, and add child tasks to a checklist: At least **Stakeholder** access. You can't reorder or reparent a backlog item using drag-and-drop. You can't update a field on a card. | +| **Permissions** | Member of the **Contributors** or **Project Administrators** group. | -- You must have **Basic** access and be a member of the Contributors or Project Administrators group to add work items to a board and use all other board features. -- You must have **Stakeholder** access for a *private* project and be a member of the Contributors or Project Administrators group to view boards, open and modify work items, and add child tasks to a checklist. But, you can't reorder or reparent a backlog item using drag-and-drop, nor update a field on a card. -- You must have **Stakeholder** access for a *public* project and be a member of the Contributors or Project Administrators group to have full access to all Boards features. +> [!NOTE] +> To drag-and-drop cards to different columns, have [Azure DevOps Server 2020 Update 1](/azure/devops/server/release-notes/azuredevops2020u1#stakeholders-can-move-work-items-across-board-columns). ::: moniker-end For more information, see [Default permissions and access for Azure Boards](permissions-access-boards.md). -::: moniker range="tfs-2018" -> [!NOTE] -> The images shown in this article correspond to the latest version of Azure Boards. While they may differ from those shown in earlier, on-premises versions of Azure DevOps, they are similar in the functions described unless otherwise noted. -::: moniker-end - -## Open your Kanban board +## Open your board -A Kanban board is provisioned with the addition of each project and each team. You can only create or add Kanban boards to a project by adding another team. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). +A board is provisioned with the addition of each project and each team. You can only create or add boards to a project by adding another team. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). -1. Sign in to your organization (```https://dev.azure.com/{your_organization}```) and go to your project. -2. Select **Boards** > **Boards**. +1. Sign in to your organization (`https://dev.azure.com/{Your_Organization}`) and go to your project. +1. Select **Boards** > **Boards**. :::image type="content" source="media/plan-track-work/open-boards.png" alt-text="Screenshot showing two selections highlighted with red boxes, to open boards."::: -3. Select a board from the **All Team Boards** dropdown menu. +1. Select a board from the **All Team Boards** dropdown menu. :::image type="content" source="media/plan-track-work/select-from-all-team-boards-dropdown-menu.png" alt-text="Screenshot showing All Team Boards to choose from, listed in the dropdown menu."::: ## Add work items to your board -Work items on your board are automatically assigned the default **Area Path** and **Iteration Path** assigned to the team. For more information, see [Configure team settings](../../organizations/settings/manage-teams.md). +Work items on your board are automatically assigned the default **Area Path** and **Iteration Path** assigned to the team. For more information, see [Manage and configure team tools](../../organizations/settings/manage-teams.md). #### [Agile process](#tab/agile-process) -1. From the Stories board, choose **New item** and the stories you want to track. +1. From the Stories board, choose **New item** and the stories you want to track. - > [!div class="mx-imgBorder"] - > ![Add new item, Kanban board, Agile process.](media/plan-track-work/new-user-story-kanban-board.png) + :::image type="content" source="media/plan-track-work/new-user-story-kanban-board.png" alt-text="Screenshot shows the option to add a New item option for the Agile process."::: -1. Enter return and the system assigns a work item ID to the user story. +1. Select **Enter**. The system assigns a work item ID to the user story. - > [!div class="mx-imgBorder"] - > ![Added item, Agile process.](media/plan-track-work/users-stories-board-added-item.png) + :::image type="content" source="media/plan-track-work/users-stories-board-added-item.png" alt-text="Screenshot shows the added item in the Agile process."::: 1. Add as many user stories as you need. > [!TIP] -> To quickly add features and child user stories, choose **Features** from the board selector. ->:::image type="content" source="media/plan-track-work/choose-features-board.png" alt-text="Screenshot to Open the features board, Agile process."::: +> To quickly add features and child user stories, choose **Features** from the board selector. +> +> :::image type="content" source="media/plan-track-work/choose-features-board.png" alt-text="Screenshot to Open the features board in the Agile process."::: -#### [Basic process](#tab/basic-process) +#### [Basic process](#tab/basic-process) -1. From the Issues board, choose **New item** and add the issues you want to track. +1. From the Issues board, choose **New item** and add the issues you want to track. - > [!div class="mx-imgBorder"] - > ![Add new item, Basic process.](media/track-issues/issues-board-new-item.png) + :::image type="content" source="media/track-issues/issues-board-new-item.png" alt-text="Screenshot shows the option to add a New item for the Basic process."::: -2. Enter return and the system assigns a work item ID to the issue. +1. Enter return and the system assigns a work item ID to the issue. - > [!div class="mx-imgBorder"] - > ![Added item, Basic process.](media/track-issues/issues-board-added-item.png) + :::image type="content" source="media/track-issues/issues-board-added-item.png" alt-text="Screenshot shows the added item in the Basic process."::: -3. Add as many issues as you need. +1. Add as many issues as you need. > [!TIP] -> The Epics Kanban board is the best tool for quickly adding epics and issues that are children of those epics. To open the Epics board from the Issues board, choose **Epics** from the board selector. -> :::image type="content" source="media/track-issues/choose-epics-board.png" alt-text="Screenshot to Open the Epics board, Basic process."::: +> The Epics board is the best tool for quickly adding epics and issues that are children of those epics. To open the Epics board from the Issues board, choose **Epics** from the board selector. +> +> :::image type="content" source="media/track-issues/choose-epics-board.png" alt-text="Screenshot to Open the Epics board, Basic process."::: #### [Scrum process](#tab/scrum-process) -1. From the Backlog items board, choose **New item** and add the stories you want to track. +1. From the Backlog items board, choose **New item** and add the stories you want to track. - > [!div class="mx-imgBorder"] - > ![Add new item, Scrum process.](media/plan-track-work/new-scrum-item-kanban-board.png) + :::image type="content" source="media/plan-track-work/new-scrum-item-kanban-board.png" alt-text="Screenshot shows the option to add a New item for the Scrum process."::: -1. Enter return and the system assigns a work item ID to the user story. +1. Enter return and the system assigns a work item ID to the user story. - > [!div class="mx-imgBorder"] - > ![Added item, Scrum process.](media/plan-track-work/board-added-item-scrum.png) + :::image type="content" source="media/plan-track-work/board-added-item-scrum.png" alt-text="Screenshot shows the added item in the Scrum process."::: 1. Add as many backlog items as you need. > [!TIP] -> The Features Kanban board is the best tool for quickly adding features and product backlog items that are children of those features. To open the Features board from the Backlog items board, choose **Features** from the board selector. +> The Features board is the best tool for quickly adding features and product backlog items that are children of those features. To open the Features board from the Backlog items board, choose **Features** from the board selector. +> >:::image type="content" source="media/plan-track-work/choose-features-board-scrum.png" alt-text="Screenshot to Open the Features board, Scrum process."::: The default Scrum process configuration doesn't enable the Epic backlog level for a team. To enable it, see [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md). #### [CMMI process](#tab/cmmi-process) -1. From the Requirements board, choose **New item** and add the stories you want to track. +1. From the Requirements board, choose **New item** and add the stories you want to track. - > [!div class="mx-imgBorder"] - > ![Add new item, CMMI process.](media/plan-track-work/new-user-story-kanban-board-cmmi.png) + :::image type="content" source="media/plan-track-work/new-user-story-kanban-board-cmmi.png" alt-text="Screenshot shows the option to add a New item for the CMMI process."::: -1. Enter return and the system assigns a work item ID to the user story. +1. Enter return and the system assigns a work item ID to the user story. - > [!div class="mx-imgBorder"] - > ![Added item, CMMI process.](media/plan-track-work/board-added-item-cmmi.png) + :::image type="content" source="media/plan-track-work/board-added-item-cmmi.png" alt-text="Screenshot shows the added item in the CMMI process."::: 1. Add as many requirements as you need. > [!TIP] -> The Features Kanban board is the best tool for quickly adding features and requirements that are children of those features. To open the Features board from the Requirements board, choose **Features** from the board selector. +> The Features board is the best tool for quickly adding features and requirements that are children of those features. To open the Features board from the Requirements board, choose **Features** from the board selector. +> >:::image type="content" source="media/plan-track-work/choose-features-board-requirements.png" alt-text="Screenshot to Open the Features board, CMMI process."::: * * * ## Add details to a board item -Select the issue or user story title to open it. Change one or more field values, add a description, or make a note in the **Discussion** section. You can also choose the ![attachments icon](../media/icons/icon-attachments-tab-wi.png) **Attachments** tab and drag-and-drop a file to share the file with others. +To open an issue or user story, select its title. Change one or more field values, add a description, or make a note in the **Discussion** section. You can also choose the :::image type="icon" source="../media/icons/icon-attachments-tab-wi.png"::: **Attachments** tab and drag-and-drop a file to share the file with others. -#### [Agile process](#tab/agile-process) +#### [Agile process](#tab/agile-process) -For example, here we assign the story to Raisa Pokrovskaya and add a discussion note, at-mentioning Raisa. +For example, assign the story to Raisa Pokrovskaya and add a discussion note, at-mentioning Raisa. -> [!div class="mx-imgBorder"] -> ![Screenshot of User Story work item form.](media/plan-track-work/user-story-form-add-details.png) +:::image type="content" source="media/plan-track-work/user-story-form-add-details.png" alt-text="Screenshot of User Story work item form."::: -Choose **Save & Close** when you're done. +When you're done, select **Save & Close**. #### [Basic process](#tab/basic-process) -For example, here we assign the issue to Raisa Pokrovskaya and add a discussion note, at-mentioning Raisa. +For example, assign the issue to Raisa Pokrovskaya and add a discussion note, at-mentioning Raisa. -> [!div class="mx-imgBorder"] -> ![Screenshot of Issues work item form, add details. ](media/track-issues/issue-form-add-details.png) +:::image type="content" source="media/track-issues/issue-form-add-details.png" alt-text="Screenshot of Issues work item form, add details."::: -Choose **Save & Close** when you're done. +When you're done, select **Save & Close**. -#### [Scrum process](#tab/scrum-process) +#### [Scrum process](#tab/scrum-process) -For example, here we assign the product backlog item to Christie Church and set an Effort level of 8. +For example, assign the product backlog item to Christie Church and set an Effort level of 8. -> [!div class="mx-imgBorder"] -> ![Screenshot of Product Backlog Item form.](../backlogs/media/create-backlog/pbi-form.png) +:::image type="content" source="../backlogs/media/create-backlog/pbi-form.png" alt-text="Screenshot of Product Backlog Item form."::: -Choose **Save & Close** when you're done. +When you're done, select **Save & Close**. -#### [CMMI process](#tab/cmmi-process) +#### [CMMI process](#tab/cmmi-process) -For example, here we assign the product backlog item to Jamal Hartnett and set Size to 8. +For example, assign the requirement to Jamal Hartnett and set Size to 8. -> [!div class="mx-imgBorder"] -> ![Screenshot of Requirements work item form.](../work-items/guidance/media/cmmi-requirement-form.png) +:::image type="content" source="../work-items/guidance/media/cmmi-requirement-form.png" alt-text="Screenshot of Requirements work item form."::: -Choose **Save & Close** when you're done. +When you're done, select **Save & Close**. #### CMMI-specific field descriptions -[!INCLUDE [temp](../includes/section-cmmi-field-descriptions.md)] +[!INCLUDE [cmmi field descriptions](../includes/section-cmmi-field-descriptions.md)] * * * - ### Field descriptions -[!INCLUDE [temp](../includes/section-basic-field-descriptions.md)] +[!INCLUDE [basic field descriptions](../includes/section-basic-field-descriptions.md)] ## Update work status -The State field tracks the status of a work item. With the Kanban board, you can quickly update the status of backlog items by dragging and dropping them to a different column. +The State field tracks the status of a work item. With the board, you can quickly update the status of backlog items by dragging and dropping them to a different column. -#### [Agile process](#tab/agile-process) +#### [Agile process](#tab/agile-process) -As work begins, drag the user story card from the **Backlog** column to the **Active** column. Once work is ready for review, move it to the **Resolved** column. After it's reviewed and accepted, move it to the **Closed** column. +As work begins, drag the user story card from the **Backlog** column to the **Active** column. When work is ready for review, move it to the **Resolved** column. After a team member reviews and accepts it, move it to the **Closed** column. -> [!div class="mx-imgBorder"] -> ![Screenshot showing updating status on Kanban board, Agile process.](media/plan-track-work/update-status.png) +:::image type="content" source="media/plan-track-work/update-status.png" alt-text="Screenshot showing updating status on board, Agile process."::: -#### [Basic process](#tab/basic-process) +#### [Basic process](#tab/basic-process) -As work begins, drag the issue from the **To Do** column to the **Doing** column. Once it's completed, move it to the **Done** column. +As work begins, drag the issue from the **To Do** column to the **Doing** column. When a team member completes it, move it to the **Done** column. -> [!div class="mx-imgBorder"] -> ![Screenshot showing updating status on Kanban board, Basic process.](media/track-issues/update-status.png) +:::image type="content" source="media/track-issues/update-status.png" alt-text="Screenshot showing updating status on board, Basic process."::: #### [Scrum process](#tab/scrum-process) -Once a backlog item is approved to start work, drag the backlog item card from the **New** column to the **Approved** column. When work begins, drag the card to the **Committed** column. Once work has completed, move it to the **Done** column. +After a backlog item is approved to start work, drag the backlog item card from the **New** column to the **Approved** column. When work begins, drag the card to the **Committed** column. After work completes, move it to the **Done** column. -> [!div class="mx-imgBorder"] -> ![Screenshot showing updating status on Kanban board, Scrum process.](media/plan-track-work/update-status-scrum.png) +:::image type="content" source="media/plan-track-work/update-status-scrum.png" alt-text="Screenshot showing updating status on board, Scrum process."::: #### [CMMI process](#tab/cmmi-process) -As work begins, drag the requirement card from the **Backlog** column to the **Active** column. Once work is ready for review, move it to the **Resolved** column. After it's reviewed and accepted, move it to the **Closed** column. +As work begins, drag the requirement card from the **Backlog** column to the **Active** column. When work is ready for review, move it to the **Resolved** column. After a team member reviews and accepts it, move it to the **Closed** column. -> [!div class="mx-imgBorder"] -> ![Screenshot showing updating status on Kanban board, CMMI process.](media/plan-track-work/update-status-cmmi.png) +:::image type="content" source="media/plan-track-work/update-status-cmmi.png" alt-text="Screenshot showing updating status on board, CMMI process."::: * * * > [!TIP] -> To add or rename columns as needed, see [Customize your board](../configure-customize.md). +> To add or rename columns as needed, see [About configuring and customizing Azure Boards](../configure-customize.md). -## Add tasks +## Add tasks -Task checklists provide a quick and easy way to track elements of work that are important to support completing a backlog item. Also, you can assign individual tasks to different team members. +Task checklists provide a quick and easy way to track elements of work that are important to complete a backlog item. Also, you can assign individual tasks to different team members. -> [!TIP] -> Tasks that you create from the Kanban board are automatically assigned the **Area Path** and **Iteration Path** of their parent work item and show up on your sprint taskboard. +> [!TIP] +> Tasks that you create from the board are automatically assigned the **Area Path** and **Iteration Path** of their parent work item and show up on your sprint taskboard. -Tasks that you create from the [sprint backlog](../sprints/assign-work-sprint.md) or [taskboard](../sprints/task-board.md) show up within tasks checklists on the Kanban board. +Tasks that you create from the [sprint backlog](../sprints/assign-work-sprint.md) or [taskboard](../sprints/task-board.md) show up in tasks checklists on the board. -#### [Agile process](#tab/agile-process) +#### [Agile process](#tab/agile-process) -1. Select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the story and select ![plus icon](../../media/icons/green_plus_icon.png) **Add Task**. +1. Select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the story and select :::image type="icon" source="../../media/icons/green_plus_icon.png"::: **Add Task**. - > [!div class="mx-imgBorder"] - > ![Choose Add Task from the User Story card menu, Agile process.](media/plan-track-work/add-child-task.png) + :::image type="content" source="media/plan-track-work/add-child-task.png" alt-text="Screenshot shows choosing Add Task from the User Story card menu in the Agile process."::: - Enter a title for the task and select **Enter** when you're done. +1. Enter a title for the task and select **Enter**. - > [!div class="mx-imgBorder"] - > ![Add first task, Agile process. ](media/plan-track-work/prep-images-task.png) + :::image type="content" source="media/plan-track-work/prep-images-task.png" alt-text="Screenshot shows adding a task in the Agile process."::: -2. If you have many tasks to add, keep entering your task titles and type Enter. +1. If you have many tasks to add, keep entering your task titles and select **Enter**. - > [!div class="mx-imgBorder"] - > ![Several tasks added, Agile process.](media/plan-track-work/add-several-tasks.png) + :::image type="content" source="media/plan-track-work/add-several-tasks.png" alt-text="Screenshot shows a user story with several tasks added in the Agile process."::: -3. You can mark a task as done, expand or collapse the task checklist, or reorder and reparent tasks. +1. You can mark a task as done, expand or collapse the task checklist, reorder, and reparent tasks. - > [!div class="mx-tdCol2BreakAll"] - > |Mark a task as done |Reorder and reparent tasks | Expand or collapse the checklist| - > |------------------|--------------|--------------| - > |To mark a task as complete, check the task checkbox. The task State changes to **Done**.
![Mark task as done](media/plan-track-work/mark-tasks-as-done.png) |To reorder a task, drag it within the checklist. To reparent a the task, drag it to another issue on the board.
![Drag tasks to reorder them within the list](media/plan-track-work/reorder-task.png) |To expand or collapse a task checklist, simply choose the task annotation.
![Collapse task checklist](media/plan-track-work/collapse-task-list.png) | + | Mark a task as done | Reorder and reparent tasks | Expand or collapse the checklist | + |:------------------|:--------------|:--------------| + | To mark a task as complete, select the task checkbox. The task State changes to **Done**.
:::image type="content" source="media/plan-track-work/mark-tasks-as-done.png" alt-text="Screenshot shows tasks marked as done under a user story in the Agile process."::: | To reorder a task, drag it in the checklist. To reparent a the task, drag it to another issue on the board.
:::image type="content" source="media/plan-track-work/reorder-task.png" alt-text="Screenshot shows how to drag a task to a new location in the Agile process."::: | To expand or collapse a task checklist, choose the task annotation.
:::image type="content" source="media/plan-track-work/collapse-task-list.png" alt-text="Screenshot shows a collapsed task list in the Agile process which you can select to expand the list."::: | -#### [Basic process](#tab/basic-process) +#### [Basic process](#tab/basic-process) -1. Select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the issue and select ![plus icon](../../media/icons/green_plus_icon.png) **Add Task**. +1. Select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the issue and select :::image type="icon" source="../../media/icons/green_plus_icon.png"::: **Add Task**. - > [!div class="mx-imgBorder"] - > ![Choose Add Task from Issues card menu, Basic process.](media/track-issues/add-tasks.png) + :::image type="content" source="media/track-issues/add-tasks.png" alt-text="Screenshot shows choosing Add Task from the User Story card menu in the Basic process."::: - Enter a title for the task and type Enter when you're done. +1. Enter a title for the task and select **Enter**. - > [!div class="mx-imgBorder"] - > ![Add first task, Basic process.](media/track-issues/enter-first-task.png) + :::image type="content" source="media/track-issues/enter-first-task.png" alt-text="Screenshot shows adding a task in the Basic process."::: -2. If you have various tasks to add, keep entering your task titles and type Enter. +1. If you have various tasks to add, keep entering your task titles and type Enter. - > [!div class="mx-imgBorder"] - > ![Several tasks added, Basic process.](media/track-issues/add-several-tasks.png) + :::image type="content" source="media/track-issues/add-several-tasks.png" alt-text="Screenshot shows a user story with several tasks added in the Basic process."::: -3. You can mark a task as done, expand or collapse the task checklist, or reorder and reparent tasks. +1. You can mark a task as done, expand or collapse the task checklist, reorder, and reparent tasks. - > [!div class="mx-tdCol2BreakAll"] - > |Mark a task as done |Reorder and reparent tasks | Expand or collapse the checklist| - > |------------------|--------------|--------------| - > |To mark a task as complete, check the task checkbox. The task State changes to **Done**.
![Mark task as done, Basic process.](media/track-issues/mark-tasks-as-done.png) |To reorder a task, drag it within the checklist. To reparent a the task, drag it to another issue on the board.
![Drag tasks to reorder them within the list, Basic process.](media/track-issues/reorder-task.png) |To expand or collapse a task checklist, simply choose the task annotation.
![Collapse task checklist, Basic process.](media/track-issues/collapse-task-list.png) | + | Mark a task as done | Reorder and reparent tasks | Expand or collapse the checklist | + |:------------------|:--------------|:--------------| + | To mark a task as complete, select the task checkbox. The task State changes to **Done**.
:::image type="content" source="media/track-issues/mark-tasks-as-done.png" alt-text="Screenshot shows tasks marked as done under a user story in the Basic process."::: | To reorder a task, drag it in the checklist. To reparent a the task, drag it to another issue on the board.
:::image type="content" source="media/track-issues/reorder-task.png" alt-text="Screenshot shows how to drag a task to a new location in the Basic process."::: | To expand or collapse a task checklist, choose the task annotation.
:::image type="content" source="media/track-issues/collapse-task-list.png" alt-text="Screenshot shows a collapsed task list in the Basic process which you can select to expand the list."::: | -#### [Scrum process](#tab/scrum-process) +#### [Scrum process](#tab/scrum-process) -1. To start adding tasks, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the story and select the ![plus icon](../../media/icons/green_plus_icon.png) **Add Task** option. +1. To start adding tasks, select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the story and select the :::image type="icon" source="../../media/icons/green_plus_icon.png"::: **Add Task** option. - > [!div class="mx-imgBorder"] - > ![Choose Add Task from Product backlog item card menu, Scrum process.](media/plan-track-work/add-child-task.png) + :::image type="content" source="media/plan-track-work/add-child-task.png" alt-text="Screenshot shows choosing Add Task from the User Story card menu in the Scrum process."::: - Enter a title for the task and type Enter when you're done. +1. Enter a title for the task and type Enter when you're done. - > [!div class="mx-imgBorder"] - > ![Add first task, Scrum process.](media/plan-track-work/prep-images-task.png) + :::image type="content" source="media/plan-track-work/prep-images-task.png" alt-text="Screenshot shows adding a task in the Scrum process."::: -1. If you have many tasks to add, just keep entering your task titles and type Enter. +1. If you have many tasks to add, just keep entering your task titles and type Enter. - > [!div class="mx-imgBorder"] - > ![Several tasks added, Scrum process.](media/plan-track-work/add-several-tasks.png) + :::image type="content" source="media/plan-track-work/add-several-tasks.png" alt-text="Screenshot shows a user story with several tasks added in the Scrum process."::: -2. You can mark a task as done, expand or collapse the task checklist, or reorder and reparent tasks. +1. You can mark a task as done, expand or collapse the task checklist, or reorder and reparent tasks. - > [!div class="mx-tdCol2BreakAll"] - > |Mark a task as done |Reorder and reparent tasks | Expand or collapse the checklist| - > |------------------|--------------|--------------| - > |To mark a task as complete, check the task checkbox. The task State changes to **Done**.
![Mark task as done, Scrum process.](media/plan-track-work/mark-tasks-as-done.png) |To reorder a task, drag it within the checklist. To reparent a the task, drag it to another issue on the board.
![Drag tasks to reorder them within the list, Scrum process.](media/plan-track-work/reorder-task.png) |To expand or collapse a task checklist, simply choose the task annotation.
![Collapse task checklist, Scrum process.](media/plan-track-work/collapse-task-list.png) | + | Mark a task as done | Reorder and reparent tasks | Expand or collapse the checklist | + |:------------------|:--------------|:--------------| + | To mark a task as complete, select the task checkbox. The task State changes to **Done**.
:::image type="content" source="media/plan-track-work/mark-tasks-as-done.png" alt-text="Screenshot shows tasks marked as done under a user story in the Scrum process."::: | To reorder a task, drag it in the checklist. To reparent a the task, drag it to another issue on the board.
:::image type="content" source="media/plan-track-work/reorder-task.png" alt-text="Screenshot shows how to drag a task to a new location in the Scrum process."::: | To expand or collapse a task checklist, choose the task annotation.
:::image type="content" source="media/plan-track-work/collapse-task-list.png" alt-text="Screenshot shows a collapsed task list in the Scrum process which you can select to expand the list."::: | -#### [CMMI process](#tab/cmmi-process) +#### [CMMI process](#tab/cmmi-process) -1. To start adding tasks, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the story and select the ![plus icon](../../media/icons/green_plus_icon.png) **Add Task** option. +1. To start adding tasks, select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the story and select the :::image type="icon" source="../../media/icons/green_plus_icon.png"::: **Add Task** option. - > [!div class="mx-imgBorder"] - > ![Choose Add Task from Requirements card menu, CMMI process.](media/plan-track-work/add-child-task.png) + :::image type="content" source="media/plan-track-work/add-child-task.png" alt-text="Screenshot shows choosing Add Task from the User Story card menu in the CMMI process."::: - Enter a title for the task and type Enter when you're done. +1. Enter a title for the task and type Enter when you're done. - > [!div class="mx-imgBorder"] - > ![Add first task, CMMI process.](media/plan-track-work/prep-images-task.png) + :::image type="content" source="media/plan-track-work/prep-images-task.png" alt-text="Screenshot shows adding a task in the CMMI process."::: -1. If you have various tasks to add, just keep entering your task titles and type Enter. +1. If you have various tasks to add, just keep entering your task titles and type Enter. - > [!div class="mx-imgBorder"] - > ![Several tasks added, CMMI process.](media/plan-track-work/add-several-tasks.png) + :::image type="content" source="media/plan-track-work/add-several-tasks.png" alt-text="Screenshot shows a user story with several tasks added in the CMMI process."::: -2. You can mark a task as done, expand or collapse the task checklist, or reorder and reparent tasks. +1. You can mark a task as done, expand or collapse the task checklist, reorder, and reparent tasks. - > [!div class="mx-tdCol2BreakAll"] - > |Mark a task as done |Reorder and reparent tasks | Expand or collapse the checklist| - > |------------------|--------------|--------------| - > |To mark a task as complete, check the task checkbox. The task State changes to **Done**.
![Mark task as done, CMMI process.](media/plan-track-work/mark-tasks-as-done.png) |To reorder a task, drag it within the checklist. To reparent a the task, drag it to another issue on the board.
![Drag tasks to reorder them within the list, CMMI process.](media/plan-track-work/reorder-task.png) |To expand or collapse a task checklist, simply choose the task annotation.
![Collapse task checklist, CMMI process.](media/plan-track-work/collapse-task-list.png) | + | Mark a task as done | Reorder and reparent tasks | Expand or collapse the checklist | + |:------------------|:--------------|:--------------| + |To mark a task as complete, select the task checkbox. The task State changes to **Done**.
:::image type="content" source="media/plan-track-work/mark-tasks-as-done.png" alt-text="Screenshot shows tasks marked as done under a user story in the CMMI process."::: | To reorder a task, drag it in the checklist. To reparent a the task, drag it to another issue on the board.
:::image type="content" source="media/plan-track-work/reorder-task.png" alt-text="Screenshot shows how to drag a task to a new location in the CMMI process."::: | To expand or collapse a task checklist, choose the task annotation.
:::image type="content" source="media/plan-track-work/collapse-task-list.png" alt-text="Screenshot shows a collapsed task list in the CMMI process which you can select to expand the list."::: | * * * ## Add details to a task -If you have details you want to add about a task, choose the title, to open it. Change one or more field values, add a description, or make a note in the **Discussion** section. Choose **Save & Close** when you're done. +If you have details you want to add about a task, select the title to open it. Change one or more field values, add a description, or make a note in the **Discussion** section. Choose **Save & Close**. -#### [Agile process](#tab/agile-process) +#### [Agile process](#tab/agile-process) -Here we assign the task to Christie Church. +This example assigns the task to Christie Church. -> [!div class="mx-imgBorder"] -> ![Screenshot of Task work item form, Agile process.](media/plan-track-work/task-form.png) +:::image type="content" source="media/plan-track-work/task-form.png" alt-text="Screenshot of Task work item form, Agile process."::: -#### [Basic process](#tab/basic-process) +#### [Basic process](#tab/basic-process) -Here we assign the task to Jamal. +This example assigns the task to Jamal. -> [!div class="mx-imgBorder"] -> ![Screenshot of Task work item form, Basic process.](media/track-issues/basic-process-task-form.png) +:::image type="content" source="media/track-issues/basic-process-task-form.png" alt-text="Screenshot of Task work item form, Basic process."::: -#### [Scrum process](#tab/scrum-process) - -Here we assign the task to Jamal. +#### [Scrum process](#tab/scrum-process) -> [!div class="mx-imgBorder"] -> ![Screenshot of Task work item form, Scrum process.](../work-items/guidance/media/scrum-task-form.png) +This example assigns the task to Jamal. +:::image type="content" source="../work-items/guidance/media/scrum-task-form.png" alt-text="Screenshot of Task work item form, Scrum process."::: -#### [CMMI process](#tab/cmmi-process) +#### [CMMI process](#tab/cmmi-process) -Here we assign the task to Jamal. +This example assigns the task to Jamal. -> [!div class="mx-imgBorder"] -> ![Screenshot of Task work item form, CMMI process.](../work-items/guidance/media/cmmi-task-form.png) +:::image type="content" source="../work-items/guidance/media/cmmi-task-form.png" alt-text="Screenshot of Task work item form, CMMI process."::: * * * - ### Field descriptions -In addition to the fields you can define for a backlog item—user story, issue, product backlog item, or requirement—you can specify the following fields for a task to support capacity and time tracking. +You can assign these fields for a backlog item: user story, issue, product backlog item, and requirement. You can specify the following fields for a task to support capacity and time tracking. -> [!NOTE] -> There are no inherent time units associated with this field even though the taskboard always shows "h" for hours in relationship to Remaining Work. You can specify work in any unit of measurement your team chooses. +> [!NOTE] +> There are no inherent time units associated with this field even though the taskboard always shows "h" for hours in relationship to Remaining Work. You can specify work in any unit of measurement your team chooses. :::row::: :::column span=""::: @@ -448,10 +396,10 @@ In addition to the fields you can define for a backlog item—user story, is --- :::row::: :::column span=""::: - [Activity](../queries/query-numeric.md) + [Activity](../queries/query-numeric.md) :::column-end::: :::column span="3"::: - The type of activity that's required to do a task.For more information about how this field is used, see [Capacity planning](../sprints/set-capacity.md). Allowed values are: + The type of activity that's required to do a task. For more information, see [Determine and set sprint capacity](../sprints/set-capacity.md). Allowed values are: - **Deployment** - **Design** - **Development** @@ -465,7 +413,7 @@ In addition to the fields you can define for a backlog item—user story, is [Discipline](../queries/query-numeric.md) (CMMI process) :::column-end::: :::column span="3"::: - The type of activity that's required to do a task.For more information about how this field is used, see [Capacity planning](../sprints/set-capacity.md). Allowed values are: + The type of activity that's required to do a task. For more information, see [Determine and set sprint capacity](../sprints/set-capacity.md). Allowed values are: - **Analysis** - **Development** - **Test** @@ -478,7 +426,7 @@ In addition to the fields you can define for a backlog item—user story, is [Original Estimate](../queries/query-numeric.md) :::column-end::: :::column span="3"::: - The amount of estimated work required to complete a task. Typically, this field doesn't change after it's assigned. + The amount of estimated work required to complete a task. Typically, this field doesn't change after you assign the task. :::column-end::: :::row-end::: :::row::: @@ -486,8 +434,8 @@ In addition to the fields you can define for a backlog item—user story, is [Remaining Work](../queries/query-numeric.md) :::column-end::: :::column span="3"::: - The amount of work that remains to finish a task. You can specify work in hours or in days. As work progresses, update this field. It's used to calculate [capacity charts](../sprints/set-capacity.md) and the [sprint burndown chart](../../report/dashboards/configure-sprint-burndown.md). - If you divide a task into subtasks, specify Remaining Work for the subtasks only. + The amount of work that remains to finish a task. You can specify work in hours or in days. As work progresses, update this field. It's used to calculate [capacity charts](../sprints/set-capacity.md) and the [sprint burndown chart](../../report/dashboards/configure-sprint-burndown.md). + If you divide a task into subtasks, specify Remaining Work for the subtasks only. :::column-end::: :::row-end::: :::row::: @@ -510,14 +458,12 @@ In addition to the fields you can define for a backlog item—user story, is :::column-end::: :::row-end::: -[!INCLUDE [temp](../includes/discussion-tip.md)] +[!INCLUDE [discussion comments](../includes/discussion-tip-azure-devops.md)] + +## Related articles -## Next steps - > [!div class="nextstepaction"] > [Customize your board](../configure-customize.md) -## Related articles - -- [Azure Boards FAQs](../faqs.yml) -- [Add tags to issues or tasks](../queries/add-tags-to-work-items.md) +- [Review Azure Boards FAQs](../faqs.yml) +- [Add tags to issues or tasks](../queries/add-tags-to-work-items.md) diff --git a/docs/boards/get-started/sign-up-invite-teammates.md b/docs/boards/get-started/sign-up-invite-teammates.md index 5cb53d89520..261b1835f15 100644 --- a/docs/boards/get-started/sign-up-invite-teammates.md +++ b/docs/boards/get-started/sign-up-invite-teammates.md @@ -8,7 +8,7 @@ ms.topic: quickstart ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 03/22/2023 +ms.date: 03/13/2025 --- # Sign up for Azure Boards @@ -21,36 +21,25 @@ To sign up for all Azure DevOps Services, see [Sign up, sign in to Azure DevOps] ## Prerequisites -You must have the latest version of one of the following web browsers: Microsoft Edge, Internet Explorer, Safari (Mac), Firefox, or Chrome. +| Category | Requirements | +|--------------|-------------| +|**Browser**| Latest version of one of the following web browsers: Microsoft Edge, Internet Explorer, Safari (Mac), Firefox, or Chrome.| -## Sign-up +## Sign up -1. From your web browser, open the [Azure Boards](https://azure.microsoft.com/services/devops/boards/?nav=min) sign-up page. +Sign up for Azure Boards with either a Microsoft account or GitHub account. - > [!div class="mx-imgBorder"] - > ![Create new project dialog, start free.](media/acquisition/start-free-azure-boards.png) - -1. Select which account you want to use. - - - **Start free**: Choose this option when: - - You have a Microsoft account and plan to sign in using your account email address, phone number, or Skype ID. If you're a Visual Studio subscriber and you get Azure DevOps as a benefit, use the Microsoft account associated with your subscription. - - You want to sign up using a general email address you want to use. A project gets created based on your account name, but you can change the project name later. - > [!TIP] - > - You can sign up with any valid email address. Signing up for Azure Boards enables your email address as a Microsoft account. - > - An organization and project get created based on your account name. Sign in to your organization at any time by entering `https://dev.azure.com/{yourorganization}` in your web portal. You can [change the organization or project settings](#change-settings) at any time. - - **Start free with GitHub**: Choose this option if you have an existing GitHub account. - > [!IMPORTANT] - > If your GitHub email address is associated with an Azure AD-backed organization in Azure DevOps, you can't sign in with your GitHub account, rather you must sign in with your Azure AD account. - - If you've already signed up or have an organization set up to use Azure Boards, choose the **Sign in** link. +# [Microsoft account](#tab/microsoft-account) -1. Continue through the flow to finish signing up. - - When you're done, you have an organization and a project that correspond to your account name. Optionally, you can [change the name or other settings for your organization or project](#optional-change-your-organization-or-project-settings). - - Sign in to your organization at any time (```https://dev.azure.com/{yourorganization}```). +[!INCLUDE [sign-up-msft-account](../../includes/sign-up-msft-account.md)] - +# [GitHub account](#tab/github-account) + +[!INCLUDE [sign-in-github-account](../../includes/sign-in-github-account.md)] + +--- + + ### Optional: Change your organization or project settings @@ -125,7 +114,7 @@ For more information about changing your project settings, see the following art - **Project name**: Can't contain special characters (such as /: \ ~ & % ; @ ' " ? < > | # $ * } { , + = [ ]), can't begin with an underscore, can't begin or end with a period, and must be 64 characters or less. - **Visibility**: Choose **Public** if you want to create an open-source project. Otherwise, choose **Private**, so only people who you give access to can view your project. -1. Your next step is to start using your Kanban board to [track issues and tasks](plan-track-work.md), or [invite other users](#invite-others) to collaborate with your project. +2. Your next step is to start using your board to [track issues and tasks](plan-track-work.md), or [invite other users](#invite-others) to collaborate with your project. > [!NOTE] @@ -135,7 +124,7 @@ For more information about changing your project settings, see the following art ## Sign up with a personal Microsoft account -If you have a Microsoft account or Azure Active Directory organizational account, follow these steps to sign up for Azure Boards. +If you have a Microsoft account or Microsoft Entra organizational account, follow these steps to sign up for Azure Boards. 1. Enter your email address, phone number, or Skype ID for your Microsoft account. If you're a Visual Studio subscriber and you get Azure DevOps as a benefit, use the Microsoft account associated with your subscription. Select **Next**. @@ -167,7 +156,7 @@ If you have a Microsoft account or Azure Active Directory organizational account 1. To complete your sign-up process, go to [create a project](#create-project). - + ## Sign up with a GitHub account @@ -175,7 +164,7 @@ If you have a Microsoft account or Azure Active Directory organizational account If you have a GitHub account, follow these steps to sign up for Azure Boards. > [!IMPORTANT] -> If your GitHub email address is associated with an Azure AD-backed organization in Azure DevOps, you can't sign in with your GitHub account, rather you must sign in with your Azure AD account. +> If your GitHub email address is associated with an organization in Azure DevOps backed by Microsoft Entra ID, you can't sign in with your GitHub account, rather you must sign in with your Microsoft Entra account. 1. From the [Azure Boards](https://azure.microsoft.com/services/devops/boards/) sign-up page, choose **Start Boards free with GitHub**. @@ -190,9 +179,7 @@ If you have a GitHub account, follow these steps to sign up for Azure Boards. ![Authorize Microsoft](../../media/authorize-Microsoft-corp.png) - For more information about GitHub authentication, see [FAQs](../../organizations/security/faq-github-authentication.yml). - -1. Choose **Continue**. +2. Choose **Continue**. ![Choose Continue to sign up for Azure DevOps](../../media/sign-up-azure-devops.png) @@ -204,9 +191,9 @@ If you have a GitHub account, follow these steps to sign up for Azure Boards. You can change the organization name as indicated in [Change organization or project settings](#change-settings) later in this article. -1. To complete your sign-up process, go to [create a project](#create-project). +3. To complete your sign-up process, go to [create a project](#create-project). - + ## Create a project @@ -220,10 +207,10 @@ If you signed up for Azure DevOps with an existing Microsoft account or GitHub i - **Project name**: Can't contain special characters (such as / : \ ~ & % ; @ ' " ? < > | # $ * } { , + = [ ]), can't begin with an underscore, can't begin or end with a period, and must be 64 characters or less. - **Visibility**: Choose **Public** if you want to create an open-source project. Otherwise, choose **Private**, so only people who you give access to can view your project. -2. Your Kanban board automatically appears. You're now set to start [tracking issues, tasks, and features](plan-track-work.md), or [invite other users](#invite-others) to collaborate with your project. +2. Your board automatically appears. You're now set to start [tracking issues, tasks, and features](plan-track-work.md), or [invite other users](#invite-others) to collaborate with your project. > [!div class="mx-imgBorder"] - > ![Kanban board](media/track-issues/issues-board-new-item.png) + > ![board](media/track-issues/issues-board-new-item.png) @@ -250,7 +237,7 @@ Your first project is automatically created using the Basic process and a Git re 3. Choose **Create** to complete the action. - + ## Invite team members to your project @@ -276,9 +263,9 @@ You can add and invite others to work on your project by adding their email addr - **Project Administrators**: Assign to users who will configure project resources. > [!NOTE] - > Add email addresses for [personal Microsoft accounts](https://account.microsoft.com/account) and IDs for GitHub accounts unless you plan to use [Azure Active Directory (Azure AD)](/azure/active-directory/fundamentals/active-directory-whatis) to authenticate users and control organization access. If a user doesn't have a Microsoft or GitHub account, ask the user to [sign up](https://signup.live.com/) for a Microsoft account or a GitHub account. + > Add email addresses for [personal Microsoft accounts](https://account.microsoft.com/account) and IDs for GitHub accounts unless you plan to use [Microsoft Entra ID](/azure/active-directory/fundamentals/active-directory-whatis) to authenticate users and control organization access. If a user doesn't have a Microsoft or GitHub account, ask the user to [sign up](https://signup.live.com/) for a Microsoft account or a GitHub account. 4. When you're done, select **Add** to complete your invitation. For more information, see [Add users or groups to a team or project](../../organizations/security/add-users-team-project.md) and [Add organization users for Azure DevOps Services](../../organizations/accounts/add-organization-users.md). ---> \ No newline at end of file +--> diff --git a/docs/boards/get-started/toc.yml b/docs/boards/get-started/toc.yml index b284b24f30e..61ab9759670 100644 --- a/docs/boards/get-started/toc.yml +++ b/docs/boards/get-started/toc.yml @@ -10,12 +10,12 @@ href: ../work-items/guidance/toc.yml - name: Permissions & access items: - - name: Default permissions & access for Boards - href: ../get-started/permissions-access-boards.md - displayname: security, features, stakeholder access - - name: Set work tracking & plan permissions - displayName: work item tags, roles, object-level, project-level, permissions - href: ../../organizations/security/set-permissions-access-work-tracking.md?toc=/azure/devops/boards/toc.json - - name: Manage permissions for select tasks - displayName: restrict access, visibility, closed work - href: ../../organizations/security/restrict-access.md?toc=/azure/devops/boards/toc.json + - name: Default permissions & access for Boards + href: ../get-started/permissions-access-boards.md + displayname: security, features, stakeholder access + - name: Set work tracking & plan permissions + displayName: work item tags, roles, object-level, project-level, permissions + href: ../../organizations/security/set-permissions-access-work-tracking.md?toc=/azure/devops/boards/toc.json + - name: Manage permissions for specific tasks + displayName: restrict access, visibility, closed work + href: ../../organizations/security/restrict-access.md?toc=/azure/devops/boards/toc.json diff --git a/docs/boards/get-started/what-is-azure-boards.md b/docs/boards/get-started/what-is-azure-boards.md index a5a555e6a5e..5815a26a36f 100644 --- a/docs/boards/get-started/what-is-azure-boards.md +++ b/docs/boards/get-started/what-is-azure-boards.md @@ -1,114 +1,72 @@ --- -title: What is Azure Boards? +title: What is Azure Boards titleSuffix: Azure Boards -description: Learn about the Agile tools that Azure Boards provides to manage software development projects. -ms.custom: boards-get-started, contperf-fy22q2 +description: Learn about the Agile tools that Azure Boards provides to manage software development projects. +ms.custom: boards-get-started ms.subservice: azure-devops-new-user -ms.assetid: ms.author: chcomley author: chcomley ms.topic: overview monikerRange: '<= azure-devops' -ms.date: 06/27/2023 +ms.date: 04/21/2025 +#customer intent: As a developer, I want to explore the Agile tools that Azure Boards provides, so I can manage software development projects. --- # What is Azure Boards? [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Azure Boards is a web-based service that enables teams to plan, track, and discuss work across the entire development process, while it supports agile methodologies, including [Scrum and Kanban](#implement-agile-scrum-and-kanban-processes). Azure Boards provides a customizable platform for managing work items, allowing teams to [collaborate](../../cross-service/cross-service-overview.md) effectively and streamline their workflow. [Sign up](sign-up-invite-teammates.md), [customize](../configure-customize.md), and experience the [benefits of using Azure Boards](#benefits-of-using-azure-boards). +Azure Boards is a web-based service that enables teams to plan, track, and discuss work across the entire development process, while it supports [agile methodologies](../work-items/guidance/agile-process.md). Azure Boards provides a customizable platform for managing work items, allowing teams to [collaborate](../../cross-service/cross-service-overview.md) effectively and streamline their workflow. [Sign up](sign-up-invite-teammates.md), [customize](../configure-customize.md), and experience the [benefits of using Azure Boards](#benefits-of-using-azure-boards). -## Use Azure Boards hubs +## Azure Boards hubs You can track and manage work and access various functions within each of the following hubs. -|Azure Boards hub |Functions | -|----------------|---------| -|[**Work items**](../work-items/about-work-items.md) | Access lists of work items based on specific criteria, such as those assigned to you, ones you follow, and work items you viewed or updated. | -|[**Boards**](../boards/kanban-overview.md) | View work items as cards and update their status through drag-and-drop, similar to physical sticky notes on a whiteboard. Use this feature to implement Kanban practices and visualize work flow for a team. | -|[**Backlogs**](../backlogs/backlogs-overview.md) | View, plan, order, and organize work items, including using a product backlog to represent your project plan and a portfolio backlog to group work under features and epics. | -|[**Sprints**](../sprints/assign-work-sprint.md) | Access your team's filtered view of work items based on a specific sprint or iteration path. Assign work to a sprint using drag-and-drop from the backlog. Interact with a backlog list or card-based Taskboard to implement Scrum practices. | -|[**Queries**](../queries/view-run-query.md) | Generate custom work item lists and perform various tasks, such as triage work, make bulk updates, and view relationships between work items. Queries also allow for creating status and trend charts that can be added to dashboards. | -|[**Delivery Plans**](../plans/review-team-plans.md) | Management teams can view deliverables and track dependencies across multiple teams in a calendar view. Delivery plans support tasks such as viewing up to 15 team backlogs, custom portfolio backlogs and epics, and work that spans several iterations. Users can add backlog items to a plan, view rollup progress of features and epics, and dependencies between work items. | -| [**Analytics views**](../../report/powerbi/what-are-analytics-views.md) | Create highly sophisticated Power BI reports, based on Azure Boards data (work items). Access default Analytics views or create a custom view. | +|Azure Boards hub |Functions | +|-----------------|----------| +|[**Work items**](../work-items/about-work-items.md) | Access lists of work items based on specific criteria, such as those assigned to you, ones you follow, and work items you viewed or updated. | +|[**Boards**](../boards/kanban-overview.md) | View work items as cards and update their status through drag-and-drop, similar to physical sticky notes on a whiteboard. Use this feature to implement Kanban practices and visualize work flow for a team. | +|[**Backlogs**](../backlogs/backlogs-overview.md) | View, plan, order, and organize work items, including using a product backlog to represent your project plan and a portfolio backlog to group work under features and epics. | +|[**Sprints**](../sprints/assign-work-sprint.md) | Access your team's filtered view of work items based on a specific sprint or iteration path. Assign work to a sprint by using drag-and-drop from the backlog. implement Scrum practices by interacting with a backlog list or card-based Taskboard. | +|[**Queries**](../queries/view-run-query.md) | Generate custom work item lists and perform various tasks, such as triage work, make bulk updates, and view relationships between work items. Queries also allow for creating status and trend charts that can be added to dashboards. | +|[**Delivery Plans**](../plans/review-team-plans.md) | Management teams can view deliverables and track dependencies across multiple teams in a calendar view. Delivery plans support tasks such as viewing up to 15 team backlogs, custom portfolio backlogs and epics, and work that spans several iterations. Users can add backlog items to a plan, view rollup progress of features and epics, and dependencies between work items. | +| [**Analytics views**](../../report/powerbi/what-are-analytics-views.md) | Create highly sophisticated Power BI reports, based on Azure Boards data (work items). Access default Analytics views or create a custom view. | **Azure Boards hubs UI** -:::image type="content" source="media/about-boards/boards-hubs.png" alt-text="Screenshot showing hubs in Azure Boards menu."::: +:::image type="content" source="media/about-boards/boards-hubs.png" alt-text="Screenshot of hubs in Azure Boards menu, including Work items, Boards, Backlogs, Sprints, Queries, Delivery Plans, and Analytics views."::: ## Benefits of using Azure Boards The following table lists some of the benefits of using Azure Boards. -|Benefit |Details | -|---------|---------| -|Start simply, scale as you grow | Azure Boards offers predefined work item types for tracking features, user stories, bugs, and tasks, making it easy to start using your product backlog or Kanban board. It supports different [Agile methods](../plans/agile-culture.md), so you can implement the method that suits you best. You can add teams as your organization grows to give them the autonomy to track their work as they see fit. | -|Use visual, interactive tools | Visual tools help teams quickly see and share progress with [Kanban boards](../boards/kanban-quickstart.md), [product backlogs](../backlogs/create-your-backlog.md), [built-in scrum boards and planning tools](../sprints/scrum-overview.md), and [delivery plans](../plans/review-team-plans.md). | -|Customize easily |Easily [configure and customize](../configure-customize.md) Kanban boards, Taskboards, and delivery plans through the user interface, as well as add [custom fields, work item types, and portfolio backlogs](../../organizations/settings/work/inheritance-process-model.md). | -|Use built-in social tools and communication | [Work item forms](../work-items/work-item-form-controls.md) provide built-in discussion that you can use to capture questions, notes, and communication as they occur. You can maintain a history of what a team decides on any particular work item. You can also quickly bring a team member or an entire team into the conversation [by using @mentions](../../organizations/notifications/at-mentions.md). | -|Capture information, generous cloud storage | Work items are designed to track all the information you need. You can edit in rich text, drag and drop inline images, and add larger attachments - up to 60 MB and as many as 100. Also, you can [link work items](../backlogs/add-link.md) within a hierarchy or by simple related links. Each work item form maintains a history of changes, so you can review what changed, who made the change, and when. | -|Find what you need quickly and get notified of changes | Azure Boards provides easy-to-use tools to help you quickly find specific work items as your project grows. You can [follow work items](../work-items/follow-work-items.md) to monitor updates and changes, use pivot views to show work items assigned to you, use the [query engine](../queries/query-field-value.md) to filter work items based on any field, and use ad-hoc search with quick inline filters. You can also personalize your alerts for work items that are assigned to you or have been changed. | -|Monitor status and progress with built-in dashboards and analytics | With Azure Boards, you gain access to many tools to generate reports to support tracking status and trends. By using [configurable dashboards](../../report/dashboards/dashboards.md), you can add one or more widgets. You configure widgets to display the information and data you want, such as the following bug [burndown widget](../../report/dashboards/configure-burndown-burnup-widgets.md). Along with dashboards, you have access to the [Analytics service](../../report/powerbi/what-is-analytics.md). This service is optimized for fast read-access and server-based aggregations. By using [Analytics views](../../report/powerbi/what-are-analytics-views.md) and [Power BI](../../report/powerbi/what-are-analytics-views.md), you can create highly sophisticated reports on the project data of interest. | -|Integrate with Office | Project managers who want to use familiar tools can import and export work item queries to and from Microsoft Office Excel or import and export work items using .csv files. For more information, see [Bulk import or update work items using CSV files](../queries/import-work-items-from-csv.md) or [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md)| -|Extend functionality | You can gain even greater functionality by adding Marketplace extensions, many of which are free. An extension is an installable unit that adds capabilities to Visual Studio, Azure DevOps Services, or Visual Studio Code. You can find extensions within these products or in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops), Azure DevOps tab. Also, by using the [REST API](/rest/api/azure/devops/index), you can create your own extensions or tools to integrate with Azure DevOps Services.| -|Get updates via a mobile browser | It's easy to stay on top of changes as they occur, using the [mobile browser](../../project/navigation/mobile-work.md), you can be notified and respond to changes made to work items. | -|Start for free |You can start for free and add up to five free users and unlimited [stakeholders](../../organizations/security/get-started-stakeholder.md). | - -For more information, see our Training module, [What is Azure Boards?](/training/modules/choose-an-agile-approach/3-what-is-azure-boards) +|Benefit |Details | +|--------|--------| +|Start simply, scale as you grow | Azure Boards offers predefined work item types for tracking features, user stories, bugs, and tasks, making it easy to start using your product backlog or board. It supports different [Agile methods](../plans/agile-culture.md), so you can implement the method that suits you best. You can add teams as your organization grows to give them the autonomy to track their work as they see fit. | +|Use visual, interactive tools | Visual tools help teams quickly see and share progress with [Boards](../boards/kanban-quickstart.md), [product backlogs](../backlogs/create-your-backlog.md), [built-in scrum boards and planning tools](../sprints/scrum-overview.md), and [delivery plans](../plans/review-team-plans.md). | +|Customize easily |Easily [configure and customize](../configure-customize.md) boards, Taskboards, and delivery plans through the user interface, as well as add [custom fields, work item types, and portfolio backlogs](../../organizations/settings/work/inheritance-process-model.md). | +|Use built-in social tools and communication | [Work item forms](../work-items/about-work-items.md#work-item-form-controls) provide built-in discussion that you can use to capture questions, notes, and communication as they occur. You can maintain a history of what a team decides on any particular work item. You can also quickly bring a team member or an entire team into the conversation [by using @mentions](../../organizations/notifications/at-mentions.md). | +|Capture information, generous cloud storage | Work items are designed to track all the information you need. You can edit in rich text, drag and drop inline images, and add larger attachments - up to 60 MB and as many as 100. Also, you can [link work items](../backlogs/add-link.md) within a hierarchy or by simple related links. Each work item form maintains a history of changes, so you can review what changed, who made the change, and when. | +|Find what you need quickly and get notified of changes | Azure Boards provides easy-to-use tools to help you quickly find specific work items as your project grows. You can [follow work items](../work-items/follow-work-items.md) to monitor updates and changes, use pivot views to show work items assigned to you, use the [query engine](../queries/query-field-value.md) to filter work items based on any field, and use ad-hoc search with quick inline filters. You can also personalize your alerts for work items that are changed or assigned to you. | +|Monitor status and progress with built-in dashboards and analytics | With Azure Boards, you gain access to many tools to generate reports to support tracking status and trends. By using [configurable dashboards](../../report/dashboards/dashboards.md), you can add one or more widgets. You configure widgets to display the information and data you want, such as the following bug [burndown widget](../../report/dashboards/configure-burndown-burnup-widgets.md). Along with dashboards, you have access to the [Analytics service](../../report/powerbi/what-is-analytics.md). This service is optimized for fast read-access and server-based aggregations. By using [Analytics views](../../report/powerbi/what-are-analytics-views.md) and Power BI, you can create highly sophisticated reports on the project data of interest. | +|Integrate with Office | Project managers who want to use familiar tools can import and export work item queries to and from Microsoft Office Excel or import and export work items using .csv files. For more information, see [Bulk import or update work items using CSV files](../queries/import-work-items-from-csv.md) or [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). | +|Extend functionality | You can gain even greater functionality by adding Marketplace extensions, many of which are free. An extension is an installable unit that adds capabilities to Visual Studio, Azure DevOps Services, or Visual Studio Code. You can find extensions within these products or in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops), Azure DevOps tab. Also, by using the [REST API](/rest/api/azure/devops/index), you can create your own extensions or tools to integrate with Azure DevOps Services. | +|Get updates via a mobile browser | It's easy to stay on top of changes as they occur, using the [mobile browser](../../project/navigation/mobile-work.md), you can be notified and respond to changes made to work items. | +|Start for free | You can start for free and add up to five free users and unlimited [stakeholders](../../organizations/security/get-started-stakeholder.md). | + +For more information, see the [What is Azure Boards?](/training/modules/choose-an-agile-approach/3-what-is-azure-boards) Training module. ## Connect Azure Boards to GitHub -You can connect Azure Boards with GitHub repositories to link GitHub commits, pull requests, and issues to work items. Use GitHub for software development and Azure Boards to plan and track work. Quickly open linked GitHub commits, pull requests, or issues from the Kanban board. For more information, see [GitHub & Azure Boards](../github/index.md). +You can connect Azure Boards with GitHub repositories to link GitHub commits, pull requests, branches, and issues to work items. Use GitHub for software development and Azure Boards to plan and track work. Quickly open linked GitHub commits, pull requests, or issues from the board. For more information, see [GitHub & Azure Boards](../github/index.md). -## Implement Agile, Scrum, and Kanban processes - -Azure Boards supports software development processes with default process models. Each process includes a set of work item types with a natural hierarchy. - -:::row::: - :::column span="2"::: - [**Basic**](../get-started/plan-track-work.md) provides the simplest model that tracks work through Issues, Tasks, and Epics. - :::column-end::: - :::column span="2"::: - :::image type="content" source="../get-started/media/about-boards/basic-process-epics-issues-tasks-2.png" alt-text="Conceptual image of Basic work item types"::: - :::column-end::: -:::row-end::: -:::row::: - :::column span="2"::: - [**Agile**](../work-items/guidance/agile-process.md) supports Agile planning methods (learn more about Agile methodologies at the - [Agile Alliance](https://www.agilealliance.org/)), including Scrum, - and tracks development and test activities separately. This process works great if you want to track user stories and - (optionally) bugs on the Kanban board, or track bugs and tasks on the Taskboard. - :::column-end::: - :::column span="2"::: - :::image type="content" source="../work-items/guidance/media/ALM_PT_Agile_WIT_Artifacts.png" alt-text="Agile work item types"::: - :::column-end::: -:::row-end::: -:::row::: - :::column span="2"::: - [**Scrum**](../work-items/guidance/scrum-process.md) tracks work using product backlog items (PBIs) and - bugs on the Kanban board or viewed on a sprint Taskboard. - - This process supports the Scrum methodology as defined by the [Scrum organization](https://www.scrum.org/) - :::column-end::: - :::column span="2"::: - :::image type="content" source="../work-items/guidance/media/ALM_PT_Scrum_WIT_Artifacts.png" alt-text="Scrum work item types"::: - :::column-end::: -:::row-end::: -:::row::: - :::column span="2"::: - [**Capability Maturity Model Integration** (CMMI)](../work-items/guidance/cmmi-process.md) supports a framework for process improvement and an auditable record of decisions. With this process, you can track requirements, change requests, risks, and reviews. - This process supports [formal change management activities](../work-items/guidance/cmmi/guidance-background-to-cmmi.md). - :::column-end::: - :::column span="2"::: - :::image type="content" source="../work-items/guidance/media/ALM_PT_CMMI_WIT_Artifacts.png" alt-text="CMMI work item types"::: - :::column-end::: - :::row-end::: +For more information, see [About default processes and process templates](../work-items/guidance/choose-process.md). ## Configure dashboards and Power BI reports Dashboards provide teams with customized views for status updates, progress tracking, and trend analysis. Teams can share information and improve workflows with flexible and tailored dashboard options. -:::image type="content" source="media/about-boards/dashboard.png" alt-text="Screenshot of Azure Boards, Dashboards"::: +:::image type="content" source="media/about-boards/dashboard.png" alt-text="Screenshot of Azure Boards Dashboards with Content Team status, Project Velocity, and Sprint Burndown information." lightbox="media/about-boards/dashboard.png"::: Use Power BI to create customized reports based on Analytics service queries for quantitative analysis of project data. For more information, see [About dashboards, charts, reports, & widgets](../../report/dashboards/overview.md) and [What is the Analytics service?](../../report/powerbi/what-is-analytics.md). @@ -126,21 +84,31 @@ With Azure Boards, you gain the advantage of full integration with the Azure Dev For more information, see [End-to-end traceability](../../cross-service/end-to-end-traceability.md) and [Cross-service integration and collaboration overview](../../cross-service/cross-service-overview.md). - - ## Support independent, autonomous teams A team in Azure Boards is a group of project members who work in a specific product area represented by hierarchical paths called **Area Paths**. Define teams by their name, members, and area paths and are essential for configuring Boards, Backlogs, Sprints, and Delivery Plans in Azure Boards. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). -:::image type="content" source="../../organizations/settings/media/agile-tools/agile-tools-team-assets.png" alt-text="Conceptual image of team tools"::: +:::image type="content" source="../../organizations/settings/media/agile-tools/agile-tools-team-assets.png" border="false" alt-text="Conceptual diagram of team tools that shows Team options for planning, tracking, collaboration, monitoring, and learning."::: Azure Boards integrates with popular chat tools such as [Microsoft Teams](../integrations/boards-teams.md) and [Slack](../integrations/boards-slack.md) through ChatOps. It also offers extensions that add new capabilities to your projects and can be found in the [Azure DevOps Marketplace](https://marketplace.visualstudio.com/azuredevops). These extensions can help with planning and tracking work items, sprints, scrums, and other project management tasks, as well as collaboration among team members. -## Related articles +## New Azure Boards + +You might notice some changes in the user experience of Azure Boards. These updates are part of the new Azure Boards, designed to provide a faster interface, improve accessibility, and ensure consistency with other areas of the product. + +### What to expect + +The core functionality of Azure Boards remains the same. It still contains the features you know and love such as Boards, Backlogs, Sprints, Queries, and Delivery Plans. However, the user experience is refined to align with the rest of Azure DevOps. User interface changes include increased spacing between elements and strategically placed scroll bars to enhance accessibility. + +It can take time to adjust to changes. To ease the transition, try out the [new features](https://devblogs.microsoft.com/devops/new-boards-hub-rollout-update-2) exclusive to the updated Azure Boards. + +### Provide feedback + +If you encounter technical issues beyond the cosmetic, or want to provide feature input, [share your feedback](../../user-guide/provide-feedback.md) with the product team. + +## Related content -- [Best tool to add, update, and link work items](../work-items/best-tool-add-update-link-work-items.md) - [Configure and customize Azure Boards](../configure-customize.md) -- [The DevOps journey at Microsoft](https://azure.microsoft.com/solutions/devops/devops-at-microsoft/) -- [Agile culture](../plans/agile-culture.md) -- [Practices that scale](../plans/practices-that-scale.md) -- [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md) +- [Explore the DevOps journey at Microsoft](https://azure.microsoft.com/solutions/devops/devops-at-microsoft/) +- [Promote an Agile culture](../plans/agile-culture.md) +- [Learn about teams and Agile tools](../../organizations/settings/about-teams-and-settings.md) diff --git a/docs/boards/github/configure-status-badges.md b/docs/boards/github/configure-status-badges.md index 16db6c50e3c..164c23d1938 100644 --- a/docs/boards/github/configure-status-badges.md +++ b/docs/boards/github/configure-status-badges.md @@ -1,51 +1,46 @@ --- -title: Enable Kanban board badge status for a GitHub repo +title: Add status badges for your GitHub repo titleSuffix: Azure Boards -description: Learn how to configure your Kanban board badge status. You can configure the badge status to appear on your GitHub repo. +description: Learn how to add and configure your board badge status so it appears on your GitHub repo. ms.service: azure-devops-boards -ms.topic: quickstart +ms.topic: how-to ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' -ms.date: 07/03/2023 +monikerRange: "<=azure-devops" +ms.date: 07/12/2023 --- -# Configure status badges for your GitHub repo +# Add status badges for your GitHub repo [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -You can add Markdown syntax to a GitHub repo `README.md` file to display your Kanban board status in that repo. Show the status by adding the syntax you choose from your Kanban board settings. - -::: moniker range="azure-devops-2019" -> [!NOTE] -> Requires Azure DevOps Server 2019 Update 1 or later version. -::: moniker-end +You can add Markdown syntax to a GitHub repo `README.md` file to display your board status in that repo. Show the status by adding the syntax you choose from your board settings. The syntax shown works whether you [connected your project to a GitHub.com or your GitHub Enterprise Server repository](connect-to-github.md). For GitHub Enterprise Server, your server must be network accessible to Azure DevOps Services. ## Prerequisites -* Your Azure Boards project must be connected to the GitHub repository where the commits and pull requests you want to link to/from exist. For more information, see [Azure Boards-GitHub integration](index.md). -* You must have a Kanban board you want to configure. When you add a team, you add a Kanban board for that team. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). -* You must be added to the team administrator role for the team's settings you want to modify, or be a member of the **Project Administrators** security group. To get added, see [Add a team administrator](../../organizations/settings/add-team-administrator.md) or [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). -* To add the status badge to the GitHub.com repository, you must be a contributor of the repository. +| Category | Requirements | +|--------------|-------------| +| **Permissions** | [Team administrator](../../organizations/settings/add-team-administrator.md) for the team's settings you want to modify or member of the [**Project Administrators**](../../organizations/security/change-project-level-permissions.md) group. | +| **Integration with GitHub** | [Connect your project to the GitHub repository](index.md) where the commits and pull requests you want to link to or from exist. | +| **Board configuration** | A board you want to configure. When you add a team, you add a board for that team. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). | +| **Repository access** | To add the status badge to the GitHub.com repository: Contributor to the repository. | ## Add a status badge -1. Sign into Azure Boards and [open your Kanban board](../boards/kanban-quickstart.md). +1. Sign into Azure Boards and [open your board](../boards/kanban-quickstart.md). -2. Select the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board and set general team settings. +2. Select the :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board and set general team settings. -:::image type="content" source="../../organizations/settings/media/configure-team/open-board-settings.png" alt-text="Screenshot of opening board settings."::: + :::image type="content" source="../../organizations/settings/media/configure-team/open-board-settings.png" alt-text="Screenshot of opening board settings."::: 3. Select **Status badge** and then check or uncheck the **Allow anonymous users to access the status badge**. When it's unchecked, users who aren't signed in can still view the status badge. ::: moniker range=">= azure-devops-2020" - :::image type="content" source="media/badges/status-badge-s188.png" alt-text="Screenshot of Kanban Board Settings dialog, Status badge tab."::: - ::: moniker-end - ::: moniker range="azure-devops-2019" - :::image type="content" source="media/badges/status-badge.png" alt-text="Screenshot of Kanban Board Settings dialog, Status badge tab, Azure DevOps Server 2019."::: + :::image type="content" source="media/badges/status-badge-s188.png" alt-text="Screenshot of board Settings dialog, Status badge tab."::: ::: moniker-end + 4. Choose the badge type you want and choose the :::image type="icon" source="../../media/icons/copy.png" border="false"::: copy icon to copy the Markdown syntax for the badge. @@ -65,15 +60,15 @@ The syntax shown works whether you [connected your project to a GitHub.com or yo The only setting that you can configure is the **Allow anonymous users to access the status badge**. The badge type under **Settings** only switches the Markdown syntax for you to copy from the **Sample Markdown** and **Image URL** values. -6. Open the README file in your GitHub repo and paste the syntax you copied to have the badge display. +6. Open the README file in your GitHub repo and paste the syntax you copied to make the badge display. - You should see the same preview image that you selected with values that correspond to your Kanban board. For example: + You should see the same preview image that you selected with values that correspond to your board. ## Related articles -- [Add columns to your Kanban board](../boards/add-columns.md) +- [Add columns to your board](../boards/add-columns.md) - [Customize cards](../boards/customize-cards.md) - [Configure team settings](../../organizations/settings/manage-teams.md) - [Change GitHub repository access](install-github-app.md#change-repository-access) -- [Azure Boards-GitHub integration](index.md) +- [Integrate Azure Boards with GitHub](index.md) - [Troubleshoot GitHub & Azure Boards integration](troubleshoot-github-connection.md) diff --git a/docs/boards/github/connect-on-premises-to-github.md b/docs/boards/github/connect-on-premises-to-github.md index b2bd2b0d70b..84871728b81 100644 --- a/docs/boards/github/connect-on-premises-to-github.md +++ b/docs/boards/github/connect-on-premises-to-github.md @@ -6,8 +6,8 @@ ms.service: azure-devops-boards ms.topic: how-to ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019 < azure-devops' -ms.date: 07/03/2023 +monikerRange: " [!NOTE] -> On-premises Azure DevOps Server 2019 supports integration with GitHub Enterprise Server repositories. If you want to connect from Azure DevOps Services, see [Connect Azure Boards to GitHub](./connect-to-github.md?preserve-view=true&view=azure-devops). - -::: moniker-end - ## Prerequisites -* To connect to GitHub.com repositories, you must install Azure DevOps Server 2020.1.1 Patch 2. Without this patch, you can only connect to your GitHub Enterprise Server repositories. -* [Install the Azure Boards app for GitHub](install-github-app.md) on the GitHub organizations or account. -* Connect to an Azure Boards or Azure DevOps project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -* You must be a member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) and the project's [Contributors group](../../organizations/security/add-users-team-project.md). If you created the project, then you have permissions. -* You must be an administrator of the GitHub Enterprise Server that you connect to. +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - Member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) and the project [Contributors group](../../organizations/security/add-users-team-project.md). If you created the project, then you have permissions.
- **Administrator** of the GitHub Enterprise Server that you connect to. | +| **Project membership**| [Project member](../../organizations/projects/create-project.md). | +| **Integration with GitHub** | - Azure DevOps Server 2020.1.1 Patch 2. Without this patch, you can only connect to your GitHub Enterprise Server repositories.
- [Azure Boards app for GitHub](install-github-app.md) installed on the GitHub organizations or account. | ## Authentication options @@ -46,85 +38,15 @@ The following authentication options are supported. ::: moniker range="azure-devops-2020" - [PAT](#server-github-ent-pat) -- [Username plus password](#server-github-ent-username) +- [GitHub credentials](#server-github-ent-credentials) > [!NOTE] > OAuth isn't supported for Azure DevOps Server 2020. ::: moniker-end -::: moniker range="azure-devops-2019" -- [OAuth (Recommended, registration required)](#server-github-ent-oauth-register) -- [PAT](#server-github-ent-pat) -- [Username plus password](#server-github-ent-username) -::: moniker-end - - - - - -::: moniker range="azure-devops-2019" - -## Register Azure DevOps in GitHub as an OAuth App - -If you plan to use OAuth to connect Azure DevOps Server with your GitHub Enterprise Server, you first need to register the application as an OAuth App. For more information, see [Create an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app). - - - - -### Register Azure DevOps Server - -1. Sign into the web portal for your GitHub Enterprise server. - - :::image type="content" source="media/github-ent/sign-in-to-ghe.png" alt-text="Screenshot of sign in for GitHub Enterprise Server."::: - -2. Select **Settings** > **Developer settings** > **Oauth Apps** > **New OAuth App**. - - :::image type="content" source="media/github-ent/ghe-settings-dev-oauth.png" alt-text="Screenshot showing sequence for getting to New OAuth App screen."::: - -3. Enter your information to register your Azure DevOps Server application. - - :::image type="content" source="media/github-ent/ghe-register-app.png" alt-text="Screenshot of Azure DevOps Server project registration."::: - - For the **Homepage URL**, specify the **Public URL** of your project collection. You can find this URL when you [open the Azure DevOps Administration Console](/azure/devops/server/admin/open-admin-console) and viewing the **Application Tier** node. - - :::image type="content" source="media/github-ent/app-tier-find-public-url.png" alt-text="Screenshot of Azure DevOps Server Administration Console, Application Tier."::: - - For the **Authorization callback URL**, use the following pattern to construct the URL. - - `{Azure DevOps Server Public Url}/{Collection Name}/_admin/oauth2/callback` - - For example: - - `http://contoso/DefaultCollection/_admin/oauth2/callback` - - `https://tfs.contoso.com/MyCollection/_admin/oauth2/callback` - -4. Select **Register application**. - -5. A page appears that provides the **Client ID** and **Client Secret** for your registered OAuth application. - - :::image type="content" source="media/github-ent/ghe-register-app-success.png" alt-text="Screenshot of Client ID and Client Secret for your registered OAuth application."::: - - - -### Register your OAuth configuration in Azure DevOps Server - -1. Sign into the web portal for your Azure DevOps Server. - -1. Add the GitHub Enterprise Oauth configuration to your Azure DevOps Server collection. - -2. Select **Admin settings** > **Oauth configurations** > **Add Oauth configuration**. - - :::image type="content" source="media/github-ent/open-admin-settings-server-oauth-add.png" alt-text="Screenshot showing step sequence to add OAuth configuration."::: - -3. Enter your information, and then select **Create**. - - :::image type="content" source="media/github-ent/add-oauth-configuration.png" alt-text="Screenshot of OAuth configuration dialog."::: - - - - -::: moniker-end + + + ## Connect Azure DevOps Server to GitHub Enterprise Server @@ -136,10 +58,7 @@ You can connect up to 250 GitHub repositories to an Azure Boards project. > Connection to GitHub.com repositories requires Azure DevOps Server 2020.1.1 Patch 2 or later version. ::: moniker-end -::: moniker range="azure-devops-2019" -You can connect up to 100 GitHub repositories to an Azure Boards project. This limit can't be changed. -::: moniker-end 1. Open the web portal for your Azure DevOps Server. @@ -154,33 +73,15 @@ You can connect up to 100 GitHub repositories to an Azure Boards project. This l 4. If it's the first time making a connection from the project, choose the authentication method you want to use to make the connection: - **Personal Access Token**, for details see [Connect using a Personal Access Token](#github-ent-pat). - - **User Name and Password**, see [Connect using a Username and Password](#server-github-ent-username). + - **GitHub credentials**, see [Connect using GitHub credentials](#server-github-ent-credentials). :::image type="content" source="media/github-ent/connect-github-account-first-time.png" alt-text="Screenshot of first time connecting with GitHub credentials."::: Otherwise, select :::image type="icon" source="../../media/icons/add-light-icon.png" border="false"::: **New connection**, and the select your authentication method from the **New Connection** dialog. ::: moniker-end -::: moniker range="azure-devops-2019" - -3. Select **Project settings** > **GitHub connections** > **Connect your GitHub Enterprise account**. - - :::image type="content" source="media/github-ent/open-project-settings-github-connections.png" alt-text="Screenshot of Project settings, selected Integrations."::: - - Or, choose a **personal access token** or **username and password**, if you're using those credentials. -::: moniker-end - -::: moniker range="azure-devops-2019" - -#### Connect using OAuth -Choose the configuration that you set up in [Step 4 of Register your OAuth configuration in Azure DevOps Server](#register-server-github-ent-oauth). Then, select **Connect**. - - :::image type="content" source="media/github-ent/new-github-ent-connect-oauth.png" alt-text="Screenshot fo New GitHub Enterprise connection, OAuth dialog."::: - -::: moniker-end - - - + + #### Connect with a Personal Access Token @@ -193,13 +94,13 @@ Choose the configuration that you set up in [Step 4 of Register your OAuth confi :::image type="content" source="media/github-ent/ads-add-ghe-pat.png" alt-text="Screenshot of sign in with PAT."::: - + -#### Connect with a Username and Password +#### Connect with GitHub credentials 1. Enter the URL for your GitHub Enterprise server and the administrator account credentials recognized by that server. And then choose **Connect**. - :::image type="content" source="media/github-ent/ads-add-ghe-user-name.png" alt-text="Screenshot of sign in with username and password."::: + :::image type="content" source="media/github-ent/ads-add-ghe-user-name.png" alt-text="Screenshot of sign in with GitHub credentials."::: 2. The dialog lists all repositories for which you have GitHub administration rights. You can toggle between **Mine** and **All** to determine if others appear, and then check the ones that you want to add. Choose **Save** when you're done. @@ -239,7 +140,7 @@ The following authentication options are supported based on the GitHub platform :::column span="1"::: - OAuth - PAT - - Username plus password + - GitHub credentials :::column-end::: :::row-end::: :::row::: @@ -251,7 +152,7 @@ The following authentication options are supported based on the GitHub platform :::column-end::: :::column span="1"::: - PAT - - Username plus password + - GitHub credentials :::column-end::: :::row-end::: :::row::: @@ -264,7 +165,7 @@ The following authentication options are supported based on the GitHub platform :::column span="1"::: - OAuth - PAT - - Username plus password + - GitHub credentials :::column-end::: :::row-end::: @@ -280,9 +181,6 @@ When the Azure Boards connection to GitHub no longer has access, it shows an ale ::: moniker-end -::: moniker range="azure-devops-2019" -When the Azure Boards connection to GitHub no longer has access, it shows an alert status in the user interface with a red-X that has a tooltip such as, *Unable to connect to GitHub*. -::: moniker-end Consider the following resolutions: @@ -295,20 +193,24 @@ Consider the following resolutions: Delete and recreate the connection to the GitHub repository. This recreated connection causes GitHub to prompt to reauthorize Azure Boards. - **If the connection is using a PAT:** - - The PAT may have been revoked or the required permission scopes changed and are insufficient. - - The user may have lost admin permissions on the GitHub repo. + - The PAT was revoked or the required permission scopes changed and are insufficient. + - The user perhaps lost administrative permissions on the GitHub repository. - Recreate the PAT and ensure the scope for the token includes the required permissions: `repo, read:user, user:email, admin:repo_hook`. + Recreate the PAT and ensure the scope for the token includes the required permissions: `repo, read:user, user:email, admin:repo_hook`. For more information, see [Best practices for using PATs](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#best-practices-for-using-pats). - + #### Update XML definitions for select work item types -If your organization uses the Hosted XML or on-premises XML process model to customize the work tracking experience and you want to link to and view the GitHub link types from the Development section in the work item forms, you must update the XML definitions for the work item types. +If your organization customizes work tracking using the Hosted XML or on-premises XML process model and wants to integrate GitHub link types into the Development section of work item forms, you must update the XML definitions for the corresponding work item types. + +For example, to link user stories and bugs to GitHub commits and pull requests within the **Development** section of work item forms, you must update the XML definitions for these work item types. -For example, if you want to link user stories and bugs to GitHub commits and pull requests from the **Development** section, you need to update the XML definitions for user stories and bugs. +To modify the XML definitions, do the steps outlined in [Hosted XML process model](../../organizations/settings/work/hosted-xml-process-model.md). For each work item type: +1. Locate the `Group Label="Development"` section. +2. To support the external link types, **GitHub Commit** and **GitHub Pull Request**, add the following lines of code: -Follow the sequence of tasks provided in [Hosted XML process model](../../organizations/settings/work/hosted-xml-process-model.md) to update the XML definitions. For each work item type, find the `Group Label="Development"` section, and add the following two lines in the following code syntax to support the external links types: **GitHub Commit** and **GitHub Pull Request**. +This integration enables seamless tracking of GitHub activities directly from your work items in Azure Boards. > [!div class="tabbedCodeSnippets"] > ```XML @@ -349,7 +251,6 @@ When it updates, the section should appear as follows. ## Related articles -- [What is Azure Boards?](../../boards/get-started/what-is-azure-boards.md) +- [Learn about Azure Boards](../../boards/get-started/what-is-azure-boards.md) - [Troubleshoot GitHub & Azure Boards integration](troubleshoot-github-connection.md) - [Build GitHub Enterprise Server repositories](../../pipelines/repos/github-enterprise.md) -- [Trigger an Azure Pipelines run from GitHub Actions](../../pipelines/ecosystems/github-actions.md) diff --git a/docs/boards/github/connect-to-github.md b/docs/boards/github/connect-to-github.md index 628a50cf048..0bb09b21184 100644 --- a/docs/boards/github/connect-to-github.md +++ b/docs/boards/github/connect-to-github.md @@ -1,13 +1,13 @@ --- title: Connect an Azure Boards or Azure DevOps project to a GitHub repository titleSuffix: Azure Boards -description: Configure one or more GitHub repositories to integrate with Azure Boards +description: Configure one or more GitHub repositories to integrate with Azure Boards. ms.service: azure-devops-boards ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 07/03/2023 +ms.date: 02/10/2025 --- # Connect Azure Boards to GitHub (cloud) @@ -21,9 +21,10 @@ Use GitHub.com repositories for your software development and your Azure Boards ## Prerequisites -* You must have an Azure Boards or Azure DevOps project. If you don't have a project yet, [create one](../get-started/sign-up-invite-teammates.md). -* You must be a member of the [**Project Administrators** group](../../organizations/security/change-project-level-permissions.md). If you created the project, you have permissions. -* You must be an administrator or owner of the GitHub repository to connect to. You can connect to multiple GitHub repositories as long as you're an administrator for those repositories. +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - Member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) If you created the project, you have permissions.
- **Administrator** or **owner** of the GitHub repository to connect to. You can connect to multiple GitHub repositories as long as you're an administrator for those repositories. | +| **Project membership**| [Project member](../../organizations/projects/create-project.md). | ## Authentication options @@ -39,69 +40,69 @@ The following authentication options are supported based on the GitHub platform :::row-end::: :::row::: :::column span=""::: - - [GitHub.com user account (Recommended)](#server-github-ent-username) + - [GitHub.com user account (Recommended)](#add-a-github-connection-with-github-credentials) - [Personal access token (PAT)](#github-pat) :::column-end::: :::column span=""::: - [OAuth (preferred, registration required)](#server-github-ent-oauth-register) - [PAT](#server-github-ent-pat) - - [Username plus password](#server-github-ent-username) + - [GitHub credentials](#server-github-ent-credentials) :::column-end::: :::row-end::: > [!NOTE] -> If you choose to connect Github with PAT, make sure you configure single sign-on (SSO) for the PAT on your GitHub account. This is needed to be able to get a list of repositories of an organization with Security Assertion Markup Language (SAML) SSO authentication configured. +> If you choose to connect GitHub with a PAT, configure single sign-on (SSO) for the PAT on your GitHub account. This configuration is necessary to retrieve a list of repositories from an organization with Security Assertion Markup Language (SAML) SSO authentication enabled. -## Connect Azure Boards to a GitHub repo. +## Connect Azure Boards to a GitHub repo -1. Sign into your Azure DevOps project. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization/Your_Project}```). 2. Select **Project settings** > **GitHub connections**. :::image type="content" source="media/connect-cloud/open-project-settings-github-connections.png" alt-text="Screenshot of open Project Settings>GitHub connections."::: -1. If it's the first time you make a connection from the project, choose **Connect your GitHub account** to use your GitHub account credentials. +3. If it's your first time connecting from the project, select **Connect your GitHub account** to use your GitHub account credentials. :::image type="content" source="media/connect-cloud/connect-github-account-first-time.png" alt-text="Screenshot of first time connecting with GitHub credentials."::: Otherwise, choose :::image type="icon" source="../../media/icons/add-light-icon.png" border="false"::: **New connection**, and select your authentication method from the **New Connection** dialog. - When you connect using your GitHub account, use your GitHub account credentials to authenticate. To use PAT, see [Add a GitHub connection using PAT](#github-pat). To connect to a GitHub Enterprise Server, see [Register Azure DevOps in GitHub as an OAuth App](#server-github-ent-oauth-register). + When you connect with your GitHub account, use your GitHub credentials to authenticate. To use a PAT, see [Add a GitHub connection using PAT](#github-pat). For connecting to a GitHub Enterprise Server, see [Register Azure DevOps in GitHub as an OAuth App](#server-github-ent-oauth-register). ## Add a GitHub connection with GitHub credentials -You can connect up to 250 GitHub repositories to an Azure Boards project. +You can connect up to 1,000 GitHub repositories to an Azure Boards project. -1. If it's your first time connecting to GitHub from Azure Boards, you're asked to sign in using your GitHub credentials. Choose an account for which you're a repository administrator. +1. If it's your first time connecting to GitHub from Azure Boards, sign in using your GitHub credentials. Choose an account for which you're a repository administrator. -2. Choose the GitHub account or organization that you want to connect. Only those organizations that you own or are an administrator for are listed. +2. Select the GitHub account or organization you want to connect. Only organizations that you own or are an administrator for are listed. - If all repositories for an organization have already been connected to Azure Boards, you see the following message. + If all repositories for an organization are already connected to Azure Boards, the following message shows: - :::image type="content" source="media/connect-cloud/message-all-repositories-already-connected.png" alt-text="Screenshot of message where no more repositories exist to connect."::: + :::image type="content" source="media/connect-cloud/message-all-repositories-already-connected.png" alt-text="Screenshot of message where no more repositories exist to connect."::: -3. Enter your GitHub credentials. If you have two-factor authentication enabled, enter the authentication code that GitHub sent you and choose **Verify**. Otherwise, the system automatically recognizes your GitHub organization as your GitHub account has previously been associated with your Azure DevOps Services account. +3. Enter your GitHub credentials. If you have two-factor authentication enabled, enter the authentication code sent by GitHub and select **Verify**. If not, the system automatically recognizes your GitHub organization as your GitHub account is associated with your Azure DevOps Services account. - + -### Choose the repositories +### Add GitHub repositories -Once you're authenticated, you can select the repositories you want to connect. +Once authenticated, you can select the repositories you want to connect. -1. The **Add GitHub Repositories** dialog automatically displays and selects all GitHub.com repositories for which you're an administrator for the organization you selected. Unselect any repositories that you don't want to participate in the integration. +1. The **Add GitHub Repositories** dialog automatically displays and selects all GitHub.com repositories for which you're an administrator in the selected organization. Deselect any repositories that you don't want to include in the integration. :::image type="content" source="media/github/add-github-repos.png" alt-text="Screenshot showing GitHub repos."::: > [!TIP] - > We recommend that you only connect a GitHub repo to projects defined in a single Azure DevOps organization. Connecting the same GitHub repo to projects defined in two or more Azure DevOps organizations can lead to unexpected **AB#** mention linking. For more information, see [Troubleshoot GitHub & Azure Boards integration](connect-to-github.md#resolve-connection-issues). + > To avoid unexpected **AB#** mention linking, we recommend connecting a GitHub repo to projects within a single Azure DevOps organization. Connecting the same GitHub repo to projects in multiple Azure DevOps organizations can cause issues. For more information, see [Troubleshoot GitHub & Azure Boards integration](connect-to-github.md#resolve-connection-issues). - If all repositories are connected already to the current or other organization, then the following message displays. + If all repositories are already connected to the current or another organization, the following message displays: :::image type="content" source="media/connect-cloud/message-all-repositories-already-connected.png" alt-text="Screenshot of message where no more repositories exist to connect."::: -2. When you're done, select **Save**. +2. After making your selections, select **Save**. - + ### Confirm the connection @@ -109,7 +110,7 @@ Once you're authenticated, you can select the repositories you want to connect. :::image type="content" source="media/github/approve-install-auth-azure-boards-from-github.png" alt-text="Screenshot showing confirming GitHub repositories."::: -2. Provide your GitHub password to confirm. +2. Provide your GitHub credentials to confirm. 3. When you're done, you should see the new connection with the selected repositories listed. @@ -117,12 +118,14 @@ Once you're authenticated, you can select the repositories you want to connect. To change the configuration or manage the Azure Boards app for GitHub, see [Change repository access to Azure Boards](change-azure-boards-app-github-repository-access.md). - - + + ## Add a GitHub connection using PAT -We recommend that you use your GitHub account credentials to connect to your GitHub repository. However, if you need to use a PAT, do so by following these procedures. +[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] + +We recommend using your GitHub account credentials to connect to your GitHub repository. > [!TIP] > When you create your GitHub PAT, make sure that you include these scopes: `repo, read:user, user:email, admin:repo_hook`. @@ -133,21 +136,21 @@ We recommend that you use your GitHub account credentials to connect to your Git To create a GitHub PAT, go to [GitHub Developer Settings > Personal access tokens](https://github.com/settings/tokens). -2. Enter the PAT and choose **Connect**. +2. Enter the PAT and select **Connect**. :::image type="content" source="media/github/add-github-connection-dialog-pat.png" alt-text="Screenshot showing entered PAT."::: -3. Choose the repositories you want connected to the project by following the procedures outlined in [Choose the repositories](#choose-repositories) earlier in this article. +3. Select the repositories you want to connect to the project by following the procedures outlined in [Choose the repositories](#choose-repositories) earlier in this article. -4. If it's the first time connecting to a GitHub account or organization from Azure Boards, you also must install the Azure Boards app for GitHub. [Confirm the connection](#confirm-connection) earlier in this article. +4. If it's the first time connecting to a GitHub account or organization from Azure Boards, install the Azure Boards app for GitHub. [Confirm the connection](#confirm-connection) earlier in this article. - + ## Register Azure DevOps in GitHub as an OAuth App -If you plan to use OAuth to connect Azure DevOps with your GitHub Enterprise Server, you first need to register the application as an OAuth App. For more information, see [Create an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). +To use OAuth to connect Azure DevOps with your GitHub Enterprise Server, first register the application as an OAuth App. For more information, see [Create an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). - + ### Register Azure DevOps Services @@ -159,10 +162,10 @@ If you plan to use OAuth to connect Azure DevOps with your GitHub Enterprise Ser :::image type="content" source="media/github-ent/ghe-settings-dev-oauth.png" alt-text="Screenshot showing sequence for New OAuth App."::: -3. Enter information to register your application. +3. Enter registration information. - For the Homepage URL, specify the Organization URL of your organization. - For the Authorization callback URL, use the following pattern to construct the URL. + For the **Homepage URL**, specify the **Organization URL** of your organization. + For the **Authorization callback URL**, use the following pattern to construct the URL. `{Azure DevOps Services Organization URL}/_admin/oauth2/callback` @@ -178,7 +181,7 @@ If you plan to use OAuth to connect Azure DevOps with your GitHub Enterprise Ser :::image type="content" source="media/github-ent/ghe-register-app-success.png" alt-text="Screenshot of Client ID and Client Secret for the registered OAuth application."::: - + ### Register your OAuth configuration in Azure DevOps Services @@ -194,16 +197,16 @@ If you plan to use OAuth to connect Azure DevOps with your GitHub Enterprise Ser :::image type="content" source="media/connect-cloud/register-oauth-azure-devops.png" alt-text="OAuth configurations dialog."::: - + ## Connect Azure DevOps Services to GitHub Enterprise Server > [!IMPORTANT] -> To connect Azure DevOps Services to your GitHub Enterprise Server, your GitHub Enterprise Server must be sufficiently accessible from the Internet. Make sure Azure DNS can resolve your GitHub Enterprise Server name and your firewall allows access from Azure Data Center IP addresses. To determine the IP address range, see [Microsoft Azure Data Center IP Ranges](https://www.microsoft.com/download/details.aspx?id=41653). A common error message encountered when connectivity issues exist is: +> To connect Azure DevOps Services to your GitHub Enterprise Server, ensure your GitHub Enterprise Server is accessible from the Internet. Verify that Azure DNS can resolve your GitHub Enterprise Server name and that your firewall allows access from Azure Data Center IP addresses. To determine the IP address range, see [Microsoft Azure Data Center IP Ranges](https://www.microsoft.com/download/details.aspx?id=41653). A common error message for connectivity issues is: > > *The remote name could not be resolved: 'github-enterprise-server.contoso.com'* > -> If you encounter this error, check that your server is accessible. For more information, see [Azure DNS FAQ](/azure/dns/dns-faq). +> If you encounter this error, check your server's accessibility. For more information, see [Azure DNS FAQ](/azure/dns/dns-faq). 1. Select **Project settings** > **GitHub connections** > **GitHub Enterprise Server** for a first-time connection. @@ -223,7 +226,7 @@ If you plan to use OAuth to connect Azure DevOps with your GitHub Enterprise Ser :::image type="content" source="media/connect-cloud/new-github-enterprise-server-dialog-oauth.png" alt-text="Screenshot of New GitHub Enterprise connection, OAuth connection dialog."::: - + **Connect with a Personal Access Token** @@ -231,9 +234,9 @@ If you plan to use OAuth to connect Azure DevOps with your GitHub Enterprise Ser :::image type="content" source="media/connect-cloud/new-github-enterprise-server-dialog-pat.png" alt-text="Screenshot of New GitHub Enterprise connection, Personal access token connection dialog."::: - + - **Connect with a Username and Password** + **Connect with GitHub credentials** Enter the URL for your GitHub Enterprise server and the administrator account credentials recognized by that server, and then select **Connect**. @@ -250,13 +253,13 @@ If you plan to use OAuth to connect Azure DevOps with your GitHub Enterprise Ser ## Resolve connection issues -The Azure Boards-GitHub integration relies on various authentication protocols to support the connection. Changes to a user's permission scope or authentication credentials can cause revocation of the GitHub repositories connected to Azure Boards. - -For an overview of the integration that the Azure Boards app for GitHub supports, see [Azure Boards-GitHub integration](index.md). +The Azure Boards-GitHub integration uses various authentication protocols to maintain the connection. Changes to a user's permission scope or authentication credentials can revoke the GitHub repositories connected to Azure Boards. -#### Supported authentication options +For an overview of the integration supported by the Azure Boards app for GitHub, see [Azure Boards-GitHub integration](index.md). -The following authentication options are supported based on the GitHub platform you want to connect to. +### Supported authentication options + +The following supported authentication options depend on the GitHub platform you are connecting to: :::row::: :::column span="1"::: @@ -280,7 +283,7 @@ The following authentication options are supported based on the GitHub platform :::column span="1"::: - OAuth - PAT - - Username plus password + - GitHub credentials :::column-end::: :::row-end::: :::row::: @@ -292,7 +295,7 @@ The following authentication options are supported based on the GitHub platform :::column-end::: :::column span="1"::: - PAT - - Username plus password + - GitHub credentials :::column-end::: :::row-end::: :::row::: @@ -305,28 +308,28 @@ The following authentication options are supported based on the GitHub platform :::column span="1"::: - OAuth - PAT - - Username plus password + - GitHub credentials :::column-end::: :::row-end::: [!INCLUDE[temp](../includes/github-platform-support.md)] -#### Grant Azure Boards organization access +### Grant Azure Boards organization access -If the integration between Azure Boards and GitHub isn't working as expected, verify you've granted organization access. +If the integration between Azure Boards and GitHub isn't working as expected, verify that you granted organization access. 1. From GitHub web portal, open **Settings** from your profile menu. :::image type="content" source="media/troubleshoot/choose-settings.png" alt-text="Screenshot of open profile, choose Settings."::: 2. Select **Applications** under **Integrations** > **Authorized OAuth Apps** > **Azure Boards**. -3. Under **Organization access**, resolve any issues that may appear. Select **Grant** to grant access to any organizations that show as having an **Access request pending**. +3. Under **Organization access**, resolve any issues that might appear. Select **Grant** to grant access to any organizations that show as having an **Access request pending**. :::image type="content" source="media/troubleshoot/organization-access-issues.png" alt-text="Screenshot of Organization access with organizations without access."::: -#### Resolve access issues +### Resolve access issues -When the Azure Boards connection to GitHub no longer has access, it shows an alert status in the user interface with a red-X. Hover over the alert and it indicates that the credentials are no longer valid. To correct the problem, remove the connection and recreate a new connection. +When the Azure Boards connection to GitHub loses access, an alert status with a red-X appears in the user interface. Hover over the alert to see that the credentials are no longer valid. To fix the issue, remove the connection and create a new one. :::image type="content" source="media/troubleshoot/failed-connection.png" alt-text="Screenshot of failed connection."::: @@ -341,47 +344,44 @@ To resolve this issue, consider the following items: Delete and recreate the connection to the GitHub repository. This recreated connection causes GitHub to prompt to reauthorize Azure Boards. - **If the connection is using a PAT:** - - The PAT may have been revoked or the required permission scopes changed and are insufficient. - - The user may have lost admin permissions on the GitHub repo. - - Recreate the PAT and ensure the scope for the token includes the required permissions: `repo, read:user, user:email, admin:repo_hook`. + - The PAT was revoked or the required permission scopes changed and are insufficient. + - The user might not have admin permissions on the GitHub repo. - + Recreate the PAT and ensure the scope for the token includes the required permissions: `repo, read:user, user:email, admin:repo_hook`. For more information, see [Best practices for using PATs](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#best-practices-for-using-pats). -#### Resolve broken GitHub Enterprise Server connection + -If you've migrated from Azure DevOps Server to Azure DevOps Services with an existing GitHub Enterprise Server connection, your existing connection won't work as expected. Work item mentions within GitHub may be delayed or never show up in Azure DevOps Services. This problem occurs because the callback url associated with GitHub is no longer valid. +### Resolve broken GitHub Enterprise Server connection +If you migrated from Azure DevOps Server to Azure DevOps Services with an existing GitHub Enterprise Server connection, your existing connection might not work as expected. Work item mentions within GitHub might be delayed or never appear in Azure DevOps Services because the callback URL associated with GitHub is no longer valid. Consider the following resolutions: - **Remove and re-create the connection**: Remove and re-create the connection to the GitHub Enterprise Server repository. Follow the sequence of steps provided in [Connect from Azure Boards](connect-to-github.md#github-ent-oauth-services) documentation. -- **Fix the webhook url**: - Go to GitHub's repository settings page and edit the webhook url to point out to the migrated Azure DevOps Services organization url: ```https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-preview``` - - +- **Fix the webhook URL**: + Go to GitHub's repository settings page and edit the webhook URL, pointing to the migrated Azure DevOps organization URL: ```https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-preview``` -#### Connect to multiple Azure DevOps organizations + -If you connect your GitHub repository to two or more projects that are defined in more than one Azure DevOps organization, such as dev.azure.com/Contoso and dev.azure.com/Fabrikam, you may get unexpected results when using **AB#** mentions to link to work items. This problem occurs because work item IDs aren't unique across Azure DevOps organizations, so **AB#12** can refer to a work item in either the Contoso or Fabrikam organization. So, when a work item is mentioned in a commit message or pull request, both organizations attempt to create a link to a work item with a matching ID (if one exists). +### Connect to multiple Azure DevOps organizations -In general, a user intends an **AB#** mention to link to a single work item in one of the projects. But, if a work item of the same ID exists in both accounts, then links get created for both work items, likely causing confusion. +When you connect your GitHub repository to projects in multiple Azure DevOps organizations, such as dev.azure.com/Contoso and dev.azure.com/Fabrikam, can cause unexpected results with **AB#** mentions. Work item IDs aren't unique across Azure DevOps organizations, so **AB#12** could refer to a work item in either Contoso or Fabrikam. When a work item is mentioned in a commit message or pull request, both organizations might attempt to link to a work item with the matching ID, causing confusion. -Currently, there's no way to work around this issue, so we recommend that you connect a single GitHub repository only to a single Azure DevOps organization. +To avoid this issue, connect a single GitHub repository to only one Azure DevOps organization. > [!NOTE] -> When you make the connection by using the Azure Boards app for GitHub, the app prevents you from connecting to two different organizations. If a GitHub repository is incorrectly connected to the wrong Azure DevOps organization, you must contact the owner of that organization to remove the connection before you can add the repository to the correct Azure DevOps organization. +> When you connect using the Azure Boards app for GitHub, the app prevents connections to multiple organizations. If a GitHub repository is connected to the wrong Azure DevOps organization, contact the owner of that organization to remove the connection before adding the repository to the correct Azure DevOps organization. - + -#### Update XML definitions for select work item types +### Update XML definitions for select work item types -If your organization uses the Hosted XML or On-premises XML process model to customize the work tracking experience and you want to link to and view the GitHub link types from the Development section in the work item forms, you'll need to update the XML definitions for the work item types. +Update the XML definitions for the work item types if your organization uses the Hosted XML or on-premises XML process model to customize the work tracking experience and link to and view the GitHub link types from the Development section in the work item forms. -For example, if you want to link user stories and bugs to GitHub commits and pull requests from the **Development** section, you need to update the XML definitions for user stories and bugs. +For example, to link user stories and bugs to GitHub commits and pull requests from the **Development** section, update the XML definitions for user stories and bugs. -Follow the sequence of tasks provided in [Hosted XML process model](../../organizations/settings/work/hosted-xml-process-model.md) to update the XML definitions. For each work item type, find the `Group Label="Development"` section, and add the following two lines in the following code syntax to support the external links types: **GitHub Commit** and **GitHub Pull Request**. +Follow the sequence of tasks provided in [Hosted XML process model](../../organizations/settings/work/hosted-xml-process-model.md) to update the XML definitions. For each work item type, find the `Group Label="Development"` section, and add the following two lines in the code syntax to support the external link types: **GitHub Commit** and **GitHub Pull Request**. > [!div class="tabbedCodeSnippets"] > ```XML @@ -389,7 +389,7 @@ Follow the sequence of tasks provided in [Hosted XML process model](../../organi > > ``` -When it's updated, the section should appear as follows. +After you update, the section should appear as follows. > [!div class="tabbedCodeSnippets"] > ```XML @@ -415,10 +415,26 @@ When it's updated, the section should appear as follows. > > ``` + + +## FAQs + +### Q: Some of my users in Azure DevOps have GitHub identities. Do I need to add them as new GitHub users to my organization? +A: No. Ask your users to sign out and then sign back in to the organization with their GitHub credentials from a fresh browser session. This action establishes their GitHub identities. + +### Q: I'm an organization Administrator and I enabled the policy for inviting GitHub users. Why can't I invite new GitHub users? +A: After changing the setting, sign out of Azure DevOps and then sign back in to the organization (`dev.azure.com/{organizationName}` or `organizationName.visualstudio.com`) with your GitHub credentials from a fresh browser session. + +### Q: I signed in with my GitHub credentials, but why can't I invite GitHub users? +A: Only organization or project Administrators can invite new users to join the organization. You might not have the required permissions to add new users. Work with your administrator to get the necessary permissions or ask them to add the user for you. + +### Q: Do GitHub Enterprise users get free access to Azure DevOps? +A: For more information, see [User and permissions management FAQs/GitHub Enterprise](../../organizations/accounts/faq-user-and-permissions-management.yml#github-enterprise). + ## Next steps > [!div class="nextstepaction"] -> [Link GitHub commits and pull requests to work items](link-to-from-github.md) +> [Link GitHub commits, pull requests, and branches to work items](link-to-from-github.md) ## Related articles @@ -427,4 +443,3 @@ When it's updated, the section should appear as follows. - [Troubleshoot GitHub & Azure Boards integration](troubleshoot-github-connection.md) - [Build GitHub repositories](../../pipelines/repos/github.md) - [Change GitHub repository access](install-github-app.md#change-repository-access) -- [Trigger an Azure Pipelines run from GitHub Actions](../../pipelines/ecosystems/github-actions.md) diff --git a/docs/boards/github/index.md b/docs/boards/github/index.md index 6c22eb8280f..97a0d64b153 100644 --- a/docs/boards/github/index.md +++ b/docs/boards/github/index.md @@ -7,11 +7,10 @@ ms.service: azure-devops-boards ms.topic: overview ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 06/19/2023 --- - # About Azure Boards-GitHub integration [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] @@ -20,10 +19,20 @@ Stay aligned and coordinated with Azure Boards and link your code activity and i ## Integrate Azure Boards and GitHub -:::moniker range=">= azure-devops-2022" +:::moniker range="> azure-devops-2022" +Azure Boards and Azure DevOps support integration with GitHub.com and GitHub Enterprise Server repositories. + +You can start from either Azure Boards or GitHub to integrate and connect up to 1,000 GitHub repositories to an Azure Boards project. + +- [Install and configure the Azure Boards app for GitHub](install-github-app.md) +- [Connect an Azure Boards project to one or more GitHub repositories](connect-to-github.md) + +:::moniker-end + +:::moniker range="= azure-devops-2022" Azure Boards and Azure DevOps support integration with GitHub.com and GitHub Enterprise Server repositories. -You can start from either Azure Boards or GitHub to integrate and connect up to 250 GitHub repositories to an Azure Boards project. +You can start from either Azure Boards or GitHub to integrate and connect up to 500 GitHub repositories to an Azure Boards project. - [Install and configure the Azure Boards app for GitHub](install-github-app.md) - [Connect an Azure Boards project to one or more GitHub repositories](connect-to-github.md) @@ -55,8 +64,8 @@ You can do the following tasks with Azure Boards-GitHub integration: - [Transition work items to a "Done" or "Completed" state with `fix`, `fixes`, or `fixed` in GitHub](link-to-from-github.md#use-ab-to-link-from-github-to-azure-boards-work-items). - [Post a comment to a GitHub commit, pull request, or issue when linked to a work item.](https://docs.github.com/en/get-started/quickstart/communicating-on-github) -- [Link from a work item to a GitHub commit, pull request, or issue](link-to-from-github.md#add-link-from-a-work-item-to-a-github-commit-pull-request-or-issue). -- [View GitHub objects on a Kanban board](link-to-from-github.md#view-github-objects-on-kanban-board). +- [Link from a work item to a GitHub commit, pull request, branch, or issue](link-to-from-github.md#link-work-item-to-branch-commit-pr). +- [View GitHub objects on a board](link-to-from-github.md#view-github-objects-on-board). - [Configure status badges](configure-status-badges.md) - [Manage GitHub repository access](install-github-app.md#change-repository-access) - [Troubleshoot Azure Boards-GitHub integration](connect-to-github.md#resolve-connection-issues) @@ -78,6 +87,5 @@ If you connect the same GitHub repo to projects defined in two or more Azure Dev - [Build GitHub repositories](../../pipelines/repos/github.md) - [Build GitHub Enterprise Server repositories](../../pipelines/repos/github-enterprise.md) -- [Trigger an Azure Pipelines run from GitHub Actions](../../pipelines/ecosystems/github-actions.md) - [What's Azure Boards?](../../boards/get-started/what-is-azure-boards.md) - [About work items](../work-items/about-work-items.md) diff --git a/docs/boards/github/install-github-app.md b/docs/boards/github/install-github-app.md index bde41115d09..5a544b4e2ac 100644 --- a/docs/boards/github/install-github-app.md +++ b/docs/boards/github/install-github-app.md @@ -6,8 +6,8 @@ ms.service: azure-devops-boards ms.topic: quickstart ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' -ms.date: 07/03/2023 +monikerRange: "<=azure-devops" +ms.date: 03/01/2024 --- # Install the Azure Boards app for GitHub @@ -20,34 +20,16 @@ For an overview of the integration that the Azure Boards app for GitHub supports ## Prerequisites -* To install the Azure Boards app, you must be an administrator or owner of the GitHub organization. -* To connect to the Azure Boards project, you must have read permission to the GitHub repository. Also, you must be a member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md). If you created the project, then you have permissions. +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - Member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md). If you created the project, you have permissions.
- **Administrator** or **owner** of the GitHub organization for installing the Azure Boards app.
- **Read** permissions for the GitHub repository. | +| **Project membership**| [Project member](../../organizations/projects/create-project.md). | > [!IMPORTANT] > If your repository is already connected via another authentication type such as OAuth, you must remove that repository from your existing connection before you re-connect it via the GitHub App. Follow the steps provided in [Add or remove GitHub repositories](#add-remove-repos) later in this article before you configure the GitHub App. > > You can connect an Azure DevOps organization to multiple GitHub repositories if you're an administrator for those repositories. However, you shouldn't connect a GitHub repository to more than one Azure DevOps organization. -## Give Azure Boards organization access - -Do the following steps to grant organization access. - -1. From the GitHub web portal, open **Settings** from your profile menu. - - :::image type="content" source="media/troubleshoot/choose-settings.png" alt-text="Screenshot of open profile, choose Settings."::: - -2. Select **Applications** under **Integrations**. - -3. Select **Authorized OAuth Apps** > **Azure Boards**. - - :::image type="content" source="media/troubleshoot/open-azure-boards.png" alt-text="Screenshot of Authorized OAuth Apps tab, choose Azure Boards."::: - -4. Under **Organization access**, resolve any issues that may appear. Select **Grant** to grant access to any organizations that show as having an **Access request pending**. - - :::image type="content" source="media/troubleshoot/organization-access-issues.png" alt-text="Screenshot of Organization access with organizations without access."::: - - - ## Install and configure the Azure Boards app 1. Go to the Azure Boards app in the [GitHub Marketplace](https://github.com/marketplace/azure-boards). @@ -56,23 +38,23 @@ Do the following steps to grant organization access. :::image type="content" source="media/github-app/install-azure-boards-app-from-marketplace.png" alt-text="Screenshot of GitHub Marketplace, Set up a plan button."::: -3. Choose the GitHub organization you want to connect to Azure Boards. +3. Choose the GitHub organization you want to connect to Azure Boards. :::image type="content" source="media/github-app/choose-github-account.png" alt-text="Screenshot showing Install Azure Boards dialog."::: 4. Choose the repositories that you want to connect to Azure Boards. - Here we choose to connect to all repositories. + In the following example, we choose to connect to all repositories. :::image type="content" source="media/github-app/install-options.png" alt-text="Screenshot showing all repositories selected."::: 5. Choose the Azure DevOps organization and Azure Boards project you want to connect to GitHub.com. - :::image type="content" source="media/github-app/choose-azure-boards-project.png" alt-text="Screenshot of Setup your Azure Boards project dialog."::: + :::image type="content" source="media/github-app/choose-azure-boards-project.png" alt-text="Screenshot of setting up connection dialog."::: You can only connect one project at a time. If you have other projects you want to connect, you can do that later as described in [Configure other projects or repositories](#configure) later in this article. -6. Authorize your Azure Boards organization to connect with GitHub.com. +6. To connect with GitHub.com, authorize your Azure Boards organization. :::image type="content" source="media/github-app/authorize-azure-boards.png" alt-text="Screenshot of Azure Boards authorization dialog."::: @@ -80,55 +62,72 @@ Do the following steps to grant organization access. :::image type="content" source="media/github-app/confirm-github-repos.png" alt-text="Screenshot of Confirm your GitHub repositories dialog."::: - + -## Use the connection +## Give Azure Boards organization access -At this point, your Azure Boards-GitHub integration is complete. You can skip the next steps or run through them to understand the features supported with the connection. +To grant GitHub access to your Azure DevOps organization, do the following steps. -1. Select **Create** to add a work item—Issue (Basic), User Story (Agile), or Product Backlog Item (Scrum)—depending on the process model used by your Azure Boards project. +1. From the GitHub web portal, open **Settings** from your profile menu. - :::image type="content" source="media/github-app/get-started-success.png" alt-text="Screenshot of the Get started, Create issue dialog."::: + :::image type="content" source="media/troubleshoot/choose-settings.png" alt-text="Screenshot of open profile, choose Settings."::: + +2. Select **Applications** under **Integrations**. - A work item titled *Add badge to README* appears on your Azure Boards. +3. Select **Authorized GitHub Apps** > **Azure Boards**. -2. Select **Create and link a pull request**. + :::image type="content" source="media/troubleshoot/open-azure-boards.png" alt-text="Screenshot of Authorized OAuth Apps tab, choose Azure Boards."::: - :::image type="content" source="media/github-app/get-started-issue-created.png" alt-text="Success screenshot, GitHub repo is connected to Azure Boards."::: +4. Under **Organization access**, resolve any issues that might appear. Select **Grant** to grant access to any organizations that show as having an **Access request pending**. - This step runs the following actions in the background: - - Adds a badge to the README file of the first repository in the list of connected GitHub repositories - - Creates a GitHub commit for the update made by adding the badge to the README file - - Creates a GitHub pull request to merge the changes made to the README file - - Links the GitHub commit and pull request to the work item created in step 1. + :::image type="content" source="media/troubleshoot/organization-access-issues.png" alt-text="Screenshot of Organization access with organizations without access."::: + + + +## Use the connection + +At this point, your Azure Boards-GitHub integration is complete. You can skip the next steps or go through them to understand the features supported with the connection. + +1. On your board, select **New work item** to enter a new work item named "Add badge to README"—Issue (Basic), User Story (Agile), or Product Backlog Item (Scrum)—depending on the process model used by your Azure Boards project. + + A work item titled *Add badge to README* appears on your board. -3. Select **View work item** to open the work item you created in step 1. Note the links under the **Development** section that correspond to the commit and pull request created in GitHub.com +2. Open your work item, go to the **Development** section, and select **Add link**. +3. Select **GitHub Pull Request** from the **Link type** dropdown menu. +4. Select the repository and enter the pull request ID and an optional comment. +5. Select **Add link**. - :::image type="content" source="media/github-app/get-started-view-work-item.png" alt-text="Screenshot of viewing work item."::: + :::image type="content" source="media/troubleshoot/add-link-to-pull-request-2.png" alt-text="Screenshot of Add link action in user story, showing repository selection and empty boxes for input of pull request ID and optional comment."::: -4. Choose the pull request link, the first link in the list, to open the pull request in GitHub. + The following actions occur in the background, automatically: + - Adds a badge to the README file of the first repository in the list of connected GitHub repositories. + - Creates a GitHub commit for the update made by adding the badge to the README file. + - Creates a GitHub pull request to merge the changes made to the README file. + - Links the GitHub commit and pull request to the work item created in step 1. + +6. Select the first pull request link from your work item. - The GitHub pull request opens in a new browser tab. + :::image type="content" source="media/github-app/issue-add-badge.png" alt-text="Screenshot of issue form for pull request opened in GitHub."::: - :::image type="content" source="media/github-app/issue-add-badge.png" alt-text="Screenshot of issue form."::: + The GitHub pull request opens in a new browser tab. -5. Complete the pull request. +7. Select **Merge pull request**. - :::image type="content" source="media/github-app/git-hub-pr-for-badge-b.png" alt-text="Screenshot of example PR."::: + :::image type="content" source="media/github-app/git-hub-pr-for-badge-b.png" alt-text="Screenshot of example pull request in GitHub."::: -6. Go to your repository README file and view the badge that was added. +8. Go to your repository README file and view the badge that was added. :::image type="content" source="media/github-app/readme-file-with-badge.png" alt-text="Screenshot of GitHub repo with badge added."::: For more information, see [Configure status badges to add to GitHub README files](configure-status-badges.md). - + ## Configure other projects or repositories You can configure other Azure Boards/Azure DevOps Projects, GitHub.com repositories, or change the current configuration from the Azure Boards app page. For more information, see [Change GitHub repository access, or suspend or uninstall the integration](install-github-app.md#add-remove-repos). - + ## Add or remove repositories, or remove a connection from Azure Boards @@ -136,48 +135,38 @@ If you encounter a problem with a connection, we recommend that you remove the c ::: moniker range=">= azure-devops-2020" -1. To add or remove repositories, choose :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More options** for the connection and choose **Add repositories** or **Remove repositories** from the menu. - - :::image type="content" source="media/connect-cloud/connection-menu.png" alt-text="Screenshot of GitHub connection menu of More options."::: - -2. To remove all repositories and the connection, choose the **Remove connection** option. Then, choose **Remove** to confirm. - - :::image type="content" source="media/github/remove-connection-confirmation.png" alt-text="Screenshot of confirmation removal of GitHub connection."::: +1. From your project in Azure DevOps, go to **Project settings** > **GitHub connections**. -::: moniker-end +2. To add or remove repositories, select the **More options** ellipses for the connection and choose **Add repositories** or **Remove repositories** from the menu. -::: moniker range="azure-devops-2019" + :::image type="content" source="media/connect-cloud/connection-menu.png" alt-text="Screenshot of GitHub connection menu of More options."::: -1. To add or remove repositories, open the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the connection and choose **Add** repositories or **Remove repositories** from the menu. +3. To remove all repositories and the connection, choose the **Remove connection** option. Then, choose **Remove** to confirm. - :::image type="content" source="media/github/repo-actions-menu.png" alt-text="Screenshot of add or remove GitHub repos."::: - -2. To remove all repositories and the connection, choose the **Remove connection** option. Then, choose **Remove** to confirm. + :::image type="content" source="media/github/remove-connection-confirmation.png" alt-text="Screenshot of confirmation removal of GitHub connection."::: - :::image type="content" source="media/github/remove-connection-confirmation.png" alt-text="Screenshot of confirmation of GitHub connection removal dialog."::: - ::: moniker-end ## Change repository access -1. Sign into the web portal for your GitHub organization and open **Account settings**. +1. Sign into GitHub and open your organization profile settings. `https://github.com/organizations/fabrikam-fiber/settings/profile` -1. Choose **Installed GitHub Apps** and then **Configure** next to **Azure Boards**. +2. Go to **Installed GitHub Apps** > **Azure Boards** > **Configure**. :::image type="content" source="media/change-repo-access/open-installed-github-apps.png" alt-text="Screenshot of open Organization account, Installed GitHub Apps, Azure Boards, Configure."::: The Azure Boards configuration page opens. -1. Scroll down to the **Repository access** section. +3. Scroll down to the **Repository access** section. -1. Choose the option you want, **All repositories** or **Only select repositories**. +4. Choose the option you want, **All repositories** or **Only select repositories**. If you choose **Only select repositories**, select the repositories you want to participate in integration with Azure Boards. :::image type="content" source="media/change-repo-access/choose-repositories.png" alt-text="Screenshot of Repository access, choose Only select repositories."::: -1. Choose **Save** when you're done. +5. Select **Save**. ## Suspend or uninstall Azure Boards integration @@ -197,20 +186,20 @@ If you encounter a problem with a connection, we recommend that you remove the c ## Update Azure Boards-GitHub connections -If you change the repositories that the Azure Boards app for GitHub supports, you may be redirected to Azure Boards GitHub connections. A good practice is to remove the repositories in Azure Boards that can no longer connect to GitHub. For more information, see [Add or remove GitHub repositories](#add-remove-repos). +If you change the repositories that the Azure Boards app for GitHub supports, you might get redirected to Azure Boards GitHub connections. A good practice is to remove the repositories in Azure Boards that can no longer connect to GitHub. For more information, see [Add or remove GitHub repositories](#add-remove-repos). -If you uninstall the Azure Boards app for GitHub, you'll see the following message in Azure Boards, **Project Settings>GitHub** Connections. Choose **Remove connection** to remove all GitHub connections that have been previously made. See also, [Add or remove GitHub repositories](#add-remove-repos). +If you uninstall the Azure Boards app for GitHub, the following message displays in Azure Boards, **Project settings** > **GitHub** connections. Choose **Remove connection** to remove all previously made GitHub connections. For more information, see [Add/remove GitHub repositories](#add-remove-repos). :::image type="content" source="media/change-repo-access/boards-remove-connection.png" alt-text="Screenshot of uninstalled Azure Boards GitHub app."::: ## Next steps > [!div class="nextstepaction"] -> [Link GitHub commits and pull requests to work items](link-to-from-github.md) +> [Link GitHub commits, pull requests, and branches to work items](link-to-from-github.md) ## Related articles - [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md) - [Change GitHub repository access, or suspend or uninstall the integration](change-azure-boards-app-github-repository-access.md) - [Configure status badges to add to GitHub README files](configure-status-badges.md) - \ No newline at end of file + diff --git a/docs/boards/github/link-to-from-github.md b/docs/boards/github/link-to-from-github.md index dcfe803e4b0..51cd935b4c7 100644 --- a/docs/boards/github/link-to-from-github.md +++ b/docs/boards/github/link-to-from-github.md @@ -1,28 +1,30 @@ --- -title: Link GitHub commits, PRs, and issues to work items +title: Link GitHub commits, PRs, branches, and issues to work items titleSuffix: Azure Boards -description: Learn how to links work items to GitHub commits, pull requests, and issues, and automatically transition work item states in Azure Boards. +description: Learn how to links work items to GitHub commits, pull requests, branches, and issues, and automatically transition work item states in Azure Boards. ms.service: azure-devops-boards ms.custom: work-items, github, engagement-fy23 ms.author: chcomley author: chcomley ms.topic: quickstart -monikerRange: '>= azure-devops-2019' -ms.date: 07/03/2023 +monikerRange: "<=azure-devops" +ms.date: 10/02/2024 --- -# Link GitHub commits, pull requests, and issues to work items in Azure Boards +# Link GitHub commits, pull requests, branches, and issues to work items in Azure Boards [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Once you connect your Azure Boards project with a GitHub repository, you can link work items to your GitHub commits and pull requests. You can add links using the **#mention** syntax familiar to GitHub users or you can add a GitHub commit or GitHub pull request link type from the Azure Boards work item. +In this article, learn how to link work items to GitHub commits, pull requests, and branches after connecting your Azure Boards project with a GitHub repository. You can use the **#mention** syntax for commits and branches or add a GitHub commit, pull request, or branch link directly from the Azure Boards work item. [!INCLUDE[temp](../includes/github-platform-support.md)] ## Prerequisites -* Your Azure Boards project must be connected to the GitHub repository where the commits and pull requests you want to link to/from exist. For more information, see [Azure Boards-GitHub integration](index.md). -* You must be a Contributor to Azure Boards project and to the GitHub repository. +| Category | Requirements | +|--------------|-------------| +| **Permissions** | **Contributor** to both the Azure Boards project and the GitHub repository. | +| **Project connection** | Azure Boards project is connected to the GitHub repository where the commits, pull requests, and branch you want to link to or from exist. For more information, see [Azure Boards-GitHub integration](index.md). | ::: moniker range="azure-devops" > [!NOTE] @@ -31,22 +33,17 @@ Once you connect your Azure Boards project with a GitHub repository, you can lin ## Use `AB#` to link from GitHub to Azure Boards work items -From a GitHub commit, pull request or issue, use the following syntax to create a link to your Azure Boards work item. Enter the `AB#ID` within the text of a commit message. Or, for a pull request or issue, enter the `AB#ID` within the title or description (not a comment). - -::: moniker range="azure-devops-2019" -> [!NOTE] -> Linking to GitHub issues requires Azure DevOps Server 2019 Update 1 or later version. -::: moniker-end +From a GitHub commit, pull request or issue, use the following syntax to create a link to your Azure Boards work item. Enter the `AB#ID` within the text of a commit message. Or, for a pull request or issue, enter the `AB#ID` within the title or description. Using `AB#ID` in a comment doesn't create a link on the work item. ``` AB#{ID} ``` -For example, `AB#125` links to work item ID 125. +For example, `AB#125` links to work item ID 125. -You can also enter a commit or pull request message to transition the work item. The system recognizes `fix, fixes, fixed` and applies it to the #-mention item that follows. Mentioned work items transition to the first **State** associated with the *Resolved* workflow category state. If there's no **State** associated with *Resolved*, then it transitions to the **State** associated with the *Completed* workflow category state. To understand how workflow states and category states are mapped, see [How workflow category states are used in Azure Boards backlogs and boards](../work-items/workflow-and-state-categories.md). +You can also enter a commit or pull request message to transition the work item. The system recognizes `fix`, `fixes`, and `fixed`, and applies it to the #-mention item that follows. Mentioned work items transition to the first **State** associated with the *Resolved* workflow category state. If no **State** is associated with *Resolved*, the work item transitions to the **State** associated with the *Completed* workflow category state. For more information, see [How workflow category states are used in Azure Boards backlogs and boards](../work-items/workflow-and-state-categories.md). -See the following table of examples. +Review the following table of examples: | Commit or pull request message | Action | | :------------------------------------------ | :----------------------------------------------- | @@ -57,41 +54,65 @@ See the following table of examples. | `Fixing multiple bugs: issue #123 and user story AB#234` | Links to GitHub issue 123 and Azure Boards work item 234. No transitions are made. | > [!NOTE] -> If you connected the same GitHub repo to projects defined in two or more Azure DevOps organizations, you may see unexpected **AB#** mention linking. For more information, see [Resolve connection issues](connect-to-github.md#resolve-connection-issues). For this reason, we recommend that you only connect a GitHub repo to projects defined in a single Azure DevOps organization. +> If you connected the same GitHub repo to projects defined in two or more Azure DevOps organizations, you might see unexpected **AB#** mention linking. For more information, see [Resolve connection issues](connect-to-github.md#resolve-connection-issues). For this reason, we recommend that you only connect a GitHub repo to projects defined in a single Azure DevOps organization. - + -::: moniker range=">= azure-devops-2019" +When you add a link to a work item using AB#, those links appear in the **Development** section of the pull request. -## Add link from a work item to a GitHub commit, pull request, or issue +:::image type="content" source="media/github/ab-links-development-control.png" alt-text="Screenshot of AB# links on the development section of GitHub pull request."::: -::: moniker-end -::: moniker range="azure-devops-2019" +## Create GitHub branch from work item -> [!NOTE] -> Linking to a GitHub issue requires Azure DevOps Server 2019 Update 1 or later version. -::: moniker-end +To create a GitHub branch directly from a work item, do these steps: + +1. From your board, find the work item from which you want to create a GitHub branch. + +2. Select :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: **Work item actions** > **New GitHub branch**. + + :::image type="content" source="media/link/create-github-branch-work-item-action.png" alt-text="Screenshot of work item More actions select and highlighted New GitHub branch option."::: + +3. In the **Create a GitHub branch** dialog, enter the branch name, and select the GitHub repository and base branch. + +4. Select **Create**. + + :::image type="content" source="media/link/create-github-branch-dialog.png" alt-text="Screenshot of Create a GitHub Branch dialog."::: + + Azure Boards creates the branch in the specified GitHub repository and links it to the work item. For more information, see [Azure Boards-GitHub integration](index.md). -::: moniker range=">= azure-devops-2019" + -1. To link to a commit or pull request, open the work item and choose **Add link** under the Development section. +## Add work item link to GitHub branch, commit, or pull request - > [!div class="mx-imgBorder"] - > ![Screenshot of work item form, Development section, Add link option.](media/link/add-link-development-github.png) +1. Open the work item and go to the **Links** tab. - To link to an issue, choose the **Links** tab, and then choose **Add Link>Existing item**. + :::image type="content" source="media/link/add-link-from-links-tab.png" alt-text="Screenshot of work item form, Links tab, Add link to issue."::: - :::image type="content" source="media/link/add-link-from-links-tab.png" alt-text="Screenshot of work item form, Links tab, Add link to issue."::: +2. From the **Add link** dialog, select one of the **GitHub** link types, select a GitHub repository, enter the URL to the GitHub branch, commit, or pull request, and then select **Add link**. -2. From the **Add link** dialog, select one of the **GitHub** link types, enter the URL to the commit, pull request, or issue and then choose **OK**. - Here, we add a link to a GitHub pull request. + In the following example, we add a link to a GitHub pull request. - :::image type="content" source="media/link/link-from-azb-gh-pull-requests.png" alt-text="Screenshot of work item form, Links tab, Add link dialog, GitHub pull request link type selected."::: + :::image type="content" source="media/link/link-from-azb-gh-pull-requests.png" alt-text="Screenshot of work item form, Links tab, Add link dialog, GitHub pull request link type selected."::: - Azure Boards completes a check to ensure that you've entered a valid link. The linked-to GitHub repository [must be connected to the Azure Boards project](connect-to-github.md) or the validation fails. + Azure Boards completes a check to ensure that you entered a valid link. The linked-to GitHub repository [must be connected to the Azure Boards project](connect-to-github.md) or the validation fails. + +::: moniker range="<= azure-devops-2022" + +> [!NOTE] +> There's a delay when completing the AB# links if you are using Azure DevOps Server and GitHub Enterprise Server. We have a 'push-and-pull' design to pull from the GitHub events every hour on the incremental changes on Commit, PR, and Issue. ::: moniker-end +## Automatic link updates + +Several events automatically update the links on the work item form, so you don’t need to create them manually. These include: + +| GitHub event | Action | +| :----------------- | :----------------------------------------------------------- | +| **Link to branch** | When a pull request is created from a branch, it is automatically linked to the work item. | +| **Merge commit** | After the pull request is merged, the resulting merge commit is automatically linked to the work item. | +| **Delete branch** | If the branch is deleted (typically after merging), its link is automatically removed from the work item. | + ## View or open links from the Development section The Development section within the work item form lists the links created to GitHub commits and pull requests with the :::image type="icon" source="../../media/icons/github.png" border="false"::: GitHub icon. @@ -100,18 +121,13 @@ The Development section within the work item form lists the links created to Git Choose the link provided to open the commit or pull request in GitHub. -## View GitHub objects on Kanban board + -With GitHub annotations enabled on the Kanban board, you can quickly open linked GitHub commits, pull requests, or issues for more detail. For more information, see [Customize cards](../boards/customize-cards.md). +## View GitHub objects on a board -:::image type="content" source="media/link/board-view-github-links.png" alt-text="Screenshot of Kanban board that shows GitHub links on work item cards."::: +With GitHub annotations enabled on the board, you can quickly open linked GitHub commits, pull requests, or issues for more detail. For more information, see [Customize cards](../boards/customize-cards.md). -::: moniker range="azure-devops-2019" - -> [!NOTE] -> GitHub annotations requires Azure DevOps Server 2019 Update 1 or later version. - -::: moniker-end +:::image type="content" source="media/link/board-view-github-links.png" alt-text="Screenshot of board that shows GitHub links on work item cards."::: ## Next steps @@ -120,11 +136,7 @@ With GitHub annotations enabled on the Kanban board, you can quickly open linked ## Related articles -- [Add or remove repositories](install-github-app.md#add-or-remove-repositories-or-remove-a-connection-from-azure-boards) -- [Change GitHub repository access](install-github-app.md#change-repository-access) -- [Azure Boards-GitHub integration](index.md) -- [How workflow category states are used in Azure Boards backlogs and boards](../work-items/workflow-and-state-categories.md) -- [Linking, traceability, and managing dependencies](../queries/link-work-items-support-traceability.md) -- [Troubleshoot GitHub & Azure Boards integration](troubleshoot-github-connection.md) - - +- [Integrate Azure Boards with GitHub](index.md) +- [Understand how workflow category states are used in Azure Boards backlogs and boards](../work-items/workflow-and-state-categories.md) +- [Link work items to objects](../backlogs/add-link.md) +- [Troubleshoot GitHub and Azure Boards integration](troubleshoot-github-connection.md) diff --git a/docs/boards/github/media/badges/badge-status-all-columns.png b/docs/boards/github/media/badges/badge-status-all-columns.png deleted file mode 100644 index f46cf1f6809..00000000000 Binary files a/docs/boards/github/media/badges/badge-status-all-columns.png and /dev/null differ diff --git a/docs/boards/github/media/badges/badge-syntax.png b/docs/boards/github/media/badges/badge-syntax.png deleted file mode 100644 index 43c3da27ec5..00000000000 Binary files a/docs/boards/github/media/badges/badge-syntax.png and /dev/null differ diff --git a/docs/boards/github/media/badges/status-badge-s188.png b/docs/boards/github/media/badges/status-badge-s188.png index 3c6f57f4085..4dc07458cd7 100644 Binary files a/docs/boards/github/media/badges/status-badge-s188.png and b/docs/boards/github/media/badges/status-badge-s188.png differ diff --git a/docs/boards/github/media/connect-cloud/new-github-enterprise-server-dialog-user-name.png b/docs/boards/github/media/connect-cloud/new-github-enterprise-server-dialog-user-name.png index 9fdd98ab4f4..72d428b6125 100644 Binary files a/docs/boards/github/media/connect-cloud/new-github-enterprise-server-dialog-user-name.png and b/docs/boards/github/media/connect-cloud/new-github-enterprise-server-dialog-user-name.png differ diff --git a/docs/boards/github/media/connect-cloud/open-oauth-configuration.png b/docs/boards/github/media/connect-cloud/open-oauth-configuration.png index 0356e72eb0d..3e90fd28d04 100644 Binary files a/docs/boards/github/media/connect-cloud/open-oauth-configuration.png and b/docs/boards/github/media/connect-cloud/open-oauth-configuration.png differ diff --git a/docs/boards/github/media/connect-cloud/register-oauth-azure-devops.png b/docs/boards/github/media/connect-cloud/register-oauth-azure-devops.png index c68b874b0a0..ead4a07b477 100644 Binary files a/docs/boards/github/media/connect-cloud/register-oauth-azure-devops.png and b/docs/boards/github/media/connect-cloud/register-oauth-azure-devops.png differ diff --git a/docs/boards/github/media/github-ent/add-oauth-configuration-organization.png b/docs/boards/github/media/github-ent/add-oauth-configuration-organization.png deleted file mode 100644 index e93aa3ff7cd..00000000000 Binary files a/docs/boards/github/media/github-ent/add-oauth-configuration-organization.png and /dev/null differ diff --git a/docs/boards/github/media/github-ent/add-oauth-configuration.png b/docs/boards/github/media/github-ent/add-oauth-configuration.png index 9c8ab5762f1..5305d7ec967 100644 Binary files a/docs/boards/github/media/github-ent/add-oauth-configuration.png and b/docs/boards/github/media/github-ent/add-oauth-configuration.png differ diff --git a/docs/boards/github/media/github-ent/ads-add-ghe-pat.png b/docs/boards/github/media/github-ent/ads-add-ghe-pat.png index dfc1d11fea9..deeeac65ed4 100644 Binary files a/docs/boards/github/media/github-ent/ads-add-ghe-pat.png and b/docs/boards/github/media/github-ent/ads-add-ghe-pat.png differ diff --git a/docs/boards/github/media/github-ent/ads-add-ghe-repositories.png b/docs/boards/github/media/github-ent/ads-add-ghe-repositories.png index dda6fe8d202..6b25ce9b18d 100644 Binary files a/docs/boards/github/media/github-ent/ads-add-ghe-repositories.png and b/docs/boards/github/media/github-ent/ads-add-ghe-repositories.png differ diff --git a/docs/boards/github/media/github-ent/ads-add-ghe-user-name.png b/docs/boards/github/media/github-ent/ads-add-ghe-user-name.png index 847e8d8b8ed..09051f4edda 100644 Binary files a/docs/boards/github/media/github-ent/ads-add-ghe-user-name.png and b/docs/boards/github/media/github-ent/ads-add-ghe-user-name.png differ diff --git a/docs/boards/github/media/github-ent/app-tier-find-public-url.png b/docs/boards/github/media/github-ent/app-tier-find-public-url.png index e345c9ce140..7f802017c1c 100644 Binary files a/docs/boards/github/media/github-ent/app-tier-find-public-url.png and b/docs/boards/github/media/github-ent/app-tier-find-public-url.png differ diff --git a/docs/boards/github/media/github-ent/ghe-register-app-success.png b/docs/boards/github/media/github-ent/ghe-register-app-success.png index a98285eb8e9..c26b9c1edd9 100644 Binary files a/docs/boards/github/media/github-ent/ghe-register-app-success.png and b/docs/boards/github/media/github-ent/ghe-register-app-success.png differ diff --git a/docs/boards/github/media/github-ent/sign-in-to-ghe.png b/docs/boards/github/media/github-ent/sign-in-to-ghe.png index a2d762e9908..9d5658881cc 100644 Binary files a/docs/boards/github/media/github-ent/sign-in-to-ghe.png and b/docs/boards/github/media/github-ent/sign-in-to-ghe.png differ diff --git a/docs/boards/github/media/github/ab-links-development-control.png b/docs/boards/github/media/github/ab-links-development-control.png new file mode 100644 index 00000000000..86f73af0cf3 Binary files /dev/null and b/docs/boards/github/media/github/ab-links-development-control.png differ diff --git a/docs/boards/github/media/github/github-dialog-sign-in.png b/docs/boards/github/media/github/github-dialog-sign-in.png deleted file mode 100644 index 22afe0a5a4f..00000000000 Binary files a/docs/boards/github/media/github/github-dialog-sign-in.png and /dev/null differ diff --git a/docs/boards/github/media/link/add-link-development-github.png b/docs/boards/github/media/link/add-link-development-github.png index 4d2698dc364..3be22cd12b7 100644 Binary files a/docs/boards/github/media/link/add-link-development-github.png and b/docs/boards/github/media/link/add-link-development-github.png differ diff --git a/docs/boards/github/media/link/add-link-from-links-tab.png b/docs/boards/github/media/link/add-link-from-links-tab.png index 7a8bae473fb..6a6ed946ff6 100644 Binary files a/docs/boards/github/media/link/add-link-from-links-tab.png and b/docs/boards/github/media/link/add-link-from-links-tab.png differ diff --git a/docs/boards/github/media/link/create-github-branch-dialog.png b/docs/boards/github/media/link/create-github-branch-dialog.png new file mode 100644 index 00000000000..fbe1ccce2fd Binary files /dev/null and b/docs/boards/github/media/link/create-github-branch-dialog.png differ diff --git a/docs/boards/github/media/link/create-github-branch-work-item-action.png b/docs/boards/github/media/link/create-github-branch-work-item-action.png new file mode 100644 index 00000000000..0aaa9fd61f9 Binary files /dev/null and b/docs/boards/github/media/link/create-github-branch-work-item-action.png differ diff --git a/docs/boards/github/media/link/link-from-azb-gh-pull-requests.png b/docs/boards/github/media/link/link-from-azb-gh-pull-requests.png index 14f9351be97..6218e4ac247 100644 Binary files a/docs/boards/github/media/link/link-from-azb-gh-pull-requests.png and b/docs/boards/github/media/link/link-from-azb-gh-pull-requests.png differ diff --git a/docs/boards/github/media/troubleshoot/add-link-to-pull-request-2.png b/docs/boards/github/media/troubleshoot/add-link-to-pull-request-2.png new file mode 100644 index 00000000000..1e5e64baf4e Binary files /dev/null and b/docs/boards/github/media/troubleshoot/add-link-to-pull-request-2.png differ diff --git a/docs/boards/github/media/troubleshoot/add-link-to-pull-request.png b/docs/boards/github/media/troubleshoot/add-link-to-pull-request.png new file mode 100644 index 00000000000..12917680637 Binary files /dev/null and b/docs/boards/github/media/troubleshoot/add-link-to-pull-request.png differ diff --git a/docs/boards/github/media/troubleshoot/choose-settings.png b/docs/boards/github/media/troubleshoot/choose-settings.png index 0944bc47e14..0be065c2f1d 100644 Binary files a/docs/boards/github/media/troubleshoot/choose-settings.png and b/docs/boards/github/media/troubleshoot/choose-settings.png differ diff --git a/docs/boards/github/media/troubleshoot/open-azure-boards.png b/docs/boards/github/media/troubleshoot/open-azure-boards.png index 55c8d2ba792..20eb792ce45 100644 Binary files a/docs/boards/github/media/troubleshoot/open-azure-boards.png and b/docs/boards/github/media/troubleshoot/open-azure-boards.png differ diff --git a/docs/boards/github/media/troubleshoot/organization-access.png b/docs/boards/github/media/troubleshoot/organization-access.png deleted file mode 100644 index e43a4ea4a07..00000000000 Binary files a/docs/boards/github/media/troubleshoot/organization-access.png and /dev/null differ diff --git a/docs/boards/github/toc.yml b/docs/boards/github/toc.yml index c47d54c3199..474c66df630 100644 --- a/docs/boards/github/toc.yml +++ b/docs/boards/github/toc.yml @@ -6,9 +6,9 @@ href: connect-to-github.md - name: Connect Azure Boards (on-premises) href: connect-on-premises-to-github.md -- name: Link GitHub commits, pull requests, & issues +- name: Link GitHub commits, pull requests, & branches href: link-to-from-github.md -- name: Configure status badges +- name: Add status badges href: configure-status-badges.md - name: Enable DevSecOps with Azure and GitHub - href: /devops/devsecops/enable-devsecops-azure-github \ No newline at end of file + href: /devops/devsecops/enable-devsecops-azure-github diff --git a/docs/boards/includes/activated-resolved-by-fields.md b/docs/boards/includes/activated-resolved-by-fields.md index 7feacc794cd..90d753301cb 100644 --- a/docs/boards/includes/activated-resolved-by-fields.md +++ b/docs/boards/includes/activated-resolved-by-fields.md @@ -6,7 +6,7 @@ ms.topic: include ms.date: 04/04/2023 --- - + ::: moniker range=">= azure-devops-2020" diff --git a/docs/boards/includes/add-portfolio-backlogs.md b/docs/boards/includes/add-portfolio-backlogs.md index bfb7c980380..e6bba6074a3 100644 --- a/docs/boards/includes/add-portfolio-backlogs.md +++ b/docs/boards/includes/add-portfolio-backlogs.md @@ -3,23 +3,20 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 07/09/2020 +ms.date: 08/01/2023 --- - -## Add portfolio backlog levels and boards - -If you need more than two portfolio backlogs, you can add up to two more for a total of five backlog levels. +## Add portfolio backlogs and boards ::: moniker range="azure-devops" -You can add them by customizing your process, adding new work item types, and then configuring your backlogs and boards. You can also add or modify the fields defined for a work item type (WIT) or add a custom WIT. For more information, see [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md) and [Customize your backlogs or boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md). +To add a portfolio backlog or board, customize your process, add new work item types, and then configuring your backlogs and boards. You can also add or modify the fields defined for a work item type (WIT) or add a custom WIT. For more information, see [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md) and [Customize your backlogs or boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md). ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="' --type '' [--area] [--assigned-to] [--description] @@ -33,7 +32,7 @@ az boards work-item create --title #### Optional parameters - **area**: Area the work item is assigned to (for example, *Demos*). -- **assigned-to**: Name of the person the work item is assigned-to (for example, *fabrikam*). +- **assigned-to**: The email address of the person the work item is assigned-to (for example, fabrikamfiber-3@fabrikamfiber.com). - **description**: Description of the work item. - **discussion**: Comment to add to a discussion in a work item. - **fields**: Space separated `field=value` pairs for custom fields you would like to set. diff --git a/docs/boards/includes/assign-to-sprint.md b/docs/boards/includes/assign-to-sprint.md index ad2a75d18a3..f12f42408a1 100644 --- a/docs/boards/includes/assign-to-sprint.md +++ b/docs/boards/includes/assign-to-sprint.md @@ -6,32 +6,19 @@ ms.topic: include ## Move work items to a sprint -::: moniker range=">= azure-devops-2019" -From any product, sprint, or portfolio backlog, you can drag a multi-selected list of work items and drop it onto a sprint in the **Planning** pane to change it's iteration path. (Not supported for users with **Stakeholder** access.) +::: moniker range="<=azure-devops" +From any product, sprint, or portfolio backlog, you can drag a multi-selected list of work items and drop it onto a sprint in the **Planning** pane to change its iteration path. This action is not supported for users with **Stakeholder** access. -1. To open the **Planning** pane, choose the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: view options icon and select **Planning**. You can choose to set **In Progress items** to On or Off. +1. To open the **Planning** pane, choose the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: view options icon and select **Planning**. You can choose to set **In Progress items** to **On** or **Off**. - > [!div class="mx-imgBorder"] - > ![Boards>Backlogs>Open view options and choose Planning](../sprints/media/define-sprints/view-options-planning-menu.png) + :::image type="content" source="../sprints/media/define-sprints/view-options-planning-menu.png" alt-text="Screenshot of the Backlogs Open view options with Planning selected."::: - The set of sprints selected for your team appears. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Define sprints](../sprints/define-sprints.md). + The set of sprints selected for your team appears. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Manage sprint timelines](../sprints/define-sprints.md). -1. You can drag and drop items from the **Backlog** onto a sprint. - > [!div class="mx-imgBorder"] - > ![Boards>Backlogs>Drag-drop items onto sprint](../sprints/media/define-sprints/drag-drop-backlog-items-to-sprint.png) +1. You can drag items from the **Backlog** onto a sprint. - This action updates the Iteration Path of the backlog items and any of its child tasks to the sprint you selected. + :::image type="content" source="../sprints/media/define-sprints/drag-drop-backlog-items-to-sprint.png" alt-text="Screenshot of the Backlog where you can drag items to a sprint."::: -::: moniker-end - - -::: moniker range="tfs-2018" - -From any backlog or board, you can drag a multi-selected list of work items and drop it onto a sprint to change it's iteration path. From a Kanban or taskboard, you can drag a single work item onto a sprint. (Not supported for users with **Stakeholder** access.) - -> [!div class="mx-imgBorder"] -> ![Drop work items onto a sprint](../sprints/media/sp-assign-to-sprints.png) - -Child items of the work items whose iteration path you change are also updated with the new iteration path. + This action updates the Iteration Path of the backlog items and any of its child tasks to the sprint you selected. ::: moniker-end diff --git a/docs/boards/includes/basic-process-bug-note.md b/docs/boards/includes/basic-process-bug-note.md index c2d84bc30fb..2e97b962b6c 100644 --- a/docs/boards/includes/basic-process-bug-note.md +++ b/docs/boards/includes/basic-process-bug-note.md @@ -6,10 +6,9 @@ ms.topic: include ms.date: 07/09/2020 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!NOTE] > Bug work item types aren't available with the Basic process. The Basic process tracks bugs as Issues and is available when you create a new project from Azure DevOps Services or [Azure DevOps Server 2019.1](https://go.microsoft.com/fwlink/?LinkId=2097609) or later versions. - ::: moniker-end \ No newline at end of file diff --git a/docs/boards/includes/basic-process-note.md b/docs/boards/includes/basic-process-note.md index d853846c286..13d7bdf32d3 100644 --- a/docs/boards/includes/basic-process-note.md +++ b/docs/boards/includes/basic-process-note.md @@ -2,9 +2,3 @@ ms.topic: include --- -::: moniker range="<= azure-devops-2019" - -> [!NOTE] -> The Basic process is available when you add a project to Azure DevOps Services or [Azure DevOps Server 2019 Update 1](https://go.microsoft.com/fwlink/?LinkId=2097609). For earlier on-premises deployments, choose Agile, Scrum, or CMMI process. - -::: moniker-end diff --git a/docs/boards/includes/common-work-item-fields.md b/docs/boards/includes/common-work-item-fields.md index 1ac8e5e99ab..3249b6896d9 100644 --- a/docs/boards/includes/common-work-item-fields.md +++ b/docs/boards/includes/common-work-item-fields.md @@ -86,7 +86,7 @@ The only required field for all work item types is **Title**. When you save a wo :::row-end::: :::row::: :::column span="1"::: - ![Links tab icon](../backlogs/media/icon-links-tab-wi.png) [(Links)](../queries/link-work-items-support-traceability.md) + ![Links tab icon](../backlogs/media/icon-links-tab-wi.png) [(Links)](../backlogs/add-link.md) :::column-end::: :::column span="3"::: Add all types of links, such as hyperlinks, changesets, source files, and so on. diff --git a/docs/boards/includes/create-team-project-links.md b/docs/boards/includes/create-team-project-links.md index 1148bd7e152..6ef23013161 100644 --- a/docs/boards/includes/create-team-project-links.md +++ b/docs/boards/includes/create-team-project-links.md @@ -3,11 +3,11 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 06/07/2023 +ms.date: 09/10/2024 --- - [Create a project](../../organizations/projects/create-project.md) - [Add work items to manage a project](../backlogs/add-work-items.md) - [Create a backlog](../backlogs/create-your-backlog.md) -- [Use a Kanban board](../boards/kanban-overview.md) -- [Plan a sprint](../sprints/assign-work-sprint.md) +- [Manage access to specific features](../../organizations/security/restrict-access.md) +- [Learn about default permissions and access levels for Azure Boards](../get-started/permissions-access-boards.md) diff --git a/docs/boards/includes/customize-work-tracking.md b/docs/boards/includes/customize-work-tracking.md index b55fcf6e51d..f88029778bc 100644 --- a/docs/boards/includes/customize-work-tracking.md +++ b/docs/boards/includes/customize-work-tracking.md @@ -6,8 +6,7 @@ ms.topic: include ms.date: 06/07/2023 --- - - + ::: moniker range="azure-devops" @@ -15,14 +14,9 @@ For most work item types, you can add fields, change the workflow, add custom ru ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] -> ![Time and Locale page, Date pattern options](../../organizations/settings/media/user-preferences/date-patterns.png) ![Time and Locale page, Time pattern options](../../organizations/settings/media/user-preferences/time-pattern.png) +::: moniker range="azure-devops" -::: moniker-end +:::image type="content" source="../../organizations/settings/media/user-preferences/date-patterns.png" alt-text="Screenshot that shows the Date Pattern dropdown options on the Time and Locale pane."::: :::image type="content" source="../../organizations/settings/media/user-preferences/time-pattern.png" alt-text="Screenshot that shows the Time Pattern dropdown options on the Time and Locale pane."::: + +::: moniker-end -::: moniker range="< azure-devops" +::: moniker range="< azure-devops" -:::image type="content" source="../../organizations/settings/media/user-preferences/jamalh-locale-settings-server.png" alt-text="Time and Locale page, Date pattern options"::: +:::image type="content" source="../../organizations/settings/media/user-preferences/jamalh-locale-settings-server.png" alt-text="Screenshot that shows the Time and Locale pane with Date pattern and Time pattern fields."::: ::: moniker-end diff --git a/docs/boards/includes/deprecate-project.md b/docs/boards/includes/deprecate-project.md index 403ba05f7e8..24fc032a895 100644 --- a/docs/boards/includes/deprecate-project.md +++ b/docs/boards/includes/deprecate-project.md @@ -5,11 +5,13 @@ author: chcomley ms.date: 03/25/2021 --- -> [!IMPORTANT] -> Microsoft Project Integration and the **TFSFieldMapping** command are not supported for: -> - Visual Studio 2019 and Azure DevOps Office® Integration 2019 -> - Azure DevOps Server 2019 and later versions, including Azure DevOps Services. -> -> However, full support for Microsoft Excel integration is maintained and supports bulk import and update of work items. Alternatives to using Microsoft Project include the following: -> - [Delivery plans](../plans/review-team-plans.md) -> - A Marketplace extension such as [Project Connect](https://marketplace.visualstudio.com/items?itemName=TVT.TVT-PjO) or [GANTT chart](https://marketplace.visualstudio.com/search?term=gantt&target=AzureDevOps&category=Azure%20Boards&visibilityQuery=all&sortBy=Relevance). \ No newline at end of file +> [!IMPORTANT] +> Microsoft Project Integration and the `TFSFieldMapping` command aren't supported for: +> +> - Visual Studio 2019 and Azure DevOps Office Integration 2019. +> - Azure DevOps Server 2019 and later versions, including Azure DevOps Services. +> +> Full support for Microsoft Excel integration is maintained, allowing bulk import and update of work items. Alternatives to using Microsoft Project include: +> +> - [Delivery Plans](../plans/review-team-plans.md) +> - Marketplace extensions like [Project Connect](https://marketplace.visualstudio.com/items?itemName=TVT.TVT-PjO) or [GANTT chart](https://marketplace.visualstudio.com/search?term=gantt&target=AzureDevOps&category=Azure%20Boards&visibilityQuery=all&sortBy=Relevance) diff --git a/docs/boards/includes/discussion-tip-azure-devops.md b/docs/boards/includes/discussion-tip-azure-devops.md index 1becc5e8e6b..74c250cebcb 100644 --- a/docs/boards/includes/discussion-tip-azure-devops.md +++ b/docs/boards/includes/discussion-tip-azure-devops.md @@ -3,82 +3,72 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/02/2023 +ms.date: 10/08/2024 --- - - - ## Capture comments in the Discussion section -Use the **Discussion** section to add and review comments made about the work being performed. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Discussion section within a work item form.](../backlogs/media/discussion-section.png) +Use the **Discussion** section to add and review comments made about the work being performed. -The rich text editor tool bar displays below the text entry area. It appears when you click your cursor within each text box that supports text formatting. +:::image type="content" source="../backlogs/media/discussion-section.png" alt-text="Screenshot of Discussion section within a work item form."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of Discussion section, New Rich Text Editor toolbar.](../queries/media/share-plans/discussion-rich-text-editor-toolbar.png) +The rich text editor toolbar appears under the text entry area when you place your cursor in any text box that supports text formatting. +:::image type="content" source="../queries/media/share-plans/discussion-rich-text-editor-toolbar.png" alt-text="Screenshot of Discussion section, New Rich Text Editor toolbar."::: > [!NOTE] -> There is no Discussion work item field. To query work items with comments entered in the Discussion area, you filter on the [**History** field](../queries/history-and-auditing.md). The full content of the text entered into the Discussion text box is added to the History field. +> A Discussion work item field doesn't exist. To query work items with comments from the Discussion area, filter on the [History field](../queries/history-and-auditing.md). The full content of the text entered in the Discussion text box is added to the History field. -### Mention someone, a group, work item, or pull request +### Mention someone, a group, work item, or pull request -Choose one of these icons--:::image type="icon" source="../../media/icons/at-mention.png" border="false" alt-text="at mention":::, :::image type="icon" source="../../media/icons/work-id.png" border="false" alt-text="pound sign ":::, or :::image type="icon" source="../../media/icons/pr-id.png" border="false" alt-text="P R":::--to open a menu of recent entries you've made to mention someone, link to a work item, or link to a pull request. Or to open the same menu, you can type **@**, **#**, or **!**. +Select one of the following icons to open a menu of recent entries where you mentioned someone, linked to a work item, or linked to a pull request. Alternatively, you can open the same menu by entering `@`, `#`, or `!`. -> [!div class="mx-imgBorder"] -> ![Screenshot of Discussion section, at-mention drop-down menu people-picker.](../media/discussion-at-mention.png) +- :::image type="icon" source="../../media/icons/at-mention.png" border="false"::: +- :::image type="icon" source="../../media/icons/work-id.png" border="false"::: +- :::image type="icon" source="../../media/icons/pr-id.png" border="false"::: -Enter a name or number and the menu list filters to match your entry. Choose the entry you want to add. You can bring a group into the discussion by entering **@** and the group name, such as a team or security group. +:::image type="content" source="../media/discussion-at-mention.png" alt-text="Screenshot of Discussion section, at-mention drop-down menu people-picker."::: -::: moniker range=">= azure-devops-2019" +Enter a name or number to filter the menu list to match your entry. Select the entry you want to add. To bring a group into the discussion, enter `@` followed by the group name, such as a team or security group. -### Edit or delete a comment +### Edit or delete a comment -If you need to edit or delete any of your discussion comments, choose :::image type="icon" source="../../media/icons/edit.png" border="false"::: **Edit** or choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and then choose **Delete**. +To edit or delete any of your discussion comments, choose :::image type="icon" source="../../media/icons/edit.png" border="false"::: **Edit** or choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and then choose **Delete**. -> [!div class="mx-imgBorder"] -> ![Screenshot of Discussion section, choose Edit or Delete actions.](../media/discussion-edit-delete.png) -::: moniker-end +:::image type="content" source="../media/discussion-edit-delete.png" alt-text="Screenshot of Discussion section where you can choose Edit or Delete actions."::: -::: moniker range="azure-devops-2019" -> [!NOTE] -> Editing and deleting comments requires Azure DevOps Server 2019 Update 1 or later version. -::: moniker-end +After you update the comment, select **Update**. To delete the comment, confirm that you want to delete it. The **History** tab on the work item form maintains a full audit trail of all edited and deleted comments. + +::: moniker range="< azure-devops" + +> [!IMPORTANT] +> For on-premises Azure DevOps Server, [configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts) for team members to receive notifications. -::: moniker range=">= azure-devops-2019" -After updating the comment, choose **Update**. To delete the comment, you'll need to confirm that you want to delete it. -A full audit trail of all edited and deleted comments is maintained in the History tab on the work item form. ::: moniker-end ::: moniker range=">= azure-devops-2020" -### Add a reaction to a comment +### Add a reaction to a comment -Add one or more reactions to a comment by choosing a smiley icon at the upper-right corner of any comment. Or, choose from the icons at the bottom of a comment next to any existing reactions. To remove your reaction, choose the reaction on the bottom of your comment. The following image shows an example of the experience of adding a reaction, as well as the display of reactions on a comment. +Add one or more reactions to a comment by choosing a smiley icon at the upper-right corner of any comment. Choose from the icons at the bottom of a comment next to any existing reactions. To remove your reaction, choose the reaction on the bottom of your comment. The following image shows an example of the experience of adding a reaction, and the display of reactions on a comment. -> [!div class="mx-imgBorder"] -> ![Screenshot of Discussion section, add a reaction to a comment.](../media/discussion-comments-reactions.png) +:::image type="content" source="../media/discussion-comments-reactions.png" alt-text="Screenshot of Discussion section, add a reaction to a comment."::: ::: moniker-end -::: moniker range="azure-devops" +::: moniker range=">= azure-devops-2022" ### Save a comment without saving the work item -If you only have permissions to add to the **Discussion** of a work item, then you can do so by saving comments. This permission is controlled by Area Path nodes and the **Edit work item comments in this node** permission. For more information, see [Set work tracking permissions, Create child nodes, modify work items under an area or iteration path](../../organizations/security/set-permissions-access-work-tracking.md#set-permissions-area-path). +[!INCLUDE [feature-added-2022-1](../../includes/feature-added-2022-1.md)] -Once you save the comments, you don't need to save the work item. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Discussion section, save comment.](../work-items/media/view-add/save-comments-discussion-control.png) +If you only have permissions to add to the **Discussion** of a work item, then you can do so by saving comments. This permission is controlled by Area Path nodes and the **Edit work item comments in this node** permission. For more information, see [Set work tracking permissions, Create child nodes, modify work items under an area or iteration path](../../organizations/security/set-permissions-access-work-tracking.md#set-permissions-area-path). +When you save the comments, you don't need to save the work item. -> [!NOTE] -> When you save changes made to the **Discussion** control, only the comment is saved. No [work item rules](../../organizations/settings/work/rule-reference.md) defined for the work item type execute. +:::image type="content" source="../work-items/media/view-add/save-comments-discussion-control.png" alt-text="Screenshot of Discussion section, save comment."::: +> [!NOTE] +> When you save changes made to the **Discussion** control, only the comment gets saved. No [work item rules](../../organizations/settings/work/rule-reference.md) defined for the work item type are executed. ::: moniker-end diff --git a/docs/boards/includes/discussion-tip.md b/docs/boards/includes/discussion-tip.md deleted file mode 100644 index 32ab6571087..00000000000 --- a/docs/boards/includes/discussion-tip.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -ms.service: azure-devops-boards -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 06/07/2023 ---- - - - - -## Capture comments in the Discussion section - -Use the **Discussion** section to add and review comments made about the work being performed. - -:::image type="content" source="../backlogs/media/discussion-section.png" alt-text="Screenshot showing the Discussion section within a work item form."::: - -::: moniker range=">= azure-devops-2019" - -The rich text editor tool bar displays below the text entry area. It appears when you select each text box that supports text formatting. - -:::image type="content" source="../queries/media/share-plans/discussion-rich-text-editor-toolbar.png" alt-text="Screenshot of Discussion section, Rich Text Editor toolbar."::: - -> [!NOTE] -> There isn't a **Discussion** work item field. To query work items with comments entered in the Discussion area, you filter on the [**History** field](../queries/history-and-auditing.md). The full content of the text entered into the Discussion text box is added to the History field. - -### Mention someone, a group, work item, or pull request - -To open a menu of recent entries you've made to mention someone, link to a work item, or link to a pull request, select :::image type="icon" source="../../media/icons/work-id.png" border="false" alt-text="pound sign"::: or :::image type="icon" source="../../media/icons/pr-id.png" border="false" alt-text="P R":::, or enter `@`, `#`, or `!`. - -:::image type="content" source="../media/discussion-at-mention.png" alt-text="Screenshot of Discussion section, at-mention drop-down menu."::: - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -Enter a name or number and the menu list filters to match your entry. Choose the entry you want to add. To bring a group into the discussion, enter `@` and the group name, such as a team or security group. -### Edit or delete a comment - -To edit or delete any of your discussion comments, choose :::image type="icon" source="../../media/icons/edit.png" border="false"::: **Edit** or choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon, and then choose **Delete**. - -:::image type="content" source="../media/discussion-edit-delete.png" alt-text="Screenshot of Discussion section, Edit, Delete actions."::: - -::: moniker-end - -::: moniker range="azure-devops-2019" -> [!NOTE] -> Editing and deleting comments requires Azure DevOps Server 2019 Update 1 or later version. -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -After updating the comment, choose **Update**. To delete the comment, confirm that you want to delete it. - -A full audit trail of all edited and deleted comments is maintained in the **History** tab on the work item form. - -::: moniker-end - -::: moniker range="tfs-2018" - -Use the [**@mention** control](../../organizations/notifications/at-mentions.md) to notify another team member about the discussion. Enter `@` and their name. To reference a work item, use the [**#ID** control](../../organizations/notifications/add-links-to-work-items.md). Enter `#` and a list of work items that you've recently referenced appears from which you can select. - -To reference a work item, use the **#ID** control. Enter `#` and a list of work items that you've recently referenced appears from which you can select. - -You can't edit or delete comments once you've entered them. - -::: moniker-end - -::: moniker range="< azure-devops" - -> [!IMPORTANT] -> For on-premises Azure DevOps Server, [you must configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts) for team members to receive notifications. - -::: moniker-end - -::: moniker range=">= azure-devops-2020" - -### Add a reaction to a comment - -Add one or more reactions to a comment by choosing a smiley icon at the upper-right corner of any comment. Or, choose from the icons at the bottom of a comment next to any existing reactions. To remove your reaction, choose the reaction on the bottom of your comment. The following image shows an example of the experience of adding a reaction and the display of reactions on a comment. - -:::image type="content" source="../media/discussion-comments-reactions.png" alt-text="Screenshot of Discussion control, Add reactions to a comment."::: - -::: moniker-end - -::: moniker range="azure-devops" - -### Save a comment without saving the work item - -If you only have permissions to add to the **Discussion** of a work item, then you can do so by saving comments. This permission is controlled by Area Path nodes and the **Edit work item comments in this node** permission. For more information, see [Set work tracking permissions, Create child nodes, modify work items under an area or iteration path](../../organizations/security/set-permissions-access-work-tracking.md#set-permissions-area-path). - -Once you save the comments, you don't need to save the work item. - -:::image type="content" source="../work-items/media/view-add/save-comments-discussion-control.png" alt-text="Screenshot of Discussion section, save comment."::: - -> [!NOTE] -> When you save changes made to the **Discussion** control, only the comment is saved. No [work item rules](../../organizations/settings/work/rule-reference.md) defined for the work item type execute. - -::: moniker-end diff --git a/docs/boards/includes/display-leaf-nodes.md b/docs/boards/includes/display-leaf-nodes.md index a362748883a..fde7a05d1a3 100644 --- a/docs/boards/includes/display-leaf-nodes.md +++ b/docs/boards/includes/display-leaf-nodes.md @@ -2,6 +2,8 @@ ms.topic: include --- -While you can create a hierarchy of backlog items, tasks, and bugs—we don't recommend that you create same-category hierarchies. In other words, don't create parent-child links among work items of the same type, such as story-story, bug-bug, or task-task. The last node in a same-category hierarchy may only appear on Kanban boards, sprint backlogs, and Taskboards. For example, if you link items within a same-category hierarchy that is four levels deep, only the items at the fourth level appear on the Kanban board, sprint backlog, and taskboard. +You can create a hierarchy of backlog items, tasks, and bugs. We don't recommend that you create same-category hierarchies. In other words, don't create parent-child links among work items of the same type, such as story-story, bug-bug, or task-task. -Rather than nest requirements, bugs, and tasks, we recommend that you maintain a flat list. Only create parent-child links one level deep between items that belong to a different category. For more information, see [Fix re-ordering and nesting issues, How backlogs and boards display hierarchical (nested) items](../backlogs/resolve-backlog-reorder-issues.md#leaf-nodes). +The last node in a same-category hierarchy might only appear on boards, sprint backlogs, and Taskboards. For example, if you link items within a same-category hierarchy that is four levels deep, only the items at the fourth level appear on the board, sprint backlog, and taskboard. + +Rather than nest requirements, bugs, and tasks, we recommend that you maintain a flat list. Create parent-child links one level deep between items that belong to a different category. For more information, see [Troubleshoot reordering and nesting issues](../backlogs/resolve-backlog-reorder-issues.md). diff --git a/docs/boards/includes/display-progress-bars.md b/docs/boards/includes/display-progress-bars.md index 6d5655ed4e6..86df9f152e6 100644 --- a/docs/boards/includes/display-progress-bars.md +++ b/docs/boards/includes/display-progress-bars.md @@ -6,8 +6,6 @@ ms.topic: include ms.date: 07/09/2020 --- -For example, progress bars are shown here for a portfolio backlog. - -> [!div class="mx-imgBorder"] -> ![Example portfolio backlog with progress bars](../backlogs/media/rollup/epic-featurs-progress-user-stories-50-percent.png) +For example, see the following progress bars for a portfolio backlog. +:::image type="content" source="../backlogs/media/rollup/epic-features-progress-user-stories-50-percent.png" alt-text="Screenshot of example portfolio backlog with progress bars."::: diff --git a/docs/boards/includes/display-rollup-section.md b/docs/boards/includes/display-rollup-section.md index ec1ce0f52a1..a0556cccab6 100644 --- a/docs/boards/includes/display-rollup-section.md +++ b/docs/boards/includes/display-rollup-section.md @@ -3,20 +3,21 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 07/09/2020 +ms.date: 08/01/2023 --- - ::: moniker range=">= azure-devops-2020" -## Display rollup progress, counts, or totals +## Display rollup progress counts, or totals + +Product and portfolio backlogs support rollup columns. You can add one or more rollup columns to display progress bars, counts of descendant work items, or totals of select numeric fields. Your settings persist for each page that you customize and are only valid for your views. -Product and portfolio backlogs support the display of rollup columns. You can add one or more rollup columns to display progress bars, counts of descendant work items, or totals of select numeric fields. Your settings persist for each page you customize and are only valid for your views. +- *Progress bars* indicate the percentage of descendant items within a hierarchy that are closed or completed. +- *Counts* display the total number of descendant items. +- *Totals* provide a sum of numeric fields, such as Effort, Story Points, Completed Work, or Remaining Work of descendant items. -*Progress bars* indicate the percentage of descendant items within a hierarchy that are closed or completed. *Counts* display the total number of descendant items. And, *Totals* provide a sum of numeric fields, such as Effort, Story Points, Completed Work, or Remaining Work of descendant items. -For example, progress bars are shown here for a portfolio backlog. +The following example shows progress bars for a portfolio backlog. -> [!div class="mx-imgBorder"] -> ![Example portfolio backlog with progress bars](../backlogs/media/rollup/epic-featurs-progress-user-stories-50-percent.png) +:::image type="content" source="../backlogs/media/rollup/epic-features-progress-user-stories-50-percent.png" alt-text="Screenshot example of epic, feature, and user stories progress."::: -::: moniker-end \ No newline at end of file +::: moniker-end diff --git a/docs/boards/includes/feature-matrix-filter-queries.md b/docs/boards/includes/feature-matrix-filter-queries.md index 1a679514deb..a30d513cc4d 100644 --- a/docs/boards/includes/feature-matrix-filter-queries.md +++ b/docs/boards/includes/feature-matrix-filter-queries.md @@ -6,12 +6,11 @@ ms.topic: include ms.date: 03/05/2021 --- - ### Query filters The following table summarizes the query filter functions supported by each Azure DevOps version. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!NOTE] > Managed queries don't support proximity searches, however semantic searches do. In addition, semantic searches support both `*` and `?` as wildcard characters and you can use more than one wildcard character to match more than one character. For more information, see [Functional work items search](../../project/search/functional-work-item-search.md). ::: moniker-end @@ -34,7 +33,7 @@ The following table summarizes the query filter functions supported by each Azur [Text string searches](../queries/titles-ids-descriptions.md) (single text, multi-line text, rich text) :::column-end::: :::column span="4"::: - Searches are not case sensitive. + Searches aren't case sensitive. :::column-end::: :::column span="1"::: All versions @@ -68,7 +67,7 @@ The following table summarizes the query filter functions supported by each Azur --- :::row::: :::column span="1"::: - [Logical clause groupings](../queries/using-queries.md#logical-groupings) + [Logical clause groupings](../queries/using-queries.md) :::column-end::: :::column span="4"::: Group and nest clauses using AND and OR Boolean operators. @@ -86,7 +85,7 @@ The following table summarizes the query filter functions supported by each Azur Find work items based on a field match with a previous value. Supported operator: `Was Ever` Find work items based on a value defined on a specific date. - Supported operator: `ASOF` ([WIQL syntax](../queries/wiql-syntax.md#asof-historical-queries)) + Supported operator: `ASOF` ([WIQL syntax](../queries/wiql-syntax.md)) :::column-end::: :::column span="1"::: All versions @@ -95,7 +94,7 @@ The following table summarizes the query filter functions supported by each Azur --- :::row::: :::column span="1"::: - [Query using macros or variables](../queries/about-managed-queries.md#macros) + [Query using macros or variables](../queries/about-managed-queries.md#supported-macros) :::column-end::: :::column span="1"::: Use macros to create queries relative to a date, other tools, such as team area path, team iteration, and more. @@ -107,7 +106,7 @@ The following table summarizes the query filter functions supported by each Azur --- :::row::: :::column span="1"::: - [Search across projects](../queries/using-queries.md#across-projects) + [Search across projects](../queries/using-queries.md) :::column-end::: :::column span="1"::: Find work items in one or more projects in an organization or collection. Default is the current project. Use the **Team Project** field to query on two or more projects. @@ -152,7 +151,7 @@ The following table summarizes the query filter functions supported by each Azur **Supported operators**: `Is Empty, Is Not Empty` :::column-end::: :::column span="1"::: - Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services + All versions :::column-end::: :::row-end::: --- @@ -161,7 +160,7 @@ The following table summarizes the query filter functions supported by each Azur [In and Not In Group searches](../queries/planning-ranking-priorities.md) :::column-end::: :::column span="1"::: - Find work whose field value matches any value in a delimited set, such as a set of work item types, workflow states, or picklist values. Separate values with the list separator that corresponds to the regional settings that are defined for your client computer. For example, you might use a comma(,). + Find work whose field value matches any value in a delimited set, such as a set of work item types, workflow states, or picklist values. Separate values with the list separator that corresponds to the regional settings that are defined for your client computer. For example, you might use a comma (,). :::column-end::: :::column span="1"::: All versions @@ -194,13 +193,13 @@ The following table summarizes the query filter functions supported by each Azur --- :::row::: :::column span="1"::: - [Query on Kanban board fields](../queries/query-by-workflow-changes.md#query-changes-to-a-kanban-board) + [Query on board fields](../queries/query-by-workflow-changes.md#query-changes-to-a-kanban-board) :::column-end::: :::column span="1"::: - Find work items based on their Kanban column, swimlane, or Doing/Done status. + Find work items based on their column, swimlane, or Doing/Done status. :::column-end::: :::column span="1"::: - Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services + All versions :::column-end::: :::row-end::: --- @@ -212,9 +211,9 @@ The following table summarizes the query filter functions supported by each Azur Filter query results based on a key word or select fields. :::column-end::: :::column span="1"::: - Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services + All versions :::column-end::: :::row-end::: --- -To bulk move, copy, or paste query clauses, install and use the WIQL editor. For more information, see [Cross-service and enhanced query operations](../queries/query-support-integration-cross-service-extensions.md#wiql) \ No newline at end of file +To bulk move, copy, or paste query clauses, install and use the [WIQL editor](https://marketplace.visualstudio.com/items?itemName=ms-eswm.wiql-to-odata). diff --git a/docs/boards/includes/feature-matrix-manage-queries.md b/docs/boards/includes/feature-matrix-manage-queries.md index 1bc69f9cbce..6e7a7e22580 100644 --- a/docs/boards/includes/feature-matrix-manage-queries.md +++ b/docs/boards/includes/feature-matrix-manage-queries.md @@ -14,33 +14,30 @@ The following features provide support for working with query results, saving an --- :::row::: :::column span="1"::: - - [Add a query chart to a dashboard](../../report/dashboards/charts.md#add-chart-to-a-dashboard) + - [Add a query chart to a dashboard](../../report/dashboards/charts.md#add-a-chart-to-a-dashboard) - [Apply interactive filters](../backlogs/filter-backlogs-boards-plans.md) - [Choose column sort](../backlogs/set-column-options.md) - [Choose query column options](../backlogs/set-column-options.md) - - [Copy query results](../backlogs/copy-list.md) - - [Copy Query URL](../queries/view-run-query.md#email-query) - - [Create a query from a backlog](../backlogs/product-backlog-controls.md) + - [Copy query results](../backlogs/copy-clone-work-items.md#copy-a-list-of-work-items) + - [Copy Query URL](../queries/view-run-query.md#email-query-items-or-share-a-query-url) - [Create query charts](../../report/dashboards/charts.md) - [Create query folders](../queries/organize-queries.md) :::column-end::: :::column span="1"::: - - [Define a query hyperlink](../queries/define-query-hyperlink.md) - [Define and edit a query](../queries/using-queries.md) - [Define WIQL syntax](../queries/wiql-syntax.md) - - [Email query results](../queries/view-run-query.md#email-query) - - [Favorite a query](../queries/view-run-query.md#favorites) + - [Email query results](../queries/view-run-query.md#email-query-items-or-share-a-query-url) + - [Favorite a query](../queries/view-run-query.md#all-and-favorites-supported-tasks) - [Filter a query](../backlogs/filter-backlogs-boards-plans.md) :::column-end::: :::column span="1"::: - [Import/export a query (csv)](../queries/import-work-items-from-csv.md) - - [Import/export a query (.wiq)](../queries/query-support-integration-cross-service-extensions.md#wiql) + - [Import/export a query (.wiq)](https://marketplace.visualstudio.com/items?itemName=ms-eswm.wiql-to-odata) - [Open and run a query](../queries/view-run-query.md) - [Publish/refresh a query (Excel)](../backlogs/office/bulk-add-modify-work-items-excel.md) - [Run REST API queries](/rest/api/azure/devops/wit/queries) - - [Save queries](../queries/organize-queries.md#flat-list-query) + - [Copy and save queries](../queries/organize-queries.md#copy-edit-and-save-a-query) - [Set query permissions](../queries/set-query-permissions.md) - - [Triage query results](../queries/triage-work-items.md) :::column-end::: :::row-end::: --- \ No newline at end of file diff --git a/docs/boards/includes/feature-matrix-query-macros.md b/docs/boards/includes/feature-matrix-query-macros.md index f53044c915d..0150d108123 100644 --- a/docs/boards/includes/feature-matrix-query-macros.md +++ b/docs/boards/includes/feature-matrix-query-macros.md @@ -7,7 +7,6 @@ ms.date: 01/14/2021 --- -### Supported macros The following table summarizes the query macros or variables supported by the Azure DevOps versions. You can use some of these macros to filter notifications. @@ -68,7 +67,7 @@ For more detailed descriptions and links to examples, see [Query fields, operato --- :::row::: :::column span="1"::: - [@Project](../queries/using-queries.md#across-projects) + [@Project](../queries/using-queries.md) :::column-end::: :::column span="1"::: Find work defined in one or more projects. @@ -98,7 +97,7 @@ For more detailed descriptions and links to examples, see [Query fields, operato Find work defined in +/- n of current iteration for a team. :::column-end::: :::column span="1"::: - Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services + All versions :::column-end::: :::row-end::: --- @@ -135,7 +134,7 @@ For more detailed descriptions and links to examples, see [Query fields, operato Find work where the selected date-time field is within the current day, month, week, or year with a plus/minus offset, example: `Closed Date>=@StartOfDay-7`. :::column-end::: :::column span="1"::: - Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services + All versions :::column-end::: :::row-end::: --- @@ -147,7 +146,7 @@ For more detailed descriptions and links to examples, see [Query fields, operato Find work assigned to an Area Path or Iteration Path of specified team, for examples, see [Query by area or iteration path](../queries/query-by-area-iteration-path.md). :::column-end::: :::column span="1"::: - Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services + All versions :::column-end::: :::row-end::: --- diff --git a/docs/boards/includes/get-latest-process-templates.md b/docs/boards/includes/get-latest-process-templates.md index 929538ba0c2..9b53dee628b 100644 --- a/docs/boards/includes/get-latest-process-templates.md +++ b/docs/boards/includes/get-latest-process-templates.md @@ -1,27 +1,18 @@ --- ms.topic: include -ms.date: 01/22/2021 +ms.date: 10/11/2024 --- -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!TIP] -> With Azure DevOps Server, you can choose between using the Inherited process model or the On-premises XML process model. For more information, see [Customize your work tracking experience, Choose the process model for your project collection](../../reference/customize-work.md#choose-the-process-model-for-your-project-collection). To access the latest versions of the default processes/process templates: -> - **For Inherited process model**: Open the Process page from organizations settings. For more information, see [Manage processes](../../organizations/settings/work/manage-process.md). -> - **For the On-premises XML process model**: -> - [Install or upgrade to the latest version of Azure DevOps Server](https://visualstudio.microsoft.com/downloads/) -> - Download the zipped template file using the [Process Template Manager](../work-items/guidance/manage-process-templates.md). You'll need to use a version of Visual Studio that is at the same version level as Azure DevOps Server. You can install the latest version of [Visual Studio Community](https://visualstudio.microsoft.com/downloads/) for free. -> - You can access the latest versions of the default process templates installed on Azure DevOps Server, for example: `%programfiles%/Azure DevOps Server 2020/Tools/Deploy/ProcessTemplateManagerFiles/1033`. For descriptions of each file and folder, see [Overview of process template files](/previous-versions/azure/devops/reference/process-templates/overview-process-template-files). +> With Azure DevOps Server, you can choose between using the *Inherited process model* or the *On-premises XML process model*. For more information, see [Choose the process model for your project collection](../../reference/customize-work.md#choose-the-process-model-for-your-project-collection). To access the latest versions of the default processes or process templates: +> +> - **Inherited process model**: Open the **Processes** page. For more information, see [Manage processes](../../organizations/settings/work/manage-process.md). +> - **On-premises XML process model**: +> +> - [Install or upgrade to the latest version of Azure DevOps Server](https://visualstudio.microsoft.com/downloads/). +> - Download the zipped template file by using the [Process Template Manager](../work-items/guidance/manage-process-templates.md). Use a version of Visual Studio that's at the same version level as Azure DevOps Server. You can install the latest version of [Visual Studio Community](https://visualstudio.microsoft.com/downloads/) for free. +> - You can access the latest versions of the default process templates installed on Azure DevOps Server, for example: `%programfiles%/Azure DevOps Server 2020/Tools/Deploy/ProcessTemplateManagerFiles/1033`. For descriptions of each file and folder, see [Overview of process template files](/previous-versions/azure/devops/reference/process-templates/overview-process-template-files). ::: moniker-end - - -::: moniker range="tfs-2018" - -> [!TIP] -> To access the latest versions of the default process templates: -> - [Install or upgrade to the latest version of TFS](https://visualstudio.microsoft.com/downloads/). -> - Download the zipped template file using the [Process Template Manager](../work-items/guidance/manage-process-templates.md). You'll need to use a version of Visual Studio that is at the same version level as TFS. You can install the latest version of [Visual Studio Community](https://visualstudio.microsoft.com/downloads/) for free. -> - You can access the latest versions of the default process templates installed on TFS 2018 here:` %programfiles%/TFS 16.0/Tools/Deploy/ProcessTemplateManagerFiles/1033`. For descriptions of each file and folder, see [Overview of process template files](/previous-versions/azure/devops/reference/process-templates/overview-process-template-files). - -::: moniker-end \ No newline at end of file diff --git a/docs/boards/includes/github-platform-support.md b/docs/boards/includes/github-platform-support.md index 4bbfb9e652d..5b33b253ca9 100644 --- a/docs/boards/includes/github-platform-support.md +++ b/docs/boards/includes/github-platform-support.md @@ -7,5 +7,5 @@ ms.date: 07/03/2023 --- > [!NOTE] -> With the Azure Boards app for GitHub, Azure Boards and Azure DevOps Services support integration with GitHub.com and GitHub Enterprise Server repositories. Azure DevOps Servers 2019 and later versions support integration with GitHub Enterprise Server repositories only.Integration with other Git repositories is not supported. +> With the Azure Boards app for GitHub, Azure Boards and Azure DevOps Services integrate with GitHub.com and GitHub Enterprise Server repositories. Azure DevOps Server 2019 and later versions support integration with GitHub Enterprise Server repositories only. Integration with other Git repositories is not supported. \ No newline at end of file diff --git a/docs/boards/includes/image-differences-with-wits.md b/docs/boards/includes/image-differences-with-wits.md index 58cf1068c83..4ab206c21d1 100644 --- a/docs/boards/includes/image-differences-with-wits.md +++ b/docs/boards/includes/image-differences-with-wits.md @@ -4,5 +4,5 @@ ms.topic: include -> [!NOTE] -> The images you see from your web portal may differ from the images you see in this article. These differences result from updates made to your web app, options that you or your admin have enabled, and which process was chosen when creating your project—[Agile](../work-items/guidance/agile-process.md), [Basic](../get-started/plan-track-work.md), [Scrum](../work-items/guidance/scrum-process.md), or [CMMI](../work-items/guidance/cmmi-process.md). The Basic process is available with [Azure DevOps Server 2019 Update 1](https://go.microsoft.com/fwlink/?LinkId=2097609) and later versions. \ No newline at end of file +> [!NOTE] +> The images you see from your web portal might differ from the images you see in this article. These differences result from updates made to your web app, options that you or your administrator enabled, and which process was chosen when creating your project: [Agile](../work-items/guidance/agile-process.md), [Basic](../get-started/plan-track-work.md), [Scrum](../work-items/guidance/scrum-process.md), or [CMMI](../work-items/guidance/cmmi-process.md). The Basic process is available with [Azure DevOps Server 2019 Update 1](https://go.microsoft.com/fwlink/?LinkId=2097609) and later versions. diff --git a/docs/boards/includes/image-differences.md b/docs/boards/includes/image-differences.md index 3b54089cf2e..38b0eb9aace 100644 --- a/docs/boards/includes/image-differences.md +++ b/docs/boards/includes/image-differences.md @@ -8,19 +8,17 @@ ms.date: 07/09/2020 - - ::: moniker range="azure-devops" > [!NOTE] -> The images you see from your web portal may differ from the images you see in this article. These differences result from updates made to Azure DevOps Services. However, the basic functionality available to you remains the same unless explicitly mentioned. +> The images in your web portal might differ from those in this article due to updates made to Azure DevOps Services. However, unless explicitly mentioned, the basic functionality remains the same. ::: moniker-end ::: moniker range="< azure-devops" > [!NOTE] -> The images you see from your web portal may differ from the images you see in this article. These differences result from updates made to your on-premises Azure DevOps. However, the basic functionality available to you remains the same unless explicitly mentioned. +> The images in your web portal might differ from those in this article due to updates made to Azure DevOps Server. However, unless explicitly mentioned, the basic functionality remains the same. ::: moniker-end diff --git a/docs/boards/includes/list-area-dependent-tools-tasks.md b/docs/boards/includes/list-area-dependent-tools-tasks.md index 1304ecfe01d..2b96fa0b968 100644 --- a/docs/boards/includes/list-area-dependent-tools-tasks.md +++ b/docs/boards/includes/list-area-dependent-tools-tasks.md @@ -8,10 +8,8 @@ ms.topic: include ms.date: 05/24/2021 --- - To perform the following tasks, you must define area paths: - - [Query and chart work items based on Area Path](../queries/query-by-area-iteration-path.md) - [Assign work to more than one team](../../organizations/settings/add-teams.md) - [Work with management and feature teams](../plans/configure-hierarchical-teams.md) @@ -27,17 +25,9 @@ To use the following tools, teams must subscribe to area paths: - [Boards> all tools](../boards/kanban-overview.md) - [Backlogs> all tools](../backlogs/backlogs-overview.md) - [Sprints> all tools](../sprints/scrum-overview.md) -- [Delivery plans](../plans/review-team-plans.md), calendar view of team deliverables +- [Delivery plans](../plans/review-team-plans.md) - [Rollup](../configure-customize.md#rollup-hierarchy-and-portfolio-management) - [Analytics> all](../../report/dashboards/overview.md#in-context-reports-work-tracking) ::: moniker-end -::: moniker range="< azure-devops-2020" - -- [Boards> all tools](../boards/kanban-overview.md) -- [Backlogs> all tools](../backlogs/backlogs-overview.md) -- [Sprints> all tools](../sprints/scrum-overview.md) -- [Delivery plans](../extensions/delivery-plans.md), calendar view of team deliverables - -::: moniker-end diff --git a/docs/boards/includes/list-sprint-dependent-tools.md b/docs/boards/includes/list-sprint-dependent-tools.md index 96743dc91a8..e0cf65d9e95 100644 --- a/docs/boards/includes/list-sprint-dependent-tools.md +++ b/docs/boards/includes/list-sprint-dependent-tools.md @@ -12,7 +12,6 @@ ms.date: 05/20/2021 Define iteration paths and assign them to teams when you want to use the following tools: - ::: moniker range="azure-devops" - [Assign work items to sprints using the Planning pane](../sprints/assign-work-sprint.md) @@ -24,27 +23,16 @@ Define iteration paths and assign them to teams when you want to use the followi ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" all tools](../sprints/scrum-overview.md) -- [Delivery Plans, a calendar view of team deliverables](../extensions/delivery-plans.md) +- [Delivery Plans](../plans/review-team-plans.md) - [Velocity chart](../../report/dashboards/team-velocity.md) and [Sprint burndown chart](../../report/dashboards/configure-sprint-burndown.md) ::: moniker-end -::: moniker range="< azure-devops-2019" - -- [Assign work to sprints using the Planning pane](../sprints/assign-work-sprint.md) -- [Query and chart work items based on Iteration Path](../queries/query-by-area-iteration-path.md) -- [Forecast your product backlog](../sprints/forecast.md) -- [Sprints> all tools](../sprints/scrum-overview.md) -- [Delivery Plans, a calendar view of team deliverables](../extensions/delivery-plans.md) -- [Velocity chart](../../report/dashboards/team-velocity.md) - -::: moniker-end - > [!TIP] > If a team hasn't subscribed or selected an iteration path, that iteration path won't appear in a team view or tool. \ No newline at end of file diff --git a/docs/boards/includes/note-add-backlog-board.md b/docs/boards/includes/note-add-backlog-board.md index b0fb616873d..d6ad21b1979 100644 --- a/docs/boards/includes/note-add-backlog-board.md +++ b/docs/boards/includes/note-add-backlog-board.md @@ -8,7 +8,5 @@ ms.topic: include ms.date: 09/24/2020 --- - - -> [!NOTE] -> **How do I add a backlog or board?** You don't add backlogs or boards. You add a team which is automatically configured with it's own set of backlogs and boards as described in [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). \ No newline at end of file +> [!NOTE] +> **How do I add a backlog or board?** You don't add backlogs or boards. You add a team which is automatically configured with it's own set of backlogs and boards. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). diff --git a/docs/boards/includes/note-closed-items.md b/docs/boards/includes/note-closed-items.md index b68512b466a..9055fac875f 100644 --- a/docs/boards/includes/note-closed-items.md +++ b/docs/boards/includes/note-closed-items.md @@ -10,16 +10,16 @@ ms.date: 04/07/2022 ::: moniker range="azure-devops" -> [!NOTE] -> Completed or closed work items don't display on the backlogs and boards once their **Changed Date** is greater than 183 days (about a half a year). You can still list these items using a query. If you want them to show up on a backlog or board, then you can make a minor change to them which resets the clock. +> [!NOTE] +> Completed or closed work items don't display on the backlogs and boards after their **Changed Date** value is greater than 183 days (about a half a year). You can still list these items by using a query. If you want them to show up on a backlog or board, you can make a minor change to them, which resets the clock. ::: moniker-end ::: moniker range="< azure-devops" -> [!NOTE] -> Completed or closed work items don't display on the backlogs and boards once their **Changed Date** is greater than a year old. You can still list these items using a query. If you want them to show up on a backlog or board, then you can make a minor change to them which resets the clock. +> [!NOTE] +> Completed or closed work items don't display on the backlogs and boards after their **Changed Date** value is greater than a year old. You can still list these items by using a query. If you want them to show up on a backlog or board, you can make a minor change to them, which resets the clock. ::: moniker-end diff --git a/docs/boards/includes/note-configure-customize.md b/docs/boards/includes/note-configure-customize.md index d374f284f6e..9ae70bffad1 100644 --- a/docs/boards/includes/note-configure-customize.md +++ b/docs/boards/includes/note-configure-customize.md @@ -5,16 +5,18 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include -ms.date: 05/02/2023 +ms.date: 11/02/2023 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -> [!NOTE] +> [!NOTE] > For more information, see the following articles: +> +> - [Use backlogs to manage projects](../backlogs/backlogs-overview.md) > - [Configure and customize Azure Boards](../configure-customize.md) > - [Create a project using the process of your choice](../../organizations/projects/create-project.md) -> - [Customize your work tracking experience (process models)](../../reference/customize-work.md) -> - [Manage inherited processes](../../organizations/settings/work/manage-process.md) +> - [Customize your work tracking experience](../../reference/customize-work.md) +> - [Create and manage inherited processes](../../organizations/settings/work/manage-process.md) ::: moniker-end diff --git a/docs/boards/includes/note-delete-area-paths.md b/docs/boards/includes/note-delete-area-paths.md index c9f7386c0b6..f6fcaefaf33 100644 --- a/docs/boards/includes/note-delete-area-paths.md +++ b/docs/boards/includes/note-delete-area-paths.md @@ -5,9 +5,15 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/10/2023 +ms.date: 03/12/2025 --- -> [!IMPORTANT] -> Deleting **Area Paths** or reconfiguring **Iteration Paths** can cause a loss of data and can't be reverted. For example, burndown or burnup widget charts, sprint burndown, and velocity charts for teams whose **Area Paths** are changed won't reflect correct data. Historical trend charts reference the **Area Path** and **Iteration Path** as defined at a point in the past for each work item. When an **Area Path** or **Iteration Path** is deleted, then the historical data for it can't be retrieved. +> [!IMPORTANT] +> - Deleting **Area Paths** or reconfiguring **Iteration Paths** causes irreversible data loss. For example: +> - Burndown and burnup widget charts +> - Sprint burndown charts +> - Velocity charts for teams with changed **Area Paths** +> - Historical trend charts that reference the **Area Path** and **Iteration Path** as they were defined at the time for each work item. +> - Once deleted, you can't retrieve historical data for these paths. +> - You can only delete area and iteration paths that are no longer used by any work items. \ No newline at end of file diff --git a/docs/boards/includes/note-kanban-boards-teams.md b/docs/boards/includes/note-kanban-boards-teams.md index 33b2bd04df3..15267ba2132 100644 --- a/docs/boards/includes/note-kanban-boards-teams.md +++ b/docs/boards/includes/note-kanban-boards-teams.md @@ -3,5 +3,5 @@ ms.topic: include --- > [!IMPORTANT] -> Work items that appear on more than one team's Kanban board can yield results that don't meet your expectations because each team can customize its Kanban board columns and swimlanes. The values assigned to Kanban **Board Column**, **Board Column Done**, and **Board Lane** fields might differ from what you expect when another team updates the work item from a different board. For more information, see [Add, review, and update work items in Azure Boards](../boards/kanban-overview.md#limits-multi-team). +> Work items that appear on more than one team's board can yield results that don't meet your expectations because each team can customize its board columns and swimlanes. The values assigned to **Board Column**, **Board Column Done**, and **Board Lane** fields might differ from what you expect when another team updates the work item from a different board. For more information, see [Add, review, and update work items in Azure Boards](../boards/kanban-overview.md). \ No newline at end of file diff --git a/docs/boards/includes/note-new-boards-hub-default-images.md b/docs/boards/includes/note-new-boards-hub-default-images.md new file mode 100644 index 00000000000..c8d0c2b237c --- /dev/null +++ b/docs/boards/includes/note-new-boards-hub-default-images.md @@ -0,0 +1,10 @@ +--- +ms.service: azure-devops-boards +ms.author: chcomley +author: chcomley +ms.topic: include +ms.date: 11/26/2024 +--- + +> [!NOTE] +> The following images display the user interface with the **New Boards Hub** feature enabled by default. For more information, see [Manage or enable features](../../project/navigation/preview-features.md). diff --git a/docs/boards/includes/note-new-git-tool-boards.md b/docs/boards/includes/note-new-git-tool-boards.md index f54a5d64f08..4eb4ac84582 100644 --- a/docs/boards/includes/note-new-git-tool-boards.md +++ b/docs/boards/includes/note-new-git-tool-boards.md @@ -1,12 +1,11 @@ --- -ms.service: azure-devops-repos ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include ms.date: 11/04/2020 -ms.subservice: azure-devops-repos-git --- > [!NOTE] -> Visual Studio 2019 now includes a new Git tool that provides an improved experience when connecting to a Git repository. When you enable this tool, the Team Explorer tool is effectively disabled when connected to a Git repository. You can acquire the new tool by downloading [Visual Studio 2019 version 16.6](/visualstudio/releases/2019/release-notes-v16.6). To enable and use the new tool, see [Git experience in Visual Studio](/visualstudio/ide/git-with-visual-studio). \ No newline at end of file +> Visual Studio 2019 now includes a new Git tool that provides an improved experience when connecting to a Git repository. When you enable this tool, the Team Explorer tool is effectively disabled when connected to a Git repository. You can acquire the new tool by downloading [Visual Studio 2019 version 16.6](/visualstudio/releases/2019/release-notes-v16.6). To enable and use the new tool, see [Git experience in Visual Studio](/visualstudio/ide/git-with-visual-studio). + \ No newline at end of file diff --git a/docs/boards/includes/note-requirements-terms.md b/docs/boards/includes/note-requirements-terms.md index 2fae5abbe40..53fd6281883 100644 --- a/docs/boards/includes/note-requirements-terms.md +++ b/docs/boards/includes/note-requirements-terms.md @@ -4,13 +4,10 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include -ms.date: 08/07/2020 +ms.date: 10/15/2024 --- + - - -> [!NOTE] -> *Requirements* specify expectations of users for a software product. In Azure Boards, requirements are defined by work items that appear on your product backlog. They correspond to User Stories (Agile), Product Backlog Items (Scrum), Issues (Basic), or Requirements (CMMI) based on the process selected for your project. They also belong to the Requirements Category which manages which work item types appear on the product backlog. -
- \ No newline at end of file +> [!NOTE] +> *Requirements* specify expectations of users for a software product. In Azure Boards, requirements are defined by work items that appear on your product backlog. Based on the process selected for your project, requirements correspond to User Story (Agile), Product backlog item (Scrum), Issue (Basic), or Requirement (CMMI) work item types. They also belong to the Requirements category, which manages the work item types that appear on the product backlog. diff --git a/docs/boards/includes/open-kanban-board.md b/docs/boards/includes/open-kanban-board.md index 79e895e1378..4b9d67081a5 100644 --- a/docs/boards/includes/open-kanban-board.md +++ b/docs/boards/includes/open-kanban-board.md @@ -4,44 +4,45 @@ ms.topic: include > [!NOTE] -> Both Kanban boards and Taskboards support visualizing the flow of work and monitoring metrics to optimize that flow. Kanban boards track requirements, are sprint-independent, and provide a cumulative flow chart for monitoring progress. Each sprint is associated with a Taskboard that supports tracking tasks defined for the sprint. You can monitor progress through capacity charts and the sprint burndown chart. For guidance on using the Taskboard, see [Update and monitor your Taskboard](../sprints/task-board.md). +> - **Visualize and optimize work flow with** both boards and Taskboards. +> - **Boards:** Ideal for tracking requirements, independent of sprints, and equipped with a cumulative flow chart for progress tracking. +> - **Taskboards:** Linked to specific sprints, they facilitate task tracking within the sprint. +> - **Progress monitoring:** Achieved through detailed capacity charts and sprint burndown charts. +> - For information about Taskboard usage and best practices, see [Update and monitor your Taskboard](../sprints/task-board.md). -## Open your Kanban board from the web portal - -Your Kanban board is one of two types of boards available to you. The other is the sprint Taskboard. Kanban boards track requirements, are sprint-independent, and provide a cumulative flow chart for monitoring progress. Each sprint is associated with a Taskboard that supports tracking tasks defined for the sprint. You can monitor progress through capacity charts and the sprint burndown chart. For guidance on using the Taskboard, see [Update and monitor your Taskboard](../sprints/task-board.md). For an overview of the features supported on each backlog and board, see [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md). - +## Open your board from the web portal ::: moniker range="azure-devops" -1. Check that you selected the right project, and select **Boards** > **Boards**. Then select the correct team from the team selector menu. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). - ![Open your Kanban board](../boards/media/quickstart/open-kanban-board-agile-s155.png) +2. Select **Boards** > **Boards** and ensure you select the correct team from the team selector menu. + + ![Screenshot showing Opening a board.](../boards/media/quickstart/open-kanban-board-agile-s155.png) To select another team's board, open the selector. Then select a different team, or select the ![home icon](../../media/icons/home-icon.png) **Browse all team boards** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. > [!div class="mx-imgBorder"] - > ![Select another team's board](../boards/media/quickstart/select-kanban-team-board.png) + > ![Screenshot show selecting another team's board.](../boards/media/quickstart/select-kanban-team-board.png) > [!TIP] > Select the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to make a team board a favorite. Favorite artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorite icon) appear at the top of the team selector list. -1. Check that you selected **Backlog items** for Scrum, **Stories** for Agile, or **Requirements** for CMMI as the backlog level. +3. Check that you selected **Backlog items** for Scrum, **Stories** for Agile, or **Requirements** for CMMI as the backlog level. > [!div class="mx-imgBorder"] - > ![Select product backlog level, Backlog items, Stories, or Requirements](../sprints/media/assign-items-sprint/select-product-backlog-agile.png) + > ![Screenshot shows selecting product backlog level, Backlog items, Stories, or Requirements.](../sprints/media/assign-items-sprint/select-product-backlog-agile.png) To switch to the [product backlog](../backlogs/create-your-backlog.md), select **Stories backlog**. To switch to a Taskboard, see [Update and monitor your Taskboard](../sprints/task-board.md). ::: moniker-end - - -::: moniker range="azure-devops-2019" +::: moniker range="< azure-devops" 1. Check that you selected the right project, and select **Boards** > **Boards**. Then select the correct team from the team selector menu. - ![Open your Kanban board](../boards/media/quickstart/open-kanban-board-agile.png) + ![Open your board](../boards/media/quickstart/open-kanban-board-agile.png) To select another team's board, open the selector. Then select a different team, or select the ![home icon](../../media/icons/home-icon.png) **Browse all team boards** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. @@ -51,7 +52,7 @@ To switch to the [product backlog](../backlogs/create-your-backlog.md), select * > [!TIP] > Select the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to make a team board a favorite. Favorite artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorite icon) appear at the top of the team selector list. -1. Check that you selected **Backlog items** for Scrum, **Stories** for Agile, or **Requirements** for CMMI as the backlog level. +2. Check that you selected **Backlog items** for Scrum, **Stories** for Agile, or **Requirements** for CMMI as the backlog level. > [!div class="mx-imgBorder"] > ![Select product backlog level, Backlog items, Stories, or Requirements](../sprints/media/assign-items-sprint/select-product-backlog-agile.png) @@ -59,26 +60,3 @@ To switch to the [product backlog](../backlogs/create-your-backlog.md), select * To switch to the [product backlog](../backlogs/create-your-backlog.md), select **Stories backlog**. To switch to a Taskboard, see [Update and monitor your Taskboard](../sprints/task-board.md). ::: moniker-end - - -::: moniker range="tfs-2018" - -1. To view your Kanban board, open your project from a web browser. Select **Work** > **Backlogs** > **Stories**, and then select **Board**. - - ![Open Portfolio Kanban board, features](../boards/media/quickstart/open-kanban-board.png) - - If you don't see **Work**, your screen size might be reduced. Select the three dots (:::image type="icon" source="../../media/ellipses-reduced-screen-size.png" border="false":::) icon. Then select **Work** > **Backlogs** > **Board**. - - ![Open Work when screen size is reduced](../boards/media/kanban-quickstart-reduced-screensize.png) - -1. To select another team, open the project and team selector. Select a different team, or select the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Select another team](../sprints/media/assign-items-sprint/team-selector-backlogs-standard.png) - - Your Kanban board appears. - - ![Kanban board, Agile template](../boards/media/kanban-basics-intro.png) - -::: moniker-end - \ No newline at end of file diff --git a/docs/boards/includes/open-queries.md b/docs/boards/includes/open-queries.md index 83a43a467bc..2cb12b7c580 100644 --- a/docs/boards/includes/open-queries.md +++ b/docs/boards/includes/open-queries.md @@ -3,41 +3,46 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 07/27/2021 +ms.date: 09/25/2024 --- #### [Browser](#tab/browser/) -::: moniker range=">= azure-devops-2019" +::: moniker range="< azure-devops" -From your web browser, (1) check that you have selected the right project, (2) choose **Boards>Queries**, and then (3) choose **All**. - -> [!div class="mx-imgBorder"] -> ![Open Boards>Queries, vertical nav](../queries/media/view-run-queries/open-queries-vert.png) +From your web browser, (1) check that you selected the right project, (2) choose **Boards > Queries**, and then (3) choose **All**. -If it is your first time opening **Queries**, the page opens to **Favorites**. This page lists those queries that you have indicated are a favorite. Otherwise, you can choose **All** to view all queries you've defined and shared queries defined for the project. +:::image type="content" source="../queries/media/view-run-queries/open-queries-vert.png" alt-text="Screenshot of the queries page."::: + +The **Queries** page opens to the **Favorites** tab that lists the queries you set as favorites. You can choose the **All** tab to view all queries you defined and shared queries for the project. > [!TIP] > Queries you or your team have chosen as favorites show up on the **Favorites** page. Favorite queries along with other objects also appear on your **Project** page. For more information, see [Set personal or team favorites](../../project/navigation/set-favorites.md). ::: moniker-end +::: moniker range="azure-devops" + +From your project, choose **Boards > Queries**, and then choose **All**. -::: moniker range="tfs-2018" +:::image type="content" source="../queries/media/view-run-queries/open-queries-new-boards-hubs.png" alt-text="Screenshot of the queries page."::: -From your web browser, open **Boards>Queries**. +The **Queries** page opens to the **Favorites** tab that lists the queries you set as favorites. You can choose the **All** tab to view all queries you defined and shared queries for the project. -![From your web browser, open Boards>Queries](../queries/media/view-run-queries/open-hub-page.png) +> [!TIP] +> Queries you or your team have chosen as favorites show up on the **Favorites** page. Favorite queries along with other objects also appear on your **Project** page. For more information, see [Set personal or team favorites](../../project/navigation/set-favorites.md). ::: moniker-end -#### [Visual Studio](#tab/visual-studio/) -> [!NOTE] -> To open, view, and run queries in Visual Studio 2019, you need to [Set the Work Items experience](../work-items/set-work-item-experience-vs.md) to the legacy option. +#### [Visual Studio](#tab/visual-studio/) + +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. + 1. From the Team Explorer home page, choose **Work Items**. :::image type="content" source="../media/team-explorer/open-work-items-team-explorer.png" alt-text="Screenshot of Team Explorer home page, choose Work Items."::: @@ -51,7 +56,7 @@ Or, select one of the following options: - **Edit Query**: Opens the [Query Editor](../queries/using-queries.md) for the selected query. - **New Query**: Opens the [Query Editor](../queries/using-queries.md) with the default new query options. - **Open in Microsoft Excel (Flat)**: [Opens the query in Microsoft Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). -- **Send to Microsoft Outlook**: [Open](../queries/share-plans.md) +- **Send to Microsoft Outlook**: [Open](../work-items/email-work-items.md) - **Cut**: Cuts the query. You can then paste the query under a different folder. - **Copy**: Copies the query. You can then paste the query under the same folder or a different folder. - **Delete**: [Deletes the query](../queries/organize-queries.md). diff --git a/docs/boards/includes/page-work-item-tasks.md b/docs/boards/includes/page-work-item-tasks.md index 30b58144e0c..9143bd000b9 100644 --- a/docs/boards/includes/page-work-item-tasks.md +++ b/docs/boards/includes/page-work-item-tasks.md @@ -5,7 +5,6 @@ author: chcomley ms.date: 01/04/2023 --- - ::: moniker range=">= azure-devops-2022" - [**Work items**](../work-items/view-add-work-items.md): Use to quickly find work items assigned to you or filter work items based on other criteria, such as work items that you follow, that you're mentioned in, or that you viewed or updated. @@ -17,8 +16,7 @@ ms.date: 01/04/2023 ::: moniker-end - -::: moniker range="azure-devops-2019 || azure-devops-2020" +::: moniker range="=azure-devops-2020" - [**Work items**](../work-items/view-add-work-items.md): Use to quickly find work items assigned to you or filter work items based on other criteria, such as work items that you follow, that you're mentioned in, or that you viewed or updated. - [**Boards**](../boards/kanban-quickstart.md): Use to implement Kanban practices, update the State, and visualize the flow of work for a team. @@ -28,15 +26,4 @@ ms.date: 01/04/2023 ::: moniker-end - -::: moniker range="tfs-2018" - -- [**Work items**](../work-items/view-add-work-items.md): Use to quickly find work items assigned to you or pivot or filter work items based on other criteria, such as work items that you follow, that you're mentioned in, or that you viewed or updated. -- **Backlogs**: Which provide access to: - - [**Product**](../backlogs/create-your-backlog.md) and [**Portfolio backlogs**](../backlogs/organize-backlog.md): Use to plan, prioritize, and organize the work for a team to do within a product or portfolio backlogs. - - [**Boards**](../boards/kanban-quickstart.md): Use to implement Kanban practices, update the State, and visualize the flow of work for a team. - - [**Sprint backlogs**](../sprints/assign-work-sprint.md): Use to plan work for a team to perform during a sprint. -- [**Queries**](../queries/view-run-query.md): Use to define a set of filter criteria to list work items for the purposes of sharing with others or performing bulk updates. - -::: moniker-end \ No newline at end of file diff --git a/docs/boards/includes/powerbi-reports-links.md b/docs/boards/includes/powerbi-reports-links.md index 62aef8fe812..5fc98b1e521 100644 --- a/docs/boards/includes/powerbi-reports-links.md +++ b/docs/boards/includes/powerbi-reports-links.md @@ -3,7 +3,7 @@ ms.topic: include --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### Analytics widgets and Power BI reports diff --git a/docs/boards/includes/prerequisites-kanban.md b/docs/boards/includes/prerequisites-kanban.md index 9a2fa0ded8e..ff469dce809 100644 --- a/docs/boards/includes/prerequisites-kanban.md +++ b/docs/boards/includes/prerequisites-kanban.md @@ -3,41 +3,34 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 08/03/2022 +ms.date: 09/11/2024 --- - -## Prerequisites - -Boards are automatically created when you create a project or add a team. Each team has access to their own product and portfolio boards as described in [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md#each-team-gets-their-own-set-of-tools). +Boards automatically get created when you create a project or add a team. Each team has access to their own product and portfolio boards as described in [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md#each-team-gets-their-own-set-of-tools). ::: moniker range="azure-devops" -* You must connect to a project. If you don't have a project yet, [create one](../get-started/sign-up-invite-teammates.md). -* You must be added to a [team or project](../../organizations/security/add-users-team-project.md). -* To add work items and exercise all board features, you must be granted [**Basic** access or higher](../../organizations/security/access-levels.md). -* To view or modify work items, your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* Users with **Stakeholder** access for a private project can add work items and update status through drag-and-drop, but cannot update fields displayed on cards. They can add tasks and change task status. -* Users with **Stakeholder** access for a public project have full access to board features just like users with **Basic** access. +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
- To add work items and use all board features: At least [**Basic** access](../../organizations/security/access-levels.md).
- Users with **Stakeholder** access:
- Public project: Full access to board features, similar to users with Basic access.
- Private project: Can add work items and update status through drag-and-drop but can't update fields displayed on cards, and can add tasks and change task status. | +| **Permissions** | To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has these permissions. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). | ::: moniker-end ::: moniker range="azure-devops-2022" -* You must connect to a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -* You must be added to a [team or project](../../organizations/security/add-users-team-project.md). -* To add work items and exercise all board features, you must be granted [**Basic** access or higher](../../organizations/security/access-levels.md). -* To view or modify work items, your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* Users with **Stakeholder** access for a private project can add work items and update status through drag-and-drop, but cannot update fields displayed on cards. They can add tasks and change task status. +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
- To add work items and use all board features: At least [**Basic** access](../../organizations/security/access-levels.md).
- Users with **Stakeholder** access for a private project can add work items and update status through drag-and-drop but can't update fields displayed on cards. They can add tasks and change task status. | +| **Permissions** | To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has these permissions. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). | ::: moniker-end ::: moniker range="< azure-devops-2022" -* You must connect to a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -* You must be added to a [team or project](../../organizations/security/add-users-team-project.md). -* To add work items and exercise all board features, you must be granted [**Basic** access or higher](../../organizations/security/access-levels.md). -* To view or modify work items, your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* Users with **Stakeholder** access can't exercise these board features: add work items, drag-and-drop work items to update status, or update fields displayed on cards. They can add tasks and change task status. +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
- To add work items and use all board features: At least [**Basic** access](../../organizations/security/access-levels.md).
- Users with **Stakeholder** access can't use these board features: Add work items, drag-and-drop work items to update status, or update fields displayed on cards. They can add tasks and change task status. | +| **Permissions** | To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has these permissions. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). | -::: moniker-end \ No newline at end of file +::: moniker-end diff --git a/docs/boards/includes/prerequisites-project-admin.md b/docs/boards/includes/prerequisites-project-admin.md new file mode 100644 index 00000000000..59ccb6b1a91 --- /dev/null +++ b/docs/boards/includes/prerequisites-project-admin.md @@ -0,0 +1,12 @@ +--- +ms.service: azure-devops-boards +ms.author: chcomley +author: chcomley +ms.topic: include +ms.date: 01/13/2025 +--- + +| Category | Requirements | +|--------------|-------------| +|**Project access**| [Project member](../../organizations/security/add-users-team-project.md).| +|**Permissions**| Member of the **Project Administrators** security group.| diff --git a/docs/boards/includes/prerequisites-queries.md b/docs/boards/includes/prerequisites-queries.md index 1e698024148..215d895634c 100644 --- a/docs/boards/includes/prerequisites-queries.md +++ b/docs/boards/includes/prerequisites-queries.md @@ -3,17 +3,16 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 09/07/2021 +ms.date: 01/13/2025 --- -## Prerequisites - ::: moniker range="azure-devops" -* By default, all project members and users with **Stakeholder** access can view and run all shared queries. You can change the permissions set for a shared query folder or shared query. For more information, see [Set query permissions](../queries/set-query-permissions.md). -* To add and save a query under **Shared queries**, you must be granted **Basic** access or higher. Also, you must have your **Contribute** permission set to **Allow** for the folder you want to add the query to. By default, the **Contributors** group doesn't have this permission. - +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - To view and run shared queries: [Project member](../../organizations/security/add-users-team-project.md).
- To add and save a shared query: At least **Basic** access. | +| **Permissions** | **Contribute** permission set to **Allow** for the folder that you want to add a query to. By default, the **Contributors** group doesn't have this permission. | > [!NOTE] > Users with **Stakeholder** access for a public project have full access to query features just like users with **Basic** access. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). @@ -22,8 +21,9 @@ ms.date: 09/07/2021 ::: moniker range="< azure-devops" -* By default, all project members and users with **Stakeholder** access can view and run all shared queries. You can change the permissions set for a shared query folder or shared query. For more information, see [Set query permissions](../queries/set-query-permissions.md). -* To add and save a query under **Shared queries**, you must be granted **Basic** access or higher. Also, you must have your **Contribute** permission set to **Allow** for the folder you want to add the query to. By default, the **Contributors** group doesn't have this permission. +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - To view and run shared queries: [Project member](../../organizations/security/add-users-team-project.md).
- To add and save a shared query: At least [**Basic** access](../../organizations/security/access-levels.md). | +| **Permissions** | **Contribute** permission set to **Allow** for the folder that you want to add a query to. By default, the **Contributors** group doesn't have this permission. | - -::: moniker-end \ No newline at end of file +::: moniker-end diff --git a/docs/boards/includes/prerequisites-team-settings.md b/docs/boards/includes/prerequisites-team-settings.md index 901abc2df30..632a744673a 100644 --- a/docs/boards/includes/prerequisites-team-settings.md +++ b/docs/boards/includes/prerequisites-team-settings.md @@ -3,27 +3,11 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 04/24/2023 +ms.date: 01/13/2025 --- -## Prerequisites - -::: moniker range="azure-devops" - -* To configure team settings, you must be added to the Team Administrator role or be a member of the **Project Administrators** security group. To get added, see [Add a team administrator](../../organizations/settings/add-team-administrator.md) or [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). -* You must be assigned **Basic** access or higher to exercise all backlog and board features. - Users with **Stakeholder** access can only edit work items on the board and add existing tags to a work item. Stakeholders can't add work items or update fields displayed on cards. - For more information, see [About access levels](../../organizations/security/access-levels.md#access-level-settings). - -::: moniker-end - -::: moniker range="< azure-devops" - -* To configure team settings, you must be added to the Team Administrator role or be a member of the **Project Administrators** security group. To get added, see [Add a team administrator](../../organizations/settings/add-team-administrator.md) or [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). -* You must be assigned **Basic** access or higher to exercise all backlog and board features. Users with **Stakeholder** access can only edit work items on the board and add existing tags to a work item. Stakeholders can't do the following tasks. For more information, see [About access levels](../../organizations/security/access-levels.md#access-level-settings). - * Add work items to a board - * Drag-and-drop work items to update status or reorder cards - * Update fields displayed on cards - -::: moniker-end +| Category | Requirements | +|--------------|-------------| +|**Access levels** | At least [**Basic**](../../organizations/security/access-levels.md) access.| +|**Permissions** | To configure team settings: Member of the **Project Administrators** security group or [**Team Administrator** role](../../organizations/settings/add-team-administrator.md). For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md).| diff --git a/docs/boards/includes/prerequisites-work-items.md b/docs/boards/includes/prerequisites-work-items.md index 7036c710d83..6cc3fc5190b 100644 --- a/docs/boards/includes/prerequisites-work-items.md +++ b/docs/boards/includes/prerequisites-work-items.md @@ -3,28 +3,22 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 01/27/2022 +ms.date: 01/13/2025 --- -## Prerequisites - -::: moniker range="azure-devops" - -* You must connect to a project. If you don't have a project yet, [create one](../get-started/sign-up-invite-teammates.md). -* You must be added to a project. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To view or modify work items, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* To add new tags to add to work items, you must have **Basic** access or higher and have the project-level **Create new tag definition** permissions set to **Allow**. By default, the **Contributors** group has this permission set. Even if the permission is explicitly set for a **Stakeholder**, they won't have permission to add new tags, as they are prohibited through their access level. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -* All project members, even those who belong to the **Readers** group, can email work items. - +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To view, follow, and edit work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has these permissions. For more information, see [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md).
- To add tags to work items: Project-level **Create new tag definition** permission set to **Allow**. By default, the **Contributors** group has this permission. | +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
- To add new tags to work items or to view or follow pull requests: At least [**Basic** access](../../organizations/security/access-levels.md).
- To view or follow work items: At least **Stakeholder** access. For more information, see [About access levels](../../organizations/security/access-levels.md).
- All project members, including those in the **Readers** group, can send emails containing work items. | +::: moniker range="azure-devops" + >[!NOTE] + >- Provide [Stakeholder access](../../organizations/security/access-levels.md) to members who want to contribute to the discussion and review progress. These are typically members who don't contribute to code, but want to view work items, backlogs, boards, and dashboards. + >- By default, all **Contributors** and **Stakeholders** in public projects can add new and existing tags. In private projects, Stakeholders can only add existing tags. To control the ability to create new tags, set the **Create tag definition** permission at the project level. For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). ::: moniker-end -::: moniker range="< azure-devops" - -* You must connect to a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -* You must be added to a project. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To view or modify work items, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* To add new tags to add to work items, you must have **Basic** access or higher and have the project-level **Create new tag definition** permissions set to **Allow**. By default, the **Contributors** group has this permission set. Even if the permission is explicitly set for a **Stakeholder**, they won't have permission to add new tags, as they are prohibited through their access level. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -* All project members, even those who belong to the **Readers** group, can email work items. -::: moniker-end \ No newline at end of file +::: moniker range=" < azure-devops" +>[!NOTE] +>- Provide [Stakeholder access](../../organizations/security/access-levels.md) to members who want to contribute to the discussion and review progress. These are typically members who don't contribute to code, but want to view work items, backlogs, boards, and dashboards. +::: moniker-end diff --git a/docs/boards/includes/prerequisites.md b/docs/boards/includes/prerequisites.md index 0a4a79d3a5a..de3f52c5ad2 100644 --- a/docs/boards/includes/prerequisites.md +++ b/docs/boards/includes/prerequisites.md @@ -3,34 +3,27 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 05/20/2022 +ms.date: 01/13/2025 --- - -## Prerequisites - -Backlogs are automatically created when you create a project or add a team. Each team has access to their own product, portfolio, and sprint backlogs as described in [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md#each-team-gets-their-own-set-of-tools). - ::: moniker range="azure-devops" -* You must connect to a project. If you don't have a project yet, [create one](../get-started/sign-up-invite-teammates.md). -* You must be added to a project as a member of the **Contributors** or **Project Administrators** security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To add or modify work items, you must be granted **Stakeholder** access or higher. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -* To view or modify work items, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* To use the **Planning** pane, the sprints that you want to assign work to must have been selected for your team by a team administrator. For more information, see [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). - -> [!NOTE] -> Users with **Stakeholder** access for a public project have full access to backlog and board features just like users with **Basic** access. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). - +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Permissions** | - Member of the **Contributors** or **Project Administrators** security group.
- To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set to **Allow**. For more information, see [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md). | +| **Access levels** | To add or modify work items: At least [**Basic** access](../../organizations/security/stakeholder-access.md). Users with **Stakeholder** access for public projects have full access to backlog and board features, like users with **Basic** access. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). | +| **Defined iterations** | To use the **Planning** pane: Ensure your team administrator [defined iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). | ::: moniker-end ::: moniker range="< azure-devops" -* You must connect to a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -* You must be added to a project as a member of the **Contributors** or **Project Administrators** security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To add or modify work items, you must be granted **Stakeholder** access or higher. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -* To view or modify work items, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* To use the **Planning** pane, the sprints that you want to assign work to must have been selected for your team by a team administrator. For more information, see [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Permissions** | - Member of the **Contributors** or **Project Administrators** security group.
- To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set to **Allow**. For more information, see [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md). | +| **Access levels** | To add or modify work items: At least [**Basic** access](../../organizations/security/stakeholder-access.md). | +| **Defined iterations** | To use the **Planning** pane: Ensure your team administrator [defined iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). | -::: moniker-end \ No newline at end of file +::: moniker-end diff --git a/docs/boards/includes/process-customize.md b/docs/boards/includes/process-customize.md index efb3edbe130..ac91b98c0d7 100644 --- a/docs/boards/includes/process-customize.md +++ b/docs/boards/includes/process-customize.md @@ -3,31 +3,22 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 06/07/2023 +ms.date: 07/02/2024 --- ::: moniker range="azure-devops" > [!NOTE] -> You can customize the work tracking system for your project by creating and customizing an inherited process and applying that process to your project. For more information, see [Inheritance process model](../../organizations/settings/work/inheritance-process-model.md). +> - You can customize the work tracking system for your project by creating and customizing an inherited process and applying that process to your project. For more information, see [Inheritance process model](../../organizations/settings/work/inheritance-process-model.md). +> - You can also customize a process template. For more information, see [About processes and process templates](../work-items/guidance/choose-process.md). ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!NOTE] -> You can customize the work tracking system for your project by customizing an Inherited process or an On-premises XML process. For more information, see [Inheritance process model](../../organizations/settings/work/inheritance-process-model.md) or [On-premises XML process customization](../../reference/on-premises-xml-process-model.md). -> -> The latest version of each process uploads automatically when you install or upgrade to the latest version of Azure DevOps Server. Additional artifacts, such as SQL Server reports are only available when you connect to a project. Other resource requirements apply. - -::: moniker-end - -::: moniker range="tfs-2018" - -> [!NOTE] -> You can customize the work tracking system for your project by customizing an On-premises XML process. For more information, see [On-premises XML process customization](../../reference/on-premises-xml-process-model.md). -> -> The latest version of each process uploads automatically when you install or upgrade to the latest version of Azure DevOps Server. Additional artifacts, such as SQL Server reports are only available when you connect to a project. Other resource requirements apply. +> - You can customize the work tracking system for your project by customizing an Inherited process or an On-premises XML process. For more information, see [Inheritance process model](../../organizations/settings/work/inheritance-process-model.md) or [On-premises XML process customization](../../reference/on-premises-xml-process-model.md). The latest version of each process uploads automatically when you install or upgrade to the latest version of Azure DevOps Server. Additional artifacts, such as SQL Server reports are only available when you connect to a project. Other resource requirements apply. +> - You can also customize a process template. For more information, see [About processes and process templates](../work-items/guidance/choose-process.md). ::: moniker-end diff --git a/docs/boards/includes/quick-tips-shared-query.md b/docs/boards/includes/quick-tips-shared-query.md index 6df7c4ec8f2..596c28167ab 100644 --- a/docs/boards/includes/quick-tips-shared-query.md +++ b/docs/boards/includes/quick-tips-shared-query.md @@ -3,24 +3,17 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 07/22/2021 +ms.date: 09/09/2024 --- -You can [view and run queries](../queries/view-run-query.md) from the web portal or from the Team Explorer plug-in to Visual Studio. You can also modify a query using the [query editor to apply different filter criteria](../queries/using-queries.md) and [add queries to team dashboards](../../report/dashboards/dashboards.md). +[View and run queries](../queries/view-run-query.md) from the web portal or from the Team Explorer plug-in for Visual Studio. Modify a query using the [query editor to apply different filter criteria](../queries/using-queries.md) and [add queries to team dashboards](../../report/dashboards/dashboards.md). ### Tips for shared queries -Manage work more effectively with the following tips: +Enhance your workflow using the following tips: -- Find work items assigned to you by adding **@Me** as the value for the Assigned To field in one of the query clauses. -- Modify any query by adding criteria to focus on a product area, an iteration, or another field. To modify a query, [open the query editor](../queries/using-queries.md). -- Open any query in [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) where you can update the fields of one or more work items and publish your changes to the database for tracking work items. -- [Visualize status or progress](../../report/dashboards/charts.md) by creating a pie-chart, column chart, or trend chart for flat-list queries. -- All valid users with standard access can create queries and folders under the **My Queries** area. To create queries and query folders under **Shared Queries**, you must have the Contribute permission set and have been assigned Basic access or greater. For more information, see [Set permissions on queries](../queries/set-query-permissions.md). - -::: moniker range=">= azure-devops-2019" - -> [!IMPORTANT] -> Starting with Visual Studio 2019, the Azure DevOps plug-in for Office has deprecated support for Microsoft Project. Project integration and the **TFSFieldMapping** command is not supported for Azure DevOps Server 2019 and later versions, including Azure DevOps Services. You can continue to use Microsoft Excel. - -::: moniker-end +- Add **@Me** as the value for the Assigned To field in a query clause to find work items assigned to you. +- [Open the query editor](../queries/using-queries.md) to modify any query by adding criteria for a product area, iteration, or another field. +- [Open a query in Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) to update fields of one or more work items and publish changes to the database. +- [Create a pie-chart, column chart, or trend chart](../../report/dashboards/charts.md) to visualize status or progress for flat-list queries. +- Create queries and folders under the **My Queries** area with standard access. To create queries and folders under **Shared Queries**, ensure you have the Contribute permission and at least Basic access. For more information, see [Set permissions on queries](../queries/set-query-permissions.md). diff --git a/docs/boards/includes/section-basic-field-descriptions.md b/docs/boards/includes/section-basic-field-descriptions.md index 4d45a38976b..4e667274024 100644 --- a/docs/boards/includes/section-basic-field-descriptions.md +++ b/docs/boards/includes/section-basic-field-descriptions.md @@ -89,7 +89,7 @@ ms.date: 09/21/2020 :::column-end::: :::column span="3"::: Provide the criteria to be met before the work item can be closed. Define what "Done" means by describing the criteria for the team to use to verify whether the backlog item or bug fix is fully implemented. - Before work begins, describe the [criteria for customer acceptance](../backlogs/best-practices-product-backlog.md#acceptance) as clearly as possible. Have conversations between the team and customers to determine the acceptance criteria. These criteria help ensure a common understanding within the team to meet customers' expectations. Also, this information provides the basis for acceptance testing. + Before work begins, describe the criteria for customer acceptance as clearly as possible. Have conversations between the team and customers to determine the acceptance criteria. These criteria help ensure a common understanding within the team to meet customers' expectations. Also, this information provides the basis for acceptance testing. :::column-end::: :::row-end::: --- @@ -99,10 +99,10 @@ ms.date: 09/21/2020 :::column-end::: :::column span="3"::: A subjective rating of the issue or task it relates to the business. You can specify the following values: - - **1**: Product cannot ship without the successful resolution of the work item, and it should be addressed as soon as possible. - - **2**: Product cannot ship without the successful resolution of the work item, but it does not need to be addressed immediately. - - **3**: Resolution of the work item is optional based on resources, time, and risk. - - **4**: Resolution of the work item is not required. + - **1**: Product can't ship without the successful resolution of the work item, and it should be addressed as soon as possible. + - **2**: Product can't ship without the successful resolution of the work item, but it doesn't need to be addressed immediately. + - **3**: Resolution of the work item is optional, based on resources, time, and risk. + - **4**: Resolution of the work item isn't required. :::column-end::: :::row-end::: --- @@ -112,7 +112,7 @@ ms.date: 09/21/2020 :::column-end::: :::column span="3"::: A subjective rating of the issue or task it relates to the business. You can specify the following values: - - **Architectural**: Technical services to implement business features that deliver solution . + - **Architectural**: Technical services to implement business features that deliver solution. - **Business**: Services that fulfill customers or stakeholder needs that directly deliver customer value to support the business (Default). :::column-end::: :::row-end::: diff --git a/docs/boards/includes/section-cmmi-field-descriptions.md b/docs/boards/includes/section-cmmi-field-descriptions.md index 0bd7c346b2a..2b6fa56f50f 100644 --- a/docs/boards/includes/section-cmmi-field-descriptions.md +++ b/docs/boards/includes/section-cmmi-field-descriptions.md @@ -23,13 +23,13 @@ ms.date: 09/21/2020 [Impact Assessment](/previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-requirements-field-reference-cmmi) :::column-end::: :::column span="3"::: - The customer impact of not implementing this requirement. You might include details from the Kano model about whether this requirement is in the surprise, required, or obvious categories. You capture this information in the rich-text HTML field which corresponds to Impact Assessment. + The effect on the customer of not implementing this requirement. You might include details from the Kano model about whether this requirement is in the surprise, required, or obvious categories. You capture this information in the rich-text HTML field that corresponds to Impact Assessment. :::column-end::: :::row-end::: --- :::row::: :::column span=""::: - [Requirement Type](/previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-requirements-field-reference-cmmi)(Required) + [Requirement Type](/previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-requirements-field-reference-cmmi) (Required) :::column-end::: :::column span="3"::: The kind of requirement to implement. You can specify one of the following values: @@ -50,8 +50,8 @@ ms.date: 09/21/2020 [Start Date/Finish Date](../queries/query-by-date-or-current-iteration.md) :::column-end::: :::column span="3"::: - The target dates for when the work to start or finish. These fields are filled in by Microsoft Project when you use it for scheduling. - You can specify work in hours or in days. There are no inherent time units associated with this field. + The target dates for when the work is expected to start or finish. These fields are filled in by Microsoft Project when you use it for scheduling. + You can specify work in hours or in days. No inherent time units are associated with this field. :::column-end::: :::row-end::: --- @@ -60,7 +60,7 @@ ms.date: 09/21/2020 [Triage](../queries/planning-ranking-priorities.md) (Required) :::column-end::: :::column span="3"::: - Indicates the type of triage decision that is pending for the work item. Use this field when the work item is in the *Proposed* state and specify one of the following values: **Pending** (default), **More Info**, **Info Received**, or **Triaged**. + Indicates the type of triage decision that's pending for the work item. Use this field when the work item is in the `Proposed` state and specify one of the following values: **Pending** (default), **More Info**, **Info Received**, or **Triaged**. :::column-end::: :::row-end::: --- @@ -69,7 +69,7 @@ ms.date: 09/21/2020 [Blocked](../queries/planning-ranking-priorities.md) :::column-end::: :::column span="3"::: - Indicates whether a team member is prevented from making progress toward implementing a requirement or task or resolving a bug, change request, or risk. If an issue has been opened to track a blocking problem, you can create a link to the issue. You can specify **Yes** or **No** (default). + Indicates whether a team member is prevented from making progress toward implementing a requirement or task or resolving a bug, change request, or risk. If an issue was opened to track a blocking problem, you can create a link to the issue. You can specify **Yes** or **No** (default). :::column-end::: :::row-end::: --- @@ -87,7 +87,7 @@ ms.date: 09/21/2020 [Integrated In](../queries/build-test-integration.md) :::column-end::: :::column span="3"::: - Product build number that incorporates the requirement, change request, or fixes a bug. + Product build number that incorporates the requirement or change request, or fixes a bug. :::column-end::: :::row-end::: --- @@ -103,7 +103,8 @@ ms.date: 09/21/2020 - **Ready** - **Skipped** - **Info Received** - Specify **Not Ready** when the requirement is in the Active state, and you specify **Ready** when the requirement is in the Resolved state. + + Specify **Not Ready** when the requirement is in the `Active` state. Specify **Ready** when the requirement is in the `Resolved` state. :::column-end::: :::row-end::: --- diff --git a/docs/boards/includes/section-portfolio-backlog-requirements.md b/docs/boards/includes/section-portfolio-backlog-requirements.md index 45ddd9ba9f9..63fb42fcac2 100644 --- a/docs/boards/includes/section-portfolio-backlog-requirements.md +++ b/docs/boards/includes/section-portfolio-backlog-requirements.md @@ -8,7 +8,7 @@ ms.date: 06/24/2020 --- - + ## Portfolio backlog requirements diff --git a/docs/boards/includes/setup-backlogs-boards.md b/docs/boards/includes/setup-backlogs-boards.md index 8375f9a2f52..1689eea9ee2 100644 --- a/docs/boards/includes/setup-backlogs-boards.md +++ b/docs/boards/includes/setup-backlogs-boards.md @@ -3,5 +3,4 @@ ms.topic: include --- > [!NOTE] -> For more information, see [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md). In case you're not seeing the desired work items on your backlog or board, see [Set up your backlogs and boards](../backlogs/set-up-your-backlog.md) to configure them according to your preferences. - +> For more information, see [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md). In case you don't see the desired work items on your backlog or board, see [Set up your backlogs and boards](../backlogs/set-up-your-backlog.md). diff --git a/docs/boards/includes/shared-queries.md b/docs/boards/includes/shared-queries.md index 90ac3eb729b..3af9b653c1b 100644 --- a/docs/boards/includes/shared-queries.md +++ b/docs/boards/includes/shared-queries.md @@ -3,9 +3,5 @@ ms.topic: include --- -::: moniker range=">= azure-devops-2019" - > [!NOTE] > When you create a new project, there's no longer a default set of **Shared Queries**. The definitions for **Shared Queries** were removed from the process template. For on-premises deployments, you can add them to a custom process template as described in [Add work item queries to a process template](/previous-versions/azure/devops/reference/process-templates/add-work-item-queries-process-template). - -::: moniker-end diff --git a/docs/boards/includes/show-bugs-matrix-options.md b/docs/boards/includes/show-bugs-matrix-options.md index ff52c91713f..9b2ca6d2586 100644 --- a/docs/boards/includes/show-bugs-matrix-options.md +++ b/docs/boards/includes/show-bugs-matrix-options.md @@ -21,32 +21,32 @@ ms.date: 04/30/2021 Track bugs as Requirements :::column-end::: :::column span="3"::: - - Prioritize (stack rank) bugs along with requirements - - Estimate Bug effort for forecasting - - Update bug status on Kanban board - - Include Bugs in [Velocity charts](../../report/dashboards/team-velocity.md) and [Cumulative Flow Diagrams](../../report/dashboards/cumulative-flow.md) - - Can use the [**Forecast** tool](../sprints/forecast.md) to support sprint planning - - Can drag and drop bugs onto [**Planning**](../sprints/assign-work-sprint.md#assign-work-from-your-backlog-to-a-sprint) pane to assign bugs to a sprint - - Can view Bugs on [Delivery Plans](../plans/review-team-plans.md) - > [!NOTE] - > - Bugs are assigned to the Requirements Category + - Prioritize, or stack rank, bugs along with requirements + - Estimate Bug effort for forecasting + - Update bug status on board + - Include Bugs in [Velocity charts](../../report/dashboards/team-velocity.md) and [Cumulative Flow Diagrams](../../report/dashboards/cumulative-flow.md) + - Be able to use the [Forecast tool](../sprints/forecast.md) to support sprint planning + - Drag bugs to the [Planning](../sprints/assign-work-sprint.md#assign-work-from-your-backlog-to-a-sprint) pane to assign bugs to a sprint + - View Bugs on [Delivery Plans](../plans/review-team-plans.md) + > [!NOTE] + > - Bugs are assigned to the Requirements Category :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - Track bugs as Tasks + Track bugs as Tasks :::column-end::: :::column span="3"::: - Estimate work for bugs similar to tasks - Update bug status on sprint Taskboards - Link bugs to requirements as child items - - Can drag and drop bugs onto Planning pane to assign bugs to a sprint - > [!NOTE] + - Drag bugs to the Planning pane to assign bugs to a sprint + > [!NOTE] > - Bugs are assigned to the Task Category - > - User Stories (Agile), Product Backlog Items (Scrum), or Requirements (CMMI) are the natural parent work item type for Bugs - > - Bugs won't be visible on Delivery Plans + > - User Stories (Agile), Product Backlog Items (Scrum), or Requirements (CMMI) are the natural parent work item type for Bugs + > - Bugs aren't visible on Delivery Plans :::column-end::: :::row-end::: --- @@ -55,11 +55,11 @@ ms.date: 04/30/2021 Bugs don't appear on backlogs or boards :::column-end::: :::column span="3"::: - - Manage bugs using queries - > [!NOTE] - > - Bugs are associated with the Bugs Category and won't appear on either backlogs or boards - > - Bugs won't be visible on Backlogs, Boards, Sprint Backlogs, Taskboards, or Delivery Plans - > - Can't drag and drop bugs onto Planning pane to assign bugs to a sprint + - Manage bugs using queries + > [!NOTE] + > - Bugs are associated with the Bugs Category and don't appear on either backlogs or boards + > - Bugs aren't visible on Backlogs, Boards, Sprint Backlogs, Taskboards, or Delivery Plans + > - You can't drag bugs to the Planning pane to assign bugs to a sprint :::column-end::: :::row-end::: --- diff --git a/docs/boards/includes/team-configuration.md b/docs/boards/includes/team-configuration.md index f834980b628..5ccfbeded2d 100644 --- a/docs/boards/includes/team-configuration.md +++ b/docs/boards/includes/team-configuration.md @@ -47,12 +47,11 @@ ms.date: 01/09/2020 :::column-end::: :::column span="3"::: - [Select active iteration paths (sprints)](../../organizations/settings/set-iteration-paths-sprints.md) - - [Set working days](../../organizations/settings/set-working-days.md) :::column-end::: :::row-end::: :::row::: :::column span="1"::: - Kanban boards + Boards :::column-end::: :::column span="3"::: - [Kanban board](../boards/kanban-overview.md) @@ -74,7 +73,7 @@ ms.date: 01/09/2020 :::column-end::: :::column span="3"::: - [New work item](../../report/dashboards/widget-catalog.md#new-work-item-widget) - - [Sprint burndown](../../report/dashboards/widget-catalog.md#sprint-burndown-widget) + - [Sprint burndown](../../report/dashboards/widget-catalog.md#burndown-widget) - [Sprint capacity](../../report/dashboards/widget-catalog.md#sprint-capacity-widget) - [Sprint overview](../../report/dashboards/widget-catalog.md#sprint-overview-widget) - [Team members](../../report/dashboards/widget-catalog.md#team-members-widget) diff --git a/docs/boards/includes/tip-wiql-extension.md b/docs/boards/includes/tip-wiql-extension.md index 3a12b51ad8a..27039d9a2ee 100644 --- a/docs/boards/includes/tip-wiql-extension.md +++ b/docs/boards/includes/tip-wiql-extension.md @@ -4,9 +4,9 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include -ms.date: 01/16/2020 +ms.date: 03/11/2024 --- > [!TIP] -> To view the WIQL syntax for a query, and how parenthesis are used to group clauses, install the [Marketplace Wiql Editor](https://marketplace.visualstudio.com/items?itemName=ottostreifel.wiql-editor). This extension supports viewing the WIQL syntax and exporting it to a WIQL file for use in REST API calls. For more information, see [Syntax for the Work Item Query Language (WIQL)](../queries/wiql-syntax.md). \ No newline at end of file +> To view the WIQL syntax for a query, and how parenthesis are used to group clauses, install the [Marketplace Wiql Editor](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.wiql-editor). This extension supports viewing the WIQL syntax and exporting it to a WIQL file for use in REST API calls. For more information, see [Syntax for the Work Item Query Language (WIQL)](../queries/wiql-syntax.md). \ No newline at end of file diff --git a/docs/boards/includes/velocity-section.md b/docs/boards/includes/velocity-section.md index 7bb2f084f04..df304de6fa7 100644 --- a/docs/boards/includes/velocity-section.md +++ b/docs/boards/includes/velocity-section.md @@ -6,28 +6,18 @@ ms.topic: include ms.date: 07/09/2020 --- - -## Velocity +## Velocity ::: moniker range=">= azure-devops-2020" -When you assign your backlog items to sprints, you'll gain access to an in-context velocity report for both product and portfolio backlogs. Velocity helps teams determine how much work they can perform sprint-over-sprint. - -You can quickly configure the Velocity report to count work items or sum Story Points, Effort, Remaining Work or other numeric field. - -> [!div class="mx-imgBorder"] -> ![Open Velocity Analytics](../../report/dashboards/media/velocity/analytics-velocity-azure-devops.png) - -::: moniker-end - -::: moniker range="< azure-devops-2020" +When you assign your backlog items to sprints, you gain access to an in-context velocity report for both product and portfolio backlogs. Velocity helps teams determine how much work they can perform sprint-over-sprint. -When you assign your product backlog items to sprints, you'll gain access to an in-context velocity report for your product backlog. Velocity helps teams determine how much work they can perform sprint-over-sprint. +You can configure the Velocity report to count work items or sum Story Points, Effort, Remaining Work or other numeric field. -The report tracks the team's estimated backlog work—sum of Effort (Basic or Scrum processes), Story Points (Agile process), or Size (CMMI process—that your team has completed (green) in the previous sprints, or that are still in progress (blue). +:::image type="content" source="../../report/dashboards/media/velocity/analytics-velocity-azure-devops.png" alt-text="Screenshot shows Velocity Analytics which displays a bar chart."::: -![Web portal, Velocity chart showing seven sprints of in progress and completed work](../../report/dashboards/media/team-velocity-chart-web-7-iterations.png) +::: moniker-end -::: moniker-end + -For more information, see [View or configure team velocity](../../report/dashboards/team-velocity.md) +For more information, see [View and configure team velocity](../../report/dashboards/team-velocity.md). diff --git a/docs/boards/includes/view-linked-objects.md b/docs/boards/includes/view-linked-objects.md deleted file mode 100644 index 3a835862bae..00000000000 --- a/docs/boards/includes/view-linked-objects.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -ms.service: azure-devops-boards -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 08/04/2021 ---- - - - - - -## View list of linked objects - -To view the list of all objects linked to a work item, open the work item and choose the :::image type="icon" source="../media/icons/icon-links-tab-wi.png" border="false"::: **Links** tab. The links tab indicates the count of all linked objects. - -:::image type="content" source="../media/view-link-list/links-tab-link-count.png" alt-text="Screenshot of Links tab with count of linked objects. "::: - -Linked objects are grouped under their link type, with a count within each group. You can expand or collapse each group, and sort within each group by **State**, **Latest Update**, or **Comment** by choosing the corresponding column title. - -For example, the following **Links** tab shows a portion of the 64 linked objects for a work item. - -:::image type="content" source="../media/view-link-list/list-linked-objects-links-tab.png" alt-text="Screenshot of Links tab with many linked objects."::: - -Links prefaced with the :::image type="icon" source="../../media/icons/required-icon.png" border="false"::: red exclamation mark indicate that the build, release, or other object has been deleted. This is usually due to retention policies which automatically delete these objects after a certain time period has passed. \ No newline at end of file diff --git a/docs/boards/includes/work-item-types.md b/docs/boards/includes/work-item-types.md index 278338d77e2..2b0f7bd2d7d 100644 --- a/docs/boards/includes/work-item-types.md +++ b/docs/boards/includes/work-item-types.md @@ -7,41 +7,53 @@ author: chcomley ms.date: 05/25/2022 --- -#### [Agile process](#tab/agile-process) +#### [Agile process](#tab/agile-process) -The following image shows the Agile process backlog work item hierarchy. User Stories and Tasks are used to track work, Bugs track code defects, and Epics and Features are used to group work under larger scenarios. +The following image shows the hierarchy for the Agile process backlog work item: -> [!div class="mx-tdCol2BreakAll"] -> ![Conceptual image, Agile work item type.](../work-items/guidance/media/ALM_PT_Agile_WIT_Artifacts.png) +:::image type="content" source="../work-items/guidance/media/ALM_PT_Agile_WIT_Artifacts.png" alt-text="Diagram that shows Agile work item types."::: -Each team can configure how they manage Bugs—at the same level as User Stories or Tasks—by configuring the [Working with bugs](../../organizations/settings/show-bugs-on-backlog.md) setting. For more information about using these work item types, see [Agile process](../work-items/guidance/agile-process.md). +- User Stories and tasks are used to track work. +- Bugs track code defects. +- Epics and features are used to group work under larger scenarios. -#### [Basic process](#tab/basic-process) +Each team can configure how they manage Bug work items at the same level as User Story or Task work items. Use the [Working with bugs](../../organizations/settings/show-bugs-on-backlog.md) setting. For more information about using these work item types, see [Agile process](../work-items/guidance/agile-process.md). -The following image shows the Basic process backlog work item hierarchy. Issues and Tasks are used to track work, while Epics are used to group work under larger scenarios. The Basic process is available with [Azure DevOps Server 2019 Update 1](https://go.microsoft.com/fwlink/?LinkId=2097609) and later versions. +#### [Basic process](#tab/basic-process) -> [!div class="mx-imgBorder"] -> ![Conceptual image, Basic work item types.](../get-started/media/about-boards/basic-process-epics-issues-tasks-2.png) +The following image shows the hierarchy for the Basic process backlog work item: + +:::image type="content" source="../get-started/media/about-boards/basic-process-epics-issues-tasks-2.png" alt-text="Diagram that shows Basic work item types."::: + +- Issues and tasks are used to track work. +- Epics are used to group work under larger scenarios. + +The Basic process is available with [Azure DevOps Server 2019 Update 1](https://go.microsoft.com/fwlink/?LinkId=2097609) and later versions. For more information about using these work item types, see [Plan and track work](../get-started/plan-track-work.md). -#### [Scrum process](#tab/scrum-process) +#### [Scrum process](#tab/scrum-process) + +The following image shows the hierarchy for the Scrum process backlog work item: -The following image shows the Scrum process backlog work item hierarchy. Product Backlog Items and Tasks are used to track work, Bugs track code defects, and Epics and Features are used to group work under larger scenarios. +:::image type="content" source="../work-items/guidance/media/ALM_PT_Scrum_WIT_Artifacts.png" alt-text="Diagram that shows Scrum work item types."::: -> [!div class="mx-tdCol2BreakAll"] -> ![Conceptual image, Scrum work item types.](../work-items/guidance/media/ALM_PT_Scrum_WIT_Artifacts.png) +- Product backlog items and Tasks are used to track work. +- Bugs track code defects. +- Epics and features are used to group work under larger scenarios. +Each team can configure how they manage bugs at the same level as product backlog items or Tasks. Use the [Working with bugs](../../organizations/settings/show-bugs-on-backlog.md) setting. For more information about using these work item types, see [Scrum process](../work-items/guidance/scrum-process.md). -Each team can configure how they manage bugs—at the same level as Product Backlog Items or Tasks—by configuring the [Working with bugs](../../organizations/settings/show-bugs-on-backlog.md) setting. For more information about using these work item types, see [Scrum process](../work-items/guidance/scrum-process.md). +#### [CMMI process](#tab/cmmi-process) -#### [CMMI process](#tab/cmmi-process) +The following image shows the hierarchy for the CMMI process backlog work item: -The following image shows the CMMI process backlog work item hierarchy. Requirements and Tasks are used to track work, Bugs track code defects, and Epics and Features are used to group work under larger scenarios. +:::image type="content" source="../work-items/guidance/media/ALM_PT_CMMI_WIT_Artifacts.png" alt-text="Diagram that shows CMMI work item types."::: -> [!div class="mx-tdCol2BreakAll"] -> ![Conceptual image, CMMI work item types.](../work-items/guidance/media/ALM_PT_CMMI_WIT_Artifacts.png) +- Requirements and Tasks are used to track work. +- Bugs track code defects. +- Epics and features are used to group work under larger scenarios. -Each team can configure how they manage bugs—at the same level as Requirements or Tasks—by configuring the [Working with bugs](../../organizations/settings/show-bugs-on-backlog.md) setting. For more information about using these work item types, see [CMMI process](../work-items/guidance/cmmi-process.md). +Each team can configure how they manage bugs at the same level as requirements or tasks. Use the [Working with bugs](../../organizations/settings/show-bugs-on-backlog.md) setting. For more information about using these work item types, see [CMMI process](../work-items/guidance/cmmi-process.md). * * * diff --git a/docs/boards/index.yml b/docs/boards/index.yml index 20bf8c2ed81..90069f161b4 100644 --- a/docs/boards/index.yml +++ b/docs/boards/index.yml @@ -10,7 +10,7 @@ metadata: ms.topic: landing-page author: chcomley ms.author: chcomley - ms.date: 03/16/2023 + ms.date: 04/24/2024 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -32,6 +32,8 @@ landingContent: url: ./work-items/guidance/choose-process.md - text: Agile process workflow url: ./work-items/guidance/agile-process-workflow.md + - text: Best practices for Agile project management + url: best-practices-agile-project-management.md - title: Get started linkLists: - linkListType: quickstart @@ -66,15 +68,15 @@ landingContent: linkLists: - linkListType: quickstart links: - - text: Kanban board quickstart + - text: Board quickstart url: ./boards/kanban-quickstart.md - linkListType: tutorial links: - - text: Kanban board overview + - text: Board overview url: ./boards/kanban-overview.md - text: Add columns url: ./boards/add-columns.md - - text: Customize your Kanban board + - text: Customize your board url: ./configure-customize.md - title: Implement Scrum linkLists: @@ -96,7 +98,7 @@ landingContent: links: - text: Create managed queries url: ./queries/using-queries.md - - text: Perform ad hoc searches + - text: Do ad hoc searches url: ./queries/search-box-queries.md - text: Define, triage, & manage bugs url: ./backlogs/manage-bugs.md @@ -108,12 +110,12 @@ landingContent: links: - text: Connect Azure Boards to GitHub url: ./github/connect-to-github.md - - text: Link GitHub commits, pull requests, & issues to work items + - text: Link GitHub commits, pull requests, & branches to work items url: ./github/link-to-from-github.md - linkListType: concept links: - - text: Link work items to support traceability - url: ./queries/link-work-items-support-traceability.md + - text: Link work items to other objects + url: ./backlogs/add-link.md - linkListType: tutorial links: - text: Use work item templates @@ -142,7 +144,7 @@ landingContent: url: ../organizations/settings/work/customize-process-workflow.md - text: See more... url: ../reference/index.yml - - title: Agile at Scale + - title: Agile at scale linkLists: - linkListType: tutorial links: @@ -156,7 +158,7 @@ landingContent: linkLists: - linkListType: how-to-guide links: - - text: Fix re-ordering & nesting issues + - text: Fix reordering & nesting issues url: ./backlogs/resolve-backlog-reorder-issues.md - text: Set up your Backlogs & Boards url: ./backlogs/set-up-your-backlog.md @@ -172,8 +174,6 @@ landingContent: url: ./queries/query-index-quick-ref.md - text: Work item field index url: ./work-items/guidance/work-item-field.md - - text: Default work tracking permissions - url: ../organizations/security/permissions-access-work-tracking.md - title: Developer resources linkLists: - linkListType: reference diff --git a/docs/boards/integrations/boards-slack.md b/docs/boards/integrations/boards-slack.md index a395553aa17..4be29bf8c24 100644 --- a/docs/boards/integrations/boards-slack.md +++ b/docs/boards/integrations/boards-slack.md @@ -25,43 +25,33 @@ events in their Slack channel. Conversations in the Slack channel can be used to ![Pic: Notification](./media/integrations-slack/notifications.png) -Read this article to learn how to: - -> [!div class="checklist"] -> * Add the Azure Boards app to your Slack workspace -> * Link and unlink your Azure Boards project to the Azure Boards app -> * Set up subscriptions to work item related events in your Slack channel -> * Create work items from your Slack channel -> * Monitor work item activity in your Slack channel -> * Get notifications in private Slack channels - > [!NOTE] > * Azure Boards and Slack integration is only supported for Azure DevOps Services. > * Notifications are currently not supported inside direct messages. ## Prerequisites -- To create a work item, you must be a contributor to the Azure Boards project. If you don't have a project yet, you can sign up and create a project. For more information, see [Start using Azure Boards](../get-started/index.md). -- To create subscriptions in a Slack channel for work item events, you must be a member of the Azure Boards Project Administrators group or Team Administrators group. To get added, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) or [Add Team Administrator](../../organizations/settings/add-team-administrator.md). -- To receive notifications, the **Third party application access via OAuth** setting must be enabled for the organization. See [Change application access policies for your organization](../../organizations/accounts/change-application-access-policies.md) - - +| Category | Requirements | +|--------------|-------------| +| **Access levels** | **Contributor** for the project. | +| **Permissions** | To create subscriptions in a Slack channel for work item events: Member of the [Project Administrators](../../organizations/security/change-project-level-permissions.md) or [Team Administrators](../../organizations/settings/add-team-administrator.md) group. | +| **Policies** | To receive notifications: [**Third party application access via OAuth** policy enabled for the organization](../../organizations/accounts/change-application-access-policies.md). | ## Add the Azure Boards app to your Slack workspace 1. To install the Azure Boards app to your Slack workspace, open a web browser, sign into Slack, and open the [Azure Boards app](https://azchatopprodcus1.azchatops.visualstudio.com/_slack/installboardsapp). -1. Once added, you'll see a welcome message from the app as shown in the following image. +2. Once added, a welcome message displays from the app as shown in the following image. ![Pic: Welcome message](./media/integrations-slack/welcome-message.png) -1. Use the `/azboards` Slack handle to interact with the app. A list of commands is provided later in this article, [Command reference](#command-reference). +3. Use the `/azboards` Slack handle to interact with the app. A list of commands is provided later in this article, [Command reference](#command-reference). ## Link your Azure Boards project to the Azure Boards app To use the app, you must first link your Azure Boards project to your Slack channel. -1. Once the app has been installed in your Slack workspace, connect and authenticate yourself to Azure Boards. +1. Once the app gets installed in your Slack workspace, connect and authenticate yourself to Azure Boards. ![screenshot of sign-in](./media/integrations-slack/signin.png) @@ -94,7 +84,7 @@ filters to customize your Slack channel. To easily set up subscriptions, your re ## Add area paths -You can add areas that your team works on to the channel so that they're always available for creating work items and subscriptions. This is important mainly for the teams with more than 100 area paths. +You can add areas that your team works on to the channel so that they're always available for creating work items and subscriptions. This action is important mainly for the teams with more than 100 area paths. - Use the following command to add area paths from your project to the Slack channel. @@ -110,7 +100,7 @@ You can add areas that your team works on to the channel so that they're always ![add areapath success message](./media/integrations-slack/add-areapath.png) -- If you choose project name as your area path, then you'll receive notifications for all the area paths in the project. It's logically equivalent to choosing 'Any' area path. +- If you choose project name as your area path, then you receive notifications for all the area paths in the project. It's logically equivalent to choosing 'Any' area path. ## Create a work item with a command @@ -155,7 +145,8 @@ access to the discussion that led to the creation of the work item. This command lists all the current subscriptions for the channel and allows you to add new subscriptions and remove existing ones. As part of adding subscriptions, you can also customize what you get notified on by using various filters. -[!NOTE]Team administrators aren't able to remove or modify subscriptions created by Project administrators. +> [!NOTE] +> Team administrators can't remove or modify subscriptions created by Project administrators. ![Pic: View subscriptions](./media/integrations-slack/view-subscriptions.png) @@ -204,7 +195,7 @@ If you're experiencing the following errors when using the [Azure Boards App for In the **same browser**, start a new tab, go to `https://slack.com`, and sign in to your work space (**use web client**). Run the `/azboards signout` command followed by the `/azboards signin` command. -Select the `Sign in` button and you'll be redirected to a consent page like the one in the following example. Ensure that the directory shown beside the email is same as what was chosen in the previous step. Accept and complete the sign-in process. +Select the `Sign in` button and you get redirected to a consent page like the one in the following example. Ensure that the directory shown beside the email is same as what was chosen in the previous step. Accept and complete the sign-in process. > [!div class="mx-imgBorder"] > ![Consent to the requested app permissions](media/troubleshooting/boards-consent-page-slack.png) @@ -215,6 +206,6 @@ If these steps don't resolve your authentication issue, reach out to us at [Deve ## Related articles - [Define area paths and assign to a team](../../organizations/settings/set-area-paths.md) -- [Azure Pipelines with Slack](../../pipelines/integrations/slack.md) -- [Azure Repos with Slack](../../repos/integrations/repos-slack.md) +- [Use Azure Pipelines with Slack](../../pipelines/integrations/slack.md) +- [Use Azure Repos with Slack](../../repos/integrations/repos-slack.md) - [Create a service hook for Azure DevOps with Slack](../../service-hooks/services/slack.md) \ No newline at end of file diff --git a/docs/boards/integrations/boards-teams.md b/docs/boards/integrations/boards-teams.md index 5d2fa8a5e8a..ecdcf39dc23 100644 --- a/docs/boards/integrations/boards-teams.md +++ b/docs/boards/integrations/boards-teams.md @@ -1,5 +1,5 @@ --- -title: Use Azure Boards with Microsoft Teams +title: Use Azure Boards in Microsoft Teams titleSuffix: Azure Boards description: Learn how to create work items and monitor work item activity in an Azure Boards project from a Microsoft Teams channel. ms.service: azure-devops @@ -10,368 +10,220 @@ ms.reviewer: karrg ms.author: karrg author: chcomley monikerRange: 'azure-devops' -ms.date: 10/26/2022 +ms.date: 08/13/2024 --- -# Use the Azure Boards app in Microsoft Teams +# Use Azure Boards in Microsoft Teams [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -If you use [Microsoft Teams](https://products.office.com/microsoft-teams/group-chat-software), you can create work items and monitor work item activity in your Azure Boards project from your Teams channel. You accomplish this by adding the [Azure Boards app for Microsoft Teams](https://appsource.microsoft.com/product/office/WA200000644?tab=Overview) to your Teams channel. +This article describes how to use the Azure Boards and Azure DevOps apps for Microsoft Teams to create and monitor Azure Boards work items from your Teams channels. -The Azure Boards app for Microsoft Teams enables users to complete the following tasks: -- Set up and manage subscriptions for creating and updating work items -- Manage other work item events -- Receive and manage notifications for work item events in their Teams channel -- Create work items from conversations in the channel -- Search and share work items with other members in the channel using the messaging extension -- View work item previews from their URLs to start discussions and keep the conversations contextual. - - -![Pic: Notification](./media/integrations-teams/notifications.png) +[!INCLUDE [temp](../../includes/feature-support-cloud-only.md)] -Read this article to learn how to: - -> [!div class="checklist"] -> * Add the Azure Boards app to your team in Microsoft Teams -> * Link and unlink your Azure Boards project to the Azure Boards app -> * Set up subscriptions to work item related events in your Teams channel -> * Create work items from your Teams channel -> * Monitor work item activity in your Teams channel +By using the Azure Boards app for Microsoft Teams, you can: +- Set up subscriptions to create and manage work items and work item events in your Teams channels. +- Create work items directly from channel conversations. +- Search for and share work items across channels using the messaging extension. +- View previews of work items from URLs. > [!NOTE] -> Azure Boards and Microsoft Teams integration is only supported for Azure DevOps Services. -> -> Also, Azure Boards and Microsoft Teams integration isn't supported if you're an O365 Government Community Cloud (GCC) customer that uses an Azure Commercial subscription in conjunction with your GCC tenant. - +> - Azure Boards notifications aren't supported inside Teams chat or direct messages. +> - The Azure Boards app for Microsoft Teams isn't supported for O365 Government Community Cloud (GCC) customers that use an Azure Commercial subscription in conjunction with a GCC tenant. ## Prerequisites -- To create a work item, you must be a contributor to the Azure Boards project. If you don't have a project yet, you can sign up and create a project. For more information, see [Start using Azure Boards](../get-started/index.md). -- To create subscriptions in a Teams channel for work item events, you must be a member of the Azure Boards Project Administrators group or added to the team administrator role for the team. To get added, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) or [Add team administrator](../../organizations/settings/add-team-administrator.md). -- To receive notifications, you must enable the **Third-party application access via OAuth** setting for the Azure DevOps organization. See [Change application access policies for your organization](../../organizations/accounts/change-application-access-policies.md). - -> [!NOTE] -> * You can link the Azure Boards app for Microsoft Teams only to a project hosted on Azure DevOps Services at this time. -> * Notifications are currently not supported inside direct messages. -> * Only public channels are supported. - -## Add the Azure Boards app to Microsoft Teams - -You add the app to your Teams channel in Microsoft Teams. - -1. Visit the App store in Microsoft Teams and search for the Azure Boards app. Upon installing, a welcome message from the app displays as shown in the following image. - - ![Pic: Welcome message](./media/integrations-teams/welcome-message.png) - -2. Use the `@azure boards` handle to interact with the app. For a list of commands, see [Command reference](#azure-boards-command-reference) provided later in this article. - -## Link your Azure Boards project to the Azure Boards app - -To use the app, you must first link your Azure Boards project to your Teams channel. - -1. Once the app has been installed in your team, connect and authenticate yourself to Azure Boards. Use **Sign in with different email** if your Microsoft Teams and Azure Boards are in different tenants. - - ![Connect and authenticate yourself to Azure Boards.](./media/integrations-teams/signin1.png) - - ![Connect and authenticate yourself to Azure Boards, step 2.](./media/integrations-teams/signin2.png) - -2. After signing in, use the following command inside a Teams channel to link to the Azure Boards project that you specify with the URL: - - ``` - @azure boards link [project url] - ``` - - For example: - - ``` - @azure boards link https://dev.azure.com/myorg/myproject - ``` - -Once the project is linked, you can create work items using `@azure boards create` command or use message actions. - -## Set up subscriptions - -You can create subscriptions to monitor work items at any time using the `@azure boards subscriptions` command. - -1. Select the area path you want and event that you're interested in. Use the associated -filters to customize what you get notified on in your Teams channel. To help easily set up subscriptions, your recently accessed area paths are shown in the area path dropdown. - - ![Set up subscriptions.](./media/integrations-teams/add-subscriptions.png) - -In case the area path you want doesn't appear in the Area path dropdown menu, follow the instructions mentioned in the next section, [Add area paths](#add-area-paths). Area paths added using the `@azure boards addAreapath` command and area paths for which subscriptions are created in the channel always appear in the Area path dropdown along with recently accessed area paths. - - -## Add area paths - -You can add areas that your team works on to the channel so that they're always available for creating work items and subscriptions. This feature is useful for teams with more than 100 area paths in their project. - -- Use the following command to add area paths from your project to the Teams channel. +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - **Contributor** for the project.
- Access to a team and channel in Microsoft Teams where you can install an app. | +| **Permissions** | To create subscriptions in a Slack channel for work item events: Member of the [Project Administrators](../../organizations/security/change-project-level-permissions.md) or [Team Administrators](../../organizations/settings/add-team-administrator.md) group. | +| **Policies** | To receive notifications: [**Third party application access via OAuth** policy enabled for the organization](../../organizations/accounts/change-application-access-policies.md). | - ``` - @azure boards addAreapath [area path] - ``` +## Add the Azure Boards app to Teams - For example: +To add the Azure Boards app to your Teams channels, do the following steps. - ``` - @azure boards addAreapath myproject\fabrikam - ``` +1. In Microsoft Teams, select **Apps**, search for *Azure Boards*, and then select **Azure Boards**. - ![add areapath success message](./media/integrations-teams/add-areapath.png) - - - If you choose project name as your area path, then you'll receive notifications for all the area paths in the project. + :::image type="content" source="media/integrations-teams/notifications.png" alt-text="Screenshot of selecting Apps, then Azure Boards."::: -## Create a work item with a command +1. Select the dropdown arrow next to **Open**, and select **Add to a team**. -With the Azure Boards app, you can create work items from your channel. The app supports custom work items as well. + :::image type="content" source="media/integrations-teams/signin1.png" alt-text="Screenshot of selecting Open and then Add to a team."::: -- To create a work item, use `@azure boards create`. +1. Select or enter your team name, and then select **Set up a bot**. - ![Create work item using command](./media/integrations-teams/create-work-item-command.png) + :::image type="content" source="media/integrations-teams/signin2.png" alt-text="Screenshot of selecting Set up a bot."::: +After the app installs, you see a welcome message in the Teams conversation pane. -## Create a work item from message actions +:::image type="content" source="media/integrations-teams/welcome-message.png" alt-text="Screenshot of the Welcome message in the conversation pane."::: -Often, discussions in a channel require creation of work items. You can use message actions to create a work item. The selected message is pre-filled in the description section of the work item. The Discussion section of the newly added work item stores a link back to the conversation in the channel. +### Azure Pipelines app commands -- To create work items using message actions +You can use the following `@azure boards` commands to interact with the Azure Boards app in your Teams channel. - > [!div class="mx-imgBorder"] - > ![Create work item using message action](./media/integrations-teams/message-action-1.png) - - > ![Create work item using message action, step 2.](./media/integrations-teams/message-action-2.png) - - -## Manage Azure Boards subscriptions - -1. To view, add and remove subscriptions for a channel, use the `@azure boards subscriptions` command: - - ``` - @azure boards subscriptions - ``` - -This command lists all the current subscriptions for the channel and allows you to add new subscriptions and remove existing ones. As part of adding subscriptions, you can also customize what you get notified on by using various filters. - -> [!div class="mx-imgBorder"] -> ![View subscriptions](./media/integrations-teams/view-subscriptions.png) - -> [!NOTE] -> Team administrators aren't able to remove or modify subscriptions created by Project administrators. - -## Search and share work items using compose extension - -To help users search and share work items, the Azure Boards app for Microsoft Teams supports compose extension. You can search for work items by work item ID, title, or supported functional command. For a list of commands, see [Functional work item search](../../project/search/functional-work-item-search.md). To use the compose extension, users must sign in to Azure Boards app either by running `@azure boards signin` command or by signing into the compose extension directly. - -![Signing into the compose extension.](./media/integrations-teams/teams-boards-compose-extension.png) - -## Preview work item URLs - -To support collaboration around work items discussed within a channel, the channel displays a preview of work items referenced. When a user pastes the work item URL, a preview is shown similar to the following image. This preview helps to keep work item-related conversations relevant and correct. - -![Work item URL unfurling.](./media/integrations-teams/url-unfurling.png) - -For this feature to work, users must be signed in. Once signed in, this feature works for all channels in a team in Microsoft Teams. - -## Unlink a project from a channel - -A Teams channel can only link to one Azure Boards project at a time. To link to a different project, you must first unlink the current project using `@azure boards unlink` command. - -Unlinking a project deletes all the subscriptions along with added area paths from the channel. If the channel has no subscriptions, any user can unlink a project. However if a channel has subscriptions, only project admins can unlink a project from a channel. +| Command | Functionality | +| -------------------- |----------------| +|@azure boards sign in | Sign in to your Azure Boards organization.| +|@azure boards sign out | Sign out from your Azure Boards organization.| +|@azure boards link \ |Link a project to this channel to create work items and receive notifications.| +|@azure boards unlink| Unlink a project from this channel.| +|@azure boards subscriptions | Add or remove subscriptions for this channel.| +|@azure boards addAreapath \| Add an area path from your project to this channel. | +|@azure boards feedback | Report a problem or suggest a feature. | +|@azure boards help | Get help on the commands. | -## Threaded notifications to link and reduce notifications +## Link your Azure Boards project to the app -The Teams channel threads notifications so as to logically link and reduce related notifications in the channel. All notifications linked to a particular work item are linked together. +To use the app, sign in to Azure Boards and link your Azure Boards project to your Teams channel. -### Compact view of threaded notifications +1. In the Teams conversation pane, enter `@azure boards signin`. +1. Select **Sign in** and complete authentication to Azure Boards. Select **Sign in with different email** if your Microsoft Teams and Azure Boards are in [different tenants](#connect-different-tenants). +1. Use the `@azure boards link` command to link to your Azure DevOps project URL. For example: -> [!div class="mx-imgBorder"] -> ![Compact thread](./media/integrations-teams/threads-boards-compact-view.png) + ``` + @azure boards link https://dev.azure.com/myorg/myproject/ + ``` -### Expanded view of threaded notifications -> [!div class="mx-imgBorder"] -> ![Expanded thread](./media/integrations-teams/threads-boards-expanded-view.png) +1. Select the **Add subscription** button in the linked project notification to start monitoring your project. -## Azure Boards command reference + :::image type="content" source="media/integrations-teams/add-subscription.png" alt-text="Screenshot of the linked project notification with the Add subscription button."::: -The following table lists all the `@azure boards` commands you can use in your Microsoft Teams channel. +### Set up subscriptions -| Command | Functionality | -| -------------------- |----------------| -|@azure boards link [project url] |Link a project to this channel to create work items and receive notifications| -|@azure boards subscriptions | Add or remove subscriptions for this channel| -|@azure boards create | Create a work item| -|@azure boards addAreapath [area path]| Add an area path from your project to this channel | -|@azure boards sign in | Sign in to your Azure Boards organization| -|@azure boards sign out | Sign out from your Azure Boards organization| -|@azure boards unlink | Unlink a project from this channel| -|@azure boards feedback | Report a problem or suggest a feature | +After your project is linked, begin monitoring project work items by selecting the **Add subscription** button. You can add more subscriptions anytime by using the `@azure boards subscriptions` command. -## Configure Azure DevOps Services tabs in Microsoft Teams +1. Under **Choose event**, select the event you want to subscribe to and select **Next**. -1. To bring your Kanban board or Dashboard into Microsoft Teams, select the '+' ('add new tab') button on the top nav of your team channel. + :::image type="content" source="media/integrations-teams/add-event.png" alt-text="Screenshot of selecting the event to monitor."::: - The **Add a tab** dialog displays. Icons are arranged typically according to most recent access. You can select A-Z for an alphabetized list. +1. Under **Choose filters**, select the **Area path**, **Work item type**, and optionally specify **Tags** or a specific string to filter on, and then select **Submit**. - :::image type="content" source="media/teams-as-website.png" alt-text="Screenshot to add a new tab to Teams channel."::: + :::image type="content" source="media/integrations-teams/add-subscriptions.png" alt-text="Screenshot of setting up the subscription."::: -2. Choose the **Azure DevOps** icon and authenticate your identity. Optionally, you can choose the **Website** icon and add the URL of your Kanban board or dashboard to the channel. +### Add area paths -3. Choose the organization whose board or dashboard you want to add. +Area paths that have subscriptions in the channel, recently accessed area paths, and area paths that you add by using the `@azure boards addAreapath` command appear in the **Area path** dropdown menu when you create a subscription. If the area path that your team works on doesn't appear in the dropdown menu, you can add it so that it's always available for creating work items and subscriptions. This feature is especially useful for teams with more than 100 area paths in their project. -4. Complete the form presented. For example, here we add a dashboard for the Azure DevOps team for the TechnicalContent project. +Use the `@azure boards addAreapath` command to add area paths from your project to the Teams channel. For example: - :::image type="content" source="media/integrations-teams/dialog-add-dashboard-kanban-board.png" alt-text="Dialog to add a team dashboard to a Teams channel."::: - -2. The Kanban board or dashboard you selected displays. - - ## Multi-tenant support +``` +@azure boards addAreapath 'VMdemo\Area4' +``` -In your organization if you're using a different email or tenant for Microsoft Teams and Azure DevOps, complete the following steps to sign in and connect based on your use case. - -:::row::: - :::column span="1"::: +You get a success message. -**Case** +:::image type="content" source="media/integrations-teams/add-areapath.png" alt-text="Screenshot of adding an area path and the success message."::: - :::column-end::: - :::column span="2"::: +If you choose the project name as your area path, you get notifications for all the area paths in the project. -**Email ID and tenant in Microsoft Teams** +## Create work items - :::column-end::: - :::column span="2"::: +You can use the Azure Boards app to create work items from your channel by using a message action. -**Email ID and tenant in Azure DevOps** +1. In any message in the channel, select the **More actions** ellipse in the actions panel, and then select **Create work item**. - :::column-end::: - :::column span="3"::: + :::image type="content" source="media/integrations-teams/create-work-item-command.png" alt-text="Screenshot of selecting create work item in the more actions menu."::: -**Steps to take** +1. Select the type of work item you want to create, and select **Next**. - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: +1. Enter a **Title** and select an **Area path** for the work item. -1 +1. The text of the message becomes the work item **Description** or **Repro Steps**, depending on work item type, or you can edit this text. Select **Create**. - :::column-end::: - :::column span="2"::: + :::image type="content" source="media/integrations-teams/message-action-1.png" alt-text="Screenshot of configuring the work item."::: - email1@abc.com - (tenant 1) +The new work item appears in Azure Boards and contains a link back to the Teams item that generated the work item. - :::column-end::: - :::column span="2"::: +:::image type="content" source="media/integrations-teams/message-action-2.png" alt-text="Screenshot of the new work item in Azure Boards."::: - email1@abc.com - (tenant 1) +## Manage Azure Boards subscriptions - :::column-end::: - :::column span="3"::: +To view, add, and remove subscriptions for a channel, use the `@azure boards subscriptions` command. This command lists all the current subscriptions for the channel. You can add new subscriptions and remove existing ones. When you add a subscription, you can customize notifications by using filters. -Sign in using **Sign in** button. +:::image type="content" source="media/integrations-teams/view-subscriptions.png" alt-text="Screenshot of the subscriptions list."::: - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: +> [!NOTE] +> Team Administrators can't remove or modify subscriptions that Project Administrators created. -2 +## Use the compose extension - :::column-end::: - :::column span="2"::: +To help you search for and share work items, the Azure Boards app for Microsoft Teams supports the compose extension. You can search for work items by work item ID, title, or supported functional command. For a list of supported commands, see [Functional work item search](../../project/search/functional-work-item-search.md). - email1@abc.com - (tenant 1) +To use the compose extension, be signed in to the Azure Boards project in the Teams channel. Select the **+** symbol in the message field, select **Azure Boards**, and then search for a work item. You can also select **Create work item** to create a new work item. - :::column-end::: - :::column span="2"::: +:::image type="content" source="media/integrations-teams/teams-boards-compose-extension.png" alt-text="Screenshot showing the compose extension."::: - email1@abc.com - (tenant 2) +## Preview work items - :::column-end::: - :::column span="3"::: +To support collaboration around work items you discuss in a channel, the Azure Boards app displays a preview of work items you reference. When you paste in a work item URL or select a work item from the compose extension, the app shows a preview similar to the following image. This URL unfurling feature works for all channels in the team. +:::image type="content" source="media/integrations-teams/url-unfurling.png" alt-text="Screenshot showing work item URL unfurling."::: -- Sign in the Azure DevOps account -- In the same browser, start a new tab, go to https://teams.microsoft.com -- Run the `signin` command and choose the **Sign in** button. +## Unlink a project from a channel +A Teams channel can link to only one Azure Boards project at a time. To link to a different project, you must first unlink the current project by using `@azure boards unlink`. - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: +Unlinking a project deletes all the project subscriptions and added area paths from the channel. If the channel has no subscriptions, any user can unlink a project. If the channel has subscriptions, only Project Administrators can unlink the project. -3 +## Expand and collapse threads - :::column-end::: - :::column span="2"::: +A Teams channel collapses posts in threads to logically link and reduce related posts in the channel. All replies to a particular post are linked together. - email1@abc.com - (tenant 1) +To expand the thread, select the compacted thread link. - :::column-end::: - :::column span="2"::: +:::image type="content" source="media/integrations-teams/threads-boards-compact-view.png" alt-text="Screenshot showing the compact thread view."::: - email2@pqr.com - (tenant 2) +To return to the channel and collapse the thread, select **Go to channel**. - :::column-end::: - :::column span="3"::: +:::image type="content" source="media/integrations-teams/threads-boards-expanded-view.png" alt-text="Screenshot showing the expanded thread view."::: -Sign in using **Sign in with different email address**, in the email ID picker use the email2 to sign in to Azure DevOps. + +## Configure Azure DevOps tabs - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: +To bring your project dashboard or Kanban board into Teams, you can install the Azure DevOps app in a tab in your Teams channel. The Azure DevOps app lets you insert content from the app in messages, and get notifications from the app in your channels. -4 +1. In Teams, select the **+** symbol on the top navigation of your channel or select **Apps** from the left menu. - :::column-end::: - :::column span="2"::: +1. Search for if necessary, and then select **Azure DevOps**. - email1@abc.com - (tenant 1) + :::image type="content" source="media/teams-as-website.png" alt-text="Screenshot to add a new tab to Teams channel."::: - :::column-end::: - :::column span="2"::: +1. Select and sign in to your Azure DevOps organization. - email2@pqr.com - (non default tenant 3) +1. On the **Azure DevOps** screen, select a **Project**, and whether to add a **Dashboard** or a **Kanban board** to the tab. Select other configurations depending on your choice, and select whether you want to post to the channel about adding the tab. - :::column-end::: - :::column span="3"::: + :::image type="content" source="media/integrations-teams/dialog-add-dashboard-kanban-board.png" alt-text="Screenshot that shows adding a Dashboard for Azure DevOps in Teams."::: -This scenario isn't supported today +1. Select **Save**. The new tab and board appear in your channel. - :::column-end::: -:::row-end::: +## Connect different tenants - - ## Troubleshoot errors +If you use different emails or tenants for Microsoft Teams and Azure DevOps, follow these steps to sign in and connect based on your settings. -If you're experiencing the following errors when using the [Azure Boards App for Microsoft Teams](https://appsource.microsoft.com/product/office/WA200000644?tab=Overview), follow the procedures in this section. +|Microsoft Teams |Azure DevOps |Sign in action | +|---------|---------|---------| +|email1@abc.com (tenant1) | email1@abc.com (tenant1) | Select **Sign in** | +|email1@abc.com (tenant1) | email2@abc.com (tenant2) | 1. Sign in to Azure DevOps.
2. In the same browser, start a new tab and go to https://teams.microsoft.com/.
3. Run the `sign in` command and select **Sign in**. | +|email1@abc.com (tenant1) | email2@pqr.com (tenant2) | 1. Select **Sign in with different email address**.
2. In the email ID picker, use the email2 to sign in.| +| email1@abc.com (tenant1) | email2@pqr.com (nondefault tenant3) | Not supported. | -[!INCLUDE [troubleshooting](includes/boards-troubleshoot-authentication.md)] +## Troubleshoot authentication issues -In the **same browser**, start a new tab, go to `https://teams.microsoft.com/`. Run the `@azure boards signout` command and then run the `@azure boards signin` command in the channel where the Azure Boards app for Microsoft Teams is installed. +If you receive the error **Configuration failed. Please make sure that the organization '{organization name}' exists and that you have sufficient permissions**, try the following steps to resolve the error. -Select the `Sign in` button and you'll be redirected to a consent page like the one in the following example. Ensure that the directory shown beside the email is same as what was chosen in the previous step. Accept and complete the sign-in process. +1. In the same browser, start a new tab and sign in to `https://teams.microsoft.com/`. -> [!div class="mx-imgBorder"] -> ![Consent to the requested app permissions](media/troubleshooting/boards-consent-page-teams.png) +1. In this tab, go to the channel where the Azure Boards app for Microsoft Teams is installed and run the `@azure boards signout` command and then the `@azure boards signin` command. -If these steps don't resolve your authentication issue, reach out to us at [Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). +1. Select the **Sign in** button, and complete the sign-in process. Ensure that the directory shown is the same one you chose in the previous step. +If these steps don't resolve your authentication issue, reach out to the [Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). ## Related articles - [Define area paths and assign to a team](../../organizations/settings/set-area-paths.md) -- [Azure Pipelines with Microsoft Teams](../../pipelines/integrations/microsoft-teams.md) -- [Azure Repos with Microsoft Teams](../../repos/integrations/repos-teams.md) +- [Use Azure Pipelines with Microsoft Teams](../../pipelines/integrations/microsoft-teams.md) +- [Use Azure Repos with Microsoft Teams](../../repos/integrations/repos-teams.md) diff --git a/docs/boards/integrations/media/integrations-slack/message-action-collated.png b/docs/boards/integrations/media/integrations-slack/message-action-collated.png index 82619e8328c..d24a28d79bd 100644 Binary files a/docs/boards/integrations/media/integrations-slack/message-action-collated.png and b/docs/boards/integrations/media/integrations-slack/message-action-collated.png differ diff --git a/docs/boards/integrations/media/integrations-slack/notifications.png b/docs/boards/integrations/media/integrations-slack/notifications.png index 064ea8990a8..82bad613e33 100644 Binary files a/docs/boards/integrations/media/integrations-slack/notifications.png and b/docs/boards/integrations/media/integrations-slack/notifications.png differ diff --git a/docs/boards/integrations/media/integrations-slack/url-unfurling.png b/docs/boards/integrations/media/integrations-slack/url-unfurling.png index 0d3f67bd563..5d643af1f48 100644 Binary files a/docs/boards/integrations/media/integrations-slack/url-unfurling.png and b/docs/boards/integrations/media/integrations-slack/url-unfurling.png differ diff --git a/docs/boards/integrations/media/integrations-teams/add-areapath.png b/docs/boards/integrations/media/integrations-teams/add-areapath.png index 5759e73abbc..7a60a8212cc 100644 Binary files a/docs/boards/integrations/media/integrations-teams/add-areapath.png and b/docs/boards/integrations/media/integrations-teams/add-areapath.png differ diff --git a/docs/boards/integrations/media/integrations-teams/add-event.png b/docs/boards/integrations/media/integrations-teams/add-event.png new file mode 100644 index 00000000000..889d19c629f Binary files /dev/null and b/docs/boards/integrations/media/integrations-teams/add-event.png differ diff --git a/docs/boards/integrations/media/integrations-teams/add-subscription.png b/docs/boards/integrations/media/integrations-teams/add-subscription.png new file mode 100644 index 00000000000..0ebc5be55f0 Binary files /dev/null and b/docs/boards/integrations/media/integrations-teams/add-subscription.png differ diff --git a/docs/boards/integrations/media/integrations-teams/add-subscriptions.png b/docs/boards/integrations/media/integrations-teams/add-subscriptions.png index 1c9d3053e97..1a97bdee282 100644 Binary files a/docs/boards/integrations/media/integrations-teams/add-subscriptions.png and b/docs/boards/integrations/media/integrations-teams/add-subscriptions.png differ diff --git a/docs/boards/integrations/media/integrations-teams/boards-consent-page-teams.png b/docs/boards/integrations/media/integrations-teams/boards-consent-page-teams.png deleted file mode 100644 index 47856d9dd36..00000000000 Binary files a/docs/boards/integrations/media/integrations-teams/boards-consent-page-teams.png and /dev/null differ diff --git a/docs/boards/integrations/media/integrations-teams/create-work-item-command.png b/docs/boards/integrations/media/integrations-teams/create-work-item-command.png index 015baf4ab47..e85d956850d 100644 Binary files a/docs/boards/integrations/media/integrations-teams/create-work-item-command.png and b/docs/boards/integrations/media/integrations-teams/create-work-item-command.png differ diff --git a/docs/boards/integrations/media/integrations-teams/dialog-add-dashboard-kanban-board.png b/docs/boards/integrations/media/integrations-teams/dialog-add-dashboard-kanban-board.png index 6ae7aea8b49..99d738f507f 100644 Binary files a/docs/boards/integrations/media/integrations-teams/dialog-add-dashboard-kanban-board.png and b/docs/boards/integrations/media/integrations-teams/dialog-add-dashboard-kanban-board.png differ diff --git a/docs/boards/integrations/media/integrations-teams/message-action-1.png b/docs/boards/integrations/media/integrations-teams/message-action-1.png index 51c077af82f..8687e1c3456 100644 Binary files a/docs/boards/integrations/media/integrations-teams/message-action-1.png and b/docs/boards/integrations/media/integrations-teams/message-action-1.png differ diff --git a/docs/boards/integrations/media/integrations-teams/message-action-2.png b/docs/boards/integrations/media/integrations-teams/message-action-2.png index d60cd2746a9..b716d7b6128 100644 Binary files a/docs/boards/integrations/media/integrations-teams/message-action-2.png and b/docs/boards/integrations/media/integrations-teams/message-action-2.png differ diff --git a/docs/boards/integrations/media/integrations-teams/notifications.png b/docs/boards/integrations/media/integrations-teams/notifications.png index 15637a37745..e1a98d6a4ad 100644 Binary files a/docs/boards/integrations/media/integrations-teams/notifications.png and b/docs/boards/integrations/media/integrations-teams/notifications.png differ diff --git a/docs/boards/integrations/media/integrations-teams/signin1.png b/docs/boards/integrations/media/integrations-teams/signin1.png index 17eda1c9c76..cdb780193da 100644 Binary files a/docs/boards/integrations/media/integrations-teams/signin1.png and b/docs/boards/integrations/media/integrations-teams/signin1.png differ diff --git a/docs/boards/integrations/media/integrations-teams/signin2.png b/docs/boards/integrations/media/integrations-teams/signin2.png index 92b8f648216..9cdd55ba316 100644 Binary files a/docs/boards/integrations/media/integrations-teams/signin2.png and b/docs/boards/integrations/media/integrations-teams/signin2.png differ diff --git a/docs/boards/integrations/media/integrations-teams/teams-boards-compose-extension.png b/docs/boards/integrations/media/integrations-teams/teams-boards-compose-extension.png index ded60db46c2..e261b7447ce 100644 Binary files a/docs/boards/integrations/media/integrations-teams/teams-boards-compose-extension.png and b/docs/boards/integrations/media/integrations-teams/teams-boards-compose-extension.png differ diff --git a/docs/boards/integrations/media/integrations-teams/threads-boards-compact-view.png b/docs/boards/integrations/media/integrations-teams/threads-boards-compact-view.png index 7f0a4e8974b..9822fabdc2f 100644 Binary files a/docs/boards/integrations/media/integrations-teams/threads-boards-compact-view.png and b/docs/boards/integrations/media/integrations-teams/threads-boards-compact-view.png differ diff --git a/docs/boards/integrations/media/integrations-teams/threads-boards-expanded-view.png b/docs/boards/integrations/media/integrations-teams/threads-boards-expanded-view.png index 9feaa578a79..5edab4ef480 100644 Binary files a/docs/boards/integrations/media/integrations-teams/threads-boards-expanded-view.png and b/docs/boards/integrations/media/integrations-teams/threads-boards-expanded-view.png differ diff --git a/docs/boards/integrations/media/integrations-teams/url-unfurling.png b/docs/boards/integrations/media/integrations-teams/url-unfurling.png index 036680ce0c8..775237d741b 100644 Binary files a/docs/boards/integrations/media/integrations-teams/url-unfurling.png and b/docs/boards/integrations/media/integrations-teams/url-unfurling.png differ diff --git a/docs/boards/integrations/media/integrations-teams/view-subscriptions.png b/docs/boards/integrations/media/integrations-teams/view-subscriptions.png index 250b3d768af..c2e31e5cafa 100644 Binary files a/docs/boards/integrations/media/integrations-teams/view-subscriptions.png and b/docs/boards/integrations/media/integrations-teams/view-subscriptions.png differ diff --git a/docs/boards/integrations/media/integrations-teams/welcome-message.png b/docs/boards/integrations/media/integrations-teams/welcome-message.png index fd000320ad3..237481450e4 100644 Binary files a/docs/boards/integrations/media/integrations-teams/welcome-message.png and b/docs/boards/integrations/media/integrations-teams/welcome-message.png differ diff --git a/docs/boards/integrations/media/teams-as-website.png b/docs/boards/integrations/media/teams-as-website.png index 68c5b2bc039..69c6ecf6836 100644 Binary files a/docs/boards/integrations/media/teams-as-website.png and b/docs/boards/integrations/media/teams-as-website.png differ diff --git a/docs/boards/integrations/media/troubleshooting/profile-page.png b/docs/boards/integrations/media/troubleshooting/profile-page.png index 91f361c2421..c68bdec47e0 100644 Binary files a/docs/boards/integrations/media/troubleshooting/profile-page.png and b/docs/boards/integrations/media/troubleshooting/profile-page.png differ diff --git a/docs/boards/integrations/media/troubleshooting/third-party-app-consent.png b/docs/boards/integrations/media/troubleshooting/third-party-app-consent.png index 4e8adf078d6..66e119ce291 100644 Binary files a/docs/boards/integrations/media/troubleshooting/third-party-app-consent.png and b/docs/boards/integrations/media/troubleshooting/third-party-app-consent.png differ diff --git a/docs/boards/media/icons/more-actions-horizontal.png b/docs/boards/media/icons/more-actions-horizontal.png new file mode 100644 index 00000000000..277b44041bd Binary files /dev/null and b/docs/boards/media/icons/more-actions-horizontal.png differ diff --git a/docs/boards/media/icons/more-actions.png b/docs/boards/media/icons/more-actions.png index f8bf99c3fdc..a3d11730fbe 100644 Binary files a/docs/boards/media/icons/more-actions.png and b/docs/boards/media/icons/more-actions.png differ diff --git a/docs/boards/media/icons/settings-icon.png b/docs/boards/media/icons/settings-icon.png new file mode 100644 index 00000000000..80f7af5da9c Binary files /dev/null and b/docs/boards/media/icons/settings-icon.png differ diff --git a/docs/boards/media/select-boards-and-boards.png b/docs/boards/media/select-boards-and-boards.png new file mode 100644 index 00000000000..76d865ca23c Binary files /dev/null and b/docs/boards/media/select-boards-and-boards.png differ diff --git a/docs/boards/media/switch-to-backlog-cloud.png b/docs/boards/media/switch-to-backlog-cloud.png index 0f21d540f8f..78e8fde514c 100644 Binary files a/docs/boards/media/switch-to-backlog-cloud.png and b/docs/boards/media/switch-to-backlog-cloud.png differ diff --git a/docs/boards/plans/add-edit-delivery-plan.md b/docs/boards/plans/add-edit-delivery-plan.md index 410c116aef2..b52c1904b0f 100644 --- a/docs/boards/plans/add-edit-delivery-plan.md +++ b/docs/boards/plans/add-edit-delivery-plan.md @@ -8,217 +8,191 @@ author: chcomley ms.custom: cross-project ms.topic: how-to monikerRange: '>= azure-devops-2022' -ms.date: 12/01/2022 +ms.date: 03/24/2025 --- - - # Add or edit a Delivery Plan [!INCLUDE [version-gt-eq-2022](../../includes/version-gt-eq-2022.md)] -Delivery Plans provide a highly interactive calendar view of multiple team backlogs. For the use cases, benefits, and interactions you can do, see [Review team Delivery Plans](review-team-plans.md). - -Use this article to learn how to complete these tasks: - -- Open a plan from the list of defined plans -- Add and edit a plan -- Add field criteria, customize cards, and add markers - +Delivery Plans provide a highly interactive calendar view of multiple team backlogs. This article shows how to add and edit a plan. For the use cases, benefits, and interactions you can do, see [Review team Delivery Plans](review-team-plans.md). > [!NOTE] -> This article describes how to add or edit Delivery Plans 2.0 which is available for Azure DevOps Services and Azure DevOps Server 2022 and later versions. For information on the Delivery Plans Marketplace extension which supports Azure DevOps Server 2020 and earlier versions, see [Delivery Plans 1.0](../extensions/delivery-plans.md). +> This article describes how to add or edit Delivery Plans 2.0 which is available for Azure DevOps Services and Azure DevOps Server 2022 and later versions. For information on the Delivery Plans Marketplace extension which supports Azure DevOps Server 2020 and earlier versions, see [Delivery Plans 1.0](../extensions/delivery-plans.md). ## Prerequisites -- To add or edit a Delivery Plan, you must be a member of the Contributors group for the project where you add the plan. -- To add team backlogs to a plan, you must have view permissions to those projects. -- To view a Delivery Plan, you must be a member of the Project Collection Valid Users group. Users granted **Stakeholder** access for a private project can view plans. Users granted **Stakeholder** access for a public project can add and view plans. -- To manage permissions for a Delivery Plan or edit or delete a plan, you must be the creator of the plan. Or, you must be a member of the **Project Administrators**, **Project Collection Administrators** group, or be granted explicit permission through the plan's Security dialog. For more information, see [Manage Delivery Plan permissions](../../organizations/security/set-permissions-access-work-tracking.md#edit-or-manage-permissions-for-delivery-plans). - -## Before you define a plan - -To add and configure a Delivery Plan, the following elements must be configured: -- [Teams and team backlogs](../../organizations/settings/add-teams.md). -- [Team product or portfolio backlog must be enabled](../../organizations/settings/select-backlog-navigation-levels.md). -- [Area paths and team area paths assignments](../../organizations/settings/set-area-paths.md). -- [Iteration (sprint) paths and team iterations](../../organizations/settings/set-iteration-paths-sprints.md) - - **Iteration Paths** must be assigned **Start** and **End Dates** or they won't appear on the plan. - - Also, **Iteration Paths** must be selected for the team whose backlogs you select, or work items associated with those **Iteration Paths** won't appear on the plan. -- Each team must have defined [product backlog items](../backlogs/create-your-backlog.md), or [portfolio backlogs](../backlogs/define-features-epics.md) and assigned those items to either a **Start Date** and **End Date** or an **Iteration Path**. - -> [!TIP] -> If you edit a plan and don't see the changes you made appear in the plan, refresh your browser. A browser refresh is needed some times to trigger the updates. - - - -## Plan customization options - - -Once you open the Plan settings dialog, choose one of the following tabs to set your customization options. +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To add or edit a Delivery Plan: Member of the **Contributors** group for the project where you add the plan.
- **Manage delivery plans** permission set to **Allow** for the **Contributors** group in **Project settings** > **Permissions**.
- To add team backlogs to a plan: **View** permission for those projects.
- To view a Delivery Plan: Member of the **Project Collection Valid Users** group. Users granted **Stakeholder** access for a private project can view plans. Users granted **Stakeholder** access for a public project can add and view plans.
- To manage permissions, edit, or delete a plan: Creator of the plan, or member of the **Project Administrators**, **Project Collection Administrators** group, or explicit permission granted through the plan's Security dialog. For more information, see [Manage Delivery Plan permissions](../../organizations/security/set-permissions-access-work-tracking.md). | +| **Configuration** | - [Teams and team backlogs](../../organizations/settings/add-teams.md) set up.
- [Team product or portfolio backlogs](../../organizations/settings/select-backlog-navigation-levels.md) enabled.
- [Area paths and team area paths](../../organizations/settings/set-area-paths.md) assigned.
- [Iteration (sprint) paths and team iterations](../../organizations/settings/set-iteration-paths-sprints.md) assigned.
- **Iteration Paths**, **Start**, and **End Dates** assigned, otherwise they don't appear on the plan.
- **Iteration Paths** selected for the team whose backlogs you select, otherwise work items associated with those iteration paths don't appear on the plan.
- [Product backlog items](../backlogs/create-your-backlog.md) or [portfolio backlogs](../backlogs/define-features-epics.md) defined and assigned to either a **Start Date**, **End Date**, or an **Iteration Path**. | -|Page | Use to... | -|-------------|-------------------| -|**Overview**|Edit the plan **Name** or **Description**. | -|**[Teams](#teams)** |Add or remove a team backlog. You can add up to 20 backlog levels for Azure DevOps Services or 15 backlog levels for Azure DevOps Server 2022. You can add a mix of backlog levels and teams from any project defined for the organization. | -|**[Field criteria](#field-criteria)**|Specify field criteria to filter work item types displayed on the plan. All criteria are evaluated as an AND statement. If no fields are specified, then all work item types that appear on the teams backlog level appear on the delivery plan. | -|**[Markers](#markers)** |Add up to 30 milestone markers to the plan. Specify a label and select a color. | -|**[Fields](#fields)** |Add or remove fields from cards to display on the plan, similar to how you [customize them for your Kanban board](../../boards/boards/customize-cards.md). You can't add rich-text (HTML) fields, such as the Description field, to a card even if it appears in the list. These field types represent too many challenges to format on a card. | -|**[Styles](#styles)** |Add styling rules to change card color based on field criteria. | -|**[Tag colors](#tag-colors)**|Add tags and specify a tag color. Optionally enable or disable a tag color. | - - - + ## Add a plan -1. Open **Boards>Delivery Plans**. +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +2. Select **Boards** > **Delivery Plans**. > [!div class="mx-imgBorder"] > ![Screenshot showing how to Open Boards and Delivery Plans.](media/plans/open-plans.png) -1. To add a plan, choose **New Plan**. +3. Select **New Plan**. > [!div class="mx-imgBorder"] > ![Screenshot showing Choose New Plan button.](media/plans/add-plan-new-plan-button.png) All users have permissions to create a plan and manage the plans they create. -2. Fill in the form to name, describe, and specify the team backlogs that you want to appear within your plan. You can add up to 15 teams to a plan. +4. Enter a name and description, and specify the team backlogs that you want to appear within your plan. + + When you define your plan, know the following guidelines: + - **Name and description:** Use the name and description fields to clearly identify your plan within the project. + - **Team selection:** You can choose one or more teams from any project defined in the organization or collection. There can be up to a maximum of 15 teams. + - **Active backlogs:** Select one or more active backlogs for a team. If you encounter issues selecting a backlog level, check the Team Backlog settings to ensure the backlog level is enabled for the team. For more information, see [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md). + - **Reordering backlogs:** You can reorder the team backlogs by dragging and dropping them into the desired sequence. + - **Filtering work items:** To filter for specific work items, specify the field criteria. For example, to exclude bugs from the view, add the following criteria: `Work Item Type <> Bug`. > [!div class="mx-imgBorder"] - > ![Dialog forNew delivery plan.](media/plans/new-delivery-plan-dialog.png) + > ![Screenshot showing Dialog for New Delivery Plan.](media/plans/new-delivery-plan-dialog.png) -When defining a plan, note the following information: -- Use the name and description field to clearly identify your plan within the project -- You can choose one or more teams from any project defined in the organization or collection. There can be up to a maximum of 15 teams -- You can choose one or more [active backlogs for a team](../../organizations/settings/select-backlog-navigation-levels.md) - > [!NOTE] - > If you aren't able to select a backlog level, check the Team Backlog settings to ensure the backlog level is enabled for the team. For more information, see [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md). -- You can reorder the team backlogs by dragging and dropping them into the sequence you want -- To filter for specific work items, specify the field criteria. For example, to exclude bugs from the view, add the following criteria: `Work Item Type <> Bug`. +For more information, see [Query fields, operators, and macros in Azure Boards](../queries/query-operators-variables.md). - + ## Edit a plan -Once you've defined a plan, you can modify or further customize it. +Once you define a plan, you can modify or further customize it. -1. Choose the **Settings** to open the **Plans settings** dialog. +1. Select **Settings** from your Delivery Plan. :::image type="content" source="media/plans/settings.png" border="true" alt-text="Screenshot of Delivery Plans title and settings button."::: -2. Then, choose the page you want to edit based on the [customizations you want to make](#customization-options). Here, we add the **Tags** to the **Field criteria**. Only work items that contain the *Build 2021* tag appear in the Delivery Plan. +2. Choose the page you want to edit based on the [customizations you want to make](#customization-options). In the following example, we add the **Tags** to the **Field criteria**. Only work items that contain the *Build 2021* tag appear in the Delivery Plan. + + :::image type="content" source="media/plans/plan-settings-field-criteria.png" border="true" alt-text="Screenshot showing Dialog for Plan settings, Field criteria page."::: + +> [!TIP] +> If you made changes to a plan but don’t see them reflected, try refreshing your browser. Sometimes a browser refresh is necessary to trigger the updates. + + - :::image type="content" source="media/plans/plan-settings-field-criteria.png" border="true" alt-text="Dialog for Plan settings, Field criteria page."::: +## Plan customization options + +Once you open the Plan settings dialog, choose one of the following tabs to set your customization options. +|Page | Use to... | +|-------------|-------------------| +|**Overview**|Edit the plan **Name** or **Description**. | +|**[Teams](#teams)** |Add or remove a team backlog. You can add up to 20 backlog levels for Azure DevOps Services or 15 backlog levels for Azure DevOps Server 2022. You can add a mix of backlog levels and teams from any project defined for the organization. | +|**[Field criteria](#field-criteria)**|Specify field criteria to filter work item types displayed on the plan. All criteria are evaluated as an AND statement. If no fields are specified, then all work item types that appear on the teams backlog level appear on the plan. | +|**[Markers](#markers)** |Add up to 30 milestone markers to the plan. Specify a label and select a color. | +|**[Fields](#fields)** |Add or remove fields from cards to display on the plan, similar to how you [customize them for your board](../../boards/boards/customize-cards.md). You can't add rich-text (HTML) fields, such as the Description field, to a card even if it appears in the list. These field types represent too many challenges to format on a card. | +|**[Styles](#styles)** |Add styling rules to change card color based on field criteria. | +|**[Tag colors](#tag-colors)**|Add tags and specify a tag color. Optionally enable or disable a tag color. | ## Choose fields to appear on cards -Show those fields that are useful for your review purposes or if they contain keywords that you may want to use to filter your plan. Unlike the Kanban board, you can't change the field displayed on the card. First, open the work item to make field changes. +Display fields that are relevant for your review purposes or contain keywords that you want to use for filtering your plan. Unlike a board, you can't change the field displayed on the card directly. To make field changes, open the work item. > [!TIP] -> To add a custom field, you must first [add it to the process used to customize the project](../../organizations/settings/work/add-custom-field.md). +> To add a custom field, first [add it to the process used to customize the project](../../organizations/settings/work/add-custom-field.md). -1. From the Plan settings dialog, choose the **Fields** tab. Place a check mark in the check box for those fields you want to have appear on the board. - -1. To add a field, choose the :::image type="icon" source="../media/icons/green_plus_icon.png" border="false"::: plus icon and enter the name of a field you want to add. You can add both default and custom fields, including Boolean fields. The only fields you can't add are rich-text or HTML fields. +1. Open your plan **Settings**. +2. Select **Fields**. +3. Check the boxes next to the field you want to appear on the board. +4. To add a field, select the :::image type="icon" source="../media/icons/green_plus_icon.png" border="false"::: plus icon and enter the name of a field. You can add both default and custom fields, including Boolean fields. The only fields you can't add are rich-text or HTML fields. - Here we select all standard fields and add the **Story Points** and **Priority** fields to display on cards. + In the following example, we select all standard fields and add the **Story Points** and **Priority** fields to display on cards. - :::image type="content" source="media/plans/plan-settings-fields.png" alt-text="Dialog for Plan settings, Fields tab."::: + :::image type="content" source="media/plans/plan-settings-fields.png" alt-text="Screenshot showing Dialog for Plan settings, Fields tab."::: > [!TIP] > To show the **Title** of the parent work item, choose the **Parent** field. Choosing the **Parent** title from a card opens the parent work item. To change the parent work item, open the child work item and remove the link and add a different parent work item. You can filter your plan based on parent work items, whether the **Parent** field is added to cards or not. -1. To remove a field, choose the :::image type="icon" source="../media/icons/trash-can.png" border="false"::: delete icon next to the field. +5. To remove a field, select the :::image type="icon" source="../media/icons/trash-can.png" border="false"::: *delete* icon next to the field. -1. When you're done with your changes, choose **Save**. +6. When you're done, select **Save**. - + ## Add milestone markers -1. To set a marker, open **Markers**, specify a date and specify a hexadecimal color, or choose the color palette icon to change to a new color selected by the system. - - :::image type="content" source="media/plans/plan-settings-markers.png" border="true" alt-text="Dialog for Plans settings, Markers tab, two markers defined."::: - -1. To add more markers, choose **+ Add marker**. You can add up to 30 markers. The **+ Add marker** button becomes disabled after 30 markers have been added. - -2. Choose **Save** when you're done. +1. Open your plan **Settings**. +2. Select **Markers**. + :::image type="content" source="media/plans/plan-settings-markers.png" border="true" alt-text="Screenshot of Dialog for Plans settings, Markers tab, two markers defined."::: +2. Specify a date. +3. Choose a hexadecimal color or select the color palette icon to change to a system-selected color. + To add more markers, select **+ Add marker**. You can add up to 30 markers. After 30 markers, the **+ Add marker** button is disabled. +4. Select **Save**. - Markers appear on the plan as shown. + Markers appear on the plan like the following example. - :::image type="content" source="media/plans/markers.png" border="true" alt-text="Screenshot of Plans, Markers appear on calendar."::: + :::image type="content" source="media/plans/markers.png" border="true" alt-text="Screenshot of Plans, Markers appear on calendar."::: -1. When you're done with your changes, choose **Save**. - - - + ## Change card color -With styling rules, you can cause cards to change color when their corresponding work items meet the field criteria that you set. This feature is similar to the one you can define for Kanban boards as described in [Customize cards](../boards/customize-cards.md). Here we highlight the card based on its **Tags** assignment. +With styling rules, you can change the color of cards when their corresponding work items meet specific field criteria that you set. This functionality is similar to what you can define for a board, as described in [Customize cards](../boards/customize-cards.md). In this case, we highlight the card based on its **Tags** assignment. :::image type="content" source="media/plans/card-tag-style.png" border="true" alt-text="Screenshot of a card with style applied."::: -1. To change the card color, open the **Styles** tab. You can specify up to 10 styles. There are some limits to the fields you choose. +1. Open your plan **Settings**. +2. Select **Styles**. - :::image type="content" source="media/plans/plan-settings-styles.png" border="true" alt-text="Dialog for Plans settings, Styles tab, two styles defined."::: + :::image type="content" source="media/plans/plan-settings-styles.png" border="true" alt-text="Screenshot of Dialog for Plans settings, Styles tab, two styles defined."::: -1. Choose **+Add styling rule**. Enter a name for the style and choose the color from the color picker. Then specify the field criteria. You can add multiple field values. For style purposes, they're all evaluated as a logical AND. Choose the field and the value for the field. +3. Select **+Add styling rule**. +4. Enter a name for the style and choose a color. +5. Specify the field criteria. You can add multiple field values. For style purposes, they're all evaluated as a logical `AND`. For example, here we choose to highlight cards with a **Priority=1**. - :::image type="content" source="media/plans/specify-style.png" border="true" alt-text="Dialog for Plans settings, Styles tab, define a new style."::: - + :::image type="content" source="media/plans/specify-style.png" border="true" alt-text="Screenshot of Dialog for Plans settings, Styles tab, define a new style."::: + You can specify up to 10 styles. + > [!NOTE] - > Some fields aren't supported for selection, such as the **Title** field, **Description** and other rich-text fields, **Assigned To** and other identity fields. Also, you may be able to select a field but not be able to specify a value or the value you want. For example, you can't specify **Tags** that are *Empty* or *Not Empty*. + > You can't directly select **Title**, **Description**, and other rich-text fields, such as **Assigned To**. Even if you can select a field, you might not be able to specify a value or the specific value you want. For example, you can't specify **Tags** that are either *Empty* or *Not Empty*. ::: moniker range="azure-devops" ### Set color for an Iteration Path -You can highlight work items for a team's current **Iteration Path** by specifying the `@CurrentIteration` macro in the **Styles** tab as shown in the following image. For more information on using the `@CurrentIteration` macros, see [Query by date or current iteration, Create queries for your team's current iteration](../queries/query-by-date-or-current-iteration.md#create-queries-for-your-teams-current-iteration). +1. Open your plan **Settings**. +2. Select **Styles**. +3. Specify the `@CurrentIteration` macro for the desired team. +:::image type="content" source="media/plans/styles-current-iteration.png" alt-text="Screenshot of Dialog for Plans settings, Styles tab, set style using the current iteration macro for the Iteration Path."::: -:::image type="content" source="media/plans/styles-current-iteration.png" border="true" alt-text="Dialog for Plans settings, Styles tab, set style using the current iteration macro for the Iteration Path."::: +For more information, see [Query by date or current iteration](../queries/query-by-date-or-current-iteration.md#create-queries-for-your-teams-current-iteration). ::: moniker-end - + ## Set tag colors -Before setting tag colors, first [add tags to backlog items](../queries/add-tags-to-work-items.md) that you want to highlight with color. - -1. From the Plan settings dialog, choose **Tag colors** and then choose :::image type="icon" source="../../media/icons/add-dark-icon.png" border="false"::: **Add tag color**. Then, select the tag and the color you want to appear on the cards. +Before you set tag colors, [add tags to backlog items](../queries/add-tags-to-work-items.md) to highlight with color. - :::image type="content" source="media/plans/edit-tags-settings.png" border="true" alt-text="Dialog for Plans settings, Tags tab, add tags and set color."::: - -2. To enable or disable a tag color, select the **Enabled** checkbox. - -3. When you're done with your changes, choose **Save**. +1. Open your plan **Settings**. +2. Select **Tag colors**. +3. Select :::image type="icon" source="../../media/icons/add-dark-icon.png" border="false"::: **Add tag color** and choose the tag and color that you want on the cards. + :::image type="content" source="media/plans/edit-tags-settings.png" border="true" alt-text="Dialog for Plans settings, Tags tab, add tags, and set color."::: +4. To enable or disable a tag color, check or uncheck the **Enabled** checkbox. +5. When you're done, select **Save**. > [!TIP] - > If tags don't display on the cards, choose **Fields** and make sure that you've checked **Show Tags**. - - - - - -## Programmatically manage Delivery Plans - -You can manage plans using the [REST API, Plans](/rest/api/azure/devops/work/plans/create?view=azure-devops-rest-6.0&preserve-view=true ). - + > If tags don't display on the cards, select **Fields** and make sure you checked **Show Tags**. ## Related articles + +- [Manage Delivery Plans using the REST API](/rest/api/azure/devops/work/plans/create?view=azure-devops-rest-6.0&preserve-view=true) - [Review team plans](review-team-plans.md) -- [Interactively filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md) -- [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md) -- [Add teams](../../organizations/settings/add-teams.md) -- [Portfolio management](portfolio-management.md) -- [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) - \ No newline at end of file +- [Filter backlogs, boards, queries, and plans interactively](../backlogs/filter-backlogs-boards-plans.md) +- [Understand backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md) +- [Add teams](../../organizations/settings/add-teams.md) +- [Manage portfolio](portfolio-management.md) + diff --git a/docs/boards/plans/agile-culture.md b/docs/boards/plans/agile-culture.md index 7e59f47470a..eb3069f00a8 100644 --- a/docs/boards/plans/agile-culture.md +++ b/docs/boards/plans/agile-culture.md @@ -142,7 +142,7 @@ Each team plans the features to deliver. They have the autonomy to determine how As your organization grows, you can scale your Agile tools in the following ways. -- **[Add teams and filtered backlog views](../../organizations/settings/add-teams.md):** You add teams to support team autonomy and provide them with the tools they can configure and manage that supports how they want to work. These tools include product backlogs, Kanban boards, sprint backlogs, Taskboards, and others. +- **[Add teams and filtered backlog views](../../organizations/settings/add-teams.md):** You add teams to support team autonomy and provide them with the tools they can configure and manage that supports how they want to work. These tools include product backlogs, boards, sprint backlogs, Taskboards, and others. Also, you can configure teams to support a hierarchy of backlogs and portfolio backlogs so that portfolio managers can review priority and progress across several teams. @@ -166,7 +166,7 @@ Often, organizations look at adding a project for each software development proj We recommend that you add teams to scale your tools rather than add projects for the following reasons: - **Visibility:** It's easier to view progress across all teams -- **Tracking and auditing:** It's easier to [link work items and other objects](../queries/link-work-items-support-traceability.md) for tracking and auditing purposes +- **Tracking and auditing:** It's easier to [link work items to other objects](../backlogs/add-link.md) for tracking and auditing purposes - **Maintainability:** You minimize the maintenance of security groups and process updates. For more information, see [About projects and scaling your organization](../../organizations/projects/about-projects.md). diff --git a/docs/boards/plans/configure-hierarchical-teams.md b/docs/boards/plans/configure-hierarchical-teams.md index 3d9358312c1..360793034e1 100644 --- a/docs/boards/plans/configure-hierarchical-teams.md +++ b/docs/boards/plans/configure-hierarchical-teams.md @@ -14,40 +14,42 @@ ms.date: 04/01/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -In [Portfolio management](portfolio-management.md), we showed how management teams and feature teams can use their backlogs to focus on the work that's most important to them. In this article, we show how to configure teams that best support the different backlog views of management and feature teams. +In [Portfolio Management](portfolio-management.md), we explore how management teams and feature teams can use their backlogs to prioritize and focus on the most critical work items. This article helps you configure teams to optimally support the distinct backlog views tailored for both management and feature teams. -Specifically, we'll show you how to configure a team structure like the one shown in the image below. +## Why effective team configuration matters -![Each team has its own view of the work](media/pm-team-structure.png) +Effective team configuration is essential for ensuring that each team has a clear and focused view of their responsibilities and priorities. By setting up a hierarchical team structure, you can: -In this article you'll learn how to: +- **Enhance collaboration:** Foster better communication and teamwork across different functions. +- **Streamline workflow management:** Simplify processes and reduce bottlenecks. +- **Align with organizational goals:** Ensure that all teams are working towards common objectives. +- **Promote accountability and efficiency:** Increase visibility into each team's workload, promoting responsibility and productivity across projects. ->[!div class="checklist"] -> * Set up a hierarchical set of teams and backlogs -> * Define a single sprint cadence for all teams -> * Review which area paths are assigned to teams +### Key benefits +- **Customized backlog views:** Each team can prioritize and manage their work based on their specific goals and responsibilities. +- **Improved visibility:** Management and feature teams gain clear insights into their respective workloads and progress. +- **Enhanced focus:** Teams can concentrate on the most critical tasks without getting overwhelmed by unrelated work items. +- **Efficient workflow management:** Streamlined processes lead to faster decision-making and project execution. -## Prerequisites +By implementing a hierarchical team structure, you ensure that your organization remains agile, focused, and aligned with its strategic objectives. -- If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -- To add teams, you must be a member of the **Project Administrator**s group. To get added to this group, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). +## Prerequisites +[!INCLUDE [prerequisites-project-admin](../includes/prerequisites-project-admin.md)] ## Add a team for each management area -The first step is to add a team for each feature team and management area. You can also rename teams that you've already added. When you finish, you'll have a set of teams similar to the ones shown. +The first step is to add a team for each feature team and management area. You can also rename teams that you already added. When you're done, you have a set of teams similar to the ones shown. > [!div class="mx-imgBorder"] -> ![Project settings, Teams](media/config-teams/team-list.png) - -::: moniker range=">= azure-devops-2019" +> ![Screenshot shows Project settings, Teams.](media/config-teams/team-list.png) 1. From the web portal, choose **Project settings** and open **Teams**. - ![Open Project settings, and then Teams](../../organizations/settings/media/shared/open-project-settings-team-new-nav.png) + ![Screenshot shows Open Project settings, and then Teams.](../../organizations/settings/media/shared/open-project-settings-team-new-nav.png) 2. Choose **New team**. Give the team a name, and optionally a description. @@ -56,25 +58,6 @@ The first step is to add a team for each feature team and management area. You c Repeat this step for all feature and management teams you want to create. -::: moniker-end - -::: moniker range="tfs-2018" - - - -1. From the web portal, choose the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: gear settings icon to open the **Project settings** page for the project. - - ![Open project admin page](../../organizations/settings/media/add-team/open-admin-context-tfs-2017.png) - -1. Choose **New team**. Give the team a name, and make sure to select **Create an area path with the name of the team**. If you don't select this option, you'll have to set the default area path for the team once you create it. You can choose an existing area path or create a new one at that time. Team tools aren't available until the team's default area path is set. - - ![Create a sub-team with its own area path](../../organizations/settings/media/add-team/create-team-dialog.png) - - Repeat this step for all feature and management teams you want to create. - -::: moniker-end - - ## Move area paths into a hierarchical structure In this step, you want to move the areas paths associated with feature teams from a flat structure to a hierarchical structure. @@ -84,119 +67,60 @@ In this step, you want to move the areas paths associated with feature teams fro |![Flat area paths](media/config-teams/team-list-flat-structure.png) | ![Hierarchical area paths](media/config-teams/team-list-hierarchy-structure.png) | -You do this by opening each area path associated with a feature team and changing its location to be under the management area path. - -::: moniker range=">= azure-devops-2019" +To move area paths into a hierarchical structure, do the following steps: -1. Choose (1) **Project Settings**, expand **Work** if needed, and choose (2) **Project configuration** and then (3) **Areas**. +1. Select (1) **Project settings**, expand **Work** if needed, and select (2) **Project configuration** > (3) **Areas**. > [!div class="mx-imgBorder"] - > ![Project Settings>Work>Project Configuration](../../organizations/settings/media/areas/open-project-work-areas-settings-vert.png) - -1. Next, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for one of the area paths associated with a feature team and select **Edit**. Then change the **Location** to move it under its corresponding management team area path. - - For example, here we move the Customer Profile to under Account Management. - - > [!div class="mx-imgBorder"] - > ![Edit area path dialog](media/config-teams/edit-area-path.png) - - Repeat this step for all feature team area paths. - -::: moniker-end - - -::: moniker range="tfs-2018" - -1. From the web portal for the project, choose the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: gear icon. - - > [!div class="mx-imgBorder"] - > ![Open Admin context, project level](../../organizations/settings/media/areas/modify-areas-its-open-admin-context-ts.png) - - If you're currently working from a team context, then hover over the ![gear icon](../../media/icons/gear_icon.png) and choose **Project settings**. - - > [!div class="mx-imgBorder"] - > ![Open Project Settings, horz nav](../../media/settings/open-project-settings-horz.png) - -1. Choose **Work**. + > ![Screenshot shows sequence of selections, Project Settings>Work>Project Configuration.](../../organizations/settings/media/areas/open-project-work-areas-settings-vert.png) 2. Next, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for one of the area paths associated with a feature team and select **Edit**. Then change the **Location** to move it under its corresponding management team area path. For example, here we move the Customer Profile to under Account Management. > [!div class="mx-imgBorder"] - > ![Edit area path dialog](media/config-teams/edit-area-path.png) + > ![Screenshot shows the edit area path dialog.](media/config-teams/edit-area-path.png) Repeat this step for all feature team area paths. -::: moniker-end - - ## Include subarea paths for management teams By including subarea paths for the management teams, you automatically include the backlog items of their feature teams onto the management team's backlog. The default setting for all teams is to exclude subarea paths. > [!NOTE] -> Sub-area paths may break a team's ability to reorder or reparent items on the backlog. Also, it can introduce uncertainties with regards to assignments made to the Kanban Board Column, Done, and Lane fields. For more information, see [Exercising select features with shared area paths](#op-issues) later in this article. +> Sub-area paths may break a team's ability to reorder or reparent items on the backlog. Also, it can introduce uncertainties with regards to assignments made to the board Column, Done, and Lane fields. For more information, see [Exercising select features with shared area paths](#op-issues) later in this article. -::: moniker range=">= azure-devops-2019" -You define both areas and iterations from **Project Settings>Boards>Team configuration**. You can quickly go to it from **Teams**. +To define both areas and iterations do the following steps: -1. From **Project Settings**, choose **Teams**, and then choose the team whose settings you want to modify. +1. Select **Project settings** > **Teams**, and then choose the team whose settings you want to modify. Here we open the Account Management team. > [!div class="mx-imgBorder"] - > ![Teams, choose a team](media/config-teams/choose-management-team.png) + > ![Screenshot shows Teams, choose a team.](media/config-teams/choose-management-team.png) -1. Choose **Iterations and areas** and then **Areas**. +2. Select **Iterations and areas** > **Areas**. > [!div class="mx-imgBorder"] - > ![Team Profile, choose Iterations and area](media/config-teams/open-iterations-areas.png) + > ![Screenshot shows Team Profile, choose Iterations and area.](media/config-teams/open-iterations-areas.png) - If you need to switch the team context, use the team selector within the breadcrumbs. + To switch the team context, use the team selector within the breadcrumbs. -2. Choose **Select area(s)**, and select the area path for **Account Management** and check the **Include sub areas** checkbox. +3. Choose **Select area(s)**, and select the area path for **Account Management** and check the **Include sub areas** checkbox. > [!div class="mx-imgBorder"] - > ![Select areas for Account Management team](media/config-teams/include-sub-area-paths.png) + > ![Screenshot shows Select areas for Account Management team.](media/config-teams/include-sub-area-paths.png) - Verify that only this area path is selected for the team and is the default area path. Remove any other area paths that may have been previously selected. + Verify that only this area path is selected for the team and is the default area path. Remove any other previously selected area paths. > [!div class="mx-imgBorder"] - > ![Verify area paths for Account Management team](media/config-teams/verify-area-path-assignments.png) - - Repeat this step for all your management areas. If you want to enable rollup across all feature teams and management areas to the top-level area, repeat this step for the default team. In our example, that corresponds to Fabrikam Fiber. - -::: moniker-end - - -::: moniker range="tfs-2018" - -1. You open team settings from the top navigation bar. Select the team you want and then choose the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: gear icon. To learn more about switching your team focus, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md#switch-team-context) - - > [!div class="mx-imgBorder"] - > ![Open team settings](../../organizations/settings/media/team-defaults/open-team-settings-horz.png) - -1. Choose **Work**, and then **Areas**. - -2. Choose **Select area(s)**, and select the area path for **Account Management** and check the **Include sub areas** checkbox. - - > [!div class="mx-imgBorder"] - > ![Select areas for Account Management team](media/config-teams/include-sub-area-paths.png) - - Verify that only this area path is selected for the team and is the default area path. Remove any other area paths that may have been previously selected. - - > [!div class="mx-imgBorder"] - > ![Verify area paths for Account Management team](media/config-teams/verify-area-path-assignments.png) - - Repeat this step for all your management areas. If you want to enable rollup across all feature teams and management areas to the top-level area, repeat this step for the default team. In our example, that corresponds to Fabrikam Fiber. - -::: moniker-end + > ![Screenshot shows Verify area paths for Account Management team.](media/config-teams/verify-area-path-assignments.png) + Repeat this step for all your management areas. If you want to enable rollup across all feature teams and management areas to the top-level area, repeat this step for the default team. In our example that corresponds to Fabrikam Fiber. ## Define a single sprint cadence for all teams -If your feature teams use Scrum or use sprints to assign their work, you'll want to set up a series of sprints that all teams can use. By default, you'll see a set of predefined sprints. Add more sprints and set their sprint dates from **Project Settings** as described in [Add iterations and set iteration dates](../../organizations/settings/set-iteration-paths-sprints.md). You can rename and edit the default sprints as needed. +If your feature teams use Scrum or use sprints to assign their work, set up a series of sprints that all teams can use. By default, you see a set of predefined sprints. Add more sprints and set their sprint dates from **Project Settings** as described in [Add iterations and set iteration dates](../../organizations/settings/set-iteration-paths-sprints.md). You can rename and edit the default sprints as needed. > [!NOTE] > While maintaining a single sprint cadence simplifies project administration, you can create different cadences as needed. For example, some teams may follow a monthly cadence while others follow a 3-week cadence. Simply define a node under the top project node for each cadence, and then define the sprints under those nodes. For example: @@ -206,63 +130,42 @@ If your feature teams use Scrum or use sprints to assign their work, you'll want > Here we define the start and end dates of the first 6 sprints corresponding to a 3-week cadence. > [!div class="mx-imgBorder"] -> ![Iteration path](../../organizations/settings/media/areas/modify-areas-its-iterations-scheduled-ts.png) - - +> ![Screenshot shows Iteration path.](../../organizations/settings/media/areas/modify-areas-its-iterations-scheduled-ts.png) ## Configure other team settings -For teams to be well defined, you'll want to add team administrator(s) and have them verify or configure other team settings. For more information, see [Manage and configure team tools](../../organizations/settings/manage-teams.md). - -## Review area paths assigned to teams +For teams to be well defined, add team administrators and have them verify or configure other team settings. For more information, see [Manage and configure team tools](../../organizations/settings/manage-teams.md). -::: moniker range=">= azure-devops-2019" +## Review area paths assigned to teams -From **Project Settings>Project configuration>Areas**, you can review which **Area Paths** have been assigned to which teams. To modify the assignments, choose the team and change the team's area path assignments. +From **Project Settings>Project configuration>Areas**, you can review which **Area Paths** are assigned to which teams. To modify the assignments, choose the team and change the team's area path assignments. > [!div class="mx-imgBorder"] -> ![Area Paths and Teams](media/config-teams/review-area-paths-teams.png) -::: moniker-end +> ![Screenshot shows Area Paths and Teams.](media/config-teams/review-area-paths-teams.png) -::: moniker range="tfs-2018" -From **Project Settings>Work>Areas**, you can review which **Area Paths** have been assigned to which teams. To modify the assignments, choose the team and change the team's area path assignments. - -> [!div class="mx-imgBorder"] -> ![Area Paths and Teams](media/config-teams/review-area-paths-teams.png) -::: moniker-end - - + ## Exercising select features with shared area paths -When you share area paths across two or more teams, you'll want to understand how Azure Boards manages conflicts that can arise when exercising these features: +When you share area paths across two or more teams, understand how Azure Boards manages conflicts that can arise when exercising these features: - Reordering or reparenting work items on a backlog or board -- Updates made to Kanban **Board Column**, **Board Column Done**, and **Board Lane** fields when dragging items to a different column +- Updates made to **Board column**, **Board column done**, and **Board Lane** fields when dragging items to a different column ### Reordering and reparenting work items -All backlogs and boards support drag-and-drop to reorder and reparent work items. Updates made to one team backlogs and boards are reflected in other team backlogs and boards that share the same area path. You may need to refresh the page to view the changes. +All backlogs and boards support drag-and-drop functionality for reordering and reparenting work items. Changes made in one team's backlogs and boards are automatically reflected in other team backlogs and boards that share the same area path. You might need to refresh the page to see these updates. -You can only use drag-and-drop to reorder or reparent work items assigned to area paths selected for your team. When the **Parents** view option is enabled, work items may appear on your backlog that your team doesn't own. Anything that appears with the :::image type="icon" source="../../media/icons/info.png" border="false"::: information icon can't be reordered nor reparented as it's owned by another team. +Drag-and-drop can only be used to reorder or reparent work items that are assigned to area paths selected for your team. When the **Parents** view option is enabled, work items that your team doesn't own might appear in your backlog. Any work item marked with the :::image type="icon" source="../../media/icons/info.png" border="false"::: information icon can't be reordered or reparented, as another team owns it. :::image type="content" source="media/config-teams/information-message-owned-by-other-team.png" alt-text="Screenshot of information message on team ownership."::: +### Board column updates -### Kanban board column updates - -Because each team can customize the Kanban board columns and swimlanes, the values assigned to Kanban board fields may differ from what you expect when another team updates the work item from a different board. Even if the management team and the feature teams configure their Feature [Kanban board columns](../boards/add-columns.md) with identical workflow mapping, updating work items on one team's Kanban board won't be reflected on another team's Kanban board. Only when the work item moves to a column that maps to a workflow state does the card column reflect the same on all boards. - -By design, the team with the longest area path wins the conflict and determines the values for the Kanban **Board Column**, **Board Column Done**, and **Board Lane** fields. If the shared area paths are of equal depth, the results are non-deterministic. - -::: moniker range=">= azure-devops-2019" - The primary work-around for this issue is to maintain single ownership of work items by [Defining area paths and assign to a team](../../organizations/settings/set-area-paths.md). Another option is to add custom workflow states that all teams can use. For more information, see [Customize the workflow (Inheritance process)](../../organizations/settings/work/customize-process-workflow.md). - -::: moniker-end +Because each team can customize their board columns and swimlanes, the values assigned to board fields might differ when another team updates a work item from a different board. Even if the management team and the feature teams configure their [Feature board columns](../boards/add-columns.md) with identical workflow mappings, updates made to work items on one team's board don't automatically reflect on another team's board. The card column updates consistently across all boards only when a work item moves to a column that maps to a workflow state. -::: moniker range="tfs-2018" - The primary work-around for this issue is to maintain single ownership of work items by [Defining area paths and assign to a team](../../organizations/settings/set-area-paths.md). Another option is to add custom workflow states that all teams can use. For more information, see [Change the workflow for a work item type](../../reference/xml/change-workflow-wit.md). -::: moniker-end +By design, the team with the longest area path takes precedence in resolving conflicts and determines the values for the **Board Column**, **Board Column Done**, and **Board Lane** fields. If two or more teams share area paths of equal depth, the results are nondeterministic. +The primary workaround is to maintain single ownership of work items by [defining area paths and assigning them to a specific team](../../organizations/settings/set-area-paths.md). Alternatively, you can add custom workflow states that all teams can use uniformly. For more information, see [Customize the workflow (Inheritance process)](../../organizations/settings/work/customize-process-workflow.md). ## Next steps > [!div class="nextstepaction"] @@ -271,7 +174,7 @@ By design, the team with the longest area path wins the conflict and determines ## Related articles - [Create your backlog](../backlogs/create-your-backlog.md) -- [Kanban quickstart](../boards/kanban-quickstart.md) +- [Create a board](../boards/kanban-quickstart.md) - [Organize your backlog](../backlogs/organize-backlog.md) - [Work with multi-team ownership of backlog items](../backlogs/backlogs-overview.md#multi-team) - [Fix display, reordering, and nesting issues](../backlogs/resolve-backlog-reorder-issues.md) diff --git a/docs/boards/plans/faqs.yml b/docs/boards/plans/faqs.yml index 0d870159757..5ae5213c4e6 100644 --- a/docs/boards/plans/faqs.yml +++ b/docs/boards/plans/faqs.yml @@ -33,7 +33,7 @@ sections: [**Delivery Plans 2.0**](review-team-plans.md) :::column-end::: :::column span="2"::: - [**Delivery Plans Extension**](../extensions/delivery-plans.md) + [**Delivery Plans Extension**](../plans/review-team-plans.md) :::column-end::: :::row-end::: :::row::: diff --git a/docs/boards/plans/index.md b/docs/boards/plans/index.md index 4a93063cb90..e198475fd4e 100644 --- a/docs/boards/plans/index.md +++ b/docs/boards/plans/index.md @@ -1,10 +1,8 @@ --- -title: Use Agile tools to use portfolios, dashboards, and delivery plans in Azure Boards +title: Use Agile tools to use portfolios, dashboards, and delivery plans in Azure Boards titleSuffix: Azure Boards description: Learn how to scale Agile tools using portfolios, dashboards, and delivery plans in Azure Boards and Azure DevOps. -ms.custom: seodec18 ms.service: azure-devops-boards -ms.assetid: ms.author: chcomley author: chcomley ms.topic: overview @@ -25,7 +23,7 @@ As your organization grows, you want your tools to scale to support your growing ## Video: Agile at Scale -> [!VIDEO https://www.microsoft.com/videoplayer/embed/RE3wM7v] +> [!VIDEO https://learn-video.azurefd.net/vod/player?id=40ca5566-4875-4611-ba66-3ec22fa0c343] ## Portfolio management diff --git a/docs/boards/plans/media/plans/open-plans.png b/docs/boards/plans/media/plans/open-plans.png index 8ae0eab36e2..3b1cdac7a34 100644 Binary files a/docs/boards/plans/media/plans/open-plans.png and b/docs/boards/plans/media/plans/open-plans.png differ diff --git a/docs/boards/plans/media/safe-add-migrate-team-members.png b/docs/boards/plans/media/safe-add-migrate-team-members.png deleted file mode 100644 index 898794fd43d..00000000000 Binary files a/docs/boards/plans/media/safe-add-migrate-team-members.png and /dev/null differ diff --git a/docs/boards/plans/media/safe-add-team-members.png b/docs/boards/plans/media/safe-add-team-members.png deleted file mode 100644 index d4e16bd360f..00000000000 Binary files a/docs/boards/plans/media/safe-add-team-members.png and /dev/null differ diff --git a/docs/boards/plans/portfolio-management.md b/docs/boards/plans/portfolio-management.md index 63b505d1f18..5104c7d92a3 100644 --- a/docs/boards/plans/portfolio-management.md +++ b/docs/boards/plans/portfolio-management.md @@ -1,5 +1,5 @@ --- -title: Manage your product and portfolio backlogs with Azure Boards +title: Manage your product and portfolio backlogs titleSuffix: Azure Boards description: Learn how to work with a hierarchical team structure to manage product and portfolio backlogs and to track progress across teams. ms.service: azure-devops-boards @@ -7,193 +7,118 @@ ms.assetid: F6FF6E6B-C9AA-4681-9205-D48C8F29D94B ms.author: chcomley author: chcomley ms.topic: tutorial +ai-usage: ai-assisted monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 09/12/2024 --- -# Use Azure Boards to manage your product and portfolio backlogs +# Manage your product and portfolio backlogs [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Portfolio backlogs provide product owners insight into the work done by several agile feature teams. Product owners can define the high-level goals as Epics or Features. Feature teams can break down these work items into the user stories they'll prioritize and develop. +Portfolio backlogs give product owners insight into the work of multiple agile feature teams. Product owners define high-level goals as Epics or Features, which feature teams break down into user stories to prioritize and develop. -In this article you'll learn: +[!INCLUDE [note-configure-customize](../includes/note-configure-customize.md)] ->[!div class="checklist"] -> * How to support a management view of multiple team progress -> * How feature teams can focus on their team backlog progress -> * How to assign work from a common backlog -> * How to set up a hierarchical set of teams and backlogs +Setting up a team structure like the one shown provides each feature team with a distinct backlog to plan, prioritize, and track their work. Portfolio or product owners can create their vision, roadmap, and goals for each release, monitor progress across projects, and manage risks and dependencies. -[!INCLUDE [configure-customize](../includes/note-configure-customize.md)] +To support the following elements, [set up a hierarchical team and backlog structure](configure-hierarchical-teams.md): -By setting up a team structure like the one shown, you provide each feature team with their distinct backlog to plan, prioritize, and track their work. And, portfolio or product owners can create their vision, roadmap, and goals for each release, monitor progress across their portfolio of projects, and manage risks and dependencies. +- **Organize and manage backlogs:** Enable autonomous feature teams to organize and manage their own backlogs. +- **Plan and monitor:** Use portfolio management views to plan epics and features and monitor the progress of feature teams. +- **Assign backlog items:** Assign backlog items to feature teams from a common backlog. -![Each team has its own view of the work](media/pm-team-structure.png) +![Screenshot shows each team has its own view of the work.](media/pm-team-structure.png) -[Set up a hierarchical team and backlog structure](configure-hierarchical-teams.md) when you want to support the following elements: - -- Autonomous feature teams that can organize and manage their backlog of work -- Portfolio management views for planning epics and features and monitoring progress of subordinate feature teams -- Assign backlog items to feature teams from a common backlog +[!INCLUDE [prerequisites-team-settings](../includes/prerequisites-team-settings.md)] [!INCLUDE [image differences](../includes/image-differences.md)] -## Management view of team progress - -In this example, we show the **Epics** portfolio backlog for the **Management** team. Drilling down, you can see all the backlog items and features, even though they belong to one of three different teams: Customer Service, Phone, and Web. - -::: moniker range=">= azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Backlog that shows parents and multi-team ownership.](../backlogs/media/multi-ownership/management-team-backlog-epics.png) - -::: moniker-end - - -::: moniker range="tfs-2018" +## Manage view of team progress -In this example, we show the **Epics** portfolio backlog for the **Management** team. Drilling down, you can see all the backlog items and features, even though they belong to one of three different teams: Customer Service, Phone, and Web. +In the following example, we show the **Epics** portfolio backlog for the **Management** team. Drilling down, you see all the backlog items and features, even though they belong to one of three different teams: Customer Service, Phone, and Web. > [!div class="mx-imgBorder"] -> ![Backlog that shows parents and multi-team ownership.](../backlogs/media/multi-ownership/management-team-backlog-epics-pre-nav.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -> [!TIP] -> Program managers can also gain insight into progress across teams using [Delivery plans](review-team-plans.md). See also [Visibility across teams](visibility-across-teams.md). - -::: moniker-end +> ![Screenshot show Backlog parents and multi-team ownership.](../backlogs/media/multi-ownership/management-team-backlog-epics.png) +> [!IMPORTANT] +> You can establish child links with work items from different projects. But, if the processes differ between projects, the hierarchy isn't visible on the backlog for those child items in separate projects. You can still view all associated child items directly on the work item form. -## Feature team backlog ownership and view of progress - -Each feature team has its own team home page or dashboards, product and portfolio backlogs, Kanban boards, and Taskboards. These pages only show work relevant to each team. The relevance is based on assignments made to the work item area and iteration paths. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). - -> [!TIP] -> Add **Node Name** to the column options to show the team assigned to the work item. - -::: moniker range=">= azure-devops-2019" - -The Customer Service feature team's view of the backlog only includes those work items assigned to their area path, **Fabrikam Fiber/Customer Service**. Here we show parents that provide a few of the features and epics to which the backlog items belong. Items that are owned by other teams appear with hollow-filled bars. For example, Mobile feedback and Text alerts belong to the Account Management team. - -Items that are owned by other teams appear with an information icon, :::image type="icon" source="../../media/icons/info.png" border="false"::: . +## Visualize team backlog ownership and progress -> [!div class="mx-imgBorder"] -> ![Backlog that shows parents and multi-team ownership](../backlogs/media/multi-ownership/customer-service-backlog-parents-on.png) +Each team has its own home page or dashboards, product and portfolio backlogs, boards, and Taskboards. These pages show work relevant only to each team, based on assignments made to the work item area and iteration paths. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). -::: moniker-end +To visualize ownership and progress involving other teams, do the following tasks: +- **Show parent items:** [Configure your backlog to show parent epics or features owned by other teams](../backlogs/backlogs-overview.md). +- **Use queries:** [Create queries to include work items from other teams](../work-items/move-work-items.md). Add these queries to your team’s dashboard for better visibility. +- **Utilize Plans:** Use the ["Plans" feature](review-team-plans.md) in Azure Boards, which gives you cross-team visibility into work items across multiple teams. This action lets you see all backlog items and features, even if they belong to different teams. -::: moniker range="tfs-2018" +> [!TIP] +> Add **Node name** to the **Column options** to show the team name assigned to each work item. -Items that are owned by other teams appear with an information icon, :::image type="icon" source="../../media/icons/info.png" border="false"::: . +For example, the Fabrikam Fiber Team's backlog view includes work items assigned to their area path, **Fabrikam Fiber**, and the parent Epic, which is assigned to the **Fabrikam** team. Items owned by other teams appear with an information icon, :::image type="icon" source="../../media/icons/info.png" border="false":::. Hover over the information icon for the Epic to see more details. > [!div class="mx-imgBorder"] -> ![Backlog that shows parents and multi-team ownership](../backlogs/media/multi-ownership/customer-service-backlog-parents-on-prev-nav.png) +> ![Screenshot of Backlog that shows parents and multi-team ownership.](../backlogs/media/multi-ownership/backlog-parents-on.png) -::: moniker-end - ## Assign work from a common backlog -While the hierarchical team and backlog structure works well to support autonomous teams to take ownership of their backlog, it also supports assigning work to teams from a common backlog. During a sprint or product planning meeting, product owners and development leads can review the backlog. Teams can also assign select items to various teams by assigning them to the feature team Area Path. - -In this view of the Account Management backlog, all items still assigned to **Account Management** have yet to be assigned. +The hierarchical team and backlog structure enables autonomous teams to take ownership of their backlogs and allows for assigning work to teams from a common backlog. During sprint or product planning meetings, product owners and development leads can review the backlog. Teams can then assign specific items to various teams by setting the feature team Area Path. -::: moniker range=">= azure-devops-2019" +In the following view of the Account Management backlog, all items still assigned to **Account Management** have yet to be assigned to specific teams. > [!div class="mx-imgBorder"] -> ![Management team common backlog](media/portfolio/account-management-backlog.png) +> ![Screenshot showing Management team common backlog.](media/portfolio/account-management-backlog.png) -During the planning meeting, you can open each item, make notes, and assign the item to the team to work on it. +During the planning meeting, open each item, make notes, and assign it to the appropriate team for action. > [!TIP] -> You can multi-select work items and perform a bulk edit of the area path. See [Bulk modify work items](../backlogs/bulk-modify-work-items.md). +> Select multiple work items and perform a bulk edit of the area path. For more information, see [Bulk modify work items](../backlogs/bulk-modify-work-items.md). -Here, all backlog items have been assigned to feature teams while all features and epics remain owned by Account Management. +In the following example, all backlog items were assigned to feature teams while all features and epics remain owned by Account Management. > [!div class="mx-imgBorder"] -> ![All backlog items have been assigned to feature teams.](media/portfolio/account-management-backlog-assigned.png) - -::: moniker-end - - -::: moniker range="tfs-2018" - -In this view of the Account Management backlog, all items still assigned to **Account Management** have yet to be assigned. - -> [!div class="mx-imgBorder"] -> ![Management team common backlog](media/portfolio/account-management-backlog-prev-nav.png) - -During the planning meeting, you can open each item, make notes, and assign the item to the team to work on it. - -> [!TIP] -> You can multi-select work items and perform a bulk edit of the area path. See [Bulk modify work items](../backlogs/bulk-modify-work-items.md). - -Here, all backlog items have been assigned to feature teams while all features and epics remain owned by Account Management. - -> [!div class="mx-imgBorder"] -> ![All backlog items have been assigned to feature teams.](media/portfolio/account-management-backlog-assigned.png) - -::: moniker-end - +> ![Screenshot shows All backlog items assigned to feature teams.](media/portfolio/account-management-backlog-assigned.png) ## Add portfolio backlogs -::: moniker range=">= azure-devops-2019" - -If you need more than three backlog levels, you can add more. To learn how, see [Customize your backlogs or boards for a process](../../organizations/settings/work/customize-process-backlogs-boards.md). - -::: moniker-end - -::: moniker range="tfs-2018" - -If you need more than three backlog levels, you can add more. To learn how, see [Add portfolio backlogs](../../reference/add-portfolio-backlogs.md). - -::: moniker-end +If you need more than three backlog levels, add more. For more information, see [Customize your backlogs or boards for a process](../../organizations/settings/work/customize-process-backlogs-boards.md). ## Track dependencies across teams -The simplest way to track dependencies across teams is to link work items using the **Related** link type. If they're dependent in time, then you can use the **Predecessor/Successor** link types. You can then create queries that find work items containing these relationships. See [Manage dependencies, link work items to support traceability](../queries/link-work-items-support-traceability.md) to learn more. +The simplest way to track dependencies across teams is to link work items using the **Related** link type. For time-based dependencies, use the **Predecessor/Successor** link types. You can then create queries to find work items with these relationships. For more information, see [Link work items to other objects](../backlogs/add-link.md). ::: moniker range="azure-devops" Using Delivery Plans, you can track dependencies across projects within an organization. For more information, see [Track dependencies using Delivery Plans](../plans/track-dependencies.md). ::: moniker-end -## Portfolio feature progress +## View portfolio feature progress ::: moniker range=">= azure-devops-2022" -To view feature progress based on linked requirements, you can add a rollup column or view a delivery plan. For more information, see [Display rollup](../backlogs/display-rollup.md) and [Review delivery plans](review-team-plans.md). +To view feature progress based on linked requirements, add a rollup column or view a delivery plan. For more information, see [Display rollup](../backlogs/display-rollup.md) and [Review delivery plans](review-team-plans.md). ::: moniker-end ::: moniker range="< azure-devops-2022" -To view feature progress based on linked requirements, you can view the Feature Timeline. For more information, see [View portfolio progress with the Feature Timeline](/previous-versions/azure/devops/all/extensions/feature-timeline). +To view feature progress based on linked requirements, use the Feature Timeline. For more information, see [View portfolio progress with the Feature Timeline](/previous-versions/azure/devops/all/extensions/feature-timeline). ::: moniker-end - ## Next steps > [!div class="nextstepaction"] > [Configure a hierarchy of teams](configure-hierarchical-teams.md) - ## Related articles -- [Create your backlog](../backlogs/create-your-backlog.md) -- [Kanban quickstart](../boards/kanban-quickstart.md) +- [Create your backlog](../backlogs/create-your-backlog.md) +- [Get started with Kanban](../boards/kanban-quickstart.md) - [Assign work to sprints](../sprints/assign-work-sprint.md) - [Organize your backlog](../backlogs/organize-backlog.md) -- [Limitations of multi-team Kanban board views](../boards/kanban-overview.md#limits-multi-team) - - - - +- [Understand limitations of multi-team board views](../boards/kanban-overview.md) \ No newline at end of file diff --git a/docs/boards/plans/practices-that-scale.md b/docs/boards/plans/practices-that-scale.md index 713db326ad0..1482bfed79d 100644 --- a/docs/boards/plans/practices-that-scale.md +++ b/docs/boards/plans/practices-that-scale.md @@ -82,7 +82,7 @@ You improve organizational effectiveness by attending to the culture you want to See the [Agile Retrospective Resource Wiki](https://retrospectivewiki.org/index.php?title=Agile_Retrospective_Resource_Wiki) for ideas, tips, and tools for planning and conducting retrospectives. See also the [Marketplace Retrospectives extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives). - **Improvement tracking board**: Good ideas to improve processes can arise from any one at any time. Capturing those ideas to discuss and decide on how to act on them quickly is a key to support process improvement efforts. - A white board provides any easy and visual means with which to capture ideas. Also, you can create an Improvement tracking team and capture ideas that you track on an electronic [Kanban board](../boards/kanban-overview.md). + A white board provides any easy and visual means with which to capture ideas. Also, you can create an Improvement tracking team and capture ideas that you track on an electronic [board](../boards/kanban-overview.md). - **Institutionalize sharing**: Sharing best practices and communicating ideas helps all teams within an organization grow and improve. Developing a culture of learning is key to supporting this and other continuous improvement activities. Some ideas to consider: - In-house wikis diff --git a/docs/boards/plans/review-team-plans.md b/docs/boards/plans/review-team-plans.md index 3157c4c8bf2..4204483dcbc 100644 --- a/docs/boards/plans/review-team-plans.md +++ b/docs/boards/plans/review-team-plans.md @@ -1,75 +1,54 @@ --- title: Review team delivery plans in Azure Boards titleSuffix: Azure Boards -description: Learn how to add, edit, and use delivery plans in Azure Boards to review multiple-team deliverables, rollups, and dependencies +description: Learn how to add, edit, and use delivery plans in Azure Boards to review multiple-team deliverables, rollups, and dependencies. ms.service: azure-devops-boards ms.assetid: 3B41D55E-B7B1-41B1-B68F-7A83BA2890A5 ms.author: chcomley author: chcomley ms.topic: tutorial ms.custom: cross-project +ai-usage: ai-assisted monikerRange: '>= azure-devops-2022' -ms.date: 08/09/2022 +ms.date: 09/16/2024 --- - # Review team delivery plans in Azure Boards [!INCLUDE [version-gt-eq-2022](../../includes/version-gt-eq-2022.md)] Use the visualization options provided by the Delivery Plans feature of Azure Boards to review the schedule of stories or features that your teams plan to deliver. A delivery plan shows the scheduled work items by sprint (iteration path) of selected teams against a calendar view. -> [!NOTE] -> This article describes using Delivery Plans 2.0, which is available for Azure DevOps Services and Azure DevOps Server 2022. For information on the Delivery Plans Marketplace extension that supports Azure DevOps Server 2020 and earlier versions, see [Delivery Plans 1.0](../extensions/delivery-plans.md). - Use the Delivery Plans feature to ensure that your teams are aligned with your organizational goals. You can view multiple backlogs and multiple teams across your whole account. Interact with the plan by using simple drag-and-drop operations to update or modify the schedule, open cards, expand and collapse teams, and more. -Delivery Plans supports these tasks: +Delivery Plans supports the following tasks: - View up to 20 team backlogs, including a mix of backlogs and teams from different projects. -- Add custom portfolio backlogs and epics. -- View work items that span several iterations. -- Reset start date and target date through drag-and-drop borders. -- Add backlog items to a team from a plan. +- Add custom portfolio backlogs and epics. +- View work items spanning several iterations. +- Reset start and target dates using drag-and-drop borders. +- Add backlog items to a team directly from a plan. - View rollup progress of features, epics, and other portfolio items. -- View dependencies that exist between work items. +- View dependencies between work items. - Enable stakeholders to view plans. -Any plan that you created with the original Delivery Plans extension works with the Delivery Plans feature. You don't have to migrate any data or reconfigure plan settings. To learn how to add or edit a plan, see [Add or edit a delivery plan](add-edit-delivery-plan.md). - -> [!div class="mx-imgBorder"] -> ![Screenshot of a feature roadmap in Delivery Plans.](media/plans/intro-image.png) - -In this article, you'll learn how to: +Any plan that you created with the original Delivery Plans extension works with the Delivery Plans feature. You don't have to migrate any data or reconfigure plan settings. For more information, see [Add or edit a delivery plan](add-edit-delivery-plan.md). -> [!div class="checklist"] -> - Open a plan from the list of defined plans. -> - Review a plan with your teams. -> - Use the interactive elements of plans and change a plan view. -> - View rollups. +:::image type="content" source="media/plans/intro-image.png" alt-text="Screenshot of a feature roadmap in Delivery Plans."::: For information on working with dependencies, see [Track dependencies](track-dependencies.md). - ## Prerequisites -- To view a delivery plan, you must be a member of the Project Collection Valid Users group. Users granted **Stakeholder** access for a private project can view plans. Users granted **Stakeholder** access for a public project can add and view plans. -- To open or modify a work item or add work items to a plan, you must have **Edit work items in this node** set to **Allow** for the area paths assigned to the work item. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md#set-permissions-area-path). - - -For work items and dependency lines to appear on the plan: - -- Work items must belong to a team's [product backlog](../backlogs/create-your-backlog.md) or [portfolio backlog](../backlogs/define-features-epics.md). Only work items that belong to a category selected for viewing on a team's backlog appear on the plan. -- [Team product or portfolio backlog must be enabled](../../organizations/settings/select-backlog-navigation-levels.md). -- [Sprints must be selected for each team](../../organizations/settings/set-iteration-paths-sprints.md#select-team-sprints-and-set-the-default-iteration-path) defined in the plan. -- [Start and end dates](../../organizations/settings/set-iteration-paths-sprints.md#add-iterations-and-set-iteration-dates) must be defined for each iteration. -- [Iteration paths](../sprints/assign-work-sprint.md) must be assigned to each work item. -- For dependency icons and lines to show, [work items must be linked](../backlogs/add-link.md) via the **Predecessor-Successor** link type or other custom dependency link type. (Remote link types are not supported.) You can add custom link types only for on-premises environments. +| Category | Requirements | +|--------------|-------------| +| **Access levels** | To view a delivery plan: Member of the **Project Collection Valid Users** group. Users granted **Stakeholder** access for a private project can view plans. Users granted **Stakeholder** access for a public project can add and view plans. | +| **Permissions** | To open or modify a work item or add work items to a plan: **Edit work items in this node** permission set to **Allow** for the area paths assigned to the work item. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md#set-permissions-area-path). | +| **Configuration** |- Work items belong to a team's [product backlog](../backlogs/create-your-backlog.md) or [portfolio backlog](../backlogs/define-features-epics.md). Only work items that belong to a category selected for viewing on a team's backlog appear on the plan.
- [Team product or portfolio backlog enabled](../../organizations/settings/select-backlog-navigation-levels.md).
- [Sprints selected for each team](../../organizations/settings/set-iteration-paths-sprints.md#select-team-sprints-and-set-the-default-iteration-path) defined in the plan.
- [Start and end dates](../../organizations/settings/set-iteration-paths-sprints.md#add-iterations-and-set-iteration-dates) defined for each iteration.
- [Iteration paths](../sprints/assign-work-sprint.md) assigned to each work item.
- For dependency icons and lines to show: [work items linked](../backlogs/add-link.md) via the **Predecessor-Successor** link type or other custom dependency link type. (Remote link types aren't supported.) You can add custom link types only for on-premises environments. | > [!TIP] > If you edit a plan and the changes that you make don't seem to appear in the plan, refresh your browser. A browser refresh is sometimes needed to trigger the updates. - ## Review a plan with your teams It takes multiple autonomous teams to develop large software projects. Autonomous teams manage their own backlog and priority, which contributes to a unified direction for that project. Review [Agile culture](agile-culture.md) for a discussion of autonomous teams and organizational alignment. @@ -82,127 +61,121 @@ Questions that you might address during the review include: - *Are dependencies across teams adequately addressed via the planned deliverables?* - *Are there gaps in the schedule, where no deliverables are scheduled? What's the cause? Can the issue be mitigated?* -For example, you might use delivery plans internally to share the schedule of features. By seeing the work that many teams have planned for the next three sprints, you can easily see if a plan has the right priorities and spot dependencies. +For example, you might use delivery plans internally to share the schedule of features. By seeing the work that many teams planned for the next three sprints, you can easily see if a plan has the right priorities and spot dependencies. In this way, a delivery plan is a driver of alignment while letting each team remain autonomous. Individual teams can work to different sprint cadences, if needed, and manage different work item types (stories, features, or epics). Their work is all visible with the same plan view. Teams can even be part of different projects if they use different processes. Customize the card fields so that you see only the data fields that interest you and that apply for each work item type. ## Best practices for using a delivery plan -- Determine how you want to use the delivery plan. Some ideas are: - - Review quarterly plans for features to be delivered. - - Sync up monthly with several teams that have dependencies. - - Review cross-project deliverables and identify dependencies. -- Use a consistent sprint schedule across your project teams and organization when possible. Although the plan can accommodate a variety of sprint schedules, it adds to visual clutter. Use the same sprints for backlogs, features, and epics. Don't create specific sprints for epics or other portfolio backlogs. -- Use **Start Date** and **Iteration** to specify the time frame for a work item. Or, use **Start Date** and **Target Date**. However, don't specify both **Iteration** and **Target Date** for a work item. **Target Date** always overrides the **Iteration** end date on the plan. -- Minimize the number of fields that you choose to display on your cards. -- Eliminate cross-team ownership of area paths. Cross-team ownership of area paths can lead to undesirable edge cases. -- Keep your work items up to date. When changes occur, update the target dates or iteration paths. - -Note the following items: - -- Plan views display the set of months that correspond to the iteration paths selected by the teams whose backlogs appear in the plan. -- Plan views are limited to a maximum of 15 teams or backlogs. -- Zooming out can cause fields and tags to disappear from the cards. The farther you zoom out, the harder it is to fit items on a card. Certain items might be hidden, depending on the zoom level. -- Rollup isn't supported for child work items that belong to a different project than that of the originating parent work item. -- If **Start Date** or **Target Date** is missing from a work item, you can add it to the custom process defined for the project, as discussed in [Add and manage fields (inheritance process)](../../organizations/settings/work/customize-process-field.md#add-an-existing-field-to-another-wit). +- Determine how you want to use the delivery plan. Some ideas include: + - Reviewing quarterly plans for features to be delivered. + - Syncing up monthly with several teams that have dependencies. + - Reviewing cross-project deliverables and identifying dependencies. +- Use a consistent sprint schedule across your project teams and organization when possible. Although the plan can accommodate various sprint schedules, it adds to visual clutter. Use the same sprints for backlogs, features, and epics. Avoid creating specific sprints for epics or other portfolio backlogs. +- Use **Start Date** and **Iteration** to specify the time frame for a work item, or use **Start Date** and **Target Date**. However, don't specify both **Iteration** and **Target Date** for a work item. **Target Date** always overrides the **Iteration** end date on the plan. +- Minimize the number of fields displayed on your cards. +- Eliminate cross-team ownership of area paths to avoid undesirable edge cases. +- Keep your work items up to date. When changes occur, update the target dates or iteration paths. +- Be aware of the following: + - Plan views display the set of months that correspond to the iteration paths selected by the teams whose backlogs appear in the plan. + - Plan views are limited to a maximum of 20 teams or backlogs. + - Zooming out can cause fields and tags to disappear from the cards. The farther you zoom out, the harder it is to fit items on a card. Certain items might be hidden, depending on the zoom level. + - Rollup isn't supported for child work items that belong to a different project than that of the originating parent work item. + - If **Start Date** or **Target Date** is missing from a work item, you can add it to the custom process defined for the project, as discussed in [Add and manage fields (inheritance process)](../../organizations/settings/work/customize-process-field.md#add-an-existing-field-to-another-wit). ## Open a plan -After you've defined a few plans, you'll see them listed on the **Plans** page under **All**. Or you'll see the ones you've favorited under **Favorites**. You can see their title, description, and most recent creator/editor. +After you define a few plans, they appear on the **Plans** page under **All** or **Favorites**, showing the title, description, and most recent creator/editor. -Use **Add to favorites** :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: to favorite a plan so that you can quickly return to that plan. You can also search for other plans in the project. +Use **Add to favorites** :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: to favorite a plan for quick access. You can also search for other plans in the project. -To open a plan, open **Boards** > **Delivery Plans** and choose the plan name. You can sort by any of the columns: **Name**, **Created By**, **Description**, **Last configured**, or **Favorites**. +To open a plan, go to **Boards** > **Delivery Plans** and select the plan name. You can sort by any of the columns: **Name**, **Created By**, **Description**, **Last configured**, or **Favorites**. -> [!div class="mx-imgBorder"] -> ![Screenshot that shows the Delivery Plans area in Azure Boards.](media/plans/open-plans.png) +:::image type="content" source="media/plans/open-plans.png" alt-text="Screenshot of the Delivery Plans area in Azure Boards."::: ## Interact with a plan -Each team's backlog specified in a delivery plan appears as a row within the plan view. When a row is collapsed, a rollup of the backlog items appears. When a row is expanded, a card for each backlog item appears, organized by its assigned iteration. +Each team's backlog specified in a delivery plan appears as a row within the plan view. When a row is collapsed, a rollup of the backlog items is displayed. When a row is expanded, cards for each backlog item appear, organized by their assigned iteration. -:::image type="content" source="media/plans/overview-with-callouts.png " border="false" alt-text="Screenshot with callouts of delivery plans and collapsed teams."::: +:::image type="content" source="media/plans/overview-with-callouts.png" border="false" alt-text="Screenshot of callouts of delivery plans and collapsed teams."::: -> [!TIP] -> Work items appear in the [prioritized order](../backlogs/create-your-backlog.md#reorder-your-backlog) listed for the sprint backlog, which inherits the priority from the product backlog. +> [!TIP] +> Work items appear in the [prioritized order](../backlogs/create-your-backlog.md#reorder-your-backlog) listed for the sprint backlog, inheriting the priority from the product backlog. -You can interact with the plan in the following ways: +Use your plan in the following ways: -- Filter the plan by selecting **Filter** :::image type="icon" source="../../media/icons/filter-icon.png" border="false":::. You can filter on any field that you include in the plan. Settings are based on the keyword or text filter. For more information, see [Interactively filter your backlogs, boards, and plans](../backlogs/filter-backlogs-boards-plans.md). -- Scale the size of the cards and calendar by selecting **Zoom out** :::image type="icon" source="media/plans/collapse-calendar-icon.png" border="false"::: or **Zoom in** :::image type="icon" source="media/plans/expand-calendar-icon.png" border="false":::. -- To view previous or future months, select **Scroll calendar left** :::image type="icon" source="media/plans/scroll-calendar-left-icon.png" border="false"::: or **Scroll calendar right** :::image type="icon" source="media/plans/scroll-calendar-right-icon.png" border="false":::. You can also scroll through the plan by selecting the plan and dragging your mouse horizontally. -- To view details for a team, expand the team row by selecting **Expand team row** or by clicking once on a sprint within a team row. -- To expand and collapse all team rows, select **Expand all team rows** or **Collapse all team rows** next to **Teams**. +- Filter the plan: Select **Filter** :::image type="icon" source="../../media/icons/filter-icon.png" border="false":::. You can filter on any field that you include in the plan. Settings are based on the keyword or text filter. For more information, see [Interactively filter your backlogs, boards, and plans](../backlogs/filter-backlogs-boards-plans.md). +- Scale the size of the cards and calendar: Select **Zoom out** :::image type="icon" source="media/plans/collapse-calendar-icon.png" border="false"::: or **Zoom in** :::image type="icon" source="media/plans/expand-calendar-icon.png" border="false":::. +- View previous or future months: Select **Scroll calendar left** :::image type="icon" source="media/plans/scroll-calendar-left-icon.png" border="false"::: or **Scroll calendar right** :::image type="icon" source="media/plans/scroll-calendar-right-icon.png" border="false":::. You can also scroll through the plan by selecting the plan and dragging your mouse horizontally. +- View details for a team: Select **Expand team row**. +- Expand and collapse all team rows: Select **Expand all team rows** or **Collapse all team rows** next to **Teams**. - Scroll the view vertically to view teams that appear lower within the plan view. -- To view titles only, select **Collapsed card fields** :::image type="icon" source="media/plans/collapsed-card-fields-icon.png" border="false":::. To view all fields, select **Expand card fields** :::image type="icon" source="media/plans/expand-card-fields-icon.png" border="false":::. +- View titles only: Select **Collapsed card fields** :::image type="icon" source="media/plans/collapsed-card-fields-icon.png" border="false":::. To view all fields, select **Expand card fields** :::image type="icon" source="media/plans/expand-card-fields-icon.png" border="false":::. - Select a card title to open the backlog item and view details. Close the work item to return to the plan. -- To add a work item to a sprint, select **Add item** :::image type="icon" source="media/plans/add-item-icon.png" border="false"::: within the sprint and team that you want to add it to. -- To [change the fields displayed on the cards](add-edit-delivery-plan.md#fields), select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false":::. +- Add a work item to a sprint: Select **Add item** :::image type="icon" source="media/plans/add-item-icon.png" border="false"::: within the sprint and team that you want to add it to. +- [Change the fields displayed on the cards](add-edit-delivery-plan.md#fields): Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false":::. ## Collapse teams for summary information -A benefit of Delivery Plans is the ability to view multiple teams across the projects that you care about. There are two main ways to view more teams within the plan view: +One of the benefits of Delivery Plans is the ability to view multiple teams across the projects you care about. Here are two main ways to view more teams within the plan view: -* Collapse all teams to focus on summary data. -* Minimize the number of fields displayed on cards. +- **Collapse all teams** to focus on summary data. +- **Minimize the number of fields** displayed on cards. -To gain a summary view of work that's scheduled, collapse all teams. You can then more easily look for gaps in the forecast. +To gain a summary view of scheduled work, collapse all teams. This makes it easier to identify gaps in the forecast. Expand or collapse each team row by selecting **Expand team row** or **Collapse team row** next to the team name. -> [!div class="mx-imgBorder"] -> ![Screenshot that shows the collapsing of click targets.](media/plans/overview.png) +:::image type="content" source="media/plans/overview.png" alt-text="Screenshot that shows the collapsing of select targets."::: ## Show work that spans one or more iterations -For work items that span one or more iterations, define **Start Date** and **Target Date**. The plan displays cards that start and end according to the dates that you set, as shown in the following image. You can also grab the left or right border of a work item and drag it to a new start date or target date. +For work items that span one or more iterations, set the **Start Date** and **Target Date**. The plan will display cards that start and end according to these dates, as shown in the following image. You can also adjust the start or target date by dragging the left or right border of a work item. -> [!div class="mx-imgBorder"] -> ![Screenshot that shows features that span iterations.](media/plans/features-span-iterations-preview.png) +:::image type="content" source="media/plans/features-span-iterations-preview.png" alt-text="Screenshot that shows features that span iterations."::: ## View titles only in the collapsed card view -The collapsed card view allows you to quickly switch back and forth between cards that show titles only and cards that show all fields configured for the plan. To view titles only, select **Collapsed card fields** :::image type="icon" source="media/plans/collapsed-card-fields-icon.png" border="false":::. To view all fields, select **Expand card fields** :::image type="icon" source="media/plans/expand-card-fields-icon.png" border="false":::. +The collapsed card view lets you easily toggle between cards that show only titles and cards that display all fields configured for the plan. To view titles only, select **Collapsed card fields** :::image type="icon" source="media/plans/collapsed-card-fields-icon.png" border="false":::. To view all fields, select **Expand card fields** :::image type="icon" source="media/plans/expand-card-fields-icon.png" border="false":::. -> [!div class="mx-imgBorder"] -> ![Screenshot that shows the location of feature icons for collapsing and expanding card fields.](media/plans/collapse-card-fields.png) +:::image type="content" source="media/plans/collapse-card-fields.png" alt-text="Screenshot that shows the location of feature icons for collapsing and expanding card fields."::: ## View the rollup of features and epics -A rollup displays a fuller picture of the underlying work directly on the cards in your delivery plan. Rollup views are available for features, epics, or any portfolio backlog you've added to your project. To enable rollups, open your plan settings, select **Fields**, and then select **Show child rollup data**. +A rollup provides a comprehensive view of the underlying work directly on the cards in your delivery plan. Rollup views are available for features, epics, or any portfolio backlog you have added to your project. To enable rollups, open your plan settings, select **Fields**, and then choose **Show child rollup data**. -For example, here's a plan view of four scenarios with a rollup of the child features, user stories, and bugs for a single team. +For example, the following plan view shows four scenarios with a rollup of the child features, user stories, and bugs for a single team. -> [!div class="mx-imgBorder"] -> ![Screenshot that shows a rollup view of four scenarios.](media/plans/rollup-view.png) +:::image type="content" source="media/plans/rollup-view.png" alt-text="Screenshot that shows a rollup view of four scenarios."::: You can also view rollups from a backlog view, as described in [Display rollup progress or totals](../backlogs/display-rollup.md). ## Update the iteration for a backlog item -As changes occur to the schedule, you can update the iteration for a backlog item. Move a card to a different iteration. This change helps drive alignment across your organization. +As the schedule changes, update the iteration for a backlog item by moving the card to a different iteration. This adjustment helps maintain alignment across your organization. -> [!div class="mx-imgBorder"] -> ![Screenshot that shows moving a card to a different iteration.](media/plans/move-card-iteration.png) +:::image type="content" source="media/plans/move-card-iteration.png" alt-text="Screenshot that shows moving a card to a different iteration."::: ## Print a delivery plan -You can print all or a portion of your delivery plan, depending on the view that you want to capture and share. You can print only one page at a time by using your browser's **Print** feature. +You can print all or part of your delivery plan, depending on the view you want to capture and share. Use your browser's **Print** feature to print one page at a time. + +Here are some tips for printing portions of a plan: -Here are some tips for printing portions of a plan: +- Select **Full screen mode** :::image type="icon" source="../../media/icons/full-screen-mode.png" border="false":::. +- Expand or collapse teams and zoom in or out to get the desired view. +- Take a screenshot of the plan view or use your browser's **Print** function. -- Select **Full screen mode** :::image type="icon" source="../../media/icons/full-screen-mode.png" border="false":::. -- Expand or collapse one or more teams and zoom in or out to get the view that you want. -- Take a screenshot of the plan view, or select the **Print** function of your browser. +> [!TIP] +> To share a delivery plan with a team member, copy the URL and send the copied URL to your team member via email, chat, or any other communication tool your team uses. ## Related articles - [Add or edit a delivery plan](add-edit-delivery-plan.md) -- [Track dependencies by using Delivery Plans](track-dependencies.md) -- [Interactively filter your backlogs, boards, and plans](../backlogs/filter-backlogs-boards-plans.md) -- [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md) -- [Add teams](../../organizations/settings/add-teams.md) -- [Portfolio management](portfolio-management.md) -- [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) - +- [Track dependencies using Delivery Plans](track-dependencies.md) +- [Filter backlogs, boards, and plans interactively](../backlogs/filter-backlogs-boards-plans.md) +- [Understand backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md) +- [Add teams](../../organizations/settings/add-teams.md) +- [Manage portfolio](portfolio-management.md) +- [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) diff --git a/docs/boards/plans/safe-concepts.md b/docs/boards/plans/safe-concepts.md index ba00ffef667..ae95e8ae62f 100644 --- a/docs/boards/plans/safe-concepts.md +++ b/docs/boards/plans/safe-concepts.md @@ -5,7 +5,7 @@ description: Learn how Scaled Agile Framework concepts map to Azure Boards artif ms.service: azure-devops-boards ms.author: chcomley author: chcomley -ms.topic: tutorial +ms.topic: conceptual monikerRange: '<= azure-devops' ms.date: 10/20/2021 --- @@ -42,7 +42,7 @@ The following image illustrates how you can configure Azure Boards to support a Examples provided below illustrate how a three-level team hierarchy is configured using hierarchical area paths. The examples build from the [Agile process](../work-items/guidance/agile-process.md), However, you can apply these changes to any project hosted on Azure Boards. - + ## Agile feature, program, and portfolio teams @@ -55,7 +55,7 @@ To support SAFe® teams, you reconfigure the default team as the Portfolio team - + ## Stories, Features, Epics, Enablers, and Capabilities @@ -78,7 +78,7 @@ Work items provide support for the following tasks: Product and portfolio backlogs enable teams to quickly add and prioritize their User Stories, Features, and Epics. For more information about work items and work item types, see [Track work with user stories, issues, bugs, features, and epics](../work-items/about-work-items.md). - + ## Team backlogs and boards @@ -88,13 +88,9 @@ SAFe® backlogs map to team, program, and portfolio backlogs. Out of the box, th You can customize your backlog and boards, even adding portfolio backlogs, as described in [Customize Azure Boards, Customize backlogs](safe-customize.md#custom-backlog). -The Kanban board view of each backlog is configurable by each team. +The board view of each backlog is configurable by each team. - - - - - + ## Program Increments, releases, and sprints @@ -107,7 +103,7 @@ Because epics can span several release trains, the Portfolio team isn't associat ![Teams track deliverables using iterations](media/safe/program-iterations.png) - + ## Iteration goals and objectives @@ -116,7 +112,7 @@ SAFe® practices include Agile release teams defining their iteration goals and For more information, see [Share information](#share-information) later in this article. - + ## Value streams and budgets @@ -126,7 +122,7 @@ You can use tags for a quick and easy way to map Features and Epics to their Val With tags that you add to work items, you can: -- Filter any backlog or Kanban board +- Filter any backlog or board - Create queries based on tags, and filter query results by tags - Create progress and trend charts or reports based on tags @@ -141,7 +137,7 @@ With rollup, you can get Budget Estimates for Epics from a rollup of the estimat To add custom fields, see [Customize Azure Boards, Add a custom field](safe-customize.md#add-custom-field). - + ## Use the project wiki to support your portfolio vision and strategic themes @@ -156,10 +152,10 @@ Use your project wiki to support sharing the following SAFe® artifacts: - Objectives - Customer-centric practices -To learn more about the project wiki, see [Share information](#share-information) later in this article. +For more information about the project wiki, see [Share information](#share-information) later in this article. - + ## Milestones and key events @@ -174,7 +170,7 @@ In Azure Boards, you can track other types of milestones or key events in the fo With custom fields and tags, you can quickly filter backlogs, boards, and queries based on a specific milestone. - + ## Shared services team structure @@ -186,7 +182,7 @@ Here we show how area paths are assigned to the UX Design team, and then selecti > ![Shared services area path and team structure](media/safe/shared-services-team-structure.png) - + ## Retrospectives and reviews @@ -201,7 +197,7 @@ This extension allows teams to create their own retrospective boards and capture - Organize and prioritize that feedback - Create and track actionable tasks to help each team in their improvement processes. - + ## Share information @@ -212,7 +208,7 @@ Azure Boards provides many ways to share information. - The Project wiki provides a central repository with versioning control built-in to share information with all project members. Other wikis can be created as needed. For more information, see [About Wikis, READMEs, and Markdown](../../project/wiki/about-readme-wiki.md). For details on supported Markdown features, see the following articles. -- [Syntax guidance for Markdown usage in Wiki](../../project/wiki/wiki-markdown-guidance.md) +- [Syntax guidance for Markdown usage in Wiki](../../project/wiki/markdown-guidance.md) - [Syntax guidance for basic Markdown usage](../../project/wiki/markdown-guidance.md) ## Next steps @@ -220,7 +216,7 @@ For details on supported Markdown features, see the following articles. > [!div class="nextstepaction"] > [Configure Azure Boards to support SAFe®](safe-configure-boards.md) - + ## Related articles @@ -240,36 +236,12 @@ For details on supported Markdown features, see the following articles. diff --git a/docs/boards/plans/safe-configure-boards.md b/docs/boards/plans/safe-configure-boards.md index 95102ba4a4c..bebfd0f5013 100644 --- a/docs/boards/plans/safe-configure-boards.md +++ b/docs/boards/plans/safe-configure-boards.md @@ -32,9 +32,12 @@ Once you've completed these core configurations, you can then consider customizi If you're new to Azure Boards, we recommend that you review [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md) and [About area and iteration (sprint) paths](../../organizations/settings/about-areas-iterations.md) before adding and configuring your teams. Also, two excellent articles to review around team structure and Agile culture are [Introduction to planning efficient workloads with DevOps](/devops/plan/planning-efficient-workloads-with-devops) and [Building productive, customer focused teams](/devops/plan/building-productive-teams). - [!INCLUDE [temp](../includes/note-safe-articles.md)] +## Prerequisites + +[!INCLUDE [prerequisites-project-admin](../includes/prerequisites-project-admin.md)] + ## Understand team hierarchy In this article, we'll go from having one project and one team, both named "Fabrikam", to the following set of nine teams. @@ -45,7 +48,6 @@ In this article, we'll go from having one project and one team, both named "Fabr > [!NOTE] > Azure Boards doesn't support a hierarchy of teams. However, by configuring the Area Paths as indicated in this article, you effectively create a type of team hierarchy. The hierarchy is defined through the structure of Area Paths. - We'll then configure the area path to the following hierarchy and configuring each team's area path. This configuration supports each team's backlog view and rollup of views within the hierarchy. > [!div class="mx-imgBorder"] @@ -54,22 +56,19 @@ We'll then configure the area path to the following hierarchy and configuring ea > [!TIP] > If you have a large number of teams, area paths, and iterations that you need to add, you may want to use command line or programmatic tools. See the [Command line and programmatic tools](#command-line-and-programmatic-tools) provided later in this article. -All teams can manage their own workload and priorities while clearly understanding how their work supports those epics managed in the portfolio team's backlog. At the same time, the portfolio team can monitor progress of its backlog on their own Kanban board, prioritize the items on their backlog, and view progress across release trains. +All teams can manage their own workload and priorities while clearly understanding how their work supports those epics managed in the portfolio team's backlog. At the same time, the portfolio team can monitor progress of its backlog on their own board, prioritize the items on their backlog, and view progress across release trains. While the above may sound complicated, it actually takes little configuration to set up the teams and get started. To go from one project with one default team, first define each team while automatically creating a default area path for that team. Then reconfigure the flat set of area paths to a hierarchical structure. Next, define the iteration paths to support the release structure you want and the program and Agile teams to use. Lastly, configure each team and populate the membership of teams. - - + ## Define your teams To start, we'll add each team, creating a default area path for each. Later in this article, we'll configure those area paths into the necessary hierarchy. This structure maps the following SAFe® teams to Azure Boards teams: - Portfolio team -> default top-level team, the Fabrikam team (already defined) - Program teams -> secondary-level teams, Fiber Suite, and Service Suite -- Agile teams -> tertiary-level teams defined under Fiber Suite and Service Suite. - -You'll need to be a [project administrator](../../organizations/security/add-users-team-project.md) to complete these steps. If you need more-detailed guidance, see [Portfolio management](portfolio-management.md). +- Agile teams -> tertiary-level teams defined under Fiber Suite and Service Suite. Add each team, one by one. @@ -99,13 +98,12 @@ Add each team, one by one. 1. Optional. If you have two or more Portfolio teams, create a team for each of them. - + ## Configure Area Paths To support your team hierarchy, you'll now configure the area paths created in the first step of defining teams into a hierarchy. - 1. From the **Project Settings** page, choose **Project configuration** and then **Areas**. You should see a flat list of Area Paths. > [!div class="mx-imgBorder"] @@ -132,7 +130,6 @@ To support your team hierarchy, you'll now configure the area paths created in t > [!div class="mx-imgBorder"] > ![Hierarchical area path](media/safe-configure/team-area-path-mapping.png) - ## Define Iteration Paths To track progress towards Releases, create your iteration path structure. Unlike area paths, multiple teams can share the same iteration path structure. Sharing the iteration structure lets multiple teams work in the same sprint cadence towards the same release trains. @@ -164,7 +161,7 @@ If you already have iterations for your default team, you can rename them. You'l > [!TIP] > You can drag and drop Iteration Paths to structure your iterations, similar to as shown in Step 2 under Configure Area Paths. Azure Boards always lists the iteration paths in order of their dates under each parent node. - + ## Configure your teams @@ -281,11 +278,9 @@ The following table lists the recommended settings to make based on the team lev *** - > [!NOTE] > By setting the Default Iteration to **\@CurrentIteration**, all work items created from the team's backlog or board are assigned to the current iteration based on the current date. By setting the Backlog Iteration to the root, **Fabrikam**, indicates that only the Area Path acts as a filter for work items to appear on the team backlogs and boards. - 1. From the **Project Settings** page, choose **Team configuration**. Choose the team you want to configure from the Team selector. @@ -344,7 +339,6 @@ The following table lists the recommended settings to make based on the team lev > [!div class="mx-imgBorder"] > ![Project configuration, Areas](media/safe-configure/area-path-structure-corrected.png) - ## Configure teams to support Shared Services For teams that support several other teams, such as a UX Design team, configure your teams as described in the following steps. @@ -376,9 +370,8 @@ For teams that support several other teams, such as a UX Design team, configure Work items that appear on shared area paths appear on the backlogs and boards of the associated teams. - - - + + ::: moniker range=">= azure-devops-2020" @@ -392,13 +385,7 @@ You can use Azure DevOps command-line tools to add or update the following artif ::: moniker-end -::: moniker range="azure-devops-2019" - -## Use programmatic tools - -::: moniker-end - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" You can use Azure DevOps REST APIs to add or update the following artifacts: @@ -413,7 +400,6 @@ You can use Azure DevOps REST APIs to add or update the following artifacts: > [!div class="nextstepaction"] > [Customize Azure Boards to support SAFe®](safe-customize.md) - ## Related articles - [Add teams](../../organizations/settings/add-teams.md) @@ -425,4 +411,3 @@ You can use Azure DevOps REST APIs to add or update the following artifacts: - diff --git a/docs/boards/plans/safe-customize.md b/docs/boards/plans/safe-customize.md index d2b04622698..ab894b7d337 100644 --- a/docs/boards/plans/safe-customize.md +++ b/docs/boards/plans/safe-customize.md @@ -11,7 +11,6 @@ monikerRange: '<= azure-devops' ms.date: 03/01/2023 --- - # Customize Azure Boards to support SAFe® practices [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -28,16 +27,19 @@ Learn how Azure Boards supports SAFe® practices through the following operation > - Add custom controls or custom extensions > - Customize your backlogs or add a custom portfolio backlog - [!INCLUDE [temp](../includes/note-safe-articles.md)] +## Prerequisites + +[!INCLUDE [prerequisites-project-admin](../includes/prerequisites-project-admin.md)] + ## About customization and the inherited process Azure Boards provides a graphical user interface to support customization of your projects. This feature is called the Inherited process. All projects that use an inherited process are automatically updated when customizations are made to that process. For an overview of all the customizations you can make to an inherited process, see [About process customization and inherited processes](../../organizations/settings/work/inheritance-process-model.md). - + ## Customize work item types @@ -46,19 +48,17 @@ Each work item type defines the fields that capture and store information. You c - [Add a custom field](#add-custom-field) to support tracking budget costs, value streams, or customer-centric information - [Customize existing fields](#customize-fields), such as modifying the picklist or changing a field label - [Add custom rules](#custom-rules) to make select fields required or specify actions to take under select conditions -- [Change the workflow](#custom-workflow) to reflect your team's Kanban workflow process +- [Change the workflow](#custom-workflow) to reflect your team's workflow process - [Add a custom control or extension](#custom-control) to support custom functions such as a calculated field - For more information on customizing a work item type, see [Add and manage work item types](../../organizations/settings/work/customize-process-work-item-type.md). - + ## Add a custom field You can add a custom field to support tracking data requirements that aren't met with the existing set of fields. Some fields to consider adding to one or more work item types include those items listed in the following table. - :::row::: :::column span=""::: **Field name** @@ -128,7 +128,7 @@ You can capture a value stream using a field or tags. Tags represent a more info - + ## Customize existing fields @@ -143,7 +143,7 @@ You customize existing fields to support one or more of the following actions: For an index of existing fields, see [Work item field index](../work-items/guidance/work-item-field.md). For more information on customizing a field, see [Add and manage fields for an inherited process](../../organizations/settings/work/customize-process-field.md). - + ## Add rules to a field @@ -169,36 +169,27 @@ The following images show the supported conditions and actions you can select fr ::: moniker-end -::: moniker range="azure-devops-2019" - -> [!div class="mx-tdBreakAll"] -> |Supported conditions |Supported actions | -> |-------------|----------| -> |![Screenshot showing list of conditions, 2019](../../organizations/settings/work/media/rules/when-condition-1.png) | ![Screenshot showing list of actions, 2019](../../organizations/settings/work/media/rules/rule-actions-2019.png) - -::: moniker-end - For more information on setting field rules, see [Add a rule to a work item type (Inheritance process)](../../organizations/settings/work/custom-rules.md). - + ## Customize the workflow -You may want to customize the workflow for User Stories, Features, and Epics so that it matches your workflow process. By customizing the workflow early, you minimize the Kanban board configuration teams must do. +You may want to customize the workflow for User Stories, Features, and Epics so that it matches your workflow process. By customizing the workflow early, you minimize the board configuration teams must do. -The default workflow for the Agile process includes *New*, *Active*, *Resolved*, and *Closed* states. While each team can add workflow columns to their Kanban board, you might want to customize the workflow to track these columns instead. That way the Kanban boards for all teams are set up to use the same workflow states. +The default workflow for the Agile process includes *New*, *Active*, *Resolved*, and *Closed* states. While each team can add workflow columns to their board, you might want to customize the workflow to track these columns instead. That way the boards for all teams are set up to use the same workflow states. -For example, you can add and rename workflow States to match the Kanban columns shown in the following image—*Backlog*, *Analyze*, *Develop*, *Test*, and *Done*. +For example, you can add and rename workflow States to match the columns shown in the following image—*Backlog*, *Analyze*, *Develop*, *Test*, and *Done*. > [!div class="mx-imgBorder"] -> ![Conceptual image of Kanban board columns to visualize flow and limit WIP.](../boards/media/alm_kb_board2.png) +> ![Conceptual image of board columns to visualize flow and limit WIP.](../boards/media/alm_kb_board2.png) Discuss with your team which workflow states best support their Agile practices. For more information, see the following articles: - [Customize the workflow (Inheritance process)](../../organizations/settings/work/customize-process-workflow.md) -- [Add columns to your Kanban board](../boards/add-columns.md) +- [Add columns to your board](../boards/add-columns.md) - [Definition of Done](../boards/add-columns.md#definition-of-done) - + ## Custom controls @@ -208,7 +199,7 @@ You can add controls from the Marketplace or create your own. [WorkBoard OKRs](https://marketplace.visualstudio.com/items?itemName=wobo-okrs.workboard-ado-extension) integration helps organizations align, localize, and measure Objectives and Key Results (OKRs) across the business. With this integration, teams can view and update their OKRs from within Azure DevOps. - + ## Add custom work item types @@ -221,8 +212,8 @@ When you define a new work item type, think through the following items: To keep things simple, however, it's always best to minimize the amount of customizations you make. So, if you can get by with existing work item types, you might consider adding custom field(s) as needed to track specific information. - - + + ## Customize your backlogs @@ -263,7 +254,7 @@ You add the following Marketplace extensions to get access to many rich features ## Related articles -- [Grant or restrict access](../../organizations/security/restrict-access.md) +- [Manage access](../../organizations/security/restrict-access.md) - [Develop a web extension for Azure DevOps Services](../../extend/get-started/node.md) - [About projects and scaling your organization](../../organizations/projects/about-projects.md) - [Plan your organizational structure](../../user-guide/plan-your-azure-devops-org-structure.md) diff --git a/docs/boards/plans/safe-plan-track-boards.md b/docs/boards/plans/safe-plan-track-boards.md index fcbc7480401..f86785c86dc 100644 --- a/docs/boards/plans/safe-plan-track-boards.md +++ b/docs/boards/plans/safe-plan-track-boards.md @@ -15,21 +15,15 @@ ms.date: 10/20/2021 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Once you've configured your Agile tools to support SAFe®, trace relationships can be created from Stories all the way up to Epics. Additionally, you can view progress from the portfolio, program, and feature team levels. +Once you configure your Agile tools to support SAFe®, you can establish trace relationships from Stories all the way up to Epics, ensuring comprehensive visibility and alignment across your initiatives. Additionally, you can monitor progress at the portfolio, program, and feature team levels, enabling more informed decision-making and strategic planning. -This article walks you through some of the basic tools you'll use to plan and track your SAFe® programs and portfolios. Specifically, you'll learn how to quickly complete these tasks: +This article guides you through the essential tools and techniques for planning and tracking your SAFe® programs and portfolios, helping you effectively manage and scale your Agile practices. ->[!div class="checklist"] -> - Define epics, features, and stories -> - Group or map stories to features, and features to epics -> - Assign value streams -> - Plan a sprint -> - Review feature team progress -> - Review program features -> - Review portfolio epics +[!INCLUDE [temp](../includes/note-safe-articles.md)] +## Prerequisites -[!INCLUDE [temp](../includes/note-safe-articles.md)] +[!INCLUDE [prerequisites-project-admin](../includes/prerequisites-project-admin.md)] ## Define portfolios and epics @@ -48,7 +42,7 @@ You can import work items using Excel. As shown in the following image, Epics, F Once you publish the list, work item IDs are assigned. Each team can then start working with their work items, adding details, and assigning work to team members and to sprints. -To learn more about bulk update, see the [Bulk add or update work items](#bulk-update) section provided later in this article. +For more information about bulk update, see the [Bulk add or update work items](#bulk-update) section provided later in this article. ### Document Portfolio Vision and Strategic Themes @@ -61,7 +55,7 @@ We recommend you use the project wiki to capture and share the Portfolio Vision, - Customer-centric programs Information can be easily shared and updated by any member of the team. -To learn more about using the project wiki, see [About Wikis, READMEs, and Markdown](../../project/wiki/about-readme-wiki.md) +For more information about using the project wiki, see [About Wikis, READMEs, and Markdown](../../project/wiki/about-readme-wiki.md) ### Define and prioritize the Epics portfolio backlog @@ -204,15 +198,15 @@ Just as you earlier mapped each Feature to its parent Epic, now you'll map each > ![Stories backlog, with Parents enabled](media/safe-plan-track/stories-parented-list.png) -## View Kanban boards and update status +## View boards and update status -Each team's Kanban board provides a visual interactive space for the team to plan and update status. With it, your team can track the critical information they need by seeing which work items are in progress, where the bottlenecks are, who work is assigned to, and more. +Each team's board provides a visual interactive space for the team to plan and update status. With it, your team can track the critical information they need by seeing which work items are in progress, where the bottlenecks are, who work is assigned to, and more. -For an overview of Kanban board tools and usage, see [About Boards and Kanban](../boards/kanban-overview.md). Each team can customize the boards columns, card fields, card styles, and more. For more information, see [Customize your boards](../configure-customize.md). +For an overview of board tools and usage, see [About Boards and Kanban](../boards/kanban-overview.md). Each team can customize the boards columns, card fields, card styles, and more. For more information, see [Customize your boards](../configure-customize.md). -### Open a Kanban board +### Open a board -You open the Kanban board from any backlog by choosing the **View as Board** link. +You open the board from any backlog by choosing the **View as Board** link. > [!div class="mx-imgBorder"] > ![Epic board](media/safe-plan-track/view-epics-kanban.png) @@ -226,28 +220,28 @@ Each board supports the following tasks: - Assign values or update fields displayed on cards - Filter based on keywords and key fields - + -### Portfolio Kanban board +### Portfolio board Child items of Epics are listed within each card. You can expand and collapse the list of child items. > [!div class="mx-imgBorder"] -> ![Epics Kanban board](media/safe-plan-track/epics-kanban-board.png) +> ![Epics board](media/safe-plan-track/epics-kanban-board.png) - + -### Program team Kanban board +### Program team board > [!div class="mx-imgBorder"] -> ![Fiber Suite Kanban board](media/safe-plan-track/features-kanban-board.png) +> ![Fiber Suite board](media/safe-plan-track/features-kanban-board.png) - + -### Agile team Kanban board +### Agile team board > [!div class="mx-imgBorder"] -> ![Feature team Kanban board](media/safe-plan-track/user-story-kanban-board.png) +> ![Feature team board](media/safe-plan-track/user-story-kanban-board.png) ## Plan a sprint @@ -259,7 +253,7 @@ As shown in the following image, the App team plans their sprints. > [!div class="mx-imgBorder"] > ![App team, Backlogs, Sprint planning](media/safe-plan-track/plan-sprint.png) -To learn more about planning and conducting sprints, see the tutorials for [Plan and work a sprint](../sprints/assign-work-sprint.md). +For more information about planning and conducting sprints, see the tutorials for [Plan and work a sprint](../sprints/assign-work-sprint.md). ## Plan a release train @@ -272,17 +266,17 @@ Here we show the Fiber Suite program team plan the releases for their features. - + ## Tips for working with work items When creating and updating work items, understand what you can and can't do. - You can only assign a work item to one team member; if you need to assign similar work to more than one user, copy the work item and make the assignment - Can only assign a work item to a single Area Path and Iteration Path -- The quickest way to add backlog work items is from the backlog or Kanban board +- The quickest way to add backlog work items is from the backlog or board - You can use [work item templates](../backlogs/work-item-template.md) to quickly fill in work item fields - + ## Bulk add or update work items diff --git a/docs/boards/plans/safe-review-roadmaps-progress.md b/docs/boards/plans/safe-review-roadmaps-progress.md index 988efeb5345..98ff9a3e529 100644 --- a/docs/boards/plans/safe-review-roadmaps-progress.md +++ b/docs/boards/plans/safe-review-roadmaps-progress.md @@ -15,47 +15,43 @@ ms.date: 10/20/2021 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -With team's configured and working backlogs and boards, you're ready to start viewing and monitoring progress. +With your teams' backlogs and boards properly configured and operational, you're now ready to begin viewing and monitoring progress effectively. -Azure Boards provides many in-context charts and dashboard widgets that allow you to monitor and report on various SAFe® metrics. Specifically Azure Boards provides access to the following tools to support teams in deriving SAFe® metrics and monitoring and reporting progress. +Azure Boards offers various in-context charts and dashboard widgets that enable you to track and report on key SAFe® metrics. Specifically, Azure Boards provides access to the following tools to help teams derive SAFe® metrics and monitor and report progress: -- Roll up columns on backlogs -- In-context reports -- Managed query charts such as pie, bar, stacked bar, trend, and pivot -- Dashboard widgets -- Team and project dashboards -- Analytic Views to support Power BI reports -- OData queries to use with Power BI reports +- **Roll-up columns on backlogs:** Aggregate and visualize work items across multiple backlogs. +- **In-context reports:** Access detailed reports directly within your work items. +- **Managed query charts:** Utilize various chart types such as pie, bar, stacked bar, trend, and pivot to analyze data. +- **Dashboard widgets:** Customize your dashboards with widgets that display pertinent metrics and information. +- **Team and project dashboards:** Create comprehensive dashboards tailored to specific teams and projects. +- **Analytic views for Power BI reports:** Use Analytic Views to integrate Azure Boards data with Power BI for advanced reporting. +- **OData queries for Power BI reports:** Use OData queries to fetch data for Power BI, enabling rich data visualization and analysis. -For an overview of these tools, see [About dashboards, charts, reports, & widgets](../../report/dashboards/overview.md). Another backlog tool is Forecast which teams can use in their iteration planning. +For an overview of these tools, see [About dashboards, charts, reports, & widgets](../../report/dashboards/overview.md). Another essential backlog tool is **Forecast**, which teams can utilize during their iteration planning sessions. -In this tutorial, we illustrate some of the out-of-the-box charts and widgets that you'll have instant access to monitor some of these key SAFe® metrics +## View progress rollup ->[!div class="checklist"] -> - Progress reports -> - Cumulative Flow Diagram -> - Lead time and cycle time charts -> - Iteration planning, team velocity, and forecast +With your teams' backlogs and boards properly configured and operational, you can now effectively view and monitor progress through rollup columns in each team's backlog. The following example illustrates progress based on the completion of child work items. -[!INCLUDE [temp](../includes/note-safe-articles.md)] - - -## View progress rollup +> [!div class="mx-imgBorder"] +> ![Screenshot shows rollup progress bars.](../backlogs/media/rollup/progress-by-work-items.png) -Quick progress views are available from each team's backlog through rollup columns. Here's an example that shows progress based on completion of child work items. +In addition to tracking completion of child work items, other rollup options include: -> [!div class="mx-imgBorder"] -> ![Rollup progress bars](../backlogs/media/rollup/progress-by-work-items.png) +- **Progress by specific work item types:** Monitor progress based on different categories of work items. +- **Progress by story points:** Track the total story points completed versus planned. +- **Count of work items:** Keep a tally of work items completed within a specific timeframe. +- **Sum of a numeric field:** Aggregate numerical data related to work items for comprehensive analysis. -Other rollup options include progress by specific work item types, progress by story points, count of work items, or sum of a numeric field. For more information, see [Display rollup progress or totals](../backlogs/display-rollup.md). +For more detailed information on configuring and displaying rollup progress or totals, refer to [Display Rollup Progress or Totals](../backlogs/display-rollup.md). ## View team velocity -Each team has access to their velocity through the in-context velocity report. These reports show a bar chart count of planned, completed, completed late, and incomplete work items for the last six or more iterations. As shown in the example below, the chart also provides the average velocity calculated for the number of iterations shown. +Each team has access to their velocity through the in-context velocity report. These reports show a bar chart count of planned, completed, completed late, and incomplete work items for the last six or more iterations. As shown in the following example, the chart also provides the average velocity calculated for the number of iterations shown. > [!div class="mx-imgBorder"] -> ![Velocity](media/safe/velocity-story-points.png) +> ![Screenshot shows velocity story points.](media/safe/velocity-story-points.png) This average can be used to forecast work by plugging it into the forecast tool. @@ -64,18 +60,18 @@ This average can be used to forecast work by plugging it into the forecast tool. By assigning Story Points to each User Story, a team can determine how much work they can complete using the Forecast tool. For details on its usage, see [Forecast your product backlog](../sprints/forecast.md). > [!div class="mx-imgBorder"] -> ![Forecast tool](../sprints/media/forecast-s125.png) +> ![Screenshot shows Forecast tool.](../sprints/media/forecast-s125.png) ## View the Cumulative Flow Diagram (CFD) Each Azure Boards backlog and board provide configurable CFD views. So each team at every level of SAFe® implementation can monitor progress using these built-in charts. -The following image shows an example CFD chart for User Stories with all Kanban columns displayed. +The following image shows an example CFD chart for User Stories with all columns displayed. > [!div class="mx-imgBorder"] -> ![CFD chart](../../report/dashboards/media/cfd/analytics-cfd-azure-devops.png) +> ![Screenshot shows CFD chart.](../../report/dashboards/media/cfd/analytics-cfd-azure-devops.png) -Teams can use their CFD to identify bottlenecks and monitor the batch size of work in their various Kanban states. +Teams can use their CFD to identify bottlenecks and monitor the batch size of work in their various states. In-context CFD charts are quickly accessible from each backlog and board view. Also, CFD charts can be added to team and project dashboards. For more information, see [View/configure a Cumulative Flow Diagram](../../report/dashboards/cumulative-flow.md). @@ -84,8 +80,8 @@ In-context CFD charts are quickly accessible from each backlog and board view. A Other metrics that teams use are derived from the Lead time and cycle time charts. These charts can be added to a team dashboard and monitored to learn the following information: -- Lead time: Days on average to complete deliverables from date created -- Cycle time: Days on average to complete deliverables from date work started +- **Lead time**: Days on average to complete deliverables from date created +- **Cycle time**: Days on average to complete deliverables from date work started - Number of outliers Both Lead Time and Cycle Time widgets display as scatter-plot control charts. They display summary information and provide several interactive elements. For more information, see [Cumulative flow, lead time, and cycle time guidance](../../report/dashboards/cumulative-flow-cycle-lead-time-guidance.md). @@ -100,7 +96,7 @@ Both Lead Time and Cycle Time widgets display as scatter-plot control charts. Th > [!div class="mx-imgBorder"] > ![Example Cycle TIme Widget](../../report/dashboards/media/cycle-time-planning.png) - + ## View and update roadmaps @@ -116,23 +112,21 @@ Program teams can review roadmaps of the deliverables of their Agile Release Tea You can expand each feature team to see details. Story deliverables are assigned to the PI 1 sprints. Delivery Plans are fully interactive, allowing you to drag and drop work items to update their sprint assignments, or open work items to update fields, add comments, and other information. > [!div class="mx-imgBorder"] -> ![Plans, Fiber Suite App team deliverables](media/safe-metrics/plan-fiber-suite-stories-expand-app-team.png) +> ![Screenshot shows Plans, Fiber Suite App team deliverables.](media/safe-metrics/plan-fiber-suite-stories-expand-app-team.png) ### Review the portfolio features deliverable Portfolio teams can review the Features under development by their program teams. For example, Features under development by the Fiber Suite team are shown in the following delivery plan view. The Features under development show up under the Program Increment timeboxes. > [!div class="mx-imgBorder"] -> ![Plans, Portfolio feature deliverables](media/safe-metrics/plan-portfolio-fiber-suite.png) - +> ![Screenshot shows Plans, Portfolio feature deliverables.](media/safe-metrics/plan-portfolio-fiber-suite.png) ### Review feature timeline roadmaps The feature timeline tool provides another view into progress of deliverables. Here we show the Fabrikam Team's Epics as shown in the Feature Timeline tool. Progress bars are configurable based on completed stories or effort. > [!div class="mx-imgBorder"] -> ![Feature Timeline, Portfolio feature deliverables](media/safe-metrics/feature-timeline-fabrikam-team.png) - +> ![Screenshot shows Feature Timeline, Portfolio feature deliverables.](media/safe-metrics/feature-timeline-fabrikam-team.png) \ No newline at end of file diff --git a/docs/boards/plans/track-dependencies.md b/docs/boards/plans/track-dependencies.md index 53df3fde504..babfe3d4399 100644 --- a/docs/boards/plans/track-dependencies.md +++ b/docs/boards/plans/track-dependencies.md @@ -12,7 +12,6 @@ ms.date: 08/03/2022 --- - # Track dependencies by using Delivery Plans [!INCLUDE [version-gt-eq-2022](../../includes/version-gt-eq-2022.md)] @@ -22,31 +21,23 @@ With Delivery Plans, you can track dependencies that have been added to work ite :::image type="content" source="media/dependencies/dependencies-with-without-issues.png" alt-text="Screenshot of delivery plan showing work items with dependencies and dependencies with issues."::: To view dependencies, you must first define the Delivery Plan and dependencies between work items. To learn how, see [Add or edit a Delivery Plans](add-edit-delivery-plan.md) and [Link user stories, issues, bugs, and other work items](../backlogs/add-link.md#link-several-work-items). - > [!TIP] > You can create dependencies between work items in different projects and different teams within the same organization, but not in projects in different organizations. You can open a work item and add a dependency through the links tab. ## Prerequisites -- To view a Delivery Plan, you must be a member of the Project Collection Valid Users group. Users granted **Stakeholder** access for a private project can view plans. Users granted **Stakeholder** access for a public project can add and view plans. -- To open or modify a work item or add work items, you must have the **Edit work items in this node** set to **Allow** for the Area Paths assigned to the work item. - -**For work items and dependency lines to appear on the plan** -- [Team product or portfolio backlog must be enabled](../../organizations/settings/select-backlog-navigation-levels.md) to select it for a plan. -- Work items must belong to a team's [product backlog](../backlogs/create-your-backlog.md) or [portfolio backlog](../backlogs/define-features-epics.md). Only work items belonging to a category selected for viewing on a team's backlog and meet any [field criteria defined for the plan](add-edit-delivery-plan.md#field-criteria) appear on the plan. -- [Sprints must be selected for each team](../../organizations/settings/set-iteration-paths-sprints.md#select-team-sprints-and-set-the-default-iteration-path) defined in the plan. -- [Start and end dates](../../organizations/settings/set-iteration-paths-sprints.md#add-iterations-and-set-iteration-dates) must be defined for each project iteration. -- [**Iteration Paths**](../sprints/assign-work-sprint.md) or [**Start Date/Target Date**](../queries/query-by-date-or-current-iteration.md#date-and-iteration-path-fields) must be assigned to each work item. When defined, **Start Date/Target Date** overrides the sprint assigned to a work item. -- For dependency icons and lines to show, [work items must be linked](../backlogs/add-link.md) using **Predecessor-Successor** link type. -- Team or teams must be expanded to view dependency icons and dependency lines. +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To view a Delivery Plan: Member of the **Project Collection Valid Users** group. Users granted **Stakeholder** access for a private project can view plans. Users granted **Stakeholder** access for a public project can add and view plans.
- To open or modify a work item or add work items: **Edit work items in this node** permission set to **Allow** for the Area Paths assigned to the work item. | +| **Configuration** |- For work items and dependency lines to appear on the plan: [Enable a team product or portfolio backlog](../../organizations/settings/select-backlog-navigation-levels.md) to select it for a plan.
- Work items belong to a team's [product backlog](../backlogs/create-your-backlog.md) or [portfolio backlog](../backlogs/define-features-epics.md). Only work items belonging to a category selected for viewing on a team's backlog and meet any [field criteria defined for the plan](add-edit-delivery-plan.md#field-criteria) appear on the plan.
- [Sprints selected for each team](../../organizations/settings/set-iteration-paths-sprints.md#select-team-sprints-and-set-the-default-iteration-path) defined in the plan.
- [Start and end dates](../../organizations/settings/set-iteration-paths-sprints.md#add-iterations-and-set-iteration-dates) defined for each project iteration.
- [**Iteration Paths**](../sprints/assign-work-sprint.md) or [**Start Date/Target Date**](../queries/query-by-date-or-current-iteration.md#date-and-iteration-path-fields) defined for each work item. When defined, **Start Date/Target Date** overrides the sprint assigned to a work item.
- To show dependency icons and lines: [Work items](../backlogs/add-link.md) linked using **Predecessor-Successor** link type.
- Team expanded to view dependency icons and dependency lines. | > [!TIP] > If you edit a plan and don't see the changes you made appear in the plan, refresh your browser. A browser refresh is needed some times to trigger the updates. ## Show dependency lines for a work item -1. Open the Delivery Plan from **Boards>Delivery Plans**. +1. Open the Delivery Plan from **Boards** > **Delivery Plans**. > [!div class="mx-imgBorder"] > ![Screenshot to Open Boards, Delivery Plans.](media/plans/open-plans.png) @@ -68,8 +59,6 @@ To view dependencies, you must first define the Delivery Plan and dependencies b :::image type="content" source="media/dependencies/dependency-lines-issue-alert.png" alt-text="Screenshot of card showing dependent work items with an issue in predecessor-successor linkage."::: - - ## Open the dependency summary for a work item To drill down into specific dependencies, open the Dependencies dialog for the work item. Choose the icon that indicates the work item has dependencies, either the :::image type="icon" source="media/dependencies/dependency-green-icon.png" border="false"::: green or :::image type="icon" source="media/dependencies/dependency-red-icon.png" border="false"::: red icon. @@ -84,15 +73,14 @@ The Dependencies dialog indicates that the work item has three predecessors and ## Identify dependency issues -When issues exist, they're highlighted in red. The issue always has to do with an end date for a successor work item occurring before the end date of the predecessor work item. Determine the end date by using either the **Target Date** for the work item or the **End Date** of the work item's assigned **Iteration Path**. +When conflicts arise, they are highlighted in red. These issues typically occur when a successor work item's end date is set before the predecessor work item's end date. To determine the end date, use either the **Target Date** for the work item or the **End Date** of the assigned **Iteration Path**. -For example, the following Dependencies dialog indicates that two predecessor work items are scheduled to complete before the successor work item is scheduled to complete. A red exclamation mark and red colored arrows indicate there's an issue with the dependency. +For example, the Dependencies dialog below shows that two predecessor work items are scheduled to complete before the successor work item. A red exclamation mark and red arrows indicate an issue with this dependency. -When the dependency is to a work item in another project, the project information is shown as are other link relationships. +When a dependency links to a work item in another project, the project information and other link relationships are displayed. :::image type="content" source="media/dependencies/dependencies-cross-project.png" alt-text="Dependencies dialog for a work item with dependencies-cross-project."::: - ## Related articles - [Add or edit a Delivery Plan](add-edit-delivery-plan.md) diff --git a/docs/boards/plans/visibility-across-teams.md b/docs/boards/plans/visibility-across-teams.md index 33638c68702..48ba732905d 100644 --- a/docs/boards/plans/visibility-across-teams.md +++ b/docs/boards/plans/visibility-across-teams.md @@ -28,22 +28,20 @@ For an overview of all team tools, see [Manage teams and configure team tools](. - - ## Delivery Plans support a view of team backlogs on a calendar timeline With a Delivery Plan, you gain a tailor-made view across several teams and their development backlogs—stories, features, or epics. You can use these views to drive alignment across teams by overlaying several backlogs onto your delivery schedule. ::: moniker range="azure-devops" -When you configure a Delivery Plan, you select the teams and backlog levels of interest. You can then interact with the plan to update it and drill into more details. To learn more about Delivery Plans, see [Review team plans](review-team-plans.md). +When you configure a Delivery Plan, you select the teams and backlog levels of interest. You can then interact with the plan to update it and drill into more details. For more information about Delivery Plans, see [Review team plans](review-team-plans.md). :::image type="content" source="media/plans/overview-with-callouts.png " border="false" alt-text="Screenshot with callouts of Delivery Plans, collapsed teams."::: ::: moniker-end ::: moniker range="< azure-devops" -When you configure a Delivery Plan, you select the teams and backlog levels of interest. You can then interact with the plan to update it and drill into more details. To learn more about Delivery Plans, see [Delivery Plans](../extensions/delivery-plans.md). +When you configure a Delivery Plan, you select the teams and backlog levels of interest. You can then interact with the plan to update it and drill into more details. For more information about Delivery Plans, see [Delivery Plans](../plans/review-team-plans.md). Interactive plan elements ::: moniker-end @@ -76,7 +74,7 @@ With the multi-team portfolio backlog view, you can: Management teams can drill down from their portfolio backlog to see how **Epics** are progressing. Drilling down, you can see all the backlog items and features, even though they belong to one of three different teams: Customer Service, Phone, and Web. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Items that are owned by other teams appear with an information icon, :::image type="icon" source="../../media/icons/info.png" border="false"::: . > [!div class="mx-imgBorder"] @@ -87,24 +85,13 @@ Items that are owned by other teams appear with an information icon, :::image t ::: moniker-end - -::: moniker range="tfs-2018" -Items that are owned by other teams appear with an information icon, :::image type="icon" source="../../media/icons/info.png" border="false"::: . - -> [!div class="mx-imgBorder"] -> ![Backlog that shows parents and multi-team ownership](../backlogs/media/multi-ownership/management-team-backlog-epics-pre-nav.png) - -> [!TIP] -> Add the **Node Name** field as a column to identify the area path/team associated with the work items. - -::: moniker-end - + ### View backlog items and parent items owned by other teams Feature teams can turn **Show parents** on their backlogs to see context and those items owned by other teams. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Items that are owned by other teams appear with an information icon, :::image type="icon" source="../../media/icons/info.png" border="false"::: . @@ -113,20 +100,12 @@ Items that are owned by other teams appear with an information icon, :::image t ::: moniker-end - -::: moniker range="tfs-2018" -Items that are owned by other teams appear with an information icon, :::image type="icon" source="../../media/icons/info.png" border="false"::: . - -> [!div class="mx-imgBorder"] -> ![Items that are owned by other teams appear with an information icon.](media/visibility/web-team-backlog-multi-team-ownership-prev-nav.png) -::: moniker-end - + > [!TIP] > When estimating stories or product backlog items, start with one story point per person per day. Feature teams can later calibrate and adjust those estimates as needed. For example, the [velocity](../../report/dashboards/team-velocity.md) of a seasoned team is higher than a new team. The size of the work stays the same, but a seasoned team can just deliver faster. -To learn more about this configuration, see [Portfolio management](portfolio-management.md), [Add teams](../../organizations/settings/add-teams.md), and [Organize your backlog](../backlogs/organize-backlog.md). - +For more information about this configuration, see [Portfolio management](portfolio-management.md), [Add teams](../../organizations/settings/add-teams.md), and [Organize your backlog](../backlogs/organize-backlog.md). @@ -140,7 +119,6 @@ For example, here we've added three query-based charts, one for each team, to a Bug debt, Email team Bug debt, Voice team Bug debt, Web team - When you define multi-team dashboards, consider the following questions: - What are you wanting to learn and how will it drive your organization's actions? - What time frame is of interest? @@ -155,7 +133,7 @@ Use the [Query Results widget](../../report/dashboards/widget-catalog.md#query-r - New features (New or Proposed) - Features being actively worked (In Progress or Active) -Use the [Chart for work items widget](../../report/dashboards/widget-catalog.md#chart-wit-widget) to add query-based charts. To learn more about creating query-based charts, see [Charts](../../report/dashboards/charts.md). +Use the [Chart for work items widget](../../report/dashboards/widget-catalog.md#chart-wit-widget) to add query-based charts. For more information about creating query-based charts, see [Charts](../../report/dashboards/charts.md). ### Technical debt, bug debt, and activity dashboard @@ -168,7 +146,7 @@ Another measure of project health and the health of the teams is to monitor bug For tips on creating queries based on counts or numeric fields, see [Query by numeric field](../queries/query-numeric.md). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Use the Analytics Service to gain visibility across teams @@ -176,18 +154,17 @@ You can add [Widgets based on the Analytics Service](../../report/dashboards/ana ::: moniker-end - ## Track capacity when working on more than one team You can track capacity for individuals that participate on more than one team. To learn how, see [Set sprint capacity, Track capacity when working on more than one team](../sprints/set-capacity.md#track-capacity-per-team). -## Limitations of multi-team Kanban board views +## Limitations of multi-team board views -While the management teams you configure can use the Kanban board to monitor feature progress by turning on the Features backlog, there are limitations inherent within these views. Even if the management team and the feature teams configure their Feature [Kanban board columns](../boards/add-columns.md) with identical workflow mapping, updating the Features on one team's Kanban board won't be reflected on another team's Kanban board. +While the management teams you configure can use the board to monitor feature progress by turning on the Features backlog, there are limitations inherent within these views. Even if the management team and the feature teams configure their Feature [board columns](../boards/add-columns.md) with identical workflow mapping, updating the Features on one team's board won't be reflected on another team's board. Only when the work item state changes does the card column reflect the same on all boards. > [!IMPORTANT] -> Work items that appear on more than one team's Kanban board can yield query results that don't meet your expectations. Because each team can customize the Kanban board columns and swimlanes, the values assigned to work items which appear on different boards may not be the same. The primary work around for this issue is to maintain single ownership of work items by [team area path](../../organizations/settings/set-area-paths.md). Another option is to add custom workflow states which all teams can use. For more information, see [Customize your work tracking experience](../../reference/customize-work.md). +> Work items that appear on more than one team's board can yield query results that don't meet your expectations. Because each team can customize the board columns and swimlanes, the values assigned to work items which appear on different boards may not be the same. The primary work around for this issue is to maintain single ownership of work items by [team area path](../../organizations/settings/set-area-paths.md). Another option is to add custom workflow states which all teams can use. For more information, see [Customize your work tracking experience](../../reference/customize-work.md). ## Related articles diff --git a/docs/boards/queries/about-managed-queries.md b/docs/boards/queries/about-managed-queries.md index a33f87934f2..b5eb736736f 100644 --- a/docs/boards/queries/about-managed-queries.md +++ b/docs/boards/queries/about-managed-queries.md @@ -1,10 +1,10 @@ --- -title: Use managed queries to list work items -titleSuffix: Azure Boards +title: Use managed queries to list work items +titleSuffix: Azure Boards description: Learn how to track work by creating queries to list work items in Azure Boards and Azure DevOps. -ms.custom: boards-queries, cross-project, contperf-fy23 +ms.custom: boards-queries, cross-project, engagement-fy23 ms.service: azure-devops-boards -ms.assetid: 285a014e-89bf-4e5f-bebf-11094e93d796 +ms.assetid: 285a014e-89bf-4e5f-bebf-11094e93d796 ms.topic: conceptual ms.author: chcomley author: chcomley @@ -32,7 +32,7 @@ You can create queries and query folders from the web portal or from Visual Stud If you're just getting started, read [View, run, or email a work item query](view-run-query.md). For a quick reference to query editor tasks and sample queries, see [Query quick reference](query-index-quick-ref.md). - To find work items that are assigned to you, add the **@Me** macros as the value for the **Assigned To** field in one of the query clauses. -- All valid users with standard access can create queries and folders under the **My Queries** area. To create queries and query folders under **Shared Queries**, you must have the Contribute permission set. For more information, see [Set permissions on queries](../queries/set-query-permissions.md). +- All valid users with standard access can create queries and folders under the **My Queries** area. To create queries and query folders under **Shared Queries**, have the Contribute permission set. For more information, see [Set permissions on queries](../queries/set-query-permissions.md). - You can modify any query by adding criteria to focus on a product area, an iteration, or another field. To modify a query, [open the query editor](using-queries.md). - You can open any query in [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). You can also update the fields of one or more work items and publish your changes to the database for tracking work items. - You can [visualize status or progress](../../report/dashboards/charts.md) by creating a pie-chart, column chart, or trend chart for flat-list queries. @@ -48,7 +48,7 @@ The following sections provide an overview of the functions supported to define [!INCLUDE [temp](../includes/feature-matrix-filter-queries.md)] - +### Supported macros [!INCLUDE [temp](../includes/feature-matrix-query-macros.md)] @@ -126,9 +126,6 @@ Azure Boards supports three query types. The icon next to each query indicates t To learn more about link types, see [Link type reference](link-type-reference.md). - - - ## My Queries, Shared Queries, and Favorites Only you can view and run queries that you save under **My Queries** with the queries directory. Also, you can favorite one of these queries to have it appear within your query selector. @@ -140,26 +137,41 @@ For more information, see: - [Set query permissions](set-query-permissions.md) - [Favorite a query](view-run-query.md) and [Set personal or team favorites](../../project/navigation/set-favorites.md#favorite-a-shared-query) -::: moniker range=">= azure-devops-2019" - ## Query directory, query folders, and breadcrumbs -The **Queries** page contains a directory-focused view that you can filter to find specific queries of interest. -When working in the **Queries** pages, you can go to a subfolder, folder, or page. +The **Queries** page contains a **Favorites** and an **All** tab. Each contains a directory-focused view that you can filter to find specific queries of interest. -![Queries breadcrumbs](../../project/navigation/media/breadcrumbs/queries-breadcrumbs.png) +When you're working in the **Queries** pages, you can go to a folder, subfolder, or a query page. -Also, you can choose a query that you've favorited from the selector menu. Or, you can choose to browse all queries that return you to the **All Queries** page. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Queries, Query selector.](../../project/navigation/media/breadcrumbs/query-bd-and-selector.png) +::: moniker range="azure-devops" +:::image type="content" source="media/view-run-queries/query-navigation-new-boards-hubs.png" alt-text="Screenshot of queries page." ::: -For more information, see [Query FAQs, Navigate, and Folders](query-faqs.yml). +::: moniker-end + +::: moniker range="< azure-devops" + +As you make selections, the breadcrumbs are shown at the top of the page. You can navigate to a folder, subfolder, or query page. + +:::image type="content" source="../../project/navigation/media/breadcrumbs/queries-breadcrumbs.png" alt-text="Screenshot of breadcrumbs on query page." ::: ::: moniker-end - +You can also select a favorite query or return to the **All** queries page from the drop-down menu of an open query. + +::: moniker range="< azure-devops" + +:::image type="content" source="../../project/navigation/media/breadcrumbs/query-bd-and-selector.png" alt-text="Screenshot of query dropdown." ::: + +::: moniker-end + +::: moniker range="azure-devops" + +:::image type="content" source="../../project/navigation/media/breadcrumbs/query-dropdown-new-boards-hubs.png" alt-text="Screenshot of query navigation dropdown." ::: + +::: moniker-end + +For more information, see [Query FAQs, Navigate, and Folders](query-faqs.yml). ## Query charts and widgets @@ -210,11 +222,10 @@ For more information, see the following articles: - [Query FAQs](query-faqs.yml) - [Query quick reference](query-index-quick-ref.md) -- [Cross-service and enhanced query operations](query-support-integration-cross-service-extensions.md) - [Work item field index](../work-items/guidance/work-item-field.md) - [Set query permissions](set-query-permissions.md) - [Query fields, operators, and macros](query-operators-variables.md) - [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) - \ No newline at end of file + diff --git a/docs/boards/queries/add-tags-to-work-items.md b/docs/boards/queries/add-tags-to-work-items.md index 1782d412caa..2972aa99fab 100644 --- a/docs/boards/queries/add-tags-to-work-items.md +++ b/docs/boards/queries/add-tags-to-work-items.md @@ -1,7 +1,7 @@ --- title: Add tags to work items to categorize lists and boards titleSuffix: Azure Boards -description: Learn how to add work item tags to categorize and filter lists & boards when working in Azure Boards and Azure DevOps. +description: Learn how to add work item tags to categorize and filter lists & boards when working in Azure Boards. ms.custom: boards-queries ms.service: azure-devops-boards ms.assetid: 79A08F31-BB8A-48BD-AD17-477EE0B76BC7 @@ -9,32 +9,25 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 07/07/2022 +ms.date: 04/24/2024 --- # Add work item tags to categorize and filter lists and boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +Tag work items to quickly filter the product backlog or a work item query by categories that you define. A tag corresponds to a one or two keyword phrase that you define and that supports your needs to filter a backlog or query, or define a query. -Tagging work items helps you quickly filter the product backlog or a work -item query by categories that you define. -A tag corresponds to a one or two keyword phrase that you define and that supports your needs to filter a backlog or query, or define a query. +Tags are a better choice for filtering work items than using text strings as described in [Define a query/Best practices](using-queries.md). -Tags are a better choice to filter work items than using text strings as described in [Guidance to create high-performing queries](high-performing-queries.md). - -You can add and modify tags from the web portal, from Team Explorer plug-in for Visual Studio. Also, you can open a query in [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) to modify tags in bulk. +You can add and modify tags from the web portal, from Team Explorer plug-in for Visual Studio. Also, you can open a query in [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) to modify tags in bulk. > [!NOTE] -> Tags are a shared resource, they're associated with a project and not a team. If your project contains multiple teams, all teams add to and work from the same set of tags. - -[!INCLUDE [temp](../includes/prerequisites-work-items.md)] +> Tags are a shared resource associated with a project and not a team. If your project contains multiple teams, all teams add to and work from the same set of tags. -::: moniker range="azure-devops" -> [!NOTE] -> Users with **Stakeholder** access for public projects are allowed to add new tags. -::: moniker-end +## Prerequisites +[!INCLUDE [temp](../includes/prerequisites-work-items.md)] @@ -42,64 +35,49 @@ You can add and modify tags from the web portal, from Team Explorer plug-in for Tags should be 400 characters or less and not contain separators such as a `,` (comma), `;` (semicolon), or other formatting character. -> [!TIP] -> We recommend that you don't use the `@` character in a tag. Tags that start with the `@` character can't be used in a work item query. The `@` character signifies a macro within a query and therefore the tag isn't recognized as a tag. - +**Recommendation:** Don't use the `@` character in a tag. Tags that start with the `@` character can't be used in a work item query. The `@` character signifies a macro within a query and therefore the tag isn't recognized as a tag. From the web portal, open a work item and add a tag. Choose **Add tag** and type your keyword. Or, select from the list of previously assigned tags. > [!div class="mx-imgBorder"] -> ![Add one or more tags to a work item](media/add-tags/add-tag-vsts.png) +> ![Screenshot showing adding one or more tags to a work item.](media/add-tags/add-tag-vsts.png) To add several tags at one time, type a comma between tags. Tags are case sensitive. -Tags that appear in the tag bar are already assigned to the work item. To unassign a tag, choose the x on the tag,![Delete a tag assigned to a work item](media/add-tags/unassign-a-tag.png). - -::: moniker range="azure-devops" -> [!NOTE] -> By default, all Contributors and Stakeholders of public projects are granted permissions to add new and existing -> tags. Stakeholders in private projects can add tags that are already defined, but not add -> new tags. To grant or restrict permissions to create new tags, you set -> the permission **Create tag definition** at the project-level. To learn -> more, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). -::: moniker-end - +Tags that appear in the tag bar are already assigned to the work item. To unassign a tag, choose the x on the tag,![Screenshot of deleting a tag assigned to a work item.](media/add-tags/unassign-a-tag.png). -## Bulk add or remove tags +## Bulk add or remove tags You can bulk update work items to add or remove tags from the web portal. You bulk modify tags in the same way as you [bulk modify other fields using the web portal](../backlogs/bulk-modify-work-items.md#tags). Or, you can use [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) to bulk add or remove tags. > [!div class="mx-imgBorder"] -> ![Edit work items dialog, Bulk add to several work items.](media/add-tags/bulk-add-tags.png) +> ![Screenshot showing Edit work items dialog, Bulk add to several work items.](media/add-tags/bulk-add-tags.png) > [!NOTE] -> Bulk modify of tags from the Visual Studio or other supported clients isn't supported. - +> Bulk modifying tags from Visual Studio or other supported clients isn't supported. -## Query for work items based on tags +## Query for work items based on tags + +To query work items based on tags, add a clause for each tag you want to use to support your query. -To query work items based on tags, add a clause for each tag you want to use to support your query. +[!INCLUDE [temp](../includes/query-clause-tip.md)] -> [!TIP] -> You can use the **Contains** or **Does Not Contain** operators. Tags that start with the `@` character can't be used in a work item query as the query editor interprets the `@` character as a macro. To learn more about queries, see [Create managed queries](using-queries.md). +You can use the **Contains** or **Does Not Contain** operators. Tags that start with the `@` character can't be used in a work item query as the query editor interprets the `@` character as a macro. For more information, see [Create managed queries](using-queries.md). For example, here we query for all work items that are tagged either ```Web``` or ```Service```. > [!div class="mx-imgBorder"] > ![Screenshot of Query Editor to query on tags.](media/add-tags/query-tags-add-or.png) - -[!INCLUDE [temp](../includes/query-clause-tip.md)] - - + > [!NOTE] -> The ability to query for work items that don't have any tags attached to them is not a supported feature. If you'd like to up vote the request to support this feature, you can do so on our Developer Community page, [Be able to search for empty tags](https://developercommunity.visualstudio.com/t/be-able-to-search-for-empty-tags/907425). +> You can't query for work items that don't have any tags attached to them. If you'd like to up vote the request to support this feature, you can do so on our Developer Community page, [Be able to search for empty tags](https://developercommunity.visualstudio.com/t/be-able-to-search-for-empty-tags/907425). @@ -108,9 +86,9 @@ For example, here we query for all work items that are tagged either ```Web``` o Choose **Column Options** to add the **Tags** field to the product backlog or a work item query. If the option doesn't appear, choose **More commands** :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: to select it from the menu of options. > [!div class="mx-imgBorder"] -> ![Column options dialog, Add Tags to the selected columns to display.](media/add-tags/column-options-add-tags-field.png) +> ![Screenshot of Column options dialog, Add Tags to the selected columns to display.](media/add-tags/column-options-add-tags-field.png) -All tags that have been added to the listed work items appear. +All tags added to the listed work items appear. > [!div class="mx-imgBorder"] > ![Screenshot of product backlog, View with Tags column added.](media/add-tags/backlog-with-tags.png) @@ -126,71 +104,65 @@ Begin by choosing **Filter** :::image type="icon" source="../media/icons/filter- Check the boxes of those tags that you want to filter on. Keep the **OR** selection to run a logical OR for all the tags you selected. Or, choose the **AND** option to run a logical AND on all the selected tags. > [!div class="mx-imgBorder"] -> ![View with Tags column added](media/add-tags/filter-backlog-tags.png) - - -## Delete, remove, or manage tags +> ![Screenshot of view with tags column added.](media/add-tags/filter-backlog-tags.png) -You can't delete a tag itself. However, if you delete a tag from all work items to which it's currently assigned, the system deletes the tag. The system automatically deletes unassigned tags after three days of disuse. +## Delete, remove, or manage tags -If you misspell a tag, don't assign the misspelled tag to any work item and the system automatically deletes it within three days. +You can't delete tags using the Azure DevOps Web UI. -Another option is to install the [Marketplace Tags Manager](https://marketplace.visualstudio.com/items?itemName=YodLabs.TagsManager2), which adds a **Tags** page under **Boards** or **Work** to manage tags. +If you need to remove a tag, you can create a script or application capable of a delete using the [Azure DevOps REST API](/rest/api/azure/devops/wit/tags?view=azure-devops-rest-7.2&preserve-view=true) or the [.NET client libraries](/azure/devops/integrate/concepts/dotnet-client-libraries?view=azure-devops&preserve-view=true). For more examples, see [Azure-DevOps-Admin-CLI](https://github.com/danhellem/azure-devops-admin-cli). +Another option is to install the [Marketplace Tags Manager](https://marketplace.visualstudio.com/items?itemName=YodLabs.TagsManager2), which adds a **Tags** page under **Boards** or **Work** to manage tags, including deletes. - ## Color-code tags on boards -You can highlight tags on Kanban board cards by color-coding them. These colors only appear on the Kanban board that you configure. They don't appear on backlogs or Taskboards. For more information, see [Customize cards, color-code tags](../boards/customize-cards.md#color-tags). +Highlight tags on board cards by color-coding them. These colors only appear on the board that you configure. They don't appear on backlogs or Taskboards. For more information, see [Customize cards, color-code tags](../boards/customize-cards.md). > [!div class="mx-imgBorder"] -> ![Boards>Settings>Tag colors dialog](media/add-tags/color-code-tags.png) +> ![Screenshot of sequence, Boards, Settings, Tag colors dialog.](media/add-tags/color-code-tags.png) ::: moniker range="azure-devops" ## Chart work items and group by tags -> [!NOTE] -> You can't group a query-based chart by tags, however, you can group a **Chart for Work Items** widget by tags that you add to a dashboard. This feature is in public preview. To enable it, see [Manage or enable features](../../project/navigation/preview-features.md) and turn on **Enable group by tags for work item chart widget on dashboard**. +You can't group a query-based chart by tags, but, you can group a **Chart for Work Items** widget by tags that you add to a dashboard. This feature is in public preview. To enable it, see [Manage or enable features](../../project/navigation/preview-features.md) and turn on **Enable group by tags for work item chart widget on dashboard**. -To group a **Chart for Work Items** widget by tags, complete the same steps provided in [Track progress with status and trend query-based charts, Add a chart widget to a dashboard](../../report/dashboards/charts.md#add-chart-widget). Make sure that your flat-list query contains **Tags** in the query clause or as a column option. Then, choose **Tags** for the **Group by** selection. To filter the chart to show only some tags, choose the **Selected tags** radio button and then choose the tags you want the chart to display. +To group a **Chart for Work Items** widget by tags, complete the same steps provided in [Track progress with status and trend query-based charts, Add a chart widget to a dashboard](../../report/dashboards/charts.md). Make sure that your flat-list query contains **Tags** in the query clause or as a column option. Then, choose **Tags** for the **Group by** selection. To filter the chart to show only some tags, choose the **Selected tags** radio button and then choose the tags you want the chart to display. :::image type="content" source="../../report/dashboards/media/charts/configure-chart-widget-tags.png" alt-text="Screenshot of Chart by Work Items, Configure, Group by Tags."::: ::: moniker-end -## Related articles - -- [Best tool to add, update, and link work items](../work-items/best-tool-add-update-link-work-items.md) -- [Use the query editor to list and manage queries](using-queries.md) -- [Show tags on cards](../../boards/boards/customize-cards.md) -- [Bulk modify work items from the web portal](../backlogs/bulk-modify-work-items.md) -- [Bulk modify work items from Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) - -### Marketplace extension - -- [Marketplace Tags Manager](https://marketplace.visualstudio.com/items?itemName=YodLabs.TagsManager2) - ### Limits on the number of tags -While no hard limit exists, creating more than 100,000 tags for a project collection can negatively impact performance. Also, the autocomplete dropdown menu for the tag control displays a maximum of 200 tags. When more than 200 tags are defined, begin entering to cause the tag control to display relevant tags. +While no hard limit exists, creating more than 100,000 tags for a project collection can negatively affect performance. Also, the autocomplete dropdown menu for the tag control displays a maximum of 200 tags. When more than 200 tags are defined, begin entering to cause the tag control to display relevant tags. -You can't assign more than 100 tags to a work item or you'll receive the following message: +You can't assign more than 100 tags to a work item or you receive the following message: ``` TF401243: Failed to save work item because too many new tags were added to the work item. ``` -Save the work item with the tags (100 or less) that you've added, and then you can add more tags. +Save the work item with the tags (100 or less) that you added, and then you can add more tags. Limit queries to fewer than 25 tags. More than that amount and the query likely times out. - ::: moniker range="< azure-devops" ### Add tags to the default column view on the product backlog -To add the **Tags** field as a column field for the product backlog, you modify the ProcessConfiguration file to include ```System.Tags```. To learn how, see the [Process configuration XML element reference](../../reference/xml/process-configuration-xml-element.md). +To add the **Tags** field as a column field for the product backlog, you modify the ProcessConfiguration file to include ```System.Tags```. For more information, see the [Process configuration XML element reference](../../reference/xml/process-configuration-xml-element.md). ::: moniker-end + +## Related articles + +- [Use the query editor to list and manage queries](using-queries.md) +- [Show tags on cards](../../boards/boards/customize-cards.md) +- [Bulk modify work items from the web portal](../backlogs/bulk-modify-work-items.md) +- [Bulk modify work items from Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) + +### Marketplace extension + +- [Marketplace Tags Manager](https://marketplace.visualstudio.com/items?itemName=YodLabs.TagsManager2) diff --git a/docs/boards/queries/build-test-integration.md b/docs/boards/queries/build-test-integration.md index 1087183bd5e..9c13c3bf527 100644 --- a/docs/boards/queries/build-test-integration.md +++ b/docs/boards/queries/build-test-integration.md @@ -8,8 +8,9 @@ ms.assetid: 6e162a82-c98b-4c94-862c-addcdcbc182d ms.author: chcomley author: chcomley ms.topic: example-scenario +ai-usage: ai-assisted monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 11/26/2024 --- @@ -17,14 +18,25 @@ ms.date: 04/01/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Work item fields that support build and test integration support the following actions: -- Associate bugs with the builds where they were found or fixed -- Query for bugs associated with a build -- Mark test cases as either manual or automated, and store information to support automated test cases -- For test cases and shared steps, define the action and validation steps and the data that are used to run tests. +Work item fields that support build and test integration offer powerful functionalities to enhance your development workflow. These integrations enable the following key actions: - +- **Associate bugs with builds:** Link bugs directly to the specific builds where they were discovered or resolved, ensuring precise tracking and accountability. +- **Query bugs by build:** Retrieve and analyze bugs associated with particular builds to identify trends and areas needing improvement. +- **Mark test cases as Manual or Automated:** Categorize test cases accordingly and store relevant information to support automated testing processes. +- **Define action and validation steps for test cases and shared steps:** Specify the actions to perform, validation criteria, and the data required to execute tests effectively. +This article provides guidance on how to use build and test integrations to improve your project's quality and efficiency. + +## Prerequisites + +- **Project-level permissions**: + - **Contributors**: Can create and edit queries. + - **Readers**: Can view queries but can't create or edit them. + - **Project Administrators**: Have full control over all project settings, including queries. +- **Specific permissions for Test Artifacts**: +- **Manage Test Plans**: Allows creating, editing, and deleting test plans. +- **Manage Test Suites**: Allows creating, editing, and deleting test suites. +- **Edit Work Items in this Node**: Required to add or edit test-specific work items like test cases and test suites. ## Supported operators and macros @@ -45,8 +57,7 @@ Most build and test integration fields have a data type of String, PlainText, or **Multi-line text strings (PlainText)** :::column-end::: :::column span="3"::: - `Contains Words`, `Does Not Contain Words`, `Is Empty`, `Is Not Empty`. - The `Is Empty` and `Is Not Empty` operators are supported for Azure DevOps Server 2019 RC2 and later versions. + `Contains Words`, `Does Not Contain Words`, `Is Empty`, `Is Not Empty`. :::column-end::: :::row-end::: :::row::: @@ -55,7 +66,7 @@ Most build and test integration fields have a data type of String, PlainText, or :::column-end::: :::column span="3"::: `= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field]`, `Contains`, `Does Not Contain`, `In`, `Not In`, `In Group`, `Not In Group`, `Was Ever` - **Macros**: `[Any]`, valid with the **Work Item Type** field; and `@Project`, valid with the **Team Project** field. The system automatically defaults to filtering based on the current project. For more information, see [Query across projects](using-queries.md#across-projects). + **Macros**: `[Any]`, valid with the **Work Item Type** field; and `@Project`, valid with the **Team Project** field. The system automatically defaults to filtering based on the current project. For more information, see [Query across projects](using-queries.md). :::column-end::: :::row-end::: @@ -99,7 +110,7 @@ Most build and test integration fields have a data type of String, PlainText, or :::row-end::: - + ## List bugs and the test cases that test them @@ -110,11 +121,11 @@ Open a new query, set the query type to Work items and direct links. Filter for > [!NOTE] >You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using parent-child link types. You can [view the hierarchy through the **Test>Test Plans** page](../../test/create-a-test-plan.md). - + ## Build and test data fields -The following table describes the fields that are defined in one or more of the test WITs. For information about data types and field attributes, see [Work item fields and attributes](../work-items/work-item-fields.md). +The following table describes the fields that are defined in one or more of the test work item types. For information about data types and field attributes, see [Work item fields and attributes](../work-items/work-item-fields.md). To customize a field or picklist, see [Add or modify a field to support queries, reports, and workflow](../../reference/add-modify-field.md). @@ -240,7 +251,7 @@ To customize a field or picklist, see [Add or modify a field to support queries, :::column-end::: :::column span="2"::: The test suite category. Allowed values are: - - **Query Based**: Use to group together test cases that have a particular characteristic - for example, all the tests that have Priority=1. The suite automatically includes every test case that is returned by the query that you define. + - **Query Based**: Use to group together test cases that have a particular characteristic - for example, all the tests that have Priority=1. The suite automatically includes every test case that gets returned by the query that you define. - **Requirement Based**: Use to group together test cases designed to track the test status of backlog items. Each test case that you add to a requirement-based test suite is automatically linked to the backlog item. - **Static**: Use to group together test cases with any characteristics or test suites. For more information, see [Create a test plan](../../test/create-a-test-plan.md). @@ -415,13 +426,11 @@ The following fields don't appear on work item forms, but these fields are track > [!NOTE] > 1. Do not customize the pick list for these fields. The system accepts only those values listed. - - - + ### Fields that integrate with Team Foundation Build -Team Foundation Build is the on-premise build system you can use with Azure DevOps Server and TFS. You can configure your build process by using Team Foundation Build, and Team Foundation Build can generate work items when a build fails. It can also add build information to work items that were resolved in a particular build. For this to work, Team Foundation Build requires that the following two fields be added to the work item type definition: **Found In** and **Integration Build**. +Team Foundation Build is the on-premises build system you can use with Azure DevOps Server. You can configure your build process by using Team Foundation Build, and Team Foundation Build can generate work items when a build fails. It can also add build information to work items that were resolved in a particular build. Team Foundation Build requires that the following two fields get added to the work item type definition: **Found In** and **Integration Build**. **Found In** and **Integrated in Build** fields are defined for Bugs in the default processes. These fields associate bugs with the builds where they were found or fixed. @@ -449,11 +458,11 @@ When the **Found In** field is present in a WIT definition, Team Foundation Buil When the **Integration Build** field is present in the WIT definition, Team Foundation Build identifies work items that were resolved with each build and then updates those work items to set the build number in which they were resolved in the **Integration Build** field. If the **Integration Build** field is missing, Team Foundation Build doesn't store the build number in the work items, and everything else works as expected. - + ### Builds and global list autopopulation -The first time you queue a build for a project using Team Foundation Build, TFS automatically adds a global list labeled Build - ProjectName. Each time a build is run, a LISTITEM is added to this global list with the name of the build. +The first time you queue a build for a project using Team Foundation Build, it automatically adds a global list labeled Build - ProjectName. Each time a build is run, a LISTITEM is added to this global list with the name of the build. ::: moniker range="< azure-devops" @@ -475,13 +484,13 @@ By adding a **GLOBALLIST** element to the **FIELD** definition, you can provide ::: moniker-end - + ### Fields that Integrate with Test Plans With Test Plans, you can automate the creation of a bug or other type of work item when a test fails. For more information, see Add findings to existing bugs with exploratory testing. -When a work item has been created in this manner, information about the system and the steps to reproduce the bug are captured in the **System Info** and **Repro Steps** fields. +When you create a work item in this manner, information about the system and the steps to reproduce the bug gets captured in the **System Info** and **Repro Steps** fields. ::: moniker range="< azure-devops" You can add these fields to work item types that you create for tracking defects using the following code snippet. @@ -496,18 +505,36 @@ You can add these fields to work item types that you create for tracking defects ### Fields that integrate with Team Foundation Version Control -One of the features available in Team Foundation version control (TFVC) enables you to associate or resolve work items when you check in code. You might have worked on a particular work item when you make a code change and you can set that association from within the source-control check-in window when you're finished working on the code. +**Associating and resolving work items with TFVC** + +Team Foundation Version Control (TFVC) offers a feature that allows you to associate or resolve work items directly during the code check-in process. When you work on a specific work item and make corresponding code changes, you can link that work item from within the source-control check-in window upon completing your changes. -The ability of Team Foundation version control to resolve a work item requires that work items contain a particular action. The source control system then queries work item tracking to determine whether the work item supports that action, and if it does support that action, it also queries for the source and destination states of the transition. If the action is found, the source control system can transition the work item according to the set transition when it checks in the code. +**How TFVC resolves work items** +The ability of TFVC to resolve a work item depends on the presence of a specific action within the work item. Here's how the process works: + +1. **Action verification:** The source control system queries the work item tracking system to determine if the work item supports the required action. +2. **State transition:** If the action is supported, TFVC retrieves the source and destination states associated with the transition. +3. **Work item update:** Upon checking in the code, TFVC transitions the work item's state according to the predefined transition. + +This integration ensures that work items accurately reflect the status of associated code changes, enhancing traceability and accountability within your development workflow. > [!NOTE] > When you use the **Checkin** action, you must set appropriate *from* and *to* states to reflect the state transition that you want. -For more information about Actions, see [Automate field assignments based on State, Transition, or Reason](/previous-versions/azure/devops/reference/xml/automate-field-assignments-state-transition-reason). +For more information, see [Automate field assignments based on State, Transition, or Reason](/previous-versions/azure/devops/reference/xml/automate-field-assignments-state-transition-reason). + +## Limitations + +There are the following limitations when querying by test case: +- **Hierarchical views**: You can’t construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren’t linked together using parent-child link types. +- **Query-based test suites**: While you can create query-based test suites, the suite automatically includes every test case that gets returned by the query you define, which can sometimes lead to unintended test cases being included if the query isn’t precise. +- **Field limitations**: Some fields related to test cases, such as detailed execution results, might require creative usage of existing fields or customization of payload data to be fully utilized. +- **Performance and rate limits**: Azure DevOps imposes limits on the resources individuals can consume and the number of requests they can make. Nonoptimized queries or excessive API calls can lead to delays or blocked requests. +- **Test case linking**: Test cases aren’t automatically linked to other work items in a way that supports complex queries. For example, you can’t easily query for a hierarchical view of test cases linked to specific requirements or user stories. ## Related articles - [Work item field index](../work-items/guidance/work-item-field.md) - [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md) -- [Linking, traceability, and managing dependencies](link-work-items-support-traceability.md) +- [Link work items to other objects](../backlogs/add-link.md) - [Link and attachment queries](linking-attachments.md) diff --git a/docs/boards/queries/define-query-hyperlink.md b/docs/boards/queries/define-query-hyperlink.md deleted file mode 100644 index d258b1183a5..00000000000 --- a/docs/boards/queries/define-query-hyperlink.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Define a query as a hyperlink in Azure Boards and Azure DevOps -titleSuffix: Azure Boards -description: Learn how to construct a hyperlink for use in a query in Azure Boards and Azure DevOps. -ms.custom: boards-queries -ms.service: azure-devops-boards -ms.article: -ms.assetid: -ms.author: chcomley -author: chcomley -ms.topic: how-to -monikerRange: '<= azure-devops' -ms.date: 04/01/2022 ---- - -# Define a query as a hyperlink in Azure Boards and Azure DevOps - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - - - -A query hyperlink uses the Work Item Query Language (WIQL), which resembles Transact-SQL. For details about constructing WIQLs, see [Syntax for the Work Item Query Language (WIQL)](wiql-syntax.md). - - -> [!NOTE] -> Most browsers enforce a limit of between 2000 and 2083 characters for a URL string. - - -[!INCLUDE [temp](../../includes/version-selector-minimize.md)] - -::: moniker range="azure-devops" - -## Query hyperlink syntax for Azure DevOps Services - -Encode the WIQL portion of the URL syntax. You can use any URL encoder tool to encode your URL. - -``` -https://dev.azure.com/OrganizationName/ProjectName/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage} -``` -For example, the following hyperlink lists the ID and title of all active bugs defined under the FabrikamFiber/Web area path for the fabrikam organization. - -``` -https://dev.azure.com/fabrikam/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.State%5D%3D'Active'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb' -``` - -The decoded WIQL conforms to: - -```wiql -SELECT [System.ID], [System.Title] - FROM WorkItems - WHERE [System.TeamProject]='FabrikamFiber' - AND [System.WorkItemType]='Bug' - AND [System.State]='Active' - AND [System.AreaPath]='FabrikamFiber\Web' -``` - -> [!NOTE] -> For queries made against Azure Boards, the WIQL length must not exceed 32K characters. The system won't allow you to create or run queries that exceed that length. - -::: moniker-end - - -::: moniker range="< azure-devops" - -## Query hyperlink syntax for TFS 2018 through Azure DevOps Server 2020 - -``` -https://{ServerName}/{CollectionName}/{ProjectName}/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage} -``` - -For example, the following hyperlink lists the ID, title, and state of all bugs under the FabrikamFiber/Web area path. - -``` -http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%2C%20%5BSystem.State%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb'%20%20 -``` - -Which is comparable to the non-encoded entry shown below. - -``` -http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql= -SELECT [System.ID], [System.Title], [System.State] - FROM WorkItems - WHERE [System.TeamProject]='FabrikamFiber' - AND [System.WorkItemType]='Bug' - AND [System.AreaPath]='FabrikamFiber\Web' -``` - -::: moniker-end - - -## Related articles - -- [Syntax for the Work Item Query Language (WIQL)](wiql-syntax.md) -- [Wiql Editor, a Marketplace extension](https://marketplace.visualstudio.com/items?itemName=ottostreifel.wiql-editor) -- [REST API, Wiql](/rest/api/azure/devops/wit/wiql) - diff --git a/docs/boards/queries/example-query-charts.md b/docs/boards/queries/example-query-charts.md index 70492774b1c..c58a6d34e9e 100644 --- a/docs/boards/queries/example-query-charts.md +++ b/docs/boards/queries/example-query-charts.md @@ -7,8 +7,9 @@ ms.custom: boards-queries, engagement-fy23 ms.author: chcomley author: chcomley ms.topic: sample +ai-usage: ai-assisted monikerRange: '<= azure-devops' -ms.date: 02/14/2023 +ms.date: 11/26/2024 --- @@ -16,68 +17,72 @@ ms.date: 02/14/2023 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Query charts are a great way to visualize status and trends. Also, by adding several charts to a dashboard, you can quickly review all the important data you want to monitor for your team or project. With that in mind, consider addressing the following questions with your team: -- *What are the most useful query charts for us to create and monitor?* -- *What charts help to maintain backlog hygiene?* -- *What time frame should we monitor when creating trend charts?* +Query charts are excellent for visualizing status and trends. Adding multiple charts to a dashboard allows quick monitoring of essential data for your team or project. Consider discussing the following questions with your team: -Not all teams have the same goals or tracking needs. However, teams that adopt Agile methods tend to routinely perform the following tasks. So consider the status and trend charts that can help your team perform these tasks. -- [Triage incoming work](../sprints/best-practices-scrum.md#tips-for-successful-triage-meetings), ensure new work is well defined -- Refine the backlog as described in [Backlog management ](../backlogs/best-practices-product-backlog.md) -- Plan sprints and set sprint goals as described in [Scrum and best practices](../sprints/best-practices-scrum.md) -- Conduct [daily stand-ups](../sprints/best-practices-scrum.md#daily-scrum-meetings). +- *Which query charts are most useful for us to create and monitor?* +- *Which charts help maintain backlog hygiene?* +- *What time frame should we use for trend charts?* + +While teams might have varied goals and tracking needs, Agile teams typically perform these tasks. Select status and trend charts that support the following activities: +- [Triage incoming work](../sprints/best-practices-scrum.md#tips-for-successful-triage-meetings) to ensure new work is well defined +- Plan sprints and set sprint goals as described in [Scrum and best practices](../sprints/best-practices-scrum.md) +- Conduct [daily stand-ups](../sprints/best-practices-scrum.md#daily-scrum-meetings) ## Prerequisites -- To create a query chart or view query charts from the Queries page, you must have **Basic** access or higher. Users with **Stakeholder** access can't view or create charts from the **Queries** page, however, they can view charts added to a team dashboard. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -- To add a query chart to a dashboard: - - You need to save the query under the **Shared Queries** folder. To do that, you must be granted permissions to save queries under a folder. To get permissions granted, see [Set permissions on queries and query folders](set-query-permissions.md). - - You must have created the dashboard or be granted permissions to edit the dashboard. To learn more about dashboard permissions, see [Set dashboard permissions](../../report/dashboard-permissions.md). -- To view a query chart added to a dashboard, you must have **Read** permissions to the underlying query. If that permission is denied, then the widget displays a *Widget failed to load* message. +- **Access levels**: To create a query chart or view query charts from the Queries page, have at least **Basic** access. +- **Permissions**: + - To create or edit a shared query, have your **Contribute** permission set to **Allow** for the shared query folder. + - To view a query chart added to a dashboard, have **Read** permissions to the underlying query. If this permission is denied, then the widget displays a *Widget failed to load* message. +- **Tasks**: To add a query chart to a dashboard, save the query under the **Shared Queries** folder. ::: moniker range="azure-devops" > [!NOTE] -> Users with **Stakeholder** access for a public project have full access to query chart features just like users with **Basic** access. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). +> Users with [**Stakeholder** access](../../organizations/security/stakeholder-access.md) for a public project have full access to query chart features just like users with **Basic** access. Users with **Stakeholder** access for a private project can't view or create charts from the **Queries** page, however, they can view charts added to a team dashboard. ::: moniker-end - -## Tips for creating query charts - -For details on creating query charts, see [Track progress with status and trend query-based charts](../../report/dashboards/charts.md). Make sure your queries meet the following guidelines. -- Only choose **Flat list of work items** for the query type. Only flat-list queries support query charts. -- Always save a query after modifying the clauses or column options before switching to the **Charts** page. -- Use the **In** and **Not In** operators to specify more than one work item type, workflow state, or other groupings of interest -- When creating a trend chart, make sure that your query returns no more than 1000 work items. You'll receive a widget error if that number is exceeded. -- Add the fields to either a query clause or the column options that you want to use within your chart. You can group charts by any field except date-time, free-form text, and tag fields. For example: - - To group by status, include the **State** field - - To group by work assignments, include the **Assigned To** field - - To group by sprints or iterations, include the **Iteration Path** - - To group by team, include the **Node Name** field that displays the leaf node of the **Area Pat**h - - To group by a custom field, include it. -- To sum a numeric column, include the corresponding field in your query clause or column options. For more examples of charts created from numeric fields, see [Query by a numeric field](query-numeric.md). -- You can't group charts by the following field data types: - - Work item **ID** or **Parent** fields - - Date-time fields, such as **Created Date**, **Changed Date** - - Plain text fields, such as **Title** - - Rich-text fields, such as **Description**, **Acceptance Criteria**, **Repro Steps** - - **Tags** (You can filter a query using tags, however you can't use tags to configure your query chart). - ::: moniker range=">= azure-devops-2022" - > [!NOTE] - > While you can't group a query-based chart by tags, you can group a **Chart for Work Items** widget by tags that you add to a dashboard as described in [Configure a chart for work items widget](../../report/dashboards/configure-chart-work-items-widget.md). - ::: moniker-end -- If you plan to add a query chart to a dashboard, first create the dashboard. Then, you can add it to the dashboard from the **Queries>Charts** page. -- If you add a query and then want to add it to a dashboard from the dashboard, you must first refresh your browser for the dashboard to register the newly added query. -- To optimize performance of complex queries, see [Best integration practices, Optimize queries](../../integrate/concepts/integration-bestpractices.md#optimize-queries). +## Guidelines for creating query charts + +For detailed instructions on creating query charts, see [Track progress with status and trend query-based charts](../../report/dashboards/charts.md). Ensure your queries adhere to the following guidelines: + +- **Query type:** Use **Flat list of work items** as only flat-list queries support query charts. +- **Save changes:** Save your query after modifying clauses or column options before navigating to the **Charts** page. +- **Operators:** Utilize **In** and **Not In** operators to include multiple work item types, workflow states, or other groupings. +- **Trend charts:** Limit queries for trend charts to a maximum of 1,000 work items to avoid widget errors. +- **Grouping fields:** Add relevant fields to your query clauses or column options. You can group charts by: + - **State:** Include the **State** field. + - **Assigned To:** Include the **Assigned To** field. + - **Iteration Path:** Include the **Iteration Path** field. + - **Node Name:** Include the **Node Name** field for team grouping. + - **Custom Fields:** Include any custom fields as needed. +- **Summing numeric columns:** To sum a numeric column, include the corresponding field in your query clause or column options. For examples, see [Query by a numeric field](query-numeric.md). + +### Limitations + +You can't group charts by the following field data types: +- **ID** or **Parent** fields +- **Date-time** fields (for example, **Created Date**, **Changed Date**) +- **Plain Text** fields (for example, **Title**) +- **Rich-text** fields (for example, **Description**, **Acceptance Criteria**, **Repro Steps**) +- **Tags:** You can filter queries using tags, but can't use them to configure query charts. + +> [!NOTE] +> While you can't group a query-based chart by tags, you can group a **Chart for Work Items** widget by tags added to a dashboard as described in [Configure a chart for work items widget](../../report/dashboards/configure-chart-work-items-widget.md). + +### Adding query charts to dashboards + +- **Create dashboard first:** To add a query chart to a dashboard, first create the dashboard. Then add the chart from the **Queries** > **Charts** page. +- **Refresh required:** After you add a query, refresh your browser to register the new query on the dashboard. +- **Optimize performance:** For complex queries, see [Best integration practices, Optimize queries](../../integrate/concepts/integration-bestpractices.md#optimize-queries). ## Maintain backlog hygiene -The following queries can help your team maintain a healthy backlog by ensuring that work is assigned. The following table provides some example queries to review periodically, usually at the beginning or end of a sprint. Review this list for what makes sense for your team and organization goals. Substitute the *Fabrikam Team* for your team and add other filters as needed. +The following queries help your team maintain a healthy backlog by ensuring that work is properly assigned. The following table provides example queries to review periodically, typically at the beginning or end of a sprint. Customize these queries to fit your team and organizational goals by replacing *Fabrikam Team* with your team name and adding other filters as needed. > [!NOTE] -> Work item types and workflow states applicable to your project may differ from those shown in the following examples depending on the process used by your project. - +> Work item types and workflow states applicable to your project might differ from those shown in the following examples depending on the process used by your project. :::row::: :::column span="1"::: @@ -90,7 +95,7 @@ The following queries can help your team maintain a healthy backlog by ensuring --- :::row::: :::column span="1"::: - **Unassigned work**: Work assigned to the current sprint but not assigned to a team member + **Unassigned work**: Work assigned to the current sprint but not assigned to a team member. :::column-end::: :::column span="3"::: :::image type="content" source="media/example-queries/query-no-assigned-to.png" alt-text="Screenshot of Query Editor, Assigned To field is blank for current iteration."::: @@ -114,15 +119,15 @@ The following queries can help your team maintain a healthy backlog by ensuring :::row-end::: :::row::: :::column span="1"::: - **Stale work**: Work items with no changes made in the last two to three months (query by **Changed Date**) + **Stale work**: Work items with no changes made in the last two to three months (query by **Changed Date**). :::column-end::: :::column span="3"::: - :::image type="content" source="media/example-queries/query-stale-work.png " alt-text="Screenshot of Query Editor, Active work not changed for past 3 months."::: + :::image type="content" source="media/example-queries/query-stale-work.png " alt-text="Screenshot of Query Editor, Active work not changed for past three months."::: :::column-end::: :::row-end::: :::row::: :::column span="1"::: - **Ill-defined work**: For example, ones with no **Description**, **Acceptance Criteria**, **Story Points**, or **Effort** defined + **Ill-defined work**: For example, ones with no **Description**, **Acceptance Criteria**, **Story Points**, or **Effort** defined. :::column-end::: :::column span="3"::: :::image type="content" source="media/example-queries/query-ill-defined-work.png " alt-text="Screenshot of Query Editor, Work with empty required fields."::: @@ -133,7 +138,6 @@ In the following image, all five query charts appear on a team dashboard. To add :::image type="content" source="media/example-queries/dashboard-backlog-hygiene-query-charts.png" alt-text="Screenshot of Dashboard with five query charts added."::: - Alternatively, you can add query tiles that reference the same query and show the total count of work items as shown in the following image. > [!NOTE] diff --git a/docs/boards/queries/high-performing-queries.md b/docs/boards/queries/high-performing-queries.md deleted file mode 100644 index 0289fdc7d70..00000000000 --- a/docs/boards/queries/high-performing-queries.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Learn how to create high-performing work item queries -titleSuffix: Azure Boards -description: Learn how to create high-performing work item queries in Azure Boards. -ms.custom: "boards-queries, linked-from-support" -ms.service: azure-devops-boards -ms.assetid: -ms.author: chcomley -author: chcomley -ms.topic: best-practice -monikerRange: '<= azure-devops' -ms.date: 01/31/2022 ---- - - -# Guidance to create high-performing queries in Azure Boards - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -While you can easily create work item queries, to create high-performing queries requires a deeper understanding. By improving your query performance, you improve your individual productivity, dashboard performance, and resource rate limits. - -> [!NOTE] -> Reference to service or resource rate limits only applies to queries run against Azure DevOps Services. For more information, see [Service limits and rate limits](../../user-guide/service-limits.md). - -This article provides general guidelines on how to write a high-performing query. These guidelines apply to the following queries you create: - -::: moniker range="azure-devops" -- [Web portal queries](view-run-query.md) -- [Work Item Query Language (WIQL) queries](wiql-syntax.md) -- [az boards query command line](view-run-query.md#run-a-query-from-the-command-line) -- [REST API queries](/rest/api/azure/devops/wit/queries) -::: moniker-end - -::: moniker range="< azure-devops" -- [Web portal queries](view-run-query.md) -- [Work Item Query Language (WIQL) queries](wiql-syntax.md) -- [REST API queries](/rest/api/azure/devops/wit/queries) -::: moniker-end - -## Create focused, selective queries - -The first guideline for a high-performing query is to define a highly selective query. To do this, apply all filters that are necessary for your query. The more selective the query is, the smaller the result set is. The smaller the result set is, the more targeted and selective your query is. - - -## Use tags to categorize work items - -Use [work item tags](add-tags-to-work-items.md) to categorize your work items instead of a custom field. Queries that filter on tags usually perform faster over those queries that filter on string matches. - -Unlike custom field matches or partial matches, a query with a `Tags Contains` operation doesn't require a complete scan of all work item tables. - -> [!div class="mx-imgBorder"] -> ![Filter on tags](media/high-perf/tag-contains-web.png) - - -## Use `Contains words` for string matches - -To filter on a string match, use the `Contains Words` instead of the `Contains` operator. The `Contains Words` operator runs a full-text search on the specified field, which tends to complete more quickly. - -The `Contains` operator runs a table scan, which is a slower operation than that used with the `Contains Words` operator. It also consumes more CPU cycles. These CPU cycles can cause you to encounter rate limitations. For more information, see [Service limits and rate limits](../../user-guide/service-limits.md) and [Rate limits](../../integrate/concepts/rate-limits.md). - - -## Specify small groups with the `In Group` operator - -The `In Group` operator filters work items based on matches within a group of values. The group of values correspond to those contained within a team, security group, or [work tracking category](../work-items/agile-glossary.md#categories). For example, you can create a query to find all work items that are assigned to any member of a team. Or, find all work items that belong to the requirements category (`Microsoft.RequirementCategory`). - -When you filter on a group that contains a large number of members, your result set tends to be larger and non-selective. Also, if a group corresponds to a large Azure Active Directory (Azure AD) group, the query generates a fairly large cost to resolve that group from Azure AD. - -## Avoid use of negated operators - -Negated operators—such as `<>, Not In, Not Under, Not In Group`—tend to generate non-selective queries and large result sets. - -Only use negated operators when absolutely necessary. Always try to find alternatives first. For example, if **Field1** has values *A*, *B*, *C*, *D*; specify the `Field1 In A, B, C` clause, instead of the negated `Field1 <> D` clause. - -## Avoid string comparisons - -Queries that contain string comparisons generate table scans that are inherently inefficient. Instead, we recommend you use tags or a specific custom field as alternatives, particularly when a query performs poorly. - -## Limit `Or` operators - -Try to limit the number of `Or` operators defined in your query. Queries run better when fewer `Or` operators are used. Too many `Or` operators can make your query non-selective. If your query runs slowly, reorder the `Or` operator clause towards the top of the query clauses. - - -## Save your query - -Save your query to improve query performance. Due to internal optimizations, saved queries tend to perform better over unsaved queries. Always save your query when you plan to reuse it. Even WIQL queries run through a REST API, save the WIQL through the web portal to make your REST API calls less prone to future performance regressions. - -## Run your query - -Sometimes your query needs to be run a few times to reach the right optimization plan. Make sure your query is saved and run that query up to 10 times over a 30 minute period. This allows the system to examine and seek out the optimization plan that is most appropriate for your query. - -[!INCLUDE [temp](../includes/rest-apis-queries.md)] - -## Related articles - -- [Service limits and rate limits](../../user-guide/service-limits.md) -- [Create managed queries](using-queries.md) -- [Query fields, operators & macros](query-operators-variables.md) -- [WIQL syntax](wiql-syntax.md) -- [Query quick reference](query-index-quick-ref.md) -- [az boards query command](/cli/azure/boards#az-boards-query) \ No newline at end of file diff --git a/docs/boards/queries/history-and-auditing.md b/docs/boards/queries/history-and-auditing.md index 6b61096d865..da8b434eeba 100644 --- a/docs/boards/queries/history-and-auditing.md +++ b/docs/boards/queries/history-and-auditing.md @@ -1,50 +1,61 @@ --- -title: Query work items by history in Azure Boards +title: Query work items by history titleSuffix: Azure Boards description: Learn how to query work item history and comments to support audit requirements when working in Azure Boards. ms.service: azure-devops-boards -ms.custom: boards-queries, contperf-fy23 +ms.custom: boards-queries, engagement-fy23 ms.assetid: A5AC271A-8DF0-40AD-9867-1B1E9E5B1FE9 +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: example-scenario monikerRange: '<= azure-devops' -ms.date: 12/16/2022 +ms.date: 11/26/2024 --- -# Query work item history and discussion fields in Azure Boards +# Query work item history and discussion fields [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The history of a work item tells you who opened the item, what changed, and why. This information helps you track how an item changes over time. When you enter information in the history field, provide as much information as possible to help the next work item owner understand what has happened and what they have to do. +The history of a work item records who created the item, what changes were made, and the reasons behind those changes. This information is essential for tracking the evolution of an item over time. When adding entries to the history field, include detailed information to help the next work item owner understand the context of the changes and the actions required. -> [!NOTE] -> There is no **Discussion** work item field. To query work items with comments entered in the Discussion area, you filter on the **History** field. The full content of the text entered into the Discussion text box is added to the History field. +> [!NOTE] +> There is no separate **Discussion** work item field. To query work items with comments from the Discussion area, filter on the **History** field. All text entered into the Discussion box is automatically included in the History field. -## Supported operators and macros +## Prerequisites -Query clauses that specify the **History** field can use the **Contains Words** and **Does Not Contain Words** operators. Search against an exact phrase or to use the wildcard character, *. You can only use the wildcard character at the end of a partial word or phrase. +[!INCLUDE [prerequisites-queries](../includes/prerequisites-queries.md)] -The **History** field is automatically indexed for full-text search when full-text search is available. See Full-Text and partial word searches +## Supported operators and macros - +- **Supported operators:** + - **Contains Words** + - **Does Not Contain Words** + +- **Search methods:** + - **Exact phrase:** Locate an exact sequence of words. + - **Wildcard character (`*`):** Use only at the end of a partial word or phrase. + +- **Full-text search:** The **History** field is automatically indexed for full-text search when available. + + ## Query a work item's history -You can use either the web portal or Team Explorer to view the history of a work item or find work items based on the contents of the **History** field. When you run a search on the contents of the **History** field, it returns only work items that have changes recorded in that field. That is, it doesn't register changes that were made to text in other fields. +You can use the web portal or Team Explorer to view a work item's history or search for work items based on the **History** field. Searching the **History** field returns only work items with changes recorded in that field and does not include changes made to other fields. #### [Browser](#tab/browser/) - + :::image type="content" source="media/hist-audit-query-ts-bt.png" alt-text="Screenshot of Query Editor to Search for items based on words contained in the History field."::: #### [Visual Studio](#tab/visual-studio/) - - + + -The **Query Editor** isn't available when you're connected to GitHub or third-party Git repository. Also, it isn't available from Visual Studio 2019 under the following conditions: +The **Query Editor** isn't available when you're connected to GitHub or non-Microsoft Git repository. Also, it isn't available from Visual Studio 2019 under the following conditions: * If you're set to use the default Landing page experience as described in [Set the Work Items experience in Visual Studio 2019](../work-items/set-work-item-experience-vs.md). * If you're set to use the new Git Tool as described in [Git experience in Visual Studio](/visualstudio/ide/git-with-visual-studio). @@ -55,9 +66,12 @@ The **Query Editor** isn't available when you're connected to GitHub or third-pa ## List items based on the contents of the History field -You use the query editor to add the **History** field to a [query clause](using-queries.md). Comments entered into the **Discussion** area are queryable. Change history entries, such as which fields were changed, aren't queryable. To quickly find items based on words entered into the Discussion area, or **Description** or other rich-text fields, consider using [work item search](../../project/search/functional-work-item-search.md). +Use the query editor to include the **History** field in a [query clause](using-queries.md). -You can filter for work items by the date on which they were changed or for a specific time period. If you limit the scope of your query, it can help with performance by only returning those results that fit the date range that you want to include. +- **Queryable content:** Comments entered in the **Discussion** area. +- **Non-queryable content:** Change history entries, such as modifications to fields, aren't queryable. +- **Alternative search methods:** To search for words in the **Discussion**, **Description**, or other rich-text fields, use [work item search](../../project/search/functional-work-item-search.md). +- **Filter by Change Date:** Filter work items by the date they were changed or specify a particular time period. :::row::: :::column span="1"::: @@ -78,7 +92,7 @@ You can filter for work items by the date on which they were changed or for a sp :::row-end::: :::row::: :::column span="1"::: - Items whose History field doesn't contain the word "beta" + Items whose History field doesn't contain the word "beta" :::column-end::: :::column span="1"::: `History Does Not Contain Words beta` @@ -105,8 +119,7 @@ You can filter for work items by the date on which they were changed or for a sp :::row-end::: :::row::: :::column span="1"::: - - Items I've been associated with + Items I've been associated with :::column-end::: :::column span="1"::: `History Contains Words MyName` @@ -117,27 +130,37 @@ You can filter for work items by the date on which they were changed or for a sp ### Tips for using the query editor -- Enter the complete word or phrase that is specified in the **History** field of those work items that you want to find. -- Enter the full text for the word that you want to search. The **History** field is indexed for full-text search. If you enter only a partial word, the query won't return work items that contain the full word. For example, if the **History** field contains the phrase *reproducible behavior* and you search for *repro*, the work item won't be found. However, if you search for the complete word *reproducible*, the work item can be found. You can also search for the string with a wild card, such as `repro*`. -- The query editor ignores common words or stop words as defined in [Configure and Manage Stopwords and Stoplists for Full-Text Search](/sql/relational-databases/search/configure-and-manage-stopwords-and-stoplists-for-full-text-search). -- On the query editor toolbar, choose ![Run query](../media/icons/run_query.png) or ![Run query, earlier version](../media/icons/run_query_te.png) icon and confirm that your query returns expected results. -- If you don't receive the results you expect, adjust the word or phrase that you entered, and run the query again. - +- **Limit query scope by date range:** Narrow the date range to improve performance and return only relevant results. + +- **Use complete words or phrases:** + - Enter full words or exact phrases from the **History** field. + - Partial words don't return work items. For example: + - Searching for "reproducible behavior" finds the item. + - Searching for "repro" doesn't find it. + - Use wildcards at the end of words or phrases, such as `repro*`. +- **Be aware of "stop" words:** + - The query editor ignores common words. + - For more information, see [Configure and Manage Stopwords and Stoplists for Full-Text Search](/sql/relational-databases/search/configure-and-manage-stopwords-and-stoplists-for-full-text-search). - +- **Run and validate your query:** + - Select ![Run query](../media/icons/run_query.png) or ![Run query, earlier version](../media/icons/run_query_te.png) in the query editor toolbar. + - Ensure the query returns the expected results. + - If results are missing, adjust your search terms and run the query again. + + ## View the history of work items -An entry is made to the **History** field each time a work item is saved. To view the history of changes, open an existing work item, and then choose the ![history tab icon](../media/icons/icon-history-tab-wi.png) or **History** tab, or for some work item types, choose the **Details** tab. +An entry gets made to the **History** field each time a work item is saved. To view the history of changes, open an existing work item, and then choose the ![history tab icon](../media/icons/icon-history-tab-wi.png) or **History**, or for some work item types (WITs), choose **Details**. - -The history details shown depend on the platform, version, and client. + +The history details shown depend on the platform, version, and client. #### [Browser](#tab/browser/) - - + + :::image type="content" source="media/hist-audit-wi-form-vsts-tab.png" alt-text="Screenshot of Work item form, Web portal, Choose History tab."::: @@ -145,7 +168,7 @@ The state change history diagram appears first. To see the entire history of sta :::image type="content" source="media/state-change-history-diagram.png" alt-text="Screenshot of Work item form, Web portal, State change history diagram (web portal only)."::: -Choose an entry in the left pane to view the details of changes made. +Choose an entry in the left pane and view the details of changes made. :::image type="content" source="media/hist-audit-wi-form.png" alt-text="Screenshot of Work item form, History tab, Web portal, Details."::: @@ -157,7 +180,7 @@ To view only the comments that were added to the log, choose the **Discussion On * * * - + ::: moniker range="azure-devops" @@ -167,11 +190,7 @@ To view only the comments that were added to the log, choose the **Discussion On The **History** tab is designed to track all changes made to a work item to support full traceability. The long revision history that results can make it difficult to understand when changes happen to specific fields. To quickly find revisions made to a specific field or by specific people, filter the history view. > [!NOTE] -> The **Toggle filter** feature requires you to enable the **New Boards Hub** preview feature. To enable this feature, see [Manage or enable features](../../project/navigation/preview-features.md). - -You enable the filter feature by choosing :::image type="icon" source="media/history-audit/filter-icon.png" border="false"::: **Toggle filter**. - -:::image type="content" source="media/history-audit/history-filter.png" alt-text="Screenshot of Work item form, History tab, Web portal, history filter enabled."::: +> The **Toggle filter** feature requires the **New Boards Hub** feature, which is enabled by default. For more information, see [Manage or enable features](../../project/navigation/preview-features.md). To review updates by specific people, select their names from the **Updated by** menu. @@ -183,14 +202,12 @@ To review updates made to one or more fields, select the fields from the **Field ::: moniker-end - - + ## Fields that support history, auditing, and revision tracking You can use the following fields to filter queries and create reports. Several of these fields are populated with information as a work item progresses from one state to another. Other fields update when the work item is modified. Some fields don't appear on the work item form, but they're tracked for the WITs listed. - :::row::: :::column span="1"::: **Field name** @@ -210,7 +227,7 @@ You can use the following fields to filter queries and create reports. Several o :::column span="2"::: The name of the team member who modified the work item most recently. - Reference name=System.ChangedBy, Data type=String + `Reference name=System.ChangedBy, Data type=String` :::column-end::: :::column span="1"::: All @@ -223,7 +240,7 @@ You can use the following fields to filter queries and create reports. Several o :::column span="2"::: The date and time when a work item was modified. - Reference name=System.ChangedDate, Data type=DateTime + `Reference name=System.ChangedDate, Data type=DateTime` :::column-end::: :::column span="1"::: All @@ -235,7 +252,7 @@ You can use the following fields to filter queries and create reports. Several o :::column-end::: :::column span="2"::: The date and time when a work item was closed. - Reference name=Microsoft.VSTS.Common.ClosedDate, Data type=DateTime + `Reference name=Microsoft.VSTS.Common.ClosedDate, Data type=DateTime` :::column-end::: :::column span="1"::: All @@ -248,7 +265,7 @@ You can use the following fields to filter queries and create reports. Several o :::column span="2"::: The date and time when a work item was created. - Reference name=System.CreatedDate, Data type=DateTime + `Reference name=System.CreatedDate, Data type=DateTime` :::column-end::: :::column span="1"::: All @@ -259,15 +276,15 @@ You can use the following fields to filter queries and create reports. Several o History :::column-end::: :::column span="2"::: - The record of changes that were made to the work item after it was created. Every time that the work item is updated, information is appended to the history, which specifies the date of the change, who made the changes, and which fields were changed. + The record of changes that were made to the work item after it was created. Every time the work item gets updated, information appends to the history, which specifies the date of the change, who made the changes, and which fields were changed. > [!NOTE] > History field queries return work items whose **Discussion** comments or **Description** fields contain words that match the keywords entered. You can't use the History field to query on changes made to other fields. - You can't add formatted text to the history field. Once you've saved the work item, you can't alter the history. + You can't add formatted text to the history field. Once you save the work item, you can't alter the history. The `History` field, along with the `Description`, `Steps to Repro` and `Title` fields are automatically indexed for full-text search as described in [Query fields, operators, and macros](query-operators-variables.md). - Reference name=System.History, Data type=History + `Reference name=System.History, Data type=History` :::column-end::: :::column span="1"::: All @@ -280,7 +297,7 @@ You can use the following fields to filter queries and create reports. Several o :::column span="2"::: The date and time when the work item was moved into a Resolved state. - Reference name=Microsoft.VSTS.Common.ResolvedDate, Data type=DateTime + `Reference name=Microsoft.VSTS.Common.ResolvedDate, Data` type=DateTime :::column-end::: :::column span="1"::: Bug (Agile, CMMI) @@ -291,11 +308,11 @@ You can use the following fields to filter queries and create reports. Several o Rev :::column-end::: :::column span="2"::: - A number that is assigned to the historical revision of a work item. - > [!NOTE] - > A work item revision limit of 10,000 is in effect for updates made through the REST API for Azure DevOps Services. This limit restricts updates from the REST API, however, updates from the web portal are not affected. + A number that is assigned to the historical revision of a work item. + > [!NOTE] + > A work item revision limit of 10,000 is in effect for updates made through the REST API for Azure DevOps Services. This limit restricts updates from the REST API, however, updates from the web portal are not affected. - Reference name=System.Rev, Data type=Integer + `Reference name=System.Rev, Data type=Integer` :::column-end::: :::column span="1"::: All @@ -308,7 +325,7 @@ You can use the following fields to filter queries and create reports. Several o :::column span="2"::: The date and time when a work item was revised or modified. - Reference name=System.RevisedDate, Data type=DateTime + `Reference name=System.RevisedDate, Data type=DateTime` :::column-end::: :::column span="1"::: Shared Parameter, Shared Step, Test Case @@ -321,7 +338,7 @@ You can use the following fields to filter queries and create reports. Several o :::column span="2"::: The date and time when the value of the State field changed. - Reference name=Microsoft.VSTS.Common.StateChangeDate, Data type=DateTime + `Reference name=Microsoft.VSTS.Common.StateChangeDate, Data type=DateTime` :::column-end::: :::column span="1"::: All @@ -332,8 +349,9 @@ You can use the following fields to filter queries and create reports. Several o Test Suite Audit :::column-end::: :::column span="2"::: - Tracks other operations performed when modifying a test suite, for example: adding tests to a test suite or changing configurations. This field can be viewed through the History tab or through a separate query. There's a consolidated history view, including changes performed to work items field and changes resulting from related artifacts such as test points and configurations. - Reference name=Microsoft.VSTS.TCM.TestSuiteAudit, Data type=PlainText + Tracks other operations performed when modifying a test suite, for example, adding tests to a test suite or changing configurations. This field can be viewed through the History tab or through a separate query. There's a consolidated history view, including changes performed to work items field and changes resulting from related artifacts such as test points and configurations. + + `Reference name=Microsoft.VSTS.TCM.TestSuiteAudit, Data type=PlainText` :::column-end::: :::column span="1"::: Test Suite @@ -345,7 +363,8 @@ You can use the following fields to filter queries and create reports. Several o :::column-end::: :::column span="2"::: A system-managed field (not editable) that increments with changes made to a work item. - Reference name=System.Watermark, Data type=Integer + + `Reference name=System.Watermark, Data type=Integer` :::column-end::: :::column span="1"::: All @@ -353,23 +372,20 @@ You can use the following fields to filter queries and create reports. Several o :::row-end::: -> [!NOTE] -> 1. For these fields to be defined for a WIT, they must be included in the `WORKFLOW` section of the WIT definition. For example, this syntax is included within the `FIELDS` definition when transitioning to a Resolved state: +> [!NOTE] +> 1. These fields must be included in the `WORKFLOW` section of the WIT definition. For example, this syntax is included within the `FIELDS` definition when transitioning to a Resolved state: > > ```xml -> -> -> -> ``` +> +> +> +> ``` ## Related articles -- [Query editor](using-queries.md) +- [Use the query editor](using-queries.md) - [Query fields, operators, and macros](query-operators-variables.md) - [Query by date or current iteration](query-by-date-or-current-iteration.md) [!INCLUDE [temp](../includes/rest-apis-queries.md)] - - - diff --git a/docs/boards/queries/import-work-items-from-csv.md b/docs/boards/queries/import-work-items-from-csv.md index 7bd9375f7b7..722d62823bd 100644 --- a/docs/boards/queries/import-work-items-from-csv.md +++ b/docs/boards/queries/import-work-items-from-csv.md @@ -1,45 +1,59 @@ --- -title: Import update bulk work items with CSV files +title: Import, update, and export bulk work items with CSV files titleSuffix: Azure Boards -description: Learn how to import or update work items in bulk from a CSV formatted file. +description: Learn how to import, update, and export work items in bulk from a CSV formatted file in Azure Boards. ms.custom: "boards-queries, linked-from-support" ms.service: azure-devops-boards +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: how-to -monikerRange: ">= azure-devops-2019" -ms.date: 06/06/2023 +monikerRange: "<=azure-devops" +ms.date: 11/26/2024 +#customer intent: As a team member, I want to import and export work items in CSV format to create or update them in bulk by using Excel. --- -# Import & update bulk work items with CSV files +# Import, update, and export bulk work items with CSV files in Azure Boards [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -::: moniker range="> azure-devops-2019" -Import and export work items in bulk using a CSV formatted file in Azure DevOps. While you can continue to use Excel for bulk import and updates, you can use the native import/export feature that doesn't require Excel. For more information, see [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). +::: moniker range="<=azure-devops" +Import and export work items in bulk using CSV-formatted files in Azure Boards. While you can continue to use Excel for bulk imports and updates, the native import/export feature allows you to manage work items without requiring Excel. For more information, see [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). ::: moniker-end -::: moniker range="azure-devops-2019" -You can export of work items in bulk using a CSV formatted file. While you continue to use Excel for bulk import and updates, you can use the native export feature from Queries that doesn't require Excel. For more information, see [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). -::: moniker-end +## Prerequisites -> [!NOTE] -> The **export** feature is available with [Azure DevOps Server 2019 Update 1](https://go.microsoft.com/fwlink/?LinkId=2097609) and later versions. The **import** feature is available with Azure DevOps Server 2020 and Azure DevOps Services. +**Permissions**: +- Export work items: Member of the **Project Administrators** group or **View project-level information** permission set to **Allow**. +- Import work items: Member of the **Project Administrators** or **Team Foundation Administrators** security group. ::: moniker range=">= azure-devops-2020" ## Import new work items -All work items that you import get created in a *New* state. This rule means that you can't specify field values that don't meet the field rules for the new state. For example, when you create a new user story with the Agile process, the *State* = *New* and the *Reason* = *New*. You can't specify any other values. +To import work items in bulk, your CSV file must include the **Work Item Type** and **Title** fields. You can include more fields as needed. Follow these guidelines to import a CSV file: + +- **Exclude the ID field:** Don't include the **ID** field in your CSV file. +- **Remove project-specific fields:** If the CSV file was exported from a different project, remove fields specific to the source project, such as **Area Path** and **Tags**. For a list of default fields, see [Work Item Field Index](../work-items/guidance/work-item-field.md). +- **Include the Test Steps field:** When importing test cases, include the **Test Steps** field. For more information, see [Bulk Import or Export Test Cases](../../test/copy-clone-test-items.md). +- Don't include **Assigned To**, **Changed Date**, **Created By**, or **State** fields. +- **Validate required fields:** + - Ensure the **Work Item Type** and **Title** fields are present in the CSV file. + - Confirm that the **Work Item Type** corresponds to a valid type in the target project. + - Verify that all fields in the CSV file match the fields for the work item types in the target project. +- **Handle invalid values:** If the imported CSV file contains work items with invalid values, you must edit and correct these work items after import before they can be saved. -1. Create a local ***import.csv*** file and open it in Visual Studio Code or Excel. +Do the following steps to import new work items. +> [!NOTE] +> You can import up to 1,000 work items at a time. If you have more than 1,000 work items to import, break them into multiple files and import them separately. + +1. Create a local *import.csv* file and open it in Visual Studio Code or Excel. 2. The file must contain the **Work Item Type** and the **Title** fields. You can include other fields as needed. For a list of default fields, see [Work item field index](../work-items/guidance/work-item-field.md). - In the following example, we include the **Priority** field. + The following example includes the **Priority** field. - > [!div class="tabbedCodeSnippets"] - ```CSV + ```csv Work Item Type,Title,Priority Issue,Fix issues with code,1 Issue,Merge testing modules,3 @@ -48,111 +62,157 @@ All work items that you import get created in a *New* state. This rule means tha Issue,Remove old test code,2 ``` -3. From the web portal for your project, open **Boards** > **Queries**, and then select the **Import Work Items** option. +3. From the web portal for your project, select **Boards** > **Queries** > **Import work items**. + + :::image type="content" source="media/import-csv/open-queries-import.png" alt-text="Screenshot showing the Boards page with Queries, then Import work items selected."::: - :::image type="content" source="media/import-csv/open-queries-import.png" alt-text="Screenshot showing Boards - Queries, Import Work Items."::: +4. Select **Choose file**, choose your file, and then select **Import**. -4. Select your CSV file and then choose **Import**. + :::image type="content" source="media/import-csv/import-file.png" alt-text="Screenshot showing Import work items dialog with the Import button highlighted."::: - :::image type="content" source="media/import-csv/import-file.png" alt-text="Screenshot showing Import Work Items Button Image."::: + The import process loads the imported work items into the queries view in an **unsaved** state. No IDs get assigned. - The import process loads the imported work items into the queries view in an **unsaved** state. No IDs get assigned. - 5. Verify the results and then select **Save items** to save the work items. - :::image type="content" source="media/import-csv/imported-file.png" alt-text="Screenshot showing Save button for imported work items."::: + :::image type="content" source="media/import-csv/imported-file.png" alt-text="Screenshot showing Save items for imported work items."::: + + > [!TIP] + > Don't assign IDs to new work items that you add. Assigning IDs results in an error message. + +6. The system highlights those work items with data issues. Resolve the data issues before you save the work items. In this example, an invalid value is in the Priority field. Fix the data by opening the work item directly. Instead, use [bulk edit](../backlogs/bulk-modify-work-items.md) to fix several work items with the same issue. + + :::image type="content" source="media/import-csv/imported-file-error.png" alt-text="Screenshot showing work items with data issues to fix."::: + +### Tips - > [!NOTE] - > Don't assign IDs to new work items that you're adding, otherwise you receive an error message similar to the following if you do so. - > :::image type="content" source="media/import-csv/import-work-item-ids-assigned.png" alt-text="Screenshot of Error message of work item ID."::: +- **Parent-child links:** You can add parent-child links between work items you import by indenting the title columns, as shown in [Can I import a CSV file that have parent-child links?](#tree-items). However, you can't specify any other link types when you import or update work items. +- **Default State field:** When you import new work items, the **State** field is set to *New* by default. You can't specify a different state during the import process. If you need to change the state of imported work items, use the following workaround: -6. The system highlights those work items with data issues. Resolve the data issues before you save the work items. In this example, an invalid value has been entered into the Priority field. Fix the data by opening the work item directly. Instead, use [bulk edit](../backlogs/bulk-modify-work-items.md) to fix several work items with the same issue. + 1. Import the work items with the default *New* state. + 1. Export the imported work items to a CSV file. + 1. Update the **State** field values in the exported CSV file. + 1. Reimport the updated CSV file to set the desired states. - :::image type="content" source="media/import-csv/imported-file-error.png" alt-text="Screenshot showing fix work items with data issues."::: +- **Default Area and Iteration fields:** The **Area** and **Iteration** fields default to the top-level node. This behavior occurs because the import process doesn't have the context for these fields unless explicitly specified in the CSV file. To set specific **Area** and **Iteration** paths during import, ensure these fields are included in your CSV file with the correct values. For example: -> [!TIP] -> You can add parent-child links between work items you import by indenting the title columns as shown in the example later in this article, [Can I import a CSV file that have parent-child links?](#tree-items). However, you can't specify any other link types when importing or updating work items. + ```csv + Title,Description,Area Path,Iteration Path + "Sample Work Item","This is a sample description.","Project\Team","Project\Sprint 1" + ``` ## Update existing work items -1. To update work items, create a query that contains all the columns you want to export and possibly edit. Save your query and select **Export to CSV** to save the data.csv file to your local machine. +1. To update work items, create a query that contains all the columns you want to export and possibly edit. Save your query and select **Export to CSV** to save the *data.csv* file to your local machine. - :::image type="content" source="media/import-csv/export-query.png" alt-text="Screenshot showing export work items, CSV."::: + :::image type="content" source="media/import-csv/export-query.png" alt-text="Screenshot showing work items in a query with the option to Export to CSV selected."::: - The exported file should look similar to the following syntax: + The exported file should look similar to the following example: - > [!div class="tabbedCodeSnippets"] - ```CSV - ID,Work Item Type,State,Assigned To,Title,Tags - "1043","Issue","To Do",,"Fix issues with code", - "1044","Issue","To Do",,"Merge testing modules", - "1045","Issue","To Do",,"Open private preview for select customers", - "1046","Issue","To Do",,"Enable feature for customer champs", - "1047","Issue","To Do",,"Remove old test code", - ``` + ```csv + ID,Work Item Type,Title,Assigned To,State,Tags + "272","Issue","Fix issues with code","Active","", + "273","Issue","Merge testing modules","Active","", + "274","Issue","Open private preview for select customers","Active","", + "275","Issue","Enable feature for customer champs","Active","", + "276","Issue","Remove old test code","Active","", + ``` -2. Make the edits to your work items. Your CSV file must contain the **ID**, **Work Item Type**, **Title**, and **State** fields. Any other fields you want to include are optional. +1. Make the edits to your work items. Your CSV file must contain the **ID**, **Work Item Type**, and **Title** fields. Any other fields you want to include are optional. - > [!NOTE] - > When you import identity fields, enter the name and email in the following format `"Display Name "`. For example, to assign work to Jamal Hartnett, specify `"Jamal Hartnett "`. If you specify a value that isn't recognized as a valid user to the system, you may encounter problems with the import. + > [!NOTE] + > When you import identity fields, enter the name and email in the following format `"Display Name "`. For example, to assign work to Jamal Hartnett, specify `"Jamal Hartnett "`. If you specify a value that isn't recognized as a valid user to the system, you may encounter problems with the import. - In the following example, we change several values on existing working items. + In the following example, we change values on existing working items. - ```ID,Work Item Type,State,Assigned To,Title,Tags - "1043","Issue","To Do","Jamal Hartnett ","Fix issues with code",architecture - "1044","Issue","To Do","Jamal Hartnett ","Merge testing modules",testing - "1045","Issue","To Do","Raisa Pokrovskaya ","Open private preview for select customers","customer focus" - "1046","Issue","To Do","Raisa Pokrovskaya ","Enable feature for customer champs","customer focus" - "1047","Issue","To Do","Christie Church ","Remove old test code",architecture``` + ```csv + ID,Work Item Type,Title,Assigned To,State,Tags + "272","Issue","Fix issues with code","Jamal Hartnett ","Active", + "273","Issue","Merge testing modules","Jamal Hartnett ","Active", + "274","Issue","Open private preview for select customers","Raisa Pokrovskaya ","Active", + "275","Issue","Enable feature for customer champs","Raisa Pokrovskaya ","Active", + "276","Issue","Remove old test code","Christie Church ","Active", + ``` -3. Save the file and import (see steps 4-6 from the previous [import section](#import-new-work-items).) +1. Save the file and import, as described in the previous section. -4. The results list with work items that contain value changes appear highlighted in bold. Select **Save Items** to apply the changes. +1. The results list with work items that contain value changes appear highlighted in bold. Select **Save Items** to apply the changes. - :::image type="content" source="media/import-csv/bulk-update-import.png" alt-text="Screenshot showing Import Work Items, Save Items."::: + :::image type="content" source="media/import-csv/bulk-update-import.png" alt-text="Screenshot showing Import Work Items with the option to Save items."::: -5. Work items with data issues get highlighted in red and must be resolved before you can save them. In this example, an invalid value appears in the Assigned To field. Fix the data by opening the work item directly. You can use bulk edit if you have many work items with the same issue. +1. Work items with data issues get highlighted in red and must be resolved before you can save them. In this example, an invalid value appears in the Assigned To field. Fix the data by opening the work item directly. You can use bulk edit if you have many work items with the same issue. - :::image type="content" source="media/import-csv/import-update-error-1.png" alt-text="Screenshot showing Invalid value appearing in the Assigned To field."::: + :::image type="content" source="media/import-csv/import-update-error-1.png" alt-text="Screenshot showing an invalid value appearing in the Assigned To field."::: ::: moniker-end -::: moniker range=">= azure-devops-2019" - ## Export list as a CSV file From any query, you can export a list of work items as a comma-delimited list. [Open the query](view-run-query.md), select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon, and then select **Export to CSV**. -::: moniker-end - -::: moniker range="azure-devops-2019" -> [!NOTE] -> Requires Azure DevOps Server 2019 Update 1 or later version. -::: moniker-end - -::: moniker range=">= azure-devops-2019" -:::image type="content" source="../work-items/media/email/export.png" alt-text="Screenshot showing Export a query as CSV."::: -::: moniker-end +:::image type="content" source="../work-items/media/email/export.png" alt-text="Screenshot showing Export a query as CSV."::: ::: moniker range=">= azure-devops-2020" ## Export and import work items to a different project -You can use this feature to export work items from one project and import them to another project. However, before you import them to another project, you must remove the work item ID. You get an error if you attempt to import new work items to a project with an ID specified. +You can use this feature to export work items from one project and import them to another project. But, before you import them to another project, you must remove the work item ID. You get an error if you attempt to import new work items to a project with an ID specified. +::: moniker-end + +## Import HTML fields -## Import or update rich-text fields +HTML fields, such as descriptions and acceptance criteria, include rich text formatting. To ensure this formatting is preserved, do the following tasks: -You can update or import rich-text fields such as the **Description** or **Acceptance Criteria** fields. Rich-text fields are HTML formatted fields. Replace lines ending in CRLF by surrounding sentences with `

...

`. +1. Ensure your CSV file includes HTML tags within the relevant fields. +1. Import the CSV file into Excel. -For example, you can import the following work item, which includes three lines of text in the Description field. +Excel might handle multi-line text fields differently, so it's important to check the formatting after import. Replace lines ending in `CRLF` by surrounding sentences with `

...

`. -> [!div class="tabbedCodeSnippets"] -```CSV +For example, you can import the following work item, which includes three lines of text in the **Description** field. + +```csv Work Item Type,Title,Description "Product Backlog Item","Hello World Web Site - 8","

 You can include bold text

 And italic text

 Underline text

" ``` -::: moniker-end +## Convert multi-line fields to plaintext + +To disable HTML in multi-line fields to ensure that they're plaintext, use the `witadmin changefield` command. For more information, see [Manage Work Item Fields](../../reference/witadmin/manage-work-item-fields.md). + +Example command: + +```cmd +witadmin changefield /collection:CollectionURL /n:FieldName /type:PlainText +``` + +## Handle formatting inconsistencies + +When you work with HTML fields across different Microsoft products, you might encounter formatting inconsistencies. Here are some tips to handle these issues: + +- Review the formatting after importing to ensure it meets your requirements. +- Use appropriate HTML tags and structures to minimize discrepancies. You can add multiple tags separated by a semicolon. For more information, see [Tasks you can and can't do with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). + +For more information on managing HTML content and ensuring compatibility, see [Provide help text, hyperlinks, or web content on a work item form](../../reference/xml/provide-help-text-hyperlinks-web-content-form.md). + +::: moniker range=">= azure-devops-2020" + +## Unsupported work item types + +The CSV import doesn't support the following work item types: + +- Code Review Request +- Code Review Response +- Feedback Request +- Feedback Response +- Test Case +- Test Plan +- Test Suite +- Shared Parameter + +- Shared Step + +For more information, see [Bulk import or export test cases](../../test/copy-clone-test-items.md). + +::: moniker-end ::: moniker range=">= azure-devops-2020" @@ -162,8 +222,7 @@ Work Item Type,Title,Description A: Absolutely! Leave the ID field empty for any new work items. In the following example, the last entry for an Epic doesn't specify an ID. -> [!div class="tabbedCodeSnippets"] -```CSV +```csv ID,Work Item Type,Title,Assigned To,State,Priority,Tags "16504","Issue","Fix issues with code",,"To Do","1", "16505","Issue","Merge testing modules",,"To Do","3", @@ -173,17 +232,12 @@ ID,Work Item Type,Title,Assigned To,State,Priority,Tags ,"Epic","Track Telemetry for data imports",,"To Do","2", ``` -### Q: How do I add multiple tags? - -A: You can add multiple tags separated by a semicolon. For more information, see [Tasks you can and can't do with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). - - + ### Q: Can I import a CSV file that has parent-child links? A: Yes, you can add child work items by indenting title columns. The following example adds three child issues under the already defined Epic. -> [!div class="tabbedCodeSnippets"] ```CSV ID,Work Item Type,Title 1,Title 2,Assigned To,State,Priority,Tags "165","Epic","Track Telemetry for data imports",,,"To Do","2", @@ -192,41 +246,26 @@ ID,Work Item Type,Title 1,Title 2,Assigned To,State,Priority,Tags ,"Issue",,"Enable feature for customer champs",,"To Do","2", ``` -> [!div class="mx-imgBorder"] -> ![Screenshot showing Excel view.](media/import-csv/import-add-child-items.png) +:::image type="content" source="media/import-csv/import-add-child-items.png" alt-text="Screenshot showing Excel view."::: ### Q: How do I know if my imported file has errors? A: You can test by adding tags with spaces and hyphens, for example, and include it in the export. The import should match the same format. Any problems with the formatting of your CSV file appear in the Results page of the import view. You can't import the work items until the formatting and syntax is correct. -> [!div class="mx-imgBorder"] -> ![CSV Error image](media/import-csv/import-error.png) +:::image type="content" source="media/import-csv/import-error.png" alt-text="Screenshot showing a CSV Error in the Import Work Items page."::: The work item results always list the data errors found for individual work items. Fix each error either from the web portal, or in the CSV file and import again. ### Q: Why am I getting errors for some identity values? -A: When you use the Web UI, the identity picker goes through extra steps to validate the user. First it checks to see if the person is a valid user in the org. If not, it searches on the identity in Azure Active Directory (Azure AD). If the user's in Azure AD but not in the org, that user gets added to the valid identities. When you import via CSV, for performance reasons, the identity picker doesn't go through these extra steps. It only checks to see if there's a matching UPN already in the org. If it doesn't find a matching UPN, it reports that the identity is unknown. - -### Q: Does CSV import support all work item types? - -A: No, the CSV import doesn't support the following work item types: - -- Code Review Request -- Code Review Response -- Feedback Request -- Feedback Response -- Test Case -- Test Plan -- Test Suite -- Shared Parameter +A: When you use the Web UI, the identity picker goes through extra steps to validate the user. First it checks to see if the person is a valid user in the org. If not, it searches on the identity in Microsoft Entra ID. If the user's in Microsoft Entra ID but not in the org, that user gets added to the valid identities. -For more information, see [Bulk import or export test cases](../../test/copy-clone-test-items.md#bulk-import-or-export-test-case). +When you import from CSV, for performance reasons, the identity picker doesn't go through these extra steps. It only checks to see if there's a matching User Principal Name (UPN) already in the org. If it doesn't find a matching UPN, it reports that the identity is unknown. ::: moniker-end ## Related articles -- [Work item field index](../work-items/guidance/work-item-field.md) -- [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) -- [FAQs: Work in Excel connected to Azure Boards](../backlogs/office/faqs.yml) +- [Access the Work Item Field Index](../work-items/guidance/work-item-field.md) +- [Bulk Add or Modify Work Items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) +- [Consult FAQs: Work in Excel Connected to Azure Boards](../backlogs/office/faqs.yml) diff --git a/docs/boards/queries/link-type-reference.md b/docs/boards/queries/link-type-reference.md index e3a59fc4532..fec1974487b 100644 --- a/docs/boards/queries/link-type-reference.md +++ b/docs/boards/queries/link-type-reference.md @@ -9,70 +9,53 @@ ms.author: chcomley author: chcomley ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 10/18/2022 +ms.date: 11/15/2023 --- - -# Reference guide for link types used in Azure DevOps and Azure Boards +# Reference guide for link types [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can use different link types to manage the various relationships between work items and other artifacts, like builds, commits, pull requests, and more. - -You can link work items to other work items or artifacts using the following link types. +You can use different link types to manage the various relationships between work items and other artifacts, like builds, commits, pull requests, and more. In this article, we describe the following link types. ::: moniker range="azure-devops" -- [**Work link types**](#work-link-types): links work items including select test case management work items -- [**Hyperlink**](#hyperlink): connects a work item to any URL or network share -- [**External link types**](#external-link-types): connects a work item to an external object, such as a code object, build, or wiki page -- [**Remote work link types**](#remote-work-link-types): connects work items that are defined in different organizations -- [**GitHub link types**](#github-link-types): connects a work item to a GitHub repository commit, issue, or pull request. - +- [**Work link type**](#work-link-type): Links work items including select test case management work items +- [**Hyperlink**](#hyperlink): Connects a work item to any URL or network share +- [**External link type**](#external-link-type): Connects a work item to an external object, such as a code object, build, or wiki page +- [**Remote work link type**](#remote-work-link-type): Connects work items that are defined in different organizations +- [**GitHub link type**](#github-link-type): Connects a work item to a GitHub repository commit, issue, or pull request. A specific field maintains a count of links for the first four link types, such as *Related Link Count*, *Hyperlink Count*, *External Link Count*, and *Remote Link Count*. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" +Link types are subject to certain restrictions based on their topology. Use the guidance provided in the following tables to choose which link type to use based on the types of queries and reports you want to create. To learn more about the different topologies, see [Link type topologies and restrictions](/previous-versions/azure/devops/reference/xml/link-type-element-reference#topology). -## Work link types +## Work link type -Work link types are system-defined, process-defined, or user-defined (custom). The links listed in the following table are system defined. +Work link types are system-defined, process-defined, or user-defined (custom). The links listed in the following table are system-defined. Each work link type defines the link labels, topology type, and restrictions that are used when links between work items are constructed. For example, the parent-child link type defines two labels: Parent and Child. The link type also supports a hierarchical or tree topology, and prevents circular references from being created between work items. -![Work item link types, conceptual image](media/link-type-reference/linkscontrol-work-item-link-types.png) +![Conceptual image of a Work item link type.](media/link-type-reference/linkscontrol-work-item-link-types.png) -A work item's [*Related Link Count*](linking-attachments.md#related-link-count) corresponds to the sum of all links defined with a work link type. +A work item's *Related Link Count* corresponds to the sum of all links defined with a work link type. ::: moniker range="< azure-devops" @@ -80,7 +63,6 @@ The following table describes the work item link types you can specify to scope ::: moniker-end - :::row::: :::column span="1"::: **Name** @@ -95,8 +77,8 @@ The following table describes the work item link types you can specify to scope --- :::row::: :::column span="1"::: - **Affects-Affected by** (CMMI only) ![Affects link type image](media/link-work-items-support-traceability/affects-cmmi.png) - ![Affected by link type image](media/link-work-items-support-traceability/affected-by-cmmi.png) + **Affects-Affected by** (CMMI only) ![Conceptual image of Affects link type.](media/link-work-items-support-traceability/affects-cmmi.png) + ![Conceptual image of Affected by link type.](media/link-work-items-support-traceability/affected-by-cmmi.png) :::column-end::: :::column span="3"::: Microsoft.VSTS.Common.Affects-Forward @@ -108,21 +90,17 @@ The following table describes the work item link types you can specify to scope Use this directional link to create links between any set of work items, but not ones that would create closed loops. Typically used to track change requests made to requirements. - Restrictions and recommendations: - + Restrictions and recommendations: - You can link a change request to only one requirement using Affects. You can link requirements to as many child change requests as needed using Affected by. + - Only use Affects-Affected by links to link work items in the same project. We recommend this action if you plan to use Excel to modify or update work item data. - - - Only use Affects-Affected by links to link work items in the same project. This action is recommended if you plan to use Excel or Project to modify or update work item data. - - :::column-end::: :::row-end::: :::row::: :::column span="1"::: **Child-Parent** - ![Child link type image](media/link-work-items-support-traceability/child-tree-forward.png) - ![Parent link type image](media/link-work-items-support-traceability/parent-tree-reverse.png) + ![Conceptual image of a Child link type.](media/link-work-items-support-traceability/child-tree-forward.png) + ![Conceptual image of a Parent link type.](media/link-work-items-support-traceability/parent-tree-reverse.png) :::column-end::: :::column span="3"::: System.LinkTypes.Hierarchy-Forward @@ -136,7 +114,6 @@ The following table describes the work item link types you can specify to scope Typical uses include: - - Maintain task summary relationships. Parent-child links are created for summary tasks and their subordinate tasks. - Link tasks to PBIs, user stories, or requirements. Supports Backlog Overview, Stories Overview, and Requirements Overview reports. @@ -150,8 +127,8 @@ The following table describes the work item link types you can specify to scope :::row::: :::column span="1"::: **Duplicate-Duplicate of** - ![Duplicate of tree forward.](media/link-work-items-support-traceability/duplicate-tree-forward.png) - ![Duplicate of tree reverse.](media/link-work-items-support-traceability/duplicate-of-tree-reverse.png) + ![Conceptual image of Duplicate of tree forward.](media/link-work-items-support-traceability/duplicate-tree-forward.png) + ![Conceptual image of Duplicate of tree reverse.](media/link-work-items-support-traceability/duplicate-of-tree-reverse.png) :::column-end::: :::column span="3"::: System.LinkTypes.Duplicate-Forward @@ -164,17 +141,16 @@ The following table describes the work item link types you can specify to scope Use this directional link to create one-to-many relationships between a single parent to one or more child items. Use to track tasks, bugs, or other work items that are duplicates of one another. Restrictions and recommendations: - - A work item can have only one Duplicate. - - Only use Duplicate or Duplicate Of links to link work items in the same project. This action is recommended if you plan to use Excel or Project to modify or update work item data. + - Only use Duplicate or Duplicate Of links to link work items in the same project. This action is recommended if you plan to use Excel to modify or update work item data. :::column-end::: :::row-end::: :::row::: :::column span="1"::: **Referenced By-References** - ![Tested by link type image](media/link-work-items-support-traceability/tested-by-dependency-forward.png) - ![Tests link type image](media/link-work-items-support-traceability/tests-dependency-reverse.png) + ![Conceptual image of Tested by link type.](media/link-work-items-support-traceability/tested-by-dependency-forward.png) + ![Conceptual image of Tests link type.](media/link-work-items-support-traceability/tests-dependency-reverse.png) :::column-end::: :::column span="3"::: Microsoft.VSTS.TestCase. @@ -184,15 +160,14 @@ The following table describes the work item link types you can specify to scope :::column-end::: :::column span="3"::: - Use to link test cases to shared parameters. Use to link Test Cases to Shared Parameters to support the ability to [repeat a test with different data](../../test/repeat-test-with-different-data.md). In general, you wouldn't add this link type to a scoped links control. For more information, see [Repeat a test with different data](../../test/repeat-test-with-different-data.md). - + Use to link test cases to shared parameters. Use to link Test Cases to Shared Parameters to support the ability to [repeat a test with different data](../../test/repeat-test-with-different-data.md). In general, you wouldn't add this link type to a scoped links control. :::column-end::: :::row-end::: :::row::: :::column span="1"::: **Related** - ![Related link type image](media/link-work-items-support-traceability/related-network.png) + ![Conceptual image of Related link type.](media/link-work-items-support-traceability/related-network.png) :::column-end::: :::column span="3"::: System.LinkTypes.Related @@ -200,7 +175,7 @@ The following table describes the work item link types you can specify to scope Link category: System-defined :::column-end::: :::column span="3"::: - Use this non-directional link to create links between any set of work items. Use to link work items that are at the same level, such as two user stories that define features that overlap one another. The Related link type creates simple relationships with few restrictions. + Use this nondirectional link to create links between any set of work items. Use to link work items that are at the same level, such as two user stories that define features that overlap one another. The Related link type creates simple relationships with few restrictions. - Relate work items that are at the same level, such as two user stories that define features that overlap one another. - Link work items that are defined in different projects and managed by different teams. - Find and view work items and their related work items in a two-tiered view. @@ -211,8 +186,8 @@ The following table describes the work item link types you can specify to scope :::row::: :::column span="1"::: **Successor-Predecessor** - ![Successor dependency, forward.](media/link-work-items-support-traceability/successor-dependency-forward.png) - ![Predecessor dependency, reverse.](media/link-work-items-support-traceability/predecessor-dependency-reverse.png) + ![Conceptual image of Successor dependency, forward.](media/link-work-items-support-traceability/successor-dependency-forward.png) + ![Conceptual image of Predecessor dependency, reverse.](media/link-work-items-support-traceability/predecessor-dependency-reverse.png) :::column-end::: :::column span="3"::: System.LinkTypes.Dependency @@ -223,24 +198,23 @@ The following table describes the work item link types you can specify to scope :::column-end::: :::column span="3"::: - Use this directional link to create links between any set of work items, but not ones that would create closed loops. Use to track tasks that must be completed before others can be started. When you plan work using Microsoft Project, linked tasks are represented as predecessor-successor links in Azure Boards. Typically used to track work that must be completed before beginning work on predecessor items. + Use this directional link to create links between any set of work items, but not ones that would create closed loops. Use to track tasks that must be completed before others can be started. Linked tasks are represented as predecessor-successor links in Azure Boards. - - Track tasks that must be completed before others can be started. When you plan work using Project, linked tasks are represented as predecessor-successor links in TFS. + - Track tasks that must be completed before others can be started. - Supports one-to-many relationships. - Find and view predecessor work items and their successor work items in a two-tiered, direct links query view. - Restrictions and recommendations:- - + Restrictions and recommendations: - An error appears when you attempt to create links that define circular relationships. - Create predecessor-successor links only to work items that are within the same project. - You can create predecessor-successor links between work items that are defined in different projects. However, if you export a query to Excel or Project, only those work items that are defined for the project for which the query is defined are imported. + You can create predecessor-successor links between work items that are defined in different projects. But, if you export a query to Excel, only those work items defined for the project for which the query is defined get imported. :::column-end::: :::row-end::: :::row::: :::column span="1"::: **Tested by-Tests** - ![Tested by link type image](media/link-work-items-support-traceability/tested-by-dependency-forward.png) - ![Tests link type image](media/link-work-items-support-traceability/tests-dependency-reverse.png) + ![Conceptual image of Tested by link type.](media/link-work-items-support-traceability/tested-by-dependency-forward.png) + ![Conceptual image of Tests link type.](media/link-work-items-support-traceability/tests-dependency-reverse.png) :::column-end::: :::column span="3"::: Microsoft.VSTS.Common.TestedBy-Forward @@ -257,8 +231,8 @@ The following table describes the work item link types you can specify to scope :::row::: :::column span="1"::: **Test Case-Shared Steps** - ![Tested by link type image](media/link-work-items-support-traceability/tested-by-dependency-forward.png) - ![Tests link type image](media/link-work-items-support-traceability/tests-dependency-reverse.png) + ![Conceptual image of Tested by link type.](media/link-work-items-support-traceability/tested-by-dependency-forward.png) + ![Conceptual image of Tests link type.](media/link-work-items-support-traceability/tests-dependency-reverse.png) :::column-end::: :::column span="3"::: Microsoft.VSTS.TestCase. @@ -268,19 +242,19 @@ The following table describes the work item link types you can specify to scope :::column-end::: :::column span="3"::: - Use to link test cases with shared steps. You [share steps between test cases](/previous-versions/azure/devops/test/mtm/share-steps-between-test-cases) to avoid having to create multiple entries of the same sequence of steps. For more information, see [Share steps between test cases](/previous-versions/azure/devops/test/mtm/share-steps-between-test-cases). + Use to link test cases with shared steps. [Share steps between test cases](/previous-versions/azure/devops/test/mtm/share-steps-between-test-cases) to avoid having to create multiple entries of the same sequence of steps. :::column-end::: :::row-end::: -## Hyperlink link type +## Hyperlink -There's one link type that tracks the number of hyperlinks—[*Hyperlink Count*](linking-attachments.md#hyper-link-count)—added to a work item. A hyperlink can link a work item to any URL. +A hyperlink can link a work item to any URL. The *Hyperlink Count* tracks the number of hyperlinks to a work item. > [!div class="mx-imgBorder"] -> ![Hyperlink, conceptual image](media/link-type-reference/hyperlink.png) +> ![Conceptual image of a Hyperlink.](media/link-type-reference/hyperlink.png) :::row::: :::column span="1"::: @@ -308,32 +282,28 @@ There's one link type that tracks the number of hyperlinks—[*Hyperlink Cou Hyperlink :::column-end::: :::column span="1"::: - Used to link a work item to a URL. **Workitem Hyperlink** is the name of this link type in the [Artifact Link Types API](/rest/api/azure/devops/wit/artifact-link-types/list). + Used to link a work item to a URL. **Work item Hyperlink** is the name of this link type in the [Artifact Link Types API](/rest/api/azure/devops/wit/artifact-link-types/list). :::column-end::: :::row-end::: +## External link type - - -## External link types - -External link types are system-defined link types that support linking work items to other objects stored within Azure DevOps as shown in the following image. A work item's [*External Link Count*](linking-attachments.md#external-link-count) corresponds to the sum of all links defined with an external link type. +External link types are system-defined link types that support linking work items to other objects stored within Azure DevOps as shown in the following image. A work item's *External Link Count* corresponds to the sum of all links defined with an external link type. > [!div class="mx-imgBorder"] -> ![External link types, conceptual image](media/link-type-reference/linkscontrol-external-link-types.png) +> ![Conceptual image of External link type.](media/link-type-reference/linkscontrol-external-link-types.png) > [!NOTE] -> You can only use an external link type to link to an Azure DevOps object. To link work items to other objects outside of Azure DevOps, you can use the [Hyperlink](#hyperlink) link type. +> You can only use an external link type to link to an Azure DevOps object. To link work items to other objects outside of Azure DevOps, use a [hyperlink](#hyperlink). ::: moniker range="azure-devops" -The following table describes the external link types you can choose when adding a link type from a work item or test case. +The following table describes the external link types you can choose when you add a link type from a work item or test case. ::: moniker-end ::: moniker range="< azure-devops" -The following table describes the external link types you can choose when adding a link type from a work item or test case. Also, you can use specify one of these link types to scope a links control using the [**ExternalLinksFilter** XML element](/previous-versions/azure/devops/reference/xml/linkscontroloptions-xml-elements?view=tfs-2017&preserve-view=true). +The following table describes the external link types you can choose when adding a link type from a work item or test case. Also, you can specify one of these link types to scope a links control using the [**ExternalLinksFilter** XML element](/previous-versions/azure/devops/reference/xml/linkscontroloptions-xml-elements?view=tfs-2017&preserve-view=true). ::: moniker-end - :::row::: :::column span=""::: **Link name** @@ -444,7 +414,7 @@ The following table describes the external link types you can choose when adding Release pipeline :::column-end::: :::column span=""::: - Used to link a release to a work item. The system creates a link of this type when a user enables the **Report deployment status to Work** option for a release definition. To learn how to set this option, see [Release pipelines, How do I integrate and report release status?](../../pipelines/release/index.md#how-do-i-integrate-and-report-release-status) + Used to link a release to a work item. The system creates a link of this type when a user enables the **Report deployment status to Work** option for a release definition. :::column-end::: :::row-end::: :::row::: @@ -514,7 +484,7 @@ The following table describes the external link types you can choose when adding Tag :::column-end::: :::column span=""::: - Used to link a work item to a tag that's been defined for a git commit or git repository. For more information, see [Work from the Git command prompt](../../repos/git/command-prompt.md). + Used to link a work item to a tag defined for a git commit or git repository. For more information, see [Work from the Git command prompt](../../repos/git/command-prompt.md). :::column-end::: :::row-end::: :::row::: @@ -560,36 +530,25 @@ The following table describes the external link types you can choose when adding :::column-end::: :::row-end::: +::: moniker range="<=azure-devops" +## GitHub link type - - -::: moniker range=">= azure-devops-2019" - -## GitHub link types - -GitHub link types are system-defined link types. They support linking work items to GitHub objects as shown in the following image. +GitHub link types are system-defined and support linking work items to GitHub objects as shown in the following image. ::: moniker-end ::: moniker range=">= azure-devops-2020" > [!div class="mx-imgBorder"] -> ![GitHub link types, conceptual image](media/link-type-reference/linkscontrol-github-link-types.png) - -::: moniker-end - -::: moniker range="azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![GitHub link types, conceptual image](media/link-type-reference/linkscontrol-github-link-types-onprem.png) +> ![Conceptual image of GitHub link type.](media/link-type-reference/linkscontrol-github-link-types.png) ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!IMPORTANT] -> You can only link to GitHub artifacts whose repositories you have connected to Azure Boards. To create that connection, see [Connect Azure Boards to GitHub](../github/connect-to-github.md). To learn more about linking to GitHub artifacts, see [Link GitHub commits, pull requests, and issues to work items](../github/link-to-from-github.md). +> You can only link to GitHub artifacts with repositories connected to Azure Boards. The following table describes the GitHub link types you can choose when adding a link type from a work item. @@ -630,7 +589,7 @@ The following table describes the GitHub link types you can choose when adding a :::column-end::: :::row-end::: ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: GitHub Pull Request @@ -647,15 +606,12 @@ The following table describes the GitHub link types you can choose when adding a ::: moniker range="azure-devops" - +## Remote work link type -## Remote work link types - -Remote work link types are system-defined link types that support linking work items defined in different organizations. Organizations must be managed by the same Azure Active Directory as described in [Connect your organization to Azure Active Directory](../../organizations/accounts/connect-organization-to-azure-ad.md). +Remote work link types are system-defined link types that support linking work items defined in different organizations, as long as the same Microsoft Entra ID manages them as described in [Connect your organization to Microsoft Entra ID](../../organizations/accounts/connect-organization-to-azure-ad.md). A work item's [*Remote Link Count*](linking-attachments.md#remote-link-count) corresponds to the sum of all links defined with a remote work link type. - :::row::: :::column span=""::: **Name** @@ -672,8 +628,8 @@ A work item's [*Remote Link Count*](linking-attachments.md#remote-link-count) co :::column span=""::: **Consumes From-Produced For** (Dependency topology) - ![Consumes From topology conceptual image](media/link-work-items-support-traceability/affected-by-cmmi.png) - ![Produced For topology conceptual image](media/link-work-items-support-traceability/affects-cmmi.png) + ![Conceptual image of Consumes From topology.](media/link-work-items-support-traceability/affected-by-cmmi.png) + ![Conceptual image of Produced For topology.](media/link-work-items-support-traceability/affects-cmmi.png) :::column-end::: :::column span=""::: System.LinkTypes.Remote.Dependency-Forward @@ -682,13 +638,13 @@ A work item's [*Remote Link Count*](linking-attachments.md#remote-link-count) co Link category: System-defined :::column-end::: :::column span=""::: - Use this directional link to create links between work items that have dependencies and are defined in different organizations. Organizations must be managed by the same Azure Active Directory. Typically used to track change requests made to requirements. + Use this directional link to create links between work items that have dependencies and are defined in different organizations, as long as the same Microsoft Entra ID manages them. Typically used to track change requests made to requirements. :::column-end::: :::row-end::: :::row::: :::column span=""::: **Remote Related** - ![Remote Related topology image](media/link-work-items-support-traceability/related-network.png) + ![Conceptual image of Remote Related topology.](media/link-work-items-support-traceability/related-network.png) :::column-end::: :::column span=""::: System.LinkTypes.Remote.Related @@ -696,25 +652,22 @@ A work item's [*Remote Link Count*](linking-attachments.md#remote-link-count) co Link category: System-defined :::column-end::: :::column span=""::: - Use this non-directional link to create links between work items defined in different organizations. Organizations must be managed by the same Azure Active Directory. + Use this nondirectional link to create links between work items defined in different organizations, as long as the same Microsoft Entra ID manage them. :::column-end::: :::row-end::: - ::: moniker-end ::: moniker range="< azure-devops" -## Custom link types +## Custom link type -You can create custom link types; export and import definitions of link types; and delete, activate, deactivate, and reactivate types of links. See the following articles: +You can create a custom link type; export and import definitions of link types; and delete, activate, deactivate, and reactivate types of links. See the following articles: - [Link type element reference](/previous-versions/azure/devops/reference/xml/link-type-element-reference) - [Manage link types (`witadmin`)](/previous-versions/azure/devops/reference/witadmin/manage-link-types). ::: moniker-end - - ## List link types To get a list of link types, you can use one of the supported command-line tools. @@ -733,10 +686,9 @@ az boards work-item relation list-type [--org] - **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. - #### Example -The following command lists the work item link types in table format that are defined for the fabrikam organization. For other formats, see [Output formats for Azure CLI commands](/cli/azure/format-output-azure-cli). +The following command lists the work item link types in table format that are defined for the fabrikam organization. ```azurecli az boards work-item relation list-type --org fabrikam --output table @@ -855,7 +807,6 @@ Is Active: True The following table provides descriptions for each of the link type attributes returned by **Azure Boards** CLI or the REST API. - :::row::: :::column span=""::: **Attribute** @@ -894,7 +845,7 @@ The following table provides descriptions for each of the link type attributes r `directional` :::column-end::: :::column span="2"::: - Indicates whether the link type is directional (`true`) or not (`false`). Directional link types are defined in pairs with a forward and reverse component. For more information, see [LinkTypes elements reference](/previous-versions/azure/devops/reference/xml/link-type-element-reference). + Indicates whether the link type is directional (`true`) or not (`false`). Directional link types get defined in pairs with a forward and reverse component. For more information, see [LinkTypes elements reference](/previous-versions/azure/devops/reference/xml/link-type-element-reference). :::column-end::: :::row-end::: :::row::: @@ -909,7 +860,7 @@ The following table provides descriptions for each of the link type attributes r Is Active, `enabled` :::column-end::: :::column span="2"::: - Indicates whether the link type is active (`true`) or not (`false`). You can only custom link types for on-premises deployments using the [`witadmin` Manage link type](/previous-versions/azure/devops/reference/witadmin/manage-link-types) command-line tool. + Indicates whether the link type is active (`true`) or not (`false`). You can only use custom link types for on-premises deployments using the [`witadmin` Manage link type](/previous-versions/azure/devops/reference/witadmin/manage-link-types) command-line tool. :::column-end::: :::row-end::: :::row::: @@ -933,7 +884,7 @@ The following table provides descriptions for each of the link type attributes r `remote` :::column-end::: :::column span="2"::: - Indicates whether the link type supports linking to a remore work item (`true`) or not (`False`). Link types with `remote=false` require that the target work item resides in the same organization or collection as the origin work item. + Indicates whether the link type supports linking to a remote work item (`true`) or not (`False`). Link types with `remote=false` require that the target work item resides in the same organization or collection as the origin work item. :::column-end::: :::row-end::: :::row::: @@ -971,11 +922,8 @@ The following table provides descriptions for each of the link type attributes r ## Related articles -- [Link work items to track dependencies](link-work-items-support-traceability.md) -- [Add link to multiple work items](../backlogs/add-link.md) -- [Query FAQs](query-faqs.yml) +- [Link work items to other objects](../backlogs/add-link.md) - [Track dependencies using Delivery Plans](../plans/track-dependencies.md) - [Use mapping to link backlog items to features and epics](../backlogs/organize-backlog.md) - [Bulk modify links using Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) -- [Link type topologies and restrictions](/previous-versions/azure/devops/reference/xml/link-type-element-reference#link-type-topologies-and-restrictions) - [Artifact Link Types API](/rest/api/azure/devops/wit/artifact-link-types/list) diff --git a/docs/boards/queries/link-work-items-support-traceability.md b/docs/boards/queries/link-work-items-support-traceability.md deleted file mode 100644 index 5d716f6df2a..00000000000 --- a/docs/boards/queries/link-work-items-support-traceability.md +++ /dev/null @@ -1,316 +0,0 @@ ---- -title: Link work items to support traceability in Azure Boards -titleSuffix: Azure Boards -description: Learn how to support an auto trail of changes and enable quick navigation by linking work items together. -ms.service: azure-devops-boards -ms.custom: work-items, cross-project, cross-service, contperf-fy23, engagement-fy23 -ms.assetid: eb47069f-e49b-424d-a674-91cb733f3518 -ms.author: chcomley -author: chcomley -ms.topic: how-to -monikerRange: '<= azure-devops' -ms.date: 12/16/2022 ---- - - -# Use links to view dependencies and track related work - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -By linking work items to other work items, you can track related work, view a hierarchy of work, view dependencies, and more. By linking work items to devops and other objects, you support an auto trail of changes and enable quick navigation to work items and linked objects. - -Different link types are used to link to the various objects. For example, you can use *Parent/Child* links to support a hierarchical tree structure of work items. The *Commit* and *Branch* link types support links between work items and Git commits and branches, respectively. - -Link work items to support the following goals: - -- Track dependencies, related items, and work hierarchies -- Track which work items are tested by test cases and test results -- Support an audit trail of code changes and the work items they support -- Support end-to-end traceability -- Share information by linking work items to a network share, storyboard, or document. - -This article describes the link types available for your use. You can link objects from the web portal or Visual Studio Team Explorer. For details on linking work items and deleting links, see [Add link to work items](../backlogs/add-link.md). - - -> [!TIP] -> You can set up automatic linking and other settings that link work items to Git commits, pull requests, builds, and more. To learn how, see the following resources: -> - [Configure repositories and branches to integrate with work tracking](../../repos/git/configure-repos-work-tracking.md?toc=/azure/devops/boards/toc.json) -> - [Configure pipelines to support work tracking](../../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/boards/toc.json) -> - [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md) -> - [Link and view work items to builds and deployments](../work-items/work-item-deployments-control.md). - - -[!INCLUDE [temp](../includes/view-linked-objects.md)] - - - -## Work items linked to work items - -There are several system link types used to link work items to each other: two tree topology, one dependency topology, and one network. Tree topology links support nested hierarchies, tree queries, and several reports. Dependent links support tracking tasks that must be completed before others can be started. And, the **Related** link type supports connecting work items that are at the same level. - -![Work item link types](media/link-tracking-work-item-link-types.png) - -All two-way link types are characterized by a *Forward* and *Reverse* name, such as Parent/Child and Duplicate/Duplicate Of. When you link using one of these names, the linked work item is updated to include a link with the corresponding link type. For example, if you add a Parent link to a work item, the linked work item contains a Child link. - -As a quick reference guide, use the following link types as indicated: - -- Use the **Duplicate** link type when two work items have been created that essentially capture the same information; close one of the work items and keep the other one active -- Use the **Parent/Child** link types when you want to break down work items into smaller items—for example, break down features into stories, or stories into tasks -- Use **Predecessor-Successor** link types when you want to track tasks that must be completed before others can be started; this link type is most often used when you plan work using Project -- Use the **Related** link type when the work items being linked are at the same level—such as two user stories that define features that overlap one another—or to link work items that are defined in different projects or managed by different teams. - -For guidance on choosing link types, review the [Link type reference](link-type-reference.md) in the related notes section. - -You can create links from within a work item form, from a work item that appears in a list of query results, in Microsoft Excel, or in Microsoft Project. You can also use any of the client programs for Team Foundation, such as Team Explorer and the web portal, to create links or attach files. - -Also, you can use the context menu in the web portal or Team Explorer. - -> [!NOTE] -> For each work item, you can add a maximum of 1000 links to other work items. - -::: moniker range="azure-devops" - - - -## Cross-organization work item linking - -Organizations that use Azure Active Directory can link work items that exist in different projects across organizations. Use the following link types as indicated: - -- Use the **Consumes From/Produces For** link types when you want to track dependencies of work items that are defined in different organizations and managed by different teams. -- Use the **Remote Related** link type when the work items being linked are defined in different organizations and managed by different teams, but don't have strong inter-dependencies. - -> [!div class="mx-imgBorder"] -> ![User Story form, Link tab, showing two external links](../backlogs/media/add-link/link-tab-remote-links.png) -::: moniker-end - -## Add a work item link - -You can create links between work items by using one of the links control tabs within a work item form. The user interface to link a work item differs based on the platform, version, and client you use. To link several work items to a new or existing item, see [Add link to work items](../backlogs/add-link.md). - -> [!NOTE] -> Work item forms and features available to you can differ depending on whether you open the form from the web portal or Visual Studio Team Explorer. - - -#### [Browser](#tab/browser/) - - - -From the work item form, you can add a link using the **Related Work** section or from the **Links** tab. - -Open a work item and choose **Add link** or the :::image type="icon" source="../media/icons/add-green-icon.png" border="false"::: plus icon to add a link. - - -::: moniker range=">= azure-devops-2020" -:::image type="content" source="media/link-work-items-support-traceability/work-item-form-link-work-items.png" alt-text="Screenshot of work item form, Links tab, and Related work control."::: -::: moniker-end -::: moniker range="< azure-devops-2020" -![Web portal, work item form, Related work section](media/link-work-items-new-form-control.png) -::: moniker-end - -Choose **Existing item** to link to a work item or other object using any supported link type. Choose **New item** to start a link and define a new work item at the same time. For more information, see [Add link to work items](../backlogs/add-link.md). - -:::image type="content" source="media/link-work-items-support-traceability/related-work-menu.png" alt-text="Screenshot of Related work control, link menu options."::: - -From the **Related Work** or **Links** tab, you can also complete these actions: - -- [View the list of objects linked to the work item](#view-list-links) -- Open an associated item or object: choose the linked item -- Delete a link: highlight it and choose the :::image type="icon" source="../media/icons/delete_icon.png" border="false"::: delete icon - - -From a query results page, you can also complete these actions: -- Link selected items to a new work item -- Link selected items to an existing work item - -For more information, see [Add link to work items](../backlogs/add-link.md#link). - -#### [Visual Studio](#tab/visual-studio/) - - - -If you primarily work in Visual Studio, and want to link work items, you can do so in many ways. Depending on the work item form and customizations that may have been made to your work item form, you may see several Link tabs. Link tabs can be customized to allow or restrict specific link types. - -Open a work item and choose the **Links** tab. From the links control tab you can link to new or existing work items, open the linked object, edit the link type, delete a link, or open the list of links in a query or Excel or Project. - -![Work item form link toolbar controls](media/IC673344.png) - -The work item form opens in the web portal for Visual Studio 2017 and later versions. Work items aren't available from Visual Studio 2019 under the following conditions: -* If you're connected to a GitHub or third-party Git repository. -* If you're set to use the new Git Tool for Visual Studio 2019 as described in [Git experience in Visual Studio](/visualstudio/ide/git-with-visual-studio). - -* * * - -## Parent-child work item links - -These features let you quickly link or change links that use the parent-child link type: - -- To link backlog items to portfolio backlog items or to change the link structure among these items, [use the mapping pane to organize your backlog](../backlogs/organize-backlog.md). -- To create and link tasks to backlog items, [use the sprint backlog page](../sprints/assign-work-sprint.md); from the web portal you can also drag-and-drop items to change the link structure. -- To indent (![Indent](media/IC588323.png)), outdent (![Outdent](media/IC588324.png)), and change the link structure of a tree hierarchy, you can [re-parent and reorder items from a backlog in the web portal](../backlogs/organize-backlog.md) or use a [tree query in Team Explorer](using-queries.md#tree-query). - -You can also use Excel to change the link structure. See [Bulk add or modify work items with Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). - - - -## Test work item links - -Test related link types link test case management work items to one another, or to other work items. From the web portal or Microsoft Test Manager, you can view which test cases are defined for a test suite, and which test suites are defined for a test plan. However, these objects aren't linked to each other through link types. - -You can link work items to test cases using the **Tested/Tested By** link types. You use the same link controls you use to link work items to other work items as [described earlier](#link-work-items). - -The following image shows the full set of link types used in linking test management work item types. most links between test management artifacts occur by executing a task from the **Test** pages or Microsoft Test Manager. - -![Link types used to link test objects](media/link-tracking-work-item-test-case-link-types.png) - -For example, when you add Shared Steps to a Test Case, they are automatically linked using the **Test Case/Shared Steps** link types. See [Share steps between test cases](/previous-versions/azure/devops/test/mtm/share-steps-between-test-cases). - -:::image type="content" source="media/link-work-items-support-traceability/test-case-work-item-form.png" alt-text="Screenshot of test work item form showing steps."::: - -:::image type="content" source="media/link-work-items-support-traceability/insert-shared-steps.png" alt-text="Screenshot of Insert Shared Steps dialog. "::: - -From **Test** you can add test plans, test suites, and test cases—which are linked, but not through a specific link type. Also, the test system creates and manages the associations of test results to test cases and test plans. - - -## Work items linked to code artifacts and build and release pipelines - -As you develop your software, you can capture which code changes and builds support the completion of a work item. In this way, your team can understand what work was done or how a bug was fixed through the audit trail of changes to the code base. - -::: moniker range=">= azure-devops-2019" -The link types used to construct these links—as illustrated in the following image—are: Branch, Build, Changeset, Commit, Found in build, Integrated in build, Pull Request, Versioned Item, and Integrated in release environment. - -:::image type="content" source="media/link-type-reference/conceptual-link-types-devops-objects.png" alt-text="Conceptual image of devops link types."::: -::: moniker-end - -::: moniker range="tfs-2018" -The link types used to construct these links—as illustrated in the following image—are: Branch, Build, Changeset, Commit, Pull Request, and Versioned Item. - -![Artifact-to-artifact link types](../backlogs/media/git/link-tracking-artifact-to-artifact-link-types.png) - -To learn more about the links control or to customize the Development links control, see [LinksControlOptions elements, Development links control](/previous-versions/azure/devops/reference/xml/linkscontroloptions-xml-elements#development-links-control?view=tfs-2017&preserve-view=true). - -::: moniker-end - -You can add a link from the work item to the supported artifacts using the method [described earlier for linking work items](#link-work-items). However, an easier method is to add the work item ID to a commit, pull request, changeset, or other supported Git or TFVC operation at the time you create those items. Also, you can link work items from the **Development** control within the work item form as described in [Work items linked to Git code development](#git-code-development). - -::: moniker range=">= azure-devops-2019" -See the following articles for more information: -::: moniker-end - -::: moniker range=">= azure-devops-2020" -- [Configure repositories and branches to integrate with work tracking](../../repos/git/configure-repos-work-tracking.md?toc=/azure/devops/boards/toc.json) -- [Configure pipelines to support work tracking](../../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/boards/toc.json) -- [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md) -- [Link and view work items to builds and deployments](../work-items/work-item-deployments-control.md) -- [Link to work items from pull requests, commits, and comments](../../organizations/notifications/add-links-to-work-items.md#link-wit-id) -- [Auto complete work items with pull requests](../work-items/auto-complete-work-items-pull-requests.md). -::: moniker-end - -::: moniker range="azure-devops-2019" -- [Configure repositories and branches to integrate with work tracking](../../repos/git/configure-repos-work-tracking.md?toc=/azure/devops/boards/toc.json) -- [Configure pipelines to support work tracking](../../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/boards/toc.json) -- [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md) -- [Link to work items from pull requests, commits, and comments](../../organizations/notifications/add-links-to-work-items.md#link-wit-id) -- [Auto complete work items with pull requests](../work-items/auto-complete-work-items-pull-requests.md). -::: moniker-end - - - - -## Work items linked to Git code development - -The recommended method is to drive development from the work item or add the work item ID when creating branches, commits, and pull requests. - -Git lets you link work items to commits by using the **Commit** link type. You can do this in several ways: - -- In Visual Studio Team Explorer, add work item IDs before you commit your changes - ![Add work item ID or drag items before you commit your changes](media/link-git-commit-items.png) -- You can use the [git-commit](https://git-scm.com/docs/git-commit) command and include the work item ID in your comment. For example, you apply this comment #35 Catch null exception to your commit. When you push the commit, the system creates a Commit link between the commit and work item #35. -- And, with the **Development** control, you can [drive your git development from the work item](../backlogs/connect-work-items-to-git-dev-ops.md) as shown in the following image. - - -::: moniker range=">= azure-devops-2020" -:::image type="content" source="../backlogs/media/git/development-control.png" alt-text="Screenshot of work item form, Development control."::: -::: moniker-end - -::: moniker range="azure-devops-2019" -:::image type="content" source="../backlogs/media/git/development-control-2019.png" alt-text="Screenshot of work item form, Development control, Azure DevOps Server 2019."::: -::: moniker-end - -::: moniker range="tfs-2018" -![Screenshot of work item form, Development control, TFS 2018.](../backlogs/media/drive-git-development-dev-section.png) -::: moniker-end - -::: moniker range=">= azure-devops-2019" - - - -## Work items linked to GitHub artifacts - -By connecting Azure Boards with GitHub repositories, you enable linking between GitHub commits and pull requests to work items. You can use GitHub for software development while using Azure Boards to plan and track your work. - -::: moniker-end - -::: moniker range=">= azure-devops-2020" - -The link types supported include **GitHub Commit**, **GitHub Issue**, and **GitHub Pull Request**. - -::: moniker-end - -::: moniker range="azure-devops-2019" - -The link types supported include **GitHub Commit** and **GitHub Pull Request**. - -::: moniker-end - -::: moniker range=">= azure-devops-2019" -> [!IMPORTANT] -> You can only link to GitHub artifacts whose repositories you have connected to Azure Boards. To create that connection, see [Connect Azure Boards to GitHub](../github/connect-to-github.md). To learn more about linking to GitHub artifacts, see [Link GitHub commits, pull requests, and issues to work items](../github/link-to-from-github.md). - -::: moniker-end - - -## Work items linked to TFVC code development - -Team Foundation version control (TFVC) lets you link work items to version control changesets or versioned source code files by using the **Changeset** and **Versioned Item** link types. When you check in pending changes or use My Work to check in changes, [work items are automatically linked to your changes](../../repos/tfvc/check-your-work-team-codebase.md). - -![Team Explorer, My Work, Pending Changes, check in](../../repos/tfvc/media/check-your-work-team-codebase/ic593474.png) - - - -## Work items linked to a Web site, network share, storyboard, or document - -You can use the Hyperlinks or Storyboard link type to link a work item to a Web site, network share, or document located on a network share. Both of these link types are one-way links. To add links of this type, you can use the same links controls [described earlier for linking work items](#link-work-items). - -![Use the Hyperlinks or Storyboard link type to link a work item to a URL.](media/link-tracking-work-item-to-url-link-types.png) - -By using the Storyboard link type, you differentiate the link you're adding to specify a storyboard or document that provides work item specifications. Use this link type to provide your team access to the shared file where they can add their comments. - -## Query for linked work items - -To filter items based on hierarchical links, use the **Tree of work items** query type. To filter items based on all link types, use **Work items and direct links**. - -You can search for work items that not only meet criteria for field values but also that are linked to other work items with specific types of links. This kind of query displays a primary set of work items, which meet the field criteria, and a secondary set, which is linked to items in the primary set. - -For query examples, see [Link and attachment queries](linking-attachments.md). - -> [!NOTE] -> You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using Parent/Child or any other link type. You can only view the hierarchy through the [**Test>Test Plans** page](../../test/create-a-test-plan.md). - -## Related articles - -You should now have a broad understanding of the various link relationships you can create to track dependencies and create an audit trail for your code development. - -Once you've formed a link relationship, you can't edit the link type of that relationship from the web portal, but you can do it from Team Explorer. - -For more information, see these articles: - -- [Add link to multiple work items](../backlogs/add-link.md) -- [Track dependencies using Delivery Plans](../plans/track-dependencies.md) -- [Share plans, add attachments](share-plans.md) -- [Use mapping to link backlog items to features and epics](../backlogs/organize-backlog.md) -- [Bulk modify links using Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) -- [Link types reference](link-type-reference.md) - -### Visualize related work and other objects - -You can view related work items and object within a work item form by installing the [Work item visualization extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization) available from the Visual Studio Marketplace, Azure DevOps tab. diff --git a/docs/boards/queries/linking-attachments.md b/docs/boards/queries/linking-attachments.md index 3e811bd62e7..a078c69340f 100644 --- a/docs/boards/queries/linking-attachments.md +++ b/docs/boards/queries/linking-attachments.md @@ -1,7 +1,7 @@ --- title: Query work items by link or attachment count in Azure Boards titleSuffix: Azure Boards -description: Learn how to query work items based on link type, link count, link restrictions, and attachment file count in Azure Boards. +description: Learn how to query work items based on link type, link count, link restrictions, and attached file count in Azure Boards. ms.custom: boards-queries, engagement-fy23 ms.service: azure-devops-boards ms.assetid: 219717a0-de6e-4f70-8558-54f813f82507 @@ -9,28 +9,21 @@ ms.author: chcomley author: chcomley ms.topic: example-scenario monikerRange: '<= azure-devops' -ms.date: 07/26/2022 +ms.date: 09/06/2024 --- # Query work items by link or attachment count [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can [link work items to track related work and dependencies](link-work-items-support-traceability.md) and [attach files to share information with your team](share-plans.md#attachments). You can then list work items based on one or more of the following fields: +You can [link work items to track related work and dependencies](../backlogs/add-link.md) and attach files to share information with your team. You can then list work items based on one or more of the following fields: ::: moniker range="azure-devops" -- Attachment File Count -- (Discussion) Comment Count -- External Link count -- Hyperlink Count -- Link Comment -- Related Link Count -- Remote Link Count +Attached File Count | (Discussion) Comment Count | External Link count| Hyperlink Count| Link Comment| Related Link Count|Remote Link Count ::: moniker-end - ::: moniker range="< azure-devops" -- Attachment File Count +- Attached File Count - (Discussion) Comment Count - External Link count - Hyperlink Count @@ -38,27 +31,22 @@ You can [link work items to track related work and dependencies](link-work-items - Related Link Count ::: moniker-end +For more information about these fields, see the [table provided later in this article](#table-field). -For descriptions of each of these fields, see the [table provided later in this article](#table-field). +## Prerequisites + +[!INCLUDE [prerequisites-queries](../includes/prerequisites-queries.md)] ## Supported operators and macros -Query clauses that specify an integer field can use the operators listed below. +Clauses that specify an integer field can use the following operators. `= , <> , > , < , >= , <= ,` `=[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field],` `In, Not In,` `Was Ever` -## Link or attachment count queries - -You can filter for work items by the link type, link count, or attachment count. - ---- -::: moniker-end - - - + ## List hierarchical items in a tree view @@ -74,9 +62,12 @@ Add a query and select **Tree of work items** to begin your query. You should se *** > [!NOTE] -> You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using parent-child link types. However, you can create a Direct links query that lists test-related work items. Also, you can, [view the hierarchy through the Test>Test Plans page](../../test/create-a-test-plan.md). +> You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using parent-child link types. But, you can create a direct links query that lists test-related work items. Also, you can [view the hierarchy through the Test Plans page](../../test/create-a-test-plan.md). + +## Options for filters and query clauses + +Change the filter options for linked work items and add query clauses via the following options. -From there, you can add query clauses or change the filter options for linked work items. :::row::: :::column span=""::: **Filter for** @@ -87,7 +78,7 @@ From there, you can add query clauses or change the filter options for linked wo :::row-end::: :::row::: :::column span=""::: - View only child items of work item 645 + Only child items of work item 645 :::column-end::: :::column span=""::: **Add to Filters for top-level work items:** @@ -123,7 +114,7 @@ From there, you can add query clauses or change the filter options for linked wo :::column-end::: :::row-end::: - + ## List items based on linked dependents @@ -135,60 +126,52 @@ The following query finds work items in all projects that are linked to work ite :::image type="content" source="media/link-attachments/direct-links-query-web-portal.png" alt-text="Screenshot of Query Editor, Work items, and direct links, Web portal."::: -**Why this works:** - -- Checking the **Query across projects** checkbox enables all dependent linked work items that match the filter criteria to be listed, no matter which project they belong to. - -- Specifying the **Area Path Under Fabrikam** clause indicates to find only work items that are linked to work items defined under the Fabrikam project. - -- Specifying **Only return items that have matching links**, and **Return selected link types** causes the query to return only work items that are linked based on the **Predecessor** and **Successor** link types. +- Check the **Query across projects** checkbox to enable all dependent linked work items that match the filter criteria to be listed, no matter which project they belong to. +- Specify the **Area Path Under Fabrikam** clause to find only work items that are linked to work items defined under the Fabrikam project. +- Specify **Only return items that have matching links**, and **Return selected link types** to return only work items that are linked based on the **Predecessor** and **Successor** link types. #### [Visual Studio 2015](#tab/visual-studio/) -Use this type of query to list all dependent work items that link to active Product Backlog Items or Bugs that haven't been removed, closed, or completed. Only those dependent work items that are under a product area other than the **Phone Save\Phone Customers** are returned. +Use this type of query to list all dependent work items that link to active Product Backlog Items or Bugs that aren't removed, closed, or completed. Only those dependent work items that are under a product area other than the **Phone Save\Phone Customers** are returned. ![Work Items and Dependent Links Query](media/example-work-item-queries/IC588290.png) -**Why this works:** - -- Removing the **Team Project = @Project** clause enables all dependent linked work items that match the filter criteria to be listed, no matter which project they belong to in the collection. - -- Grouping each of two clauses returns all **Product Backlog Item**s on the backlog or in progress, and the second grouped clause returns all **Bug**s on the backlog or in progress. - -- Grouping the two clauses with the **OR** operator at the start of the second clause returns work items that match either of the two filter criteria. - -- Choosing the **Only return items that have the specified links** returns only top-level work items that have dependencies. +- Remove the **Team Project = @Project** to enable all dependent linked work items that match the filter criteria to be listed, no matter which project they belong to in the collection. +- Group each of two clauses to return all **Product Backlog Item**s on the backlog or in progress, and the second grouped clause returns all **Bug**s on the backlog or in progress. +- Group the two clauses with the **OR** operator at the start of the second clause to return work items that match either of the two filter criteria. +- Choose the **Only return items that have the specified links** to return only top-level work items that have dependencies. +- Choose **Return links of any type** to return all linked work items that match the filter criteria for linked work items, in this case, returning all work items that aren't under the **Phone Saver\\Phone Customers** area path, and aren't completed or removed. -- Choosing **Return links of any type** returns all linked work items that match the filter criteria for linked work items, in this case, returning all work items that aren't under the **Phone Saver\\Phone Customers** area path, and aren't completed or removed. +The following image shows the query results. -The following image shows the query results that are returned. - -![Direct links query results](media/example-work-item-queries/IC588291.png) +![Screenshot of Direct links query results.](media/example-work-item-queries/IC588291.png) *** - + ## List orphan user stories -If you typically organize your user stories under features, you can quickly find user stories that are orphan by opening the product backlog, enable **Parents On** view option, and scroll down to the section that lists **Unparented Stories** (Agile) or **Unparented Backlog items** (Scrum). +If you typically organize your user stories under features, you can quickly find them by doing the following steps. + +1. Open the product backlog and turn on the **Parents On** view option. +2. Scroll down to the section that lists **Unparented Stories** (Agile) or **Unparented Backlog items** (Scrum). -> [!div class="mx-imgBorder"] -> ![List orphan stories or backlog items](media/link-attachments/list-orphan-stories.png) +:::image type="content" source="media/link-attachments/list-orphan-stories.png" alt-text="Screenshot of List orphan stories or backlog items."::: Or, you can find unparented backlog items using a **Work items and direct links** query. For example, the following query lists active user stories for the Azure DevOps team that don't have a Parent link. :::image type="content" source="media/link-attachments/unparented-work-items.png" alt-text="Screenshot of Query Editor, Work items, and direct links, Web portal, unparented user stories."::: - - + + -## Link, attachment count, and comment fields +## Fields associated with links and attachments -The following table describes fields associated with links and attachments. Most of these fields don't appear within the work item form, but are tracked for all work item types. +The following table describes fields associated with links and attachments. Most of these fields don't appear within the work item form, but get tracked for all work item types. :::row::: :::column span="1"::: - **Attachment File Count** + **Attached File Count** :::column-end::: :::column span="3"::: The number of files attached to the work item and stored in the work item tracking database. @@ -196,9 +179,6 @@ The following table describes fields associated with links and attachments. Most > [!NOTE] > For Azure Boards (cloud service), you can add up to 100 attachments to a work item. Attempts to add more result in an error message upon saving the work item. :::column-end::: - :::column span="1"::: - All - :::column-end::: :::row-end::: :::row::: :::column span="1"::: @@ -208,28 +188,22 @@ The following table describes fields associated with links and attachments. Most The number of comments added to the **Discussion** section of the work item. Reference Name=System.CommentCount, Data type=Integer :::column-end::: - :::column span="1"::: - All - :::column-end::: :::row-end::: :::row::: :::column span="1"::: - + **External Link Count** :::column-end::: :::column span="3"::: - The number of links from the work item to artifacts that are not work items. such as pull requests, commits, changesets, or other link types. + The number of links from the work item to artifacts that aren't work items, such as pull requests, commits, changesets, or other link types. Reference Name=System.ExternalLinkCount, Data type=Integer :::column-end::: - :::column span="1"::: - All - :::column-end::: :::row-end::: :::row::: :::column span="1"::: - + **Hyperlink Count** @@ -239,9 +213,6 @@ The following table describes fields associated with links and attachments. Most Reference Name=System.HyperLinkCount, Data type=Integer :::column-end::: - :::column span="1"::: - All - :::column-end::: :::row-end::: :::row::: :::column span="1"::: @@ -252,9 +223,6 @@ The following table describes fields associated with links and attachments. Most Reference Name=System.Links.Comment, Data type=PlainText :::column-end::: - :::column span="1"::: - All - :::column-end::: :::row-end::: :::row::: :::column span="1"::: @@ -267,14 +235,11 @@ The following table describes fields associated with links and attachments. Most Reference Name=System.Links.Description, Data type=PlainText :::column-end::: - :::column span="1"::: - All - :::column-end::: :::row-end::: ::: moniker range=">= azure-devops-2022" :::row::: :::column span="1"::: - + **Parent** @@ -293,7 +258,7 @@ The following table describes fields associated with links and attachments. Most ::: moniker range="azure-devops-2020" :::row::: :::column span="1"::: - + **Parent** @@ -304,73 +269,56 @@ The following table describes fields associated with links and attachments. Most > The **Parent** field is available from Azure DevOps Server 2020 and later versions. You can't specify this field within a query clause. Reference Name=System.Parent, Data type=Integer :::column-end::: - :::column span="1"::: - All - :::column-end::: :::row-end::: ::: moniker-end :::row::: :::column span="1"::: - + **Related Link Count** :::column-end::: :::column span="3"::: - The number of links defined for a work item which use a work link type, such as Parent-Child, Predecessor-Successor, and Related. For a full list, see [Link type reference](link-type-reference.md#work-link-types). + The number of links defined for a work item that use a work link type, such as Parent-Child, Predecessor-Successor, and Related. For a full list, see [Link type reference](link-type-reference.md). Reference Name=System.RelatedLinkCount, Data type=Integer :::column-end::: - :::column span="1"::: - All - :::column-end::: :::row-end::: :::row::: :::column span="1"::: - + **Remote Link Count** :::column-end::: :::column span="3"::: - Available for Azure DevOps Services only. The number of links from a work item to work items defined in another organization. Organizations must be managed by the same Azure Active Directory. Supported link types include Consumes From, Produced For, and Remote Related. For more information, see [Add link to work items, Link to a remote work item](../backlogs/add-link.md). + Available for Azure DevOps Services only. The number of links from a work item to work items defined in another organization. The same Microsoft Entra ID must manage the organizations. Supported link types include Consumes From, Produced For, and Remote Related. For more information, see [Add link to work items, Link to a remote work item](../backlogs/add-link.md). Reference Name=System.RemoteLinkCount, Data type=Integer :::column-end::: - :::column span="1"::: - All - :::column-end::: :::row-end::: ## Related articles - [Add a link to multiple work items](../backlogs/add-link.md) -- [Linking, traceability, and managing dependencies](link-work-items-support-traceability.md) -- [Track dependencies using Delivery Plans](../plans/track-dependencies.md) +- [Link work items to other objects](../backlogs/add-link.md) - [Query quick reference](query-index-quick-ref.md) - [Query editor](using-queries.md) - [Query fields, operators, and macros](query-operators-variables.md) -- [Add work items](../backlogs/add-work-items.md) - [Work item field index](../work-items/guidance/work-item-field.md) - ::: moniker range="< azure-devops" ### Visualize related work and other objects -You can view related work items and object within a work item form by installing the [Work item visualization extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization) available from the Visual Studio Marketplace, Azure DevOps tab. -::: moniker-end - -::: moniker range="< azure-devops" +You can view related work items and objects within a work item with the [Work item visualization extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization) available from the Visual Studio Marketplace, Azure DevOps tab. ### Add custom link types or customize the links controls To add link types, see [Manage link types [witadmin]](/previous-versions/azure/devops/reference/witadmin/manage-link-types). -All tabs that support creating links between work items are implemented by using the **LinksControl** element on the work item form. This element controls filtering and restricting the types of work items to which you can link, the types of links that you can create, and whether you can link to work items in another project. To customize the link controls and restrictions, you modify the definition of the `LinksControlOptions` for a work item type, see [LinksControlOptions XML elements](/previous-versions/azure/devops/reference/xml/linkscontroloptions-xml-elements?view=tfs-2017&preserve-view=true). +All tabs that support creating links between work items are implemented by using the **LinksControl** element on the work item form. This element controls filtering and restricting the types of work items to which you can link. It also controls the types of links that you can create and whether you can link work items in another project. To customize the link controls and restrictions, you modify the definition of the `LinksControlOptions` for a work item type, see [LinksControlOptions XML elements](/previous-versions/azure/devops/reference/xml/linkscontroloptions-xml-elements?view=tfs-2017&preserve-view=true). ### Default data fields in lists of links You can add or remove columns from the list of links, and you can customize the default columns and the column order. For more information, see [LinksControlOptions XML elements](/previous-versions/azure/devops/reference/xml/linkscontroloptions-xml-elements?view=tfs-2017&preserve-view=true). ::: moniker-end - - diff --git a/docs/boards/queries/media/boards-queries-all-shared-queries.png b/docs/boards/queries/media/boards-queries-all-shared-queries.png new file mode 100644 index 00000000000..66aa0be96b2 Binary files /dev/null and b/docs/boards/queries/media/boards-queries-all-shared-queries.png differ diff --git a/docs/boards/queries/media/history-audit/filter-history-people.png b/docs/boards/queries/media/history-audit/filter-history-people.png index 77c5e40e301..60dd9c17389 100644 Binary files a/docs/boards/queries/media/history-audit/filter-history-people.png and b/docs/boards/queries/media/history-audit/filter-history-people.png differ diff --git a/docs/boards/queries/media/import-csv/bulk-update-import.png b/docs/boards/queries/media/import-csv/bulk-update-import.png index a748427f6b7..3ede3a05bfb 100644 Binary files a/docs/boards/queries/media/import-csv/bulk-update-import.png and b/docs/boards/queries/media/import-csv/bulk-update-import.png differ diff --git a/docs/boards/queries/media/import-csv/export-query.png b/docs/boards/queries/media/import-csv/export-query.png index 95152c88f8b..fa6cccda41c 100644 Binary files a/docs/boards/queries/media/import-csv/export-query.png and b/docs/boards/queries/media/import-csv/export-query.png differ diff --git a/docs/boards/queries/media/import-csv/import-file.png b/docs/boards/queries/media/import-csv/import-file.png index c0119788610..73905c63492 100644 Binary files a/docs/boards/queries/media/import-csv/import-file.png and b/docs/boards/queries/media/import-csv/import-file.png differ diff --git a/docs/boards/queries/media/import-csv/import-update-error-1.png b/docs/boards/queries/media/import-csv/import-update-error-1.png index 731a27924ca..78de033d1d1 100644 Binary files a/docs/boards/queries/media/import-csv/import-update-error-1.png and b/docs/boards/queries/media/import-csv/import-update-error-1.png differ diff --git a/docs/boards/queries/media/import-csv/imported-file-error.png b/docs/boards/queries/media/import-csv/imported-file-error.png index 9d4e5101631..bf08bce1abf 100644 Binary files a/docs/boards/queries/media/import-csv/imported-file-error.png and b/docs/boards/queries/media/import-csv/imported-file-error.png differ diff --git a/docs/boards/queries/media/import-csv/imported-file.png b/docs/boards/queries/media/import-csv/imported-file.png index d1931515c83..cdd714f4af5 100644 Binary files a/docs/boards/queries/media/import-csv/imported-file.png and b/docs/boards/queries/media/import-csv/imported-file.png differ diff --git a/docs/boards/queries/media/import-csv/open-queries-import.png b/docs/boards/queries/media/import-csv/open-queries-import.png index 9c90dcb9939..57f2193beb2 100644 Binary files a/docs/boards/queries/media/import-csv/open-queries-import.png and b/docs/boards/queries/media/import-csv/open-queries-import.png differ diff --git a/docs/boards/queries/media/link-git-commit-items.png b/docs/boards/queries/media/link-git-commit-items.png index df76d49d576..29db6aec8ac 100644 Binary files a/docs/boards/queries/media/link-git-commit-items.png and b/docs/boards/queries/media/link-git-commit-items.png differ diff --git a/docs/boards/queries/media/numeric/config-pivot-items-developer.png b/docs/boards/queries/media/numeric/config-pivot-items-developer.png index 588e13ad2e3..e03ebdc3bd3 100644 Binary files a/docs/boards/queries/media/numeric/config-pivot-items-developer.png and b/docs/boards/queries/media/numeric/config-pivot-items-developer.png differ diff --git a/docs/boards/queries/media/numeric/config-pivot-remaining-work-per-developer-area.png b/docs/boards/queries/media/numeric/config-pivot-remaining-work-per-developer-area.png index 8b07169450d..3a0a470aec1 100644 Binary files a/docs/boards/queries/media/numeric/config-pivot-remaining-work-per-developer-area.png and b/docs/boards/queries/media/numeric/config-pivot-remaining-work-per-developer-area.png differ diff --git a/docs/boards/queries/media/numeric/config-pivot-state-area.png b/docs/boards/queries/media/numeric/config-pivot-state-area.png index 96ae48903aa..3f4cb6f712d 100644 Binary files a/docs/boards/queries/media/numeric/config-pivot-state-area.png and b/docs/boards/queries/media/numeric/config-pivot-state-area.png differ diff --git a/docs/boards/queries/media/numeric/config-psum-story-points-stacked-bar.png b/docs/boards/queries/media/numeric/config-psum-story-points-stacked-bar.png index 9bf82b2774d..788603d5dec 100644 Binary files a/docs/boards/queries/media/numeric/config-psum-story-points-stacked-bar.png and b/docs/boards/queries/media/numeric/config-psum-story-points-stacked-bar.png differ diff --git a/docs/boards/queries/media/numeric/config-trend-sum-story-points.png b/docs/boards/queries/media/numeric/config-trend-sum-story-points.png index 701cab06256..fba65bab655 100644 Binary files a/docs/boards/queries/media/numeric/config-trend-sum-story-points.png and b/docs/boards/queries/media/numeric/config-trend-sum-story-points.png differ diff --git a/docs/boards/queries/media/numeric/field-value-blank.png b/docs/boards/queries/media/numeric/field-value-blank.png index 5a436975490..1d3df39b3ff 100644 Binary files a/docs/boards/queries/media/numeric/field-value-blank.png and b/docs/boards/queries/media/numeric/field-value-blank.png differ diff --git a/docs/boards/queries/media/organize-queries/save-query-dashboard-new-boards-hubs.png b/docs/boards/queries/media/organize-queries/save-query-dashboard-new-boards-hubs.png new file mode 100644 index 00000000000..3a235065828 Binary files /dev/null and b/docs/boards/queries/media/organize-queries/save-query-dashboard-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/organize-queries/save-query-team-favorite-new-boards-hubs.png b/docs/boards/queries/media/organize-queries/save-query-team-favorite-new-boards-hubs.png new file mode 100644 index 00000000000..bb365dd63eb Binary files /dev/null and b/docs/boards/queries/media/organize-queries/save-query-team-favorite-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/permissions/select-query-security-new-boards-hubs.png b/docs/boards/queries/media/permissions/select-query-security-new-boards-hubs.png new file mode 100644 index 00000000000..45a2eecbb29 Binary files /dev/null and b/docs/boards/queries/media/permissions/select-query-security-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/query-effort-active-bugs-count-summary.png b/docs/boards/queries/media/query-effort-active-bugs-count-summary.png index 54d80db94f9..8e4a0d3fc24 100644 Binary files a/docs/boards/queries/media/query-effort-active-bugs-count-summary.png and b/docs/boards/queries/media/query-effort-active-bugs-count-summary.png differ diff --git a/docs/boards/queries/media/query-effort-sum-story-points-active-closed.png b/docs/boards/queries/media/query-effort-sum-story-points-active-closed.png index 980a4ea2bf5..d74c4f9193e 100644 Binary files a/docs/boards/queries/media/query-effort-sum-story-points-active-closed.png and b/docs/boards/queries/media/query-effort-sum-story-points-active-closed.png differ diff --git a/docs/boards/queries/media/query-effort-sum-story-points-iteration.png b/docs/boards/queries/media/query-effort-sum-story-points-iteration.png index bfe311093d1..e25d08e342e 100644 Binary files a/docs/boards/queries/media/query-effort-sum-story-points-iteration.png and b/docs/boards/queries/media/query-effort-sum-story-points-iteration.png differ diff --git a/docs/boards/queries/media/query-effort-tasks-bugs-list.png b/docs/boards/queries/media/query-effort-tasks-bugs-list.png index a83a8a77196..b3c72f70585 100644 Binary files a/docs/boards/queries/media/query-effort-tasks-bugs-list.png and b/docs/boards/queries/media/query-effort-tasks-bugs-list.png differ diff --git a/docs/boards/queries/media/using-queries/define-clause-new-boards-hubs.png b/docs/boards/queries/media/using-queries/define-clause-new-boards-hubs.png new file mode 100644 index 00000000000..8659cc345f2 Binary files /dev/null and b/docs/boards/queries/media/using-queries/define-clause-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/using-queries/new-query-dialog-new-boards-hubs.png b/docs/boards/queries/media/using-queries/new-query-dialog-new-boards-hubs.png new file mode 100644 index 00000000000..9f092199f08 Binary files /dev/null and b/docs/boards/queries/media/using-queries/new-query-dialog-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/using-queries/query-across-projects-new-boards-hubs.png b/docs/boards/queries/media/using-queries/query-across-projects-new-boards-hubs.png new file mode 100644 index 00000000000..f94312f07f7 Binary files /dev/null and b/docs/boards/queries/media/using-queries/query-across-projects-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/using-queries/query-across-two-projects-new-boards-hubs.png b/docs/boards/queries/media/using-queries/query-across-two-projects-new-boards-hubs.png new file mode 100644 index 00000000000..ffbdb33d1cd Binary files /dev/null and b/docs/boards/queries/media/using-queries/query-across-two-projects-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/edit-query-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/edit-query-new-boards-hubs.png new file mode 100644 index 00000000000..8c558c5ab5b Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/edit-query-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/email-query-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/email-query-new-boards-hubs.png new file mode 100644 index 00000000000..76f36b43e33 Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/email-query-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/filter-queries-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/filter-queries-new-boards-hubs.png new file mode 100644 index 00000000000..640b20b0d48 Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/filter-queries-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/new-folder-dialog-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/new-folder-dialog-new-boards-hubs.png new file mode 100644 index 00000000000..73ab14de59f Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/new-folder-dialog-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/new-folder-dialog.png b/docs/boards/queries/media/view-run-queries/new-folder-dialog.png new file mode 100644 index 00000000000..16c4a10061d Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/new-folder-dialog.png differ diff --git a/docs/boards/queries/media/view-run-queries/new-query-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/new-query-new-boards-hubs.png new file mode 100644 index 00000000000..585285fe065 Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/new-query-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/new-query-new-exp.png b/docs/boards/queries/media/view-run-queries/new-query-new-exp.png index 4b9c4a819e8..6a979f85421 100644 Binary files a/docs/boards/queries/media/view-run-queries/new-query-new-exp.png and b/docs/boards/queries/media/view-run-queries/new-query-new-exp.png differ diff --git a/docs/boards/queries/media/view-run-queries/open-queries-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/open-queries-new-boards-hubs.png new file mode 100644 index 00000000000..a01ae3571a3 Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/open-queries-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/open-queries-vert.png b/docs/boards/queries/media/view-run-queries/open-queries-vert.png index a2786cf71c6..0e423927ca9 100644 Binary files a/docs/boards/queries/media/view-run-queries/open-queries-vert.png and b/docs/boards/queries/media/view-run-queries/open-queries-vert.png differ diff --git a/docs/boards/queries/media/view-run-queries/query-context-menu-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/query-context-menu-new-boards-hubs.png new file mode 100644 index 00000000000..12551fd6081 Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/query-context-menu-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/query-navigation-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/query-navigation-new-boards-hubs.png new file mode 100644 index 00000000000..4f5c75e17f7 Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/query-navigation-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/save-as-dialog-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/save-as-dialog-new-boards-hubs.png new file mode 100644 index 00000000000..b3a4dcee2d5 Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/save-as-dialog-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/save-as-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/save-as-new-boards-hubs.png new file mode 100644 index 00000000000..84e80226093 Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/save-as-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/select-active-bugs-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/select-active-bugs-new-boards-hubs.png new file mode 100644 index 00000000000..efe8a5c76f0 Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/select-active-bugs-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/select-new-folder-new-boards-hubs.png b/docs/boards/queries/media/view-run-queries/select-new-folder-new-boards-hubs.png new file mode 100644 index 00000000000..e129da0c2ea Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/select-new-folder-new-boards-hubs.png differ diff --git a/docs/boards/queries/media/view-run-queries/select-query-security.png b/docs/boards/queries/media/view-run-queries/select-query-security.png new file mode 100644 index 00000000000..eb574cca82f Binary files /dev/null and b/docs/boards/queries/media/view-run-queries/select-query-security.png differ diff --git a/docs/boards/queries/organize-queries.md b/docs/boards/queries/organize-queries.md index 8e17d68e8f1..24fa48b6bbb 100644 --- a/docs/boards/queries/organize-queries.md +++ b/docs/boards/queries/organize-queries.md @@ -1,10 +1,10 @@ --- title: Manage and organize your queries in Azure Boards and Azure DevOps -titleSuffix: Azure Boards +titleSuffix: Azure Boards description: Learn how to manage your queries by using favorites and folders in Azure Boards and Azure DevOps. -ms.custom: boards-queries, contperf-fy23 +ms.custom: boards-queries, engagement-fy23 ms.service: azure-devops-boards -ms.assetid: BAD9F638-3F26-4FE3-8A7D-F5C0793BE8AC +ms.assetid: BAD9F638-3F26-4FE3-8A7D-F5C0793BE8AC ms.author: chcomley author: chcomley ms.topic: how-to @@ -12,7 +12,6 @@ monikerRange: '<= azure-devops' ms.date: 02/02/2023 --- - # Manage and organize queries in Azure Boards and Azure DevOps [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -20,240 +19,238 @@ ms.date: 02/02/2023 Organize your personal or shared queries by adding a query folder. You can then add queries to or move existing queries into those folders. You can create queries and query folders from the web portal or from a supported client, such as Visual Studio Team Explorer. -> [!NOTE] -> To create and manage queries in Visual Studio 2019, you need to [Set the Work Items experience](../work-items/set-work-item-experience-vs.md) to the legacy option. Also, you can perform bulk drag-and-drop of queries into query folders from Visual Studio but not from the web portal. +::: moniker range="azure-devops" - -[!INCLUDE [temp](../includes/prerequisites-queries.md)] +[!INCLUDE [note-new-boards-hub-default-images](../includes/note-new-boards-hub-default-images.md)] -## Open a query +::: moniker-end -[!INCLUDE [temp](../includes/open-queries.md)] +## Prerequisites +[!INCLUDE [temp](../includes/prerequisites-queries.md)] +## Open a query - - +[!INCLUDE [temp](../includes/open-queries.md)] -## Run, edit, and save a query +## Copy, edit, and save a query -The easiest way to define a query is to start with an existing shared query. -The following example shows how to find all closed bugs by modifying the -*Active Bugs* shared query provided with the Agile process template. Examples are based on the user interface provided through the web portal. +You can copy a query within the same project by selecting a query and saving it with a new name with the **Save as** option. +The easiest way to define a query is to start with an existing shared query. The following example shows how to find all closed bugs by modifying the *Active Bugs* shared query provided with the Agile process template. Examples are based on the user interface provided through the web portal. #### [Browser](#tab/browser/) -::: moniker range=">= azure-devops-2019" +::: moniker range="< azure-devops" 1. Open a shared query. For example, from the web portal, open the *Active Bugs* or similar flat list query. - > [!div class="mx-imgBorder"] - > ![Run Active bugs query](media/view-run-queries/run-active-bugs.png) + :::image type="content" source="media/view-run-queries/run-active-bugs.png" alt-text="Screenshot of the query selection."::: > [!TIP] > If you're working in Visual Studio Team Explorer, open the **Work** page to access your queries and shared queries. If Team Explorer isn't visible, choose **View>Team Explorer** from the top level menu. 1. Edit the query to find closed bugs and then run the query. - Use ![Insert new filter line](media/3.png) to insert a clause above the current clause. Use ![Remove this filter line](media/4.png) to delete a clause. Queries are automatically scoped to the current project. To find work items defined in several projects, see [Query across projects](using-queries.md#across-projects). - - > [!div class="mx-imgBorder"] - > ![Web portal, Queries page, new queries experience, Editor view of a Flat List Query](media/using-queries-new-vsts-exp.png) + Use ![Insert new filter line](media/3.png) to insert a clause above the current clause. Use ![Remove this filter line](media/4.png) to delete a clause. Queries are automatically scoped to the current project. To find work items defined in several projects, see [Query across projects](using-queries.md). -2. Save the query to your **My Queries** folder. + :::image type="content" source="media/using-queries-new-vsts-exp.png" alt-text="Screenshot of the query editor."::: - > [!div class="mx-imgBorder"] - > ![Save As query dialog, new experience](media/view-run-queries/save-as-new-exp.png) +1. Save the query to your **My Queries** folder. + :::image type="content" source="media/view-run-queries/save-as-new-exp.png" alt-text="Screenshot of Save As query dialog, new experience."::: + To save a query to the **Shared Queries** folder, you need to be a member of the [Project Administrators group](../../organizations/security/add-users-team-project.md), or have your **Contribute** permissions on the folder set to **Allow**. For more information, see [Set query permissions](set-query-permissions.md). ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="azure-devops" 1. Open a shared query. For example, from the web portal, open the *Active Bugs* or similar flat list query. - ![Web portal, Boards>Queries, Open Shared queries, Active Bugs](media/using-queries-active-bugs-ts.png) + :::image type="content" source="media/view-run-queries/select-active-bugs-new-boards-hubs.png" alt-text="Screenshot of the query selection list."::: > [!TIP] - > If you're working in Visual Studio Team Explorer, open the **Work** page to access your queries and shared queries. If Team Explorer isn't visible, choose **View>Team Explorer** from the top level menu. + > If you're working in Visual Studio Team Explorer, open the **Work** page to access your queries and shared queries. If Team Explorer isn't visible, choose **View > Team Explorer** from the top level menu. 1. Edit the query to find closed bugs and then run the query. - Use ![Insert new filter line](media/3.png) to insert a clause above the current clause. Use ![Remove this filter line](media/4.png) to delete a clause. Queries are automatically scoped to the current project. To find work items defined in several projects, see [Query across projects](using-queries.md#across-projects). - - ![Web portal, Queries page, Editor view of a Flat List Query](media/query-active-bugs-editor-vso.png) + Use ![Insert new filter line](media/3.png) to insert a clause above the current clause. Use ![Remove this filter line](media/4.png) to delete a clause. Queries are automatically scoped to the current project. To find work items defined in several projects, see [Query across projects](using-queries.md). -2. Save the query to your **My Queries** folder. - - ![Save Query As](media/6.png) + :::image type="content" source="media/view-run-queries/edit-query-new-boards-hubs.png" alt-text="Screenshot of edit query dialog."::: - To save a query to the **Shared Queries** folder, you need to be a member of the [Project Administrators group](../../organizations/security/add-users-team-project.md), or have your **Contribute** permissions on the folder set to **Allow**. For more information, see [Set query permissions](set-query-permissions.md). +1. Select **Save as** in the more actions ![More actions](../../media/icons/more-actions.png) menu. -::: moniker-end + > [!NOTE] + > If the **New Boards Hubs** feature is disabled, the **Save As** selection is at the top of the page. +1. Save the query to your **My Queries** folder. -#### [Visual Studio](#tab/visual-studio/) - -To save a query as a new query, open the query results and then from the toolbar choose File>Save *QueryName* As.... + :::image type="content" source="media/view-run-queries/save-as-new-boards-hubs.png" alt-text="Screenshot of Save As query dialog, new boards hubs experience."::: -:::image type="content" source="media/organize-queries/visual-studio-save-query-as.png" alt-text="Screenshot, Visual Studio, File menu, save query as."::: + To save a query to the **Shared Queries** folder, you need to be a member of the [Project Administrators group](../../organizations/security/add-users-team-project.md), or have your **Contribute** permissions on the folder set to **Allow**. For more information, see [Set query permissions](set-query-permissions.md). -Specify the file name and folder location to use to save the query. +::: moniker-end -:::image type="content" source="media/organize-queries/visual-studio-save-query-as-dialog.png" alt-text="Screenshot, Visual Studio, Save Query As dialog."::: +#### [Visual Studio](#tab/visual-studio/) +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md?view=azure-devops&preserve-view=true&tabs=visual-studio#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. -To save the query as a `.wiq` file, choose the **File** radio button and specify the file location. +To save a query as a new query, open the query results and then from the toolbar choose File>Save *QueryName* As.... -:::image type="content" source="media/organize-queries/visual-studio-save-query-as-wiq-file.png" alt-text="Screenshot, Visual Studio, Save Query As a WIQ file dialog."::: +:::image type="content" source="media/organize-queries/visual-studio-save-query-as.png" alt-text="Screenshot of Visual Studio > File menu save query as selection."::: +Specify the query name and folder location for the query. +:::image type="content" source="media/organize-queries/visual-studio-save-query-as-dialog.png" alt-text="Screenshot of Visual Studio, Save Query As dialog."::: -* * * +To save the query as a `.wiq` file, choose the **File** radio button and specify the file location. +:::image type="content" source="media/organize-queries/visual-studio-save-query-as-wiq-file.png" alt-text="Screenshot of Visual Studio, Save Query As a WIQ file dialog."::: - +--- ## Rename or delete a query - - #### [Browser](#tab/browser/) -::: moniker range=">= azure-devops-2019" - -From either the **Favorites** or **All** page, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon of a query to run, edit, rename, or delete the query. +From either the **Favorites** or **All** page, choose the :::image type="icon" source="../media/icons/more-actions.png" border="false"::: actions icon of a query to run, edit, rename, or delete the query. -![New query experience, Favorites page, query context menu](media/view-run-queries/query-context-menu-favorites-page.png) +::: moniker range="< azure-devops" -For shared queries, you can also choose to do one of these tasks: -- **Add to team queries**: Select the team to add the query as a team favorite -- **Security...**: to set permissions for the query. For more information, see [Set query permissions](set-query-permissions.md). -- **Add to dashboard**: Adds a Query tile widget to the team dashboard you select. For more information, see [Add widgets to a dashboard](../../report/dashboards/add-widget-to-dashboard.md). +![Screenshot of new query experience, Favorites page, query context menu.](media/view-run-queries/query-context-menu-favorites-page.png) ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="azure-devops" -Choose the :::image type="icon" source="../media/icons/context_menu.png" border="false"::: context menu icon of a query to edit, rename, or delete the query. - -![Web portal, Boards>Queries, Open Shared queries, Active Bugs](media/using-queries-active-bugs-ts.png) +:::image type="content" source="media/view-run-queries/query-context-menu-new-boards-hubs.png" alt-text="Screenshot of query context menu."::: ::: moniker-end + +For shared queries, you can also choose to do one of these tasks: +- **Add to team queries**: Select the team to add the query as a team favorite +- **Security...**: to set permissions for the query. For more information, see [Set query permissions](set-query-permissions.md). +- **Add to dashboard**: Adds a Query tile widget to the team dashboard you select. For more information, see [Add widgets to a dashboard](../../report/dashboards/add-widget-to-dashboard.md). #### [Visual Studio](#tab/visual-studio/) +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md?view=azure-devops&preserve-view=true&tabs=visual-studio#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. From the **Work Items** page, open the context menu for the query you want to run, edit, rename, or delete and choose the corresponding option. -:::image type="content" source="../media/team-explorer/open-query-from-team-explorer.png" alt-text="Screenshot, Visual Studio, open context menu and choose option."::: - +:::image type="content" source="../media/team-explorer/open-query-from-team-explorer.png" alt-text="Screenshot of Visual Studio, open context menu and choose option."::: -* * * +--- ## Add a query folder and move items into a folder > [!TIP] > You need **Delete** permissions to rename or move a shared query or folder, and **Contribute** permissions for the folder where you move the query to. To view or set permissions, see [Set permissions on queries and query folders](set-query-permissions.md). - - #### [Browser](#tab/browser/) -::: moniker range=">= azure-devops-2019" +::: moniker range="< azure-devops" -You add query folders from the **Boards>Queries>All** page. +You add query folders from the **Boards > Queries > All** page. 1. Choose **All**. Expand **My Queries** or Shared Queries depending on where you want to add a query folder. -1. To add a folder, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon for an existing folder or the top container folder, and choose **New folder**. +1. To add a folder, choose actions icon for an existing folder or the top container folder, and choose **New folder**. - > [!div class="mx-imgBorder"] - > ![Open Actions menu, choose New folder](media/organize-queries/select-new-folder.png) + :::image type="content" source="media/organize-queries/select-new-folder.png" alt-text="Screenshot of Open Actions menu, choose New folder."::: -2. Enter the name for the folder in the New folder dialog. If you want to change the location of the folder, select it from the Folder drop down menu. +1. Enter the name for the folder in the New folder dialog. If you want to change the location of the folder, select it from the Folder drop down menu. - Enter the name and location of the folder. + :::image type="content" source="media/organize-queries/new-folder-dialog.png" alt-text="Screenshot of new folder dialog."::: -3. To move items into a folder, drag-and-drop a query onto the folder. From the web portal, you can only drag a single query from outside a folder into a folder. +1. To move items into a folder, drag-and-drop a query onto the folder. From the web portal, you can only drag a single query from outside a folder into a folder. - Optionally, you can choose **More commands** :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: for an existing query, choose **Edit**, and then choose **Save As**. In the Save query as dialog, choose the folder you want to save the query in. + Optionally, you can choose **More commands** :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: for an existing query, choose **Edit**, and then choose **Save As**. In the **Save query** as dialog, choose the folder you want to save the query in. - Save query as dialog + :::image type="content" source="media/organize-queries/save-query-as-dialog.png" alt-text="Screenshot of Save query as dialog."::: ::: moniker-end +::: moniker range="azure-devops" -::: moniker range="tfs-2018" - -You add query folders from the **Boards>Queries** page. - -1. To add a folder, choose the :::image type="icon" source="../media/icons/context_menu.png" border="false"::: context menu for an existing folder or the top container folder and select **New query folder**. - - Enter the name for the folder in the New query folder dialog. +You add query folders from the **Boards > Queries > All** page. + +1. Choose **All**. Expand **My Queries** or Shared Queries depending on where you want to add a query folder. + +1. To add a folder, choose **New folder**. - ![New query folder link on queries context menu](media/set-query-perm-new-folder.png) + :::image type="content" source="media/view-run-queries/select-new-folder-new-boards-hubs.png" alt-text="Screenshot of New folder selection."::: + +1. Enter the name for the folder in the New folder dialog. If you want to change the location of the folder, select it from the Folder drop down menu. -1. To move items into a folder, drag-and-drop a query onto the folder. From the web portal, you can only drag a single query from outside a folder into a folder. + :::image type="content" source="media/view-run-queries/new-folder-dialog-new-boards-hubs.png" alt-text="Screenshot of new folder dialog."::: - Optionally, you can choose the :::image type="icon" source="../media/icons/context_menu.png" border="false"::: context icon for an existing query and choose **Rename**. In the Rename query dialog, select the folder you want to save the query in. +1. To move items into a folder, drag-and-drop a query onto the folder. From the web portal, you can only drag a single query from outside a folder into a folder. - ![Rename query dialog](media/organize-queries/rename-query-old-experience.png) + Optionally, you can choose **More commands** :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: for an existing query, choose **Edit**, and then choose **Save As**. In the **Save query** as dialog, choose the folder you want to save the query in. + + :::image type="content" source="media/view-run-queries/save-as-dialog-new-boards-hubs.png" alt-text="Screenshot of Save query as dialog."::: ::: moniker-end - #### [Visual Studio](#tab/visual-studio/) -> [!NOTE] -> To create and manage queries in Visual Studio 2019, you need to [Set the Work Items experience](../work-items/set-work-item-experience-vs.md) to the legacy option. +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md?view=azure-devops&preserve-view=true&tabs=visual-studio#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. All changes you make to your query folder structure in Visual Studio appear in the web portal by refreshing your browser. - 1. From the **Work Items** page, open the context menu for **My Queries**, **Team Queries**, or an existing query folder, and choose **New Folder**. - :::image type="content" source="media/organize-queries/visual-studio-new-folder.png" alt-text="Screenshot, Visual Studio, open context menu and choose New Folder."::: + :::image type="content" source="media/organize-queries/visual-studio-new-folder.png" alt-text="Screenshot of Visual Studio, open context menu and choose New Folder."::: - A **New Folder** is added under the area you selected. Select the folder to rename it. + A **New Folder** is added under the area you selected. To rename a folder, select the folder. -1. To move queries into a folder, drag-and-drop a query onto the folder. You can select multiple queries and drag them into a folder or from one folder into another folder. +1. To move queries into a folder, drag-and-drop a query onto the folder. You can select multiple queries and drag them into a folder or from one folder into another folder. -* * * +--- - - - - ## Save a query as a team favorite -To save a shared query as a team favorite, you must be a member of the team. +To save a shared query as a team favorite, be a member of the team. -To add a query to a dashboard, open the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon (or :::image type="icon" source="media/22.png" border="false"::: context icon) menu for the query and [add it to a specific dashboard](../../report/dashboards/dashboards.md) or as a team favorite. +You can add a shared query to team favorites. Share queries with your team by adding them to a folder under the **Shared Queries** container. To save a query to a **Shared Queries** folder, get added to the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) or have your [permissions set for a folder under Shared Queries](set-query-permissions.md). -Share queries with your team by adding them to a folder under the **Shared Queries** container. To save a query to a **Shared Queries** folder, get added to the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) or have your [permissions set for a folder under Shared Queries](set-query-permissions.md). +You can only add shared queries as team favorites if you have [team administrator or project administrator permissions](../../organizations/settings/manage-teams.md). -You can only add shared queries to dashboards or as team favorites, and only if you have [team administrator or project administrator permissions](../../organizations/settings/manage-teams.md). +::: moniker range="< azure-devops" -1. To save a query as a team favorite, open :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **More actions** or :::image type="icon" source="media/22.png" border="false"::: the context menu for the query from the **Queries** page. +1. To save a query as a team favorite, open **More actions** :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: or the :::image type="icon" source="media/22.png" border="false"::: context menu for the query from the **Queries** page. 1. Choose **Add to team favorites**, and then select from the teams listed. Only teams for which you're a member are listed. :::image type="content" source="media/organize-queries/save-query-team-favorite.png" alt-text="Screenshot of Save query as a team favorite."::: +::: moniker-end + +::: moniker range="azure-devops" - +1. To save a query as a team favorite, open the **More actions** :::image type="icon" source="../media/icons/more-actions.png" border="false"::: context menu for the query from the **Shared Queries** on the **Queries** page. + +1. Choose **Add to team favorites**, and then select from the teams listed. Only teams for which you're a member are listed. + + :::image type="content" source="media/organize-queries/save-query-team-favorite-new-boards-hubs.png" alt-text="Screenshot of Save query as a team favorite."::: + +::: moniker-end ## Add a query tile to a dashboard A query tile displays a count of the work items in a query. You can also quickly open the query from the dashboard. You can add a query tile to a dashboard from the **Queries** page using the following steps, or by following the steps outlined in [Add widgets to a dashboard](../../report/dashboards/add-widget-to-dashboard.md). > [!NOTE] -> You can only add a shared query to a dashboard. And, to add or edit a widget of a team dashboard, you must be a member of the team or be [granted permissions to edit the dashboard](../../report/dashboards/dashboard-permissions.md). +> Be a member of the team or be [granted permissions to edit the dashboard](../../report/dashboards/dashboard-permissions.md). + +::: moniker range="< azure-devops" -1. To add a query to a dashboard from the **Queries** page, open the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon (or :::image type="icon" source="media/22.png" border="false"::: context icon) menu for the query. +1. To add a query to a dashboard from the **Queries** page, open the **More actions** menu :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon (or :::image type="icon" source="media/22.png" border="false"::: context icon) for the query. :::image type="content" source="media/organize-queries/save-query-dashboard.png" alt-text="Screenshot of More actions menu, select Add to dashboard."::: @@ -264,6 +261,24 @@ A query tile displays a count of the work items in a query. You can also quickly 1. Open the dashboard, and verify the query tile was added. You can configure the query tile to change the default color and to specify the color for the tile based on a conditional rule you specify. :::image type="content" source="media/organize-queries/configure-query-tile-widget.png" alt-text="Screenshot of Configure dialog for query tile widget."::: + +::: moniker-end + +::: moniker range="azure-devops" + +1. To add a query to a dashboard from the **Queries** page, open the **More actions** menu :::image type="icon" source="../media/icons/more-actions.png" border="false"::: for the query. + + :::image type="content" source="media/organize-queries/save-query-dashboard-new-boards-hubs.png" alt-text="Screenshot of More actions menu, select Add to dashboard."::: + +1. From the **Select a dashboard** dialog, choose the dashboard you want to add the query to. + + :::image type="content" source="media/organize-queries/select-dashboard.png" alt-text="Screenshot of Select a dashboard dialog."::: + +1. Open the dashboard, and verify the query tile was added. You can configure the query tile to change the default color and to specify the color for the tile based on a conditional rule you specify. + + :::image type="content" source="media/organize-queries/configure-query-tile-widget.png" alt-text="Screenshot of Configure dialog for query tile widget."::: + +::: moniker-end ## Related articles @@ -271,4 +286,3 @@ A query tile displays a count of the work items in a query. You can also quickly - [Set query permissions](set-query-permissions.md) - [Keyboard shortcuts](../../project/navigation/keyboard-shortcuts.md) - [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) - diff --git a/docs/boards/queries/planning-ranking-priorities.md b/docs/boards/queries/planning-ranking-priorities.md index 6169cfbc1f3..6d9a80604a8 100644 --- a/docs/boards/queries/planning-ranking-priorities.md +++ b/docs/boards/queries/planning-ranking-priorities.md @@ -12,25 +12,27 @@ monikerRange: '<= azure-devops' ms.date: 05/24/2022 --- -# Query by rank and picklist value in Azure DevOps and Azure Boards +# Query by rank and picklist value [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You use planning, ranking, and priority fields to specify which work the team should complete first. By ranking and prioritizing work items, all team members gain an understanding of the relative importance of the work that they must accomplish. +You use planning, ranking, and priority fields to determine the order in which your team should complete work items. By effectively ranking and prioritizing tasks, all team members understand the relative importance of each item they need to accomplish. -You rank and prioritize work items when you [Create your backlog](../backlogs/create-your-backlog.md). +Rank and prioritize work items when you [create your backlog](../backlogs/create-your-backlog.md). + +## Prerequisites + +[!INCLUDE [prerequisites-queries](../includes/prerequisites-queries.md)] ## Supported operators and macros -Query clauses that specify a string or integer field can use the operators listed below. -- = , <> , > , < , >= , <= +Query clauses that specify a string or integer field can use the following operators: + +- = , `<>` , `>` , `<` , `>=` , `<=` - =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field] - In, Not In - Was Ever - - - ## Picklist query examples Most of the planning fields described in the next section are either an integer or string field. For example queries of numeric or rich-text fields, see [Query by numeric fields](query-numeric.md) and [Query by titles, IDs, and rich-text fields](titles-ids-descriptions.md). @@ -77,8 +79,8 @@ To use the **In** and **Not In** operators, enter the names or labels of items t :::row-end::: --- - - + + ## Fields used to plan and prioritize work @@ -115,7 +117,7 @@ The following table describes the fields that you can use to plan and prioritize **Blocked** :::column-end::: :::column span="2"::: - Indicates that no further work can be performed on the work item. If an issue has been opened to track a blocking problem, a link should be made to the issue. + Indicates that no further work can be performed on the work item. If an issue gets opened to track a blocking problem, a link should be made to the issue. - For the Scrum process, task work items: You can specify **Yes** or clear the field. - For the CMMI process work items: You can specify **Yes** or **No**. @@ -153,14 +155,14 @@ The following table describes the fields that you can use to plan and prioritize :::row-end::: :::row::: :::column span="1"::: - **Priority** 1 + **Priority** 1 :::column-end::: :::column span="2"::: A subjective rating of the bug, issue, task, or test case as it relates to the business. You can specify the following values: - - **1**: Highest priority, implement feature or fix as soon as possible. Product cannot ship without successful resolution. - - **2**: Medium priority. Product cannot ship without successful resolution, but it does not need to be addressed immediately. - - **3**: Low priority. Implementation or fix is optional based on resources, time, and risk. If product ships without successful resolution, document the issue in release notes as known issues. - - **4**: Lowest priority. Tracks an issue that basically does not affect usage (such as a small typo). + - **1**: Highest priority, implement feature, or fix as soon as possible. Product can't ship without successful resolution. + - **2**: Medium priority. Product can't ship without successful resolution, but it doesn't need to be addressed immediately. + - **3**: Low priority. Implementation or fix is optional, based on resources, time, and risk. If product ships without successful resolution, document the issue in release notes as known issues. + - **4**: Lowest priority. Tracks an issue that basically doesn't affect usage (such as a small typo). Reference name=Microsoft.VSTS.Common.Priority, Data type=Integer :::column-end::: :::column span="1"::: @@ -169,7 +171,7 @@ The following table describes the fields that you can use to plan and prioritize :::row-end::: :::row::: :::column span="1"::: - **Risk** + **Risk** :::column-end::: :::column span="2"::: A subjective rating of the relative uncertainty around the successful completion of a user story. @@ -206,7 +208,7 @@ The following table describes the fields that you can use to plan and prioritize **Stack Rank** 2 :::column-end::: :::column span="2"::: - A number, assigned by a background process, used to track the list order of items on a backlog or board in the web portal. To learn more about how this field is used, see [Use backlogs for effective project management, Backlog priority or stack rank order](../backlogs/backlogs-overview.md#backlog-priority-or-stack-rank-order). + A number, assigned by a background process, used to track the list order of items on a backlog or board in the web portal. To learn more about how this field is used, see [Use backlogs for effective project management](../backlogs/backlogs-overview.md#backlog-priority-or-stack-rank-order). Reference name=Microsoft.VSTS.Common.StackRank, Data type=Double :::column-end::: @@ -265,7 +267,7 @@ The following table describes the fields that you can use to plan and prioritize **Notes:** 1. To change the menu selection, see [Add and manage fields (Inherited process)](../../organizations/settings/work/customize-process-field.md) or [Add or modify a field, customize a picklist (On-premises XML process)](../../reference/add-modify-field.md). -2. The sequence of items on a product backlog page is determined according to where you have added or dragged the items. As you drag items, a background process updates either the Backlog Priority (Scrum) or Stack Rank (Agile, Basic, CMMI) field. These fields determine the order in which backlog items appear on a backlog page. They are assigned to `type="Order"` in the ProcessConfiguration file. +2. The sequence of items on a product backlog page is determined according to where you added or dragged the items. As you drag items, a background process updates either the Backlog Priority (Scrum) or Stack Rank (Agile, Basic, CMMI) field. These fields determine the order in which backlog items appear on a backlog page. They're assigned to `type="Order"` in the ProcessConfiguration file. ## More about Backlog Priority or Stack Rank fields diff --git a/docs/boards/queries/query-by-area-iteration-path.md b/docs/boards/queries/query-by-area-iteration-path.md index eefc8a35ac6..e3893689ba5 100644 --- a/docs/boards/queries/query-by-area-iteration-path.md +++ b/docs/boards/queries/query-by-area-iteration-path.md @@ -12,7 +12,6 @@ monikerRange: '<= azure-devops' ms.date: 10/24/2021 --- - # Query by area or iteration path [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -21,9 +20,11 @@ The Area Path and Iteration Path are two fields that appear on the work tracking To better understand how to work with area and iteration paths, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). +## Prerequisites -[!INCLUDE [temp](../includes/note-macro-web-portal.md)] +[!INCLUDE [prerequisites-queries](../includes/prerequisites-queries.md)] +[!INCLUDE [temp](../includes/note-macro-web-portal.md)] ## Supported operators and macros @@ -39,7 +40,6 @@ When creating queries and specifying the Area Path and Iteration Path fields, yo > | `Under` | Specify all paths under a select area or iteration path. | > | `Not Under` | Exclude items assigned under a specific area or iteration path. | - Along with these operators, you can use the following macros when you select the Iteration Path. For examples, see [Query by date or current iteration](query-by-area-iteration-path.md). > [!div class="mx-tdCol2BreakAll"] @@ -60,7 +60,6 @@ You can specify to filter for work items assigned to several area paths by using > [!div class="mx-imgBorder"] > ![Query on Area Path for several areas](media/query-area-iteration/query-with-in-operator.png) - ## Node Name and keyword-based queries Use the **Node Name** field to filter on work items assigned to area paths based on a keyword using the **Contains** operator. The **Node Name** specifies the last node of an **Area Path**, which corresponds to the last node in the tree hierarchy. @@ -80,10 +79,8 @@ Here's another example that uses the **Node Name** and the **In** operator. > [!div class="mx-imgBorder"] > ![Query on Node Name for several areas](media/query-area-iteration/query-with-in-operator-node-name.png) - - -::: moniker range=">= azure-devops-2019" - +::: moniker range="<=azure-devops" + ## Team area path queries @@ -95,7 +92,7 @@ Use the @TeamAreas macro to quickly find items assigned to the ::: moniker-end - + ## Classification field reference @@ -122,7 +119,6 @@ The following fields don't appear on work item forms but are tracked for each wo The default reportable type is none. Area ID and Iteration ID are indexed, Node Name isn't. To learn more about field attributes, see [Work item fields and attributes](../work-items/work-item-fields.md). - ## Related articles - [Query quick reference](query-index-quick-ref.md) @@ -130,6 +126,5 @@ The default reportable type is none. Area ID and Iteration ID are indexed, Node - [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md) - [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md) - [!INCLUDE [temp](../includes/rest-apis-queries.md)] diff --git a/docs/boards/queries/query-by-date-or-current-iteration.md b/docs/boards/queries/query-by-date-or-current-iteration.md index 203654231a9..791fe89f85f 100644 --- a/docs/boards/queries/query-by-date-or-current-iteration.md +++ b/docs/boards/queries/query-by-date-or-current-iteration.md @@ -1,7 +1,7 @@ --- title: Query by date or current iteration in Azure Boards titleSuffix: Azure Boards -description: Learn how to query for work items based on a date, a team's current iteration, or a sliding window of sprints in Azure Boards and Azure DevOps +description: Learn how to query for work items based on a date, a team's current iteration, or a sliding window of sprints in Azure Boards. ms.custom: boards-queries ms.service: azure-devops-boards ms.assetid: 95D9F558-E3C4-4D5F-BB69-76A3BD7625D8 @@ -9,32 +9,33 @@ ms.author: chcomley author: chcomley ms.topic: example-scenario monikerRange: '<= azure-devops' -ms.date: 10/06/2022 +ms.date: 10/15/2024 +#customer intent: As a team member, I want to learn how to query work items in Azure Boards so I can find items based on when they were created, which iteration they belong to, or other factors. --- -# Query by date or current iteration in Azure Boards +# Query by date or current iteration [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -To list work items based on when they were created, closed, resolved, or changed—you can specify a date or use a supported macro. Use the `@Today` macro and specify a plus or minus number of days for relative dates. For queries that list work items based on their assignment to a team's current sprint, use `@CurrentIteration`. +In this article, learn how to list work items based on when they were created, closed, resolved, or changed. You can specify a date or use a supported macro. Use the `@Today` macro and specify a plus or minus number of days for relative dates. For queries that list work items based on their assignment to a team's current sprint, use `@CurrentIteration`. -For example, you can find work items that were modified in the last three days with the following query. +For example, find work items that were modified in the last three days with the following query. -::: moniker range=">= azure-devops-2019" -:::image type="content" source="media/example-work-item-queries/query-changed-date-last-3-days.png" alt-text="Screenshot of Query Editor, Changed Date >= 3."::: +::: moniker range="<=azure-devops" +:::image type="content" source="media/example-work-item-queries/query-changed-date-last-3-days.png" alt-text="Screenshot that shows Query Editor showing the Changed Date field set to >= 3."::: ::: moniker-end -::: moniker range="tfs-2018" -![Screenshot of query editor, filter based on recent changes.](media/query-by-date-example.png) -::: moniker-end -::: moniker range=">= azure-devops-2019" -Also, you can use the `CurrentIteration +/- _n_` macro to create queries based on a sliding window of team iterations. + +::: moniker range="<=azure-devops" +Also, you can use the `CurrentIteration +/- _n_` macro to create queries based on a sliding window of team iterations. ::: moniker-end +## Prerequisites -## Supported operators and macros +[!INCLUDE [prerequisites-queries](../includes/prerequisites-queries.md)] -Query clauses that specify a **DateTime** field or the **Iteration Path** can use the operators and macros listed in the following table. - +## Supported operators and macros + +Query clauses that specify a **DateTime** field or the **Iteration Path** field can use the operators and macros listed in the following table. --- :::row::: @@ -46,92 +47,66 @@ Query clauses that specify a **DateTime** field or the **Iteration Path** can us :::column-end::: :::row-end::: --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: - **DateTime** + DateTime :::column-end::: :::column span="3"::: `= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever` - **Macros**: `@StartOfDay`, `@StartOfWeek`, `@StartOfMonth`, `@StartOfYear`, and `@Today`. - You can use +/- _n_ with each of the supported macros. + **Macros**: `@StartOfDay`, `@StartOfWeek`, `@StartOfMonth`, `@StartOfYear`, and `@Today`. + You can use `+/- _n_` with each of the supported macros. :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **TreePath** + TreePath :::column-end::: :::column span="3"::: - = , <> , Under, Not Under - **Macros**: `@CurrentIteration`2 and `@CurrentIteration +/- n`3 valid with the **Iteration Path** field. + =, <>, Under, Not Under + **Macros**: `@CurrentIteration`1 and `@CurrentIteration +/- n`2 valid with the **Iteration Path** field. :::column-end::: :::row-end::: --- ::: moniker-end -::: moniker range="tfs-2018" -:::row::: - :::column span="1"::: - **DateTime** - :::column-end::: - :::column span="3"::: - `= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever` - **Macros**: **@Today** which you can specify with +/- _n_ integer. - :::column-end::: -:::row-end::: - --- -:::row::: - :::column span="1"::: - **TreePath** - :::column-end::: - :::column span="3"::: - `=`, `<>` , `Under`, `Not Under` - **Macros**: `@CurrentIteration`2 is valid with the **Iteration Path** field - :::column-end::: -:::row-end::: ---- -::: moniker-end - - -#### Notes: -1. The `@StartOfDay`, `@StartOfWeek`, `@StartOfMonth`, `@StartOfYear` macros are supported for Azure DevOps Server 2019.1 and later versions, and only when run from the web portal. -2. The `@CurrentIteration +/- n` macro is supported for Azure DevOps Server 2019 and later versions, and only when run from the web portal. +Notes: +1. The `@StartOfDay`, `@StartOfWeek`, `@StartOfMonth`, and `@StartOfYear` macros are supported for Azure DevOps Server 2019.1 and later versions. They're only supported when run from the web portal. +1. The `@CurrentIteration +/- n` macro is supported for Azure DevOps Server 2019 and later versions and is only supported when run from the web portal. -> [!TIP] -> The `WasEver` operator can be used with the **Iteration Path** field but only when defined through the WIQL syntax. For an example, see [Work Item Query Language (WIQL) syntax reference](wiql-syntax.md#asof-historical-queries). - +> [!TIP] +> The `WasEver` operator can be used with the **Iteration Path** field but only when defined through the WIQL syntax. For an example, see [Work Item Query Language (WIQL) syntax reference](wiql-syntax.md). [!INCLUDE [date-time-pattern](../includes/date-time-pattern.md)] - - + -## Client restrictions on the use of the `@CurrentIteration` macros +## Client restrictions on the use of the @CurrentIteration macros You can use the `@CurrentIteration` macro in a query from the following clients: - Web portal that connects to Azure Boards -- Visual Studio 2019 or later versions connected to Azure Boards -- Using the REST API. +- Visual Studio 2019 or later versions connected to Azure Boards +- The REST API -You can use the `@CurrentIteration +/- n` macro in a query against Azure Boards, Azure DevOps Server 2019, and later versions, and with a REST API that includes the team as a parameter, for example, `@CurrentIteration('[Project]/Team')`. - +You can use the `@CurrentIteration +/- n` macro in a query against Azure Boards, Azure DevOps Server 2019, and later versions, and with a REST API that includes the team as a parameter. An example is `@CurrentIteration('[Project]\Team')`. -An error occurs if you open a query that contains the `@CurrentIteration` macro in earlier versions of Visual Studio, or from Excel or Project. Also, you can't use the macro when [copying or cloning test suites and test cases](/previous-versions/azure/devops/test/mtm/copying-and-cloning-test-suites-and-test-cases), [defining alerts](../../organizations/notifications/about-notifications.md), or with [REST APIs](/rest/api/azure/devops/). +An error occurs if you open a query that contains the `@CurrentIteration` macro in earlier versions of Visual Studio, or from Microsoft Excel or Microsoft Project. Also, you can't use the macro when [copying or cloning test suites and test cases](/previous-versions/azure/devops/test/mtm/copying-and-cloning-test-suites-and-test-cases), [defining alerts](../../organizations/notifications/about-notifications.md), or with [REST APIs](/rest/api/azure/devops/). +## Date-based queries -## Date-based queries +Filter for work items by the date on which they were changed or for a specific time period. Limit the scope of your query. This approach can help with performance by only returning results that fit the date range that you include. If you're new to creating queries, see [Define a work item query](using-queries.md). -You can filter for work items by the date on which they were changed or for a specific time period. Limiting the scope of your query can help with performance by only returning results that fit the date range that you include. If you're new to creating queries, see [Use the query editor to list and manage queries](using-queries.md). +Not all fields are valid for all work item types. Jump to [date fields](#date_fields) for the set of fields you can include in queries and the work item types to which they apply. -Not all fields are valid for all work item types. Jump to [date fields](#date_fields) for the set of fields you can include in queries and which work item types they apply to. +> [!TIP] +> +> - Remember to enter dates in the **Date Pattern** field that you set for your [personal profile](../../organizations/settings/set-your-preferences.md). +> - To understand how `AND/OR` clauses are grouped, see [Group clauses](../queries/using-queries.md#group-clauses). To view the WIQL syntax for a query, install the [WIQL editor extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.wiql-editor), which allows you to see the WIQL version of any Query Editor entry. -> [!TIP] -> Remember to enter dates in the **Date Pattern** you set for your [personal profile](../../organizations/settings/set-your-preferences.md). - --- :::row::: :::column span="1"::: @@ -144,84 +119,76 @@ Not all fields are valid for all work item types. Jump to [date fields](#date_fi --- :::row::: :::column span="1"::: - Items created in the last 30 days + Items created in the last 30 days. :::column-end::: :::column span="2"::: - :::image type="content" source="media/q-by-date-last-30-days.png" alt-text="Screenshot of query editor, Clause for finding items created in the last 30 days."::: + :::image type="content" source="media/q-by-date-last-30-days.png" alt-text="Screenshot that shows the Query Editor clause for finding items created in the last 30 days."::: :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - Items modified on a specific date + Items modified on a specific date. :::column-end::: :::column span="2"::: - :::image type="content" source="media/q-by-specific-date.png" alt-text="Screenshot of query editor, Clause for finding items changed on a specific date."::: + :::image type="content" source="media/q-by-specific-date.png" alt-text="Screenshot that shows the Query Editor clause for finding items changed on a specific date."::: :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - Items resolved today + Items resolved today. :::column-end::: :::column span="2"::: - :::image type="content" source="media/q-by-resolved-today.png" alt-text="Screenshot of query editor, Clause for finding items resolved today."::: + :::image type="content" source="media/q-by-resolved-today.png" alt-text="Screenshot that shows the Query Editor clause for finding items resolved today."::: :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - Items closed within a specified time period + Items closed within a specified time period. :::column-end::: :::column span="2"::: - :::image type="content" source="media/q-by-closed-time-period.png" alt-text="Screenshot of query editor, Clause for finding items closed within a specified time period."::: + :::image type="content" source="media/q-by-closed-time-period.png" alt-text="Screenshot that shows the Query Editor clause for finding items closed within a specified time period."::: :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - Items that haven't been closed (Closed Date is null) + Items that aren't closed. Closed Date is null. :::column-end::: :::column span="2"::: - :::image type="content" source="media/q-closed-date-null.png" alt-text="Screenshot of query editor, Clause for finding items whose Closed Date is empty or null."::: + :::image type="content" source="media/q-closed-date-null.png" alt-text="Screenshot that shows the Query Editor clause for finding items whose Closed Date is empty or null."::: :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - Items whose status was updated within the last week + Items whose status was updated within the last week. :::column-end::: :::column span="2"::: - :::image type="content" source="media/q-by-state-changed-within-last-week.png" alt-text="Screenshot of query editor, Clause for items whose status was updated within the last week."::: + :::image type="content" source="media/q-by-state-changed-within-last-week.png" alt-text="Screenshot that shows the Query Editor clause for items whose status was updated within the last week."::: :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - Items closed during the current sprint (the macro references the sprint defined for the current team context) + Items closed during the current sprint. The `` macro refers to the sprint defined for the current team context. :::column-end::: :::column span="2"::: - :::image type="content" source="media/q-by-done-current-iteration.png" alt-text="Screenshot of query editor, Clause for items closed during the current sprint."::: + :::image type="content" source="media/q-by-done-current-iteration.png" alt-text="Screenshot that shows the Query Editor clause for items closed during the current sprint."::: :::column-end::: :::row-end::: --- -[!INCLUDE [temp](../includes/query-clause-tip.md)] - - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Create start of day, week, month, or year date-based queries -The following examples show how to use the **StartOf...** macros to filter for work items with various offsets. For more examples of using these macros, see [WIQL syntax](wiql-syntax.md#start-of). -::: moniker-end - -::: moniker range="azure-devops-2019" -> [!NOTE] -> Requires Azure DevOps Server 2019 Update 1 or later version. +The following examples show how to use the `StartOf...` macros to filter for work items with various offsets. For more information, see [Work Item Query Language (WIQL) syntax](wiql-syntax.md#start-of). ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: @@ -234,119 +201,103 @@ The following examples show how to use the **StartOf...** macros to filter for w --- :::row::: :::column span="1"::: - Bugs closed in the last two weeks + Bugs closed in the last two weeks. :::column-end::: :::column span="2"::: - :::image type="content" source="media/example-queries/close-date-last-2-weeks.png" alt-text="Screenshot of query editor, Clauses for finding bugs closed in the last two weeks."::: + :::image type="content" source="media/example-queries/close-date-last-2-weeks.png" alt-text="Screenshot that shows the Query Editor clause for finding bugs closed in the last two weeks."::: :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - Items modified in the last 10 days + Items modified in the last 10 days. :::column-end::: :::column span="2"::: - :::image type="content" source="media/example-queries/changed-date-last-10-days.png" alt-text="Screenshot of query editor, Clause for finding items changed in the last 10 days."::: + :::image type="content" source="media/example-queries/changed-date-last-10-days.png" alt-text="Screenshot that shows the Query Editor clauses for finding items changed in the last 10 days."::: :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - Features scheduled to be completed in the next three months + Features scheduled to be completed in the next three months. :::column-end::: :::column span="2"::: - :::image type="content" source="media/example-queries/start-month-target-date-3.png" alt-text="Clauses for features scheduled to be completed in the next 3 months."::: + :::image type="content" source="media/example-queries/start-month-target-date-3.png" alt-text="Screenshot that shows the Query Editor clauses for features scheduled to be completed in the next three months."::: :::column-end::: :::row-end::: --- - -Not all fields are valid for all work item types. Jump to [date fields](#date_fields) for the set of fields you can include in queries and which work item types they apply to. +Not all fields are valid for all work item types. Jump to [date fields](#date_fields) for the set of fields you can include in queries and the work item types to which they apply. ::: moniker-end ## Create queries for your team's current iteration - -If your team follows Scrum processes, you [schedule work to be completed in sprints](../sprints/define-sprints.md). You can track the progress of requirements, bugs, and other work to be completed in the current sprint using the **@CurrentIteration** macro. - -Any item assigned to a sprint that corresponds to the current iteration path for the team is found. For example, if a team is on Sprint 5, the query returns items assigned to Sprint 5. Later, when the team is working in Sprint 6, the same query returns items assigned to Sprint 6. -> [!NOTE] -> For the **@CurrentIteration** macro to work, the team must have selected an **Iteration Path** whose date range encompasses the current date. For more information, see [Define iteration paths (also referred to as sprints) and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md#activate). Also, queries that contain this macro are only valid when run from the web portal. -> -> See also [Client restrictions on the use of the @CurrentIteration macros](#current_sprint_restrict) later in this article. - -::: moniker range=">= azure-devops-2019" +If your team follows Scrum processes, you schedule work to be completed in sprints. You can track the progress of requirements, bugs, and other work to be completed in the current sprint by using the `@CurrentIteration` macro. For more information, see [Manage sprint timelines](../sprints/define-sprints.md). -Azure Boards adds a team parameter when you select the **@CurrentIteration** or **@CurrentIteration +/- _n_** macros. The team parameter is derived from your current [team context](#team_view). +The query finds any item assigned to a sprint that corresponds to the current iteration path for the team. For example, if a team is on Sprint 5, the query returns items assigned to Sprint 5. Later, when the team is working in Sprint 6, the same query returns items assigned to Sprint 6. -> [!div class="mx-imgBorder"] -> ![Query filter using the CurrentIteration macro with team parameter](media/query-date-iteration/at-current-with-team-parameter.png) +> [!NOTE] +> For the `@CurrentIteration` macro to work, the team must have selected an iteration path whose date range encompasses the current date. For more information, see [Select team sprints and set the default iteration path](../../organizations/settings/set-iteration-paths-sprints.md#select-team-sprints-and-set-the-default-iteration-path). Also, queries that contain this macro are only valid when run from the web portal. +> +> See also [Client restrictions on the use of the @CurrentIteration macros](#current_sprint_restrict) earlier in this article. -> [!TIP] -> If the **@CurrentIteration** macro isn't working, check that the [expected iteration is selected for your team and that dates have been set for it](../../organizations/settings/set-iteration-paths-sprints.md#activate). +::: moniker range="<=azure-devops" -To change the team parameter the system automatically sets, you choose it by entering the name of the team into the parameter field added below the **@CurrentIteration** macro. +Azure Boards adds a team parameter when you select the **@CurrentIteration** or **@CurrentIteration +/- _n_** macros. The team parameter derives from your current [team context](#team_view). -> [!div class="mx-imgBorder"] -> ![Choose team parameter](media/query-date-iteration/choose-team-parameter.png) +:::image type="content" source="media/query-date-iteration/at-current-with-team-parameter.png" alt-text="Screenshot that shows the Query filter by using the CurrentIteration macro with team parameter."::: -::: moniker-end +> [!TIP] +> If the `@CurrentIteration` macro isn't working, check that the expected iteration is selected for your team and that dates have been set for it. For more information, see [Select team sprints](../../organizations/settings/set-iteration-paths-sprints.md#select-team-sprints-and-set-the-default-iteration-path). -::: moniker range="tfs-2018" +To change the team parameter that the system automatically sets, choose it by entering the name of the team in the parameter field added below the **@CurrentIteration** macro. -Before creating or updating a query to use the **@CurrentIteration** macro, make sure you [select your team](#team_view). The **@CurrentIteration** macro references the current team selected in the web portal. - -> [!div class="mx-imgBorder"] -> ![Query filter using the CurrentIteration macro](media/query-date-iteration/at-current-no-team-specified.png) +:::image type="content" source="media/query-date-iteration/choose-team-parameter.png" alt-text="Screenshot that shows choosing a team parameter."::: ::: moniker-end - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -## Create a sliding window of your team's iterations query +## Create a sliding window of your team's iterations query -Use the **@CurrentIteration +/- n** macro when you want to track the work a team has planned for upcoming sprints and for understanding work that wasn't completed in previous sprints. +Use the `@CurrentIteration +/- n` macro when you want to track the work a team planned for upcoming sprints and for understanding work that wasn't completed in previous sprints. > [!NOTE] -> For the **@CurrentIteration +/- n** macro to work, the team must have selected **Iteration Paths** that meet the **+/- _n_** -> criteria and date ranges encompass the current date for the **@CurrentIteration**. For details about team selection of Iteration Paths, see [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md#activate). -> -> See also [Client restrictions on the use of the @CurrentIteration macros](#current_sprint_restrict) later in this article. +> For the `@CurrentIteration +/- n` macro to work, the team must have selected iteration paths that meet the `+/- n` +> criteria. Date ranges must encompass the current date for the `@CurrentIteration`. For more information about team selection of iteration paths, see [Select team sprints and set the default iteration path](../../organizations/settings/set-iteration-paths-sprints.md#select-team-sprints-and-set-the-default-iteration-path). +> +> See also [Client restrictions on the use of the @CurrentIteration macros](#current_sprint_restrict) earlier in this article. -Here we show how to list all User Stories and Bugs that are assigned to the sliding window that spans the last two, the current, and the next two sprints selected for the *Cloud Admin and Tools* team. +The following image shows how to list all User Story and Bug work item types that are assigned to the sliding window. The window spans the last two, the current, and the next two sprints selected for the Cloud Admin and Tools team. -> [!div class="mx-imgBorder"] -> ![CurrentIteration plus and minus clauses](media//query-date-iteration/sliding-window-iterations.png) +:::image type="content" source="media//query-date-iteration/sliding-window-iterations.png" alt-text="Screenshot that shows CurrentIteration plus and minus clauses."::: -To use this macro, the specified team must have [selected a set of sprints](../../organizations/settings/set-iteration-paths-sprints.md) that span the **+/- _n_** value entered for the macro. +To use this macro, the specified team must [select a set of sprints](../../organizations/settings/set-iteration-paths-sprints.md) that span the `+/- n` value entered for the macro. ::: moniker-end - -## List work items moved out of a sprint +## List work items moved out of a sprint -You can list work items that were defined for a sprint but later moved out using a query with a clause that contains the **Was Ever** operator for the **Iteration Path**. You can only construct this query using the [WIQL syntax](wiql-syntax.md). You can edit the WIQL syntax in the Query Editor by installing the [Wiql Editor Marketplace extension](https://marketplace.visualstudio.com/items?itemName=ottostreifel.wiql-editor). +List work items that were defined for a sprint but later moved out by using a query with a clause that contains the `Was Ever` operator for the **Iteration Path** field. You can only construct this query by using the [WIQL syntax](wiql-syntax.md). Edit the WIQL syntax in Query Editor by installing the [WIQL Editor Marketplace extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.wiql-editor). -For example, the following syntax queries for work items that meet the following criteria: -1. Defined in the current project -2. Work item type equals User Story or Bug -3. Work items are under the Fabrikam Fiber Web team Area Path -4. Work items aren't in a Closed, Completed, Cut, or Resolved state -5. Not in the current iteration path for the Fabrikam Fiber Web team -6. But were assigned to the current iteration path for the Fabrikam Fiber Web team -7. Are now assigned to the Current iteration +1 for the Fabrikam Fiber Web team -8. And were changed within the last 30 days (the length of the sprint) +For example, the following syntax queries for work items meet the following criteria: +- Defined in the current project. +- Work item type equals User Story or Bug. +- Work items are under the Fabrikam Fiber Web team Area Path. +- Work items aren't in a `Closed`, `Completed`, `Cut`, or `Resolved` state. +- Not in the current iteration path for the Fabrikam Fiber Web team. +- Were assigned to the current iteration path for the Fabrikam Fiber Web team. +- Are now assigned to the current iteration +1 for the Fabrikam Fiber Web team. +- Were changed within the last 30 days (the length of the sprint). -> [!div class="tabbedCodeSnippets"] ```WIQL SELECT [System.Id], @@ -374,32 +325,29 @@ WHERE ORDER BY [System.Id] ``` +The Query Editor view of the syntax appears as shown. -The Query Editor view of the syntax appears as shown. - -> [!NOTE] -> The Query Editor displays a :::image type="icon" source="../../media/icons/required-icon.png" border="false"::: information icon next to the **Was Ever** operator, indicating an issue with the clause. However, the query still runs and you can create query charts. However, to modify the query, you need to use the [WIQL editor](https://marketplace.visualstudio.com/items?itemName=ottostreifel.wiql-editor). - -:::image type="content" source="media/example-work-item-queries/query-work-items-moved-out-of-sprint.png" alt-text="Screenshot of Query Editor, Work Items moved out of a sprint."::: +> [!NOTE] +> The Query Editor displays a :::image type="icon" source="../../media/icons/required-icon.png" border="false"::: information icon next to the `Was Ever` operator, indicating an issue with the clause. However, the query still runs and you can create query charts. To modify the query, you *must* use the [WIQL Editor](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.wiql-editor). +:::image type="content" source="media/example-work-item-queries/query-work-items-moved-out-of-sprint.png" alt-text="Screenshot that shows Query Editor work items moved out of a sprint."::: - + -## List work items added to a sprint after the start date +## List work items added to a sprint after the start date -To list newly created work items added to a sprint after its start date, use a query similar to the one shown in the following image. This query works by filtering for work items assigned to the current sprint but were created after the start of the sprint date. In this example, this is achieved with the clause **created Date = @Today - 28**. +To list newly created work items added to a sprint after its start date, use a query similar to the one shown in the following image. This query works by filtering for work items assigned to the current sprint but were created after the start of the sprint date. Use the clause `created Date = @Today - 28`. -:::image type="content" source="media/example-work-item-queries/query-work-items-added-to-sprint.png" alt-text="Screenshot of Query Editor, Work Items newly created and added to a sprint after it's start date."::: +:::image type="content" source="media/example-work-item-queries/query-work-items-added-to-sprint.png" alt-text="Screenshot that shows Query Editor work items newly created and added to a sprint after its start date."::: -For other options for querying changes to sprint scope, see [About Sprints, Scrum and project management, Sprint scope change](../sprints/scrum-overview.md#sprint-scope-change). +For other options for querying changes to sprint scope, see [Sprint scope change](../sprints/scrum-overview.md#sprint-scope-change). - + ## Date and Iteration Path fields -You can use date fields to filter your queries. Some of these fields are populated with information as a work item progresses from one state to another. Several of these fields don't appear on the work item form, but are tracked for those work item types listed in the following table. - +Use **Date** fields to filter your queries. Some of these fields are populated with information as a work item progresses from one state to another. Several of these fields don't appear on the work item form, but they're tracked for those work item types listed in the following table. :::row::: :::column span="1"::: @@ -415,14 +363,15 @@ You can use date fields to filter your queries. Some of these fields are populat --- :::row::: :::column span="1"::: - Activated Date (Notes 1, and 2) + Activated Date (Notes 1 and 2) :::column-end::: :::column span="2"::: - The date and time when the work item was created or when its status was changed from closed, completed, or done to a new or active state. + The date and time when the work item was created or when its status was changed from `Closed`, `Completed`, or `Done` to a `New` or `Active` state. + Reference name=Microsoft.VSTS.Common.ActivatedDate, Data type=DateTime :::column-end::: :::column span="1"::: - Bug, Change Request, Epic, Feature, Issue, Product Backlog Item, Requirement, Review, Risk, Shared Step, Task, Test Case, User Story + Bug, Change Request, Epic, Feature, Issue, Product Backlog Item, Requirement, Review, Risk, Shared Step, Task, Test Case, User Story :::column-end::: :::row-end::: :::row::: @@ -430,8 +379,9 @@ You can use date fields to filter your queries. Some of these fields are populat Change Date :::column-end::: :::column span="2"::: - The date and time when a work item was modified. - Reference name=System.ChangedDate, Data type=DateTime + The date and time when a work item was modified. + + Reference name=System.ChangedDate, Data type=DateTime :::column-end::: :::column span="1"::: All @@ -442,7 +392,8 @@ You can use date fields to filter your queries. Some of these fields are populat Closed Date (Note 2) :::column-end::: :::column span="2"::: - The date and time when a work item was closed. + The date and time when a work item was closed. + Reference name=Microsoft.VSTS.Common.ClosedDate, Data type=DateTime :::column-end::: :::column span="1"::: @@ -454,7 +405,8 @@ You can use date fields to filter your queries. Some of these fields are populat Created Date :::column-end::: :::column span="2"::: - The date and time when a work item was created. + The date and time when a work item was created. + Reference name=System.CreatedDate, Data type=DateTime :::column-end::: :::column span="1"::: @@ -466,7 +418,8 @@ You can use date fields to filter your queries. Some of these fields are populat Due Date :::column-end::: :::column span="2"::: - The forecasted due date for an issue to be resolved. + The forecasted due date for an issue to be resolved. + Reference name=Microsoft.VSTS.Scheduling.DueDate, Data type=DateTime :::column-end::: :::column span="1"::: @@ -478,7 +431,8 @@ You can use date fields to filter your queries. Some of these fields are populat Finish Date (Note 3) :::column-end::: :::column span="2"::: - The date and time when the schedule indicates that the task is completed. + The date and time when the schedule indicates that the task is completed. + Reference name=Microsoft.VSTS.Scheduling.FinishDate, Data type=DateTime :::column-end::: :::column span="1"::: @@ -490,7 +444,8 @@ You can use date fields to filter your queries. Some of these fields are populat Iteration Path :::column-end::: :::column span="2"::: - Groups work items by named sprints or time periods. The iteration must be a valid node in the project hierarchy. You [define iteration paths for a project and select iteration paths for a team](../../organizations/settings/set-iteration-paths-sprints.md) define iteration paths for a project and select iteration paths for a team. + Groups work items by named sprints or time periods. The iteration must be a valid node in the project hierarchy. You [define iteration paths for a project and select iteration paths for a team](../../organizations/settings/set-iteration-paths-sprints.md). + Reference name=System.IterationPath, Data type=TreePath :::column-end::: :::column span="1"::: @@ -502,7 +457,8 @@ You can use date fields to filter your queries. Some of these fields are populat Resolved Date (Notes 1 and 2) :::column-end::: :::column span="2"::: - The date and time when the work item was moved into a Resolved state. + The date and time when the work item was moved into a `Resolved` state. + Reference name=Microsoft.VSTS.Common.ResolvedDate, Data type=DateTime :::column-end::: :::column span="1"::: @@ -516,9 +472,10 @@ You can use date fields to filter your queries. Some of these fields are populat :::column span="2"::: The date and time when the schedule indicates that the task starts. ::: moniker range="azure-devops" - > [!NOTE] - > [Delivery Plans](../plans/review-team-plans.md) uses the **Start Date** and **Target Date** to show the span of Features, Epics, and other portfolio backlog items. + > [!NOTE] + > [Delivery Plans](../plans/review-team-plans.md) uses the **Start Date** and **Target Date** fields to show the span of features, epics, and other portfolio backlog items. ::: moniker-end + Reference name=Microsoft.VSTS.Scheduling.StartDate, Data type=DateTime :::column-end::: :::column span="1"::: @@ -530,7 +487,8 @@ You can use date fields to filter your queries. Some of these fields are populat State Change Date :::column-end::: :::column span="2"::: - The date and time when the value of the State field changed. + The date and time when the value of the **State** field changed. + Reference name=Microsoft.VSTS.Common.StateChangeDate, Data type=DateTime :::column-end::: :::column span="1"::: @@ -542,11 +500,12 @@ You can use date fields to filter your queries. Some of these fields are populat Target Date :::column-end::: :::column span="2"::: - The date by which a feature, work item, or issue is to be completed or resolved. + The date by which a feature, work item, or issue is to be completed or resolved. ::: moniker range="azure-devops" - > [!NOTE] - > [Delivery Plans](../plans/review-team-plans.md) uses the **Start Date** and **Target Date** to show the span of Features, Epics, and other portfolio backlog items. + > [!NOTE] + > [Delivery Plans](../plans/review-team-plans.md) uses the **Start Date** and **Target Date** fields to show the span of features, epics, and other portfolio backlog items. ::: moniker-end + Reference name=Microsoft.VSTS.Scheduling.TargetDate, Data type=DateTime :::column-end::: :::column span="1"::: @@ -554,38 +513,29 @@ You can use date fields to filter your queries. Some of these fields are populat :::column-end::: :::row-end::: +Notes: +1. See also [Query by assignment or workflow changes](query-by-workflow-changes.md). -#### Notes: - -1. See also [Query by assignment or workflow changes, Date, and Identity fields](query-by-workflow-changes.md). - -1. For these fields to be defined for a WIT, they must be included in the ```WORKFLOW``` section of the WIT definition. For example, this syntax is included within the ```FIELDS``` definition when transitioning to a Resolved state: - ```xml - - - - ``` +1. For these fields to be defined for a work item type, they must be included in the `WORKFLOW` section of the work item type definition. For example, this syntax is included within the `FIELDS` definition when transitioning to a `Resolved` state. -2. **Start Date** and **Finish Date** fields are calculated if you create a project plan in Microsoft Project and then synchronize that plan with tasks that are stored in Azure Boards. These fields might not appear on the work item form, but are calculated for the backlog items and tasks that are linked to backlog items. You can view their read-only values in results from a query or from Microsoft Excel. + ```xml + + + + ``` - [!INCLUDE [temp](../includes/deprecate-project.md)] +1. **Start Date** and **Finish Date** values are calculated if you create a project plan in Project and then synchronize that plan with tasks that are stored in Azure Boards. These fields might not appear on the work item form, but they're calculated for the backlog items and tasks that are linked to backlog items. You can view their read-only values in results from a query or from Excel. + [!INCLUDE [feature support information](../includes/deprecate-project.md)] ## Related articles -To query for items based on text entered in the History field, see [History and auditing](history-and-auditing.md). - - [Query by assignment or workflow changes](query-by-workflow-changes.md) - [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md) -- [Create managed queries with the query editor](using-queries.md) -- [Query operators & macros](query-operators-variables.md) -- [Query permissions](set-query-permissions.md) +- [Define a work item query in Azure Boards](using-queries.md) +- [Query fields, operators, and macros](query-operators-variables.md) - [Work item fields and attributes](../work-items/work-item-fields.md) -- [Work item query language (WIQL) syntax](../queries/wiql-syntax.md) -- [Query quick reference](query-index-quick-ref.md) -- [Work item field index](../work-items/guidance/work-item-field.md) - - -[!INCLUDE [temp](../includes/rest-apis-queries.md)] +- [Work Item Query Language (WIQL) syntax](../queries/wiql-syntax.md) +[!INCLUDE [rest api links](../includes/rest-apis-queries.md)] diff --git a/docs/boards/queries/query-by-workflow-changes.md b/docs/boards/queries/query-by-workflow-changes.md index 61d5f559b75..7c518abfb49 100644 --- a/docs/boards/queries/query-by-workflow-changes.md +++ b/docs/boards/queries/query-by-workflow-changes.md @@ -1,43 +1,65 @@ --- title: Query by account, user, workflow, or board changes in Azure Boards titleSuffix: Azure Boards -description: Learn how to list work items based on changes made to their assignment, state, or Kanban board column or swimlane in Azure Boards. +description: Learn how to list work items based on changes made to their assignment, state, or board column or swimlane in Azure Boards. ms.custom: boards-queries ms.service: azure-devops-boards ms.assetid: 1FD042F2-D503-40A3-A6C7-1E25A0F664C6 +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: example-scenario monikerRange: '<= azure-devops' -ms.date: 06/29/2022 +ms.date: 11/26/2024 --- -# Query by assignment or workflow changes in Azure Boards +# Query by assignment or workflow changes [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The states in the workflow support tracking work status as it moves from a new state to a closed or done state. Kanban query fields support tracking the status of work as it moves from one column or swimlane to another on the Kanban board. +Efficiently tracking assignment and workflow changes in your work items is essential for maintaining project visibility and ensuring smooth progress. This article guides shows how to create queries that monitor these changes, enabling better management and oversight of your team's work. -Each workflow consists of a set of states, valid transitions between states, and reasons for transitioning the work item to the selected state. [Workflow states and reasons](../work-items/guidance/choose-process.md#workflow-states) differ among the work item types and default processes used to create your project. +## Track work status in workflows -Most work items move from a *New*, *Active*, or *Proposed* state to a *Done* or *Closed* state. As each work item moves from one state to another, the item might also be reassigned to various members of the team. For example, a tester might create a bug that is assigned to another team member during triage. When the other team member resolves the bug, it's reassigned to the tester who created it. +- **Workflow states:** Track the progress of work items as they move from *New*, *Active*, or *Proposed* to *Done* or *Closed*. Each workflow includes: + - **States** + - **Valid transitions** + - **Reasons for transitions** + + [Workflow states and reasons](../work-items/guidance/choose-process.md#workflow-states) vary by work item type and project process. - +- **State transitions and reassignments:** + - Work items can be reassigned during state transitions. + - **Example:** A tester creates a bug and assigns it to a team member for triage. Once resolved, the bug is reassigned back to the tester. -For example, you can find all work items that were closed but then reactivated. By specifying the **Changed Date** field, you can focus on reactivations that occurred today, yesterday, or in the last week. + + +## Query reactivated work items + +Identify work items that were closed but later reactivated by using the **Changed Date** field. Focus on reactivations that occurred: +- Today +- Yesterday +- In the last week ![Query Editor filter for reactivated items.](media/query-reactivated-items.png) -You can also use the **Activated By** and **Activated Date** fields, or other workflow fields. +You can also utilize the following fields: +- **Activated By** +- **Activated Date** +- Other workflow-related fields > [!TIP] -> Not all fields are valid for all work item types. Jump to [Workflow and Kanban query fields](#workflow-fields) for the set of fields you can include in queries and which work item types they apply to. +> Not all fields are valid for every work item type. Refer to [Workflow and query fields](#workflow-fields) to see which fields are applicable to your queries and work item types. + +If you're new to creating queries, see [Use the query editor to list and manage queries](using-queries.md). -If you're new to creating queries, see [Use the query editor to list and manage queries](using-queries.md). +## Prerequisites + +[!INCLUDE [prerequisites-queries](../includes/prerequisites-queries.md)] ## Supported operators and macros -Query clauses that specify an identity or workflow-associated field can use the operators and macros listed in the following table. To learn about the field data type, see [Workflow and Kanban board fields](#workflow-fields) provided later in this article. +Query clauses that specify an identity or workflow-associated field can use the operators and macros listed in the following table. To learn about the field data type, see [Workflow and board fields](#workflow-fields) provided later in this article. --- :::row::: @@ -90,12 +112,9 @@ Query clauses that specify an identity or workflow-associated field can use the Use the `In` and `Not In` operators to filter for or exclude two or more pick list entries or a delimited set of items. Use the `In Group` or `Not In Group` operators to filter for items that belong or don't belong within a category group or security group. For more information, see [Query fields, operators, and macros](query-operators-variables.md). - [!INCLUDE [date-time-pattern](../includes/date-time-pattern.md)] - - - + ## Identity-based queries @@ -160,7 +179,7 @@ Use `=` to find current assignments, `Was Ever` to list items based on past assi --- - + ## Team or group membership queries @@ -171,10 +190,10 @@ To filter on items assigned to someone who belongs to a team or security group, You can use the **In Group** or **Not In Group** operators to filter a query based on several values that are members of a group, or that aren't members of a group. Examples of groups you can specify include the following items: - Teams - Built-in and custom security groups -- Azure Active Directory and Active Directory security groups +- Microsoft Entra ID and Active Directory security groups - Work item categories - + ## Queries based on workflow changes @@ -235,7 +254,7 @@ You use the State, Reason, and Resolved Reason fields to query for items based o :::row-end::: --- - + ## Workflow changes and identity-based queries @@ -272,23 +291,22 @@ You can quickly find items that you changed, resolved, or closed. You can also f ## Query changes in work item state -To list work items that have changed state within a specific date range, you can use the **State Change Date** field to narrow the search and then add clauses for changes to the **State** field. An example is shown in the following image. +To list work items that changed state within a specific date range, you can use the **State Change Date** field to narrow the search and then add clauses for changes to the **State** field. An example is shown in the following image. > [!div class="mx-imgBorder"] > ![Screenshot of Query Editor, filter State Change Date and State fields.](media/workflow/query-state-change-date.png) + + + - - - - -## Query changes to a Kanban board +## Query changes to a board -Using the Kanban query fields—Board Column, Board Column Done, and Board Lane—you can list work items according to their flow status on the Kanban board. And, you can create a [status or trend chart](../../report/dashboards/charts.md) based on these queries. +Using the query fields—**Board Column**, **Board Column Done**, and **Board Lane**—you can list work items based on their flow status on the board. Additionally, you can create [status or trend charts](../../report/dashboards/charts.md) from these queries. -You can list items based on the team area path, and if they are in a specific custom Kanban column and swimlane. If you rename a column or swimlane, you'll need to update the query filters to reflect the new name. For more ideas, see this blog post: [New fields bring Kanban goodness to queries, and more](https://blogs.msdn.microsoft.com/devops/2015/10/19/new-fields-bring-kanban-goodness-to-queries-and-more/) +You can filter items by team area path, specific custom columns, and swimlanes. If you rename a column or swimlane, update the query filters accordingly. For more ideas, see this blog post: [New Fields Bring Goodness to Queries, and More](https://blogs.msdn.microsoft.com/devops/2015/10/19/new-fields-bring-kanban-goodness-to-queries-and-more/) -![Screenshot of Query Editor, filter on Kanban Board Column and Board Lane fields.](media/query-kanban-fields.png) +![Screenshot of Query Editor, filter on board Column and Board Lane fields.](media/query-kanban-fields.png) > [!NOTE] > Queries are now scoped to the current project by default. Check the **Query across projects** to find work items defined in other projects within the collection. @@ -340,18 +358,17 @@ You can list items based on the team area path, and if they are in a specific cu ::: moniker-end --- - [!INCLUDE [temp](../includes/note-kanban-boards-teams.md)] - + -## Workflow and Kanban board fields +## Workflow and board fields -The following fields are useful to filter queries. Some of these fields get updated as a work item progresses from one state to another. Or they're updated as you move a work item in the [Kanban board](../boards/kanban-overview.md) to a different column or swimlane. Several of these fields don't appear on the work item form, but they're tracked for those work item types listed in the following table. +The following fields are useful to filter queries. Some of these fields get updated as a work item progresses from one state to another. Or they're updated as you move a work item in the [board](../boards/kanban-overview.md) to a different column or swimlane. Several of these fields don't appear on the work item form, but they're tracked for those work item types listed in the following table. For more information about field attributes, see [Work item fields and attributes](../work-items/work-item-fields.md). @@ -376,7 +393,7 @@ For more information about field attributes, see [Work item fields and attribute The name of the team member who changed the status of a work item to an *In Progress* category state. ::: moniker-end ::: moniker range="< azure-devops" - The name of the team member who changed the status of a work item from *New* to *Active* or reactivated a work item after it had been closed, completed, or done. + The name of the team member who changed the status of a work item from *New* to *Active* or reactivated a work item after it was closed, completed, or done. ::: moniker-end Reference name=`Microsoft.VSTS.Common.ActivatedBy` Data type=String (Identity) @@ -394,7 +411,7 @@ For more information about field attributes, see [Work item fields and attribute The date and time when the work item was changed to an *In Progress* category state. ::: moniker-end ::: moniker range="< azure-devops" - The date and time when the work item was changed from *New* to *Active* or reactivated after it had been closed, completed, or done. + The date and time when the work item was changed from *New* to *Active* or reactivated after it was closed, completed, or done. ::: moniker-end Reference name=`Microsoft.VSTS.Common.ActivatedDate` Data type=DateTime @@ -427,7 +444,7 @@ For more information about field attributes, see [Work item fields and attribute Board Column :::column-end::: :::column span="2"::: - The current Kanban board column assignment of the work item, for example: Active, Closed, Committed, Done, or other custom column assignment. + The current board column assignment of the work item, for example: Active, Closed, Committed, Done, or other custom column assignment. Reference name=`System.BoardColumn` Data type=String @@ -446,7 +463,7 @@ For more information about field attributes, see [Work item fields and attribute Board Column Done :::column-end::: :::column span="2"::: - The current assignment of the work item to Doing (False) or Done (True) Kanban column. Only assigned when [split-columns](../boards/split-columns.md) is enabled for a Kanban board column. + The current assignment of the work item to Doing (False) or Done (True) column. Only assigned when [split-columns](../boards/split-columns.md) is enabled for a board column. Reference name=`System.BoardColumnDone` Data type=Boolean @@ -465,7 +482,7 @@ For more information about field attributes, see [Work item fields and attribute Board Lane :::column-end::: :::column span="2"::: - The current Kanban board swimlane assignment of the work item, for example: Default, Expedite, Blocked, or other custom swimlane assignment. + The current board swimlane assignment of the work item, for example: Default, Expedite, Blocked, or other custom swimlane assignment. Reference name=`System.BoardLane` Data type=String :::column-end::: @@ -555,9 +572,7 @@ For more information about field attributes, see [Work item fields and attribute :::column-end::: :::column span="2"::: The reason why the work item is in the current state. Each transition from one workflow state to another is associated with a corresponding reason. - ::: moniker range="< azure-devops-2019" - For On-premises XML process models, the reason values are defined within the `WORKFLOW` section of the work item type definition using the `REASON` element. To modify the defined reasons, see [Change the workflow for a work item type](../../reference/xml/change-workflow-wit.md). - ::: moniker-end + Reference name=`System.Reason` Data type=String :::column-end::: @@ -652,18 +667,16 @@ For more information about field attributes, see [Work item fields and attribute ::: moniker-end :::column-end::: :::column span="2"::: - The current state of the work item. This field allows you to update the status of a work item as it progresses from new or active to a done or closed state. + The current state of the work item. This field allows you to update the status of a work item as it progresses from new or active to done or closed state. ::: moniker range="azure-devops" To modify the workflow states, see [Customize the workflow for a process](../../organizations/settings/work/customize-process-workflow.md). ::: moniker-end - ::: moniker range=">= azure-devops-2019 < azure-devops" + ::: moniker range=" [!NOTE] > 1. See [Date and Identity fields](#date-identity). -> 2. By default, the server synchronizes system-defined person-name or Identity-based fields with Active Directory or Azure Active Directory. These fields include: **Activated By**, **Assigned To**, **Closed By**, **Created By**, and **Resolved By**. You can grant access to a project by adding security groups that you created in AD or Azure AD or by adding accounts to existing or custom groups defined from the collection setting **Security** page. See set up [Active Directory or Azure Active Directory](../../organizations/security/about-permissions.md#aad). -> 3. See [Activated By/Date and Resolved By/Date fields](#activated-resolved-fields). -> 4. The Requirement Category applies to all work item types that appear on the product backlog and Kanban board, and may include those added to the Bug Category based on the team setting for [Show bugs on boards and backlogs](../../organizations/settings/show-bugs-on-backlog.md). For more information on work item type categories, see [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types). +> 2. By default, the server synchronizes system-defined person-name or Identity-based fields with Active Directory or Microsoft Entra ID. These fields include: **Activated By**, **Assigned To**, **Closed By**, **Created By**, and **Resolved By**. You can grant access to a project by adding security groups that you created in Active Directory or Microsoft Entra ID or by adding accounts to existing or custom groups defined from the collection setting **Security** page. See set up [Active Directory or Microsoft Entra ID](../../organizations/security/about-permissions.md#active-directory-and-microsoft-entra-security-groups). +> 3. See [Activated By/Date and Resolved By/Date fields](#activated-by-and-activated-date-transition-assignments). +> 4. The Requirement Category applies to all work item types that appear on the product backlog and board, and may include those added to the Bug Category based on the team setting for [Show bugs on boards and backlogs](../../organizations/settings/show-bugs-on-backlog.md). For more information on work item type categories, see [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types). > [!NOTE] > Even if you add a board-related field, such as Board Column or Board Lane, to a work item form, you can't modify the field from the form. ::: moniker-end - ::: moniker range="< azure-devops" 1. See [Date and Identity fields](#date-identity). -2. By default, the server synchronizes system-defined person-name or Identity-based fields with Active Directory or Azure Active Directory. These fields include: Activated By, Assigned To, Closed By, Created By, and Resolved By. You can grant access to a project by adding security groups that you created in AD or Azure AD or by adding accounts to existing or custom groups defined from the collection setting **Security** page. See set up [Active Directory or Azure Active Directory](../../organizations/security/about-permissions.md#aad). +2. By default, the server synchronizes system-defined person-name or Identity-based fields with Active Directory or Microsoft Entra ID. These fields include: Activated By, Assigned To, Closed By, Created By, and Resolved By. You can grant access to a project by adding security groups that you created in Active Directory or Microsoft Entra ID or by adding accounts to existing or custom groups defined from the collection setting **Security** page. See set up [Active Directory or Microsoft Entra ID](../../organizations/security/about-permissions.md#active-directory-and-microsoft-entra-security-groups). For on-premises deployments, you can enable or disable synchronization for a person-name field by using the **witadmin changefields** command-line tool. You can also synchronize custom person-name fields by specifying the **syncnamechanges** attribute. See [Manage work item fields](../../reference/witadmin/manage-work-item-fields.md) and [FIELD (Definition) element reference](/previous-versions/azure/devops/reference/xml/field-definition-element-reference). 3. Reportable field with attribute set to Dimension. Only valid when the collection is configured to support the On-premises XML model. Reportable data is exported to the data warehouse and can be included in Excel or SQL Server reports. For on-premises Azure DevOps, use the [**witadmin changefield**](../../reference/witadmin/manage-work-item-fields.md) command to change the reportable attribute for a field. -4. Indexed field. Enabling indexing for a field may increase the performance of finding work items whose queries specify that field. For on-premises Azure DevOps, use the [**witadmin indexfield** command](../../reference/witadmin/manage-work-item-fields.md) to change the index attribute for a field. -5. The Requirement Category applies to all work item types that appear on the product backlog and Kanban board. The category includes those items added to the Bug Category based on the team setting for [Show bugs on boards and backlogs](../../organizations/settings/show-bugs-on-backlog.md). For more information on work item type categories, see [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types). +4. Indexed field. Enabling indexing for a field might increase the performance of finding work items whose queries specify that field. For on-premises Azure DevOps, use the [**witadmin indexfield** command](../../reference/witadmin/manage-work-item-fields.md) to change the index attribute for a field. +5. The Requirement Category applies to all work item types that appear on the product backlog and board. The category includes those items added to the Bug Category based on the team setting for [Show bugs on boards and backlogs](../../organizations/settings/show-bugs-on-backlog.md). For more information on work item type categories, see [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types). > [!NOTE] > Even if you add a board-related field, such as **Board Column** or **Board Lane**, to a work item form, you can't modify the field from the form. ::: moniker-end - ### People picker -The **Assigned To** field is supported by the people picker feature. For example, when you choose the **Assigned To** field from within a work item form, the people picker is activated. As shown in the following image, you simply start entering the name of the user you want to select, and search until you find a match. Users that you've previously selected appear in the list automatically. To select users that you haven't selected previously, enter their entire name or search against the full directory. +The **Assigned To** field is supported by the people picker feature. For example, when you choose the **Assigned To** field from within a work item form, the people picker is activated. As shown in the following image, you simply start entering the name of the user you want to select, and search until you find a match. Users that you've previously selected appear in the list automatically. To select users that you didn't previously select, enter their entire name or search against the full directory. > [!div class="mx-imgBorder"] > ![Screenshot of the @mention tool in Discussion showing people picker.](../../organizations/notifications/media/at-mention/identity-selector.png) -For organizations that manage their users and groups using Azure Active Directory (Azure AD) or Active Directory, people pickers provide support for searching all users and groups added to the AD, not just those users and groups added to the project. +For organizations that manage their users and groups using Microsoft Entra ID or Active Directory, people pickers provide support for searching all users and groups added to the AD, not just those users and groups added to the project. ::: moniker range="azure-devops" -To limit the scope of identities available for selection to just those users added to the project, you can do so using the **Project-Scoped Users** group. For more information, see [Manage your organization, Limit identity search and selection](../../user-guide/manage-organization-collection.md#limit-identity-selection). +To limit the scope of identities available for selection to just those users added to the project, you can do so using the **Project-Scoped Users** group. For more information, see [Manage your organization, Limit identity search and selection](../../user-guide/manage-organization-collection.md#limit-user-visibility-for-projects-and-more). ::: moniker-end - - + ### Date and identity fields -Several date and identity fields are set based on workflow states or transitions. Some fields, such as **Created By** and **Created Date**, are set by the system when a work item is added. Other fields, such as **Closed Date** and **Closed By**, are set through the workflow definition of the work item type. Additionally, customized work item types may have other rules defined that influence the date and identity field assignments. +Several date and identity fields are set based on workflow states or transitions. Some fields, such as **Created By** and **Created Date**, are set by the system when a work item is added. Other fields, such as **Closed Date** and **Closed By**, are set through the workflow definition of the work item type. Additionally, customized work item types might have other rules defined that influence the date and identity field assignments. [!INCLUDE [date-time-pattern](../includes/date-time-pattern.md)] @@ -746,7 +756,7 @@ Several date and identity fields are set based on workflow states or transitions #### State changes -The following XML syntax example illustrates rules that may be defined for a work item type that govern the values for select fields. +The following XML syntax example illustrates rules that might be defined for a work item type that govern the values for select fields. Here, the **Resolved Date**, **Resolved By**, **Closed Date**, **Closed By**, **Activated Date**, and **Activated By** fields are set to `EMPTY` when a State value is set to New. The State value assignments are evaluated first, and then the transition assignments are evaluated next. > [!div class="tabbedCodeSnippets"] @@ -862,10 +872,8 @@ Then the Activated By and Activated Date fields are set to `READONLY`. ::: moniker-end - [!INCLUDE [activated-resolved-by-fields](../includes/activated-resolved-by-fields.md)] - ## Related articles - [How workflow states and state categories are used in Backlogs and Boards](../work-items/workflow-and-state-categories.md) @@ -874,6 +882,4 @@ Then the Activated By and Activated Date fields are set to `READONLY`. - [Work item fields and attributes](../work-items/work-item-fields.md) - [Query permissions](set-query-permissions.md) - [!INCLUDE [temp](../includes/rest-apis-queries.md)] - diff --git a/docs/boards/queries/query-faqs.yml b/docs/boards/queries/query-faqs.yml index 2c38a979195..b0e8cf5be04 100644 --- a/docs/boards/queries/query-faqs.yml +++ b/docs/boards/queries/query-faqs.yml @@ -27,17 +27,16 @@ sections: - question: What's the difference between a query and a semantic search? answer: | - While both query and semantic searches find and list work items, the filter features and results presentation are different. For more information, see [Functional work item search, Semantic search vs. managed work item queries](../../project/search/functional-work-item-search.md#search-vs-managed-work-item-queries). + While both query and semantic searches find and list work items, the filter features and results presentation are different. For more information, see [Functional work item search, Semantic search vs. managed work item queries](../../project/search/functional-work-item-search.md). - question: Can I export a query and import to another project? answer: | - **Yes**. You can save a query as a `.wiq` file, update the syntax, and then import it to another project, organization, or collection. - For more information, see [Cross-service and enhanced query operations](query-support-integration-cross-service-extensions.md#wiql). + **Yes**. You can save a query as a `.wiq` file, update the syntax, and then import it to another project, organization, or collection. - question: What are all the query filter functions? answer: | From the Query Editor, you can exercise the following filter functions. Choose the filter to jump to an article with sample queries. In addition to the query filters, you can [interactively apply filters to query results](../backlogs/filter-backlogs-boards-plans.md). - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" > [!NOTE] > Managed queries don't support proximity searches, however semantic searches do. In addition, semantic searches support both `*` and `?` as wildcard characters and you can use more than one wildcard character to match more than one character. For more information, see [Advanced work items search](../../project/search/advanced-work-item-search-syntax.md). ::: moniker-end @@ -54,46 +53,31 @@ sections: --- :::row::: :::column span="1"::: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - [Compare fields](./query-field-value.md) - [Key words](./titles-ids-descriptions.md) - [Linked work items](./linking-attachments.md) - - [Logical groupings](./using-queries.md#logical-groupings) - - [Query macros](about-managed-queries.md#macros) - - [Tags](./add-tags-to-work-items.md#query) - - [Was Ever](./query-by-workflow-changes.md) - - [Wildcard](./titles-ids-descriptions.md) - ::: moniker-end - ::: moniker range="tfs-2018" - - [Compare fields](./query-field-value.md) - - [Key words](./titles-ids-descriptions.md) - - [Linked work items](./linking-attachments.md) - - [Logical groupings](./using-queries.md#logical-groupings) - - [Query macros](about-managed-queries.md#macros) + - [Logical groupings](./using-queries.md) + - [Query macros](about-managed-queries.md#supported-macros) - [Tags](./add-tags-to-work-items.md#query) - [Was Ever](./query-by-workflow-changes.md) - [Wildcard](./titles-ids-descriptions.md) ::: moniker-end + :::column-end::: :::column span="1"::: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - [Blank or empty fields](./titles-ids-descriptions.md#empty-or-not-empty-html-field-queries) - [Boolean searches](./query-by-workflow-changes.md#query-changes-to-a-kanban-board) - [History and Discussion](./history-and-auditing.md) - - [Kanban board fields](./query-by-workflow-changes.md#query-changes-to-a-kanban-board) - - [In and Not In Group searches](./planning-ranking-priorities.md) - - [Search across projects](./using-queries.md#across-projects) - ::: moniker-end - ::: moniker range="tfs-2018" - - [Boolean searches](./query-by-workflow-changes.md#query-changes-to-a-kanban-board) - - [History and Discussion](./history-and-auditing.md) - - [In and Not In Group searches](./planning-ranking-priorities.md) - - [Search across projects](./using-queries.md#across-projects) + - [Board fields](./query-by-workflow-changes.md#query-changes-to-a-kanban-board) - [In and Not In Group searches](./planning-ranking-priorities.md) + - [Search across projects](./using-queries.md) ::: moniker-end + :::column-end::: :::column span="2"::: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - [[Any]](titles-ids-descriptions.md) - [@Me](query-by-workflow-changes.md) - [@Today](query-by-date-or-current-iteration.md) @@ -103,14 +87,7 @@ sections: - [@StartOfDay, @StartOfMonth, @StartOfWeek, @StartOfYear](query-by-date-or-current-iteration.md) - [@TeamAreas](query-by-area-iteration-path.md) ::: moniker-end - ::: moniker range="tfs-2018" - - [[Any]](titles-ids-descriptions.md) - - [@Me](query-by-workflow-changes.md) - - [@Today](query-by-date-or-current-iteration.md) - - [@CurrentIteration](query-by-date-or-current-iteration.md) - - [@Follows](titles-ids-descriptions.md#following) - - [@MyRecentActivity, @RecentMentions, @RecentProjectActivity](titles-ids-descriptions.md#recent-macros) - ::: moniker-end + :::column-end::: :::row-end::: --- @@ -159,7 +136,6 @@ sections: - You can also use the macros — @Me, @Follows, **MyRecentActivity**, @RecentMentions, @RecentProjectActivity — to create custom queries. These queries can filter for work items assigned to you, that you're following, and so on. To learn more about these macros, see [Query macros and variables](query-operators-variables.md#macros). - - question: How do I sort on the Parent field? answer: | You can't. Sorting a query on the **Parent** field isn't a supported feature. @@ -169,7 +145,7 @@ sections: - question: How do I query for a list of related work items? answer: | - You can't query for work items that contain links solely based on the **Related** link type. You can query for work items that have links by specifying `Related Link Count > 0`. However, the results contain all work items containing links to other work items, including **Parent-Child**, **Predecesor-Successor**, and other link types. + You can't query for work items that contain links solely based on the **Related** link type. You can query for work items that have links by specifying `Related Link Count > 0`. However, the results contain all work items containing links to other work items, including **Parent-Child**, **Predecessor-Successor**, and other link types. - question: Can I query for work items linked across projects? answer: | @@ -178,7 +154,7 @@ sections: - question: Can I link work items across organizations or collections? answer: | ::: moniker range="azure-devops" - **Yes** across organizations. See [Link user stories, issues, bugs, and other work items; Link to a remote work item](../backlogs/add-link.md#link-to-a-remote-work-item). However, you can't run a search for work items linked from other projects than the current project you're connected to. + **Yes** across organizations. See [Link user stories, issues, bugs, and other work items; Link to a remote work item](../backlogs/add-link.md). However, you can't run a search for work items linked from other projects than the current project you're connected to. ::: moniker-end ::: moniker range="< azure-devops" **No** across collections. This feature isn't supported. @@ -188,12 +164,10 @@ sections: questions: - question: Can I export a cross-project query to Excel? answer: | - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" **No**. Cross-project queries won't open in Excel. However, you can export a cross-project query to a .csv file, open it in Excel, and import it to Azure Boards. For more information, see [Bulk import or update work items using CSV files](import-work-items-from-csv.md). ::: moniker-end - ::: moniker range="tfs-2018" - **No**. Cross-project queries won't open in Excel. - ::: moniker-end + - question: How do I manage dependencies across projects? answer: | @@ -221,8 +195,7 @@ sections: questions: - question: How can I best use queries to monitor progress on a project or team? answer: | - - [Define a chart for a query](../../report/dashboards/charts.md) and add it to a dashboard, or add the [Query Results widget](../../report/dashboards/widget-catalog.md#query-results-widget) to a dashboard. Each time you open the dashboard, the query automatically runs and refreshes. - - Periodically, [triage query results](triage-work-items.md) to review and update status. + - [Define a chart for a query](../../report/dashboards/charts.md) and add it to a dashboard, or add the [Query Results widget](../../report/dashboards/widget-catalog.md#query-results-widget) to a dashboard. Each time you open the dashboard, the query automatically runs and refreshes. additionalContent: | ## Related articles diff --git a/docs/boards/queries/query-field-value.md b/docs/boards/queries/query-field-value.md index c37caf0b1b4..803b7f0d2b4 100644 --- a/docs/boards/queries/query-field-value.md +++ b/docs/boards/queries/query-field-value.md @@ -11,7 +11,7 @@ monikerRange: '<= azure-devops' ms.date: 10/25/2021 --- -# Query by field value comparisons in Azure Boards and Azure DevOps +# Query by field value comparisons [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -19,6 +19,10 @@ You can create queries based on how one field's value compares to another using - Is the person who created the work item the same as or different than the person assigned to it? Or, who closed it - Which Tasks were closed before or after their Target Date. +## Prerequisites + +[!INCLUDE [prerequisites-queries](../includes/prerequisites-queries.md)] + ## Supported data types You can use the comparison field operators—`=[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field]`—with the following field data types. The data type you select for the **Field** and the **Value** must match. @@ -48,8 +52,7 @@ You can use the comparison field operators—`=[Field], <>[Field], >[Field], :::column-end::: :::column span="1"::: - `Created By <>[Field] Closed By` - State = Closed + `Created By <>[Field] Closed By State = Closed` :::column-end::: :::row-end::: :::row::: @@ -68,13 +71,12 @@ You can use the comparison field operators—`=[Field], <>[Field], >[Field], :::column-end::: :::column span="1"::: - `Target Date <=[Field] Closed Date` - State = Closed + `Target Date <=[Field] Closed Date State = Closed` :::column-end::: :::row-end::: - + diff --git a/docs/boards/queries/query-index-quick-ref.md b/docs/boards/queries/query-index-quick-ref.md index a70ce102e5b..2873b4f89a4 100644 --- a/docs/boards/queries/query-index-quick-ref.md +++ b/docs/boards/queries/query-index-quick-ref.md @@ -2,7 +2,7 @@ title: Use an index to query examples, tasks, operators, and macros titleSuffix: Azure Boards description: Learn how to use an index to query operators, macros, and sample queries that are used to list work items for Azure Boards and Azure DevOps. -ms.custom: boards-queriess, engagement-fy23 +ms.custom: boards-queries, engagement-fy23 ms.service: azure-devops-boards ms.topic: overview ms.author: chcomley @@ -11,20 +11,18 @@ monikerRange: '<= azure-devops' ms.date: 10/05/2022 --- -# Use an index to query quick reference data in Azure Boards and Azure DevOps +# Use an index to query quick reference data [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Use this index to quickly access example queries and information on opening, defining, and working with queries. To learn how to use the Query Editor, see [Define a query](using-queries.md). If you find that your queries take too long to return results, review the [Guidance to create high-performing queries](high-performing-queries.md). +Use this index to quickly access example queries and information on opening, defining, and working with queries. To learn how to use the Query Editor, see [Define a query](using-queries.md). If you find that your queries take too long to return results, see [Define a query/Best practices](using-queries.md#best-practices). - - + ## Example queries You can list work items based on the following criteria... - --- :::row::: :::column span="1"::: @@ -105,16 +103,13 @@ You can list work items based on the following criteria... - [Items you've been associated with](history-and-auditing.md) **Team focus queries** - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - [Assigned to a member of a team](query-by-workflow-changes.md#group) - [Assigned to a team's area path](query-by-area-iteration-path.md#team-area-path) - [Assigned to a team's current sprint](query-by-date-or-current-iteration.md#current-iteration) - [Assigned to a team's sprint window](query-by-date-or-current-iteration.md#current-iteration-plus-minus-n) ::: moniker-end - ::: moniker range="tfs-2018" - - [Assigned to a member of a team](query-by-workflow-changes.md#group) - - [Assigned to a team's current sprint](query-by-date-or-current-iteration.md#current-iteration) | - ::: moniker-end + **Build and test field queries** - [List bugs and linked test cases](build-test-integration.md#linked-bugs) @@ -129,35 +124,33 @@ You can list work items based on the following criteria... :::row-end::: --- - - + ## Query tasks - --- :::row::: :::column span="1"::: - [Add a query](using-queries.md) - [Add a query chart](../../report/dashboards/charts.md) - - [Add a query chart to a dashboard](../../report/dashboards/charts.md#add-chart-to-a-dashboard) - - [Add a query tile to a dashboard](organize-queries.md#add-query-dashboard) - - [Add query results to a dashboard](using-queries.md#query-results-widget-dashboard) + - [Add a query chart to a dashboard](../../report/dashboards/charts.md#add-a-chart-to-a-dashboard) + - [Add a query tile to a dashboard](organize-queries.md#add-a-query-tile-to-a-dashboard)) + - [Add query results to a dashboard](using-queries.md#view-query-results-in-a-dashboard) - [Add a query folder](organize-queries.md) - [Add columns to query results](../backlogs/set-column-options.md) - [Bulk modify query items](../backlogs/bulk-modify-work-items.md) - [Bulk update existing work items (csv)](import-work-items-from-csv.md#update-existing-work-items) - - [Copy query URL](view-run-query.md#email-query) - - [Define a clause](using-queries.md#define-clause) - - [Delete a query or query folder](organize-queries.md#view-rename-delete) - - [Direct-links query](using-queries.md#directs-link-query) + - [Copy query URL](view-run-query.md#email-query-items-or-share-a-query-url) + - [Define a clause](using-queries.md#define-a-clause) + - [Delete a query or query folder](organize-queries.md#rename-or-delete-a-query)) + - [Direct-links query](using-queries.md#use-direct-links-to-view-dependencies) :::column-end::: :::column span="1"::: - [Edit a query](using-queries.md) - - [Email a query](view-run-query.md#email-query) + - [Email a query](view-run-query.md#email-query-items-or-share-a-query-url) - [Export a query to Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) - [Export a query (csv)](import-work-items-from-csv.md#export-list-as-a-csv-file) - - [Favorite a query](view-run-query.md#favorites) + - [Favorite a query](view-run-query.md#all-and-favorites-supported-tasks) - [Favorite a query as a team favorite](organize-queries.md#save-a-query-as-a-team-favorite) - [Filter a query](../backlogs/filter-backlogs-boards-plans.md) - [Flat-list query](using-queries.md#flat-list) @@ -165,31 +158,29 @@ You can list work items based on the following criteria... - [Group a chart by tags](add-tags-to-work-items.md#chart-work-items-and-group-by-tags) - [Import new work items (csv)](import-work-items-from-csv.md#import-new-work-items) - [Open a query](using-queries.md) - - [Query across projects](using-queries.md#across-projects) + - [Query across projects](using-queries.md#query-across-or-within-projects) - [Query based on tags](add-tags-to-work-items.md#query) :::column-end::: :::column span="1"::: ::: moniker range="azure-devops" - - [Rename a query or query folder](organize-queries.md#view-rename-delete) + - [Rename a query or query folder](organize-queries.md#rename-or-delete-a-query)) - [Run a query](view-run-query.md) - - [Save a query](organize-queries.md#save) + - [Copy and save a query](organize-queries.md#copy-edit-and-save-a-query) - [Set query permissions](set-query-permissions.md) - - [Tree query](using-queries.md#tree-query) - - [Triage query results](triage-work-items.md) + - [Tree query](using-queries.md#use-a-work-item-tree-to-view-hierarchies) - [View a query](view-run-query.md) - - [View query results with Parent field](using-queries.md#query-results-widget-parent-titles) + - [View query results with Parent field](using-queries.md#view-query-results-widget-with-parent-titles) - [Understand link types](link-type-reference.md) - [Ungroup a clause](using-queries.md#ungroup-clause) - [Work Item Query Language (WIQL)](wiql-syntax.md) ::: moniker-end ::: moniker range="< azure-devops" - - [Rename a query or query folder](organize-queries.md#view-rename-delete) + - [Rename a query or query folder](organize-queries.md#rename-or-delete-a-query) - [Run a query](using-queries.md) - - [Save a query](organize-queries.md#save) - - [Save a query as a team favorite](organize-queries.md#favorite-query) + - [Copy and save a query](organize-queries.md#copy-edit-and-save-a-query) + - [Save a query as a team favorite](organize-queries.md#save-a-query-as-a-team-favorite) - [Set query permissions](set-query-permissions.md) - - [Tree query](using-queries.md#tree-query) - - [Triage query items](triage-work-items.md) + - [Tree query](using-queries.md#use-a-work-item-tree-to-view-hierarchies) - [View a query](view-run-query.md) - [Understand link types](link-type-reference.md) - [Ungroup a clause](using-queries.md#ungroup-clause) @@ -199,7 +190,7 @@ You can list work items based on the following criteria... :::row-end::: --- - + ## Operators and macros supported for each data type @@ -207,8 +198,6 @@ The following table indicates the operators and macros available for the differe [!INCLUDE [temp](../includes/note-macro-web-portal.md)] - - :::row::: :::column span="1"::: **Data type** @@ -378,10 +367,9 @@ The following table indicates the operators and macros available for the differe > 3. The `@TeamAreas` macro is supported for Azure Boards and Azure DevOps Server 2019 and later versions. > 4. The `@CurrentIteration +/- n` macro is supported for Azure DevOps Server 2019 and later versions, and only when run from the web portal. - [!INCLUDE [date-time-pattern](../includes/date-time-pattern.md)] - + ## Example queries for select fields @@ -478,12 +466,9 @@ The following table lists common query fields and their data type for which samp :::column-end::: :::row-end::: - - ## Related articles -- [Query by field value comparisons](query-field-value.md) -- [Guidance to create high-performing queries](high-performing-queries.md) +- [Query by field value comparisons](query-field-value.md) - [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types) - [Define a managed query](using-queries.md) - [Work item field index](../work-items/guidance/work-item-field.md) diff --git a/docs/boards/queries/query-numeric.md b/docs/boards/queries/query-numeric.md index 151aece1791..e3fb33cfb6c 100644 --- a/docs/boards/queries/query-numeric.md +++ b/docs/boards/queries/query-numeric.md @@ -9,36 +9,41 @@ ms.author: chcomley author: chcomley ms.topic: example-scenario monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 05/30/2024 --- -# Query by numeric fields in Azure Boards and Azure DevOps +# Query by numeric fields [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -How do I determine how much work each developer has completed on my team? Is there a way to sum up the effort or story points for an iteration? +Learn how to query by numeric fields based on effort, schedule, story points, or time tracking fields in Azure Boards and Azure DevOps. -The most common numeric fields track effort for items in the Requirements category or estimated, remaining, and completed work for items in the Task category. With queries you can list the work items of interest, and then define a chart that shows either a count of work items or a sum of a numeric field. +The most common numeric fields track effort for items in the **Requirements** category or estimated, remaining, and completed work for items in the **Task** category. With queries you can list the work items of interest, and then define a chart that shows either a count of work items or a sum of a numeric field. +## Prerequisites -## Supported operators and macros +[!INCLUDE [prerequisites-queries](../includes/prerequisites-queries.md)] -Query clauses that specify a numeric field can use the operators listed below. -- = , <> , > , < , >= , <= -- =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field] -- In, Not In -- Was Ever +## Use operators and macros -## Tips for developing chart-based queries +Supported query clauses that specify a numeric field can use the following operators. +- `=` , `<>` , `>` , `<` , `>=` , `<=` +- `=[Field]`, `<>[Field]`, `>[Field]`, `<[Field]`, `>=[Field]`, `<=[Field]` +- `In`, `Not In` +- `Was Ever` -- You can only add charts for flat-list queries -- Chart options reference either query filters or fields displayed through column options -- Save changes you make to your query prior to adding or modifying a chart. -- To group one or more clauses, select them and then choose the ![Group Query Clause icon](../media/icons/group-clauses-icon.png) group clauses icon. To ungroup, select on the grouped clause. +## Develop chart-based queries +The following tips can help you develop your queries: +- Add charts for flat-list queries only. +- Reference either query filters or fields displayed through column options. +- Save changes you make to your query before you add or modify a chart. +- Group one or more clauses by selecting them and then the ![Group Query Clause icon](../media/icons/group-clauses-icon.png) group clauses icon. To ungroup, select on the grouped clause. -For more details on creating queries and chart-based queries, see [Use the query editor to list and manage queries](using-queries.md) and [Charts](../../report/dashboards/charts.md). If you want to add a custom field to track and generate sums of other numeric values, see [Add or modify a field](../../reference/add-modify-field.md). +For more information, see [Use the query editor to list and manage queries](using-queries.md) and [Charts](../../report/dashboards/charts.md) and [Add or modify a field](../../reference/add-modify-field.md). -### Useful filters +### Use filters + +The following table shows useful filters for queries. :::row::: :::column span="1"::: @@ -96,103 +101,79 @@ For more details on creating queries and chart-based queries, see [Use the query `Story Points <> (leave Value field blank)` :::column-end::: :::row-end::: + +--- + - - -## Work item count queries and charts +## Query for count of work items All queries show a count of items when you run the query. Here we define a flat-list query that filters for bugs in any state. -![Query bugs any state, count of work items summary](media/query-effort-active-bugs-count-summary.png) +![Screenshot of Query bugs any state, count of work items summary.](media/query-effort-active-bugs-count-summary.png) Also, all charts contain a Values selection designed to display a count of work items within the chart. -### Count of bugs per developer +### Query for count of bugs per developer -Create an active bugs query and modify the column options to show Assigned To and State. Then, add a pivot chart that displays the assignments and state. +To show Assigned To and State, create an active bugs query and modify the column options. Then, add a pivot chart that displays the assignments and state. -::: moniker range=">= azure-devops-2019" > [!div class="mx-imgBorder"] -> ![Configure chart dialog, pivot by assigned to and state](media/numeric/config-pivot-items-developer.png) -::: moniker-end - -::: moniker range="tfs-2018" -Configure chart, count of bugs by developer, area, pivot chart -::: moniker-end +> ![Screenshot of Configure chart dialog, pivot by assigned to and state.](media/numeric/config-pivot-items-developer.png) -### Count of bugs by state and area +### Query for count of bugs by state and area Using the same flat-list query that filters for bugs shown in the previous section, you can show a count based on area. Modify the column options to show the Area Path. Then, add a pivot chart that displays the state and area path. -::: moniker range=">= azure-devops-2019" > [!div class="mx-imgBorder"] -> ![Configure chart dialog, pivot by state and area](media/numeric/config-pivot-state-area.png) -::: moniker-end +> ![Screenshot showing Configure chart dialog, pivot by state and area.](media/numeric/config-pivot-state-area.png) -::: moniker range="tfs-2018" -![Configure chart, count of bugs by area, state, pivot chart](media/query-effort-config-chart-count-bugs-area-state-pivot-chart.png) -::: moniker-end + +## Query for undefined field values - - -## Undefined field value queries - -You can find work items that have an undefined field value by using the equals operator (=) and leaving the Value for the field blank. For example, the following filters list all work items of type User Stories whose Story Points field is blank. +You can find work items that have an undefined field value by using the *equals* operator, `=`, and leaving the Value for the field blank. For example, the following filters list all work items of type User Stories whose Story Points field is blank. > [!div class="mx-imgBorder"] -> ![Filter based on blank entries](media/numeric/field-value-blank.png) +> ![Screenshot showing Filter based on blank entries.](media/numeric/field-value-blank.png) -To list work items based on a field that isn't blank, use the not operator (<>) and leave the Value blank. +To list work items based on a field that isn't blank, use the *not* operator, `<>`, and leave the Value blank. + - - -## Effort or story point queries and charts +## Query for effort or story points You can assign Story Points to user stories or bugs when you work in an Agile process. Or, Effort to product backlog items and bugs when you work in a Scrum process. For more information, see [Basic](../get-started/plan-track-work.md), [Agile](../work-items/guidance/agile-process.md), [Scrum](../work-items/guidance/scrum-process.md), or [CMMI](../work-items/guidance/cmmi-process.md) work item types and workflow articles. -### Sum of story points and their status +### Query for sum of story points and their status Create a query that filters for User Story as the work item type and modify the column options to show Story Points and State. -Query editor, flat list, open stories +> [!div class="mx-imgBorder"] +> ![Screenshot showing Query editor, flat list, open stories.](media/query-effort-sum-story-points-iteration.png) Then, add a stacked bar chart that sums the Story Points. -::: moniker range=">= azure-devops-2019" > [!div class="mx-imgBorder"] -> ![Configure chart dialog, stacked bar, sum of story points](media/numeric/config-psum-story-points-stacked-bar.png) -::: moniker-end +> ![Screenshot showing Configure chart dialog, stacked bar, sum of story points.](media/numeric/config-psum-story-points-stacked-bar.png) -::: moniker range="tfs-2018" -![Configure chart, sum of story points per iteration, stacked bar chart.](media/query-effort-config-chart-sum-story-points-iteration.png) -::: moniker-end +For more information on system-defined cumulative flow diagrams, see [Cumulative flow](../../report/dashboards/cumulative-flow.md). -For information on system-defined cumulative flow diagrams, see [Cumulative flow](../../report/dashboards/cumulative-flow.md). +### Query for burn up chart of user stories for an iteration -### Burn up chart of user stories for an iteration +Create a query that filters for User Story as the work item type and in the Active or Closed state. To show Story Points, modify the column options. -Create a query that filters for User Story as the work item type and in the Active or Closed state. Modify the column options to show Story Points. - -Query editor, flat list, user stories - active or closed +> [!div class="mx-imgBorder"] +> ![Screenshot showing Query editor, flat list, user stories - active or closed.](media/query-effort-sum-story-points-active-closed.png) Then, add a stacked area trend chart that sums the Story Points. -::: moniker range=">= azure-devops-2019" > [!div class="mx-imgBorder"] -> ![Configure chart dialog, trend, sum of story points](media/numeric/config-trend-sum-story-points.png) -::: moniker-end - -::: moniker range="tfs-2018" -![Configure chart, sum of story points per iteration, stacked bar chart](media/query-effort-config-chart-sum-story-points-burnup.png) -::: moniker-end - +> ![Screenshot showing Configure chart dialog, trend, sum of story points.](media/numeric/config-trend-sum-story-points.png) - + -## Remaining and completed work queries and charts +## Query for remaining and completed work Based on the process your project references, you can assign the following fields to tasks or bugs. @@ -202,34 +183,26 @@ Based on the process your project references, you can assign the following field | Scrum | Remaining Work | | CMMI | Original Estimate, Remaining Work, Completed Work | - ### Sum of remaining work per developer -If you follow Scrum practices and estimate Remaining Work for your tasks and bugs, you can get a rollup of the amount of work remaining for each developer with the following query and chart. By using the In operator and including both Task and Bug, you include any bugs that are being tracked as tasks. +If you follow Scrum practices and estimate Remaining Work for your tasks and bugs, you can get a rollup of remaining work with the following query and chart. Use the *In* operator and include both Task and Bug to include any bugs that are tracked as tasks. -Query of tasks and bugs for sprint +> [!div class="mx-imgBorder"] +> ![Screenshot showing Query of tasks and bugs for sprint.](media/query-effort-tasks-bugs-list.png) -Add Remaining Work as a column option to the query and save. To view a sum of the remaining work, add a pivot chart as shown. +Add Remaining Work as a column option to the query and save. To view a sum of the remaining work, add a pivot chart as shown in the following example. -::: moniker range=">= azure-devops-2019" > [!div class="mx-imgBorder"] -> ![Configure chart dialog, pivot, sum of remaining work per developer](media/numeric/config-pivot-remaining-work-per-developer-area.png) -::: moniker-end - -::: moniker range="tfs-2018" -![Configure chart, sum of remaining work by developer, area, pivot chart](media/example-query-config-chart-sum-remaining-work-pivot-chart.png) -::: moniker-end +> ![Screenshot showing Configure chart dialog, pivot, sum of remaining work per developer.](media/numeric/config-pivot-remaining-work-per-developer-area.png) For information on system-defined sprint burndown charts, see [Sprint burndown](../../report/dashboards/configure-sprint-burndown.md). - - + ## Fields used to estimate and track work The following table describes the activity-based and numeric fields that you can use to track work. For information on date-related fields, such as Start Date, Finish Date, and Target Date, see [Query by date or current iteration](query-by-date-or-current-iteration.md). - :::row::: :::column span="1"::: **Field name** @@ -248,7 +221,7 @@ The following table describes the activity-based and numeric fields that you can :::column-end::: :::column span="2"::: - The type of activity that is required to complete a task.To learn more about how this field is used, see [Capacity planning](../sprints/set-capacity.md). Allowed values are: + The type of activity that is required to complete a task. For more information about how this field is used, see [Capacity planning](../sprints/set-capacity.md). Allowed values are: - Deployment - Design - Development @@ -283,11 +256,11 @@ The following table describes the activity-based and numeric fields that you can :::row-end::: :::row::: :::column span="1"::: - Completed Work + Completed Work :::column-end::: :::column span="2"::: - The amount of work that has been spent implementing a task. You can specify work in hours or in days. There are no inherent time units associated with this field. + The amount of work spent implementing a task. You can specify work in hours or in days. There are no inherent time units associated with this field. Reference name=Microsoft.VSTS.Scheduling.CompletedWork, Data type=Double @@ -325,7 +298,7 @@ The following table describes the activity-based and numeric fields that you can :::column span="2"::: A subjective unit of measure that captures the size of a bug or product backlog item. If you assign more effort to an item, you indicate that more work is required to implement it. - This field 3 is also used to calculate team velocity and forecasting. It's assigned to `Effort` in the ProcessConfiguration file. + This field 3 is also used to calculate team velocity and forecasting. It gets assigned to `Effort` in the ProcessConfiguration file. Reference name=Microsoft.VSTS.Scheduling.Effort, Data type=Double @@ -344,7 +317,7 @@ The following table describes the activity-based and numeric fields that you can :::column span="2"::: A subjective unit of measure that captures the size of a user story. If you assign more points to a user story, you indicate that more work is required to implement it. - This field 3 is also used to calculate team velocity and forecasting. It's assigned to `Effort` in the ProcessConfiguration file. + This field 3 is also used to calculate team velocity and forecasting. It gets assigned to `Effort` in the ProcessConfiguration file. Reference name=Microsoft.VSTS. Scheduling.StoryPoints, Data type=Double @@ -355,14 +328,14 @@ The following table describes the activity-based and numeric fields that you can :::row-end::: :::row::: :::column span="1"::: - Size + Size :::column-end::: :::column span="2"::: A subjective unit of measure that captures the size of a requirement. The larger the size, the more work is required to implement it. - This field3 is also used to calculate team velocity and forecasting. It's assigned to `Effort` in the ProcessConfiguration file. + This field3 is also used to calculate team velocity and forecasting. It gets assigned to `Effort` in the ProcessConfiguration file. - Reference name=Microsoft.VSTS. Scheduling.Size, Data type=Double + Reference name=Microsoft.VSTS. Scheduling. Size, Data type=Double :::column-end::: :::column span="1"::: @@ -385,11 +358,11 @@ The following table describes the activity-based and numeric fields that you can :::row-end::: :::row::: :::column span="1"::: - Remaining Work + Remaining Work :::column-end::: :::column span="2"::: The amount of work that remains to finish a task. You can specify work in hours or in days. There are no inherent time units associated with this field. - This field 3 is also used to calculate burn down. It is assigned to `type="RemainingWork"` in the ProcessConfiguration file. + This field 3 is also used to calculate the burn down. It gets assigned to `type="RemainingWork"` in the ProcessConfiguration file. > [!NOTE] > For Azure Boards, the taskboard always shows "h" for hours in relationship to Remaining Work. For TFS, you can modify the ProcessConfiguration file for the Remaining Work type field to specify "d" for days, or other preferred label. @@ -446,50 +419,21 @@ The following table describes the activity-based and numeric fields that you can > 1. To change the menu selection: for cloud services or an Inherited process, see [Add and manage fields](../../organizations/settings/work/customize-process-field.md); and for On-premises XML process, see [Add or modify a field, customize a picklist](../../reference/add-modify-field.md). > 2. The values displayed in the [Capacity page](../sprints/set-capacity.md) for **Activity** (Agile or Scrum) or **Discipline** (CMMI) reflect a union of all values defined for the field in all projects within the project collection instance. Therefore, to restrict the values that appear for Capacity on the sprint backlog pages, you must make the values match in all the projects for the field assigned to `type="Activity"`. > 3. To change the ProcessConfiguration field assignment (on-premises only), see [Process configuration XML element reference](../../reference/xml/process-configuration-xml-element.md). -> 4. Each team can configure their Agile tools to determine if [bugs are treated similar to requirements or tasks](#show-bugs). Since bugs can appear either with requirements or tasks, fields used to estimate effort at the requirement-level and the task-level are included in the work item form. - -## Related articles - -For information on adding custom fields, see [Customize your work tracking experience](../../reference/customize-work.md). +> 4. Each team can configure their Agile tools to determine if bugs are treated similar to requirements or tasks. Since bugs can appear either with requirements or tasks, fields used to estimate effort at the requirement-level and the task-level are included in the work item form. -The main tools you use to plan and track work are described here: -- [Create your backlog](../backlogs/create-your-backlog.md) -- [Sprint planning](../sprints/assign-work-sprint.md) -- [Capacity planning](../sprints/set-capacity.md) -- [Taskboard](../sprints/task-board.md) -- [Kanban board](../boards/kanban-overview.md) - -For more information on using work items and queries, see: -- [Query editor](using-queries.md) -- [Query fields, operators, and macros](query-operators-variables.md) -- [Add work items](../backlogs/add-work-items.md) -- [Work item field index](../work-items/guidance/work-item-field.md) -- [About managed queries](about-managed-queries.md) +## Next steps - +> [!div class="nextstepaction"] +> [Customize your work tracking experience](../../reference/customize-work.md) - - -### Rollup numeric values across work item types +## Related articles -Rollup provides summed values of select fields for all child work items of a parent. Natively, Azure Boards provides rollup of **Remaining Work** for tasks on the taskboard. For other rollup requirements, see the following articles: +- [Create your backlog](../backlogs/create-your-backlog.md) +- [Plan sprints](../sprints/assign-work-sprint.md) +- [Plan capacity](../sprints/set-capacity.md) +- [Define a work item query](using-queries.md) +- [Query fields, operators, and macros](query-operators-variables.md) - [Support rollup of work and other fields](../../reference/xml/support-rollup-of-work-and-other-fields.md) -- [Create rollup charts with Power BI](../../report/powerbi/data-connector-connect.md) - - - -### What items appear in the Requirement or Task categories? - -The default assignments of work item types to each category are listed below for each process. - -| Process | Requirement category | Task category | -|---------|---------|---------| -| Agile | User Story | Task | -| Scrum | Product Backlog Item | Task | -| CMMI | Requirement | Task | - -However, each team can determine if the Bug work item type appears in either the Requirement or Task category. See [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). - -You can add custom work item types to a backlog. For more information, see [Add or modify a work item type, Add a custom WIT to a backlog or board](../../reference/add-modify-wit.md). +- [Create rollup charts with Power BI](../../report/powerbi/data-connector-connect.md) -[!INCLUDE [temp](../includes/rest-apis-queries.md)] \ No newline at end of file +[!INCLUDE [temp](../includes/rest-apis-queries.md)] diff --git a/docs/boards/queries/query-operators-variables.md b/docs/boards/queries/query-operators-variables.md index 79a5d621f61..69d7bb99915 100644 --- a/docs/boards/queries/query-operators-variables.md +++ b/docs/boards/queries/query-operators-variables.md @@ -9,19 +9,23 @@ ms.author: chcomley author: chcomley ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 06/29/2022 +ms.date: 09/06/2024 --- -# Query fields, operators, and macros in Azure Boards +# Query fields, operators, and macros [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Here you'll find detailed descriptions of each field data type, query operators, and query macros. Some data types, operators, and macros are only valid for the indicated Azure DevOps version. +This article provides descriptions of each field data type, query operator, and query macro. Some data types, operators, and macros are only valid for the indicated Azure DevOps version. -For a quick reference of query tasks and operators and macros supported for each data type, see [Query quick reference](query-index-quick-ref.md). See also [Guidance to create high-performing queries](high-performing-queries.md) for tips on constructing high-performing queries. +For more information, see [Query quick reference](query-index-quick-ref.md) and [Manage and organize queries](organize-queries.md). - +## Prerequisites + +[!INCLUDE [prerequisites-queries](../includes/prerequisites-queries.md)] + + ## Query field data types and values @@ -51,7 +55,7 @@ The value you specify for a field must conform to the data type for that field. **DateTime** or **Date/Time** :::column-end::: :::column span="3"::: - A date field in which you can specify a variable, such as **** or ****, or a value, such as 1/1/2012. Enter dates in the Date Pattern you set for your personal profile. (See [Set personal preferences](../../organizations/settings/set-your-preferences.md) for details.) For query examples, see [Query by date or@CurrentIteration](query-by-date-or-current-iteration.md). + A date field in which you can specify a variable, such as **** or ****, or a value, such as `01/01/2025`. Enter dates in the Date Pattern you set for your personal profile. (See [Set personal preferences](../../organizations/settings/set-your-preferences.md) for details.) For query examples, see [Query by date or @CurrentIteration](query-by-date-or-current-iteration.md). For WIQL queries, you can also specify the date in the Coordinated Universal Time (UTC) pattern. For more information, see [Syntax for the Work Item Query Language (WIQL)](wiql-syntax.md). :::column-end::: @@ -77,7 +81,7 @@ The value you specify for a field must conform to the data type for that field. **History** :::column-end::: :::column span="3"::: - Custom formatted field used to track historical information. This data type is only used to support the **History** field. This field is automatically indexed for full-text search when full-text search is available. See [Full-Text and partial word searches](#full-text) described later in this article. For query examples, see [History and auditing](history-and-auditing.md). + Custom formatted field used to track historical information. This data type is only used to support the **History** field. This field is automatically indexed for full-text search when full-text search is available. See [Full-Text and partial word searches](#full-text) described later in this article. For query examples, see [History and auditing](history-and-auditing.md). :::column-end::: :::row-end::: :::row::: @@ -114,7 +118,7 @@ The value you specify for a field must conform to the data type for that field. :::row-end::: :::row::: :::column span="1"::: - **picklistDouble**1 + **picklistDouble** :::column-end::: :::column span="3"::: Custom field defined to contain a pick list of Decimal values. @@ -122,7 +126,7 @@ The value you specify for a field must conform to the data type for that field. :::row-end::: :::row::: :::column span="1"::: - **picklistInteger**1 + **picklistInteger** :::column-end::: :::column span="3"::: Custom field defined to contain a pick list of Integer values. @@ -130,7 +134,7 @@ The value you specify for a field must conform to the data type for that field. :::row-end::: :::row::: :::column span="1"::: - **picklistString**1 + **picklistString** :::column-end::: :::column span="3"::: Custom field defined to contain a pick list of short text string (255 characters or less) values. @@ -149,7 +153,7 @@ The value you specify for a field must conform to the data type for that field. **TreePath** :::column-end::: :::column span="3"::: - A branching tree structure, such as an Area Path or Iteration path. Choose an item from a list of valid values. Find work items that equal, not equal, under or not under a tree structure, or use the In or Not In operators to specify several values. You define the tree structure for a project—[area paths](../../organizations/settings/set-area-paths.md) and [iteration paths](../../organizations/settings/set-iteration-paths-sprints.md)—and then select the ones you want to associate with a team. + A branching tree structure, such as an Area Path or Iteration path. Choose an item from a list of valid values. Find work items that are equal to, not equal to, under, or not under a tree structure. You can also use the `In` or `Not In` operators to specify multiple values. Define the tree structure for a project—[area paths](../../organizations/settings/set-area-paths.md) and [iteration paths](../../organizations/settings/set-iteration-paths-sprints.md)—and then select the ones you want to associate with a team. For more information on constructing queries, see [Query by area or iteration path](query-by-area-iteration-path.md) or [Query by date or current iteration](query-by-area-iteration-path.md). @@ -157,17 +161,17 @@ The value you specify for a field must conform to the data type for that field. :::row-end::: > [!NOTE] -> 1. The **picklist...** data types are only assigned to custom fields defined for an inherited process. The Inherited process model is only supported for Azure DevOps Services and Azure DevOps Server 2019. +> The **picklist...** data types are only assigned to custom fields defined for an inherited process. [!INCLUDE [date-time-pattern](../includes/date-time-pattern.md)] - + ## Query operators -You can use query operators in the following table to specify how each value in a clause must relate to the corresponding value in a work item. For information about the data type that is assigned to work item fields, see [Work item field reference](../work-items/guidance/work-item-field.md). +Use query operators in the following table to specify how each value in a clause must relate to the corresponding value in a work item. For information about the data type that is assigned to work item fields, see [Work item field reference](../work-items/guidance/work-item-field.md). -To learn about adding clauses and use of the And/Or operators, see [Define a query, And/Or logical expression](using-queries.md#andor-logical-expression). +For more information, see [Define a query](using-queries.md). :::row::: :::column span="1"::: @@ -272,7 +276,8 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Name of a field that is of the same data type as the specified field + Name of a field that is of the same data type as the specified field
+ Checks if the Boolean field is equal to another field :::column-end::: :::row-end::: @@ -286,7 +291,8 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Name of a field that is of the same data type as the specified field + Name of a field that is of the same data type as the specified field
+ Checks if the Boolean field isn't equal to another field :::column-end::: :::row-end::: @@ -396,7 +402,7 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column span="3"::: Doesn't contain the exact text string or words within the field you selected for filtering. Text string is limited to 100 characters. - Use this operator in combination with a clause with the **Contains Words** operator to include and exclude specific keywords. + Use this operator in combination with a clause with the `Contains Words` operator to include and exclude specific keywords. :::column-end::: :::column span="3"::: @@ -410,7 +416,7 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Matches any value in a delimited set. For example, you can find work items whose IDs are 100, 101, and 102 if you specify those values for the ID field. Separate values with the list separator that corresponds to the regional settings that are defined for your client computer. For example, you might use a comma(,). + Matches any value in a delimited set. For example, you can find work items whose IDs are 100, 101, and 102 if you specify those values for the ID field. Separate values with the list separator that corresponds to the regional settings that are defined for your client computer. For example, you might use a comma `,`. :::column-end::: :::column span="3"::: @@ -425,7 +431,7 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Lists work items that contain an empty HTML field. You don't specify a value with this operator. This operator is supported for Azure Boards (cloud service), Azure DevOps Server 2019, and later versions. + Lists work items that contain an empty HTML field. You don't specify a value with this operator. This operator is supported for Azure Boards and Azure DevOps Server. :::column-end::: :::column span="3"::: @@ -438,7 +444,7 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Lists work items that contain some content in the HTML field. You don't specify a value with this operator. This operator is supported for Azure Boards (cloud service), Azure DevOps Server 2019, and later versions. + Lists work items that contain some content in the HTML field. You don't specify a value with this operator. This operator is supported for Azure Boards and Azure DevOps Server. :::column-end::: :::column span="3"::: @@ -451,10 +457,10 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Doesn't match any value in a delimited set. You can exclude work items whose states are not Resolved, Completed, or Closed from query results if you specify those values for the State field. Separate values with the list separator that corresponds to the regional settings that are defined for your client computer. For example, you might use a comma(,). + Doesn't match any value in a delimited set. You can exclude work items whose states aren't Resolved, Completed, or Closed from query results if you specify those values for the State field. Separate values with the list separator that corresponds to the regional settings that are defined for your client computer. For example, you might use a comma `,`. - > The **Not In** operator is available from Azure Boards and TFS 2018.2 and later versions. + > The **Not In** operator is supported for Azure Boards and Azure DevOps Server. :::column-end::: @@ -477,12 +483,10 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column span="3"::: **String** that matches the name of a team, security group, or category defined in the system. - - > [!NOTE] - > You can use the **In Group** operator only with fields that use the **String** data type or the **Work Item Type** field. You can also use groups defined in Azure Active Directory (Azure AD) when your Azure Boards account is backed by Azure AD, or Active Directory when your on-premises server instance is backed by Active Directory. + > You can use the **In Group** operator only with fields that use the **String** data type or the **Work Item Type** field. You can also use groups defined in Microsoft Entra ID when your Azure Boards account is backed by Microsoft Entra ID, or Active Directory when your on-premises server instance is backed by Active Directory. - For information about category groups, see [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types). + For information, see [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types). :::column-end::: :::row-end::: @@ -496,10 +500,10 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - **String** that matches the name of a user group in Team Foundation Server or a category group defined for a project. + **String** that matches the name of a user group in Azure DevOps Server or a category group defined for a project. > [!NOTE] - > You can use the **Not In Group** operator only with fields that use the **String** data type or the **Work Item Type** field. You can also use groups defined in Azure AD when your Azure Boards account is backed by Azure AD, or Active Directory when your on-premises server instance is backed by Active Directory. + > You can use the **Not In Group** operator only with fields that use the **String** data type or the **Work Item Type** field. You can also use groups defined in Microsoft Entra ID when your Azure Boards account is backed by Microsoft Entra ID, or Active Directory when your on-premises server instance is backed by Active Directory. :::column-end::: :::row-end::: @@ -543,15 +547,18 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column span="3"::: **String** , **DateTime** + > [!NOTE] + > **Was Ever** on date fields isn't currently supported when using the Query Editor. They're only supported when doing a direct WIQL. + :::column-end::: :::row-end::: > [!TIP] -> It's possible to contruct a query using WIQL syntax that uses an operator, such as **Was Ever**, for other data type fields than those listed. For example, you can use **Was Ever** within a clause using the **Iteration Path**. For an example, see [Query by date or current iteration, List work items moved out of a sprint](query-by-date-or-current-iteration.md#list-work-items-moved-out-sprint). +> It's possible to construct a query using WIQL syntax that uses an operator, such as **Was Ever**, for other data type fields than those listed. For example, you can use **Was Ever** within a clause using the **Iteration Path**. For an example, see [Query by date or current iteration, List work items moved out of a sprint](query-by-date-or-current-iteration.md#list-work-items-moved-out-sprint). - - + + ## Query macros or variables @@ -574,7 +581,7 @@ You can use the macros described in the following table to filter your queries b **[Any]** :::column-end::: :::column span="3"::: - Use with the **Work Item Type** or **State** fields to search across all work item types or across all states. For example, Work Item Type=[Any] won't place any filters based on the work item type. + Use with the **Work Item Type** or **State** fields to search across all work item types or across all states. For example, `Work Item Type=[Any]` doesn't place any filters based on the work item type. :::column-end::: :::row-end::: --- @@ -594,7 +601,7 @@ You can use the macros described in the following table to filter your queries b :::column-end::: :::column span="3"::: Use with the **Iteration Path** field to filter the set of work items assigned to the current sprint +/- *n* sprints based on the [current team focus or context](../../project/navigation/go-to-project-repo.md?toc=/azure/devops/boards/toc.json&bc=/azure/devops/boards/breadcrumb/toc.json). For specific examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). - The **@CurrentIteration +/- n** macro is supported for Azure Boards, Azure DevOps Server 2019 and later versions, and only when run from the web portal. + The **@CurrentIteration +/- n** macro is supported for Azure Boards, Azure DevOps Server when run from the web portal. :::column-end::: :::row-end::: --- @@ -603,7 +610,7 @@ You can use the macros described in the following table to filter your queries b **@Follows** :::column-end::: :::column span="3"::: - Use with the **ID** field and **In** operator to list all work items that you're following in the project. To learn more about the Follow feature, see [Follow a work item or pull request](../work-items/follow-work-items.md). You can view this same list from the [Work Items page, **Following** pivot view](../work-items/view-add-work-items.md). + Use with the **ID** field and **In** operator to list all work items that you're following in the project. For more information, see [Follow a work item or pull request](../work-items/follow-work-items.md). You can view this same list from the [Work Items page, **Following** pivot view](../work-items/view-add-work-items.md). The **@Follows** macro is supported only when run from the web portal. :::column-end::: :::row-end::: @@ -613,16 +620,16 @@ You can use the macros described in the following table to filter your queries b **@Me** :::column-end::: :::column span="3"::: - Use with an identity or user account field to automatically search for items associated with your user or account name. For example, you can find work items that you opened with the clause Created By=@Me. For more examples, see [Query by assignment, workflow, or Kanban board changes](query-by-workflow-changes.md). + Use with an identity or user account field to automatically search for items associated with your user or account name. For example, you can find work items that you opened with the clause `Created By=@Me`. For more examples, see [Query by assignment, workflow, or board changes](query-by-workflow-changes.md). :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **@MyRecentActivity** 1 + **@MyRecentActivity** :::column-end::: :::column span="3"::: - Use with the **ID** field and **In** operator to list work items that you have viewed or updated in the project within the last 30 days. You can view this same list from the [Work Items page, **My activity** pivot view](../work-items/view-add-work-items.md). + Use with the **ID** field and **In** operator to list work items you viewed or updated in the project within the last 30 days. You can view this same list from the [Work Items page, **My activity** pivot view](../work-items/view-add-work-items.md). :::column-end::: :::row-end::: --- @@ -631,61 +638,61 @@ You can use the macros described in the following table to filter your queries b **@Project** :::column-end::: :::column span="3"::: - Use with the **Team Project** field to filter for work items in other projects. For example, you can find all the work items in the currently selected project with the clause Team Project=@Project. The system automatically defaults to filtering based on the current project. For more information, see [Define a query, Query across projects](using-queries.md#across-projects). + Use with the **Team Project** field to filter for work items in other projects. For example, you can find all the work items in the currently selected project with the clause `Team Project=@Project`. The system automatically defaults to filtering based on the current project. For more information, see [Define a query, Query across projects](using-queries.md#query-across-or-within-projects). :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **@RecentMentions** 1 + **@RecentMentions** :::column-end::: :::column span="3"::: - Use with the **ID** field and **In** operator to list work items where you have been mentioned in the Discussion section. You can view this same list from the [Work Items page, **Mentioned** pivot view](../work-items/view-add-work-items.md). + Use with the **ID** field and **In** operator to list work items where you're mentioned in the Discussion section. You can view this same list from the [Work Items page, **Mentioned** pivot view](../work-items/view-add-work-items.md). :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **@RecentProjectActivity** 1 + **@RecentProjectActivity** :::column-end::: :::column span="3"::: - Use with the **ID** field and **In** operator to list work items that have been recently updated. The number of work items listed depends on the work tracking activity of the project. For highly active projects, the macro lists work items that have been updated in the project within the last 30 days or so. For less active projects, however, this list could include work items older than 30 days. You can view similar lists from the [Work Items page, **Recently created**, **Recently updated** and **Recently completed** pivot views](../work-items/view-add-work-items.md). The number of work items returned is capped at 5000. + Use with the **ID** field and **In** operator to list work items recently updated. The number of work items listed depends on the work tracking activity of the project. For highly active projects, the macro lists work items updated in the project within the last 30 days or so. For less active projects, however, this list could include work items older than 30 days. You can view similar lists from the [Work Items page, **Recently created**, **Recently updated** and **Recently completed** pivot views](../work-items/view-add-work-items.md). The number of work items returned is capped at 5000. :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **@StartOfDay** 2 + **@StartOfDay** :::column-end::: :::column span="3"::: - Use with a DateTime field to filter for work items that relate to the current date or with a plus/minus offset. For example, you can find all items closed in the last week with the clause Closed Date>=@StartOfDay-7. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). + Use with a `DateTime` field to filter for work items that relate to the current date or with a plus/minus offset. For example, you can find all items closed in the last week with the clause `Closed Date>=@StartOfDay-7`. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **@StartOfMonth** 2 + **@StartOfMonth** :::column-end::: :::column span="3"::: - Use with a DateTime field to filter for work items that relate to the current month or with a plus/minus offset. For example, you can find all items created in the last three months with the clause Created Date>=@StartOfMonth-3. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). + Use with a `DateTime` field to filter for work items that relate to the current month or with a plus/minus offset. For example, you can find all items created in the last three months with the clause `Created Date>=@StartOfMonth-3`. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **@StartOfWeek** 2 + **@StartOfWeek** :::column-end::: :::column span="3"::: - Use with a DateTime field to filter for work items that relate to the current week or with a plus/minus offset. For example, you can find all items changed in the last two weeks with the clause Changed Date>=@StartOfWeek-2. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). + Use with a `DateTime` field to filter for work items that relate to the current week or with a plus/minus offset. For example, you can find all items changed in the last two weeks with the clause `Changed Date>=@StartOfWeek-2`. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **@StartOfYear** 2 + **@StartOfYear** :::column-end::: :::column span="3"::: - Use with a DateTime field to filter for work items that relate to the current year or with a plus/minus offset. For example, you can find all features that have a Target Date scheduled within the current year with the clause Target Date>=@StartOfYear. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). + Use with a `DateTime` field to filter for work items that relate to the current year or with a plus/minus offset. For example, you can find all features that have a Target Date scheduled within the current year with the clause `Target Date>=@StartOfYear`. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). :::column-end::: :::row-end::: --- @@ -694,8 +701,8 @@ You can use the macros described in the following table to filter your queries b **@TeamAreas** :::column-end::: :::column span="3"::: - Only use with the **Area Path** field to filter for work items whose area path corresponds to one assigned to a specific team. Requires you use the **=** operator. For example, you can find all items assigned to the area paths assigned to the Web team with the clause Area Path=@TeamAreas [Fabrikam Fiber]\Web. For more examples, see [Query by area or iteration path](query-by-area-iteration-path.md). - The **@TeamAreas** macro is supported for Azure DevOps Server 2019 and later versions, and only when run from the web portal. + Only use with the **Area Path** field to filter for work items whose area path corresponds to one assigned to a specific team. Requires you use the **=** operator. For example, you can find all items assigned to the area paths assigned to the Web team with the clause `Area Path=@TeamAreas [Fabrikam Fiber]\Web`. For more examples, see [Query by area or iteration path](query-by-area-iteration-path.md). + The **@TeamAreas** macro is supported for Azure DevOps Server only when run from the web portal. :::column-end::: :::row-end::: --- @@ -704,19 +711,12 @@ You can use the macros described in the following table to filter your queries b **@Today** :::column-end::: :::column span="3"::: - Use with a DateTime field to filter for work items that relate to the current date or to an earlier date. You can also modify the **@Today** macro by subtracting days. For example, you can find all items created in the last week with the clause Created Date>=Today-7. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). + Use with a `DateTime` field to filter for work items that relate to the current date or to an earlier date. You can also modify the **@Today** macro by subtracting days. For example, you can find all items created in the last week with the clause `Created Date>=@Today-7`. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). :::column-end::: :::row-end::: --- - - -> [!NOTE] -> 1. The **@MyRecentActivity**, **@RecentMentions**, and **@RecentProjectActivity** macros are supported for TFS 2018.2 and later versions. -> 2. The **@StartOfDay**, **@StartOfWeek**, **@StartOfMonth**, and **@StartOfYear** macros are supported for Azure DevOps Server 2019 Update 1 and later versions. - - - + ## Full-text and partial word searches @@ -724,28 +724,24 @@ Specify **Contains** or **Does Not Contain** to search against exact or partial For examples, see [Example work item queries](query-index-quick-ref.md) and [Query for work items using the History field](history-and-auditing.md). - > [!NOTE] > Not all deployments support full-text searches. For example, SQL Express and SQL Azure, which support the cloud service, do not support full-text search. In these instances, you only see the **Contains** and **Does not Contain** operators. - ::: moniker range="< azure-devops" -Azure DevOps Server and Team Foundation Server automatically index all long-text fields with a data type of **PlainText** and **HTML** and the **Title** field for full-text search. The index and operators are only available when the SQL Server that supports Team Foundation Server supports full-text search. +Azure DevOps Server automatically indexes all long-text fields with a data type of **PlainText** and **HTML** and the **Title** field for full-text search. The index and operators are only available when the SQL Server that supports Azure DevOps Server supports full-text search. -Full-text searches require a SQL collation that corresponds to a language that has a word breaker registered with SQL Server. If the collation settings for the project collection database used for your Team Foundation Server instance don't correspond to a supported language, your search results may not match your expectations. In these cases, you might try using the **Contains** or **Does Not Contain** operators. +Full-text searches require a SQL collation that corresponds to a language that has a word breaker registered with SQL Server. If the collation settings for the project collection database used for your Azure DevOps Server instance don't correspond to a supported language, your search results might not match your expectations. In these cases, you might try using the **Contains** or **Does Not Contain** operators. For more information, see [Full-Text Search Queries and Collation Settings](/azure/devops/server/install/sql-server/collation-requirements). ::: moniker-end - - ## Related articles -- [Query quick reference](query-index-quick-ref.md) -- [About managed queries](about-managed-queries.md) -- [Work item field index](../work-items/guidance/work-item-field.md) -- [Syntax for the Work Item Query Language (WIQL)](wiql-syntax.md) +- [Use the query quick reference](query-index-quick-ref.md) +- [Learn about managed queries](about-managed-queries.md) +- [Access the work item field index](../work-items/guidance/work-item-field.md) +- [Understand the syntax for the Work Item Query Language (WIQL)](wiql-syntax.md) [!INCLUDE [temp](../includes/rest-apis-queries.md)] diff --git a/docs/boards/queries/query-support-integration-cross-service-extensions.md b/docs/boards/queries/query-support-integration-cross-service-extensions.md deleted file mode 100644 index 95855e3d381..00000000000 --- a/docs/boards/queries/query-support-integration-cross-service-extensions.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Cross-service operation queries in Azure Boards and Azure DevOps -titleSuffix: Azure Boards -description: Learn about extra features, like cross-service operations, that are supported by work tracking queries in Azure Boards and Azure DevOps. -ms.custom: boards-queries -ms.service: azure-devops-boards -ms.topic: conceptual -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 04/01/2022 ---- - - - -# Cross-service and enhanced query operations - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Managed queries are primarily focused on listing and working with work items. However, the query capabilities also support several cross-service operations, some of which require installation of a Marketplace extension. - - -## Query-based dashboard widgets - -Along with defining flat-list query charts that you can add to a dashboard, you can configure one of the following query-based widgets. - - ![Chart work item query widget.](../../report/dashboards/media/widget-chart-work-query.png) - - ![Query results widget.](../../report/dashboards/media/widget-query-results.png) - - ![Query tile widget.](../../report/dashboards/media/widget-query-tile.png) - -Other query-based widgets are available from the Azure DevOps Marketplace. - - -## Query filters used in notifications - -Notifications support query filter criteria so that you can customize when you'll receive notifications. There may be limitations in what fields can be used to support notification filtering. - -:::image type="content" source="media/about-queries/query-filter-notifications.png" alt-text="Screenshot of query filters in a notification subscription."::: - -For more information, see [Manage your personal notifications](../../organizations/notifications/manage-your-personal-notifications.md) - - - -## WIQL syntax, Wiql editor, and `.wiq` files - -Managed queries use the work item query language (WIQL), a language similar to Structured Query Language (SQL). You can gain access to the WIQL syntax behind a managed query when you install the [**Wiql Editor**](https://marketplace.visualstudio.com/items?itemName=ottostreifel.wiql-editor) Marketplace extensions. - -This extension adds the following to your Azure Boards web portal: - -- **Edit query wiql** (Work Item Query Language) to the **More commands** menu on the Query Editor and Query Results pages. -- **WIQL Playground** page to **Boards**. - -From these interfaces you can exercise the following query features: - -- View the underlying WIQL syntax of a managed query -- Run historical queries using the `ASOF` operator (`ASOF` operator won't be saved in a managed query) -- Specify a `MODE` clause for linked work items to further refine the query results (`MODE` clause won't be saved in a managed query) -- Move, copy, or paste query clauses -- Import and export queries as `.wiq` files from one project, organization, or collection to another -- Export WIQL for use in REST API calls. - -You may find that it's easier to read queries with lots of clauses or heavily nested clauses from the WIQL format. For exceptionally large queries, the load times from a WIQL query may yield better load times. - -### WIQL syntax - -WIQL has five parts shown in the following syntax snippet. The WIQL syntax is not case-sensitive. - -> [!div class="tabbedCodeSnippets"] -```WIQL -SELECT [State], [Title] -FROM WorkItems -WHERE [Work Item Type] = 'User Story' -ORDER BY [State] Asc, [Changed Date] Desc -ASOF '6/15/2010' -``` -To learn more about WIQL, see [Syntax for the Work Item Query Language (WIQL)](wiql-syntax.md). - -> [!NOTE] -> For queries made against Azure DevOps, the WIQL length must not exceed 32K characters. The system won't allow you to create or run queries that exceed that length. - -### `.wiq` file structure - - The following syntax shows the structure of the `.wiq` file. For details on each `WorkItemQuery` syntax element, see [Define a work item query to add to a process template](/previous-versions/azure/devops/reference/process-templates/define-work-item-query-process-template) - -> [!div class="tabbedCodeSnippets"] -> ```XML -> -> collectionURL -> TeamProjectName -> -> WorkItemQueryLanguage -> -> -> ``` - -## Extensions and manage queries - -The following Azure DevOps Marketplace extensions work with managed queries to provide more functionality. - -> [!NOTE] -> Most Marketplace extensions are not supported features of Azure Boards and therefore not supported by the product team. For questions, suggestions, or issues you have when using these extensions, visit their corresponding extension page. - -::: moniker range=">= azure-devops-2019" -- [Query Based Boards](https://marketplace.visualstudio.com/items?itemName=realdolmen.EdTro-AzureDevOps-Extensions-QueryBasedBoards-Public) supports viewing a flat-list query of work items as a Kanban board. The query can contain different work item types and work items defined in different projects. -::: moniker-end -- [**Query Tile PRO**](https://marketplace.visualstudio.com/items?itemName=mskold.mskold-Query-Tile-PRO): Adds the **Query Tile PRO** widget to the widget catalog for dashboards. This widget provides support for all query types (not just flat list queries) and provides more options to configure calculated values on the widget. - -- [**Wiql to OData**](https://marketplace.visualstudio.com/items?itemName=ms-eswm.wiql-to-odata): Adds the **Translate to OData** option to the **More commands** menu on the Query Editor and Query Results pages. You can then use this query or augment it to retrieve the work items from the Analytics service. For more information, see [Query your work tracking data using OData Analytics](../../report/extend-analytics/wit-analytics.md). - -- [**Open in Power BI**](https://marketplace.visualstudio.com/items?itemName=stansw.vsts-open-in-powerbi): Adds the **Open in Power BI** option to the **More commands** menu on the Query Editor and Query Results pages. You can then use Power BI to generate reports based on the Analytics work tracking data. You can add these reports to an Azure DevOps dashboard. For more information, see [Query your work tracking data using OData Analytics](../../report/extend-analytics/wit-analytics.md). - -- [**Enhanced Export**](https://marketplace.visualstudio.com/items?itemName=mskold.mskold-enhanced-export): Lets you export work item queries or test plans to document-like formats. To get the output formatted the way you want, you can select different templates to get the form and layout of your choice. You can preview, print or even open the document directly in Office. - -[!INCLUDE [temp](../includes/rest-apis-queries.md)] - -## Related articles - -- [About managed queries](about-managed-queries.md) -- [Syntax for the Work Item Query Language (WIQL)](wiql-syntax.md) -- [Work across projects FAQs](../../project/work-across-projects-faqs.yml) diff --git a/docs/boards/queries/search-box-queries.md b/docs/boards/queries/search-box-queries.md index edda783fa08..b7c554bc59c 100644 --- a/docs/boards/queries/search-box-queries.md +++ b/docs/boards/queries/search-box-queries.md @@ -12,12 +12,11 @@ monikerRange: '<= azure-devops' ms.date: 04/01/2022 --- - -# Run a semantic work item search in Azure Boards and Azure DevOps +# Run a semantic work item search [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - + You can find work items by using shortcut filters or by specifying keywords or phrases. You can also use specific fields/field values, assignment or date modifications, or using Equals, Contains, and Not operators. Searching isn't case-sensitive. Use semantic searches when you want to do the following tasks: @@ -27,13 +26,19 @@ You can find work items by using shortcut filters or by specifying keywords or p - Review work items assigned to a specific team member - Search against specific work item fields to quickly narrow down a list of work items - Determine what key words support a managed search - -You can run a powerful [semantic search](#start-search) from the web portal for Azure DevOps Services or for on-premises deployments when the [server instance has been configured with the work item search extension](../../project/search/get-started-search.md). +## Prerequisites + +- **Access levels**: **All project members**: Every project member can use the search functions, including users with Stakeholder, Basic, and higher levels of access. +- Search results: + - **Access-based results**: When you're searching across the organization or collection, only results for which a project member has access are listed. + - **Stakeholder limitations**: + - **Wiki search**: Stakeholder wiki search results are limited to provisioned wikis. Published wiki results don’t appear because they require access to regular repositories, which Stakeholders don’t have. + - **Code search**: Code search results don’t appear for Stakeholders. ::: moniker range="< azure-devops" > [!TIP] -> If semantic search has been configured, you'll notice that the search box moves into the blue bar as shown in the following image. +> If semantic search is configured, you'll notice that the search box moves into the blue bar as shown in the following image. > >![Search Work Items Text Box](media/search-box/search-box-vsts.png) ::: moniker-end @@ -47,9 +52,7 @@ With semantic search you can search: - Across all work item fields using free text - Against specific work item fields -Free text search easily searches across all work item fields, including custom fields, which enables more natural searches. Search results are displayed in a snippet view where the search matches found are highlighted. Semantic search also integrates with work item tracking, providing familiar controls to view, edit, comment, and share information within a work item form. - -::: moniker range=">= azure-devops-2019" +Free text search easily searches across all work item fields, including custom fields, resulting in more natural searches. Search results are displayed in a snippet view where the search matches found are highlighted. Semantic search also integrates with work item tracking, providing familiar controls to view, edit, comment, and share information within a work item form. 1. Choose any **Boards** page, enter a keyword or phrase in the search box, and press *Enter* or choose the :::image type="icon" source="../../project/search/media/shared/start-search-icon.png" border="false"::: start search icon. @@ -63,7 +66,7 @@ Free text search easily searches across all work item fields, including custom f Work item search matches derived forms of your search terms; for example, a search for "updating" also finds instances of the word "updated" and "update". Searches _aren't_ case-sensitive. -3. Select a snippet of a work item to display it in the right window. +3. Select a snippet of a work item and display it in the right window. Open the search results in a new browser tab from a search box by pressing _Ctrl_ + _Enter_ or by holding _Ctrl_ and clicking the @@ -71,47 +74,9 @@ Free text search easily searches across all work item fields, including custom f In Google Chrome, press _Ctrl_ + _Shift_ + _Enter_ to switch the focus to the new browser tab. -::: moniker-end - - -::: moniker range="tfs-2018" - -1. In the search box, check that the text says _Search work items_. If it doesn't, use the selector to select it. - - ![The Work Item Search textbox in the title bar](../../project/search/media/work-item-search-get-started/title-bar-search-box-empty-outlined.png) - -1. Enter a search string in the text box, and press _Enter_ (or choose the - ![start search icon](../../project/search/media/shared/start-search-icon.png) icon) to start your search. - -1. Search results are displayed in a snippet view where the matches found are shown in bold. - - ![Search results](../../project/search/media/work-item-search-get-started/results-matching.png) - - This search is a full text search that uses simple search strings for words or phrases. - Work item search matches derived forms of your search terms; for example, a search for - "updating" also finds instances of the word "updated" and "update". Searches _aren't_ case-sensitive. - -2. Select a snippet of a work item to display it in the right window. - - Open the search results in a new browser tab from a search box by - pressing _Ctrl_ + _Enter_ or by holding _Ctrl_ and clicking the - ![start search icon](../../project/search/media/shared/start-search-icon.png) icon. - In Google Chrome, press _Ctrl_ + _Shift_ + _Enter_ to switch the focus - to the new browser tab. - -::: moniker-end - -::: moniker range="azure-devops-2019" -[!INCLUDE [temp](../../includes/previous-navigation-not-supported-azd.md)] -::: moniker-end - - - ### Fine-tune semantic search results -::: moniker range=">= azure-devops-2019" -1. Fine-tune your search by specifying the fields to search. Enter `a:` and a user name - to search for all items assigned to that user. +1. Fine-tune your search by specifying the fields to search. Enter `a:` and a user name to search for all items assigned to that user. :::image type="content" source="../../project/search/media/get-started/search-work-vert.png" alt-text="Search from the title bar"::: @@ -138,42 +103,9 @@ Free text search easily searches across all work item fields, including custom f 4. Narrow your search to specific types and states, by using the drop-down selector lists at the top of the results page. - -::: moniker-end - - -::: moniker range="tfs-2018" -1. Fine-tune your search by specifying the fields to search. Enter `a:` and a user name - to search for all items assigned to that user. - - :::image type="content" source="../../project/search/media/get-started/work-item-search-filters.png" alt-text="Title bar Search"::: - - The quick filters you can use are: - - * `a:` for **Assigned to:** - * `c:` for **Created by:** - * `s:` for **State** - * `t:` for **Work item type**

- -2. Start entering the name of a field in your work items; for example, type `ta`. - - ![Quick filters as you type](../../project/search/media/work-item-search-get-started/dyna-dropdown.png) - - The dropdown list shows work item field name suggestions - that match user input and help the user to complete the search faster. For example, a search such as - `tags:Critical` finds all work items tagged "Critical". - -3. Add more filters to further narrow your search, and use Boolean operators - to combine terms if necessary. For example, - `a: Chris t: Bug s: Active` finds all active bugs assigned - to a user named "Chris". - -4. Narrow your search to specific types - and states, by using the drop-down selector lists at the top of the results page. - ::: moniker-end - + ### From the web portal @@ -181,13 +113,6 @@ Free text search easily searches across all work item fields, including custom f Improvised search isn't available from Azure DevOps Services. Only [semantic search](#start-search). ::: moniker-end -::: moniker range="<= azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Search box shortcut menu (web portal)](media/example-search-box-queries/IC588318.png) - -::: moniker-end - ### From Visual Studio Team Explorer @@ -196,7 +121,6 @@ Open the ![Context Menu Icon](media/example-search-box-queries/IC533396.png) con > [!div class="mx-imgBorder"] > ![Search box menu (Team Explorer)](media/example-search-box-queries/IC588319.png) - Finding work items using the search box (Team Explorer) ![Find a work item using the search text box](media/example-search-box-queries/IC552976.png) @@ -205,8 +129,7 @@ You can combine shortcuts and use search operators within the search box. Use the ![Search box clear icon (Team Explorer)](media/example-search-box-queries/IC588317.png) **Clear** button to remove content from the search box. To switch your context to the search box from within Visual Studio, enter **Ctrl+'**. - - + ## Find items based on keywords or phrases @@ -247,9 +170,7 @@ To find work items based on a keyword or phrase contained within other text stri ## Use @Me or @Today macros -The @Me macro expands to the full name of the current user in any work item search. The @Me macro is especially useful for creating a search that you can share with other users, and it can simplify your work by reducing the number of characters you must type to specify your own user name. For a description of all macros, see [Query fields, operators, and macros, Query macros or variables](query-operators-variables.md#macros). - - +The **@Me** macro expands to the full name of the current user in any work item search. The **@Me** macro is especially useful for creating a search that you can share with other users, and it can simplify your work by reducing the number of characters you must type to specify your own user name. For a description of all macros, see [Query fields, operators, and macros, Query macros or variables](query-operators-variables.md#macros). --- :::row::: @@ -325,7 +246,6 @@ The following examples show how to use operators when you create a search string |Contain the keyword `triage` in the title or description, aren't assigned to you, and aren't closed.|`triage -A=@me -S=Closed`| |Active bugs that are assigned to you that don't contain the keyword `bugbash` in the title.|`S=Active T=bug A=@Me -Title:bugbash` - ## Related articles - [About managed queries](about-managed-queries.md) diff --git a/docs/boards/queries/set-query-permissions.md b/docs/boards/queries/set-query-permissions.md index 90ef72998ca..a28140c8eb8 100644 --- a/docs/boards/queries/set-query-permissions.md +++ b/docs/boards/queries/set-query-permissions.md @@ -9,29 +9,38 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 02/02/2023 +ms.date: 11/26/2024 --- - -# Set permissions on queries and query folders in Azure Boards and Azure DevOps +# Set permissions on queries and query folders [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -As with most project objects, you can control access by setting permissions. With queries, you can configure users and groups to create, delete, view, and manage permissions of shared queries and shared query folders. +You can control access to queries by setting permissions, which let you configure users and groups to create, delete, view, and manage shared queries and query folders. + +- **My Queries:** + - **Create and edit:** All users, except users in the Readers group, can create and edit their own queries. + - **View:** Only the signed-in user can view queries in their **My Queries** space. -All users, except those users assigned to the Readers group, can create and edit their own queries and save them under **My Queries**. Only the signed in user can view queries saved under their **My Queries** space. +- **Shared Queries:** + - **Permissions:** By default, only Project Administrators can create, edit, or change permissions for queries and folders. + - **Team management:** Create separate folders for each team under Shared Queries to allow them to manage their own set of shared queries. -By default, only members of the Project Administrators group can create and edit queries and folders under **Shared Queries**, or change the permissions for a query or folder. +For more information, see [Organize queries](organize-queries.md). +::: moniker range="azure-devops" -By creating folders under Shared Queries, you can grant permissions to users for each folder. For example, if you have several teams contributing to a project, then you might want to create a folder under Shared Queries for each team to manage their own set of shared queries. +[!INCLUDE [note-new-boards-hub-default-images](../includes/note-new-boards-hub-default-images.md)] + +::: moniker-end ## Prerequisites -- To create or edit a shared query or manage permissions, you must be a member of the **Project Administrators** groups with **Basic** or higher access level. Or, you must have your **Contribute** permission set to **Allow** for the shared query folder. To get added to this group, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) -- Or, to create a query or folder under a shared query folder, you must have the **Contribute** permission set explicitly to **Allow** for the query folder and be granted **Basic** or higher access level. -- Or, to change permissions of a query or query folder, you must have the **Manage Permissions** permission set explicitly to **Allow** for the query folder and be granted **Basic** or higher access level. +| Category | Requirements | +|--------------|-------------| +|**Access levels**| At least [**Basic** access](../../organizations/security/access-levels.md).| +|**Permissions**| - To manage permissions, be a member of the [**Project Administrators** group](../../organizations/security/change-project-level-permissions.md).
- To create or edit a shared query, have your **Contribute** permission set to **Allow** for the shared query folder.
- To change permissions of a query or query folder, have the **Manage Permissions** permission set to **Allow** for the query folder.| -Users with Stakeholder access can't create or save queries in a Shared folder. To learn more about access levels, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). +Users with [Stakeholder access](../../organizations/security/stakeholder-access.md) can't create or save queries in a shared folder. > [!TIP] > Consider creating a query folder for each team and give the team administrators or the team group query permissions to manage their folder. @@ -44,146 +53,118 @@ A ✔️ (checkmark) in the following table indicates that the corresponding sec ## Set permissions on a new query folder -You set permissions from the web portal. To open **Queries**, see [View, run, or email a query](view-run-query.md). - +To set permissions on a new query folder, do the following steps: > [!TIP] -> You need **Delete** permissions to rename or move a shared query or folder, and **Contribute** permissions for the folder where you move the query to. +> To rename or move a shared query or folder, have **Delete** permissions and **Contribute** permissions for the folder where you move the query to. -::: moniker range=">= azure-devops-2020" +::: moniker range="azure-devops" -1. Choose **All**. Expand **Shared Queries**. - -1. To add a folder, choose :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **More actions** for an existing folder or the top container folder, and choose **New folder**. +1. From your project, select **Boards** > **Queries** > **All** > **Shared Queries**. - > [!div class="mx-imgBorder"] - > ![Screenshot that shows Open More actions menu, choose New folder.](media/organize-queries/select-new-folder.png) + :::image type="content" source="media/boards-queries-all-shared-queries.png" alt-text="Screenshot showing sequence of selections to get to Shared Queries."::: -2. Enter the name for the folder. If you want to change the location of the folder, select **Rename** from the folder drop-down menu. +1. Select **New folder**. - Here we name the folder *Service Delivery* with the intention that it gets used by the Service Delivery team. + :::image type="content" source="media\view-run-queries\select-new-folder-new-boards-hubs.png" alt-text="Screenshot of New folder selection."::: - > [!div class="mx-imgBorder"] - > ![Screenshot of New folder dialog.](media/permissions/new-folder-dialog.png) +1. Enter the name for the folder and select the parent folder from the drop-down list. -3. To set permissions for the folder you just added, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon and select **Security**. + This example uses the name the folder *Service Delivery* with the intention that it gets used by the Service Delivery team. -4. Change the permissions so that the team member or group can contribute and manage permissions for the folder. Enter the name of a user or group within the search box. + :::image type="content" source="media/view-run-queries/new-folder-dialog-new-boards-hubs.png" alt-text="Screenshot of New folder dialog."::: - Here we add the Service Delivery team and grant them permissions to create and manage permissions to all queries and folders under the Service Delivery folder. +1. To set permissions for the new folder, select **More actions** :::image type="icon" source="../media/icons/more-actions.png" border="false"::: > **Security**. - > [!div class="mx-imgBorder"] - > ![Screenshot of Permissions dialog for a query folder.](media/permissions/service-delivery-folder-permissions-team-dialog.png) + :::image type="content" source="media/view-run-queries/select-query-security.png" alt-text="Screenshot of security selection for query folder."::: + +1. Change the permissions so that the team member or group can contribute and manage permissions for the folder. Enter the name of a user or group within the search box. + + This example adds the Service Delivery team and grant them permissions to create and manage permissions to all queries and folders under the Service Delivery folder. + + :::image type="content" source="media/permissions/service-delivery-folder-permissions-team-dialog.png" alt-text="Screenshot of Permissions dialog for a query folder."::: **Contribute** allows team members to create and edit queries and folders under the folder where the permissions were granted. And, **Manage Permissions** allows team members to manage the permission settings on queries and subfolders. -5. (Optional) Turn off inheritance. Default is **On**. By turning off inheritance for a folder, you disallow inheritance of permissions that exist up the chain of query folders. For more information, see [Permissions, Inheritance](../../organizations/security/about-permissions.md#inheritance). +1. (Optional) Turn off inheritance. Default is **On**. By turning off inheritance for a folder, you disallow inheritance of permissions that exist up the chain of query folders. For more information, see [Permissions, Inheritance](../../organizations/security/about-permissions.md#permission-inheritance). -6. Close the dialog when you're done. +1. Close the dialog when you're done. -7. Reopen the Security dialog and choose Service Delivery to verify that the permissions are set. +1. Reopen the Security dialog and choose Service Delivery and verify that the permissions are set. + + :::image type="content" source="media/permissions/permissions-folder-dialog-s166.png" alt-text="Screenshot of Permissions dialog for a query folder, verify permission settings."::: - > [!div class="mx-imgBorder"] - > ![Screenshot of Permissions dialog for a query folder, verify permission settings.](media/permissions/permissions-folder-dialog-s166.png) - ::: moniker-end -::: moniker range="azure-devops-2019" +::: moniker range=">= azure-devops-2020 <= azure-devops-2022" 1. Choose **All**. Expand **Shared Queries**. -1. To add a folder, choose :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **More actions** for an existing folder or the top container folder, and choose **New folder**. +1. To add a folder, choose the **More actions** icon :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: for an existing folder or the top container folder, and choose **New folder**. - > [!div class="mx-imgBorder"] - > ![Screenshot of Open Actions menu, choose New folder.](media/organize-queries/select-new-folder.png) + :::image type="content" source="media/organize-queries/select-new-folder.png" alt-text="Screenshot that shows Open More actions menu, choose New folder."::: -2. Enter the name for the folder. If you want to change the location of the folder, select it from the Folder drop down menu. +1. Enter the name for the folder. If you want to change the location of the folder, select **Rename** from the folder drop-down menu. Here we name the folder *Service Delivery* with the intention that it gets used by the Service Delivery team. - > [!div class="mx-imgBorder"] - > ![Screenshot of New folder dialog, Azure DevOps Server 2019.](media/permissions/new-folder-dialog.png) + :::image type="content" source="media/permissions/new-folder-dialog.png" alt-text="Screenshot of New folder dialog."::: -3. To set permissions for the folder you just added, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon and select **Security**. +1. To set permissions for the folder you just added, choose the **More actions** icon :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: and select **Security**. -4. Change the permissions so that the team member or group can contribute and manage permissions for the folder. Choose the **Add...** menu to add a user identity or group. +1. Change the permissions so that the team member or group can contribute and manage permissions for the folder. Enter the name of a user or group within the search box. Here we add the Service Delivery team and grant them permissions to create and manage permissions to all queries and folders under the Service Delivery folder. - > [!div class="mx-imgBorder"] - > ![Screenshot of Permissions dialog for a query folder, Azure DevOps Server 2019.](media/permissions/permissions-dialog-query-folder-service-delivery.png) + :::image type="content" source="media/permissions/service-delivery-folder-permissions-team-dialog.png" alt-text="Screenshot of Permissions dialog for a query folder."::: **Contribute** allows team members to create and edit queries and folders under the folder where the permissions were granted. And, **Manage Permissions** allows team members to manage the permission settings on queries and subfolders. -5. (Optional) Turn off inheritance. Default is **On**. By turning off inheritance for a folder, you disallow inheritance of permissions that exist up the chain of query folders. For more information, see [Permissions, Inheritance](../../organizations/security/about-permissions.md#inheritance). - -::: moniker-end - +1. (Optional) Turn off inheritance. Default is **On**. By turning off inheritance for a folder, you disallow inheritance of permissions that exist up the chain of query folders. For more information, see [Permissions, Inheritance](../../organizations/security/about-permissions.md#permission-inheritance). -::: moniker range="tfs-2018" +1. Close the dialog when you're done. -1. Add a query folder under **Shared queries** or a subfolder. Choose the :::image type="icon" source="../media/icons/context_menu.png" border="false"::: context menu for the folder and choose **New query folder**. - - ![Screenshot of New query folder menu option and New query folder dialog, TFS 2018. ](media/set-query-perm-new-folder.png) - -1. To set permissions for the folder, choose the :::image type="icon" source="../media/icons/context_menu.png" border="false"::: context menu for the folder you just added and choose **Security**. - - ![Screenshot of context menu for a query folder, Security option, TFS 2018.](media/set-permissions-query-folder-security.png) - -2. Change the permissions so that the team member or group can contribute and manage permissions for the folder. - - Here we add the Web team and grant them permissions to create and manage permissions to all queries and folders under the Triage folder. - - ![Screenshot of Permissions dialog for a Shared query folder, TFS 2018.](media/set-permissions-triage-folder-dialog.png) - - Choose the **Add...** menu to add a user identity or group. - - **Contribute** allows team members to create and edit queries and folders under the folder where the permissions were granted. And, **Manage Permissions** allows team members to manage the permission settings on queries and subfolders. - -3. (Optional) Turn off inheritance. Default is On. By turning off inheritance for a folder, you disallow inheritance of permissions that exist up the chain of query folders. For more information, see [Permissions, Inheritance](../../organizations/security/about-permissions.md#inheritance). +1. Reopen the Security dialog and choose Service Delivery and verify that the permissions are set. + :::image type="content" source="media/permissions/permissions-folder-dialog-s166.png" alt-text="Screenshot of Permissions dialog for a query folder, verify permission settings."::: + ::: moniker-end ## Set permissions on a shared query -To keep anyone else from modifying a shared query that you create, you may want to set permissions on a specific query. You can set permissions by opening the permissions dialog for the specific query. +To keep anyone else from modifying a shared query that you create, you might want to set permissions on a specific query. You can set permissions by opening the permissions dialog for the specific query. -::: moniker range=">= azure-devops-2019" +::: moniker range="azure-devops" -1. Choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon and select **Security**. +1. Choose the **More actions** icon :::image type="icon" source="../media/icons/more-actions.png" border="false"::: and select **Security**. - > [!div class="mx-imgBorder"] - > ![Screenshot of Open query permissions context menu.](media/permissions/query-permissions-select.png) + :::image type="content" source="media/view-run-queries/select-query-security.png" alt-text="Screenshot of Open query permissions context menu."::: -1. Change the permissions so that a team member or group can't edit, delete, or change permissions for the query. +2. Change the permissions so that a team member or group can't edit, delete, or change permissions for the query. Here we deny permissions for the *Disallow access group*. - > [!div class="mx-imgBorder"] - > ![Screenshot of Permissions dialog for a shared query.](media/permissions/deny-access-group-permissions-set.png) + :::image type="content" source="media/permissions/deny-access-group-permissions-set.png" alt-text="Screenshot of Permissions dialog for a shared query."::: ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="< azure-devops" -1. Choose the :::image type="icon" source="../media/icons/context_menu.png" border="false"::: context menu icon and select **Security**. +1. Choose the **More actions** icon :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: and select **Security**. - ![Screenshot of Open query permissions context menu, TFS 2018.](media/set-query-perm-security-menu-option.png) + :::image type="content" source="media/permissions/query-permissions-select.png" alt-text="Screenshot of Open query permissions context menu."::: -1. Change the permissions so that the team member or group can't edit, delete, or change permissions for the query. +1. Change the permissions so that a team member or group can't edit, delete, or change permissions for the query. - Here we deny permissions for the Project Administrators group. + Here we deny permissions for the *Disallow access group*. - ![Screenshot of Permissions dialog for a shared query, TFS 2018.](media/set-permissions-deny-for-query.png) + :::image type="content" source="media/permissions/deny-access-group-permissions-set.png" alt-text="Screenshot of Permissions dialog for a shared query."::: ::: moniker-end - ## Related articles -With queries, you cannot only list work items, you can create status and trend charts and add them to dashboards. You can learn more about permissions and working with queries from these resources: - -- [Manage queries and query folders](organize-queries.md) -- [Permissions and access for work tracking](../../organizations/security/permissions-access-work-tracking.md) +- [Manage queries and query folders](organize-queries.md) +- [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md) - [Add a chart to a dashboard](../../report/dashboards/add-charts-to-dashboard.md) -- [Dashboards](../../report/dashboards/dashboards.md) +- [Manage dashboards](../../report/dashboards/dashboards.md) diff --git a/docs/boards/queries/share-plans.md b/docs/boards/queries/share-plans.md deleted file mode 100644 index 0e82a6c3f72..00000000000 --- a/docs/boards/queries/share-plans.md +++ /dev/null @@ -1,315 +0,0 @@ ---- -title: Share information in work items and social tools in Azure Boards -titleSuffix: Azure Boards -description: Learn how to easily share information about work items, queries, and more in Azure Boards. -ms.custom: boards-queries, engagement-fy23 -ms.service: azure-devops-boards -ms.assetid: 5edac6b9-2642-419a-8745-9e91ee40993b -ms.author: chcomley -author: chcomley -ms.topic: how-to -monikerRange: '<= azure-devops' -ms.date: 10/26/2022 ---- - - -# Share information within work items and social tools in Azure Boards - - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -[!INCLUDE [version-vs-gt-eq-2019.md](../../includes/version-vs-gt-eq-2019.md)] - -Using work items to track your work provides a host of benefits, including the ability to easily share information. You can capture most information within the work item *Description* or other rich-text formatted fields. If you need to maintain the information in a different format, you can easily link to or attach a file. - -Other ways to share information include using dashboards, README files, and project Wikis. - -Using work items, you can share information in the following ways: - -- Add information to the Description or other rich-text field -- Link to a web site or file, or attach files -- Link to a storyboard file - -> [!TIP] -> If you have stakeholders who don't contribute code but want to contribute to the discussion and review progress, make sure you provide them [stakeholder access](../../organizations/security/get-started-stakeholder.md) so that they can view work items and dashboards. - - - - -## Rich text fields - -To convey detailed information, you can format text and insert images inline within any HTML field type. By default, the following fields are HTML fields and many others not listed here for the CMMI process. - -- *Acceptance Criteria* -- *Description* -- *Steps* -- *System Info* - - - You can add custom HTML fields to support your business processes. To learn more about each field, look it up in the [Work item field index](../work-items/guidance/work-item-field.md) - -The specific set of formatting features differs depending on the client you use. In all clients, you can bold, italicize, and underline text. You can also add and remove hyperlinks, format text as ordered or unordered lists, and add images. - - -#### [Browser](#tab/browser/) - -::: moniker range=">= azure-devops-2020" - -The editor toolbar appears below each text box that accepts formatted text. It only becomes active when you move your cursor within the text box. - -> [!div class="mx-imgBorder"] -> ![Rich Text Editor toolbar](media/share-plans/new-rich-text-editor-toolbar.png) - -You can use the :::image type="icon" source="../../media/icons/rtf-clear.png" border="false"::: clear format icon or **CTRL+Spacebar** to remove formatting from highlighted text. - -For the **Discussion** section, the tool bar comes with a few extra icons—:::image type="icon" source="../../media/icons/at-mention.png" border="false"::: at-mention, :::image type="icon" source="../../media/icons/work-id.png" border="false"::: #-work-item-id, and :::image type="icon" source="../../media/icons/pr-id.png" border="false"::: pull-request id—to help bring others into the discussion or link to work items or pull requests. Choose one of these icons and a menu displays with the most recent options that you've worked with. - -> [!div class="mx-imgBorder"] -> ![Discussion section, New Rich Text Editor toolbar](media/share-plans/discussion-rich-text-editor-toolbar.png) - -**Keyboard shortcuts** - -You can copy and paste HTML text or an image from another application directly into the text box using **Ctrl+c** and **Ctrl+v** shortcuts. You can also use the keyboard shortcuts listed in [Keyboard shortcuts](../../project/navigation/keyboard-shortcuts.md). - -> [!TIP] -> Enter **Shift-?** to view additional Keyboard shortcuts for the work item form. -> >[!div class="mx-imgBorder"] -> >![work item form keyboard shortcuts](media/share-plans/shortcuts-work-item-form-s142.png) - -::: moniker-end - -::: moniker range="< azure-devops-2020" - -The rich text formatting toolbar appears above each text box that can be formatted. It only becomes active when you click within the text box. - -![Rich text tool bar](media/rich-text-ui-team-services.png) - -You can use the following shortcut keys to format your text: -- **Bold**: **Ctrl+B** -- *Italic*: **Ctrl+I** -- Underscore: **Ctrl+U** - -You can copy and paste HTML text or an image from another application directly into the text box using **Ctrl+C** and **Ctrl+V** shortcuts. You can also use the ![Remove format](../media/icons/remove-formatting-icon.png) icon or **CTRL+Spacebar** to remove formatting from highlighted text. - -::: moniker-end - - - - -#### [Visual Studio](#tab/visual-studio/) - - - -**Visual Studio 2017-2019/Team Explorer** - -The work item form opens in the web portal for Visual Studio 2017. Work items aren't available from Visual Studio 2019 under the following conditions: -* If you're connected to a GitHub or third-party Git repository. -* If you're set to use the new Git Tool for Visual Studio 2019 as described in [Git experience in Visual Studio](/visualstudio/ide/git-with-visual-studio). - -From the work item form you can choose the font, font size, and text and background colors. - -![Rich text tool bar - Team Explorer](media/rich-text-ui-te.png) - -You can copy and paste HTML text or an image from another application directly into the text box using **Ctrl+C** and **Ctrl+V** shortcuts. You can use the following shortcut keys to format your text: -- **Bold**: **Ctrl+B** -- *Italic*: **Ctrl+I** -- Underscore: **Ctrl+U** - -[!INCLUDE [temp](../../includes/images-not-appearing-vs.md)] - - -* * * - - - - -## Link items to work items or objects - -To support traceability and add context to work items, you can link items to other work items or objects. From a links control tab, you can choose from various link types to based on the objects you want to link to. - -Your link options differ depending on the client you use. For specific guidance, see these resources: - -- [Add link to work items](../backlogs/add-link.md) -- [Link items to support traceability and manage dependencies](link-work-items-support-traceability.md) - - - - - -## Attach files to work items - -You and your team can centralize reference materials by attaching files to your work items. That way they're always readily accessible when you need them. For example, you can attach a screen image that illustrates a problem, a line of code in a text file, a log, an e-mail thread, or a product feature's specification. - -::: moniker range="azure-devops" - -You can add up to 100 attachments to a work item. Attachments are limited to 60 MB. Attempts to add more result in an error message upon saving the work item. -::: moniker-end - -::: moniker range="< azure-devops" - -You can add up to 100 attachments to a work item. Attachments are limited to 60 MB. - -By default, the size of work item attachments is limited to 4 MB. You can use the web service to [increase the size of files you attach up to 2 GB](/previous-versions/azure/devops/reference/xml/change-maximum-attachment-size-work-items). - -::: moniker-end - -Choose the ![Attachment tab icon](../backlogs/media/icon-attachments-tab-wi.png) or **Attachments** tab to attach a file with supplemental information. The following file types support preview as attachments. -- **Image types**: jpg, jpeg, png, jif, jfif, jpx, fpx, pcd, bmp, img, eps, psd, wmf, gif, svg, webp -- **Video types**: mp4, mov, m4v, webm -- **Text & code types**: sql, java, jsp, jar, asp, aspx, css, scss, sass, less, html, htm, xhtml, js, jsx, cs, csv, vb, cpp, cxx, c++, hpp, hxx, h, f#, ts, tsx, py, md, rs, rb, xml, c, php, swift, tex, json, yml, yaml, sbl, asm, d, f, for, go, m, p, pas, r, bat, sh, pl, awk, cmd, lua, sln, proj, txt, log, wiql - - - -#### [Browser](#tab/browser/) - -::: moniker range=">= azure-devops-2019" - -Choose the :::image type="icon" source="../backlogs/media/icon-attachments-tab-wi.png" border="false"::: Attachment tab icon to attach a file to the work item. - -You can drag and drop a file onto the tab or anywhere on the work item form. - -::: moniker-end - -::: moniker range="azure-devops-2019" -> [!NOTE] -> Some features require upgrade to Azure DevOps Server 2019.1. -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -You can continue viewing the attachments as a list or switch to a grid view to show a thumbnail preview. Double-click or right-click on the file to open a preview and cycle through them to quickly find the information you need. - -![Attachments tab, list or grid view](media/share-plans/142_attachments.gif) - -You can drag and drop files into the attachment area. From the browse menu, you can multi-select several files and attach within a single action. You can add attachments to your pull request comments. You can also add attachments in pull request comments by drag-and-drop or by browsing. For more information, see [Syntax support for Markdown files, widgets, and pull request comments, Attachments](../../project/wiki/markdown-guidance.md#attach). - -> [!TIP] -> To get the URL of an image file you've attached, choose to preview it, right-click the image and choose the copy image address. Paste the address into a text editor and discard everything starting with **&download** to the end. - -::: moniker-end - -::: moniker range="tfs-2018" - -Choose the :::image type="icon" source="../backlogs/media/icon-attachments-tab-wi.png" border="false"::: Attachment tab icon to attach a file to the work item. - -You can drag and drop a file onto the tab or anywhere on the work item form. - -![Attachment controls, web portal](media/share-plans-attachment-tab-vsts.png) - -You can edit, open, save, or delete an attachment by choosing an attachment and opening its :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions menu. - -Attachment menu options - -::: moniker-end - - - - -#### [Visual Studio](#tab/visual-studio/) - -Choose the ![plus icon](../media/icons/add-green-icon.png) plus icon to add an attachment. Or, drag and drop files into the attachment area. - -Attachment controls, web portal (on-premises Azure DevOps), Visual Studio and Eclipse - -To open the menu options to download or delete several attachments, choose one or more items and then right-click. - -Attachment menu options, Team Explorer - - -* * * - - - -::: moniker range="azure-devops" - -## Copy URL of attached file - -To quickly copy the URL of an attachment, you can select **Copy attachment link** option from the attachment's :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More actions** menu. - -:::image type="content" source="media/share-plans/copy-url-attachment-menu-option.png" alt-text="Screenshot of work item form, Attachments tab, Copy attachment link attachment menu option."::: -::: moniker-end - - - -## Storyboard your information - -Storyboarding your ideas and goals increases visual understanding. With [PowerPoint Storyboarding](/previous-versions/azure/devops/boards/backlogs/office/storyboard-your-ideas-using-powerpoint) you can bring your ideas to life with storyboard shapes, text, animation, and all the other features that PowerPoint provides. - - -> [!NOTE] -> Starting with Visual Studio 2019, the Team Foundation plug-in for Office deprecated support for Storyboarding with PowerPoint. Also, the Visual Studio Gallery for PowerPoint Storyboarding is deprecated. You can still use the **Storyboard** link type to link to network share objects to share information, however, you can't link from PowerPoint to Azure DevOps using the link feature. - - -::: moniker range="tfs-2018" -> [!NOTE] -> Storyboarding with PowerPoint requires [Office PowerPoint 2007 or later](https://www.microsoftstore.com/store/msstore/pd/PowerPoint-2010/productID.216564300) and the TFS Storyboarding add-in. You install the TFS Storyboarding add-in for PowerPoint by installing one of the latest editions of [Visual Studio](https://visualstudio.microsoft.com/downloads/download-visual-studio-vs) or [Team Foundation Server Standalone Office Integration](https://visualstudio.microsoft.com/downloads). -::: moniker-end - -By linking your storyboard to a work item, you provide your team access to the shared file where they can add their comments. From the ![Links tab icon](../backlogs/media/icon-links-tab-wi.png), **Links**, or a **Storyboards** tab, you can link storyboards that you created using PowerPoint Storyboarding or other application. When you make changes to a linked storyboard, the work item continues to link to the file with the latest changes. - -To open PowerPoint with storyboarding, see [Storyboard your ideas using PowerPoint](/previous-versions/azure/devops/boards/backlogs/office/storyboard-your-ideas-using-powerpoint). - -#### [Browser](#tab/browser/) - - -You can open Storyboarding with PowerPoint from the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions menu within a work item form. - -Start storyboarding within work item web form, web portal - -To link to an existing storyboard, click the ![Links page icon](../media/icons/icon-links-tab-wi.png) Links tab and add a storyboard link. - - -#### [Visual Studio](#tab/visual-studio/) - -From the **Storyboards** tab, click **Start Storyboarding** to open Storyboarding with PowerPoint. Or, you can link to an existing storyboard. - -Storyboards tab, Visual Studio Team Explorer and Eclipse - -* * * - - -## Email a work item query list - -A common way teams share information is by sharing a list of work items. You can email a formatted list or share a link to a query. - -#### [Browser](#tab/browser/) - -You can quickly generate a formatted list using the **Copy as HTML** or **Copy to clipboard** options. See [Copy list](../backlogs/copy-list.md). - - -> [!IMPORTANT] -> If you use the built-in email feature, you can only send the email to individual address for a project member that is recognized by the system. Adding a team group or security group to the to line isn't supported. If you add an email account that the system doesn't recognize, you receive a message that one or more recipients of your email don't have permissions to read the mailed work items. - -#### [Visual Studio](#tab/visual-studio/) - -You can email a formatted query list by choosing the **Send to Microsoft Outlook** option from the context menu. - -:::image type="content" source="media/view-run-queries/send-to-outlook-team-explorer.png" alt-text="Screenshot of Team Explorer, choose Send to Microsoft Outlook query option."::: - -> [!NOTE] -> This feature requires you to have Microsoft Outlook installed. For on-premises Azure DevOps, all email actions require an [SMTP server to be configured](/azure/devops/server/admin/setup-customize-alerts). If you don't have an SMTP server configured, you can work around this by using **Copy as HTML** from the web portal. - -* * * - -## Share data with team dashboards - -You can share progress and status with your team using configurable team dashboards. Dashboards provide easy-to-read, easy access, real-time information. You can add widgets to provide Markdown information, query charts, and more. - -For more information, see [Manage dashboards](../../report/dashboards/dashboards.md). - -## Share information with a project wiki - -You can use your project wiki to share information with other team members. Each wiki corresponds to its own git repository and supports collaborative editing of its content and structure. - -For more information, see [Create a wiki for your project](../../project/wiki/wiki-create-repo.md). - -## Marketplace extensions - -You may find more ways to share information by exporting work items to other applications such as Microsoft Word. For more information, review the [Marketplace extensions that support Microsoft Word](https://marketplace.visualstudio.com/search?term=word&target=AzureDevOps&category=Azure%20Boards&sortBy=Relevance). - -## Related articles - -As you can see, there are many ways to share information using work items alone. See these other tools and features to support planning, tracking, and sharing information with your team. - -- [Dashboards](../../report/dashboards/dashboards.md) -- [Add and edit a wiki](../../project/wiki/add-edit-wiki.md) -- [Work tracking, process, and project limits](../../organizations/settings/work/object-limits.md) \ No newline at end of file diff --git a/docs/boards/queries/titles-ids-descriptions.md b/docs/boards/queries/titles-ids-descriptions.md index b837939d310..1123e0710f6 100644 --- a/docs/boards/queries/titles-ids-descriptions.md +++ b/docs/boards/queries/titles-ids-descriptions.md @@ -7,22 +7,25 @@ ms.service: azure-devops-boards ms.assetid: c0b1fcb1-c4f4-4651-a401-171fa4372518 ms.author: chcomley author: chcomley +ai-usage: ai-assisted ms.topic: example-scenario monikerRange: '<= azure-devops' -ms.date: 10/06/2022 +ms.date: 10/16/2024 --- -# Query by titles, IDs, and rich-text fields in Azure Boards and Azure DevOps +# Query by titles, IDs, and rich-text fields [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -When you want to find work items based on a keyword or phrase or a null text field, you can do so by filtering on single-line text (String), multi-line text (PlainText), and rich-text (HTML) fields. If you find that your queries take too long to return results, review the [Guidance to create high-performing queries](high-performing-queries.md). +When you want to find work items based on a keyword or phrase or a null text field, you can do so by filtering on single-line text (String), multi-line text (PlainText), and rich-text (HTML) fields. If you find that your queries take too long to return results, see [Create a query, Best practices](using-queries.md#best-practices). -## Supported operators and macros +## Prerequisites -Query clauses that specify a text or rich-text field can use the operators and macros listed in the following table. +[!INCLUDE [prerequisites-queries](../includes/prerequisites-queries.md)] +## Supported operators and macros +Query clauses that specify a text or rich-text field can use the operators and macros listed in the following table. --- :::row::: @@ -79,7 +82,7 @@ Query clauses that specify a text or rich-text field can use the operators and m > [!NOTE] > 1. The `Is Empty` and `Is Not Empty` operators are supported for Azure DevOps Server 2019 RC2 and later versions -> 2. The system automatically defaults to filtering based on the current project. For more information, see [Query across projects](using-queries.md#across-projects). +> 2. The system automatically defaults to filtering based on the current project. For more information, see [Query across projects](using-queries.md#query-across-or-within-projects). ## Use `Contains words` for string matches @@ -88,8 +91,17 @@ When you want to filter on a string match, try using the `Contains Words` operat While the `Contains` operator runs a table scan, which isn't only slower, but also consumes more CPU cycles. These CPU cycles contribute towards your resource consuming rate limit. +> [!NOTE] +> The `Contains Words` operator makes use of SQL's [full-text search indexing](./query-operators-variables.md#full-text). When a new value is saved to a long-text field, SQL Server will: +> +> - Split the phrase into individual words +> - Remove any common words that don't really add value to a search (like "a" or "is" in English) +> - Convert words to their common stem (e.g. running, ran, and runner would get converted into "run", as they are all variations on that word) +> - Store these unique keywords in an index. +> +> When a user then runs a query on this field using the `Contains Words` operator, the search will be run against the unique keywords stored in the index. For long-text fields, this makes searching much more efficient and quicker than doing a substring search. By default, SQL defines a "word" as a set of characters between punctuation. For example, periods signify the end of a word, but the period is not considered to be part of the word. Because the full-text search index contains keywords instead of exact phrases, you'll end up getting all the results that contain the same keywords, as determined by the indexing. - + ## Keyword or phrase query with wildcards @@ -106,9 +118,7 @@ For example, specify **Contains Words** and **inform*** to filter on a text [!INCLUDE [temp](../includes/query-clause-tip.md)] - - - + ## Query for specific words and not others @@ -119,50 +129,60 @@ In the following example, these operators filter work items for those items that > [!div class="mx-imgBorder"] > ![Screenshot of Query Editor to include and exclude exact words.](media/text-queries/contains-words-exact-query.png) +> [!NOTE] +> Certain reserved words in SQL, such as `WHERE`, `THEN`, and `AND`, do not return results when used as standalone search terms with the `Contains Words` or `Does Not Contain Words` filters. ## Undefined field value queries -You can find work items that have an undefined field value by using the equals operator (=) and leaving the Value for the field blank. For example, the following filters list all work items of type Task whose Activity field is blank. +You can find work items that have an undefined field value by using the equals operator `=` and leaving the Value for the field blank. For example, the following filters list all work items of type Task whose Activity field is blank. ![Filter based on blank entries](media/example-work-item-queries/IC736440.png) -To list work items based on a field that isn't blank, use the not operator (<>) and leave the Value blank. - - - +To list work items based on a field that isn't blank, use the *not* operator `<>` and leave the Value blank. -::: moniker range=">= azure-devops-2019" + + ## Empty or not empty HTML field queries -You can find work items where no **Description** has been entered. Using the **Is Empty** or **Is Not Empty** with an HTML field supports listing work items with empty or not empty rich text fields. You don't specify a value with this operator. +You can find work items with empty **Description**s. Using the **Is Empty** or **Is Not Empty** with an HTML field supports listing work items with empty or not empty rich text fields. You don't specify a value with this operator. -For example, the following query filters list all work items where some entries have been made into the **Description** field. +For example, the following query filters list all work items with some **Description** field entries. > [!div class="mx-imgBorder"] > ![Filter based non-empty HTML fields](media/example-queries/is-not-empty-query.png) -::: moniker-end +## Filter for special characters + +To filter for a URL or a phrase that contains special characters like `/` or `-`, use a backslash to escape these characters. The following examples show how to filter for a URL and for a phrase with a dash: + +- **Filter for a URL**: Search for a work item title that includes the phrase `https://example.com/path-to-resource`. + - Query: `Title ~ "https:\/\/example.com\/path-to-resource"` + - Results: Returns all work items with the exact URL in the specified field. + +- **Filter for a phrase with a dash**: Search for a work item title that includes `"your-phrase-with-dash"`. + - Query: `Title ~ "feature-update\-2023"` + - Results: Returns all work items that contain the exact phrase with dashes in the specified field. - + > [!NOTE] -> The ability to query for work items that don't have any tags attached to them is not a supported feature. If you'd like to up vote the request to support this feature, you can do so on our Developer Community page, [Be able to search for empty tags](https://developercommunity.visualstudio.com/t/be-able-to-search-for-empty-tags/907425). +> You can't query for work items that don't have any tags attached to them. To up vote this feature request, do so on our Developer Community page, [Be able to search for empty tags](https://developercommunity.visualstudio.com/t/be-able-to-search-for-empty-tags/907425). - + ## Category-based queries -To filter work items based on the category they belong to, use the **In Group** operator. For example, the following filter criteria returns all work items that are in the current project, assigned to the team member, and defined as belonging to the Bug Category. +To filter work items based on the category they belong to, use the **In Group** operator. For example, the following filter criteria return all work items that are in the current project, assigned to the team member, and defined as belonging to the Bug Category. ![Query clause to find work items by category](media/example-work-item-queries/IC720125.png) - + ### What items appear in the Requirement or Task categories? -The default assignments of work item types to each category are listed below for each process. +The default assignments of work item types to each category are listed as follows for each process. | Process | Requirement category | Task category | |---------|---------|---------| @@ -173,7 +193,7 @@ The default assignments of work item types to each category are listed below for Each team can determine if the Bug work item type appears in either the Requirement or Task category. See [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). You can add custom work item types to a backlog. For more information, see [Add or modify a work item type, Add a custom WIT to a backlog or board](../../reference/add-modify-wit.md). - + ## Query for work items that you're following @@ -185,29 +205,29 @@ For example, the following query shows how to query across all projects for acti :::image type="content" source="../work-items/media/follow-work/query-follows.png" alt-text="Query Editor, with ID In @Follows query clause"::: - + ## Query for recent work item activity You can use the following macros to list work items based on recent activity: -- **@MyRecentActivity**: List items you've recently viewed or modified. +- **@MyRecentActivity**: List items you recently viewed or modified. - **@RecentMentions**: List items you were added to via an **@mention** in the last 30 days. -- **@RecentProjectActivity**: List items that have been recently created or modified in your project. +- **@RecentProjectActivity**: List items recently created or modified in your project. Specify the **ID** field and either the **In** or **Not In** operators. -For example, the following query shows how to query for work items that you've recently viewed or modified. +For example, the following query shows how to query for work items that you recently viewed or modified. :::image type="content" source="media/titles-ids/my-recent-activity-macro-query.png" alt-text="Query Editor, with ID In @MyRecentActivity query clause"::: - + ## Common fields for most work item types -The following table describes common fields used to filter queries. The **ID** fields uniquely identify work items in a list. Use the **Title** field to distinguish the work item from all others of the same type. The **Description** and other rich-text (data type=HTML) fields provide additional information that is needed to implement work and track changes. After a work item is created, you can modify all fields except for the **ID**. When you add and save a work item, the ID is assigned by the system and cannot be changed. +The following table describes common fields used to filter queries. The **ID** fields uniquely identify work items in a list. Use the **Title** field to distinguish the work item from all others of the same type. The **Description** and other rich-text (data type=HTML) fields provide additional information that is needed to implement work and track changes. After a work item is created, you can modify all fields except for the **ID**. When you add and save a work item, the ID gets assigned by the system and can't be changed. > [!NOTE] > The system automatically indexes all long-text fields with a data type of **PlainText** and **HTML** fields for full-text search. This includes the **Title**, **Description**, and **Steps to Repro** fields. For more information and server and collation requirements applicable to on-premises Azure DevOps, see [Query fields, operators, values, and variables - Full-text and partial word searches](query-operators-variables.md#full-text). @@ -231,7 +251,7 @@ The following table describes common fields used to filter queries. The **ID** f :::column span="2"::: A description of the criteria to be met before the bug or product backlog item can be closed. - Before work begins on a bug or product backlog item, the criteria for customer acceptance should be described as clearly as possible. Conversations between the team and customers to define the acceptance criteria helps ensure that your team understands your customers' expectations. The acceptance criteria can be used as the basis for acceptance tests so that you can more effectively evaluate whether an item has been satisfactorily completed. + Before work begins on a bug or product backlog item, the criteria for customer acceptance should be described as clearly as possible. Conversations between the team and customers to define the acceptance criteria helps ensure that your team understands your customers' expectations. The acceptance criteria can be used as the basis for acceptance tests so that you can more effectively evaluate whether an item is satisfactorily completed. Reference name=Microsoft.VSTS.Common.AcceptanceCriteria, Data type=HTML :::column-end::: @@ -273,7 +293,7 @@ The following table describes common fields used to filter queries. The **ID** f Repro Steps (or Steps to reproduce) 1 :::column-end::: :::column span="2"::: - The steps that are required to reproduce unexpected behavior. Capture enough information so that other team members can understand the full impact of the problem as well as whether they have fixed the bug. This includes actions taken to find or reproduce the bug and expected behavior. + The steps that are required to reproduce unexpected behavior. Capture enough information so that other team members can understand the full effect of the problem and whether they fixed the bug. This entry includes actions taken to find or reproduce the bug and expected behavior. Reference name=Microsoft.VSTS.TCM.ReproSteps, Data type=HTML :::column-end::: :::column span="1"::: @@ -311,7 +331,7 @@ The following table describes common fields used to filter queries. The **ID** f Team Project :::column-end::: :::column span="2"::: - The project to which a work item belongs. Add this field to a query when you want to filter your list to items in one or more projects. For more information, see [Example queries, query across projects](using-queries.md#across-projects). + The project to which a work item belongs. Add this field to a query when you want to filter your list to items in one or more projects. For more information, see [Example queries, query across projects](using-queries.md#query-across-or-within-projects). Reference name=System.TeamProject, Data type=String :::column-end::: @@ -349,8 +369,7 @@ The following table describes common fields used to filter queries. The **ID** f :::row-end::: > [!NOTE] -> 1. To learn more about working with rich-text fields, see [Share information within work items](share-plans.md#rich-text). -> 2. Upon upgrade to Team Foundation Server 2012, the Description field was changed from a field type of PlainText to **HTML**. Using the **witadmin changefield** command you can revert the data type for this field. See [Manage work item fields (witadmin)](../../reference/witadmin/manage-work-item-fields.md). +> Upon upgrade to Team Foundation Server 2012, the Description field was changed from a field type of PlainText to **HTML**. Using the **witadmin changefield** command you can revert the data type for this field. See [Manage work item fields (witadmin)](../../reference/witadmin/manage-work-item-fields.md). ## Related articles diff --git a/docs/boards/queries/toc.yml b/docs/boards/queries/toc.yml index 68e63828309..70d5e73f84c 100644 --- a/docs/boards/queries/toc.yml +++ b/docs/boards/queries/toc.yml @@ -4,7 +4,7 @@ href: query-index-quick-ref.md - name: Semantic search href: search-box-queries.md -- name: Get started with queries +- name: Manage queries items: - name: View, open, run a query href: view-run-query.md @@ -16,37 +16,25 @@ displayname: delete, rename, dashboard, share, save - name: Chart a query href: ../../report/dashboards/charts.md?toc=/azure/devops/boards/toc.json - - name: Triage work items - href: triage-work-items.md - name: Filter your queries href: ../backlogs/filter-backlogs-boards-plans.md displayname: sort, reorder, group, parent, tags - - name: Best practices to define a query - href: high-performing-queries.md - name: Query FAQs href: query-faqs.yml - name: Set query permissions (Security) href: set-query-permissions.md - expanded: true -- name: Additional query operations - items: - name: Change column options href: ../backlogs/set-column-options.md - - name: Cross-service and enhanced query operations - href: query-support-integration-cross-service-extensions.md - displayname: OData, Power BI, WIQL - name: Bulk import & update work items (CSV) href: import-work-items-from-csv.md displayname: import, export, csv - name: Bulk add or modify work items (Excel) href: ../backlogs/office/bulk-add-modify-work-items-excel.md - - name: Define a query as a hyperlink - href: define-query-hyperlink.md - name: Sample queries items: - name: Example query charts href: example-query-charts.md - displayname: status, monitor, trend, widgets + displayname: status, monitor, trend, widgets - name: Query by title, ID, or description href: titles-ids-descriptions.md displayname: Title, Description, Detail, Repo Steps, Acceptance Criteria, Resolution, System Info, Team Project, Title, Work Item Type, wildcard diff --git a/docs/boards/queries/triage-work-items.md b/docs/boards/queries/triage-work-items.md deleted file mode 100644 index 0c44f6424d8..00000000000 --- a/docs/boards/queries/triage-work-items.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Triage work items by using a work item query in Azure Boards and Azure DevOps -titleSuffix: Azure Boards -ms.global_help.title: Triage work items -description: Review and update work items by using the triage mode from the query results view in Azure Boards and Azure DevOps. -ms.custom: boards-queries -ms.service: azure-devops-boards -ms.assetid: 486A876F-A04F-4DC7-829C-94E88BB9B7E1 -ms.topic: tutorial -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 04/01/2022 ---- - - -# Triage work items with a work item query in Azure Boards and Azure DevOps - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -**Visual Studio 2019 | Visual Studio 2015 | Visual Studio 2013** - -Using a work item query you can quickly review and update work items. Teams often use the triage mode for a query to complete the following tasks: -- Set the priority of a bug or work item -- Assign a work item to a sprint or team member -- Add details to the description, acceptance criteria, or repo steps -- Link-related work items -- Update the status of work items - -In this article you'll learn how to: - ->[!div class="checklist"] -> * Use triage query mode to update a list of work items -> * Bulk save work items that you've updated - -[!INCLUDE [temp](../includes/prerequisites-queries.md)] - - -## Open Queries - -[!INCLUDE [temp](../includes/open-queries.md)] - -## Use triage buttons and save work items - -#### [Browser](#tab/browser/) - -::: moniker range=">= azure-devops-2019" - -The buttons to move up or down within the query results list are outside the work item form. Choose **Bottom** to cycle through the choices for where the work item form appears: **Bottom**, **Right**, or **Off**. - -![Screenshot of Web portal, Queries Results page, move up or down in the list controls.](media/triage-queries/triage-buttons-new-exp.png) - - -You can save each work item as you change it. Or, you can update multiple work items and save them all at once with :::image type="icon" source="../media/icons/save-items.png" border="false"::: **Save Items**. - -:::image type="content" source="media/triage-queries/save-items-web-portal.png" alt-text="Screenshot of Web portal, Queries Results, and Save Items."::: - -If you don't see :::image type="icon" source="../media/icons/save-items.png" border="false"::: **Save Items**, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **More commands** and select the **Save Items** option. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Query results page, save bulk modified items.](../backlogs/media/bulk-modify/query-results-bulk-save-items.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -The buttons to move up or down within the query results list are inside the work item form. Choose **Bottom** to cycle through the choices for where the work item form appears: **Bottom**, **Right**, or **Off**. - -![Screenshot of Triage query results, TFS 2018 version.](media/triage-queries/scrum-active-bug-triage-mode-co.png) - - -You can save each work item as you change it. Or, you can update multiple work items and save them all at once with :::image type="icon" source="../media/icons/save-items.png" border="false"::: **Save Items**. - -::: moniker-end - - -#### [Visual Studio](#tab/visual-studio/) - - -> [!NOTE] -> Triage mode isn't available from Visual Studio 2017. - - -When you choose **View Results** for a query, it opens in triage mode displaying the first item in the list. You can switch from vertical and horizontal views or expand or collapse the triage window using the :::image type="icon" source="media/triage-buttons.png" border="false"::: **Vertical Split**, **Horizontal Split**, **Collapse Bottom Panel**, or **Collapse Top Panel** icons. - -Choose **Previous** or **Next** to move up or down within the query results list. - -:::image type="content" source="media/triage-queries/triage-mode-visual-studio-2019.png" alt-text="Screenshot of View Results and triage mode, Visual Studio."::: - -After making several changes to work items, choose **Save Results** to save all changes. - - -:::image type="content" source="media/triage-queries/triage-mode-save-results-visual-studio-2019.png" alt-text="Screenshot of Save Results for triage mode, Visual Studio."::: - -* * * - - - -## Bulk update and save changes to work items - -From the web portal, you can update several work items through the triage process, and then do a bulk save when you're finished. - - -Multi-select the work items you want to update, choose :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: **More commands**, and then select the option you want from the menu of options. - -![Screenshot of Web portal, Query results multi-select menu.](../backlogs/media/bulk-m-query-results-menu-options-ts.png) - - -Work items shown in bold text indicate that local changes haven't yet been saved to the data store. - -::: moniker range=">= azure-devops-2019" -Choose **Save items** to save all work items you've modified. - -![Screenshot of Choose Save work items to save all modified work items](media/triage-queries/save-work-items-new-exp.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -Choose the ![double-save-icon](../media/icons/icon-double-save.png) double-save icon to save all work items you've modified. - -![Screenshot of Web portal, Query results page, save bulk modified items, TFS 2018 version.](../backlogs/media/bulk-modify-save-ts.png) - -::: moniker-end - - - -## Related articles - -- [Best tool to add, update, and link work items](../work-items/best-tool-add-update-link-work-items.md) -- [Manage bugs](../backlogs/manage-bugs.md) -- [Create a query](using-queries.md) - diff --git a/docs/boards/queries/using-queries.md b/docs/boards/queries/using-queries.md index d251ea152ef..2757175a1c9 100644 --- a/docs/boards/queries/using-queries.md +++ b/docs/boards/queries/using-queries.md @@ -1,67 +1,48 @@ --- -title: Define a work item query with the Query Editor in Azure Boards +title: Define a work item query in Azure Boards titleSuffix: Azure Boards -description: Learn how to create a flat-list, tree, or direct links queries to list, triage, update, and chart work items. -ms.custom: boards-queries, contperf-fy23, linked-from-support, cross-project +description: Learn how to use queries and perform tasks like define a flat-list, clause, or hyperlink, and use a tree, direct link, hyperlink, or logical expression. Also learn how to query across or within projects and view results in a dashboard, and best practices. +ms.custom: boards-queries, linked-from-support, cross-project, engagement-fy23 ms.service: azure-devops-boards ms.assetid: 364000d3-200a-495a-bfb9-83915240af67 +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 12/16/2022 +ms.date: 10/17/2024 --- -# Define a work item query in Azure Boards +# Define a work item query [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-eq-2019.md](../../includes/version-vs-gt-eq-2019.md)] -Work item queries generate lists of work items based on the filter criteria you provide. You can then save and share these managed queries with others. In contrast, semantic searches list work items, but can't be saved or shared. +Work item queries in Azure Boards generate lists of work items based on the filter criteria provided by you. You can save and share these managed queries with others. + ::: moniker range=">= azure-devops-2020" -Create queries from the web portal or from a supported client, such as Visual Studio Team Explorer. You can also define and import a work item query using [WIQL syntax and a .wiq file](query-support-integration-cross-service-extensions.md#wiql). To support bulk updates or additions, import or export queries using [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) or [.csv files](import-work-items-from-csv.md). -::: moniker-end -::: moniker range="< azure-devops-2019" -Create queries from the web portal or from a supported client, such as Visual Studio Team Explorer. You can also define and import a work item query using [WIQL syntax and a .wiq file](query-support-integration-cross-service-extensions.md#wiql). To support bulk updates or additions, import or export queries using [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md). +You can create queries from the web portal or from a supported client, such as Visual Studio Team Explorer. To support bulk updates or additions, import or export queries using [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) or [.csv files](import-work-items-from-csv.md). ::: moniker-end -#### [Browser](#tab/browser/) - -> [!div class="mx-imgBorder"] -> ![Query Editor, web browser.](media/using-queries/query-editor.png) - -#### [Visual Studio](#tab/visual-studio/) - -> [!div class="mx-imgBorder"] -> ![Query Editor, Visual Studio.](media/using-queries/visual-studio-new-query-editor.png) +::: moniker range="azure-devops" -> [!NOTE] -> To define queries in Visual Studio 2019, you need to [Set the Work Items experience](../work-items/set-work-item-experience-vs.md) to the legacy option. +[!INCLUDE [note-new-boards-hub-default-images](../includes/note-new-boards-hub-default-images.md)] -* * * +::: moniker-end +Check out our recommended [best practices](#best-practices), later in this article. -If you find that your queries take too long to return results, review the [Guidance to create high-performing queries](high-performing-queries.md). +## Prerequisites -In this article you'll learn: +[!INCLUDE [temp](../includes/prerequisites-queries.md)] -> [!div class="checklist"] -> * How to add or create a query -> * How to query across projects -> * How to group and ungroup query clauses -> * How to create a tree of work items or a direct-links query - -For quick access to all query tasks, supported operators—such as, `Contains`, `In`, `In Group`, and `<>`(not operator) — based on field data type, and query examples, see [Query quick reference](query-index-quick-ref.md). - ## Choose a query filter -From the Query Editor, exercise the following filter functions. Choose the filter to jump to an article with sample queries. +From the Query Editor, select the filter to jump to an article with sample queries. Along with the query filters, you can [interactively apply filters to query results](../backlogs/filter-backlogs-boards-plans.md). -::: moniker range=">= azure-devops-2019" > [!NOTE] -> Managed queries don't support proximity searches, however semantic searches do. In addition, semantic searches supports both `*` and `?` as wildcard characters and you can use more than one wildcard character to match more than one character. For more information, see [Functional work item search](../../project/search/functional-work-item-search.md). -::: moniker-end +> Managed queries don't support proximity searches, however semantic searches do. Semantic searches also support both `*` and `?` as wildcard characters and you can use more than one wildcard character to match more than one character. For more information, see [Functional work item search](../../project/search/functional-work-item-search.md). --- :::row::: @@ -75,47 +56,33 @@ Along with the query filters, you can [interactively apply filters to query resu --- :::row::: :::column span="1"::: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - [Compare fields](./query-field-value.md) - [Key words](./titles-ids-descriptions.md) - [Linked work items](./linking-attachments.md) - - [Logical groupings](#logical-groupings) - - [Query macros](./about-managed-queries.md#macros) + - [Logical groupings](#use-andor-logical-expression) + - [Query macros](./about-managed-queries.md#supported-macros) - [Tags](./add-tags-to-work-items.md#query) - [Was Ever](./query-by-workflow-changes.md) - [Was Ever (Board Column)](./query-by-workflow-changes.md#kanban_query_fields) - [Wildcard](./titles-ids-descriptions.md) ::: moniker-end - ::: moniker range="tfs-2018" - - [Compare fields](./query-field-value.md) - - [Key words](./titles-ids-descriptions.md) - - [Linked work items](./linking-attachments.md) - - [Logical groupings](#logical-groupings) - - [Query macros](./about-managed-queries.md#macros) - - [Tags](./add-tags-to-work-items.md#query) - - [Was Ever](./query-by-workflow-changes.md) - - [Wildcard](./titles-ids-descriptions.md) - ::: moniker-end + :::column-end::: :::column span="1"::: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - [Blank or empty fields](./titles-ids-descriptions.md#empty-or-not-empty-html-field-queries) - [Boolean searches](./query-by-workflow-changes.md#query-changes-to-a-kanban-board) - [Identity searches](./query-by-workflow-changes.md#me) - [History and Discussion](./history-and-auditing.md) - - [Kanban board fields](./query-by-workflow-changes.md#query-changes-to-a-kanban-board) - - [In and Not In Group searches](./planning-ranking-priorities.md#picklist-query-examples) - - [Search across projects](#across-projects) - ::: moniker-end - ::: moniker range="tfs-2018" - - [Boolean searches](./query-by-workflow-changes.md#query-changes-to-a-kanban-board) - - [History and Discussion](./history-and-auditing.md) + - [Board fields](./query-by-workflow-changes.md#query-changes-to-a-kanban-board) - [In and Not In Group searches](./planning-ranking-priorities.md#picklist-query-examples) - - [Search across projects](#across-projects) + - [Search across projects](#query-across-or-within-projects) ::: moniker-end + :::column-end::: :::column span="2"::: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - [[Any]](titles-ids-descriptions.md) - [@Me](query-by-workflow-changes.md) - [@Today](query-by-date-or-current-iteration.md) @@ -125,116 +92,129 @@ Along with the query filters, you can [interactively apply filters to query resu - [@StartOfDay, @StartOfMonth, @StartOfWeek, @StartOfYear](query-by-date-or-current-iteration.md) - [@TeamAreas](query-by-area-iteration-path.md) ::: moniker-end - ::: moniker range="tfs-2018" - - [[Any]](titles-ids-descriptions.md) - - [@Me](query-by-workflow-changes.md) - - [@Today](query-by-date-or-current-iteration.md) - - [@CurrentIteration](query-by-date-or-current-iteration.md) - - [@Follows](titles-ids-descriptions.md#following) - - [@MyRecentActivity, @RecentMentions, @RecentProjectActivity](titles-ids-descriptions.md#recent-macros) - ::: moniker-end + :::column-end::: :::row-end::: --- -Along with the filters you use from the Query Editor, you can interactively filter a query result using the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: **Filter** function. To learn how, see [Interactively filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md). - -[!INCLUDE [temp](../includes/prerequisites-queries.md)] +You can [interactively filter a query](../backlogs/filter-backlogs-boards-plans.md) using the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: **Filter** function. ## Open Queries [!INCLUDE [temp](../includes/open-queries.md)] - - + ## Define a flat-list query -You can start a fresh, new query from the **Queries** tab in the web portal or the **Work Items** tab in Team Explorer. +Start a new query from the **Queries** tab in the web portal or the **Work Items** tab in Team Explorer. #### [Browser](#tab/browser/) +::: moniker range="< azure-devops" -::: moniker range=">= azure-devops-2019" +1. Select **New** > **New query**. -> [!div class="mx-imgBorder"] -> ![Screenshot to Add new query, new experience.](media/view-run-queries/new-query-new-exp.png) +:::image type="content" source="media/view-run-queries/new-query-new-exp.png" alt-text="Screenshot to Add new query, new experience."::: The Query Editor displays with the following default settings: **Flat list of work items**, **Work Item Type=[Any]**, and **State=[Any]**. :::image type="content" source="media/using-queries/new-query-web-portal.png" alt-text="Screenshot of Query Editor with flat list of work items selected."::: -You can modify the **Values** and [add or remove clauses](#define-clause). Or, change the **Type of query** to [Work items and direct links](#directs-link-query) or to a [Tree of work items](#tree-query). +2. Modify the **Values** and [add or remove clauses](#define-a-clause), or change the **Type of query** to [Work items and direct links](#use-direct-links-to-view-dependencies) or to a [Tree of work items](#use-a-work-item-tree-to-view-hierarchies). + ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="azure-devops" -![Screenshot to Queries page, Choose New query from the drop down menu.](media/using-queries-new-query-ts.png) +1. Select **New** > **New query**. -The Query Editor displays with the following default settings: **Flat list of work items**, **Team Project=@Project** (the current project), **Work Item Type=[Any]**, and **State=[Any]**. +:::image type="content" source="media/view-run-queries/new-query-new-boards-hubs.png" alt-text="Screenshot to Add new query, new experience."::: -:::image type="content" source="media/using-queries/new-query-flat-list-tfs.png" alt-text="Screenshot of Query Editor with flat list of work items selected, TFS 2018 and earlier versions."::: +The Query Editor displays with the following default settings: **Flat list of work items**, **Work Item Type=[Any]**, and **State=[Any]**. -You can modify the **Values** and [add or remove clauses](#define-clause). Or, change the **Type of query** to [Work items and direct links](#directs-link-query) or to a [Tree of work items](#tree-query). +:::image type="content" source="media/using-queries/new-query-dialog-new-boards-hubs.png" alt-text="Screenshot of Query Editor with flat list of work items selected."::: -::: moniker-end +2. Modify the **Values** and [add or remove clauses](#define-a-clause), or change the **Type of query** to [Work items and direct links](#use-direct-links-to-view-dependencies) or to a [Tree of work items](#use-a-work-item-tree-to-view-hierarchies). +::: moniker-end + #### [Visual Studio](#tab/visual-studio/) -Choose **New Query** from the **Work Items** page. - -:::image type="content" source="media/using-queries/new-query-visual-studio-2019.png" alt-text="Screenshot of Work Items, choose New Query."::: -The Query Editor displays with the following default settings: **Flat list (Default)**, **Team Project=current project**, **Work Item Type=[Any]**, and **State=[Any]**. +> [!IMPORTANT] +> We strongly recommend using the [default view](../work-items/view-add-work-items.md?view=azure-devops&tabs=visual-studio&preserve-view=true#view-work-items) instead of this legacy view. This view is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. -:::image type="content" source="media/using-queries/visual-studio-new-query-editor.png" alt-text="Screenshot of Visual Studio Query Editor, flat-list query."::: +1. Select **New Query** from the **Work Items** page. -You can modify the **Values** and [add or remove clauses](#define-clause). Or, change the **Type of query** to [Work items and direct links](#directs-link-query) or to a [Tree of work items](#tree-query). + :::image type="content" source="media/using-queries/new-query-visual-studio-2019.png" alt-text="Screenshot of Work Items, choose New Query."::: + The Query Editor displays with the following default settings: **Flat list (Default)**, **Team Project=current project**, **Work Item Type=[Any]**, and **State=[Any]**. -* * * + :::image type="content" source="media/using-queries/visual-studio-new-query-editor.png" alt-text="Screenshot of Visual Studio Query Editor, flat-list query."::: - +2. Modify the **Values** and [add or remove clauses](#define-a-clause). Or, change the **Type of query** to [Work items and direct links](#use-direct-links-to-view-dependencies) or to a [Tree of work items](#use-a-work-item-tree-to-view-hierarchies). - +--- ## Query across or within projects -New queries scope to the current project by default. However, you can create queries to find work items defined within the organization or project collection. All queries that you save, however, are saved under a specific project. +New queries scope to the current project by default. But, you can create queries to find work items defined within the organization or project collection. All queries that you save, however, get saved under a specific project. #### [Browser](#tab/browser/) To list work items defined in two or more projects, checkmark **Query across projects**. For example, the following query finds all features created in all projects within the last 30 days. - -![Screenshot of Query Editor with Query across projects checked.](media/using-queries/portal-query-across-projects.png) + +::: moniker range="< azure-devops" + +:::image type="content" source="media/using-queries/portal-query-across-projects.png" alt-text="Screenshot of Query Editor with Query across projects checked."::: + +::: moniker-end + +::: moniker range="azure-devops" + +:::image type="content" source="media/using-queries/query-across-projects-new-boards-hubs.png" alt-text="Screenshot of Query across project selections."::: + +::: moniker-end With the **Query across projects** checked, you can add the **Team Project** field to filter to a select number of projects. -![Screenshot of Query Editor with Team Project and other fields added to filter.](media/using-queries/portal-query-across-two-projects.png) +::: moniker range="< azure-devops" -> [!NOTE] -> Separate multiple project names with the list separator that corresponds to the regional settings defined for your client computer, for example, a comma (,). +:::image type="content" source="media/using-queries/portal-query-across-two-projects.png" alt-text="Screenshot of Query Editor with Team Project and other fields added to filter."::: -The **Team Project** field is available only after you check **Query across projects**. Further, when **Query across projects** is unchecked, only those fields from those work item types, as defined in the current project, appear in the **Field** drop-down menu. When **Query across projects** is checked, all fields from all work item types defined in all projects in the collection appear in the **Field** drop-down menu. +::: moniker-end +::: moniker range="azure-devops" + +:::image type="content" source="media/using-queries/query-across-two-projects-new-boards-hubs.png" alt-text="Screenshot of Query Editor with Team Project and other fields added to filter."::: + +::: moniker-end + +> [!NOTE] +> - Separate multiple project names with the list separator that corresponds to the regional settings defined for your client computer, for example, a comma `,`. +> - When you use the 'State' field in a query across multiple projects, the displayed values are limited to those defined in the default project. This means that if you're querying across projects, you might not see all possible state values from each project, but only those from the project that is set as the default. For example, if you have three projects—Project A, Project B, and Project C—and only Project A has a state called 'In Review,' while Projects B and C have different states, querying across these projects only shows the states defined in Project A. + +- The **Team Project** field is available only after you check **Query across projects**. +- When **Query across projects** is checked, all fields from all work item types defined in all projects in the collection appear in the **Field** drop-down menu. +- When **Query across projects** is unchecked, only those fields from those work item types, as defined in the current project, appear in the **Field** drop-down menu. #### [Visual Studio](#tab/visual-studio/) +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md?view=azure-devops&tabs=visual-studio&preserve-view=true#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. + To list work items defined in two or more projects, change the clause for the **Team Project** using the **In** operator, and enter the names of the projects to search in. For example, the following query finds work items defined in the *Fabrikam Fiber* and *Design Agile* projects. :::image type="content" source="media/using-queries/visual-studio-query-multiple-projects.png" alt-text="Screenshot of Visual Studio Query Editor, flat-list query, specify two projects clause."::: To query across all projects, delete the clause with the **Team Project** field. -* * * - - - +--- ## Define a clause -You create a query by defining one or more clauses. Each clause defines a filter criteria for a single field. - +To create a query, define one or more clauses. Each clause defines a filter criteria for a single field. #### Sample query clause @@ -244,25 +224,36 @@ You create a query by defining one or more clauses. Each clause defines a filter For a list of available operators based on the field data type, see [Query index quick reference](query-index-quick-ref.md#fields-operators-macros). -All clauses you add are added as an **And** statement. Choose **Or** to change the grouping. You group clauses to ensure that the clause statements are run in the sequence required. +All clauses get added as an **And** statement. Select **Or** to change the grouping. Group clauses to ensure that the clause statements are run in the sequence required. #### [Browser](#tab/browser/) -Choose **Add new clause** to add another clause at the end of the query, and then choose the **Field**, **Operator**, and **Value** for that clause. +Select **Add new clause** to add another clause at the end of the query, and then select the **Field**, **Operator**, and **Value** for that clause. -> [!div class="mx-imgBorder"] -> ![Screenshot of Query Editor showing how to add a clause.](media/using-queries/define-clause.png) +::: moniker range="< azure-devops" -For example, search for all work items assigned to you by specifying the **Assigned To** field, the equals (**=**) operator, and the **@Me** macro, which represents your user identity. +:::image type="content" source="media/using-queries/define-clause.png" alt-text="Screenshot of Query Editor showing how to add a clause."::: +::: moniker-end + +::: moniker range="azure-devops" + +:::image type="content" source="media/using-queries/define-clause-new-boards-hubs.png" alt-text="Screenshot of Query Editor showing how to add a clause."::: + +::: moniker-end + +For example, search for all work items assigned to you by specifying the **Assigned To** field, the equals (**=**) operator, and the **@Me** macro, which represents your user identity. #### [Visual Studio](#tab/visual-studio/) -Choose **Click here to add a clause** to add another clause at the end of the query, and then choose the **Field**, **Operator**, and **Value** for that clause. +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md?view=azure-devops&tabs=visual-studio&preserve-view=true#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. + +Select **Click here to add a clause** to add another clause at the end of the query, and then select the **Field**, **Operator**, and **Value** for that clause. :::image type="content" source="media/using-queries/visual-studio-add-new-clause.png" alt-text="Screenshot of Visual Studio Query Editor, add new clause."::: -To insert a clause within the existing set of query clauses, place your cursor on the clause below where you want to insert the clause, and then choose **Insert Clause**. Then, choose the **Field**, **Operator**, and **Value** for that clause. +To insert a clause within the existing set of query clauses, place your cursor on the following clause where you want to insert the clause, and then choose **Insert Clause**. Then, select the **Field**, **Operator**, and **Value** for that clause. :::image type="content" source="media/using-queries/visual-studio-add-new-clause.png" alt-text="Screenshot of Visual Studio Query Editor, insert clause."::: @@ -273,29 +264,17 @@ Or, open the context menu for the clause and choose **Insert Clauses**. To delete a clause, choose the clause you want to delete, and choose :::image type="icon" source="../media/icons/icon-delete-clause-visual-studio.png" border="false"::: **Delete Clause**. When finished, choose :::image type="icon" source="../media/icons/run_query.png" border="false"::: **Run** or :::image type="icon" source="../media/icons/icon-save-visual-studio.png" border="false"::: **Save Query**. - - * * * - [!INCLUDE [temp](../includes/tip-wiql-extension.md)] -### Checklist for how to define a query clause - -1. In the first empty row, under the **Field** column heading, choose the down arrow to display the list of available fields, and choose an item in the list. - - For more information, see [Query Fields and Values](query-operators-variables.md#field-values). +### Checklist for defining a query clause -2. In the same row, under the **Operator** column heading, choose the down arrow to display the list of available operators, and choose an item in the list. - - For more information, see [Operators](query-operators-variables.md#operators). - -3. In the same row, under the **Value** column heading, either type a value, or choose the down arrow, and choose an item in the list. - - For more information about how to use a macro or variable to specify the current project, user, date, or other selection, see [Variables](query-operators-variables.md#variables). - -5. To add a clause, choose **Add new clause**. +1. In the first empty row, under the **Field** column heading, choose the down arrow to display the list of available fields, and choose an item in the list. For more information, see [Query Fields and Values](query-operators-variables.md#field-values). +2. In the same row, under the **Operator** column heading, select the down arrow to display the list of available operators, and then choose an item in the list. For more information, see [Operators](query-operators-variables.md#operators). +3. In the same row, under the **Value** column heading, either enter a value, or select the down arrow, and then choose an item in the list. For more information about how to use a macro or variable to specify the current project, user, date, or other selection, see [Variables](query-operators-variables.md#variables). +4. To add a clause, choose **Add new clause**. You can add a clause to the end of the query, or perform the following tasks with the corresponding icons: - :::image type="icon" source="../media/icons/add-green-icon.png" border="false"::: **Insert new filter line** @@ -303,9 +282,6 @@ When finished, choose :::image type="icon" source="../media/icons/run_query.png" - :::image type="icon" source="media/query-fields-operators-values-variables/IC588313.png" border="false"::: **Group selected clauses** - :::image type="icon" source="media/query-fields-operators-values-variables/IC588314.png" border="false"::: **Ungroup clauses** - - - ## Use a work item tree to view hierarchies Use the :::image type="icon" source="media/11.png" border="false"::: **Tree of Work Items** query to view a multi-tiered, nested list of work items. For example, you can view all backlog items and their linked tasks. To focus on different parts of the tree, choose :::image type="icon" source="media/13.png" border="false"::: **Expand all** or :::image type="icon" source="media/14.png" border="false"::: **Collapse all**. @@ -313,40 +289,30 @@ Use the :::image type="icon" source="media/11.png" border="false"::: **Tree of W > [!NOTE] > You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using parent-child link types. However, you can create a direct links query that lists test-related work items. Also, you can, [view the hierarchy through the Test Plans page](../../test/create-a-test-plan.md). - - #### [Browser](#tab/browser/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -> [!div class="mx-imgBorder"] -> ![Screenshot of Query Results List showing a Tree Query.](media/view-run-queries/tree-query-new-exp.png) +:::image type="content" source="media/view-run-queries/tree-query-new-exp.png" alt-text="Screenshot of Query Results List showing a Tree Query."::: ::: moniker-end -::: moniker range="tfs-2018" - -> [!div class="mx-imgBorder"] -> ![Screenshot of Query Results List showing a Tree Query, TFS 2018 view.](media/view-run-queries/tree-query-view-tfs.png) - -::: moniker-end + Define the filter criteria for both parent and child work items. To find linked children, select **Match top-level work items first**. To find linked parents, select **Match linked work items first**. -> [!div class="mx-imgBorder"] -> ![Screenshot of Query Editor view of Tree of work items.](media/view-run-queries/tree-query-editor-s136.png) - +:::image type="content" source="media/view-run-queries/tree-query-editor-s136.png" alt-text="Screenshot of Query Editor view of Tree of work items."::: #### [Visual Studio](#tab/visual-studio/) +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md?view=azure-devops&tabs=visual-studio&preserve-view=true#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. + Define the filter criteria for both parent and child work items. To find linked children, select **Match top-level work items first**. To find linked parents, select **Match linked work items first**. :::image type="content" source="media/using-queries/tree-backlog-te.png" alt-text="Screenshot, Query Editor, Tree Query, Team Explorer. "::: -* * * - - - +* * * ## Use direct links to view dependencies @@ -354,64 +320,51 @@ Use the :::image type="icon" source="media/16.png" border="false"::: **Work item Use the direct links query to track dependencies across teams. The query also helps you manage commitments your team makes. Choose the filter criteria for the top and linked work items. And, select the types of links to filter the dependencies. - #### [Browser](#tab/browser/) -![Screenshot of Direct Links Query Results.](media/17.png) +:::image type="content" source="media/17.png" alt-text="Screenshot of Direct Links Query Results."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of Query Editor, Direct Links Query.](media/view-run-queries/direct-query-editor-s136.png) +:::image type="content" source="media/view-run-queries/direct-query-editor-s136.png" alt-text="Screenshot of Query Editor, Direct Links Query."::: Filter your first-tier list of work items by choosing one of these options: - **Only return items that have matching links**: First-tier work items return, but only if they have links to work items specified by the linked work items filter criteria. - - **Return all top level items**: All first-tier work items return despite the linked work items filter criteria. Second-tier work items that are linked to the first tier return if they match the linked work items filter criteria. - - **Only return items that do not have matching links**: First-tier work items are returned, but only if they don't have links to work items specified by the linked work items filter criteria. - #### [Visual Studio](#tab/visual-studio/) -:::image type="content" source="media/using-queries/direct-links-te.png" alt-text="Screenshot, Query Editor, Direct Links Query, Team Explorer."::: +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md?view=azure-devops&tabs=visual-studio&preserve-view=true#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. +:::image type="content" source="media/using-queries/direct-links-te.png" alt-text="Screenshot, Query Editor, Direct Links Query, Team Explorer."::: Filter your first-tier list of work items by choosing one of these options: - - **Return all top level work items**: All first-tier work items return despite the linked work items filter criteria. Second-tier work items that are linked to the first tier return if they match the linked work items filter criteria. - **Only return items that have the specified links**: First-tier work items return, but only if they have links to work items specified by the linked work items filter criteria. - **Only return items that do not have the specified links**: First-tier work items return, but only if they don't have links to work items specified by the linked work items filter criteria. -* * * - -To learn more about each link type, see [Linking, traceability, and managing dependencies](link-work-items-support-traceability.md). - +* * * - - +For more information about each link type, see [Link type reference](../backlogs/add-link.md). -## And/Or logical expression +## Use and/or logical expression -You specify **And** or **Or** to create logical expressions of your query clauses. Specify **And** to find work items that meet the criteria in both the current clause and the previous clause. Specify **Or** to find work items that meet the criterion in either the current clause or the previous clause. +Specify `And` or `Or` to create logical expressions of your query clauses. Use `And` to find work items that meet the criteria in both the current clause and the previous clause. Use `Or` to find work items that meet the criterion in either the current clause or the previous clause. Add one new clause for each work item field to refine your search criteria. Add clauses to return only the set of work items you want. If you don't receive the results you expect from your query, refine it. You can add, remove, group, or ungroup query clauses to improve your query results. -Group query clauses to operate as a single unit separate from the rest of the query. Grouping clauses is similar to putting parentheses around an expression in a mathematical equation or logic statement. When you group clauses, the **AND** or **OR** for the first clause in the group applies to the whole group. - - +Group query clauses to operate as a single unit separate from the rest of the query. Grouping clauses is similar to putting parentheses around an expression in a mathematical equation or logic statement. When you group clauses, the `And` or `Or` for the first clause in the group applies to the whole group. ### Group clauses -Grouped clauses operate as a single unit separate from the rest of the query. Grouping clauses is similar to putting parentheses around a mathematical equation or logic expression. The **And** or **Or** operator for the first clause in the group applies to the whole group. +Grouped clauses operate as a single unit separate from the rest of the query. Grouping clauses is similar to putting parentheses around a mathematical equation or logic expression. The `And` or `Or` operator for the first clause in the group applies to the whole group. As the following examples show, the grouped clauses are translated to the corresponding logical expression. -> [!TIP] -> To view the WIQL syntax for a query, install the [WIQL query editor extension](https://marketplace.visualstudio.com/items?itemName=ottostreifel.wiql-editor) which allows you to see the WIQL version of any Query UI entry. This extension allows you to see just how AND/OR grouped clauses are treated. - > [!div class="mx-tdCol2BreakAll"] > |Query| Grouped clauses|Logical expression| > |---|---|---| @@ -424,44 +377,41 @@ These queries return work items that are type Bug and meet the following logical - **Query 2**: `AND (State=Active OR Assigned to @Me)` - **Query 3**: `OR (State=Active AND Assigned to @Me)` - -To group one or more clauses, select them and then choose the :::image type="icon" source="../media/icons/group-clauses-icon.png" border="false"::: group clauses icon. +To group one or more clauses, select them and then select the :::image type="icon" source="../media/icons/group-clauses-icon.png" border="false"::: group clauses icon. > [!div class="mx-imgBorder"] > ![Screenshot of Web portal, Query Editor, Group Selected Query Clauses.](media/view-run-queries/group-clauses.png) -You can also group several grouped clauses. Check the boxes of each clause that's already been grouped. Then, choose the :::image type="icon" source="../media/icons/group-clauses-icon.png" border="false"::: group clauses icon. +You can also group several grouped clauses. Check the boxes of each clause. Then, choose the :::image type="icon" source="../media/icons/group-clauses-icon.png" border="false"::: group clauses icon. > [!div class="mx-imgBorder"] > ![Screenshot of Web portal, Query Editor, Group multiple query clauses.](media/using-queries/multiple-clauses.png) - -If your query results don't return expected results, follow these steps: +If your query results don't return expected results, do the following steps: - Make sure that each clause is defined as you intended. -- Verify And/Or assignments to each clause. If your results contain more work items than expected, often an Or clause is present instead of an And clause. -- Determine if you need to group or change the grouping of the query clauses and the And/Or assignments of each grouped clause. +- Verify `And`/`Or` assignments to each clause. If your results contain more work items than expected, often an `Or` clause is present instead of an `And` clause. +- Determine if you need to group or change the grouping of the query clauses and the `And`/`Or` assignments of each grouped clause. - Add more query clauses to refine your query filter criteria. -- Review the options available to specify [fields, operators, and values](query-operators-variables.md). +- Review the options available to specify [fields, operators, and values](query-operators-variables.md). +- See [best practices](#limit-or-operators), later in this article. - + ### Ungroup a clause +To ungroup a clause, select the :::image type="icon" source="../media/icons/ungroup-clause.png" border="false"::: ungroup clauses icon for the grouped clause. -#### [Browser](#tab/browser/) - -To ungroup a clause, choose the :::image type="icon" source="../media/icons/ungroup-clause.png" border="false"::: ungroup clauses icon for the grouped clause. - - -#### [Visual Studio](#tab/visual-studio/) - -To ungroup a clause, choose the :::image type="icon" source="../media/icons/ungroup-clause-visual-studio.png" border="false"::: ungroup clauses icon for the grouped clause, Visual Studio. +## Set default column width in query results -* * * +To set the default column width in query results, do the following steps: +1. Open the query you want to modify. +2. Manually adjust the column widths to your desired size by dragging the edges of the column headers. +3. Select **Save** or **Save As** if you want to save it as a new query. +4. Close and reopen the query to ensure that the column widths are retained. - +Azure DevOps doesn't currently support setting a default column width that persists across all sessions. The column widths are saved per query, so you need to adjust and save them for each query individually. ## View query results in a dashboard @@ -469,20 +419,17 @@ The following two widgets display query results. You can open work items directl - **Work assigned to me**: Lists all proposed or active work items assigned to the signed-in user. Lists the ID, State, and Title fields. - **Query results widget**: Displays the results of a flat, tree, or direct-links query. You can configure the fields displayed through the widget, resize the column fields, and expand and collapse tree and direct-links query. -To learn more about adding widgets to a dashboard, see [Add widgets to a dashboard](../../report/dashboards/add-widget-to-dashboard.md). - +For more information, see [Add widgets to a dashboard](../../report/dashboards/add-widget-to-dashboard.md). - - -::: moniker range="azure-devops" +::: moniker range=" >= azure-devops-2022" ### View query results widget with Parent titles You can view the results of a query with the **Parent** title displayed. To do so, perform these steps: 1. Create the query that filters the work items of interest. The query can be a flat-list, tree, or direct-links query. -2. Add the **Parent** field as a column. -3. Save the query as a Shared query or Team favorite. -3. Add the **Query results widget** to your dashboard and configure the query. Make sure the Parent field is set to display. +1. Add the **Parent** field as a column. +1. Save the query as a Shared query or Team favorite. +1. Add the **Query results widget** to your dashboard and configure the query. Make sure the Parent field is set to display. The following image illustrates a query results widget that displays the **Parent** field. @@ -490,12 +437,135 @@ The following image illustrates a query results widget that displays the **Paren ::: moniker-end -## Related articles +## Define a query as a hyperlink + +A query hyperlink uses the Work Item Query Language (WIQL), which resembles Transact-SQL. For more information, see [Syntax for the Work Item Query Language (WIQL)](wiql-syntax.md). +> [!NOTE] +> Most browsers enforce a limit of between 2000 and 2083 characters for a URL string. +::: moniker range="azure-devops" + +### Query hyperlink syntax + +Encode the WIQL portion of the URL syntax. You can use any URL encoder tool to encode your URL. + +``` +https://dev.azure.com/OrganizationName/ProjectName/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage} +``` +For example, the following hyperlink lists the ID and title of all active bugs defined under the FabrikamFiber/Web area path for the Fabrikam organization. -That's the basics about defining queries. For an index of query examples, see [Query quick reference](query-index-quick-ref.md). +``` +https://dev.azure.com/fabrikam/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.State%5D%3D'Active'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb' +``` + +The decoded WIQL conforms to: + +```wiql +SELECT [System.ID], [System.Title] + FROM WorkItems + WHERE [System.TeamProject]='FabrikamFiber' + AND [System.WorkItemType]='Bug' + AND [System.State]='Active' + AND [System.AreaPath]='FabrikamFiber\Web' +``` + +> [!NOTE] +> The WIQL length must not exceed 32K characters for Azure Boards queries. + +::: moniker-end + +::: moniker range="< azure-devops" + +### Query hyperlink syntax + +``` +https://{ServerName}/{CollectionName}/{ProjectName}/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage} +``` + +For example, the following hyperlink lists the ID, title, and state of all bugs under the FabrikamFiber/Web area path. + +``` +http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%2C%20%5BSystem.State%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb'%20%20 +``` + +For example, see the following nonencoded entry. + +``` +http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql= +SELECT [System.ID], [System.Title], [System.State] + FROM WorkItems + WHERE [System.TeamProject]='FabrikamFiber' + AND [System.WorkItemType]='Bug' + AND [System.AreaPath]='FabrikamFiber\Web' +``` + +::: moniker-end + +## Best practices + +The following best practices apply to the following queries you can create: + +::: moniker range="azure-devops" +- [Web portal queries](view-run-query.md) +- [Work Item Query Language (WIQL) queries](wiql-syntax.md) +- [az boards query command line](view-run-query.md#run-a-query-from-the-command-line) +- [REST API queries](/rest/api/azure/devops/wit/queries) +::: moniker-end + +::: moniker range="< azure-devops" +- [Web portal queries](view-run-query.md) +- [Work Item Query Language (WIQL) queries](wiql-syntax.md) +- [REST API queries](/rest/api/azure/devops/wit/queries) +::: moniker-end + +### Create focused, selective queries + +Define a highly selective query by applying all filters that are necessary for your query. The more selective the query is, the smaller the set of results. The smaller the result set is, the more targeted and selective your query is. + +### Use tags to categorize work items + +Use [work item tags](add-tags-to-work-items.md) to categorize your work items instead of a custom field. Queries that filter on tags usually perform faster over those queries that filter on string matches. + +Unlike custom field matches or partial matches, a query with a `Tags Contains` operation doesn't require a complete scan of all work item tables. + +### Use `Contains words` for string matches + +To filter on a string match, use the `Contains Words` instead of the `Contains` operator. The `Contains Words` operator runs a full-text search on the specified field, which tends to complete more quickly. + +The `Contains` operator runs a table scan, which is a slower operation than the `Contains Words` operator. It also consumes more CPU cycles. These CPU cycles can cause you to encounter rate limitations. For more information, see [Rate and usage limits](../../integrate/concepts/rate-limits.md). + +### Specify small groups with the `In Group` operator + +The `In Group` operator filters work items based on matches within a group of values. The group of values correspond to the values contained within a team, security group, or [work tracking category](../work-items/agile-glossary.md#categories). For example, you can create a query to find all work items that are assigned to any member of a team. Or, find all work items that belong to the requirements category (`Microsoft.RequirementCategory`). + +When you filter on a group that contains a large number of members, your result set tends to be larger and nonselective. Also, if a group corresponds to a large Microsoft Entra group, the query generates a fairly large cost to resolve that group from Microsoft Entra ID. + +### Avoid use of negated operators + +Negated operators—such as `<>, Not In, Not Under, Not In Group`—tend to generate nonselective queries and large result sets. + +Only use negated operators when necessary. Always try to find alternatives first. For example, if **Field1** has values *A*, *B*, *C*, *D*; specify the `Field1 In A, B, C` clause, instead of the negated `Field1 <> D` clause. + +### Avoid string comparisons + +Queries that contain string comparisons generate table scans that are inherently inefficient. Instead, we recommend you use tags or a specific custom field as alternatives, particularly when a query performs poorly. + +### Limit `Or` operators + +Limit the number of `Or` operators defined in your query. Queries run better when fewer `Or` operators are used. Too many `Or` operators can make your query nonselective. If your query runs slowly, reorder the `Or` operator clause towards the top of the query clauses. + +### Save your query + +Due to internal optimizations, saved queries tend to perform better over unsaved queries. Always save your query when you plan to reuse it. Even for WIQL queries run through a REST API, save the WIQL through the web portal to make your [REST API calls](/rest/api/azure/devops/wit/queries), so they're less prone to future performance regressions. + +### Run your query + +Sometimes you need to run your query a few times to reach the right optimization plan. Make sure to save your query and run it up to 10 times over a 30-minute period. This way, the system can examine and seek out the optimization plan that's most appropriate for your query. + +## Related articles +- [Query quick reference](query-index-quick-ref.md). - [Query FAQs](query-faqs.yml) - [Chart a flat-list query](../../report/dashboards/charts.md) - [Change column options](../backlogs/set-column-options.md?toc=/azure/devops/boards/queries/toc.json) - [Work item field index](../work-items/guidance/work-item-field.md) -- [Keyboard shortcuts](../../project/navigation/keyboard-shortcuts.md) \ No newline at end of file +- [Keyboard shortcuts](../../project/navigation/keyboard-shortcuts.md) diff --git a/docs/boards/queries/view-run-query.md b/docs/boards/queries/view-run-query.md index b96f1f208b8..4493f58ea9a 100644 --- a/docs/boards/queries/view-run-query.md +++ b/docs/boards/queries/view-run-query.md @@ -8,7 +8,7 @@ ms.author: chcomley author: chcomley ms.topic: quickstart monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 09/20/2024 --- @@ -17,10 +17,17 @@ ms.date: 04/01/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-eq-2019.md](../../includes/version-vs-gt-eq-2019.md)] -To find work items assigned to you or your team, run a query. Many work item queries are predefined with your process. Members of your team may have created shared queries that you can view and run. Often, it's easier to define a new query by building on the query definition that's already available to you. +To locate work items assigned to you or your team, you can run a query. Your process could include several predefined queries that you can access and run. Often, it's easier to create a new query by modifying an existing query definition. -[!INCLUDE [temp](../includes/prerequisites-queries.md)] +::: moniker range="azure-devops" + +[!INCLUDE [note-new-boards-hub-default-images](../includes/note-new-boards-hub-default-images.md)] +::: moniker-end + +## Prerequisites + +[!INCLUDE [temp](../includes/prerequisites-queries.md)] ## Open Queries @@ -29,45 +36,64 @@ To find work items assigned to you or your team, run a query. Many work item que ## Run a query in Azure Boards To run any query, expand a folder and choose the title of the query. The view opens to display the query **Results**. -::: moniker range=">= azure-devops-2020" -You can also run a query by using the [Azure DevOps command line interface](#cli). + +::: moniker range="azure-devops" + +You can also run a query by using the [Azure DevOps command line interface](#run-a-query-from-the-command-line). + ::: moniker-end #### [Browser](#tab/browser/) +::: moniker range="< azure-devops" > [!TIP] > The **Queries** page, as with other web portal pages, remembers the view you last went to and returns you to that view. -::: moniker range=">= azure-devops-2019" -1. Choose **All** to open the page where you can view all queries you've defined or that are shared within your project. +1. Choose **All** to open the page where you can view all queries that you defined or are shared within your project. - > [!div class="mx-imgBorder"] - > ![Web portal, choose Boards>Queries>All page](media/view-run-queries/queries-all.png) + :::image type="content" source="media/view-run-queries/queries-all.png" alt-text="Screenshot of all queries view." ::: 1. Choose **My Queries** as needed. - - To view all work items assigned to you, choose **Assigned to me**. This query uses the @Me macro to list all work items assigned to you. - - To view all work items you're following, choose **Followed work items**. This query uses the @Follows macro (ID in @Follows) to list all work items you've chosen to follow. For more information, see [Follow a work item or pull request](../work-items/follow-work-items.md). + - To view all work items assigned to you, choose **Assigned to me**. This query uses the **@Me** macro to list all work items assigned to you. + - To view all work items you're following, choose **Followed work items**. This query uses the **@Follows** macro (ID in @Follows) to list all work items you chose to follow. For more information, see [Follow a work item or pull request](../work-items/follow-work-items.md). -2. Choose **Shared Queries** to expand the folder and access queries saved as shared queries. +1. Choose **Shared Queries** to expand the folder and access queries saved as shared queries. -3. Choose a folder within a breadcrumb to open a query folder. - > [!div class="mx-imgBorder"] - > ![Screenshot of queries breadcrumb example.](media/example-queries/queries-breadcrumb-example.png) +1. Choose a folder within a breadcrumb to open a query folder. + + :::image type="content" source="media/example-queries/queries-breadcrumb-example.png" alt-text="Screenshot of queries breadcrumb example." ::: + +::: moniker-end + +::: moniker range="azure-devops" + +> [!TIP] +> The **Queries** page, as with other web portal pages, remembers the view you last went to and returns you to that view. + +1. Choose **All** to open the page where you can view all queries you defined or that are shared within your project. + + :::image type="content" source="media/view-run-queries/open-queries-new-boards-hubs.png" alt-text="Screenshot of all queries view."::: + +1. Choose **My Queries** as needed. + - To view all work items assigned to you, choose **Assigned to me**. This query uses the **@Me** macro to list all work items assigned to you. + - To view all work items you're following, choose **Followed work items**. This query uses the **@Follows** macro (ID in @Follows) to list all work items you follow. For more information, see [Follow a work item or pull request](../work-items/follow-work-items.md). + +1. Choose **Shared Queries** to expand the folder and access queries saved as shared queries. ::: moniker-end #### [Visual Studio](#tab/visual-studio/) - + +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md?view=azure-devops&preserve-view=true&tabs=visual-studio#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. - From the Team Explorer **Work Items**, page, open the context menu for the query (right-click with your mouse), and choose **View Results**. Or, double-click the query to open it. :::image type="content" source="../media/team-explorer/open-query-from-team-explorer.png" alt-text="Screenshot of Team Explorer, open context menu for a query, choose View Results."::: -* * * - - +--- ::: moniker range="azure-devops" @@ -86,7 +112,7 @@ az boards query [--id] #### Parameters - **id**: The ID of an existing query. Required unless--path or--wiql is specified. -- **wiql**: The query in Work Item Query Language format. Ignored if--id or--path is specified. +- **wiql**: The query in Work Item Query Language (WIQL) format. Ignored if `--id` or `--path` is specified. - **path**: The path of an existing query. Ignored if--id is specified. - **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. - **project**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. @@ -122,51 +148,47 @@ Priority Node Name Work Item Type Title Remaining W ``` ::: moniker-end +## Query directory, query folders, and breadcrumbs + +> [!NOTE] +> You can't add folders to **My Favorites** or **Team Favorites**. - +#### [Browser](#tab/browser/) -::: moniker range=">= azure-devops-2019" -## Query directory, query folders, and breadcrumbs +The **Queries** page contains a **Favorites** and an **All** tab. Each contains a directory-focused view that you can filter to find specific queries of interest. -::: moniker-end +When you're working in the **Queries** pages, you can go to a folder, subfolder, or a query page. -::: moniker range="< azure-devops-2019" +::: moniker range="azure-devops" -## Query folders +:::image type="content" source="media/view-run-queries/query-navigation-new-boards-hubs.png" alt-text="Screenshot of queries page." ::: ::: moniker-end +::: moniker range="< azure-devops" -> [!NOTE] -> You can't add folders to **My Favorites** or **Team Favorites**. - -#### [Browser](#tab/browser/) +As you make selections, the breadcrumbs are shown at the top of the page. You can navigate to a folder, subfolder, or query page. +:::image type="content" source="../../project/navigation/media/breadcrumbs/queries-breadcrumbs.png" alt-text="Screenshot of breadcrumbs on query page." ::: -::: moniker range=">= azure-devops-2019" +::: moniker-end -The **Queries** page contains a directory-focused view that you can filter to find specific queries of interest. -When you're working in the **Queries** pages, you can go to a subfolder, folder, or page. +You can also select a favorite query or return to the **All** queries page from the drop-down menu of an open query. -![Queries breadcrumbs](../../project/navigation/media/breadcrumbs/queries-breadcrumbs.png) +::: moniker range="< azure-devops" -Also, you can choose a query that you've favorited from the selector menu, Or, you can choose to browse all queries, which returns you to the **All Queries** page. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Queries, Query selector.](../../project/navigation/media/breadcrumbs/query-bd-and-selector.png) +:::image type="content" source="../../project/navigation/media/breadcrumbs/query-bd-and-selector.png" alt-text="Screenshot of query dropdown." ::: ::: moniker-end +::: moniker range="azure-devops" -::: moniker range="< azure-devops-2019" - -The **Queries** page displays the folder structure in the left pane. You can expand and collapse folders, rename folders, and drag and drop queries from one folder to another. For more information, see [Manage and organize queries](../queries/organize-queries.md). - -:::image type="content" source="media/organize-queries/query-folders-tfs.png" alt-text="Screenshot of Queries page, TFS 2018 and earlier versions."::: +:::image type="content" source="../../project/navigation/media/breadcrumbs/query-dropdown-new-boards-hubs.png" alt-text="Screenshot of query navigation dropdown." ::: ::: moniker-end + #### [Visual Studio](#tab/visual-studio/) The **Work Items** page displays the same folder structure as defined in the web portal. Changes you make through Visual Studio are reflected in the web portal. @@ -176,17 +198,10 @@ The **Work Items** page displays the same folder structure as defined in the web You can expand and collapse folders, rename folders, and drag and drop queries from one folder to another. For more information, see [Manage and organize queries](../queries/organize-queries.md) -* * * +--- For more information, see [Query FAQs, Navigate, and Folders](query-faqs.yml). - - - - - -::: moniker range=">= azure-devops-2019" - ## All and Favorites supported tasks You can do most tasks for viewing and running queries from each of the queries list pages as indicated in the following table. Only queries you save under **My Queries** and have favorited show up under **My Favorites**. Only queries saved under **Shared Queries** can be favorited by a team. @@ -204,24 +219,24 @@ You can do most tasks for viewing and running queries from each of the queries l > |Unfavorite a query (for web portal, choose :::image type="icon" source="../../media/icons/icon-favorited.png" border="false":::) |✔️ |✔️ | ✔️ | > |Add a new query: Choose :::image type="icon" source="/azure/devops/boards/media/icons/add-new-query.png" border="false"::: |✔️ |✔️ | ✔️| -::: moniker-end - -::: moniker range=">= azure-devops-2019" ## Filter the list of queries Enter a keyword into the filter box to filter the set of queries displayed on either the **Favorites** or **All** pages. To learn more about filtering, see [Filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md). -> [!div class="mx-imgBorder"] -> ![Screenshot showing all queries in the project filtered by WIT IQ keyword criteria.](media/queries-all-filter.png) +::: moniker range="< azure-devops" -For more information, see [Query FAQs, Navigate, and Folders](query-faqs.yml). +:::image type="content" source="media/queries-all-filter.png" alt-text="Screenshot showing all queries in the project filtered by a keyword criteria." ::: + +::: moniker-end + +::: moniker range="azure-devops" + +:::image type="content" source="media/view-run-queries/filter-queries-new-boards-hubs.png" alt-text="Screenshot showing all queries in the project filtered by a keyword criteria." ::: ::: moniker-end - - - +For more information, see [Query FAQs, Navigate, and Folders](query-faqs.yml). ## Email query items or share a query URL @@ -229,30 +244,27 @@ For more information, see [Query FAQs, Navigate, and Folders](query-faqs.yml). From the **Query Editor** or **Results** view, you can email a formatted list of query items or copy the query URL. -::: moniker range=">= azure-devops-2019" +::: moniker range="< azure-devops" Choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon to open the menu and select from the options listed, **Email query** or **Copy query URL**. - -> [!div class="mx-imgBorder"] -> ![Web portal, Query Editor/Results, Open Actions menu, Choose Email query or Copy query URL](media/view-run-queries/email-query-new-exp.png) - You can only send the email to individual address for a project member that is recognized by the system. Adding a team group or security group to the to line isn't supported. If you add an email account that the system doesn't recognize, you receive a message that one or more recipients of your email don't have permissions to read the mailed work items. -> [!NOTE] -> To email a formatted list to people who aren't project members, you'll need to use the **Copy as HTML** option described in [Copy a list of work items](../backlogs/copy-clone-work-items.md#html). For on-premises Azure DevOps, all email actions require an [SMTP server to be configured](/azure/devops/server/admin/setup-customize-alerts). If you don't have an SMTP server configured, you can work around this by using **Copy as HTML**. +:::image type="content" source="media/view-run-queries/email-query-new-exp.png" alt-text="Screenshot of Choose Email query or Copy query URL." ::: ::: moniker-end -::: moniker range="tfs-2018" - -Choose **Copy query URL**. To email query items, see [Copy a list of work items](../backlogs/copy-clone-work-items.md#html). +::: moniker range="azure-devops" -![Web portal, Query Editor/Results, Copy query URL](media/view-run-queries/copy-url-old-exp.png) +Choose the more actions icon :::image type="icon" source="../media/icons/more-actions.png" border="false"::: to open the menu and select from the options listed, **Email query** or **Copy query URL**. -> [!NOTE] -> With **Email query**, the system sends an email of the formatted list to those teammates you select. To email a formatted list to people not part of the project, you'll need to use the **Copy as HTML** option described in [Copy a list of work items](../backlogs/copy-clone-work-items.md#html). All email actions require an [SMTP server to be configured](/azure/devops/server/admin/setup-customize-alerts). If you don't have an SMTP server configured, you can work around this by using **Copy as HTML**. +:::image type="content" source="media/view-run-queries/email-query-new-boards-hubs.png" alt-text="Screenshot of Choose Email query or Copy query URL." ::: ::: moniker-end - + +You can only send the email to individual address for a project member that the system recognizes. Adding a team group or security group to the "To" line isn't supported. If you add an email account that the system doesn't recognize, you receive a message that one or more recipients of your email doesn't have permissions to read the mailed work items. + +> [!NOTE] +> To email a formatted list to people who aren't project members, you'll need to use the **Copy as HTML** option described in [Copy a list of work items](../backlogs/copy-clone-work-items.md). For on-premises Azure DevOps, all email actions require an [SMTP server to be configured](/azure/devops/server/admin/setup-customize-alerts). If you don't have an SMTP server configured, you can work around this by using **Copy as HTML**. + #### [Visual Studio](#tab/visual-studio/) @@ -263,7 +275,7 @@ You can email a formatted query list by choosing the **Send to Microsoft Outlook > [!NOTE] > This feature requires you to have Microsoft Outlook installed. For on-premises Azure DevOps, all email actions require an [SMTP server to be configured](/azure/devops/server/admin/setup-customize-alerts). If you don't have an SMTP server configured, you can work around this by using **Copy as HTML** from the web portal. -* * * +--- ## Next steps diff --git a/docs/boards/queries/wiql-syntax.md b/docs/boards/queries/wiql-syntax.md index 2927ecfecbd..7e3cb7f80bd 100644 --- a/docs/boards/queries/wiql-syntax.md +++ b/docs/boards/queries/wiql-syntax.md @@ -17,7 +17,7 @@ ms.date: 10/18/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can use the WIQL syntax to [define a query as a hyperlink](../../boards/queries/define-query-hyperlink.md) or when using the [Work Item Query Language (REST API)](/rest/api/azure/devops/wit/wiql). +You can use the WIQL syntax to [define a query as a hyperlink](using-queries.md#define-a-query-as-a-hyperlink) or when using the [Work Item Query Language (REST API)](/rest/api/azure/devops/wit/wiql). The WIQL syntax supports all functions available through the web portal Query Editor plus a few more. You can specify the fields to return and specify logical grouping of query clauses. In addition, you can use an `ASOF` clause to filter based on assignments based on a previous date. @@ -26,8 +26,9 @@ The WIQL syntax supports all functions available through the web portal Query Ed ## Prerequisites -A query returns only those work items for which you have the **View work items** or **View work items in this node** permission. Typically, these permissions are granted to members of the **Readers** and **Contributors** groups for each team project. For more information, see [Permissions and groups](../../organizations/security/permissions.md). - +| Category | Requirements | +|--------------|-------------| +| **Permissions** | **View work items** or **View work items in this node** permission set to **Allow**. Typically, these permissions get granted to members of the **Readers** and **Contributors** groups for each team project. For more information, see [Permissions and groups](../../organizations/security/permissions.md). | ## Query language overview @@ -50,9 +51,8 @@ ORDER BY [System.ChangedDate] DESC ASOF '02-11-2020' ``` - > [!TIP] -> By installing the [Wiql Editor Marketplace extension](https://marketplace.visualstudio.com/items?itemName=ottostreifel.wiql-editor), you can construct your queries using the Query Editor and then view the WIQL syntax. You can then copy and modify the WIQL syntax and run the query using the **Wiql Playground** hub added to **Boards**. +> By installing the [Wiql Editor Marketplace extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.wiql-editor), you can construct your queries using the Query Editor and then view the WIQL syntax. You can then copy and modify the WIQL syntax and run the query using the **Wiql Playground** hub added to **Boards**. :::row::: :::column span="1"::: @@ -111,7 +111,6 @@ ASOF '02-11-2020' > [!NOTE] > The WIQL length of queries made against Azure Boards must not exceed 32K characters. The system won't allow you to create or run queries that exceed that length. - [!INCLUDE [date-time-pattern](../includes/date-time-pattern.md)] Quote (single or double quotes are supported) DateTime literals used in comparisons. They must be in the .NET DateTime format of the local client computer running the query. Unless a time zone is specified, DateTime literals are in the time zone of the local computer. @@ -134,10 +133,9 @@ WHERE OR [Resolved Date] >= '2019-01-18T00:00:00.0000000') ``` - ### Custom fields -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" You can add a custom field to a query clause. With WIQL, you must specify the reference name for the custom field. For projects that use an Inherited process model, custom fields are typically labeled with **_Custom._** prepended to their name, and spaces removed. For example: @@ -153,15 +151,9 @@ For more information, see [Work item fields and attributes](../work-items/work-i ::: moniker-end -::: moniker range="tfs-2018" - -You can add a custom field to a query clause. With WIQL, you must specify the reference name for the custom field. - -For more information, see [Add or modify a field to track work](../../reference/add-modify-field.md). - -::: moniker-end + - + ## Specify filter clauses (`WHERE`) @@ -189,7 +181,6 @@ WHERE ) ``` - ### Filter conditions Each filter condition is composed of three parts, each of which must conform to the following rules: @@ -201,13 +192,12 @@ Each filter condition is composed of three parts, each of which must conform to - **Operator**: Valid values are specified in the [Operators](#operators) section later in this article. - **Field value**: You can specify one of the following three values depending on the field specified. - A *literal value* must match the data type of the field value. - - A *variable or macro that indicates a certain value. For example, **@Me** indicates the person who is running the query. For more information, see [Macros and variables](#macros) later in this article. + - A *variable* or macro that indicates a certain value. For example, **@Me** indicates the person who is running the query. For more information, see [Macros and variables](#macros) later in this article. - The name of another *field*. For example, you can use `[Assigned to] = [Changed by]` to find work items that are assigned to the person who changed the work item most recently. For a description and reference names of all system-defined fields, see [Work item field index](../work-items/guidance/work-item-field.md). - - + ### Operators @@ -233,7 +223,6 @@ Beyond these basic operators, there are some behaviors and operators specific to > [!NOTE] > The operators available to you depend on your platform and version. For more information, see [Query quick reference](query-index-quick-ref.md). - :::row::: :::column span="1"::: **Field type** @@ -305,8 +294,6 @@ Beyond these basic operators, there are some behaviors and operators specific to :::column-end::: :::row-end::: - - ### Logical groupings You can use the terms `AND` and `OR` in the typical Boolean sense to evaluate two clauses. You can use the terms `AND EVER` and `OR EVER` when specifying a `WAS EVER` operator. You can group logical expressions and further conjoin them, as needed. Examples are shown below. @@ -360,15 +347,13 @@ WHERE AND EVER [System.AssignedTo] = 'Jamal Hartnett ' ``` - - + ## Macros or variables The following table lists the macros or variables you can use within a WIQL query. -::: moniker range=">= azure-devops-2019" - +::: moniker range="<=azure-devops" | Macro | Usage | |---------|-----| @@ -381,17 +366,6 @@ The following table lists the macros or variables you can use within a WIQL quer ::: moniker-end -::: moniker range="< azure-devops-2019" -| Macro | Usage | -|-----------------|----------------| -| **@Me**| Use this variable to automatically search for the current user's alias in a field that contains user aliases. For example, you can find work items that you opened if you set the **Field** column to **Activated By**, the **Operator** column to **=**, and the **Value** column to **@Me**. | -|**@CurrentIteration** | Use this variable to automatically filter for work items assigned to the current sprint for the selected team based on the selected team context. | -| **@Project**|Use this variable to search for work items in the current project. For example, you can find all the work items in the current project if you set the **Field** column to **Team Project**, the **Operator** column to **=**, and the **Value** column to **@Project**. | -|**@Today**| Use this variable to search for work items that relate to the current date or to an earlier date. You can also modify the @Today variable by subtracting days. For example, you can find all items activated in the last week if you set the **Field** column to **Activated Date**, the **Operator** column to **>=**, and the **Value** column to **@Today - 7**. | -|**[Any]** |Use this variable to search for work items that relate to any value that is defined for a particular field. | - -::: moniker-end - ### @me macro @@ -434,11 +408,9 @@ WHERE [System.CreatedDate] > '01-01-2019' ``` + - - - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### @StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear macros @@ -446,14 +418,7 @@ You can use the `@StartOf...` macros with any DateTime field. T ::: moniker-end -::: moniker range="azure-devops-2019" - -> [!NOTE] -> Requires Azure DevOps Server 2019 Update 1 or later version. - -::: moniker-end - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" These macros accept a modifier string that has a format of `(+/-)nn(y|M|w|d|h|m)`. Similar to the `@Today` macro, you can specify plus or minus integer offsets. If the time unit qualifier is omitted, it defaults to the natural period of the function. For example, `@StartOfWeek("+1")` is the same as `@StartOfWeek("+1w")`. If the plus/minus (+/-) sign is omitted, plus is assumed. @@ -464,7 +429,6 @@ WHERE [Microsoft.VSTS.Common.ClosedDate] >=@StartOfYear('+3M') - 1 ``` - The following examples assume that today is 4/5/19. ```WIQL @@ -533,7 +497,6 @@ WHERE > [!NOTE] > If no time is specified, WIQL uses midnight. If no time zone is specified, WIQL uses the time zone of the local client computer. - ## Set the sort order (`ORDER BY`) You can use the `ORDER BY` clause to sort the results of a query by one or more fields in ascending or descending order. @@ -559,15 +522,12 @@ ORDER BY [Microsoft.VSTS.Common.Priority], [System.CreatedDate] DESC ``` - - - + ## Query for links between work items To return links between work items, you specify `FROM WorkItemLinks`. Filter conditions in the `WHERE` clause may apply to the links or to any work item that is the source or the target of a link. For example, the following query returns the links between Product Backlog Items and their active child items. - > [!div class="tabbedCodeSnippets"] ```WIQL SELECT @@ -710,7 +670,6 @@ WHERE ) MODE (Recursive) - ``` ### Direct-link query example @@ -720,7 +679,6 @@ The following query returns all work item types define in the current project. T > [!div class="mx-imgBorder"] > ![Screenshot of Query Editor, direct-link query, all work items and states.](media/wiql/direct-link-query.png) - The equivalent WIQL syntax is as shown. > [!div class="tabbedCodeSnippets"] @@ -752,7 +710,6 @@ ORDER BY [System.Id] MODE (MustContain) ``` - ## More query examples The following typical WIQL query example uses reference names for the fields. The query selects work items (no work item type specified) with a **Priority=1**. The query returns the **ID** and **Title** of the return set as columns. The results are sorted by **ID** in ascending order. @@ -779,7 +736,6 @@ You specify the date-time pattern according to one of two patterns: `AND [System.ChangedDate] >= '1/1/2019 00:00:00Z'` - ### Example clauses The following example statements show specific qualifying clauses. @@ -896,7 +852,6 @@ The following example statements show specific qualifying clauses. :::column-end::: :::row-end::: - ### String and PlainText Quote string literals (single or double quotes are supported) in a comparison with a string or plain text field. String literals support all Unicode characters. @@ -954,22 +909,17 @@ WHERE ) ``` - ## Related articles - [Query fields, operators, values, and variables](query-operators-variables.md) - [Work item fields and attributes](../work-items/work-item-fields.md) - [About managed queries](about-managed-queries.md) -- [Cross-service and enhanced query operations](query-support-integration-cross-service-extensions.md) - [Define a query](using-queries.md) - - - +When you add and manage tasks, your team gains a clear understanding of the importance and required effort for each item. This action ensures better workload distribution and project planning. - -Add as many tasks as needed to capture the work required to complete each item. Tasks can represent different work to be completed, such as design, code, test, content, or sign out. Usually, each team member adds their own tasks and sets estimates for the work. However, a development lead could define the initial tasks for a story or requirement. +## Prerequisites [!INCLUDE [temp](../includes/prerequisites.md)] - ## Open a sprint backlog for a team - ::: moniker range=">= azure-devops-2020" -1. From your web browser, open your team's sprint backlog. (1) Check that you've selected the right project, (2) choose **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), choose **Backlog**. - - > [!div class="mx-imgBorder"] - > ![Open Work, Sprints, for a team](media/add-tasks/open-sprint-backlog-s155-co.png) - - To choose another team, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all sprints** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/add-tasks/team-selector-sprints-agile.png) - -2. To choose a different sprint than the one shown, open the sprint selector and choose the sprint you want. +1. From your web browser, open your team's sprint backlog. (1) Check that you selected the right project, (2) choose **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), choose **Backlog**. > [!div class="mx-imgBorder"] - > ![Choose another sprint](media/add-tasks/select-specific-sprint-agile.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). - - -::: moniker-end - -::: moniker range="azure-devops-2019" - -1. From your web browser, open your team's sprint backlog. (1) Check that you've selected the right project, (2) choose **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), choose **Backlog**. - - ![Open Work, Sprints, for a team](media/add-tasks/open-sprints-backlog-agile.png) + > ![Screenshot shows Open Work, Sprints, for a team.](media/add-tasks/open-sprint-backlog-s155-co.png) To choose another team, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all sprints** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. > [!div class="mx-imgBorder"] - > ![Choose another team](media/add-tasks/team-selector-sprints-agile.png) + > ![Screenshot shows Choose another team.](media/add-tasks/team-selector-sprints-agile.png) 2. To choose a different sprint than the one shown, open the sprint selector and choose the sprint you want. > [!div class="mx-imgBorder"] - > ![Choose another sprint](media/add-tasks/select-specific-sprint-agile.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). - - -::: moniker-end - - -::: moniker range="tfs-2018" + > ![Screenshot shows Choose another sprint.](media/add-tasks/select-specific-sprint-agile.png) -1. From your web browser, open your team's sprint backlog. (1) Select the team from the project/team selector, choose (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - - > [!div class="mx-imgBorder"] - > ![Open the Boards>Backlogs page](media/assign-items-sprint/open-work-backlogs-standard.png) - - To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/assign-items-sprint/team-selector-backlogs-standard.png) - - The set of sprints selected for your team appears in the left pane. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Define sprints](define-sprints.md). - -1. Choose the sprint you want to plan. - - > [!div class="mx-imgBorder"] - > ![Choose another sprint](media/add-tasks/choose-sprint-standard.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). + The system lists only those sprints selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). ::: moniker-end ## Add existing work items to a sprint -If you haven't yet assigned work items to a sprint, see [1. Assign backlog items to a sprint](assign-work-sprint.md). +If you don't have any work items assigned to a sprint, see [1. Assign backlog items to a sprint](assign-work-sprint.md). -If you have added work items and they don't appear in your sprint backlog, check their area and iteration paths. +If you added work items and they don't appear in your sprint backlog, check their area and iteration paths. - The Area Path must match one of the areas assigned to the team -- The Iteration Path must match the iteration of the sprint that you've selected. +- The Iteration Path must match the iteration of the sprint that you selected. For details on assigning iteration paths to teams, see [Define Iteration Paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). -If you have added task work items, but they don't appear as a child of a product backlog item, you can parent them from the sprint backlog. +If you added task work items, but they don't appear as a child of a product backlog item, you can parent them from the sprint backlog. Unparented tasks assigned to the selected sprint appear at the top of the backlog under the Unparented group. Drag and drop the task on top of the work item you want to parent it to. > [!div class="mx-imgBorder"] -> ![Sprint backlog page, parent a task](media/add-tasks/reparent-task.png) - +> ![Screenshot shows Sprint backlog page, parent a task.](media/add-tasks/reparent-task.png) - + ## Add tasks to backlog items -If you haven't yet assigned backlog items to your sprint, [do that now](assign-work-sprint.md). Also, you'll want to have [set the start and end dates for your sprint](define-sprints.md#quick-start-schedule). +If you don't have any backlog items assigned to your sprint, [do that now](assign-work-sprint.md). Also, [set the start and end dates for your sprint](define-sprints.md#quick-start-schedule). For each sprint backlog item, add a task. Adding tasks from the sprint backlog or board automatically links the task to its parent backlog item. > [!TIP] > You can quickly add several tasks on the taskboard by simply entering a title. You can then later bulk edit items to assign them or add additional details. You can also enter *Remaining Work* onto the card by making sure you [add that field to display on the taskboard](customize-taskboard.md). - -::: moniker range=">= azure-devops-2019" - -You can add tasks from the sprint **Backlog** or **Taskboard**. ALl items you add are automatically assigned the **Iteration Path** of the selected sprint. +You can add tasks from the sprint **Backlog** or **Taskboard**. All items you add automatically get assigned to the **Iteration Path** of the selected sprint. From the **Backlog** view, choose the plus sign to open the work item form for a task. > [!div class="mx-imgBorder"] -> ![Sprint backlog page, add task](media/add-tasks/add-task-from-backlog-agile.png) +> ![Screenshot shows Sprint backlog page, add task.](media/add-tasks/add-task-from-backlog-agile.png) Complete the form as described in the next section. -Another option, is to open the **Taskboard**, and add tasks as cards. Select the :::image type="icon" source="../../media/icons/add-icon.png" border="false"::: plus icon, enter a title for the item, and then press Enter on your keyboard. +Another option is to open the **Taskboard**, and add tasks as cards. Select the :::image type="icon" source="../../media/icons/add-icon.png" border="false"::: plus icon, enter a title for the item, and then press Enter on your keyboard. > [!div class="mx-imgBorder"] -> ![Add task from the taskboard](media/add-tasks/add-task-board-agile.png) +> ![Screenshot shows Add task from the taskboard.](media/add-tasks/add-task-board-agile.png) > [!TIP] > You can quickly add tasks through the **Taskboard** by just specifying the title of the work item. To show fields on the card, see [Customize a sprint Taskboard](customize-taskboard.md). -::: moniker-end - - -::: moniker range="tfs-2018" - -You can add tasks from the sprint **Backlog** or **Taskboard**. - -From the **Backlog** view, choose the :::image type="icon" source="../../media/icons/blue-add-icon.png" border="false"::: plus icon to add a new task. - -> [!div class="mx-imgBorder"] -> ![print backlog page, add task](media/add-tasks/sp-add-tasks.png) - -Complete the form as described in the next section. - -Another option, is to open **Taskboard**, and add tasks as cards. Select the :::image type="icon" source="../../media/icons/add-icon.png" border="false"::: plus icon, enter a title for the item, and then press Enter on your keyboard. - -> [!div class="mx-imgBorder"] -> ![Add task from the taskboard](media/add-tasks/add-task-board-standard.png) - -> [!TIP] -> You can quickly add tasks by just specifying the title of the work item. To show fields on the card, see [Customize a sprint Taskboard](customize-taskboard.md). - -::: moniker-end - To interactively filter sprint views, choose **Filter** :::image type="icon" source="../../media/icons/filter-icon.png" border="false":::, and then specify a keyword or select a value for a field or tag. For more information, see [Interactively filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md). - - ## Complete the task form Name the task and enter an estimate for *Remaining Work*. Also, if you know who's doing the work, assign the task to that team member. -::: moniker range=">= azure-devops-2019" > [!div class="mx-imgBorder"] -> ![Add task](media/add-tasks/add-task-form.png) -::: moniker-end - -::: moniker range="tfs-2018" - - -![New task form](media/sp-scrum-task-form.png) -::: moniker-end - +> ![Screenshot shows task form.](media/add-tasks/add-task-form.png) At the planning stage, *Remaining Work* corresponds to an estimate of how long it takes to complete the task. -A good rule of thumb is to size tasks to take no more than a day to complete. If a task is too large, the team should break it down. In some cases, you might not estimate some tasks effectively until other tasks have been completed. Create the task now, but estimate it when you have enough information. +A good rule of thumb is to size tasks to take no more than a day to complete. If a task is too large, the team should break it down. In some cases, you might not estimate some tasks effectively until other tasks get completed. Create the task now, but estimate it when you have enough information. -During the sprint, team members update remaining work to continually reflect the time required to complete the task. This value can actually increase after work begins. For example, after working 4 hours on a task that was estimated to take 8 hours, you realize you need 16 hours over what you estimated. You would update the *Remaining Work* field with 20 (8-4+16). As you complete a task, you might find that more time is required. Always update the task with your best estimate of remaining work. That way, you help accurately reflect the total amount of work remaining in the sprint. +During the sprint, team members update remaining work to continually reflect the time required to complete the task. This value can actually increase after work begins. For example, after working 4 hours on a task that was estimated to take 8 hours, you realize you need 16 hours over what you estimated. You would update the *Remaining Work* field with 20 (8-4+16). As you complete a task, you might find that more time is required. Always update the task with your best estimate of remaining work. That way, you help accurately reflect the total amount of work remaining in the sprint. :::row::: :::column span="1"::: @@ -218,7 +131,7 @@ During the sprint, team members update remaining work to continually reflect the :::column-end::: :::column span="3"::: - The amount of approximate work required to complete a task. Typically, this field doesn't change after it's assigned. + The amount of approximate work required to complete a task. Typically, this field doesn't change after it gets assigned. You can specify work in hours or in days. There are no inherent time units associated with this field. @@ -255,31 +168,41 @@ During the sprint, team members update remaining work to continually reflect the :::column-end::: :::row-end::: - ## Unparented tasks -Tasks without links to parent backlog items or user stories appear at the top of the taskboard. You can track unparented tasks in similar ways to other tasks. You can also drag them to an existing backlog item to parent them. The unparented card tracks the total of remaining work defined for all unparented tasks. However, it isn't associated with any work item. - +Tasks without links to parent backlog items or user stories appear at the top of the Taskboard. You can track unparented tasks in similar ways to other tasks. You can also drag them to an existing backlog item to parent them. The unparented card tracks the total of remaining work defined for all unparented tasks. However, it isn't associated with any work item. -::: moniker range=">= azure-devops-2019" > [!div class="mx-imgBorder"] -> ![Unparented tasks, agile taskboard](media/add-tasks/unparented-tasks.png) -::: moniker-end +> ![Screenshot shows Unparented tasks, agile Taskboard.](media/add-tasks/unparented-tasks.png) -::: moniker range="tfs-2018" +## Unparent a work item -![Unparented tasks](media/ALM_TB_UnparentedTasks_CO.png) +Unparenting a work item removes its association with a parent backlog item or user story. This action is useful for reorganizing tasks or when a work item's parent is no longer relevant. -::: moniker-end +1. From your project, select **Boards** > **Taskboard**. +2. Find the task you want to unparent in the Taskboard. +3. Select the task card to open its details pane. +4. In the work item's details, locate the **Links** section and find the parent link under **Parent** or **Related Work**. +5. Select **Remove** (trash can icon) next to the parent link to delete the association. +6. **Save** the work item. + The task should appear as an unparented task at the top of the Taskboard. +7. Confirm that the task is no longer associated with any parent backlog item or user story. -## Next step +### Tips -> [!div class="nextstepaction"] -> [3. Set sprint capacity](set-capacity.md) +- **Bulk unparenting:** To unparent multiple tasks, consider using the **Bulk edit** feature. Select the tasks you want to unparent, choose **Edit**, and remove the parent links as needed. +- **Using queries:** + - Create a query to list all unparented tasks for easier management. + - Go to **Queries**, create a new query, and set the criteria to filter tasks without a parent. +- **Drag and drop:** Alternatively, you can drag the task directly on the Taskboard to the **Unparented** section if your board configuration supports it. + +## Next steps +> [!div class="nextstepaction"] +> [3. Set sprint capacity](set-capacity.md) ## Related articles diff --git a/docs/boards/sprints/adjust-work.md b/docs/boards/sprints/adjust-work.md index 4989e9fb039..16e3eb384aa 100644 --- a/docs/boards/sprints/adjust-work.md +++ b/docs/boards/sprints/adjust-work.md @@ -30,12 +30,12 @@ Use this article to learn how to: > * Load balance work across your team > * Quickly reassign tasks to another team member +## Prerequisites [!INCLUDE [temp](../includes/prerequisites.md)] ## Open a Sprint backlog for a team - ::: moniker range=">= azure-devops-2020" 1. From your web browser, open your team's sprint backlog. (1) Check that you've selected the right project, (2) choose **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), choose **Backlog**. @@ -55,80 +55,24 @@ Use this article to learn how to: The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). - ::: moniker-end -::: moniker range="azure-devops-2019" - -1. From your web browser, open your team's sprint backlog. (1) Check that you've selected the right project, (2) choose **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), choose **Backlog**. - - ![Open Work, Sprints, for a team](media/add-tasks/open-sprints-backlog-agile.png) - - To choose another team, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all sprints** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/add-tasks/team-selector-sprints-agile.png) - -2. To choose a different sprint than the one shown, open the sprint selector and choose the sprint you want. - - > [!div class="mx-imgBorder"] - > ![Choose another sprint](media/add-tasks/select-specific-sprint-agile.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). - - -::: moniker-end - - -::: moniker range="tfs-2018" - -1. From your web browser, open your team's product backlog. (1) Select the team from the project/team selector, choose (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - - > [!div class="mx-imgBorder"] - > ![Open the Boards>Backlogs page](media/assign-items-sprint/open-work-backlogs-standard.png) - - To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/assign-items-sprint/team-selector-backlogs-standard.png) - - The set of sprints selected for your team appears in the left pane. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Define sprints](define-sprints.md). - -1. Choose the sprint you want to plan. - - > [!div class="mx-imgBorder"] - > ![Choose another sprint](media/add-tasks/choose-sprint-standard.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). - -::: moniker-end - - ## Check your team capacity To view capacity charts, you'll want to turn **Work details** on for a sprint. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!div class="mx-imgBorder"] > ![Turn work details on](media/adjust-work/work-details-on.png) ::: moniker-end - -::: moniker range="tfs-2018" - -> [!div class="mx-imgBorder"] -> ![Turn work details on](media//adjust-work/work-details-on-standard.png) - -::: moniker-end - - ## Move items out of a sprint Move items from the sprint backlog back to the product backlog if your team is over capacity. This action resets the Iteration Path to the default set for your team. Or, you can move the item into the next sprint your team works in. All the tasks that you've defined for that item move with the backlog items. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Here we select two items at the bottom of the sprint backlog, open the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: action icon for one of the items, choose **Move to iteration**, and then select **Backlog**. @@ -140,24 +84,11 @@ Here we select two items at the bottom of the sprint backlog, open the :::image ::: moniker-end - -::: moniker range="tfs-2018" - -Here we select the last item in the sprint backlog and drag it to the product backlog. - -![Drag items back to product backlog](media/IC797613.png) - -> [!TIP] -> Dragging a backlog item to the backlog or another sprint reassigns all child tasks to the same iteration path. Also, you can multi-select several items and drag them to the backlog or another sprint. Users with **Stakeholder** access can't drag-and-drop work items. - -::: moniker-end - - ## Balance work across the team To quickly reassign tasks, drag the task onto the new assignee's capacity bar. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" For example, here we reassign work from Raisa Pokrovskaya to Christie Church. @@ -171,11 +102,6 @@ As you reassign tasks, capacity bars automatically update. ::: moniker-end -::: moniker range="tfs-2018" - -![Reassign tasks](media/IC797838.png) -::: moniker-end - ## Next step > [!div class="nextstepaction"] > [5. Share your sprint plan](share-plan.md) \ No newline at end of file diff --git a/docs/boards/sprints/assign-work-sprint.md b/docs/boards/sprints/assign-work-sprint.md index bb5060b5677..648e83d54c9 100644 --- a/docs/boards/sprints/assign-work-sprint.md +++ b/docs/boards/sprints/assign-work-sprint.md @@ -12,7 +12,6 @@ monikerRange: '<= azure-devops' ms.date: 04/01/2022 --- - # 1. Assign backlog items to a sprint in Azure Boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -26,18 +25,12 @@ The first step in planning your sprint is to assign work from your backlog to a Here's an example of a sprint plan that consists of backlog items and the tasks required to complete each item. By setting team capacity and estimating tasks, the team can see when the team or a team member is at, under, or over capacity. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!div class="mx-imgBorder"] > ![Screenshot of Sprint planning.](media/assign-items-sprint/assign-intro.png) ::: moniker-end - -::: moniker range="tfs-2018" - -![Screenshot of Sprint planning, TFS 2018.](media/sp-intro.png) - -::: moniker-end In this article you'll learn how to: @@ -52,14 +45,14 @@ These items get added to the sprint backlog. In the second part, your team deter They then define and estimate the tasks required to complete each item. Finally, your team commits to implementing some or all of the items based on these estimates. - > [!NOTE] > Sprint planning doesn't need to be challenging. It can be fun and a time for the entire Scrum team to build camaraderie by working together to answer the question of "What can we commit to?" For examples and strategies to keep your sprint planning focused and effective, check out the [What is Scrum?](/devops/plan/what-is-scrum). > > When you've completed your sprint plan, your sprint backlog should contain all the information your team needs to successfully complete work within the time allotted without having to rush at the end. -[!INCLUDE [temp](../includes/prerequisites.md)] +## Prerequisites +[!INCLUDE [temp](../includes/prerequisites.md)] ## Open your team's product backlog @@ -97,52 +90,11 @@ From your web browser, open your product backlog. ::: moniker-end -::: moniker range="azure-devops-2019" - -1. From your web browser, open your product backlog. (1) Check that you've selected the right project, (2) choose **Boards>Backlogs**, and then (3) select the correct team from the team selector menu. - - ![Open Work, Backlogs, for a team](media/assign-items-sprint/open-work-backlogs-agile.png) - - To choose another team, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all team backlogs** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Screenshot for Choose another team, Azure DevOps 2019.](media/assign-items-sprint/team-selector-backlogs-agile.png) - - > [!TIP] - > Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to favorite a team backlog. Favorited artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorited icon) appear at the top of the team selector list. - -1. Check that you have selected **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI) as the backlog level. - - > [!div class="mx-imgBorder"] - > ![Screenshot, Choose product backlog level, Backlog items, Stories, or Requirements, Azure DevOps 2019.](media/assign-items-sprint/select-product-backlog-agile.png) - -2. (Optional) To choose which columns should display and in what order, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select **Column options**. You may want to add the Iteration Path to the set of columns that appear on your backlog. For more information, see [Change column options](../backlogs/set-column-options.md). - - > [!div class="mx-imgBorder"] - > ![Screenshot for Open Column Options, Azure DevOps 2019.](media/assign-items-sprint/open-work-backlogs-column-options-agile.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -1. From your web browser, open your team's product backlog. (1) Select the team from the project/team selector, choose (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - - > [!div class="mx-imgBorder"] - > ![Screenshot, Open the Boards>Backlogs page, TFS 2018.](media/assign-items-sprint/open-work-backlogs-standard.png) - - To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/assign-items-sprint/team-selector-backlogs-standard.png) - - The set of sprints selected for your team appears in the left pane. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Define sprints](define-sprints.md). - -1. (Optional) To choose which columns should display and in what order, choose **Column options**. You may want to add the Iteration Path to the set of columns that appear on your backlog. For more information, see [Change column options](../backlogs/set-column-options.md). - -::: moniker-end + + - + ## Assign work from your backlog to a sprint @@ -152,7 +104,7 @@ Also, you'll want to have [set the start and end dates for your sprint](define-s You can quickly assign work items to a sprint through drag-and-drop from the product backlog to the sprint. -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" 1. The next step is to open the Planning pane. Choose the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: view options icon and select **Planning**. While you're at it, make sure **Parents** and **Forecasting** are Off. You can choose to set **In Progress items** to On or Off. @@ -180,20 +132,6 @@ You can quickly assign work items to a sprint through drag-and-drop from the pro ::: moniker-end - -::: moniker range="tfs-2018" - -Select one or more items and drag them to one of the listed sprints. - -> [!NOTE] -> The **Iteration Paths** listed only show the current sprint and the next 10 future sprints in the list, even if more have been selected for the team. Only a team administrator or member of the **Project Administrators** group can [select iterations for a team](../../organizations/settings/set-iteration-paths-sprints.md). - -> [!div class="mx-imgBorder"] -> ![Product backlog page, drag work items to sprint or assign to sprint through the context menu](media/sp-assign-to-sprints.png) - -::: moniker-end - - ## Use the multi-select feature to modify items in bulk @@ -209,7 +147,6 @@ With multi-select, you can complete several actions on several work items at onc - Add links - [Map items or change the parent an item is linked to](../backlogs/organize-backlog.md#mapping) - To select several items in a sequence, hold down the shift key. To select several non-sequential items, use the Ctrl key. Then, you can either drag the selected items to a new position within the backlog, to a different sprint, or select an option from the context (![context icon](../media/icons/context_menu.png)) or action ( :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: ) menu of one of the items. For more information, see [Bulk modify work items](../backlogs/bulk-modify-work-items.md). diff --git a/docs/boards/sprints/best-practices-scrum.md b/docs/boards/sprints/best-practices-scrum.md index ccd12096e83..908c19abfe0 100644 --- a/docs/boards/sprints/best-practices-scrum.md +++ b/docs/boards/sprints/best-practices-scrum.md @@ -25,7 +25,7 @@ Much of sprint planning involves a negotiation between the product owner and the In the first part of the meeting, your product owner meets with your team to discuss the user stories that might be included in the sprint. Your product owner shares information and answers any questions that your team has about those stories. This conversation might reveal details such as data sources and user interface layout. Or it might reveal response time expectations, and considerations for security and usability. Your team should capture these details within the backlog items form. During this part of the meeting, your team learns what it must build. -As you plan your sprints, you may discover other requirements to capture and add to your backlog. Before your sprint planning meeting, you'll want to [refine your backlog](../backlogs/best-practices-product-backlog.md#refine) to make sure it's well defined and in priority order. +As you plan your sprints, you may discover other requirements to capture and add to your backlog. Make sure it's well defined and in priority order. Also, setting a sprint goal as part of your planning efforts can help the team stay focused on what's most important for each sprint. @@ -42,7 +42,7 @@ You can learn more from these resources: ## Set sprint goals Scrum teams use sprint goals to focus their sprint activities. They often set this goal during their sprint planning meeting. The goal summarizes what the team wants to accomplish by the end of the sprint. By explicitly stating the goal, you create shared understanding within the team of the core purpose. The sprint goal can also help guide the team when conflicts arise around priorities. - + ## Tips from the trenches: Define sprint goals diff --git a/docs/boards/sprints/customize-taskboard.md b/docs/boards/sprints/customize-taskboard.md index 6aa2ceb52f6..552ef8bc362 100644 --- a/docs/boards/sprints/customize-taskboard.md +++ b/docs/boards/sprints/customize-taskboard.md @@ -12,39 +12,31 @@ monikerRange: '<= azure-devops' ms.date: 04/01/2022 --- - -# Customize cards on a sprint taskboard in Azure Boards +# Customize cards on a sprint Taskboard in Azure Boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] ::: moniker range=">= azure-devops-2020" -Sprint Taskboards are similar to Kanban boards because they show work items as cards instead of as lists. They're different in the ways summarized in [Backlogs, Boards, and Plans](../backlogs/backlogs-boards-plans.md#kanban-Taskboards). Similar to the Kanban boards, you can customize cards and add columns. - -::: moniker-end - - -::: moniker range="<= azure-devops-2019" - -Sprint Taskboards are similar to Kanban boards in that they show work items as cards instead of as lists. They're different in the ways summarized in [Backlogs, Boards, and Plans](../backlogs/backlogs-boards-plans.md#kanban-Taskboards). Similar to the Kanban boards, you can customize cards. To change column names or add columns, you need to customize the workflow. +Sprint Taskboards are similar to boards because they show work items as cards instead of as lists. They're different in the ways summarized in [Backlogs, Boards, and Plans](../backlogs/backlogs-boards-plans.md#kanban-Taskboards). Similar to boards, you can customize cards and add columns. ::: moniker-end > [!NOTE] -> This article addresses customization of a sprint Taskboard. For information on customizing a Kanban board, see [Manage and configure team tools](../../organizations/settings/manage-teams.md#configure-team-backlogs). - +> This article addresses customization of a sprint Taskboard. For information on customizing a board, see [Manage and configure team tools](../../organizations/settings/manage-teams.md#configure-team-backlogs). ## Prerequisites -* You must have a sprint Taskboard you want to configure. When you add a team, you add a Taskboard for every sprint that you select for your team. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). -* To add or rename columns, or customize cards, you must be added to the team administrator role for the team's settings you want to modify, or be a member of the **Project Administrators** security group. To get added, see [Add a team administrator](../../organizations/settings/add-team-administrator.md) or [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). - +| Category | Requirements | +|--------------|-------------| +| **Taskboard** | A sprint Taskboard that you want to configure. When you add a team, you add a Taskboard for every sprint selected for your team. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). | +| **Permissions** | To add or rename columns, or customize cards: [Team Administrator](../../organizations/settings/add-team-administrator.md) role for the team's settings that you want to modify, or Member of the [**Project Administrators** group](../../organizations/security/change-project-level-permissions.md). | ## Taskboard customization options To add or remove columns, choose **Column Options**. You customize all other options through the **Settings** dialog for the Taskboard. -[!INCLUDE [temp](../../includes/version-selector-minimize.md)] +[!INCLUDE [temp](../../includes/version-selector.md)] :::row::: :::column span="1"::: @@ -84,16 +76,7 @@ To add or remove columns, choose **Column Options**. You customize all other opt :::column-end::: :::row-end::: ::: moniker-end -::: moniker range="< azure-devops-2020" -:::row::: - :::column span="1"::: - **[Fields](#choose-fields)** - :::column-end::: - :::column span="3"::: - Add or remove fields from cards. - :::column-end::: -:::row-end::: -::: moniker-end + :::row::: :::column span="1"::: **[Styles](#style-rule)** @@ -107,7 +90,6 @@ To add or remove columns, choose **Column Options**. You customize all other opt > [!NOTE] > Each team can customize their Taskboard columns and cards. Taskboard settings are not inherited from other teams that they may share portions of area paths. - ## Understand the Taskboard customization sequence Before you configure your Taskboard, you'll want to make sure the following tasks are as complete as possible. Otherwise, you'll find yourself revisiting your configuration. @@ -117,18 +99,10 @@ Before you configure your Taskboard, you'll want to make sure the following task 2. Customize your iteration backlog to ensure all of your wanted work item types appear on the Taskboards. For more information, see [Customize backlogs & boards](../../organizations/settings/work/customize-process-backlogs-boards.md). 3. Customize each work item type to have any custom fields you want to show. For more information, see [Customize a workflow](../../organizations/settings/work/add-custom-field.md). - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!NOTE] -> You can customize a work item type which is different then customizing the card displayed on the Taskboard. You customize a WIT by adding fields, changing the workflow, adding custom rules and more. You can also add custom work item types and custom backlog levels. For more information, see [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md). - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -> [!NOTE] -> You can customize a work item type which is different then customizing the card displayed on the Taskboard. You customize a WIT by adding fields, changing the workflow, adding custom rules and more. You can also add custom work item types and custom backlog levels. For more information, see [Customize the On-premises XML process model](../../reference/on-premises-xml-process-model.md). +> You can customize a work item type which is different than customizing the card displayed on the Taskboard. You customize a WIT by adding fields, changing the workflow, adding custom rules and more. You can also add custom work item types and custom backlog levels. For more information, see [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md). ::: moniker-end @@ -143,7 +117,6 @@ Before you configure your Taskboard, you'll want to make sure the following task If you want bugs to appear on your taskboard, change your team settings for [show bugs on the backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). - ::: moniker range=">= azure-devops-2020" @@ -153,7 +126,7 @@ If you want bugs to appear on your taskboard, change your team settings for [sho You can add columns or rename columns that appear in your Taskboard. You'll see different column titles and choices based on the [process](../work-items/guidance/choose-process.md) used to create your project and whether your team has chosen to [treat bugs like requirements or like tasks](../../organizations/settings/show-bugs-on-backlog.md). > [!NOTE] -> Columns you add to a Taskboard aren't supported with corresponding fields such as the Kanban board columns you add which is supported with Board Column field. +> Columns you add to a Taskboard aren't supported with corresponding fields such as the board columns you add which is supported with Board Column field. The changes made apply to all sprint Taskboards for the selected team. @@ -171,19 +144,18 @@ The changes made apply to all sprint Taskboards for the selected team. > [!div class="mx-imgBorder"] > ![Customize Columns dialog](media/customize/customize-columns-taskboard.png) - Similar to the Kanban board, each column must map to a category state. There are four category states: *Proposed*, *Committed*, *In Progress*, and *Completed*. At least one column must map to *Proposed* and one column must map to *Completed*. To learn more about each state, see [Workflow states and state categories](../work-items/workflow-and-state-categories.md). + Similar to the board, each column must map to a category state. There are four category states: *Proposed*, *Committed*, *In Progress*, and *Completed*. At least one column must map to *Proposed* and one column must map to *Completed*. To learn more about each state, see [Workflow states and state categories](../work-items/workflow-and-state-categories.md). -4. To change the column order, hover over the column and choose the :::image type="icon" source="../media/icons/grabber.png" border="false"::: grabber icon and drag it up or down within the list of columns. +2. To change the column order, hover over the column and choose the :::image type="icon" source="../media/icons/grabber.png" border="false"::: grabber icon and drag it up or down within the list of columns. > [!div class="mx-imgBorder"] > ![Move column](media/customize/choose-column-move.png) -5. To delete a column, first make sure that the column doesn't contain any work items. If it does, move the items to another column. Then, hover over the column and choose the :::image type="icon" source="../media/icons/trash-can.png" border="false"::: delete icon. +3. To delete a column, first make sure that the column doesn't contain any work items. If it does, move the items to another column. Then, hover over the column and choose the :::image type="icon" source="../media/icons/trash-can.png" border="false"::: delete icon. > [!div class="mx-imgBorder"] > ![Delete column](media/customize/choose-column-delete.png) - ::: moniker-end @@ -215,9 +187,9 @@ Your best bet is to show fields on cards based on what your team frequently refe ### Add or remove fields from cards on the Taskboard -You change the way cards appear on the Taskboard in the same way you change the appearance of cards on Kanban boards. Only here, you start from the Taskboard. +You change the way cards appear on the Taskboard in the same way you change the appearance of cards on boards. Only here, you start from the Taskboard. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. [Open the taskboard](task-board.md) for the sprint you want to customize. Remember, only [team or project administrators](../../organizations/settings/add-team-administrator.md) can customize the taskboard. @@ -243,31 +215,7 @@ You change the way cards appear on the Taskboard in the same way you change the ::: moniker-end - -::: moniker range="tfs-2018" - -1. [Open the taskboard](task-board.md) for the sprint you want to customize. Remember, only [team or project administrators](../../organizations/settings/add-team-administrator.md) can customize the taskboard. - -1. Choose the :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: gear icon to open the Settings dialog. - - ![taskboard, open card customization dialog](media/customize/task-board-customize-open-settings.png) - -2. Choose **Fields** and then a work item type to see all the settings you can modify. - -3. Place a check mark in the check box for those fields you want to have appear on the board. - - > [!div class="mx-imgBorder"] - > ![Settings dialog, Fields, Task work item type](media/customize/settings-fields-taskboard-142.png) - - Repeat this step for each work item type you want to change. Don't be surprised if the options change when you choose a different work item type. For example, **Show Remaining Work** only applies to tasks and perhaps bugs, but not to user stories or product backlog items. - -4. To add a field, choose the :::image type="icon" source="../media/icons/green_plus_icon.png" border="false"::: plus icon and enter the name of a field you want to add. - -5. To remove a field, choose the :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: delete icon next to the field. - -6. When you're done with your changes, choose **Save**. - -::: moniker-end + @@ -284,7 +232,7 @@ Moving the card from In Progress to the Done column on the Task board, for examp Another handy feature is to update a field without having to open the work item. You can update most fields shown on the card. Here we reassign a task. -![Kanban board, assign a work item](media/customize/field-reassign.png) +![Board, assign a work item](media/customize/field-reassign.png) This quick update feature is useful when you need to update many work items at once. For example, you can add estimates or update Remaining Work. @@ -303,7 +251,6 @@ To add tags, double-click the work item to open it. And, just a reminder, you ca With styling rules, you can cause cards to change color when their corresponding work items meet criteria that you set. Here, we highlight Priority 1 tasks by having the cards display as green. - ![Styling rule applied to tasks with Priority=1](media/customize/task-style-green.png) ### Example styling rules @@ -327,7 +274,7 @@ What rules should you apply to highlight work items? Here are a few examples and You can apply style rules to change the color of Taskboard cards based on specified field criteria. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. [Open the Taskboard](task-board.md) that you want to customize. @@ -360,37 +307,6 @@ You can apply style rules to change the color of Taskboard cards based on specif ::: moniker-end - -::: moniker range="tfs-2018" - -1. [Open the Taskboard](task-board.md) that you want to customize. If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize boards. - -2. Choose the :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: gear icon to open the **Settings** dialog. - -3. Choose **Styles** to specify a style rule. Choose the :::image type="icon" source="../../media/icons/green_plus_icon.png" border="false"::: plus icon to add a style. Select the color to apply to the card and define the criteria for the style rule. - - In this example, we show the **Styles** dialog for the taskboard. - - > [!div class="mx-imgBorder"] - > ![Settings, Styles dialog](media/customize/taskboard-styles-priority.png) - - Follow these rules when creating and ordering your style rules: - - The criteria you specify works in a similar fashion as when [constructing a query](../queries/using-queries.md) - - All clauses are considered AND clauses, grouping clauses isn't supported - - Card rules apply to all work items that meet the rule criteria - - Rule color applies to work items based on the order in which rules are listed. If you add more than one style rule, make sure that you move them in the order of most importance. Drag them into the order you want them applied. - - You can quickly enable and disable a style rule - - Here we add a Stale tasks rule that highlights tasks that haven't changed in the last five days. - - ![taskboard, Style dialog, example style rule](media/customize/task-board-card-style-rule-stale-tasks.png) - -4. To copy or delete a style rule, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select **Clone** or **Delete**, respectively. - -5. When you're done with your changes, choose **Save**. - -::: moniker-end - ::: moniker range=">= azure-devops-2020" ## Changes cause automatic taskboard updates @@ -399,10 +315,8 @@ Your Taskboard automatically refreshes when changes occur. There isn't any live ::: moniker-end - ## Related articles - [Manage and configure team tools](../../organizations/settings/manage-teams.md) - [Setup your backlogs and boards](../backlogs/set-up-your-backlog.md) - [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md) -- [Set working days](../../organizations/settings/set-working-days.md) diff --git a/docs/boards/sprints/define-sprints.md b/docs/boards/sprints/define-sprints.md index 5a0c4623772..5c70b5134b0 100644 --- a/docs/boards/sprints/define-sprints.md +++ b/docs/boards/sprints/define-sprints.md @@ -12,7 +12,6 @@ monikerRange: '<= azure-devops' ms.date: 09/20/2021 --- - # Manage sprint timelines [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -25,13 +24,15 @@ With Scrum, teams plan and track work at regular time intervals, referred to as ## Prerequisites -* To change sprint dates, you must be a member of the **Project Administrators** security group, or have the **Edit this node** permission for the iteration child node you want to change. By default, the user who created the project has these permissions set. For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) or [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). +| Category | Requirements | +|--------------|-------------| +| **Permissions** | To change sprint dates: Member of the [**Project Administrators** group](../../organizations/security/change-project-level-permissions.md), or **Edit this node** permission for the iteration child node you want to change. By default, the user who created the project has these permissions set. For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) or [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). | ## Start scheduling sprints -To quickly get started, you can use the default sprints. Default sprints are also referred to as iterations and were added when your project was created. Note, you must be a member of the [**Project Administrators** group](../../organizations/security/change-project-level-permissions.md) to add sprints and schedule sprint dates. If you created the project, you're a member. +To quickly get started, you can use the default sprints. Default sprints are also referred to as iterations and were added when your project was created. Note, be a member of the [**Project Administrators** group](../../organizations/security/change-project-level-permissions.md) to add sprints and schedule sprint dates. If you created the project, you're a member. ::: moniker range=">= azure-devops-2020" @@ -62,70 +63,6 @@ To quickly get started, you can use the default sprints. Default sprints are als ::: moniker-end -::: moniker range="azure-devops-2019" - -1. From your web browser, open your team's sprint backlog. (1) Check that you've selected the right project, (2) choose **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), choose **Backlog**. - - ![Open Work, Sprints, for a team](media/add-tasks/open-sprints-backlog-agile.png) - -1. To choose another team, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all sprints** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/add-tasks/team-selector-sprints-agile.png) - -2. Choose **Set sprint dates**. - - > [!div class="mx-imgBorder"] - > ![Boards>Sprints>set dates](media/define-sprints/set-sprint-dates-scrum-agile.png) - -3. Choose the calendar icon to select the start date, and then the end date of the sprint. - - > [!div class="mx-imgBorder"] - > ![Edit iteration dialog, Set dates](media/define-sprints/edit-iteration-set-sprint-dates.png) - -4. Choose **Save and close**. You'll see the date listed. - - > [!div class="mx-imgBorder"] - > ![Boards>Sprints>Sprint dates set ](media/define-sprints/sprint-dates-set-scrum-agile.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -1. From your web browser, open your team's sprint backlog. (1) Select the team from the project/team selector, choose (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - - > [!div class="mx-imgBorder"] - > ![Open the Boards>Backlogs page](media/assign-items-sprint/open-work-backlogs-standard.png) - - To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/assign-items-sprint/team-selector-backlogs-standard.png) - - The set of sprints selected for your team appears in the left pane. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Define sprints](define-sprints.md). - -1. Choose the sprint you want to plan. - - > [!div class="mx-imgBorder"] - > ![Choose another sprint](media/add-tasks/choose-sprint-standard.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). - -2. Choose the sprint listed under **Current** and then choose **Set dates**. - - Sprint 1 backlog, Set dates - - > [!NOTE] - > If you don't see any sprints listed or the **Set dates** link, then no sprints have been selected for the team context you've selected. To select sprints for the team context, see [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). To switch team context, see [Switch project or team focus](../../project/navigation/go-to-project-repo.md). - -3. Choose the calendar icon to select the start date, and then the end date of the sprint. - - > [!div class="mx-imgBorder"] - > ![Edit iteration dialog, Set dates](media/define-sprints/edit-iteration-set-sprint-dates.png) - - -::: moniker-end - That's it! You can now start [planning your first sprint](assign-work-sprint.md). If you have several teams, more complex release and sprint cadences to schedule, or want to create child iterations, then read further. You define these items through the settings context for the project. See [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). @@ -133,13 +70,12 @@ If you have several teams, more complex release and sprint cadences to schedule, > [!NOTE] > **Terminology note:** Your set of Agile tools uses the Iteration Path field to track sprints and releases. When you define sprints, you define the picklist of values available for the [Iteration Path](../../organizations/settings/set-area-paths.md) field. You use iterations to group work into sprints, milestones, or releases in which they'll be worked on or shipped. - ## Schedule new sprints for different teams and release cadences > [!NOTE] -> Your sprint backlog and taskboard are designed to support your Scrum processes. In addition, you have access to product and portfolio backlogs and Kanban boards. For an overview of the features supported on each backlog and board, see [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md). +> Your sprint backlog and taskboard are designed to support your Scrum processes. In addition, you have access to product and portfolio backlogs and boards. For an overview of the features supported on each backlog and board, see [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md). Your project comes with several sprints predefined. However, they aren't associated with any dates. For Scrum and sprint planning, assign start and end dates for your team's sprints. @@ -151,24 +87,12 @@ Each sprint that you select for your team provides access to a [sprint backlog, For example, by selecting Sprints 1 through 6, the Fabrikam Fiber team gets access to six sprint backlogs. They also get access to capacity planning tools and a taskboard for each sprint. - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ![Selected sprints for a team](media/define-sprints/selected-team-iterations-agile.png) - - ::: moniker-end - -::: moniker range="tfs-2018" - -![Selected sprints for a team](media/define-sprints/selected-team-iterations-vsts.png) - - -::: moniker-end - - ## Next step > [!div class="nextstepaction"] diff --git a/docs/boards/sprints/end-sprint-activities.md b/docs/boards/sprints/end-sprint-activities.md index 54f2a602b80..2f02b2864da 100644 --- a/docs/boards/sprints/end-sprint-activities.md +++ b/docs/boards/sprints/end-sprint-activities.md @@ -59,7 +59,7 @@ The following suggestions walk through the main end-of-sprint activities teams s - **Determine how to handle Remaining Work for completed tasks.** If tasks are complete, then having a non-zero value for **Remaining Work** doesn't make a lot of sense. Teams should decide how they want to handle these cases and consider setting the value of **Remaining Work** to zero for completed tasks. - + ### Review sprint backlog for incomplete work @@ -67,7 +67,7 @@ To determine incomplete work, review the Sprint backlog for work that is still i :::image type="content" source="media/end-sprint/review-sprint-backlog.png" alt-text="Screenshot of Sprint Backlog at end of sprint."::: - + ### Reassign incomplete user stories and tasks to future sprint diff --git a/docs/boards/sprints/forecast.md b/docs/boards/sprints/forecast.md index 3a3b15b4a11..2b1dd1dd3c9 100644 --- a/docs/boards/sprints/forecast.md +++ b/docs/boards/sprints/forecast.md @@ -30,21 +30,22 @@ Use this article to learn: ::: moniker range="azure-devops" -* Connect to a project. If you don't have a project yet, [create one](../get-started/sign-up-invite-teammates.md). -* You must be added to a project as a member of the **Contributors** security group. If you're not on a project or team, [get added now](../../organizations/security/add-users-team-project.md). -* You must be granted **Basic** access or higher to use the forecast feature. For more information, see [About access levels](../../organizations/security/access-levels.md). +| Category | Requirements | +|--------------|-------------| +| **Project membership** | [Project member](../../organizations/projects/create-project.md). | +| **Permissions** | Member of the **Contributors** security group. | +| **Access levels** | At least [**Basic** access](../../organizations/security/access-levels.md). | > [!NOTE] > Users with **Stakeholder** access for a public project have full access to backlog and board features just like users with **Basic** access. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). - ::: moniker-end ::: moniker range="< azure-devops" -* Connect to a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -* You must be added to a project as a member of the **Contributors** security group. If you're not on a project or team, [get added now](../../organizations/security/add-users-team-project.md). -* You must be granted **Basic** access or higher to add or modify work items. For more information, see [About access levels](../../organizations/security/access-levels.md). +* **Project membership**: Member of a [project](../../organizations/projects/create-project.md). +* **Permissions**: Member of the **Contributors** security group. +* **Access levels**: At least [**Basic** access](../../organizations/security/access-levels.md). ::: moniker-end @@ -61,13 +62,12 @@ Here's what you need to have in place before you attempt to forecast your team's * Update the status of backlog items once work starts and when completed. Only backlog items whose State maps to a state category of *Proposed* or *In Progress* show up on the velocity chart. (For more information, see [Workflow states and state categories](../work-items/workflow-and-state-categories.md)). **Recommended:** -* Define and size backlog items to [minimize variability](../../report/dashboards/team-velocity.md#minimize-variability). +* Define and size backlog items to [minimize variability](../../report/dashboards/team-velocity.md). * Determine how your team wants to [treat bugs](../../organizations/settings/show-bugs-on-backlog.md). If your team chooses to treat bugs like requirements, bugs appear on the backlog and be counted within the Velocity chart and forecasting. * [Set your team's area path](../../organizations/settings/set-area-paths.md). The forecast tool forecasts those items based on your team's default settings. These settings can specify to include items in area paths under the team's default or exclude them. -* Don't create a hierarchy of backlog items and bugs. The display of the leaf node, the last node in a same-category hierarchy, may only appear on Kanban boards, sprint backlogs, and Taskboards. For more information, see [Fix reordering and nesting issues, How backlogs and boards display hierarchical (nested) items](../backlogs/resolve-backlog-reorder-issues.md#leaf-nodes).
Instead of nesting requirements, bugs, and tasks, maintain a flat list—only creating parent-child links one level deep between different-category items. Use [Features to group requirements or user stories](../backlogs/organize-backlog.md). You can quickly map stories to features. The map creates parent-child links in the background. +* Don't create a hierarchy of backlog items and bugs. The display of the leaf node, the last node in a same-category hierarchy, may only appear on boards, sprint backlogs, and Taskboards. For more information, see [Fix reordering and nesting issues, How backlogs and boards display hierarchical (nested) items](../backlogs/resolve-backlog-reorder-issues.md).
Instead of nesting requirements, bugs, and tasks, maintain a flat list—only creating parent-child links one level deep between different-category items. Use [Features to group requirements or user stories](../backlogs/organize-backlog.md). You can quickly map stories to features. The map creates parent-child links in the background. * At the end of the sprint, update the status of those backlog items that the team has fully completed. Incomplete items should be moved back to the product backlog and considered in a future sprint planning meeting. - > [!NOTE] > If you work with several teams, and each team wants to work with their own backlog, velocity chart, and forecast tool, you can [create additional teams](../../organizations/settings/add-teams.md). Each team then gets access to their own set of Agile tools. Each Agile tool filters work items to only include those whose assigned area paths and iteration paths meet those set for the team. @@ -79,10 +79,8 @@ Use the forecast tool to get an idea of how many items you can complete within a To forecast your product backlog, complete the following actions. - ::: moniker range=">= azure-devops-2020" - 1. (1) Check that you've selected the right project, (2) choose **Boards>Backlogs**, and then (3) select the correct team from the team selector menu. > [!div class="mx-imgBorder"] @@ -122,79 +120,6 @@ To forecast your product backlog, complete the following actions. ::: moniker-end - -::: moniker range="azure-devops-2019" - -1. From your web browser, open your product backlog. (1) Check that you've selected the right project, (2) choose **Boards>Backlogs**, and then (3) select the correct team from the team selector menu. - - ![Open Work, Backlogs, for a team](media/assign-items-sprint/open-work-backlogs-agile.png) - - To choose another team, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all team backlogs** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/assign-items-sprint/team-selector-backlogs-agile.png) - -1. Check that you have selected **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI) as the backlog level. You can only forecast a product backlog. You can't forecast a portfolio backlog such as Features or Epics. - - > [!div class="mx-imgBorder"] - > ![Choose product backlog level, Backlog items, Stories, or Requirements](media/assign-items-sprint/select-product-backlog-agile.png) - -2. (Optional) To choose which columns should display and in what order, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select **Column options**. You may want to add the Iteration Path to the set of columns that appear on your backlog. For more information, see [Change column options](../backlogs/set-column-options.md). - - > [!div class="mx-imgBorder"] - > ![Open Column Options](media/assign-items-sprint/open-work-backlogs-column-options-agile.png) - -3. Choose the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: view options icon and slide **Forecasting** to **On**. To keep things simple, turn the **Mapping** and **Planning** panes **Off**. - - > [!div class="mx-imgBorder"] - > ![Boards>Backlog, view options menu, Forecast on](media/forecast/turn-forecasting-on-agile.png) - - Set **In Progress Items** to **Off** to hide those items that won't be counted in the forecast. The forecast tool ignores Scrum items set to *Committed* or *Done* and Agile and CMMI items set to *Active*, *Resolved*, or *Completed*. - -4. Enter your team's predicted velocity. If the **Forecasting** bar doesn't appear. - - > [!div class="mx-imgBorder"] - > ![Boards>Backlog, Set Forecast velocity](media/forecast/set-forecast-velocity.png) - - > [!TIP] - > If your team has been working for several sprints, you can gain an idea of your team's velocity from the [Velocity widget](../../report/dashboards/team-velocity.md). - - The tool draws lines for each future sprint selected by the team. The Forecast lines show how much work your team can complete in future sprints. Typically, items above the first line are already in progress for the current sprint. Items that fall between the first and second forecast lines indicate what can be completed in the named sprint. - -::: moniker-end - -::: moniker range="tfs-2018" - -To forecast your product backlog, complete the following actions. - -1. From your web browser, open your team's product backlog. (1) Select the team from the project/team selector, choose (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - - > [!div class="mx-imgBorder"] - > ![Open the Boards>Backlogs page](media/assign-items-sprint/open-work-backlogs-standard.png) - - You can only forecast the product backlog of Stories, Backlog items, or Requirements. - - To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/assign-items-sprint/team-selector-backlogs-standard.png) - - > [!NOTE] - > If you work with several teams, and each team wants to work with their own backlog, velocity chart, and forecast tool, you can [create additional teams](../../organizations/settings/add-teams.md). Each team then gets access to their own set of Agile tools. Each Agile tool filters work items to only include those whose assigned area paths and iteration paths meet those set for the team. - -1. (Optional) To choose which columns should display and in what order, choose **Column options**. You may want to add the Iteration Path to the set of columns that appear on your backlog. For more information, see [Change column options](../backlogs/set-column-options.md). - -2. Set **Forecast** to **On** and enter your team's predicted velocity. If the Forecasting bar doesn't appear, set **Parents** to **Hide**. - - ![Web portal, Boards>Backlog, Forecast On](media/forecast-tool-settings.png) - -3. Set **In progress** items to **Hide** to hide those items that won't be counted in the forecast. The forecast tool ignores Scrum items set to Committed or Done and Agile and CMMI items set to Active, Resolved, or Completed. - - The tool draws lines for each future sprint selected by the team. The Forecast lines show how much work your team can complete in future sprints. Typically, items above the first line are already in progress for the current sprint. Items that fall between the first and second forecast lines indicate what can be completed in the named sprint. - -::: moniker-end - - ## Review the forecast results * Check the results manually to understand discrepancies in what you expect and what the forecast tool displays. @@ -233,6 +158,3 @@ You can then assess the delta between the current team's velocity and the requir * Use the [taskboard](task-board.md) to track work during your sprint * Monitor the [sprint burndown chart](task-board.md) to determine if your team is on track to complete the sprint plan - - - diff --git a/docs/boards/sprints/media/add-tasks/open-sprint-backlog-s155-co.png b/docs/boards/sprints/media/add-tasks/open-sprint-backlog-s155-co.png index 2930c3968a8..060fe3542c6 100644 Binary files a/docs/boards/sprints/media/add-tasks/open-sprint-backlog-s155-co.png and b/docs/boards/sprints/media/add-tasks/open-sprint-backlog-s155-co.png differ diff --git a/docs/boards/sprints/media/add-tasks/open-sprints-backlog-agile.png b/docs/boards/sprints/media/add-tasks/open-sprints-backlog-agile.png index 68fade8dfe5..1cad67caaad 100644 Binary files a/docs/boards/sprints/media/add-tasks/open-sprints-backlog-agile.png and b/docs/boards/sprints/media/add-tasks/open-sprints-backlog-agile.png differ diff --git a/docs/boards/sprints/media/add-tasks/select-specific-sprint-agile.png b/docs/boards/sprints/media/add-tasks/select-specific-sprint-agile.png index fcc872d5c45..25a00f95fc0 100644 Binary files a/docs/boards/sprints/media/add-tasks/select-specific-sprint-agile.png and b/docs/boards/sprints/media/add-tasks/select-specific-sprint-agile.png differ diff --git a/docs/boards/sprints/media/add-tasks/team-selector-sprints-agile.png b/docs/boards/sprints/media/add-tasks/team-selector-sprints-agile.png index d87175c1397..52fce859ec9 100644 Binary files a/docs/boards/sprints/media/add-tasks/team-selector-sprints-agile.png and b/docs/boards/sprints/media/add-tasks/team-selector-sprints-agile.png differ diff --git a/docs/boards/sprints/media/assign-items-sprint/backlog-team-selector-s155.png b/docs/boards/sprints/media/assign-items-sprint/backlog-team-selector-s155.png index a4cf411c866..bb71c3c1bfe 100644 Binary files a/docs/boards/sprints/media/assign-items-sprint/backlog-team-selector-s155.png and b/docs/boards/sprints/media/assign-items-sprint/backlog-team-selector-s155.png differ diff --git a/docs/boards/sprints/media/assign-items-sprint/open-column-options-s155.png b/docs/boards/sprints/media/assign-items-sprint/open-column-options-s155.png index c4c64a72dff..caa737897fc 100644 Binary files a/docs/boards/sprints/media/assign-items-sprint/open-column-options-s155.png and b/docs/boards/sprints/media/assign-items-sprint/open-column-options-s155.png differ diff --git a/docs/boards/sprints/media/assign-items-sprint/open-work-backlogs-agile.png b/docs/boards/sprints/media/assign-items-sprint/open-work-backlogs-agile.png index 4a794d117c0..438bb846776 100644 Binary files a/docs/boards/sprints/media/assign-items-sprint/open-work-backlogs-agile.png and b/docs/boards/sprints/media/assign-items-sprint/open-work-backlogs-agile.png differ diff --git a/docs/boards/sprints/media/assign-items-sprint/select-product-backlog-agile-s155.png b/docs/boards/sprints/media/assign-items-sprint/select-product-backlog-agile-s155.png index bb6fac0793e..8c11ff3fa7a 100644 Binary files a/docs/boards/sprints/media/assign-items-sprint/select-product-backlog-agile-s155.png and b/docs/boards/sprints/media/assign-items-sprint/select-product-backlog-agile-s155.png differ diff --git a/docs/boards/sprints/media/burndown/analytics-burndown-remaining-work.png b/docs/boards/sprints/media/burndown/analytics-burndown-remaining-work.png index 56681747ea4..679ec42a273 100644 Binary files a/docs/boards/sprints/media/burndown/analytics-burndown-remaining-work.png and b/docs/boards/sprints/media/burndown/analytics-burndown-remaining-work.png differ diff --git a/docs/boards/sprints/media/capacity/add-team-members.png b/docs/boards/sprints/media/capacity/add-team-members.png index f4c21b23e0a..1ad7d91f184 100644 Binary files a/docs/boards/sprints/media/capacity/add-team-members.png and b/docs/boards/sprints/media/capacity/add-team-members.png differ diff --git a/docs/boards/sprints/media/capacity/open-capacity-agile.png b/docs/boards/sprints/media/capacity/open-capacity-agile.png index c2f0810383d..8988b83fc10 100644 Binary files a/docs/boards/sprints/media/capacity/open-capacity-agile.png and b/docs/boards/sprints/media/capacity/open-capacity-agile.png differ diff --git a/docs/boards/sprints/scrum-key-concepts.md b/docs/boards/sprints/scrum-key-concepts.md index 5191c961705..6b593a43aa3 100644 --- a/docs/boards/sprints/scrum-key-concepts.md +++ b/docs/boards/sprints/scrum-key-concepts.md @@ -15,10 +15,8 @@ ms.date: 01/23/2023 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - This article provides a short dictionary of terms and available tools used in tracking work using Sprints and Scrum methods. Other resources to review are [Agile glossary](../work-items/agile-glossary.md) and [Project management and navigation glossary](../../project/navigation/glossary.md). - [!INCLUDE [temp](../../includes/glossary-terms/agile-tools.md)] [!INCLUDE [temp](../../includes/glossary-terms/bugs.md)] @@ -38,14 +36,10 @@ Capacity correlates to actual task time, either hours or days, that an individua By setting team capacity, the team knows exactly the total number of work hours or days the team has for each sprint. With this tool, you set individual team member capacity and days off. Setting capacity for each team member working during a sprint causes the capacity bar for that individual to appear. Learn more: [Set sprint capacity](set-capacity.md). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::image type="content" source="media/capacity/set-capacity-web-team.png" alt-text="Screenshot of team capacity page."::: ::: moniker-end -::: moniker range="tfs-2018" -:::image type="content" source="media/team-capacity-planning-tool.png" alt-text="Screenshot of team capacity page, TFS 2018."::: -::: moniker-end - ## Capacity bars With capacity bars, you can quickly see who is over, at, or under capacity. Capacity bars update with each of these activities: @@ -55,17 +49,15 @@ With capacity bars, you can quickly see who is over, at, or under capacity. Capa |Capacity colors |Capacity bars | |----------------|--------------| -|![Screenshot of capacity colors.](media/capacity-planning-tool-color-chart.png) | ![Screeshot of Capacity bars.](media/ALM_DS_CapacityBars_S.png) | +|![Screenshot of capacity colors.](media/capacity-planning-tool-color-chart.png) | ![Screenshot of Capacity bars.](media/ALM_DS_CapacityBars_S.png) | For more information, see [Adjust work to fit sprint capacity](adjust-work.md). - ## Daily scrum meetings Daily Scrum meetings help teams stay focused on what they need to do to maximize their ability to meet their sprint commitments. The team's Scrum Master should enforce the structure of the meeting and ensure that it starts on time and finishes in 15 minutes or less. Learn more: [Scrum best practices, Daily scrum meeting](best-practices-scrum.md#daily-scrum-meetings). - - + ## Forecast @@ -75,7 +67,6 @@ As shown here, a velocity of 20 indicates that it will take five sprints to comp > [!div class="mx-imgBorder"] > ![Screenshot of team backlog, Forecast view.](media/forecast-s125.png) - [!INCLUDE [temp](../../includes/glossary-terms/iterations.md)] [!INCLUDE [temp](../../includes/glossary-terms/product-backlog.md)] @@ -84,7 +75,7 @@ As shown here, a velocity of 20 indicates that it will take five sprints to comp ## Product owner role -The role of product owners is to act as the interface between customers and the team. A product owner can reduce the need for detailed specifications. They reduce the need by being more responsive to the team's questions about implementation details. Also, they clearly define acceptance criteria within each requirement. Learn more: [Refine your backlog, Role of the product owner](../backlogs/best-practices-product-backlog.md#product-owner-role). +The role of product owners is to act as the interface between customers and the team. A product owner can reduce the need for detailed specifications. They reduce the need by being more responsive to the team's questions about implementation details. Also, they clearly define acceptance criteria within each requirement. ## Scrum Master role @@ -94,21 +85,16 @@ Scrum Masters help build and maintain healthy teams by employing Scrum processes [!INCLUDE [temp](../../includes/glossary-terms/sprint-backlogs.md)] - + ## Sprint burndown chart The sprint burndown chart reflects the progress made by a team in completing all the work they estimated during their sprint planning meeting. Team's monitor it to mitigate risk and check for scope creep throughout their sprint cycle. The ideal trend line always indicates a steady burndown. The blue area, as shown in the following chart, represents what's actually going on. It shows the buildup of work as team members add tasks and the reduction of work as team members complete those tasks. Learn more: [Monitor sprint burndown](../../report/dashboards/configure-sprint-burndown.md). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::image type="content" source="../../report/dashboards/media/burndown/analytics-burndown-remaining-work-s159.png" alt-text="Screenshot of Sprint burndown chart."::: ::: moniker-end -::: moniker range="tfs-2018" -![Screenshot of Sprint burndown chart, TFS 2018](media/ALM_DS_SprntBD_Chrt_S.png) -::: moniker-end - - ## Sprint goals Sprint goals are used to focus sprint activities. The goal summarizes what the team wants to accomplish by the end of the sprint. Learn more: [Scrum best practices, Set sprint goals](best-practices-scrum.md#set-sprint-goals). @@ -125,7 +111,7 @@ The Sprint review or retrospective meeting occurs at the end of a sprint. This m A task is a type of work item used to track estimated and remaining work. In Scrum, a task is defined to range between four and twelve hours. Defining tasks are essential for monitoring sprint burndown, working with team capacity, and using the [Taskboard](#taskboard). Tasks are linked to their parent product backlog items or user stories. Learn more: [Add tasks to backlog items](add-tasks.md). - + ## Taskboard @@ -148,7 +134,6 @@ Technical debt includes anything the team must do to deploy production quality c ## Triage meetings Triage meetings are used to review and organize the backlog and bugs assigned to a team. Other details, such as estimates, acceptance criteria, and more may be added to the work items. Typically, a product owner runs triage meetings, and team leads, business analysts, and other stakeholders who can speak about specific project risks attend them. -Learn more: [Triage work items](../queries/triage-work-items.md). [!INCLUDE [temp](../../includes/glossary-terms/user-story.md)] @@ -160,22 +145,16 @@ Velocity is a measure of how much work a team can complete based on their sprint For example, in the chart shown below the green bar indicates the total estimated effort (story points) of the user stories completed within each sprint. Blue corresponds to the estimated effort of items not yet completed. Learn more: [View and work with the built-in team velocity chart](../../report/dashboards/team-velocity.md). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::image type="content" source="../../report/dashboards/media/velocity/analytics-velocity-azure-devops.png" alt-text="Screenshot of Velocity."::: ::: moniker-end -::: moniker range="tfs-2018" -![Screenshot of Velocity chart, TFS 2018.](media/velocity-chart.png) -::: moniker-end - - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Along with the built-in Velocity chart, you can add a Velocity widget to your team dashboard. You can configure this widget to sum a count of work items or the sum of effort. Learn more: [Configure the Velocity widget](../../report/dashboards/team-velocity.md). ::: moniker-end Each team is associated with one and only one velocity chart. Velocity varies depending on team capacity, sprint over sprint. However, over time, the velocity should indicate a reliable average that can be used to forecast the full backlog. By minimizing the variability of backlog item size—effort or story points—you gain more reliable velocity metrics. Learn more: [Add tasks to backlog items](add-tasks.md). - ## Related articles - [About Sprints and Scrum](scrum-overview.md) @@ -184,4 +163,3 @@ Each team is associated with one and only one velocity chart. Velocity varies de - [Project management and navigation glossary](../../project/navigation/glossary.md) - [What is Scrum?](/devops/plan/what-is-scrum) - diff --git a/docs/boards/sprints/scrum-overview.md b/docs/boards/sprints/scrum-overview.md index 0024d845851..a80aedf24c4 100644 --- a/docs/boards/sprints/scrum-overview.md +++ b/docs/boards/sprints/scrum-overview.md @@ -8,7 +8,7 @@ ms.author: chcomley author: chcomley ms.topic: overview monikerRange: '<= azure-devops' -ms.date: 01/23/2023 +ms.date: 09/09/2024 --- # Implement Scrum practices for your team in Azure Boards @@ -17,31 +17,29 @@ ms.date: 01/23/2023 Your Sprints tools include a filtered backlog based on an Iteration Path and a similarly filtered taskboard. These tools are useful for implementing Scrum practices. With Scrum, you can schedule and plan sprints, update your taskboard, and monitor your sprint burndown. -Scrum methods use Iteration Paths, also referred to as sprints, to plan work to be performed by a team within a specific time period and cadence. To get started, several sprints are predefined for your team. If you're new to Scrum, get an overview from [What is Scrum?](/devops/plan/what-is-scrum). - +Scrum methods use Iteration Paths, also referred to as sprints, to plan work to for a team within a specific time period and cadence. To get started, several sprints are predefined for your team. If you're new to Scrum, get an overview from [What is Scrum?](/devops/plan/what-is-scrum). [!INCLUDE [temp](../includes/setup-backlogs-boards.md)] - ## Use Azure Boards to implement Scrum The general sequence of steps for implementing Scrum using Azure Boards is as follows: -### Configure teams and sprints +### 1. Configure teams and sprints 1. [Define project-level Iteration Paths and set dates](../../organizations/settings/set-iteration-paths-sprints.md) 1. (Optional) [Add project-level Area Paths](../../organizations/settings/set-area-paths.md) (Or, add an area path when you configure each team) 1. [Add teams](../../organizations/settings/add-teams.md) -1. [Select team-level Iteration Paths](../../organizations/settings/set-iteration-paths-sprints.md#activate). +1. [Select team-level Iteration Paths](../../organizations/settings/set-iteration-paths-sprints.md#list-team-iterations). -### Create team backlog +### 2. Create team backlog 1. [Create and organize your team backlog](../backlogs/create-your-backlog.md). 1. (Optional) [Forecast your team backlog](forecast.md). -### Implement a sprint +### 3. Implement a sprint -You can quickly assign work items to a sprint by dragging and dropping them from the product backlog to the sprint. +Quickly assign work items to a sprint by dragging and dropping them from the product backlog to the sprint. 1. [Assign backlog items to a sprint](assign-work-sprint.md) 2. [Add tasks to backlog items](add-tasks.md) @@ -56,63 +54,42 @@ You can quickly assign work items to a sprint by dragging and dropping them from 1. [End of sprint activities](end-sprint-activities.md) 2. [Sprint retrospective meetings](best-practices-scrum.md#sprint-retrospective-meetings) - ## Sprint backlogs and Taskboards overview -Sprint backlogs and Taskboards provide a filtered view of work items a team has assigned to a specific iteration path, or sprint. Sprints are defined for a project and then selected by teams. From your backlog, you can map work to an iteration path using drag-and-drop, and then view that work in a separate **sprint backlog**. +Sprint backlogs and Taskboards provide a filtered view of work items a team assigned to a specific iteration path, or sprint. Sprints are defined for a project and then selected by teams. From your backlog, you can map work to an iteration path using drag-and-drop, and then view that work in a separate **sprint backlog**. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!div class="mx-imgBorder"] > ![Screenshot of Web portal, Open Boards, Sprints, Backlog.](../work-items/media/view-add/view-sprint-backlogs.png) ::: moniker-end - -::: moniker range="tfs-2018" -> [!div class="mx-imgBorder"] -> [Screenshot of Web portal, choose Boards, Backlogs, Sprint.](../work-items/media/view-add/view-sprint-backlog.png) - -::: moniker-end - - ## How selected sprints show up on the backlog Each sprint that you select for your team provides access to a sprint backlog, taskboard, and other Agile tools for planning and tracking work. - - -::: moniker range=">= azure-devops-2019" + -1. You can gain an overview of your sprint planning by turning on the **Planning** view option. From the product backlog or any sprint backlog, choose the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: view options icon and select **Planning**. +1. Gain an overview of your sprint planning by turning on the **Planning** view option. From the product backlog or any sprint backlog, choose the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: view options icon and select **Planning**. > [!div class="mx-imgBorder"] > ![Screenshot of Sprints backlogs Planning pane.](media/overview/sprints-new-nav.png) > [!NOTE] - > The Planning pane will only show the current sprint and the next 10 future sprints in the list, even if more have been selected for the team. + > The Planning pane only shows the current sprint and the next 10 future sprints in the list, even if more have been selected for the team. The set of sprints selected for your team appears. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Define sprints](define-sprints.md). -1. To select a sprint backlog, you can choose one of the sprint links from the **Planning** pane, or from a Sprint backlog, choose a sprint from the sprint selector. +2. To select a sprint backlog, you can choose one of the sprint links from the **Planning** pane, or from a Sprint backlog, choose a sprint from the sprint selector. > [!div class="mx-imgBorder"] > ![Screenshot showing how to select a sprint. ](media/overview/select-a-sprint-new-nav.png) -::: moniker-end - -::: moniker range="tfs-2018" - -For example, by selecting Sprints 1 through 6, the Fabrikam Fiber team gets access to six sprint backlogs. They also get access to capacity planning tools and a taskboard for each sprint. - -![Screenshot showing how selected iterations show up on Web portal, sprint backlogs.](media/define-sprints/selected-team-iterations-vsts.png) - -::: moniker-end - ## Track team capacity -Once you've [defined iteration (sprint) paths and configured team iterations](../../organizations/settings/set-iteration-paths-sprints.md), you can start using the following tools to plan your sprint. +Once you [define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md), you can start using the following tools to plan your sprint. -At the start of each sprint, you'll want to plan the work that your team can commit to. The three Agile tools that support this work include the sprint backlog, capacity planning, and capacity bars. The sprint backlog contains a filtered subset of backlog items whose iteration path corresponds to the current sprint. +At the start of each sprint, plan the work that your team can commit to. The three Agile tools that support this work include the sprint backlog, capacity planning, and capacity bars. The sprint backlog contains a filtered subset of backlog items whose iteration path corresponds to the current sprint. ### Team capacity planning tool @@ -120,14 +97,14 @@ By setting team capacity, the team knows exactly the total number of work hours Setting capacity for each team member working during a sprint causes the capacity bar for that individual to appear. -You [set recurring days off](../../organizations/settings/set-working-days.md), such as weekends, through team settings. +For more information, see [Set capacity for the team and team members](set-capacity.md#set-capacity-for-the-team-and-team-members). ![Screenshot of Team capacity planning tool.](media/team-capacity-planning-tool.png) ### Individual and team capacity bars With capacity bars, you can quickly see who is over, at, or under capacity. Capacity bars update with each of these activities: -- Tasks are assigned with non-zero remaining work +- Tasks are assigned with nonzero remaining work - Change in remaining work - Date change within the sprint cycle. Individual and team capacity always reflects their capacity from the current day until the end of the sprint. @@ -137,7 +114,6 @@ Here's how to interpret the capacity colors: ![Screenshot of capacity board that help distinguish capacity.](media/capacity-planning-tool-color-chart.png) - ## Update tasks and monitor burndown During a sprint, use the taskboard and sprint burndown chart to track their progress. Your sprint burndown chart provides you with an at-a-glance visual to determine if your team is on track to meet their sprint plan. @@ -145,7 +121,7 @@ During a sprint, use the taskboard and sprint burndown chart to track their prog :::row::: :::column span="1"::: **Taskboard** - Your [Taskboard](task-board.md) provides an interactive progress board for work required to complete the sprint backlog. During your sprint, you'll want to update the status of tasks and the remaining work for each task. + Your [Taskboard](task-board.md) provides an interactive progress board for work required to complete the sprint backlog. During your sprint, update the status of tasks and the remaining work for each task. Updating tasks daily or several times a week yields a smoother burndown chart. :::column-end::: @@ -157,7 +133,7 @@ During a sprint, use the taskboard and sprint burndown chart to track their prog :::column span="1"::: **Sprint burndown chart** - You use the [sprint burndown chart](../../report/dashboards/configure-sprint-burndown.md) to mitigate risk and check for scope creep throughout your sprint cycle. The burndown chart reflects the progress made by your team in completing all the work they estimated during their sprint planning meeting. + Use the [sprint burndown chart](../../report/dashboards/configure-sprint-burndown.md) to mitigate risk and check for scope creep throughout your sprint cycle. The burndown chart reflects the progress made by your team in completing all the work they estimated during their sprint planning meeting. The ideal trend line always indicates a steady burndown. The blue area, however, represents what's actually going on. It shows the buildup of work as team members add tasks and the reduction of work as team members complete those tasks. :::column-end::: @@ -166,7 +142,6 @@ During a sprint, use the taskboard and sprint burndown chart to track their prog :::column-end::: :::row-end::: - ## Use velocity and forecast tools to predict work effort @@ -183,7 +158,7 @@ After several sprints, use the [Velocity chart](../../report/dashboards/team-vel :::column span="1"::: **Velocity chart** Each team is associated with one and only one velocity chart. The green bar within the chart indicates the total estimated effort (story points or size) of backlog items (user stories or requirements) completed within the sprint. (Blue corresponds to the estimated effort of items not yet completed.) - Velocity will vary depending on team capacity, sprint over sprint. However, over time, the velocity should indicate a reliable average that can be used to forecast the full backlog. + Velocity varies depending on team capacity, sprint over sprint. However, over time, the velocity should indicate a reliable average that can be used to forecast the full backlog. By minimizing the variability of backlog item size—effort or story points—you gain more reliable velocity metrics. :::column-end::: :::column span="1"::: @@ -194,8 +169,8 @@ After several sprints, use the [Velocity chart](../../report/dashboards/team-vel :::row::: :::column span="1"::: **Forecast tool** - You can use the forecast tool to get an idea of how many and which items you can complete within a sprint. - By plugging in a velocity, you can see which items are within scope for the set of sprints the team has selected. As shown here, a velocity of 15 indicates that it will take three sprints to complete the work shown.* + Use the forecast tool to get an idea of how many and which items you can complete within a sprint. + By plugging in a velocity, you can see which items are within scope for the set of sprints the team selected. As shown here, a velocity of 15 indicates that it takes three sprints to complete the work shown.* :::column-end::: :::column span="1"::: ![Screenshot of Forecast tool.](media/forecast-tool.png) @@ -203,21 +178,21 @@ After several sprints, use the [Velocity chart](../../report/dashboards/team-vel :::row-end::: --- - + ## Query sprint scope changes -There isn't a sprint scope change chart or widget. However, you can query for work items added to a sprint or moved out of a sprint after the start of the sprint. Use the steps provided next. +There isn't a sprint scope change chart or widget. But, you can query for work items added to a sprint or moved out of a sprint after the start of the sprint. Use the steps provided next. ## List work items added after the start of the sprint -1. [Open the velocity chart](../../report/dashboards/team-velocity.md) for the team and choose the **Planned** bar for the sprint of interest. You can use the Planned bar for a velocity chart widget or the team backlog velocity chart. +1. [Open the velocity chart](../../report/dashboards/team-velocity.md) for the team and choose the **Planned** bar for the sprint of interest. Use the Planned bar for a velocity chart widget or the team backlog velocity chart. :::image type="content" source="media/overview/velocity-chart.png" alt-text="Screenshot of team velocity chart, choose a planned work bar."::: 2. The Query Results page opens with a list of work items defined for the sprint at the start of the sprint, the first day of the sprint. This list is an itemized list of work item IDs. -3. Choose the Editor page to edit the query. +3. Choose the **Editor** page to edit the query. 4. List the items that were added to the sprint after the sprint's start. To do so, change the query to add and change the following clauses: @@ -230,29 +205,30 @@ There isn't a sprint scope change chart or widget. However, you can query for wo :::image type="content" source="media/overview/query-for-added-work-items-to-sprint.png" alt-text="Screenshot of Query Editor, Work Items added to a sprint after the start of the sprint."::: -5. Add **Created Date** as a column option, and sort by that field. You can then view the existing work items that were added to the sprint and what newly created work items were added. +5. Add **Created Date** as a column option, and sort by that field. View the existing work items that were added to the sprint and what newly created work items were added. + +For more information, see [Query fields, operators, and macros in Azure Boards](../queries/query-operators-variables.md). ## List work items moved out of the sprint -1. [Open the velocity chart](../../report/dashboards/team-velocity.md) for the team and choose the **Planned** bar for the sprint of interest. You can use the Planned bar for a velocity chart widget or the team backlog velocity chart. +1. [Open the velocity chart](../../report/dashboards/team-velocity.md) for the team and choose the **Planned** bar for the sprint of interest. Use the Planned bar for a velocity chart widget or the team backlog velocity chart. :::image type="content" source="media/overview/velocity-chart.png" alt-text="Screenshot of team velocity chart, choose a planned work bar, second instance."::: 2. The Query Results page opens with a work item list defined for the sprint at the sprint's start, the first day of the sprint. This list is an itemized list of work item IDs. -3. Choose the Editor page to edit the query. +3. Choose the **Editor** page to edit the query. 4. List the items that were moved out of the sprint after the sprint's start. To do so, change the query to add and change the following clauses: - - Add a clause at the top to specify the Work Item Types of interest - - Add the Iteration Path for the sprint of interest, specify **Not Under** operator + - Add a clause at the top to specify the Work Item Types of interest. + - Add the Iteration Path for the sprint of interest and specify **Not Under** operator. - Add the Area Path for the team. The updated query should look similar to the following image. :::image type="content" source="media/overview/query-for-work-items-moved-out-of-sprint.png" alt-text="Screenshot of Query Editor, Work Items moved out of a sprint"::: - For other options to determine changes to the sprint scope, see [Query by date or current iteration, List work items moved out of a sprint](../queries/query-by-date-or-current-iteration.md#list-work-items-moved-out-sprint). ## Next step @@ -264,10 +240,8 @@ For other options to determine changes to the sprint scope, see [Query by date o If you work with several teams, and each team wants their own backlog view, you can [create more teams](../../organizations/settings/add-teams.md). Each team then gets access to their own set of Agile tools. Each Agile tool filters work items to only include those assigned values under the team's default area path and iteration path. -- [Scrum concepts](scrum-key-concepts.md) -- [End of sprint activities](end-sprint-activities.md) -- [Web portal navigation](../../project/navigation/index.md) -- [Backlogs, portfolios, and Agile project management](../backlogs/backlogs-overview.md) -- [About work items](../work-items/about-work-items.md) -- [What is Scrum?](/devops/plan/what-is-scrum) -- [What is Agile development?](/devops/plan/what-is-agile-development) +- [Learn Scrum concepts](scrum-key-concepts.md) +- [Complete end of sprint activities](end-sprint-activities.md) +- [Navigate the web portal](../../project/navigation/index.md) +- [Manage backlogs, portfolios, and Agile projects](../backlogs/backlogs-overview.md) +- [Understand work items](../work-items/about-work-items.md) diff --git a/docs/boards/sprints/set-capacity.md b/docs/boards/sprints/set-capacity.md index 296a9c5df48..6012019366e 100644 --- a/docs/boards/sprints/set-capacity.md +++ b/docs/boards/sprints/set-capacity.md @@ -1,7 +1,7 @@ --- title: Set the team sprint capacity in Azure Boards titleSuffix: Azure Boards -description: Learn how to determine team capacity, adjust work to fit team capacity, and set capacity for a sprint in Azure Boards. +description: In this tutorial, determine team capacity, adjust work to fit team capacity, and set capacity for a sprint in Azure Boards. ms.service: azure-devops-boards ms.custom: boards-sprints ms.assetid: @@ -9,10 +9,10 @@ ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 10/14/2024 +#customer intent: As a team member, I want to understand how to set capacity for a sprint and how to use capacity to track progress durning a sprint. --- - # 3. Determine and set sprint capacity in Azure Boards @@ -21,25 +21,28 @@ ms.date: 04/01/2022 -As a next step, you'll want to determine your team's actual capacity. While velocity correlates to how your team estimates requirements, capacity correlates to actual task time. Time is calculated in either hours or days. Capacity takes into consideration the variation in work hours by team members. It also considers holidays, vacation days, and non-working days. +While velocity correlates to how your team estimates requirements, *capacity* correlates to actual task time. Time is calculated in either hours or days. Capacity takes into consideration the variation in work hours by team members. It also considers holidays, vacation days, and nonworking days. + +Because days off and time available for each team member might vary from sprint to sprint, set capacity for each sprint. The capacity tool helps you make sure your team isn't overcommitted or undercommitted for the sprint. As you work day-to-day, you see if your team is on track. -Because days off and time available for each team member may vary from sprint to sprint, set capacity for each sprint. The capacity tool helps you make sure your team isn't over or undercommitted for the sprint. Also, as you work day-to-day, you'll see if your team is on track. +In this article, learn how to do the following tasks. -> [!div class="checklist"] -> * Set team capacity for a sprint -> * Copy capacity from the previous sprint to the current sprint -> * Track capacity when performing multiple activities -> * Add or remove user accounts from capacity planning for a sprint -> * Track capacity when working on more than one team +> [!div class="checklist"] +> - Set team capacity for a sprint +> - Copy capacity from the previous sprint to the current sprint +> - Track capacity when performing multiple activities +> - Add or remove user accounts from capacity planning for a sprint +> - Track capacity when working on more than one team -If you haven't set up sprints yet for your team, see the [Manage sprint timelines while working in Scrum](define-sprints.md) article. +To set up sprints yet for your team, see [Manage sprint timelines](define-sprints.md). ## Prerequisites -* Connect to a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -* You must be added to a project as a member of the **Contributors** or **Project Administrators** security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To view or set capacity, you must be granted **Basic** access or higher. Users with **Stakeholder** access can't view or set capacity. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -* To set capacity, you must be a member of the team. For more information, see [Add users to a project or team](../../organizations/security/add-users-team-project.md#add-users-to-a-team). +| Category | Requirements | +|----------------------|----------------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Permissions** | - To view capacity: Be a member of the [**Contributors**](../../organizations/security/add-users-team-project.md) security group in your project.
- To edit capacity: Be a member of the [**Project Administrators**](../../organizations/security/change-project-level-permissions.md) security group or a [**Team Administrator**](../../organizations/settings/add-team-administrator.md) of the team. | +| **Access levels** | To view or set capacity: At least **[Basic](../../organizations/security/access-levels.md)**[ access](../../organizations/security/access-levels.md). Users with **Stakeholder** access can't view or set capacity. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). | @@ -47,216 +50,123 @@ If you haven't set up sprints yet for your team, see the [Manage sprint timeline ::: moniker range="azure-devops" -The values displayed for **Activity** (Agile, Basic, or Scrum) or **Discipline** (CMMI) reflect a union of all values defined for the [Activity or Discipline](../queries/query-numeric.md#fields-used-to-estimate-and-track-work) fields in all projects within the organization. +The values displayed for **Activity** (Agile, Basic, or Scrum) or **Discipline** (Capability Maturity Model Integration (CMMI)) reflect a union of all values defined for the [Activity or Discipline](../queries/query-numeric.md#fields-used-to-estimate-and-track-work) fields in all projects within the organization. -To change the **Activity** or **Discipline** menu selections, see [Add and manage fields](../../organizations/settings/work/customize-process-field.md). +To change the **Activity** or **Discipline** menu selections, see [Add and manage fields](../../organizations/settings/work/customize-process-field.md). ::: moniker-end ::: moniker range="< azure-devops" -The values displayed for **Activity** (Agile, Basic, or Scrum) or **Discipline** (CMMI) reflect a union of all values defined for the [Activity or Discipline](../queries/query-numeric.md#fields-used-to-estimate-and-track-work) fields in all projects within the project collection. Or, if your project has been customized, with the field assigned to [`type="Activity" within the ProcessConfiguration file`](../../reference/xml/process-configuration-xml-element.md#assign-agile-tool-fields). +The values displayed for **Activity** (Agile, Basic, or Scrum) or **Discipline** (Capability Maturity Model Integration (CMMI)) reflect a union of all values defined for the [Activity or Discipline](../queries/query-numeric.md#fields-used-to-estimate-and-track-work) fields in all projects within the project collection. Or, if your project is customized, with the field assigned to [`type="Activity" within the ProcessConfiguration file`](../../reference/xml/process-configuration-xml-element.md#assign-agile-tool-fields). -To change the **Activity** or **Discipline** menu selections, see [Add or modify a field, customize a picklist](../../reference/add-modify-field.md). +To change the **Activity** or **Discipline** menu selections, see [Add or modify a field, customize a picklist](../../reference/add-modify-field.md). ::: moniker-end -## Capacity per day entries - -Most teams specify capacity in hours. You can also specify it in days or any other units your team chooses. For example, 0.5 days would correspond to 4 hours for a typical 8 hour day. Choose the same unit your team uses to estimate and track their time. For example, the entries they'll make to the [Original Estimate or Remaining Work](../queries/query-numeric.md#fields-used-to-estimate-and-track-work) fields. +## Capacity per day entries -## Open a sprint backlog for a team +Most teams specify capacity in hours. You can also specify it in days or any other units your team chooses. For example, 0.5 days would correspond to 4 hours for a typical 8 hour day. Choose the same unit your team uses to estimate and track their time. For example, the entries they make to the **Original Estimate** or **Remaining Work** fields. For more information, see [Fields used to estimate and track work](../queries/query-numeric.md#fields-used-to-estimate-and-track-work). -::: moniker range=">= azure-devops-2019" +## Open a sprint backlog for a team -1. From your web browser, open your product backlog. (1) Check that you've selected the right project, (2) choose **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), choose **Capacity**. +::: moniker range="<=azure-devops" - > [!div class="mx-imgBorder"] - > ![Screenshot showing Open Sprints for a team.](media/capacity/open-capacity-agile.png) +1. From your web browser, open your product backlog. Check that you selected the right project. Select **Boards** > **Sprints**, select the correct team from the team selector menu, and choose **Capacity**. - To choose another team, open the selector and select a different team or choose the **Browse all sprints** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. + :::image type="content" source="media/capacity/open-capacity-agile.png" alt-text="Screenshot showing Open Sprints for a team."::: - > [!div class="mx-imgBorder"] - > ![Screenshot of Choose another team.](media/add-tasks/team-selector-sprints-agile.png) + To choose another team, open the selector and select a different team or choose the **Browse all sprints** option. You can enter a keyword in the search box to filter the list of team backlogs for the project. -1. To choose a different sprint than the one shown, open the sprint selector and choose the sprint you want. + :::image type="content" source="media/add-tasks/team-selector-sprints-agile.png" alt-text="Screenshot of Choose another team."::: - > [!div class="mx-imgBorder"] - > ![Screenshot of Choose another sprint.](media/add-tasks/select-specific-sprint-agile.png) +1. To choose a different sprint than the one shown, open the sprint selector and choose the sprint you want. - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). + :::image type="content" source="media/add-tasks/select-specific-sprint-agile.png" alt-text="Screenshot of Choose another sprint."::: - -::: moniker-end - - -::: moniker range="tfs-2018" - -1. From your web browser, open your team's product backlog. (1) Select the project/team from the project/teams selector, choose (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - - > [!div class="mx-imgBorder"] - > ![Screenshot of Open the Backlogs page, earlier versions](media/assign-items-sprint/open-work-backlogs-standard.png) - - To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Choose another team, earlier versions.](media/assign-items-sprint/team-selector-backlogs-standard.png) - - The set of sprints selected for your team appears in the left pane. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Define sprints](define-sprints.md). - -1. Choose the sprint you want to plan. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Choose another sprint, earlier versions](media/add-tasks/choose-sprint-standard.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). + The system lists only those sprints that are selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). ::: moniker-end -## Set capacity for the team and team members +## Set capacity for the team and team members From the **Capacity** page, you can add team members, enter the team time off, and set capacity and days off for each team member. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -1. If you don't see your team members listed, add them. Choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: action icon and select **Add all team members**. For this feature to work, [team members will have been added to the team](../../organizations/settings/add-teams.md#add-team-members). +1. If you don't see your team members listed, add them. Choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: action icon and select **Add all team members**. For this feature to work, users must be added to the team. - > [!div class="mx-imgBorder"] - > ![Screenshot of Capacity page, Add team members.](media/capacity/add-team-members.png) + :::image type="content" source="media/capacity/add-team-members.png" alt-text="Screenshot of Capacity page, Add team members."::: - > [!NOTE] - > The **Add all team members** action retrieved a maximum of 100 team members. If you have more team members to add, then you can add them one by one by choosing **Add user**. + The **Add all team members** action retrieves a maximum of 100 team members. If you have more team members to add, you can add them one-by-one by choosing **Add user**. -1. If you need to add other contributors to your project, choose the :::image type="icon" source="../../media/icons/blue-add-icon.png" border="false"::: **Add user**. +2. If you need to add other contributors to your project, choose the :::image type="icon" source="../../media/icons/blue-add-icon.png" border="false"::: **Add user**. -2. Next, set any time off that a team member will take. For the entire team days off, choose the **0 days** link as shown. +3. Set team member time off. For the entire team days off, choose the **0 days** link as shown. - > [!div class="mx-imgBorder"] - > ![Screenshot of setting time off](media/capacity/team-members-added-set-team-days-off.png) + :::image type="content" source="media/capacity/team-members-added-set-team-days-off.png" alt-text="Screenshot of setting time off."::: - In the **Days off for** dialog, select the start and end days during the sprint that the team member or team will take off. + In the **Days off for** dialog, select the start and end days during the sprint for the team member or team days off. - > [!NOTE] - > Your sprint planning and tracking tools automatically consider days off when calculating capacity and sprint burndown. You only have to indicate planned days off for the team. You set weekend days or other recurring days off under your team's [Settings, Working days](../../organizations/settings/set-working-days.md) page. + > [!TIP] + > Your sprint planning and tracking tools automatically consider days off when calculating capacity and sprint burndown. You only have to indicate planned days off for the team. For more information, see [Set capacity for the team and team members](../../boards/sprints/set-capacity.md#set-capacity-for-the-team-and-team-members). -3. Now, set the **Activity/Discipline** and **Capacity** per day for each team member. If you track capacity simply by team member, you can leave the Activity or Discipline selection unassigned. +4. Set the **Activity/Discipline** and **Capacity** per day for each team member. If you track capacity simply by team member, you can leave the Activity or Discipline selection unassigned. - For example, Christie Church's capacity is 6 hours/day for design work. + For example, Christie Church's capacity is 6 hours/day for design work. - > [!div class="mx-imgBorder"] - > ![Screenshot of Set team capacity](media/capacity/set-team-capacity-agile.png) + :::image type="content" source="media/capacity/set-team-capacity-agile.png" alt-text="Screenshot of Set team capacity."::: ::: moniker-end -::: moniker range="tfs-2018" - -1. If you don't see your team members listed, add them. Choose the :::image type="icon" source="media/capacity/capacity-add-users.png" border="false"::: **Add missing team members** icon. For this feature to work, [team members will have been added to the team](../../organizations/settings/add-teams.md#add-team-members). - - > [!div class="mx-imgBorder"] - > ![Screenshot of Add team members, earlier versions](media/capacity/add-team-members-standard.png) - -2. If you need to add other contributors to your project, choose the :::image type="icon" source="../media/icons/add-light-icon.png" border="false"::: **Add user** icon. - -3. Next, set any time off that a team member will take. For the entire team days off, choose the **0 days** link as shown. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Set team days off, earlier versions.](media/capacity/set-team-days-off-standard.png) - - In the Days off for the entire team dialog, select the start and end days during the sprint that the team will take off. - - > [!NOTE] - > Your sprint planning and tracking tools automatically consider days off when calculating capacity and sprint burndown. Leave those days of the week that your team doesn't work unchecked in your team's Settings, [Working days](../../organizations/settings/set-working-days.md) page. - -4. Now, set the **Activity/Discipline** and **Capacity** per day for each team member. If you track capacity simply by team member, you can leave the Activity or Discipline selection unassigned. - - For example, Christie Church's capacity is 6 hours/day for design work. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Set individual capacity, TFS 2018 version.](media/capacity/capacity-planning-set-capacity-tfs-15.png) - -::: moniker-end - - ## Copy capacity planning from the previous sprint -By copying the capacity from the previous sprint, you save time. With the basics defined, all you have to do is adjust the capacity based on individual and team days off and capacity allocation per activity. +By copying the capacity from the previous sprint, you save time. With the basics defined, all you have to do is adjust the capacity based on individual and team days off and capacity allocation per activity. -Notice that only the capacity-per-day value and activity value are copied over. Individual and team days off remain unset. The copy operation always copies the latest updates made to the previous sprint. So you can repeat the copy operation if you've made changes to the previous sprint that you want to copy to the latest sprint. +Only the capacity-per-day value and activity value are copied over. Individual and team days off remain unset. The copy operation always copies the latest updates made to the previous sprint. So you can repeat the copy operation if you made changes to the previous sprint that you want to copy to the latest sprint. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -> [!div class="mx-imgBorder"] -> ![Screenshot of Copy capacity.](media/capacity/copy-capacity-from-previous-sprint-vert.png) +:::image type="content" source="media/capacity/copy-capacity-from-previous-sprint-vert.png" alt-text="Screenshot of Copy capacity."::: ::: moniker-end -::: moniker range="tfs-2018" - -For example, here we choose Sprint 2 and copy the capacity set for Sprint 1. -![Screenshot of Copy capacity from the previous iteration, earlier versions.](media/capacity/copy-capacity-from-previous-sprint.png) - -::: moniker-end - - -## Remove a user from capacity +## Remove a user from capacity -To remove a user, choose the option from the users :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: action menu. This action won't remove the user from the team. +To remove a user, choose the option from the users :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: action menu. This action doesn't remove the user from the team. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -> [!div class="mx-imgBorder"] -> ![Screenshot of Copy capacity Remove user from capacity list.](media/capacity/remove-user-agile.png) +:::image type="content" source="media/capacity/remove-user-agile.png" alt-text="Screenshot of Copy capacity Remove user from capacity list."::: ::: moniker-end -::: moniker range="tfs-2018" -![Screenshot of Copy capacity Capacity planning, Remove a user, earlier versions.](media/capacity/capacity-planning-remove-user.png) +## Review capacity charts -::: moniker-end - - -## Review capacity charts +As you define tasks and estimate the work, capacity charts start to fill in for each team member. Capacity bars track the remaining work against the capacity for each team member and the entire team. -As you define tasks and estimate the work, you'll see capacity charts start to fill in for each team member. Capacity bars track the remaining work against the capacity for each team member and the entire team. +You also see a roll-up of the remaining work required to complete each requirement or bug. -You'll also see a roll-up of the remaining work required to complete each requirement or bug. +::: moniker range="<=azure-devops" -::: moniker range=">= azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Screenshot of work details.](media/capacity/work-details.png) +:::image type="content" source="media/capacity/work-details.png" alt-text="Screenshot of work details."::: ::: moniker-end -::: moniker range="tfs-2018" - -![Screenshot of Capacity charts.](media/capacity/review-capacity.png) +From this view, you can see which individuals are at or near capacity. Teams can determine if work needs to be moved out of the sprint or to reassign tasks. -::: moniker-end - -From this view, you can easily see which individuals are at or near capacity. Teams can determine if work needs to be moved out of the sprint or to reassign tasks. - -::: moniker range=">= azure-devops-2019" - -> [!TIP] -> Define tasks that take a day or less to complete. This helps mitigate the risks that come from poor estimates. -> -> Also, don't divide tasks into subtasks. If you do divide a task into subtasks, specify Remaining Work only for the subtasks, as the system rolls up summary values to the parent task. - -::: moniker-end - -::: moniker range="tfs-2018" +::: moniker range="<=azure-devops" > [!TIP] > Define tasks that take a day or less to complete. This helps mitigate the risks that come from poor estimates. > -> Also, don't divide tasks into sub-tasks as [Taskboards only show leaf node tasks](../backlogs/resolve-backlog-reorder-issues.md). If you do divide a task into sub-tasks, specify Remaining Work only for the sub-tasks, as the system rolls up summary values to the parent task. +> Also, don't divide tasks into subtasks. If you do divide a task into subtasks, specify **Remaining Work** only for the subtasks, as the system rolls up summary values to the parent task. ::: moniker-end @@ -264,39 +174,32 @@ From this view, you can easily see which individuals are at or near capacity. Te ## Track capacity when completing multiple activities -Because individual team members have different sets of skills and duties, you can track their activity and capacity for each activity and for each sprint. +Because individual team members have different sets of skills and duties, you can track their activity and capacity for each activity and for each sprint. -Here, Jamal divides time between Deployment and Development. +Here, Jamal divides time between Deployment and Development. -> [!div class="mx-imgBorder"] -> ![Screenshot of Add activity to capacity tracking for an individual.](media/capacity/add-activity-to-capacity-planning.png) +:::image type="content" source="media/capacity/add-activity-to-capacity-planning.png" alt-text="Screenshot of Add activity to capacity tracking for an individual."::: ## Track capacity when working on more than one team -If you work on more than one team, you'll want to specify your sprint capacity for each team. For example, both Christie and Raisa split their time between the Web and Phone teams. As such, give 3 hours a day to the Web team, and 3 hours a day to the Phone team. +If you work on more than one team, specify your sprint capacity for each team. For example, both Christie and Raisa split their time between the Web and Phone teams. As such, give 3 hours a day to the Web team, and 3 hours a day to the Phone team. -> [!div class="mx-imgBorder"] -> ![Screenshot of Allocate capacity for team Web.](media/capacity/set-capacity-web-team.png) -
-> [!div class="mx-imgBorder"] -> ![Screenshot of Allocate capacity for team Phone.](media/capacity/set-capacity-phone-team.png) - -If your name isn't listed in the capacity view, you need to be added as a team member. +:::image type="content" source="media/capacity/set-capacity-web-team.png" alt-text="Screenshot of Allocate capacity for team Web."::: +:::image type="content" source="media/capacity/set-capacity-phone-team.png" alt-text="Screenshot of Allocate capacity for team Phone."::: + +If your name isn't listed in the capacity view, you need to be added as a team member. ## Next step > [!div class="nextstepaction"] -> [4. Adjust work](adjust-work.md) - +> [4. Adjust work](adjust-work.md) ## Related articles -Setting capacity and [estimating remaining work for each task](assign-work-sprint.md) provides you with the tools you need to track the amount of work and resources you have given sprint over sprint. - -- [Sprint burndown](../../report/dashboards/configure-sprint-burndown.md) -- [Velocity](../../report/dashboards/team-velocity.md) -- [Forecasting](../sprints/forecast.md) -- [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) \ No newline at end of file +- [Configure and monitor sprint burndown](../../report/dashboards/configure-sprint-burndown.md) +- [View and configure team velocity](../../report/dashboards/team-velocity.md) +- [Forecast your product backlog](../sprints/forecast.md) +- [Manage and configure team tools](../../organizations/settings/manage-teams.md) diff --git a/docs/boards/sprints/share-plan.md b/docs/boards/sprints/share-plan.md index 0af73be06dc..a02e0c36c65 100644 --- a/docs/boards/sprints/share-plan.md +++ b/docs/boards/sprints/share-plan.md @@ -17,14 +17,7 @@ ms.date: 09/20/2021 -Once you've completed your sprint plan, you can easily share it with other members of your team or organization. This article shows you how to: - -> [!div class="checklist"] -> * Create a query from your sprint plan -> * Email your sprint plan - -Any stakeholder on your team (someone with permissions to connect to your project) can view your sprint plan. Send them the URL of your sprint backlog page. But also, you can share it with them through email or print a version. - +Once you complete your sprint plan, sharing it with your team and organization is simple. Stakeholders with project access can view the sprint plan by accessing the URL of your sprint backlog page. Additionally, you can distribute the plan via email or by printing a copy to ensure everyone stays informed and aligned. ## Open a sprint backlog for a team @@ -49,54 +42,9 @@ Any stakeholder on your team (someone with permissions to connect to your projec ::: moniker-end -::: moniker range="azure-devops-2019" - -1. From your web browser, open your product backlog. (1) Check that you've selected the right project, (2) choose **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), choose **Backlog**. - -1. ![Open Work, Sprints, for a team](media/add-tasks/open-sprints-backlog-agile.png) - - To choose another team, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all sprints** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/add-tasks/team-selector-sprints-agile.png) - -2. To choose a different sprint than the one shown, open the sprint selector and choose the sprint you want. - - > [!div class="mx-imgBorder"] - > ![Choose another sprint](media/add-tasks/select-specific-sprint-agile.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). - -::: moniker-end - - -::: moniker range="tfs-2018" - -1. From your web browser, open your team's product backlog. (1) Select the team from the project/team selector, choose (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - - > [!div class="mx-imgBorder"] - > ![Open the Boards>Backlogs page](media/assign-items-sprint/open-work-backlogs-standard.png) - - To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Choose another team](media/assign-items-sprint/team-selector-backlogs-standard.png) - - The set of sprints selected for your team appears in the left pane. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Define sprints](define-sprints.md). - -1. Choose the sprint you want to plan. - - > [!div class="mx-imgBorder"] - > ![Choose another sprint](media/add-tasks/choose-sprint-standard.png) - - The system lists only those sprints that have been selected for the current team focus. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). - -::: moniker-end - - ## Create query for your sprint plan -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. (Optional) To choose which columns should display and in what order, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select **Column options**. For more information, see [Change column options](../backlogs/set-column-options.md). @@ -120,38 +68,12 @@ Any stakeholder on your team (someone with permissions to connect to your projec ::: moniker-end - -::: moniker range="tfs-2018" - -1. (Optional) To choose which columns should display and in what order, choose **Column options**. For more information, see [Change column options](../backlogs/set-column-options.md). - -1. To email the sprint plan, create and save the query for the sprint backlog. - - ![Share plan](media/share-plan/create-query-standard.png) - -2. Then, open the query and choose the email icon. - - ![Email query](media/IC795975.png) - -3. In the form that appears, enter the name(s) of valid users (ones who have access to the project). - - > [!IMPORTANT] - > You can only send the email to individual address for a project member that is recognized by the system. Adding a team group or security group to the to line isn't supported. If you add an email account that the system doesn't recognize, you receive a message that one or more recipients of your email don't have permissions to read the mailed work items. - - -::: moniker-end - -Or, you can select all the items in the list, choose **Copy as HTML**, and paste the formatted list into an email form or Word document. See [Copy a list of work items](../backlogs/copy-list.md?toc=/azure/devops/boards/sprints/toc.json). - - +Or, you can select all the items in the list, choose **Copy as HTML**, and paste the formatted list into an email form or Word document. See [Copy a list of work items](../backlogs/copy-clone-work-items.md#copy-a-list-of-work-items). ## Next step > [!div class="nextstepaction"] > [6. Update the taskboard](task-board.md) - ## Related articles -- [Email or print work items](../work-items/email-work-items.md) -- [Share information in work items and social tools](../queries/share-plans.md) - +- [Send email with work items](../work-items/email-work-items.md) diff --git a/docs/boards/sprints/task-board.md b/docs/boards/sprints/task-board.md index cf6187f4987..48e5ea1a8c2 100644 --- a/docs/boards/sprints/task-board.md +++ b/docs/boards/sprints/task-board.md @@ -9,51 +9,50 @@ ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 01/23/2023 +ms.date: 11/27/2024 --- # 6. Update and monitor your Taskboard [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Once you have your [sprint plan](assign-work-sprint.md) in place, you'll execute that plan during the sprint. In your daily Scrum meetings, your team can view progress made to backlog items and tasks from the sprint **Taskboard**. +Adding tasks to backlog items is essential for tracking the work required to implement them. Tasks also help estimate the effort assigned to individual team members and the team as a whole. The capacity tool indicates how much work your team can commit to. To effectively compare capacity with planned work, define and estimate tasks for each backlog item. -Your **Taskboard** provides a visualization of flow and status of each sprint task. With it, you can focus on the status of backlog items and work assigned to each team member. It also summarizes the total amount of **Remaining Work** to complete for a task and within a column. +### Define comprehensive tasks -In this article you'll learn how to: +- **Capture all work:** Add as many tasks as needed to fully capture the work required to complete each backlog item. +- **Differentiate work types:** Represent various activities such as design, coding, testing, content creation, or sign-offs with separate tasks. +- **Assign responsibility:** + - **Individual tasks:** Team members typically add their own tasks and set estimates for their workload. + - **Initial tasks:** A development lead can define the initial tasks for a story or requirement. -> [!div class="checklist"] -> * Open the sprint **Taskboard** for your team -> * Customize your **Taskboard** -> * Use your **Taskboard** to review progress during daily scrum meetings -> * Filter and group work items on your **Taskboard** -> * Update the status of tasks through drag-and-drop -> * Update remaining work -> * Close out a sprint +### Estimate effort -If you haven't yet [added tasks to your sprint backlog](add-tasks.md), do that now. +- **Set estimates:** Assign effort estimates to each task to help gauge the total work required. +- **Align with capacity:** Use the capacity tool to ensure that the estimated work aligns with your team’s available capacity. -> [!NOTE] -> Your **Taskboard** is one of two types of boards available to you. For an overview of the features supported on each backlog and board, see [Backlogs, boards, and plans](../backlogs/backlogs-boards-plans.md). +By effectively adding and managing tasks, your team gains a clear understanding of the relative importance and required effort for each item, ensuring better workload distribution and project planning. ## Prerequisites -* Connect to a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -* Get added to a project as a member of the **Contributors** or **Project Administrators** security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To add work items and exercise all board features, you must be granted **Basic** access or higher. Users granted **Stakeholder** accesses have limited access to features. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -* To view or modify work items, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Permissions** | - Member of the **Contributors** or **Project Administrators** security group. To get added, see [Add users to a project or team](../../organizations/security/add-users-team-project.md).
- To view or modify work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). | +| **Access levels** | To add work items and exercise all board features: At least [**Basic** access](../../organizations/security/access-levels.md). | +| **Sprint backlog** | [Tasks on your sprint backlog](add-tasks.md). | ::: moniker range=">= azure-devops-2022" > [!NOTE] -> Users assigned **Stakeholder** access can't exercise these **Taskboard** features: update fields displayed on cards or use the **Planning** pane to change the sprint assignment. +> Users assigned **Stakeholder** access can't update fields displayed on cards or use the **Planning** pane to change the sprint assignment. ::: moniker-end ::: moniker range="< azure-devops-2022" > [!NOTE] -> Users with **Stakeholder** access can't exercise these **Taskboard** features: add tasks, update fields displayed on cards, drag-and-drop tasks to update status, or use the **Planning** pane to change the sprint assignment. +> Users with **Stakeholder** access can't add tasks, update fields displayed on cards, drag-and-drop tasks to update status, or use the **Planning** pane to change the sprint assignment. ::: moniker-end @@ -61,12 +60,11 @@ If you haven't yet [added tasks to your sprint backlog](add-tasks.md), do that n ::: moniker range=">= azure-devops-2020" -1. From your web browser, open the sprint backlog for your team. +1. From your project, open the sprint backlog for your team. - 1. Check that you've selected the right **Project** - 2. Choose **Boards>Sprints** - 3. Select the correct **Team** from the team selector menu - 4. Choose **Taskboard** +2. Select **Boards** > **Sprints**. +3. Select the correct **Team** from the team selector menu. +4. Choose **Taskboard**. > [!div class="mx-imgBorder"] > ![Screenshot that shows how to Open the sprint Taskboard for a team.](media/add-tasks/open-sprint-backlog-taskboard-s155-co.png) @@ -76,61 +74,15 @@ If you haven't yet [added tasks to your sprint backlog](add-tasks.md), do that n > [!div class="mx-imgBorder"] > ![Screenshot that shows the sprint backlog team selector options.](media/add-tasks/team-selector-sprints-agile.png) -1. To choose a different sprint than the one shown, open the sprint selector and choose the sprint you want. +5. To choose a different sprint than the one shown, open the sprint selector and choose the sprint you want. > [!div class="mx-imgBorder"] > ![Screenshot that shows how to Choose another sprint.](media/add-tasks/select-specific-sprint-agile.png) - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). - -::: moniker-end - - -::: moniker range="azure-devops-2019" - -1. From your web browser, open the sprint backlog for your team. (1) Check that you've selected the right project, (2) choose **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), choose (4) **Taskboard**. - - > [!div class="mx-imgBorder"] - > ![Screenshot that shows how to Open the sprint Taskboard for a team, Azure DevOps 2019.](media/taskboard/open-taskboard-agile.png) - - To choose another team, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all sprints** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Screenshot that shows the sprint backlog team selector options, Azure DevOps 2019.](media/add-tasks/team-selector-sprints-agile.png) - -1. To choose a different sprint than the one shown, open the sprint selector and choose the sprint you want. - - > [!div class="mx-imgBorder"] - > ![Screenshot that shows how to Choose another sprint, Azure DevOps 2019.](media/add-tasks/select-specific-sprint-agile.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). + The system lists only those sprints that selected for the current team focus. If you don't see the sprints you want listed, then choose **New Sprint** from the menu, and then choose **Select existing iteration**. For more information, see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). ::: moniker-end -::: moniker range="tfs-2018" - -1. From your web browser, open your team's product backlog. (1) Select the team from the project/team selector, choose (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - - > [!div class="mx-imgBorder"] - > ![Screenshot to open a team's sprint backlog page.](media/assign-items-sprint/open-work-backlogs-standard.png) - - To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Screenshot to Choose another team, TFS 2018.](media/assign-items-sprint/team-selector-backlogs-standard.png) - - The set of sprints selected for your team appears in the left pane. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Define sprints](define-sprints.md). - -1. Choose the sprint you want to plan, and then choose **Board**. - - > [!div class="mx-imgBorder"] - > ![Screenshot that shows how to Open the task Board for a sprint, TFS 2018.](media/taskboard/open-taskboard-standard.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then see [Define iteration (sprint) paths](../../organizations/settings/set-iteration-paths-sprints.md). - -::: moniker-end - - ## Customize the Taskboard Each team can customize their **Taskboard** in the following ways: @@ -139,16 +91,7 @@ Each team can customize their **Taskboard** in the following ways: - [Add or rename columns](customize-taskboard.md#add-columns). - [Customize cards](customize-taskboard.md#choose-fields) to show another fields or change card color based on specified field criteria. -- [Show bugs on the Taskboard](../../organizations/settings/show-bugs-on-backlog.md). Your team can choose to manage bugs similar to product backlog items, as shown in this article, or manage them similar to tasks. When you track bugs similar to tasks, they'll show up on your sprint backlogs and **Taskboards** at the same level as tasks. - -::: moniker-end - -::: moniker range="<= azure-devops-2019" - -- [Customize cards](../../boards/boards/customize-cards.md) that appear on the **Taskboard** to show other fields. -- [Show bugs on the Taskboard](../../organizations/settings/show-bugs-on-backlog.md). Your team can choose to manage bugs similar to product backlog items, as shown in this article, or manage them similar to tasks. When you track bugs similar to tasks, they'll show up on your sprint backlogs and **Taskboards** at the same level as tasks. - -Unlike the Kanban board for a product backlog, you can't add another columns to the **Taskboard** via a team configuration setting. Instead, you need to modify the workflow definitions for the task work item type used by the project. Workflow customizations update the columns for the **Taskboard** for all teams within the project. +- [Show bugs on the Taskboard](../../organizations/settings/show-bugs-on-backlog.md). Your team can choose to manage bugs similar to product backlog items, as shown in this article, or manage them similar to tasks. When you track bugs similar to tasks, they show up on your sprint backlogs and **Taskboards** at the same level as tasks. ::: moniker-end @@ -160,30 +103,6 @@ An administrator can customize the **Taskboard** for all teams in the following ::: moniker-end -::: moniker range="azure-devops-2019" - -An administrator can customize the **Taskboard** for all teams in the following ways based on the process model selected for the project: - -**Inherited process model:** -- [Add a custom workflow state to the task WIT for a process](../../organizations/settings/work/customize-process-workflow.md) -- [Add a custom work item type to the Taskboard for a process](../../organizations/settings/work/customize-process-backlogs-boards.md) - -**On-prem XML process model:** -- [Add a custom workflow state to the task WIT for a process](../../organizations/settings/work/customize-process-workflow.md) -- [Add a custom work item type to the Taskboard for a process](../../organizations/settings/work/customize-process-backlogs-boards.md) -- -::: moniker-end - - -::: moniker range="tfs-2018" - -An administrator can customize the **Taskboard** for all teams in the following ways: -- [Modify the workflow for the task WIT definition](../../reference/xml/change-workflow-wit.md). -- [Add a work item type to a backlog or board](../../reference/add-wits-to-backlogs-and-boards.md). - -::: moniker-end - - ## Taskboard controls @@ -191,8 +110,8 @@ An administrator can customize the **Taskboard** for all teams in the following | Control | Function | |-----------------------|---------------------------------------------| | Backlog | [Switch to sprint backlog view](assign-work-sprint.md) | -| Board | Switch to taskboard view | -| Capacity | [Switch to Capacity planning](assign-work-sprint.md#set-capacity) | +| Board | Switch to Taskboard view | +| Capacity | [Switch to Capacity planning](assign-work-sprint.md) | | Group by Stories/People | Switch grouping of cards based on backlog items or team members | | Person | Filter tasks to show items assigned to All or a selected team member | | ![Settings icon](../media/icons/team-settings-gear-icon.png) | [Open board settings](../../boards/boards/customize-cards.md) | @@ -200,7 +119,6 @@ An administrator can customize the **Taskboard** for all teams in the following See also [Backlog keyboard shortcuts](../../project/navigation/keyboard-shortcuts.md). - ## Review progress in daily scrum meetings @@ -209,13 +127,11 @@ During your daily Scrum, you can filter your **Taskboard** to help focus on item * Group by Backlog items or Group by stories to monitor progress of your product backlog items, stories, requirements, or bugs. * Group by People when you want to monitor progress of individual team members. - ::: moniker range=">= azure-devops-2020" > [!NOTE] > Your Taskboard automatically refreshes when changes occur. There isn't any live updates control, it simply happens in the background. As other team members move or reorder cards on the taskboard, the Taskboard automatically updates with these changes. You don't need to press F5 to see the latest changes. ::: moniker-end - Use the Person filter when you want to focus on work assigned to individual team members. > [!TIP] @@ -227,61 +143,33 @@ Use the Person filter when you want to focus on work assigned to individual team With this view, you can quickly see which items are nearing completion and which have yet to be started. -::: moniker range=">= azure-devops-2019" - -1. To show cards based on their backlog-to-task groupings, choose :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options** and select **Stories** (for Agile), **Issues** (for Basic), **Backlog items** (for Scrum),and **Requirements** (for CMMI). +1. To show cards based on their backlog-to-task groupings, choose :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options** and select **Stories** (for Agile), **Issues** (for Basic), **Backlog items** (for Scrum), and **Requirements** (for CMMI). > [!div class="mx-imgBorder"] > ![Screenshot of Taskboard, Set view options.](media/taskboard/group-items-all-agile.png) -1. You can **Collapse All** or **Expand All** rows, and selectively expand ![expand icon](../media/icons/expand_row_icon.png) and collapse ![collapse icon](../media/icons/collapse_row_icon.png) a row to focus on a particular item and its tasks. +2. You can **Collapse All** or **Expand All** rows, and selectively expand ![expand icon](../media/icons/expand_row_icon.png) and collapse ![collapse icon](../media/icons/collapse_row_icon.png) a row to focus on a particular item and its tasks. > [!div class="mx-imgBorder"] > ![Screenshot of Taskboard, collapsed, show items.](media/taskboard/group-items-all-taskboard-agile.png) -::: moniker-end - - -::: moniker range="tfs-2018" -You can expand ![expand icon](../media/icons/expand_row_icon.png) and collapse ![collapse icon](../media/icons/collapse_row_icon.png) a row to focus on a particular item and its tasks. - -![Screenshot of Taskboard, Group by backlog items, show All team members, TFS 2018.](media/taskboard/group-items-all.png) - -::: moniker-end - ## Show a team member's progress -With this view, you can focus on the work completed and the work remaining for each individual team member. You can quickly see who may need help with completing their sprint tasks. This view shows items and tasks assigned to the selected team member. - - -::: moniker range=">= azure-devops-2019" +With this view, you can focus on the work completed and the work remaining for each individual team member. You can quickly see who might need help with completing their sprint tasks. This view shows items and tasks assigned to the selected team member. To filter on the tasks for a specific team member, choose the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: filter icon, and then select their name from the **Assigned to** filter box. > [!div class="mx-imgBorder"] > ![Screenshot of Taskboard, filter on a person.](media/taskboard/group-by-people.png) -::: moniker-end - -::: moniker range="tfs-2018" - -Choose the **Group by People** option, and then select a specific team member, or **All**. - -![Screenshot of Taskboard, Group by Backlog items, show Christie Church team member, TFS 2018.](media/ALM_TB_GRP_Items_CC.png) -::: moniker-end - - - ## Group tasks by team members With this view, you can quickly see all the tasks associated with each team member. Backlog items don't appear in this view, only the tasks associated with each individual. -::: moniker range=">= azure-devops-2019" - 1. Choose the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: view options icon and select **People**. Only those team members with tasks assigned to them are listed. All their tasks are shown as cards under their column state. @@ -289,21 +177,11 @@ With this view, you can quickly see all the tasks associated with each team memb > [!div class="mx-imgBorder"] > ![Screenshot of Taskboard, Group by people.](media/taskboard/group-by-people-agile.png) -1. To filter on the tasks for a specific team member, choose **Filter** :::image type="icon" source="../../media/icons/filter-icon.png" border="false":::, and then select their name from the **Assigned to** filter box. For more information, see [Interactively filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md). +2. To filter on the tasks for a specific team member, choose **Filter** :::image type="icon" source="../../media/icons/filter-icon.png" border="false":::, and then select their name from the **Assigned to** filter box. For more information, see [Interactively filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md). > [!div class="mx-imgBorder"] > ![Screenshot of Taskboard, Filter on tasks for a specific team member.](media/taskboard/filter-by-a-team-member.png) -::: moniker-end - -::: moniker range="tfs-2018" - -Choose the **Group by People** option, and then select a specific team member, or **All**. - -![Screenshot of Taskboard, Group by People, show All team members, TFS 2018.](media/ALM_TB_GRP_People_All.png) - -::: moniker-end - ## Update tasks during the sprint cycle @@ -322,53 +200,39 @@ When you move a task to the **Done** or **Completed** column, the system automat ### Update Remaining Work -Updating **Remaining Work**, preferably before the daily Scrum meeting, helps the team stay informed of the progress being made. It also ensures a smoother burndown chart. +Update **Remaining Work**, preferably before the daily Scrum meeting, which helps the team stay informed of the progress being made. It also ensures a smoother burndown chart. -Each team member can review the tasks they've worked on and estimate the work remaining. If they've discovered that it's taking longer than expected to complete, they should increase the **Remaining Work** for the task. **Remaining Work** should always reflect exactly how much work the team member estimates is remaining to complete the task. +Each team member can review the tasks they worked on and estimate the work remaining. If they discover that it's taking longer than expected to complete, they should increase the **Remaining Work** for the task. **Remaining Work** should always reflect exactly how much work the team member estimates is remaining to complete the task. -::: moniker range=">= azure-devops-2019" > [!div class="mx-imgBorder"] > ![Screenshot of Taskboard, Update remaining work.](media/taskboard/update-hours.png) -::: moniker-end - -::: moniker range="tfs-2018" -![Screenshot of Taskboard, update task remaining work, TFS 2018.](media/ALM_TB_UpdateRWork.png) -::: moniker-end ## Close out a sprint and update your Taskboard -At the end of the sprint, you'll want to complete these final tasks: -* Zero out *Remaining Work* of all completed tasks -* Update the status of all completed backlog items -* Drag incomplete backlog items and tasks to the next sprint or back to the product backlog. +At the end of the sprint, complete these final tasks: +* Zero out *Remaining Work* of all completed tasks +* Update the status of all completed backlog items +* Drag incomplete backlog items and tasks to the next sprint or back to the product backlog. Drag an incomplete item to the product backlog or to a future sprint updates the Iteration Path of all unfinished child tasks to correspond to the product-backlog iteration path or future sprint. See also [End of sprint activities](end-sprint-activities.md). -::: moniker range="tfs-2018" -You can [drag-and-drop work items onto a sprint from any backlog or board](assign-work-sprint.md#drag-drop). -::: moniker-end - - - -## Reduce the number of items on the taskboard +## Reduce the number of items on the Taskboard -If you exceed the number of items allowed on your taskboard, you'll receive a message indicating that you need to reduce the number of items. The maximum number of items includes work item types included in the Requirement and Task categories. +If you exceed the number of items allowed on your Taskboard, you receive a message indicating that you need to reduce the number of items. The maximum number of items includes work item types included in the Requirement and Task categories. -You can reduce the number of items on the taskboard by moving them to the backlog or another sprint. When you move a parent PBI or user story, all active child tasks (State not equal to Done or Closed) automatically move with the parent item. +You can reduce the number of items on the Taskboard by moving them to the backlog or another sprint. When you move a parent PBI or user story, all active child tasks (State not equal to Done or Closed) automatically move with the parent item. -- From the taskboard, drag the PBI or user story from the first column onto the backlog or future sprint. All child tasks automatically move with the parent item. +- From the Taskboard, drag the PBI or user story from the first column onto the backlog or future sprint. All child tasks automatically move with the parent item. - From the sprint backlog, multi-select the items to move and then select the context menu for an item. Then, select the iteration to move them to. ![Screenshot that shows multi-select items from the sprint backlog. ](media/sprint-backlog-multi-select-non-sequential-items.png) - - ::: moniker range="< azure-devops" Or, if your project uses an On-premises XML process, you can [increase the maximum number of allowed items](../../reference/customize-work.md#limits). ::: moniker-end @@ -378,20 +242,13 @@ Or, if your project uses an On-premises XML process, you can [increase the maxim > [!div class="nextstepaction"] > [End of sprint activities](end-sprint-activities.md) - ## Related articles -As you can see, the Taskboard provides support for your Scrum activities. For related articles, see: - -- [Assign backlog items to a sprint](assign-work-sprint.md) -- [Interactively filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md) -- [Scrum best practices](best-practices-scrum.md) -- [Sprint planning](assign-work-sprint.md) -- [Schedule sprints](define-sprints.md) -- [Sprint burndown](../../report/dashboards/configure-sprint-burndown.md) -- [Customize a sprint Taskboard](customize-taskboard.md) -- [Capacity planning](../sprints/set-capacity.md) - - - - +- Assign backlog items to a sprint using [Assign backlog items to a sprint](assign-work-sprint.md) +- Interactively filter backlogs, boards, queries, and plans with [Interactively filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md) +- Implement [Scrum best practices](best-practices-scrum.md) +- Plan sprints using [Sprint planning](assign-work-sprint.md) +- Schedule sprints with [Schedule sprints](define-sprints.md) +- Monitor [Sprint burndown](../../report/dashboards/configure-sprint-burndown.md) +- Customize your sprint Taskboard using [Customize a sprint Taskboard](customize-taskboard.md) +- Manage capacity with [Capacity planning](../sprints/set-capacity.md) diff --git a/docs/boards/sprints/toc.yml b/docs/boards/sprints/toc.yml index aafc932b10b..cc9838da387 100644 --- a/docs/boards/sprints/toc.yml +++ b/docs/boards/sprints/toc.yml @@ -40,8 +40,8 @@ - name: Filter your sprint views href: ../backlogs/filter-backlogs-boards-plans.md displayname: group, parent, tags - - name: Set working days - href: ../../organizations/settings/set-working-days.md?bc=%252fazure%252fdevops%252fboards%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fboards%252ftoc.json + - name: Set capacity + href: ../../boards/sprints/set-capacity.md?bc=%252fazure%252fdevops%252fboards%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fboards%252ftoc.json displayname: team - name: Best practices, monitoring, & reports items: diff --git a/docs/boards/toc.yml b/docs/boards/toc.yml index 3f9b6389dd0..64b5b7e0b32 100644 --- a/docs/boards/toc.yml +++ b/docs/boards/toc.yml @@ -7,7 +7,7 @@ displayName: agile, kanban, scrum, rollup, filtering, waterfall, deliverables, cadence, sprint cadence, work types, CMMI, product plan, product backlog href: best-practices-agile-project-management.md - name: Quick reference - concepts and tasks - displayName: agile, charts, interitance, work item, scrum, state categories, bulk modify, WIT + displayName: agile, charts, inheritance, work item, scrum, state categories, bulk modify, WIT href: ./work-items/quick-ref.md - name: Get started href: get-started/toc.yml @@ -55,12 +55,6 @@ items: - name: Office integration issues href: backlogs/office/tfs-office-integration-issues.md - - name: Resolve Excel data conflicts - displayName: conflicts, Excel, conflicting work-items/guidance/cmmi/guidance-review-meeting-field-reference-cmmi.md - href: backlogs/office/resolve-excel-data-conflicts-publish-refresh.md - - name: Resolve Excel data validation errors - displayName: error checking in Excel, error checking, invalid links - href: backlogs/office/resolve-excel-data-validation-errors.md - name: Project portal & process guidance (Deprecated) items: - name: Configure or add a project portal @@ -71,14 +65,9 @@ items: - name: FAQs href: faqs.yml - - name: Set up your backlogs & boards - href: backlogs/set-up-your-backlog.md - - name: Fix "Ordering backlog items is disabled" + - name: Fix reordering and nesting issues href: backlogs/resolve-backlog-reorder-issues.md displayname: reorder, disable, nest, natural hierarchy, in progress - - name: Work item form caching - href: ../organizations/settings/work/troubleshoot-work-item-form-caching-issues.md - displayname: IndexDB, rule - name: Field reference items: - name: Work item field index diff --git a/docs/boards/work-items/about-work-items.md b/docs/boards/work-items/about-work-items.md index 052f99cb546..8b81f8016df 100644 --- a/docs/boards/work-items/about-work-items.md +++ b/docs/boards/work-items/about-work-items.md @@ -1,7 +1,7 @@ --- title: About work items and work item types titleSuffix: Azure Boards -description: Learn how Azure Boards supports work items to plan, track, & collaborate with others when developing software apps in Azure DevOps. +description: Learn how Azure Boards supports work items to plan, track, and collaborate with others when developing software applications in Azure DevOps. ms.custom: work-items, engagement-fy23 ms.service: azure-devops-boards ms.assetid: @@ -9,25 +9,24 @@ ms.author: chcomley author: chcomley ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 04/04/2023 +ms.date: 10/02/2024 --- # About work items and work item types [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You use work items to track features and requirements you're developing, code defects or bugs, and issues or risks to your project. Each work item is based on a work item type that determines the work item fields available for tracking information. The work item types available to you differ depending on the [process used when your project was created](../../boards/work-items/guidance/choose-process.md): **Agile**, **Basic**, **Scrum**, or **CMMI**. +Use work items to track features, requirements, code defects, bugs, and project issues or risks. Each work item is based on a work item type that determines the fields available for tracking information. The work item types available depend on the [process used when your project was created](../../boards/work-items/guidance/choose-process.md): **Agile**, **Basic**, **Scrum**, or **CMMI**. -Each work item represents an object stored in the work item data store, and is assigned a unique identifier within an organization or project collection. The available work item types depend on the [process you used when creating your project](guidance/choose-process.md). +Each work item represents an object stored in the work item data store and is assigned a unique identifier within an organization or project collection. -If you're just getting started, read this article. To jump right in and start tracking work on a Kanban board, see [Plan and track work](../get-started/plan-track-work.md). For a quick reference to various work item tasks and key concepts, see [Work item quick reference](quick-ref.md). +If you're just getting started, read this article. To start tracking work on a board, see [Plan and track work](../get-started/plan-track-work.md). For a quick reference to various work item tasks and key concepts, see [Work item quick reference](quick-ref.md). - - + ## Track work with different work item types -To track different types of work, you choose a specific work item type. The following images show the default work item types available for the four default processes. The items in your backlog might be called User Stories (Agile), Issues (Basic), Product Backlog Items (Scrum), or Requirements (CMMI). All four types are similar. They describe the customer value of the work to do and provide fields to track information about that work. +To track different types of work, choose a specific work item type. The following images show the default work item types available for the four default processes. Items in your backlog might be called User Stories (Agile), Issues (Basic), Product Backlog Items (Scrum), or Requirements (CMMI). All four types are similar; they describe the customer value of the work and provide fields to track information about that work. [!INCLUDE [temp](../includes/work-item-types.md)] @@ -41,25 +40,23 @@ Each work item type belongs to a category. Categories are used to group work ite |Task | Task | Sprint backlogs and Taskboards | |Bug | Bug | Dependent on [team configuration for tracking bugs](#track) | -The Issue (Agile and CMMI) and Impediment (Scrum) work item types are used to track nonwork project elements that can impact work getting done. By default, they don't appear on any backlog or board. +The Issue (Agile and CMMI) and Impediment (Scrum) work item types are used to track nonwork project elements that can affect work getting done. By default, they don't appear on any backlog or board. For a list of other work item types, see [Work item types to track testing, reviews, and feedback ](#wit-other) later in this article. - ### Track bugs as requirements or tasks -Your team can choose how to track bugs. They can track them along with requirements and have them show up on their product backlog and Kanban board. Or, they track them similar to tasks, in which case they typically link the bugs to a user story or product backlog item. A third option exists to not track them as requirements or tasks. - +Your team can choose how to track bugs. They can track them along with requirements, showing them on the product backlog and board. Alternatively, they can track bugs similar to tasks, typically linking them to a user story or product backlog item. A third option is to not track them as requirements or tasks. + To configure the team bug tracking option, see [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). For an overview of all team settings, see [Manage teams and configure team tools](../../organizations/settings/manage-teams.md). - - + ### Customize a work item type -You can add or modify the fields that are contained within a work item type, add a custom work item type, or change the work item types that appear on backlogs and boards. The method you use and what you can customize depends on the process model assigned to your project. For more information, see the following articles: +You can include or revise fields within a work item type, introduce a personalized work item type, or adjust the display of work item types on backlogs and boards. The approach and extent of customization available depend on the process model assigned to your project. For more information, see the following articles: ::: moniker range="azure-devops" - [Customize your work tracking experience](../../organizations/settings/work/inheritance-process-model.md) @@ -72,24 +69,52 @@ You can add or modify the fields that are contained within a work item type, add - [On-premises XML process customization](../../reference/on-premises-xml-process-model.md). ::: moniker-end - + ## Work item form and Details tab -The work item form shows the fields used to track information related to each work item. In general, you define and update a work item through its work item form, although other methods are available to bulk import, export, update, and modify work items. For an overview of all form controls, see [Work item form controls](work-item-form-controls.md). +The work item form displays the fields used to track information for each individual work item. Define and update a work item through its respective form, as well as through methods like bulk import, export, update, and modification. -Each work item form contains several tabs. The **Details** tab contains the common fields, other fields defined for the work item type, and the **Discussion** control. Common fields defined for all work item types display at the top of the work item form. As shown in the following image, these fields include the following fields: **Title**, **Assigned To**, **State**, **Reason**, **Area**, and **Iteration**. You can update these fields at any time. +Each work item form contains several tabs. The **Details** tab includes common fields, other fields defined for the work item type, and the **Discussion** control. Common fields for all work item types appear at the top of the form. These fields include **Title**, **Assigned To**, **State**, **Reason**, **Area**, and **Iteration**. You can update these fields at any time. :::image type="content" source="media/about-work-items/common-fields-basic.png" alt-text="Screenshot of common fields in work item form for all work item types."::: +### Work item form controls + +| Control | Function | +|--------------------------|-------------------------------| +| ![Copy to clipboard icon](../backlogs/media/icon-copy-to-clipboard.png) | Copy URL of work item to clipboard (appears on hover over work item title) | +| ![Discussions icon](../media/icons/icon-discussions-wi.png) | Go to Discussions section | +| :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: | Open Actions menu for other work item tasks | +| ![Refresh icon](../media/icons/icon-refresh-wi.png) | Refresh work item with latest changes | +| ![Undo icon](../media/icons/icon-undo-changes-wi.png) | Revert changes to work item | +| ![History tab icon](../media/icons/icon-history-tab-wi.png) | Open History tab | +| ![Links tab icon](../media/icons/icon-links-tab-wi.png) | Open Links tab | +| ![Attachment tab icon](../backlogs/media/icon-attachments-tab-wi.png) | Open Attachments tab | +| ![full screen icon](../media/icons/fullscreen_icon.png) / ![exit full screen icon](../media/icons/exitfullscreen_icon.png) | Enter or exit full display mode of a section within the form | +|![Collapse section icon](../media/icons/collapse-wi-section.png)/![Expand section icon](../media/icons/expand-wi-section.png) | Collapse or expand a section within the form | +| ![New linked work item icon](../media/icons/new-linked-work-item.png) | Add new work item and link to existing work item (might appear under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | +| ![Change work item type icon](../media/icons/change-type-icon.png) | [Change work item type](../backlogs/remove-delete-work-items.md) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | +| ![Change project icon](../media/icons/change-team-project-icon.png) | [Move work item to a different project](../backlogs/remove-delete-work-items.md) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | +| ![Clone icon](../media/icons/clone-icon.png) | [Copy work item and optionally change work item type](../backlogs/copy-clone-work-items.md#copy-clone) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | +| ![Email icon](../media/icons/email-icon.png) | [Send email with work item](email-work-items.md) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | +| ![Delete icon](../media/icons/delete_icon.png) | [Recycle work item](../backlogs/remove-delete-work-items.md) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | +| ![Storyboard icon](../media/icons/storyboard-icon.png) | [Storyboard with PowerPoint](/previous-versions/azure/devops/boards/backlogs/office/storyboard-your-ideas-using-powerpoint) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | + +### Copy the URL + +From the web portal, copy the URL from the web browser address or hover over the title and then select the :::image type="icon" source="../../media/icons/copy-clone-icon.png" border="false"::: copy icon. For other copy options, see [Copy or clone work items](../backlogs/copy-clone-work-items.md). + +:::image type="content" source="../backlogs/media/add-work-item-copy-URL.png" alt-text="Screenshot of copy hyperlink for a work item from web portal."::: + - + ### Common work tracking fields -The following common fields appear in most work items in the header area of the form. The only required field for all work item types is **Title**. When the work item is saved, the system assigns it a unique **ID**. The form highlights required field in yellow. For descriptions about other fields, see [Work item field index](../work-items/guidance/work-item-field.md). +The following common fields appear in most work items in the header area of the form. The only required field for all work item types is **Title**. When the work item is saved, the system assigns it a unique **ID**. The form highlights required fields in yellow. For descriptions of other fields, see [Work item field index](../work-items/guidance/work-item-field.md). > [!NOTE] > Additional fields may be required depending on customizations made to your process and project. @@ -97,7 +122,7 @@ The following common fields appear in most work items in the header area of the |Field | Usage | |----------|------------------------| |[Title](../queries/titles-ids-descriptions.md) |Enter a description of 255 characters or less. You can always modify the title later.| -|[Assigned To](#assign) |Assign the work item to the team member responsible for performing the work. Depending on the context you're working in, the drop-down menu lists only team members or contributors to the project.| +|[Assigned To](#assign) |Assign the work item to the team member responsible for performing the work. Depending on the context, the drop-down menu lists only team members or contributors to the project.| |[State](#workflow-states) |When the work item is created, the **State** defaults to the first state in the workflow. As work progresses, you update it to reflect the current state.| |[Reason](#workflow-states) | Automatically updates when the State is changed. Each State is associated with a default reason.| |[Area](../queries/query-by-area-iteration-path.md) |Choose the area path associated with the product or team, or leave blank until assigned during a planning meeting. To change the dropdown list of areas, see [Define area paths and assign to a team](../../organizations/settings/set-area-paths.md).| @@ -107,48 +132,45 @@ The following common fields appear in most work items in the header area of the ### Track active, open, resolved, or closed work items -Workflow states define how a work item progresses from its creation to closure. Workflow states also determine whether a work item appears on a backlog or board as described in [How workflow category states are used in Azure Boards backlogs and boards](workflow-and-state-categories.md). +Workflow states define how a work item progresses from creation to closure. They also determine whether a work item appears on a backlog or board, as described in [How workflow category states are used in Azure Boards backlogs and boards](workflow-and-state-categories.md). -The four main states that are defined for the User Story (Agile process) describe a user story's progression. The workflow states are *New*, *Active*, *Resolved*, *Closed*, and *Removed*. The following images illustrate the natural progressions and regressions for User Stories (Agile), Issues (Basic), Product Backlog Items (Scrum), or Requirements (CMMI). Similar progressions and regressions are defined for other work item types for each process. +The User Story (Agile process) has four main states that describe its progression: *New*, *Active*, *Resolved*, *Closed*, and *Removed*. The following images illustrate the natural progressions and regressions for User Stories (Agile), Issues (Basic), Product Backlog Items (Scrum), and Requirements (CMMI). Similar progressions and regressions are defined for other work item types in each process. [!INCLUDE [temp](../includes/four-process-workflow.md)] > [!NOTE] -> - A work item can exist in one and only one state. -> - When all work is complete, set the work item **State** to -> - The Kanban board and Sprint Taskboard support viewing and updating the workflow state of requirements or tasks, respectively, using drag and drop. For more information, see [Start using your Kanban board](../boards/kanban-quickstart.md) and [Update and monitor your Taskboard](../sprints/task-board.md). -> - Depending on the :::image type="icon" source="../media/icons/view-options-icon.png" border="false"::: **View Options** you select, work items in a *Closed* or *Completed* state won't appear on the backlog. -> - The *Removed* state supports removing a work item from appearing on the backlog. For more information, see [Move, change, or delete work items](../backlogs/remove-delete-work-items.md#remove). +> - A work item can exist in only one state at a time. +> - When all work is complete, set the work item **State** to Closed. +> - The board and Sprint Taskboard support viewing and updating the workflow state of requirements or tasks using drag and drop. For more information, see [Start using your board](../boards/kanban-quickstart.md) and [Update and monitor your Taskboard](../sprints/task-board.md). +> - Depending on the :::image type="icon" source="../media/icons/view-options-icon.png" border="false"::: **View Options** you select, work items in a *Closed* or *Completed* state won't appear on the backlog. +> - The *Removed* state removes a work item from appearing on the backlog. For more information, see [Move, change, or delete work items](../backlogs/remove-delete-work-items.md#remove). > - You can query work items by **State** and other fields to list work in progress, resolved, or completed. For more information, see [Query by assignment or workflow changes](../queries/query-by-workflow-changes.md). - - + ### Assign work -You can only assign a work item to one person at a time. The **Assigned To** field is an identity field designed to hold a user identity that has been added to the project. Within the work item form, choose the **Assigned To** field to select a project member. Or, you can begin entering the name of a project member to quickly focus your search to a select few. +You can assign a work item to only one person at a time. The **Assigned To** field is an identity field designed to hold a user identity added to the project. In the work item form, select the **Assigned To** field to choose a project member, or start typing the name of a project member to quickly narrow your search. :::image type="content" source="media/about-work-items/assigned-to-field.png" alt-text="Screenshot of Assigned To field in the work item form."::: > [!NOTE] -> - You can assign a work item only to users that have been [added to a project or team](../../organizations/security/add-users-team-project.md) -> - You can assign a work item to one and only one user at a time. If work is split across two or more users, consider creating separate work items that you'll assign to each user responsible for the work to complete. -> - Over time, the drop-down menu of identity fields display the names you have most recently selected. -> - You can assign several work items at once from the backlog or query results, see [Bulk modify work items](../backlogs/bulk-modify-work-items.md) for details. -> - To learn more about identity fields, see [Query by assignment or workflow changes](../queries/query-by-workflow-changes.md). +> - You can assign a work item only to users who have been [added to a project or team](../../organizations/security/add-users-team-project.md). +> - You can assign a work item to only one user at a time. If work is split across multiple users, create separate work items for each user responsible for the work. +> - The drop-down menu of identity fields displays the names you have most recently selected over time. +> - You can assign several work items at once from the backlog or query results. See [Bulk modify work items](../backlogs/bulk-modify-work-items.md) for details. +> - For more information about identity fields, see [Query by assignment or workflow changes](../queries/query-by-workflow-changes.md). +When configured with Microsoft Entra ID or Active Directory, Azure DevOps synchronizes identity fields such as **Activated By**, **Assigned To**, **Closed By**, **Created By**, and **Resolved By**. -When configured with Azure Active Directory or Active Directory, Azure DevOps synchronizes identity fields with these directories. Identity fields include **Activated By**, **Assigned To**, **Closed By**, **Created By**, and **Resolved By**. +Grant access to a project by adding security groups created in Microsoft Entra ID or Active Directory. Add accounts to existing or custom groups defined in the collection setting **Security** pages. For more information, see [Add or delete users using Microsoft Entra ID](/azure/active-directory/fundamentals/add-users-azure-active-directory) or [Set up groups for use in Azure DevOps Server deployments](/azure/devops/server/admin/setup-ad-groups). -You can grant access to a project by adding security groups that you created in Azure AD or Active Directory by adding accounts to existing or custom groups defined from the collection setting **Security** pages. For more information, see [Add or delete users using Azure Active Directory](/azure/active-directory/fundamentals/add-users-azure-active-directory) or [Set up groups for use in Azure DevOps Server deployments](/azure/devops/server/admin/setup-ad-groups). - + - +### Use work item templates to quickly complete forms -### Use work item templates to quickly fill in forms - -With work item templates, you can quickly create work items that have prepopulated values for your team's commonly used fields. For example, create a task template that sets the area path, iteration path, and discipline or activity whenever you use it to create a task. For more information, see [Use templates to add and update work items](../backlogs/work-item-template.md). +With work item templates, you can quickly create work items with prepopulated values for commonly used fields. For example, create a task template that sets the area path, iteration path, and discipline or activity whenever you use it to create a task. For more information, see [Use templates to add and update work items](../backlogs/work-item-template.md). ## Follow, Refresh, Revert, and Actions menu @@ -160,14 +182,14 @@ The **Follow**, **Refresh**, **Revert changes**, and **Actions** menu controls a :::column-end::: :::column span="1"::: - Choose **Follow** to get updates when changes are made to the work item. For more information, see [Follow changes made to a user story, bug, or other work item or pull request](follow-work-items.md). - - Choose :::image type="icon" source="../media/icons/icon-refresh-wi.png" border="false"::: **Refresh** to update the work item form with the latest changes that someone else may have made while you had the work item open. + - Choose :::image type="icon" source="../media/icons/icon-refresh-wi.png" border="false"::: **Refresh** to update the work item form with the latest changes that someone else made while you had the work item open. - Choose :::image type="icon" source="../media/icons/icon-undo-changes-wi.png" border="false"::: **Revert changes** to undo any changes you made to the work item form. - To exercise a task available from the **Actions** menu, see the following articles: - [New linked work item](../backlogs/add-link.md) - [Change type](../backlogs/move-change-type.md#change-the-work-item-type) - [Move to team project](../backlogs/move-change-type.md#change-the-work-item-type) - [Create copy of work item...](../backlogs/copy-clone-work-items.md) - - [Email work item](email-work-items.md) + - [Send email with work item](email-work-items.md) - [Delete](../backlogs/remove-delete-work-items.md) - [Templates](../backlogs/work-item-template.md) - [New branch...](../backlogs/connect-work-items-to-git-dev-ops.md) @@ -176,21 +198,18 @@ The **Follow**, **Refresh**, **Revert changes**, and **Actions** menu controls a :::row-end::: > [!NOTE] -> Some menu options may not appear depending on your permission assignments. Also, additional options may appear based on Marketplace extensions added to your organization or other customizations made to the work item type. - +> Some menu options might not appear based on your permission assignments. Additional options might appear due to Marketplace extensions added to your organization or other customizations made to the work item type. ## Discussion control -With the **Discussion** control, project members can add and review comments made about the work being performed. The rich text editor tool bar displays below the text entry area when you select your cursor within each text box. Each comment added is recorded in the **History** field. For more information, see [View and add work items](view-add-work-items.md#capture-comments-in-the-discussion-section). To query the Discussion or History, see [Query work item history and discussion fields](../queries/history-and-auditing.md). +With the **Discussion** control, project members can add and review comments made about the work being performed. The rich text editor tool bar displays below the text entry area when you select your cursor within each text box. Each comment added is recorded in the **History** field. For more information, see [View and add work items](../backlogs/manage-work-items.md#capture-comments-in-the-discussion-section). To query the Discussion or History, see [Query work item history and discussion fields](../queries/history-and-auditing.md). > [!div class="mx-imgBorder"] -> ![Screenshot of Discussion section within a work item form.](../backlogs/media/discussion-section.png) - -::: moniker range=">= azure-devops-2019" +> ![Screenshot of Discussion section within a work item form.](../backlogs/media/discussion-section.png) ## Deployment, Development, and Related Work controls -The **Deployment**, **Development** and **Related Work** controls are special controls available in most work tracking forms. +The **Deployment**, **Development** and **Related Work** controls are special controls available in most work tracking forms. :::row::: :::column span="1"::: @@ -204,28 +223,7 @@ The **Deployment**, **Development** and **Related Work** controls are special co :::column-end::: :::row-end::: - -The **Deployment** control provides a quick view of whether a feature or user story has been deployed and to what stage. You gain visual insight into the status of a work item as it is deployed to different release environments and quick navigation to each release stage and run. For more information, see [Link work items to builds and deployments](work-item-deployments-control.md). - -::: moniker-end - - -::: moniker range="tfs-2018" - -## Development and Related Work controls - -The **Development** and **Related Work** controls are used to support common linking tasks to development objects or other work items. These controls are available in most work items used to track work. The following table provides a short description of each control. - -:::row::: - :::column span="1"::: - ![Screenshot of Development control.](media/about-work-items/development-control.png) - :::column-end::: - :::column span="1"::: - ![Screenshot of Related Work control.](media/about-work-items/related-work-control.png) - :::column-end::: -:::row-end::: - -::: moniker-end +The **Deployment** control provides a quick view of whether a feature or user story is deployed and to what stage. You gain visual insight into the status of a work item as it is deployed to different release environments and quick navigation to each release stage and run. For more information, see [Link work items to deployments](../backlogs/add-link.md#link-work-items-to-deployments). The **Development** control records all Git development processes that support completion of the work item. It also supports traceability, providing visibility into all the branches, commits, pull requests, and builds related to the work item. For more information, see [Drive Git development from a work item ](../backlogs/connect-work-items-to-git-dev-ops.md). @@ -249,7 +247,6 @@ Choose an entry in the left pane to view the details of changes made. For more i :::image type="content" source="../queries/media/hist-audit-wi-form.png" alt-text="Screenshot of Work item form, History tab, Web portal, Details."::: - ### Links: Link work items to other work items or objects @@ -258,18 +255,12 @@ From the :::image type="icon" source="../media/icons/icon-links-tab-wi.png" bord :::image type="content" source="media/about-work-items/links-tab.png" alt-text="Screenshot of Work item form, Links tab."::: -To learn more about linking, see the following articles: - -- [Link user stories, issues, bugs, and other work items](../backlogs/add-link.md) -- [Linking, traceability, and managing dependencies](../queries/link-work-items-support-traceability.md) -- [Link type reference](../queries/link-type-reference.md) +For more information, see the following articles, see [Link work items to other objects](../backlogs/add-link.md) and [Link type reference](../queries/link-type-reference.md). - ### Attachments: Attach files to a work item From the :::image type="icon" source="../media/icons/icon-links-tab-wi.png" border="false"::: **Attachments** tab, you can add, remove, or view files or images added to the work item. You can add up to 100 attachments to a work item. Attachments are limited to 60 MB. For more information, see [Share information within work items and social tools](../queries/share-plans.md). - ## Track work in the web portal @@ -278,8 +269,7 @@ You can add and update work items from the web portal. For an overview of all cl [!INCLUDE [temp](../includes/page-work-item-tasks.md)] - - + ## Work item types to track testing, reviews, and feedback @@ -288,7 +278,7 @@ Along with the work items types that appear on backlogs and boards, there are wo | Category and Work item type | Used to track specified types of work| |-----------------------------|--------------------------------------| |Code Review Request|Tracks a code review request against code maintained in a [Team Foundation version control (TFVC) repository](../../repos/tfvc/index.yml). For more information, see [Day in the life of a Developer: Suspend work, fix a bug, and conduct a code review](../../repos/tfvc/day-life-alm-developer-suspend-work-fix-bug-conduct-code-review.md). | -|Code Review Response|A code review response is created for each person who's requested to provide review comments.| +|Code Review Response|A code review response is created for each person who requested to provide review comments.| |Feedback Request|Feedback requests track requests for feedback generated through the feedback request form. See [Get feedback](/previous-versions/azure/devops/project/feedback/get-feedback).| |Feedback Response|A feedback response is created for each person and for each item for which feedback is provided through the Microsoft Feedback Client. See [Get feedback](/previous-versions/azure/devops/project/feedback/get-feedback).| |Shared Step|Shared steps are used to [repeat tests with different data](../../test/repeat-test-with-different-data.md).| @@ -297,14 +287,13 @@ Along with the work items types that appear on backlogs and boards, there are wo |Test Plan|Test plan group test suites and individual test cases together. Test plans include static test suites, requirement-based suites, and query-based suites.For more information, see [Create test plans and test suites](../../test/create-a-test-plan.md). | |Test Suite|Test suites group test cases into separate testing scenarios within a single test plan. Grouping test cases makes it easier to see which scenarios are complete. See [Create test plans and test suites](../../test/create-a-test-plan.md). | - - + ## Required permissions and access -Members added to the Contributors group of a project can use most features provided under the **Boards** hub. To add users to a project, see [Add users to a project or team](../../organizations/security/add-users-team-project.md). +Members of the Contributors group can use most features under the **Boards** hub. To add users to a project, see [Add users to a project or team](../../organizations/security/add-users-team-project.md). -The following table summarizes the permissions that impact project member's ability to view and edit work items. +The following table summarizes the permissions that affect a project member's ability to view and edit work items. | Level | Permission | |-----|--------| @@ -316,21 +305,19 @@ The following table summarizes the permissions that impact project member's abil |Project | **Delete and restore work items**| |Project | **Permanently delete work items**| -Users with Basic access have full access to all features. Users with Stakeholder access are limited to certain features. To learn more about work tracking permissions and feature access, see [Permissions and access for work tracking](../../organizations/security/permissions-access-work-tracking.md) and [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). - +Users with Basic access have full access to all features. Users with Stakeholder access have limited access to certain features. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md) and [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). ## Next steps > [!div class="nextstepaction"] -> [Add a work item](../backlogs/add-work-items.md?toc=/azure/devops/boards/work-items/toc.json) - +> [Add a work item](view-add-work-items.md) ## Related articles -- [Key concepts and work item tasks in Azure Boards](quick-ref.md) -- [Web portal navigation](../../project/navigation/index.md) -- [Work item form controls](work-item-form-controls.md) -- [Backlogs, portfolios, and Agile project management](../backlogs/backlogs-overview.md) -- [About Kanban and Agile project management](../boards/kanban-overview.md) -- [Agile, Scrum, and CMMI processes](./guidance/choose-process.md) -- [Work item field index](./guidance/work-item-field.md) +- [Learn key concepts and work item tasks in Azure Boards](quick-ref.md) +- [Navigate the web portal](../../project/navigation/index.md) +- [Use work item form controls](about-work-items.md#work-item-form-controls) +- [Explore backlogs, portfolios, and Agile project management](../backlogs/backlogs-overview.md) +- [Understand Kanban and Agile project management](../boards/kanban-overview.md) +- [Choose between Agile, Scrum, and CMMI processes](./guidance/choose-process.md) +- [View the work item field index](./guidance/work-item-field.md) diff --git a/docs/boards/work-items/agile-glossary.md b/docs/boards/work-items/agile-glossary.md index f951620d365..61e781a9808 100644 --- a/docs/boards/work-items/agile-glossary.md +++ b/docs/boards/work-items/agile-glossary.md @@ -3,8 +3,6 @@ title: Learn key concepts & terms to support Agile tools titleSuffix: Azure Boards description: Learn about the key terms and concepts to understand the objects and items used to track work in Azure Boards. ms.service: azure-devops-boards -ms.custom: seodec18 -ms.assetid: ms.topic: conceptual ms.author: chcomley author: chcomley @@ -41,7 +39,7 @@ A family of engineering best processes with a goal of enabling rapid delivery of ## Categories -Groups one or more work item types to support flexible reporting, queries, and other functions made available through Agile tools. Categories support the process configuration used by the web portal backlog and taskboard pages. For example, you can add custom work item types to the Requirements category and manage them using the product backlog and Kanban boards. For more information, see [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types). +Groups one or more work item types to support flexible reporting, queries, and other functions made available through Agile tools. Categories support the process configuration used by the web portal backlog and taskboard pages. For example, you can add custom work item types to the Requirements category and manage them using the product backlog and boards. For more information, see [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types). [!INCLUDE [temp](../../includes/glossary-terms/collections.md)] @@ -92,7 +90,7 @@ The Inheritance process model provides support for customizing work tracking obj **Agile process**: An issue is a type of work item that defines an item that you want to track as it may impact the completion of other work. It's defined for the Agile process and doesn't appear on any backlog or board. See [Manage issues and impediments](../backlogs/manage-issues-impediments.md). -**Basic process**: An issue is a type of work item that defines some work or code defect that needs to be tracked. It's defined for the Basic process and appears on the product backlog and [Issues Kanban board](../get-started/plan-track-work.md). +**Basic process**: An issue is a type of work item that defines some work or code defect that needs to be tracked. It's defined for the Basic process and appears on the product backlog and [Issues board](../get-started/plan-track-work.md). [!INCLUDE [temp](../includes/basic-process-note.md)] [!INCLUDE [temp](../../includes/glossary-terms/iterations.md)] @@ -117,7 +115,7 @@ A picklist specifies an enumerated set of values that appear within a drop-down ## Process configuration -Specifies the default configuration and functional capabilities that your teams can access using the Agile tools. These web portal tools include the product backlog, sprint backlogs, Kanban board, and taskboard. (Only supported for Hosted XML and On-premises XML process models) +Specifies the default configuration and functional capabilities that your teams can access using the Agile tools. These web portal tools include the product backlog, sprint backlogs, board, and taskboard. (Only supported for Hosted XML and On-premises XML process models) ## Process model @@ -162,5 +160,4 @@ A workflow is an integral aspect of a work item. It's defined by its correspondi ## Related articles -- [Refine your backlog](../backlogs/best-practices-product-backlog.md) - [Scrum best practices](../sprints/best-practices-scrum.md) diff --git a/docs/boards/work-items/auto-complete-work-items-pull-requests.md b/docs/boards/work-items/auto-complete-work-items-pull-requests.md index 3a805e08d6d..058fb739305 100644 --- a/docs/boards/work-items/auto-complete-work-items-pull-requests.md +++ b/docs/boards/work-items/auto-complete-work-items-pull-requests.md @@ -7,10 +7,9 @@ ms.custom: cross-service ms.author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 09/09/2024 --- - # Autocomplete work items with pull requests [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -19,12 +18,17 @@ ms.date: 04/01/2022 When you link a work item to a pull request (PR), you can automatically complete those work items when you complete the PR. Or, you can specify the workflow state to transition the work item to upon merging the PR. ::: moniker-end -::: moniker range="< azure-devops-2020" -When you link a work item to a pull request (PR), you can automatically complete those work items when you complete the PR. -::: moniker-end + -To learn more about pull requests, see [Create, view, and manage pull requests](../../repos/git/pull-requests.md). +For more information, see [Create, view, and manage pull requests](../../repos/git/pull-requests.md). +## Prerequisites + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To view, follow, and edit work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has these permissions. For more information, see [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md).
- To add tags to work items: Project-level **Create new tag definition** permission set to **Allow**. By default, the **Contributors** group has this permission. | +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
- To add new tags to work items or to view or follow pull requests: At least [**Basic** access](../../organizations/security/access-levels.md).
- To view or follow work items: At least **Stakeholder** access. For more information, see [About access levels](../../organizations/security/access-levels.md).
- All project members, including those in the **Readers** group, can send emails containing work items. | +|**GitHub permissions**| **Contributor** to the GitHub repository.| ## Autocomplete work items @@ -33,23 +37,21 @@ As shown in the following image, check the box to **Complete linked work items a ::: moniker range=">= azure-devops-2020" :::image type="content" source="media/automate-state-transition/complete-pull-request-dialog.png" alt-text="Complete pull request dialog, Complete linked work items after merging"::: ::: moniker-end -::: moniker range="< azure-devops-2020" -![Complete pull request dialog, Autocomplete work items with completion of PR option](media/workflow-states-complete-pr.png) -::: moniker-end + -In the following circumstances, the system won't automatically update the work item state to Done, Closed, or the state that belongs to the Closed category for the work item type: -- The work item, whose work item type is managed with the Inheritance process model, is already in a State that belongs to the Resolved category. In this instance, the system won't update the State. For example, if a bug derived from the Agile process is in a Resolved state, the system won't transition it to Closed. -- The work item is already in a State that belongs to the Completed category. No further transition is required. -- The WIT associated with the work item contains one or more workflow field rules that prevent the work item being saved to a next state. For example, a rule requires that another field must be defined as part of closing the work item. -- For on-premises deployments and Azure Boards Hosted process model, you must modify the workflow to specify actions (**ACTION** element) to take place when transitioning the workflow. See [Change the workflow for a work item type, Specify Actions](../../reference/xml/change-workflow-wit.md#Actions). +In the following circumstances, the system doesn't automatically update the work item state to **Done**, **Closed**, or **Completed** categories for the work item type (WIT): +- The work item, whose WIT is managed with the Inheritance process model, is already in the **Resolved** state. In this instance, the system doesn't update the State. For example, if a bug derived from the Agile process is in a **Resolved** state, the system doesn't transition it to **Closed**. +- The work item is already in the **Completed** state. No further transition is required. +- The WIT includes workflow field rules that prevent the work item from advancing to the next state. For instance, a rule might require that another field gets defined when closing the work item. +- For on-premises deployments and Azure Boards Hosted process model, you must modify the workflow to specify actions (**ACTION** element) to take place when transitioning the workflow. For more information, see [Change the workflow for a WIT, Specify Actions](../../reference/xml/change-workflow-wit.md#Actions). -To learn more about process models, see [Customize your work tracking experience](../../reference/customize-work.md). +For more information, see [Customize your work tracking experience](../../reference/customize-work.md). ::: moniker range=">= azure-devops-2020" ## Specify the workflow state of linked work items -To transition a work item to a specific workflow state, you can enter the information in the pull request Description. Prefix the **#ID** with a valid workflow state for the work item you mention. +To transition a work item to a specific workflow state, you can enter the information in the pull request description. Prefix the **#ID** with a valid workflow state for the mentioned work item. ::: moniker-end ::: moniker range="azure-devops-2020" @@ -59,12 +61,21 @@ To transition a work item to a specific workflow state, you can enter the inform ::: moniker range=">= azure-devops-2020" -As shown in the following image, two user stories are transitioned, one to **Resolved** and the other to **Review**. Also, two tasks are set to **Done**. +The following example shows user stories that transitioned - one to the **Resolved** state and the other to the **Review** state. Also, two tasks are marked as **Done**. :::image type="content" source="media/automate-state-transition/pull-request-set-workflow-state-to-transition-to.png" alt-text="Screenshot of pull request, set workflow state to transition #ID work items."::: ::: moniker-end +## Disable automatic completion of associated work items + +To disable the automatic completion of associated work items when users complete a pull request, follow these steps: + +1. Go to **Project settings** > **Repositories** > select the repository. +2. In the **Settings** tab, move the toggle to **Off** for **Commit mention work item resolution**. + +Mentions in commit comments to close work items (for example, "Fixes #123") isn't allowed. + ## Related articles - [Create, view, and manage pull requests](../../repos/git/pull-requests.md) diff --git a/docs/boards/work-items/best-tool-add-update-link-work-items.md b/docs/boards/work-items/best-tool-add-update-link-work-items.md deleted file mode 100644 index 2af59859192..00000000000 --- a/docs/boards/work-items/best-tool-add-update-link-work-items.md +++ /dev/null @@ -1,410 +0,0 @@ ---- -title: Find the best tool to add or update stories, bugs, issues, and other work items -titleSuffix: Azure Boards -description: Learn which tool is best to add or update user stories, bugs, issues, and other work items in Azure Boards. -ms.custom: work-items, seodec18 -ms.service: azure-devops-boards -ms.assetid: -ms.topic: best-practice -ms.author: chcomley -monikerRange: '<= azure-devops' -ms.date: 04/01/2022 ---- - - -# Best tool to add, update, and link work items in Azure Boards - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Azure Boards provides you with several tools—many designed to support a single task and others that support several tasks. This article provides a guide to the best tool for specific tasks that help you work most efficiently. - - -## Work item form - -If you want to make a single update to one work item, you can make an update from within the work item form. When you want to add or update several work items at a time, then you'll want to use a backlog or query. - -[Work item form controls](work-item-form-controls.md) | [Work item field index](guidance/work-item-field.md) - -**Best tool for**: -- [Updating a work item field for a single work item](../backlogs/add-work-items.md) -- [Adding to the discussion, mentioning others in the discussion](view-add-work-items.md#capture-comments-in-the-discussion-section) -- [Choosing to follow or unfollow a work item](follow-work-items.md) -- [Driving Git development, creating a branch](../backlogs/connect-work-items-to-git-dev-ops.md) -- [Adding a link to another work item or external object](../backlogs/add-link.md) -- [Copying or cloning a work item](../backlogs/copy-clone-work-items.md) -- [Deleting the work item](../backlogs/remove-delete-work-items.md#delete-work-items) - -**Additional supported tasks**: - -- [Share information](../queries/share-plans.md) -- [Copy the work item URL](../backlogs/copy-clone-work-items.md#copy-the-url) -- [Capturing the work item to use as a template](../backlogs/work-item-template.md#capture) -- [Updating fields of the work item by applying an existing template](../backlogs/work-item-template.md#apply) - -::: moniker range=">= azure-devops-2019" - -## Work Items - -Use the [Work Items](view-add-work-items.md) page to quickly focus on work items of interest to you. - -**Best tool for**: -- Listing and filtering work items of interest to you, specifically work items that meet the following criteria: - - That are assigned to you - - That you chose to follow - - Where you were mentioned - - That you've recently viewed or updated - - That has been recently updated, completed, or created for the project. - -#### Other supported tasks: - -- [Add a work item](view-add-work-items.md) -- [Restore work items from the recycle bin](../backlogs/remove-delete-work-items.md#restore-work-items) -- [View work items through a mobile browser](../..//project/navigation/mobile-work.md) - -::: moniker-end - -## Boards - -The two types of Kanban boards, product backlog and portfolio backlogs, provide the quickest means for adding user stories and portfolio work item types. You can also quickly add and update the status of child items within a hierarchy. As shown in the following image for the Agile process, when you add tasks to user stories, users stories to features, or features to epics, you automatically create parent-child links between the work items. - -> [!div class="mx-imgBorder"] -> ![Agile process, hierarchy of work items types](media/best-tool/agile-process-plan-wits.png) - -[Product backlog board](../boards/kanban-quickstart.md) | [Features or Epics board](../boards/kanban-epics-features-stories.md) | [Customize cards](../boards/customize-cards.md) - -**Best tool for**: -- Viewing the flow of work from start to completion -- Quickly adding [product backlog](../boards/kanban-quickstart.md) and [portfolio backlog](../boards/kanban-epics-features-stories.md) items -- Updating the status of backlog items -- Adding linked child items ([checklists](../boards/add-task-checklists.md), [user stories or features](../boards/kanban-epics-features-stories.md)) -- [Focusing the view based on assignment, tags, or other filter criteria](../backlogs/filter-backlogs-boards-plans.md) -- Adding, running, and updating [inline test cases](../boards/add-run-update-tests.md)) - - -**Additional supported tasks**: -::: moniker range=">= azure-devops-2019" -- [Assigning a work item, updating a field displayed on a card](../boards/kanban-quickstart.md#update-fields-from-the-card) -- [Monitoring cumulative flow](../../report/dashboards/cumulative-flow.md) -- [Monitoring lead time and cycle time control charts](../..//report/dashboards/cycle-time-and-lead-time.md) -::: moniker-end - -::: moniker range="tfs-2018" -- [Assigning a work item, updating a field displayed on a card](../boards/kanban-quickstart.md) -- [Monitoring cumulative flow](../../report/dashboards/cumulative-flow.md) -::: moniker-end - -[!INCLUDE [temp](../includes/setup-backlogs-boards.md)] - -## Backlogs - -You can quickly add and prioritize your product and portfolio backlogs, which list work items either as a flat or hierarchical list. You can also quickly add and reparent child items within a hierarchy. - -[Product backlog](../backlogs/create-your-backlog.md) | [Portfolio backlogs](../backlogs/define-features-epics.md) - -**Best tool for**: -- [Managing your product backlog, developing your project plan](../backlogs/best-practices-product-backlog.md) -- Quickly adding [product](../backlogs/create-your-backlog.md) and [portfolio backlog items](../backlogs/define-features-epics.md) -- [Moving backlog items in priority order](../backlogs/create-your-backlog.md#move-items-priority-order) -- [Creating, viewing, and modifying a hierarchy of backlog items](../backlogs/define-features-epics.md) -- [Organizing your backlog, linking or mapping backlog items to portfolio backlog items](../backlogs/organize-backlog.md) -- [Planning a sprint](../sprints/assign-work-sprint.md) -- [Forecasting work](../sprints/forecast.md) -- [Emailing a list of backlog items](email-work-items.md) -- [Focusing the list based on assignment, tags, or other filter criteria](../backlogs/filter-backlogs-boards-plans.md) - -**Additional supported tasks**: -::: moniker range=">= azure-devops-2019" -- [Bulk modifying work items](../backlogs/bulk-modify-work-items.md) - - [Change work item type](../backlogs/move-change-type.md#change-type) - - [Move work item to a different project](../backlogs/move-change-type.md#move) - - [Assign work items, change the iteration](../backlogs/bulk-modify-work-items.md#assign-to) - - [Add or remove tags](../queries/add-tags-to-work-items.md#bulk-add-or-remove-tags) - - [Delete work items](../backlogs/remove-delete-work-items.md#delete) -- [Creating a Git branch from one or more work items](../backlogs/connect-work-items-to-git-dev-ops.md) -- [Monitoring team velocity](../../report/dashboards/team-velocity.md) -::: moniker-end - -::: moniker range="tfs-2018" -- [Bulk modifying work items](../backlogs/bulk-modify-work-items.md) - - [Assign work items, change the iteration](../backlogs/bulk-modify-work-items.md#assign-to) - - [Delete work items](../backlogs/remove-delete-work-items.md#delete) - - [Add or remove tags](../queries/add-tags-to-work-items.md#bulk-add-or-remove-tags) -- [Creating a Git branch from one or more work items](../backlogs/connect-work-items-to-git-dev-ops.md) -- [Restoring work items from the recycle bin](../backlogs/remove-delete-work-items.md#restore-work-items) -- [Monitoring team velocity](../../report/dashboards/team-velocity.md) -::: moniker-end - -## Sprint tools - -Sprint tools provide teams a focused view of work items they've assigned to a specific sprint. You can add tasks to work items and prioritize your sprint backlog. - -[Sprint backlog](../sprints/add-tasks.md) | [Taskboard](../sprints/task-board.md) | [Capacity](../sprints/set-capacity.md) - -**Best set of tools for**: -- [Implementing Scrum methods](../sprints/best-practices-scrum.md) -- [Adding tasks to backlog items](../sprints/add-tasks.md) -- [Configuring team capacity](../sprints/set-capacity.md) -- [Monitoring and adjusting team capacity](../sprints/adjust-work.md) -- [Updating remaining work, and task status](../sprints/task-board.md) -- [Emailing or sharing a sprint plan](../sprints/share-plan.md) - -**Additional supported tasks**: -- [Monitoring sprint burndown](../../report/dashboards/configure-sprint-burndown.md) -- [Bulk modifying work items](../backlogs/bulk-modify-work-items.md) - - -## Queries - -Queries enable you to filter work items within or across projects for the purposes of listing, updating, or sharing work items. - -- [Queries](../queries/view-run-query.md) | [Query operators](../queries/query-operators-variables.md) - -**Best tool for**: -- [Listing items to run bulk updates, assign, or reassign](../backlogs/bulk-modify-work-items.md) -- Listing a [tree of parent-child related work item](../queries/linking-attachments.md#tree) or [dependent work items](../queries/linking-attachments.md#dependents) -- [Triaging work items (review, set priority, update)](../queries/triage-work-items.md) -- [Creating simple progress and trend charts](../../report/dashboards/charts.md) -- [Emailing a list work items](email-work-items.md) - -**Additional supported tasks**: -- Create a chart and add it to a dashboard -- Create a chart to get a count of items or sum a field -- Create a chart that shows a burndown or burnup over time - -## Plans - -When you want to review the schedule of stories or features your teams plan to deliver, use [Delivery Plans](../plans/review-team-plans.md). Plans show scheduled work items that are assigned to sprints of selected teams against a calendar view. - -**Best tool for**: -- [Viewing product or portfolio work items assigned to several teams against a calendar schedule](../plans/review-team-plans.md) - -**Additional supported tasks**: -- [Moving a work item to a different iteration](../plans/review-team-plans.md) - - -## Office integration tools - -> [!NOTE] -> Starting with Azure DevOps Server 2019 and Visual Studio 2019, the Team Foundation plug-in for Office is deprecating support for Office Project and Storyboarding with PowerPoint. - -Use [**Excel**](../backlogs/office/bulk-add-modify-work-items-excel.md) to complete the following tasks: -- Add or update many work items and their fields -- Add or change hierarchical links between work items. - - - - -## Test tools, test artifacts, and bugs - -Testing tools used several work item types—such as test plans, test suites, test cases, and more. You create and manage them from **Test Plans/Test** or using one or more test tools. Several of these tools also support creating bugs. - - -:::row::: - :::column span="1"::: - **Test tool** - :::column-end::: - :::column span="3"::: - **Best tool for:** - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Test Plans](../../test/create-a-test-plan.md) - :::column-end::: - :::column span="3"::: - - - - [Test Plans and Test Suites](../../test/create-a-test-plan.md) - - [Test Cases](../../test/create-test-cases.md) - - [Test Cases, grid view](../../test/create-test-cases.md#use-the-grid-view-to-edit-test-cases) - - [Shared Steps, Shared Parameters](../../test/repeat-test-with-different-data.md) - - [Delete test artifacts](../backlogs/delete-test-artifacts.md) - - **Additional supported tasks**: - - - - [Track test status](../../test/track-test-status.md) - - [Order manual tests within suites](/previous-versions/azure/devops/2016/jun-01-team-services#ordering-of-tests-in-test-hub) - - [Export test plans and test suites](../../test/reference-qa.yml#testcases) - - [Assign testers to test cases](../../test/user-acceptance-testing.md#assign-and-invite-testers) - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Test Runner](../../test/run-manual-tests.md) - :::column-end::: - :::column span="3"::: - - - - [Running tests, adding bugs](../../test/run-manual-tests.md) - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Test & Feedback extension](../../test/connected-mode-exploratory-testing.md) - :::column-end::: - :::column span="3"::: - - - - [Exploratory testing, capture feedback in connected mode](../../test/connected-mode-exploratory-testing.md) - - [Adding bugs, tasks, and test cases linked to a work item](../../test/explore-workitems-exploratory-testing.md) - - [Requesting feedback](../../test/request-stakeholder-feedback.md) - - [Providing feedback](../../test/provide-stakeholder-feedback.md) - - **Additional supported tasks**: - - - - [Updating existing bugs](../../test/add-to-bugs-exploratory-testing.md) - - [Capture feedback in standalone mode](../../test/standalone-mode-exploratory-testing.md) - - [Capture screen recordings of your app during testing](../../test/run-manual-tests.md) - - :::column-end::: -:::row-end::: - - -## Other tools - - -:::row::: - :::column span="1"::: - **Tool** - :::column-end::: - :::column span="3"::: - **Best tool for:** - :::column-end::: - - - -:::row-end::: - -:::row::: - :::column span="1"::: - [Adhoc search](../queries/search-box-queries.md) - :::column-end::: - :::column span="3"::: - - - - Find a specific work item using its ID or a keyword - - Find one or more work items across all projects in a fast, flexible manner - - Run full text search across all work item fields - - Review work items assigned to a specific team member - - Search against specific work item fields to quickly narrow down a list of work items - - Determine what key words support a managed search - - :::column-end::: -:::row-end::: - -:::row::: - :::column span="1"::: - [Work item templates](../backlogs/work-item-template.md) - :::column-end::: - :::column span="3"::: - - - - Capture templates - - Apply templates to update work items - - Use templates to create work items - - Manage work item templates - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - **Request and capture feedback** - :::column-end::: - :::column span="3"::: - - - - [Request feedback](/previous-versions/azure/devops/project/feedback/get-feedback) - - [Give feedback using Microsoft Feedback Client](/previous-versions/azure/devops/project/feedback/give-feedback) - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - **Notifications** - :::column-end::: - :::column span="3"::: - - - - [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md) - - [Manage team and project notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) - - [Manage organization notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - **Favorites** - :::column-end::: - :::column span="3"::: - - - - [Set personal and team favorites](../../project/navigation/set-favorites.md) - - :::column-end::: -:::row-end::: - -## Marketplace extensions - -Other tools become available when you install one of the [Extensions for Azure DevOps, Boards category](https://marketplace.visualstudio.com/search?target=AzureDevOps&category=Boards&sortBy=Downloads). - -See also [Azure Boards extensions developed by Microsoft](../extensions/index.md). - -## Related articles - -- [Set up your Backlogs and Boards](../backlogs/set-up-your-backlog.md) -- [Navigate in the web portal](../../project/navigation/index.md) -- [Navigate in Team Explorer](../../user-guide/work-team-explorer.md) -- [Why use Azure Boards?](../get-started/why-use-azure-boards.md) diff --git a/docs/boards/work-items/email-work-items.md b/docs/boards/work-items/email-work-items.md index 16f425af9c7..5b186160535 100644 --- a/docs/boards/work-items/email-work-items.md +++ b/docs/boards/work-items/email-work-items.md @@ -1,19 +1,18 @@ --- -title: Email or print user stories and other work items +title: Send an email with work items titleSuffix: Azure Boards -description: Learn how to email or print work items to share information in Azure Boards, Azure DevOps, and Visual Studio Team Explorer. -ms.custom: work-items, contperf-fy23 +description: Learn how to send an email with work items in Azure Boards, Azure DevOps, and Visual Studio Team Explorer. Also learn how to print a list of work items. +ms.custom: work-items, engagement-fy23 ms.service: azure-devops-boards ms.assetid: B2E9B082-15BE-448C-96D8-3EF048A15560 ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 12/16/2022 +ms.date: 09/19/2023 --- - -# Email or print user stories, bugs, and other work items +# Send an email with work items [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-eq-2019.md](../../includes/version-vs-gt-eq-2019.md)] @@ -24,13 +23,14 @@ Using work items to track your work provides a host of benefits, including the a Emailing lists of work items is a common way to share work tracking information. The following table indicates which tasks or features are supported from the web portal and Visual Studio. - > [!NOTE] > The tasks/features listed in the following table aren't available when you're connected to a GitHub or third-party Git repository. Also, they aren't available from Visual Studio under the following conditions: > -> * If you're set to use the default Landing page experience as described in [Set the Work Items experience in Visual Studio 2019](set-work-item-experience-vs.md). -> * If you're set to use the new Git Tool as described in [Git experience in Visual Studio](/visualstudio/ide/git-with-visual-studio). - +> * If you're set to use the new Git Tool as described in [Git experience in Visual Studio](/visualstudio/ide/git-with-visual-studio). + +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](view-add-work-items.md?view=azure-devops&preserve-view=true&tabs=visual-studio#view-work-items) instead of the legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. + --- :::row::: :::column span="2"::: @@ -88,7 +88,7 @@ Emailing lists of work items is a common way to share work tracking information. ✔️ :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="2"::: [Export query result as CSV](#export) @@ -111,18 +111,11 @@ Emailing lists of work items is a common way to share work tracking information. ::: moniker-end +## Prerequisites - -[!INCLUDE [temp](../includes/prerequisites-work-items.md)] - -> [!NOTE] -> Make sure you provide members of your organization [Stakeholder access](../../organizations/security/access-levels.md) who want to contribute to the discussion and review progress. These are typically members who don't contribute to code, but want to view work items, backlogs, Kanban boards, and dashboards. - +[!INCLUDE [temp](../includes/prerequisites-work-items.md)] - - - ## Email a single item @@ -132,22 +125,21 @@ You can quickly email a summary of one or more work items. Summaries include the > [!IMPORTANT] > If you use the built-in email feature, you can only send the email to individual address for a project member that is recognized by the system. Adding a team group or security group to the to line isn't supported. If you add an email account that the system doesn't recognize, you receive a message that one or more recipients of your email don't have permissions to read the mailed work items. - + #### [Web portal](#tab/browser/) -**From the web portal**, open the work item, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon, and select the **Email work item** option. The first 200 items in the list appears in a formatted table. +**From the web portal**, open the work item, choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon, and select the **Email work item** option. The first 200 items in the list appear in a formatted table. > [!div class="mx-imgBorder"] > ![Screenshot of work item form, context menu, Email work items option.](media/email/email-work-item.png) - #### [Visual Studio](#tab/visual-studio/) - + -> [!IMPORTANT] -> To email a summary of work items in Visual Studio 2019, you need to [Set the Work Items experience](../work-items/set-work-item-experience-vs.md) to the legacy option. +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](view-add-work-items.md?view=azure-devops&preserve-view=true&tabs=visual-studio#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. From Visual Studio or Team Explorer, choose ![Send work item to Microsoft Outlook](../queries/media/IC764665.png). This option requires that you configure Office Outlook on your client computer. @@ -155,7 +147,6 @@ From Visual Studio or Team Explorer, choose ![Send work item to Microsoft Outloo * * * - ::: moniker range="< azure-devops" > [!NOTE] @@ -163,24 +154,20 @@ From Visual Studio or Team Explorer, choose ![Send work item to Microsoft Outloo ::: moniker-end - - + - ## Email summary lists with links to items Another way to share items is by emailing summary lists, such as a sprint summary plan or active bugs list. You can share items from a backlog or query results list. Depending on the option and client you choose, summary lists may or may not include a hyperlink to the work item ID. - #### [Web portal](#tab/browser/) **To email items from the web portal**: Open a backlog or query and highlight the items from the list. Open the context menu for one of the selected items and select to email them. - > [!div class="mx-imgBorder"] > ![Screenshot of backlog, context menu, Email... options.](media/email/bulk-email-backlog-items.png) @@ -191,19 +178,17 @@ If you want to mail a list of all items in the backlog or query, choose the ::: #### [Visual Studio](#tab/visual-studio/) - + -> [!NOTE] -> To email a query results list in Visual Studio 2019, you need to [Set the Work Items experience](../work-items/set-work-item-experience-vs.md) to the legacy option. +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](view-add-work-items.md?view=azure-devops&preserve-view=true&tabs=visual-studio#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. **To email items from Visual Studio**: Open a query, highlight the items from the list, choose the context menu, and select **Send selection to Microsoft Outlook** from the menu. This option requires that you configure Office Outlook on your client computer. ![Screenshot of Email selected items from Visual Studio query result list.](../queries/media/share-plans-email-work-item-list.png) - * * * - ## Copy formatted list of work items @@ -224,14 +209,13 @@ With this option, you can copy an HTML formatted table of selected items. You ca ## Print items -To print work item details, open a query in Visual Studio that contains the work item(s) you want to print, and select or highlight those items that you want to print. Then, choose the **Print** option from the context menu. +Open a query in Visual Studio that contains a work item that you want to print, select or highlight those items, and then select the **Print** option from the context menu. -> [!IMPORTANT] -> To print work items in Visual Studio 2019, you need to [Set the Work Items experience](../work-items/set-work-item-experience-vs.md) to the legacy option. +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](view-add-work-items.md?view=azure-devops&preserve-view=true&tabs=visual-studio#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. ![Print work items from Team Explorer](../queries/media/share-plans-print-work-item-details.png) - ## Print work items as cards @@ -239,7 +223,7 @@ To print work item details, open a query in Visual Studio that contains the work Some teams want to work with physical cards when planning or updating their physical Kanban or Scrum task boards. There's no native support for printing work items as cards. However, you may find a solution from the [Azure DevOps Marketplace](https://marketplace.visualstudio.com/search?term=card&target=AzureDevOps&category=Azure%20Boards&sortBy=Relevance). - + ## Copy the URL to a single work item @@ -248,17 +232,16 @@ Some teams want to work with physical cards when planning or updating their phys #### [Web portal](#tab/browser/) - + **From the web portal**, copy the URL from the web browser address or hover over the title and then select the ![Copy to clipboard icon](../backlogs/media/icon-copy-to-clipboard.png) copy-to-clipboard icon. ![Screenshot for Copy hyperlink for a work item from web portal.](../backlogs/media/add-work-item-copy-URL.png) - #### [Visual Studio](#tab/visual-studio/) -> [!NOTE] -> To copy the URL of a work item in Visual Studio 2019, you need to [Set the Work Items experience](../work-items/set-work-item-experience-vs.md) to the legacy option. +> [!IMPORTANT] +> We strongly recommend that everyone use the [default view](view-add-work-items.md?view=azure-devops&preserve-view=true&tabs=visual-studio#view-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. **From Visual Studio**, right-click the work item tab to copy the URL. The URL opens the work item in the web portal. @@ -266,10 +249,9 @@ Some teams want to work with physical cards when planning or updating their phys * * * + - - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Export list as CSV @@ -277,43 +259,30 @@ From any query, you can export a list of work items as a comma-delimited list. O ::: moniker-end -::: moniker range="azure-devops-2019" - -> [!NOTE] -> Requires Azure DevOps Server 2019 Update 1 or later version. - -::: moniker-end - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!div class="mx-imgBorder"] > ![Screenshot that shows how to export a query as CSV.](media/email/export.png) ::: moniker-end - - ## Marketplace extensions You may find other ways to share information by exporting work items to other applications such as Microsoft Word. For more information, review the [Marketplace extensions that support Microsoft Word](https://marketplace.visualstudio.com/search?term=word&target=AzureDevOps&category=Azure%20Boards&sortBy=Relevance). - - ## Related articles ::: moniker range="azure-devops" - [Use templates to add and update work items](../backlogs/work-item-template.md) -- [Share information in work items and social tools](../queries/share-plans.md) -- [Define the hyperlink for a work item](work-item-url-hyperlink.md) +- [Send email with work item](../work-items/email-work-items.md) ::: moniker-end ::: moniker range="< azure-devops" - [Use templates to add and update work items](../backlogs/work-item-template.md) -- [Share information in work items and social tools](../queries/share-plans.md) -- [Define the hyperlink for a work item](work-item-url-hyperlink.md) +- [Send email with work item](../work-items/email-work-items.md) - [Configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts) ::: moniker-end diff --git a/docs/boards/work-items/follow-work-items.md b/docs/boards/work-items/follow-work-items.md index 93b02bcacc2..e783ca2d6b3 100644 --- a/docs/boards/work-items/follow-work-items.md +++ b/docs/boards/work-items/follow-work-items.md @@ -2,7 +2,7 @@ title: Follow changes to work titleSuffix: Azure Boards & Azure Repos description: Learn how to track updates made to a work item or pull request by following it when using Azure Boards or Azure Repos. -ms.custom: work-items, seodec18, cross-project +ms.custom: work-items, cross-project ms.subservice: azure-devops-settings ms.assetid: 77CAEE8E-BF1A-47DA-9818-A0C52BAC813C ms.author: chcomley @@ -27,7 +27,6 @@ If you want to subscribe to receive notifications automatically based on changes > > ![Work item notification templates](media/follow-work/work-item-notifications.png) - This article shows you how to: >[!div class="checklist"] @@ -35,31 +34,11 @@ This article shows you how to: > * Follow a pull request > * Manage work items that you're following -::: moniker range="<= azure-devops-2019" - -[Configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts) for team members to receive notifications. -::: moniker-end - + ## Prerequisites -::: moniker range="azure-devops" - -* Connect to a project. If you don't have a project yet, [create one](../get-started/sign-up-invite-teammates.md). -* You must be added to a project as a member of the **Contributors** or **Project Administrators** security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To view or follow work items, you must be granted **Stakeholder** access or higher. For more information, see [About access levels](../../organizations/security/access-levels.md). Also, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* To view or follow pull requests, you must have **Basic** access or higher. - -::: moniker-end - -::: moniker range="< azure-devops" - -* You must connect to a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -* You must be added to a project as a member of the **Contributors** or **Project Administrators** security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To view or follow work items, you must be granted **Stakeholder** access or higher. For more information, see [About access levels](../../organizations/security/access-levels.md). Also, you must have your **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has this permission set. For more information, see [Set permissions and access for work tracking](../../organizations/security/set-permissions-access-work-tracking.md). -* To view or follow pull requests, you must have **Basic** access or higher. - -::: moniker-end +[!INCLUDE [prerequisites-work-items](../includes/prerequisites-work-items.md)] ## Follow a work item @@ -79,13 +58,6 @@ By default, you're **Subscribed** to receive a notification when any change is m ::: moniker-end -::: moniker range="<= azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Work item form, Follow icon control](media/follow-work/follow-work-item.png) - -::: moniker-end - You'll only receive notifications when other members of your team modify the work item, such as adding to the discussion, changing a field value, or adding an attachment. Notifications are sent to your preferred email address, which [you can change from your user profile](../../organizations/notifications/change-email-address.md) @@ -110,7 +82,7 @@ To stop following changes, open the PR context menu and choose the :::image typ You can review and manage all the work items you've selected to follow. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Open **Boards>Queries**, choose **All**, and under **My Queries**, choose **Followed work items**. @@ -125,7 +97,6 @@ From this view, you can view all items you're following across all projects. Als - Set work item pane - Enter full screen mode. - You can also view and manage work that you're following from **Boards>Work Items** and pivot to **Following**. > [!div class="mx-imgBorder"] @@ -133,24 +104,7 @@ You can also view and manage work that you're following from **Boards>Work Items ::: moniker-end -::: moniker range="tfs-2018" - -Open **Work>Queries** and choose **Followed work items**. - -Followed work items, Follow icon control - -From this view, you can view all items you're following across all projects. Also, you can complete similar actions supported with a query results view, such as: -- Refresh the view -- Add or remove visible columns -- Sort the order of specific columns -- Filter results by text or tags -- Set work item pane -- Enter full screen mode. - -You can also view and manage work that you're following from your Project pages. For more information, see [Work across projects](../../project/navigation/work-across-projects.md). - -::: moniker-end - + ## Query work items that you're following @@ -158,22 +112,18 @@ You can use the **\@Follows** macro in a work item query to filter a list based For example, the following query shows how to query across all projects for active work items that you're following. You use the **ID** field and the **In** operator with the **\@Follows** macro. - :::image type="content" source="media/follow-work/query-follows.png" alt-text="Query Editor, with ID In @Follows query clause"::: - ## Next steps > [!div class="nextstepaction"] > [Add, update, and follow a work item](../backlogs/add-work-items.md) - ## Related articles - [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md) - [View and update work items via the mobile work item form](../../project/navigation/mobile-work.md) - ### Q: Can I add someone else to follow a work item or PR? **A:** No, you can't add another team member to follow a work item or pull request at this time. You can subscribe them to get notified based on select criteria, such as when a work item is create or modified, or a pull request is created. For more information, see [Manage team notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md). diff --git a/docs/boards/work-items/guidance/agile-process-workflow.md b/docs/boards/work-items/guidance/agile-process-workflow.md index 1b9c13c45c4..8f7fedac6f8 100644 --- a/docs/boards/work-items/guidance/agile-process-workflow.md +++ b/docs/boards/work-items/guidance/agile-process-workflow.md @@ -16,7 +16,7 @@ ms.date: 06/01/2023 [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -When you use the Agile process in Azure Boards, the following work item types (WITs) help your team to plan and track progress of your projects: epics, features, user stories, tasks, issues/bugs. Once you define your WITs, you can use the Kanban board to track progress by updating the status of those items. +When you use the Agile process in Azure Boards, the following work item types (WITs) help your team to plan and track progress of your projects: epics, features, user stories, tasks, issues/bugs. Once you define your WITs, you can use the board to track progress by updating the status of those items. :::image type="content" source="../../../organizations/settings/work/media/scrum-to-agile/agile-process-plan-wits.png" alt-text="Conceptual image of Agile process, work item types used to plan and track work."::: @@ -105,7 +105,7 @@ Use the guidance in the following table and the [common fields used across work :::column-end::: :::row-end::: -[!INCLUDE [temp](../../includes/discussion-tip.md)] +[!INCLUDE [temp](../../includes/discussion-tip-azure-devops.md)] ## Track progress @@ -129,13 +129,13 @@ A typical workflow progression for a user story follows: - A user story gets moved to **Resolved** when the team has completed all its associated tasks and unit tests for the story pass. - A user story gets moved to the **Closed** state when the product owner agrees that the story has been implemented according to the Acceptance Criteria and acceptance tests pass. -### Update status with Kanban or Taskboards +### Update status with board or Taskboards -Teams can use the [Kanban board](../../boards/kanban-overview.md) to update the status of requirements, and the [Taskboard](../../sprints/task-board.md) to update the status of tasks. Dragging items to a new state column updates both the State and Reason fields. +Teams can use the [board](../../boards/kanban-overview.md) to update the status of requirements, and the [Taskboard](../../sprints/task-board.md) to update the status of tasks. Dragging items to a new state column updates both the State and Reason fields. -![Screenshot of Track progress on the Kanban board.](../../boards/media/alm-cc-move-card.png) +![Screenshot of Track progress on the board.](../../boards/media/alm-cc-move-card.png) -You can customize the Kanban board to support more [swimlanes](../../boards/expedite-work.md) or [columns](../../boards/add-columns.md). For more information, see [Customize your work tracking experience](#customize-work-item-types). +You can customize the board to support more [swimlanes](../../boards/expedite-work.md) or [columns](../../boards/add-columns.md). For more information, see [Customize your work tracking experience](#customize-work-item-types). ## Map user stories to features diff --git a/docs/boards/work-items/guidance/agile-process.md b/docs/boards/work-items/guidance/agile-process.md index 8741344265a..a4450043a19 100644 --- a/docs/boards/work-items/guidance/agile-process.md +++ b/docs/boards/work-items/guidance/agile-process.md @@ -24,7 +24,7 @@ Along with the WITs, teams have access to a set of work item queries to track in [!INCLUDE [temp](../../includes/process-customize.md)] - + ## Plan and track work with Agile @@ -40,13 +40,7 @@ You can manage your workload more effectively by frequently reviewing the status [!INCLUDE [temp](../../includes/shared-queries.md)] -::: moniker range="tfs-2018" -![Screenshot of Agile work item queries, TFS 2018.](media/IC667910.png) - -[Descriptions of predefined queries](#predefined-queries) are listed later in this article. - -::: moniker-end [!INCLUDE [temp](../../includes/quick-tips-shared-query.md)] @@ -84,188 +78,9 @@ As updates are made to the Agile process template, the version number is updated For a summary of updates made to process templates, see [Release Notes for Azure DevOps Server](/azure/devops/server/release-notes/azuredevops2020u1). - - -::: moniker range="tfs-2018" - -### Agile process predefined queries + -#### Product backlog and feedback queries -Product owners can use the shared queries that are defined in the following table to plan and track user stories that compose the product backlog. - -:::row::: - :::column span="1"::: - Shared query - :::column-end::: - :::column span="3"::: - Description - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Product Backlog - :::column-end::: - :::column span="3"::: - Provides a tree list of all user stories that are in a New, Active or Resolved state and sorts them by rank. - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Product Planning - :::column-end::: - :::column span="3"::: - Provides a flat list of all user stories that aren't in a Removed state, and haven't been closed in the last 90 days. - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Feedback - :::column-end::: - :::column span="3"::: - Lists all feedback responses that are in an Active state. - :::column-end::: -:::row-end::: - -#### Iteration planning queries - -The following table describes the shared queries that are listed under the **Current Iteration** folder. These queries find work items that are assigned to a specified iteration. As you plan more iterations, you can modify these queries to specify a different iteration and then save them to other folders that you create, such as **Iteration 2** or **Iteration 3**. - -The project administrator for each project [defines area and iteration paths](../../../organizations/settings/set-area-paths.md) for that project so that the team can track progress by those designations. - -:::row::: - :::column span="1"::: - **Shared query** - :::column-end::: - :::column span="3"::: - **Description** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Active Bugs - - :::column-end::: - :::column span="3"::: - Lists all active bugs and sorts them by rank, priority, and severity. - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Active Tasks - - :::column-end::: - :::column span="3"::: - Lists all active tasks and sorts them by rank, priority, and severity. - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Bug Triage - - :::column-end::: - :::column span="3"::: - Lists all active bugs that aren't assigned to a team member. - - The [Triage Workbook references](/previous-versions/azure/devops/report/sharepoint-dashboards/workbooks) this query. - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Completed Tasks - - :::column-end::: - :::column span="3"::: - Lists all tasks that have been closed and sorts them by rank, priority, and severity. - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Iteration Backlog - - :::column-end::: - :::column span="3"::: - Lists all user stories and their linked tasks and sorts the stories by rank and priority. - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Open Issues - - :::column-end::: - :::column span="3"::: - Lists all issues under the specified iteration path that aren't closed and any tasks that are linked to the issues and then sorts the issues by rank and priority. - - The [Issues Workbook](/previous-versions/azure/devops/report/sharepoint-dashboards/workbooks) references this query. - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Open Test Cases - - :::column-end::: - :::column span="3"::: - Lists all test cases that aren't closed and sorts them by priority. - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Open User Stories - - :::column-end::: - :::column span="3"::: - Lists all active user stories and sorts them by their stack rank. - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Resolved Bugs - - :::column-end::: - :::column span="3"::: - Lists all resolved bugs and sorts them by rank, priority, and severity. - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - User Stories - - :::column-end::: - :::column span="3"::: - Lists all user stories that aren't closed and sorts them by priority and then ID, - - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - User Stories without Test Cases - - :::column-end::: - :::column span="3"::: - Lists all user stories that don't have a link to a test case. Stories are sorted by ID. - - :::column-end::: -:::row-end::: - -> [!TIP] -> Queries listed under the **Current Iteration** folder do not automatically update when a new iteration becomes current. The current iteration is based on the dates that you [assign to your sprint schedules](../../sprints/define-sprints.md). You must manually update the iteration path of each query to have it point to the iteration path that corresponds to the current iteration. Or, you can edit the shared query to [use the **@CurrentIteration** macro](../../queries/query-by-date-or-current-iteration.md). - -#### Find tasks with summary values - -The **Work Items With Summary Values** shared query, which is located in the **Troubleshooting** folder, lists all tasks that have child tasks and that contain nonzero values in the Remaining Work or Completed Work fields. This query is designed to find tasks that report work effort that is already accounted for in their child tasks. For the hours to be counted only once, summary tasks shouldn't be assigned any hours. For more information, see [Address inaccuracies published for summary values](../../../report/sql-reports/address-inaccuracies-published-for-summary-values.md). - -::: moniker-end ## Related articles [!INCLUDE [temp](../../includes/create-team-project-links.md)] diff --git a/docs/boards/work-items/guidance/choose-process.md b/docs/boards/work-items/guidance/choose-process.md index deae05359b6..807944d27e0 100644 --- a/docs/boards/work-items/guidance/choose-process.md +++ b/docs/boards/work-items/guidance/choose-process.md @@ -1,7 +1,7 @@ --- -title: About default processes and process templates +title: Default processes and process templates titleSuffix: Azure Boards -description: Learn about choosing a process or process template based on the process model you use in your Azure Boards project. +description: Learn about choosing a process or process template based on the process model you use in your Azure Boards project. ms.custom: work-items ms.service: azure-devops-boards ms.assetid: 702EE9E5-7AEA-49B6-9DB0-B12A882979C8 @@ -9,168 +9,156 @@ ms.topic: overview ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 05/02/2023 +ms.date: 10/11/2024 +#customer intent: As a team leader, I want to understand the processes that Azure Boards uses to manage work items for my project. --- - -# About default processes and process templates +# Default processes and process templates [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -Azure Boards offers various processes to choose from for managing work items. Selecting the right process is essential for optimizing the workflow and ensuring the success of a project. In this article, we explore the different processes available Azure Boards and provide guidance on how to choose the most suitable one for your project. - -[!INCLUDE [temp](../../../includes/choose-process-introduction.md)] +Azure Boards offers various processes for managing work items. Selecting the right process helps optimize project workflow and ensure your project's success. In this article, explore the different processes available with Azure Boards. This article provides guidance on how to choose the most suitable process for your project. -[!INCLUDE [temp](../../includes/note-configure-customize.md)] +[!INCLUDE [process terms](../../../includes/choose-process-introduction.md)] -The work tracking objects contained within the default processes and process templates—Basic, Agile, Capability Maturity Model Integration (CMMI), and Scrum—are the same and summarized in this article. +The default process types are *Basic*, *Agile*, *Capability Maturity Model Integration (CMMI)*, and *Scrum*. The work tracking objects in the default processes and process templates are the same. They're summarized in this article. -[!INCLUDE [temp](../../includes/get-latest-process-templates.md)] +[!INCLUDE [process templates](../../includes/get-latest-process-templates.md)] ## Default processes -The default processes differ mainly in the work item types (WITs) they provide for planning and tracking work. +The default processes differ mainly in the work item types they provide for planning and tracking work. The default processes are: -**Basic** is the most lightweight and is in a selective Preview. -**Scrum** is the next most lightweight. **Agile** supports many Agile method terms, and **CMMI** provides the most support for formal processes and change management. +- **Basic**: Is the most lightweight and is in a selective preview. +- **Scrum**: Is the next most lightweight. +- **Agile**: Supports many Agile method terms. +- **CMMI**: Provides the most support for formal processes and change management. [!INCLUDE [temp](../../includes/note-basic-process.md)] :::row::: :::column span="2"::: - + **Basic** - Choose [Basic](../../get-started/plan-track-work.md) when your team wants the simplest model that uses Issues, Tasks, and Epics to track work. + Choose [Basic](../../get-started/plan-track-work.md) when your team wants the simplest model that uses Issue, Task, and Epic work item types to track work. - Tasks support tracking Remaining Work. + Tasks support tracking Remaining Work. :::column-end::: :::column span="2"::: - - ![Basic work item types](../../get-started/media/about-boards/basic-process-epics-issues-tasks-2.png) + + :::image type="content" source="../../get-started/media/about-boards/basic-process-epics-issues-tasks-2.png" alt-text="Diagram shows Basic work item types in a hierarchy."::: :::column-end::: :::row-end::: --- :::row::: :::column span="2"::: - + **Agile** - Choose [Agile](agile-process.md) when your team uses Agile planning methods, including Scrum, - and tracks development and test activities separately. This process works great if you want to track user stories and (optionally) bugs on the Kanban board, or track bugs and tasks on the taskboard. + Choose [Agile](agile-process.md) when your team uses Agile planning methods, including Scrum, and tracks development and test activities separately. This process works great for tracking User Stories and, optionally, bugs on the board. You can also track bugs and tasks on the taskboard. + + For more information about Agile methodologies, see [Agile Alliance](https://www.agilealliance.org/). - You can learn more about Agile methodologies at the - [Agile Alliance](https://www.agilealliance.org/). - - Tasks support tracking Original Estimate, Remaining Work, and Completed Work. + Tasks support tracking Original Estimate, Remaining Work, and Completed Work. :::column-end::: :::column span="2"::: - - ![Agile work item types](media/ALM_PT_Agile_WIT_Artifacts.png) + + :::image type="content" source="media/ALM_PT_Agile_WIT_Artifacts.png" alt-text="Diagram shows Agile work item types in a hierarchy."::: :::column-end::: :::row-end::: --- :::row::: :::column span="2"::: - + **Scrum** - - Choose [Scrum](scrum-process.md) when your team practices Scrum. This process works great for tracking product backlog items (PBIs) and bugs on the Kanban board. You can also break down PBIs and bugs into tasks on the taskboard. - + Choose [Scrum](scrum-process.md) when your team practices Scrum. This process works great for tracking product backlog items and bugs on the board. You can also break down product backlog items and bugs into tasks on the taskboard. + This process supports the Scrum methodology as defined by the [Scrum organization](https://www.scrum.org/). - Tasks support tracking remaining work only. + Tasks support tracking Remaining Work only. :::column-end::: :::column span="2"::: - - ![Scrum work item types](media/ALM_PT_Scrum_WIT_Artifacts.png) + + :::image type="content" source="media/ALM_PT_Scrum_WIT_Artifacts.png" alt-text="Diagram shows Scrum work item types in a hierarchy."::: :::column-end::: :::row-end::: --- -:::row::: +:::row::: :::column span="2"::: - + **CMMI** - Choose [CMMI](cmmi-process.md) when your team follows more formal project methods - that require a framework for process improvement and an auditable record of decisions. With this process, - you can track requirements, change requests, risks, and reviews. - - - This process supports [formal change management activities](./cmmi/guidance-background-to-cmmi.md). - Tasks support tracking Original Estimate, Remaining Work, and Completed Work. - + Choose [CMMI](cmmi-process.md) when your team follows more formal project methods that require a framework for process improvement and an auditable record of decisions. With this process, you can track requirements, change requests, risks, and reviews. + + This process supports [formal change management activities](./cmmi/guidance-background-to-cmmi.md). Tasks support tracking Original Estimate, Remaining Work, and Completed Work. + :::column-end::: :::column span="2"::: - - ![CMMI work item types](media/ALM_PT_CMMI_WIT_Artifacts.png) + + :::image type="content" source="media/ALM_PT_CMMI_WIT_Artifacts.png" alt-text="Screenshot shows CMMI work item types in a hierarchy."::: :::column-end::: :::row-end::: --- -If you need more than two or three backlog levels, you can add more based on the process model you use: -- **Inheritance**: [Customize your backlogs or boards for a process](../../../organizations/settings/work/customize-process-backlogs-boards.md) -- **Hosted XML or On-premises XML**: [Add portfolio backlogs](../../../reference/add-portfolio-backlogs.md) - +If you need more than two or three backlog levels, add more based on the process model that you use: + +- **Inheritance**: [Customize your backlogs or boards for a process](../../../organizations/settings/work/customize-process-backlogs-boards.md) +- **Hosted XML or On-premises XML**: [Add portfolio backlogs](../../../reference/add-portfolio-backlogs.md) + ## Main distinctions among the default processes -The default processes are designed to meet the needs of most teams. -If your team has unusual needs and connects to an on-premises server, -you can customize a process, and then create the project. -Or, you can create a project from a process and then customize the project. +The default processes are designed to meet the needs of most teams. If your team has unusual needs and connects to an on-premises server, customize a process and then create the project. You can also create a project from a process and then customize the project. -The following table summarizes the main distinctions between the WITs and states used by the four default processes. +The following table summarizes the main distinctions between the work item types and states used by the four default processes. :::row::: :::column span="1"::: - Tracking area + **Tracking area** :::column-end::: :::column span="1"::: - Basic + **Basic** :::column-end::: :::column span="1"::: - Agile + **Agile** :::column-end::: :::column span="1"::: - Scrum + **Scrum** :::column-end::: :::column span="1"::: - CMMI + **CMMI** :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - + Workflow states :::column-end::: :::column span="1"::: - - + - To Do - Doing - Done - + :::column-end::: :::column span="1"::: - - + - New - Active - Resolved - Closed - Removed - + :::column-end::: :::column span="1"::: - - + - New - Approved - Committed @@ -178,391 +166,358 @@ The following table summarizes the main distinctions between the WITs and states - Removed :::column-end::: :::column span="1"::: - - + - Proposed - Active - Resolved - Closed - + :::column-end::: :::row-end::: :::row::: :::column span="1"::: - - Product planning (see note 1) + + Product planning (see Note 1) :::column-end::: :::column span="1"::: - - + - Issue - + :::column-end::: :::column span="1"::: - - - - User story + + - User Story - Bug (optional) - + :::column-end::: :::column span="1"::: - - + - Product backlog item - Bug (optional) - + :::column-end::: :::column span="1"::: - - + - Requirement - Bug (optional) - + :::column-end::: :::row-end::: :::row::: :::column span="1"::: - - Portfolio backlogs (2) + + Portfolio backlogs (see Note 2) :::column-end::: :::column span="1"::: - - + - Epic - + :::column-end::: :::column span="1"::: - - + - Epic - Feature - + :::column-end::: :::column span="1"::: - - + - Epic - Feature - + :::column-end::: :::column span="1"::: - - + - Epic - Feature - + :::column-end::: :::row-end::: :::row::: :::column span="1"::: - - Task and sprint planning (3) + + Task and sprint planning (see Note 3) :::column-end::: :::column span="1"::: - - + - Task - + :::column-end::: :::column span="1"::: - - + - Task - Bug (optional) - + :::column-end::: :::column span="1"::: - - + - Task - Bug (optional) - - + :::column-end::: :::column span="1"::: - - + - Task - Bug (optional) - + :::column-end::: :::row-end::: :::row::: :::column span="1"::: - - Bug backlog management (1) + + Bug backlog management (see Note 1) :::column-end::: :::column span="1"::: - - + - Issue - + :::column-end::: :::column span="1"::: - - + - Bug - + :::column-end::: :::column span="1"::: - - + - Bug - + :::column-end::: :::column span="1"::: - - + - Bug - + :::column-end::: :::row-end::: :::row::: :::column span="1"::: - - Issue and risk management + + Issue and risk management :::column-end::: :::column span="1"::: - - + - Issue - + :::column-end::: :::column span="1"::: - - + - Issue - + :::column-end::: :::column span="1"::: - - + - Impediment - + :::column-end::: :::column span="1"::: - - + - Issue - Risk - Review - + :::column-end::: :::row-end::: --- -> [!NOTE] -> 1. You can add these WITs from the [product backlog](../../backlogs/create-your-backlog.md) or [Kanban board](../../boards/kanban-overview.md). The product backlog shows a single view of the current backlog of work that can be dynamically re-ordered and grouped. Product owners can quickly prioritize work and outline dependencies and relationships. -> Also, each team can configure how they want [bugs to show up on their backlogs and boards](../../../organizations/settings/show-bugs-on-backlog.md). -> 2. With portfolio backlogs you can define a hierarchy of backlogs to understand the scope of work across several teams and see how that work rolls up into broader initiatives. Each team can configure which [portfolio backlogs appear for their use](../../../organizations/settings/select-backlog-navigation-levels.md). -> 3. You can define tasks from the [sprint backlog and taskboard](../../sprints/assign-work-sprint.md). -With capacity planning, teams can quickly determine if they are over or under capacity for a sprint. +Notes: + +1. Add work items from the [product backlog](../../backlogs/create-your-backlog.md) or [board](../../boards/kanban-overview.md). The product backlog shows a single view of the current backlog of work that can be dynamically reordered and grouped. Product owners can prioritize work and outline dependencies and relationships. Each team can configure how they want [bugs to show up on their backlogs and boards](../../../organizations/settings/show-bugs-on-backlog.md). +1. Define a hierarchy of portfolio backlogs to understand the scope of work across several teams and see how that work rolls up into broader initiatives. Each team configures which [portfolio backlogs appear for their use](../../../organizations/settings/select-backlog-navigation-levels.md). +1. Define tasks from the [sprint backlog and taskboard](../../sprints/assign-work-sprint.md). With capacity planning, teams can determine if they're over capacity or under capacity for a sprint. ### Workflow states, transitions, and reasons -Workflow states support tracking the status of work as it moves from a new state to a closed or a done state. Each workflow consists of a set of states, the valid transitions between the states, and the reasons for transitioning the work item to the selected state. +Workflow states support tracking the status of work as it moves from a `New` state to a `Closed` or a `Done` state. Each workflow consists of a set of states, the valid transitions between the states, and the reasons for transitioning the work item to the selected state. + +> [!IMPORTANT] +> For Azure DevOps Services and Azure DevOps Server 2019, the default workflow transitions support any state to any state transition. Customize these workflows to restrict some transitions. For more information, see [Customize your work tracking experience](../../../reference/customize-work.md). +> +> View the supported workflow transitions for each work item type by installing the [State Model Visualization](https://marketplace.visualstudio.com/items?itemName=taavi-koosaar.StateModelVisualization) Marketplace extension. This extension adds a new hub under **Boards** labeled **State Visualizer**. On that page, choose a work item type and view the workflow state model. -> [!IMPORTANT] -> For Azure DevOps Services and Azure DevOps Server 2019, the default workflow transitions support any state to any state transition. You can customize these workflows to restrict some transitions .See [Customize work tracking objects to support your team's processes](../../../reference/customize-work.md). -> -> Also, you can view the supported workflow transitions for each work item type by installing the [State Model Visualization](https://marketplace.visualstudio.com/items?itemName=taavi-koosaar.StateModelVisualization) Markeplace extension. This extension adds a new hub under Boards labeled **State Visualizer**. On that page you can choose a work item type and view the workflow state model. +The following diagrams show the typical forward progression of those work item types used to track work and code defects for the three default processes. They also show some of the regressions to former states and transitions to removed states. -The following diagrams show the typical forward progression of -those WITs used to track work and code defects for the three default processes. -They also show some of the regressions to former states and transitions to removed states. -Each image shows only the default reason associated with the transition. +Each image shows only the default reason associated with the transition. -#### [Agile process](#tab/agile-process) +#### [Agile process](#tab/agile-process) :::row::: :::column span="1"::: - - #### User story - ![User story workflow states, Agile process](media/ALM_PT_Agile_WF_UserStory.png) + + #### User Story + :::image type="content" source="media/ALM_PT_Agile_WF_UserStory.png" alt-text="Diagram that shows User Story workflow states by using the Agile process."::: :::column-end::: :::column span="1"::: - + #### Feature - ![Feature workflow states, Agile process](media/ALM_PT_Agile_WF_Feature.png) + :::image type="content" source="media/ALM_PT_Agile_WF_Feature.png" alt-text="Diagram that shows Feature workflow states by using the Agile process."::: :::column-end::: :::column span="1"::: - + #### Epic - ![Epic workflow states, Agile process](media/ALM_PT_Agile_WF_Epic.png) + :::image type="content" source="media/ALM_PT_Agile_WF_Epic.png" alt-text="Diagram that shows Epic workflow states by using the Agile process."::: :::column-end::: :::row-end::: :::row::: :::column span="1"::: - + #### Bug - ![Bug workflow states, Agile process](media/ALM_PT_Agile_WF_Bug.png) + :::image type="content" source="media/ALM_PT_Agile_WF_Bug.png" alt-text="Diagram that shows Bug workflow states by using the Agile process."::: :::column-end::: :::column span="1"::: - + #### Task - ![Task workflow states, Agile process](media/ALM_PT_Agile_WF_Task.png) + :::image type="content" source="media/ALM_PT_Agile_WF_Task.png" alt-text="Diagram that shows Task workflow states by using the Agile process."::: :::column-end::: :::column span="1"::: - + :::column-end::: :::row-end::: +#### [Basic process](#tab/basic-process) -#### [Basic process](#tab/basic-process) - -> [!NOTE] -> The Basic process is available when you create a new project from Azure DevOps Services or [Azure DevOps Server 2019.1](https://go.microsoft.com/fwlink/?LinkId=2097609). For earlier on-premises deployments, choose Agile, Scrum, or CMMI process. - +> [!NOTE] +> The Basic process is available when you create a new project from Azure DevOps Services or [Azure DevOps Server 2019.1](https://go.microsoft.com/fwlink/?LinkId=2097609). For earlier on-premises deployments, choose the Agile, Scrum, or CMMI process. :::row::: :::column span="1"::: - - #### Epic, Issue, Task hierarchy - ![Basic process work item hierarchy](../../get-started/media/track-issues/basic-process-epics-issues-tasks.png) + + #### Epic, Issue, and Task hierarchy + :::image type="content" source="../../get-started/media/track-issues/basic-process-epics-issues-tasks.png" alt-text="Diagram that shows the Basic process work item hierarchy."::: :::column-end::: :::column span="1"::: - - #### Epic, Issue, Task workflow - ![Basic process workflow](../../get-started/media/track-issues/basic-process-workflow.png) + + #### Epic, Issue, and Task workflow + :::image type="content" source="../../get-started/media/track-issues/basic-process-workflow.png" alt-text="Diagram that shows the Basic process workflow."::: :::column-end::: :::column span="1"::: - + :::column-end::: :::row-end::: - -#### [Scrum process](#tab/scrum-process) +#### [Scrum process](#tab/scrum-process) :::row::: :::column span="1"::: - + #### Product backlog item - ![Screenshot of product backlog item workflow states, Scrum process.](media/alm-pt-scrum-wf-pbi.png) + :::image type="content" source="media/alm-pt-scrum-wf-pbi.png" alt-text="Diagram that shows Product backlog item workflow states by using the Scrum process."::: :::column-end::: :::column span="1"::: - + #### Feature - ![Feature workflow states, Scrum process](media/ALM_PT_Scrum_WF_Feature.png) + :::image type="content" source="media/ALM_PT_Scrum_WF_Feature.png" alt-text="Diagram that shows Feature workflow states by using the Scrum process."::: :::column-end::: :::column span="1"::: - + #### Epic - ![Epic workflow states, Scrum process](media/ALM_PT_Scrum_WF_Epic.png) + :::image type="content" source="media/ALM_PT_Scrum_WF_Epic.png" alt-text="Diagram that shows Epic workflow states by using the Scrum process."::: :::column-end::: :::row-end::: :::row::: :::column span="1"::: - + #### Bug - ![Screenshot of bug workflow states, Scrum process.](media/alm-pt-scrum-wf-bug.png) + :::image type="content" source="media/alm-pt-scrum-wf-bug.png" alt-text="Diagram that shows Bug workflow states by using the Scrum process."::: :::column-end::: :::column span="1"::: - + #### Task - ![Screenshot of task workflow states, Scrum process.](media/alm-pt-scrum-wf-task.png) + :::image type="content" source="media/alm-pt-scrum-wf-task.png" alt-text="Diagram that shows Task workflow states by using the Scrum process."::: :::column-end::: :::column span="1"::: - + :::column-end::: :::row-end::: - -#### [CMMI process](#tab/cmmi-process) +#### [CMMI process](#tab/cmmi-process) :::row::: :::column span="1"::: - + #### Requirement - ![Requirement workflow states, CMMI process](media/ALM_PT_CMMI_WF_Requirement.png) + :::image type="content" source="media/ALM_PT_CMMI_WF_Requirement.png" alt-text="Diagram that shows Requirement workflow states by using the CMMI process."::: :::column-end::: :::column span="1"::: - + #### Feature - ![Feature workflow states, CMMI process](media/ALM_PT_CMMI_WF_Feature.png) + :::image type="content" source="media/ALM_PT_CMMI_WF_Feature.png" alt-text="Diagram that shows Feature workflow states by using the CMMI process."::: :::column-end::: :::column span="1"::: - + #### Epic - ![Epic workflow states, CMMI process](media/ALM_PT_CMMI_WF_Epic.png) + :::image type="content" source="media/ALM_PT_CMMI_WF_Epic.png" alt-text="Diagram that shows Epic workflow states by using the CMMI process."::: :::column-end::: :::row-end::: :::row::: :::column span="1"::: - + #### Bug - ![Bug workflow states, CMMI process](media/ALM_PT_CMMI_WF_Bug.png) + :::image type="content" source="media/ALM_PT_CMMI_WF_Bug.png" alt-text="Diagram that shows Bug workflow states by using the CMMI process."::: :::column-end::: :::column span="1"::: - + #### Task - ![Task workflow states, CMMI process](media/ALM_PT_CMMI_WF_Task.png) + :::image type="content" source="media/ALM_PT_CMMI_WF_Task.png" alt-text="Diagram that shows Task workflow states by using the CMMI process."::: :::column-end::: :::column span="1"::: - + :::column-end::: :::row-end::: - * * * -Most WITs used by Agile tools, ones that appear on backlogs and boards, support any-to-any transitions. You can update the status of a work item using the Kanban board or the taskboard by dragging it to its corresponding state column. +Most work item types used by Agile tools, the ones that appear on backlogs and boards, support any-to-any transitions. Update the status of a work item by using the board or the taskboard. Drag a work item to its corresponding state column. -You can change the workflow to support other states, transitions, and reasons. For more information, see [Customize your work tracking experience](../../../reference/customize-work.md). +Change the workflow to support other states, transitions, and reasons. For more information, see [Customize your work tracking experience](../../../reference/customize-work.md). ### Work item states -When you change the state of a work item to `Removed`, `Closed`, or `Done`, the system responds as follows: +When you change the state of a work item to `Removed`, `Closed`, or `Done`, the system responds as follows: -* **`Closed`** / **`Done`**: Work items in this state don't appear on the portfolio backlog and backlog pages. However, they do appear on the sprint backlog pages, Kanban board, and taskboard. Also, when you change the portfolio backlog view to show backlog items, for example, to view Features to Product Backlog Items, work items in the closed and done state appear. -* **`Removed`**: Work items in this state don't appear on any backlog or board. +- `Closed` or `Done`: Work items in this state don't appear on the portfolio backlog and backlog pages. They do appear on the sprint backlog pages, board, and taskboard. When you change the portfolio backlog view to **Show backlog items**, for example, to view features to product backlog items, work items in the `Closed` and `Done` state appear. +- `Removed`: Work items in this state don't appear on any backlog or board. -Your project maintains work items as long as the project is active. Even if you set work items to `Closed`, `Done`, or `Removed`, the data store keeps a record. You can use a record to create queries or reports. +Your project maintains work items as long as the project is active. Even if you set work items to `Closed`, `Done`, or `Removed`, the data store keeps a record. Use a record to create queries or reports. -[!INCLUDE [temp](../../includes/note-closed-items.md)] +[!INCLUDE [closed items](../../includes/note-closed-items.md)] If you need to permanently delete work items, see [Remove or delete work items](../../backlogs/remove-delete-work-items.md). - -## WITs added to all processes +## Work item types added to all processes -The following WITs are added to all processes except the Basic process. +The following work item types are added to all processes except the Basic process. - ![Work item types used by Test Plans, Microsoft Test Managers, My Work, and Feedback](media/ALM_PT_WITS_shared.png) +:::image type="content" source="media/ALM_PT_WITS_shared.png" alt-text="Diagram that shows work item types used by Test Plans, Microsoft Test Managers, My Work, and Feedback."::: -Your team can create and work with these types using the corresponding tool: +Your team can create and work with these types by using the corresponding tool. -|Tool |Work item types | -|---------|---------| -|Microsoft Test Manager | `Test Plan`, `Test Suite`, `Test Case Shared Steps`, `Shared Parameters` | -|Request Feedback | `Feedback Request`, `Feedback Response` | -|My Work (from Team Explorer), Code Review | `Code Review Request`, `Code Review Response` | +| Tool | Work item types | +|:---------|:---------| +| Microsoft Test Manager | `Test Plan`, `Test Suite`, `Test Case Shared Steps`, `Shared Parameters` | +| Request Feedback | `Feedback Request`, `Feedback Response` | +| My Work (from Team Explorer), Code Review | `Code Review Request`, `Code Review Response` | -Work items from these type definitions aren't meant to be created manually and are then added to the `Hidden Types` category. -Work item types added to the `Hidden Types` category don't appear in the menus that create new work items. +Work items from these type definitions aren't meant to be created manually and are then added to the `Hidden Types` category. Work item types added to the `Hidden Types` category don't appear on the menus that create new work items. -### WITs that support the test experience +### Work item types that support the test experience -WITs that support the test experience and work with Test Manager and the web portal are linked together using the link types shown in the following picture. +Work item types that support the test experience and work with Test Manager and the web portal are linked together by using the link types shown in the following image. -![Test management work item types](media/ALM_PT_WITS_TestExperience.png) +:::image type="content" source="media/ALM_PT_WITS_TestExperience.png" alt-text="Diagram that shows test management work item types."::: -From the web portal or Microsoft Test Manager, you can view which test cases are defined for a test suite and view which test suites are defined for a test plan. However, these objects aren't connected to each other through link types. Customize these WITs as you would any other WIT. For more information, see [Customize work tracking objects to support your team's processes](../../../reference/customize-work.md). +From the web portal or Microsoft Test Manager, view which test cases are defined for a test suite and view which test suites are defined for a test plan. However, these objects aren't connected to each other through link types. Customize these work item types as you would any other work item types. For more information, see [Customize your work tracking experience](../../../reference/customize-work.md). -If you change the workflow for the test plan and test suite, you might need to update the process configuration as described here. For definitions of each test field, see [Query based on build and test integration fields](../../queries/build-test-integration.md). +If you change the workflow for the test plan and test suite, you might need to update the process configuration as described here. For definitions of each test field, see [Create a query based on build and test integration fields](../../queries/build-test-integration.md). ## Related articles -- [Customize your work tracking experience](../../../reference/customize-work.md). -- [Upload/download process templates](manage-process-templates.md) -- [Configure features after an Azure DevOps Server upgrade](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) -- [Azure DevOps support page](https://azure.microsoft.com/support/devops/) +- [Customize your work tracking experience](../../../reference/customize-work.md) +- [Upload and download process templates](manage-process-templates.md) diff --git a/docs/boards/work-items/guidance/cmmi-process-workflow.md b/docs/boards/work-items/guidance/cmmi-process-workflow.md index 02b63ce5923..74516dffbb0 100644 --- a/docs/boards/work-items/guidance/cmmi-process-workflow.md +++ b/docs/boards/work-items/guidance/cmmi-process-workflow.md @@ -12,13 +12,11 @@ monikerRange: '<= azure-devops' ms.date: 01/04/2023 --- - # CMMI process work item types and workflow in Azure Boards - [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -Teams use the work item types (WITs) provided with the MSF for CMMI Process Improvement 2015 (CMMI) process to plan and track progress of software projects. Teams define requirements to manage the backlog of work and then, using the Kanban board, track progress by updating the status of requirements. +Teams use the work item types (WITs) provided with the MSF for CMMI Process Improvement 2015 (CMMI) process to plan and track progress of software projects. Teams define requirements to manage the backlog of work and then, using your board, track progress by updating the status of requirements. ![Conceptual image of CMMI process work item types.](media/cmmi-process-plan-wits.png) @@ -35,22 +33,16 @@ Create requirements from the quick add panel on the [product backlog page](../.. :::image type="content" source="../media/about-work-items/work-item-form-requirement.png" alt-text="Screenshot of Requirement work item form."::: -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" Or, you can bulk add requirements using a [cvs file](../../queries/import-work-items-from-csv.md). ::: moniker-end -::: moniker range="<= azure-devops-2019" -Or, you can bulk add requirements using [Excel](../../backlogs/office//bulk-add-modify-work-items-excel.md) or [Project](/previous-versions/azure/devops/boards/backlogs/office/create-your-backlog-tasks-using-project). -::: moniker-end - - [!INCLUDE [temp](../../includes/deprecate-project.md)] Requirements specify the functions and product elements that teams need to create. Product owners typically define and stack rank requirements on the product backlog page. The team then scopes the size of the effort to deliver the highest priority items. Use the following guidance and that provided for [fields used in common across work item types](#definitions-in-common) when filling out the form. For more information, see [Plan a project](cmmi/guidance-plan-a-project-cmmi.md). - :::row::: :::column span="1"::: **Field** @@ -140,7 +132,7 @@ Use the following guidance and that provided for [fields used in common across w :::column span="3"::: Estimate the amount of work required to complete a requirement using any numeric unit of measurement your team prefers. - By defining the **Size** for requirements, teams can use the Agile [velocity charts](../../../report/dashboards/team-velocity.md) and [forecast](../../sprints/forecast.md) tools to estimate future iterations or work efforts. The Kanban [Cumulative Flow Diagram](../../boards/kanban-overview.md) references the values in this field. For more information, see the [Estimating](/previous-versions/visualstudio/visual-studio-2013/hh765979(v=vs.120)) white paper. + By defining the **Size** for requirements, teams can use the Agile [velocity charts](../../../report/dashboards/team-velocity.md) and [forecast](../../sprints/forecast.md) tools to estimate future iterations or work efforts. The [Cumulative Flow Diagram](../../boards/kanban-overview.md) references the values in this field. For more information, see the [Estimating](/previous-versions/visualstudio/visual-studio-2013/hh765979(v=vs.120)) white paper. :::column-end::: :::row-end::: @@ -272,7 +264,7 @@ Use the following guidance and that provided for [fields used in common across w :::row-end::: --- -[!INCLUDE [temp](../../includes/discussion-tip.md)] +[!INCLUDE [temp](../../includes/discussion-tip-azure-devops.md)] ## Track work progress @@ -295,13 +287,13 @@ The typical workflow progression for a requirement is: - The team updates the status to **Resolved** when code development is finished and system tests have passed. - Lastly, the team or product owner moves the requirement to **Closed** when the product owner agrees that it has been implemented according to the Acceptance Criteria and passed all validation tests. -### Update work status with Kanban or Taskboards +### Update work status with a board or Taskboards -Teams can use the [Kanban board](../../boards/kanban-overview.md) to update the status of requirements, and the [sprint taskboard](../../sprints/task-board.md) to update the status of tasks. Dragging items to a new state column updates both the State and Reason fields. +Teams can use the [board](../../boards/kanban-overview.md) to update the status of requirements, and the [sprint taskboard](../../sprints/task-board.md) to update the status of tasks. Dragging items to a new state column updates both the State and Reason fields. -:::image type="content" source="../../boards/media/alm-cc-move-card.png" alt-text="Screenshot of web portal, track progress on the Kanban board."::: +:::image type="content" source="../../boards/media/alm-cc-move-card.png" alt-text="Screenshot of web portal, track progress on the board."::: -You can customize the Kanban board to support more [swim lanes](../../boards/expedite-work.md) or [columns](../../boards/add-columns.md). For more customization options, see [Customize your work tracking experience](#customize-work-tracking). +You can customize the board to support more [swim lanes](../../boards/expedite-work.md) or [columns](../../boards/add-columns.md). ## Map requirements to features @@ -311,7 +303,6 @@ Using portfolio backlogs, you can [drill down from one backlog to another](../.. The feature work item contains similar fields provided for requirements and includes other fields, as the following table describes. - ## Define tasks When your team manages their work in sprints, they can use the [sprint backlog page](../../sprints/assign-work-sprint.md) to break down the work to be accomplished into distinct tasks. @@ -410,7 +401,6 @@ When teams estimate work, they define tasks and estimate the hours or days to co :::column-end::: :::row-end::: - ## Track test progress ### Test requirements @@ -429,7 +419,6 @@ The :::image type="icon" source="../../backlogs/media/icon-links-tab-wi.png" bor You can [create bugs from the web portal web portal, Visual Studio, or when testing with Test Manager](../../backlogs/manage-bugs.md). - ## Track change requests, risks, issues, and notes captured in review meetings Along with the requirement, feature, task, and bug WITs, you can track information recommended by the CMMI process with the following WITS. @@ -445,7 +434,6 @@ You can add an issue from the [New work item widget](../../../report/dashboards Work items you add from the widget are automatically scoped to your team's default area and iteration paths. To change the team context, see [Switch team context](../../../project/navigation/go-to-project-repo.md?toc=/azure/devops/boards/plans/toc.json). - [!INCLUDE [temp](../../includes/common-work-item-fields.md)] ## Customize work item types @@ -456,7 +444,6 @@ Work items you add from the widget are automatically scoped to your team's defau [!INCLUDE [temp](../../includes/create-team-project-links.md)] - ### Backlog list order The [Stack Rank](../../queries/planning-ranking-priorities.md) field is used to track the relative ranking of requirements, features, or epics. However, by default it doesn't appear on the work item form. The sequence of items on the backlog page is determined according to where you've [added the items or moved the items on the page](../../backlogs/create-your-backlog.md#move-items-priority-order). As you drag items, a background process updates this field. diff --git a/docs/boards/work-items/guidance/cmmi-process.md b/docs/boards/work-items/guidance/cmmi-process.md index 6dd0aadaed4..ce6fb0f0876 100644 --- a/docs/boards/work-items/guidance/cmmi-process.md +++ b/docs/boards/work-items/guidance/cmmi-process.md @@ -9,25 +9,22 @@ ms.topic: conceptual ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 09/10/2024 --- - # Understand CMMI process template artifacts - [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -The CMMI process supports the following work item types (WITs) to plan and track work, tests, feedback, and code review. With different WITs you can track different types of work—such as requirements, change requests, tasks, bugs and more. These artifacts are created when you create a project using the CMMI process. They're based on the [Capability Maturity Model Integration (CMMI)](./cmmi/guidance-background-to-cmmi.md) process. +The Capability Maturity Model Integration (CMMI) process supports various work item types (WITs) to plan and track work, tests, feedback, and code reviews. Different WITs allow you to track various types of work, such as requirements, change requests, tasks, bugs, and more. These artifacts get created when you set up a project using the CMMI process, based on the [Capability Maturity Model Integration (CMMI)](./cmmi/guidance-background-to-cmmi.md) framework. :::image type="content" source="media/cmmi-process-work-tracking-wits.png" alt-text="Conceptual image, CMMI process work item types."::: - -Along with the WITs, teams have access to a set of work item queries to track information, analyze progress, and make decisions. +Teams can use a set of work item queries to track information, analyze progress, and make decisions. [!INCLUDE [temp](../../includes/process-customize.md)] - + ## Plan and track work with CMMI @@ -43,17 +40,6 @@ You can use work item queries to list work items based on their type, such as ch [!INCLUDE [temp](../../includes/shared-queries.md)] - -::: moniker range="tfs-2018" - -Or, use one of the shared queries that the CMMI process provides. - -![Screenshot of CMMI shared queries.](media/IC667909.png) - -[Descriptions of predefined queries](#predefined-queries) are listed later in this article. - -::: moniker-end - [!INCLUDE [temp](../../includes/quick-tips-shared-query.md)] ## Monitor progress @@ -64,24 +50,16 @@ All processes—Agile, Scrum, and CMMI—support ## SQL Server reports - -If your project collection and the project are configured with SQL Server Analysis Services and Reporting Services, you'll have access to many CMMI reports. For these reports to be useful, [teams must do certain activities](/previous-versions/azure/devops/report/admin/review-team-activities-for-useful-reports), such as define build processes, link work items, and update status or remaining work. +If your project collection and the project are configured with SQL Server Analysis Services and Reporting Services, you have access to many CMMI reports. For these reports to be useful, [teams must do certain activities](/previous-versions/azure/devops/report/admin/review-team-activities-for-useful-reports), such as define build processes, link work items, and update status or remaining work. If you need to add reporting services or update reports to the latest versions, see [Add reports to a project](/previous-versions/azure/devops/report/admin/add-reports-to-a-team-project). ::: moniker-end - - -## Related notes - -[!INCLUDE [temp](../../includes/create-team-project-links.md)] - ### CMMI process versions @@ -92,98 +70,25 @@ As updates are made to the CMMI process template, the version number is updated. > |-------------|-------------------|--------------| > | Azure DevOps Services
Azure DevOps Server 2022 | CMMI | 18 | > | Azure DevOps Server 2020
Azure DevOps Server 2019 | CMMI | 17 | -> | TFS 2018 | CMMI | 16 | For a summary of updates made to process templates, see [Release Notes for Azure DevOps Server](/azure/devops/server/release-notes/azuredevops2020u1). +### Use the CMMI process effectively -### More CMMI guidance - -The situations and working practices of development teams vary widely, and most companies have their own well-established processes. For these reasons, the guidance given here doesn't attempt to prescribe a development process in full. Instead, we describe just the activities that are relevant to making best use of the CMMI process. - -- [Background to CMMI](cmmi/guidance-background-to-cmmi.md): Provides an overview of CMMI and the six capability levels that are intrinsic to the model. - -- [Project management](/previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-project-management): Provides guidance to help you better understand how to manage, plan, and coordinate the development and maintenance of software products working with the CMMI model. - -- [Engineering](cmmi/guidance-engineering.md): Addresses the value-added activities for discovering the information that is required to design and build software products - -Using the CMMI template and guidance can help you achieve the aims of CMMI if you use it as part of a process improvement program. Adapt this guidance to your own situation, which depends on the type and history of the product that you're developing, the project's scale, the background of the team members, and accepted practices in your organization. +Development teams have diverse practices and established processes. This guidance focuses on activities relevant to effectively using the CMMI process. - This guidance was developed in partnership with David Anderson. For more information, see the following Web page: [David J Anderson & Associates](https://djaa.com/). +- [Learn about CMMI](cmmi/guidance-background-to-cmmi.md): Understand CMMI and its six capability levels. +- [Manage projects](/previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-project-management): Get guidance on managing, planning, and coordinating software development and maintenance with the CMMI model. +- [Explore engineering activities](cmmi/guidance-engineering.md): Discover value-added activities for designing and building software products. +Use the CMMI template and guidance as part of a process improvement program. Adapt this guidance based on: +- Product type and history +- Project scale +- Team members' backgrounds +- Accepted practices in your organization - + -::: moniker range="tfs-2018" +## Related articles -### CMMI process predefined queries - -#### Query for items assigned to you - -You can find the work items that are assigned to you by using one of the shared queries that the following table describes. - -> [!div class="mx-tdCol2BreakAll"] -> | Shared query | Description | -> |---|---| -> | My Test Cases | Lists all test cases that are not closed and that are assigned to the team member who is running the query. Test cases are sorted by priority and then ID. | -> | My Work Items | Lists all work items, excluding shared steps, that are not closed and that are assigned to the team member who is running the query. Work items are sorted by rank, priority, type, and ID. | - -#### Development and test queries - -Team members can use the shared queries that are described in the following table to track the status of development and test tasks and active and resolved bugs. - -> [!div class="mx-tdCol2BreakAll"] -> | Shared query | Description | -> |---|---| -> | Active Bugs | Lists all active bugs and sorts them by rank, priority, and severity. | -> | Development Tasks | Lists all tasks whose **Discipline** is set to **Development**. Tasks are sorted by ID. | -> | My Test Cases | Lists all test cases that are not closed and that are assigned to the team member who is running the query. Test cases are sorted by priority and then ID. | -> | Open Tasks | Lists all tasks that are not closed, sorted by rank, priority, and then ID. | -> | Open Test Cases | Lists all test cases that are not closed, sorted by priority and then ID. | -> | Resolved Bugs | Lists all resolved bugs that are defined for the project, sorted by rank, priority, and severity. | -> | Test Tasks | Lists all tasks whose **Discipline** is set to **Test**, sorted by ID. | - -#### Backlog management queries - -Product owners can use the shared queries that are described in the following table to track the status of requirements and untriaged work. - -> [!div class="mx-tdCol2BreakAll"] -> | Shared query | Description | -> |---|---| -> | Customer Requirements | Lists all requirements, sorted by ID, that have been identified as Scenario or Quality of Service work items. | -> | Product Requirements | Lists all requirements, sorted by ID, that have been identified as Functional, Operational, Security, Safety, or a Feature. | -> | Open Requirements | Lists all requirements that are not closed, sorted by iteration ID, priority, and then work item ID. | -> | Open Requirements without Test Cases | Lists all requirements that are not closed and that do not have a Tested By link to a test case, sorted by work item ID. | -> | Open Work Items | Lists all work items except shared steps that are not closed. Work items are sorted by rank, priority, type, and then ID. | -> | Proposed Work Items | Lists all proposed work items, sorted by rank, priority, iteration, area, triage, and then work item ID. | -> | Reviews | Lists all reviews, sorted by work item ID. | -> | Untriaged Work Items | Lists all requirements, tasks, change requests, bugs, and issues that have not been closed or triaged. The Triage field for these work items is set to Pending, More Info, or Info Received.

Work items are sorted by state, triage, rank, priority, iteration, and area. | -> | Work Breakdown | Lists all requirements that are not closed and their child requirements or tasks. | -> | Work Items With Summary Values | Lists all tasks that have child tasks and that contain non-zero values for the Remaining Work or Completed Work fields. This query is designed to find tasks that report work effort that is already accounted for in their child tasks. For the hours to be counted only once, summary tasks should not be assigned any hours.

For more information, see [Address inaccuracies published for summary values](../../../report/sql-reports/address-inaccuracies-published-for-summary-values.md). | - -#### Change management queries - -Product owners can use the shared queries that are described in the following table to track change requests and dependencies that have been identified between change requests and requirements. - -> [!div class="mx-tdCol2BreakAll"] -> | Shared query | Description | -> |---|---| -> | Change Requests | Lists all change requests, sorted by ID. | -> | Open Change Requests with Requirements | Lists change requests that are not closed and their linked requirements, sorted by ID. Only change requests that are linked to a requirement with a link type of Affects appears in the list. | -> | Requirements with Open Change Requests | Lists requirements and the change requests that are not closed and that depend on them, sorted by ID. Only requirements that are linked to a change request with a link type of Affected By are listed. | - -#### Troubleshooting queries - -Product owners can use the shared queries that are described in the following table to troubleshoot issues and risks to the product schedule. - -> [!div class="mx-tdCol2BreakAll"] -> | Shared query | Lists | -> |---|---| -> | Blocked Work Items | Lists all work items where the **Blocked** field is set to **Yes**.

Only requirements, tasks, bugs, issues, and change requests can be blocked. | -> | Corrective Action Status | Lists all tasks whose **Task Type** is set to **Corrective Action**. | -> | Mitigation Actions | Lists all tasks whose **Task Type** is set to **Mitigation Action**. | -> | Open Issues | Lists all issues that are not closed.

The [Issues workbook](/previous-versions/azure/devops/report/sharepoint-dashboards/workbooks) references this query. | -> | Risks | Lists all risks, sorted by ID. | - -::: moniker-end - \ No newline at end of file +[!INCLUDE [temp](../../includes/create-team-project-links.md)] diff --git a/docs/boards/work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md b/docs/boards/work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md index d222382561b..fd7ec6b38a2 100644 --- a/docs/boards/work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md +++ b/docs/boards/work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md @@ -17,7 +17,7 @@ ms.date: 01/20/2017 The following fields track information about bugs, issues, and risks. These work item types are defined within the process template for the [CMMI process](../cmmi-process.md). - + ## Bug tracking fields diff --git a/docs/boards/work-items/guidance/guidance-code-review-feedback-field-reference.md b/docs/boards/work-items/guidance/guidance-code-review-feedback-field-reference.md index efc594f4a05..f21a66bd308 100644 --- a/docs/boards/work-items/guidance/guidance-code-review-feedback-field-reference.md +++ b/docs/boards/work-items/guidance/guidance-code-review-feedback-field-reference.md @@ -17,15 +17,10 @@ ms.date: 11/07/2021 You can use the code review and feedback fields to create queries and reports that track the status of these processes. The fields appear in the following work item types, which are included with the default processes for Azure Boards and TFS: Code Review Request, Code Review Response, Feedback Request, and Feedback Response. -::: moniker range="tfs-2018" -> [!NOTE] -> If your on-premises server has been upgraded from an earlier version, you might need to update your project to get access to these work item types. See [Configure features after an upgrade](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade). - -::: moniker-end - + ## Fields used to track code reviews diff --git a/docs/boards/work-items/guidance/manage-process-templates.md b/docs/boards/work-items/guidance/manage-process-templates.md index ec33779b220..698dc2edf93 100644 --- a/docs/boards/work-items/guidance/manage-process-templates.md +++ b/docs/boards/work-items/guidance/manage-process-templates.md @@ -12,33 +12,28 @@ monikerRange: '<= azure-devops' ms.date: 01/05/2023 --- - # Upload or download a process template [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -When you create a project, a process is used to specify the work item types to configure and other settings. Each process template primarily defines the building blocks of the work item tracking system for Azure Boards. For the Hosted XML and On-premises XML process models, you can upload a process template to either update an existing project or create a project. For the Inheritance process model, you customize work tracking through the web portal. To learn more about these different processes, see [Customize your work tracking experience](../../../reference/customize-work.md). +When you create a project, a process is used to specify the work item types to configure and other settings. Each process template primarily defines the building blocks of the work item tracking system for Azure Boards. For the Hosted XML and On-premises XML process models, you can upload a process template to either update an existing project or create a project. For the Inheritance process model, you customize work tracking through the web portal. For more information about these different processes, see [Customize your work tracking experience](../../../reference/customize-work.md). -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!IMPORTANT] > Uploading and downloading Inherited processes isn't supported. To manage Inherited processes, see [About process customization and inherited processes](../../../organizations/settings/work/inheritance-process-model.md). @@ -46,7 +41,6 @@ To manage process templates, you must be a member of the **Project Collection Ad [!INCLUDE [temp](../../../organizations/settings/includes/open-process-admin-context-ts.md)] ::: moniker-end - ::: moniker range="azure-devops" ## Import a process template (Hosted XML process) @@ -82,7 +76,7 @@ To manage process templates, you must be a member of the **Project Collection Ad > [!div class="mx-imgBorder"] > ![Screenshot of Import process actions menu, Create new team project from imported process.](../../../organizations/settings/work/import-process/media/import-process-new-team-project.png) -5. Complete the form that appears. To learn more about the different options, see [Create a project](../../../organizations/projects/create-project.md). +5. Complete the form that appears. For more information about the different options, see [Create a project](../../../organizations/projects/create-project.md). > [!div class="mx-imgBorder"] > ![Dialog for Create new project.](../../../organizations/settings/work/import-process/media/create-project-from-hosted.png) @@ -91,7 +85,7 @@ For other Hosted XML process management tasks, see [Import and export a Hosted X ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="Team Project Collection Settings>Process Template Manager** bar menu. - - > [!div class="mx-imgBorder"] - > ![Screenshot that shows Open Process Template Manager from Visual Studio 2015.](media/open-process-template-manager.png) - - You'll see a list of each process template that has been uploaded to the project collection. - - ![Process Template Manager dialog, Select process template to work with.](media/process-template-manager.png) - - > [!TIP] - > For a comparison of the default process templates--Agile, CMMI, and Scrum--see [About processes and process templates](choose-process.md). - The **Upload**, **Download**, **Make Default**, and **Delete** buttons are disabled when you don't have the necessary permissions to manage process templates. - -3. Select the process template that you want to work with and then choose from the following actions. - - |**Choose this task** | **To perform this operation** | - |---------------------|-------------------------------| - |**Upload**|To upload a process template.
In the **Upload Process Template** dialog box, choose the folder that contains the root file, ProcessTemplate.xml, for the process template that you want to upload. See also [Process template restrictions and validation checks](#restrictions). | - |**Download** | To download the process template to a local computer.
In the **Download Process Template** dialog box, select a folder where the process template gets downloaded.

If you're downloading a process template to use to [configure new features](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade), [manually add new features](/previous-versions/azure/devops/reference/upgrade/add-features-manually) or [update a custom process template to enable new features](/previous-versions/azure/devops/reference/upgrade/additional-configuration-options)--choose the process that corresponds to the one you used previously to create your project. For example, if you're updating a project based on the Scrum process template, then select **Scrum**. All version numbers have been removed from the process templates. If you don't see Agile, CMMI, or Scrum, then you need to [update TFS](https://visualstudio.microsoft.com/downloads/download-visual-studio-vs).

You can determine which process template to select based on the [work item types defined for your existing project](#wit_correlation). | - |**Make Default**| To cause the selected process template to appear as the default selection in the **New Team Project Wizard**. | - |**Delete** |To permanently remove the selected process template from the collection. | - - -::: moniker-end - - - ## Correlate a process template with an existing project To determine the type of process template that was used to create your project, review the work item types that appear in the New Work Item menu for Team Explorer and then compare them with the work item types in the following chart. If your work item types differ from those items shown, then a custom process template might have been used. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" | **Agile**| **Basic**| **CMMI**| **Scrum**| |-----------|-----------|-----------|-----------| @@ -163,16 +125,6 @@ To determine the type of process template that was used to create your project, ::: moniker-end -::: moniker range="tfs-2018" - - -| **Agile**| **CMMI**| **Scrum**| -|-----------|-----------|-----------|-----------| -| ![Agile work item types](media/ALM_MPT_WIT_Agile.png) | ![CMMI work item types](media/ALM_MPT_WIT_CMMI.png) | ![Scrum work item types](media/ALM_MPT_WIT_Scrum.png) | - -::: moniker-end - - ## Process template restrictions and validation checks diff --git a/docs/boards/work-items/guidance/scrum-process-workflow.md b/docs/boards/work-items/guidance/scrum-process-workflow.md index 8643e8eacf3..9a498e72bbb 100644 --- a/docs/boards/work-items/guidance/scrum-process-workflow.md +++ b/docs/boards/work-items/guidance/scrum-process-workflow.md @@ -93,7 +93,7 @@ Use the following fields and [fields used in common across work item types](#def :::column-end::: :::row-end::: -[!INCLUDE [temp](../../includes/discussion-tip.md)] +[!INCLUDE [temp](../../includes/discussion-tip-azure-devops.md)] ## Track progress @@ -118,13 +118,13 @@ PBIs and bugs follow this typical workflow progression: - The team updates the status to **Committed** when they decide to commit to working on it during the sprint - The item gets moved to the **Done** state when the team has completed all its associated tasks and the product owner agrees that it has been implemented according to the Acceptance Criteria. -### Update status with Kanban or Taskboards +### Update status with board or Taskboards -Teams can use the [Kanban board](../../boards/kanban-overview.md) to update the status of PBIs, and the [sprint Taskboard](../../sprints/task-board.md) to update the status of tasks. Dragging items to a new state column updates both the State and Reason fields. +Teams can use the [board](../../boards/kanban-overview.md) to update the status of PBIs, and the [sprint Taskboard](../../sprints/task-board.md) to update the status of tasks. Dragging items to a new state column updates both the State and Reason fields. -:::image type="content" source="../../boards/media/alm-cc-move-card.png" alt-text="Screenshot of track progress on the Kanban board."::: +:::image type="content" source="../../boards/media/alm-cc-move-card.png" alt-text="Screenshot of track progress on the board."::: -You can customize the Kanban board to support more [swim lanes](../../boards/expedite-work.md) or [columns](../../boards/add-columns.md). For other customization options, see [Customize your work tracking experience](#customize-work-tracking). +You can customize the board to support more [swim lanes](../../boards/expedite-work.md) or [columns](../../boards/add-columns.md). For other customization options, see [Customize your work tracking experience](#customize-work-tracking). ## Map PBIs to features diff --git a/docs/boards/work-items/guidance/scrum-process.md b/docs/boards/work-items/guidance/scrum-process.md index 1c9dd09c9f7..5a2569b88b9 100644 --- a/docs/boards/work-items/guidance/scrum-process.md +++ b/docs/boards/work-items/guidance/scrum-process.md @@ -24,7 +24,7 @@ Along with the WITs, teams have access to a set of work item queries to track in [!INCLUDE [temp](../../includes/process-customize.md)] - + ## Plan and track work with Scrum processes @@ -42,18 +42,7 @@ Define work item queries to list work items for a current sprint or the product [!INCLUDE [temp](../../includes/shared-queries.md)] -::: moniker range="tfs-2018" -Or, use the shared queries that the Scrum process provides. - -:::image type="content" source="media/IC665405.png" alt-text="Screenshot of Shared queries for the Scrum process."::: - -You can find [descriptions of predefined queries](#predefined-queries) later in this article. - -> [!TIP] -> Queries listed under the **Current Iteration** folder don't automatically update when a new iteration becomes current. The current iteration is based on the dates that you [assign to your sprint schedules](../../sprints/define-sprints.md). You must manually update the iteration path of each query to have it point to the iteration path that corresponds to the current iteration. Or, you can edit the shared query to [use the **@CurrentIteration** macro](../../queries/query-by-date-or-current-iteration.md). - -::: moniker-end [!INCLUDE [temp](../../includes/quick-tips-shared-query.md)] @@ -91,29 +80,9 @@ As updates get made to the Scrum process template, the version number gets updat For a summary of updates made to process templates, see [Release Notes for Azure DevOps Server](/azure/devops/server/release-notes/azuredevops2020u1). - - -::: moniker range="tfs-2018" + -### Scrum process predefined queries -Your product owner can plan and track product backlog items and bugs in the product backlog by using the **Product Backlog** query. You can find work items that are assigned to the current sprint by using the shared queries that are listed under the **Current Sprint** folder. These queries find work items that are assigned to a specified iteration or sprint. As you plan more sprints, you can modify these queries to specify the latest sprint and save them to other folders that you create, such as **Sprint 2** or **Sprint 3**. - -The project administrator for each project [defines area paths](../../../organizations/settings/set-area-paths.md) and [iteration paths](../../../organizations/settings/set-iteration-paths-sprints.md) for that project so that the team can track progress by those designations. - -> [!div class="mx-tdCol2BreakAll"] -> |Shared queries|Description| -> |---|---| -> |Blocked Tasks | Lists all tasks in the current sprint that have been marked as Blocked.| -> |Open Impediments |Lists all open impediment work items in the current sprint.| -> |Sprint Backlog |Lists all product backlog items, bugs, and their linked tasks that your team has committed to complete in the current sprint.| -> |Test Cases |Lists all test cases in the current sprint and sorts them by priority.| -> |Unfinished Work |Lists all product backlog items, bugs, and their linked tasks that have not been marked as Done in the current sprint.| -> |Work in Progress |Lists all tasks in the current sprint that are marked as In Progress.| -> |Feedback | Lists all feedback responses that are in an Active state. | -> |Product Backlog |Lists all product backlog items and bugs that are assigned to the root iteration. Product backlog items and bugs are sorted by backlog priority.| - -::: moniker-end ## Related articles diff --git a/docs/boards/work-items/guidance/work-item-field.md b/docs/boards/work-items/guidance/work-item-field.md index 01bc2c84030..836eb0b0b09 100644 --- a/docs/boards/work-items/guidance/work-item-field.md +++ b/docs/boards/work-items/guidance/work-item-field.md @@ -9,41 +9,29 @@ ms.topic: conceptual ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 01/17/2023 +ms.date: 08/19/2024 --- # Field descriptions for default and work item fields used in process templates [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -Use this index to look up a description of each field used to track work items. This reference includes all fields defined within the core system processes/process templates: [Basic](../../get-started/plan-track-work.md), [Agile](agile-process.md), [Scrum](scrum-process.md), and [CMMI](cmmi-process.md). The fields and work item types (WITs) available to you depend on the process you chose when you [created your project](../../../organizations/projects/create-project.md). +Use this index to find descriptions of each field used to track work items. This reference covers all fields defined within the core system processes/templates: [Basic](../../get-started/plan-track-work.md), [Agile](agile-process.md), [Scrum](scrum-process.md), and [CMMI](cmmi-process.md). The fields and work item types (WITs) available to you depend on the process you selected when you [created your project](../../../organizations/projects/create-project.md). ::: moniker range="azure-devops" -To support other tracking needs, you can [define your own custom work item fields](../../../organizations/settings/work/customize-process.md). +To support other tracking needs, [define your own custom work item fields](../../../organizations/settings/work/customize-process.md). ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - -To support other tracking needs, you can [define your own custom work item fields](../../../organizations/settings/work/customize-process.md) using the Inheritance process model, or if your project collection is configured to use the On-premises XML process model, then see [Modify or add a custom field](../../../reference/add-modify-field.md). - -::: moniker-end - -::: moniker range="tfs-2018" - -To support other tracking needs, you can [modify or add a custom field](../../../reference/add-modify-field.md). +::: moniker range=" [!NOTE] > The [Analytics Service](../../../report/powerbi/what-is-analytics.md) doesn't support reporting on plain text and HTML fields. -::: moniker-end - ## Alphabetical index Values in parenthesis indicate the following criteria: @@ -52,8 +40,7 @@ Values in parenthesis indicate the following criteria: - **Agile**: Used only by the [Agile process](agile-process.md) - **CMMI**: Used only by the [CMMI process](cmmi-process.md) - **Scrum**: Used only by the [Scrum process](scrum-process.md) -- **TCM**: Used to support Test case management - +- **TCM**: Used to support test case management :::row::: :::column span="1"::: @@ -79,7 +66,7 @@ Values in parenthesis indicate the following criteria: - [Associated Context Type](guidance-code-review-feedback-field-reference.md#fields) - [Attached File Count](../../queries/linking-attachments.md#fields) - Authorized As (Not used) - - [Automated Test Id](../../queries/build-test-integration.md#fields) (TCM) + - [Automated Test ID](../../queries/build-test-integration.md#fields) (TCM) - [Automated Test Name](../../queries/build-test-integration.md#fields) (TCM) - [Automated Test Storage](../../queries/build-test-integration.md#fields) (TCM) - [Automated Test Type](../../queries/build-test-integration.md#fields) (TCM) @@ -243,12 +230,11 @@ Values in parenthesis indicate the following criteria: > 1. This field is available from Azure DevOps Services and Azure DevOps Server 2020 and later versions. > 2. This field is available for Azure DevOps Services only. -By using the system fields or other fields you've added to your project collection, you can enable meaningful cross-project reports and queries. Also, any non-system field that is referenced in the workflow or forms section of the work item type definition must have a **FIELD** element that defines it in the **FIELDS** section of the work item type definition XML file. Also, you must specify any non-system field that you might want to use to generate a query or report in the **FIELDS** section. - +Use system fields or custom fields added to your project collection to enable meaningful cross-project reports and queries. Any nonsystem field referenced in the workflow or forms section of the work item type definition must have a **FIELD** element defined in the **FIELDS** section of the work item type definition XML file. Specify any nonsystem field you want to use for generating queries or reports in the **FIELDS** section. ## Field reference articles -The following articles describe fields that are used in common by several WITs, or those fields that are functionally specific to just one or a few WITs. +The following articles describe fields that are commonly used by several WITs or are functionally specific to one or a few WITs. For more information, see [Work item field and attributes in Azure Boards](../work-item-fields.md). ### Fields common to many work types @@ -278,27 +264,25 @@ The following articles describe fields that are used in common by several WITs, - [Issues](cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md#fields) - [Review Meetings](/previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-review-meeting-field-reference-cmmi#fields) - [Risks](cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md#fields) - ## Related articles - ::: moniker range=">= azure-devops-2022" -- [About work item fields](../work-item-fields.md) -- [About managed queries](../../queries/about-managed-queries.md) +- [Learn about work item fields](../work-item-fields.md) +- [Learn about managed queries](../../queries/about-managed-queries.md) - [Define a query](../../queries/using-queries.md) -- [About processes and process templates](choose-process.md) +- [Learn about processes and process templates](choose-process.md) ::: moniker-end ::: moniker range="< azure-devops-2022" -- [About work item fields](../work-item-fields.md) -- [About managed queries](../../queries/about-managed-queries.md) +- [Learn about work item fields](../work-item-fields.md) +- [Learn about managed queries](../../queries/about-managed-queries.md) - [Define a query](../../queries/using-queries.md) -- [About processes and process templates](choose-process.md) -- [Reportable fields reference](/previous-versions/azure/devops/reference/xml/reportable-fields-reference) (On-premises XML process model only) +- [Learn about processes and process templates](choose-process.md) +- [Learn about reportable fields reference](/previous-versions/azure/devops/reference/xml/reportable-fields-reference) (On-premises XML process model only) ::: moniker-end diff --git a/docs/boards/work-items/manage-attachments.md b/docs/boards/work-items/manage-attachments.md new file mode 100644 index 00000000000..b27c1473a6d --- /dev/null +++ b/docs/boards/work-items/manage-attachments.md @@ -0,0 +1,208 @@ +--- +title: Manage work item attachments +titleSuffix: Azure Boards +description: Learn how to manage work item attachments in Azure DevOps. +ms.custom: devx-track-azurecli +ms.service: azure-devops-boards +ms.author: chcomley +author: chcomley +ai-usage: ai-assisted +monikerRange: '<= azure-devops' +ms.topic: how-to +ms.date: 11/21/2024 +--- + +# Manage work item attachments + +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] +[!INCLUDE [version-vs-gt-eq-2019](../../includes/version-vs-gt-eq-2019.md)] + +Attachments enhance work items by enabling you to share essential information with your team. You can attach files, images, and links directly to work items, facilitating better collaboration and documentation. This article provides guidance on managing attachments within Azure DevOps. + +::: moniker range="azure-devops" + +Each work item can include up to **100 attachments**, with each file limited to **60 MB**. This article provides guidance on managing attachments within Azure DevOps. + +::: moniker-end + +::: moniker range="< azure-devops" +By default, each work item can include up to **100 attachments**, with each file limited to **4 MB**. The maximum size of attachments can be configured via the Azure DevOps Server Administration Console. + +::: moniker-end + +## Prerequisites + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To view, follow, and edit work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has these permissions. For more information, see [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md).
- To add tags to work items: Project-level **Create new tag definition** permission set to **Allow**. By default, the **Contributors** group has this permission. | +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
- To add new tags to work items or to view or follow pull requests: At least [**Basic** access](../../organizations/security/access-levels.md).
- To view or follow work items: At least **Stakeholder** access. For more information, see [About access levels](../../organizations/security/access-levels.md).
- All project members, including those in the **Readers** group, can send emails containing work items. | +|**Permanent deletion permissions**| To permanently delete attachments: **Permanently delete work items** permission set to **Allow**.| + +## Manage attachments through the web portal + +Do the following steps to manage attachments through the web portal: + +::: moniker range=" azure-devops" + +1. Go to the desired work item and select the **Attachments** tab. + + :::image type="content" source="media/manage-work-items/attachments-tab-services.png" alt-text="Screenshot showing highlighted Attachments button in work item." ::: + +2. Use the **Collapse/Expand** button to toggle the visibility of attachments. + + :::image type="content" source="media/manage-work-items/expand-collapse-attachments.png" alt-text="Screenshot showing highlighted expand or collapse attachments button in work item." ::: + +3. Switch between **List** and **Grid** views by selecting the corresponding icon. + + :::image type="content" source="media/manage-work-items/attachments-list-grid-view-buttons-services.png" alt-text="Screenshot showing list and grid view buttons." ::: + +4. After you [add an attachment](#add-attachment), hover over the work item to access the **more actions** ![More Actions Icon](../media/icons/more-actions.png) menu. This menu allows you to do the following tasks: + - **Preview** the attachment + - [**Add** and **Edit** a comment](#add-and-edit-comment) + - [**Copy** an attachment link](#copy-attachment-link) + - [**Download** an attachment](#download-attachment) + - [**Delete** attachments](#delete-attachment) + - [**Permanently Delete** an attachment](#permanently-delete-attachment) +### Tips + +- **Bulk management**: To manage multiple attachments simultaneously, consider using bulk actions available in the **Attachments** tab. +- **Permissions**: Ensure you have the appropriate permissions to add, edit, or delete attachments. Project administrators typically have full access, while other roles might have limited permissions. +- **File size and type**: Be mindful of the attachment size limits (up to **60 MB** per file) and ensure that the file types you upload are supported by Azure DevOps. + +::: moniker-end + +::: moniker range="< azure-devops" + +1. Go to the desired work item and select the **Attachments** tab. + + :::image type="content" source="media/manage-work-items/attachments-tab-server.png" alt-text="Screenshot of highlighted Attachments button in work item." ::: + +2. Choose a list or grid view of attachments. The grid view provides a thumbnail preview of the attachment. + + :::image type="content" source="media/manage-work-items/attachments-list-grid-view-buttons-server.png" alt-text="Screenshot showing list and grid view buttons." ::: + +3. After you [add an attachment](#add-attachment), hover over the work item to access the **more actions** ![More Actions Icon](../media/icons/more-actions.png) menu. This menu allows you to do the following tasks: + - **Preview** an attachment + - [**Add** and **Edit** a comment](#add-and-edit-comment) + - [**Download** an attachment](#download-attachment) + - [**Delete** an attachment](#delete-attachment) + +::: moniker-end + +### Add attachment + +To add an attachment to a work item, do the following steps: + +1. From your work item, select **Attachments** > **Add attachment**. + + :::image type="content" source="../backlogs/media/add-attachment.png" alt-text="Screenshot showing highlighted Attachments button."::: + +2. Select the file > **Open** > **Save**. + +The attachment gets added to the work item. To add more attachments, select **+ Add attachment**. + +### Add and edit comment + +To add or edit a comment for an attachment, do the following steps: + +::: moniker range="azure-devops" + +1. Hover over the attachment and select **more actions** :::image type="icon" source="../media/icons/more-actions.png" border="false"::: > **Edit comment**. + + :::image type="content" source="media/manage-work-items/add-comment-attachment.png" alt-text="Screenshot showing add comment to attachment flow."::: + +1. Add or edit your comment and select **Save**. + +::: moniker-end + +::: moniker range="< azure-devops" + +1. Select or hover over the attachment and select **more actions** :::image type="icon" source="../media/icons/more-actions-horizontal.png" border="false"::: > **Edit comment**. + + :::image type="content" source="media/manage-work-items/add-comment-attachment.png" alt-text="Screenshot showing add comment to attachment flow."::: + +1. Edit your comment and select **Save**. + +::: moniker-end + +::: moniker range="azure-devops" + +### Copy attachment link + +To copy the link to an attachment: + +Hover over the attachment and select **more actions** :::image type="icon" source="../media/icons/more-actions.png" border="false"::: > **Copy attachment link**. + +::: moniker-end + +### Download attachment + +To download an attachment to your browser's download directory: + +::: moniker range="azure-devops" + +Hover over the attachment and select **more actions** :::image type="icon" source="../media/icons/more-actions.png" border="false"::: > **Edit comment**. + +::: moniker-end + +::: moniker range="< azure-devops" + +Select or hover over the attachment and select **more actions** :::image type="icon" source="../media/icons/more-actions-horizontal.png" border="false"::: > **Download attachment**. + +::: moniker-end + +### Delete attachment + +To delete an attachment, do the following steps: + +::: moniker range="azure-devops" + +1. Hover over the attachment and select **more actions** :::image type="icon" source="../media/icons/more-actions.png" border="false"::: > **Delete attachment**. + +1. Select **Delete** to confirm you want to delete the attachment. + + :::image type="content" source="../backlogs/media/confirm-delete-attachment.png" alt-text="Screenshot showing Delete button for confirming delete action."::: + +::: moniker-end + +::: moniker range="< azure-devops" + +1. Select or hover over the attachment and select **more actions** :::image type="icon" source="../media/icons/more-actions-horizontal.png" border="false"::: > **Delete attachment**. + +1. Select **Delete** to confirm you want to delete the attachment. + + :::image type="content" source="../backlogs/media/confirm-delete-attachment.png" alt-text="Screenshot showing Delete button for confirming delete action."::: + +The deleted attachment can't be restored and is permanently removed after 28 days. In the meantime, if you have permissions, you can [permanently delete](#permanently-delete-attachment) it. + +::: moniker-end + +The deleted attachment can't be restored and is permanently removed after 28 days. In the meantime, if you have permissions, you can [permanently delete](#permanently-delete-attachment) it. + +::: moniker range="azure-devops" + +### Permanently delete attachment + +This action is typically reserved for situations requiring immediate removal, such as when files are infected. Otherwise, deleted attachments are automatically removed within 28 days. + +1. From your work item, select the **Attachments** tab. +2. Select **more actions** :::image type="icon" source="../media/icons/more-actions.png" border="false"::: > **Permanently delete attachment**. + + :::image type="content" source="../backlogs/media/permanently-delete-attachment.png" alt-text="Screenshot showing permanently delete attachment flow."::: + +3. Select **Delete** to confirm you want to permanently delete the attachment. + + :::image type="content" source="../backlogs/media/confirm-permanently-delete-attachment.png" alt-text="Screenshot showing Delete button for confirming permanent delete action."::: + +The attachment is permanently deleted and isn't accessible from any other links. + +> [!NOTE] +> This feature requires the **New Boards Hub**, which is enabled by default. For more information, see [Manage or enable features](../../project/navigation/preview-features.md). + +::: moniker-end + +## Related articles + +- [Learn about work items and work item types](about-work-items.md) +- [Manage work items](../backlogs/manage-work-items.md) +- [View and add work items](view-add-work-items.md) diff --git a/docs/boards/work-items/media/follow-work/follow-work-item-new-boards-hubs.png b/docs/boards/work-items/media/follow-work/follow-work-item-new-boards-hubs.png new file mode 100644 index 00000000000..8ca2d079d2b Binary files /dev/null and b/docs/boards/work-items/media/follow-work/follow-work-item-new-boards-hubs.png differ diff --git a/docs/boards/work-items/media/follow-work/follow-work-item.png b/docs/boards/work-items/media/follow-work/follow-work-item.png index b9448322125..d0b5eea33cb 100644 Binary files a/docs/boards/work-items/media/follow-work/follow-work-item.png and b/docs/boards/work-items/media/follow-work/follow-work-item.png differ diff --git a/docs/boards/work-items/media/manage-work-items/add-comment-attachment.png b/docs/boards/work-items/media/manage-work-items/add-comment-attachment.png new file mode 100644 index 00000000000..ab2efc4d4bb Binary files /dev/null and b/docs/boards/work-items/media/manage-work-items/add-comment-attachment.png differ diff --git a/docs/boards/work-items/media/manage-work-items/assign-work-item.png b/docs/boards/work-items/media/manage-work-items/assign-work-item.png new file mode 100644 index 00000000000..700d5ac6f95 Binary files /dev/null and b/docs/boards/work-items/media/manage-work-items/assign-work-item.png differ diff --git a/docs/boards/work-items/media/manage-work-items/attachments-list-grid-view-buttons-server.png b/docs/boards/work-items/media/manage-work-items/attachments-list-grid-view-buttons-server.png new file mode 100644 index 00000000000..b37106762f1 Binary files /dev/null and b/docs/boards/work-items/media/manage-work-items/attachments-list-grid-view-buttons-server.png differ diff --git a/docs/boards/work-items/media/manage-work-items/attachments-list-grid-view-buttons-services.png b/docs/boards/work-items/media/manage-work-items/attachments-list-grid-view-buttons-services.png new file mode 100644 index 00000000000..79304bc6152 Binary files /dev/null and b/docs/boards/work-items/media/manage-work-items/attachments-list-grid-view-buttons-services.png differ diff --git a/docs/boards/work-items/media/manage-work-items/attachments-tab-server.png b/docs/boards/work-items/media/manage-work-items/attachments-tab-server.png new file mode 100644 index 00000000000..2c35a37011a Binary files /dev/null and b/docs/boards/work-items/media/manage-work-items/attachments-tab-server.png differ diff --git a/docs/boards/work-items/media/manage-work-items/attachments-tab-services.png b/docs/boards/work-items/media/manage-work-items/attachments-tab-services.png new file mode 100644 index 00000000000..6bbac5ed798 Binary files /dev/null and b/docs/boards/work-items/media/manage-work-items/attachments-tab-services.png differ diff --git a/docs/boards/work-items/media/manage-work-items/expand-collapse-attachments.png b/docs/boards/work-items/media/manage-work-items/expand-collapse-attachments.png new file mode 100644 index 00000000000..0ad3c60fa9f Binary files /dev/null and b/docs/boards/work-items/media/manage-work-items/expand-collapse-attachments.png differ diff --git a/docs/boards/work-items/media/manage-work-items/go-to-work-items-vs-2022.png b/docs/boards/work-items/media/manage-work-items/go-to-work-items-vs-2022.png new file mode 100644 index 00000000000..897f9178b9b Binary files /dev/null and b/docs/boards/work-items/media/manage-work-items/go-to-work-items-vs-2022.png differ diff --git a/docs/boards/work-items/media/manage-work-items/select-work-items-vs-2022.png b/docs/boards/work-items/media/manage-work-items/select-work-items-vs-2022.png new file mode 100644 index 00000000000..ad53c08f3f1 Binary files /dev/null and b/docs/boards/work-items/media/manage-work-items/select-work-items-vs-2022.png differ diff --git a/docs/boards/work-items/media/new-work-item-button.png b/docs/boards/work-items/media/new-work-item-button.png new file mode 100644 index 00000000000..80a675b608f Binary files /dev/null and b/docs/boards/work-items/media/new-work-item-button.png differ diff --git a/docs/boards/work-items/media/new-work-item.png b/docs/boards/work-items/media/new-work-item.png new file mode 100644 index 00000000000..cf663951aec Binary files /dev/null and b/docs/boards/work-items/media/new-work-item.png differ diff --git a/docs/boards/work-items/media/team-settings-work-item-automation.png b/docs/boards/work-items/media/team-settings-work-item-automation.png new file mode 100644 index 00000000000..d9775ce9800 Binary files /dev/null and b/docs/boards/work-items/media/team-settings-work-item-automation.png differ diff --git a/docs/boards/work-items/media/view-add/open-work-items-agile.png b/docs/boards/work-items/media/view-add/open-work-items-agile.png index ebe05d0f28d..8064ab8e549 100644 Binary files a/docs/boards/work-items/media/view-add/open-work-items-agile.png and b/docs/boards/work-items/media/view-add/open-work-items-agile.png differ diff --git a/docs/boards/work-items/move-work-items.md b/docs/boards/work-items/move-work-items.md index ca3338355c9..c4a767984eb 100644 --- a/docs/boards/work-items/move-work-items.md +++ b/docs/boards/work-items/move-work-items.md @@ -4,78 +4,69 @@ titleSuffix: Azure Boards description: Learn how to move work items assigned to one team to another team. ms.subservice: azure-devops-settings ms.custom: devx-track-azurecli +ai-usage: ai-assisted ms.author: chcomley author: chcomley -ms.topic: tutorial +ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 05/20/2022 +ms.date: 01/03/2025 --- # Move work items from one team to another team [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -When you add a team or your teams undergo reorganization, you may need to move work items assigned to one team to new **Area Paths** owned by another team. All work items are assigned to an **Area Path**, even if it is at the top of the hierarchy for the project. +When you add a team or reorganize existing teams, you might need to transfer work items from one team to another by updating their Area Paths. Every work item in Azure DevOps is assigned to an Area Path, which determines team ownership and influences how work items are displayed on backlogs and boards. -Work items that belong to the Requirements category appear on a team's backlog based on their assignment to the **Area Path(s)** owned by a team. Assigning other work items to a team's **Area Path(s)** support queries based on team ownership. - -To learn how to add a team, see [Create or add a team](../../organizations/settings/add-teams.md). - +Work items categorized under the Requirements category appear on a team's backlog based on their assignment to the team's Area Path. Similarly, assigning other work items to a team's Area Path supports queries and reporting based on team ownership. ## Prerequisites ::: moniker range="azure-devops" -- To change the **Area Paths** of work items, you must be a project member and have permissions to view and edit work items under the **Area Path** nodes. To learn about these permissions, see [Set work tracking permissions, Create child nodes, modify work items under an area or iteration path](../../organizations/security/set-permissions-access-work-tracking.md#create-child-nodes-modify-work-items-under-an-area-or-iteration-path). -- To use Azure CLI commands, you must first install Azure CLI as described in [Get started with Azure DevOps CLI](../../cli/index.md). +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To view, follow, and edit work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has these permissions. For more information, see [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md).
- To add tags to work items: Project-level **Create new tag definition** permission set to **Allow**. By default, the **Contributors** group has this permission. | +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
- To add new tags to work items or to view or follow pull requests: At least [**Basic** access](../../organizations/security/access-levels.md).
- To view or follow work items: At least **Stakeholder** access. For more information, see [About access levels](../../organizations/security/access-levels.md).
- All project members, including those in the **Readers** group, can send emails containing work items. | +|**Area Path permissions**| **View** and **Edit** work items under the Area Path nodes. For more information, see [Modify work items under an area or iteration path](../../organizations/security/set-permissions-access-work-tracking.md#create-child-nodes-modify-work-items-under-an-area-or-iteration-path).| +|**Configured area paths**| The target team has correctly configured Area Paths. If not, set up the required Area Paths before transferring work items.| +|**Consistent process model**| Your team uses a compatible process model (Inherited, Hosted XML, or On-premises XML) to ensure seamless movement of work items.| +|**Backed up work items**| We recommend you back up or export work items before performing bulk moves to prevent data loss if there's an error. | +|**Tools**| To use Azure CLI commands: [Azure DevOps CLI](../../cli/index.md). | ::: moniker-end ::: moniker range="< azure-devops" -- To change the **Area Paths** of work items, you must be a project member and have permissions to view and edit work items under the **Area Path** nodes. To learn about these permissions, see [Set work tracking permissions, Create child nodes, modify work items under an area or iteration path](../../organizations/security/set-permissions-access-work-tracking.md#create-child-nodes-modify-work-items-under-an-area-or-iteration-path). +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To view, follow, and edit work items: **View work items in this node** and **Edit work items in this node** permissions set to **Allow**. By default, the **Contributors** group has these permissions. For more information, see [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md).
- To add tags to work items: Project-level **Create new tag definition** permission set to **Allow**. By default, the **Contributors** group has this permission. | +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
- To add new tags to work items or to view or follow pull requests: At least [**Basic** access](../../organizations/security/access-levels.md).
- To view or follow work items: At least **Stakeholder** access. For more information, see [About access levels](../../organizations/security/access-levels.md).
- All project members, including those in the **Readers** group, can send emails containing work items. | +|**Area Path permissions**| **View** and **Edit** work items under the **Area Path** nodes. For more information, see [Modify work items under an area or iteration path](../../organizations/security/set-permissions-access-work-tracking.md#create-child-nodes-modify-work-items-under-an-area-or-iteration-path).| ::: moniker-end - - ## Move work items under teams -From the web portal, you can perform bulk updates of the **Area Path**. - -::: moniker range=">= azure-devops-2019" +To move work items under a team, do the following steps: 1. [Create a query](../queries/using-queries.md) of all work items you want to reassign. + +2. Multi-select those items, which belong to each team, and [bulk edit the area path](../backlogs/bulk-modify-work-items.md). -1. Multi-select those items, which belong to each team, and [bulk edit the area path](../backlogs/bulk-modify-work-items.md). - - Screenshot of Web portal, Queries page, Bulk modify select work items. - -1. After you bulk modify, do a bulk save. + ![Screenshot of Web portal, Queries page, Bulk modify select work items.](media/move-work-items/query-bulk-edit-area-path.png) - Screenshot of Bulk save edited work items. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. [Create a query](../queries/using-queries.md) of all work items you want to reassign. Multi-select those items belonging to each team, and [bulk edit the area path](../backlogs/bulk-modify-work-items.md). - -2. After you bulk modify, do a bulk save. - - ![Screenshot of the Web portal, Queries page, Bulk save selected work items.](media/move-work-items/scale-agile-bulk-save-area-path-co.png) - -::: moniker-end - - - +3. After you bulk modify, bulk save. + + ![Screenshot of Bulk save edited work items.](media/move-work-items/query-bulk-save.png) + ::: moniker range="azure-devops" ## Move a work item using Azure CLI -You can use the [az boards work-item update](/cli/azure/boards/work-item#az-boards-work-item-update) to move a single work item by updating it's Area Path. +You can use the [az boards work-item update](/cli/azure/boards/work-item#az-boards-work-item-update) to move a single work item by updating its Area Path. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -115,7 +106,7 @@ You can only move one work item at a time using Azure DevOps CLI. In this exampl az boards work-item update --id 148 --area "Fabrikam Fiber\Production Planning" --output yaml ``` -The YAML output listed below provides information on each of the fields defined for the work item. +The following YAML output provides information on each of the fields defined for the work item. > [!div class="tabbedCodeSnippets"] ```YAML output @@ -195,15 +186,19 @@ url: https://fabrikamprime.visualstudio.com/854a3f67-9962-43d1-a968-2e5f2eb66c99 ``` ::: moniker-end - -## Verify your team backlog +## Verify visibility -After you move work items from one team to another team, check your team backlog to ensure the items appear. See [Create your backlog](../backlogs/create-your-backlog.md). +After you move work items from one team to another team, do the following actions if you don't see the work items: +- **Refresh**: Refresh the board or select **Show more items** if newly added work items don't appear. +- **Verify team**: Check that you selected the right team to ensure the items appear on the backlog. +- **Verify Area Path**: Verify that the moved work items are assigned to the correct Area Path that corresponds to the team's backlog. Each team has specific Area Paths that determine which work items show up on their backlog. This action is crucial for ensuring visibility in the backlog. +- **Verify Iteration Path**: Check the Iteration Path for the sprint. The sprint backlog only displays work items assigned to the selected sprint's Iteration Path. +- **Verify work item types and filters**: Review your backlog filters and that work item types are correctly categorized to ensure all relevant items display. -If you encounter any problems, review [Set up your project's backlogs and boards](../backlogs/set-up-your-backlog.md). +For more information, see [Set up your project's backlogs and boards](../backlogs/set-up-your-backlog.md). ## Related articles - [Create or add a team](../../organizations/settings/add-teams.md) -- [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md) +- [Learn about teams and Agile tools](../../organizations/settings/about-teams-and-settings.md) diff --git a/docs/boards/work-items/quick-ref.md b/docs/boards/work-items/quick-ref.md index abaabbc01e4..45168008dd9 100644 --- a/docs/boards/work-items/quick-ref.md +++ b/docs/boards/work-items/quick-ref.md @@ -17,20 +17,18 @@ ms.date: 02/02/2023 Use this index to quickly access concepts and tasks related to work items and information on adding and updating work items—such as users stories, features, tasks, and bugs. - ::: moniker range="azure-devops" > [!NOTE] -> The following features require that you enable the **New Boards Hub** preview feature. These features are only available for Azure DevOps Services at this time. To enable the **New Boards Hub**, see [Manage or enable features](../../project/navigation/preview-features.md). -> - [Change the link type of an existing link](../backlogs/add-link.md#change-link-type) +> The following features require the **New Boards Hub** feature, which is enabled by default. For more information, see [Manage or enable features](../../project/navigation/preview-features.md): +> - [Change the link type of an existing link](quick-ref.md#work-item-user-tasks) > - [Filter the history tab](../queries/history-and-auditing.md#filter-history) > - [Reassign a checklist item](../boards/add-task-checklists.md#checklist-actions) > - [Move a card to a specific column position](../boards/customize-cards.md#reorder-cards) -> - [Change the color of a swimlane on a Kanban board](../boards/expedite-work.md#add-or-remove-a-swimlane) +> - [Change the color of a swimlane on a board](../boards/expedite-work.md#add-or-remove-a-swimlane) ::: moniker-end - - + ## Key concepts @@ -40,7 +38,7 @@ Use this index to quickly access concepts and tasks related to work items and in - [Agile glossary](agile-glossary.md) - [Agile process](guidance/agile-process.md) - [Area Paths](../../organizations/settings/about-areas-iterations.md) - - [Autocomplete work items](workflow-and-state-categories.md#auto-complete-work-items-with-pr) + - [Autocomplete work items](workflow-and-state-categories.md#auto-completion-of-work-items-with-pull-requests) - [Assigned to](about-work-items.md#assign) - [Basic process](../get-started/plan-track-work.md)
@@ -60,20 +58,19 @@ Use this index to quickly access concepts and tasks related to work items and in :::column-end::: :::column span="1"::: - [Link types](../queries/link-type-reference.md) - - [Linking and traceability](../queries/link-work-items-support-traceability.md) + - [Link work items to other objects](../backlogs/add-link.md) - [Mobile browser](../..//project/navigation/mobile-work.md) - [New Boards Hub](/azure/devops/release-notes/2022/sprint-202-update#new-boards-hubs-now-available-in-public-preview) - [New work item widget](../../report/dashboards/widget-catalog.md#new-work-item) - [On-premises XML process model](../../reference/on-premises-xml-process-model.md) - - [Permissions and access](../../organizations/security/permissions-access-work-tracking.md) + - [Set permissions and access](../../organizations/security/set-permissions-access-work-tracking.md) - [Process guidance](guidance/choose-process.md) - [Process models](../../reference/customize-work.md)
::: moniker range="azure-devops" - [Queries](../queries/about-managed-queries.md) - [Recycle bin](../backlogs/remove-delete-work-items.md#restore) - - [Remote linking](../backlogs/add-link.md#remote-link) - - [Rich text fields](../queries/share-plans.md#rich-text-fields) + - [Remote linking](../backlogs/add-link.md) - [Rollup](../backlogs/display-rollup.md) - [Scrum process](guidance/scrum-process.md) - [State categories](workflow-and-state-categories.md) @@ -81,20 +78,11 @@ Use this index to quickly access concepts and tasks related to work items and in ::: moniker range="azure-devops-2020" - [Queries](../queries/about-managed-queries.md) - [Recycle bin](../backlogs/remove-delete-work-items.md#restore) - - [Rich text fields](../queries/share-plans.md#rich-text-fields) - [Rollup](../backlogs/display-rollup.md) - [Scrum process](guidance/scrum-process.md) - [State categories](workflow-and-state-categories.md) ::: moniker-end - ::: moniker range="< azure-devops-2020" - - [Queries](../queries/about-managed-queries.md) - - [Recycle bin](../backlogs/remove-delete-work-items.md#restore) - - [Requirements](../../cross-service/manage-requirements.md) - - [Rich text fields](../queries/share-plans.md#rich-text-fields) - - [Rollup](../../reference/xml/support-rollup-of-work-and-other-fields.md) - - [Scrum process](guidance/scrum-process.md) - - [State categories](workflow-and-state-categories.md) - ::: moniker-end + :::column-end::: :::column span="1"::: - [Tags](../queries/add-tags-to-work-items.md) @@ -104,10 +92,10 @@ Use this index to quickly access concepts and tasks related to work items and in - [Visual Studio work item experience](set-work-item-experience-vs.md)
- [Work item fields](guidance/work-item-field.md) - - [Work item form](about-work-items.md#work-item-form) - - [Work item form controls](work-item-form-controls.md) + - [Work item form](about-work-items.md) + - [Work item form controls](about-work-items.md#work-item-form-controls) - [Work item templates](about-work-items.md#templates) - - [Work item types](about-work-items.md#work-item-types-wits) + - [Work item types](about-work-items.md) - [Work tracking limits](../../organizations/settings/work/object-limits.md) - [Workflow](workflow-and-state-categories.md) :::column-end::: @@ -126,45 +114,35 @@ Tasks listed below are available to users with **Contributor** permissions and * - [Add Epics](../boards/kanban-epics-features-stories.md) - [Add Features](../boards/kanban-epics-features-stories.md) - [Add items to a backlog](../backlogs/create-your-backlog.md) - - [Add items to a Kanban board](../boards/kanban-quickstart.md) + - [Add items to a board](../boards/kanban-quickstart.md) - [Add links](../backlogs/add-link.md) - [Add tags](../queries/add-tags-to-work-items.md) - [Add tasks](../sprints/add-tasks.md) - [Add to discussion](../backlogs/add-work-items.md#capture-comments-in-the-discussion-section) - [Apply a template to a work item](../backlogs/work-item-template.md) - [Assign work to a team member](about-work-items.md#assign-work-items) - - [Attach files](../queries/share-plans.md#attach-files) -
- [Bulk add or remove tags](../queries/add-tags-to-work-items.md#bulk-add-or-remove-tags) - [Bulk modify work items (Excel)](../backlogs/office/bulk-add-modify-work-items-excel.md) - [Bulk modify work items (Web)](../backlogs/bulk-modify-work-items.md)
- [Capture work item as a template](../backlogs/work-item-template.md#capture-a-work-item-as-a-template) - - [Change the link type](../backlogs/add-link.md#change-link-type) + - [Change the link type](../backlogs/add-link.md#change-the-link-type-of-an-existing-link) - [Change work item type](../backlogs/move-change-type.md#change-the-work-item-type) - [Copy or clone a work item](../backlogs/copy-clone-work-items.md) - - [Copy work item URL](work-item-form-controls.md#copy-the-url) - - [Copy URL of attachment](../queries/share-plans.md#copy-url-attached-file) - - [Copy list of work items](../backlogs/copy-list.md) + - [Copy work item URL](about-work-items.md#copy-the-url) + - [Copy list of work items](../backlogs/copy-clone-work-items.md#copy-a-list-of-work-items) - [Create a branch](../backlogs/connect-work-items-to-git-dev-ops.md) - [Create a work tracking chart](../../report/dashboards/charts.md)
::: moniker range=">= azure-devops-2020" - - [Define a work item template](../backlogs/work-item-template.md) - - [Define work item URL](work-item-url-hyperlink.md) + - [Define a work item template](../backlogs/work-item-template.md) - [Delete work item tags](../queries/add-tags-to-work-items.md#delete-remove-or-manage-tags) - [Delete work items](../backlogs/remove-delete-work-items.md) - [Display rollup](../backlogs/display-rollup.md) ::: moniker-end - ::: moniker range="< azure-devops-2020" - - [Define a work item template](../backlogs/work-item-template.md) - - [Define work item URL](work-item-url-hyperlink.md) - - [Delete work item tags](../queries/add-tags-to-work-items.md#delete-remove-or-manage-tags) - - [Delete work items](../backlogs/remove-delete-work-items.md) - ::: moniker-end - + - - [Email work item list](email-work-items.md) + - [Send email of work item list](email-work-items.md) - [Export a work item list](email-work-items.md#export) :::column-end::: :::column span="1"::: @@ -178,10 +156,10 @@ Tasks listed below are available to users with **Contributor** permissions and * - [Link to cross-organization work items](../backlogs/add-link.md) - [Link to development objects](../backlogs/add-link.md) - [Link to GitHub commits and pull requests](../github/link-to-from-github.md) - - [Link to work items from a wiki](../../project/wiki/wiki-markdown-guidance.md) + - [Link to work items from a wiki](../../project/wiki/markdown-guidance.md) - [Link work items](../backlogs/add-link.md) - [List work items](../queries/using-queries.md) - - [List work items in a wiki](../../project/wiki/wiki-markdown-guidance.md) + - [List work items in a wiki](../../project/wiki/markdown-guidance.md#)
- [Manage bugs](../backlogs/manage-bugs.md) - [Manage issues or impediments](../backlogs/manage-issues-impediments.md) @@ -201,15 +179,14 @@ Tasks listed below are available to users with **Contributor** permissions and * - [Reassign a checklist item](../boards/add-task-checklists.md#checklist-actions) - [Reassign work items](../backlogs/bulk-modify-work-items.md#reassign-work-items) - [Remove work items](../backlogs/remove-delete-work-items.md#remove-work-items) - - [Request feedback ](/previous-versions/azure/devops/project/feedback/get-feedback) + - [Request feedback](/previous-versions/azure/devops/project/feedback/get-feedback) - [Restore deleted work items](../backlogs/remove-delete-work-items.md#restore-or-permanently-delete-work-items)
- - [Start storyboarding ](../queries/share-plans.md#storyboard) + - [Start storyboarding](/previous-versions/azure/devops/boards/backlogs/office/storyboard-your-ideas-using-powerpoint) - [Track dependencies](../plans/track-dependencies.md) - - [Triage work items](../queries/triage-work-items.md)
- [Update status of tasks (Taskboard)](../sprints/task-board.md) - - [Update status of work items (Kanban board)](../boards/kanban-quickstart.md) + - [Update status of work items (board)](../boards/kanban-quickstart.md) - [Use #ID to link](../../organizations/notifications/add-links-to-work-items.md) - [Use @mentions](../../organizations/notifications/at-mentions.md)
@@ -224,11 +201,7 @@ Tasks listed below are available to users with **Contributor** permissions and * - [View work recently created](view-add-work-items.md) - [View work where I'm mentioned](view-add-work-items.md) ::: moniker-end - ::: moniker range="< azure-devops-2020" - - [View history](../queries/history-and-auditing.md#view-history) - - [View work items (mobile)](../../project/navigation/mobile-work.md) - - [View work items (web)](../backlogs/add-work-items.md) - ::: moniker-end + :::column-end::: :::row-end::: --- @@ -245,7 +218,7 @@ You customize work item types using the Inheritance process model. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" - - [Change a field label](../../organizations/settings/work/customize-process-field.md#rename-field) - - [Change the WIT color or description](../../organizations/settings/work/customize-process-work-item-type.md#overview) - - [Create a project](../../organizations/projects/create-project.md) - :::column-end::: - :::column span="1"::: - - [Define Area Paths](../../organizations/settings/set-area-paths.md) - - [Define Iteration Paths](../../organizations/settings/set-iteration-paths-sprints.md) - - [Delete field](../../organizations/settings/work/customize-process-field.md#delete-field) - - [Delete a WIT](../../organizations/settings/work/customize-process-work-item-type.md#destroy) -
- - [Enable/disable a WIT](../../organizations/settings/work/customize-process-work-item-type.md#enable-disable) - - [Modify a default pick list](../../organizations/settings/work/customize-process-field.md#add-a-picklist) - - [Move the field within the layout](../../organizations/settings/work/customize-process-form.md#move-field) -
- - [Remove a field from a form](../../organizations/settings/work/customize-process-field.md#remove-field) - - [Restrict modification](../../organizations/security/restrict-access.md#restrict-modifications-wits) - - [Set required/default options](../../organizations/settings/work/customize-process-field.md#options) - - [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md) - :::column-end::: -:::row-end::: ---- - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="= azure-devops-2019' -ms.date: 06/27/2022 +monikerRange: "<=azure-devops" +ms.date: 11/21/2024 --- -# Set the Work Items experience +# Set the work items experience [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -[!INCLUDE [version-vs-gt-eq-2019](../../includes/version-vs-gt-eq-2019.md)] +[!INCLUDE [version-vs-gt-eq-2019](../../includes/version-vs-gt-eq-2019.md)] -Visual Studio 2019 supports switching between the default view of the Team Explorer **Work Items** page and the legacy view. The default view is designed to match the web portal **Boards>Work Items** page. The legacy view supports the Work Items page available with the previous versions of Visual Studio as described in the linked articles listed below. +Visual Studio 2019 allows you to switch between the default and legacy views of the Team Explorer **Work Items** page. The default view is designed to align with the web portal's **Boards** > **Work Items** page, offering a modern and consistent interface for managing work items. The legacy view retains the familiar layout from previous versions of Visual Studio, supporting users who prefer the traditional Work Items page experience. -Each view supports the following tasks: +## Prerequisites -| **Default experience**|**Legacy experience**| -|-----------------------|---------------------| -|- [View and add work items](./view-add-work-items.md)|- [Add work items](../backlogs/add-work-items.md)
- [Use the query editor to list and manage queries](../queries/using-queries.md)
- [Organize query folders and set query permissions](../queries/set-query-permissions.md)
- [Open query in Excel](../backlogs/office/bulk-add-modify-work-items-excel.md)
- [Email query results list using Outlook](../queries/share-plans.md)
- [Create reports from query in Excel](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports)
(on-premises Azure DevOps Server only)| - -> [!NOTE] -> If you want to quickly access a list of work items based on their assignment to you, following, mentioned, or recent updates; then use the new default experience. However, if you rely on accessing queries from Team Explorer, then we recommend that you set your Landing page to the legacy option. +Before you switch between work item views in Visual Studio 2019, ensure you meet the following requirements: +[!INCLUDE [prerequisites-work-items](../includes/prerequisites-work-items.md)] -## Change your Work Items view +| Category | Requirements | +|--------------|-------------| +|**Tools**| Visual Studio 2019 and latest updates.| +|**Extensions**| Enabled Team Explorer extension in Visual Studio 2019.| -1. From Visual Studio 2019 choose **Tools>Options**. +## Work item views -1. In the Options dialog, enter **work items** in the search box. +Visual Studio 2019 provides flexibility in how you interact with work items by offering the following two distinct views: -1. Choose your **Landing page** option from the menu. +### Default view - > [!div class="mx-imgBorder"] - > ![Open Tools>Options>Work Items](media/set-vs-experience/option-vs-options-work-items.png) +- **Consistency with web portal**: Mirrors the **Boards** > **Work Items** page in the Azure DevOps web portal. +- **Modern interface**: Features a streamlined and updated design for enhanced usability. +- **Integrated features**: Applies the latest updates and integrations available in Azure DevOps. -To learn more about **Options**, see [Options Dialog Box (Visual Studio)](/visualstudio/ide/reference/options-dialog-box-visual-studio). +### Legacy view + +- **Familiar layout**: Maintains the traditional Work Items page layout from earlier Visual Studio versions. +- **Compatibility**: Ensures continuity for users transitioning from previous versions of Visual Studio. +- **Customizations**: Supports existing customizations and workflows established in older environments. + +## Switch work item views + +To switch between the default and legacy views of the Work Items page in Visual Studio 2019, do the following steps: + +1. Select **View** > **Team Explorer** in the Visual Studio menu. + +2. In Team Explorer, select **Work Items** to open the Work Items page. + +3. Look for a toggle or option labeled **Switch to Legacy View** or **Use Default View** and move the toggle to switch between the default and legacy views based on your preference. + +## More resources + +For more information on managing work items and customizing your experience, see the following resources: + +- [Azure Boards-GitHub integration](index.md) +- [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md) +- [Work item field index](guidance/work-item-field.md) +- [Manage work item fields using witadmin](../../reference/witadmin/manage-work-item-fields.md) +- [Naming restrictions and conventions](../../organizations/settings/naming-restrictions.md#work-items-work-item-types-and-customizations) ## New Git tool experience @@ -47,4 +71,4 @@ Visual Studio 2019 now includes a new Git tool that provides an improved experie ## Related articles -- [View and add work items using the Work Items page](view-add-work-items.md) \ No newline at end of file +- [Manage work items](../backlogs/manage-work-items.md) diff --git a/docs/boards/work-items/toc.yml b/docs/boards/work-items/toc.yml index 5388a94cba9..d8e4d20f527 100644 --- a/docs/boards/work-items/toc.yml +++ b/docs/boards/work-items/toc.yml @@ -1,16 +1,19 @@ - name: About work items href: about-work-items.md - displayname: user stories, issues, bugs, features, epics, backlog items, requirements, assign, web portal, cients + displayname: user stories, issues, bugs, features, epics, backlog items, requirements, assign, web portal, clients - name: Quick reference href: quick-ref.md displayname: index, concepts, tasks, customize +- name: Manage work items + href: ../backlogs/manage-work-items.md + displayname: add, view, update, attachments, tags, link, delete, copy, clone, analytics, customize, follow, link, best oractices - name: View & add work items displayName: Visual Studio 2019, filter, sort, column options, Discussion, copy to clipboard, email, open as query href: view-add-work-items.md -- name: Add & update a work item - href: ../backlogs/add-work-items.md - displayname: follow, update status, Discussion -- name: Filter your work items +- name: Manage work item attachments + href: ../work-items/manage-attachments.md + displayname: attach, upload, download, delete, view, image, file, drag and drop, link, copy, paste, clipboard +- name: Filter work items href: ../backlogs/filter-backlogs-boards-plans.md displayname: sort, reorder, group, parent, tags - name: Manage requirements @@ -25,11 +28,9 @@ - name: Link work items href: ../backlogs/add-link.md displayname: remote work, bulk modify links, pull request, build -- name: Copy or clone +- name: Copy or clone work items href: ../backlogs/copy-clone-work-items.md - displayname: change type, URL, list -- name: Work item form controls - href: work-item-form-controls.md + displayname: copy, clone, create, duplicate, copy to clipboard - name: Collaborate with others items: - name: Follow work @@ -38,15 +39,10 @@ - name: Use @mentions in discussions href: ../../organizations/notifications/at-mentions.md?toc=/azure/devops/boards/toc.json displayname: people picker - - name: Add tags to work items + - name: Add tags for work items href: ../queries/add-tags-to-work-items.md displayname: chart, color-code, filter, show, query, bulk modify - - name: Share information - href: ../queries/share-plans.md - displayname: rich text, link, attach files, storyboard, email, dashboards, wiki - - name: Copy list - href: ../backlogs/copy-list.md - - name: Email or print work items + - name: Send email of items or print displayName: cards href: email-work-items.md - name: Move work items from one team to another @@ -72,12 +68,8 @@ href: ../backlogs/delete-test-artifacts.md - name: Use work item templates href: ../backlogs/work-item-template.md -- name: Samples - items: - name: Sample work item templates href: work-item-template-examples.md displayname: rich text, tags - - name: Define a work item URL - href: work-item-url-hyperlink.md - name: Go mobile href: ../../project/navigation/mobile-work.md?toc=/azure/devops/boards/toc.json diff --git a/docs/boards/work-items/view-add-work-items.md b/docs/boards/work-items/view-add-work-items.md index dc4533ee69f..23ff0cd9cc2 100644 --- a/docs/boards/work-items/view-add-work-items.md +++ b/docs/boards/work-items/view-add-work-items.md @@ -1,8 +1,8 @@ --- -title: View and add work items from Work Items page +title: View and add work items titleSuffix: Azure Boards -description: Learn how to view and filter work items like user stories, issues, and bugs from the Work Items hub and seven personalized pivot views. -ms.custom: boards-work-items, devx-track-azurecli, contperf-fy20q4, engagement-fy23 +description: Learn how to view and filter work items like user stories, issues, and bugs, as well as create them. +ms.custom: boards-work-items, devx-track-azurecli, engagement-fy23 f1_keywords: - vs.tfc.teamexplorer.workitems - vs.tfc.teamexplorer.TeamExplorer @@ -11,129 +11,119 @@ ms.assetid: EBDE0739-FAE6-4BEA-8F59-E9D20AFE5FE8 ms.author: chcomley author: chcomley ms.topic: quickstart -monikerRange: '>= azure-devops-2019' -ms.date: 02/02/2023 +monikerRange: "<=azure-devops" +ms.date: 10/02/2024 --- -# View and add work items using the Work Items page +# View and add work items [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] [!INCLUDE [version-vs-gt-eq-2019](../../includes/version-vs-gt-eq-2019.md)] -View work items that you created or are assigned to you. The **Work Items** page provides several personalized pivots, as shown in the following image, and interactive filter functions to streamline listing work items. Use this page to quickly find work items defined across teams within a project. +View work items that you created or are assigned to you. The **Work items** page offers several personalized pivots and interactive filter functions to streamline listing work items. Use this page to quickly find work items defined across teams within a project. +This article shows how to add any type of work item. However, use the backlog or board to add backlog or portfolio items—such as user stories, product backlog items, features, or epics. For more information, see [Create your backlog](../backlogs/create-your-backlog.md), [Define features and epics](../backlogs/define-features-epics.md), and [Start using your board](../boards/kanban-quickstart.md). -::: moniker range=">= azure-devops-2020" -![Screenshot of Boards, Work Items page, Work Item Menu, cloud version.](media/view-add/view-menu-cloud-version.png) -::: moniker-end -::: moniker range="< azure-devops-2020" -![Screenshot of Boards, Work Items page, Work Item Menu, on-premises version.](media/view-add/view-menu.png) -::: moniker-end +To create test cases and link them to user stories, see [Add, run, and update inline tests](../boards/add-run-update-tests.md) and [Create test plans and test suites](../../test/create-a-test-plan.md). + +You can add work items in the following ways: +- [Add work items from the Work items page](#add-a-work-item-from-the-work-items-page) +- [Add work items from a Boards, Backlogs, or Sprints page](#add-a-work-item-from-a-boards-backlogs-or-sprints-page) +- [Add work items using the Azure DevOps CLI](#add-a-work-item-from-a-boards-backlogs-or-sprints-page) + +These methods provide flexibility in how you manage and track your work items within Azure DevOps. > [!NOTE] > The **Work Items** page is available from Azure DevOps Services, Azure DevOps Server 2019 and later versions, and Visual Studio 2019 RC1. +## Prerequisites [!INCLUDE [temp](../includes/prerequisites-work-items.md)] - -## Open Work Items - -You can start viewing and adding work items once you connect to a project. - - +## Open the Work items page # [Web portal](#tab/browser) -(1) Check that you've selected the right project, then (2) choose **Boards>Work Items**. +From your project, select **Boards** > **Work items**. > [!div class="mx-imgBorder"] > ![Screenshot of web portal, Open Boards, Work Items hub.](media/view-add/open-work-items-agile.png) - # [Visual Studio 2019](#tab/visual-studio) -Open Visual Studio 2019, Team Explorer, and then choose **Work Items**. To switch between the **Work Items** (default) view and the legacy view, see [Set the Work Items experience in Visual Studio 2019](set-work-item-experience-vs.md). +Open Visual Studio 2019, Team Explorer, and then select **Work Items**. To switch between the **Work Items** (default) view and the legacy view, see [Set the Work Items experience in Visual Studio 2019](set-work-item-experience-vs.md). [!INCLUDE [temp](../includes/note-git-vs-github-connect.md)] > [!div class="mx-imgBorder"] > ![Screenshot of Visual Studio, Team Explorer, Open Work Items hub.](media/view-add/open-work-items-vs-te-complete.png) -If you don't see the **Work Items** option, you need to connect to a project and not just a repository. From the Connect to a Project dialog. Use **CTRL-Shift** to select your options and then choose **Connect**. +If you don't see the **Work Items** option, you're not connected to a project. From the Connect to a Project dialog. Use **CTRL-Shift** to select your options and then choose **Connect**. > [!div class="mx-imgBorder"] > ![Screenshot of Connect to a Project dialog, connect to a Project and Git repository.](media/view-add/connect-to-a-project-and-github.png) - -::: moniker range="azure-devops-2019" - -> [!NOTE] -> The new **Work Items** experience is available when you connect to a Azure Repos Git repository. If you connect to a TFVC repository, you'll continue to see the legacy query-focused experience. - -::: moniker-end - - # [Azure DevOps CLI](#tab/azure-devops-cli) There's no [**az boards**](/cli/azure//boards) command that opens the **Work Items** page at this time. The Azure DevOps CLI commands are valid for Azure DevOps Services only. -*** +--- > [!NOTE] -> Depending on the process chosen when the project was created—[Agile](guidance/agile-process-workflow.md), [Basic](../get-started/plan-track-work.md), [Scrum](guidance/scrum-process-workflow.md), or [CMMI](guidance/cmmi-process-workflow.md)—the types of work items you can create differ. For example, backlog items may be called user stories (Agile), issues (Basic), product backlog items (Scrum), or requirements (CMMI). All three are similar: they describe the customer value to deliver and the work to be performed. +> The types of work items you can create depend on the process chosen when the project was created—[Agile](guidance/agile-process-workflow.md), [Basic](../get-started/plan-track-work.md), [Scrum](guidance/scrum-process-workflow.md), or [CMMI](guidance/cmmi-process-workflow.md). For example, backlog items may be called user stories (Agile), issues (Basic), product backlog items (Scrum), or requirements (CMMI). All these types describe the customer value to deliver and the work to be performed. > > For more information, see [About processes and process templates](../work-items/guidance/choose-process.md). ## View work items -Using the drop-down menu, you can focus on relevant items inside a project using one of seven pivots. Additionally, you can [filter](#filter) and [sort](#sort) each pivot view. You can also use an Azure DevOps CLI command to view details about a work item. +You can view work items assigned to you, work items you're following, work items in which you're mentioned, and work items that you recently viewed or updated via the web portal and Visual studio. + +::: moniker range="azure-devops" + +You can also view work items usings the Azure DevOps CLI. + +::: moniker-end # [Web portal](#tab/browser) - + +Use the drop-down menu to focus on relevant items within a project using one of seven pivots. Additionally, [filter](#filter-to-create-personal-views) each pivot view. + :::row::: :::column span="1"::: ::: moniker range=">= azure-devops-2020" ![Screenshot of web portal, Boards, Work Items, Menu options.](media/view-add/view-menu-cloud-version.png) ::: moniker-end - ::: moniker range="< azure-devops-2020" - ![Screenshot of web portal, Boards, Work Items, Menu options, Azure DevOps Server 2019 version.](media/view-add/view-menu.png) - ::: moniker-end + :::column-end::: :::column span="2"::: ::: moniker range=">= azure-devops-2022" - - **Assigned to me**: lists all work items assigned to you in the project in the order they were last updated. Doesn't include items moved to the **Removed** category state. To open or update a work item, simply click its title. - - **Following**: lists work items that you're [following](follow-work-items.md). - - **Mentioned**: lists work items in which you've been mentioned in the last 30 days. - - **My activity**: lists work items that you've recently viewed or updated. - - **My team(s)**: lists work items that your team members have recently viewed or updated. + - **Assigned to me**: Lists all work items assigned to you in the project in the order they were last updated. Doesn't include items moved to the **Removed** category state. To open or update a work item, select its title. + - **Following**: Lists work items that you're [following](follow-work-items.md). + - **Mentioned**: Lists work items in which you're mentioned in the last 30 days. + - **My activity**: Lists work items that you recently viewed or updated. + - **My team(s)**: Lists work items that your team members recently viewed or updated. ::: moniker-end ::: moniker range="azure-devops-2020" - - **Assigned to me**: lists all work items assigned to you in the project in the order they were last updated. To open or update a work item, simply click its title. - - **Following**: lists work items that you're [following](follow-work-items.md). - - **Mentioned**: lists work items in which you've been mentioned in the last 30 days. - - **My activity**: lists work items that you've recently viewed or updated. - - **My team(s)**: lists work items that your team members have recently viewed or updated. - ::: moniker-end - ::: moniker range="< azure-devops-2020" - - **Assigned to me**: lists all work items assigned to you in the project in the order they were last updated. To open or update a work item, simply click its title. - - **Following**: lists work items that you're [following](follow-work-items.md). - - **Mentioned**: lists work items in which you've been mentioned in the last 30 days. - - **My activity**: lists work items that you've recently viewed or updated. + - **Assigned to me**: Lists all work items assigned to you in the project in the order they were last updated. To open or update a work item, select its title. + - **Following**: Lists work items that you're [following](follow-work-items.md). + - **Mentioned**: Lists work items in which you're mentioned in the last 30 days. + - **My activity**: Lists work items that you recently viewed or updated. + - **My team(s)**: Lists work items that your team members recently viewed or updated. ::: moniker-end + --- - - **Recently updated**: lists work items recently updated in the project. - - **Recently completed**: lists work items completed or closed in the project. - - **Recently created**: lists work items created within the last 30 days in the project. + - **Recently updated**: Lists work items recently updated in the project. + - **Recently completed**: Lists work items completed or closed in the project. + - **Recently created**: Lists work items created within the last 30 days in the project. :::column-end::: :::row-end::: - - -# [Visual Studio 2019](#tab/visual-studio) +You can sort your view by any column field selected from the **Column Options** dialog in the web portal. For more information, see [Change column options](../backlogs/set-column-options.md). -To view a work item, double-click the title or open the context menu for the work item (right-click or enter the menu key) and select **Open**. A browser window opens with the work item form. +# [Visual Studio 2019](#tab/visual-studio) + +To view a work item, double-select the title or open the context menu (right-select or select the menu key) and **Open**. A browser window opens with the work item form. :::row::: :::column span="2"::: @@ -147,7 +137,6 @@ To view a work item, double-click the title or open the context menu for the wor :::column-end::: :::row-end::: - # [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" @@ -182,142 +171,160 @@ ID Type Title Assigned To State [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] +--- -*** +## Filter to create personal views - +Filter each work item pivot view by entering a keyword or using fields like work item type (Types), State, Area Path, and Tags. The page remembers your filters for each pivot, providing personalized views across all pivots. For more information, see [Filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md). -## Add a work item +# [Web portal](#tab/browser) -Adding a work item is just one click away. Choose the work item type from the **New Work Item** drop down menu. You can also use an Azure DevOps CLI command to add a new work item. +> [!div class="mx-imgBorder"] +> ![Screenshot of web portal, Work Items page, Filter options, choose to show Bugs.](media/view-add/work-items-filter-bug.png) + +# [Visual Studio 2019](#tab/visual-studio) + +> [!div class="mx-imgBorder"] +> ![Screenshot of Visual Studio 2019, Team Explorer, Work Items page, Filter based on a key word.](media/view-add/filter-list-vs-te.png) + +# [Azure DevOps CLI](#tab/azure-devops-cli) + +No [**az boards**](/cli/azure//boards) command applies to filtering. Azure DevOps CLI commands are only valid for Azure DevOps Services. + +--- + +## Add work items + +You can add work items from the **Work Items** page or from a **Boards**, **Backlogs**, or **Sprints** page in the web portal, from Visual Studio, or by using the Azure DevOps CLI. + +## Add a work item from the Work items page > [!NOTE] > New work items are assigned the last **Area Path** and **Iteration Path** selected by the user. # [Web portal](#tab/browser) +Select **New Work Item** and choose the work item type from the drop-down menu. For example, here we choose User Story. > [!div class="mx-imgBorder"] > ![Screenshot of web portal, Work Items page, New Work Item.](media/view-add/work-items-hub-new.png) > [!TIP] -> Work items you add are automatically scoped to the currently selected team's area and iteration paths. To change the team context, see [Switch project or team focus](../../project/navigation/go-to-project-repo.md?toc=/azure/devops/boards/work-items/toc.json). - -Enter a title and then save the work item. Before you can change the State from its initial default, you must save it. +> Work items you add are automatically assigned to the current team's area and iteration paths. To change the team context, see [Switch project or team focus](../../project/navigation/go-to-project-repo.md?toc=/azure/devops/boards/work-items/toc.json). Enter a title and save the work item. You must save it before changing its initial default state. ![Screenshot of Agile process, User story work item form.](../backlogs/media/add-new-work-item-vsts-user-story.png) - # [Visual Studio 2019](#tab/visual-studio) - -For example, here we choose User Story. - -Choose **New Work Item** and select the work item type you want. +1. Select **New Work Item** and choose the work item type you want. For example, we choose User Story. > [!div class="mx-imgBorder"] > ![Screenshot of Visual Studio 2019, Work Items hub, New Work Item, choose User Story.](media/view-add/add-user-story-vs-te.png) -A browser window opens with the work item form to complete. +A browser window opens, displaying the work item form for you to complete. - -Enter a title and then save the work item. Before you can change the State from its initial default, you must save it. +2. Enter a title and then **Save** the work item. You must save it before changing its initial default state. ![Screenshot of Agile process, User story work item form, opens in web portal.](../backlogs/media/add-new-work-item-vsts-user-story.png) - # [Azure DevOps CLI](#tab/azure-devops-cli) - [!INCLUDE [temp](../includes/add-work-items-cli.md)] [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -*** +--- -You can [add tags to any work item](../queries/add-tags-to-work-items.md) to filter backlogs, queries, and work item lists. Users with **Basic** access can create new tags by default, users with **Stakeholder** access can only add existing tags. +[Add tags to any work item](../queries/add-tags-to-work-items.md) to filter backlogs, queries, and work item lists. Users with **Basic** access can create new tags, while users with **Stakeholder** access can only add existing tags. +## Add a work item from a Boards, Backlogs, or Sprints page - +Do the following steps to add a work item from your Boards, Backlogs, or Sprints page. -## Filter to create personal views +### [Browser](#tab/browser/) -You can filter each work item pivot view by entering a keyword or using one or more of the fields provided, such as work item type (Types), State, Area Path, and Tags. The page remembers the filters you set for each pivot, supporting personalized views across all pivots. To learn more about filtering, see [Filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md). +1. From your **Boards**, **Backlogs**, or **Sprints** page, choose the :::image type="icon" source="../../media/icons/blue-add.png" border="false"::: plus icon or **+ New Work Item**. The following example shows creating a work item from a board. + + :::image type="content" source="media/new-work-item-button.png" alt-text="Screenshot showing highlighted New item button, for creating a work item."::: + > [!NOTE] + > Depending on the process chosen when the project was created—[Agile](../work-items/guidance/agile-process.md), [Basic](../get-started/plan-track-work.md), [Scrum](../work-items/guidance/scrum-process.md), + or [CMMI](../work-items/guidance/cmmi-process.md)—the types of work items you can create are different. For example, backlog items may be called user stories (Agile), issues (Basic) product backlog items (Scrum), or requirements (CMMI). All four are similar: they describe the customer value to deliver and the work to be performed. + > + > For more information, see [About processes and process templates](../work-items/guidance/choose-process.md). The Basic process requires Azure DevOps Server 2019.1 or later version. -# [Web portal](#tab/browser) +2. Select a work item type from the dropdown menu, enter a title, and then select **Enter**. From a board, for example, you can also select **Add to top**. Before you can change the state from its initial default, save it. -> [!div class="mx-imgBorder"] -> ![Screenshot of web portal, Work Items page, Filter options, choose to show Bugs.](media/view-add/work-items-filter-bug.png) + ![Screenshot showing Agile process, User story work item form.](media/new-work-item.png) -# [Visual Studio 2019](#tab/visual-studio) +You can [add tags to any work item to filter backlogs and queries](../queries/add-tags-to-work-items.md). -> [!div class="mx-imgBorder"] -> ![Screenshot of Visual Studio 2019, Team Explorer, Work Items page, Filter based on a key word.](media/view-add/filter-list-vs-te.png) +Added work items are automatically scoped to your team's default area path and iteration path. To change the team context, see [Switch project or team focus](../../project/navigation/go-to-project-repo.md). -# [Azure DevOps CLI](#tab/azure-devops-cli) +Create as many work items as you need of the type you need to track the work you want to manage. -There's no [**az boards**](/cli/azure//boards) command that applies to filtering. The Azure DevOps CLI commands are only valid for Azure DevOps Services. +### [Visual Studio 2019](#tab/visual-studio/) -*** +1. Open Visual Studio 2019, Team Explorer, and then choose **Work Items**. + > [!div class="mx-imgBorder"] + > ![Visual Studio, Team Explorer, Choose Work Items](../work-items/media/view-add/open-work-items-vs-te-complete.png) - + If you don't see the **Work Items** option, you need to connect to a project and not just a repository. From the Connect to a Project dialog. Use **CTRL-Shift** to select your options and then choose **Connect**. -## Add columns and sort by a column + > [!div class="mx-imgBorder"] + > ![Connect to a Project dialog, connect to a Project and Git repository](../work-items/media/view-add/connect-to-a-project-and-github.png) -From the web portal, you can sort your view by one of the column fields that you select from the **Column Options** dialog. For more information, see [Change column options](../backlogs/set-column-options.md). +1. Choose **New Work Item** and select the work item type you want. -[!INCLUDE [temp](../includes/discussion-tip-azure-devops.md)] + > [!div class="mx-imgBorder"] + > ![Work Items, Add User Story](../work-items/media/view-add/add-user-story-vs-te.png) + When you work within Visual Studio 2017 or later version, a browser window opens with the work item form to complete. If you work within Visual Studio 2015 or earlier version, a work item form opens within Visual Studio. -## Copy selected items to the clipboard or email them +### [Azure DevOps CLI](#tab/azure-devops-cli/) -To select several items in a sequence, hold down the shift key from a web portal page. To select several non-sequential items, use the **Ctrl** key. Then, you can use **Ctrl+c** to copy the selected items to a clipboard. Or, you can open the context menu for the selected work items, click ( :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon), and then select an option from the menu. +[!INCLUDE [temp](../includes/add-work-items-cli.md)] -> [!div class="mx-imgBorder"] -> ![Screenshot of web portal, Work Items page, Following view, Select multiple work items, open context menu.](media/view-add/following-context-menu.png) +[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] +* * * ## Open a view as a query From the web portal, you can open any view, filtered view, or selected set of work items as a query. Choose **Open in Queries** or the **Open selected items in Queries** option from the context menu. -Queries provide other features that you can use, including: +Queries provide the following features and more: * Edit one or more fields of several work items * Add or remove tags from several work items * Change the work item type * Delete work items * Apply work item templates -* And more - -For more information, see [Bulk modify work items](../backlogs/bulk-modify-work-items.md?toc=/azure/devops/boards/work-items/toc.json). To learn more about queries, see [Use the query editor to list and manage queries](../queries/using-queries.md) and [Query fields, operators, and macros](../queries/query-operators-variables.md). - - +For more information, see [Bulk modify work items](../backlogs/bulk-modify-work-items.md?toc=/azure/devops/boards/work-items/toc.json). For more information about queries, see [Use the query editor to list and manage queries](../queries/using-queries.md) and [Query fields, operators, and macros](../queries/query-operators-variables.md). -## Work Items page controls +## Use work items page controls Use the following three controls to manage your views in the web portal. > [!div class="mx-tdBreakAll"] -> | Control | Function | +> | Control | Function | > |--------------------------|-------------------------------| -> | ![Image of View options control icon.](../media/icons/view-options-icon.png) | View/hide completed items | -> | ![Image of Filter control icon.](../media/icons/filter-icon.png) | [Turn filtering On/Off](#filter) | -> | ![Image of Full screen icon.](../media/icons/full-screen-icon.png) / ![Image of Exit full screen icon.](../media/icons/exit-full-screen-icon.png) | Enter or exit full screen mode | +> | ![Screenshot of View options control icon.](../media/icons/view-options-icon.png) | View/hide completed items | +> | ![Screenshot of Filter control icon.](../media/icons/filter-icon.png) | [Turn filtering On/Off](#filter-to-create-personal-views) | +> | ![Screenshot of Full screen icon.](../media/icons/full-screen-icon.png) / ![Image of Exit full screen icon.](../media/icons/exit-full-screen-icon.png) | Enter or exit full screen mode | +## Next steps + +> [!div class="nextstepaction"] +> [Manage work items](../backlogs/manage-work-items.md) ## Related articles -- [Azure Boards FAQs](../faqs.yml) -- [Best tool to add, update, and link work items](best-tool-add-update-link-work-items.md) +- [Azure Boards FAQs](../faqs.yml) - [Move, change, or delete work items (Recycle Bin)](../backlogs/remove-delete-work-items.md) - [Manage or enable features](../../project/navigation/preview-features.md) -- [Use work item form controls](work-item-form-controls.md) +- [Use work item form controls](about-work-items.md#work-item-form-controls) - [Keyboard shortcuts](../../project/navigation/keyboard-shortcuts.md) - [Work across projects](../../project/navigation/work-across-projects.md) - - - diff --git a/docs/boards/work-items/work-item-deployments-control.md b/docs/boards/work-items/work-item-deployments-control.md deleted file mode 100644 index bfa882d0c87..00000000000 --- a/docs/boards/work-items/work-item-deployments-control.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Link work items to deployments and other objects -titleSuffix: Azure Boards -description: Learn how to link work items to other objects to improve traceability and simplify navigation to those objects in Azure Boards. -ms.custom: boards-work-items, contperf-fy22q1 -ms.service: azure-devops-boards -ms.topic: how-to -ms.author: chcomley -author: chcomley -monikerRange: '>= azure-devops-2020' -ms.date: 08/26/2022 ---- - -# Link work items to builds and deployments in Azure Boards - -[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] - -One of the main ways Azure DevOps supports traceability is by linking objects. Work items link to Git branches, commits, pull requests, builds, and more. Work item forms provide two controls to show and quickly go to development objects. The **Deployment** control is described in this article, and the **Development** control is described in [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md). - -With the **Deployment** control, you can determine at a glance whether a feature or user story has been deployed and to what stage. You gain visual insight into the status of a work item as it is deployed to different release environments and quick navigation to each release stage and run. - -> [!NOTE] -> The **Deployment** control requires configuration of a Classic release pipeline. It doesn't support linking to release stages defined for a YAML pipeline. - -As shown in the following image, the **Deployment** control shows release information for two release stages those work items that have been linked to a Git commit or pull request for a release pipeline configured to integrate with Azure Boards. - -:::image type="content" source="media/deployments-control/deployment-control-intro.png " alt-text="Screenshot of Work item form, Deployment control."::: - - -## How linking is supported - - Work items linked to a Git repository branch, commit, or pull request participate in populating the **Deployment** control. -You can view all links through the work item form **Links** tab. - -- Work items associated with commits in the build shows the status of the release -- Only work items co-located with the same project where the release pipeline is defined are linked to. - -:::image type="content" source="../../organizations/notifications/media/types-of-work-item-links.png" alt-text="Conceptual image of Git and integrated link types."::: - -To learn how to associate work items to commits, see [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md) or [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md?toc=/azure/devops/boards/toc.json). To view objects linked to a work item, see [View list of links for a work item](#view-link-list). - -## Prerequisites - -- To configure the integration options for a Classic release pipeline, you must have permissions to edit the release. -- To link work items to commits and pull requests, you must have your **Edit work items in this node** permissions set to **Allow** for the Area Path assigned to the work item. By default, the Contributors group has this permission set. -- To view work items, you must have your **View work items in this node** permissions set to **Allow** for the Area Path assigned to the work item. - -To populate the **Deployment** control, complete the following steps: - -1. Define a Classic release pipeline and set up the release stages as described in [Define your multi-stage continuous deployment (CD) pipeline](../../pipelines/release/define-multistage-release-process.md). -2. Configure the pipeline as described in [Configure pipelines to support work tracking, Report deployment status to Boards](../../pipelines/integrations/configure-pipelines-work-tracking.md#classic-report-boards). -3. Link work items to a commit or pull request in Azure Repos Git repository. For more information, see: - - [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md) - - [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md) -4. Run the pipeline. - - - - - - -### Deployment control and work item types - -By default, the Deployment control appears on the work item forms for User Story (Agile), Product Backlog Item (Scrum), Issue (Basic), Requirement (CMMI), Feature, Epic, Bug, Task, and Test Case work item types. It's automatically enabled for custom work item types you define using the Inherited process. If you don't use the control, you can choose to [Hide from layout](../../organizations/settings/work/customize-process-field.md#hide-a-field-or-custom-control). - -If your project is customized using a Hosted XML process or you need to add it to a custom work item type for an On-premises XML process, you'll need to update your work item type definitions to display the control. For more information, see [Hosted XML process model, Add release deployment support to a work item type](../../organizations/settings/work/hosted-xml-process-model.md#add-support-wit). - -## Deployment control - -The work item deployment control displays the status of releases within those work items that are associated with commits in the build and those release pipelines you've configured to report deployment information to Azure Boards. - -The following example shows multiple environments that the release is targeting which the selected work item is associated with. - -> [!div class="mx-imgBorder"] -> ![Example showing multiple environments that the release is targeting.](media/deployments-control/releases-stages-1.png) - -When you open the work item, you can see the stages the release is being deployed, in real time. - -> [!div class="mx-imgBorder"] -> ![Release Settings Stages](media/deployments-control/deployments-control-1.png) - - - - - -## View a list of links for a work item - -To view and go to the builds and releases linked to a work item, choose the :::image type="icon" source="../media/icons/icon-links-tab-wi.png" border="false"::: **Links** tab. Links are grouped under their link type and listed in the order they were created. Choose the **State** or **Latest Update** column headings to sort by the column. Links prefaced with the :::image type="icon" source="../../media/icons/required-icon.png" border="false"::: red exclamation mark indicate that the build, release, or other object has been deleted. This indicator occurs because of retention policies, which automatically delete these objects after a certain time period has passed. - -:::image type="content" source="media/deployments-control/links-list.png" alt-text="Screenshot of Links tab, Integrated in build and Integrated in release stage."::: - - - -## Unlink work items - -Once a work item is linked to a commit or pull request, it continues to appear as part of the release stages. For example, if you have a work item that didn't pass testing criteria, you may want to remove it from the builds and releases. - -To remove the work item from participating in future builds and releases, delete the link to the most recent commit and pull request. You can do that by opening the **Links** tab for the work item as shown in the previous section. - -## Query for linked work items - -You can't query for work items that are included in releases. However, you can create a query for work items with an `External Link Count > 0`. Include other query filters to optimize your search criteria. - - -## Related articles - - -**Azure Repos, Git** - -- [Configure repositories and branches to integrate with work tracking](../../repos/git/configure-repos-work-tracking.md) -- [Drive Git development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md) - - -**Azure Pipelines** - -- [Define your multi-stage continuous deployment (CD) pipeline](../../pipelines/release/define-multistage-release-process.md) -- [Release pipelines (Classic) overview](../../pipelines/release/index.md) -- [Configure pipelines to support work tracking](../../pipelines/integrations/configure-pipelines-work-tracking.md). -- [How to retrieve all work items associated with a release pipeline using Azure DevOps API](https://devblogs.microsoft.com/premier-developer/how-to-retrieve-all-work-items-associated-with-a-release-pipeline-using-azure-devops-api/) - -**Link work items** - -- [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md?toc=/azure/devops/boards/toc.json) -- [End-to-end traceability](../../cross-service/end-to-end-traceability.md) -- [Linking, traceability, and managing dependencies](../queries/link-work-items-support-traceability.md) -- [Link type reference](../queries/link-type-reference.md) - -**Process customization** -- [Hosted XML process model, Add release deployment support to a work item type](../../organizations/settings/work/hosted-xml-process-model.md#add-support-wit) - diff --git a/docs/boards/work-items/work-item-fields.md b/docs/boards/work-items/work-item-fields.md index a0cf0dc9d89..0a318e37c31 100644 --- a/docs/boards/work-items/work-item-fields.md +++ b/docs/boards/work-items/work-item-fields.md @@ -3,50 +3,47 @@ title: List work item fields and attributes in Azure Boards titleSuffix: Azure Boards description: Learn about work item fields, their attributes, and how to modify them in Azure Boards. ms.custom: work-items, engagement-fy23 -ms.service: azure-devops-boards +ms.service: azure-devops-boards +ai-usage: ai-assisted ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' ms.topic: how-to -ms.date: 01/17/2023 +ms.date: 11/21/2024 --- -# Work item fields and attributes in Azure Boards +# List work item fields and attributes [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] ::: moniker range="azure-devops" -Work item fields are used to track information. Fields are defined for an organization and shared across all projects defined for that organization. You can use one of two tools to review the fields defined for the organization. These tools are available for both Inherited and Hosted XML process models. +Work item fields are used to track information within Azure DevOps. These fields are defined at the organization level and are shared across all projects in the organization. To review the fields defined for your organization, you can use one of the following two tools, available for both Inherited and Hosted XML process models: -- [Process>Fields web page](#review-fields) -- [Work Item Field Explorer](#wi-explorer) +- [Process > Fields web page](#review-fields) +- [Work Item Field Explorer](#wi-explorer) ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" -Work item fields are used to track information. Fields are defined for a collection and shared across all projects defined for that collection. You can use one of two tools to review the fields defined for the Collection. +::: moniker range=" < azure-devops" +Work item fields are used to track information within Azure DevOps. These fields are defined at the collection level and shared across all projects within that collection. To review the fields defined for your collection, use one of the following tools: -- [Process>Fields web page](#review-fields): Available for Inherited process model -- [Work Item Field Explorer](#wi-explorer): Available for Inherited and On-premises XML process models. -::: moniker-end - - -::: moniker range="< azure-devops-2019" -Work item fields are used to track information. Fields are defined for a collection and shared across all projects defined for that collection. To view all fields defined for a collection, you can use the [Work Item Field Explorer](#wi-explorer) tool, a plug-in to Visual Studio. +- [Process > Fields web page](#review-fields): Available for the **Inherited** process model. +- [Work Item Field Explorer](#wi-explorer): Available for both **Inherited** and **On-premises XML** process models. ::: moniker-end For a description of each field defined with a system process, see [Work item field index](guidance/work-item-field.md). ## Prerequisites -- To view the fields defined for an organization or collection, you must be a member of the **Project Collection Valid Users** application group or have the **View instance-level information** permission set to **Allow** for the organization or collection. - +| Category | Requirements | +|--------------|-------------| +| **Permissions** | To view the fields defined for an organization or collection: Member of the **Project Collection Valid Users** application group or **View instance-level information** permission set to **Allow** for the organization or collection. | ### List or review fields -To list or review fields, you can use one of the following tools, depending on the process model—Inheritance, Hosted XML, or On-premises XML—you use. For an index of fields defined within the default processes, see [Work item field index](guidance/work-item-field.md). +To list or review fields, use one of the following tools based on your process model—**Inherited**, **Hosted XML**, or **On-premises XML**. For an index of fields defined within the default processes, see [Work item field index](guidance/work-item-field.md). | Tool | Inheritance | Hosted XML | On-premises XML | | --- | --- | --- | --- | @@ -56,72 +53,68 @@ To list or review fields, you can use one of the following tools, depending on t > [!NOTE] > 1. Only supported for default processes (Agile, CMMI, Scrum). - - ## Field data types and names -Each work item type specifies the fields defined for the work items that reference that type. Each field is associated with a number of attributes, many of which are set by the system and cannot be changed. +Each work item type specifies the fields included in work items of that type. Each field has multiple attributes, many of which are system-defined and immutable. -Each field is defined by the following three attributes. -- **Data type**: Specifies the type of data that can be entered into the field, such as Boolean, Double, Integer, HTML, and String. For descriptions of each data type, see [Query fields, operators, and macros](../queries/query-operators-variables.md#field-values). -- **Friendly name**: Specifies the name assigned to the field and that you select for a **Field** in a query clause. This name may differ from the name displayed on the work item form. -- **Reference name**: Specifies the name that you use when creating [WIQL query](../queries/wiql-syntax.md) or an [improvised work item template](../backlogs/work-item-template.md), using [REST API commands](/rest/api/azure/devops/wit/), or defining [XML work item type definitions](/previous-versions/azure/devops/reference/xml/field-definition-element-reference). Once defined, the reference name cannot be changed. - -For a description of each field attribute and how you can list them, see [Field attributes](#field-attributes) and [List field attributes](#list-attributes) later in this article. For an overview of WITs and work items, see [Track work with user stories, issues, bugs, features, and epics](about-work-items.md). +Fields get defined by the following three attributes: +- **Data type**: Indicates the kind of data that can be entered into the field, such as Boolean, Double, Integer, HTML, or String. For detailed descriptions of each data type, see [Query fields, operators, and macros](../queries/query-operators-variables.md#field-values). +- **Friendly name**: The user-friendly name assigned to the field, used when selecting a **Field** in a query clause. This name might differ from the name displayed on the work item form. +- **Reference name**: The identifier used when creating [WIQL queries](../queries/wiql-syntax.md), [improvised work item templates](../backlogs/work-item-template.md), executing [REST API commands](/rest/api/azure/devops/wit/), or defining [XML work item type definitions](/previous-versions/azure/devops/reference/xml/field-definition-element-reference). The reference name is permanent and can't be changed once set. + +For a detailed description of each field attribute and instructions on how to list them, see [Field attributes](#field-attributes) and [List field attributes](#list-attributes) later in this article. For an overview of work item types (WITs) and work items, refer to [Track work with user stories, issues, bugs, features, and epics](about-work-items.md). ### What is a field? How are field names used? -Each [work item type](../backlogs/add-work-items.md) is associated with 31 system fields and several more type-specific fields. You use work items to plan and track your project. +Each [work item type](../backlogs/add-work-items.md) includes 31 system fields and several type-specific fields. Work items are used to plan and track your project. -Each field supports tracking a piece of information about the work to perform. Values you assign to a field are stored in the work tracking data store which you can create queries to determine status and trends. +Each field captures specific information about the work to be performed. The values you assign to these fields are stored in the work tracking data store, enabling you to create queries that determine status and trends. -For descriptions and usage of each field defined for the core system processes, [Agile, Basic, Scrum, and CMMI processes](guidance/choose-process.md), see [Work item field index](guidance/work-item-field.md). +For descriptions and usage of each field defined for the core system processes—[Agile, Basic, Scrum, and CMMI](guidance/choose-process.md)—refer to the [Work item field index](guidance/work-item-field.md). ### Field names -A work item field name uniquely identifies each work item field. Make sure your field names fall within these guidelines: +A work item field name uniquely identifies each work item field. Ensure your field names adhere to the following guidelines: -- Field names must be unique within the account/project collection -- Field names must be 128 or fewer Unicode characters -- Field names can't contain any leading or trailing spaces, nor two or more consecutive spaces -- Field names must contain at least one alphabetic character -- Field names can't contain the following characters: ```.,;'`:~\/\*|?"&%$!+=()[]{}<>```. +- **Uniqueness**: Field names must be unique within the account or project collection. +- **Length**: Field names must contain 128 Unicode characters or fewer. +- **Spacing**: Field names can't have leading or trailing spaces or contain two or more consecutive spaces. +- **Composition**: Field names must include at least one alphabetic character. +- **Prohibited Characters**: Field names can't include the following characters: `.,;'`:~/*|?"&%$!+=()[]{}<>`. -Because custom fields are defined for an organization or collection, you can't add a custom field to a process with the same field name that you add to another process. +Since custom fields are defined at the organization or collection level, you can't add a custom field with the same name to multiple processes. For more information, see [Naming restrictions and conventions](../../organizations/settings/naming-restrictions.md#work-items-work-item-types-and-customizations). - ### System and predefined fields -All system defined fields have reference names that begin with *System*, for example, System.AreaPath, System.AssignedTo, and continue in that pattern. +A work item field name uniquely identifies each field within Azure DevOps. Ensure your field names comply with the following guidelines: -Predefined fields defined by the default process begin with Microsoft.VSTS and then further differ based on their usage. Examples of predefined fields that are used in common, for scheduling purposes and integration with Office Project, for integration with Team Foundation Build, and integration with test case management (TCM) are as follows: +- **Uniqueness**: Field names must be unique within an account or project collection. +- **Length**: Field names must be 128 Unicode characters or fewer. +- **Spacing**: Field names can't have leading or trailing spaces or contain multiple consecutive spaces. +- **Composition**: Field names must include at least one alphabetic character. +- **Prohibited Characters**: Field names can't include the following characters: `.,;'`:~/*|?"&%$!+=()[]{}<>`. -- Microsoft.VSTS.Common.Priority -- Microsoft.VSTS.Scheduling.DueDate -- Microsoft.VSTS.Build.FoundIn -- Microsoft.VSTS.TCM.Steps +Since custom fields are defined at the organization or collection level, you can't add a custom field with the same name to multiple processes. -For an overview of all system and predefined fields that are defined for the default processes/process templates, see [Work item field index](guidance/work-item-field.md). For more information about specifying field names, see [Naming restrictions](../../organizations/settings/naming-restrictions.md). +For more information, see [Naming restrictions and conventions](../../organizations/settings/naming-restrictions.md#work-items-work-item-types-and-customizations). ### Custom fields -Because custom fields are defined for an organization or project collection, you can't add a custom field to a process with the same field name that you add to another process. - -When adding custom fields, note the following limits: -* A maximum of 64 fields can be defined for each WIT -* A maximum of 512 fields can be defined per process +Because custom fields are defined at the organization or project collection level, you can't add a custom field with the same name to multiple processes. -The field data type determines the kind and size of data that you can store in the field. A field can have only one type defined within a project collection. This restriction encourages organizations to use common fields across projects and work item types. +When adding custom fields, note the following limits: +- **Maximum fields per work item type (WIT):** 64 +- **Maximum fields per process:** 512 -::: moniker range=">= azure-devops-2019" +The field data type determines the kind and size of data that can be stored in the field. Each field can have only one type defined within a project collection, encouraging the use of common fields across different projects and work item types. -When you add a custom field to an inherited process, Azure DevOps assigns a reference name prefixed with *Custom* and then the name of the field with spaces removed. For example, you add a field named *DevOps Triage*, the reference name is **Custom.DevOpsTriage**. No spaces are allowed within the reference name. +When you add a custom field to an inherited process, Azure DevOps assigns a reference name prefixed with *Custom* followed by the field name without spaces. For example, adding a field named *DevOps Triage* results in the reference name **Custom.DevOpsTriage**. Spaces aren't allowed in reference names. -::: moniker-end +For more information, see [Naming restrictions and conventions](../../organizations/settings/naming-restrictions.md#work-items-work-item-types-and-customizations). ## How can I determine the field data type? @@ -134,47 +127,41 @@ You can view the data type of fields defined for your organization by [opening t ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - -When your project collection uses the Inheritance process model to customize work tracking, you can view the data type of fields by [opening the Process>Fields page](../work-items/work-item-fields.md#review-fields). +::: moniker range=" < azure-devops" -> [!div class="mx-imgBorder"] -> ![Screenshot of Collection Settings, Process, Fields page.](media/fields/list-fields.png) +When your project collection uses the **Inheritance** process model to customize work tracking, you can view the data type of fields by [opening the Process > Fields page](../work-items/work-item-fields.md#review-fields). -If the On-premises XML process model is used, you can look up the data type through the [Work item field index](guidance/work-item-field.md). Or, you can open the Work Item Field Explorer to review the fields defined and their attribute assignments, or use the **witadmin listfields** command to list the field attributes. For more information, see [Work Item Field Explorer](#wi-explorer) and [List field attributes](#list-attributes) later in this article. +> [!div class="mx-imgBorder"] +> ![Screenshot of Collection Settings, Process, Fields page.](media/fields/list-fields.png) -::: moniker-end +If your project collection uses the **On-premises XML** process model, you can determine the data type through the [Work item field index](guidance/work-item-field.md). Alternatively, you can: -::: moniker range="tfs-2018" +- Open the **Work Item Field Explorer** to review defined fields and their attributes. +- Use the **witadmin listfields** command to list field attributes. -You can look up the data type through the [Work item field index](guidance/work-item-field.md). Or, you can open the Work Item Field Explorer to review the fields defined and their attribute assignments, or use the **witadmin listfields** command to list the field attributes. For more information, see [Work Item Field Explorer](#wi-explorer) and [List field attributes](#list-attributes) later in this article. +For more information, see [Work Item Field Explorer](#wi-explorer) and [List field attributes](#list-attributes) later in this article. ::: moniker-end - + -::: moniker range=">= azure-devops-2019" +## Review fields list -## Process>Fields web page +To review the list of fields defined for an organization or collection, do the following steps: -To review the list of fields defined for an organization or collection, open **Organization settings>Process>Fields**. - -1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Then choose **Organization settings**. +1. Select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Then choose **Organization settings**. > [!div class="mx-imgBorder"] > ![Screenshot of Choose Organization settings.](../../media/settings/open-admin-settings-vert.png) -1. Then, choose **Process**. +2. Select **Process**. > [!div class="mx-imgBorder"] - > ![Screenshot of Choose Process.](/azure/devops/organizations/settings/work/media/process/open-process-page-s150.png) + > ![Screenshot of Choose Process.](/azure/devops/organizations/settings/work/media/process/open-process-page-s150.png) - > [!NOTE] - > If you don't see **Process**, then you're working from TFS-2018 or earlier version. The **Process** page isn't supported. You must use the features supported for the [On-premises XML process model](../../reference/customize-work.md). +3. Select **Fields**. -1. Then, choose **Fields**. - - Fields listed correspond to all fields defined for the organization or collection. This includes all custom fields and those defined for system processes. + Fields listed correspond to all fields defined for the organization or collection, which includes all custom fields and the fields defined for system processes. > [!div class="mx-imgBorder"] > ![Screenshot of Make a copy of a selected inherited process.](media/fields/list-fields.png) @@ -182,13 +169,9 @@ To review the list of fields defined for an organization or collection, open **O > [!NOTE] > If you don't see **Fields**, then your collection uses the On-premises XML process. The Fields page isn't supported for that process. - For descriptions and usage of each field, as well as the Reference name for each field, you can look it up from the [Work item field index](guidance/work-item-field.md). You can also get the Reference name of fields from the [Work Item Types Field - List REST API](/rest/api/azure/devops/wit/work-item-types-field/list). - - -::: moniker-end - + For descriptions, usage, and reference names of each field, refer to the [Work item field index](guidance/work-item-field.md). Additionally, you can retrieve field reference names using the [Work Item Types Field - List REST API](/rest/api/azure/devops/wit/work-item-types-field/list). - + ## Work Item Field Explorer @@ -196,19 +179,17 @@ You can look up the assignments of field attributes using the Work Item Field Ex ![Screenshot of Work item field explorer.](media/fields/work-item-field-explorer.png) - -To access the Work Item Field Explorer, you must install the Process Editor Tool. Based on the version of Visual Studio you have installed, get the Process Editor Tool from one of the following extensions. +To access the Work Item Field Explorer, install the Process Editor Tool. Based on your installed version of Visual Studio, get the Process Editor Tool from one of the following extensions. [!INCLUDE [temp](../../includes/process-editor-tool.md)] - - + ## Field attributes -There are many non-changeable and hidden attributes for each work item field. The following table describes each attribute. Attributes have different names based on if you get them through the [**Fields - Get** **REST** API](/rest/api/azure/devops/wit/fields/get) or view through the [Work Item Field Explorer (**WIFE**) tool](#wi-explorer). +There are many nonchangeable and hidden attributes for each work item field. The following table describes each attribute. Attributes have different names depending on whether you retrieve them through the [**Fields - Get REST API**](/rest/api/azure/devops/wit/fields/get) or view them through the [Work Item Field Explorer (**WIFE**) tool](#wi-explorer). -Attributes assigned to a field depend on the platform and version you use. For example, some attributes aren't support with the Inheritance process. To look up the reference name for a field, see [Work item field index](guidance/work-item-field.md). +Attributes assigned to a field depend on the platform and version you're using. For example, some attributes aren't supported with the Inheritance process. To look up the reference name for a field, see the [Work item field index](guidance/work-item-field.md). :::row::: :::column span="1"::: @@ -322,7 +303,7 @@ Attributes assigned to a field depend on the platform and version you use. For e boolean :::column-end::: :::column span="3"::: - Indicates if users can modify this field (True) or not (False). Examples of non-editable fields are ones that are set by the system, such as the **ID**, **Revision**, **Created By**, and **Changed By** fields + Indicates if users can modify this field (True) or not (False). Examples of noneditable fields are ones that are set by the system, such as the **ID**, **Revision**, **Created By**, and **Changed By** fields Can change?=No :::column-end::: :::row-end::: @@ -371,7 +352,7 @@ Attributes assigned to a field depend on the platform and version you use. For e WIFE: :::column-end::: :::column span="1"::: - boolean + Boolean :::column-end::: :::column span="3"::: Indicates whether the field is associated with a picklist. The value is set to *True* when a custom field is defined for Azure DevOps and Picklist (String) or Picklist (Integer) type is selected. The value is set to *False* for inherited fields that define picklists. @@ -384,7 +365,7 @@ Attributes assigned to a field depend on the platform and version you use. For e WIFE: :::column-end::: :::column span="1"::: - boolean + Boolean :::column-end::: :::column span="3"::: Indicates whether the field allows users to enter their own values for a picklist. The value is set to *True* when a custom field is defined for Azure DevOps, Picklist (String), or Picklist (Integer) type is selected, and the checkbox for **Allow users to set their own values** is checked. @@ -453,7 +434,7 @@ Attributes assigned to a field depend on the platform and version you use. For e :::column-end::: :::column span="3"::: Friendly name assigned to the field. The friendly name can't be changed for Azure DevOps, but can be changed for on-premises using the **witadmin changefield** command. - Can change?=On-prem only + Can change?=On-premises only :::column-end::: :::row-end::: :::row::: @@ -479,7 +460,7 @@ Attributes assigned to a field depend on the platform and version you use. For e :::column-end::: :::column span="3"::: Gets the collection of prohibited values for a field that specifies such values. You can only define prohibited values for on-premises deployments. - Can change?=On-prem only + Can change?=On-premises only :::column-end::: :::row-end::: :::row::: @@ -488,10 +469,10 @@ Attributes assigned to a field depend on the platform and version you use. For e WIFE: :::column-end::: :::column span="1"::: - boolean + Boolean :::column-end::: :::column span="3"::: - Indicates whether the field is set to read only. For Azure DevOps Services, only custom fields can be changed to be read-only. System fields cannot be modified. + Indicates whether the field is set to read only. For Azure DevOps Services, only custom fields can be changed to be read-only. System fields can't be modified. Can change?=Yes :::column-end::: :::row-end::: @@ -518,7 +499,7 @@ Attributes assigned to a field depend on the platform and version you use. For e :::column-end::: :::column span="3"::: Specifies **Detail**, **Dimension**, or **Measure**, depending on whether and how you want the field to be included in reports. Data from fields that have a value other than **None** for this attribute are exported to the data warehouse and can be included in SQL reports. - Can change?=On-prem only + Can change?=On-premises only :::column-end::: :::row-end::: :::row::: @@ -625,46 +606,53 @@ Attributes assigned to a field depend on the platform and version you use. For e ## Reportable attributes -All reporting attributes are valid only for on-premises deployments whose projects have been configured to support SQL Server Reporting and SQL Server Analysis Services. For more information, see [Add reports to a project](/previous-versions/azure/devops/report/admin/add-reports-to-a-team-project). +All reporting attributes are valid only for on-premises deployments where projects are configured to support SQL Server Reporting and SQL Server Analysis Services. For more information, see [Add reports to a project](/previous-versions/azure/devops/report/admin/add-reports-to-a-team-project). -For a description of each reportable attribute, see [Add or modify work item fields to support reporting]((/previous-versions/azure/devops/reference/xml/add-or-modify-work-item-fields-to-support-reporting). +For descriptions of each reportable attribute, refer to [Add or modify work item fields to support reporting](/previous-versions/azure/devops/reference/xml/add-or-modify-work-item-fields-to-support-reporting). -For a list of fields that have reportable attributes defined by default, see [Reportable fields reference](/previous-versions/azure/devops/reference/xml/reportable-fields-reference) . +To see a list of fields with reportable attributes defined by default, see [Reportable fields reference](/previous-versions/azure/devops/reference/xml/reportable-fields-reference). ::: moniker-end - + ::: moniker range="< azure-devops-2022" ## Indexed fields -You can enable or disable indexing for a work item field by using the **witadmin indexfield** command. When you enable indexing for a field, you may increase the performance of finding work items whose queries specify that field. By default, the following fields are indexed: Assigned To, Created Date, Changed By, State, Reason, Area ID, Iteration ID, and Work Item Type. +Use the **witadmin indexfield** command to enable or disable indexing for a work item field. Enabling indexing for a field can improve the performance of queries that specify that field. By default, the following fields are indexed: -If you add a custom field that you use in many of your work item queries, you may want to enable indexing for that field. For more information, see [Manage work item fields (witadmin)](../../reference/witadmin/manage-work-item-fields.md). +- Assigned To +- Created Date +- Changed By +- State +- Reason +- Area ID +- Iteration ID +- Work Item Type -::: moniker-end +If you add a custom field used frequently in your work item queries, consider enabling indexing for that field. For more information, see [Manage work item fields (witadmin)](../../reference/witadmin/manage-work-item-fields.md). +::: moniker-end - + ## List field attributes ::: moniker range="azure-devops" -You can list the attributes assigned to a field by using the [**Fields - Get** REST API](/rest/api/azure/devops/wit/fields/get). Enter your organization name for *OrganizationName*. +You can list the attributes assigned to a field by using the [**Fields - Get REST API**](/rest/api/azure/devops/wit/fields/get). Replace *OrganizationName* with your actual organization name. > [!div class="tabbedCodeSnippets"] > ```REST > https://dev.azure.com/OrganizationName/_apis/wit/fields/FieldReferenceName > ``` -For example, here we list the attributes for the Iteration Path, specifying the reference name, `System.IterationPath`, for the fabrikam organization. +For example, to list the attributes for the Iteration Path, use the reference name `System.IterationPath` for the `fabrikam` organization: ```REST https://dev.azure.com/fabrikam/_apis/wit/fields/System.IterationPath -``` **Returned data:** @@ -775,7 +763,7 @@ https://fabrikam:8080/tfs/DefaultCollection/_apis/wit/fields/System.IterationPat ::: moniker-end -::: moniker range="< azure-devops" +::: moniker range=" < azure-devops" ### List attributes using `witadmin` command-line tool @@ -804,15 +792,6 @@ The **Use** parameter indicates the name of each project and the work item type ::: moniker-end - -::: moniker range="tfs-2018" - -## Project integration and project field mapping - -You can change how work tracking fields map to fields in Project, and you can change how specific fields are published. See [The Microsoft Project Field Mapping File](/previous-versions/azure/devops/reference/xml/customize-project-field-mapping-file). - -::: moniker-end - ## Add and modify fields ::: moniker range="azure-devops" @@ -821,7 +800,7 @@ To add fields to a process, you add them to one or more work item types. For mor ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" You can add or modify the fields contained within a WIT or add a custom WIT. For more information, see: - For project collections that use the Inheritance process model: [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md). @@ -831,43 +810,22 @@ You can change the field name, the index, and the report attributes for any fiel ::: moniker-end -::: moniker range="< azure-devops-2019" - -To add fields to a project, you add them to one or more work item types. See [Add or modify a field to track work](../../reference/add-modify-field.md). - -You can change the field name, the index, and the report attributes for any field except system fields by using the **witadmin** command-line tool. For more information, see [Manage work item fields-witadmin](../../reference/witadmin/manage-work-item-fields.md). - -::: moniker-end - - ## Related articles ::: moniker range="azure-devops" -- [Query quick reference](../queries/query-index-quick-ref.md) -- [Work item field index](guidance/work-item-field.md) -- [Add and manage fields for an inherited process](../../organizations/settings/work/customize-process-field.md) -- [Metadata reference for Azure Boards Analytics](../../report/analytics/entity-reference-boards.md) -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - -- [Query quick reference](../queries/query-index-quick-ref.md) -- [Work item field index](guidance/work-item-field.md) -- [Choose the process model for your project collection](../../reference/customize-work.md#choose-process-model) -- [Add or modify a field to track work](../../reference/add-modify-field.md) -- [Manage work item fields using witadmin](../../reference/witadmin/manage-work-item-fields.md) -- [Metadata reference for Azure Boards Analytics](../../report/analytics/entity-reference-boards.md) - -::: moniker-end - -::: moniker range="tfs-2018" - -- [Query quick reference](../queries/query-index-quick-ref.md) -- [Work item field index](guidance/work-item-field.md) -- [Add or modify a field to track work](../../reference/add-modify-field.md) -- [Manage work item fields-witadmin](../../reference/witadmin/manage-work-item-fields.md) - +- [Refer to the Query quick reference](../queries/query-index-quick-ref.md) to quickly understand query syntax and usage. +- [Explore the Work item field index](guidance/work-item-field.md) to view all available work item fields. +- [Add and manage fields for an inherited process](../../organizations/settings/work/customize-process-field.md) to customize fields according to your inherited process requirements. +- [Access the metadata reference for Azure Boards Analytics](../../report/analytics/entity-reference-boards.md) to understand analytics metadata and reporting capabilities. ::: moniker-end +::: moniker range=" < azure-devops" +- [Refer to the Query quick reference](../queries/query-index-quick-ref.md) to quickly understand query syntax and usage. +- [Explore the Work item field index](guidance/work-item-field.md) to view all available work item fields. +- [Choose the process model for your project collection](../../reference/customize-work.md#choose-process-model) to select the appropriate process model for your needs. +- [Modify a work item field](../../reference/add-modify-field.md) according to your project's requirements. +- [Manage work item fields using witadmin](../../reference/witadmin/manage-work-item-fields.md) to perform advanced field management tasks. +- [Access the metadata reference for Azure Boards Analytics](../../report/analytics/entity-reference-boards.md) to understand analytics metadata and reporting capabilities. +::: moniker-end diff --git a/docs/boards/work-items/work-item-form-controls.md b/docs/boards/work-items/work-item-form-controls.md deleted file mode 100644 index e5ae52cb1c0..00000000000 --- a/docs/boards/work-items/work-item-form-controls.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: Use work item form controls in Azure Boards -titleSuffix: Azure Boards -description: Learn how to use work item form controls to update status, link work items, and more in Azure Boards. -ms.custom: work-items, engagement-fy23 -ms.service: azure-devops-boards -ms.assetid: A9AB9B95-61B4-41E7-AE7A-B96CD4AF9B33 -ms.topic: conceptual -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 02/03/2023 ---- - -# Work item form controls - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Different types of work items track different data. Each work item form contains some standard fields—such as title, assigned to, and area and iteration path—and to fields specific to the type. You can link work items to one another and to changesets and source code files. - -### Web portal form - -As the following image shows, each work item form comes with several controls, fields, and tabs. Keep in mind that the work item tracking experience and forms that appear in Visual Studio won't show several of the features that the web portal makes available. - -![Screenshot of work item form to track features or user stories.](media/about-work-items/work-item-form-user-story.png) - - -::: moniker range=">= azure-devops-2019" - -> [!NOTE] -> Depending on the process chosen when the project was created—[Agile](./guidance/agile-process.md), [Basic](../get-started/plan-track-work.md), [Scrum](./guidance/scrum-process.md), or [CMMI](./guidance/cmmi-process.md)—the types of work items you can create differ. For example, backlog items may be called user stories (Agile), product backlog items (Scrum), or requirements (CMMI). All three are similar: they describe the customer value to deliver and the work to be performed. -> -> For more information, see [About processes and process templates](./guidance/choose-process.md). - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -> [!NOTE] ->Depending on the process chosen when the project was created—[Agile](./guidance/agile-process.md), [Scrum](./guidance/scrum-process.md), or [CMMI](./guidance/cmmi-process.md)—the types of work items you can create differ. For example, backlog items may be called user stories (Agile), product backlog items (Scrum), or requirements (CMMI). All three are similar: they describe the customer value to deliver and the work to be performed. -> -> FFor more information, see [About processes and process templates](./guidance/choose-process.md). - -::: moniker-end - - - - -### Form controls - -| Control | Function | -|--------------------------|-------------------------------| -| ![Copy to clipboard icon](../backlogs/media/icon-copy-to-clipboard.png) | Copy URL of work item to clipboard (appears on hover over work item title) | -| ![Discussions icon](../media/icons/icon-discussions-wi.png) | Go to Discussions section | -| :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: | Open Actions menu for other work item tasks | -| ![Refresh icon](../media/icons/icon-refresh-wi.png) | Refresh work item with latest changes | -| ![Undo icon](../media/icons/icon-undo-changes-wi.png) | Revert changes to work item | -| ![History tab icon](../media/icons/icon-history-tab-wi.png) | Open History tab | -| ![Links tab icon](../media/icons/icon-links-tab-wi.png) | Open Links tab | -| ![Attachment tab icon](../backlogs/media/icon-attachments-tab-wi.png) | Open Attachments tab | -| ![full screen icon](../media/icons/fullscreen_icon.png) / ![exit full screen icon](../media/icons/exitfullscreen_icon.png) | Enter or exit full display mode of a section within the form | -|![Collapse section icon](../media/icons/collapse-wi-section.png)/![Expand section icon](../media/icons/expand-wi-section.png) | Collapse or expand a section within the form | -| ![New linked work item icon](../media/icons/new-linked-work-item.png) | Add new work item and link to existing work item (May appear under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | -| ![Change work item type icon](../media/icons/change-type-icon.png) | [Change work item type](../backlogs/remove-delete-work-items.md) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | -| ![Change project icon](../media/icons/change-team-project-icon.png) | [Move work item to a different project](../backlogs/remove-delete-work-items.md) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | -| ![Clone icon](../media/icons/clone-icon.png) | [Copy work item and optionally change work item type](../backlogs/copy-clone-work-items.md#copy-clone) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | -| ![Email icon](../media/icons/email-icon.png) | [Email work item](email-work-items.md) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | -| ![Delete icon](../media/icons/delete_icon.png) | [Recycle work item](../backlogs/remove-delete-work-items.md) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | -| ![Storyboard icon](../media/icons/storyboard-icon.png) | [Storyboard with PowerPoint](/previous-versions/azure/devops/boards/backlogs/office/storyboard-your-ideas-using-powerpoint) (Appears under :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: Actions menu) | - - - -## Update work status - -As work progresses, team members can update the state and reassign it as needed. - -![Product backlog item workflow, Scrum process](../backlogs/media/add-work-item-vsts-update-state.png) - -While the workflow states differ for different work item types, they usually follow a progression from New or Active to Closed or Done. The following image shows the work flow states for the Agile process user story. If you want to discard a work item, change the state to Removed. - -:::row::: - :::column span="2"::: - - **Typical workflow progression:** - - Create a user story in the default state, New. - - Change the state from New to Active. - - Change the state from Active to Resolved. - - Change the state from Resolved to Closed. - - **Atypical transitions:** - - Change the state from New to Removed. - - Change the state from Removed to New. - - Change the state from Active to Removed. - - Change the state from Resolved to Active. - - Change the state from Closed to Resolved. - - :::column-end::: - :::column span="1"::: - - ![Work flow states for the Agile process user story.](./guidance/media/ALM_PT_Agile_WF_UserStory.png) - :::column-end::: -:::row-end::: - -Removed work items remain in the data store and can be reactivated by changing the State. If you want to permanently remove a work item, you can [delete it](../backlogs/remove-delete-work-items.md). - -With each update, the Reason field also updates and changes are recorded in the History field, which you can view through the ![history tab icon](../media/icons/icon-history-tab-wi.png) **History** tab. To find work items based on their history, see [History & auditing](../queries/history-and-auditing.md). - -![View change history](../backlogs/media/add-work-item-history.png) - - - - - -## Link items to support traceability - -By linking work items using Related or Dependent link types, you can track work that is dependent on other work. Each work item contains one or more tabs with link controls. These controls support linking the work item to one or more objects. - - -::: moniker range=">= azure-devops-2020" - -There are four links controls provided on most forms. The **Deployment**, **Development**, and **Related Work** scoped links controls appear on the **Details** tab. The ![Links page icon](../media/icons/icon-links-tab-wi.png) **Links** tab provides access to all links made to the work item. - -:::image type="content" source="media/linkscontrol-bug-form-dev-related-links-azure-devops.png" alt-text="Screenshot of Bug work item form, Agile process, Deployment, Development, and Related links controls."::: -::: moniker-end - -::: moniker range="< azure-devops-2020" - -There are three links controls provided on most forms. The **Development** and **Related Work** scoped links controls appear on the **Details** tab. The ![Links page icon](../media/icons/icon-links-tab-wi.png) **Links** tab provides access to all links made to the work item. - -![Screenshot of Bug work item form, Agile process, Development and Related links controls.](media/linkscontrol-bug-form-dev-related-links.png) - -::: moniker-end - - -## Add links - -From each links control, you can complete these actions: - -- To open an associated item or object, select the linked item -- To delete a link, highlight it and select the ![delete icon](../media/icons/delete_icon.png) delete icon -- To link to an existing work item, or create and link to a new work item, select one of the menu options from the **Related Work** control. - -::: moniker range=">= azure-devops-2019" -:::image type="content" source="media/linkscontrol-related-work-menu-options-azure-devops.png" alt-text="Screenshot of Related Links control menu options. "::: -::: moniker-end - -::: moniker range="tfs-2018" -![Screenshot of Related Links control menu options, TFS 2018.](media/linkscontrol-related-work-menu-options.png) -::: moniker-end - -For more information, see [Add links to work items](../backlogs/add-link.md). - - - -::: moniker range=">= azure-devops-2020" - -### Deployment control - -The **Deployment** control supports a quick view of where and when a work item has been deployed and to what stage. You gain visual insight into the status of a work item as it is deployed to different release environments and quick navigation to each release stage and run. -For more information, see [Link work items to builds and deployments](work-item-deployments-control.md). - -:::image type="content" source="media/deployments-control/deployment-control-intro.png" alt-text="Screenshot of Deployment control with links to production and staging runs. "::: - -::: moniker-end - - - - -### Development control - -The **Development** control displays all of your development links, whether based on a Git repository or Team Foundation version control (TFVC) repository. It displays links in a set order, and provides calls-to-action that support users to [drive development from a work item](../backlogs/connect-work-items-to-git-dev-ops.md). - -Git lets you link work items to commits by using the **Commit**, **Pull Request**, or **Branch link** types. To learn how, see [Manage and commit your changes](../../repos/git/commits.md). - -If you've connected your Azure DevOps project to a GitHub repository, you can link to GitHub commits, PRs, and issues. To learn how, see [Link GitHub commits, pull requests, and issues to work items](../github/link-to-from-github.md). - -Team Foundation version control (TFVC) lets you link work items to version control changesets or versioned source code files by using the Changeset and Versioned Item link types. When you check in pending changes or use My Work to check in changes, [work items are automatically linked to your changes](../../repos/tfvc/check-your-work-team-codebase.md). - - -### Related scoped links control - -The Related Work links control displays links to other work items in a set order on the front page of the form. It supports these link types: Duplicate/Duplicate of, Parent/Child, Predecessor/Successor, Related, and Tests/Tested by. To learn more about different link types, see [Linking, traceability, and managing dependencies](../queries/link-work-items-support-traceability.md). - -### Links control tab - -Also, the Links control tab provides access to all links made to the work item—both work items and external objects. - -![Agile process, User Story work item form, Links control tab](../backlogs/media/add-work-item-links.png) - - - -[!INCLUDE [temp](../includes/discussion-tip.md)] - - - -## Copy the URL - -From the web portal, simply copy the URL from the web browser address or hover over the title and then select the :::image type="icon" source="../../media/icons/copy-clone-icon.png" border="false"::: copy icon. For other copy options, see [Copy or clone work items](../backlogs/copy-clone-work-items.md). - -![Copy hyperlink for a work item from web portal](../backlogs/media/add-work-item-copy-URL.png) - -::: moniker range="<= azure-devops-2019" - - - - -## Use the Start storyboarding menu option - -> [!IMPORTANT] -> Starting with Visual Studio 2019, the Azure DevOps Office Integration plug-in has deprecated support for Storyboarding with PowerPoint and Microsoft Project. Also, the Visual Studio Gallery for PowerPoint Storyboarding has been deprecated. - -The **Start storyboarding** menu option is only available from the new web form. However, from the old web form, you can choose the **Start Storyboarding** link from the **Storyboard** tab from a backlog item, or open PowerPoint. See [Storyboard your ideas using PowerPoint](/previous-versions/azure/devops/boards/backlogs/office/storyboard-your-ideas-using-powerpoint) for requirements and usage. - -You can storyboard your ideas using PowerPoint to bring your ideas to life with storyboard shapes, text, animation, and all the other features that PowerPoint Storyboarding provides. From any work item, you can open PowerPoint by choosing the Start storyboarding menu option. - -![Work item form, Start storyboarding menu option](../backlogs/media/add-work-item-start-storyboarding.png) - - -::: moniker-end - -## Related articles - -- [Run a semantic work item search](../queries/search-box-queries.md) -- [Keyboard shortcuts](../../project/navigation/keyboard-shortcuts.md) -- [Customize your work tracking experience](../../reference/customize-work.md) - diff --git a/docs/boards/work-items/work-item-template-examples.md b/docs/boards/work-items/work-item-template-examples.md index bea5e195cfe..bffc5619a16 100644 --- a/docs/boards/work-items/work-item-template-examples.md +++ b/docs/boards/work-items/work-item-template-examples.md @@ -39,7 +39,7 @@ In this example, the Voice team sets the Area Path=`Fabrikam Fi > [!div class="mx-imgBorder"] > ![Specify the Area Path.](media/template/area-path.png) -To learn more about area paths, see [About area and iteration (sprint) paths](../../organizations/settings/about-areas-iterations.md). +For more information about area paths, see [About area and iteration (sprint) paths](../../organizations/settings/about-areas-iterations.md). @@ -63,11 +63,6 @@ The work item form renders this example as shown. > [!div class="mx-imgBorder"] > ![Rendered syntax in work item form.](media/template/repo-steps-rendered.png) - -For more information about rich-text fields, see [Share information within work items and social tools](../queries/share-plans.md). - - - ## Add work item tags @@ -81,7 +76,7 @@ For example, here we add Web and Sept Release. > [!div class="mx-imgBorder"] > ![Add tags to work items.](media/template/add-tags.png) -To learn more about tags, see [Add work item tags to categorize and filter lists and boards](../queries/add-tags-to-work-items.md). +For more information about tags, see [Add work item tags to categorize and filter lists and boards](../queries/add-tags-to-work-items.md). You can also use the Tags (Remove) template field to remove tags from work items. For example, if many work items were tagged with Milestone 1, and that no longer applies, you could query for all those work items and remove the tag by doing a bulk apply of a template that removed the Milestone 1 tag. diff --git a/docs/boards/work-items/work-item-url-hyperlink.md b/docs/boards/work-items/work-item-url-hyperlink.md deleted file mode 100644 index ac4e7dd9f14..00000000000 --- a/docs/boards/work-items/work-item-url-hyperlink.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Define the hyperlink for a work item -titleSuffix: Azure Boards -description: Learn how to construct a URL for a work item for Azure Boards and Azure DevOps. -ms.custom: work-items, seodec18 -ms.service: azure-devops-boards -ms.author: chcomley -author: chcomley -ms.topic: how-to -monikerRange: '<= azure-devops' -ms.date: 03/02/2022 ---- - - -# Define the URL for a work item - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -You can define the URL for a work item using the syntax provided based on the version or platform you work from. - -[!INCLUDE [temp](../../includes/version-selector-minimize.md)] - -Examples in this article use the following conventions: - -- *OrganizationName* specifies the name of the Azure Boards organization -- *ServerName* specifies the name of the Azure DevOps application tier server -- *Port* specifies the port, default=8080 -- *CollectionName* specifies the name of the project collection. -- *ProjectName* specifies the project name -- *WorkItemNumber* specifies the ID of the bug, task, or other work item. - - -## Azure DevOps Services - - -``` -https://dev.azure.com/OrganizationName/ProjectName/_workitems/edit/WorkItemNumber -``` - -or - -``` -https://OrganizationName.visualstudio.com/DefaultCollection/ProjectName/_workitems/edit/WorkItemNumber -``` - - -**Examples:** - -``` -https://dev.azure.com/fabrikam/Phone%20Saver/_workitems/edit/390 -``` - -or - -``` -https://fabrikam/DefaultCollection/Phone%20Saver/_workitems/edit/390 -``` - -## Azure DevOps Server 2020 - - -http://*ServerName:Port/CollectionName/ProjectName*/_workitems?id=*WorkItemNumber*&_a=edit - -**Example:** -``` -http://fabrikamprime:8080/DefaultCollection/Phone%20Saver/_workitems/133&_a=edit -``` - -## Azure DevOps Server 2019 and earlier versions - - -http://*ServerName:Port*/**tfs**/*CollectionName/ProjectName*/**_workitems?id**=*WorkItemNumber***&_a=edit** - -**Example:** -``` -http://fabrikamprime:8080/tfs/DefaultCollection/Phone%20Saver/_workitems/133&_a=edit -``` - - -::: moniker range=">= azure-devops-2020" - -## Share links in context with your board or backlog - -Share links to work items within the context of your board or backlog with the work item URL parameter. When you open a work item form from your board, backlog, or sprint backlog, the parameter `?workitem=[ID]` is appended to the URL. - -For example: - -::: moniker-end - -::: moniker range="azure-devops" - -``` -https://dev.azure.com/fabrikam/FabrikamFiber/_boards/board/t/Voice/Stories/?showParents=true&workitem=191 -``` -::: moniker-end - -::: moniker range="azure-devops-2020" - -``` -https://ServerName/DefaultCollection/ProjectName/_boards/board/t/Voice/Stories/?workitem=56 -``` -::: moniker-end - -::: moniker range=">= azure-devops-2020" - -Anyone you share the link with, opens the work item within the same context you had when you shared the link. - -::: moniker-end - - diff --git a/docs/boards/work-items/workflow-and-state-categories.md b/docs/boards/work-items/workflow-and-state-categories.md index 259be6deee8..f4d41ba1534 100644 --- a/docs/boards/work-items/workflow-and-state-categories.md +++ b/docs/boards/work-items/workflow-and-state-categories.md @@ -1,44 +1,38 @@ --- title: How workflow category states are used in Azure Boards backlogs and boards -titleSuffix: Azure Boards -description: Understand how workflow states map to workflow category states and are used in Azure Boards backlogs, boards, and Analytics in Azure Boards. -ms.custom: seodec18 +titleSuffix: Azure Boards +description: Learn how workflow states map to workflow category states and how to use them in Azure Boards backlogs, boards, and Analytics to manage work items effectively. ms.service: azure-devops-boards ms.assetid: C6FEEE5A-CD13-413E-8A3F-84A7D4F3A2C9 +ai-usage: ai-assisted ms.author: chcomley -author: chcomley +author: chcomley ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 04/04/2023 +ms.date: 11/08/2024 --- -# How workflow category states are used in Azure Boards backlogs and boards +# About workflow states in backlogs and boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -All workflows consist of states, transitions, and reasons. Workflows are defined for a work item type. A transition supports forward and backward movement among two states. When you add a custom state, the system automatically adds transitions from the custom state to all other inherited states (except for Removed). +Workflows are essential for managing work items, consisting of states, transitions, and reasons. Each workflow is defined for a specific work item type. Transitions allow movement between states, both forward and backward. When you add a custom state, the system automatically includes transitions to all other inherited states, except for the Removed state. -Each state belongs to a state category (previously referred to as a metastate). State categories support the Agile tool backlog and board views. - - +Each state is categorized to support Agile tool backlogs and board views, ensuring a streamlined and organized workflow process. ## Workflow states -Workflow states define how a work item progresses from its creation to closure. The four main states that are defined for the User Story (Agile process) describe a user story's progression. The workflow states are New, Active, Resolved, and Closed. (The Removed state supports removing a work item from appearing on the backlog; for more information, see [Move, change, or delete work items](../backlogs/remove-delete-work-items.md#remove).) +Workflow states define how a work item progresses from creation to closure. For the User Story (Agile process), the main states are New, Active, Resolved, and Closed. The Removed state is used to remove a work item from the backlog; for more information, see [Move, change, or delete work items](../backlogs/remove-delete-work-items.md#remove). -The natural progressions and regressions for the work item types—user story (Agile), issue (Basic) product backlog item (SCrum), and requirement (CMMI)—are as shown. +The natural progressions and regressions for work item types—user story (Agile), issue (Basic), product backlog item (Scrum), and requirement (CMMI)—are as shown. [!INCLUDE [temp](../includes/four-process-workflow.md)] - - - ## Category states -Category states determine how Agile planning tools and select dashboard widgets treat each workflow state. The state categories used by the backlogs, boards and widgets are *Proposed*, *In Progress*, *Resolved*, and *Complete*. - -Here's how the default, inherited states map to the category states for the four system processes, including Test Plan work item types. The workflow states for Test Case, Test Design, and Test Suite are the same across all four system processes. +Category states determine how Agile planning tools and dashboard widgets treat each workflow state. Work item types use state categories to track progress. These states apply across all projects using the same process and affect how work items appear on backlogs and boards. The state categories used by backlogs, boards, and widgets are *Proposed*, *In Progress*, *Resolved*, and *Complete*. +The following table shows how the default, inherited states map to the category states for the four system processes, including Test Plan work item types. The workflow states for Test Case, Test Design, and Test Suite are the same across all four system processes. #### [Agile process](#tab/agile-process) @@ -55,7 +49,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Proposed:** Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the Kanban boards and Taskboards map to a Proposed state category. + **Proposed:** Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the boards and Taskboards map to a Proposed state category. :::column-end::: :::column span="1"::: New @@ -66,7 +60,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **In Progress:** Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on Kanban boards. + **In Progress:** Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on boards. :::column-end::: :::column span="1"::: Active (Bug, Epic, Feature, User Story) @@ -77,7 +71,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Resolved:** Assigned to states that represent a solution has been implemented, but aren't yet verified. Generally these states apply to bugs. Work items in a *Resolved* category state appear on the backlog by default. The Agile tools treat the *Resolved* category state exactly the same as the *In Progress* category state. + **Resolved:** Assigned to states that represent a solution was implemented, but not yet verified. Generally these states apply to bugs. Work items in a *Resolved* category state appear on the backlog by default. You can also include *Resolved* states in burndown charts, providing a more accurate tracking of progress. The Agile tools treat the *Resolved* category state exactly the same as the *In Progress* category state. :::column-end::: :::column span="1"::: Resolved (Bug) @@ -88,7 +82,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Completed:** Assigned to states that represent work that has finished. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the Kanban board. You can't modify states in this category nor can you add states to this category. + **Completed:** Assigned to states that represent work that's complete. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the board. You can't modify states in this category nor can you add states to this category. :::column-end::: :::column span="1"::: Closed (Bug, Epic, Feature, User Story) @@ -127,7 +121,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Proposed:** Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the Kanban boards and Taskboards map to a Proposed state category. + **Proposed:** Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the boards and Taskboards map to a Proposed state category. :::column-end::: :::column span="1"::: To Do @@ -138,7 +132,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **In Progress:** Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on Kanban boards. + **In Progress:** Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on boards. :::column-end::: :::column span="1"::: Doing @@ -149,7 +143,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Resolved:** Assigned to states that represent a solution has been implemented, but aren't yet verified. Generally these states apply to bug WITs. Work items in a Resolved state appear on the backlog by default. The Agile tools treat the Resolved state category exactly the same as the In Progress state category. + **Resolved:** Assigned to states that represent a solution was implemented, but not yet verified. Generally these states apply to bug work item types. Work items in a *Resolved* state appear on the backlog by default. You can also include *Resolved* states in burndown charts, providing a more accurate tracking of progress. The Agile tools treat the *Resolved* state category exactly the same as the In Progress state category. :::column-end::: :::column span="1"::: n/a @@ -160,7 +154,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Completed:** Assigned to states that represent work that has finished. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the Kanban board. You can't modify states in this category nor can you add states to this category. + **Completed:** Assigned to states that represent completed work. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the board. You can't modify states in this category nor can you add states to this category. :::column-end::: :::column span="1"::: Done @@ -197,7 +191,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Proposed:** Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the Kanban boards and Taskboards map to a Proposed state category. + **Proposed:** Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the boards and Taskboards map to a Proposed state category. :::column-end::: :::column span="1"::: New (Bug, Epic, Feature, Product backlog item) Approved To Do (Task) @@ -208,7 +202,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **In Progress:** Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on Kanban boards. + **In Progress:** Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on boards. :::column-end::: :::column span="1"::: Committed (Bug, Epic, Feature, Product backlog item) Open (Impediment) @@ -219,7 +213,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Resolved:** Assigned to states that represent a solution has been implemented, but aren't yet verified. Generally these states apply to bugs. Work items in a *Resolved* category state appear on the backlog by default. The Agile tools treat the *Resolved* category state exactly the same as the *In Progress* state category. + **Resolved:** Assigned to states that represent a solution was implemented, but not yet verified. Generally these states apply to bugs. Work items in a *Resolved* category state appear on the backlog by default. You can also include *Resolved* states in burndown charts, providing a more accurate tracking of progress. The Agile tools treat the *Resolved* category state exactly the same as the *In Progress* state category. :::column-end::: :::column span="1"::: n/a @@ -230,7 +224,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Completed:** Assigned to states that represent work that has finished. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the Kanban board. You can't modify states in this category nor can you add states to this category. + **Completed:** Assigned to states that represent completed work. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the board. You can't modify states in this category nor can you add states to this category. :::column-end::: :::column span="1"::: Done @@ -267,7 +261,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Proposed:** Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the Kanban boards and Taskboards map to a Proposed state category. + **Proposed:** Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the boards and Taskboards map to a Proposed state category. :::column-end::: :::column span="1"::: Proposed @@ -278,7 +272,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **In Progress:** Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on Kanban boards. + **In Progress:** Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on boards. :::column-end::: :::column span="1"::: Active Resolved (Epic, Feature, Requirement, Task) @@ -289,7 +283,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Resolved:** Assigned to states that represent a solution has been implemented but not yet verified. Generally these states apply to bugs. Work items in a *Resolved* category state appear on the backlog by default. The Agile tools treat the *Resolved* category state exactly the same as the *In Progress* state category. + **Resolved:** Assigned to states that represent a solution was implemented, but not yet verified. Generally these states apply to bugs. Work items in a *Resolved* category state appear on the backlog by default. You can also include *Resolved* states in burndown charts, providing a more accurate tracking of progress. The Agile tools treat the *Resolved* category state exactly the same as the *In Progress* state category. :::column-end::: :::column span="1"::: Resolved (Bug, Issue, Review, Risk) @@ -300,7 +294,7 @@ Here's how the default, inherited states map to the category states for the four :::row-end::: :::row::: :::column span="2"::: - **Completed:** Assigned to states that represent work that has finished. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the Kanban board. You can't modify states in this category nor can you add states to this category. + **Completed:** Assigned to states that represent completed work. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the board. You can't modify states in this category nor can you add states to this category. :::column-end::: :::column span="1"::: Closed @@ -323,49 +317,58 @@ Here's how the default, inherited states map to the category states for the four * * * -[!INCLUDE [temp](../includes/note-closed-items.md)] +### Work item types and their boards -[!INCLUDE [activated-resolved-by-fields](../includes/activated-resolved-by-fields.md)] +Understand where each work item type appears so you can manage your work effectively. +|Work item type category |Work items appear here | +|---------|---------| +|Requirement | Only on the product board. | +|Feature | Only on the Feature portfolio board. | +|Epic | Only on the Epic portfolio board. | +|Custom| Only on a custom portfolio board. | - +> [!TIP] +> We recommend that you map each workflow state to a column. If it’s not mapped, it doesn’t appear on the board. -## When to add a State versus a Kanban column +[!INCLUDE [temp](../includes/note-closed-items.md)] -Use both States and Kanban columns to track the status of work. Workflow states are shared across a project while Kanban columns are shared within a team. Only project collection admins can add custom states, while team admins can add Kanban columns. +[!INCLUDE [activated-resolved-by-fields](../includes/activated-resolved-by-fields.md)] -Add custom states when you want all teams to track the status according to the business workflow adopted by the organization. By customizing the process, you automatically customize the projects and work item types that reference that process. +## When to add a State versus a column -Adding custom states to support workflow states that multiple teams want to track, helps avoid the resulting confusion of different teams creating queries based on a Kanban column. Because each team can customize the Kanban board columns and swimlanes, the values assigned to work items that appear on different boards might not be the same. The primary workaround for this issue is to maintain single ownership of work items by team area path. Another workaround is to formalize the columns by adding custom states that can be shared across teams. +Use both States and columns to track work status. Workflow states are shared across a project, while columns are shared within a team. Only project collection admins can add custom states, while team admins can add columns. +Add custom states to align all teams with the organization's business workflow. Customizing the process automatically customizes the projects and work item types that reference it. - +Custom states help avoid confusion from different teams creating queries based on columns. Since teams can customize board columns and swimlanes, work item values might differ across boards. Maintain single ownership of work items by team area path or formalize columns by adding custom states shared across teams. ## Auto completion of work items with pull requests When you link a work item to a pull request (PR), you can automatically complete those work items when you complete the PR. For more information, see [Auto complete work items with pull requests](auto-complete-work-items-pull-requests.md). +## Automate work item state transitions + +You can automatically update the state of a work item according to the state of its child tasks. For more information, see [Automate work item state transitions](automate-work-item-state-transitions.md). + ## Related articles -::: moniker range=">= azure-devops-2019" **Inheritance process model** -- [Customize a workflow for a process](../../organizations/settings/work/customize-process-workflow.md) -- [Apply rules to workflow states (Inheritance process)](../../organizations/settings/work/apply-rules-to-workflow-states.md) -- [Rules and rule evaluation](../../organizations/settings/work/rule-reference.md) -- [Sample custom rule scenarios](../../organizations/settings/work/rule-samples.md) -::: moniker-end +- [Customize your workflow](../../organizations/settings/work/customize-process-workflow.md) +- [Apply rules to workflow states](../../organizations/settings/work/apply-rules-to-workflow-states.md) +- [Evaluate rules](../../organizations/settings/work/rule-reference.md) +- [Explore custom rule scenarios](../../organizations/settings/work/rule-samples.md) ::: moniker range="< azure-devops" **On-premises XML process model** - [Change the workflow for a work item type](../../reference/xml/change-workflow-wit.md) -- [ProcessConfiguration XML element reference](../../reference/xml/process-configuration-xml-element.md) -- [Customize your work tracking experience](../../reference/on-premises-xml-process-model.md) -- [Rules and rule evaluation](../../organizations/settings/work/rule-reference.md) -- [Sample custom rule scenarios](../../organizations/settings/work/rule-samples.md) +- [Reference the ProcessConfiguration XML element](../../reference/xml/process-configuration-xml-element.md) +- [Customize your work tracking experience](../../reference/on-premises-xml-process-model.md) +- [Evaluate rules](../../organizations/settings/work/rule-reference.md) +- [Explore custom rule scenarios](../../organizations/settings/work/rule-samples.md) ::: moniker-end -::: moniker range=">= azure-devops-2019" **Dashboard widgets** -- [Lead Time and Cycle Time control charts (widgets)](../../report/dashboards/cycle-time-and-lead-time.md) +- [Explore Lead Time and Cycle Time control charts (widgets)](../../report/dashboards/cycle-time-and-lead-time.md) ::: moniker-end diff --git a/docs/breadcrumb/toc.yml b/docs/breadcrumb/toc.yml index e8f6aa3f49b..3a8e13580cc 100644 --- a/docs/breadcrumb/toc.yml +++ b/docs/breadcrumb/toc.yml @@ -21,72 +21,3 @@ - name: Azure Test Plans tocHref: /azure/devops/test/ topicHref: /azure/devops/test/index - - name: Azure DevOps - Get Started - tocHref: /azure/devops/get-started/ - topicHref: /azure/devops/get-started/index - - name: Get Started - tocHref: /azure/devops/user-guide/ - topicHref: /azure/devops/get-started/index - - name: Get Started - tocHref: /azure/devops/migrate/ - topicHref: /azure/devops/get-started/index - - name: Cross-Service Overview - tocHref: /azure/devops/cross-service/ - topicHref: /azure/devops/cross-service/index - - name: Wiki, Search, Navigation - tocHref: /azure/devops/project/ - topicHref: /azure/devops/project/index - - name: Developer Resources - tocHref: /azure/devops/dev-resources/ - topicHref: /azure/devops/dev-resources/index - - name: Developer Resources - tocHref: /azure/devops/cli/ - topicHref: /azure/devops/dev-resources/index - - name: Developer Resources - tocHref: /azure/devops/demo-gen/ - topicHref: /azure/devops/dev-resources/index - - name: Settings - tocHref: /azure/devops/organizations/ - topicHref: /azure/devops/organizations/index - - name: Settings - tocHref: /azure/devops/organizations/settings/ - topicHref: /azure/devops/organizations/index - - name: Settings - tocHref: /azure/devops/organizations/accounts/ - topicHref: /azure/devops/organizations/index - - name: Settings - tocHref: /azure/devops/organizations/audit/ - topicHref: /azure/devops/organizations/index - - name: Settings - tocHref: /azure/devops/organizations/notifications/ - topicHref: /azure/devops/organizations/index - - name: Settings - tocHref: /azure/devops/organizations/projects/ - topicHref: /azure/devops/organizations/index - - name: Security - tocHref: /azure/devops/organizations/security/ - topicHref: /azure/devops/organizations/security/index - - name: Security - tocHref: /azure/devops/organizations/billing/ - topicHref: /azure/devops/organizations/security/index - - name: Marketplace & Extensibility - tocHref: /azure/devops/marketplace-extensibility/ - topicHref: /azure/devops/marketplace-extensibility/index?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Marketplace & Extensibility - tocHref: /azure/devops/marketplace/ - topicHref: /azure/devops/marketplace-extensibility/index?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Marketplace & Extensibility - tocHref: /azure/devops/extend/ - topicHref: /azure/devops/marketplace-extensibility/index?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Marketplace & Extensibility - tocHref: /azure/devops/integrate/ - topicHref: /azure/devops/marketplace-extensibility/index?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Marketplace & Extensibility - tocHref: /azure/devops/service-hooks/ - topicHref: /azure/devops/marketplace-extensibility/index?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Azure Boards Customization - tocHref: /azure/devops/reference/ - topicHref: /azure/devops/reference/index - - name: Azure Boards Customization - tocHref: /azure/devops/organizations/settings/work/ - topicHref: /azure/devops/reference/index?toc=/azure/devops/reference/toc.json \ No newline at end of file diff --git a/docs/cli/auto-detect-and-git-aliases.md b/docs/cli/auto-detect-and-git-aliases.md index a4a1ba1859f..2b350eef921 100644 --- a/docs/cli/auto-detect-and-git-aliases.md +++ b/docs/cli/auto-detect-and-git-aliases.md @@ -4,6 +4,7 @@ titleSuffix: Azure DevOps description: Auto detect configuration and git aliases when using Azure DevOps extension command-line interface ms.topic: how-to ms.subservice: azure-devops-reference +ms.custom: devx-track-azurecli ms.manager: mijacobs ms.author: chcomley author: chcomley diff --git a/docs/cli/azure-devops-cli-in-yaml.md b/docs/cli/azure-devops-cli-in-yaml.md index 23da7927a98..87938e29c94 100644 --- a/docs/cli/azure-devops-cli-in-yaml.md +++ b/docs/cli/azure-devops-cli-in-yaml.md @@ -4,35 +4,49 @@ titleSuffix: Azure DevOps description: Use Azure DevOps CLI to create Azure Pipeline YAML ms.topic: how-to ms.subservice: azure-devops-reference -ms.custom: devx-track-azurecli +ms.custom: devx-track-azurecli, linux-related-content ms.manager: mijacobs ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 09/22/2021 +ms.date: 11/20/2023 --- # Azure DevOps CLI in Azure Pipeline YAML [!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] -If you wish to use Azure DevOps CLI with a YAML pipeline, you can use the following example to understand how YAML can be used to install Azure CLI, add the Azure DevOps extension, and run Azure DevOps CLI commands. +If you wish to use Azure DevOps CLI with a YAML pipeline, you can use the following examples to install Azure CLI, add the Azure DevOps extension, and run Azure DevOps CLI commands. > [!NOTE] > The steps in this article show how to authenticate with Azure DevOps and run `az devops` commands using the Azure DevOps CLI extension. If you want to use Azure CLI to interact with Azure resources, use the [AzureCLI task](/azure/devops/pipelines/tasks/reference/azure-cli-v2). ## Authenticate with Azure DevOps -Some Azure DevOps CLI commands that don't call into Azure DevOps, like `az devops configure` and `az devops -h`, do not require any authentication, but most commands interact with Azure DevOps and do require authentication. You can authenticate using the [System.AccessToken](../pipelines/build/variables.md#systemaccesstoken) security token used by the running pipeline, by assigning it to an environment variable named `AZURE_DEVOPS_EXT_PAT`, as shown in the following example. +Some Azure DevOps CLI commands that don't call into Azure DevOps, like `az devops configure` and `az devops -h`, don't require any authentication, but most commands interact with Azure DevOps and do require authentication. You can authenticate using the [System.AccessToken](../pipelines/build/variables.md#systemaccesstoken) security token used by the running pipeline, by assigning it to an environment variable named `AZURE_DEVOPS_EXT_PAT`, as shown in the following example. + +# [Bash](#tab/bash) ```yml - bash: | - az pipelines build list + az pipelines build list --organization '$(System.TeamFoundationCollectionUri)' --project '$(System.TeamProject)' displayName: 'Show build list' env: AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) ``` +# [PowerShell](#tab/powershell) + +```yml +- pwsh: | + az pipelines build list --organization '$(System.TeamFoundationCollectionUri)' --project '$(System.TeamProject)' + displayName: 'Show build list ' + env: + AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) +``` + +--- + If you have multiple steps that require authentication, add the `AZURE_DEVOPS_EXT_PAT` environment variable to each step. For more information on the scope of the security token used by the running pipeline, see [Access repositories, artifacts, and other resources](../pipelines/process/access-tokens.md). @@ -47,18 +61,20 @@ The following example shows how to log in to Azure DevOps and run a few commands This example authenticates with Azure DevOps CLI using the [System.AccessToken](../pipelines/build/variables.md#systemaccesstoken) security token used by the running pipeline. +# [Bash](#tab/bash) + ```yml trigger: - main pool: - vmImage: `ubuntu-latest` + vmImage: 'ubuntu-latest' steps: - bash: az --version displayName: 'Show Azure CLI version' -- bash: az devops configure --defaults organization=$(System.TeamFoundationCollectionUri) project=$(System.TeamProject) --use-git-aliases true +- bash: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true displayName: 'Set default Azure DevOps organization and project' - bash: | @@ -69,6 +85,31 @@ steps: AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) ``` +# [PowerShell](#tab/powershell) + +```yml +trigger: +- main + +pool: + vmImage: 'windows-latest' + +steps: +- bash: az --version + displayName: 'Show Azure CLI version' + +- pwsh: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true + displayName: 'Set default Azure DevOps organization and project' + +- pwsh: | + az pipelines build list + git pr list + displayName: 'Show build list and PRs' + env: + AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) +``` + +--- ## Azure DevOps CLI with macOS hosted agents @@ -82,12 +123,28 @@ The macOS Microsoft-hosted agents have Azure CLI installed but not the Azure Dev ## Hosted agent Azure CLI version -Microsoft-hosted agents [typically deploy weekly updates](https://github.com/actions/runner-images#image-releases) to the software on the virtual environments. For some tools, the latest version at the time of the deployment is used; for others, the tool is pinned to specific version(s). +Microsoft-hosted agents [typically deploy weekly updates](https://github.com/actions/runner-images#image-releases) to the software on the virtual environments. For some tools, the latest version at the time of the deployment is used; for others, the tool is pinned to specific versions. * To check the included software and their versions for Microsoft-hosted agents, including the installed version of Azure CLI and Azure DevOps CLI extension, follow the **Included Software** links in the [Software](../pipelines/agents/hosted.md#software) table. * To check the current version for Azure CLI, see [How to install the Azure CLI](/cli/azure/install-azure-cli). -If a newer version of Azure CLI is released and the hosted images do not yet have the latest version, you can upgrade the Azure CLI version to the latest version by running the following commands in your pipeline. +You can upgrade the Azure CLI on your hosted images by running the following commands in your pipeline. + +# [Bash](#tab/bash) + +```yml +# Specify python version +- task: UsePythonVersion@0 + inputs: + versionSpec: '3.x' + architecture: 'x64' + +# Update to latest Azure CLI version +- bash: pip install --pre azure-cli + displayName: 'Upgrade Azure CLI' +``` + +# [PowerShell](#tab/powershell) ```yml # Specify python version @@ -97,14 +154,18 @@ If a newer version of Azure CLI is released and the hosted images do not yet hav architecture: 'x64' # Update to latest Azure CLI version -- bash: pip install --pre azure-cli --extra-index-url https://azurecliprod.blob.core.windows.net/edge +- pwsh: pip install --pre azure-cli displayName: 'Upgrade Azure CLI' ``` +--- + ## Conditionally install the Azure DevOps CLI extension -If you have a pipeline that runs on several Microsoft-hosted VM images, some of which do not have the Azure DevOps CLI extension installed, you can perform that step conditionally, as shown in the following example. +If your pipeline runs on several Microsoft-hosted VM images, some of which don't have the Azure DevOps CLI extension installed, you perform the installation conditionally. + +# [Bash](#tab/bash) ```yml trigger: @@ -113,13 +174,15 @@ trigger: # Run on multiple Microsoft-hosted agent images strategy: matrix: - linux18: - imageName: "ubuntu-18.04" + linux22: + imageName: "ubuntu-22.04" linux20: imageName: "ubuntu-20.04" - mac1015: - imageName: "macos-10.15" - macOS11: + mac13: + imageName: "macos-13" + mac12: + imageName: "macos-12" + mac11: imageName: "macos-11" windows2019: imageName: "windows-2019" @@ -141,7 +204,7 @@ steps: # Azure DevOps CLI extension call that does not require login or credentials # since it configures the local environment -- bash: az devops configure --defaults organization=$(System.TeamFoundationCollectionUri) project=$(System.TeamProject) --use-git-aliases true +- bash: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true displayName: 'Set default Azure DevOps organization and project' # Call that does require credentials, use the System.AccessToken PAT @@ -154,16 +217,70 @@ steps: displayName: 'Show build list and PRs' ``` +# [PowerShell](#tab/powershell) + +```yml +trigger: +- main + +# Run on multiple Microsoft-hosted agent images +strategy: + matrix: + linux22: + imageName: "ubuntu-22.04" + linux20: + imageName: "ubuntu-20.04" + mac13: + imageName: "macos-13" + mac12: + imageName: "macos-12" + mac11: + imageName: "macos-11" + windows2019: + imageName: "windows-2019" + windows2022: + imageName: "windows-2022" + maxParallel: 3 + +pool: + vmImage: $(imageName) + +steps: +- pwsh: az --version + displayName: 'Show Azure CLI version' + +# Install Azure DevOps CLI extension only on macOS images +- pwsh: az extension add -n azure-devops + condition: contains(variables.imageName, 'windows') + displayName: 'Install Azure DevOps extension' + +# Azure DevOps CLI extension call that does not require login or credentials +# since it configures the local environment +- pwsh: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true + displayName: 'Set default Azure DevOps organization and project' + +# Call that does require credentials, use the System.AccessToken PAT +# and assign to AZURE_DEVOPS_EXT_PAT which is known to Azure DevOps CLI extension +- pwsh: | + az pipelines build list + git pr list + env: + AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) + displayName: 'Show build list and PRs' +``` + +--- + ## Azure DevOps CLI with self-hosted agents -If your self-hosted agent isn't configured with the required software to use Azure DevOps CLI, or if you want to ensure you have the latest versions, you can install the required software using the following steps. +You can use the following methods to install or upgrade the Azure DevOps CLI in your self-hosted agent. * [Manually install Azure CLI and Azure DevOps CLI extension](#manually-install-azure-cli-and-azure-devops-cli-extension) * [Install Azure CLI and Azure DevOps CLI extension in your pipeline](#install-azure-cli-and-azure-devops-cli-extension-in-your-pipeline) ### Manually install Azure CLI and Azure DevOps CLI extension -Installing Azure CLI and Azure DevOps CLI extension on your self-hosted agent when you provision the virtual machine image for the agent is much faster than installing them each time the pipeline is run. +Installing Azure CLI and Azure DevOps CLI extension on your self-hosted agent when you provision the virtual machine image for the agent is faster than installing them each time the pipeline is run. * To install Azure CLI on your self-hosted agent image, see [Install the Azure CLI](/cli/azure/install-azure-cli). There are separate instructions for [Windows](/cli/azure/install-azure-cli-windows), [Linux](/cli/azure/install-azure-cli-linux), and [macOS](/cli/azure/install-azure-cli-macos). * After installing Azure CLI, install [Azure DevOps CLI extension](index.md). @@ -173,7 +290,10 @@ Installing Azure CLI and Azure DevOps CLI extension on your self-hosted agent wh The following example of configuring Azure CLI and Azure DevOps CLI extension on a self-hosted agent using a pipeline has the following prerequisites. * Install Azure CLI using Python - * Python must be installed on the agent according to the instructions in [Python version task - How can I configure a self-hosted agent to use this task?](/azure/devops/pipelines/tasks/reference/use-python-version-v0#how-can-i-configure-a-self-hosted-agent-to-use-this-task) The `UsePythonVersion@0` task does not install Python onto your self-hosted agent. If you only have one version of Python installed on your self-hosted agent and it is in the path, you don't need to use the `UsePythonVersion@0` task. + * Python must be installed on the agent according to the instructions in [Python version task - How can I configure a self-hosted agent to use this task?](/azure/devops/pipelines/tasks/reference/use-python-version-v0#how-can-i-configure-a-self-hosted-agent-to-use-this-task) The `UsePythonVersion@0` task doesn't install Python onto your self-hosted agent. If you only have one version of Python installed on your self-hosted agent and it is in the path, you don't need to use the `UsePythonVersion@0` task. + +# [Bash](#tab/bash) + ```yml # Specify python version if you have side-by-side versions - task: UsePythonVersion@0 @@ -186,13 +306,36 @@ The following example of configuring Azure CLI and Azure DevOps CLI extension on displayName: 'Upgrade pip' # Update to latest Azure CLI version, min version required for Azure DevOps is 2.10.1 - - bash: pip install --pre azure-cli --extra-index-url https://azurecliprod.blob.core.windows.net/edge + - bash: pip install --pre azure-cli + displayName: 'Upgrade Azure CLI' + ``` + +# [PowerShell](#tab/powershell) + + ```yml + # Specify python version if you have side-by-side versions + - task: UsePythonVersion@0 + inputs: + versionSpec: '3.x' + architecture: 'x64' + + # Update pip to latest + - pwsh: python -m pip install --upgrade pip + displayName: 'Upgrade pip' + + # Update to latest Azure CLI version, min version required for Azure DevOps is 2.10.1 + - pwsh: pip install --pre azure-cli displayName: 'Upgrade Azure CLI' ``` +--- + * Install Azure CLI DevOps extension * Azure CLI version [2.10.1](index.md) or higher is installed. - * There is a version of `bash` installed on the agent and in the path. A bash installation is required to use the [bash task](/azure/devops/pipelines/tasks/reference/bash-v3). + * There's a version of `bash` installed on the agent and in the path. A bash installation is required to use the [bash task](/azure/devops/pipelines/tasks/reference/bash-v3). + +# [Bash](#tab/bash) + ```yml # Install Azure DevOps extension - bash: az extension add -n azure-devops @@ -202,8 +345,23 @@ The following example of configuring Azure CLI and Azure DevOps CLI extension on # ... ``` +# [PowerShell](#tab/powershell) + + ```yml + # Install Azure DevOps extension + - pwsh: az extension add -n azure-devops + displayName: 'Install Azure DevOps extension' + + # Now you can make calls into Azure DevOps CLI + # ... + ``` + +--- + The following example installs Azure CLI followed by the Azure DevOps CLI extension. +# [Bash](#tab/bash) + ```yml steps: # Specify python version if you have side-by-side versions @@ -217,7 +375,7 @@ steps: displayName: 'Upgrade pip' # Update to latest Azure CLI version, min version required for Azure DevOps is 2.10.1 -- bash: pip install --pre azure-cli --extra-index-url https://azurecliprod.blob.core.windows.net/edge +- bash: pip install --pre azure-cli displayName: 'Upgrade Azure CLI' # Install Azure DevOps extension @@ -228,9 +386,39 @@ steps: # ... ``` +# [PowerShell](#tab/powershell) + +```yml +steps: +# Specify python version if you have side-by-side versions +- task: UsePythonVersion@0 + inputs: + versionSpec: '3.x' + architecture: 'x64' + +# Update pip to latest +- pwsh: python -m pip install --upgrade pip + displayName: 'Upgrade pip' + +# Update to latest Azure CLI version, min version required for Azure DevOps is 2.10.1 +- pwsh: pip install --pre azure-cli + displayName: 'Upgrade Azure CLI' + +# Install Azure DevOps extension +- pwsh: az extension add -n azure-devops + displayName: 'Install Azure DevOps extension' + +# Now you can make calls into Azure DevOps CLI +# ... +``` + +--- + ## Assign the results of an Azure DevOps CLI call to a variable -To store the results of an Azure DevOps CLI call to a pipeline variable, use the `task.setvariable` syntax described in [Set variables in scripts](../pipelines/process/variables.md#set-variables-in-scripts). The following example retrieves the ID of a variable group named **Fabrikam-2021** and then uses this value in a subsequent step. +To store the results of an Azure DevOps CLI call to a pipeline variable, use the `task.setvariable` syntax described in [Set variables in scripts](../pipelines/process/variables.md#set-variables-in-scripts). The following example retrieves the ID of a variable group named **Fabrikam-2023** and then uses this value in a subsequent step. + +# [Bash](#tab/bash) ```yml variables: @@ -242,20 +430,48 @@ pool: vmImage: "ubuntu-latest" steps: -- bash: az devops configure --defaults organization=$(System.TeamFoundationCollectionUri) project=$(System.TeamProject) --use-git-aliases true +- bash: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true displayName: 'Set default Azure DevOps organization and project' -- bash: echo "##vso[task.setvariable variable=variableGroupId]$(az pipelines variable-group list --group-name Fabrikam-2021 --query [].id -o tsv)" +- bash: echo "##vso[task.setvariable variable=variableGroupId]$(az pipelines variable-group list --group-name Fabrikam-2023 --query [].id -o tsv)" env: AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) - displayName: 'Get Fabrikam-2021 variable group id' + displayName: 'Get Fabrikam-2023 variable group id' -- bash: az pipelines variable-group variable list --group-id $(variableGroupId) +- bash: az pipelines variable-group variable list --group-id '$(variableGroupId)' env: AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) - displayName: 'List variables in Fabrikam-2021 variable group' + displayName: 'List variables in Fabrikam-2023 variable group' ``` +# [PowerShell](#tab/powershell) + +```yml +variables: +- name: variableGroupId + +trigger: none + +pool: + vmImage: "windows-latest" + +steps: +- pwsh: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true + displayName: 'Set default Azure DevOps organization and project' + +- pwsh: echo "##vso[task.setvariable variable=variableGroupId]$(az pipelines variable-group list --group-name Fabrikam-2023 --query [].id -o tsv)" + env: + AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) + displayName: 'Get Fabrikam-2023 variable group id' + +- pwsh: az pipelines variable-group variable list --group-id '$(variableGroupId)' + env: + AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) + displayName: 'List variables in Fabrikam-2023 variable group' +``` + +--- + For more examples of working with variables, including working with variables across jobs and stages, see [Define variables](../pipelines/process/variables.md). For examples of the query syntax used in the previous example, see [How to query Azure CLI command output using a JMESPath query](/cli/azure/query-azure-cli). ## Related articles diff --git a/docs/cli/index.md b/docs/cli/index.md index ddc1e894c1e..903404c18fa 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -34,6 +34,9 @@ To start using the Azure DevOps extension for Azure CLI, perform the following s 3. Sign in: Run `az login` to sign in. Note that we support only interactive or log in using user name and password with `az login`. To sign in using a Personal Access Token (PAT), see [Sign in via Azure DevOps Personal Access Token (PAT)](log-in-via-pat.md). +> [!NOTE] +> The Azure DevOps extension does not currently support authenticating with [Managed Identities](../integrate/get-started/authentication/service-principal-managed-identity.md). + 4. Configure defaults: We recommend you set the default configuration for your organization and project. Otherwise, you can set these within the individual commands themselves. ``` diff --git a/docs/cli/log-in-via-pat.md b/docs/cli/log-in-via-pat.md index e8dfafe69ed..cdc7377f43f 100644 --- a/docs/cli/log-in-via-pat.md +++ b/docs/cli/log-in-via-pat.md @@ -8,7 +8,7 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 08/17/2020 +ms.date: 01/08/2025 --- # Sign in with a personal access token (PAT) @@ -17,17 +17,19 @@ ms.date: 08/17/2020 You can sign in using an Azure DevOps personal access token (PAT). To create a PAT, see [Use personal access tokens](../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat). +[!INCLUDE [use-microsoft-entra-reduce-pats](../includes/use-microsoft-entra-reduce-pats.md)] + To use a PAT with the Azure DevOps CLI, use one of these options: -* Use `az devops login` and be [prompted for the PAT token](#userprompt). -* Pipe the [PAT token on StdIn](#PipePATonStdIn) to `az devops login`. +* Use `az devops login` and be [prompted for the PAT token](#user-prompted-to-use-az-devops-login). +* Pipe the [PAT token on StdIn](#pipe-pat-on-stdin-to-az-devops-login) to `az devops login`. > [!NOTE] > This option works only in a non-interactive shell. -* Set the `AZURE_DEVOPS_EXT_PAT` [environment variable](#EnvironmentVariable), and don't use `az devops login`. +* Set the `AZURE_DEVOPS_EXT_PAT` [environment variable]((#use-the-azuredevopsextpat-environment-variable), and don't use `az devops login`. -## User prompted to use az devops login +## User prompted to use az devops login You're prompted to enter a PAT after you run the `az devops login` command: @@ -37,15 +39,19 @@ Token: ``` > [!NOTE] -> If you have already signed in with `az login` interactively or if you're using a user name and password, you're not required to provide a token because the `az devops` commands now support sign-in through `az login`. However, you can't sign in as the service principal via `az login`. In that scenario, a PAT is required. +> If you have already signed in with `az login` interactively or if you're using a user name and password, you're not required to provide a token because the `az devops` commands now support sign-in through `az login`. When you're successfully signed in, this command also can set your default organization to Contoso, provided no default organization is configured. -## Pipe PAT on StdIn to az devops login +> [!NOTE] +> For Guest Users, only the `az devops login` is supported. + + +## Pipe PAT on StdIn to az devops login ### From a variable -This option is useful in pipelines in which `#####` can be replaced by `$(System.AccessToken)` or another pipeline variable: +This option is useful in pipelines in which you can replace `#####` with `$(System.AccessToken)` or another pipeline variable: ```azurecli echo "######" | az devops login --organization https://dev.azure.com/contoso/ @@ -57,11 +63,11 @@ echo "######" | az devops login --organization https://dev.azure.com/contoso/ cat my_pat_token.txt | az devops login --organization https://dev.azure.com/contoso/ ``` -## Use the AZURE_DEVOPS_EXT_PAT environment variable +## Use the AZURE_DEVOPS_EXT_PAT environment variable To gain access in a non-interactive manner for automation scenarios, you can use environment variables or fetch a PAT from a file. -If `az login` or `az devops login` haven't been used, all `az devops` commands will try to sign in using a PAT stored in the `AZURE_DEVOPS_EXT_PAT` environment variable. +If `az login` or `az devops login` haven't been used, all `az devops` commands try to sign in using a PAT stored in the `AZURE_DEVOPS_EXT_PAT` environment variable. To use a PAT, set the `AZURE_DEVOPS_EXT_PAT` environment variable at the process level. diff --git a/docs/cli/media/DockerServiceEndpointCreateUI.PNG b/docs/cli/media/DockerServiceEndpointCreateUI.PNG index 10a7451f9c6..3d541d80064 100644 Binary files a/docs/cli/media/DockerServiceEndpointCreateUI.PNG and b/docs/cli/media/DockerServiceEndpointCreateUI.PNG differ diff --git a/docs/cli/policy-configuration-file.md b/docs/cli/policy-configuration-file.md index ca5ba482aac..975ad07ff21 100644 --- a/docs/cli/policy-configuration-file.md +++ b/docs/cli/policy-configuration-file.md @@ -28,33 +28,33 @@ Create a policy configuration file for build policy, including the multiple appl > [!div class="tabbedCodeSnippets"] > ```json > { -> "isBlocking": true, -> "isDeleted": false, -> "isEnabled": true, -> "revision": 1, -> "settings": { -> "buildDefinitionId": 22, -> "displayName": "Manual Queue Policy", -> "manualQueueOnly": true, -> "queueOnSourceUpdateOnly": false, -> "scope": [ -> { -> "matchKind": "Prefix", -> "refName": "refs/heads/release", -> "repositoryId": "e646f204-53c9-4153-9ab9-fd41a11e3564" +> "isBlocking": true, +> "isDeleted": false, +> "isEnabled": true, +> "revision": 1, +> "settings": { +> "buildDefinitionId": 22, +> "displayName": "Manual Queue Policy", +> "manualQueueOnly": true, +> "queueOnSourceUpdateOnly": false, +> "scope": [ +> { +> "matchKind": "Prefix", +> "refName": "refs/heads/release", +> "repositoryId": "e646f204-53c9-4153-9ab9-fd41a11e3564" +> }, +> { +> "matchKind": "Exact", +> "refName": "refs/heads/main", +> "repositoryId": "e646f204-53c9-4153-9ab9-fd41a11e1234" +> } +> ], +> "validDuration": 0 > }, -> { -> "matchKind": "Exact", -> "refName": "refs/heads/main", -> "repositoryId": "e646f204-53c9-4153-9ab9-fd41a11e1234" +> "type": { +> "displayName": "Build", +> "id": "0609b952-1397-4640-95ec-e00a01b2f659" > } -> ], -> "validDuration": 0 -> }, -> "type": { -> "displayName": "Build", -> "id": "0609b952-1397-4640-95ec-e00a01b2f659" -> } > } > ``` @@ -62,7 +62,7 @@ To learn more about the structure for various policy types, refer to [Policy cre ## Save the file and run the create policy command -`az repos policy create C:\policyConfiguration.txt` +`az repos policy create --policy-configuration C:\policyConfiguration.txt` Note that the path is provided using '\\' backslash. diff --git a/docs/cli/quick-reference.md b/docs/cli/quick-reference.md index 4b690395eda..be3060fd08f 100644 --- a/docs/cli/quick-reference.md +++ b/docs/cli/quick-reference.md @@ -26,10 +26,10 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m ## Azure Artifacts -- [Universal Packages - download specific files](../artifacts/quickstarts/universal-packages.md#download-specific-files) +- [Universal Packages - download specific files](../artifacts/quickstarts/download-universal-packages.md#download-specific-files) - [Create a feed](../artifacts/quickstarts/universal-packages.md) -- [Download a universal package](../artifacts/quickstarts/universal-packages.md#download-universal-packages) -- [Publish a universal package](../artifacts/quickstarts/universal-packages.md#publish-universal-packages) +- [Download a universal package](../artifacts/quickstarts/universal-packages.md) +- [Publish a universal package](../artifacts/quickstarts/universal-packages.md) ## Azure Boards @@ -37,17 +37,17 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m :::row::: :::column span="1"::: #### Area and Iteration Paths - - [Add a project area path](../organizations/settings/set-area-paths.md#add-area) - - [Add a project iteration](../organizations/settings/set-iteration-paths-sprints.md#add-project-iteration) - - [Delete or update a project iteration path](../organizations/settings/set-iteration-paths-sprints.md#delete-update-iteration-paths) - - [List project area paths](../organizations/settings/set-area-paths.md#list-areas) - - [List project iteration paths](../organizations/settings/set-iteration-paths-sprints.md#iteration-project-list) + - [Add a project area path](../organizations/settings/set-area-paths.md#add-an-area-path) + - [Add a project iteration](../organizations/settings/set-iteration-paths-sprints.md#add-iterations-and-set-iteration-dates) + - [Delete or update a project iteration path](../organizations/settings/set-iteration-paths-sprints.md#rename-or-move-an-iteration) + - [List project area paths](../organizations/settings/set-area-paths.md#list-project-areas) + - [List project iteration paths](../organizations/settings/set-iteration-paths-sprints.md#list-project-iterations) - [List team areas paths](../organizations/settings/set-area-paths.md#list-team-area-paths) - - [List team iteration paths](../organizations/settings/set-iteration-paths-sprints.md#list-team-iteration-paths) - - [Remove area path from a team](../organizations/settings/set-area-paths.md#remove-area-path-from-team) - - [Rename or move a project area path](../organizations/settings/set-area-paths.md#rename-move-project-area-path) + - [List team iteration paths](../organizations/settings/set-iteration-paths-sprints.md#list-team-iterations) + - [Remove area path from a team](../organizations/settings/set-area-paths.md#remove-an-area-path-from-a-team) + - [Rename or move a project area path](../organizations/settings/set-area-paths.md#rename-or-move-an-area-path) - [Set team area paths](../organizations/settings/set-area-paths.md#set-team-area-paths) - - [Set team iteration paths](../organizations/settings/set-iteration-paths-sprints.md#set-team-iteration-paths) + - [Set team iteration paths](../organizations/settings/set-iteration-paths-sprints.md#select-team-sprints-and-set-the-default-iteration-path) :::column-end::: :::column span="1"::: #### Queries @@ -100,7 +100,7 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m #### Teams - [Add a team](../organizations/settings/add-teams.md#add-team) - [Delete a team](../organizations/settings/rename-remove-team.md#delete-team) - - [List team members](../organizations/security/add-users-team-project.md#list-members) + - [List team members](../organizations/security/add-users-team-project.md#list-team-members) - [List teams](../organizations/settings/add-teams.md#list-teams) - [Show team details](../organizations/security/add-users-team-project.md#show-details) - [Update a team](../organizations/settings/rename-remove-team.md#update-team) @@ -156,15 +156,15 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m - [Update a variable](../pipelines/process/variables.md#update-variable) #### Variable groups - - [Add variables to a variable group](../pipelines/library/variable-groups.md#create-a-variable-group) - - [Create a variable group](../pipelines/library/variable-groups.md#create-variable-group) - - [Delete a variable group](../pipelines/library/variable-groups.md#delete-variable-group) - - [Delete variables from a variable group](../pipelines/library/variable-groups.md#delete-variables-group) + - [Add variables to a variable group](../pipelines/library/variable-groups.md#add-variables-to-a-variable-group) + - [Create a variable group](../pipelines/library/variable-groups.md#create-a-variable-group) + - [Delete a variable group](../pipelines/library/variable-groups.md#delete-a-variable-group) + - [Delete variables from a variable group](../pipelines/library/variable-groups.md#delete-variables-from-a-variable-group) - [List variable groups](../pipelines/library/variable-groups.md#list-variable-groups) - - [List variables in a variable group](../pipelines/library/variable-groups.md#list-variables-group) - - [Show details for a variable group](../pipelines/library/variable-groups.md#show-variable-group) - - [Update a variable group](../pipelines/library/variable-groups.md#update-variable-group) - - [Update variables in a variable group](../pipelines/library/variable-groups.md#update-variables-group) + - [List variables in a variable group](../pipelines/library/variable-groups.md#list-variables-in-a-variable-group) + - [Show details for a variable group](../pipelines/library/variable-groups.md#show-details-for-a-variable-group) + - [Update a variable group](../pipelines/library/variable-groups.md#update-a-variable-group) + - [Update variables in a variable group](../pipelines/library/variable-groups.md#update-variables-in-a-variable-group) :::column-end::: :::row-end::: @@ -210,7 +210,7 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m - [Define a custom pull request view](../repos/git/view-pull-requests.md#define-custom-pr-view) - [Show pull request details](../repos/git/view-pull-requests.md#open-pr) - [Set vote on a pull request](../repos/git/review-pull-requests.md#set-vote) - - [Reset vote on a pull request](../repos/git/review-pull-requests.md#reset-vote) + - [Reset vote on a pull request](../repos/git/review-pull-requests.md) - [Complete or update a pull request](../repos/git/complete-pull-requests.md#complete-the-pull-request) - [Set pull request completion options](../repos/git/complete-pull-requests.md#set-completion-options) - [Set pull request to autocomplete](../repos/git/complete-pull-requests.md#complete-automatically) @@ -246,8 +246,6 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m - [Show permissions for specified token, namespace and user or group](../organizations/security/manage-tokens-namespaces.md) - [Update a security group](../organizations/security/add-manage-security-groups.md) - - ## Service endpoints or service connections - [Create a GitHub service endpoint](service-endpoint.md) diff --git a/docs/cli/service-endpoint.md b/docs/cli/service-endpoint.md index 3b617c12eba..226286e0367 100644 --- a/docs/cli/service-endpoint.md +++ b/docs/cli/service-endpoint.md @@ -4,7 +4,7 @@ titleSuffix: Azure DevOps description: Learn how to use Azure DevOps CLI to create a service endpoint ms.topic: how-to ms.subservice: azure-devops-reference -ms.custom: devx-track-arm-template +ms.custom: devx-track-arm-template, devx-track-azurecli, arm2024 ms.manager: mijacobs ms.author: chcomley author: chcomley @@ -27,10 +27,11 @@ With the `az devops service-endpoint` command, you can create and manage differe For detail command syntax, see [`az devops service-endpoint`](/cli/azure/devops/service-endpoint). For syntax on the REST API for service endpoints, see [Endpoints](/rest/api/azure/devops/serviceendpoint/endpoints). -You can also use azure cli commands to get details, list, delete, and update a service endpoint. See [Index to Azure DevOps CLI examples, Service endpoints or service connections](quick-reference.md#service-endpoints). +You can also use azure cli commands to get details, list, delete, and update a service endpoint. See [Index to Azure DevOps CLI examples, Service endpoints or service connections](quick-reference.md#service-endpoints-or-service-connections). To use the web portal to create and edit service connections, see [Manage service connections](../pipelines/library/service-endpoints.md). +[!INCLUDE [use-service-principals-tip](../includes/use-service-principals-tip.md)] ## Create service endpoint using a configuration file @@ -45,14 +46,13 @@ The following syntax shows the `json` format for the configuration file. { "data": {}, "name": "MyNewServiceEndpoint", - "type": "Generic", - "url": "https://myserver", + "type": "AzureRM", + "url": "https://management.azure.com/", "authorization": { "parameters": { - "username": "myusername", - "password": "mysecretpassword" + "tenantid": "your-tenant-id" }, - "scheme": "UsernamePassword" + "scheme": "ManagedServiceIdentity" }, "isShared": false, "isReady": true, @@ -123,10 +123,11 @@ Upon successful creation, an `Id` is assigned to the service endpoint and a resp "administratorsGroup": null, "authorization": { "parameters": { - "password": null, - "username": "myusername" + "serviceprincipalid": "your-service-principal-id", + "serviceprincipalkey": "your-service-principal-key", + "tenantid": "your-tenant-id" }, - "scheme": "UsernamePassword" + "scheme": "ServicePrincipal" }, "createdBy": { "descriptor": "aad.OGYxZTFlODEtMGJiNC03N2ZkLThkYzUtYjE3MTNiNTQ2MjQ4", @@ -198,9 +199,9 @@ az devops service-endpoint azurerm create --azure-rm-service-principal-id [--project] ``` -### Use a client secret/password +### Use a client secret -In interactive mode, the the `az devops service-endpoint azurerm create` command asks for a service principal password/secret using a prompt message. For automation purposes, set the service principal password/secret using the `AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY` environment variable. +In interactive mode, the `az devops service-endpoint azurerm create` command asks for a service principal secret using a prompt message. For automation purposes, set the service principal secret using the `AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY` environment variable. ```bash export AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY= @@ -212,81 +213,17 @@ $env:AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY= ### Use a client certificate -If Azure Active Directory application uses [certificate for authentication](/azure/active-directory/develop/active-directory-certificate-credentials), then create a .pem file for the certificate and pass the path to the .pem file using the `--azure-rm-service-principal-certificate-path` argument. +If the Microsoft Entra application uses [certificate for authentication](/azure/active-directory/develop/active-directory-certificate-credentials), then create a .pem file for the certificate and pass the path to the .pem file using the `--azure-rm-service-principal-certificate-path` argument. -You can create a.pem file using openssl: +You can create a .pem file using openssl: ```bash -openssl pkcs12 -in file.pfx -out file.pem -nodes -password pass: +openssl pkcs12 -in file.pfx -out file.pem -nodes -secret pass: ``` - ## Related articles - [Manage service connections](../pipelines/library/service-endpoints.md) -- [Create an Azure Resource Manager service connection using automated security](../pipelines/library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-using-automated-security) +- [Create an Azure Resource Manager service connection using automated security](../pipelines/library/connect-to-azure.md) - [`az devops service-endpoint`](/cli/azure/devops/service-endpoint) -- [Endpoints REST API](/rest/api/azure/devops/serviceendpoint/endpoints) - - - +- [Endpoints REST API](/rest/api/azure/devops/serviceendpoint/endpoints) diff --git a/docs/cross-service/cross-service-overview.md b/docs/cross-service/cross-service-overview.md index be82ba4d8db..86289b45f4e 100644 --- a/docs/cross-service/cross-service-overview.md +++ b/docs/cross-service/cross-service-overview.md @@ -1,183 +1,60 @@ --- -title: Cross-service integration overview +title: Cross-service overview titleSuffix: Azure DevOps -description: Learn about how Azure DevOps supports collaboration across all its services. +description: Discover how Azure DevOps facilitates collaboration and integration across its core services, enhancing your workflow and productivity. ms.subservice: azure-devops-cross-service ms.custom: cross-service +ai-usage: ai-assisted ms.topic: overview ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 09/28/2022 +ms.date: 03/05/2025 --- -# Cross-service integration and collaboration overview +# Azure DevOps integration of services overview [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -One of the major strengths of Azure DevOps is the integration it supports across its core services. Azure DevOps supports multiple integration points across each of the major services—Azure Boards, Azure Repos, Azure Pipelines, and Azure Test Plans. - -Review this article to understand how to use various features to support collaboration and traceability for all your devops tasks. - +With Azure DevOps, you can connect to and collaborate across its core services. You can use various features to link and track your devops tasks across Azure Boards, Azure Repos, Azure Pipelines, and Azure Test Plans. This article shows you options for how to use the cross-service integration of Azure DevOps to improve your workflow and productivity. +Links to more information: +- [Power Automate, Azure DevOps](https://powerautomate.microsoft.com/connectors/details/shared_visualstudioteamservices/azure-devops/) +- [Power Automate templates for Azure DevOps](https://powerautomate.microsoft.com/connectors/details/shared_visualstudioteamservices/azure-devops/) ## Collaboration across Azure DevOps -Collaborating within and across teams is supported with many of the features summarized in the following table. - +The following table summarizes some of the features that help you work with your team and other teams. -:::row::: - :::column span="1"::: - **Feature** - :::column-end::: - :::column span="3"::: - **Description** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - `@mentions` (add to discussions and comments) - :::column-end::: - :::column span="3"::: - You can @mention a team member or an entire team within a work item form discussion or the comment section of a commit, pull request, or changeset. For details, see [Use @mentions in work items and pull requests](../organizations/notifications/at-mentions.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - `#ID` (link to a work item) - :::column-end::: - :::column span="3"::: - To support end-to-end traceability, you can link to work items from commits, pull requests, and changesets. For details, see [Link to work items from other objects](../organizations/notifications/add-links-to-work-items.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Teams - :::column-end::: - :::column span="3"::: - Each team gets access to a suite of Agile tools and team assets. These tools let teams work autonomously and collaborate with other teams across the enterprise. Each team can configure and customize each tool to support how they work. For quick navigation, they can favorite repositories, pipelines, and test plans. To learn more, see: - - [About teams and Agile tools](../organizations/settings/about-teams-and-settings.md) - - [Set personal or team favorites](../project/navigation/set-favorites.md) - - [Unsubscribe from default notification](../organizations/notifications/unsubscribe-default-notification.md) - - [Manage team, group, and Global notifications](../organizations/notifications/manage-team-group-global-organization-notifications.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Set up alerts - :::column-end::: - :::column span="3"::: - Configure or opt out of personal, team, project, or organization-level alerts. Subscribe to email alerts when changes occur to work items, code reviews, pull requests, source control files, builds and more. To learn more, see: - - [About notifications](../organizations/notifications/about-notifications.md) - - [Manage personal notifications](../organizations/notifications/manage-your-personal-notifications.md) - - [Unsubscribe from default notification](../organizations/notifications/unsubscribe-default-notification.md) - - [Manage team, group, and Global notifications](../organizations/notifications/manage-team-group-global-organization-notifications.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Share summaries by email - :::column-end::: - :::column span="3"::: - - [Email a list of work items](../boards/backlogs/bulk-modify-work-items.md) - - [Email query items](../boards/queries/view-run-query.md) - - [Send release summaries by email](../pipelines/release/index.md#how-do-i-send-release-summaries-by-email) - :::column-end::: -:::row-end::: ---- -::: moniker range=">= azure-devops-2019" -:::row::: - :::column span="1"::: - Wiki - :::column-end::: - :::column span="3"::: - [Embed Azure Boards query results in Wiki](../project/wiki/wiki-markdown-guidance.md#embed-azure-boards-query-results-in-wiki). - :::column-end::: -:::row-end::: ---- -::: moniker-end - +| **Feature** | **Description** | +|-------------|-----------------| +| `@mentions` (add to discussions and comments) | You can [@mention a team member or an entire team](../organizations/notifications/at-mentions.md) within a work item form discussion or the comment section of a commit, pull request, or changeset. | +| `#ID` (link to a work item) | To support end-to-end traceability, you can [link to work items from commits, pull requests, and changesets](../organizations/notifications/add-links-to-work-items.md). | +| Teams | [Each team gets access to a suite of Agile tools](../organizations/settings/about-teams-and-settings.md) and team assets. These tools let teams work autonomously and collaborate with other teams across the enterprise. Each team can configure and customize each tool to support how they work. For quick navigation, they can favorite repositories, pipelines, and test plans. | +| Alerts | Configure or opt out of personal, team, project, or organization-level alerts. [Subscribe to email alerts](../organizations/notifications/about-notifications.md) when changes occur to work items, code reviews, pull requests, source control files, builds, and more. | +| Summaries by email | - [Email a list of work items](../boards/backlogs/bulk-modify-work-items.md)
- [Email query items](../boards/queries/view-run-query.md)
- [Send release summaries by email](../pipelines/release/index.md) | +| Wiki | [Embed Azure Boards query results in Wiki](../project/wiki/markdown-guidance.md#embed-azure-boards-query-results-in-wiki). | -## Azure Boards - Azure Repos +## Azure Boards and Azure Repos integration -The following table summarizes the integration points between Azure Boards and Azure Repos. Through various link types, you can track code changes—commits and pull requests for Git, and changesets and versioned items for Team Foundation Version Control (TFVC)—that support development of user stories and features. The link types used to construct these links include *Branch , Commit, Pull Request*, and *Tag* for Git repositories, and *Changeset*, and *Versioned Item* for TFVC repositories. To learn more, see [Link to work items from other objects, View list of linked objects](../organizations/notifications/add-links-to-work-items.md#view-list-links). +You can link code changes to user stories and features with different link types. For Git, use *Branch*, *Commit*, *Pull Request*, or *Tag*. For TFVC, use *Changeset* or *Versioned Item*. :::image type="content" source="media/overview/concept-link-types-repos.png" alt-text="Conceptual image of link types that link work items to Azure Repos objects."::: +The following table summarizes the integration points between Azure Boards and Azure Repos. -:::row::: - :::column span="1"::: - **Feature** - :::column-end::: - :::column span="2"::: - **Description** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Drive Git development from work item(s) - :::column-end::: - :::column span="2"::: - You can initiate a Git branch or link to Git commits or pull requests and drive your Git development cycle for a work item from within the work item form. - :::image type="content" source="media/overview/development-control-git.png" alt-text="Screenshot of Development control for Git repositories."::: - For details, see [Drive Git development from a work item](../boards/backlogs/connect-work-items-to-git-dev-ops.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Automatically link and transition work items with Git commits - :::column-end::: - :::column span="2"::: - You can enable or disable the following options for a single Git repository: - - Automatically create links for work items mentioned in a commit comment - - Allow mentions in commit comments to close work items - - Remember user preferences for completing work items with pull requests. -
For details, see [Configure branch policies to support integration](../repos/git/configure-repos-work-tracking.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Check for linked work items in a Git branch - :::column-end::: - :::column span="2"::: - Encourage traceability by checking for linked work items on pull requests. For details, see [Configure branch policies to support integration](../repos/git/configure-repos-work-tracking.md). - :::column-end::: -:::row-end::: ---- -::: moniker range=">= tfs-2018" -:::row::: - :::column span="1"::: - Auto complete work items with pull requests - :::column-end::: - :::column span="2"::: - When you link a work item to a pull request (PR), you have the option to automatically complete those work items when you successfully complete the PR. The system defaults to your selection for future PRs. For details, see [Auto complete of work items with pull requests](../boards/work-items/auto-complete-work-items-pull-requests.md). - :::column-end::: -:::row-end::: ---- -::: moniker-end -:::row::: - :::column span="1"::: - View list of code objects a single work item is linked to - :::column-end::: - :::column span="2"::: - You can link work items to code changes, builds, and releases—providing an audit trail of how a feature has been developed - :::column-end::: -:::row-end::: ---- - - +| **Feature** | **Description** | +|-------------|-----------------| +| Drive Git development from work items | You can initiate a Git branch or link to Git commits or pull requests and [drive your Git development cycle for a work item](../boards/backlogs/connect-work-items-to-git-dev-ops.md) from within the work item form. | +| Automatically link and transition work items with Git commits | For a Git repository, you can turn on or off the following options:
- Close work items with mentions in commit comments.
- Remember user choices for completing work items with pull requests.
- Link work items from commit comments. You can also automate linking from commits or pull requests in repo settings.
- Commit mention linking: Turn on to link commits to work items with #*WorkItemID* in commit messages. Turn off when you push a repo from a different account or service. Azure DevOps automatically turns off this feature when you import a repo.
- Commit mention work item resolution: Turn on to close work items with Fixes #*WorkItemID* in commits.
- Work item transition preferences: On by default, it remembers each user’s option to complete linked work items with pull requests. You can turn this feature off to discourage users from completing work items with pull requests. When it's off, users have to choose to complete work items for each pull request. | +| Check for linked work items in a Git branch | Encourage traceability by checking for linked work items on pull requests. | +| Auto complete work items with pull requests | When you link a work item to a pull request (PR), you can [automatically complete](../boards/work-items/auto-complete-work-items-pull-requests.md) those work items when you successfully complete the PR. The system defaults to your selection for future PRs. | +| View list of code objects a single work item is linked to | You can link work items to code changes, builds, and releases—providing an audit trail of the feature development. | +| Query for external links | You can [query for work items that contain links](../boards/queries/linking-attachments.md) to branches, commits, pull requests, or tags. | +| Configure branch policies to support work tracking | To ensure that changes to a branch have links to work items, you configure the branch policy for a Git repository in repo settings. Turn on the **Check for linked work items** option. Choose **Required** to mandate all pull requests have at least one linked work item in order to be completed. Choose **Optional** to allow pull requests without linked work items, but warn about it. | - -## Azure Boards - Azure Pipelines +## Azure Boards and Azure Pipelines integration The following table summarizes the integration points between Azure Boards and Azure Pipelines. Several features provide support for end-to-end traceability as user stories and features move through the development cycle. As with Azure Repos, you can link work items to pipeline objects with the following link types: *Build, Integrated in build*, and *Integrated in release*. @@ -200,9 +77,7 @@ The following table summarizes the integration points between Azure Boards and A ::: moniker range=">= azure-devops-2020" Link work items to builds in the same or other project within the organization or collection. ::: moniker-end - ::: moniker range="< azure-devops-2020" - Link work items to builds in the same project within the organization or collection. - ::: moniker-end + :::column-end::: :::row-end::: :::row::: @@ -210,18 +85,17 @@ The following table summarizes the integration points between Azure Boards and A Set integration option to automatically create *Integrated in build* links to work items linked to a branch, commit, or pull request associated with a pipeline. :::column-end::: :::column span="2"::: - Required to populate the **Development** control with Integrated in build links. The work items or commits that are part of a release are computed from the versions of artifacts. For example, each build in Azure Pipelines is associated with a set of work items and commits. For details, see [Configure pipelines to support integration](../pipelines/integrations/configure-pipelines-work-tracking.md). - :::image type="content" source="media/overview/development-control.png" alt-text="Screenshot of Development control showing several links."::: + Required to populate the **Development** control with *Integrated in build* links. The work items or commits that are part of a release are computed from the versions of artifacts. For example, each build in Azure Pipelines is associated with a set of work items and commits. For more information, see [Configure pipelines to support integration](../pipelines/integrations/configure-pipelines-work-tracking.md). :::column-end::: :::row-end::: --- ::: moniker range="azure-devops" :::row::: :::column span="1"::: - Set option and branch to automatically create *Integrated in build* and *Integrated in release stage* links to work items linked to a branch, commit, or pull request associated with a Classic or YAML pipeline. + To link work items to builds and releases, choose an option and a branch for a Classic or YAML pipeline. This action creates *Integrated in build* and *Integrated in release stage* links for work items that are linked to a branch, commit, or pull request. :::column-end::: :::column span="2"::: - Required to populate the work item form **Development** control with *Integrated in build* links and the **Deployment** control with *Integrated in release stage* links when running a Classic or YAML pipeline. For details, see [Configure pipelines to support integration](../pipelines/integrations/configure-pipelines-work-tracking.md). + Required to populate the work item form **Development** control with *Integrated in build* links and the **Deployment** control with *Integrated in release stage* links when running a Classic or YAML pipeline. For more information, see [Configure pipelines to support integration](../pipelines/integrations/configure-pipelines-work-tracking.md). :::column-end::: :::row-end::: --- @@ -232,7 +106,7 @@ The following table summarizes the integration points between Azure Boards and A Set integration option to automatically create *Integrated in release stage* links to work items linked to a branch, commit, or pull request associated with a release. :::column-end::: :::column span="2"::: - Required to populate **Deployment** control in work item form with **Integrated in release stage** links. For details, see [Release pipelines, How do I integrate and report release status?](../pipelines/release/index.md#reportstatus). + Required to populate **Deployment** control in work item form with **Integrated in release stage** links. For more information, see [Release pipelines, How do I integrate and report release status?](../pipelines/release/index.md). :::column-end::: :::row-end::: --- @@ -264,7 +138,7 @@ The following table summarizes the integration points between Azure Boards and A View list of build or release objects a single work item is linked to :::column-end::: :::column span="2"::: - You can link work items to builds and releases—providing an audit trail of how a feature has been built and deployed. To learn more, see [Link to work items from other objects, View list of linked objects](../organizations/notifications/add-links-to-work-items.md#view-list-links). + You can [link work items to builds and releases](../organizations/notifications/add-links-to-work-items.md#view-list-links)—providing an audit trail of the feature development and deployment. :::column-end::: :::row-end::: --- @@ -273,7 +147,7 @@ The following table summarizes the integration points between Azure Boards and A Query for external links. :::column-end::: :::column span="2"::: - You can query for work items that contain external links. For details, see [Query by link or attachment count](../boards/queries/linking-attachments.md) + You can [query for work items that contain external links](../boards/queries/linking-attachments.md). :::column-end::: :::row-end::: --- @@ -283,8 +157,7 @@ The following table summarizes the integration points between Azure Boards and A View and quickly navigate to release stages a work item is linked to. :::column-end::: :::column span="2"::: - The work item form **Deployment** control lists set of stages work item is associated with. You can expand a stage to view status of select runs and quickly open each stage or run. For details, see [Link and view work items to builds and deployments](../boards/work-items/work-item-deployments-control.md). - :::image type="content" source="media/overview/deployment-control.png" alt-text="Screenshot of Deployment control showing several links."::: + The **Deployment** control on the work item form shows the stages that the work item is linked to. You can see the status of some runs and open each stage or run by expanding a stage. For more information, see [Link and view work items to deployments](../boards/backlogs/add-link.md#link-work-items-to-deployments). :::column-end::: :::row-end::: --- @@ -295,7 +168,7 @@ The following table summarizes the integration points between Azure Boards and A Create a work item on failure, optionally set values for a work item field (Classic) :::column-end::: :::column span="2"::: - Automatically create a work item and set fields when a build fails. For details, see [Build options](../pipelines/build/options.md). + [Automatically create a work item and set fields when a build fails](../pipelines/build/options.md). :::column-end::: :::row-end::: --- @@ -306,7 +179,7 @@ The following table summarizes the integration points between Azure Boards and A Create a work item on failure (Classic or YAML), optionally set values for a work item field (Classic) :::column-end::: :::column span="2"::: - Automatically create a work item and set fields when a build fails. For details, see [Build options](../pipelines/build/options.md) for Classic pipelines, and [Customize pipelines, Create work item on failure](../pipelines/customize-pipeline.md#create-work-item-on-failure). + Automatically create a work item and set fields when a build fails. For more information, see [Build options](../pipelines/build/options.md) for Classic pipelines, and [Customize pipelines, Create work item on failure](../pipelines/customize-pipeline.md#create-work-item-on-failure). :::column-end::: :::row-end::: --- @@ -317,377 +190,98 @@ The following table summarizes the integration points between Azure Boards and A Query Work Items task. Ensure the number of matching work items returned from a query is within a threshold. :::column-end::: :::column span="2"::: - Use this task to ensure the number of matching items returned by a work item query is within the configured thresholds. For details, see [Query Work Items task, Control deployments with gates and approvals](/azure/devops/pipelines/tasks/reference/query-work-items-v0). + Use this task to ensure the number of matching items returned by a work item query is within the configured thresholds. For more information, see [Query Work Items task, Control deployments with gates and approvals](/azure/devops/pipelines/tasks/reference/query-work-items-v0). :::column-end::: :::row-end::: --- ::: moniker-end - -::: moniker range=">= tfs-2018" - -## Azure Repos - Azure Pipelines +## Azure Repos and Azure Pipelines integration Azure Pipelines provides support for building code stored in Azure Repos, either a Git or Team Foundation Version Control (TFVC) repository. Other repositories that Azure Pipelines supports are listed in [Supported source repositories](../pipelines/repos/index.md). The following table summarizes the integration features between Azure Repos and Azure Pipelines. -::: moniker-end -::: moniker range=">= tfs-2018" -:::row::: - :::column span="1"::: - **Feature** - :::column-end::: - :::column span="2"::: - **Description** - :::column-end::: -:::row-end::: ---- -::: moniker-end -::: moniker range=">= tfs-2018" -:::row::: - :::column span="1"::: - Report deployment status - :::column-end::: - :::column span="2"::: - Indicates the status of a deployment on the **Files**, **Commits**, and **Branches** pages for Git repositories. This feature improves the traceability from code commit to deployment. You can configure the release environments to report deployment status. For details, see [Release pipelines, How do I integrate and report release status?](../pipelines/release/index.md#reportstatus).. - :::column-end::: -:::row-end::: ---- -::: moniker-end ::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - Release status badge - :::column-end::: - :::column span="2"::: - Post the status of your most recent pipeline build in your repository. To learn how, see [Create your first pipeline, Add a status badge to your repository](../pipelines/create-first-pipeline.md#add-a-status-badge-to-your-repository). - :::column-end::: -:::row-end::: ---- -::: moniker-end -:::row::: - :::column span="1"::: - Code coverage - :::column-end::: - :::column span="2"::: - Publish and review code coverage results that indicate the proportion of your project's code that is actually being tested. To learn more, see [Publish Code Coverage Results task](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v1) and [Review code coverage results](../pipelines/test/review-code-coverage-results.md). - :::column-end::: -:::row-end::: ---- - +| **Feature** | **Description** | +|-------------|-----------------| +| Report deployment status | Indicates the status of a deployment on the **Files**, **Commits**, and **Branches** pages for Git repositories. This feature improves the traceability from code commit to deployment. You can [configure the release environments to report deployment status](../pipelines/release/index.md). | +| Release status badge | [Post the status of your most recent pipeline build in your repository](../pipelines/create-first-pipeline.md#add-a-status-badge-to-your-repository). | +| Code coverage | [Publish](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v1) and [review](../pipelines/test/review-code-coverage-results.md) code coverage results that indicate the proportion of your project's code that is actually being tested. | - - -## Azure Boards - Azure Repos - Azure Test Plans +::: moniker-end -Several collaboration scenarios are supported through Azure Boards work item types. As with other work item types, you can use [managed queries](../boards/queries/about-managed-queries.md) and the [Azure DevOps search function](../project/search/get-started-search.md) to find and list work items. +::: moniker range="< azure-devops" -> [!NOTE] -> Several of these work item types—such as Feedback Request, Code Review Request, Shared Steps, and Shared Parameters— are designed to be created through a specific tool or form. They aren't meant to be created manually. Therefore, they are added to the Hidden Types category. Work item types that are added to the Hidden Types category don't appear in the menus used to add work items. -> -> Also, for the Inherited process model, you can only customize the following work item types: Test Plan, Test Suite, Test Case. +| **Feature** | **Description** | +|-------------|-----------------| +| Report deployment status | Indicates the status of a deployment on the **Files**, **Commits**, and **Branches** pages for Git repositories. This feature improves the traceability from code commit to deployment. You can [configure the release environments to report deployment status](../pipelines/release/index.md). | +| Code coverage | [Publish](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v1) and [review](../pipelines/test/review-code-coverage-results.md) code coverage results that indicate the proportion of your project's code that is actually being tested. | -:::row::: - :::column span="1"::: - **Scenario** - :::column-end::: - :::column span="1"::: - **Work item type** - :::column-end::: - :::column span="3"::: - **Description** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Request code review - :::column-end::: - :::column span="1"::: - **Code Review Request** - :::column-end::: - :::column span="3"::: - Tracks information entered into the TFVC New Code Review form. To learn more, see [Get your code reviewed with Visual Studio](../repos/tfvc/get-code-reviewed-vs.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Provide code review - :::column-end::: - :::column span="1"::: - **Code Review Response** - :::column-end::: - :::column span="3"::: - Tracks review comments provided by code reviewers in response to a code review request. To learn more, see [Respond to the code review request](../repos/tfvc/get-code-reviewed-vs.md#respond-to-the-code-review-request). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Request feedback - :::column-end::: - :::column span="1"::: - **Feedback Request** - :::column-end::: - :::column span="3"::: - Tracks information entered into a request feedback form. There are two forms that you can use to initiate a feedback request. - - [Request stakeholder feedback](../test/request-stakeholder-feedback.md) - - [Get feedback](/previous-versions/azure/devops/project/feedback/get-feedback). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Provide feedback - :::column-end::: - :::column span="1"::: - **Feedback Review** - :::column-end::: - :::column span="3"::: - Enables stakeholders to provide feedback based on request for feedback or by volunteering feedback using the [Microsoft Test & Feedback](https://marketplace.visualstudio.com/items?itemName=ms.vss-exploratorytesting-web) marketplace extension. To learn more, see the following articles: - - [Provide feedback ](../test/provide-stakeholder-feedback.md) - - [Voluntarily provide stakeholder feedback](../test/voluntary-stakeholder-feedback.md) - - [Give feedback](/previous-versions/azure/devops/project/feedback/give-feedback). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Manual testing - :::column-end::: - :::column span="1"::: - **Test Plan** - :::column-end::: - :::column span="3"::: - Groups one or more test suites and individual test cases together. Test plans include static test suites, requirement-based suites, and query-based suites. To get started, see [Create test plans and test suites](../test/create-a-test-plan.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Manual testing - :::column-end::: - :::column span="1"::: - **Test Suite** - :::column-end::: - :::column span="3"::: - Groups one or more test cases into separate testing scenarios within a single test plan. Grouping test cases makes it easier to see which scenarios are complete. To learn more, see [Create test plans and test suites](../test/create-a-test-plan.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Manual testing - :::column-end::: - :::column span="1"::: - **Test Case** - :::column-end::: - :::column span="3"::: - Defines steps used to validate individual parts of your code to ensure your code works correctly, has no errors, and meets business and customer requirements. You can add individual test cases to a test plan without creating a test suite. More than one test suite or test plan can refer to a test case. You can effectively reuse test cases without having to copy or clone them for each suite or plan. To learn more, see [Create manual test cases](../test/create-test-cases.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Manual testing - :::column-end::: - :::column span="1"::: - **Shared Steps** - :::column-end::: - :::column span="3"::: - Enables sharing steps across several test cases. For details, see [Share steps between test cases](/previous-versions/azure/devops/test/mtm/share-steps-between-test-cases). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Manual testing - :::column-end::: - :::column span="1"::: - **Shared Parameters** - :::column-end::: - :::column span="3"::: - Enables repeating the same test cases with different data. For more information, see [Repeat a test with different data](../test/repeat-test-with-different-data.md). - :::column-end::: -:::row-end::: ---- +::: moniker-end -### Test work item types + -Work item types that support the test experience are linked together using the link types shown in the following image. These include *Tested By/Tests*, *Test Cases/Shared Steps*, and *Reference By/References*. +## Azure Boards, Azure Repos, and Azure Test Plans integration -![Test management work item types](../boards/work-items/guidance/media/ALM_PT_WITS_TestExperience.png) +Several collaboration scenarios are supported through Azure Boards work item types. You can use [managed queries](../boards/queries/about-managed-queries.md) and the [Azure DevOps search function](../project/search/get-started-search.md) to find and list work items. -From the web portal, you can view which test cases are defined for a test suite, and which test suites are defined for a test plan. However, these objects aren't connected to each other through specific link types. - +> [!NOTE] +> You should create some work item types—such as Feedback Request, Code Review Request, Shared Steps, and Shared Parameters—through specific tools or forms. These types get added to the Hidden Types category and don't appear in the menus used to add work items. +> +> For the Inherited process model, you can only customize the following work item types: Test Plan, Test Suite, and Test Case. -### Bug tracking +| **Scenario** | **Work item type** | **Description** | +|--------------|--------------------|-----------------| +| Request code review | **Code Review Request** | Tracks information entered into the TFVC New Code Review form. For more information, see [Get your code reviewed with Visual Studio](../repos/tfvc/get-code-reviewed-vs.md). | +| Provide code review | **Code Review Response** | Tracks review comments provided by code reviewers in [response to a code review request](../repos/tfvc/get-code-reviewed-vs.md#respond-to-the-code-review-request). | +| Request feedback | **Feedback Request** | Tracks information entered into a request feedback form. Use the following forms to initiate a feedback request.
- [Request stakeholder feedback](../test/request-stakeholder-feedback.md)
- [Get feedback](/previous-versions/azure/devops/project/feedback/get-feedback). | +| Provide feedback | **Feedback Review** | Lets stakeholders [provide feedback](../test/provide-stakeholder-feedback.md) based on requests for feedback or by [volunteering feedback](../test/voluntary-stakeholder-feedback.md) using the [Microsoft Test & Feedback](https://marketplace.visualstudio.com/items?itemName=ms.vss-exploratorytesting-web) Marketplace extension. | +| Manual testing | **Test Plan** | Groups one or more test suites and individual test cases together. Test plans include static test suites, requirement-based suites, and query-based suites. To get started, see [Create test plans and test suites](../test/create-a-test-plan.md). | +| Manual testing | **Test Suite** | Groups one or more test cases into separate testing scenarios within a single test plan. Grouping test cases makes it easier to see which scenarios are complete. | +| Manual testing | **Test Case** | Defines steps used to validate individual parts of your code to ensure your code works correctly, has no errors, and meets business and customer requirements. You can [add individual test cases](../test/create-test-cases.md) to a test plan without creating a test suite. More than one test suite or test plan can refer to a test case. You can effectively reuse test cases without having to copy or clone them for each suite or plan. | +| Manual testing | **Shared Steps** | Enables [sharing steps across several test cases](/previous-versions/azure/devops/test/mtm/share-steps-between-test-cases). | +| Manual testing | **Shared Parameters** | Enables [repeating the same test cases with different data](../test/repeat-test-with-different-data.md). | -When tracking bugs using the Bug work item type, note the following supported integrations. +### Test work item types +Work item types that support the test experience are linked together using the link types shown in the following image. These types include *Tested By/Tests*, *Test Cases/Shared Steps*, and *Reference By/References*. -:::row::: - :::column span="1"::: - **Scenario** - :::column-end::: - :::column span="3"::: - **Description** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Create a bug from a testing tool - :::column-end::: - :::column span="3"::: - You can add a bug from Test Runner or the Test & Feedback extension. To learn more, see [Define, capture, triage, and manage bugs](../boards/backlogs/manage-bugs.md#create-a-bug-from-a-testing-tool). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Create inline tests linked to bugs or user stories - :::column-end::: - :::column span="3"::: - When your team tracks bugs as requirements, you can use the Kanban board to add tests to verify bug fixes or user stories. To learn more, see [Add, run, and update inline tests](../boards/boards/add-run-update-tests.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Track build information with bugs - :::column-end::: - :::column span="3"::: - The Bug work item form contains System Info, Found in Build, and Integrated in Build that support tracking code defects found and resolved within pipeline builds. To learn more, see [Query based on build and test integration fields](../boards/queries/build-test-integration.md). - :::column-end::: -:::row-end::: ---- +![Screenshot of the Test management work item types.](../boards/work-items/guidance/media/ALM_PT_WITS_TestExperience.png) +You can use the web portal to see the test cases that are defined for a test suite, and the test suites that are defined for a test plan. But, there's no specific link type that connects these objects to each other. -::: moniker range=">= azure-devops-2019" +### Track bugs -## Azure Pipelines - Azure Test Plans +The Bug work item type supports the following integrations that you should be aware of when you're tracking bugs. -Azure Test Plans is fully integrated with Azure Pipelines to support testing within continuous integration/continuous deployment (CI/CD). Test plans and test cases can be associated with build or release pipelines. Pipeline tasks can be added to pipeline definitions to capture and publish test results. Test results can be reviewed via built in progress reports and pipeline test reports. The following table summarizes the integration points between Azure Pipelines and Azure Test Plans. +| **Scenario** | **Description** | +|--------------|-----------------| +| Create a bug from a testing tool | You can add a bug from Test Runner or the Test & Feedback extension. For more information, see [Define, capture, triage, and manage bugs](../boards/backlogs/manage-bugs.md#create-a-bug-from-a-testing-tool). | +| Create inline tests linked to bugs or user stories | When your team tracks bugs as requirements, you can use the board to [add tests](../boards/boards/add-run-update-tests.md) to verify bug fixes or user stories. | +| Track build information with bugs | The Bug work item form contains System Info, Found in Build, and Integrated in Build, which support tracking code defects found and resolved within pipeline builds. For more information, see [Query based on build and test integration fields](../boards/queries/build-test-integration.md). | -:::row::: - :::column span="1"::: - **Feature** - :::column-end::: - :::column span="2"::: - **Description** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Test plans setting - :::column-end::: - :::column span="2"::: - With test plan settings, you configure the Test Run settings to associate build or release pipelines and Test Outcome settings. To learn more, see [Run automated tests from test plans](../test/run-automated-tests-from-test-hub.md) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Pipeline test-enable tasks - :::column-end::: - :::column span="2"::: - Specify test-enable tasks within a pipeline definition. Azure Pipelines provides several tasks, including those listed below, that support a comprehensive test reporting and analytics experience. - - [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2): Use to publish test results to Azure Pipelines. - - [Visual Studio Test task](/azure/devops/pipelines/tasks/reference/vstest-v2): Use to run unit and functional tests (Selenium, Appium, Coded UI test, and more) using the Visual Studio Test Runner. - - [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2): Use to build, test, package, or publish a dotnet application. - For additional tasks, see [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Run automated tests in build pipelines - :::column-end::: - :::column span="2"::: - Associate test plans with a build pipeline so that they run with each build. To learn more, see [Run automated tests from test plans](..//test/run-automated-tests-from-test-hub.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Associate automated tests with test cases - :::column-end::: - :::column span="2"::: - See [Associate automated tests with test cases](../test/associate-automated-test-with-test-case.md) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Set retention policy for automated test results associated with builds - :::column-end::: - :::column span="2"::: - You can set the test retention policy for automated buidls from the **Pipelines>Retention** page. See [Set test retention policies](../test/how-long-to-keep-test-results.md) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Requirements traceability - :::column-end::: - :::column span="2"::: - The Requirements quality widget supports tracking quality continuously from a build or release pipeline. The widget shows the mapping between a requirement and latest test results executed against that requirement. It provides insights into requirements traceability. to learn more, see [Requirements traceability](../pipelines/test/requirements-traceability.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Test results trend - :::column-end::: - :::column span="2"::: - The Test results trend configurable widget displays the trend of test results for the selected build or release pipeline. The widget helps you visualize the test trends over a period of time, thereby surfacing patterns about test failures, test duration etc. To learn more, see [Configure the Test Results Trend (Advanced) widget](../report/dashboards/configure-test-results-trend.md) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Deployment status - :::column-end::: - :::column span="2"::: - The Deployment status configurable widget shows a combined view of the deployment status and test pass rate across multiple environments for a recent set of builds. You configure the widget by specifying a build pipeline, branch, and linked release pipelines. To view the test summary across multiple environments in a release, the widget provides a matrix view of each environment and corresponding test pass rate. See [Associate automated tests with test cases](../test/how-long-to-keep-test-results.md) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - View test results in builds and releases - :::column-end::: - :::column span="2"::: - Both build and release summaries provide details of test execution. Review these summaries to assess pipeline quality, review traceability, and troubleshoot failures. Choose **Test summary** to view the details in the **Tests** tab. To learn more, see [Review test results, Tests tab](../pipelines/test/review-continuous-test-results-after-build.md#tests-tab). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Test analytics for builds - :::column-end::: - :::column span="2"::: - Each build summary includes an **Analytics** tab that hosts the Test analytics report. To learn more, see [Test Analytics](../pipelines/test/test-analytics.md) - :::column-end::: -:::row-end::: ---- - -::: moniker-end +## Azure Pipelines and Azure Test Plans integration +Azure Test Plans is fully integrated with Azure Pipelines to support testing within continuous integration/continuous deployment (CI/CD). You can associate test plans and test cases with build or release pipelines. Add pipeline tasks to pipeline definitions to capture and publish test results. Review test results via built-in progress reports and pipeline test reports. The following table summarizes the integration points between Azure Pipelines and Azure Test Plans. - -::: moniker range=">= azure-devops-2019" +| **Feature** | **Description** | +|-------------|-----------------| +| Test plans setting | With test plan settings, you can [configure the Test Run settings](../test/run-automated-tests-from-test-hub.md) to associate build or release pipelines and Test Outcome settings. | +| Pipeline test-enable tasks | Specify test-enable tasks within a pipeline definition. Azure Pipelines provides several tasks, including the following tasks, that support a comprehensive test reporting and analytics experience.
- [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2): Use to publish test results to Azure Pipelines.
- [Visual Studio Test task](/azure/devops/pipelines/tasks/reference/vstest-v2): Use to run unit and functional tests (Selenium, Appium, Coded UI test, and more) using the Visual Studio Test Runner.
- [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2): Use to build, test, package, or publish a dotnet application.
For other tasks, see [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) | +| Run automated tests in build pipelines | [Associate test plans with a build pipeline](../test/run-automated-tests-from-test-hub.md) so that they run with each build. | +| Associate automated tests with test cases | [Associate automated tests with test cases](../test/associate-automated-test-with-test-case.md). | +| Set retention policy for automated test results associated with builds | You can [set the test retention policy](../test/how-long-to-keep-test-results.md) for automated builds from the **Pipelines** > **Retention** page. | +| Requirements traceability | The Requirements quality widget supports tracking quality continuously from a build or release pipeline. The widget shows the mapping between a requirement and latest test results executed against that requirement. It provides insights into [requirements traceability](../pipelines/test/requirements-traceability.md). | +| Test results trend | The Test results trend configurable widget displays the trend of test results for the selected build or release pipeline. The widget helps you visualize the test trends over a period of time, surfacing patterns about test failures, test duration, and so on. For more information, see [Configure the Test Results Trend (Advanced) widget](../report/dashboards/configure-test-results-trend.md) | +| Deployment status | The Deployment status configurable widget shows a combined view of the deployment status and test pass rate across multiple environments for a recent set of builds. You configure the widget by specifying a build pipeline, branch, and linked release pipelines. To view the test summary across multiple environments in a release, the widget provides a matrix view of each environment and corresponding test pass rate. See [Associate automated tests with test cases](../test/how-long-to-keep-test-results.md) | +| View test results in builds and releases | Both build and release summaries provide details of test execution. [Review these summaries](../pipelines/test/review-continuous-test-results-after-build.md#tests-tab) to assess pipeline quality, review traceability, and troubleshoot failures. Choose **Test summary** to view the details in the **Tests** tab. | +| Test analytics for builds | Each build summary includes an **Analytics** tab that hosts the [Test analytics](../pipelines/test/test-analytics.md) report. | ## Dashboards, reporting, and Analytics -Dashboards provide an easy way to monitor progress and status. Using widgets, teams can add configurable widgets to support their goals. To learn more, see [About dashboards, charts, reports, & widgets](../report/dashboards/overview.md). - -The Analytics service is the reporting platform for Azure DevOps, replacing the previous platform based on SQL Server Reporting Services. Built for reporting, Analytics is optimized for fast read-access and server-based aggregations. The Analytics service provides: +[Dashboards](../report/dashboards/overview.md) provide an easy way to monitor progress and status. Teams can add configurable widgets to support their goals. The [Analytics service](../report/powerbi/what-is-analytics.md) is the reporting platform for Azure DevOps, and replaces the previous platform based on SQL Server Reporting Services. Analytics is optimized for fast read-access and server-based aggregations and provides the following benefits: - Analytics widgets that you can add to your dashboards - In-context Analytics reports available from select Azure DevOps pages @@ -696,157 +290,21 @@ The Analytics service is the reporting platform for Azure DevOps, replacing the - Custom reports you can create using OData queries - Support to develop and add your custom Analytics widgets you can add to dashboards -To learn more, see [What is the Analytics service?](../report/powerbi/what-is-analytics.md) - -::: moniker-end - - -::: moniker range="< azure-devops-2019" - -## Dashboards and reporting - -Dashboards provide an easy way to monitor progress and status. Using widgets, teams can add configurable widgets to support their goals. To learn more, see [About dashboards, charts, reports, & widgets](../report/dashboards/overview.md). - -SQL Server reports provide additional monitoring capabilities. To learn more, see [Reporting Services reports](/sql/reporting-services/reports/reporting-services-reports-ssrs). - -::: moniker-end - -Built-in widgets you can add to your dashboard are listed below. They are organized under the service they support. You may find additional widgets from the [Azure DevOps Marketplace](https://marketplace.visualstudio.com/azuredevops). - -[!INCLUDE [temp](../report/includes/widgets-oob.md)] - - -::: moniker range=">= azure-devops-2019" +You can add the following built-in widgets to your dashboard. They're organized under the service they support. You might find more widgets from the [Azure DevOps Marketplace](https://marketplace.visualstudio.com/azuredevops). ## Data available from Analytics -Analytics provides the reporting platform for Azure DevOps. Analytics is generally available for Azure DevOps Service and Azure DevOps Server 2020. It is in preview for Azure DevOps Server 2019. - - You can access the following data from Analytics. - ---- -:::row::: - :::column span="1"::: - - **Service** - :::column-end::: - :::column span="1"::: - - **Data availability** - :::column-end::: - :::column span="1"::: - **Azure DevOps Services** - **Azure DevOps Server 2020** - :::column-end::: - :::column span="1"::: - - **Azure DevOps Server 2019** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - **Boards** - :::column-end::: - :::column span="1"::: - [Widgets](../report/dashboards/analytics-widgets.md) - [In-context reports](../report/dashboards/overview.md#in-context-reports-work-tracking) - [OData](../report/extend-analytics/quick-ref.md) - [Power BI](../report/powerbi/overview.md) - :::column-end::: - :::column span="1"::: - ✔️ - ✔️ - ✔️ - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - - ✔️ - ✔️ - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - **Repos** - :::column-end::: - :::column span="1"::: - None - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - **Pipelines** - :::column-end::: - :::column span="1"::: - [Test Analytics](../pipelines/test/test-analytics.md) - [Pipeline Analytics](../pipelines/reports/pipelinereport.md) - [OData Preview](../report/extend-analytics/quick-ref.md) - :::column-end::: - :::column span="1"::: - ✔️ - ✔️ - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - - - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - **Test Plans** - :::column-end::: - :::column span="1"::: - [Progress Report](../test/track-test-status.md) - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - **Artifacts** - :::column-end::: - :::column span="1"::: - None - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: -:::row-end::: ---- - - -::: moniker-end +Analytics provides the reporting platform for Azure DevOps. For information, see [Data available from Analytics](../report/powerbi/data-available-in-analytics.md). -## Automation and Azure DevOps connectors +## Automation and connectors -Several connectors are supported by Microsoft products to support automation or integration with other applications and services. You can learn more from the following resources. +Microsoft products support automation or integration with several other applications and services. For more information, see the following articles. - [Power Automate, Azure DevOps](https://powerautomate.microsoft.com/connectors/details/shared_visualstudioteamservices/azure-devops/) - [Power Automate templates for Azure DevOps](https://powerautomate.microsoft.com/connectors/details/shared_visualstudioteamservices/azure-devops/) -- [Microsoft Power Automate documentation](/power-automate/) ## Related articles - [End-to-end traceability](end-to-end-traceability.md) - [Data model for Analytics](../report/extend-analytics/data-model-analytics-service.md) +- [GitHub integration](github-integration.md) diff --git a/docs/cross-service/end-to-end-traceability.md b/docs/cross-service/end-to-end-traceability.md index f55202bf0be..430205be35c 100644 --- a/docs/cross-service/end-to-end-traceability.md +++ b/docs/cross-service/end-to-end-traceability.md @@ -1,110 +1,66 @@ --- title: End-to-end traceability titleSuffix: Azure DevOps -description: Learn about the tools and features that support traceability from requirements to deployment +description: Overview of the tools and features that support traceability from requirements to deployment. ms.subservice: azure-devops-cross-service ms.custom: cross-service, cross-project ms.topic: overview +ai-usage: ai-assisted ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 01/26/2021 +ms.date: 03/05/2025 --- -# End-to-end traceability +# About end-to-end traceability [!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] -One of the chief advantages of adopting a platform such as Azure DevOps is the support it provides to trace work from requirements to deployment. You gain insight at each step of decisions made and the software deployed. The scenarios illustrated in this article are supported when you use Azure Repos git repositories. +Azure DevOps supports end-to-end traceability by linking various objects in your development process, such as work items, branches, commits, pull requests, builds, and releases. You can use built-in reports and Analytics to monitor traceability in real time. -The following are some of the supported tasks to facilitate end-to-end traceability: - -> [!div class="checklist"] -> - Create a branch from a requirement -> - Create a pull request of updated branch -> - Validate the pull request using a build pipeline -> - Create and run inline tests on requirements -> - Merge the pull request into the main, default branch -> - Deploy changes into production with deployment status to Azure Boards -> - Monitor and report on requirements traceability - -> [!NOTE] -> *Tracking the origin of work through delivery, and the ability to trace work across the development lifecycle, is essential to achieving end-to-end traceability.* - -End-to-end traceability is supported by linking various objects such as work items, branches, commits, pull requests, builds, and releases. Build in reports and Analytics support the ability to monitor traceability in real time. This article presents an overview of Azure DevOps traceability support without going into the details of how to enable and support traceability. More detailed information is provided under [Related articles](#related-articles). +This article provides an overview of how Azure DevOps enables and supports traceability, with links to more detailed information. ## Traceability and linking +You can track the code changes, builds, and releases that are [linked to a work item](../boards/backlogs/add-link.md) throughout the development lifecycle. This way, your team can see the audit trail of how the work was done or how a bug was fixed by looking at the changes in the code base. -Throughout the development lifecycle, you can capture which code changes, builds, and releases support the completion of a work item. In this way, your team can understand what work was done or how a bug was fixed through the audit trail of changes to the code base. +The link types used for Git repositories are *Build*, *Found in build*, *Integrated in build*, *Branch*, *Commit*, *Pull Request*, and *Integrated in release stage*. -The link types used to construct these links for Git repositories—as illustrated in the following image—are *Build*, *Found in build*, *Integrated in build*, *Branch*, *Commit*, *Pull Request*, and *Integrated in release stage*. - -> [!div class="mx-imgBorder"] -> ![Conceptual image of code, build, and release links to work items.](media/traceability/concept-build-release-links.png) +:::image type="content" source="media/traceability/concept-build-release-links.png" alt-text="Graphic showing how work items, builds, and releases get linked."::: -## Branch from a requirement +## Create a branch and pull request from a work item -You can accomplish many tasks with a single click from the product Kanban board. Here we show creating a branch from a requirement by opening the work item card menu. +- **Branch:** You can create a branch from a work item by opening the work item card menu on the product board or by selecting **Create a branch** in the work item form. The branch is automatically linked to the work item with the *Branch* link type. -> [!div class="mx-imgBorder"] -> ![Screenshot of Kanban board card, menu, choose New branch option.](media/traceability/board-card-menu-new-branch.png) - -You can name and label a branch off the default main branch from the dialog that opens. The work item is automatically linked to the branch you created with the *Branch* link type. - -> [!div class="mx-imgBorder"] -> ![Create a branch dialog.](media/traceability/create-branch-dialog.png) + :::image type="content" source="media/traceability/board-card-menu-new-branch.png" alt-text="Screenshot shows board card with highlighted New branch selection."::: -You can also accomplish this task through the work item form by choosing the **create a branch** link. - -> [!div class="mx-imgBorder"] -> ![Work item form, Create a branch link.](media/traceability/work-item-form-branch.png) - -## Create a pull request from a requirement - -After code changes have been made to the new branch, developers can then create a pull request from the requirement by opening the work item form. - -> [!div class="mx-imgBorder"] -> ![Work item form, Create a pull request.](media/traceability/work-item-form-pull-request.png) - -Another advantage of driving software development from the Kanban board and work item is to encourage developers to input comments as they work to further the audit trail of changes occurring. +- **Pull request:** Once the code changes are done in the new branch, developers can create a pull request from the work item. Using the board and the work item to drive software development encourages developers to add comments as they work, documenting the changes and the reasons behind them. This way, the work item becomes a rich source of information and history for the code changes. + :::image type="content" source="media/traceability/work-item-form-pull-request.png" alt-text="Screenshot shows highlighted selection, Create a pull request, in the work item form."::: -## Add and run tests from requirements - -Just like you can create a new branch from the Kanban board, you can also add tests to the work item. +## Add and run tests from work items -> [!div class="mx-imgBorder"] -> ![Screenshot of Kanban board card, menu, choose Add test option.](media/traceability/board-card-menu-add-test.png) - -> [!NOTE] -> *Test traceability supports linking a test to a set of requirements and validating that the application works as expected.* +Link a test to a set of requirements and validate that the application works as expected. From the board, you can add tests to the work item. Then, you can run your new tests from the board and set the test status. -After adding and defining the tests, you can run them from the Kanban board and set the test status. +Test integration with the board makes it easy for teams to get started with manual testing and then take advantage of the full testing capabilities provided by Azure Test Plans. The board shows the test added to support the requirement when test cases are created from the board or when requirement-based test suites are created under Test Plans. -> [!div class="mx-imgBorder"] -> ![Screenshot of Kanban board card, test menu, choose Run test.](media/traceability/board-card-menu-run-test.png) - -Test integration with the Kanban board makes it easy for teams to get started with manual testing and then take advantage of the full testing capabilities provided by Azure Test Plans. The Kanban board shows the test added to support the requirement when test cases are created from the Kanban board or when requirement-based test suites are created under Test Plans. +:::image type="content" source="media/traceability/board-card-menu-add-test.png" alt-text="Screenshot shows highlighted Add test selection made from board card."::: ### Manual and automated testing -Teams that are moving from manual testing to continuous, automated testing, and have a subset of tests already automated, can execute them as part of a pipeline or on demand. Referred to as *planned testing*, automated tests can be associated to the test cases in a test plan and executed from Test Plans. Once associated, these tests contribute towards the quality metrics of the corresponding requirements. - +You can [run automated tests](../boards/boards/add-run-update-tests.md) in a pipeline or on demand. You can also [link them to test cases](../test/associate-automated-test-with-test-case.md) in a test plan and run them from Test Plans. This way, you can track the quality of your requirements with automated tests, which is called *planned testing*. ## Deploy changes into production -After you define a pipeline to build and release the code changes, you can track the deployment of the requirement to each release stage. From the work item form, you can quickly open the links to builds and releases from the **Deployment** and **Development** control sections. +After you define a pipeline to build and release the code changes, you can track the deployment of the work item requirement to each release stage. From the work item form, you can quickly open the links to builds and releases from the **Deployment** and **Development** sections. -#### Deployment and Development controls +When you open the work item form, it displays the stages to which the requirement is deployed. You can drill down for greater details with the dropdown menu. -When you open the work item form, you can see the stages the requirement has been deployed to, and drill down for greater details by choosing the links. Under the **Development** section, you can open the branch ,commit, or pull requests that have been linked to the requirement. +- **Development** section: Open branches, commits, or pull requests linked to the work item. +- **Deployment** section: Find release information for work items associated with a Git commit that's part of a build being released. -> [!div class="mx-imgBorder"] -> ![Work item form, Deployment control, Release Settings Stages.](/azure/devops/boards/work-items/media/deployments-control/deployments-control-1.png) - -The **Deployment** control shows release information for those work items that have been associated to a Git commit which is part of a build being released. +For more information, see [About kanban boards](../boards/boards/kanban-overview.md). #### Release view @@ -115,133 +71,42 @@ The following image illustrates the multiple environments that the release is ta #### Release settings -You manage the deploy to production view options from the release settings. +Manage your display options from the release settings. The work item deployment control shows you how the releases that are linked to your work items are progressing. You can see the release status for work items that have commits in the build and for release pipelines that you set up to send deployment information to Azure Boards. -> [!div class="mx-imgBorder"] -> ![Screenshot of Release pipeline Options>Integrations settings.](media/traceability/release-pipeline-options.png) +![Screenshot of Release pipeline Options>Integrations settings.](media/traceability/release-pipeline-options.png) - -The work item deployment control displays the status of releases within those work items that are associated with commits in the build and those release pipelines you've configured to report deployment information to Azure Boards. - - - ## Requirements Traceability Matrix -Requirements traceability relates and documents two or more phases of a development process, which can then be traced both forward or backward from its origin. Requirements traceability provides teams insights into indicators such as quality of requirements or readiness to ship requirements. A fundamental aspect of requirements traceability is association of the requirements to test cases, bugs and code changes. - +Requirements traceability provides teams with insights into indicators such as the quality of requirements or readiness to ship requirements. A fundamental aspect of requirements traceability is the association of requirements to test cases, bugs, and code changes. -> [!NOTE] -> *The Requirements Traceability Matrix (RTM) is a document that links requirements throughout the validation process. The purpose of the Requirements Traceability Matrix is to ensure that all requirements defined for a system are tested in the test protocols.* +The Requirements Traceability Matrix (RTM) ensures that all requirements defined for a system are tested in the test protocols. For more information about the Requirements Traceability Matrix, see [Requirements traceability](../pipelines/test/requirements-traceability.md). +### Requirements traceability reports -## Requirements traceability reports - -Requirements traceability reports - - -> [!div class="mx-imgBorder"] -> ![Requirements quality widget](/azure/devops/pipelines/test/media/requirements-traceability/requirements-quality-widget.png) +Requirements traceability reports are a way of showing how different phases of a development process are related and documented. They help teams to measure the quality and completeness of their requirements, and to assess their readiness for delivery. They also help to track the code changes, tests, bugs, and deployments that are linked to the requirements. +![Screenshot of the Requirements quality widget.](/azure/devops/pipelines/test/media/requirements-traceability/requirements-quality-widget.png) -## Bug traceability +### Bug traceability -View the bug with the test result, directly in context, within the Tests tab. The Work Items tab also lists any linked requirements for the test result. +You can see the bug and the test result together in the **Tests** tab, in the same context. The **Work Items** tab also shows any requirements that are linked to the test result. -> [!div class="mx-imgBorder"] -> ![Bug traceability](/azure/devops/pipelines/test/media/requirements-traceability/view-bug-in-tests-tab.png) +For information about bug and source traceability, see [Requirements traceability](../pipelines/test/requirements-traceability.md). ### Source traceability -Based on the build or release pipeline, you can choose the timeline or pipeline view to see what code changes were committed. You can analyze the code changes to identify the potential root cause of the test failure. - -> [!div class="mx-imgBorder"] -> ![Screenshot of source traceability.](/azure/devops/pipelines/test/media/requirements-traceability/view-code-commits.png) - -## Test analytics - -### Test analytics for builds - -To help teams find and fix tests that fail frequently or intermittently, use the top failing tests report. The build summary includes the Analytics page that hosts this report. The top-level view provides a summary of the test pass rate and results for the selected build pipeline, for the specified period. The default range is 14 days. - -> [!div class="mx-imgBorder"] -> ![Screenshot of build analytics.](/azure/devops/pipelines/test/media/test-analytics/view-in-build.png) - - -### Test analytics for releases - -Open a build or release summary to view the top failing tests report. This report provides a granular view of the top failing tests in the pipeline, along with the failure details. - -For tests executing as part of release, access test analytics from the Analytics link at the top right corner. As with build, the summary provides an aggregated view of the test pass rate and results for the specified period. - -> [!div class="mx-imgBorder"] -> ![Screenshot of release analytics.](/azure/devops/pipelines/test/media/test-analytics/test-failures.png) - -### Track the quality of requirements - -To track the quality of work items that belong to the Requirements category. This includes work items such as User Stories (Agile), Product Backlog Items (Scrum) and Requirements (CMMI). - -> [!div class="mx-imgBorder"] -> ![Screenshot of requirements tracking, OData and PowerBi.](/azure/devops/report/powerbi/media/odatapowerbi-storiesoverview.png) - - -### Test failures +Based on the build or release pipeline, you can choose the timeline or pipeline view to see the committed code changes. You can analyze the code changes to identify the potential root cause of the test failure. -Open a build or release summary to view the top failing tests report. This report provides a granular view of the top failing tests in the pipeline, along with the failure details. +![Screenshot of source traceability.](/azure/devops/pipelines/test/media/requirements-traceability/view-code-commits.png) +## Test Analytics -> [!div class="mx-imgBorder"] -> ![Screenshot of test failures.](/azure/devops/pipelines/test/media/test-analytics/test-failures.png) - - - +For more information about Test Analytics for builds and releases, tracking the quality of requirements, and test failures, see [Test Analytics](../pipelines/test/test-analytics.md). ## Related articles -To learn more about any of the concepts introduced in this article, refer to the following articles. - -### Linking - -- [Configure repositories and branches to integrate with work tracking](../repos/git/configure-repos-work-tracking.md?toc=/azure/devops/boards/toc.json&bc=/azure/devops/boards/breadcrumb/toc.json) +- [Learn about requirements traceability](../pipelines/test/requirements-traceability.md) +- [View requirements tracking sample report](../report/powerbi/sample-stories-overview.md) +- [Link work items to other objects](../boards/backlogs/add-link.md) - [Configure pipelines to support work tracking](../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/boards/toc.json&bc=/azure/devops/boards/breadcrumb/toc.json) -- [Drive Git development from a work item](../boards/backlogs/connect-work-items-to-git-dev-ops.md) -- [Link and view work items to builds and deployments](../boards/work-items/work-item-deployments-control.md) -- [Link user stories, issues, bugs, and other work items](../boards/backlogs/add-link.md) -- [Linking, traceability, and managing dependencies](../boards/queries/link-work-items-support-traceability.md) -- [Link type reference](../boards/queries/link-type-reference.md) - - -### Testing - -- [Add, run, and update inline tests](../boards/boards/add-run-update-tests.md) -- [Associate automated tests with test cases](../test/associate-automated-test-with-test-case.md) - - -### Reports and Analytics - -- [Requirements traceability](../pipelines/test/requirements-traceability.md) -- [Requirements tracking sample report](../report/powerbi/sample-stories-overview.md) -- [Requirements tracking rollup sample report](../report/powerbi/sample-stories-overview-rollup.md) -- [Review test results](../pipelines/test/review-continuous-test-results-after-build.md) -- [Test Analytics](../pipelines/test/test-analytics.md) -- [Review code coverage results](../pipelines/test/review-code-coverage-results.md) -- [Code coverage for pull requests](../pipelines/test/codecoverage-for-pullrequests.md) - - +- [Associate automated tests with test cases](../test/associate-automated-test-with-test-case.md) diff --git a/docs/cross-service/github-integration.md b/docs/cross-service/github-integration.md index 87d82d37bc1..83b182efeac 100644 --- a/docs/cross-service/github-integration.md +++ b/docs/cross-service/github-integration.md @@ -5,356 +5,108 @@ description: Learn about Azure DevOps integration with GitHub. ms.subservice: azure-devops-cross-service ms.custom: cross-service ms.topic: overview +ai-usage: ai-assisted ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' -ms.date: 08/31/2021 +monikerRange: "<=azure-devops" +ms.date: 03/05/2025 --- -# Azure DevOps and GitHub integration overview +# About GitHub integration [!INCLUDE [version-gt-eq-2019](../includes/version-gt-eq-2019.md)] -Azure Boards and Azure Pipelines provide several integration points with GitHub and GitHub Enterprise. - +Azure Boards and Azure Pipelines offer multiple integration points with GitHub and GitHub Enterprise. These integrations enable seamless collaboration between development and project management, enhancing traceability, workflow efficiency, and overall productivity. By connecting your GitHub repositories with Azure DevOps, you can streamline your development processes and gain better insights into your projects. -## Sign-in with GitHub credentials +## Authenticate and collaborate with GitHub -Azure DevOps simplifies deployment from your repository with seamless access to the Azure portal and Azure DevOps using your GitHub account credentials. +::: moniker range="= azure-devops" + +| **Feature** | **Description** | +|-------------|-----------------| +| **Sign into Azure DevOps using your GitHub credentials** | Allows users to sign in using their GitHub credentials and link their GitHub account to a Microsoft account. For more information, see [Signing into Azure DevOps using your GitHub credentials (Release Notes)](/azure/devops/release-notes/2019/build-may#signing-into-azure-devops-using-your-github-credentials). | +| **Invite GitHub collaborators into Azure DevOps** | Provides support for inviting GitHub account users to collaborate within an Azure DevOps project. For more information, see [Invite GitHub collaborators into Azure DevOps (Release Notes)](/azure/devops/release-notes/2019/sprint-155-update#invite-github-collaborators-into-azure-devops). | +| **Connect to a GitHub repository from Visual Studio** | Provides a user interface to support cloning GitHub repositories, pushing and pulling commits, and more. For more information, see [Side-by-side comparison of Git and Team Explorer](/visualstudio/version-control/git-team-explorer-feature-comparison?view=vs-2019&&preserve-view=true). | - ---- -:::row::: - :::column span="1"::: - **Feature** - :::column-end::: - :::column span="2"::: - **Description** - :::column-end::: -:::row-end::: ---- -::: moniker range=">= azure-devops-2020" -:::row::: - :::column span="1"::: - Invite GitHub collaborators into Azure DevOps - :::column-end::: - :::column span="2"::: - Provides support for inviting GitHub account users to collaborate within an Azure DevOps project. For details, see [Invite GitHub collaborators into Azure DevOps (Release Notes)](/azure/devops/release-notes/2019/sprint-155-update#invite-github-collaborators-into-azure-devops). - :::column-end::: -:::row-end::: ---- ::: moniker-end -::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - Sign into Azure DevOps using your GitHub credentials - :::column-end::: - :::column span="2"::: - Allows users to sign in using their GitHub credentials and link their GitHub account to a Microsoft account. For details, see [Signing into Azure DevOps using your GitHub credentials (Release Notes)](/azure/devops/release-notes/2019/build-may#signing-into-azure-devops-using-your-github-credentials). - :::column-end::: -:::row-end::: ---- + +::: moniker range=">= azure-devops-2020 < azure-devops" + +| **Feature** | **Description** | +|-------------|-----------------| +| **Invite GitHub collaborators into Azure DevOps** | Provides support for inviting GitHub account users to collaborate within an Azure DevOps project. For more information, see [Invite GitHub collaborators into Azure DevOps (Release Notes)](/azure/devops/release-notes/2019/sprint-155-update#invite-github-collaborators-into-azure-devops). | +| **Connect to a GitHub repository from Visual Studio** | Provides a user interface to support cloning GitHub repositories, pushing and pulling commits, and more. For more information, see [Side-by-side comparison of Git and Team Explorer](/visualstudio/version-control/git-team-explorer-feature-comparison?view=vs-2019&&preserve-view=true). | + ::: moniker-end -:::row::: - :::column span="1"::: - Connect to a GitHub repository from Visual Studio - :::column-end::: - :::column span="2"::: - Provides a user interface to support cloning GitHub repositories, pushing and pulling commits, and more. For details, see [Side-by-side comparison of Git and Team Explorer](/visualstudio/version-control/git-team-explorer-feature-comparison?view=vs-2019&&preserve-view=true). - :::column-end::: -:::row-end::: - -## Azure Boards and GitHub integration +## Integrate Azure Boards with GitHub -By connecting Azure Boards with GitHub repositories, you enable linking between GitHub commits, pull requests, and issues to work items. You can use GitHub for software development while using Azure Boards to plan and track your work. To get started, see [Azure Boards-GitHub integration](../boards/github/index.md). - ---- -:::row::: - :::column span="1"::: - **Feature** - :::column-end::: - :::column span="2"::: - **Description** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Connect Azure Boards project to GitHub repos - :::column-end::: - :::column span="2"::: - Supports establishing connection of one or more GitHub repositories to an Azure Boards project. For details, see [Azure Boards-GitHub integration](../boards/github/index.md). - :::column-end::: -:::row-end::: ---- -::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - Connect Azure Boards project to repositories hosted in a GitHub Enterprise Server instance - :::column-end::: - :::column span="2"::: - Supports establishing connection of one or more GitHub repositories hosted in a GitHub Enterprise Server. For details, see [Azure Boards-GitHub integration](../boards/github/index.md). - :::column-end::: -:::row-end::: ---- -::: moniker-end -:::row::: - :::column span="1"::: - Link work items to GitHub commits, pull requests, and issues. Quickly view and open linked objects from the Kanban board. - :::column-end::: - :::column span="2"::: - Supports linking GitHub commits, pull requests, and issues to Azure Boards work items. Mentioned work items in GitHub comments are configured as hyperlinks to support quick navigation to Azure Boards work items. - :::image type="content" source="media/overview/development-control-plus-github.png" alt-text="Screenshot of Development control for GitHub."::: - For details, see [Link GitHub commits, pull requests, and issues to work items](../boards/github/link-to-from-github.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Add status badges of Azure Boards to a GitHub repository README file. - :::column-end::: - :::column span="2"::: - Supports adding Markdown syntax to a GitHub repo README.md file to display the status of a Kanban board. For details, see [Configure status badges to add to GitHub README files](../boards/github/configure-status-badges.md). - :::image type="content" source="../boards/github/media/badges/custom-columns.png" alt-text="Screenshot of GitHub status badge."::: - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Work items linked to GitHub commit in Release Summary - :::column-end::: - :::column span="2"::: - Review list of all work items linked to GitHub commits in the Release summary page. This helps teams track and retrieve more information about the commits that have been deployed to an environment. - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Sync GitHub Issues to Azure Boards Work Items - :::column-end::: - :::column span="2"::: - Using the [GitHub Action, GitHub Issues to Azure DevOps](https://github.com/marketplace/actions/github-issues-to-azure-devops) you can sync your GitHub Issues to your Azure Boards. For details, see [Sync GitHub Issues to Azure DevOps Work Items (Release Notes)](/azure/devops/release-notes/2020/sprint-167-update#sync-github-issues-to-azure-devops-work-items). - :::column-end::: -:::row-end::: ---- - +By integrating Azure Boards with GitHub repositories, you can link GitHub commits, pull requests, branches, and issues to work items. This integration allows you to use GitHub for software development while using Azure Boards to plan and track your work. To get started, see [Azure Boards-GitHub integration](../boards/github/index.md). -## Azure Pipelines and GitHub integration +### Benefits of integration -You can use Azure Pipelines to automatically build, test, package, release, and deploy your GitHub repository code. To get started, see [Build GitHub repositories](../pipelines/repos/github.md). +- **Enhanced traceability**: Link work items to GitHub commits, pull requests, branches, and issues for better traceability. +- **Streamlined workflow**: Use GitHub for development and Azure Boards for planning and tracking, ensuring a seamless workflow. +- **Improved collaboration**: Collaborate more effectively by connecting development activities in GitHub with project management in Azure Boards. -You can map your GitHub repositories to one or more projects in Azure DevOps. +### Features of Azure Boards and GitHub integration -:::image type="content" source="media/overview/github-azure-devops-integration.png" alt-text="Conceptual image of GitHub and Azure Pipelines integration."::: +| **Feature** | **Description** | +|-------------|-----------------| +| **Link work items** | Easily link work items to GitHub commits, pull requests, branches, and issues. | +| **View linked objects** | Quickly view and open linked objects from the board. | +| **Add status badges** | Add status badges of Azure Boards to a GitHub repository README file. | +| **View release summary** | Review work items linked to GitHub commits in the Release summary page. | +| **Sync GitHub issues** | Sync GitHub Issues to Azure Boards Work Items using the [GitHub Action](https://github.com/marketplace/actions/github-issues-to-azure-devops). | - - -:::row::: - :::column span="1"::: - **Feature** - :::column-end::: - :::column span="2"::: - **Description** - :::column-end::: -:::row-end::: ---- -::: moniker range=">= azure-devops-2019 < azure-devops" -:::row::: - :::column span="1"::: - GitHub repository and pull request builds - :::column-end::: - :::column span="2"::: - Automatically build pull requests from repository forks to ensure changes successfully build and tests pass before they are merged. - For details, see [Build GitHub repositories](../pipelines/repos/github.md). - :::column-end::: -:::row-end::: ---- -::: moniker-end -::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - GitHub repository and pull request builds - :::column-end::: - :::column span="2"::: - - Automatically build your GitHub pull requests. After the build is done, status is reported back with a comment in your GitHub pull request. - - Manually run a pipeline or test suite triggered by a GitHub pull request comment. - - Configure draft PR validation for GitHub repository. Supports adding `drafts` to the `pr` trigger YAML syntax for GitHub draft pull requests. You can choose if you want your draft PRs to queue a build. The default option is true (a build will be queued) like it currently is for GitHub PRs. - - Rebuild GitHub pull request builds upon failure. Provides support for queueing a failed build. - - Configure draft PR validation for GitHub repositories - - Automatically build pull requests from repository forks to ensure changes successfully build and tests pass before they are merged. - For details, see [Build GitHub repositories](../pipelines/repos/github.md). - :::column-end::: -:::row-end::: ---- -::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" -:::row::: - :::column span="1"::: - GitHub Enterprise builds - :::column-end::: - :::column span="2"::: - Supports continuous integration (CI) builds for GitHub Enterprise repositories. For details, see [Build GitHub repositories, CI triggers](../pipelines/repos/github.md#ci-triggers). - :::column-end::: -:::row-end::: ---- -::: moniker-end +## Integrate Azure Pipelines with GitHub -::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - GitHub Enterprise builds - :::column-end::: - :::column span="2"::: - - Supports continuous integration (CI) builds for GitHub Enterprise repositories. - - Create a pipeline to build code contained within a GitHub Enterprise repository using the the build pipeline wizard. - For details, see [Build GitHub repositories, CI triggers](../pipelines/repos/github.md#ci-triggers). - :::column-end::: -:::row-end::: ---- -::: moniker-end -::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - GitHub service connections - :::column-end::: - :::column span="2"::: - The pipeline wizard automatically creates and reuses a service connection for the repository you choose. If you wish to manually choose a connection other than the one that is automatically selected, follow the **Choose connection** hyperlink. For details, see [Build GitHub repositories](../pipelines/repos/github.md). - :::column-end::: -:::row-end::: ---- -::: moniker-end -::: moniker range=">= azure-devops-2020" -:::row::: - :::column span="1"::: - GitHub-specific tasks and utilities - :::column-end::: - :::column span="2"::: - Supported: - - [Download GitHub Release task](/azure/devops/pipelines/tasks/reference/download-github-release-v0) - - [GitHub Release task](/azure/devops/pipelines/tasks/reference/github-release-v1) - - [Open source Azure Pipeline tasks](https://github.com/microsoft/azure-pipelines-tasks/tree/master/Tasks) - :::column-end::: -:::row-end::: ---- -::: moniker-end -::: moniker range="azure-devops-2019" -:::row::: - :::column span="1"::: - Manage GitHub releases - :::column-end::: - :::column span="2"::: - - Inline GitHub connection as a release artifact source. - - Automate GitHub releases using the **GitHub Release** task. - For details, see: - - [CI triggers](../pipelines/repos/github.md#ci-triggers) - - [Download GitHub Release task](/azure/devops/pipelines/tasks/reference/download-github-release-v0) - :::column-end::: -:::row-end::: ---- -::: moniker-end -::: moniker range=">= azure-devops-2020" -:::row::: - :::column span="1"::: - Manage GitHub releases - :::column-end::: - :::column span="2"::: - - Inline GitHub connection as a release artifact source. - - Automate GitHub releases using the **GitHub Release** task. - - Link your GitHub releases as an artifact source in release pipelines. This function lets you consume the GitHub release as part of your deployments. - For details, see: - - [CI triggers](../pipelines/repos/github.md#ci-triggers) - - [Download GitHub Release task](/azure/devops/pipelines/tasks/reference/download-github-release-v0) - - [GitHub Release task](/azure/devops/pipelines/tasks/reference/github-release-v1) - :::column-end::: -:::row-end::: ---- -::: moniker-end -::: moniker range=">= azure-devops-2019" -:::row::: - :::column span="1"::: - Filter GitHub branches for GitHub, GitHub Enterprise, or external Git artifacts - :::column-end::: - :::column span="2"::: - When releasing from GitHub, GitHub Enterprise, or external Git repositories, you can configure the specific branches to release. For example, you may want to deploy only builds coming from a specific branch to production. For details, see [Release triggers, Continuous deployment triggers](../pipelines/release/triggers.md). - :::column-end::: -:::row-end::: ---- -::: moniker-end -::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - GitHub Actions to trigger a pipeline run - :::column-end::: - :::column span="2"::: - automate your software development workflows from within GitHub. You can deploy workflows in the same place where you store code and collaborate on pull requests and issues. For details, see [Quickstart: Trigger an Azure Pipelines run from GitHub Actions](../pipelines/ecosystems/github-actions.md). - :::column-end::: -:::row-end::: ---- -::: moniker-end +You can use Azure Pipelines to automatically build, test, package, release, and deploy your GitHub repository code. To get started, see [Build GitHub repositories](../pipelines/repos/github.md). + +Additionally, you can map your GitHub repositories to one or more projects in Azure DevOps, enabling seamless integration and management across your development lifecycle. + +### Benefits of integration + +- **Automated workflows**: Automatically build, test, package, release, and deploy your GitHub repository code using Azure Pipelines. +- **Continuous integration and continuous deployment (CI/CD)**: Implement CI/CD practices to ensure that your code changes are automatically tested and deployed. +- **Seamless integration**: Map your GitHub repositories to one or more projects in Azure DevOps for seamless integration and management across your development lifecycle. +- **Enhanced collaboration**: Collaborate more effectively by linking work items to GitHub commits, pull requests, branches, and issues. +- **Improved traceability**: Achieve better traceability by reviewing work items linked to GitHub commits in the release summary page. +- **Status badges**: Add status badges of Azure Boards to a GitHub repository README file and display the build status. +- **Issue synchronization**: Sync GitHub Issues to Azure Boards work items using the GitHub Action for better issue tracking and management. + +### Features of Azure Pipelines and GitHub integration + +::: moniker range="= azure-devops" + +| **Feature** | **Description** | +|-------------|-----------------| +| **Create GitHub repository and pull request builds** | - Automatically build your GitHub pull requests. After the build is done, status is reported back with a comment in your GitHub pull request.
- Manually run a pipeline or test suite triggered by a GitHub pull request comment.
- Configure draft PR validation for GitHub repository. Supports adding `drafts` to the `pr` trigger YAML syntax for GitHub draft pull requests. You can choose if you want your draft PRs to queue a build. The default option is true (a build is queued) like it currently is for GitHub PRs.
- Rebuild GitHub pull request builds upon failure. Provides support for queueing a failed build.
- Configure draft PR validation for GitHub repositories.
- Automatically build pull requests from repository forks to ensure changes successfully build and tests pass before they get merged. For more information, see [Build GitHub repositories](../pipelines/repos/github.md). | +| **Create GitHub Enterprise builds** | - Supports continuous integration (CI) builds for GitHub Enterprise repositories.
- Create a pipeline to build code contained within a GitHub Enterprise repository using the build pipeline wizard. For more information, see [Build GitHub repositories, CI triggers](../pipelines/repos/github.md#ci-triggers). | +| **Use GitHub service connections** | The pipeline wizard automatically creates and reuses a service connection for the repository you choose. If you wish to manually choose a connection other than the one that is automatically selected, follow the **Choose connection** hyperlink. For more information, see [Build GitHub repositories](../pipelines/repos/github.md). | +| **Manage GitHub releases** | - Inline GitHub connection as a release artifact source.
- Automate GitHub releases using the **GitHub Release** task.
- Link your GitHub releases as an artifact source in release pipelines. This function lets you consume the GitHub release as part of your deployments. For more information, see [CI triggers](../pipelines/repos/github.md#ci-triggers), [Download GitHub Release task](/azure/devops/pipelines/tasks/reference/download-github-release-v0), and [GitHub Release task](/azure/devops/pipelines/tasks/reference/github-release-v1). | +| **Use build tags to trace GitHub sources or trigger GitHub releases** | - Use build tags to trace GitHub sources to builds. While choosing a GitHub repository in a build definition, you can select the types of builds you want to tag, along with the tag format.
- Specify a tag pattern to determine when to trigger a GitHub release. By specifying a tag regular expression, you can control when a GitHub release is created based on the triggering commit. For more information, see [Build GitHub repositories, Label sources](../pipelines/repos/github.md#label-sources). | +| **Support GitHub packages in YAML pipelines** | In your YAML pipeline, specify a package type (NuGet or npm) that you want to consume from GitHub. For more information, see [Resources: packages](../pipelines/process/resources.md). | +| **Get status checks, tracking, and traceability** | - **GitHub Checks**:
- Display status for each pipeline job: Run a pipeline or test suite to validate a GitHub pull request from the comments section of the GitHub pull request.
- Send detailed information about the pipeline status, test, code coverage, and errors. Status is posted to GitHub Checks for each job in the pipeline.
- **Status badges**: Add Markdown syntax to a GitHub repo README.md file and display the pipeline status.
- GitHub artifacts: Show associated commits deployed in a release. To enhance traceability, you can see all the commits that were deployed to an environment for GitHub repositories, as a part of a specific release.
- Track GitHub commits and associated issues in releases. List commits made in GitHub repos and the associated GitHub issues that are being deployed with a release. For more information, see [Track GitHub commits and associated issues in releases (Release Notes)](/azure/devops/release-notes/2018/sep-10-azure-devops-launch#new-build-status-badge-url). For more information, see:
- [Create your first pipeline, Add a status badge to your repository](../pipelines/create-first-pipeline.md#add-a-status-badge-to-your-repository)
- [GitHub Checks API](https://docs.github.com/en/rest/reference/checks)
- [Display status for each pipeline job in GitHub Checks (Release Notes)](/azure/devops/release-notes/2019/sprint-146-update#automatic-github-service-connections-in-pipelines) | -::: moniker range=">= azure-devops-2019 < azure-devops-2020" -:::row::: - :::column span="1"::: - Use build tags to trace GitHub sources - :::column-end::: - :::column span="2"::: - Use build tags to trace GitHub sources to builds. While choosing a GitHub repository in a build definition, you can select the types of builds you want to tag, along with the tag format. - For details, see [Build GitHub repositories, Label sources](../pipelines/repos/github.md#label-sources). - :::column-end::: -:::row-end::: ---- ::: moniker-end -::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - Use build tags to trace GitHub sources or trigger GitHub releases - :::column-end::: - :::column span="2"::: - Use build tags to trace GitHub sources to builds. While choosing a GitHub repository in a build definition, you can select the types of builds you want to tag, along with the tag format. - - Use build tags to trace GitHub sources to builds. While choosing a GitHub repository in a build definition, you can select the types of builds you want to tag, along with the tag format. - - Specify a tag pattern to determine when to trigger a GitHub release. By specifying a tag regular expression, you can control when a GitHub release is created based on the triggering commit. - For details, see [Build GitHub repositories, Label sources](../pipelines/repos/github.md#label-sources). - :::column-end::: -:::row-end::: ---- -::: moniker-end -::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - GitHub packages support in YAML pipelines - :::column-end::: - :::column span="2"::: - In your YAML pipeline, specify a package type (NuGet or npm) that you want to consume from GitHub. For details, see [Resources: packages](../pipelines/process/resources.md). - :::column-end::: -:::row-end::: ---- +::: moniker range="< azure-devops" + +| **Feature** | **Description** | +|-------------|-----------------| +| **Create GitHub repository and pull request builds** | Automatically build pull requests from repository forks to ensure changes successfully build and tests pass before they get merged. For more information, see [Build GitHub repositories](../pipelines/repos/github.md). | +| **Create GitHub Enterprise builds** | Supports continuous integration (CI) builds for GitHub Enterprise repositories. For more information, see [Build GitHub repositories, CI triggers](../pipelines/repos/github.md#ci-triggers). | +| **Use GitHub-specific tasks and utilities** | Supported tasks include [Download GitHub Release task](/azure/devops/pipelines/tasks/reference/download-github-release-v0), [GitHub Release task](/azure/devops/pipelines/tasks/reference/github-release-v1), and [Open source Azure Pipelines tasks](https://github.com/microsoft/azure-pipelines-tasks/tree/master/Tasks). | +| **Manage GitHub releases** | Inline GitHub connection as a release artifact source. Automate GitHub releases using the **GitHub Release** task. For more information, see [CI triggers](../pipelines/repos/github.md#ci-triggers), [Download GitHub Release task](/azure/devops/pipelines/tasks/reference/download-github-release-v0), and [GitHub Release task](/azure/devops/pipelines/tasks/reference/github-release-v1). | +| **Filter GitHub branches for GitHub, GitHub Enterprise, or external Git artifacts** | Configure the specific branches to release when you release from GitHub, GitHub Enterprise, or external Git repositories. For more information, see [Release triggers, Continuous deployment triggers](../pipelines/release/triggers.md). | +| **Use build tags to trace GitHub sources** | Use build tags to trace GitHub sources to builds. While choosing a GitHub repository in a build definition, you can select the types of builds you want to tag, along with the tag format. For more information, see [Build GitHub repositories, Label sources](../pipelines/repos/github.md#label-sources). | + ::: moniker-end -::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - Status checks, tracking, and traceability - :::column-end::: - :::column span="2"::: - - **GitHub Checks**: Display status for each pipeline job: Run a pipeline or test suite to validate a GitHub pull request from the comments section of the GitHub pull request. - - **GitHub Checks** allows for sending detailed information about the pipeline status, test, code coverage, and errors. Status is posted to GitHub Checks for each job in the pipeline. - - **Status badges**: Supports adding Markdown syntax to a GitHub repo README.md file to display the pipeline status. - - GitHub artifacts show associated commits deployed in a release. To enhance traceability, you can see all the commits that were deployed to an environment for GitHub repositories, as a part of a specific release. - - Track GitHub commits and associated issues in releases. Lists commits made in GitHub repos and the associated GitHub issues that are being deployed with a release. For details, see [Track GitHub commits and associated issues in releases (Release Notes)](/azure/devops/release-notes/2018/sep-10-azure-devops-launch#new-build-status-badge-url). - - For details, see: - - [Create your first pipeline, Add a status badge to your repository](../pipelines/create-first-pipeline.md#add-a-status-badge-to-your-repository). - - [GitHub Checks API](https://docs.github.com/en/rest/reference/checks) - - [Display status for each pipeline job in GitHub Checks (Release Notes)](/azure/devops/release-notes/2019/sprint-146-update#automatic-github-service-connections-in-pipelines). - :::column-end::: -:::row-end::: ---- -::: moniker-end ## Related articles - [Azure Boards-GitHub integration](../boards/github/index.md) - [Build GitHub repositories](../pipelines/repos/github.md) -- [Git experience in Visual Studio](/visualstudio/version-control/git-with-visual-studio) \ No newline at end of file +- [Git experience in Visual Studio](/visualstudio/version-control/git-with-visual-studio) diff --git a/docs/cross-service/index.yml b/docs/cross-service/index.yml index 70623bb690c..a876885d0b3 100644 --- a/docs/cross-service/index.yml +++ b/docs/cross-service/index.yml @@ -28,36 +28,16 @@ landingContent: url: github-integration.md - text: Deploy to Azure url: ../pipelines/overview-azure.md?toc=/azure/devops/cross-service/toc.json - - title: Work across projects - linkLists: - - linkListType: get-started - links: - - text: View work assigned to you - url: ../project/navigation/work-across-projects.md?toc=/azure/devops/cross-service/toc.json - - linkListType: reference - links: - - text: Work across projects FAQs - url: ../project/work-across-projects-faqs.yml?toc=/azure/devops/cross-service/toc.json - - title: Track work, code, builds, and releases + - title: Integrate with Microsoft Teams linkLists: - - linkListType: overview - links: - - text: End-to-end traceability - url: end-to-end-traceability.md - - text: Configure Git repositories to integrate with work tracking - url: ../repos/git/configure-repos-work-tracking.md?toc=/azure/devops/cross-service/toc.json - - linkListType: tutorial - links: - - text: Drive Git development - url: ../boards/backlogs/connect-work-items-to-git-dev-ops.md?toc=/azure/devops/cross-service/toc.json - linkListType: how-to-guide links: - - text: Link work items to builds and deployments - url: ../boards/work-items/work-item-deployments-control.md?toc=/azure/devops/cross-service/toc.json - - text: Link objects to work items - url: ../organizations/notifications/add-links-to-work-items.md?toc=/azure/devops/cross-service/toc.json - - text: Configure pipelines to support work tracking - url: ../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/cross-service/toc.json + - text: Azure Boards with Microsoft Teams + url: ../boards/integrations/boards-teams.md?toc=/azure/devops/cross-service/toc.json + - text: Azure Repos with Microsoft Teams + url: ../repos/integrations/repos-teams.md?toc=/azure/devops/cross-service/toc.json + - text: Azure Pipelines with Microsoft Teams + url: ../pipelines/integrations/microsoft-teams.md?toc=/azure/devops/cross-service/toc.json - title: Integrate with GitHub linkLists: - linkListType: quickstart @@ -80,16 +60,16 @@ landingContent: url: ../service-hooks/services/webhooks.md?toc=/azure/devops/cross-service/toc.json - text: Create a service hook with Microsoft Teams url: ../service-hooks/services/teams.md?toc=/azure/devops/cross-service/toc.json - - title: Integrate with Microsoft Teams + - title: Work across projects linkLists: - - linkListType: how-to-guide + - linkListType: get-started links: - - text: Azure Boards with Microsoft Teams - url: ../boards/integrations/boards-teams.md?toc=/azure/devops/cross-service/toc.json - - text: Azure Repos with Microsoft Teams - url: ../repos/integrations/repos-teams.md?toc=/azure/devops/cross-service/toc.json - - text: Azure Pipelines with Microsoft Teams - url: ../pipelines/integrations/microsoft-teams.md?toc=/azure/devops/cross-service/toc.json + - text: View work assigned to you + url: ../project/navigation/work-across-projects.md?toc=/azure/devops/cross-service/toc.json + - linkListType: reference + links: + - text: Work across projects FAQs + url: ../project/work-across-projects-faqs.yml?toc=/azure/devops/cross-service/toc.json - title: Integrate with Slack linkLists: - linkListType: how-to-guide @@ -100,6 +80,24 @@ landingContent: url: ../repos/integrations/repos-slack.md?toc=/azure/devops/cross-service/toc.json - text: Azure Pipelines with Slack url: ../pipelines/integrations/slack.md?toc=/azure/devops/cross-service/toc.json + - title: Track work, code, builds, and releases + linkLists: + - linkListType: overview + links: + - text: End-to-end traceability + url: end-to-end-traceability.md + - linkListType: tutorial + links: + - text: Drive Git development + url: ../boards/backlogs/connect-work-items-to-git-dev-ops.md?toc=/azure/devops/cross-service/toc.json + - linkListType: how-to-guide + links: + - text: Link work items to other objects + url: ../boards/backlogs/add-link.md?toc=/azure/devops/cross-service/toc.json + - text: Link objects to work items + url: ../organizations/notifications/add-links-to-work-items.md?toc=/azure/devops/cross-service/toc.json + - text: Configure pipelines to support work tracking + url: ../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/cross-service/toc.json - title: Create and manage a public project linkLists: - linkListType: overview diff --git a/docs/cross-service/manage-change.md b/docs/cross-service/manage-change.md index 936ecd0b4d4..566be47498e 100644 --- a/docs/cross-service/manage-change.md +++ b/docs/cross-service/manage-change.md @@ -1,254 +1,90 @@ --- title: Manage change, Agile methods titleSuffix: Azure DevOps -description: Learn about the tools and features available to manage change when using Agile methods +description: Learn about the tools and features available to manage change when you use Agile methods in Azure DevOps. ms.subservice: azure-devops-cross-service ms.topic: conceptual +ai-usage: ai-assisted ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 03/30/2021 +ms.date: 03/05/2025 --- - -# Manage change +# Manage change [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Managing change is an aspect of managing your project plan, your requirements, and your sprints. In keeping with the Agile manifesto that encourages "*Responding to change over following a plan*, how should you manage change? +Azure DevOps provides various tools and features to help you manage change effectively and efficiently, which is a crucial part of any project. This article provides an overview for managing change and maps Agile change management tasks to the tools that Azure DevOps supports. -> [!NOTE] -> *Agile change management is the adaptive and iterative planning and execution of change management practices that encourages flexibility and speed. If organizations want to make effective change, they need to recognize and deal with the principles of how change happens within agile organizations and have the tools to make the work happen. —[Managing Change in an Agile World](https://www.agilealliance.org/resources/books/managing-change-in-an-agile-world/)* +## Identify the need for change -You'll want to keep your change management process lightweight. You'll want to gain insight into where change is occurring in your project, and how the change impacts your team in their ability to deliver. And, when managing change, you'll want to consider your business requirements to meet the following scenarios. +Several sources can contribute to necessary changes in your software development projects: -> [!div class="checklist"] -> - Define and track status of change -> - Analyze and prioritize change requirements -> - Monitor and report on changes -> - Keep stakeholders and teams informed of changes. +- Changing business and customer needs +- New priorities +- Evolving feature requirements due to new information or discovered dependencies +- Changes in resources and organizations +- Delays in development or testing +- Issues arising after deployment and during ongoing operations -This article provides guidance for managing change. It also maps Agile change management tasks by project managers to the tools Azure DevOps supports. More detailed information is provided under [Related articles](#related-articles). +## Minimize unnecessary change -## Where does change arise? How can you minimize change? +To minimize unnecessary change, ensure the following: -Several sources can contribute to changes that you need to manage in your software development projects. +- Clear requirements and acceptance criteria +- Clear project scope and priorities +- Agreed-upon change management process +- Accurate estimates on planned work +- Negotiated requests for new work +- Effective communication within the team when changes occur +- Input from stakeholders and customers on change requests +- Team members feel comfortable raising issues as they occur -- Business needs and customer needs change -- New priorities arise -- Feature requirements change as new information occurs or dependencies are discovered -- Resources and organizations change -- Development or testing takes longer than expected -- Issues arise after deployment and ongoing operations. +## Implement Agile best practices for change management -While some changes are unavoidable, other changes can be avoided or their effect minimized. Many changes arise when a team is new to Agile methods and haven't yet adopted an Agile culture. +Agile is a project management approach that works by breaking projects into short, iterative cycles called “sprints”. At its core, Agile is based on the assumption that circumstances change as a project develops. That’s why, in an Agile project, the planning, design, development, and testing cycles are never done. They continue to change as the project takes form. -To minimize avoidable changes, minimize the occurrence of the following. -- Unclear requirements and acceptance criteria -- Unclear project scope and priorities -- Unclear change management process agreed to by the team -- Poor estimates on planned work -- Not negotiating requests for new work -- Allowing a team member to focus on developing what they believe to be best rather than what is required -- Poor communication within the team when changes occur -- Lack of stakeholders and customer input around change requests -- Team members are hesitant to raise issues as they occur. - +To mitigate problems that arise from change, Agile project managers adopt many best practices. These practices are divided into the following categories: Control your process, Manage change at the product plan level, Manage your sprints, and Consider change criteria. -## Agile practices for managing change +| **Category** | **Best practices** | +|--------------|--------------------| +| **Control your process** | - Meet both team and business objectives
- Minimize the number of approvals required to address changes
- Assist your teams in their continual improvement processes
**Tip:** Continuous improvement is a method to make sure that your processes, methods, and practices are as efficient and effective as possible. | +| **Manage change at the product plan level** | - Refine and prioritize the product plan and product backlog continuously
- Ensure customer needs are understood and properly scoped and communicated
- Analyze the product backlog for dependencies and risks
- Develop contingency plans
- Analyze and triage change requests
- Determine the scope effect of change requests on current and planned work
- Assess the risks of accepting or rejecting the change
- Use a light change control form as needed | +| **Manage your sprints** | - Ensure the acceptance criteria and requirements are well understood at the start of a sprint
- Minimize accepting changes after the start of the sprint, while still adhering to Agile principles
- Keep all stakeholders and teams involved as changes occur
- Control scope changes and minimize scope creep
- Protect your team against making changes to a project that are outside of the original agreed-upon scope
**Tip:** *What is Scope creep? Scope creep occurs when the deliverables or features of a project expand from what was originally defined, without a commensurate change in additional time or budget.* | +| **Consider change criteria** | Ask the following questions when you consider making a change:
- Does it serve the sprint goal?
- Is there a clear business value for the change?
- Upon release, do you plan to use the result of the scope change?
- What is the urgency for the change request?
- If new scope is added to the sprint backlog, is there something that can be removed? | -> [!NOTE] -> *Agile is a project management approach that works by breaking projects into short, iterative cycles called “sprints”. At its core, Agile is based on the assumption that circumstances change as a project develops. That’s why, in an Agile project, the planning, design, development, and testing cycles are never done. They continue to change as the project takes form. —[IMA](https://www.imaworldwide.com/blog/5-implications-for-change-management-in-an-agile-world)* +## Track change - -To mitigate problems that arise from change, Agile project managers adopt a number of best practices. These practices are divided into the following three groups: +Choose from several methods to track change, ranging from lightweight to robust: -### Process practices +- Track changes to requirements within the requirement work item through discussions, changes to acceptance criteria, or attachments. +- Add a *change* tag to work items to support tracking changes to the scope of work. +- Set up notifications to automatically communicate change within your team or organization. +- Add a bug that tracks a change in scope or another work. +- Add a change request work item type to formally track and log change requests to the product backlog. -- Support a change management process -- Meet both team and business objectives -- Minimize the number of approvals required to address changes -- Assist teams in their continual improvement processes. - -> [!NOTE] -> *Continuous improvement is a method to make sure that your processes, methods, and practices are as efficient and effective as possible. —[Agile and a continuous improvement mindset](https://scrumtraininginstitute.com/agile-scrum-training/agile-team-health-check/#:~:text=At%20the%20core%20of%20Agile%20continuous%20improvement%20is,your%20organization%20can%20develop%20a%20continuous%20improvement%20mindset)* +With any of these methods, you can generate a query to list work items involved in change, and then review and triage the change with the team. Choose a tracking method that aligns with how you and your team monitor and report the scope of change. -### Manage change at the product plan level +| **Method** | **Details** | +|-------------|-------------| +| **Use the change request form** | Define a change request work item type, like the one in the following image for the Capability Maturity Model Integration (CMMI) process.
![Screenshot of a change request work item form.](media/manage-change/change-request-form.png)
You can adopt this form or customize your own. You can also have change requests appear on your backlog along with other user stories or requirements. | +| **Define acceptance criteria** | Clearly describe what "done" means with acceptance criteria to verify whether a requirement or bug fix is fully implemented. Capture these criteria within the work item. Clear acceptance criteria help teams estimate work and develop tests to ensure the criteria are met.
Specify acceptance criteria for individual requirements and sprints to ensure all team members understand the scope of work. | -- Continuously refine and prioritize the product plan and product backlog -- Ensure customer needs are understood and properly scoped and communicated -- Analyze the product backlog for dependencies and risks -- Develop contingency plans -- Analyze and triage change requests -- Determine the scope impact of change requests on current and planned work -- Assess the risks of accepting or rejecting the change -- Use a light change control form as needed +## Monitor and report on changes -### Sprint management practices +Teams can monitor changes through work item queries, team velocity charts, and sprint burndown and release burndown charts. -- Ensure the acceptance criteria and requirements are well understood at the start of a sprint -- Work to minimize accepting changes after the start of the sprint, while still adhering to Agile principles -- Keep all stakeholders and teams involved as changes occur -- Control scope changes and minimize scope creep -- Protect your team against "gold plating", a practice of making changes to a project that are outside of the original agreed-upon scope. +| **Method** | **Details** | +|-------------|-------------| +| **Work item queries** | With [queries](../boards/queries/using-queries.md), you can find and triage a list of change management requests or work items tagged with a change management tag. | +| **Team velocity and unplanned work** | The team [velocity chart](../report/dashboards/team-velocity.md) provides several pieces of information. This chart shows how much work was planned and how much was completed. Visually, you can determine how often work was added to a sprint after the sprint began. | +| **Sprint burndown and scope creep** | Another chart to review for scope creep is the [sprint burndown chart](../report/dashboards/burndown-guidance.md). With Azure Boards, you can review the sprint burndown charts for each sprint and each team to determine the degree of scope creep introduced into each sprint. | -> [!NOTE] -> *What is Scope creep? Scope creep occurs when the deliverables or features of a project expand from what was originally defined, without a commensurate change in additional time or budget.* +## Get notified of changes -### Questions to ask before accepting a change -- Does it serve the sprint goal? -- Is there a clear business value for the change? -- Upon release, will the customer use the result of the scope change? -- What is the urgency for the change request? -- If new scope is added to the sprint backlog, is there something that can be removed? +Azure DevOps provides a robust alert system, where project members can [set alerts for themselves, a team, or a project](../organizations/notifications/about-notifications.md). As changes occur to work items, code reviews, source control files, and builds, you can receive email notifications. -## Options for tracking change - -You have several choices for tracking change. From most lightweight to most robust, you can use one or more of the following methods: - -- Track changes to requirements within the requirement work item through discussions, changes to acceptance criteria, or attachments -- Add a *change* tag to work items to support tracking changes to the scope of work -- Set up notifications to automatically communicate change within your team or organization -- Add a bug that tracks a change in scope or another work -- Add a change request work item type to formally track and log change requests to the product backlog. - -With any of these methods, you can generate a query to list work items involve in change. You can then review and triage the change with the team. How you choose to track change should align with how you and your team choose to monitor and report the scope of change. - -### Change request form - -To formally track change, you can define a change request work item type, similar to the one shown in the following image for the Capability Maturity Model Integration (CMMI) process. - -> [!div class="mx-imgBorder"] -> ![Change request work item form.](media/manage-change/change-request-form.png) - -This form provides rich-text fields to capture the effect of the change to the following areas: -- Architecture -- User experience -- Test -- Design and development -- Technical publications - -You can adopt this form or customize your own. You can also customize your backlog to have change requests appear on your backlog along with other user stories or requirements. - -### Ensure acceptance criteria is well-defined - -Acceptance criteria defines what "done" means. It clearly describes the conditions that the team should use to verify whether a requirement or bug fix has been fully implemented. Typically, you want to capture these criteria within the work item. Clear acceptance criteria helps teams estimate work and develop tests to ensure the criteria has been met. - -You can specify acceptance criteria for individual requirements and for sprints. Shared understanding of acceptance criteria ensures that all team members understand the scope of work. - -Here are two examples of defining acceptance criteria. - -- **Example 1: A Product Backlog Item is considered "Done" when the following objectives have been met:** - - - Solution builds successfully. - - Code written and merged into main branch - - Unit Tests implemented on all features to an appropriate code coverage - - All regression tests run and pass - - All acceptance criteria met - - Code has been peer reviewed and comments addressed - - User Story moved to Resolved state - - Remaining hours for tasks set to zero and tasks closed. - - No open Sev1 or Sev2 bugs - - Deploys successfully to nondevelopment environment (automated) - - Static Code Analysis is run with results no worse than the baseline. - -- **Example 2: A Sprint is considered "Done" when the following objectives have been met:** - - The time period allocated for the Sprint has passed - - Unfinished work has been moved to the Backlog - - Completed work has been deployed to target environment(s) and demoed in a Sprint Review to the Product Owner - - Sprint Summary email has been sent to the team detailing: - - User Stories Completed - - Velocity of the sprint - - Sprint Burndown - - Notable accomplishments, highlights, or milestones that were hit - - Retrospective conducted. - -## Monitor and report on changes - -Teams can monitor changes through the following methods: -- Work item queries -- Team velocity charts -- Sprint burndown and release burndown charts - - -### Work item queries - -With queries you can find and triage a list of change management requests or work items tagged with a change management tag. - - -### Team velocity and unplanned work - -The team velocity chart provides several pieces of information. This chart shows how much work was planned and how much was completed. Visually, you can determine how often work was added to a sprint after the sprint began. As shown in the following image, the team velocity for the past 10 sprints shows a pattern of adding work after the sprint start date. - -:::image type="content" source="media/manage-change/velocity-chart-scope-creep.png" alt-text="Screenshot of Velocity chart showing scope creep"::: - - -### Sprint burndown and scope creep - -Another chart to review for scope creep is the sprint burndown chart. As shown in the following image, a number of work items were added after the start of the sprint. - -:::image type="content" source="media/manage-change/sprint-burndown-scope-increase.png" alt-text="Screenshot of Sprint burndown showing scope creep"::: - -With Azure Boards, you can review the sprint burndown charts for each sprint and each team to determine the degree of scope creep introduced into each sprint. - -## Get notified of changes - -Azure DevOps provides a robust alert system, allowing project members to set alerts for themselves, a team, or a project. - -As changes occur to work items, code reviews, source control files, and builds, you can receive email notifications. For example, you can set an alert to be notified whenever a bug that you opened is resolved or a work item is assigned to you. You can set personal alerts, team, project, or organization alerts. - -To support change management, you can define team alerts for the following instances: - -- A requirement or work item is tagged with a change request tag -- A formal change request work item is filed -- Work is added to a sprint after the sprint has started - - - -## Related articles - -To learn more about any of the concepts introduced in this article, refer to the following resources. - -#### Industry articles - -- [5 Implications for Change Management in an Agile World](https://www.imaworldwide.com/blog/5-implications-for-change-management-in-an-agile-world) -- [How to Create the Best Agile Change Management Process](https://www.mindville.com/blog/create-the-best-agile-change-management-process) -- [Managing Change Requests in Scrum](https://www.infoq.com/news/2008/12/change-requests-in-scrum/) -- [Identify And Avoid Project Scope Creep](https://thedigitalprojectmanager.com/scope-creep/) -- [Change Management meets Agile, how does that work?](https://www.andchange.com/themes/change-management-meets-agile/) - - -#### Agile and Agile culture +## Related articles - [What is Agile?](/devops/plan/what-is-agile) -- [Agile culture](../boards/plans/agile-culture.md) -- [Best practices for "light-weight" Agile project management](../boards/best-practices-agile-project-management.md) -- [Scaling Agile - Practices that scale](../boards/plans/practices-that-scale.md) - - -#### Work items and process guidance - -- [Capability Maturity Model Integration (CMMI) process](../boards/work-items/guidance/cmmi-process.md) -- [Acceptance criteria](../boards/backlogs/best-practices-product-backlog.md#acceptance-criteria) -- [Definition of Done](../boards/boards/add-columns.md#definition-of-done) -- [Add work item tags to categorize and filter lists and boards](../boards/queries/add-tags-to-work-items.md) -- [Customize your backlogs or boards (Inheritance process)](../organizations/settings/work/customize-process-backlogs-boards.md) - -#### Monitor and report on progress - -- [Triage work items](../boards/queries/triage-work-items.md) -- [View or configure team velocity](../report/dashboards/team-velocity.md) -- [Burndown guidance, scope management](../report/dashboards/burndown-guidance.md) -- [Cumulative flow, lead time, and cycle time guidance](../report/dashboards/cumulative-flow-cycle-lead-time-guidance.md) - -#### Notifications - -- [Default and supported notifications](../organizations/notifications/oob-built-in-notifications.md) -- [Manage personal notifications](../organizations/notifications/manage-your-personal-notifications.md) -- [Manage notifications for a team or group](../organizations/notifications/manage-team-group-global-organization-notifications.md) - - -#### Maintain specifications and share information - -- [About Wikis, READMEs, and Markdown](../project/wiki/about-readme-wiki.md) -- [Share information within work items and social tools](../boards/queries/share-plans.md) diff --git a/docs/cross-service/manage-requirements.md b/docs/cross-service/manage-requirements.md index 3792ba07845..ac8a955a699 100644 --- a/docs/cross-service/manage-requirements.md +++ b/docs/cross-service/manage-requirements.md @@ -1,281 +1,218 @@ --- -title: Manage requirements, Agile methods +title: Manage requirements, Agile titleSuffix: Azure DevOps -description: Learn about the tools and features available to manage requirements +description: Learn about the tools and features available to manage requirements for Agile projects in Azure DevOps. ms.subservice: azure-devops-cross-service ms.topic: conceptual ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 09/08/2020 +ms.date: 03/05/2025 --- - - -# Manage requirements +# Manage Agile requirements [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] +In this article, learn the key concepts and tasks associated with managing project requirements with Agile tools and features in Azure DevOps. -Become familiar with the essential concepts to manage projects using Agile tools. Gain an overview of Azure DevOps tools and features to manage requirements. This article maps Agile requirements management tasks by project managers to the tools Azure DevOps supports. More detailed information is provided under [Related articles](#related-articles). - - -> [!NOTE] +> [!TIP] > *Requirements management is a continuous process throughout a project lifecycle—encompassing the processes of documenting, analyzing, prioritizing, tracking, and collaborating with stakeholders to agree on work to be performed. A single requirement corresponds to a capability which a project outcome—product, service, architecture, performance—should conform.* - -Agile requirements management supports the following scenarios. - -> [!div class="checklist"] -> - Define and track status of requirements -> - Analyze and prioritize requirements -> - Assign requirements to timeboxes -> - Group and organize requirements -> - Manage dependencies -> - Determine what can ship and when -> - Monitor and report on progress - -When managing requirements using Agile methods, you'll also perform within an Agile culture which supports the following principles and methods: - -> [!div class="checklist"] -> - Alignment within the organization -> - Autonomous teams -> - Kanban and lean management -> - Scrum - - ## Capture requirements -You capture requirements using work items, where each work item is based on a work item type. You have a choice of work item types to use based on the process you select. Or, you can add a custom work item type. +Use work items to capture requirements. Each work item has a type, which depends on the [process you choose](../boards/work-items/guidance/choose-process.md). You can also create a custom work item type. [!INCLUDE [temp](../boards/includes/note-requirements-terms.md)] - -### Work item fields and form - -You can use work items to track anything you need to track. Each work item represents an object stored in the work item data store. Each work item is based on a work item type and is assigned a unique identifier. - -Each work item supports tracking data contained in work item fields. Also, it captures changes as updates are made within the **History** field and comments made in the **Discussion** section. The following image shows a sample work item form for the User Story work item type. - -**Example work item form** - -> [!div class="mx-imgBorder"] -> ![Screenshot of User Story work item form](media/manage-requirements/user-story-work-item-form.png) - -In a nutshell, you use work items to support these tasks: -- Add information, update status, assign to team members, link work items, and attach files -- Assign work to a timebox or sprint -- Quickly fill in work item fields using work item templates -- Contribute to a queryable discussion thread -- Prioritize work and triage work items. - -Other features that support end-to-end traceability are the **Development** and **Deployment** sections. These sections support the following tasks and insights: - -- Create a new branch or pull request from a work item -- Complete the pull request -- Perform a squash merge -- Create a branch for several work items -- Link a work item to existing development and build objects -- View the release stages associated with the work item within the work item form in real time -- View the status of releases within those work items that are associated with commits in the build and release pipelines ### Work item types -Different work item types support capturing different information and workflow processes. Each work item is based on a work item type. The following images illustrate the default work item types used to capture requirements and code defects. They are based on the four system processes—Agile, Basic, Scrum, or Capability Maturity Model Integration (CMMI). +Work items let you capture different information and workflows. Each work item has a type, which depends on the process you choose. You can use these default work item types for requirements and defects: + +- **Agile:** User Story and Bug +- **Basic:** Issue and Bug +- **Scrum:** Product Backlog Item and Bug +- **CMMI:** Requirement and Bug -Each Azure DevOps project is defined based on one of these customizable processes. Each team can determine how they want to track bugs. +You can customize each process for your Azure DevOps project. You can also decide how to track bugs for each team. **Default work item types** [!INCLUDE [temp](../boards/includes/work-item-types.md)] - ### Customize work item types -You can add custom work item types or customize the default work item types. Supported customizations include the following additions: +You can customize the following aspects of work item types: - Add custom fields and workflow states -- Add custom rules to support business workflow processes +- Add custom rules that support business workflow processes - Add custom portfolio backlogs and customize backlogs and boards -- Add custom controls to work item forms to gain enhanced functionality. +- Add custom controls to work item forms to gain enhanced functionality + +### Add work items to the product backlog or board + +To capture requirements, start by adding a Title to the product backlog. You can add more details later as needed. -### Add work items to product backlog or board +**Capture requirements on the product backlog** -Capturing requirements typically starts by adding a Title to a product backlog. You add details later. +Adding a Title to the product backlog helps you quickly capture and organize requirements and allows you to prioritize and refine them over time. -**Capture requirements on the product backlog** +![Screenshot of adding product backlog item.](media/manage-requirements/add-new-items-agile.png) -> [!div class="mx-imgBorder"] -> ![Screenshot of add product backlog item](media/manage-requirements/add-new-items-agile.png) +### Work item fields +Each work item tracks data in fields, captures changes in the **History** field, and comments in the **Discussion** section. + +Use work items to: +- Add information, update status, assign to team members, link work items, and attach files +- Assign work to a timebox or sprint +- Quickly fill in fields using templates +- Contribute to a queryable discussion thread +- Prioritize and triage work items + +**Development** and **Deployment** sections support end-to-end traceability: +- Create a new branch or pull request from a work item +- Complete the pull request +- Perform a squash merge +- Create a branch for several work items +- Link a work item to existing development and build objects +- View release stages associated with the work item in real time +- View the status of releases associated with commits in build and release pipelines ### Import and update requirements using Excel -Alternatively, you can import and update requirements you've defined through a .csv file or Excel spreadsheet. These tools support a flat list or a hierarchy of work items. As shown in the following image, a hierarchy of Epics, Features, and User Stories are defined in Excel and then imported to Azure DevOps. +You can use a .csv file or Excel spreadsheet to import and update your requirements. These tools let you work with a flat list or a tree of work items. For example, you can define a tree of Epics, Features, and User Stories in Excel and then import them to Azure DevOps. **Import requirements from Excel** -> [!div class="mx-imgBorder"] -> ![Screenshot of Excel tree list of requirements to import.](../boards/backlogs/office/media/excel/import-safe-hierarchy-list.png) +![Screenshot of Excel tree list of requirements to import.](../boards/backlogs/office/media/excel/import-safe-hierarchy-list.png) +### Functional and nonfunctional requirements -### Functional and non-functional requirements +Work items help you track any work that you or your team need to do. You can use the same work item type for both functional and nonfunctional requirements: -Any work that you or a development team need to track can be captured using work items. You can use the same type of work item to capture both functional and non-functional requirements. Non-functional requirements specify criteria associated with system operations rather than specific product or service functionality. - -You can differentiate your requirements using tags, the Business Value field, or a custom field. - -### Maintain requirement specifications +- **Functional requirements**: Describe what your product or service should do. +- **Nonfunctional requirements**: Describe how your product or service should operate. -Requirements often require specifications to provide details that aren't readily captured within the work item. You can use Azure DevOps to maintain and version control your requirements under an Azure Repos repository. Or, you can use a project wiki to provide a central source and repository for specifications. +Categorize your requirements using the following elements: +- Tags +- Business Value field +- Custom fields -You can then link your specifications or attach them to your requirements. - - -## Analyze and prioritize requirements +### Maintain requirement specifications -Once you have a working backlog, you'll want to get it in priority order. You'll want to review and refine your requirements and make sure the acceptance criteria is well-defined. These tasks are supported through the following Azure Boards tools: +Some requirements need more details than what you can put in a work item. Use Azure DevOps to store and manage your requirements in an Azure Repos repository or a project wiki. -- **Product backlog**: Supports drag-and-drop of work items to get them in priority order. Supports bulk-edit of work items to change assignments or update fields. -- **Query Results, Triage mode**: Supports review of a list of work items and their forms so that you can quickly update work items and add details. - -Here the features backlog shows the sequence of features to ship. +You can link or attach your specifications to your requirements. -**Prioritize feature backlog** +## Analyze and prioritize requirements -:::image type="content" source="media/manage-requirements/features-backlog-priority-order.png" alt-text="Screenshot of Features backlog, ordered by feature parent."::: +Use Azure Boards tools to prioritize and refine your backlog, ensuring your requirements are clear and well-defined: +- **Product backlog**: Drag and drop work items to reorder by priority. Edit multiple work items at once to change assignments or update fields. +- **Query Results, Triage mode**: Review and quickly update work items and add details. ## Group and organize requirements -The product backlog starts out as a flat list. However, often you want to group requirements that support specific features or business objectives. Azure Boards supports this by providing portfolio work item types, portfolio backlogs and boards, and a Mapping tool to quickly link requirements to a portfolio work item. - -Work item tags are another way you can group requirements. +Use Azure Boards to group your requirements by features or business objectives. Utilize portfolio work item types, portfolio backlogs and boards, and the Mapping tool to link requirements to higher-level work items. +You can also use work item tags to group requirements in different ways. ### Epics, features, and portfolio backlogs -You group requirements under Features, and Features under Epics, using parent-child hierarchical links. This type of grouping is recommended for organizations with several teams that want to view rollups associated with multiple teams and to take advantage of all portfolio planning tools. +Use parent-child links to create a hierarchy of requirements, features, and epics. Parent-child links are useful for organizations with multiple teams that want to see how their work contributes to overall goals and utilize portfolio planning tools. -By grouping work within a hierarchy, you can manage a portfolio of features that are supported by different development and management teams. Also, you can view a rollup of estimates, progress bars, and more on product backlogs. - +With a hierarchy, you can manage a set of features that different teams work on. You can also view summaries of estimates, progress, and more on the product backlogs. -**Group User Stories under Features using Mapping** - -:::image type="content" source="media/manage-requirements/mapping-user-stories-to-features.png" alt-text="Screenshot of mapping User Stories under Features using Mapping tool."::: +**Group user stories under Features using Mapping** +:::image type="content" source="media/manage-requirements/mapping-user-stories-to-features.png" alt-text="Screenshot of mapping user stories under Features using Mapping tool."::: ### Use tags to group work items -With work item tags, team members can assign ad-hoc tags to work items. You can use these tags to filter backlogs and boards as well as query on work items. For example, the following image illustrates a Kanban board filtered on the *web* keyword which displays cards with the *Web* tag. +Work item tags are labels that team members can add to work items. You can filter backlogs and boards by these tags to see only the matching work items. Tags can also be used in queries. For example, you can filter the board to see only the cards with the *web* tag. **Filter backlogs and boards based on tags** -> [!div class="mx-imgBorder"] -> ![Screenshot of Kanban board, Filter using keyword search.](../boards/backlogs/media/filter-boards/filter-kb-text-web-services.png) - -## Implement Kanban or Scrum +![Screenshot of board, Filter using keyword search.](../boards/backlogs/media/filter-boards/filter-kb-text-web-services.png) -Two of the major Agile methods are Kanban and Scrum. Azure Boards supports both methods. Or, teams can adapt them to use a combination of methods such as Scrumban. +## Use Kanban or Scrum -### Implement Kanban +Azure Boards supports two major Agile methods: Kanban and Scrum. You can also use a hybrid approach like Scrumban that combines elements of both methods. -Each product and portfolio backlog is associated with a corresponding Kanban board. Both backlogs and boards are associated with a team, and display work items based on the area and iteration paths selected by the team. +### Use Kanban -Each board supports many Kanban practices such as defining columns and swimlanes, setting Work-in-Progress (WIP) limits, defining the Definition of Done, and more. As work completes in one stage, you update the status of an item by dragging it to a downstream stage. +Use a Kanban board to visualize your work items on a product or portfolio backlog. The board shows the work items that belong to your team, based on the area and iteration paths you choose. -**Example Kanban board** +You can customize your board to match your Kanban practices. For example, you can define columns and swimlanes, set WIP limits, and specify the Definition of Done. You can drag a work item to a different column to update its status as it moves through the stages of your workflow. -:::image type="content" source="../boards/boards/media/alm-cc-move-card.png" alt-text="Screenshot of Kanban board, Agile template, update status of work item."::: +**Example board** -Each team can quickly configure their board and the cards to support their business needs. - - -### Implement Scrum - -Sprint backlogs and Taskboards provide a filtered view of work items a team has assigned to a specific iteration path, or sprint. From your requirements backlog, you can drag-and-drop work items onto an iteration path, and then view that work in a separate **Sprint Backlog**. +:::image type="content" source="../boards/boards/media/alm-cc-move-card.png" alt-text="Screenshot of board, Agile template, update status of work item."::: -**Example Sprint Backlog** +### Use Scrum -> [!div class="mx-imgBorder"] -> ![Screenshot of Boards>Sprints>Backlog](../boards/work-items/media/view-add/view-sprint-backlogs.png) +Use a sprint backlog and Taskboard to view the work items your team planned for a specific sprint. Assign work items to a sprint by dragging and dropping them from your requirements backlog. Then, view them in a separate **Sprint Backlog**. -Supported Scrum practices include the following tasks: +**Example sprint backlog** -- Assign requirements to a sprint -- Add tasks to requirements -- Set sprint capacity for team members -- Adjust work to fit sprint capacity -- Share your sprint plan -- Filter, update tasks, and update task status -- Monitor sprint burndown +![Screenshot of Boards>Sprints>Backlog](../boards/work-items/media/view-add/view-sprint-backlogs.png) +For more information, see [Plan and track your work](../boards/get-started/plan-track-work.md). #### Sprint burndown chart -By updating the status of work daily throughout a sprint, you can easily track sprint progress with the Sprint burndown chart, as shown in the following image. +The Sprint burndown chart provides a daily update on your sprint's progress, showing the current work status, as illustrated in the following image. **Example Sprint burndown chart** -> [!div class="mx-imgBorder"] -> ![Screenshot of Analytics Sprint burndown chart.](../boards/media/best-practices/sprint-burndown-chart.png) - - +![Screenshot of Analytics Sprint burndown chart.](../boards/media/best-practices/sprint-burndown-chart.png) ## Manage dependencies -In Microsoft Project, you manage tasks that depend on the completion of other tasks by linking them. To manage dependencies in Azure Boards, you can link work items using the Predecessor/Successor link type. Once you've linked work items, you can view link relationships using the [Work Item Visualization](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization) Marketplace extension. The following image illustrates link relationships among several work items. +In Microsoft Project, you manage task dependencies by linking them. In Azure Boards, link work items using the Predecessor/Successor link type. View link relationships using the [Work Item Visualization](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.WorkItemVisualization) Marketplace extension. The following image illustrates link relationships among several work items. [!INCLUDE [temp](../includes/lightbox-image.md)] -> [!div class="mx-imgBorder"] -> [![Screenshot of Visualize work item relationships.](../boards/media/best-practices/visualize-successor-links-cross-project-wide.png)](../boards/media/best-practices/visualize-successor-links-cross-project-wide.png#lightbox) +[![Screenshot of Visualize work item relationships.](../boards/media/best-practices/visualize-successor-links-cross-project-wide.png)](../boards/media/best-practices/visualize-successor-links-cross-project-wide.png#lightbox) ### Minimum Viable Product versus Critical Path Management -Azure Boards doesn't provide a native view of the critical path. In part, as Agile methodologies favor a Minimum Viable Product (MVP) over Critical Path Management (CPM). By using MVP, you identify the shortest path and dependencies by prioritizing epics, features, stories, and tasks. - +Azure Boards doesn't have a built-in way to show the critical path because Agile methods prefer a Minimum Viable Product (MVP) over Critical Path Management (CPM). With MVP, you find the shortest and most dependent path by ranking epics, features, stories, and tasks by importance. ## Perform milestone planning -Two tools that support planning what can ship when are team velocity and forecasting. +You can use team velocity and forecasting to plan when you can deliver your work. ### Team velocity -One of the advantages of working in sprints is that you gain insight into team velocity. Velocity provides an indication of how much work a team can complete during a sprint based either on a count of completed work items or the sum of requirement estimates. +Working in sprints helps you understand your team’s velocity. Velocity shows how much work your team can finish in a sprint, based on the number or the size of the completed work items. **Example team Velocity chart** -> [!div class="mx-imgBorder"] -> ![Screenshot of team velocity chart.](media/manage-requirements/team-velocity.png) - +![Screenshot of team velocity chart.](media/manage-requirements/team-velocity.png) ### Forecast requirements -The **Forecast** tool requires that you provide estimates to the Story Points, Effort, or Size field for each requirement. - -With estimates assigned to each requirement, you can set a team velocity. In the example below, we specify 12 for the velocity, equivalent to stating that on average the team can complete 12 Story Points per sprint. The Forecast tool shows which requirements and features the team can complete within the next six sprints. Using the Planning tool, you can quickly assign requirements to the forecasted sprints. +Use the **Forecast** tool to estimate Story Points, Effort, or Size for each requirement. +You can also set team velocity based on your estimates. For example, if you say your team can do 12 Story Points per sprint, the Forecast tool shows you which requirements and features you can finish in the next six sprints. You can use the Planning tool to assign requirements to the predicted sprints. **Example Forecast of requirements backlog** -[!INCLUDE [temp](../includes/lightbox-image.md)] - -> [!div class="mx-imgBorder"] -> [![Screenshot of Forecast of Requirements backlog, ordered by feature parent.](../boards/media/best-practices/forecast-product-backlog-ordered-parent.png)]../boards/media/best-practices/forecast-product-backlog-ordered-parent.png#lightbox) - -If you want to integrate your requirements planning with Microsoft Project tools, you may do so via a Marketplace extension. +![Screenshot of Forecast of Requirements backlog, ordered by feature parent.](../boards/media/best-practices/forecast-product-backlog-ordered-parent.png) +Use a Marketplace extension to integrate your requirements planning with Microsoft Project tools. #### Milestone markers -Milestone markers aren't used in Azure Boards work tracking, except for Delivery Plans. [Delivery Plans](#delivery-plans) provide a calendar view and allow you to define a milestone marker. -However, you can use one or more of the following options to mark a work item as a milestone: -- Simply prepend or append the word **Milestone** in the title of your work item +Milestone markers aren't used in Azure Boards work tracking, except for Delivery Plans. [Delivery Plans](#delivery-plans-and-multiple-team-deliverables) provide a calendar view and allow you to define a milestone marker. + +You can use one or more of the following options to mark a work item as a milestone: +- Prepend or append the word **Milestone** in the title of your work item - Add a work item tag labeled **Milestone** - Add a custom field labeled **Milestone** and populate it with a pick list of milestones - Link work items using the Predecessor/Successor or Related link type to a milestone work item -- Assign a milestone work item to the sprint in which it's targeted for completion. - - +- Assign a milestone work item to the sprint targeted for completion. ## Assign requirements to timeboxes @@ -283,45 +220,40 @@ You can quickly assign work items to a sprint through drag-and-drop from the pro **Example assign requirements to sprints** -> [!div class="mx-imgBorder"] -> ![Boards>Backlogs>Drag-drop items onto sprint](../boards/sprints/media/define-sprints/drag-drop-backlog-items-to-sprint.png) - +![Screenshot of drag-drop items onto a sprint.](../boards/sprints/media/define-sprints/drag-drop-backlog-items-to-sprint.png) ## Monitor and report on progress -The three main tools you'll want to use to review progress and deliverables are: +To review progress and deliverables, you can use the following tools: -- Features Kanban board -- Features backlog with rollup columns -- Delivery plans +- Features board: Shows the status of each feature and its tasks +- Features backlog: Displays the rollup columns for the features and their child work items +- Delivery plans: Provides a timeline view of the features and their dependencies across different teams -### Features Kanban board +### Features board -Your Features board is another place to review progress and ensure the continuous flow of deliverables. The following image illustrates a customized Features board. In progress columns have been added such as *Need more info*, *Spec Complete*, *In Progress*, and *Customer Rollout*. These column labels provide a more natural set of states as Features get proposed, researched, designed, developed, and then deployed to production. +You can also use your **Features** board to track progress and ensure the continuous delivery of value. The following image shows an example of a customized Features board with added columns for different stages of feature development, such as Need more info, Spec Complete, In Progress, and Customer Rollout. These columns reflect the natural flow of features from proposal to production. **Example of Features board with customized columns** [!INCLUDE [temp](../includes/lightbox-image.md)] -> [!div class="mx-imgBorder"] -> [![Screenshot of Features board with customized columns.](../boards/media/best-practices/features-board-customized.png)](../boards/media/best-practices/features-board-customized.png#lightbox) +[![Screenshot of Features board with customized columns.](../boards/media/best-practices/features-board-customized.png)](../boards/media/best-practices/features-board-customized.png#lightbox) ### Rollup -One quick and visual way to monitor progress is from the Features backlog. By adding the rollup progress bar column, you can see what percentage of work items are completed for each feature, as shown in the following image. +The **Features backlog** offers a quick and visual way to monitor progress. You can add the **rollup progress bar** column to see the completion percentage of each feature’s work items. The following image shows how the column shows the progress of different features. **Example of Requirements backlog showing progress rollup** -> [!div class="mx-imgBorder"] -> ![Screenshot of Features backlog showing progress bars column option.](../boards/media/best-practices/feature-backlog-progress.png) - - +![Screenshot of Features backlog showing progress bars column option.](../boards/media/best-practices/feature-backlog-progress.png) + ### Delivery plans and multiple team deliverables -To review features delivered across several teams, configure a delivery plan. Delivery plans provide an interactive board to review a calendar schedule of stories or features several teams plan to deliver. +If you want to see the features that several teams are delivering across a timeline, you can set up a delivery plan. A delivery plan is an interactive board that shows a calendar view of the stories or features that different teams plan to deliver. -**Example of multi-team Delivery Plan** +**Example of multi-team delivery plan** ::: moniker range="azure-devops" :::image type="content" source="../boards/plans/media/plans/overview-with-callouts.png " border="false" alt-text="Screenshot with callouts of Delivery Plans, collapsed teams."::: @@ -331,88 +263,13 @@ To review features delivered across several teams, configure a delivery plan. De Interactive plan elements ::: moniker-end - ## Get notified of changes -Azure DevOps provides a robust alert system, allowing project members to set alerts for themselves, a team, or a project. - -As changes occur to work items, code reviews, source control files, and builds, you can receive email notifications. For example, you can set an alert to be notified whenever a bug that you opened is resolved or a work item is assigned to you. You can set personal alerts, team, project, or organization alerts. +Azure DevOps provides a robust alert system, where project members can [set alerts for themselves, a team, or a project](../organizations/notifications/about-notifications.md). As changes occur to work items, code reviews, source control files, and builds, you can receive email notifications. - - - - ## Related articles -To learn more about any of the concepts introduced in this article, refer to the following articles. - -#### Agile and Agile culture - -- [What is Agile?](/devops/plan/what-is-agile) -- [Agile culture](../boards/plans/agile-culture.md) -- [Best practices for "light-weight" Agile project management](../boards/best-practices-agile-project-management.md) -- [Scaling Agile - Practices that scale](../boards/plans/practices-that-scale.md) - - -#### Work items, work item types, and process models - -- [About work items](../boards/work-items/about-work-items.md) -- [Add work item tags to categorize and filter lists and boards](../boards/queries/add-tags-to-work-items.md) -- [About processes and process templates](../boards/work-items/guidance/choose-process.md) -- [About process customization and inherited processes](../organizations/settings/work/inheritance-process-model.md) -- [Bulk add or modify work items with Excel](../boards/backlogs/office/bulk-add-modify-work-items-excel.md) -- [About Area and Iteration Paths (sprints)](../organizations/settings/about-areas-iterations.md) -- [Work tracking, process, and project limits](../organizations/settings/work/object-limits.md) - - -#### Backlogs and boards - -- [Create your backlog](../boards/backlogs/create-your-backlog.md) -- [Organize your backlog](../boards/backlogs/organize-backlog.md) -- [Define features and epics](../boards/backlogs/define-features-epics.md) -- [Refine your backlog](../boards/backlogs/best-practices-product-backlog.md) -- [About teams and Agile tools](../organizations/settings/about-teams-and-settings.md) -- [Tasks supported by Backlogs, Boards, Taskboards, and Plans](../boards/backlogs/backlogs-boards-plans.md) -- [Configure and customize Azure Boards](../boards/configure-customize.md) - -#### Kanban - -- [Start using your Kanban board](../boards/boards/kanban-quickstart.md) -- [Add columns to your Kanban board](../boards/boards/add-columns.md) -- [Customize cards](../boards/boards/customize-cards.md) -- [Filter your Kanban board](../boards/backlogs/filter-backlogs-boards-plans.md) - -#### Scrum - -- [Assign backlog items to a sprint](../boards/sprints/assign-work-sprint.md) -- [Configure and monitor sprint burndown](../report/dashboards/configure-sprint-burndown.md) -- [Scrum and best practices](../boards/sprints/best-practices-scrum.md) - -#### Dependency management - -- [Link user stories, issues, bugs, and other work items](../boards/backlogs/add-link.md) -- [Triage work items](../boards/queries/triage-work-items.md) - -#### Milestone planning - -- [View or configure team velocity](../report/dashboards/team-velocity.md) -- [Forecast your product backlog](../boards/sprints/forecast.md) -- [The Critical Path on Agile Projects](https://www.mountaingoatsoftware.com/blog/the-critical-path-on-agile-projects) -- [Running a lean startup on Azure DevOps](https://medium.com/@giladkhen/running-a-lean-startup-on-azure-devops-5934ced2cc42) - -#### Monitor and report on progress - -- [Display rollup progress or totals](../boards/backlogs/display-rollup.md) -- [Review team Delivery Plans](../boards/plans/review-team-plans.md) - -#### Maintain specifications and share information - -- [About Wikis, READMEs, and Markdown](../project/wiki/about-readme-wiki.md) -- [Share information within work items and social tools](../boards/queries/share-plans.md) - - -#### Notifications - -- [Default and supported notifications](../organizations/notifications/oob-built-in-notifications.md) -- [Manage personal notifications](../organizations/notifications/manage-your-personal-notifications.md) -- [Manage notifications for a team or group](../organizations/notifications/manage-team-group-global-organization-notifications.md) +- [Follow best practices for "light-weight" Agile project management](../boards/best-practices-agile-project-management.md) +- [Understand work items](../boards/work-items/about-work-items.md) +- [Create your backlog](../boards/backlogs/create-your-backlog.md) +- [Link user stories, issues, bugs, and other work items](../boards/backlogs/add-link.md) \ No newline at end of file diff --git a/docs/cross-service/media/overview/development-control-plus-github.png b/docs/cross-service/media/overview/development-control-plus-github.png index ee0b9f384f3..da59eed5806 100644 Binary files a/docs/cross-service/media/overview/development-control-plus-github.png and b/docs/cross-service/media/overview/development-control-plus-github.png differ diff --git a/docs/cross-service/toc.yml b/docs/cross-service/toc.yml index 985667e7e05..e6f919151b2 100644 --- a/docs/cross-service/toc.yml +++ b/docs/cross-service/toc.yml @@ -15,10 +15,8 @@ href: end-to-end-traceability.md - name: Drive Git development href: ../boards/backlogs/connect-work-items-to-git-dev-ops.md?toc=/azure/devops/cross-service/toc.json - - name: Link work items to builds and deployments - href: ../boards/work-items/work-item-deployments-control.md?toc=/azure/devops/cross-service/toc.json - name: Link work items to other objects - href: ../organizations/notifications/add-links-to-work-items.md?toc=/azure/devops/cross-service/toc.json + href: ../boards/backlogs/add-link.md?toc=/azure/devops/cross-service/toc.json - name: Manage requirements href: manage-requirements.md - name: Manage change diff --git a/docs/demo-gen/build-your-own-template.md b/docs/demo-gen/build-your-own-template.md index 289bbabbee9..ee5e6094947 100644 --- a/docs/demo-gen/build-your-own-template.md +++ b/docs/demo-gen/build-your-own-template.md @@ -17,7 +17,7 @@ Azure DevOps Generator provides many out-of-the-box templates that support a wid ## Prerequisites -You must have an [Azure DevOps project](../organizations/projects/create-project.md) that's ready for extraction. The extractor captures the contents of the project and saves them as JSON files, which get archived into a zip file. +An [Azure DevOps project](../organizations/projects/create-project.md) that's ready for extraction. The extractor captures the contents of the project and saves them as JSON files, which get archived into a zip file. ## Build a custom template diff --git a/docs/demo-gen/configure.md b/docs/demo-gen/configure.md new file mode 100644 index 00000000000..d83bd42b097 --- /dev/null +++ b/docs/demo-gen/configure.md @@ -0,0 +1,88 @@ +--- +title: Demo Generator Overview +description: Learn how to create an Azure DevOps project using the Azure DevOps Demo Generator. +ms.subservice: azure-devops-new-user +ms.author: glmorale +author: gloridelmorales +ms.topic: conceptual +monikerRange: 'azure-devops' +ms.date: 02/28/2025 +--- + +# Overview of Demo Generator + +To run the Azure DevOps Demo Generator project as a console application or executable, follow these steps: + +Ensure you have the following installed on your machine: + +- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) +- [Visual Studio](https://visualstudio.microsoft.com/) or any other preferred IDE + + +## Steps + +1. **Clone the Repository** + + If you haven't already, clone the repository to your local machine: + + ```sh + git clone + cd + ``` + +2. **Open the Solution** + + Open the **ADOGenerator.sln** solution file in Visual Studio or your preferred IDE. + +3. **Set ADOGenerator as the Startup Project** + + In Visual Studio: + + - Right-click on the ADOGenerator project in the Solution Explorer. + - Select Set as Startup Project. + +4. **Build the Solution** + + Build the solution to ensure all dependencies are restored and the project compiles successfully: + + - In Visual Studio, right-click on the solution in the Solution Explorer and select `Build Solution`. + - Alternatively, you can use the command line: + ```sh + dotnet build + ``` + +5. **Run the Project** + + To run the project as a console application: + + - In Visual Studio, press `F5` or click on the Start button. + - Alternatively, you can run the project from the command line: + ```sh + dotnet run --project src/ADOGenerator/ADOGenerator.csproj + ``` + +6. **Publish the Project** + + To create an executable, publish the project: + + - In Visual Studio, right-click on the ADOGenerator project in the Solution Explorer and select `Publish`. + - Follow the prompts to configure the publish settings (e.g., target folder, configuration, etc.). + - Alternatively, you can use the command line: + ```sh + dotnet publish src/ADOGenerator/ADOGenerator.csproj -c Release -r win-x64 --self-contained + ``` + +7. **Run the Executable** + + Navigate to the publish directory and run the executable: + ```sh + cd src/ADOGenerator/bin/Release/net8.0/win-x64/publish + ./ADOGenerator.exe + ``` + +## Additional Notes + +- Ensure that any required configuration files (e.g., `appsettings.json`) are present in the output directory. +- If you encounter any issues, check the console output for error messages and resolve any missing dependencies or configuration issues. + +By following these steps, you should be able to run the ADOGenerator project as a console application or executable. \ No newline at end of file diff --git a/docs/demo-gen/index.md b/docs/demo-gen/index.md index b49e8ef7a60..e50ba413c52 100644 --- a/docs/demo-gen/index.md +++ b/docs/demo-gen/index.md @@ -5,7 +5,7 @@ ms.subservice: azure-devops-new-user ms.author: sdanie ms.topic: conceptual monikerRange: 'azure-devops' -ms.date: 05/09/2018 +ms.date: 03/03/2025 --- # About the Azure DevOps Services Demo Generator @@ -14,9 +14,6 @@ ms.date: 05/09/2018 The Azure DevOps Services Demo Generator is a service which helps you provision projects in your organization with pre-populated sample content that includes source code, work items, iterations, service connections, and build and release pipelines based on a template you choose. -> [!div class="mx-imgBorder"] -> ![Image of Demo Generator main screen](media/3.png) - The purpose of this system is to simplify working with the hands-on-labs, demos and other education material provided by the Microsoft Visual Studio Marketing team. You can use it to experiment with different services and options in a personal, pre-configured sandbox, or to simply develop comfort with UI and workflows without impacting a production environment. -[Get started using the Demo Generator V2 now](https://azuredevopsdemogenerator.azurewebsites.net/), or follow the [simple walkthrough](use-demo-generator-v2.md). \ No newline at end of file +To run the Azure DevOps Demo Generator project as a console application or executable, follow the instructions provided in the [configure section](configure.md). \ No newline at end of file diff --git a/docs/demo-gen/media/101.png b/docs/demo-gen/media/101.png new file mode 100644 index 00000000000..f3170abbb1c Binary files /dev/null and b/docs/demo-gen/media/101.png differ diff --git a/docs/demo-gen/media/102.png b/docs/demo-gen/media/102.png new file mode 100644 index 00000000000..d1bab6deac8 Binary files /dev/null and b/docs/demo-gen/media/102.png differ diff --git a/docs/demo-gen/media/103.png b/docs/demo-gen/media/103.png new file mode 100644 index 00000000000..8e7464af321 Binary files /dev/null and b/docs/demo-gen/media/103.png differ diff --git a/docs/demo-gen/media/104.png b/docs/demo-gen/media/104.png new file mode 100644 index 00000000000..30ffc251103 Binary files /dev/null and b/docs/demo-gen/media/104.png differ diff --git a/docs/demo-gen/toc.yml b/docs/demo-gen/toc.yml index 1583b6573a0..2f84f88c163 100644 --- a/docs/demo-gen/toc.yml +++ b/docs/demo-gen/toc.yml @@ -1,6 +1,8 @@ - name: About Demo Generator - href: index.md?toc=/azure/devops/demo-gen/toc.json + href: index.md?toc=/azure/devops/demo-gen/toc.json +- name: Configure + href: configure.md?toc=/azure/devops/demo-gen/toc.json - name: Get started - href: use-demo-generator-v2.md?toc=/azure/devops/demo-gen/toc.json + href: use-demo-generator-v2.md?toc=/azure/devops/demo-gen/toc.json - name: Build a custom template - href: build-your-own-template.md?toc=/azure/devops/demo-gen/toc.json \ No newline at end of file + href: build-your-own-template.md?toc=/azure/devops/demo-gen/toc.json \ No newline at end of file diff --git a/docs/demo-gen/use-demo-generator-v2.md b/docs/demo-gen/use-demo-generator-v2.md index 2e8b49d78fc..86a12f5111e 100644 --- a/docs/demo-gen/use-demo-generator-v2.md +++ b/docs/demo-gen/use-demo-generator-v2.md @@ -5,84 +5,73 @@ ms.subservice: azure-devops-new-user ms.author: sdanie ms.topic: conceptual monikerRange: 'azure-devops' -ms.date: 10/10/2019 +ms.date: 2/28/2025 --- # Get started creating and populating demo Azure DevOps Services projects [!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] -1. Browse to the [Azure DevOps Demo Generator site](https://azuredevopsdemogenerator.azurewebsites.net/) by selecting the link, or copy `https://azuredevopsdemogenerator.azurewebsites.net/` into your browser's URL field. +You should first have the **Azure DevOps Demo Generator** app ready by following the steps outlined in the [configure section](configure.md). This app will automate the process of creating a new Azure DevOps project within your organization that is prepopulated with content (work items, repos, etc.) required for the labs. -2. Click **Sign In** and provide the Microsoft or Azure AD account credentials associated with an organization in Azure DevOps Services. If you don't have an organization, click on **Get Started for Free** to create one and then log in with your credentials. +When you run the application you will see the information about predefined templates, choose the template by entering the corresponding number - > [!div class="mx-imgBorder"] - > :::image type="content" source="media/homepage.png" alt-text="Azure DevOps Demo Generator V2 login" lightbox="media/homepage.png"::: - - > [!NOTE] - > If you are a member of multiple tenants and the desired tenant isn't the selected one, - > close your browser windows and then open a new browser and navigate to - > `https://aka.ms/vssignout`. Close this browser, open a new browser and navigate to - > `https://aex.dev.azure.com/me`, and sign-in using the desired tenant. +> [!div class="mx-imgBorder"] +> [![Azure DevOps Demo Generator select project template](../demo-gen/media/101.png "Azure DevOps Demo Generator select project template")](../demo-gen/media/101.png#lightbox) -1. After you sign in, select **Accept** to grant the Demo Generator permissions to access your Azure DevOps organization. +#### Select the authentication method - > [!div class="mx-imgBorder"] - > :::image type="content" source="media/2.png" alt-text="Azure DevOps Demo Generator V2 permissions screen" lightbox="media/2.png"::: +You have 2 methods to authenticate to use the Azure DevOps Demo Generator app: -1. Select the organization you will use to host the project created by the Azure DevOps Demo Generator. (You may have multiple accounts of which you are a member, and which are associated with your login, so choose carefully.) Provide a name for your project (such as "MyProjectDemo" ) that you and other contributors can use to identify it as a demo project. Lastly, select the demo project template you want to provision by clicking **...** (Browse) button. +1. Device Login using AD authentication +Register Your Application in Azure AD. Check out the [Register and Application](/entra/identity-platform/quickstart-register-app?tabs=certificate%2Cexpose-a-web-api#register-an-application) documentation for more details. - > [!div class="mx-imgBorder"] - > :::image type="content" source="media/templateselection.png" alt-text="Azure DevOps Demo Generator template selection screen" lightbox="media/templateselection.png"::: + * Login with the code displayed - The default template is **SmartHotel360**, which contains complete ASP.NET 2 web mobile and desktop business apps for a hotel, and can be deployed using Docker containers. + * After the login, organizations will be listed and select an organization to create project - There are several other templates available, including **MyHealthClinic**, which defines a team project for an ASP.NET Core app that deploys to Azure App Service; **PartsUnlimited**, which defines an ASP.NET app with customized CI/CD pipelines; and **MyShuttle**, which defines a Java app and Azure App Service deployment. If you are following a lab from [Azure DevOps Labs](https://www.azuredevopslabs.com), select the **DevOps Labs** tab to choose the template + > [!div class="mx-imgBorder"] +> [![Device login using AD Auth](../demo-gen/media/102.png "Device login using AD Auth")](../demo-gen/media/102.png#lightbox) - > [!NOTE] - > All templates provide fictional Azure DevOps users and pre-populated Agile planning and tracking work items and data, along with source code in an Azure Repos Git repo, as well as access to Azure Pipelines. +1. Sign in with a [Personal Access Token (PAT)](../organizations/accounts/use-personal-access-tokens-to-authenticate.md#creating-pats) with the following scopes: -1. Some templates may require additional extensions to be installed to your organization. The demo generation process checks to see if these extensions are already installed. If the extension is already installed, a green check will be displayed in front of the extension name. If the extension is **not** installed, select the empty check boxes to install the extension(s) to your account. When ready, click on **Create Project** button. + | Scope | Description | + | -------------------------- | ------------------------------------------ | + | vso.agentpools | Agent Pools (read) | + | vso.build_execute | Build (read and execute) | + | vso.code_full | Code (full) | + | vso.dashboards_manage | Team dashboards (manage) | + | vso.extension_manage | Extensions (read and manage) | + | vso.profile | User profile (read) | + | vso.project_manage | Project and team (read, write and manage) | + | vso.release_manage | Release (read, write, execute and manage) | + | vso.serviceendpoint_manage | Service Endpoints (read, query and manage) | + | vso.test_write | Test management (read and write) | + | vso.variablegroups_write | Variable Groups (read, create) | + | vso.work_full | Work items (full) | - > [!NOTE] - > If you want to manually install the extensions, click on the provided link for a specific extension, which takes you to the extension's page on Azure DevOps Marketplace. From there, you can install the extension. + Enter the organization name and the Personal Access Token (PAT). Provide the project name and press enter to create a project -2. Your project may take a couple of minutes for the Demo Generator to provision. When it completes, you will be provided with a link to the demo project. +> [!div class="mx-imgBorder"] +> [![Authenticating the app using Personal Access Token(PAT)](../demo-gen/media/103.png "Authenticating the app using Personal Access Token(PAT)")](../demo-gen/media/103.png#lightbox) - > [!div class="mx-imgBorder"] - > :::image type="content" source="media/projectcreated.png" alt-text="Azure DevOps Demo Generator project created screen" lightbox="media/projectcreated.png"::: +#### Select your organization -1. Select the link to go to the new demo Azure DevOps Services project and confirm it was successfully provisioned. +1. Select the organization you will use to host the project created by the Azure DevOps Demo Generator. (You may have multiple organizations of which you are a member, and which are associated with your login, so choose carefully.) Provide a name for your project (such as "MyProjectDemo" ) that you and other contributors can use to identify it as a demo project. - > [!div class="mx-imgBorder"] - > :::image type="content" source="media/projecthomepage.png" alt-text="Azure DevOps Demo Generator provision confirmation screen" lightbox="media/projecthomepage.png"::: +There are several templates available, including **eShopOnWeb**, which defines a team project for an .NET app that deploys to Azure App Service; **PartsUnlimited**, which defines an ASP.NET app with customized CI/CD pipelines; and **MyShuttle**, which defines a Java app and Azure App Service deployment. If you are following a lab from [Azure DevOps Labs](https://www.azuredevopslabs.com), select the **DevOps Labs** section to choose the template > [!NOTE] -> You must provide your own information such as URLs, logins, password, and others for the configuration of demo endpoints that use Azure resources. - -Next: [Learn how you can build your own template](build-your-own-template.md) - -## Common Issues and workarounds: +> All templates provide fictional Azure DevOps users and pre-populated Agile planning and tracking work items and data, along with source code in an Azure Repos Git repo, as well as access to Azure Pipelines. -### **Issue:** Error while creating release definition: -Tasks with versions `ARM Outputs:4.*` are not valid for deploy job `Agent job` in stage Stage 1 +Some templates may require additional extensions to be installed to your organization. The demo generation process checks to see if these extensions are already installed. If the extension is **not** installed, provide your consent to install extension by pressing **Y** or **Yes** to install the extension(s) to your account. When ready, press enter to **Create Project**. -**Cause:** This is usually caused by one of the third-party extensions not enabled or installed in your Azure DevOps org. Usually installation of extensions are quick but sometimes, it can take a few minutes (or even hours!) for an extension to be available to use, after it is installed in the marketplace. - -**Workaround:** You can try waiting for a few minutes and confirm whether the extension is available to use, and then run the generator again. - ------------------- -### **Issue:** Error while creating query: TF401256: You do not have Write permissions for query Shared Queries: - -**Cause:** In Azure DevOps, users have different access levels - Basic, Stakeholder and Visual Studio Subscriber. Access levels determine what features are available to users. In order to provision projects using the demo generator, you need at least a **Basic** access level. This error indicates the user has a *stakeholder* license which does not grant permissions to writing shared queries - -**Fix:** You should change the access level, from stakeholder to basic. Please refer to this article on docs: [Add users to your organization or project](../organizations/accounts/add-organization-users.md?view=azure-devops&preserve-view=true) for more information on how to add users to your organization, and specify the level of features they can use - -------------- +> [!NOTE] +> If you want to manually install the extensions, click on the provided link for a specific extension, which takes you to the extension's page on Azure DevOps Marketplace. From there, you can install the extension. -### **Issue:** TF50309: The following account does not have sufficient permissions to complete the operation: -The following permissions are needed to perform this operation: Create new projects +2. Your project may take a couple of minutes for the Demo Generator to provision. -**Cause:** You do not have permissions to create new projects in the Azure DevOps organization you have selected. You will need to be a part of the Project Administrators group or have explicit permissions to create new projects + > [!div class="mx-imgBorder"] + > :::image type="content" source="media/104.png" alt-text="Required extensions setup in organization" lightbox="media/104.png"::: -**Fix:** Please make sure you have the required permissions or try selecting a different Azure DevOps org where you project creation permission. \ No newline at end of file +3. You can go to your organization to confirm that the project was created once you see the Project created successfully message. \ No newline at end of file diff --git a/docs/dev-resources/index.yml b/docs/dev-resources/index.yml index 2bdd799e8aa..40c77e25a4f 100644 --- a/docs/dev-resources/index.yml +++ b/docs/dev-resources/index.yml @@ -9,8 +9,8 @@ metadata: description: Use command line interface, REST APIs, typescript tools and more to interface with Azure DevOps . ms.subservice: azure-devops-reference ms.topic: landing-page - author: KathrynEE - ms.author: kaelli + ms.author: rabououn + author: ramiMSFT ms.date: 02/18/2022 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new diff --git a/docs/docfx.json b/docs/docfx.json index 0c7bc605615..efe82051580 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -1,15 +1,19 @@ { "build": { - "content": - [ - { - "files": ["breadcrumb/toc.yml"] - }, - { - "files": ["**/**.md", - "**/**.yml"], + "content": [ + { + "files": [ + "breadcrumb/toc.yml" + ] + }, + { + "files": [ + "**/**.md", + "**/**.yml" + ], "exclude": [ "artifacts/nuget/bootstrap-nuget.md", + "pipelines/apps/cd/deploy-linuxvm-deploygroups.md", "**/obj/**", "**/includes/**", "**/_data/**", @@ -23,7 +27,8 @@ }, { "files": [ - "artifacts/nuget/bootstrap-nuget.md" + "artifacts/nuget/bootstrap-nuget.md", + "pipelines/apps/cd/deploy-linuxvm-deploygroups.md" ], "exclude": [ "**/obj/**", @@ -57,10 +62,9 @@ "overwrite": [], "externalReference": [], "globalMetadata": { - "feedback_system": "GitHub", - "feedback_github_repo": "MicrosoftDocs/azure-devops-docs", + "feedback_system": "Standard", "feedback_product_url": "https://developercommunity.visualstudio.com/AzureDevOps", - "breadcrumb_path": "/azure/devops/breadcrumb/toc.json", + "breadcrumb_path": "/azure/devops/breadcrumb/toc.json", "uhfHeaderId": "MSDocsHeader-AzureDevOps", "archive_url": "https://docs.microsoft.com/en-us/previous-versions/azure/devops/all/", "ms.topic": "conceptual", @@ -70,7 +74,7 @@ "ms.date": "09/05/2018", "ms.service": "azure-devops", "ms.version": "ALM", - "zone_pivot_group_filename": "zone-pivot-groups.json", + "zone_pivot_group_filename": "devops/zone-pivot-groups.json", "searchScope": [ "Azure DevOps Services" ], @@ -96,6 +100,7 @@ "notifications/**/**.md": "Azure DevOps", "organizations/**/**.md": "Azure DevOps", "pipelines/**/**.md": "Azure Pipelines", + "managed-devops-pools/**/**.md": "Managed DevOps Pools", "project/**/**.md": "Azure DevOps", "reference/**/**.md": "Azure DevOps", "report/**/**.md": "Azure DevOps", @@ -106,10 +111,12 @@ "user-guide/**/**.md": "Azure DevOps" }, "monikerRange": { - "report/extend-analytics/**": ">= azure-devops-2019" + "report/extend-analytics/**": ">= azure-devops-2019", + "managed-devops-pools/**": "=azure-devops" }, "ms.author": { "artifacts/**": "rabououn", + "managed-devops-pools/**": "sdanie", "pipelines/*.md": "sdanie", "pipelines/agents/**": "sdanie", "pipelines/apps/**": "jukullam", @@ -134,14 +141,16 @@ "pipelines/security/**": "jukullam", "pipelines/targets/**": "rabououn", "pipelines/tasks/**": "sdanie", - "pipelines/test/**": "sdanie", + "pipelines/test/**": "jeom", "service-hooks/**": "aaronha", "repos/tfvc/**": "vijayma", "repos/get-started/**": "vijayma", - "repos/git/**": "vijayma" + "repos/git/**": "vijayma", + "test/**": "jeom" }, "author": { "artifacts/**": "ramiMSFT", + "managed-devops-pools/**": "steved0x", "pipelines/*.md": "steved0x", "pipelines/agents/**": "steved0x", "pipelines/apps/**": "juliakm", @@ -165,17 +174,19 @@ "pipelines/security/**": "juliakm", "pipelines/targets/**": "ramiMSFT", "pipelines/tasks/**": "steved0x", - "pipelines/test/**": "steved0x", + "pipelines/test/**": "raviLiftr", "service-hooks/**": "aaronhallberg", "repos/tfvc/**": "MaximMalygin", "repos/get-started/**": "vijayma", - "repos/git/**": "vijayma" + "repos/git/**": "vijayma", + "test/**": "raviLiftr" }, "ms.service": { "pipelines/**": "azure-devops-pipelines", "pipelines/ecosystems/**": "azure-devops" }, "ms.subservice": { + "managed-devops-pools/**": "azure-devops-managed-devops-pools", "pipelines/agents/**": "azure-devops-pipelines-agents", "pipelines/apps/**": "azure-devops-pipelines-apps", "pipelines/artifacts/**": "azure-devops-pipelines-artifacts", @@ -206,7 +217,7 @@ "repos/tfvc/**": "true", "repos/get-started/**": "true", "repos/git/**": "true" - }, + }, "exclude_monikers": { "reference/error/**/*.md": [ "azure-devops" @@ -214,52 +225,62 @@ "boards/backlogs/**/*.md": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "boards/boards/**/*.md": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "boards/plans/**/*.md": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "boards/queries/**/*.md": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "boards/sprints/**/*.md": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "boards/work-items/**/*.md": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "boards/best-practices-agile-project-management.md": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "boards/configure-customize.md": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "boards/faqs.yml": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "boards/index.yml": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "get-started/**/*.md": [ "tfs-2013", @@ -289,7 +310,8 @@ "reference/index.yml": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "organizations/security/**/*.md": [ "tfs-2013", @@ -350,12 +372,14 @@ "project/index.yml": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "project/work-across-projects-faqs.yml": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "report/dashboards/**/*.md": [ "tfs-2013", @@ -370,7 +394,8 @@ "repos/index.yml": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "repos/get-started/**/*.md": [ "tfs-2013", @@ -380,7 +405,8 @@ "user-guide/**/*.md": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "user-guide/**/*.yml": [ "tfs-2013", @@ -389,38 +415,45 @@ ], "boards/get-started/**/*.md": [ "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "marketplace/**/*.md": [ "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "marketplace/**/*.yml": [ "tfs-2015", "tfs-2017" ], "marketplace-extensibility/index.yml": [ - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "organizations/accounts/**/*.md": [ "tfs-2017" ], "organizations/index.yml": [ "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "pipelines/**/*.md": [ "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "pipelines/index.yml": [ "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "report/index.yml": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "repos/git/**/*.md": [ "tfs-2015", @@ -428,7 +461,8 @@ ], "test/**/*.md": [ "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "test/**/*.yml": [ "tfs-2015", @@ -437,33 +471,455 @@ "index.yml": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "artifacts/**/*.md": [ - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "artifacts/**/*.yml": [ "tfs-2017" ], "extend/**/*.md": [ - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "integrate/**/*.md": [ - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "service-hooks/**/*.md": [ + "tfs-2017", + "tfs-2018" + ], + "cross-service/media/**/*.md": [ + "tfs-2018" + ], + "cross-service/cross-service-overview.md": [ + "tfs-2018" + ], + "cross-service/end-to-end-traceability.md": [ + "tfs-2018" + ], + "cross-service/github-integration.md": [ + "tfs-2018" + ], + "cross-service/index.yml": [ + "tfs-2018" + ], + "cross-service/manage-change.md": [ + "tfs-2018" + ], + "cross-service/manage-requirements.md": [ + "tfs-2018" + ], + "get-started/index.yml": [ + "tfs-2018" + ], + "migrate/media/**/*.md": [ + "tfs-2018" + ], + "migrate/faqs.yml": [ + "tfs-2018" + ], + "migrate/migrate-from-tfs.md": [ + "tfs-2018" + ], + "migrate/migration-import-large-collections.md": [ + "tfs-2018" + ], + "migrate/migration-import.md": [ + "tfs-2018" + ], + "migrate/migration-overview.md": [ + "tfs-2018" + ], + "migrate/migration-post-import.md": [ + "tfs-2018" + ], + "migrate/migration-processtemplates.md": [ + "tfs-2018" + ], + "migrate/migration-restricting-access-to-azure-devops-services.md": [ + "tfs-2018" + ], + "migrate/migration-troubleshooting.md": [ + "tfs-2018" + ], + "migrate/phase-rollout-with-rings.md": [ + "tfs-2018" + ], + "organizations/settings/work/faqs.yml": [ + "tfs-2018" + ], + "organizations/accounts/faq-azure-access.yml": [ + "tfs-2018" + ], + "organizations/accounts/faq-configure-customize-organization.yml": [ + "tfs-2018" + ], + "organizations/accounts/faq-set-up-vs.yml": [ + "tfs-2018" + ], + "organizations/accounts/faq-user-and-permissions-management.yml": [ + "tfs-2018" + ], + "organizations/billing/billing-faq.yml": [ + "tfs-2018" + ], + "organizations/notifications/faq-notifications.yml": [ + "tfs-2018" + ], + "organizations/security/faq-github-authentication.yml": [ + "tfs-2018" + ], + "organizations/security/faq-permissions.yml": [ + "tfs-2018" + ], + "organizations/security/index.yml": [ + "tfs-2018" + ], + "organizations/**/*.md": [ + "tfs-2018" + ], + "project/**/*.md": [ + "tfs-2018" + ], + "reference/mapping/**/*.md": [ + "tfs-2018" + ], + "reference/media/**/*.md": [ + "tfs-2018" + ], + "reference/process-templates/**/*.md": [ + "tfs-2018" + ], + "reference/witadmin/**/*.md": [ + "tfs-2018" + ], + "reference/xml/**/*.md": [ + "tfs-2018" + ], + "reference/add-modify-field.md": [ + "tfs-2018" + ], + "reference/add-modify-wit.md": [ + "tfs-2018" + ], + "reference/add-portfolio-backlogs.md": [ + "tfs-2018" + ], + "reference/add-wits-to-backlogs-and-boards.md": [ + "tfs-2018" + ], + "reference/customize-wit-form.md": [ + "tfs-2018" + ], + "reference/customize-work.md": [ + "tfs-2018" + ], + "reference/on-premises-xml-process-model.md": [ + "tfs-2018" + ], + "reference/quick-reference-index-boards-settings.md": [ + "tfs-2018" + ], + "report/dashboards/faqs.yml": [ + "tfs-2018" + ], + "report/**/*.md": [ + "tfs-2018" + ], + "repos/git/howto.yml": [ + "tfs-2018" + ], + "repos/git/index.yml": [ + "tfs-2018" + ], + "repos/tfvc/index.yml": [ + "tfs-2018" + ], + "repos/**/*.md": [ + "tfs-2018" + ], + "test/index.yml": [ + "tfs-2018" + ], + "test/reference-qa.yml": [ "tfs-2017" + ], + "boards/backlogs/office/media/**/*.md": [ + "tfs-2018" + ], + "boards/backlogs/office/bulk-add-modify-work-items-excel.md": [ + "tfs-2018" + ], + "boards/backlogs/office/faqs.yml": [ + "tfs-2018" + ], + "boards/backlogs/office/resolve-excel-data-conflicts-publish-refresh.md": [ + "tfs-2018" + ], + "boards/backlogs/office/resolve-excel-data-validation-errors.md": [ + "tfs-2018" + ], + "boards/backlogs/office/tfs-office-integration-issues.md": [ + "tfs-2018" + ], + "boards/backlogs/office/track-work.md": [ + "tfs-2018" + ], + "boards/backlogs/add-link.md": [ + "tfs-2018" + ], + "boards/backlogs/add-work-items.md": [ + "tfs-2018" + ], + "boards/backlogs/automate-work-item-state-transitions.md": [ + "tfs-2018" + ], + "boards/backlogs/backlogs-overview.md": [ + "tfs-2018" + ], + "boards/backlogs/bulk-modify-work-items.md": [ + "tfs-2018" + ], + "boards/backlogs/configure-your-backlog-view.md": [ + "tfs-2018" + ], + "boards/backlogs/connect-work-items-to-git-dev-ops.md": [ + "tfs-2018" + ], + "boards/backlogs/copy-clone-work-items.md": [ + "tfs-2018" + ], + "boards/backlogs/create-your-backlog.md": [ + "tfs-2018" + ], + "boards/backlogs/define-features-epics.md": [ + "tfs-2018" + ], + "boards/backlogs/delete-test-artifacts.md": [ + "tfs-2018" + ], + "boards/backlogs/display-rollup.md": [ + "tfs-2018" + ], + "boards/backlogs/filter-backlogs-boards-plans.md": [ + "tfs-2018" + ], + "boards/backlogs/manage-bugs.md": [ + "tfs-2018" + ], + "boards/backlogs/manage-issues-impediments.md": [ + "tfs-2018" + ], + "boards/backlogs/move-change-type.md": [ + "tfs-2018" + ], + "boards/backlogs/organize-backlog.md": [ + "tfs-2018" + ], + "boards/backlogs/remove-delete-work-items.md": [ + "tfs-2018" + ], + "boards/backlogs/resolve-backlog-reorder-issues.md": [ + "tfs-2018" + ], + "boards/backlogs/set-column-options.md": [ + "tfs-2018" + ], + "boards/backlogs/set-up-your-backlog.md": [ + "tfs-2018" + ], + "boards/backlogs/work-item-template.md": [ + "tfs-2018" + ], + "boards/boards/add-columns.md": [ + "tfs-2018" + ], + "boards/boards/add-run-update-tests.md": [ + "tfs-2018" + ], + "boards/boards/add-task-checklists.md": [ + "tfs-2018" + ], + "boards/boards/customize-cards.md": [ + "tfs-2018" + ], + "boards/boards/expedite-work.md": [ + "tfs-2018" + ], + "boards/boards/kanban-epics-features-stories.md": [ + "tfs-2018" + ], + "boards/boards/kanban-overview.md": [ + "tfs-2018" + ], + "boards/boards/kanban-quickstart.md": [ + "tfs-2018" + ], + "boards/boards/wip-limits.md": [ + "tfs-2018" + ], + "boards/extensions/**/*.md": [ + "tfs-2018" + ], + "boards/github/**/*.md": [ + "tfs-2018" + ], + "boards/plans/media/**/*.md": [ + "tfs-2018" + ], + "boards/plans/add-edit-delivery-plan.md": [ + "tfs-2018" + ], + "boards/plans/agile-culture.md": [ + "tfs-2018" + ], + "boards/plans/configure-hierarchical-teams.md": [ + "tfs-2018" + ], + "boards/plans/faqs.yml": [ + "tfs-2018" + ], + "boards/plans/index.md": [ + "tfs-2018" + ], + "boards/plans/portfolio-management.md": [ + "tfs-2018" + ], + "boards/plans/practices-that-scale.md": [ + "tfs-2018" + ], + "boards/plans/review-team-plans.md": [ + "tfs-2018" + ], + "boards/plans/safe-concepts.md": [ + "tfs-2018" + ], + "boards/plans/safe-configure-boards.md": [ + "tfs-2018" + ], + "boards/plans/safe-customize.md": [ + "tfs-2018" + ], + "boards/plans/safe-plan-track-boards.md": [ + "tfs-2018" + ], + "boards/plans/safe-review-roadmaps-progress.md": [ + "tfs-2018" + ], + "boards/plans/scaled-agile-framework.md": [ + "tfs-2018" + ], + "boards/plans/track-dependencies.md": [ + "tfs-2018" + ], + "boards/plans/visibility-across-teams.md": [ + "tfs-2018" + ], + "boards/integrations/**/*.md": [ + "tfs-2018" + ], + "boards/queries/media/**/*.md": [ + "tfs-2018" + ], + "boards/queries/about-managed-queries.md": [ + "tfs-2018" + ], + "boards/queries/add-tags-to-work-items.md": [ + "tfs-2018" + ], + "boards/queries/build-test-integration.md": [ + "tfs-2018" + ], + "boards/queries/example-query-charts.md": [ + "tfs-2018" + ], + "boards/queries/history-and-auditing.md": [ + "tfs-2018" + ], + "boards/queries/import-work-items-from-csv.md": [ + "tfs-2018" + ], + "boards/queries/link-type-reference.md": [ + "tfs-2018" + ], + "boards/queries/linking-attachments.md": [ + "tfs-2018" + ], + "boards/queries/organize-queries.md": [ + "tfs-2018" + ], + "boards/queries/planning-ranking-priorities.md": [ + "tfs-2018" + ], + "boards/queries/query-by-area-iteration-path.md": [ + "tfs-2018" + ], + "boards/queries/query-by-date-or-current-iteration.md": [ + "tfs-2018" + ], + "boards/queries/query-by-workflow-changes.md": [ + "tfs-2018" + ], + "boards/queries/query-faqs.yml": [ + "tfs-2018" + ], + "boards/queries/query-field-value.md": [ + "tfs-2018" + ], + "boards/queries/query-index-quick-ref.md": [ + "tfs-2018" + ], + "boards/queries/query-numeric.md": [ + "tfs-2018" + ], + "boards/queries/query-operators-variables.md": [ + "tfs-2018" + ], + "boards/queries/search-box-queries.md": [ + "tfs-2018" + ], + "boards/queries/set-query-permissions.md": [ + "tfs-2018" + ], + "boards/queries/titles-ids-descriptions.md": [ + "tfs-2018" + ], + "boards/queries/using-queries.md": [ + "tfs-2018" + ], + "boards/queries/view-run-query.md": [ + "tfs-2018" + ], + "boards/queries/wiql-syntax.md": [ + "tfs-2018" + ], + "boards/includes/**/*.md": [ + "tfs-2018" + ], + "boards/media/**/*.md": [ + "tfs-2018" + ], + "artifacts/index.yml": [ + "tfs-2018" + ], + "**/*.md": [ + "azure-devops-2019" ] } }, "template": [], - "dest": "team-services", "markdownEngineName": "markdig", "groups": { "all": { "dest": "all", - "moniker_range": "azure-devops || tfs-2018 || >= azure-devops-2019 <= azure-devops-2022" + "moniker_range": "azure-devops || >= azure-devops-2020 <= azure-devops-2022" } - } + }, + "dest": "team-services" } -} +} \ No newline at end of file diff --git a/docs/extend/develop/add-action.md b/docs/extend/develop/add-action.md index 79197c6c3ee..8db8121bc14 100644 --- a/docs/extend/develop/add-action.md +++ b/docs/extend/develop/add-action.md @@ -19,10 +19,10 @@ In this example, we add an action to the query context menu in the work item que [!INCLUDE [extension-docs-new-sdk](../../includes/extension-docs-new-sdk.md)] -## Prerequisites for this article +## Prerequisites -- You need to create a web app for your action, which can be found in the [hub example](./add-hub.md). -- If you haven't, take a look at the [write your first extension tutorial](../get-started/node.md) to learn about the basics. +- [Develop a web extension](../get-started/node.md). +- [Create a web app for your action](./add-hub.md). ## Update extension manifest file diff --git a/docs/extend/develop/add-backlog-panel.md b/docs/extend/develop/add-backlog-panel.md index 5c9d437eb9a..634b2fa99f4 100644 --- a/docs/extend/develop/add-backlog-panel.md +++ b/docs/extend/develop/add-backlog-panel.md @@ -7,7 +7,7 @@ ms.topic: conceptual monikerRange: 'azure-devops' ms.author: chcomley author: chcomley -ms.date: 08/22/2016 +ms.date: 02/21/2025 --- # Add panels on backlog pages @@ -31,11 +31,12 @@ The custom panel opens in the same space that the mapping panel opens if it were There are three types of backlogs that can be targets for panel extensions: Portfolio backlogs, Product backlogs, and Iteration backlogs. For the Agile template, this breakdown is as below. This is representative of Scrum and CMMI as well. For custom templates, please consult your process to see which backlogs are requirement or portfolio category. - -![backlog panel contribution point breakdown](media/add-panel-show-three-types.png) +| Backlog Category | Contribution point | +|--------------------|--------------------| +| Portfolio (Epic, Feature) | ms.vss-work-web.portfolio-backlog-toolpane | +| Requirements (User Story, Product Backlog Item) | ms.vss-work-web.requirement-backlog-toolpane | +| Sprint Backlog | ms.vss-work-web.iteration-backlog-toolpane | For more information, see the [Azure DevOps Services Extension Sample](https://github.com/Microsoft/azure-devops-extension-sample). @@ -81,7 +82,7 @@ For each contribution in your extension, the manifest defines | title | Tooltip text that appears on the menu item | | name | What appears in the dropdown for panel selection | | uri | Path (relative to the extension's base URI) of the page to surface as the panel | -| registeredObjectId | Id of the object registered for the panel | +| registeredObjectId | ID of the object registered for the panel | Learn about all of the places where you can add an extension in [Extensibility points](../reference/targets/overview.md). diff --git a/docs/extend/develop/add-build-task.md b/docs/extend/develop/add-build-task.md index ad39076b91f..0e36508128e 100644 --- a/docs/extend/develop/add-build-task.md +++ b/docs/extend/develop/add-build-task.md @@ -1,128 +1,128 @@ --- -title: Add a build or release task in an extension -description: Add a custom build or release task in an extension for Azure DevOps. +title: Add a Custom Build or Release Task in an Extension +description: Learn how to add a custom build or release task in an extension for Azure DevOps. ms.assetid: 98821825-da46-498e-9b01-64d3a8c78ea0 ms.subservice: azure-devops-ecosystem ms.custom: freshness-fy22q3 ms.topic: how-to +ai-usage: ai-assisted monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -date: 12/27/2022 +date: 04/16/2025 --- # Add a custom pipelines task extension [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Learn how to install extensions to your organization for custom build or release tasks in Azure DevOps. - -For more information about the new cross-platform build/release system, see [What is Azure Pipelines?](../../pipelines/get-started/what-is-azure-pipelines.md). +This article explains how to install extensions to your organization for custom build or release tasks in Azure DevOps. For more information, see [What is Azure Pipelines?](../../pipelines/get-started/what-is-azure-pipelines.md) > [!NOTE] -> This article covers agent tasks in agent-based extensions. For information on server tasks/server-based extensions, check out the [Server Task GitHub Documentation](https://github.com/Microsoft/azure-pipelines-tasks/blob/master/docs/authoring/servertaskauthoring.md). +> This article covers agent tasks in agent-based extensions. For more information on server tasks and server-based extensions, see the [Server Task Authoring](https://github.com/Microsoft/azure-pipelines-tasks/blob/master/docs/authoring/servertaskauthoring.md). ## Prerequisites -To create extensions for Azure DevOps, you need the following software and tools. - -- An organization in Azure DevOps. For more information, see [Create an organization](../../organizations/accounts/create-organization.md). -- A text editor. For many of the tutorials, we use **Visual Studio Code**, which provides intellisense and debugging support. Go to [code.visualstudio.com](https://code.visualstudio.com/) to download the latest version. -- The [latest version](https://nodejs.org/en/download/) of Node.js. -- TypeScript Compiler 2.2.0 or greater, although we recommend version 4.0.2 or newer. Go to [npmjs.com](https://www.npmjs.com/package/typescript) to download the compiler. - -- [Cross-platform CLI for Azure DevOps](https://github.com/microsoft/tfs-cli) to package your extensions. - You can install **tfx-cli** by using `npm`, a component of Node.js, by running `npm i -g tfx-cli`. -- A `home` directory for your project. - The `home` directory of a build or release task extension should look like the following example after you complete the steps in this tutorial: - - ``` - |--- README.md - |--- images - |--- extension-icon.png - |--- buildandreleasetask // where your task scripts are placed - |--- vss-extension.json // extension's manifest - ``` +- An organization in Azure DevOps. [Create an organization](../../organizations/accounts/create-organization.md). +- A text editor. For many tutorials, we use [Visual Studio Code](https://code.visualstudio.com), which provides intellisense and debugging support. +- The latest version of [Node.js](https://nodejs.org/en/download/). +- npmjs.com 4.0.2 or newer. Install the [latest version](https://www.npmjs.com/package/typescript) of this TypeScript compiler. +- [Cross-platform CLI for Azure DevOps (tfx-cli)](https://github.com/microsoft/tfs-cli) to package your extensions. + - tfx-cli can be installed using `npm`, a component of Node.js, by running `npm i -g tfx-cli`. +- Azure DevOps extension SDK. Install the [azure-devops-extension-sdk](https://github.com/Microsoft/azure-devops-extension-sdk) package. +- A `home` directory for your project. The `home` directory of a build or release task extension should have the following structure after you complete the steps in this article: -- The [azure-devops-extension-sdk package installation](https://github.com/Microsoft/azure-devops-extension-sdk). + ``` + |--- README.md + |--- images + |--- extension-icon.png + |--- buildandreleasetask // where your task scripts are placed + |--- vss-extension.json // extension's manifest + ``` > [!IMPORTANT] -> The dev machine needs to run the [latest version of Node](https://nodejs.org/en/download/) to ensure that the written code is compatible with the production environment on the agent and the latest non-preview version of azure-pipelines-task-lib. +> The dev machine must run the [latest version of Node](https://nodejs.org/en/download/) to ensure that the written code is compatible with the production environment on the agent and the latest non-preview version of `azure-pipelines-task-lib`. Update your `task.json` file as per the following command: +>``` +>"execution": { +> "Node20_1": { +> "target": "index.js" +> } +> } +>``` ## 1. Create a custom task -Do every part of [1. Create a custom task](#1-create-a-custom-task) within the `buildandreleasetask` folder. +Do every part of this procedure within the `buildandreleasetask` folder inside your `home` directory. > [!NOTE] -> This example walk-through is on Windows with PowerShell. We made it generic for all platforms, but the syntax for getting environment variables is different. If you're using a Mac or Linux, replace any instances of `$env:=` with `export =`. +> This example walkthrough uses Windows with PowerShell. The steps are generic for all platforms, but the syntax for getting environment variables is different. If you're using a Mac or Linux, replace any instances of `$env:=` with `export =`. ### Create task scaffolding 1. Create the folder structure for the task and install the required libraries and dependencies. -2. From within your `buildandreleasetask` folder, run the following command. - ``` +1. Open a PowerShell command window, go to your `buildandreleasetask` folder, and run the following command. + + ```powershell npm init --yes ``` `npm init` creates the `package.json` file. We added the `--yes` parameter to accept all of the default `npm init` options. > [!TIP] - > The agent doesn't automatically install the required modules because it's expecting your task folder to include the node modules. To mitigate this, copy the `node_modules` to `buildandreleasetask`. As your task gets bigger, it's easy to exceed the size limit (50MB) of a VSIX file. Before you copy the node folder, you may want to run `npm install --production` or `npm prune --production`, or you can write a script to build and pack everything. + > The agent doesn't automatically install the required modules because it's expecting your task folder to include the node modules. To mitigate, copy the `node_modules` to `buildandreleasetask`. As your task gets bigger, it's easy to exceed the size limit (50 MB) of a VSIX file. Before you copy the node folder, you might want to run `npm install --production` or `npm prune --production`, or you can write a script to build and pack everything. -3. Add `azure-pipelines-task-lib` to your library. +1. Add `azure-pipelines-task-lib` to your library. - ``` + ```powershell npm install azure-pipelines-task-lib --save ``` -4. Ensure that TypeScript typings are installed for external dependencies. +1. Ensure that TypeScript typings are installed for external dependencies. - ``` + ```powershell npm install @types/node --save-dev npm install @types/q --save-dev ``` -5. Create a `.gitignore` file and add node_modules to it. Your build process should do an `npm install` and a `typings install` so that node_modules are built each time and don't need to be checked in. +1. Create a `.gitignore` file and add node_modules to it. Your build process should do an `npm install` and a `typings install` so that node_modules are built each time and don't need to be checked in. - ``` + ```powershell echo node_modules > .gitignore ``` -6. Install [Mocha](https://mochajs.org/) as a development dependency. +1. Install [Mocha](https://mochajs.org) as a development dependency. - ``` + ```powershell npm install mocha --save-dev -g npm install sync-request --save-dev npm install @types/mocha --save-dev ``` -7. Choose TypeScript version 2.3.4 or 4.6.3. +1. Choose TypeScript version 2.3.4 or 4.6.3. - ``` + ```powershell npm install typescript@4.6.3 -g --save-dev ``` > [!NOTE] - > To have the `tsc` command available, make sure that TypeScript is installed globally with npm in your development environment. If you skip this step, TypeScript version 2.3.4 gets used by default, and you still have to install the package globally to have the `tsc` command available. + > Make sure that TypeScript is installed globally with `npm` in your development environment, so the `tsc` command is available. If you skip this step, TypeScript version 2.3.4 gets used by default, and you still have to install the package globally to have the `tsc` command available. -8. Create `tsconfig.json` compiler options. This file ensures that your TypeScript files are compiled to JavaScript files. +1. Create `tsconfig.json` compiler options. This file ensures that your TypeScript files are compiled to JavaScript files. - ``` - tsc --init --target es6 + ```powershell + tsc --init --target es2022 ``` - To ensure the ES6 (rather than ES5) standard is used, we added the `--target es6` parameter. +### Create task -### Create custom task - -Now that the scaffolding is complete, we can create our custom task. +Now that the scaffolding is complete, you can create your custom task. 1. Create a `task.json` file in the `buildandreleasetask` folder. The `task.json` file describes the build/release task and is what the build/release system uses to render configuration options to the user and to know which scripts to execute at build/release time. -2. Copy the following code and replace the `{{placeholders}}` with your task's information. The most important placeholder is the `taskguid`, and it must be unique. +1. Copy the following code and replace the `{{placeholders}}` with your task's information. The most important placeholder is the `taskguid`, and it must be unique. ```json { @@ -151,113 +151,114 @@ Now that the scaffolding is complete, we can create our custom task. } ], "execution": { - "Node": { + "Node20_1": { "target": "index.js" } } } ``` -**task.json components** +1. Create an `index.ts` file by using the following code as a reference. This code runs when the task gets called. + + ```typescript + import tl = require('azure-pipelines-task-lib/task'); + + async function run() { + try { + const inputString: string | undefined = tl.getInput('samplestring', true); + if (inputString == 'bad') { + tl.setResult(tl.TaskResult.Failed, 'Bad input was given'); + return; + } + console.log('Hello', inputString); + } + catch (err:any) { + tl.setResult(tl.TaskResult.Failed, err.message); + } + } + + run(); + ``` + +1. To compile an `index.js` file from `index.ts`, enter `tsc` from the `buildandreleasetask` folder. + +#### task.json components See the following descriptions of some of the components of the `task.json` file. -| Property | Description | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| `id` | A unique GUID for your task. | -| `name` | Name with no spaces. | -| `friendlyName` | Descriptive name (spaces allowed). | -| `description` | Detailed description of what your task does. | -| `author` | Short string describing the entity developing the build or release task, for example: "Microsoft Corporation." | +| Property | Description | +| -------------------- | ------------------------- | +| `id` | A unique GUID for your task. | +| `name` | Name with no spaces. | +| `friendlyName` | Descriptive name (spaces allowed). | +| `description` | Detailed description of what your task does. | +| `author` | Short string describing the entity developing the build or release task, for example: *Microsoft Corporation* | | `instanceNameFormat` | How the task displays within the build/release step list. You can use variable values by using **$(variablename)**. | -| `groups` | Describes groups that task properties may be logically grouped by in the UI. | -| `inputs` | Inputs to be used when your build or release task runs. This task expects an input with the name **samplestring**. | -| `execution` | Execution options for this task, including scripts. -| `restrictions` | Restrictions being applied to the task about [GitHub Codespaces commands](../../pipelines/scripts/logging-commands.md) task can call, and variables task can set. We recommend that you specify restriction mode for new tasks.| +| `groups` | Describes the logical grouping of task properties in the UI. | +| `inputs` | Inputs to be used when your build or release task runs. This task expects an input with the name **samplestring**. | +| `execution` | There are multiple execution options for this task, including scripts, like `Node`, `PowerShell`, `PowerShell3`, or `Process`. | +| `restrictions` | Restrictions being applied to the task about [GitHub Codespaces commands](../../pipelines/scripts/logging-commands.md) that the task can call, and variables that the task can set. We recommend that you specify restriction mode for new tasks.| > [!NOTE] -> You can create an `id` with the following command in PowerShell: +> Create an `id` with the following command in PowerShell: > ```powershell > (New-Guid).Guid > ``` +> For more information, see the [Build/release task reference](./integrate-build-task.md). -> [!NOTE] -> For a more in-depth look into the task.json file, or to learn how to bundle multiple versions in your extension, see the **[Build/release task reference](./integrate-build-task.md)**. - -3. Create an `index.ts` file by using the following code as a reference. This code runs when the task gets called. +### Run the task -```typescript -import tl = require('azure-pipelines-task-lib/task'); +Run the task by using `node index.js` from PowerShell. -async function run() { - try { - const inputString: string | undefined = tl.getInput('samplestring', true); - if (inputString == 'bad') { - tl.setResult(tl.TaskResult.Failed, 'Bad input was given'); - return; - } - console.log('Hello', inputString); - } - catch (err) { - tl.setResult(tl.TaskResult.Failed, err.message); - } -} +In the following example, the task fails because inputs weren't supplied (`samplestring` is a required input). -run(); +```output + node index.js + ##vso[task.debug]agent.workFolder=undefined + ##vso[task.debug]loading inputs and endpoints + ##vso[task.debug]loaded 0 + ##vso[task.debug]task result: Failed + ##vso[task.issue type=error;]Input required: samplestring + ##vso[task.complete result=Failed;]Input required: samplestring ``` -4. Enter "tsc" from the `buildandreleasetask` folder to compile an `index.js` file from `index.ts`. - -### Run the task - -1. Run the task with `node index.js` from PowerShell. - - In the following example, the task fails because inputs weren't supplied (`samplestring` is a required input). - - ``` - node index.js - ##vso[task.debug]agent.workFolder=undefined - ##vso[task.debug]loading inputs and endpoints - ##vso[task.debug]loaded 0 - ##vso[task.debug]task result: Failed - ##vso[task.issue type=error;]Input required: samplestring - ##vso[task.complete result=Failed;]Input required: samplestring - ``` - - As a fix, we can set the `samplestring` input and run the task again. +As a fix, set the `samplestring` input and run the task again. + +```output +$env:INPUT_SAMPLESTRING="Human" +node index.js +##vso[task.debug]agent.workFolder=undefined +##vso[task.debug]loading inputs and endpoints +##vso[task.debug]loading INPUT_SAMPLESTRING +##vso[task.debug]loaded 1 +##vso[task.debug]Agent.ProxyUrl=undefined +##vso[task.debug]Agent.CAInfo=undefined +##vso[task.debug]Agent.ClientCert=undefined +##vso[task.debug]Agent.SkipCertValidation=undefined +##vso[task.debug]samplestring=Human +Hello Human +``` - ``` - $env:INPUT_SAMPLESTRING="Human" - node index.js - ##vso[task.debug]agent.workFolder=undefined - ##vso[task.debug]loading inputs and endpoints - ##vso[task.debug]loading INPUT_SAMPLESTRING - ##vso[task.debug]loaded 1 - ##vso[task.debug]Agent.ProxyUrl=undefined - ##vso[task.debug]Agent.CAInfo=undefined - ##vso[task.debug]Agent.ClientCert=undefined - ##vso[task.debug]Agent.SkipCertValidation=undefined - ##vso[task.debug]samplestring=Human - Hello Human - ``` +This time, the task succeeds because `samplestring` was supplied, and it correctly outputs *Hello Human!* -This time, the task succeeded because `samplestring` was supplied and it correctly outputted "Hello Human"! +> [!TIP] +> For information about various task runners and how to include the latest node version in the `task.json`, see [Node runner update guidance for Azure Pipelines task authors](https://devblogs.microsoft.com/devops/node-runner-update-guidance-for-azure-pipelines-task-authors/#upcoming-changes). ## 2. Unit test your task scripts -We unit test to quickly test the task script, and not the external tools that it's calling. We want to test all aspects of both success and failure paths. +Do unit tests to quickly test the task script, and not the external tools that it calls. Test all aspects of both success and failure paths. -1. Install test tools. We use [Mocha](https://mochajs.org/) as the test driver in this walk through. +1. Install test tools. We use [Mocha](https://mochajs.org/) as the test driver in this procedure. - ``` + ```powershell npm install mocha --save-dev -g npm install sync-request --save-dev npm install @types/mocha --save-dev ``` -2. Create a `tests` folder containing a `_suite.ts` file with the following contents: +1. Create a `tests` folder containing a `_suite.ts` file with the following contents: ```typescript import * as path from 'path'; @@ -285,10 +286,10 @@ We unit test to quickly test the task script, and not the external tools that it ``` > [!TIP] - > Your test folder should be located in the buildandreleasetask folder. If you get a sync-request error, you can work around it by adding sync-request to the buildandreleasetask folder with the command + > Your test folder should be located in the `buildandreleasetask` folder. If you get a sync-request error, you can work around it by adding sync-request to the `buildandreleasetask` folder with the command > `npm i --save-dev sync-request`. -3. Create a `success.ts` file in your test directory with the following contents. This file creation simulates running the task and mocks all calls to outside methods. +1. Create a `success.ts` file in your test directory with the following contents. This file creation simulates running the task and mocks all calls to outside methods. ```typescript import ma = require('azure-pipelines-task-lib/mock-answer'); @@ -303,30 +304,33 @@ We unit test to quickly test the task script, and not the external tools that it tmr.run(); ``` - The success test validates that with the appropriate inputs, it succeeds with no errors or warnings and returns the correct output. - + The success test validates that, with the appropriate inputs, it succeeds with no errors or warnings and returns the correct output. -4. Add the following example success test to your `_suite.ts` file to run the task mock runner. +1. To run the task mock runner, add the following example success test to your `_suite.ts` file. - ```typescript - it('should succeed with simple inputs', function(done: Mocha.Done) { + ```typescript + it('should succeed with simple inputs', function(done: Mocha.Done) { this.timeout(1000); - - let tp = path.join(__dirname, 'success.js'); + + let tp: string = path.join(__dirname, 'success.js'); let tr: ttm.MockTestRunner = new ttm.MockTestRunner(tp); - - tr.run(); - console.log(tr.succeeded); - assert.equal(tr.succeeded, true, 'should have succeeded'); - assert.equal(tr.warningIssues.length, 0, "should have no warnings"); - assert.equal(tr.errorIssues.length, 0, "should have no errors"); - console.log(tr.stdout); - assert.equal(tr.stdout.indexOf('Hello human') >= 0, true, "should display Hello human"); - done(); + + // tr.run(); //current, old function. + tr.runAsync().then(() => { + console.log(tr.succeeded); + assert.equal(tr.succeeded, true, 'should have succeeded'); + assert.equal(tr.warningIssues.length, 0, "should have no warnings"); + assert.equal(tr.errorIssues.length, 0, "should have no errors"); + console.log(tr.stdout); + assert.equal(tr.stdout.indexOf('Hello human') >= 0, true, "should display Hello human"); + done(); + }).catch((error) => { + done(error); // Ensure the test case fails if there's an error + }); }); - ``` + ``` -5. Create a `failure.ts` file in your test directory as your task mock runner with the following contents: +1. Create a `failure.ts` file in your test directory as your task mock runner with the following contents: ```typescript import ma = require('azure-pipelines-task-lib/mock-answer'); @@ -341,39 +345,39 @@ We unit test to quickly test the task script, and not the external tools that it tmr.run(); ``` - The failure test validates that when the tool gets bad or incomplete input, it fails in the expected way with helpful output. + The failure test validates that, when the tool gets bad or incomplete input, it fails in the expected way with helpful output. -6. Add the following code to your `_suite.ts` file to run the task mock runner. +1. To run the task mock runner, add the following code to your `_suite.ts` file. ```typescript - it('it should fail if tool returns 1', function(done: Mocha.Done) { + it('should fail if tool returns 1', function(done: Mocha.Done) { this.timeout(1000); - let tp = path.join(__dirname, 'failure.js'); - let tr: ttm.MockTestRunner = new ttm.MockTestRunner(tp); - - tr.run(); - console.log(tr.succeeded); - assert.equal(tr.succeeded, false, 'should have failed'); - assert.equal(tr.warningIssues.length, 0, "should have no warnings"); - assert.equal(tr.errorIssues.length, 1, "should have 1 error issue"); - assert.equal(tr.errorIssues[0], 'Bad input was given', 'error issue output'); - assert.equal(tr.stdout.indexOf('Hello bad'), -1, "Should not display Hello bad"); + const tp = path.join(__dirname, 'failure.js'); + const tr: ttm.MockTestRunner = new ttm.MockTestRunner(tp); - done(); + tr.runAsync().then(() => { + console.log(tr.succeeded); + assert.equal(tr.succeeded, false, 'should have failed'); + assert.equal(tr.warningIssues.length, 0, 'should have no warnings'); + assert.equal(tr.errorIssues.length, 1, 'should have 1 error issue'); + assert.equal(tr.errorIssues[0], 'Bad input was given', 'error issue output'); + assert.equal(tr.stdout.indexOf('Hello bad'), -1, 'Should not display Hello bad'); + done(); + }); }); ``` -7. Run the tests. +1. Run the tests. - ``` + ```powershell tsc mocha tests/_suite.js ``` Both tests should pass. If you want to run the tests with more verbose output (what you'd see in the build console), set the environment variable: `TASK_TEST_TRACE=1`. - ``` + ```powershell $env:TASK_TEST_TRACE=1 ``` @@ -381,22 +385,24 @@ We unit test to quickly test the task script, and not the external tools that it ## 3. Create the extension manifest file -The extension manifest contains all of the information about your extension. It includes links to your files, including your task folders and images folders. Ensure you've created an images folder with extension-icon.png. The following example is an extension manifest that contains the build or release task. +The extension manifest contains all of the information about your extension. It includes links to your files, including your task folders and images folders. Ensure you created an images folder with `extension-icon.png`. The following example is an extension manifest that contains the build or release task. + +Copy the following .json code and save it as your `vss-extension.json` file in your `home` directory. -1. Copy the following .json code and save it as your `vss-extension.json` file in your `home` directory. **Don't create this file in the buildandreleasetask folder.** +**Don't create this file in the buildandreleasetask folder.** -[!code-javascript[JSON](../_data/extension-build-tasks.json)] +[!Code-javaScript[JSON](../_data/extension-build-tasks.json)] >[!NOTE] ->Change the **publisher** to your publisher name. For more information, see [Create a publisher](#createpublisher). +> Change the **publisher** to your publisher name. For more information, see [Create a publisher](#createpublisher). ### Contributions -| Property | Description | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Property | Description | +| ----------------- | -------------------------------- | | `id` | Identifier of the contribution. Must be unique within the extension. Doesn't need to match the name of the build or release task. Typically the build or release task name is in the ID of the contribution. | -| `type` | Type of the contribution. Should be **ms.vss-distributed-task.task**. | -| `targets` | Contributions "targeted" by this contribution. Should be **ms.vss-distributed-task.tasks**. | +| `type` | Type of the contribution. Should be `ms.vss-distributed-task.task`. | +| `targets` | Contributions *targeted* by this contribution. Should be `ms.vss-distributed-task.tasks`. | | `properties.name` | Name of the task. This name must match the folder name of the corresponding self-contained build or release pipeline task. | ### Files @@ -405,235 +411,217 @@ The extension manifest contains all of the information about your extension. It | -------- | ----------------------------------------------------------- | | `path` | Path of the file or folder relative to the `home` directory. | ->[!NOTE] ->For more information about the **extension manifest file**, such as its properties and what they do, check out the [extension manifest reference](./manifest.md). +For more information about the extension manifest file, such as its properties and what they do, see the [extension manifest reference](./manifest.md). ## 4. Package your extension -After you've written your extension, the next step toward getting it into the Visual Studio Marketplace is to package all of your files together. All extensions are packaged -as VSIX 2.0-compatible .vsix files. Microsoft provides a cross-platform command-line interface (CLI) to package your extension. +Package all of your files together to get your extension into the Visual Studio Marketplace. All extensions are packaged as VSIX 2.0-compatible .vsix files. Microsoft provides a cross-platform command-line interface (CLI) to package your extension. -1. Once you have the [tfx-cli](#cli), go to your extension's home directory, and run the following command: +Once you have the [tfx-cli](#prerequisites), go to your extension's home directory, and run the following command: - ```no-highlight - tfx extension create --manifest-globs vss-extension.json - ``` +```powershell +tfx extension create --manifest-globs vss-extension.json +``` > [!NOTE] > An extension or integration's version must be incremented on every update. > When you're updating an existing extension, either update the version in the manifest or pass the `--rev-version` command line switch. This increments the *patch* version number of your extension and saves the new version to your manifest. > You must rev both the task version and extension version for an update to occur. `tfx extension create --manifest-globs vss-extension.json --rev-version` only updates the extension version and not the task version. For more information, see [Build Task in GitHub](https://github.com/microsoft/tfs-cli/blob/master/docs/buildtasks.md). -After you have your packaged extension in a .vsix file, you're ready to publish your extension to the Marketplace. +Once your packaged extension is in a .vsix file, you're ready to publish your extension to the Marketplace. ## 5. Publish your extension -To publish your extension, you first [create your publisher](#create-your-publisher), then [upload your extension](#upload-your-extension), and finally [share it](#share-your-extension). +To publish your extension, first [create your publisher](#create-your-publisher), then [upload your extension](#upload-your-extension), and finally [share it](#share-your-extension). ### Create your publisher All extensions, including extensions from Microsoft, are identified as being provided by a publisher. -If you aren't already a member of an existing publisher, you'll create one. +If you aren't already a member of an existing publisher, you create one. 1. Sign in to the [Visual Studio Marketplace Publishing Portal](https://marketplace.visualstudio.com/manage). -2. If you aren't already a member of an existing publisher, you're prompted to create a publisher. If you're not prompted to create a publisher, scroll down to the bottom of the page and select **Publish extensions** under **Related Sites**. + +1. If you aren't already a member of an existing publisher, you're prompted to create a publisher. If you're not prompted to create a publisher, scroll down to the bottom of the page and select **Publish extensions** under **Related Sites**. * Specify an identifier for your publisher, for example: `mycompany-myteam`. * This identifier is used as the value for the `publisher` attribute in your extensions' manifest file. * Specify a display name for your publisher, for example: `My Team`. -3. Review the [Marketplace Publisher Agreement](https://aka.ms/vsmarketplace-agreement) and select **Create**. + +1. Review the [Marketplace Publisher Agreement](https://aka.ms/vsmarketplace-agreement) and select **Create**. Your publisher is defined. In a future release, you can grant permissions to view and manage your publisher's extensions. -It's easier and more secure to publish extensions under a common publisher, -without the need to share a set of credentials across users. +It's easier and more secure to publish extensions under a common publisher, without the need to share a set of credentials across users. ### Upload your extension -1. Find the **Upload new extension** button, go to your packaged .vsix file, and select **Upload**. +Find the **Upload new extension** button, go to your packaged .vsix file, and select **Upload**. - You can also upload your extension via the command line by using the `tfx extension publish` command instead of `tfx extension create` to package and publish your extension in one step. - You can optionally use `--share-with` to share your extension with one or more accounts after publishing. You'll need a personal access token, too. For more information, see [Create a personal access token](../publish/command-line.md#create-a-personal-access-token). +1. You can also upload your extension via the command-line interface (CLI) by using the `tfx extension publish` command instead of `tfx extension create` to package and publish your extension in one step. You can optionally use `--share-with` to share your extension with one or more accounts after it gets published. - ```no-highlight + ```powershell tfx extension publish --manifest-globs your-manifest.json --share-with yourOrganization ``` +1. [Create a personal access token (PAT)](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). + - Select the **Marketplace (publish)** scope. This scope limits the token to only being able to publish extensions to the Marketplace. + ### Share your extension -Now that you've uploaded your extension, it's in the Marketplace, but no one can see it. +Now that you uploaded your extension, it's in the Marketplace, but no one can see it. Share it with your organization so that you can install and test it. -1. Right-click your extension and select **Share**, and enter your organization information. You can share it with other accounts that you want to have access to your extension, too. +Right-select your extension and select **Share**, and enter your organization information. You can share it with other accounts that you want to have access to your extension, too. > [!IMPORTANT] -> Publishers must be verified to share extensions publicly. To learn more, see [Package/Publish/Install](../publish/overview.md). +> Publishers must be verified to share extensions publicly. For more information, see [Package/Publish/Install](../publish/overview.md). -Now that your extension is shared in the Marketplace, anyone who wants to use it must install it. +After your extension is shared in the Marketplace, anyone who wants to use it must install it. ## 6. Create a build and release pipeline to publish the extension to Marketplace -Create a build and release pipeline on Azure DevOps to help maintain the custom task on the Marketplace. - -### Prerequisites - -- A project in your organization. For more information, see [Create a project](../../organizations/projects/create-project.md?tabs=preview-page). -- An [Azure DevOps Extension Tasks](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-developer-tools-build-tasks&targetId=85fb3d5a-9f21-420f-8de3-fc80bf29054b&utm_source=vstsproduct&utm_medium=ExtHubManageList) extension installed in your organization. - 1. Go to [Azure DevOps Extension Tasks](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-developer-tools-build-tasks&targetId=85fb3d5a-9f21-420f-8de3-fc80bf29054b&utm_source=vstsproduct&utm_medium=ExtHubManageList) - 2. Choose **Get it free** and install the extension into your organization. - -Create a pipeline library variable group to hold the variables used by the pipeline. For more information about creating a variable group, see [Add and use variable groups](../../pipelines/library/variable-groups.md?tabs=classic). Keep in mind that you can make variable groups from the Azure DevOps Library tab or through the CLI. After a variable group is made, use any variables within that group in your pipeline. Read more on [How to use a variable group](../../pipelines/library/variable-groups.md?tabs=yaml#use-a-variable-group). - -Declare the following variables in the variable group. - -- `publisherId`: ID of your marketplace publisher -- `extensionId`: ID of your extension, as declared in the vss-extension.json file -- `extensionName`: Name of your extension, as declared in the vss-extension.json file -- `artifactName`: Name of the artifact being created for the VSIX file - -Create a new Visual Studio Marketplace service connection and grant access permissions for all pipelines. For more information about creating a service connection, see [Service connections](../../pipelines/library/service-endpoints.md?tabs=yaml). - -![Screenshot that shows the new service connection pane.](media/new-service-connection.png) - -![Screenshot that shows the Visual Studio Marketplace new service connection pane.](media/new-vs-marketplace-service-connection.png) - -:::moniker range=">=azure-devops-2019" - -Use the following example to create a new pipeline with YAML. Learn more about how to [Create your first pipeline](../../pipelines/create-first-pipeline.md?tabs=javascript%2Cyaml%2Cbrowser%2Ctfs-2018-2) and [YAML schema](/azure/devops/pipelines/yaml-schema/). - -```yaml -trigger: -- main - -pool: - vmImage: "ubuntu-latest" - -variables: - - group: variable-group # Rename to whatever you named your variable group in the prerequisite stage of step 6 - -stages: - - stage: Run_and_publish_unit_tests - jobs: - - job: - steps: - - task: TfxInstaller@4 - inputs: - version: "v0.x" - - task: Npm@1 - inputs: - command: 'install' - workingDir: '/TaskDirectory' # Update to the name of the directory of your task - - task: Bash@3 - displayName: Compile Javascript - inputs: - targetType: "inline" - script: | - cd TaskDirectory # Update to the name of the directory of your task - tsc - - task: Npm@1 - inputs: - command: 'custom' - workingDir: '/TestsDirectory' # Update to the name of the directory of your task's tests - customCommand: 'testScript' # See the definition in the explanation section below - it may be called test - - task: PublishTestResults@2 - inputs: - testResultsFormat: 'JUnit' - testResultsFiles: '**/ResultsFile.xml' - - stage: Package_extension_and_publish_build_artifacts - jobs: - - job: - steps: - - task: TfxInstaller@4 - inputs: - version: "0.x" - - task: Npm@1 - inputs: - command: 'install' - workingDir: '/TaskDirectory' # Update to the name of the directory of your task - - task: Bash@3 - displayName: Compile Javascript - inputs: - targetType: "inline" - script: | - cd TaskDirectory # Update to the name of the directory of your task - tsc - - task: QueryAzureDevOpsExtensionVersion@4 - name: QueryVersion - inputs: - connectTo: 'VsTeam' - connectedServiceName: 'ServiceConnection' # Change to whatever you named the service connection - publisherId: '$(PublisherID)' - extensionId: '$(ExtensionID)' - versionAction: 'Patch' - - task: PackageAzureDevOpsExtension@4 - inputs: - rootFolder: '$(System.DefaultWorkingDirectory)' - publisherId: '$(PublisherID)' - extensionId: '$(ExtensionID)' - extensionName: '$(ExtensionName)' - extensionVersion: '$(QueryVersion.Extension.Version)' - updateTasksVersion: true - updateTasksVersionType: 'patch' - extensionVisibility: 'private' # Change to public if you're publishing to the marketplace - extensionPricing: 'free' - - task: CopyFiles@2 - displayName: "Copy Files to: $(Build.ArtifactStagingDirectory)" - inputs: - Contents: "**/*.vsix" - TargetFolder: "$(Build.ArtifactStagingDirectory)" - - task: PublishBuildArtifacts@1 - inputs: - PathtoPublish: '$(Build.ArtifactStagingDirectory)' - ArtifactName: '$(ArtifactName)' - publishLocation: 'Container' - - stage: Download_build_artifacts_and_publish_the_extension - jobs: - - job: - steps: - - task: TfxInstaller@4 - inputs: - version: "v0.x" - - task: DownloadBuildArtifacts@0 - inputs: - buildType: "current" - downloadType: "single" - artifactName: "$(ArtifactName)" - downloadPath: "$(System.DefaultWorkingDirectory)" - - task: PublishAzureDevOpsExtension@4 - inputs: - connectTo: 'VsTeam' - connectedServiceName: 'ServiceConnection' # Change to whatever you named the service connection - fileType: 'vsix' - vsixFile: '$(PublisherID).$(ExtensionName)/$(PublisherID)..vsix' - publisherId: '$(PublisherID)' - extensionId: '$(ExtensionID)' - extensionName: '$(ExtensionName)' - updateTasksVersion: false - extensionVisibility: 'private' # Change to public if you're publishing to the marketplace - extensionPricing: 'free' -``` - -:::moniker-end +To maintain the custom task on the Marketplace, create a build and release pipeline on Azure DevOps. + +### Prerequisites to publish + +- An Azure DevOps project. [Create a project](../../organizations/projects/create-project.md?tabs=preview-page). +- Azure DevOps Extension Tasks extension. [Install it for free](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-developer-tools-build-tasks&targetId=85fb3d5a-9f21-420f-8de3-fc80bf29054b&utm_source=vstsproduct&utm_medium=ExtHubManageList) in your organization. +- Pipeline library variable group. Create a pipeline library variable group to hold the variables used by the pipeline. For more information, see [Add and use variable groups](../../pipelines/library/variable-groups.md?tabs=classic). You can make variable groups from the Azure DevOps Library tab or through the CLI. [Use the variables](../../pipelines/library/variable-groups.md?tabs=yaml#use-variable-groups-in-pipelines) within this group in your pipeline. Also, declare the following variables in the variable group: + - `publisherId`: ID of your marketplace publisher + - `extensionId`: ID of your extension, as declared in the vss-extension.json file + - `extensionName`: Name of your extension, as declared in the vss-extension.json file + - `artifactName`: Name of the artifact being created for the VSIX file +- Service connection. Create a new Marketplace service connection and grant access permissions for all pipelines. +- YAML pipeline. Use the following example to create a new pipeline with YAML. For more information, see [Create your first pipeline](../../pipelines/create-first-pipeline.md?tabs=javascript%2Cyaml%2Cbrowser%2Ctfs-2018-2) and [YAML schema](/azure/devops/pipelines/yaml-schema/). + + ```yaml + trigger: + - main + pool: + vmImage: "ubuntu-latest" + variables: + - group: variable-group # Rename to whatever you named your variable group in the prerequisite stage of step 6 + stages: + - stage: Run_and_publish_unit_tests + jobs: + - job: + steps: + - task: TfxInstaller@4 + inputs: + version: "v0.x" + - task: Npm@1 + inputs: + command: 'install' + workingDir: '/TaskDirectory' # Update to the name of the directory of your task + - task: Bash@3 + displayName: Compile Javascript + inputs: + targetType: "inline" + script: | + cd TaskDirectory # Update to the name of the directory of your task + tsc + - task: Npm@1 + inputs: + command: 'custom' + workingDir: '/TestsDirectory' # Update to the name of the directory of your task's tests + customCommand: 'testScript' # See the definition in the explanation section below - it may be called test + - task: PublishTestResults@2 + inputs: + testResultsFormat: 'JUnit' + testResultsFiles: '**/ResultsFile.xml' + - stage: Package_extension_and_publish_build_artifacts + jobs: + - job: + steps: + - task: TfxInstaller@4 + inputs: + version: "0.x" + - task: Npm@1 + inputs: + command: 'install' + workingDir: '/TaskDirectory' # Update to the name of the directory of your task + - task: Bash@3 + displayName: Compile Javascript + inputs: + targetType: "inline" + script: | + cd TaskDirectory # Update to the name of the directory of your task + tsc + - task: QueryAzureDevOpsExtensionVersion@4 + name: QueryVersion + inputs: + connectTo: 'VsTeam' + connectedServiceName: 'ServiceConnection' # Change to whatever you named the service connection + publisherId: '$(PublisherID)' + extensionId: '$(ExtensionID)' + versionAction: 'Patch' + - task: PackageAzureDevOpsExtension@4 + inputs: + rootFolder: '$(System.DefaultWorkingDirectory)' + publisherId: '$(PublisherID)' + extensionId: '$(ExtensionID)' + extensionName: '$(ExtensionName)' + extensionVersion: '$(QueryVersion.Extension.Version)' + updateTasksVersion: true + updateTasksVersionType: 'patch' + extensionVisibility: 'private' # Change to public if you're publishing to the marketplace + extensionPricing: 'free' + - task: CopyFiles@2 + displayName: "Copy Files to: $(Build.ArtifactStagingDirectory)" + inputs: + Contents: "**/*.vsix" + TargetFolder: "$(Build.ArtifactStagingDirectory)" + - task: PublishBuildArtifacts@1 + inputs: + PathtoPublish: '$(Build.ArtifactStagingDirectory)' + ArtifactName: '$(ArtifactName)' + publishLocation: 'Container' + - stage: Download_build_artifacts_and_publish_the_extension + jobs: + - job: + steps: + - task: TfxInstaller@4 + inputs: + version: "v0.x" + - task: DownloadBuildArtifacts@0 + inputs: + buildType: "current" + downloadType: "single" + artifactName: "$(ArtifactName)" + downloadPath: "$(System.DefaultWorkingDirectory)" + - task: PublishAzureDevOpsExtension@4 + inputs: + connectTo: 'VsTeam' + connectedServiceName: 'ServiceConnection' # Change to whatever you named the service connection + fileType: 'vsix' + vsixFile: '$(PublisherID).$(ExtensionName)/$(PublisherID)..vsix' + publisherId: '$(PublisherID)' + extensionId: '$(ExtensionID)' + extensionName: '$(ExtensionName)' + updateTasksVersion: false + extensionVisibility: 'private' # Change to public if you're publishing to the marketplace + extensionPricing: 'free' + ``` -For more help with triggers, such as CI and PR triggers, see [Specify events that trigger pipelines](../../pipelines/build/triggers.md). +For more information, see [Specify events that trigger pipelines](../../pipelines/build/triggers.md). > [!NOTE] > Each job uses a new user agent and requires dependencies to be installed. ### Pipeline stages -This section helps you understand how the pipeline stages work. +The following section helps you understand how the pipeline stages work. -#### Stage: Run and publish unit tests +#### Stage 1: Run and publish unit tests This stage runs unit tests and publishes test results to Azure DevOps. -To run unit tests, add a custom script to the package.json file. For example: +To run unit tests, add a custom script to the `package.json` file like the following example. ```json "scripts": { @@ -641,84 +629,85 @@ To run unit tests, add a custom script to the package.json file. For example: }, ``` -1. Add "Use Node CLI for Azure DevOps (tfx-cli)" to install the tfx-cli onto your build agent. -1. Add the "npm" task with the "install" command and target the folder with the package.json file. -1. Add the "Bash" task to compile the TypeScript into JavaScript. -1. Add the "npm" task with the "custom" command, target the folder that contains the unit tests, and input `testScript` as the command. Use the following inputs: - - Command: custom - - Working folder that contains package.json: /TestsDirectory +1. Add **Use Node CLI for Azure DevOps (tfx-cli)** to install the tfx-cli onto your build agent. +1. Add the `npm` task with the `install` command and target the folder with the `package.json` file. +1. Add the `Bash` task to compile the TypeScript into JavaScript. +1. Add the `npm` task with the `custom` command, target the folder that contains the unit tests, and input `testScript` as the command. Use the following inputs: + - Command: `custom` + - Working folder that contains package.json: `/TestsDirectory` - Command and arguments: `testScript` -1. Add the "Publish Test Results" task. If you're using the Mocha XUnit reporter, ensure that the result format is "JUnit" and not "XUnit." Set the search folder to the root directory. Use the following inputs: - - Test result format: JUnit - - Test results files: **/ResultsFile.xml +1. Add the **Publish Test Results** task. If you're using the Mocha XUnit reporter, ensure that the result format is `JUnit` and not `XUnit`. Set the search folder to the root directory. Use the following inputs: + - Test result format: `JUnit` + - Test results files: `**/ResultsFile.xml` - Search folder: `$(System.DefaultWorkingDirectory)` -After the test results have been published, the output under the tests tab should look like the following example. + After the test results get published, the output under the tests tab should look like the following example. -![Screenshot of the test result example.](media/test-results-example.png) + :::image type="content" source="media/test-results-example.png" alt-text="Screenshot of the test result example."::: -#### Stage: Package the extension and publish build artifacts +#### Stage 2: Package the extension and publish build artifacts -1. Add "Use Node CLI for Azure DevOps (tfx-cli)" to install the tfx-cli onto your build agent. -1. Add the "npm" task with the "install" command and target the folder with the package.json file. -1. Add the "Bash" task to compile the TypeScript into JavaScript. -1. Add the "Query Extension Version" task to query the existing extension version. Use the following inputs: +1. Add **Use Node CLI for Azure DevOps (tfx-cli)** to install the tfx-cli onto your build agent. +1. Add the `npm` task with the `install` command and target the folder with the `package.json` file. +1. Add the `Bash` task to compile the TypeScript into JavaScript. +1. To query the existing version, add the **Query Extension Version** task using the following inputs: - Connect to: Visual Studio Marketplace - Visual Studio Marketplace (Service connection): Service Connection - Publisher ID: ID of your Visual Studio Marketplace publisher - - Extension ID: ID of your extension in the vss-extension.json file + - Extension ID: ID of your extension in the `vss-extension.json` file - Increase version: Patch - - Output Variable: Task.Extension.Version + - Output Variable: `Task.Extension.Version` -1. Add the "Package Extension" task to package the extensions based on manifest Json. Use the following inputs: - - Root manifests folder: Points to root directory that contains manifest file. For example, $(System.DefaultWorkingDirectory) is the root directory - - Manifest file(s): vss-extension.json +1. To package the extensions based on manifest Json, add the **Package Extension** task using the following inputs: + - Root manifests folder: Points to root directory that contains manifest file. For example, `$(System.DefaultWorkingDirectory)` is the root directory + - Manifest file: `vss-extension.json` - Publisher ID: ID of your Visual Studio Marketplace publisher - - Extension ID: ID of your extension in the vss-extension.json file - - Extension Name: Name of your extension in the vss-extension.json file - - Extension Version: $(Task.Extension.Version) + - Extension ID: ID of your extension in the `vss-extension.json` file + - Extension Name: Name of your extension in the `vss-extension.json` file + - Extension Version: `$(Task.Extension.Version)` - Override tasks version: checked (true) - Override Type: Replace Only Patch (1.0.r) - - Extension Visibility: If the extension is still in development, set the value to private. To release the extension to the public, set the value to public -1. Add the "Copy files" task to copy published files. Use the following inputs: + - Extension Visibility: If the extension is still in development, set the value to *private*. To release the extension to the public, set the value to *public*. +1. To copy to published files, add the **Copy files** task using the following inputs: - Contents: All of the files to be copied for publishing them as an artifact - Target folder: The folder that the files get copied to - - For example: $(Build.ArtifactStagingDirectory) -1. Add "Publish build artifacts" to publish the artifacts for use in other jobs or pipelines. Use the following inputs: + - For example: `$(Build.ArtifactStagingDirectory)` +1. Add **Publish build artifacts** to publish the artifacts for use in other jobs or pipelines. Use the following inputs: - Path to publish: The path to the folder that contains the files that are being published - - For example: $(Build.ArtifactStagingDirectory) + - For example: `$(Build.ArtifactStagingDirectory)` - Artifact name: The name given to the artifact - - Artifacts publish location: Choose "Azure Pipelines" to use the artifact in future jobs + - Artifacts publish location: Choose **Azure Pipelines** to use the artifact in future jobs + +#### Stage 3: Download build artifacts and publish the extension -#### Stage: Download build artifacts and publish the extension +1. To install the tfx-cli onto your build agent, add **Use Node CLI for Azure DevOps (tfx-cli)**. -1. Add "Use Node CLI for Azure DevOps (tfx-cli)" to install the tfx-cli onto your build agent. +1. To download the artifacts onto a new job, add the **Download build artifacts** task using the following inputs: + - Download artifacts produced by: If you're downloading the artifact on a new job from the same pipeline, select **Current build**. If you're downloading on a new pipeline, select **Specific build** + - Download type: Choose **Specific artifact** to download all files that were published. + - Artifact name: The published artifact's name + - Destination directory: The folder where the files should be downloaded -1. Add the "Download build artifacts" task to download the artifacts onto a new job. Use the following inputs: - - Download artifacts produced by: If you're downloading the artifact on a new job from the same pipeline, select "Current build." If you're downloading on a new pipeline, select "Specific build." - - Download type: Choose "Specific artifact" to download all files that were published. - - Artifact name: The published artifact's name. - - Destination directory: The folder where the files should be downloaded. -1. The last task that you need is the "Publish Extension" task. Use the following inputs: +1. To get the **Publish Extension** task, use the following inputs: - Connect to: Visual Studio Marketplace - Visual Studio Marketplace connection: ServiceConnection - Input file type: VSIX file - - VSIX file: /Publisher.*.vsix + - VSIX file: `/Publisher.*.vsix` - Publisher ID: ID of your Visual Studio Marketplace publisher - - Extension ID: ID of your extension in the vss-extension.json file - - Extension Name: Name of your extension in the vss-extension.json file + - Extension ID: ID of your extension in the `vss-extension.json` file + - Extension Name: Name of your extension in the `vss-extension.json` file - Extension visibility: Either private or public ## Optional: Install and test your extension -Install an extension that is shared with you in just a few steps: +Install an extension that's shared with you in just a few steps: 1. From your organization control panel (`https://dev.azure.com/{organization}/_admin`), go to the project collection administration page. -2. In the **Extensions** tab, find your extension in the "Extensions Shared With Me" group and select the extension link. -3. Install the extension. +1. In the **Extensions** tab, find your extension in the **Extensions Shared With Me** group and select the extension link. +1. Install the extension. If you can't see the **Extensions** tab, make sure you're in the control panel (the administration page at the project collection level, `https://dev.azure.com/{organization}/_admin`) and not the administration page for a project. @@ -726,27 +715,28 @@ If you don't see the **Extensions** tab, then extensions aren't enabled for your To package and publish Azure DevOps Extensions to the Visual Studio Marketplace, you can download [Azure DevOps Extension Tasks](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-developer-tools-build-tasks). -## FAQs -See the following frequently asked questions (FAQs) about adding custom build or release tasks in extensions for Azure DevOps +## FAQ -### Q: How can I restrict GitHub Codespaces commands usage for task? +See the following frequently asked questions about adding custom build or release tasks in extensions for Azure DevOps. -You can restrict GitHub Codespaces commands usage and variables, which can be set by task. -This action could be useful to prevent unrestricted access to variables/vso commands for custom scripts which task executes. We recommend that you set it up for new tasks. -To apply, you may need to add the following statement to your task.json file: +### Q: How can I restrict Azure Pipelines commands usage for task? + +You can restrict Azure Pipelines commands usage and variables, which get set by task. +This action could be useful to prevent unrestricted access to variables or vso commands for custom scripts which task executes. We recommend that you set it up for new tasks. +To apply, you might need to add the following statement to your `task.json` file: ```json - "restrictions": { - "commands": { - "mode": "restricted" - }, - "settableVariables": { - "allowed": ["variable1", "test*"] - } +"restrictions": { + "commands": { + "mode": "restricted" + }, + "settableVariables": { + "allowed": ["variable1", "test*"] + } } ``` -If `restricted` value is specified for `mode` - you can only execute the following commands by the task: +If `restricted` value is specified for `mode`, you can only execute the following commands by the task: - `logdetail` - `logissue` @@ -759,11 +749,11 @@ If `restricted` value is specified for `mode` - you can only execute the followi - `prependpath` - `publish` -`settableVariables` restrictions allow you to pass in an allowlist of variables, which can be set by `setvariable` or `prependpath` commands. It also allows basic regular expressions. For example, if your allowlist was: `['abc', 'test*']`, setting `abc`, `test`, or `test1` as variables with any value or prepending them to the path would succeed, but if you try to set a variable proxy it would warn. Empty list means that no variables can be changed by task. +The `settableVariables` restrictions allow you to pass in an allowlist of variables, which get set by `setvariable` or `prependpath` commands. It also allows basic regular expressions. For example, if your allowlist was: `['abc', 'test*']`, setting `abc`, `test`, or `test1` as variables with any value or prepending them to the path would succeed, but if you try to set a variable proxy it would warn. Empty list means that no variables get changed by task. If either the `settableVariables` or `commands` key is omitted, relevant restriction isn't applied. -The restriction feature is available from [2.182.1](https://github.com/microsoft/azure-pipelines-agent/releases/tag/v2.182.1) agent version. +The restriction feature is available from [agent version 2.182.1](https://github.com/microsoft/azure-pipelines-agent/releases/tag/v2.182.1). ### Q: How is the cancellation signal handled by a task? @@ -773,12 +763,54 @@ The pipeline agent sends `SIGINT` and `SIGTERM` signals to the relevant child pr We don't support the automatic deletion of tasks. Automatic deletion isn't safe and breaks existing pipelines that already use such tasks. But, you can mark tasks as deprecated. To do so, [bump the task version](https://github.com/microsoft/azure-pipelines-tasks/blob/master/docs/taskversionbumping.md) and [mark the task as deprecated](https://github.com/microsoft/azure-pipelines-tasks/blob/master/docs/deprecatedtasks.md). -### Q: How can I upgrade a task to the latest Node? +### Q: How can I upgrade my custom task to the latest Node? + +We recommend upgrading to [the latest Node version](https://nodejs.org/en/download/). For example information, see [Upgrading tasks to Node 20](https://github.com/microsoft/azure-pipelines-tasks/blob/master/docs/migrateNode20.md). + +Microsoft Hosted agents and various Azure DevOps Server versions have different life cycles, leading to different Node runner versions being installed depending on where a task is running. To ensure compatibility across agents with different Node runner versions, the `task.json` file can include multiple execution sections. In the following example, Azure Pipeline agents with the Node 20 runner use it by default, while agents without it fall back to the Node 10 implementation. -We recommend upgrading to [the latest Node version](https://nodejs.org/en/download/). For example information, see [Upgrading tasks to Node 10](https://github.com/microsoft/azure-pipelines-tasks/blob/master/docs/migrateNode10.md). +```nodejs +"execution": { + "Node10": { + "target": "bash.js", + "argumentFormat": "" + }, + "Node20_1": { + "target": "bash.js", + "argumentFormat": "" + } +} +``` + +To upgrade your tasks: + +* To ensure your code behaves as expected, test your tasks on the various Node runner versions. +* In your task's execution section, update from `Node` or `Node10` to `Node16` or `Node20`. +* To support older server versions, you should leave the `Node`/`Node10` target. Older Azure DevOps Server versions might not have the latest Node runner version included. +* You can choose to share the entry point defined in the target or have targets optimized to the Node version used. + + ```nodejs + "execution": { + "Node10": { + "target": "bash10.js", + "argumentFormat": "" + }, + "Node16": { + "target": "bash16.js", + "argumentFormat": "" + }, + "Node20_1": { + "target": "bash20.js", + "argumentFormat": "" + } + } + ``` + +> [!IMPORTANT] +> If you don't add support for the Node 20 runner to your custom tasks, they fail on agents installed from the `pipelines-agent-*` [release feed](../../pipelines/agents/agents.md#node-runner-versions). -## Related articles +## Related content - [Extension manifest reference](./manifest.md) -- [Build/Release Task JSON Schema](./integrate-build-task.md) -- [Build/Release Task Examples](https://github.com/Microsoft/vso-agent-tasks/tree/master/Tasks) +- [Integrate custom build pipeline tasks with extensions](./integrate-build-task.md) +- [Build/Release task examples](https://github.com/microsoft/vso-agent-tasks/tree/master/Tasks) diff --git a/docs/extend/develop/add-chart.md b/docs/extend/develop/add-chart.md index 836b715daf2..f6f4a56ce85 100644 --- a/docs/extend/develop/add-chart.md +++ b/docs/extend/develop/add-chart.md @@ -7,7 +7,7 @@ ms.topic: conceptual ms.author: chcomley author: chcomley ms.date: 12/31/2019 -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" --- # Add a chart diff --git a/docs/extend/develop/add-dashboard-widget.md b/docs/extend/develop/add-dashboard-widget.md index 0552703a78c..02b1fe13bd7 100644 --- a/docs/extend/develop/add-dashboard-widget.md +++ b/docs/extend/develop/add-dashboard-widget.md @@ -1,395 +1,377 @@ --- -title: Add a dashboard widget +title: Add a Dashboard Widget titleSuffix: Azure DevOps -description: Tutorial for creating a widget that you can then add to a dashboard in Azure DevOps or Team Foundation Server (TFS) +description: Learn how to create a widget that you can then add to a dashboard in Azure DevOps. ms.subservice: azure-devops-ecosystem ms.assetid: 1D393A4A-2D25-479D-972B-304F99B5B1F8 -ms.topic: conceptual +ms.topic: concept-article ms.author: chcomley author: chcomley -ms.date: 10/31/2019 -monikerRange: '>= azure-devops-2019' +ms.date: 04/15/2025 +monikerRange: "<=azure-devops" --- # Add a dashboard widget [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Widgets on a dashboard are implemented as [contributions](./contributions-overview.md) in the [extension framework](../overview.md). -A single extension can have multiple contributions. Learn how to create an extension with multiple widgets as contributions. +Widgets on a dashboard are implemented as [contributions](./contributions-overview.md) in the [extension framework](../overview.md). A single extension can have multiple contributions. Learn how to create an extension with multiple widgets as contributions. -This article is divided into three parts, each building on the previous - beginning with a simple widget and ending with a comprehensive widget. +This article is divided into three parts, each building on the previous. You begin with a simple widget and end with a comprehensive widget. [!INCLUDE [extension-docs-new-sdk](../../includes/extension-docs-new-sdk.md)] -## Preparation and required setup for this tutorial +## Prerequisites + +- Some **knowledge** of JavaScript, HTML, and CSS is required for widget development. +- An **organization** in Azure DevOps. [Create an organization](../../organizations/accounts/create-organization.md). +- A **text editor**. For many of the tutorials, we use [Visual Studio Code](https://code.visualstudio.com/). +- The [latest version of Node.js](https://nodejs.org). +- [Cross-platform CLI for Azure DevOps (tfx-cli)](https://github.com/microsoft/tfs-cli) to package your extensions. + - tfx-cli can be installed using `npm`, a component of Node.js by running `npm i -g tfx-cli` +- A home directory for your project. This directory is referred to as `home` throughout the tutorial, and should have the following structure after you complete the steps in this article: + + ``` + |--- README.md + |--- sdk + |--- node_modules + |--- scripts + |--- VSS.SDK.min.js + |--- img + |--- logo.png + |--- scripts + |--- hello-world.html // html page to be used for your widget + |--- vss-extension.json // extension's manifest + ``` + +## In this tutorial + +- [Part 1: Hello World](#part-1): Shows you how to create a new widget, which prints a simple *Hello World* message. +- [Part 2: Hello World with Azure DevOps REST API](#part-2): Builds on the first part by adding a call to an Azure DevOps REST API. +- [Part 3: Configure Hello World](#part-3): Explains how to add configuration to your widget. -To create extensions for Azure DevOps or TFS, there are some prerequisite software and tools you'll need: - -**Knowledge:** -Some knowledge of JavaScript, HTML, CSS is required for widget development. - -- An **organization** in Azure DevOps for installing and testing your widget, more information can be found [here](https://visualstudio.microsoft.com/products/visual-studio-team-services-vs.aspx) -- **A text editor**. For many of the tutorials, we used `Visual Studio Code`, which can be downloaded [here](https://code.visualstudio.com/) -- The latest version of **node**, which can be downloaded [here](https://nodejs.org/download/) -- **Cross-platform CLI for Azure DevOps (tfx-cli)** to package your extensions. - - **tfx-cli** can be installed using `npm`, a component of Node.js by running `npm i -g tfx-cli` -- A home directory for your project. This directory is referred to as `home` throughout the tutorial. - -**Extension file structure:** -```no-highlight -|--- README.md -|--- sdk - |--- node_modules - |--- scripts - |--- VSS.SDK.min.js -|--- img - |--- logo.png -|--- scripts -|--- hello-world.html // html page to be used for your widget -|--- vss-extension.json // extension's manifest -``` - -## What you'll find in the tutorial - -1. The first part of this guide shows you how to create a new widget, which prints a simple "Hello World" message. -2. The [second part](#part-2) builds on the first one by adding a call to an Azure DevOps REST API. -3. The [third part](#part-3) explains how to add configuration to your widget. - -> [!NOTE] -> If you're in a hurry and want to get your hands on the code right away, you can download the samples [here](https://github.com/Microsoft/azure-devops-extension-sample). +> [!NOTE] +> If you're in a hurry and want to get your hands on the code right away, you can download the [sample extension for Azure DevOps](https://github.com/Microsoft/azure-devops-extension-sample). > Once downloaded, go to the `widgets` folder, then follow [Step 6](#package-publish-share) and [Step 7](#add-from-catalog) directly to publish the sample extension which has the three sample widgets of varying complexities. -Get started with some [basic styles for widgets](./styles-from-widget-sdk.md) that we provide out of the box for you and some guidance on widget structure. +Get started with some [basic styles for widgets](./styles-from-widget-sdk.md) that we provide out-of-the-box and some guidance on widget structure. - + ## Part 1: Hello World -This part presents a widget that prints "Hello World" using JavaScript. +Part 1 presents a widget that prints *Hello World* using JavaScript. -![Overview dashboard with a sample widget](../media/add-dashboard-widget/sample.png) +:::image type="content" source="../media/add-dashboard-widget/sample.png" alt-text="Screenshot of Overview dashboard with a sample widget."::: -### Step 1: Get the client SDK - `VSS.SDK.min.js` +### Step 1: Get the client SDK -The core SDK script, `VSS.SDK.min.js`, enables web extensions to communicate to the host Azure DevOps frame. The script does operations like initializing, notifying extension is loaded, or getting context about the current page. -Get the Client SDK `VSS.SDK.min.js` file and add it to your web app. Place it in the `home/sdk/scripts` folder. +The core SDK script, `VSS.SDK.min.js`, enables web extensions to communicate with the host Azure DevOps frame. The script does operations like initializing, notifying extension is loaded, or getting context about the current page. -Use the 'npm install' command to retrieve the SDK: +To retrieve the SDK, use the `npm install` command: -```no-highlight +```cmd npm install vss-web-extension-sdk ``` -To learn more about the SDK, visit the [Client SDK GitHub Page](https://github.com/Microsoft/vss-sdk). +Find the client SDK `VSS.SDK.min.js` file located in the `vss-web-extension-sdk/lib` folder, and then place it in your `home/sdk/scripts` folder. + +For more information, see the [Client SDK GitHub page](https://github.com/Microsoft/vss-sdk). -### Step 2: Your HTML page - `hello-world.html` +### Step 2: Set up your HTML page -Your HTML page is the glue that holds your layout together and includes references to CSS and JavaScript. -You can name this file anything, just be sure to update all references to `hello-world` with the name you use. +Create a file called `hello-world.html`. Your HTML page is the glue that holds your layout together and includes references to CSS and JavaScript. You can name this file anything. If you use a different filename, update all references to `hello-world` with the name you use. Your widget is HTML based and is hosted in an [iframe](https://msdn.microsoft.com/library/windows/apps/hh465955.aspx). -Add the below HTML in `hello-world.html`. We add the mandatory reference to `VSS.SDK.min.js` file and include an `h2` element in the , which is updated with the string Hello World in the upcoming step. +Copy the following HTML into your `hello-world.html` file. We add the mandatory reference to `VSS.SDK.min.js` file and include an `h2` element, which is updated with the string *Hello World* in the upcoming step. ```html - - - - - - -

-

-
- - + + + + + + +
+

+
+ + ``` -> Even though we are using an HTML file, most of the HTML head elements other than script and link are ignored by the framework. +Even though you're using an HTML file, most of the HTML head elements other than script and link are ignored by the framework. + + - +### Step 3: Update JavaScript -### Step 3: Your JavaScript +We use JavaScript to render content in the widget. In this article, we wrap all of our JavaScript code inside a ` + VSS.notifyLoadSucceeded(); + }); + ``` - - -`VSS.init` initializes the handshake between the iframe hosting the widget and the host frame. -We pass `explicitNotifyLoaded: true` so that the widget can explicitly notify the host when we're done loading. This control allows us to notify load completion after ensuring that the dependent modules are loaded. -We pass `usePlatformStyles: true` so that the Azure DevOps core styles for html elements (such as body, div, and so on) can be used by the Widget. If the widget prefers to not use these styles, they can pass in `usePlatformStyles: false`. + -`VSS.require` is used to load the required VSS script libraries. A call to this method automatically loads general libraries like [JQuery](https://jquery.com/) and [JQueryUI](https://jqueryui.com/). -In our case, we depend on the WidgetHelpers library, which is used to communicate widget status to the widget framework. -So, we pass the corresponding module name `TFS/Dashboards/WidgetHelpers` and a callback to `VSS.require`. -The callback is called once the module is loaded. -The callback has the rest of the JavaScript code needed for the widget. At the end of the callback, we call `VSS.notifyLoadSucceeded` to notify load completion. +- `VSS.init` initializes the handshake between the iframe hosting the widget and the host frame. -`WidgetHelpers.IncludeWidgetStyles` includes a stylesheet with some [basic css](./styles-from-widget-sdk.md) to get you started. Make sure to wrap your content inside an HTML element with class `widget` to make use of these styles. +- Pass in `explicitNotifyLoaded: true` so that the widget can explicitly notify the host when it finishes loading. This control allows us to notify load completion after ensuring that the dependent modules are loaded. Use `usePlatformStyles: true` so that the widget can use Azure DevOps core styles for HTML elements, such as `body` and `div`. If you don't want the widget to use these styles, pass in `usePlatformStyles: false`. -`VSS.register` is used to map a function in JavaScript, which uniquely identifies the widget among the different contributions in your extension. The name should match the `id` that identifies your contribution as described in [Step 5](#widget-extension-manifest). For widgets, the function that is passed to `VSS.register` should return an object that satisfies the `IWidget` contract, -for example, the returned object should have a load property whose value is another function that has the core logic to render the widget. -In our case, it's to update the text of the `h2` element to "Hello World". -It's this function that is called when the widget framework instantiates your widget. -We use the `WidgetStatusHelper` from WidgetHelpers to return the `WidgetStatus` as success. +- `VSS.require` is used to load the required VSS script libraries. A call to this method automatically loads general libraries like [JQuery](https://jquery.com) and [JQueryUI](https://jqueryui.com). In our case, we depend on the WidgetHelpers library, which is used to communicate widget status to the widget framework. So, pass the corresponding module name `TFS/Dashboards/WidgetHelpers` and a callback to `VSS.require`. The callback is called once the module is loaded. The callback has the rest of the JavaScript code needed for the widget. At the end of the callback, call `VSS.notifyLoadSucceeded` to notify load completion. +- `WidgetHelpers.IncludeWidgetStyles` includes a stylesheet with some [basic CSS](./styles-from-widget-sdk.md) to get you started. To make use of these styles, wrap your content inside an HTML element with class `widget`. -> [!WARNING] -> If the name used to register the widget doesn't match the ID for the contribution in the manifest, then the widget functions unexpectedly. +- `VSS.register` is used to map a function in JavaScript, which uniquely identifies the widget among the different contributions in your extension. The name should match the `id` that identifies your contribution as described in [Step 5](#widget-extension-manifest). For widgets, the function that is passed to `VSS.register` should return an object that satisfies the `IWidget` contract. For example, the returned object should have a load property whose value is another function that has the core logic to render the widget. In our case, it's to update the text of the `h2` element to *Hello World*. It's this function that's called when the widget framework instantiates your widget. We use the `WidgetStatusHelper` from WidgetHelpers to return the `WidgetStatus` as success. -The `vss-extension.json` should always be at the root of the folder (in this guide, `HelloWorld`). For all the other files, you can place them in whatever structure you want inside the folder, just make sure to update the references appropriately in the HTML files and in the `vss-extension.json` manifest. + > [!WARNING] + > If the name used to register the widget doesn't match the ID for the contribution in the manifest, then the widget functions unexpectedly. - + -### Step 4: Your extension's logo: logo.png +### Step 4: Update your extension logo -Your logo is displayed in the Marketplace, and in the widget catalog once a user installs your extension. +Your logo is displayed in the Marketplace and in the widget catalog once a user installs your extension. -You need a 98 px x 98-px catalog icon. Choose an image, name it `logo.png`, and place it in the `img` folder. +You need a 98x98-pixel catalog icon. Choose an image, name it `logo.png`, and place it in the `img` folder. You can name the image however you want as long as the extension manifest in the next step is updated with the name you use. -To support TFS 2015 Update 3, you need an additional image that is 330 px x 160 px. This preview image is shown in this catalog. Choose an image, name it `preview.png`, and place it in the `img` folder as before. +### Step 5: Create your extension manifest -You can name these images however you want as long as the extension manifest in the next step is updated with the names you use. - -### Step 5: Your extension's manifest: vss-extension.json - -* ***Every*** extension must have an extension manifest file -* Read the [extension manifest reference](./manifest.md) -* Find out more about the contribution points in [Extensibility points](../reference/targets/overview.md) - -Create a json file (`vss-extension.json`, for example) in the `home` directory with the following contents: +*Every* extension must have an extension manifest file. Create a json file called `vss-extension.json` in the `home` directory with the following contents: ```json - { - "manifestVersion": 1, - "id": "vsts-extensions-myExtensions", - "version": "1.0.0", - "name": "My First Set of Widgets", - "description": "Samples containing different widgets extending dashboards", - "publisher": "fabrikam", - "categories": ["Azure Boards"], - "targets": [ - { - "id": "Microsoft.VisualStudio.Services" - } - ], - "icons": { - "default": "img/logo.png" - }, - "contributions": [ - { - "id": "HelloWorldWidget", - "type": "ms.vss-dashboards-web.widget", - "targets": [ - "ms.vss-dashboards-web.widget-catalog" +{ + "manifestVersion": 1, + "id": "azure-devops-extensions-myExtensions", + "version": "1.0.0", + "name": "My First Set of Widgets", + "description": "Samples containing different widgets extending dashboards", + "publisher": "fabrikam", + "categories": ["Azure Boards"], + "targets": [ + { + "id": "Microsoft.VisualStudio.Services" + } + ], + "icons": { + "default": "img/logo.png" + }, + "contributions": [ + { + "id": "HelloWorldWidget", + "type": "ms.vss-dashboards-web.widget", + "targets": [ + "ms.vss-dashboards-web.widget-catalog" + ], + "properties": { + "name": "Hello World Widget", + "description": "My first widget", + "catalogIconUrl": "img/CatalogIcon.png", + "previewImageUrl": "img/preview.png", + "uri": "hello-world.html", + "supportedSizes": [ + { + "rowSpan": 1, + "columnSpan": 2 + } ], - "properties": { - "name": "Hello World Widget", - "description": "My first widget", - "catalogIconUrl": "img/CatalogIcon.png", - "previewImageUrl": "img/preview.png", - "uri": "hello-world.html", - "supportedSizes": [ - { - "rowSpan": 1, - "columnSpan": 2 - } - ], - "supportedScopes": ["project_team"] - } - } - ], - "files": [ - { - "path": "hello-world.html", "addressable": true - }, - { - "path": "sdk/scripts", "addressable": true - }, - { - "path": "img", "addressable": true + "supportedScopes": ["project_team"] } - ] - } + } + ], + "files": [ + { + "path": "hello-world.html", + "addressable": true + }, + { + "path": "sdk/scripts", + "addressable": true + }, + { + "path": "img", + "addressable": true + } + ] +} ``` -For more information about required attributes, see the [Extension manifest reference](manifest.md) +The `vss-extension.json` file should always be at the root of the home directory. For all the other files, you can place them in whatever structure you want inside the folder, just make sure to update the references appropriately in the HTML files and in the `vss-extension.json` manifest. + +For more information about required attributes, see the [Extension manifest reference](manifest.md). > [!NOTE] -> The **publisher** here needs to be changed to your publisher name. To create a publisher now, visit [Package/Publish/Install](../publish/overview.md). +> Change the `publisher` to your publisher name. To create a publisher, see [Package/Publish/Install](../publish/overview.md). #### Icons -The **icons** stanza specifies the path to your extension's icon in your manifest. +The `icons` stanza specifies the path to your extension's icon in your manifest. #### Contributions Each contribution entry defines [properties](./manifest.md#contributions). -- The **ID** to identify your contribution. This ID should be unique within an extension. This ID should match with the name you used in [Step 3](#widget-javascript) to register your widget. -- The **type** of contribution. For all widgets, the type should be `ms.vss-dashboards-web.widget`. -- The array of **targets** to which the contribution is contributing. For all widgets, the target should be `[ms.vss-dashboards-web.widget-catalog]`. -- The **properties** are objects that include properties for the contribution type. For widgets, the following properties are mandatory. - - -| Property | Description | -|--------------------|----------------| -| name | Name of the widget to display in the widget catalog. | -| description | Description of the widget to display in the widget catalog. | -| catalogIconUrl | Relative path of the catalog icon that you added in [Step 4](#image) to display in the widget catalog. The image should be 98 px x 98 px. If you've used a different folder structure or a different file name, then specify the appropriate relative path here. | -| previewImageUrl | Relative path of the preview image that you added in [Step 4](#image) to display in the widget catalog for TFS 2015 Update 3 only. The image should be 330 px x 160 px. If you've used a different folder structure or a different file name, then specify the appropriate relative path here. | -| uri | Relative path of the HTML file that you added in [Step 1](#step-1-files). If you've used a different folder structure or a different file name, then specify the appropriate relative path here. | -| supportedSizes | Array of sizes supported by your widget. When a widget supports multiple sizes, the first size in the array is the default size of the widget. The `widget size` is specified for the rows and columns occupied by the widget in the dashboard grid. One row/column corresponds to 160 px. Any dimension above 1x1 gets an additional 10 px that represent the gutter between widgets. For example, a 3x2 widget is `160*3+10*2` wide and `160*2+10*1` tall. The maximum supported size is `4x4`. | -| supportedScopes | At the moment, we support only team dashboards. The value has to be `project_team`. In the future, when we support other dashboard scopes, there'll be more options to choose from here. | - +- The `id` to identify your contribution. This ID should be unique within an extension. This ID should match with the name you used in [Step 3](#widget-javascript) to register your widget. +- The `type` of contribution. For all widgets, the type should be `ms.vss-dashboards-web.widget`. +- The array of `targets` to which the contribution is contributing. For all widgets, the target should be `[ms.vss-dashboards-web.widget-catalog]`. +- The `properties` are objects that include properties for the contribution type. For widgets, the following properties are mandatory: + + | Property | Description | + |--------------------|----------------| + | `name` | Name of the widget to display in the widget catalog. | + | `description` | Description of the widget to display in the widget catalog. | + | `catalogIconUrl` | Relative path of the catalog icon that you added in [Step 4](#image) to display in the widget catalog. The image should be 98x98 pixels. If you used a different folder structure or a different file name, then specify the appropriate relative path here. | + | `previewImageUrl` | Relative path of the preview image that you added in [Step 4](#image) to display in the widget catalog. The image should be 330x160 pixels. If you used a different folder structure or a different file name, then specify the appropriate relative path here. | + | `uri` | Relative path of the HTML file that you added in [Step 1](#step-1-files). If you used a different folder structure or a different file name, then specify the appropriate relative path here. | + | `supportedSizes` | Array of sizes supported by your widget. When a widget supports multiple sizes, the first size in the array is the default size of the widget. The `widget size` is specified for the rows and columns occupied by the widget in the dashboard grid. One row/column corresponds to 160 px. Any dimension larger than 1x1 gets an extra 10 px that represent the gutter between widgets. For example, a 3x2 widget is `160*3+10*2` wide and `160*2+10*1` tall. The maximum supported size is 4x4. | + | `supportedScopes` | Currently, only team dashboards are supported. The value has to be `project_team`. Future updates might include more options for dashboard scopes. | + +To learn more about contribution points, see [Extensibility points](../reference/targets/overview.md). #### Files -The **files** stanza states the files that you want to include in your package - your HTML page, your scripts, the SDK script, and your logo. +The `files` stanza states the files that you want to include in your package: your HTML page, your scripts, the SDK script, and your logo. Set `addressable` to `true` unless you include other files that don't need to be URL-addressable. > [!NOTE] -> For more information about the **extension manifest file**, such as its properties and what they do, check out the [extension manifest reference](./manifest.md). +> For more information about the *extension manifest file*, such as its properties and what they do, check out the [extension manifest reference](./manifest.md). - + ### Step 6: Package, publish, and share -Once you've written your extension, the next step towards getting it into the Marketplace is to package all of your files together. All extensions are packaged -as VSIX 2.0 compatible .vsix files - Microsoft provides a cross-platform command line interface (CLI) to package your extension. +Once you have your written extension, the next step toward getting it into the Marketplace is to package all of your files together. All extensions are packaged as VSIX 2.0 compatible .vsix files. Microsoft provides a cross-platform command line interface (CLI) to package your extension. #### Get the packaging tool -You can install or update the Cross-platform CLI for Azure DevOps (tfx-cli) using `npm`, a component of [Node.js](https://nodejs.org), from your command line. +You can install or update the tfx-cli using `npm`, a component of [Node.js](https://nodejs.org), from your command line. -```no-highlight +```cmd npm i -g tfx-cli ``` - + + #### Package your extension Packaging your extension into a .vsix file is effortless once you have the tfx-cli. Go to your extension's home directory and run the following command. -```no-highlight +```cmd tfx extension create --manifest-globs vss-extension.json ``` ->[!NOTE] ->An extension/integration's version must be incremented on every update.
->When updating an existing extension, either update the version in the manifest or pass the `--rev-version` command line switch. This increments the *patch* version number of your extension and save the new version to your manifest. +> [!NOTE] +> An extension/integration version must be incremented on every update.
+> When you update an existing extension, either update the version in the manifest or pass the `--rev-version` command line switch. This increments the *patch* version number of your extension and saves the new version to your manifest. -After you have your packaged extension in a .vsix file, you're ready to publish your extension to the Marketplace. +After you package your extension in a .vsix file, you're ready to publish your extension to the Marketplace. #### Create publisher for the extension -All extensions, including extensions from Microsoft, are identified as being provided by a publisher. -If you aren't already a member of an existing publisher, you'll create one. +All extensions, including extensions from Microsoft, are identified as being provided by a publisher. If you aren't already a member of an existing publisher, create one. + +1. Sign in to the [Visual Studio Marketplace Publishing Portal](https://marketplace.visualstudio.com/manage/createpublisher). -1. Sign in to the [Visual Studio Marketplace Publishing Portal](https://marketplace.visualstudio.com/manage/createpublisher) -2. If you aren't already a member of an existing publisher, you'll be prompted to create a publisher. If you're not prompted to create a publisher, scroll down to the bottom of the page and select Publish Extensions underneath Related Sites. - * Specify an identifier for your publisher, for example: `mycompany-myteam` +1. If you aren't already a member of an existing publisher, you must create a publisher. If you already have a publisher, scroll to and select **Publish Extensions** under **Related Sites**. + * Specify an identifier for your publisher, for example: *mycompany-myteam*. * The identifier is used as the value for the `publisher` attribute in your extensions' manifest file. - * Specify a display name for your publisher, for example: `My Team` -3. Review the [Marketplace Publisher Agreement](https://aka.ms/vsmarketplace-agreement) and select **Create** + * Specify a display name for your publisher, for example: *My Team*. + +1. Review the [Marketplace Publisher Agreement](https://aka.ms/vsmarketplace-agreement) and select **Create**. Now your publisher is defined. In a future release, you can grant permissions to view and manage your publisher's extensions. -It's easy and more secure for teams and organizations to publish extensions under a common publisher, -but without the need to share a set of credentials across a set of users. -**Update the `vss-extension.json` manifest file in the samples to replace the dummy publisher ID `fabrikam` with your publisher ID.** +Publishing extensions under a common publisher simplifies the process for teams and organizations, offering a more secure approach. This method eliminates the need to distribute a single set of credentials among multiple users, enhancing security. + +Update the `vss-extension.json` manifest file in the samples to replace the dummy publisher ID *fabrikam* with your publisher ID. #### Publish and share the extension -After creating a publisher, you can now upload your extension to the Marketplace. +Now, you can now upload your extension to the Marketplace. -1. Find the Upload new extension button, navigate to your packaged .vsix file, and select upload. +Select **Upload new extension**, go to your packaged .vsix file, and select **Upload**. -You can also upload your extension via the command line by using the ```tfx extension publish``` command instead of ```tfx extension create``` -to package and publish your extension in one step. -You can optionally use ```--share-with``` to share your extension with one or more accounts after publishing. -You'll need a personal access token, too. +You can also upload your extension via the command line by using the `tfx extension publish` command instead of `tfx extension create` to package and publish your extension in one step. You can optionally use `--share-with` to share your extension with one or more accounts after publishing. You also need a personal access token. -```no-highlight +```cmd tfx extension publish --manifest-globs your-manifest.json --share-with yourOrganization ``` - + ### Step 7: Add widget from the catalog -1. Go to your project in Azure DevOps, `http://dev.azure.com/{yourOrganization}/{yourProject}` -2. Select **Overview**, and then select **Dashboards**. -3. Choose **Add a widget**. -4. Highlight your widget, and then select **Add**. - +1. Sign in to your project, `http://dev.azure.com/{Your_Organization}/{Your_Project}`. + +1. Select **Overview** > **Dashboards**. + +1. Select **Add a widget**. + +1. Highlight your widget, and then select **Add**. + The widget appears on your dashboard. - + ## Part 2: Hello World with Azure DevOps REST API Widgets can call any of the [REST APIs](/rest/api/azure/devops/) in Azure DevOps to interact with Azure DevOps resources. -In this example, we use the REST API for WorkItemTracking to fetch information about an existing query and display some query info in the widget right -below the "Hello World" text. -![Overview dashboard with a sample widget using the REST API for WorkItemTracking.](../media/add-dashboard-widget/sample2.png) +In the following example, we use the REST API for WorkItemTracking to fetch information about an existing query and display some query info in the widget under the *Hello World* text. - +:::image type="content" source="../media/add-dashboard-widget/sample2.png" alt-text="Screenshot of Overview dashboard with a sample widget using the REST API for WorkItemTracking."::: -### Step 1: HTML + -Copy the file `hello-world.html` from the previous example, and rename the copy to `hello-world2.html`. Your folder now looks like below: +### Step 1: Add HTML file -```no-highlight +Copy the file `hello-world.html` from the previous example, and rename the copy to `hello-world2.html`. Your folder now looks like the following example: + +``` |--- README.md -|--- sdk - |--- node_modules +|--- node_modules +|--- SDK |--- scripts - |--- VSS.SDK.min.js -|--- img - |--- logo.png -|--- scripts -|--- hello-world.html // html page to be used for your widget + |--- VSS.SDK.min.js +|--- img + |--- logo.png +|--- scripts +|--- hello-world.html // html page to be used for your widget |--- hello-world2.html // renamed copy of hello-world.html |--- vss-extension.json // extension's manifest ``` -
-Add a new div element right below the h2 to hold the query information. -Update the name of the widget from HelloWorldWidget to HelloWorldWidget2 in the line where you call VSS.register. -This allows the framework to uniquely identify the widget within the extension. +To hold the query information, add a new `div` element under the `h2`. +Update the name of the widget from `HelloWorldWidget` to `HelloWorldWidget2` in the line where you call `VSS.register`. +This action allows the framework to uniquely identify the widget within the extension. ```html - - + + @@ -423,40 +405,48 @@ This allows the framework to uniquely identify the widget within the extension. ### Step 2: Access Azure DevOps resources -To enable access to Azure DevOps resources, [scopes](./manifest.md#scopes) need to be specified in the extension manifest. We add the `vso.work` scope to our manifest. -This scope indicates the widget needs read-only access to queries and work items. See all available scopes [here](./manifest.md#scopes). -Add the below at the end of your extension manifest. +To enable access to Azure DevOps resources, [scopes](./manifest.md#scopes) need to be specified in the extension manifest. We add the `vso.work` scope to our manifest. This scope indicates the widget needs read-only access to queries and work items. To see all available scopes, see [Scopes](./manifest.md#scopes). + +Add the following code at the end of your extension manifest: ```json { - ..., "scopes":[ "vso.work" ] } ``` +To include other properties, you should list them explicitly, for example: + +```json +{ + "name": "example-widget", + "publisher": "example-publisher", + "version": "1.0.0", + "scopes": [ + "vso.work" + ] +} +``` + > [!WARNING] -> Adding or changing scopes after publishing an extension is currently not supported. If you've already uploaded your extension, remove it from the Marketplace. Go to ![Visual Studio Marketplace Publishing Portal](https://marketplace.visualstudio.com/manage/createpublisher), right-click your extension and select "Remove". +> Adding or changing scopes after publishing an extension is currently not supported. If you already uploaded your extension, remove it from the Marketplace. Go to the [Visual Studio Marketplace Publishing Portal](https://marketplace.visualstudio.com/manage/createpublisher), right-select your extension, and select **Remove**. + +### Step 3: Make the REST API call -### Step 3: Make the REST API Call +There are many client-side libraries that can be accessed via the SDK to make REST API calls in Azure DevOps. These libraries are known as REST clients and are JavaScript wrappers around Ajax calls for all available server-side endpoints. You can use methods provided by these clients instead of writing Ajax calls yourself. These methods map the API responses to objects that your code can consume. -There are many client-side libraries that can be accessed via the SDK to make REST API calls in Azure DevOps. -These libraries are called REST clients and are JavaScript wrappers around Ajax calls for all available server-side endpoints. -You can use methods provided by these clients instead of writing Ajax calls yourself. These methods map the API responses to objects that can be consumed by your code. +In this step, update the `VSS.require` call to load `AzureDevOps/WorkItemTracking/RestClient`, which provides the WorkItemTracking REST client. You can use this REST client to get information about a query called `Feedback` under the folder `Shared Queries`. -In this step, we update the `VSS.require` call to load `TFS/WorkItemTracking/RestClient`, which provides the WorkItemTracking REST client. -We can use this REST client to get information about a query called `Feedback` under the folder `Shared Queries`. +Inside the function that you pass to `VSS.register`, create a variable to hold the current project ID. You need this variable to fetch the query. Also, create a new method `getQueryInfo` to use the REST client. This method is then called from the load method. -Inside the function that we pass to `VSS.register`, we create a variable to hold the current project ID. We need this variable to fetch the query. -We also create a new method `getQueryInfo` to use the REST client. This method that is then called from the load method. +The method `getClient` gives an instance of the REST client you need. The method `getQuery` returns the query wrapped in a promise. -The method `getClient` gives an instance of the REST client we need. -The method `getQuery` returns the query wrapped in a promise. The updated `VSS.require` looks as follows: -```JavaScript -VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"], +```js +VSS.require(["AzureDevOps/Dashboards/WidgetHelpers", "AzureDevOps/WorkItemTracking/RestClient"], function (WidgetHelpers, TFS_Wit_WebApi) { WidgetHelpers.IncludeWidgetStyles(); VSS.register("HelloWorldWidget2", function () { @@ -487,32 +477,31 @@ VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"], VSS.notifyLoadSucceeded(); }); ``` -Notice the use of the Failure method from `WidgetStatusHelper`. -It allows you to indicate to the widget framework that an error has occurred and take advantage to the standard error experience provided to all widgets. -> If you do not have the `Feedback` query under the `Shared Queries` folder, then replace `Shared Queries\Feedback` in the code with the path of a query that exists in your project. +Notice the use of the Failure method from `WidgetStatusHelper`. It allows you to indicate to the widget framework that an error occurred and take advantage to the standard error experience provided to all widgets. -### Step 4: Display the Response +If you don't have the `Feedback` query under the `Shared Queries` folder, then replace `Shared Queries\Feedback` in the code with the path of a query that exists in your project. -The last step is to render the query information inside the widget. -The `getQuery` function returns an object of type `Contracts.QueryHierarchyItem` inside a promise. -In this example, we display the query ID, the query name, and the name of the query creator under the "Hello World" text. -Replace the `// Do something with the query` comment with the below: +### Step 4: Display the response -```JavaScript - // Create a list with query details - var $list = $('
    '); - $list.append($('
  • ').text("Query Id: " + query.id)); - $list.append($('
  • ').text("Query Name: " + query.name)); - $list.append($('
  • ').text("Created By: " + ( query.createdBy? query.createdBy.displayName: "" ) ) ); +The last step is to render the query information inside the widget. The `getQuery` function returns an object of type `Contracts.QueryHierarchyItem` inside a promise. In this example, you display the query ID, the query name, and the name of the query creator under the *Hello World* text. - // Append the list to the query-info-container - var $container = $('#query-info-container'); - $container.empty(); - $container.append($list); +Replace the `// Do something with the query` comment with the following code: + +```JavaScript +// Create a list with query details +var $list = $('
      '); +$list.append($('
    • ').text("Query Id: " + query.id)); +$list.append($('
    • ').text("Query Name: " + query.name)); +$list.append($('
    • ').text("Created By: " + (query.createdBy ? query.createdBy.displayName : ""))); + +// Append the list to the query-info-container +var $container = $('#query-info-container'); +$container.empty(); +$container.append($list); ``` -Your final `hello-world2.html` is as follows: +Your final `hello-world2.html` is like the following example: ```html @@ -525,7 +514,7 @@ Your final `hello-world2.html` is as follows: usePlatformStyles: true }); - VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"], + VSS.require(["AzureDevOps/Dashboards/WidgetHelpers", "AzureDevOps/WorkItemTracking/RestClient"], function (WidgetHelpers, TFS_Wit_WebApi) { WidgetHelpers.IncludeWidgetStyles(); VSS.register("HelloWorldWidget2", function () { @@ -539,7 +528,7 @@ Your final `hello-world2.html` is as follows: var $list = $('
        '); $list.append($('
      • ').text("Query ID: " + query.id)); $list.append($('
      • ').text("Query Name: " + query.name)); - $list.append($('
      • ').text("Created By: " + (query.createdBy ? query.createdBy.displayName: "") )); + $list.append($('
      • ').text("Created By: " + (query.createdBy ? query.createdBy.displayName : ""))); // Append the list to the query-info-container var $container = $('#query-info-container'); @@ -578,91 +567,94 @@ Your final `hello-world2.html` is as follows: ``` - + -### Step 5: Extension Manifest Updates +### Step 5: Update extension manifest In this step, we update the extension manifest to include an entry for our second widget. Add a new contribution to the array in the `contributions` property and add the new file `hello-world2.html` to the array in the files property. You need another preview image for the second widget. Name this `preview2.png` and place it in the `img` folder. ```json - { - ..., - "contributions":[ - ..., +{ + ..., + "contributions": [ + ..., { - "id": "HelloWorldWidget2", - "type": "ms.vss-dashboards-web.widget", - "targets": [ - "ms.vss-dashboards-web.widget-catalog" - ], - "properties": { - "name": "Hello World Widget 2 (with API)", - "description": "My second widget", - "previewImageUrl": "img/preview2.png", - "uri": "hello-world2.html", - "supportedSizes": [ - { - "rowSpan": 1, - "columnSpan": 2 - } - ], - "supportedScopes": ["project_team"] - } - } - - ], - "files": [ - { - "path": "hello-world.html", "addressable": true - }, - { - "path": "hello-world2.html", "addressable": true - }, - { - "path": "sdk/scripts", "addressable": true - }, - { - "path": "img", "addressable": true - } - ], - "scopes":[ - "vso.work" - ] - } + "id": "HelloWorldWidget2", + "type": "ms.vss-dashboards-web.widget", + "targets": [ + "ms.vss-dashboards-web.widget-catalog" + ], + "properties": { + "name": "Hello World Widget 2 (with API)", + "description": "My second widget", + "previewImageUrl": "img/preview2.png", + "uri": "hello-world2.html", + "supportedSizes": [ + { + "rowSpan": 1, + "columnSpan": 2 + } + ], + "supportedScopes": ["project_team"] + } + } + ], + "files": [ + { + "path": "hello-world.html", + "addressable": true + }, + { + "path": "hello-world2.html", + "addressable": true + }, + { + "path": "sdk/scripts", + "addressable": true + }, + { + "path": "img", + "addressable": true + } + ], + "scopes": [ + "vso.work" + ] +} ``` -### Step 6: Package, Publish, and Share +### Step 6: Package, publish, and share [Package, publish, and share your extension](#package-publish-share). -If you've already published the extension, you can repackage the extension, as described [here](#package-the-extension), and directly [update it](../publish/overview.md#update-an-extension) to the Marketplace. +If you already published the extension, you can repackage the extension and directly update it to the Marketplace. +### Step 7: Add widget from the catalog -### Step 7: Add Widget From the Catalog - -Now, go to your team dashboard at `https:\//dev.azure.com/{yourOrganization}/{yourProject}`. If this page is already open, then refresh it. -Hover on the Edit button in the bottom right, and select the Add button. The widget catalog opens where you find the widget you installed. -Choose your widget and select the 'Add' button to add it to your dashboard. +Now, go to your team dashboard at `https:\//dev.azure.com/{Your_Organization}/{Your_Project}`. If this page is already open, then refresh it. +Hover over **Edit** and select **Add**. The widget catalog opens where you find the widget you installed. +To add it to your dashboard, choose your widget and select **Add**. - + -## Part 3: Hello World with Configuration +## Part 3: Configure Hello World In [Part 2](#part-2) of this guide, you saw how to create a widget that shows query information for a hard-coded query. -In this part, we add the ability to configure the query to be used instead of the hard-coded one. +In this part, you add the ability to configure the query to be used instead of the hard-coded one. When in configuration mode, the user gets to see a live preview of the widget based on their changes. These changes get saved to the widget on the dashboard when the user selects **Save**. -![Overview dashboard live preview of the widget based on changes.](../media/add-dashboard-widget/sampleConfiguration.png) +:::image type="content" source="../media/add-dashboard-widget/sample-configuration.png" alt-text="Screenshot of Overview dashboard live preview of the widget based on changes."::: -### Step 1: HTML +### Step 1: Add HTML file -Implementations of Widgets and Widget Configurations are a lot alike. Both are implemented in the extension framework as contributions. Both use the same SDK file, `VSS.SDK.min.js`. Both are based on HTML, JavaScript, and CSS. +Implementations of widgets and widget configurations are a lot alike. Both are implemented in the extension framework as contributions. Both use the same SDK file, `VSS.SDK.min.js`. Both are based on HTML, JavaScript, and CSS. Copy the file `html-world2.html` from the previous example and rename the copy to `hello-world3.html`. Add another HTML file called `configuration.html`. + Your folder now looks like the following example: -```no-highlight +``` |--- README.md |--- sdk |--- node_modules @@ -678,8 +670,7 @@ Your folder now looks like the following example: |--- vss-extension.json // extension's manifest ``` -
        -Add the below HTML in configuration.html. We basically add the mandatory reference to the VSS.SDK.min.js file and a select element for the dropdown to select a query from a preset list. +Add the following HTML in `configuration.html`. You basically add the mandatory reference to the `VSS.SDK.min.js` file and a `select` element for the dropdown to select a query from a preset list. ```html @@ -703,74 +694,66 @@ Add the below HTML in configuration.html. We basically add the mand ``` -### Step 2: JavaScript - Configuration +### Step 2: Configure JavaScript Use JavaScript to render content in the widget configuration just like we did for the widget in [Step 3](#widget-javascript) of Part 1 in this guide. -This JavaScript code renders content, initializes the VSS SDK, maps the code for your widget configuration to the configuration name, -and passes the configuration settings to the framework. In our case, below is the code that loads the widget configuration. -Open the file `configuration.html` and the below ` + VSS.notifyLoadSucceeded(); + }); + ``` -`VSS.init`, `VSS.require`, and `VSS.register` play the same role as they played for the widget as described in [Part 1](#vss-methods). -The only difference is that for widget configurations, the function that is passed to `VSS.register` should return an object that satisfies the `IWidgetConfiguration` contract. +- `VSS.init`, `VSS.require`, and `VSS.register` play the same role they played for the widget as described in [Part 1](#vss-methods). The only difference is that for widget configurations, the function that's passed to `VSS.register` should return an object that satisfies the `IWidgetConfiguration` contract. -The `load` property of the `IWidgetConfiguration` contract should have a function as its value. -This function has the set of steps to render the widget configuration. -In our case, it's to update the selected value of the dropdown element with existing settings if any. -This function gets called when the framework instantiates your `widget configuration` +- The `load` property of the `IWidgetConfiguration` contract should have a function as its value. This function has the set of steps to render the widget configuration. In our case, it's to update the selected value of the dropdown element with existing settings if any. This function gets called when the framework instantiates your `widget configuration` -The `onSave` property of the `IWidgetConfiguration` contract should have a function as its value. -This function gets called by the framework when the user selects **Save** in the configuration pane. -If the user input is ready to save, then serialize it to a string, form the `custom settings` object -and use `WidgetConfigurationSave.Valid()` to save the user input. +- The `onSave` property of the `IWidgetConfiguration` contract should have a function as its value. This function gets called by the framework when the user selects **Save** in the configuration pane. If the user input is ready to save, then serialize it to a string, form the `custom settings` object, and use `WidgetConfigurationSave.Valid()` to save the user input. In this guide, we use JSON to serialize the user input into a string. You can choose any other way to serialize the user input to string. -It is accessible to the widget via the customSettings property of the `WidgetSettings` object. -The widget has to deserialize this, which is covered in [Step 4](#reload-widget). +It's accessible to the widget via the customSettings property of the `WidgetSettings` object. +The widget has to deserialize, which is covered in [Step 4](#reload-widget). -### Step 3: JavaScript - Enable Live Preview +### Step 3: Enable live preview - JavaScript -To enable live preview update when the user selects a query from the dropdown, we attach a change event handler to the button. This handler notifies the framework that the configuration has changed. -It also passes the `customSettings` to be used for updating the preview. To notify the framework, the `notify` method on the `widgetConfigurationContext` needs to be called. It takes two parameters, the name of the -event, which in this case is `WidgetHelpers.WidgetEvent.ConfigurationChange`, and an `EventArgs` object for the event, created from the `customSettings` with the help of `WidgetEvent.Args` helper method. +To enable live preview update when the user selects a query from the dropdown, attach a change event handler to the button. This handler notifies the framework that the configuration changed. +It also passes the `customSettings` to be used for updating the preview. To notify the framework, the `notify` method on the `widgetConfigurationContext` needs to be called. It takes two parameters, the name of the event, which in this case is `WidgetHelpers.WidgetEvent.ConfigurationChange`, and an `EventArgs` object for the event, created from the `customSettings` with the help of `WidgetEvent.Args` helper method. -Add the below in the function assigned to the `load` property. +Add the following code in the function assigned to the `load` property. -```JavaScript +```js $queryDropdown.on("change", function () { var customSettings = { data: JSON.stringify({ @@ -783,82 +766,81 @@ Add the below in the function assigned to the `load` property. }); ``` -> You need to notify the framework of configuration change at least once so that the "Save" button can be enabled. - -At the end, your `configuration.html` looks like this: +Ensure that the framework is notified of the configuration change at least once to enable the **Save** button. +At the end, your `configuration.html` looks like the following example: ```html - - - - - + - - -
        -
        - - -
        -
        - - + VSS.notifyLoadSucceeded(); + }); + + + +
        +
        + + +
        +
        + + ``` - + -### Step 4: JavaScript - Implement reload in the widget +### Step 4: Implement reload in the widget - JavaScript -We've set up widget configuration to store the query path selected by the user. -We now have to update the code in the widget to use this stored configuration instead of the hard-coded `Shared Queries/Feedback` from the previous example. +Set up widget configuration to store the query path selected by the user. +You now have to update the code in the widget to use this stored configuration instead of the hard-coded `Shared Queries/Feedback` from the previous example. Open the file `hello-world3.html` and update the name of the widget from `HelloWorldWidget2` to `HelloWorldWidget3` in the line where you call `VSS.register`. -This allows the framework to uniquely identify the widget within the extension. +This action allows the framework to uniquely identify the widget within the extension. The function mapped to `HelloWorldWidget3` via `VSS.register` currently returns an object that satisfies the `IWidget` contract. Since our widget now needs configuration, this function needs to be updated to return an object that satisfies the `IConfigurableWidget` contract. -To do this, update the return statement to include a property called reload as below. The value for this property is a function that calls the `getQueryInfo` method one more time. -This reload method gets called by the framework every time the user input changes to show the live preview. This is also called when the configuration is saved. +To do so, update the return statement to include a property called reload per the following code. The value for this property is a function that calls the `getQueryInfo` method one more time. +This reload method gets called by the framework every time the user input changes to show the live preview. This reload method is also called when the configuration is saved. ```JavaScript return { @@ -875,9 +857,9 @@ return { } ``` -
        -The hard-coded query path in getQueryInfo should be replaced with the configured query path, which can be extracted from the parameter widgetSettings that is passed to the method. -Add the below in the very beginning of the getQueryInfo method and replace the hard-coded querypath with settings.queryPath. +The hard-coded query path in `getQueryInfo` should be replaced with the configured query path, which can be extracted from the parameter `widgetSettings` that is passed to the method. + +Add the following code in the very beginning of the `getQueryInfo` method and replace the hard-coded query path with `settings.queryPath`. ```JavaScript var settings = JSON.parse(widgetSettings.customSettings.data); @@ -889,17 +871,18 @@ if (!settings || !settings.queryPath) { return WidgetHelpers.WidgetStatusHelper.Success(); } ``` + At this point, your widget is ready to render with the configured settings. -> Both the `load` and the `reload` properties have a similar function. This is the case for most simple widgets. -For complex widgets, there would be certain operations that you would want to run just once no matter how many times the configuration changes. -Or there might be some heavy-weight operations that need not run more than once. Such operations would be part of the function corresponding to the `load` property and not the `reload` property. +Both the `load` and the `reload` properties have a similar function. This is the case for most simple widgets. +For complex widgets, there are certain operations that you would want to run just once no matter how many times the configuration changes. +Or there might be some heavy-weight operations that need not run more than once. Such operations are part of the function corresponding to the `load` property and not the `reload` property. +### Step 5: Update extension manifest -### Step 5: Extension Manifest Updates -Open the `vss-extension.json` file to include two new entries to the array in the `contributions` property. One for the `HelloWorldWidget3` widget and the other for its configuration. +Open the `vss-extension.json` file to include two new entries to the array in the `contributions` property: one for the `HelloWorldWidget3` widget, and the other for its configuration. You need yet another preview image for the third widget. Name this `preview3.png` and place it in the `img` folder. -Update the array in the `files` property to include the two new HTML files we have added in this example. +Update the array in the `files` property to include the two new HTML files you added in this example. ```json { @@ -911,7 +894,7 @@ Update the array in the `files` property to include the two new HTML files we ha "type": "ms.vss-dashboards-web.widget", "targets": [ "ms.vss-dashboards-web.widget-catalog", - "fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration" + "fabrikam.azuredevops-extensions-myExtensions.HelloWorldWidget.Configuration" ], "properties": { "name": "Hello World Widget 3 (with config)", @@ -962,56 +945,63 @@ Update the array in the `files` property to include the two new HTML files we ha } ``` -
        -Note the contribution for widget configuration follows a slightly different model than the widget itself. +The contribution for widget configuration follows a slightly different model than the widget itself. A contribution entry for widget configuration has: -- The **ID** to identify your contribution. This should be unique within an extension. -- The **type** of contribution. For all widget configurations, this should be `ms.vss-dashboards-web.widget-configuration` -- The array of **targets** to which the contribution is contributing. For all widget configurations, this has a single entry: `ms.vss-dashboards-web.widget-configuration`. -- The **properties** that contain a set of properties that includes name, description, and the URI of the HTML file used for configuration. +- The `id` to identify your contribution. The ID should be unique within an extension. +- The `type` of contribution. For all widget configurations, it should be `ms.vss-dashboards-web.widget-configuration`. +- The array of `targets` to which the contribution is contributing. For all widget configurations, it has a single entry: `ms.vss-dashboards-web.widget-configuration`. +- The `properties` that contain a set of properties that includes name, description, and the URI of the HTML file used for configuration. -To support configuration, the widget contribution needs to be changed as well. The array of **targets** for the widget needs to be updated to include the ID for the configuration in the form -<`publisher`>.<`id for the extension`>.<`id for the configuration contribution`> which in this case is `fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration`. +To support configuration, the widget contribution needs to be changed as well. The array of `targets` for the widget needs to be updated to include the ID for the configuration in the following form: + + `..` + +In this case, the example is: + + `fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration` > [!WARNING] -> If the contribution entry for your configurable widget doesn't target the configuration using the right publisher and extension name as described previously, the configure button doesn't show up for the widget. +> If the contribution entry for your configurable widget doesn't target the configuration using the right publisher and extension name as described previously, the configure button doesn't show up for the widget. -At the end of this part, the manifest file should contain three widgets and one configuration. You can get the complete manifest from the sample [here](https://github.com/Microsoft/vso-extension-samples/blob/master/widgets/vss-extension.json). +At the end of this part, the manifest file should contain three widgets and one configuration. For the complete sample manifest file, see [vss-extension.json](https://github.com/Microsoft/vso-extension-samples/blob/master/widgets/vss-extension.json). -### Step 6: Package, Publish, and Share +### Step 6: Package, publish, and share -If you have not published your extension yet, then read [this section](#package-publish-share) to package, publish, and share your extension. -If you have already published the extension before this point, you can repackage the extension as described [here](#package-the-extension) and directly [update it](../publish/overview.md#update-an-extension) to the Marketplace. +If your extension isn't published, see [Step 6: Package, publish, and share](#package-publish-share). +If you already published the extension, you can repackage the extension and directly update it to the Marketplace. -### Step 7: Add Widget From the Catalog -Now, go to your team dashboard at https:\//dev.azure.com/{yourOrganization}/{yourProject}. If this page is already open, refresh it. -Hover on the Edit button in the bottom right, and select the Add button. This should open the widget catalog where you find the widget you installed. -Choose your widget and select the 'Add' button to add it to your dashboard. +### Step 7: Add widget from the catalog + +Now, go to your team dashboard at `https://dev.azure.com/{Your_Organization}/{Your_Project}`. If this page is already open, refresh it. +Hover over **Edit** and select **Add**. This action should open the widget catalog where you find the widget you installed. +To add the widget to your dashboard, choose your widget and select **Add**. -You would see a message asking you to configure the widget. +A message similar to the following, asks you to configure the widget. -![Overview dashboard with a sample widget from the catalog.](../media/add-dashboard-widget/sampleWidgetWithNoSettings.png) +:::image type="content" source="../media/add-dashboard-widget/sample-widget-with-no-settings.png" alt-text="Screenshot of Overview dashboard with a sample widget from the catalog."::: -There are two ways to configure widgets. One is to hover on the widget, select the ellipsis that appears on the top-right corner and then select Configure. +There are two ways to configure widgets. One is to hover over the widget, select the ellipsis that appears on the top-right corner, and then select **Configure**. The other is to select the Edit button in the bottom right of the dashboard, and then select the configure button that appears on the top-right corner of the widget. Either opens the configuration experience on the right side, and a preview of your widget in the center. + Go ahead and choose a query from the dropdown. The live preview shows the updated results. -Select "Save" and your widget displays the updated results. +Select **Save** and your widget displays the updated results. +### Step 8: Configure more (optional) -### Step 8: Configure More (optional) -You can add as many HTML form elements as you need in the `configuration.html` for additional configuration. -There are two configurable features that are available out of the box: widget name and widget size. +You can add as many HTML form elements as you need in the `configuration.html` for more configurations. +There are two configurable features available out-of-the-box: Widget name and widget size. By default, the name that you provide for your widget in the extension manifest is stored as the widget name for every instance of your widget that ever gets added to a dashboard. -You can allow users to configure this, so that they can add any name they want to their instance of your widget. +You can allow users to configure, so that they can add any name they want to their instance of your widget. To allow such configuration, add `isNameConfigurable:true` in the properties section for your widget in the extension manifest. If you provide more than one entry for your widget in the `supportedSizes` array in the extension manifest, then users can configure the widget's size as well. -The extension manifest for the third sample in this guide would look like the below if we enable the widget name and size configuration: +The extension manifest for the third sample in this guide would look like the following example if you enable the widget name and size configuration: + ```json { ... @@ -1021,7 +1011,8 @@ The extension manifest for the third sample in this guide would look like the be "id": "HelloWorldWidget3", "type": "ms.vss-dashboards-web.widget", "targets": [ - "ms.vss-dashboards-web.widget-catalog", "fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration" + "ms.vss-dashboards-web.widget-catalog", + "fabrikam.azuredevops-extensions-myExtensions.HelloWorldWidget.Configuration" ], "properties": { "name": "Hello World Widget 3 (with config)", @@ -1043,25 +1034,22 @@ The extension manifest for the third sample in this guide would look like the be } }, ... + ] } ``` -With the previous change, [repackage](#package-the-extension) and [update](../publish/overview.md#update-an-extension) your extension. Refresh the dashboard that has this widget (Hello World Widget 3 (with config)). +[Repackage](#package-the-extension) and [update](../publish/overview.md) your extension. Refresh the dashboard that has this widget (Hello World Widget 3 (with config)). Open the configuration mode for your widget, you should now be able to see the option to change the widget name and size. -![Widget where name and size can be configured](../media/add-dashboard-widget/sampleConfigureNameAndSize.png) - -Go ahead and choose a different size from the drop-down. You see the live preview get resized. Save the change and the widget on the dashboard is resized as well. +:::image type="content" source="../media/add-dashboard-widget/sample-configure-name-and-size.png" alt-text="Screenshot showing where the widget name and size can be configured."::: -> [!WARNING] -> If you remove an already supported size, then the widget fails to load properly. We are working on a fix for a future release. +Choose a different size from the dropdown. You see the live preview get resized. Save the change, and the widget on the dashboard is resized as well. -Changing the name of the widget doesn't result in any visible change in the widget. -This is because our sample widgets don't display the widget name anywhere. Let us modify the sample code to display the widget name instead of the hard-coded text "Hello World". +Changing the name of the widget doesn't result in any visible change in the widget because our sample widgets don't display the widget name anywhere. -To do this, replace the hard-coded text "Hello World" with `widgetSettings.name` in the line where we set the text of the `h2` element. -This ensures that the widget name gets displayed every time the widget gets loaded on page refresh. -Since we want the live preview to be updated every time the configuration changes, we should add the same code in the `reload` part of our code as well. +Modify the sample code to display the widget name instead of the hard-coded text *Hello World* by replacing the hard-coded text *Hello World* with `widgetSettings.name` in the line where you set the text of the `h2` element. +This action ensures that the widget name gets displayed every time the widget gets loaded on page refresh. +Since you want the live preview to be updated every time the configuration changes, you should add the same code in the `reload` part of your code as well. The final return statement in `hello-world3.html` is as follows: ```JavaScript @@ -1083,5 +1071,6 @@ return { } ``` -[Repackage](#package-the-extension) and [update](../publish/overview.md#update-an-extension) your extension again. Refresh the dashboard that has this widget. Any changes to the widget name, in the configuration mode, update the widget title now. +[Repackage](#package-the-extension) and [update](../publish/overview.md) your extension again. Refresh the dashboard that has this widget. +Any changes to the widget name, in the configuration mode, update the widget title now. diff --git a/docs/extend/develop/add-hub.md b/docs/extend/develop/add-hub.md index ad2161dd71f..664ed38513b 100644 --- a/docs/extend/develop/add-hub.md +++ b/docs/extend/develop/add-hub.md @@ -143,7 +143,7 @@ The **contributions** stanza adds your contribution - the Hello hub - to your ex For each contribution in your extension, the manifest defines the following: - type of contribution, hub -- contribution target, the work hub group (check out all of the [targetable hub groups](../reference/targets/overview.md#targetable-hub-groups)), +- contribution target, the work hub group (check out all of the [targetable hub groups](../reference/targets/overview.md), - the properties specific to each type of contribution. A hub has the following properties. | Property | Description | diff --git a/docs/extend/develop/add-pipeline-decorator.md b/docs/extend/develop/add-pipeline-decorator.md index c9bd9ab9292..0f87cc66c2a 100644 --- a/docs/extend/develop/add-pipeline-decorator.md +++ b/docs/extend/develop/add-pipeline-decorator.md @@ -86,6 +86,7 @@ Let's take a look at the properties and what they're used for: > [!NOTE] > [Deployment jobs](../../pipelines/process/deployment-jobs.md) in a YAML pipeline only support `ms.azure-pipelines-agent-job.pre-job-tasks` and `ms.azure-pipelines-agent-job.post-job-tasks` targets. > [Jobs](../../pipelines/process/phases.md) support all YAML pipeline targets. +> Deployment jobs are not supported in classic release pipelines. In this example, we use `ms.azure-pipelines-agent-job.post-job-tasks` because we want to run at the end of all build jobs. @@ -108,6 +109,9 @@ steps: script: dir ``` +> [!NOTE] +> Pipeline decorator tasks with service connection usage are not supported for classic release pipelines. + ## 3. Install the decorator To add a pipeline decorator to your organization, you must [install an extension](../../marketplace/install-extension.md). @@ -167,7 +171,7 @@ steps: ## 5. Specify a target task -You can specify target [task ID](add-build-task.md#taskjson), and inject tasks before or after this target task. +You can specify target [task ID](add-build-task.md), and inject tasks before or after this target task. To specify target task, you can modify vss-extension.json manifest file like the following example. #### vss-extension.json @@ -198,11 +202,11 @@ Tasks will be injected before/after all instances of specified target task. ### Specify target task's inputs injection You can specify a list of inputs of the target task that you want to inject as inputs to the injected task. -This feature is designed to work with [custom pipeline tasks](add-build-task.md#step-1-create-a-custom-task). It isn't intended to provide access to target pipeline task inputs via pipeline variables. +This feature is designed to work with [custom pipeline tasks](add-build-task.md). It isn't intended to provide access to target pipeline task inputs via pipeline variables. To get access to the target pipeline task inputs (inputs with the `target_` prefix), the injected pipeline task should use methods from the [azure-pipelines-tasks-task-lib](https://github.com/Microsoft/azure-pipelines-task-lib), and not the pipeline variables, for example `const inputString = tl.getInput('target_targetInput')`). -To do so, you can create your own custom pipeline [task](add-build-task.md#task-implementation) and use the target inputs there. If you need the functionality of one of the out-of-box tasks, like `CmdLine@2`, you can create a copy of the [CmdLine@2 task](https://github.com/microsoft/azure-pipelines-tasks/tree/master/Tasks/CmdLineV2) and publish it with your decorator extension. +To do so, you can create your own custom pipeline [task](add-build-task.md) and use the target inputs there. If you need the functionality of one of the out-of-box tasks, like `CmdLine@2`, you can create a copy of the [CmdLine@2 task](https://github.com/microsoft/azure-pipelines-tasks/tree/master/Tasks/CmdLineV2) and publish it with your decorator extension. > [!NOTE] > This functionality is only available for tasks that are injected before or after the target task. @@ -254,7 +258,7 @@ Pipeline decorators currently work with Azure Dev Ops Git and GitHub. They do no --> ## Debug -You might need to debug when you create your decorator. You also may want to see what data you have available in the context. +You might need to debug when you create your decorator. You also might want to see what data you have available in the context. You can set the `system.debugContext` variable to `true` when you queue a pipeline. Then, look at the pipeline summary page. diff --git a/docs/extend/develop/add-workitem-extension.md b/docs/extend/develop/add-workitem-extension.md index c45445f2afc..be7e8ee5247 100644 --- a/docs/extend/develop/add-workitem-extension.md +++ b/docs/extend/develop/add-workitem-extension.md @@ -1,20 +1,20 @@ --- -title: Extend the work item form | Extensions for Azure DevOps -description: Describes how to extend work item tracking, including adding an action, an observer, a group, or a page to the work item form in Azure DevOps. +title: Extend the Work Item Form | Azure DevOps Extensions +description: Learn how to extend work item tracking, including adding an action, an observer, a group, or a page to the work item form in Azure DevOps. ms.assetid: bffc76b7-f6ba-41f0-8460-ccb44d45d670 ms.subservice: azure-devops-ecosystem ms.topic: conceptual monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 08/22/2016 +ms.date: 04/11/2025 --- # Extend the work item form [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Learn how to customize how the work item form gets presented to users via contributions that are made through an extension. +This article explains how to use extensions to customize how the work item form gets presented to users. You can extend work item tracking, including adding an action, an observer, a group, or a page to the work item form in Azure DevOps. * [Add a group to the main page](#addagroup) * [Add a page (tab)](#addapage) @@ -23,13 +23,13 @@ Learn how to customize how the work item form gets presented to users via contri * [Listen for events on the form](#listenforevents) * [Configure contributions in work item form](#showcontributions) -See the **UI** example in the [Azure DevOps Extension Samples](https://github.com/Microsoft/vso-extension-samples/tree/master/ui) on GitHub for the full source. +For the full source code, see the **UI** example in the [Azure DevOps extension samples](https://github.com/Microsoft/vso-extension-samples/tree/master/ui) on GitHub. ## Add a group -![Toolbar item in work item form.](./media/add-workitem-extension-group.png) +:::image type="content" source="media/add-workitem-extension-group.png" alt-text="Screenshot that shows the toolbar item in work item form."::: To add a group to the main page, add a contribution to your extension manifest. The type of this contribution should be `ms.vss-work-web.work-item-form-group` and it should target the `ms.vss-work-web.work-item-form` contribution. @@ -50,19 +50,20 @@ To add a group to the main page, add a contribution to your extension manifest. } ] ``` + ### Properties | Property | Description | |--------------|-----------------------| -| ```name``` | Text that appears on the group | -| ```uri``` | URI to a page that hosts the html that shows on the work item form and its scripts -| ```height``` | (Optional) Defines the height of the group. When omitted, it's 100% +| `name` | Text that appears on the group. | +| `uri` | URI to a page that hosts the html that shows on the work item form and its scripts. | +| `height` | (Optional) Defines the height of the group. When omitted, it's 100%. | -### JavaScript sample +### JavaScript sample -This example shows how to register an object that's called when events occur on the work item form that may impact your contributed group. Please see [WorkItemFormGroup Sample](https://github.com/microsoft/azure-devops-extension-sample/blob/master/src/Samples/WorkItemFormGroup/WorkItemFormGroup.tsx) for more examples. +This example shows how to register an object that's called when events occur on the work item form that might affect your contributed group. -```js +```js import { IWorkItemFormService, WorkItemTrackingServiceIds } from "azure-devops-extension-api/WorkItemTracking"; import * as SDK from "azure-devops-extension-sdk"; @@ -116,7 +117,7 @@ SDK.register(SDK.getContributionId(), function () { } } }); -``` +``` [!INCLUDE [Events](../includes/add-workitem-extension-sharedevents.md)] @@ -124,9 +125,9 @@ SDK.register(SDK.getContributionId(), function () { ## Add a page -A new page is rendered as a tab on the work item form. New pages appear next to the Details tab. +A new page is rendered as a tab on the work item form. New pages appear next to the **Details** tab. -![New page as a tab on the work item form.](./media/add-workitem-extension-page.png) +:::image type="content" source="media/add-workitem-extension-page.png" alt-text="Screenshot that shows the new page as a tab on the work item form."::: To add a page to the work item form, add a contribution to your extension manifest. The type of this contribution should be `ms.vss-work-web.work-item-form-page` and it should target the `ms.vss-work-web.work-item-form` contribution. @@ -154,7 +155,7 @@ To add a page to the work item form, add a contribution to your extension manife | name | Text that appears on the tab page. | | uri | URI to a page that hosts the html that shows on the work item form and its scripts. | -### JavaScript sample +### JavaScript sample See the JavaScript sample in the form group section. The name of the registered object should match the `id` of the contribution. @@ -164,15 +165,15 @@ See the JavaScript sample in the form group section. The name of the registered ## Configure contributions in work item form -In Azure DevOps Services, by default the group extensions appear in the end of the second column of the form and page contributions appear after all the work item form pages as a tab. Control contributions are not shown in the form by default so users have to manually add them to the form. In Azure DevOps Server, to show/hide or move the control, group and page contributions in work item form, see [Configure work item form extensions](./configure-workitemform-extensions.md). +In Azure DevOps Services, by default, the group extensions appear in the end of the second column of the form, and page contributions appear after all the work item form pages as a tab. Control contributions aren't shown in the form by default, so users have to manually add them to the form. In Azure DevOps Server, to show/hide or move the control, group and page contributions in work item form, see [Configure work item form extensions](./configure-workitemform-extensions.md). ## Add menu action -![Add an item to the work item toolbar.](./media/add-workitem-extension-toolbar.png) +:::image type="content" source="media/add-workitem-extension-toolbar.png" alt-text="Screenshot that shows how to add an item to the work item toolbar."::: -To add an item to the work item toolbar, add this contribution to your extension manifest. The item appears in the ... dropdown in the top right of the work item form. +To add an item to the work item toolbar, add this contribution to your extension manifest. Select the vertical ellipsis in the work item form to see the dropdown menu. ```json "contributions": [ @@ -194,23 +195,23 @@ To add an item to the work item toolbar, add this contribution to your extension ] ``` - ### Properties + | Property | Description | |--------------|-----------------------| -| text | Text that appears on the toolbar item. | -| title | Tooltip text that appears on the menu item. | -| toolbarText | Text that appears when the item is being hovered over. | -| uri | URI to a page that registers the toolbar action handler. | -| icon | URL to an icon that appears on the menu item. Relative URLs are resolved using baseUri. | -| group | Determines where the menu item appears, related to others. Toolbar items with the same group name are grouped and divided by a separator from the rest of the items. -| registeredObjectId | (Optional) Name of the registered menu action handler. Defaults to the contribution ID. +| `text` | Text that appears on the toolbar item. | +| `title` | Tooltip text that appears on the menu item. | +| `toolbarText` | Text that appears when the item is being hovered over. | +| `uri` | URI to a page that registers the toolbar action handler. | +| `icon` | URL to an icon that appears on the menu item. Relative URLs are resolved using `baseUri`. | +| `group` | Determines where the menu item appears, related to others. Toolbar items with the same group name are grouped and divided by a separator from the rest of the items. | +| `registeredObjectId` | (Optional) Name of the registered menu action handler. Defaults to the contribution ID. | - + ## Listen for events -To add an observer to the work item, which listens to the work item events, add this contribution to your extension manifest. There's no visualization for observers on the work item form. This is the best way to listen to work item form onSaved event since the observer lives outside of the form and doesn't get destroyed when form closes, which might happen right after save. +To add an observer to the work item, which listens to the work item events, add this contribution to your extension manifest. There's no visualization for observers on the work item form. This is the best way to listen to work item form *onSaved* event since the observer lives outside of the form and doesn't get destroyed when form closes, which might happen right after save. ```json "contributions": [ @@ -232,7 +233,7 @@ To add an observer to the work item, which listens to the work item events, add | Property | Description | |--------------|-----------------------| -| uri | URI to a page that hosts the scripts listening to events | +| `uri` | URI to a page that hosts the scripts listening to events. | [!INCLUDE [Events](../includes/add-workitem-extension-sharedevents.md)] @@ -295,3 +296,22 @@ To add an observer to the work item, which listens to the work item events, add ``` + +## Changes with New Boards Hub + +> [!NOTE] +> The New Boards Hub feature is enabled by default. We strongly suggest that you test your internal extensions with the New Boards Hub to ensure compatibility. + +### Use the latest SDKs + +Make sure your extension is using the latest version of [azure-devops-extension-sdk](https://www.npmjs.com/package/azure-devops-extension-sdk) + +When using the new SDK, you should also be using the [azure-devops-extension-api](https://www.npmjs.com/package/azure-devops-extension-api) package for REST APIs. We update the methods and interfaces every sprint to ensure it includes all of the latest features. + +### When to use action or action-provider + +Use `ms.vss-web.action-provider` when dynamically loading menu items using `getMenuItems` on the menu handler. Avoid using `ms.vss-web.action-provider` when your menu items are static and defined in your manifest. Instead `ms.vss-web.action` should be used. + +### Package `require("VSS/Events/Document")` is no longer supported + +`require("VSS/Events/Document")` import is no longer supported with the New Boards Hub. diff --git a/docs/extend/develop/auth-schemes.md b/docs/extend/develop/auth-schemes.md index 07f8bf584fc..39ca8128f2e 100644 --- a/docs/extend/develop/auth-schemes.md +++ b/docs/extend/develop/auth-schemes.md @@ -7,15 +7,14 @@ ms.topic: conceptual monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 09/10/2020 +ms.date: 01/08/2025 --- # Service endpoint authentication schemes [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Learn how to set the credentials in the HTTP request header when you're calling the external endpoint. Azure DevOps can then connect to the external service using the credentials. Azure DevOps supports a closed set of authentication schemes -that can be utilized by a custom service endpoint type. Azure DevOps interprets the authentication scheme that's used in any custom endpoint & support connection to the external service. +Learn how to set the credentials in the HTTP request header when you're calling the external endpoint. Azure DevOps can then connect to the external service using the credentials. Azure DevOps supports a closed set of authentication schemes utilized by a custom service endpoint type. Azure DevOps interprets the authentication scheme that's used in any custom endpoint & support connection to the external service. See the following authentication schemes that are part of the closed set. @@ -23,61 +22,7 @@ See the following authentication schemes that are part of the closed set. ## Basic authentication -This scheme takes two inputs - Username & Password (confidential) - -Default authentication header used is: "Basic {{ #base64 endpoint.username \":\" endpoint.password }}" - -```json -{ - "id": "endpoint-auth-scheme-basic", - "description": "Basic Authentication based endpoint authentication scheme", - "type": "ms.vss-endpoint.service-endpoint-type", - "targets": [ - "ms.vss-endpoint.endpoint-types" - ], - "properties": { - "name": "UsernamePassword", - "displayName": "i18n:Basic Authentication", - "authenticationSchemes": [ - { - "type": "ms.vss-endpoint.endpoint-auth-scheme-basic", - "headers": [ - { - "name": "Authorization", - "value": "Basic {{ #base64 endpoint.username \":\" endpoint.password }}" - } - ], - "inputDescriptors": [ - { - "id": "username", - "name": "i18n:Username", - "description": "i18n:Username for connecting to the endpoint", - "inputMode": "textbox", - "isConfidential": false, - "validation": { - "isRequired": true, - "dataType": "string", - "maxLength": 300 - } - }, - { - "id": "password", - "name": "i18n:Password", - "description": "i18n:Password for connecting to the endpoint", - "inputMode": "passwordbox", - "isConfidential": true, - "validation": { - "isRequired": true, - "dataType": "string", - "maxLength": 300 - } - } - ] - } - ] - } -} -``` +As a security measure, we recommend using service principals & managed identities over basic authentication. For more information, see [Use service principals & managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md). ## Token-based authentication diff --git a/docs/extend/develop/auth.md b/docs/extend/develop/auth.md index 1598a084056..57444e15d7d 100644 --- a/docs/extend/develop/auth.md +++ b/docs/extend/develop/auth.md @@ -1,50 +1,53 @@ --- ms.subservice: azure-devops-ecosystem -title: Auth and Security | Extensions for Azure DevOps -description: Learn about authentication and security for Azure DevOps extensions. +title: Authenticate and Secure | Extensions for Azure DevOps +description: Learn how to authenticate requests to your service and call REST APIs from your Azure DevOps extension. ms.assetid: c1704b14-66d2-4950-8633-a63fc8f88508 -ms.topic: conceptual +ms.topic: how-to monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 08/29/2016 +ms.date: 07/10/2024 --- -# Auth and security +# Authenticate and secure web extensions [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -This article pertains only to _web extensions_, and not Pipelines task extensions or service endpoint extensions. For those tasks, you can use the [Publish to Azure Service Bus Task](/azure/devops/pipelines/tasks/reference/publish-to-azure-service-bus-v1). +This article pertains only to authentication and security for _web extensions_, and not Pipelines task extensions or service endpoint extensions. For those tasks, you can use the [Publish to Azure Service Bus Task](/azure/devops/pipelines/tasks/reference/publish-to-azure-service-bus-v1). -[!INCLUDE [extension-docs-new-sdk](../../includes/extension-docs-new-sdk.md)] - -## Calling REST APIs from your extension +## Call REST APIs from your extension -Most extensions have a need to call Azure DevOps REST APIs on behalf of the current user. -* If you are using the provided `JavaScript REST clients`, authentication is automatically handled for you. These clients automatically request an access token from the core SDK and set it in the Authorization header of the request. -* If you are not using the provided clients, you need to request a token from the `Core SDK` and set it in the Authorization header of your request: +Most extensions need to call Azure DevOps REST APIs on behalf of the current user. +* If you're using the provided `JavaScript REST clients`, authentication is automatically handled for you. These clients request an access token from the core SDK and set it in the Authorization header of the request. +* If you're not using the provided clients, you need to request a token from the `Core SDK` and set it in the Authorization header of your request: ```javascript - VSS.require(["VSS/Authentication/Services"], - function (VSS_Auth_Service) { - VSS.getAccessToken().then(function(token){ - // Format the auth header - var authHeader = VSS_Auth_Service.authTokenManager.getAuthorizationHeader(token); - - // Add token as an Authorization header to your request - }); - }); + import * as SDK from "azure-devops-extension-sdk"; + import { getAccessToken } from "azure-devops-extension-sdk"; + + SDK.init(); + + getAccessToken().then((token) => { + // Format the auth header + const authHeader = `Bearer ${token}`; + + // Add token as an Authorization header to your request + console.log(authHeader); + }); ``` -## Authenticating requests to your service +[!INCLUDE [extension-docs-new-sdk](../../includes/extension-docs-new-sdk.md)] + +## Authenticate requests to your service -A common scenario is to make calls to a back-end service from an extension. To verify these calls are coming from your extension running in Azure DevOps and to verify the authenticity of the current user (and other context information), a special type of token is made available to your extension. This token contains information about who is making the call and also a signature that you can validate to know that the request came from your extension. +A common scenario is making calls to a back-end service from an extension. To verify these calls are coming from your extension running in Azure DevOps and to authenticate the current user, and other context information, a special type of token is provided to your extension. This token contains information about the caller and a signature that you can validate to ensure the request originated from your extension. ### Get your extension's key -Your extension's unique key (which is generated when the extension is published) can be used to verify the authenticity of requests made from your extension. +Your extension's unique key, generated when the extension is published, can be used to verify the authenticity of requests made from your extension. -To get this key, right-click a [published extension](../publish/overview.md) and select **Certificate**. +To obtain this key, go to the [extension management portal](https://aka.ms/vsmarketplace-manage), right-click on a [published extension](../publish/overview.md), and then select **Certificate**. ![key](./media/get-extension-key.png) @@ -53,11 +56,17 @@ To get this key, right-click a [published extension](../publish/overview.md) and ### Generate a token to provide to your service -1. The Core SDK `getAppToken` method return a promise that, when resolved, contains a token signed with your extension's certificate. +1. The Core SDK `getAppToken` method returns a promise that, when resolved, contains a token signed with your extension's certificate. ```javascript - VSS.getAppToken().then(function(token){ - // Add token to your request + import * as SDK from "azure-devops-extension-sdk"; + import { getAppToken } from "azure-devops-extension-sdk"; + + SDK.init(); + + getAppToken().then((token) => { + // Add token to your request + console.log(token); }); ``` @@ -65,52 +74,55 @@ To get this key, right-click a [published extension](../publish/overview.md) and ### Parse and validate the token -Here is a sample of parsing the token. First download and store the secret for your extension. You can get this from your publisher page. This secret needs to be available to your application. +Here is a sample of parsing the token. First, download and store the secret for your extension from your publisher page. This secret must be available to your application. #### .NET Framework -You must add 1 reference to get this sample to compile. +Do the following task to add one reference to get the sample to compile. -1. Open the NuGet Package Manager and add a reference to *System.IdentityModel.Tokens.Jwt*. This sample was built with version 5.2.2 of this package. +Open the NuGet Package Manager and add a reference to `System.IdentityModel.Tokens.Jwt`. This sample was built with version 6.8.0 of this package. ```csharp -using System.Collections.Generic; -using System.ServiceModel.Security.Tokens; +using System; +using System.IdentityModel.Tokens.Jwt; using Microsoft.IdentityModel.Tokens; namespace TokenSample { - class Program - { - static void Main(string[] args) - { - string secret = ""; // Load your extension's secret - string issuedToken = ""; // Token you are validating - - var validationParameters = new TokenValidationParameters() - { - IssuerSigningKey = new SymmetricSecurityKey(System.Text.UTF8Encoding.UTF8.GetBytes(secret)), - ValidateIssuer = false, - RequireSignedTokens = true, - RequireExpirationTime = true, - ValidateLifetime = true, - ValidateAudience = false, - ValidateActor = false - }; - - SecurityToken token = null; - var tokenHandler = new JwtSecurityTokenHandler(); - var principal = tokenHandler.ValidateToken(issuedToken, validationParameters, out token); - } - } + class Program + { + static void Main(string[] args) + { + string secret = ""; // Load your extension's secret + string issuedToken = ""; // Token you are validating + + var validationParameters = new TokenValidationParameters() + { + IssuerSigningKey = new SymmetricSecurityKey(System.Text.Encoding.UTF8.GetBytes(secret)), + ValidateIssuer = false, + RequireSignedTokens = true, + RequireExpirationTime = true, + ValidateLifetime = true, + ValidateAudience = false, + ValidateActor = false + }; + + SecurityToken token = null; + var tokenHandler = new JwtSecurityTokenHandler(); + var principal = tokenHandler.ValidateToken(issuedToken, validationParameters, out token); + + // Use the principal object as needed + Console.WriteLine(principal.Identity.Name); + } + } } ``` #### .NET Core - WebAPI -You must add 1 reference to get this sample to compile. +Do the following task to add one reference to get this sample to compile. -1. Open the NuGet Package Manager and add a reference to *System.IdentityModel.Tokens.Jwt*. This sample was built with version 5.1.4 of this package. +Open the NuGet Package Manager and add a reference to `System.IdentityModel.Tokens.Jwt`. This sample was built with version 5.1.4 of this package. **Startup.cs** @@ -120,6 +132,7 @@ using Microsoft.AspNetCore.Authentication.JwtBearer; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Hosting; using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; using Microsoft.IdentityModel.Tokens; namespace TokenSample.Core.API @@ -135,10 +148,10 @@ namespace TokenSample.Core.API public void ConfigureServices(IServiceCollection services) { - services.AddMvc(); + services.AddControllers(); string _secret = "ey9asfasdmax...9faf7eh"; - + services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer((o) => { @@ -155,12 +168,22 @@ namespace TokenSample.Core.API }); } - public void Configure(IApplicationBuilder app, IHostingEnvironment env) + public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { + if (env.IsDevelopment()) + { + app.UseDeveloperExceptionPage(); + } + app.UseAuthentication(); app.UseAuthorization(); - app.UseMvc(); + app.UseRouting(); app.UseStaticFiles(); + + app.UseEndpoints(endpoints => + { + endpoints.MapControllers(); + }); } } } @@ -169,11 +192,13 @@ namespace TokenSample.Core.API **Your API Controllers:** ```csharp -[Route("api/[controller]"), - Authorize()] -public class SampleLogicController : Controller +using Microsoft.AspNetCore.Authorization; +using Microsoft.AspNetCore.Mvc; + +[Route("api/[controller]")] +[Authorize] +public class SampleLogicController : ControllerBase { // ... } ``` - diff --git a/docs/extend/develop/custom-control.md b/docs/extend/develop/custom-control.md index 6d7c6d8489f..55ae75fd448 100644 --- a/docs/extend/develop/custom-control.md +++ b/docs/extend/develop/custom-control.md @@ -8,17 +8,29 @@ ms.topic: conceptual monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 10/14/2022 +ms.date: 09/09/2024 --- # Add a custom control to the work item form [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Custom controls allow you to change how users view and interact with a field on the work item form. The following article walks you through how this sample custom control was built. Learn how to build your own custom control. +Custom controls allow you to change how users view and interact with a field on the work item form. The following article walks you through how this sample custom control was built. This article shows you how to build your own custom control. [!INCLUDE [extension-docs-new-sdk](../../includes/extension-docs-new-sdk.md)] +## Prerequisites + +Include the azure-devops-extension-sdk in your project: + +1. Install the SDK via npm: `npm install azure-devops-extension-sdk`. +2. Initialize it in your JavaScript code: + + ```javascript + import * as SDK from "azure-devops-extension-sdk"; + SDK.init(); + ``` + ## Add the custom control To add a control to the main page, add a contribution to your [extension manifest](../develop/manifest.md). The type of contribution should be `ms.vss-work-web.work-item-form-control` @@ -39,7 +51,11 @@ and it should target the `ms.vss-work-web.work-item-form` contribution. "height": 600 } } -] +], +"manifestVersion": 1.0, + "scopes": [ + "vso.work" + ] ``` The work item form adds an IFrame to host the custom control. @@ -82,6 +98,7 @@ The values for the inputs get provided by the users when they add to the work it { "id": "Colors", "description": "The colors that match the values in the control.", + "type": "string", "validation": { "dataType": "String", "isRequired": false @@ -129,28 +146,33 @@ A control extension works like a group or page extension with one difference tha ```typescript import { Control } from "control"; -import * as ExtensionContracts from "TFS/WorkItemTracking/ExtensionContracts"; +import * as SDK from "azure-devops-extension-sdk"; +import * as ExtensionContracts from "azure-devops-extension-api/WorkItemTracking/WorkItemTracking"; -var control: Control; +let control; -var provider = () => { +const provider = () => { return { - onLoaded: (workItemLoadedArgs: ExtensionContracts.IWorkItemLoadedArgs) => { + onLoaded: (workItemLoadedArgs) => { // create the control - var fieldName = VSS.getConfiguration().witInputs["FieldName"]; - var colors = VSS.getConfiguration().witInputs["Colors"]; + const config = SDK.getConfiguration(); + const fieldName = config.witInputs["FieldName"]; + const colors = config.witInputs["Colors"]; control = new Control(fieldName, colors); }, - onFieldChanged: (fieldChangedArgs: ExtensionContracts.IWorkItemFieldChangedArgs) => { - var changedValue = fieldChangedArgs.changedFields[control.getFieldName()]; + onFieldChanged: (fieldChangedArgs) => { + const changedValue = fieldChangedArgs.changedFields[control.getFieldName()]; if (changedValue !== undefined) { control.updateExternal(changedValue); } } - } + }; }; -VSS.register(VSS.getContribution().id, provider); +SDK.init(); +SDK.ready().then(() => { + SDK.register(SDK.getContributionId(), provider); +}); ``` The following screenshot shows a sample custom work item control for the *Priority* field. diff --git a/docs/extend/develop/data-storage.md b/docs/extend/develop/data-storage.md index 2772393694d..e0e5a198dd9 100644 --- a/docs/extend/develop/data-storage.md +++ b/docs/extend/develop/data-storage.md @@ -1,22 +1,22 @@ --- ms.subservice: azure-devops-ecosystem title: Data and Setting Storage | Extensions for Azure DevOps -description: DevOps extensions can store user preferences and complex data structures just like other project data. Use REST APIs or a Microsoft client service to do this. +description: DevOps extensions can store user preferences and complex data structures just like other project data. Use REST APIs or a Microsoft client service to do so. ms.assetid: 4662d1cf-ddb6-4079-8eb4-6f553861c1b4 ms.topic: conceptual monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 08/04/2016 +ms.date: 11/28/2023 --- # Data storage [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Azure DevOps extensions have the ability to store user preferences and complex data structures directly on Microsoft-provided infrastructure. This ensures your user's data is secure and backed up just like other organization and project data. It also means for simple data storage needs, you (as the extension provider) are not required to set up or manage (or pay for) third-party data storage services. +Azure DevOps extensions can store user preferences and complex data structures directly on Microsoft-provided infrastructure, which ensures your user's data is secure and backed up just like other organization and project data. It also means for simple data storage needs, you, as the extension provider, aren't required to set up, manage, or pay for third-party data storage services. -There are two ways to interact with the data storage service: REST APIs or a Microsoft-provided client service available as part of the VSS SDK. It's highly recommended that extension developers use the provided client service APIs, which provide a convenient wrapper over the REST APIs. +There are two methods to engage with the data storage service: through REST APIs or via a client service provided by Microsoft, which is part of the VSS SDK. We advise extension developers to utilize the provided client service APIs, as they offer a user-friendly encapsulation of the REST APIs. [!INCLUDE [rest-api-docs-rollout](../../includes/rest-api-docs-rollout.md)] @@ -27,7 +27,7 @@ The service is designed to let you store and manage two different types of data: - **Settings**: simple key-value settings (like user preferences) - **Documents**: collections of similar complex objects (documents) -A collection is as an indexed container for documents. A document is a JSON blob that belongs to a collection. Other than a few reserved property names, the schema of these documents is controlled and managed by you. +A collection is as an indexed container for documents. A document is a JSON blob that belongs to a collection. Other than a few reserved property names, you control and manage the schema of these documents. ### How you can scope data @@ -36,23 +36,35 @@ Settings and document collections can be scoped to either the: - **Project Collection**: shared by all users of the project collection to which the extension is installed - **User**: a single user of a project collection to which the extension is installed -## Setting storage +## Settings storage -The two primary functions for interacting with settings are getValue() and setValue(): +The two main methods for managing settings are `getValue()` and `setValue()`: -* `getValue()` takes a string key (and other options such as scope) and returns an IPromise. The resolution of this promise contains a value for the provided key. -* `setValue()` take a string key and a value (and other options such as scope) and returns an IPromise. The resolution this promise contains the new value of the setting. +* `getValue()` accepts a string key (along with other options like scope) and returns an IPromise. The resolved value of this promise is the value associated with the provided key. +* `setValue()` accepts a string key, a value, and other options such as scope, and returns an IPromise. The resolved value of this promise is the updated value of the setting. Here's an example of how to set a value: ```js - // Get data service - SDK.getService(SDK.getContributionId()).then(function(dataService) { - // Set value in user scope - dataService.setValue("userScopedKey", 12345, {scopeType: "User"}).then(function(value) { - console.log("User scoped key value is " + value); + private async initializeState(): Promise { + await SDK.ready(); + const accessToken = await SDK.getAccessToken(); + const extDataService = await SDK.getService(CommonServiceIds.ExtensionDataService); + this._dataManager = await extDataService.getExtensionDataManager(SDK.getExtensionContext().id, accessToken); + + this._dataManager.getValue("test-id").then((data) => { + this.setState({ + dataText: data, + persistedText: data, + ready: true + }); + }, () => { + this.setState({ + dataText: "", + ready: true + }); }); - }); + } ``` Here's an example of how to retrieve a setting value: @@ -82,7 +94,7 @@ Here's an example of how to set a setting value at the project collection level: ## Data (collections of documents) storage -For interacting with richer data beyond key-value pairs, you can use the concepts of documents to perform CRUD operations on their extension's data. A document is a JSON blob, augmented with two special properties: ID and `__etag`. IDs can be user-defined if they are important an extension's data model, or, if left undefined, gets generated by the system. These IDs must be unique within a particular collection. Because a collection references a particular scope and instance of an extension, this means that the same document ID can be used across different collections. +To handle more complex data beyond key-value pairs, you can utilize the concept of documents to execute CRUD operations on your extension's data. A document is a JSON blob, enhanced with two special properties: ID and `__etag`. If they're crucial to an extension's data model, IDs can be user-defined, or if left unspecified, the system generates them. These IDs must be unique within a specific collection. Since a collection refers to a particular scope and instance of an extension, it implies that the same document ID can be reused across different collections. The following document operations are available: @@ -92,13 +104,24 @@ The following document operations are available: * Update a document * Delete a document -There's also a single operation that can be performed on a collection: - -* Get all documents +There's also a single operation that can be performed on a collection: Get all documents ### Get a document by ID -Retrieving a document by its identifier from a collection is easy: +Obtaining a document from a collection using its identifier is straightforward, like the following example: + +```js + // Acquire data service + SDK.getService(SDK.getContributionId()).then(function(dataService) { + // Retrieve document by id + dataService.getDocument("MyCollection", "MyDocumentId").then(function(doc) { + // Assuming document has a property named foo + console.log("Doc foo: " + doc.foo); + }); + }); +``` + +This operation tries to fetch a document with the ID "MyDocumentId" from the "MyCollection" collection. In the absence of a provided scope, the service defaults to using the collection scoped to the entire instance of this extension. If either this collection or a document with the specified ID doesn't exist, a 404 error is returned, which the extension should handle. The returned document is a JSON object that includes all its properties, along with the special ID and `__etag` properties utilized by the data storage service. ```js // Get data service @@ -111,11 +134,11 @@ Retrieving a document by its identifier from a collection is easy: }); ``` -This call attempts to retrieve a document with the ID "MyDocumentId", from the collection "MyCollection". Since no scope is provided, the collection that the service uses gets scoped to the default of the entire instance of this extension. If this collection doesn't exist or a document with that ID doesn't exist, then a 404 gets returned, which should be handled by the extension. The document that is returned is a JSON object containing all of its own properties, in addition to the special ID and `__etag` properties used by the data storage service. +This call attempts to retrieve a document with the ID "MyDocumentId," from the collection "MyCollection." Since no scope is provided, the collection that the service uses gets scoped to the default of the entire instance of this extension. If this collection doesn't exist or a document with that ID doesn't exist, then a 404 gets returned, which the extension should handle. The document that is returned is a JSON object containing all of its own properties, in addition to the special ID and `__etag` properties used by the data storage service. ### Create a document -To create a new document, perform a call such as the following: +To create a new document, perform a call like the following example: ```js // Get data service @@ -136,13 +159,13 @@ To create a new document, perform a call such as the following: If the collection with the name and scope provided, doesn't yet exist, it gets created dynamically before the document itself is created. -If the document provided contains an `id` property, that value gets used as the unique ID for the document. If that field doesn't exist, a GUID gets generated by the service and included on the document that is returned when the promise is resolved. +If the document provided contains an `id` property, that value gets used as the unique ID for the document. Please note that the provided `id` should be limited to 50 characters. If that field doesn't exist, a GUID gets generated by the service and included on the document that is returned when the promise is resolved. If another document in the collection already exists with the same ID as the one provided on the document, the operation fails. If the desired behavior is create a new document if the ID doesn't exist, but modify the existing document if it does, then the `setDocument()` method should be used. ### Set a document (update or create) -`setDocument()` performs the equivalent of an "upsert" operation - modifying an existing document if there's an ID on the document provided that exists in the collection. If the ID doesn't exist, or no ID was provided, then a new document gets added to the collection. +The `setDocument()` function carries out an "upsert" operation - it modifies an existing document if its ID is present and matches a document in the collection. If the ID is absent or doesn't correspond to any document in the collection, then a new document is added to the collection. ```js // Get data service @@ -163,7 +186,7 @@ If another document in the collection already exists with the same ID as the one ### Update a document -updateDocument requires that the document which is being modified already exists in the collection. If no ID is provided or the ID provided on the document doesn't exist in the collection, then an exception is thrown. +The `updateDocument` function requires that the document being altered already resides in the collection. An exception is thrown if no ID is supplied or if the provided ID doesn't correspond to any document in the collection. Here's an example of how update is used: @@ -202,7 +225,7 @@ Here's an example usage: ### Get all documents in a collection -In addition to the operations on documents themselves, the data storage service provides a single operation on collections - retrieving all documents within a single collection. This call looks like the following: +The following example retrieves all documents from the "MyCollection" collection using the data service, and then logs the number of documents to the console: ```js // Get data service @@ -215,21 +238,21 @@ In addition to the operations on documents themselves, the data storage service ``` -This call returns all documents within a scoped collection, up to 100,000 documents. If the collection doesn't exist, a 404 gets returned. +This call retrieves all documents in a scoped collection, with a limit of 100,000 documents. If the collection is nonexistent, it returns a 404 error. ### Advanced -#### How settings are stored +#### How settings get stored -This call wraps the setDocument client method, passing it several pieces of information. As previously mentioned, settings are stored as documents internally, so a simple document is created on the fly, where the ID of the document, is the key that was provided in the setValue() method. There are two additional properties on the document. One is 'value', which contains value passed to the method. The other is 'revision', which is set to -1. The revision property gets discussed in more detail in the "Working with Documents" section, but in the context of settings, by passing revision: -1 in the document, we're indicating that we do not care about the versioning of this setting document. +This call encapsulates the `setDocument` client method, supplying it with multiple pieces of data. As stated before, settings are internally saved as documents. Therefore, a basic document is dynamically generated, where the document's ID is the key given in the `setValue()` method. The document has two more properties. The `value` property holds the value passed to the method, and the `revision` property is set to `-1`. While the `revision` property is elaborated more in the "Working with Documents" section, in the context of settings, setting `revision` to `-1` in the document signifies that we're not concerned with the versioning of this settings document. -Because settings are stored as documents, we need to provide a collection name, indicating where to store the document. To keep things simple, when working with the setValue()/getValue() methods, the collection name is always the special name '$settings'. The previous call issues a PUT Request at the following endpoint: +Because settings are stored as documents, we need to provide a collection name, indicating where to store the document. To keep things simple, when working with the `setValue()`/`getValue()` methods, the collection name is always the special name `$settings`. The previous call issues a PUT Request at the following endpoint: ```httprequest GET _apis/ExtensionManagement/InstalledExtensions/{publisherName}/{extensionName}/Data/Scopes/User/Me/Collections/%24settings/Documents ``` -The request payload would be the following: +The request payload is like the following example: ```json { @@ -240,7 +263,7 @@ The request payload would be the following: ``` #### REST APIs -Assuming this snippet is executed after the value has already been set, you should see an alert message containing the text "The value is myValue". The getValue method is again a wrapper around the REST APIs, issuing a GET request to the following endpoint: +Assuming this snippet is executed after the value is set, you should see an alert message containing the text "The value is myValue." The getValue method is again a wrapper around the REST APIs, issuing a GET request to the following endpoint: ```httprequest GET _apis/ExtensionManagement/InstalledExtensions/{publisherName}/{extensionName}/Data/Scopes/User/Me/Collections/%24settings/Documents/myKey @@ -248,6 +271,6 @@ GET _apis/ExtensionManagement/InstalledExtensions/{publisherName}/{extensionName #### etags -The `__etag` field is how the Data Storage Service handles document concurrency. Before an update to a document is stored by the service, a check is performed to verify that the `__etag` of the document currently stored is equal to the `__etag` of the document passed as part of the updated. If this check succeeds, the `__etag` is incremented, and the new document is returned to the caller. If this check fails, it means that the document that was attempted to be updated was out of date, and an exception gets thrown. It is up to the extension writer to gracefully handle this exception, by either getting the latest `__etag` of the document merging the changes, and re-attempting the update, or bubbling up a message to the user. +The `__etag` field is used by the Data Storage Service for document concurrency management. Before an update is saved, the service verifies that the `__etag` of the currently stored document matches the `__etag` of the updated document. If they match, the `__etag` is incremented and the updated document is returned to the caller. If they don't match, it indicates that the document to be updated is outdated, and an exception is thrown. The extension writer is responsible for handling this exception gracefully, either by retrieving the latest `__etag` of the document, merging the changes, and retrying the update, or by notifying the user. -There may be certain types of documents where this level of concurrency is not needed, and a last-in-wins model is what is desired. For these cases, when editing the document, pass -1 as the `__etag` value, to indicate this type of functionality. The settings service previously described uses this model for saving settings and preferences. +For some types of documents, the level of concurrency provided might not be necessary, and a last-in-wins model might be more suitable. In such cases, while editing the document, input -1 as the `__etag` value to signify this functionality. The previously mentioned settings service employs this model for storing settings and preferences. diff --git a/docs/extend/develop/integrate-build-task.md b/docs/extend/develop/integrate-build-task.md index 07a69e10769..6a7344e39f4 100644 --- a/docs/extend/develop/integrate-build-task.md +++ b/docs/extend/develop/integrate-build-task.md @@ -1,16 +1,16 @@ --- ms.subservice: azure-devops-ecosystem -title: Custom build/release task reference | Extensions for Azure DevOps -description: Reference for creating and integrating custom build or release tasks with an extension in Azure DevOps. +title: Integrate Custom Build Tasks with Extensions +description: Learn how to create and integrate custom build pipeline tasks with extensions in Azure DevOps. ms.assetid: 00806e48-3839-40eb-880f-12ec53bfdf73 -ms.topic: conceptual +ms.topic: concept-article monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 09/23/2020 +ms.date: 04/11/2025 --- -# Reference - integrate custom build tasks into extensions +# Integrate custom build pipeline tasks with extensions [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -20,18 +20,17 @@ Use this reference when you want to create and integrate custom build pipeline t ## Custom tasks -[Tasks](../../pipelines/process/tasks.md) are the building blocks for defining automation in a build or release pipeline. We offer many [built-in tasks](../../pipelines/tasks/index.md) -to enable fundamental build and deployment scenarios. We recommend that you review these scenarios before building your own. If the existing tasks don't satisfy your needs, you can build a [custom task](add-build-task.md). +Tasks are the building blocks for defining automation in a build or release pipeline. To learn more, see [Task types & usage](../../pipelines/process/tasks.md). + +We offer many [built-in tasks](../../pipelines/tasks/index.md) to enable fundamental build and deployment scenarios. We recommend that you review these scenarios before building your own. If the existing tasks don't satisfy your needs, you can build a [custom task](add-build-task.md). ## Custom build task JSON -When you're creating a custom build or release task with an extension, your extension includes a `task.json` file for each build or release task. -The `task.json` file describes the build or release task. The build system uses it to render configuration options to the user and to know which scripts to execute at build time. +When you create a custom build or release task with an extension, your extension includes a *task.json* file for each build or release task. The *task.json* file describes the build or release task. The build system uses it to render configuration options to the user and to know which scripts to execute at build time. -The build/release task SDK documentation is [on GitHub](https://github.com/Microsoft/azure-pipelines-task-lib). -Specifically, you may be interested in the [task.json schema](https://github.com/Microsoft/azure-pipelines-task-lib/blob/master/tasks.schema.json). +To learn more, see the [build and release task SDK documentation](https://github.com/Microsoft/azure-pipelines-task-lib) on GitHub. Specifically, you might be interested in the [task.json schema](https://github.com/Microsoft/azure-pipelines-task-lib/blob/master/tasks.schema.json). -## Bundle multiple versions of build/release tasks within one extension +## Bundle multiple versions of build or release tasks within one extension You can include multiple versions of a build or release task within your extension. Roll out future versions of your extension without interrupting service of users on older versions. The following information shows the layout for having multiple versions in one extension. @@ -47,14 +46,14 @@ You can include multiple versions of a build or release task within your extensi > [!NOTE] > When you're setting up a task icon, ensure the following is true. > -> * The icon name is icon.png +> * The icon name is *icon.png* > * The icon size is 32x32 pixels -> * The icon is in the same location as the `task.json` file +> * The icon is in the same location as the *task.json* file ### Multiple versions layout >[!NOTE] ->The code looks for the `task.json` file inside of the task folder and then one level deeper. +>The code looks for the *task.json* file inside the task folder and then one level deeper. >If one isn't found in either level, you see an error message. * extensionManifest.json @@ -79,10 +78,10 @@ You can include multiple versions of a build or release task within your extensi * taskScript.ps1 > [!TIP] -> To ensure the `_build/Tasks/ssrsfilesdeploy` folder contains the V1 and V2 contents, set `matchCopy(item, srcPath, destPath, { noRecurse:` to `false` in the `make-util.js` file. +> To ensure the *_build/Tasks/ssrsfilesdeploy* folder contains the V1 and V2 contents, set `matchCopy(item, srcPath, destPath, { noRecurse:` to `false` in the *make-util.js* file. -## Related articles +## Related content * [Add a custom pipelines task extension](add-build-task.md) -* [Server Task GitHub Documentation](https://github.com/Microsoft/azure-pipelines-tasks/blob/master/docs/authoring/servertaskauthoring.md) -* [Build/Release Task Examples](https://github.com/Microsoft/vso-agent-tasks/tree/master/Tasks) +* [Server Task Authoring](https://github.com/Microsoft/azure-pipelines-tasks/blob/master/docs/authoring/servertaskauthoring.md) +* [Build and release task examples](https://github.com/Microsoft/vso-agent-tasks/tree/master/Tasks) diff --git a/docs/extend/develop/manifest.md b/docs/extend/develop/manifest.md index 572d9e62778..acec9e3ebf4 100644 --- a/docs/extend/develop/manifest.md +++ b/docs/extend/develop/manifest.md @@ -7,7 +7,7 @@ ms.topic: conceptual monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 01/06/2023 +ms.date: 03/21/2025 --- # Extension manifest reference @@ -24,9 +24,11 @@ See the following example of a typical manifest: [!code-json[](../_data/extension-typical.json)] +For information about inputs, see [...](custom-control.md) + ## Required attributes - + [!INCLUDE [](../includes/manifest-core.md)] @@ -47,11 +49,11 @@ See the following example of a typical manifest: [!INCLUDE [](../includes/manifest-discovery.md)] - + #### Mark an extension public -By default, all extensions in the [Azure DevOps Marketplace](https://marketplace.visualstudio.com/azuredevops/) are private. They're only visible to the publisher and accounts shared to by the publisher. If your publisher has been verified, you can make your extension public by setting the `Public` flag in your extension manifest: +By default, all extensions in the [Azure DevOps Marketplace](https://marketplace.visualstudio.com/azuredevops/) are private. They are hidden from public view, and are only visible to the publisher and specific accounts shared to by the publisher. If your publisher is verified, you can make your extension public by setting the `Public` flag in your extension manifest: ```json { @@ -110,7 +112,7 @@ If you want to sell your extension on the Marketplace, you can mark it with the } ``` -Both the `Paid` flag and `__BYOLENFORCED` tag need to be present to mark an extension as paid in the Marketplace. Bring-Your-Own-License (BYOL) means the publisher of the extension provides the billing and licensing mechanism for the extension, as it isn't provided by Microsoft for Azure DevOps extensions. All paid extensions are required to define privacy policy, support policy, and an end-user license agreement. Also, publishers must provide content for the pricing tab in Marketplace as follows: +Both the `Paid` flag and `__BYOLENFORCED` tag need to be present to mark an extension as paid in the Marketplace. Bring-Your-Own-License (BYOL) means the publisher of the extension provides the billing and licensing mechanism for the extension, as it isn't provided by Microsoft for Azure DevOps extensions. All paid extensions are required to define privacy policy, support policy, and an end-user license agreement. Publishers must provide content for the pricing tab in Marketplace as follows: ```json { @@ -125,7 +127,8 @@ Both the `Paid` flag and `__BYOLENFORCED` tag need to be present to mark an exte } ``` -You also need to add a new section in your extension manifest to override paid licensing. In the future, we'll remove the paid licensing check and no longer require the override. For now, ensure your extension displays as expected. Each override consists of an “ID” and a “behavior.” The “ID” must match the ID of the contributions defined in the manifest. +You also need to add a new section in your extension manifest to override paid licensing. In the future, we remove the paid licensing check and no longer require the override. For now, ensure your extension displays as expected. Each override consists of an "ID" and a "behavior." Make the "ID" match the ID of the contributions defined in the manifest. + ```json "licensing": { @@ -147,8 +150,8 @@ If your paid BYOL extension offers a trial period (we recommend so), then you ca ``` > [!NOTE] -> If you want to target TFS, but don't wish to surface a **Download** option for your extension, then add the `__DoNotDownload` tag (starts with two underscores) to the extension manifest. -> If you're moving an extension from the previously-offered billing & licensing from Microsoft to the BYOL model, then contact us and we'll provide you with suitable steps. +> If you want to target Azure DevOps, but don't wish to surface a **Download** option for your extension, then add the `__DoNotDownload` tag (starts with two underscores) to the extension manifest. +> If you're moving an extension from the previously offered billing & licensing from Microsoft to the BYOL model, then contact us for suitable steps. ### Example of more properties @@ -170,13 +173,13 @@ If your paid BYOL extension offers a trial period (we recommend so), then you ca ### Marketplace Q & A - CustomerQnASupport property -All extensions on the Visual Studio Marketplace have a Q&A section to allow one-on-one public conversations between extension users and publishers. Publishers can choose between Marketplace Q&A, GitHub issues, or a custom Q&A URL. You can disable Q&A in the Marketplace using the CustomerQnASupport property in the manifest. +All extensions on the Visual Studio Marketplace have a Questions and Answers (Q & A) section to allow one-on-one public conversations between extension users and publishers. Publishers can choose between Marketplace Q & A, GitHub issues, or a custom Q & A URL. You can disable Q & A in the Marketplace using the `CustomerQnASupport` property in the manifest. **Default experience** (No changes to manifest are required) - For extensions with a GitHub repository, Marketplace redirects users in the Q&A section to the associated GitHub issues. - For extensions without a GitHub repository, Marketplace Q&A is enabled. -For a different experience than one of the default options, use the **CustomerQnASupport** property in the manifest. +For a different experience than one of the default options, use the `CustomerQnASupport` property in the manifest. ```json @@ -192,7 +195,7 @@ For a different experience than one of the default options, use the **CustomerQn Properties for the Customer Q & A Support section: -- **enablemarketplaceqna** - boolean field, set to true for marketplace or custom Q&A; false for disabling Q&A +- **enablemarketplaceqna** - boolean field, set to `true` for marketplace, or custom Q&A; false for disabling Q&A - **url** - string, URL for custom Q&A @@ -229,7 +232,7 @@ Properties for the Customer Q & A Support section: ## Scopes -Your extension can specify one or more scopes. Scopes control what resources can be accessed by your extension and what operations your extension is allowed to do with those resources. The scopes you specify in your extension manifest are the scopes set on access tokens issued to your extension. For more information, see [Auth and security](auth.md). +In your extension, you can define one or more scopes. These scopes determine which resources your extension can access and the operations permitted to perform on those resources. The scopes you specify in your extension manifest are the scopes set on access tokens issued to your extension. For more information, see [Auth and security](auth.md). If no scopes are specified, extensions are only provided access to user profile and extension data. @@ -239,7 +242,7 @@ If no scopes are specified, extensions are only provided access to user profile ### Changing scope of published extension -You can change the scope of a published extension. If you previously installed your extension (and authorized the previous set of scopes), you must authorize the new scopes before you can upgrade to the newest version. +You can change the scope of a published extension. If you previously installed your extension (and authorized the previous set of scopes), authorize the new scopes before you can upgrade to the newest version. The **Action Required** section of the Extension settings hub shows a user that, if any, installed extensions require authorization: @@ -258,13 +261,13 @@ The installation targets for an extension or integration are specified via the ` Supported identifiers for **extensions**: * `Microsoft.VisualStudio.Services.Cloud`: installs into Azure DevOps Services -* `Microsoft.TeamFoundation.Server`: installs into TFS +* `Microsoft.TeamFoundation.Server`: installs into Azure DevOps Server * `Microsoft.VisualStudio.Services`: installs into both. Shortcut for `Microsoft.VisualStudio.Services.Cloud` and `Microsoft.TeamFoundation.Server` version `[14.2,)` Supported identifiers for **integrations**: * `Microsoft.VisualStudio.Services.Cloud.Integration`: integrates with Azure DevOps Services -* `Microsoft.TeamFoundation.Server.Integration`: integrates with TFS +* `Microsoft.TeamFoundation.Server.Integration`: integrates with Azure DevOps Server * `Microsoft.VisualStudio.Services.Integration`: integrates with both. Shortcut for `Microsoft.VisualStudio.Services.Cloud.Integration` and `Microsoft.TeamFoundation.Server.Integration` For more information, see [Extensibility points](../reference/targets/overview.md). @@ -308,7 +311,7 @@ Installation targets can also be used in the manifest of integrations. For examp } ``` -#### Example: Integration that only works with TFS +#### Example: Integration that only works with Azure DevOps Server ```json { @@ -422,7 +425,7 @@ is equivalent to: ### Using installation targets and demands -Installation targets and demands are used together to present users with a correct view of the products/services your extension or integration is compatible with. For example, specifying an installation target of `Microsoft.VisualStudio.Services` with a demand of `api-version/3.0` means the extension works with Azure DevOps. +Installation targets and demands are used together to present users with a correct view of the products and services your extension or integration is compatible with. For example, specifying an installation target of `Microsoft.VisualStudio.Services` with a demand of `api-version/3.0` means the extension works with Azure DevOps. > [!TIP] > For more information on REST APIs, see the [REST API Reference](/rest/api/azure/devops). @@ -498,8 +501,8 @@ In this example, the extension demands version 3.0 of the APIs, which means it c | `contributionType/{id}` | Requires a specific contribution type be available | No | Yes | > [!NOTE] -> * Use `environment/cloud` and `environment/onprem` only when your extension has topology-related requirements that require running in that particular environment. -> * `extension`, `contribution`, and `contributionType` demands are evaluated at install time, and requires that the specified extension is already installed and enabled in the organization/collection. +> - Use `environment/cloud` and `environment/onprem` only when your extension has topology-related requirements that require running in that particular environment. +> - `extension`, `contribution`, and `contributionType` demands are evaluated at install time and require that the specified extension is already installed and enabled in the organization or collection. ## Files @@ -536,7 +539,7 @@ Properties for the Files section: Each contribution entry has the following properties: -* **id** - A reference ID (string) for the contribution. Each contribution's ID must be unique within an extension. See [referencing contributions and types](#contributionIds). +* **id** - A reference ID (string) for the contribution. Make each contribution ID unique within an extension. See [referencing contributions and types](#contributionIds). * **type** - The ID of the contributionType of this contribution. * **description** - (Optional) A string describing what the contribution is providing. * **targets** - An array of contribution IDs that the contribution is targeting (contributing to). See [Targeting contributions](#contributionTargets). @@ -550,10 +553,10 @@ For more information, see the [contribution model overview](contributions-overvi Each contribution entry has the following properties: -* **id** - A reference ID (string) for the contribution type. Each contribution type's ID must be unique within an extension. See [referencing contributions and types](#contributionIds). +* **id** - A reference ID (string) for the contribution type. Make each contribution type ID unique within an extension. See [referencing contributions and types](#contributionIds). * **name** - The friendly name of the contribution type. * **description** - (Optional) A string describing in more detail what the contribution type is for. -* **properties** - (Optional) A dictionary that maps property names to property descriptions. These properties describe the required and optional properties that can be used by contributions of this type. +* **properties** - (Optional) A dictionary that maps property names to property descriptions. These properties describe the required and optional properties that contributions of this type can use. Property descriptions have the following properties: @@ -567,21 +570,20 @@ For more information, see the [contribution model overview](contributions-overvi ### Referencing contributions and types -Contributions and contribution types are referenced by their identifiers. Contributions reference types through the `type` property, and reference other -contributions through the `targets` property. +Use unique identifiers to reference contributions and contribution types. Reference *types* with the `type` property, and reference other contributions with the `targets` property. - A *full* contribution reference includes the publisher identifier, extension identifier, and contribution/type identifier, separated by -a dot (.). For example, `ms.vss-web.hub` is the full identifier for the contribution with identifier of "hub" in the "vss-web" extension published by the "ms" (Microsoft) publisher. -- *Relative* contribution references may be used within an extension manifest for a contribution's reference to another contribution or contribution type within that same extension. In this case, the publisher and extension identifiers are NOT included, and the identifier is a dot (.) followed -by the contribution identifier. For example, ".hub" may be used within the "vss-web" extension mentioned previously as a shortcut for "ms.vss-web.hub". +a dot (.). For example, `ms.vss-web.hub` is the full identifier for the contribution with identifier of `hub` in the `vss-web` extension published by the "ms" (Microsoft) publisher. +- *Relative* contribution references might get used within an extension manifest for a contribution's reference to another contribution or contribution type within that same extension. In this case, the publisher and extension identifiers are NOT included, and the identifier is a dot (`.`) followed +by the contribution identifier. For example, `.hub` might be used within the `vss-web` extension mentioned previously as a shortcut for `ms.vss-web.hub`. ### Targeting contributions -Some contributions act as containers that can be targeted by other contributions. +Some contributions act as containers targeted by other contributions. - Hub contributions can target Hub Groups. When a page is rendered, the web UI shows all Hub contributions that target the selected hub group. Hub groups target a hub group collection, which defines a set of hub groups that show up in a given navigational area, for example, project-level admin pages. -- Menus can be targeted by contributions of different types: action, hyperlink-action, and action-provider. Actions and hyperlink-actions provide single menu item entries. An action-provider can provide multiple dynamic menu items. For a given menu, items are aggregated across all contributions (of any of these types) that target that specific menu contribution. +- Different types of contributions can target menus: action, hyperlink-action, and action-provider. Actions and hyperlink-actions provide single menu item entries. An action-provider can provide multiple dynamic menu items. For a given menu, items are aggregated across all contributions (of any of these types) that target that specific menu contribution. ### Adding a hub icon @@ -619,9 +621,9 @@ The Marketplace only supports badges from the following trusted services: * opencollective.co/ > [!NOTE] -> Replace "vsmarketplacebadge.apphb.com" with "vsmarketplacebadges.dev". +> Replace `vsmarketplacebadge.apphb.com` with `vsmarketplacebadges.dev`. -If you want to show a badge from another service, contact *vsmarketplace@microsoft.com*. +To show a badge from another service, contact [Customer Support at the Developer Community](https://developercommunity.visualstudio.com/AzureDevOps). diff --git a/docs/extend/develop/media/add-panel-intro-show-mapping-hello-world.png b/docs/extend/develop/media/add-panel-intro-show-mapping-hello-world.png index be18c0ffbdc..272aeed195b 100644 Binary files a/docs/extend/develop/media/add-panel-intro-show-mapping-hello-world.png and b/docs/extend/develop/media/add-panel-intro-show-mapping-hello-world.png differ diff --git a/docs/extend/develop/media/add-panel-show-custom-panel.png b/docs/extend/develop/media/add-panel-show-custom-panel.png index 8b7378f0e04..6840432281a 100644 Binary files a/docs/extend/develop/media/add-panel-show-custom-panel.png and b/docs/extend/develop/media/add-panel-show-custom-panel.png differ diff --git a/docs/extend/develop/media/add-workitem-extension-toolbar.png b/docs/extend/develop/media/add-workitem-extension-toolbar.png index 2a3cd051e74..63268a6aea5 100644 Binary files a/docs/extend/develop/media/add-workitem-extension-toolbar.png and b/docs/extend/develop/media/add-workitem-extension-toolbar.png differ diff --git a/docs/extend/develop/media/query-results-pivot-tab.png b/docs/extend/develop/media/query-results-pivot-tab.png index 7e1f5e5911f..35bab8fcd4d 100644 Binary files a/docs/extend/develop/media/query-results-pivot-tab.png and b/docs/extend/develop/media/query-results-pivot-tab.png differ diff --git a/docs/extend/develop/pipeline-decorator-context.md b/docs/extend/develop/pipeline-decorator-context.md index a07ebdf96ba..6e497df1e8c 100644 --- a/docs/extend/develop/pipeline-decorator-context.md +++ b/docs/extend/develop/pipeline-decorator-context.md @@ -6,7 +6,7 @@ ms.subservice: azure-devops-ecosystem ms.assetid: fe3e1e94-0415-400a-9b2d-7eeadb6101fc ms.author: chcomley author: chcomley -ms.date: 07/20/2021 +ms.date: 02/26/2024 monikerRange: 'azure-devops' --- @@ -16,11 +16,16 @@ monikerRange: 'azure-devops' [Pipeline decorators](add-pipeline-decorator.md) have access to context about the pipeline in which they run. As a pipeline decorator author, you can use this context to make decisions about the decorator's behavior. The information available in context is different for pipelines and for release. -Also, decorators run after task names are resolved to task GUIDs. +Also, decorators run after task names are resolved to task globally unique identifiers (GUIDs). When your decorator wants to reference a task, it should use the GUID rather than the name or keyword. + [!INCLUDE [extension-docs-new-sdk](../../includes/extension-docs-new-sdk.md)] +> [!NOTE] +> Pipeline decorators are used when building [web extensions](../get-started/node.md). These examples are not designed to work in YAML pipelines. + + ## Resources Pipeline resources are available on the `resources` object. @@ -110,7 +115,7 @@ For instance, to conditionally add a task only if it doesn't already exist: For instance, if the pipeline had a variable called `myVar`, its value would be available to the decorator as `variables['myVar']`. For example, to give a decorator an opt-out, we could look for a variable. -Pipeline authors who wish to opt out of the decorator can set this variable, and the decorator won't be injected. +Pipeline authors who wish to opt out of the decorator can set this variable, and the decorator isn't injected. If the variable isn't present, then the decorator is injected as usual. #### my-decorator.yml @@ -131,7 +136,7 @@ steps: ## Task names and GUIDs -Decorators run after tasks have already been turned into GUIDs. +Decorators run after tasks already turned into GUIDs. Consider the following YAML: ```yaml @@ -154,15 +159,15 @@ For special keywords like `checkout` and `bash` in the previous example, you can | Keyword | GUID | Task Name | |--------------|----------------------------------------|-----------| -| `checkout` | `6D15AF64-176C-496D-B583-FD2AE21D4DF4` | n/a, see note below | +| `checkout` | `6D15AF64-176C-496D-B583-FD2AE21D4DF4` | n/a, see note | | `bash` | `6C731C3C-3C68-459A-A5C9-BDE6E6595B5B` | Bash | | `script` | `D9BAFED4-0B18-4F58-968D-86655B4D2CE9` | CmdLine | | `powershell` | `E213FF0F-5D5C-4791-802D-52EA3E7BE1F1` | PowerShell | | `pwsh` | `E213FF0F-5D5C-4791-802D-52EA3E7BE1F1` | PowerShell | | `publish` | `ECDC45F6-832D-4AD9-B52B-EE49E94659BE` | PublishPipelineArtifact | -| `download` | `61F2A582-95AE-4948-B34D-A1B3C4F6A737` | DownloadPipelineArtifact | +| `download` | `30f35852-3f7e-4c0c-9a88-e127b4f97211` | DownloadPipelineArtifact | -After resolving task names and keywords, the previous YAML becomes: +After task names and keywords resolve, the previous YAML becomes: ```yaml steps: @@ -180,6 +185,6 @@ steps: ``` > [!TIP] -> Each of these GUIDs can be found in the `task.json` for the corresponding [in-box task](https://github.com/microsoft/azure-pipelines-tasks). +> You can find each of these GUIDs in the `task.json` for the corresponding [in-box task](https://github.com/microsoft/azure-pipelines-tasks). > The only exception is `checkout`, which is a native capability of the agent. > Its GUID is built into the Azure Pipelines service and agent. diff --git a/docs/extend/develop/samples-overview.md b/docs/extend/develop/samples-overview.md index 2e9d98a2456..f51aea6d801 100644 --- a/docs/extend/develop/samples-overview.md +++ b/docs/extend/develop/samples-overview.md @@ -8,57 +8,57 @@ ms.topic: conceptual monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 10/12/2022 +ms.date: 03/21/2025 --- # Extension samples [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Get started developing your extension by working from a sample. +Start developing your extension by working from a sample. [!INCLUDE [extension-docs-new-sdk](../../includes/extension-docs-new-sdk.md)] -The following Microsoft samples show the capabilities of the extension framework and how to -contribute to various areas. Each sample illustrates one or more contributions. We've limited the -number of contributions for each sample to increase understanding of the extension framework. +The following Microsoft samples show the capabilities of the extension framework and how to contribute to various areas. Each sample illustrates one or more contributions. We limit the number of contributions for each sample to increase understanding of the extension framework. For source information, see the [Azure DevOps extension samples repo](https://github.com/microsoft/azure-devops-extension-sample/). + +| Sample | Contributions | Description | +|--------|---------------|-------------| +| [BreadcrumbService](./add-hub.md) | Breadcrumb Service, Hub | Adds a breadcrumb service, which adds a "Sample Breadcrumb Item" to the sample hub. To see this item, go to the **Sample Hub** in the **Pipelines** hub group. | +| CodeEditorContribution | Code Editor | Adds a language definition and a JSON schema for the code editor. | +| [Feature](./add-hub.md) | Feature, Hub, Property Provider | Shows how to hook into the **Preview Features** panel under the user profile menu. Adds a simple hub that only shows when you turn on an "ABC" feature. You can toggle the feature on and off, per user or per organization. | +| [Hub](./add-hub.md) | Hub | Adds a hub named **Sample Hub** into the **Pipelines** hub group. The Sample Hub is on a project-level page, under the **Pipelines** navigation element. | +| [Menu](./add-action.md) | Build Definition Menu Item | Adds a **Sample build definition menu item** to the **Builds** hub in the dropdown actions menu. The menu handler gets the current build definition from the context passed, makes a REST call, and then shows the result in a message box. | +| [Panel](./add-hub.md) | Panel Content, Hub | Applied within the **Hub** sample. Contains a toggle button along with **OK** and **Cancel** buttons. Can be used as a custom panel or dialog content. | +| [Pivot](./add-hub.md) | Web Tab | Adds a **Sample Pivot** tab to the organization or project collection home page, next to **Projects**, **My work items**, and **My pull requests**. | +| Pills | Pill Provider | Adds pills to the title of the Pipeline definition (Runs) page. | +| QueryParamsHandler | Event Subscription | Adds a service that loads on any page whenever a `showMyPanel` query parameter presents in the URL when any page gets loaded. The startup service shows the custom panel from the Panel sample, using an optional `myPanelTitle` query parameter as the panel title. | +| [RepositoryActions](./add-action.md) | Menu Item | Adds a **Sample repository action** menu item to the repository picker in the header of code hub pages. If the `href` property shows, select the action to go to the given URL. If the `uri` property is provided, that code executes when you select the action. | +| [RepositoryServiceHub](./add-hub.md) | Hub | Adds a **Repository Information** hub to the **Code** hub group. Demonstrates how to interact with the `IVersionControlRepositoryService` to obtain basic information about a user's Git repository. | +| [WorkItemFormGroup](./custom-control.md) | Work Item Form Group | Adds a **Sample WorkItem Form Group** extension to the work item form to show how to interact with the `IWorkItemFormService` service and `IWorkItemNotificationListener`. Provides a UI to show case how to change field values using the form service and displaying work item form notification events. | +| [WorkItemOpen](./add-hub.md) | Hub | Adds a **Sample WorkItem Open** hub to the **Boards** hub group to show how to interact with the `IWorkItemFormNavigationService` service. Provides a UI for you to open an existing work item by ID, or open the work item form for a new work item by work item type. Either of these options open a dialog in the host frame. | + +## DevLabs examples + +Other open source examples that you might be interested in. | Sample | Source | Contributions | Description | |--------|-------|---------------|-------------| -| [BreadcrumbService](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/BreadcrumbService) | Breadcrumb Service, Hub | It adds a breadcrumb service which adds a "Sample Breadcrumb Item" to the sample hub. Visit the "Sample Hub" in the Pipelines hub group to see this item. | -| [CodeEditorContribution](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/CodeEditorContribution) | Code Editor | It adds a language definition and a JSON schema for the code editor. | -| [Feature](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/Feature) | Feature, Hub, Property Provider | It shows how to hook into the Preview Features panel (under the user profile menu). It adds a simple hub that is only shown when an "ABC" feature is turned on. The feature can be toggled per-user or per-organization. | -| [Hub](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/Hub) | Hub | It adds a hub named "Sample Hub" into the `Pipelines` hub group. If you visit a project-level page, you will find Sample Hub under the `Pipelines` navigation element in the vertical navigation menu on the left of the page. | -| [Menu](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/Menu) | Build Definition Menu Item | It adds a "Sample build definition menu item" to the `Builds` hub in the dropdown actions menu in the top-right of the page. The menu handler gets the current build definition from the context that is passed to it, it makes a REST call, and shows the result in a message box. | -| [Panel](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/Panel) | Panel Content, Hub | It is leveraged within the `Hub` sample. It is content that contains a toggle button along with OK/Cancel buttons. It can be used as custom panel or dialog content. | -| [Pivot](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/Pivot) | Web Tab | It adds a "Sample Pivot" pivot (tab) to the Organization (Project Collection) home page, next to "Projects", "My work items", and "My pull requests". | -| [Pills](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/Pills) | Pill Provider | It adds pills to the title of the Pipeline definition (Runs) page. | -| [QueryParamsHandler](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/QueryParamsHandler) | Event Subscription | It adds a service that gets loaded on any page whenever a "showMyPanel" query parameter is present in the URL when any page is loaded. The startup service shows the custom panel from the Panel sample, using an optional "myPanelTitle" query parameter as the panel title. | -| [RepositoryActions](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/RepositoryActions) | Menu Item | It adds a "Sample repository action" menu item to the repository picker in the header of code hub pages. If a `href` property is provided, clicking on the action will navigate to the given url. If a `uri` is provided, that code will be executed when the action is clicked. | -| [RepositoryServiceHub](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/Feature) | Hub | It adds a "Repository Information" hub to the `Code` hub group. It demonstrates how to interact with the `IVersionControlRepositoryService` to obtain basic information about a user's currently selected Git repository. | -| [WorkItemFormGroup](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/WorkItemFormGroup) | Work Item Form Group | It adds a "Sample WorkItem Form Group" extension to workitem form to show how to interact with the `IWorkItemFormService` service and `IWorkItemNotificationListener`. It gives UI to show case how to change field values using the form service and displaying workitem form notification events. | -| [WorkItemOpen](./custom-control.md) | [GitHub](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/WorkItemOpen) | Hub | It adds a "Sample WorkItem Open" hub to the Boards hub group to show how to interact with the `IWorkItemFormNavigationService` service. It gives UI for you to open an existing work item (by ID) or open the work item form for a new work item (by work item type). Either of these options open a dialog in the host frame. | -| [Color Scale Work Item Form Custom Control](./custom-control.md) | [GitHub](https://github.com/Microsoft/vsts-sample-wit-custom-control) | Work Item Form Control | Add color coding to the values in a dropdown. | -| [Folder Management](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.FolderManagement) | [GitHub](https://github.com/ALM-Rangers/VSO-Extension-FolderManagement) | Context menu action (code explorer tree) | Create a folder in your source repositories from the code explorer tree. No need to clone the repository or install extra tools. | -| [Offline Test Execution](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.OfflineTestExecution) | [GitHub](https://github.com/ALM-Rangers/Offline-Test-Execution-extension) | Test plan tab | Allows the tester to perform the test steps even if disconnected from Azure DevOps. It can be done using the exported Excel Spreadsheet. | -| [Release Management Utility tasks](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.utilitytasks) | [GitHub](https://github.com/openalm/Extension-UtilitiesPack) | Release Management tasks | Utility tasks for Release Management. | -| [Roll-up Board](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.RollUpBoard) | [GitHub](https://github.com/ALM-Rangers/Roll-Up-Board-Widget-Extension) | Dashboard Widget | This widget shows the number of cards in each column of the Kanban board. | -| [Sample Data Widget](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.SampleDataWidget) | [GitHub](https://github.com/ALM-Rangers/Sample-Data-Widget-Extension) | Dashboard Widget | Create sample data in your Team Services project. | -| [State Model Visualization](https://marketplace.visualstudio.com/items?itemName=taavi-koosaar.StateModelVisualization) | [GitHub](https://github.com/melborp/StateModelVisualization) | Toolbar action (work item), Hub | Visualize the state model for a selected work item type. | | [Team Calendar](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-calendar) | [GitHub](https://github.com/Microsoft/vsts-team-calendar) | Hub, Event sources | Track events important to your team, view and manage days off, quickly see when sprints start and end, and more. | -| [Team Project Health](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.TeamProjectHealth) | [GitHub](https://github.com/ALM-Rangers/Visualize-Team-Project-Health-Widgets) | Dashboard Widget | Enable users to visualize the overall health of builds, delivering a visual cue similar to the Codify Build Light. | | [WSJF (Weighted Shortest Job First)](https://marketplace.visualstudio.com/items?itemName=MS-Agile-SAFe.WSJF-extension) | [GitHub](https://github.com/Microsoft/vsts-wsjf-extension) | Notification (work item), Context menu action (work item) | Auto calculates WSJF (weighted shortest job first) per work item and stores it in a work item field. | | [Cascading Lists](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.cascading-picklists-extension) | [GitHub](https://github.com/microsoft/azure-devops-extension-cascading-picklist) | Work Item Form | Define cascading behavior for picklists in work item form. | +| [Retrospectives](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.team-retrospectives) | [GitHub](https://github.com/microsoft/vsts-extension-retrospectives) | Hub | First-class experience for retrospectives and general feedback board scenarios. Collect feedback on your project milestones, organize and prioritize, and create and track actionable tasks, which can help your team improve over time. | +| [Estimate](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.estimate) | [GitHub](https://github.com/microsoft/azure-boards-estimate) | Hub, Work item action menu| Play Planning Poker in Azure DevOps. Select work from an iteration, query, or your backlog, estimate the effort of those items with your team, and immediately update the work items. | +| [Multivalue control](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-extensions-multivalue-control) | [GitHub](https://github.com/Microsoft/vsts-extension-multivalue-control) | Work item form | A work item form control, which allows selection of multiple values. | +| [Azure DevOps Extension Tasks](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-developer-tools-build-tasks) | [GitHub](https://github.com/Microsoft/azure-devops-extension-tasks) | Build and release tasks | Azure Pipelines tasks for packaging and publishing Azure Devops and Visual Studio extensions to the Visual Studio Marketplace. | -## How to get started +## Get started -To get you started as quickly as possible, there's a [seed project](https://github.com/cschleiden/vsts-extension-ts-seed-simple) available that contains the files required to build an extension using TypeScript. To automate building, packaging, and publishing the extension, a grunt script is -added. +To get started as quickly as possible, use the [seed project](https://github.com/cschleiden/vsts-extension-ts-seed-simple) that contains the files required to build an extension using TypeScript. There's a grunt script to automate building, packaging, and publishing the extension. ## Related articles - [Develop a web extension](../get-started/node.md) -- [Developer Formula Design System](https://developer.microsoft.com/azure-devops/) -- [Azure DevOps sample extensions repo](https://github.com/Microsoft/azure-devops-extension-sample) -- [Contribution model](../develop/contributions-overview.md) +- [Use the Developer Formula Design System](https://developer.microsoft.com/azure-devops/) +- [Use the Azure DevOps sample extensions repo](https://github.com/Microsoft/azure-devops-extension-sample) +- [View the contribution model](../develop/contributions-overview.md) - [Package and publish extensions](../publish/overview.md) diff --git a/docs/extend/develop/service-endpoints.md b/docs/extend/develop/service-endpoints.md index 1c44825c8d1..af09b0b59fe 100644 --- a/docs/extend/develop/service-endpoints.md +++ b/docs/extend/develop/service-endpoints.md @@ -23,11 +23,7 @@ Service endpoints are a way for Azure DevOps to connect to external systems or s - Certificates or tokens - User names and passwords -::: moniker range="tfs-2018" -> [!NOTE] -> _Service endpoints_ are called _service connections_ in TFS 2018 and earlier versions. -> _Pipelines_ are called _build definitions_ in TFS 2018 and and earlier versions. -::: moniker-end + Extensions are then able to use the service endpoint to acquire the stored details to do the necessary operations on that service. Follow this guide to create a new service endpoint contribution and use it in your extension. @@ -50,7 +46,7 @@ The steps involved in completing this task are: > [!NOTE] > This tutorial refers to the home directory for your project as "home". - + ## Create the manifest file: `vss-extension.json` @@ -196,7 +192,7 @@ For this tutorial, this REST call returns nothing and is meant to be replaced by It's possible to use other parameters than the endpoint URL for the REST URL, for instance some endpoint properties. For instance, assuming that we had a property in the endpoint named subscriptionId, the REST URL could use it with the following syntax: $(endpoint.subscription). - + ## Create the build task @@ -238,7 +234,7 @@ Create a `task.json` file in your `BuildTaskFolder` directory, if you haven't cr "label": "Fabrikam service/server end point", "defaultValue": "", "required": true, - "helpMarkDown": "Select the Fabrikam end point to use. If needed,selecton 'manage', and add a new service endpoint of type 'Fabrikam server connection'" + "helpMarkDown": "Select the Fabrikam end point to use. If needed, select 'manage', and add a new service endpoint of type 'Fabrikam server connection'" }, { "name": "project", diff --git a/docs/extend/develop/upload-tasks.md b/docs/extend/develop/upload-tasks.md index 011dfa979db..412adf2e6bb 100644 --- a/docs/extend/develop/upload-tasks.md +++ b/docs/extend/develop/upload-tasks.md @@ -15,7 +15,7 @@ Learn how to upload tasks to organization for custom tasks or in-the-box tasks i For example, this guideline can help to update in-the-box tasks on Azure DevOps Server. > [!IMPORTANT] -> For the case of in-the-box tasks being uploaded to on-prem instance, there could be some task capabilities not supported due to the old agent version/lack of support on Azure DevOps Server side. +> When uploading in-the-box tasks to an on-premises instance, some task capabilities might not be supported due to the old agent version or lack of support on the Azure DevOps Server side. For more information about **tfx-cli**, see the [Node CLI for Azure DevOps on GitHub](https://github.com/Microsoft/tfs-cli). @@ -31,23 +31,22 @@ To upload tasks to project collection, you need prerequisites: npm install -g tfx-cli ``` - Permissions to update required project collection, PAT generated with scope **Environment (Read & Write)** to be able to upload tasks to the project collection. + [!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] ## Tfx-cli sign in with personal access token -You need to login to Azure DevOps with tfx-cli - to be able to upload pipeline tasks to the project collection. +Sign in to Azure DevOps with tfx-cli to upload pipeline tasks to the project collection. > [!IMPORTANT] -> A personal access token is required by default for authentication to project collection in Azure DevOps. You need to create [personal access token (PAT)](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with scope **Environment (Read & manage)**. +> A personal access token is required by default for authentication to project collection in Azure DevOps. Create [personal access token (PAT)](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with scope **Environment (Read & manage)**. +> You can use other ways to authorize with tfx-cli. For more information, see [Authenticate in Cross-platform CLI for Azure DevOps](../../integrate/get-started/auth/tfs-basic-auth.md). -> [!TIP] -> You can use other ways to authorize with tfx-cli - see [Authenticate in Cross-platform CLI for Azure DevOps](../../integrate/get-started/auth/tfs-basic-auth.md) for more details. - -To login - you should specify the path to project collection as URL. The default name of the project collection is `DefaultCollection`. +To sign in, specify the path to project collection as URL. The default name of the project collection is `DefaultCollection`. For Azure DevOps Services, path to project collection would have the following format: `https://{Azure DevOps organization name}.visualstudio.com/DefaultCollection` -For Azure DevOps Server default project collection URL will depend on the url where the server is located and its template will be: +For Azure DevOps Server, the default project collection URL depends on the location of the url server and its template: `http://{Azure DevOps Server url}/DefaultCollection` Enter the following command and provide requested information: diff --git a/docs/extend/develop/use-control.md b/docs/extend/develop/use-control.md deleted file mode 100644 index 8c497e03569..00000000000 --- a/docs/extend/develop/use-control.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -ms.subservice: azure-devops-ecosystem -title: How to use a Control | Extensions for Azure DevOps Services -description: How to use a control in your extension for Azure DevOps Services. -ms.assetid: eadb8d03-0664-4810-a6e8-62d64e834d33 -ms.topic: conceptual -monikerRange: 'azure-devops' -ms.author: chcomley -author: chcomley -ms.date: 06/03/2020 ---- - -# Use a control - -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -[!INCLUDE [disclaimer](../../integrate/api/_data/disclaimer.md)] - -* [Configure](/previous-versions/azure/devops/extend/develop/ui-controls/configure) -* [Use grid](/previous-versions/azure/devops/extend/develop/ui-controls/grido) -* [Use menubar](/previous-versions/azure/devops/extend/develop/ui-controls/menubaro) -* [Use treeview](/previous-versions/azure/devops/extend/develop/ui-controls/treeviewo) -* [Use combo](/previous-versions/azure/devops/extend/develop/ui-controls/comboo) -* [Use modal dialog](/previous-versions/azure/devops/extend/develop/ui-controls/modaldialogo) -* [Use splitter](/previous-versions/azure/devops/extend/develop/ui-controls/splittero) -* [Use wait control](/previous-versions/azure/devops/extend/develop/ui-controls/waitcontrolo) -* [Use pivot filter control](/previous-versions/azure/devops/extend/develop/ui-controls/pivotfiltero) - -> [!TIP] -> For more information, see the [Formula Design System documentation](https://azdevinternal.azureedge.net/). - -## Next steps - -> [!div class="nextstepaction"] -> [Reference the Formula Design System documentation](https://azdevinternal.azureedge.net/) - diff --git a/docs/extend/develop/using-host-dialog.md b/docs/extend/develop/using-host-dialog.md index 0dfdc235c55..8dac7487cc3 100644 --- a/docs/extend/develop/using-host-dialog.md +++ b/docs/extend/develop/using-host-dialog.md @@ -117,7 +117,7 @@ The `uri` property references a page that is rendered within the content area of ### Showing the dialog -To show the dialog (for example, when a user selects an action on a toolbar or menu), call the `openDialog` function on an instance of the HostDialogService, passing the fully-qualified identifer of the dialog content, for example `my-publisher.my-extension.registration-form` and any dialog options: +To show the dialog (for example, when a user selects an action on a toolbar or menu), call the `openDialog` function on an instance of the HostDialogService, passing the fully-qualified identifier of the dialog content, for example `my-publisher.my-extension.registration-form` and any dialog options: ```javascript VSS.getService(VSS.ServiceIds.Dialog).then(function(dialogService) { diff --git a/docs/extend/develop/web-navigation.md b/docs/extend/develop/web-navigation.md index d476a8b77a2..e68f82ac3a4 100644 --- a/docs/extend/develop/web-navigation.md +++ b/docs/extend/develop/web-navigation.md @@ -114,7 +114,7 @@ Complete the following steps to set an icon for your hub. 1. Set the `iconAsset` property of the hub contribution to the fully qualified asset identifier, which follows the pattern: `{publisher-id}.{extension-id}/{asset-path}`. -2. Add an entry for this asset in the `includesata` contribution property. +2. Add an entry for this asset in the `includesData` contribution property. 3. Package the asset with your extension by listing it in the `files` property at the root of your manifest. diff --git a/docs/extend/develop/work-with-urls.md b/docs/extend/develop/work-with-urls.md index 10a42de01e9..b4aff82b782 100644 --- a/docs/extend/develop/work-with-urls.md +++ b/docs/extend/develop/work-with-urls.md @@ -1,36 +1,36 @@ --- ms.subservice: azure-devops-ecosystem -title: Working with URLs in extensions | Azure DevOps +title: Work with URLs in Extensions | Azure DevOps description: Learn about best practices for working with URLs in Azure DevOps extensions and integrations. ms.assetid: 1f27f05e-2c55-4873-ab4a-8c9c0947a7fe -ms.topic: conceptual +ms.topic: concept-article monikerRange: 'azure-devops' ms.author: chcomley author: chcomley -ms.date: 06/02/2020 +ms.date: 04/15/2025 --- # Work with URLs in extensions and integrations [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -With the introduction of Azure DevOps, organizational resources and APIs are now accessible via either of the following URLs: +With Azure DevOps, organizational resources and APIs are accessible through either of the following URLs: * `https://dev.azure.com/{organization}` (new) * `https://{organization}.visualstudio.com` (legacy) -Regardless of when the organization was created, users, tools, and integrations can interact with organization-level REST APIs using either URL. As the developer of an extension, integration, or tool that interacts with Azure DevOps, learn how to best work with URLs made available to your code and form URLs when you call REST APIs. +Users, tools, and integrations can interact with organization-level REST APIs using either URL, regardless of when the organization was created. -For more information, see the [REST API Reference](/rest/api/azure/devops). - -## Organization primary URL +This article explains how you can best work with URLs in extensions, integrations, or tools. For more information, see the [Azure DevOps Services REST API Reference](/rest/api/azure/devops). + +## Primary URL -Each organization has a designated **primary** URL that is either the new form or the legacy form. The primary URL is used by Azure DevOps for constructing URLs in certain scenarios (more details follow). The default primary URL for an organization is determined by when the organization was created, but can be changed by an administrator: +Each organization has a designated *primary* URL that's in either the new form or the legacy form. The primary URL is used by Azure DevOps to construct URLs in certain scenarios. The default primary URL for an organization is determined by when the organization was created, but can be changed by an administrator: | When the organization was created | Default primary URL | |--------------------------|---------------------| -| On or after 9/10/2018 | New | -| Before 9/10/2018 | Legacy | +| On or after 9/10/2018 | New | +| Before 9/10/2018 | Legacy | ### How the primary URL is used @@ -47,13 +47,13 @@ $orgUrl = $env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI Write-Host $orgUrl ``` -If this task is executed on an organization where the primary URL is the new URL form, the output is `https://dev.azure.com/{organization}`. The same task executed on an organization where the primary URL is the legacy URL form outputs `https://{organization}.visualstudio.com`. +If this task is executed on an organization where the primary URL is in the new URL form, the output is `https://dev.azure.com/{organization}`. The same task executed on an organization where the primary URL is the legacy URL form outputs `https://{organization}.visualstudio.com`. -It's therefore important that Azure Pipeline tasks and services that receive events from service hooks handle both URL forms. +Therefore, it's important that Azure Pipelines tasks and services that receive events from service hooks handle both URL forms. ## URLs returned in REST APIs -Regardless of an organization's primary URL, URLs returned in the response to a REST API call use the same base URL as the requesting URL. This function ensures clients calling a REST API using a legacy URL continues to get back URLs in the same (legacy) form. For example, when the Projects REST API is called using a legacy URL, URLs in the response use the legacy form: +Regardless of an organization's primary URL, URLs returned in the response to a REST API call use the same base URL as the requesting URL. This function ensures that clients calling a REST API using a legacy URL continue to get back URLs in the same (legacy) form. For example, when the Projects REST API is called using a legacy URL, URLs in the response use the legacy form: ### Request @@ -65,7 +65,7 @@ GET https://Fabrikam.visualstudio.com/_apis/projects/MyProject ```javascript { - "id": "ef4de40d-3d96-4b80-a320-cfafe038ae57", + "id": "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5", "name": "MyProject", "url": "https://Fabrikam.visualstudio.com/_apis/projects/MyProject" } @@ -77,32 +77,32 @@ Calling the same API using the new URL (`https://dev.azure.com/Fabrikam/_apis/pr To ensure your extension, tool, or integration is resilient to changing organization URL forms and to possible future changes to the location (domain) of a REST API: -1. Assume the form of the organization URL can change over time. -2. Avoid parsing a URL to construct another URL. -3. Don't assume a particular REST API always resides on the same domain. -4. Avoid storing URLs in your service. -5. When possible, use Microsoft-provided [.NET](../../integrate/concepts/dotnet-client-libraries.md), TypeScript (web), [Node.js](https://github.com/Microsoft/vsts-node-api), and [Python](https://github.com/Microsoft/vsts-python-api) client libraries with Azure DevOps. +* Assume the form of the organization URL can change over time. +* Avoid parsing a URL to construct another URL. +* Don't assume a particular REST API always resides on the same domain. +* Avoid storing URLs in your service. +* When possible, use Microsoft-provided [.NET](../../integrate/concepts/dotnet-client-libraries.md), TypeScript (web), [Node.js](https://github.com/Microsoft/vsts-node-api), and [Python](https://github.com/Microsoft/vsts-python-api) client libraries with Azure DevOps. ## How to get an organization's URL -With just the organization's name or ID, you can get its base URL using the global Resource Areas REST API (`https://dev.azure.com/_apis/resourceAreas`). This API doesn't require authentication. It also provides information about the location (URL) of the organization and the base URL for REST APIs, which can live on different domains. +With just the organization's name or ID, you can get its base URL by using the global Resource Areas REST API (`https://dev.azure.com/_apis/resourceAreas`). This API doesn't require authentication. It also provides information about the location (URL) of the organization and the base URL for REST APIs, which can live on different domains. -A resource area is a group of related REST API resources and endpoints. Each resource area has a well-known identifier (see the following table). Each resource area has an organization-specific base URL that can be used to form URLs for APIs in that resource area. For example, the base URL for "build" REST APIs for the Fabrikam might be `https://dev.azure.com/Fabrikam`, but the base URL for "release management" REST APIs might be `https://vsrm.dev.azure.com/Fabrikam`. +A resource area is a group of related REST API resources and endpoints. Each resource area has a well-known identifier. Each resource area has an organization-specific base URL that can be used to form URLs for APIs in that resource area. For example, the base URL for *build* REST APIs for the Fabrikam might be `https://dev.azure.com/Fabrikam`, but the base URL for *release management* REST APIs might be `https://vsrm.dev.azure.com/Fabrikam`. > [!NOTE] > The Resource Areas REST API returns URLs for the organization based on that organization's designated primary URL. -### With the organization's name +### Using the organization's name -There are a few ways to get the base URL for an organization using its name. +There are a few ways to get the base URL for an organization by using its name. # [HTTP](#tab/http) #### Request -Replace `{organizationName}` with organization's name, for example "Fabrikam". `79134C72-4A58-4B42-976C-04E7115F32BF` is the ID for the "core" resource area, which is where important resources like "projects" are. +Replace `{organizationName}` with organization's name, for example *Fabrikam*. `79134C72-4A58-4B42-976C-04E7115F32BF` is the ID for the *core* resource area, which is where important resources like *projects* are. -``` +```http GET https://dev.azure.com/_apis/resourceAreas/79134C72-4A58-4B42-976C-04E7115F32BF ?accountName={organizationName}&api-version=5.0-preview.1 ``` @@ -121,10 +121,10 @@ The `locationUrl` reflects the organization's base URL. # [C# (client library)](#tab/csharpclient) -The Microsoft-provided .NET client library ([Microsoft.VisualStudio.Services.Client](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Client/16.139.0-preview)) provides a helper class that calls the Resource Areas REST API for you and returns the base URL for an organization. +The Microsoft-provided [.NET client library](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Client/16.139.0-preview) provides a helper class that calls the Resource Areas REST API for you and returns the base URL for an organization. > [!NOTE] -> The `VssConnectionHelper` class is available in version `16.139.0-preview` and later version of the client library. +> The `VssConnectionHelper` class is available in `16.139.0-preview` and later versions of the client library. ```cs using System; @@ -208,37 +208,38 @@ getOrgUrl('fabrikam', (err, url) => { --- -### With the organization's ID +### Using the organization's ID -To get the URL for an organization using its GUID identifier, use the `hostId` query parameter in the previous examples (instead of `accountName`). For example: +To get the URL for an organization by using its GUID identifier, use the `hostId` query parameter in the previous examples (instead of `accountName`). For example: -``` +```http GET https://dev.azure.com/_apis/resourceAreas/79134C72-4A58-4B42-976C-04E7115F32BF?hostId={organizationId}&api-version=5.0-preview.1 ``` ## How to get the base URL for a REST API -Starting from an organization's URL, you can use the Resource Areas REST API to look up the correct base URL for any REST API you need to call. This process ensures your code is resilient to the location (domain) of a REST API changing in the future and avoids potentially brittle logic. +Starting from an organization's URL, you can use the Resource Areas REST API to look up the correct base URL for any REST API you need to call. This process ensures that your code is resilient to the location (domain) of a REST API changing in the future and avoids potentially brittle logic. > [!NOTE] -> If you are using the Microsoft-provided .NET, TypeScript (web), Node.js, or Python client library, URL lookup is handled for you. For example, in .NET when you construct a `VssConnection` and call `GetClient`, the returned client is properly bound to the correct base URL for the REST APIs called by this client. +> If you're using the Microsoft-provided .NET, TypeScript (web), Node.js, or Python client library, URL lookup is handled for you. For example, when you construct a `VssConnection` and call `GetClient` in .NET, the returned client is properly bound to the correct base URL for the REST APIs called by this client. If you aren't using a Microsoft-provided client library: -1. Use the following table to find the resource area ID for the REST API you need to call. The resource area name usually appears after `/_apis/` in the REST API route. For example, the `/_apis/release/definitions` REST API belongs to the `release` resource area, which has an ID of `efc2f575-36ef-48e9-b672-0c6fb4a48ac5`. +1. Use the [following table](#reference-resource-area-ids) to find the resource area ID for the REST API you need to call. The resource area name usually appears after `/_apis/` in the REST API route. For example, the `/_apis/release/definitions` REST API belongs to the `release` resource area, which has an ID of `efc2f575-36ef-48e9-b672-0c6fb4a48ac5`. -2. Call the organization-level Resource Areas REST API (`{organizationUrl}/_apis/resourceAreas/{resourceAreaId}?api-version=5.0-preview.1`) and pass the resource area ID. For example: - ``` - GET https://dev.azure.com/Fabrikam/_apis/resourceAreas/efc2f575-36ef-48e9-b672-0c6fb4a48ac5?api-version=5.0-preview.1 - ``` - -3. Use the `locationUrl` field from the JSON response as the base URL for calling other REST APIs for this area. In this example, the base URL for Release Management REST APIs is `https://vsrm.dev.azure.com/Fabrikam`. +1. Call the organization-level Resource Areas REST API (`{organizationUrl}/_apis/resourceAreas/{resourceAreaId}?api-version=5.0-preview.1`) and pass the resource area ID. For example: + + ```http + GET https://dev.azure.com/Fabrikam/_apis/resourceAreas/efc2f575-36ef-48e9-b672-0c6fb4a48ac5?api-version=5.0-preview.1 + ``` + +1. Use the `locationUrl` field from the JSON response as the base URL for calling other REST APIs for this area. In this example, the base URL for Release Management REST APIs is `https://vsrm.dev.azure.com/Fabrikam`. Like the global Resource Areas REST API described earlier, no credentials are required to call the organization-level Resource Areas REST API. ### Example: Pipelines task calling an Azure Pipelines releases REST API -In this example, a build task needs to call the Azure Pipelines releases REST API. It forms the correct base URL for this REST API call by using the organization URL (provided in an environment variable) and the Resource Areas REST API. +In this example, a build task needs to call the Azure Pipelines releases REST API. The task forms the correct base URL for this REST API call by using the organization URL (provided in an environment variable) and the Resource Areas REST API. > [!NOTE] > Resource area IDs are fixed and can be safely embedded in tasks and other logic. @@ -260,14 +261,14 @@ $rmUrl = $results.locationUrl $releaseDefinitionsUrl = [string]::Format("{0}/_apis/release/definitions?api-preview=5.0-preview.1", $rmUrl) ``` -## Resource area IDs (reference) +## Reference: Resource area IDs This table shows the IDs for common resource areas. See the previous section for details on how to use this table. > [!NOTE] > Resource area IDs are fixed and are consistent across all organizations in Azure DevOps Services. -| Resource Area ID | Name | +| Resource area ID | Name | |---|---| |0d55247a-1c47-4462-9b1f-5e2125590ee6|account| |5d6898bb-45ec-463f-95f9-54d49c71752e|build| @@ -301,7 +302,7 @@ This table shows the IDs for common resource areas. See the previous section for |1d4f49f9-02b9-4e26-b826-2cdb6195f2a9|work| |85f8c7b6-92fe-4ba6-8b6d-fbb67c809341|worktracking| -## Next steps +## Next step > [!div class="nextstepaction"] -> [Make your extension or integration public](https://azdevinternal.azureedge.net/) \ No newline at end of file +> [Make your extension or integration public](../publish/overview.md) diff --git a/docs/extend/extension-report.md b/docs/extend/extension-report.md deleted file mode 100644 index b2191cbf948..00000000000 --- a/docs/extend/extension-report.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Extension Report | Azure DevOps -description: Use the Reports feature to track and analyze how your extension is doing and take required actions. -ms.assetid: baf829df-0975-46d8-8dea-7a5c9f6968ef -ms.subservice: azure-devops-ecosystem -ms.topic: conceptual -monikerRange: '<= azure-devops' -ms.author: chcomley -author: chcomley -ms.date: 11/12/2019 ---- - -# Extension reporting hub - -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - -Once your extension is available in the [Visual Studio Marketplace]() you can use the **Reports** feature. With this feature, you can track and analyze how the extension is performing and take required actions. -To visit the extension hub, browse to your [publisher page](https://aka.ms/vsmarketplace-manage) and select the extension or select the **Reports** link on the extension details page. - -## Acquisition - -You can view acquisition-related data in this tab for the selected period. -* Aggregated acquisition in the selected period for overall acquisition -* Aggregated acquisition split by extension downloads Azure DevOps connected install for free extension -* Aggregated acquisition split by trials Azure DevOps connected buy for paid extension -* Daily trend of extension page views with acquisition for Azure DevOps and connected server -* Conversion percentage from page views to acquisition - -For paid extensions, all transactional details for buy and trials are available with date, organization name, trial end date, and quantity. You can use the **Contact** action to communicate with your users. For more information, see the [Contact](#contact) section provided later in this article. - -## Uninstall - -You can view the following statistics: -- how many organizations have uninstalled your extension -- daily trend of uninstalls -- detailed feedback shared during uninstalls -- top uninstall reasons - -You can use search for text and dates to analyze and draw more insights from the detailed feedback. - -For paid extensions, you can use the **Contact** action to communicate with your users. [Contact](#contact) section provided later in this article for more details. - -## Ratings and review - -This tab gives you the following information: -- the average rating for the selected period versus overall rating -- the average rating by number of reviewers -- the daily trend of average rating - -The details section provides all the reviews and your responses in transactional view. - -You can **Reply** to a review or **Edit** a previous response and better manage engagement with your extension users. You can also **Appeal** to void a rating if the issue reported is because of the Marketplace or underlying platform. If the issue is valid, we'll void the rating. - -## Q & A - -This tab gives you snapshot of all questions by your extension users with the non-responded queries on the top. You can take actions of replying or editing a previous response and better manage engagement with your extension users. - -## Export to Excel - -All data elements available in the reports page are also available for download in XLS format to aid creating your own custom reports. - -## Contact - -For paid extensions, you can use the Contact action to communicate with your users. This functionality is available only for publishers with contributor + access on the extension. - -Marketplace brokers the first communication with the user as our privacy policy doesn't allow direct sharing of customer email addresses. Only users who have opted in for communication are sent the email. -Last contacted date for an organization is as also updated after sending a communication. - -**Important** Follow the guidance on transactional and promotional communication. A publisher found to do promotional communication or spamming users gets *added to a deny list*. They also can't use the **Contact** feature for any of their extensions. - -**Transactional Communication**: Transactional emails convey critical information necessary for the continued use of the extension or service. The following examples include: -- critical security notices -- transaction confirmations -- product recall notices -- specific feedback requests -- service discontinuation notices - -**Promotional Emails**: Promotional emails are used to market your extension, product, service, website, or event. Examples include invitations to events or web casts, information about new marketing or partner programs, and offers the prospect to obtain value-added content. Almost all newsletters fall into the promotional bucket as they generally contain at least some promotional content. - -For more information and guidance on communication with customers, see the [Marketplace Publisher Agreement](https://aka.ms/vsmarketplace-agreement). - -## Terminology - -* **Page views**: total number of extension detail page views. Repeated views are counted. -* **Azure DevOps installs**: total number of organizations the extension is installed in. Repeated installs on the same organization are counted. -* **TFS installs**: total number of TFS connected accounts the extension is installed in. Repeated installs on the same organization are counted. TFS disconnected server data isn't available. diff --git a/docs/extend/get-started/media/install-dialog.png b/docs/extend/get-started/media/install-dialog.png index 729457c6280..2a26419c8ff 100644 Binary files a/docs/extend/get-started/media/install-dialog.png and b/docs/extend/get-started/media/install-dialog.png differ diff --git a/docs/extend/get-started/media/organization-settings-extensions.png b/docs/extend/get-started/media/organization-settings-extensions.png index 94baa3ea8db..c0d3af01bb4 100644 Binary files a/docs/extend/get-started/media/organization-settings-extensions.png and b/docs/extend/get-started/media/organization-settings-extensions.png differ diff --git a/docs/extend/get-started/media/published-extension.png b/docs/extend/get-started/media/published-extension.png index 42b7a33bcf4..e4b4b8af346 100644 Binary files a/docs/extend/get-started/media/published-extension.png and b/docs/extend/get-started/media/published-extension.png differ diff --git a/docs/extend/get-started/media/share-dialog.png b/docs/extend/get-started/media/share-dialog.png index 20a0fe29bc1..7901cc93643 100644 Binary files a/docs/extend/get-started/media/share-dialog.png and b/docs/extend/get-started/media/share-dialog.png differ diff --git a/docs/extend/get-started/media/upload-new-extension.png b/docs/extend/get-started/media/upload-new-extension.png index 0cc2be097d3..11d6f34ad1c 100644 Binary files a/docs/extend/get-started/media/upload-new-extension.png and b/docs/extend/get-started/media/upload-new-extension.png differ diff --git a/docs/extend/get-started/node.md b/docs/extend/get-started/node.md index 3b8efa74e3a..ef9844f7e7c 100644 --- a/docs/extend/get-started/node.md +++ b/docs/extend/get-started/node.md @@ -1,14 +1,14 @@ --- ms.subservice: azure-devops-ecosystem title: Develop a web extension -description: Tutorial showing you how to develop your first web extension for Azure DevOps. +description: Learn how to develop your first web extension for Azure DevOps. ms.assetid: ae82118c-82fa-40ec-9f29-989ce981f566 ms.custom: engagement-fy23 ms.topic: how-to monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 10/12/2022 +ms.date: 03/20/2025 --- # Develop a web extension @@ -22,11 +22,10 @@ Use extensions to enhance Azure DevOps with new web experiences, dashboard widge ## Prerequisites -You must have the following permission and installations. - -* You must be an organization owner. If you don't have an organization, you can [create an organization for free](https://app.vsaex.visualstudio.com/profile/account). -* Install [Node.js](https://nodejs.org). -* Install the extension packaging tool (TFX). Run `npm install -g tfx-cli` from a command prompt, which you'll use to [package your extension](../publish/overview.md) later on. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Owner of the organization.| +|**Tools** |- [Node.js](https://nodejs.org)
        - Extension packaging tool: Run `npm install -g tfx-cli` from a command prompt, which you use to [package your extension](../publish/overview.md) later on.| ## Create a directory and manifest @@ -38,7 +37,7 @@ An extension is composed of a set of files that includes a required manifest fil mkdir my-first-extension ``` -2. From this directory, initialize a new npm package manifest: +2. Initialize a new npm package manifest from this directory: ``` npm init -y @@ -46,13 +45,13 @@ An extension is composed of a set of files that includes a required manifest fil This file describes the libraries required by your extension. -3. Install the Microsoft VSS Web Extension SDK package and save it to your npm package manifest: - +3. Install the Azure DevOps Extension SDK package and save it to your npm package manifest: + ``` npm install azure-devops-extension-sdk --save ``` - This SDK includes a JavaScript library that provides APIs required for communicating with the page your extension is embedded in. +This SDK includes a JavaScript library that provides APIs required for communicating with the page your extension is embedded in. 4. Create an extension manifest file named `vss-extension.json` at the root of your extension directory with the following content: @@ -90,7 +89,7 @@ An extension is composed of a set of files that includes a required manifest fil "addressable": true }, { - "path": "node_modules/azure-devops-extension-sdk/lib", + "path": "node_modules/azure-devops-extension-sdk", "addressable": true, "packagePath": "lib" } @@ -98,8 +97,8 @@ An extension is composed of a set of files that includes a required manifest fil } ``` - > [!NOTE] - > The `public` property controls whether the extension is visible to everyone on the Visual Studio Marketplace. Keep your extensions private during development. + > [!IMPORTANT] + > The `public` property controls whether the extension is visible to everyone on the Visual Studio Marketplace. Keep your extensions private during development. 5. Create a file named `my-hub.html` at the root of your extension directory with the following content, which is for the view (also known as a hub) contributed into the web experience. @@ -107,7 +106,27 @@ An extension is composed of a set of files that includes a required manifest fil - + + -

        Hello,

        @@ -140,7 +153,8 @@ An extension is composed of a set of files that includes a required manifest fil |-- vss-extension.json ``` -[!INCLUDE [preview](../_data/get-help.md)] + [!INCLUDE [preview](../_data/get-help.md)] + ## Next steps > [!div class="nextstepaction"] diff --git a/docs/extend/includes/add-workitem-extension-sharedevents.md b/docs/extend/includes/add-workitem-extension-sharedevents.md index c88b88a39b9..d77bc6581a3 100644 --- a/docs/extend/includes/add-workitem-extension-sharedevents.md +++ b/docs/extend/includes/add-workitem-extension-sharedevents.md @@ -2,12 +2,12 @@ ### Events -| Event | Event description | Argument | Argument description | -|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------| -| onFieldChanged | Fired after a field has changed. If the field change ran rules which updated other fields, all these changes are part of a single event. | ID | The ID of the work item. | -| changedFields | Array with the reference name of all changed fields. | ID | The ID of the work item. | -| onLoaded | Fired after when the data gets loaded in the work item form, when the user opens a work item, or when the user navigates to another work item in the triage view. | ID | The ID of the work item. | -| onReset | Fired after the user undoes the changes to the work item. | ID | The ID of the work item. | -| onRefreshed | Fired after the user refreshed the work item manually. | ID | The ID of the work item. | -| onSaved | Fired after a work item is saved. For work items in a dialog, you should target the "ms.vss-work-web.work-item-notifications" type to ensure the event fires since once the dialog closes, this contribution type gets unloaded. For more information, see Listen for events. | ID | The ID of the work item. | -| onUnloaded | Fired before the user closes the dialog, or before the user moves to another work item in the triage view. | ID | The ID of the work item. | +| Event | Event description | Argument | Argument description | +|----------------|----------------------|----------|--------------------------| +| `onFieldChanged` | Fired after a field has changed. If the field change ran rules that updated other fields, all these changes are part of a single event. | ID | The ID of the work item | +| `changedFields` | Array with the reference name of all changed fields. | ID | The ID of the work item | +| `onLoaded` | Fired after the data gets loaded in the work item form, when the user opens a work item, or when the user navigates to another work item in the triage view. | ID | The ID of the work item | +| `onReset` | Fired after the user undoes the changes to the work item. | ID | The ID of the work item | +| `onRefreshed` | Fired after the user refreshes the work item manually. | ID | The ID of the work item | +| `onSaved` | Fired after a work item is saved. For work items in a dialog, you should target the `ms.vss-work-web.work-item-notifications` type to ensure the event fires since once the dialog closes, this contribution type gets unloaded. For more information, see [Listen for events](#listenforevents). | ID | The ID of the work item | +| `onUnloaded` | Fired before the user closes the dialog, or before the user moves to another work item in the triage view. | ID | The ID of the work item | diff --git a/docs/extend/includes/manifest-core.md b/docs/extend/includes/manifest-core.md index 1c1d233a2ac..745f9b1c8ff 100644 --- a/docs/extend/includes/manifest-core.md +++ b/docs/extend/includes/manifest-core.md @@ -1,4 +1,4 @@ - + These properties are required: | Property | Description | Notes | @@ -8,5 +8,5 @@ These properties are required: | **version** | *A string specifying the version of an extension.* | Should be in the format `major.minor.patch`, for example `0.1.2` or `1.0.0`. You can also add a fourth number for the following format: `0.1.2.3`| | **name** | *A short, human-readable name of the extension. Limited to 200 characters.* | Example: `"Fabrikam Agile Board Extension"`. | | **publisher** | *The identifier of the publisher.* | This identifier must match the identifier the extension is published under. See [Create and manage a publisher](../publish/overview.md). | -| **categories** | *Array of strings representing the categories your extension belongs to. At least one category must be provided and there's no limit to how many categories you may include.* | Valid values: `Azure Repos`, `Azure Boards`, `Azure Pipelines`, `Azure Test Plans`, and `Azure Artifacts`.

        Notes:
        • Use version >=0.6.3 of the tfx-cli if you're publishing the extension programmatically.
        • If you're using [Azure DevOps Extension Tasks extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-developer-tools-build-tasks) to publish, ensure that its version is >= 1.2.8. You might have to approve the extension update because of recent scope changes.
        • The categories previously mentioned are natively present in Visual Studio Marketplace and Azure DevOps Server 2019 & above. For extensions targeting earlier versions of TFS:
          • If TFS customers acquire your extension via Visual Studio Marketplace (not local gallery) in connected context, then use the categories that are previously stated.
          • If you are going to share the extension directly (that is, not via the Visual Studio Marketplace) with a customer using TFS <=2018 then use the following categories instead: Code, Plan and track, Build and release, Test, Collaborate, and Integrate. If you need to share both via Visual Studio Marketplace and directly with a TFS <= 2018 customer then you would need to have 2 extension packages.
        | -| **targets** | *The products and services supported by your integration or extension.* For more information, see [installation targets](../develop/manifest.md#installation-targets). | An array of objects, where each object has an `id` field indicating one of the following:
        • `Microsoft.VisualStudio.Services` (extensions that works with Azure DevOps or TFS),
        • `Microsoft.TeamFoundation.Server` (extension that works with TFS),
        • `Microsoft.VisualStudio.Services.Integration` (integrations that works with Azure DevOps or TFS),
        • `Microsoft.TeamFoundation.Server.Integration` (integrations that work with TFS)
        | \ No newline at end of file +| **categories** | *Array of strings representing the categories your extension belongs to. At least one category must be provided and there's no limit to how many categories you may include.* | Valid values: `Azure Repos`, `Azure Boards`, `Azure Pipelines`, `Azure Test Plans`, and `Azure Artifacts`.

        Notes:
          - Use version >=0.6.3 of the tfx-cli if you're publishing the extension programmatically.
          - If you're using [Azure DevOps Extension Tasks extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-developer-tools-build-tasks) to publish, ensure that its version is >= 1.2.8. You might have to approve the extension update because of recent scope changes.
          - The categories previously mentioned are natively present in Visual Studio Marketplace and Azure DevOps Server 2019 & above.
      | +| **targets** | *The products and services supported by your integration or extension.* For more information, see [installation targets](../develop/manifest.md#installation-targets). | An array of objects, where each object has an `id` field indicating one of the following:
        - `Microsoft.VisualStudio.Services` (extensions that works with Azure DevOps),
        - `Microsoft.TeamFoundation.Server` (extension that works with Azure DevOps Server),
        - `Microsoft.VisualStudio.Services.Integration`,
        - `Microsoft.TeamFoundation.Server.Integration` (integrations that work with Azure DevOps Server)
      | diff --git a/docs/extend/includes/manifest-extension-runtime.md b/docs/extend/includes/manifest-extension-runtime.md index 7b3b821ec93..6027fdc748b 100644 --- a/docs/extend/includes/manifest-extension-runtime.md +++ b/docs/extend/includes/manifest-extension-runtime.md @@ -4,4 +4,4 @@ | **demands** | *An array of demands (strings) listing the capabilities required by your extension.* | For example, `api-version/3.0` indicates that your extension uses version 3.0 APIs, and so can't run in older products that don't support this version. For more information, see the [full list of demands](../develop/manifest.md#demands). | | **baseUri** | *(Optional) base URL for all relative URLs specified by the extension's contributions.* | For example: ```https://myapp.com/{{account.name}}/```. This property should be left empty if your extension's contents are packaged with your extension. | | **contributions** | *An array of contributions to the system.* | | -| **contributionTypes** | *An array of contribution types defined by the extension* | | \ No newline at end of file +| **contributionTypes** | *An array of contribution types defined by the extension* | | diff --git a/docs/extend/includes/procedures/create-hub-group.md b/docs/extend/includes/procedures/create-hub-group.md index 0e3be01230a..ef8cb405238 100644 --- a/docs/extend/includes/procedures/create-hub-group.md +++ b/docs/extend/includes/procedures/create-hub-group.md @@ -25,7 +25,7 @@ ms.date: 02/24/2022 ] ``` - Look at the contribution targets reference to see the [available hub groups that can be contributed to](../../reference/targets/overview.md#targets). + Look at the contribution targets reference to see the [available hub groups that can be contributed to](../../reference/targets/overview.md). 2. Change the hub contribution so that it's in the samples hub group that you just created. Just update the targets to the relative contribution ID of the hub group you just added. @@ -45,7 +45,7 @@ ms.date: 02/24/2022 } ``` -4. [Install](../../develop/install.md) your extension. +3. [Install](../../develop/install.md) your extension. Now your hub appears under your Samples hub group. diff --git a/docs/extend/includes/procedures/publish.md b/docs/extend/includes/procedures/publish.md index 0a1fd8a319b..a8078a4e1aa 100644 --- a/docs/extend/includes/procedures/publish.md +++ b/docs/extend/includes/procedures/publish.md @@ -8,13 +8,13 @@ Once your extension is packaged, you can upload it to the Marketplace under a pu 3. Drag and drop your file or select it to find your VSIX file, which you created in the previous packaging step, and then choose **Upload**. - ![Upload new extension for Azure DevOps.](../../get-started/media/upload-new-extension2.png) + ![Screenshot showing Upload of new extension for Azure DevOps.](../../get-started/media/upload-new-extension2.png) After quick validation, your extension appears in the list of published extensions. Don't worry, the extension is only visible to you. :::image type="content" source="../../get-started/media/published-extension.png" alt-text="Screenshot showing extension in the list of published extensions."::: -At this point, your extension isn't visible to any accounts and can't be installed until you share it. +At this point, your extension isn't visible to any accounts. To make it visible to others, you need to share the extension. > [!NOTE] > Microsoft runs a virus scan on each new and updated extension package published. Until the scan is all clear, we don't publish the extension in the Marketplace for public usage. This way we also avoid surfacing inappropriate or offensive content on the Marketplace pages. diff --git a/docs/extend/includes/procedures/update.md b/docs/extend/includes/procedures/update.md index 7fa476cf0b3..a365f8041bb 100644 --- a/docs/extend/includes/procedures/update.md +++ b/docs/extend/includes/procedures/update.md @@ -12,5 +12,3 @@ To change an extension that's already published, update it. 5. Browse to the .vsix for your extension and upload it. The updated version of your extension automatically gets installed to accounts that have it already installed. New accounts where the extension is installed in the future also receive the latest version. - - diff --git a/docs/extend/includes/tip-for-more-information.md b/docs/extend/includes/tip-for-more-information.md index 8ba31d549bc..16714f5855c 100644 --- a/docs/extend/includes/tip-for-more-information.md +++ b/docs/extend/includes/tip-for-more-information.md @@ -1,2 +1,2 @@ > [!TIP] -> For more information, see [Extensibility points, menus and toolbars](../reference/targets/overview.md#menus-and-toolbars), the [Contribution model](../develop/contributions-overview.md) the [Formula Design System](https://developer.microsoft.com/azure-devops/develop/extensions), [REST API reference](/rest/api/azure/devops), [Extension samples](https://github.com/Microsoft/azure-devops-extension-sample), and resources in the [Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). +> For more information, see [Extensibility points, menus and toolbars](../reference/targets/overview.md#settings-for-menus-and-toolbars), the [Contribution model](../develop/contributions-overview.md) the [Formula Design System](https://developer.microsoft.com/azure-devops/develop/extensions), [REST API reference](/rest/api/azure/devops), [Extension samples](https://github.com/Microsoft/azure-devops-extension-sample), and resources in the [Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). diff --git a/docs/extend/media/add-dashboard-widget/sample-configuration.png b/docs/extend/media/add-dashboard-widget/sample-configuration.png new file mode 100644 index 00000000000..7ae9e1c4ddf Binary files /dev/null and b/docs/extend/media/add-dashboard-widget/sample-configuration.png differ diff --git a/docs/extend/media/add-dashboard-widget/sample-configure-name-and-size.png b/docs/extend/media/add-dashboard-widget/sample-configure-name-and-size.png new file mode 100644 index 00000000000..0fb60484e1a Binary files /dev/null and b/docs/extend/media/add-dashboard-widget/sample-configure-name-and-size.png differ diff --git a/docs/extend/media/add-dashboard-widget/sampleWidgetWithNoSettings.PNG b/docs/extend/media/add-dashboard-widget/sample-widget-with-no-settings.png similarity index 100% rename from docs/extend/media/add-dashboard-widget/sampleWidgetWithNoSettings.PNG rename to docs/extend/media/add-dashboard-widget/sample-widget-with-no-settings.png diff --git a/docs/extend/media/add-dashboard-widget/sample2.png b/docs/extend/media/add-dashboard-widget/sample2.png index 4ad5423ec05..0f5e1f1a703 100644 Binary files a/docs/extend/media/add-dashboard-widget/sample2.png and b/docs/extend/media/add-dashboard-widget/sample2.png differ diff --git a/docs/extend/media/add-dashboard-widget/sampleConfiguration.PNG b/docs/extend/media/add-dashboard-widget/sampleConfiguration.PNG deleted file mode 100644 index 8525fa657db..00000000000 Binary files a/docs/extend/media/add-dashboard-widget/sampleConfiguration.PNG and /dev/null differ diff --git a/docs/extend/media/add-dashboard-widget/sampleConfigureNameAndSize.PNG b/docs/extend/media/add-dashboard-widget/sampleConfigureNameAndSize.PNG deleted file mode 100644 index 96e6a84a272..00000000000 Binary files a/docs/extend/media/add-dashboard-widget/sampleConfigureNameAndSize.PNG and /dev/null differ diff --git a/docs/extend/media/backlog-tab/iteration-backlog-tab.png b/docs/extend/media/backlog-tab/iteration-backlog-tab.png index 9ab785b62e6..0197c3ccfb7 100644 Binary files a/docs/extend/media/backlog-tab/iteration-backlog-tab.png and b/docs/extend/media/backlog-tab/iteration-backlog-tab.png differ diff --git a/docs/extend/media/backlog-tab/product-backlog-tab.png b/docs/extend/media/backlog-tab/product-backlog-tab.png index 667a2cdadb9..57b63e97366 100644 Binary files a/docs/extend/media/backlog-tab/product-backlog-tab.png and b/docs/extend/media/backlog-tab/product-backlog-tab.png differ diff --git a/docs/extend/media/create-new-personal-access-token.png b/docs/extend/media/create-new-personal-access-token.png index ecc8b88c50d..a0b0ff17a14 100644 Binary files a/docs/extend/media/create-new-personal-access-token.png and b/docs/extend/media/create-new-personal-access-token.png differ diff --git a/docs/extend/media/extension_test_custom_action.png b/docs/extend/media/extension-test-custom-action.png similarity index 100% rename from docs/extend/media/extension_test_custom_action.png rename to docs/extend/media/extension-test-custom-action.png diff --git a/docs/extend/media/extension_test_custom_tab.png b/docs/extend/media/extension-test-custom-tab.png similarity index 100% rename from docs/extend/media/extension_test_custom_tab.png rename to docs/extend/media/extension-test-custom-tab.png diff --git a/docs/extend/media/publish-azure/create-web-app.png b/docs/extend/media/publish-azure/create-web-app.png index 6dbc75fe901..9f62050bfb9 100644 Binary files a/docs/extend/media/publish-azure/create-web-app.png and b/docs/extend/media/publish-azure/create-web-app.png differ diff --git a/docs/extend/overview.md b/docs/extend/overview.md index bffb6a665ad..43dccc79dbd 100644 --- a/docs/extend/overview.md +++ b/docs/extend/overview.md @@ -1,26 +1,25 @@ --- ms.subservice: azure-devops-ecosystem title: Extensions overview -description: Overview of extensions for Azure DevOps. +description: Learn about extensions for Azure DevOps, including how to develop, package, publish, and manage them. ms.assetid: bd7bd829-e80e-4234-849f-d4b273605a22 ms.topic: conceptual ms.custom: engagement-fy23 monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 10/12/2022 +ms.date: 03/21/2025 --- # Extensions overview [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Extensions are add-ons which you can use to customize and extend your experience with Azure DevOps. -They're written with standard technologies - HTML, JavaScript, CSS - and developed using your preferred development tools. +Extensions are add-ons that you can use to customize and extend your experience with Azure DevOps. They're written using standard technologies such as HTML, JavaScript, and CSS, and can be developed using your preferred development tools. -Extensions get published at the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops), where they can be kept private for you and your team or [shared publicly](publish/publicize.md) with the millions of developers currently using Azure DevOps. +Extensions are published on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops), where they can be kept private for you and your team or [shared publicly](./publish/overview.md) with millions of developers currently using Azure DevOps. -Extensions use our [RESTful API Library](/rest/api/azure/devops/) to easily interact with Azure DevOps and applications/services. +Extensions use our [RESTful API Library](/rest/api/azure/devops/) to easily interact with Azure DevOps and other applications/services. ## Understand parts of an extension @@ -33,7 +32,7 @@ The following items make up an extension: - Discovery assets: Markdown and images that make up the extension's overview and aesthetics in the Marketplace. - Static files: Contain the logic of the extension, including HTML, JS, and CSS files. Static files are only applicable to contribution-based extensions. -These files and assets get bundled up to make a [VSIX file](/visualstudio/extensibility/anatomy-of-a-vsix-package?view=vs-2022&preserve-view=true) that's published to the Marketplace. +These files and assets get bundled up to make a [VSIX file](/visualstudio/extensibility/anatomy-of-a-vsix-package?view=vs-2022&preserve-view=true) that gets published to the Marketplace. From the Marketplace, users can [install extensions](../marketplace/install-extension.md) directly into their organization. If you don't have permissions to install an extension, but you're a project member, you can [request an extension](../marketplace/request-extensions.md) instead. @@ -45,7 +44,7 @@ There are dozens of ways you can use an extension and places where you can add t - Use [dashboard widgets](./develop/add-dashboard-widget.md) to get custom views within Azure DevOps. - Extend the [work item form](./develop/add-workitem-extension.md) with new tabs, sections, and actions. - Create [your own hub](./develop/add-hub.md) to embed new capabilities within our Agile, code, build, and test experiences. -- Develop [actions](./develop/add-action.md) that can be run on hubs, whether they're ours or ones you've created. +- Develop [actions](./develop/add-action.md) that can be run on hubs, whether they're ours or ones you created. ## Evaluate a Marketplace extension @@ -66,7 +65,7 @@ To evaluate a Marketplace extension, review the information and resources descri :::image type="content" source="../marketplace/media/top-publisher-badge.png" alt-text="Screenshot showing Top Publisher badge and label."::: :::column-end::: :::column span="2"::: - The publisher has demonstrated commitment to its customers and the Marketplace through excellent policies, quality, reliability, and support. For more information, go to [Top Publisher](#top-publisher). + The publisher demonstrates commitment to its customers and the Marketplace through excellent policies, quality, reliability, and support. For more information, see [Top Publisher](publish/overview.md#top-publisher). :::column-end::: :::row-end::: --- @@ -75,7 +74,7 @@ To evaluate a Marketplace extension, review the information and resources descri **Q & A** :::column-end::: :::column span="2"::: - The Q & A section of published extensions may answer questions you may have. Also, they're a good mechanism to engage with the extension’s publisher(s) to have a meaningful dialogue to make yourself comfortable. Use the Q & A information to understand the development, testing, and security practices the publisher follows. It also gives you a sense of the publisher's responsiveness. + The Q & A section of published extensions might answer questions you have. Also, they're a good mechanism to engage with the extension’s publishers to have a meaningful dialogue to make yourself comfortable. Use the Q & A information to understand the development, testing, and security practices the publisher follows. It also gives you a sense of the publisher's responsiveness. :::column-end::: :::row-end::: --- @@ -84,7 +83,7 @@ To evaluate a Marketplace extension, review the information and resources descri **Ratings & reviews** :::column-end::: :::column span="2"::: - Ratings and reviews indicate how others perceive the offering. + Ratings and reviews indicate how others perceive the offering. For more information, see [Respond to customer feedback](publish/overview.md#respond-to-marketplace-extension-reviews). :::column-end::: :::row-end::: --- @@ -93,44 +92,24 @@ To evaluate a Marketplace extension, review the information and resources descri **Privacy, license, and support policies** :::column-end::: :::column span="2"::: - See if the publisher has provided them and if they meet your needs or concerns. For more information, go to [Safety information](#safety-information). + See if the publisher provided them and if they meet your needs or concerns. For more information, go to [Safety information](#safety-information). :::column-end::: :::row-end::: --- ### Safety information -- **Malware scan**: The Marketplace runs a virus scan on each new and updated extension package that's published to ensure its safety. Until the scan is all clear, we don't publish the extension for public usage. If a concern surfaces, the Marketplace team has the means to disable an extension immediately and notify its existing customers. -- **Content scan**: The Marketplace scans content for every new and updated extension to avoid surfacing inappropriate or offensive content on the Marketplace pages. -- **Access to approved scopes only**: An extension can only operate within the granted scopes. For example, an extension that has only read permissions on work items can't modify your features and bugs. Azure DevOps web extensions run in a sandboxed browser IFrame. They're only able to access Azure DevOps data and APIs approved for the extension. During installation, admins are prompted to approve permissions and scopes. One way to protect yourself is to carefully review the scopes being requested by the extension. +The Marketplace ensures the safety and integrity of extensions through the following measures: - > [!NOTE] - > If the scopes change for an extension, the you must approve the update before it can become applicable on your organization or collection. - -- **Third-party build and release tasks**: Tasks are implemented as code that executes on an agent machine. Tasks are only able to access secrets explicitly provided to them (see [variable secrets](../pipelines/process/variables.md?tabs=yaml%252cbatch#secret-variables)), but tasks generally have full access to the agent machine itself. To reduce risk, run builds on Microsoft-hosted agents, which are VMs isolated from other jobs and recycled after each job. Or, limit file and network access on private hosted agent machines. Learn more about [build and release agents](../pipelines/agents/agents.md?view=azure-devops&preserve-view=true#microsoft-hosted-agents). -- **Third-party code execution on the server**: There's no way for an extension to install or execute any code on Azure DevOps Server. - -### Top Publisher - -The Top Publisher program in the Marketplace is designed to help you evaluate or acquire Azure DevOps extensions and integrations with confidence. The Top Publisher badge implies that the publisher has shown commitment to their customers and the Marketplace through exemplary policies, quality, reliability, and support. It's for publishers with one or more global Azure DevOps extensions or integrations and isn't applicable for Visual Studio IDE and Visual Studio Code extension publishers. +- **Malware scan**: The Marketplace runs a virus scan on each new and updated extension package to ensure its safety. Until the scan is clear, the extension isn't published for public usage. If a concern surfaces, the Marketplace team can disable the extension immediately and notify its existing customers. +- **Content scan**: The Marketplace scans the content of every new and updated extension to avoid surfacing inappropriate or offensive content on the Marketplace pages. +- **Access to approved scopes only**: An extension can only operate within the granted scopes. For example, an extension with read-only permissions on work items can't modify your features and bugs. Azure DevOps web extensions run in a sandboxed browser iframe and can only access Azure DevOps data and APIs approved for the extension. During installation, admins are prompted to approve permissions and scopes. To protect yourself, carefully review the scopes the extension requests. -Marketplace assigns the badge to a publisher after carefully reviewing the publisher across the following parameters: - -* Privacy policy -* Licensing policy -* Support policy -* Documentation -* Q & A responsiveness -* Ratings & review for their offerings -* Active uptake and the install count for their offerings - -You can expect timely support and a good overall experience when you get an extension from a Top Publisher. Check out the [offerings from the Top Publishers](https://marketplace.visualstudio.com/search?target=AzureDevOps&certified=certifiedpublishers). -For more information on the Top Publisher program, see the [publisher facing requirements](../extend/publish/publicize.md). - -> [!NOTE] -> Through this program, it is the publisher that is being certified. This doesn't cover the software or security of their extensions and integrations. We recommend you read the previous section when you're evaluating the offerings from a publisher. + > [!NOTE] + > If the scopes change for an extension, you must approve the update before it can be applied to your organization or collection. -If you got an extension from a Top Publisher and aren't satisfied with your experience, consider engaging with the publisher first. Afterward, if you're still unsatisfied, [contact the Marketplace team](/vsts/marketplace/marketplace-billing-qa). +- **Third-party build and release tasks**: Tasks are implemented as code that executes on an agent machine. Tasks can only access secrets explicitly provided to them (see [variable secrets](../pipelines/process/variables.md?tabs=yaml%252cbatch#secret-variables)), but generally have full access to the agent machine itself. To reduce risk, run builds on Microsoft-hosted agents, which are VMs isolated from other jobs and recycled after each job. Alternatively, limit file and network access on private hosted agent machines. Learn more about [build and release agents](../pipelines/agents/agents.md?view=azure-devops&preserve-view=true#microsoft-hosted-agents). +- **Third-party code execution on the server**: Extensions can't install or execute any code on Azure DevOps Server. ## Build an extension @@ -144,7 +123,7 @@ For more information about building extensions, see the following articles: - [Service Hooks](../service-hooks/overview.md) - [Package, publish, and install your extension](./publish/overview.md) - [Package and publish your integration with an external app or service](./publish/integration.md) -- [Share your work publicly with the entire community](./publish/publicize.md) +- [Share your work publicly with the entire community](./develop/manifest.md#mark-an-extension-public) ## Next steps diff --git a/docs/extend/publish/command-line.md b/docs/extend/publish/command-line.md index 66d9595876c..360de4aa362 100644 --- a/docs/extend/publish/command-line.md +++ b/docs/extend/publish/command-line.md @@ -18,29 +18,68 @@ You can use the Cross-platform CLI for Azure DevOps (tfx-cli) to publish your ex For more information, see the overview of [publish, install, and share](./overview.md). -## Prerequisites +### Prerequisites -Get the TFX CLI from Node Package Manager and generate a personal access token (PAT). Also, if you haven't already, set up a Publisher in the Gallery. +Get the TFX CLI from Node Package Manager and generate a Microsoft Entra token or a personal access token (PAT). Also, if you haven't already, set up a Publisher in the Gallery. ### Acquire the Cross-platform CLI for Azure DevOps [!INCLUDE [Control](../includes/procedures/acquire-tfx-cli.md)] -### Create a personal access token +### Publish with a Microsoft Entra token as a service principal -[!INCLUDE [Control](../includes/procedures/acquire-pat.md)] +It is also possible to publish an extension as a [service principal](../../integrate/get-started/authentication/service-principal-managed-identity.md). + +1. Add the service principal as a member to a publisher account. You can get the service principal's ID through the REST API by logging in via the az cli and querying the service principal's profile. This can be done with the following commands: + +# [Bash](#tab/bash) + +```azurecli-interactive +az login --service-principal --username --password --tenant +# 499b84ac-1321-427f-aa17-267ca6975798 specifies azure devops as a resource +az rest -u https://app.vssps.visualstudio.com/_apis/profile/profiles/me --resource 499b84ac-1321-427f-aa17-267ca6975798 +``` +# [PowerShell](#tab/powershell) + +```azurecli-interactive +# Variable block +$tenantId = "" +$appId = "" +$password = "" +$resource = "499b84ac-1321-427f-aa17-267ca6975798" # specifies azure devops +$url = "https://app.vssps.visualstudio.com/_apis/profile/profiles/me" + +Connect-AzAccount -ServicePrincipal -Tenant $tenantId -ApplicationId $appId -Credential (New-Object System.Management.Automation.PSCredential($appId, (ConvertTo-SecureString $password -AsPlainText -Force))) + +$accessToken = (Get-AzAccessToken -ResourceUrl $resource).Token +$response = Invoke-RestMethod -Uri $url -Headers @{Authorization = "Bearer $accessToken"} +$response +``` -## Publish from the command line +--- + +Then, you can [add the service principal as a member](/visualstudio/extensibility/walkthrough-publishing-a-visual-studio-extension#add-additional-users-to-manage-your-publisher-account) to the publisher using the ID from the previous step. + +2. Publish an extension via [TFX CLI](/azure/devops/extend/publish/command-line) using a service principal. Execute the following [TFX CLI](https://github.com/microsoft/tfs-cli/blob/master/docs/extensions.md) command to use its access token: +``` +tfx extension publish --publisher my-publisher --vsix my-publisher.my-extension-1.0.0.vsix --auth-type pat -t +``` -Once TFX CLI is installed and you have your PAT, you can use the tool to package and publish your extension. +### Publish with a personal access token + +[!INCLUDE [Control](../includes/procedures/acquire-pat.md)] + +Once TFX CLI is installed and you have your token, you can use the tool to package and publish your extension. 1. Open a command prompt to the root directory of your extension. -1. Run the following command to publish your extension. When prompted, enter your personal access token to authenticate. +1. Run the following command to publish your extension. When prompted, enter your token to authenticate. ```Command tfx extension publish --publisher --manifest-js --share-with ``` +## Potential Errors + You may receive the following error if your extension has already been published: ``` diff --git a/docs/extend/publish/includes/before-publishing.md b/docs/extend/publish/includes/before-publishing.md index 77d02cc720f..d6cd3d40c72 100644 --- a/docs/extend/publish/includes/before-publishing.md +++ b/docs/extend/publish/includes/before-publishing.md @@ -1,10 +1,8 @@ -The following list of **requirements** must be met before you publish to the Marketplace. +The following list of requirements must be met before you publish to the Marketplace. - Install the extension packaging tool (TFX). Run `npm install -g tfx-cli` from a command prompt. - Ensure the proper permissions are granted to use any images, for example, icons, logos, screenshots, and so on. - Include a thorough `overview.md` file to describe your listing in the Marketplace. - Include an icon for your extension, which is at least 128x128 pixels in size. -- When you're referring to Microsoft products, use full names in place of abbreviations, for example, Azure DevOps vs. AzDO or - any other abbreviation. +- When you refer to Microsoft products, use full names in place of abbreviations, for example, Azure DevOps vs. AzDO or - any other abbreviation. - Refrain from using brand names in the name of your extension. - - diff --git a/docs/extend/publish/includes/create-publisher.md b/docs/extend/publish/includes/create-publisher.md index 43d9ab6f5bf..cad7d0ae9e2 100644 --- a/docs/extend/publish/includes/create-publisher.md +++ b/docs/extend/publish/includes/create-publisher.md @@ -1,24 +1,22 @@ All extensions and integrations, including extensions from Microsoft, have a publisher. Anyone can create a publisher and publish extensions under it. You can also give other people access to your publisher if a team is developing the extension. -A user owns the publisher, typically the user who created it. The publisher can also be shared with other users. +A user owns the publisher, typically the user who created it. You can also share the publisher with other users. 1. Sign in to the [Visual Studio Marketplace Publishing Portal](https://marketplace.visualstudio.com/manage/createpublisher?managePageRedirect=true). 2. If you're not already a member of an existing publisher, **+ Create a publisher**. - 1. Enter a name in the publisher name field. The ID field should automatically get set based on the name you entered. + Enter a name in the publisher name field. The ID field should automatically get set based on the name you entered. :::image type="content" source="../../media/create-publisher.png" alt-text="Screenshot showing highlighted button, Create publisher."::: > [!NOTE] - > Make note of the ID. You need to set it in the manifest file of your extension. + > Make note of the ID, as you need to set it in the manifest file of your extension. If you're not prompted to create a publisher, scroll down to the bottom of the page and select **Publish extensions** below *Related sites*. - * Specify an identifier for your publisher, for example: `mycompany-myteam` - * This identifier is used as the value for the `publisher` attribute in your extension manifest file. + * Specify an identifier for your publisher, for example: `mycompany-myteam`. This identifier is used as the value for the `publisher` attribute in your extension manifest file. * Specify a display name for your publisher, for example: `My Team` -4. Review the [Marketplace Publisher Agreement](https://aka.ms/vsmarketplace-agreement), and then select **Create**. +3. Review the [Marketplace Publisher Agreement](https://aka.ms/vsmarketplace-agreement), and then select **Create**. :::image type="content" source="../../media/create-publisher.png" alt-text="Create publisher for extension"::: -Once the publisher's create, you're directed to manage items, but there aren't any items. - +Once the publisher's created, you're directed to manage items, but there aren't any items. diff --git a/docs/extend/publish/manage-ratings-reviews.md b/docs/extend/publish/manage-ratings-reviews.md deleted file mode 100644 index 8fda4e3231b..00000000000 --- a/docs/extend/publish/manage-ratings-reviews.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Manage ratings and reviews for your published extension | Extensions for Azure DevOps -description: Guidelines for responding to and requesting to void reviews for a published extension in the Visual Studio Marketplace. -ms.subservice: azure-devops-ecosystem -ms.assetid: f814d685-c0e0-48dc-adb6-ad8571a9fb73 -ms.topic: conceptual -monikerRange: '<= azure-devops' -ms.author: chcomley -author: chcomley -ms.date: 10/24/2017 ---- - -# Respond to Marketplace extension reviews - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -You can respond to reviews that customers leave for your extensions in the Visual Studio Marketplace. Find and select **Reply** next to a review if you have one of the following permissions. - -- owner -- creator -- contributor - -To respond to a review,selectReply
      - -Your response shows up under the review. - -Reply details
      - -You can leave only one response. Avoid using reviews as a support forum. If you need more details, please provide a support alias for the reviewer to -contact. You can then resolve their problems externally and then update your reply with a resolution. - -## Guidelines for publisher response to reviews - -Keep the Visual Studio Marketplace an open, inviting, respectful, and helpful place for customers to find, try, install, -and review extensions. Communication plays an important role in keeping a healthy community. To help create this environment, here are guidelines for -publishers responding to customer reviews. Think deeply about your customer interactions and reflect on the spirit of the customer experience -that the Marketplace is trying to create. - -* Reviews are reserved for customer comments. Use *Reply* only to respond to a review. -* Reviews are for sharing customer opinions, so *all opinions are valid*. Customers are entitled to their opinions, so treat comments respectfully -as feedback without debate, criticism, or argument. -* Make sure that your responses add value and are relevant to your customers' comments. -* Focus on precisely addressing questions or problems. If you need more details, ask the customer to contact you over email, rather discuss in reviews. When you -resolve the problem, update your reply with the resolution. You can edit your reply, just like customers can edit their reviews. -* If you come across any inappropriate reviews, like spam, abusive, or offensive content, for any extension, flag it for our review. - -## Publisher request to void a review - -As a publisher, you can appeal to void a review if the issue reported is because of the Marketplace or underlying platform. If the issue is valid, Marketplace admins void the rating. You can **Appeal** from ratings and review section on your extension hub page. diff --git a/docs/extend/publish/overview.md b/docs/extend/publish/overview.md index d55fc5fff48..f1238464f96 100644 --- a/docs/extend/publish/overview.md +++ b/docs/extend/publish/overview.md @@ -1,21 +1,22 @@ --- ms.subservice: azure-devops-ecosystem title: Package, publish extensions -description: An overview of how to package, publish, unpublish, and share an extension for Azure DevOps. +description: An overview of how to package, publish, unpublish, publicize, and share an extension for Azure DevOps. ms.assetid: 77b385a2-069a-4704-9a17-ad9f79a36f17 ms.custom: engagement-fy23 +ai-usage: ai-assisted ms.topic: how-to monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 10/12/2022 +ms.date: 03/25/2025 --- # Package and publish extensions [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Once you've [developed your extension](../get-started/node.md), then you can package and publish it to the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops). The Marketplace is a global repository for private and public extensions, integrations, and other offers from Microsoft. +Once you [develop your extension](../get-started/node.md), you can package and publish it to the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops). The Marketplace is a global repository for private and public extensions, integrations, and other offers from Microsoft. > [!NOTE] > For information on the discovery properties available in your extension's manifest file that helps users discover and learn about your extension, see the [Extension Manifest Reference](../develop/manifest.md#discoveryprops). @@ -28,11 +29,11 @@ Once you've [developed your extension](../get-started/node.md), then you can pac [!INCLUDE [](./includes/create-publisher.md)] - + ## Package your extension -To upload your extension, you need to package it as a VSIX 2.0-compatible .vsix file. +To upload your extension, package it as a VSIX 2.0-compatible .vsix file. Microsoft provides a cross-platform command-line interface (CLI) to package and publish your extension. 1. Open your extension manifest file (`vss-extension.json`) and set the value of the `publisher` field to the ID of your publisher. For example: @@ -52,7 +53,7 @@ Microsoft provides a cross-platform command-line interface (CLI) to package and npx tfx-cli extension create ``` - When it's completed, you see a message indicating your extension has been successfully packaged: + A message displays indicating your extension is successfully packaged: ``` === Completed operation: create extension === @@ -63,22 +64,23 @@ Microsoft provides a cross-platform command-line interface (CLI) to package and ``` > [!NOTE] -> An extension/integration's version must be incremented on every update.
      -> If you haven't incremented your extension/integration in the manifest, you should pass the `--rev-version` command line switch. This increments the *patch* version number of your extension and saves the new version to your manifest. +> Increment the version of your extension or integration in the manifest with every update.
      +> Use the `--rev-version` command line switch. This switch increments the *patch* version number of your extension and saves the new version to your manifest. #### Check package size -Check the size of the vsix after it's packaged. If it's greater than 50 MB, you need to optimize it. To do so, see the following considerations: -* De-duplicate the common dependencies, if any, by stating them once in the extension package. -* Fetch things at runtime or during install time rather than providing it within the package. Consider using the tool installer lib to pull tool dependencies at runtime. Using the lib offers benefits where the tool is cached by version so for private agents, it won't get downloaded every build. We made it a lib so it can be used outside of tool installer tasks. But, the task won't work in disconnected scenarios (no internet), which should be in the description / docs for the task. -* Some users have had success with WebPack to tree shake their dependencies in their tasks. +Check the size of the vsix after it gets packaged. If it's greater than 50 MB, you need to optimize it. To do so, see the following considerations: +- Deduplicate common dependencies by stating them once in the extension package. +- Fetch dependencies at runtime or during install time rather than including them in the package. Consider using the tool installer library to pull tool dependencies at runtime. This approach caches the tool by version for private agents, preventing downloads for every build. The tool installer library doesn't work in disconnected scenarios (no internet), which should be mentioned in the task description or documentation. +- Use WebPack to tree shake dependencies in tasks. + ## Publish your extension [!INCLUDE [Package_extension](../includes/procedures/publish.md)] ## Share your extension -You must share your extension with an organization before you can install it in Azure DevOps. To share an extension, do the following tasks: +Share your extension with an organization before you can install it in Azure DevOps. To share an extension, do the following tasks: 1. From the [Marketplace management portal](https://aka.ms/vsmarketplace-manage), select your extension from the list, right-click, and then choose **Share/Unshare** or **Publish/Unpublish**, depending on the extension. @@ -90,76 +92,36 @@ You must share your extension with an organization before you can install it in 1. Close the panel. - Your extension can now be installed into this organization. +Your extension can now be installed into this organization. ## Install your extension -To install your extension that has been shared, do the following steps. - -::: moniker range=">= azure-devops-2019" +To install your shared extension, do the following steps. 1. In the Marketplace, select your extension to open its overview page. :::image type="content" source="../get-started/media/details-page2.png" alt-text="Screenshot of the Overview page."::: -:::moniker-end > [!NOTE] - > Because your extension is private, only you and any member of the organization it is shared with can see this page. + > Since your extension is private, only you and members of the organization it's shared with can see this page. -1. Select **Get it free** to start the installation process. Select the organization you shared the extension with from the dropdown menu. +2. Select **Get it free** to start the installation process. Select the organization you shared the extension with from the dropdown menu. :::image type="content" source="../get-started/media/install-dialog.png" alt-text="Screenshot showing extension installation dialog."::: -1. Select **Install**. - -::: moniker-end - -::: moniker range=" tfs-2018" - -1. From your organization home page, select the Marketplace icon in the top-right corner and choose **Manage extensions**. - - ![Manage Extensions](media/manage-extensions.png) - -2. Find the extension under the **Shared with this organization** category. - - ![Shared with me](media/extensions-tab-shared.png) - -3. Select the card to open the item in the Marketplace. -4. From the item's details page, select **Install**. -5. Choose the organization you shared the extension with and continue through the installation process. - -::: moniker-end +3. Select **Install**. Congratulations! You installed your extension into an organization and you're ready to try it. ## Try your extension 1. Select **Proceed to organization** at the end of the installation wizard to go to the home page of the organization the extension was installed to (`https://dev.azure.com/{organization}`). - -:::moniker range=">= azure-devops-2019" - -1. Refresh your browser. -1. Open **Organization settings**, and then select **Extensions**. You should see the new extension on the **Installed** tab. +2. Refresh your browser. +3. Open **Organization settings**, and then select **Extensions**. :::image type="content" source="../get-started/media/organization-settings-extensions.png" alt-text="Screenshot of Organization settings, Extensions page."::: -:::moniker-end - -:::moniker range="tfs-2018" - -1. Open your project. - - :::image type="content" source="../get-started/media/account-home2.png" alt-text="Screenshot of project selection."::: - - If there aren't any projects in your organization, you're prompted to create one. - -2. Go to the **Code** area and then to the hub contributed by your extension (**My Hub**). - - ![My hub](../get-started/media/my-hub.png) - -You should see your new extension in the hub. - -:::moniker-end +You should see the new extension on the **Installed** tab. ## Debug your extension @@ -185,34 +147,199 @@ After you change the manifest, deploy and install this debugging extension only ## Make your extension public -For information on making your extension visible to everyone, see [Make your listing public](publicize.md). - +While you develop your extension or integration for the Marketplace, keep it private. This limits the visibility of the extension to specific accounts that you have shared it with. + +To make your extension available publicly, set the [public flag](../develop/manifest.md#public-flag) to `true` in your manifest. + +### Qualifications + +To have a public listing on the Marketplace, your integration or extension must meet the following qualifications: + +- Works with or extends Azure DevOps. +- You, or your company, own, develop, and are licensed to distribute and advertise the integration or extension. +- The extension or integration is actively maintained. + +Microsoft might also request a demo and to review the content planned for your Marketplace entry. + +## Top Publisher + +The Top Publisher program is only available for publishers with Azure DevOps extensions or integrations. It's not applicable for Visual Studio IDE and Visual Studio Code extension publishers. + +:::image type="content" source="media/top-publisher.png" alt-text="Screenshot of the Top Publisher badge."::: + +The Top Publisher program recognizes publishers with commitment to their customers and the Marketplace through exemplary policies, quality, reliability, and support. Once you become a Top Publisher, all of your public offerings display the Top Publisher badge. + +### Top Publisher requirements + +The Top Publisher program in the Marketplace is designed to help you evaluate or acquire Azure DevOps extensions and integrations with confidence. The Top Publisher badge implies that the publisher shows commitment to their customers and the Marketplace through exemplary policies, quality, reliability, and support. It's for publishers with one or more global Azure DevOps extensions or integrations and isn't applicable for Visual Studio IDE and Visual Studio Code extension publishers. + +Marketplace assigns the badge to a publisher after carefully reviewing the publisher across the following parameters: + +- Privacy policy +- Licensing policy +- Support policy +- Documentation +- Q & A responsiveness +- Ratings and reviews for their offerings +- Active uptake and install count for their offerings +- Management of at least one public extension for Azure DevOps +- Public extension with more than 5,000 installs and an active install count exceeding 1000 + +You can expect timely support and a good overall experience when you get an extension from a Top Publisher. Check out the offerings from the Top Publishers. + +For more information on adding policies to your offering, see the [extension manifest](../develop/manifest.md). + +1. Update your publisher profile. + + Through the publisher profile, you can showcase all of your offerings in one place along with key publisher-related information. To provide the information, which shows up in the profile, do the following steps: + + a. Sign in to https://marketplace.visualstudio.com/manage/publishers using the account with which you publish and manage your offerings in the Visual Studio Marketplace. + + b. Select the publisher and complete the **About you** section in the **Details** tab. + :::image type="content" source="media/microsoft-about-you-section.png" alt-text="Screenshot of the section about you for Microsoft publishers."::: + c. Save your changes and select **View profile** to see how it appears to consumers. You can use this profile page to evangelize your offerings. + +> [!NOTE] +> This program certifies the publisher, not the software, or security of their extensions and integrations. We recommend reviewing the [safety information](../overview.md#safety-information) when evaluating offerings from a publisher. If you got an extension from a Top Publisher and aren't satisfied with your experience, consider engaging with the publisher first. + +## Apply to be a Top Publisher + +1. Sign in to [Marketplace management portal](https://marketplace.visualstudio.com/manage/publishers) using the account with which you publish and manage your offerings in Marketplace. +2. Select the publisher and go to its **Top Publisher** tab. Have one or more global Azure DevOps (Server/Service) extensions or integrations for the tab to appear. +3. If you meet the previously listed requirements and are the publisher's owner, you can apply for the program. Upon application, an email gets sent to the Marketplace team to review your case. They respond within 10 business days with next steps, clarifying questions, or the grant of the badge. + +The team likely considers other parameters, such as active uptake of your offerings, install/get started counts, and ratings & reviews across your offerings before granting the badge. Microsoft reserves the right to grant, reject, or revoke the Top Publisher badge at any time. + +Once a publisher is a Top Publisher, all its future updates and offerings must meet the previously listed requirements. + +## Respond to Marketplace extension reviews + +You can respond to reviews that customers leave for your extensions in the Visual Studio Marketplace. Find and select **Reply** next to a review if you have one of the following permissions: owner, creator, or contributor. + +You can leave only one response. Avoid using reviews as a support forum. If you need more details, please provide a support alias for the reviewer to contact. You can then resolve their problems externally and update your reply with a resolution. + +### Guidelines for publisher responses + +Keep the Visual Studio Marketplace an open, inviting, respectful, and helpful place for customers to find, try, install, and review extensions. Communication plays an important role in keeping a healthy community. To help create this environment, here are guidelines for publishers responding to customer reviews. Think deeply about your customer interactions and reflect on the spirit of the customer experience that the Marketplace is trying to create. + +- Reserve reviews for customer comments. Use *Reply* only to respond to a review. +- Respect all customer opinions. Treat comments as feedback without debate, criticism, or argument. +- Ensure your responses add value and are relevant to your customers' comments. +- Focus on precisely addressing questions or problems. If you need more details, ask the customer to contact you over email rather than discussing in reviews. When you resolve the problem, update your reply with the resolution. You can edit your reply like customers can edit their reviews. +- Flag any inappropriate reviews, such as spam, abusive, or offensive content, for our review. + +## Request to void a review + +As a publisher, you can appeal to void a review if the issue reported is because of the Marketplace or underlying platform. If the issue is valid, Marketplace admins void the rating. You can **Appeal** from ratings and review section on your extension hub page. + ## Unpublish an extension -You can unpublish free extensions, if you no longer want to offer them in the Marketplace. +You can unpublish free extensions if you no longer want to offer them in the Marketplace. -The following scenarios cover when you might want to remove your extension from the Marketplace: - * You developed another extension and no longer want to offer the current one. - * Your extension has a problem, so you want to remove your extension from the Marketplace until you've resolved the problem. - * You published your extension as public by mistake. +Consider removing your extension from the Marketplace in the following scenarios: +- You developed a new extension and no longer want to offer the current one. +- Your extension has a problem, and you want to remove it from the Marketplace until you resolve the issue. +- You published your extension as public by mistake. Certain criteria must be met for an extension to be unpublished or removed: | Action | Requirements | |-----------|---------------------------------------------------------------| -| Unpublish | Only **free extensions** may be unpublished. | +| Unpublish | Only **free extensions** might be unpublished. | | Remove | Your extension must have **zero (0)** installs to be removed. | -**Important**: If you must remove your extension because of legal or security problems, contact the [Marketplace team](mailto:vsmarketplace@microsoft.com). We'll review the request and manually delete the extension. - +> [!IMPORTANT] +> If you must remove your extension because of legal or security problems, contact [Customer Support at the Developer Community](https://developercommunity.visualstudio.com/AzureDevOps). We review the request and manually delete the extension. 1. Select the extension on your [publisher page](https://aka.ms/vsmarketplace-manage) and choose **Unpublish** on the menu. Your extension is unpublished immediately from the Marketplace, and new users can't install it. Ratings and reviews for your extension stay intact. -To offer your extension again in the Marketplace, choose **Publish** on the menu. +To offer your extension again in the Marketplace, select **Publish** from the menu. + +If your extension has zero installs, you can choose to remove it completely from the Marketplace. To do so, select **Remove** from the menu. You can't reverse this action. + + + +## Extension reporting hub + +Once your extension is available in the Visual Studio Marketplace, you can use the **Reports** feature. With this feature, you can track and analyze how the extension is performing and take required actions. +To visit the extension hub, browse to your [publisher page](https://aka.ms/vsmarketplace-manage) and select the extension or select the **Reports** link on the extension details page. + +### Acquisition + +You can view acquisition-related data in this tab for the selected period. +* Aggregated acquisition in the selected period for overall acquisition +* Aggregated acquisition split by extension downloads Azure DevOps connected install for free extension +* Aggregated acquisition split by trials Azure DevOps connected buy for paid extension +* Daily trend of extension page views with acquisition for Azure DevOps and connected server +* Conversion percentage from page views to acquisition + +For paid extensions, all transactional details for buy and trials are available with date, organization name, trial end date, and quantity. You can use the **Contact** action to communicate with your users. For more information, see the [Contact](#contact) section provided later in this article. + +### Uninstall + +You can view the following statistics: +- How many organizations uninstalled your extension +- Daily trend of uninstall extensions +- Detailed feedback shared during uninstalls +- Top uninstall reasons + +You can use search for text and dates to analyze and draw more insights from the detailed feedback. + +For paid extensions, you can use the **Contact** action to communicate with your users. [Contact](#contact) section provided later in this article for more details. + +### Ratings and review + +This tab gives you the following information: +- Average rating for the selected period versus overall rating +- Average rating by number of reviewers +- Daily trend of average rating + +The details section provides all the reviews and your responses in transactional view. + +You can **Reply** to a review or **Edit** a previous response and better manage engagement with your extension users. You can also **Appeal** to void a rating if the issue reported is because of the Marketplace or underlying platform. If the issue is valid, we void the rating. + +### Manage engagement + +The Q & A tab provides a snapshot of all questions from your extension users, with nonresponded queries at the top. You can reply to or edit previous responses to better manage engagement with your extension users. + +### Export to Excel + +All data elements available in the reports page are also available for download in XLS format to aid creating your own custom reports. + +### Contact + +For paid extensions, you can use the **Contact** action to communicate with your users. This feature is available only for publishers with Contributor+ access on the extension. + +Marketplace brokers the first communication with the user as our privacy policy doesn't allow direct sharing of customer email addresses. Only users who opted in for communication receive the email. The last contacted date for an organization is updated after sending a communication. + +> [!IMPORTANT] +> Follow the guidance on transactional and promotional communication. Publishers found to be sending promotional communication or spamming users get added to a blocklist and lose access to the **Contact** feature for all their extensions. + +**Transactional communication**: Emails conveying critical information necessary for the continued use of the extension or service, such as: +- Critical security notices +- Transaction confirmations +- Product recall notices +- Specific feedback requests +- Service discontinuation notices + +**Promotional emails**: Emails used to market your extension, product, service, website, or event, such as: +- Invitations to events or webcasts +- Information about new marketing or partner programs +- Offers to obtain value-added content +- Newsletters containing promotional content + +For more information, see the [Marketplace Publisher Agreement](https://aka.ms/vsmarketplace-agreement). -You can also choose to remove your extension completely from the Marketplace if your extension has zero (0) installs. To do so, choose **Remove** on the menu. This action can't be undone. +| Terminology | Description | +|-------------|-------------| +| **Page views** | Total number of extension detail page views. Repeated views are counted. | +| **Azure DevOps Services installs** | Total number of organizations the extension is installed in. Repeated installs on the same organization get counted. | +| **Azure DevOps Server installs** | Total number of collections the extension is installed in. Repeated installs on the same collection get counted. Disconnected server data isn't available. | +## Related articles +- [Develop a web extension](../get-started/node.md) +- [Explore extensibility points](../reference/targets/overview.md) diff --git a/docs/extend/publish/publicize.md b/docs/extend/publish/publicize.md deleted file mode 100644 index 51bce855aac..00000000000 --- a/docs/extend/publish/publicize.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -ms.subservice: azure-devops-ecosystem -title: Make Your Extension or Integration Public | Extensions for Azure DevOps -description: Guideline for making an integration or extension publicly visible on the Visual Studio Marketplace -ms.assetid: d4dab00f-5089-4754-85f0-19bff1cb364a -ms.topic: conceptual -monikerRange: '>= azure-devops-2019' -ms.author: chcomley -author: chcomley -ms.date: 05/08/2019 ---- - -# Make your extension or integration public - -[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] - -> **Developing for Visual Studio or Visual Studio Code?** If so, you do not need to request verification. Verification is only required for Azure DevOps integrations or extensions. - -The [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops) is where users can get extensions, tools, products, and services that extend Visual Studio, Visual Studio Code, or Azure DevOps. - -This page covers the required steps to make your integration or extension listing publicly available in the Marketplace. - -* Learn more about developing an [extension for Azure DevOps](../overview.md) -* Learn more about [packaging and publishing an extension to the Marketplace](./overview.md) -* Learn more about [packaging and publishing an integration to the Marketplace](./integration.md) - -> As you are developing your extension or the content for your Marketplace page (for either an extension or integration), your extension can and should remain private. To make your extension available publicly, you need to set the [public flag](../develop/manifest.md#public-flag) to true in your manifest. - -## Qualifications - -To have a public listing on the Marketplace, your integration or extension must meet the following qualifications: - -- Works with or extends Azure DevOps. -- You (or your company) own, develops, and is licensed to distribute and advertise the integration or extension. -- The extension or integration is actively maintained. - -Microsoft might also request a demo and to review the content planned for your Marketplace entry. - - -## Top Publisher -> The Top Publisher program is only available for publishers with one or more public Azure DevOps extensions or integrations. It is not applicable for Visual Studio IDE and Visual Studio Code extension publishers. - -The Top Publisher program Top Publisher badge recognizes publishers who have shown commitment to their customers and the Marketplace through exemplary policies, quality, reliability, and support. Once marked so, all of their public Azure DevOps offerings (extensions and integrations) display the Top Publisher badge. This helps customers feel more confident in evaluating and acquiring their offerings. - -### Requirements - -1. For each global Azure DevOps offering under the publisher, ensure you have the following items: - - * Comprehensive and up-to-date privacy policy - * Comprehensive and up-to-date license that is, end-user license agreement - * Comprehensive and up-to-date support policy. Your customers should have access your support URL and see a clear way to get support from you: file a ticket, email your support team, or other ways to contact you. You should offer support for about 8 hours a day for all business days in your local time zone for all your offerings. And a documented low response time for paid offerings for critical issues. - * Comprehensive and high-quality documentation, which could be hosted in your domain, be within your offering, or hosted in a public GitHub repo. Customers should ideally get an overview, quickstart, and how-to-guides. - * Timely and satisfactory responses to valid questions under the Q&A section: answer all valid questions under the Q&A section timely (roughly within a week) and satisfactorily. Responses to reviews are welcome too. - - Refer the [extension manifest](../develop/manifest.md) on how to add policies to your offering. - -2. Update your publisher profile - - Through publisher profile, you have a way to showcase all of your offerings in one place along with key publisher-related information. To provide the information, which shows up in the profile: - - * Sign in to https://marketplace.visualstudio.com/manage/publishers using the account with which you publish and manage your offerings in Marketplace - * Select the publisher and fill in the About you section under the **Details** tab. Below is an example of the About you section for Microsoft (the publisher): - Microsoft Details - * Save your changes and use the 'View profile' action towards the upper portion of the page to see how it appears to consumers. You may use this profile page to evangelize your offering(s). - - -### Apply to be a Top Publisher - -1. Sign in to https://marketplace.visualstudio.com/manage/publishers using the account with which you publish and manage your offerings in Marketplace -2. Select the publisher and navigate to its **Top Publisher** tab. Note: you need to have one or more global Azure DevOps (Server/Service) extension or integration for the tab to appear. -3. If you meet part of the previously listed requirements and are the publisher's owner, you see an option to apply for the program. On application, an email is sent to the Marketplace team to review your case. They respond in under 10 business days with next steps, clarifying questions or with the grant of the badge. - -> The team likely looks at additional parameters, such as active uptake of your offerings, install/get started counts and ratings & reviews across your offerings before granting the badge.
      Microsoft reserves the right to grant, reject or revoke the Top Publisher badge at any time. - -Once a publisher is a Top Publisher, then all its future updates and offerings must meet the previously listed requirements. diff --git a/docs/extend/reference/targets/media/build/buildDefinitionActions.png b/docs/extend/reference/targets/media/build/build-definition-actions.png similarity index 100% rename from docs/extend/reference/targets/media/build/buildDefinitionActions.png rename to docs/extend/reference/targets/media/build/build-definition-actions.png diff --git a/docs/extend/reference/targets/media/build/completed-build-actions.png b/docs/extend/reference/targets/media/build/completed-build-actions.png new file mode 100644 index 00000000000..5f53bc4035b Binary files /dev/null and b/docs/extend/reference/targets/media/build/completed-build-actions.png differ diff --git a/docs/extend/reference/targets/media/build/completedBuildActions.png b/docs/extend/reference/targets/media/build/completedBuildActions.png deleted file mode 100644 index 02eeff024eb..00000000000 Binary files a/docs/extend/reference/targets/media/build/completedBuildActions.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/build/extension-test-custom-action.png b/docs/extend/reference/targets/media/build/extension-test-custom-action.png new file mode 100644 index 00000000000..ac8934d89aa Binary files /dev/null and b/docs/extend/reference/targets/media/build/extension-test-custom-action.png differ diff --git a/docs/extend/reference/targets/media/build/extension-test-custom-tab.png b/docs/extend/reference/targets/media/build/extension-test-custom-tab.png new file mode 100644 index 00000000000..01f2a4f76bd Binary files /dev/null and b/docs/extend/reference/targets/media/build/extension-test-custom-tab.png differ diff --git a/docs/extend/reference/targets/media/build/folder-menu.png b/docs/extend/reference/targets/media/build/folder-menu.png index 549affca378..2e079314ab5 100644 Binary files a/docs/extend/reference/targets/media/build/folder-menu.png and b/docs/extend/reference/targets/media/build/folder-menu.png differ diff --git a/docs/extend/reference/targets/media/build/header-menu.png b/docs/extend/reference/targets/media/build/header-menu.png index 742f64b0fb4..982f799478c 100644 Binary files a/docs/extend/reference/targets/media/build/header-menu.png and b/docs/extend/reference/targets/media/build/header-menu.png differ diff --git a/docs/extend/reference/targets/media/code/git-branches-tree-actions.png b/docs/extend/reference/targets/media/code/git-branches-tree-actions.png new file mode 100644 index 00000000000..19629ad44fb Binary files /dev/null and b/docs/extend/reference/targets/media/code/git-branches-tree-actions.png differ diff --git a/docs/extend/reference/targets/media/code/git-commit-detail-menu.png b/docs/extend/reference/targets/media/code/git-commit-detail-menu.png new file mode 100644 index 00000000000..9db75e96ba6 Binary files /dev/null and b/docs/extend/reference/targets/media/code/git-commit-detail-menu.png differ diff --git a/docs/extend/reference/targets/media/code/git-commit-list-menu.png b/docs/extend/reference/targets/media/code/git-commit-list-menu.png new file mode 100644 index 00000000000..b3e82efa21b Binary files /dev/null and b/docs/extend/reference/targets/media/code/git-commit-list-menu.png differ diff --git a/docs/extend/reference/targets/media/code/gitBranchesTreeActions.png b/docs/extend/reference/targets/media/code/gitBranchesTreeActions.png deleted file mode 100644 index 05dd8b84b01..00000000000 Binary files a/docs/extend/reference/targets/media/code/gitBranchesTreeActions.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/code/pull-request-actions.png b/docs/extend/reference/targets/media/code/pull-request-actions.png new file mode 100644 index 00000000000..4ef4a015fd5 Binary files /dev/null and b/docs/extend/reference/targets/media/code/pull-request-actions.png differ diff --git a/docs/extend/reference/targets/media/code/pull-request-tab.png b/docs/extend/reference/targets/media/code/pull-request-tab.png new file mode 100644 index 00000000000..6c502d5ab11 Binary files /dev/null and b/docs/extend/reference/targets/media/code/pull-request-tab.png differ diff --git a/docs/extend/reference/targets/media/code/pullRequestActions.png b/docs/extend/reference/targets/media/code/pullRequestActions.png deleted file mode 100644 index f0885d37ed7..00000000000 Binary files a/docs/extend/reference/targets/media/code/pullRequestActions.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/code/pullRequestTab.png b/docs/extend/reference/targets/media/code/pullRequestTab.png deleted file mode 100644 index d8d05a84d97..00000000000 Binary files a/docs/extend/reference/targets/media/code/pullRequestTab.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/code/source-grid-item-actions.png b/docs/extend/reference/targets/media/code/source-grid-item-actions.png new file mode 100644 index 00000000000..c89e0e26021 Binary files /dev/null and b/docs/extend/reference/targets/media/code/source-grid-item-actions.png differ diff --git a/docs/extend/reference/targets/media/code/source-item-actions.png b/docs/extend/reference/targets/media/code/source-item-actions.png new file mode 100644 index 00000000000..56bd2de7b54 Binary files /dev/null and b/docs/extend/reference/targets/media/code/source-item-actions.png differ diff --git a/docs/extend/reference/targets/media/code/source-tree-item-actions.png b/docs/extend/reference/targets/media/code/source-tree-item-actions.png new file mode 100644 index 00000000000..ddebefb7f48 Binary files /dev/null and b/docs/extend/reference/targets/media/code/source-tree-item-actions.png differ diff --git a/docs/extend/reference/targets/media/code/sourceGridItemActions.png b/docs/extend/reference/targets/media/code/sourceGridItemActions.png deleted file mode 100644 index eac8e62b841..00000000000 Binary files a/docs/extend/reference/targets/media/code/sourceGridItemActions.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/code/sourceTreeItemActions.png b/docs/extend/reference/targets/media/code/sourceTreeItemActions.png deleted file mode 100644 index 01a0c6d25b2..00000000000 Binary files a/docs/extend/reference/targets/media/code/sourceTreeItemActions.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/release/definition-explorer-context-menu.png b/docs/extend/reference/targets/media/release/definition-explorer-context-menu.png new file mode 100644 index 00000000000..29203af70e3 Binary files /dev/null and b/docs/extend/reference/targets/media/release/definition-explorer-context-menu.png differ diff --git a/docs/extend/reference/targets/media/release/definitionExplorerToolbarMenu.png b/docs/extend/reference/targets/media/release/definition-explorer-toolbar-menu.png similarity index 100% rename from docs/extend/reference/targets/media/release/definitionExplorerToolbarMenu.png rename to docs/extend/reference/targets/media/release/definition-explorer-toolbar-menu.png diff --git a/docs/extend/reference/targets/media/release/definitionExplorerContextMenu.png b/docs/extend/reference/targets/media/release/definitionExplorerContextMenu.png deleted file mode 100644 index 0cf2acd5149..00000000000 Binary files a/docs/extend/reference/targets/media/release/definitionExplorerContextMenu.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/release/releaseSummarySection.png b/docs/extend/reference/targets/media/release/release-summary-section.png similarity index 100% rename from docs/extend/reference/targets/media/release/releaseSummarySection.png rename to docs/extend/reference/targets/media/release/release-summary-section.png diff --git a/docs/extend/reference/targets/media/release/releaseSummaryTab.png b/docs/extend/reference/targets/media/release/release-summary-tab.png similarity index 100% rename from docs/extend/reference/targets/media/release/releaseSummaryTab.png rename to docs/extend/reference/targets/media/release/release-summary-tab.png diff --git a/docs/extend/reference/targets/media/release/releaseSummaryToolbarMenu.png b/docs/extend/reference/targets/media/release/release-summary-toolbar-menu.png similarity index 100% rename from docs/extend/reference/targets/media/release/releaseSummaryToolbarMenu.png rename to docs/extend/reference/targets/media/release/release-summary-toolbar-menu.png diff --git a/docs/extend/reference/targets/media/test/organization-settings.png b/docs/extend/reference/targets/media/test/organization-settings.png index 566d29e6595..9b8e3a535b5 100644 Binary files a/docs/extend/reference/targets/media/test/organization-settings.png and b/docs/extend/reference/targets/media/test/organization-settings.png differ diff --git a/docs/extend/reference/targets/media/test/test-plan-hub-pivot-tab-preview.png b/docs/extend/reference/targets/media/test/test-plan-hub-pivot-tab-preview.png index a4b63cce78d..f013c01f775 100644 Binary files a/docs/extend/reference/targets/media/test/test-plan-hub-pivot-tab-preview.png and b/docs/extend/reference/targets/media/test/test-plan-hub-pivot-tab-preview.png differ diff --git a/docs/extend/reference/targets/media/test/test-plans-suites-context.png b/docs/extend/reference/targets/media/test/test-plans-suites-context.png new file mode 100644 index 00000000000..8e9b05da921 Binary files /dev/null and b/docs/extend/reference/targets/media/test/test-plans-suites-context.png differ diff --git a/docs/extend/reference/targets/media/test/test-run-grid-menu.png b/docs/extend/reference/targets/media/test/test-run-grid-menu.png new file mode 100644 index 00000000000..1b67aea8647 Binary files /dev/null and b/docs/extend/reference/targets/media/test/test-run-grid-menu.png differ diff --git a/docs/extend/reference/targets/media/web/organization-overview-toolbar.png b/docs/extend/reference/targets/media/web/organization-overview-toolbar.png deleted file mode 100644 index d939adfa76a..00000000000 Binary files a/docs/extend/reference/targets/media/web/organization-overview-toolbar.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/work/backlog-board-pivot-filter-actions.png b/docs/extend/reference/targets/media/work/backlog-board-pivot-filter-actions.png new file mode 100644 index 00000000000..0713fa81c1e Binary files /dev/null and b/docs/extend/reference/targets/media/work/backlog-board-pivot-filter-actions.png differ diff --git a/docs/extend/reference/targets/media/work/backlog-item-actions.png b/docs/extend/reference/targets/media/work/backlog-item-actions.png new file mode 100644 index 00000000000..4d8986bf584 Binary files /dev/null and b/docs/extend/reference/targets/media/work/backlog-item-actions.png differ diff --git a/docs/extend/reference/targets/media/work/backlogBoardPivotFilterActions.png b/docs/extend/reference/targets/media/work/backlogBoardPivotFilterActions.png deleted file mode 100644 index 31c4882ebe9..00000000000 Binary files a/docs/extend/reference/targets/media/work/backlogBoardPivotFilterActions.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/work/backlogItemActions.png b/docs/extend/reference/targets/media/work/backlogItemActions.png deleted file mode 100644 index da9df3bffbf..00000000000 Binary files a/docs/extend/reference/targets/media/work/backlogItemActions.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/work/iteration-backlog-pane.png b/docs/extend/reference/targets/media/work/iteration-backlog-pane.png new file mode 100644 index 00000000000..23ffa8d86a8 Binary files /dev/null and b/docs/extend/reference/targets/media/work/iteration-backlog-pane.png differ diff --git a/docs/extend/reference/targets/media/work/iteration-backlog-tab.png b/docs/extend/reference/targets/media/work/iteration-backlog-tab.png new file mode 100644 index 00000000000..eb0cc39b016 Binary files /dev/null and b/docs/extend/reference/targets/media/work/iteration-backlog-tab.png differ diff --git a/docs/extend/reference/targets/media/work/portfolio-backlog-pane.png b/docs/extend/reference/targets/media/work/portfolio-backlog-pane.png new file mode 100644 index 00000000000..29aa3961f76 Binary files /dev/null and b/docs/extend/reference/targets/media/work/portfolio-backlog-pane.png differ diff --git a/docs/extend/reference/targets/media/work/product-backlog-pane.png b/docs/extend/reference/targets/media/work/product-backlog-pane.png new file mode 100644 index 00000000000..306c0bd77dd Binary files /dev/null and b/docs/extend/reference/targets/media/work/product-backlog-pane.png differ diff --git a/docs/extend/reference/targets/media/work/product-backlog-tab.png b/docs/extend/reference/targets/media/work/product-backlog-tab.png new file mode 100644 index 00000000000..558c03687dd Binary files /dev/null and b/docs/extend/reference/targets/media/work/product-backlog-tab.png differ diff --git a/docs/extend/reference/targets/media/work/query-actions.png b/docs/extend/reference/targets/media/work/query-actions.png new file mode 100644 index 00000000000..a1bb9033e3a Binary files /dev/null and b/docs/extend/reference/targets/media/work/query-actions.png differ diff --git a/docs/extend/reference/targets/media/work/query-results-item-menu.png b/docs/extend/reference/targets/media/work/query-results-item-menu.png new file mode 100644 index 00000000000..dadbd44bcec Binary files /dev/null and b/docs/extend/reference/targets/media/work/query-results-item-menu.png differ diff --git a/docs/extend/reference/targets/media/work/query-results-pivot-tab.png b/docs/extend/reference/targets/media/work/query-results-pivot-tab.png new file mode 100644 index 00000000000..2ba9ac4aa2a Binary files /dev/null and b/docs/extend/reference/targets/media/work/query-results-pivot-tab.png differ diff --git a/docs/extend/reference/targets/media/work/query-results-toolbar-menu.png b/docs/extend/reference/targets/media/work/query-results-toolbar-menu.png new file mode 100644 index 00000000000..8d16d2f126f Binary files /dev/null and b/docs/extend/reference/targets/media/work/query-results-toolbar-menu.png differ diff --git a/docs/extend/reference/targets/media/work/queryActions.png b/docs/extend/reference/targets/media/work/queryActions.png deleted file mode 100644 index 41b6fddec00..00000000000 Binary files a/docs/extend/reference/targets/media/work/queryActions.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/work/queryResultsItemMenu.png b/docs/extend/reference/targets/media/work/queryResultsItemMenu.png deleted file mode 100644 index e273be40fd3..00000000000 Binary files a/docs/extend/reference/targets/media/work/queryResultsItemMenu.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/work/queryResultsPivotTab.png b/docs/extend/reference/targets/media/work/queryResultsPivotTab.png deleted file mode 100644 index 7e1f5e5911f..00000000000 Binary files a/docs/extend/reference/targets/media/work/queryResultsPivotTab.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/work/queryResultsToolbarMenu.png b/docs/extend/reference/targets/media/work/queryResultsToolbarMenu.png deleted file mode 100644 index 2bf837b05ba..00000000000 Binary files a/docs/extend/reference/targets/media/work/queryResultsToolbarMenu.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/work/sprint-board-pivot-filter-actions.png b/docs/extend/reference/targets/media/work/sprint-board-pivot-filter-actions.png new file mode 100644 index 00000000000..a685e81332e Binary files /dev/null and b/docs/extend/reference/targets/media/work/sprint-board-pivot-filter-actions.png differ diff --git a/docs/extend/reference/targets/media/work/sprintBoardPivotFilterActions.png b/docs/extend/reference/targets/media/work/sprintBoardPivotFilterActions.png deleted file mode 100644 index 69dca8beff4..00000000000 Binary files a/docs/extend/reference/targets/media/work/sprintBoardPivotFilterActions.png and /dev/null differ diff --git a/docs/extend/reference/targets/media/work/work-item-toolbar-actions.png b/docs/extend/reference/targets/media/work/work-item-toolbar-actions.png new file mode 100644 index 00000000000..16d461dd538 Binary files /dev/null and b/docs/extend/reference/targets/media/work/work-item-toolbar-actions.png differ diff --git a/docs/extend/reference/targets/media/work/workItemToolbarActions.png b/docs/extend/reference/targets/media/work/workItemToolbarActions.png deleted file mode 100644 index 9dc522d0291..00000000000 Binary files a/docs/extend/reference/targets/media/work/workItemToolbarActions.png and /dev/null differ diff --git a/docs/extend/reference/targets/overview.md b/docs/extend/reference/targets/overview.md index 1e48972bdb0..37889f2b475 100644 --- a/docs/extend/reference/targets/overview.md +++ b/docs/extend/reference/targets/overview.md @@ -1,7 +1,7 @@ --- -title: Extensibility points +title: Extensibility Points titleSuffix: Azure DevOps -description: Browse through the places where your extension can extend Azure DevOps. +description: Browse through the places where your extension can extend Azure DevOps capabilities. ms.assetid: 007954b7-9424-4ea6-916b-8cb2f215f5c4 ms.subservice: azure-devops-ecosystem ms.custom: engagement-fy23 @@ -9,55 +9,41 @@ ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' ms.topic: overview -ms.date: 10/12/2022 +ms.date: 04/11/2025 --- # Extensibility points [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -Extensions enhance the Azure DevOps user experience by contributing new capabilities. In this article, we highlight the most common extensibility points that your extension can target. For more information about the Azure DevOps extensibility model, see the [Contribution model](../../develop/contributions-overview.md). +Extensions enhance the Azure DevOps user experience by contributing new capabilities. This article highlights the most common extensibility points that your extension can target. Extensibility points allow packages to add functionality in a manner defined by the operating system. For more information about the Azure DevOps extensibility model, see the [Contribution model](../../develop/contributions-overview.md). -The [Contributions Guide extension](https://marketplace.visualstudio.com/items/ms-samples.samples-contributions-guide) is a sample extension. Install this extension into your organization. Once it's installed, you see the extensibility points that are available. We recommend you install this extension into a personal or test organization. The [source for this extension](https://github.com/Microsoft/vso-extension-samples/tree/master/contributions-guide) is also available. -Also, find a sample of a repository creation extension point [here](https://github.com/microsoft/azure-devops-extension-sample/tree/master/src/Samples/RepositoryActions). +The [Contributions Guide extension](https://marketplace.visualstudio.com/items/ms-samples.samples-contributions-guide) is a sample extension. Install this extension into your organization. Once it's installed, you see the extensibility points that are available. We recommend you install this extension into a personal or test organization. The [source code for this extension](https://github.com/Microsoft/vso-extension-samples/tree/master/contributions-guide) is also available. For more information, see the following references: - [azure-devops-extension-api](/javascript/api/azure-devops-extension-api/) - [azure-devops-extension-sdk](/javascript/api/azure-devops-extension-sdk/) - [azure-devops-extension-sample](https://github.com/microsoft/azure-devops-extension-sample) -- [installed extension api](/rest/api/azure/devops/extensionmanagement/installed-extensions?view=azure-devops-rest-6.0&preserve-view=true) +- [installed extension API](/rest/api/azure/devops/extensionmanagement/installed-extensions?view=azure-devops-rest-6.0&preserve-view=true) ## Hubs and hub groups -Hubs and hub groups are the primary navigation elements in Azure DevOps. **Files**, **Releases**, **Backlogs**, and **Queries** are examples of hubs. A hub belongs to a hub group. The **Files** hub, for example, belongs to the project-level **Azure Repos** hub group. Hub groups can exist at the organization or collection level or the project level. Most extensions contribute to the project level. +Hubs and hub groups are the primary navigation elements in Azure DevOps. **Files**, **Releases**, **Backlogs**, and **Queries** are examples of hubs. A hub belongs to a hub group. The **Files** hub, for example, belongs to the project-level **Azure Repos** hub group. Hub groups can exist at the organization or collection level or at the project level. Most extensions contribute to the project level. -The following table describes the most common hub groups in Azure DevOps that you can contribute hubs to. +The following table describes the most common hub groups in Azure DevOps where you can contribute hubs. -::: moniker range=">= azure-devops-2019" - -| Name | ID | Level | Preview image| -| --------------------|--------------------------------------------|--------------------------|----------------------------- | -| Azure Boards | `ms.vss-work-web.work-hub-group` | Project/team | ![Custom hub added to Azure Boards.](media/work/azure-boards.png)| -| Azure Repos | `ms.vss-code-web.code-hub-group` | Project/team | ![Custom hub added to Azure Repos.](media/code/azure-repos.png)| -| Azure Pipelines | `ms.vss-build-web.build-release-hub-group` | Project/team | ![Custom hub added to Azure Pipelines.](media/build/azure-pipelines.png)| -| Azure Test Plans | `ms.vss-test-web.test-hub-group` | Project/team | ![Custom hub added to Azure Test Plans.](media/test/azure-test-plans.png)| -| Project settings | `ms.vss-web.project-admin-hub-group` | Project | ![Custom project admin hub.](media/test/project-settings.png)| -| Organization settings | `ms.vss-web.collection-admin-hub-group` | Organization or collection | ![Custom organization admin hub.](media/test/organization-settings.png) | -::: moniker-end - -::: moniker range="< azure-devops-2019" - -| Name | ID | Level | Preview image| -| --------------------|--------------------------------------------|---------------------------------|----------------------------- | -| Code | `ms.vss-code-web.code-hub-group` | Project/team | ![Custom code hub, TFS versions](media/code/hubs-source.png)| -| Work | `ms.vss-work-web.work-hub-group` | Project/team | ![Custom work hub, TFS versions](media/work/hubs-workitems.png)| -| Build and Release | `ms.vss-build-web.build-release-hub-group` | Project/team | ![Custom build and release hub, TFS versions](media/build/hubs-build-release.png)| -| Test | `ms.vss-test-web.test-hub-group` | Project/team | ![Custom test hub, TFS versions](media/test/hubs-testmanagement.png)| -| Project settings | `ms.vss-web.project-admin-hub-group` | Project | ![Custom project admin hub, TFS versions](media/web/hubs-admin-project.png) | -| Collection settings | `ms.vss-web.collection-admin-hub-group` | Collection | ![Custom collection admin hub, TFS versions](media/web/hubs-admin-collection.png) | +::: moniker range="<=azure-devops" +| Name | ID | Level | Preview image | +| --------------------|--------------------------------------------|--------------------------|----------------------------- | +| Azure Boards | `ms.vss-work-web.work-hub-group` | Project/team | :::image type="content" source="media/work/azure-boards.png" alt-text="Screenshot of custom work hub added to Azure Boards."::: | +| Azure Repos | `ms.vss-code-web.code-hub-group` | Project/team | :::image type="content" source="media/code/azure-repos.png" alt-text="Screenshot of custom work hub added to Azure Repos."::: | +| Azure Pipelines | `ms.vss-build-web.build-release-hub-group` | Project/team | :::image type="content" source="media/build/azure-pipelines.png" alt-text="Screenshot of custom hub added to Azure Pipelines."::: | +| Azure Test Plans | `ms.vss-test-web.test-hub-group` | Project/team | :::image type="content" source="media/test/azure-test-plans.png" alt-text="Screenshot of custom hub added to Azure Test Plans."::: | +| Project settings | `ms.vss-web.project-admin-hub-group` | Project | :::image type="content" source="media/test/project-settings.png" alt-text="Screenshot of custom project admin hub."::: | +| Organization settings | `ms.vss-web.collection-admin-hub-group` | Organization or collection | :::image type="content" source="media/test/organization-settings.png" alt-text="Screenshot of custom organization admin hub."::: | ::: moniker-end ### Example @@ -83,9 +69,10 @@ The following example shows how to contribute a hub to the Code hub group: ] } ``` -* `ms.vss-web.hub` is the type of this contribution. This type is defined in the `vss-web` extension published under the `ms` publisher. This type declares optional and required properties that are required by contributions of this type (for example, name, order, and so on). -* `ms.vss-code-web.code-hub-group` is the full ID of the hub group contribution this hub is targeting. This contribution is declared in the `vss-code-web` extension published under the `ms` publisher -* `my-custom-hub` is the short ID of this contribution; `{publisherId}.{extensionId}.my-custom-hub` is the full ID + +* `ms.vss-web.hub` is the type of contribution. This type is defined in the `vss-web` extension published under the `ms` publisher. This type declares optional and required properties that are required by contributions of this type (for example, name, order, and so on). +* `ms.vss-code-web.code-hub-group` is the full ID of the hub group contribution that this hub targets. This contribution is declared in the `vss-code-web` extension published under the `ms` publisher. +* `my-custom-hub` is the short ID of this contribution; `{publisherId}.{extensionId}.my-custom-hub` is the full ID. @@ -114,196 +101,110 @@ Using the [Office UI Fabric Icons](https://uifabricicons.azurewebsites.net/) exa } ``` - ## Settings for menus and toolbars | Name | Target ID | -| ----------------------------------|-----------------------------------------------------| -| Organization/collection) overview toolbar | `ms.vss-admin-web.collection-overview-toolbar-menu` | -| Collection overview projects grid | `ms.vss-admin-web.projects-grid-menu` | -| Project overview toolbar | `ms.vss-admin-web.project-overview-toolbar-menu` | -| Project overview teams grid | `ms.vss-admin-web.teams-grid-menu` | +| ----------------------------------|-----------------------------------------------------| +| Organization/collection overview toolbar | `ms.vss-admin-web.collection-overview-toolbar-menu` | +| Collection overview projects grid | `ms.vss-admin-web.projects-grid-menu` | +| Project overview toolbar | `ms.vss-admin-web.project-overview-toolbar-menu` | +| Project overview teams grid | `ms.vss-admin-web.teams-grid-menu` | -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Azure Boards menu and toolbar -| Name | Target ID | Preview image | -| --------------------------------|---------------------------------------------------|------------------- | -| Work item query menu | `ms.vss-work-web.work-item-query-menu` | ![Custom query action added to query menu. ](media/work/queryActions.png)| -| Work item query results toolbar menu | `ms.vss-work-web.work-item-query-results-toolbar-menu` | ![Query Results custom toolbar menu action](media/work/queryResultsToolbarMenu.png)| -| Work item query results menu item | `ms.vss-work-web.query-result-work-item-menu` | ![Query Result Item Menu custom action.](media/work/queryResultsItemMenu.png)| -| Work item query results tab | `ms.vss-work-web.query-tabs` | ![Query toolbar custom pivot tab ](media/work/queryResultsPivotTab.png)| -| Work item for context menu | `ms.vss-work-web.work-item-toolbar-menu` | ![Custom work item toolbar actions.](media/work/workItemToolbarActions.png)| -| Backlog item menu | `ms.vss-work-web.backlog-item-menu` | ![Backlog item actions custom menu options. ](media/work/backlogItemActions.png)| -| Sprint board pivot filter menu | `ms.vss-work-web.sprint-board-pivot-filter-menu` | ![Sprint Board Pivot Filter Actions.](media/work/sprintBoardPivotFilterActions.png)| -| Board pivot filter menu | `ms.vss-work-web.backlog-board-pivot-filter-menu` | ![Backlog Board Pivot Filter Actions.](media/work/backlogBoardPivotFilterActions.png)| -| Card menu | `ms.vss-work-web.backlog-board-card-item-menu` | | -| Product backlog tab | `ms.vss-work-web.product-backlog-tabs` | ![Product Backlog Custom Tab](../../media/backlog-tab/product-backlog-tab.png)| -| Iteration backlog tab | `ms.vss-work-web.iteration-backlog-tabs` | ![Iterations Backlog Custom Tab](../../media/backlog-tab/iteration-backlog-tab.png)| -| Portfolio backlog pane | `ms.vss-work-web.portfolio-backlog-toolpane` | ![Portfolio Backlog Custom Pane](../../media/backlog-pane/portfolio-backlog-pane.png)| -| Product backlog pane | `ms.vss-work-web.requirement-backlog-toolpane` | ![Product Backlog Custom Pane](../../media/backlog-pane/product-backlog-pane.png)| -| Iteration backlog pane | `ms.vss-work-web.iteration-backlog-toolpane` | ![Iteration Backlog Custom Pane](../../media/backlog-pane/iteration-backlog-pane.png)| - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -## Work menu and toolbar - -| Name | Target ID | Preview image | -| --------------------------------|---------------------------------------------------|-------------------| -| Work item query menu | `ms.vss-work-web.work-item-query-menu` | ![Custom query action added to query menu, TFS versions](media/work/queryActions.png)| -| Work item query results toolbar menu | `ms.vss-work-web.work-item-query-results-toolbar-menu` | ![Query Results custom toolbar menu action, TFS versions](media/work/queryResultsToolbarMenu.png)| -| Work item query results menu item | `ms.vss-work-web.query-result-work-item-menu` | ![Query Result Item Menu custom action, TFS versions](media/work/queryResultsItemMenu.png)| -| Work item query results tab | `ms.vss-work-web.query-tabs` | ![Query toolbar custom pivot tab, TFS versions](media/work/queryResultsPivotTab.png)| -| Work item for context menu | `ms.vss-work-web.work-item-toolbar-menu` | ![Custom work item toolbar actions, TFS versions](media/work/workItemToolbarActions.png)| -| Backlog item menu | `ms.vss-work-web.backlog-item-menu` | ![Backlog item actions custom menu options, TFS versions](media/work/backlogItemActions.png)| -| Sprint board pivot filter menu | `ms.vss-work-web.sprint-board-pivot-filter-menu` | ![Sprint Board Pivot Filter Actions, TFS versions](media/work/sprintBoardPivotFilterActions.png)| -| Board pivot filter menu | `ms.vss-work-web.backlog-board-pivot-filter-menu` | ![Backlog Board Pivot Filter Actions, TFS versions](media/work/backlogBoardPivotFilterActions.png)| -| Card menu | `ms.vss-work-web.backlog-board-card-item-menu` | | -| Product backlog tab | `ms.vss-work-web.product-backlog-tabs` | ![Product Backlog Custom Tab, TFS versions](../../media/backlog-tab/product-backlog-tab.png)| -| Iteration backlog tab | `ms.vss-work-web.iteration-backlog-tabs` | ![Iterations Backlog Custom Tab, TFS versions](../../media/backlog-tab/iteration-backlog-tab.png)| -| Portfolio backlog pane | `ms.vss-work-web.portfolio-backlog-toolpane` | ![Portfolio Backlog Custom Pane, TFS versions](../../media/backlog-pane/portfolio-backlog-pane.png)| -| Product backlog pane | `ms.vss-work-web.requirement-backlog-toolpane` | ![Product Backlog Custom Pane, TFS versions](../../media/backlog-pane/product-backlog-pane.png)| -| Iteration backlog pane | `ms.vss-work-web.iteration-backlog-toolpane` | ![Iteration Backlog Custom Pane, TFS versions](../../media/backlog-pane/iteration-backlog-pane.png) | - +| Name | Target ID | Preview image | +| ------------------------------------ | ------------------------------------------------------ | ------------------------------------------ | +| Work item query menu | `ms.vss-work-web.work-item-query-menu` | :::image type="content" source="media/work/query-actions.png" alt-text="Screenshot of custom query action added to query menu."::: | +| Work item query results toolbar menu | `ms.vss-work-web.work-item-query-results-toolbar-menu` | :::image type="content" source="media/work/query-results-toolbar-menu.png" alt-text="Screenshot of Query Results custom toolbar menu action."::: | +| Work item query results menu item | `ms.vss-work-web.query-result-work-item-menu` | :::image type="content" source="media/work/query-results-item-menu.png" alt-text="Screenshot of Query Results Item Menu custom action."::: | +| Work item query results tab | `ms.vss-work-web.query-tabs` | :::image type="content" source="media/work/query-results-pivot-tab.png" alt-text="Screenshot of Query toolbar custom pivot tab."::: | +| Work item for context menu | `ms.vss-work-web.work-item-toolbar-menu` | :::image type="content" source="media/work/work-item-toolbar-actions.png" alt-text="Screenshot of custom work item toolbar actions."::: | +| Backlog item menu | `ms.vss-work-web.backlog-item-menu` | :::image type="content" source="media/work/backlog-item-actions.png" alt-text="Screenshot of backlog item actions custom menu options."::: | +| Sprint board pivot filter menu | `ms.vss-work-web.sprint-board-pivot-filter-menu` | :::image type="content" source="media/work/sprint-board-pivot-filter-actions.png" alt-text="Screenshot of sprint board pivot filter menu."::: | +| Board pivot filter menu | `ms.vss-work-web.backlog-board-pivot-filter-menu` | :::image type="content" source="media/work/backlog-board-pivot-filter-actions.png" alt-text="Screenshot of Backlog Board Pivot Filter Actions."::: | +| Card menu | `ms.vss-work-web.backlog-board-card-item-menu` | | +| Product backlog tab | `ms.vss-work-web.product-backlog-tabs` | :::image type="content" source="media/work/product-backlog-tab.png" alt-text="Screenshot of product Backlog Custom Tab."::: | +| Iteration backlog tab | `ms.vss-work-web.iteration-backlog-tabs` | :::image type="content" source="media/work/iteration-backlog-tab.png" alt-text="Screenshot of iterations Backlog Custom Tab."::: | +| Portfolio backlog pane | `ms.vss-work-web.portfolio-backlog-toolpane` | :::image type="content" source="media/work/portfolio-backlog-pane.png" alt-text="Screenshot of Portfolio Backlog Custom Pane."::: | +| Product backlog pane | `ms.vss-work-web.requirement-backlog-toolpane` | :::image type="content" source="media/work/product-backlog-pane.png" alt-text="Screenshot of Product Backlog Custom Pane."::: | +| Iteration backlog pane | `ms.vss-work-web.iteration-backlog-toolpane` | :::image type="content" source="media/work/iteration-backlog-pane.png" alt-text="Screenshot of Iteration Backlog Custom Pane."::: | ::: moniker-end -::: moniker range=">= azure-devops-2019 <= azure-devops-2020" +::: moniker range="=azure-devops-2020" ## Azure Pipelines menu and toolbar -| Name | Target ID | Preview | -| --------------------------|---------------------------------------------|-------------------| -| Completed build menu | `ms.vss-build-web.completed-build-menu` | ![Completed Build Actions](media/build/completedBuildActions.png)| -| Build definitions menu | `ms.vss-build-web.build-definition-menu` | ![Build Definition Actions](media/build/buildDefinitionActions.png)| -| Test results toolbar action | `ms.vss-test-web.test-results-actions-menu` | ![Test Results Toolbar Action](../../media/extension_test_custom_action.png)| -| Test result details tab | `ms.vss-test-web.test-result-details-tab-items` | ![Test Result Details Tab](../../media/extension_test_custom_tab.png)| -| Release pipeline explorer context menu | `ms.vss-releaseManagement-web.release-definition-explorer-context-menu` | ![Definition Explorer Context Menu](media/release/definitionExplorerContextMenu.png)| -| Release pipeline explorer toolbar menu | `ms.vss-releaseManagement-web.release-definition-explorer-toolbar-menu` | ![Definition Explorer Toolbar Menu](media/release/definitionExplorerToolbarMenu.png)| -| Release summary toolbar menu | `ms.vss-releaseManagement-web.release-editor-tool-bar-menu` | ![Release Summary Toolbar Menu](media/release/releaseSummaryToolbarMenu.png)| -| Release summary tab | `ms.vss-releaseManagement-web.release-details-view` | ![Release Summary Tab](media/release/releaseSummaryTab.png)| -| Release summary section | `ms.vss-releaseManagement-web.release-details-summary-tab` | ![Release Summary Section](media/release/releaseSummarySection.png)| +| Name | Target ID | Preview | +| -------------------------------------- | ----------------------------------------------------------------------- | ------------------------ | +| Completed build menu | `ms.vss-build-web.completed-build-menu` | :::image type="content" source="media/build/completed-build-actions.png" alt-text="Screenshot of completed build actions."::: | +| Build definitions menu | `ms.vss-build-web.build-definition-menu` | :::image type="content" source="media/build/build-definition-actions.png" alt-text="Screenshot of build definition actions."::: | +| Test results toolbar action | `ms.vss-test-web.test-results-actions-menu` | :::image type="content" source="../../media/extension-test-custom-action.png" alt-text="Screenshot of test results toolbar action."::: | +| Test result details tab | `ms.vss-test-web.test-result-details-tab-items` | :::image type="content" source="../../media/extension-test-custom-tab.png" alt-text="Screenshot of test result details tab."::: | +| Release pipeline explorer context menu | `ms.vss-releaseManagement-web.release-definition-explorer-context-menu` | :::image type="content" source="media/release/definition-explorer-context-menu.png" alt-text="Screenshot of definition explorer context menu."::: | +| Release pipeline explorer toolbar menu | `ms.vss-releaseManagement-web.release-definition-explorer-toolbar-menu` | :::image type="content" source="media/release/definition-explorer-toolbar-menu.png" alt-text="Screenshot of definition explorer toolbar menu."::: | +| Release summary toolbar menu | `ms.vss-releaseManagement-web.release-editor-tool-bar-menu` | :::image type="content" source="media/release/release-summary-toolbar-menu.png" alt-text="Screenshot of release summary toolbar menu."::: | +| Release summary tab | `ms.vss-releaseManagement-web.release-details-view` | :::image type="content" source="media/release/release-summary-tab.png" alt-text="Screenshot of release summary tab."::: | +| Release summary section | `ms.vss-releaseManagement-web.release-details-summary-tab` | :::image type="content" source="media/release/release-summary-section.png" alt-text="Screenshot of release summary section."::: | ::: moniker-end ::: moniker range="azure-devops" ## Azure Pipelines menu and toolbar -| Name | Target ID | Preview | -| --------------------------|---------------------------------------------|-------------------| -| Completed build menu | `ms.vss-build-web.completed-build-menu` | ![Completed Build Actions](media/build/completedBuildActions.png)| -| Build definitions menu | `ms.vss-build-web.build-definition-menu` | ![Build Definition Actions](media/build/buildDefinitionActions.png)| -| Test results toolbar action | `ms.vss-test-web.test-results-actions-menu` | ![Test Results Toolbar Action](../../media/extension_test_custom_action.png)| -| Test result details tab | `ms.vss-test-web.test-result-details-tab-items` | ![Test Result Details Tab](../../media/extension_test_custom_tab.png)| -| Release pipeline explorer context menu | `ms.vss-releaseManagement-web.release-definition-explorer-context-menu` | ![Definition Explorer Context Menu](media/release/definitionExplorerContextMenu.png)| -| Release pipeline explorer toolbar menu | `ms.vss-releaseManagement-web.release-definition-explorer-toolbar-menu` | ![Definition Explorer Toolbar Menu](media/release/definitionExplorerToolbarMenu.png)| -| Release summary toolbar menu | `ms.vss-releaseManagement-web.release-editor-tool-bar-menu` | ![Release Summary Toolbar Menu](media/release/releaseSummaryToolbarMenu.png)| -| Release summary tab | `ms.vss-releaseManagement-web.release-details-view` | ![Release Summary Tab](media/release/releaseSummaryTab.png)| -| Release summary section | `ms.vss-releaseManagement-web.release-details-summary-tab` | ![Release Summary Section](media/release/releaseSummarySection.png)| -| Pipeline details view, header button | `ms.vss-build-web.pipelines-header-menu` | ![Pipeline details view, header menu](media/build/header-menu.png)| -| Pipeline details view, folder context menu | `ms.vss-build-web.pipelines-folder-menu` | ![Pipeline details view, folder context menu](media/build/folder-menu.png)| +| Name | Target ID | Preview | +| ------------------------------------------ | ----------------------------------------------------------------------- | -------------------- | +| Completed build menu | `ms.vss-build-web.completed-build-menu` | :::image type="content" source="media/build/completed-build-actions.png" alt-text="Screenshot of completed build actions."::: | +| Test results toolbar action | `ms.vss-test-web.test-results-actions-menu` | :::image type="content" source="media/build/extension-test-custom-action.png" alt-text="Screenshot of test results toolbar action."::: | +| Test result details tab | `ms.vss-test-web.test-result-details-tab-items` | :::image type="content" source="media/build/extension-test-custom-tab.png" alt-text="Screenshot of test result details tab."::: | +| Release pipeline explorer context menu | `ms.vss-releaseManagement-web.release-definition-explorer-context-menu` | :::image type="content" source="media/release/definition-explorer-context-menu.png" alt-text="Screenshot of definition explorer context menu."::: | +| Pipeline details view, header button | `ms.vss-build-web.pipelines-header-menu` | :::image type="content" source="media/build/header-menu.png" alt-text="Screenshot of pipeline details view, header menu."::: | +| Pipeline details view, folder context menu | `ms.vss-build-web.pipelines-folder-menu` | :::image type="content" source="media/build/folder-menu.png" alt-text="Screenshot of pipeline details view, folder context menu."::: | ### Azure Pipelines tasks -Tasks perform work in a build or release. For more information, learn how to [contribute a build or release task](../../develop/add-build-task.md). - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -## Build menu and toolbar - -| Name | Target ID | Preview image| -| --------------------------|---------------------------------------------|-------------------| -| Completed build menu | `ms.vss-build-web.completed-build-menu` | ![Completed Build Actions, TFS versions](media/build/completedBuildActions.png)| -| Build definitions menu | `ms.vss-build-web.build-definition-menu` | ![Build Definition Actions, TFS versions](media/build/buildDefinitionActions.png)| -| Test results toolbar action | `ms.vss-test-web.test-results-actions-menu` | ![Test Results Toolbar Action, TFS versions](../../media/extension_test_custom_action.png)| -| Test result details tab | `ms.vss-test-web.test-result-details-tab-items` | ![Test Result Details Tab, TFS versions](../../media/extension_test_custom_tab.png) | - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -## Release menu and toolbar - -| Name | Target ID | Preview | -| -----------------------------------------|-------------------------------------------------------------------------|-------------------| -| Release pipeline explorer context menu | `ms.vss-releaseManagement-web.release-definition-explorer-context-menu` | ![Definition Explorer Context Menu, TFS versions](media/release/definitionExplorerContextMenu.png)| -| Release pipeline explorer toolbar menu | `ms.vss-releaseManagement-web.release-definition-explorer-toolbar-menu` | ![Definition Explorer Toolbar Menu, TFS versions](media/release/definitionExplorerToolbarMenu.png)| -| Release summary toolbar menu | `ms.vss-releaseManagement-web.release-editor-tool-bar-menu` | ![Release Summary Toolbar Menu, TFS versions](media/release/releaseSummaryToolbarMenu.png)| -| Release summary tab | `ms.vss-releaseManagement-web.release-details-view` | ![Release Summary Tab, TFS versions](media/release/releaseSummaryTab.png)| -| Release summary section | `ms.vss-releaseManagement-web.release-details-summary-tab` | ![Release Summary Section, TFS versions](media/release/releaseSummarySection.png)| +Tasks perform work in a build or release. For more information, see [Add a custom pipelines task extension](../../develop/add-build-task.md). ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Azure Repos menu and toolbar -| Name | Target ID | Preview image | -| ------------------------------------|--------------------------------------------------|-------------------| -| Source item (grid) menu | `ms.vss-code-web.source-grid-item-menu` | ![Repos Item Grid Actions](media/code/sourceGridItemActions.png)| -| Source item (tree) menu | `ms.vss-code-web.source-tree-item-menu` | ![Repos Item Tree Actions](media/code/sourceTreeItemActions.png)| -| Source item (grid and tree) menu | `ms.vss-code-web.source-item-menu` | | -| Change list item menu | `ms.vss-code-web.change-list-item-menu` | | -| Change list summary item menu | `ms.vss-code-web.change-list-summary-item-menu` | | -| Git branches tree menu | `ms.vss-code-web.git-branches-tree-menu` | ![Git Branches Tree](media/code/gitBranchesTreeActions.png)| -| Git pull request actions menu | `ms.vss-code-web.pull-request-action-menu` | ![Git Pull Request Actions](media/code/pullRequestActions.png)| -| Git pull request tabs (pivots) | `ms.vss-code-web.pr-tabs` | ![Git Pull Request Tab](media/code/pullRequestTab.png)| -| Git commit listing menu | `ms.vss-code-web.git-commit-list-menu` | ![Git Commit List Menu](../../media/git-commit-list-menu.png)| -| Git commit detail menu | `ms.vss-code-web.git-commit-details-menu` | ![Git Commit Detail Menu](../../media/git-commit-detail-menu.png)| - -::: moniker-end - -::: moniker range="< azure-devops-2019" -## Code menu and toolbar - -|Name | Target ID | Preview image | -|------------------------------------|--------------------------------------------------|-------------------| -|Source item (grid) menu | `ms.vss-code-web.source-grid-item-menu` | ![Source Item Grid Actions, TFS versions](media/code/sourceGridItemActions.png)| -|Source item (tree) menu | `ms.vss-code-web.source-tree-item-menu` | ![Source Item Tree Actions, TFS versions](media/code/sourceTreeItemActions.png)| -|Source item (grid and tree) menu | `ms.vss-code-web.source-item-menu` | | -|Change list item menu | `ms.vss-code-web.change-list-item-menu` | | -|Change list summary item menu | `ms.vss-code-web.change-list-summary-item-menu` | | -|Git branches tree menu | `ms.vss-code-web.git-branches-tree-menu` | ![Git Branches Tree, TFS versions](media/code/gitBranchesTreeActions.png)| -|Git pull request actions menu | `ms.vss-code-web.pull-request-action-menu` | ![Git Pull Request Actions, TFS versions](media/code/pullRequestActions.png)| -|Git pull request tabs (pivots) | `ms.vss-code-web.pr-tabs` | ![Git Pull Request Tab, TFS versions](media/code/pullRequestTab.png)| -|Git commit listing menu | `ms.vss-code-web.git-commit-list-menu` | ![Git Commit List Menu, TFS versions](../../media/git-commit-list-menu.png)| -|Git commit detail menu | `ms.vss-code-web.git-commit-details-menu` | ![Git Commit Detail Menu, TFS versions](../../media/git-commit-detail-menu.png)| +| Name | Target ID | Preview image | +| -------------------------------- | ----------------------------------------------- | --------------------------------------------- | +| Source item (grid) menu | `ms.vss-code-web.source-grid-item-menu` | :::image type="content" source="media/code/source-grid-item-actions.png" alt-text="Screenshot of repos item grid actions."::: | +| Source item (tree) menu | `ms.vss-code-web.source-tree-item-menu` | :::image type="content" source="media/code/source-tree-item-actions.png" alt-text="Screenshot of repos item tree actions."::: | +| Source item (grid and tree) menu | `ms.vss-code-web.source-item-menu` | :::image type="content" source="media/code/source-item-actions.png" alt-text="Screenshot of repos item actions."::: | +| Change list item menu | `ms.vss-code-web.change-list-item-menu` | | +| Change list summary item menu | `ms.vss-code-web.change-list-summary-item-menu` | | +| Git branches tree menu | `ms.vss-code-web.git-branches-tree-menu` | :::image type="content" source="media/code/git-branches-tree-actions.png" alt-text="Screenshot of git branches tree."::: | +| Git pull request actions menu | `ms.vss-code-web.pull-request-action-menu` | :::image type="content" source="media/code/pull-request-actions.png" alt-text="Screenshot of git pull request actions."::: | +| Git pull request tabs (pivots) | `ms.vss-code-web.pr-tabs` | :::image type="content" source="media/code/pull-request-tab.png" alt-text="Screenshot of git pull request tab."::: | +| Git commit listing menu | `ms.vss-code-web.git-commit-list-menu` | :::image type="content" source="media/code/git-commit-list-menu.png" alt-text="Screenshot of git commit list menu."::: | +| Git commit detail menu | `ms.vss-code-web.git-commit-details-menu` | :::image type="content" source="media/code/git-commit-detail-menu.png" alt-text="Screenshot of git commit detail menu."::: | ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Azure Test Plans menu and toolbar -| Name | Target ID | Preview image | -| ---------------------------|---------------------------------------------|-------------------| -| Test run grid menu | `ms.vss-test-web.test-run-grid-menu` | | -| Test plan suites tree menu | `ms.vss-test-web.test-plans-suites-context` | | -| Test plan hub pivot tab | `ms.vss-test-web.test-plan-pivot-tabs` | ![Test Hub Pivot Tab](media/test/test-plan-hub-pivot-tab-preview.png)| - -::: moniker-end - -::: moniker range="< azure-devops-2019" -## Test menu and toolbar - -| Name | Target ID | Preview image | -| ---------------------------|---------------------------------------------|-------------------| -| Test run grid menu | `ms.vss-test-web.test-run-grid-menu` | | -| Test plan suites tree menu | `ms.vss-test-web.test-plans-suites-context` | | -| Test plan hub pivot tab | `ms.vss-test-web.test-plan-pivot-tabs` | ![Test Hub Pivot Tab, TFS versions](media/test/test-plan-hub-pivot-tab-preview.png)| +| Name | Target ID | Preview image | +| -------------------------- | ------------------------------------------- | ------------------------------------------ | +| Test run grid menu | `ms.vss-test-web.test-run-grid-menu` | :::image type="content" source="media/test/test-run-grid-menu.png" alt-text="Screenshot of test run grid menu."::: | +| Test plan suites tree menu | `ms.vss-test-web.test-plans-suites-context` | :::image type="content" source="media/test/test-plans-suites-context.png" alt-text="Screenshot of test plans suites context."::: | +| Test plan hub pivot tab | `ms.vss-test-web.test-plan-pivot-tabs` | :::image type="content" source="media/test/test-plan-hub-pivot-tab-preview.png" alt-text="Screenshot of test hub pivot tab."::: | ::: moniker-end @@ -312,16 +213,15 @@ Tasks perform work in a build or release. For more information, learn how to [co ## Other extensibility points - **Dashboard widget**: An extension can contribute a new type of widget that can be added by users to a [dashboard](../../../report/dashboards/overview.md). Learn how to [contribute a dashboard widget](../../develop/add-dashboard-widget.md). -- **Work item form**: The work item form is enhanced by extensions with new sections, tabs, actions, and custom field renderers. For more information, learn how to - [extend the work item form](../../develop/add-workitem-extension.md). -- **Service hooks**: A "consumer" is the service that events are sent to in Service Hooks. An extension can contribute consumer services. These services get configured by a user (or programmatically), to send events to that service. For more information, see [contribute a service hooks consumer](../../develop/add-service-hook.md). -- **Features**: +- **Work item form**: The work item form is enhanced by extensions with new sections, tabs, actions, and custom field renderers. For more information, learn how to [extend the work item form](../../develop/add-workitem-extension.md). +- **Service hooks**: A *consumer* is the service that events are sent to in Service Hooks. An extension can contribute consumer services. These services get configured by a user (or programmatically), to send events to that service. For more information, see [Create a custom consumer for service hooks](../../develop/add-service-hook.md). ::: moniker range="azure-devops" - **Name:** Preview feature (hosted only) - **Target ID:** ms.vss-web.managed-features +- **Features**: + **Name:** Preview feature (hosted only) + **Target ID:** ms.vss-web.managed-features ::: moniker-end - ::: moniker range="< azure-devops" - **Name:** Feature (on-premises only) - **Target ID:** ms.vss-web.managed-features-onprem +- **Features**: + **Name:** Feature (on-premises only) + **Target ID:** ms.vss-web.managed-features-onprem ::: moniker-end diff --git a/docs/get-started/index.yml b/docs/get-started/index.yml index 06e53bbe2bd..5131600d63d 100644 --- a/docs/get-started/index.yml +++ b/docs/get-started/index.yml @@ -7,11 +7,12 @@ metadata: title: Get started with Azure DevOps documentation titleSuffix: Azure DevOps description: Learn how to start using Azure DevOps to collaborate on code, build and deploy apps, or plan and track work. + ms.custom: UpdateFrequency3 ms.subservice: azure-devops-new-user ms.topic: landing-page author: chcomley ms.author: chcomley - ms.date: 09/30/2019 + ms.date: 09/17/2024 manager: jillfra # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -32,8 +33,10 @@ landingContent: url: ../repos/get-started/what-is-repos.md - text: What is Azure Pipelines? url: ../pipelines/get-started/what-is-azure-pipelines.md + - text: What is Azure Test Plans? + url: ../test/overview.md - text: Get started as a Stakeholder - url: ../organizations/security/get-started-stakeholder.md + url: ../organizations/security/get-started-stakeholder.md - title: Sign up for free linkLists: - linkListType: quickstart @@ -46,6 +49,8 @@ landingContent: url: ../repos/get-started/sign-up-invite-teammates.md - text: Azure Pipelines url: ../pipelines/get-started/pipelines-sign-up.md + - text: Azure Artifacts + url: ../artifacts/start-using-azure-artifacts.md - linkListType: how-to-guide links: - text: Connect to a project @@ -62,12 +67,22 @@ landingContent: url: ../organizations/security/change-project-level-permissions.md?toc=/azure/devops/get-started/toc.json - text: Add a project collection administrator url: ../organizations/security/change-organization-collection-level-permissions.md?toc=/azure/devops/get-started/toc.json + - text: Create a new project + url: ../organizations/projects/create-project.md?toc=/azure/devops/get-started/toc.json + - text: Delete or restore a project + url: ../organizations/projects/delete-project.md?toc=/azure/devops/get-started/toc.json + - text: Set up billing for your organization + url: ../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing - linkListType: concept links: + - text: Security overview + url: ../organizations/security/security-overview.md?toc=/azure/devops/get-started/toc.json - text: Default permissions and access url: ../organizations/security/permissions-access.md?toc=/azure/devops/get-started/toc.json - text: Permission lookup guide url: ../organizations/security/permissions-lookup-guide.md?toc=/azure/devops/get-started/toc.json + - text: About settings + url: ../organizations/settings/about-settings.md?toc=/azure/devops/get-started/toc.json - title: Plan and track work linkLists: - linkListType: quickstart @@ -76,6 +91,10 @@ landingContent: url: ../boards/get-started/plan-track-work.md - text: Create your backlog url: ../boards/backlogs/create-your-backlog.md + - text: Define sprints + url: ../boards/sprints/define-sprints.md + - text: Use boards + url: ../boards/boards/kanban-quickstart.md - title: Collaborate on code linkLists: - linkListType: quickstart @@ -88,16 +107,22 @@ landingContent: url: ../repos/git/use-ssh-keys-to-authenticate.md - text: Search code across projects url: ../project/search/functional-code-search.md + - text: Set Git repo permissions + url: ../repos/git/set-git-repository-permissions.md - title: Build and deploy your apps linkLists: - linkListType: quickstart links: - text: Create your first pipeline url: ../pipelines/get-started/pipelines-get-started.md + - text: Build multiple branches + url: ../pipelines/build/ci-build-git.md - linkListType: reference links: - - text: YAML Schema + - text: YAML schema url: /azure/devops/pipelines/yaml-schema/ + - text: Pipeline variables + url: ../pipelines/process/variables.md - title: Set your preferences linkLists: - linkListType: quickstart @@ -118,13 +143,27 @@ landingContent: url: ../project/navigation/index.md - text: Team Explorer navigation url: ../user-guide/work-team-explorer.md - - title: Migrate & import + - text: Use the command line + url: ../repos/git/command-prompt.md + - title: Migrate linkLists: - linkListType: concept links: - - text: Migrate from TFS to Azure DevOps Services + - text: Migration overview url: ../migrate/migration-overview.md - - text: Migration options - url: ../migrate/migrate-from-tfs.md - - text: Import - url: ../migrate/migration-import.md \ No newline at end of file + - text: Get started + url: ../migrate/migration-get-started.md + - text: Prerequisites + url: ../migrate/migration-prerequisites.md + - text: Validate + url: ../migrate/migration-validate.md + - text: Prepare test run + url: ../migrate/migration-prepare-test-run.md + - text: Test run + url: ../migrate/migration-test-run.md + - text: Migrate + url: ../migrate/migration-migrate.md + - text: Post-migration + url: ../migrate/migration-post-migration.md + - text: Troubleshoot + url: ../migrate/migration-troubleshooting.md \ No newline at end of file diff --git a/docs/get-started/toc.yml b/docs/get-started/toc.yml index 2ff551c06ad..5f0574df8e4 100644 --- a/docs/get-started/toc.yml +++ b/docs/get-started/toc.yml @@ -38,7 +38,7 @@ href: ../project/search/functional-code-search.md?toc=/azure/devops/get-started/toc.json - name: Search work items href: ../project/search/functional-work-item-search.md?toc=/azure/devops/get-started/toc.json -- name: Migrate & import +- name: Migrate href: ../migrate/toc.yml - name: Permissions & access items: @@ -54,8 +54,6 @@ href: ../organizations/security/data-protection.md?toc=/azure/devops/get-started/toc.json - name: Data location href: ../organizations/security/data-location.md?toc=/azure/devops/get-started/toc.json - - name: Credential storage - href: ../organizations/security/credential-storage.md?toc=/azure/devops/get-started/toc.json - name: IDE Client Resources items: - name: Visual Studio IDE diff --git a/docs/includes/ability-to-find-user-once-added.md b/docs/includes/ability-to-find-user-once-added.md index 0936e96c275..4966079a0b0 100644 --- a/docs/includes/ability-to-find-user-once-added.md +++ b/docs/includes/ability-to-find-user-once-added.md @@ -9,4 +9,4 @@ ms.date: 04/15/2021 > [!NOTE] -> You may not be able to find a user from a permissions page or identity field if the user hasn't been added to the project—either by adding it to a security group or to a project team. Also, when a user is added to Azure Active Directory or Active Directory, there can be a delay between the time they are added to the project and when they are searchable from an identity field. The delay can be between 5 minutes to 7 days. +> You may not be able to find a user from a permissions page or identity field if the user hasn't been added to the project—either by adding it to a security group or to a project team. Also, when a user is added to Microsoft Entra ID or Active Directory, there can be a delay between the time they are added to the project and when they are searchable from an identity field. The delay can be between 5 minutes to 7 days. diff --git a/docs/includes/alt-creds-deprecation-notice.md b/docs/includes/alt-creds-deprecation-notice.md index e9d6d036cbe..c609a65daa9 100644 --- a/docs/includes/alt-creds-deprecation-notice.md +++ b/docs/includes/alt-creds-deprecation-notice.md @@ -5,5 +5,5 @@ ms.topic: include --- >[!IMPORTANT] -> Azure DevOps no longer supports Alternate Credentials authentication since the beginning of March 2, 2020. If you're still using Alternate Credentials, we strongly encourage you to switch to a more secure authentication method (for example, personal access tokens). [Learn more](https://devblogs.microsoft.com/devops/azure-devops-will-no-longer-support-alternate-credentials-authentication/). +> [Azure DevOps doesn't support Alternate Credentials authentication](https://devblogs.microsoft.com/devops/azure-devops-will-no-longer-support-alternate-credentials-authentication/). If you're still using Alternate Credentials, we strongly encourage you to switch to a more secure authentication method. diff --git a/docs/includes/choose-process-introduction.md b/docs/includes/choose-process-introduction.md index 357a33d97a6..99d253f60fb 100644 --- a/docs/includes/choose-process-introduction.md +++ b/docs/includes/choose-process-introduction.md @@ -7,7 +7,7 @@ ms.date: 05/02/2023 --- -When you create a project, you choose a *process* or *process template* based on the *process model* for which your organization or collection was created. Before you choose a process for your project, understand the following terms: +When you create a project, you choose a *process* or *process template* based on the *process model* for which your organization or collection was created. Before you choose a process for your project, you should understand the following terms. |Term |Description | |---------|---------| diff --git a/docs/includes/feature-added-2022-1.md b/docs/includes/feature-added-2022-1.md new file mode 100644 index 00000000000..d24115caa33 --- /dev/null +++ b/docs/includes/feature-added-2022-1.md @@ -0,0 +1,7 @@ +--- +ms.topic: include +ms.date: 08/06/2024 +--- + +> [!NOTE] +> This feature is available starting in Azure DevOps Server 2022.1. diff --git a/docs/includes/feature-added-2022-2.md b/docs/includes/feature-added-2022-2.md new file mode 100644 index 00000000000..95c822705b2 --- /dev/null +++ b/docs/includes/feature-added-2022-2.md @@ -0,0 +1,7 @@ +--- +ms.topic: include +ms.date: 08/06/2024 +--- + +> [!NOTE] +> This feature is available starting in Azure DevOps Server 2022.2. diff --git a/docs/includes/feature-support-cloud-only.md b/docs/includes/feature-support-cloud-only.md index 4514e0c8e2e..61ad8d4e720 100644 --- a/docs/includes/feature-support-cloud-only.md +++ b/docs/includes/feature-support-cloud-only.md @@ -3,4 +3,4 @@ ms.topic: include --- > [!NOTE] -> This feature is only available on Azure DevOps Services. Typically, new features are introduced in the cloud service first, and then made available on-premises in the next major version or update of Azure DevOps Server. To learn more, see [Azure DevOps Feature Timeline](/azure/devops/release-notes/features-timeline). \ No newline at end of file +> This feature is only available on Azure DevOps Services. Typically, new features are introduced in the cloud service first, and then made available on-premises in the next major version or update of Azure DevOps Server. For more information, see [Azure DevOps Feature Timeline](/azure/devops/release-notes/features-timeline). \ No newline at end of file diff --git a/docs/includes/features-not-available-stakeholder.md b/docs/includes/features-not-available-stakeholder.md index d9f3dd6650d..5d438fccc4a 100644 --- a/docs/includes/features-not-available-stakeholder.md +++ b/docs/includes/features-not-available-stakeholder.md @@ -11,8 +11,7 @@ ms.date: 04/04/2022 If a Stakeholder needs access to one or more of the following features—which support the daily work of product owners, team leads, developers, testers, and project administrators—you need to provide them **Basic** access. > [!NOTE] -> Even if Stakeholders are explicity granted permissions to some features, they are disallowed access to the feature due to their access level. Stakeholders that choose a feature that's not available to them receive an error message indicating that they don't have permissions to complete the task. - +> Even if Stakeholders are explicitly granted permissions to some features, they are disallowed access to the feature due to their access level. Stakeholders that choose a feature that's not available to them receive an error message indicating that they don't have permissions to complete the task. ::: moniker range="azure-devops" @@ -20,7 +19,7 @@ If a Stakeholder needs access to one or more of the following features—whi - Change the priority of an item within a backlog or board - Delete work items or move work items to another project -- Change fields on cards on a Kanban board or Taskboard, except for State field +- Change fields on cards on a board or Taskboard, except for State field - Drag-and-drop work items from a Backlog to the Mapping pane (parent a work item) or Planning pane (to assign to a sprint) - Add new work item tags - Create shared queries, view query charts, and modify the home page @@ -34,12 +33,11 @@ If a Stakeholder needs access to one or more of the following features—whi ::: moniker-end - ::: moniker range="azure-devops-2020" - Change the priority of an item within a backlog or board - Delete work items or move work items to another project -- Change fields on cards on a Kanban board or Taskboard, except for State field +- Change fields on cards on a board or Taskboard, except for State field - Drag-and-drop work items from a Backlog to the Mapping pane (parent a work item) or Planning pane (to assign to a sprint) - Add new work item tags - Create shared queries, view query charts, and modify the home page @@ -48,32 +46,3 @@ If a Stakeholder needs access to one or more of the following features—whi ::: moniker-end -::: moniker range="azure-devops-2019" - -- Drag-and-drop work items from one column to another on a Kanban board or Taskboard to change the work item state -- Change the priority of an item within a backlog or board -- Delete work items or move work items to another project -- Change fields on cards on a Kanban board or Taskboard -- Drag-and-drop work items from a Backlog to the Mapping pane (parent a work item) or Planning pane (to assign to a sprint) -- Add new work item tags -- Create shared queries, view query charts, and modify the home page -- View Delivery Plans (a Marketplace extension) -- Access the full set of features under **Pipelines**, **Repos**, or **Test Plans**. - -::: moniker-end - -::: moniker range="tfs-2018" - -- Drag-and-drop work items from one column to another on a Kanban board or Taskboard to change the work item state -- Change the priority of an item within a backlog or board -- Delete work items or move work items to another project -- Change fields on cards on a Kanban board or Taskboard -- Drag-and-drop work items from a Backlog to the Mapping pane (parent a work item) or Planning pane (to assign to a sprint) -- Add new work item tags -- Create shared queries, view query charts, and modify the home page -- View Delivery Plans (a Marketplace extension) -- Access the full set of features under **Code**, **Build and Release**, or **Test**. -::: moniker-end - - - diff --git a/docs/includes/free-tier.md b/docs/includes/free-tier.md index 235cce60296..6174909fa84 100644 --- a/docs/includes/free-tier.md +++ b/docs/includes/free-tier.md @@ -2,10 +2,10 @@ ms.topic: include --- -* First five users free (Basic license) -* **Azure Pipelines:** - * One [Microsoft-hosted CI/CD](../pipelines/licensing/concurrent-jobs.md#how-much-do-parallel-jobs-cost) (one concurrent job, up to 30 hours per month) - * One self-hosted CI/CD concurrent job -* **Azure Boards:** Work item tracking and Kanban boards -* **Azure Repos:** Unlimited private Git repos -* **Azure Artifacts:** Two GiB free per organization +- First five users free (Basic license) +- **Azure Pipelines:** + - One [Microsoft-hosted CI/CD](../pipelines/licensing/concurrent-jobs.md#how-much-do-parallel-jobs-cost) (one concurrent job, up to 30 hours per month) + - One self-hosted CI/CD concurrent job +- **Azure Boards:** Work item tracking and boards +- **Azure Repos:** Unlimited private Git repos +- **Azure Artifacts:** Two GiB free per organization diff --git a/docs/includes/get-started/add-teams-to-scale.md b/docs/includes/get-started/add-teams-to-scale.md index d208c373fce..3c2155f04fa 100644 --- a/docs/includes/get-started/add-teams-to-scale.md +++ b/docs/includes/get-started/add-teams-to-scale.md @@ -13,7 +13,7 @@ As your organization grows, we recommend that you add teams to scale your projec ![Agile tools and team assets](../../organizations/settings/media/agile-tools/agile-tools-team-assets-post-2018.png) -To learn more, see the following articles: +For more information, see the following articles: - [About projects and scaling your organization](../../organizations/projects/about-projects.md) - [Add a team, move from one default team to several teams](../../organizations/settings/add-teams.md) diff --git a/docs/includes/get-started/add-users-project.md b/docs/includes/get-started/add-users-project.md index bcad9b716bc..45b8cd5e81c 100644 --- a/docs/includes/get-started/add-users-project.md +++ b/docs/includes/get-started/add-users-project.md @@ -6,7 +6,7 @@ ms.topic: include ms.date: 02/25/2022 --- - + ## Add users to your project @@ -20,7 +20,7 @@ Members of the **Project Administrators** group can add users to a project. Add Once users have been added to a project or organization, you can browse for their display name or user name (email alias) from any people-picker tool. Users can connect to a project and access features available through a supported client or the web portal. -To learn more, see the following articles: +For more information, see the following articles: - [Add users or groups to a team or project](../../organizations/security/add-users-team-project.md) - [Manage your organization or project collection, Add users to your organization](../../user-guide/manage-organization-collection.md) - [Connect to a project](../../organizations/projects/connect-to-projects.md) diff --git a/docs/includes/get-started/customize-work-tracking.md b/docs/includes/get-started/customize-work-tracking.md index 8604570bdd0..5609a9f80d6 100644 --- a/docs/includes/get-started/customize-work-tracking.md +++ b/docs/includes/get-started/customize-work-tracking.md @@ -6,8 +6,7 @@ ms.topic: include ms.date: 04/04/2022 --- - - + ### Customize work-tracking processes @@ -16,9 +15,9 @@ You and your team can start using all work-tracking tools immediately after you > [!NOTE] > By default, organization owners and users added to the **Project Collection Administrators** security group are granted permission to create, edit, and manage processes used to customize the work-tracking experience. If you want to lock down who is able to perform these tasks, you can set permissions at the organization-level to **Deny**. -To learn more, see these articles: +For more information, see these articles: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" - [About process customization and inherited processes](../../organizations/settings/work/inheritance-process-model.md) - [Customize a project](../../organizations/settings/work/customize-process.md) @@ -26,11 +25,4 @@ To learn more, see these articles: ::: moniker-end -::: moniker range="tfs-2018" - -- [On-premises XML process customization](../../reference/on-premises-xml-process-model.md) -- [Add or modify a field to track work](../../reference/add-modify-field.md) -- [Add or modify a work item type](../../reference/add-modify-wit.md) - -::: moniker-end \ No newline at end of file diff --git a/docs/includes/get-started/define-area-iteration-paths.md b/docs/includes/get-started/define-area-iteration-paths.md index bb125ea70c4..0ce0aa7b526 100644 --- a/docs/includes/get-started/define-area-iteration-paths.md +++ b/docs/includes/get-started/define-area-iteration-paths.md @@ -6,7 +6,7 @@ ms.topic: include ms.date: 02/28/2022 --- - + ### Define area and iteration paths to track work diff --git a/docs/includes/get-started/enable-remove-services.md b/docs/includes/get-started/enable-remove-services.md index 1c56c5c458a..d8754567110 100644 --- a/docs/includes/get-started/enable-remove-services.md +++ b/docs/includes/get-started/enable-remove-services.md @@ -6,12 +6,11 @@ ms.topic: include ms.date: 02/25/2022 --- - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Remove unused services -To simplify the web portal user interface, you can disable select services. For example, if you use a project only to log bugs, then disable all services except for **Boards**. To learn more, see [Turn a service on or off](../../organizations/settings/set-services.md). +To simplify the web portal user interface, you can disable select services. For example, if you use a project only to log bugs, then disable all services except for **Boards**. For more information, see [Turn a service on or off](../../organizations/settings/set-services.md). This example shows that **Test Plans** is disabled: diff --git a/docs/includes/get-started/share-project-vision.md b/docs/includes/get-started/share-project-vision.md index 500f93d2c4b..99a48ffd09e 100644 --- a/docs/includes/get-started/share-project-vision.md +++ b/docs/includes/get-started/share-project-vision.md @@ -6,7 +6,7 @@ ms.topic: include ms.date: 04/04/2022 --- - + ## Share your project vision, set up a project wiki diff --git a/docs/includes/glossary-terms/area-paths.md b/docs/includes/glossary-terms/area-paths.md index 31d9f7dd7cb..02a4bbdbbc8 100644 --- a/docs/includes/glossary-terms/area-paths.md +++ b/docs/includes/glossary-terms/area-paths.md @@ -3,4 +3,4 @@ ms.topic: include --- ## Area path -Area paths are used to group work items by team, product, or feature area. Iteration paths are used to group work into sprints, milestones, or other event-specific or time-related periods. You can use area paths to define a hierarchy of paths. To learn more, see [About area and iteration paths](../../organizations/settings/about-areas-iterations.md). \ No newline at end of file +Area paths are used to group work items by team, product, or feature area. Iteration paths are used to group work into sprints, milestones, or other event-specific or time-related periods. You can use area paths to define a hierarchy of paths. For more information, see [About area and iteration paths](../../organizations/settings/about-areas-iterations.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/dashboards.md b/docs/includes/glossary-terms/dashboards.md index 195e186eef1..4a82f7f487f 100644 --- a/docs/includes/glossary-terms/dashboards.md +++ b/docs/includes/glossary-terms/dashboards.md @@ -4,4 +4,4 @@ ms.topic: include ## Dashboards -Dashboards are user-configurable interactive signboards that provide real-time information. Dashboards are associated with a team and display configurable widgets to show information. To learn more, see [Add and manage dashboards](../../report/dashboards/dashboards.md). \ No newline at end of file +Dashboards are user-configurable interactive signboards that provide real-time information. Dashboards are associated with a team and display configurable widgets to show information. For more information, see [Add and manage dashboards](../../report/dashboards/dashboards.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/discussion.md b/docs/includes/glossary-terms/discussion.md index 8e4315965ec..781b5e65fed 100644 --- a/docs/includes/glossary-terms/discussion.md +++ b/docs/includes/glossary-terms/discussion.md @@ -4,6 +4,4 @@ ms.topic: include ## Discussion -Area within a work item form that supports adding and reviewing comments made about the work being performed. This way, you capture all comments within the work item rather than maintaining a long email thread. Within the discussion section, you can use the [@mention control](../../organizations/notifications/at-mentions.md) to notify another team member about the discussion. Simply type **@** and their name. - -Learn more: [Work item form controls](../../boards/work-items/work-item-form-controls.md#discussion). +Area within a work item form that supports adding and reviewing comments made about the work being performed. This way, you capture all comments within the work item rather than maintaining a long email thread. Within the discussion section, you can use the [@mention control](../../organizations/notifications/at-mentions.md) to notify another team member about the discussion. Simply type **@** and their name. diff --git a/docs/includes/glossary-terms/favorites.md b/docs/includes/glossary-terms/favorites.md index b800716d3a1..b3e9b5339fc 100644 --- a/docs/includes/glossary-terms/favorites.md +++ b/docs/includes/glossary-terms/favorites.md @@ -5,4 +5,4 @@ ms.topic: include ## Favorites -Tagging an object as a favorite is a method used to support quick navigation by yourself or other team members. You can tag work item queries and build definitions as personal and team favorites. Other objects you can tag as a favorite for yourself only include code branches, delivery plans, test plans, and teams or projects. To learn more, see [Set personal or team favorites](../../project/navigation/set-favorites.md). \ No newline at end of file +Tagging an object as a favorite is a method used to support quick navigation by yourself or other team members. You can tag work item queries and build definitions as personal and team favorites. Other objects you can tag as a favorite for yourself only include code branches, delivery plans, test plans, and teams or projects. For more information, see [Set personal or team favorites](../../project/navigation/set-favorites.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/follow.md b/docs/includes/glossary-terms/follow.md index 236a52fd89c..e0cb2b6592c 100644 --- a/docs/includes/glossary-terms/follow.md +++ b/docs/includes/glossary-terms/follow.md @@ -5,4 +5,4 @@ ms.topic: include ## Follow -Tagging specific work items or pull requests to follow them is a method used to receive email updates about changes that are made to them. To learn more, see [Follow a work item or pull request](../../boards/work-items/follow-work-items.md). \ No newline at end of file +Tagging specific work items or pull requests to follow them is a method used to receive email updates about changes that are made to them. For more information, see [Follow a work item or pull request](../../boards/work-items/follow-work-items.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/kanban-board.md b/docs/includes/glossary-terms/kanban-board.md index 56133b465b7..2f5c509ae25 100644 --- a/docs/includes/glossary-terms/kanban-board.md +++ b/docs/includes/glossary-terms/kanban-board.md @@ -3,4 +3,4 @@ ms.topic: include --- ## Kanban board -An interactive, electronic sign board that supports visualization of the flow of work from concept to completion and lean methods. Azure DevOps provides a Kanban board for each product and portfolio backlog. Learn more: [Kanban overview](../../boards/boards/kanban-overview.md) and [Kanban board features and epics](../../boards/boards/kanban-epics-features-stories.md). \ No newline at end of file +An interactive, electronic sign board that supports visualization of the flow of work from concept to completion and lean methods. Azure DevOps provides a board for each product and portfolio backlog. For more information, see [Board overview](../../boards/boards/kanban-overview.md) and [Board features and epics](../../boards/boards/kanban-epics-features-stories.md). diff --git a/docs/includes/glossary-terms/links-and-link-types.md b/docs/includes/glossary-terms/links-and-link-types.md index e881a8c3885..d19377ad8d9 100644 --- a/docs/includes/glossary-terms/links-and-link-types.md +++ b/docs/includes/glossary-terms/links-and-link-types.md @@ -3,4 +3,4 @@ ms.topic: include --- ## Links and link types -Links support defining relationships between work items and other objects—such as commits, branches, pull requests, and more—using different link types. Learn more: [Add link to work items](../../boards/backlogs/add-link.md), [Link work items to support traceability and manage dependencies](../../boards/queries/link-work-items-support-traceability.md) and [Link types reference](../../boards/queries/link-type-reference.md). \ No newline at end of file +Links support defining relationships between work items and other objects—such as commits, branches, pull requests, and more—using different link types. For more information, see [Link work items to other objects](../../boards/backlogs/add-link.md) and [Link types reference](../../boards/queries/link-type-reference.md). diff --git a/docs/includes/glossary-terms/plans.md b/docs/includes/glossary-terms/plans.md index 0ba070aa109..938448f2bb4 100644 --- a/docs/includes/glossary-terms/plans.md +++ b/docs/includes/glossary-terms/plans.md @@ -5,4 +5,4 @@ ms.topic: include ## Plans (also known as delivery plans) -A plan is a configurable view that displays work from multiple teams and projects laid out within a calendar based on each team's iterations. Each row in the view represents the work from a team's product or portfolio backlog. Each card corresponds to a work item, such as user story, feature, or epic. To learn more, see [Review team delivery plans](../../boards/plans/review-team-plans.md). \ No newline at end of file +A plan is a configurable view that displays work from multiple teams and projects laid out within a calendar based on each team's iterations. Each row in the view represents the work from a team's product or portfolio backlog. Each card corresponds to a work item, such as user story, feature, or epic. For more information, see [Review team delivery plans](../../boards/plans/review-team-plans.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/process.md b/docs/includes/glossary-terms/process.md index 659f72cc3c0..a423ff21d6d 100644 --- a/docs/includes/glossary-terms/process.md +++ b/docs/includes/glossary-terms/process.md @@ -2,10 +2,10 @@ ms.topic: include --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Process -A process defines the building blocks of a work-tracking system. To customize a process, you first create an inherited process from one of the default system processes, [Agile](../../boards/work-items/guidance/agile-process.md), [Scrum](../../boards/work-items/guidance/scrum-process.md), or [CMMI](../../boards/work-items/guidance/cmmi-process.md). All projects that use the process see the changes you make. To learn more, see [About process customization and inherited processes](../../organizations/settings/work/inheritance-process-model.md). +A process defines the building blocks of a work-tracking system. To customize a process, you first create an inherited process from one of the default system processes, [Agile](../../boards/work-items/guidance/agile-process.md), [Scrum](../../boards/work-items/guidance/scrum-process.md), or [CMMI](../../boards/work-items/guidance/cmmi-process.md). All projects that use the process see the changes you make. For more information, see [About process customization and inherited processes](../../organizations/settings/work/inheritance-process-model.md). ::: moniker-end \ No newline at end of file diff --git a/docs/includes/glossary-terms/product-backlog.md b/docs/includes/glossary-terms/product-backlog.md index c0bc09db171..883ab29af05 100644 --- a/docs/includes/glossary-terms/product-backlog.md +++ b/docs/includes/glossary-terms/product-backlog.md @@ -4,6 +4,6 @@ ms.topic: include ## Product backlog -An interactive list of work items that corresponds to a team's project plan or roadmap for what the team plans to deliver. The product backlog supports prioritizing work, forecasting work by sprints, and quickly linking work to portfolio backlog items. You can define your backlog items and then manage their status using the Kanban board. +An interactive list of work items that corresponds to a team's project plan or roadmap for what the team plans to deliver. The product backlog supports prioritizing work, forecasting work by sprints, and quickly linking work to portfolio backlog items. You can define your backlog items and then manage their status using the board. Each product backlog can be customized by a team. Learn more: [Create your backlog](../../boards/backlogs/create-your-backlog.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/projects.md b/docs/includes/glossary-terms/projects.md index e68f7cd49eb..f634ee074f0 100644 --- a/docs/includes/glossary-terms/projects.md +++ b/docs/includes/glossary-terms/projects.md @@ -3,4 +3,4 @@ ms.topic: include --- ## Projects -A project, which was previously known as a *team project*, provides a repository for source code. A project provides a place where a group of people can plan, track progress, and collaborate on building software solutions. A project is defined for an Azure DevOps Services organization or within a TFS project collection. You can use it to focus on those objects defined within the project. To learn more, see [About projects and scaling your organization](../../organizations/projects/about-projects.md). \ No newline at end of file +A project, which was previously known as a *team project*, provides a repository for source code. A project provides a place where a group of people can plan, track progress, and collaborate on building software solutions. A project is defined for an Azure DevOps Services organization or within a TFS project collection. You can use it to focus on those objects defined within the project. For more information, see [About projects and scaling your organization](../../organizations/projects/about-projects.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/public-projects.md b/docs/includes/glossary-terms/public-projects.md index c7ec3a788d8..3e9f123aeb7 100644 --- a/docs/includes/glossary-terms/public-projects.md +++ b/docs/includes/glossary-terms/public-projects.md @@ -4,4 +4,4 @@ ms.topic: include ## Public projects -A project created within an Azure DevOps Services organization that is visible to the whole world. Everyone in the world can discover them and perform limited operations. You can use the [Azure DevOps CLI to discover a list of projects](../../organizations/projects/create-project.md#list-and-connect-to-projects). Administrators can control who gets to fully contribute. Administrators can switch a project from private to public, and vice-versa, as described in [Change the project visibility](../../organizations/projects/make-project-public.md). \ No newline at end of file +A project created within an Azure DevOps Services organization that is visible to the whole world. Everyone in the world can discover them and perform limited operations. You can use the [Azure DevOps CLI to discover a list of projects](../../organizations/projects/create-project.md#list-projects-with-cli). Administrators can control who gets to fully contribute. Administrators can switch a project from private to public, and vice-versa, as described in [Change the project visibility](../../organizations/projects/make-project-public.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/queries.md b/docs/includes/glossary-terms/queries.md index fda106922a1..2eaa406cbf8 100644 --- a/docs/includes/glossary-terms/queries.md +++ b/docs/includes/glossary-terms/queries.md @@ -5,4 +5,4 @@ ms.topic: include ## Queries -Queries are used to find and list work items. Queries support managed searches, which are used to triage work, versus ad-hoc searches, which are used to find a specific work item. Flat-list queries also support status and trend charts. To learn more, see [About managed queries](../../boards/queries/about-managed-queries.md). \ No newline at end of file +Queries are used to find and list work items. Queries support managed searches, which are used to triage work, versus ad-hoc searches, which are used to find a specific work item. Flat-list queries also support status and trend charts. For more information, see [About managed queries](../../boards/queries/about-managed-queries.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/remote-linking.md b/docs/includes/glossary-terms/remote-linking.md index 06ebbfe6314..3ff6f7709bc 100644 --- a/docs/includes/glossary-terms/remote-linking.md +++ b/docs/includes/glossary-terms/remote-linking.md @@ -6,6 +6,6 @@ ms.topic: include ::: moniker range="azure-devops" ## Remote linking -With remote linking, you can create link relationships between work items in one organization to work items or other objects defined in another organization. Organizations must be managed by the same Azure Active Directory. Learn more: [Link work items, Link to a remote work item](../../boards/backlogs/add-link.md#remote-link). +With remote linking, you can create link relationships between work items in one organization to work items or other objects defined in another organization. Organizations must be managed by the same Microsoft Entra ID. Learn more: [Link work items, Link to a remote work item](../../boards/backlogs/add-link.md#link-work-items-to-remote-work-items-cross-organization). -::: moniker-end \ No newline at end of file +::: moniker-end diff --git a/docs/includes/glossary-terms/rollup.md b/docs/includes/glossary-terms/rollup.md index 6723a5c4d54..871c5c10b8e 100644 --- a/docs/includes/glossary-terms/rollup.md +++ b/docs/includes/glossary-terms/rollup.md @@ -2,8 +2,6 @@ ms.topic: include --- - - ## Rollup ::: moniker range=">= azure-devops-2020" @@ -12,8 +10,3 @@ Rollup refers to the sum of Remaining Work, Story Points, or other numeric field ::: moniker-end -::: moniker range="< azure-devops-2020" - -Rollup refers to the sum of Remaining Work, Story Points, or other numeric field of child and descendent work items within a hierarchy. Azure Boards supports some native rollup features. To learn more, see [Rollup of work and other fields](../../reference/xml/support-rollup-of-work-and-other-fields.md). - -::: moniker-end \ No newline at end of file diff --git a/docs/includes/glossary-terms/sprints.md b/docs/includes/glossary-terms/sprints.md index e7e5c18b83d..250e72c8a06 100644 --- a/docs/includes/glossary-terms/sprints.md +++ b/docs/includes/glossary-terms/sprints.md @@ -3,4 +3,4 @@ ms.topic: include --- ## Sprints (also known as iterations) -A sprint is a time period of usually two to three weeks that's used to group work items to be completed during that time period. Sprints are used in Scrum methods to support sprint planning, sprint burndown, and other Scrum processes. Sprints are defined via iteration paths. To learn more, see [About area and iteration paths (aka sprints)](../../organizations/settings/about-areas-iterations.md). \ No newline at end of file +A sprint is a time period of usually two to three weeks that's used to group work items to be completed during that time period. Sprints are used in Scrum methods to support sprint planning, sprint burndown, and other Scrum processes. Sprints are defined via iteration paths. For more information, see [About area and iteration paths (aka sprints)](../../organizations/settings/about-areas-iterations.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/taskboard.md b/docs/includes/glossary-terms/taskboard.md index 698fe972624..4959f5b761f 100644 --- a/docs/includes/glossary-terms/taskboard.md +++ b/docs/includes/glossary-terms/taskboard.md @@ -3,4 +3,4 @@ ms.topic: include --- ## Taskboard -A taskboard is an interactive board of work items that you can use to review and update tasks defined for the sprint backlog. The taskboard supports teams that use Scrum methodologies. To learn more, see [Update and monitor your taskboard](../../boards/sprints/task-board.md). \ No newline at end of file +A taskboard is an interactive board of work items that you can use to review and update tasks defined for the sprint backlog. The taskboard supports teams that use Scrum methodologies. For more information, see [Update and monitor your taskboard](../../boards/sprints/task-board.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/teams.md b/docs/includes/glossary-terms/teams.md index 6e253a606a9..26d9efd6b02 100644 --- a/docs/includes/glossary-terms/teams.md +++ b/docs/includes/glossary-terms/teams.md @@ -5,4 +5,4 @@ ms.topic: include ## Teams -A team corresponds to a selected set of project members. With teams, organizations can subcategorize work to better focus on all the work they track within a project. Each team gets access to a suite of Agile tools. Teams can use these tools to work autonomously and collaborate with other teams across the enterprise. Each team can configure and customize each tool to meet their work requirements. To learn more, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). \ No newline at end of file +A team corresponds to a selected set of project members. With teams, organizations can subcategorize work to better focus on all the work they track within a project. Each team gets access to a suite of Agile tools. Teams can use these tools to work autonomously and collaborate with other teams across the enterprise. Each team can configure and customize each tool to meet their work requirements. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). \ No newline at end of file diff --git a/docs/includes/glossary-terms/widgets.md b/docs/includes/glossary-terms/widgets.md index 0f2be22d14d..f3a0eab1286 100644 --- a/docs/includes/glossary-terms/widgets.md +++ b/docs/includes/glossary-terms/widgets.md @@ -3,4 +3,4 @@ ms.topic: include --- ## Widgets -Widgets display information and charts on dashboards. Many of them can be configured. Many widgets display information available from one or more data stores or charts created by the system. To learn more, see [Widget catalog](../../report/dashboards/widget-catalog.md). \ No newline at end of file +Widgets display information and charts on dashboards. Many of them can be configured. Many widgets display information available from one or more data stores or charts created by the system. For more information, see [Widget catalog](../../report/dashboards/widget-catalog.md). \ No newline at end of file diff --git a/docs/includes/image-differences.md b/docs/includes/image-differences.md index 283e6e6d8e6..5b38ad9b461 100644 --- a/docs/includes/image-differences.md +++ b/docs/includes/image-differences.md @@ -4,4 +4,4 @@ ms.topic: include > [!NOTE] -> The images you see from your web portal may differ from the images you see in this article. These differences result from updates made to Azure DevOps Services or your on-premises deployment. However, the basic functionality available to you remains the same unless explicitly mentioned. +> The images you see from your web portal may differ from the images you see in this article. These differences result from updates made to Azure DevOps. However, the basic functionality available to you remains the same unless explicitly mentioned. diff --git a/docs/includes/keyboard-shortcuts/code-shortcuts.md b/docs/includes/keyboard-shortcuts/code-shortcuts.md index 3dbeed89cd9..53c6bda04be 100644 --- a/docs/includes/keyboard-shortcuts/code-shortcuts.md +++ b/docs/includes/keyboard-shortcuts/code-shortcuts.md @@ -5,14 +5,10 @@ ms.date: 04/04/2022 -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" You can use the following keyboard shortcuts when you work on a page under **Repos**. To view the valid shortcuts, select **?** to access global and service-specific shortcuts. ::: moniker-end -::: moniker range="tfs-2018" -You can use the following keyboard shortcuts when you work on a page under **Code**. To view the valid shortcuts, select **?** to access global and service-specific shortcuts. -::: moniker-end - ::: moniker range=">= azure-devops-2020" ### Git repositories @@ -76,32 +72,3 @@ The following screenshot shows the lists of keyboard shortcuts as they appear in ::: moniker-end -::: moniker range="<= azure-devops-2019" - -#### Code shortcuts - -|Shortcut|Action| -|---|---| -|r|Select repository| -|e|Open explorer| -|h|Open history| -|b|Open branches (Git)| -|q|Open pull requests (Git)| -|c, p|Create pull request (Git)| - -#### Files shortcuts - -|Shortcut|Action| -|---|---| -|1|Open contents| -|2|Open history| -|t|Move focus to directory path| -|w|Select branch (Git)| -|y|Switch to commit (Git)| -|c, b|Create branch (Git)| - -The following screenshot shows the lists of keyboard shortcuts as they appear in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/code-shortcuts.png" alt-text="Screenshot that shows Azure DevOps 2019 Repos Code page and File Explorer keyboard shortcuts."::: - -::: moniker-end diff --git a/docs/includes/keyboard-shortcuts/global-shortcuts.md b/docs/includes/keyboard-shortcuts/global-shortcuts.md index 0d555cc9ac3..8da2684069d 100644 --- a/docs/includes/keyboard-shortcuts/global-shortcuts.md +++ b/docs/includes/keyboard-shortcuts/global-shortcuts.md @@ -27,24 +27,3 @@ The following screenshot shows the list of keyboard shortcuts as it appears in A ::: moniker-end -::: moniker range="<= azure-devops-2019" - -|Shortcut|Action| -|--------|------| -|?|Show keyboard shortcuts| -|p|Go to [Projects and teams](../../project/navigation/go-to-project-repo.md)| -|g, h|Go to [Projects home](../../project/navigation/go-to-project-repo.md)| -|g, w|Go to [Boards or Work](../../boards/get-started/what-is-azure-boards.md)| -|g, c|Go to [Repos or Code](../../repos/git/index.yml)| -|g, b|Go to [Pipelines or Build and release](../../pipelines/get-started/what-is-azure-pipelines.md)| -|g, t|Go to [Test Plans or Test](../../test/index.yml)| -|g, s|Go to [Project settings](../../organizations/settings/about-settings.md)| -|f, n|Move focus to next section| -|f, p|Move focus to previous section| -|/|Move focus to Search| - -The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/global-shortcuts.png" alt-text="Screenshot that shows Azure DevOps 2019 global keyboard shortcuts."::: - -::: moniker-end diff --git a/docs/includes/keyboard-shortcuts/queries-shortcuts.md b/docs/includes/keyboard-shortcuts/queries-shortcuts.md index 3ef6bd8353b..60ef3beeb94 100644 --- a/docs/includes/keyboard-shortcuts/queries-shortcuts.md +++ b/docs/includes/keyboard-shortcuts/queries-shortcuts.md @@ -24,19 +24,3 @@ The following screenshot shows the list of keyboard shortcuts as it appears in A ::: moniker-end -::: moniker range="<= azure-devops-2019" - -|Shortcut|Action| -|---|---| -|c, q|Add new query| -|r *or* Alt+r|Refresh query| -|Alt+q|Return to query| -|j *or* Alt+n|Move to next item| -|k *or* Alt+p|Move to previous item| -|Ctrl+Shift+f|Filter results| - -The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/queries-new-shortcut.png" alt-text="Screenshot that shows Azure DevOps 2019 Queries page keyboard shortcuts."::: - -::: moniker-end diff --git a/docs/includes/keyboard-shortcuts/wi-form-shortcuts.md b/docs/includes/keyboard-shortcuts/wi-form-shortcuts.md index 7ab57b37f8c..d087539a225 100644 --- a/docs/includes/keyboard-shortcuts/wi-form-shortcuts.md +++ b/docs/includes/keyboard-shortcuts/wi-form-shortcuts.md @@ -5,19 +5,12 @@ ms.date: 04/04/2022 -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" You can use the following keyboard shortcuts to [interact with a work item form](../../boards/work-items/work-item-form-controls.md). To view valid shortcuts, select **?** in the form. ::: moniker-end -::: moniker range="azure-devops-2019" - -> [!NOTE] -> Shortcuts for work item forms are available in the web portal for Azure DevOps Server 2019 and later versions. - -::: moniker-end - ::: moniker range=">= azure-devops-2020" |Shortcut|Action| @@ -37,23 +30,6 @@ The following screenshot shows the list of keyboard shortcuts as it appears in A ::: moniker-end -::: moniker range="azure-devops-2019" - -|Shortcut|Action| -|---|---| -|Alt+i|Assign work item to me| -|Ctrl+Shift+d|Go to discussion| -|Ctrl+s|Save changes| -|Shift+Alt+c|Copy work item title| -|Ctrl+Shift+,|Move to left tab (page)| -|Ctrl+Shift+.|Move to right tab (page)| - -The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/work-item-form.png" alt-text="Screenshot that shows Azure DevOps 2019 work item form keyboard shortcuts."::: - -::: moniker-end - ## Rich text editor ::: moniker range=">= azure-devops-2020" @@ -102,29 +78,3 @@ You can use the following keyboard shortcuts when you work in a web browser on o ::: moniker-end -::: moniker range="<= azure-devops-2019" - -The rich text formatting toolbar appears above each text box that can be formatted. It becomes active only when you select the text box. - -Here's an example of the toolbar in a text box: - -:::image type="content" source="../../boards/queries/media/rich-text-ui-team-services.png" alt-text="Screenshot that shows the Azure DevOps 2019 rich text editor toolbar."::: - -You can use the following keyboard shortcuts when you work in the editor in a web browser running on a Windows operating system. - -|Shortcut|Action| -|---|---| -|Ctrl+b|Bold| -|Ctrl+c|Copy text| -|Ctrl+i|Italics| -|Ctrl+k|Insert hyperlink| -|Ctrl+s|Save| -|Ctrl+u|Underline| -|Ctrl+v|Paste text| -|Ctrl+y|Redo| -|Ctrl+z|Undo| -|Ctrl+.|Bulleted list| -|Ctrl+/|Numbered list| -|Ctrl+Spacebar|Remove formatting| - -::: moniker-end diff --git a/docs/includes/keyboard-shortcuts/wiki-shortcuts.md b/docs/includes/keyboard-shortcuts/wiki-shortcuts.md deleted file mode 100644 index f52f81dcb40..00000000000 --- a/docs/includes/keyboard-shortcuts/wiki-shortcuts.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -ms.topic: include -ms.date: 04/04/2022 ---- - - - - -You can use the following keyboard shortcuts when you [manage or edit wiki pages](../../project/wiki/add-edit-wiki.md). To view valid shortcuts, select **?** on a **Wiki** page. - -::: moniker range="tfs-2018" - -> [!NOTE] -> Shortcuts you can use when you manage or edit a wiki page are available in the web portal for TFS 2018.2 and later versions. - -::: moniker-end - -::: moniker range=">= azure-devops-2020" - -### Manage wiki page shortcuts - -|Shortcut|Action| -|---|---| -|n|Add new page| -|e|Edit page| -|c|Create new sub-page| -|Ctrl+Down arrow|Move page down the order| -|Ctrl+Up arrow|Move page up the order| -|Ctrl+P|Print page| -|Ctrl+Shift+b|Create work item from selected text| - -The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/wiki-manage-cloud.png" alt-text="Screenshot that shows Azure DevOps 2020 manage Wiki page keyboard shortcuts."::: - -### Edit wiki page shortcuts - -|Shortcut|Action| -|---|---| -|Ctrl+b|Bold text| -|Ctrl+i|Italicize text| -|Ctrl+k|Insert hyperlink| -|Ctrl+c|Copy text| -|Ctrl+v|Paste copied text| -|Ctrl+Shift+f|Format tables| -|Ctrl+s|Save changes| -|Ctrl+Enter|Save and close| -|Esc|Close| - -The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/wiki-edit-cloud.png" alt-text="Screenshot that shows Azure DevOps 2020 edit Wiki page keyboard shortcuts."::: - -::: moniker-end - -::: moniker range="<= azure-devops-2019" - -### Manage wiki page shortcuts - -|Shortcut|Action| -|---|---| -|n|Add new page| -|e|Edit page| -|c|Create new sub-page| -|Ctrl+Down arrow|Move page down the order| -|Ctrl+Up arrow|Move page up the order| -|Ctrl+P|Print page| -|Ctrl+Shift+f|Filter page| - -The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/wiki-manage.png" alt-text="Screenshot that shows Azure DevOps 2019 manage Wiki page keyboard shortcuts."::: - -### Edit wiki page shortcuts - -|Shortcut|Action| -|---|---| -|Ctrl+b|Bold text| -|Ctrl+i|Italicize text| -|Ctrl+k|Insert hyperlink| -|Ctrl+c|Copy text| -|Ctrl+v|Paste copied text| -|Ctrl+Shift+f|Format tables| -|Ctrl+s|Save changes| -|Ctrl+Enter|Save and close| -|Esc|Close| - -The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/wiki-edit.png" alt-text="Screenshot that shows Azure DevOps 2019 edit Wiki page keyboard shortcuts."::: - -::: moniker-end diff --git a/docs/includes/keyboard-shortcuts/work-backlog-shortcuts.md b/docs/includes/keyboard-shortcuts/work-backlog-shortcuts.md index 269fe0ad439..7b5d56bcfe4 100644 --- a/docs/includes/keyboard-shortcuts/work-backlog-shortcuts.md +++ b/docs/includes/keyboard-shortcuts/work-backlog-shortcuts.md @@ -5,7 +5,7 @@ ms.date: 04/04/2022 -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" You can use the following keyboard shortcuts when you work on a **Boards** > **Backlogs** page. These shortcuts work when you are on a product backlog, portfolio backlog, or sprint backlog page. @@ -28,42 +28,3 @@ The following screenshot shows the list of keyboard shortcuts as it appears in A ::: moniker-end -::: moniker range="azure-devops-2019" - -|Shortcut|Action| -|---|---| -|Ctrl+Home|Move item to top| -|m, b|Move item to backlog| -|m, i|Move item to current iteration| -|m, n|Move item to next iteration| -|Insert|Add child| -|Ctrl+Shift+f|Filter results| - -The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/work-backlogs-shortcuts-S136.png" alt-text="Screenshot that shows Azure DevOps 2019 Boards Backlogs page keyboard shortcuts."::: - -::: moniker-end - -::: moniker range="tfs-2018" - -You can use the following keyboard shortcuts when you work on a **Work** > **Backlogs** page. These shortcuts work when you are on a product backlog, portfolio backlog, or sprint backlog page. - -### Backlogs - -|Shortcut|Action| -|---|---| -|Ctrl+Home|Move item to top| -|m, b|Move item to backlog| -|m, i|Move item to current iteration| -|m, n|Move item to next iteration| -|n|Open new item panel| -|Insert|Add child| -|Ctrl+Shift+f|Filter results| -|r|Toggle show/hide parents| - -The following screenshot shows the list of keyboard shortcuts as it appears in Team Foundation Server 2018: - -:::image type="content" source="../../media/keyboard-shortcuts/work-backlogs-shortcuts-S136.png" alt-text="Screenshot that shows TFS 2018 Work Backlogs page keyboard shortcuts."::: - -::: moniker-end diff --git a/docs/includes/keyboard-shortcuts/work-board-shortcuts.md b/docs/includes/keyboard-shortcuts/work-board-shortcuts.md index b2566bb6a88..a7a69fc8c90 100644 --- a/docs/includes/keyboard-shortcuts/work-board-shortcuts.md +++ b/docs/includes/keyboard-shortcuts/work-board-shortcuts.md @@ -5,7 +5,7 @@ ms.date: 04/04/2022 -You can use the following keyboard shortcuts when you work on a Kanban board on a **Boards** > **Boards** page or a **Work** > **Boards** page. +You can use the following keyboard shortcuts when you work on a board on a **Boards** > **Boards** page or a **Work** > **Boards** page. ::: moniker range=">= azure-devops-2020" @@ -33,36 +33,7 @@ You can use the following keyboard shortcuts when you work on a Kanban board on The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: -:::image type="content" source="../../media/keyboard-shortcuts/kanban-board-shortcuts-cloud-original.png" alt-text="Screenshot that shows Azure DevOps 2020 Kanban board shortcuts."::: +:::image type="content" source="../../media/keyboard-shortcuts/kanban-board-shortcuts-cloud-original.png" alt-text="Screenshot that shows Azure DevOps 2020 board shortcuts."::: ::: moniker-end -::: moniker range="< azure-devops-2020" - -|Shortcut|Action| -|---|---| -|n|Add new item| -|c|Add new child item| -|Home|Select first item| -|Enter|Open item| -|Ctrl+Shift+f|Filter results| -|Ctrl+Up arrow|Move item up| -|Ctrl+Down arrow|Move item down| -|Ctrl+Left arrow|Move item left| -|Ctrl+Right arrow|Move item right| -|Ctrl+Home|Move item to top of column| -|Ctrl+End|Move item to bottom of column| -|Ctrl+Shift+Up arrow|Move item to swimlane above| -|Ctrl+Shift+Down arrow|Move item to swimlane below| -|F2|Rename item| -|e|Toggle show/hide empty fields| -|o|Expand all swimlanes| -|u|Collapse all swimlanes| -|Shift+Page up|Select first/next swimlane above| -|Shift+Page down|Select last/next swimlane below| - -The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/kanban-board-shortcuts.png" alt-text="Screenshot that shows Azure DevOps 2019 Kanban board shortcuts."::: - -::: moniker-end diff --git a/docs/includes/keyboard-shortcuts/work-items-page-shortcuts.md b/docs/includes/keyboard-shortcuts/work-items-page-shortcuts.md index b6868432b2f..f3b398b0e2b 100644 --- a/docs/includes/keyboard-shortcuts/work-items-page-shortcuts.md +++ b/docs/includes/keyboard-shortcuts/work-items-page-shortcuts.md @@ -4,19 +4,12 @@ ms.topic: include -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" You can use these keyboard shortcuts on a **Boards** > **Work items** page or a **Work** > **Work items** page. ::: moniker-end -::: moniker range="azure-devops-2019" - -> [!NOTE] -> Shortcuts you can use in a work item are available in the web portal for Azure DevOps Server 2019 and later versions. - -::: moniker-end - ::: moniker range=">= azure-devops-2020" |Shortcut|Action| @@ -37,22 +30,3 @@ The following screenshot shows the lists of keyboard shortcuts as they appear in ::: moniker-end -::: moniker range="azure-devops-2019" - -|Shortcut|Action| -|---|---| -|l|Open [backlog](../../boards/backlogs/create-your-backlog.md)| -|b|Open [board](../../boards/boards/kanban-quickstart.md)| -|i|Open [current iteration](../../boards/sprints/assign-work-sprint.md)| -|t|Open [task board](../../boards/sprints/task-board.md)| -|q|Open [queries](../../boards/queries/using-queries.md)| -|z|Toggle full screen| -|Ctrl+Shift+f|Filter results| -|Ctrl+c|Copy to clipboard| -|Delete|Delete| - -The following screenshot shows the lists of keyboard shortcuts as they appear in Azure DevOps: - -:::image type="content" source="../../media/keyboard-shortcuts/work-items-shortcuts.png" alt-text="Screenshot that shows Azure DevOps 2019 work items page keyboard shortcuts."::: - -::: moniker-end diff --git a/docs/includes/link-work-item-builds-projects.md b/docs/includes/link-work-item-builds-projects.md deleted file mode 100644 index f33d1b8bfc7..00000000000 --- a/docs/includes/link-work-item-builds-projects.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -ms.service: azure-devops-boards -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 04/16/2021 ---- - - - - - -::: moniker range=">= azure-devops-2020" - -## Link work items to a build in same or other projects - -You can link work items to existing builds from the **Add link** dialog. These builds can be within your project or to other projects in your organization or collection. -::: moniker-end - -::: moniker range="azure-devops-2020" -> [!NOTE] -> This feature requires installation of Azure DevOps Server 2020.1 update. To learn more, see [Azure DevOps Server 2020 Update 1 RC1 Release Notes, Boards](/azure/devops/server/release-notes/azuredevops2020u1#customize-work-item-state-when-pull-request-is-merged). -::: moniker-end - - -::: moniker range=">= azure-devops-2020" - -1. From the **Links** tab of a work item, choose **Add link>Existing item**. - -1. From the **Add link** dialog, choose one of the build link types—**Build**, **Found in build**, **Integrated in build**— and specify the build number. - - If you don't know the build number—a combination of the pipeline and build name—you can search for it by choosing the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: icon. - - :::image type="content" source="../media/add-links/add-link-build.png" alt-text="Add link dialog with Build link type selected. "::: - -1. From the **Link builds** dialog, choose the parameters to filter your search of builds. - - If linking to a build in a different project, then first choose the **Project** whose build you want to link to. - - For example, you can specify a build number, select a build pipeline, a build result—such as, **All**, **succeeded**, **partially succeeded**, **failed**, or **canceled**. Or, with **All** selected for **Result**, choose **Find** to list the available builds to link to. - - :::image type="content" source="../media/add-links/find-builds-dialog-filled-out.png" alt-text="Find builds dialog with project selected and builds listed. "::: - -1. Choose the build from the list you want to link to and then choose **OK**. -2. From the **Add link** dialog, choose **OK** to complete the operation. - - :::image type="content" source="../media/add-links/add-link-build-filled-in.png" alt-text="Add link dialog with Build number filled in. "::: - -::: moniker-end - - -::: moniker range="azure-devops-2019" - -## Link work items to a build - -You can link work items to existing builds from the **Add link** dialog. - -1. From the **Links** tab of a work item, choose **Add link>Existing item**. - -1. From the **Add link** dialog, choose one of the build link types—**Build**, **Found in build**, **Integrated in build**— and specify the build number. - - If you don't know the build number—a combination of the pipeline and build name—you can search for it by choosing the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: icon. - - :::image type="content" source="../media/add-links/add-link-build.png" alt-text="Add link dialog with Build link type selected. "::: - -1. From the **Link builds** dialog, choose the parameters to filter your search of builds. - - For example, you can specify a build number, select a build pipeline, a build result—such as, **All**, **succeeded**, **partially succeeded**, **failed**, or **canceled**. Or, with **All** selected for **Result**, choose **Find** to list the available builds to link to. - - :::image type="content" source="../boards/backlogs/media/add-link/find-builds-dialog-2020-and-previous-versions.png" alt-text="Find builds dialog, link to a build within your project."::: - -1. Choose the build from the list you want to link to and then choose **OK**. -2. From the **Add link** dialog, choose **OK** to complete the operation. - - :::image type="content" source="../media/add-links/add-link-build-filled-in.png" alt-text="Add link dialog with Build number filled in. "::: - -::: moniker-end - - \ No newline at end of file diff --git a/docs/includes/manage-policies.md b/docs/includes/manage-policies.md index 62123656eec..0f79e081f90 100644 --- a/docs/includes/manage-policies.md +++ b/docs/includes/manage-policies.md @@ -4,7 +4,7 @@ ms.topic: include ## Manage a policy -Complete the following steps to change application connection, security, and user policies for your organization in Azure DevOps. +To change application connection, security, and user policies for your organization, do the following steps. 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). @@ -12,6 +12,6 @@ Complete the following steps to change application connection, security, and use ![Screenshot of Organization settings button, preview page.](../media/settings/open-admin-settings-vert.png) -3. Select **Policies**, and then next to your policy, move the toggle to *on* or *off*. +3. Select **Policies**, and then toggle your policy to **on** or **off** as needed. ![Screenshot of select policy, and then turn On or Off.](../media/change-policies-preview.png) diff --git a/docs/includes/note-cli-not-supported-on-premises.md b/docs/includes/note-cli-not-supported-on-premises.md deleted file mode 100644 index 682bce637b9..00000000000 --- a/docs/includes/note-cli-not-supported-on-premises.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -ms.subservice: azure-devops-reference -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 05/19/2022 ---- - -::: moniker range="< azure-devops" -Azure DevOps CLI commands are only available for Azure DevOps Services. Azure CLI isn't supported for Azure DevOps Server on-premises. -::: moniker-end - \ No newline at end of file diff --git a/docs/includes/note-cli-not-supported.md b/docs/includes/note-cli-not-supported.md index 47eca45db86..df4019ed249 100644 --- a/docs/includes/note-cli-not-supported.md +++ b/docs/includes/note-cli-not-supported.md @@ -7,6 +7,6 @@ ms.date: 07/09/2020 --- ::: moniker range="< azure-devops" -Azure DevOps CLI commands aren't supported for Azure DevOps Server on-premises. +Azure DevOps CLI commands aren't supported for Azure DevOps Server. ::: moniker-end \ No newline at end of file diff --git a/docs/includes/note-cli-supported-server.md b/docs/includes/note-cli-supported-server.md deleted file mode 100644 index 9a6057f8255..00000000000 --- a/docs/includes/note-cli-supported-server.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.service: azure-devops-boards -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 07/14/2020 ---- - -::: moniker range="azure-devops-2020" - -> [!NOTE] -> For Azure DevOps Server 2020, you can use the following command to set the default server instance, collection, and project. -> `az devops configure --defaults organization=https://ServerName/CollectionName project=ContosoWebApp` - -::: moniker-end \ No newline at end of file diff --git a/docs/includes/note-working-days-off.md b/docs/includes/note-working-days-off.md deleted file mode 100644 index 9ab88776d93..00000000000 --- a/docs/includes/note-working-days-off.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -ms.service: azure-devops-boards -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 06/01/2020 ---- - - -> [!NOTE] -> The **Show non-working days** shades those days set through the team's [**Working days** setting](../organizations/settings/set-working-days.md) as well as the team's days off set through the [**Capacity** page](../boards/sprints/set-capacity.md#set-team-capacity). \ No newline at end of file diff --git a/docs/includes/open-admin-organization-settings.md b/docs/includes/open-admin-organization-settings.md index 4fcd792b514..2107f11c3a8 100644 --- a/docs/includes/open-admin-organization-settings.md +++ b/docs/includes/open-admin-organization-settings.md @@ -2,7 +2,6 @@ ms.topic: include --- - ::: moniker range="azure-devops" @@ -22,8 +21,7 @@ Organization settings configure resources for all projects or the entire organiz ::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] - > ![Organization settings, Policy page, Security policies](../media/settings/open-organization-settings.png) - -2. From there, you can choose a page. Settings are organized based on the service they support. - - > [!div class="mx-imgBorder"] - > ![Organization settings, Projects](../media/settings/open-admin-settings-horizontal.png) - -::: moniker-end \ No newline at end of file diff --git a/docs/includes/organization-name-limitation.md b/docs/includes/organization-name-limitation.md index 971970ce6c3..09bd769864f 100644 --- a/docs/includes/organization-name-limitation.md +++ b/docs/includes/organization-name-limitation.md @@ -3,4 +3,12 @@ ms.topic: include --- > [!IMPORTANT] -> Currently, you can only use letters from the English alphabet in your organization name. Start organization names with a letter or number, followed by letters, numbers, or hyphens. Organization names must not contain more than 50 Unicode characters and must end with a letter or number. +> Adhere to the following guidelines when you create an organization name. +> - Use only letters from the English alphabet +> - Start your organization name with a letter or number +> - Use letters, numbers, or hyphens after the initial character +> - Ensure that your organization doesn't exceed 50 Unicode characters +> - End with a letter or number +> +> If you use any of the disallowed characters, you get the following error message: +> VS850015: The specified name is not allowed to be used: {Organization name}. diff --git a/docs/includes/prerequisites-add-users-org.md b/docs/includes/prerequisites-add-users-org.md index 55699ec7fed..e5de3d8db51 100644 --- a/docs/includes/prerequisites-add-users-org.md +++ b/docs/includes/prerequisites-add-users-org.md @@ -3,17 +3,17 @@ ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/10/2022 +ms.date: 01/13/2025 --- ::: moniker range="azure-devops" - -* You must have an organization and project. If you don't have a project yet, [create one](../organizations/projects/create-project.md). -* To add users to or remove users from a team, you must be added as a [team administrator](../organizations/settings/add-team-administrator.md), or be a member of one of the administrative groups. -* To add users to or remove users from a project, you must be a member of the [**Project Administrators** group](../organizations/security/change-project-level-permissions.md). -* When the organization is connected to Azure Active Directory, the [Allow team and project administrators to invite new users](../organizations/security/restrict-invitations.md) policy must be enabled for team administrators or members of the Project Administrators group to add new users. -* To add users or manage users for an organization, you must be a member of the [**Project Collection Administrators** group](../organizations/security/change-organization-collection-level-permissions.md). Organization owners are automatically members of this group. -::: moniker-end \ No newline at end of file +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of a [project](../organizations/projects/create-project.md). | +| **Permissions** | - To add users to or remove users from a team: [Team Administrator](../organizations/settings/add-team-administrator.md) or member of one of the administrative groups.
      - To add users to or remove users from a project: Member of the [**Project Administrators** group](../organizations/security/change-project-level-permissions.md).
      - To add users or manage users for an organization: Member of the [**Project Collection Administrators** group](../organizations/security/change-organization-collection-level-permissions.md). Organization owners are automatically members of this group. | +| **Policies** | If your organization is connected to Microsoft Entra ID: Enable the [Allow team and project administrators to invite new users](../organizations/security/restrict-invitations.md) policy for team administrators or members of the Project Administrators group for adding new users. | + +::: moniker-end diff --git a/docs/includes/prerequisites-add-users-server.md b/docs/includes/prerequisites-add-users-server.md index ff8a2915d60..f5e0636a333 100644 --- a/docs/includes/prerequisites-add-users-server.md +++ b/docs/includes/prerequisites-add-users-server.md @@ -3,13 +3,14 @@ ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/10/2022 +ms.date: 01/13/2025 --- ::: moniker range="< azure-devops" -* If you don't have a project yet, [create one](../organizations/projects/create-project.md) -* To add users to or remove users from a team, you must be added as a [team administrator](../organizations/settings/add-team-administrator.md), or be a member of one of the administrative groups. -* To add users to or remove users from a project,you must be a member of the [**Project Administrators** group](../organizations/security/change-project-level-permissions.md). -* To add users or manage users for a server, you must be a member of the [Azure DevOps Administrators group](/azure/devops/server/admin/add-administrator). +| Category | Requirements | +|--------------|-------------| +| **Project membership**| [Project member](../organizations/projects/create-project.md). | +| **Permissions**| - To add users to or remove users from a team: [Team Administrator](../organizations/settings/add-team-administrator.md) or member of one of the administrative groups.
      - To add users to or remove users from a project: Member of the [**Project Administrators** group](../organizations/security/change-project-level-permissions.md).
      - To add users or manage users for a server: Member of the [Azure DevOps Administrators group](/azure/devops/server/admin/add-administrator).| + ::: moniker-end diff --git a/docs/includes/prerequisites-contributor-only.md b/docs/includes/prerequisites-contributor-only.md new file mode 100644 index 00000000000..c865db42d30 --- /dev/null +++ b/docs/includes/prerequisites-contributor-only.md @@ -0,0 +1,8 @@ +--- +ms.topic: include +ms.date: 01/27/2025 +--- + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| At least [**Contributor** role](../organizations/security/permissions.md).| diff --git a/docs/includes/prerequisites-organization-owner-only.md b/docs/includes/prerequisites-organization-owner-only.md new file mode 100644 index 00000000000..c89b28171c7 --- /dev/null +++ b/docs/includes/prerequisites-organization-owner-only.md @@ -0,0 +1,8 @@ +--- +ms.topic: include +ms.date: 01/13/2025 +--- + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| [Owner of your organization](../organizations/accounts/change-organization-ownership.md).| diff --git a/docs/includes/prerequisites-pca-and-basic.md b/docs/includes/prerequisites-pca-and-basic.md new file mode 100644 index 00000000000..90ee7ba3309 --- /dev/null +++ b/docs/includes/prerequisites-pca-and-basic.md @@ -0,0 +1,9 @@ +--- +ms.topic: include +ms.date: 01/13/2025 +--- + +| Category | Requirements | +|--------------|-------------| +|**Permissions** | Member of the [Project Collection Administrators group](../organizations/security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +|**Access levels**| At least **Basic** access.| diff --git a/docs/includes/prerequisites-pca-only.md b/docs/includes/prerequisites-pca-only.md new file mode 100644 index 00000000000..9381ecf6465 --- /dev/null +++ b/docs/includes/prerequisites-pca-only.md @@ -0,0 +1,8 @@ +--- +ms.topic: include +ms.date: 01/13/2025 +--- + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../organizations/security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| diff --git a/docs/includes/prerequisites-project-administrator-and-basic.md b/docs/includes/prerequisites-project-administrator-and-basic.md new file mode 100644 index 00000000000..aab87c35b52 --- /dev/null +++ b/docs/includes/prerequisites-project-administrator-and-basic.md @@ -0,0 +1,12 @@ +--- +ms.author: chcomley +author: chcomley +ms.service: azure-devops +ms.topic: include +ms.date: 02/06/2025 +--- + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | Member of the **Project Administrators** security group. | +|**Access levels**| At least **Basic** access.| diff --git a/docs/includes/prerequisites-project-administrator-only.md b/docs/includes/prerequisites-project-administrator-only.md new file mode 100644 index 00000000000..cdaecdca034 --- /dev/null +++ b/docs/includes/prerequisites-project-administrator-only.md @@ -0,0 +1,11 @@ +--- +ms.author: chcomley +author: chcomley +ms.service: azure-devops +ms.topic: include +ms.date: 02/05/2025 +--- + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | Member of the **Project Administrators** security group. | diff --git a/docs/includes/prerequisites-project-collection-valid-users-group.md b/docs/includes/prerequisites-project-collection-valid-users-group.md new file mode 100644 index 00000000000..9d5b5937507 --- /dev/null +++ b/docs/includes/prerequisites-project-collection-valid-users-group.md @@ -0,0 +1,13 @@ +--- +ms.topic: include +--- + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the **Project Collection Valid Users** group. Project members are automatically members of this group.| + +::: moniker range="azure-devops" +> [!NOTE] +> Users added to the **Project-scoped users** group can't access **Organization settings** other than the **Overview** section if the [**Limit user visibility and collaboration to specific projects** preview feature is enabled](../user-guide/manage-organization-collection.md#project-scoped-user-group) for the organization. + +::: moniker-end diff --git a/docs/includes/prerequisites-project-member-only.md b/docs/includes/prerequisites-project-member-only.md new file mode 100644 index 00000000000..32f99d0aeb9 --- /dev/null +++ b/docs/includes/prerequisites-project-member-only.md @@ -0,0 +1,11 @@ +--- +ms.author: chcomley +author: chcomley +ms.service: azure-devops +ms.topic: include +ms.date: 02/05/2025 +--- + +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../organizations/security/add-users-team-project.md). | diff --git a/docs/includes/process-editor-tool.md b/docs/includes/process-editor-tool.md index 99b184616a4..fa2b918caeb 100644 --- a/docs/includes/process-editor-tool.md +++ b/docs/includes/process-editor-tool.md @@ -3,9 +3,9 @@ title: Process Editor Tool ms.service: azure-devops-boards ms.author: chcomley author: chcomley -ms.date: 01/13/2023 +ms.date: 10/08/2024 --- -- **Visual Studio 2019**: [Process Template Editor](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.msdevlabs-pte). +- **Visual Studio 2019 & 2022:** As of now, there's no specific Process Template Editor extension available. But, you can still customize process templates using other tools such as any text editor or XML editor. You can also use the Azure DevOps web portal for certain customizations, especially for inherited processes. - **Visual Studio 2017**: [TFS Process Template Editor](https://marketplace.visualstudio.com/items?itemName=KarthikBalasubramanianMSFT.TFSProcessTemplateEditor). You can also use this version of the Process Editor to modify the old-style work item forms. You can't use it to edit forms associated with the [new web forms](/previous-versions/azure/devops/reference/process/new-work-item-experience). -- **Visual Studio 2015**: [TFS Power Tools](https://marketplace.visualstudio.com/items?itemName=TFSPowerToolsTeam.MicrosoftVisualStudioTeamFoundationServer2015Power). \ No newline at end of file +- **Visual Studio 2015**: [TFS Power Tools](https://marketplace.visualstudio.com/items?itemName=TFSPowerToolsTeam.MicrosoftVisualStudioTeamFoundationServer2015Power). diff --git a/docs/includes/process-editor.md b/docs/includes/process-editor.md index 68f77ea0557..fd5729dc25c 100644 --- a/docs/includes/process-editor.md +++ b/docs/includes/process-editor.md @@ -6,19 +6,10 @@ author: chcomley ms.date: 01/13/2023 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!TIP] > With **witadmin**, you can [import and export definition files](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md). Other tools you can use include the Process Editor (requires that you have installed a version of Visual Studio). [Install the Process Template editor from the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.msdevlabs-pte). ::: moniker-end - -::: moniker range="tfs-2018" - -> [!TIP] -> With **witadmin**, you can [import and export definition files](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md). Other tools you can use include the Process Editor (requires that you have installed a version of Visual Studio). [Install the TFS Process Template editor from the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KarthikBalasubramanianMSFT.TFSProcessTemplateEditor). You can use this version of the Process Editor to modify the old-style work item forms. You can't use it to edit forms associated with the [new web forms](/previous-versions/azure/devops/reference/process/new-work-item-experience). -> ->Or, you can use the [TFS Team Project Manager](https://github.com/jelledruyts/TfsTeamProjectManager), an open-source client available from GitHub. - -::: moniker-end diff --git a/docs/includes/project-scoped-users-important-note.md b/docs/includes/project-scoped-users-important-note.md deleted file mode 100644 index d37094a088a..00000000000 --- a/docs/includes/project-scoped-users-important-note.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -ms.subservice: azure-devops-security -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 03/23/2023 ---- - -> [!IMPORTANT] -> - The limited visibility features described in this section apply only to interactions through the web portal. With the REST APIs or `azure devops` CLI commands, project members can access the restricted data. -> - Guest users who are members in the limited group with default access in Azure AD, can't search for users with the people picker. When the preview feature's turned *off* or when guest users aren't members of the limited group, guest users can search all Azure AD users, as expected. diff --git a/docs/includes/project-scoped-users-warning.md b/docs/includes/project-scoped-users-warning.md index 70a6bab9876..89fb9ecb654 100644 --- a/docs/includes/project-scoped-users-warning.md +++ b/docs/includes/project-scoped-users-warning.md @@ -3,8 +3,11 @@ ms.subservice: azure-devops ms.author: chcomley author: chcomley ms.topic: include -ms.date: 03/23/2023 +ms.date: 02/04/2025 --- -> [!WARNING] -> When the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization, project-scoped users are unable to search for users who were added to the organization through Azure Active Directory group membership, rather than through an explicit user invitation. This is an unexpected behavior and a resolution is being worked on. To self-resolve this issue, disable the **Limit user visibility and collaboration to specific projects** preview feature for the organization. +> [!WARNING] +> Consider the following limitations when using this preview feature: +> - The limited visibility features described in this section apply only to interactions through the web portal. With the REST APIs or `azure devops` CLI commands, project members can access the restricted data. +> - Users in the limited group can only select users who are explicitly added to Azure DevOps and not users who have access through Microsoft Entra group membership. +> - Guest users who are members in the limited group with default access in Microsoft Entra ID, can't search for users with the people picker. diff --git a/docs/includes/qa-azure-subscriptions-for-billing.md b/docs/includes/qa-azure-subscriptions-for-billing.md index 8f07a314ed5..7025322b159 100644 --- a/docs/includes/qa-azure-subscriptions-for-billing.md +++ b/docs/includes/qa-azure-subscriptions-for-billing.md @@ -6,7 +6,7 @@ A: You can use an [Azure subscription](https://azure.microsoft.com/pricing/purch that's not the following: * An [Azure Free Trial](https://azure.microsoft.com/offers/ms-azr-0044p/) -* A [free Azure AD subscription](/microsoft-365/compliance/use-your-free-azure-ad-subscription-in-office-365) +* A [free Microsoft Entra subscription](/microsoft-365/compliance/use-your-free-azure-ad-subscription-in-office-365) If you have one of these subscriptions, set up a separate [Pay-As-You-Go Azure subscription](https://azure.microsoft.com/offers/ms-azr-0003p/) @@ -37,4 +37,4 @@ instead. 1. Sign in to [Azure Account Center (**Account** > **subscriptions**)](https://portal.azure.com). 2. Select your Azure subscription. - 3. Remove your spending limit **indefinitely**. \ No newline at end of file + 3. Remove your spending limit **indefinitely**. diff --git a/docs/includes/qa-choose-msa-azuread-account.md b/docs/includes/qa-choose-msa-azuread-account.md index 3bdc0fb5125..68fa2ba8bd5 100644 --- a/docs/includes/qa-choose-msa-azuread-account.md +++ b/docs/includes/qa-choose-msa-azuread-account.md @@ -1,4 +1,4 @@ -### Q: Why do I have to choose between a "work or school account" and my "personal account"? +### Why do I have to choose between a "work or school account" and my "personal account"? -A: This happens when you sign in with an email address (for example, jamalhartnett@fabrikam.com) that's shared by your personal Microsoft account and by your work account or school account. Although both identities use the same sign-in address, they're still separate identities. The two identities have different profiles, security settings, and permissions. +You have to choose between a "work or school account" and your "personal account" when you sign in with an email address (for example, jamalhartnett@fabrikam.com) shared by both accounts. Although both identities use the same sign-in address, they're separate and have different profiles, security settings, and permissions. diff --git a/docs/includes/qa-choose-msa-azuread-account2.md b/docs/includes/qa-choose-msa-azuread-account2.md index a4699931066..0314b5c2f80 100644 --- a/docs/includes/qa-choose-msa-azuread-account2.md +++ b/docs/includes/qa-choose-msa-azuread-account2.md @@ -1,6 +1,3 @@ -* Select **Work or school account** if you used this identity to create your organization, or if you previously signed in with this identity. Your identity is authenticated by your organization's directory in Azure AD, which controls access to your organization. - -* Select **Personal account** if you used your Microsoft account with Azure DevOps. Your identity is authenticated by the global directory for Microsoft accounts. - - +* Select **Work or school account** if you used this identity to create your organization or previously signed in with it. Your organization's directory in Microsoft Entra ID authenticates your identity and controls access to your organization. +* Select **Personal account** if you used your Microsoft account with Azure DevOps. The global directory for Microsoft accounts authenticates your identity. diff --git a/docs/includes/qa-get-vsts-support.md b/docs/includes/qa-get-vsts-support.md index 30f4e138d5d..54ba4678bc0 100644 --- a/docs/includes/qa-get-vsts-support.md +++ b/docs/includes/qa-get-vsts-support.md @@ -1,10 +1,5 @@ -### Q: How do I get help or support for Azure DevOps? +#### Q: How do I get help or support for Azure DevOps? -A: You have the following options for support: - -* Report a problem with Azure DevOps on [Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). -* Provide a suggestion on [Developer Community](https://developercommunity.visualstudio.com/content/idea/post.html?space=21) -* Get advice on [Stack Overflow](https://stackoverflow.com/questions/tagged/vs-team-services) -* View the archives of the [Azure DevOps forum](https://social.msdn.microsoft.com/Forums/home?forum=TFService) on MSDN +A: See [Get support and provide feedback](../user-guide/provide-feedback.md). diff --git a/docs/includes/qa-why-cant-sign-in-msa-azuread-account.md b/docs/includes/qa-why-cant-sign-in-msa-azuread-account.md index 90972e19b52..9892258fc7e 100644 --- a/docs/includes/qa-why-cant-sign-in-msa-azuread-account.md +++ b/docs/includes/qa-why-cant-sign-in-msa-azuread-account.md @@ -1,7 +1,6 @@ -### Q: Why can't I sign in after I select "personal Microsoft account" or "work or school account"? - -A: When your sign-in address is shared by your personal Microsoft account and by your work account or school account, but your selected identity doesn't have access, you can't sign in. Although both identities use the same sign-in address, they're separate: they have different profiles, security settings, and permissions. +### Why can't I sign in after I select "personal Microsoft account" or "work or school account"? +If your sign-in address is shared by both your personal Microsoft account and your work or school account, but the selected identity doesn't have access, you can't sign in. Although both identities use the same sign-in address, they're separate and have different profiles, security settings, and permissions. Sign out completely from Azure DevOps by completing the following steps. Closing your browser might not sign you out completely. Sign in again and select your other identity: 1. Close all browsers, including browsers that aren't running Azure DevOps. @@ -10,9 +9,9 @@ Sign out completely from Azure DevOps by completing the following steps. Closing 3. Go to this URL: `https://aka.ms/vssignout`. - You see a message that says, "Sign out in progress." After you sign out, you're redirected to the Azure DevOps @dev.azure.microsoft.com webpage. + A message displays, "Sign out in progress." After you sign out, you're redirected to the Azure DevOps @dev.azure.microsoft.com webpage. > [!TIP] - > If the sign-out page takes more than a minute to sign you out, close the browser and continue. + > If the sign-out page takes longer than a minute, close the browser and try again. 4. Sign in to Azure DevOps again. Select your other identity. diff --git a/docs/includes/restrict-modification-fields-for-not.md b/docs/includes/restrict-modification-fields-for-not.md index ec1afdbea81..1a38248ca2a 100644 --- a/docs/includes/restrict-modification-fields-for-not.md +++ b/docs/includes/restrict-modification-fields-for-not.md @@ -20,7 +20,7 @@ Using one of the following two conditions, you can make select fields required f > [!TIP] -> To avoid rule evaluation issues that may arise, specify Azure DevOps security groups and not Azure Active Directory or Active Directory security groups. To learn more, see [Default rules and the rule engine](../organizations/settings/work/rule-reference.md). +> To avoid rule evaluation issues that may arise, specify Azure DevOps security groups and not Microsoft Entra ID or Active Directory security groups. For more information, see [Default rules and the rule engine](../organizations/settings/work/rule-reference.md). For example, you can make the Title or the State field Read-only for select users or groups. @@ -28,6 +28,6 @@ For example, the Priority field, for the User Story work item type, becomes read :::image type="content" source="../organizations/settings/work/media/rules/rule-priority-field-read-only-for-not.png" alt-text="Custom rule, Current user is not a member of a group, make Priority field read-only"::: -To learn more, see [Add a rule to a work item type (Inheritance process)](../organizations/settings/work/custom-rules.md). +For more information, see [Add a rule to a work item type (Inheritance process)](../organizations/settings/work/custom-rules.md). -::: moniker-end \ No newline at end of file +::: moniker-end diff --git a/docs/includes/set-work-item-state-pull-request.md b/docs/includes/set-work-item-state-pull-request.md deleted file mode 100644 index e2a03453c9f..00000000000 --- a/docs/includes/set-work-item-state-pull-request.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -ms.service: azure-devops-boards -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 04/16/2021 ---- - - - -::: moniker range=">= azure-devops-2020" - -When you create a pull request, you can set the *state* value of the linked work items in the description. Follow the syntax: ``` {state value}: #ID ```. -When you merge the pull request, the system reads the description and updates the work item state. In the following example, we set work items #300 and #301 to Resolved, and #323 and #324 to Closed. - -:::image type="content" source="/azure/devops/organizations/notifications/media/pr-set-state-of-work-items.png" alt-text="Screenshot of setting work item state within a PR."::: - -::: moniker-end - -::: moniker range="azure-devops-2020" -> [!NOTE] -> This feature requires installation of Azure DevOps Server 2020.1 update. To learn more, see [Azure DevOps Server 2020 Update 1 RC1 Release Notes, Boards](/azure/devops/server/release-notes/azuredevops2020u1#customize-work-item-state-when-pull-request-is-merged). -::: moniker-end \ No newline at end of file diff --git a/docs/includes/sign-in-github-account.md b/docs/includes/sign-in-github-account.md index 65e68d97f1a..be96045450e 100644 --- a/docs/includes/sign-in-github-account.md +++ b/docs/includes/sign-in-github-account.md @@ -4,41 +4,27 @@ ms.topic: include ## Sign up with a GitHub account -> [!IMPORTANT] -> If your GitHub email address is associated with an Azure AD-backed organization in Azure DevOps, you can't sign in with your GitHub account, rather you must sign in with your Azure AD account. +> [!NOTE] +> If your GitHub email address is associated with an organization in Azure DevOps [connected to Microsoft Entra ID](../organizations/accounts/connect-organization-to-azure-ad.md), you can't sign in with your GitHub account. Sign in with your Microsoft Entra account instead. -1. Select the sign-up link for [Azure DevOps](https://azure.microsoft.com/services/devops/), **Start free with GitHub**. If you're already part of an Azure DevOps organization, select **Sign in to Azure DevOps**. +1. If you don't have one, [create a GitHub account](https://github.com/join). +2. Go to [Azure DevOps](https://azure.microsoft.com/services/devops/) and select **Get started with Azure**. +3. Select **Sign in with GitHub**. +4. Enter your account credentials and go through the sign-up process. You're asked to **Authorize Microsoft-corp**. - ![Sign up for Azure DevOps](../media/azure-devops-start-free.png) + Azure DevOps creates an organization. Sign in to your organization at any time `https://dev.azure.com/{Your_Organization}`. + Azure DevOps turns on the *External guest access* policy by default. + + ![Screenshot of the Invite GitHub users policy.](../media/invite-github-users-policy.png) -2. Select **Sign in with GitHub**. +An organization gets created based on the account you used to sign in. Sign in to your organization at any time, (`https://dev.azure.com/{Your_Organization}`). - ![Select Sign in with GitHub](../media/sign-in-github.png) - - If you have an account in session already, select **Use another account**. You're taken to GitHub sign-in where you can enter your GitHub user name or email address. - -3. Enter your GitHub account credentials, and then select **Sign in**. - - ![Enter GitHub credentials](../media/enter-github-credentials.png) - -4. Select **Authorize Microsoft corporation**. - - ![Authorize Microsoft](../media/authorize-Microsoft-corp.png) - -5. To get started with Azure DevOps, select **Continue**. - - ![Choose Continue to sign up for Azure DevOps](../media/sign-up-azure-devops.png) - -An organization is created based on the account you used to sign in. Sign in to your organization at any time, (`https://dev.azure.com/{yourorganization}`). - -You can rename and delete your organization, or change the organization location. To learn more, see [Manage organizations](../organizations/accounts/organization-management.md). +You can rename and delete your organization, or change the organization location. For more information, see [Manage organizations](../organizations/accounts/organization-management.md). ### Enable GitHub invitations -Creating a new Azure DevOps organization with your GitHub username turns on the Invite GitHub users policy by default. For existing organizations, your administrator can turn on this capability via **Organization settings** > **Policies** tab. - -Once the setting is changed, sign out of Azure DevOps, and then from a fresh browser session, sign back in to the organization `dev.azure.com/{organizationName}` or `organizationName.visualstudio.com` with your GitHub credentials. You're now recognized as a GitHub user and the GitHub invitation experience is available to you. +Creating a new Azure DevOps organization with your GitHub username turns on the External guest access policy by default. For existing organizations, your administrator can turn on this capability via **Organization settings** > **Policies** tab. -![Invite GitHub users policy ](../media/invite-github-users-policy.png) +Once the setting gets changed, sign out of Azure DevOps, and then from a fresh browser session, sign back in to the organization `dev.azure.com/{Organization_Name}` or `organizationName.visualstudio.com` with your GitHub credentials. You're recognized as a GitHub user and the GitHub invitation experience is available to you. -For more information about GitHub authentication, see [FAQs](../organizations/security/faq-github-authentication.yml). \ No newline at end of file +For more information about GitHub authentication, see [Connect to GitHub/FAQs](../boards/github/connect-to-github.md#faqs). diff --git a/docs/includes/sign-up-msft-account.md b/docs/includes/sign-up-msft-account.md index 51a4d1489aa..c3bbae6d33f 100644 --- a/docs/includes/sign-up-msft-account.md +++ b/docs/includes/sign-up-msft-account.md @@ -4,27 +4,13 @@ ms.topic: include ## Sign up with a personal Microsoft account -1. Select the sign-up link for [Azure DevOps](https://azure.microsoft.com/services/devops/). +1. If you don't have one, [create a Microsoft account](https://azure.microsoft.com/services/devops/). +2. Go to [Azure DevOps](https://azure.microsoft.com/services/devops/) and select **Get started with Azure**. +3. Select either **Try Azure for free** or **Pay as you go**. +4. Enter your Microsoft account credentials and go through the sign-up process. -2. Enter your email address, phone number, or Skype ID for your Microsoft account. If you're a Visual Studio subscriber and you get Azure DevOps as a benefit, use the Microsoft account associated with your subscription. Select **Next**. + Azure DevOps creates an organization: + - If you signed up with a newly created Microsoft account, Azure DevOps creates a project named after your account. + - If you signed up with an existing Microsoft account, [create a project](../organizations/projects/create-project.md) next. - ![Sign in with your Microsoft account](../media/sign-in-with-microsoft-account.png) - - If you don't have a Microsoft account, choose **Create one**. To learn more, see [create a Microsoft account](https://support.microsoft.com/help/4026324/microsoft-account-how-to-create). - -3. Enter your password and select **Sign in**. - - ![Enter your password and sign in](../media/enter-password-sign-in.png) - -4. To get started with Azure DevOps, select **Continue**. - - ![Choose Continue to sign up for Azure DevOps](../media/sign-up-azure-devops.png) - -An organization is created based on the account you used to sign in. Sign in to your organization at any time, (`https://dev.azure.com/{yourorganization}`). - -You can rename and delete your organization, or change the organization location. To learn more, see the following articles: - -- [Rename an organization](../organizations/accounts/rename-organization.md) -- [Change the location of your organization](../organizations/accounts/change-organization-location.md) - -If you signed in with an existing Microsoft account, your next step is to [Create a project](../organizations/projects/create-project.md). If you signed in with a newly created Microsoft account, then your project is automatically created and named after your account name. To learn more about managing projects, see [Manage projects](../organizations/projects/about-projects.md). \ No newline at end of file + Sign in to your organization at any time: `https://dev.azure.com/{Your_Organization}`. diff --git a/docs/includes/tip-find-setting-permission.md b/docs/includes/tip-find-setting-permission.md deleted file mode 100644 index ab2faa3370d..00000000000 --- a/docs/includes/tip-find-setting-permission.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.subservice: azure-devops-settings -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 04/15/2021 ---- - - -::: moniker range="azure-devops" - -> [!TIP] -> To quickly find a permission or setting defined for a project or organization, use the [Organization search setting feature](../organizations/settings/search-settings.md). - -::: moniker-end \ No newline at end of file diff --git a/docs/includes/use-microsoft-entra-reduce-pats.md b/docs/includes/use-microsoft-entra-reduce-pats.md new file mode 100644 index 00000000000..b3e19f8b418 --- /dev/null +++ b/docs/includes/use-microsoft-entra-reduce-pats.md @@ -0,0 +1,7 @@ +--- +ms.topic: include +--- + +> [!IMPORTANT] +> We recommend using [Microsoft Entra tokens](../integrate/get-started/authentication/entra.md). For more information about our efforts to reduce PAT usage, see [our blog](https://devblogs.microsoft.com/devops/reducing-pat-usage-across-azure-devops/). +> Review our [authentication guidance](../integrate/get-started/authentication/authentication-guidance.md) to choose the appropriate authentication mechanism for your needs. diff --git a/docs/includes/use-service-principals-tip.md b/docs/includes/use-service-principals-tip.md new file mode 100644 index 00000000000..d0c5dba1cb2 --- /dev/null +++ b/docs/includes/use-service-principals-tip.md @@ -0,0 +1,6 @@ +--- +ms.topic: include +--- + +> [!TIP] +> The examples in this article use service principals in lieu of basic authentication as a more secure method for authentication. For more information, see [Use service principals & managed identities in Azure DevOps](../integrate/get-started/authentication/service-principal-managed-identity.md). diff --git a/docs/includes/version-eq-2018.md b/docs/includes/version-eq-2018.md deleted file mode 100644 index 1158b96481e..00000000000 --- a/docs/includes/version-eq-2018.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -ms.topic: include ---- - -**TFS 2018** \ No newline at end of file diff --git a/docs/includes/version-gt-eq-2018.md b/docs/includes/version-gt-eq-2018.md deleted file mode 100644 index 42a8d0bd612..00000000000 --- a/docs/includes/version-gt-eq-2018.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -ms.topic: include -ms.author: rabououn -author: ramiMSFT -ms.topic: include -ms.date: 06/02/2022 ---- - -**Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018** \ No newline at end of file diff --git a/docs/includes/version-lt-azure-devops-plus-xml-process.md b/docs/includes/version-lt-azure-devops-plus-xml-process.md index a2ca56bc239..acf66489229 100644 --- a/docs/includes/version-lt-azure-devops-plus-xml-process.md +++ b/docs/includes/version-lt-azure-devops-plus-xml-process.md @@ -3,7 +3,7 @@ ms.topic: include --- -**Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018** +**Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019** > [!IMPORTANT] > This article applies to project customization for On-premises XML process models. For an overview of process models, see [Customize your work tracking experience](../reference/customize-work.md). \ No newline at end of file diff --git a/docs/includes/version-lt-azure-devops.md b/docs/includes/version-lt-azure-devops.md index 142a1b340e8..34251a4caf2 100644 --- a/docs/includes/version-lt-azure-devops.md +++ b/docs/includes/version-lt-azure-devops.md @@ -5,4 +5,4 @@ ms.topic: include ms.date: 08/08/2022 --- -**Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018** \ No newline at end of file +**Azure DevOps Server 2022 - Azure DevOps Server 2019** \ No newline at end of file diff --git a/docs/includes/version-lt-eq-2020.md b/docs/includes/version-lt-eq-2020.md index e91ef6bfc34..fca15c09f7e 100644 --- a/docs/includes/version-lt-eq-2020.md +++ b/docs/includes/version-lt-eq-2020.md @@ -2,4 +2,4 @@ ms.topic: include --- -**Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018** \ No newline at end of file +**Azure DevOps Server 2020 | Azure DevOps Server 2019** \ No newline at end of file diff --git a/docs/includes/version-lt-eq-azure-devops-plus-witadmin.md b/docs/includes/version-lt-eq-azure-devops-plus-witadmin.md index 3c4e5662d97..54c9cd6c6b2 100644 --- a/docs/includes/version-lt-eq-azure-devops-plus-witadmin.md +++ b/docs/includes/version-lt-eq-azure-devops-plus-witadmin.md @@ -2,7 +2,7 @@ ms.topic: include --- -**Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018** +**Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019** > [!IMPORTANT] > For the On-premises XML process model, you can use **witadmin** to list, import, export, and modify a process for a project. For the Inherited and Hosted XML process models, you can only use **witadmin** to list and export process information. For an overview of process models and what is supported, see [Customize your work tracking experience](../reference/customize-work.md). \ No newline at end of file diff --git a/docs/includes/version-lt-eq-azure-devops.md b/docs/includes/version-lt-eq-azure-devops.md index b9cd6e0cb43..a78e6fa752f 100644 --- a/docs/includes/version-lt-eq-azure-devops.md +++ b/docs/includes/version-lt-eq-azure-devops.md @@ -6,4 +6,4 @@ ms.date: 08/08/2022 --- -**Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018** \ No newline at end of file +**Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019** \ No newline at end of file diff --git a/docs/includes/version-selector-minimize.md b/docs/includes/version-selector-minimize.md deleted file mode 100644 index 2713bcc99af..00000000000 --- a/docs/includes/version-selector-minimize.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 06/16/2021 ---- - - -> [!IMPORTANT] -> :::row::: -> :::column span="1"::: -> :::image type="content" source="../media/version-selector-minimize.png" alt-text="Select a version from Azure DevOps Content Version selector."::: -> :::column-end::: -> :::column span="2"::: -> To view the content available for your platform, make sure that you select the correct version of this article from the version selector which is located above the table of contents. Feature support differs depending on whether you are working from Azure DevOps Services or an on-premises version of Azure DevOps Server. -> To learn which on-premises version you are using, see [Look up your Azure DevOps platform and version](../user-guide/lookup-platform-version.md) -> :::column-end::: -> :::row-end::: \ No newline at end of file diff --git a/docs/includes/version-selector.md b/docs/includes/version-selector.md index b8fd8dd7165..fc9b3bc43e0 100644 --- a/docs/includes/version-selector.md +++ b/docs/includes/version-selector.md @@ -2,15 +2,12 @@ ms.topic: include --- - -> [!IMPORTANT] +> [!IMPORTANT] > :::row::: > :::column span="1"::: -> :::image type="content" source="../media/version-selector.png" alt-text="Select a version from Azure DevOps Content Version selector." +> :::image type="content" source="../media/version-selector.png" alt-text="Select a version from Azure DevOps Content Version selector."::: > :::column-end::: > :::column span="2"::: -> To view the content available for your platform, make sure that you select the correct version of this article from the version selector which is located above the table of contents. Feature support differs depending on whether you are working from Azure DevOps Services or an on-premises version of Azure DevOps Server, renamed from Team Foundation Server (TFS). -> To learn which on-premises version you are using, see [Look up your Azure DevOps platform and version](../user-guide/lookup-platform-version.md) +> Select the version of this article that corresponds to your platform and version. The version selector is above the table of contents. [Look up your Azure DevOps platform and version](../user-guide/lookup-platform-version.md). > :::column-end::: > :::row-end::: - diff --git a/docs/includes/version-vs-gt-2013.md b/docs/includes/version-vs-gt-2013.md deleted file mode 100644 index 00017115648..00000000000 --- a/docs/includes/version-vs-gt-2013.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -ms.topic: include -ms.date: 02/09/2022 ---- - -**Visual Studio 2022 | Visual Studio 2019 | Visual Studio 2017 | Visual Studio 2015 | Visual Studio 2013** \ No newline at end of file diff --git a/docs/includes/witadmin-run-tool-example.md b/docs/includes/witadmin-run-tool-example.md index 1f01e6df40f..f960e1a8f31 100644 --- a/docs/includes/witadmin-run-tool-example.md +++ b/docs/includes/witadmin-run-tool-example.md @@ -2,7 +2,7 @@ ms.topic: include --- - + 1. Open a Command Prompt window according to the instructions provided in [witAdmin: Customize and manage objects for tracking work](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md#run-witadmin-tool). For example: ```%programfiles(x86)%\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer diff --git a/docs/includes/witadmin-run-tool.md b/docs/includes/witadmin-run-tool.md index 73657cd20dc..f4498984af4 100644 --- a/docs/includes/witadmin-run-tool.md +++ b/docs/includes/witadmin-run-tool.md @@ -5,38 +5,37 @@ ms.date: 12/01/2022 --- - + -## How to run the `witadmin` command-line tool +## Run the `witadmin` command-line tool To run the `witadmin` command-line tool, open a Command Prompt window where Visual Studio is installed. The `witadmin` command-line tool installs with any version of Visual Studio. You can access this tool by installing the free version of [Visual Studio Community or Visual Studio Team Explorer](https://visualstudio.microsoft.com/downloads/). ::: moniker range="azure-devops" > [!NOTE] -> If you are connecting to Azure DevOps Services, we recommend that you use the latest version of Visual Studio or Visual Studio Community. +> To connect to Azure DevOps Services, we recommend that you use the latest version of Visual Studio or Visual Studio Community. ::: moniker-end ::: moniker range="< azure-devops" > [!NOTE] -> If you are connecting to an on-premises server, we recommend that you use the same or later version of Visual Studio as your Azure DevOps Server. For example, if you connect to Azure DevOps Server 2019, then connect to your project from a version of Visual Studio 2019. +> To connect to an on-premises server, we recommend that you use the same or later version of Visual Studio as your Azure DevOps Server. For example, if you connect to Azure DevOps Server 2019, then connect to your project from a version of Visual Studio 2019. ::: moniker-end **For Visual Studio 2022** `%programfiles(x86)%\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer` -or `Professional` or `Enterprise` in place of `Community`, depending on the version you've installed. +or `Professional` or `Enterprise` in place of `Community`, depending on the version you installed. **For Visual Studio 2019** `%programfiles(x86)%\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer` -or `Professional` or `Enterprise` in place of `Community`, depending on the version you've installed. +or `Professional` or `Enterprise` in place of `Community`, depending on the version you installed. **For Visual Studio 2017** `%programfiles(x86)%\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer` -or `TeamExplorer` or `Professional` in place of `Enterprise`, depending on the version you've installed. +or `TeamExplorer` or `Professional` in place of `Enterprise`, depending on the version you installed. On a 32-bit edition of Windows, replace **%programfiles(x86)%** with **%programfiles%**. You can [install Visual Studio Community (which provides access to Team Explorer) or Visual Studio Team Explorer 2017](https://visualstudio.microsoft.com/downloads/download-visual-studio-vs) for free. - diff --git a/docs/index.yml b/docs/index.yml index 2d47b02cab6..756980d9a24 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -6,12 +6,12 @@ brand: azure metadata: title: Azure DevOps documentation - description: Collaborate on software development through source control, work tracking, and continuous integration and delivery, both on-premises and in the cloud! + description: Collaborate on software development with source control, work tracking, and continuous integration and delivery, both on-premises and in the cloud! ms.topic: hub-page ms.subservice: azure-devops-projects - author: KathrynEE - ms.author: kaelli - ms.date: 09/17/2022 + ms.author: chcomley + author: chcomley + ms.date: 03/11/2025 # highlightedContent section (optional) # Maximum of 8 items @@ -47,9 +47,9 @@ highlightedContent: itemType: how-to-guide url: ./organizations/projects/connect-to-projects.md # Card - - title: Authenticate access with personal access tokens + - title: Secure access to Azure DevOps itemType: how-to-guide - url: ./organizations/accounts/use-personal-access-tokens-to-authenticate.md + url: ./integrate/get-started/authentication/authentication-guidance.md # productDirectory section (optional) productDirectory: # title: Azure DevOps Products @@ -68,7 +68,7 @@ productDirectory: - url: ./boards/get-started/plan-track-work.md text: Plan & track work - url: ./boards/backlogs/office/bulk-add-modify-work-items-excel.md - text: Bulk add or modify work items + text: Add or modify work items in bulk - url: ./boards/index.yml text: See more > # Card @@ -143,12 +143,8 @@ productDirectory: text: Setup and upgrade requirements - url: /azure/devops/server/install/get-started text: Install - - url: /azure/devops/server/upgrade/get-started - text: Upgrade - - url: ./migrate/migrate-from-tfs.md + - url: /azure/devops/migrate text: Migrate - - url: /azure/devops/server/server/ - text: See more > tools: title: Build & deploy your apps items: @@ -160,10 +156,10 @@ tools: url: ./pipelines/ecosystems/dotnet-core.md - title: C/C++ with GCC imageSrc: /media/logos/logo_Cplusplus.svg - url: ./pipelines/apps/c-cpp/gcc.md + url: /previous-versions/azure/devops/pipelines/apps/c-cpp/gcc?view=tfs-2017&preserve-view=true - title: C/C++ with VC++ imageSrc: /media/logos/logo_visual-studio.svg - url: ./pipelines/apps/windows/cpp.md + url: /previous-versions/azure/devops/pipelines/apps/windows/cpp?view=tfs-2017&preserve-view=true - title: Docker imageSrc: ./pipelines/media/index/logo_dockercontainer.svg url: /azure/devops/pipelines/tasks/reference/docker-v2 @@ -193,11 +189,11 @@ tools: additionalContent: # Supports up to 3 sections sections: - - title: Configure & customize resources - items: - # Card - - title: Settings & Usage - links: + - title: Configure & customize resources + items: + # Card + - title: Settings & usage + links: - text: About settings url: ./organizations/settings/about-settings.md - text: Manage your project @@ -218,17 +214,13 @@ additionalContent: url: ./organizations/audit/azure-devops-auditing.md - text: See more > url: ./organizations/index.yml - # Card - - title: Security, Permissions, & Access - links: + # Card + - title: Security, permissions, & access + links: - text: About permissions, access, and security groups url: ./organizations/security/about-permissions.md - text: About access levels url: ./organizations/security/access-levels.md - - text: Use personal access tokens - url: ./organizations/accounts/use-personal-access-tokens-to-authenticate.md - - text: Security quick reference index - url: ./organizations/security/quick-reference-index-security.md - text: Billing overview url: ./organizations/billing/overview.md - text: Add or remove users or groups @@ -236,12 +228,12 @@ additionalContent: - text: Change project-level permissions url: ./organizations/accounts/organization-management.md - text: Change project collection-level permissions - url: ./organizations/accounts/organization-management.md + url: ./organizations/accounts/organization-management.md - text: See more > url: ./organizations/security/index.yml - # Card - - title: Cross-service, Azure, & GitHub Integration - links: + # Card + - title: Cross-service, Azure, & GitHub integration + links: - text: Cross-service integration overview url: ./cross-service/cross-service-overview.md - text: End-to-end traceability @@ -256,9 +248,9 @@ additionalContent: url: ./boards/github/connect-to-github.md?toc=/azure/devops/cross-service/toc.json - text: See more > url: ./cross-service/index.yml - # Card - - title: Azure Boards Customization - links: + # Card + - title: Azure Boards customization + links: - text: Configure & customize Azure Boards url: ./boards/configure-customize.md?toc=/azure/devops/reference/toc.json - text: Compare processes @@ -275,10 +267,10 @@ additionalContent: url: ./reference/process-templates/index.md - text: See more > url: ./reference/index.yml - - title: Additional services - items: + - title: Other services + items: # Card - - title: Analytics & Reporting + - title: Analytics & reporting links: - text: Dashboards, charts, reports, & widgets url: ./report/dashboards/overview.md @@ -293,12 +285,12 @@ additionalContent: - text: See more > url: ./report/index.yml # Card - - title: Wikis, Search, & Navigation + - title: Wiki, search, & navigation links: - text: Create a wiki for your project url: ./project/wiki/wiki-create-repo.md - text: Syntax guidance for Markdown usage in Wiki - url: ./project/wiki/wiki-markdown-guidance.md + url: ./project/wiki/markdown-guidance.md - text: Search url: ./project/search/get-started-search.md - text: Web portal navigation @@ -308,12 +300,12 @@ additionalContent: # Card - title: Marketplace & Extensibility links: + - text: Authentication overview + url: ./integrate/get-started/authentication/authentication-guidance.md?toc=/azure/devops/marketplace-extensibility/toc.json - text: Discover extensions url: ./extend/overview.md?toc=/azure/devops/marketplace-extensibility/toc.json - text: Develop extensions url: ./extend/get-started/node.md?toc=/azure/devops/marketplace-extensibility/toc.json - - text: Integrate applications - url: ./integrate/index.md?toc=/azure/devops/marketplace-extensibility/toc.json - text: Service hooks url: ./service-hooks/overview.md?toc=/azure/devops/marketplace-extensibility/toc.json - text: See more > @@ -328,9 +320,7 @@ additionalContent: - text: Git command reference url: ./repos/git/command-prompt.md - text: Team Foundation version control commands - url: ./repos/tfvc/use-team-foundation-version-control-commands.md - - text: Test case management (TCM) commands - url: ./test/test-case-managment-reference.md + url: ./repos/tfvc/use-team-foundation-version-control-commands.md - text: Azure DevOps Services Demo Generator url: ./demo-gen/index.md?toc=/azure/devops/dev-resources/toc.json - text: REST APIs @@ -341,4 +331,4 @@ additionalContent: url: ./dev-resources/index.yml # footer (optional) - footer: "[Blogs](https://devblogs.microsoft.com/devops/) - [Twitter](https://twitter.com/AzureDevOps) - [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops) - [Issue Reporting](https://azure.microsoft.com/support/devops/) - [Developer Community](https://azure.microsoft.com/support/devops/) - [Service Status](https://status.dev.azure.com/)" \ No newline at end of file + footer: "[Blogs](https://devblogs.microsoft.com/devops/) - [Twitter](https://twitter.com/AzureDevOps) - [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops) - [Issue Reporting](https://azure.microsoft.com/support/devops/) - [Developer Community](https://azure.microsoft.com/support/devops/) - [Service Status](https://status.dev.azure.com/)" diff --git a/docs/integrate/api/_scripts/2.0/boards.js b/docs/integrate/api/_scripts/2.0/boards.js index f7196a3c8a1..72864389a88 100644 --- a/docs/integrate/api/_scripts/2.0/boards.js +++ b/docs/integrate/api/_scripts/2.0/boards.js @@ -1,13 +1,14 @@ var apiwriter = require('apiwriter'); -/* When running with OnPrem, ensure that Basic Auth is set up in the virtual directory itself. - * Set these environment variables when running writer tool for boards.js - * set cfgApisUrl=http://localhost:8080/tfs/DefaultCollection/fooScrum/AgileTeam/_apis - * set cfgUserName= - * set cfgPassword= - * set cfgApiVersion=1.0 - * set cfgScript=boards.js - * set cfgScriptPath = ../../VSContent/integrate/api/_scripts/2.0 +/* When running with OnPrem, ensure that Service Principal authentication is set up. + * Set these environment variables when running writer tool for plans.js + * set cfgApisUrl=http://localhost:8080/tfs/DefaultCollection/agile/_apis + * set cfgServicePrincipalId= + * set cfgServicePrincipalKey= + * set cfgTenantId= + * set cfgApiVersion=3.0-preview.1 + * set cfgScript=plans.js + * set cfgScriptPath=../../Content.VS/vscom/integrate/api/_scripts/3.0 */ exports.getContext = function () { diff --git a/docs/integrate/api/_scripts/2.0/endpoints.js b/docs/integrate/api/_scripts/2.0/endpoints.js index d8f502ee2c5..d2f5c642cd3 100644 --- a/docs/integrate/api/_scripts/2.0/endpoints.js +++ b/docs/integrate/api/_scripts/2.0/endpoints.js @@ -29,10 +29,11 @@ exports.submitRequests = function() { "type": "chef", "url": "https://fabrikam-chef:9090", "authorization": { - "scheme": "UsernamePassword", + "scheme": "ServicePrincipal", "parameters": { - "username": "someUsername", - "password": "somePassword" + "serviceprincipalid": "your-service-principal-id", + "serviceprincipalkey": "your-service-principal-key", + "tenantid": "your-tenant-id" } }, //"data": {} @@ -48,10 +49,11 @@ exports.submitRequests = function() { "type": "chef", "url": "https://fabrikam-chef-updated:9090", "authorization": { - "scheme": "UsernamePassword", + "scheme": "ServicePrincipal", "parameters": { - "username": "someUsername", - "password": "somePassword" + "serviceprincipalid": "your-service-principal-id", + "serviceprincipalkey": "your-service-principal-key", + "tenantid": "your-tenant-id" } } }); diff --git a/docs/integrate/api/_scripts/3.0/plans.js b/docs/integrate/api/_scripts/3.0/plans.js index 0842d8084c9..9b79f0d8fb2 100644 --- a/docs/integrate/api/_scripts/3.0/plans.js +++ b/docs/integrate/api/_scripts/3.0/plans.js @@ -1,13 +1,14 @@ var apiwriter = require('apiwriter'); -/* When running with OnPrem, ensure that Basic Auth is set up in the virtual directory itself. +/* When running with OnPrem, ensure that Service Principal authentication is set up. * Set these environment variables when running writer tool for plans.js * set cfgApisUrl=http://localhost:8080/tfs/DefaultCollection/agile/_apis - * set cfgUserName= - * set cfgPassword= + * set cfgServicePrincipalId= + * set cfgServicePrincipalKey= + * set cfgTenantId= * set cfgApiVersion=3.0-preview.1 * set cfgScript=plans.js - * set cfgScriptPath =../../Content.VS/vscom/integrate/api/_scripts/3.0 + * set cfgScriptPath=../../Content.VS/vscom/integrate/api/_scripts/3.0 */ exports.getContext = function () { diff --git a/docs/integrate/concepts/cross-origin-resource-sharing.md b/docs/integrate/concepts/cross-origin-resource-sharing.md deleted file mode 100644 index d0d6d64de38..00000000000 --- a/docs/integrate/concepts/cross-origin-resource-sharing.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Cross-origin resource sharing (CORS) with Azure DevOps REST APIs -description: Learn about using CORS with Azure DevOps REST APIs -ms.assetid: d7e3c119-5678-40e6-9c11-55a57c171278 -ms.subservice: azure-devops-ecosystem -ms.topic: conceptual -monikerRange: 'azure-devops' -ms.author: chcomley -author: chcomley -ms.date: 08/04/2016 ---- - -# Cross-origin resource sharing (CORS) - -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -Azure DevOps supports cross-origin resource sharing (CORS). CORS enables JavaScript code served from a domain other than `dev.azure.com/*` to make Ajax requests to Azure DevOps Services REST APIs. For this to work, each request must provide credentials (personal access tokens and OAuth access tokens are both supported options). Example: - -```js - $( document ).ready(function() { - $.ajax({ - url: 'https://dev.azure.com/fabrikam/_apis/projects?api-version=1.0', - dataType: 'json', - headers: { - 'Authorization': 'Basic ' + btoa("" + ":" + myPatToken) - } - }).done(function( results ) { - console.log( results.value[0].id + " " + results.value[0].name ); - }); - }); -``` - -(replace `myPatToken` with a personal access token) diff --git a/docs/integrate/concepts/dotnet-client-libraries.md b/docs/integrate/concepts/dotnet-client-libraries.md index 58c7a2b5968..ed5d0d84638 100644 --- a/docs/integrate/concepts/dotnet-client-libraries.md +++ b/docs/integrate/concepts/dotnet-client-libraries.md @@ -1,5 +1,5 @@ --- -title: .NET Client Libraries +title: .NET client libraries description: Easily integrate with Azure DevOps from apps and services on Windows. ms.assetid: 474cdb4f-9a5e-49fb-84b2-9c540ebcf98b ms.subservice: azure-devops-ecosystem @@ -8,90 +8,88 @@ ms.topic: conceptual monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 07/28/2022 +ms.date: 03/20/2025 --- # .NET client libraries [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Client libraries are available for .NET developers who build Windows apps and services that integrate with Azure DevOps. Client libraries integrate with work item tracking, version control, build, and other services. These packages replace the traditional TFS Client OM installer and make it easy to acquire and redistribute the libraries needed by your app or service. +Client libraries are available for .NET developers who build Windows apps and services that integrate with Azure DevOps. Client libraries integrate with work item tracking, version control, build, and other services. These packages make it easy to acquire and redistribute the libraries needed by your app or service. > [!TIP] -> For more information, see the [Azure DevOps REST API Reference](/rest/api/azure/devops). +> Find the corresponding .NET client class and API method, using [.NET Client Library Samples](../get-started/client-libraries/samples.md) and [Azure DevOps API Reference](/rest/api/azure/devops). ## Dependency diagram ![Dependency diagram shows the relationship between Services.Client, Services.InteractiveClient, and TeamFoundationServer.Client.](../concepts/media/dotnet-client-libraries-dependancy-diagram.jpg) -## Features +## Features of .NET Client Libraries -* Downloadable from [nuget.org](https://www.nuget.org/) and easily importable into your Visual Studio projects -* Libraries are licensed for redistribution in your apps and services ([view the license](https://go.microsoft.com/fwlink/?LinkId=329770)) -* Access both traditional client object model APIs and [new REST APIs](../rest-api-overview.md) +The .NET client libraries for Azure DevOps offer several key features that make it easy to integrate with services in Azure DevOps from your Windows applications and services: -> [!NOTE] -> REST-based clients only work with Azure DevOps and TFS 2015 or later. -> For more information about extending and integrating with Azure DevOps using the client libraries, -> see [Extending Team Foundation](/previous-versions/visualstudio/visual-studio-2013/bb130146(v=vs.120)). +- **Downloadable from NuGet.org**: Easily import the libraries into your Visual Studio projects by downloading them from [NuGet.org](https://www.nuget.org/). +- **Licensed for redistribution**: The libraries are licensed for redistribution in your apps and services. You can [view the license](https://go.microsoft.com/fwlink/?LinkId=329770) for more details. +- **Access to APIs**: Gain access to both traditional client object model APIs and [REST APIs](/rest/api/azure/devops/?view-azure-devops-rest-7.2&preserve-view=true) to interact with Azure DevOps programmatically. -## Package and Azure DevOps Server version-mapping table +## Package and Azure DevOps version-mapping table -|Package version|Azure DevOps Server version| -|---------------|-----------| -|16.170.0| `versions >= Azure DevOps Server 2020`| +The following table maps the package versions of the .NET client libraries to the corresponding versions of Azure DevOps Server. Use this table to determine which package version corresponds to your Azure DevOps version. + +|Package version|Azure DevOps version| +|---------------|---------------------| +|16.205.x| `versions >= Azure DevOps Server 2022` | +|16.170.x| `versions >= Azure DevOps Server 2020`| |16.153.x| `versions >= Azure DevOps Server 2019 Update 1`| |16.143.x| `versions >= Azure DevOps Server 2019`| -|15.131.x| `versions >= TFS 2018 Update 1`| -|15.112.x| `versions >= TFS 2017 Update 1`| -|14.102.x| `versions >= TFS 2015 Update 3`| -|14.95.x| `versions >= TFS 2015 Update 2`| -|14.89.x| `versions >= TFS 2015 Update 1`| -|14.83.x| `versions >= TFS 2015`| For the latest preview versions, see the [NuGet packages gallery](https://www.nuget.org/packages?q=azure+devops+.net). ## REST packages +The following table lists the .NET client libraries available for accessing various services via public REST APIs. These packages can be downloaded from NuGet.org and provide the necessary binaries to integrate with Azure DevOps. + |Packages and description |Binaries | -|---------|--------------| -|[Microsoft.VisualStudio.Services.Client​](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Client/)
      Provides access to shared platform services via public REST APIs, like organization, profile, identity, security, and more. |`Microsoft.VisualStudio.Services.WebApi.dll`, `Microsoft.VisualStudio.Services.Common.dll`, `Microsoft.TeamFoundation.Common.dll` | -|[Microsoft.TeamFoundationServer.Client](https://www.nuget.org/packages/Microsoft.TeamFoundationServer.Client/)​
      Provides access to version control, work item tracking, build, and more via public REST APIs. | `Microsoft.TeamFoundation.Build2.WebApi.dll`, `Microsoft.TeamFoundation.Core.WebApi.dll`, `Microsoft.TeamFoundation.WorkItemTracking.Process.WebApi.dll`, `Microsoft.TeamFoundation.SourceControl.WebApi.dll`, `Microsoft.TeamFoundation.TestManagement.WebApi.dll`, and so on. | -|[Microsoft.VisualStudio.Services.InteractiveClient](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.InteractiveClient/)​
      Supports applications that require interactive sign-in by a user. | `Microsoft.VisualStudio.Services.Client.Interactive.dll` | -|[Microsoft.VisualStudio.Services.Release.Client​](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Release.Client/)
      Provides access to the Release Service via public REST APIs. |`Microsoft.VisualStudio.Services.ReleaseManagement.WebApi.dll` | -|[Microsoft.TeamFoundation.DistributedTask.Common.Contracts​](https://www.nuget.org/packages/Microsoft.TeamFoundation.DistributedTask.Common.Contracts)
      Provides the models used to access the Distributed Task Service via public REST APIs. |`Microsoft.TeamFoundation.DistributedTask.Common.Contracts.dll` | -|[Microsoft.TeamFoundation.DistributedTask.WebApi](https://www.nuget.org/packages/Microsoft.TeamFoundation.DistributedTask.WebApi)
      Provides access to the Distributed Task Service via public REST APIs. | `Microsoft.TeamFoundation.DistributedTask.WebApi.dll` | -|[Microsoft.VisualStudio.Services.ServiceHooks.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.ServiceHooks.WebApi)​
      Provides access to the Service Hooks Service via public REST APIs. |`Microsoft.VisualStudio.Services.ServiceHooks.WebApi.dll` | -|[Microsoft.VisualStudio.Services.Gallery.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Gallery.WebApi)
      Provides access to the Gallery Service via public REST APIs. |`Microsoft.VisualStudio.Services.Gallery.WebApi.dll` | -|[Microsoft.VisualStudio.Services.Notifications.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Notifications.WebApi)​
      Provides access to the Notifications Service via public REST APIs. |`Microsoft.VisualStudio.Services.Notifications.WebApi.dll` | -|[Microsoft.VisualStudio.Services.ExtensionManagement.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.ExtensionManagement.WebApi)
      Provides access to the Extension Management Service via public REST APIs. |`Microsoft.VisualStudio.Services.ExtensionManagement.WebApi.dll` | -|[Microsoft.VisualStudio.Services.MemberEntitlementManagement.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.MemberEntitlementManagement.WebApi)
      Provides access to the Member Entitlement Management Service via public REST APIs. |`Microsoft.VisualStudio.Services.MemberEntitlementManagement.WebApi.dll` | -|[Microsoft.VisualStudio.Services.ServiceEndpoints.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.ServiceEndpoints.WebApi)
      Provides access to the Service Endpoints via public REST APIs. |`Microsoft.VisualStudio.Services.ServiceEndpoints.WebApi.dll` | -|[Microsoft.VisualStudio.Services.Search.Client](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Search.Client)
      Provides access to the Search Service via public REST APIs. |`Microsoft.VisualStudio.Services.Search.Shared.WebApi.dll`, `Microsoft.VisualStudio.Services.Search.WebApi.dll` | -|[Microsoft.TeamFoundation.PublishTestResults​](https://www.nuget.org/packages/Microsoft.TeamFoundation.PublishTestResults)
      This task can be used to Publish test results and upload test attachments on Azure DevOps. The following results formats are supported with this package: 1. JUnit - publish tests from Junit projects, 2. NUnit- publish tests from Nunit projects, 3. VSTest- publish tests from Visual Studio projects, 4. Xunit- publish tests from Xunit projects |`Microsoft.TeamFoundation.TestClient.PublishTestResults.dll` | -|[Microsoft.VisualStudio.Services.Audit.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Audit.WebApi)​
      Provides access to the Audit Service via public REST APIs.|`Microsoft.VisualStudio.Services.Audit.WebApi.dll` | -| [Microsoft.Azure.Pipelines.Policy.Client](https://www.nuget.org/packages/Microsoft.Azure.Pipelines.Policy.Client/19.207.0-preview)​
      Provides access to the pipeline approvals, checks, and authorization via public REST APIs.|`Microsoft.Azure.Pipelines.Policy.Client.dll` | +|--------------------------|----------| +|[Microsoft.VisualStudio.Services.Client](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Client/)
      Provides access to shared platform services via public REST APIs, like organization, profile, identity, security, and more. |`Microsoft.VisualStudio.Services.WebApi.dll`, `Microsoft.VisualStudio.Services.Common.dll`, `Microsoft.TeamFoundation.Common.dll` | +|[Microsoft.TeamFoundationServer.Client](https://www.nuget.org/packages/Microsoft.TeamFoundationServer.Client/)
      Provides access to version control, work item tracking, build, and more via public REST APIs. | `Microsoft.TeamFoundation.Build2.WebApi.dll`, `Microsoft.TeamFoundation.Core.WebApi.dll`, `Microsoft.TeamFoundation.WorkItemTracking.Process.WebApi.dll`, `Microsoft.TeamFoundation.SourceControl.WebApi.dll`, `Microsoft.TeamFoundation.TestManagement.WebApi.dll`, and so on. | +|[Microsoft.VisualStudio.Services.InteractiveClient](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.InteractiveClient/)
      Supports applications that require interactive sign-in by a user. | `Microsoft.VisualStudio.Services.Client.Interactive.dll` | +|[Microsoft.VisualStudio.Services.Release.Client](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Release.Client/)
      Provides access to the Release Service via public REST APIs. |`Microsoft.VisualStudio.Services.ReleaseManagement.WebApi.dll` | +|[Microsoft.TeamFoundation.DistributedTask.Common.Contracts](https://www.nuget.org/packages/Microsoft.TeamFoundation.DistributedTask.Common.Contracts)
      Provides the models used to access the Distributed Task Service via public REST APIs. |`Microsoft.TeamFoundation.DistributedTask.Common.Contracts.dll` | +|[Microsoft.TeamFoundation.DistributedTask.WebApi](https://www.nuget.org/packages/Microsoft.TeamFoundation.DistributedTask.WebApi)
      Provides access to the Distributed Task Service via public REST APIs. | `Microsoft.TeamFoundation.DistributedTask.WebApi.dll` | +|[Microsoft.VisualStudio.Services.ServiceHooks.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.ServiceHooks.WebApi/)
      Provides access to the Service Hooks Service via public REST APIs. |`Microsoft.VisualStudio.Services.ServiceHooks.WebApi.dll` | +|[Microsoft.VisualStudio.Services.Gallery.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Gallery.WebApi/)
      Provides access to the Gallery Service via public REST APIs. |`Microsoft.VisualStudio.Services.Gallery.WebApi.dll` | +|[Microsoft.VisualStudio.Services.Notifications.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Notifications.WebApi/)
      Provides access to the Notifications Service via public REST APIs. |`Microsoft.VisualStudio.Services.Notifications.WebApi.dll` | +|[Microsoft.VisualStudio.Services.ExtensionManagement.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.ExtensionManagement.WebApi/)
      Provides access to the Extension Management Service via public REST APIs. |`Microsoft.VisualStudio.Services.ExtensionManagement.WebApi.dll` | +|[Microsoft.VisualStudio.Services.MemberEntitlementManagement.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.MemberEntitlementManagement.WebApi/)
      Provides access to the Member Entitlement Management Service via public REST APIs. |`Microsoft.VisualStudio.Services.MemberEntitlementManagement.WebApi.dll` | +|[Microsoft.VisualStudio.Services.ServiceEndpoints.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.ServiceEndpoints.WebApi/)
      Provides access to the Service Endpoints via public REST APIs. |`Microsoft.VisualStudio.Services.ServiceEndpoints.WebApi.dll` | +|[Microsoft.VisualStudio.Services.Search.Client](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Search.Client/)
      Provides access to the Search Service via public REST APIs. |`Microsoft.VisualStudio.Services.Search.Shared.WebApi.dll`, `Microsoft.VisualStudio.Services.Search.WebApi.dll` | +|[Microsoft.TeamFoundation.PublishTestResults](https://www.nuget.org/packages/Microsoft.TeamFoundation.PublishTestResults/)
      This task can be used to publish test results and upload test attachments on Azure DevOps. The following results formats are supported with this package: 1. JUnit - publish tests from JUnit projects, 2. NUnit - publish tests from NUnit projects, 3. VSTest - publish tests from Visual Studio projects, 4. Xunit - publish tests from Xunit projects. |`Microsoft.TeamFoundation.TestClient.PublishTestResults.dll` | +|[Microsoft.VisualStudio.Services.Audit.WebApi](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Audit.WebApi/)
      Provides access to the Audit Service via public REST APIs. |`Microsoft.VisualStudio.Services.Audit.WebApi.dll` | +|[Microsoft.Azure.Pipelines.Policy.Client](https://www.nuget.org/packages/Microsoft.Azure.Pipelines.Policy.Client/)
      Provides access to the pipeline approvals, checks, and authorization via public REST APIs. |`Microsoft.Azure.Pipelines.Policy.Client.dll` | > [!TIP] -> If you have an existing Windows application or service that uses the TFS Client Object Model, use `Microsoft.TeamFoundationServer.ExtendedClient`. +> If you have an existing Windows application or service that uses the TFS Client Object Model, use `Microsoft.TeamFoundationServer.ExtendedClient`. This package provides access to the older SOAP-based APIs, which are necessary for certain functionalities not available in the newer REST APIs. However, this package doesn't support .NET Standard and is intended for use only when the REST APIs don't offer the required functionality. ## Soap package -|**Package and description** |**Binaries** | -|---------|------------| -|[Microsoft.TeamFoundationServer.ExtendedClient​](https://www.nuget.org/packages/Microsoft.TeamFoundationServer.ExtendedClient/)
      Work with and manage version control, work items, and build, and other resources from your client application. This package doesn't support Net Standard Client OM. Only use this package when our REST APIs don't offer the functionality you need (for example, creating workspaces in TFVC) |`Microsoft.TeamFoundation.Build.Client.dll`, `Microsoft.TeamFoundation.DeleteTeamProject.dll`, `Microsoft.TeamFoundation.Diff.dll`, `Microsoft.TeamFoundation.Git.Client.dll`, `Microsoft.TeamFoundation.SharePointReporting.Integration.dll`, and so on. | +The following table lists the .NET client libraries available for accessing various services via SOAP APIs. These packages can be downloaded from NuGet.org and provide the necessary binaries to integrate with Azure DevOps. Only use these packages when the REST APIs don't offer the functionality you need, for example, creating workspaces in TFVC. + +|**Package and description** |**Binaries** | +|-----------------------------|--------------| +|[Microsoft.TeamFoundationServer.ExtendedClient](https://www.nuget.org/packages/Microsoft.TeamFoundationServer.ExtendedClient/)
      Work with and manage version control, work items, build, and other resources from your client application. This package doesn't support Net Standard Client OM. Only use this package when our REST APIs don't offer the functionality you need (for example, creating workspaces in TFVC). |`Microsoft.TeamFoundation.Build.Client.dll`, `Microsoft.TeamFoundation.DeleteTeamProject.dll`, `Microsoft.TeamFoundation.Diff.dll`, `Microsoft.TeamFoundation.Git.Client.dll`, `Microsoft.TeamFoundation.SharePointReporting.Integration.dll`, and so on. | ## Install -From a NuGet package manager command prompt: +Install from a NuGet package manager command prompt: ```powershell PM> Install-Package Microsoft.TeamFoundationServer.ExtendedClient ``` -## Pattern for use +## Connect -Create an authenticated connection to Azure DevOps, get an HttpClient for the service you want to work with, and then call methods against that service. +To create an authenticated connection to Azure DevOps, get an HttpClient for the service you want to work with, and then call methods against that service. See the following examples: @@ -105,6 +103,8 @@ const String c_collectionUri = "https://dev.azure.com/fabrikam"; const String c_projectName = "MyGreatProject"; const String c_repoName = "MyRepo"; +Uri orgUrl = new Uri(c_collectionUri); + // Connect to Azure DevOps Services VssConnection connection = new VssConnection(orgUrl, new VssBasicCredential(string.Empty, personalAccessToken)); @@ -151,7 +151,7 @@ namespace ConsoleApp1 ``` -Further authentication samples can be found on our [.NET Samples page](../get-started/client-libraries/samples.md). +For more authentication samples, see [.NET Samples](../get-started/client-libraries/samples.md). ## Reference @@ -161,17 +161,13 @@ For more information and for up-to-date reference documentation, see the [.NET A Check out samples on our [.NET Samples Page](../get-started/client-libraries/samples.md) or directly on our [.NET GitHub Repo](https://github.com/microsoft/azure-devops-dotnet-samples). -::: moniker range=">= azure-devops-2019" - For more information on NuGet packages, see [Microsoft.VisualStudio.Services.Client](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Client/). -::: moniker-end - ## Known issues ### Interactive authentication dialog doesn't appear when using the Azure DevOps OM in a Single Threaded Apartment (STA) -The interactive authentication dialog doesn't appear in cases where your code is running from a [Single Threaded Apartment](/windows/desktop/com/single-threaded-apartments) (STA). This issue can commonly occur from [WPF](/dotnet/desktop-wpf/) applications. To work around this issue, you can change your initialization method to be async and request authentication as in the following example. +The interactive authentication dialog doesn't appear in cases where your code is running from a [Single Threaded Apartment](/windows/desktop/com/single-threaded-apartments) (STA). This issue can commonly occur from [WPF](/dotnet/desktop-wpf/) applications. To work around this issue, you can change your initialization method to be async and request authentication as in the following example. ```csharp async void InitAzureDevOps() @@ -183,7 +179,9 @@ async void InitAzureDevOps() CredentialPromptType.PromptIfNeeded); VssConnection vssConnection = new VssConnection(_uri, creds); - await vssConnection.ConnectAsync(); + CancellationTokenSource source = new CancellationTokenSource(); + CancellationToken token = source.Token; + await vssConnection.ConnectAsync(token); ... @@ -196,4 +194,7 @@ For version 16.143.1 of our NuGet packages, we support NetStandard 2.0. These pa ### Microsoft.TeamFoundationServer.ExtendedClient package doesn't have NetStandard support -The [Microsoft.TeamFoundationServer.ExtendedClient](https://www.nuget.org/packages/Microsoft.TeamFoundationServer.ExtendedClient) currently doesn't support a NetStandard compliant version. This package includes our older SOAP object model, which has been replaced by our newer REST object model. At this point, we're no longer investing in the older SOAP object model, and have no plans to create a NetStandard version of it. +The [Microsoft.TeamFoundationServer.ExtendedClient](https://www.nuget.org/packages/Microsoft.TeamFoundationServer.ExtendedClient) doesn't support a NetStandard compliant version. + +> [!IMPORTANT] +> This package includes our older SOAP object model, which we replaced by our newer REST object model. We're no longer investing in the older SOAP object model, and have no plans to create a NetStandard version of it. diff --git a/docs/integrate/concepts/integration-bestpractices.md b/docs/integrate/concepts/integration-bestpractices.md index 6f2ad245990..555a0db8f66 100644 --- a/docs/integrate/concepts/integration-bestpractices.md +++ b/docs/integrate/concepts/integration-bestpractices.md @@ -1,34 +1,35 @@ --- -title: Integration best practices with REST APIs +title: Integration Best Practices titleSuffix: Azure DevOps Services -description: Best practices for integrating Azure DevOps Services with REST APIs. +description: Learn about best practices for integrating Azure DevOps Services. ms.subservice: azure-devops-ecosystem ms.assetid: 9E1F3FD7-E1C1-44D9-B265-5368B3BD621E ms.custom: content-health, FY22Q3, freshness monikerRange: 'azure-devops' ms.author: chcomley author: chcomley -ms.date: 05/31/2022 +ms.date: 04/11/2025 --- -# Best integration practices +# Best practices for integration [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Tools and integrations between services get built to improve efficiencies for Azure DevOps Services. If you aren't careful, automated tools can get out of control executing a high rate of requests. The requests quickly cause Azure DevOps Services to enforce [rate limits](./rate-limits.md) to your organization. To help reduce your risk of hitting the rate limits, follow these best practices when you're using the REST APIs to integrate with Azure DevOps Services. +Tools and integrations between services improve efficiencies for Azure DevOps Services. If you aren't careful, automated tools can get out of control and execute a high rate of requests. The requests can cause Azure DevOps to enforce [rate limits](./rate-limits.md) on your organization. To help reduce your risk of hitting rate limits, follow these best practices when you use the REST APIs to integrate with Azure DevOps. ## Push only actionable work items -Only push actionable items into Azure DevOps Services that your team plans to engage on or address in the future. Keep work items out of Azure DevOps Services until necessary. For example, don't attempt to store telemetry data in Azure DevOps. +Only push actionable items into Azure DevOps that your team plans to engage on or address in the future. Keep work items out of Azure DevOps until necessary. For example, don't attempt to store telemetry data in Azure DevOps. ## Maintain your own data store -Don't add work items into Azure DevOps Services for the sake of having them all in one place. Azure DevOps Services isn't designed as a data storage service. Maintain your own data store. +Don't add work items into Azure DevOps for the sake of having them all in one place. Azure DevOps Services isn't designed as a data storage service. Maintain your own data store. ## Batch your changes -Doing single operations is slow and expensive, which is the leading cause for performance issues and rate limiting. Batch your changes into a single call. See our [batch documentation](/previous-versions/azure/devops/integrate/previous-apis/wit/batch) and [sample code](/previous-versions/azure/devops/integrate/previous-apis/wit/samples) for guidance. + +Doing single operations is slow and expensive, which is the leading cause of performance issues and rate limiting. Batch your changes into a single call. For more information, see our [batch documentation](/previous-versions/azure/devops/integrate/previous-apis/wit/batch) and [sample code](/previous-versions/azure/devops/integrate/previous-apis/wit/samples). ## Limit your revisions @@ -38,40 +39,39 @@ Many revisions on a single work item create bloat and cause performance problems * If you have changes to multiple work items, batch those changes into a single action. * Keep the number of revisions to a minimum to avoid revision limits. -> [!NOTE] -> A work item revision limit of 10,000 is in effect for updates made through the REST API for Azure DevOps Services. This limit restricts updates from the REST API, however, updates from the web portal are not affected. - +> [!NOTE] +> A work item revision limit of 10,000 is in effect for updates made through the REST API. This limit restricts updates from the REST API, but updates from the web portal aren't affected. ## Optimize queries -Optimize your queries to return a modest number of results. Complex conditions and filters can lead to long-running queries. Keep your queries execution time under 30 seconds to avoid threshold failures. +Optimize your queries to return a modest number of results. Complex conditions and filters can lead to long-running queries. Keep your query execution time under 30 seconds to avoid threshold failures. -#### Query performance tips +### Query performance tips * Place a date or range-limiting clause near the top of a query whenever possible. -* Reduce the number of clauses that use the *Ever* operator. -* Reduce the number of clauses that use the *Contains* operator, except for Tags. - - Use the *Contains Words* operator when available. - - Don't use the *Contains* operator on long text fields, as it's expensive. -* Avoid the '<>' and not operators when possible. -* Avoid using the *In Group* operator for large groups. -* Minimize the amount of *Or* operators and ensure you still have top-level scoping before using. -* Avoid using an *OR* clause between an *In Group* operator and Area or Iteration Paths. +* Reduce the number of clauses that use the `Ever` operator. +* Reduce the number of clauses that use the `Contains` operator, except for Tags. + - Use the `Contains Words` operator when available. + - Don't use the `Contains` operator on long text fields, as it's expensive. +* Avoid the `<>` and `Not` operators when possible. +* Avoid using the `In Group` operator for large groups. +* Minimize the number of `Or` operators and ensure you still have top-level scoping before using. +* Avoid using an `OR` clause between an `In Group` operator and Area or Iteration Paths. * Reduce the number of overall clauses to achieve your goal when possible. -* Avoid sorting on anything other than core fields, such as *ID*, when possible. -* If you want to sort on a custom field, use it in your filters. -* Specify a project if possible. Otherwise, the query gets scoped to the entire collection and could take dramatically longer than it needs to. Uncheck "Query across projects on the top-right corner" of the query editor. +* Avoid sorting on anything other than core fields, such as `ID`, when possible. +* Use a custom field in your filters if you want to sort on a custom field. +* Specify a project if possible. Otherwise, the query gets scoped to the entire collection and could take dramatically longer than it needs to. Uncheck **Query across projects** on the top-right corner of the query editor. -#### Query across projects +### Query across projects -* If the query requires search across projects, specify which project you're looking for. +* Specify which project you're looking for if the query requires search across projects. * Use *tags* instead of *keywords* when possible, unless you're searching for partial text of a string. ## Handle failures gracefully Updates and queries fail when resource limits or frequency of utilization crosses the limit threshold. For example, a query that runs longer than 30 seconds returns the following error: -```VS402335: The timeout period (30 seconds) elapsed prior to completion of the query or the server is not responding.``` +`VS402335: The timeout period (30 seconds) elapsed prior to completion of the query or the server is not responding.` When you're consuming the REST APIs, make sure you design your code to handle failures appropriately. @@ -80,7 +80,7 @@ When you're consuming the REST APIs, make sure you design your code to handle fa Limit the number of links per work item as much as possible, to avoid enforcement of link limits. > [!IMPORTANT] -> We'll enforce work item revision and link limits in the near future. These limits will be determined by performance monitoring and customer feedback. +> We plan to enforce work item revision and link limits soon. These limits get determined by performance monitoring and customer feedback. ## Don't use queries for reporting @@ -88,9 +88,9 @@ Using queries and individual *get work item* calls is the top way to get rate li For more information, see our [C# sample on GitHub](https://github.com/sferg-msft/vsts-wit-reporting-example). -## Related articles +## Related content - [.NET client libraries](dotnet-client-libraries.md) - [Migration guide](migration-guide.md) -- [Service hooks](service-hooks.md) +- [Service hooks in Azure DevOps Services REST APIs](service-hooks.md) - [REST API versioning](rest-api-versioning.md) diff --git a/docs/integrate/concepts/rate-limits.md b/docs/integrate/concepts/rate-limits.md index 8be3b400a49..e3796587a94 100644 --- a/docs/integrate/concepts/rate-limits.md +++ b/docs/integrate/concepts/rate-limits.md @@ -1,118 +1,82 @@ --- -title: Resource limits & constraints +title: Rate and usage limits titleSuffix: Azure DevOps -description: Limits on the resources individual users can consume in Azure DevOps, and the number of work item tracking requests they can make +description: Description of limits on rates and the resources used in Azure DevOps. ms.subservice: azure-devops-ecosystem ms.topic: conceptual ms.assetid: 6CBE3B3E-ABFF-4F66-8168-DB5D772E9DDB ms.author: chcomley author: chcomley -ms.date: 07/15/2022 +ms.date: 03/20/2025 monikerRange: 'azure-devops' --- -# Rate limits +# Rate and usage limits [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Azure DevOps, like many software-as-a-service solutions, uses multi-tenancy to reduce costs and improve performance. This design leaves users vulnerable to performance issues and even outages when other users, of their shared resources, have spikes in their consumption. -To combat these problems, Azure DevOps limits the resources individuals can consume, and the amount of requests they can make to certain commands. -When these limits are exceeded, future requests may be either delayed or blocked. +Azure DevOps Services uses multi-tenancy to reduce costs and improve performance. This design leaves users vulnerable to performance issues and even outages when other users of their shared resources have spikes in their consumption. So, Azure DevOps limits the resources individuals can consume, and the amount of requests they can make to certain commands. When these limits are exceeded, future requests might be either delayed or blocked. -When a user's requests are delayed by a significant amount, that user gets an email and sees a warning banner in the web. -For the build service account and others without an email address, members of the Project Collection Administrators group get the email. -For more information, see [Usage monitoring](../../organizations/accounts/usage-monitoring.md). - -When an individual user's requests get blocked, responses with HTTP code 429 (too many requests) are received, with a message similar to the following message: - -```TF400733: The request has been canceled: Request was blocked due to exceeding usage of resource in namespace .``` - -For more information, see the following articles: +For more information, see [Git limits](../../repos/git/limits.md) and [Best practices to avoid hitting rate limits](integration-bestpractices.md). -- [Service and rate limits for Azure DevOps](../../user-guide/service-limits.md) -- [Git limits](../../repos/git/limits.md) -- [Best practices to avoid hitting rate limits](integration-bestpractices.md) -- or [Contact Support in the Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html) +## Global consumption limit -## Current rate limits - -Azure DevOps currently has a global consumption limit. -This limit delays requests from individual users beyond a threshold when shared resources are in danger of being overwhelmed. - -### Global consumption limit - -This limit is focused exclusively on avoiding outages when shared resources are close to being overwhelmed. -Individual users typically only have their requests delayed when one of the following occurs: +Azure DevOps currently has a global consumption limit, which delays requests from individual users beyond a threshold when shared resources are in danger of being overwhelmed. This limit is focused exclusively on avoiding outages when shared resources are close to being overwhelmed. +Individual users typically only get delayed requests when one of the following incidents occurs: - One of their shared resources is at risk of being overwhelmed - Their personal usage exceeds 200 times the consumption of a typical user within a (sliding) five-minute window -The amount of the delay depends on the user's sustained level of consumption. -Delays range from a few milliseconds per request up to 30 seconds. -Once consumption goes to zero or the resource is no longer overwhelmed, the delays stop within five minutes. -If consumption remains high, delays may continue indefinitely to protect the resource. +The amount of the delay depends on the user's sustained level of consumption. Delays range from a few milliseconds per request up to 30 seconds. Once consumption goes to zero or the resource is no longer overwhelmed, the delays stop within five minutes. If consumption remains high, delays might continue indefinitely to protect the resource. -#### Azure DevOps throughput units (TSTUs) +When a user request gets delayed by a significant amount, that user receives an email and a warning banner in the web. +For the build service account and others without an email address, members of the Project Collection Administrators group get the email. +For more information, see [Usage monitoring](../../organizations/accounts/usage-monitoring.md). -Azure DevOps users consume many shared resources, and consumption depends on many factors. For example: +When an individual user's requests get blocked, responses with HTTP code 429 (too many requests) are received, with a message similar to the following message: -- Uploading a large number of files to version control creates a large amount of load on databases and storage accounts. -- Complex work item tracking queries create database load based on the number of work items they search through. -- Builds drive load by downloading files from version control, producing log output, and so on. -- All operations consume CPU and memory on various parts of the service. +```TF400733: The request has been canceled: Request was blocked due to exceeding usage of resource in namespace .``` -To accommodate all of this, Azure DevOps resource consumption is expressed in abstract units called Azure DevOps throughput units, or TSTUs. +### Azure DevOps throughput units -TSTUs eventually incorporate a blend of the following: +Azure DevOps users consume many shared resources, and consumption depends on the following factors: + +- Uploading a large number of files to version control creates a large amount of load on databases and storage accounts +- Complex work item tracking queries create database load based on the number of work items they search through +- Builds drive load by downloading files from version control, producing log output +- All operations consume CPU and memory on various parts of the service + +To accommodate, Azure DevOps resource consumption is expressed in abstract units called Azure DevOps throughput units (TSTUs). TSTUs eventually incorporate a blend of the following items: - [Azure SQL Database DTUs](/azure/azure-sql/database/purchasing-models) as a measure of database consumption - Application tier and job agent CPU, memory, and I/O as a measure of compute consumption - Azure Storage bandwidth as a measure of storage consumption -For now, TSTUs are primarily focused on Azure SQL Database DTUs, since Azure SQL Databases are the shared resources most commonly overwhelmed by excessive consumption. +For now, TSTUs are primarily focused on Azure SQL Database DTUs, since Azure SQL Databases are the shared resources most commonly overwhelmed by excessive consumption. A single TSTU is the average load we expect a typical user of Azure DevOps to generate per five minutes. Typical users also generate spikes in load. These spikes are typically 10 or fewer TSTUs per five minutes. Less frequently, spikes go as high as 100 TSTUs. -A single TSTU is the average load we expect a single normal user of Azure DevOps to generate per five minutes. -Normal users also generate spikes in load. -These spikes are typically 10 or fewer TSTUs per five minutes. -Less frequently, spikes go as high as 100 TSTUs. The global consumption limit is 200 TSTUs within a sliding five-minute window. -## Pipelines - -Rate limiting is similar for Azure Pipelines. -Each pipeline is treated as an individual entity with its own resource consumption tracked. -Even if build agents are self-hosted, they generate load in the form of cloning and sending logs. - -We apply a 200 TSTU limit for an individual pipeline in a sliding 5-minute window. This limit is the same as the global consumption limit for users. -If a pipeline is delayed or blocked by rate limiting, a message appears in the attached logs. - - +We apply a 200 TSTU limit for an individual pipeline in a sliding 5-minute window. This limit is the same as the global consumption limit for users. +If a pipeline gets delayed or blocked by rate limiting, a message appears in the attached logs. ## API client experience -When requests are delayed or blocked, Azure DevOps returns response headers to help API clients react. -While not fully standardized, these headers are [broadly in line with other popular services](https://stackoverflow.com/questions/16022624/examples-of-http-api-rate-limiting-http-response-headers). +When requests get delayed or blocked, Azure DevOps returns response headers to help API clients react. While not fully standardized, these headers are [broadly in line with other popular services](https://stackoverflow.com/questions/16022624/examples-of-http-api-rate-limiting-http-response-headers). The following table lists the headers available and what they mean. Except for `X-RateLimit-Delay`, all of these headers get sent before requests start getting delayed. @@ -141,7 +105,7 @@ This design gives clients the opportunity to proactively slow down their rate of `X-RateLimit-Resource` :::column-end::: :::column span="2"::: - A custom header indicating the service and type of threshold that was reached. Threshold types and service names may vary over time and without warning. We recommend displaying this string to a human, but not relying on it for computation. + A custom header indicating the service and type of threshold that was reached. Threshold types and service names might vary over time and without warning. We recommend displaying this string to a human, but not relying on it for computation. :::column-end::: :::row-end::: --- @@ -182,19 +146,25 @@ This design gives clients the opportunity to proactively slow down their rate of :::row-end::: --- -### Recommendations +## Work tracking, process, & project limits + +Azure DevOps imposes limits for the number of projects you can have in an organization and the number of teams you can have within each project. Also be aware of limits for work items, queries, backlogs, boards, dashboards, and more. For more information, see [Work tracking, process, and project limits](../../organizations/settings/work/object-limits.md). + +## Wiki -We recommend that you at least respond to the `Retry-After` header. If you detect a `Retry-After` header in any response, wait until that amount of time has passed before sending another request. Doing so helps your client application experience fewer enforced delays. Keep in mind that the response is 200, so you don't need to apply retry logic to the request. +In addition to the usual [repository limits](../../repos/git/limits.md#repository-size), wikis defined for a project are limited to 25 MB per single file. -If possible, we further recommend that you monitor `X-RateLimit-Remaining` and `X-RateLimit-Limit` headers. +## Service connections -Doing so allows you to approximate how quickly you're approaching the delay threshold. +There are no per-project limits placed on creating service connections. However, there might be limits, which are imposed through Microsoft Entra ID. For additional information, review the following articles: -Your client can intelligently react by spreading out its requests over time. +- [Microsoft Entra service limits and restrictions](/azure/active-directory/enterprise-users/directory-service-limits-restrictions) +- [Azure subscription and service limits, quotas, and constraints](/azure/azure-resource-manager/management/azure-subscription-service-limits) ## Related articles -- [Service and rate limits for Azure DevOps Services](../../user-guide/service-limits.md) -- [Work tracking, process, and project limits](../../organizations/settings/work/object-limits.md) +- [Track work, manage processes, and set project limits](../../organizations/settings/work/object-limits.md) - [Configure and customize Azure Boards](../../boards/configure-customize.md) -- [Usage monitoring](../../organizations/accounts/usage-monitoring.md) +- [Monitor usage](../../organizations/accounts/usage-monitoring.md) +- [Understand Git limits](../../repos/git/limits.md) +- [Follow best practices for avoiding hitting rate limits](integration-bestpractices.md) diff --git a/docs/integrate/concepts/rest-api-versioning.md b/docs/integrate/concepts/rest-api-versioning.md index 4b7b6444b1e..4c1dcbbafb9 100644 --- a/docs/integrate/concepts/rest-api-versioning.md +++ b/docs/integrate/concepts/rest-api-versioning.md @@ -1,29 +1,33 @@ --- -title: REST API versioning for Azure DevOps -description: Overview of the importance of versioning in REST APIs and guidance on implementing versioning in your projects in Azure DevOps. +title: REST API Versioning for Azure DevOps +description: Learn about the importance of versioning in REST APIs and explore guidance on implementing versioning in your projects in Azure DevOps. ms.assetid: 5fc6efd4-9947-40f2-b4f6-9695a24de87c ms.subservice: azure-devops-ecosystem -ms.topic: conceptual +ms.topic: concept-article ms.custom: engagement-fy23 monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 02/14/2023 +ms.date: 04/10/2025 --- # REST API versioning [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Using versioned REST APIs, you can ensure your projects are scalable and maintainable over time while applications and services continue to work as APIs evolve. +Using versioned REST APIs, you can ensure that your projects are scalable and maintainable over time, and that your applications and services continue to work as APIs evolve. ## Guidelines * API version **must** be specified with every request. -* API versions are in the format {major}.{minor}[-{stage}[.{resource-version}]] - For example, ```1.0```, ```1.1```, ```1.2-preview```, ```2.0```. -* While an API is in preview, you can specify a precise version of a particular revision of the API when needed (for example, ```1.0-preview.1```, ```1.0-preview.2```). -* Once an API is released (1.0, for example), its preview version (1.0-preview) is deprecated and can be deactivated after 12 weeks. -* During this time, you should upgrade to the released version of the API. Once a preview API is deactivated, requests that specify a ```-preview``` version get rejected. + +* API versions are in the format `{major}.{minor}[-{stage}[.{resource-version}]]`. For example: `1.0`, `1.1`, `1.2-preview`, `2.0` + +* While an API is in preview, you can specify a precise version of a particular revision of the API when needed. For example: `1.0-preview.1`, `1.0-preview.2` + +* After an API is released (`1.0`, for example), its preview version (`1.0-preview`) is deprecated and can be deactivated after 12 weeks. + +* During this time, you should upgrade to the released version of the API. Once a preview API is deactivated, requests that specify a `-preview` version get rejected. ### Usage @@ -35,9 +39,9 @@ HTTP request header: Accept: application/json;api-version=1.0 ``` -Uri: +Uri query parameter: -```no-highlight +``` [scheme"://"][host[':'port]]"/v" major-version '/'namespace '/'resource ('/'resource)* '?' query i.e. GET https://dev.azure.com/v1.0/{organization}/_apis/{area}/{resource}?some-query=1000 @@ -45,21 +49,26 @@ i.e. GET https://dev.azure.com/v1.0/{organization}/_apis/{area}/{resource}?some- ### Supported versions +> [!NOTE] +> All supported Rest APIs are documented in the [Azure DevOps Services REST API Reference](/rest/api/azure/devops). + +Team Foundation Server was renamed Azure DevOps Server in 2019. + | Product | 1.0 | 2.0 | 3.0 | 4.0 | 5.0 | 6.0 | 7.0 | |-----------------------------|-----|-----|-----|-----|-----|-----|-----| -| Azure DevOps Services | X | X | X | X | X | X | X | -|Azure DevOps Server 2022 | X | X | X | X | X | X | X | -| Azure DevOps Server 2020 | X | X | X | X | X | X | - | -| Azure DevOps Server 2019 | X | X | X | X | X | - | -| Team Foundation Server 2018 | X | X | X | X | - | - | -| Team Foundation Server 2017 | X | X | X | - | - | - | -| Team Foundation Server 2015 | X | X | - | - | - | - | +| Azure DevOps Services | X | X | X | X | X | X | X | +| Azure DevOps Server 2022 | X | X | X | X | X | X | X | +| Azure DevOps Server 2020 | X | X | X | X | X | X | - | +| Azure DevOps Server 2019 | X | X | X | X | X | - | - | +| Team Foundation Server 2018 | X | X | X | X | - | - | - | +| Team Foundation Server 2017 | X | X | X | - | - | - | - | +| Team Foundation Server 2015 | X | X | - | - | - | - | - | Major API version releases align with Team Foundation Server RTM releases. For example, the `3.0` API set was introduced with Team Foundation Server 2017. A few undocumented version 1.0 APIs existed in Team Foundation Server 2013, but aren't supported. -## Related articles +## Related content -* [Get started with REST APIs](../how-to/call-rest-api.md) -* [Azure DevOps Services REST API reference](/rest/api/azure/devops/) +* [Get started with the REST APIs](../how-to/call-rest-api.md) +* [Azure DevOps Services REST API Reference](/rest/api/azure/devops/) diff --git a/docs/integrate/concepts/service-hooks.md b/docs/integrate/concepts/service-hooks.md index f4f7fb0c5da..01c6b244baf 100644 --- a/docs/integrate/concepts/service-hooks.md +++ b/docs/integrate/concepts/service-hooks.md @@ -7,16 +7,17 @@ ms.topic: conceptual monikerRange: 'azure-devops' ms.author: chcomley author: chcomley -ms.date: 03/25/2022 +ms.date: 11/10/2023 --- -# Service hooks in Azure DevOps +# Service hooks in Azure DevOps Services REST APIs [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -When you use the [Subscriptions](../../service-hooks/overview.md#create-a-subscription) REST APIs, you can programmatically create a subscription that performs an action on an external (consumer) service when a specific event occurs in a project. For example, you can create a subscription to notify your service when a build fails. +When you use the [Subscription](../../service-hooks/overview.md#create-a-subscription) REST APIs, you can programmatically create a subscription that performs an action on an external (consumer) service when a specific event occurs in a project. For example, you can create a subscription to notify your service when a build fails. Supported events: + - Build completed - Code pushed (for Git projects) - Pull request create or updated (for Git projects) diff --git a/docs/integrate/get-started/auth/tfs-basic-auth.md b/docs/integrate/get-started/auth/tfs-basic-auth.md index 4c3a6cde677..1e95f56ace6 100644 --- a/docs/integrate/get-started/auth/tfs-basic-auth.md +++ b/docs/integrate/get-started/auth/tfs-basic-auth.md @@ -7,26 +7,33 @@ ms.assetid: 6dc7f977-4b62-4bd6-b77a-1c6cade1ffa8 monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 10/20/2020 +ms.date: 11/10/2023 --- -# Use the Cross-platform CLI for Azure DevOps using personal access tokens (PATs) +# Use the Cross-platform CLI for Azure DevOps using personal access tokens [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -- You can download the latest version of **Node.js source code**, from the [Node.js source code downloads page](https://nodejs.org/en/download/) -- Install the **Cross-platform CLI for Azure DevOps** +Use personal access tokens (PATs) with the cross-platform CLI for Azure DevOps. + +> [!IMPORTANT] +> We don't recommend using basic authentication or PATs. Instead, we recommend using [Microsoft Entra-based authentication](../authentication/entra.md), if you're interacting with Microsoft Entra accounts. + +## Prerequisites + +- Latest version of [**Node.js source code**](https://nodejs.org/en/download/) +- **Cross-platform CLI for Azure DevOps** - Install **tfx-cli** using `npm`, a component of Node.js by running: ```no-highlight npm i -g tfx-cli ``` - For more information about **tfx-cli**, see the [Node CLI for Azure DevOps on GitHub](https://github.com/Microsoft/tfs-cli). + For more information about **tfx-cli**, see the [Node CLI for Azure DevOps on GitHub](https://github.com/Microsoft/tfs-cli). ## Personal access token -Start by creating a personal access token and paste it into the sign in command. +Create a personal access token and paste it into the sign-in command. ``` ~$ tfx login @@ -37,23 +44,22 @@ Copyright Microsoft Corporation Logged in successfully ``` -Examples of valid URLs are: +See the following examples of valid URLs: - `https://marketplace.visualstudio.com` - `https://youraccount.visualstudio.com/DefaultCollection` ## Configure for Basic authentication -> [!IMPORTANT] -> Basic authentication is not recommended. Turning on IIS basic authentication causes various issues, and you should -> use [personal access tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) instead. For example, if you turn on IIS basic authentication, GIT command line stops working. +> [!WARNING] +> We don't recommend basic authentication. Turning on IIS basic authentication causes various issues, and you should use [personal access tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) instead. For example, if you turn on IIS basic authentication, GIT command line stops working. Follow these steps to enable basic auth for your Azure DevOps instance: > [!WARNING] -> Basic authentication sends usernames and passwords in plaintext. You should consider [configuring Azure DevOps Server to use SSL](/azure/devops/server/admin/setup-secure-sockets-layer) in order to enable secure communication when using basic auth. +> Basic authentication sends usernames and passwords in plaintext. Consider [configuring Azure DevOps Server to use SSL](/azure/devops/server/admin/setup-secure-sockets-layer) to enable secure communication when using basic auth. -1. Install the `Basic Authentication` feature for IIS in Server Manager +1. Install the `Basic Authentication` feature for IIS in Server Manager. > [!div class="mx-imgBorder"] > ![Screenshot of configure basic authentication feature.](./media/configureBasicAuthFeature.png) @@ -67,7 +73,7 @@ Follow these steps to enable basic auth for your Azure DevOps instance: ## tfx sign in with Basic authentication -Now you can start to use `tfx` against your server. You'll want to sign in before issuing commands. +Now you can start to use `tfx` against your server. Sign in before you issue commands. 1. Enter the following command: @@ -76,7 +82,7 @@ Now you can start to use `tfx` against your server. You'll want to sign in befor ``` 2. Add your service url. -3. Add your username. Use `domain\user` (e.g. fabrikam\peter). If you are working on a workgroup machine, use `machinename\user`. +3. Add your username. Use `domain\user` (for example, fabrikam\peter). If you're working on a workgroup machine, use `machinename\user`. 4. Add your password. Enter the password for the username that you previously entered. **You can now use any other tfx command.** diff --git a/docs/integrate/get-started/authentication/authentication-guidance.md b/docs/integrate/get-started/authentication/authentication-guidance.md index 039d343a2c6..fcee9700e13 100644 --- a/docs/integrate/get-started/authentication/authentication-guidance.md +++ b/docs/integrate/get-started/authentication/authentication-guidance.md @@ -4,49 +4,55 @@ titleSuffix: Azure DevOps description: Guidance for authentication with Azure DevOps ms.assetid: 15CCEB1E-F42B-4439-8C35-B8A225F5546C ms.subservice: azure-devops-security -ms.topic: conceptual +ms.topic: conceptual +ms.custom: arm2024 monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 03/05/2021 +ms.date: 07/10/2024 --- # Choose the right authentication mechanism [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -For applications that interface with Azure DevOps Services, you must authenticate to gain access to resources like REST APIs. We understand that Azure DevOps Services offers many different ways to authenticate your application. This article provides guidance to help you choose the right authentication for your application. The following table outlines the recommended authentication mechanism for different application types. See the following basic descriptions, examples, and code samples to get you started. +For applications that interface with Azure DevOps Services, you must authenticate to gain access to resources like REST APIs. This article provides guidance to help you choose the right authentication mechanism for your application. + +The following table outlines suggested authentication concepts to consider for different application scenarios. Refer to the accompanying descriptions, examples, and code samples to help get you started. -| Type of application | Description | Example |Authentication mechanism | Code samples | -|---------------------|-------------|---------|-------------------------|--------| - Interactive client-side (REST) | Client application, that allows user interaction, calling [Azure DevOps Services REST APIs](/rest/api/azure/devops) | Console application enumerating projects in an organization | [Microsoft Authentication Library (MSAL)](/azure/active-directory/develop/msal-overview) | [sample](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ManagedClientConsoleAppSample) | -| Interactive client-side (Client library) | Client application, that allows user interaction, calling Azure DevOps Services Client libraries | Console application enumerating bugs assigned to the current user | [Client libraries](../../concepts/dotnet-client-libraries.md) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/ClientLibraryConsoleAppSample) | -| Interactive JavaScript | GUI-based JavaScript application | AngularJS single page app displaying project information for a user | [Microsoft Authentication Library for JavaScript (MSAL JS)](https://github.com/AzureAD/microsoft-authentication-library-for-js#microsoft-authentication-library-for-javascript-msaljs) | [sample](https://github.com/microsoft/azure-devops-auth-samples/tree/master/JavascriptWebAppSample) | -| Personal access token (PAT) | Bearer token to access your own resources | Use your PAT in place of your password. | [PATs](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) -| Non-interactive client-side | Headless text only client-side application | Console app displaying all bugs assigned to a user | [Device Profile](/azure/active-directory/develop/v2-oauth2-device-code) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/DeviceProfileSample) | -| Interactive client-side app targeting Azure DevOps | Client application, that allows user interaction, authenticates Azure DevOps users | Console application allowing Azure DevOps users to see assigned bugs | [Client Library (Interactive and Windows authentication)](../client-libraries/samples.md#authenticating) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/DualSupportClientSample) | -| Interactive web | GUI-based web application that requires user consent | Custom Web dashboard displaying build summaries |[Azure DevOps OAuth](./oauth.md) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/OAuthWebSample) | -| Service Principals or Managed Identities | Application with access to organization's Azure DevOps resources | Azure function to create work items |[Service principals and managed identities](./service-principal-managed-identity.md)| [sample](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ServicePrincipalsSamples) | -| Azure DevOps Server application | Azure DevOps Server app using the Client OM library | Azure DevOps Server extension displaying team bug dashboards | [Client Libraries](../../concepts/dotnet-client-libraries.md) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/ClientLibraryConsoleAppSample) | -| [Azure DevOps Services Extension](../../../extend/get-started/node.md) | Azure DevOps Services extension | [Agile Cards](https://marketplace.visualstudio.com/items?itemName=spartez.agile-cards) | [VSS Web Extension SDK](https://github.com/Microsoft/azure-devops-extension-sdk) | [sample](../../../extend/develop/add-dashboard-widget.md) | -For a primer on security and identity concepts in Azure DevOps, see [About security and identity](../../../organizations/security/about-security-identity.md). -To learn more about how we store your credentials, see [Credential storage for Azure DevOps](../../../organizations/security/credential-storage.md). +| Type of application | Description | Example | Authentication mechanism | Code samples | +|---------------------|-------------|---------|-------------------------|--------| +| Interactive client-side app (REST) | Client application that allows user interaction calling [Azure DevOps Services REST APIs](/rest/api/azure/devops) | Console application enumerating projects in an organization | [OAuth](./oauth.md) with Microsoft Authentication Library (MSAL) | [sample](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ManagedClientConsoleAppSample) | +| Interactive client-side app (client libraries) | Client application that allows user interaction calling Azure DevOps Services [client libraries](../../concepts/dotnet-client-libraries.md) | Console application enumerating bugs assigned to the current user | OAuth with [client libraries](../../concepts/dotnet-client-libraries.md) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/ClientLibraryConsoleAppSample) | +| Non-interactive client-side app | Headless text only client-side application | Console app displaying all bugs assigned to a user | OAuth with [Device Profile](/azure/active-directory/develop/v2-oauth2-device-code) flow | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/DeviceProfileSample) | +| Personal access token (PAT) | Bearer token to access your own resources | Use your PAT in place of your password for ad-hoc REST calls. Not ideal for applications. | [PATs](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) |[examples](../../how-to/call-rest-api.md) | +| Server app | Azure DevOps Server app using the Client OM library | Azure DevOps Server extension displaying team bug dashboards | [Client Libraries](../../concepts/dotnet-client-libraries.md) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/ClientLibraryConsoleAppSample) | +| Service principal or Managed identity | Application with its own identity | Azure function to create work items | [Service principals and managed identities](./service-principal-managed-identity.md)| [sample](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ServicePrincipalsSamples) | +| Web extension | Azure DevOps Services [extension](../../../extend/develop/samples-overview.md) | [Agile Cards](https://marketplace.visualstudio.com/items?itemName=spartez.agile-cards) extension | [VSS Web Extension SDK](https://github.com/Microsoft/azure-devops-extension-sdk) | [sample](../../../extend/develop/add-dashboard-widget.md) | -#### Enabling IIS Basic Authentication invalidates using PATs for Azure DevOps Server +> [!TIP] +> [Entra-based authentication](entra.md) is our recommendation for developers looking to integrate with Azure DevOps Services, if you are interacting with Microsoft Entra accounts. The OAuth sample apps in this table are using [Microsoft Entra's identity platform for app development](entra-oauth.md).
      +> For authentication with Microsoft accounts (MSA) or Azure DevOps Server users, look into our [client libraries](../../concepts/dotnet-client-libraries.md) or [PATs](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md).
      +> Read up more in [our blog](https://devblogs.microsoft.com/devops/reducing-pat-usage-across-azure-devops/) on how we're reducing PAT usage across our platform. -Learn more about [using IIS Basic Authentication with Azure DevOps on-premises](iis-basic-auth.md). ## Frequently asked questions (FAQs) -#### Q: Why can't one of my service accounts access the Azure DevOps REST API? -A: Your service account may not have "materialized." Since signing in isn't possible with a service account that doesn't have interactive signing in permissions, check out [this work-around](https://github.com/microsoft/azure-devops-dotnet-samples/blob/main/ClientLibrary/Quickstarts/dotnet/MaterializeUserQuickStarts/Program.cs). +### Q: Why can't my service account access the Azure DevOps REST API? +A: Your service account might not have "materialized." Service accounts without interactive sign-in permissions can't sign in. For more information, see [this work-around](https://github.com/microsoft/azure-devops-dotnet-samples/blob/main/ClientLibrary/Quickstarts/dotnet/MaterializeUserQuickStarts/Program.cs) for a solution. + +### Q: Should I use [Azure DevOps Services Client Libraries](../../concepts/dotnet-client-libraries.md) or [Azure DevOps Services REST APIs](/rest/api/azure/devops) for my interactive client-side application? +A: We recommend using Azure DevOps Services Client Libraries over REST APIs for accessing Azure DevOps Services resources. They're simpler and easier to maintain when REST endpoint versions change. If the client libraries lack certain functionality, use [MSAL](/azure/active-directory/develop/msal-overview) for authentication with our REST APIs. + +### Q: Is this guidance only for Azure DevOps Services or is it also relevant for on-premises Azure DevOps Server users? +A: This guidance is primarily for Azure DevOps Services users. For Azure Devops Server users, we recommend using the [Client Libraries](../../concepts/dotnet-client-libraries.md), Windows Authentication, or [Personal Access Tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) for authentication. -#### Q: I'm making an interactive client-side application. Should I use [Azure DevOps Services Client Libraries](../../concepts/dotnet-client-libraries.md) or [Azure DevOps Services REST APIs](/rest/api/azure/devops)? -A: We recommend using Azure DevOps Services Client Libraries over REST APIs when accessing Azure DevOps Services resources. They're simpler and more easily maintained when version changes to our REST endpoints occur. If functionality is missing from the client libraries, [MSAL](/azure/active-directory/develop/msal-overview) is the best authentication mechanism to use with our REST APIs. +### Q: What if I want my application to authenticate with both Azure DevOps Server and Azure DevOps Services? +A: The best practice is to have separate authentication paths for Azure DevOps Server and Azure DevOps Services. You can use the `requestContext` to determine which service you're accessing and then apply the appropriate authentication mechanism. If you prefer a unified solution, [PATs](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) work for both. -#### Q: Is this guidance only for Azure DevOps Services or is it also relevant for on-premises Azure DevOps Server users? -A: This guidance is mainly for Azure DevOps Services users. [Client Libraries](../../concepts/dotnet-client-libraries.md) are a series of packages built specifically for extending Azure DevOps Server functionality. For on-premises users, we recommend using the [Client Libraries](../../concepts/dotnet-client-libraries.md), Windows Auth, or [Personal Access Tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) to authenticate for a user. +## Related resources -#### Q: What if I want my application to authenticate with both Azure DevOps Server and Azure DevOps Services? -A: The best practice is to have different authentication paths for Azure DevOps Server and Azure DevOps Services. You can use the requestContext to find out which you're hitting and then use the best mechanism for each. Instead, if you want a unified solution, [PATs](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) works for both. +- [About security and identity](../../../organizations/security/about-security-identity.md). +- [Azure DevOps data protection overview](../../../organizations/security/data-protection.md) +- [Sample applications](https://github.com/microsoft/azure-devops-auth-samples/tree/master) diff --git a/docs/integrate/get-started/authentication/azure-devops-oauth.md b/docs/integrate/get-started/authentication/azure-devops-oauth.md new file mode 100644 index 00000000000..b269d077e5c --- /dev/null +++ b/docs/integrate/get-started/authentication/azure-devops-oauth.md @@ -0,0 +1,284 @@ +--- +ms.topic: how-to +title: Use Azure DevOps OAuth 2.0 implementation +description: How to use the Azure DevOps OAuth 2.0 implementation for existing web apps. +monikerRange: 'azure-devops' +ms.author: chcomley +author: chcomley +ms.date: 10/21/2024 +--- + +# Use Azure DevOps OAuth 2.0 to create a web app + +[!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] + +> [!IMPORTANT] +> Azure DevOps OAuth is slated for deprecation in 2026. This information is for existing Azure DevOps OAuth apps only. To create new apps, use [Microsoft Entra ID OAuth](entra-oauth.md) to integrate with Azure DevOps. Starting April 2025, we stop accepting new Azure DevOps OAuth apps. [Learn more in our blog post](https://devblogs.microsoft.com/devops/no-new-azure-devops-oauth-apps-beginning-february-2025/). + +Azure DevOps is an identity provider for OAuth 2.0 apps. Our implementation of OAuth 2.0 lets developers authorize their app for users and get access tokens for Azure DevOps resources. + +## Get started with Azure DevOps OAuth + +### 1. Register your app + +1. Go to `https://app.vsaex.visualstudio.com/app/register` to register your app. + +2. Select the [scopes](./oauth.md#scopes) that your application needs, and then use the same scopes when you [authorize your app](#2-authorize-your-app). If you registered your app using the preview APIs, re-register because the scopes that you used are now deprecated. + +3. Select **Create application**. + + The application settings page displays. + + :::image type="content" source="media/app-page.png" alt-text="Screenshot showing Applications settings for your app."::: + + - When Azure DevOps Services presents the authorization approval page to your user, it uses your company name, app name, and descriptions. It also uses the URLs for your company web site, app website, and terms of service and privacy statements. + + :::image type="content" source="media/grant-access.png" alt-text="Screenshot showing Visual Studio Codespaces authorization page with your company and app information."::: + + - When Azure DevOps Services asks for a user's authorization, and the user grants it, the user's browser gets redirected to your authorization callback URL with the authorization code. + The callback URL must be a secure connection (https) to transfer the code back to the app and exactly match the URL registered in your app. If it doesn't, a 400 error page is displayed instead of a page asking the user to grant authorization to your app. + +4. Call the authorization URL and pass your app ID and authorized scopes when you want to have a user authorize your app to access their organization. +Call the access token URL when you want to get an access token to call an Azure DevOps Services REST API. + +The settings for each app that you register are available from your profile `https://app.vssps.visualstudio.com/profile/view`. + +### 2. Authorize your app + +1. If your user didn't authorize your app to access their organization, call the authorization URL. It calls you back with an authorization code, if the user approves the authorization. + +```no-highlight +https://app.vssps.visualstudio.com/oauth2/authorize + ?client_id={app ID} + &response_type={Assertion} + &state={state} + &scope={scope} + &redirect_uri={callback URL} +``` + +Parameter | Type | Notes +--------------|--------|---------------------------- +client_id | GUID | The ID assigned to your app when it was registered. +response_type | string | `Assertion` +state | string | Can be any value. Typically a generated string value that correlates the callback with its associated authorization request. +scope | string | Scopes registered with the app. Space separated. See [available scopes](oauth.md#scopes). +redirect_uri | URL | Callback URL for your app. **Must exactly match the URL registered with the app**. + +2. Add a link or button to your site that takes the user to the Azure DevOps Services authorization endpoint: + +```no-highlight +https://app.vssps.visualstudio.com/oauth2/authorize + ?client_id=00001111-aaaa-2222-bbbb-3333cccc4444 + &response_type=Assertion + &state=User1 + &scope=vso.work%20vso.code_write + &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback +``` + +Azure DevOps Services asks the user to authorize your app. + +Assuming the user accepts, Azure DevOps Services redirects the user's browser to your callback URL, including a short-lived authorization code and the state value provided in the authorization URL: + +```no-highlight +https://fabrikam.azurewebsites.net/myapp/oauth-callback + ?code={authorization code} + &state=User1 +``` + +### 3. Get an access and refresh token for the user + +Use the authorization code to request an access token (and refresh token) for the user. Your service must make a service-to-service HTTP request to Azure DevOps Services. + +#### URL - authorize app + +```no-highlight +POST https://app.vssps.visualstudio.com/oauth2/token +``` + +#### HTTP request headers - authorize app + +| Header | Value +|-------------------|------------------------------------------------------------------ +| Content-Type | `application/x-www-form-urlencoded` + +```no-highlight +Content-Type: application/x-www-form-urlencoded +``` + +#### HTTP request body - authorize app + +```no-highlight +client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2} +``` + +Replace the placeholder values in the previous sample request body: + +* **{0}**: URL encoded client secret acquired when the app was registered +* **{1}**: URL encoded "code" provided via the `code` query parameter to your callback URL +* **{2}**: callback URL registered with the app + +#### C# example to form the request body - authorize app + +```no-highlight +public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl) +{ + return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}", + HttpUtility.UrlEncode(appSecret), + HttpUtility.UrlEncode(authCode), + callbackUrl + ); +} +``` + +#### Response - authorize app + +```json +{ + "access_token": { access token for the user }, + "token_type": { type of token }, + "expires_in": { time in seconds that the token remains valid }, + "refresh_token": { refresh token to use to acquire a new access token } +} +``` + +> [!NOTE] +> Securely persist the **refresh_token** so your app doesn't need to prompt the user to authorize again. Access tokens expire quickly and shouldn't be persisted. + +### 4. Use the access token + +To use an access token, include it as a bearer token in the Authorization header of your HTTP request: + +``` +Authorization: Bearer {access_token} +``` + +For example, the HTTP request to [get recent builds](https://visualstudio.com/api/build-release/builds.md#getalistofbuilds) for a project: + +```no-highlight +GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0 +Authorization: Bearer {access_token} +``` + +### 5. Refresh an expired access token + +If a user's access token expires, you can use the refresh token that they acquired in the authorization flow to get a new access token. It's like the original process for exchanging the authorization code for an access and refresh token. + +#### URL - refresh token + +```no-highlight +POST https://app.vssps.visualstudio.com/oauth2/token +``` + +#### HTTP request headers - refresh token + + +| Header | Value | +|-------------------|------------------------------------------------------------------| +| Content-type | `application/x-www-form-urlencoded`| +| Content-length | Calculated string length of the request body (see the following example)| + + +```no-highlight +Content-Type: application/x-www-form-urlencoded +Content-Length: 1654 +``` + +#### HTTP request body - refresh token + +```no-highlight +client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2} + +``` + +Replace the placeholder values in the previous sample request body: + +* **{0}**: URL encoded client secret acquired when the app was registered +* **{1}**: URL encoded refresh token for the user +* **{2}**: callback URL registered with the app + +#### Response - refresh token + +```json +{ + "access_token": { access token for this user }, + "token_type": { type of token }, + "expires_in": { time in seconds that the token remains valid }, + "refresh_token": { new refresh token to use when the token has timed out } +} +``` + +> [!NOTE] +> A new refresh token gets issued for the user. Persist this new token and use it the next time you need to acquire a new access token for the user. + +### Samples + +You can find a C# sample that implements OAuth to call Azure DevOps Services REST APIs in our [C# OAuth GitHub Sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/OAuthWebSample). + +## Regenerate client secret + +Your application secret regularly expires. Starting March 2025, the default secret lifespan of new application secrets is 60 days. + +Applications can have two secrets at any time. Continue to create and use access tokens and refresh tokens by rotating your soon-to-expire app secret with a new application secret. + +1. Create a secondary secret by selecting **"Generate Secret"** for "Secret 2". + +:::image type="content" source="media/app-page-new-secret.png" alt-text="Screenshot of app page with secondary secret already generated."::: + +2. Next, confirm in the modal that you want to complete this action. + +:::image type="content" source="media/secret-regeneration-modal.png" alt-text="Screenshot confirming secret regeneration."::: + +3. Update your app to use the new Secret #2 before Secret #1 expires. By managing two secrets at once, there is no downtime for your users as a result of expiring secrets. + +4. Secret #1 naturally expires and all previous tokens cease to work. + +5. When it's time to rotate a soon-to-expire Secret #2, you can repeat this process by regenerating Secret #1 and using the regenerated Secret #1 in place of Secret #2. + +If secrets are leaked, you can quickly revoke the secret by clicking "Regenerate Secret". Once you confirm that you want to regenerate, the previous app secret no longer works and all previous tokens minted with this secret also stop working. Use the dual secrets rotation method to minimize downtime while revoking the leaked secret through regeneration. + +## Delete your app + +If you no longer need your app, delete it from your profile. + +1. Go to your profile at: `https://app.vssps.visualstudio.com/profile/view`. +2. Ensure you're on the correct tenant's page by selecting from the dropdown menu under your name in the sidebar. +3. Find the app under the **Applications and services** header on the left sidebar. +4. select "Delete" on the application registration page. A modal appears to confirm your deletion. + + :::image type="content" source="media/azdo-oauth-app-delete.png" alt-text="Screenshot of app metadata page with delete button highlighted"::: + +5. Once you delete the app registration, the app breaks, and we stop minting new tokens or accepting minted tokens for this app. + +## Frequently asked questions (FAQs) + + + +#### Q: Can I use OAuth with my mobile phone app? + +A: No. Azure DevOps Services only supports the web server flow, so there's no way to implement OAuth, as you can't securely store the app secret. + +#### Q: What errors or special conditions do I need to handle in my code? + +A: Make sure that you handle the following conditions: +* If your user denies your app access, no authorization code gets returned. Don't use the authorization code without checking for denial. +* If your user revokes your app's authorization, the access token is no longer valid. When your app uses the token to access data, a 401 error returns. Request authorization again. + +#### Q: I want to debug my web app locally. Can I use localhost for the callback URL when I register my app? + +A: Yes. Azure DevOps Services now allows localhost in your callback URL. Ensure you use `https://localhost` as the beginning of your callback URL when you register your app. + +#### Q: I get an HTTP 400 error when I try to get an access token. What might be wrong? + +A: Check that you set the content type to application/x-www-form-urlencoded in your request header. + +#### Q: I get an HTTP 401 error when I use an OAuth-based access token, but a PAT with the same scope works fine. Why? + +A: Verify that your organization's admin didn't disable **Third-party application access via OAuth** at `https://dev.azure.com/{your-org-name}/_settings/organizationPolicy`. +In this scenario, the flow to authorize an app and generate an access token works, but all REST APIs return only an error, such as `TF400813: The user "" is not authorized to access this resource.` + +## Related articles + +* [Choosing the right authentication method](authentication-guidance.md) +* [Use Microsoft Entra ID OAuth](oauth.md) +* [Default permissions and access for Azure DevOps](../../../organizations/security/permissions-access.md) +* [Manage authorizations](../../../organizations/settings/manage-authorizations.md) diff --git a/docs/integrate/get-started/authentication/entra-oauth.md b/docs/integrate/get-started/authentication/entra-oauth.md new file mode 100644 index 00000000000..1237610a0b8 --- /dev/null +++ b/docs/integrate/get-started/authentication/entra-oauth.md @@ -0,0 +1,59 @@ +--- +title: Building Azure DevOps integrations with Microsoft Entra OAuth apps +description: Use Microsoft Entra authentication to integrate with Azure DevOps Services. +ms.assetid: 19285121-1805-4421-B7C4-63784C9A7CFA +ms.subservice: azure-devops-security +ms.topic: conceptual +monikerRange: 'azure-devops' +ms.author: chcomley +author: chcomley +ms.date: 01/08/2025 +--- + +# Build Azure DevOps integrations with Microsoft Entra OAuth apps + +[!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] + +This guide provides information and links to more information on building a Microsoft Entra OAuth app for Azure DevOps. Microsoft Entra ID offers robust identity and access management capabilities, which allow you to authenticate users and perform actions on their behalf using OAuth tokens. Use this information to apply Microsoft Entra OAuth tokens for various app flows, including delegated access and service principal-based access. + +## Use Microsoft Entra OAuth tokens + +The Microsoft identity platform offers many ways to authenticate users via [the OAuth 2.0 protocol](/entra/identity-platform/v2-protocols). In these docs, we use OAuth tokens to colloquially refer to [on-behalf-of user flows](/entra/identity-platform/v2-oauth2-on-behalf-of-flow), also known as [delegated flows](/entra/identity-platform/delegated-access-primer), for apps that request tokens to perform actions for their users. The rest of this guide offers helpful resources for these app developers. + +Another common app flow we support is building [on-behalf-of app using service principals and managed identities](service-principal-managed-identity.md). +Microsoft Entra tokens can also be used for [ad-hoc requests with the Azure CLI](entra.md?tabs=azure-cli#acquire-user-tokens) or [git operations through the Git Credential Manager](entra.md#git-operations-with-git-credential-manager). + +> [!IMPORTANT] +> When creating a new OAuth 2.0 app, start here with Microsoft Entra OAuth apps, as [Azure DevOps OAuth apps](azure-devops-oauth.md) are planned for deprecation in 2026. [Learn more in our blog post](https://devblogs.microsoft.com/devops/no-new-azure-devops-oauth-apps-beginning-february-2025/). + +## Resources for developers + +* [Register an application with the Microsoft identity platform](/entra/identity-platform/quickstart-register-app) +* [Add permissions for access to Microsoft Graph](/entra/identity-platform/quickstart-configure-app-access-web-apis#add-permissions-to-access-microsoft-graph): Learn how to add delegated permissions from an Azure resource. Instead of Microsoft Graph, select `Azure DevOps` from the list of resources. +* [Read about scopes and permissions in the Microsoft identity platform](/entra/identity-platform/scopes-oidc): Understand the `.default` scope. See the scopes available for Azure DevOps in [our list of scopes](oauth.md#scopes). +* [Request permissions through consent](/entra/identity-platform/consent-types-developer) +* [Use authentication libraries](/entra/identity-platform/reference-v2-libraries) and [code samples](/entra/identity-platform/sample-v2-code?tabs=apptype) +* [Manage personal access tokens via API](../../../organizations/accounts/manage-personal-access-tokens-via-api.md): Use the PAT lifecycle management APIs with Microsoft Entra tokens. Our docs and the [associated sample app](https://github.com/microsoft/azure-devops-auth-samples/tree/master/PersonalAccessTokenAPIAppSample) provide examples for setting up a Microsoft Entra app to use Azure DevOps REST APIs. +* [Explore support and help options for developers](/entra/identity-platform/developer-support-help-options) + +### Resources for admins + +* [Understand application management in Microsoft Entra ID](/entra/identity/enterprise-apps/what-is-application-management) +* [Add an enterprise application](/entra/identity/enterprise-apps/add-application-portal) +* [Explore the consent experience for applications in Microsoft Entra ID](/entra/identity-platform/application-consent-experience) + +## Tips for building & migrating + +> [!NOTE] +> Microsoft Entra OAuth apps don't natively support Microsoft account (MSA) users for Azure DevOps REST APIs. If you're building an app that must cater to MSA users or support both Microsoft Entra and MSA users, [Azure DevOps OAuth apps](azure-devops-oauth.md) remain your best option. We're currently working on native support for MSA users through Microsoft Entra OAuth. + +* **Important Azure DevOps IDs:** + * Microsoft Entra resource identifier: `499b84ac-1321-427f-aa17-267ca6975798` + * Resource URI: `https://app.vssps.visualstudio.com` + * Use the `.default` scope when requesting a token with all scopes that the app is permissioned for. +* When you migrate an existing app, you might use Azure DevOps user identifiers that don't exist in Microsoft Entra. Use the [ReadIdentities API](/rest/api/azure/devops/ims/identities/read-identities) to resolve and match the different identities used by each identity provider. + +## Related articles + +- [Authenticate to Azure DevOps with Microsoft Entra](entra.md) +- [Use service principals & managed identities in Azure DevOps](service-principal-managed-identity.md) diff --git a/docs/integrate/get-started/authentication/entra.md b/docs/integrate/get-started/authentication/entra.md new file mode 100644 index 00000000000..75f4dd30ae8 --- /dev/null +++ b/docs/integrate/get-started/authentication/entra.md @@ -0,0 +1,91 @@ +--- +ms.topic: how-to +title: Authenticate to Azure DevOps with Microsoft Entra ID access tokens +description: Use Microsoft Entra authentication to access Azure DevOps Services. +ms.assetid: 19285121-1805-4421-B7C4-63784C9A7CFA +ms.subservice: azure-devops-security +monikerRange: 'azure-devops' +ms.author: chcomley +author: chcomley +ms.date: 01/31/2025 +--- + +# Authenticate to Azure DevOps with Microsoft Entra + +Microsoft Entra ID is a separate Microsoft product with its own platform. As a leading identity and access management (IAM) provider, [Microsoft Entra ID](/entra/fundamentals/whatis) focuses on managing team members and safeguarding company resources. You can [connect your Azure DevOps organization to a Microsoft Entra ID tenant](../../../organizations/accounts/connect-organization-to-azure-ad.md), which offers [many benefits to your company](../../../organizations/accounts/access-with-azure-ad.md). + +Once connected, the Microsoft Identity application platform on top of Microsoft Entra ID provides several advantages for app developers and org admins. You can register an application to access Azure tenants and define permissions needed from Azure resources, including Azure DevOps, which exists outside of the Azure tenant construct. + +Microsoft Entra apps and Azure DevOps apps are separate entities with no knowledge of each other. The authentication methods differ: Microsoft Entra uses OAuth, while Azure DevOps uses its own OAuth. [Microsoft Entra ID OAuth apps](/entra/identity-platform/v2-protocols) issue Microsoft Entra tokens, not Azure DevOps access tokens. These tokens have a standard one-hour duration before expiration. + +## Develop Azure DevOps apps on Microsoft Entra + +Read the Microsoft Entra documentation thoroughly to understand the new functionality and [different expectations](/entra/identity-platform/application-model) during setup. + +We support your app development with guidance for: +* [Microsoft Entra OAuth apps (on-behalf-of user apps)](entra-oauth.md) for apps that perform actions on behalf of consenting users. +* [Microsoft Entra service principals and managed identities (on-behalf-of itself apps)](service-principal-managed-identity.md) for apps that perform automated tooling within a team. + +## Replace PATs with Microsoft Entra tokens + +[Personal access tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) are popular for Azure DevOps authentication due to their ease of creation and use. However, poor PAT management and storage can lead to unauthorized access to your Azure DevOps organizations. Long-lived or over-scoped PATs increase the risk of damage from a leaked PAT. + +Microsoft Entra tokens offer a secure alternative, lasting only one hour before requiring a refresh. The authentication protocols for generating Entra tokens are more robust and secure. Security measures like [conditional access policies](../../../organizations/accounts/change-application-access-policies.md#cap-support-on-azure-devops) protect against token theft and replay attacks. We encourage users to explore using Microsoft Entra tokens instead of PATs. We share popular PAT use cases and ways to replace PATs with Entra tokens in this workflow. + +### Ad-hoc requests to Azure DevOps REST APIs + +You can also use the [**Azure CLI**](/cli/azure/install-azure-cli) to get Microsoft Entra ID access tokens for users to call [Azure DevOps REST APIs](/rest/api/azure/devops/). Since Entra access tokens only last for one hour, they're ideal for quick one-off operations, like API calls that don't need a persistent token. + +--- + +#### Acquire user tokens + +# [Azure CLI](#tab/azure-cli) + +1. Sign in to the Azure CLI using the `az login` command and follow the on-screen instructions. +1. Set the correct subscription for the signed-in user with these bash commands. Make sure the Azure subscription ID is associated with the tenant connected to the Azure DevOps organization you're trying to access. If you don't know your subscription ID, you can find it in the [Azure portal](/azure/azure-portal/get-subscription-tenant-id). + + ```bash + az account set -s + ``` + +1. Generate a Microsoft Entra ID access token with the `az account get-access-token` command using the Azure DevOps resource ID: `499b84ac-1321-427f-aa17-267ca6975798`. + + ```bash + az account get-access-token \ + --resource 499b84ac-1321-427f-aa17-267ca6975798 \ + --query "accessToken" \ + -o tsv + ``` + +# [Azure PowerShell](#tab/azure-powershell) + +1. Sign in to Azure PowerShell using the `Connect-AzAccount` command and follow the on-screen instructions. +1. Set the correct subscription for the signed-in user with these PowerShell commands. Make sure the Azure subscription ID is associated with the tenant connected to the Azure DevOps organization you're trying to access. If you don't know your subscription ID, you can find it in the [Azure portal](/azure/azure-portal/get-subscription-tenant-id). + + ```azurepowershell-interactive + Set-AzContext -Subscription + ``` + +1. Generate a Microsoft Entra ID access token with the `Get-AzAccessToken` command using the Azure DevOps resource ID: `499b84ac-1321-427f-aa17-267ca6975798`. + + ```azurepowershell-interactive + Get-AzAccessToken -ResourceUrl '499b84ac-1321-427f-aa17-267ca6975798' + ``` + +--- + +For more information, see the [Databricks docs](/azure/databricks/dev-tools/user-aad-token). + +#### Acquire service principal tokens in Azure CLI + +Service principals can also use ad-hoc Microsoft Entra ID access tokens for ad-hoc operations. For more information, see [Service principals and managed identities/Get a Microsoft Entra ID token with the Azure CLI](service-principal-managed-identity.md#b-acquire-a-microsoft-entra-id-token-with-the-azure-cli). + +### Git operations with Git Credential Manager + +You can also use Microsoft Entra tokens to perform Git operations. If you regularly push to git repositories, [use the Git Credential Manager](../../../repos/git/set-up-credential-managers.md) to easily request and manage your Microsoft Entra OAuth token credentials, as long as `oauth` is set as the default `credential.azReposCredentialType`. + +## Related articles + +- [Build Azure DevOps integration with Microsoft Entra OAuth apps](entra-oauth.md) +- [Use service principals & managed identities in Azure DevOps](service-principal-managed-identity.md) diff --git a/docs/integrate/get-started/authentication/iis-basic-auth.md b/docs/integrate/get-started/authentication/iis-basic-auth.md deleted file mode 100644 index 8280b6b75fc..00000000000 --- a/docs/integrate/get-started/authentication/iis-basic-auth.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: IIS Basic Authentication invalidates using PATs -description: Enabling IIS Basic Authentication invalidates using Personal Access Tokens. -ms.assetid: 173198c4-9b65-4c4a-a8f1-931b6b6c295a -ms.subservice: azure-devops-ecosystem -ms.topic: conceptual -monikerRange: '<= azure-devops-2020' -ms.author: chcomley -author: chcomley -ms.date: 09/30/2021 ---- - -# Enabling IIS Basic Authentication invalidates using Personal Access Tokens - -[!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] - -We recommend you keep [IIS Basic Authentication]( /iis/configuration/system.webserver/security/authentication/basicauthentication) turned off always when using Azure DevOps Server. Only if necessary should you enable IIS Basic Authentication. When IIS Basic Authentication is enabled on your windows machine, it prevents you from using personal access tokens (PATs) as an authentication mechanism. - -For example, if you use a PAT to allow a third-party app to retrieve bug information, and then email that info to the bug assignee with IIS Basic Authentication enabled, then that app fails authentication. The app can't retrieve bug info. - -## Git with IIS Basic Authentication enabled - -> [!WARNING] -> If you use Git with IIS Basic Authentication, Git breaks because it requires PATs for user authentication. Although we don't recommend you use IIS Basic Authentication, by adding an extra header to Git requests, you can use Git with IIS Basic Authentication. -> -> The extra header must be used for all Azure DevOps Server installations, as Windows Auth also prevents using PATs. - -The extra header must include a base 64 encoding of "user:PAT". See the following format and example. - -### Format - - ``` - git -c http.extraheader='Authorization: Basic [base 64 encoding of "user:password"]' ls-remote http://tfsserver:8080/tfs/DefaultCollection/_git/projectName - ``` - -### Example - - ``` - git -c http.extraheader='Authorization: Basic a2FzYW50aGE6bzN3cDVndmw2YXRkajJkam83Znd4N2k3NDdhbGxjNXp4bnc3b3o0dGQycmd3d2M1eTdjYQ==' ls-remote http://tfsserver:8080/tfs/DefaultCollection/_git/projectName - ``` - -## Related articles - -- [Authentication guidance](authentication-guidance.md) -- [Authorize access to REST APIs with OAuth 2.0](oauth.md) diff --git a/docs/integrate/get-started/authentication/media/app-page-new-secret.png b/docs/integrate/get-started/authentication/media/app-page-new-secret.png new file mode 100644 index 00000000000..ff10262b478 Binary files /dev/null and b/docs/integrate/get-started/authentication/media/app-page-new-secret.png differ diff --git a/docs/integrate/get-started/authentication/media/app-page.png b/docs/integrate/get-started/authentication/media/app-page.png new file mode 100644 index 00000000000..767f8f5f60a Binary files /dev/null and b/docs/integrate/get-started/authentication/media/app-page.png differ diff --git a/docs/integrate/get-started/authentication/media/app-settings-new.png b/docs/integrate/get-started/authentication/media/app-settings-new.png new file mode 100644 index 00000000000..73472310f7a Binary files /dev/null and b/docs/integrate/get-started/authentication/media/app-settings-new.png differ diff --git a/docs/integrate/get-started/authentication/media/app-settings.png b/docs/integrate/get-started/authentication/media/app-settings.png deleted file mode 100644 index 3bbd8a995c7..00000000000 Binary files a/docs/integrate/get-started/authentication/media/app-settings.png and /dev/null differ diff --git a/docs/integrate/get-started/authentication/media/azdo-oauth-app-delete.png b/docs/integrate/get-started/authentication/media/azdo-oauth-app-delete.png new file mode 100644 index 00000000000..4dfc3d709a2 Binary files /dev/null and b/docs/integrate/get-started/authentication/media/azdo-oauth-app-delete.png differ diff --git a/docs/integrate/get-started/authentication/media/secret-regeneration-modal.png b/docs/integrate/get-started/authentication/media/secret-regeneration-modal.png new file mode 100644 index 00000000000..c86b6a967a1 Binary files /dev/null and b/docs/integrate/get-started/authentication/media/secret-regeneration-modal.png differ diff --git a/docs/integrate/get-started/authentication/media/sp-app-perms.png b/docs/integrate/get-started/authentication/media/sp-app-perms.png deleted file mode 100644 index 16483b406cd..00000000000 Binary files a/docs/integrate/get-started/authentication/media/sp-app-perms.png and /dev/null differ diff --git a/docs/integrate/get-started/authentication/media/users-hub-sps.png b/docs/integrate/get-started/authentication/media/users-hub-sps.png index aee50842f00..3329f589f58 100644 Binary files a/docs/integrate/get-started/authentication/media/users-hub-sps.png and b/docs/integrate/get-started/authentication/media/users-hub-sps.png differ diff --git a/docs/integrate/get-started/authentication/oauth.md b/docs/integrate/get-started/authentication/oauth.md index 5e83b4a86d6..d0e14ea50dd 100644 --- a/docs/integrate/get-started/authentication/oauth.md +++ b/docs/integrate/get-started/authentication/oauth.md @@ -7,301 +7,63 @@ ms.subservice: azure-devops-security monikerRange: 'azure-devops' ms.author: chcomley author: chcomley -ms.date: 07/15/2022 +ms.date: 10/21/2024 --- # Authorize access to REST APIs with OAuth 2.0 [!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] -In this article, learn how to authenticate your web app users for REST API access, so your app doesn't continue to ask for usernames and passwords. +Learn how to authenticate your web app users for REST API access, so your app doesn't continue to ask for usernames and passwords. > [!NOTE] -> The following guidance is intended for Azure DevOps Services users since OAuth 2.0 is not supported on Azure DevOps Server. [Client Libraries](../../concepts/dotnet-client-libraries.md) are a series of packages built specifically for extending Azure DevOps Server functionality. For on-premises users, we recommend using [Client Libraries](../../concepts/dotnet-client-libraries.md), Windows Auth, or [Personal Access Tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) to authenticate on behalf of a user. +> The following guidance is intended for Azure DevOps Services users since OAuth 2.0 isn't supported on Azure DevOps Server. Client Libraries are a series of packages built specifically for extending Azure DevOps Server functionality. For on-premises users, we recommend using [Client Libraries](../../concepts/dotnet-client-libraries.md), Windows Auth, or [personal access tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) to authenticate on behalf of a user. -Azure DevOps Services uses the [OAuth 2.0 protocol](https://oauth.net/2/) to authorize your app for a user and generate an access token. Use this token when you call the REST APIs from your application. +## About OAuth 2.0 -When you call Azure DevOps Services APIs for that user, use that user's access token. Access tokens expire, so refresh the access token if it's expired. +Azure DevOps Services uses the [OAuth 2.0 protocol](https://oauth.net/2/) to authorize your app for a user and generate an access token. Use this token when you call the REST APIs from your application. When you call Azure DevOps Services APIs for that user, use that user's access token. Access tokens expire, so refresh the access token if expired. :::image type="content" source="media/oauth-overview.png" alt-text="Process to get authorization."::: -For a C# example of the overall flow, see [vsts-auth-samples](https://github.com/Microsoft/vsts-auth-samples/tree/master/OAuthWebSample). - -> [!NOTE] -> You can register an application within your instance of Azure Active Directory (Azure AD). For more information, see [OAuth 2.0 authentication with Azure AD](/azure/active-directory/fundamentals/auth-oauth2) and [OpenID Connect protocol](/azure/active-directory/develop/v2-protocols-oidc). - -## 1. Register your app - -1. Go to `https://app.vsaex.visualstudio.com/app/register` to register your app. - -2. Select the [scopes](#scopes) that your application needs, and then use the same scopes when you [authorize your app](#2-authorize-your-app). If you registered your app using the preview APIs, re-register because the scopes that you used are now deprecated. -3. Select **Create application**. - - The application settings page displays. - - :::image type="content" source="media/app-settings.png" alt-text="Screenshot showing Applications settings for your app."::: - - - When Azure DevOps Services presents the authorization approval page to your user, it uses your company name, app name, and descriptions. It also uses the URLs for your company web site, app website, and terms of service and privacy statements. - - :::image type="content" source="media/grant-access.png" alt-text="Screenshot showing Visual Studio Codespaces authorization page with your company and app information."::: - - - When Azure DevOps Services asks for a user's authorization, and the user grants it, the user's browser gets redirected to your authorization callback URL with the authorization code. - The callback URL must be a secure connection (https) to transfer the code back to the app and exactly match the URL registered in your app. If it doesn't, a 400 error page is displayed instead of a page asking the user to grant authorization to your app. - -4. Call the authorization URL and pass your app ID and authorized scopes when you want to have a user authorize your app to access their organization. -Call the access token URL when you want to get an access token to call an Azure DevOps Services REST API. - -The settings for each app that you register are available from your profile `https://app.vssps.visualstudio.com/profile/view`. - -## 2. Authorize your app - -1. If your user hasn't yet authorized your app to access their organization, call the authorization URL. It calls you back with an authorization code, if the user approves the authorization. - -```no-highlight -https://app.vssps.visualstudio.com/oauth2/authorize - ?client_id={app ID} - &response_type={Assertion} - &state={state} - &scope={scope} - &redirect_uri={callback URL} -``` - -Parameter | Type | Notes ---------------|--------|---------------------------- -client_id | GUID | The ID assigned to your app when it was registered. -response_type | string | `Assertion` -state | string | Can be any value. Typically a generated string value that correlates the callback with its associated authorization request. -scope | string | Scopes registered with the app. Space separated. See [available scopes](#scopes). -redirect_uri | URL | Callback URL for your app. **Must exactly match the URL registered with the app**. - -2. Add a link or button to your site that takes the user to the Azure DevOps Services authorization endpoint: - -```no-highlight -https://app.vssps.visualstudio.com/oauth2/authorize - ?client_id=88e2dd5f-4e34-45c6-a75d-524eb2a0399e - &response_type=Assertion - &state=User1 - &scope=vso.work%20vso.code_write - &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback -``` - -Azure DevOps Services asks the user to authorize your app. - -Assuming the user accepts, Azure DevOps Services redirects the user's browser to your callback URL, including a short-lived authorization code and the state value provided in the authorization URL: - -```no-highlight -https://fabrikam.azurewebsites.net/myapp/oauth-callback - ?code={authorization code} - &state=User1 -``` - -## 3. Get an access and refresh token for the user - -Use the authorization code to request an access token (and refresh token) for the user. Your service must make a service-to-service HTTP request to Azure DevOps Services. - -### URL - authorize app - -```no-highlight -POST https://app.vssps.visualstudio.com/oauth2/token -``` - -### HTTP request headers - authorize app - -| Header | Value -|-------------------|------------------------------------------------------------------ -| Content-Type | `application/x-www-form-urlencoded` - -```no-highlight -Content-Type: application/x-www-form-urlencoded -``` - -### HTTP request body - authorize app - -```no-highlight -client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2} -``` - -Replace the placeholder values in the previous sample request body: - -* **{0}**: URL encoded client secret acquired when the app was registered -* **{1}**: URL encoded "code" provided via the `code` query parameter to your callback URL -* **{2}**: callback URL registered with the app - -#### C# example to form the request body - authorize app - -```no-highlight -public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl) -{ - return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}", - HttpUtility.UrlEncode(appSecret), - HttpUtility.UrlEncode(authCode), - callbackUrl - ); -} -``` - -### Response - authorize app - -```json -{ - "access_token": { access token for the user }, - "token_type": { type of token }, - "expires_in": { time in seconds that the token remains valid }, - "refresh_token": { refresh token to use to acquire a new access token } -} -``` +## Available OAuth models > [!IMPORTANT] -> Securely persist the **refresh_token** so your app doesn't need to prompt the user to authorize again. Access tokens expire quickly and shouldn't be persisted. - -## 4. Use the access token - -To use an access token, include it as a bearer token in the Authorization header of your HTTP request: - -``` -Authorization: Bearer {access_token} -``` - -For example, the HTTP request to [get recent builds](https://visualstudio.com/api/build-release/builds.md#getalistofbuilds) for a project: - -```no-highlight -GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0 -Authorization: Bearer {access_token} -``` +> When creating a new OAuth 2.0 app, use Microsoft Entra ID OAuth. Azure DevOps OAuth 2.0 is slated for deprecation in 2026. Starting April 2025, we will stop accepting new Azure DevOps OAuth apps. [Learn more in our blog post](https://devblogs.microsoft.com/devops/no-new-azure-devops-oauth-apps-beginning-february-2025/). -## Refresh an expired access token + -If a user's access token expires, you can use the refresh token that they acquired in the authorization flow to get a new access token. It's like the original process for exchanging the authorization code for an access and refresh token. +### Microsoft Entra ID OAuth -### URL - refresh token +Building on a new platform can be overwhelming. In [this guide to building a Microsoft Entra app for Azure DevOps](entra-oauth.md), we collect helpful links that might be useful to kicking off the OAuth app development process on Microsoft Entra. For folks migrating from Azure DevOps OAuth to Microsoft Entra OAuth, we offer tips to consider during your migration effort. -```no-highlight -POST https://app.vssps.visualstudio.com/oauth2/token -``` +### Azure DevOps OAuth -### HTTP request headers - refresh token - -| Header | Value -|-------------------|------------------------------------------------------------------ -| Content-Type | `application/x-www-form-urlencoded` -| Content-Length | Calculated string length of the request body (see the following example) - -```no-highlight -Content-Type: application/x-www-form-urlencoded -Content-Length: 1654 -``` - -### HTTP request body - refresh token - -```no-highlight -client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2} - -``` - -Replace the placeholder values in the previous sample request body: - -* **{0}**: URL encoded client secret acquired when the app was registered -* **{1}**: URL encoded refresh token for the user -* **{2}**: callback URL registered with the app - -### Response - refresh token - -```json -{ - "access_token": { access token for this user }, - "token_type": { type of token }, - "expires_in": { time in seconds that the token remains valid }, - "refresh_token": { new refresh token to use when the token has timed out } -} -``` - -> [!IMPORTANT] -> A new refresh token gets issued for the user. Persist this new token and use it the next time you need to acquire a new access token for the user. - - +For existing apps, see the [Azure DevOps OAuth app guide](./azure-devops-oauth.md). You can also [manage which Azure DevOps apps are authorized](../../../organizations/settings/manage-authorizations.md) to access your resources. ## Scopes -> [!IMPORTANT] -> Scopes only enable access to REST APIs and select Git endpoints. SOAP API access isn't supported. - -[!INCLUDE [scopes table](../../includes/scopes.md)] - -[Register your app](#1-register-your-app) and use scopes to indicate which permissions in Azure DevOps Services that your app requires. -When your users authorize your app to access their organization, they authorize it for those scopes. -[Requesting the authorization](#2-authorize-your-app) passes the same scopes that you registered. +Developers are expected to specify what scopes they require from their users. The same scopes are available on both OAuth models. The following scopes are available via delegated (on-behalf-of user) flows only. +To find out what scopes you need for your app, look under the `scopes` header on the API Reference page for each API you're using. -For more information, see [Create work item tracking/attachments](/rest/api/azure/devops/wit/attachments/create?view=azure-devops-rest-6.0&preserve-view=true). +Some scopes might be inclusive of other scopes, for example, `vso.code_manage` includes `vso.code_write`. For example, many scopes inherit from `vso.profile`. Consider what is the minimal number of scopes you need when requesting scope consent from users. -## Samples +> [!NOTE] +> Scopes only enable access to REST APIs and select Git endpoints. SOAP API access isn't supported. -You can find a C# sample that implements OAuth to call Azure DevOps Services REST APIs in our [C# OAuth GitHub Sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/OAuthWebSample). +[!INCLUDE [scopes table](../../includes/scopes.md)] ## Frequently asked questions (FAQs) - - -### Q: Can I use OAuth with my mobile phone app? - -A: No. Azure DevOps Services only supports the web server flow, -so there's no way to implement OAuth, as you can't securely store the app secret. - -### Q: What errors or special conditions do I need to handle in my code? - -A: Make sure that you handle the following conditions: - -* If your user denies your app access, no authorization code gets returned. Don't use the authorization code without checking for denial. -* If your user revokes your app's authorization, the access token is no longer valid. When your app uses the token to access data, a 401 error returns. Request authorization again. - -### Q: I want to debug my web app locally. Can I use localhost for the callback URL when I register my app? - -A: Yes. Azure DevOps Services now allows localhost in your callback URL. Ensure you use `https://localhost` as the beginning of your callback URL when you register your app. - -### Q: I get an HTTP 400 error when I try to get an access token. What might be wrong? - -A: Check that you set the content type to application/x-www-form-urlencoded in your request header. - -### Q: I get an HTTP 401 error when I use an OAuth-based access token, but a PAT with the same scope works fine. Why? - -A: Verify that **Third-party application access via OAuth** hasn't been disabled by your organization's admin at `https://dev.azure.com/{your-org-name}/_settings/organizationPolicy`. - -In this scenario, the flow to authorize an app and generate an access token works, but all REST APIs return only an error, such as `TF400813: The user "" is not authorized to access this resource.` - -### Q: Can I use OAuth with the SOAP endpoints and REST APIs? - -A: No. OAuth is only supported in the REST APIs at this point. - -### Q: How can I get attachments detail for my work item using Azure DevOps REST APIs? - -A: First, get the work item details with [Work items - Get work item](/rest/api/azure/devops/wit/work-items?preserve-view=true&view=azure-devops-rest-6.1) REST API: - -```REST -GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id} -``` - -To get the attachments details, you need to add the following parameter to the URL: - -```REST -$expand=all -``` - -With the results, you get the relations property. There you can find the attachments URL, and within the URL you can find the ID. For example: - -```REST API -$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=5.0 - -$workItem = Invoke-RestMethod -Uri $url -Method Get -ContentType application/json - -$split = ($workitem.relations.url).Split('/') +#### Q: Can I use OAuth with my mobile phone app? -$attachmentId = $split[$split.count - 1] +A: No. Azure DevOps Services only supports the web server flow, so there's no way to implement OAuth, as you can't securely store the app secret. -# Result: 1244nhsfs-ff3f-25gg-j64t-fahs23vfs -``` +#### Q: Can I use OAuth with the SOAP endpoints and REST APIs? - +A: No. OAuth is only supported in the REST APIs. ## Related articles * [Choosing the right authentication method](authentication-guidance.md) -* [Default permissions and access for Azure DevOps](../../../organizations/security/permissions-access.md) +* [Building for Azure DevOps with Microsoft Entra OAuth apps](entra-oauth.md) +* [Using Azure DevOps OAuth](azure-devops-oauth.md) diff --git a/docs/integrate/get-started/authentication/service-principal-managed-identity.md b/docs/integrate/get-started/authentication/service-principal-managed-identity.md index 45c37a3075a..296a494c189 100644 --- a/docs/integrate/get-started/authentication/service-principal-managed-identity.md +++ b/docs/integrate/get-started/authentication/service-principal-managed-identity.md @@ -1,179 +1,207 @@ --- -title: Use Azure Active Directory service principals & managed identities +title: Use service principals & managed identities titleSuffix: Azure DevOps -ms.custom: description: Learn how to add and manage service principals and managed identities in your Azure DevOps organizations. ms.subservice: azure-devops-security ms.assetid: ms.topic: how-to +ms.custom: arm2024 ms.author: wonga author: wonga -ms.date: 04/07/2023 -monikerRange: '<= azure-devops' +ms.date: 01/08/2025 +monikerRange: 'azure-devops' --- -# Use Azure Active Directory service principals & managed identities +# Use service principals & managed identities in Azure DevOps [!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] -You can now add Azure Active Directory (Azure AD) service principals and managed identities to your Azure DevOps organizations to grant access to your organization resources. For many teams, this feature can be a viable and preferred alternative to [personal access tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) when authenticating applications that power automation workflows for your company. - > [!NOTE] -> Service principals and managed identities support is currently in public preview. They're only available to organizations that are connected to Azure AD. +> Azure Active Directory (Azure AD) is now Microsoft Entra ID. For more information, see [New name for Azure AD](/entra/fundamentals/new-name). + +Add [Microsoft Entra](entra.md) service principals and managed identities as application identities into your Azure DevOps Services organizations, which grant them access to your organization resources. For many teams, this feature can be a viable and preferred alternative to [personal access tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) when you authenticate applications that power automation workflows in your company. ## About service principals and managed identities -[Service principals](/azure/active-directory/fundamentals/service-accounts-principal) are security objects within an Azure AD application that define what an application can do in a given tenant. They're set up in the Azure portal during the application registration process and configured to access Azure resources, like Azure DevOps. By adding service principals into your organization and setting up permissions on top of them, we can determine whether a service principal is authorized to access your organizational resources and which ones. +[Service principals](/azure/active-directory/fundamentals/service-accounts-principal) are security objects within a Microsoft Entra application that define what an application can do in a given tenant. They're set up in the Azure portal during the application registration process and configured to access Azure resources, like Azure DevOps. By adding service principals into your organization and setting up permissions on top of them, we can determine whether a service principal is authorized to access your organizational resources and which ones. -[Managed identities](/azure/active-directory/fundamentals/service-accounts-managed-identities) are another Azure AD feature that act similarly to an application's service principals. These objects provide identities for Azure resources and allow an easy way for services that support Azure AD authentication to share credentials. They're an appealing option because Azure AD takes care of credential management and rotation. While setup for a managed identity may look different on the Azure portal, Azure DevOps treats both security objects the same as a new identity in an organization with defined permissions. Throughout the rest of this article, we refer to managed identities and service principals interchangeably as service principal, unless specified. +[Managed identities](/azure/active-directory/fundamentals/service-accounts-managed-identities) is another Microsoft Entra feature that acts similarly to an application's service principals. These objects provide identities for Azure resources and allow an easy way for services that support Microsoft Entra authentication to share credentials. They're an appealing option because Microsoft Entra ID takes care of credential management and rotation. While setup for a managed identity might look different on the Azure portal, Azure DevOps treats both security objects the same as a new application identity in an organization with defined permissions. Throughout the rest of this article, we refer to managed identities and service principals interchangeably as service principal, unless specified. Use the following steps to authenticate these identities to Azure DevOps to allow them to perform actions on behalf of themselves. ## Configure managed identities and service principals -Your implementation may vary, but at a high-level, the following steps help you start using service principals in your workflow. Consider looking at one of our [sample apps](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ServicePrincipalsSamples) to follow along with an example on your own. +Your implementation might vary, but at a high-level, the following steps help you start using service principals in your workflow. To follow along, consider looking at one of our [sample apps](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ServicePrincipalsSamples). ### 1. Create a new managed identity or application service principal -Create an [application service principal](#create-an-application-service-principal) or a [managed identity](#create-a-managed-identity) in the Azure portal. +Create an [application service principal](#option-1-create-an-application-service-principal) or a [managed identity](#option-2-create-a-managed-identity) in the Azure portal. -#### Create an application service principal +#### Option 1: Create an application service principal -When you create a new application registration, an application object is created in Azure AD. The **application service principal** is a representation of this application object for a given tenant. When you register an application as a multi-tenant application, there's a unique service principal object that represents the application object for every tenant the application is added to. +When you create a new application registration, an application object is created in Microsoft Entra ID. The **application service principal** is a representation of this application object for a given tenant. When you register an application as a multitenant application, there's a unique service principal object that represents the application object for every tenant the application is added to. -Further information: -* [Application and service principal objects in Azure Active Directory](/azure/active-directory/develop/app-objects-and-service-principals) -* [Securing service principals](/azure/active-directory/fundamentals/service-accounts-principal) -* [Use the portal to create an Azure AD application and service principal that can access resources](/azure/active-directory/develop/howto-create-service-principal-portal) +For more information, see the following articles: +* [Application and service principal objects in Microsoft Entra ID](/azure/active-directory/develop/app-objects-and-service-principals) +* [Secure your service principals](/azure/active-directory/fundamentals/service-accounts-principal) +* [Use the portal to create a Microsoft Entra application and service principal that can access resources](/azure/active-directory/develop/howto-create-service-principal-portal) -> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWWY8q] - -#### Create a managed identity +#### Option 2: Create a managed identity Creating managed identities in the Azure portal differs significantly from setting up applications with service principals. Before you begin the creation process, you must first consider which type of managed identity you want to create: -* **System-assigned managed identity:** Some Azure services allow you to enable a managed identity directly on a service instance. When you enable a system-assigned managed identity, an identity is created in Azure AD. The identity is tied to the lifecycle of that service instance. When the resource is deleted, Azure automatically deletes the identity for you. By design, only that Azure resource can use this identity to request tokens from Azure AD. -* **User-assigned managed identity** You may also create a managed identity as a standalone Azure resource by creating a user-assigned managed identity and assign it to one or more instances of an Azure service. For user-assigned managed identities, the identity is managed separately from the resources that use it. +* **System-assigned managed identity:** Some Azure services allow you to enable a managed identity directly on a service instance. When you enable a system-assigned managed identity, an identity is created in Microsoft Entra ID. The identity is tied to the lifecycle of that service instance. When the resource is deleted, Azure automatically deletes the identity for you. By design, only that Azure resource can use this identity to request tokens from Microsoft Entra ID. +* **User-assigned managed identity** You might also create a managed identity as a standalone Azure resource by creating a user-assigned managed identity and assign it to one or more instances of an Azure service. For user-assigned managed identities, the identity is managed separately from the resources that use it. For more information, see the following articles and video: -* [What are managed identities for Azure resources?](/azure/active-directory/managed-identities-azure-resources/overview) +* [Learn about managed identities for Azure resources](/azure/active-directory/managed-identities-azure-resources/overview) * [Manage user-assigned managed identities](/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities) -* [Configure managed identities for Azure resources on a VM using the Azure portal](/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm) +* [Configure managed identities for Azure resources on a virtual machine using the Azure portal](/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm) -> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWWL8K] +> [!VIDEO https://learn-video.azurefd.net/vod/player?id=b9cf4e49-db98-4247-8770-b8707b043f17] -### 2. Add and manage service principals in an Azure DevOps organization +### 2. Add a service principal to an Azure DevOps organization -Once you configure the service principals in the Azure AD portal, you must do the same in Azure DevOps by adding the service principals to your organization. You can add them through the [Users page](../../../organizations/accounts/add-organization-users.md) or with the [ServicePrincipalEntitlements APIs](/rest/api/azure/devops/memberentitlementmanagement/service-principal-entitlements?view=azure-devops-rest-7.1&preserve-view=true). Since they can't sign in interactively, a user account that can add users to an organization, project, or team must add them. Such users include **Project Collection Administrators** (PCA) or **Project Administrators and Team Administrators** when the ["Allow team and project administrators to invite new users" policy](/azure/devops/organizations/security/restrict-invitations) is enabled. +Once you configure the service principals in the Microsoft Entra admin center, you must do the same in Azure DevOps by adding the service principals to your organization. You can add them through the [Users page](../../../organizations/accounts/add-organization-users.md) or with the [ServicePrincipalEntitlements APIs](/rest/api/azure/devops/memberentitlementmanagement/service-principal-entitlements?view=azure-devops-rest-7.1&preserve-view=true). Since they can't sign in interactively, a user account that can add users to an organization, project, or team must add them. Such users include **Project Collection Administrators** (PCA) or **Project Administrators and Team Administrators** when the ["Allow team and project administrators to invite new users" policy](/azure/devops/organizations/security/restrict-invitations) is enabled. > [!TIP] -> To add a service principal to the organization, enter the application or managed identity's display name. If you choose to add a service principal programmatically through the [`ServicePrincipalEntitlements` API](/rest/api/azure/devops/memberentitlementmanagement/service-principal-entitlements?view=azure-devops-rest-7.1&preserve-view=true), make sure to pass in the **service principal's object id** and not the application's object id. +> To add a service principal to the organization, enter the application or managed identity's display name. If you choose to add a service principal programmatically through the [`ServicePrincipalEntitlements` API](/rest/api/azure/devops/memberentitlementmanagement/service-principal-entitlements?view=azure-devops-rest-7.1&preserve-view=true), make sure to pass in the **service principal's object id** and not the application's object ID. If you're a PCA, you can also grant a service principal access to specific projects and assign a license. If you're not a PCA, you must reach out to the PCA to update any project memberships or license access levels. ![Screenshot of service principals and managed identities in the Users Hub.](./media/users-hub-sps.png) > [!NOTE] -> You can only add a managed identity for the tenant your organization is connected to. If you would like to access a managed identity in a different tenant, see the [workaround we've included in the FAQ](#q-can-i-add-a-managed-identity-from-a-different-tenant-to-my-organization). +> You can only add a managed identity or service principal for the tenant your organization is connected to. Service principals can be made multitenant to access multiple tenants at once. Managed identities can only belong to a single tenant. To access a managed identity in a different tenant, see the [workaround in the FAQ](#q-can-i-add-a-managed-identity-from-a-different-tenant-to-my-organization). +### 3. Set permissions on a service principal After your service principals are added to the organization, you can treat them similarly to standard user accounts. You can assign permissions directly on a service principal, add it to security groups and teams, assign it to any access level, and remove it from the organization. You can also use the [`Service Principal Graph APIs`](/rest/api/azure/devops/graph/service-principals?view=azure-devops-rest-7.1&preserve-view=true) to perform CRUD operations on service principals. -> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWWG70] +> [!VIDEO https://learn-video.azurefd.net/vod/player?id=e8ee6f58-3939-4170-b112-0ca1b39b0298] + +Setting these permissions might differ from how you're used to setting up application permissions in a Microsoft Entra application for other Azure resources. Azure DevOps doesn't rely on the ["Application permissions" setup](/entra/identity-platform/permissions-consent-overview#types-of-permissions) available to application registrations through the Azure portal. These application permissions apply permissions to a service principal across all organizations tied to a tenant and have no knowledge of the organization, project, or object permissions available in Azure DevOps. To offer service principals more granular permissions, we rely on our own permissions model instead of Microsoft Entra IDs. +### 4. Manage a service principal Management of service principals differs from user accounts in the following key ways: * Service principals don't have emails and as such, they can't be invited to an organization via email. * Group rules for licensing currently don't apply to service principals. If you want to assign an access level to a service principal, it's best to do so directly. -* While service principals can be added to Azure AD groups (in the Azure portal), we have a current technical limitation preventing us from being able to display them in a list of Azure AD group members. This limitation isn't true for Azure DevOps groups. That being said, a service principal still inherits any group permissions set on top of an Azure AD group they belong to. -* Not all users in an Azure AD group are immediately part of an Azure DevOps organization just because an admin creates a group and adds an Azure AD group to it. We have a process called "materialization" that happens once a user from an Azure AD group signs in to the organization for the first time. A user signing into an organization allows us to determine which users should be granted a license. Since sign-in isn't possible for service principals, an admin must explicitly add it to an organization as described earlier. +* Service principals can be added to Microsoft Entra groups (in the Azure portal). There currently exists a technical limitation preventing us from being able to display them in a list of Microsoft Entra group members. This limitation isn't true for Azure DevOps groups. That being said, a service principal still inherits any group permissions set on top of a Microsoft Entra group they belong to. +* Users in a Microsoft Entra group aren't part of an Azure DevOps organization immediately just because an admin creates a group and adds a Microsoft Entra group to it. We have a process called "materialization" that happens once a user from a Microsoft Entra group signs in to the organization for the first time. A user signing into an organization allows us to determine which users should be granted a license. Since sign-in isn't possible for service principals, an admin must explicitly add it to an organization as described earlier. * You can't modify a service principal’s display name or avatar on Azure DevOps. -* A service principal counts as a license for each organization it's added to, even if [multi-organization billing](../../../organizations/billing/buy-basic-access-add-users.md?#pay-for-a-user-once-across-multiple-organizations) is selected. +* Service principals get licenses in each organization they get added to, even if [multi-organization billing](../../../organizations/billing/buy-basic-access-add-users.md?#pay-for-a-user-once-across-multiple-organizations) is selected. -### 3. Access Azure DevOps resources with an Azure AD token +### 5. Get a Microsoft Entra ID token -#### Get an Azure AD token -Acquiring an access token for a managed identity can be done by following along with the Azure AD documentation. For more information, see the examples for [service principals](/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#get-a-token) and [managed identities](/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token). +#### (a) Acquire a Microsoft Entra ID token programmatically -The returned access token is a JWT with the defined roles, which can be used to access organization resources using the token as *Bearer*. +Acquiring an access token for a managed identity can be done by following along with the Microsoft Entra ID documentation. See the examples for [service principals](/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#get-a-token) and [managed identities](/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token). -#### Use the Azure AD token to authenticate to Azure DevOps resources -In the following video example, we move from authenticating with a PAT to using a token from a service principal. We start by using a client secret for authentication, then move to using a client certificate. +The returned access token is a JSON web token (JWT) with the defined roles, which can be used to access organization resources using the token as *Bearer*. -> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWWNVM] +#### (b) Acquire a Microsoft Entra ID token with the Azure CLI +For ad-hoc operations, it might be easier to acquire a one-off Microsoft Entra ID token through the Azure CLI. This approach is preferred for operations that don't need a persistent token to be regularly rotated, like API calls or git clone operations. -Another example demonstrates how to connect to Azure DevOps using a User Assigned Managed Identity within an Azure Function. +**Prerequisites** +* **Azure tenant id and subscription id**: Make sure the subscription is associated with the tenant connected to the Azure DevOps organization you're trying to access. If you don't know your tenant or subscription ID, you can find it in the [Azure portal](/azure/azure-portal/get-subscription-tenant-id). +* **Azure app client ID and client secret** +* [**Azure CLI**](/cli/azure/install-azure-cli) -> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWWL8L] +These instructions are provided by the Databricks docs and more details can be found on [their page](/azure/databricks/dev-tools/service-prin-aad-token). -Follow along with these examples by finding the app code in our [collection of sample apps](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ServicePrincipalsSamples). + 1. Sign in to the Azure CLI as the service principal using the `az devops login` command. + 2. Follow the on-screen instructions and finish signing in. + ``` powershell + # To authenticate a service principal with a password or cert: + az login --service-principal -u -p --tenant -Service principals can be used to call Azure DevOps REST APIs and do most actions, but it's limited from the following operations: -* Service principals can't be Organization Owners or create organizations. -* Service principals can't create tokens, like [personal access tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) or [SSH Keys](../../../repos/git/use-ssh-keys-to-authenticate.md). They can generate their own Azure AD tokens and these tokens can be used to call Azure DevOps REST APIs. -* We don't support [Azure DevOps OAuth](./oauth.md) for service principals. + # To authenticate a managed identity: + az login --identity + ``` -## FAQs + 3. Set the right correct subscription for the signed-in service principal by entering the command: + ``` powershell + az account set -s + ``` -### Q: Why should I use a service principal or a managed identity instead of a PAT? + 4. Generate a Microsoft Entra ID access token with the `az account get-access-token` the Azure DevOps resource ID: `499b84ac-1321-427f-aa17-267ca6975798`. + ``` powershell + $accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv + ``` -A: Many of our customers seek out a service principal or managed identity to replace an existing PAT (personal access token). Such PATs often belong to a service account (shared team account) that is using them to authenticate an application with Azure DevOps resources. PATs must be laboriously rotated every so often (minimum 180 days). As PATs are simply bearer tokens, meaning token strings that represent a user’s username and password, they're incredibly risky to use as they can easily fall into the wrong person’s hands. Azure AD tokens expire every hour and must be regenerated with a refresh token to get a new access token, which limits the overall risk factor when leaked. + 5. Now, you can use `az cli` commands per usual. Let's try to call an Azure DevOps API by passing it in the headers as a `Bearer` token: + ```powershell + $apiVersion = "7.1-preview.1" + $uri = "https://dev.azure.com/${yourOrgname}/_apis/projects?api-version=${apiVersion}" + $headers = @{ + Accept = "application/json" + Authorization = "Bearer $accessToken" + } + Invoke-RestMethod -Uri $uri -Headers $headers -Method Get | Select-Object -ExpandProperty value ` | Select-Object id, name + ``` -### Q: What are the rate limits on service principals and managed identities? -A: At this time, service principals and managed identities have the same [rate limits](../../concepts/rate-limits.md) as users. +> [!NOTE] +> Use the Azure DevOps application ID, not our resource URI, for generating tokens. -### Q: Will using this feature cost more? +### 6. Use the Microsoft Entra ID token to authenticate to Azure DevOps resources -A: Service principals and managed identities are priced similarly as users, based on the access level. One notable change pertains to how we treat "multi-org billing" for service principals. Users get counted as only one license, no matter how many organizations they're in. Service principals get counted as one license per each organization the user's in. This scenario is similar to standard "user assignment-based billing". +In the following video example, we move from authenticating with a PAT to using a token from a service principal. We start by using a client secret for authentication, then move to using a client certificate. -### Q: Can I use a service principal or managed identity with Azure CLI? +> [!VIDEO https://learn-video.azurefd.net/vod/player?id=8397f848-b946-4c30-8d0c-78aa4784a549] -A: Yes! Anywhere that asks for PATs in the [Azure CLI](/cli/azure/authenticate-azure-cli) can also accept [Azure AD access tokens](#get-an-azure-ad-token). See these examples for how you might pass an Azure AD token in to authenticate with CLI. +Another example demonstrates how to connect to Azure DevOps using a User Assigned Managed Identity within an Azure Function. -```powershell -# To authenticate with a command: After typing this command, the az devops login will prompt you to enter a token. You can add an Azure AD token too! Not just a PAT. -az devops login +> [!VIDEO https://learn-video.azurefd.net/vod/player?id=f4a20e00-c2df-49cc-9b86-7454bd84b9ce] -# To authenticate a service principal with a password or cert: -az login --service-principal -u -p --tenant +Follow along with these examples by finding the app code in our [collection of sample apps](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ServicePrincipalsSamples). -# To authenticate a managed identity: -az login --identity -``` +Some common scenarios for authenticating with service principals besides making Azure DevOps REST API calls can be found in these docs: +* Connect your service principal to a NuGet feed with [Nuget.exe](../../../artifacts/nuget/nuget-exe.md) or [dotnet](../../../artifacts/nuget/dotnet-setup.md). +* [Publish extensions to the Visual Studio Marketplace via command line](../../../extend/publish/command-line.md) with your service principal. +* Create [secret-free service connections in Azure Pipelines](../../../pipelines/library/connect-to-azure.md) backed by service principals or managed identities. +* [Make clones of repos using a service principal with Git Credential Manager](../../../repos/git/set-up-credential-managers.md) -Now, let's get an Azure AD token and try to call an Azure DevOps API by passing it in the headers as a `Bearer` token: -```powershell -Write-Host "Obtain access token for Service Connection identity..." -$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv - -Write-Host "Use access token with Azure DevOps REST API to list projects in the organization..." -$apiVersion = "7.1-preview.1" -$uri = "https://dev.azure.com/${yourUsername}/_apis/projects?api-version=${apiVersion}" -$headers = @{ - Accept = "application/json" - Authorization = "Bearer $accessToken" -} -Invoke-RestMethod -Uri $uri -Headers $headers -Method Get | Select-Object -ExpandProperty value ` | Select-Object id, name -``` +## How service principals differ from users + +* You can't modify a service principal’s display name or avatar on Azure DevOps. +* A service principal counts as a license for each organization it joins, even with [multi-organization billing](../../../organizations/billing/buy-basic-access-add-users.md?#pay-for-a-user-once-across-multiple-organizations). +* Service principals can't be organization owners or create organizations. +* Service principals can't create tokens like [personal access tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) or [SSH Keys](../../../repos/git/use-ssh-keys-to-authenticate.md). They can generate their own Microsoft Entra ID tokens to call Azure DevOps REST APIs. +* Service principals don't support [Azure DevOps OAuth](./oauth.md). + +## FAQs + +#### Q: Why should I use a service principal or a managed identity instead of a PAT? + +A: Many of our customers seek out a service principal or managed identity to replace an existing PAT (personal access token). Such PATs often belong to a service account (shared team account) that is using them to authenticate an application with Azure DevOps resources. PATs must be laboriously rotated every so often (minimum 180 days). Improperly stored PATs can fall into the wrong hands and last the duration of its often longer lifespan. Microsoft Entra tokens expire every hour, limiting the overall risk factor when leaked. For common PAT scenarios, we [share some examples on how you might explore using a Microsoft Entra token instead](entra.md#replace-pats-with-microsoft-entra-tokens). + +You can't use a service principal to create a personal access token. + +#### Q: What are the rate limits on service principals and managed identities? + +A: Service principals and managed identities have the same [rate limits](../../concepts/rate-limits.md) as users. + +#### Q: Will using this feature cost more? -Now, you can use `az cli` commands per usual. +A: Service principals and managed identities are priced similarly as users, based on the access level. One notable change pertains to how we treat "multi-org billing" for service principals. Users get counted as only one license, no matter how many organizations they're in. Service principals get counted as one license per each organization the user's in. This scenario is similar to standard "user assignment-based billing." -### Q: Can I add a managed identity from a different tenant to my organization? +#### Q: Can I add a managed identity from a different tenant to my organization? -A: You can only add a managed identity from the same tenant that your organization is connected to. However, we have a workaround that allows you to set up a managed identity in the "resource tenant", where are all of your resources are. Then, you can enable it to be used by a service principal in the "target tenant", where your organization is connected. Do the following steps as a workaround: +A: You can only add a managed identity from the same tenant that your organization is connected to. However, we have a workaround that allows you to set up a managed identity in the "resource tenant," where are all of your resources are. Then, you can enable it to be used by a service principal in the "target tenant," where your organization is connected. Do the following steps as a workaround: 1. Create a [user-assigned managed identity](/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities) in Azure portal for your resource tenant. 2. Connect it to a [virtual machine and assign this managed identity](/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm) to it. -3. Create a [key vault](/azure/key-vault/general/quick-create-portal) and generate a [certificate](/azure/key-vault/certificates/quick-create-portal) (can't be of type "PEM"). When you generate this certificate, a secret with the same name is also generated, which we use later. -4. Grant access to the managed identity so that it can read the private key from the key vault. Create an access policy in the key vault with the "Get/List" permissions (under "Secret permissions" and search for the managed identity under "Select principal". -5. Download the created certificate in "CER" format, which ensures that it doesn't contain the private part of your certificate. +3. Create a [key vault](/azure/key-vault/general/quick-create-portal) and generate a [certificate](/azure/key-vault/certificates/quick-create-portal) (can't be of type `PEM`). When you generate this certificate, a secret with the same name is also generated, which we use later. +4. Grant access to the managed identity so that it can read the private key from the key vault. Create an access policy in the key vault with the "Get/List" permissions, under "Secret permissions" and search for the managed identity under "Select principal." +5. Download the created certificate in `CER` format, which ensures that it doesn't contain the private part of your certificate. 6. Create a new application registration in the target tenant. 7. Upload the downloaded certificate to this new application in the "Certificates & secrets" tab. -8. Add this application's service principal to the [Azure DevOps organization we want it to access](#2-add-and-manage-service-principals-in-an-azure-devops-organization), and remember to set up the service principal with any required permissions. -9. To get an Azure AD access token from this service principal that makes use of the managed identity certificate, see the following code sample: +8. Add this application's service principal to the Azure DevOps organization we want it to access and remember to set up the service principal with any required permissions. +9. Get a Microsoft Entra access token from this service principal that makes use of the managed identity certificate with this code sample: > [!NOTE] -> You must regularly rotate certificates, as always. +> Always regularly rotate your certificates. ```cs public static async Task GetSecret(string keyVaultName, string secretName) @@ -208,116 +236,32 @@ private static async Task GetAppRegistrationAADAccessToken } ``` -### Q: Can I use a service principal to do git operations, like clone a repo? - -A: See the following example of how we've passed an [Azure AD token](#get-an-azure-ad-token) of a service principal instead of a PAT to git clone a repo in a PowerShell script. - -```powershell -$ServicePrincipalAadAccessToken = 'Azure AD access token of a service principal' -git -c http.extraheader="AUTHORIZATION: bearer $ServicePrincipalAadAccessToken" clone https://dev.azure.com/{yourOrgName}/{yourProjectName}/_git/{yourRepoName} -``` -> [!TIP] -> To keep your token more secure, use credential managers so you don't have to enter your credentials every time. We recommend [Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager), which can accept [Azure AD tokens (that is, Microsoft Identity OAuth tokens)](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/environment.md#GCM_AZREPOS_CREDENTIALTYPE) instead of PATs if an environment variable is changed. - -A helpful tip on how to get the access token from the Azure CLI to call git fetch: - -1. Open the Git configuration of your repository: -```sh -git config -e -``` - -2. Add the following lines: -```sh -[credential] - helper = "!f() { test \"$1\" = get && echo \"password=$(az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv)\"; }; f" -``` - -3. Test that it works using: -```sh -GIT_TRACE=1 GCM_TRACE=1 GIT_CURL_VERBOSE=1 git fetch -``` -### Q: Can I use a service principal to connect to feeds? - -A: Yes, you can connect to any feed using Basic authentication by replacing the PAT secret value with an SP access token. In the following examples, we demonstrate how to connect with an Azure AD token for NuGet and Maven, but other feed types should also work. - -#### Npm project setup with Azure AD tokens -> [!NOTE] -> The vsts-npm-auth tool does not support Azure AD access tokens. - -1. Add a `.npmrc` to your project, in the same directory as your `package.json`. -``` -registry=https://pkgs.dev.azure.com/Fabrikam/_packaging/FabrikamFeed/npm/registry/ -always-auth=true -``` -2. Get an access token for your service principal or managed identity. -3. Add this code to your `${user.home}/.npmrc` and replace the placeholder `[AAD_SERVICE_PRINCIPAL_ACCESS_TOKEN]` with the access token from the previous step. -``` -//pkgs.dev.azure.com/Fabrikam/_packaging/FabrikamFeed/npm/:_authToken=[AAD_SERVICE_PRINCIPAL_ACCESS_TOKEN] -``` +## Potential errors -#### Maven project setup with Azure AD tokens -1. Add the repo to both your `pom.xml`'s `` and `` sections. - -```xml - - Fabrikam - https://pkgs.dev.azure.com/Fabrikam/_packaging/FabrikamFeed/maven/v1 - - true - - - true - - -``` -2. Get an access token for your Service Principal or Managed Identity. -3. Add or edit the `settings.xml` file in `${user.home}/.m2` and replace the placeholder `[AAD_SERVICE_PRINCIPAL_ACCESS_TOKEN]` with the access token from the previous step. -```xml - - - - Fabrikam - - Fabrikam - [AAD_SERVICE_PRINCIPAL_ACCESS_TOKEN] - - - -``` - -### Q: Can I use a service principal to publish extensions to the Visual Studio Marketplace? - -A: Yes. Do the following steps. - -1. Add a service principal as a member to a publisher account. You can get the service principal's ID from its profile using [Profiles - Get](/rest/api/azure/devops/profile/profiles/get). Then, you can [add the service principal as a member](/visualstudio/extensibility/walkthrough-publishing-a-visual-studio-extension#add-additional-users-to-manage-your-publisher-account) to the publisher using the ID from the previous step. - -2. Publish an extension via [TFX CLI](/azure/devops/extend/publish/command-line) using an SP. Execute the following [TFX CLI](https://github.com/microsoft/tfs-cli/blob/master/docs/extensions.md) command to use an SP access token: -``` -tfx extension publish --publisher my-publisher --vsix my-publisher.my-extension-1.0.0.vsix --auth-type pat -t -``` +### The Git repository with name or identifier '{`repoName`}' doesn't exist or you don't have permissions for the operation you're attempting. -## Potential errors +Ensure that the service principal has at least a ["Basic" license](/azure/devops/organizations/security/access-levels) to access repositories. A "Stakeholder" license isn't sufficient. ### Failed to create service principal with object ID '{`provided objectId`}' There's no service principal with the `provided objectId` in the tenant connected to your organization. One common reason is that you're passing in the object ID of the app registration, instead of the object ID of its service principal. Remember, a service principal is an object that represents the application for a given tenant, it's not the application itself. The `service principal object ID` can be found in your tenant's "Enterprise Applications" page. Search for the application's name and select on the "Enterprise Application" result that returns. This result is the page of the service principal / enterprise application and you can use the Object ID found on this page to create a service principal in Azure DevOps. -### Access Denied: {`ID of the caller identity`} needs the following permission(s) on the resource Users to perform this action: Add Users +### Access Denied: {`ID of the caller identity`} needs the following permissions on the resource Users to perform this action: Add Users This error might be due to one of the following reasons: * You're not the owner of the organization, project collection administrator, or a project or team administrator. -* You're a project or team administrator, but the policy ['Allow team and project administrators to invite new users'](../../../organizations/security/restrict-invitations.md) has been disabled. -* You're a project or team administrator who's enabled to invite new users, but you're trying to assign a license when you invite a new user. Project or team administrators aren't allowed to assign a license to new users. Any new invited user is added at the [default access level for new users](/azure/devops/organizations/billing/buy-basic-access-add-users#select-default-access-level-for-new-users). Contact a PCA to change the license access level. +* You're a project or team administrator, but the policy ['Allow team and project administrators to invite new users'](../../../organizations/security/restrict-invitations.md) is disabled. +* You're a project or team administrator who can invite new users, but you're trying to assign a license when you invite a new user. Project or team administrators aren't allowed to assign a license to new users. Any new invited user is added at the [default access level for new users](/azure/devops/organizations/billing/buy-basic-access-add-users#select-default-access-level-for-new-users). Contact a PCA to change the license access level. + +### Azure DevOps Graph List API returns an empty list, even though we know there are service principals in the organization +The Azure DevOps Graph List API might return an empty list, even if there are still more pages of users to return. Use the `continuationToken` to iterate through the lists, and you can eventually find a page where the service principals are returned. If a `continuationToken` is returned, that means there are more results available through the API. While we have plans to improve upon this logic, at this moment, it's possible that the first X results return empty. -### Azure DevOps Graph List API returns empty list, even though we know there are service principals in the organization -The Azure DevOps Graph List API may return an empty list, even if there are still more pages of users to return. Use the `continuationToken` to iterate through the lists, and you can eventually find a page where the service principals are returned. If a `continuationToken` is returned, that means there are more results available through the API. While we have plans to improve upon this logic, at this moment, it's possible that the first X results return empty. +### TF401444: Sign-in at least once as {`tenantId`\`tenantId`\`servicePrincipalObjectId`} in a web browser to enable access to the service. +If the service principal wasn't invited to the organization, you might come across the following error. Ensure that the service principal is added to the appropriate organization and has all permissions needed to access any required resources. ## Related articles -* [Link to sample apps](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ServicePrincipalsSamples) -* [Service Principals Entitlements API Reference](/rest/api/azure/devops/memberentitlementmanagement/service-principal-entitlements?view=azure-devops-rest-7.1&preserve-view=true) -* [Service Principal Graph API Reference](/rest/api/azure/devops/graph/service-principals) +* [Explore sample apps](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ServicePrincipalsSamples) +* [Review the Service Principals Entitlements API reference](/rest/api/azure/devops/memberentitlementmanagement/service-principal-entitlements?view=azure-devops-rest-7.1&preserve-view=true) +* [Review the Service Principal Graph API reference](/rest/api/azure/devops/graph/service-principals) diff --git a/docs/integrate/get-started/client-libraries/samples.md b/docs/integrate/get-started/client-libraries/samples.md index 8dc5980800d..0a771e0efbc 100644 --- a/docs/integrate/get-started/client-libraries/samples.md +++ b/docs/integrate/get-started/client-libraries/samples.md @@ -1,38 +1,37 @@ --- title: .NET Client Library Samples for Azure DevOps -description: C# samples showing how to integrate with Azure DevOps from apps and services on Windows. +description: Learn how to extend and integrate with Azure DevOps by using C# samples from apps and services on Windows. ms.assetid: 9ff78e9c-63f7-45b1-a70d-42aa6a9dbc57 ms.subservice: azure-devops-ecosystem ms.custom: devx-track-dotnet -ms.topic: conceptual +ms.topic: concept-article monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 05/05/2022 +ms.date: 04/10/2025 --- -# C# client library samples +# C# client library samples [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -Samples showing how to extend and integrate with Azure DevOps using the [.NET client libraries](../../concepts/dotnet-client-libraries.md). - +The following samples show you how to extend and integrate with Azure DevOps using the [.NET client libraries](../../concepts/dotnet-client-libraries.md). ## Samples in GitHub -There are many samples with instructions on how to run them on our [.NET Sample GitHub Page](https://github.com/microsoft/azure-devops-dotnet-samples). + +On the [.NET samples page](https://github.com/microsoft/azure-devops-dotnet-samples) in GitHub, you can find many samples with instructions on how to run them. ## Other samples -REST examples on this page require the following NuGet packages: + +The REST examples in this article require the following NuGet packages: + * [Microsoft.TeamFoundationServer.Client](https://www.nuget.org/packages/Microsoft.TeamFoundationServer.Client/) * [Microsoft.VisualStudio.Services.Client](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Client/) * [Microsoft.VisualStudio.Services.InteractiveClient](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.InteractiveClient/) ->[!NOTE] -> The Work Item Tracking (WIT) and Test Client OM are scheduled to be deprecated in 2020. For more information, see [Deprecation of WIT and Test Client OM](../../concepts/wit-client-om-deprecation.md). +### Example: Use a REST-based HTTP client -#### Example: Using a REST-based HTTP client - -```cs +```csharp // https://www.nuget.org/packages/Microsoft.TeamFoundationServer.Client/ using Microsoft.TeamFoundation.WorkItemTracking.WebApi; using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models; @@ -122,24 +121,29 @@ public static void SampleREST() } ``` -## Authenticating +## Authentication -To change the method of authentication to Azure DevOps Services or Azure DevOps Server, change the VssCredential type passed to VssConnection when creating it. +To change the authentication method for Azure DevOps, change the `VssCredential` type passed to `VssConnection` when you create it. -##### Personal Access Token authentication for REST services -```cs -public static void PersonalAccessTokenRestSample() + + +#### Microsoft Entra authentication for REST services + +```csharp +public static void AADRestSample() { - // Create instance of VssConnection using Personal Access Token - VssConnection connection = new VssConnection(orgUrl, new VssBasicCredential(string.Empty, personalAccessToken)); + // Create instance of VssConnection using Azure AD Credentials for Azure AD backed account + VssConnection connection = new VssConnection(new Uri(collectionUri), new VssAadCredential(userName, password)); } ``` -##### Visual Studio sign-in prompt (Microsoft Account or Azure Active Directory backed) for REST services (.NET Framework only) + + +#### Visual Studio sign-in prompt (Microsoft Account or Microsoft Entra backend) for REST services (.NET Framework only) -Because interactive dialogs aren't supported by the .NET Core version of the clients, this sample applies only to the .NET Framework version of the clients. +Since the .NET Core version doesn't support interactive dialogs, this sample applies only to the .NET Framework version of the clients. -```cs +```csharp public static void MicrosoftAccountRestSample() { // Create instance of VssConnection using Visual Studio sign-in prompt @@ -147,21 +151,24 @@ public static void MicrosoftAccountRestSample() } ``` -##### Azure Active Directory Authentication for REST services -```cs -public static void AADRestSample() -{ - // Create instance of VssConnection using Azure AD Credentials for Azure AD backed account - VssConnection connection = new VssConnection(new Uri(collectionUri), new VssAadCredential(userName, password)); -} -``` +#### OAuth authentication for REST services + +For more information, see [Azure DevOps auth samples](https://github.com/microsoft/azure-devops-auth-samples) and [Microsoft identity platform and OAuth 2.0 authorization code flow](/entra/identity-platform/v2-oauth2-auth-code-flow). -##### OAuth Authentication for REST services -Follow this link to learn how to obtain and refresh an OAuth accessToken: https://github.com/microsoft/azure-devops-auth-samples -```cs +```csharp public static void OAuthSample() { // Create instance of VssConnection using OAuth Access token VssConnection connection = new VssConnection(new Uri(collectionUri), new VssOAuthAccessTokenCredential(accessToken)); } ``` + +#### Personal access token authentication for REST services + +```csharp +public static void PersonalAccessTokenRestSample() +{ + // Create instance of VssConnection using Personal Access Token + VssConnection connection = new VssConnection(orgUrl, new VssBasicCredential(string.Empty, personalAccessToken)); +} +``` diff --git a/docs/integrate/get-started/client-libraries/soapSamples.md b/docs/integrate/get-started/client-libraries/soapSamples.md index d9da455917b..0b75f9b616e 100644 --- a/docs/integrate/get-started/client-libraries/soapSamples.md +++ b/docs/integrate/get-started/client-libraries/soapSamples.md @@ -1,6 +1,6 @@ --- -title: .NET Client Library Samples for Azure DevOps Services - Legacy SOAP -description: C# samples showing how to integrate with Azure DevOps Services and Team Foundation Server from apps and services on Windows using the legacy SOAP clients. +title: .NET Client Library Samples - Legacy SOAP +description: C# samples showing how to integrate with Azure DevOps Services and Azure DevOps Server from apps and services on Windows using the legacy SOAP clients. ms.assetid: 9ff78e9c-63f7-45b1-a70d-42aa6a9dbc57 ms.subservice: azure-devops-ecosystem ms.custom: devx-track-dotnet @@ -8,14 +8,19 @@ ms.topic: conceptual monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 09/26/2019 +ms.date: 11/10/2023 --- # C# client library samples for SOAP clients and services [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -Samples showing how to extend and integrate with Team Foundation Server and Azure DevOps Services using the legacy SOAP clients. These clients are only available in the .NET Framework version of the clients. For new development, prefer the JSON-based clients described in [.NET client libraries](../../concepts/dotnet-client-libraries.md). +This article contains samples that show you how to extend and integrate with Azure DevOps Server and Azure DevOps Services using the legacy SOAP clients. These clients are only available in the .NET Framework version of the clients. + +> [!IMPORTANT] +> For new development, see the JSON-based clients described in [.NET client libraries](../../concepts/dotnet-client-libraries.md). + +## Prerequisites Examples on this page require the following NuGet packages: @@ -72,11 +77,12 @@ public static void SampleSOAP() } ``` -## Authenticating +## Authentication -To change the method of authentication to Azure DevOps Services or Azure DevOps Server, change the VssCredential type passed to VssConnection when creating it. +To change the method of authentication to Azure DevOps, change the VssCredential type passed to VssConnection when you create it. + +### Personal access token authentication for SOAP services -### Personal Access Token authentication for SOAP services ```cs public static void PersonalAccessTokenSoapSample() { @@ -90,7 +96,10 @@ public static void PersonalAccessTokenSoapSample() } ``` -### Azure Active Directory authentication for SOAP services + + +### Microsoft Entra authentication for SOAP services + ```cs public static void AADSoapSample() { @@ -103,7 +112,10 @@ public static void AADSoapSample() } ``` -### Visual Studio sign-in prompt (Microsoft Account or Azure Active Directory backed) for SOAP services + + +### Visual Studio sign-in prompt (Microsoft Account or Microsoft Entra backed) for SOAP services + ```cs public static void MicrosoftAccountSample() { diff --git a/docs/integrate/get-started/rest/samples.md b/docs/integrate/get-started/rest/samples.md index 8a2b5ec7ca3..72b9207c0aa 100644 --- a/docs/integrate/get-started/rest/samples.md +++ b/docs/integrate/get-started/rest/samples.md @@ -8,23 +8,27 @@ ms.custom: devx-track-dotnet monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 10/06/2020 +ms.date: 03/21/2025 --- -# Get started sample +# REST API samples for Azure DevOps [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] +Most samples in this article use personal access tokens (PATs). While PATs are a compact example for authentication, we don't recommend using them for production applications. There are many other authentication mechanisms available, including Microsoft Authentication Library, OAuth, and Session tokens. For more information to gauge which is best suited for your scenario, see [Authentication guidance](../authentication/authentication-guidance.md). + +For more information, see [Azure DevOps Services REST API Reference](/rest/api/azure/devops/?view=azure-devops-rest-7.2&preserve-view=true) and [Get started with REST APIs](../../how-to/call-rest-api.md). + ## Personal access tokens -Authenticate with Azure DevOps when you're using the REST APIs or .NET Libraries. Most samples in this article use PATs. PATs are a compact example for authentication. There are many other authentication mechanisms available, including Microsoft Authentication Library, OAuth, and Session tokens. For more information to gauge which is best suited for your scenario, see [Authentication](../authentication/authentication-guidance.md). +Authenticate with Azure DevOps when you use the REST APIs or .NET Libraries. -Get started with these samples and [create a personal access token](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). +Get started with these samples and [create a PAT](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). -> [!TIP] -> Personal access tokens are like passwords. Keep them secret. Make sure you save them in a secure location once your personal access token is created. +> [!NOTE] +> We don't recommend using PATs. For more secure authentication mechanisms, see [Authentication guidance](../authentication/authentication-guidance.md). -To provide the personal access token through an HTTP header, first convert it to a Base64 string. The following example shows how to convert to Base64 using C#. The resulting string can then be provided as an HTTP header in the following format: +To provide the PAT through an HTTP header, first convert it to a Base64 string. The following example shows how to convert to Base64 using C#. You can provide the resulting string as an HTTP header in the following format: `` Authorization: Basic BASE64USERNAME:PATSTRING @@ -70,7 +74,7 @@ using (var client = new HttpClient()) ## .NET Client Libraries -Here, we're using two of the .NET Client Libraries. Make sure these .NET Client Libraries are referenced within your .NET project. +Here, we're using two of the .NET Client Libraries. Make sure you reference the following .NET Client Libraries within your .NET project. - [Microsoft.TeamFoundationServer.Client](https://www.nuget.org/packages/Microsoft.TeamFoundationServer.Client/) - [Microsoft.Visual Studio.Services.Client](https://www.nuget.org/packages/Microsoft.VisualStudio.Services.Client/) @@ -94,7 +98,7 @@ using (ProjectHttpClient projectHttpClient = new ProjectHttpClient(uri, credenti ``` -## Q & A +## FAQs diff --git a/docs/integrate/how-to/call-rest-api.md b/docs/integrate/how-to/call-rest-api.md index 0944819636d..ec6740c3e3e 100644 --- a/docs/integrate/how-to/call-rest-api.md +++ b/docs/integrate/how-to/call-rest-api.md @@ -8,83 +8,84 @@ ms.custom: monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 09/13/2021 +ms.date: 04/04/2025 --- # Get started with the REST APIs [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Integrate your app with Azure DevOps using these REST APIs. +Integrate your application with Azure DevOps using the REST APIs provided in this article. These APIs allow you to interact with the services programmatically, enabling you to automate workflows, integrate with other systems, and extend the capabilities of Azure DevOps. -These APIs follow a common pattern: +The APIs follow a common pattern, as shown in the following example: ```no-highlight VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version} ``` > [!TIP] -> To avoid having your app or service broken as APIs evolve, specify an [API version](#versions) on every request. +> As APIs evolve, we recommend that you include an API version in every request. This practice can help you avoid unexpected changes in the API that could break. ## Azure DevOps Services -For Azure DevOps Services, `instance` is `dev.azure.com/{organization}` and `collection` is `DefaultCollection`, -so the pattern looks like this: +For Azure DevOps Services, `instance` is `dev.azure.com/{organization}` and `collection` is `DefaultCollection`, so the pattern looks like the following example: ```no-highlight VERB https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version} ``` -For example, here's how to get a list of projects in an organization. +The following example shows how to get a list of projects in an organization: ```dos curl -u {username}:{personalaccesstoken} https://dev.azure.com/{organization}/_apis/projects?api-version=2.0 ``` -If you wish to provide the personal access token through an HTTP header, you must first convert it to a Base64 string (the following example shows how to convert to Base64 using C#). The resulting string can then be provided as an HTTP header in the format: +If you want to provide the personal access token (PAT) through an HTTP header, first prepend a colon to the PAT. Then, convert the concatenation of the colon and the PAT to a Base64 string. The following example shows how to convert to Base64 using C#. The resulting string can then be provided as an HTTP header in the format: ``` -Authorization: Basic BASE64PATSTRING +Authorization: Basic BASE64COLONANDPATSTRING ``` -Here it is in C# using the HttpClient class. +> [!NOTE] +> Include the colon before the PAT to avoid authentication errors. + +The following example shows C# using the [HttpClient class](/previous-versions/visualstudio/hh193681(v=vs.118)): ```cs public static async void GetProjects() { - try - { - var personalaccesstoken = "PAT_FROM_WEBSITE"; - - using (HttpClient client = new HttpClient()) - { - client.DefaultRequestHeaders.Accept.Add( - new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json")); - - client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", - Convert.ToBase64String( - System.Text.ASCIIEncoding.ASCII.GetBytes( - string.Format("{0}:{1}", "", personalaccesstoken)))); - - using (HttpResponseMessage response = client.GetAsync( - "https://dev.azure.com/{organization}/_apis/projects").Result) - { - response.EnsureSuccessStatusCode(); - string responseBody = await response.Content.ReadAsStringAsync(); - Console.WriteLine(responseBody); - } - } - } - catch (Exception ex) - { - Console.WriteLine(ex.ToString()); - } + try + { + var personalaccesstoken = "PAT_FROM_WEBSITE"; + + using (HttpClient client = new HttpClient()) + { + client.DefaultRequestHeaders.Accept.Add( + new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json")); + + client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", + Convert.ToBase64String( + System.Text.ASCIIEncoding.ASCII.GetBytes( + string.Format("{0}:{1}", "", personalaccesstoken)))); + + using (HttpResponseMessage response = client.GetAsync( + "https://dev.azure.com/{organization}/_apis/projects").Result) + { + response.EnsureSuccessStatusCode(); + string responseBody = await response.Content.ReadAsStringAsync(); + Console.WriteLine(responseBody); + } + } + } + catch (Exception ex) + { + Console.WriteLine(ex.ToString()); + } } ``` -
      -If you don't have an organization, you can set one up for free. -Most samples on this site use Personal Access Tokens as they're a compact example for authenticating with the service. However, there are various authentication mechanisms available for Azure DevOps Services including Microsoft Authentication Library (MSAL), OAuth, and Session Tokens. Refer to the [Authentication](../get-started/authentication/authentication-guidance.md) section for guidance on which one is best suited for your scenario. +> [!IMPORTANT] +> While we use personal access tokens (PATs) in many examples for simplicity, we don't recomment using them for production applications. Instead, consider using more secure authentication mechanisms. For more information, see [Authentication guidance](../get-started/authentication/authentication-guidance.md). ## Azure DevOps Server @@ -104,47 +105,47 @@ To get the same list across a non-SSL connection: curl -u {username}:{personalaccesstoken} http://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0 ``` -These examples use personal access tokens, which requires that you [create a personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). +These examples use PATs, which require that you [create a PAT](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). ## Responses -You should get a response like this. +You should get a response like the following example: ```json { "value": [ { - "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam-Fiber-TFVC", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1", + "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000", "description": "TeamFoundationVersionControlprojects", "collection": { - "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16", + "id": "00000000-0000-0000-0000-000000000000", "name": "DefaultCollection", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16", + "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000", "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc" }, "defaultTeam": { - "id": "66df9be7-3586-467b-9c5f-425b29afedfd", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam-Fiber-TFVCTeam", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd" + "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000" } }, { - "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam-Fiber-Git", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", + "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000", "description": "Gitprojects", "collection": { - "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16", + "id": "00000000-0000-0000-0000-000000000000", "name": "DefaultCollection", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16", + "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000", "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc" }, "defaultTeam": { - "id": "8bd35c5e-30bb-4834-a0c4-d576ce1b8df7", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam-Fiber-GitTeam", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/teams/8bd35c5e-30bb-4834-a0c4-d576ce1b8df7" + "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000" } } ], @@ -152,10 +153,8 @@ You should get a response like this. } ``` -The response is [JSON](https://json.org/). -That's generally what you'll get back from the REST APIs, -although there are a few exceptions, -like [Git blobs](/rest/api/azure/devops/git/blobs). +The response is [JSON](https://json.org/), which is generally what you get back from the REST APIs, +although there are a few exceptions, like [Git blobs](/rest/api/azure/devops/git/blobs). Now, you can look around the specific [API areas](/rest/api/azure/devops/git/) like [work item tracking](/rest/api/azure/devops/wit/) or [Git](/rest/api/azure/devops/git/) and get to the resources that you need. @@ -195,9 +194,9 @@ Content-Type: application/json ### HTTP method override -Some web proxies may only support the HTTP verbs GET and POST, but not more modern HTTP verbs like PATCH and DELETE. -If your calls may pass through one of these proxies, you can send the actual verb using a POST method, with a header to override the method. -For example, you may want to [update a work item](/rest/api/azure/devops/wit/work-items/update) (`PATCH _apis/wit/workitems/3`), but you may have to go through a proxy that only allows GET or POST. +Some web proxies might only support the HTTP verbs GET and POST, but not more modern HTTP verbs like PATCH and DELETE. +If your calls might pass through one of these proxies, you can send the actual verb using a POST method, with a header to override the method. +For example, you might want to [update a work item](/rest/api/azure/devops/wit/work-items/update) (`PATCH _apis/wit/workitems/3`), but you might have to go through a proxy that only allows GET or POST. You can pass the proper verb (PATCH in this case) as an HTTP request header parameter and use POST as the actual HTTP method. ```no-highlight @@ -222,14 +221,14 @@ Response | Notes 201 | Success, when creating resources. Some APIs return 200 when successfully creating a resource. Look at the docs for the API you're using to be sure. 204 | Success, and there's no response body. For example, you get this response when you delete a resource. 400 | The parameters in the URL or in the request body aren't valid. -401 | Authentication has failed. Often, this response is because of a missing or malformed Authorization header. +401 | Authentication failed. Often, this response is because of a missing or malformed Authorization header. 403 | The authenticated user doesn't have permission to do the operation. 404 | The resource doesn't exist, or the authenticated user doesn't have permission to see that it exists. 409 | There's a conflict between the request and the state of the data on the server. For example, if you attempt to submit a pull request and there's already a pull request for the commits, the response code is 409. ## Cross-origin resource sharing (CORS) -Azure DevOps Services supports CORS, which enables JavaScript code served from a domain other than `dev.azure.com/*` to make Ajax requests to Azure DevOps Services REST APIs. Each request must provide credentials (personal access tokens and OAuth access tokens are both supported options). Example: +Azure DevOps Services supports CORS, which enables JavaScript code served from a domain other than `dev.azure.com/*` to make Ajax requests to Azure DevOps Services REST APIs. Each request must provide credentials (PATs and OAuth access tokens are both supported options). Example: ```js $( document ).ready(function() { @@ -245,7 +244,7 @@ Azure DevOps Services supports CORS, which enables JavaScript code served from a }); ``` -(replace `myPatToken` with a personal access token) +Replace `myPatToken` with a PAT. @@ -255,15 +254,14 @@ Azure DevOps REST APIs are versioned to ensure applications and services continu ### Guidelines -* API version **must** be specified with every request. -* API versions are in the format {major}.{minor}-{stage}.{resource-version} - For example, ```1.0```, ```1.1```, ```1.2-preview```, ```2.0```. -* While an API is in preview, you can specify a precise version of a particular revision of the API when needed (for example, ```1.0-preview.1```, ```1.0-preview.2```) -* Once an API is released (1.0, for example), its preview version (1.0-preview) is deprecated and can be deactivated after 12 weeks. -* Now, you should upgrade to the released version of the API. Once a preview API is deactivated, requests that specify ```-preview``` version gets rejected. +* Specify the API version with every request (**required**). +* Format API versions as follows: {major}.{minor}-{stage}.{resource-version}. For example, ```1.0```, ```1.1```, ```1.2-preview```, ```2.0```. +* Specify a particular revision of the API when it's in preview, by using the following version format: ```1.0-preview.1```, ```1.0-preview.2```. Once an API is released (1.0, for example), its preview version (1.0-preview) is deprecated and can be deactivated after 12 weeks. +* Upgrade to the released version of the API. Once a preview API is deactivated, requests that specify ```-preview``` version get rejected. ### Usage -API version can be specified either in the header of the HTTP request or as a URL query parameter: +Specify the API version in the header of the HTTP request or as a URL query parameter. HTTP request header: diff --git a/docs/integrate/includes/scopes.md b/docs/integrate/includes/scopes.md index 3294bb44b71..39083657432 100644 --- a/docs/integrate/includes/scopes.md +++ b/docs/integrate/includes/scopes.md @@ -1,82 +1,88 @@ -| Category | Scope | Name | Description | -| -------- | ----- | ---- | ----------- | -| **Agent Pools** | `vso.agentpools` | Agent Pools (read) | Grants the ability to view tasks, pools, queues, agents, and currently running or recently completed jobs for agents. | -| | `vso.agentpools_manage` | Agent Pools (read, manage) | Grants the ability to manage pools, queues, and agents. | -| | `vso.environment_manage` | Environment (read, manage) | Grants the ability to manage pools, queues, agents, and environments. | -| **Analytics** | `vso.analytics` | Analytics (read) | Grants the ability to query analytics data. | -| **Auditing** | `vso.auditlog` | Audit Log (read) | Grants the ability to read the auditing log to users. | -| | `vso.auditstreams_manage` | Audit Streams (read) | Grants the ability to manage auditing streams to users. | -| **Build** | `vso.build` | Build (read) | Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to receive notifications about build events via service hooks. | -| | `vso.build_execute` | Build (read and execute) | Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to queue a build, update build properties, and the ability to receive notifications about build events via service hooks. | -| **Code** | `vso.code` | Code (read) | Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to search code and get notified about version control events via service hooks. | -| | `vso.code_write` | Code (read and write) | Grants the ability to read, update, and delete source code, access metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage pull requests and code reviews and to receive notifications about version control events via service hooks. | -| | `vso.code_manage` | Code (read, write, and manage) | Grants the ability to read, update, and delete source code, access metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage code repositories, create and manage pull requests and code reviews, and to receive notifications about version control events via service hooks. | -| | `vso.code_full` | Code (full) | Grants full access to source code, metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage code repositories, create and manage pull requests and code reviews, and to receive notifications about version control events via service hooks. Also includes limited support for Client OM APIs. | -| | `vso.code_status` | Code (status) | Grants the ability to read and write commit and pull request status. | -| **Connected Server** | `vso.connected_server` | Connected Server | Grants the ability to access endpoints needed from an on-prem connected server. | -| **Entitlements** | `vso.entitlements` | Entitlements (Read) | Provides read only access to licensing entitlements endpoint to get account entitlements. | -| | `vso.memberentitlementmanagement` | MemberEntitlement Management (read) | Grants the ability to read users, their licenses as well as projects and extensions they can access. | -| | `vso.memberentitlementmanagement_write` | MemberEntitlement Management (write) | Grants the ability to manage users, their licenses as well as projects and extensions they can access. | -| **Extensions** | `vso.extension` | Extensions (read) | Grants the ability to read installed extensions. | -| | `vso.extension_manage` | Extensions (read and manage) | Grants the ability to install, uninstall, and perform other administrative actions on installed extensions. | -| | `vso.extension.data` | Extension data (read) | Grants the ability to read data (settings and documents) stored by installed extensions. | -| | `vso.extension.data_write` | Extension data (read and write) | Grants the ability to read and write data (settings and documents) stored by installed extensions. | -| **Graph & identity** | `vso.graph` | Graph (read) | Grants the ability to read user, group, scope, and group membership information. | -| | `vso.graph_manage` | Graph (manage) | Grants the ability to read user, group, scope and group membership information, and to add users, groups, and manage group memberships. | -| | `vso.identity` | Identity (read) | Grants the ability to read identities and groups. | -| | `vso.identity_manage` | Identity (manage) | Grants the ability to read, write, and manage identities and groups. | -| **Load Test** | `vso.loadtest` | Load test (read) | Grants the ability to read your load test runs, test results, and APM artifacts. | -| | `vso.loadtest_write` | Load test (read and write) | Grants the ability to create and update load test runs, and read metadata including test results and APM artifacts. | -| **Machine Group** | `vso.machinegroup_manage` | Deployment group (read, manage) | Provides ability to manage deployment group and agent pools. | -| **Marketplace** | `vso.gallery` | Marketplace | Grants read access to public and private items and publishers. | -| | `vso.gallery_acquire` | Marketplace (acquire) | Grants read access and the ability to acquire items. | -| | `vso.gallery_publish` | Marketplace (publish) | Grants read access and the ability to upload, update, and share items. | -| | `vso.gallery_manage` | Marketplace (manage) | Grants read access and the ability to publish and manage items and publishers. | -| **Notifications** | `vso.notification` | Notifications (read) | Provides read access to subscriptions and event metadata, including filterable field values. | -| | `vso.notification_write` | Notifications (write) | Provides read and write access to subscriptions and read access to event metadata, including filterable field values. | -| | `vso.notification_manage` | Notifications (manage) | Provides read, write, and management access to subscriptions and read access to event metadata, including filterable field values. | -| | `vso.notification_diagnostics` | Notifications (diagnostics) | Provides access to notification-related diagnostic logs and provides the ability to enable diagnostics for individual subscriptions. | -| **Packaging** | `vso.packaging` | Packaging (read) | Grants the ability to read feeds and packages. | -| | `vso.packaging_write` | Packaging (read and write) | Grants the ability to create and read feeds and packages. | -| | `vso.packaging_manage` | Packaging (read, write, and manage) | Grants the ability to create, read, update, and delete feeds and packages. | -| **Pipeline Resources** | `vso.pipelineresources_use` | Pipeline Resources (use) | Grants the ability to approve a pipeline's request to use a protected resource: agent pool, environment, queue, repository, secure files, service connection, and variable group. | -| | `vso.pipelineresources_manage` | Pipeline Resources (use and manage) | Grants the ability to manage a protected resource or a pipeline's request to use a protected resource: agent pool, environment, queue, repository, secure files, service connection, and variable group. | -| **Project and Team** | `vso.project` | Project and team (read) | Grants the ability to read projects and teams. | -| | `vso.project_write` | Project and team (read and write) | Grants the ability to read and update projects and teams. | -| | `vso.project_manage` | Project and team (read, write and manage) | Grants the ability to create, read, update, and delete projects and teams. | -| **Release** | `vso.release` | Release (read) | Grants the ability to read release artifacts, including releases, release definitions and release environment. | -| | `vso.release_execute` | Release (read, write and execute) | Grants the ability to read and update release artifacts, including releases, release definitions and release environment, and the ability to queue a new release. | -| | `vso.release_manage` | Release (read, write, execute and manage) | Grants the ability to read, update, and delete release artifacts, including releases, release definitions and release environment, and the ability to queue and approve a new release. | -| **Secure Files** | `vso.securefiles_read` | Secure Files (read) | Grants the ability to read secure files. | -| | `vso.securefiles_write` | Secure Files (read, create) | Grants the ability to read and create secure files. | -| | `vso.securefiles_manage` | Secure Files (read, create, and manage) | Grants the ability to read, create, and manage secure files. | -| **Security** | `vso.security_manage` | Security (manage) | Grants the ability to read, write, and manage security permissions. | -| **Service Connections** | `vso.serviceendpoint` | Service Endpoints (read) | Grants the ability to read service endpoints. | -| | `vso.serviceendpoint_query` | Service Endpoints (read and query) | Grants the ability to read and query service endpoints. | -| | `vso.serviceendpoint_manage` | Service Endpoints (read, query and manage) | Grants the ability to read, query, and manage service endpoints. | -| **Settings** | `vso.settings` | Settings (read) | Grants the ability to read settings. | -| | `vso.settings_write` | Settings (read and write) | Grants the ability to create and read settings. | -| **Symbols** | `vso.symbols` | Symbols (read) | Grants the ability to read symbols. | -| | `vso.symbols_write` | Symbols (read and write) | Grants the ability to read and write symbols. | -| | `vso.symbols_manage` | Symbols (read, write and manage) | Grants the ability to read, write, and manage symbols. | -| **Task Groups** | `vso.taskgroups_read` | Task Groups (read) | Grants the ability to read task groups. | -| | `vso.taskgroups_write` | Task Groups (read, create) | Grants the ability to read and create task groups. | -| | `vso.taskgroups_manage` | Task Groups (read, create and manage) | Grants the ability to read, create and manage taskgroups. | -| **Team Dashboard** | `vso.dashboards` | Team dashboards (read) | Grants the ability to read team dashboard information. | -| | `vso.dashboards_manage` | Team dashboards (manage) | Grants the ability to manage team dashboard information. | -| **Test Management** | `vso.test` | Test management (read) | Grants the ability to read test plans, cases, results and other test management related artifacts. | -| | `vso.test_write` | Test management (read and write) | Grants the ability to read, create, and update test plans, cases, results and other test management related artifacts. | -| **Threads** | `vso.threads_full` | PR threads | Grants the ability to read and write to pull request comment threads. | -| **Tokens** | `vso.tokens` | Delegated Authorization Tokens | Grants the ability to manage delegated authorization tokens to users. | -| | `vso.tokenadministration` | Token Administration | Grants the ability to manage (view and revoke) existing tokens to organization administrators. | -| **User Profile** | `vso.profile` | User profile (read) | Grants the ability to read your profile, accounts, collections, projects, teams, and other top-level organizational artifacts. | -| | `vso.profile_write` | User profile (write) | Grants the ability to write to your profile. | -| **Variable Groups** | `vso.variablegroups_read` | Variable Groups (read) | Grants the ability to read variable groups. | -| | `vso.variablegroups_write` | Variable Groups (read, create) | Grants the ability to read and create variable groups. | -| | `vso.variablegroups_manage` | Variable Groups (read, create and manage) | Grants the ability to read, create and manage variable groups. | -| **Wiki** | `vso.wiki` | Wiki (read) | Grants the ability to read wikis, wiki pages and wiki attachments. Also grants the ability to search wiki pages. | -| | `vso.wiki_write` | Wiki (read and write) | Grants the ability to read, create and updates wikis, wiki pages and wiki attachments. | -| **Work Items** | `vso.work` | Work items (read) | Grants the ability to read work items, queries, boards, area and iterations paths, and other work item tracking related metadata. Also grants the ability to execute queries, search work items and to receive notifications about work item events via service hooks. | -| | `vso.work_write` | Work items (read and write) | Grants the ability to read, create, and update work items and queries, update board metadata, read area and iterations paths other work item tracking related metadata, execute queries, and to receive notifications about work item events via service hooks. | -| | `vso.work_full` | Work items (full) | Grants full access to work items, queries, backlogs, plans, and work item tracking metadata. Also provides the ability to receive notifications about work item events via service hooks. | - +| Category | Scope | Name | High-privilege | Description | Inherits From | +| -------- | ----- | ---- | --------- | ----------- | ------------- | +| **Advanced Security** | `vso.advsec` | AdvancedSecurity (read) | Yes | Grants the ability to read alerts, result instances, analysis result instances. || +| | `vso.advsec_write` | AdvancedSecurity (read and write) | Yes |Grants the ability to upload analyses in sarif | `vso.advsec` | +| | `vso.advsec_manage` | AdvancedSecurity (read, write, and manage) | Yes |Grants the ability to upload analyses in sarif | `vso.advsec_write` | +| **Agent Pools** | `vso.agentpools` | Agent Pools (read) || Grants the ability to view tasks, pools, queues, agents, and currently running or recently completed jobs for agents. || +| | `vso.agentpools_manage` | Agent Pools (read, manage) | Yes | Grants the ability to manage pools, queues, and agents. | `vso.agentpools` | +| | `vso.environment_manage` | Environment (read, manage) | Yes | Grants the ability to manage pools, queues, agents, and environments. | `vso.agentpools_manage` | +| **Analytics** | `vso.analytics` | Analytics (read) || Grants the ability to query analytics data. || +| **Auditing** | `vso.auditlog` | Audit Log (read) || Grants the ability to read the auditing log to users. || +| | `vso.auditstreams_manage` | Audit Streams (read) | Yes | Grants the ability to manage auditing streams to users. | `vso.auditlog` | +| **Build** | `vso.build` | Build (read) || Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to receive notifications about build events via service hooks. | `vso.hooks_write` | +| | `vso.build_execute` | Build (read and execute) | Yes | Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to queue a build, update build properties, and the ability to receive notifications about build events via service hooks. | `vso.build` | +| **Code** | `vso.code` | Code (read) || Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to search code and get notified about version control events via service hooks. | `vso.hooks_write` | +| | `vso.code_write` | Code (read and write) | Yes | Grants the ability to read, update, and delete source code, access metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage pull requests and code reviews and to receive notifications about version control events via service hooks. | `vso.code` | +| | `vso.code_manage` | Code (read, write, and manage) | Yes | Grants the ability to read, update, and delete source code, access metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage code repositories, create and manage pull requests and code reviews, and to receive notifications about version control events via service hooks. | `vso.code_write` | +| | `vso.code_full` | Code (full) | Yes | Grants full access to source code, metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage code repositories, create and manage pull requests and code reviews, and to receive notifications about version control events via service hooks. Also includes limited support for Client OM APIs. | `vso.code_manage` | +| | `vso.code_status` | Code (status) || Grants the ability to read and write commit and pull request status. || +| **Connected Server** | `vso.connected_server` | Connected Server || Grants the ability to access endpoints needed from an on-premises connected server. || +| **Entitlements** | `vso.entitlements` | Entitlements (Read) || Provides read only access to licensing entitlements endpoint to get account entitlements. || +| | `vso.memberentitlementmanagement` | MemberEntitlement Management (read) || Grants the ability to read users, their licenses as well as projects and extensions they can access. || +| | `vso.memberentitlementmanagement_write` | MemberEntitlement Management (write) | Yes | Grants the ability to manage users, their licenses as well as projects and extensions they can access. | `vso.memberentitlementmanagement` | +| **Extensions** | `vso.extension` | Extensions (read) || Grants the ability to read installed extensions. | `vso.profile` | +| | `vso.extension_manage` | Extensions (read and manage) | Yes | Grants the ability to install, uninstall, and perform other administrative actions on installed extensions. | `vso.extension` | +| | `vso.extension.data` | Extension data (read) || Grants the ability to read data (settings and documents) stored by installed extensions. | `vso.profile` | +| | `vso.extension.data_write` | Extension data (read and write) || Grants the ability to read and write data (settings and documents) stored by installed extensions. | `vso.extension.data` | +| **Github Connections** | `vso.githubconnections` | GitHub Connections (read) || Grants the ability to read GitHub connections and GitHub repositories data. || +| | `vso.githubconnections_manage` | GitHub Connections (read and manage) | Yes | Grants the ability to read and manage GitHub connections and GitHub repositories data | `vso.githubconnections` | +| **Graph & identity** | `vso.graph` | Graph (read) || Grants the ability to read user, group, scope, and group membership information. || +| | `vso.graph_manage` | Graph (manage) | Yes | Grants the ability to read user, group, scope and group membership information, and to add users, groups, and manage group memberships. | `vso.graph` | +| | `vso.identity` | Identity (read) || Grants the ability to read identities and groups. || +| | `vso.identity_manage` | Identity (manage) | Yes | Grants the ability to read, write, and manage identities and groups. | `vso.identity` | +| **Machine Group** | `vso.machinegroup_manage` | Deployment group (read, manage) | Yes | Provides ability to manage deployment group and agent pools. | `vso.agentpools_manage` | +| **Marketplace** | `vso.gallery` | Marketplace || Grants read access to public and private items and publishers. | `vso.profile` | +| | `vso.gallery_acquire` | Marketplace (acquire) || Grants read access and the ability to acquire items. | `vso.gallery` | +| | `vso.gallery_publish` | Marketplace (publish) | Yes | Grants read access and the ability to upload, update, and share items. | `vso.gallery` | +| | `vso.gallery_manage` | Marketplace (manage) | Yes | Grants read access and the ability to publish and manage items and publishers. | `vso.gallery_publish` | +| **Notifications** | `vso.notification` | Notifications (read) || Provides read access to subscriptions and event metadata, including filterable field values. | `vso.profile` | +| | `vso.notification_write` | Notifications (write) || Provides read and write access to subscriptions and read access to event metadata, including filterable field values. | `vso.notification` | +| | `vso.notification_manage` | Notifications (manage) || Provides read, write, and management access to subscriptions and read access to event metadata, including filterable field values. | `vso.notification_write` | +| | `vso.notification_diagnostics` | Notifications (diagnostics) || Provides access to notification-related diagnostic logs and provides the ability to enable diagnostics for individual subscriptions. | `vso.notification` | +| **Packaging** | `vso.packaging` | Packaging (read) || Grants the ability to read feeds and packages. | `vso.profile` | +| | `vso.packaging_write` | Packaging (read and write) | Yes | Grants the ability to create and read feeds and packages. | `vso.packaging` | +| | `vso.packaging_manage` | Packaging (read, write, and manage) | Yes | Grants the ability to create, read, update, and delete feeds and packages. | `vso.packaging_write` | +| **Pipeline Resources** | `vso.pipelineresources_use` | Pipeline Resources (use) | Yes | Grants the ability to approve a pipeline's request to use a protected resource: agent pool, environment, queue, repository, secure files, service connection, and variable group. || +| | `vso.pipelineresources_manage` | Pipeline Resources (use and manage) | Yes | Grants the ability to manage a protected resource or a pipeline's request to use a protected resource: agent pool, environment, queue, repository, secure files, service connection, and variable group. | `vso.pipelineresources_manage` | +| **Project and Team** | `vso.project` | Project and team (read) || Grants the ability to read projects and teams. || +| | `vso.project_write` | Project and team (read and write) || Grants the ability to read and update projects and teams. | `vso.project` | +| | `vso.project_manage` | Project and team (read, write and manage) | Yes | Grants the ability to create, read, update, and delete projects and teams. | `vso.project_write` | +| **Release** | `vso.release` | Release (read) || Grants the ability to read release artifacts, including releases, release definitions and release environment. | `vso.profile` | +| | `vso.release_execute` | Release (read, write and execute) | Yes | Grants the ability to read and update release artifacts, including releases, release definitions and release environment, and the ability to queue a new release. | `vso.release` | +| | `vso.release_manage` | Release (read, write, execute and manage) | Yes | Grants the ability to read, update, and delete release artifacts, including releases, release definitions and release environment, and the ability to queue and approve a new release. | `vso.release_manage` | +| **Secure Files** | `vso.securefiles_read` | Secure Files (read) | Yes | Grants the ability to read secure files. || +| | `vso.securefiles_write` | Secure Files (read, create) | Yes | Grants the ability to read and create secure files. | `vso.securefiles_read` | +| | `vso.securefiles_manage` | Secure Files (read, create, and manage) | Yes | Grants the ability to read, create, and manage secure files. | `vso.securefiles_write` | +| **Security** | `vso.security_manage` | Security (manage) | Yes | Grants the ability to read, write, and manage security permissions. || +| **Service Connections** | `vso.serviceendpoint` | Service Endpoints (read) || Grants the ability to read service endpoints. | `vso.profile` | +| | `vso.serviceendpoint_query` | Service Endpoints (read and query) || Grants the ability to read and query service endpoints. | `vso.serviceendpoint` | +| | `vso.serviceendpoint_manage` | Service Endpoints (read, query and manage) | Yes | Grants the ability to read, query, and manage service endpoints. | `vso.serviceendpoint_query` | +| **Service Hooks** | `vso.hooks` | Service hooks (read) || Grants the ability to read service hook subscriptions and metadata, including supported events, consumers, and actions. (No longer public.) | `vso.profile` | +| | `vso.hooks_write` | Service hooks (read and write) || Grants the ability to create and update service hook subscriptions and read metadata, including supported events, consumers, and actions. (No longer public.) | `vso.hooks` | +| | `vso.hooks_interact` | Service hooks (interact) || Grants the ability to interact and perform actions on events received via service hooks. (No longer public.) | `vso.profile` | +| **Settings** | `vso.settings` | Settings (read) || Grants the ability to read settings. || +| | `vso.settings_write` | Settings (read and write) || Grants the ability to create and read settings. || +| **Symbols** | `vso.symbols` | Symbols (read) || Grants the ability to read symbols. | `vso.profile` | +| | `vso.symbols_write` | Symbols (read and write) || Grants the ability to read and write symbols. | `vso.symbols` | +| | `vso.symbols_manage` | Symbols (read, write and manage) || Grants the ability to read, write, and manage symbols. | `vso.symbols_write` | +| **Task Groups** | `vso.taskgroups_read` | Task Groups (read) || Grants the ability to read task groups. || +| | `vso.taskgroups_write` | Task Groups (read, create) || Grants the ability to read and create task groups. | `vso.taskgroups_read` | +| | `vso.taskgroups_manage` | Task Groups (read, create and manage) | Yes | Grants the ability to read, create and manage taskgroups. | `vso.taskgroups_write` | +| **Team Dashboard** | `vso.dashboards` | Team dashboards (read) || Grants the ability to read team dashboard information. || +| | `vso.dashboards_manage` | Team dashboards (manage) || Grants the ability to manage team dashboard information. | `vso.dashboards` | +| **Test Management** | `vso.test` | Test management (read) || Grants the ability to read test plans, cases, results and other test management related artifacts. | `vso.profile` | +| | `vso.test_write` | Test management (read and write) || Grants the ability to read, create, and update test plans, cases, results and other test management related artifacts. | `vso.test` | +| **Threads** | `vso.threads_full` | PR threads || Grants the ability to read and write to pull request comment threads. || +| **Tokens** | `vso.tokens` | Delegated Authorization Tokens | Yes | Grants the ability to manage delegated authorization tokens to users. || +| | `vso.tokenadministration` | Token Administration | Yes | Grants the ability to manage (view and revoke) existing tokens to organization administrators. || +| **User Profile** | `vso.profile` | User profile (read) || Grants the ability to read your profile, accounts, collections, projects, teams, and other top-level organizational artifacts. || +| | `vso.profile_write` | User profile (write) || Grants the ability to write to your profile. | `vso.profile` | +| **Variable Groups** | `vso.variablegroups_read` | Variable Groups (read) || Grants the ability to read variable groups. || +| | `vso.variablegroups_write` | Variable Groups (read, create) || Grants the ability to read and create variable groups. | `vso.variablegroups_read` | +| | `vso.variablegroups_manage` | Variable Groups (read, create and manage) | Yes | Grants the ability to read, create and manage variable groups. | `vso.variablegroups_write` | +| **Wiki** | `vso.wiki` | Wiki (read) || Grants the ability to read wikis, wiki pages and wiki attachments. Also grants the ability to search wiki pages. || +| | `vso.wiki_write` | Wiki (read and write) || Grants the ability to read, create and updates wikis, wiki pages and wiki attachments. | `vso.wiki` | +| **Work Items** | `vso.work` | Work items (read) || Grants the ability to read work items, queries, boards, area and iterations paths, and other work item tracking related metadata. Also grants the ability to execute queries, search work items and to receive notifications about work item events via service hooks. | `vso.hooks_write` | +| | `vso.work_write` | Work items (read and write) || Grants the ability to read, create, and update work items and queries, update board metadata, read area and iterations paths other work item tracking related metadata, execute queries, and to receive notifications about work item events via service hooks. | `vso.work` | +| | `vso.work_full` | Work items (full) || Grants full access to work items, queries, backlogs, plans, and work item tracking metadata. Also provides the ability to receive notifications about work item events via service hooks. | `vso.work_write` | +| **User Impersonation** | `user_impersonation` | User Impersonation | Yes | Have full access to Visual Studio Team Services REST APIs. **Request and/or consent this scope with caution as it is very powerful!** || diff --git a/docs/integrate/index.md b/docs/integrate/index.md index ba9cdda7ab1..415e4dc2c57 100644 --- a/docs/integrate/index.md +++ b/docs/integrate/index.md @@ -7,7 +7,7 @@ ms.assetid: c9b97ad7-ffd8-4657-8322-74f764eec5c9 monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 03/15/2021 +ms.date: 01/27/2025 --- # Integrate applications @@ -16,13 +16,25 @@ ms.date: 03/15/2021 You can build custom applications or services that integrate with Azure DevOps by using the **REST APIs** to make direct HTTP calls, or use our **.NET Client Libraries**. -Along with interacting with Azure DevOps in your application, you can also integrate with popular third-party services such as Slack or Jenkins. +Along with interacting with Azure DevOps in your application, you can also integrate with popular non-Microsoft services such as Slack or Jenkins. -To get started, see: +To get started, see the following articles: - [Create a bug](./quickstarts/create-bug-quickstart.md) - [Get work items using queries](./quickstarts/work-item-quickstart.md) - + +## Integrate applications with Azure DevOps + +Integrate Azure DevOps with other tools and services to not only enhance team collaboration but also streamline workflows across the software development lifecycle. Whether you're building custom integrations or using off-the-shelf services, it's essential that you understand the prerequisites. + +## Prerequisites for integration + +Before you start the integration process, ensure you have the following items: + +- **Access:** Ensure proper permissions and use secure authentication. +- **API knowledge:** Understand Azure DevOps REST API and the target tool API. +- **Data mapping:** Identify and align fields and data types between systems to ensure compatibility in field names, formats, and value ranges. +- **Network and connectivity:** Ensure your network supports API calls, webhook notifications, and connectivity between Azure DevOps and self-hosted tools. ## Resources diff --git a/docs/integrate/quickstarts/create-bug-quickstart.md b/docs/integrate/quickstarts/create-bug-quickstart.md index 3eb3d53494c..7bc6b6e4cb0 100644 --- a/docs/integrate/quickstarts/create-bug-quickstart.md +++ b/docs/integrate/quickstarts/create-bug-quickstart.md @@ -17,7 +17,7 @@ ms.custom: quickstart, devx-track-dotnet Creating a new bug (or any work item) is pretty straight forward. You just need to set the field values and send a JSON-Patch object to the REST endpoint. ## Prerequisites -You must have the following before you can create a work item. +Have the following before you can create a work item. * An organization in Azure DevOps Services. If you don't have one, you can [create one for free](https://go.microsoft.com/fwlink/?LinkId=307137) * A Personal Access Token, [find out how to create one](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) diff --git a/docs/integrate/quickstarts/work-item-quickstart.md b/docs/integrate/quickstarts/work-item-quickstart.md index 73d2e4faf19..ce1473c52e6 100644 --- a/docs/integrate/quickstarts/work-item-quickstart.md +++ b/docs/integrate/quickstarts/work-item-quickstart.md @@ -7,40 +7,43 @@ ms.topic: conceptual monikerRange: 'azure-devops' ms.author: chcomley author: chcomley -ms.date: 06/27/2017 +ai-usage: ai-assisted +ms.date: 03/21/2025 --- # Fetch work items with queries programmatically [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -A common scenario in Azure DevOps Services is to fetch work items using queries. This article details how to implement that scenario programmatically using our REST APIs or .NET client libraries. +Fetching work items using queries is a common scenario in Azure DevOps Services. This article explains how to implement this scenario programmatically using REST APIs or .NET client libraries. ## Prerequisites -You must have the following items: +| Category | Requirements | +|--------------|-------------| +|**Azure DevOps** | - [An organization](https://go.microsoft.com/fwlink/?LinkId=307137).<\br>- A [Personal Access Token (PAT)](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md).| +|**Development environment**| A C# development environment. You can use [Visual Studio](https://visualstudio.microsoft.com/vs/).| -* An organization in Azure DevOps Services. If you don't have one, you can [create one for free](https://go.microsoft.com/fwlink/?LinkId=307137) -* A Personal Access Token, [find out how to create one](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) -* A C# development environment, you can use [Visual Studio](https://visualstudio.microsoft.com/vs/) +> [!IMPORTANT] +> We use Personal Access Tokens (PATs) as an example in this article, but we don't recommend using PATs. For more secure authentication mechanisms, see [Authentication guidance](../get-started/authentication/authentication-guidance.md). ## Create a C# project in Visual Studio -To learn about C# programming within Visual Studio, see the [Visual Studio C# programming documentation](/dotnet/csharp/programming-guide/inside-a-program/). +For information about C# programming within Visual Studio, see the [Visual Studio C# programming documentation](/dotnet/csharp/programming-guide/inside-a-program/). ## C# code content -The following tasks occur in the following code sample: +The following tasks occur in the code snippet: -1. Authenticate - 1. Create credentials using your PAT - 2. Generate the client -2. Get the work items - 1. Create the query you want to use - 2. Get the results for that query - 3. Get each of the work items by ID +- **Authenticate** + 1. Create credentials using your Personal Access Token (PAT). + 2. Generate the client using the credentials. +- **Get the work items** + 1. Create the query you want to use. + 2. Retrieve the results for that query. + 3. Fetch each of the work items by ID. -## C# code snippet +### C# code snippet ```cs // nuget:Microsoft.TeamFoundationServer.Client @@ -48,10 +51,10 @@ using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; - using Microsoft.TeamFoundation.WorkItemTracking.WebApi; using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models; using Microsoft.VisualStudio.Services.Common; +using Microsoft.VisualStudio.Services.WebApi; public class QueryExecutor { @@ -59,15 +62,15 @@ public class QueryExecutor private readonly string personalAccessToken; /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// /// - /// An organization in Azure DevOps Services. If you don't have one, you can create one for free: - /// . + /// An organization in Azure DevOps Services. If you don't have one, you can create one for free: + /// . /// /// - /// A Personal Access Token, find out how to create one: - /// . + /// A Personal Access Token, find out how to create one: + /// . /// public QueryExecutor(string orgName, string personalAccessToken) { @@ -76,18 +79,15 @@ public class QueryExecutor } /// - /// Execute a WIQL (Work Item Query Language) query to return a list of open bugs. + /// Execute a WIQL (Work Item Query Language) query to return a list of open bugs. /// /// The name of your project within your organization. /// A list of objects representing all the open bugs. public async Task> QueryOpenBugs(string project) { var credentials = new VssBasicCredential(string.Empty, this.personalAccessToken); - - // create a wiql object and build our query var wiql = new Wiql() { - // NOTE: Even if other columns are specified, only the ID & URL are available in the WorkItemReference Query = "Select [Id] " + "From WorkItems " + "Where [Work Item Type] = 'Bug' " + @@ -96,39 +96,39 @@ public class QueryExecutor "Order By [State] Asc, [Changed Date] Desc", }; - // create instance of work item tracking http client - using (var httpClient = new WorkItemTrackingHttpClient(this.uri, credentials)) + using (var httpClient = new WorkItemTrackingHttpClient(this.uri, new VssCredentials(credentials))) { - // execute the query to get the list of work items in the results - var result = await httpClient.QueryByWiqlAsync(wiql).ConfigureAwait(false); - var ids = result.WorkItems.Select(item => item.Id).ToArray(); + try + { + var result = await httpClient.QueryByWiqlAsync(wiql).ConfigureAwait(false); + var ids = result.WorkItems.Select(item => item.Id).ToArray(); + + if (ids.Length == 0) + { + return Array.Empty(); + } - // some error handling - if (ids.Length == 0) + var fields = new[] { "System.Id", "System.Title", "System.State" }; + return await httpClient.GetWorkItemsAsync(ids, fields, result.AsOf).ConfigureAwait(false); + } + catch (Exception ex) { + Console.WriteLine("Error querying work items: " + ex.Message); return Array.Empty(); } - - // build a list of the fields we want to see - var fields = new[] { "System.Id", "System.Title", "System.State" }; - - // get work items for the ids found in query - return await httpClient.GetWorkItemsAsync(ids, fields, result.AsOf).ConfigureAwait(false); } } /// - /// Execute a WIQL (Work Item Query Language) query to print a list of open bugs. + /// Execute a WIQL (Work Item Query Language) query to print a list of open bugs. /// /// The name of your project within your organization. /// An async task. public async Task PrintOpenBugsAsync(string project) { var workItems = await this.QueryOpenBugs(project).ConfigureAwait(false); - Console.WriteLine("Query Results: {0} items found", workItems.Count); - // loop though work items and write to console foreach (var workItem in workItems) { Console.WriteLine( diff --git a/docs/integrate/rest-api-overview.md b/docs/integrate/rest-api-overview.md deleted file mode 100644 index a61f6214378..00000000000 --- a/docs/integrate/rest-api-overview.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: REST APIs for Azure DevOps -description: Find reference material and overviews of the basic patterns for using the REST APIs for Azure DevOps. -ms.assetid: bdddaf58-6849-4134-a295-2887dafeeea3 -ms.subservice: azure-devops-ecosystem -ms.topic: conceptual -ms.custom: -monikerRange: '<= azure-devops' -ms.author: chcomley -author: chcomley -ms.date: 03/24/2021 -robots: NOINDEX, NOFOLLOW ---- - -# REST API reference - -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - -Representational State Transfer (REST) APIs are service endpoints that support sets of HTTP operations (methods). These methods provide *create*, *retrieve*, *update*, or *delete* access to the service's resources. Learn the basic components of a REST API request and response pair, and see overviews of how to create and send a REST request, and handle the response. - -> [!NOTE] -> Most REST APIs have a corresponding .NET Client Library that you can use to simplify your client code. For more information, see -> [.NET Client Libraries documentation](./concepts/dotnet-client-libraries.md) - - -## Components of a REST API request and response pair - -You can separate a REST API request and response pair into the following five components: - -1. The **request URI**, in the following form: `VERB https://{instance}[/{collection}][/{team-project}]/_apis[/{area}]/{resource}?api-version={version}` - * *instance*: The Azure DevOps organization or Azure DevOps Server you're sending the request to. They're structured as follows: - * Azure DevOps: `dev.azure.com/{organization}` - * Azure DevOps Server: `server:port` (the default port is 8080) - * *collection*: The value for collection should be `DefaultCollection` for Azure DevOps. - * *resource path*: The collection should be followed by `_apis/{area}/{resource}`. For example, `_apis/wit/workitems`. - * *api-version*: Every API request should include an api-version to avoid having your app or service break as APIs evolve. api-versions are in the following format: `{major}.{minor}[-{stage}[.{resource-version}]], for example: - * `api-version=1.0` - * `api-version=1.2-preview` - * `api-version=2.0-preview.1` - - *area* and *team-project* are optional, depending on the API request. - -2. HTTP **request message header** fields: - * A required [HTTP method](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) (also known as an operation or verb), which tells the service what type of operation you're requesting. Azure REST APIs support GET, HEAD, PUT, POST, and PATCH methods. - * Optional additional header fields, as required by the specified URI and HTTP method. For example, an Authorization header that provides a bearer token containing client authorization information for the request. -3. Optional HTTP **request message body** fields, to support the URI and HTTP operation. For example, POST operations contain MIME-encoded objects that are passed as complex parameters. - * For POST or PUT operations, the MIME-encoding type for the body should be specified in the Content-type request header as well. Some services require you to use a specific MIME type, such as `application/json`. -4. HTTP **response message header** fields: - * An [HTTP status code](https://www.w3.org/Protocols/HTTP/HTRESP.html), ranging from 2xx success codes to 4xx or 5xx error codes. Or, a service-defined status code may be returned, as indicated in the API documentation. - * Optional additional header fields, as required to support the request's response, such as a `Content-type` response header. -5. Optional HTTP **response message body** fields: - * MIME-encoded response objects may be returned in the HTTP response body, such as a response from a GET method that is returning data. Typically, these objects are returned in a structured format such as JSON or XML, as indicated by the `Content-type` response header. For example, when you request an access token from Azure AD, it gets returned in the response body as the `access_token` element, one of several name/value paired objects in a data collection. In this example, a response header of `Content-Type: application/json` is also included. - - -## Create the request - -### Authenticate - -There are many ways to authenticate your application or service with Azure DevOps. The following table is an excellent way to decide which method is the best for you: - -| Type of application | Description | Example |Authentication mechanism | Code samples | -|---------------------|-------------|---------|-------------------------|--------| -| Interactive client-side | GUI-based client-side application | Windows app enumerating bugs for a user | [Microsoft Authentication Library](/azure/active-directory/develop/active-directory-authentication-libraries) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/ManagedClientConsoleAppSample) | -| Interactive JavaScript | GUI-based JavaScript application | AngularJS single page app displaying work items for a user | [Microsoft Authentication Library](/azure/active-directory/develop/active-directory-authentication-libraries) | sample (coming soon) | -| Non-interactive client-side | Headless text only client-side application | Console app displaying all bugs assigned to a user | [Device Profile](/azure/active-directory/develop/v2-oauth2-device-code) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/DeviceProfileSample) | -| Interactive web | GUI-based web application | Custom Web dashboard displaying build summaries |[OAuth](./get-started/authentication/oauth.md) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/OAuthWebSample) | -| Azure DevOps Server application | Azure DevOps Server app using the Client OM library | Azure DevOps Server extension displaying team bug dashboards | [Client Libraries](./concepts/dotnet-client-libraries.md) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/ClientLibraryConsoleAppSample) | -| [Azure DevOps Services extension](../extend/get-started/node.md) | Azure DevOps Services extension | [Agile Cards](https://marketplace.visualstudio.com/items?itemName=spartez.agile-cards) | [VSS Web Extension SDK](https://github.com/Microsoft/azure-devops-extension-sdk) | [sample walk through](../extend/develop/add-dashboard-widget.md) | - -> [!NOTE] -> You can find more information on authentication on our [authentication guidance page](./get-started/authentication/authentication-guidance.md) - -### Assemble the request - -::: moniker range="azure-devops" - -For Azure DevOps Services, *instance* is `dev.azure.com/{organization}` and *collection* is `DefaultCollection`, so the pattern looks like the following example: - -``` -VERB https://dev.azure.com/{organization}/_apis[/{area}]/{resource}?api-version={version} -``` - -For example, here's how to get a list of projects in an organization. - -```dos -curl -u {username}[:{personalaccesstoken}] https://dev.azure.com/{organization}/_apis/projects?api-version=2.0 -``` - -If you wish to provide the personal access token through an HTTP header, you must first convert it to a Base64 string (the following example shows how to convert to Base64 using C#). The resulting string can then be provided as an HTTP header in the format: - -```http -Authorization: Basic BASE64PATSTRING -``` - -Here it is in C# using the [HttpClient class](/previous-versions/visualstudio/hh193681(v=vs.118)). - -```cs -public static async void GetProjects() -{ - try - { - var personalaccesstoken = "PAT_FROM_WEBSITE"; - - using (HttpClient client = new HttpClient()) - { - client.DefaultRequestHeaders.Accept.Add( - new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json")); - - client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", - Convert.ToBase64String( - System.Text.ASCIIEncoding.ASCII.GetBytes( - string.Format("{0}:{1}", "", personalaccesstoken)))); - - using (HttpResponseMessage response = client.GetAsync( - "https://dev.azure.com/{organization}/_apis/projects").Result) - { - response.EnsureSuccessStatusCode(); - string responseBody = await response.Content.ReadAsStringAsync(); - Console.WriteLine(responseBody); - } - } - } - catch (Exception ex) - { - Console.WriteLine(ex.ToString()); - } -} -``` - - -Most samples on this site use Personal Access Tokens (PATs), as they're a compact example for authenticating with the service. However, there are different kinds of authentication mechanisms available for Azure DevOps Services including Microsoft Authentication Library, OAuth, and Session Tokens. Refer to the [Authentication](./get-started/authentication/authentication-guidance.md) section for guidance on which one is best suited for your scenario. - -::: moniker-end - - -::: moniker range="< azure-devops" - -For Azure DevOps Server, `instance` is `{server:port}` and by default the port is 8080. -The default collection is `DefaultCollection`, but can be any collection. - -Here's how to get a list of projects: - -```dos -curl -u {username}[:{personalaccesstoken}] https://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0 -``` - -The previously listed examples use personal access tokens, which requires that you [create a personal access token](../organizations/accounts/use-personal-access-tokens-to-authenticate.md). - -## Process the response - -You should get a response like the following example. - -```json -{ - "value": [ - { - "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1", - "name": "Fabrikam-Fiber-TFVC", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1", - "description": "TeamFoundationVersionControlprojects", - "collection": { - "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16", - "name": "DefaultCollection", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16", - "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc" - }, - "defaultTeam": { - "id": "66df9be7-3586-467b-9c5f-425b29afedfd", - "name": "Fabrikam-Fiber-TFVCTeam", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd" - } - }, - { - "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", - "name": "Fabrikam-Fiber-Git", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", - "description": "Gitprojects", - "collection": { - "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16", - "name": "DefaultCollection", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16", - "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc" - }, - "defaultTeam": { - "id": "8bd35c5e-30bb-4834-a0c4-d576ce1b8df7", - "name": "Fabrikam-Fiber-GitTeam", - "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/teams/8bd35c5e-30bb-4834-a0c4-d576ce1b8df7" - } - } - ], - "count": 2 -} -``` - -The response is [JSON](https://json.org/). That's generally what you'll get back from the REST APIs, although there are a few exceptions, -like [Git blobs](/previous-versions/azure/devops/integrate/previous-apis/git/blobs). - -::: moniker-end - -Find the resources you need for [API areas](/previous-versions/azure/devops/integrate/previous-apis/overview), like [work item tracking](/previous-versions/azure/devops/integrate/previous-apis/wit/overview) -or [Git](/previous-versions/azure/devops/integrate/previous-apis/git/overview). - -## Related content - -* Check out the [Integrate documentation](./index.md) for REST API samples and use cases - * [Authentication guidance](./get-started/authentication/authentication-guidance.md) - * [Samples](./get-started/rest/samples.md) -* Discover the [.NET Client Libraries](./concepts/dotnet-client-libraries.md) for these REST APIs - * [Samples](./get-started/client-libraries/samples.md) diff --git a/docs/managed-devops-pools/architecture-overview.md b/docs/managed-devops-pools/architecture-overview.md new file mode 100644 index 00000000000..75059784d16 --- /dev/null +++ b/docs/managed-devops-pools/architecture-overview.md @@ -0,0 +1,46 @@ +--- +title: Microsoft Managed DevOps Pools architecture +description: Learn about the architecture, key concepts & terminology for Microsoft Managed DevOps Pools. +author: ElizaTar +ms.author: elizatar +ms.date: 11/13/2024 +ms.topic: overview +#Customer intent: As a platform engineer, I want to understand Managed DevOps Pools concepts and terminology so that I can set up a Managed DevOps Pool. +--- + +# Microsoft Managed DevOps Pools architecture overview + +In this article, you learn about the architecture and key concepts for Microsoft Managed DevOps Pools. Microsoft Managed DevOps Pools gives developers self-service access to managed compute resources to run their CI/CD workloads. You can configure the service to meet your development team and project structure, and manage security and network settings to access resources securely. + +## Microsoft Managed DevOps Pools architecture + +The *hosted on behalf of* architecture lets Microsoft services, after they’re delegated appropriate and scoped permissions to a virtual network by a subscription owner, attach hosted Azure services to a customer subscription. This connectivity model lets a Microsoft service provide software-as-a-service and user licensed services as opposed to standard consumption-based services. + +Managed DevOps Pools service uses the *hosted on-behalf* architecture, which means that the virtual machines exist in a subscription owned by Microsoft. Therefore, Microsoft incurs the costs for running and managing this infrastructure, the customer paying for the usage. + +Managed DevOps Pools service manages the capacity and in-region availability in the Managed DevOps Pools service subscriptions. + +Inside the internal subscription, the resources for a pool are isolated to a dedicated virtual network. +For the network connection, you can also choose between a Microsoft-hosted network connection, and an Azure network connection that you create in your own subscription. + +The following diagrams show the logical architecture of Managed DevOps Pools service. + +![Diagram that gives an overview of the Managed DevOps Pools service architecture.](media/architecture/architecture.png) + +### Network connectivity + +Network connectivity is determined by which virtual network the agents are connected to. + +By default, all pools use a Microsoft-provided virtual network, which restricts all inbound traffic and allows all outbound traffic. + +You can choose to bring your own virtual network, so that you can access company resources and set up custom security policies (like setting up a firewall). In this scenario, you'll need to [delegate a subnet](/azure/virtual-network/subnet-delegation-overview) on the virtual network to the Managed DevOps Pools service and associate the subnet with your pool. From that point, all virtual machines created for the pool will use that subnet. No other resources will be able to use the subnet. + +### User connectivity + +Currently you can't access the virtual machines provided by Managed DevOps Pools. + +## Related content + +- [What is Managed DevOps Pools service?](overview.md) +- [Quickstart: Get started with Managed DevOps Pools](quickstart-azure-portal.md) + diff --git a/docs/managed-devops-pools/configure-identity.md b/docs/managed-devops-pools/configure-identity.md new file mode 100644 index 00000000000..61fc56a1482 --- /dev/null +++ b/docs/managed-devops-pools/configure-identity.md @@ -0,0 +1,48 @@ +--- +title: Configure identity +description: Learn how to configure a managed identity for Managed DevOps Pools. +ms.date: 11/18/2024 +--- + +# Configure Managed DevOps Pools identity + +User assigned managed identities enable Azure resources to authenticate to cloud services, like Azure Key Vault, without storing credentials in code. These types of managed identities are created as standalone Azure resources, and have their own lifecycle. A single resource, like a Virtual Machine, can utilize multiple user assigned managed identities. Similarly, a single user assigned managed identity can be shared across multiple resources. + +## Create an identity and register it with Managed DevOps Pools + +The managed identity must be in the same Microsoft Entra directory as your Azure DevOps organization. + +* [View your current directory in the Azure portal](/azure/azure-portal/set-preferences#directories--subscriptions) +* [View the directory for your Azure DevOps organization](../organizations/accounts/connect-organization-to-azure-ad.md#connect-your-organization-to-microsoft-entra-id). You can go directly to this page in the Azure DevOps portal here: `https://dev.azure.com//_settings/organizationAad`. + +If the two directories don't match, or your Azure DevOps organization isn't connected to Microsoft Entra, follow the steps in [Connect your organization to Microsoft Entra ID](../organizations/accounts/connect-organization-to-azure-ad.md#connect-your-organization-to-microsoft-entra-id) and connect to the same directory as your Azure subscription. + +1. Go to the [Azure portal](https://portal.azure.com), search for **Managed Identities**, select it from the available options, and choose **Create**. Ensure you're logged in to the tenant specified in the previous section. If not, you must switch to an Azure account with access to that tenant, or switch the tenant of your Azure DevOps organization. You can view your current Tenant ID by searching for **Microsoft Entra Id** in the search bar, or by navigating the Microsoft Entra ID option using the portal menu in the top left of the Azure portal. + + :::image type="content" source="./media/prerequisites/create-identity-button.png" alt-text="Screenshot of Managed Identities Create button."::: + +1. Choose the desired **Subscription**, **Resource group**, **Region**, and **Name**, and choose **Review + Create**. + + :::image type="content" source="./media/prerequisites/create-identity.png" alt-text="Screenshot of Create User Assigned Managed Identity window."::: + +1. On the confirmation window, choose **Create** to create the identity. + +1. Go to your Managed DevOps Pool in the Azure portal, and choose **Settings > Identity**, **Add**. + + :::image type="content" source="./media/configure-identity/add-identity-button.png" alt-text="Screenshot of Add identity button."::: + +1. Choose your subscription, choose the managed identity from the list, and choose **Add**. + + :::image type="content" source="./media/configure-identity/add-identity.png" alt-text="Screenshot of Add identity pane."::: + +## Azure Key Vault integration + +Managed DevOps Pools offers the ability to fetch certificates from an Azure Key Vault during agent provisioning, which means the certificates will already exist on the machine by the time it runs your Azure DevOps pipelines. To use this feature, add an identity to your pool as shown in the previous example, and assign the **Key Vault Secrets User** role to the identity. + +Key Vault integration is configured in **Settings > Security**. For more information, see [Configure security - Key Vault integration](./configure-security.md#key-vault-configuration). + +:::image type="content" source="./media/configure-security/key-vault-configuration-menu.png" alt-text="Screenshot of Azure Key Vault integration settings."::: + +## See also + +* [Configure pool settings](./configure-pool-settings.md) diff --git a/docs/managed-devops-pools/configure-images.md b/docs/managed-devops-pools/configure-images.md new file mode 100644 index 00000000000..b65c44d76e0 --- /dev/null +++ b/docs/managed-devops-pools/configure-images.md @@ -0,0 +1,426 @@ +--- +title: Configure images +description: Learn how to configure agent images for Managed DevOps Pools. +ms.date: 03/25/2025 +--- + +# Configure Managed DevOps Pools images + +Managed DevOps Pools provides you with several options for virtual machine images for running pipelines in your pool. You can create your pool using selected Azure Marketplace VM images, use your own custom Azure Compute Gallery images, or use the same images as Azure Pipelines Microsoft-hosted agents. + +Managed DevOps Pools can be configured with a single image or multiple images. When your pool has multiple images, your pipelines should specify the image they want to run on using [aliases](#use-multiple-images-per-pool-with-aliases). + +## Choose your pool's image + +#### [Azure portal](#tab/azure-portal/) + +A default image is selected when you create a Managed DevOps Pool. You can keep the default choice, or change it during pool creation. To configure the image after pool creation, go to **Settings** > **Pool**, choose **Add from Image Library**, and select one or more images for your pool. + +:::image type="content" source="./media/configure-images/configure-pool-image.png" alt-text="Screenshot of configure image."::: + +#### [ARM template](#tab/arm/) + +Images are configured in the `fabricProfile` section of the Managed DevOps Pools resource properties. + +The following example specifies three images. For more information on the schema for images, see the following sections in this article. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "fabricProfile": { + ... + "images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest", + "aliases": [ + "ubuntu-20.04-gen2" + ] + }, + { + "wellKnownImageName": "windows-2022" + }, + { + "wellKnownImageName": "ubuntu-22.04" + } + ] + } + } + } + ] +} +``` + +Each image can have the following properties. + +| Property | Description | +|----------|-------------| +| `aliases` | An optional list of aliases. You can then refer to the image using the aliases instead of the full resource ID of the image. | +| `resourceID` | The resource ID of the image to use. Required when using [Azure Compute Gallery images](#azure-compute-gallery-images) or [selected marketplace images](#selected-marketplace-images). | +| `wellKnownImageName` | The alias of the Azure Pipelines image. Required when using [Azure Pipelines images](#azure-pipelines-images). | +| `buffer` | When [standby agents](./configure-scaling.md#standby-agent-mode) are enabled, `buffer` designates which percentage of standby agents to be allocated to this image. The total of all image `buffer` values must equal 100. | + +The following example defines three images. Standby agents are enabled, with 100% of the standby agents allocated to the `windows-2022` image. + +```json +"images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest", + "aliases": [ + "ubuntu-20.04-gen2" + ], + "buffer": "0" + }, + { + "buffer": "100", + "wellKnownImageName": "windows-2022" + }, + { + "buffer": "0", + "wellKnownImageName": "ubuntu-22.04" + } +] +``` + +#### [Azure CLI](#tab/azure-cli/) + +Images are configured in the `fabric-profile` section of the Managed DevOps Pools resource properties. + +```azurecli +az mdp pool create \ + --fabric-profile fabric-profile.json + # other parameters omitted for space +``` + +The following example shows the `images` section of the **fabric-profile.json** file and specifies three images. For more information on the schema for images, see the following sections in this article. + +```json +{ + "vmss": { + "sku": {...}, + "images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest", + "aliases": [ + "ubuntu-20.04-gen2" + ], + "buffer": "0" + }, + { + "buffer": "100", + "wellKnownImageName": "windows-2022" + }, + { + "buffer": "0", + "wellKnownImageName": "ubuntu-22.04" + } + ], + "osProfile": {...}, + "storageProfile": {...} + } +} +``` + +Each image can have the following properties. + +| Property | Description | +|----------|-------------| +| `aliases` | An optional list of aliases. You can then refer to the image using the aliases instead of the full resource ID of the image. | +| `resourceID` | The resource ID of the image to use. Required when using [Azure Compute Gallery images](#azure-compute-gallery-images) or [selected marketplace images](#selected-marketplace-images). | +| `wellKnownImageName` | The alias of the Azure Pipelines image. Required when using [Azure Pipelines images](#azure-pipelines-images). | +| `buffer` | When [standby agents](./configure-scaling.md#standby-agent-mode) are enabled, `buffer` designates which percentage of standby agents to be allocated to this image. The total of all image `buffer` values must equal 100. | + +The following example defines three images. Standby agents are enabled, with 100% of the standby agents allocated to the `windows-2022` image. + +```json +{ + "vmss": { + "sku": {...}, + "images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest", + "aliases": [ + "ubuntu-20.04-gen2" + ], + "buffer": "0" + }, + { + "buffer": "100", + "wellKnownImageName": "windows-2022" + }, + { + "buffer": "0", + "wellKnownImageName": "ubuntu-22.04" + } + ], + "osProfile": {...}, + "storageProfile": {...} + } +} +``` + +* * * + +If you choose a single image, all pipelines run in your pool using that image. If you choose multiple images, you can specify the image to use on a per-pipeline basis. For more information, see [Use multiple images per pool](#use-multiple-images-per-pool-with-aliases). + +> [!IMPORTANT] +> If you have multiple images in your pool, and don't use demands in your pipelines to designate an image, the pipelines run using the first listed image in your pool. You can change the order of the images in your pool by changing the order of the images in the `images` list in the `fabricProfile` section (if using [templates](./configure-images.md?&tabs=arm#choose-your-pools-image)), or by ordering the [images in the images list](./configure-pool-settings.md#images) in the Azure portal using drag and drop. + +You can choose from the following types of images. + +* [Azure Pipelines images](#azure-pipelines-images) - Choose from the same images that Microsoft-hosted agents use. +* [Selected marketplace images](#selected-marketplace-images) - Choose from a set of curated Microsoft published Azure Marketplace VM images. +* [Azure Compute Gallery images](#azure-compute-gallery-images) - Choose from your own Azure Compute Galleries images. You must assign the Reader role to the DevOpsInfrastructure Service Principal for the Azure Compute Gallery images you want to use. For more information, see [Grant Reader role access to the DevOpsInfrastructure Service Principal](#grant-reader-role-access-to-the-devopsinfrastructure-service-principal). + +## Azure Pipelines images + +Managed DevOps Pools provides several preconfigured images that have the same software as selected Microsoft-hosted agents for Azure Pipelines. + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="./media/configure-images/image-library-azure-pipelines-images.png" alt-text="Screenshot of Azure Pipelines images."::: + +#### [ARM template](#tab/arm/) + +To specify an Azure Pipelines image, provide the alias of the image using the `wellKnownImageName` property. See a [list of Azure Pipelines image predefined aliases.](#azure-pipelines-image-predefined-aliases) + +```json +"images": [ + { + "wellKnownImageName": "windows-2022" + } +] +``` + +#### [Azure CLI](#tab/azure-cli/) + +To specify an Azure Pipelines image, provide the alias of the image using the `wellKnownImageName` property. See a [list of Azure Pipelines image predefined aliases.](#azure-pipelines-image-predefined-aliases) + +```json +"images": [ + { + "wellKnownImageName": "windows-2022" + } +] +``` + +* * * + +Each image includes the following installed software. + +| Image | Included software | +|-------|-------------------| +| Azure Pipelines - Windows Server 2022 | [Included software](https://github.com/actions/runner-images/blob/main/images/windows/Windows2022-Readme.md) | +| Azure Pipelines - Windows Server 2019 | [Included software](https://github.com/actions/runner-images/blob/main/images/windows/Windows2019-Readme.md) | +| Azure Pipelines - Ubuntu 24.04 | [Included software](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md) | +| Azure Pipelines - Ubuntu 22.04 | [Included software](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md) | +| Azure Pipelines - Ubuntu 20.04 | [Included software](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md) | + +## Selected marketplace images + +Managed DevOps Pools provides a set of curated Microsoft published Azure Marketplace VM images for use in your pools. + +:::image type="content" source="./media/configure-images/image-library-marketplace-images.png" alt-text="Screenshot of selected marketplace images."::: + +#### [Azure portal](#tab/azure-portal/) + +Choose **Selected marketplace images**, choose the desired image, and choose the desired version. Choose **latest** to always use the latest version of the image. + +#### [ARM template](#tab/arm/) + +To specify a selected marketplace image, provide the resource ID of the image using the `resourceId` property. + +```json +"images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest" + } +] +``` + +#### [Azure CLI](#tab/azure-cli/) + +To specify selected marketplace image, provide the resource ID of the image using the `resourceId` property. + +```json +"images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest" + } +] +``` + +* * * + +## Azure Compute Gallery images + +Choose **Azure Compute Gallery images** to specify an image from any Azure Compute Galleries that are available in your subscriptions. [Generalized](/azure/virtual-machines/generalize) images with the following operating systems are supported. + +* Windows Server 2019 +* Windows Server 2022 +* Windows 11 +* Ubuntu 20.04 +* Ubuntu 22.04 +* Ubuntu 24.04 +* Debian 9 +* RHEL 8 +* RHEL 9 +* SUSE 12 +* SUSE 15 + +> [!IMPORTANT] +> Managed DevOps Pools supports only [generalized](/azure/virtual-machines/generalize) Azure Compute Gallery images. + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="./media/configure-images/image-library-compute-gallery-images.png" alt-text="Screenshot of Azure Compute Gallery images."::: + +#### [ARM template](#tab/arm/) + +To specify an Azure Compute Gallery image, provide the resource ID of the image using the `resourceId` property. + +```json +"images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest" + } +] +``` + +#### [Azure CLI](#tab/azure-cli/) + +To specify selected marketplace image, provide the resource ID of the image using the `resourceId` property. + +```json +"images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest" + } +] +``` + +* * * + +### Grant Reader role access to the DevOpsInfrastructure Service Principal + +> [!IMPORTANT] +> Assign the Reader role to the DevOpsInfrastructure Service Principal for the Azure Compute Gallery images you want to use. If you select an Azure Compute Gallery image that doesn't have this access configured, pool creation fails. You can assign the Reader role individually at the image level, or at the image gallery level for all images in the gallery. + +1. Go to the desired resource in the Azure portal. To be able to use all images in a gallery, go to Azure Compute Gallery in the Azure portal. To use a specific image only, go to that image. +1. Select **Access control (IAM)**. +1. Select **Add** > **Add role assignment** to open the **Add role assignment** page. +1. Assign the following role. For detailed steps, see [Assign Azure roles using the Azure portal](/azure/role-based-access-control/role-assignments-portal). + + | Setting | Value | + | --- | --- | + | Role | Reader | + | Assign access to | Service Principal | + | Members | DevOpsInfrastructure | + + :::image type="content" source="./media/configure-images/add-role-assignment-button.png" alt-text="Screenshot of Add role assignment." + +## Use multiple images per pool with aliases + +If you have multiple images in your pool, you can configure your Azure DevOps pipeline to use a specific image by referencing an alias for that image. + +If you have multiple images in your pool, and don't use demands in your pipelines to designate an image, the pipelines run using the first listed image in your pool. You can change the order of the images in your pool by changing the order of the images in the `images` list in the `fabricProfile` section (if using [templates](./configure-images.md?tabs=arm#choose-your-pools-image)), or by ordering the [images in the images list](./configure-pool-settings.md#images) in the Azure portal using drag and drop. + +> [!TIP] +> If your pipelines experience problems after adding a new image to your pool for the first time, check the ordering of the images in the list, and consider using demands and aliases to explicitly designate which image to use for each pipeline. + +### Configure image aliases + +#### [Azure portal](#tab/azure-portal/) + +To add and manage image aliases, go to the **Images** section of pool settings and choose **...**, **Add alias**. + +:::image type="content" source="./media/configure-images/add-alias-menu.png" alt-text="Screenshot of add alias menu option." + +Add any desired aliases to the **Alias** list, and choose **Save**. + +:::image type="content" source="./media/configure-images/add-alias-pane.png" alt-text="Screenshot of the alias pane." + +The following example shows a pool with two Azure Pipelines images and one selected marketplace image. The Azure Pipeline images have their default aliases displayed, and the selected marketplace image has a single configured alias named **ubuntu-20.04-gen2**. + +:::image type="content" source="./media/configure-images/multiple-images-with-aliases.png" alt-text="Screenshot of a pool with multiple images with aliases." + +#### [ARM template](#tab/arm/) + +To configure aliases, specify them in the `aliases` list. The following example defines one image with a single alias named `ubuntu-20.04-gen2`. + +```json +"images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest", + "aliases": [ + "ubuntu-20.04-gen2" + ] + } +] +``` + +#### [Azure CLI](#tab/azure-cli/) + +To configure aliases, specify them in the `aliases` list. The following example defines one image with a single alias named `ubuntu-20.04-gen2`. + +```json +"images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/0001-com-ubuntu-server-focal/skus/20_04-lts-gen2/versions/latest", + "aliases": [ + "ubuntu-20.04-gen2" + ] + } +] +``` + +* * * + +#### Azure Pipelines image predefined aliases + +In addition to any aliases that you configure, Azure Pipelines images have the following predefined aliases. + +| Azure Pipelines image | Predefined alias | +|-----------------------|------------------| +| Azure Pipelines - Windows Server 2022 | `windows-2022` | +| Azure Pipelines - Windows Server 2019 | `windows-2019` | +| Azure Pipelines - Ubuntu 24.04 | `ubuntu-24.04` | +| Azure Pipelines - Ubuntu 22.04 | `ubuntu-22.04` | +| Azure Pipelines - Ubuntu 20.04 | `ubuntu-20.04` | + +### Use demands to specify an image + +If you have multiple images in your pool, you can configure a pipeline to run on a specific image by using a [demand](/azure/devops/pipelines/yaml-schema/pool-demands) named `ImageOverride`. When you specify the `ImageOverride` demand in your pipeline, Managed DevOps Pools sends the job only to agents using that image. + +To run a pipeline on the Ubuntu 20.04 image from the previous example that had an `ubuntu-20.04-gen2` alias, specify the following demand in the `pool` section of your pipeline. + +```yml +pool: + name: fabrikam-dev-pool # Name of Managed DevOps Pool + demands: + - ImageOverride -equals ubuntu-20.04-gen2 +``` + +> [!IMPORTANT] +> Don't put quotes around the alias name in the `ImageOverride` demand, even if it has spaces in the name. + +To run a pipeline using an Azure Pipelines image in your pool, use the alias in the previous table. To run a pipeline on the Azure Pipelines Windows Server 2022 image from the previous example, specify the following demand in the `pool` section of your pipeline. + +```yml +pool: + name: fabrikam-dev-pool # Name of Managed DevOps Pool + demands: + - ImageOverride -equals windows-2022 +``` + +## See also + +* [Configure pool settings](./configure-pool-settings.md) diff --git a/docs/managed-devops-pools/configure-networking.md b/docs/managed-devops-pools/configure-networking.md new file mode 100644 index 00000000000..d1df7b5c4c5 --- /dev/null +++ b/docs/managed-devops-pools/configure-networking.md @@ -0,0 +1,195 @@ +--- +title: Configure networking +description: Learn how to configure networking for Managed DevOps Pools. +ms.date: 11/13/2024 +--- + +# Configure Managed DevOps Pools networking + +Managed DevOps Pools agents can be configured to run in an isolated virtual network, or into an existing virtual network. This article describes how to configure your Managed DevOps Pool to run agents in your virtual network. + +## Adding agents to your own virtual network + +You may want to add agents from Managed DevOps Pools to your own virtual network for scenarios such as: + +* Your CI/CD Agents need to access resources that are only available in your company network through a service like Express Route +* Your CI/CD Agents need to access resources that are isolated to private endpoints +* You want to network isolate your CI/CD infrastructure by bringing your own VNet with company specific firewall rules +* Any other unique use cases that can't be achieved by out-of-box Managed DevOps Pools networking related features + +You can add your pool's agents to your virtual network using the following steps. + +1. [Create or bring your virtual network and subnet](#create-or-bring-your-virtual-network-and-subnet) +2. [Delegate the subnet to Microsoft.DevOpsInfrastructure/pools](#delegate-the-subnet-to-microsoftdevopsinfrastructurepools) +3. [Associate the subnet with your Managed DevOps Pool](#associate-the-subnet-with-your-managed-devops-pool) + +The previous steps delegate the subnet for exclusive access by the pool and the subnet can't be used by other pools or resources. +In order to connect multiple pools to the same virtual network, multiple subnets can be used, each delegated and associated with their own pool. + +## Create or bring your virtual network and subnet + +The subnet must have enough address space to accommodate the max pool size of the pool you want to associate (include the 5 IP address Azure reserves in the subnet). +If you're using Express Route, you need to temporary drop or change the management lock on the resource group to allow writes. + +> [!IMPORTANT] +> The Managed DevOps Pool and virtual network must be in the same region, or you'll get an error similar to the following when you try to create the pool or update the network configuration. `Virtual network MDPVN is in region eastus, but pool mdpnonprodsub is in region australiaeast. These must be in the same region.` + +### Grant Reader and Network Contributor access to DevOpsInfrastructure service principal + +Ensure the DevOpsInfrastructure principal has the following access on the virtual network: +- `Reader` and `Network Contributor` +- Or add the following permission to a custom role: + - `Microsoft.Network/virtualNetworks/*/read` + - `Microsoft.Network/virtualNetworks/subnets/join/action` + - `Microsoft.Network/virtualNetworks/subnets/serviceAssociationLinks/validate/action` + - `Microsoft.Network/virtualNetworks/subnets/serviceAssociationLinks/write` + - `Microsoft.Network/virtualNetworks/subnets/serviceAssociationLinks/delete` + +Make a custom role for the **Service Association Link** access. An example role can be created at the resource group or subscription level in the Access Control tab, as shown in the following example. + +:::image type="content" source="./media/configure-networking/customrole.png" alt-text="Screenshot of custom role permissions."::: + +### To check the DevOpsInfrastructure principal access + +1. Choose **Access control (IAM)** for the virtual network, and choose **Check access**. + + :::image type="content" source="./media/configure-networking/permissions-check-access.png" alt-text="Screenshot of VNet Permissions for SubNet Delegation."::: + +2. Search for **DevOpsInfrastructure** and select it. + + :::image type="content" source="./media/configure-networking/devops-infrastructure-access.png" alt-text="Screenshot of selecting AzureDevOpsInfrastructure principal."::: + +3. Verify **Reader** access. Verify that `Microsoft.Network/virtualNetworks/subnets/join/action`, `Microsoft.Network/virtualNetworks/subnets/serviceAssociationLinks/validate/action` and `Microsoft.Network/virtualNetworks/subnets/serviceAssociationLinks/write` access is assigned. Your custom role should appear here. + + :::image type="content" source="./media/configure-networking/verify-permissions.png" alt-text="Screenshot of VNet Permissions."::: + +4. If **DevOpsInfrastructure** doesn't have those permissions, add them by choosing **Access control (IAM)** for the virtual network, and choose **Grant access to this resource** and add them. + +## Delegate the subnet to Microsoft.DevOpsInfrastructure/pools + +The subnet needs to be delegated to the `Microsoft.DevOpsInfrastructure/pools` to be used. +Open the subnet properties in the Portal and select `Microsoft.DevOpsInfrastructure/pools` under the Subnet Delegation section and choose **Save**. + +:::image type="content" source="./media/configure-networking/MDP-BYO-Networking-MDPSubNet-Delegation.png" alt-text="Screenshot of configuring the subnet delegation."::: + +This delegates the subnet for exclusive access for the pool and the subnet can't be used by other pools or resources. In order to connect multiple pools to the same virtual network, multiple subnets must be used, each delegated and associated with their own pool. More information on subnet delegation can be found [here](/azure/virtual-network/subnet-delegation-overview). + +Once the subnet is delegated to `Microsoft.DevOpsInfrastructure/pools`, the pool can be updated to use the subnet. + +## Associate the subnet with your Managed DevOps Pool + +#### [Azure portal](#tab/azure-portal/) + +1. If you're creating a new pool, go to the **Networking** tab. To update an existing pool, go to **Settings** > **Networking**, and choose **Agents injected into existing virtual network**, **Configure**. + + :::image type="content" source="./media/configure-networking/inject-agents-configure-option.png" alt-text="Screenshot of configure option."::: + +1. Choose the **Subscription**, **Virtual Network**, and **Subnet** you delegated to `Microsoft.DevOpsInfrastructure/pools`, and choose **Ok**. + + :::image type="content" source="./media/configure-networking/subnet-resource.png" alt-text="Screenshot of associating the subnet to the pool."::: + +Once the network update completes, newly created resource in the pool will use the delegated subnet. + +#### [ARM template](#tab/arm/) + +If you are using ARM templates, add a `networkProfile` property if it doesn't already exist, then add a `subnetId` property under `networkProfile` with the resource ID of your subnet. + +```json +{ + "name": "MyManagedDevOpsPool", + "type": "Microsoft.DevOpsInfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "networkProfile": { + "subnetId":"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVirtualNetwork/subnets/mySubnet", + } + ... + } +} +``` + + +#### [Azure CLI](#tab/azure-cli/) + +Networking is configured using the `networkProfile` property in the `fabricProfile` section when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. For an isolated network, omit the `networkProfile` property when creating a pool. + +```azurecli +az mdp pool create \ + --fabric-profile fabric-profile.json + # other parameters omitted for space +``` + +The following example shows the `networkProfile` section of the **fabric-profile.json** file. + +```json +{ + "vmss": { + "sku": {...}, + "images": [...], + "osProfile": {...}, + "storageProfile": {...}, + "networkProfile": { + "subnetId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVirtualNetwork/subnets/mySubnet" + } + } +} +``` + +* * * + +## Restricting outbound connectivity + +If you have systems in place on your network (NSG, Firewall etc.) which restrict outbound connectivity, you need to ensure that the following domains can be accessed, otherwise your Managed DevOps Pool will not be functional. +All of them are HTTPS, unless otherwise stated. + +* Highly secure endpoints that our service depends on: + * `*.prod.manageddevops.microsoft.com` - Managed DevOps Pools endpoint + * `rmprodbuilds.azureedge.net` - Worker binaries + * `vstsagentpackage.azureedge.net` and `https://download.agent.dev.azure.com` - Azure DevOps agent CDN location + * `*.queue.core.windows.net` - Worker queue for communicating with Managed DevOps Pools service + * `server.pipe.aria.microsoft.com` - Common client side telemetry solution (and used by the Agent Pool Validation extension among others) + * `azure.archive.ubuntu.com` - Provisioning Linux machines - this is HTTP, not HTTPS + * `www.microsoft.com` - Provisioning Linux machines + * `security.ubuntu.com` - Provisioning Linux machines +* Less secure, more open endpoints that our service depends on: + * Needed by our service: + * `packages.microsoft.com` - Provisioning Linux machines + * `ppa.launchpad.net` - Provisioning Ubuntu machines + * `dl.fedoraproject.org` - Provisioning certain Linux distros + * Needed by Azure DevOps agent: + * `dev.azure.com` + * `*.services.visualstudio.com` + * `*.vsblob.visualstudio.com` + * `*.vssps.visualstudio.com` + * `*.visualstudio.com` + These entries are the minimum domains required. If you have any issues, see [Azure DevOps allowlist](/azure/devops/organizations/security/allow-list-ip-url) for the full list of domains required. +* Azure related endpoints: + Azure VMs may route traffic to certain Azure features through your subnet. For these requests, you have the option of routing requests through Azure directly, or enabling access through your network. + 1. [Configuring Azure traffic to run through Service Endpoints](/azure/virtual-network/virtual-network-service-endpoints-overview) + + Routing traffic through Azure directly avoids adding throughput to your NSGs or Firewalls, and does not require that you allowlist the domains listed in the following option. + + For example, using the [data disk](./configure-storage.md) feature will involve network calls to Azure Storage. Enabling **Microsoft.Storage** service endpoint on your network will route traffic directly through Azure, avoiding your network rules and reducing load. + 2. If you want to avoid routing traffic through Service Endpoints, these are the domains to allowlist for specific features. + + * `md-*.blob.storage.azure.net` - Required to [configure a data disk](./configure-storage.md) + +If you configure your Azure DevOps Pipeline to run inside of a container, you need to also allowlist the source of the container image (Docker or ACR). + +## Configure the Azure DevOps Agent to run behind a Proxy + +If you configured a proxy service on your image and want your workloads running on your Managed DevOps pool to run behind this proxy, you must add the following environment variables on your image. + +* `VSTS_AGENT_INPUT_PROXYURL` - The URL of the configured proxy to run behind +* `VSTS_AGENT_INPUT_PROXYUSERNAME` - The username needed to use the proxy +* `VSTS_AGENT_INPUT_PROXYPASSWORD` - The password to use the proxy. + +For Windows, these environment variables should be system environment variables, and for Linux these variables should be in the **/etc/environment** file. Setting these system variables incorrectly or without a configured proxy service on the image causes provisioning of new agents to fail with network connectivity issues. + +If you are migrating from Azure Virtual Machine Scale Set agents and are already using the proxy environment variables on your image, as described in [Azure Virtual Machine Scale Set agents- Customizing Pipeline Agent Configuration](/azure/devops/pipelines/agents/scale-set-agents#customizing-pipeline-agent-configuration), no changes should be required. + +## See also + +* [Configure pool settings](./configure-pool-settings.md) diff --git a/docs/managed-devops-pools/configure-pool-settings.md b/docs/managed-devops-pools/configure-pool-settings.md new file mode 100644 index 00000000000..0dd1b8f1d5a --- /dev/null +++ b/docs/managed-devops-pools/configure-pool-settings.md @@ -0,0 +1,356 @@ +--- +title: Configure pool settings +description: Learn how to configure Managed DevOps Pools settings. +ms.date: 02/10/2025 +--- + +# Configure pool settings + +This article describes how to configure the basic settings of your Managed DevOps Pool. + +Go to **Overview** to view an overview of pool settings, [move Azure resources to a new resource group or subscription](/azure/azure-resource-manager/management/move-resource-group-and-subscription), or configure [tags](/azure/azure-resource-manager/management/tag-resources). Managed DevOps Pools passes up to 20 tags to the VM, and the rest are ignored. + +:::image type="content" source="media/pool-settings/essentials.png" alt-text="Screenshot of pool overview essentials." lightbox="media/pool-settings/essentials-expanded.png"::: + +To configure your pool, go to **Settings** > **Pool**. + +:::image type="content" source="media/pool-settings/pool-settings-menu.png" alt-text="Screenshot of Pool settings menu."::: + +Use the following settings to configure your Managed DevOps Pool. + +* [Dev Center project](#dev-center-project) +* [Azure DevOps organization](#azure-devops-organization) +* [Images](#images) +* [Maximum agents](#maximum-agents) +* [Agent size](#agent-size) +* [OS disk type](#os-disk-type) + +## Dev Center project + +#### [Azure portal](#tab/azure-portal/) + +Choose the Dev Center project for your Managed DevOps Pool. During pool creation, you can create a Dev Center and Dev Center project if you don't have one. + +:::image type="content" source="media/pool-settings/dev-center.png" alt-text="Screenshot of Dev Center settings."::: + +#### [ARM template](#tab/arm/) + +The dev center project is specified by the `devCenterProjectResourceId` property. + +```json + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "location": "eastus", + "tags": {}, + "properties": { + ... + "devCenterProjectResourceId": "/subscriptions/subscription_id_placeholder/resourceGroups/fabrikam-managed-devops-pools/providers/Microsoft.DevCenter/projects/fabrikam-dev-center-project" + } + } + ] +} +``` + +You can retrieve the `devCenterProjectResourceId` for your Dev Center project in the Azure portal by using the JSON View from the overview page of your Dev Center project, or you can retrieve it using the Azure CLI to query the project for its `id` property. In the following example, the `devCenterProjectResourceId` is retrieved from a Dev Center project named `fabrikam-dev-center-project` in the `fabrikam-managed-devops-pools` resource group. + +```azurecli + az devcenter admin project show --name fabrikam-dev-center-project --resource-group fabrikam-managed-devops-pools --query "id" +``` + +#### [Azure CLI](#tab/azure-cli/) + +The dev center project is specified by the `devcenter-project-id` parameter when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. + +```azurecli +az mdp pool create \ + --devcenter-project-id /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/resourceGroupName/providers/Microsoft.DevCenter/projects/devCenterProjectName + # other parameters omitted for space +``` + +You can retrieve the `devcenter-project-id` for your dev center project in the Azure portal by using the JSON View from the overview page of your dev center project, or you can retrieve it using the Azure CLI to query the project for its `id` property. In the following example, the `devcenter-project-id` is retrieved from a dev center project named `fabrikam-dev-center-project` in the `fabrikam-managed-devops-pools` resource group. + +```azurecli + az devcenter admin project show --name fabrikam-dev-center-project --resource-group fabrikam-managed-devops-pools --query "id" +``` + +* * * + +## Azure DevOps organization + +#### [Azure portal](#tab/azure-portal/) + +If your Managed DevOps Pool is configured for a single Azure DevOps organization, you can specify the organization in pool settings. + +:::image type="content" source="media/pool-settings/single-organization.png" alt-text="Screenshot of configuring a single organization."::: + +If your pool is configured for multiple organizations, the **Azure DevOps organization** setting is not present in pool settings. To configure your pool for use in multiple organizations, go to **Settings** > **Security**, and configure [Use pool in multiple organizations](./configure-security.md#use-pool-in-multiple-organizations). + +#### [ARM template](#tab/arm/) + +**Azure DevOps organization** is configured using the `organizations` list in the `organizationProfile` section. In the following example, a Managed DevOps Pool is configured for all projects in a single organization, with a parallelism of 4. For an example of configuring multiple organizations, see [Use pool in multiple organizations](./configure-security.md#use-pool-in-multiple-organizations). + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "organizationProfile": { + "organizations": [ + { + "url": "https://dev.azure.com/fabrikam-tailspin", + "projects": [], + "parallelism": 4 + } + ] + } + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +**Azure DevOps organization** is configured using the `organizations` list in the `organization-profile` parameter. In the following example, a Managed DevOps Pool is configured for all projects in a single organization, with a parallelism of 4. For an example of configuring multiple organizations, see [Use pool in multiple organizations](./configure-security.md#use-pool-in-multiple-organizations). + +```azurecli +az mdp pool create \ + --organization-profile organization-profile.json + # other parameters omitted for space +``` + +The following example shows the `organizations` list in the **organization-profile.json** file. + +```json +{ + "AzureDevOps": { + "organizations": [ + { + "url": "https://dev.azure.com/fabrikam-tailspin", + "projects": [], + "parallelism": 4 + } + ], + "permissionProfile": {...} + } +} +``` + +* * * + +By default, your Managed DevOps Pool is available to all projects in your specified organizations. To limit your pool to specific projects, see [Security settings - configure organization access](configure-security.md#configure-organization-access). + +## Maximum agents + +Specify the maximum count of agents that can be provisioned at a given time in your pool. For example, if you specify a **Maximum agents** value of **2**, you can run a maximum of two agents at the same time. If more than two jobs are queued, only two agents at a time will run jobs while the other jobs wait. + +You can view the current status and count of the provisioned agents in your pool using the [Agents](./view-agents.md) pane. All of the agents in the **Agents** view (with the exception of agents with a **Returned** status) are running on a virtual machine resource, and count towards the **Maximum agents** count. + +#### [Azure portal](#tab/azure-portal/) + +**Maximum agents** is configured in **Pool** settings for an existing pool, and on the **Basics** tab when creating a pool. + +:::image type="content" source="./media/pool-settings/maximum-agents.png" alt-text="Screenshot of Maximum agents setting."::: + +#### [ARM template](#tab/arm/) + +**Maximum agents** is configured using the `maximumConcurrency` property. In the following example, **Maximum agents** is set to `4`. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "maximumConcurrency": 4 + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +**Maximum agents** is configured using the `maximum-concurrency` parameter when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. In the following example, **Maximum agents** is set to `4`. + +```azurecli +az mdp pool create \ + --maximum-concurrency 4 + # other parameters omitted for space +``` + +* * * + +> [!NOTE] +> **Maximum agents** configures the maximum number of agents that can be provisioned at the same time, but your organization's self-hosted parallel jobs count specifies the number of jobs that can run concurrently. Ensure that you have enough self-hosted parallel jobs available in your organization to enable your agents to run jobs. For more information, see [Azure DevOps Services parallel job pricing](./pricing.md#azure-devops-services-parallel-job-pricing). + +## Agent size + +**Agent size** specifies the [Azure virtual machine size](/azure/virtual-machines/sizes) to use for hosting your Managed DevOps Pools agents. + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="./media/pool-settings/agent-size.png" alt-text="Screenshot of Agent size setting."::: + +Choose **Change size** to view and select an Azure virtual machine size that is available in your Azure region. Agent sizes (SKUs) with available Managed DevOps Pools quotas are marked as **Available**. You can request more quota for **Not Available** SKUs. Once a quota request for a **Not Available** SKU is approved, it will then be listed as **Available**. [Learn more about Managed DevOps Pools quotas](./prerequisites.md#view-your-quotas). + +#### [ARM template](#tab/arm/) + +Agent size is configured using the `sku` property in the `fabricProfile` section. In the following example, a **Standard_D2ads_v5** VM size is specified. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "fabricProfile": { + "sku": { + "name": "Standard_D2ads_v5" + } + } + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +Agent size is configured using the `sku` property in the `fabricProfile` section when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. In the following example, a **Standard_D2ads_v5** VM size is specified. + +```azurecli +az mdp pool create \ + --fabric-profile fabric-profile.json + # other parameters omitted for space +``` + +The following example shows the `sku` section of the **fabric-profile.json** file. + +```json +{ + "vmss": { + "sku": { + "name": "Standard_D2ads_v5" + }, + "images": [...], + "osProfile": {...}, + "storageProfile": {...} + } +} +``` + +* * * + +If your subscription doesn't have the capacity to configure your pool with desired Azure VM SKU and maximum agents count, you'll receive an error similar to the following message. `Cores needed to complete this request is 8, which exceeds the current limit of 0 for SKU family standardDDSv4Family in region eastus. Please choose a different region if possible, or request additional quota at https://portal.azure.com/#view/Microsoft_Azure_Support/NewSupportRequestV3Blade/issueType/quota/subscriptionId/subscription_id_placeholder/topicId/3eadc5d3-b59a-3658-d8c6-9c729ba35b97`. To resolve the issue, see [Review Managed DevOps Pools quotas](./prerequisites.md#review-managed-devops-pools-quotas). + +Not all SKUs are supported for all Azure regions. If you receive an error like `SKU family is not available in location `, ensure your SKU size is supported for your region. For more information, see [Sizes for virtual machines in Azure](/azure/virtual-machines/sizes) and [Products available by region](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/). + +## OS disk type + +Managed DevOps Pools provides the following disk types for the OS disk. + +* Standard +* Standard SSD +* Premium SSD + +The default OS disk type is **Standard**. If your workload's throughput exceeds the level of the standard tier, you can potentially gain a performance improvement in your workload by upgrading to a more performant disk type. For more information on disk types and performance, see [Azure Managed disk types](/azure/virtual-machines/disks-types). + +#### [Azure portal](#tab/azure-portal/) + +**OS disk type** is configured in **Pool** settings for an existing pool, and on the **Basics** tab when creating a pool. + +:::image type="content" source="./media/pool-settings/os-disk-type.png" alt-text="Screenshot of OS disk type setting."::: + +#### [ARM template](#tab/arm/) + +OS disk type is configured using the `osDiskStorageAccountType` property in the `storageProfile` section. In the following example, a **Standard** OS disk type is specified. Choose **Standard**, **StandardSSD**, or **Premium**. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "storageProfile": { + "osDiskStorageAccountType": "Standard" + } + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + + In the following example, a **Standard** OS disk type is specified. Choose **Standard**, **StandardSSD**, or **Premium**. + +OS disk type is configured using the `osDiskStorageAccountType` property in the `storageProfile` section in the `fabric-profile` parameter. In the following example, a **Standard** OS disk type is specified. Choose **Standard**, **StandardSSD**, or **Premium**. + +```azurecli +az mdp pool create \ + --fabric-profile fabric-profile.json + # other parameters omitted for space +``` + +The following example shows the `storageProfile` section of the **fabric-profile.json** file. + +```json +{ + "vmss": { + "sku": {...}, + "images": [...], + "osProfile": {...}, + "storageProfile": { + "osDiskStorageAccountType": "Standard", + "dataDisks": [] + } + } +} +``` + +* * * + +## Images + +Managed DevOps Pools provides you with several options for virtual machine images for running pipelines in your pool. You can create your pool using selected Azure Marketplace VM images, use your own custom images in an Azure Compute Gallery, or use the same Windows and Linux images used by Azure Pipelines Microsoft-hosted agents. + +:::image type="content" source="./media/configure-images/configure-pool-image.png" alt-text="Screenshot of configure image."::: + +You can configure your pool to use a single image or multiple images, and use aliases to configure your pipelines to use a specific image. For more information, see [Configure Managed DevOps Pools images](./configure-images.md). + +> [!IMPORTANT] +> If you have multiple images in your pool, and don't use [demands in your pipelines to designate an image](./configure-images.md#use-multiple-images-per-pool-with-aliases), the pipelines run using the first listed image in your pool. You can change the order of the images in your pool by changing the order of the images in the `images` list in the `fabricProfile` section (if using [templates](./configure-images.md?tabs=arm#choose-your-pools-image)), or by ordering the images in the images list in the Azure portal using drag and drop. + +## See also + +* [Configure images](./configure-images.md) diff --git a/docs/managed-devops-pools/configure-scaling.md b/docs/managed-devops-pools/configure-scaling.md new file mode 100644 index 00000000000..5263562a7a5 --- /dev/null +++ b/docs/managed-devops-pools/configure-scaling.md @@ -0,0 +1,890 @@ +--- +title: Configure scaling +description: Learn the different performance options for Managed DevOps Pools and their impact on agent performance. +ms.date: 11/15/2024 +--- + +# Configure scaling + +Configure scaling settings to manage the performance and cost of your Managed DevOps Pool. For information on pricing and performance, see [Manage cost and performance](manage-costs.md). + +## Agent state + +Managed DevOps Pools can be configured as stateless or stateful. + +* [Stateless pools](#stateless-pools) - Provide a fresh agent for every job. +* [Stateful pools](#stateful-pools) - Allow sharing of agents between multiple jobs. + +The default setting for a Managed DevOps pool is stateless (**Fresh agent every time**) but in some cases teams might want to reuse agents in order to reuse the packages or files created during the previous pipeline run. Build workload is a common scenario where teams want to preserve state and reuse agents. You can achieve stateful pools through Managed DevOps Pools while balancing it with security best practices. By default an agent can be reused for a maximum of 7 days but you can configure it to be recycled sooner. + +> [!NOTE] +> Stateless pools or use of the agent state setting **Fresh agent every time** are recommended by security experts as a defense against supply chain attacks. + +### Stateless pools + +When a stateless agent is configured, a new agent is procured for each job, and is discarded after the job completes. + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="media/agent-performance/stateless-agent.png" alt-text="Screenshot of a stateless agent."::: + + +#### [ARM template](#tab/arm/) + +Agents are configured using the `agentProfile` property in the Managed DevOps Pools resource. In the following example, a **Stateless** agent is specified. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "agentProfile": { + "kind": "Stateless" + } + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +Agents are configured using the `agent-profile` parameter when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. + +In the following example, a **Stateless** agent is specified with no standby agents. + +```azurecli +az mdp pool create \ + --agent-profile agent-profile.json + # other parameters omitted for space +``` + +The following example shows the contents of the **agent-profile.json** file. + +```json +{ + "Stateless": {} +} +``` + +* * * + +When **Agent state** is set to **Fresh agent every time**, a new agent is procured for each job, and is discarded after the job completes. + +### Stateful pools + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="media/agent-performance/stateful-agent.png" alt-text="Screenshot of a stateful agent."::: + + +#### [ARM template](#tab/arm/) + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "agentProfile": { + "maxAgentLifetime": "7.00:00:00", + "gracePeriodTimeSpan": "00:30:00", + "kind": "Stateful" + } + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +Agents are configured using the `agent-profile` parameter when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. + +In the following example, a **Stateful** agent is specified with a seven day maximum lifetime and a thirty minute grace period. + +```azurecli +az mdp pool create \ + --agent-profile agent-profile.json + # other parameters omitted for space +``` + +The following example shows the contents of the **agent-profile.json** file. + +```json +{ + "Stateful": + { + "maxAgentLifetime": "7.00:00:00", + "gracePeriodTimeSpan": "00:30:00" + } +} +``` + +* * * + +When **Same agent can be used by multiple builds** (`"kind": "stateful"` in resources templates or `{ "stateful": {...} }` in Azure CLI) is enabled, agents in the pool are considered to be stateful. Stateful pools are configured using the following settings. + +* **Max time to live for standby agents** (`maxAgentLifetime`) configures the maximum duration an agent in a stateful pool can run before it is shut down and discarded. The format for **Max time to live for standby agents** is `dd.hh:mm:ss`. The default value of **Max time to live for standby agents** is set to the maximum allowed duration of seven days (`7.00:00:00`). + +* **Grace Period** (`gracePeriodTimeSpan`) configures the amount of time an agent in a stateful pool waits for new jobs before shutting down after all current and queued jobs are complete. The format for **Grace Period** is `dd.hh:mm:ss` and the default is no grace period. + +While agents in stateless pools are shut down and discarded after every job, agents in stateful pools continue running if any of the following conditions are met. + +* If there is another job queued when the first job completes, Managed DevOps Pools sends that job to the agent that ran the first job instead of shutting it down. +* If there is a grace period configured for the pool, agents wait for new jobs for the duration specified by the grace period before shutting down. +* If [standby agents are enabled](#standby-agent-mode), and the agent image meets the criteria of the active provisioning period, the agent continues to run and wait for jobs. + +Running agents in stateful pools are shut down and discarded if they run continuously for the duration specified by **Max time to live for standby agents**, even if the previous conditions are true. For example, if **Max time to live for standby agents** is configured for three days, and **Standby agent mode** is set to **Manual, All Week Scheme (Machines available 24/7)**, the agents are restarted after three continuous days of uptime. + +> [!IMPORTANT] +> Agents in stateful pools can still be shut down and discarded after a job completes if there is no grace period, no active provisioning period for standby agents, and no queued jobs matching the agent. Once an agent is discarded, any state is lost. + +Grace period enables the most cost effective way of running stateful pools for pipelines with consistent load and does not require the use of standby agent mode to keep agents online and ready to accept jobs. + +## Standby agent mode + +When you create a pool, **Standby agent mode** is off by default, and there are no standby agents to immediately assign to your pipelines, which might have to wait a few moments, up to 15 minutes, for an agent to be provisioned on demand. For better performance, enable **Standby agent mode** and configure a standby agent schedule that provides capacity for your workload. + +When a standby agent schedule is configured, Managed DevOps Pools periodically compares the count of provisioned agents with the standby agent count specified by the current provisioning scheme, and starts new agents as required to maintain the standby agent count. You can view the current status and count of the agents in your pool using the [Agents](./view-agents.md) pane. + +> [!IMPORTANT] +> The provisioning count in a scheme can't be greater than the **Maximum agents** configured in [Pool settings](configure-pool-settings.md#maximum-agents). + +Standby agent mode is configured using the following settings: + +* **Off** - Standby agent mode is off and agents are provisioned on-demand when jobs are queued. +* [Manual](#manual) - Configure a manual standby schedule. +* [Automatic](#automatic) - Use an automatic standby schedule based on agent usage history and configurable for cost and performance. + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="media/agent-performance/standby-agent-mode.png" alt-text="Screenshot of standby agent mode selection."::: + +#### [ARM template](#tab/arm/) + +Standby agents are configured using the `resourcePredictionsProfile` section of the `agentProfile` property. Set `"kind": "Manual"` to configure a start from scratch, weekday scheme, or all week scheme, and specify the details of the scheme in the `resourcePredictions` section. Set `"kind": "Automatic"` to configure automatic standby agents. Omit the `ResourcePredictionsProfile` section to disable standby agents. See the following sections for details on how to configure each scaling type. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "agentProfile": { + "kind": "Stateless", + "resourcePredictionsProfile": { + "kind": "Manual" + }, + "resourcePredictions": {...} + } + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +Agents are configured using the `agent-profile` parameter when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. + +Standby agents are configured using the `resourcePredictionsProfile` section of the `agent-profile` parameter. Set `"Manual": {}` to configure a start from scratch, weekday scheme, or all week scheme, and specify the details of the scheme in the `resourcePredictions` section. Set `"Automatic": {}` to configure automatic standby agents. See the following sections for details on how to configure each scaling type. + +```azurecli +az mdp pool create \ + --agent-profile agent-profile.json + # other parameters omitted for space +``` + +The following example shows the contents of the **agent-profile.json** file. + +```json +{ + "Stateless": {}, + "resourcePredictionsProfile": { + "Manual": {} + }, + "resourcePredictions": {...} +} +``` + +* * * + +## Manual + +Manual mode is best suited for teams that have knowledge of their CI/CD pipelines usage patterns. If you select the manual option, you need to define your pre-provisioning scheme based on your understanding of when agents in the pool are most likely to get used and how many agents are likely to be used, and specify a provisioning count of agents that meet the projected demand. + +You can create your own provisioning schedule or choose from one of the predefined schedules, and you can configure the time zone to use for specifying the schedules. The default value for **Pre-provisioning TimeZone** is **(UTC) Coordinated Universal Time**. + +Manual standby agent configuration can be configured in one of the following three ways. + +* [Start from scratch](#start-from-scratch) - Configure a set of provisioning periods for standby agents +* [Weekday Scheme (Machines available during time period every weekday)](#weekday-scheme) - Configure a start and end time for standby agents to be available each weekday +* [All Week Scheme (Machines available 24/7)](#all-week-scheme) - Configure a fixed number of standby agents to be continuously available + +Each of the pre-provisioning quick starts has the following common settings in addition to the specific settings for that quick start. + +* **Pre-provisioning TimeZone** allows you to configure the time zone for the times in your pre-provisioning scheme. The default value for **Pre-provisioning TimeZone** is **(UTC) Coordinated Universal Time**. +* **Standby agent percentage** configures the percentage of standby agents you want for each image. You can enter `*` to ensure all images are provisioned equally, or you can specify an integer from 0 to 100 to represent a percentage. If you specify a percentage, the total for all images must equal 100. If you have a single image, specify `*` or 100. **Standby agent percentage** is configured in the `images` section when using ARM templates. For more information, see [Configure images](./configure-images.md). + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="media/agent-performance/manual-standby-mode.png" alt-text="Screenshot of manual standby mode."::: + +#### [ARM template](#tab/arm/) + +Manual standby agent provisioning is specified in the `resourcePredictionsProfile` section of `agentProfile`, and the details are configured in the `resourcePredictions` section. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "agentProfile": { + "kind": "Stateless", + "resourcePredictionsProfile": { + "kind": "Manual" + }, + "resourcePredictions": { + "timeZone": "Eastern Standard Time", + "daysData": [ + {}, + { + "00:00:00": 1, + "04:00:00": 0 + }, + {}, + {}, + {}, + {}, + {} + ] + } + } + } + } + ] +} +``` + +Specify the desired time zone for your scheme using the `timeZone` property. The default is `UTC`. To retrieve a list of time zone names for this property, see [TimeZoneInfo.GetSystemTimeZones Method](/dotnet/api/system.timezoneinfo.getsystemtimezones). + +The schedule for the standby agents is defined by the `daysData` list. The `daysData` list can have either one item or seven items. + +A `daysData` list with seven items maps to the days of the week, starting with Sunday. Each of these seven items can have zero or more `"time": count` entries, specifying a time in 24 hour format, and a standby agent count. The specified count of standby agents is maintained until the next `"time": count` entry, which can be on the same day, or on a following day. + +A `daysData` list with a single item defines an [All Week scheme](#all-week-scheme), where the single `"time": count` entry corresponds to the standby agent count for the entire week. + +The following example is a manual standby agent scheme, using `Eastern Standard Time`, with a single agent provisioned Monday through Friday, from 9:00 AM (standby agent count `1`) through 5:00 PM (standby agent count `0`). + +```json +{ + "kind": "Stateless", + "resourcePredictions": { + "timeZone": "Eastern Standard Time", + "daysData": [ + {}, + { + "09:00:00": 1, + "17:00:00": 0 + }, + { + "09:00:00": 1, + "17:00:00": 0 + }, + { + "09:00:00": 1, + "17:00:00": 0 + }, + { + "09:00:00": 1, + "17:00:00": 0 + }, + { + "09:00:00": 1, + "17:00:00": 0 + }, + {} + ] + }, + "resourcePredictionsProfile": { + "kind": "Manual" + } +} +``` + +A single `daysData` item contains a dictionary of times and standby agent counts. Each `"time" : count` entry specifies the number of standby agents to schedule starting at the specified time, in 24 hour format. Consecutive `"time" : count` entries specify a sequence of scheduled agent counts for that day. + +```json +"daysData": [ + {}, # Schedule of standby agent count adjustments for Sunday + { # Schedule of standby agent count adjustments for Monday + "09:00:00": 1, # Adjust standby agent count to 1 + "17:00:00": 0 # Adjust standby agent count to 0 + }, + { # Schedule of standby agent count adjustments for Tuesday + "09:00:00": 1, + "17:00:00": 0 + }, + { # Schedule of standby agent count adjustments for Wednesday + "09:00:00": 1, + "17:00:00": 0 + }, + { # Schedule of standby agent count adjustments for Thursday + "09:00:00": 1, + "17:00:00": 0 + }, + { # Schedule of standby agent count adjustments for Friday + "09:00:00": 1, + "17:00:00": 0 + }, + {} # Schedule of standby agent count adjustments for Saturday +] +``` + +Standby agent counts do not automatically reset back to zero at the end of a day or at the end of the week, and specifying an empty `daysData` item does not disable standby agents for that day. An empty `daysData` item means that there are no changes to the standby agent count schedule for that day. To set the standby agent to zero starting at a specific time period, you must explicitly provide a `"time" : count` entry with a `count` of `0`. + +#### Examples + +To make no adjustment to the standby agent count specified at the conclusion of the previous day (or week if you are configuring the first period of the week), specify a `daysData` item with zero entries. + +```json +{ +} +``` + +To schedule a single standby agent to start at `09:00:00` and stop at `17:00:00` (using the time zone specified by the `resourcePredictions` property), specify the following configuration. + +```json +{ + "09:00:00": 1, + "17:00:00": 0 +} +``` + +To schedule a single standby agent starting from midnight through `09:00:00`, followed by 10 standby agents until `17:00:00`, specify the following configuration. + +```json +{ + "00:00:00": 1, + "09:00:00": 10, + "17:00:00": 0 +} +``` + +To schedule a standby agent to be available starting at `09:00:00` on the specified day, and stopping at `17:00:00` the following day, use two consecutive `daysData` items. + +```json +{ + "09:00:00": `1` +}, +{ + "17:00:00": 0 +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +Agents are configured using the `agent-profile` parameter when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. + +```azurecli +az mdp pool create \ + --agent-profile agent-profile.json + # other parameters omitted for space +``` + +The following example shows the contents of the **agent-profile.json** file. + +Manual standby agent provisioning is specified in the `resourcePredictionsProfile` section of the `agent-profile` parameter, and the details are configured in the `resourcePredictions` section. + +```json +{ + "Stateless": {}, + "resourcePredictionsProfile": { + "Manual": {} + }, + "resourcePredictions": { + "timeZone": "Eastern Standard Time", + "daysData": [ + {}, + { + "00:00:00": 1, + "04:00:00": 0 + }, + {}, + {}, + {}, + {}, + {} + ] + } +} +``` + +Specify the desired time zone for your scheme using the `timeZone` property. The default is `UTC`. To retrieve a list of time zone names for this property, see [TimeZoneInfo.GetSystemTimeZones Method](/dotnet/api/system.timezoneinfo.getsystemtimezones). + +The schedule for the standby agents is defined by the `daysData` list. The `daysData` list can have either one item or seven items. + +A `daysData` list with seven items maps to the days of the week, starting with Sunday. Each of these seven items can have zero or more `"time": count` entries, specifying a time in 24 hour format, and a standby agent count. The specified count of standby agents is maintained until the next `"time": count` entry, which can be on the same day, or on a following day. + +A `daysData` list with a single item defines an [All Week scheme](#all-week-scheme), where the single `"time": count` entry corresponds to the standby agent count for the entire week. + +The following example is a manual standby agent scheme, using `Eastern Standard Time`, with a single agent provisioned Monday through Friday, from 9:00 AM (standby agent count `1`) through 5:00 PM (standby agent count `0`). + +```json +{ + "Stateless": {}, + "resourcePredictionsProfile": { + "Manual": {} + }, + "resourcePredictions": { + "timeZone": "Eastern Standard Time", + "daysData": [ + {}, + { + "09:00:00": 1, + "17:00:00": 0 + }, + { + "09:00:00": 1, + "17:00:00": 0 + }, + { + "09:00:00": 1, + "17:00:00": 0 + }, + { + "09:00:00": 1, + "17:00:00": 0 + }, + { + "09:00:00": 1, + "17:00:00": 0 + }, + {} + ] + } +} +``` + +A single `daysData` item contains a dictionary of times and standby agent counts. Each `"time" : count` entry specifies the number of standby agents to schedule starting at the specified time, in 24 hour format. Consecutive `"time" : count` entries specify a sequence of scheduled agent counts for that day. + +```json +"daysData": [ + {}, # Schedule of standby agent count adjustments for Sunday + { # Schedule of standby agent count adjustments for Monday + "09:00:00": 1, # Adjust standby agent count to 1 + "17:00:00": 0 # Adjust standby agent count to 0 + }, + { # Schedule of standby agent count adjustments for Tuesday + "09:00:00": 1, + "17:00:00": 0 + }, + { # Schedule of standby agent count adjustments for Wednesday + "09:00:00": 1, + "17:00:00": 0 + }, + { # Schedule of standby agent count adjustments for Thursday + "09:00:00": 1, + "17:00:00": 0 + }, + { # Schedule of standby agent count adjustments for Friday + "09:00:00": 1, + "17:00:00": 0 + }, + {} # Schedule of standby agent count adjustments for Saturday +] +``` + +Standby agent counts do not automatically reset back to zero at the end of a day or at the end of the week, and specifying an empty `daysData` item does not disable standby agents for that day. An empty `daysData` item means that there are no changes to the standby agent count schedule for that day. To set the standby agent to zero starting at a specific time period, you must explicitly provide a `"time" : count` entry with a `count` of `0`. + +#### Examples + +To make no adjustment to the standby agent count specified at the conclusion of the previous day (or week if you are configuring the first period of the week), specify a `daysData` item with zero entries. + +```json +{ +} +``` + +To schedule a single standby agent to start at `09:00:00` and stop at `17:00:00` (using the time zone specified by the `resourcePredictions` property), specify the following configuration. + +```json +{ + "09:00:00": 1, + "17:00:00": 0 +} +``` + +To schedule a single standby agent starting from midnight through `09:00:00`, followed by 10 standby agents until `17:00:00`, specify the following configuration. + +```json +{ + "00:00:00": 1, + "09:00:00": 10, + "17:00:00": 0 +} +``` + +To schedule a standby agent to be available starting at `09:00:00` on the specified day, and stopping at `17:00:00` the following day, use two consecutive `daysData` items. + +```json +{ + "09:00:00": `1` +}, +{ + "17:00:00": 0 +} +``` + +* * * + +### Start From scratch + +If you choose to start from scratch, you can add a list of provisioning periods to serve as your provisioning scheme. Each provisioning period consists of a start day, end day, time zone, start time, end time, and a count. Provisioning periods can't overlap each other. + +| Property | Description | +|----------|-------------| +| Multi-day | When checked, you can configure both a Start Day and an End Day for your provisioning scheme. | +| Until next period | When checked, the provisioning period runs from the Start Time until the start of the next provisioning period. | +| Start Day | The day that the provisioning period starts. | +| End Day | The day the provisioning period ends. Required if Multi-Day is checked. | +| Start Time | The time the provisioning period starts. | +| End Time | The time the provisioning period ends. Required unless **Until next period** is checked. | +| Count | The number of standby agents to provision. This number must be greater than zero, and must not be greater than the **Maximum agents** value configured in Pool settings. | + +After creating a provisioning period, you can delete or edit the period from the **Pre-provisioning scheme** list. + +The following example configures a manual scheme with 1 agent provisioned on Monday mornings from 12:00 AM to 5:00 AM EST. + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="media/agent-performance/manual-scaling-scheme.png" alt-text="Screenshot of manual scaling scheme."::: + +#### [ARM template](#tab/arm/) + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "agentProfile": { + "kind": "Stateless", + "resourcePredictionsProfile": { + "kind": "Manual" + }, + "resourcePredictions": { + "timeZone": "Eastern Standard Time", + "daysData": [ + {}, + { + "00:00:00": 1, + "04:00:00": 0 + }, + {}, + {}, + {}, + {}, + {} + ] + } + } + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +```json +{ + "Stateless": {}, + "resourcePredictionsProfile": { + "Manual": {} + }, + "resourcePredictions": { + "timeZone": "Eastern Standard Time", + "daysData": [ + {}, + { + "00:00:00": 1, + "04:00:00": 0 + }, + {}, + {}, + {}, + {}, + {} + ] + } +} +``` + +* * * + +### Weekday scheme + +If you choose the weekday scheme, you can specify a start time and end time in which the specified number of standby agents will be on standby each weekday. + +| Property | Description | +|----------|-------------| +| Start Time | The time the provisioning period starts. | +| End Time | The time the provisioning period ends. | +| Provisioning Count | The number of standby agents to provision. This number must be greater than zero, and must not be greater than the **Maximum agents** value configured in Pool settings. | + +The following example configures four agents to be used during working hours with 0 agents during non-working hours and weekends, using Eastern Standard Time. + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="media/agent-performance/manual-scaling-weekday-scheme.png" alt-text="Screenshot of weekday scheme."::: + +#### [ARM template](#tab/arm/) + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "agentProfile": { + "kind": "Stateless", + "resourcePredictionsProfile": { + "kind": "Manual" + }, + "resourcePredictions": { + "timeZone": "Eastern Standard Time", + "daysData": [ + {}, + { + "09:00:00": 4, + "17:00:00": 0 + }, + { + "09:00:00": 4, + "17:00:00": 0 + }, + { + "09:00:00": 4, + "17:00:00": 0 + }, + { + "09:00:00": 4, + "17:00:00": 0 + }, + { + "09:00:00": 4, + "17:00:00": 0 + }, + {} + ] + } + } + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +```json +{ + "Stateless": {}, + "resourcePredictionsProfile": { + "Manual": {} + }, + "resourcePredictions": { + "timeZone": "Eastern Standard Time", + "daysData": [ + {}, + { + "09:00:00": 4, + "17:00:00": 0 + }, + { + "09:00:00": 4, + "17:00:00": 0 + }, + { + "09:00:00": 4, + "17:00:00": 0 + }, + { + "09:00:00": 4, + "17:00:00": 0 + }, + { + "09:00:00": 4, + "17:00:00": 0 + }, + {} + ] + } +} +``` + +* * * + +### All Week Scheme + +If you choose the all week scheme, you can specify a number of agents you want available 24/7. + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="media/agent-performance/manual-scaling-all-week-scheme.png" alt-text="Screenshot of all week scheme."::: + +#### [ARM template](#tab/arm/) + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "agentProfile": { + "kind": "Stateless", + "resourcePredictionsProfile": { + "kind": "Manual" + }, + "resourcePredictions": { + "timeZone": "Eastern Standard Time", + "daysData": [ + { + "00:00:00": 1 + } + ] + } + } + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +```json +{ + "Stateless": {}, + "resourcePredictionsProfile": { + "Manual": {} + }, + "resourcePredictions": { + "timeZone": "Eastern Standard Time", + "daysData": [ + { + "00:00:00": 1 + } + ] + } +} +``` + +* * * + +## Automatic + +If you don't know your usage patterns and want to rely on automatic forecasting based on past data, choose **Automatic**. You can balance between cost and agent performance using a slider with the following five options. Managed DevOps Pools runs a query over your past three weeks of historical data (if available), organizing queued sessions of the pool into five minute periods, and assigns the specified percentile (to avoid spikes) to each hour. + +* **Most cost effective** (`MostCostEffective`) - 10th percentile +* **More cost effective** (`MoreCostEffective`) - 25th percentile +* **Balanced** (default) (`Balanced`) - 50th percentile +* **More performance** (`MorePerformance`) - 75th percentile +* **Best performance** (`BestPerformance`) - 90th percentile + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="media/agent-performance/automatic-scaling-setting.png" alt-text="Screenshot of automatic scaling setting."::: + +#### [ARM template](#tab/arm/) + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "agentProfile": { + "kind": "Stateless", + "resourcePredictionsProfile": { + "predictionPreference": "Balanced", + "kind": "Automatic" + } + } + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +```json +{ + "Stateless": {}, + "resourcePredictionsProfile": { + "Automatic": { + "predictionPreference": "Balanced" + } + } +} +``` + +* * * + +## See also + +* [Configure pool settings](./configure-pool-settings.md) +* [Manage cost and performance](./manage-costs.md) diff --git a/docs/managed-devops-pools/configure-security.md b/docs/managed-devops-pools/configure-security.md new file mode 100644 index 00000000000..6a4a2dc25fe --- /dev/null +++ b/docs/managed-devops-pools/configure-security.md @@ -0,0 +1,444 @@ +--- +title: Configure security +description: Learn how to configure security settings for Managed DevOps Pools. +ms.date: 11/18/2024 +--- + +# Configure Managed DevOps Pools security settings + +You can configure security setting for Managed DevOps Pools during pool creation by using the **Security** tab, and after pool creation by using the **Security** settings pane. + +## Configure organization access + +Be default, Managed DevOps Pools are configured for a single organization, with access to the pool granted to all projects in the organization. You can optionally limit access to specific projects in the organization, and you can grant access to additional organizations if desired. + +* [Use pool with a single organization](#use-pool-with-a-single-organization) +* [Use pool in multiple organizations](#use-pool-in-multiple-organizations) + +### Use pool with a single organization + +#### [Azure portal](#tab/azure-portal/) + +By default, Managed DevOps Pools is configured for use with a single Azure DevOps organization that you specify when you create the pool. When your pool is configured for a single organization, the organization name is displayed and configured in Pool settings + +By default, **Add pool to all projects** is set to **Yes**, and access to the Managed DevOps Pool is granted to all projects in the organization. Choose **No** to specify a list of projects to limit which projects in your organization can use the pool. + +:::image type="content" source="./media/configure-security/single-organization-projects.png" alt-text="Screenshot of configuring projects for a single organization."::: + +#### [ARM template](#tab/arm/) + +Organizations are configured in the `organizationProfile` property of the Managed DevOps Pools resource. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "organizationProfile": { + "organizations": [ + { + "url": "https://dev.azure.com/fabrikam-tailspin", + "projects": [], + "parallelism": 4 + } + ], + "permissionProfile": { + "kind": "CreatorOnly" + }, + "kind": "AzureDevOps" + } + } + ] +} +``` + +The `organizationProfile` section has the following properties. + +| Property | Description | +|------|-------------| +| `organizations` | A list of the organizations that can use your pool. `url` specifies the URL of the organization, `projects` is a list of project names that can use the pool (an empty list supports all projects in the organization), and `parallelism` specifies the number of agents that can be used by this organization. The sum of the parallelism for the organizations must match the maximum agents setting for the pool. | +| `permissionProfile` | Specify the permission granted to the Azure DevOps pool when it is created. This value can be set during pool creation only. Allowed values are `Inherit`, `CreatorOnly`, and `SpecificAccounts`. If `specificAccounts` is specified, provide a single email address or a list of email addresses for the `users` property; otherwise omit `users`. For more information, see [Pool administration permissions](./configure-security.md#pool-administration-permissions). | +| `kind` | This value specifies the type of organization for the pool, and must be set to `Azure DevOps`. | + +#### [Azure CLI](#tab/azure-cli/) + +Organizations are configured in the `organization-profile` parameter when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. + +```azurecli +az mdp pool create \ + --organization-profile organization-profile.json + # other parameters omitted for space +``` + +The following example shows an `organization-profile` object that is configured for all projects in the `fabrikam-tailspin` organization with `parallelism` set to `1`. + +```json +{ + "AzureDevOps": + { + "organizations": [ + { + "url": "https://dev.azure.com/fabrikam-tailspin", + "projects": [], + "parallelism": 1 + } + ] + } +} +``` + +The `organizationProfile` section has the following properties. + +| Property | Description | +|------|-------------| +| `AzureDevOps` | This value is the name of the object defined in `organization-profile` and must be set to `Azure DevOps`. | +| `organizations` | A list of the organizations that can use your pool. `url` specifies the URL of the organization, `projects` is a list of project names that can use the pool (an empty list supports all projects in the organization), and `parallelism` specifies the number of agents that can be used by this organization. The sum of the parallelism for the organizations must match the maximum agents setting for the pool. | +| `permissionProfile` | Specify the permission granted to the Azure DevOps pool when it is created. This value can be set during pool creation only. Allowed values are `Inherit`, `CreatorOnly`, and `SpecificAccounts`. If `specificAccounts` is specified, provide a single email address or a list of email addresses for the `users` property; otherwise omit `users`. For more information, see [Pool administration permissions](./configure-security.md#pool-administration-permissions). | + +* * * + +### Use pool in multiple organizations + +#### [Azure portal](#tab/azure-portal/) + +Enable **Use pool in multiple organizations** to use your pool with multiple Azure DevOps organizations. For each organization, specify the projects that are permitted to use the pool, or leave blank to allow all projects. Configure the **Parallelism** for each organization by specifying what portions of the concurrency, as specified by **Maximum agents** for the pool, to allocate to each organization. The sum of the parallelism for all organizations must equal the maximum concurrency of the pool. For example, if **Maximum agents** is set to five, the sum of the parallelism for the specified organizations must be five. If **Maximum agents** is set to one, you can only use the pool with one organization. + +In the following example, the pool is configured to be available for the **FabrikamResearch** and **FabrikamTest** projects in the **fabrikam-tailspin** organization, and to all projects in the **fabrikam-blue** organization. + +:::image type="content" source="./media/configure-security/use-pool-multiple-organizations.png" alt-text="Screenshot of configuring multiple organizations."::: + +If you receive an error like `The sum of parallelism for all organizations must equal the max concurrency.`, ensure that the [Maximum agents](./configure-pool-settings.md#maximum-agents) count for the pool matches the sum of the **Parallelism** column. + +#### [ARM template](#tab/arm/) + +Add additional organizations to the organizations list to configure your pool for use with multiple organizations. The following example has two organizations configured. The first organization is configured to use Managed DevOps Pools for all projects, and the second organizations is limited to two projects. In this example, the maximum agents setting for the pool is four, and each organization can use two of these four agents. + +```json +"organizationProfile": { + "organizations": [ + { + "url": "https://dev.azure.com/fabrikam-tailspin", + "projects": [], + "parallelism": 2 + }, + { + "url": "https://dev.azure.com/fabrikam-prime", + "projects": [ "fabrikam-dev", "fabrikam-test" ], + "parallelism": 2 + } + ], + "permissionProfile": { + "kind": "CreatorOnly" + }, + "kind": "AzureDevOps" +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +Organizations are configured in the `organization-profile` parameter when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. + +```azurecli +az mdp pool create \ + --organization-profile organization-profile.json + # other parameters omitted for space +``` + +Add additional organizations to the organizations list to configure your pool for use with multiple organizations. The following example has two organizations configured. The first organization is configured to use Managed DevOps Pools for all projects, and the second organizations is limited to two projects. In this example, the maximum agents setting for the pool is four, and each organization can use two of these four agents. + +```json +{ + "AzureDevOps": + { + "organizations": [ + { + "url": "https://dev.azure.com/fabrikam-tailspin", + "projects": [], + "parallelism": 2 + }, + { + "url": "https://dev.azure.com/fabrikam-prime", + "projects": [ "fabrikam-dev", "fabrikam-test" ], + "parallelism": 2 + } + ] + } +} +``` + +* * * + +## Configure interactive mode + +If your tests need an interactive login for UI testing, enable interactive login by enabling the **EnableInteractiveMode** setting. + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="./media/configure-security/interactive-mode.png" alt-text="Screenshot of configuring interactive mode."::: + +#### [ARM template](#tab/arm/) + +Interactive mode is configured in the `osProfile` section of the `fabricProfile` property. Set `logonType` to `Interactive` to enable interactive mode, or `Service` to disable interactive mode. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "fabricProfile": { + "sku": {...}, + "images": [...], + "osProfile": { + "secretsManagementSettings": {...}, + "logonType": "Interactive" + }, + "storageProfile": {...}, + "kind": "Vmss" + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +Interactive mode is configured using the `logonType` property in the `osProfile` section in the `fabric-profile` parameter when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. + +```azurecli +az mdp pool create \ + --fabric-profile fabric-profile.json + # other parameters omitted for space +``` + +The following example shows the `osProfile` section of the **fabric-profile.json** file with `Interactive` mode enabled. + +```json +{ + "vmss": { + "sku": {...}, + "images": [...], + "osProfile": { + "secretsManagementSettings": {...}, + "logonType": "Interactive" + }, + "storageProfile": {...} + } +} +``` + +* * * + +## Pool administration permissions + +As part of the Managed DevOps Pool creation process, an organization level agent pool is created in Azure DevOps. The **Pool administration permissions** setting specifies which users are granted the administrator role of the newly created Azure DevOps pool. To view and manage the Azure DevOps agent pool permissions after the Managed DevOps Pool is created, see [Create and manage agent pools - Security of agent pools](/azure/devops/pipelines/agents/pools-queues#security). + +#### [Azure portal](#tab/azure-portal/) + +:::image type="content" source="./media/configure-security/pool-admin-permissions.png" alt-text="Screenshot of configuring pool administration permissions."::: + +* **Creator only** - The user that created the Managed DevOps Pool is added as an administrator of the Azure DevOps agent pool, and **Inheritance** is set to **Off** in the agent pool security settings. **Creator only** is the default setting. +* **Inherit permissions from project** - The user that created the Managed DevOps Pool is added as an administrator of the Azure DevOps agent pool, and **Inheritance** is set to **On** in the agent pool security settings. +* **Specific accounts** - Specify the accounts to be added as administrators of the created agent pool in Azure DevOps. By default the Managed DevOps Pool creator is added to the list. + +> [!NOTE] +> The **Pool administration permissions** setting is configured on the **Security** tab when the pool is created, and is not displayed in the **Security** settings after the pool is created. To view and manage the Azure DevOps agent pool permissions after the Managed DevOps Pool is created, see [Create and manage agent pools - Security of agent pools](/azure/devops/pipelines/agents/pools-queues#security). + +#### [ARM template](#tab/arm/) + +Pool administration permissions are configured in the `permissionsProfile` property of the `organizationProfile` section of the Managed DevOps Pools resource. + +```json +{ +"organizationProfile": { + "organizations": [...], + "permissionProfile": { + "kind": "CreatorOnly" + }, + "kind": "AzureDevOps" +} +``` + +The `permissionProfile` property can be set during pool creation only. Allowed values are `Inherit`, `CreatorOnly`, and `SpecificAccounts`. + +* `CreatorOnly` - The user that created the Managed DevOps Pool is added as an administrator of the Azure DevOps agent pool, and **Inheritance** is set to **Off** in the agent pool security settings. **Creator only** is the default setting. +* `Inherit` - The user that created the Managed DevOps Pool is added as an administrator of the Azure DevOps agent pool, and **Inheritance** is set to **On** in the agent pool security settings. +* `SpecificAccounts` - Specify the accounts to be added as administrators of the created agent pool in Azure DevOps. By default the Managed DevOps Pool creator is added to the list. Provide a single email address or a list of email addresses for the `users` property; otherwise omit `users`. + + ```json + { + "organizationProfile": { + "organizations": [...], + "permissionProfile": { + "kind": "SpecificAccounts", + "users" : ["User1@fabrikam.com", "User2@fabrikam.com" ] + }, + "kind": "AzureDevOps" + } + ``` + +#### [Azure CLI](#tab/azure-cli/) + +Pool administration permissions are configured in the `organization-profile` parameter when [creating](/cli/azure/mdp/pool#az-mdp-pool-create)a pool. + +```azurecli +az mdp pool create \ + --organization-profile organization-profile.json + # other parameters omitted for space +``` + +```json +{ + "AzureDevOps": + { + "organizations": [...], + "permissionProfile": { + "kind": "CreatorOnly" + } + } +} +``` + +The `permissionProfile` property can be set during pool creation only. Allowed values are `Inherit`, `CreatorOnly`, and `SpecificAccounts`. + +* `CreatorOnly` - The user that created the Managed DevOps Pool is added as an administrator of the Azure DevOps agent pool, and **Inheritance** is set to **Off** in the agent pool security settings. **Creator only** is the default setting. +* `Inherit` - The user that created the Managed DevOps Pool is added as an administrator of the Azure DevOps agent pool, and **Inheritance** is set to **On** in the agent pool security settings. +* `SpecificAccounts` - Specify the accounts to be added as administrators of the created agent pool in Azure DevOps. By default the Managed DevOps Pool creator is added to the list. Provide a single email address or a list of email addresses for the `users` property; otherwise omit `users`. + + ```json + { + "AzureDevOps" : { + "organizationProfile": { + "organizations": [...], + "permissionProfile": { + "kind": "SpecificAccounts", + "users" : ["User1@fabrikam.com", "User2@fabrikam.com" ] + } + } + } + ``` + +* * * + +## Key Vault configuration + +Managed DevOps Pools offers the ability to fetch certificates from an Azure Key Vault during provisioning, which means the certificates will already exist on the machine by the time it runs your Azure DevOps pipelines. To use this feature, you must configure an [identity on your pool](configure-identity.md), and this identity must have **Key Vault Secrets User** permissions to fetch the secret from your Key Vault. To assign your identity to the **Key Vault Secrets User** role, see [Provide access to Key Vault keys, certificates, and secrets with an Azure role-based access control](/azure/key-vault/general/rbac-guide). + +> [!NOTE] +> As of `api-version 2024-10-19`, if you use this feature you can only use a single identity on the pool. Support for multiple identities will be added soon. +> +> Only one identity can be used to fetch secrets from the Key Vault. + +#### [Azure portal](#tab/azure-portal/) + +Key Vault integration is configured in **Settings > Security**. + +:::image type="content" source="./media/configure-security/configure-keyvault.png" alt-text="Screenshot of configuring Key Vault certificates."::: + +> [!NOTE] +> Key Vault integration settings can be configured only after the pool is created. Key Vault integration settings can't be configured during pool creation and are not displayed in the **Security** tab during pool creation. + +#### [ARM template](#tab/arm/) + +Azure Key Vault is configured in the `osProfile` section of the `fabricProfile` property. Set the `secretManagementSettings` to be able to access the desired certificate. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "fabricProfile": { + "sku": {...}, + "images": [...], + "osProfile": { + "secretsManagementSettings": { + "certificateStoreLocation": "LocalMachine", + "observedCertificates": [ + "https:///secrets/" + ], + "keyExportable": false + } + }, + "storageProfile": {...}, + "kind": "Vmss" + } + } + ] +} +``` + +#### [Azure CLI](#tab/azure-cli/) + +Azure Key Vault is configured in the `osProfile` section of the `fabricProfile` property when [creating](/cli/azure/mdp/pool#az-mdp-pool-create) or [updating](/cli/azure/mdp/pool#az-mdp-pool-update) a pool. Set the `secretManagementSettings` to be able to access the desired certificate. + +```azurecli +az mdp pool create \ + --fabric-profile fabric-profile.json + # other parameters omitted for space +``` + +The following example shows the `osProfile` section of the **fabric-profile.json** file with `secretsManagementSettings`configured. + +```json +{ + "vmss": { + "sku": {...}, + "images": [...], + "osProfile": { + "secretsManagementSettings": { + "certificateStoreLocation": "LocalMachine", + "observedCertificates": [ + "https:///secrets/" + ], + "keyExportable": false + }, + "logonType": "Interactive" + }, + "storageProfile": {...} + } +} +``` + +* * * + +### Configuring SecretManagementSettings + +Certificates retrieved using the `SecretManagementSettings` on your pool will automatically sync with the most recent versions published within the Key Vault. These secrets will be on the machine by the time it runs any Azure DevOps pipeline, meaning you can save time and remove tasks for fetching certificates. + +> [!IMPORTANT] +> Provisioning of your agent virtual machines will fail if the secret cannot be fetched from the Key Vault due to a permissions or network issue. + +#### [Windows](#tab/windows/) + +For Windows, the Certificate Store Location is allowed to either be set to `LocalMachine` or `CurrentUser`. This setting will ensure that the secret is installed at that location on the machine. For specific behavior of how secret retrieval works, see [the documentation for the Azure VMSS Key Vault extension for Windows](/azure/virtual-machines/extensions/key-vault-windows). + +#### [Linux](#tab/linux/) + +For Linux, the Certificate Store Location can be any directory on the machine, and the certificates will be downloaded and synced to that location. For specifics on default settings and secret behavior, see [the documentation for the Azure VMSS Key Vault extension for Linux](/azure/virtual-machines/extensions/key-vault-linux). + +* * * + + +## See also + +* [Configure pool settings](./configure-pool-settings.md) diff --git a/docs/managed-devops-pools/configure-storage.md b/docs/managed-devops-pools/configure-storage.md new file mode 100644 index 00000000000..5ee75afc8ce --- /dev/null +++ b/docs/managed-devops-pools/configure-storage.md @@ -0,0 +1,149 @@ +--- +title: Configure storage +description: Learn how to add an empty data disk to your Managed DevOps Pools agents. +ms.date: 11/13/2024 +--- + +# Configure storage + +If you want more disk space for your agents, Managed DevOps Pools supports attaching an empty data disk to the agents in your Managed DevOps Pool. Attaching a data disk allows you to get more storage space without incurring the potentially greater cost of moving your VM size to a more expensive size that has more built-in storage. + +## Attach an empty data disk + +#### [Azure portal](#tab/azure-portal/) + +Configure storage settings when creating your pool on the **Storage** tab. The default setting is no empty data disk. + +:::image type="content" source="media/configure-storage/empty-data-disk-pool-creation.png" alt-text="Screenshot of configuring a data disk during pool creation."::: + +If you are configuring additional storage for an existing pool, go to the pool in the Azure portal as described in the following steps. + +1. Sign in to the [Azure portal](https://portal.azure.com/). +1. Search for **Managed DevOps Pools** and select it from the available options. +1. Choose your Managed DevOps Pool from the list. +1. Go to **Settings** > **Storage** to configure the empty data disk settings for your pool. + +:::image type="content" source="media/configure-storage/empty-data-disk-menu.png" alt-text="Screenshot of empty data disk menu."::: + +Configure the following properties for your disk, and choose **Apply** (or **Next** if you are creating a pool) to save your changes. You can add a single empty data disk configuration for your Managed DevOps Pool, and all agent instances will have an empty data disk attached matching the configuration you specify. + +Choose **Delete** to delete the data disk configuration for an existing pool. + +#### [ARM template](#tab/arm/) + +Additional disk storage is configured in an ARM template in `dataDisks` section under `storageProfile`. In the following example, a 10 GB Standard_LRS disk is configured with the drive letter `Q` and no caching. + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "name": "fabrikam-managed-pool", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "eastus", + "properties": { + ... + "storageProfile": { + "osDiskStorageAccountType": "Standard", + "dataDisks": [ + { + "diskSizeGiB": 10, + "caching": "None", + "storageType": "Standard_LRS", + "driveLetter": "Q" + } + ] + } + } + } + ] +} +``` + +To delete the data disk configuration for an existing pool, specify an empty list for `dataDisks`: `"dataDisks": []`. + +#### [Azure CLI](#tab/azure-cli/) + +Additional disk storage is configured using the `dataDisks` property in the `storageProfile` section in the `fabric-profile` parameter. + +```azurecli +az mdp pool create \ + --fabric-profile fabric-profile.json + # other parameters omitted for space +``` + +In the following example, a 10 GB Standard_LRS disk is configured with the drive letter `Q` and no caching. + +The following example shows the `storageProfile` section of the **fabric-profile.json** file. + +```json +{ + "vmss": { + "sku": {...}, + "images": [...], + "osProfile": {...}, + "storageProfile": { + "osDiskStorageAccountType": "Standard", + "dataDisks": [ + { + "diskSizeGiB": 10, + "caching": "None", + "storageType": "Standard_LRS", + "driveLetter": "Q" + } + ] + } + } +} +``` + +To delete the data disk configuration for an existing pool, specify an empty list for `dataDisks`: `"dataDisks": []`. + +* * * + +Configure the following properties for your attached data disk. + +| Property | Description | +|----------|-------------| +| Size (GiB) | Specify the size of your data disk. The maximum size depends on the storage type. For more information, see [Disk type comparison](/azure/virtual-machines/disks-types#disk-type-comparison) .| +| Caching Type | Specify the caching type for your disk. Choose from: **Default**, **None**, **ReadOnly**, **ReadWrite**. The default for data disks that support caching is **ReadOnly**. For more information, see [Virtual machine and disk performance](/azure/virtual-machines/disks-performance). | +| Storage Type | Choose from the following storage types: **Standard_LRS** (default), **Premium_LRS**, **StandardSSD_LRS**, **Premium_ZRS**, **StandardSSD_ZRS**. For more information about these types, see [SKU Types](/rest/api/storagerp/srp_sku_types) and [Azure managed disk types](/azure/virtual-machines/disks-types). | +| Drive Letter | If you have any Windows agent images in your pool, choose a drive letter for your disk. If you don't specify a drive letter, **F** is used for VM sizes with a temporary disk; otherwise **E** is used. The drive letter must be a single letter except **A**, **C**, **D**, or **E**. If you are using a VM size without a temporary disk and want **E** as your drive letter, leave **Drive Letter** empty to get the default value of **E**. | + +## Use the data disk for your agent working directory + +To configure your agents to use a working directory on the data disk, specify a folder from the data disk in a `WorkFolder` demand. + +#### [Windows](#tab/windows/) + +In the following example, the agent working directory on a Windows agent is configured to use a folder on an attached data disk that is assigned the drive letter **F**. + +```yml +pool: + name: fabrikam-managed-pool # Name of Managed DevOps Pool + demands: + - WorkFolder -equals f:\custom-work-folder # Windows agent example +``` + +#### [Linux](#tab/linux/) + +For Linux agents, the data disk is mounted as **/mnt/storage/sdc**. The following example configures the agent working directory to be a folder named **custom-work-folder** on the data disk. + +```yml +pool: + name: fabrikam-managed-pool # Name of Managed DevOps Pool + demands: + - WorkFolder -equals /mnt/storage/sdc/custom-work-folder +``` + +* * * + +For more information about configuring the agent work directory, see [Demands - WorkFolder](demands.md#workfolder). + +## See also + +* [Configure pool settings](./configure-pool-settings.md) +* [Allowlisting Azure Storage](./configure-networking.md) + diff --git a/docs/managed-devops-pools/demands.md b/docs/managed-devops-pools/demands.md new file mode 100644 index 00000000000..cd2793dbd4f --- /dev/null +++ b/docs/managed-devops-pools/demands.md @@ -0,0 +1,104 @@ +--- +title: Configure demands +description: Learn how to configure demands for Managed DevOps Pools. +ms.date: 02/21/2025 +--- + +# Demands + +[Demands](/azure/devops/pipelines/yaml-schema/pool-demands) provide a way for pipelines to specify what capabilities must be present in an agent in order for Azure DevOps to send a job from the pipeline to the agent. In Managed DevOps Pools, demands like [ImageOverride](#imageoverride) work just like demands in Azure Pipelines, where a pipeline job is routed to a specific agent that has attributes matching the demand, but some demands, like [WorkFolder](#workfolder) and [Priority](#priority), can be used to configure attributes on the agent. This article describes the demands available in Managed DevOps Pools and how to use them. + +## WorkFolder + +The default work folder for agents is typically on the **D:\\** drive for Windows or **/mnt** for Linux, and can be referenced in your pipeline by using the `Agent.WorkFolder` [predefined variable](/azure/devops/pipelines/build/variables). You can override this location to change both the drive and directory name used when starting the agent by specifying the `WorkFolder` demand in your pipeline. If you have a stateful pool with a running agent with a `WorkFolder` that matches your demand, your pipeline will be sent to that agent. If you aren't using stateful pools, or there is no agent running with that `WorkFolder`, a new agent is started and configured to use the designated `WorkFolder`. The directory specified is created if not present. If the path name for the `WorkFolder` is invalid, the default agent working folder is used. + +Configure the `WorkFolder` demand in the `demands` section of your pipeline to set your agent work folder. If you're using an [attached data disk](configure-storage.md) and want your agent work folder on that disk, use `WorkFolder` and [specify a folder on the data disk as your agent working directory](configure-storage.md#use-the-data-disk-for-your-agent-working-directory). + +```yml +pool: + name: fabrikam-managed-pool # Name of Managed DevOps Pool + demands: + - WorkFolder -equals c:\custom-work-folder # Windows agent example + # Use a folder like /user/local/custom-work-folder for Linux + # or /mnt/storage/sdc/custom-work-folder if you're using a data disk. +``` + +## Priority + +`Priority` specifies the priority of the job. Jobs with higher priority are executed first. Valid values are: `High`, `Medium`, `Low`. The default value is `Medium`. + +Configure the `Priority` demand in the `demands` section of your pipeline. + +```yml +pool: + name: fabrikam-dev-pool # Name of Managed DevOps Pool + demands: + - Priority -equals Low +``` + +Jobs are selected to run from the queue in order of priority. For example, you have a pool which has a maximum agents setting of 10 and a pipeline configured to use this pool. The pool is already running 10 pipelines, and 20 more are queued. If you have a priority pipeline to run, for example to push out a hot fix, it would normally run after the 10 running pipelines and the 20 queued pipelines complete. If you set priority to high when queuing your hotfix pipeline, it will get an agent and run before the 20 previously queued pipelines. + +If multiple jobs are queued at the same time, it is possible that a lower priority job will run before a higher priority job. + +For the case of a single pipeline with multiple jobs: + +* If your pipeline has [dependencies that define sequential jobs](../pipelines/process/phases.md#dependencies), the sequential jobs run in the order specified by the pipeline regardless of the priority setting for each job. +* If your pipeline has multiple jobs configured to run in parallel ([the default for YAML pipelines](../pipelines/process/phases.md#dependencies)), the jobs are queued at the same time, and jobs in the pipeline with lower priority might run before jobs in the pipeline with higher priority. + + +## ImageOverride + +If you have multiple images in your pool, you can configure your pipelines to use a specific image by using the `ImageOverride` demand and providing the [alias](configure-images.md#use-multiple-images-per-pool-with-aliases) of the image to use. If you're using an Azure Pipelines image, you can use its [predefined alias](configure-images.md#azure-pipelines-image-predefined-aliases). For all other images, you must [configure your own aliases](configure-images.md#configure-image-aliases). + +> [!IMPORTANT] +> If you have multiple images in your pool, and don't use demands in your pipelines to designate an image, the pipelines run using the first listed image in your pool. You can change the order of the images in your pool by changing the order of the images in the `images` list in the `fabricProfile` section (if using [templates](./configure-images.md?&tabs=arm#choose-your-pools-image)), or by ordering the [images in the images list](./configure-pool-settings.md#images) in the Azure portal using drag and drop. + +In the following example, a pipeline is configured to run using an image that is configured with an `ubuntu-20.04-gen2` alias. + +```yml +pool: + name: fabrikam-dev-pool # Name of Managed DevOps Pool + demands: + - ImageOverride -equals ubuntu-20.04-gen2 +``` + +> [!IMPORTANT] +> Don't put quotes around the alias name in the `ImageOverride` demand, even if it has spaces in the name. + +## ImageVersionOverride + +If you're using an Azure Compute Gallery or Azure Marketplace [image](configure-images.md#choose-your-pools-image) and want to use a specific version of the image instead of the version specified by your image configuration, you can use the `ImageVersionOverride` demand. For example, you can use it to validate a new image version before promoting it to be **latest** for an image. The following examples specify an `ImageVersionOverride` of `2.0.0`. + +Configure the `ImageVersionOverride` demand in the `demands` section of your pipeline. + +```yml +pool: + name: fabrikam-dev-pool # Name of Managed DevOps Pool + demands: + - ImageVersionOverride -equals 2.0.0 +``` + +## CustomCapabilities + +If you have stateful pools and you want a way to run a job on a specific running agent instance, you can use the `CustomCapabilities` demand. + +> [!IMPORTANT] +> The `CustomCapabilities` demand applies only to agents in stateful pools. When you're using stateless pools, you get a fresh agent image for every job. + +When you specify a `CustomCapabilities` demand in your pipeline, if any pipeline with the same demand has run previously, and the stateful agent that ran the pipeline is still online, that agent will be used to run the pipeline. If no online agents match the `CustomCapabilities` demand, an agent is provisioned from the pool, tagged with the `CustomCapabilities` demand, and is used to run the pipeline. Subsequent jobs with the same `CustomCapabilities` demand will use that tagged agent instance to run their jobs as long as that agent is online. + +In the following example, a pipeline is run using the `windows-2022` Azure Pipelines image in a stateful pool. If an online agent is ready to accept jobs and is tagged with the `CustomCapabilities` attribute (set by a pipeline that previously ran on the agent), that agent will be used to run this pipeline. If no online agent matches this demand, the next available agent is used to run the job, and the agent is tagged with the `CustomCapabilities` attribute. Future pipeline runs with this demand will run on this agent, if it is online and ready for jobs. + +```yml +pool: + name: fabrikam-dev-pool # Name of Managed DevOps Pool + demands: + - ImageOverride -equals windows-2022 + - CustomCapabilities -equals MyCustomValue +``` + +For example, you have a large repository that takes a long time to clone, and you have multiple pipelines that run from this repository. Using the same `CustomCapabilities` demand in the pipelines could help the second pipeline run more quickly by using an agent with the repository already cloned. + +## See also + +* [Configure images](./configure-images.md) diff --git a/docs/managed-devops-pools/diagnostics.md b/docs/managed-devops-pools/diagnostics.md new file mode 100644 index 00000000000..251ec7bca51 --- /dev/null +++ b/docs/managed-devops-pools/diagnostics.md @@ -0,0 +1,51 @@ +--- +title: Diagnostic logs +description: Learn how to troubleshoot using diagnostic logs. +ms.date: 11/13/2024 +--- + +# Diagnostics logs + +Diagnostic settings in Azure are used to collect resource logs. An Azure resource emits resource logs and provides rich, frequent data about the operation of that resource. These logs are captured per request and are also referred to as "data plane logs". See [Diagnostic settings in Azure Monitor](/azure/azure-monitor/essentials/diagnostic-settings) for a recommended overview of the functionality in Azure. The content of these logs varies by resource type. In Managed DevOps Pools, two options are available to log: + +- **Managed DevOps Pools Metrics** (**AllMetrics**) used to [log metrics from Azure Monitor](/azure/azure-monitor/essentials/diagnostic-settings) + - Choose from the [same metrics](./monitor-pool.md#available-metrics) you use in the **Monitoring** > **Metrics** tab. +- **Resource Provisioning Logs** logs provisioning events for the agents in your pool. + - These are the same events you can view in the [Agents](./view-agents.md) view. + +## Create diagnostic setting + +1. To create a new diagnostic setting, choose **Monitoring** > **Diagnostic settings**, and choose **+Add diagnostic setting**. + + :::image type="content" source="./media/diagnostics/add-diagnostic-setting.png" alt-text="Screenshot of add diagnostic setting menu."::: + +2. Choose the type of log to capture, and one or more options from **Destination details**, and choose **Save**. + + > [!IMPORTANT] + > Managed DevOps Pools currently supports **Archive to a storage account** and **Stream to an event hub**, with more destination types coming soon. + + :::image type="content" source="./media/diagnostics/diagnostics.png" alt-text="Screenshot of diagnostics settings."::: + +3. Run jobs in your pool, and then review the collected data. For information on analyzing diagnostic log data, see [Analyze and visualize monitoring data](/azure/azure-monitor/best-practices-analysis). The diagnostic data contains log entries similar to the following example. + + ```json + { + "time": "2024-07-15T17:23:42.0302794Z", + "resourceId": "/SUBSCRIPTIONS/SUBSCRIPTION_ID_PLACEHOLDER/RESOURCEGROUPS/FABRIKAM-POOLS/PROVIDERS/MICROSOFT.DEVOPSINFRASTRUCTURE/POOLS/FABRIKAM_POOL", + "location": "eastus", + "category": "ProvisioningLogs", + "operationName": "Provision", + "properties": { + "RequestId": "RequestId_Placeholder", + "AgentName": "7ec0d355c", + "Image": "/canonical/0001-com-ubuntu-server-focal/20_04-lts-gen2/20.04.202407040", + "Sku": "Standard_D2ads_v5", + "Status": "Completed" + } + } + ``` +## See also + +* [Analyze and visualize monitoring data](/azure/azure-monitor/best-practices-analysis) +* For more information about diagnostic settings and the different destinations for logs, see [Diagnostic settings in Azure Monitor](/azure/azure-monitor/essentials/diagnostic-settings). + diff --git a/docs/managed-devops-pools/faq.md b/docs/managed-devops-pools/faq.md new file mode 100644 index 00000000000..acea7af5fa2 --- /dev/null +++ b/docs/managed-devops-pools/faq.md @@ -0,0 +1,40 @@ +--- +title: Frequently asked questions +description: Learn the answers to frequently asked questions for Managed DevOps Pools. +ms.date: 11/13/2024 +--- + +# Frequently asked questions + +## How many agents can I create? + +See [Review Managed DevOps Pools quotas](./prerequisites.md#review-managed-devops-pools-quotas) for information about the default quota and how to increase the quota for your pool. + +## What Azure VM SKU should I choose? + +See [Manage cost and performance](./manage-costs.md) for information about choosing the right Azure VM size to meet your workflow needs as well as your budget. + +## Can I remote access to my agents VMs? + +You cannot remote access to the VMs that run the Managed DevOps Pools agents. + +## What Azure regions support Managed DevOps Pools? + +To see the Azure regions that support Managed DevOps Pools in your subscription, review the locations list for the **Microsoft.DevOpsInfrastructure** resource provider. + + +1. Sign in to the [Azure portal](https://portal.azure.com/). +1. On the Azure portal menu, search for **Subscriptions**. Select it from the available options. +1. Select the Azure subscription you plan to use for Managed DevOps Pools. +1. On the left menu, under **Settings**, select **Resource providers**. +1. Search for **Microsoft.DevOpsInfrastructure**. +1. Verify that the **Status** is **registered**. If it's not registered, select it, and choose **Register**. + + :::image type="content" source="./media/prerequisites/register-resource-provider.png" alt-text="Screenshot of registering the Managed DevOps Pools Azure Resource provider."::: + +1. Choose **Microsoft.DevOpsInfrastructure** from the list, and choose **Locations**. + + :::image type="content" source="media/prerequisites/view-provider-regions-small.png" lightbox="media/prerequisites/view-provider-regions.png" alt-text="Screenshot of Azure regions that support Managed DevOps Pools."::: + +> [!IMPORTANT] +> If the **Microsoft.DevOpsInfrastructure** is not registered in your subscription, you won't see any locations. [Register the Managed DevOps Pools resource provider in your Azure Subscription](./prerequisites.md#register-the-managed-devops-pools-resource-provider-in-your-azure-subscription) before you check for supported regions. For more information about Azure resource providers, see [Azure resource providers and types](/azure/azure-resource-manager/management/). diff --git a/docs/managed-devops-pools/features-timeline.md b/docs/managed-devops-pools/features-timeline.md new file mode 100644 index 00000000000..6d3eb36f248 --- /dev/null +++ b/docs/managed-devops-pools/features-timeline.md @@ -0,0 +1,58 @@ +--- +title: Features timeline and roadmap +description: Learn about new features in Managed DevOps Pools. +ms.date: 03/31/2025 +ms.topic: overview +#Customer intent: As a platform engineer, I want to understand the new features in Managed DevOps Pools. +--- + +# Managed DevOps Pools features timeline and roadmap + +## Roadmap + +The following section describes new features in development for Managed DevOps Pools. + +* **Trusted root certificates**: Managed DevOps Pools is adding support so you can configure your pool to add certificates from your Key Vault as a trusted root certificate to your agents, so you don’t have to add a task for it to all the pipelines that use the pool. For more information, see [Key Vault configuration](./configure-security.md#key-vault-configuration). **Planned for April 2025.** + +* **Shorter time for agent allocation**: The Managed DevOps Pools team is making updates to shorten the startup time for [standby agents](./configure-scaling.md#standby-agent-mode) (**Fresh agent every time** setting). **Planned for April 2025.** + +* **Log analytics**: Managed DevOps Pools is adding support so you can configure your pools to emit logs into Log analytics. The Log Analytics tool in the Azure portal lets you run and edit log queries against data in the Azure Monitor Logs store. Use Log Analytics to analyze and visualize log data using [Kusto Query Language (KQL)](/azure/azure-monitor/logs/get-started-queries) or the point-and-click experience provided in [Log Analytics simple mode](/azure/azure-monitor/logs/log-analytics-simple-mode). **Planned for April 2025.** + +* **Pool creation at the Azure DevOps project level using project level permissions**: To create a Managed DevOps Pool, you must currently be an [Organization-level Agent pools administrator or a Project Collection Administrator in Azure DevOps](./prerequisites.md#verify-azure-devops-permissions). We're enabling a new mode of Managed DevOps Pools creation, requiring only Project-level Agent pools administrator. Managed DevOps Pools created using Project-level Agent pools administrator will be created and enabled only for use in the designated Azure DevOps Project. **Planned for April 2025.** + +* **Open access for all pipelines to use a Managed DevOps Pool**: By default, each pipeline must be explicitly authorized to use a newly created Managed DevOps Pool. We're adding an option to enable [Open access for all pipelines](/azure/devops/pipelines/agents/pools-queues#pipeline-permissions) so that administrators don't need to explicitly authorize each pipeline. **Planned for April 2025.** + +* **Windows 2025 Azure Pipelines Image**: We're adding the [Windows Server 2025 image](https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md) to [Azure Pipelines images](./configure-images.md#azure-pipelines-images). + +* **Public Static IP**: We're adding support for public static IP addresses in Managed DevOps Pool to more easily enable access to external resources once [Default outbound access for VMs in Azure is retired](https://azure.microsoft.com/updates?id=default-outbound-access-for-vms-in-azure-will-be-retired-transition-to-a-new-method-of-internet-access). **Planned for June 2025.** + +* **Spot Virtual Machines instances**: Reduce your Azure cost [by up to 90%](/azure/architecture/guide/spot/spot-eviction#understand-spot-vm-pricing) by switching your non-time-critical pipelines to Spot Virtual Machines. CI/CD workloads make ideal candidates to use Spot Virtual Machines due to the ephemeral nature of CI/CD agents. For more information on Spot Virtual Machines, see [Spot Virtual Machines overview](https://azure.microsoft.com/products/virtual-machines/spot). **Planned for end of 2025.** + +* **Container agents**: We're adding support for provisioning a container and starting the agent inside the container. **Planned for end 2025.** + +* **Purge agents**: We're adding the ability for you to manually recycle your agents if desired. **Planned for end of 2025.** + +## March 2025 + +The following features were released in Managed DevOps Pools in March 2025. + +* **Managed DevOps Pools supported in more Azure regions**: Managed DevOps Pools is now available in **(Asia Pacific) Jio India Central** and **(Asia Pacific) Jio India West**, allowing you to leverage regional resources for optimized performance and compliance. To see the Azure regions that support Managed DevOps Pools in your subscription, [register the Microsoft.DevOpsInfrastructure provider in your subscription and view the supported locations](prerequisites.md#register-the-managed-devops-pools-resource-provider-in-your-azure-subscription). + +* **Ubuntu 24.04 Azure Pipelines Image**: Ubuntu 24.04 is supported for [Selected marketplace images](./configure-images.md#selected-marketplace-images) and [Azure Compute Gallery images](./configure-images.md#azure-compute-gallery-images), and it's now supported for [Azure Pipelines images](./configure-images.md#azure-pipelines-images). + +## November 2024 + +The following features were released in Managed DevOps Pools in November 2024. + +* **Managed DevOps Pools supported in more Azure regions**: Managed DevOps Pools is now available in Sweden Central, Brazil South, Japan East, UAE North, Korea Central, and Norway East, allowing you to leverage regional resources for optimized performance and compliance. To see the Azure regions that support Managed DevOps Pools in your subscription, [register the Microsoft.DevOpsInfrastructure provider in your subscription and view the supported locations](prerequisites.md#register-the-managed-devops-pools-resource-provider-in-your-azure-subscription). + +* **Integrate with Azure Key Vault**: Managed DevOps Pools offers the ability to fetch certificates from an Azure Key Vault during provisioning, which means the certificates will already exist on the machine by the time it runs your Azure Pipelines. To use this feature, [configure a managed identity on your pool](./configure-identity.md), and grant it permissions to access secrets from your Key Vault. For more information, see [Integrate with Azure Key Vault](./configure-security.md#key-vault-configuration). + +* **Proxy support**: You can set up your Managed DevOps Pools to direct network traffic through a proxy. By using an image with a preinstalled proxy, you can run your Azure Pipelines on Managed DevOps Pools behind a proxy, like the current Azure Virtual Machine Scale Set agents offering. This setup enables the agent to retrieve sources and download artifacts, passing the proxy details to tasks that also require proxy settings to access the web. For more information, see [Proxy support](./configure-networking.md#configure-the-azure-devops-agent-to-run-behind-a-proxy). + +* **View agent IP address**: You can now view the IP address of the agent in the Initialize job step of your pipeline log, useful for scenarios such as investigating failing pipelines due to proxies or firewall rules. + +* **Move to another resource group or subscription**: You now have the option to move your Managed DevOps Pools to another Azure resource group or to another subscription. For more information, see [Move Azure resources to a new resource group or subscription](/azure/azure-resource-manager/management/move-resource-group-and-subscription). + +* **Ubuntu 24.04 support**: We've added support for Ubuntu 24.04 by adding three images to [Selected marketplace images](./configure-images.md#selected-marketplace-images) and enabling bring-your-own Ubuntu 24.04 images using [Azure Compute Gallery images](./configure-images.md#azure-compute-gallery-images). + diff --git a/docs/managed-devops-pools/includes/mdp-recommended.md b/docs/managed-devops-pools/includes/mdp-recommended.md new file mode 100644 index 00000000000..da9e571e024 --- /dev/null +++ b/docs/managed-devops-pools/includes/mdp-recommended.md @@ -0,0 +1,9 @@ +--- +ms.topic: include +ms.date: 01/23/2025 +--- + +> [!TIP] +> Managed DevOps Pools is a new service that is an evolution of Azure DevOps Virtual Machine Scale Set agent pools, simplifying custom pool creation even further, by improving scalability and reliability of custom pools. Managed DevOps Pools is a fully managed service where virtual machines or containers powering the agents live in a Microsoft Azure subscription and not in your own Azure subscription, like when using Azure DevOps Virtual Machine Scale Set agent pools. +> +> If you're considering using auto-scalable self-hosted agent pools, we recommend looking at Managed DevOps Pools. For more information, see [Compare Managed DevOps Pools with Azure Virtual Machine Scale Set agents](../migrate-from-scale-set-agents.md) and [Managed DevOps Pools overview](../overview.md). diff --git a/docs/managed-devops-pools/index.yml b/docs/managed-devops-pools/index.yml new file mode 100644 index 00000000000..8d844dce2a8 --- /dev/null +++ b/docs/managed-devops-pools/index.yml @@ -0,0 +1,108 @@ +### YamlMime:Landing + +title: Managed DevOps Pools documentation +summary: Managed DevOps Pool is a fully managed service where VMs or containers powering the agents will live in a Microsoft Azure subscription and not in your own Azure subscription. + +metadata: + title: Managed DevOps Pools documentation + titleSuffix: Azure DevOps + description: Managed DevOps Pool is a fully managed service where VMs or containers powering the agents will live in a Microsoft Azure subscription and not in your own Azure subscription. + ms.topic: landing-page + ms.date: 02/03/2025 + +# linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new + +landingContent: +# Cards and links should be based on top customer tasks or top subjects +# Start card title with a verb + # Card (optional) + - title: Get started + linkLists: + - linkListType: concept + links: + - text: What is Managed DevOps Pools? + url: overview.md + - text: Compare with Azure Virtual Machine Scale Set agents + url: migrate-from-scale-set-agents.md + - text: Roadmap and features timeline + url: features-timeline.md + - linkListType: quickstart + links: + - text: Azure portal + url: quickstart-azure-portal.md + - text: ARM template + url: quickstart-arm-template.md + - text: Azure CLI + url: quickstart-azure-cli.md + - title: Configure Managed DevOps Pools + linkLists: + - linkListType: concept + links: + - text: Configure prerequisites + url: prerequisites.md + - text: Configure pool settings + url: configure-pool-settings.md + - text: Configure scaling + url: configure-scaling.md + - text: Configure networking + url: configure-networking.md + - text: Configure additional storage + url: configure-storage.md + - text: Configure images + url: configure-images.md + - text: Configure security settings + url: configure-security.md + - text: Configure Identity + url: configure-identity.md + - title: Key concepts + linkLists: + - linkListType: concept + links: + - text: Architecture overview + url: architecture-overview.md + - text: Demands + url: demands.md + - title: Reference guidance + linkLists: + - linkListType: reference + links: + - text: .NET + url: /dotnet/api/overview/azure/devops-infrastructure + - text: ARM template + url: /azure/templates/microsoft.devopsinfrastructure/pools?pivots=deployment-language-arm-template + - text: Azure CLI + url: /cli/azure/service-page/managed%20devops%20pools + - text: Azure PowerShell + url: /powershell/module/az.mdp + - text: Bicep + url: /azure/templates/microsoft.devopsinfrastructure/pools?pivots=deployment-language-bicep + - text: Java + url: /java/api/overview/azure/devops-infrastructure + - text: JavaScript + url: /javascript/api/overview/azure/devops-infrastructure + - text: Python + url: /python/api/overview/azure/devops-infrastructure + - text: REST + url: /rest/api/devopspools + - text: Terraform + url: /azure/templates/microsoft.devopsinfrastructure/pools?pivots=deployment-language-terraform + - title: Troubleshoot + linkLists: + - linkListType: how-to-guide + links: + - text: Monitor + url: monitor-pool.md + - text: Diagnostic logs + url: diagnostics.md + - text: Troubleshooting + url: troubleshooting.md + - text: Reliability + url: reliability-managed-devops-pools.md + - title: Manage costs + linkLists: + - linkListType: concept + links: + - text: Pricing + url: pricing.md + - text: Manage costs + url: manage-costs.md diff --git a/docs/managed-devops-pools/manage-costs.md b/docs/managed-devops-pools/manage-costs.md new file mode 100644 index 00000000000..5fefd6a7c15 --- /dev/null +++ b/docs/managed-devops-pools/manage-costs.md @@ -0,0 +1,64 @@ +--- +title: Manage cost and performance +description: Learn how to manage cost and performance for your Managed DevOps Pools. +ms.date: 11/13/2024 +ms.topic: concept-article +#Customer intent: As a platform engineer, I want to understand how to balance the cost and performance of my pools. +--- + +# Manage cost and performance + +Managed DevOps Pools provides several different options for configuring the performance of your pool. This article describes options for matching your pool's performance to the demands of your workload, by increasing or reducing the performance and cost of your pools. + +## Configure agent performance + +When you configure your Managed DevOps Pool, you have different options for configuring the performance and cost of your pool. The following sections describe some choices you can make to configure the performance of your pool. + +* [Disk types](#disk-types) +* [Choose the right agent size and type](#choose-the-right-agent-size-and-type) +* [Pool region co-location](#pool-region-co-location) +* [Pre-provisioning with standby agents](#pre-provisioning-with-standby-agents) + +### Disk types + +When you create your Managed DevOps Pool, you have an option to chose **Standard SSD** or **Premium SSD** instead of the default **Standard** OS disk type. OS disk type determines what kind of disk is used for your OS drive. Your agent working directory is by default in the temp drive or **D:\\**, so you may not benefit by an expensive OS disk type. Benchmark your workload's performance with different OS disk types, understand the costs involved and chose an OS disk type appropriately. + +If your workload's throughput exceeds the level of the standard tier, you can potentially gain a performance improvement in your workload by upgrading to a more performant disk type. For more information on disk types and performance, see [Azure Managed disk types](/azure/virtual-machines/disks-types). + +Instead of changing the OS disk type or going to a larger SKU for more disk space, consider [configuring a data disk](configure-storage.md) for your pool. You can configure a size and disk type that meets your workload requirements, and configure your pools to use this drive as the agent working directory, to provide greater storage while using the default OS disk type and a potentially less expensive VM size. + +### Choose the right agent size and type + +Agent size in Managed DevOps Pools specifies the [Azure virtual machine size](/azure/virtual-machines/sizes) to use for hosting your Managed DevOps Pools agents. You can change the [agent size](configure-pool-settings.md#agent-size) for your pool to provide more CPU cores, more memory and more disk space. Using a more powerful VM size will increase your Azure bill as well, so choose this option only if you determine that using a more powerful VM size will increase your workload performance. + +#### VM CPU architecture + +AMD powered VM sizes are often up to 40% less expensive than Intel powered VM sizes, with the same or better performance. Using AMD powered VM sizes provide an opportunity to reduce your Azure spend. + +#### VM size + +Make sure you are using the right Azure VM size. If you are currently using an eight core Azure VM size, make sure your workload is able to use all the 8 cores. You can run your workload on different VM sizes and see how performant your workload is. You can downgrade a VM size to reduce your COGS, while keeping your workload's performance about the same. + +#### VM type + +Different Azure VM series are designed for workloads with specific characteristics to perform better. Familiarize yourself with different Azure SKU series so you can pick a series that best suits your workload. Example: If your application doesn't use as much core as it does memory, you can pick a VM size from the [Memory optimized](/azure/virtual-machines/sizes-memory) family of sizes. + +Review the different [Azure VM types](/azure/virtual-machines/sizes) to understand their benefits. For example, if your workload requires more cores and less memory, you can use [Compute optimized](/azure/virtual-machines/sizes-compute) size. If your workload requires more disk space but the same cores/memory, you can pick an Azure VM type that has a higher disk to compute ratio rather than going up a SKU size, or you could use an [attached data disk](configure-storage.md). + +#### VM type generation + +The latest generation of an Azure VM type might be more performant than the previous version. For example, D2dsV4 and D2dsV5 are priced the same and have the same specifications but it is likely that V5 is faster than the V4. + +### Pool region co-location + +Try to colocate your pool's Azure region to the region where CI/CD workload's dependencies are present. This proximity reduces network latency and makes your workloads relatively more performant. You can find your [Azure DevOps organization's region](/azure/devops/organizations/accounts/change-organization-location) and locate your Managed DevOps Pool in the same region. + +### Pre-provisioning with standby agents + +By default, whenever you queue a pipeline, an agent is created from scratch. You can choose to enable standby agents, so that your pipelines don't spend time waiting. If you have turned on standby agents in manual mode, you can look at historical utilization of standby agents and decide if you want to reduce the number of standby agents. You can also decide to completely turn off pre-provisioning if your workflows aren't time critical and can wait 5-10 minutes for the agents to be created on demand. + +One option to improve agent performance without using standby agents is to use stateful agents with a short grace period. When stateful agents with a grace period complete a job, they stay online for the duration specified by the grace period and wait for jobs. If your workload comes in bursts, you can configure a grace period that keeps agents online when jobs are steady, and starts them from scratch during slower periods. + +For more information, see [Standby agents](configure-scaling.md#standby-agent-mode) and [Stateful pools](configure-scaling.md#stateful-pools). + + diff --git a/docs/managed-devops-pools/media/agent-performance/automatic-scaling-setting.png b/docs/managed-devops-pools/media/agent-performance/automatic-scaling-setting.png new file mode 100644 index 00000000000..e51d52fe7c2 Binary files /dev/null and b/docs/managed-devops-pools/media/agent-performance/automatic-scaling-setting.png differ diff --git a/docs/managed-devops-pools/media/agent-performance/manual-scaling-all-week-scheme.png b/docs/managed-devops-pools/media/agent-performance/manual-scaling-all-week-scheme.png new file mode 100644 index 00000000000..5d3629e7b06 Binary files /dev/null and b/docs/managed-devops-pools/media/agent-performance/manual-scaling-all-week-scheme.png differ diff --git a/docs/managed-devops-pools/media/agent-performance/manual-scaling-scheme.png b/docs/managed-devops-pools/media/agent-performance/manual-scaling-scheme.png new file mode 100644 index 00000000000..d3fffd95352 Binary files /dev/null and b/docs/managed-devops-pools/media/agent-performance/manual-scaling-scheme.png differ diff --git a/docs/managed-devops-pools/media/agent-performance/manual-scaling-weekday-scheme.png b/docs/managed-devops-pools/media/agent-performance/manual-scaling-weekday-scheme.png new file mode 100644 index 00000000000..9bdebba82b1 Binary files /dev/null and b/docs/managed-devops-pools/media/agent-performance/manual-scaling-weekday-scheme.png differ diff --git a/docs/managed-devops-pools/media/agent-performance/manual-standby-mode.png b/docs/managed-devops-pools/media/agent-performance/manual-standby-mode.png new file mode 100644 index 00000000000..3e6b5fae12f Binary files /dev/null and b/docs/managed-devops-pools/media/agent-performance/manual-standby-mode.png differ diff --git a/docs/managed-devops-pools/media/agent-performance/standby-agent-mode.png b/docs/managed-devops-pools/media/agent-performance/standby-agent-mode.png new file mode 100644 index 00000000000..b139e818bc6 Binary files /dev/null and b/docs/managed-devops-pools/media/agent-performance/standby-agent-mode.png differ diff --git a/docs/managed-devops-pools/media/agent-performance/stateful-agent.png b/docs/managed-devops-pools/media/agent-performance/stateful-agent.png new file mode 100644 index 00000000000..19e4734b171 Binary files /dev/null and b/docs/managed-devops-pools/media/agent-performance/stateful-agent.png differ diff --git a/docs/managed-devops-pools/media/agent-performance/stateless-agent.png b/docs/managed-devops-pools/media/agent-performance/stateless-agent.png new file mode 100644 index 00000000000..29113469ab1 Binary files /dev/null and b/docs/managed-devops-pools/media/agent-performance/stateless-agent.png differ diff --git a/docs/managed-devops-pools/media/agents/agents-status-expanded.png b/docs/managed-devops-pools/media/agents/agents-status-expanded.png new file mode 100644 index 00000000000..f71e83ae5de Binary files /dev/null and b/docs/managed-devops-pools/media/agents/agents-status-expanded.png differ diff --git a/docs/managed-devops-pools/media/agents/agents-status.png b/docs/managed-devops-pools/media/agents/agents-status.png new file mode 100644 index 00000000000..ab38bcfc296 Binary files /dev/null and b/docs/managed-devops-pools/media/agents/agents-status.png differ diff --git a/docs/managed-devops-pools/media/architecture/architecture.png b/docs/managed-devops-pools/media/architecture/architecture.png new file mode 100644 index 00000000000..fc2fe0223b1 Binary files /dev/null and b/docs/managed-devops-pools/media/architecture/architecture.png differ diff --git a/docs/managed-devops-pools/media/configure-identity/add-identity-button.png b/docs/managed-devops-pools/media/configure-identity/add-identity-button.png new file mode 100644 index 00000000000..f068967cf96 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-identity/add-identity-button.png differ diff --git a/docs/managed-devops-pools/media/configure-identity/add-identity.png b/docs/managed-devops-pools/media/configure-identity/add-identity.png new file mode 100644 index 00000000000..10e65d306d5 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-identity/add-identity.png differ diff --git a/docs/managed-devops-pools/media/configure-images/add-alias-menu.png b/docs/managed-devops-pools/media/configure-images/add-alias-menu.png new file mode 100644 index 00000000000..e5affa18b0f Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/add-alias-menu.png differ diff --git a/docs/managed-devops-pools/media/configure-images/add-alias-pane.png b/docs/managed-devops-pools/media/configure-images/add-alias-pane.png new file mode 100644 index 00000000000..50be9bf1afa Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/add-alias-pane.png differ diff --git a/docs/managed-devops-pools/media/configure-images/add-from-image-library.png b/docs/managed-devops-pools/media/configure-images/add-from-image-library.png new file mode 100644 index 00000000000..fd664ade2e6 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/add-from-image-library.png differ diff --git a/docs/managed-devops-pools/media/configure-images/add-role-assignment-button.png b/docs/managed-devops-pools/media/configure-images/add-role-assignment-button.png new file mode 100644 index 00000000000..5a3f99992dd Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/add-role-assignment-button.png differ diff --git a/docs/managed-devops-pools/media/configure-images/configure-pool-image.png b/docs/managed-devops-pools/media/configure-images/configure-pool-image.png new file mode 100644 index 00000000000..a5962673eb0 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/configure-pool-image.png differ diff --git a/docs/managed-devops-pools/media/configure-images/image-library-azure-pipelines-images.png b/docs/managed-devops-pools/media/configure-images/image-library-azure-pipelines-images.png new file mode 100644 index 00000000000..e82b8049428 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/image-library-azure-pipelines-images.png differ diff --git a/docs/managed-devops-pools/media/configure-images/image-library-compute-gallery-images.png b/docs/managed-devops-pools/media/configure-images/image-library-compute-gallery-images.png new file mode 100644 index 00000000000..96718602e63 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/image-library-compute-gallery-images.png differ diff --git a/docs/managed-devops-pools/media/configure-images/image-library-marketplace-images.png b/docs/managed-devops-pools/media/configure-images/image-library-marketplace-images.png new file mode 100644 index 00000000000..3d82f3b5274 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/image-library-marketplace-images.png differ diff --git a/docs/managed-devops-pools/media/configure-images/multiple-images-with-aliases.png b/docs/managed-devops-pools/media/configure-images/multiple-images-with-aliases.png new file mode 100644 index 00000000000..a2fd4caf28e Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/multiple-images-with-aliases.png differ diff --git a/docs/managed-devops-pools/media/configure-images/select-devops-infrastructure-add.png b/docs/managed-devops-pools/media/configure-images/select-devops-infrastructure-add.png new file mode 100644 index 00000000000..23d4a82fc29 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/select-devops-infrastructure-add.png differ diff --git a/docs/managed-devops-pools/media/configure-images/select-devops-infrastructure.png b/docs/managed-devops-pools/media/configure-images/select-devops-infrastructure.png new file mode 100644 index 00000000000..4f6fe43a896 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/select-devops-infrastructure.png differ diff --git a/docs/managed-devops-pools/media/configure-images/select-members-role-assignment.png b/docs/managed-devops-pools/media/configure-images/select-members-role-assignment.png new file mode 100644 index 00000000000..61ef42aa82e Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/select-members-role-assignment.png differ diff --git a/docs/managed-devops-pools/media/configure-images/select-reader-role.png b/docs/managed-devops-pools/media/configure-images/select-reader-role.png new file mode 100644 index 00000000000..f6cf733d820 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-images/select-reader-role.png differ diff --git a/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-MDPSubNet-Delegation.png b/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-MDPSubNet-Delegation.png new file mode 100644 index 00000000000..1e938cef1a8 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-MDPSubNet-Delegation.png differ diff --git a/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-MDPSubNet.png b/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-MDPSubNet.png new file mode 100644 index 00000000000..52a210fe5b7 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-MDPSubNet.png differ diff --git a/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-RP-Perms - Copy.png b/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-RP-Perms - Copy.png new file mode 100644 index 00000000000..7067c95d34c Binary files /dev/null and b/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-RP-Perms - Copy.png differ diff --git a/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-RP-Perms.png b/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-RP-Perms.png new file mode 100644 index 00000000000..42bedbcee6b Binary files /dev/null and b/docs/managed-devops-pools/media/configure-networking/MDP-BYO-Networking-RP-Perms.png differ diff --git a/docs/managed-devops-pools/media/configure-networking/customrole.png b/docs/managed-devops-pools/media/configure-networking/customrole.png new file mode 100644 index 00000000000..0ba0d6fe517 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-networking/customrole.png differ diff --git a/docs/managed-devops-pools/media/configure-networking/devops-infrastructure-access.png b/docs/managed-devops-pools/media/configure-networking/devops-infrastructure-access.png new file mode 100644 index 00000000000..c0bb0e1a4cf Binary files /dev/null and b/docs/managed-devops-pools/media/configure-networking/devops-infrastructure-access.png differ diff --git a/docs/managed-devops-pools/media/configure-networking/inject-agents-configure-option.png b/docs/managed-devops-pools/media/configure-networking/inject-agents-configure-option.png new file mode 100644 index 00000000000..f4d2189361b Binary files /dev/null and b/docs/managed-devops-pools/media/configure-networking/inject-agents-configure-option.png differ diff --git a/docs/managed-devops-pools/media/configure-networking/permissions-check-access.png b/docs/managed-devops-pools/media/configure-networking/permissions-check-access.png new file mode 100644 index 00000000000..318ac3cd2db Binary files /dev/null and b/docs/managed-devops-pools/media/configure-networking/permissions-check-access.png differ diff --git a/docs/managed-devops-pools/media/configure-networking/subnet-resource.png b/docs/managed-devops-pools/media/configure-networking/subnet-resource.png new file mode 100644 index 00000000000..1ece3019d8e Binary files /dev/null and b/docs/managed-devops-pools/media/configure-networking/subnet-resource.png differ diff --git a/docs/managed-devops-pools/media/configure-networking/verify-permissions.png b/docs/managed-devops-pools/media/configure-networking/verify-permissions.png new file mode 100644 index 00000000000..09403a779c0 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-networking/verify-permissions.png differ diff --git a/docs/managed-devops-pools/media/configure-security/configure-keyvault.png b/docs/managed-devops-pools/media/configure-security/configure-keyvault.png new file mode 100644 index 00000000000..4d8062a135e Binary files /dev/null and b/docs/managed-devops-pools/media/configure-security/configure-keyvault.png differ diff --git a/docs/managed-devops-pools/media/configure-security/interactive-mode.png b/docs/managed-devops-pools/media/configure-security/interactive-mode.png new file mode 100644 index 00000000000..f01cab45e45 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-security/interactive-mode.png differ diff --git a/docs/managed-devops-pools/media/configure-security/key-vault-configuration-menu.png b/docs/managed-devops-pools/media/configure-security/key-vault-configuration-menu.png new file mode 100644 index 00000000000..778884a665b Binary files /dev/null and b/docs/managed-devops-pools/media/configure-security/key-vault-configuration-menu.png differ diff --git a/docs/managed-devops-pools/media/configure-security/pool-admin-permissions.png b/docs/managed-devops-pools/media/configure-security/pool-admin-permissions.png new file mode 100644 index 00000000000..f6a83ca4b51 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-security/pool-admin-permissions.png differ diff --git a/docs/managed-devops-pools/media/configure-security/single-organization-projects.png b/docs/managed-devops-pools/media/configure-security/single-organization-projects.png new file mode 100644 index 00000000000..a7cad7046e0 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-security/single-organization-projects.png differ diff --git a/docs/managed-devops-pools/media/configure-security/single-organization.png b/docs/managed-devops-pools/media/configure-security/single-organization.png new file mode 100644 index 00000000000..68aff6d067c Binary files /dev/null and b/docs/managed-devops-pools/media/configure-security/single-organization.png differ diff --git a/docs/managed-devops-pools/media/configure-security/use-pool-multiple-organizations.png b/docs/managed-devops-pools/media/configure-security/use-pool-multiple-organizations.png new file mode 100644 index 00000000000..fd716f41fdf Binary files /dev/null and b/docs/managed-devops-pools/media/configure-security/use-pool-multiple-organizations.png differ diff --git a/docs/managed-devops-pools/media/configure-stateful-pool/MDP-stateful-pool-alwayson.png b/docs/managed-devops-pools/media/configure-stateful-pool/MDP-stateful-pool-alwayson.png new file mode 100644 index 00000000000..60849e80588 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-stateful-pool/MDP-stateful-pool-alwayson.png differ diff --git a/docs/managed-devops-pools/media/configure-stateful-pool/MDP-stateful-pool-weekdayworkinghours.png b/docs/managed-devops-pools/media/configure-stateful-pool/MDP-stateful-pool-weekdayworkinghours.png new file mode 100644 index 00000000000..a350acdc1c6 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-stateful-pool/MDP-stateful-pool-weekdayworkinghours.png differ diff --git a/docs/managed-devops-pools/media/configure-storage/empty-data-disk-menu.png b/docs/managed-devops-pools/media/configure-storage/empty-data-disk-menu.png new file mode 100644 index 00000000000..c59523ee45d Binary files /dev/null and b/docs/managed-devops-pools/media/configure-storage/empty-data-disk-menu.png differ diff --git a/docs/managed-devops-pools/media/configure-storage/empty-data-disk-pool-creation.png b/docs/managed-devops-pools/media/configure-storage/empty-data-disk-pool-creation.png new file mode 100644 index 00000000000..def678d97d2 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-storage/empty-data-disk-pool-creation.png differ diff --git a/docs/managed-devops-pools/media/diagnostics/add-diagnostic-setting.png b/docs/managed-devops-pools/media/diagnostics/add-diagnostic-setting.png new file mode 100644 index 00000000000..7464618d5a7 Binary files /dev/null and b/docs/managed-devops-pools/media/diagnostics/add-diagnostic-setting.png differ diff --git a/docs/managed-devops-pools/media/diagnostics/diagnostics.png b/docs/managed-devops-pools/media/diagnostics/diagnostics.png new file mode 100644 index 00000000000..210c4dd28b4 Binary files /dev/null and b/docs/managed-devops-pools/media/diagnostics/diagnostics.png differ diff --git a/docs/managed-devops-pools/media/get-started/agent-pool-delete.png b/docs/managed-devops-pools/media/get-started/agent-pool-delete.png new file mode 100644 index 00000000000..1cf8c0fe366 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/agent-pool-delete.png differ diff --git a/docs/managed-devops-pools/media/get-started/agent-pools-list.png b/docs/managed-devops-pools/media/get-started/agent-pools-list.png new file mode 100644 index 00000000000..2eee813edae Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/agent-pools-list.png differ diff --git a/docs/managed-devops-pools/media/get-started/agent-size-count-os-disk-type.png b/docs/managed-devops-pools/media/get-started/agent-size-count-os-disk-type.png new file mode 100644 index 00000000000..18edca3da08 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/agent-size-count-os-disk-type.png differ diff --git a/docs/managed-devops-pools/media/get-started/azure-devops-organization-and-pool.png b/docs/managed-devops-pools/media/get-started/azure-devops-organization-and-pool.png new file mode 100644 index 00000000000..df64dc25788 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/azure-devops-organization-and-pool.png differ diff --git a/docs/managed-devops-pools/media/get-started/choose-repo-type.png b/docs/managed-devops-pools/media/get-started/choose-repo-type.png new file mode 100644 index 00000000000..26816206e34 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/choose-repo-type.png differ diff --git a/docs/managed-devops-pools/media/get-started/choose-repository.png b/docs/managed-devops-pools/media/get-started/choose-repository.png new file mode 100644 index 00000000000..db22b8b6d66 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/choose-repository.png differ diff --git a/docs/managed-devops-pools/media/get-started/choose-starter-pipeline.png b/docs/managed-devops-pools/media/get-started/choose-starter-pipeline.png new file mode 100644 index 00000000000..85fd6979f13 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/choose-starter-pipeline.png differ diff --git a/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-button.png b/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-button.png new file mode 100644 index 00000000000..28d3e6ce025 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-button.png differ diff --git a/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-initial-settings.png b/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-initial-settings.png new file mode 100644 index 00000000000..5313bf7305d Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-initial-settings.png differ diff --git a/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-settings.png b/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-settings.png new file mode 100644 index 00000000000..a5da72d59e9 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-settings.png differ diff --git a/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-tabs.png b/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-tabs.png new file mode 100644 index 00000000000..638f880f321 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/create-managed-devops-pools-tabs.png differ diff --git a/docs/managed-devops-pools/media/get-started/github-pool-basic-settings.png b/docs/managed-devops-pools/media/get-started/github-pool-basic-settings.png new file mode 100644 index 00000000000..0e8346f536a Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/github-pool-basic-settings.png differ diff --git a/docs/managed-devops-pools/media/get-started/new-pipeline-button.png b/docs/managed-devops-pools/media/get-started/new-pipeline-button.png new file mode 100644 index 00000000000..81243b6b622 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/new-pipeline-button.png differ diff --git a/docs/managed-devops-pools/media/get-started/project-pipelines.png b/docs/managed-devops-pools/media/get-started/project-pipelines.png new file mode 100644 index 00000000000..170a8dc5e89 Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/project-pipelines.png differ diff --git a/docs/managed-devops-pools/media/get-started/save-and-run.png b/docs/managed-devops-pools/media/get-started/save-and-run.png new file mode 100644 index 00000000000..3c139f652ac Binary files /dev/null and b/docs/managed-devops-pools/media/get-started/save-and-run.png differ diff --git a/docs/managed-devops-pools/media/pool-settings/agent-size.png b/docs/managed-devops-pools/media/pool-settings/agent-size.png new file mode 100644 index 00000000000..8a4fb2a2e11 Binary files /dev/null and b/docs/managed-devops-pools/media/pool-settings/agent-size.png differ diff --git a/docs/managed-devops-pools/media/pool-settings/dev-center.png b/docs/managed-devops-pools/media/pool-settings/dev-center.png new file mode 100644 index 00000000000..fd1fbdcc05e Binary files /dev/null and b/docs/managed-devops-pools/media/pool-settings/dev-center.png differ diff --git a/docs/managed-devops-pools/media/pool-settings/essentials-expanded.png b/docs/managed-devops-pools/media/pool-settings/essentials-expanded.png new file mode 100644 index 00000000000..e2bc043904d Binary files /dev/null and b/docs/managed-devops-pools/media/pool-settings/essentials-expanded.png differ diff --git a/docs/managed-devops-pools/media/pool-settings/essentials.png b/docs/managed-devops-pools/media/pool-settings/essentials.png new file mode 100644 index 00000000000..3125936ce09 Binary files /dev/null and b/docs/managed-devops-pools/media/pool-settings/essentials.png differ diff --git a/docs/managed-devops-pools/media/pool-settings/json-view-button.png b/docs/managed-devops-pools/media/pool-settings/json-view-button.png new file mode 100644 index 00000000000..ea6ff64378f Binary files /dev/null and b/docs/managed-devops-pools/media/pool-settings/json-view-button.png differ diff --git a/docs/managed-devops-pools/media/pool-settings/maximum-agents.png b/docs/managed-devops-pools/media/pool-settings/maximum-agents.png new file mode 100644 index 00000000000..7787b055c5d Binary files /dev/null and b/docs/managed-devops-pools/media/pool-settings/maximum-agents.png differ diff --git a/docs/managed-devops-pools/media/pool-settings/os-disk-type.png b/docs/managed-devops-pools/media/pool-settings/os-disk-type.png new file mode 100644 index 00000000000..8cecde4560d Binary files /dev/null and b/docs/managed-devops-pools/media/pool-settings/os-disk-type.png differ diff --git a/docs/managed-devops-pools/media/pool-settings/pool-settings-menu.png b/docs/managed-devops-pools/media/pool-settings/pool-settings-menu.png new file mode 100644 index 00000000000..ff7bcbc228c Binary files /dev/null and b/docs/managed-devops-pools/media/pool-settings/pool-settings-menu.png differ diff --git a/docs/managed-devops-pools/media/pool-settings/single-organization.png b/docs/managed-devops-pools/media/pool-settings/single-organization.png new file mode 100644 index 00000000000..6563ec9380f Binary files /dev/null and b/docs/managed-devops-pools/media/pool-settings/single-organization.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/add-identity-to-users.png b/docs/managed-devops-pools/media/prerequisites/add-identity-to-users.png new file mode 100644 index 00000000000..4d3e6ef0394 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/add-identity-to-users.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/add-project-collection-administrator.png b/docs/managed-devops-pools/media/prerequisites/add-project-collection-administrator.png new file mode 100644 index 00000000000..9c5d00a3f29 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/add-project-collection-administrator.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/create-dev-center-proect-button.png b/docs/managed-devops-pools/media/prerequisites/create-dev-center-proect-button.png new file mode 100644 index 00000000000..f2502da5d11 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/create-dev-center-proect-button.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/create-dev-center-project.png b/docs/managed-devops-pools/media/prerequisites/create-dev-center-project.png new file mode 100644 index 00000000000..525ea0d28ee Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/create-dev-center-project.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/create-dev-center.png b/docs/managed-devops-pools/media/prerequisites/create-dev-center.png new file mode 100644 index 00000000000..cbfc049b58a Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/create-dev-center.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/create-identity-button.png b/docs/managed-devops-pools/media/prerequisites/create-identity-button.png new file mode 100644 index 00000000000..841e29d281f Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/create-identity-button.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/create-identity.png b/docs/managed-devops-pools/media/prerequisites/create-identity.png new file mode 100644 index 00000000000..2a0ab611aae Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/create-identity.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/dev-center-create-button.png b/docs/managed-devops-pools/media/prerequisites/dev-center-create-button.png new file mode 100644 index 00000000000..86d45d2dca9 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/dev-center-create-button.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/manageddevops-app-github.png b/docs/managed-devops-pools/media/prerequisites/manageddevops-app-github.png new file mode 100644 index 00000000000..12ea3313fbb Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/manageddevops-app-github.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/members-add.png b/docs/managed-devops-pools/media/prerequisites/members-add.png new file mode 100644 index 00000000000..9e202e3056d Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/members-add.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/organization-settings.png b/docs/managed-devops-pools/media/prerequisites/organization-settings.png new file mode 100644 index 00000000000..5e271889143 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/organization-settings.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/register-resource-provider.png b/docs/managed-devops-pools/media/prerequisites/register-resource-provider.png new file mode 100644 index 00000000000..2a1986391ea Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/register-resource-provider.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/security-permissions.png b/docs/managed-devops-pools/media/prerequisites/security-permissions.png new file mode 100644 index 00000000000..cea6af2377e Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/security-permissions.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/users-add-users.png b/docs/managed-devops-pools/media/prerequisites/users-add-users.png new file mode 100644 index 00000000000..424540423c9 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/users-add-users.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/view-provider-regions-small.png b/docs/managed-devops-pools/media/prerequisites/view-provider-regions-small.png new file mode 100644 index 00000000000..c3a8cdae5a0 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/view-provider-regions-small.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/view-provider-regions.png b/docs/managed-devops-pools/media/prerequisites/view-provider-regions.png new file mode 100644 index 00000000000..dc2fa9cde44 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/view-provider-regions.png differ diff --git a/docs/managed-devops-pools/media/quotas/new-quota-request.png b/docs/managed-devops-pools/media/quotas/new-quota-request.png new file mode 100644 index 00000000000..93742453437 Binary files /dev/null and b/docs/managed-devops-pools/media/quotas/new-quota-request.png differ diff --git a/docs/managed-devops-pools/media/quotas/new-support-request-quota-details.png b/docs/managed-devops-pools/media/quotas/new-support-request-quota-details.png new file mode 100644 index 00000000000..56721df59cc Binary files /dev/null and b/docs/managed-devops-pools/media/quotas/new-support-request-quota-details.png differ diff --git a/docs/managed-devops-pools/media/quotas/new-support-request.png b/docs/managed-devops-pools/media/quotas/new-support-request.png new file mode 100644 index 00000000000..d2b8c1d9088 Binary files /dev/null and b/docs/managed-devops-pools/media/quotas/new-support-request.png differ diff --git a/docs/managed-devops-pools/media/quotas/quota-request-granted.png b/docs/managed-devops-pools/media/quotas/quota-request-granted.png new file mode 100644 index 00000000000..88dcab0cd99 Binary files /dev/null and b/docs/managed-devops-pools/media/quotas/quota-request-granted.png differ diff --git a/docs/managed-devops-pools/media/quotas/quotas-list.png b/docs/managed-devops-pools/media/quotas/quotas-list.png new file mode 100644 index 00000000000..a0dfb48d453 Binary files /dev/null and b/docs/managed-devops-pools/media/quotas/quotas-list.png differ diff --git a/docs/managed-devops-pools/media/quotas/quotas-overview.png b/docs/managed-devops-pools/media/quotas/quotas-overview.png new file mode 100644 index 00000000000..c6801313fb2 Binary files /dev/null and b/docs/managed-devops-pools/media/quotas/quotas-overview.png differ diff --git a/docs/managed-devops-pools/media/quotas/quotas-search.png b/docs/managed-devops-pools/media/quotas/quotas-search.png new file mode 100644 index 00000000000..2b33d4d0b7b Binary files /dev/null and b/docs/managed-devops-pools/media/quotas/quotas-search.png differ diff --git a/docs/managed-devops-pools/media/quotas/request-adjustment-menu.png b/docs/managed-devops-pools/media/quotas/request-adjustment-menu.png new file mode 100644 index 00000000000..47f61ebf8f9 Binary files /dev/null and b/docs/managed-devops-pools/media/quotas/request-adjustment-menu.png differ diff --git a/docs/managed-devops-pools/media/quotas/support-request-enter-details-link.png b/docs/managed-devops-pools/media/quotas/support-request-enter-details-link.png new file mode 100644 index 00000000000..9621f4c13fe Binary files /dev/null and b/docs/managed-devops-pools/media/quotas/support-request-enter-details-link.png differ diff --git a/docs/managed-devops-pools/migrate-from-scale-set-agents.md b/docs/managed-devops-pools/migrate-from-scale-set-agents.md new file mode 100644 index 00000000000..253872139a4 --- /dev/null +++ b/docs/managed-devops-pools/migrate-from-scale-set-agents.md @@ -0,0 +1,64 @@ +--- +title: Compare Managed DevOps Pools with Azure Virtual Machine Scale Set agents +description: Learn about the differences between Managed DevOps Pools and Azure Virtual Machine Scale Set agents. +ms.date: 12/10/2024 +ms.topic: overview +#Customer intent: As a platform engineer, I want to understand the benefits of using Managed DevOps Pools over Azure Virtual Machine Scale Set agents. +--- + +# Compare Managed DevOps Pools with Azure Virtual Machine Scale Set agents + +[!INCLUDE [mdp-recommended](./includes/mdp-recommended.md)] + +## Feature comparison + +The following table compares features of Managed DevOps Pools and scale set agents. + +| Feature | Managed DevOps Pools | Azure virtual machine scale set agent pools | +|---------|----------------------|------------------| +| Pricing | Pricing is the same for Managed DevOps Pools and Scale set agents. See [Pricing](#pricing) for more information. | Same as Managed DevOps Pools pricing | +| Virtual machine hosting | [Agents run on a Microsoft Azure subscription](./architecture-overview.md) | Agents run on your Azure subscription | +| Standby agent schedule | Provides flexible scheduling options to configure the number of standby agents available at different times as well as an automatic standby agent option | Supports a single standby agent count setting (equivalent to Managed DevOps Pools [All Week Scheme](./configure-scaling.md#all-week-scheme)) | +| Scaling granularity | Scale out is done in increments of one | Scale out is done in increments of a percentage of the maximum pool size, potentially resulting in extra idle agents for which you are billed | +| Pool size | Support for thousands of agents | Support for hundreds of agents | +| Multiple images | Support for multiple images in your pool | Supports only a single image | +| Quota | Quota is dedicated to the Managed DevOps Pools resource and not shared with other services in your subscription | Uses Compute quota shared with other services in your subscription | +| Virtual network support | Support for running in a private network or joining your existing virtual network | Supported | +| Image support | [Azure Pipelines images (same as Microsoft-hosted agent images for Windows and Linux)](./configure-images.md#azure-pipelines-images), [selected Azure Marketplace images, Azure compute gallery images](./configure-images.md) | [Azure Marketplace images and custom images](/azure/devops/pipelines/agents/scale-set-agents#create-the-scale-set) | +| VMSS extension scripts | Not supported, but you can configure your custom image with the required software | You can run a custom script on your agent before it starts running pipeline jobs | +| Azure Key Vault integration | Download Azure Key Vault certificates to your agent automatically | Key vault certificates can be preinstalled on your custom images, or downloaded using tasks or VMSS extension scripts | +| Multiple organizations | Support for using a pool in multiple Azure DevOps organizations, and optionally restrict the pool to certain projects | Supports a single Azure DevOps organization | +| Stateless agents | Supported | [Supported on Windows Server and selected Linux images](/azure/devops/pipelines/agents/scale-set-agents#you-check-the-option-to-automatically-tear-down-virtual-machines-after-every-use-for-the-agent-pool-but-you-see-that-the-vms-arent-re-imaging-as-they-should-and-just-pick-up-new-jobs-as-theyre-queued) | +| Stateful agents | Supported | Supported | +| Spot Virtual Machine support | On product roadmap | Not supported | +| Containers | Coming soon | Not supported | +| BCDR | On product roadmap: You will have the ability to configure backup pools for your primary pools to automatically send requests to the backup pools when your primary pool's health degrades | [Supports availability sets and zones](/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-faq#do-scale-sets-work-with-azure-availability-sets-) | + +### Map scale set agent settings to Managed DevOps Pools + +You can configure a Managed DevOps Pool with the same behavior as your Azure virtual machine scale set agent pool by mapping the scale set agent pool settings to their Managed DevOps Pools equivalent. +The following table lists scale set agent pool properties and the corresponding Managed DevOps Pools property that configures the equivalent behavior. + +| Scale set agents setting | Managed DevOps Pools setting | +|------------------|----------------------| +| Automatically tear down virtual machines after every use | Choose [stateless pools](./configure-scaling.md#stateless-pools) for a fresh agent for every job (Automatically tear down virtual machines after every use), or [stateful pools](./configure-scaling.md#stateful-pools) for persistent agents | +| Save an unhealthy agent for investigation | Not available in Managed DevOps Pools | +| Maximum number of virtual machines in the scale set | [Maximum agents](./configure-pool-settings.md#maximum-agents) | +| Number of agents to keep on standby | Choose [All week scheme](./configure-scaling.md#all-week-scheme) for the same behavior as scale set agents, configure a [flexible schedule](./configure-scaling.md#manual), or choose [Automatic standby agent scheduling](./configure-scaling.md#automatic) | +| Delay in minutes before deleting excess idle agents | [Grace period for stateful pools](./configure-scaling.md#stateful-pools) | +| Configure VMs to run interactive tests | [Enable Interactive Mode](./configure-security.md#configure-interactive-mode) | + +## Pricing + +Managed DevOps Pools and Azure virtual machine scale set agents pricing is calculated in the same way and has two components: + +1. **Azure DevOps self-hosted parallel job pricing** - Azure DevOps refers to the capability to run pipeline jobs concurrently as **parallel jobs**. Both Managed DevOps Pools and Azure virtual machine scale set agents use self-hosted parallel jobs. Each parallel job allows you to run a pipeline job. To run two pipeline jobs concurrently, you need two parallel jobs. For more information on parallel jobs, see [Managed DevOps Pools pricing - parallel job pricing](./pricing.md#azure-devops-services-parallel-job-pricing) and [Configure and pay for parallel jobs](../pipelines/licensing/concurrent-jobs.md?tabs=self-hosted). + +2. **Azure services pricing** - Azure services pricing for Managed DevOps Pools and Azure virtual machine scale set agents is determined by the cost of the Azure services your pool uses, like compute, storage, and data egress. + +Some Managed DevOps Pools features, like flexible standby agent scheduling, and more granular scaling, can reduce the number of idle agents waiting for jobs. Support for multiple images and SKUs lets you choose the right sized Azure resources to support your workload, instead of being limited to a single image or SKU. + +## See also + +* [Managed DevOps Pools pricing](./pricing.md) +* [Manage cost and performance of Managed DevOps Pools](./manage-costs.md) diff --git a/docs/managed-devops-pools/monitor-pool.md b/docs/managed-devops-pools/monitor-pool.md new file mode 100644 index 00000000000..32537edab02 --- /dev/null +++ b/docs/managed-devops-pools/monitor-pool.md @@ -0,0 +1,137 @@ +--- +title: Monitor +description: Learn how to view the health of your Managed DevOps Pools. +ms.date: 11/13/2024 +--- + +# Monitor Managed DevOps Pools + +Managed DevOps Pools provides several options for monitoring your pool instances. The **Overview** page provides predefined metrics charts, and you can configure custom charts on the **Metrics** page. Use these tools to monitor the health of your Managed DevOps Pools instances. + +## Available metrics + +Managed DevOps Pools provides the following metrics: + +| Metric | Unit | [Aggregations](/azure/azure-monitor/essentials/metrics-aggregation-explained) | [Dimensions](/azure/azure-monitor/essentials/analyze-metrics#use-dimension-filters-and-splitting) | +|---|---|---|---| +| **AllocationDurationMS**
      Average pool request duration | Milliseconds | Average | `Image`, `PoolId`, `ResourceRequestType`, `Type` | +| **Allocated**
      Number of Azure DevOps Agents with jobs currently running | Count | Average, Min, Max | `Images`, `PoolId`, `ProviderName`, `SKU` | +| **NotReady**
      Number of Azure DevOps Agents that are not set up for testing | Count | Average, Min, Max | `Images`, `PoolId`, `ProviderName`, `SKU` | +| **PendingReimage**
      Number of Azure DevOps Agents in the process of being reimaged | Count | Average, Min, Max | `Images`, `PoolId`, `ProviderName`, `SKU` | +| **PendingReturn**
      Number of Azure DevOps Agents that are post-cleanup, waiting to be deleted (which occur in batches) | Count | Average, Min, Max | `Images`, `PoolId`, `ProviderName`, `SKU` | +| **Provisioned**
      Number of Azure DevOps Agents currently up | Count | Average, Min, Max | `Images`, `PoolId`, `ProviderName`, `SKU` | +| **Ready**
      Number of Azure DevOps Agents present that are prepared to accept a job | Count | Average, Min, Max | `Images`, `PoolId`, `ProviderName`, `SKU` | +| **Starting**
      Number of Azure DevOps Agents being prepared | Count | Average, Min, Max | `Images`, `PoolId`, `ProviderName`, `SKU` | +| **Total**
      Total number of Azure DevOps Agents | Count | Average, Min, Max | `Images`, `PoolId`, `ProviderName`, `SKU` | +| **Count**
      Total number of agents provisioned, grouped by status | Count | Count | `ErrorCode`, `FailureStage`, `PoolId`, `RequestType`, `Status`, `Type` | + +### Filtering and splitting + +Azure Monitor supports filtering and splitting for metrics that have dimensions. Managed DevOps Pools provides the following dimensions. See the previous table to a list of which dimensions apply for a particular metric. + +| Dimension | Description | +|-----------|-------------| +| `Image` | Image name | +| `Images` | List of images | +| `PoolId` | Name of Managed DevOps Pool | +| `ProviderName` | CI/CD provider (AzureProvider is currently the only provider) | +| `ResourceRequestType` | | +| `SKU` | VM size | +| `Type` | | +| `ErrorCode` | One of the error codes listed in [Error codes](#error-codes) | +| `FailureStage` | | +| `RequestType` | | +| `Status` | Agent status | + + +**Filtering** lets you choose which dimension values are included in the chart. You might want to show successful requests when you chart the **Total number of agents provisions Count** metric. You apply the filter on the **Status** dimension. + +**Splitting** controls whether the chart displays separate lines for each value of a dimension or aggregates the values into a single line. Splitting allows you to visualize how different segments of the metric compare with each other. You can see one line for an average **AllocationDurationMS** across all pools, or you can see separate lines for each pool. + +For more information, see [Analyze Metrics, Use dimension filters and splitting](/azure/azure-monitor/essentials/analyze-metrics#use-dimension-filters-and-splitting). + +## View metrics on the Managed DevOps Pool Overview + +The **Overview** page for your Managed DevOps Pool contains the following predefined metrics charts, which can be set to display metrics for the past hour, day, 7 days, or 30 days. + +- [Pool Usage](#pool-usage-chart) +- [Pool Provisioning Health](#pool-provisioning-health-chart) +- [Request Durations](#request-durations-chart) +- [Failure Stages](#failure-stages-chart) +- [Error Codes](#error-codes-chart) + +You can customize the charts or create your own. For more information, see [Analyze metrics, Create a metric chart](/azure/azure-monitor/essentials/analyze-metrics#create-a-metric-chart). + +### Pool Usage chart + +The **Pool Usage** chart displays the following metrics. + +- Starting: Count of agents starting up and preparing to accept jobs. +- Ready: Count of agents only and ready to accept jobs. +- Allocated: Count of agents currently running jobs. +- NotReady: Count of stateful agents that have completed a job but are not yet ready to accept a new job. +- PendingReimage: Count of agents that have completed a job and are preparing to be reimaged. This status is typical if you have your pool configured for stateless agents with standby agent mode enabled. +- PendingReturn: Number of Azure DevOps Agents that are post-cleanup, waiting to be deleted (which occurs in batches) +- Provisioned: Count of online agents. +- Total: Total number of agents. + +### Pool Provisioning Health chart + +The **Pool Provisioning Health** chart displays the following metrics. + +- Count - Total number of agents provisioned, grouped by status (Completed/Failed) + +### Request Durations chart + +The **Request Durations** chart displays the following metrics. + +- AllocationDurationMS - Average pool request duration + +### Failure Stages chart + +The **Failure Stages** chart displays the following metrics. + +- Count - Total number of agents that failed to provision, grouped by FailureStage + +### Error Codes chart + +The **Error Codes** chart displays the following metrics. + +- Count - Total number of agents that failed to provision, grouped by ErrorCode + +For a list of error codes, see the following [Error codes](#error-codes) section. + +## Error codes + +| Error code | Error message | +|---|---| +| `AzureInternalServerError` | The VM allocation failed due to an internal error. Retry later or try deploying to a different location. | +| `ClusterOutOfCapacity` | Allocation failed. Note that allocation for this subscription is constrained to a set of clusters, which may be out of capacity. To remove the cluster constraint, contact the subscription administrator or Microsoft Support. Read more about improving likelihood of allocation success at `https://aka.ms/allocation-guidance`. | +| `CustomScriptError` | VM reported a failure when processing extension 'customScript' (publisher 'Microsoft.Compute' and type 'CustomScriptExtension'). Error message: 'Finished executing command'. More information on troubleshooting is available at `https://aka.ms/VMExtensionCSEWindowsTroubleshoot`. | +| `DiskProcessingTimeout` | The processing of VM '...' is halted because of one or more disk processing errors encountered by VM '...' in the same Availability Set. Resolve the error with VM '...' before retrying the operation. For more information, refer to `https://aka.ms/activitylog`. | +| `EndpointNotFound` | 404 - There are no listeners connected for the endpoint. TrackingId:00000000-0000-0000-0000-0000000000, SystemTracker:tipresourceprovider.servicebus.windows.net:tipresourceproviderconnection/pools/es_tap_prime_cus_d4ds, Timestamp:2024-02-15T21:15:57 | +| `ExceedingQuota` | Quota exceeded. | +| `FailedToRetrieveUserPassword` | Failed to retrieve user password ... from Key Vault | +| `ForbiddenByFirewall` | Forbidden | +| `HTTPResponseBodyNotAvailable` | HTTP response body isn't available | +| `ImageNotFound` | The image could not be found. Check the image and the version exists | +| `ImageRemovedFromPool` | The given key was not present in the dictionary | +| `ImageThrottling` | Too many simultaneous copy requests from a snapshot or image resource. Retry later. | +| `InstallationOfWindowsUndeployable` | OS provisioning for VM failed. Error details: This installation of Windows is undeployable. Make sure the image is properly prepared (generalized). Instructions for Windows: `https://azure.microsoft.com/documentation/articles/virtual-machines-windows-upload-image/` | +| `InsufficientCapacity` | Allocation failed. We do not have sufficient capacity for the requested VM size in this region. Read more about improving likelihood of allocation success at `https://aka.ms/allocation-guidance` | +| `InvalidSubnetDelegation` | Subnet `/subscriptions/{subscriptionId}/resourceGroups/{rgName}/providers/Microsoft.Network/virtualNetworks/{vnetName}/subnets/{subnetName}` referenced by `/subscriptions/{subscriptionId}/resourceGroups/{rgName}/providers/Microsoft.Compute/virtualMachineScaleSets/{}/updateGroups/version1/networkInterfaceConfigurations/nic/ipConfigurations/ipconfig` can't be used because it contains external resources. | +| `NetworkProfileProcessingTimeout` | An unexpected error occurred while processing the network profile of the VM. Retry later. | +| `ProvisioningTimeOut` | Resource `subscriptions/{subscriptionId}/resourceGroups/{rgName}/providers/Microsoft.Network/networkInterfaces/providers/Microsoft.Compute/virtualMachineScaleSets/{}/virtualMachines/networkInterfaces/nic` not found. OS Provisioning for VM did not finish in the allotted time. The VM may still finish provisioning successfully. Check provisioning state later. Also, make sure the image has been properly prepared (generalized). Instructions for Windows: `https://azure.microsoft.com/documentation/articles/virtual-machines-windows-upload-image/` Instructions for Linux: `https://azure.microsoft.com/documentation/articles/virtual-machines-linux-capture-image/` If you are deploying more than 20 Virtual Machines concurrently, consider moving your custom image to shared image gallery. Refer to `https://aka.ms/movetosig` for the same. | +| `RemoteNameCantBeResolved` | | +| `ResourceGroupBeingDeleted` | The resource group ... is in deprovisioning state and can't perform this operation. | +| `SecretDisabled` | Operation get isn't allowed on a disabled secret. Status: 403 (Forbidden) ErrorCode: Forbidden | +| `ServiceUnavailable` | The service is unavailable now. Retry the request later. | +| `SkuNotAvailable` | The requested VM size for resource 'Following SKUs failed for Capacity Restrictions:' is currently not available in location. Try another size or deploy to a different location or different zone. See `https://aka.ms/azureskunotavailable` for details. | +| `TaskCanceled` | The request was canceled due to the configured HttpClient.Timeout of 100 seconds elapsing. | +| `VirtualNetworkIsNotFound` | The Virtual Network might be deleted. | + +## See also + +- [Azure Monitor documentation](/azure/azure-monitor/) +- [Azure Monitor overview](/azure/azure-monitor/overview) +- [Analyze and visualize monitoring data](/azure/azure-monitor/best-practices-analysis) diff --git a/docs/managed-devops-pools/overview.md b/docs/managed-devops-pools/overview.md new file mode 100644 index 00000000000..4273593fe27 --- /dev/null +++ b/docs/managed-devops-pools/overview.md @@ -0,0 +1,79 @@ +--- +title: Managed DevOps Pools Overview +description: Learn about Managed DevOps Pools. +ms.date: 03/25/2025 +ms.topic: overview +#Customer intent: As a platform engineer, I want to understand the benefits of using Managed DevOps Pools. +--- + +# Overview of Managed DevOps Pools + +Managed DevOps Pools empowers development teams to quickly and easily spin up Azure DevOps agent pools that are tailored to a team's specific needs. Managed DevOps Pools implements security best practices, provides knobs to balance cost and performance, provides paths for the most common scenarios, and significantly reduces time spent in creating and maintaining custom pools. + +Managed DevOps Pools is an evolution of Azure DevOps Virtual Machine Scale Set agent pools, simplifying custom pool creation even further, by improving scalability and reliability of custom pools. See [Compare Managed DevOps Pools with Azure Virtual Machine Scale Set agents](./migrate-from-scale-set-agents.md). Managed DevOps Pools is a fully managed service where virtual machines or containers powering the agents live in a Microsoft Azure subscription and not in your own Azure subscription, like when using Azure DevOps Virtual Machine Scale Set agent pools. For more information, see [Microsoft Managed DevOps Pools architecture overview](./architecture-overview.md). + +## Usage Scenarios + +Manage DevOps Pools: + +* Has more powerful agents than those available in the out-of-the-box agents +* Uses a virtual machine image that is custom tailored by you for your CI/CD workload +* Has agents in the geographical region closest to your dependencies +* Scales up and down based on your configuration +* Can maintain state of your agents up to seven days, so your builds are faster due to cache hits +* Can run long running workflows up to two days long +* Can access resources in your company network or isolate your workload to only access specific endpoints +* Can create agents that have the same software as Azure Pipelines Microsoft-hosted agents +* Can view all active agents and the status of agent provisioning and reimaging +* Can attach a data disk, so you don't have to use a larger SKU just to get more disk space +* See [Roadmap and features timeline](./features-timeline.md#roadmap) for features coming up. + +## What's new for Managed DevOps Pools GA + +**Managed DevOps Pools supported in more Azure regions**: Managed DevOps Pools is now available in Sweden Central, Brazil South, Japan East, UAE North, Korea Central, and Norway East, allowing you to leverage regional resources for optimized performance and compliance. To see the Azure regions that support Managed DevOps Pools in your subscription, [register the Microsoft.DevOpsInfrastructure provider in your subscription and view the supported locations](prerequisites.md#register-the-managed-devops-pools-resource-provider-in-your-azure-subscription). + +**Integrate with Azure Key Vault**: Managed DevOps Pools offers the ability to fetch certificates from an Azure Key Vault during provisioning, which means the certificates will already exist on the machine by the time it runs your Azure Pipelines. To use this feature, [configure a managed identity on your pool](./configure-identity.md), and grant it permissions to access secrets from your Key Vault. For more information, see [Integrate with Azure Key Vault](./configure-security.md#key-vault-configuration). + +**Proxy support**: You can set up your Managed DevOps Pools to direct network traffic through a proxy. By using an image with a preinstalled proxy, you can run your Azure Pipelines on Managed DevOps Pools behind a proxy, like the current Azure Virtual Machine Scale Set agents offering. This setup enables the agent to retrieve sources and download artifacts, passing the proxy details to tasks that also require proxy settings to access the web. For more information, see [Proxy support](./configure-networking.md#configure-the-azure-devops-agent-to-run-behind-a-proxy). + +**View agent IP address**: You can now view the IP address of the agent in the Initialize job step of your pipeline log, useful for scenarios such as investigating failing pipelines due to proxies or firewall rules. + +**Move to another resource group or subscription**: You now have the option to move your Managed DevOps Pools to another Azure resource group or to another subscription. For more information, see [Move Azure resources to a new resource group or subscription](/azure/azure-resource-manager/management/move-resource-group-and-subscription). + +**Ubuntu 24.04 support**: We've added support for Ubuntu 24.04 by adding three images to [Selected marketplace images](./configure-images.md#selected-marketplace-images) and enabling bring-your-own Ubuntu 24.04 images using [Azure Compute Gallery images](./configure-images.md#azure-compute-gallery-images). + +## Benefits + +Managed DevOps Pools provide the following benefits to creating, configuring, and managing Azure DevOps agent pools in the cloud: + +**Time spent in Management**: Managed DevOps Pools is designed to reduce time spent in managing CI/CD infrastructure. This will free up Platform Engineering cycles or Dev Team cycles to focus on other problems. + +**Team-specific Pools**: Due to the ease with which new pools can be created, Platform Engineering can very easily create multiple team-specific pools, preventing teams from noisy neighbor situations and tailoring pools to suit the needs of individual teams. + +**Worry-free Self-Service**: Platform Engineering can choose to empower development teams to create their own custom pools without compromising on governance, by allowing the use of curated images and networks. + +**Azure Cost**: Managed DevOps pools will help optimize your Azure cost based on your CI/CD workload's unique needs. + +**Scalable**: Managed DevOps pools are scalable up to thousands of agents running simultaneously. + +**Reliable**: Your developers will experience lowest amount of downtime due to the high uptimes of Managed DevOps pools. + +**Security**: Your pool's agents are secured by Microsoft's best practices, and has features to further secure your pool. + +## Get Started + +To start using Managed DevOps Pools, see [Get started with Managed DevOps Pools](./quickstart-azure-portal.md). + +## See also + +See what our MVPs are saying about Managed DevOps Pools. The following links take you to the respective author's external sites outside of Microsoft Learn. + +* [A first look at revolutionizing your cloud deployments with Azure Managed DevOps Pools](https://www.azureviking.com/post/a-first-look-at-revolutionizing-your-cloud-deployments-with-azure-managed-devops-pools) by Haflidi Fridthjofsson +* [A first look at using Azure Managed DevOps Pools](https://blogs.blackmarble.co.uk/rfennell/a-first-look-at-using-azure-mdp/) by Richard Fennell +* [Azure DevOps Managed DevOps pools](https://bjompen.com/#/posts/azdo.mdp?id=azure-devops-managed-devops-pools) by bjompen +* [Deploying in a private Azure environment using Managed DevOps Pools](https://logcorner.com/deploying-in-a-private-azure-environment-using-managed-devops-pools/) by Gora LEYE +* [Managed DevOps Pools: Simplifying Self-Hosted Azure Pipeline Agents]( +https://blog.almguru.com/managed-devops-pools-simplifying-self-hosted-azure-pipeline-agents-cd5f9c60640c) by Vladimir Gusarov +* [Simplify Azure DevOps agent management with Managed DevOps Pools](https://johnlokerse.dev/2024/10/14/simplify-azure-devops-agent-management-with-managed-devops-pools/) by John Lokerse +* [Simplifying Build Farms with Managed DevOps Pools for Azure DevOps](https://mattvsts.github.io/2024/09/11/managed-devops-pools/) by Matteo Emili + diff --git a/docs/managed-devops-pools/prerequisites.md b/docs/managed-devops-pools/prerequisites.md new file mode 100644 index 00000000000..279f6839b20 --- /dev/null +++ b/docs/managed-devops-pools/prerequisites.md @@ -0,0 +1,227 @@ +--- +title: Prerequisites for Managed DevOps Pools +description: Learn how to configure your Azure subscription and Azure DevOps organization for use with Managed DevOps Pools. +ms.date: 04/14/2025 +--- + +# Prerequisites for Managed DevOps Pools + +There are a few things you need to prepare before using Managed DevOps Pools for the first time. + +At a high level, you need: + +> [!div class="checklist"] +> - An Azure account with an active subscription, with the Managed DevOps Pools resource provider registered +> - An Azure DevOps organization, connected to the Microsoft Entra ID tenant of the users who will be administering the Managed DevOps Pool +> - Permissions in the Azure DevOps organization to create a Managed DevOps Pool + +This article shows you how to configure your Azure subscription and Azure DevOps organization for use with Managed DevOps Pools. These configuration steps only need to be performed a single time per Azure DevOps organization and Azure subscription. + +## Configure your Azure subscription + +1. [Register the Managed DevOps Pools resource provider in your Azure Subscription](#register-the-managed-devops-pools-resource-provider-in-your-azure-subscription) +1. [Review Managed DevOps Pools quotas](#review-managed-devops-pools-quotas) +1. [Create a dev center and dev center project](#create-a-dev-center-and-dev-center-project) (If you plan to create your Managed DevOps Pools using the Azure portal, you can create the dev center and dev center project during the pool creation process.) + +### Register the Managed DevOps Pools resource provider in your Azure Subscription + +To use Managed DevOps Pools, register the following resource providers with your Azure subscription. + +| Resource provider | Description | +|-------------------|-------------| +| **Microsoft.DevOpsInfrastructure** | Resource provider for Managed DevOps Pools | +| **Microsoft.DevCenter** | Resource provider for dev center and dev center project | + +Registering a resource provider uses the `/register/action` operation. Permission to perform this operation is included if your account is assigned the [contributor or owner role](/azure/role-based-access-control/built-in-roles) on your subscription. + + +#### [Azure portal](#tab/azure-portal/) + +### Azure portal + +1. Sign in to the [Azure portal](https://portal.azure.com/). +1. On the Azure portal menu, search for **Subscriptions**. Select it from the available options. +1. Select the Azure subscription you plan to use for Managed DevOps Pools. +1. On the left menu, under **Settings**, select **Resource providers**. +1. Search for **Microsoft.DevOpsInfrastructure**, select the check box from the list, and choose **Register**. + + :::image type="content" source="./media/prerequisites/register-resource-provider.png" alt-text="Screenshot of registering the Managed DevOps Pools Azure Resource provider."::: + +1. Search for **Microsoft.DevCenter**. If **Microsoft.DevCenter** isn't registered, select the check box from the list, and choose **Register**. + +1. To see the Azure regions that support Managed DevOps Pools in your subscription, first register the **Microsoft.DevOpsInfrastructure** provider, select it from the list, and choose **Locations**. + + :::image type="content" source="media/prerequisites/view-provider-regions-small.png" lightbox="media/prerequisites/view-provider-regions.png" alt-text="Screenshot of Azure regions that support Managed DevOps Pools."::: + +#### [Azure CLI](#tab/azure-cli/) + +### Azure CLI + +If you prefer using Azure CLI to register the Azure Resource Provider, run the following command using [Azure CLI](/cli/azure/). + +```bash +az provider register --namespace 'Microsoft.DevOpsInfrastructure' +az provider register --namespace 'Microsoft.DevCenter' +``` + +#### [PowerShell](#tab/powershell/) + +### PowerShell + +If you prefer using PowerShell to register the Azure Resource Provider, run the following command using the [Az.Resources module](/powershell/module/az.resources/register-azresourceprovider). + +```PowerShell +Register-AzResourceProvider -ProviderNamespace 'Microsoft.DevOpsInfrastructure' +Register-AzResourceProvider -ProviderNamespace 'Microsoft.DevCenter' +``` + +* * * + +For more information about Azure resource providers, see [Azure resource providers and types](/azure/azure-resource-manager/management/resource-providers-and-types). + +### Review Managed DevOps Pools quotas + +Managed DevOps Pools uses [Azure Quotas](/azure/quotas/quotas-overview) to manage the usage of the virtual machine resources that run your agents. Managed DevOps Pools quotas are based on CPU cores per Azure VM SKU family. By default, regions that support Managed DevOps Pools have five cores of quota granted for the following [SKU families](/azure/virtual-machines/sizes/overview). + +* `standardBSFamily` +* `standardDADSv5Family` +* `standardDASv5Family` +* `standardDDSv5Family` +* `standardDLDSv5Family` +* `standardDPLDSv5Family` +* `standardDPLSv5Family` +* `standardDPSv5Family` +* `standardDSv2Family` +* `standardDSv5Family` +* `standardDv2Family` +* `standardEASv4Family` +* `standardEDSv5Family` +* `standardESv5Family` +* `standardFSv2Family` +* `standardLSv3Family` + +The default agent size for new Managed DevOps Pools resources is **Standard D2ads v5**, which is part of the **standardDADSv5Family**. **Standard D2ads v5** uses two cores, so you can create a pool with up to two agents, for a total of four cores, without requesting additional quota. To create more, you must [request a quota adjustment](#request-a-quota-adjustment). + +#### View your quotas + +1. To view the quotas for SKU families in your region, sign in to the [Azure portal](https://portal.azure.com/), enter **quotas** in the search box, and choose **Quotas** from the list. + + :::image type="content" source="./media/quotas/quotas-search.png" alt-text="Screenshot of Azure portal search for quotas."::: + +1. Choose **Managed DevOps Pools**. + + :::image type="content" source="./media/quotas/quotas-overview.png" alt-text="Screenshot of quotas overview."::: + +1. Choose your subscription and the region where you want to create the pool. In the following example, the **Standard DADSv5 Family vCPUs** quota is **8 of 8**, which means eight cores are available, but all eight are being used. If you want to use more than eight cores for this SKU, or you want to use a different SKU that doesn't have any quota, you can request a quota adjustment. + + :::image type="content" source="./media/quotas/quotas-list.png" alt-text="Screenshot of quotas list."::: + +#### Request a quota adjustment + +1. To request an increase in quota, choose **Request adjustment** for the desired SKU in your region. + + :::image type="content" source="./media/quotas/request-adjustment-menu.png" alt-text="Screenshot of request adjustment menu item."::: + +2. Specify the desired number of cores for the selected SKU, and choose **Submit**. In the following example, 20 cores are requested for **Standard DSv2 Family vCPUs**. + + :::image type="content" source="./media/quotas/new-quota-request.png" alt-text="Screenshot of selecting an increased number of cores."::: + +3. The quota request takes a few moments to process. The following example shows the result of a successful quota adjustment. + + :::image type="content" source="./media/quotas/quota-request-granted.png" alt-text="Screenshot of granted quota request."::: + + If the quota adjustment can't be auto-approved, you'll be directed to submit a support request, as described in the following section. + +##### Create a quota support request + +If your subscription doesn't have the capacity to configure your pool with desired Azure VM SKU and maximum agents count, pool creation fails with an error similar to the following message: + +`Cores needed to complete this request is 8, which exceeds the current limit of 0 for SKU family standardDDSv4Family in region eastus. Please choose a different region if possible, or request additional quota at https://portal.azure.com/#view/Microsoft_Azure_Support/NewSupportRequestV3Blade/issueType/quota/subscriptionId/subscription_id_placeholder/topicId/3eadc5d3-b59a-3658-d8c6-9c729ba35b97`. + +1. Go to the link to start a **New support request** to request a quota increase. Choose **Next**. + + :::image type="content" source="./media/quotas/new-support-request.png" alt-text="Screenshot of new quota support request"::: + +1. Choose **Enter details**. + + :::image type="content" source="./media/quotas/support-request-enter-details-link.png" alt-text="Screenshot of new quota support request."::: + +1. Enter the **Region**, **Sku Family**, **New limit**, and choose **Save and continue**. In th following example, 100 cores are requested for **Standard DDSv4 Family vCPUs**. + + :::image type="content" source="./media/quotas/new-support-request-quota-details.png" alt-text="Screenshot of quota details."::: + +1. Fill the following details in this form: + + * **Severity**: Choose one of the available severity levels based on the business impact. + + * **Preferred contact method**: You can either choose to be contacted over **Email** or by **Phone**. + +1. Select **Next: Review+Create**. Validate the information provided and select **Create** to create a support request. + +Within 24 hours, the Managed DevOps Pools support team will evaluate your request and get back to you. + +### Create a dev center and dev center project + +Managed DevOps Pools requires a dev center and dev center project. You have the option to create a dev center and dev center project when you create your pool in the Azure portal, but if you want to create them ahead of time, perform the following steps. + +* [Create a dev center](#create-a-dev-center) +* [Create a dev center Project](#create-a-dev-center-project) + +Multiple Managed DevOps Pools can use the same dev center and dev center project, and the dev center project isn't required to be in the same region or the same subscription as your Managed DevOps Pool. + +#### Create a dev center + +1. Sign in to the [Azure portal](https://portal.azure.com/). +1. On the Azure portal menu, search for **Dev centers**, select it from the available options, and choose **Create**. + + ![Screenshot of the Dev centers create button.](./media/prerequisites/dev-center-create-button.png) + +1. Choose the desired **Subscription**, **Resource group**, **Name**, and **Location**, and choose **Review + Create**. + + ![Screenshot of Create a dev center.](./media/prerequisites/create-dev-center.png) + +1. On the confirmation window, choose **Create** to create the dev center. +1. Wait until the new dev center is created, and proceed to the next section and create a dev center Project. + +#### Create a dev center Project + +1. Go to the dev center created in the previous section, and choose **Create project**. + + ![Screenshot of Create dev center Project button](./media/prerequisites/create-dev-center-proect-button.png) + +1. Choose the desired **Subscription**, **Resource group**, **dev center**, **Name**, and choose **Review + Create**. + + ![Screenshot of Create a dev center project.](./media/prerequisites/create-dev-center-project.png) + +1. On the confirmation window, choose **Create** to create the dev center project. + +1. When you create your Managed DevOps Pool, specify the dev center and dev center project you created in these steps. + +## Configure your Azure DevOps organization + +1. [Connect your Azure DevOps organization to Microsoft Entra ID and verify membership](#connect-your-azure-devops-organization-to-microsoft-entra-id-and-verify-membership) +1. [Verify Azure DevOps permissions](#verify-azure-devops-permissions) + +### Connect your Azure DevOps organization to Microsoft Entra ID and verify membership + +To create a Managed DevOps Pool in your Azure DevOps organization, your Azure DevOps organization must be connected to Microsoft Entra ID, and your user account must be a member of the following Microsoft Entra ID [tenants](/entra/identity-platform/developer-glossary#tenant): + +* The tenant of the Azure subscription that contains your Managed DevOps Pool +* The tenant your Azure DevOps organization is connected to + +1. [View your current directory (Azure tenant) in the Azure portal](/azure/azure-portal/set-preferences#directories--subscriptions). +1. [View the tenant for your Azure DevOps organization](../organizations/accounts/connect-organization-to-azure-ad.md#connect-your-organization-to-microsoft-entra-id). You can go directly to this page in the Azure DevOps portal here: `https://dev.azure.com//_settings/organizationAad`. +1. If your Azure DevOps organization isn't connected to Microsoft Entra ID, follow the steps in [Connect your organization to Microsoft Entra ID](../organizations/accounts/connect-organization-to-azure-ad.md#connect-your-organization-to-microsoft-entra-id) and connect to the desired tenant, such as the same tenant as your Azure subscription. + +## Verify Azure DevOps permissions + +When you create a Managed DevOps Pool, the account you use to sign in to the Azure subscription that contains your Managed DevOps Pool is used to create a corresponding agent pool in your Azure DevOps organization. To successfully create a Managed DevOps Pool, your account must have one of the following permissions in your Azure DevOps organization. These permissions are listed in order from least privileged to most privileged. + +| Permission | Description | Granted by | +|------------|-------------|------------| +| **Organization-level Agent pools administrator** | Administrators of agent pools at the organization level can [create new agent pools as well as perform all operations on them](../organizations/security/about-security-roles.md#agent-pool-security-roles-organization-or-collection-level). | A [Project Collection Administrator](../organizations/security/look-up-project-collection-administrators.md) or another **Organization-level Agent pools administrator** can add users to this group and grant them the administrator role. For more information, see [Set organization security for all agent pools](../pipelines/policies/permissions.md#set-organization-security-for-all-agent-pools). | +| **Project Collection Administrator** | The Project Collection Administrators group is the main administrative security group defined for an organization and can perform all operations in an Azure DevOps organization, including creating new pools. | Other project collection administrators can add users to this group. For information about this group and how to see its members, see [Look up a project collection administrator](../organizations/security/look-up-project-collection-administrators.md). | + +## Next steps + +* [Create your first Managed DevOps Pool](./quickstart-azure-portal.md) diff --git a/docs/managed-devops-pools/pricing.md b/docs/managed-devops-pools/pricing.md new file mode 100644 index 00000000000..d13548b460e --- /dev/null +++ b/docs/managed-devops-pools/pricing.md @@ -0,0 +1,52 @@ +--- +title: Managed DevOps Pools pricing +description: Learn how pricing is calculated for your Managed DevOps Pools. +ms.date: 11/13/2024 +ms.topic: concept-article +#Customer intent: As a platform engineer, I want to understand how Managed DevOps Pools pricing is determined so that I can estimate my projected cost. +--- + +# Pricing + +Managed DevOps Pools pricing is determined by the cost of the Azure services your pool uses, like compute, storage, and data egress, combined with the standard Azure DevOps Services pricing for self-hosted agents. This article describes how to estimate and project the costs for your Managed DevOps Pools. + +## Azure DevOps Services parallel job pricing + +Azure DevOps refers to the capability to run pipeline jobs concurrently as **parallel jobs**. If you have five parallel jobs, you can run five pipelines at the same time. If more than five pipelines are queued, the first five start, and the remaining pipelines remain in the queue until one of the previous pipelines completes. + +Managed DevOps Pools agents are considered to be self-hosted agents by Azure DevOps Services. Azure DevOps Services provides self-hosted agents one free parallel job, and charges $15.00 per month for each additional parallel job. If you want the capacity to run five jobs in parallel, you must pay for four additional parallel jobs at $15.00 each, for an additional $60.00 per month. + +Managed DevOps Pools uses the [Maximum agents](./configure-pool-settings.md#maximum-agents) to configure the maximum number of agents that it makes available to run pipelines. If you set **Maximum agents** to **5**, ensure that you have five parallel jobs available in your organization for best performance. Parallel jobs are paid and configured at the Azure DevOps organization level and are shared with all pipelines running in any project in the organization. If you set **Maximum agents** to **5** but only have the default free parallel job, you can only run a single pipeline at a time. + +For more information, see [Configure and pay for parallel jobs](../pipelines/licensing/concurrent-jobs.md?tabs=self-hosted). + +## Azure services pricing + +The Azure services your pool uses, like compute, storage, and data egress, are billed at the standard Azure pricing rates. For more details, see: + +* [Azure pricing calculator](https://azure.microsoft.com/pricing/calculator/) +* [View and download your Azure usage and charges](/azure/cost-management-billing/understand/download-azure-daily-usage). + +For additional details about the Azure Services used by Managed DevOps Pools and strategies for reducing cost, see [Manage cost and performance](./manage-costs.md). + +## Estimating cost + +A basic formula for estimating the cost for Managed DevOps Pools is to determine how many hours of jobs are run per month multiplied by the cost per hour. + +To estimate the number of hours, multiply the number of projected jobs by the projected run time of the jobs. For example, if your typical job takes two hours to run, runs 100 times per day, five days per week, your estimated hours would be 1000 hours per week, or approximately 4000 hours per month. If your jobs transfer data that is subject to [standard data egress charges](https://azure.microsoft.com/pricing/details/bandwidth/), factor this pricing into your estimates. + +If you are using [standby agents](./configure-scaling.md#standby-agent-mode), factor in the hours that the agents are online for standby but not actively running jobs and add that to the estimated hours. To use standby agents, you configure a provisioning schedule to keep agents online to reduce the startup time to run jobs. If you provisioned five agents to be on standby during a 40 hour work week, you would be paying for 200 hours of machine time per week, even during times when no jobs were running. + +To find the cost per hour, [review the pricing](https://azure.microsoft.com/pricing/details/virtual-machines/linux/) for the [Azure VM size you're using](/azure/virtual-machines/sizes) for your pool. If you're using a data disk, see [Managed Disks pricing](https://azure.microsoft.com/pricing/details/managed-disks/). + +If your selected Azure VM size is 12 cents an hour, and you are projected to run 4000 hours of jobs, your projected monthly cost would be $480. + +To view your previous Azure resource usage, see [View and download your Azure usage and charges](/azure/cost-management-billing/understand/download-azure-daily-usage). + +## See also + +* [Manage cost and performance for Managed DevOps Pools](./manage-costs.md) +* [Azure bandwidth pricing](https://azure.microsoft.com/pricing/details/bandwidth/) +* [Azure pricing calculator](https://azure.microsoft.com/pricing/calculator/) +* [View and download your Azure usage and charges](/azure/cost-management-billing/understand/download-azure-daily-usage) + diff --git a/docs/managed-devops-pools/quickstart-arm-template.md b/docs/managed-devops-pools/quickstart-arm-template.md new file mode 100644 index 00000000000..f7a857dfb6e --- /dev/null +++ b/docs/managed-devops-pools/quickstart-arm-template.md @@ -0,0 +1,277 @@ +--- +title: Create a Managed DevOps Pool using an ARM template +description: Learn how to create a Managed DevOps Pool using an Azure Resource Manager template (ARM template). +ms.date: 11/13/2024 +ms.topic: quickstart +#Customer intent: As a developer, I want to learn how to create a Managed DevOps Pool using an ARM template and run a pipeline in the new pool. +--- + +# Quickstart: Create a Managed DevOps Pool using an ARM template + +This article shows you how to create a Managed DevOps Pool using an ARM template, and run a pipeline in the new pool. + +## Prerequisites + +Before completing the steps in this article, have configured your Azure subscription and Azure DevOps organization for use with Managed DevOps Pools, as described in the [Prerequisites](./prerequisites.md) article. These steps need to be completed only once per Azure subscription and Azure DevOps organization. + +## Sign in to the Azure CLI + +Open a command prompt (on Windows, use Windows Command Prompt or PowerShell) and run the following commands. + +1. Sign in the to Azure CLI. + + ```azurecli + az login + ``` +2. If you have more than one Azure subscription, set your default Azure subscription. + + ```azurecli + az account set --subscription "My subscription name" + ``` + + To get a list of your subscriptions, you can run the following command. + + ```azurecli + az account list -o table + ``` + + If you have multiple tenants, or want to see more information about working with Azure subscription using Azure CLI, see [How to manage Azure subscriptions with the Azure CLI](/cli/azure/manage-azure-subscriptions-azure-cli). + +## Create a resource group, Dev Center, and Dev Center Project + +1. Follow the [Create a dev center](/azure/deployment-environments/how-to-create-configure-dev-center#create-a-dev-center) steps in [Create and configure a dev center for Azure Deployment Environments by using the Azure CLI](/azure/deployment-environments/how-to-create-configure-dev-center). + + You only need to follow the steps in the [Create a dev center](/azure/deployment-environments/how-to-create-configure-dev-center#create-a-dev-center) section. Make a note of the resource group name and Dev Center name. + +1. Follow the [Create a project](/azure/deployment-environments/how-to-create-configure-projects#create-a-project) steps in [Create and configure a project by using the Azure CLI](/azure/deployment-environments/how-to-create-configure-projects). + + Make a note of the `id` of the created project (not the `devCenterId`). + +## Review and save the template + +1. Create a local file name **mdp-azure-deploy.json** with the following contents. This file is a parameterized ARM template that creates a `microsoft.devopsinfrastructure/pools` resource. + + ```json + { + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "poolName": { + "type": "string" + }, + "adoOrg": { + "type": "string" + }, + "devCenterResourceId": { + "type": "string" + }, + "imageName": { + "type": "string" + }, + "poolSize": { + "type": "int" + }, + "location": { + "type": "string", + "defaultValue": "eastus" + } + }, + "variables": {}, + "resources": [ + { + "name": "[parameters('poolName')]", + "type": "microsoft.devopsinfrastructure/pools", + "apiVersion": "2024-10-19", + "location": "[parameters('location')]", + "tags": {}, + "properties": { + "organizationProfile": { + "organizations": [ + { + "url": "[parameters('adoOrg')]", + "parallelism": 1 + } + ], + "permissionProfile": { + "kind": "CreatorOnly" + }, + "kind": "AzureDevOps" + }, + "devCenterProjectResourceId": "[parameters('devCenterResourceId')]", + "maximumConcurrency": "[parameters('poolSize')]", + "agentProfile": { + "kind": "Stateless" + }, + "fabricProfile": { + "sku": { + "name": "Standard_D2ads_v5" + }, + "images": [ + { + "wellKnownImageName": "[parameters('imageName')]", + "buffer": "*" + } + ], + "kind": "Vmss" + } + } + } + ] + } + ``` + +2. Create another local file named **mdp-azure-deploy-parameters.json** and save it in the same folder as the first file. Update the following properties to match the details of your environment. + + | Parameter | Value | + |----------|-------| + | `poolName` | Update `value` with the desired name of your pool. The name must consist of alphanumeric characters, `.`, `-`, or `_`, and be between 3 and 44 characters in length. The name must be globally unique in Azure. | + | `adoOrg` | Update `value` and replace `your-organization` with the name of your Azure DevOps organization. | + | `devCenterResourceId` | Update `value` with the `id` from the previous [Create a resource group, Dev Center, and Dev Center Project](#create-a-resource-group-dev-center-and-dev-center-project) step. | + | `imageName` | This example is configured to use an [Azure Pipelines image](./configure-images.md#azure-pipelines-images), and uses the Windows Server 2022 image. If you want to change it, choose from the [Azure Pipelines image predefined aliases](./configure-images.md#azure-pipelines-image-predefined-aliases). Managed DevOps Pools also supports Azure Compute Gallery images and selected marketplace images. For information on configuring a Managed DevOps Pools resource for these image types, see [Configure Managed DevOps Pools images](./configure-images.md). | + | `poolSize` | Update `value` with the maximum number of agents you want to be able to run concurrent jobs. In this example the `poolSize` is `1`.| + | `location` | The Azure region for the pool. In this example the region is `eastus`. | + + ```json + { + "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "poolName": { + "value": "my-first-managed-pool" + }, + "adoOrg": { + "value": "https://dev.azure.com/your-organization" + }, + "devCenterResourceId": { + "value": "/subscriptions/subscription_id_placeholder/resourceGroups/fabrikam-managed-devops-pools/providers/Microsoft.DevCenter/projects/fabrikam-dev-center-project" + }, + "imageName": { + "value": "windows-2022" + }, + "poolSize": { + "value": 1 + }, + "location": { + "value": "eastus" + } + } + } + ``` + +## Create the Managed DevOps Pool + +Open a command prompt (on Windows, use Windows Command Prompt or PowerShell) and run the following commands. You can skip the first two commands if your Azure CLI session from the first procedure is still active. + +1. Sign in the to Azure CLI. + + ```azurecli + az login + ``` +2. If you have more than one Azure subscription, set your default Azure subscription. + + ```azurecli + az account set --subscription "My subscription name" + ``` + + To get a list of your subscriptions, you can run the following command. + + ```azurecli + az account list -o table + ``` + + If you have multiple tenants, or want to see more information about working with Azure subscription using Azure CLI, see [How to manage Azure subscriptions with the Azure CLI](/cli/azure/manage-azure-subscriptions-azure-cli). + +3. Go to the folder when you saved the two JSON files from the previous step. In this example, the files are saved to `C:\examples`. + + ```azurecli + cd c:\examples + ``` + +4. Create the Managed DevOps Pool. Replace `` with the resource group created in the first step. + + ```azurecli + az deployment group create --resource-group --template-file mdp-azure-deploy.json --parameters mdp-azure-deploy-parameters.json + ``` + + If your subscription doesn't have the capacity to configure your pool with desired Azure VM SKU and maximum agents count, pool creation fails with an error similar to the following message. `Cores needed to complete this request is 8, which exceeds the current limit of 0 for SKU family standardDDSv4Family in region eastus. Please choose a different region if possible, or request additional quota at https://portal.azure.com/#view/Microsoft_Azure_Support/NewSupportRequestV3Blade/issueType/quota/subscriptionId/subscription_id_placeholder/topicId/3eadc5d3-b59a-3658-d8c6-9c729ba35b97`. To resolve the issue, see [Review Managed DevOps Pools quotas](./prerequisites.md#review-managed-devops-pools-quotas). + +## View your created pool in the Azure portal + +1. Sign in to the [Azure portal](https://portal.azure.com/). +1. Search for **Managed DevOps Pools** and select it from the available options. +1. Choose your new Managed DevOps Pool from the list. +1. Choose **JSON View** to see the JSON format of your Managed DevOps Pools resource. + + :::image type="content" source="./media/pool-settings/json-view-button.png" alt-text="Screenshot of JSON View button in pool overview."::: + +## View the agent pool in Azure DevOps + +1. Go to the Azure DevOps portal and sign in to your Azure DevOps organization (`https://dev.azure.com/{your-organization}`). + +1. Go to **Azure DevOps** > **Organization settings**. + + :::image type="content" source="./media/prerequisites/organization-settings.png" alt-text="Screenshot of Organization settings button."::: + +1. Go to **Pipelines** > **Agent pools**, and verify that your new pool is listed. If you just created the Managed DevOps Pool, it can take a few moments for the new pool to appear in the agents list. + + ![Screenshot of Agent pools list.](./media/get-started/agent-pools-list.png) + +## Run a pipeline in your new pool + +In this step, we'll create a simple pipeline in the default repository of an Azure DevOps project and run it in your new Managed DevOps Pool. + +1. Go to the Azure DevOps portal and sign in to your Azure DevOps organization (`https://dev.azure.com/{your-organization}`). +1. Go to the project where you want to run the pipeline, and choose Pipelines. + + ![Screenshot of Projects list.](./media/get-started/project-pipelines.png) + +1. Choose **New pipeline** (or **Create Pipeline** if this is your first pipeline). + + ![Screenshot of new pipeline button.](./media/get-started/new-pipeline-button.png) + +1. Choose **Azure Repos Git**. + + ![Screenshot of repository types.](./media/get-started/choose-repo-type.png) + +1. Choose the repository that has the same name as your project. In this example, the project is named FabrikamFiber, so we choose the repository with the same name. + + ![Screenshot of FabrikamFiber repository.](./media/get-started/choose-repository.png) + +1. Choose Starter pipeline. + + ![Screenshot of pipeline template list.](./media/get-started/choose-starter-pipeline.png) + +1. By default the starter template uses a Microsoft hosted Linux agent. Edit the pipeline template and change the `pool` section so that it refers to the pool you created in the previous steps. + + ``` + # Change these two lines as shown in the following example. + pool: + vmImage: ubuntu-latest + ``` + + In this example, the Managed DevOps Pools is named `fabrikam-managed-pool`, so replace `vmImage: ubuntu-latest` with `name: fabrikam-managed-pools`, and specify the name of your Managed DevOps Pool. + + ``` + # Replace fabrikam-managed-pools with the name + # of your Managed DevOps Pool. + pool: + name: fabrikam-managed-pool + ``` + +1. Choose **Save and run**, and choose **Save and run** a second time to confirm. + + ![Screenshot of save and run button.](./media/get-started/save-and-run.png) + +1. If this is the first pipeline run in this pool, you may be asked to grant permissions before the pipeline runs. + +1. Watch the [pipeline run](../pipelines/create-first-pipeline.md#view-pipeline-run-details) in Azure DevOps, and you can switch over to the Azure portal and see the running agent in the [Agents](./view-agents.md) view. + +## Clean up resources + +When you have completed the quickstart, delete the created resources if you don't want to continue to use them. + +To delete the Managed DevOps Pool, Dev Center, and Dev Center Project, you can delete them by [deleting the resource group](/azure/azure-resource-manager/management/delete-resource-group#delete-resource-group) that contains them. + +## See also + +* [Managed DevOps Pools ARM template reference](/azure/templates/microsoft.devopsinfrastructure/pools?pivots=deployment-language-arm-template) diff --git a/docs/managed-devops-pools/quickstart-azure-cli.md b/docs/managed-devops-pools/quickstart-azure-cli.md new file mode 100644 index 00000000000..1befd6e2237 --- /dev/null +++ b/docs/managed-devops-pools/quickstart-azure-cli.md @@ -0,0 +1,337 @@ +--- +title: Create a Managed DevOps Pool using Azure CLI +description: Learn how to create a Managed DevOps Pool using Azure CLI. +ms.date: 12/04/2024 +ms.topic: quickstart +#Customer intent: As a developer, I want to learn how to create a Managed DevOps Pool using Azure CLI and run a pipeline in the new pool. +--- + +# Quickstart: Create a Managed DevOps Pool using Azure CLI + +This article shows you how to create a Managed DevOps Pool using Azure CLI, and run a pipeline in it. + +## Prerequisites + +Before completing the steps in this article, have configured your Azure subscription and Azure DevOps organization for use with Managed DevOps Pools, as described in the [Prerequisites](./prerequisites.md) article. These steps need to be completed only once per Azure subscription and Azure DevOps organization. + +## Install or run in Azure Cloud Shell + +The easiest way to learn how to use the Azure CLI is by running a Bash environment in [Azure Cloud Shell](https://portal.azure.com/#cloudshell/) through your browser. To learn about Cloud Shell, see [Quickstart for Bash in Azure Cloud Shell](/azure/cloud-shell/quickstart). + +When you're ready to install the Azure CLI, see the [installation instructions](/cli/azure/install-azure-cli) +for Windows, Linux, macOS, and Docker container. + +Check your version by running `az --version`. Azure Cloud Shell always has the latest version of the Azure CLI preinstalled. + +```azurecli-interactive +az version +``` + +## Sign in to the Azure CLI + +Open a command prompt (on Windows, use Windows Command Prompt or PowerShell) and run the following commands. If you're using [Azure Cloud Shell](https://portal.azure.com/#cloudshell/) you don't need to run `az login` unless you want to use a different account. + +1. Sign in the to Azure CLI. + + ```azurecli + az login + ``` + +2. If you have more than one Azure subscription, set your default Azure subscription. + + ```azurecli + az account set --subscription "My subscription name" + ``` + + To get a list of your subscriptions, you can run the following command. + + ```azurecli + az account list -o table + ``` + + If you have multiple tenants, or want to see more information about working with Azure subscription using Azure CLI, see [How to manage Azure subscriptions with the Azure CLI](/cli/azure/manage-azure-subscriptions-azure-cli). + + +## Define environment variables + +1. Run the following commands to generate the names for the resources in this quickstart. This example uses the `EastUS2` region. Replace `EastUS2` with your desired region. + + ```bash + export RANDOM_ID="$(openssl rand -hex 3)" + export RESOURCE_GROUP_NAME="myManagedDevOpsPoolGroup$RANDOM_ID" + export REGION=EastUS2 + export POOL_NAME="mdpPool$RANDOM_ID" + export DEV_CENTER_NAME="mdpDevCenter$RANDOM_ID" + export DEV_CENTER_PROJECT_NAME="mdpDevCenterProject$RANDOM_ID" + ``` + +2. Run the following commands to review your resource names. + + ```bash + echo $RESOURCE_GROUP_NAME + echo $POOL_NAME + echo $DEV_CENTER_NAME + echo $DEV_CENTER_PROJECT_NAME + echo $REGION + ``` + +## Create a resource group + +1. Run the following command to create the resource group to contain the resources used in this quickstart. + + ```azurecli + az group create --name $RESOURCE_GROUP_NAME --location $REGION + ``` + +## Create a dev center and dev center project + +1. Install the Azure CLI `devcenter` extension, and ensure it is upgraded to the latest version if it is already installed. + + ```azurecli + az extension add --name devcenter --upgrade + ``` + +1. Run the following commands to create a dev center and dev center project. + + ```azurecli + # Create a dev center + az devcenter admin devcenter create -n $DEV_CENTER_NAME \ + -g $RESOURCE_GROUP_NAME \ + -l $REGION + + # Save the id of the newly created dev center + DEVCID=$( \ + az devcenter admin devcenter show -n $DEV_CENTER_NAME \ + -g $RESOURCE_GROUP_NAME \ + --query id -o tsv) + + # Create a dev center project + az devcenter admin project create -n $DEV_CENTER_PROJECT_NAME \ + --description "My dev center project." \ + -g $RESOURCE_GROUP_NAME \ + -l $REGION \ + --dev-center-id $DEVCID + + # Save the dev center project for use when creating + # the Managed DevOps Pool + DEVCPID=$( \ + az devcenter admin project show -n $DEV_CENTER_PROJECT_NAME \ + -g $RESOURCE_GROUP_NAME \ + --query id -o tsv) + ``` + + After a few moments, the output indicates that the Dev center was created. The `id` of the created dev center is saved in `DEVCID` and is used to create the dev center project. + + ```json + { + "devCenterUri": "https://...", + "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/resourceGroupName/providers/Microsoft.DevCenter/devcenters/devCenterName", + "location": "eastus", + "name": "devCenterName", + "provisioningState": "Succeeded", + "resourceGroup": "resourceGroupName", + "systemData": { ... }, + "type": "microsoft.devcenter/devcenters" + } + ``` + + After a few more moments, the output indicates that the dev center project was created. The `id` of the created dev center project is saved in `DEVCPID` and is used when creating the Managed DevOps Pool in the next section. + + ```json + { + "description": "My dev center project.", + "devCenterId": "...", + "devCenterUri": "https://...", + "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/resourceGroupName/providers/Microsoft.DevCenter/projects/devCenterProjectName", + "location": "eastus", + "name": "devCenterProjectName", + "provisioningState": "Succeeded", + "resourceGroup": "resourceGroupName", + "systemData": { ... }, + "type": "microsoft.devcenter/projects" + } + ``` + +## Prepare the Managed DevOps Pool configuration files + +The `mdp pool create` method has several parameters that take JSON values that configure different aspects of the pool. + +* `agent-profile` specifies whether the pool is stateful or stateless, and contains the standby agent schedule. It is a dictionary with a single key named either `Stateful` or `Stateless`, depending on your desired agent configuration. For more information on `agent-profile` properties, see [Configure scaling](./configure-scaling.md?tabs=azure-cli). +* `fabric-profile` specifies the agent size, VM images, OS disk, and attached storage. For more information on the `fabric-profile` properties, see [Configure pool settings](./configure-pool-settings.md?tabs=azure-cli) and [Configure additional storage](./configure-storage.md?tabs=azure-cli). +* `organization-profile` specifies the Azure DevOps organizations and projects that can use the pool. For more information on `organization-profile` settings, see [Configure security settings - Configure organization access](./configure-security.md?tabs=azure-cli#configure-organization-access). + +Create the following three files and save them to the folder where you plan to run the Azure CLI commands to create the pool. + +1. Create a file name **agent-profile.json** with the following contents. + + ```json + { + "Stateless": {} + } + ``` + + This configuration specifies a [stateless agent](./configure-scaling.md?tabs=azure-cli#stateless-pools) for your pool. + + +2. Create a file named **fabric-profile.json** with the following contents. + + ```json + { + "vmss": { + "sku": { + "name": "Standard_D2as_v5" + }, + "images": [ + { + "aliases": [ + "ubuntu-22.04" + ], + "buffer": "*", + "wellKnownImageName": "ubuntu-22.04/latest" + } + ], + "osProfile": { + "secretsManagementSettings": { + "observedCertificates": [], + "keyExportable": false + }, + "logonType": "Service" + }, + "storageProfile": { + "osDiskStorageAccountType": "Standard", + "dataDisks": [] + } + } + } + ``` + + This configuration specifies a pool using the **Standard_D2as_v5** image, the **ubuntu-22.04** [Azure Pipelines image](./configure-images.md?tabs=azure-cli#azure-pipelines-images), and a **Standard** [OS Disk type](./configure-pool-settings.md?tabs=azure-cli#os-disk-type) with no [attached data disk](./configure-storage.md?tabs=azure-cli). + +1. Create a file named **organization-profile.json** with the following contents. Replace `` with the name for your Azure DevOps organization. + + ```json + { + "AzureDevOps": { + "organizations": [ + { + "url": "https://dev.azure.com/", + "projects": [], + "parallelism": 1 + } + ], + "permissionProfile": { + "kind": "CreatorOnly" + } + } + } + ``` + + This configuration specifies a pool that is available to [all projects in your Azure DevOps organization](./configure-security.md?tabs=azure-cli#configure-organization-access). + + +## Create the Managed DevOps Pool + +1. Install the `mdp` extension, and ensure it is upgraded to the latest version if it is already installed. + + ```azurecli + az extension add --name mdp --upgrade + ``` + +1. Create the Managed DevOps Pool by running the following [az mdp pool create](/cli/azure/mdp/pool#az-mdp-pool-create) command. + + ```azurecli + az mdp pool create -n $POOL_NAME \ + -g $RESOURCE_GROUP_NAME \ + -l $REGION \ + --devcenter-project-id $DEVCPID \ + --maximum-concurrency 1 \ + --agent-profile agent-profile.json \ + --fabric-profile fabric-profile.json \ + --organization-profile organization-profile.json + ``` + + If your subscription doesn't have the capacity to configure your pool with desired Azure VM SKU and maximum agents count, pool creation fails with an error similar to the following message. `Cores needed to complete this request is 2, which exceeds the current limit of 0 for SKU family standardDDSv4Family in region eastus. Please choose a different region if possible, or request additional quota at https://portal.azure.com/#view/Microsoft_Azure_Support/NewSupportRequestV3Blade/issueType/quota/subscriptionId/subscription_id_placeholder/topicId/3eadc5d3-b59a-3658-d8c6-9c729ba35b97`. To resolve the issue, see [Review Managed DevOps Pools quotas](./prerequisites.md#review-managed-devops-pools-quotas). + +## View your created pool in the Azure portal + +1. Sign in to the [Azure portal](https://portal.azure.com/). +1. Search for **Managed DevOps Pools** and select it from the available options. +1. Choose your new Managed DevOps Pool from the list. +1. Choose **JSON View** to see the JSON format of your Managed DevOps Pools resource. + + :::image type="content" source="./media/pool-settings/json-view-button.png" alt-text="Screenshot of JSON View button in pool overview."::: + +## View the agent pool in Azure DevOps + +1. Go to the Azure DevOps portal and sign in to your Azure DevOps organization (`https://dev.azure.com/{your-organization}`). + +1. Go to **Azure DevOps** > **Organization settings**. + + :::image type="content" source="./media/prerequisites/organization-settings.png" alt-text="Screenshot of Organization settings button."::: + +1. Go to **Pipelines** > **Agent pools**, and verify that your new pool is listed. If you just created the Managed DevOps Pool, it can take a few moments for the new pool to appear in the agents list. + + ![Screenshot of Agent pools list.](./media/get-started/agent-pools-list.png) + +## Run a pipeline in your new pool + +In this step, we'll create a simple pipeline in the default repository of an Azure DevOps project and run it in your new Managed DevOps Pool. + +1. Go to the Azure DevOps portal and sign in to your Azure DevOps organization (`https://dev.azure.com/{your-organization}`). +1. Go to the project where you want to run the pipeline, and choose Pipelines. + + ![Screenshot of Projects list.](./media/get-started/project-pipelines.png) + +1. Choose **New pipeline** (or **Create Pipeline** if this is your first pipeline). + + ![Screenshot of new pipeline button.](./media/get-started/new-pipeline-button.png) + +1. Choose **Azure Repos Git**. + + ![Screenshot of repository types.](./media/get-started/choose-repo-type.png) + +1. Choose the repository that has the same name as your project. In this example, the project is named FabrikamFiber, so we choose the repository with the same name. + + ![Screenshot of FabrikamFiber repository.](./media/get-started/choose-repository.png) + +1. Choose Starter pipeline. + + ![Screenshot of pipeline template list.](./media/get-started/choose-starter-pipeline.png) + +1. By default the starter template uses a Microsoft hosted Linux agent. Edit the pipeline template and change the `pool` section so that it refers to the pool you created in the previous steps. + + ``` + # Change these two lines as shown in the following example. + pool: + vmImage: ubuntu-latest + ``` + + In this example, the Managed DevOps Pools is named `fabrikam-managed-pool`, so replace `vmImage: ubuntu-latest` with `name: fabrikam-managed-pools`, and specify the name of your Managed DevOps Pool. + + ``` + # Replace fabrikam-managed-pools with the name + # of your Managed DevOps Pool. + pool: + name: fabrikam-managed-pool + ``` + +1. Choose **Save and run**, and choose **Save and run** a second time to confirm. + + ![Screenshot of save and run button.](./media/get-started/save-and-run.png) + +1. If this is the first pipeline run in this pool, you may be asked to grant permissions before the pipeline runs. + +1. Watch the [pipeline run](../pipelines/create-first-pipeline.md#view-pipeline-run-details) in Azure DevOps, and you can switch over to the Azure portal and see the running agent in the [Agents](./view-agents.md) view. + +## Clean up resources + +If you're not going to continue to use this application, delete the resource group, dev center, dev center project, and the Managed DevOps Pool. This quickstart created all of the resources in a new resource group, so you can delete them all by using the [az group delete](/cli/azure/group#az-group-delete) command to delete the resource group and all of its resources. + + +```azurecli +az group delete -n $RESOURCE_GROUP_NAME +``` + +## See also + +* [Managed DevOps Pools Azure CLI reference](/cli/azure/service-page/managed%20devops%20pools) diff --git a/docs/managed-devops-pools/quickstart-azure-portal.md b/docs/managed-devops-pools/quickstart-azure-portal.md new file mode 100644 index 00000000000..ba8cb1ed6d7 --- /dev/null +++ b/docs/managed-devops-pools/quickstart-azure-portal.md @@ -0,0 +1,122 @@ +--- +title: Create a Managed DevOps Pool using the Azure portal +description: Learn how to create a Managed DevOps Pool using the Azure portal. +ms.date: 11/13/2024 +ms.topic: quickstart +#Customer intent: As a developer, I want to learn how to create a Managed DevOps Pool using the Azure portal and run a pipeline in the new pool. +--- + +# Quickstart: Create a Managed DevOps Pool using the Azure portal + +This article shows you how to create a Managed DevOps pool, and run a pipeline in the new pool. + +## Prerequisites + +Before completing the steps in this article, you must configure your Azure subscription and Azure DevOps organization for use with Managed DevOps Pools, as described in the [Prerequisites](./prerequisites.md) article. These steps need to be completed only once per Azure subscription and Azure DevOps organization. + +## Create the Managed DevOps Pools resource + +1. Sign in to the [Azure portal](https://portal.azure.com/). +1. Search for **Managed DevOps Pools** and select it from the available options. +1. Choose **Create**, or **Create Managed DevOps Pools** if this is your first pool. + + :::image type="content" source="./media/get-started/create-managed-devops-pools-button.png" alt-text="Screenshot of Create Managed DevOps Pools button."::: + +1. Specify the **Subscription**, **Resource group**, **Dev Center**, and **Dev Center project**. If you haven't yet created a resource group, Dev Center, or Dev Center project, you can create them in this step. + :::image type="content" source="./media/get-started/create-managed-devops-pools-initial-settings.png" alt-text="Screenshot of Create Managed DevOps Pools initial configuration settings."::: + +1. Specify the **Azure DevOps organization** you want to use with your pool, the name of the pool, and the region for your pool. + + :::image type="content" source="./media/get-started/azure-devops-organization-and-pool.png" alt-text="Screenshot of Azure DevOps organization field."::: + + By default pools are configured for all projects in a single organization. You can configure additional organizations or limit the projects on the [Security](./configure-security.md) tab. Choose a region that is close to the other Azure resources you're using for [best cost and performance](./manage-costs.md#pool-region-co-location). + +1. Specify the maximum number of agents you wish to be available ([Maximum agents](./configure-pool-settings.md#maximum-agents)), the virtual machine size of the agents ([Agent size](./configure-pool-settings.md#agent-size)), and the [OS disk type](./configure-pool-settings.md#os-disk-type) for the agents. [D2adsV5](/azure/virtual-machines/dasv5-dadsv5-series#dadsv5-series) is the default **Agent size**; choose **Change size** to pick a different size if desired. + + :::image type="content" source="./media/get-started/agent-size-count-os-disk-type.png" alt-text="Screenshot of agent size, count, and OS disk type."::: + + Agent sizes (SKUs) with available Managed DevOps Pools quotas are marked as **Available**. You can request more quota for **Not Available** SKUs. Once a quota request for a **Not Available** SKU is approved, it will then be listed as **Available**. [Learn more about Managed DevOps Pools quotas](./prerequisites.md#view-your-quotas). + +1. Configure the images for your pool. By default pools are created with a [single image](./configure-images.md). To change the image or [configure multiple images](./configure-images.md#use-multiple-images-per-pool-with-aliases), choose **Add from Image Library** and select the image or images you want to use for your pool. + + :::image type="content" source="./media/configure-images/configure-pool-image.png" alt-text="Screenshot if Images section."::: + +1. Configure any desired additional settings for your pool by choosing the corresponding tab. View each tab to see the default settings for Managed DevOps Pools, and see the following links for more information about the settings available on each tab. To use the default settings for the following sections, continue to **Review + create**. + + :::image type="content" source="./media/get-started/create-managed-devops-pools-tabs.png" alt-text="Screenshot of tabs of settings."::: + + * [Scaling](./configure-scaling.md) - Configure scaling settings to manage the performance and cost of your Managed DevOps Pool. The default setting is stateless agents with no standby agents. + * [Networking](./configure-networking.md) - Add agents from your Managed DevOps Pool to your virtual network. The default setting is an isolated virtual network for your agents. + * [Storage](./configure-storage.md) - Attach an empty data disk to your agents. The default is no attached data disk. + * [Security](./configure-security.md) - Configure organization and project access, specify pool permissions, and configure interactive mode for testing. The default is a pool configured for all projects in the organization specified in **Azure DevOps organization**. + * [Tags](/azure/azure-resource-manager/management/tag-resources) - Use tags to organize your Azure resources and management hierarchy. + +1. Choose **Review + create**, and choose **Create** to confirm. + + :::image type="content" source="./media/get-started/create-managed-devops-pools-settings.png" alt-text="Screenshot of Review + create for Managed DevOps Pools initial configuration settings."::: + + The provisioning process can take a few moments. When the agent pool creation is complete, you can view the pool in Azure DevOps and run pipelines in that pool. + + If your subscription doesn't have the capacity to configure your pool with the desired Azure VM SKU and maximum agents count, pool creation fails with an error similar to the following message. `Cores needed to complete this request is 8, which exceeds the current limit of 0 for SKU family standardDDSv4Family in region eastus. Please choose a different region if possible, or request additional quota at https://portal.azure.com/#view/Microsoft_Azure_Support/NewSupportRequestV3Blade/issueType/quota/subscriptionId/subscription_id_placeholder/topicId/3eadc5d3-b59a-3658-d8c6-9c729ba35b97`. To resolve the issue, see [Review Managed DevOps quotas](./prerequisites.md#review-managed-devops-pools-quotas). + +## View the agent pool in Azure DevOps + +1. Go to the Azure DevOps portal and sign in to your Azure DevOps organization (`https://dev.azure.com/{your-organization}`). + +1. Go to **Azure DevOps** > **Organization settings**. + + :::image type="content" source="./media/prerequisites/organization-settings.png" alt-text="Screenshot of Organization settings button."::: + +1. Go to **Pipelines** > **Agent pools**, and verify that your new pool is listed. If you just created the Managed DevOps Pool, it can take a few moments for the new pool to appear in the agents list. + + ![Screenshot of Agent pools list.](./media/get-started/agent-pools-list.png) + +## Run a pipeline in your new pool + +In this step, we'll create a simple pipeline in the default repository of an Azure DevOps project and run it in your new Managed DevOps Pool. + +1. Go to the Azure DevOps portal and sign in to your Azure DevOps organization (`https://dev.azure.com/{your-organization}`). +1. Go to the project where you want to run the pipeline, and choose Pipelines. + + ![Screenshot of Projects list.](./media/get-started/project-pipelines.png) + +1. Choose **New pipeline** (or **Create Pipeline** if this is your first pipeline). + + ![Screenshot of new pipeline button.](./media/get-started/new-pipeline-button.png) + +1. Choose **Azure Repos Git**. + + ![Screenshot of repository types.](./media/get-started/choose-repo-type.png) + +1. Choose the repository that has the same name as your project. In this example, the project is named FabrikamFiber, so we choose the repository with the same name. + + ![Screenshot of FabrikamFiber repository.](./media/get-started/choose-repository.png) + +1. Choose Starter pipeline. + + ![Screenshot of pipeline template list.](./media/get-started/choose-starter-pipeline.png) + +1. By default the starter template uses a Microsoft hosted Linux agent. Edit the pipeline template and change the `pool` section so that it refers to the pool you created in the previous steps. + + ``` + # Change these two lines as shown in the following example. + pool: + vmImage: ubuntu-latest + ``` + + In this example, the Managed DevOps Pools is named `fabrikam-managed-pool`, so replace `vmImage: ubuntu-latest` with `name: fabrikam-managed-pools`, and specify the name of your Managed DevOps Pool. + + ``` + # Replace fabrikam-managed-pools with the name + # of your Managed DevOps Pool. + pool: + name: fabrikam-managed-pool + ``` + +1. Choose **Save and run**, and choose **Save and run** a second time to confirm. + + ![Screenshot of save and run button.](./media/get-started/save-and-run.png) + +1. If this is the first pipeline run in this pool, you may be asked to grant permissions before the pipeline runs. + +1. Watch the [pipeline run](../pipelines/create-first-pipeline.md#view-pipeline-run-details) in Azure DevOps, and you can switch over to the Azure portal and see the running agent in the [Agents](./view-agents.md) view. diff --git a/docs/managed-devops-pools/reliability-managed-devops-pools.md b/docs/managed-devops-pools/reliability-managed-devops-pools.md new file mode 100644 index 00000000000..c86fe60c39a --- /dev/null +++ b/docs/managed-devops-pools/reliability-managed-devops-pools.md @@ -0,0 +1,38 @@ +--- +title: Reliability in Managed DevOps Pools +description: Learn about reliability and disaster recovery options with Managed DevOps Pools. +ms.date: 11/05/2024 +ms.topic: reliability-article +#Customer intent: As a developer, I want to understand reliability support for Managed DevOps Pools so that I can respond to and/or avoid failures in order to minimize downtime and data loss. +--- + +# Reliability in Managed DevOps Pools + +This article describes reliability support in Managed DevOps Pools, and covers [cross-region disaster recovery](#cross-region-disaster-recovery). + +## Availability zones + +Managed DevOps Pools does not support availability zones at this time. + +## Cross-region disaster recovery + +Disaster recovery (DR) is about recovering from high-impact events such as natural disasters that result in downtime and data loss. Regardless of the cause, the best remedy for a disaster is a well-defined and tested DR plan and an application design that actively supports DR. Before you begin to think about creating your disaster recovery plan, see [Recommendations for designing a disaster recovery strategy](/azure/well-architected/reliability/disaster-recovery). + +When it comes to DR, Microsoft uses the [shared responsibility model](/azure/reliability/business-continuity-management-program#shared-responsibility-model). In a shared responsibility model, Microsoft ensures that the baseline infrastructure and platform services are available. At the same time, many Azure services don't automatically replicate data or fall back from a failed region to cross-replicate to another enabled region. For those services, you are responsible for setting up a disaster recovery plan that works for your workload. + +Managed DevOps Pools instances don't automatically replicate or switch from a failed region to another enabled region. In the event of a complete outage of the Azure region that hosts your Managed DevOps Pool, you would need to create a new Managed DevOps Pool in a different region, and manually update your pipelines to reference the new pool. + +### Plan for disaster recovery + +Document the configuration of your Managed DevOps Pools so that you can recreate them in the even of an outage. This includes the following resources that Managed DevOps Pools depends on: + +- The resource group for the replacement pool +- The dev center and dev center project for the replacement pool +- The Azure Compute Gallery images (if your pool uses them) + +You can save the configuration of your existing pool and create [ARM templates](./quickstart-arm-template.md) or Azure CLI scripts to recreate your pool using the same settings (except for name and location), and manually update your pipelines to use the new pool. When normal operations resume in the Azure region of your original pool, you can update your pipelines to use the original pool, and delete the new pool and associated resources. + +## Related content + +- [Azure reliability documentation](/azure/reliability/overview) +- [Azure DevOps data protection overview](/azure/devops/organizations/security/data-protection) diff --git a/docs/managed-devops-pools/toc.yml b/docs/managed-devops-pools/toc.yml new file mode 100644 index 00000000000..606650335d0 --- /dev/null +++ b/docs/managed-devops-pools/toc.yml @@ -0,0 +1,82 @@ +- name: Managed DevOps Pools + href: index.yml +- name: Overview + href: overview.md +- name: Roadmap and features timeline + href: features-timeline.md +- name: Architecture overview + href: architecture-overview.md +- name: Prerequisites + href: prerequisites.md +- name: Compare with Azure Virtual Machine Scale Set agents + href: migrate-from-scale-set-agents.md +- name: Quickstarts + items: + - name: Azure portal + href: quickstart-azure-portal.md + - name: ARM template + href: quickstart-arm-template.md + - name: Azure CLI + href: quickstart-azure-cli.md +- name: Configure + items: + - name: Configure pool settings + href: configure-pool-settings.md + - name: Configure scaling + href: configure-scaling.md + - name: Configure networking + href: configure-networking.md + - name: Configure additional storage + href: configure-storage.md + - name: Configure images + href: configure-images.md + - name: Configure security settings + href: configure-security.md + - name: Configure identity + href: configure-identity.md + - name: View agent status + href: view-agents.md + - name: Demands + href: demands.md + - name: Reliability + href: reliability-managed-devops-pools.md +- name: Monitor and troubleshoot + items: + - name: Monitor + href: monitor-pool.md + - name: Diagnostic logs + href: diagnostics.md + - name: Troubleshooting + href: troubleshooting.md +- name: Manage cost and performance + items: + - name: Pricing + href: pricing.md + - name: Manage cost and performance + href: manage-costs.md +- name: FAQs + items: + - name: Frequently asked questions + href: faq.md +- name: Reference + items: + - name: .NET + href: /dotnet/api/overview/azure/devops-infrastructure + - name: ARM template + href: /azure/templates/microsoft.devopsinfrastructure/pools?pivots=deployment-language-arm-template + - name: Azure CLI + href: /cli/azure/service-page/managed%20devops%20pools + - name: Azure PowerShell + href: /powershell/module/az.mdp + - name: Bicep + href: /azure/templates/microsoft.devopsinfrastructure/pools?pivots=deployment-language-bicep + - name: Java + href: /java/api/overview/azure/devops-infrastructure + - name: JavaScript + href: /javascript/api/overview/azure/devops-infrastructure + - name: Python + href: /python/api/overview/azure/devops-infrastructure + - name: REST + href: /rest/api/devopspools + - name: Terraform + href: /azure/templates/microsoft.devopsinfrastructure/pools?pivots=deployment-language-terraform diff --git a/docs/managed-devops-pools/troubleshooting.md b/docs/managed-devops-pools/troubleshooting.md new file mode 100644 index 00000000000..e9a7909dd62 --- /dev/null +++ b/docs/managed-devops-pools/troubleshooting.md @@ -0,0 +1,100 @@ +--- +title: Troubleshoot Managed DevOps Pools issues +description: Learn how to troubleshoot common issues with Managed DevOps Pools. +ms.topic: how-to +ms.date: 02/13/2025 +--- + +# Troubleshoot Managed DevOps Pools issues + +This article provides solutions to common Managed DevOps Pools issues. + +## Pool creation errors + +| Error code | Description | +|-------|------------------| +| `PoolProvisioningFailed` | [Pool creation failure due to Azure DevOps organization permissions](#pool-creation-failure-due-to-azure-devops-organization-permissions) | +| `UnauthorizedAccessToVirtualNetwork` | [Pool creation failure due to VNet permissions](#pool-creation-failure-due-to-vnet-permissions) | + +### Pool creation failure due to Azure DevOps organization permissions + +Pool creation fails with an error similar to one the following error messages. + +#### The logged in user was not found in the Azure DevOps organization + +* `Validation failure "PoolProvisioningFailed": "Failed to provision agent pool. Exception: The logged in user, , was not found in the Azure DevOps organization provided, ."` + +To resolve the issue: +* Your Azure DevOps organization must be connected to Microsoft Entra ID and your logged in Azure user must be a member (and not a guest) of this tenant. See [Managed DevOps Pools prerequisites - Connect your Azure DevOps organization to Microsoft Entra ID and verify membership](./prerequisites.md#connect-your-azure-devops-organization-to-microsoft-entra-id-and-verify-membership). + +#### The logged in user does not have Manage permissions in the Azure DevOps organization + +* `Validation failure "PoolProvisioningFailed": "Failed to provision agent pool. Exception: The logged in user, , does not have Manage permissions in the Azure DevOps organization provided, ."` + +To resolve the issue: +* Your logged in Azure user must have the proper Azure DevOps permissions to create a pool. See [Azure DevOps prerequisites - Verify Azure DevOps permissions](./prerequisites.md#verify-azure-devops-permissions). + +### Pool creation failure due to VNet permissions + +Pool creation fails with a `UnauthorizedAccessToVirtualNetwork` error similar to the following error: `Validation failure "UnauthorizedAccessToVirtualNetwork": "DevOpsInfrastructure service principal does not have Read access to virtual network in resource group . Give Reader and Network Contributor access to DevOpsInfrastructure service principal and try again.`. + +To resolve this issue: +* Managed DevOps Pools requires access to your virtual network. See [Grant Reader and Network Contributor access to DevOpsInfrastructure service principal](./configure-networking.md#grant-reader-and-network-contributor-access-to-devopsinfrastructure-service-principal). +* The virtual network subnet needs to be delegated to `Microsoft.DevOpsInfrastructure/pools`. See [Delegate the subnet to Microsoft.DevOpsInfrastructure/pools](./configure-networking.md#delegate-the-subnet-to-microsoftdevopsinfrastructurepools). + +## Delays in pipeline startup + +When using Managed DevOps Pools, you might encounter situations where there is a long delay before a pipeline starts to run after it is triggered. This section of the troubleshooting guide describes common items that can impact the performance of your pools. For more information, see [Manage cost and performance](./manage-costs.md). + +* [Check for insufficient parallel jobs](#check-for-insufficient-parallel-jobs) +* [Check Maximum agents configuration](#check-maximum-agents-configuration) +* [Consider pre-provisioning agents using a standby agent schedule](#consider-pre-provisioning-agents-using-a-standby-agent-schedule) + * [Automatic standby mode for new pools](#automatic-standby-mode-for-new-pools) + * [Check standby agent percentage if using standby agents with multiple images](#check-standby-agent-percentage-if-using-standby-agents-with-multiple-images) +* [Consider using Stateful pools with a grace period to keep agents online](#consider-using-stateful-pools-with-a-grace-period-to-keep-agents-online) +* [Check time-out error codes](#check-time-out-error-codes) + +### Check for insufficient parallel jobs + +Managed DevOps Pools agents are considered to be self-hosted agents by Azure DevOps, and require self-hosted parallel jobs to run. For example, if your organization's self-hosted parallel count is 10, your organization can run only 10 self-hosted pipeline jobs concurrently. If more than 10 pipelines are queued, only 10 at a time can run. + +Check your self-hosted parallel jobs count to ensure that you have enough capacity to meet the concurrent pipeline needs of your workload. For more information, see [Configure and pay for parallel jobs](../pipelines/licensing/concurrent-jobs.md). + +### Check Maximum agents configuration + +The [Maximum agents](./configure-pool-settings.md#maximum-agents) setting configures the maximum count of running agents in your Managed DevOps Pool. If the **Maximum agents** setting is 5, Managed DevOps Pools can run a maximum of five concurrent pipelines. If more than five pipelines are queued, the additional pipelines won't start until one of the five available agents is available. + +> [!NOTE] +> **Maximum agents** configures the maximum number of agents that can be provisioned at the same time, but your organization's self-hosted parallel jobs count specifies the number of jobs that can run concurrently. Ensure that you have enough self-hosted parallel jobs available in your organization to enable your agents to run jobs. For more information, see [Azure DevOps Services parallel job pricing](./pricing.md#azure-devops-services-parallel-job-pricing). + +### Consider pre-provisioning agents using a standby agent schedule + +If [Standby agent mode](./configure-scaling.md#standby-agent-mode) is disabled, Managed DevOps Pools agents are started on demand when a pipeline is queued, and while typically a fresh agent takes only a few moments to start, sometimes it can take up to 15 minutes. + +When **Standby agent mode** is enabled, you can specify a schedule and a count of agents to keep ready to meet the demands of your workload. + +For more information, see [Manage cost and performance - Pre-provisioning with standby agents](./manage-costs.md#pre-provisioning-with-standby-agents). + +#### Automatic standby mode for new pools + +Manage DevOps Pools uses historical pool usage data to help make its [automatic standby mode](./configure-scaling.md#automatic) scaling predictions. New pools don't have any historical data, so agents might be created on demand. To improve performance, you can switch to manual standby mode for the first month, and switch to automatic standby mode once Managed DevOps Pools has had time to observe your pool's usage. + +#### Check standby agent percentage if using standby agents with multiple images + +If you use standby agents with multiple images, check the history of usage per image and compare it with the [Standby agent percentage](./configure-scaling.md#manual) setting of your images to ensure your standby ratio matches your usage. For example, if you have one Windows image and one Ubuntu image, and your workload uses Windows 75% of the time, ensure your Windows image is configured with a standby agent percentage of 75. + +### Consider using Stateful pools with a grace period to keep agents online + +One option to improve agent performance without using standby agents is to use stateful agents with a short grace period. When a stateful agent with a grace period completes a job, it stays online for the duration specified by the grace period and waits for additional jobs. If your workload comes in bursts, you can configure a grace period that keeps agents online when jobs are steady, and starts them from scratch during slower periods. + +For more information, see [Standby agents](configure-scaling.md#standby-agent-mode) and [Stateful pools](configure-scaling.md#stateful-pools). + +### Check time-out error codes + +If your agent assignment times out, you can check the error code on the [Error codes](./monitor-pool.md#error-codes-chart) section of the [Overview](./monitor-pool.md#view-metrics-on-the-managed-devops-pool-overview) page. + +## See also + +* [Managed DevOps Pools prerequisites](./prerequisites.md) +* [Configure Managed DevOps Pools networking](./configure-networking.md) +* [Manage cost and performance](./manage-costs.md) diff --git a/docs/managed-devops-pools/view-agents.md b/docs/managed-devops-pools/view-agents.md new file mode 100644 index 00000000000..90df4455cca --- /dev/null +++ b/docs/managed-devops-pools/view-agents.md @@ -0,0 +1,42 @@ +--- +title: View agents +description: View the status of agents in the pool. +ms.date: 11/13/2024 +--- + +# View agents + +You can view the status of the agents in your pool on the **Agents** pane. You can use this information to get a quick overview of how many agents are running jobs and see how many standby agents are online. + +## Agents list + +Go to your Managed DevOps Pool and choose **Settings** > **Agents** to view the status of the agents in your pool. + +:::image type="content" source="media/agents/agents-status.png" lightbox="media/agents/agents-status-expanded.png" alt-text="Screenshot of list of agents and their status."::: + +The **Agents** list displays the following columns. + +| Name | Description | +|------|-------------| +| **Agent Machine Name** | The name of the agent instance. | +| **Image** | The name of the image. For more information, see [Configure images](configure-images.md). | +| **Image version** | The version of the agent image. For more information, see [Configure images](configure-images.md). | +| **Status** | The current status of the agent. See [Status](#status) for more information about each status type. | + +## Status + +Agents in the **Agents** list can have the following statuses. + +| Status | Description | +|--------|-------------| +| **Ready** | The agent is online and is ready to accept jobs. You can expect to see this status if you have standby agents configured or stateful pools with a grace period. | +| **NotReady** | A stateful agent job is complete, but the agent not ready to accept a new job. | +| **Allocated** | The agent is running a job. | +| **PendingReimage** | The agent job is complete and the agent is ready to be reimaged. This status is typical if you have you have your pool configured for stateless agents with standby agent mode enabled. | +| **Reimaging** | The agent is being prepared with a fresh image. This status is typical for stateless agents with standby agent mode enabled. | +| **Starting** | The agent is starting up and should be ready to accept jobs when it completes starting. | +| **PendingReturn** | The agent is preparing to be shut down. This status is typical for stateless agents with standby agent mode disabled. | +| **Returned** | The agent is shut down and will be removed from the **Agents** list in a few moments. This status is typical for stateless agents with standby agent mode disabled after they run a job. | + +For more information, see [Standby agents](configure-scaling.md#standby-agent-mode) and [Agent state](configure-scaling.md#agent-state). + diff --git a/docs/marketplace-extensibility/index.yml b/docs/marketplace-extensibility/index.yml index b07d8d6a485..ffc4a323ae6 100644 --- a/docs/marketplace-extensibility/index.yml +++ b/docs/marketplace-extensibility/index.yml @@ -1,7 +1,7 @@ ### YamlMime:Landing title: Marketplace & Extensibility documentation -summary: Discover, manage, develop extensions and widgets for integration with Azure DevOps. +summary: Discover, manage, develop extensions, and widgets for integration with Azure DevOps. metadata: title: Marketplace & extensibility documentation @@ -11,7 +11,7 @@ metadata: ms.topic: landing-page author: chcomley ms.author: chcomley - ms.date: 10/08/2019 + ms.date: 03/03/2025 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -23,7 +23,7 @@ landingContent: linkLists: - linkListType: concept links: - - text: About Azure DevOps Marketplace + - text: Learn about Azure DevOps Marketplace url: ../extend/overview.md?toc=/azure/devops/marketplace-extensibility/toc.json - linkListType: how-to-guide links: @@ -51,7 +51,7 @@ landingContent: linkLists: - linkListType: overview links: - - text: Integration overview + - text: Learn about integrating applications url: ../integrate/index.md?toc=/azure/devops/marketplace-extensibility/toc.json - linkListType: how-to-guide links: @@ -69,11 +69,11 @@ landingContent: linkLists: - linkListType: how-to-guide links: - - text: Azure Boards with Slack + - text: Use Azure Boards with Slack url: ../boards/integrations/boards-slack.md?toc=/azure/devops/marketplace-extensibility/toc.json - - text: Azure Pipelines with Slack + - text: Use Azure Pipelines with Slack url: ../pipelines/integrations/slack.md?toc=/azure/devops/marketplace-extensibility/toc.json - - text: Azure Pipelines with Microsoft Teams + - text: Use Azure Pipelines with Microsoft Teams url: ../pipelines/integrations/microsoft-teams.md?toc=/azure/devops/marketplace-extensibility/toc.json - title: Integrate with Service hooks linkLists: diff --git a/docs/marketplace-extensibility/toc.yml b/docs/marketplace-extensibility/toc.yml index 355044404e9..6ad0f5b1d98 100644 --- a/docs/marketplace-extensibility/toc.yml +++ b/docs/marketplace-extensibility/toc.yml @@ -25,8 +25,6 @@ href: ../integrate/get-started/authentication/oauth.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Cross-platform CLI for Azure DevOps using PATs href: ../integrate/get-started/auth/tfs-basic-auth.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: IIS Basic Authentication and PATs - href: ../integrate/get-started/authentication/iis-basic-auth.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Develop extensions items: - name: Get started @@ -124,13 +122,13 @@ href: ../extend/publish/integration.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Make listing public and Top Publisher program displayName: Marketplace, extension, requirements, qualifications - href: ../extend/publish/publicize.md?toc=/azure/devops/marketplace-extensibility/toc.json + href: ../extend/publish/overview.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Publish via command line displayName: CLI, Marketplace, share href: ../extend/publish/command-line.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Respond to Marketplace reviews displayName: owner, creator, contributor, reply, appeal - href: ../extend/publish/manage-ratings-reviews.md?toc=/azure/devops/marketplace-extensibility/toc.json + href: ../extend/publish/overview.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Reference items: - name: Manifest reference @@ -195,7 +193,7 @@ displayName: oauth, secure, resources, access, credentials, account, approve href: ../service-hooks/authorize.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Service hook consumers - displayName: subscription, event, consumer, action, storage, webhooks, bus, campfire, hipchat, jenkins, kato, trello, zendesk + displayName: subscription, event, consumer, action, storage, webhooks, bus, jenkins, trello, zendesk href: ../service-hooks/consumers.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Service hook events displayName: build, release, deployment, created, updated, deleted, restored, commented, changed, approval @@ -205,7 +203,7 @@ href: ../service-hooks/troubleshoot.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Integrate applications items: - - name: Integrate applications overview + - name: Integrate applications overview href: ../integrate/index.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Get started items: @@ -269,8 +267,8 @@ href: ../pipelines/integrations/microsoft-teams.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Reference items: - - name: REST API reference overview - href: ../integrate/rest-api-overview.md + - name: REST API overview + href: /rest/api/azure/devops/?view=azure-devops-rest-7.2&preserve-view=true - name: Rate limits href: ../integrate/concepts/rate-limits.md - name: Deprecation of WIT & Test client OM @@ -310,4 +308,4 @@ - name: Find and use Visual Studio extensions >> href: /visualstudio/ide/finding-and-using-visual-studio-extensions - name: Install Visual Studio Code extensions >> - href: https://code.visualstudio.com/docs/editor/extension-gallery \ No newline at end of file + href: https://code.visualstudio.com/docs/editor/extension-gallery diff --git a/docs/marketplace/grant-permissions.md b/docs/marketplace/grant-permissions.md index 95c1fd79149..f75093f1cc0 100644 --- a/docs/marketplace/grant-permissions.md +++ b/docs/marketplace/grant-permissions.md @@ -7,7 +7,7 @@ ms.subservice: azure-devops-marketplace ms.assetid: 5b0786ec-9f5e-419f-acef-c15d15985285 ms.author: chcomley author: chcomley -ms.date: 10/12/2022 +ms.date: 03/03/2025 monikerRange: '<= azure-devops' --- @@ -15,30 +15,40 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Learn how to manage permissions for users or groups, so they can manage extensions. +This article helps you understand how to grant and manage permissions for users or groups, enabling them to manage extensions effectively. By setting the appropriate permissions, you can maintain control over the extensions used within your organization and ensure compliance with your security policies. ## Prerequisites + ::: moniker range="azure-devops" -- You must be a member of the Project Collection Administrators group to manage permissions for users or groups. Organization owners are automatically members of this group. -- Private extensions must be shared with your organization to be installed. Check out the [publishing documentation](../extend/publish/overview.md#upload) for information on how to share private extensions. + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the Project Collection Administrators group. Organization owners are automatically members of this group. If you don't have permissions, you can [request extensions](./request-extensions.md) instead or [look up a project collection administrator](../organizations/security/look-up-project-collection-administrators.md).| +|**Extension sharing** | Private extensions [shared with your organization](../extend/publish/overview.md#share-your-extension).| + ::: moniker-end ::: moniker range="< azure-devops" -- You must be a member of the Project Collection Administrators group or have "Edit collection-level information" permissions to manage permissions for users or groups. Organization owners are automatically members of the Project Collection Administrators group. + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the Project Collection Administrators group or **Edit collection-level information** permissions. Organization owners are automatically members of this group.| +|**Extension sharing**| Private extensions [shared with your organization](../extend/publish/overview.md#share-your-extension).| + ::: moniker-end ## Manage permissions ::: moniker range="azure-devops" -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select ![gear icon](../media/icons/gear-icon.png) **Organization settings**. - ![Open Organization settings](../media/settings/open-admin-settings-vert.png) + ![Screenshot showing highlighted Organization settings button.](../media/settings/open-admin-settings-vert.png) 3. Select **Extensions**. - ![Extension settings hub](media/manage-permissions/extensions-settings.png) + ![Screenshot showing Extension settings hub.](media/manage-permissions/extensions-settings.png) 4. Select **Security**. @@ -50,7 +60,7 @@ Learn how to manage permissions for users or groups, so they can manage extensio ::: moniker-end -::: moniker range="azure-devops-2019 || azure-devops-2020" +::: moniker range="=azure-devops-2020" 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). @@ -68,42 +78,7 @@ Learn how to manage permissions for users or groups, so they can manage extensio ::: moniker-end -::: moniker range="tfs-2018" -To grant permissions for publishing or updating to users or groups, use the [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd#permissions) command-line tool. - -1. At the server level, create a group, for example, "TFS Extension Publishers". - - ``` - tfssecurity /gcg "TFS Extension Publishers" "publishers who can manage extensions for the server" /server:ServerURL - ``` - -2. Grant access to the "TFS Extension Publishers" group to manage extensions. - - ``` - tfssecurity /a+ Publisher "//" CreatePublisher n:"[TEAM FOUNDATION]\TFS Extension Publishers" allow /server:ServerURL - tfssecurity /a+ Publisher "//" PublishExtension n:"[TEAM FOUNDATION]\TFS Extension Publishers" allow /server:ServerURL - tfssecurity /a+ Publisher "//" UpdateExtension n:"[TEAM FOUNDATION]\TFS Extension Publishers" allow /server:ServerURL - tfssecurity /a+ Publisher "//" DeleteExtension n:"[TEAM FOUNDATION]\TFS Extension Publishers" allow /server:ServerURL - ``` - -3. Add existing users and groups to the "TFS Extension Publishers" group. - - ``` - tfssecurity /g+ "[TEAM FOUNDATION]\TFS Extension Publishers" n:User /server:ServerURL - ``` - ``` - -You can add users later to "TFS Extension Publishers". This permission is a server-level permission. -When you update or delete an extension, it affects all the project collections that use the extension. -::: moniker-end +By following these steps, you can effectively manage extension permissions within your Azure DevOps organization. This ensures that only authorized users can install, update, or remove extensions, maintaining the security and integrity of your development environment. ## Related articles diff --git a/docs/marketplace/install-extension.md b/docs/marketplace/install-extension.md index 84330c0533b..6df4214cfb5 100644 --- a/docs/marketplace/install-extension.md +++ b/docs/marketplace/install-extension.md @@ -1,13 +1,14 @@ --- title: Install extensions -description: Learn how to install, assign, and uninstall extensions for Azure DevOps. +description: Learn how to install, assign, disable, and uninstall extensions for Azure DevOps. ms.topic: how-to ms.custom: engagement-fy23, devx-track-azurecli ms.subservice: azure-devops-marketplace ms.assetid: dd117c5c-111f-4361-91c6-ed37fb476c75 ms.author: chcomley author: chcomley -ms.date: 03/06/2023 +ai-usage: ai-assisted +ms.date: 04/21/2025 monikerRange: '<= azure-devops' --- @@ -15,34 +16,44 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Learn how to install, assign, disable, and uninstall extensions, which add new features and capabilities for Azure DevOps. +Install, assign, disable, and uninstall extensions, which add new features and capabilities for Azure DevOps. For more information about extensions, see the [developing](../extend/overview.md) and [publishing](../extend/publish/overview.md) overviews. ## Prerequisites + ::: moniker range="azure-devops" -- To install extensions, you must be a member of the Project Collection Administrators group. Organization owners are automatically members of this group. If you don't have permissions, you can [request extensions](./request-extensions.md) instead or [look up a project collection administrator](../organizations/security/look-up-project-collection-administrators.md). -- Private extensions must be shared with your organization to be installed. Check out the [publishing documentation](../extend/publish/overview.md#upload) for information on how to share private extensions. + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the Project Collection Administrators group. Organization owners are automatically members of this group. If you don't have permissions, you can [request extensions](./request-extensions.md) instead or [look up a project collection administrator](../organizations/security/look-up-project-collection-administrators.md).| +|**Extension sharing** | Private extensions [shared with your organization](../extend/publish/overview.md#share-your-extension).| + ::: moniker-end ::: moniker range="< azure-devops" -- Only members of the Project Collection Administrators group or who have "Edit collection-level information" permissions can install extensions. Organization owners are automatically members of this group. If you don't have permissions, you can [request extensions](./request-extensions.md) instead or [look up a project collection administrator](../organizations/security/look-up-project-collection-administrators.md). + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the Project Collection Administrators group or **Edit collection-level information** permissions. Organization owners are automatically members of this group. If you don't have permissions, you can [request extensions](./request-extensions.md) instead or [look up a project collection administrator](../organizations/security/look-up-project-collection-administrators.md).| +|**Extension sharing** | Private extensions [shared with your organization](../extend/publish/overview.md#share-your-extension).| > [!NOTE] -> To use an existing Azure subscription for billing, you must have at least co-administrator permissions for that subscription. If you don't have permissions, an Azure Account Administrator or Service Administrator can [add you as co-administrator](/azure/billing-add-change-azure-subscription-administrator) to the Azure subscription in the Azure portal. +> To use an existing Azure subscription for billing, have at least coadministrator permissions for that subscription. If you don't have permissions, an Azure Account Administrator or Service Administrator can [add you as coadministrator](/azure/billing-add-change-azure-subscription-administrator) to the Azure subscription in the Azure portal. + +Your project collection reuses your Azure subscription for future Marketplace purchases. [Where can I find more info about Azure billing?](faq-extensions.yml) -Your project collection reuses your Azure subscription for future Marketplace purchases. -[Where can I find more info about Azure billing?](faq-extensions.yml) ::: moniker-end ## Install an extension Install an extension to your organization by doing the following steps. -::: moniker range="azure-devops" #### [Browser](#tab/browser) -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +::: moniker range=">= azure-devops-2020" + +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select the shopping bag icon, and then select **Browse Marketplace**. ![Screenshot showing highlighted shopping bag icon and Browse Marketplace button selection.](media/shopping-bag-icon-browse-marketplace.png) @@ -63,8 +74,12 @@ Your extension is now installed! You can now go to your organization to use your ![Extension installed](media/get-vsts-extensions/you-are-all-set.png) +::: moniker-end + #### [Azure DevOps CLI](#tab/azure-devops-cli/) +::: moniker range=" azure-devops" + Install an extension with the [az devops extension install](/cli/azure/devops/extension#az-devops-extension-install) command. To get started, see [Get started with Azure DevOps CLI](../cli/index.md). ### Search for an extension @@ -140,196 +155,71 @@ serviceInstanceType: null version: 5.0.1.34507 ``` -* * * ::: moniker-end -::: moniker range="> tfs-2018 < azure-devops" +::: moniker range=">= azure-devops-2020 < azure-devops" -1. Open your Azure DevOps Server home page (`https://{server}:DefaultCollection`). +**Manual installation:** -2. Open the extensions menu and choose **Browse Marketplace**. +1. Use the following command to get the extension you want to install. - ![Browse Marketplace](media/get-devops-extensions/install-devops-extension-01.png) + `az extension add --name ` -3. Find the extension that you want to install. Use the search box to filter the list of extensions. +2. Replace `` with the actual name of the extension you want to install. + - If the extension is from an external resource or you have a direct link to it, provide the source URL or local path. - ![Select an extension](media/get-devops-extensions/install-devops-extension-02.png) + `az extension add --source ` -4. Select the extension and choose **Get** or **Get it free**. - Or, for some third-party extensions, choose **Get Started** to show pricing information - and extension-specific installation instructions. + You can also build a private extension index following the format in `index.json`, then set the extension index URL used by Azure CLI starting from version 2.20.0. After that, you can install the extension by name from the private extension index. - ![Get the extension](media/get-devops-extensions/install-devops-extension-04.png) +**Automatic installation (Dynamic install):** - If you don't have permission to install the extension, you can request an administrator - to install it for you. Your request gets stored in Azure DevOps Server and is ready for attention from an administrator. +When you run an extension command that isn’t installed, the Azure CLI recognizes the command you run and automatically installs the extension for you (starting from version 2.10.0). This feature referred to as dynamic install, is enabled by default since 2.12.0. You can also enable it through configuration for previous supported versions: -5. Select the project collection where you want to install this extension and choose **Install**. +`az config set extension.use_dynamic_install=yes_prompt` - ![Select project collection and choose Install.](media/get-devops-extensions/install-devops-extension-06.png) +Use the following configuration command to enable dynamic install without a prompt: -6. After installation is complete, go to the project collection or return to the Marketplace to find other extensions. +`az config set extension.use_dynamic_install=yes_without_prompt` - ![Installation done](media/get-devops-extensions/install-devops-extension-07.png) +Use the following configuration command to turn off the dynamic install feature to revert to the default behavior: -::: moniker-end - -::: moniker range=" tfs-2018" - -1. From your Azure DevOps Server home page (```https://{server}:8080/tfs/```), - go to the project collection where you want to install the extension. - -2. Open the extensions menu and choose **Browse Marketplace**. - - :::image type="content" source="media/browse-marketplace2-new.png" alt-text="Screenshot showing highlighted Browse Marketplace button."::: - -3. Find and select the extension that you want to install. - - :::image type="content" source="media/get-tfs-extensions/connected/marketplace-select-extension.png" alt-text="Screenshot showing selected extension example."::: - -4. Select the extension, and then **Install**. +`az config set extension.use_dynamic_install=no` -5. Confirm the project collection that you want to install this extension to. - - :::image type="content" source="media/get-tfs-extensions/connected/select-team-project-collection.png" alt-text="Selection showing Project collection."::: +The extension command returns a “command-not-found” error if the extension isn’t installed. -5. Finish installing your extension. +**Extension location:** -6. Assign the extension to users who need access. - Otherwise, you can go to your project collection to use your extension. - Tell your team about this extension, so they can start using its capabilities too. - - :::image type="content" source="media/get-tfs-extensions/connected/assign-extension-to-users.png" alt-text="Screenshot showing installed extension confirmation."::: +Once an extension is installed, you can find it under the value of the `$AZURE_EXTENSION_DIR` shell variable. If this variable is unset, by default the value is `$HOME/.azure/cliextensions` on Linux and macOS, and `%USERPROFILE%\\.azure\\cliextensions` on Windows. ::: moniker-end -::: moniker range=" tfs-2018" -### Install extensions when disconnected - -When you're disconnected from Azure DevOps Server, you can install free and preview extensions. First, you [download the extension](#download-from-the-marketplace), then [upload it to Azure DevOps Server](#upload-extension-to-azure-devops), and then [install it in a project collection](#install-extension-in-your-project-collection). - -#### Download from the Marketplace - -1. Sign in to the [Marketplace > Azure DevOps](https://marketplace.visualstudio.com/azuredevops). - -2. Find the extension that you want to install. - - :::image type="content" source="media/get-tfs-extensions/standalone/marketplace-find-extension.png" alt-text="Screenshot showing search for extension in the Marketplace."::: - - :::image type="content" source="media/get-tfs-extensions/standalone/marketplace-find-extension2.png" alt-text="Screenshot showing search for extension."::: - -3. Download and save your extension. - - :::image type="content" source="media/get-tfs-extensions/standalone/download-extension.png" alt-text="Screenshot showing download extension."::: - -#### Upload extension to Azure DevOps - -1. Browse for your downloaded extensions (```https://{server}:8080/tfs/_gallery```). - -2. Select **Manage extensions**. - - :::image type="content" source="media/get-tfs-extensions/standalone/manage-extensions.png" alt-text="Screenshot showing selection, Manage extensions button."::: - -3. Select **Upload new extension**. - - :::image type="content" source="media/get-tfs-extensions/standalone/upload-extension.png" alt-text="Screenshot showing selection, Upload new extension button."::: - - [Why can't I upload extensions?](faq-extensions.yml) - -> [!TIP] -> The maximum size for upload is 25MB. If you can't work around this requirement, **Report a problem** in the [Developer Community](https://developercommunity.visualstudio.com/search?space=21). - -#### Install extension in your project collection - -1. Select and install the extension that you uploaded. - - :::image type="content" source="media/get-tfs-extensions/standalone/install-extension.png" alt-text="Screenshot showing extension selection."::: - -2. Choose the project collection where you want to install the extension. - - :::image type="content" source="media/get-tfs-extensions/standalone/choose-collection.png" alt-text="Screenshot showing Continue button selection."::: - -3. Review the permissions that the extension gets when it's installed. Finish installing your extension. - - :::image type="content" source="media/get-tfs-extensions/standalone/confirm.png" alt-text="Screenshot showing review of permissions granted to the extension."::: - - You can now go to your project collection to use your extension. Tell your team about this extension, so they can start using its capabilities too. - -### Install pre-installed extensions (first-party) for disconnected TFS - ->[!NOTE] -> This section is only for adding pre-installed extensions (first-party), if you're installing extensions that aren't pre-installed with TFS, see the section [Install extensions when disconnected](#install-extensions-when-disconnected). - -For first-party extensions that come pre-installed with TFS, here's an alternate method of installation that prevents compatibility issues. - -1. Hover over the shopping bag and select **Manage extensions** - - ![Select Manage extensions.](./media/get-tfs-extensions/standalone/manage-extensions.png) - -2. Once on the Extensions page, select **Browse local extensions** - - ![On the Extensions page, Browse local extensions](./media/get-tfs-extensions/standalone/browse-local-extensions.png) - -3. Scroll down until you see the "Plan and track" category, which includes **Delivery Plans**. Select **Delivery Plans**. - - ![Choose your extension](./media/get-tfs-extensions/standalone/delivery-plans.png) - -4. You're redirected to a local extension page for Delivery Plans where you select **Install**. Installation works when you're online and offline. - - ![Delivery plans extension gallery](./media/get-tfs-extensions/standalone/delivery-plans-gallery.png) - -### Install extension from the local gallery - -Several extensions are pre-installed in the local extensions gallery. -Users can install these extensions without requiring an external connection to Marketplace or the internet. - -> [!TIP] -> Extensions that have previously been installed from Marketplace appear in the local gallery automatically so that they can easily be installed into other project collections. - -1. Open the extensions menu and choose **Manage Extensions**. - - ![On the extensions menu, choose Manage extensions.](media/get-devops-extensions/install-devops-extension-13.png) - -2. In the Extensions page, choose **Browse local extensions** - - ![Browse local extensions](media/get-devops-extensions/install-devops-extension-09.png) - -3. Choose the extension you want to install. - - ![Choose a local extension](media/get-devops-extensions/install-devops-extension-10.png) - -4. Select the project collection where you want to install this extension and choose **Install**. - - ![Select the project collection where you want to install this extension and choose Install.](media/get-devops-extensions/install-devops-extension-06.png) - -5. After installation is complete, go to the project collection or return to the Marketplace to find other extensions. +* * * - ![Installation done](media/get-devops-extensions/install-devops-extension-07.png) +### High privilege, pipeline decorators, and unpublished extensions -::: moniker-end +Extensions with high privilege scopes, pipeline decorators, or unpublished status can pose potential security risks if not properly vetted. High privilege scopes grant extensive access to your organization's resources, while pipeline decorators can modify all pipelines in your organization. Unpublished extensions might no longer be maintained by their publishers. For more information on managing these types of extensions, see [Manage high privilege scopes, pipeline decorators, and unpublished extensions](manage-high-privilege-extensions.md). -## Uninstall or disable an extension - -> [!NOTE] -> Charges continue for a paid extension until you [reduce all users to zero (0) for the extension](install-extension.md). +## Uninstall or disable an extension ::: moniker range="azure-devops" + #### [Browser](#tab/browser) -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select ![gear icon](../media/icons/gear-icon.png) **Organization settings**. - ![Open Organization settings](../media/settings/open-admin-settings-vert.png) + ![Screenshot showing Open Organization settings.](../media/settings/open-admin-settings-vert.png) 3. Select **Extensions**, and then select the extension that you want to uninstall or disable. - ![Select uninstall or disable for extension](media/org-settings-select-extension.png) + ![Screenshot showing Select uninstall or disable for extension.](media/org-settings-select-extension.png) 4. Select **Uninstall** or select the ellipses (**...**), and then select **Disable**. - ![Disable or uninstall extension](media/disable-or-uninstall-extension.png) + ![Screenshot showing Disable or uninstall extension actions.](media/disable-or-uninstall-extension.png) #### [Azure DevOps CLI](#tab/azure-devops-cli/) @@ -360,7 +250,7 @@ The following command uninstalls the "Timetracker" extension without prompts for ```azurecli az devops extension uninstall --extension-name Timetracker --publisher-name 7pace --yes ``` - + ### Disable an extension @@ -396,17 +286,18 @@ Publisher Id Extension Id Name Version Last Updated State ::: moniker range="< azure-devops" -To uninstall extensions in a collection, perform the following steps. +To uninstall extensions in a collection, do the following steps: 1. Go to the local gallery management portal (```http://{server}:8080/tfs/_gallery/manage```). 2. For the wanted extension, select the ellipses (**...**), and then select **Remove**. - ![Remove extension](media/remove-extension-TFS.png) + ![Screenshot showing Remove extension action.](media/remove-extension-TFS.png) ::: moniker-end ::: moniker range="azure-devops" + ## Enable or list extensions through the command line Enable an extension with the [az devops extension enable](/cli/azure/devops/extension#az-devops-extension-enable) command. To get started, see [Get started with Azure DevOps CLI](../cli/index.md). @@ -453,7 +344,7 @@ az devops extension list [--include-built-in {false, true}] ### Example - list extensions -The following command lists extensions in your organization. It excludes the **disabled** and **built-in** extensions, and shows the results in table format. +The following command lists extensions in your organization. It excludes the disabled and built-in extensions, and shows the results in table format. ```azurecli az devops extension list --include-built-in false --include-disabled false -output table @@ -510,31 +401,53 @@ Publisher Id Extension Id Name Version Last Updated State ::: moniker-end +### Troubleshoot extension installation -## Frequently asked questions (FAQs) +To resolve common issues, follow these troubleshooting steps: + +- **Extension fails to install:** + - **Check permissions:** To install extensions, ensure you're a Project Collection Administrator or have the necessary permissions granted by an administrator. + - **Verify extension compatibility:** Ensure the extension is compatible with your version of Azure DevOps. Check the extension's details page for compatibility information. + - **Network issues:** Verify that your network connection is stable and that there are no firewall or proxy settings blocking the installation process. + +- **Extension crashes or causes errors:** + - **Collect diagnostic information:** If an extension crashes or causes errors, collect diagnostic information to help identify the issue. This information includes error messages, logs, and screenshots of the problem. + - **Check extension logs:** Some extensions provide logs that can help diagnose issues. Check the extension's documentation for information on how to access and interpret these logs. + - **Contact support:** If you can't resolve the issue, contact the extension's support team with the collected diagnostic information. Provide as much detail as possible to help them troubleshoot the problem. + +- **Extension not visible after installation:** + - **Refresh the page:** Sometimes, the extension might not appear immediately after installation. + - **Check permissions:** Ensure you have the necessary permissions to view and use the extension. Some extensions might require specific permissions to be visible. + - **Reinstall the extension:** If the extension still isn't visible, try uninstalling and reinstalling it. ::: moniker range=" < azure-devops" -### Q: Why don't I see my organization from the Marketplace installation page? + +## Frequently asked questions (FAQs) + +### Q: Why don't I see my organization from the Marketplace installation page? + A: If you don't see your organization when buying from the Azure DevOps Marketplace, try the following steps: 1. Check the identity that you use to sign in to the Visual Studio Marketplace. In the upper-right corner, select your user name to view your profile. -1. On the left, make sure your email address and directory are correct. +1. Make sure your email address and directory are correct. 1. Close all browser windows. 1. Open a private or incognito browsing session. 1. Sign in to the Visual Studio Marketplace. Use the identity of a user in the organization that you want. > [!TIP] -> Azure DevOps might ask you to choose between "work or school account" or "personal account". If so, then you used an email address that's the same for a Microsoft account and a "work or school account" that your organization manages in Azure Active Directory. Although these identities have the same email address, they're still separate identities with different profiles, security settings, and permissions. +> Azure DevOps might ask you to choose between "work or school account" or "personal account." If so, then you used an email address that's the same for a Microsoft account and a "work or school account" that your organization manages in Microsoft Entra ID. Although these identities have the same email address, they're still separate identities with different profiles, security settings, and permissions. > Choose the identity for the user in the organization that you want to select. ### Q: Why can't I install an extension? + A: You can't install extensions for one of the following reasons. -- You must be a member of the [**Project Collection Administrators** group](../organizations/security/look-up-project-collection-administrators.md) or are the [**Organization owner**](../organizations/security/look-up-organization-owner.md). If you don't have permissions, but you're a project member, you can [request extensions](request-extensions.md) instead. +- Be a member of the [**Project Collection Administrators** group](../organizations/security/look-up-project-collection-administrators.md) or are the [**Organization owner**](../organizations/security/look-up-organization-owner.md). If you don't have permissions, but you're a project member, you can [request extensions](request-extensions.md) instead. - For an "already installed or requested" error, check with your Project Collection Administrator and ask them to assign the extension to you. ### Q: Why can't users access extension features? -A: Users can't access an extension for one of the following reasons: + +A: Users can't access an extension for one of the following reasons. - Most extensions require that users have at least Basic access, not Stakeholder. For example, you can install the free [Code Search extension](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search), but each user must have at least Basic access to search for code. To help your team improve app quality, you can install the free [Test & Feedback extension](https://marketplace.visualstudio.com/items?itemName=ms.vss-exploratorytesting-web). You experience different capabilities, based on your access level and whether you work offline or connected to Azure DevOps Services or on-premises Azure DevOps Server. For more information, see the extension's description in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops), Azure DevOps tab. -- If you're using an organization and you started a free extension trial, your trial might have expired. To check whether your trial expired: +- If you're using an organization and you started a free extension trial, your trial might be expired. Check whether your trial expired. 1. On your organization toolbar, select **Users**. 2. Go to the extension pane. 3. Check for an expiration message to find if or when your extension expired. @@ -547,55 +460,47 @@ A: Users can't access an extension for one of the following reasons: For more information, see [Assign extensions to users](../marketplace/install-extension.md). ### Q: What happened to my preview extension? -A: Your extension may have been moved out of preview. After a preview period, an extension longer is generally available as a paid extension. A grace period may be offered before you have to buy the extension. All preview extensions automatically convert to a [free trial](../organizations/billing/try-additional-features-vs.md) before you have to buy the extension. -::: moniker-end +A: Your extension might be out of preview. After a preview period, an extension longer is generally available as a paid extension. A grace period might be offered before you have to buy the extension. All preview extensions automatically convert to a [free trial](../organizations/billing/try-additional-features-vs.md) before you have to buy the extension. -::: moniker range=" < azure-devops" +### Q: Why can't I install extensions for Azure DevOps Server? -### Q: Why can't I install extensions for Azure DevOps Server? (on-premises) A: You can't install extensions for Azure DevOps Server for one of the following reasons: -- You must be a member of the **Project Collection Administrators** group or have the **Edit collection-level information** permission set to **Allow** in the project collection where you want to install extensions. If you don't have permissions, you can [request extensions](./request-extensions.md) instead. +- Be a member of the **Project Collection Administrators** group or have the **Edit collection-level information** permission set to **Allow** in the project collection where you want to install extensions. If you don't have permissions, you can [request extensions](./request-extensions.md) instead. - You might get an error that says you already installed or requested the extension. If so, check with a member of the **Project Collection Administrators** group and ask them to assign the extension to you. For more information, see [Request an increase in permission levels](../organizations/security/request-changes-permissions.md). -### Q: Why don't I see the project collection I want? (on-premises) -A: You must be a member of your project collection. Follow these steps to check your identity that you use to sign in to the Marketplace. +### Q: Why don't I see the project collection I want (on-premises)? + +A: Be a member of your project collection. Follow these steps to check your identity that you use to sign in to the Marketplace. 1. On your Azure DevOps Server web portal home page (```https://{server}:8080/tfs/```), go to the top-right corner of the page, and select your user name to view your profile. 1. On the left side of your profile, make sure that your email address and directory are correct. 1. Close all browser windows. 1. Open a private or incognito browsing session. -1. Sign in to your Azure DevOps Server home page (```https://{server}:8080/tfs/```) with the identity that's a user in the project collection where you want to install the extension. - - Azure DevOps might ask you to choose between a "work or school organization" or "personal account". This message means that you used an email address that's the same for a Microsoft account and a "work or school account" managed by your organization in Azure Active Directory. Although these identities have the same email address, they're still separate identities with different profiles, security settings, and permissions. Choose the identity that's the user in your project collection. - +1. Sign in to your Azure DevOps Server home page (```https://{server}:8080/tfs/```) with the identity that's a user in the project collection where you want to install the extension.
      + Azure DevOps might ask you to choose between a "work or school organization" or "personal account." This message means that you used an email address that's the same for a Microsoft account and a "work or school account" managed by your organization in Microsoft Entra ID. Although these identities have the same email address, they're still separate identities with different profiles, security settings, and permissions. Choose the identity that's the user in your project collection.
      1. From your project collection, go to the Marketplace. -### Q: Why doesn't the extension that I want show a download button? (on-premises) +### Q: Why doesn't the extension that I want show a download button (on-premises)? + A: Some extensions work only with Azure DevOps Services for one of the following reasons: - The extension uses Azure DevOps features that aren't released yet for Azure DevOps Server. - The [extension manifest](../extend/develop/manifest.md) indicates that the extension is available only for Azure DevOps Services (targets = Microsoft.Visualstudio.Services.Cloud). - The extension manifest indicates that the extension is an integration (targets = Microsoft.Visualstudio.Services.Integration). -### Q: Why can't I upload extensions to Azure DevOps Server? (on-premises) -A: You must be a member of the [Team Foundation Administrators group](/azure/devops/server/admin/add-administrator#add-a-user-to-the-server-administrators-group). You must also have [**Edit instance-level information** permissions](../organizations/security/permissions.md#server) for the Azure DevOps Server where you want to upload extensions. -::: moniker-end - -### Q: How do I get support for Azure subscriptions, billing, and Marketplace? -A: Depending on the support you need, choose from the following articles: -- [Azure Billing and Subscription FAQs](https://azure.microsoft.com/pricing/faq/) -- [Azure support](https://azure.microsoft.com/support/options/). -- [Azure billing support](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade) -- [Visual Studio subscriptions support](https://visualstudio.microsoft.com/subscriptions/support) +### Q: Why can't I upload extensions to Azure DevOps Server? -> [!NOTE] -> The Azure DevOps support team is unable to support Visual Studio Marketplace extensions. To get support on marketplace extensions, locate the extension you're using in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/search?target=AzureDevOps&category=Azure%20Pipelines&sortBy=Installs). On the extension page, you can find a link to the GitHub repository where you can create an issue, or a link to get community support. +A: Be a member of the [Team Foundation Administrators group](/azure/devops/server/admin/add-administrator#add-a-user-to-the-server-administrators-group). You must also have [**Edit instance-level information** permissions](../organizations/security/permissions.md#server) for the Azure DevOps Server where you want to upload extensions. +::: moniker-end ## Next steps - > [!div class="nextstepaction"] - > [Manage extension permissions](grant-permissions.md) +> [!div class="nextstepaction"] +> [Manage extension permissions](grant-permissions.md) ## Related articles -- [Request extensions and approve extension requests](request-extensions.md) +- [Request and approve extension requests](request-extensions.md) - [Develop a web extension](../extend/get-started/node.md) +- [Review Azure Billing and Subscription FAQs](https://azure.microsoft.com/pricing/faq/) +- [Access Azure billing support](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade) +- [Get Visual Studio subscriptions support](https://visualstudio.microsoft.com/subscriptions/support) diff --git a/docs/marketplace/manage-high-privilege-extensions.md b/docs/marketplace/manage-high-privilege-extensions.md new file mode 100644 index 00000000000..f7f8708b58c --- /dev/null +++ b/docs/marketplace/manage-high-privilege-extensions.md @@ -0,0 +1,106 @@ +--- +title: Manage high privilege scopes, pipeline decorators, and unpublished extensions +description: Learn why certain extensions are marked as high privilege and unpublished and how to best manage them in your Azure DevOps organization. +ms.topic: conceptual +ms.subservice: azure-devops-marketplace +ms.author: pliaros +author: chcomley +ms.date: 04/21/2025 +#customer intent: As an Azure DevOps administrator, I want to identify and manage high privilege, pipeline decorators, and unpublished extensions so that I can protect my organization from potential security vulnerabilities and other unexpected behaviour. +--- + +# Manage high privilege scopes, pipeline decorators, and unpublished extensions + +> [!IMPORTANT] +> This feature is in **public preview**. Features in public preview could undergo changes before becoming generally available. + +Extensions in Azure DevOps enhance functionality and streamline workflows, but some extensions might pose security vulnerabilities due to their high privilege scopes or unpublished status. This article explains how to identify and manage high privilege, pipeline decorators, and unpublished extensions to protect your Azure DevOps organization from potential security vulnerabilities or unexpected behavior. + +By following these practices, you can ensure your organization remains secure while benefiting from the capabilities of Azure DevOps extensions. + +## What are high privilege scopes and high privilege extensions? + +### High privilege scopes + +In your extension, you can define one or more scopes. These scopes determine which resources your extension can access and the operations permitted to perform on those resources. + +If no scopes are specified, extensions only gain access to user profile and extension data. +High privilege scopes are dedined as overly permissive scopes. For a list of scopes, including high privilege scopes, see the [Manifest reference](../extend/develop/manifest.md#scopes). +Examples of high privilege scopes include: +- Read, update, and delete source code +- Read, write, and manage identities and groups +- Create, read, update, and delete projects + +### High privilege extensions + +High privilege extensions make use of one or more high privilege scopes. These extensions have the potential to introduce security vulnerabilities or risks if they're not properly vetted or maintained. High privilege extensions can access sensitive resources and perform critical operations, making it essential to evaluate them carefully to ensure they align with your organization's security and operational standards. + +When you manage high privilege extensions, consider the following actions: +- **Trust the publisher**: Install and use extensions only if you trust their code and publisher +- **Review the requested scopes**: Ensure the requested scopes are necessary for the extension's functionality +- **Limit usage**: Install high privilege extensions only if they're critical to your workflows + +## Evaluate the usage of high privilege scopes in Azure DevOps extensions + +Few of your already installed extensions might be flagged for high privilege scope usage. You can check their state in the **Extensions** section of **Organization settings**. This designation is due to several potential reasons, explained in this article. + +We recommend that you only install, update, or use extensions if you trust their code and their publishers. + +This feature only highlights in the user interface whether a specific extension uses high privilege scopes. Microsoft runs a virus scan on each new and updated extension package that gets published. For more information, see [Publish your extension](../extend/publish/overview.md#publish-your-extension). + +> [!div class="mx-imgBorder"] +> ![Screenshot showing list of high privilege extensions in Organization settings.](media/high-privilege-extensions/extension-list.png) + +By understanding and managing high privilege scopes and extensions, you can safeguard your Azure DevOps organization while still using the capabilities of trusted extensions. + +## Manage extensions with high privilege scopes + +Extensions that use high privilege scopes can potentially expose your Azure DevOps organization to security vulnerabilities or other risks. High privilege scopes grant extensive access to your organization's resources, making it essential to evaluate their necessity carefully. To better understand which scopes fall into the high privilege category, see the Supported scopes section of the [Extension manifest reference](../extend/develop/manifest.md). + +If you identify an extension with high privilege scopes, take the following actions: +- **Evaluate necessity**: Assess whether the requested scopes are essential for your use case +- **Avoid unnecessary risks**: If the extension's functionality doesn't justify the high privilege scopes, we recommend not installing or using the extension to safeguard your Azure DevOps environment + +> [!div class="mx-imgBorder"] +> ![Screenshot showing high privilege scope details for the extension.](media/high-privilege-extensions/details-scopes.png) + +You can also identify high privilege scopes flagged in the [Azure DevOps Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops). The Marketplace provides similar indications to those extensions shown in the admin page for high privilege scopes. + +When you select an extension with high privilege scopes, think critically about whether the extension's functionality justifies the use of these scopes. Only proceed with installation if you trust the publisher and the extension's code. + +> [!div class="mx-imgBorder"] +> ![Screenshot showing Azure DevOps' Visual Studio Marketplace acquisition screen for a high privilege extension.](media/high-privilege-extensions/acquisition-pipeline.png) + +> [!NOTE] +> This feature is being released gradually. If you don't see the high privilege scope insights in your [Azure DevOps Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops) user interface, wait a few more days until it becomes available for you too. + +## Discontinue use of unpublished extensions + +In the extension's administration page, extensions are visually marked to show whether they're unpublished by their publishers. + +When an extension is unpublished from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/) by its publisher, it typically signifies that the extension is no longer maintained. + +Discontinue the use of unpublished extensions by uninstalling them from your Azure DevOps organization. + +> [!div class="mx-imgBorder"] +> ![Screenshot showing high privilege extension details with unpublished status.](media/high-privilege-extensions/details-scopes.png) + +## Use pipeline decorators safely + +[Pipeline decorators](../extend/develop/add-pipeline-decorator.md) are private extensions that modify and enhance all pipelines within your organization. Use pipeline decorator extensions cautiously and only if you trust their publishers and code. + +> [!div class="mx-imgBorder"] +> ![Screenshot showing authorization screen for newly added scopes with pipeline decorator included.](media/high-privilege-extensions/auth-scopes.png) + +## Use the unpublished state field in the Azure DevOps Services REST API + +With the Azure DevOps Services REST API [version 7.2](/rest/api/azure/devops/extensionmanagement/installed-extensions/list?view=azure-devops-rest-7.2&tabs=HTTP#extensionstateflags&preserve-view=true), the string field `unpublished` is now available. This field allows you to programmatically identify extensions that are unpublished from the Visual Studio Marketplace. + +By using this field, you can build your own process of detecting and managing unpublished extensions within your Azure DevOps organization. + +## Related articles + +- [Make your Azure DevOps secure](../organizations/security/security-overview.md) +- [Publish extensions to the Visual Studio Marketplace](../extend/publish/overview.md) +- [Add pipeline decorators](../extend/develop/add-pipeline-decorator.md) +- [Reference the extension manifest](../extend/develop/manifest.md) diff --git a/docs/marketplace/media/browse-local-extensions-on-premises.png b/docs/marketplace/media/browse-local-extensions-on-premises.png new file mode 100644 index 00000000000..6e31065150a Binary files /dev/null and b/docs/marketplace/media/browse-local-extensions-on-premises.png differ diff --git a/docs/marketplace/media/disable-or-uninstall-extension.png b/docs/marketplace/media/disable-or-uninstall-extension.png index 6d1eac48b08..fe310ffd689 100644 Binary files a/docs/marketplace/media/disable-or-uninstall-extension.png and b/docs/marketplace/media/disable-or-uninstall-extension.png differ diff --git a/docs/marketplace/media/get-vsts-extensions/get-extension.png b/docs/marketplace/media/get-vsts-extensions/get-extension.png index 02e422b8e5e..222ac3d2dee 100644 Binary files a/docs/marketplace/media/get-vsts-extensions/get-extension.png and b/docs/marketplace/media/get-vsts-extensions/get-extension.png differ diff --git a/docs/marketplace/media/high-privilege-extensions/acquisition-pipeline.png b/docs/marketplace/media/high-privilege-extensions/acquisition-pipeline.png new file mode 100644 index 00000000000..00d3035eeba Binary files /dev/null and b/docs/marketplace/media/high-privilege-extensions/acquisition-pipeline.png differ diff --git a/docs/marketplace/media/high-privilege-extensions/acquisition-scopes-pipeline.png b/docs/marketplace/media/high-privilege-extensions/acquisition-scopes-pipeline.png new file mode 100644 index 00000000000..ee77a5b9726 Binary files /dev/null and b/docs/marketplace/media/high-privilege-extensions/acquisition-scopes-pipeline.png differ diff --git a/docs/marketplace/media/high-privilege-extensions/auth-pipeline.png b/docs/marketplace/media/high-privilege-extensions/auth-pipeline.png new file mode 100644 index 00000000000..e411f848b53 Binary files /dev/null and b/docs/marketplace/media/high-privilege-extensions/auth-pipeline.png differ diff --git a/docs/marketplace/media/high-privilege-extensions/auth-scopes.png b/docs/marketplace/media/high-privilege-extensions/auth-scopes.png new file mode 100644 index 00000000000..28f21f6ec03 Binary files /dev/null and b/docs/marketplace/media/high-privilege-extensions/auth-scopes.png differ diff --git a/docs/marketplace/media/high-privilege-extensions/details-scopes.png b/docs/marketplace/media/high-privilege-extensions/details-scopes.png new file mode 100644 index 00000000000..15cb45767cb Binary files /dev/null and b/docs/marketplace/media/high-privilege-extensions/details-scopes.png differ diff --git a/docs/marketplace/media/high-privilege-extensions/extension-list.png b/docs/marketplace/media/high-privilege-extensions/extension-list.png new file mode 100644 index 00000000000..5034505fa29 Binary files /dev/null and b/docs/marketplace/media/high-privilege-extensions/extension-list.png differ diff --git a/docs/marketplace/media/manage-extensions-on-premises.png b/docs/marketplace/media/manage-extensions-on-premises.png new file mode 100644 index 00000000000..08e3a3cd80b Binary files /dev/null and b/docs/marketplace/media/manage-extensions-on-premises.png differ diff --git a/docs/marketplace/media/manage-permissions/extensions-settings.png b/docs/marketplace/media/manage-permissions/extensions-settings.png index bca854551be..8c0937fbe16 100644 Binary files a/docs/marketplace/media/manage-permissions/extensions-settings.png and b/docs/marketplace/media/manage-permissions/extensions-settings.png differ diff --git a/docs/marketplace/media/on-premises-upload-extension.png b/docs/marketplace/media/on-premises-upload-extension.png new file mode 100644 index 00000000000..3433e4caa68 Binary files /dev/null and b/docs/marketplace/media/on-premises-upload-extension.png differ diff --git a/docs/marketplace/media/org-settings-select-extension.png b/docs/marketplace/media/org-settings-select-extension.png index 03ee65e97cc..20847e5c178 100644 Binary files a/docs/marketplace/media/org-settings-select-extension.png and b/docs/marketplace/media/org-settings-select-extension.png differ diff --git a/docs/marketplace/media/select-extensions-browse-marketplace.png b/docs/marketplace/media/select-extensions-browse-marketplace.png index 93385ccbbee..368fb007dc9 100644 Binary files a/docs/marketplace/media/select-extensions-browse-marketplace.png and b/docs/marketplace/media/select-extensions-browse-marketplace.png differ diff --git a/docs/marketplace/media/user-access-level.png b/docs/marketplace/media/user-access-level.png deleted file mode 100644 index 51ac5561b2d..00000000000 Binary files a/docs/marketplace/media/user-access-level.png and /dev/null differ diff --git a/docs/marketplace/request-extensions.md b/docs/marketplace/request-extensions.md index cdec6e029dd..8a731d2640c 100644 --- a/docs/marketplace/request-extensions.md +++ b/docs/marketplace/request-extensions.md @@ -7,7 +7,7 @@ ms.subservice: azure-devops-marketplace ms.assetid: 93a88b2c-559d-43ae-aaa9-e75ba33272fe ms.author: chcomley author: chcomley -ms.date: 10/06/2022 +ms.date: 03/03/2025 monikerRange: '<= azure-devops' --- @@ -15,123 +15,86 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -If you don't have permissions to install extensions, you can request extensions instead. -Project Collection Administrators receive an email when another project member requests an extension. Azure DevOps automatically installs the extension once it's approved. +If you don't have permissions to install extensions, you can request extensions instead. When another project member requests an extension, Project Collection Administrators receive an email notification. When a request gets approved, Azure DevOps automatically installs the extension. ## Prerequisites -- To request extensions, you must be a contributor for your organization. -- To approve extensions, you must be a member of the Project Collection Administrators group and have [**Edit collection-level information** permissions](../organizations/security/permissions.md#collection). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To request extensions: **Contributor** for your organization.
      - To approve extensions: Member of the **Project Collection Administrators** group and [**Edit collection-level information** permissions](../organizations/security/permissions.md#collection).| ## Request an extension ::: moniker range=" azure-devops" -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select ![gear icon](../media/icons/gear-icon.png) **Organization settings**. - ![Open Organization settings](../media/settings/open-admin-settings-vert.png) + ![Screenshot showing Organization settings button.](../media/settings/open-admin-settings-vert.png) -3. Select **Extensions**, and then **Browse marketplace**. +3. Select **Extensions** > **Browse marketplace**. - ![Select Extensions and Browse marketplace](media/select-extensions-browse-marketplace.png) + ![Screenshot showing Extensions and Browse marketplace buttons.](media/select-extensions-browse-marketplace.png) 4. Select an extension to install. -5. If you don't have permission to install the extension, you can request it now. +5. If you don't have permission to install the extension, you can request it. -Review your requests after the Marketplace sends the request to your Project Collection Administrator. + Review your requests after the Marketplace sends the request to your Project Collection Administrator. -Your requests appear on the **Extensions** page, **Requested** tab. + Your requests appear on the **Extensions** page, **Requested** tab. -![Requested tab for extensions](media/requested-extensions.png) + ![Screenshot showing the Requested tab for extensions.](media/requested-extensions.png) ::: moniker-end -::: moniker range="= azure-devops-2019 || azure-devops-2020" +::: moniker range="=azure-devops-2020" -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select ![gear icon](../media/icons/gear-icon.png) **Admin settings**. - ![Open Admin settings](../media/settings/open-admin-settings-server.png) + ![Screenshot showing Admin settings button.](../media/settings/open-admin-settings-server.png) -3. Select **Extensions**, and then **Browse Marketplace**. +3. Select **Extensions** > **Browse Marketplace**. - ![Select Browse Marketplace](media/browse-marketplace-2019.png) + ![Screenshot showing Browse Marketplace selection.](media/browse-marketplace-2019.png) 4. Select an extension to install. -5. If you don't have permission to install the extension, request it now. +5. If you don't have permission to install the extension, request it. -Review your requests after the Marketplace sends the request to your Project Collection Administrator. + Review your requests after the Marketplace sends the request to your Project Collection Administrator. -Your requests appear on the **Extensions** page, **Requested** tab. + Your requests appear on the **Extensions** page, **Requested** tab. -![Requested tab for extensions page](media/requested-extensions-2019.png) + ![Screenshot showing the Requested tab for extensions page.](media/requested-extensions-2019.png) ::: moniker-end -::: moniker range="tfs-2018" - -1. Select an extension from the [Visual Studio Marketplace > Azure DevOps](https://marketplace.visualstudio.com/azuredevops). - -2. Select the project collection where you want to install the extension. If you don't have permission to install the extension, request it now. - -You can review your requests after the Marketplace sends the request to your Project Collection or Project Administrator. - -Your requests appear on your **Manage extensions** page. - -![On the Extension page, a drop-down list to the right of the search window has two options, Browse Marketplace and Manage extensions (highlighted).](media/manage-extensions-vsts.png) - -::: moniker-end - -To approve extensions, you must have [**edit collection-level information** permissions](../organizations/security/permissions.md#collection). +To approve extensions, have [**edit collection-level information** permissions](../organizations/security/permissions.md#collection). ## Approve an extension request -::: moniker range=">= azure-devops-2019" - -1. Go to your Azure DevOps project, ```https://dev.azure.com/{organization}/{project}```. +1. Go to your Azure DevOps project, ```https://dev.azure.com/{Your_Organization}/{Your_Project}```. -1. Select the shopping bag icon, and then **Manage extensions**. +2. Select the shopping bag icon, and then **Manage extensions**. - ![Manage extensions](../organizations/billing/media/shared/marketplace-shopping-bag-manage-extensions.png) + ![Screenshot showing Manage extensions selection.](../organizations/billing/media/shared/marketplace-shopping-bag-manage-extensions.png) -2. Review and approve your requested extensions. +3. Review and approve your requested extensions. > [!div class="mx-imgBorder"] - > ![Extensions tab, requested extensions](media/get-tfs-extensions/connected/approve-request-tfs.png) + > ![Screenshot showing the Extensions tab, requested extensions.](media/get-tfs-extensions/connected/approve-request-tfs.png) After you approve extension requests, the extensions are automatically installed. -3. [Assign those extensions](./install-extension.md) to users who need access. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Go to your project, ```https://{server}:8080/tfs/{team-project-collection}/{team-project}```. - -1. Select the shopping bag icon, and then **Manage extensions**. - - ![On the Extension page, a drop-down list to the right of the search window has two options, Browse Marketplace and Manage extensions (highlighted)](../organizations/billing/media/shared/marketplace-shopping-bag-manage-extensions-prev-nav.png) - -2. Review and approve your requested extensions. - - > [!div class="mx-imgBorder"] - > ![Extensions tab, requested extensions](media/get-tfs-extensions/connected/approve-request-tfs.png) - - After you approve extension requests, the extensions automatically get installed. - -3. [Assign those extensions](./install-extension.md) to users who need access. - -::: moniker-end +4. [Assign the extensions](./install-extension.md) to users who need access. -Tell your team about installed extensions, so they can start using their capabilities. +Tell your team about your installed extensions, so they can start using their capabilities. ## Related articles -- [FAQs](faq-extensions.yml) -- [Set up billing](../organizations/billing/set-up-billing-for-your-organization-vs.md) -- [Azure DevOps pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) +- [Review FAQs](faq-extensions.yml) +- [Set up billing](../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing) +- [Explore Azure DevOps pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) - [Assign access levels by group membership](../organizations/accounts/assign-access-levels-by-group-membership.md) diff --git a/docs/media/add-new-users.png b/docs/media/add-new-users.png index fd80f7a6744..4597243dbaf 100644 Binary files a/docs/media/add-new-users.png and b/docs/media/add-new-users.png differ diff --git a/docs/media/connect-your-organization-to-azure-ad.png b/docs/media/connect-your-organization-to-azure-ad.png deleted file mode 100644 index 62b913ccaef..00000000000 Binary files a/docs/media/connect-your-organization-to-azure-ad.png and /dev/null differ diff --git a/docs/media/find-organization-owner.png b/docs/media/find-organization-owner.png index acd1abbdf64..119b2106820 100644 Binary files a/docs/media/find-organization-owner.png and b/docs/media/find-organization-owner.png differ diff --git a/docs/media/icons/add-team-member-plus-sign-blue.png b/docs/media/icons/add-team-member-plus-sign-blue.png new file mode 100644 index 00000000000..ea436662ef6 Binary files /dev/null and b/docs/media/icons/add-team-member-plus-sign-blue.png differ diff --git a/docs/media/icons/filter-icon.png b/docs/media/icons/filter-icon.png index ade06674c1f..fc3573e7309 100644 Binary files a/docs/media/icons/filter-icon.png and b/docs/media/icons/filter-icon.png differ diff --git a/docs/media/icons/link.png b/docs/media/icons/link.png new file mode 100644 index 00000000000..25d0ccc68e5 Binary files /dev/null and b/docs/media/icons/link.png differ diff --git a/docs/media/icons/save-icon.png b/docs/media/icons/save-icon.png new file mode 100644 index 00000000000..2157cb735ce Binary files /dev/null and b/docs/media/icons/save-icon.png differ diff --git a/docs/media/invite-github-users-policy.png b/docs/media/invite-github-users-policy.png index 60952a3e5e7..cca8ff098ae 100644 Binary files a/docs/media/invite-github-users-policy.png and b/docs/media/invite-github-users-policy.png differ diff --git a/docs/media/open-organization-settings-preview.png b/docs/media/open-organization-settings-preview.png index a84a6bc37b0..753263a6694 100644 Binary files a/docs/media/open-organization-settings-preview.png and b/docs/media/open-organization-settings-preview.png differ diff --git a/docs/media/open-organization-settings-users-preview.png b/docs/media/open-organization-settings-users-preview.png index 89ac4901cc3..ffe68ae6a4f 100644 Binary files a/docs/media/open-organization-settings-users-preview.png and b/docs/media/open-organization-settings-users-preview.png differ diff --git a/docs/media/open-organization-settings.png b/docs/media/open-organization-settings.png new file mode 100644 index 00000000000..fe0e251cd36 Binary files /dev/null and b/docs/media/open-organization-settings.png differ diff --git a/docs/media/organization-connected-azure-ad.png b/docs/media/organization-connected-azure-ad.png deleted file mode 100644 index 8ee05f8edf1..00000000000 Binary files a/docs/media/organization-connected-azure-ad.png and /dev/null differ diff --git a/docs/media/policies/security-policies.png b/docs/media/policies/security-policies.png index a7fd789fe8d..b8b77ed9732 100644 Binary files a/docs/media/policies/security-policies.png and b/docs/media/policies/security-policies.png differ diff --git a/docs/media/service-principal-service-connection.png b/docs/media/service-principal-service-connection.png new file mode 100644 index 00000000000..95f1a4ffb68 Binary files /dev/null and b/docs/media/service-principal-service-connection.png differ diff --git a/docs/media/settings/open-organization-settings-users-vert.png b/docs/media/settings/open-organization-settings-users-vert.png index 0a06ede7fd1..91cbab20eca 100644 Binary files a/docs/media/settings/open-organization-settings-users-vert.png and b/docs/media/settings/open-organization-settings-users-vert.png differ diff --git a/docs/media/settings/open-process-page-basic.png b/docs/media/settings/open-process-page-basic.png new file mode 100644 index 00000000000..673785ad795 Binary files /dev/null and b/docs/media/settings/open-process-page-basic.png differ diff --git a/docs/media/version-selector-minimize.png b/docs/media/version-selector-minimize.png index e1a8ace0d21..657c5bc8b23 100644 Binary files a/docs/media/version-selector-minimize.png and b/docs/media/version-selector-minimize.png differ diff --git a/docs/media/version-selector.png b/docs/media/version-selector.png index e1a8ace0d21..a33941f4c7b 100644 Binary files a/docs/media/version-selector.png and b/docs/media/version-selector.png differ diff --git a/docs/migrate/faqs.yml b/docs/migrate/faqs.yml deleted file mode 100644 index 7d79541d2e7..00000000000 --- a/docs/migrate/faqs.yml +++ /dev/null @@ -1,77 +0,0 @@ -### YamlMime:FAQ -metadata: - title: Migration and process model FAQs - description: Answers to frequently asked questions about process models post migration - titleSuffix: Azure DevOps - ms.subservice: azure-devops-migrate - ms.author: chcomley - author: chcomley - ms.topic: faq - monikerRange: '<= azure-devops' - "recommendations": "true" - ms.date: 04/01/2021 - - -title: Migration and process model FAQs - -summary: | - [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - - Find answers to frequently asked questions when migrating to Azure DevOps Services from on-premises. - - -sections: - - name: Single section - ignored - - questions: - - question: Why is my production import taking longer than the corresponding dry-run import of the same organization? - answer: | - During a production import, additional provisioning steps are undertaken to cement the organization into the Azure DevOps Services hosted environment. In contrast, the dry-run import of the same organization typically completes faster since dry-run organizations are temporary and thus do not require these additional steps. - - - question: Why is my dry-run import taking longer than previous dry-run imports of the same organization? - answer: | - Any dry-run import after the first is expected to take longer given the extra time required to clean up resources from previous dry-run attempts. - - - question: How long after deleting or renaming an existing dry-run organization will the name become available so another import can be queued? - answer: | - It can take up to one hour for an organization name to become available after deleting or renaming. - - - question: Does use of the Hosted XML process model pose a future risk in use of Azure DevOps Services? - answer: | - **No**. When it comes to service updates, Hosted XML organizations are treated the same as organizations using the Inheritance process model. - - - question: Will my organization be stuck in Hosted XML forever? - answer: | - **No**. You are using the Hosted XML process because the Inheritance process model doesn't contain all features yet. However, you can now [clone a hosted XML process to an Inheritance process](../organizations/settings/work/upgrade-hosted-to-inherited.md). - - - question: Will migrating from Hosted XML into Inheritance process model be a manual process? - answer: | - **No**. The migration is automated. Follow the steps to [clone a hosted XML process to an Inheritance process](../organizations/settings/work/upgrade-hosted-to-inherited.md). - - - question: What happens in Hosted XML when Microsoft makes a change to a system process? - answer: | - This is the same experience with Azure DevOps Server. If we make a change to a system process, it isn't applied to any of your Hosted XML processes. You won't have to update your processes if you don't want to. But if you do, you'll need to make the changes in the XML definition files manually for each process. - - - question: Is there a difference between a project that was created manually versus one that was created from data import? - - answer: | - The features available to each project are the same. The differences occur in how you modify the processes in your organization. When you create an organization, you'll use the [Inheritance process model](../organizations/settings/work/manage-process.md?toc=/azure/devops/reference/toc.json) to customize the work tracking experience. Team projects migrated via data import, however, will use the [Hosted XML process model](../organizations/settings/work/import-process/import-process.md?toc=/azure/devops/reference/toc.json) to customize the work tracking experience. As described previously, you can clone a Hosted XML process to an Inheritance process model after import. - - - question: If my organization is using Hosted XML, can I create new projects to use the Inheritance process model? - - answer: | - **Yes**. For data import organizations, Azure DevOps Services supports team projects that use Inheritance as well as Hosted XML process models. To learn more about the Inheritance process, see [Manage processes](../organizations/settings/work/manage-process.md?toc=/azure/devops/reference/toc.json). - - - question: Where can I find more information on Hosted XML and the Inheritance process model? - - answer: | - * [Inheritance Process Model](../organizations/settings/work/manage-process.md?toc=/azure/devops/reference/toc.json) - * [Hosted XML](../organizations/settings/work/import-process/import-process.md?toc=/azure/devops/reference/toc.json) - -additionalContent: | - ## Related articles - - [Migration overview](migration-overview.md) - - [Process template validation](migration-processtemplates.md) - - [Troubleshooting process errors](migration-processtemplates.md#dealing-with-process-errors) - - [Inheritance Process Model](../organizations/settings/work/manage-process.md?toc=/azure/devops/reference/toc.json) - - [Hosted XML](../organizations/settings/work/import-process/import-process.md?toc=/azure/devops/reference/toc.json) diff --git a/docs/migrate/media/migration-troubleshooting/conformProjectProcessesPowerShell.png b/docs/migrate/media/conform-project-processes-powershell.png similarity index 100% rename from docs/migrate/media/migration-troubleshooting/conformProjectProcessesPowerShell.png rename to docs/migrate/media/conform-project-processes-powershell.png diff --git a/docs/migrate/media/get-started-stage-migration-highres.png b/docs/migrate/media/get-started-stage-migration-highres.png new file mode 100644 index 00000000000..01afdfe93c0 Binary files /dev/null and b/docs/migrate/media/get-started-stage-migration-highres.png differ diff --git a/docs/migrate/media/import-spec-after.png b/docs/migrate/media/import-spec-after.png new file mode 100644 index 00000000000..190a74b63aa Binary files /dev/null and b/docs/migrate/media/import-spec-after.png differ diff --git a/docs/migrate/media/import-spec-before.png b/docs/migrate/media/import-spec-before.png new file mode 100644 index 00000000000..00d705f4266 Binary files /dev/null and b/docs/migrate/media/import-spec-before.png differ diff --git a/docs/migrate/media/import-spec-iaas.png b/docs/migrate/media/import-spec-iaas.png new file mode 100644 index 00000000000..6bde8e7a666 Binary files /dev/null and b/docs/migrate/media/import-spec-iaas.png differ diff --git a/docs/migrate/media/migrate-stage-migration-highres.png b/docs/migrate/media/migrate-stage-migration-highres.png new file mode 100644 index 00000000000..7b6f92016c0 Binary files /dev/null and b/docs/migrate/media/migrate-stage-migration-highres.png differ diff --git a/docs/migrate/media/migration-import/ImportSpecFillOutNoType.png b/docs/migrate/media/migration-import/ImportSpecFillOutNoType.png index 577c67bb21f..ca8acecfd38 100644 Binary files a/docs/migrate/media/migration-import/ImportSpecFillOutNoType.png and b/docs/migrate/media/migration-import/ImportSpecFillOutNoType.png differ diff --git a/docs/migrate/media/migration-import/example.png b/docs/migrate/media/migration-import/example.png index 84caa8c85f9..ac90f55aad3 100644 Binary files a/docs/migrate/media/migration-import/example.png and b/docs/migrate/media/migration-import/example.png differ diff --git a/docs/migrate/media/migration-import/identityMapNewlyGenerated.png b/docs/migrate/media/migration-import/identityMapNewlyGenerated.png index 0651ad111e3..4d96cf68d2c 100644 Binary files a/docs/migrate/media/migration-import/identityMapNewlyGenerated.png and b/docs/migrate/media/migration-import/identityMapNewlyGenerated.png differ diff --git a/docs/migrate/media/migration-import/importSpecAfter.png b/docs/migrate/media/migration-import/importSpecAfter.png deleted file mode 100644 index a01c180a944..00000000000 Binary files a/docs/migrate/media/migration-import/importSpecAfter.png and /dev/null differ diff --git a/docs/migrate/media/migration-import/importSpecBefore.png b/docs/migrate/media/migration-import/importSpecBefore.png deleted file mode 100644 index 7194b715849..00000000000 Binary files a/docs/migrate/media/migration-import/importSpecBefore.png and /dev/null differ diff --git a/docs/migrate/media/migration-import/importSpecCompleted.png b/docs/migrate/media/migration-import/importSpecCompleted.png deleted file mode 100644 index ac6c4f00cc3..00000000000 Binary files a/docs/migrate/media/migration-import/importSpecCompleted.png and /dev/null differ diff --git a/docs/migrate/media/migration-import/importSpecHalfFilledOut.png b/docs/migrate/media/migration-import/importSpecHalfFilledOut.png index 811951738d2..e2afa66322d 100644 Binary files a/docs/migrate/media/migration-import/importSpecHalfFilledOut.png and b/docs/migrate/media/migration-import/importSpecHalfFilledOut.png differ diff --git a/docs/migrate/media/migration-import/importSpecIaaS.png b/docs/migrate/media/migration-import/importSpecIaaS.png deleted file mode 100644 index 7c8ad8440c6..00000000000 Binary files a/docs/migrate/media/migration-import/importSpecIaaS.png and /dev/null differ diff --git a/docs/migrate/media/migration-import/importSpecNotFilledOut.png b/docs/migrate/media/migration-import/importSpecNotFilledOut.png deleted file mode 100644 index 25bce8768b9..00000000000 Binary files a/docs/migrate/media/migration-import/importSpecNotFilledOut.png and /dev/null differ diff --git a/docs/migrate/media/migration-post-import/UserSummary.png b/docs/migrate/media/migration-post-import/UserSummary.png deleted file mode 100644 index 23849c701ec..00000000000 Binary files a/docs/migrate/media/migration-post-import/UserSummary.png and /dev/null differ diff --git a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-ab-test.png b/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-ab-test.png deleted file mode 100644 index 1deb136a32d..00000000000 Binary files a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-ab-test.png and /dev/null differ diff --git a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-admin.png b/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-admin.png deleted file mode 100644 index 66cd148a6dd..00000000000 Binary files a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-admin.png and /dev/null differ diff --git a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-all-or-nothing.png b/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-all-or-nothing.png deleted file mode 100644 index cf2d0e55fa0..00000000000 Binary files a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-all-or-nothing.png and /dev/null differ diff --git a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-feature-flag.png b/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-feature-flag.png deleted file mode 100644 index 10ec9d850e8..00000000000 Binary files a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-feature-flag.png and /dev/null differ diff --git a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-ld-azure-fx.png b/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-ld-azure-fx.png deleted file mode 100644 index b0c6f831034..00000000000 Binary files a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-ld-azure-fx.png and /dev/null differ diff --git a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-user-group.png b/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-user-group.png deleted file mode 100644 index ab5db11fe5e..00000000000 Binary files a/docs/migrate/media/phase-features-with-ff/phase-features-with-ff-user-group.png and /dev/null differ diff --git a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-app-layer.png b/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-app-layer.png deleted file mode 100644 index 3f6747f5f5d..00000000000 Binary files a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-app-layer.png and /dev/null differ diff --git a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-dash.png b/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-dash.png deleted file mode 100644 index bd648abf23e..00000000000 Binary files a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-dash.png and /dev/null differ diff --git a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-early-approval.png b/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-early-approval.png deleted file mode 100644 index f285e16ce0b..00000000000 Binary files a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-early-approval.png and /dev/null differ diff --git a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-feature-flags.png b/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-feature-flags.png deleted file mode 100644 index d2b179d9501..00000000000 Binary files a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-feature-flags.png and /dev/null differ diff --git a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-inf-layer.png b/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-inf-layer.png deleted file mode 100644 index 34f1b9032c0..00000000000 Binary files a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-inf-layer.png and /dev/null differ diff --git a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-pipeline.png b/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-pipeline.png deleted file mode 100644 index de7352f2e12..00000000000 Binary files a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-pipeline.png and /dev/null differ diff --git a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-rings.png b/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-rings.png deleted file mode 100644 index 19f4720f85d..00000000000 Binary files a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-rings.png and /dev/null differ diff --git a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-users-approval.png b/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-users-approval.png deleted file mode 100644 index f7b415c0f4e..00000000000 Binary files a/docs/migrate/media/phase-rollout-with-rings/phase-rollout-with-rings-users-approval.png and /dev/null differ diff --git a/docs/migrate/media/post-migration-stage-migration-highres.png b/docs/migrate/media/post-migration-stage-migration-highres.png new file mode 100644 index 00000000000..ccda7660c2a Binary files /dev/null and b/docs/migrate/media/post-migration-stage-migration-highres.png differ diff --git a/docs/migrate/media/prepare-test-run-stage-migration-highres.png b/docs/migrate/media/prepare-test-run-stage-migration-highres.png new file mode 100644 index 00000000000..924a32bf3a4 Binary files /dev/null and b/docs/migrate/media/prepare-test-run-stage-migration-highres.png differ diff --git a/docs/migrate/media/prerequisites-stage-migration-highres.png b/docs/migrate/media/prerequisites-stage-migration-highres.png new file mode 100644 index 00000000000..c1accc3b381 Binary files /dev/null and b/docs/migrate/media/prerequisites-stage-migration-highres.png differ diff --git a/docs/migrate/media/test-run-stage-migration-highres.png b/docs/migrate/media/test-run-stage-migration-highres.png new file mode 100644 index 00000000000..52fbe13e32c Binary files /dev/null and b/docs/migrate/media/test-run-stage-migration-highres.png differ diff --git a/docs/migrate/media/validate-stage-migration-highres.png b/docs/migrate/media/validate-stage-migration-highres.png new file mode 100644 index 00000000000..68f57696cf2 Binary files /dev/null and b/docs/migrate/media/validate-stage-migration-highres.png differ diff --git a/docs/migrate/media/migration-troubleshooting/witLogFile.png b/docs/migrate/media/wit-log-file.png similarity index 100% rename from docs/migrate/media/migration-troubleshooting/witLogFile.png rename to docs/migrate/media/wit-log-file.png diff --git a/docs/migrate/migrate-from-tfs.md b/docs/migrate/migrate-from-tfs.md deleted file mode 100644 index 22217014618..00000000000 --- a/docs/migrate/migrate-from-tfs.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Migrate from Azure DevOps on-premises to Azure DevOps Services -titleSuffix: Azure DevOps -description: Learn about migrating from Azure DevOps Server to Azure DevOps Services -ms.topic: conceptual -ms.subservice: azure-devops-migrate -ms.assetid: 3D20B6AC-E8A8-4A6D-B9D8-68ED2F5E0E8D -ms.author: chcomley -author: chcomley -ms.date: 06/22/2017 -monikerRange: '<= azure-devops' ---- - - -# Migration options - -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - -When you decide to make the move from Azure DevOps Server to Azure DevOps Services, you might start fresh with an empty organization. Often, however, -you will have existing code, work items, and other assets that you want to move. There are many approaches to doing this -which vary in both the fidelity of the data transfer and the complexity of the process. - -Prior to migrating data, review the differences that exist between [Azure DevOps Server and Azure DevOps Services](../user-guide/about-azure-devops-services-tfs.md). - -## Option 1: Copy the most important assets manually - -By far the easiest option for moving data into Azure DevOps Services is to manually copy your most important assets and start relatively fresh. -This can be difficult when you are in the middle of a large project, but you can make it easier if you do some advance planning -and schedule your move when it makes sense for your team. - -For example, when the Azure DevOps team chose to move from Azure DevOps Server to Azure DevOps Services, we also decided to -move from Team Foundation Version Control (TFVC) to Git. This required a fair bit of planning, but when we actually -performed our migration, we created a new Git repo using the "tip" version of our TF VC sources, and left our history -behind in Azure DevOps Server. We also moved our active work items, and left behind all our old bugs, completed user stories and tasks, -and so on. - -Here's the general process: - -1. Identify the most important assets that you need to migrate - typically source code, work items, or both. Other assets in Azure DevOps Server - -build pipelines, test plans, and so forth - are harder to manually migrate. -2. Identify a good time to make the transition. -3. Prepare your target organizations. Create the organizations and team projects that you need, provision users, and so on. -4. Migrate your data. -5. Consider making the source Azure DevOps Server deployments read-only. - -## Option 2: High fidelity database migration. - -The Azure DevOps Server & Azure DevOps Services product team provides a high fidelity data migration tool. A downloadable Migration -Guide is available at [https://aka.ms/AzureDevOpsImport](https://aka.ms/AzureDevOpsImport). - - -Migration Guide - - -Because the data migration tool operates at a database level, it can provide a very high fidelity migration. -If you want to move your existing Azure DevOps Server data into Azure DevOps Services, we strongly recommend using this option. - -## Option 3: Using public API-based tools for higher fidelity migration - -If for some reason you cannot use the data migration tool but still want a higher fidelity migration than -Option 1, you can choose from a variety of tools that use public APIs to move data. Generally these tools can provide -a higher fidelity migration than a manual copy of "tip" data, but they are still relatively low fidelity. For example: - -- None of them will preserve the dates of TF VC changesets. -- Many of them will not preserve the changed dates of work item revisions. -- None of them will migrate all Azure DevOps Server artifacts. - -In general, we only recommend this approach if the extra fidelity beyond a manual copy is critical. If you decide to -take this approach, you might consider hiring a consultant who has experience with one or more of the tools. -You should definitely consider doing a test migration before doing your final migration. - -Many organizations need a very high fidelity migration for only a subset of their work. New work could -potentially start directly in Azure DevOps Services. Other work, with less stringent fidelity requirements, -could be migrated using one of the other approaches. You will have to weigh the pros and cons of the -various approaches against your motivations for moving into Azure DevOps Services and decide for yourself what -is the right strategy. - - -## Related articles - -- [About Azure DevOps Services and Azure DevOps Server](../user-guide/about-azure-devops-services-tfs.md) -- [Pricing, Azure DevOps Services](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) -- [Pricing, Azure DevOps Server](https://visualstudio.microsoft.com/team-services/tfs-pricing/) - - - - diff --git a/docs/migrate/migration-get-started.md b/docs/migrate/migration-get-started.md new file mode 100644 index 00000000000..2dcded7d7bd --- /dev/null +++ b/docs/migrate/migration-get-started.md @@ -0,0 +1,124 @@ +--- +title: Get started with Azure DevOps Data Migration Tool +description: Overview of the high fidelity migration process from on-premises Server to cloud Azure DevOps Services. +ms.topic: how-to +ms.subservice: azure-devops-migrate +ms.contentid: +ai-usage: ai-assisted +ms.author: chcomley +author: chcomley +monikerRange: '<= azure-devops' +ms.date: 05/20/2024 +--- + +# Get started with Azure DevOps Data Migration Tool + +Before you use the [Azure DevOps Data Migration Tool](https://www.microsoft.com/download/details.aspx?id=54274) to migrate your database with high fidelity, learn some of the basic concepts in this article. + +:::image type="content" source="media/get-started-stage-migration-highres.png" alt-text="Diagram highlighting the Get started stage in sequential stages."::: + +## Learn which data gets migrated + +Not all data gets migrated. Separate databases outside the collection, for example, reporting and SharePoint data, don’t get migrated. The following sections list more detail about which data gets migrated. + +### Included data + +The following table shows data included in migration. + +|Included data |Description | +|---------|---------| +|Collection mapping |Each collection in Azure DevOps Server corresponds to one database. During migration, the whole collection—including work items, history, Team Foundation Version Control (TFVC) changesets, Git data, build definitions, and more—get migrated to Azure DevOps Services. Work item, TFVC changeset, and Git commit numbers/IDs remain unchanged. | + +### Excluded data + + The following table shows specific data exclusions in migration. + +|Excluded data | Description | +|-----------------|----------| +|Extensions | Extensions must be reinstalled post-migration. You should publish local extensions to the Marketplace as private extensions and shared with the account. | +|Service Hooks |Service Hooks data isn’t included in the migration; reconfigure after migration. | +|Load test |Load test data isn’t brought over; reconfigure load tests after migration. | +|Pipeline agents and agent pools | Reconfigure pipeline agents and agent pools after migration. | +|Mentions | User mentions in work item discussions retain on-premises identity, not the new Microsoft Entra ID. Hovering on usernames doesn’t display contact cards, and some hyperlinks might be invalid. | +|Project Server integrations | Not available for Azure DevOps Services. For example, XAML Builds, Microsoft Test Manager, SharePoint, SQL Data Warehouse, and so on. | +|Preview features | Some Azure DevOps Server features can be previewed during migration to Azure DevOps Services. | + +## Project limits + +If your collection contains numerous projects, Azure DevOps Services imposes a limit of 1,000 projects per organization, although we recommend 300 or less. Beyond this threshold, certain experiences—such as connecting to the organization from Visual Studio—might degrade. To stay within the limit, consider either splitting the collection or deleting older projects. + +## Understand the relationship between on-premises databases and Azure DevOps organizations. + +Before you dive too deeply into planning your migration, it’s important to understand at an elevated level how the database migration process functions. Migrations operate on the following main concepts: + +- **Team Project Collection**: Collections in Azure DevOps Server are a physical container for team projects and their artifacts. Each collection equates to a single SQL database and is the source of migrations to Azure DevOps Services. +- **Azure DevOps Services organization**: Organizations are the management unit in the cloud-hosted service. Logically they map 1:1 to the concept of a team project collection in Azure DevOps Server. Therefore, organizations are the destination of migrations to Azure DevOps Services. For example, Azure DevOps Services organizations are represented as `https://dev.azure.com/Contoso` where Contoso represents the name of the Azure DevOps Services organization. + +When you migrate a team project collection SQL database, the Data Migration Tool creates a new Azure DevOps organization with a user-provided name. Migrating a collection database into an existing Azure DevOps Services organization or consolidating multiple collection databases into a single Azure DevOps Services organization isn't possible. The mapping is strictly one-to-one between team project collections and Azure DevOps Services organizations. + +## Choose data center + +When you set up your Azure DevOps Services organization, you can choose the location for your data. During initial sign-up and organization creation, select a region that suits your needs. To use later for migration, make a note of the region’s shorthand code. For more information, see Supported regions for migration. + +## Understand pricing + +A question that typically comes up with migration is what type of licensing a company needs to use Azure DevOps Services. The good news is you're likely to have all the licenses you already need. We created an example worksheet that should cover most cases. If you have any specific questions about your situation, reach out to your Developer Solution Sales Specialist or Microsoft Reseller. For more information, see Pricing for Azure DevOps. + +### User licenses worksheet + +|#|Column 1 |Column 2 | +||---------|---------| +|1|Number of team members | | +|2|Number of stakeholders | | +|3|Subtract the value in line 2 from the value in line 1* | | +|4|# of Visual Studio subscribers** | | +|5|Subtract the value in line 4 from the value in line 3 | | +|6|Subtract the value in line 5 from the value in line 5*** | | + +- *Stakeholders are free +- ** Visual Studio Subscribers have Azure DevOps Services included as a benefit of the subscription +- ***Each Azure DevOps Services organization gets five free users + +For more information about cost-effective options for accessing features, see the [Billing overview](../organizations/billing/overview.md) and the [Azure Pricing Calculator](https://azure.microsoft.com/pricing/calculator/?service=azure-devops). + +Buy any needed Azure DevOps Services user licenses through the Visual Studio Marketplace or the Azure portal. We delve into this process during the [Prepare for test run phase](migration-prepare-test-run.md). + +In addition to the core features, the following value-added services are available in Azure DevOps that you might find beneficial: + +- Hosted load testing services: If you need to simulate and analyze the performance of your applications under load, Azure DevOps provides hosted load testing services. These services allow you to stress-test your applications and identify bottlenecks or performance issues. +- Test Manager extensions: For comprehensive test management, consider using Test Manager extensions. These extensions enhance your testing capabilities by providing features like test case management, exploratory testing, and test execution tracking. +- More features: Azure DevOps offers various extensions and integrations that cater to specific needs. Whether it’s integrating with non-Microsoft tools, enhancing security, or automating deployment pipelines, there's a wide range of options. + +Some of these services might come with extra costs, so it’s essential to evaluate your requirements and budget accordingly. These costs appear on your bill under the associated subscription. For more information, see [Set up billing](../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing). If you have specific questions about your situation, contact your DevOps Partner, Microsoft Reseller, or your Microsoft Developer Solutions Sales Specialist for personalized guidance. + +## Reserve your new organization + +Considering the migration project’s timeline, we recommend that you reserve the name of your organization early on to ensure that your desired name is available for your final migration. + +For instance, if your company is Contoso and you want an organization with a matching name, for example, `https://dev.azure.com/contoso`, you can create an organization with that name now. But keep in mind that you can only migrate into a brand-new Azure DevOps Services organization. + +Do the following steps to reserve your organization name. + +1. Initial reservation: + 1. Create an organization with a temporary name, for example, `https://dev.azure.com/contoso-temporary`. + 2. Reserve this temporary name for your future migration. +2. Final migration: + 1. When you’re ready to begin the final migration, perform it into the `https://dev.azure.com/contoso-temporary` organization. + 2. After successful migration, rename the reserved organization to open your desired name for the imported organization. Rename it rather than deleting it because a deletion can take up to an hour to release the name, when renaming it's immediate. + 3. Immediately rename the migrated organization to the desire name, for example, `https://dev.azure.com/contoso`, that you just cleared by renaming. + 4. Optionally, you can delete the originally reserved and renamed organization at this point. + +By following this approach, you have a smooth transition while ensuring your preferred organization name remains available. + +## Next steps + +> [!div class="nextstepaction"] +> [Complete prerequisites for migration](migration-prerequisites.md) + +## Related articles + +- [Validate and prepare for migration](migration-validate.md) +- [Prepare for test run](migration-prepare-test-run.md) +- [Do test run migration](migration-test-run.md) +- [Migrate to Azure DevOps Services](migration-migrate.md) +- [Complete post-migration tasks](migration-post-migration.md) diff --git a/docs/migrate/migration-import-large-collections.md b/docs/migrate/migration-import-large-collections.md deleted file mode 100644 index 5e1642d36fb..00000000000 --- a/docs/migrate/migration-import-large-collections.md +++ /dev/null @@ -1,334 +0,0 @@ ---- -title: Import process for large collections from Azure DevOps on-premises -titleSuffix: Azure DevOps -description: How to guide for importing a large collection to the cloud -ms.topic: how-to -ms.subservice: azure-devops-migrate -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 10/07/2021 ---- - -# Import large collections - -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - - - - -For databases that the data migration tool warns are too large, a different data packaging approach is required to migrate to Azure DevOps Services. If you're unsure whether your collection exceeds the size threshold, you should run a data migration tool validation on the collection. The validation lets you know whether you need to use the SQL Azure VM method for import. - -## Determine if you can reduce the collection size - -Before you proceed, we recommend checking to see whether your [old data can be cleaned up](/azure/devops/server/upgrade/clean-up-data). Over time, collections can build up large volumes of data. This growth is a natural part of the DevOps process, but you might find that you don't need to retain all of the data. Some common examples of no longer relevant data are older workspaces and build results. - -Cleaning older, no-longer-relevant artifacts could remove a lot more space than you might expect, and it could determine whether you use the DACPAC import method or a SQL Azure VM. - -> [!IMPORTANT] -> After you've deleted older data, it *can't* be recovered unless you restore an older backup of the collection. - -If you're under the DACPAC threshold, follow the instructions to [generate a DACPAC](migration-import.md#dacpac-file) for import. If you still can't get the database under the DACPAC threshold, you need to set up a SQL Azure VM to import to Azure DevOps Services. - -## Set up a SQL Azure VM to import to Azure DevOps Services - -Let's walk through how to accomplish this. At a high level, you'll: - -* Set up a SQL Azure VM. -* (Optional) Restrict access to Azure DevOps Services IPs only. -* Configure IP firewall exceptions. -* Restore your database on the VM. -* Configure your collection for import. -* Configure the import specification file to target the VM - -## Set up a SQL Azure VM - -You can set up a SQL Azure VM from the Azure portal with just a few clicks. To learn how, see [Use the Azure portal to provision a Windows virtual machine with SQL Server](/azure/azure-sql/virtual-machines/windows/create-sql-vm-portal). - -> [!NOTE] -> While setting up your SQL Azure VM, bear in mind that the performance of the VM and attached data disks will have a significant impact on the performance of the import. For this reason, we *highly* recommend: -> - Selecting a VM Size at the level of D8s_v5_* or greater -> - Using managed disks -> - Consulting [Virtual machine and disk performance](/azure/virtual-machines/disks-performance). Please ensure your infrastructure is configured so that neither the VM IOPS or storage IOPS become a bottleneck on the performance of the import. For example, ensuring the number of data disks attached to your VM is sufficient to support the IOPS from the VM. - -Azure DevOps Services is available in several Azure regions across the globe. These can be seen in the table below. - -> [!IMPORTANT] -> To ensure that the import starts successfully, it's critical to place your data in the correct region. If you set up your SQL Azure VM in a location other than the regions listed in the following table, the import will fail to start. - -If you're using this import method, determine where to create your SQL Azure VM by referring to the following table. Creating your VM in a region other than those in this list is not supported for running an import. - -| Desired import region | SQL Azure VM region | -| --- | --- | -| Central United States | Central US | -| Western Europe | West Europe | -| Australia East | Australia East | -| Brazil South | Brazil South | -| South India | South India | -| Central Canada | Canada Central | -| Asia Pacific | Southeast Asia (Singapore) | -| UK South | UK South | - -
      - -Although Azure DevOps Services is available in multiple regions in the US, only the Central United States region accepts new organizations. Companies can't import their data into other US Azure regions at this time. - -> [!NOTE] -> DACPAC customers should consult the region table in the ["Step 3: Upload the DACPAC file" section](migration-import.md#step-3-upload-the-dacpac-file). The preceding guidelines are for SQL Azure VMs only. - -Here are a few more SQL Azure VM configurations that we recommend: -- [Configure the SQL temporary database](/sql/relational-databases/databases/move-system-databases#Examples) to use a drive other than drive C. Ideally the drive should have ample free space; at least equivalent to your database's [largest table](migration-import.md#step-2-generate-a-dacpac-file). -- If your source database is still over 1 terabyte (TB) after you've [reduced its size](/azure/devops/server/upgrade/clean-up-data), you need to [attach additional 1-TB disks](/azure/virtual-machines/windows/attach-disk-portal) and combine them into a single partition to restore your database on the VM. -- If your collection databases are over 1 TB in size, consider using an SSD for both the temporary database and collection database. Also, consider using larger VMs with 16 virtual CPUs (vCPUs) and 128 GB of RAM. -- You need to have a public facing IP address for the service to reach this machine. - - - -## (Optional) Restrict access to Azure DevOps Services IPs only - -We highly recommend that you restrict access to your VM to only IPs from Azure DevOps Services. You do this by allowing connections only from the set of Azure DevOps Services IPs that are involved in the collection database import process. The IPs that need to be granted access to your collection database depend on the region you're importing into. The following tables can help you identify the correct IPs. The only port that's required to be opened to connections is the standard SQL connection port 1433. - -First, no matter what Azure DevOps Services region you import into, you must grant the following IP addresses access to your collection database. - -> [!NOTE] -> In the following table, the two IP addresses listed with x.x.x.0/23 indicate a range. Allow the entire /23 range. For example, if you're importing into the Central United States region, allow the /23 range for 20.37.158.0. For IP addresses with x.x.x.0/24, allow the /24 range. - -| Service | IP address | -| --- | --- | -| Azure DevOps Services Identity Service | 168.62.105.45, 40.81.42.115 | - -
      - -Next, grant access to the Regional Identity Service. You need to grant an exception for the data migration tool instance only in the region that you're importing into. - -| Service | IP address | -| --- | --- | -| Regional Identity Service - Central United States | 13.89.236.72, 52.165.41.252, 52.173.25.16, 13.86.38.60, 20.45.1.175, 13.86.36.181, 52.154.53.1, 52.158.209.56, 20.37.138.122, 20.37.158.0/23, 20.37.139.247, 20.37.158.5 | -| Regional Identity Service - West Europe | 20.67.123.240, 52.166.54.85, 13.95.233.212, 52.236.145.119, 52.142.235.223, 52.236.147.103, 23.97.221.25, 52.233.181.148, 52.149.110.153, 51.144.61.32, 52.236.147.236, 40.74.28.0/23 | -| Regional Identity Service - Australia East | 13.75.145.145, 40.82.217.103, 20.188.213.113, 104.210.88.194, 40.81.62.114, 20.37.194.0/24 | -| Regional Identity Service - Brazil South | 20.40.114.3, 191.235.90.183, 191.232.38.181, 191.233.25.175, 191.235.226.0/24 | -| Regional Identity Service - India South | 104.211.227.29, 40.81.75.130, 52.172.54.122, 52.172.49.252, 20.41.194.0/24 | -| Regional Identity Service - Canada Central | 52.237.19.6, 40.82.190.38, 52.228.82.0/243 | -| Regional Identity Service - Asia Pacific (Singapore) | 20.195.68.0/24 | -| Regional Identity Service - UK South | 40.81.159.67, 51.104.26.0/24 | - -
      - -Next, grant access to the data migration tool for Azure DevOps itself. You need to grant an exception for the data migration tool instance only in the region that you're importing into. - -| Service | IP address | -| --- | --- | -| Data migration tool - Central United States | 52.173.74.9, 52.165.184.188, 20.45.1.234, 13.86.39.123 | -| Data migration tool - West Europe | 40.115.43.138, 13.95.15.128, 52.236.146.105, 40.67.219.89, 40.119.145.63, 52.142.236.228, 52.142.238.75 | -| Data migration tool - Australia East | 13.75.134.204, 40.82.219.41, 20.40.124.19 | -| Data migration tool - Brazil South | 104.41.24.164, 20.40.115.123 | -| Data migration tool - India South | 13.71.120.31, 40.81.76.137 | -| Data migration tool - Canada Central | 52.237.18.100, 52.237.24.61, 40.82.191.163 | -| Data migration tool - Asia Pacific (Singapore) | 20.195.68.0/24 | -| Data migration tool - UK South | 40.81.153.223, 51.105.8.98, 51.104.26.2 | - -
      - -Next, grant Azure DevOps Services access. Again, you need to grant an exception for the Azure DevOps Services instance only in the region that you're importing into. - -| Service | IP address | -| --- | --- | -| Azure DevOps Services - Central United States | 13.89.236.72, 52.165.41.252, 52.173.25.16, 13.86.38.60, 20.45.1.175, 13.86.36.181, 52.158.209.56 | -| Azure DevOps Services - West Europe | 52.166.54.85, 13.95.233.212, 52.236.145.119, 52.142.235.223, 52.236.147.103, 23.97.221.25, 52.233.181.148, 52.149.110.153, 51.144.61.32, 52.236.147.236 | -| Azure DevOps Services - Australia East | 13.75.145.145, 40.82.217.103, 20.188.213.113, 104.210.88.194, 40.81.62.114 | -| Azure DevOps Services - Brazil South | 20.40.114.3, 191.235.90.183, 191.232.38.181, 191.233.25.175 | -| Azure DevOps Services - India South | 104.211.227.29, 40.81.75.130, 52.172.54.122, 52.172.49.252 | -| Azure DevOps Services - Canada Central | 52.237.19.6, 40.82.190.38 | -| Azure DevOps Services - Asia Pacific (Singapore) | 20.195.68.0/24 | -| Azure DevOps Services - UK South | 40.81.159.67, 51.105.8.98, 51.104.26.2, 51.104.26.5 | - -
      - -Next, grant Azure Pipelines Releases service access. You need to grant an exception for the Azure DevOps Services instance only in the region that you're importing into. - -**Release Management IPs** - -| Service | IP address | -| --- | --- | -| Releases service - United States | 23.102.153.83, 23.101.127.247, 23.100.85.250, 13.86.39.233, 40.80.217.53, 52.232.229.122 | -| Releases service - West Europe | 13.95.223.69, 104.45.64.13 | -| Releases service - Australia East | 13.73.204.151, 20.40.176.135 | -| Releases service - Brazil South | 191.235.94.154, 20.40.116.69 | -| Releases service - India South | 52.172.15.233, 40.81.79.60 | -| Releases service - Canada Central | 52.237.28.171, 40.82.189.127 | -| Releases service - Asia Pacific (Singapore) | 20.195.68.0/24 | -| Releases service - UK South | 40.81.156.207 | - -
      - -Next, grant Azure Artifacts access. Again, you need to grant an exception for the Azure DevOps Services instance only in the region that you're importing into. - -**Azure Artifacts IPs** - -Add exceptions for all three services that make up Azure Artifacts. - -| Service | IP address | -| --- | --- | -| Azure Artifacts - United States | 52.173.148.93, 104.43.253.181, 23.99.179.148, 40.80.222.154, 40.119.0.130, 40.119.0.139, 13.86.125.169, 20.41.44.47, 40.90.219.165 | -| Azure Artifacts - West Europe | 104.46.45.12, 52.236.148.212 | -| Azure Artifacts - Australia East | 13.73.100.166, 20.40.176.15, 40.81.59.69 | -| Azure Artifacts - Brazil South | 191.234.179.224, 20.40.115.214 | -| Azure Artifacts - India South | 52.172.11.191, 40.81.74.79 | -| Azure Artifacts - Canada Central | 52.237.24.224, 40.85.224.121, 13.71.189.199, 40.82.188.122 | -| Azure Artifacts - Asia Pacific (Singapore) | 20.195.68.0/24 | -| Azure Artifacts - UK South | 51.145.120.132 | - -
      - -| Service | IP address | -| --- | --- | -| Azure Artifacts Feed - United States | 52.173.251.89, 20.45.1.3, 40.67.190.224, 20.41.58.125, 40.119.1.14, 20.45.1.249 | -| Azure Artifacts Feed - West Europe | 40.118.19.43, 52.236.146.118 | -| Azure Artifacts Feed - Australia East | 13.70.143.138, 20.40.176.80 | -| Azure Artifacts Feed - Brazil South | 191.235.93.87, 20.40.116.17 | -| Azure Artifacts Feed - India South | 52.172.8.41,40.81.79.49 | -| Azure Artifacts Feed - Canada Central | 52.237.19.70, 40.82.188.254 | -| Azure Artifacts Feed - Asia Pacific (Singapore) | 20.195.68.0/24 | -| Azure Artifacts Feed - UK South | 51.145.120.49 | - -
      - -| Service | IP address | -| --- | --- | -| Azure Artifacts Blob - United States | 70.37.94.103, 40.78.129.25, 40.67.155.236, 52.230.216.163, 20.45.3.51 | -| Azure Artifacts Blob - West Europe | 23.97.221.25 | -| Azure Artifacts Blob - Australia East | 40.127.86.30, 20.188.213.113, 40.82.221.14 | -| Azure Artifacts Blob - Brazil South | 191.235.90.183 | -| Azure Artifacts Blob - India South | 52.172.54.122 | -| Azure Artifacts Blob - Canada Central | 52.237.16.145, 52.237.16.145, 52.233.38.115, 40.82.187.186 | -| Azure Artifacts Blob - Asia Pacific (Singapore) | 20.195.68.0/24 | -| Azure Artifacts Blob - UK South | 51.143.174.59, 40.81.152.41 | - -
      - -**Test Plans IPs** - -Add exceptions for Test Plans IP addresses only in the region you're migrating into. - -| Service | IP address | -| --- | --- | -| Test Plans - United States | 52.253.227.131, 40.91.89.233, 20.41.47.199, 40.91.117.40, 40.91.126.113, 20.37.141.154 | -| Test Plans - West Europe | 40.119.145.57 | -| Test Plans - Australia East | 20.40.177.101 | -| Test Plans - Brazil South | 20.40.118.62 | -| Test Plans - India South | 40.81.72.10 | -| Test Plans - Canada Central | 40.82.184.28 | -| Test Plans - Asia Pacific (Singapore) | 20.195.68.0/24 | -| Test Plans - UK South | 40.81.159.9 | - -
      - -**Analytics IPs (Azure DevOps Server 2019 or later only)** - -If you included preview features with your import, add an exception for the analytics IPs only in your target import region. - -| Service | IP address | -| --- | --- | -| Analytics service - United States | 20.41.43.22, 20.36.236.83, 20.41.40.50, 52.143.251.221, 52.242.212.199, 13.86.33.148, 13.86.39.80 | -| Analytics service - West Europe | 52.236.146.143, 52.236.146.9, 52.149.108.23 | -| Analytics service - Australia East | 20.40.179.159 | -| Analytics service - Brazil South | 20.40.113.248 | -| Analytics service - India South | 40.81.73.58 | -| Analytics service - Canada Central | 40.82.185.214 | -| Analytics service - Asia Pacific (Singapore) | 20.195.68.0/24 | -| Analytics service - UK South | 40.81.159.247 | - -
      - -> [!NOTE] -> Alternatively, you can also use [Service Tags](/azure/virtual-network/service-tags-overview) in place of explicit IP ranges. Azure Service Tags are a convenient way for customers to manage their networking configuration to allow traffic from specific Azure services. Customers can easily allow access by adding the tag name azuredevops to their network security groups or firewalls either through the portal or programmatically. - -## Configure IP firewall exceptions - -Granting exceptions for the necessary IPs is handled at the Azure networking layer for your SQL Azure VM. To get started, go to your SQL Azure VM in the [Azure portal](https://ms.portal.azure.com). In **Settings**, select **Networking**. This will take you to the network interface page for your SQL Azure VM. The data migration tool requires the Azure DevOps Services IPs to be configured for inbound connections only on port 1433. You can grant exceptions for the IPs by selecting **Add inbound port rule** in the networking settings. - -![Screenshot of the "Add inbound port rule" button on your SQL Azure VM network interface page.](media/migration-import/inbound.png) - -On the **Add inbound security rule** pane, select **Advanced** to configure an inbound port rule for a specific IP. - -![Screenshot of the "Advanced" button on the "Add inbound security rule" pane.](media/migration-import/advanced.png) - -In the **Source** drop-down list, select **IP Addresses**, enter an IP address that needs to be granted an exception, set the **Destination port range** to **1433** and, in the **Name** box, enter a name that best describes the exception you're configuring. - -Depending on other inbound port rules that have been configured, you might need to change the default priority for the Azure DevOps Services exceptions so they don't get ignored. For example, if you have a "deny on all inbound connections to 1433" rule with a higher priority than your Azure DevOps Services exceptions, the data migration tool might be unable to make a successful connection to your database. - -![Screenshot of a completed inbound port rule configuration.](media/migration-import/example.png) - -Repeat adding inbound port rules until all necessary Azure DevOps Services IPs have been granted an exception. Missing one IP could result in your import failing to start. - -## Restore your database on the VM - -After you set up and configure an Azure VM, you need to take your detached backup from your Azure DevOps Server instance to your Azure VM. Azure has [several documented methods](/azure/azure-sql/virtual-machines/windows/migrate-to-vm-from-sql-server) for how to accomplish this task. The collection database needs to be restored on your SQL instance and doesn't require Azure DevOps Server to be installed on the VM. - -## Configure your collection for import - -After your collection database has been restored on your Azure VM, configure a SQL login to allow Azure DevOps Services to connect to the database to import the data. This login allows only *read* access to a single database. - -To start, open SQL Server Management Studio on the VM, and then open a new query window against the database to be imported. - -Set the database's recovery to simple: - -```sql -ALTER DATABASE [] SET RECOVERY SIMPLE; -``` - -Create a SQL login for the database, and assign that login the 'TFSEXECROLE': - -```sql -USE [] -CREATE LOGIN WITH PASSWORD = '' -CREATE USER FOR LOGIN WITH DEFAULT_SCHEMA=[dbo] -EXEC sp_addrolemember @rolename='TFSEXECROLE', @membername='' -``` - -Following our Fabrikam example, the two SQL commands would be: - -```sql -ALTER DATABASE [Foo] SET RECOVERY SIMPLE; - -USE [Foo] -CREATE LOGIN fabrikam WITH PASSWORD = 'fabrikamimport1!' -CREATE USER fabrikam FOR LOGIN fabrikam WITH DEFAULT_SCHEMA=[dbo] -EXEC sp_addrolemember @rolename='TFSEXECROLE', @membername='fabrikam' -``` -> [!NOTE] -> Be sure to enable [SQL Server and Windows authentication mode](/sql/database-engine/configure-windows/change-server-authentication-mode?view=sql-server-ver15#change-authentication-mode-with-ssms&preserve-view=true) in SQL Server Management Studio on the VM. If you don't enable authentication mode, the import will fail. - -## Configure the import specification file to target the VM - -Update the import specification file to include information about how to connect to the SQL Server instance. Open your import specification file and make the following updates: - -1. Remove the DACPAC parameter from the source files object. - - The import specification before the change is shown in the following code: - - ![Screenshot of the import specification before the change.](media/migration-import/importSpecBefore.png) - - The import specification after the change is shown in the following code: - - ![Screenshot of the import specification after the change.](media/migration-import/importSpecAfter.png) - -1. Fill out the required parameters and add the following properties object within your source object in the specification file. - - ```json - "Properties": - { - "ConnectionString": "Data Source={SQL Azure VM Public IP};Initial Catalog={Database Name};Integrated Security=False;User ID={SQL Login Username};Password={SQL Login Password};Encrypt=True;TrustServerCertificate=True" - } - ``` - -Following the Fabrikam example, after you apply the changes, the import specification would look like the following: - -![Screenshot of the import specification referencing a SQL Azure VM.](media/migration-import/importSpecIaaS.png) - -Your import specification is now configured to use a SQL Azure VM for import. Proceed with the [rest of preparation steps](migration-import.md#determine-the-import-type) to import to Azure DevOps Services. After the import has finished, be sure to delete the SQL login or rotate the password. Microsoft does not retain the login information after the import has finished. - - -## Related articles - -- [Validation and import processes](migration-import.md) diff --git a/docs/migrate/migration-import.md b/docs/migrate/migration-import.md deleted file mode 100644 index ee7f6d87a5d..00000000000 --- a/docs/migrate/migration-import.md +++ /dev/null @@ -1,609 +0,0 @@ ---- -title: Import migrate process from on-premises to Azure DevOps -titleSuffix: Azure DevOps -description: How to guide for preparing an on-premises collection to importing it to the cloud -ms.topic: how-to -ms.subservice: azure-devops-migrate -ms.contentid: 829179bc-1f98-49e5-af9f-c224269f7910 -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 08/18/2022 ---- - -# Validation and import processes - -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - -This article walks you through the preparation that's required to get an import to Azure DevOps Services ready to run. If you encounter errors during the process, see [Troubleshoot import and migration errors](migration-troubleshooting.md). - - -> [!NOTE] -> * Visual Studio Team Services (VSTS) is now [Azure DevOps Services.](../user-guide/about-azure-devops-services-tfs.md#visual-studio-team-services-is-now-azure-devops-services) -> * With the release of Azure DevOps Server 2019, the TFS Database Import Service has been rebranded as the data migration tool for Azure DevOps. This change includes TfsMigrator (Migrator) becoming the data migration tool. This service works exactly the same as the former import service. If you're running an older version of on-premises Azure DevOps Server with the TFS branding, you can still use this feature to migrate to Azure DevOps as long as you've upgraded to one of the supported server versions. -> * Before you begin the import tasks, check to ensure that you're running a [supported version of Azure DevOps Server](migration-overview.md#supported-azure-devops-server-versions-for-import). - -We recommend that you use the [Step-by-step migration guide](https://aka.ms/AzureDevOpsImport) to progress through your import. The guide links to technical documentation, tools, and best practices. - -## Prerequisites - -- You must set up an Azure Active Directory tenant as described [Azure AD Connect sync: Make a change to the default configuration](/azure/active-directory/hybrid/how-to-connect-sync-change-the-configuration). - The data migration tool sets up a link to your Azure Active Directory tenant when your Azure DevOps Services organization is created as part of the beginning of the import process. - - By synchronizing your on-premises Active Directory with Azure Active Directory, your team - members will be able to use the same credentials to authenticate and your Azure DevOps - Services administrators will be able to leverage your Active Directory groups for setting - permissions within your Azure DevOps Services organization. To setup the synchronization, you will want to use the Azure AD Connect technology. - - - -## Validate a collection - -After you've confirmed that you're running the latest version of Azure DevOps Server, your next step is to validate each collection that you want to migrate to Azure DevOps Services. - -The validation step examines various aspects of your collection, including, but not limited to, size, collation, identity, and processes. - -You run the validation by using the data migration tool. To start, [download the tool](https://aka.ms/AzureDevOpsImport), copy the zip file to one of your Azure DevOps Server application tiers, and then unzip it. You can also run the tool from a different machine without Azure DevOps Server installed as long as the machine can connect to the configuration database of the Azure DevOps Server instance. An example is shown here. - -1. Open a Command Prompt window on the server, and enter a cd command to change to the directory where the data migration tool is stored. Take a few moments to review the help content that's provided with the tool. - - a. To view the top-level help and guidance, run the following command: - - ```cmdline - Migrator /help - ``` - - b. View the help text for the command: - - ```cmdline - Migrator validate /help - ``` - -1. Because this is your first time validating a collection, let's keep it simple. Your command should have the following structure: - - ```cmdline - Migrator validate /collection:{collection URL} /tenantDomainName:{name} - ``` - - Where `{name}` provides the name of your Azure Active Directory tenant. For example, to run against the *DefaultCollection* and the *fabrikam* tenant, the command would look like: - - ```cmdline - Migrator validate /collection:http://localhost:8080/DefaultCollection /tenantDomainName:fabrikam.OnMicrosoft.com - ``` - -1. To run the tool from a machine other than the Azure DevOps Server, you need the **/connectionString** parameter. The connection string parameter points to your Azure DevOps Server configuration database. As an example, if the validate command is being run by the Fabrikam corporation, the command would look like: - - ```cmdline - Migrator validate /collection:http://fabrikam:8080/DefaultCollection /tenantDomainName:fabrikam.OnMicrosoft.com /connectionString:"Data Source=fabrikam;Initial Catalog=Configuration;Integrated Security=True" - ``` - - > [!Important] - > The data migration tool *does not* edit any data or structures in the collection. It reads the collection only to identify issues. - -1. After the validation is complete, you can view the log files and results. - - ![Screenshot of the validation results and logs in the Command Prompt window.](media/migration-import/tfsmigratorConsole.png) - - During validation, you'll receive a warning if some of your pipelines contain per-pipeline retention rules. Azure DevOps Services uses a [project-based retention model](../pipelines/policies/retention.md?view=azure-devops&preserve-view=true) and _doesn't_ support per-pipeline retention policies. If you proceed with the migration, the policies won't be carried over to the hosted version. Instead, the default project-level retention policies will apply. Retain builds important to you, to avoid their loss. - -After all the validations pass, you can move to the next step of the import process. If the data migration tool flags any errors, you need to correct them before you proceed. For guidance on correcting validation errors, see [Troubleshoot import and migration errors](migration-troubleshooting.md). - - - -### Import log files - -When you open the log directory, you'll notice several logging files. - -The main log file is named *DataMigrationTool.log*. It contains details about everything that was run. To make it easier for you to focus on specific areas, a log is generated for each major validation operation. - -For example, if TfsMigrator reports an error in the "Validating Project Processes" step, you can open the *ProjectProcessMap.log* file to view everything that was run for that step instead of having to scroll through the entire log. - -You should review the *TryMatchOobProcesses.log* file only if you're trying to import your project processes to use the [inherited model](migration-processtemplates.md). If you don't want to use the inherited model, you can ignore these errors, because they won't prevent you from importing to Azure DevOps Services. - -## Generate import files - -By now, you've run the data migration tool validation against the collection, and it's returning a result of "All collection validations passed." Before you take a collection offline to migrate it, you need to generate the import files. When you run the `prepare` command, you generate two import files: - -- *IdentityMapLog.csv*: Outlines your identity map between Active Directory and Azure Active Directory (Azure AD). -- *import.json*: Requires you to fill out the import specification you want to use to kick off your migration. - -### The prepare command - -The `prepare` command assists with generating the required import files. Essentially, this command scans the collection to find a list of all users to populate the identity map log, *IdentityMapLog.csv*, and then tries to connect to Azure AD to find each identity's match. To do this, your company needs to use the [Azure Active Directory Connect tool](/azure/active-directory/connect/active-directory-aadconnect) (formerly known as the Directory Synchronization tool, Directory Sync tool, or DirSync.exe tool). - -If directory synchronization is set up, the data migration tool should be able to find the matching identities and mark them as *Active*. If it doesn't find a match, the identity is marked as *Historical* in the identity map log, and you'll need to investigate why the user isn't included in your directory sync. The import specification file, *import.json*, should be filled out prior to the import. - -Unlike the `validate` command, `prepare` *does* require an internet connection, because it needs to connect to Azure AD to populate the identity map log file. If your Azure DevOps Server instance doesn't have internet access, you need to run the tool from a machine that does. As long as you can find a machine with an intranet connection to your Azure DevOps Server instance and an internet connection, you can run this command. For help with the `prepare` command, run the following command: - -```cmdline -Migrator prepare /help -``` - -Included in the help documentation are instructions and examples for running the `Migrator` command from the Azure DevOps Server instance itself and a remote machine. If you're running the command from one of the Azure DevOps Server instance's application tiers, your command should have the following structure: - - -```cmdline -Migrator prepare /collection:{collection URL} /tenantDomainName:{name} /region:{region} -``` - -```cmdline -Migrator prepare /collection:{collection URL} /tenantDomainName:{name} /region:{region} /connectionString:"Data Source={sqlserver};Initial Catalog=Configuration;Integrated Security=True" -``` - -The **connectionString** parameter is a pointer to the configuration database of your Azure DevOps Server instance. As an example, if the `prepare` command is being run by the Fabrikam corporation, the command would look like: - -```cmdline -Migrator prepare /collection:http://fabrikam:8080/DefaultCollection /tenantDomainName:fabrikam.OnMicrosoft.com /region:{region} /connectionString:"Data Source=fabrikam;Initial Catalog=Configuration;Integrated Security=True" -``` - -When the data migration tool runs the `prepare` command, it runs a complete validation to ensure that nothing has changed with your collection since the last full validation. If any new issues are detected, no import files are generated. - -Shortly after the command has started running, an Azure AD sign-in window is displayed. You need to sign in with an identity that belongs to the tenant domain that's specified in the command. Make sure that the specified Azure AD tenant is the one you want your future organization to be backed with. In our Fabrikam example, a user would enter credentials that are similar to what's shown in the following screenshot. - -> [!IMPORTANT] -> Do *not* use a test Azure AD tenant for a test import and your production Azure AD tenant for the production run. Using a test Azure AD tenant can result in identity import issues when you begin your production run with your organization's production Azure AD tenant. - -![Screenshot of the Azure AD sign-in window.](media/migration-import/aadLogin.png) - -When you run the `prepare` command successfully in the data migration tool, the results window displays a set of logs and two import files. In the log directory, you'll find a logs folder and two files: - -* *import.json* is the import specification file. We recommend that you take time to fill it out. -* *IdentityMapLog.csv* contains the generated mapping of Active Directory to Azure AD identities. Review it for completeness before you kick off an import. - -The two files are described in greater detail in the next sections. - -### The import specification file - -The import specification, *import.json*, is a JSON file that provides import settings. It includes the desired organization name, storage account information, and other information. Most of the fields are autopopulated, and some fields require your input before you attempt an import. - -![Screenshot of a newly generated import specification file.](media/migration-import/importSpecNotFilledOut.png) - -The *import.json* file's displayed fields and required actions are described in the following table: - -| Field | Description | Required action | -| --- | --- | --- | -| Source | Information about the location and names of the source data files that are used for import. | No action required. Review information for the subfield actions to follow. | -| Location | The shared access signature key to the Azure storage account that hosts the data-tier application package (DACPAC). | No action required. This field will be covered in a later step. | -| Files | The names of the files containing import data. | No action required. Review information for the subfield actions to follow. | -| DACPAC | A DACPAC file that packages the collection database to be used to bring in the data during the import. | No action required. In a later step, you'll generate this file by using your collection and then upload it to an Azure storage account. You'll need to update the file based on the name you use when you generate it later in this process. | -| Target | Properties of the new organization to import into. | No action required. Review information for the subfield actions to follow. | -| Name | The name of the organization to be created during the import. | Provide a name. The name can be quickly changed later after the import has completed.
      **Note**: Do *not* create an organization with this name before you run the import. The organization will be created as part of the import process. | -| ImportType | The type of import that you want to run. | No action required. In a later step, you'll select the type of import to run. | -| Validation Data | Information that's needed to help drive your import experience. | The "ValidationData" section is generated by the data migration tool. It contains information that's needed to help drive your import experience. Do *not* edit the values in this section, or your import could fail to start. | - -
      - -After you complete the preceding process, you should have a file that looks like the following: - -![Screenshot of a partially completed import specification file.](media/migration-import/importSpecHalfFilledOut.png) - -In the preceding image, note that the planner of the Fabrikam import added the organization name *fabrikam-import* and selected CUS (Central United States) as the region for import. Other values were left as is to be modified just before the planner took the collection offline for the migration. - -> [!NOTE] -> Dry-run imports have a '-dryrun' automatically appended to the end of the organization name. This can be changed after the import. - - - - -### Supported Azure regions for import - -Azure DevOps Services is available in several [Azure regions](https://azure.microsoft.com/regions/services/). However, not all regions where Azure DevOps Services is available are supported for import. The following table lists the Azure regions that you can select for import. Also included is the value that you need to place in the import specification file to target that region for import. - - -| Geographic region | Azure region | Import specification value | -| --- | --- | --- | -| United States | Central United States | CUS | -| Europe | Western Europe | WEU | -| United Kingdom | United Kingdom South | UKS| -| Australia | Australia East | EAU | -| South America | Brazil South | SBR | -| Asia Pacific | South India | MA | -| Asia Pacific | Southeast Asia (Singapore) | SEA | -| Canada | Central Canada | CC | - - - - -
      - -### The identity map log - -The identity map log is of equal importance to the actual data that you'll be migrating to Azure DevOps Services. As you're reviewing the file, it's important to understand how identity import operates and what the potential results could entail. When you import an identity, it can become either *active* or *historical*. Active identities can sign in to Azure DevOps Services, but historical identities cannot. - -#### Active identities - -Active identities refer to identities that will be users in Azure DevOps Services post-import. In Azure DevOps Services, these identities are licensed and are displayed as users in the organization. The identities are marked as *active* in the **Expected Import Status** column in the identity map log file. - - -#### Historical identities - -Historical identities are mapped as such in the **Expected Import Status** column in the identity map log file. Identities without a line entry in the file also become historical. An example of an identity without a line entry might be an employee who no longer works at a company. - -Unlike active identities, historical identities: -* *Don't* have access to an organization after migration. -* *Don't* have licenses. -* *Don't* show up as users in the organization. All that persists is the notion of that identity's name in the organization, so that its history can be searched later. We recommend that you use historical identities for users who no longer work at the company or who won't need further access to the organization. - -> [!NOTE] -> After an identity is imported as historical, it *can't* become active. - -### Understand the identity map log file - -The identity map log file is similar to the example shown here: - -![Screenshot of an identity map log file that's generated by the data migration tool.](media/migration-import/identityMapNewlyGenerated.png) - -The columns in the identity map log file are described in the following table: - -> [!NOTE] -> You and your Azure AD admin will need to investigate users that are marked as *No Match Found (Check Azure AD Sync)* to understand why they aren't part of your Azure AD Connect sync. - -| Column | Description | -| --- | --- | -| Active Directory: User (Azure DevOps Server) | The friendly display name used by the identity in Azure DevOps Server. This name makes it easier to identify which user the line in the map is referencing. | -| Active Directory: Security Identifier | The unique identifier for the on-premises Active Directory identity in Azure DevOps Server. This column is used to identify users in the collection. | -| Azure Active Directory: Expected Import User (Azure DevOps Services) | Either the expected sign-in address of the matched soon-to-be-active user or *No Match Found (Check Azure AD Sync)*, indicating that the identity wasn't found during the Azure Active Directory sync and it will be imported as historical. | -| Expected Import Status | The expected user import status: either *Active* if there's a match between your Active Directory and Azure Active Directory, or *Historical* if there isn't a match. | -| Validation Date | The last time the identity map log was validated. | - -
      - -As you read through the file, notice whether the value in the **Expected Import Status** column is *Active* or *Historical*. *Active* indicates that it's expected that the identity on this row will map correctly on import and will become active. *Historical* means that the identities will become historical on import. It's important to review the generated mapping file for completeness and correctness. - -> [!IMPORTANT] -> Your import will fail if major changes occur to your Azure AD Connect security ID sync between import attempts. You can add new users between dry runs, and you can make corrections to ensure that previously imported historical identities become active. However, changing an existing user that was previously imported as active isn't supported at this time. Doing so will cause your import to fail. An example of a change might be completing a dry-run import, deleting an identity from your Azure AD that was imported actively, re-creating a new user in Azure AD for that same identity, and then attempting another import. In this case, an active identity import will be attempted between the Active Directory and newly created Azure AD identity, but it will cause an import failure. - -1. Start by reviewing the correctly matched identities. Are all the expected identities present? Are the users mapped to the correct Azure AD identity? - - If any values are incorrectly mapped or need to be changed, contact your Azure AD administrator to verify that the on-premises Active Directory identity is part of the sync to Azure AD and has been set up correctly. For more information, see [Integrate your on-premises identities with Azure Active Directory](/azure/active-directory/hybrid/whatis-hybrid-identity). - -1. Next, review the identities that are labeled as *historical*. This labeling implies that a matching Azure AD identity couldn't be found, for any of the following reasons: - - * The identity hasn't been set up for sync between on-premises Active Directory and Azure AD. - * The identity hasn't been populated in your Azure AD yet (for example, there's a new employee). - * The identity doesn't exist in your Azure AD instance. - * The user who owns that identity no longer works at the company. - -To address the first three reasons, you need to set up the intended on-premises Active Directory identity to sync with Azure AD. For more information, see [Integrate your on-premises identities with Azure Active Directory](/azure/active-directory/hybrid/how-to-connect-sync-change-the-configuration). You must set up and run Azure AD Connect for identities to be imported as *active* in Azure DevOps Services. - -You can ignore the fourth reason, because employees who are no longer at the company should be imported as *historical*. - -#### Historical identities (small teams) - -> [!NOTE] -> The identity import strategy proposed in this section should be considered by small teams only. - -If Azure AD Connect hasn't been configured, you'll notice that all users in the identity map log file are marked as *historical*. Running an import this way results in all users being imported as [*historical*](#historical-identities). We strongly recommended that you configure [Azure AD Connect](/azure/active-directory/hybrid/how-to-connect-sync-change-the-configuration) to ensure that your users are imported as *active*. - -Running an import with all historical identities has consequences that need to be considered carefully. It should be considered only by teams with a small number of users and for which the cost of setting up Azure AD Connect is deemed too high. - -To import all identities as historical, follow the steps outlined in later sections. When you queue an import, the identity that's used to queue the import is bootstrapped into the organization as the organization owner. All other users are imported as historical. Organization owners can then [add the users back in](../organizations/accounts/add-organization-users.md?toc=/azure/devops/organizations/accounts/toc.json&bc=/azure/devops/organizations/accounts/breadcrumb/toc.json) by using their Azure AD identity. The added users are treated as new users. They do *not* own any of their history, and there's no way to re-parent this history to the Azure AD identity. However, users can still look up their pre-import history by searching for their \\. - -The data migration tool displays a warning if it detects the complete historical identities scenario. If you decide to go down this migration path, you'll need to consent in the tool to the limitations. - -### Visual Studio subscriptions - -The data migration tool can't detect Visual Studio subscriptions (formerly known as MSDN benefits) when it generates the identity map log file. Instead, we recommend that you apply the auto license upgrade feature after the import. As long as users' work accounts are [linked](/visualstudio/subscriptions/vs-alternate-identity) correctly, Azure DevOps Services automatically applies their Visual Studio subscription benefits at their first sign-in after the import. You're never charged for licenses that are assigned during the import, so this can be safely handled afterward. - -You don't need to repeat a dry-run import if users' Visual Studio subscriptions aren't automatically upgraded in Azure DevOps Services. Visual Studio subscription linking happens outside the scope of an import. As long as their work account is linked correctly before or after the import, users' licenses are automatically upgraded on their next sign-in. After their licenses have been upgraded successfully, the next time you run an import, the users are upgraded automatically on their first sign-in to the organization. - - - -## Prepare for import - -By now, you have everything ready to execute on your import. You need to schedule downtime with your team to take the collection offline for the migration. When you've agreed upon a time to run the import, you need to upload to Azure both the required assets you've generated and a copy of the database. This process has five steps: - -Step 1: [Take the collection offline and detach it](#step-1-detach-your-collection). - -> [!NOTE] -> DACPAC imports are not currently supported for SQL Server 2022. Imports from SQL Server 2022 databases must use the SQL Azure virtual machine (VM) method. If you are using SQL Server 2022, skip steps 2 to 5. Then follow the instructions provided in [Import large collections](migration-import-large-collections.md) and continue to section [determine the import type](#determine-the-import-type). - -> [!NOTE] -> The collection size limit for the DACPAC method is 150 GB. If the data migration tool displays a warning that you can't use the DACPAC method, you have to perform the import by using the SQL Azure virtual machine (VM) method. Skip steps 2 to 5 in that case and follow instructions provided in [Import large collections](migration-import-large-collections.md) and then continue to section [determine the import type](#determine-the-import-type). - -Step 2: [Generate a DACPAC file from the collection you're going to import](#step-2-generate-a-dacpac-file). -Step 3: [Upload the DACPAC file and import files to an Azure storage account](#step-3-upload-the-dacpac-file). -Step 4: [Generate an SAS token to access the storage account](#step-4-generate-an-sas-token). -Step 5: [Complete the import specification](#step-5-complete-the-import-specification). - -> [!NOTE] -> Before you perform a production import, we *strongly* recommend that you complete a dry-run import. With a dry run, you can validate that the import process works for your collection and that there are no unique data shapes present that might cause a production import failure. - -### Step 1: Detach your collection - -[Detaching the collection](/azure/devops/server/admin/move-project-collection#detach-coll) is a crucial step in the import process. Identity data for the collection resides in the Azure DevOps Server instance's configuration database while the collection is attached and online. When a collection is detached from the Azure DevOps Server instance, it takes a copy of that identity data and packages it with the collection for transport. Without this data, the identity portion of the import *can't* be executed. We recommend that you keep the collection detached until the import has been completed, because there isn't a way to import the changes that occurred during the import. - -If you're doing a dry run (test) import, we recommend that you reattach your collection after you back it up for import, because you won't be concerned about having the latest data for this type of import. To avoid offline time altogether, you can also choose to employ an [offline detach](/azure/devops/server/command-line/tfsconfig-cmd#offlinedetach) for dry runs. - -It's important to weigh the cost of choosing to incur zero downtime for a dry run. It requires taking backups of the collection and configuration database, restoring them on a SQL instance, and then creating a detached backup. A cost analysis could prove that taking just a few hours of downtime to directly take the detached backup is better in the long run. - - - -### Step 2: Generate a DACPAC file - -DACPACs offer a fast and relatively easy method for moving collections into Azure DevOps Services. However, after a collection database size exceeds a certain threshold, the benefits of using a DACPAC start to diminish. - -> [!NOTE] -> If the data migration tool displays a warning that you can't use the DACPAC method, you have to perform the import by using the SQL Azure virtual machine (VM) method provided in [Import large collections](migration-import-large-collections.md). -> -> If the data migration tool doesn't display a warning, use the DACPAC method described in this step. - - -[DACPAC](/sql/relational-databases/data-tier-applications/data-tier-applications) is a feature of SQL server that allows database changes to be packaged into a single file and deployed to other instances of SQL. A DACPAC file can also be restored directly to Azure DevOps Services, so you can use it as the packaging method for getting your collection's data in the cloud. You use the SqlPackage.exe tool to generate the DACPAC file. The tool is included as part of [SQL Server Data Tools (SSDT)](/sql/ssdt/download-sql-server-data-tools-ssdt). - -Multiple versions of the SqlPackage.exe tool are installed with SSDT. The versions are stored in folders with names such as 120, 130, and 140. When you use SqlPackage.exe, it's important to use the right version to prepare the DACPAC. - -* TFS 2018 imports need to use the SqlPackage.exe version from the 140 folder or higher. - -If you installed SSDT for Visual Studio, you'll find your SqlPackage.exe version in one of the following folder paths: - -* If you installed SSDT and integrated it with an existing installation of Visual Studio, your SqlPackage.exe folder path is similar to `C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\130\`. -* If you installed SSDT as a standalone installation, your SqlPackage.exe folder path is similar to `C:\Program Files (x86)\Microsoft Visual. Studio\2017\SQL\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\130\`. -* If you already have an installation of SQL Server, SqlPackage.exe might already be present, and your folder path is similar to `%PROGRAMFILES%\Microsoft SQL Server\130\DAC\bin\`. - -Both versions of SSDT that you can download from [SQL Server Data Tools](/sql/ssdt/download-sql-server-data-tools-ssdt) include both the 130 and 140 folders and their SqlPackage.exe versions. - -When you generate a DACPAC, keep two considerations in mind: the disk that the DACPAC will be saved on and the disk space on the machine that's generating the DACPAC. You want to ensure that you have enough disk space to complete the operation. - -As it creates the package, SqlPackage.exe temporarily stores data from your collection in the temp directory on drive C of the machine you're initiating the packaging request from. - -You might find that your drive C is too small to support creating a DACPAC. You can estimate the amount of space you'll need by looking for the largest table in your collection database. DACPACs are created one table at a time. The maximum space requirement to run the generation is roughly equivalent to the size of the largest table in the collection's database. If you're saving the generated DACPAC to drive C, you also need to take into account the size of the collection database as reported in the *DataMigrationTool.log* file from a validation run. - -The *DataMigrationTool.log* file provides a list of the largest tables in the collection each time the validate command is run. For an example of table sizes for a collection, see the following output. Compare the size of the largest table with the free space on the drive that hosts your temporary directory. - -> [!IMPORTANT] -> Before you proceed with generating a DACPAC file, ensure that your collection is [detached](migration-import.md#step-1-detach-your-collection). - - -```cmdline -[Info @08:23:59.539] Table name Size in MB -[Info @08:23:59.539] dbo.tbl_Content 38984 -[Info @08:23:59.539] dbo.tbl_LocalVersion 1935 -[Info @08:23:59.539] dbo.tbl_Version 238 -[Info @08:23:59.539] dbo.tbl_FileReference 85 -[Info @08:23:59.539] dbo.Rules 68 -[Info @08:23:59.539] dbo.tbl_FileMetadata 61 -``` - -Ensure that the drive that hosts your temporary directory has at least as much free space. If it doesn't, you need to redirect the temp directory by setting an environment variable. - -```cmdline -SET TEMP={location on disk} -``` - -Another consideration is where the DACPAC data is saved. Pointing the save location to a far-off remote drive could result in much longer generation times. If a fast drive such as a solid-state drive (SSD) is available locally, we recommend that you target the drive as the DACPAC save location. Otherwise, it's always faster to use a disk that's on the machine where the collection database resides rather than a remote drive. - -Now that you've identified the target location for the DACPAC and ensured that you have enough space, it's time to generate the DACPAC file. - -Open a Command Prompt window and go to the SqlPackage.exe location. To generate the DACPAC, replace the placeholder values with the required values, and then run the following command: - -```cmdline -SqlPackage.exe /sourceconnectionstring:"Data Source={database server name};Initial Catalog={Database Name};Integrated Security=True" /targetFile:{Location & File name} /action:extract /p:ExtractAllTableData=true /p:IgnoreUserLoginMappings=true /p:IgnorePermissions=true /p:Storage=Memory -``` - -* **Data Source**: The SQL Server instance that hosts your Azure DevOps Server collection database. -* **Initial Catalog**: The name of the collection database. -* **targetFile**: The location on the disk and the DACPAC file name. - -A DACPAC generation command that's running on the Azure DevOps Server data tier itself is shown in the following example: - -```cmdline -SqlPackage.exe /sourceconnectionstring:"Data Source=localhost;Initial Catalog=Foo;Integrated Security=True" /targetFile:C:\DACPAC\Foo.dacpac /action:extract /p:ExtractAllTableData=true /p:IgnoreUserLoginMappings=true /p:IgnorePermissions=true /p:Storage=Memory -``` - -The output of the command is a DACPAC file that's generated from the collection database *Foo* called *Foo.dacpac*. - - -#### Configure your collection for import - -After your collection database has been restored on your Azure VM, configure a SQL login to allow Azure DevOps Services to connect to the database to import the data. This login allows only *read* access to a single database. - -To start, open SQL Server Management Studio on the VM, and then open a new query window against the database to be imported. - -Set the database's recovery to simple: - -```sql -ALTER DATABASE [] SET RECOVERY SIMPLE; -``` - -Create a SQL login for the database, and assign that login the 'TFSEXECROLE': - -```sql -USE [] -CREATE LOGIN WITH PASSWORD = '' -CREATE USER FOR LOGIN WITH DEFAULT_SCHEMA=[dbo] -EXEC sp_addrolemember @rolename='TFSEXECROLE', @membername='' -``` - -Following our Fabrikam example, the two SQL commands would look like the following: - -```sql -ALTER DATABASE [Foo] SET RECOVERY SIMPLE; - -USE [Foo] -CREATE LOGIN fabrikam WITH PASSWORD = 'fabrikamimport1!' -CREATE USER fabrikam FOR LOGIN fabrikam WITH DEFAULT_SCHEMA=[dbo] -EXEC sp_addrolemember @rolename='TFSEXECROLE', @membername='fabrikam' -``` -> [!NOTE] -> Be sure to enable [SQL Server and Windows authentication mode](/sql/database-engine/configure-windows/change-server-authentication-mode?view=sql-server-ver15#change-authentication-mode-with-ssms&preserve-view=true) in SQL Server Management Studio on the VM. If you don't enable authentication mode, the import will fail. - -#### Configure the import specification file to target the VM - -Update the import specification file to include information about how to connect to the SQL Server instance. Open your import specification file and make the following updates: - -1. Remove the DACPAC parameter from the source files object. - - The import specification before the change is shown in the following code: - - ![Screenshot of the import specification before the change.](media/migration-import/importSpecBefore.png) - - The import specification after the change is shown in the following code: - - ![Screenshot of the import specification after the change.](media/migration-import/importSpecAfter.png) - -1. Fill out the required parameters and add the following properties object within your source object in the specification file. - - ```json - "Properties": - { - "ConnectionString": "Data Source={SQL Azure VM Public IP};Initial Catalog={Database Name};Integrated Security=False;User ID={SQL Login Username};Password={SQL Login Password};Encrypt=True;TrustServerCertificate=True" - } - ``` - -Following the Fabrikam example, after you apply the changes, the import specification would look like the following: - -![Screenshot of the import specification referencing a SQL Azure VM.](media/migration-import/importSpecIaaS.png) - -Your import specification is now configured to use a SQL Azure VM for import. Proceed with the rest of preparation steps to import to Azure DevOps Services. After the import has finished, be sure to delete the SQL login or rotate the password. Microsoft does not retain the login information after the import has finished. - -### Step 3: Upload the DACPAC file - -> [!NOTE] -> If you're using the SQL Azure VM method, you need to provide only the connection string. You don't have to upload any files, and you can skip this step. - -Your DACPAC must be placed in an Azure storage container. This can be an existing container or one created specifically for your migration effort. It's important to ensure that your container is created in the right region. - -Azure DevOps Services is available in multiple [regions](https://azure.microsoft.com/regions/services/). When you're importing to these regions, it's critical to place your data in the correct region to ensure that the import can start successfully. Your data must be placed in the same region that you'll be importing to. Placing the data anywhere else will result in the import being unable to start. The following table lists the acceptable regions for creating your storage account and uploading your data. - -| Desired import region | Storage account region | -| --- | --- | -| Central United States | Central United States | -| Western Europe | Western Europe | -| United Kingdom | United Kingdom South | -| Australia East | Australia East | -| Brazil South | Brazil South | -| India South | India South | -| Canada Central | Canada Central | -| Asia Pacific (Singapore) | Asia Pacific (Singapore) | - -
      - -Although Azure DevOps Services is available in multiple regions in the US, only the Central United States region accepts new Azure DevOps Services. You can't import your data into other US Azure regions at this time. - -You can [create a blob container](/azure/storage/common/storage-create-storage-account) from the Azure portal. After you've created the container, you need to upload the Collection DACPAC file. - -After the import has finished, you can delete the blob container and accompanying storage account. To do so, you can use tools such as [AzCopy](/azure/storage/common/storage-use-azcopy-v10) or any other Azure storage explorer tool, such as [Azure Storage Explorer](https://storageexplorer.com/). - -> [!NOTE] -> If your DACPAC file is larger than 10 GB, we recommend that you use AzCopy. AzCopy has multithreaded upload support for faster uploads. - -### Step 4: Generate an SAS token - -A [shared access signature (SAS) token](/azure/storage/common/storage-sas-overview) provides delegated access to resources in a storage account. The token allows you to give Microsoft the lowest level of privilege that's required to access your data for executing the import. - -SAS tokens can be [generated using the Azure Portal](/azure/storage/blobs/blob-containers-portal#generate-a-shared-access-signature). From a security point-of-view, we recommend: - -1. Selecting only **Read** and **List** as permissions for your SAS token. No other permissions are required. -2. Setting an expiry time no further than seven days into the future. -3. [Restricting IP addresses to only those used by the import process](migration-import-large-collections.md#optional-restrict-access-to-azure-devops-services-ips-only). -4. Placing the SAS token in a secure location. - -### Step 5: Complete the import specification - -Earlier in the process you partially filled out the import specification file generally known as *import.json*. At this point, you have enough information to complete all the remaining fields except for the import type. The import type will be covered later, in the import section. - -In the *import.json* specification file, under **Source**, complete the following fields: - -* **Location**: Paste the SAS key you generated from the script and then copied in the preceding step. -* **Dacpac**: Ensure that the file, including the *.dacpac* file extension, has the same name as the DACPAC file you uploaded to the storage account. - -Using the Fabrikam example, the final import specification file should look like the following: - -![Screenshot of the completed import specification file.](media/migration-import/ImportSpecFillOutNoType.png) - -       - - -### Restrict access to Azure DevOps Services IPs only - -We highly recommend that you restrict access to your Azure Storage account to only IPs from Azure DevOps Services. You do this by allowing connections only from the set of Azure DevOps Services IPs that are involved in the collection database import process. The IPs that need to be granted access to your storage account depend on the region you're importing into. Use the IpList option to get the list of IPs that need to be granted access. - -Included in the help documentation are instructions and examples for running Migrator from the Azure DevOps Server instance itself and a remote machine. If you're running the command from one of the Azure DevOps Server instance's application tiers, your command should have the following structure: - -```cmdline -Migrator IpList /collection:{CollectionURI} /tenantDomainName:{name} /region:{region} -``` - -> [!NOTE] -> Alternatively, you can also use [Service Tags](/azure/virtual-network/service-tags-overview) in place of explicit IP ranges. Azure Service Tags are a convenient way for customers to manage their networking configuration to allow traffic from specific Azure services. Customers can easily allow access by adding the tag name azuredevops to their network security groups or firewalls either through the portal or programmatically. - -### Determine the import type - -Imports can be queued as either a dry run or a production run. The **ImportType** parameter determines the import type: - -- **DryRun**: Use a dry run for test purposes. The system deletes dry runs after 21 days. -- **ProductionRun**: Use a production run when you want to keep the resulting import and use the organization full time in Azure DevOps Services after the import finishes. - -> [!TIP] -> We always recommend that you complete a dry-run import first. - -![Completed import specification file with import type](media/migration-import/importSpecCompleted.png) - -### Dry-run organizations - -Dry-run imports help teams test the migration of their collections. Organizations are expected not to remain around forever but to exist for a short time. In fact, before a production migration can be run, any completed dry-run organizations will need to be deleted. All dry-run organizations have a *limited existence and are automatically deleted after a set period of time*. Information about when the organization will be deleted is included in the success email you should receive after the import finishes. Be sure to take note of this date and plan accordingly. - -Most dry-run organizations have 15 days before they're deleted. Dry-run organizations can also have a 21-day expiration if more than 100 users have a basic or greater license at *import time*. After the specified time period, the dry-run organization is deleted. You can repeat dry-run imports as many times as you need before you do a production migration. You need to delete any previous dry runs before you attempt a new one. When your team is ready to perform a production migration, you'll need to manually delete the dry-run organization. - -For more information about post-import activities, see the [post import](migration-post-import.md) article. - -If you encounter any import problems, see [Troubleshoot import and migration errors](migration-troubleshooting.md#resolve-import-errors). - - - -## Run an import - -Your team is now ready to begin the process of running an import. We recommend that you start with a successful dry-run import before you attempt a production-run import. With dry-run imports, you can see in advance how an import will look, identify potential issues, and gain experience before you head into your production run. - -> [!NOTE] -> If you need to repeat a completed production-run import for a collection, as in the event of a rollback, contact Azure DevOps Services [Customer Support](https://azure.microsoft.com/support/devops/) before you queue up another import. - -> [!NOTE] -> Azure administrators can prevent users from creating new Azure DevOps organizations. If the Azure AD tenant policy is turned on, your import will fail to finish. Before you begin, verify that the policy isn't set or that there is an exception for the user that is performing the migration. For more information, see [Restrict organization creation via Azure AD tenant policy](../organizations/accounts/azure-ad-tenant-policy-restrict-org-creation.md). - -> [!NOTE] -> Azure DevOps Services does not support per-pipeline retention policies, and they will not be carried over to the hosted version. - -### Considerations for rollback plans - -A common concern for teams that are doing a final production run is what their rollback plan will be if anything goes wrong with import. This is why we highly recommend doing a dry run to make sure that you're able to test the import settings you provide to the data migration tool for Azure DevOps. - -Rollback for the final production run is fairly simple. Before you queue the import, you detach the team project collection from Azure DevOps Server or Team Foundation Server, which will make it unavailable to your team members. If for any reason you need to roll back the production run and bring the on-premises server back online for your team members, you can do so. You simply attach the team project collection on-premises again and inform your team that they'll continue to work normally while your team regroups to understand any potential failures. - -### Queue an import - -> [!IMPORTANT] -> Before you proceed, ensure that your collection was [detached](migration-import.md#step-1-detach-your-collection) prior to generating a DACPAC file or uploading the collection database to a SQL Azure VM. If you don't complete this step, the import will fail. In the event that your import fails, see [Troubleshoot import and migration errors](migration-troubleshooting.md). - -You start an import by using the data migration tool's **import** command. The import command takes an import specification file as input. It parses the file to ensure that the provided values are valid and, if successful, it queues an import to Azure DevOps Services. The import command requires an internet connection, but does *not* require a connection to your Azure DevOps Server instance. - -To get started, open a Command Prompt window, and change directories to the path to the data migration tool. We recommended that you take a moment to review the help text provided with the tool. Run the following command to see the guidance and help for the import command: - -```cmdline -Migrator import /help -``` - -The command to queue an import will have the following structure: - -```cmdline -Migrator import /importFile:{location of import specification file} -``` - -Here is an example of a completed import command: - -```cmdline -Migrator import /importFile:C:\DataMigrationToolFiles\import.json -``` - -After the validation passes, you'll be asked to sign in to Azure AD. It's important to sign in with an identity that's a member of the same Azure AD tenant as the identity map log file was built against. The user that signs in becomes the owner of the imported organization. - -> [!NOTE] -> Each Azure AD tenant is limited to five imports per 24-hour period. Only imports that are queued count against this cap. - -When your team initiates an import, an email notification is sent to the user that queued the import. About 5 to 10 minutes after it queues the import, your team can go to the organization to check on the status. After the import finishes, your team is directed to sign in, and an email notification is sent to the organization owner. - -## Related articles - -- [Migrate options](migration-overview.md) -- [Post-import](migration-post-import.md) diff --git a/docs/migrate/migration-migrate.md b/docs/migrate/migration-migrate.md new file mode 100644 index 00000000000..4072bf338da --- /dev/null +++ b/docs/migrate/migration-migrate.md @@ -0,0 +1,44 @@ +--- +title: Migrate to Azure DevOps Services +titleSuffix: Azure DevOps +description: How to do a production migration from on-premises to the cloud in Azure DevOps Services. +ms.topic: how-to +ms.subservice: azure-devops-migrate +ms.contentid: +ms.author: chcomley +author: chcomley +monikerRange: '<= azure-devops' +ms.date: 05/20/2024 +--- + +# Migrate to Azure DevOps Services + +You completed the [Test run](migration-test-run.md) phase and familiarized yourself with the process. Now, it’s time to embark on the actual journey of migrating to Azure DevOps Services. + +:::image type="content" source="media/migrate-stage-migration-highres.png" alt-text="Diagram of highlighted Migrate stage of the seven stages of migration."::: + +## Prerequisites + +Ensure your test runs result in zero errors before you officially migrate to Azure DevOps Services. + +## Queue the migration + +Do the following steps to queue the migration with the Data Migration Tool. + +1. Ensure the migration specification file is complete. +1. Use the following command to queue the migration: `Migration /importFile:C:\TFSDataImportFiles\import.json`. + - Ownership: The user who queued the migration owns the migrated organization. + - Notifications: The owner receives an email for migration success or [failure](migration-troubleshooting.md). + +## Next steps + +> [!div class="nextstepaction"] +> [Complete post-migration tasks](migration-post-migration.md) + +## Related articles + +- [Validate and prepare for migration](migration-validate.md) +- [Prepare for test run](migration-prepare-test-run.md) +- [Do test run migration](migration-test-run.md) + + \ No newline at end of file diff --git a/docs/migrate/migration-overview.md b/docs/migrate/migration-overview.md index 1d39354d20e..cba8c24c25b 100644 --- a/docs/migrate/migration-overview.md +++ b/docs/migrate/migration-overview.md @@ -1,87 +1,146 @@ --- -title: Azure DevOps Server to Services Migration overview -description: Overview of the high fidelity migration process from Server to Services +title: Azure DevOps Server to Azure DevOps Services Migration overview +description: Overview of the high fidelity migration process from on-premises Server to cloud Services. ms.topic: overview ms.subservice: azure-devops-migrate ms.contentid: 3d6edd06-ceed-43b4-9e77-4a121864594c ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 04/01/2021 +ms.date: 02/18/2025 --- -# Migrate data from Azure DevOps Server to Azure DevOps Services +# Migration overview -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] +Moving from Azure DevOps Server to Azure DevOps Services is an essential step for organizations that want to take advantage of cloud-based collaboration, scalability, and enhanced features. In this overview, we explore the options for transferring your valuable data from the on-premises Azure DevOps Server to the cloud-based Azure DevOps Services. -The data migration tool for Azure DevOps provides a high fidelity way to migrate collection databases from Azure DevOps Server to Azure DevOps Services. It's recommended that you download the [migration guide and tool](https://aka.ms/AzureDevOpsImport) if you're looking to use this service to import your collection(s). The guide serves as a walk through of the different steps involved in an import. Providing best practices, checklists, and helpful tips to make your import as easy as possible. The guide should be used in conjunction with the more technical documentation referenced below to successfully import to Azure DevOps Services. +For information about the main differences between on-premises Azure DevOps Server and the cloud-based Azure DevOps Services, see [Compare Azure DevOps Services with Azure DevOps Server - Azure DevOps](../user-guide/about-azure-devops-services-tfs.md). -## Supported Azure DevOps Server versions for import +Regardless of your selected migration option, we recommend that you determine your most important assets, such as source code and work items. You should think about your data size, organization complexity and make sure that you have enough time for test runs before actual migration for a smooth and successful transition. -> [!IMPORTANT] -> It can take up to 2-3 weeks after a new RTW version of Azure DevOps Server is released for import support to come online for that version. It's important to take this into consideration when choosing to upgrade shortly after a new RTW Azure DevOps Server release. +### Approaches to migration -The data migration tool for Azure DevOps supports the two latest releases of Azure DevOps Server at a given time. Releases include updates and major releases. Currently the following versions of Azure DevOps Server are supported for import: +It’s crucial to assess the pros and cons of each approach to migration, based on your specific motivations for adopting Azure DevOps Services. The right strategy depends on your unique context and requirements. -* Azure DevOps Server 2022.0.1 -* Azure DevOps Server 2022 -* Azure DevOps Server 2020.1.2 +|Options |Recommended scenarios |Limitations | +|---------|---------|---------| +|[1: Manual migration](#option-1-manual-migration) | Use for smaller projects or specific data subsets. | Not all data can be migrated with full fidelity and is subject to throttling. This migration doesn’t support migrating XML templates, so you need to recreate process templates as inherited templates. | +|[2: Azure DevOps Data Migration Tool](#option-2-azure-devops-data-migration-tool) | Use for medium to large-scale migrations with varied data types and complex structures. | You can only "lift and shift" one Azure DevOps Server collection to one new Azure DevOps Services organization, with no modifications. For more information, see the [Limitations section](#migration-tool-limitations). | +|[3: API-based migration](#option-3-api-based-migration) | Offers flexibility and customization for organizations with unique migration requirements or automation needs. | Low fidelity, data loss, and ID changes can occur. For more information, see the [Limitations section](#api-based-migration-limitations). | -> [!NOTE] -> The data migration tool doesn't support imports from Azure DevOps Server release candidates (RC). If you're planning on importing your collection database to Azure DevOps Services using this service, it's important that you don't upgrade your production database to an RC release. If you do upgrade, then you will need to wait and upgrade to the release to web (RTW) version when it's available or restore a backup copy of your database from a previous Azure DevOps Server version to import. +## Option 1: Manual migration -Normal release cadence for new Azure DevOps Server versions is once every three-to-four months. Meaning that support for a given version of Azure DevOps Server for migration to Azure DevOps Services should last for anywhere between six-to-eight months. It's important to ensure that your planning accounts for this support window to avoid having to suddenly upgrade to migrate. +For example, when the Azure DevOps team at Microsoft chose to move from Azure DevOps Server to Azure DevOps Services, we also decided to move from Team Foundation Version Control (TFVC) to Git. Migration required lots of planning, but when we migrated, we created a new Git repo using the "tip" version of our TFVC sources and left our history behind in Azure DevOps Server. We also moved our active work items, and left behind all our old bugs, completed user stories and tasks, and so on. -## Preview features +### Manual migration process -> [!Note] -> If you're not including preview features when running the migration tool, then you will need to re-run the migration tool prepare to generate a new import.json to queue an import. You DO NOT need to include preview features when you re-generate your import.json. -> -> If you had previously been including preview features then you DO NOT need to take any additional actions after Monday, April 23, 2020. +1. Identify the most important assets that you need to migrate - typically source code, work items, or both. Other assets in Azure DevOps Server - build pipelines, test plans, and so forth - are harder to manually migrate. +1. Identify a suitable time to make the transition. +1. Prepare your target organizations. Create the organizations and team projects that you need, provision users, and so on. +1. Migrate your data. +1. Consider making the source Azure DevOps Server deployments read-only. You can do so in the following ways: + - [Adjust project-level permissions](../organizations/security/change-project-level-permissions.md): Set the permissions for all users or groups to read-only at the project level, which you can do by modifying the security roles in **Project settings**. + - [Modify repository settings](../organizations/security/set-object-level-permissions.md): For each repository, you can change the settings to make them read-only, which involves adjusting the permissions for each user or group to only allow read actions. + - [Use built-in security groups](../organizations/security/permissions-access.md): Utilize the built-in security groups to manage permissions more efficiently. You can assign users to groups like "Readers" to provide read-only access. + - Scripting permission changes: If you have many projects or repositories, you might need to script them. You can use the [Azure CLI DevOps extension](../cli/index.md) to list all permissions and update them as needed. + - Disable repository feature: Disables access to the repository, including builds and pull requests, but keeps the repository discoverable with a warning. Go to **Project settings** > **Repositories** > your repo, and next to Disable Repository, move the toggle to **On**. +## Option 2: Azure DevOps Data Migration Tool -The following features can be included with your import, but are currently in a preview state. +The [Azure DevOps Data Migration Tool](https://www.microsoft.com/download/details.aspx?id=54274) is a set of utilities provided by Microsoft to facilitate the migration of data from Azure DevOps Server to Azure DevOps Services. These tools offer a streamlined approach to migrate various artifacts, including source code, work items, test cases, and other project-related data. -* [Analytics](../report/powerbi/what-is-analytics.md) - Note this is only supported for Azure DevOps Server 2019 and later. +Before you initiate the migration process, the tools can perform a premigration analysis to assess the readiness of the source environment and identify potential issues or dependencies that might affect the migration. Assess readiness, so you can plan and mitigate potential challenges beforehand. -When queueing an import you can elect to include preview features with your import. If you do, data related to these features will be copied into your new organization along with all your other data. Should you choose to not include these features then their data will not be copied. +## Migration Tool limitations -For a list of items not included with an import, see the [migration guide and tool](https://aka.ms/AzureDevOpsImport). +The tool allows you to "lift and shift" one Azure DevOps Server Collection to one new Azure DevOps Service Organization, with no modifications for the following reasons: -## Data migration tool for Azure DevOps resources +- Data integrity and consistency: + - When you migrate data, maintaining integrity and consistency is crucial. Allowing modifications during migration could lead to data corruption or inconsistencies. + - The tool ensures that data remains intact during the transfer process, minimizing the risk of errors. +- Source data preservation: + - The migration tool aims to faithfully replicate the source data in the target environment. + - Modifications could alter the original data, potentially causing discrepancies between the migrated data and the source data. +- Predictable behavior: + - By restricting modifications, the tool ensures predictable behavior during migration. + - Users can rely on consistent results without unexpected changes. +- Migration focus, not transformation: + - The primary purpose of the migration tool is to move data from one location to another. + - Data transformation, such as modifying values, typically gets handled separately after migration. +- Supported migration scenarios: + - Moving projects from one Azure DevOps Services organization to another Azure DevOps Services organization isn't currently supported. + - Migrating from one Azure DevOps Server instance to another isn't supported. -In general you should use the [Migration guide and tool](https://aka.ms/AzureDevOpsImport) when going through an import. When it's required, the guide links back to the following articles. These articles offer deeper technical knowledge on various import topics. +You can purge data that you don’t need before or after the migration. -### Import process +## Migration Tool process -* [Validate a collection for import](migration-import.md#validate-a-collection) -* [Prepare a collection for import](migration-import.md#generate-import-files) -* [Prepare for import](migration-import.md#prepare-import) - * [Prepare large collections for import](migration-import-large-collections.md) -* [Run an import](migration-import.md#run-an-import) -* [Post import steps](migration-post-import.md) +1. Complete the prerequisites such as updating Azure DevOps Server to one of the two most recent releases. +1. Validate each collection that you want to move to Azure DevOps Services. +1. Generate migration files. +1. Prepare everything for your migration execution. +1. Perform a test run. +1. Carry out a migration. +1. Confirm that your users and data got migrated, and the collection is functioning as expected. -### Troubleshooting +## Option 3: API-based migration -* [Troubleshooting validation errors](migration-troubleshooting.md) -* [Troubleshooting process errors](migration-processtemplates.md#dealing-with-process-errors) -* [Troubleshooting import errors](migration-troubleshooting.md#resolve-import-errors) +If you can't use the Data Migration Tool but still want a higher fidelity migration than [Option 2](#option-2-azure-devops-data-migration-tool), consider using various tools that leverage public APIs to move data. These tools include extensions available at the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops). +## API-based migration limitations -## Q & A +The following limitations occur with API-based migration: - +- Low fidelity migration: + - Limitation: API-based tools provide a higher fidelity than manual copying but are still relatively low fidelity. + - Implication: While these tools offer some fidelity, they don’t preserve all aspects of your data. + - Example: None of them retain the original dates of TFVC changesets (Team Foundation Version Control). + - Many don’t preserve the changed dates of work item revisions either. +- Data loss and ID changes: + - Limitation: During migration, the tools replay work item changes, TFVC changesets, package feeds, and pipeline artifacts. + - Implication: This process might lead to data loss, generate new IDs, and alter creation, modification, and closure dates. + - Example: Historical context tied to specific dates might get lost, affecting reporting and traceability. -### Q: Will my Personal Access Tokens also migrate when I migrate from on-premises to Azure DevOps Services? +## API-based migration process -A: **No**. Your tokens will not migrate and you will need to [regenerate your Personal Access Tokens](../organizations/accounts/use-personal-access-tokens-to-authenticate.md?tabs=preview-page) on Azure DevOps Services. +In general, we only recommend this approach if extra fidelity beyond a manual copy is critical. If you decide to take this approach, you might consider hiring a consultant who has experience with one or more of the tools and do a test migration before your final migration. -### Q: If I have feedback or additional questions is there somewhere I can reach out? +Many organizations need a very high-fidelity migration for only a subset of their work. New work could potentially start directly in Azure DevOps Services. Other work, with less stringent fidelity requirements, could be migrated using one of the other approaches. -A: You can search the [developer community portal](https://developercommunity.visualstudio.com/report?space=21&entry=problem) to see if your question is asked and answered and if not, please open up a new issue. If you need assistance with a failed import, please contact Azure DevOps [customer support](https://aka.ms/AzureDevOpsImportSupport). - +## Supported process models -## Related articles +Azure DevOps Services supports the following process models: + +- [Inherited](../organizations/settings/work/customize-process.md) +- [Hosted XML](../organizations/settings/work/hosted-xml-process-model.md) + +By default, Hosted XML is turned **off** in Azure DevOps Services. We turn on the Hosted XML process model during migration only if you customized a project in Azure DevOps Server. Once your project is on Hosted XML, you can [upgrade it to inherited post migration](../organizations/settings/work/hosted-xml-process-model.md). + +## Key principles + +When migrating into Azure DevOps Services, keep in mind the following key principles and limitations: + +- **Azure DevOps Services is English only**: Azure DevOps Server supports multiple languages, however today, Azure DevOps Services only supports English. If your collection uses the non-English language or used non-English in the past and you converted the language to English during an upgrade, you can’t use the Data Migration Tool. +- **Inheritance**: A project, which was created from the Agile, Scrum or CMMI process template and was never customized, is on the Inheritance process model after the migration. +- **Hosted XML**: Any project with customizations uses the Hosted XML process model. +- **Process per customized project**: Although Azure DevOps Services allows projects to share a process, the Data Migration Tool creates a Hosted XML process for each customized team project. For example, if you have 30 customized projects, you have 30 Hosted XML processes to manage. If you want to further customize your Hosted XML process for all your projects, you must update each Hosted XML process separately. +- **Process validation**: The process validation of the Data Migration Tool detects the target process model for each project. Before you can migrate, you need to fix any process validation errors for the Hosted XML projects. You might want to consider updating the process of your projects to match one of our processes (Agile, Scrum or CMMI) to take advantage of the Inheritance process model. Learn more on the process validation types in our documentation. -- [Migration and process model FAQs](faqs.yml) +## Resources + +- [Report an issue in the Developer Community](https://developercommunity.visualstudio.com/AzureDevOps/report) +- [Get support and provide feedback](../user-guide/provide-feedback.md) + +## Next steps + +> [!div class="nextstepaction"] +> [Get started with the Azure DevOps Data Migration Tool](migration-get-started.md) + +## Related articles +- [Complete prerequisites for migration](migration-prerequisites.md) +- [Validate and prepare for migration](migration-validate.md) +- [Prepare for test run](migration-prepare-test-run.md) +- [Do test run migration](migration-test-run.md) +- [Migrate to Azure DevOps Services](migration-migrate.md) +- [Complete post-migration tasks](migration-post-migration.md) diff --git a/docs/migrate/migration-post-import.md b/docs/migrate/migration-post-import.md deleted file mode 100644 index 7d1bf1e2e63..00000000000 --- a/docs/migrate/migration-post-import.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Post migration import steps to validate and configure an organization -titleSuffix: Azure DevOps -description: Guidance on how to validate and configure an organization after it has been imported to Azure DevOps Services. -ms.topic: conceptual -ms.subservice: azure-devops-migrate -ms.contentid: db186305-0d82-4152-bb04-e7b44b56305f -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 02/24/2023 ---- - -# Post import - -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - - -Once a successful import is completed, an organization is ready to use. However, before you make it available to all users, there are several common tasks you should complete. See the following list of the most typical tasks that should be completed after import, in the recommended order of execution. - -> [!NOTE] -> We recommend that you use the [Migration Guide](https://aka.ms/AzureDevOpsImport) to progress through your import. The guide links to the technical documentation as needed. -> -> With the release of Azure DevOps Server 2019 the TFS Database Import Service was rebranded to become data migration tool for Azure DevOps. This includes TfsMigrator becoming the data migration tool or migrator for short. This service still works exactly the same as the old Import Service. If you're on an older version of on-premises with TFS as the branding you can still use this feature to migrate to Azure DevOps as long as you upgrade to one of the supported versions. - - -## Immediately after import - -Immediately after the organization becomes available, take a small team and perform spot checks on the organization. We recommend that this team consists of the project collection administrators. This shouldn't be an in-depth check, but rather making sure that major pieces from your collection were brought over. Did your source code get imported? Are you seeing your build history? Are all of our area paths still present? It's best to confirm these artifacts are present before opening the organization to the entirety of your user base. - -After you check the organization, consider whether you want to rename it. [Renaming an organization](../organizations/accounts/rename-organization.md) is a simple operation, but it has [large impacts](https://support.microsoft.com/kb/2793597) on users currently using the organization. Some examples being Team Explore connections breaking or bookmarks no longer working. Getting a rename out of the way while it's just a small group of users using the organization allows the rest of the users to come in and configure their connections once. - -## Set up billing - -To pay for users or services in Azure DevOps, like hosted build and deployment agents, you need to [set up billing](../organizations/billing/set-up-billing-for-your-organization-vs.md) for your organization. If you import more than one collection, you should ensure all your organizations are set up for billing with the same Azure subscription, and that your subscription is enabled for [multi-organization billing](../organizations/billing/billing-faq.yml). You can then assign as many Basic users as you need free of charge during the calendar month in which you run the import. - -## Manage users and access - -Your organization includes five free users with [Basic](https://visualstudio.microsoft.com/products/visual-studio-team-services-feature-matrix-vs) access. Basic includes features like Git and Team Foundation version control, tools for Agile planning and Java teams, and more. Also, you can add [Visual Studio subscribers](https://visualstudio.microsoft.com/products/how-to-buy-vs) for free—they get basic features plus other features—based on their subscription level. Also, you can add [Stakeholder](../organizations/security/get-started-stakeholder.md) for free, which allows them to have partial access to Agile tools, create work items, and view backlogs and boards. - -As Visual Studio subscribers sign in to the organization, they're automatically detected. For all other users, you need to [assign paid access](../organizations/billing/buy-basic-access-add-users.md). Keep in mind, if you automate access using [group rules](../organizations/accounts/assign-access-levels-by-group-membership.md), the rules only apply to existing users if you [remove direct assignments](../organizations/accounts/assign-access-levels-by-group-membership.md#remove-direct-assignments), which were applied to users during import. - -**Behavior change**—Starting November 13, 2019, the default access behavior for imports will change. Previously, all imports tried to give users an equivalent access level post import. This means that users that had **_Basic_** received Basic access, and other users started with **_Stakeholder_** access. Once this change happens, all users start out with free **_Stakeholder_** access. **You will continue to be able to assign Basic access to any users who need it at no cost, until the end of the calendar month during which your import is run.** If you have any questions or concerns about this change, feel free to [contact us](mailto:AzureDevOpsImport@microsoft.com?subject=Default%20access%20level%20change). - -## Builds - -Next, you want to configure your build agents. As part of the migration, all of your build pipelines have been brought over, but agents and pools need to be reconfigured against the new organization. Azure DevOps offers the ability to use a Microsoft-hosted pool of build agents that you can use, or you can connect your self-hosted build agent(s). It's important to note that only one self-hosted build agent is included for free. After that there's a [fee](https://visualstudio.microsoft.com/products/visual-studio-team-services-pricing-vs.aspx) for having more self-hosted build agents. To pay for Microsoft-hosted and self-hosted build agents, you need to link a subscription to your organization. See the following resources for details on performing this task: - -* [Build Agents](../pipelines/agents/agents.md) - -If you plan on using your existing on-premises private build agents, there's one more recommended step that needs to be taken after registering them to your new organization. Clearing their cache ensures that you don't encounter any build issues related to older TFVC or Git pointers to your on-premises collection. See [refreshing caches on client computers](/azure/devops/server/admin/backup/refresh-data-caches) for details on how to accomplish this task. - -## Release management - -If you used Release Management in Azure DevOps Server, then your release pipelines and history data are included with your import. However, like builds, you need to reconfigure your [agents](../pipelines/agents/agents.md) and pools against the new organization. - -## Azure Artifacts - -Azure Artifacts is included with Azure DevOps Services for all users granted a **Basic** license. There's no need to install an extension. Your Azure Artifacts data should be available post import. - -## Azure Boards - -If you have an existing GitHub Enterprise Server connection associated with your Azure DevOps Server, it will not work as expected. Work item mentions, within GitHub, may be delayed or never show up in Azure DevOps Services. This problem occurs because the callback URL associated with GitHub is no longer valid. - -To resolve the problem, consider the following items: - -- **Remove and re-create the connection**: - Remove and re-create the connection to the GitHub Enterprise Server repository. Follow the sequence of steps provided in [Connect from Azure Boards](../boards/github/connect-to-github.md#connect-azure-devops-services-to-github-enterprise-server) documentation. - -- **Fix the webhook url**: - Go to GitHub's repository settings page and edit the webhook url to point out to the migrated Azure DevOps Services organization url: ```https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-preview``` - -## Notify your teams - -After your builds are running and license subscription is configured, we recommend that you open up the organization to all users for validation. Then individual users can ensure that all of the content is in place, they have the right access level, and that they can pull code. Be sure to point users to our [documentation](../organizations/accounts/set-up-vs.md) on connecting to Azure DevOps Services from all of our supported IDEs and Team Explorer. - -Users of TFVC with local workspaces need to remap their workspaces against the new organization and Git users have to reconfigure their remotes to be able to pull code. - -If anything is reported as missing from the migrated organization, reach out to [AzureDevOpsImport@microsoft.com](mailto:AzureDevOpsImport@microsoft.com). For other functional issues, reach out to [customer support](https://visualstudio.microsoft.com/support/). \ No newline at end of file diff --git a/docs/migrate/migration-post-migration.md b/docs/migrate/migration-post-migration.md new file mode 100644 index 00000000000..a856e6ebaec --- /dev/null +++ b/docs/migrate/migration-post-migration.md @@ -0,0 +1,86 @@ +--- +title: Complete post migration tasks +titleSuffix: Azure DevOps +description: Guidance on how to configure an organization after it migrates to Azure DevOps Services. +ms.topic: conceptual +ms.subservice: azure-devops-migrate +ms.contentid: db186305-0d82-4152-bb04-e7b44b56305f +ms.author: chcomley +author: chcomley +monikerRange: '<= azure-devops' +ms.date: 05/20/2024 +--- + +# Complete post migration tasks + +When migration completes, an email gets sent to the organization owner and at this point, anyone with access can sign in to the newly migrated Azure DevOps Services organization. But, before you make the organization available to all users, you should complete the common tasks listed within this article. + +:::image type="content" source="media/post-migration-stage-migration-highres.png" alt-text="Diagram of highlighted post-migration stage of the seven stages of migration."::: + +## Spot check + +Immediately after the organization becomes available, take a small team and do spot checks on the organization. We recommend that this team consists of the project collection administrators. This check shouldn't be in-depth, but rather making sure that major pieces from your collection were brought over. + +- **Source code:** Verify that your source code repositories migrated correctly. +- **Build history:** Ensure your build history made it over. +- **Area paths:** Confirm that all area paths are still present. + +These quick checks help you catch any missing or incomplete data before opening the organization to your entire user base. + +## Rename organization (optional) + +In the [Get started phase](migration-get-started.md), you might have already created organizations with the final Azure DevOps Services organization names that you want to use. If this is your final migration, you can rename your newly migrated Azure DevOps Services organization to that desired name. For more information, see [Rename your organization](../organizations/accounts/rename-organization.md). + +## Set up billing + +To pay for users or services in Azure DevOps, like hosted build and deployment agents, you need to set up billing for your organization. If you migrate more than one collection, you should ensure all your organizations are set up for billing with the same Azure subscription, and that your subscription is enabled for [multi-organization billing](../organizations/billing/billing-faq.yml). You can then assign as many Basic users as you need free of charge during the calendar month in which you run the migration. + +## Configure build agents + +If you used automated build or deployment servers in your Azure DevOps Server environment, you can connect them to your Azure DevOps Services organization. As part of the migration, all your build definitions got migrated, but you must reconfigure agents and pools against your new Azure DevOps Services organization. + +For more information, see [Azure Pipelines agents](../pipelines/agents/agents.md). + +If you plan to use your existing on-premises private build agents, you must clear their cache, which ensures that you don't encounter any build issues related to older Team Foundation Version Control (TFVC) or Git pointers to your on-premises collection. For more information, see refreshing caches on client computers. + +> [!TIP] +> If you used Release Management in Azure DevOps Server, then your release pipelines and history data migrated. But like with builds, you must reconfigure your agents(link again) and pools against the new organization. + +## Use Azure Artifacts + +Azure Artifacts is included with Azure DevOps Services for all users granted a Basic license. There's no need to install an extension. Your Azure Artifacts data should be available post migration. For more information, see [Azure Artifacts overview](../artifacts/start-using-azure-artifacts.md). + +## Customize Azure Boards + +If you have an existing GitHub Enterprise Server connection associated with your Azure DevOps Server, it doesn't work as expected. Work items mentioned within GitHub might be delayed or never show up in Azure DevOps Services. This problem occurs because the callback URL associated with GitHub is no longer valid. + +To resolve the problem, consider the following tasks: + +- **Remove and re-create the connection:** Remove and re-create the connection to the GitHub Enterprise Server repository. Follow the sequence of steps provided in Connect from Azure Boards documentation. +- **Fix the webhook URL:** Go to GitHub's repository settings page and edit the webhook URL to point to the migrated Azure DevOps Services organization URL: `https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-preview`. + +For more information, see [Configure and customize Azure Boards](../boards/configure-customize.md). + +## Review permissions + +Your organization includes five free users with [Basic](https://visualstudio.microsoft.com/products/visual-studio-team-services-feature-matrix-vs) access. For more information, see [Add organization users and manage access](../organizations/accounts/add-organization-users.md). + +## Notify your teams + +After your builds are running and license subscription is configured, we recommend that you open the organization to all users for validation. Then individual users can ensure that all the content is in place, has the right access level, and they can pull code. + +Users of TFVC with local workspaces must remap their workspaces against the new organization, and Git users must reconfigure their remotes to pull code. + +If anything is missing from the migrated organization, [contact Support](https://visualstudio.microsoft.com/support/). + +## Next steps + +> [!div class="nextstepaction"] +> [Get Azure DevOps Services extensions (optional)](https://marketplace.visualstudio.com/azuredevops?utm_source=ms&utm_medium=guide&utm_campaign=vstsdataimportguide) + +## Related articles + +- [Validate and prepare for migration](migration-validate.md) +- [Prepare for test run](migration-prepare-test-run.md) +- [Do test run migration](migration-test-run.md) +- [Migrate to Azure DevOps Services](migration-migrate.md) diff --git a/docs/migrate/migration-prepare-test-run.md b/docs/migrate/migration-prepare-test-run.md new file mode 100644 index 00000000000..e7aedf462ff --- /dev/null +++ b/docs/migrate/migration-prepare-test-run.md @@ -0,0 +1,284 @@ +--- +title: Prepare test run migration +description: Learn about the steps you need to take to prepare for a test run migration to Azure DevOps Service. +ms.topic: how-to +ms.subservice: azure-devops-migrate +ms.contentid: +ms.author: chcomley +author: chcomley +monikerRange: '<= azure-devops' +ms.date: 05/20/2024 +--- + +# Prepare for test run migration + +This article focuses on team preparation and file generation required by the Data Migration Tool. + +:::image type="content" source="media/prepare-test-run-stage-migration-highres.png" alt-text="Diagram of highlighted Prepare for test run stage of the seven stages of migration."::: + +## Prerequisites + +Complete the [Validate phase](migration-validate.md) before you begin to prepare for test run migration. + +## Generate migration settings + +Do the following steps to generate the migration specification and related files to queue the migration of your collection database. + +1. Run the Data Migration Tool prepare command with the following parameters: + + `/collection:http://localhost:8080/tfs/DefaultCollection/ tenantDomainName:contoso.com /Region:CUS` + + - The tenant domain name option is the name of your company’s Microsoft Entra ID tenant. + - The prepare command requires internet access. If your Azure DevOps Server lacks internet connectivity, run the command from a different computer. + - The term "organization region" refers to the location where you plan to migrate your collection into Azure DevOps Services. You previously selected a region and recorded its shorthand code. Use this code in the prepare command. + +2. Sign in with a user from the tenant who has permission to read information about all users in the Microsoft Entra ID tenant. + +## Configure the migration specification file + +The migration specification file is a JSON file that instructs the Data Migration Tool how to do the following actions. +- Configure your migrated organization +- Specify the source locations +- Customize the migration + +Many of the fields are auto populated during the prepare step but you must configure the following fields: + +- **Organization name:** The name of the organization you want to create for migrating your data. +- **Location:** A backup of your database and migration files to be uploaded to an Azure storage container. This field specifies the SAS key used by the migration tool to securely connect to and read the source files from the Azure storage container. Creating the storage container is covered later in Phase 5 and generating a SAS key is covered in Phase 6 before you queue for a new migration. +- **DACPAC:** A file that packages up your collection’s SQL database. +- **Migration type:** The type of migration: Test run or Production run. + +Each migration specification file is meant for a single collection. If you try to use a migration specification file generated for another collection, the migration doesn’t start. You need to prepare a test run for each collection you wish to migrate and use the generated migration specification file to queue the migration. + +## Review the identity map log file + +The identity map log is crucial, as important as the actual data that you migrate. When you examine the log file, understand how identity migration functions and the potential outcomes. When you migrate an identity, it can be either active or historical. Active identities can sign in to Azure DevOps Services, while historical identities can't. The service decides which type gets used. + +> [!NOTE] +> Once an identity gets migrated as a historical identity, there's no way to convert it to an active one. + +### Active identities + +Active identities refer to user identities in Azure DevOps Services post-migration. In Azure DevOps Services, these identities are licensed and are displayed as users in the organization. The identities are marked as active in the **Expected Import Status** column in the identity map log file. + +### Historical identities + +Historical identities are mapped as such in the Expected Import Status column in the identity map log file. Identities without a line entry in the file also become historical. An example of an identity without a line entry might be an employee who no longer works at a company. + +Unlike active identities, historical identities: + +- Don't have access to an organization after migration. +- Don't have licenses. +- Don't show up as users in the organization. All that persists is the notion of that identity's name in the organization, so that its history can be searched later. We recommend that you use historical identities for users who no longer work at the company or who don't need further access to the organization. + +> [!NOTE] +> After an identity migrates as historical, you can't make it active. + +### Licenses + +During migration, licenses get assigned automatically for all users displayed as "active" in the Expected Import Status column of identity mapping log. If automatic license assignment is incorrect, you can change it by editing the "access level" of one or more users after migration completes. + +Assignment might not always be perfect, so you have until the first of the following month to reassign licenses as needed. If by the first of the next month you don't link a subscription to your organization and purchased the correct number of licenses, all your grace period licenses get revoked. Alternatively, if auto assignment assigned more licenses than you purchased for next month, then we don't charge you for the extra licenses, but we revoke all unpaid licenses. + +To avoid losing access, we recommend you link a subscription and purchase needed licenses before the first of the month, as billing runs monthly. For all test runs, licenses are free for as long as the organization is active. + +### Azure DevOps subscriptions + +Visual Studio Subscriptions aren’t assigned by default for migrations. Instead, users with Visual Studio Subscriptions automatically get upgraded to use that license. If a user’s work organization is linked correctly, Azure DevOps Services automatically applies their Visual Studio subscription benefits on their first sign-in post migration. + +You don’t need to repeat a test run migration if users don’t automatically get upgraded to use their Visual Studio Subscription in Azure DevOps Services. Visual Studio Subscription linking is something that happens outside of the scope of a migration. If the work organization gets linked correctly before or after the migration, then the user automatically has their license upgraded on the next sign in. Once they’re upgraded, next time you migrate the user automatically gets upgraded upon initial sign-in to the organization. + +## Restrict access to Azure DevOps Services IPs only + +- [Option 1: Use Service Tags](#option-1-use-service-tags) +- [Option 2: Use IP List](#option-2-use-ip-list) + +Restrict access to your Azure Storage account to only IPs from Azure DevOps Services. You can restrict access by only allowing connections from Azure DevOps Services IPs that are involved in the collection database migration process. The IPs that need to be granted access to your storage account depend on the region you're migrating into. + +### Option 1: Use Service Tags + +You can easily allow connections from all Azure DevOps Services regions by adding the `azuredevops` Service Tag to your network security groups or firewalls either through the portal or programmatically. + +### Option 2: Use IP List + +Use the `IpList` command to get the list of IPs that need to be granted access to allow connections from a specific Azure DevOps Services region. + +Included in the help documentation are instructions and examples for running Migrator from the Azure DevOps Server instance itself and a remote machine. If you're running the command from one of the Azure DevOps Server instance's application tiers, your command should have the following structure: + +```cmdline +Migrator IpList /collection:{CollectionURI} /tenantDomainName:{name} /region:{region} +``` + +You can add the list of IPs to your network security groups or firewalls either through the portal or programmatically. + +### Configure IP firewall exceptions for SQL Azure + +This section only applies to configuring firewall exceptions for SQL Azure. For DACPAC migrations, see [Configure Azure Storage firewalls and virtual networks](/azure/storage/common/storage-network-security?tabs=azure-portal). + +The Data Migration Tool requires the Azure DevOps Services IPs get configured for inbound connections only on port `1433`. + +Do the following steps to grant exceptions for the necessary IPs handled at the Azure networking layer for your SQL Azure VM. + +1. Sign in to the Azure portal. +1. Go to your SQL Azure VM. +1. In **Settings**, select **Networking**. +1. Select **Add inbound port rule**. + :::image type="content" source="media/migration-import/inbound.png" alt-text="Screenshot of the Add inbound port rule button on your SQL Azure VM network interface page."::: +2. Select **Advanced** to configure an inbound port rule for a specific IP. + :::image type="content" source="media/migration-import/advanced.png" alt-text="Screenshot of the Advanced button on the Add inbound security rule pane."::: +3. In the **Source** drop-down list, select **IP Addresses**, enter an IP address that needs to be granted an exception, set the **Destination port range** to `1433` and, in the **Name** box, enter a name that best describes the exception you're configuring. + +Depending on other configured inbound port rules, you might need to change the default priority for the Azure DevOps Services exceptions, so they don't get ignored. For example, if you have a "deny on all inbound connections to 1433" rule with a higher priority than your Azure DevOps Services exceptions, the Data Migration Tool might be unable to make a successful connection to your database. + +:::image type="content" source="media/migration-import/example.png" alt-text="Screenshot of a completed inbound port rule configuration."::: + +Repeat adding inbound port rules until all necessary Azure DevOps Services IPs are granted an exception. Missing one IP could result in your migration failing to start. + +## Migrate large collections + +For databases that the Data Migration Tool warns are too large, a different data packaging approach is required to migrate to Azure DevOps Services. If you're unsure whether your collection exceeds the size threshold, you should run a Data Migration Tool validation on the collection. The validation lets you know whether you need to use the SQL Azure VM method for migration. + +### Determine if you can reduce the collection size + +Check to see whether you can clean up old data. Over time, collections can build up large volumes of data. This growth is a natural part of the DevOps process, but you might find you don't need to retain all the data. Some common examples of no longer relevant data are older workspaces and build results. + +The Data Migration Tool scans your collection and compares it to the limits mentioned previously. It then reports whether your collection is eligible for DACPAC or SQL migration method. In general, the idea is that if your collection is small enough to fit within the DACPAC limits, you can use the faster and simpler DACPAC approach. However, if your collection is too large, you need to use the SQL migration method, which involves setting up a SQL Azure VM and migrating the database manually. + +### Size limits + +The current limits are: + +- 150 GB total database size (database metadata + blobs) for DACPAC, if you exceed this limit, then you need to perform the SQL migration method. +- 30 GB individual table size (database metadata + blobs) for DACPAC, if any single table exceeds this limit, then you need to perform the SQL migration method. +- 1,536 GB database metadata size for SQL migration method. Exceeding this limit issues a warning, we advise that you keep under this size to have a successful migration. +- 2,048 GB database metadata size for SQL migration method. Exceeding this limit results in an error, so you can't perform a migration. +- No limit for blob sizes for SQL migration method. + +When you clean older, no-longer-relevant artifacts, it could remove a lot more space than you might expect, and it could determine whether you use the DACPAC migration method or a SQL Azure VM. + +> [!IMPORTANT] +> Once you delete older data, you can't recover it unless you restore an older backup of the collection. + +If you're under the DACPAC threshold, follow the instructions to generate a DACPAC for migration. If you still can't get the database under the DACPAC threshold, you need to set up a SQL Azure VM to migrate to Azure DevOps Services. + +## Set up a SQL Azure VM to migrate to Azure DevOps Services + +Do the following high-level steps to set up a SQL Azure virtual machine (VM) to migrate to Azure DevOps Services. + +1. [Set up a SQL Azure VM](#set-up-a-sql-azure-vm) +1. [Configure IP firewall exceptions](#configure-ip-firewall-exceptions-for-sql-azure) +1. [Restore your database on the VM](#restore-your-database-on-the-vm) +1. [[Configure your collection for migration](#configure-your-collection-for-migration) +1. [Configure the migration specification file to target the VM](#configure-the-migration-specification-file-to-target-the-vm) + +### Set up a SQL Azure VM +You can set up a SQL Azure VM from the Azure portal quickly. For more information, see [Use the Azure portal to provision a Windows virtual machine with SQL Server](/azure/azure-sql/virtual-machines/windows/create-sql-vm-portal?view=azuresql&preserve-view=true). + +The performance of your SQL Azure VM and attached data disks have a significant impact on the performance of the migration. For this reason, we highly recommend doing the following tasks: +- Select a VM Size at the level of `D8s_v5_*` or greater. +- Use managed disks. +- Consult [virtual machine and disk performance](/azure/virtual-machines/disks-performance). Ensure your infrastructure is configured so that the VM IOPS (input/output per second) and storage IOPS don't become a bottleneck on the performance of the migration. For example, ensure the number of data disks attached to your VM is sufficient to support the IOPS from the VM. + +Azure DevOps Services is available in several [Azure regions across the globe](migration-test-run.md#supported-azure-regions-for-migration). To ensure that the migration starts successfully, it's critical to place your data in the correct region. If you set up your SQL Azure VM in a wrong location, the migration fails to start. + +> [!IMPORTANT] +> The Azure VM requires a public IP address. + +If you're using this migration method, create your VM in a supported region. Although Azure DevOps Services is available in multiple regions in the United States (US), only the Central United States region accepts new organizations. You can't migrate your data into other US Azure regions now. + +> [!NOTE] +> DACPAC customers should consult the region table in the "Step 3: Upload the DACPAC file](migration-test-run.md#)" section. The preceding guidelines are for SQL Azure VMs only. If you're a DACPAC customer, see [supported Azure regions for migration](migration-test-run.md#supported-azure-regions-for-migration). + +Use the following SQL Azure VM configurations: +- Configure the SQL temporary database to use a drive other than drive C. Ideally the drive should have ample free space; at least equivalent to your database's largest table. +- If your source database is still over 1 terabyte (TB) after you reduced its size, you need to attach more 1-TB disks and combine them into a single partition to restore your database on the VM. +- If your collection databases are over 1 TB in size, consider using an SSD (solid state hard drives) for both the temporary database and collection database. Also, consider using larger VMs with 16 virtual CPUs (vCPUs) and 128 GB (gigabytes) of RAM (random access memory). + +## Restore your database on the VM + +After you set up and configure an Azure VM, you need to take your detached backup from your Azure DevOps Server instance to your Azure VM. The collection database needs to be restored on your SQL instance and doesn't require Azure DevOps Server to be installed on the VM. + +## Configure your collection for migration + +After your collection database restores on your Azure VM, configure a SQL sign-in to allow Azure DevOps Services to connect to the database to migrate the data. This sign-in allows only read access to a single database. + +1. Open SQL Server Management Studio on the VM, and then open a new query window against the database to be migrated. +2. Set the database's recovery to simple: + + ```sql + ALTER DATABASE [] SET RECOVERY SIMPLE; + ``` + +3. Create a SQL sign-in for the database, and assign that sign-in the 'TFSEXECROLE', like the following example. + + ```sql + USE [] + CREATE LOGIN WITH PASSWORD = '' + CREATE USER FOR LOGIN WITH DEFAULT_SCHEMA=[dbo] + EXEC sp_addrolemember @rolename='TFSEXECROLE', @membername='' + ``` + +See the following example of the SQL command: + +```sql + ALTER DATABASE [Foo] SET RECOVERY SIMPLE; + + USE [Foo] + CREATE LOGIN fabrikam WITH PASSWORD = 'fabrikampassword' + CREATE USER fabrikam FOR LOGIN fabrikam WITH DEFAULT_SCHEMA=[dbo] + EXEC sp_addrolemember @rolename='TFSEXECROLE', @membername='fabrikam' +``` + +> [!IMPORTANT] +> Enable SQL Server and Windows authentication mode in SQL Server Management Studio on the VM. If you don't enable authentication mode, the migration fails. + +### Configure the migration specification file to target the VM + +Update the migration specification file to include information about how to connect to the SQL Server instance. Open your migration specification file and make the following updates: + +1. Remove the DACPAC parameter from the source files object. + The migration specification before the change looks like the following example code. + + :::image type="content" source="media/import-spec-before.png" alt-text="Screenshot of the migration specification before the change."::: + + The migration specification after the change looks like the following example code. + + :::image type="content" source="media/import-spec-after.png" alt-text="Screenshot of the migration specification after the change."::: + +2. Enter the required parameters and add the following properties object within your source object in the specification file. + + ```json + "Properties": + { + "ConnectionString": "Data Source={SQL Azure VM Public IP};Initial Catalog={Database Name};Integrated Security=False;User ID={SQL Login Username};Password={SQL Login Password};Encrypt=True;TrustServerCertificate=True" + } + ``` + +After you apply the changes, the migration specification looks like the following example. + +:::image type="content" source="media/import-spec-iaas.png" alt-text="Screenshot of the migration specification referencing a SQL Azure VM."::: + +Your migration specification is now configured to use a SQL Azure VM for migration. Proceed with the rest of the preparation steps for migration. After the migration finishes, be sure to delete the SQL sign-in or rotate the password. Microsoft doesn't retain the sign-in information after the migration completes. + +## Create an Azure Storage Container in chosen data center + +Using the Data Migration Tool for Azure DevOps requires having an Azure Storage container in the same Azure data center as the final Azure DevOps Services organization. For example, if you intend for your Azure DevOps Services organization to be created in the Central United States data center, then create the Azure Storage container in that same data center. This action drastically speeds up the time that it takes to migrate the SQL database, since the transfer occurs within the same data center. + +For more information, see [Create a storage account](/azure/storage/common/storage-account-create?tabs=azure-portal). + +## Set up billing + +A grace period is placed on the newly migrated Azure DevOps Services organization to allow your team to finish any steps it needs and correct license assignments. If you anticipate that you might want to purchase any more user plans, build or deployment pipelines, hosted build services, hosted load test services, for example, we highly recommend that you sure you have an Azure Subscription ready for linking to your migrated organization. The grace period ends on the first day of the following month after you completed your migration. + +We remind you again in the Post-migration phase(link) for when you need to do the linking. This preparation step is more about making sure that you know which Azure Subscription you use in that later step. For more information, see [Set up billing for your organization](../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing). + +## Next steps + +> [!div class="nextstepaction"] +> [Do test run migration](migration-test-run.md) + +## Related articles + +- [Migrate to Azure DevOps Services](migration-migrate.md) +- [Complete post-migration tasks](migration-post-migration.md) + diff --git a/docs/migrate/migration-prerequisites.md b/docs/migrate/migration-prerequisites.md new file mode 100644 index 00000000000..f722996eca4 --- /dev/null +++ b/docs/migrate/migration-prerequisites.md @@ -0,0 +1,95 @@ +--- +title: Complete migration prerequisites +description: Learn about what's required before you begin migration from on-premises to the cloud in Azure DevOps Services. +ms.topic: how-to +ms.subservice: azure-devops-migrate +ms.contentid: +ms.author: chcomley +author: chcomley +monikerRange: '<= azure-devops' +ms.date: 05/20/2024 +--- + +# Complete prerequisites for migration + +As you move to the second phase of migrating to Azure DevOps Services with the Azure DevOps Data Migration Tool, you must complete the prerequisites for transferring your data to the cloud. If your organization already meets these prerequisites, you can skip this phase entirely. + +:::image type="content" source="media/prerequisites-stage-migration-highres.png" alt-text="Diagram highlighting the Prerequisites stage in sequential stages."::: + +## Update Azure DevOps Server + +The Data Migration Tool for Azure DevOps supports the [two latest releases of Azure DevOps Server](/azure/devops/server/release-notes/azuredevops2022?view=azure-devops&preserve-view=true) at a given time. Releases include updates and major releases. + +It can take up to 2-3 weeks after a new RTW version of Azure DevOps Server is released for migration support to come online for that version. Consider this possibility when you choose to upgrade shortly after a new RTW Azure DevOps Server release. + +The Data Migration Tool doesn't support migration from Azure DevOps Server release candidates (RC). If you're planning to migrate your collection database to Azure DevOps Services using this service, it's important that you don't upgrade your production database to an RC release. If you upgrade, then you must wait and upgrade to the release to web (RTW) version when it's available. Or, restore a backup copy of your database from a previous Azure DevOps Server version to migrate. You can't downgrade to a previous version of Azure DevOps, but must revert using a backup of the database at that version. + +Normal release cadence for new Azure DevOps Server versions is once every three to four months. Meaning that support for a given version of Azure DevOps Server for migration to Azure DevOps Services should last for anywhere between six-to-eight months. It's important to ensure that your plan accounts for this support window to avoid having to suddenly upgrade to migrate. + +## Implement Microsoft Entra ID + +Ensure your team has a functional Microsoft Entra ID tenant for authenticating members in your Azure DevOps Services organization. In Azure DevOps Services, user authentication relies on a Microsoft Entra ID tenant like Azure DevOps Server user authentication relies on Active Directory. During the Test Run phase(link), you verify an identity map log file to match your on-premises Active Directory organizations with Microsoft Entra ID organizations. This file isn't used by the migration service. This action ensures individual history visibility, security permissions preservation, and access to personal settings. + +> [!TIP] +> - We recommend that you use the same Microsoft Entra ID tenant as other Microsoft Cloud services. If your company already has Microsoft Entra ID, skip this step. +> - While Microsoft accounts (MSAs) work for Azure DevOps Services authentication, they can't be mapped during Azure DevOps Server database migration. + +### Synchronize identities and groups with Microsoft Entra ID Connect + +Synchronize your on-premises Active Directory with Microsoft Entra ID, so your team members can use the same credentials to authenticate. Also, your Azure DevOps Services administrators can use your Active Directory groups for setting permissions within your organization. + +To set up the synchronization, do the following steps: +1. Utilize the [Microsoft Entra ID Connect](https://aka.ms/AzureADConnect) technology. +2. To configure Microsoft Entra ID Connect with your on-premises environment, collaborate with your IT department, DevOps Partner, Microsoft Premier Support, or Microsoft Consulting Services. + +For more information on setting up Microsoft Entra ID Connect, see [Microsoft Entra Connect Sync](https://aka.ms/AzureADConnect). + +Also, explore how you can configure Azure DevOps Services to use Microsoft Entra ID by visiting this page. Although the steps in that article don’t align exactly with your Team Foundation Server database migration, it serves as valuable reference information. The Data Migration Tool establishes the link to your Microsoft Entra ID tenant during the creation of your Azure DevOps Services organization at the start of the migration process. + +> [!NOTE] +> DirSync was a predecessor technology to Microsoft Entra ID Connect. Upgrade to Microsoft Entra ID Connect if you’re using DirSync. + +## Download Azure DevOps Data Migration Tool + +The bulk of the work throughout the migration to Azure DevOps Services gets handled by the Data Migration Tool. The tool gets used with the following high-level steps: + +1. Validate a team project collection. +1. Generate the files used to customize the migration. +1. Queue migration of an Azure DevOps Server database to Azure DevOps Services. + +Have the following items: + +- TFSEXECROLE role in SQL Server. +- Permissions to connect to both the Azure DevOps Server configuration and collection databases. +- An established link between your Azure DevOps Services organization and your Microsoft Entra ID tenant. + +### Download the tool + +1. Download the latest version of the [Data Migration Tool.](https://www.microsoft.com/download/details.aspx?id=54274) +2. Copy the zip file to one of your Azure DevOps Server application tiers. +3. Unzip the file. + You can also run the tool from a different machine without Azure DevOps Server installed, if it can connect to the configuration database of the Azure DevOps Server instance. +1.Open a Command Prompt window on the server and go to the directory where the Data Migration Tool is stored. +1. Review the help content for the tool: + 1. To view the top-level help and guidance, run the following command: + `Migrator /help` + 2. View the help text for the validation command: + `Migrator validate /help` + For your first time validating a collection, keep it simple. Your command should have the following structure: + `Migrator validate /collection:{collection URL} /tenantDomainName:{name} /region:{region}` +2. Replace {name} with the name of your Microsoft Entra tenant. For example, to run against the DefaultCollection and the fabrikam tenant, the command would look like this: + `Migrator validate /collection:[^1^][4] (http://localhost:8080/DefaultCollection) /tenantDomainName:fabrikam.OnMicrosoft.com /region:{region}` + If you need to run the tool from a machine other than the Azure DevOps Server, use the `/connectionString` parameter. + +## Next steps + +> [!div class="nextstepaction"] +> [Validate and prepare for migration](migration-validate.md) + +## Related articles + +- [Prepare for test run](migration-prepare-test-run.md) +- [Do test run migration](migration-test-run.md) +- [Migrate to Azure DevOps Services](migration-migrate.md) +- [Complete post-migration tasks](migration-post-migration.md) + \ No newline at end of file diff --git a/docs/migrate/migration-processtemplates.md b/docs/migrate/migration-processtemplates.md deleted file mode 100644 index eeb8615afcb..00000000000 --- a/docs/migrate/migration-processtemplates.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: Validation of process templates for migration import -titleSuffix: Azure DevOps -description: Guidance for fixing common data migration tool process template issues. -ms.topic: troubleshooting -ms.subservice: azure-devops-migrate -ms.contentid: ee8c290d-0b48-4cbd-b7fd-7afb9591c169 -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 04/01/2021 ---- - -# Validate and resolve errors related to process templates - -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - -As part of the migration import process, the data migration tool checks the process used by the projects in the collection. Fix any errors that get flagged. - -After resolving the errors, rerun the data migration tool's `validate` command to verify that all errors have been fixed. - -> [!NOTE] -> It's recommended that you use the [Migration Guide](https://aka.ms/AzureDevOpsImport) to progress through your import. The guide links to the technical documentation as needed. -> -> With the release of Azure DevOps Server 2019 the TFS Database Import Service was rebranded to Migrate to Azure DevOps. This includes TfsMigrator becoming the data migration tool or migrator for short. This service still works exactly the same as the old Import Service. If you're on an older version of on-premises with TFS as the branding you can still use this feature to migrate to Azure DevOps as long as you upgrade to one of the supported versions. - - - -## Process validation types - -During validation, the data migration tool determines the target process model for each project. It automatically assigns one of the following two process models to each project in the collection: -- **Inherited process model**: If the project was created with the Agile, Scrum, or CMMI process template, and was never customized. -- **Hosted XML process model**: If the project process appears to have been customized. A customized process contains custom fields, work item types, or other types of customizations. - -When the Hosted XML process is the targeted process model, the data migration tool validates if the customizations can be migrated. The data migration tool generates two files during the validation: - -- **DataMigrationTool.log**: Contains the set of process validation errors found in the collection. Fix all process errors found to proceed with your migration. - -- **TryMatchOobProcesses.log**: Lists for each project the target process model - Inheritance or Hosted XML. For projects that are set to target the Hosted XML process model, it explains why they are considered to be customized. You don't have to fix these errors, but they give you guidance what to do in case you want to migrate to the Inheritance process model. Note that once a collection is imported, you can migrate a project to an Inheritance process model. - -Most customers have a mix of projects within a collection. Some projects use a default process template and others use custom process templates. The data migration tool checks and validates each project accordingly. It is very possible that you'll have a mix of projects, some mapped to an Inherited process and others to a Hosted XML process. - -We recommend that for any project that has not been customized, that you review the **TryMatchOobProcesses.log** to determine if there are any errors. If so, make the adjustments accordingly so that the project can be mapped to an Inherited process upon data import. - -## Update to a system process - -If you started with an older version of Azure DevOps Server, odds are your projects are still using an older process template. If those projects have not been updated using the [Configure Features Wizard](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) then the data migration tool will find process errors. In some rare cases, if your process is very old, even the Configure Features Wizard won't be able to resolve the errors. - -Here are some examples of error messages you may receive: - -```no-highlight -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element PortfolioBacklog is missing from Process Configuration. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element BugWorkItems is missing from Process Configuration. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element FeedbackRequestWorkItems is missing from Process Configuration. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element FeedbackResponseWorkItems is missing from Process Configuration. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Team. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField RemainingWork. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Order. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Effort. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Activity. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationStartInformation. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationLaunchInstructions. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationType. -Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF400572: The Project Process Settings must be configured for this feature to be used. -``` - -If you have never customized your project (added fields, work item types, etc.), then fixing these errors is actually pretty simple. If you have customized your process, then this approach won't work. You'll need to manually change the process templates so that your customizations don't get overwritten. - -First, make sure you know what process your project started as. Is it Scrum, Agile or CMMI? In this example, let us assume Agile. Next, go to the [Process Customization Scripts](https://github.com/Microsoft/process-customization-scripts) provided on GitHub and download the repo. In this instance, we are going to focus on contents in the -**Import** folder. - -Use the **ConformProject.ps1** script to conform a project of your choosing to the Agile system process. This will update the entire project to be Agile. - -``` -.\ConformProject.ps1 "" "" "c:\process-customization-scripts\import\agile" -``` - -Make sure you do this for each and every project. - - - -## Resolve process errors - -Are your process templates customized? Are you using an older outdated process template? If so, you'll most likely have process validation errors. The data migration tool does an exhaustive check against your process templates. It checks to make sure that it is valid for Azure DevOps Services. Odds are that you'll need to make some adjustments and apply them to your collection. - -> [!NOTE] -> If you are using an OOB Agile, Scrum, or CMMI process, you probably won't see any errors in the **DataMigrationTool.log**. Instead, check the **TryMatchOobProcesses.log** for errors. If you are error free, then your project will map to an OOB process. - -There are several customizations that won't work in Azure DevOps Services. Make sure you review the [list of customizations](../organizations/settings/work/import-process/differences.md) that are supported. - -If you have projects that are using an older process template, the data migration tool will find several errors. This is because your process templates hasn't been updated to match the most recent process templates. To start, try running the [Configure Features Wizard](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) for each project. This will attempt to update your process templates with the most recent features. Doing so should drastically reduce the error count. - -Finally, make sure you have [`witadmin`](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) on the machine that you intend to use to fix the process errors. This can be your local desktop. The `witadmin` command line tool is used in the automated scripts and is required whenever making changes to the process templates. - -## Step 1 - Review errors - -**DataMigrationTool.log** file will be generated and contains the list of errors that the validation process found. To view the logs, open DataMigrationTool.log file. Search for the string "Validation - Starting validation of project 1". Each project is validated. Scan through all the projects and search for any lines that contain a prefix of **[Error ...**. - -![Process logging file generated by the data migration tool](media/migration-troubleshooting/witLogFile.png) - -For a list of validation errors, see [Resolve validation errors for process import](../organizations/settings/work/import-process/resolve-errors.md). For each validation error, we have provided the error number, description, and the method to resolve. - -## Step 2 - Fix errors - -Once you've determined which projects have errors and the error details, fix the errors. Fixing the errors requires that you change the XML syntax and apply the changes back to the project. - -> [!NOTE] -> We recommend you don't use TFS Power Tools to do this work. Instead, we highly recommended that you modify the XML manually. - -To get the process template from the project add the **/SaveProcesses** parameter when running the data migration tool command. - -```cmdline -Migrator validate /collection:{collection URL} /SaveProcesses -``` - -This command will extract the XML from the project and place it into the same folder as the logs. Extract the zip files to your local machine so that you can edit the files. - -Now, fix the XML. Use the logs from the ```DataMigrationTool.log``` file to determine the errors for each project. - -![Process logging file generated by the data migration tool](media/migration-troubleshooting/witLogFile.png) - -Some errors will require you to do use a [`witadmin changefield`](../reference/witadmin/manage-work-item-fields.md) command. Changing a field name is the most common example. To save yourself some time, we recommend you run the `witadmin changefield` command and then re-run the data migration tool. Doing this will re-export the XML with the corrected names. Otherwise, you'll need to manually fix the fields in the XML syntax as well. - -Once you make a fix, apply the changes back to the Azure DevOps Server. To do this, depending on the changes you made, you'll need to run one or more [`witadmin`](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) commands. To make this easier for you, we created a PowerShell script to automate the process. The script contains all of the `witadmin` commands needed to conform the entire process. - -You can get the scripts at [Process Customization Scripts](https://github.com/Microsoft/process-customization-scripts). Use the **import/ConformProject.ps1** script. - -```cmdline -.\conformproject.ps1 "" "" "" -``` -![Conform project processes script running](media/migration-troubleshooting/conformProjectProcessesPowerShell.png) - -When the script has completed, re-run the data migration tool to validate the collection. Follow steps 1 through 3 until the data migration tool generates no more validation errors. - -> [!TIP] -> If you are new to XML and `witadmin`, we suggest you make one fix at a time and then conform. Continue this loop until all errors are resolved. - -## Common validation errors - -#### VS402841: Field X in work item type Bug has syncnamechanges=false but has rules making it an identity field. Identity fields must have syncnamechanges=true. Please update your process template to include this change. - -In Azure DevOps Services we added a rule so that every identity field must have the **syncnamechanges=true** attribute. In Azure DevOps Server that rule does not apply. Therefore, the data migration tool will identify this as an issue. Don't worry, making this change on Azure DevOps Server on-prem will not cause any harm. - -Run the `witadmin changefield` command. Syntax for the command looks similar to the following: - -```cmdline -witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /syncnamechanges:true -``` - -For more information on the `witadmin changefield` command see [Manage work item fields](../reference//witadmin/manage-work-item-fields.md). - -#### TF402556: For field System.IterationId to be well defined, you must name it Iteration ID and set its type to Integer. - -This error is typical for old process templates. Try running the [Configure Features Wizard](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) on each project. Alternatively you can run the follow `witadmin` command: - -```cmdline -witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /name:newname -``` -#### TF402571: Required element BugWorkItems is missing from Process Configuration. - -This error typically occurs when a process hasn't been updated in a while. Try running the [configure features wizard](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) on each project to resolve. - -#### TF402564: You've defined XX global lists. Only 64 are allowed. - -By default, Azure DevOps Services will support 64 global lists. You'll typically run across this error if you have a large amount of build pipelines. The global list named Builds - **TeamProjectName** gets created for each new build pipeline. You'll need to remove the outdated global lists. - -## Related articles - -- [Migration and process model FAQs](faqs.yml) -- [`witadmin`: Customize and manage objects for tracking work](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) -- [Differences between Azure DevOps Services and Azure DevOps Server process template customizations](../organizations/settings/work/import-process/differences.md) -- [Configure features after Azure DevOps Server upgrade](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) -- [Resolve validation errors](../organizations/settings/work/import-process/resolve-errors.md) -- [Define global lists in Azure DevOps Server](/previous-versions/azure/devops/reference/xml/define-global-lists) -- [Process customization PowerShell scripts](https://github.com/Microsoft/process-customization-scripts) diff --git a/docs/migrate/migration-test-run.md b/docs/migrate/migration-test-run.md new file mode 100644 index 00000000000..42e7e59bdba --- /dev/null +++ b/docs/migrate/migration-test-run.md @@ -0,0 +1,574 @@ +--- +title: Test run migration +titleSuffix: Azure DevOps +description: How to do a test run, migrating from on-premises to the cloud in Azure DevOps Services. +ms.topic: how-to +ms.subservice: azure-devops-migrate +ms.contentid: 829179bc-1f98-49e5-af9f-c224269f7910 +ai-usage: ai-assisted +ms.author: chcomley +author: chcomley +monikerRange: '<= azure-devops' +ms.date: 04/04/2025 +--- + +# Do test run migration + +Your team is now ready to begin the process of starting a test run of your migration and then finally a full production migration. In this phase, we discuss the final steps to queue a migration in addition to other tasks that typically come up at the end of the migration project. + +:::image type="content" source="media/test-run-stage-migration-highres.png" alt-text="Diagram highlighting the Prerequisites stage in sequential stages."::: + +## Prerequisites + +Complete the [Prepare test run phase](migration-prepare-test-run.md) before you begin a test run migration. + +> [!IMPORTANT] +> To ensure a smooth migration process, perform one or more test run imports. A test run import lasts for 45 days for testing and validation. After 45 days, the test run times out and gets removed, requiring you to start over if needed. +> The more time that passes between the test run and production run, the more the service might change, potentially introducing errors that a fresh test run would catch. You can rerun the test run import as many times as needed. Each import begins from the initial state of the imported database, as it's not possible for changes from one import to persist to another. +> Note the following points: +> - You can't extend a test run indefinitely +> - You can't promote a test run to a production run +> - A test run gets deleted if any of the following occur: +> - The test run times out +> - A new test run with the same name is run +> - A production run starts +> - The organization is manually deleted via organization settings + +## Validate a collection + +Validate each collection that you want to migrate to Azure DevOps Services. The validation step examines various aspects of your collection, including, but not limited to, size, collation, identity, and processes. + +Run the validation by using the Data Migration Tool. +1. [Download the Data Migration Tool](https://azure.microsoft.com/products/devops/migrate/). +2. Copy the zip file to one of your Azure DevOps Server application tiers. +3. Unzip the file. + You can also run the tool from a different machine without Azure DevOps Server installed, as long as the machine can connect to the configuration database of the Azure DevOps Server instance. +4. Open a Command Prompt window on the server, and enter a cd command to change to the directory where the Data Migration Tool is stored. Take a few moments to review the help content for the tool. + + a. To view the top-level help and guidance, run the following command. + + ```cmdline + Migrator /help + ``` + + b. View the help text for the command. + + ```cmdline + Migrator validate /help + ``` + +5. As your first time validating a collection, your command should have the following simple structure. + + ```cmdline + Migrator validate /collection:{collection URL} /tenantDomainName:{name} /region:{region} + ``` + + Where `{name}` provides the name of your Microsoft Entra tenant, for example, to run against the *DefaultCollection* and the *fabrikam* tenant, the command would look like the following example. + + ```cmdline + Migrator validate /collection:http://localhost:8080/DefaultCollection /tenantDomainName:fabrikam.OnMicrosoft.com /region:{region} + ``` + +6. To run the tool from a machine other than the Azure DevOps Server, you need the **/connectionString** parameter. The connection string parameter points to your Azure DevOps Server configuration database. As an example, if the validated command runs by the Fabrikam corporation, the command would look like. + + ```cmdline + Migrator validate /collection:http://fabrikam:8080/DefaultCollection /tenantDomainName:fabrikam.OnMicrosoft.com /region:{region} /connectionString:"Data Source=fabrikam;Initial Catalog=Configuration;Integrated Security=True" + ``` + + > [!Important] + > The Data Migration Tool *does not* edit any data or structures in the collection. It reads the collection only to identify issues. + +7. After the validation is complete, you can view the log files and results. + + :::image type="content" source="media/migration-import/tfsmigratorConsole.png" alt-text="Screenshot of the validation results and logs in the Command Prompt window."::: + + During validation, you receive a warning if some of your pipelines contain per-pipeline retention rules. Azure DevOps Services uses a [project-based retention model](../pipelines/policies/retention.md?view=azure-devops&preserve-view=true) and doesn't support per-pipeline retention policies. If you proceed with the migration, the policies aren't carried over to the hosted version. Instead, the default project-level retention policies apply. Retain builds important to you to avoid their loss. + + After all the validations pass, you can move to the [next step of the migration process](#import-log-files). If the Data Migration Tool flags any errors, correct them before you proceed. For guidance on correcting validation errors, see [Troubleshoot migration and migration errors](migration-troubleshooting.md). + +### Import log files + +When you open the log directory, you might notice several logging files. + +The main log file is named *DataMigrationTool.log*. It contains details about everything that was run. To make it easier for you to focus on specific areas, a log generates for each major validation operation. + +For example, if TfsMigrator reports an error in the "Validating Project Processes" step, you can open the *ProjectProcessMap.log* file to view everything that was run for that step instead of having to scroll through the entire log. + +Review the *TryMatchOobProcesses.log* file only if you're trying to migration your project processes to use the inherited model. If you don't want to use the inherited model, you can ignore these errors, because they don't prevent you from importing to Azure DevOps Services. For more information, see the [Validate phase of migration](migration-validate.md). + +## Generate migration files + +The Data Migration Tool validated the collection and it's returning a result of "All collection validations passed." Before you take a collection offline to migrate it, generate the migration files. When you run the `prepare` command, you generate two migration files: + +- *IdentityMapLog.csv*: Outlines your identity map between Active Directory and Microsoft Entra ID. +- *migration.json*: Requires you to fill out the migration specification you want to use to kick off your migration. + +### Prepare command + +The `prepare` command assists with generating the required migration files. Essentially, this command scans the collection to find a list of all users to populate the identity map log, *IdentityMapLog.csv*, and then tries to connect to Microsoft Entra ID to find each identity's match. To do so, your company needs to use the [Microsoft Entra Connect tool](/azure/active-directory/connect/active-directory-aadconnect) (formerly known as the Directory Synchronization tool, Directory Sync tool, or DirSync.exe tool). + +If directory synchronization is set up, the Data Migration Tool should find the matching identities and mark them as *Active*. If there are no matches, the identity is marked as *Historical* in the identity map log, so you must investigate why the user isn't included in your directory sync. The migration specification file, *migration.json*, should be populated before the migration. + +Unlike the `validate` command, `prepare` *does* require an internet connection, because it needs to connect to Microsoft Entra ID to populate the identity map log file. If your Azure DevOps Server instance doesn't have internet access, run the tool from a machine that does. As long as you can find a machine with an intranet connection to your Azure DevOps Server instance and an internet connection, you can run this command. For help with the `prepare` command, run the following command: + +```cmdline +Migrator prepare /help +``` + +Included in the help documentation are instructions and examples for running the `Migrator` command from the Azure DevOps Server instance itself and a remote machine. If you're running the command from one of the Azure DevOps Server instance's application tiers, your command should have the following structure: + +```cmdline +Migrator prepare /collection:{collection URL} /tenantDomainName:{name} /region:{region} +``` + +```cmdline +Migrator prepare /collection:{collection URL} /tenantDomainName:{name} /region:{region} /connectionString:"Data Source={sqlserver};Initial Catalog=Configuration;Integrated Security=True" +``` + +The **connectionString** parameter is a pointer to the configuration database of your Azure DevOps Server instance. As an example, if the Fabrikam corporation runs the `prepare` command, the command looks like the following example: + +```cmdline +Migrator prepare /collection:http://fabrikam:8080/DefaultCollection /tenantDomainName:fabrikam.OnMicrosoft.com /region:{region} /connectionString:"Data Source=fabrikam;Initial Catalog=Configuration;Integrated Security=True" +``` + +When the Data Migration Tool runs the `prepare` command, it runs a complete validation to ensure that nothing changed with your collection since the last full validation. If any new issues are detected, no migration files are generated. + +Shortly after the command starts running, a Microsoft Entra sign-in window displays. Sign in with an identity that belongs to the tenant domain, which is specified in the command. Make sure that the specified Microsoft Entra tenant is the one you want your future organization to be backed with. In our Fabrikam example, a user enters credentials that are similar to the following example screenshot. + +> [!IMPORTANT] +> Don't use a test Microsoft Entra tenant for a test migration and your production Microsoft Entra tenant for the production run. Using a test Microsoft Entra tenant can result in identity migration issues when you begin your production run with your organization's production Microsoft Entra tenant. + +When you run the `prepare` command successfully in the Data Migration Tool, the results window displays a set of logs and two migration files. In the log directory, find a logs folder and two files: + +* *migration.json* is the migration specification file. We recommend that you take time to fill it out. +* *IdentityMapLog.csv* contains the generated mapping of Active Directory to Microsoft Entra identities. Review it for completeness before you kick off a migration. + +The two files are described in greater detail in the next sections. + +### The migration specification file + +The migration specification, *migration.json*, is a JSON file that provides migration settings. It includes the desired organization name, storage account information, and other information. Most of the fields are autopopulated, and some fields require your input before you attempt a migration. + +![Screenshot of a newly generated migration specification file.](media/migration-import/importSpecHalfFilledOut.png) + +The *migration.json* file's displayed fields and required actions are described in the following table: + +| Field | Description | Required action | +| --- | --- | --- | +| Source | Information about the location and names of the source data files that are used for migration. | No action required. Review information for the subfield actions to follow. | +| Location | The shared access signature key to the Azure storage account that hosts the data-tier application package (DACPAC). | No action required. This field is covered in a later step. | +| Files | The names of the files containing migration data. | No action required. Review information for the subfield actions to follow. | +| DACPAC | A DACPAC file that packages the collection database to be used to bring in the data during the migration. | No action required. In a later step, you create this file by using your collection and then upload it to an Azure storage account. Update the file based on the name you use when you generate it later in this process. | +| Target | Properties of the new organization to migration into. | No action required. Review information for the subfield actions to follow. | +| Name | The name of the organization to be created during the migration. | Provide a name. The name can be quickly changed later after the migration completed.
      **NOTE**: *Don't* create an organization with this name before you run the migration. The organization is created as part of the migration process. | +| ImportType | The type of migration that you want to run. | No action required. In a later step, select the type of migration to run. | +| Validation Data | Information needed to help drive your migration experience. | The Data Migration Tool generates the "ValidationData" section. It contains information to help drive your migration experience. Don't* edit the values in this section, or your migration could fail to start. | + +After you complete the preceding process, you should have a file that looks like the following example. + +![Screenshot of a partially completed migration specification file.](media/migration-import/importSpecHalfFilledOut.png) + +In the preceding image, the planner of the Fabrikam migration added the organization name *fabrikam-import* and selected CUS (Central United States) as the geographical location for migration. Other values were left as is to be modified just before the planner took the collection offline for the migration. + +> [!NOTE] +> Test run imports have a '-dryrun' automatically appended to the end of the organization name, which you can change after the migration. + +### Supported Azure regions for migration + +Azure DevOps Services is available in several [Azure geographical locations](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/). But, not all locations where Azure DevOps Services is available are supported for migration. The following table lists the Azure geographical locations that you can select for migration. Also included is the value that you need to place in the migration specification file to target that geography for migration. + +| Geographical location | Azure geographical location | Import specification value | +| --- | --- | --- | +| United States | Central United States | CUS | +| Europe | Western Europe | WEU | +| United Kingdom | United Kingdom South | UKS| +| Australia | Australia East | EAU | +| South America | Brazil South | SBR | +| Asia Pacific | South India | MA | +| Asia Pacific | Southeast Asia (Singapore) | SEA | +| Canada | Central Canada | CC | + +### The identity map log + +The identity map log is of equal importance to the actual data that you migrate to Azure DevOps Services. As you're reviewing the file, it's important to understand how identity migration operates and what the potential results could entail. When you migrate an identity, it can become either *active* or *historical*. Active identities can sign in to Azure DevOps Services, but historical identities can't. + +#### Active identities + +Active identities refer to user identities in Azure DevOps Services post-migration. In Azure DevOps Services, these identities are licensed and are displayed as users in the organization. The identities are marked as *active* in the **Expected Import Status** column in the identity map log file. + + + +#### Historical identities + +Historical identities are mapped as such in the **Expected Import Status** column in the identity map log file. Identities without a line entry in the file also become historical. An example of an identity without a line entry might be an employee who no longer works at a company. + +Unlike active identities, historical identities: +* *Don't* have access to an organization after migration. +* *Don't* have licenses. +* *Don't* show up as users in the organization. All that persists is the notion of that identity's name in the organization, so that its history can be searched later. We recommend that you use historical identities for users who no longer work at the company or who don't need further access to the organization. + +> [!NOTE] +> After an identity is imported as historical, it *can't* become active. + +### Understand the identity map log file + +The identity map log file is similar to the example shown here: + +![Screenshot of an identity map log file that's generated by the Data Migration Tool.](media/migration-import/identityMapNewlyGenerated.png) + +The columns in the identity map log file are described in the following table: + +You and your Microsoft Entra admin must investigate users marked as *No Match Found (Check Microsoft Entra ID Sync)* to understand why they aren't part of your Microsoft Entra Connect Sync. + +| Column | Description | +| --- | --- | +| Active Directory: User (Azure DevOps Server) | The friendly display name used by the identity in Azure DevOps Server. This name makes it easier to identify which user the line in the map is referencing. | +| Active Directory: Security Identifier | The unique identifier for the on-premises Active Directory identity in Azure DevOps Server. This column is used to identify users in the collection. | +| Microsoft Entra ID: Expected Import User (Azure DevOps Services) | Either the expected sign-in address of the matched soon-to-be-active user or *No Match Found (Check Microsoft Entra ID Sync)*, which indicates that the identity got lost during the Microsoft Entra ID Sync and is imported as historical. | +| Expected Import Status | The expected user migration status: either *Active* if there's a match between your Active Directory and Microsoft Entra ID, or *Historical* if there isn't a match. | +| Validation Date | The last time the identity map log was validated. | + +As you read through the file, notice whether the value in the **Expected Import Status** column is *Active* or *Historical*. *Active* indicates that the identity on this row maps correctly on migration becomes active. *Historical* means that the identities become historical on migration. It's important to review the generated mapping file for completeness and correctness. + +> [!IMPORTANT] +> The migration fails if major changes occur to your Microsoft Entra Connect security ID sync between migration attempts. You can add new users between test runs, and you can make corrections to ensure that previously imported historical identities become active. But, you can't change an existing user that was previously imported as active. Doing so causes your migration to fail. An example of a change is completing a test run migration, deleting an actively imported identity from Microsoft Entra ID, re-creating the user in Microsoft Entra ID, and then attempting another migration. In this case, an active identity migration attempts between the Active Directory and newly created Microsoft Entra identity, but causes a migration failure. + +1. Review the correctly matched identities. Are all the expected identities present? Are the users mapped to the correct Microsoft Entra identity? + + If any values need to be updated, contact your Microsoft Entra administrator to ensure the on-premises Active Directory identity is synced with Microsoft Entra ID and configured correctly. For more information, see [Integrate your on-premises identities with Microsoft Entra ID](/azure/active-directory/hybrid/whatis-hybrid-identity). + +2. Next, review the identities that are labeled as *historical*. This labeling implies that a matching Microsoft Entra identity couldn't be found, for any of the following reasons: + + * The identity isn't set up for sync between on-premises Active Directory and Microsoft Entra ID. + * The identity isn't populated in your Microsoft Entra ID yet (for example, there's a new employee). + * The identity doesn't exist in your Microsoft Entra instance. + * The user who owns that identity no longer works at the company. + +To address the first three reasons, set up the intended on-premises Active Directory identity to sync with Microsoft Entra ID. For more information, see [Integrate your on-premises identities with Microsoft Entra ID](/azure/active-directory/hybrid/how-to-connect-sync-change-the-configuration). You must set up and run Microsoft Entra Connect for identities to be imported as *active* in Azure DevOps Services. + +You can ignore the fourth reason, because employees who are no longer at the company should be imported as *historical*. + +#### Historical identities (small teams) + +> [!NOTE] +> Only small teams should consider the identity migration strategy proposed in this section. + +If Microsoft Entra Connect isn't configured, all users in the identity map log file are marked as *historical*. Running a migration this way results in all users being imported as [*historical*](#historical-identities). We strongly recommended that you configure [Microsoft Entra Connect](/azure/active-directory/hybrid/how-to-connect-sync-change-the-configuration) to ensure that your users are imported as *active*. + +Running a migration with all historical identities has consequences that need to be considered carefully. Only teams with a few users and for which the cost of setting up Microsoft Entra Connect is deemed too high should consider. + +To migration all identities as historical, follow the steps outlined in later sections. When you queue a migration, the identity used to queue the migration is bootstrapped into the organization as the organization owner. All other users are imported as historical. Organization owners can then [add the users back in](../organizations/accounts/add-organization-users.md?toc=/azure/devops/organizations/accounts/toc.json&bc=/azure/devops/organizations/accounts/breadcrumb/toc.json) by using their Microsoft Entra identity. The added users are treated as new users. They don't* own any of their history, and there's no way to reparent this history to the Microsoft Entra identity. However, users can still look up their premigration history by searching for their `\\`. + +The Data Migration Tool displays a warning if it detects the complete historical identities scenario. If you decide to go down this migration path, you need to consent in the tool to the limitations. + +### Visual Studio subscriptions + +The Data Migration Tool can't detect Visual Studio subscriptions (formerly known as MSDN benefits) when it generates the identity map log file. Instead, we recommend that you apply the auto license upgrade feature after the migration. As long as users' work accounts are [linked](/visualstudio/subscriptions/vs-alternate-identity) correctly, Azure DevOps Services automatically applies their Visual Studio subscription benefits at their first sign-in after the migration. You're never charged for licenses that are assigned during the migration, so you can safely handle subscriptions afterward. + +You don't need to repeat a test run migration if users' Visual Studio subscriptions aren't automatically upgraded in Azure DevOps Services. Visual Studio subscription linking happens outside the scope of a migration. As long as their work account is linked correctly before or after the migration, users' licenses are automatically upgraded on their next sign-in. After their licenses are upgraded successfully, the next time you run a migration, the users are upgraded automatically on their first sign-in to the organization. + +## Prepare for migration + +Now you have everything ready to execute on your test run migration. Schedule downtime with your team to take the collection offline for the migration. When you agree upon a time to run the migration, upload the required assets you generated and a copy of the database to Azure. Preparing for migration consists of the following five steps. + +Step 1: [Take the collection offline and detach it](#step-1-detach-your-collection). +Step 2: [Generate a DACPAC file from the collection you're going to migrate](#step-2-generate-a-dacpac-file). +Step 3: [Upload the DACPAC file and migration files to an Azure storage account](#step-3-upload-the-dacpac-file). +Step 4: [Generate an SAS token to access the storage account](#step-4-generate-an-sas-token). +Step 5: [Complete the migration specification](#step-5-complete-the-migration-specification). + +> [!NOTE] +> Before performing a production migration, we *strongly* recommend completing a test run migration. A test run allows you to validate that the migration process works for your collection and ensures there are no unique data shapes or issues that could cause a production migration to fail. + +### Step 1: Detach your collection + +[Detaching the collection](/azure/devops/server/admin/move-project-collection#detach-coll) is a crucial step in the migration process. Identity data for the collection resides in the Azure DevOps Server instance's configuration database while the collection is attached and online. When a collection is detached from the Azure DevOps Server instance, it takes a copy of that identity data and packages it with the collection for transport. Without this data, the identity portion of the migration *can't* be executed. + +> [!TIP] +> Keep the collection detached until the migration completes to avoid losing any changes made during the migration, as these changes can't get migrated afterward. After backing up your collection for migration, you can reattach it. However, any changes made after the backup aren't included in the migration, which might raise concerns about having the most current data. You can use an offline detach for test runs, but this process might not align with recommended migration practices. Review the documentation on [offline detach](/azure/devops/server/command-line/tfsconfig-cmd#offlinedetach) to fully understand its implications and how it fits into your migration strategy. + +It's important to weigh the cost of choosing to incur zero downtime for a test run. It requires taking backups of the collection and configuration database, restoring them on a SQL instance, and then creating a detached backup. A cost analysis could prove that taking just a few hours of downtime to directly take the detached backup is better in the end. + + + +### Step 2: Generate a DACPAC file + +DACPACs offer a fast and relatively easy method for moving collections into Azure DevOps Services. However, after a collection database size exceeds a certain threshold, the benefits of using a DACPAC start to diminish. + +> [!NOTE] +> If the Data Migration Tool displays a warning that you can't use the DACPAC method, you have to perform the migration by using the SQL Azure virtual machine (VM) method. Skip steps 2 to 5 in that case and follow instructions in the [Prepare test run phase, Migrate large collections section](migration-prepare-test-run.md#migrate-large-collections), and then continue to [determine the migration type](#determine-the-migration-type). +> If the Data Migration Tool doesn't display a warning, use the DACPAC method described in this step. + +[DACPAC](/sql/relational-databases/data-tier-applications/data-tier-applications) is a feature of SQL Server that allows databases to be packaged into a single file and deployed to other instances of SQL Server. A DACPAC file can also be restored directly to Azure DevOps Services, so you can use it as the packaging method for getting your collection's data in the cloud. + +> [!IMPORTANT] +> - When you use SqlPackage.exe, you must use the .NET Framework version of SqlPackage.exe to prepare the DACPAC. The MSI Installer must be used to install the .NET Framework version of SqlPackage.exe. Don't use the dotnet CLI or .zip (Windows .NET 6) versions of SqlPackage.exe because those versions might generate DACPACs that are incompatible with Azure DevOps Services. +> - Version 161 of SqlPackage encrypts database connections by default and might not connect. If you receive a sign-in process error, add `;Encrypt=False;TrustServerCertificate=True` to the connection string of the SqlPackage statement. + +Download and install SqlPackage.exe using the latest MSI Installer from the [SqlPackage release notes](/sql/tools/sqlpackage/release-notes-sqlpackage). + +After you use the MSI Installer, SqlPackage.exe installs in a path similar to `%PROGRAMFILES%\Microsoft SQL Server\160\DAC\bin\`. + +When you generate a DACPAC, keep two considerations in mind: the disk that the DACPAC is saved on and the disk space on the machine that's generating the DACPAC. You want to ensure that you have enough disk space to complete the operation. + +As it creates the package, SqlPackage.exe temporarily stores data from your collection in the temp directory on drive C of the machine you're initiating the packaging request from. + +You might find that your drive C is too small to support creating a DACPAC. You can estimate the amount of space you need by looking for the largest table in your collection database. DACPACs are created one table at a time. The maximum space requirement to run the generation is roughly equivalent to the size of the largest table in the collection's database. If you save the generated DACPAC to drive C, consider the size of the collection database as reported in the *DataMigrationTool.log* file from a validation run. + +The *DataMigrationTool.log* file provides a list of the largest tables in the collection each time the command is run. For an example of table sizes for a collection, see the following output. Compare the size of the largest table with the free space on the drive that hosts your temporary directory. + +> [!IMPORTANT] +> Before you proceed with generating a DACPAC file, ensure that your collection is [detached](#step-1-detach-your-collection). + + +```cmdline +[Info @08:23:59.539] Table name Size in MB +[Info @08:23:59.539] dbo.tbl_Content 38984 +[Info @08:23:59.539] dbo.tbl_LocalVersion 1935 +[Info @08:23:59.539] dbo.tbl_Version 238 +[Info @08:23:59.539] dbo.tbl_FileReference 85 +[Info @08:23:59.539] dbo.Rules 68 +[Info @08:23:59.539] dbo.tbl_FileMetadata 61 +``` + +Ensure that the drive that hosts your temporary directory has at least as much free space. If it doesn't, you need to redirect the temp directory by setting an environment variable. + +```cmdline +SET TEMP={location on disk} +``` + +Another consideration is where the DACPAC data is saved. Pointing the saved location to a far-off remote drive could result in longer generation times. If a fast drive such as a solid-state drive (SSD) is available locally, we recommend that you target the drive as the DACPAC save location. Otherwise, it's always faster to use a disk that's on the machine where the collection database resides rather than a remote drive. + +Now that you identified the target location for the DACPAC and ensured that you have enough space, it's time to generate the DACPAC file. + +Open a Command Prompt window and go to the SqlPackage.exe location. To generate the DACPAC, replace the placeholder values with the required values, and then run the following command: + +```cmdline +SqlPackage.exe /sourceconnectionstring:"Data Source={database server name};Initial Catalog={Database Name};Integrated Security=True" /targetFile:{Location & File name} /action:extract /p:ExtractAllTableData=true /p:IgnoreUserLoginMappings=true /p:IgnorePermissions=true /p:Storage=Memory +``` + +* **Data Source**: The SQL Server instance that hosts your Azure DevOps Server collection database. +* **Initial Catalog**: The name of the collection database. +* **targetFile**: The location on the disk and the DACPAC file name. + +A DACPAC generation command that's running on the Azure DevOps Server data tier itself is shown in the following example: + +```cmdline +SqlPackage.exe /sourceconnectionstring:"Data Source=localhost;Initial Catalog=Foo;Integrated Security=True" /targetFile:C:\DACPAC\Foo.dacpac /action:extract /p:ExtractAllTableData=true /p:IgnoreUserLoginMappings=true /p:IgnorePermissions=true /p:Storage=Memory +``` + +The output of the command is a DACPAC file, generated from the collection database *Foo* called *Foo.dacpac*. + +#### Configure your collection for migration + +After your collection database restores on your Azure VM, configure a SQL sign-in to allow Azure DevOps Services to connect to the database to migration the data. This sign-in allows only *read* access to a single database. + +To start, open SQL Server Management Studio on the VM, and then open a new query window against the database to be imported. + +Set the database's recovery to simple: + +```sql +ALTER DATABASE [] SET RECOVERY SIMPLE; +``` + +Create a SQL sign-in for the database, and assign that sign-in the 'TFSEXECROLE': + +```sql +USE [] +CREATE LOGIN WITH PASSWORD = '' +CREATE USER FOR LOGIN WITH DEFAULT_SCHEMA=[dbo] +EXEC sp_addrolemember @rolename='TFSEXECROLE', @membername='' +``` + +Following our Fabrikam example, the two SQL commands would look like the following example: + +```sql +ALTER DATABASE [Fabrikam] SET RECOVERY SIMPLE; + +USE [Foo] +CREATE LOGIN fabrikam WITH PASSWORD = 'fabrikampassword' +CREATE USER fabrikam FOR LOGIN fabrikam WITH DEFAULT_SCHEMA=[dbo] +EXEC sp_addrolemember @rolename='TFSEXECROLE', @membername='fabrikam' +``` +> [!NOTE] +> Enable [SQL Server and Windows authentication mode](/sql/database-engine/configure-windows/change-server-authentication-mode?view=sql-server-ver15#change-authentication-mode-with-ssms&preserve-view=true) in SQL Server Management Studio on the VM. If you don't enable authentication mode, the migration fails. + +#### Configure the migration specification file to target the VM + +Update the migration specification file to include information about how to connect to the SQL Server instance. Open your migration specification file and make the following updates. + +1. Remove the DACPAC parameter from the source files object. + + The migration specification before the change is shown in the following code. + + ![Screenshot of the migration specification before the change.](media/import-spec-before.png) + + The migration specification after the change is shown in the following code. + + ![Screenshot of the migration specification after the change.](media/import-spec-after.png) + +2. Fill out the required parameters and add the following properties object within your source object in the specification file. + + ```json + "Properties": + { + "ConnectionString": "Data Source={SQL Azure VM Public IP};Initial Catalog={Database Name};Integrated Security=False;User ID={SQL Login Username};Password={SQL Login Password};Encrypt=True;TrustServerCertificate=True" + } + ``` + +After you apply the changes, the migration specification looks like the following example. + +![Screenshot of the migration specification referencing a SQL Azure VM.](media/import-spec-iaas.png) + +Your migration specification is now configured to use a SQL Azure VM for migration. Proceed with the rest of preparation steps to migration to Azure DevOps Services. After the migration finishes, be sure to delete the SQL sign-in or rotate the password. Microsoft doesn't retain the sign-in information after the migration finished. + +### Step 3: Upload the DACPAC file + +> [!NOTE] +> If you're using the SQL Azure VM method, you need to provide only the connection string. You don't have to upload any files, and you can skip this step. + +Your DACPAC must be placed in an Azure storage container, which can be an existing container or one created specifically for your migration effort. It's important to ensure that your container is created in the right geographical locations. + +Azure DevOps Services is available in multiple [geographical locations](https://azure.microsoft.com/regions/services/). When you're importing to these locations, it's critical to place your data correctly to ensure that the migration can start successfully. Your data must be placed in the same geographical location that you're importing to. Placing the data anywhere else results in the migration being unable to start. The following table lists the acceptable geographical locations for creating your storage account and uploading your data. + +| Desired migration geographical location | Storage account geographical location | +| --- | --- | +| Central United States | Central United States | +| Western Europe | Western Europe | +| United Kingdom | United Kingdom South | +| Australia East | Australia East | +| Brazil South | Brazil South | +| India South | India South | +| Canada Central | Canada Central | +| Asia Pacific (Singapore) | Asia Pacific (Singapore) | + +Although Azure DevOps Services is available in multiple geographical locations in the US, only the Central United States location accepts new Azure DevOps Services. You can't migrate your data into other US Azure locations at this time. + +[Create a blob container](/azure/storage/common/storage-create-storage-account) from the Azure portal. After you create the container, upload the Collection DACPAC file. + +After the migration finishes, delete the blob container and accompanying storage account with tools such as [AzCopy](/azure/storage/common/storage-use-azcopy-v10) or any other Azure storage explorer tool. + +> [!NOTE] +> If your DACPAC file is larger than 10 GB, we recommend that you use [AzCopy](/azure/storage/common/storage-use-azcopy-v10), as it has multithreaded upload support for faster uploads. + +### Step 4: Generate an SAS token + +A [shared access signature (SAS) token](/azure/storage/common/storage-sas-overview) provides delegated access to resources in a storage account. The token allows you to give Microsoft the lowest level of privilege required to access your data for executing the migration. + +You can generate SAS tokens [using the Azure portal](/azure/storage/blobs/blob-containers-portal#generate-a-shared-access-signature). From a security point-of-view, we recommend doing the following tasks: + +1. Select only **Read** and **List** as permissions for your SAS token. No other permissions are required. +2. Set an expiry time no further than seven days into the future. +3. [Restrict access to Azure DevOps Services IPs only](migration-prepare-test-run.md#restrict-access-to-azure-devops-services-ips-only). +4. Treat the SAS key as a secret. Don't leave the key in an insecure location as it grants read and list access to any data stored in the container. + +### Step 5: Complete the migration specification + +Earlier in the process you partially filled out the migration specification file, known as *migration.json*. At this point, you have enough information to complete all the remaining fields except for the migration type. The migration type is covered later, in the migration section. + +In the *migration.json* specification file, under **Source**, complete the following fields. + +* **Location**: Paste the SAS key you generated from the script and then copied in the preceding step. +* **Dacpac**: Ensure that the file, including the *.dacpac* file extension, has the same name as the DACPAC file you uploaded to the storage account. + +The final migration specification file should look like the following example. + +![Screenshot of the completed migration specification file.](media/migration-import/ImportSpecFillOutNoType.png) + +### Determine the migration type + +Imports can be queued as either a test run (`DryRun`) or a production run (`ProductionRun`). The **ImportType** parameter determines the migration type: + +- **DryRun**: Also referred to as a test run. Use for test and validation purposes. The system deletes test runs after 45 days. +- **ProductionRun**: Use a production run when you want to keep the resulting migration and use the organization full time in Azure DevOps Services after the migration finishes. + +> [!TIP] +> We always recommend that you complete a test run migration first. + +### Test run organizations + +Test run organizations help teams test the migration of their collections. Before a production migration can be run, any completed [test run organizations must be deleted](#prepare-for-migration). All test run organizations have a *limited existence and are automatically deleted after a set period of time*. Information about when the organization is deleted is included in the success email you should receive after the migration finishes. Be sure to take note of this date and plan accordingly. + +Test run organizations have 45 days before they're deleted. After the specified time period, the test run organization is deleted. You can repeat test run imports as many times as you need before you do a production migration. + +## Delete test runs + +Delete any previous test runs before you attempt a new one. When your team is ready to perform a production migration, you need to manually delete the test run organization. +Before you can run a second test run migration or the final production migration, make sure you delete any previous Azure DevOps Services organizations that you created in a previous test run. For more information, see [Delete organization](../organizations/accounts/delete-your-organization.md). + +> [!TIP] +> Optional information to help a user be more successfulAny test run migration that follows the first is expected to take longer given the extra time required to clean up resources from previous test runs. + +It can take up to one hour for an organization name to become available after deleting or renaming. +For more information, see the [Post migration tasks](migration-post-migration.md) article. + +If you encounter any migration problems, see [Troubleshoot migration and migration errors](migration-troubleshooting.md#resolve-migration-errors). + + + +## Run a migration + +Your team is now ready to begin the process of running a migration. We recommend that you start with a successful test run migration before you attempt a production-run migration. With test run imports, you can see in advance how a migration looks, identify potential issues, and gain experience before you head into your production run. + +> [!NOTE] +> - If you need to repeat a completed production-run migration for a collection, such as due to a rollback, contact Azure DevOps Services [Customer Support](https://azure.microsoft.com/support/devops/) before you queue another migration. +- Azure administrators can prevent users from creating new Azure DevOps organizations. If the Microsoft Entra tenant policy is turned on, your migration fails to finish. Before you begin, verify that the policy isn't set or that there's an exception for the user that is performing the migration. For more information, see [Restrict organization creation via Microsoft Entra tenant policy](../organizations/accounts/azure-ad-tenant-policy-restrict-org-creation.md). +- Azure DevOps Services doesn't support per-pipeline retention policies, and they aren't carried over to the hosted version. + +### Considerations for rollback plans + +A common concern for teams doing a final production run is their rollback plan, if anything goes wrong with migration. We highly recommend doing a test run to make sure that you can test the migration settings you provide to the Data Migration Tool for Azure DevOps. + +Rollback for the final production run is fairly simple. Before you queue the migration, detach the team project collection from Azure DevOps Server, which makes it unavailable to your team members. If for any reason you need to roll back the production run and bring the on-premises server back online for your team members, you can do so. Attach the team project collection on-premises again and inform your team that they continue to work normally while your team regroups to understand any potential failures. + +You can then contact Azure DevOps Services customer support for help with understanding the failure's cause if you can't determine the cause. For more information, see the [Troubleshooting article](migration-troubleshooting.md). Customer support tickets can be opened from the following page https://aka.ms/AzureDevOpsImportSupport. If the issue requires product group engineers to engage, those cases get handled during regular business hours. + +#### Detach your team project collection from Azure DevOps Server to prepare it for migration. + +Before you generate a backup of your SQL database, you must completely detach the collection from Azure DevOps Server (not SQL) using the Data Migration Tool. The detach process in Azure DevOps Server transfers user identity information stored outside of the collection database, making it portable for moving to a new server or, in this case, to Azure DevOps Services. + +Detaching a collection is easily done from the Azure DevOps Server Administration Console on your Azure DevOps Server instance. For more information, see [Move project collection, Detach the collection](/azure/devops/server/admin/move-project-collection). + +### Queue the migration + +> [!IMPORTANT] +> Before you proceed, ensure that your collection was [detached](#step-1-detach-your-collection) before you generate a DACPAC file or upload the collection database to a SQL Azure VM. If you don't complete this step, the migration fails. If your migration fails, see [Resolve migration errors](migration-troubleshooting.md). + +Start a migration by using the Data Migration Tool's **import** command. The import command takes a migration specification file as input. It parses the file to ensure that the provided values are valid and, if successful, it queues a migration to Azure DevOps Services. The import command requires an internet connection, but doesn't* require a connection to your Azure DevOps Server instance. + +To get started, open a Command Prompt window, and change directories to the path to the Data Migration Tool. We recommended that you review the help text provided with the tool. Run the following command to see the guidance and help for the import command: + +```cmdline +Migrator import /help +``` + +The command to queue a migration has the following structure: + +```cmdline +Migrator import /importFile:{location of migration specification file} +``` + +The following example shows a completed import command: + +```cmdline +Migrator import /importFile:C:\DataMigrationToolFiles\migration.json +``` + +After the validation passes, sign in to Microsoft Entra ID with an identity that's a member of the same Microsoft Entra tenant as the identity map log file was built against. The signed in user is the owner of the imported organization. + +> [!NOTE] +> Each Microsoft Entra tenant is limited to five imports per 24-hour period. Only imports that are queued count against this cap. + +When your team initiates a migration, an email notification is sent to the user that queued the migration. About 5 to 10 minutes after it queues the migration, your team can go to the organization to check on the status. After the migration finishes, your team is directed to sign in, and an email notification is sent to the organization owner. + +The Data Migration Tool flags errors that you need to correct before migration. This article describes the most common warnings and errors that you might receive when you're preparing to migrate. After you correct each error, run the **migrator validate** command again to verify resolution. + +## Next steps + +> [!div class="nextstepaction"] +> [Resolve migration errors](migration-troubleshooting.md) + +## Related articles + +- [Migration overview](migration-overview.md) +- [Post migration tasks](migration-post-migration.md) diff --git a/docs/migrate/migration-troubleshooting.md b/docs/migrate/migration-troubleshooting.md index 4745ec70fe1..34d653ad2e6 100644 --- a/docs/migrate/migration-troubleshooting.md +++ b/docs/migrate/migration-troubleshooting.md @@ -1,116 +1,109 @@ --- -title: Troubleshoot migration import to Azure DevOps Services +title: Resolve migration errors titleSuffix: Azure DevOps -description: Resolve common DataMigratorTool validation errors +description: Troubleshoot and resolve common Data Migration Tool validation errors. ms.topic: troubleshooting ms.subservice: azure-devops-migrate +ms.custom: has-azure-ad-ps-ref, azure-ad-ref-level-one-done ms.contentid: ee8c290d-0b48-4cbd-b7fd-7afb9591c169 +ai-usage: ai-assisted ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 01/31/2022 +ms.date: 12/26/2024 --- -# Troubleshoot import and migration errors +# Resolve migration errors -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - -The data migration tool flags errors that you need to correct prior to performing a migration to Azure DevOps Services. This article describes the most common warnings and errors that you may receive when preparing to migrate. After correcting each error, run the **migrator validate** command again to verify resolution of all errors. - - -> [!NOTE] -> We recommended that you use the [Migration guide](https://aka.ms/AzureDevOpsImport) to progress through your import. The guide links to the technical documentation as needed. -> -> With the release of Azure DevOps Server 2019, the Team Foundation Server (TFS) Database Import Service was re-branded to become the data migration tool for Azure DevOps. The data migration tool, **TfsMigrator** has been renamed **migrator** for short. The service still works exactly the same as the previous import service. If you're on an older version of on-premises with TFS as the branding, you can still use **migrator** to migrate to Azure DevOps as long as you upgrade to one of the supported versions. For details, see [Migrate data from Azure DevOps Server to Azure DevOps Services](migration-overview.md). +The Data Migration Tool flags errors that you need to correct before you import to Azure DevOps Services. This article describes the most common warnings and errors that you might receive when you're preparing to import. After you correct each error, run the **migrator validate** command again to verify resolution. +For more help, refer to the [FAQs section](#faqs) at the end of this article. ## Resolve size warnings -Extra-large collections may generate one of the following messages after running the data migration tool. If you receive any of these warnings or errors, we recommend that you try to [reduce your database's size](/azure/devops/server/upgrade/clean-up-data). +Extra-large collections might generate one of the following messages after running the Data Migration Tool. If you receive any of these warnings or errors, we recommend that you try to [reduce your database's size](/azure/devops/server/upgrade/clean-up-data). -### Database size above recommended size +### Database size over recommended size -The following warning means you need to use the SQL Azure VM method to complete your import. Once a database reaches a certain size, it becomes faster to setup a SQL Azure VM to complete the import to Azure DevOps Services. To setup the VM and complete your import, follow the instructions linked from the warning message. +The following warning means you need to use the SQL Azure VM method to complete your migration. Once a database reaches a certain size, it becomes faster to set up a SQL Azure VM to complete the migration to Azure DevOps Services. To set up the VM and complete your migration, follow the instructions linked from the warning message. ```cmdline -The database is currently {Database Size}GBs. This is above the recommended size of {DACPAC Size Limit}GBs to use the DACPAC import method. Please see the following page to learn how to import using a SQL Azure VM: https://aka.ms/AzureDevOpsImportLargeCollection +The database is currently {Database Size}GBs. This is above the recommended size of {DACPAC Size Limit}GBs to use the DACPAC migration method. Please see the following page to learn how to migration using a SQL Azure VM: https://aka.ms/AzureDevOpsImportLargeCollection ``` -This warning **DOES NOT** mean that your collection is too large for import. +This warning **DOES NOT** mean that your collection is too large for migration. -### Table size above recommended size +### Table size over recommended size -Similar to the previous warning, the following warning means you must use the SQL Azure Virtual Machine (VM) method to complete the import. Follow the instructions linked from the warning message to setup the VM and complete your import. +Similar to the previous warning, the following warning means you must use the SQL Azure Virtual Machine (VM) method to complete the migration. To set up the VM and complete your migration, follow the instructions linked from the warning message. ```cmdline -The largest table size is currently {Table size}GBs. This is above the recommended size of {Size limit}GBs to use the DACPAC import method. Please see the following page to learn how to import using a SQL Azure VM: https://aka.ms/AzureDevOpsImportLargeCollection +The largest table size is currently {Table size}GBs. This is above the recommended size of {Size limit}GBs to use the DACPAC migration method. Please see the following page to learn how to migration using a SQL Azure VM: https://aka.ms/AzureDevOpsImportLargeCollection ``` -This warning **DOES NOT** mean that your collection is too large for import. +This warning **DOES NOT** mean that your collection is too large for migration. -### Database metadata size above recommended size +### Database metadata size over recommended size -The following warning means that your database is approaching the limit for total metadata size. Metadata size refers to the size of your database without including files, code, and other binary data. We recommend that you [reduce the size](/azure/devops/server/upgrade/clean-up-data) of your database before import. Reducing the size provides the additional benefit of speeding up your import. +The following warning means that your database is approaching the limit for total metadata size. Metadata size refers to the size of your database without including files, code, and other binary data. We recommend that you [reduce the size](/azure/devops/server/upgrade/clean-up-data) of your database before migration. Reducing the size provides the other benefit of speeding up your migration. ```cmdline The database metadata size is currently {Metadata Size}GBs. This is above the recommended size of {Warning Size}GBs. It's recommended that you consider cleaning up older data as described in [Cleaning up old data](/azure/devops/server/upgrade/clean-up-data). ``` -The warning **DOES NOT** mean that your collection is too large for import, rather its metadata size is larger than the vast majority of other databases. +The warning **DOES NOT** mean that your collection is too large for migration, rather its metadata size is larger than most other databases. -### Database metadata size above maximum supported size +### Database metadata size over maximum supported size Unlike the previous warnings, the following error **WILL** block you from moving forward with your migration. -It indicates that the volume of metadata in your collection is too large. To proceed with the import, you need to [reduce](/azure/devops/server/upgrade/clean-up-data) the size below the indicated limit. +It indicates that the volume of metadata in your collection is too large. To proceed with the migration, you need to [reduce](/azure/devops/server/upgrade/clean-up-data) the size below the indicated limit. ```cmdline The database metadata size is currently {Metadata Size}GBs. This is above the maximum supported size of {Metadata Limit}GBs. ``` - - ## Resolve collation warnings -Collation warnings refer to your collection database's collation. Collations control the way string values are sorted and compared. Collections that aren't using either `SQL_Latin1_General_CP1_CI_AS` or `Latin1_General_CI_AS` will generally receive one of the **warning** messages. +Collation warnings refer to your collection database's collation. Collations control the way string values are sorted and compared. Collections that aren't using either `SQL_Latin1_General_CP1_CI_AS` or `Latin1_General_CI_AS` receive one of the **warning** messages. ### No native support -Receiving the following warning means that you need to consider collation implications before performing the import. +Receiving the following warning means that you need to consider collation implications before performing the migration. ```cmdline The collection database's collation '{collation}' is not natively supported in Azure DevOps Services. Importing your collection will result in your collation being converted to one of the supported Azure DevOps Services collations. See more details at https://aka.ms/AzureDevOpsImportCollations ``` -This warning **DOES NOT** mean that you can't import your collection. +This warning **DOES NOT** mean that you can't migrate your collection. -This warning requires you to acknowledge acceptance of the warning. Accepting the warning allows the data migration tool to continue import preparations. +This warning requires you to acknowledge acceptance of the warning. Accepting the warning allows the Data Migration Tool to continue migration preparations. -When you import a non-supported collation into Azure DevOps Services, the collation is transformed to a supported collation. While this transform generally works without issue, unexpected results post import or import failures could occur. +When you migrate an unsupported collation into Azure DevOps Services, the collation is transformed to a supported collation. While this transform generally works without issue, unexpected results post migration or migration failures could occur. -For instance, customers may notice different ordering for strings containing non-English characters. Non-English characters like 'é' may become equivalent to the English 'e' after import. It's important that you complete and verify a dry run import when importing a collection with a non-supported collation. +For instance, customers might notice different ordering for strings containing non-English characters. Non-English characters like 'é' might become equivalent to the English 'e' after migration. It's important that you complete and verify a test run migration when you migrate a collection with an unsupported collation. ### No native support, no internet connection -If the data migration tool can't connect to the internet, it can't validate conversion of your collation. It's only a warning, so you can continue with your migration process. However, when you run the **prepare** command, an internet connection is required and collation conversion is validated at that time. +If the Data Migration Tool can't connect to the internet, it can't validate conversion of your collation. It's only a warning, so you can continue with your migration process. However, when you run the **prepare** command, an internet connection is required and collation conversion is validated at that time. ```cmdline -The collections database's collation '{collation}' is not natively supported in Azure DevOps Services. It could not be validated that the collation can be converted during import to a supported Azure DevOps Services collation, as there was no internet connection. Please run the command again from a machine with an internet connection. See more details at https://aka.ms/AzureDevOpsImportCollations +The collections database's collation '{collation}' is not natively supported in Azure DevOps Services. It could not be validated that the collation can be converted during migration to a supported Azure DevOps Services collation, as there was no internet connection. Please run the command again from a machine with an internet connection. See more details at https://aka.ms/AzureDevOpsImportCollations ``` ### Unsupported database collation -Generally you can convert a non-supported collation to a supported collation at import time. However, some collations can't be converted. If your collection uses one of these collations, you'll receive the following **error** message. +Generally you can convert a nonsupported collation to a supported collation at migration time. However, some collations can't be converted. If your collection uses one of these collations, you receive the following **error** message. ```cmdline -The collection database's collation '{collation}' is not supported for import to Azure DevOps Services. It will need to be changed to a supported collation before it can be imported. See more details at https://aka.ms/AzureDevOpsImportCollations +The collection database's collation '{collation}' is not supported for migration to Azure DevOps Services. It will need to be changed to a supported collation before it can be imported. See more details at https://aka.ms/AzureDevOpsImportCollations ``` In order to continue, you need to [change your collection's collation](/sql/relational-databases/collations/set-or-change-the-database-collation) to one of the supported collations on Azure DevOps Services. ## Resolve identity errors -Identity errors aren't common when validating a collection, but when they do occur you need to fix them prior to migration to avoid undesired results. Generally, identity problems stem from valid operations on previous versions of TFS that are no longer valid on your current Azure DevOps Server version. For example, while it was once allowed for some users to be members of a built-in valid users group, it isn't in the more recent versions. +Fix identity errors before migration to prevent problems. These errors are rare and occur when old operations are invalid on a new Azure DevOps Server. For instance, some users might no longer be part of the valid users group. The following sections provide guidance for resolving the most common identity errors. @@ -118,11 +111,11 @@ The following sections provide guidance for resolving the most common identity e This error indicates that a permission is missing from a system security group. For example, every collection that you create has Project Collection Valid Users and Project Collection Administrators groups. The system creates them by default. These groups don't support editing of their permissions. -This error indicates that one or more groups is missing a permission that it's expected to have. To resolve this error, use the **TFSSecurity.exe** command to apply the expected permissions onto the flagged system groups. Your first step is to identify which [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd) command(s) you need to run. +This error indicates that one or more groups is missing a permission that it should have. To resolve this error, use the **TFSSecurity.exe** command to apply the expected permissions onto the flagged system groups. Your first step is to identify which [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd) command you need to run. #### Project Collection Valid Users error message -Examine the error message(s) the data migration tool highlighted. If the flagged group ends with "**0-0-0-0-3**", such as in the following example, you need to fix a missing permission for the **Project Collection Valid Users** group. +Examine one or more error messages the Data Migration Tool highlighted. If the flagged group ends with "**0-0-0-0-3**", such as in the following example, you need to fix a missing permission for the **Project Collection Valid Users** group. Run the following command, replace the scope with the one from the error message and specify your collection URL. @@ -144,7 +137,7 @@ TFSSecurity.exe /a+ Identity "397c326b-b97c-4510-8271-75aac13de7a9\\" Read sid:S #### Project Collection Administrators error message -Carefully examine the error message(s) the data migration tool highlighted. If the flagged group that ends with "**0-0-0-0-1**", such as in the following example, then you will need to fix a missing permission for the **Project Collection Administrators** group. Run the following commands against **TFSSecurity.exe**, replace the scope with the one from the error message and specify your collection. +Carefully examine the error messages the Data Migration Tool highlighted. If the flagged group that ends with "**0-0-0-0-1**", such as in the following example, then you need to fix a missing permission for the **Project Collection Administrators** group. Run the following commands against **TFSSecurity.exe**, replace the scope with the one from the error message and specify your collection. ```cmdline TFSSecurity.exe /a+ Identity "{scope}\\" Read sid:{Group SID} ALLOW /collection:{collectionUrl} @@ -174,16 +167,16 @@ TFSSecurity.exe /a+ Identity "0c7c2216-fa4b-4107-a203-82b324a147ef\\" Delete sid TFSSecurity.exe /a+ Identity "0c7c2216-fa4b-4107-a203-82b324a147ef\\" ManageMembership sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 ALLOW /collection:https://localhost:8080/defaultcollection ``` -When you need to correct multiple errors, we recommend that you create a batch file to automate execution of the commands. Once you've executed the commands, you need to rerun the data migration **validate** tool to verify resolution. If some errors still persist, contact [Azure DevOps Services customer support](https://aka.ms/AzureDevOpsImportSupport). +When you need to correct multiple errors, we recommend that you create a batch file to automate execution of the commands. Once you execute the commands, rerun the data migration **validate** tool to verify resolution. If some errors still persist, contact [Azure DevOps Services customer support](https://aka.ms/AzureDevOpsImportSupport). ### ISVError: 300005 -ISVError: 300005 indicates that a non-group identity is a member of an everyone group, more commonly known as the Valid Users groups. Valid Users groups are default groups defined for all projects and collections. These groups are not editable. They are designed to only contain other Azure DevOps permission or security groups as members. This error indicates that an Active Directory (AD) group or user identity has a direct membership in a Valid Users group. +ISVError: 300005 indicates that a nongroup identity is a member of an everyone group, more commonly known as the Valid Users groups. Valid Users groups are default groups defined for all projects and collections. These groups aren't editable. They're designed to only contain other Azure DevOps permission or security groups as members. This error indicates that an Active Directory (AD) group or user identity has a direct membership in a Valid Users group. > [!IMPORTANT] > Ensure that you have a backup of your collection and configuration databases before running the following commands to resolve the error. -Since you can't directly edit Valid Users groups, you need to run a SQL statement against the configuration database to remove the offending identity and correct the invalid membership. Carefully examine the error messages highlighted by the data migration tool. Copy the `GroupSid`, `MemberId`, and `ScopeId` as you'll need to place these values into the following command. +Since you can't directly edit Valid Users groups, you need to run a SQL statement against the configuration database to remove the offending identity and correct the invalid membership. Carefully examine the error messages highlighted by the Data Migration Tool. Copy the `GroupSid`, `MemberId`, and `ScopeId` as you need to place these values into the following command. ```SQL DECLARE @p6 dbo.typ_GroupMembershipTable @@ -193,7 +186,7 @@ INSERT into @p6 values('{GroupSid}','Microsoft.TeamFoundation.Identity','{Member EXEC prc_UpdateGroupMembership @partitionId=1,@scopeId='{ScopeId}',@idempotent=1,@incremental=1,@insertInactiveUpdates=0,@updates=@p6,@eventAuthor='9EE20697-5343-43FC-8FC5-3D5D455D21C5',@updateGroupAudit=0 ``` -The following example lists an example of an ISVError: 300005 message from the data migration tool. +The following example lists an example of an ISVError: 300005 message from the Data Migration Tool. ```cmdline ISVError:300005 Unexpected non group identity was found to have direct membership to everyone group. GroupSid:S-1-9-1551374245-3746625149-2333054533-2458719197-2313548623-0-0-0-0-3, MemberId:76050ddf-4fd8-48c4-a1ff-859e44364519, ScopeId:7df650df-0f8b-4596-928d-13dd89e5f34f @@ -223,54 +216,54 @@ INSERT into @p6 values('S-1-9-1551374245-3746625149-2333054533-2458719197-231354 EXEC prc_UpdateGroupMembership @partitionId=1,@scopeId='7df650df-0f8b-4596-928d-13dd89e5f34f',@idempotent=1,@incremental=1,@insertInactiveUpdates=0,@updates=@p6,@eventAuthor='9EE20697-5343-43FC-8FC5-3D5D455D21C5' ``` - -Run the completed command against the Azure DevOps Server configuration database. You'll need to repeat this command for each ISVError: 300005 instance reported. You can batch errors with the same scope ID into a single command. Once you've executed the commands, rerun the data migration tool validate again to ensure that the errors have been corrected. If the errors still persist, contact [Azure DevOps Services customer support](https://aka.ms/AzureDevOpsImportSupport). +Run the completed command against the Azure DevOps Server configuration database. Repeat this command for each ISVError: 300005 instance reported. You can batch errors with the same scope ID into a single command. Once you execute the commands, rerun the Data Migration Tool validate again to ensure that the errors are corrected. If the errors still persist, contact [Azure DevOps Services customer support](https://aka.ms/AzureDevOpsImportSupport). > [!IMPORTANT] > To address these errors, the collection must be attached. > > If you receive a -1 result when you run the command, ensure that your collection database that produced the error is attached to your Azure DevOps Server instance and that you're running the command on the configuration database. -### Azure Active Directory timeout exception + + +### Microsoft Entra timeout exception -On rare occasions, you may receive an Azure Active Directory (Azure AD) timeout error when running the data migration tool prepare command. +On rare occasions, you might receive a Microsoft Entra timeout error when running the Data Migration Tool prepare command. ```cmdline Exception Message: Request failed (type AadGraphTimeoutException) ``` -This error means that the requests to Azure AD to find the matching Azure AD identities for users in your collection timed out. Generally, you can resolve this error by waiting to run the **prepare** command at a less busy time of the day, such as after regular business hours. +This error means that the requests to Microsoft Entra ID to find the matching Microsoft Entra identities for users in your collection timed out. Generally, you can resolve this error by waiting to run the **prepare** command at a less busy time of the day, such as after regular business hours. -In the event that the error continues, you should undertake a few troubleshooting steps. First, you will want to test your connection to Azure AD from the machine running the **prepare** command. Execute the following steps to retrieve information on a user in your Azure AD. +To troubleshoot, test Microsoft Entra ID connection from **prepare** machine. Follow these steps to get user info from Microsoft Entra ID. -Open PowerShell in elevated mode and replace 'someone@somecompany.com' in the following command with your Azure AD user identity. +Open PowerShell in elevated mode and replace 'someone@somecompany.com' in the following command with your Microsoft Entra user identity. ```PowerShell -//Install the AzureAD PowerShell module - ensuring to select Yes to All -Install-Module AzureAD +# Install the Microsoft Graph PowerShell module - ensuring to select Yes to All +Install-Module Microsoft.Graph -// Install the MSOnline PowerShell module - ensuring to select Yes to All -Install-Module MSOnline +# Import Users module +Import-Module Microsoft.Graph.Users -// Connect to Azure AD and use your Azure AD credentials (someone@somecompany.com) to login when the pop-up appears -Connect-MsolService +# Connect to Microsoft Entra and use your Microsoft Entra ID credentials (someone@somecompany.com) to login when the pop-up appears +Connect-MgGraph -Scopes 'User.Read.All' -// Try to retrieve information on a user from your Azure AD -Get-MsolUser -UserPrincipalName someone@somecompany.com +# Try to retrieve information on a user from your Microsoft Entra +Get-MgUser -Filter "UserPrincipalName eq 'someone@somecompany.com'" ``` -If any of the above steps fail or you're unable to look up a user's identity, a connection issue may exist between the machine running the **prepare** command and Azure AD. Run a network trace while executing the **prepare** command to ensure that nothing within your network is interfering with calls reaching Azure AD. If you've confirmed that the problem isn't with your network, contact Azure support for assistance with troubleshooting. -If you're able to retrieve user information, open your log file from the **prepare** attempt and look for a line similar to the following entry. +If the steps fail or you can’t find the user, check the connection between the **prepare** machine and Microsoft Entra ID. Run a network trace with **prepare** to see if the network blocks calls. If not, contact Azure support. Check the log file for the user information. ```cmdline Number of active users is {Number of Users}. ``` -If the number of active users is over 50,000, the volume of identities being mapped may require more time than provided by the timeout limit. Inspect your collection for inclusions of large AD groups such as an 'everyone' group. If possible, remove these groups and try again. If you still can't resolve this error, contact [Azure DevOps Services customer support](https://aka.ms/AzureDevOpsImportSupport). +If the number of active users is over 50,000, the volume of identities being mapped might require more time than provided by the timeout limit. Inspect your collection for inclusions of large groups such as an 'everyone' group. If possible, remove these groups and try again. If you still can't resolve this error, contact [Azure DevOps Services customer support](https://aka.ms/AzureDevOpsImportSupport). ## Resolve process errors -See the separate [Process Templates](migration-processtemplates.md) page for details on resolving common process errors. +See the [Validate phase article, Resolve process templates](migration-validate.md#resolve-process-template-errors) for details on resolving common process errors. ## Resolve field validation errors @@ -281,9 +274,6 @@ See the separate [Process Templates](migration-processtemplates.md) page for det The following error message can occur when an inconsistency in collection files is detected. Contact customer support if you encounter this error. `VS403310: An inconsistency was detected in some of the files in the collection.` - - - #### VS403442 @@ -291,14 +281,12 @@ Field name conflicts sometimes occur between your local collection and an Azure `In order to migrate successfully, you must rename field *{TFSfieldReferenceName}*. Given name *{TFSfieldName}* is reserved for field *{VSTSfieldReferenceName}*.` -To resolve this error, change the name of your collection field. Use the **witadmin changefield** command from [witadmin](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md). +To resolve this error, change the name of your collection field. Use the **`witadmin changefield`** command from [witadmin](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md). ```cmdline witadmin changefield /collection:http://AdventureWorksServer:8080/DefaultCollection /n:TFSfieldReferenceName /name:newFieldName ``` - - #### VS403443 The following error indicates a field name conflict exists between your local collection and a specific Azure DevOps Services field. @@ -306,14 +294,12 @@ The following error indicates a field name conflict exists between your local co `In order to migrate successfully, you must rename field *{TFSfieldReferenceName}* to *{VSTSfieldName}*. Given name for *{TFSfieldReferenceName}* is *{TFSfieldName}*` -To resolve this error, use the **witadmin changefield** command. For details, see [witadmin](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md). +To resolve this error, use the **`witadmin changefield`** command. For details, see [witadmin](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md). ```cmdline witadmin changefield /collection:http://AdventureWorksServer:8080/DefaultCollection /n:TFSfieldReferenceName /name:VSTSfieldName ``` - - #### VS403444 The following error indicates a field type conflict exists between your local collection and Azure DevOps Services. @@ -339,34 +325,27 @@ witadmin deletefield /collection:http://AdventureWorksServer:8080/DefaultCollect > [!IMPORTANT] > Deleting a field results in a loss of field data across the collection. - +## Resolve verification failures -## Resolve import errors +Verification failures mean the migration didn't start. The Data Migration Tool attempted to queue a migration, but got an error instead. Your migration request isn't valid. Fix the error messages and then try to migrate again. -Failures that occur during import fall into one of two categories, [verification failure](#verification-failures) and [import failure](#import-failures). +#### VS403254 -### Verification failures +The region that you entered for your Azure DevOps Services migration isn't supported. -Verification failures occur when the import fails to start. The data migration tool attempted to queue an import, but returned an error instead. Verification failure issues indicate that your import request isn't valid. Address the error messages you receive according to the following guidance and then try to import again. +`VS403254: Region {0} might not be used for the Import, it is not a supported region.` -**VS403254** +Open your migration specification file and update the region that you provided with the correct short name for the [region](migration-test-run.md#supported-azure-regions-for-migration). -The region that you entered for your Azure DevOps Services import isn't supported. +#### VS403249 +The organization name your team selected is already in use by an existing organization. All Azure DevOps Services migrations go into a new organization that is created at migration time. -`VS403254: Region {0} may not be used for the Import, it is not a supported region.` +`VS403249: The organization {0} already exists. Please select a different name and try the migration again.` -Open your import specification file and update the region that you've provided with the correct short name for the [region](migration-import.md#supported-azure-regions-for-import). +Select a different organization name and update the migration specification file before retrying the migration. -**VS403249** - -The organization name your team has selected is already in use by an existing organization. All Azure DevOps Services imports go into a new organization that is created at import time. - -`VS403249: The organization {0} already exists. Please select a different name and try the import again.` - -Select a different organization name and update the import specification file before retrying the import. - -**VS403250 & VS403286** +#### VS403250 & VS403286 The DACPAC isn't built off a detached collection. @@ -374,9 +353,9 @@ The DACPAC isn't built off a detached collection. `VS403286: The dacpac is from a Azure DevOps Server Configuration database. You must use a detached Azure DevOps Server Collection database.` -[Detach](migration-import.md#step-1-detach-your-collection) your collection database and generate the DACPAC again. +[Detach](migration-test-run.md#step-1-detach-your-collection) your collection database and generate the DACPAC again. -**VS403243** +#### VS403243 Unable to make a connection to the database using the provided SQL Connection String. @@ -384,17 +363,17 @@ Unable to make a connection to the database using the provided SQL Connection St Review the parameters that were provided to ensure they're correct and try again. -**VS403260 & VS403351** +#### VS403260 & VS403351 The collection database isn't detached. `VS403260: The database is not detached.` -`VS403351: The DACPAC or source database is missing an expected table. It's possible that the database was not correctly detached from Azure DevOps Server. ` +`VS403351: The DACPAC or source database is missing an expected table. It's possible that the database was not correctly detached from Azure DevOps Server.` -[Detach](migration-import.md#step-1-detach-your-collection) your collection database and retry the import queue. +[Detach](migration-test-run.md#step-1-detach-your-collection) your collection database and retry the migration queue. -**VS403261** +#### VS403261 The connection string must be encrypted otherwise the password is sent in the clear. @@ -402,7 +381,7 @@ The connection string must be encrypted otherwise the password is sent in the cl Add **Encrypt=true** to your SQL connection string. -**VS403262** +#### VS403262 The connection string must use SQL Authentication. @@ -410,30 +389,28 @@ The connection string must use SQL Authentication. Add **Integrated Security=False** to your SQL connection string. -**VS403263** +#### VS403263 Your SQL sign in user account doesn't have the required database role. - `VS403263: The User ID {0} must be member of the database role {1}.` -Make sure the user account for sign in is assigned the ['TFSEXECROLE'](migration-import.md#configure-your-collection-for-import) role. +Make sure the user account for sign in is assigned the ['TFSEXECROLE'](migration-test-run.md#configure-your-collection-for-migration) role. > [!NOTE] -> There is a known issue with using `sp_addrolemember` to add `TFSEXECROLE` to an existing SQL login. The role membership isn't applied until all open connections using that identity are closed. If you receive the VS403263 error and have confirmed your identity has the role, we recommend that you create a new identity for your import. Details on how to create a new SQL login that's ready to be used for import can be found at [Import large collections](migration-import-large-collections.md). +> There is a known issue with using `sp_addrolemember` to add `TFSEXECROLE` to an existing SQL login. The role membership isn't applied until all open connections using that identity are closed. If you receive the VS403263 error and have confirmed your identity has the role, we recommend that you create a new identity for your migration. -**VS403264** +#### VS403264 The connection string doesn't point to an Azure DevOps Server collection database. -`VS403264: The database is not a Azure DevOps Server Collection database, it cannot be used for import.` +`VS403264: The database is not a Azure DevOps Server Collection database, it cannot be used for migration.` Verify or correct the connection string points to your collection database. +#### VS40325 -**VS40325** - -The Azure DevOps Server Update has queued the file migration job. Imports can't be performed until this job has completed. The completion time for this job is dependent on the size of the collection. +The Azure DevOps Server Update has queued the file migration job. You can't perform migrations until this job completes. The completion time for this job is dependent on the size of the collection. `VS403255: The collection cannot be imported due to an ongoing post upgrade job. Please wait and try again later` @@ -446,39 +423,39 @@ WHERE PartitionId > 0 AND MigrateFileId IS NOT NULL ``` -Once the number of files remaining to migrate is zero, you can run the data migration tool. +Once the number of files remaining to migrate is zero, you can run the Data Migration Tool. -**VS403282** +#### VS403282 -A new line character exists in the source location value. This character could have remained after copying the SAS key from your windows console. +A new line character exists in the source location value. This character might remain after copying the SAS key from your windows console. -`VS403282: The source location parameter contains a new line character. Please ensure the SAS key is defined on a single line in the import specification file.` +`VS403282: The source location parameter contains a new line character. Please ensure the SAS key is defined on a single line in the migration specification file.` Remove the line break and try again. -**VS403271** +#### VS403271 -Your import files and DACPAC aren't located in the **required** Azure region to complete the import to your target Azure DevOps Services region. +Your migration files and DACPAC aren't located in the **required** Azure region to complete the migration to your target Azure DevOps Services region. -`VS403271: It appears that your DACPAC was uploaded to East US. It's required that customers targeting Central US for import put their DACPACs in Central US. Please move your DACPAC to Central US and requeue the import.` +`VS403271: It appears that your DACPAC was uploaded to East US. It's required that customers targeting Central US for migration put their DACPACs in Central US. Please move your DACPAC to Central US and requeue the migration.` -[Create a new Windows Azure storage account](/azure/storage/common/storage-create-storage-account) in the required region and copy your files. The following example shows how to copy your data using **AzCopy**. +[Create a new Microsoft Azure storage account](/azure/storage/common/storage-create-storage-account) in the required region and copy your files. The following example shows how to copy your data using **AzCopy**. ```cmdline AzCopy.exe /Source:https://accountSCUS.blob.core.windows.net/mycontainer /SourceKey:"primary access key" /Dest:https://accountCUS.blob.core.windows.net/mycontainer /DestKey:"primary access key" /S ``` -**VS403316** +#### VS403316 Inconsistencies were detected in some Team Foundation version control (TFVC) files within your collection. -`VS403316: An inconsistency was detected in some TFVC files for this collection. The inconsistency needs to be corrected prior to running an import to Azure DevOps Services. Please reach out to https://aka.ms/AzureDevOpsImportSupport for assistance with addressing this issue.` +`VS403316: An inconsistency was detected in some TFVC files for this collection. The inconsistency needs to be corrected prior to running a migration to Azure DevOps Services. Please reach out to https://aka.ms/AzureDevOpsImportSupport for assistance with addressing this issue.` -Work with Azure DevOps Services [customer support](https://aka.ms/AzureDevOpsImportSupport). Open a support ticket and they'll work with you to resolve the error. +Work with Azure DevOps Services [customer support](https://aka.ms/AzureDevOpsImportSupport). Open a support ticket and they work with you to resolve the error. -**VS403366** +#### VS403366 -The data migration tool was unable to connect to the SQL Azure VM. +The Data Migration Tool was unable to connect to the SQL Azure VM. ``` VS403366: A problem occurred while attempting to connect to your database. Please verify that your connection string is correct and that all required IP addresses for Azure DevOps Services have been provided exceptions for your machines firewall. @@ -486,38 +463,42 @@ VS403366: A problem occurred while attempting to connect to your database. Pleas List of Azure DevOps Services IPs: ``` -Verify that you've entered the information correctly in your connection string and that you can connect to the VM. +Verify that you entered the information correctly in your connection string and that you can connect to the VM. -The IPs that the error message lists are for Azure DevOps Services. Azure DevOps Services IPs can change temporarily during deployments. Add them to your firewall exceptions and try queuing the import again. For a list of IP addresses, see [Import large collections, Restrict access to Azure DevOps Services IPs only](migration-import-large-collections.md#ips) +The IPs that the error message lists are for Azure DevOps Services. Azure DevOps Services IPs can change temporarily during deployments. Add them to your firewall exceptions and try queuing the migration again. For a list of IP addresses, see [Migrate large collections, Restrict access to Azure DevOps Services IPs only](migration-prepare-test-run.md#migrate-large-collections). -**VS403373** +#### VS403373 -The data migration tool doesn't support importing multiple copies of the **SAME** collection. However, it **DOES** support importing **split** copies of a collection. Change the GUID for the **_DataImportCollectionID_**. +The Data Migration Tool doesn't support migrating multiple copies of the **SAME** collection. However, it **DOES** support migrating **split** copies of a collection. Change the GUID for the **_DataImportCollectionID_**. -From SQL Server Management Studio (SSMS), open the extended properties for the split copies that you haven't imported yet. Add a newly generated GUID to the "TFS_DATAIMPORT_COLLECTIONID" property. Then rerun the **prepare** command and use the new **import.json** file to queue the import. +From SQL Server Management Studio (SSMS), open the extended properties for the split copies that you didn't migrate yet. Add a newly generated GUID to the "TFS_DATAIMPORT_COLLECTIONID" property. Then rerun the **prepare** command and use the new **migration.json** file to queue the migration. -**VS403379** +#### VS403379 -Data import will fail as one or more projects found in this collection are in the soft-deleted stage. Please restore the soft-deleted project(s) or delete them permanently before running the data import. For details, see [Delete a project](../organizations/projects/delete-project.md). +Data migration fails as one or more projects found in this collection are in the soft-deleted stage. Restore the soft-deleted projects or delete them permanently before running the data migration. For details, see [Delete a project](../organizations/projects/delete-project.md). -`VS403379: Data import will fail as one or more projects found in this collection are in the soft-deleted stage. Please restore the soft-deleted project(s) or delete them permanently before running the data import.` +`VS403379: Data migration will fail as one or more projects found in this collection are in the soft-deleted stage. Please restore the soft-deleted project(s) or delete them permanently before running the data migration.` -Verify the collection against which you are running the data migration tool has projects in the soft-deleted stage. Once a project is deleted, it remains in a soft-delete state for 28 days during which the deleted project can be restored. You can read about how to restore a deleted project in [Restore a project](../organizations/projects/restore-project.md). If you have projects in the soft-deleted stage, remove them completely or restore them back before running data import. +Verify the collection against which you're running the Data Migration Tool has projects in the soft-deleted stage. Once a project is deleted, it remains in a soft-delete state for 28 days during which the deleted project can be restored. You can read about how to restore a deleted project in [Restore a project](../organizations/projects/delete-project.md#restore-a-deleted-project). If you have projects in the soft-deleted stage, remove them completely or restore them back before running data migration. -### Import failures +## Resolve migration failures -Import failures happen when the data migration tool successfully queues an import, but fails to complete the import. The individual that queued the import receives a failure email notification. Most of the time this email includes a reason for the failure. If it does, use the troubleshooting steps provided in the email and this page to resolve the errors and retry your import. +Migration failures mean that the migration queued, but didn't complete. The individual who queued the migration receives a failure email notification. Most of the time this email includes a reason for the failure. If it does, use the troubleshooting steps provided in the email and this page to resolve the errors and retry your migration. -If the error is more complex, then the email you receive provides instructions on how to file a [customer support case](https://aka.ms/AzureDevOpsImportSupport). After submitting a customer support case, your team will need to roll back by bringing your Azure DevOps Server instance back online and reattach your collection. Your team members can then continue working. We recommended you not attempt the import again until the failure causing issue is resolved. - +If the error is more complex, then the email you receive provides instructions on how to file a [customer support case](https://aka.ms/AzureDevOpsImportSupport). After you submit a customer support case, your team must roll back by bringing your Azure DevOps Server instance back online and reattach your collection. Your team members can then continue working. We recommended that you don't try the migration again until the failure causing the issue gets resolved. -## Related articles - -- [Validate and import](migration-import.md) -- [Post-import](migration-post-import.md) -- [Delete a project](../organizations/projects/delete-project.md) -- [Restore a project](../organizations/projects/restore-project.md) +## FAQs +#### Q: What should I do if my migration was queued but failed and I didn't receive an email with next steps? +A: If your migration was queued but failed and you didn't receive an email notification, follow these steps: +- **Check migration logs**: Review the migration logs for any error messages that might indicate the cause of the failure. The logs can provide insights into what went wrong during the migration process. +- **Follow troubleshooting steps**: Refer to the troubleshooting steps outlined in this migration troubleshooting guide. These steps can help you identify and resolve common issues that perhaps caused the failure. +- **Contact Customer Support**: If the error is complex or you can't resolve the issue using the logs and troubleshooting steps, consider [filing a customer support case](https://developercommunity.visualstudio.com/AzureDevOpsServerTFS) for further assistance. +- **Rollback and retry**: If necessary, roll back your Azure DevOps Server instance and reattach the collection before attempting the migration again. + +## Related articles +- [Complete post migration tasks](migration-post-import.md) +- [Delete a project](../organizations/projects/delete-project.md) diff --git a/docs/migrate/migration-validate.md b/docs/migrate/migration-validate.md new file mode 100644 index 00000000000..abca39f41ac --- /dev/null +++ b/docs/migrate/migration-validate.md @@ -0,0 +1,202 @@ +--- +title: Validate and prepare server environment for migration +description: Learn how to prepare for migration by validating your environment and resolving errors. +ms.topic: how-to +ms.subservice: azure-devops-migrate +ms.contentid: +ms.author: chcomley +author: chcomley +monikerRange: '<= azure-devops' +ms.date: 05/20/2024 +--- + +# Validate and prepare server environment for migration + +Validation involves preparing your upgraded Azure DevOps Server environment for migration. This article assists you in troubleshooting common issues. If there were no errors and all the validation checks passed, then your team project collection is ready and you can move on to the next phase. Look through the log files to find any errors if not all checks passed. + +:::image type="content" source="media/validate-stage-migration-highres.png" alt-text="Diagram of highlighted Validate stage of the seven stages of migration."::: + +## Prerequisites + +Download the latest [Data Migration Tool](migration-prerequisites.md#download-azure-devops-data-migration-tool). + +## Learn process validation types + +During validation, the Data Migration Tool determines the target process model for each project. It automatically assigns one of the following two process models to each project in the collection: + +- **Inherited process model:** If the project was created with the Agile, Scrum, or Capability Maturity Model Integration (CMMI) process template and was never customized. +- **Hosted XML process model:** If the project process appears to be customized. A customized process contains custom fields, work item types, or other types of customizations. + +When the Hosted XML process is the targeted process model, the Data Migration Tool validates if the customizations can be migrated. The Data Migration Tool generates two files during the validation: + +- **DataMigrationTool.log:** Contains the set of process validation errors found in the collection. Fix all process errors found to proceed with your migration. +- **TryMatchOobProcesses.log:** Lists for each project the target process model - Inheritance or Hosted XML. For projects that are set to target the Hosted XML process model, it explains why they're considered to be customized. You don't have to fix these errors, but they give you guidance what to do in case you want to migrate to the Inheritance process model. Once a collection gets migrated, you can migrate a project to an Inheritance process model. + +## Validate a team project collection + +Since each team project collection corresponds to its own SQL database, the validation process examines various aspects of your collection, including: + +- Size of your collection database +- Collation of the SQL database +- Identities of users in the collection +- Template customizations (process) + +To start validation, use the migrator tool. We recommend running the migrator tool from one of the application tier (AT) servers in your Azure DevOps Server environment. + +For specific command-line options, request help text using the following command: + +```cmdline + Migrator validate /help +``` + +The most common way to start validation is by specifying the URL of the team project collection with the following structure: + +```cmdline + Migrator validate /collection:http://localhost:8080/tfs/DefaultCollection +``` + +## View validation warnings and errors + +When the migrator tool completes, it generates log files and results displayed on the command prompt screen. If no errors occur and all validation checks pass, your team project collection is ready for the next phase. In case validation checks fail, review the log files to identify errors, and then address them. + +Focus on the `Migrator.log` file, which contains essential details about the validation checks and helps you preserve customization. The other files correspond to specific validation errors based on their names. Search for the string "Validation - Starting validation of project 1." Each project is validated. Scan through all the projects and search for any lines that contain a prefix of `[Error...` + +Also, the `TryMatchOobProcesses.log` lists errors related to projects that use Out-of-Box (OOB) processes (such as Agile, Scrum, or CMMI). If a project uses an OOB process without customizations, the project is included in the inherited model. Importantly, errors in this file don’t hinder the migration process. + +:::image type="content" source="media/wit-log-file.png" alt-text="Screenshot of the DataMigrationTool.log file generated by the Data Migration Tool."::: + +For a list of validation errors, see [Resolve validation errors](migration-troubleshooting.md#resolve-field-validation-errors). For each validation error, we provided the error number, description, and the method to resolve. Various error types might appear in the validation check logs. Seek assistance from your trained DevOps Partner, Microsoft Consulting Services, or Microsoft Premier Support for resolving encountered errors. + +## Resolve process template errors + +The primary errors we find are process template issues. These issues stem from either outdated team projects not incorporating Azure DevOps Server's latest features or unsupported customizations by Azure DevOps Services. But, Azure DevOps Services does support a range of customizations, and the validation only flags those requiring resolution premigration. The Data Migration Tool performs a comprehensive check of your templates for Azure DevOps Services compatibility, but some modifications might be necessary. + +- Customized process templates or outdated templates might cause process validation errors during migration. +- If you use an OOB Agile, Scrum, or CMMI process, check the `TryMatchOobProcesses.log` for errors. Error-free projects map to OOB processes. +- Some customizations don’t work in Azure DevOps Services. Review the supported customization list. +- For projects using older templates, run the [Configure Features Wizard](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) to update templates with recent features and reduce error count. +- Ensure `witadmin` is available on the machine where you fix process errors. It’s essential for making changes to process templates. +- For and Not rules should be commented out or removed from the process template before attempting the migration. These rules are supported in Azure DevOps Service, but they are not supported as part of the migration process. Once your collection is migrated, you can add these rules back to the process template. + +Consider the following tools for resolving process errors: + +- Utilize the witadmin.exe command-line tool included with Visual Studio installations. Detailed technical documentation on addressing these errors is available at this link. +- Automate exporting process templates for each team project using an undocumented migrator tool command: Migrator validates /collection:http://localhost:8080/tfs/DefaultCollection /SaveProcesses. +- Explore the TFS Team Project Manager on GitHub (link). It allows you to compare team projects with known process templates, including out-of-the-box templates. + +To fix the errors, change the XML syntax and apply the changes back to the project. + +> [!TIP] +> We recommend that you modify the XML manually, rather than using TFS Power Tools. + +To get the process template from the project, add the `/SaveProcesses` parameter when you run the Data Migration Tool command. + +```cmdline +Migrator validate /collection:{collection URL} /tenantDomainName:{name} /region:{region} /SaveProcesses +``` + +This command extracts the XML from the project and places it into the same folder as the logs. Extract the zip files to your local machine so that you can edit the files. + +Now, fix the XML. Use the logs from the DataMigrationTool.log file to determine the errors for each project. + +:::image type="content" source="media/wit-log-file.png" alt-text="Screenshot of Process logging file generated by the Data Migration Tool."::: + +Some errors require you to do use a `witadmin changefield` command. Changing a field name is the most common example. To save yourself some time, we recommend you run the witadmin `changefield` command and then rerun the Data Migration Tool. Doing so re-exports the XML with the corrected names. Otherwise, manually fix the fields in the XML syntax as well. + +Once you make a fix, apply the changes back to the Azure DevOps Server. Depending on the changes you made, you need to run one or more witadmin commands. We created a PowerShell script to automate this process. The script contains all of the witadmin commands needed to confirm the entire process. + +You can get the scripts at Process Customization Scripts. Use the import/ConformProject.ps1 script. + +```cmdline +.\conformproject.ps1 "" "" "" +``` + +When the script completes, rerun the Data Migration Tool to validate the collection. Follow steps 1 through 3 until the Data Migration Tool generates no more validation errors. + +:::image type="content" source="media/conform-project-processes-powershell.png" alt-text="Screenshot of conform project process in PowerShell."::: + +> [!TIP] +> If you're new to XML and witadmin, we suggest you make one fix at a time and then conform. Continue this loop until all errors are resolved. + +## Update to a system process + +If you began with an older version of Azure DevOps Server, your projects likely use an older process template. If these projects weren't updated using the [Configure Features Wizard](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade), the Data Migration Tool detects process errors. In rare cases, even the wizard might not resolve old process-related issues. + +You might receive some of the following sample error messages: + +```no-highlight +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element PortfolioBacklog is missing from Process Configuration. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element BugWorkItems is missing from Process Configuration. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element FeedbackRequestWorkItems is missing from Process Configuration. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element FeedbackResponseWorkItems is missing from Process Configuration. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Team. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField RemainingWork. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Order. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Effort. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Activity. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationStartInformation. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationLaunchInstructions. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationType. +Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF400572: The Project Process Settings must be configured for this feature to be used. +``` + +If you didn't customize your project (for example, added fields, work item types, and so on.), fixing these errors is straightforward. But, if you customized your process, this approach doesn't suffice. You need to manually adjust the process templates to preserve your customizations from being overwritten. + +Do the following steps, for each project, to align your process: + +1. Identify the initial process your project started with (Scrum, Agile, or CMMI). +2. Visit the Process Customization Scripts on GitHub and download the repository. +3. Focus on the contents in the Migration folder. +4. Utilize the following `ConformProject.ps1` script to align a project of your choice with the Agile system process. This action updates the entire project to be Agile. + +```cmdline +.\ConformProject.ps1 "" "" "c:\process-customization-scripts\import\agile" +``` + +## Common validation errors + +### VS402841: Field X in work item type Bug has syncnamechanges=false but has rules making it an identity field. Identity fields must have syncnamechanges=true. Please update your process template to include this change. + +In Azure DevOps Services, we added a rule so that every identity field must have the `syncnamechanges=true` attribute. In Azure DevOps Server that rule doesn't apply. Therefore, the Data Migration Tool identifies this as an issue. Making this change on Azure DevOps Server on-premises doesn't cause any harm. + +Run the witadmin `changefield` command. Syntax for the command looks like the following example. + +```cmdline +witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /syncnamechanges:true +``` + +For more information on the witadmin `changefield` command, see [Manage work item fields](../reference/witadmin/manage-work-item-fields.md). + +### TF402556: For field System.IterationId to be well defined, you must name it Iteration ID and set its type to Integer. + +This error is often associated with outdated process templates. To address it, you can run the [Configure Features Wizard](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) for each project. Alternatively, you might execute the following command to automate the process. + +```cmdline +witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /name:newname +``` + +### TF402571: Required element BugWorkItems is missing from Process Configuration. + +This error is commonly seen when a process wasn't updated for some time. To fix it, run the [Configure Features Wizard](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade?view=tfs-2017&preserve-view=true) for each project. + +### TF402564: You've defined XX global lists. Only 64 are allowed + +Azure DevOps Services natively supports 64 global lists. This error typically arises when there's an extensive number of build pipelines, as each new pipeline creates a global list named `Builds - TeamProjectName`. To resolve this error, remove any outdated global lists. + +## Repeat validation checks + +In each iteration, address errors and conduct validation checks to resolve them, as indicated by the validation log files. Persist with this cycle until all errors are rectified and you receive confirmation that the collection validation checks are successful. + +## Next steps + +> [!div class="nextstepaction"] +> [Prepare for test run](migration-prepare-test-run.md) + +## Related articles + +- [`witadmin`: Customize and manage objects for tracking work](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) +- [Differences between Azure DevOps Services and Azure DevOps Server process template customizations](../organizations/settings/work/import-process/differences.md) +- [Configure features after Azure DevOps Server upgrade](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) +- [Resolve validation errors](../organizations/settings/work/import-process/resolve-errors.md) +- [Define global lists in Azure DevOps Server](/previous-versions/azure/devops/reference/xml/define-global-lists) +- [Process customization PowerShell scripts](https://github.com/Microsoft/process-customization-scripts) diff --git a/docs/migrate/phase-rollout-with-rings.md b/docs/migrate/phase-rollout-with-rings.md deleted file mode 100644 index dbfb0d02ae7..00000000000 --- a/docs/migrate/phase-rollout-with-rings.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Progressively expose your releases using deployment rings -description: Learn how to progressively expose your Azure DevOps extension releases in production to validate, before affecting all users. -ms.assetid: F6B1E468-A762-4E6A-BBAB-8D9C0EA8A095 -ms.topic: conceptual -ms.subservice: azure-devops-migrate -ms.date: 09/23/2021 -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' ---- - -# Use deployment rings with extension releases - -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - -With deployment rings, you can gradually deploy and validate changes to your extension in production, while limiting the affect on your users. - -We don't recommend deploying to all production environments at the same time, which exposes all users to the changes. A gradual rollout exposes users to the changes over time, validating the changes in production with fewer users. - -The following table shows the differences for affected areas when you're using rings vs. no rings. - -| Without rings | Affected area | With rings | -|--------------------|:-:|-----------:| -|Manual and error prone|Build|Automated and consistent| -|Manual and error prone|Release|Automated and consistent| -|Hours|Time to build (TTB)|Seconds| -|Days|Time to release (TTR)|Minutes| -|Call from user|Issue detection|Proactive| -|Days to weeks|Issue resolution|Minutes to days| - -For more information, see [Configuring your release pipelines for safe deployments](https://devblogs.microsoft.com/devops/configuring-your-release-pipelines-for-safe-deployments/). - -## Prerequisites - -* Review [CI/CD Pipelines](../pipelines/get-started/pipelines-get-started.md) and [Approvals](../pipelines/release/approvals/index.md) for detailed documentation of pipelines and the approval features for releases. - -## Assign user types - -Determine which users are best suited for each user type. Communicate the opportunity to provide feedback and the risk levels at each tier, as it's critical to setting expectations and ensuring success. In the following example, users get divided into three groups in production: - -* **Canaries**: voluntarily test features as soon as they're available. -* **Early adopters**: voluntarily preview releases, considered more refined than the canary bits. -* **Users**: consume the products, after they've passed through canaries and early adopters. - -![User Rings](./media/phase-rollout-with-rings/phase-rollout-with-rings-rings.png) - -## Map the topology - -Map the topology of your extension to the ringed deployment model to limit the impact of change on your users and deliver value. For our open-source community extensions, we mostly use ring-based deployment to progressively expose a new release to canary, early adopters, and users. - -At the application level, the composition of Azure DevOps extensions is easy to digest, scale, and deploy independently. - -Each extension does the following tasks: - -* Has one of more web and script files -* Interfaces with Core client -* Interfaces with REST client and REST APIs -* Persists state in cache or resilient storage - -![Progressive exposure of the application layer](./media/phase-rollout-with-rings/phase-rollout-with-rings-app-layer.png) - -At the infrastructure level, the extensions get published to the [Marketplace](https://marketplace.visualstudio.com). Once you install the extension in your organization, it gets hosted by the Azure DevOps service portal, with state persisted to Azure storage or the extension [data storage](../extend/develop/data-storage.md). - -![Progressive exposure of the infrastructure layer](./media/phase-rollout-with-rings/phase-rollout-with-rings-inf-layer.png) - -The extension topology is perfectly suited for the ring deployment model and to publish the extension to each deployment ring: - -* A **private** development version for the canary ring -* A **private** preview version for the early adopter ring -* A **public** production version for the users ring - -> [!TIP] -> Publish your extension as *private*, to control exposure to invited users. - -## Move changes through deployment rings - -See the following example flow of moving changes through deployment rings. - -::: moniker range=">= azure-devops-2019" - -Use the [Azure DevOps Developer Tools Build Tasks](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vsts-developer-tools-build-tasks) extension to package and publish extensions to the Marketplace. - -![Extension rings](./media/phase-rollout-with-rings/phase-rollout-with-rings-pipeline.png) - -::: moniker-end - -1. A developer from the [Countdown Widget extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.CountdownWidget) project commits a change to the [GitHub](https://github.com/ALM-Rangers/Countdown-Widget-Extension) repository. -2. The commit triggers a continuous integration build. -3. The new build triggers a continuous deployment trigger, which automatically starts the **Canaries** environment deployment. -4. The **Canaries** deployment publishes a private extension to the Marketplace and shares it with predefined organizations. Only the **Canaries** are affected by the change. -5. The **Canaries** deployment triggers the **Early Adopter** environment deployment. A pre-deployment approval gate requires any one of the authorized users to approve the release. - ![Pre-deployment approval for Early Adopter environment](./media/phase-rollout-with-rings/phase-rollout-with-rings-early-approval.png) -6. The **Early Adopter** deployment publishes a private extension to the marketplace and shares it with predefined organizations. Both the **Canaries** and **Early Adopter** are affected by the change. -7. The **Early Adopter** deployment triggers the **Users** environment deployment. A stricter pre-deployment approval gate requires all of the authorized users to approve the release. - ![Pre-deployment approval for User environment](./media/phase-rollout-with-rings/phase-rollout-with-rings-users-approval.png) -8. The **Users** deployment publishes a public extension to the marketplace. At this stage, everyone who installed the extension in their organization is affected by the change. -9. It's key to realize that the effect increases as your change moves through the rings. Exposing the change to the **Canaries** and the **Early Adopters** gives you two opportunities to validate the change and hotfix critical bugs before you release to production. - -## Monitor issues - -Monitoring and alerts can help you detect and mitigate issues. Determine what type of data is important, for example: infrastructure issues, violations, and feature usage. Focus on actionable alerts to avoid users ignoring them and missing high priority issues. - -> [!TIP] -> Start with high-level views of your data, visual dashboards that you can watch from afar and drill-down, as needed. Perform regular housekeeping of your views and remove all noise. A visual dashboard tells a better story than lots of notification emails, often filtered and forgotten by email rules. - - - -Use [Team Project Health](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.TeamProjectHealth) and other extensions to build an overview of your pipelines, lead and cycle times, and gather other information. In the sample dashboard, it's evident that there are 34 successful builds, 21 successful releases, 1 failed release, and 2 releases in progress. - -![High-level dashboard on Azure DevOps](./media/phase-rollout-with-rings/phase-rollout-with-rings-dash.png) - -## Is there a dependency on feature flags? - -No. Sometimes you might need a certain functionality to be deployed as part of a release, but not initially exposed to users. Feature flags give you fine-grained control of features that are included in your change. For example, if you're not fully confident about a feature you can use feature flags to **hide** the feature in one or all of the deployment rings. You can enable all features in the canaries ring, and fine-tune a subset for the early adopters and production users, as shown in the following image. - -![Feature flags](./media/phase-rollout-with-rings/phase-rollout-with-rings-feature-flags.png) - -For more information, see [Progressive experimentation with feature flags](/devops/operate/progressive-experimentation-feature-flags). - -## FAQ - -### Q: How do you know that a change can be deployed to the next ring? - -A: You should have a consistent checklist for the users approving a release. - -### Q: How long do you wait before you push a change to the next ring? - -There's no fixed duration or "cool off" period. It depends on how long it takes for you to complete all release validations successfully. - -### Q: How do you manage a hotfix? - -A: The ring deployment model allows you to process a hotfix like any other change. The sooner you catch an issue, the sooner you can deploy a hotfix with no effect to downstream rings. - -### Q: How do you deal with variables that span shared release environments? - -A: Refer to [Default and custom release variables](../pipelines/release/variables.md). - -### Q: How can you manage secrets used by the pipeline? - -A: To safeguard cryptographic keys and other secrets used by your pipelines, see [Azure Key Vault](https://azure.microsoft.com/services/key-vault/). - -## Related articles - -* [Safe deployment practices](/devops/operate/safe-deployment-practices) -* [Progressive experimentation with feature flags](/devops/operate/progressive-experimentation-feature-flags) -* [Configure your release pipelines for safe deployments](https://devblogs.microsoft.com/devops/configuring-your-release-pipelines-for-safe-deployments/). diff --git a/docs/migrate/toc.yml b/docs/migrate/toc.yml index c301a36348c..c7503557b4b 100644 --- a/docs/migrate/toc.yml +++ b/docs/migrate/toc.yml @@ -1,23 +1,27 @@ -- name: Migrate data to Azure DevOps Services - href: migration-overview.md +- name: Migration overview displayName: migration, migration guide, migration tool -- name: Migrate options - href: migrate-from-tfs.md + href: migration-overview.md +- name: 1. Get started with Data Migration Tool displayName: migration options, database, migration guide -- name: Import - href: migration-import.md + href: migration-get-started.md +- name: 2. Complete prerequisites displayName: database import, data migration tool, validate collection -- name: Import large collections - href: migration-import-large-collections.md + href: migration-prerequisites.md +- name: 3. Validate & prepare server environment displayName: reduce collection size -- name: Process templates - href: migration-processtemplates.md + href: migration-validate.md +- name: 4. Prepare test run + displayName: restrict access to azure devops services ips only + href: migration-prepare-test-run.md +- name: 5. Do test run displayName: inherited process model, hosted xml process model -- name: Post-import - href: migration-post-import.md -- name: Troubleshooting + href: migration-test-run.md +- name: 6. Migrate + displayName: migration tool, migration process, migration service + href: migration-migrate.md +- name: 7. Complete post-migration tasks + displayName: post migration tasks, post migration steps, post migration activities + href: migration-post-migration.md +- name: Resolve migration errors + displayName: migration errors, migration issues, migration problems, troubleshoot migration href: migration-troubleshooting.md - displayName: maximum supported size, isverror 100014, isverror 300005, VS4034, VS4032, VS4033 -- name: FAQs, migration and process models - href: faqs.yml - displayName: hosted xml \ No newline at end of file diff --git a/docs/organizations/accounts/access-with-azure-ad.md b/docs/organizations/accounts/access-with-azure-ad.md index 9d959094abf..966ec8354ea 100644 --- a/docs/organizations/accounts/access-with-azure-ad.md +++ b/docs/organizations/accounts/access-with-azure-ad.md @@ -1,45 +1,62 @@ --- -title: Access your organization with Azure Active Directory +title: Access your organization with Microsoft Entra ID titleSuffix: Azure DevOps Services -ms.custom: seodec18, engagement-fy23 -description: About user authentication and controlling conditional access to your organization with your Azure Active Directory tenant. +ms.custom: engagement-fy23 +description: About user authentication, and controlling conditional access to your organization with a Microsoft Entra tenant. ms.subservice: azure-devops-organizations ms.assetid: c9aecaaf-9dfb-4877-84b4-60da253e3dc2 ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 10/05/2022 +ai-usage: ai-assisted +ms.date: 10/22/2024 monikerRange: 'azure-devops' --- -# About accessing your organization via Azure AD +# About accessing your organization via Microsoft Entra ID [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] [!INCLUDE [alt-creds-deprecation-notice](../../includes/alt-creds-deprecation-notice.md)] -Learn about controlling access to your organization via Azure Active Directory (Azure AD). -If your organization was created with a Microsoft account, connect your organization to your [Azure Azure AD](/azure/active-directory/fundamentals/active-directory-whatis). -Sign in to Azure DevOps with the same username and password that you use with your Microsoft services. -Enforce policies for accessing your team's critical resources and key assets. +This article discusses controlling access to your organization using Microsoft Entra ID. Connecting your organization to Microsoft Entra ID enhances security and simplifies user management. + +## Benefits of using Microsoft Entra ID + +- **Centralized management**: Manage user access and permissions from a single location. Microsoft Entra administrators oversee user access, providing secure and centralized control. +- **Enhanced security**: Utilize advanced security features like MFA and conditional access. +- **Simplified user experience**: Provide a seamless sign-in experience with SSO. +- **Directory-based authentication**: Only users who are members or guests in your directory can access your organization. +- **Access revocation**: Disabled or removed users have no access by any mechanism, including PATs or SSH. +- **Manual management without Entra ID**: Without Microsoft Entra ID, you manually manage access, and all users sign in with only Microsoft accounts. + +For more information on setting up and managing Microsoft Entra ID, see the [Microsoft Entra ID documentation](/azure/active-directory/fundamentals/active-directory-whatis). > [!NOTE] -> To use existing on-premises identities with Azure DevOps, you can integrate directories with Azure AD by using [Azure AD Connect](/azure/active-directory/hybrid/whatis-hybrid-identity). To switch your organization to another directory, learn [how to change your directory in Azure AD](change-azure-ad-connection.md). +> To use existing on-premises identities with Azure DevOps, integrate your directories with Microsoft Entra ID using [Microsoft Entra Connect](/azure/active-directory/hybrid/whatis-hybrid-identity). You can also [switch your directory in Microsoft Entra ID](change-azure-ad-connection.md). + +## High-level steps to connect your organization to Microsoft Entra ID + +1. **Connect to Microsoft Entra ID**: If your organization was created with a Microsoft account, connect it to your [Microsoft Entra ID](/azure/active-directory/fundamentals/active-directory-whatis). This integration allows you to manage access and enforce security policies centrally. +2. **Sign in**: Use the same credentials that you use with your Microsoft services to sign in to Azure DevOps. The single sign-on (SSO) capability streamlines the sign-in process and improves security. +3. **Enforce policies**: Implement and enforce policies to control access to your team's critical resources and key assets. Microsoft Entra ID provides robust policy management features, including multifactor authentication (MFA), conditional access, and role-based access control. + + + +## How Microsoft Entra ID controls access to Azure DevOps -## How Azure AD controls access to Azure DevOps +Your organization authenticates users through its directory, ensuring that only members or guests within that directory can access your organization. Disabled or removed users from your directory are denied access by any mechanism, including personal access tokens (PATs) or SSH. -Your organization authenticates users through its directory. Only users who are members or guests in that directory get access to your organization. -Disabled or removed users from your directory have no access to your organization by any mechanism. For example, mechanisms such as personal access tokens (PATs) or SSH. -Only specific [Azure AD administrators](/azure/active-directory/roles/permissions-reference) manage users in your directory, so they control who gets access to your organization. +Access control gets managed by specific [Microsoft Entra administrators](/azure/active-directory/roles/permissions-reference) who oversee user management within your directory. These administrators can control who gets access to your organization, ensuring secure and centralized management. -Without Azure AD, you're solely responsible for controlling organization access. All users must sign in with Microsoft accounts. +Without Microsoft Entra ID, you're solely responsible for controlling organization access. In this case, all users sign in with only Microsoft accounts, and you manually manage user permissions and access. For more information, see [Frequently asked questions about Azure access](faq-azure-access.yml) ## Related articles -* [Add or delete users using Azure Active Directory](/azure/active-directory/fundamentals/add-users-azure-active-directory) -* [Connect your organization to Azure AD](./connect-organization-to-azure-ad.md) -* [Disconnect your organization from Azure AD](./disconnect-organization-from-azure-ad.md) -* [Get a list of organizations backed by Azure AD](get-list-of-organizations-connected-to-azure-active-directory.md) +* [Add or delete users using Microsoft Entra ID](/azure/active-directory/fundamentals/add-users-azure-active-directory) +* [Connect your organization to Microsoft Entra ID](./connect-organization-to-azure-ad.md) +* [Disconnect your organization from Microsoft Entra ID](/azure/active-directory/add-users-azure-active-directory#delete-a-user) +* [Get a list of organizations backed by Microsoft Entra ID](get-list-of-organizations-connected-to-azure-active-directory.md) * [Restrict organization creation with tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) diff --git a/docs/organizations/accounts/add-external-user.md b/docs/organizations/accounts/add-external-user.md index 5a1fc46f9e6..5eec4f9307d 100644 --- a/docs/organizations/accounts/add-external-user.md +++ b/docs/organizations/accounts/add-external-user.md @@ -1,14 +1,13 @@ --- title: Add, invite guest external users to your organization titleSuffix: Azure DevOps Services -ms.custom: seodec18 -description: Learn how to invite an external user or outside guest to your organization +description: Learn how to invite an external user or outside guest to your organization. ms.subservice: azure-devops-organizations ms.assetid: ec935536-6a5e-4b62-adf2-4207a70440bd ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 05/09/2022 +ms.date: 10/22/2024 monikerRange: 'azure-devops' --- @@ -16,23 +15,18 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Learn how to invite external users to your organization. If you access Azure DevOps via Azure Active Directory (Azure AD), you must add the identities of those users to your Azure AD. Doing so also grants the users more privileges. For more information, see [more organization-level resources](../projects/resources-granted-to-project-members.md). +Learn how to invite external users to your organization. If you access Azure DevOps via Microsoft Entra ID, you must add the identities of those users to your Microsoft Entra ID. Doing so also grants the users more privileges. For more information, see [more organization-level resources](../projects/resources-granted-to-project-members.md). ## Prerequisites +| Category | Requirements | +|--------------|-------------| +|**Permissions** | Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +| **Microsoft Entra tenant** |The Microsoft Entra tenant to which you want to invite external users allows adding new users, as per your Microsoft Entra guest policies. For more information, see [how to become eligible to invite external users on your Microsoft Entra tenant](/azure/active-directory/active-directory-b2b-delegate-invitations).| +| **Policies** |- **External guest access** turned **On** for the organization to which you want to invite external users.
      - Team and Project Administrators can only invite external users if the user policy, **Allow team and project administrators to invite new users**, is **On**. For more information, see [Restrict invitations from Project and Team Administrators](../security/restrict-invitations.md).
      - If the **Invite GitHub users** policy displays, you're recognized as a GitHub user and the GitHub invitation experience is available. For more information, see [Enable GitHub invitations](../../repos/get-started/sign-up-invite-teammates.md).| -* You must be a member of the Project Collection Administrators or Project Administrators group for the organization that you want to invite external users to. - -* The Azure AD tenant, to which you want to invite external users, must allow adding new users, per your Azure AD guest policies. For more information, see [how to become eligible to invite external users on your Azure AD tenant](/azure/active-directory/active-directory-b2b-delegate-invitations). - -* The user policy, **External guest access**, must be **On** for the organization that you want to invite external users to. See the following image example. - * Team and Project Administrators can only invite external users if the user policy, **Allow team and project administrators to invite new users**, is **On**. For more information, see [Restrict invitations from Project and Team Administrators](../security/restrict-invitations.md). - * If instead the *Invite GitHub users* policy displays, you're recognized as a GitHub user and so the GitHub invitation experience is available. For more information, see [Enable GitHub invitations](../../repos/get-started/sign-up-invite-teammates.md). - -![External guest access turned on](media/add-external-user/guest-access-preview.png) - -> [!TIP] -> We recommend using a different email or user principal name (UPN) for your personal and business accounts, rather than using the same, even though it's allowed. This eliminates the challenge of disambiguating between your business and personal accounts when the email/UPN is the same. +> [!IMPORTANT] +> **Required:** Use a different email address or user principal name (UPN) for your personal and business accounts. This eliminates the challenge of disambiguating between your business and personal accounts when the email or UPN is the same. ## Invite external user @@ -44,9 +38,9 @@ Learn how to invite external users to your organization. If you access Azure Dev 3. Select **Users**, and then select **Add users**. - ![Select the Users tab, and then select Add users](../../media/add-new-users.png) + ![Screenshot showing Select the Users tab, and then select Add users.](../../media/add-new-users.png) -4. Complete the form based on the following guidance, and then select **Add**. +4. Enter information based on the following guidance, and then select **Add**. - **Users**: Enter the email address for the user. You can add several email addresses by separating them with a semicolon (;). For Microsoft accounts (MSAs), the email addresses display in red. - **Access level**: You can add up to five users with *Basic* access. You're included as one of the five users. Otherwise, you can add an unlimited number of users with *Stakeholder* access. In public projects, both Stakeholder and Basic access levels grant full access to **Code**, **Work**, and **Build and Release**. But, Stakeholders only get partial access to **Test** and **Dashboards**. For more information, see [Default roles & permissions](../security/permissions-access.md). @@ -54,20 +48,20 @@ Learn how to invite external users to your organization. If you access Azure Dev - **Azure DevOps Groups**: Leave this entry at Project Contributors, the default security group for people who contribute to your project. For more information, see [Default permissions and access assignments](../security/permissions-access.md). - **Send email invites**: Check this box to invite your new users via their email addresses. -5. Advise the external user to locate the email that they received from AzureDevOps@microsoft.com with the subject, **You have been invited to an Azure DevOps project** and select **Join now**. This final step adds the user to your organization. The invitation looks similar to the following image. +5. Advise the external user to locate the email that they received from `AzureDevOps@microsoft.com` with the subject, **You have been invited to an Azure DevOps project** and select **Join now**. This final step adds the user to your organization. The invitation looks similar to the following image. - :::image type="content" source="media/add-external-user/external-user-email-invitation.png" alt-text="External user's invitation email"::: + :::image type="content" source="media/add-external-user/external-user-email-invitation.png" alt-text="Screenshot showing External user's invitation email."::: >[!Note] ->If you need to resend the invitation email, go to **Users**, select the user, and then select **Resend invite**. +> If you need to resend the invitation email, go to **Users** > select the user > **Resend invite**. The external user is added to the organization to which they were invited and has immediate access. -A guest user can add other guest users to the organization after being granted the Guest Inviter role in Azure AD. +A guest user can add other guest users to the organization after being granted the Guest Inviter role in Microsoft Entra ID. ## Related articles -* [What is Azure AD B2B collaboration?](/azure/active-directory/active-directory-b2b-what-is-azure-ad-b2b) +* [Learn about Microsoft Entra B2B collaboration](/azure/active-directory/active-directory-b2b-what-is-azure-ad-b2b) * [Migrate to group-based resource management](./assign-access-levels-by-group-membership.md) * [Assign access levels to users by group membership](assign-access-levels-by-group-membership.md) * [Restrict invitations to new users](../security/restrict-invitations.md) diff --git a/docs/organizations/accounts/add-organization-users.md b/docs/organizations/accounts/add-organization-users.md index ce14a082f3a..5d289c29a0a 100644 --- a/docs/organizations/accounts/add-organization-users.md +++ b/docs/organizations/accounts/add-organization-users.md @@ -1,15 +1,16 @@ --- title: Add users to organizations and manage access titleSuffix: Azure DevOps -ms.custom: seodec18 -description: Learn how to add users to an organization and manage users' access levels (like Stakeholder), direct assignments, invitations, and more. +ms.custom: devx-track-azurecli +description: Learn how to add users to an organization and manage users' access levels, direct assignments, invitations, and more. ms.topic: how-to ms.subservice: azure-devops-organizations ms.assetid: 19ac647f-04c1-4ddd-9953-b3ecfa0f1457 +ai-usage: ai-assisted ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 03/23/2023 +ms.date: 04/10/2025 --- # Add organization users and manage access @@ -18,11 +19,12 @@ ms.date: 03/23/2023 Learn how to add users to your organization and manage user access through direct assignment. For an overview of adding users and related concepts, see [About organization management in Azure DevOps](organization-management.md). Users can include human users, service accounts, and [service principals](../../integrate/get-started/authentication/service-principal-managed-identity.md). -The following types of users can join your Azure DevOps Services organization for free: +The following types of users can join your organization for free: * Five users who get [Basic features](https://azure.microsoft.com/services/devops/compare-features/), such as version control, tools for Agile, Java, build, release, and more -* Unlimited users who get [Stakeholder features](https://azure.microsoft.com/services/devops/compare-features/), such as working with your backlog, work items, and queries -* Unlimited [Visual Studio subscribers](https://azure.microsoft.com/services/devops/compare-features/) who also get Basic or Basic + Test Plan features, depending on their subscription level. +* Unlimited users who get [Stakeholder features](https://azure.microsoft.com/services/devops/compare-features/), such as working with your backlog, work items, and queries. Don't use Stakeholder access as a substitute for more limited permissions, as users with a Visual Studio subscription or a GitHub Enterprise license automatically get upgraded from Stakeholder when they sign in. For more information, see [Stakeholder access quick reference](../security/stakeholder-access.md). +* Unlimited [Visual Studio subscribers](https://azure.microsoft.com/services/devops/compare-features/) who also get Basic or Basic + Test Plan features, depending on their subscription level. +* Unlimited [GitHub Enterprise users](https://github.com/enterprise) who also get Basic features when they sign in with their GitHub Enterprise account. [Need more users with Basic features?](../billing/buy-basic-access-add-users.md) @@ -31,26 +33,25 @@ The following types of users can join your Azure DevOps Services organization fo ## Prerequisites -* You must have an organization. If you don't have an organization yet, [create one](create-organization.md). -* You must be a member of the [**Project Collection Administrators** group](../security/change-organization-collection-level-permissions.md). Organization owners are automatically members of this group. +| Category | Requirements | +|--------------|-------------| +|**Permissions** | Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. Or, if [invitation restrictions are enabled](../security/restrict-invitations.md), the Project Administrator can add users. The Project Collection Administrator role can't select the license for new users or remove users from the organization.| +|**Organization** | An [organization](create-organization.md).| -For an overview of the methods supported for adding users to an organization, see [About organization management, Add and manage user access](organization-management.md#add-users). +For an overview of the methods supported for adding users to an organization, see [Add and manage user access](organization-management.md#add-users). ## Add users to your organization -Administrators can add users to an organization, grant access to appropriate tooling extensions and service access levels, -and add users to groups - all in one view. +Administrators can efficiently manage user access by adding users to an organization. Provide access to the appropriate tooling extensions and service access levels, and assign users to relevant groups—all from a single view. This streamlined process ensures that new users have the necessary permissions and resources to start contributing immediately. > [!NOTE] -> If you have an Azure Active Directory (Azure AD)-backed organization, and you need to add users who are external to Azure AD, first [add external users](add-external-user.md). On the **Tell us about this user page**, under **Type of user**, be sure to choose **User with an existing Microsoft account**. After you complete those steps, use the following steps to add the Azure AD - > user to Azure DevOps. +> If you have a Microsoft Entra ID-backed organization and need to add users who are external to Microsoft Entra ID, first [add external users](add-external-user.md). On the **Tell us about this user** page, under **Type of user**, choose **User with an existing Microsoft account**. After completing those steps, follow these instructions to add the Microsoft Entra ID user to Azure DevOps. -You can add up to 50 users in a single transaction. When you add users, each user receives a notification email with a -link to the organization page. +You can add up to 50 users in a single transaction. When you add users, each user receives a notification email with a link to the organization page, allowing them to easily access and start using the organization's resources. #### [Browser](#tab/browser) -To give other users access to your organization, add their email addresses. +To give other users access to your organization, do the following steps: 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). @@ -58,7 +59,7 @@ To give other users access to your organization, add their email addresses. ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) -3. Select **Users**, and then select **Add users**. +3. Select **Users** > **Add users**. ![Select the Users tab, and then select Add users](../../media/add-new-users.png) @@ -67,20 +68,21 @@ To give other users access to your organization, add their email addresses. > [!div class="mx-imgBorder"] >![Web portal, organization admin context, Add new users dialog box](media/add-organization-users-from-user-hub/add-new-users-dialog.png) - * **Users:** Enter the email addresses (Microsoft accounts) or GitHub usernames for the users. You can add several email addresses by separating them with a semicolon (;). An email address appears in red when it's accepted. For more information about GitHub authentication, see [FAQs](../security/faq-github-authentication.yml). To add a service principal, enter the display name of the application or managed identity. - * **Access level:** Leave the access level as **Basic** for users who contribute to the code base. To learn more, see [About access levels](../security/access-levels.md). - * **Add to projects:** Select the project you want to add them to. - * **Azure DevOps Groups:** Leave as **Project Contributors**, the default security group for users who contribute to your project. To learn more, see [Default permissions and access assignments](../security/permissions-access.md). + * **Users:** Enter the email addresses (Microsoft accounts) or GitHub usernames of the users. You can add multiple email addresses by separating them with a semicolon `;`. Accepted email addresses appear in red. For more information about GitHub authentication, see [Connect to GitHub/FAQs](../../boards/github/connect-to-github.md#faqs). To add a service principal, enter the display name of the application or managed identity. + * **Access level:** Set the access level to **Basic** for users who contribute to the code base. For more information, see [About access levels](../security/access-levels.md). + * **Add to projects:** Select the project to which you want to add the users. + * **Azure DevOps Groups:** Leave as **Project Contributors**, the default security group for users who contribute to your project. For more information, see [Default permissions and access assignments](../security/permissions-access.md). + + >[!NOTE] + > Add email addresses for [personal Microsoft accounts](https://account.microsoft.com/account) and IDs for GitHub accounts unless you plan to use [Microsoft Entra ID](/azure/active-directory/fundamentals/active-directory-whatis) to authenticate users and control organization access. If a user doesn't have a Microsoft or GitHub account, ask them to sign up for a [Microsoft account](https://signup.live.com/) or a [GitHub account](https://github.com/join). - > [!NOTE] - > Add email addresses for [personal Microsoft accounts](https://account.microsoft.com/account) and IDs for GitHub accounts unless you plan to use [Azure Active Directory (Azure AD)](/azure/active-directory/fundamentals/active-directory-whatis) to authenticate users and control organization access. If a user doesn't have a Microsoft or GitHub account, ask the user to sign up for a [Microsoft account](https://signup.live.com/) or a [GitHub account](https://github.com/join). 5. Select **Add** to complete your invitation. #### [Azure DevOps CLI](#tab/azure-devops-cli/) [Add a user](#add-user) | [List users](../security/export-users-audit-log.md#list-users) | [Remove a user](delete-organization-users.md#remove-user) | [Update a user](add-organization-users.md#update-user) | [Show users](add-organization-users.md#show-users) - + ### Add a user @@ -96,7 +98,7 @@ az devops user add –-email-id #### Parameters * **email-id**: Required. Enter the Microsoft account's email address for the user organization. -* **license-type**: Required. Enter stakeholder, express, professional, or advanced based on the mapping provided in the following table. For Users who contribute to the code base require express or higher level of license-type. To learn more, see [About access levels](../../organizations/security/access-levels.md). +* **license-type**: Required. Enter stakeholder, express, professional, or advanced based on the mapping provided in the following table. For Users who contribute to the code base require express or higher level of license-type. For more information, see [About access levels](../../organizations/security/access-levels.md). * **send-email-invite**: Optional. Specify whether to send email invite for new user or not. * **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. @@ -125,7 +127,7 @@ ID Display Name Email ``` -You can also add the user to the project-level **Contributors** group, the default Azure DevOps security group for people who contribute to your project. To learn more, see [Add or remove users or groups, manage security groups](../security/add-remove-manage-user-group-security-group.md). +You can also add the user to the project-level **Contributors** group, the default Azure DevOps security group for people who contribute to your project. For more information, see [Add or remove users or groups, manage security groups](../security/add-remove-manage-user-group-security-group.md). ```azurecli az devops security group membership --group-id vssgp.Uy0xLTktMTU1MTM3NDI0NS0xMTM1NzQ1NzUzLTExNDI0NTQwOTQtMjQ4MjkwODAwNS0xNDU4NjAwODE1LTEtMTY5NTI2NTAyNi00MjM0Mzc1NS0yMTY5ODM4OTczLTI0NDk3NzU5NDE --member-id contoso@contoso.com @@ -138,20 +140,20 @@ You can see all security groups in a project using the [az devops security group For more information about user access, read [about access levels](../security/access-levels.md). > [!NOTE] -> You can add people to projects instead of to your organization. Users are automatically assigned [Basic features](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) if your organization has seats available, or [Stakeholder features](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) if not. Learn how to [add members to projects](../security/add-users-team-project.md#add-users-to-a-project). +> You can add people to projects instead of to your organization. Users are automatically assigned [Basic features](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) if your organization has available access, or [Stakeholder features](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) if not. For more information, see [Add users to projects](../security/add-users-team-project.md#add-users-to-a-project). > > When a user no longer needs access to your organization, [delete them](delete-organization-users.md) from your organization. ## Manage users -From your web browser, you can view and edit certain user information. From the Azure DevOps CLI command, you can see details about a specific user and update their access level. +From your web browser, you can view and edit certain user information. Using the Azure DevOps CLI, you can see details about a specific user and update their access level. -The Users view shows key information per user in a table. In this view, you can do the following tasks: +The Users view displays key information for each user in a table. In this view, you can: * See and modify assigned service extensions and access levels. -* Multi-select users and bulk edit their extensions and access. -* Filter by searching for partial user names, access level, or extension names. -* See the last access date for each user. This information can help you choose users to remove access from or lower access to stay within your license limits. For more information, see Manage access with Azure AD. +* Multi-select users and bulk edit their extensions and access levels. +* Filter by searching for partial user names, access levels, or extension names. +* See the last access date for each user. This information can help you identify users to remove or lower their access to stay within your license limits. For more information, see [Permissions and access](../security/permissions-access.md). #### [Browser](#tab/browser) @@ -167,14 +169,13 @@ The Users view shows key information per user in a table. In this view, you can 4. Select a user or group of users. Then, select **Actions ...** at the end of the **Name** column to open the context menu. - In the context menu, select one of the following options: - - * **Change access level** - * **Manage user** - * **Resend invite** - * **Remove direct assignments** - * **Remove from organization** (deletes user) +In the context menu, choose one of the following options: +* **Change access level** +* **Manage user** +* **Resend invite** +* **Remove direct assignments** +* **Remove from organization** (deletes user) ![Select Users, select an item in the context menu](media/manage-users/manage-users-show-context-menu-preview.png) 5. **Save** your changes. @@ -183,7 +184,7 @@ The Users view shows key information per user in a table. In this view, you can [Add a user](add-organization-users.md#add-user) | [List users](../security/export-users-audit-log.md#list-users) | [Remove a user](delete-organization-users.md#remove-user) |[Update a user](#update-user) | [Show users](#show-users) - + ### Update a user @@ -213,7 +214,7 @@ ID Display Name Email 35b1952b-ca8c-45b5-a60c-d6b0086aa584 contoso@contoso.com contoso@contoso.com stakeholder Stakeholder pending ``` - + ### Show users @@ -246,77 +247,83 @@ ID Display Name Email * * * -## Restrict user view to organization projects +## Restrict user visibility to organization and project information -To limit select users access to organizational information, enable the **Limit user visibility and collaboration to specific projects** preview feature and add the users to the **Project-Scoped Users** group. Once added, users in that group can't access projects that they haven't been added to. +To restrict certain users' access to organizational information, enable the **Limit user visibility and collaboration to specific projects** preview feature and add the users to the **Project-Scoped Users** group. Once added, users in that group can't access projects that they aren't explicitly added to. > [!NOTE] -> Users and groups added to the **Project-Scoped Users** group have limited access to project and organization information as well as limited access to select identities through the people picker. For more information, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). +> Users and groups added to the **Project-Scoped Users** group get limited access to project and organization information. They also get restricted access to specific identities through the people picker. For more information, see [Limit user visibility for projects, and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). -Complete the following steps to add users to the new **Project-Scoped Users** group: +To add users to the new **Project-Scoped Users** group, do the following steps: -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). -2. Enable the **Limit user visibility and collaboration to specific projects** preview feature for the organization. To learn how, see [Manage or enable features](../../project/navigation/preview-features.md#account-level). +2. Turn on the **Limit user visibility and collaboration to specific projects** preview feature for the organization. For more information, see [Manage preview features](../../project/navigation/preview-features.md). > [!TIP] - > The **Project-Scoped Users** group only appears under **Permissions** > **Groups** once **Limit user visibility and collaboration to specific projects** preview feature is enabled. + > The **Project-Scoped Users** group only appears under **Permissions** > **Groups** once **Limit user visibility and collaboration to specific projects** preview feature gets enabled. -3. Add users or groups to your project(s) as described in [Add users to a project or team](../security/add-users-team-project.md). Users added to a team are automatically added to the project and team group. +3. Add users or groups to your project by following the steps in [Add users to a project or team](../security/add-users-team-project.md). When you add users to a team, they automatically get added to both the project and the team group. -4. Open **Organizations Settings**, choose ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. +4. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) -5. Open **Security>Permissions** and choose **Project-Scoped Users**. Choose the **Members** tab. Add all users and groups that you want to scope to the project(s) you've added them to. - -[!INCLUDE [project-scoped-users-important-note](../../includes/project-scoped-users-important-note.md)] +5. Select **Security** > **Permissions** > **Project-Scoped Users**. +6. Choose the **Members** tab. +7. Add all users and groups that you want to scope to the project you added them to. For more information, see [Add or remove users or groups, manage security groups](../security/add-remove-manage-user-group-security-group.md). [!INCLUDE [project-scoped-users-warning](../../includes/project-scoped-users-warning.md)] -## FAQ +## FAQs -#### Q: Which email addresses can I add? +### Q: Why does the permissions level show as 'Custom' when I add a user to a project in the Users Hub? -**A:** +**A:** By design, the permissions settings accessible via the Users Hub are intended to provide a quick way to set user permissions after they get added. However, these settings don't override custom permissions that might be assigned through group membership or direct assignments in other areas. + +For example, if a user is designated as a standard contributor in a project but is also granted a specific permission, such as "Allow force push" for a repository within that project, the Users Hub displays their permission level as 'Custom.' So, any changes made in the Users Hub don't revert the permission display back to 'Contributor' or any other standard role. -* If your organization is connected to Azure Active Directory, you can add only email addresses that are internal to the directory. +So, if you see 'Custom' in the Users Hub, it indicates that there are other permissions assigned to the user that don't reflect in the standard role settings. To modify these permissions, go to the specific project settings or group memberships where these custom permissions got assigned. -* Add email addresses of users who have ["personal" Microsoft accounts](https://www.microsoft.com/account) unless you [use your organization's directory](faq-azure-access.yml) to authenticate users and control access through [Azure Active Directory (Azure AD)](/azure/active-directory/fundamentals/active-directory-whatis). +### Q: Which email addresses can I add? + +**A:** +* If your organization is connected to Microsoft Entra ID, you can only add email addresses that are internal to the directory. + * Add email addresses of users who have ["personal" Microsoft accounts](https://www.microsoft.com/account) unless you authenticate users and control access through [Microsoft Entra ID](/azure/active-directory/fundamentals/active-directory-whatis) using your organization's directory. * If your organization is connected to your directory, all users must be directory members. They must sign in to Azure DevOps with work or school accounts managed by your directory. If they aren't members, they need to be [added to the directory](add-external-user.md). -![Add members' sign-in addresses or display names](media/add-team-members/add-user-or-group-to-project.png) +![Screenshot shows adding members' sign-in addresses or display names.](media/add-team-members/add-user-or-group-to-project.png) -After you add members to your project, each member gets an invitation email that links to your organization. They can use this link to sign in to your organization and find your project. First-time members might be asked for extra details when they sign in to personalize their experience. +After you add members to your project, each member receives an invitation email with a link to your organization. They can use this link to sign in and access your project. First-time members might get asked for more details when they sign in to personalize their experience. -#### Q: What if they don't get or lose the invitation email? +### Q: What if users don't get or lose the invitation email? **A:** -- For **Organizations connected to Azure AD**: If you're [inviting users from outside your Azure AD](/azure/active-directory/active-directory-b2b-what-is-azure-ad-b2b), they must use the email. Removing users from the organization removes both their access and their license. However, any artifacts that were assigned to them remain unchanged. You can always invite users back into the organization if they exist in the Azure AD tenant. After they're removed from Azure AD, you can't assign any artifacts (work items, pull requests, and so forth) to them. We preserve the history of artifacts that have already been assigned to the users. +- For **Organizations connected to Microsoft Entra ID**: If you're [inviting users from outside your Microsoft Entra ID](/azure/active-directory/active-directory-b2b-what-is-azure-ad-b2b), they must use their email. Removing users from the organization removes both their access and their license. However, any artifacts assigned to them remain unchanged. You can always invite users back into the organization if they exist in the Microsoft Entra tenant. After they're removed from Microsoft Entra ID, you can't assign any new artifacts (work items, pull requests, and so on) to them. The history of artifacts already assigned to the users is preserved. -- For **Organizations with Microsoft accounts**: You can send a link to the project page, which the email contains, to the new team members. Removing users from the organization removes both their access and their licenses. You can no longer assign any artifacts (work items, pull requests, and so forth) to these users. However, any artifacts that were assigned to them remain unchanged. +- For **Organizations with Microsoft accounts**: You can send a link to the project page, included in the invitation email, to new team members. Removing users from the organization removes both their access and their licenses. You can no longer assign any new artifacts (work items, pull requests, and so on) to these users. However, any artifacts previously assigned to them remain unchanged. ### Q: Why can't I add any more members? **A:** See [Q: Why can't I add any more members to my project?](faq-user-and-permissions-management.yml#q--why-can-t-i-add-any-more-members-to-my-project-). -#### Q: How is *access* different from *permissions*? +### Q: How is *access* different from *permissions*? -**A:** Access levels control user access to select web portal features, based on the user's subscription. Permissions control a user's access to select operations, based on security group membership or specific Access Control Level (ACL) assignments made to a specific user or group. +**A:** Access levels determine a user's access to specific web portal features based on their subscription. Permissions control a user's ability to perform specific operations, which get governed by security group membership or specific Access Control Level (ACL) assignments made to a user or group. ## Next steps > [!div class="nextstepaction"] -> [Set up billing](../billing/set-up-billing-for-your-organization-vs.md) +> [Set up billing](../billing/set-up-billing-for-your-organization-vs.md#set-up-billing) ## Related articles * [Create a project](../projects/create-project.md) * [Invite external users](add-external-user.md) -* [Grant or restrict access to select features and functions](../../organizations/security/restrict-access.md) +* [Manage access to specific features and functions](../../organizations/security/restrict-access.md) * [Delete users from Azure DevOps](delete-organization-users.md) * [Export a list of users and their access levels](../security/export-users-audit-log.md) diff --git a/docs/organizations/accounts/add-privacy-policy-url.md b/docs/organizations/accounts/add-privacy-policy-url.md index af59d08527c..9b602c88168 100644 --- a/docs/organizations/accounts/add-privacy-policy-url.md +++ b/docs/organizations/accounts/add-privacy-policy-url.md @@ -6,7 +6,7 @@ ms.subservice: azure-devops-organizations ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 06/09/2020 +ms.date: 10/22/2024 monikerRange: 'azure-devops' --- @@ -14,14 +14,14 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -A privacy policy is a legal requirement for all websites and apps that collect or use personal data from users. Learn how to add your privacy policy URL to your organization in Azure DevOps for public projects. Your privacy policy URL links to your custom document that describes how you handle both internal and external guest data privacy. The custom privacy policy URL displays only in **Organization settings** on the **Overview** page in Azure DevOps. The Microsoft Privacy Statement continues to display throughout Azure DevOps, whether or not you add a privacy policy URL for your organization. +A privacy policy is legally required for all websites and apps that collect or use personal data from users. This article shows how to add your privacy policy URL to your organization in Azure DevOps for public projects. This URL links to your custom document that describes how you handle both internal and external guest data privacy. The custom privacy policy URL appears only in **Organization settings** on the **Overview** page in Azure DevOps. The Microsoft Privacy Statement continues to display throughout Azure DevOps, regardless of whether you add a privacy policy URL for your organization. > [!NOTE] -> If you're interested in viewing or deleting personal data, see [Azure Data Subject Requests for the General Data Protection Regulation](/microsoft-365/compliance/gdpr-dsr-azure) (GDPR). If you're looking for general info about GDPR, see the [GDPR section of the Service Trust portal](https://servicetrust.microsoft.com/ViewPage/GDPRGetStarted). +> To view or delete personal data, see [Azure Data Subject Requests for the General Data Protection Regulation (GDPR)](/microsoft-365/compliance/gdpr-dsr-azure). For general information about GDPR, visit the [GDPR section of the Service Trust portal](https://servicetrust.microsoft.com/ViewPage/GDPRGetStarted). ## Prerequisites -You must be a member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] ## Add your privacy policy URL in Azure DevOps @@ -30,11 +30,13 @@ You must be a member of the [Project Collection Administrators group](../securit ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) -3. In the **Overview** tab, add your privacy policy URL, and then select **Save**. +3. In the **Overview** tab, add your privacy policy URL. ![Screenshot showing where you can add your privacy policy URL in Organization settings](media/add-privacy-url/privacy-url-in-organization-settings.png) -A link is added to your organization's privacy document. +4. Select **Save**. + + A link to your organization's privacy document gets added. This link provides users with direct access to your custom privacy policy, detailing how you handle both internal and external guest data privacy. The link appears in the **Organization settings** on the **Overview** page, ensuring that users can easily find and review your privacy practices. ## Related articles - [Data Protection Overview](../security/data-protection.md) diff --git a/docs/organizations/accounts/admin-revoke-user-pats.md b/docs/organizations/accounts/admin-revoke-user-pats.md index 445398337d9..1ac4c75cc14 100644 --- a/docs/organizations/accounts/admin-revoke-user-pats.md +++ b/docs/organizations/accounts/admin-revoke-user-pats.md @@ -1,14 +1,12 @@ --- title: Revoke personal access tokens for users titleSuffix: Azure DevOps -ms.custom: seodec18 description: Administrators can revoke personal access tokens (PATs) for users when they're compromised, protecting the organization. ms.subservice: azure-devops-security -ms.assetid: ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 08/12/2022 +ms.date: 10/22/2024 monikerRange: '<= azure-devops' --- @@ -16,46 +14,67 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -If your personal access token (PAT) is compromised, take immediate action. Learn how an administrator can revoke a user's PAT, as a precaution to protect your organization. You can also disable a user, which revokes their PAT. There's latency (up to an hour) before the PAT stops working however, once the disable or delete function completes in Azure Active Directory (Azure AD). +If a Personal Access Token (PAT) is compromised, it's crucial to act swiftly. Administrators can revoke a user's PAT to safeguard the organization. Disabling a user's account also revokes their PAT. -## Prerequisites +[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] + +## Why revoke user PATs? +Revoking user PATs is essential for the following reasons: +- **Compromised token**: Prevent unauthorized access if a token is compromised. +- **User leaves the organization**: Ensure former employees no longer have access. +- **Permission changes**: Invalidate tokens reflecting old permissions. +- **Security breach**: Mitigate unauthorized access during a breach. +- **Regular security practices**: Regularly revoke and reissue tokens as part of a security policy. -Only the **Organization owner** or a member of the **Project Collection Administrators** group can revoke user PATs. If you're not a member of the **Project Collection Administrators** group, [get added as one](../../organizations/security/change-organization-collection-level-permissions.md). To learn how to find your **Organization owner**, see [Look up the organization owner](../security/look-up-organization-owner.md). +## Prerequisites -For users, if you want to create or revoke your own PATs, see [Create or revoke personal access tokens](use-personal-access-tokens-to-authenticate.md). +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] + +> [!TIP] +> To create or revoke your own PATs, see [Create or revoke PATs](use-personal-access-tokens-to-authenticate.md). ## Revoke PATs -1. To revoke the OAuth authorizations, including PATs, for your organization's users, see [Token revocations - Revoke authorizations](/rest/api/azure/devops/tokenadministration/token%20revocations/revoke%20authorizations?view=azure-devops-rest-5.0&preserve-view=true). -2. Use this [PowerShell script](https://github.com/Microsoft/vsts-script-samples/tree/master/PowerShell/TokenAdmin) to automate calling the new REST API by passing a list of user principal names (UPNs). If you don't know the UPN of the user who created the PAT, use this script, however it must be based on a date range. +1. To revoke OAuth authorizations, including PATs, for your organization's users, see [Token revocations - Revoke authorizations](/rest/api/azure/devops/tokenadministration/token%20revocations/revoke%20authorizations?view=azure-devops-rest-5.0&preserve-view=true). +2. To automate calling the REST API, use this [PowerShell script](https://github.com/Microsoft/vsts-script-samples/tree/master/PowerShell/TokenAdmin), which passes a list of user principal names (UPNs). If you don't know the UPN of the user who created the PAT, use this script with a specified date range. > [!NOTE] -> Keep in mind that when you use a date range any JSON web tokens (JWTs) are also revoked. Also be aware that any tooling that relies on these tokens won't work until refreshed with new tokens. +> When you use a date range any JSON web tokens (JWTs) are also revoked. Any tooling that relies on these tokens doesn't work until refreshed with new tokens. + +3. After you successfully revoke the affected PATs, inform your users. They can recreate their tokens as necessary. -3. After you've successfully revoked the affected PATs, let your users know. They can recreate their tokens, as needed. +There might be a delay of up to one hour before the PAT becomes inactive, as this latency period persists until the disable or delete operation is fully processed in Microsoft Entra ID. - + ## FedAuth token expiration A FedAuth token gets issued when you sign in. It's valid for a seven-day sliding window. The expiry automatically extends another seven days whenever you refresh it within the sliding window. If users access the service regularly, only an initial sign-in is needed. After a period of inactivity extending seven days, the token becomes invalid and the user must sign in again. -## Personal access token expiration +## PAT expiration + +Users can choose an expiry date for their PAT, not to exceed one year. We recommend using shorter time periods and generating new PATs upon expiry. Users receive a notification email one week before the token expires. Users can generate a new token, extend the expiry of the existing token, or change the scope of the existing token if needed. + +:::moniker range="azure-devops" + +## Auditing logs + +If your organization is connected to Microsoft Entra ID, you have access to audit logs that track various events, including permissions changes, deleted resources, and log access. These audit logs are valuable for checking revocations or investigating any activity. For more information, see [Access, export, and filter audit logs](../audit/azure-devops-auditing.md). -Users can choose an expiry date for their personal access token, not to exceed one year. We recommend you use shorter time periods, generating new PATs upon expiry. Users receive a notification email one week before token expiry. Users can generate a new token, extend expiry of the existing token, or change the scope of the existing token, if needed. +:::moniker-end ## Frequently asked questions (FAQs) -### Q: What if a user leaves my company? +### Q: What happens to a PAT if a user leaves my company? -A: Once a user's removed from Azure AD, the PATs and FedAuth tokens invalidate within an hour, since the refresh token is valid only for one hour. +A: Once a user gets removed from Microsoft Entra ID, the PATs and FedAuth tokens invalidate within an hour, since the refresh token is valid only for one hour. -### Q: What about JSON web tokens (JWTs)? +### Q: Should I revoke JSON web tokens (JWTs)? -A: Revoke JWTs, issued as part of the OAuth flow, via the [PowerShell script](https://github.com/Microsoft/vsts-script-samples/tree/master/PowerShell/TokenAdmin). However, you must use the date range option in the script. +A: If you have JWTs that you believe should be revoked, we recommend doing so promptly. Revoke JWTs issued as part of the OAuth flow using the [PowerShell script](https://github.com/Microsoft/vsts-script-samples/tree/master/PowerShell/TokenAdmin). Be sure to use the date range option in the script. ## Related articles -- [How Microsoft protects your projects and data in Azure DevOps](../../organizations/security/data-protection.md) -- [Create or revoke your personal access tokens](use-personal-access-tokens-to-authenticate.md) +- [Learn how Microsoft protects your projects and data in Azure DevOps](../../organizations/security/data-protection.md) +- [Create or revoke PATs](use-personal-access-tokens-to-authenticate.md) diff --git a/docs/organizations/accounts/assign-access-levels-by-group-membership.md b/docs/organizations/accounts/assign-access-levels-by-group-membership.md index b9e29883b48..834a44cde19 100644 --- a/docs/organizations/accounts/assign-access-levels-by-group-membership.md +++ b/docs/organizations/accounts/assign-access-levels-by-group-membership.md @@ -1,29 +1,34 @@ --- -title: Add group rule to assign access levels +title: Add group rule, assign access levels titleSuffix: Azure DevOps Services -ms.custom: seodec18, engagement-fy23 -description: Learn how to assign access levels with group rules in Azure Active Directory and Azure DevOps. +ms.custom: engagement-fy23 +description: Learn how to assign access levels with group rules in Microsoft Entra ID and Azure DevOps. ms.subservice: azure-devops-organizations ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 02/24/2023 +ms.date: 02/07/2025 monikerRange: 'azure-devops' --- -# Add a group rule to assign access levels +# Assign access levels with group rules [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Azure DevOps includes group-based licensing for Azure Active Directory (Azure AD) groups and Azure DevOps groups. Learn how to add a group rule to assign an access level to a group. Resources in Azure DevOps are assigned to all members of the group. Group rules are also used to add users to team projects and other specific groups, like Contributors, Readers, and Administrators. +Azure DevOps provides group-based access levels for Microsoft Entra groups and Azure DevOps groups, allowing you to manage permissions efficiently by assigning access levels to entire groups of users. This article explains how to add a group rule to assign an access level to a group of users. Azure DevOps resources are assigned to all members of a group. -When users leave the group, the licenses get freed and returned to your pool. You don't need to automate license management to reflect changes in your organizational structure on a per-user basis. +Assign a group rule to manage both access levels and project memberships. When a user is assigned to multiple rules or Microsoft Entra groups with different access levels, they receive the highest access level among them. For example, if John is assigned to two Microsoft Entra groups with different group rules—one specifying Stakeholder access and the other Basic access—John receives Basic access. + +When a user leaves a Microsoft Entra group, Azure DevOps adjusts their access level according to the group's defined rules. If the group was the user's sole source of access, Azure DevOps automatically removes them from the organization. If the user belongs to other groups, their access level and permissions are reevaluated. [!INCLUDE [note-group-rules](../security/includes/note-group-rules.md)] ## Prerequisites -- To manage licenses and group rules, you must be a member of the **Project Collection Administrators** group. If you're not a member, get added as one. See [Change project collection-level permissions](../security/change-organization-collection-level-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +|**Microsoft Entra** |Member of the Microsoft Entra ID that backs your organization. For more information, see [Access via Microsoft Entra FAQs. Microsoft Entra guests can't search the Microsoft Entra ID in the manner required by Azure DevOps](../accounts/faq-azure-access.yml#no-identities) | ## Add group rule @@ -35,51 +40,48 @@ When users leave the group, the licenses get freed and returned to your pool. Yo 3. Select **Permissions**, and then verify that you're a member of the **Project Collection Administrators** group. - ![Project collection administrators group members](media/assign-access-levels/project-collection-administrators-group-members-new.png) + ![Screenshot showing project collection administrators group members.](media/assign-access-levels/project-collection-administrators-group-members-new.png) 4. Select **Users**, and then select **Group rules**. This view shows you all of your created group rules. Select **Add a group rule**. - ![Select Add a group rule](media/manage-group-licensing/add-group-rule.png) + ![Screenshot showing selected Add a group rule button.](media/manage-group-licensing/add-group-rule.png) **Group rules** appear only if you're a member of the **Project Collection Administrators** group. 5. Complete the dialog box for the group for which you want to create a rule. Include an access level for the group and any optional project access for the group. Select **Add**. - ![Complete add a group rule dialog](media/assign-access-levels/add-group-rule-dialog-new.png) + ![Screenshot showing Add a group rule dialog.](media/assign-access-levels/add-group-rule-dialog-new.png) - A notification displays, showing the status and outcome of the rule. If the assignment couldn't be completed (for example, because your organization didn't have enough purchased licenses), select **View status** to see the details. + A notification displays, showing the status and outcome of the rule. If the assignment couldn't be completed, select **View status** to see the details. - ![Group rule completed](media/assign-access-levels/group-rule-completed-successfully.png) + ![Screenshot showing Group rule completed.](media/assign-access-levels/group-rule-completed-successfully.png) > [!IMPORTANT] -> Group rules only apply to users without direct assignments and to users added to the group going forward. [Remove direct assignments](#remove-direct-assignments) so the group rules apply to those users. +> - Group rules only apply to users without direct assignments and to users added to the group going forward. [Remove direct assignments](#remove-direct-assignments) so the group rules apply to those users. +> - Users don't appear in **All users** until they attempt to sign in for the first time. ## Manage group members 1. Select **Group rules** > :::image type="icon" source="../../media/ellipses-reduced-screen-size.png" border="false"::: > **Manage members**. - ![Highlight a group rule and select manage members](media/migrate-to-group-based-resource-management/highlight-rule-choose-manage-members.png) + ![Screenshot shows highlighted group rule for managing members.](media/migrate-to-group-based-resource-management/highlight-rule-choose-manage-members.png) - > [!NOTE] - > Leave existing automation for managing access levels for users running as-is (for example, PowerShell). The goal is to reflect the same resources that the automation is applying to those users. + Keep the existing automation for managing user access levels running as-is (for example, PowerShell scripts). The goal is to ensure that the same resources applied by the automation are accurately reflected for those users. 2. Add members, and then select **Add**. - ![Add group member](media/migrate-to-group-based-resource-management/add-group-members.png) - -When you assign the same access level to a user, the user consumes only one access level. User assignments can be made both directly and through a group. No other licenses are required. + ![Screenshot of Adding a group member.](media/migrate-to-group-based-resource-management/add-group-members.png) -> [!NOTE] -> You can assign Group rules to support both access levels and project memberships. Users are granted the highest access level when assigned to more than one rule or Azure AD group which specify different levels of access. For example, if John is assigned to two Azure AD groups and two different Group rules that specify Stakeholder access and the other Basic access, then John's access level is Basic. + When you assign the same access level to a user, they consume only one access level, regardless of whether the assignment is made directly or through a group. ## Verify group rule Verify that the resources are applied to each group and individual user. Select **All users**, highlight a user, and then select **Summary**. -:::image type="content" source="media/assign-access-levels/verify-user-summary.png" alt-text="Verify user summary for group rule"::: +:::image type="content" source="media/assign-access-levels/verify-user-summary.png" alt-text="Screenshot showing verification of user summary for group rule."::: ## Remove direct assignments -To manage a user's resources only by the groups that they're in, remove their direct assignments. Resources assigned to a user via individual assignment stay assigned to the user. This assignment stays whether the resources are assigned or taken away from the user's groups. +To manage a user's resources solely through their group memberships, remove any direct assignments. Resources assigned to a user individually remain assigned, regardless of changes to the user's group memberships. 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). @@ -87,25 +89,30 @@ To manage a user's resources only by the groups that they're in, remove their di ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) -3. Select the **Users** tab. +3. Select **Users**. - :::image type="content" source="media/assign-access-levels/select-users-in-organization-settings.png" alt-text="Select the Users tab"::: + :::image type="content" source="media/assign-access-levels/select-users-in-organization-settings.png" alt-text="Screenshot showing selected Users tab."::: 4. Select all users with resources for management only by groups. - ![Select group rules for migration](media/remove-direct-assignments/choose-remove-direct-assignments-preview.png) + ![Screenshot showing Selected group rules for migration.](media/remove-direct-assignments/choose-remove-direct-assignments-preview.png) 5. To confirm that you want to remove the direct assignments, select **Remove**. - ![Remove](media/remove-direct-assignments/confirm-removal-of-direct-assignments.png) + ![Screenshot of confirmation to Remove.](media/remove-direct-assignments/confirm-removal-of-direct-assignments.png) + + Direct assignments get removed from the users. If a user isn't a member of any groups, then the user isn't affected. + +### FAQs + + -Direct assignments are removed from the users. +#### Q: How do Visual Studio Subscriptions work with group rules? -> [!NOTE] -> If a user isn't a member of any groups, then the user isn't affected. +A: Visual Studio Subscribers are always directly assigned via the [Visual Studio Admin Portal](https://manage.visualstudio.com/) and take precedence in Azure DevOps over access levels assigned directly or via group rules. When you view these users from the Users Hub, the License Source always shows as Direct. The only exception are Visual Studio Professional subscribers who are assigned Basic + Test Plans. Since Basic + Test Plans provides more access in Azure DevOps, it takes precedence over a Visual Studio Professional subscription. ## Related articles -* [Install Active Directory and Azure Active Directory users or groups to a built-in security group](../security/add-ad-aad-built-in-security-groups.md) -* [About accessing your organization with Azure AD](access-with-azure-ad.md) -* [Manage Azure Active Directory groups](manage-azure-active-directory-groups.md) +* [Install Active Directory and Microsoft Entra users or groups to a built-in security group](../security/add-ad-aad-built-in-security-groups.md) +* [Learn about accessing your organization with Microsoft Entra ID](access-with-azure-ad.md) +* [Manage Microsoft Entra groups](manage-azure-active-directory-groups.md) diff --git a/docs/organizations/accounts/azure-ad-tenant-policy-restrict-org-creation.md b/docs/organizations/accounts/azure-ad-tenant-policy-restrict-org-creation.md index 20dcfc84168..52b86b0169b 100644 --- a/docs/organizations/accounts/azure-ad-tenant-policy-restrict-org-creation.md +++ b/docs/organizations/accounts/azure-ad-tenant-policy-restrict-org-creation.md @@ -1,82 +1,73 @@ --- -title: Restrict new organization creation, Azure Active Directory tenant policy +title: Restrict new organization creation, Microsoft Entra tenant policy titleSuffix: Azure DevOps Services ms.custom: -description: Learn how Azure DevOps Administrators can prevent users from creating new organizations via the Azure Active Directory tenant policy. +description: Learn how Azure DevOps Administrators can prevent users from creating new organizations via the Microsoft Entra tenant policy. ms.subservice: azure-devops-organizations ms.assetid: ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 05/13/2022 +ms.date: 04/09/2025 monikerRange: 'azure-devops' --- -# Restrict organization creation via Azure AD tenant policy +# Restrict organization creation via Microsoft Entra tenant policy [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Learn how to turn on the Azure Active Directory (Azure AD) tenant policy, which restricts users from creating an organization in Azure DevOps. This policy is turned off, by default. +Learn how to turn on the Microsoft Entra tenant policy, which restricts users from creating an organization in Azure DevOps. This policy is turned off, by default. ## Prerequisites -You must be an Azure DevOps Administrator in Azure AD to manage this policy. It isn't a requirement to be a Project Collection Administrator. - -If you don't see the policy section in Azure DevOps, then you aren't an administrator. To check your role, sign in to the [Azure portal](https://ms.portal.azure.com/#home), and then choose **Azure Active Directory > Roles and administrators**. In case that you aren't an Azure DevOps administrator, talk to your administrator. - -![Check Azure AD roles and administrators](media/azure-ad-tenant-policy/azure-ad-roles-and-administrators.png) +| Category | Requirements | +|--------------|-------------| +|**Permissions**|[Azure DevOps Administrator in Microsoft Entra ID](/azure/active-directory/roles/permissions-reference). To check your role, sign in to the [Azure portal](https://ms.portal.azure.com/#home), and go to **Microsoft Entra ID** > **Roles and administrators**. If you're not an Azure DevOps administrator, you can't see the policies. Contact your administrator, if necessary. The Project Collection Administrator role isn't required. | ## Turn on the policy -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +To turn on the policy that restricts users from creating new organizations, do the following steps: + +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) -3. Select **Azure Active Directory**, and then switch the toggle to turn on the policy, restricting organization creation. - ![Turn on Azure AD policy](media/azure-ad-tenant-policy/azure-ad-turn-policy-on.png) +3. Select **Microsoft Entra ID**, and then switch the toggle to turn on the policy, restricting organization creation. + + :::image type="content" source="media/azure-ad-tenant-policy/restrict-organization-creation-toggle.png" alt-text="Screenshot shows highlighted toggle for Restrict organization creation."::: ## Optional ### Create allowlist > [!WARNING] -> We recommend using groups with your tenant policy allow list(s). If you use a named user, be aware that a reference to the named user's identity will reside in the United States, Europe (EU), and Southeast Asia (Singapore). +> We recommend using groups with your tenant policy allowlist. If you use a named user, a reference to the named user's identity resides in the United States, Europe (EU), and Southeast Asia (Singapore). -With the policy turned on, all users are restricted from creating new organizations. Grant an exception to users with an allowlist. Users on the allowlist can create new organizations, but they can't manage the policy. +When the policy is enabled, only users in the allowlist and users assigned to the Azure DevOps **Administrator** role can create new organizations. To grant exceptions, add users to an allowlist. Users on the allowlist can create new organizations but can't manage the policy. -1. Select **Add AAD user or group**. +Select **Add Microsoft Entra user or group**. -![Option, Create allow list and add Azure AD users or groups](media/azure-ad-tenant-policy/add-azure-ad-user-group.png) +For more information, see [Add organization users and manage access](add-organization-users.md). ### Create error message -When administrators, who aren't on the allowlist, try to create an organization they get an error similar to the following example. - -![Error message example](media/azure-ad-tenant-policy/error-message.png) - -Customize this error message in the policy settings in Azure DevOps. +To customize the error message, do the following steps: -1. Select **Edit display message**. +1. In the policy settings in Azure DevOps, select **Edit display message**. - ![Select Edit display message to customize](media/azure-ad-tenant-policy/edit-display-message.png) -2. Enter your customized message, and then choose **Save**. +2. Enter your customized message, and then select **Save**. - ![Customize error message dialog](media/azure-ad-tenant-policy/display-error-message-dialog.png) + ![Screenshot shows Customize error message dialog.](media/azure-ad-tenant-policy/display-error-message-dialog.png) The error message is customized. -![Customized error message](media/azure-ad-tenant-policy/error-message-example-ui.png) - -> [!NOTE] -> Administrators, who aren't on the allow list, can't connect their organization to the Azure AD tenant where the policy is turned on. -> -> ![Connection failed error](media/azure-ad-tenant-policy/connection-failed-notification.png) +![Screenshot shows customized error message.](media/azure-ad-tenant-policy/error-message-example-ui.png) ## Related articles -* [Connect your organization to Azure Active Directory](connect-organization-to-azure-ad.md) -* [About access with Azure AD](access-with-azure-ad.md) -* [Get a list of organizations backed by Azure AD](get-list-of-organizations-connected-to-azure-active-directory.md) +* [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md) +* [Learn about access with Microsoft Entra ID](access-with-azure-ad.md) +* [Get a list of organizations backed by Microsoft Entra ID](get-list-of-organizations-connected-to-azure-active-directory.md) * [Resolve orphaned organization](resolve-orphaned-organization.md) diff --git a/docs/organizations/accounts/change-application-access-policies.md b/docs/organizations/accounts/change-application-access-policies.md index e00e8ff97b2..bbbef82e750 100644 --- a/docs/organizations/accounts/change-application-access-policies.md +++ b/docs/organizations/accounts/change-application-access-policies.md @@ -1,14 +1,13 @@ --- title: Change application access, security policies for organizations titleSuffix: Azure DevOps Services -ms.custom: seodec18 description: Manage security policies for accessing organization resources, like conditional access, OAuth, SSH, and personal access tokens (PATs). ms.subservice: azure-devops-organizations ms.assetid: 2fdfbfe2-b9b2-4d61-ad3e-45f11953ef3e -ms.topic: conceptual +ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 05/05/2022 +ms.date: 10/22/2024 monikerRange: 'azure-devops' --- @@ -16,79 +15,72 @@ monikerRange: 'azure-devops' [!INCLUDE [alt-creds-deprecation-notice](../../includes/alt-creds-deprecation-notice.md)] -Learn how to manage your organization's security policies that determine how applications can access services and resources in your organization. You can access most of these policies in **Organization Settings**. +This article shows how to manage your organization's security policies that determine how applications can access services and resources in your organization. You can access most of these policies in **Organization settings**. ## Prerequisites -You must be a member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| [!INCLUDE [manage-policies](../../includes/manage-policies.md)] +## Change application connection policies -## Application connection policies +To allow seamless access to your organization without repeatedly prompting for user credentials, applications often use the following authentication methods: -To access your organization without asking for user credentials multiple times, applications often use the following authentication methods: +* [**OAuth**](../../integrate/get-started/authentication/oauth.md): Generate tokens for accessing [REST APIs for Azure DevOps](/rest/api/azure/devops/). All REST APIs accept OAuth tokens, making it the preferred method of integration over personal access tokens (PATs). The [Organizations](/rest/api/azure/devops/account), [Profiles](/rest/api/azure/devops/profile/), and [PAT Management](/rest/api/azure/devops/tokens/pats/) APIs only support OAuth. You can also use OAuth tokens with [Microsoft Entra ID](../../integrate/get-started/authentication/oauth.md) to provide secure and seamless authentication for users within your organization. -* [**OAuth**](../../integrate/get-started/authentication/oauth.md) to generate tokens for accessing [REST APIs for Azure DevOps](/rest/api/azure/devops/). All of the REST APIs accept OAuth tokens and this is the preferred method of integration over personal access tokens (PATs). The [Organizations](/rest/api/azure/devops/account), [Profiles](/rest/api/azure/devops/profile/), and [PAT Management](/rest/api/azure/devops/tokens/pats/) APIs only support OAuth. +* [**SSH**](../../repos/git/use-ssh-keys-to-authenticate.md): Generate encryption keys for use with Linux, macOS, and Windows running [Git for Windows](https://www.git-scm.com/download/win). You can't use [Git credential managers](../../repos/git/set-up-credential-managers.md) or [PATs](use-personal-access-tokens-to-authenticate.md) for HTTPS authentication with SSH. -* [**SSH**](../../repos/git/use-ssh-keys-to-authenticate.md) to generate encryption keys for using Linux, macOS, and Windows running [Git for Windows](https://www.git-scm.com/download/win), but you can't use [Git credential managers](../../repos/git/set-up-credential-managers.md) or [PATs](use-personal-access-tokens-to-authenticate.md) for HTTPS authentication. - -* [**PATs**](use-personal-access-tokens-to-authenticate.md) to generate tokens for: +* [**PATs**](use-personal-access-tokens-to-authenticate.md): Generate tokens for: + * Accessing specific resources or activities, such as builds or work items. + * Clients like Xcode and NuGet that require usernames and passwords as basic credentials and don't support Microsoft account and Microsoft Entra features, such as multifactor authentication. + * Accessing [REST APIs for Azure DevOps](/rest/api/azure/devops/). - * Accessing specific resources or activities, like builds or work items - * Clients, like Xcode and NuGet, that require usernames and passwords as basic credentials and don't support Microsoft account and Azure Active Directory (Azure AD) features, like multi-factor authentication - * Accessing [REST APIs for Azure DevOps](/rest/api/azure/devops/) +By default, your organization allows access for all authentication methods. -By default, your organization allows access for all authentication methods. +You can limit access for OAuth and SSH keys by disabling these application connection policies: +- **Third-party application access via OAuth**: Enable Azure DevOps OAuth apps to access resources in your organization through OAuth. This policy is defaulted to *off* for all new organizations. If you want access to [Azure DevOps OAuth apps](../../integrate/get-started/authentication/azure-devops-oauth.md), enable this policy to ensure these apps can access resources in your organization. This policy doesn't impact [Microsoft Entra ID OAuth app access](../../integrate/get-started/authentication/entra-oauth.md). +- **SSH Authentication**: Enable applications to connect to your organization's Git repos through SSH. -You can limit access for OAuth and SSH keys by disabling access to these application connection policies: -- **Third-party application via OAuth** - Enable third-party applications to access resources in your organization through OAuth. This policy is defaulted to *off* for all new organizations. If you want access to third-party applications, enable this policy to make sure these apps can gain access to resources in your organization. -- **SSH Authentication** - Enable applications to connect to your organization's Git repos through SSH. +When you deny access to an authentication method, no application can access your organization through that method. Any application that previously had access encounter authentication errors and lose access. -When you deny access to an authentication method, no application can access your organization through this method. Any application that previously had access will get authentication errors and no longer have access to your organization. +To remove access for PATs, [revoke them](use-personal-access-tokens-to-authenticate.md). -To remove access for PATs, you must [revoke them](use-personal-access-tokens-to-authenticate.md). +## Change conditional access policies -## Conditional access policies +Microsoft Entra ID allows tenants to define which users can access Microsoft resources through their [Conditional Access Policy (CAP) feature](/azure/active-directory/conditional-access/overview). Tenant admins can set conditions that users must meet to gain access. For example, the user must: -Azure AD allows tenants to define which users are allowed to gain access to Microsoft resources through their [Conditional Access Policy (CAP) feature](/azure/active-directory/conditional-access/overview). Through these settings, the tenant admin can require members must adhere to any of the following conditions, for example, the user must: +- Be a member of a specific security group +- Belong to a certain location and/or network +- Use a specific operating system +- Use an enabled device in a management system -- be a member of a specific security group -- belong to a certain location and/or network -- be using a specific operating system -- be using an enabled device in a management system +Depending on which conditions the user satisfies, you can then require multifactor authentication, set further checks to gain access, or block access altogether. -Depending on which conditions the user satisfies, you can then require multi-factor authentication or further checks to gain access, or block access altogether. +### CAP support on Azure DevOps -If you sign in to the web portal of an Azure AD-backed organization, Azure AD checks that you can move forward by performing validation for any CAPs that were set by tenant administrators. +When you sign in to the web portal of a Microsoft Entra ID-backed organization, Microsoft Entra ID always performs validation for any Conditional Access Policies (CAPs) set by tenant administrators. -Azure DevOps can also perform more CAP validation once you're signed in and navigating through Azure DevOps. +Azure DevOps can also perform more CAP validation once you're signed in and navigating through a Microsoft Entra ID-backed organization: -* If the **Enable Azure AD CAP validation** policy is enabled, web flows are 100% honored for all conditional access policies. If the policy is disabled, Azure DevOps doesn't perform more CAP validation, but Azure AD always checks for CAPs upon sign-in. -* For third-party client flows, like using a PAT with git.exe, we support IP fencing policies only. Users may find that sign-in policy may be enforced for PATs as well. Using PATs to make Azure AD calls requires the user to adhere to any sign-in policies that are set. For example, if a sign-in policy requires that a user sign in every seven days, you must also sign in every seven days if you wish to continue using PATs to make requests to Azure AD. +* If the **“Enable IP Conditional Access policy Validation”** organization policy is enabled, we check IP fencing policies on both web and non-interactive flows, such as non-Microsoft client flows like using a PAT with git operations. +* Sign-in policies might be enforced for PATs as well. Using PATs to make Microsoft Entra ID calls requires adherence to any sign-in policies that are set. For example, if a sign-in policy requires that a user sign in every seven days, you must also sign in every seven days to continue using PATs for Microsoft Entra ID requests. +* If you don't want any CAPs to be applied to Azure DevOps, remove Azure DevOps as a resource for the CAP. We don't enforce CAPs on Azure DevOps on an organization-by-organization basis. -For these third-party client flows, we don't support any MFA policies set after CAP validation. See the following examples: - -- Policy 1 - Block all access from outside of IP range x, y, and z. - * Access Azure DevOps via the web, the user's allowed from IP x, y, and z. If outside of that list, the user's blocked. - * Access Azure DevOps via alt-auth, the user's allowed from IP x, y, and z. If outside of that list, the user's blocked. -- Policy 2 - Require MFA when outside of IP range x, y, and z. - * Access Azure DevOps via the web, the user's allowed from IP x, y, and z. The user is prompted for MFA if outside of that list. - * Access Azure DevOps via alt-auth, the user's allowed from IP x, y, and z. If outside of that list, the user's blocked. +We support MFA policies on web flows only. For non-interactive flows, if they don't satisfy the conditional access policy, the user isn't prompted for MFA and gets blocked instead. #### IP-based conditions -We support IP-fencing conditional access policies for both IPv4 and IPv6 addresses. - -If you find that your IPv6 address is being blocked, we recommend confirming that they configured CAPs to allow your IPv6 address. Also, it may help to include the IPv4-mapped address for your IPv6 address in all CAP conditions. - -Another issue we've found is that users may be accessing the Azure AD sign-in page via a different IP address than the IP address they're using to access Azure DevOps resources. Check your VPN configuration or networking infrastructure to make sure all IP addresses you're using are included within your tenant admin's CAPs. +We support IP-fencing conditional access policies (CAPs) for both IPv4 and IPv6 addresses. If your IPv6 address is being blocked, ensure that the tenant administrator configured CAPs to allow your IPv6 address. Additionally, consider including the IPv4-mapped address for any default IPv6 address in all CAP conditions. +If users access the Microsoft Entra sign-in page via a different IP address than the one used to access Azure DevOps resources (common with VPN tunneling), check your VPN configuration or networking infrastructure. Ensure to include all used IP addresses within your tenant administrator's CAPs. ## Related articles - [Disable Request Access Policy](disable-request-access-policy.md) -- [Restrict users from creating new organizations with Azure AD policy](azure-ad-tenant-policy-restrict-org-creation.md) +- [Restrict users from creating new organizations with Microsoft Entra policy](azure-ad-tenant-policy-restrict-org-creation.md) - [Restrict Team and Project Administrators from inviting new users](../security/restrict-invitations.md) -- [What is Conditional Access in Azure AD?](/azure/active-directory/active-directory-conditional-access) -- [Detailed instructions and requirements for Conditional Access](/azure/active-directory/conditional-access/concept-conditional-access-cloud-apps) +- [Learn about Conditional Access in Microsoft Entra ID](/azure/active-directory/active-directory-conditional-access) +- [Learn about instructions and requirements for Conditional Access](/azure/active-directory/conditional-access/concept-conditional-access-cloud-apps) diff --git a/docs/organizations/accounts/change-azure-ad-connection.md b/docs/organizations/accounts/change-azure-ad-connection.md index 45c583710d0..5a43cd0b479 100644 --- a/docs/organizations/accounts/change-azure-ad-connection.md +++ b/docs/organizations/accounts/change-azure-ad-connection.md @@ -1,40 +1,46 @@ --- -title: Switch to another Azure Active Directory +title: Switch to another Microsoft Entra ID titleSuffix: Azure DevOps Services -ms.custom: seodec18, engagement-fy23 -description: Learn how to change or switch your organization connection to a different Azure Active Directory. +ms.custom: engagement-fy23 +description: Learn how to change or switch your organization connection to a different Microsoft Entra ID. ms.subservice: azure-devops-organizations ms.assetid: 629a48b6-b2ab-4706-8256-d187c8ed5ce7 -ms.topic: conceptual +ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 06/06/2023 +ms.date: 11/08/2024 monikerRange: 'azure-devops' --- -# Change your organization connection to a different Azure AD +# Change your organization connection to a different Microsoft Entra ID [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Learn how to switch your organization connection from one Azure Active Directory (Azure AD) to another. When you change directories, your project resources remain unaffected. +This article explains how to switch your organization's connection from one Microsoft Entra ID to another. When you change directories, your project resources remain unaffected. -For more information about using Azure AD with Azure DevOps, see the [Conceptual overview](access-with-azure-ad.md). +You might want to switch to a different directory to align with organizational changes, such as mergers or acquisitions, or to consolidate multiple directories for better management and security. + +For more information about using Microsoft Entra ID with Azure DevOps, see the [conceptual overview](access-with-azure-ad.md). ## Prerequisites -- You must be a Project Collection Administrator group for the organization. -- You must be a member in the destination Azure AD. For more information, see how to [convert an Azure AD guest into a member](faq-azure-access.yml). -- You must be a member or a guest in the source Azure AD. -- Confirm there are 100 or fewer users in your organization. If your organization has more than 100 users, [contact Support](https://azure.microsoft.com/support/devops/) to resolve any disconnected users. You can map them to their Azure AD identities in the new tenant. -- Request that SSH keys get manually cleared by [Support](https://azure.microsoft.com/support/devops/) before you switch directories. You can find the steps for how to recreate SSH keys [further in this article](#inform-users-of-the-completed-change). For more information, see the [FAQ](faq-azure-access.yml). -- Don't add the users from the destination Azure AD into the Azure DevOps organization. -- If you [add any new custom domains](/azure/active-directory/fundamentals/add-custom-domain) to your Azure AD directory, contact [Support](https://azure.microsoft.com/support/devops/) before you migrate customers over to the new custom domain as this action breaks the mapping for existing identities. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +|**Access levels**|- Member in the destination Microsoft Entra ID. For more information, see how to [convert a Microsoft Entra guest into a member](faq-azure-access.yml).
      - Member or a guest in the source Microsoft Entra ID.| +|**User management** |- 100 or fewer users in your organization. If your organization has more than 100 users, [contact Support](https://azure.microsoft.com/support/devops/) to resolve any disconnected users. You can map them to their Microsoft Entra identities in the new tenant.
      - Don't add the users from the destination Microsoft Entra ID into the Azure DevOps organization.| +|**SSH keys** |Request that SSH keys get manually cleared by [Support](https://azure.microsoft.com/support/devops/) before you switch directories. Find the steps for how to recreate SSH keys [further in this article](#inform-users-microsoft-entra-change). For more information, see the [FAQ](faq-azure-access.yml).| + +### Custom domains + +If you [add any new custom domains](/azure/active-directory/fundamentals/add-custom-domain) to your Microsoft Entra directory, contact [Support](https://azure.microsoft.com/support/devops/) before you migrate customers over to the new custom domain as this action breaks the mapping for existing identities. > [!IMPORTANT] -> Users and groups who inherit membership and permissions from an Azure AD group, will no longer inherit those permissions after the transfer. Azure AD groups that were added to your Azure DevOps organization don't get transferred and will cease to exist in your organization when the Azure AD connection is changed. All permissions and membership relationships made with these Azure AD groups will also cease to exist after the transfer. - +> After the transfer, users and groups who inherit membership and permissions from a Microsoft Entra group no longer inherit those permissions. Microsoft Entra groups added to your Azure DevOps organization won't be transferred and cease to exist in your organization when the Microsoft Entra connection is changed. All permissions and membership relationships associated with these Microsoft Entra groups also cease to exist after the transfer. -## Change the Azure AD connection + + +## Change the Microsoft Entra connection 1. Sign into your organization (```https://dev.azure.com/{yourorganization}```). @@ -42,72 +48,39 @@ For more information about using Azure AD with Azure DevOps, see the [Conceptual :::image type="content" source="../../media/settings/open-admin-settings-vert.png" alt-text="Screenshot showing highlighted Organization settings button."::: -3. Select **Azure Active Directory**, and then **Switch directory**. +3. Select **Microsoft Entra ID**, and then **Switch directory**. :::image type="content" source="media/change-azure-ad-connection.md/select-switch-directory.png" alt-text="Screenshot showing Switch directory button emphasized."::: 4. Select a directory from the dropdown menu, and then select **Connect**. - :::image type="content" source="media/shared/select-directory-connect.png" alt-text="Screenshot showing Azure AD dropdown menu, and then Connect button emphasized."::: + :::image type="content" source="media/shared/select-directory-connect.png" alt-text="Screenshot showing Microsoft Entra dropdown menu, and then Connect button emphasized."::: - If you can't find your directory, contact your Azure AD administrator to request that they add you as a member to the Azure AD. + If you can't find your directory, contact your Microsoft Entra administrator to request to get added as a member to the Microsoft Entra ID. 5. Select **Sign out**. :::image type="content" source="media/shared/connect-success-dialog.png" alt-text="Screenshot showing Sign out button emphasized."::: - Your organization connects to your Azure AD. + Your organization connects to your Microsoft Entra ID. -6. Confirm that the process is complete. Sign out, and then open your browser in a private session and sign in to your organization with your Azure AD or work credentials. +6. Confirm that the process is complete by signing out. Open your browser in a private session and sign in to your organization using your Microsoft Entra ID or work credentials. -7. If some members are disconnected, sign back in to Azure DevOps and map them to their Azure AD identities. Or, you can invite them as guests into the Azure AD. For more information, see the [FAQs](./faq-azure-access.yml#faq-connect). +7. If some of your members are disconnected during this process, an error message like the following example appears on the Microsoft Entra page. Choose **Resolve** to map the disconnected users. For more information, see [FAQs](./faq-azure-access.yml#users-disconnected-after-tenant-switch). :::image type="content" source="media/shared/azure-ad-select-resolve-for-disconnected-users.png" alt-text="Screenshot showing Resolve button emphasized."::: :::image type="content" source="media/shared/resolve-disconnected-users.png" alt-text="Screenshot showing Resolve disconnected users dialog."::: -## Inform users of the completed change - -When you inform your users of the completed change, include the following tasks for each user in the organization to complete. - -### Clear cache for Git Credential Manager - -If you use Visual Studio or the Git command-line too, clear the cache for the [Git Credential Manager](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/blob/master/Docs/Faq.md#q-why-is-gitexe-failing-to-authenticate-after-linkingunlinking-your-visual-studio-team-services-organization-from-azure-active-directory). Delete the *%LocalAppData%\GitCredentialManager\tenant.cache* file on each client machine. - -### Regenerate new PATs - -Complete the steps in [Use personal access tokens](use-personal-access-tokens-to-authenticate.md). - -### Recreate SSH keys - -Complete the following steps to recreate your SSH keys. - -1. In Azure DevOps, open your **profile**, and then select **Security** from the resulting dropdown menu. - - :::image type="content" source="media/shared/select-security-profile-menu.png" alt-text="Screenshot showing Security selection emphasized."::: - -2. Select **SSH public keys**, and then select **Add**. - - :::image type="content" source="media/shared/user-settings-security-ssh.png" alt-text="Screenshot that shows adding an SSH public key."::: - -3. Enter a description and key data, and then select **Save**. - - :::image type="content" source="media/shared/add-ssh-public-key-info.png" alt-text="Screenshot showing info dialog for creating SSH key."::: - -4. Copy your key and put it in a safe place, as you can't view it again. - -### Rename your MSA - -[Rename your Microsoft account](https://support.microsoft.com/help/11545/microsoft-account-rename-your-personal-account) to a different email that doesn't conflict with your Azure AD identity. Doing so ensures that you aren't prompted to choose between accounts. - -### Adjust your VS subscription + -If the UPN used inside your organization changed, adjust your Visual Studio subscription. You can reassign the subscription to your new UPN, or set that UPN as the alternate account inside the subscription. For more information, see [how to add an alternate account to your subscription](/visualstudio/subscriptions/vs-alternate-identity#add-an-alternate-account-to-your-subscription). +[!INCLUDE [inform-users-microsoft-entra-change](includes/inform-users-microsoft-entra-change.md)] ## Related articles +- [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md) - [Rename a project](../projects/rename-project.md) - [Rename an organization](rename-organization.md) -- [Get a list of organizations backed by Azure AD](get-list-of-organizations-connected-to-azure-active-directory.md) +- [Get a list of organizations backed by Microsoft Entra ID](get-list-of-organizations-connected-to-azure-active-directory.md) - [Restrict organization creation with tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) -- [Disconnect your organization from Azure AD](disconnect-organization-from-azure-ad.md) +- [Disconnect your organization from Microsoft Entra ID](disconnect-organization-from-azure-ad.md) diff --git a/docs/organizations/accounts/change-organization-image.md b/docs/organizations/accounts/change-organization-image.md index d28acdfd753..0bba7f1d84b 100644 --- a/docs/organizations/accounts/change-organization-image.md +++ b/docs/organizations/accounts/change-organization-image.md @@ -1,13 +1,12 @@ --- title: Change organization image titleSuffix: Azure DevOps Services -ms.custom: seodec18 description: Change your organization's profile icon image. ms.subservice: azure-devops-organizations ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 07/05/2023 +ms.date: 10/22/2024 monikerRange: 'azure-devops' --- @@ -15,12 +14,14 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -When you [create an organization](create-organization.md) in Azure DevOps, the system automatically generates a profile image. You can replace the default image with one that better represents your organization. +When you [create an organization](create-organization.md) in Azure DevOps, the system automatically generates a default profile image. You can replace the default image with one that better represents your organization. > [!NOTE] -> The max image size allowed is 2560 x 1024 px, and then we resize to 200 x 200. +> The maximum image size allowed is 2560 x 1024 pixels. The image gets resized to 200 x 200 pixels for display. -[!INCLUDE [pca-prerequisite](includes/pca-prerequisite.md)] +## Prerequisites + +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] ## Change your organization image @@ -36,11 +37,11 @@ When you [create an organization](create-organization.md) in Azure DevOps, the s 4. Upload your image, and then select **Save**. -Your organization's image is updated. +Your organization's image gets updated. This change is reflected across all areas of Azure DevOps where the organization image is displayed, including the organization settings, project dashboards, and user profiles. ## Related articles - [Change your organization's owner](change-organization-ownership.md) - [Change your organization's location](change-organization-location.md) -- [Change your organization's Azure AD connection](change-azure-ad-connection.md) +- [Change your organization's Microsoft Entra connection](change-azure-ad-connection.md) - [Rename your organization](rename-organization.md) diff --git a/docs/organizations/accounts/change-organization-location.md b/docs/organizations/accounts/change-organization-location.md index 44728dbb5fb..6878f3fcafc 100644 --- a/docs/organizations/accounts/change-organization-location.md +++ b/docs/organizations/accounts/change-organization-location.md @@ -1,42 +1,43 @@ --- -title: Find or change location or region of organization +title: Find or change the geography of your organization titleSuffix: Azure DevOps Services -ms.custom: seodec18, references_regions +ms.custom: references_regions description: Find your organization's default location or update your organization's region in Azure DevOps. ms.subservice: azure-devops-organizations ms.assetid: cc4fd0d6-b24f-48ec-8b90-8e5f18e18d65 ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 06/21/2023 +ms.date: 04/03/2025 monikerRange: 'azure-devops' --- -# Find or change your organization region +# Find or change your organization geography [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -When you [create an organization](create-organization.md) in Azure DevOps, you can choose the region your organization is hosted in. You may choose your organization's region based on locality and network latency, or because you have sovereignty requirements for data centers. Your organization's default location is based on the closest [Microsoft Azure region](https://azure.microsoft.com/regions) where Azure DevOps is available. +When you [create an organization](create-organization.md) in Azure DevOps, you can choose the geography where your organization gets hosted. You might select your organization's geography based on locality, network latency, or sovereignty requirements for data centers. The default location for your organization is based on the nearest [Microsoft Azure geography](https://azure.microsoft.com/regions) where services are available. -## Find your organization region +## Find your organization geography -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: **Organization settings**. :::image type="content" source="../../media/settings/open-admin-settings-vert.png" alt-text="Screenshot showing a gear icon and Organization settings emphasized."::: -3. Select **Overview**. The region is listed lower on the page. +1. Select **Overview**. The geography information is listed further down the page. - :::image type="content" source="media/change-organization-location/organization-settings-region.png" alt-text="Screenshot showing the region in Organization settings."::: + :::image type="content" source="media/change-organization-location/organization-settings-geography.png" alt-text="Screenshot showing the region in Organization settings."::: -[!INCLUDE [pca-prerequisite](includes/pca-prerequisite.md)] +## Prerequisites -## Change organization region +[!INCLUDE [prerequisites-organization-owner-only](../../includes/prerequisites-organization-owner-only.md)] + +## Change organization geography > [!IMPORTANT] -> A region change is only possible in the following geographies across the world: -> +> You can only change your organization's geography to one of the following locations: > - Australia > - Brazil > - Canada @@ -45,11 +46,16 @@ When you [create an organization](create-organization.md) in Azure DevOps, you c > - India > - United Kingdom > - United States -> -> We default your organization to your closest geography. Making a change to another data center within your geography isn't possible, for example, changing from EastUS to CentralUS. -To change your organization region, use [Azure DevOps Virtual Support Agent](https://go.microsoft.com/fwlink/?linkid=2163146). +By default, your organization is associated with the closest geography based on your location. However, changing to a different data center (region) within the same geography isn't possible. + +To change your organization geography, use [Azure DevOps Virtual Support Agent](https://go.microsoft.com/fwlink/?linkid=2160944). + +We can't provide a specific time frame for your organization's relocation due to potential delays from various factors and the automated nature of the migration process. The process might get rescheduled to take place over the weekend to ensure all necessary changes are successfully completed. ## Related articles -- [Worldwide data regions for Azure DevOps](../security/data-location.md). +- [Explore worldwide data regions for Azure DevOps](../security/data-location.md) +- [View data locations for Azure DevOps](../security/data-location.md) +- [Learn about data protection](../security/data-protection.md) +- [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md) diff --git a/docs/organizations/accounts/change-organization-ownership.md b/docs/organizations/accounts/change-organization-ownership.md index fe198540b0a..1512a95027f 100644 --- a/docs/organizations/accounts/change-organization-ownership.md +++ b/docs/organizations/accounts/change-organization-ownership.md @@ -1,14 +1,14 @@ --- title: Change the owner of an organization titleSuffix: Azure DevOps Services -ms.custom: seodec18, contperf-fy21q4, linked-from-support +ms.custom: linked-from-support description: Learn how to assign a different user as the owner for your organization and which permissions are required. ms.subservice: azure-devops-organizations ms.assetid: ec935536-6a5e-4b62-adf2-4207a70440bd ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 06/20/2023 +ms.date: 10/22/2024 monikerRange: 'azure-devops' --- @@ -21,24 +21,27 @@ As roles and responsibilities change, you can change the owner for your organiza > [!NOTE] > When you change the organization owner, the old owner is not removed from the Project Collection Administrators group. -[!INCLUDE [pca-prerequisite](includes/pca-prerequisite.md)] -- The new owner must do the following tasks: +## Prerequisites - - Sign in to your organization, create a profile, and agree to the Terms of Service. - - Access the organization at least once after creating your initial profile. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +|**New owner tasks**|- Sign in to your organization, create a profile, and agree to the Terms of Service.
      - Access the organization at least once after creating your initial profile.| > [!TIP] -> For organizations connected to Azure Active Directory (Azure AD), if your organization owner and any other Project Collection Administrators are no longer active, you can [transfer ownership to another user](resolve-orphaned-organization.md). +> For organizations connected to Microsoft Entra ID, if your organization owner and all other Project Collection Administrators are no longer active, you can [transfer ownership to another user](resolve-orphaned-organization.md). ## Change organization owner +To change the organization owner, do the following steps: + 1. Sign in to your organization (`https://dev.azure.com/{yourorganization}`). 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. :::image type="content" source="../../media/settings/open-admin-settings-vert.png" alt-text="Screenshot showing Organization settings button emphasized."::: -3. Select **Overview**, and then **Change owner**. +3. Select **Overview** > **Change owner**. :::image type="content" source="media/change-organization-ownership/change-organization-owner.png" alt-text="Screenshot showing Overview, and then Change owner buttons emphasized."::: @@ -46,11 +49,11 @@ As roles and responsibilities change, you can change the owner for your organiza :::image type="content" source="media/change-organization-ownership/save-new-organization-owner.png" alt-text="Screenshot showing Change button emphasized."::: -Your organization has a new owner. +Your organization has a new owner. The new owner has full administrative control over the organization, including the ability to manage users, projects, and settings. They can also configure security policies, access levels, and billing information. Ensure the new owner is aware of their responsibilities and has the necessary permissions to effectively manage the organization. ## Related articles - [Resolve inactive organization owner](resolve-orphaned-organization.md) - [Change organization location](change-organization-location.md) - [Rename your organization](rename-organization.md) -- [Connect your organization to Azure AD](connect-organization-to-azure-ad.md) +- [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md) diff --git a/docs/organizations/accounts/change-time-zone.md b/docs/organizations/accounts/change-time-zone.md index 45aca7e3e88..a42789efee1 100644 --- a/docs/organizations/accounts/change-time-zone.md +++ b/docs/organizations/accounts/change-time-zone.md @@ -2,13 +2,13 @@ title: Change time zone titleSuffix: Azure DevOps Services ms.custom: -description: Learn how to change the time zone for your organization or for user profile. +description: Learn how to change the time zone for your organization or user profile. ms.subservice: azure-devops-organizations ms.assetid: ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 06/23/2023 +ms.date: 10/22/2024 monikerRange: 'azure-devops' --- @@ -16,19 +16,23 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -You can change the time zone for your organization or user profile in Azure DevOps. +You can change the time zone for your organization or user profile in Azure DevOps to ensure that timestamps on work items, builds, and other activities reflect your local time. This setting helps maintain consistency and clarity across your team's activities, especially if team members are distributed across different time zones. Adjusting the time zone can be done through the organization settings or your user profile settings. -The following time zones are available in Azure DevOps: +Azure DevOps offers two time zone settings: -* **Azure DevOps organization time zone** - the main time zone setting. This setting is where all your iteration dates, builds, and release schedules depend upon, and so on. Changing your organization time zone affects its dependencies. -* **Azure DevOps user profile time zone** - only used for the user interface (UI). The user profile time zone setting is used for a more personalized experience. It also displays timestamps for when users browse Azure DevOps using the time zone configured for that specific user. +* **Azure DevOps organization time zone**: This is the primary time zone setting. It affects all iteration dates, builds, release schedules, and other dependencies. Changing the organization time zone will impact all related schedules and timelines. +* **Azure DevOps user profile time zone**: This setting is used only for the user interface (UI) to provide a personalized experience. It displays timestamps based on the time zone configured for each specific user. -If your organization time zone is EST, and user profile is PST, all date and time fields display in PST time zone. For more information, see [Time zone settings and usage](../settings/timezone-settings-usage.md). +For example, if your organization time zone is set to EST and your user profile time zone is set to PST, all date and time fields will display in PST for you. For more information, see [Time zone settings and usage](../settings/timezone-settings-usage.md). -[!INCLUDE [pca-prerequisite](includes/pca-prerequisite.md)] +## Prerequisites + +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] ## Change your organization time zone +To change your organization time zone, do the following steps: + 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). 2. Select :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: **Organization settings**. @@ -45,6 +49,10 @@ Your organization's time zone is updated. ## Change user profile time zone +To change your user profile time zone, do the following steps: + +#### [Preview page](#tab/preview-page) + 1. From your home page, select :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **User settings** > **Time and Locale**. :::image type="content" source="media/change-time-zone/user-settings-time-locale.png" alt-text="Screenshot showing User settings icon and Time and Locale emphasized."::: @@ -55,17 +63,18 @@ Your organization's time zone is updated. #### [Current page](#tab/current-page) -1. From your home page, open **User profile**, and then select **My profile**. +1. From your home page, open **User profile** > **My profile**. :::image type="content" source="../settings/media/open-profile-user-settings.png" alt-text="Screenshot showing user profile settings screen."::: 2. Select **Edit profile**. :::image type="content" source="media/change-time-zone/select-edit-profile.png" alt-text="Screenshot showing Edit profile button emphasized."::: +--- Your user profile time zone is updated. ## Related articles -- [Time zone settings and usage](../settings/timezone-settings-usage.md) +- [Learn about time zone settings and usage](../settings/timezone-settings-usage.md) - [Set user preferences](../settings/set-your-preferences.md) diff --git a/docs/organizations/accounts/connect-organization-to-azure-ad.md b/docs/organizations/accounts/connect-organization-to-azure-ad.md index ae0496b1ed7..84f34652160 100644 --- a/docs/organizations/accounts/connect-organization-to-azure-ad.md +++ b/docs/organizations/accounts/connect-organization-to-azure-ad.md @@ -1,124 +1,78 @@ --- -title: Connect organization to Azure Active Directory +title: Connect organization to Microsoft Entra ID titleSuffix: Azure DevOps Services -ms.custom: seodec18 -description: Learn how to connect your organization to your Azure Active Directory +description: Learn how to connect your organization to your Microsoft Entra ID ms.subservice: azure-devops-organizations ms.assetid: 629a48b6-b2ab-4706-8256-d187c8ed5ce7 ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 05/11/2022 +ms.date: 10/22/2024 monikerRange: 'azure-devops' --- -# Connect your organization to Azure Active Directory +# Connect your organization to Microsoft Entra ID [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Learn how to connect your Azure DevOps organization to [Azure Active Directory (Azure AD)](/azure/active-directory/fundamentals/active-directory-whatis). You can sign in with the same username and password that you use with Microsoft services. Add members to your Azure DevOps organization who are already a part of your work organization. You can also enforce policies for accessing your team's critical resources and key assets. +This article shows how to connect your Azure DevOps organization to [Microsoft Entra ID](/azure/active-directory/fundamentals/active-directory-whatis). You can sign in with the same credentials that you use with Microsoft services. Add members to your Azure DevOps organization who are already a part of your work organization. You can also enforce policies for accessing your team's critical resources and key assets. -For more information about using Azure AD with Azure DevOps, see the [conceptual overview](access-with-azure-ad.md). +For more information about using Microsoft Entra ID with Azure DevOps, see the [conceptual overview](access-with-azure-ad.md). ## Prerequisites -- Have 100 or fewer users in your organization. If your organization has more than 100 users, [contact Support](https://azure.microsoft.com/support/devops/) for help with connecting to Azure AD. -- You must be a [member of the **Project Collection Administrators** group](../security/look-up-project-collection-administrators.md) or the [**organization Owner**](../security/look-up-organization-owner.md) to make the connection. -- Ensure that you exist in Azure AD as a *member*. For more information, see [how you can convert an Azure AD *guest* into a *member*](./faq-azure-access.yml#how-can-i-convert-an-azure-ad-guest-into-a-member). -- Inform users of the upcoming change. - There's no downtime during this change, but users are affected. Let them know before you begin that there's a short series of steps they need to complete. As your company transitions from Microsoft account (MSA) to Azure AD identities, your users' benefits continue with their new identity, as long as their emails match. -- Delete unwanted users from your organization. For example, you can remove a user who left the company and is no longer an employee. -- Prepare your mapping list for inviting users to Azure AD. - - 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). - 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - - ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) - - 3. Select **Users**. - - ![Open organization settings, users](../../media/settings/open-organization-settings-users-vert.png) - - 4. Compare your Azure DevOps email list with your Azure AD email list. Create an Azure AD email address entry for every user who's in the Azure DevOps organization and not in the Azure AD. Afterward, you can [invite users as guests](add-external-user.md) who don't have Azure AD email addresses. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +|**Access levels**|- Member in the destination Microsoft Entra ID. For more information, see how to [convert a Microsoft Entra guest into a member](faq-azure-access.yml).
      - Member or a guest in the source Microsoft Entra ID.| +|**User management** |- 100 or fewer users in your organization. If your organization has more than 100 users, [contact Support](https://azure.microsoft.com/support/devops/) to resolve any disconnected users. You can map them to their Microsoft Entra identities in the new tenant.
      - Don't add the users from the destination Microsoft Entra ID into the Azure DevOps organization.
      - Delete unwanted users from your organization. For example, you can remove a user who left the company and is no longer an employee.
      - Inform users of the upcoming change. There's no downtime during this change, but users are affected. Let them know before you begin that there's a short [series of steps](#inform-users-microsoft-entra-change) they need to complete. As your company transitions from Microsoft account (MSA) to Microsoft Entra identities, your users' benefits continue with their new identity, as long as their emails match.
      - Compare your Azure DevOps email list with your Microsoft Entra ID email list. Create a Microsoft Entra ID email address entry for every user who's in the Azure DevOps organization and not in the Microsoft Entra ID. Afterward, you can [invite users as guests](add-external-user.md) who don't have Microsoft Entra ID email addresses.| +|**SSH keys** |Request that SSH keys get manually cleared by [Support](https://azure.microsoft.com/support/devops/) before you switch directories. Find the steps for how to recreate SSH keys [further in this article](#inform-users-microsoft-entra-change). For more information, see the [FAQ](faq-azure-access.yml).| > [!NOTE] -> Ensure you're using Azure AD Public. Connecting Azure DevOps Services organizations to Azure AD Government and accessing Azure DevOps Services with user accounts from Azure AD Government isn't supported. +> Ensure you're using Microsoft Entra Public. Connecting Azure DevOps Services organizations to Microsoft Entra Government and accessing Azure DevOps Services with user accounts from Microsoft Entra Government isn't supported. -## Connect your organization to Azure AD + + +## Connect your organization to Microsoft Entra ID + +To connect your organization to Microsoft Entra ID, do the following steps: 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) -3. Select **Azure Active Directory**, and then select **Connect directory**. +3. Select **Microsoft Entra ID**, and then select **Connect directory**. - ![Select Connect directory to connect your organization to Azure AD](media/shared/select-azure-ad-connect-directory.png) + ![Select Connect directory to connect your organization to Microsoft Entra ID](media/shared/select-azure-ad-connect-directory.png) 4. Select a directory from the dropdown menu, and then select **Connect**. - ![Select your Azure AD, and then Connect](media/shared/select-directory-connect.png) + ![Select your Microsoft Entra ID, and then Connect](media/shared/select-directory-connect.png) - If you can't find your directory, contact your Azure AD administrator and request that they add you as a member to the Azure AD. + If you can't find your directory, contact your Microsoft Entra administrator and request that they add you as a member to the Microsoft Entra ID. 5. Select **Sign out**. ![Connect success dialog - select Sign out](media/shared/connect-success-dialog.png) - Your organization is now connected to your Azure AD. + Your organization is connected to your Microsoft Entra ID. -6. Confirm that the process is complete. Sign out, and then open your browser in a private session and sign in to your organization with your Azure AD or work credentials. +6. Confirm that the process is complete. Sign out, and then open your browser in a private session and sign in to your organization with your Microsoft Entra ID or work credentials. -7. Sign back in to Azure DevOps and map any disconnected members to their Azure AD identities. Or, you can invite them as guests into the Azure AD. For more information, see the [FAQs](./faq-azure-access.yml#faq-connect). +7. Sign back in to Azure DevOps and map any disconnected members to their Microsoft Entra identities. Or, you can invite them as guests into the Microsoft Entra ID. For more information, see the [FAQs](./faq-azure-access.yml#faq-connect). ![Select Resolve to invite unmapped users](media/shared/azure-ad-select-resolve-for-disconnected-users.png) ![Mapping disconnected users](media/shared/resolve-disconnected-users.png) -## Inform users of the completed change - -When you inform your users of the completed change, include the following tasks for each user in the organization to complete: - -- Clear the cache for the [Git Credential Manager](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/blob/master/Docs/Faq.md#q-why-is-gitexe-failing-to-authenticate-after-linkingunlinking-your-visual-studio-team-services-organization-from-azure-active-directory) if you use Visual Studio or the Git command-line tool. Delete the *%LocalAppData%\GitCredentialManager\tenant.cache* file on each client machine. -- [Regenerate new personal access tokens](use-personal-access-tokens-to-authenticate.md). Complete the following steps: - - a. In Azure DevOps, open your **User profile**, and then select **Security** from the resulting dropdown menu. - - ![Select from your profile dropdown menu, Security](media/shared/select-security-profile-menu.png) - - b. Select **Personal access tokens**, and then select **New Token**. - - ![Select New Token](media/shared/select-personal-access-tokens-new-token.png) - - c. Complete the form, and then select **Create**. - - ![Create new token](media/shared/create-new-personal-access-token.png) - - d. When the token is created, copy it, as it can't be viewed again. - -- Request that SSH keys be manually cleared by [Support](https://azure.microsoft.com/support/devops/), and then recreate SSH keys. Complete the following steps. - - a. In Azure DevOps, open your **User profile**, and then select **Security** from the resulting dropdown menu. - - ![Select from your profile dropdown menu, Security](media/shared/select-security-profile-menu.png) - - b. Select **SSH public keys**, and then select **Add**. - - ![Screenshot that shows adding an SSH public key.](media/shared/user-settings-security-ssh.png) - - c. Enter a description and key data, and then select **Save**. - - ![Add info to create SSH key](media/shared/add-ssh-public-key-info.png) - - d. When the token's created, copy it, as it can't be viewed again. - -- [Rename your Microsoft account](https://support.microsoft.com/help/11545/microsoft-account-rename-your-personal-account) to a different email that doesn't conflict with your Azure AD identity. Doing so ensures that you won't be prompted to choose between accounts. -- Adjust your Visual Studio subscription if the UPN used inside your Azure DevOps organization has changed. You can have it reassigned to your new UPN, or set that UPN as the alternate account inside the subscription. For more information, see [how to add an alternate account to your subscription](/visualstudio/subscriptions/vs-alternate-identity#add-an-alternate-account-to-your-subscription). + +[!INCLUDE [inform-users-microsoft-entra-change](includes/inform-users-microsoft-entra-change.md)] ## Related articles -* [Get a list of organizations backed by Azure AD](get-list-of-organizations-connected-to-azure-active-directory.md) +* [Get a list of organizations backed by Microsoft Entra ID](get-list-of-organizations-connected-to-azure-active-directory.md) * [Restrict organization creation with tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) -* [Disconnect from Azure AD](disconnect-organization-from-azure-ad.md) -* [Change Azure AD connection](change-azure-ad-connection.md) -* [Frequently asked questions (FAQs) about connecting, disconnecting, or changing your Azure AD](./faq-azure-access.yml#connect-to-disconnect-from-or-change-azure-ad-connection) +* [Disconnect from Microsoft Entra ID](disconnect-organization-from-azure-ad.md) +* [Change Microsoft Entra connection](change-azure-ad-connection.md) +* [View frequently asked questions (FAQs) about connecting, disconnecting, or changing your Microsoft Entra ID](./faq-azure-access.yml) diff --git a/docs/organizations/accounts/create-organization.md b/docs/organizations/accounts/create-organization.md index eb0e903c127..bc42bcd6743 100644 --- a/docs/organizations/accounts/create-organization.md +++ b/docs/organizations/accounts/create-organization.md @@ -1,14 +1,13 @@ --- title: Create an organization titleSuffix: Azure DevOps -ms.custom: seodec18, contperf-fy20q4, contperf-fy22q3 description: Learn how to create an organization or project collection with a personal Microsoft account, GitHub account, or work or school account. ms.subservice: azure-devops-organizations ms.assetid: e2eacd25-e6be-4294-b1da-5529195f30d0 -ms.topic: quickstart +ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 02/14/2022 +ms.date: 10/23/2024 monikerRange: '<= azure-devops' --- @@ -16,54 +15,46 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="= azure-devops" - -Use an organization to connect groups of related projects, and help to scale up your enterprise. You can use a personal Microsoft account, GitHub account, or a work or school account. Use your work or school account to *automatically connect* your organization to your Azure Active Directory (Azure AD). - -::: moniker-end - -::: moniker range="= azure-devops" +Use an organization to connect groups of related projects and help scale up your enterprise. You can use a personal Microsoft account, GitHub account, or a work or school account. Using your work or school account *automatically connects* your organization to your Microsoft Entra ID. > [!NOTE] -> All organizations must be manually created via the web portal. We don't support automated creation of organizations. We do support automated organization configuration, project creation, and resource provisioning via [REST API](/rest/api/azure/devops). +> All organizations must be manually created via the web portal. Automated creation of organizations is not supported. However, we do support automated organization configuration, project creation, and resource provisioning via the [REST API](/rest/api/azure/devops). ## Prerequisites -* Understand how to [plan your organizational structure](../../user-guide/plan-your-azure-devops-org-structure.md). -* Determine whether you want to use only Microsoft accounts or authenticate users with Azure AD. For more information, see [Choosing your organization administrator account type](../../user-guide/plan-your-azure-devops-org-structure.md#choose-your-organization-administrator-account-type). - -::: moniker-end +| Category | Requirements | +|--------------|-------------| +|**Authentication**| Determine whether you want to use only Microsoft accounts or authenticate users with Microsoft Entra ID. For more information, see [Choosing your organization administrator account type](../../user-guide/plan-your-azure-devops-org-structure.md#choose-your-organization-administrator-account-type).| +|**Planning**| Understand how to [plan your organizational structure](../../user-guide/plan-your-azure-devops-org-structure.md).| -::: moniker range="= azure-devops" +## Create an organization -[!INCLUDE [organization-name-limitation](../../includes/organization-name-limitation.md)] +1. Sign in to [Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137). -[!INCLUDE [create-organization](../../includes/create-organization.md)] +1. Select **New organization**. -::: moniker-end + :::image type="content" source="../../media/select-new-organization.png" alt-text="Screenshot shows New organization button for selection."::: -::: moniker range="< azure-devops" +1. Enter the name for your organization, select its hosting geography, and then select **Continue**. -## Create a project collection + [!INCLUDE [organization-name-limitation](../../includes/organization-name-limitation.md)] -A project collection is a container of projects. By grouping projects together, you can manage projects more efficiently and assign the same resources to those projects. + :::image type="content" source="../../media/name-your-organization.png" alt-text="Screenshot shows Creating an organization in Azure DevOps, highlighted Continue button."::: -For more information about how to create a project collection, see [Create a project collection](/azure/devops/server/admin/manage-project-collections?view=azure-devops&preserve-view=true#create-a-project-collection). + :::image type="content" source="../../media/taking-you-to-your-azure-devops-organization.png" alt-text="Screenshot shows temporary screen taking you to your organization notification."::: -::: moniker-end + Congratulations, you're an organization owner! -::: moniker range="azure-devops" +Sign in to your organization at any time, `https://dev.azure.com/{yourorganization}`. With your organization, the following aspects are included in the free tier: [!INCLUDE [free-tier](../../includes/free-tier.md)] -::: moniker-end - ## Next steps > [!div class="nextstepaction"] @@ -72,8 +63,8 @@ With your organization, the following aspects are included in the free tier: ## Related articles * [Get started with Azure Repos and Visual Studio](../../repos/git/gitquickstart.md) -* [Rename your organization](rename-organization.md) +* [Rename an organization](rename-organization.md) * [Change organization time-zone](change-organization-location.md) * [Change organization owner](change-organization-ownership.md) -* [Delete your organization](delete-your-organization.md) +* [Delete an organization](delete-your-organization.md) * [Resolve orphaned organization](resolve-orphaned-organization.md) diff --git a/docs/organizations/accounts/delete-organization-users.md b/docs/organizations/accounts/delete-organization-users.md index 3669f61f064..6699a4f149d 100644 --- a/docs/organizations/accounts/delete-organization-users.md +++ b/docs/organizations/accounts/delete-organization-users.md @@ -1,37 +1,38 @@ --- title: Delete, remove users from team, project, organization titleSuffix: Azure DevOps -ms.custom: seodec18 description: Steps for how to delete or remove organization users from Azure DevOps and remove users from a team or project. ms.subservice: azure-devops-organizations ms.topic: conceptual ms.assetid: d3a31878-a869-45a9-9bca-f46cc2682596 ms.author: chcomley author: chcomley -ms.date: 11/08/2022 -monikerRange: '>= azure-devops-2019' +ms.date: 10/23/2024 +monikerRange: "<=azure-devops" --- # Remove users from Azure DevOps [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -If users no longer require access to a team, project, or organization, you can remove their access. +If users no longer require access to a team, project, or organization, you can remove their access. Removing access ensures that only authorized users can view and interact with your organization's data and resources. This article provides step-by-step instructions on how to remove user access from a team, project, or organization in Azure DevOps. By following these guidelines, you can ensure that your organization's security and resource management practices remain robust and up-to-date. > [!IMPORTANT] -> - [Removing a user from a team or project](#remove-users-from-a-team-or-project) doesn’t remove the user from the organization. -> - Work items that are assigned to the user aren't affected by removing user access. -> - Azure Active Directory (Azure AD)-backed organizations: -> - After you remove a user from Azure AD, you can't assign artifacts to that user anymore. Examples are work items and pull requests. However, we preserve the history of artifacts that were already assigned to the user. -> - Removing a user from the organization doesn't remove their memberships to any Azure AD groups. If the user is a member of an access-granting Azure AD group, then the user still has access to Azure DevOps, even after you remove them from the organization. If you'd like to completely remove the user from the organization, make sure they aren't in any of your access-granting Azure AD groups. For more information, see about managing access with [Azure AD groups](manage-azure-active-directory-groups.md) -> - Managed service account (MSA)-backed organizations: After you remove a user from your MSA-backed organization, the user remains within the tenant and can be re-added at any time. +> - Removing a user from a team or project doesn’t remove them from the organization. +> - Work items assigned to the user aren't affected by removing their access. +> - For Microsoft Entra ID-backed organizations: +> - Removing a user from Microsoft Entra ID prevents assigning new artifacts (for example, work items or pull requests) to that user. However, the history of already assigned artifacts is preserved. +> - Removing a user from the organization doesn't remove their memberships in any Microsoft Entra groups. If the user is a member of an access-granting Microsoft Entra group, they still have access to Azure DevOps. To completely remove the user, ensure they aren't in any access-granting Microsoft Entra groups. For more information, see [Manage access with Microsoft Entra groups](manage-azure-active-directory-groups.md). +> - For Managed Service Account (MSA)-backed organizations: Removing a user from your MSA-backed organization doesn't remove them from the tenant, and they can be re-added at any time. ## Prerequisites -- To remove users, you must be a member of the **Project Collection Administrators** group. See [Change project collection-level permissions](../security/change-organization-collection-level-permissions.md). +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] ## Remove users from your organization +[!INCLUDE [image-differences](../../includes/image-differences.md)] + #### [Browser](#tab/browser) ::: moniker range=">= azure-devops-2020" @@ -46,52 +47,18 @@ If users no longer require access to a team, project, or organization, you can r ![Screenshot showing highlighted Users button within Organization settings.](../../media/open-organization-settings-users-preview.png) -4. Select **...** for the user to be removed. Select **Remove from organization**. - +4. Select **...** next to the user you want to remove. Then, choose **Remove from organization**. If this option isn't available, see the [prerequisites](#prerequisites). + ![Screenshot showing removal of a user from your organization.](media/delete-user/remove-user-from-organization-preview.png) -5. Choose **Remove** in the confirmation dialog. - - [Why don't users appear or disappear promptly after I add or delete them in the Users Services page?](faq-user-and-permissions-management.yml#users-delay) +5. Select **Remove** in the confirmation dialog. -6. If you deleted paid users who had Basic or higher features, also [reduce the users in Organization settings](../billing/buy-basic-access-add-users.md#reduce-charges-for-users-with-no-access). Then you're not charged in your next Azure billing cycle. +6. If you deleted paid users with Basic or higher features, [reduce the users in Organization settings](../billing/buy-basic-access-add-users.md#reduce-charges-for-users-with-no-access) to avoid charges in your next Azure billing cycle. - To reduce or cancel users for the next month, make updates before the last day of the current month. - Your bill won't show the changes until the next month because paid users are monthly purchases. +To reduce or cancel users for the next month, make updates before the last day of the current month. Your bill reflects these changes in the following month, as paid users get billed monthly. ::: moniker-end -::: moniker range="azure-devops-2019" - -1. Sign in to your organization: ```https://dev.azure.com/{yourorganization}```. - -2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - - ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) - -3. Select **Users**. - - ![Screenshot showing selected Users button in organization settings.](../../media/settings/open-organization-settings-users-vert.png) - -4. Open the context menu **...** for the user to be removed. Select **Remove from organization**. - - ![Screenshot showing removal of user from organization.](media/delete-user/remove-user-from-organization-new.png) - -5. Choose **Remove** in the confirmation dialog. - -6. To confirm that you've removed the users completely, make sure they aren't in any of your [security groups](../../organizations/security/add-users-team-project.md). - - [Why don't users appear or disappear promptly after I add or delete them in the Users Services page?](faq-user-and-permissions-management.yml#users-delay) - -7. If you deleted paid users who had Basic or higher features, also [reduce the users in Organization settings](../billing/buy-basic-access-add-users.md#reduce-charges-for-users-with-no-access). Then you're not charged in your next Azure billing cycle. - - To reduce or cancel users for the next month, make updates before the last day of the current month. - Your bill won't show the changes until the next month because paid users are monthly purchases. - -::: moniker-end - -The **Users** page isn't available for on-premises server instances. However, you can use Azure DevOps CLI to manage users for Azure DevOps Server 2020. - #### [Azure DevOps CLI](#tab/azure-devops-cli/) ::: moniker range=" azure-devops" @@ -101,7 +68,7 @@ The **Users** page isn't available for on-premises server instances. However, yo [Add a user](add-organization-users.md#add-user) | [List users](../security/export-users-audit-log.md#list-users) | [Remove a user](#remove-user) | [Update a user](add-organization-users.md#update-user) | [Show users](add-organization-users.md#show-users) - + ### Remove a user @@ -135,7 +102,7 @@ az devops user remove --user contoso@contoso.com --org https://dev.azure.com/con ## Remove users from a team or project -To remove users from a project, remove them from the **Teams** groups they belong to or the **Contributors** group for the project. See [Add users to a project or specific team](../../organizations/security/add-users-team-project.md). You can remove a user from the **Members** page of a team group or security group. +To remove users from a project, remove them from the **Teams** groups they belong to or the **Contributors** group for the project. For more information, see [Add users to a project or specific team](../../organizations/security/add-users-team-project.md). You can remove a user from the **Members** page of a team group or security group. ![Screenshot showing removal of a user from a security group, new navigation.](media/delete-user/remove-user-vert.png) @@ -143,6 +110,6 @@ To remove users from a project, remove them from the **Teams** groups they belon - [Change project collection-level permissions](../security/change-organization-collection-level-permissions.md) - [Request an increase in permission levels](../../organizations/security/request-changes-permissions.md) -- [Grant or restrict access to select features and functions](../../organizations/security/restrict-access.md) +- [Manage access to specific features and functions](../../organizations/security/restrict-access.md) - [Troubleshoot adding and deleting organization users](faq-user-and-permissions-management.yml) - [Export a list of users and their access levels](../security/export-users-audit-log.md) diff --git a/docs/organizations/accounts/delete-your-organization.md b/docs/organizations/accounts/delete-your-organization.md index 542d35791ff..a4ebe74434b 100644 --- a/docs/organizations/accounts/delete-your-organization.md +++ b/docs/organizations/accounts/delete-your-organization.md @@ -1,14 +1,14 @@ --- title: Delete or remove an organization titleSuffix: Azure DevOps Services -ms.custom: seodec18 description: Learn how to delete your organization, and what happens to users when you do. ms.subservice: azure-devops-organizations ms.assetid: 82433ad3-d665-4a11-95b7-82178f493fb5 +ai-usage: ai-assisted ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 04/16/2020 +ms.date: 01/03/2025 monikerRange: 'azure-devops' --- @@ -17,30 +17,30 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] When you no longer need an organization, you can delete it from Azure DevOps. If you change your mind within 28 days, you can [recover your organization](./recover-your-organization.md). -After 28 days, your organization and data are permanently deleted. +After 28 days, your organization and all associated data get permanently deleted. -When you delete your organization, note the following occurrences: +When you delete your organization, the following results occur: -* All users lose access to organization services and resources immediately. +- **Loss of access:** Users immediately lose access to organization services and resources. +- **URL availability:** Your organization URL becomes available for anyone to use, which might take up to one hour. +- **Organization disabled:** Your organization is disabled and appears deleted in your profile for 28 days. +- **Billing unlinking:** If your organization is linked to an Azure subscription for billing, you must unlink it before deletion. You're still charged for any paid users and services used during the current billing cycle. Billing stops after the current cycle ends. +- **Azure account access:** Deleting an organization in Azure DevOps doesn't directly affect users' access to their Azure accounts in portal.azure.com. Users still retain access to Azure accounts and other services, as the deletion is specific to the Azure DevOps organization and its associated data. -* Your organization URL becomes available for anyone to use. (It might take up to one hour before your organization URL becomes available again.) - -* Your organization is disabled, and appears deleted in your profile for 28 days. - -* If your organization is linked to an Azure subscription for billing purchases, you must unlink your organization before you delete your organization. - - You're still charged for any paid users and services used during this billing cycle. Billing stops after the current cycle ends. - -To delete your organization, you need Project Collection Administrator permissions. [How do I find the Project Collection Administrators?](../security/look-up-project-collection-administrators.md) +> [!CAUTION] +> In rare cases, our deletion process might take up to 70 days due to backend retries and the need to delete data from multiple sources. ## Prerequisites -If your organization uses an Azure subscription to bill purchases, you must [first remove billing from your organization](../billing/change-azure-subscription.md#remove-your-billing-subscription) before you can delete your organization in Azure DevOps. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +|**Access levels**| At least **Basic** access.| +|**Subscription** |If your organization uses an Azure subscription for billing, [remove billing from your organization](../billing/change-azure-subscription.md#remove-your-billing-subscription) before deleting it in Azure DevOps.| ## Delete organization -To delete your organization, you need at least Basic access and Project Collection Administrator -permissions. [How do I find the Project Collection Administrators?](../security/look-up-project-collection-administrators.md) +To delete an organization, do the following steps. 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). @@ -48,7 +48,6 @@ permissions. [How do I find the Project Collection Administrators?](../security/ ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) - 3. Select **Overview** > **Delete**. ![Screenshot of organization settings, with Overview and Delete highlighted](media/delete-organization/organization-overview-settings.png) diff --git a/docs/organizations/accounts/disable-request-access-policy.md b/docs/organizations/accounts/disable-request-access-policy.md index ef630ce5a62..d37115b410f 100644 --- a/docs/organizations/accounts/disable-request-access-policy.md +++ b/docs/organizations/accounts/disable-request-access-policy.md @@ -8,7 +8,7 @@ ms.assetid: ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 07/25/2022 +ms.date: 10/23/2024 monikerRange: 'azure-devops' --- @@ -16,13 +16,14 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Stop your users from requesting access to your organization or project within your organization, by disabling the Request Access policy. - -When this policy is on, users can request access to a resource. A request results in an email notification to the administrators asking for review and access, as needed. +To prevent users from requesting access to your organization or projects, you can disable the 'Request Access' policy. When enabled, this policy allows users to request access, triggering email notifications to administrators for review and approval. Disabling the policy stops these requests and notifications. ## Prerequisites -You must be a member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md) and have at least Basic access. Organization owners are automatically members of this group. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +|**Access levels**| At least **Basic** access.| ## Disable Request Access policy @@ -30,19 +31,23 @@ You must be a member of the [Project Collection Administrators group](../securit 2. Choose ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - ![Choose the gear icon, Organization settings](../../media/settings/open-admin-settings-vert.png) + ![Screenshot shows Choose the gear icon and Organization settings button.](../../media/settings/open-admin-settings-vert.png) + +3. Select **Policies**, locate the *Request Access policy* and toggle it to *off*. + + ![Screenshot shows Disable the Request Access policy in Organization settings.](media/request-access-policy-settings.png) -3. Select **Policies** to find the *Request Access policy* and move the toggle to *off*. +4. Provide the URL to your internal process for gaining access. Users see this URL in the error report when they try to access the organization or a project within the organization that they don't have permission to access. - ![Disable the Request Access policy in Organization settings](media/request-access-policy-settings.png) + ![Screenshot shows prompt for entering the URL to your organization's internal process for gaining access.](media/disable-request-access-provide-url.png) -4. Provide the URL to your internal process for gaining access. Users see this URL in the error report when they try to access the organization or a project within the organization that they don't have access to. +**Results:** - ![Enter the URL to your organization's internal process for gaining access.](media/disable-request-access-provide-url.png) +- **Users already part of the organization:** If they lack permission to access a specific project, they get a 404 error. To maintain confidentiality, the 404 error doesn’t reveal whether the project exists and so doesn't provide a link to request access. +- **Users not part of the organization:** If they attempt to access a resource, they get a 401 error, which includes a link to the configured custom URL for requesting access. ## Related articles -- [Need help?](faq-configure-customize-organization.yml#get-support) - [Assign access levels by group membership](assign-access-levels-by-group-membership.md) - [Manage Conditional Access](change-application-access-policies.md) -- [Change application access policies](change-application-access-policies.md). +- [Change application access policies](change-application-access-policies.md) diff --git a/docs/organizations/accounts/disconnect-organization-from-azure-ad.md b/docs/organizations/accounts/disconnect-organization-from-azure-ad.md index bc477d240af..2fe4da3b769 100644 --- a/docs/organizations/accounts/disconnect-organization-from-azure-ad.md +++ b/docs/organizations/accounts/disconnect-organization-from-azure-ad.md @@ -1,38 +1,37 @@ --- -title: Disconnect organization from Azure AD +title: Disconnect organization from Microsoft Entra ID titleSuffix: Azure DevOps Services -ms.custom: seodec18 -description: Learn how to stop using your organization's Azure AD and sign in with a Microsoft account by disconnecting your organization from your directory +description: Learn how to stop using your organization's Microsoft Entra ID and sign in with a Microsoft account by disconnecting your organization from your directory ms.subservice: azure-devops-organizations ms.assetid: 3eb744cf-854d-4cbd-b725-c2e070bd922b ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 05/14/2019 +ms.date: 10/23/2024 monikerRange: 'azure-devops' --- -# Disconnect your organization from Azure Active Directory + +# Disconnect your organization from Microsoft Entra ID [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -To stop using your organization's Azure Active Directory (Azure AD) and return to signing in with Microsoft accounts, disconnect your organization from your directory. +To stop using your organization's Microsoft Entra ID and return to signing in with Microsoft accounts, you need to disconnect your organization from the directory. This process reverts the authentication method for your organization, allowing users to sign in using their Microsoft accounts instead of Microsoft Entra ID. You might disconnect if you no longer require the centralized management and security features provided by Microsoft Entra ID or if you need to simplify the sign-in process for your users. Follow the steps in this article to disconnect your organization from Microsoft Entra ID and switch back to using Microsoft accounts for authentication. -For more information about using Azure AD with Azure DevOps, see the [conceptual overview](access-with-azure-ad.md). +For more information about using Microsoft Entra ID with Azure DevOps, see the [conceptual overview](access-with-azure-ad.md). ## Prerequisites -* Before you disconnect your organization from your directory, make sure to **change the organization owner to a Microsoft account** and not to a school or work account. You can't sign in to your organization unless your work or school account has the same email address as your Microsoft account. - -* Add your Microsoft account to the Project Collection Administrator group in Organization Settings and confirm that you have Global Administrator Permissions in your Azure AD for your Microsoft account. You need both because Azure AD users can't disconnect organizations from directories. You can add Microsoft accounts to a directory as external users. - -Learn about how to [Manage Azure administrators](/azure/active-directory/users-groups-roles/directory-assign-admin-roles). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.
      - Change the organization owner to a Microsoft account instead of a school or work account. Ensure that your work or school account has the same email address as your Microsoft account; otherwise, you can't sign in to your organization.| +|**Access levels**| At least **Basic** access.| **What happens to current users?** Users can migrate everything except work history. They can reconnect Visual Studio subscriptions and have their access levels reassigned to their new identities. > [!IMPORTANT] -> If you want to connect your organization to a different Azure Active Directory at any time, ensure that any connected organizations are disconnected from the original directory BEFORE you delete that directory. Once a new directory is established, connect your organization to the new directory so users can regain access. Learn more about [connecting your organization to Azure AD](connect-organization-to-azure-ad.md). +> If you want to connect your organization to a different Microsoft Entra ID, first disconnect any connected organizations from the original directory before deleting it. Once the new directory is established, connect your organization to it so users can regain access. For more information, see [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md) or [Change your organization connection to a different Microsoft Entra ID](change-azure-ad-connection.md). ## Disconnect organization from directory @@ -42,26 +41,24 @@ Learn about how to [Manage Azure administrators](/azure/active-directory/users-g ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) -3. Select **Azure Active Directory**, and then select **Disconnect directory**. +3. Select **Microsoft Entra ID**, and then select **Disconnect directory**. ![Organization settings, disconnect directory](media/shared/select-disconnect-directory.png) 4. Enter the name of your organization, and then select **Disconnect**. - ![Disconnection confirmation](media/shared/disconnection-confirmation.png) + ![Screenshot showing Disconnection confirmation.](media/shared/disconnection-confirmation.png) 5. Select **Sign out**. - ![Select Sign out](media/shared/sign-out-azure-devops.png) - -Your organization is disconnected from Azure AD. Only users with Microsoft accounts can sign in. + ![Screenshot showing Sign out button.](media/shared/sign-out-azure-devops.png) -For answers to frequently asked questions about connecting to, disconnecting from, or switching your Azure AD, see [FAQs](./faq-azure-access.yml#faq-connect). +Your organization is disconnected from Microsoft Entra ID. Only users with Microsoft accounts can sign in. ## Related articles -* [Connect your organization to Azure Active Directory](connect-organization-to-azure-ad.md) -* [About access with Azure AD](access-with-azure-ad.md) -* [Get a list of organizations backed by Azure AD](get-list-of-organizations-connected-to-azure-active-directory.md) +* [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md) +* [Learn about access with Microsoft Entra ID](access-with-azure-ad.md) +* [Get a list of organizations backed by Microsoft Entra ID](get-list-of-organizations-connected-to-azure-active-directory.md) * [Restrict organization creation with tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) -* [Frequently asked questions (FAQs) about connecting, disconnecting, or changing your Azure AD](./faq-azure-access.yml#connect-to-disconnect-from-or-change-azure-ad-connection) \ No newline at end of file +* [Frequently asked questions (FAQs) about connecting, disconnecting, or changing your Microsoft Entra ID](./faq-azure-access.yml) diff --git a/docs/organizations/accounts/faq-azure-access.yml b/docs/organizations/accounts/faq-azure-access.yml index e1f9a84eb3d..f44bd5422d8 100644 --- a/docs/organizations/accounts/faq-azure-access.yml +++ b/docs/organizations/accounts/faq-azure-access.yml @@ -1,61 +1,60 @@ ### YamlMime:FAQ metadata: - title: Access via Azure AD FAQs - ms.custom: seodec18, fasttrack-edit, engagement-fy23 - description: Learn the answers to frequently asked questions (FAQs), like how to understand Azure AD groups, add users, connect to, disconnect from, or switch your directory. + title: Access via Microsoft Entra FAQs + ms.custom: fasttrack-edit, engagement-fy23, has-azure-ad-ps-ref, azure-ad-ref-level-one-done + description: Learn the answers to frequently asked questions (FAQs), like how to understand Microsoft Entra groups, add users, connect to, disconnect from, or switch your directory. ms.subservice: azure-devops-organizations ms.assetid: d51de748-c53e-4468-ad9b-275d6bf1a4dd ms.topic: faq ms.author: chcomley author: chcomley - ms.date: 03/02/2023 + ms.date: 10/23/2024 monikerRange: 'azure-devops' -title: Access via Azure AD FAQs +title: Access via Microsoft Entra FAQs summary: | [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] [!INCLUDE [alt-creds-deprecation-notice](../../includes/alt-creds-deprecation-notice.md)] - Learn the answers to the following frequently asked questions (FAQs) about access to your Azure DevOps organization via Azure Active Directory (AD). We grouped the FAQs by the following subjects: + Learn the answers to the following frequently asked questions (FAQs) about access to your Azure DevOps organization via Microsoft Entra ID. We grouped the FAQs by the following subjects: - [General](#general) - - [Azure AD users and permissions](#azure-ad-users-and-permissions) - - [Azure AD groups](#azure-ad-groups) + - [Microsoft Entra users and permissions](#azure-ad-users-and-permissions) + - [Microsoft Entra groups](#azure-ad-groups) - [Add users to directory](#add-users-to-directory) - - [Remove users or groups](#remove-users-or-groups) - - [Connect to, disconnect from, or switch connection with Azure AD](#faq-connect) + - [Connect to, disconnect from, or switch connection with Microsoft Entra ID](#faq-connect) sections: - - name: General access with Azure AD + - name: General access with Microsoft Entra ID questions: - question: | Why don't I see my organization in the Azure portal? answer: | - In both applications, you must have - [Azure Service Administrator or Co-administrator](/azure/billing-add-change-azure-subscription-administrator) - permissions for the Azure subscription that's linked to your organization in Azure DevOps. - Also, in the [Azure portal](https://portal.azure.com), you must have Project Collection Administrator or organization owner permissions. + In both applications, have + [Azure Service Administrator or Coadministrator](/azure/billing-add-change-azure-subscription-administrator) + permissions for the Azure subscription linked to your organization in Azure DevOps. + Also, in the [Azure portal](https://portal.azure.com), have Project Collection Administrator or organization owner permissions. - question: | - What do I need to set up an existing Azure DevOps instance with Azure AD? + What do I need to set up an existing Azure DevOps instance with Microsoft Entra ID? answer: | - Ensure you meet the prerequisites in the following article, [Connect your organization to Azure AD](connect-organization-to-azure-ad.md). + Ensure you meet the prerequisites in the following article, [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md). - question: | - I made changes to Azure Active Directory (Azure AD), but they didn't seem to take effect, why? + I made changes to Microsoft Entra ID, but they didn't seem to take effect, why? answer: | - Changes made in Azure AD can take up to 1 hour to be visible in Azure DevOps. + Changes made in Microsoft Entra ID can take up to 1 hour to be visible in Azure DevOps. - question: | - Can I use Microsoft 365 and Azure AD with Azure DevOps? + Can I use Microsoft 365 and Microsoft Entra ID with Azure DevOps? answer: | **Yes**. - Don't have an organization yet? [Create an organization in Azure DevOps](https://aka.ms/SignupAzureDevOps). - - Already have an organization? [Connect your organization to Azure AD](connect-organization-to-azure-ad.md). + - Already have an organization? [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md). @@ -66,16 +65,16 @@ sections: - question: | - My organization uses Microsoft accounts only. Can I switch to Azure AD? + My organization uses Microsoft accounts only. Can I switch to Microsoft Entra ID? answer: | - **Yes**, but before you switch, make sure that Azure AD meets your needs for sharing the following items: - - work items - - code - - resources - - other assets with your team and partners + **Yes**, but before you switch, make sure that Microsoft Entra ID meets your needs for sharing the following items: + - Work items + - Code + - Resources + - Other assets with your team and partners Learn more about - controlling access with Microsoft accounts versus Azure AD, and [how to switch when you're ready](access-with-azure-ad.md). + controlling access with Microsoft accounts versus Microsoft Entra ID, and [how to switch when you're ready](access-with-azure-ad.md). [!INCLUDE [why-cant-sign-in-msa-azuread-account](../../includes/qa-why-cant-sign-in-msa-azuread-account.md)] @@ -94,40 +93,40 @@ sections: - #### Azure AD users and permissions + #### Microsoft Entra users and permissions If you don't find an answer to your question here, see [User and permissions management FAQs](./faq-user-and-permissions-management.yml?view=azure-devops). - question: | Why do I have to add users to a directory? answer: | - Your organization authenticates users and controls access through Azure Active Directory (Azure AD). All users must be directory members to get access. + Your organization authenticates users and controls access through Microsoft Entra ID. All users must be directory members to get access. As a directory administrator, you can [add users to the directory](/previous-versions/azure/hh967632(v=azure.100)). If you're not an administrator, work with your directory administrator to add users. Learn more about [controlling access to Azure DevOps Services by using a directory](access-with-azure-ad.md). - question: | What happens to current users? answer: | - Your work in Azure DevOps Services is associated with your credentials for Azure AD. After your organization is connected to your directory, users continue working seamlessly if their credential addresses appear in the connected directory. If users' addresses don't appear, you must [add those users to your directory](/azure/active-directory/fundamentals/add-users-azure-active-directory). Your organization might have policies about adding users to the directory, so find out more first. + Your work in Azure DevOps is associated with your credentials for Microsoft Entra ID. After your organization is connected to your directory, users continue working seamlessly if their credential addresses appear in the connected directory. If users' addresses don't appear, you must [add those users to your directory](/azure/active-directory/fundamentals/add-users-azure-active-directory). Your organization might have policies about adding users to the directory, so find out more first. - question: | - How do I find out whether my organization uses Azure AD to control access? + How do I find out whether my organization uses Microsoft Entra ID to control access? answer: | - If you have at least Basic access, go to your **Organization settings**, and then select the **Azure Active Directory** tab. You either have an option to **Connect directory**, or **Disconnect directory**. + If you have at least Basic access, go to your **Organization settings**, and then select the **Microsoft Entra ID** tab. Either **Connect directory**, or **Disconnect directory**. - question: | - My organization controls access by using Azure Active Directory. Can I just delete users from the directory? + My organization controls access by using Microsoft Entra ID. Can I just delete users from the directory? answer: | - Yes, but deleting a user from the directory removes the user's access to all organizations and other assets associated with that directory. You must have Azure AD global administrator permissions to [delete a user from your Azure AD directory](/azure/active-directory/fundamentals/add-users-azure-active-directory). + Yes, but deleting a user from the directory removes the user's access to all organizations and other assets associated with that directory. For more information, see [Delete a user from your Microsoft Entra directory](/azure/active-directory/fundamentals/add-users-azure-active-directory). - question: | - Why are "no identities found" when I try to add users from Azure AD to my Azure DevOps organization? + Why are "no identities found" when I try to add users from Microsoft Entra ID to my Azure DevOps organization? answer: | - You're probably a *guest* in the Azure AD that backs your Azure DevOps organization, rather than a *member*. Azure AD guests can't search the Azure AD in the manner required by Azure DevOps. For example, Azure AD guests can't use the Azure DevOps web portal to search for or select users who haven't already been added to the Azure DevOps organization. Learn how to [convert an Azure AD guest into a member](#how-can-i-convert-an-azure-ad-guest-into-a-member). + You're probably a *guest* in the Microsoft Entra ID that backs your Azure DevOps organization, rather than a *member*. Microsoft Entra guests can't search the Microsoft Entra ID in the manner required by Azure DevOps. For example, Microsoft Entra guests can't use the Azure DevOps web portal to search for or select users who aren't added to the Azure DevOps organization. Learn how to [convert a Microsoft Entra guest into a member](#how-can-i-convert-an-azure-ad-guest-into-a-member). - question: | What if we can't use the same sign-in addresses? @@ -135,72 +134,69 @@ sections: Add these users to the directory with new work or school accounts, and reassign access levels and readd them to any projects. If they have existing work or school accounts, those accounts can be used instead. Work isn't lost and stays with their current sign-in addresses. Users can migrate work that they want to keep, except for their work history. For more information, see [how to add organization users](add-organization-users.md). - question: | - What if I accidentally delete a user in Azure AD? + What if I accidentally delete a user in Microsoft Entra ID? answer: | [Restore the user](/azure/active-directory/fundamentals/active-directory-users-restore), rather than create a new one. If you create a new user, even with the same email address, this user isn't associated with the previous identity. - question: | - How can I convert an Azure AD guest into a member? + How can I convert a Microsoft Entra guest into a member? answer: | Select from the following two options: - * Have the Azure AD administrator(s) remove you from the Azure AD and readd you, making you an Azure AD *member*, rather than a *guest*. For more information, see [Can Azure AD B2B users be added as members instead of guests?](/azure/active-directory/b2b/user-properties#can-azure-ad-b2b-users-be-added-as-members-instead-of-guests). - * [Change the UserType of the Azure AD guest using Azure AD PowerShell](#convert-azure-ad-usertype-from-guest-to-member-using-azure-ad-powershell). [We don't advise](/azure/active-directory/external-identities/user-properties#convert-usertype) using this advanced process, but it allows the user to query Azure AD from the Azure DevOps organization. + * Have a Microsoft Entra administrator remove your account from the directory and readd it, making you a *member*, rather than a *guest*. For more information, see [Can Microsoft Entra B2B users be added as members instead of guests?](/azure/active-directory/b2b/user-properties#can-azure-ad-b2b-users-be-added-as-members-instead-of-guests). + * [Change the UserType of the Microsoft Entra guest using Microsoft Graph PowerShell](#convert-the-usertype-from-guest-to-member-using-microsoft-graph-powershell). [We don't advise](/azure/active-directory/external-identities/user-properties#convert-usertype) using this advanced process, but it allows the user to query Microsoft Entra ID from the Azure DevOps organization. - #### Convert Azure AD UserType from guest to member using Azure AD PowerShell + #### Convert the UserType from guest to member using Microsoft Graph PowerShell > [!WARNING] - > This process is advanced, which [we don't advise](/azure/active-directory/external-identities/user-properties#convert-usertype), but it allows the user to query Azure AD from the Azure DevOps organization. - + > [We don't recommend](/azure/active-directory/external-identities/user-properties#convert-usertype) this advanced process, but it allows the user to query Microsoft Entra ID from the Azure DevOps organization. + **Prerequisites** - The user making the UserType change must have the following items: + As the user making the UserType change, have the following items: - * A work/school account (WSA)/native user in Azure AD. You can't change the UserType with a Microsoft Account. - * Global administrator permissions + * A work/school account (WSA)/native user in Microsoft Entra ID. You can't change the UserType with a Microsoft Account. + * User Administrator permissions > [!IMPORTANT] - > We recommend that you create a brand new (native) Azure AD user who's a global admin in the Azure AD. Then, complete the following steps with that user. This new user should eliminate the possibility of connecting to the wrong Azure AD. You can delete the new user when you're done. - + > We recommend creating a new (native) Microsoft Entra user with User Administrator permissions in Microsoft Entra ID. Complete the following steps with this user to eliminate the possibility of connecting to the wrong Microsoft Entra ID. You can delete the new user when you're done. + **Process** - 1. Sign in to the [Azure portal](https://portal.azure.com) as global administrator for your organization's directory. + 1. Sign in to the [Azure portal](https://portal.azure.com) as User Administrator for your organization's directory. 2. Go to the tenant that backs your Azure DevOps organization. - 3. Check the UserType. Confirm that the user is a *Guest*. - 4. Open an Administrative Windows PowerShell prompt. - 5. Execute `Install-Module -Name AzureAD`. The [Azure Active Directory PowerShell for Graph](/powershell/azure/active-directory/install-adv2?&preserve-view=true&view=azureadps-2.0) downloads from the PowerShell Gallery. You may see prompts about installing NuGet and untrusted repository, pictured as follows. If you run into issues, review the system requirements and information at the [Azure Active Directory PowerShell for Graph](/powershell/azure/active-directory/install-adv2?view=azureadps-2.0&preserve-view=true) page. + 3. Open an Administrative Windows PowerShell prompt to use Microsoft Graph PowerShell. + 4. Execute `Install-Module -Name Microsoft.Graph -Scope CurrentUser`. The [Microsoft Graph](/powershell/microsoftgraph/installation) downloads from the PowerShell Gallery. + 5. Once the installation completes, execute `Connect-MgGraph -Scopes "User.ReadWrite.All"`. Sign in to the Microsoft Entra ID. Be sure to use an ID that meets the previously mentioned criteria and consent to the permissions. + 6. Execute `Get-MgUser -Filter "DisplayName eq ' is the display name for the user, as seen inside the Azure portal. We want to change the userType to `Member`. + 7. Execute `Update-MgUser -UserId string -UserType Member`, where `string` is the value of ID returned by the previous command. The user is set to member status. + 8. Execute `Get-MgUser -Filter "DisplayName eq '"`, where is part of the entire display name for the user, as seen inside the Azure portal). The command returns four columns for the user found - ObjectId, DisplayName, UserPrincipalName, UserType - and the UserType should say *guest*. - 8. Execute `Set-AzureADUser -ObjectID string -UserType Member`, where `string` is the value of ObjectId returned by the previous command. The user is set to member status. - 9. Execute `Get-AzureADuser -SearchString ""` again to verify the UserType has changed. You can also verify in the Azure Active Directory section of the Azure portal. - While not the norm, we've seen it takes several hours, or even days before this change is reflected inside Azure DevOps. If it doesn't fix your Azure DevOps issue immediately, give it some time and keep trying. + While not the norm, it could take several hours, or even days before this change reflects in Azure DevOps. If it doesn't fix your Azure DevOps issue immediately, give it some time and keep trying. - - name: Azure AD groups + - name: Microsoft Entra groups questions: - question: | - Why can't I assign Azure DevOps permissions directly to an Azure AD group? + Why can't I assign Azure DevOps permissions directly to a Microsoft Entra group? answer: | Because these groups are created and managed in Azure, you can't assign Azure DevOps permissions directly or secure version control paths to these groups. You get an error if you try to assign permissions directly. - You can add an Azure AD group to the Azure DevOps group that has the permissions you want. Or, - you can assign these permissions to the group instead. Azure AD group members inherit permissions from the group where you add them. + You can add a Microsoft Entra group to the Azure DevOps group that has the permissions you want. Or, + you can assign these permissions to the group instead. Microsoft Entra group members inherit permissions from the group where you add them. - question: | - Can I manage Azure AD groups in Azure DevOps? + Can I manage Microsoft Entra groups in Azure DevOps? answer: | - No, because these groups are created and managed in Azure. Azure DevOps doesn't store or sync member status for Azure AD groups. To manage Azure AD groups, use the [Azure portal](https://portal.azure.com), Microsoft Identity Manager (MIM), + No, because these groups are created and managed in Azure. Azure DevOps doesn't store or sync member status for Microsoft Entra groups. To manage Microsoft Entra groups, use the [Azure portal](https://portal.azure.com), Microsoft Identity Manager (MIM), or the group management tools that your organization supports. - question: | - How do I tell the difference between an Azure DevOps group and an Azure AD group? + How do I tell the difference between an Azure DevOps group and a Microsoft Entra group? answer: | The Azure DevOps UI indicates membership scope using brackets `[]`. For example, consider this permissions settings page: @@ -210,64 +206,69 @@ sections: |:--|:--| | `[fabrikam-fiber]` | Membership is defined in Organization Settings | | `[Project Name]` | Membership is defined in Project Settings | - | `[TEAM FOUNDATION]` | Membership is defined _directly_ in Azure AD | + | `[TEAM FOUNDATION]` | Membership is defined _directly_ in Microsoft Entra ID | > [!Note] - > If you add an Azure AD group to a custom security group _and_ use a similar name, you may see what appears to be duplicate groups. Examine the scope in `[]` to determine which is a DevOps Group and which is an Azure AD Group. + > If you add a Microsoft Entra group to a custom security group and use a similar name, you might see what appears to be duplicate groups. Examine the scope in `[]` to determine which is a DevOps Group and which is a Microsoft Entra group. - question: | - Why doesn't the Users list show all Azure AD group members? + Why doesn't the Users list show all Microsoft Entra group members? answer: | These users have to sign in to your organization before they appear in Users. - question: | - How do I assign organization access to Azure AD group members? + How do I assign organization access to Microsoft Entra group members? answer: | When these group members sign in to your organization for the first time, Azure DevOps assigns an access level to them automatically. If they have [Visual Studio subscriptions](faq-user-and-permissions-management.yml#EligibleMSDNSubscriptions), Azure DevOps assigns the respective access level to them. Otherwise, Azure DevOps assigns them the next "best available" [access level](https://visualstudio.microsoft.com/pricing/visual-studio-online-feature-matrix-vs), in this order: Basic, Stakeholder. - If you don't have enough access levels for all Azure AD group members, those members who sign in get a Stakeholder access. + If you don't have enough access levels for all Microsoft Entra group members, those members who sign in get a Stakeholder access. - question: | - Why doesn't the Security tab show all members when I select an Azure AD group? + How can I protect access to built-in administrator groups? answer: | - The Security tab shows Azure AD group members only after they sign in to your organization, and have an access level assigned to them. + Require just-in-time access using a Microsoft Entra Privileged Identity Management (PIM) group. + + - question: | + Why doesn't the Security tab show all members when I select a Microsoft Entra group? + answer: | + The Security tab shows Microsoft Entra group members only after they sign in to your organization, and have an access level assigned to them. - To see all Azure AD group members, use the [Azure portal](https://portal.azure.com), MIM, or the group management tools that your organization supports. + To see all Microsoft Entra group members, use the [Azure portal](https://portal.azure.com), MIM, or the group management tools that your organization supports. - question: | - Why doesn't the team members widget show all Azure AD group members? + Why doesn't the team members widget show all Microsoft Entra group members? answer: | The team members widget shows only users who previously signed in to your organization. - question: | - Why doesn't the team capacity pane show all Azure AD group members? + Why doesn't the team capacity pane show all Microsoft Entra group members? answer: | The team capacity pane shows only users who previously signed in to your organization. To set capacity, manually add users to your team. - question: | - Why doesn't Azure DevOps reclaim access levels from users who aren't Azure AD group members anymore? + Why doesn't Azure DevOps reclaim access levels from users who aren't Microsoft Entra group members anymore? answer: | Azure DevOps doesn't automatically reclaim access levels from these users. To manually remove their access, go to **Users**. - question: | - Can I assign work items to Azure AD group members who haven't signed in? + Can I assign work items to Microsoft Entra group members who haven't signed in? answer: | - You can assign work items to any Azure AD member who has permissions for your organization. This action also adds that member to your organization. When you add users this way, they automatically appear as Users, with the best available + You can assign work items to any Microsoft Entra member who has permissions for your organization. This action also adds that member to your organization. When you add users this way, they automatically appear as Users, with the best available access level. The user also appears in the security settings. - question: | - Can I use Azure AD groups to query work items by using the "In Group" clause? + Can I use Microsoft Entra groups to query work items by using the "In Group" clause? answer: | - No, we don't support querying on Azure AD groups. + No, we don't support querying on Microsoft Entra groups. - question: | - Can I use Azure AD groups to set up field rules in my work item templates? + Can I use Microsoft Entra groups to set up field rules in my work item templates? answer: | No, but you might be interested in our [process customization plans](https://devblogs.microsoft.com/devops/visual-studio-online-process-customization-update/). @@ -275,34 +276,36 @@ sections: #### Add users to directory - [Add organization users to your Azure Active Directory](/azure/active-directory/fundamentals/add-users-azure-active-directory). + [Add organization users to your Microsoft Entra ID](/azure/active-directory/fundamentals/add-users-azure-active-directory). - question: | Why did I get an error stating that my organization has multiple active identities with the same UPN? answer: | - During the connect process, we map existing users to members of the Azure AD tenant, based on their UPN, which is often known as sign-in address. If we detect multiple users with the same UPN, we don't know how to map these users. This scenario occurs if a user changes their UPN to match one already existing in the organization. + During the connect process, we map existing users to members of the Microsoft Entra tenant, based on their UPN, which is often known as sign-in address. If we detect multiple users with the same UPN, we don't know how to map these users. This scenario occurs if a user changes their UPN to match one already existing in the organization. + + If you encounter this error, review your list of users for any duplicates. If you find any duplicates, remove the users you don't need. If you can't find any duplicates, [contact support](https://developercommunity.visualstudio.com/spaces/21/index.html). - question: | Can I switch current users from Microsoft accounts to work accounts in Azure DevOps? answer: | - No. Although you can add new work accounts to your organization, they're treated as new users. If you want to access all your work, including its history, you must use the same sign-in addresses that you used before your organization was connected to your Azure AD. - Add your Microsoft account as a member to your Azure AD. + No. Although you can add new work accounts to your organization, they're treated as new users. If you want to access all your work, including its history, you must use the same sign-in addresses that you used before your organization was connected to your Microsoft Entra ID. + Add your Microsoft account as a member to your Microsoft Entra ID. - question: | - Why can't I add users from other directories to my Azure AD? + Why can't I add users from other directories to my Microsoft Entra ID? answer: | - You must be a member or have read access in those directories. Otherwise, you can add them - [using B2B collaboration through your Azure AD administrator](/azure/active-directory/external-identities/what-is-b2b). You can also add them by using their Microsoft accounts, or by creating new work accounts for them in your directory. + Be a member of or have Read access in those directories. Otherwise, you can add them + [using B2B collaboration through your Microsoft Entra administrator](/azure/active-directory/external-identities/what-is-b2b). You can also add them by using their Microsoft accounts, or by creating new work accounts for them in your directory. - question: | What if I get an error trying to map a user to an existing member of my organization? answer: | - You can map the user onto a different identity that isn't yet an active member of the organization or add the existing user to your Azure AD. If you still need to map to the existing Azure DevOps organization member, [contact support.](https://developercommunity.visualstudio.com/spaces/21/index.html) + You can map the user onto a different identity that isn't yet an active member of the organization or add the existing user to your Microsoft Entra ID. If you still need to map to the existing Azure DevOps organization member, [contact support.](https://developercommunity.visualstudio.com/spaces/21/index.html) - question: | How do I use my work or school account with my Visual Studio with MSDN subscription? answer: | - If you used a Microsoft account to activate a [Visual Studio with MSDN subscription](https://visualstudio.microsoft.com/vs/pricing/) containing Azure DevOps as a benefit, you can add a work or school account. Azure AD must manage the account. Learn [how to link work or school accounts to Visual Studio with MSDN subscriptions](/visualstudio/subscriptions/vs-alternate-identity). + If you used a Microsoft account to activate a [Visual Studio with MSDN subscription](https://visualstudio.microsoft.com/vs/pricing/) containing Azure DevOps as a benefit, you can add a work or school account. Microsoft Entra ID must manage the account. Learn [how to link work or school accounts to Visual Studio with MSDN subscriptions](/visualstudio/subscriptions/vs-alternate-identity). @@ -310,7 +313,7 @@ sections: Can I control access to my organization for external users in the connected directory? answer: | Yes, but only for external users who are [added as guests through Microsoft 365](https://support.office.com/article/Share-sites-or-documents-with-people-outside-your-organization-80E49744-E30F-44DB-8D51-16661B1D4232) - or [added using B2B collaboration by your Azure AD administrator](/azure/active-directory/external-identities/what-is-b2b). These external users are managed outside the connected directory. To learn more, contact your Azure AD administrator. The following setting doesn't affect [users who are added directly to your organization's directory](/azure/active-directory/fundamentals/add-users-azure-active-directory). + or [added using B2B collaboration by your Microsoft Entra administrator](/azure/active-directory/external-identities/what-is-b2b). These external users are managed outside the connected directory. For more information, contact your Microsoft Entra administrator. The following setting doesn't affect [users who are added directly to your organization's directory](/azure/active-directory/fundamentals/add-users-azure-active-directory). Before you start, make sure you have at least Basic access, not Stakeholder. @@ -321,47 +324,47 @@ sections: - name: Remove users or groups questions: - question: | - How do I remove an Azure AD group from Azure DevOps? + How do I remove a Microsoft Entra group from Azure DevOps? answer: | Go to your project collection or project. In the upper bar, select :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: **Settings**, and then select **Security**. - Find the Azure AD group, and delete it from your organization. + Find the Microsoft Entra group, and delete it from your organization. ![Screenshot of project, with Delete option highlighted](media/manage-azure-ad-groups/deleteaadgroupfromvso.png) - question: | - Why am I asked to remove a user from an Azure AD group when I delete that user from my organization? + Why am I asked to remove a user from a Microsoft Entra group when I delete that user from my organization? answer: | - Users can belong to your organization, both as individuals and as members of Azure AD groups in Azure DevOps groups. These users can still access your organization while they're members of these Azure AD groups. + Users can belong to your organization, both as individuals and as members of Microsoft Entra groups in Azure DevOps groups. These users can still access your organization while they're members of these Microsoft Entra groups. - To block all access for users, remove them from Azure AD groups in your organization, or remove these groups from your organization. We currently can't block access completely or make exceptions for such users. + To block all access for users, remove them from Microsoft Entra groups in your organization, or remove these groups from your organization. We currently can't block access completely or make exceptions for such users. - question: | - If an Azure AD user is removed, are all their related PATs revoked as well? + If a Microsoft Entra user is removed, are all their related PATs revoked as well? answer: | Users who are disabled or removed from your directory, can no longer access your organization by any mechanism, including via PATs or SSH. - #### Connect to, disconnect from, or change Azure AD connection + #### Connect to, disconnect from, or change Microsoft Entra connection - - [Connect your organization to Azure AD](./connect-organization-to-azure-ad.md) + - [Connect your organization to Microsoft Entra ID](./connect-organization-to-azure-ad.md) - [Disconnect your organization from your directory](./disconnect-organization-from-azure-ad.md) - - [Change the directory that's connected to Azure DevOps](change-azure-ad-connection.md) - - [Get a list of organizations backed by Azure AD](get-list-of-organizations-connected-to-azure-active-directory.md) + - [Change the directory connected to Azure DevOps](change-azure-ad-connection.md) + - [Get a list of organizations backed by Microsoft Entra ID](get-list-of-organizations-connected-to-azure-active-directory.md) - [Restrict organization creation with tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) - question: | - How can I manage multiple organizations that are connected to Azure AD? + How can I manage multiple organizations that are connected to Microsoft Entra ID? answer: | - You can download a complete list of organizations backed by an Azure Active Directory tenant. For more information, see [Get a list of organizations backed by Azure AD](get-list-of-organizations-connected-to-azure-active-directory.md). + You can download a complete list of organizations backed by a Microsoft Entra tenant. For more information, see [Get a list of organizations backed by Microsoft Entra ID](get-list-of-organizations-connected-to-azure-active-directory.md). - question: | - Can I connect my organization to an Azure AD created from Microsoft 365? + Can I connect my organization to a Microsoft Entra ID created from Microsoft 365? answer: | - **Yes**. If you can't find your Azure AD created from Microsoft 365, see + **Yes**. If you can't find your Microsoft Entra ID created from Microsoft 365, see [Why don't I see the directory that I want to connect?](#why-not-my-directory). @@ -373,7 +376,7 @@ sections: * You aren't recognized as the [**organization Owner**](../security/look-up-organization-owner.md) to manage directory connections. - * Talk to your Azure AD organization administrator and ask them to make you a member of the organization. It's possible that you're not part of the organization. + * Talk to your Microsoft Entra organization administrator and ask them to make you a member of the organization. It's possible that you're not part of the organization. @@ -387,7 +390,7 @@ sections: - question: | Can I switch to a different directory? answer: | - **Yes**. For more information, see [Switch to another Azure AD](change-azure-ad-connection.md). + **Yes**. For more information, see [Switch to another Microsoft Entra ID](change-azure-ad-connection.md). [!INCLUDE [note-azure-ad-tenant-switch](includes/note-azure-ad-tenant-switch.md)] @@ -396,7 +399,7 @@ sections: - question: | Why and when should I request Support to manually clear my SSH keys? answer: | - When you switch from one Azure AD tenant to another, the underlying identity also changes and any PAT tokens or SSH keys that the user had with their old identity stop working. Any active SSH keys uploaded to the organization aren't deleted as part of the tenant switch process, which may block the user from uploading new keys after the switch. We recommend that users delete all their SSH keys **before** they switch their active directory tenant. We have work in our backlog for automatic deletion of the SSH keys as part of the tenant switch process and in the interim if you're blocked from uploading new keys after tenant switch, we recommend you to contact Support to delete those old SSH keys. + When you switch from one Microsoft Entra tenant to another, the underlying identity also changes and any PAT tokens or SSH keys that the user had with their old identity stop working. Any active SSH keys uploaded to the organization aren't deleted as part of the tenant switch process, which might block the user from uploading new keys after the switch. We recommend that users delete all their SSH keys **before** they switch their active directory tenant. We have work in our backlog to automatically delete the SSH keys as part of the tenant switch process and in the interim if you're blocked from uploading new keys after tenant switch, we recommend you contact Support to delete those old SSH keys. - question: | My alternate credentials don't work anymore. What do I do? @@ -404,35 +407,35 @@ sections: Azure DevOps no longer supports Alternate Credentials authentication since the beginning of March 2, 2020. If you're still using Alternate Credentials, we strongly encourage you to switch to a more secure authentication method (for example, personal access tokens or SSH). [Learn more](https://devblogs.microsoft.com/devops/azure-devops-will-no-longer-support-alternate-credentials-authentication/). - question: | - Some users are disconnected, but they have matching identities in Azure AD. What should I do? + Some users are disconnected, but they have matching identities in Microsoft Entra ID. What should I do? answer: | - - In your Azure DevOps **Organization settings**, select **Azure Active Directory**, and then select **Resolve**. + - In your Azure DevOps **Organization settings**, select **Microsoft Entra ID**, and then select **Resolve**. - ![Select Azure AD and then Resolve](media/shared/azure-ad-select-resolve-for-disconnected-users.png) + ![Select Microsoft Entra ID and then Resolve](media/shared/azure-ad-select-resolve-for-disconnected-users.png) - Match the identities. Select **Next** when you're done. ![Resolve disconnected users](media/shared/resolve-disconnected-users.png) + + - question: | I got an error message when I was resolving disconnections. What should I do? answer: | * Try again. - * You might be a guest in Azure AD. Request that an organization administrator, who is a member of Azure AD, do the mapping. Or, request that an admin of the Azure AD converts you to a member. - - ![Screenshot showing an error when resolving disconnected users.](media/shared/guest-azure-ad-cannot-invite.png) + * You might be a guest in Microsoft Entra ID. Request that an organization administrator, who is a member of Microsoft Entra ID, do the mapping. Or, request that an admin of the Microsoft Entra ID converts you to a member. * If the error message includes a user in your domain, but you don't see them active in your directory, the user likely left your company. Go to the organization user settings to remove the user from your organization. - question: | - When I was trying to invite a new user to my Azure AD, I got a 403 exception. What do I do? + When I was trying to invite a new user to my Microsoft Entra ID, I got a 403 exception. What do I do? answer: | - You may be a guest in Azure AD and don't have the right permission to invite users. Go to **External collaboration settings** in Azure AD and move the "Guests can invite" toggle to **Yes**. Refresh Azure AD and try again. + You might be a guest in Microsoft Entra ID and don't have the right permission to invite users. Go to **External collaboration settings** in Microsoft Entra ID and move the "Guests can invite" toggle to **Yes**. Refresh Microsoft Entra ID and try again. - question: | Will my users keep their existing Visual Studio subscriptions? answer: | - Visual Studio subscription administrators ordinarily assign subscriptions to users' corporate email addresses, so that users can receive welcome email and notifications. If the identity and subscription email addresses match, users can access the benefits of the subscription. As you transition from Microsoft to Azure AD identities, users' benefits still work with their new Azure AD identity. But, the email addresses must match. If the email addresses don't match, your subscription administrator must [reassign the subscription](../billing/csp/buy-vs-app-center.md). Otherwise, users must [add an alternate identity to their Visual Studio subscription](/visualstudio/subscriptions/vs-alternate-identity). + Visual Studio subscription administrators ordinarily assign subscriptions to users' corporate email addresses, so that users can receive welcome email and notifications. If the identity and subscription email addresses match, users can access the benefits of the subscription. As you transition from Microsoft to Microsoft Entra identities, users' benefits still work with their new Microsoft Entra identity. But, the email addresses must match. If the email addresses don't match, your subscription administrator must [reassign the subscription](../billing/csp/buy-vs-app-center.md). Otherwise, users must [add an alternate identity to their Visual Studio subscription](/visualstudio/subscriptions/vs-alternate-identity). - question: | What if I'm required to sign in when I use the people picker? @@ -445,28 +448,24 @@ sections: Clear your browser cache and delete any cookies for the session. Close your browser, and then reopen. - question: | - Once my organization is connected to Azure AD, will it update Azure Boards work items, pull requests, and other pieces where I'm referenced in the system with my new ID? + Once my organization is connected to Microsoft Entra ID, will it update Azure Boards work items, pull requests, and other pieces where I'm referenced in the system with my new ID? answer: | **Yes**, all pieces in the system are updated with the new ID when a user's ID gets mapped from their personal email to their work email. - question: | What if I get a warning about members who will lose access to the organization? answer: | - You can still connect to Azure AD, but try to resolve the mapping issue after you've connected. If you still need help, [contact support](https://developercommunity.visualstudio.com/spaces/21/index.html). - - ![Screenshot showing Azure AD connection warning.](media/shared/connection-warning.png) - - Select the bolded text to see which users are affected. + You can still connect to Microsoft Entra ID, but try to resolve the mapping issue after you connect and select the bolded text to see which users are affected. If you still need help, [contact support](https://developercommunity.visualstudio.com/spaces/21/index.html). - ![Show disconnected users](media/shared/show-disconnected-users.png) + ![Screenshot showing Microsoft Entra connection warning.](media/shared/connection-warning.png) - question: | - With more than 100 members in my Azure DevOps organization, how can I connect to an Azure AD? + With more than 100 members in my Azure DevOps organization, how can I connect to a Microsoft Entra ID? answer: | Currently, you can still connect, but the mapping and invite features that help resolve disconnected users post-connection doesn't work beyond 100. [Contact Support](https://azure.microsoft.com/support/devops/). - question: | - Why is git.exe/Visual Studio failing to authenticate after linking/unlinking from Azure Active Directory? + Why is git.exe/Visual Studio failing to authenticate after linking/unlinking from Microsoft Entra ID? answer: | The tenant cache must be cleared if you're using a GCM version before v1.15.0. Clearing the tenant cache is as easy as deleting the `%LocalAppData%\GitCredentialManager\tenant.cache` file on each machine returning a sign-in error. The GCM automatically recreates and populates the cache file, as needed, on subsequent sign-in attempts. @@ -477,5 +476,5 @@ additionalContent: | ## Related articles - [Configure and customize organization FAQs](faq-configure-customize-organization.yml) - - [User and permissions management FAQs](faq-user-and-permissions-management.yml) + - [Learn about user and permissions management FAQs](faq-user-and-permissions-management.yml) - [Set up Visual Studio FAQs](faq-set-up-vs.yml) diff --git a/docs/organizations/accounts/faq-configure-customize-organization.yml b/docs/organizations/accounts/faq-configure-customize-organization.yml index f146ccdbc65..4ad44b6a9d0 100644 --- a/docs/organizations/accounts/faq-configure-customize-organization.yml +++ b/docs/organizations/accounts/faq-configure-customize-organization.yml @@ -1,54 +1,48 @@ ### YamlMime:FAQ metadata: - title: Create and configure organization FAQs + title: Organization FAQs titleSuffix: Azure DevOps - ms.custom: seodec18 description: Learn the answers to frequently asked questions (FAQs) about creating, deleting, restoring, and configuring your organization in Azure DevOps. ms.subservice: azure-devops-organizations ms.assetid: e0fe24d4-f76b-43af-b0fd-125a7fb39042 ms.topic: faq ms.author: chcomley author: chcomley - ms.date: 08/15/2022 + ms.date: 01/15/2025 monikerRange: '<= azure-devops' -title: Create and configure organization FAQs +title: Organization FAQs summary: | [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - Learn the answers to frequently asked questions (FAQs) about creating and configuring an organization in Azure DevOps. FAQs are grouped by the following subjects: + Learn the answers to frequently asked questions (FAQs) about creating and configuring an organization in Azure DevOps, grouped into the following categories: - - [General](#general-organization-faqs) - - [Create an organization](#create-organization-faqs) - - [Configure an organization](#configure-organization-faqs) - - [Delete or restore an organization](#delete-restore-organization-faqs) + - [General](#general-organization-faqs) + - [Create an organization](#create-organization-faqs) + - [Configure an organization](#configure-organization-faqs) + - [Delete or restore an organization](#delete-restore-organization-faqs) For more information about user and permissions management, see [User and permissions management FAQs](faq-user-and-permissions-management.yml). - sections: - name: General questions: - question: | - Q: What users can join for free? What benefits do users get from joining Azure DevOps? + Q: Which users can join for free, and what benefits do they receive from joining Azure DevOps? answer: | - A: Azure DevOps is free for these users to join: - - * Five users who get [Basic features](https://visualstudio.microsoft.com/team-services/compare-features/), like version control and tools for Agile, Java, and build and release management. - - * Unlimited users who get [Stakeholder features](https://visualstudio.microsoft.com/team-services/compare-features/), like working with your backlog, work items, and queries. - - * Unlimited [Visual Studio subscribers](https://visualstudio.microsoft.com/team-services/compare-features/) who also get Basic features. + A: Get the following benefits from joining Azure DevOps: + + [!INCLUDE [free-tier](../../includes/free-tier.md)] - [Learn what else you get with Azure DevOps](https://visualstudio.microsoft.com/team-services/pricing/). + For more information, see [Azure DevOps pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). - question: | Q: Why won't my browser work with Azure DevOps? answer: | - A: This might happen if you're using an unsupported browser. For the best experience, make sure that you're using a [supported browser](/azure/devops/server/compatibility#supported-browsers). + A: You might be using an unsupported browser. For the best experience, ensure you're using a [supported browser](/azure/devops/server/compatibility#supported-browsers). - question: | Q: Which Visual Studio subscriptions can I use with Azure DevOps? @@ -56,47 +50,38 @@ sections: A: [Find Visual Studio subscriptions that include Azure DevOps](faq-user-and-permissions-management.yml#EligibleMSDNSubscriptions). - question: | - Q: Why am I asked to provide profile details? + Q: How do I sign in to Azure DevOps if I forgot my organization name? answer: | - A: If you're a new user, you can change your profile details. Change your profile details only once. - - 1. Confirm your profile details. - - ![Confirm profile details](media/sign-up-visual-studio-team-services/create-profile-msa.png) - - 2. Continue creating your organization. - - ![Create your organization](media/sign-up-visual-studio-team-services/my-info-new-organization.png) - + A: If you forgot your organization name, [sign in to your Visual Studio profile](https://go.microsoft.com/fwlink/?LinkId=309329), where you can view a list of your organizations. + - question: | - Q: How do I find the region where my organization is located? + Q: How do I find the geography where my organization is located? answer: | - A: [Find your organization's region](./change-organization-location.md). + A: [Find your organization's geography](./change-organization-location.md). - question: | - Q: How do I change my project name, organization location, or process? + Q: How do I change my project name, organization location, or project process? answer: | - A: Change these when you sign up for your organization. - - ![Change organization details](../../media/change-details-standard1.png) - - Azure DevOps uses Agile as the default [process](../../boards/work-items/guidance/choose-process.md) to organize your work. Your organization's default location is based on the closest [Microsoft Azure region](https://azure.microsoft.com/regions) where Azure DevOps is available. For a better experience, select a location that's closest to most users in your organization. - - If a new region or location opens later, you can [change your organization location or region](./change-organization-location.md). You can also select another process, like Scrum, if that works best for you. + A: See the following articles: - ![Rename project, change organization location, or select another process](../../media/change-details-standard2.png) - - If you connected your organization to Azure Active Directory but you belong to multiple directories and want to select a different directory, change your directory here: - - ![Change your directory](../../media/change-details-standard2-with-directory.png) + - [Change your project name](../../organizations/projects/rename-project.md) + - [Change your organization geography](./change-organization-location.md) + - [Change your project process from Agile to Scrum](../../organizations/settings/work/change-process-agile-to-scrum.md) + - [Change your project process from Scrum to Agile](../../organizations/settings/work/change-process-scrum-to-agile.md) + - [Change your project process from Basic to Agile](../../organizations/settings/work/change-process-basic-to-agile.md) ## Create an organization For more information, see [Plan your Azure DevOps organization structure](../../user-guide/plan-your-azure-devops-org-structure.md?view=azure-devops). + + - question: | + Q: Is localization supported in the Azure Devops service? + answer: | + A: Sorry, we don't support localization in the Azure DevOps service. We do support localization in the on-premises version of Azure DevOps. - question: | Q: How many organizations can I create? @@ -115,9 +100,7 @@ sections: - question: | Q: How do I create another organization? answer: | - A: Sign in to your [Visual Studio profile](https://app.vsaex.visualstudio.com/profile/view). - - ![Create another organization.](media/sign-up-visual-studio-team-services/my-info-organization-list.png) + A: [Create an organization](create-organization.md). @@ -126,20 +109,15 @@ sections: answer: | A: Yes, multiple projects help you keep work separate when you have development projects for different teams. Only one project collection is supported. - To create projects, you need project collection administrator or organization owner permissions. For details, see [Create a project](../projects/create-project.md). - - To learn more about projects and when you should or shouldn't add one, see [About projects and scaling your organization](../projects/about-projects.md). + For more information, see the following articles: + - [About projects and scaling your organization](../projects/about-projects.md) + - [Create a project](../projects/create-project.md) - question: | Q: Can I delete a project that I created? answer: | A: Yes, you can [delete a project](../projects/delete-project.md) that you don't use anymore. - - question: | - Q: Where can I find my organization name (URL)? - answer: | - A: [Sign in to your Visual Studio profile](https://go.microsoft.com/fwlink/?LinkId=309329) to find your organization list. - - question: | Q: Can I delete an organization that I don't need anymore? answer: | @@ -148,7 +126,7 @@ sections: - question: | - Q: What's the difference between using a Microsoft account and a work account or school account to sign up? + Q: What's the difference between using a Microsoft account and a work or school account to sign up? answer: | A: Your choice of account type affects how you control access and authenticate users for your organization. @@ -159,19 +137,12 @@ sections: When you sign up with a work or school account: - * Your organization is automatically connected to your directory in Azure Active Directory. + * Your organization is automatically connected to your directory in Microsoft Entra ID. * All users must be members in the connected directory to get access to your organization. * The directory administrator has control over who can join the directory. * You sign in with work or school accounts, or with Microsoft accounts if your company allows that. - To [add users to the directory](/azure/active-directory/active-directory-create-users), you must be a directory administrator. If you can't access, work with your directory administrator to add users. Learn more about [work or school accounts for your organization](/azure/active-directory/sign-up-organization). - - - - - question: | - Q: Can I change the directory after sign-in? - answer: | - A: Yes, see [Disconnect your organization from Azure Active Directory](disconnect-organization-from-azure-ad.md) and [Connect your organization to Azure AD](connect-organization-to-azure-ad.md). + To [add users to the directory](/azure/active-directory/active-directory-create-users), be a directory administrator. If you can't access, work with your directory administrator to add users. Learn more about [work or school accounts for your organization](/azure/active-directory/sign-up-organization). @@ -182,21 +153,26 @@ sections: * Choose **Personal account** if you want to use your Microsoft account with Azure DevOps. In this case, all other users also must sign in with Microsoft accounts. [!INCLUDE [why-cant-sign-in-msa-azuread-account](../../includes/qa-why-cant-sign-in-msa-azuread-account.md)] - + + + + - question: | + Q: Can I change the directory after sign-in? + answer: | + A: Yes, see [Disconnect your organization from Microsoft Entra ID](disconnect-organization-from-azure-ad.md) and [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md). + - question: | Q: How do you store, secure, and protect my data? answer: | - A: Azure DevOps storage features help make sure that your data is available in case of hardware failure, service disruption, or datacenter disasters. Azure DevOps helps protect data from accidental or malicious deletion. - - We follow industry best practices and have enterprise-grade security measures to help protect your code and project data. Also, all communication between your computer and the service takes place over an encrypted HTTPS connection. Learn [how your data is secured and protected](../security/data-protection.md). + A: See the [Data protection overview](../security/data-protection.md). - question: | Q: Do I still own my code and intellectual property? What do you do with my personal information? answer: | - A: Yes, your code and your intellectual property are yours. Please review our [terms of service](https://go.microsoft.com/fwlink/?LinkID=266231) and [privacy policy](https://go.microsoft.com/fwlink/?LinkID=264782). + A: Yes, your code and your intellectual property are yours. Review our [terms of service](https://go.microsoft.com/fwlink/?LinkID=266231) and [privacy policy](https://go.microsoft.com/fwlink/?LinkID=264782). - question: | - Q: Where can I find the Azure DevOps SLA? + Q: Where can I find the Azure DevOps Service Level Agreement (SLA)? answer: | A: You can find it here: [Azure DevOps SLA](https://azure.microsoft.com/support/legal/sla/visual-studio-team-services/v1_2/). @@ -212,27 +188,27 @@ sections: - question: | Q: Why can't I find the user who I want to make the new owner? answer: | - A: You may not find the user for one of the following reasons: + A: You might not find the user for one of the following reasons: * The user isn't in your organization, or the user doesn't have organization access. Learn how to [add a user to your organization](add-organization-users.md). - * The user hasn't created a Visual Studio profile and agreed to the Terms of Service. + * The user didn't create a Visual Studio profile or agree to the Terms of Service. * If you recently added this person to your organization, you might experience a delay before the user appears in the possible organization owners list. - * If your organization uses Azure Active Directory to control access, directory members don't appear in the possible organization owners list until they meet the requirements. For more information, see [Access Azure AD FAQs](faq-azure-access.yml). + * If your organization uses Microsoft Entra ID to control access, directory members don't appear in the possible organization owners list until they meet the requirements. For more information, see [Access Microsoft Entra FAQs](faq-azure-access.yml). - question: | - Q: What if the owner of my organization has left the company/isn't active? + Q: What if the owner of my organization left the company/isn't active? answer: | - A: Azure DevOps Administrators can claim ownership of organizations where the current owner and any members of the Project Collection Administrators group are inactive in the Azure AD tenant that's connected to your organization. For more information, see [Resolve inactive organization owner](resolve-orphaned-organization.md). + A: Azure DevOps Administrators can claim ownership of organizations where the current owner and any members of the Project Collection Administrators group are inactive in the Microsoft Entra tenant connected to your organization. For more information, see [Resolve inactive organization owner](resolve-orphaned-organization.md). - question: | Q: Can I change my organization owner? answer: | - A: Yes. If you are a Project Collection Administrator, you can change the organization owner in your organization settings. For more information, see [Change the organization owner](./change-organization-ownership.md). + A: Yes. If you're a Project Collection Administrator, you can change the organization owner in your organization settings. For more information, see [Change the organization owner](./change-organization-ownership.md). - question: | - Q: Can I change the organization name (URL), too? + Q: Can I change the organization name (URL)? answer: | - A: Only the organization owner can change the URL. If you're the organization owner, learn how to [change the organization URL](./rename-organization.md). + A: Only the organization owner can change the URL. If you're the organization owner, see [Rename your organization](./rename-organization.md). - question: | Q: Can I reverse an organization owner change? @@ -252,14 +228,14 @@ sections: - question: | Q: Why did you ask for extra information when I signed in? answer: | - A: If our Terms of Service have changed since you last signed in, you may need to agree and confirm that your information is up to date. + A: If our Terms of Service changed since you last signed in, you might need to agree and confirm that your information is up to date. - question: | - Q: When I change ownership from myself (as PCA) to a different user, my own account is removed from the PCA group. Is this behavior a bug? + Q: When I change ownership from myself (as PCA) to a different user, my own account gets removed from the PCA group. Is this behavior a bug? answer: | - A: No, this behavior isn't a bug and is how it has been implemented. We hope to address this behavior soon. + A: No, this behavior isn't a bug and is currently by design, although we hope to address this behavior soon. - question: | Q: What makes the organization owner different from other organization users? @@ -268,12 +244,12 @@ sections: - Manage billing in the [Azure portal](https://ms.portal.azure.com/#home) - [Pay for users to access the organization](../billing/buy-basic-access-add-users.md) - - [Pay for additional organization services](../billing/try-additional-features-vs.md) + - [Pay for more organization services](../billing/try-additional-features-vs.md) - [Rename the organization URL](./rename-organization.md) - [Change the organization owner](./change-organization-ownership.md) - [Recover a deleted organization](./recover-your-organization.md) - Project collection administrators (PCAs) can perform all actions done by organization owners, except for recovering a deleted organization. This is a current limitation we're working to resolve. + Project collection administrators (PCAs) can perform all actions done by organization owners, except for recovering a deleted organization, which is a current limitation we're working to resolve. - question: | Q: Why don't I see the organizations that I own after I sign in to my Visual Studio profile on visualstudio.com? @@ -306,7 +282,7 @@ sections: - question: | Q: How do I delete my organization? answer: | - A: See [Delete your organization](delete-your-organization.md), which includes prerequisites and helpful tips. + A: See [Delete your organization](delete-your-organization.md), which includes prerequisites, precautions, and helpful tips. - question: | Q: How do I restore my organization? @@ -321,6 +297,6 @@ additionalContent: | ## Related articles - - [Access with Azure AD FAQs](faq-azure-access.yml) - - [Set up Visual Studio FAQs](faq-set-up-vs.yml) - - [User and permissions management FAQs](faq-user-and-permissions-management.yml) + - [Access with Microsoft Entra FAQ](faq-azure-access.yml) + - [Set up Visual Studio FAQ](faq-set-up-vs.yml) + - [User and permissions management FAQ](faq-user-and-permissions-management.yml) diff --git a/docs/organizations/accounts/faq-set-up-vs.yml b/docs/organizations/accounts/faq-set-up-vs.yml index 4a7f9c70aa0..af279e6359e 100644 --- a/docs/organizations/accounts/faq-set-up-vs.yml +++ b/docs/organizations/accounts/faq-set-up-vs.yml @@ -2,8 +2,7 @@ metadata: title: Set up Visual Studio with Azure DevOps FAQs titleSuffix: Azure DevOps Services - ms.custom: seodec18 - description: Having problems installing Visual Studio, signing in, or handling an expired subscription? Learn answers to these frequently asked questions (FAQs). + description: Having problems installing Visual Studio, signing in, or handling an expired subscription? Learn answers to these frequently asked questions (FAQs). ms.subservice: azure-devops-organizations ms.assetid: 985fcb48-0d9e-44ef-811d-7178df1cb09b ms.topic: faq @@ -48,23 +47,25 @@ sections: answer: | Sign in with a [personal Microsoft account](https://www.microsoft.com/account) or a [work or school account](/azure/active-directory/fundamentals/sign-up-organization) - that's managed by Azure Active Directory. + that's managed by Microsoft Entra ID. - question: | Which versions of Visual Studio can I use with Azure DevOps? answer: | + > [!IMPORTANT] + > While previous versions of Visual Studio are compatible with Azure DevOps, it's a best practice to make sure you are on the latest update of that version and to use [supported versions](/visualstudio/productinfo/vs-servicing#older-versions-of-visual-studio) of Visual Studio whenever possible. + You can use the following versions: - + * Visual Studio 2019 * Visual Studio 2017 * Visual Studio 2015 * Visual Studio 2013 * Visual Studio 2012 * Visual Studio 2010, - which requires [Service Pack 1](https://www.microsoft.com/download/details.aspx?id=29082) - and [KB2662296](https://support.microsoft.com/kb/2662296) + which requires Service Pack 1 and [KB2662296](https://support.microsoft.com/kb/2662296) * Visual Studio 2008 SP1, which requires a [GDR update](https://support.microsoft.com/kb/2673642) To connect to Azure DevOps with Visual Studio 2008 through Visual Studio 2012: @@ -116,6 +117,6 @@ sections: - question: | Related articles answer: | - - [Access with Azure AD FAQs](faq-azure-access.yml) - - [Configure and customize organization FAQs](faq-configure-customize-organization.yml) - - [User and permissions management FAQs](faq-user-and-permissions-management.yml) + - [Access with Microsoft Entra FAQ](faq-azure-access.yml) + - [Configure and customize organization FAQ](faq-configure-customize-organization.yml) + - [User and permissions management FAQ](faq-user-and-permissions-management.yml) diff --git a/docs/organizations/accounts/faq-user-and-permissions-management.yml b/docs/organizations/accounts/faq-user-and-permissions-management.yml index 6c4c94e4f61..3f8b00b1d96 100644 --- a/docs/organizations/accounts/faq-user-and-permissions-management.yml +++ b/docs/organizations/accounts/faq-user-and-permissions-management.yml @@ -2,28 +2,20 @@ metadata: title: User and permissions management FAQs titleSuffix: Azure DevOps - ms.custom: seodec18 + ms.custom: has-azure-ad-ps-ref, azure-ad-ref-level-one-done description: Learn the answers to frequently asked questions (FAQs), like the permissions that are required to manage users and user access, manage Visual Studio subscriptions, and more. ms.subservice: azure-devops-organizations ms.assetid: 7107fb6c-c132-45c2-a0d1-d44e9270e907 ms.topic: faq ms.author: chcomley author: chcomley - ms.date: 07/24/2020 + ms.date: 02/10/2025 monikerRange: '<= azure-devops' title: User and permissions management FAQs summary: | [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - Learn the answers to the following frequently asked questions (FAQs) about user and permissions management in Azure DevOps. FAQs are grouped by the following subjects: - - [General permissions](#general-permissions) - - [Visual Studio subscriptions](#visual-studio-subscriptions) - - [User access](#user-access) - - [Change app access policies](#change-app-access-policies) - - [Leave your organization](#leave-organization) - - [Group-based licensing](#group-based-licensing) - - [Add members to projects](#add-members-to-projects) - + Learn the answers to the following frequently asked questions (FAQs) about user and permissions management in Azure DevOps. We grouped the FAQs by the following subjects. @@ -33,12 +25,12 @@ sections: - question: | Q: What happens if I forget my password? answer: | - A: You can [recover your Microsoft account password](https://account.live.com/ResetPassword.aspx) or [recover your work or school account password](https://passwordreset.microsoftonline.com) if your organization turned on this feature. Otherwise, contact your Azure Active Directory administrator to recover your work or school account. + A: You can [recover your Microsoft account password](https://account.live.com/ResetPassword.aspx) or [recover your work or school account password](https://passwordreset.microsoftonline.com) if your organization turned on this feature. Otherwise, contact your Microsoft Entra administrator to recover your work or school account. - question: | Q: Why can't I manage users? answer: | - A: You must be a member of the Project Collection Administrators group or [organization Owner](../security/look-up-organization-owner.md) to manage users at the organization level. To get added, see [Change permissions at the organization or collection-level](../security/change-organization-collection-level-permissions.md). + A: Be a member of the Project Collection Administrators group or [organization Owner](../security/look-up-organization-owner.md) to manage users at the organization level. To get added, see [Change permissions at the organization or collection-level](../security/change-organization-collection-level-permissions.md). @@ -60,18 +52,16 @@ sections: answer: | A: If you have at least **Basic** access, you can find a member of the **Project Collection Administrators** group in your organization's or collection's settings. - ::: moniker range=">= azure-devops-2019" - For more information, see [Look up a project collection administrator](../security/look-up-project-collection-administrators.md). - - ::: moniker-end - - ::: moniker range="<= tfs-2018" - - For more information, see [Look up a project administrator](../security/look-up-project-administrators.md). - - ::: moniker-end - + + - question: Why can't users access some features? + answer: | + Q: They might need a different [access level](../security/access-levels.md#supported-access-levels) assigned, in addition to permissions granted through security groups. For example, [Stakeholder access](../security/stakeholder-access.md) access level provides partial support to select features, allowing users to view and modify work items, but not to use all features. + + - question: I accidentally removed my permissions and am unable to grant them again. What should I do? + answer: | + A: The only way to resolve this scenario is to [Request an increase in permission levels](../security/request-changes-permissions.md). + - name: Visual Studio subscriptions @@ -79,7 +69,7 @@ sections: - question: | Q: When do I select "Visual Studio/MSDN Subscriber"? answer: | - A: Assign this access level to users who have active, valid [Visual Studio subscriptions](#EligibleMSDNSubscriptions). Azure DevOps automatically recognizes and validates Visual Studio subscribers who have Azure DevOps as a benefit. You need the email address that's associated with the subscription. + A: Assign this access level to users who have active, valid [Visual Studio subscriptions](#EligibleMSDNSubscriptions). Azure DevOps automatically recognizes and validates Visual Studio subscribers who have Azure DevOps as a benefit. You need the email address associated with the subscription. If the user doesn't have a valid, active Visual Studio subscription, they can work only [as a Stakeholder](../../organizations/security/get-started-stakeholder.md). @@ -95,9 +85,9 @@ sections: - question: | - Q: Why won't my Visual Studio subscription validate? + Q: Why doesn't my Visual Studio subscription validate? answer: | - A: See [Why won't Azure DevOps recognize my Visual Studio subscription?](/visualstudio/subscriptions/vs-alternate-identity#faq) + A: See [Why doesn't Azure DevOps recognize my Visual Studio subscription?](/visualstudio/subscriptions/vs-alternate-identity#faq) @@ -113,34 +103,76 @@ sections: answer: | A: If no other access levels are available, users can [work as Stakeholders](../../organizations/security/get-started-stakeholder.md). To restore access, a user must renew their subscription. - + + + - name: GitHub Enterprise + questions: + - question: | + Q: Which GitHub Enterprise customers are eligible for Azure DevOps access? + answer: | + A: GitHub Enterprise Cloud customers who access GitHub and Azure DevOps with the same Entra tenant. Users must sign in using the same identity in GitHub and Azure DevOps. + ![Screenshot shows GitHub Enterprise listed as user's access level in Organization settings, Users page.](media/faq/github-enterprise.png) + + - question: | + Q: Are users using GitHub Enterprise Server detected as having GitHub Enterprise? + answer: | + A: Users of GitHub Enterprise Server are detected if they also have a matching license in the cloud. For more information, see [Syncing license usage between GitHub Enterprise Server and GitHub Enterprise Cloud](https://docs.github.com/enterprise-server@3.15/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud). + + - question: | + Q: What kind of access do GitHub Enterprise users get in Azure DevOps? + answer: | + A: Basic access, which includes all features except Test Plans. For more information, see [Pricing for Azure DevOps](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) + + - question: | + Q: How are GitHub Enterprise users detected? + answer: | + A: Azure DevOps automatically checks if a user has GitHub Enterprise when the user signs in. It can take up to 24 hours for their access level to change to GitHub Enterprise. There are no charges for a user with the GitHub Enterprise access level. + + - question: | + Q: What access level should I select if a user has a GitHub Enterprise license? + answer: | + A: If you know a user has a GitHub Enterprise license, the best option to choose is Stakeholder, to avoid any charges for Basic before the user signs in for the first time + + - question: | + Q: What if a GitHub Enterprise user needs access to Test Plans? + answer: | + A: GitHub Enterprise users who need access to Test Plans can be assigned the Basic + Test Plans access level. + + - question: | + Q: What if a GitHub Enterprise user also has a Visual Studio subscription? + answer: | + A: If a user accessing Azure DevOps has both a GitHub Enterprise and Visual Studio subscription, they get detected as a Visual Studio subscriber. A Visual Studio subscription always gives them the same Basic access, and might provide access to Test Plans, depending on the subscription level. + + + - name: User access questions: + - question: | Q: What does "Last Access" mean in the All Users view? answer: | - A: The value in **Last Access** is the last date a user accessed any resources or services. Accessing Azure DevOps includes using *organizationname*.visualstudio.com directly and using resources or services indirectly. For example, you might use the [Azure Artifacts](https://azure.microsoft.com/services/devops/artifacts/) extension, or you can push code to Azure DevOps from a Git command line or IDE. + A: The value in **Last Access** is the last date a user accessed any resources or services. Accessing Azure DevOps includes using *OrganizationName*.visualstudio.com directly and using resources or services indirectly. For example, you might use the [Azure Artifacts](https://azure.microsoft.com/services/devops/artifacts/) extension, or you can push code to Azure DevOps from a Git command line or IDE. - question: | - Q: Can a user who has paid for Basic access join other organizations? + Q: Can a user who paid for Basic access join other organizations? answer: | - A: No, a user can join only the organization for which the user has paid for Basic access. But a user can join any organization where free users with Basic access are still available. The user can also join as a user with Stakeholder access for free. + A: No, a user can join only the organization for which the user paid for Basic access. But a user can join any organization where free users with Basic access are still available. The user can also join as a user with Stakeholder access for free. - question: | Q: Why can't users access some features? answer: | - A: Make sure that users have the correct [access level](https://visualstudio.microsoft.com/team-services/compare-features/) assigned to them. + A: Make sure that users have the correct access level assigned to them. * Learn [how to manage users and access levels for Azure DevOps](./add-organization-users.md). * Learn [how to change access levels for Azure DevOps Server](../security/change-access-levels.md). - Some features are available only as [extensions](https://visualstudio.microsoft.com/team-services/compare-features/). You need to install these extensions. Most extensions require you to have at least Basic access, not Stakeholder access. Check the extension's description in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops), Azure DevOps tab. + Some features are available only as extensions. You need to install these extensions. Most extensions require you to have at least Basic access, not Stakeholder access. Check the extension's description in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops), Azure DevOps tab. For example, to search your code, you can install the free [Code Search extension](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search), but you need at least Basic access to use the extension. @@ -159,11 +191,11 @@ sections: answer: | A: A user can lose access for the following reasons (although the user can continue to [work as a Stakeholder](../../organizations/security/get-started-stakeholder.md)): - * The user's Visual Studio subscription has expired. Meanwhile, the user can [work as a Stakeholder](../../organizations/security/get-started-stakeholder.md), or you can give the user Basic access until the user renews their subscription. After the user signs in, Azure DevOps restores access automatically. + * The user's Visual Studio subscription expired. Meanwhile, the user can [work as a Stakeholder](../../organizations/security/get-started-stakeholder.md), or you can give the user Basic access until the user renews their subscription. After the user signs in, Azure DevOps restores access automatically. * The Azure subscription used for billing is no longer active. All purchases made with this subscription are affected, including Visual Studio subscriptions. To fix this issue, visit the [Azure account portal](https://portal.azure.com). - * The Azure subscription used for billing was removed from your organization. Learn more about [linking your organization](../billing/set-up-billing-for-your-organization-vs.md). + * The Azure subscription used for billing was removed from your organization. For more information, see [Link your organization](../billing/set-up-billing-for-your-organization-vs.md#set-up-billing). * Your organization has more users with Basic access than the number of users that you're paying for in Azure. Your organization includes five free users with Basic access. If you need to add more users with Basic access, you can [pay for these users](../billing/buy-basic-access-add-users.md). @@ -172,23 +204,32 @@ sections: - question: | - Q: How does my user account inherit permissions from other Azure AD groups? + Q: How does my user account inherit permissions from other Microsoft Entra groups? answer: | - A: If a user is in more than one Azure AD group, a **DENY** permission set in one group applies to the user in all groups the user is in. Because the permission is set to **DENY** for the user at the lowest possible level, the user's usage of the resource is affected in all groups they are in because denial always takes precedence. + A: If a user is in more than one Microsoft Entra group, a **DENY** permission set in one group applies to the user in all groups the user is in. Because the permission is set to **DENY** for the user at the lowest possible level, the user's usage of the resource is affected in all groups they are in because denial always takes precedence. For example, if a user is in the Contributor group and in the Project Administrator group and **DENY** is set for a specific permission in the Contributor group, that permission is denied for the user in the Project Administrator group, too. In this scenario, you can use the **Not set** option. For more information about permissions states, see [Permission states](../security/about-permissions.md?view=azure-devops&tabs=preview-page&preserve-view=true#permission-states). - - - name: Change app access policies for your organization - questions: - question: | - Q: How do personal access tokens differ from alternate authentication credentials? + Q: How do I remove users from Azure DevOps? answer: | - A: Personal access tokens are a more convenient and secure replacement for alternate authentication credentials. You can limit a token's use to a specific lifetime, to an organization, and to [scopes](../../integrate/index.md) of activities that the token authorizes. Learn more about [personal access tokens](use-personal-access-tokens-to-authenticate.md). - + A: See [How to remove users from Azure DevOps](../accounts/delete-organization-users.md). + + - question: | + Q: I added a user to my project. Why can't they see the project? + answer: | + A: Verify the user isn't added to a group where the project-level **View project-level information** permission isn't set or is set to **Deny**. For more information, see [Change project-level permissions](../security/change-project-level-permissions.md). + + - question: | + Q: Why can't guest users search for Microsoft Entra users? + answer: | + A: By default, [Access via Microsoft Entra FAQs. Microsoft Entra guests can't search the Microsoft Entra ID in the manner required by Azure DevOps](../accounts/faq-azure-access.yml#no-identities). + + - name: Change app access policies for your organization + questions: - question: | Q: If I deny access to one authentication method in one organization, does that affect all the organizations that I own? answer: | @@ -201,7 +242,7 @@ sections: - - name: Leave your organization + - name: Organizations questions: - question: | Q: How do I remove myself from an organization when the owner isn't available to remove me? @@ -218,7 +259,12 @@ sections: ![Screenshot showing confirmation for leaving the organization.](media/faq/confirm-removal-from-organization.png) - + + - question: | + Q: Why can't I create an organization? + answer: | + A: Contact your administrator to determine if your organization is using [the Microsoft Entra tenant policy to restrict new organization creation](../accounts/azure-ad-tenant-policy-restrict-org-creation.md). + - name: Group-based licensing questions: - question: | @@ -230,14 +276,14 @@ sections: > ![remove-test-group-group-rule-managing_group-based-licensing](media/faq/remove-test-group-rule.png) - question: | - Q: Will my Azure DevOps or Azure AD group be deleted if I remove its group rule? + Q: Will my Azure DevOps or Microsoft Entra group get deleted if I remove its group rule? answer: | - A: No. Your groups won't be deleted. + A: No. Your groups don't get deleted. - question: | Q: What does the option "Remove from all project level groups" do? answer: | - A: This option removes the Azure DevOps or Azure AD group from any project-level default groups, such as **Project Readers** or **Project Contributors**. + A: This option removes the Azure DevOps or Microsoft Entra group from any project-level default groups, such as **Project Readers** or **Project Contributors**. - question: | Q: What determines the final access level if a user is in more than one group? @@ -247,17 +293,17 @@ sections: See the following examples, showing how the subscriber detection factors into group rules. - **Example 1**: group rule gives me more access + **Example 1**: group rule gives me more access. If I have a Visual Studio Pro subscription and I'm in a group rule that gives me Basic + Test Plans – what happens? Expected: I get Basic + Test Plans because what the group rule gives me is greater than my subscription. - **Example 2**: group rule gives me the same access + **Example 2**: group rule gives me the same access. - I have a Visual Studio Test Pro subscription and I'm in a group rule that gives me Basic + Test Plans – what happens? + I have a Visual Studio Test Pro subscription and I'm in a group rule that gives me Basic + Test Plans what happens? - Expected: I get detected as a Visual Studio Test Pro subscriber, because the access is the same as the group rule, and I'm already paying for the Visual Studio Test Pro, so I wouldn't want to pay again. + Expected: I get detected as a Visual Studio Test Pro subscriber, because the access is the same as the group rule, and I'm already paying for the Visual Studio Test Pro, so I don't want to pay again. @@ -268,7 +314,7 @@ sections: answer: | A: Your organization is free for the first five users with Basic access. You can add unlimited Stakeholders and Visual Studio subscribers for no extra charge. After you assign all five free users with Basic access, you can continue adding Stakeholders and Visual Studio subscribers. - To add six or more users with Basic access, you need to [set up billing in Azure](../billing/set-up-billing-for-your-organization-vs.md). Then, you can [pay for more users who need Basic access](../billing/buy-basic-access-add-users.md), return to your organization, [add these users, and assign them Basic access](add-organization-users.md). When billing is set up, you pay monthly for the extra users' access. And can cancel at any time. + To add six or more users with Basic access, you need to [set up billing in Azure](../billing/set-up-billing-for-your-organization-vs.md#set-up-billing). Then, you can [pay for more users who need Basic access](../billing/buy-basic-access-add-users.md), return to your organization, [add these users, and assign them Basic access](add-organization-users.md). When billing is set up, you pay monthly for the extra users' access. And can cancel at any time. If you need more Visual Studio subscriptions, learn [how to buy subscriptions](../billing/change-azure-subscription.md). @@ -277,9 +323,9 @@ sections: - question: | Q: Why can't some users sign in? answer: | - A: This problem might happen because users must sign in with Microsoft accounts unless your organization controls access with Azure Active Directory (Azure AD). If your organization is connected to Azure AD, users must be directory members to get access. + A: This problem might happen because users must sign in with Microsoft accounts unless your organization controls access with Microsoft Entra ID. If your organization is connected to Microsoft Entra ID, users must be directory members to get access. - If you're an Azure AD Administrator, you can add users to the directory. If you're not an Azure AD Administrator, work with the directory administrator to add them. Learn [about controlling organization access with Azure AD](access-with-azure-ad.md). + If you're a Microsoft Entra Administrator, you can add users to the directory. If you're not a Microsoft Entra Administrator, work with the directory administrator to add them. Learn [about controlling organization access with Microsoft Entra ID](access-with-azure-ad.md). - question: | Q: Why did some users lose access to certain features? @@ -294,51 +340,51 @@ sections: A: Learn [how to delete users](delete-organization-users.md) across all projects in your organization. If you paid for more users but don't need their organization access anymore, you must reduce your paid users to avoid charges. - question: | - Q: Why can't I find members from my connected Azure AD, even though I'm the Azure AD global admin? + Q: Why can't I find members from my connected Microsoft Entra ID, even though I'm the global admin? answer: | - A: You're probably a guest in the Azure AD instance that backs Azure DevOps. By default, Azure AD guests can't search in Azure AD. That's why you aren't finding users in your connected Azure AD to add to your organization. + A: You're probably a guest in the Microsoft Entra instance that backs Azure DevOps. By default, Microsoft Entra guests can't search in Microsoft Entra ID. That's why you aren't finding users in your connected Microsoft Entra ID to add to your organization. - First, check to see if you're an Azure AD guest: + First, check to see if you're a Microsoft Entra guest: - 1. Go to the **Settings** section of your organization. Look at the lower **Azure Active Directory** section. Make a note of the tenant that backs your organization. + 1. Go to the **Settings** section of your organization. Look at the lower **Microsoft Entra ID** section. Make a note of the tenant that backs your organization. 2. Sign in to the new Azure portal, portal.azure.com. Check your user profile in the tenant from step 1. Check the **User type** value shown as follows: ![Check user type in the Azure portal](media/faq/check-user-type-in-Azure-portal.png) - If you're an Azure AD guest, do one of the following steps: + If you're a Microsoft Entra guest, do one of the following steps: - * Have another Azure DevOps admin, who isn't an Azure AD guest, manage the users in Azure DevOps for you. Members of the Project Collection Administrators group inside Azure DevOps can administer users. - * Have the Azure AD admin remove you from the connected Azure AD and readd you. The admin needs to make you an Azure AD member rather than a guest. See [Can Azure AD B2B users be added as members instead of guests?](/azure/active-directory/b2b/user-properties#can-azure-ad-b2b-users-be-added-as-members-instead-of-guests) - * Change the **User Type** of the Azure AD guest by using Azure AD PowerShell. We don't advise using the following process, but it works and allows the user to query Azure AD from Azure DevOps thereafter. + * Have another Azure DevOps admin, who isn't a Microsoft Entra guest, manage the users in Azure DevOps for you. Members of the Project Collection Administrators group inside Azure DevOps can administer users. + * Have the Microsoft Entra admin remove your account from the connected directory and readd it. The admin needs to make you a Microsoft Entra member rather than a guest. See [Can Microsoft Entra B2B users be added as members instead of guests?](/azure/active-directory/b2b/user-properties#can-azure-ad-b2b-users-be-added-as-members-instead-of-guests) + * Change the **User Type** of the Microsoft Entra guest by using Microsoft Graph PowerShell. We don't advise using the following process, but it works and allows the user to query Microsoft Entra ID from Azure DevOps thereafter. - 1. [Download and install Azure AD PowerShell module](/powershell/module/azuread/?view=azureadps-2.0&preserve-view=true). + 1. [Download and install Microsoft Graph PowerShell](/powershell/microsoftgraph/installation). ``` - PS Install-Module -Name AzureAD + PS Install-Module -Name Microsoft Graph ``` 2. Open PowerShell and run the following cmdlets. - a. Connect to Azure AD: + a. Connect to Microsoft Entra ID: ``` - PS Connect-AzureAD + PS Connect-MgGraph -Scopes 'User.Read.All' ``` b. Find the **objectId** of the user: ``` - PS Get-AzureADuser -SearchString "YourUPN" + PS Get-MgUser -Filter "UserPrincipalName eq ''" ``` c. Check the **usertype** attribute for this user to see if they're a guest or member: ``` - PS Get-AzureADUser -objectId This is the result of the previous command + PS Get-MgUser -UserId -Property DisplayName, ID, UserPrincipalName, UserType | Select DisplayName, ID, UserPrincipalName, UserType ``` d. Change the **usertype** from **member** to **guest**: ``` - PS Set-AzureADUser -objectId -UserType Member + PS Update-MgUser -UserID -UserType Member ``` @@ -359,12 +405,22 @@ sections: [!INCLUDE [get-team-services-support](../../includes/qa-get-vsts-support.md)] - + + + - name: Switch between accounts in the Azure portal and Azure DevOps + questions: + - question: | + Q: As an administrator, how can I make it easier to switch between accounts across the Azure portal and Azure DevOps? + answer: | + A: Managing multiple accounts can be cumbersome and time-consuming. To streamline the process, consider the following actions: + - **Use different browsers or profiles:** Use different web browsers or browser profiles for each account to stay signed into multiple accounts simultaneously without switching back and forth. + - **Utilize incognito/private browsing:** Use an incognito or private browsing window to temporarily access a different account without affecting your current session. + - **Single sign-on (SSO):** If supported by your organization, implement single sign-on (SSO) to streamline the sign-in process across Azure services. additionalContent: | ## Related articles - - [Access with Azure AD FAQs](faq-azure-access.yml) - - [Configure and customize organization FAQs](faq-configure-customize-organization.yml) - - [Set up Visual Studio FAQs](faq-set-up-vs.yml) + - [Access with Microsoft Entra ID FAQ](faq-azure-access.yml) + - [Configure and customize organization FAQ](faq-configure-customize-organization.yml) + - [Set up Visual Studio FAQ](faq-set-up-vs.yml) diff --git a/docs/organizations/accounts/get-list-of-organizations-connected-to-azure-active-directory.md b/docs/organizations/accounts/get-list-of-organizations-connected-to-azure-active-directory.md index fc94aa6125e..5d2e1b90678 100644 --- a/docs/organizations/accounts/get-list-of-organizations-connected-to-azure-active-directory.md +++ b/docs/organizations/accounts/get-list-of-organizations-connected-to-azure-active-directory.md @@ -1,35 +1,41 @@ --- -title: Get list of organizations connected to Azure Active Directory +title: Get list of organizations connected to Microsoft Entra ID titleSuffix: Azure DevOps Services -ms.custom: seodec18 -description: Learn how to download a complete list of organizations backed by or connected to Azure Active Directory (Azure AD). +description: Learn how to download a complete list of organizations backed by or connected to Microsoft Entra ID. ms.subservice: azure-devops-organizations ms.assetid: 629a48b6-b2ab-4706-8256-d187c8ed5ce7 ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 04/28/2020 +ai-usage: ai-assisted +ms.date: 10/08/2024 monikerRange: 'azure-devops' --- -# Get list of organizations backed by Azure AD +# Get list of organizations backed by Microsoft Entra ID [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Learn how to download a complete list of organizations backed by an Azure Active Directory (Azure AD) tenant. -On this list, you can find the following information: -- organization IDs -- organization names -- organization URLs -- organization owners +Learn how to download a comprehensive list of organizations backed by a Microsoft Entra ID tenant. This list includes essential information such as: + +- Organization IDs +- Organization names +- Organization URLs +- Organization owners + +By accessing this information, you can efficiently manage and oversee the organizations connected to your Microsoft Entra ID tenant. ## Prerequisites -You must be a member of an Azure DevOps organization [connected to Azure AD.](connect-organization-to-azure-ad.md) +| Category | Requirements | +|--------------|-------------| +|**Organization connection** |Member of an Azure DevOps organization [connected to Microsoft Entra ID](connect-organization-to-azure-ad.md).| ## Get list of organizations -Using any organization backed by your Azure AD, complete the following steps. If you don't have access to an organization, create one by signing in to [Start.VisualStudio.com](https://start.visualstudio.com/) with your Azure AD identity. You can [delete the organization](delete-your-organization.md) when you're done. +#### [Browser](#tab/browser) + +Using any organization backed by your Microsoft Entra ID, complete the following steps. If you don't have access to an organization, create one by signing in to [Start.VisualStudio.com](https://start.visualstudio.com/) with your Microsoft Entra identity. You can [delete the organization](delete-your-organization.md) when you're done. 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). @@ -37,9 +43,39 @@ Using any organization backed by your Azure AD, complete the following steps. If ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) -3. Select **Azure Active Directory**, and then **Download**. +3. Select **Microsoft Entra ID**, and then **Download**. + + :::image type="content" source="media/shared/select-azure-ad-download.png" alt-text="Select Microsoft Entra ID, and then Download"::: + +#### [Azure DevOps CLI](#tab/azure-devops-cli/) + +You can get a list of organizations backed by Microsoft Entra ID by using the [az account list](/cli/azure/devops/user#az-devops-user-add) command. To get started, see [Azure DevOps CLI](../../cli/index.md). + +1. To get a list of Microsoft Entra ID tenants, use the following command: + + ```azurecli + az account list --output table + ``` + + This command lists all the tenants you have access to. + +2. Currently, there's no direct Azure CLI command to list Azure DevOps organizations connected to a specific Microsoft Entra ID tenant. But, you can use the Azure DevOps REST API in combination with the Azure CLI to do so. + + 1. Set the Azure DevOps organization and project: + + ```azurecli + az devops configure --defaults organization=https://dev.azure.com/{My_Organization}/ + ``` + + 2. Use the REST API to list organizations. Ensure you have a personal access token (PAT). You can [generate a PAT from Azure DevOps](use-personal-access-tokens-to-authenticate.md). Use the following command to list projects with an organization: + + ```azurerestapi + az rest --method get --uri https://dev.azure.com/{My_Organization}/_apis/projects?api-version=6.0 --headers "Authorization=Bearer {PAT}" + ``` + + This process should correctly authenticate and retrieve the list or organizations connected to your Microsoft Entra ID. - :::image type="content" source="media/shared/select-azure-ad-download.png" alt-text="Select Azure Active Directory, and then Download"::: +* * * ## Next steps @@ -49,7 +85,7 @@ Using any organization backed by your Azure AD, complete the following steps. If ## Related articles * [Resolve orphaned organization](resolve-orphaned-organization.md) -* [Disconnect from Azure AD](disconnect-organization-from-azure-ad.md) -* [Change Azure AD connection](change-azure-ad-connection.md) +* [Disconnect from Microsoft Entra ID](disconnect-organization-from-azure-ad.md) +* [Change Microsoft Entra connection](change-azure-ad-connection.md) * [Enforce Conditional Access policies](change-application-access-policies.md) -* [Manage access with Azure AD groups](./manage-azure-active-directory-groups.md) +* [Manage access with Microsoft Entra groups](./manage-azure-active-directory-groups.md) diff --git a/docs/organizations/accounts/includes/inform-users-microsoft-entra-change.md b/docs/organizations/accounts/includes/inform-users-microsoft-entra-change.md new file mode 100644 index 00000000000..9409f1e4171 --- /dev/null +++ b/docs/organizations/accounts/includes/inform-users-microsoft-entra-change.md @@ -0,0 +1,36 @@ +--- +ms.topic: include +ms.subservice: azure-devops-organizations +ms.author: chcomley +author: chcomley +--- + +## Inform users of the completed Microsoft Entra change + +When you inform your users of the completed change, provide them with the following tasks to do: + +1. Sign out of Azure DevOps. +2. Clear browser cache. + If you use Visual Studio or the Git command-line too, clear the cache for the [Git Credential Manager](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/blob/master/Docs/Faq.md#q-why-is-gitexe-failing-to-authenticate-after-linkingunlinking-your-visual-studio-team-services-organization-from-azure-active-directory). Delete the *%LocalAppData%\GitCredentialManager\tenant.cache* file on each client machine. +3. Sign in to Azure DevOps using Microsoft Entra ID or work credentials. +4. Reconfigure any personal access tokens (PATs) or SSH keys, if necessary. + + - **PATs:** Complete the steps in [Use personal access tokens](../use-personal-access-tokens-to-authenticate.md). + - **SSH keys:** + 1. In Azure DevOps, open your **profile**, and then select **Security** from the resulting dropdown menu. + + :::image type="content" source="../media/shared/select-security-profile-menu.png" alt-text="Screenshot showing Security selection emphasized."::: + + 2. Select **SSH public keys**, and then select **Add**. + + :::image type="content" source="../media/shared/user-settings-security-ssh.png" alt-text="Screenshot that shows adding an SSH public key."::: + + 3. Enter a description and key data, and then select **Save**. + + :::image type="content" source="../media/shared/add-ssh-public-key-info.png" alt-text="Screenshot showing info dialog for creating SSH key."::: + + 4. Copy your key and put it in a safe place, since you can't view it again. + +5. Rename your Microsoft account (MSA). [Rename your MSA](https://support.microsoft.com/help/11545/microsoft-account-rename-your-personal-account) to a different email that doesn't conflict with your Microsoft Entra identity. Doing so ensures that you aren't prompted to choose between accounts. + +6. (Optional) Adjust your visual Studio (VS) subscription. If the UPN used inside your organization changed, adjust your Visual Studio subscription. You can reassign the subscription to your new UPN, or set that UPN as the alternate account inside the subscription. For more information, see [how to add an alternate account to your subscription](/visualstudio/subscriptions/vs-alternate-identity#add-an-alternate-account-to-your-subscription). diff --git a/docs/organizations/accounts/includes/note-azure-ad-tenant-switch.md b/docs/organizations/accounts/includes/note-azure-ad-tenant-switch.md index 4569708d39f..b9f39d50300 100644 --- a/docs/organizations/accounts/includes/note-azure-ad-tenant-switch.md +++ b/docs/organizations/accounts/includes/note-azure-ad-tenant-switch.md @@ -6,5 +6,4 @@ author: chcomley --- > [!IMPORTANT] -> Users and groups that inherit membership and permissions from an Azure AD group, no longer inherit those permissions after the transfer. Azure AD groups that were added to your Azure DevOps organization don't get transferred and cease to exist in your organization when you change the Azure AD connection. All permissions and membership relationships made with these Azure AD groups also cease to exist after the transfer. Also, note that [group rules](../assign-access-levels-by-group-membership.md) that were enabled on Azure AD groups cease to exist when you change the Azure AD connection. - +> When you change the Microsoft Entra connection, users and groups that inherit membership and permissions from a Microsoft Entra group no longer inherit those permissions. Microsoft Entra groups added to your Azure DevOps organization don't get transferred and cease to exist in your organization. All permissions and membership relationships made with these Microsoft Entra groups also cease to exist after the transfer. Additionally, [group rules](../assign-access-levels-by-group-membership.md) enabled on Microsoft Entra groups cease to exist when you change the Microsoft Entra connection. diff --git a/docs/organizations/accounts/includes/pca-prerequisite.md b/docs/organizations/accounts/includes/pca-prerequisite.md deleted file mode 100644 index 11db27315c5..00000000000 --- a/docs/organizations/accounts/includes/pca-prerequisite.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -ms.topic: include -ms.subservice: azure-devops-organizations -ms.author: chcomley -author: chcomley ---- - -## Prerequisites - -- You must be a member of the [Project Collection Administrators group](../../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. For more information, see [Resolve an orphaned organization](../resolve-orphaned-organization.md). diff --git a/docs/organizations/accounts/manage-azure-active-directory-groups.md b/docs/organizations/accounts/manage-azure-active-directory-groups.md index 0682b41ab8a..45c5d135e47 100644 --- a/docs/organizations/accounts/manage-azure-active-directory-groups.md +++ b/docs/organizations/accounts/manage-azure-active-directory-groups.md @@ -1,42 +1,40 @@ --- -title: Manage access with Azure Active Directory groups +title: Manage access with Microsoft Entra groups titleSuffix: Azure DevOps Services -ms.custom: seodec18 -description: Learn how to control who can access Azure DevOps with Azure Active Directory groups +description: Learn how to control who can access Azure DevOps with Microsoft Entra groups ms.subservice: azure-devops-organizations ms.assetid: 882E6E07-F407-478A-9DCC-9324493CBE11 -ms.topic: conceptual +ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 11/11/2022 +ms.date: 03/17/2025 monikerRange: 'azure-devops' --- -# Access with Azure Active Directory groups +# Manage access with Microsoft Entra groups [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Do you want an easier way to control who can access your team's critical resources and key business assets in Azure DevOps Services? -If you already use Microsoft services like Microsoft 365 or [Azure Active Directory (Azure AD)](https://azure.microsoft.com/services/active-directory/), you can use the same identities with your organization. -[Azure AD works with your organization](access-with-azure-ad.md) to control access and authenticate users. +To control access to your team's critical resources and key business assets in Azure DevOps Services, use Microsoft services like Microsoft 365 or [Microsoft Entra ID](https://azure.microsoft.com/services/active-directory/). [Microsoft Entra ID works with your organization](access-with-azure-ad.md) to control access and authenticate users. -When you organize directory members with [Azure AD groups](/azure/active-directory/fundamentals/active-directory-manage-groups), you can reuse those groups to manage permissions in bulk for your organization. Add those groups to the group that you want. For example, add them to built-in groups like Project Collection Administrators or Contributors, or manually created groups like your project management team. Azure AD group members inherit permissions from the Azure DevOps group, so you don't have to manage group members one at a time. +Organize your directory members with [Microsoft Entra groups](/azure/active-directory/fundamentals/active-directory-manage-groups) and manage permissions in bulk for your organization. Add these groups to built-in groups like Project Collection Administrators or Contributors, or to custom groups like your project management team. Microsoft Entra group members inherit permissions from the Azure DevOps group, so you don't have to manage group members individually. -Not familiar with Azure AD, but want to check it out? Learn more about [Azure AD benefits](/azure/active-directory/fundamentals/active-directory-whatis) -and differences in how you [control organization access with Microsoft accounts or with Azure AD](access-with-azure-ad.md). +For more information on [Microsoft Entra ID benefits](/azure/active-directory/fundamentals/active-directory-whatis) and how to [control organization access with Microsoft accounts or Microsoft Entra ID](access-with-azure-ad.md), see the provided links. > [!NOTE] -> Due to a functional limitation on Microsoft Graph, [service principals](../../integrate/get-started/authentication/service-principal-managed-identity.md) will not appear in any list of Azure AD group members on Azure DevOps. Permissions set on any Azure AD groups will still apply to any service principals in the group that have been added to the organizations, even if they are not displaying on the web UI. +> Due to a functional limitation on Microsoft Graph, [service principals](../../integrate/get-started/authentication/service-principal-managed-identity.md) don't appear in any list of Microsoft Entra group members on Azure DevOps. Permissions set on any Microsoft Entra groups still apply to any service principals in the group that were added to the organizations, even if they aren't displaying on the web UI. ## Prerequisites -* Your organization must be connected to Azure Active Directory. [My organization uses Microsoft accounts only. Can I switch to Azure AD?](faq-azure-access.yml#ChangeMSA). Learn how to [connect your organization to Azure AD](connect-organization-to-azure-ad.md). -* You must be a member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. You must also have at least Basic access, not Stakeholder. -* To create and manage Azure AD groups, you need Azure AD administrator permissions or have the directory administrator delegate those permissions to you in the [Azure portal](https://portal.azure.com). -* Azure AD changes might take up to 1 hour to be visible in Azure DevOps, but you can immediately [reevaluate your permissions](../security/request-changes-permissions.md#refresh-or-re-evaluate-your-permissions). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.
      - Microsoft Entra Administrator in the [Azure portal](https://portal.azure.com).| +|**Access levels**| At least **Basic** access.| -## Add an Azure AD group to an Azure DevOps group + + +## Add a Microsoft Entra group to an Azure DevOps group > [!NOTE] > To enable the preview feature, **Organization Permissions Settings Page v2**, see [Enable preview features](../../project/navigation/preview-features.md). @@ -59,7 +57,7 @@ and differences in how you [control organization access with Microsoft accounts ![Select Members, and then Add](media/user-hub/select-members-add.png) - You [invite guests into Azure AD](https://devblogs.microsoft.com/devops/inviting-directory-guests-to-aad-backed-vsts-accounts/) and into your Azure AD-backed organizations, without waiting for them to accept. This invitation allows you to add those guests to your organization, grant access to projects, assign extensions, and more. + You [invite guests into Microsoft Entra ID](https://devblogs.microsoft.com/devops/inviting-directory-guests-to-aad-backed-vsts-accounts/) and into your Microsoft Entra ID-backed organizations, without waiting for them to accept. This invitation allows you to add those guests to your organization, grant access to projects, assign extensions, and more. 5. Add users or groups, and then **Save** your changes. @@ -82,12 +80,35 @@ and differences in how you [control organization access with Microsoft accounts ![Bulk adds members to a group](media/manage-azure-ad-groups/bulk-add-groups.png) - You [invite guests into Azure AD](https://devblogs.microsoft.com/devops/inviting-directory-guests-to-aad-backed-vsts-accounts/) and into your Azure AD-backed organizations, without waiting for them to accept. This invitation allows you to add those guests to your organization, grant access to projects, assign extensions, and more. + You [invite guests into Microsoft Entra ID](https://devblogs.microsoft.com/devops/inviting-directory-guests-to-aad-backed-vsts-accounts/) and into your Microsoft Entra ID-backed organizations, without waiting for them to accept. This invitation allows you to add those guests to your organization, grant access to projects, assign extensions, and more. 5. Add more users or groups if needed, and then **Save** your changes. * * * +Microsoft Entra ID changes might take up to 1 hour to be visible in Azure DevOps, but you can immediately [reevaluate your permissions](../security/request-changes-permissions.md#refresh-or-reevaluate-your-permissions). + +## Configure just-in-time-access for admin groups + +If you have [Project Collection Administrator](../../user-guide/manage-organization-collection.md) and [Project Administrator](../../user-guide/project-admin-tutorial.md) access, you can modify the configuration of your organization or project. To enhance security for these built-in administrator groups, consider implementing just-in-time access using a Microsoft Entra [Privileged Identity Management (PIM) group](/azure/active-directory/privileged-identity-management/concept-pim-for-groups). This approach allows you to grant elevated permissions only when needed, reducing the risk associated with permanent access. + +### Configure access + +1. [Create a role-assignable group in Microsoft Entra ID](/azure/active-directory/roles/groups-create-eligible?tabs=ms-powershell&branch=main). +2. [Add your Microsoft Entra group to the Azure DevOps group](/azure/devops/organizations/security/add-ad-aad-built-in-security-groups?view=azure-devops&branch=main&tabs=preview-page&preserve-view=true). + +> [!NOTE] +> When you configure just-in-time access using a Microsoft Entra Privileged Identity Management (PIM) group, ensure that any user with elevated access also retains standard access to the organization. This way, they can view the necessary pages and refresh their permissions as needed. + +### Use access + +1. [Activate your access](/azure/active-directory/privileged-identity-management/groups-activate-roles). +2. [Refresh your permissions](../security/request-changes-permissions.md#refresh-or-reevaluate-your-permissions) in Azure DevOps. +3. Take the action requiring administrator access. + +> [!NOTE] +> Users have elevated access in Azure DevOps for up to 1 hour after their PIM group access gets deactivated. + ## Related articles - [Restrict organization creation with tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) diff --git a/docs/organizations/accounts/manage-pats-with-policies-for-administrators.md b/docs/organizations/accounts/manage-pats-with-policies-for-administrators.md index 876cf63a13c..e1c5071ac12 100644 --- a/docs/organizations/accounts/manage-pats-with-policies-for-administrators.md +++ b/docs/organizations/accounts/manage-pats-with-policies-for-administrators.md @@ -6,7 +6,8 @@ ms.subservice: azure-devops-organizations ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 03/29/2023 +ai-usage: ai-assisted +ms.date: 10/24/2024 monikerRange: 'azure-devops' --- @@ -14,87 +15,85 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -You can limit the creation, scope, and lifespan of new or renewed personal access tokens (PATs) for users in Azure DevOps by enabling Azure Active Directory (Azure AD) policies. You can also manage automatic revocation of leaked PATs. Learn the default behavior for each policy in its own section of this article. +This article provides guidance on how to use Microsoft Entra policies to manage personal access tokens (PATs) in Azure DevOps. It explains how to limit the creation, scope, and lifespan of new or renewed PATs, and how to handle the automatic revocation of leaked PATs. Each section details the default behavior of the respective policies, helping administrators effectively control and secure PAT usage within their organization. > [!IMPORTANT] -> Existing PATs, created via both the UI and APIs, apply per the remainder of their lifespan. Update your existing PATs to comply with the new restriction, and then they can be successfully renewed. +> Existing PATs, created through both the UI and APIs, remain valid for the rest of their lifespan. Update your existing PATs to comply with the new restrictions to ensure successful renewal. ## Prerequisites -- Your organization must be [linked to Azure AD](connect-organization-to-azure-ad.md). -- You must be an [Azure DevOps Administrator in Azure AD](/azure/active-directory/roles/permissions-reference) to manage your organization policies. +| Category | Requirements | +|--------------|-------------| +|**Organization connection**| Your organization's [linked to Microsoft Entra ID](connect-organization-to-azure-ad.md).| +|**Permissions** | [Azure DevOps Administrator in Microsoft Entra ID](/azure/active-directory/roles/permissions-reference). To check your role, sign in to the [Azure portal](https://ms.portal.azure.com/#home), and go to **Microsoft Entra ID** > **Roles and administrators**. If you're not an Azure DevOps administrator, you can't see the policies. Contact your administrator, if necessary.| -To check your role, sign in to the [Azure portal](https://ms.portal.azure.com/#home), and then choose **Azure Active Directory** > **Roles and administrators**. If you're not an Azure DevOps administrator, contact your administrator. +[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] ## Restrict creation of global PATs -The Azure DevOps Administrator in Azure AD restricts users from creating global PATs. Global tokens apply to all accessible organizations, rather than a single organization. Enabling this policy means that new PATs must be associated with specific Azure DevOps organizations. By default, this policy is set to *off*. +The Azure DevOps Administrator in Microsoft Entra can restrict users from creating global Personal Access Tokens (PATs), which apply to all accessible organizations rather than a single organization. When this policy is enabled, new PATs must be associated with specific Azure DevOps organizations. By default, this policy is set to *off*. 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Choose ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. +2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - ![Choose the gear icon, Organization settings](../../media/settings/open-admin-settings-vert.png) + ![Screenshot showing Choose the gear icon, Organization settings.](../../media/settings/open-admin-settings-vert.png) -3. In the Azure Active Directory tab, find the *Restrict global personal access token creation* policy and move the toggle to *on*. +3. Select **Microsoft Entra**, find the *Restrict global personal access token creation* policy and move the toggle *on*. :::image type="content" source="media/policies/restrict-global-pat-creation-policy-toggle-on.png" alt-text="Screenshot of toggle moved to on position for Restrict global PAT creation policy."::: ## Restrict creation of full-scoped PATs -The Azure DevOps Administrator in Azure AD restricts users from creating full-scoped PATs. Enabling this policy means new PATs must be limited to a specific custom defined set of scopes. By default, this policy is set to *off*. +The Azure DevOps Administrator in Microsoft Entra can restrict users from creating full-scoped PATs. Enabling this policy requires new PATs to be limited to a specific, custom-defined set of scopes. By default, this policy is set to *off*. 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Choose ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. +2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - ![Choose the gear icon, Organization settings](../../media/settings/open-admin-settings-vert.png) - -3. In the Azure Active Directory tab, find the *Restrict full-scoped personal access token creation *policy and move the toggle to *on*. +3. Select **Microsoft Entra**, find the *Restrict full-scoped personal access token creation* policy and move the toggle *on*. :::image type="content" source="media/policies/restrict-full-scoped-pat-creation-policy-toggle-on.png" alt-text="Screenshot of toggle moved to on position for the Restrict full-scoped PAT creation policy."::: ## Set maximum lifespan for new PATs -The Azure DevOps Administrator in Azure AD defines the maximum lifespan of a PAT. The maximum lifespan for new tokens can be specified in number of days. By default, this policy is set to *off*. +The Azure DevOps Administrator in Microsoft Entra ID can define the maximum lifespan of a PAT, specifying it in days. By default, this policy is set to *off*. 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Choose ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - - ![Choose the gear icon, Organization settings](../../media/settings/open-admin-settings-vert.png) +2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. -3. In the Azure Active Directory tab, find the *Enforce maximum personal access token lifespan* policy and move the toggle to *on*. +3. Select **Microsoft Entra**, find the *Enforce maximum personal access token lifespan* policy and move the toggle *on*. :::image type="content" source="media/policies/enforce-maximum-pat-lifespan-policy-toggle-on.png" alt-text="Screenshot of toggle moved to on position for Enforce maximum PAT lifespan policy."::: 4. Enter the number of maximum days, and then select **Save**. -## Add Azure AD users or groups to the allowlist + + +## Add Microsoft Entra users or groups to the allowlist > [!WARNING] -> We recommend using groups with your tenant policy allow list(s). If you use a named user, be aware that a reference to the named user's identity will reside in the United States, Europe (EU), and Southeast Asia (Singapore). +> We recommend using groups for your tenant policy allowlists. If you use a named user, a reference to their identity resides in the United States, Europe (EU), and Southeast Asia (Singapore). -Users or groups on the allowlist are exempt from the restrictions and enforcements created by these policies when they're turned on. Select **Add AAD user or group** to add the user or group to the list, and then select **Add**. Each policy has its own allowlist. If a user is on the allowlist for one policy, any other activated policies still apply. In other words, if you want a user to be exempt from all policies, you should add them to each allowlist. +Users or groups on the allowlist are exempt from the restrictions and enforcements of these policies when enabled. To add a user or group, select **Add Microsoft Entra user or group**, then select **Add**. Each policy has its own allowlist. If a user is on the allowlist for one policy, other activated policies still apply. Therefore, to exempt a user from all policies, add them to each allowlist. ## Revoke leaked PATs automatically -The [Azure DevOps Administrator in Azure AD](azure-ad-tenant-policy-restrict-org-creation.md#prerequisites) can manage the policy that automatically revokes leaked PATs. This policy applies to all PATs within all organizations linked to your Azure AD tenant. By default, this policy is set to *on*. If Azure DevOps PATs get checked into public GitHub repositories, they're automatically revoked. +The [Azure DevOps Administrator in Microsoft Entra ID](azure-ad-tenant-policy-restrict-org-creation.md#prerequisites) can manage the policy that automatically revokes leaked PATs. This policy applies to all PATs within organizations linked to your Microsoft Entra tenant. By default, this policy is set to *on*. If Azure DevOps PATs are checked into public GitHub repositories, they're automatically revoked. > [!WARNING] -> If you disable this policy, any PATs that get checked into public GitHub repositories will remain and could compromise your Azure DevOps organization and data, putting your applications and services at significant risk. With the policy disabled and feature turned off, you still receive an email notification when we find your leaked PAT, but we don't revoke it. +> Disabling this policy means any PATs checked into public GitHub repositories remain active, potentially compromising your Azure DevOps organization and data, and putting your applications and services at significant risk. Even with the policy disabled, you still receive an email notification if a PAT is leaked, but it isn't revoked automatically. ### Turn off automatic revocation of leaked PATs 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Choose ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - - ![Choose the gear icon, Organization settings](../../media/settings/open-admin-settings-vert.png) +2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. -3. In the Azure Active Directory tab, find the *Automatically revoke leaked personal access tokens* policy and move the toggle to *off*. +3. Select **Microsoft Entra**, find the *Automatically revoke leaked personal access tokens* policy and move the toggle to *off*. -The policy is disabled and any PATs that get checked into public GitHub repositories remain. +The policy is disabled and any PATs checked into public GitHub repositories remain active. ## Next steps @@ -103,6 +102,6 @@ The policy is disabled and any PATs that get checked into public GitHub reposito ## Related articles -- [Restrict organization creation with Azure AD tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) +- [Restrict organization creation with Microsoft Entra tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) - [Use personal access tokens to authenticate](use-personal-access-tokens-to-authenticate.md) -- [Get list of organizations connected to Azure AD](get-list-of-organizations-connected-to-azure-active-directory.md) +- [Get list of organizations connected to Microsoft Entra ID](get-list-of-organizations-connected-to-azure-active-directory.md) diff --git a/docs/organizations/accounts/manage-personal-access-tokens-via-api.md b/docs/organizations/accounts/manage-personal-access-tokens-via-api.md index cf900efad0d..a10e3a057c4 100644 --- a/docs/organizations/accounts/manage-personal-access-tokens-via-api.md +++ b/docs/organizations/accounts/manage-personal-access-tokens-via-api.md @@ -6,7 +6,7 @@ ms.subservice: azure-devops-security ms.custom: devx-track-python ms.topic: how-to ms.reviewer: wonga -ms.date: 12/30/2020 +ms.date: 10/24/2024 monikerRange: 'azure-devops' --- @@ -14,124 +14,106 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -When you're dealing with a large set of personal access tokens (PATs) you own, it may become complex to manage the maintenance of these tokens using UI alone. +When you own a large set of [personal access tokens (PATs)](use-personal-access-tokens-to-authenticate.md), it might become complex to manage the maintenance of these tokens using the UI alone. -With the PAT Lifecycle Management API, you can easily manage the PATs associated with your organizations using automated processes. This rich set of APIs enables you to manage the PATs you own, allowing you to create new personal access tokens and renew or expire existing personal access tokens. +With the PAT Lifecycle Management API, you can easily manage the PATs associated with your organizations using automated processes. This [rich set of APIs](/rest/api/azure/devops/tokens) lets you manage your PATs, allowing you to create new PATs and renew or expire existing PATs. -In this article, we'll show you how to configure an application that authenticates with an Azure Active Directory (Azure AD) token and makes calls with the PAT Lifecycle API. If you'd like to just see the full list of available endpoints, [view the API reference here](/rest/api/azure/devops/tokens). +[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] -## Prerequisites - -To use the API, you must authenticate with an Azure AD token. Learn more on how to do this in the following [authentication section](#authenticate-with-azure-active-directory-azure-ad-tokens). +In this article, we show you how to configure an application that [authenticates with a Microsoft Entra token](../../integrate/get-started/authentication/entra-oauth.md) and makes calls with the PAT Lifecycle API. -In order to do so, a few prerequisites must be met: - -* You must [have an Azure AD tenant with an active Azure subscription.](/azure/active-directory/develop/quickstart-create-new-tenant) -* Depending on your tenant's security policies, your application may need to be granted permissions to access resources in the organization. At this moment, the only way to proceed with using this app in this tenant is to ask an admin to grant permission to the app before you can use it. +> [!IMPORTANT] +> You can't use service principals or managed identities to create or revoke PATs. -## Authenticate with Azure Active Directory (Azure AD) tokens +## Prerequisites -Unlike other Azure DevOps Services APIs, users must provide an [Azure AD access token](/azure/active-directory/develop/access-tokens) to use this API instead of a PAT token. Azure AD tokens are a safer authentication mechanism than using PATs. Given this API’s ability to create and revoke PATs, we want to ensure that such powerful functionality is given to allowed users only. +| Category | Requirements | +|--------------|-------------| +|Unlike other Azure DevOps Services APIs, users must provide a [Microsoft Entra access token](../../integrate/get-started/authentication/entra-oauth.md) to use this API. Given this API’s ability to create and revoke PATs, we want to ensure that such powerful functionality is available only to [safer Microsoft Entra tokens](../../integrate/get-started/authentication/entra.md). | -In order to acquire and refresh Azure AD access tokens, you must: +To acquire and refresh Microsoft Entra access tokens: -* [Have an Azure AD tenant with an active Azure subscription](/azure/active-directory/develop/quickstart-create-new-tenant) -* [Register an application in their Azure AD tenant](/azure/active-directory/develop/quickstart-register-app) +* [Have a Microsoft Entra tenant with an active Azure subscription](/azure/active-directory/develop/quickstart-create-new-tenant) +* [Register an application in their Microsoft Entra tenant](/azure/active-directory/develop/quickstart-register-app) * [Add Azure DevOps permissions to the application](/azure/active-directory/develop/quickstart-configure-app-access-web-apis) +* Get consent from tenant admin: Depending on your tenant's security policies, your application might need permissions to access resources in the organization. Request a tenant administrator to grant permission to the app to use it within your tenant. > [!IMPORTANT] -> "On-behalf-of application" solutions (such as the “client credential” flow) and any authentication flow that does not issue an Azure AD access token is not valid for use with this API. If multi-factor authentication is enabled in your Azure AD tenant, you must definitely use the ["authorization code” flow](/azure/active-directory/develop/v2-oauth2-auth-code-flow). - -> [!CAUTION] -> Having an Azure AD tenant with an active Azure subscription is a prerequisite for using this API. - -Once you have an application with a working authentication flow for handling Azure AD tokens, you can use these tokens to make calls to the PAT Lifecycle Management API. - -In order to call the API directly, you need to provide an Azure AD access token as a `Bearer` token in `Authorization` header of your request. -To see the examples and a full list of the available requests, refer to the [PAT API reference](/rest/api/azure/devops/tokens) +> "On-behalf-of application" solutions (such as the “client credential” flow) and any authentication flow that does not issue a Microsoft Entra access token is not valid for use with this API. If multifactor authentication is enabled in your Microsoft Entra tenant, you must definitely use the ["authorization code” flow](/azure/active-directory/develop/v2-oauth2-auth-code-flow). -In the following section, we show you how to create an app that authenticates a user with an Azure AD access token using the MSAL library and calls our PAT Lifecycle Management API. +Once you have an application with a working authentication flow for handling Microsoft Entra tokens, you can use these tokens to make calls to the PAT Lifecycle Management API. -The Microsoft Authentication Library (MSAL) includes multiple compliant authentication flows you can use within your app for acquiring and refreshing Azure AD tokens. A complete list of MSAL flows can be found under [Microsoft Authentication Library “authentication flows” documentation](/azure/active-directory/develop/msal-authentication-flows). A guide to choosing the right authentication method for your application can be found under [Choosing the right authentication method](../../integrate/get-started/authentication/authentication-guidance.md) for Azure DevOps. +To call the API directly, provide a Microsoft Entra access token as a `Bearer` token in `Authorization` header of your request. +For more information and a full list of the available requests, see the [PAT API reference.](/rest/api/azure/devops/tokens) -Follow either one of the two examples to get started: - -* [Clone our sample Python Flask app](#clone-our-python-flask-web-app) and configure it with your tenant and ADO organization -* [Generate a sample application in the Azure portal](#generate-a-quickstart-azure-portal-application) for your language of choice and configure it for the PAT Lifecycle Management API +In the following section, we show how to create an app that authenticates a user with a Microsoft Entra access token. The app uses the [Microsoft Authentication Library (MSAL)](/entra/identity-platform/msal-overview) and calls our PAT Lifecycle Management API. ## Clone our Python Flask web app -We've provided you with a [sample Python Flask web application for this API that you can download on GitHub](https://github.com/microsoft/azure-devops-auth-samples/tree/master/PersonalAccessTokenAPIAppSample) and can be configured to use with your Azure AD tenant and Azure DevOps organization. The sample application uses the MSAL authentication code flow to acquire an Azure AD access token. +We provided you with a [sample Python Flask web application for this API that you can download on GitHub](https://github.com/microsoft/azure-devops-auth-samples/tree/master/PersonalAccessTokenAPIAppSample) and configure to use with your Microsoft Entra tenant and Azure DevOps organization. The sample application uses the [MSAL authorization code flow](/entra/identity-platform/msal-authentication-flows#authorization-code) to acquire a Microsoft Entra access token. > [!IMPORTANT] > We recommend getting started with the sample Python Flask web application on GitHub, but if you prefer to use a different language or application type, use the [Quickstart option](#generate-a-quickstart-azure-portal-application) to recreate an equivalent test application. -Once you've cloned the sample app, follow the instructions in the repo’s README. The README explains how to register an application in your Azure AD tenant, configure the sample to use your Azure AD tenant, and run your cloned app. +Once you clone the sample app, follow the instructions in the repo’s README. The README explains how to register an application in your Microsoft Entra tenant, configure the sample to use your Microsoft Entra tenant, and run your cloned app. ## Generate a Quickstart Azure portal application -Instead, you can generate a sample app with the generated MSAL code using the **Quickstart** option on the application's page in [Azure portal](https://portal.azure.com/). The Quickstart test application follows the authorization code flow, but does so with a Microsoft Graph API endpoint. Users will need to update the application's configuration to point to the endpoint for the PAT Lifecycle Management API. - -To follow this approach, follow the **Quickstarts** instructions for the application type of your choice on the [Azure AD Develop docs homepage](/azure/active-directory/develop/). We will walk through an example where we've done this for a Python Flask Quickstart app. +Instead, you can generate a sample app with the generated MSAL code using the **Quickstart** option on the application's page in [Azure portal](https://portal.azure.com/). The Quickstart test application follows the authorization code flow, but does so with a Microsoft Graph API endpoint. Users need to update the application's configuration to point to the endpoint for the PAT Lifecycle Management API. +To follow this approach, follow the **Quickstarts** instructions for the application type of your choice on the [Microsoft Entra ID Develop docs homepage](/azure/active-directory/develop/). We walk through the following example with a [Python Flask Quickstart app](#configure-a-quickstart-application). -#### Example: Get started with a Python Flask Quickstart application -1. Once you've registered your application in an Azure AD tenant that has an active Azure subscription, navigate to your registered application under **Azure Active Directory** -> **App Registrations** in the [Azure portal](https://portal.azure.com/). +1. Once you register your application in a Microsoft Entra tenant with an active Azure subscription, navigate to your registered application under **Microsoft Entra ID** -> **App Registrations** in the [Azure portal](https://portal.azure.com/). - ![Open "Azure Active Directory" -> "App Registrations"](./media/manage-personal-access-tokens-via-api/step-1-azure-ad-app-registrations.png) + ![Screenshot shows opened Microsoft Entra ID, App Registrations.](./media/manage-personal-access-tokens-via-api/step-1-azure-ad-app-registrations.png) 2. Select your application and navigate to **API Permissions**. - - ![Select your application and navigate to "API Permissions"](./media/manage-personal-access-tokens-via-api/step-2-api-permissions.png) -3. Select **Add a permission** and select **Azure DevOps** -> check **user_impersonation** -> select **Add permissions**. - - ![Add the "Azure DevOps" -> "user_impersonation" permission](./media/manage-personal-access-tokens-via-api/step-3-add-azure-devops-permissions.png) + ![Screenshot shows selecting an application and navigating to API Permissions.](./media/manage-personal-access-tokens-via-api/step-2-api-permissions.png) + +3. Select **Add a permission** and select **Azure DevOps** -> select the appropriate scopes you need. In this case, the PAT Lifecycle Management APIs only support **user_impersonation**, but other APIs may request different more [granular scopes](../../integrate/get-started/authentication/oauth.md#scopes) that you can find on [each API's individual reference page](/rest/api/azure/devops/). Once all the scopes are selected, click **Add permissions**. + + ![Screenshot shows add the Azure DevOps, user_impersonation permission.](./media/manage-personal-access-tokens-via-api/step-3-add-azure-devops-permissions.png) + +4. Select **Quickstart**. -4. Select **Quickstart** from the left navigation panel. - 5. Select your application type: for Python Flask, select **Web application**. -6. Select your application platform. For this tutorial, select "Python". - -7. Make sure you've met the necessary prerequisites, then allow Azure portal to make the necessary changes to configure your application. The **reply URL** will be the redirect URL that was set at application creation + “/getAToken”. +6. Select your application platform. For this tutorial, select **Python**. + +7. Make sure you meet the necessary prerequisites, then allow Azure portal to make the necessary changes to configure your application. The **reply URL** is the redirect URL that was set at application creation + “/getAToken”. - ![Allow the Azure portal to make the necessary changes to configure your application](./media/manage-personal-access-tokens-via-api/step-7-allow-portal-configuration.png) + ![Screenshot shows allowing the Azure portal to make the necessary changes to configure your application.](./media/manage-personal-access-tokens-via-api/step-7-allow-portal-configuration.png) 8. Download the Quickstart application and extract the files. - ![Download the Quickstart application and extract the files](./media/manage-personal-access-tokens-via-api/step-8-download-and-extract.png) + ![Screenshot shows downloading the Quickstart application and extracting the files.](./media/manage-personal-access-tokens-via-api/step-8-download-and-extract.png) -9. Install the application requirements and run the application to ensure you have all necessary dependencies. The application is initially configured to hit an endpoint in the Microsoft Graph API. Learn how to change this endpoint to the PAT Lifecycle Management API base endpoint by following the configuration instructions in the following section. +9. Install the application requirements and run the application to ensure you have all necessary dependencies. The application is initially configured to hit an endpoint in the Microsoft Graph API. Learn how to change this endpoint to the PAT Lifecycle Management API base endpoint by following the configuration instructions in the following section. - ![Install the application requirements and run the application to ensure you have all necessary dependencies](./media/manage-personal-access-tokens-via-api/step-9-install-and-run.png) - + ![Screenshot shows installing the application requirements and running the application.](./media/manage-personal-access-tokens-via-api/step-9-install-and-run.png) ### Configure a Quickstart application -Once the user has downloaded and installed the Quickstart application, it will be configured to use a test API endpoint from Microsoft Graph. We'll need to modify the generated configuration file to have it call the PAT Lifecycle Management API instead. - +Once the user downloads and installs the Quickstart application, it gets configured to use a test API endpoint from Microsoft Graph. Modify the generated configuration file to have it call the PAT Lifecycle Management API instead. > [!TIP] > We use collection and organization interchangeably in these docs. If a configuration variable needs a collection name, please replace it with your organization name. +Do the following tasks: -To do so, we need to do a few things: 1. Update the **ENDPOINT** configuration variable to `https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview` for the PAT Lifecycle Management APIs 2. Update the **SCOPE** configuration variable to **"499b84ac-1321-427f-aa17-267ca6975798/.default"** to refer to the Azure DevOps resource and all of its scopes. -The following example will show you how we did this configuration for the Quickstart Python Flask application we generated through the Azure portal in the previous section. +The following example shows you how we did this configuration for the Quickstart Python Flask application we generated through the Azure portal in the previous section. Make sure you follow instructions to secure your client secret, which is initially inserted in plain-text into the application configuration file. As a best practice, remove the plain-text variable from the configuration file and use an environment variable or Azure KeyVault to secure their application's secret. -Instead, you can choose to use a certificate instead of a client secret. Using certificates is the recommended option if the application will eventually be used in production. The instructions for using a certificate can be found in the final step of the Quickstart application setup. - +Instead, you can choose to use a certificate instead of a client secret. Using certificates is the recommended option if the application gets used in production. The instructions for using a certificate can be found in the final step of the Quickstart application setup. > [!CAUTION] > Never leave a plain-text client secret in production application code. - -#### Example: Configure a Python Flask Quickstart application for the PAT lifecycle management API -1. Once you've downloaded your Quickstart application, installed its dependencies, and tested that it runs in your environment, open the `app_config.py` file in your editor of choice. The file should resemble the following code snippet; for clarity, comments referencing the default Microsoft Graph API configuration have been removed: +1. Once you download your Quickstart application, install its dependencies, and test that it runs in your environment, open the `app_config.py` file in your editor of choice. The file should resemble the following code snippet; for clarity, comments referencing the default Microsoft Graph API configuration were removed: ```python import os @@ -175,8 +157,7 @@ Instead, you can choose to use a certificate instead of a client secret. Using c # In a production app, we recommend you use a more secure method of storing your secret. ``` - -3. Change the `ENDPOINT` variable to your Azure DevOps collection URL and API endpoint. For example, for a collection named "testCollection", the value would be: +3. Change the `ENDPOINT` variable to your Azure DevOps collection URL and API endpoint. For example, for a collection named "testCollection," the value would be: ```python # Fill in the url to the user's ADO collection + the PAT lifecycle management API endpoint here @@ -184,19 +165,18 @@ Instead, you can choose to use a certificate instead of a client secret. Using c ENDPOINT = 'https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview' ``` - For a collection named "testCollection", this endpoint would be: + For a collection named "testCollection," this endpoint would be: ```python ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview' ``` - -4. Change the `SCOPE` variable to reference the Azure DevOps API resource; the character string is the resource ID for the Azure DevOps API, and the “.default” scope refers to all scopes for that resource ID. +4. Change the `SCOPE` variable to reference the Azure DevOps API resource; the character string is the resource ID for the Azure DevOps API, and the `.default` scope refers to all scopes for that resource ID. ```python SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"] ``` -5. If your application is configured for a specific tenant (rather than the multi-tenant configuration), use the alternate value for the `AUTHORITY` variable, adding the specific tenant name in "Enter_the_Tenant_Name_Here". +5. If your application is configured for a specific tenant (rather than the multitenant configuration), use the alternate value for the `AUTHORITY` variable, adding the specific tenant name in "Enter_the_Tenant_Name_Here." ```python # For single-tenant app: @@ -206,8 +186,7 @@ Instead, you can choose to use a certificate instead of a client secret. Using c AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here" ``` - -6. Verify that the final `app_config.py` file matches the following, with your CLIENT_ID, tenant ID, and collection URL. For security reasons, ensure that the CLIENT_SECRET has been moved to an environment variable, Azure KeyVault, or swapped with a certificate for your registered application: +6. Verify that the final `app_config.py` file matches the following, with your CLIENT_ID, tenant ID, and collection URL. For security reasons, ensure that the CLIENT_SECRET was moved to an environment variable, Azure KeyVault, or swapped with a certificate for your registered application: ```python import os @@ -234,47 +213,34 @@ Instead, you can choose to use a certificate instead of a client secret. Using c # Specifies the token cache should be stored in server-side session ``` -6. Rerun the application to test that you can GET all PAT tokens for the requesting user. Once you've verified that you have, feel free to modify the contents of `'app.py'` and the `'ms-identity-python-webapp-master\templates'` directory to support sending requests to the rest of the PAT lifecycle management API endpoints. For an example of a Python Flask Quickstart application that has been modified to support requests to all PAT lifecycle management API endpoints, [see this sample repo on GitHub](https://github.com/microsoft/azure-devops-auth-samples/tree/master/PersonalAccessTokenAPIAppSample). - - -## Automatically refresh an Azure AD access token -Once the application is configured correctly and the user has acquired an access token, the token can be used for up to an hour. The MSAL code provided in both examples above will automatically refresh the token once it expires. Refreshing the token prevents the user from needing to log in again and acquire a new authorization code. However, users may need to log in again after 90 days once their refresh token expires. - +7. Rerun the application to test that you can GET all PAT tokens for the requesting user. Once verified, you can modify the contents of `'app.py'` and the `'ms-identity-python-webapp-master\templates'` directory to support sending requests to the rest of the PAT lifecycle management API endpoints. For an example of a Python Flask Quickstart application that was modified to support requests to all PAT lifecycle management API endpoints, [see this sample repo on GitHub](https://github.com/microsoft/azure-devops-auth-samples/tree/master/PersonalAccessTokenAPIAppSample). -## Explore PAT Lifecycle Management API’s -In the above GitHub sample application and Quickstart applications, the application has been pre-configured to make requests with the Azure AD tokens you've acquired. -To learn more about the endpoints, what parameters they accept, and what is returned in responses, see the [API Reference docs](/rest/api/azure/devops/tokens/pats). + +## Automatically refresh a Microsoft Entra access token +Once the application is configured correctly and the user acquired an access token, the token can be used for up to an hour. The MSAL code provided in both previous examples automatically refreshes the token once it expires. Refreshing the token prevents the user from needing to sign in again and acquire a new authorization code. However, users might need to sign in again after 90 days once their refresh token expires. -## FAQ +## Frequently asked questions (FAQs) -### Q: Why do I need to authenticate with an Azure AD token? Why is a PAT not enough? -**A:** With this PAT Lifecycle Management API, we've opened up the ability to create new PATs and revoke existing PATs. In the wrong hands, this API could be used by malicious actors to create multiple entry points into your organization’s ADO resources. By enforcing Azure AD authentication, we hope to have this powerful API be more secure against this unauthorized usage. +#### Q: Can I get an example of this sample application for another language/framework/application type? +If you have a request for an example, head over to our [Dev Community](https://developercommunity.visualstudio.com/search?space=21) to see if someone else has an example to share. If you have a sample application that you’d like to share to the larger Azure DevOps audience, [let us know](mailto:ado-identity@github.com) and we can look into circulating it on these docs more widely! -### Q: Do I need to have an Azure AD tenant with an active Azure subscription to use this API? -**A:** Unfortunately, this API is only available to users that are part of an Azure AD tenant with an active Azure subscription. - -### Q: Can I get an example of this sample application for another language/framework/application type? -**A:** We love that you want to use the API in your language of choice! If you have a request for an example, head over to our [Dev Community](https://developercommunity.visualstudio.com/search?space=21) to see if someone else has an example to share. If you have a sample application that you’d like to share to the larger Azure DevOps audience, [let us know](mailto:ado-identity@github.com) and we can look into circulating it on these docs more widely! - -### Q: What is the difference between this token API and the token admin API? -**A:** This [token API](/rest/api/azure/devops/tokens/pats) and the [token admin API](/rest/api/azure/devops/tokenadmin/), while similar, serve different use cases and audiences: +#### Q: What is the difference between this token API and the token admin API? +This [token API](/rest/api/azure/devops/tokens/pats) and the [token admin API](/rest/api/azure/devops/tokenadmin/), while similar, serve different use cases and audiences: * This token API is largely for users who want to manage the PATs that they own in an automated pipeline. This API allows. It gives you the ability to create new tokens and update existing ones. * The token admin API is meant for organization admins. Admins can use this API to retrieve and revoke OAuth authorizations, including personal access tokens (PATs) and self-describing session tokens, of users in their organizations. -### Q: How can I regenerate/rotate PATs through the API? I saw that option in the UI, but I don’t see a similar method in the API. -**A:** Great question! The “Regenerate” functionality available in the UI actually accomplishes a few actions, which are fully replicable through the API. +#### Q: How can I regenerate/rotate PATs through the API? I saw that option in the UI, but I don’t see a similar method in the API. +The 'Regenerate' functionality available in the UI actually accomplishes a few actions, which are fully replicable through the API. -To rotate your PAT, you need to: +To rotate your PAT, do the following steps: 1. Understand the metadata of the PAT using a **GET** call, 2. Create a new PAT with the old PAT’s metadata using a **POST** call, 3. Revoke the old PAT using a **DELETE** call -### Q: I see a "Need admin approval" pop-up when I try to proceed with using this app. How can I use this app without admin approval? -**A:** It seems that your tenant has set security policies which require your application to be granted permissions to access resources in the organization. At this moment, the only way to proceed with using this app in this tenant is to ask an admin to grant permission to the app before you can use it. - +#### Q: I see a "Need admin approval" pop-up when I try to proceed with using this app. How can I use this app without admin approval? +It seems that your tenant has security policies, which require your application to be granted permissions to access resources in the organization. At this moment, the only way to proceed with using this app in this tenant is to ask an admin to grant permission to the app before you can use it. -## Next steps -> [!div class="nextstepaction"] -> [Learn about the PAT lifecycle management API endpoints](/rest/api/azure/devops/tokens/pats) +#### Q: Why am I seeing an error like "Service principals aren't allowed to perform this action" when I try to call the PAT Lifecycle Management API using a Service Principal or Managed Identity? +**A:** Service Principals and Managed Identities aren't permitted. Given this API’s ability to create and revoke PATs, we want to ensure that such powerful functionality is given to allowed users only. diff --git a/docs/organizations/accounts/media/add-external-user/external-user-email-invitation.png b/docs/organizations/accounts/media/add-external-user/external-user-email-invitation.png index 26a0a1b20b8..44f2717a0f6 100644 Binary files a/docs/organizations/accounts/media/add-external-user/external-user-email-invitation.png and b/docs/organizations/accounts/media/add-external-user/external-user-email-invitation.png differ diff --git a/docs/organizations/accounts/media/add-external-user/guest-access-preview.png b/docs/organizations/accounts/media/add-external-user/guest-access-preview.png index b68772a8fce..97d7de10721 100644 Binary files a/docs/organizations/accounts/media/add-external-user/guest-access-preview.png and b/docs/organizations/accounts/media/add-external-user/guest-access-preview.png differ diff --git a/docs/organizations/accounts/media/add-privacy-url/privacy-url-in-organization-settings.png b/docs/organizations/accounts/media/add-privacy-url/privacy-url-in-organization-settings.png index 68639dd9aba..521ef03a769 100644 Binary files a/docs/organizations/accounts/media/add-privacy-url/privacy-url-in-organization-settings.png and b/docs/organizations/accounts/media/add-privacy-url/privacy-url-in-organization-settings.png differ diff --git a/docs/organizations/accounts/media/assign-access-levels/add-group-rule-dialog-new.png b/docs/organizations/accounts/media/assign-access-levels/add-group-rule-dialog-new.png index 51c83274b3e..d07f7f25383 100644 Binary files a/docs/organizations/accounts/media/assign-access-levels/add-group-rule-dialog-new.png and b/docs/organizations/accounts/media/assign-access-levels/add-group-rule-dialog-new.png differ diff --git a/docs/organizations/accounts/media/assign-access-levels/project-collection-administrators-group-members-new.png b/docs/organizations/accounts/media/assign-access-levels/project-collection-administrators-group-members-new.png index d3a3ef337d3..aa632d53db7 100644 Binary files a/docs/organizations/accounts/media/assign-access-levels/project-collection-administrators-group-members-new.png and b/docs/organizations/accounts/media/assign-access-levels/project-collection-administrators-group-members-new.png differ diff --git a/docs/organizations/accounts/media/assign-access-levels/see-group-rules.png b/docs/organizations/accounts/media/assign-access-levels/see-group-rules.png deleted file mode 100644 index bdb3caab2a7..00000000000 Binary files a/docs/organizations/accounts/media/assign-access-levels/see-group-rules.png and /dev/null differ diff --git a/docs/organizations/accounts/media/assign-access-levels/verify-user-summary.png b/docs/organizations/accounts/media/assign-access-levels/verify-user-summary.png index cc4cf1c83a8..ac8a2c8e904 100644 Binary files a/docs/organizations/accounts/media/assign-access-levels/verify-user-summary.png and b/docs/organizations/accounts/media/assign-access-levels/verify-user-summary.png differ diff --git a/docs/organizations/accounts/media/azure-ad-tenant-policy/add-azure-ad-user-group.png b/docs/organizations/accounts/media/azure-ad-tenant-policy/add-azure-ad-user-group.png deleted file mode 100644 index 0ea115af4ce..00000000000 Binary files a/docs/organizations/accounts/media/azure-ad-tenant-policy/add-azure-ad-user-group.png and /dev/null differ diff --git a/docs/organizations/accounts/media/azure-ad-tenant-policy/azure-ad-powershell.png b/docs/organizations/accounts/media/azure-ad-tenant-policy/azure-ad-powershell.png deleted file mode 100644 index 1c0c0aab0ba..00000000000 Binary files a/docs/organizations/accounts/media/azure-ad-tenant-policy/azure-ad-powershell.png and /dev/null differ diff --git a/docs/organizations/accounts/media/azure-ad-tenant-policy/azure-ad-roles-and-administrators.png b/docs/organizations/accounts/media/azure-ad-tenant-policy/azure-ad-roles-and-administrators.png index 3d3c1083d88..21303829d51 100644 Binary files a/docs/organizations/accounts/media/azure-ad-tenant-policy/azure-ad-roles-and-administrators.png and b/docs/organizations/accounts/media/azure-ad-tenant-policy/azure-ad-roles-and-administrators.png differ diff --git a/docs/organizations/accounts/media/azure-ad-tenant-policy/azure-ad-turn-policy-on.png b/docs/organizations/accounts/media/azure-ad-tenant-policy/azure-ad-turn-policy-on.png deleted file mode 100644 index 630e05ecd5d..00000000000 Binary files a/docs/organizations/accounts/media/azure-ad-tenant-policy/azure-ad-turn-policy-on.png and /dev/null differ diff --git a/docs/organizations/accounts/media/azure-ad-tenant-policy/edit-display-message.png b/docs/organizations/accounts/media/azure-ad-tenant-policy/edit-display-message.png deleted file mode 100644 index 18c7187fb32..00000000000 Binary files a/docs/organizations/accounts/media/azure-ad-tenant-policy/edit-display-message.png and /dev/null differ diff --git a/docs/organizations/accounts/media/azure-ad-tenant-policy/options-add-azure-ad-user-group-display-error-message.png b/docs/organizations/accounts/media/azure-ad-tenant-policy/options-add-azure-ad-user-group-display-error-message.png deleted file mode 100644 index 25441ae0e5a..00000000000 Binary files a/docs/organizations/accounts/media/azure-ad-tenant-policy/options-add-azure-ad-user-group-display-error-message.png and /dev/null differ diff --git a/docs/organizations/accounts/media/azure-ad-tenant-policy/restrict-organization-creation-toggle.png b/docs/organizations/accounts/media/azure-ad-tenant-policy/restrict-organization-creation-toggle.png new file mode 100644 index 00000000000..a463f5ff1c3 Binary files /dev/null and b/docs/organizations/accounts/media/azure-ad-tenant-policy/restrict-organization-creation-toggle.png differ diff --git a/docs/organizations/accounts/media/change-application-access-policies/application-connection-policy-settings.png b/docs/organizations/accounts/media/change-application-access-policies/application-connection-policy-settings.png deleted file mode 100644 index fa725f23c09..00000000000 Binary files a/docs/organizations/accounts/media/change-application-access-policies/application-connection-policy-settings.png and /dev/null differ diff --git a/docs/organizations/accounts/media/change-azure-ad-connection.md/select-more-actions.png b/docs/organizations/accounts/media/change-azure-ad-connection.md/select-more-actions.png deleted file mode 100644 index 67932f21579..00000000000 Binary files a/docs/organizations/accounts/media/change-azure-ad-connection.md/select-more-actions.png and /dev/null differ diff --git a/docs/organizations/accounts/media/change-azure-ad-connection.md/select-switch-directory.png b/docs/organizations/accounts/media/change-azure-ad-connection.md/select-switch-directory.png index bd55efb1ea4..72ee7763c86 100644 Binary files a/docs/organizations/accounts/media/change-azure-ad-connection.md/select-switch-directory.png and b/docs/organizations/accounts/media/change-azure-ad-connection.md/select-switch-directory.png differ diff --git a/docs/organizations/accounts/media/change-azure-ad-connection.md/switch-to-another-directory.png b/docs/organizations/accounts/media/change-azure-ad-connection.md/switch-to-another-directory.png deleted file mode 100644 index 990b148dbc3..00000000000 Binary files a/docs/organizations/accounts/media/change-azure-ad-connection.md/switch-to-another-directory.png and /dev/null differ diff --git a/docs/organizations/accounts/media/change-organization-location/organization-settings-geography.png b/docs/organizations/accounts/media/change-organization-location/organization-settings-geography.png new file mode 100644 index 00000000000..a9c4aad1750 Binary files /dev/null and b/docs/organizations/accounts/media/change-organization-location/organization-settings-geography.png differ diff --git a/docs/organizations/accounts/media/change-organization-location/organization-settings-region.png b/docs/organizations/accounts/media/change-organization-location/organization-settings-region.png deleted file mode 100644 index 831dd4c1f02..00000000000 Binary files a/docs/organizations/accounts/media/change-organization-location/organization-settings-region.png and /dev/null differ diff --git a/docs/organizations/accounts/media/change-time-zone/organization-time-zone-settings.png b/docs/organizations/accounts/media/change-time-zone/organization-time-zone-settings.png index 150eff9a435..c814e545f1e 100644 Binary files a/docs/organizations/accounts/media/change-time-zone/organization-time-zone-settings.png and b/docs/organizations/accounts/media/change-time-zone/organization-time-zone-settings.png differ diff --git a/docs/organizations/accounts/media/change-time-zone/select-edit-profile.png b/docs/organizations/accounts/media/change-time-zone/select-edit-profile.png index 25a41820f4a..9fadd509943 100644 Binary files a/docs/organizations/accounts/media/change-time-zone/select-edit-profile.png and b/docs/organizations/accounts/media/change-time-zone/select-edit-profile.png differ diff --git a/docs/organizations/accounts/media/connect-organization-to-aad/select-azure-ad-connect-directory.png b/docs/organizations/accounts/media/connect-organization-to-aad/select-azure-ad-connect-directory.png deleted file mode 100644 index 430bd4983cf..00000000000 Binary files a/docs/organizations/accounts/media/connect-organization-to-aad/select-azure-ad-connect-directory.png and /dev/null differ diff --git a/docs/organizations/accounts/media/delete-organization/organization-overview-settings.png b/docs/organizations/accounts/media/delete-organization/organization-overview-settings.png index 63295c0a546..f38fd3cdc98 100644 Binary files a/docs/organizations/accounts/media/delete-organization/organization-overview-settings.png and b/docs/organizations/accounts/media/delete-organization/organization-overview-settings.png differ diff --git a/docs/organizations/accounts/media/delete-user/confirm-remove-existing-user.png b/docs/organizations/accounts/media/delete-user/confirm-remove-existing-user.png deleted file mode 100644 index bb34f12ed31..00000000000 Binary files a/docs/organizations/accounts/media/delete-user/confirm-remove-existing-user.png and /dev/null differ diff --git a/docs/organizations/accounts/media/delete-user/remove-user-from-organization-new.png b/docs/organizations/accounts/media/delete-user/remove-user-from-organization-new.png index 9ad8766d374..5ec1b5a9ab9 100644 Binary files a/docs/organizations/accounts/media/delete-user/remove-user-from-organization-new.png and b/docs/organizations/accounts/media/delete-user/remove-user-from-organization-new.png differ diff --git a/docs/organizations/accounts/media/delete-user/remove-user-vert.png b/docs/organizations/accounts/media/delete-user/remove-user-vert.png index 6511735494a..05009728b76 100644 Binary files a/docs/organizations/accounts/media/delete-user/remove-user-vert.png and b/docs/organizations/accounts/media/delete-user/remove-user-vert.png differ diff --git a/docs/organizations/accounts/media/faq/check-user-type-in-Azure-portal.png b/docs/organizations/accounts/media/faq/check-user-type-in-Azure-portal.png index 166eb43bff8..4d756ac1848 100644 Binary files a/docs/organizations/accounts/media/faq/check-user-type-in-Azure-portal.png and b/docs/organizations/accounts/media/faq/check-user-type-in-Azure-portal.png differ diff --git a/docs/organizations/accounts/media/faq/confirm-removal-from-organization.png b/docs/organizations/accounts/media/faq/confirm-removal-from-organization.png index 71a51676e99..90b5adda38a 100644 Binary files a/docs/organizations/accounts/media/faq/confirm-removal-from-organization.png and b/docs/organizations/accounts/media/faq/confirm-removal-from-organization.png differ diff --git a/docs/organizations/accounts/media/faq/github-enterprise.png b/docs/organizations/accounts/media/faq/github-enterprise.png new file mode 100644 index 00000000000..3f0b0cab828 Binary files /dev/null and b/docs/organizations/accounts/media/faq/github-enterprise.png differ diff --git a/docs/organizations/accounts/media/faq/member-leave-organization.png b/docs/organizations/accounts/media/faq/member-leave-organization.png index eee2b2b83cf..4ddcb6012c0 100644 Binary files a/docs/organizations/accounts/media/faq/member-leave-organization.png and b/docs/organizations/accounts/media/faq/member-leave-organization.png differ diff --git a/docs/organizations/accounts/media/manage-azure-ad-groups/permissions-scope-example.png b/docs/organizations/accounts/media/manage-azure-ad-groups/permissions-scope-example.png index fcd75be4428..8159cbef7c4 100644 Binary files a/docs/organizations/accounts/media/manage-azure-ad-groups/permissions-scope-example.png and b/docs/organizations/accounts/media/manage-azure-ad-groups/permissions-scope-example.png differ diff --git a/docs/organizations/accounts/media/manage-group-licensing/add-group-rule.png b/docs/organizations/accounts/media/manage-group-licensing/add-group-rule.png index 3f06624e666..82107c30f5f 100644 Binary files a/docs/organizations/accounts/media/manage-group-licensing/add-group-rule.png and b/docs/organizations/accounts/media/manage-group-licensing/add-group-rule.png differ diff --git a/docs/organizations/accounts/media/manage-personal-access-tokens-via-api/step-1-azure-ad-app-registrations.png b/docs/organizations/accounts/media/manage-personal-access-tokens-via-api/step-1-azure-ad-app-registrations.png index 2fa2d532a5f..de5fab1a90d 100644 Binary files a/docs/organizations/accounts/media/manage-personal-access-tokens-via-api/step-1-azure-ad-app-registrations.png and b/docs/organizations/accounts/media/manage-personal-access-tokens-via-api/step-1-azure-ad-app-registrations.png differ diff --git a/docs/organizations/accounts/media/manage-users/manage-users-show-context-menu-preview.png b/docs/organizations/accounts/media/manage-users/manage-users-show-context-menu-preview.png index 192f418ced2..1e22abd1501 100644 Binary files a/docs/organizations/accounts/media/manage-users/manage-users-show-context-menu-preview.png and b/docs/organizations/accounts/media/manage-users/manage-users-show-context-menu-preview.png differ diff --git a/docs/organizations/accounts/media/manage-users/manage-users-show-context-menu-vert.png b/docs/organizations/accounts/media/manage-users/manage-users-show-context-menu-vert.png deleted file mode 100644 index 6f2971a5c1d..00000000000 Binary files a/docs/organizations/accounts/media/manage-users/manage-users-show-context-menu-vert.png and /dev/null differ diff --git a/docs/organizations/accounts/media/manage-work-access/AzureAddMembers3.png b/docs/organizations/accounts/media/manage-work-access/AzureAddMembers3.png deleted file mode 100644 index d83e57043d7..00000000000 Binary files a/docs/organizations/accounts/media/manage-work-access/AzureAddMembers3.png and /dev/null differ diff --git a/docs/organizations/accounts/media/manage-work-access/AzureFindConnectedDirectory.png b/docs/organizations/accounts/media/manage-work-access/AzureFindConnectedDirectory.png deleted file mode 100644 index 8e40b70d7db..00000000000 Binary files a/docs/organizations/accounts/media/manage-work-access/AzureFindConnectedDirectory.png and /dev/null differ diff --git a/docs/organizations/accounts/media/migrate-to-group-based-resource-management/add-group-members.png b/docs/organizations/accounts/media/migrate-to-group-based-resource-management/add-group-members.png index bce9c5ceb8c..a811b8679f9 100644 Binary files a/docs/organizations/accounts/media/migrate-to-group-based-resource-management/add-group-members.png and b/docs/organizations/accounts/media/migrate-to-group-based-resource-management/add-group-members.png differ diff --git a/docs/organizations/accounts/media/policies/enforce-maximum-pat-lifespan-policy-toggle-on.png b/docs/organizations/accounts/media/policies/enforce-maximum-pat-lifespan-policy-toggle-on.png index 40bb3246466..68959320279 100644 Binary files a/docs/organizations/accounts/media/policies/enforce-maximum-pat-lifespan-policy-toggle-on.png and b/docs/organizations/accounts/media/policies/enforce-maximum-pat-lifespan-policy-toggle-on.png differ diff --git a/docs/organizations/accounts/media/policies/restrict-full-scoped-pat-creation-policy-toggle-on.png b/docs/organizations/accounts/media/policies/restrict-full-scoped-pat-creation-policy-toggle-on.png index 468c91cf813..c66e4b5dc8a 100644 Binary files a/docs/organizations/accounts/media/policies/restrict-full-scoped-pat-creation-policy-toggle-on.png and b/docs/organizations/accounts/media/policies/restrict-full-scoped-pat-creation-policy-toggle-on.png differ diff --git a/docs/organizations/accounts/media/policies/restrict-global-pat-creation-policy-toggle-on.png b/docs/organizations/accounts/media/policies/restrict-global-pat-creation-policy-toggle-on.png index 6bdb9123cf9..2e54ce494f6 100644 Binary files a/docs/organizations/accounts/media/policies/restrict-global-pat-creation-policy-toggle-on.png and b/docs/organizations/accounts/media/policies/restrict-global-pat-creation-policy-toggle-on.png differ diff --git a/docs/organizations/accounts/media/remove-direct-assignments/choose-remove-direct-assignments-preview.png b/docs/organizations/accounts/media/remove-direct-assignments/choose-remove-direct-assignments-preview.png index 8f353e35332..d05572811cc 100644 Binary files a/docs/organizations/accounts/media/remove-direct-assignments/choose-remove-direct-assignments-preview.png and b/docs/organizations/accounts/media/remove-direct-assignments/choose-remove-direct-assignments-preview.png differ diff --git a/docs/organizations/accounts/media/remove-direct-assignments/confirm-removal-of-direct-assignments.png b/docs/organizations/accounts/media/remove-direct-assignments/confirm-removal-of-direct-assignments.png index 7dd4301d191..16f46e0c9da 100644 Binary files a/docs/organizations/accounts/media/remove-direct-assignments/confirm-removal-of-direct-assignments.png and b/docs/organizations/accounts/media/remove-direct-assignments/confirm-removal-of-direct-assignments.png differ diff --git a/docs/organizations/accounts/media/rename-vso-organization/rename-organization-new.png b/docs/organizations/accounts/media/rename-vso-organization/rename-organization-new.png index 92cb519f2e4..f09d83368e1 100644 Binary files a/docs/organizations/accounts/media/rename-vso-organization/rename-organization-new.png and b/docs/organizations/accounts/media/rename-vso-organization/rename-organization-new.png differ diff --git a/docs/organizations/accounts/media/request-access-policy-settings.png b/docs/organizations/accounts/media/request-access-policy-settings.png index d10aeadf7e0..818317f5348 100644 Binary files a/docs/organizations/accounts/media/request-access-policy-settings.png and b/docs/organizations/accounts/media/request-access-policy-settings.png differ diff --git a/docs/organizations/accounts/media/resolve-org-owner/change-owner-dialog.png b/docs/organizations/accounts/media/resolve-org-owner/change-owner-dialog.png deleted file mode 100644 index e1e4e51cb3b..00000000000 Binary files a/docs/organizations/accounts/media/resolve-org-owner/change-owner-dialog.png and /dev/null differ diff --git a/docs/organizations/accounts/media/resolve-org-owner/warning-orphan-ownership.png b/docs/organizations/accounts/media/resolve-org-owner/warning-orphan-ownership.png deleted file mode 100644 index 2f90052fcc8..00000000000 Binary files a/docs/organizations/accounts/media/resolve-org-owner/warning-orphan-ownership.png and /dev/null differ diff --git a/docs/organizations/accounts/media/shared/add-new-users.png b/docs/organizations/accounts/media/shared/add-new-users.png deleted file mode 100644 index 26a6107cbf0..00000000000 Binary files a/docs/organizations/accounts/media/shared/add-new-users.png and /dev/null differ diff --git a/docs/organizations/accounts/media/shared/azure-ad-select-resolve-for-disconnected-users.png b/docs/organizations/accounts/media/shared/azure-ad-select-resolve-for-disconnected-users.png index 306ea11c145..f7a153ae66a 100644 Binary files a/docs/organizations/accounts/media/shared/azure-ad-select-resolve-for-disconnected-users.png and b/docs/organizations/accounts/media/shared/azure-ad-select-resolve-for-disconnected-users.png differ diff --git a/docs/organizations/accounts/media/shared/connect-success-dialog.png b/docs/organizations/accounts/media/shared/connect-success-dialog.png index d0dc8f990fe..e0d8b037dc5 100644 Binary files a/docs/organizations/accounts/media/shared/connect-success-dialog.png and b/docs/organizations/accounts/media/shared/connect-success-dialog.png differ diff --git a/docs/organizations/accounts/media/shared/connection-warning.png b/docs/organizations/accounts/media/shared/connection-warning.png index daae9d0bf46..7058e91b846 100644 Binary files a/docs/organizations/accounts/media/shared/connection-warning.png and b/docs/organizations/accounts/media/shared/connection-warning.png differ diff --git a/docs/organizations/accounts/media/shared/disconnection-confirmation.png b/docs/organizations/accounts/media/shared/disconnection-confirmation.png index 81d9f15160b..03f885a61bc 100644 Binary files a/docs/organizations/accounts/media/shared/disconnection-confirmation.png and b/docs/organizations/accounts/media/shared/disconnection-confirmation.png differ diff --git a/docs/organizations/accounts/media/shared/enable-conditional-access-policy-preview.png b/docs/organizations/accounts/media/shared/enable-conditional-access-policy-preview.png deleted file mode 100644 index 06b6ebbf22e..00000000000 Binary files a/docs/organizations/accounts/media/shared/enable-conditional-access-policy-preview.png and /dev/null differ diff --git a/docs/organizations/accounts/media/shared/enable-conditional-access-policy.png b/docs/organizations/accounts/media/shared/enable-conditional-access-policy.png deleted file mode 100644 index a09288f776f..00000000000 Binary files a/docs/organizations/accounts/media/shared/enable-conditional-access-policy.png and /dev/null differ diff --git a/docs/organizations/accounts/media/shared/guest-azure-ad-cannot-invite.png b/docs/organizations/accounts/media/shared/guest-azure-ad-cannot-invite.png index 8b0e0ded381..5780254131d 100644 Binary files a/docs/organizations/accounts/media/shared/guest-azure-ad-cannot-invite.png and b/docs/organizations/accounts/media/shared/guest-azure-ad-cannot-invite.png differ diff --git a/docs/organizations/accounts/media/shared/organization-settings-select-overview.png b/docs/organizations/accounts/media/shared/organization-settings-select-overview.png index e7b2d022036..91f7fe17d14 100644 Binary files a/docs/organizations/accounts/media/shared/organization-settings-select-overview.png and b/docs/organizations/accounts/media/shared/organization-settings-select-overview.png differ diff --git a/docs/organizations/accounts/media/shared/resolve-disconnected-users.png b/docs/organizations/accounts/media/shared/resolve-disconnected-users.png index 9606bff8cff..af4d20820f9 100644 Binary files a/docs/organizations/accounts/media/shared/resolve-disconnected-users.png and b/docs/organizations/accounts/media/shared/resolve-disconnected-users.png differ diff --git a/docs/organizations/accounts/media/shared/select-azure-ad-connect-directory.png b/docs/organizations/accounts/media/shared/select-azure-ad-connect-directory.png index 9d3d955a3b3..7ea4a305d53 100644 Binary files a/docs/organizations/accounts/media/shared/select-azure-ad-connect-directory.png and b/docs/organizations/accounts/media/shared/select-azure-ad-connect-directory.png differ diff --git a/docs/organizations/accounts/media/shared/select-azure-ad-download.png b/docs/organizations/accounts/media/shared/select-azure-ad-download.png index fd7df077a0d..7570e302fbe 100644 Binary files a/docs/organizations/accounts/media/shared/select-azure-ad-download.png and b/docs/organizations/accounts/media/shared/select-azure-ad-download.png differ diff --git a/docs/organizations/accounts/media/shared/select-directory-connect.png b/docs/organizations/accounts/media/shared/select-directory-connect.png index 30cadf6e3be..568f3978ee3 100644 Binary files a/docs/organizations/accounts/media/shared/select-directory-connect.png and b/docs/organizations/accounts/media/shared/select-directory-connect.png differ diff --git a/docs/organizations/accounts/media/shared/select-disconnect-directory.png b/docs/organizations/accounts/media/shared/select-disconnect-directory.png index bc51606d05c..718907b7f5e 100644 Binary files a/docs/organizations/accounts/media/shared/select-disconnect-directory.png and b/docs/organizations/accounts/media/shared/select-disconnect-directory.png differ diff --git a/docs/organizations/accounts/media/shared/select-security-profile-menu.png b/docs/organizations/accounts/media/shared/select-security-profile-menu.png index 40fb076aa71..2e2839389c7 100644 Binary files a/docs/organizations/accounts/media/shared/select-security-profile-menu.png and b/docs/organizations/accounts/media/shared/select-security-profile-menu.png differ diff --git a/docs/organizations/accounts/media/shared/show-disconnected-users.png b/docs/organizations/accounts/media/shared/show-disconnected-users.png index 8c57ecbd6e8..6e5938a83eb 100644 Binary files a/docs/organizations/accounts/media/shared/show-disconnected-users.png and b/docs/organizations/accounts/media/shared/show-disconnected-users.png differ diff --git a/docs/organizations/accounts/media/shared/sign-out-azure-devops.png b/docs/organizations/accounts/media/shared/sign-out-azure-devops.png index 6ac4b38ae91..f03f62d3739 100644 Binary files a/docs/organizations/accounts/media/shared/sign-out-azure-devops.png and b/docs/organizations/accounts/media/shared/sign-out-azure-devops.png differ diff --git a/docs/organizations/accounts/media/shared/sort-by-professional-access-level.png b/docs/organizations/accounts/media/shared/sort-by-professional-access-level.png deleted file mode 100644 index dee53e78b53..00000000000 Binary files a/docs/organizations/accounts/media/shared/sort-by-professional-access-level.png and /dev/null differ diff --git a/docs/organizations/accounts/media/shared/visual-studio-profile-page.png b/docs/organizations/accounts/media/shared/visual-studio-profile-page.png index 8aad6de2635..4ef13d87e4e 100644 Binary files a/docs/organizations/accounts/media/shared/visual-studio-profile-page.png and b/docs/organizations/accounts/media/shared/visual-studio-profile-page.png differ diff --git a/docs/organizations/accounts/media/tenant-policy-automatically-revoke-leaked-pats.png b/docs/organizations/accounts/media/tenant-policy-automatically-revoke-leaked-pats.png deleted file mode 100644 index eb2be8786c9..00000000000 Binary files a/docs/organizations/accounts/media/tenant-policy-automatically-revoke-leaked-pats.png and /dev/null differ diff --git a/docs/organizations/accounts/media/usage-screenshot-example.png b/docs/organizations/accounts/media/usage-screenshot-example.png index 3c01d7a3d50..136e5927db5 100644 Binary files a/docs/organizations/accounts/media/usage-screenshot-example.png and b/docs/organizations/accounts/media/usage-screenshot-example.png differ diff --git a/docs/organizations/accounts/media/use-personal-access-tokens-to-authenticate/PAT-creation.png b/docs/organizations/accounts/media/use-personal-access-tokens-to-authenticate/PAT-creation.png index 449ff657358..edae60053a9 100644 Binary files a/docs/organizations/accounts/media/use-personal-access-tokens-to-authenticate/PAT-creation.png and b/docs/organizations/accounts/media/use-personal-access-tokens-to-authenticate/PAT-creation.png differ diff --git a/docs/organizations/accounts/media/use-personal-access-tokens-to-authenticate/PAT-expiration.png b/docs/organizations/accounts/media/use-personal-access-tokens-to-authenticate/PAT-expiration.png index 25b39140db9..2d36578d85f 100644 Binary files a/docs/organizations/accounts/media/use-personal-access-tokens-to-authenticate/PAT-expiration.png and b/docs/organizations/accounts/media/use-personal-access-tokens-to-authenticate/PAT-expiration.png differ diff --git a/docs/organizations/accounts/media/user-hub/add-users.png b/docs/organizations/accounts/media/user-hub/add-users.png deleted file mode 100644 index 1b64dc28f6a..00000000000 Binary files a/docs/organizations/accounts/media/user-hub/add-users.png and /dev/null differ diff --git a/docs/organizations/accounts/media/user-hub/choose-permissions-select-group.png b/docs/organizations/accounts/media/user-hub/choose-permissions-select-group.png index d89a7486502..389d0f489af 100644 Binary files a/docs/organizations/accounts/media/user-hub/choose-permissions-select-group.png and b/docs/organizations/accounts/media/user-hub/choose-permissions-select-group.png differ diff --git a/docs/organizations/accounts/media/user-hub/select-members-add.png b/docs/organizations/accounts/media/user-hub/select-members-add.png index af4abc9d116..2aeaabbb8c6 100644 Binary files a/docs/organizations/accounts/media/user-hub/select-members-add.png and b/docs/organizations/accounts/media/user-hub/select-members-add.png differ diff --git a/docs/organizations/accounts/organization-management.md b/docs/organizations/accounts/organization-management.md index d9b298d19f9..b7340817479 100644 --- a/docs/organizations/accounts/organization-management.md +++ b/docs/organizations/accounts/organization-management.md @@ -1,14 +1,13 @@ --- title: Manage an organization titleSuffix: Azure DevOps Services -ms.custom: seodec18, contperf-fy22q3 description: Manage an organization, so you can collaborate with others to develop apps, plan and track work, integrate with other services, get more features and extensions. ms.subservice: azure-devops-organizations ms.assetid: fa1dbe39-08b1-4eba-886a-33c1aa1e6a83 ms.topic: overview ms.author: chcomley author: chcomley -ms.date: 02/22/2022 +ms.date: 10/24/2024 monikerRange: 'azure-devops' --- @@ -16,33 +15,37 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -With an organization, you gain access to Azure DevOps Services, where you can do the following tasks: +With an organization in Azure DevOps Services, you can do the following tasks: -* Collaborate with others to develop applications by using our cloud service -* Plan and track your work and code defects and issues -* Set up continuous integration and deployment -* Integrate with other services by using service hooks -* Obtain more features and extensions -* Create one or more projects to segment work +- **Collaborate**: Work with team members to develop applications using our cloud service. +- **Plan and track**: Manage your work, track code defects, and address issues efficiently. +- **Use continuous integration and deployment**: Set up automated builds and deployments to streamline your development process. +- **Integrate**: Connect with other services using service hooks for seamless workflows. +- **Enhance**: Access other features and extensions to extend the capabilities of Azure DevOps. +- **Organize**: Create one or more projects to segment and manage your work effectively. + +By using these capabilities, you can enhance your development process and improve collaboration within your team. > [!NOTE] > If you're just getting started, see [Get started managing your organization](../../user-guide/manage-organization-collection.md). For information about managing an on-premises Azure DevOps Server, see [Administrative tasks quick reference](/azure/devops/server/admin/admin-quick-ref). ## Prerequisites -Before you can manage an organization, do the following tasks: +To effectively manage an organization, ensure the following tasks are complete: + +**Organization:** - [Plan your organizational structure](../../user-guide/plan-your-azure-devops-org-structure.md) in Azure DevOps Services. -- [Create your organization](create-organization.md) and invite others, so they have access. +- [Create your organization](create-organization.md) and invite team members and grant them access. ## Connect to your organization -Once you've created your organization, you can [connect to your projects](../../organizations/projects/connect-to-projects.md) with tools like Xcode, Eclipse, or Visual Studio, and then add code to your project. +Once you create your organization, you can [connect to your projects](../../organizations/projects/connect-to-projects.md) with tools like Xcode, Eclipse, or Visual Studio, and then add code to your project. -Some clients, like Xcode, Git, and NuGet, require basic credentials (a username and password) to access Azure DevOps. To connect these clients to Azure DevOps, create personal access tokens (PATs) to authenticate your identity. Then, you can use a credential manager to create, store, and secure your tokens. This way, you don't have to reenter them every time you make updates. Or, if you don't want to use a credential manager, you can [create PATs manually](use-personal-access-tokens-to-authenticate.md). +Some clients, like Xcode, Git, and NuGet, require basic credentials to access Azure DevOps. To connect these clients to Azure DevOps, look into the [available authentication methods](../../integrate/get-started/authentication/authentication-guidance.md) and choose the method that best fits your security and workflow requirements. - + -## Manage access to your organization +## Manage access to your organization Manage access to your organization by adding users. Manage use of features and tasks with access levels and permissions for each user. @@ -50,33 +53,32 @@ You can add and assign an access level to users one-by-one, which is referred to ### *Access*, *access level*, and *permissions* -Understand the following three key definitions when you manage your user base: +Understand the following key definitions when managing your user base in Azure DevOps: -* **Access** indicates a user can sign into your organization, and at a minimum view information about your organization. -* **Access levels** grant or restrict access to select web portal features. Access levels enable administrators to provide their user base access to the features they need and only pay for those features. -* **Permissions**, granted through security groups, provide and restrict users from completing specific tasks. +* **Access**: Indicates that a user can sign into your organization and, at a minimum, view information about your organization. Access is the basic level of interaction a user can have with your Azure DevOps environment. +* **Access levels**: Manage access to specific web portal features. Access levels allow administrators to grant users access to the features they need while only paying for those features. For example, users with Basic access can contribute to projects, while users with Stakeholder access can only view and provide feedback. +* **Permissions**: Permissions provide or restrict users from completing specific tasks, which are granted through security groups. Permissions control which actions users can perform within the organization, such as creating projects, editing work items, or managing repositories. By assigning users to different security groups, you can tailor their permissions to match their roles and responsibilities. For an overview of default assignments, see [Default permissions and access for Azure DevOps](../security/permissions-access.md). - + ### Direct assignment -If you don't manage your user base with Azure AD, as described in the next section, then you can add users through the following ways: +If you don't manage your user base with Microsoft Entra ID, as described in the next section, then you can add users through the following ways: -* Add users to your organization from the **Organization settings > Users** page. Only organization owners or members of the Project Collection Administration group can add users at this level. Specify the access level and the project(s) the user gets added to. For more information, see [Add users to your organization or project](add-organization-users.md). +* **Add users to your organization:** Go to **Organization settings > Users**. Only organization owners or members of the Project Collection Administrator group can add users at this level. Specify the access level and the project the user gets added to. For more information, see [Add users to your organization or project](add-organization-users.md). -* Add users to one or more teams from the **Project > Summary** page or to a specific team from the **Project settings > Teams > Team** page. Members of the Project Collection Administration or Project Administration groups, or a team administrator can add users to teams. +* **Add users to a team:** Go to **Project** > **Summary** to add users to one or more teams. Or, go to **Project settings** > **Teams** > **Team** to add users to a specific team. Members of the Project Collection Administrator or Project Administrator groups, or a team administrator, can add users to teams. - > [!div class="mx-imgBorder"] - > ![Web portal, Project Overview page, Invite new users dialog box](media/org-manage/invite-members-dialog.png) + > [!div class="mx-imgBorder"] + > ![Screenshot shows Web portal, Project Overview page, Invite new users dialog box.](media/org-manage/invite-members-dialog.png) - Unless users get granted an access level directly or through a group rule, they're assigned the best available access level. If there are no more free Basic slots available, then the user is added as a Stakeholder. The access level can be changed later through the **Organization settings > Users** page. + Unless users are granted an access level directly or through a group rule, they get assigned the best available access level. If there are no more free Basic slots available, the user gets added with Stakeholder access. You can change the access level later via the **Organization settings** > **Users** page. > [!TIP] > If you need more than the free users and services included with your organization, -[set up billing for your organization](../billing/set-up-billing-for-your-organization-vs.md). -You can then pay for more users with Basic access, buy more services, and purchase extensions for your organization. +[set up billing for your organization](../billing/set-up-billing-for-your-organization-vs.md#set-up-billing). This allows you to pay for additional users with Basic access, purchase more services, and acquire extensions for your organization. For more information about adding users to your organization, see the following articles: @@ -84,27 +86,26 @@ For more information about adding users to your organization, see the following * [Add users to a team](../security/add-users-team-project.md#add-users-to-a-team) * [Add users to a project](../security/add-users-team-project.md#add-users-to-a-project) + + - +### Microsoft Entra ID -### Azure AD +If you manage your users with Microsoft Entra ID, you can connect your organization to Microsoft Entra ID and manage access through it. If you already use Microsoft Entra ID, [authenticate access to Azure DevOps Services using your directory](access-with-azure-ad.md). -If you manage your users with Azure AD, you can connect your organization to Azure AD and manage access through Azure AD. If you already use Azure AD, [use your directory to authenticate access to Azure DevOps Services](access-with-azure-ad.md). +To add users through Microsoft Entra ID, do the following tasks: -Do the following tasks, to add users through Azure AD: +1. [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md) +1. [Add organization users to your Microsoft Entra ID](/azure/active-directory/fundamentals/add-users-azure-active-directory) +1. [Add a Microsoft Entra group to an Azure DevOps group](manage-azure-active-directory-groups.md) +1. [Create bulk assignments of access levels for users](add-organization-users.md) or [define group rules and assign access levels](assign-access-levels-by-group-membership.md) -1. [Connect your organization to Azure AD](connect-organization-to-azure-ad.md). If you need to set up Azure AD, do that now. -2. Go to [Azure AD](https://azure.microsoft.com/services/active-directory/) and sign in with your organization account. -3. [Add organization users to your Azure AD](/azure/active-directory/fundamentals/add-users-azure-active-directory). -4. [Add an Azure AD group to an Azure DevOps group](manage-azure-active-directory-groups.md). -5. [Create bulk assignments of access levels for users](add-organization-users.md), or [define group rules and assign access levels](assign-access-levels-by-group-membership.md). - - + ### Group rules -A best practice is to manage users through security groups. You can use the default security groups, create custom security groups, or reference Azure AD groups. You can use any of these groups to add and manage user access levels using group rules. For more information, see [Add a group rule to assign access levels and extensions](assign-access-levels-by-group-membership.md). +A best practice for managing users is to use security groups. You can utilize default security groups, create custom security groups, or reference Microsoft Entra groups. These groups allow you to add and manage user access levels using group rules. For more information, see [Add a group rule to assign access levels and extensions](assign-access-levels-by-group-membership.md). ## Other organization management tasks @@ -120,13 +121,15 @@ A best practice is to manage users through security groups. You can use the defa - [Authenticate with PATs](use-personal-access-tokens-to-authenticate.md) - [Revoke user PATs](admin-revoke-user-pats.md) - #### Manage Azure AD access + + +#### Manage Microsoft Entra ID access - [Remove Azure DevOps users](add-external-user.md) - - [Disconnect from Azure AD](disconnect-organization-from-azure-ad.md) - - [Change your Azure AD tenant connection](change-azure-ad-connection.md) + - [Disconnect from Microsoft Entra ID](disconnect-organization-from-azure-ad.md) + - [Change your Microsoft Entra tenant connection](change-azure-ad-connection.md) - [Restrict organization creation with tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) - - [About accessing your organization with Azure AD](access-with-azure-ad.md) + - [About accessing your organization with Microsoft Entra ID](access-with-azure-ad.md) #### Manage group-based licensing @@ -160,17 +163,17 @@ A best practice is to manage users through security groups. You can use the defa - [Add a team admin](../settings/add-team-administrator.md) - [Request an increase in permission levels](../security/request-changes-permissions.md) - [Grant or restrict permissions](../security/restrict-access.md) - - [Resources granted to project members](../projects/resources-granted-to-project-members.md) + - [Understand resources granted to project members](../projects/resources-granted-to-project-members.md) :::column-end::: :::row-end::: ## Related articles -* [About access levels](../security/access-levels.md) -* [Default permissions and access](../security/permissions-access.md) +* [Learn about access levels](../security/access-levels.md) +* [Understand default permissions and access](../security/permissions-access.md) * [Change project-level permissions](../security/change-project-level-permissions.md) * [Change project collection-level permissions](../security/change-organization-collection-level-permissions.md) * [Add a user as a team administrator](../settings/add-team-administrator.md) -* [About using Azure AD to authenticate access to Azure DevOps Services](access-with-azure-ad.md) -* [Troubleshoot permissions and access with Azure AD](faq-azure-access.yml) +* [Authenticate access to Azure DevOps Services using Microsoft Entra ID](access-with-azure-ad.md) +* [Troubleshoot permissions and access with Microsoft Entra ID](faq-azure-access.yml) diff --git a/docs/organizations/accounts/recover-your-organization.md b/docs/organizations/accounts/recover-your-organization.md index 5135a6c204e..dd16390ca37 100644 --- a/docs/organizations/accounts/recover-your-organization.md +++ b/docs/organizations/accounts/recover-your-organization.md @@ -1,14 +1,13 @@ --- title: Recover a deleted organization titleSuffix: Azure DevOps Services -ms.custom: seodec18 description: Learn how to restore your organization and data up to 90 days after being deleted, done with organization owner permissions. ms.subservice: azure-devops-organizations ms.assetid: b81adafa-adac-4e80-baa6-140fb58fbeff ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 10/25/2022 +ms.date: 10/24/2024 monikerRange: 'azure-devops' --- @@ -16,18 +15,17 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -After you delete an organization, it's disabled but available for 28 days. If you change your mind during this time, you can recover the organization. After 28 days, the organization and data are permanently deleted. +After you delete an organization, it's disabled but available for 28 days. If you change your mind during this time, you can recover the organization. After 28 days, the organization and data are permanently deleted. In rare cases, our deletion process might take up to 70 days due to backend retries and the need to delete data from multiple sources. ## Prerequisites -* An organization deleted within the last 28 days. -* Organization owner permissions. [How do I find the organization owner?](../security/look-up-organization-owner.md). For more information about specific scenarios, see the following instructions: - * [When you don't have an Azure DevOps Administrator](resolve-orphaned-organization.md#when-you-dont-have-an-azure-devops-administrator) - * [Resolve orphaned organization when your Azure DevOps Administrator *is* a member of the target organization](resolve-orphaned-organization.md#when-your-azure-devops-administrator-is-a-member-of-the-target-organization) - * [Resolve orphaned organization when your Azure DevOps Administrator *isn't* a member of the target organization](resolve-orphaned-organization.md#when-your-azure-devops-administrator-isnt-a-member-of-the-target-organization) +| Category | Requirements | +|--------------|-------------| +|**Permissions**| [Organization owner](../security/look-up-organization-owner.md). For more information about specific scenarios, see the following instructions:
      - [When you don't have an Azure DevOps Administrator](resolve-orphaned-organization.md#when-you-dont-have-an-azure-devops-administrator)
      - [Resolve orphaned organization when your Azure DevOps Administrator *is* a member of the target organization](resolve-orphaned-organization.md#when-your-azure-devops-administrator-is-a-member-of-the-target-organization)
      - [Resolve orphaned organization when your Azure DevOps Administrator *isn't* a member of the target organization](resolve-orphaned-organization.md#when-your-azure-devops-administrator-isnt-a-member-of-the-target-organization)| +|**Deletion time frame**| An organization deleted within the last 28 days.| > [!NOTE] -> If there's no owner for the deleted organization and you're an active Project Collection Administrator (PCA) and a member of the deleted organization, you still can't access **Organization settings** to assign a new owner. If this is your scenario, [contact Support](https://developercommunity.visualstudio.com/AzureDevOps). +> If there's no owner for the deleted organization and you're an active Project Collection Administrator and member of the deleted organization, you still can't access **Organization settings** to assign a new owner. If this is your scenario, [contact Support](https://developercommunity.visualstudio.com/AzureDevOps). ## Recover organization @@ -35,11 +33,11 @@ After you delete an organization, it's disabled but available for 28 days. If yo [Why am I asked to choose between my work or school account and my personal account?](faq-user-and-permissions-management.yml#ChooseOrgAcctMSAcct) -2. On your profile page, go to the lower *Organizations Pending Deletion* section, and then select **Restore**. +2. On your profile page, go to the lower *Organizations Pending Deletion* section, find the organization you want to restore, and then select **Restore**. ![Screenshot showing organizations pending deletion with highlighted Restore button.](media/shared/visual-studio-profile-page.png) -3. In the resulting popup, select **Restore** to confirm. +3. In the resulting popup page, select **Restore** to confirm. * If your organization URL is still available, you can restore it. @@ -49,13 +47,13 @@ After you delete an organization, it's disabled but available for 28 days. If yo 4. After you restore your organization, do the following tasks: - * If billing was previously set up for your organization, [relink your organization](../billing/set-up-billing-for-your-organization-vs.md) to an Azure subscription. - * If your organization was connected to Azure Active Directory for authenticating user access, you don't have to reconnect it. + * If billing was previously set up for your organization, [relink your organization](../billing/set-up-billing-for-your-organization-vs.md#set-up-billing) to an Azure subscription. + * If your organization was connected to Microsoft Entra ID for authenticating user access, you don't have to reconnect it. ## Related articles -* [Delete your organization from Azure DevOps](delete-your-organization.md) +* [Delete an organization](delete-your-organization.md) * [Create a new organization](create-organization.md) * [Change organization owner](change-organization-ownership.md) * [Change organization data region](change-organization-location.md) -* [FAQs for configuring and customizing your organization](faq-configure-customize-organization.yml) +* [Learn about FAQs for configuring and customizing your organization](faq-configure-customize-organization.yml) diff --git a/docs/organizations/accounts/rename-organization.md b/docs/organizations/accounts/rename-organization.md index 2192f52944d..d8204b55d7e 100644 --- a/docs/organizations/accounts/rename-organization.md +++ b/docs/organizations/accounts/rename-organization.md @@ -1,14 +1,13 @@ --- title: Rename your organization titleSuffix: Azure DevOps Services -ms.custom: seodec18 description: Learn how to rename your organization and what to do before and after you rename it. ms.subservice: azure-devops-organizations ms.assetid: a69f3789-19e9-40c5-ade3-4e11435d452d ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 06/23/2023 +ms.date: 10/24/2024 monikerRange: 'azure-devops' --- @@ -16,17 +15,21 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -You can change your organization name (URL) at any time in Azure DevOps. +You can change your organization name (URL) at any time in Azure DevOps. This action allows you to update the URL to better reflect your organization's branding or structure. Changing the organization name updates the URL used to access your Azure DevOps resources, including the URLs of your projects, repositories and other resources in the organization. Follow the steps in this article to rename your organization and ensure a smooth transition for your team. > [!CAUTION] -> The rename operation affects your organization's connections and individuals who are currently working with your organization. Before you start, find out [what to do before and after renaming your organization](https://support.microsoft.com/kb/2793597). +> The rename operation affects your organization's connections and individuals who are currently working with your organization. Before you start, meet the [prerequisites](#prerequisites) and find out [what to do after renaming your organization](/troubleshoot/azure/devops/rename-service-url). The URL of projects, repositories, and other resources within the organization will change. Make sure to update any bookmarks or links to these resources. ## Prerequisites -To change your organization URL, you need at least Basic access and organization owner permissions. [How do I find the organization owner?](../security/look-up-organization-owner.md) +| Category | Requirements | +|--------------|-------------| +|**Permissions** |[Organization owner](change-organization-ownership.md).| +|**Access levels**| At least **Basic** access.| +|**Tasks**|- Save your work.
      - Ensure other members aren't using the service.| > [!NOTE] -> You can't rename an organization within one hour of the most recent rename operation. +> Wait at least one hour after the most recent rename operation before renaming an organization again. ## Rename your organization @@ -57,5 +60,5 @@ A: The organization URL setting is two-way toggle. You can turn on the new domai ## Related articles - [Resolve orphaned organization](resolve-orphaned-organization.md) -- [Delete your organization](delete-your-organization.md) -- [Connect your organization to Azure Active Directory](connect-organization-to-azure-ad.md) +- [Delete an organization](delete-your-organization.md) +- [Connect your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md) diff --git a/docs/organizations/accounts/resolve-orphaned-organization.md b/docs/organizations/accounts/resolve-orphaned-organization.md index 9e8e905a058..71070c1c6cb 100644 --- a/docs/organizations/accounts/resolve-orphaned-organization.md +++ b/docs/organizations/accounts/resolve-orphaned-organization.md @@ -1,14 +1,14 @@ --- title: Assign an owner to an orphaned organization titleSuffix: Azure DevOps Services -ms.custom: seodec18 description: Learn how to assign a new owner to an organization when the current owner's inactive. ms.subservice: azure-devops-organizations ms.assetid: b81adafa-adac-4e80-baa6-140fb58fbeff ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 12/12/2022 +ai-usage: ai-assisted +ms.date: 10/24/2024 monikerRange: 'azure-devops' --- @@ -16,74 +16,82 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -When the organization owner and all project collection administrators are inactive, the organization is considered orphaned. An orphaned organization doesn't have an administrator, so there's no way of transferring administrator rights to another user. +When the organization owner and all project collection administrators are inactive, the organization is considered orphaned. An orphaned organization doesn't have an administrator, so there's no way to transfer administrator rights to another user. -But, organizations that are connected to Azure AD can transfer ownership to an active user. +But, organizations connected to Microsoft Entra ID can transfer ownership to an active user. > [!NOTE] -> If your organization isn't considered orphaned and you want to change the owner, then see [Change organization owner](change-organization-ownership.md). +> If your organization isn't considered orphaned and you want to change the owner, see [Change organization owner](change-organization-ownership.md). ## Prerequisites -- You must be an [Azure DevOps Administrator](/azure/active-directory/users-groups-roles/directory-assign-admin-roles#azure-devops-administrator) in Azure AD. If you're using [Privileged Identity Management,](/azure/active-directory/privileged-identity-management/pim-configure?msclkid=303229fdc6c111ecaf0f666b2dd9cd6f) then the Azure DevOps Administrator must be of type [Active](/azure/active-directory/privileged-identity-management/pim-how-to-add-role-to-user?msclkid=5cdc55f5c6c011eca737e344cbe17b42). It isn't a requirement to be a Project Collection Administrator. -- The Azure DevOps Administrator role can only claim ownership of organizations when the current owner and all members of the Project Collection Administrators group are inactive in the backing Azure AD. Azure DevOps and Azure AD define inactive user accounts the same. For more information, see [What are inactive user accounts?](/azure/active-directory/reports-monitoring/howto-manage-inactive-user-accounts) +| Category | Requirements | +|--------------|-------------| +|**Permissions**|[Azure DevOps Administrator in Microsoft Entra ID](/azure/active-directory/roles/permissions-reference). If using [Privileged Identity Management](/azure/active-directory/privileged-identity-management/pim-configure?msclkid=303229fdc6c111ecaf0f666b2dd9cd6f), the Azure DevOps Administrator should be of type [Active](/azure/active-directory/privileged-identity-management/pim-how-to-add-role-to-user?msclkid=5cdc55f5c6c011eca737e344cbe17b42). Being a Project Collection Administrator isn't required.| + +> [!NOTE] +> Claim ownership of organizations only when the current owner and all members of the Project Collection Administrators group are inactive in the backing Microsoft Entra ID. Azure DevOps and Microsoft Entra ID define inactive user accounts the same way. For more information, see [What are inactive user accounts?](/azure/active-directory/reports-monitoring/howto-manage-inactive-user-accounts). + ### Find your Azure DevOps Administrator -If you don't know who the Azure DevOps Administrator is for your organization, follow these steps to find out. +If you don't know who the Azure DevOps Administrator is for your organization, do the following steps: +1. Sign in to the [Azure portal](https://portal.azure.com/). +2. Go to the Microsoft Entra ID section as described in [View and assign administrator roles in Microsoft Entra ID](/azure/active-directory/users-groups-roles/directory-manage-roles-portal). +3. Look for users assigned to the Azure DevOps Administrator role. For more information about Microsoft Entra roles, see [Administrator role permissions in Microsoft Entra ID](/azure/active-directory/users-groups-roles/directory-assign-admin-roles). -1. To find your Azure DevOps Administrator, go to the [Azure portal](https://portal.azure.com/), as described in [View and assign administrator roles in Azure AD](/azure/active-directory/users-groups-roles/directory-manage-roles-portal). For more information about Azure AD roles, see [Administrator role permissions in Azure AD](/azure/active-directory/users-groups-roles/directory-assign-admin-roles). -2. The Azure DevOps Administrator can now complete the steps in [Change Azure DevOps owner](change-organization-ownership.md) to claim ownership of the target Azure DevOps organization. +Once you identify the Azure DevOps Administrator, they can [Change the Azure DevOps owner](change-organization-ownership.md) to claim ownership of the target Azure DevOps organization. ## When you don't have an Azure DevOps Administrator -When your Azure AD tenant hasn't assigned an Azure DevOps Administrator, complete the following steps. +When your Microsoft Entra tenant doesn't have an Azure DevOps Administrator, do the following steps: -1. Find your Azure AD Global Administrator or Privileged Role Administrator. These administrators can be found in the [Azure portal](https://portal.azure.com/), as described in [View and assign administrator roles in Azure AD](/azure/active-directory/users-groups-roles/directory-manage-roles-portal). To learn more about Azure AD roles, see [Administrator role permissions in Azure AD](/azure/active-directory/users-groups-roles/directory-assign-admin-roles). -2. Ask the Azure AD Global Administrator or Privileged Role Administrator to assign the Azure DevOps Administrator role to the appropriate user(s). +1. Locate your Microsoft Entra Global Administrator or Privileged Role Administrator. You can find these administrators in the [Azure portal](https://portal.azure.com/), as described in [View and assign administrator roles in Microsoft Entra ID](/azure/active-directory/users-groups-roles/directory-manage-roles-portal). For more information, see [Administrator role permissions in Microsoft Entra ID](/azure/active-directory/users-groups-roles/directory-assign-admin-roles). +2. Request that your Privileged Role Administrator assigns the Azure DevOps Administrator role to the appropriate users. > [!NOTE] - > Any changes to role membership may take up to an hour to propagate to Azure DevOps. + > Any changes to role membership might take up to an hour to propagate to Azure DevOps. -3. The Azure DevOps Administrator can now complete the steps in [Change Azure DevOps owner](change-organization-ownership.md) to claim ownership of the target Azure DevOps organization. +3. Complete the steps in [Change Azure DevOps owner](change-organization-ownership.md) to claim ownership of the target Azure DevOps organization as the Azure DevOps Administrator. ## When your Azure DevOps Administrator is a member of the target organization -Complete the following steps when your Azure DevOps Administrator in Azure AD *is* a member of the target Azure DevOps organization. +When your Azure DevOps Administrator in Microsoft Entra ID *is* a member of the target Azure DevOps organization, do the following steps. 1. As the Azure DevOps Administrator, sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Select **Organization settings**, and then **Overview**. +2. Select **Organization settings** > **Overview**. -3. Within the warning message, select **Change owner**. +3. In the warning message, select **Change owner**. - ![Screenshot of warning, PCA and Owner inactive in Azure AD.](media/change-organization-ownership/warning-message-change-owner.png) + ![Screenshot of warning, PCA and Owner inactive in Microsoft Entra ID.](media/change-organization-ownership/warning-message-change-owner.png) 4. Select a user from the dropdown menu, or search for a user by entering the user's name, provide a short justification, and then select **Change**. ![Screenshot of button highlighted by red box, Change owner.](media/change-organization-ownership/change-organization-owner.png) -A notification of the ownership transfer with your provided justification gets sent to all Azure DevOps Administrators in your Azure AD. +A notification of the ownership transfer with your provided justification gets sent to all Azure DevOps Administrators in your Microsoft Entra ID. ## When your Azure DevOps Administrator isn't a member of the target organization -Complete the following steps when your Azure DevOps Administrator in Azure AD *isn't* a member of the target Azure DevOps organization. +When your Azure DevOps Administrator in Microsoft Entra ID *isn't* a member of the target Azure DevOps organization, do the following steps: -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) using the credentials granted to the Azure DevOps Administrator role in Azure AD. - An error page appears where you can Claim Ownership. +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) using the credentials granted to the Azure DevOps Administrator role in Microsoft Entra ID. + + An error page appears where you can claim ownership. - ![Screenshot of 401 message: Azure AD Administrator not member of organization.](media/change-organization-ownership/error-message-administrator-not-member-of-organization.png) + ![Screenshot of 401 message: Microsoft Entra Administrator not member of organization.](media/change-organization-ownership/error-message-administrator-not-member-of-organization.png) -2. Select **Claim Ownership**. Provide a short justification, and then select **Claim Ownership** once again. All Azure DevOps Administrators in your Azure AD receive a notification of the ownership transfer, which includes your provided justification. +2. Select **Claim Ownership**, provide a short justification, and then select **Claim Ownership** once again. + + A notification of the ownership transfer with your provided justification gets sent to all Azure DevOps Administrators in your Microsoft Entra ID. ![Screenshot showing empty box, where you enter justification and claim ownership of the organization.](media/change-organization-ownership/claim-ownership.png) - A notification of the ownership transfer with your provided justification is sent to all Azure DevOps Administrators in your Azure AD. - - You're redirected to the organization overview page. If you want to transfer ownership to another user, see [Change organization owner](change-organization-ownership.md). + You're redirected to the organization overview page. To transfer ownership to another user, see [Change organization owner](change-organization-ownership.md). ## Related articles -- [Change organization owner](change-organization-ownership.md) -- [Administrator role permissions in Azure AD](/azure/active-directory/users-groups-roles/directory-assign-admin-roles). -- [Delete your organization](delete-your-organization.md) -- [Get list of organizations backed by Azure AD](get-list-of-organizations-connected-to-azure-active-directory.md) +- [Change the organization owner](change-organization-ownership.md) +- [Review administrator role permissions in Microsoft Entra ID](/azure/active-directory/users-groups-roles/directory-assign-admin-roles) +- [Delete an organization](delete-your-organization.md) +- [Get a list of organizations backed by Microsoft Entra ID](get-list-of-organizations-connected-to-azure-active-directory.md) \ No newline at end of file diff --git a/docs/organizations/accounts/set-up-vs.md b/docs/organizations/accounts/set-up-vs.md index 09265bad1f9..57d60552c26 100644 --- a/docs/organizations/accounts/set-up-vs.md +++ b/docs/organizations/accounts/set-up-vs.md @@ -1,14 +1,13 @@ --- title: Set up Visual Studio with Azure DevOps Services titleSuffix: Azure DevOps Services -ms.custom: seodec18 description: Learn how to set up and connect Visual Studio via Azure DevOps Services. ms.subservice: azure-devops-organizations ms.assetid: abf70640-8fb2-4def-9237-21276a39b5ad -ms.topic: conceptual +ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 04/01/2020 +ms.date: 10/24/2024 monikerRange: 'azure-devops' --- @@ -16,94 +15,71 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -When you first open [Visual Studio 2015](https://visualstudio.microsoft.com/products/vs-2015-product-editions), -you can sign in and connect to [Azure DevOps Services](https://visualstudio.microsoft.com/products/visual-studio-team-services-vs). +When you first open [Visual Studio 2022](https://visualstudio.microsoft.com/vs/), you can sign in and connect to [Azure DevOps Services](https://azure.microsoft.com/services/devops/). -If you're already signed in to Visual Studio or using Visual Studio 2017, [connect to Azure DevOps Services](../../repos/git/gitquickstart.md). +If you're already signed in to Visual Studio 2019, see [connect to Azure DevOps Services](../../repos/git/gitquickstart.md). -Once you're connected, you can store or share code in free, unlimited, private, -cloud-based Git repositories or Team Foundation Version Control (TFVC). -Organize and manage your work with Agile tools for DevOps, -continuous integration, and continuous delivery. Your team can build often, -test early, and ship faster. +Once connected, you can store and share code in free, unlimited, private, cloud-based Git repositories or Team Foundation Version Control (TFVC). Use Agile tools for DevOps, continuous integration, and continuous delivery to organize and manage your work, which helps your team build frequently, test early, and ship faster. -> To set up Visual Studio without Azure DevOps Services, -> learn how to [get started](/visualstudio/install/install-visual-studio-2015). -> To host your own server, -> learn how to [install and set up Azure DevOps Server](/azure/devops/server/install/get-started). +To set up Visual Studio without Azure DevOps Services, see [Install Visual Studio](/visualstudio/install/install-visual-studio?view=vs-2022&preserve-view=true). To host your own server, [install and set up Azure DevOps Server](/azure/devops/server/install/get-started). -Azure DevOps Services is free for [up to five users with access to Basic features](https://visualstudio.microsoft.com/products/visual-studio-team-services-feature-matrix-vs) and for unlimited [Visual Studio subscribers](https://visualstudio.microsoft.com/products/how-to-buy-vs) and [Stakeholders who can access limited features](https://visualstudio.microsoft.com/products/visual-studio-team-services-feature-matrix-vs). -Learn [what else you get with Azure DevOps Services](https://visualstudio.microsoft.com/pricing/visual-studio-team-services-pricing-vs). -If you want, you can also use Azure DevOps Services with any IDE or code editor, like the following examples: +You can also use Azure DevOps Services with any IDE or code editor, like the following examples: * [Eclipse, Android Studio, or IntelliJ](/azure/devops/pipelines/ecosystems/java) * Xcode (see [Git](../../repos/git/share-your-code-in-git-xcode.md) or [TFVC](../../repos/tfvc/share-your-code-in-tfvc-xcode.md)) * [Visual Studio Code](https://code.visualstudio.com/docs/editor/versioncontrol) -## How do I set up Visual Studio 2015 for Azure DevOps Services when I sign in? +## Prerequisites -1. [Download and install Visual Studio](https://go.microsoft.com/fwlink/?LinkId=309297&clcid=0x409&slcid=0x409), -if you don't have the version you want already. -[Which versions can I use with Azure DevOps Services?](./faq-set-up-vs.yml) +| Category | Requirements | +|--------------|-------------| +|**Tools**| [Visual Studio](https://go.microsoft.com/fwlink/?LinkId=309297&clcid=0x409&slcid=0x409). If you have a Visual Studio subscription that includes the Visual Studio IDE, get the version that's available with your subscription.| - If you have a Visual Studio subscription that - includes the Visual Studio IDE, get the version - that's available with your subscription. +## Set up Visual Studio 2022 for Azure DevOps Services -2. Start Visual Studio, and then sign in to create your profile. +1. Start Visual Studio, and then sign in to create your profile. - This profile saves your settings and roams with you - when you sign in to Visual Studio on any computer. - [Why else should I sign in?](./faq-set-up-vs.yml) - If you're a Visual Studio subscriber, use the sign in address for your subscription. + This profile saves your settings and roams with you when you sign in to Visual Studio on any computer. [Why else should I sign in?](./faq-set-up-vs.yml) If you're a Visual Studio subscriber, use the sign in address for your subscription. - ![Sign in to Visual Studio](media/set-up-vs/sign-in-visual-studio.png) + ![Screenshot shows Visual Studio sign in prompt.](media/set-up-vs/sign-in-visual-studio.png) [Can't sign in?](/azure/devops/organizations/accounts/faq-set-up-vs#t-i-assign-azure-devops-permissions-directly-to-an-azure-ad-group-) -3. Enter your sign in address, -and then enter your password. +2. Enter your credentials. -4. Add your Visual Studio profile details. You only need to add these details once. +3. Add your Visual Studio profile details. You only need to do this action once. - ![Create your profile](media/set-up-vs/profile-organization-details.png) + ![Screenshot shows Create your profile screen.](media/set-up-vs/profile-organization-details.png) -5. Give your organization a name, and confirm its location. +4. Name your organization and confirm its location. - ![Name your organization, confirm its location](media/set-up-vs/profile-organization-details2.png) + ![Screenshot shows naming your organization and confirming its location.](media/set-up-vs/profile-organization-details2.png) [How can I create an organization later](faq-configure-customize-organization.yml#create-organization-faqs) or [change its location?](change-organization-location.md) -6. Create your first project to store your code, -work items, backlog, builds, tests, and other assets. -Name your project, select a process to organize your work, -and choose the version control to manage your code. +5. Create your first project to store your code, work items, backlog, builds, tests, and other assets. Name your project, select a process to organize your work, and choose a version control to manage your code. - ![Create your project](media/set-up-vs/create-team-project-vs.png) + :::image type="content" source="media/set-up-vs/create-team-project-vs.png" alt-text="Screenshot shows creating new project."::: - Not sure which to choose? Learn which - [process](../../boards/work-items/guidance/choose-process.md) - and version control ([Git](../../repos/git/index.yml) - or [TFVC](../../repos/tfvc/index.yml)) - work best for you. + Not sure which to choose? Learn which [process](../../boards/work-items/guidance/choose-process.md) and version control, [Git](../../repos/git/index.yml) or [TFVC](../../repos/tfvc/index.yml), work best for you. -7. If you're a new Visual Studio user, you can change your settings here, -or change them later in Visual Studio options. +6. If you're a new Visual Studio user, you can change your settings anytime in Visual Studio options. - ![Change settings, if you want](media/set-up-vs/hellonewprofile.png) + :::image type="content" source="media/set-up-vs/hellonewprofile.png" alt-text="Screenshot shows option to change settings."::: - These changes are saved with your profile, - and your settings roam with you wherever you sign in. + These changes get saved with your profile and your settings roam with you wherever you sign in. -8. To view your new organization, sign in to ```https://dev.azure.com/{yourorganization}```. +7. To view your new organization, sign in to ```https://dev.azure.com/{Your_Organization}```. ## Next steps > [!div class="nextstepaction"] - > [Add users to your organization](add-organization-users.md) +> [Add users to your organization](add-organization-users.md) ## Related articles -* Add code to [Git](../../repos/git/share-your-code-in-git-vs.md) or [TFVC](../../repos/tfvc/share-your-code-in-tfvc-vs.md). - -* [Create your backlog](../../boards/backlogs/create-your-backlog.md) to organize your work, [manage your process](../../organizations/settings/work/manage-process.md), or [customize your process](../../organizations/settings/work/customize-process.md). +* [Add code to Git](../../repos/git/share-your-code-in-git-vs.md) +* [Add code to TFVC](../../repos/tfvc/share-your-code-in-tfvc-vs.md) +* [Create your backlog](../../boards/backlogs/create-your-backlog.md) +* [Manage your process](../../organizations/settings/work/manage-process.md) +* [Customize your process](../../organizations/settings/work/customize-process.md) diff --git a/docs/organizations/accounts/toc.yml b/docs/organizations/accounts/toc.yml index e3d5201e09a..fd9f2c22401 100644 --- a/docs/organizations/accounts/toc.yml +++ b/docs/organizations/accounts/toc.yml @@ -28,7 +28,7 @@ - name: Change organization owner displayName: update, reassign, Project Collection Administrator, owner href: change-organization-ownership.md - - name: Change organization region + - name: Change organization geography displayName: update, reassign, region, geography, location, Virtual Support Agent href: change-organization-location.md - name: Change time zone @@ -60,3 +60,12 @@ - name: Create and configure an organization displayName: create, configure, delete, restore, owner, browser, region, name, location, features, project, data protection, subscription href: faq-configure-customize-organization.yml + - name: Manage users and permissions + displayName: user, permission, role, access, project, collection, administrator, owner, member, guest, external, Azure Active Directory, group, team, security, policy, token, authentication, authorization, identity, organization, account, profile, settings, data, protection + href: faq-user-and-permissions-management.yml + - name: Access via Microsoft Entra + displayName: access, Microsoft Entra, organization, account, sign in, sign out, browser, device, mobile, desktop, tablet + href: faq-azure-access.yml + - name: Set up Visual Studio + displayName: Visual Studio, protocol, connection, Azure DevOps, project + href: faq-set-up-vs.yml diff --git a/docs/organizations/accounts/usage-monitoring.md b/docs/organizations/accounts/usage-monitoring.md index 4750e6bba58..d771f5a6d1e 100644 --- a/docs/organizations/accounts/usage-monitoring.md +++ b/docs/organizations/accounts/usage-monitoring.md @@ -6,83 +6,93 @@ ms.subservice: azure-devops-organizations ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 06/09/2021 +ms.date: 10/24/2024 monikerRange: 'azure-devops' --- -# Usage monitoring +# Monitor usage [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -You can investigate the usage of your users in Azure DevOps Services. Usage monitoring is important to identify causes for bandwidth bottlenecks, that aren't caused by faulty systems. See the following most common commands or operations that might trigger a usage message. - -- Requests that were delayed -- Requests that exceeded thresholds +Monitoring usage in Azure DevOps Services is crucial for identifying and addressing performance bottlenecks. By understanding the common commands and operations that trigger usage messages, you can optimize your tools and processes to ensure efficient use of resources. Regularly reviewing the usage page and audit logs helps maintain the performance and reliability of your Azure DevOps environment. ## Prerequisites -You must be a member of the Project Collection Administrators group to view the Usage page. - -## Usage concepts +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] -When a user's request is delayed by a significant amount of time, that user gets a notification email. There's also a warning banner displayed on the web. Both the warning banner and notification email have a link to the usage page. If the user doesn't have an email address, the notification email gets sent to the Project Collection Administrators group members. +> [!NOTE] +> To view usage from an audit perspective, see [Access, export, and filter audit logs](../../organizations/audit/azure-devops-auditing.md). This view doesn't include TSTUs but retains data for 90 days. -Commands that consume a high number of Azure DevOps throughput units (TSTUs) (in the hundreds, for example) are responsible for the user exceeding the threshold. The User Agent and IP address columns can be helpful to see where these commands are coming from. Custom tools or build service accounts might be making a large number of calls in a short time window. - -To avoid issues, you may need to rewrite tools or update build processes. This action reduces the type and number of calls. For example, a tool may be pulling a large version control repository from scratch regularly, when it could pull incrementally instead. - -- Request history on the Usage page is in descending order by default. -- Usage is grouped by command into five-minute time windows. -- The Count column gives the number of commands in the window. -- Other columns highlight total TSTUs and delay time. - -For information on rate limits, see [Current rate limits](../../integrate/concepts/rate-limits.md#current-rate-limits). +For more information, see [Rate and usage limits](../../integrate/concepts/rate-limits.md). ## View usage -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings** > **Usage**. - :::image type="content" source="media/usage-pca-newnav.png" alt-text="Screenshot of Usage page for collection administrators."::: + :::image type="content" source="media/usage-pca-newnav.png" alt-text="Screenshot of Usage page for collection administrators."::: -3. Use this page to investigate the usage of other users. Usage can occur from regular web portal operations or use of command line or REST API tools. +3. Use this page to investigate the usage of other users. Usage can occur from regular web portal operations or the use of command line or REST API tools. - a. View by the following categories: - - Usage By User - - Usage By Pipeline - - Top user agents - - Top commands - - Top Build Pipelines - - Top Release Pipelines + a. View by the following categories: + - Usage by user + - Usage by pipeline + - Top user agents + - Top commands + - Top build pipelines + - Top release pipelines - b. Filter by the following column options: - - User - - User agent - - IP address - - Time range - - ServiceApplication - - Command - - Status - - Count - - Usage (TSTUs) - - Delay(s) + b. Filter by the following column options: + - User + - User agent + - IP address + - Time range + - Service + - Application + - Referrer + - Command + - UriStem + - Status + - Count + - Usage (TSTUs) + - Delay (s) Azure DevOps displays the last hour of requests by default. You can select from other increments of time. - d. Select from the following statuses: - - All statuses - - Normal - - Delayed - - Blocked + c. Select from the following statuses: + - All statuses + - Normal + - Delayed + - Blocked + + d. The usage page is scoped to the 30 minutes before and after the first delayed request. Review the request history leading up to delayed requests. - e. The usage page is scoped to the 30 minutes before and after the first delayed request. Review the request history leading up to delayed requests. + :::image type="content" source="media/usage-screenshot-example.png" alt-text="Screenshot of usage page example."::: - :::image type="content" source="media/usage-screenshot-example.png" alt-text="Usage page screenshot example"::: +### Understand notifications and alerts +- When a user's request gets delayed, they receive a notification email and see a warning banner on the web. Both the banner and email link to the usage page. +- When a user doesn't have an email address, the notification gets sent to the Project Collection Administrators group members. + +### Identify high usage +- Commands consuming a high number of Azure DevOps throughput units (TSTUs) can cause users to exceed thresholds. +- The User Agent and IP address columns help identify the source of these commands. Custom tools or build service accounts might be making numerous calls in a short time window. + +### Optimize tools and processes + +To avoid issues, consider rewriting tools or updating build processes to reduce the type and number of calls. For example, instead of pulling a large version control repository from scratch regularly, pull incrementally. + +### Understand usage page details + +- Request history on the `Usage` page is in descending order by default. +- Usage gets grouped by command into five-minute time windows. +- The `Count` column shows the number of commands in the window. +- Other columns highlight total TSTUs and delay time. ## Related articles - [Work tracking, process, and project limits](../settings/work/object-limits.md) - [Access, export, and filter Azure DevOps audit logs](../audit/azure-devops-auditing.md) - [About Settings at the user, team, project, and organizational level](../settings/about-settings.md) -- [Get list of organizations backed by Azure AD](get-list-of-organizations-connected-to-azure-active-directory.md) +- [Get list of organizations backed by Microsoft Entra ID](get-list-of-organizations-connected-to-azure-active-directory.md) + diff --git a/docs/organizations/accounts/use-personal-access-tokens-to-authenticate.md b/docs/organizations/accounts/use-personal-access-tokens-to-authenticate.md index 5f3d4fdbfb7..7703d3c2936 100644 --- a/docs/organizations/accounts/use-personal-access-tokens-to-authenticate.md +++ b/docs/organizations/accounts/use-personal-access-tokens-to-authenticate.md @@ -1,14 +1,15 @@ --- title: Use personal access tokens titleSuffix: Azure DevOps -ms.custom: contperf-fy20q4, contperf-fy22q3 +ms.custom: ai-video-demo +ai-usage: ai-assisted description: Learn how to create and manage personal access tokens (PATs) as alternate passwords to authenticate to Azure DevOps. ms.subservice: azure-devops-security ms.assetid: d980d58e-4240-47c7-977c-baaa7028a1d8 ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 06/20/2023 +ms.date: 03/10/2025 monikerRange: '<= azure-devops' --- @@ -16,60 +17,130 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can use a personal access token (PAT) as an alternate password to authenticate into Azure DevOps. In this article, we show you how to create, use, modify, and revoke PATs for Azure DevOps. +A Personal Access Token (PAT) serves as an alternative password for authenticating into Azure DevOps. This PAT identifies you and determines your accessibility and scope of access. Therefore, treat PATs with the same level of caution as passwords. -## About PATs +[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] -A personal access token contains your security credentials for Azure DevOps. A PAT identifies you, your accessible organizations, and scopes of access. As such, they're as critical as passwords, so you should treat them the same way. +When you use Microsoft tools, your Microsoft account (MSA) or Microsoft Entra ID is recognized and supported. If you use tools that don't support Microsoft Entra accounts or don't want to share your primary credentials, PATs can be a suitable alternative. However, we recommend using [Microsoft Entra tokens](../../integrate/get-started/authentication/entra.md) over PATs whenever possible. -If you're working within Microsoft tools, then your Microsoft account (MSA) or Azure Active Directory (Azure AD) is an acceptable and well-supported approach. But, if you're working with third-party tools that don't support Microsoft or Azure AD accounts – or you don't want to provide your primary credentials to the tool – use PATs to limit your risk. +You can manage PATs through the following methods: +* **User interface (UI):** Through user settings, as detailed in this article. +* [**PAT Lifecycle Management APIs**](manage-personal-access-tokens-via-api.md) +* [Git credential managers](../../repos/git/set-up-credential-managers.md) for Git operations. Credential managers facilitate token management. Without one, users must input their credentials each time. -You can create and manage your PATs through one of the following ways: +## Prerequisites -* the user interface in your user settings, which is described in detail in this article -* through the [PAT Lifecycle Management API](manage-personal-access-tokens-via-api.md) - -To set up PATs for non-Microsoft tools, use [Git credential managers](../../repos/git/set-up-credential-managers.md) or create them manually. We recommend that you review our [authentication guidance](../../integrate/get-started/authentication/authentication-guidance.md) to help you choose the correct authentication mechanism. For smaller projects that require a less robust solution, PATs are a simple alternative. Unless your users are using a credential manager, they have to enter their credentials each time. +| Category | Requirements | +|--------------|-------------| +|**Permissions** |Permission to access and modify your user settings where PATs are managed.
      - Go to **your profile** and select **User settings** > **Personal access tokens**. If you can see and manage your PATs here, you have the necessary permissions.
      - Go to your project and select **Project settings** > **Permissions**. Find your user account in the list and check the permissions assigned to you. Look for permissions related to managing tokens or user settings.
      - If your [organization has policies in place](manage-pats-with-policies-for-administrators.md), an Azure DevOps Administrator might need to grant you specific permissions or add you to an allowlist to create and manage PATs.
      - PATs are connected to the user account that minted the token. Depending on the tasks the PAT performs, you might need more permissions yourself.| +|**Access levels** |At least **Basic** access.| +|**Tasks**|**Use PATs only when necessary and always regularly rotate them.**| [!INCLUDE [personal-access-tokens](../../repos/git/includes/personal-access-tokens.md)] -## Related articles +## Changes to format -* [About security, authentication, and authorization](../security/about-security-identity.md) -* [Default permissions and access for Azure DevOps](../security/permissions-access.md) -* [Revoke user PATs (for admins)](admin-revoke-user-pats.md) -* [Manage service principals and managed identities in Azure DevOps](../../integrate/get-started/authentication/service-principal-managed-identity.md) +As of July 2024, we significantly changed the format of PATs issued by Azure DevOps. These changes provide more security benefits and improve secret detection tooling available through our [leaked PAT detection tooling](manage-pats-with-policies-for-administrators.md#revoke-leaked-pats-automatically) or [partner offerings](../../repos/security/github-advanced-security-secret-scanning.md). This new PAT format follows the recommended format across all Microsoft products. The inclusion of more identifiable bits improves the false positive detection rate of these secret detection tools and enables us to mitigate detected leaks faster. + +Key changes: +* **Increased token length:** The new tokens are now **84** characters long, with 52 characters being randomized data. This increased length improves overall entropy, making the tokens more resistant to potential brute force attacks. +* **Fixed signature:** Tokens issued by our service include a fixed `AZDO` signature at positions 76-80. + +Action required: +* **Regenerate existing PATs:** We strongly recommend regenerating all PATs currently in use to take advantage of these security enhancements. +* **Integrator support:** Integrators should update their systems to accommodate both the new and existing token lengths. + +> [!IMPORTANT] +> Both formats remain valid for the foreseeable future, but we **actively encourage customers to transition to the new 84-character format**. As adoption of the new format increases, we consider retiring the older 52-character format and all tokens issued in that style. + +## Best practices for using PATs + +### Consider alternatives + +* Acquire a Microsoft Entra token via [Azure CLI](../../integrate/get-started/authentication/entra.md#ad-hoc-requests-to-azure-devops-rest-apis) for ad-hoc requests that lasts for one hour instead of minting a longer-lived PAT. +* Use credential managers like [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager) or [Azure Artifacts Credential Manager](https://github.com/microsoft/artifacts-credprovider) for credential management simplification. These tools might offer options to [use Microsoft Entra tokens](../../integrate/get-started/authentication/entra.md) as the default authentication instead of PATs. + +### Creating PATs + +* Avoid putting personal data in the PAT name. Don't rename the PAT token string as the name of your token. +* Select only the organization your PAT needs to access if it doesn't need to access multiple organizations. For workflows requiring access to multiple organizations, create a separate global PAT for that workflow. +* Choose only the necessary scopes for each PAT. If possible, create multiple PATs for each workflow with fewer scopes instead of a single fully scoped PAT. If your PAT only needs read permissions, don't provide it write permissions until necessary. +* Keep PAT lifespans short (weekly is ideal, even shorter is better) and regularly rotate or regenerate them via the UI or the [PAT Lifecycle Management APIs](manage-personal-access-tokens-via-api.md). + +### Managing PATs + +* **Always** store your PATs in a secure key management solution like [Azure KeyVault](/azure/key-vault/general/overview). +* Revoke PATs when they're no longer needed. Tenant admins can [revoke PATs for their organization users](admin-revoke-user-pats.md) if the PAT is compromised. +* Rotate your PATs to use the [new PAT format](#changes-to-format) for better leaked secret detection and revocation by our first-party tools. -::: moniker range="azure-devops" +### For admins + +[Tenant admins can set policies](manage-pats-with-policies-for-administrators.md) to restrict global PAT creation, full scoped PAT creation, and long-lived PAT duration. They can also enable policies to automatically revoke leaked PATs detected in public repositories. Use these policies to improve your company's security. ## FAQs +### Q: Why can't I edit or regenerate a PAT scoped to a single organization? + +A: Sign into the organization where your PAT is scoped. You can view all your PATs while signed into any organization in the same Microsoft Entra ID, but you can only edit organization-scoped tokens when signed into the specific organization. + ### Q: What happens to a PAT if a user account is disabled? -A: Once a user's removed from Azure DevOps, the PAT is invalidated within 1 hour. If your organization is connected to Azure Active Directory (Azure AD), the PAT is also invalidated in Azure AD, as it belongs to the user. We recommend that the user rotates their PAT to another user or service account to keep services running. +A: When a user is removed from Azure DevOps, the PAT invalidates within 1 hour. If your organization is connected to Microsoft Entra ID, the PAT also invalidates in Microsoft Entra ID, as it belongs to the user. We recommend rotating the PAT to another user or service account to keep services running. ### Q: Is there a way to renew a PAT via REST API? -A: Yes, there's a way to renew, manage, and create PATs using our [PAT Lifecycle Management APIs](manage-personal-access-tokens-via-api.md). For more information, see [Manage PATs using REST API](manage-personal-access-tokens-via-api.md) and our [FAQ](manage-personal-access-tokens-via-api.md#q-how-can-i-regeneraterotate-pats-through-the-api-i-saw-that-option-in-the-ui-but-i-dont-see-a-similar-method-in-the-api). +A: Yes, you can renew, manage, and create PATs using our [PAT Lifecycle Management APIs](manage-personal-access-tokens-via-api.md#q-how-can-i-regeneraterotate-pats-through-the-api-i-saw-that-option-in-the-ui-but-i-dont-see-a-similar-method-in-the-api). -### Q: Can I use basic auth with all Azure DevOps REST APIs? +### Q: Can I use PATs with all Azure DevOps REST APIs? -A: No. You can use basic auth with most Azure DevOps REST APIs, but [organizations and profiles](/rest/api/azure/devops/) only support [OAuth](../../integrate/get-started/authentication/oauth.md). For more information, see [Manage PATs using REST API](manage-personal-access-tokens-via-api.md). +A: No. You can use basic auth with most Azure DevOps REST APIs, but [organizations and profiles](/rest/api/azure/devops/) and the [PAT Management Lifecycle APIs](manage-personal-access-tokens-via-api.md) only support [Microsoft Entra OAuth](../../integrate/get-started/authentication/entra-oauth.md). For an example on how to set up a Microsoft Entra app to call such APIs, see [Manage PATs using the REST API](manage-personal-access-tokens-via-api.md). ### Q: What happens if I accidentally check my PAT into a public repository on GitHub? -A: Azure DevOps scans for PATs checked into public repositories on GitHub. When we find a leaked token, we immediately send a detailed email notification to the token owner and log an event to your Azure DevOps organization's [audit log](../audit/azure-devops-auditing.md#review-audit-log). Unless you disabled the *Automatically revoke leaked personal access tokens* policy, we immediately revoke the leaked PAT. We encourage affected users to mitigate immediately by [revoking the leaked token](use-personal-access-tokens-to-authenticate.md#revoke-a-pat) and replacing it with a new token. - -For more information, see [Revoke leaked PATs automatically](manage-pats-with-policies-for-administrators.md#revoke-leaked-pats-automatically). +A: Azure DevOps scans for PATs checked into public repositories on GitHub. When we find a leaked token, we immediately send a detailed email notification to the token owner and log an event in your Azure DevOps organization's [audit log](../audit/azure-devops-auditing.md#review-audit-log). Unless you disabled the *Automatically revoke leaked personal access tokens* policy, we immediately revoke the leaked PAT. We encourage affected users to mitigate the issue by [revoking the leaked token](use-personal-access-tokens-to-authenticate.md#revoke-a-pat) and replacing it with a new token. For more information, see [Revoke leaked PATs automatically](manage-pats-with-policies-for-administrators.md#revoke-leaked-pats-automatically). ### Q: Can I use a personal access token as an ApiKey to publish NuGet packages to an Azure Artifacts feed using the dotnet/nuget.exe command line? -A: No. Azure Artifacts doesn't support passing a personal access token as an ApiKey. When using a local development environment, we recommended installing the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider) to authenticate with Azure Artifacts. For more information, see the following examples: [dotnet](../../artifacts/nuget/dotnet-exe.md), [NuGet.exe](../../artifacts/nuget/publish.md). -If you want to publish your packages using Azure Pipelines, use the [NuGet Authenticate](/azure/devops/pipelines/tasks/reference/nuget-authenticate-v1) task to authenticate with your feed [example](../../pipelines/artifacts/nuget.md#publish-a-package). +A: No. Azure Artifacts doesn't support passing a PAT as an ApiKey. When using a local development environment, we recommend installing the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider) to authenticate with Azure Artifacts. For more information, see the following examples: [dotnet](../../artifacts/nuget/dotnet-exe.md), [NuGet.exe](../../artifacts/nuget/publish.md). If you want to publish your packages using Azure Pipelines, use the [NuGet Authenticate](/azure/devops/pipelines/tasks/reference/nuget-authenticate-v1) task to authenticate with your feed. See [example](../../pipelines/artifacts/nuget.md). ### Q: Why did my PAT stop working? -A: PAT authentication requires you to regularly sign into Azure DevOps using the full authentication flow. Once every 30 days is sufficient for many, but you may need to sign in more often than that depending upon your Azure Active Directory configuration. If your PAT stops working, first try signing into your organization, ensuring that you go through the full authentication prompt. If your PAT still doesn't work after that, check to see if your PAT has expired. +A: PAT authentication requires you to regularly sign into Azure DevOps using the full authentication flow. Signing in once every 30 days is sufficient for many users, but you might need to sign in more frequently depending on your Microsoft Entra configuration. If your PAT stops working, first try signing into your organization and complete the full authentication prompt. If your PAT still doesn't work, check if it expired. + +Enabling IIS Basic Authentication invalidates using PATs for Azure DevOps Server. +> [!CAUTION] +> We recommend that you keep [IIS Basic Authentication]( /iis/configuration/system.webserver/security/authentication/basicauthentication) turned **off** always. Only if necessary should you enable IIS Basic Authentication. When IIS Basic Authentication is enabled on your windows machine, it prevents you from using personal access tokens (PATs) as an authentication mechanism. + +For example, if you use a PAT to allow a third-party app to retrieve bug information, and then send an email with the info to the bug assignee (with IIS Basic Authentication enabled), the app fails authentication. The app can't retrieve bug info. + +> [!WARNING] +> If you use Git with IIS Basic Authentication, Git breaks because it requires PATs for user authentication. Although we don't recommend you use IIS Basic Authentication, by adding an extra header to Git requests, you can use Git with IIS Basic Authentication. +> +> The extra header must be used for all Azure DevOps Server installations, as Windows Auth also prevents using PATs. +> The extra header must include a base 64 encoding of "user:PAT." See the following format and example. +> +>**Format:** +> +> ``` +> git -c http.extraheader='Authorization: Basic [base 64 encoding of "user:password"]' ls-remote http://tfsserver:8080/tfs/DefaultCollection/_git/projectName +> ``` +> +>**Example:** +> +> ``` +> git -c http.extraheader='Authorization: Basic a2FzYW50aGE6bzN3cDVndmw2YXRkajJkam83Znd4N2k3NDdhbGxjNXp4bnc3b3o0dGQycmd3d2M1eTdjYQ==' ls-remote http://tfsserver:8080/tfs/DefaultCollection/_git/projectName +> ``` -::: moniker-end +### Q: How do I create access keys that aren't tied to a specific person for deployment purposes? + +A: In Azure DevOps, you can create access keys that aren't tied to a specific person by using Service Principals or Managed Identities. For more information, see [Manage service connections](../../pipelines/library/service-endpoints.md) and [Use Azure Key Vault secrets in Azure Pipelines](../../pipelines/release/azure-key-vault.md). + +## Related articles + +* [Use policies to manage personal access tokens for users](manage-pats-with-policies-for-administrators.md) +* [Revoke user PATs (for admins)](admin-revoke-user-pats.md) +* [Learn about security, authentication, and authorization](../security/about-security-identity.md) +* [Review default permissions and access for Azure DevOps](../security/permissions-access.md) +* [Manage personal access tokens (PATs) using REST API](manage-personal-access-tokens-via-api.md) +* [Manage service principals and managed identities in Azure DevOps](../../integrate/get-started/authentication/service-principal-managed-identity.md) diff --git a/docs/organizations/audit/auditing-events.md b/docs/organizations/audit/auditing-events.md index 52cca7d7ce2..2302b8648ad 100644 --- a/docs/organizations/audit/auditing-events.md +++ b/docs/organizations/audit/auditing-events.md @@ -6,9 +6,9 @@ ms.subservice: azure-devops-audit ms.assetid: 9F1D0A0F-02D5-4E06-A5EC-C220472A0F66 ms.author: chcomley author: chcomley -ms.topic: quickstart +ms.topic: conceptual monikerRange: '= azure-devops' -ms.date: 08/03/2022 +ms.date: 11/22/2024 --- # Auditing events list @@ -22,9 +22,9 @@ The following tables describe the type of events (or actions) that are available [!INCLUDE [important-backed-by-azure-active-directory](includes/important-backed-by-azure-active-directory.md)] -* Any given event belongs to a specific *Product Area*. The full list of areas is in the [Area table](#areas). -* An event has a *Category* field that reflects the type of action performed during the event. The list of possible action types is in the [Categories table](#categories). -* The list of all possible actions is grouped by *Product Area* and can be found in the [Actions section](#actions). +* Identify the *Product Area* for any given event. Refer to the full list in the [Area table](#areas). +* Determine the *Category* field of an event to understand the type of action performed. See the list of possible action types in the [Categories table](#categories). +* Find the list of all possible actions grouped by *Product Area* in the [Actions section](#actions). > [!NOTE] > We try our best to keep adding new actions regularly. If you'd like to see an event that isn't currently in the following tables, consider sharing that with us in the [Developer Community](https://developercommunity.visualstudio.com/search?space=21). @@ -33,23 +33,23 @@ The following tables describe the type of events (or actions) that are available | Area | Description | |----------------------------|-------------| -| [Auditing](#auditing) | View and download audit logs. Access, create, modify, enable, disable, and delete audit streams. | -| [Billing](#billing) | Add, change, or remove Azure Subscriptions. Modify billing quantities for Pipelines, Artifacts, and Cloud Load Test usage. | -| [Checks](#checks) | Create, modify, delete, and track usage of checks including approvals on protected resources in Azure Pipelines (YAML only). | -| [Extension](#extension) | Install, modify, enable, disable, and uninstall extensions for Extensions Marketplace. | -| [Git](#git) | Create, modify, enable, disable, fork, delete and undelete Git repositories in Azure Repos. Bypass PR policies. Change branch policies. | -| [Group](#group) | Create groups and modify group memberships. | -| [Library](#library) | Create, modify, delete, and track usage of service connections, variable groups, secure files, and agent pools in Azure Pipelines. | -| [Licensing](#licensing) | Assign, modify, and remove licensing. Create, modify, and delete group licensing rules. | -| [Organization](#organization)| Create and modify Azure DevOps organization. Link and unlink to Azure Active Directory organizations. | -| [OrganizationPolicy](#organizationpolicy) | Add, modify, or remove organization policies. | -| [Permissions](#permissions)| Modify or remove permissions and access control lists for users and groups throughout an Azure DevOps organization. | -| [Pipelines](#pipelines) | Create, modify, and delete Pipelines in Azure Pipelines. Authorize and unauthorize resource for projects and pipelines. Modify pipeline retention settings. Retain and unretain pipeline runs. | -| [Policy](#policy) | Create, modify, and delete policies for a Git repository in Azure Repos. | -| [Process](#process) | Create, modify, and delete attributes for processes (portfolio backlogs, controls, fields, groups, lists, pages, processes, rules, states, control settings, work items, etc.) in Azure Boards. | -| [Project](#project) | Create, modify, change visibility of, delete, and restore projects in Azure Boards. Create, modify, and delete Area paths. | -| [Release](#release) | Create, modify, and delete releases and release pipelines in Azure Pipelines. Track deployments and deployment approvals. | -| [Token](#token) | Create, modify, revoke, and delete Personal Access Tokens (PATs) or SSH Keys. Track public repository discovery and system revocations of PATs. Token access events aren't currently logged. | +| [Artifacts events](#artifacts-events) | Create, modify permissions, and delete feed views and both organization-scoped and project-scoped feeds. | +| [AuditLog events](#auditlog-events) | View and download audit logs. Access, create, modify, enable, disable, and delete audit streams. | +| [Billing events](#billing-events) | Add, change, or remove Azure Subscriptions. Modify billing quantities for Pipelines, Artifacts, and Cloud Load Test usage. | +| [Extension events](#extension-events) | Install, modify, enable, disable, and uninstall extensions for Extensions Marketplace. | +| [Git licensing events](#git-licensing-events) | Create, modify, enable, disable, fork, delete, and undelete Git repositories in Azure Repos. Bypass PR policies. Change branch policies. | +| [Group events](#group-events) | Create groups and modify group memberships. | +| [Library events](#library-events) | Create, modify, delete, and track usage of service connections, variable groups, secure files, and agent pools in Azure Pipelines. | +| [Licensing events](#licensing-events) | Assign, modify, and remove licensing. Create, modify, and delete group licensing rules. | +| [Organization events](#organization-events)| Create and modify Azure DevOps organization. Link and unlink to Microsoft Entra organizations. | +| [OrganizationPolicy events](#organizationpolicy-events) | Add, modify, or remove organization policies. | +| [Pipelines events](#pipelines-events) | Create, modify, delete, and track usage of checks including approvals on protected resources in Azure Pipelines (YAML only). | +| [Policy events](#policy-events) | Create, modify, and delete policies for a Git repository in Azure Repos. | +| [Process events](#process-events) | Create, modify, and delete attributes for processes (portfolio backlogs, controls, fields, groups, lists, pages, processes, rules, states, control settings, work items, etc.) in Azure Boards. | +| [Project events](#project-events) | Create, modify, change visibility of, delete, and restore projects in Azure Boards. Create, modify, and delete Area paths. | +| [Release events](#release-events) | Create, modify, and delete releases and release pipelines in Azure Pipelines. Track deployments and deployment approvals. | +| [Security events](#security-events) | Create, modify, and delete Pipelines in Azure Pipelines. Authorize and unauthorize resource for projects and pipelines. Modify pipeline retention settings. Retain and unretain pipeline runs. | +| [Token events](#token-events) | Create, modify, revoke, and delete Personal Access Tokens (PATs) or SSH Keys. Track public repository discovery and system revocations of PATs. Token access events aren't currently logged. | ## Categories @@ -65,267 +65,300 @@ The following tables describe the type of events (or actions) that are available ## Actions > [!NOTE] -> Want to find out what actions your organization logs? Be sure to check out the [Audit Log Query API](/rest/api/azure/devops/audit/audit-log/query): `https://auditservice.dev.azure.com/{YOUR_ORGANIZATION}/_apis/audit/actions`, replacing {YOUR_ORGANIZATION} with the name of your organization. This API returns a list of all audit events your organization could emit. - -### Auditing - -| ActionId | Category | Details | -|-----------|----------|----------| -|AuditLog.AccessLog | Access | Accessed the audit log | -|AuditLog.DownloadLog | Access | Downloaded a {Format} copy of the audit log | -|AuditLog.StreamCreated | Create | Stream for {ConsumerType:consumerType} was set up to send auditing events to {displayName}. | -|AuditLog.StreamDeleted | Remove | Stream for {ConsumerType:consumerType} to send auditing data to {displayName} was deleted. | -|AuditLog.StreamDisabledBySystem | Modify | Stream for {ConsumerType:consumerType} to send auditing data to {displayName} was disabled by the system. | -|AuditLog.StreamDisabledByUser | Modify | Stream for {ConsumerType:consumerType} to send auditing data to {displayName} was disabled. | -|AuditLog.StreamEnabled | Modify | Stream for {ConsumerType:consumerType} to send auditing data to {displayName} was enabled. | -|AuditLog.StreamModified | Modify | Stream for {ConsumerType:consumerType} to send auditing data to {displayName} was modified.| -|AuditLog.StreamRead | Access | Accessed auditing streams. | -|AuditLog.TestStream | Create | {ResolveIdentity:ActorId} initiated a {StreamConsumerType} stream connection test from {OrganizationName} in Azure DevOps.| - -### Billing -| ActionId | Category | Details | -|-----------|----------|----------| -| Billing.BillingModeUpdate | Modify | User billing configuration changed to '{BillingMode}' for subscription {SubscriptionGuid} | -| Billing.LimitUpdate | Modify | {MeterName} usage limit changed from {PreviousLimitNumber} to {LimitNumber} | -| Billing.PurchaseUpdate | Modify | {MeterName} quantity changed from {PreviousPurchaseNumber} to {PurchaseNumber}. | -| Billing.SubscriptionLink | Create | Billing relationship set up to {NewSubscriptionGuid} | -| Billing.SubscriptionUnlink | Remove | Billing relationship removed from {PreviousSubscriptionGuid} | -| Billing.SubscriptionUpdate | Modify | Billing relationship changed from {PreviousSubscriptionGuid} to {NewSubscriptionGuid} | - -### Checks -| ActionId | Category | Details | -|----------|-----------|----------| -| CheckConfiguration.Created | Create | {Type} check has been added to {ResourceType} {ResourceName} | -| CheckConfiguration.Deleted | Remove | {Type} check has been removed from {ResourceType} {ResourceName} | -| CheckConfiguration.Updated | Modify | {Type} check has been updated for {ResourceType} {ResourceName} | -| CheckSuite.Completed | Execute | Checks on stage {StageName} of run #{RunName} of pipeline {PipelineName} in Project {ResolveProjectId:ProjectId} have been {CheckSuiteStatus} | - -### Extension -| ActionId | Category | Details | -|----------|-----------|----------| -| Extension.Disabled | Modify | Extension "{ExtensionName}" from publisher "{PublisherName}" was disabled | -| Extension.Enabled | Modify | Extension "{ExtensionName}" from publisher "{PublisherName}" was enabled | -| Extension.Installed | Create | Extension "{ExtensionName}" from publisher "{PublisherName}" was installed - Version "{Version}" | -| Extension.Uninstalled | Remove | Extension "{ExtensionName}" from publisher "{PublisherName}" was uninstalled | -| Extension.VersionUpdated | Modify | Extension "{ExtensionName}" from publisher "{PublisherName}" has been updated from version "{FromVersion}" to version "{Version}" | - -### Git -| ActionId | Category | Details | -|----------|-----------|----------| -| Git.RefUpdatePoliciesBypassed | Modify | Policies on "{FriendlyName}" were bypassed in Git repository "{RepoName}" in project {ResolveProjectId:ProjectId} | -| Git.RepositoryCreated | Create | Created Git repository "{RepoName}" in project {ResolveProjectId:ProjectId} | -| Git.RepositoryDefaultBranchChanged | Modify | Default branch of Git repository "{RepoName}" was changed to "{DefaultBranch}" in project {ResolveProjectId:ProjectId} | -| Git.RepositoryDeleted | Remove | Git repository "{RepoName}" was deleted from project {ResolveProjectId:ProjectId} | -| Git.RepositoryDestroyed | Remove | Git repository "{RepoName}" was destroyed in project {ResolveProjectId:ProjectId} | -| Git.RepositoryDisabled | Modify | Git repository "{RepoName}" was disabled in project {ResolveProjectId:ProjectId} | -| Git.RepositoryEnabled | Modify | Git repository "{RepoName}" was enabled in project {ResolveProjectId:ProjectId} | -| Git.RepositoryForked | Create | Git repository "{RepoName}" in project {ResolveProjectId:ProjectId} was forked from "{ParentRepoName}" in project "{ParentProjectName}" | -| Git.RepositoryRenamed | Modify | Git repository "{PreviousRepoName}" was renamed to "{RepoName}" in project {ResolveProjectId:ProjectId} | -| Git.RepositoryUndeleted | Create | Git repository "{RepoName}" was undeleted in project {ResolveProjectId:ProjectId} | - -### Group -| ActionId | Category | Details | -|----------|-----------|----------| -| Group.CreateGroups | Create | {GroupName} group was created | -| Group.UpdateGroupMembership | Modify | | -| Group.UpdateGroupMembership.Add | Modify | {ResolveIdentity:MemberId} was added as a member of group {ResolveIdentity:GroupId} | -| Group.UpdateGroupMembership.Remove | Modify | {ResolveIdentity:MemberId} was removed as a member of group {ResolveIdentity:GroupId} | -| Group.UpdateGroups.Delete | Remove | {ResolveIdentity:GroupId} group was deleted | -| Group.UpdateGroups.Modify | Modify | {ResolveIdentity:GroupId} group information was updated | - -### Library -| ActionId | Category | Details | -|----------|-----------|----------| -| Library.AgentAdded | Modify | Added agent {AgentName} to pool {AgentPoolName}. | -| Library.AgentDeleted | Modify | Removed agent {AgentName} from pool {AgentPoolName}. | -| Library.AgentPoolCreated | Create | Created agent pool {AgentPoolName}. | -| Library.AgentPoolDeleted | Remove | Deleted agent pool {AgentPoolName}. | -| Library.AgentsDeleted | Modify | Removed multiple agents from pool {AgentPoolName}. | -| Library.ServiceConnectionCreated | Create | Created Service Connection "{ConnectionName}" of type {ConnectionType}. | -| Library.ServiceConnectionDeleted | Remove | Deleted Service Connection "{ConnectionName}" of type {ConnectionType} from project {ResolveProjectId:ProjectId}. | -| Library.ServiceConnectionDeletedFromMultipleProjects | Remove | Deleted Service Connection "{ConnectionName}" of type {ConnectionType} from multiple Projects. | -| Library.ServiceConnectionExecuted | Execute | Service Connection "{ConnectionName}" of type {ConnectionType} executed in project {ResolveProjectId:ProjectId}. | -| Library.ServiceConnectionForProjectModified | Modify | Modified Service Connection "{ConnectionName}" in project {ResolveProjectId:ProjectId}. | -| Library.ServiceConnectionModified | Modify | Modified Service Connection "{ConnectionName}" of type {ConnectionType}. | -| Library.ServiceConnectionShared | Modify | Shared Service Connection "{ConnectionName}" of type {ConnectionType} with project {ResolveProjectId:ProjectId}. | -| Library.ServiceConnectionSharedWithMultipleProjects | Modify | Shared Service Connection "{ConnectionName}" of type {ConnectionType} with multiple projects. | -| Library.VariableGroupCreated | Create | Created Variable Group "{VariableGroupName}" in project {ResolveProjectId:ProjectId}. | -| Library.VariableGroupCreatedForProjects | Create | Created Variable Group "{VariableGroupName}" for multiple projects. | -| Library.VariableGroupDeleted | Remove | Deleted Variable Group "{VariableGroupName}" in project {ResolveProjectId:ProjectId}. | -| Library.VariableGroupDeletedFromProjects | Remove | Deleted Variable Group "{VariableGroupName}" from multiple projects. | -| Library.VariableGroupModified | Modify | Modified Variable Group "{VariableGroupName}" in project {ResolveProjectId:ProjectId}. | -| Library.VariableGroupModifiedForProjects | Modify | Modified Variable Group "{VariableGroupName}" for multiple projects. | - -### Licensing -| ActionId | Category | Details | -|----------|-----------|----------| -| Licensing.Assigned | Create | {AccessLevel} access level assigned to "{ResolveIdentity:UserIdentifier}" {Optional:Reason} | -| Licensing.GroupRuleCreated | Create | New group rule for the "{ResolveIdentity:GroupIdentifier}" group assigning the {AccessLevel} access level was added to the organization| -| Licensing.GroupRuleDeleted | Remove | Group rule for the "{ResolveIdentity:GroupIdentifier}" group assigning the {AccessLevel} access level was removed | -| Licensing.GroupRuleModified | Modify | Group rule access level modified from for the {PreviousAccessLevel} to {AccessLevel} for "{ResolveIdentity:GroupIdentifier}" group | -| Licensing.Modified | Modify | Access level modified from {PreviousAccessLevel} to {AccessLevel} for "{ResolveIdentity:UserIdentifier}" {Optional:Reason} | -| Licensing.Removed | Remove | {AccessLevel} access level removed from "{ResolveIdentity:UserIdentifier}" | - -### Organization -| ActionId | Category | Details | -|----------|----------|---------| -| Organization.Create | Create | Organization {OrganizationName} was created in {PreferredRegion} region | -| Organization.LinkToAAD | Modify | Organization {OrganizationName} was linked to Azure Active Directory tenant {AADTenant} | -| Organization.UnlinkFromAAD | Modify | Organization {OrganizationName} was unlinked from Azure Active Directory tenant | -| Organization.Update.Delete | Modify | Organization {OrganizationName} was deleted | -| Organization.Update.ForceUpdateOwner | Modify | Organization owner was changed from {OldOwnerName} to {NewOwnerName}. Reason specified by actor "{ForceUpdateReason}" | -| Organization.Update.Owner | Modify | Organization owner was changed from {OldOwnerName} to {NewOwnerName} | -| Organization.Update.Rename | Modify | Organization {OldOrganizationName} was renamed to {NewOrganizationName} | -| Organization.Update.Restore | Modify | Organization {OrganizationName} was restored successfully | - -### OrganizationPolicy -| ActionId | Category | Details | -|----------|-----------|----------| -| OrganizationPolicy.EnforcePolicyAdded | Create | Enforced policy {EnforcePolicyName} was added | -| OrganizationPolicy.EnforcePolicyRemoved | Remove | Enforced policy {EnforcePolicyName} was removed | -| OrganizationPolicy.PolicyValueUpdated | Modify | Policy {PolicyName} was changed to {PolicyValue} | - -### Permissions -| ActionId | Category | Details | -|-----------|----------|----------| -| Security.ModifyAccessControlLists | Modify | Permission "{NamespaceName}\{ChangedPermission}" was set to {PermissionModifiedTo} for {ResolveIdentity:SubjectDescriptor} | -| Security.ModifyPermission | Modify | Permission "{NamespaceName}\{ChangedPermission}" was set to {PermissionModifiedTo} for {ResolveIdentity:SubjectDescriptor} | -| Security.RemoveAccessControlLists | Remove | All access control lists were removed on namespace {NamespaceName} on token(s) {Tokens} | -| Security.RemoveAllAccessControlLists | Remove | {ResolveIdentity:ActorId} removed all Access Control Lists | -| Security.RemoveIdentityACEs | Remove | {ResolveIdentity:ActorId} removed an identity ACE | -| Security.RemovePermission | Remove | All permissions were removed for {ResolveIdentity:Identities} on namespace {NamespaceName} and token {Token} | -| Security.ResetAccessControlLists | Modify | {ResolveIdentity:ActorId} reset an access control list | -| Security.ResetPermission | Modify | All permissions for the namespace {NamespaceName} on {ResolveIdentity:SubjectDescriptor} were reset back to default | - -### Pipelines -| ActionId | Category | Details | -|----------|----------|---------| -| Pipelines.DeploymentJobCompleted | Execute | Deployment for run "{RunName}" on pipeline "{PipelineName}" to environment "{EnvironmentName}" {DeploymentResult} | -| Pipelines.PipelineCreated | Create | Created pipeline "{PipelineName}" in project {ResolveProjectId:ProjectId} | -| Pipelines.PipelineDeleted | Remove | Deleted pipeline "{PipelineName}" in project {ResolveProjectId:ProjectId} | -| Pipelines.PipelineModified | Modify | Modified pipeline "{PipelineName}" in project {ResolveProjectId:ProjectId} | -| Pipelines.PipelineRetentionSettingChanged | Modify | Pipelines retention "{SettingName}" changed from {OldValue} to {NewValue} in {ProjectName} project | -| Pipelines.ResourceAuthorizedForPipeline | Modify | Successfully authorized {ResourceType} resource {ResourceId} for pipeline id {PipelineId} | -| Pipelines.ResourceAuthorizedForProject | Modify | Successfully authorized {ResourceType} resource {ResourceId} for the project | -| Pipelines.ResourceNotAuthorizedForPipeline | Modify | Didn't authorize {ResourceType} resource {ResourceId} for pipeline id {PipelineId}. The resource doesn't exist or the user doesn't have permission | -| Pipelines.ResourceNotAuthorizedForProject | Modify | Didn't authorize {ResourceType} resource {ResourceId} for the project. The resource doesn't exist or the user doesn't have permission | -| Pipelines.ResourceUnauthorizedForPipeline | Modify | Successfully unauthorized {ResourceType} resource {ResourceId} for pipeline id {PipelineId} | -| Pipelines.ResourceUnauthorizedForProject | Modify | Successfully unauthorized {ResourceType} resource {ResourceId} for the project | -| Pipelines.RunRetained | Modify | Pipeline run "{RunName}" in project {ResolveProjectId:ProjectId} granted lease id {RetentionLeaseId} to {RetentionOwnerId} | -| Pipelines.RunUnretained | Modify | Pipeline run "{RunName}" in project {ResolveProjectId:ProjectId} no longer retained | -| Pipelines.ProjectSettings | Modify | Pipelines setting "{SettingName}" changed from "{OldValue}" to "{NewValue}" in "{ProjectName}" project. | -| Pipelines.OrganizationSettings | Modify | Pipelines setting "{SettingName}" changed from "{OldValue}" to "{NewValue}" at organization level. | - -### Policy -| ActionId | Category | Details | -|-----------|----------|----------| -| Policy.PolicyConfigCreated | Create | Created {PolicyTypeDisplayName} policy in project {ResolveProjectId:ProjectId} | -| Policy.PolicyConfigModified | Modify | Modified {PolicyTypeDisplayName} policy in project {ResolveProjectId:ProjectId} | -| Policy.PolicyConfigRemoved | Remove | Removed {PolicyTypeDisplayName} policy in project {ResolveProjectId:ProjectId} | - -### Process -| ActionId | Category | Details | -|----------|-----------|----------| -| Process.Behavior.Add | Create | Work item type "{WorkItemTypeReferenceName}" created and portfolio backlog "{BehaviorName}" created. | -| Process.Behavior.Create | Create | Portfolio backlog "{BehaviorName}" created for process "{ProcessName}". | -| Process.Behavior.Delete | Remove | Portfolio backlog "{BehaviorName}" deleted for process "{ProcessName}". | -| Process.Behavior.Edit | Modify | Portfolio backlog "{BehaviorName}" edited for process "{ProcessName}". | -| Process.Behavior.Remove | Remove | Portfolio backlog "{BehaviorReferenceName}" removed from work item type. | -| Process.Behavior.Update | Modify | Portfolio backlog "{BehaviorName}" changed for {WorkItemTypeReferenceName}. | -| Process.Control.Create | Create | Control "{ControlLabel}" created for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.Control.CreateWithoutLabel | Create | Control created for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.Control.Delete | Remove | A control was deleted for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.Control.Update | Modify | Control "{ControlLabel}" updated for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.Control.UpdateWithoutLabel | Modify | Control updated for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.Field.Add | Create | Field "{FieldReferenceName}" created on work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.Field.Create | Create | Field "{FieldName}" created for process "{ProcessName}". | -| Process.Field.Delete | Remove | Field "{FieldReferenceName}" deleted. | -| Process.Field.Edit | Modify | Field "{FieldName}" edited for process "{ProcessName}". | -| Process.Field.Remove | Remove | Field "{FieldReferenceName}" removed from work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.Field.Update | Modify | Field "{FieldReferenceName}" updated in work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.Group.Add | Create | New group "{GroupLabel}" added to {WorkItemTypeReferenceName} in process "{ProcessName}". | -| Process.Group.Update | Modify | Group "{GroupLabel}" updated for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.List.Create | Modify | The picklist "{PicklistName}" was created. | -| Process.List.Delete | Remove | The picklist "{PicklistName}" was deleted. | -| Process.List.ListAddValue | Modify | Picklist value {PicklistValue} was added. | -| Process.List.ListRemoveValue| Remove | Picklist value {PicklistValue} was removed. | -| Process.List.Update | Modify | The picklist "{PicklistName}" was updated. | -| Process.Page.Add | Create | Page "{PageName}" added to work item type "{WorkItemTypeReferenceName}". | -| Process.Page.Delete | Remove | Page "{PageName}" deleted from work item type "{WorkItemTypeReferenceName}". | -| Process.Page.Update | Modify | Page "{PageName}" updated for work item type "{WorkItemTypeReferenceName}". | -| Process.Process.CloneXmlToInherited | Create | The process "{ParentProcessName}" has been cloned to an inherited process called "{TargetProcessName}". | -| Process.Process.Create | Create | Created inherited process "{ProcessName}". | -| Process.Process.Delete | Remove | Process "{ProcessName}" has been set as deleted. | -| Process.Process.Edit | Modify | Process with the name "{OldProcessName}" has been modified, and has the following name {NewProcessInformation}. | -| Process.Process.EditWithoutNewInformation | Modify | Process with the name "{OldProcessName}" has been modified. | -| Process.Process.Import | Create | New process "{ProcessName}" has been imported. | -| Process.Process.MigrateXmlToInherited | Modify | Process for project "{ProjectName}" was changed from "{OldProcess}" to "{NewProcess}". | -| Process.Rule.Add | Create | Rule "{RuleName}" added to "{WorkItemReferenceName}" for process "{ProcessName}". | -| Process.Rule.Delete | Remove | Rule "{RuleName}" deleted from "{WorkItemTypeReferenceName}" for process "{ProcessName}". | -| Process.Rule.Update | Modify | Rule "{RuleName}" updated in "{WorkItemTypeReferenceName}" for process "{ProcessName}". | -| Process.State.Create | Create | State "{StateName}" added to "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.State.Delete | Remove | State "{StateName}" deleted from "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.State.Update | Modify | State "{StateName}" updated in "{WorkItemTypeReferenceName}" in process "{ProcessName}". | -| Process.SystemControl.Delete | Remove | SystemControl "{ControlId}" deleted in "{WorkItemTypeReferenceName}" for process "{ProcessName}". | -| Process.SystemControl.Update | Modify | SystemControl "{ControlId}" updated in "{WorkItemTypeReferenceName}" for process "{ProcessName}". | -| Process.WorkItemType.Create | Create | New work item type "{WorkItemTypeName}" created for process "{ProcessName}". | -| Process.WorkItemType.Delete | Remove | Work item type "{WorkItemTypeReferenceName}" deleted from process "{ProcessName}". | -| Process.WorkItemType.Update | Modify | Work item type "{WorkItemTypeReferenceName}" updated for process "{ProcessName}". | - -### Project -| ActionId | Category | Details | -|----------|-----------|----------| -| Project.AreaPath.Create | Create | Area path "{Path}" has been created. | -| Project.AreaPath.Delete | Remove | Area path "{Path}" has been deleted. | -| Project.AreaPath.Update | Modify | Area path "{Path}" has been updated. | -| Project.Create | Create | Project {ProjectName} was created successfully | -| Project.CreateCompleted | Create | Project {ProjectName} was created successfully | -| Project.CreateFailed | Create | Project {ProjectName} failed to be created | -| Project.CreateQueued | Create | Project {ProjectName} creation was started | -| Project.DeleteCompleted | Remove | Project {ProjectName} was {ProjectDeleteType} deleted successfully | -| Project.DeleteFailed | Remove | Project {ProjectName} failed to be deleted | -| Project.DeleteQueued | Remove | Project {ProjectName} deletion was started | -| Project.HardDeleteCompleted | Remove | {PreviousProjectName} project was hard deleted successfully | -| Project.HardDeleteFailed | Remove | {PreviousProjectName} project failed to be deleted | -| Project.HardDeleteQueued | Remove | {PreviousProjectName} project deletion was started | -| Project.RestoreCompleted | Modify | Project {ResolveProjectId:ProjectId} was restored successfully | -| Project.RestoreQueued | Modify | Project {ResolveProjectId:ProjectId} restore was started | -| Project.SoftDeleteCompleted | Remove | {PreviousProjectName} project was soft deleted successfully | -| Project.SoftDeleteFailed | Remove | {PreviousProjectName} project failed to be deleted | -| Project.SoftDeleteQueued | Remove | {PreviousProjectName} project deletion was started | -| Project.UpdateRenameCompleted | Modify | Rename for project {PreviousProjectName} to {ProjectName} was successful | -| Project.UpdateRenameQueued | Modify | Rename for project {PreviousProjectName} to {ProjectName} was started | -| Project.UpdateVisibilityCompleted | Modify | Project {ResolveProjectId:ProjectId} visibility change from {PreviousProjectVisibility} to {ProjectVisibility} was successful | -| Project.UpdateVisibilityQueued | Modify | Project {ResolveProjectId:ProjectId} visibility change from {PreviousProjectVisibility} to {ProjectVisibility} was started | - -### Release -| ActionId | Category | Details | -|----------|-----------|----------| -| Release.ApprovalCompleted | Modify | {ApprovalType} approval for deployment of release "{ReleaseName}" to stage "{StageName}" has been {ApprovalResult} in Project {ResolveProjectId:ProjectId} | -| Release.ApprovalsCompleted | Modify | Multiple {ApprovalType} approvals for deployment of release "{ReleaseName}" have been {ApprovalResult} in Project {ResolveProjectId:ProjectId}| -| Release.DeploymentCompleted | Execute | Deployment of release "{ReleaseName}" on pipeline "{PipelineName}" to "{StageName}" in Project {ResolveProjectId:ProjectId} was {DeploymentResult}| -| Release.DeploymentsCompleted | Execute | Deployments of multiple stages of release "{ReleaseName}" on pipeline "{PipelineName}" were {DeploymentResult} in Project {ResolveProjectId:ProjectId}| -| Release.ReleaseCreated | Create | Created release "{releaseName}" of Release Pipeline "{PipelineName}" in Project {ResolveProjectId:ProjectId}| -| Release.ReleaseDeleted | Remove | Deleted release "{ReleaseName}" of Release Pipeline "{PipelineName}" in Project {ResolveProjectId:ProjectId}| -| Release.ReleasePipelineCreated | Create | Release Pipeline "{PipelineName}" created in Project {ResolveProjectId:ProjectId}| -| Release.ReleasePipelineDeleted | Remove | Release Pipeline "{PipelineName}" deleted in Project {ResolveProjectId:ProjectId}| -| Release.ReleasePipelineModified | Modify | Release Pipeline "{PipelineName}" modified in Project {ResolveProjectId:ProjectId}| - -### Token -| ActionId | Category | Details | -|----------|-----------|----------| -| Token.PatCreateEvent | Create | Personal Access Token "{DisplayName}" was created. | -| Token.PatExpiredEvent | Modify | Personal Access Token "{DisplayName}" expired. | -| Token.PatPublicDiscoveryEvent | Access | Personal Access Token "{DisplayName}" associated with user "{OwnerName}" was discovered in a public repository. | -| Token.PatRevokeEvent | Remove | Personal Access Token "{DisplayName}" was revoked. | -| Token.PatSystemRevokeEvent | Remove | Personal Access Token "{DisplayName}" associated with user "{OwnerName}" was revoked by the system. | -| Token.PatUpdateEvent | Modify | Personal Access Token "{DisplayName}" was updated. | -| Token.SshCreateEvent | Create | SSH Key "{DisplayName}" was created. | -| Token.SshRevokeEvent | Remove | SSH Key "{DisplayName}" was revoked. | -| Token.SshUpdateEvent | Modify | SSH Key "{DisplayName}" was updated. | - +> Want to find out what actions your organization logs? Be sure to check out the [Audit Log Query API](/rest/api/azure/devops/audit/audit-log/query): `https://auditservice.dev.azure.com/{YOUR_ORGANIZATION}/_apis/audit/actions`, replacing {YOUR_ORGANIZATION} with the name of your organization. This API returns a list of all audit events your organization could emit. + +### Artifacts events + +| Action | Description | +|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------| +| `Artifacts.Feed.Project.Create` | Created feed {FeedName} in project {ProjectId}. | +| `Artifacts.Feed.Org.Create` | Created organization feed {FeedName}. | +| `Artifacts.Feed.Project.Modify` | Modified feed {FeedName} in project {ProjectId}- {FeedChanges}. | +| `Artifacts.Feed.Org.Modify` | Modified organization feed {FeedName}- {FeedChanges}. | +| `Artifacts.Feed.Project.SoftDelete` | Moved feed {FeedName} to the Feed Recycle Bin in project {ProjectId}. | +| `Artifacts.Feed.Org.SoftDelete` | Moved organization feed {FeedName} to the Feed Recycle Bin. | +| `Artifacts.Feed.Project.HardDelete` | Permanently deleted feed {FeedName} in project {ProjectId}. | +| `Artifacts.Feed.Org.HardDelete` | Permanently deleted organization feed {FeedName}. | +| `Artifacts.Feed.Project.Modify.Permissions` | Permissions for {DisplayName} were set to {Role} for feed {FeedName} in project {ProjectId}. | +| `Artifacts.Feed.Org.Modify.Permissions` | Permissions for {DisplayName} were set to {Role} for organization feed {FeedName}. | +| `Artifacts.Feed.Project.Modify.Permissions.Deletion` | Permissions for feed {FeedName} in project {ProjectId} were removed for {DisplayName}. | +| `Artifacts.Feed.Org.Modify.Permissions.Deletion` | Permissions for organization feed {FeedName} were removed for {DisplayName}. | +| `Artifacts.Feed.Project.FeedView.Create` | Created feed view {FeedViewName} in feed {FeedName} in project {ProjectId}. | +| `Artifacts.Feed.Org.FeedView.Create` | Created feed view {FeedViewName} in organization feed {FeedName}. | +| `Artifacts.Feed.Project.FeedView.Modify` | Modified feed view {FeedViewName} in feed {FeedName} in project {ProjectId}- {FeedViewChanges}. | +| `Artifacts.Feed.Org.FeedView.Modify` | Modified feed view {FeedViewName} in organization feed {FeedName}- {FeedViewChanges}. | +| `Artifacts.Feed.Project.FeedView.HardDelete` | Permanently deleted feed view {FeedViewName} in feed {FeedName} in project {ProjectId}. | +| `Artifacts.Feed.Org.FeedView.HardDelete` | Permanently deleted feed view {FeedViewName} in organization feed {FeedName}. | + +### AuditLog events + +| Action | Description | +|--------|-------------| +| `AuditLog.AccessLog` | Accessed the audit log. | +| `AuditLog.DownloadLog` | Downloaded a {Format} copy of the audit log. | +| `AuditLog.StreamCreated` | Stream for {ConsumerType:consumerType} was set up to send auditing events to {displayName}. | +| `AuditLog.StreamDeleted` | Stream for {ConsumerType:consumerType} to send auditing data to {displayName} was deleted. | +| `AuditLog.StreamDisabledBySystem` | Stream for {ConsumerType:consumerType} to send auditing data to {displayName} was disabled by the system. | +| `AuditLog.StreamDisabledByUser` | Stream for {ConsumerType:consumerType} to send auditing data to {displayName} was disabled. | +| `AuditLog.StreamEnabled` | Stream for {ConsumerType:consumerType} to send auditing data to {displayName} was enabled. | +| `AuditLog.StreamModified` | Stream for {ConsumerType:consumerType} to send auditing data to {displayName} was modified. | +| `AuditLog.StreamRead` | Accessed auditing streams. | +| `AuditLog.TestStream` | {ResolveIdentity:ActorId} initiated a {StreamConsumerType} stream connection test from {OrganizationName} in Azure DevOps. | + +### Billing events + +| Action | Description | +|--------|-------------| +| `Billing.BillingModeUpdate` | User billing configuration changed to '{BillingMode}' for subscription {SubscriptionGuid}. | +| `Billing.LimitUpdate` | {MeterName} usage limit changed from {PreviousLimitNumber} to {LimitNumber}. | +| `Billing.PurchaseUpdate` | {MeterName} quantity changed from {PreviousPurchaseNumber} to {PurchaseNumber}. | +| `Billing.SubscriptionLink` | Billing relationship set up to {NewSubscriptionGuid}. | +| `Billing.SubscriptionUnlink` | Billing relationship removed from {PreviousSubscriptionGuid}. | +| `Billing.SubscriptionUpdate` | Billing relationship changed from {PreviousSubscriptionGuid} to {NewSubscriptionGuid}. | + +### Extension events + +| Action | Description | +|--------|-------------| +| `Extension.Disabled` | Extension "{ExtensionName}" from publisher "{PublisherName}" was disabled. | +| `Extension.Enabled` | Extension "{ExtensionName}" from publisher "{PublisherName}" was enabled. | +| `Extension.Installed` | Extension "{ExtensionName}" from publisher "{PublisherName}" was installed - Version "{Version}". | +| `Extension.Uninstalled` | Extension "{ExtensionName}" from publisher "{PublisherName}" was uninstalled. | +| `Extension.VersionUpdated` | Extension "{ExtensionName}" from publisher "{PublisherName}" was updated from version "{FromVersion}" to version "{Version}". | + +### Git licensing events + +| Action | Description | +|--------|-------------| +| `Git.RefUpdatePoliciesBypassed` | Policies on "{FriendlyName}" were bypassed in Git repository "{RepoName}" in project {ResolveProjectId:ProjectId}. | +| `Git.RepositoryCreated` | Created Git repository "{RepoName}" in project {ResolveProjectId:ProjectId}. | +| `Git.RepositoryDefaultBranchChanged` | Default branch of Git repository "{RepoName}" was changed to "{DefaultBranch}" in project {ResolveProjectId:ProjectId}. | +| `Git.RepositoryDeleted` | Git repository "{RepoName}" was deleted from project {ResolveProjectId:ProjectId}. | +| `Git.RepositoryDestroyed` | Git repository "{RepoName}" was destroyed in project {ResolveProjectId:ProjectId}. | +| `Git.RepositoryDisabled` | Git repository "{RepoName}" was disabled in project {ResolveProjectId:ProjectId}. | +| `Git.RepositoryEnabled` | Git repository "{RepoName}" was enabled in project {ResolveProjectId:ProjectId}. | +| `Git.RepositoryForked` | Git repository "{RepoName}" in project {ResolveProjectId:ProjectId} was forked from "{ParentRepoName}" in project "{ParentProjectName}". | +| `Git.RepositoryRenamed` | Git repository "{PreviousRepoName}" was renamed to "{RepoName}" in project {ResolveProjectId:ProjectId}. | +| `Git.RepositoryUndeleted` | Git repository "{RepoName}" was undeleted in project {ResolveProjectId:ProjectId}. | + +### Group events + +| Action | Description | +|--------|-------------| +| `Group.CreateGroups` | {GroupName} group was created. | +| `Group.UpdateGroupMembership.Add` | {ResolveIdentity:MemberId} was added as a member of group {ResolveIdentity:GroupId}. | +| `Group.UpdateGroupMembership.Remove` | {ResolveIdentity:MemberId} was removed as a member of group {ResolveIdentity:GroupId}. | +| `Group.UpdateGroups.Delete` | {ResolveIdentity:GroupId} group was deleted. | +| `Group.UpdateGroups.Modify` | {ResolveIdentity:GroupId} group information was updated. | + +### Library events + +| Action | Description | +|--------|-------------| +| `Library.AgentAdded` | Added agent {AgentName} to pool {AgentPoolName}. | +| `Library.AgentDeleted` | Removed agent {AgentName} from pool {AgentPoolName}. | +| `Library.AgentPoolCreated` | Created agent pool {AgentPoolName}. | +| `Library.AgentPoolDeleted` | Deleted agent pool {AgentPoolName}. | +| `Library.AgentsDeleted` | Removed multiple agents from pool {AgentPoolName}. | +| `Library.ServiceConnectionCreated` | Created Service Connection "{ConnectionName}" of type {ConnectionType}. | +| `Library.ServiceConnectionCreatedForMultipleProjects` | Created Service Connection "{ConnectionName}" of type {ConnectionType} for multiple projects. | +| `Library.ServiceConnectionDeleted` | Deleted Service Connection "{ConnectionName}" of type {ConnectionType} from project {ResolveProjectId:ProjectId}. | +| `Library.ServiceConnectionDeletedFromMultipleProjects` | Deleted Service Connection "{ConnectionName}" of type {ConnectionType} from multiple projects. | +| `Library.ServiceConnectionForProjectModified` | Modified Service Connection "{ConnectionName}" in project {ResolveProjectId:ProjectId}. | +| `Library.ServiceConnectionModified` | Modified Service Connection "{ConnectionName}" of type {ConnectionType}. | +| `Library.ServiceConnectionPropertyChanged` | One or more properties of Service Connection "{ConnectionName}" of type {ConnectionType} were changed: IsDisabled = {IsDisabled}. | +| `Library.ServiceConnectionShared` | Shared Service Connection "{ConnectionName}" of type {ConnectionType} with project {ResolveProjectId:ProjectId}. | +| `Library.ServiceConnectionSharedWithMultipleProjects` | Shared Service Connection "{ConnectionName}" of type {ConnectionType} with multiple projects. | +| `Library.VariableGroupCreated` | Created Variable Group "{VariableGroupName}" in project {ResolveProjectId:ProjectId}. | +| `Library.VariableGroupCreatedForProjects` | Created Variable Group "{VariableGroupName}" for multiple projects. | +| `Library.VariableGroupDeleted` | Deleted Variable Group "{VariableGroupName}" in project {ResolveProjectId:ProjectId}. | +| `Library.VariableGroupDeletedFromProjects` | Deleted Variable Group "{VariableGroupName}" from multiple projects. | +| `Library.VariableGroupModified` | Modified Variable Group "{VariableGroupName}" in project {ResolveProjectId:ProjectId}. | +| `Library.VariableGroupModifiedForProjects` | Modified Variable Group "{VariableGroupName}" for multiple projects. | + +### Licensing events + +| Action | Description | +|--------|-------------| +| `Licensing.Assigned` | {AccessLevel} access level assigned to "{ResolveIdentity:UserIdentifier}" {Optional:Reason}. | +| `Licensing.GroupRuleCreated` | New group rule for the "{ResolveIdentity:GroupIdentifier}" group assigning the {AccessLevel} access level was added to the organization. | +| `Licensing.GroupRuleDeleted` | Group rule for the "{ResolveIdentity:GroupIdentifier}" group assigning the {AccessLevel} access level was removed. | +| `Licensing.GroupRuleModified` | Group rule access level modified from {PreviousAccessLevel} to {AccessLevel} for "{ResolveIdentity:GroupIdentifier}" group. | +| `Licensing.Modified` | Access level modified from {PreviousAccessLevel} to {AccessLevel} for "{ResolveIdentity:UserIdentifier}" {Optional:Reason}. | +| `Licensing.Removed` | {AccessLevel} access level removed from "{ResolveIdentity:UserIdentifier}". | + +### Organization events + +| Action | Description | +|--------|-------------| +| `Organization.Create` | Organization {OrganizationName} was created in {PreferredRegion} region. | +| `Organization.LinkToAAD` | Organization {OrganizationName} was linked to Microsoft Entra tenant {AADTenant}. | +| `Organization.UnlinkFromAAD` | Organization {OrganizationName} was unlinked from Microsoft Entra tenant. | +| `Organization.Update.Delete` | Organization {OrganizationName} was deleted. | +| `Organization.Update.ForceUpdateOwner` | Organization owner was changed from {OldOwnerName} to {NewOwnerName}. Reason specified by actor "{ForceUpdateReason}". | +| `Organization.Update.Owner` | Organization owner was changed from {OldOwnerName} to {NewOwnerName}. | +| `Organization.Update.Rename` | Organization {OldOrganizationName} was renamed to {NewOrganizationName}. | +| `Organization.Update.Restore` | Organization {OrganizationName} was restored successfully. | + +### OrganizationPolicy events + +| Action | Description | +|--------|-------------| +| `OrganizationPolicy.EnforcePolicyAdded` | Enforced policy {EnforcePolicyName} was added. | +| `OrganizationPolicy.EnforcePolicyRemoved` | Enforced policy {EnforcePolicyName} was removed. | +| `OrganizationPolicy.PolicyValueUpdated` | Policy {PolicyName} was changed to {PolicyValue}. | + +### Pipelines events + +| Action | Description | +|--------|-------------| +| `Pipelines.DeploymentJobCompleted` | Deployment for run "{RunName}" on pipeline "{PipelineName}" to environment "{EnvironmentName}" {DeploymentResult}. | +| `Pipelines.PipelineCreated` | Created pipeline "{PipelineName}" in project {ResolveProjectId:ProjectId}. | +| `Pipelines.PipelineDeleted` | Deleted pipeline "{PipelineName}" in project {ResolveProjectId:ProjectId}. | +| `Pipelines.PipelineModified` | Modified pipeline "{PipelineName}" in project {ResolveProjectId:ProjectId}. | +| `Pipelines.PipelineRetentionSettingChanged` | Pipelines retention "{SettingName}" changed from {OldValue} to {NewValue} in {ProjectName} project. | +| `Pipelines.ResourceAuthorizedForPipeline` | Successfully authorized {ResourceType} resource {ResourceId} for pipeline ID {PipelineId}. | +| `Pipelines.ResourceAuthorizedForProject` | Successfully authorized {ResourceType} resource {ResourceId} for the project. | +| `Pipelines.ResourceNotAuthorizedForPipeline` | Didn't authorize {ResourceType} resource {ResourceId} for pipeline ID {PipelineId}. The resource doesn't exist or the user doesn't have permission. | +| `Pipelines.ResourceNotAuthorizedForProject` | Didn't authorize {ResourceType} resource {ResourceId} for the project. The resource doesn't exist or the user doesn't have permission. | +| `Pipelines.ResourceUnauthorizedForPipeline` | Successfully unauthorized {ResourceType} resource {ResourceId} for pipeline ID {PipelineId}. | +| `Pipelines.ResourceUnauthorizedForProject` | Successfully unauthorized {ResourceType} resource {ResourceId} for the project. | +| `Pipelines.RunRetained` | Pipeline run "{RunName}" in project {ResolveProjectId:ProjectId} granted lease ID {RetentionLeaseId} to {RetentionOwnerId}. | +| `Pipelines.RunUnretained` | Pipeline run "{RunName}" in project {ResolveProjectId:ProjectId} no longer retained. | +| `Pipelines.ProjectSettings` | Pipelines setting "{SettingName}" changed from "{OldValue}" to "{NewValue}" in "{ProjectName}" project. | +| `Pipelines.OAuthConfigurationCreated` | Created OAuth configuration '{ConfigName}' for '{SourceType}'. | +| `Pipelines.OAuthConfigurationDeleted` | Updated OAuth configuration '{ConfigName}' for '{SourceType}'. | +| `Pipelines.OAuthConfigurationUpdated` | Deleted OAuth configuration '{ConfigName}' for '{SourceType}'. | +| `Pipelines.OrganizationSettings` | Pipelines setting "{SettingName}" changed from "{OldValue}" to "{NewValue}" at organization level. | + +### Policy events + +| Action | Description | +|--------|-------------| +| `Policy.PolicyConfigCreated` | Created {PolicyTypeDisplayName} policy in project {ResolveProjectId:ProjectId}. | +| `Policy.PolicyConfigModified` | Modified {PolicyTypeDisplayName} policy in project {ResolveProjectId:ProjectId}. | +| `Policy.PolicyConfigRemoved` | Removed {PolicyTypeDisplayName} policy in project {ResolveProjectId:ProjectId}. | + +### Process events + +| Action | Description | +|--------|-------------| +| `Process.Behavior.Add` | Work item type "{WorkItemTypeReferenceName}" created and portfolio backlog "{BehaviorName}" created. | +| `Process.Behavior.Create` | Portfolio backlog "{BehaviorName}" created for process "{ProcessName}". | +| `Process.Behavior.Delete` | Portfolio backlog "{BehaviorName}" deleted for process "{ProcessName}". | +| `Process.Behavior.Edit` | Portfolio backlog "{BehaviorName}" edited for process "{ProcessName}". | +| `Process.Behavior.Remove` | Portfolio backlog "{BehaviorReferenceName}" removed from work item type. | +| `Process.Behavior.Update` | Portfolio backlog "{BehaviorName}" changed for {WorkItemTypeReferenceName}. | +| `Process.Control.Create` | Control "{ControlLabel}" created for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.Control.CreateWithoutLabel` | Control created for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.Control.Delete` | A control was deleted for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.Control.Update` | Control "{ControlLabel}" updated for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.Field.Add` | Field "{FieldReferenceName}" created on work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.Field.Create` | Field "{FieldName}" created for process "{ProcessName}". | +| `Process.Field.Delete` | Field "{FieldReferenceName}" deleted. | +| `Process.Field.Edit` | Field "{FieldName}" edited for process "{ProcessName}". | +| `Process.Field.Remove` | Field "{FieldReferenceName}" removed from work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.Field.Update` | Field "{FieldReferenceName}" updated in work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.Group.Add` | New group "{GroupLabel}" added to {WorkItemTypeReferenceName} in process "{ProcessName}". | +| `Process.Group.Update` | Group "{GroupLabel}" updated for work item type "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.List.Create` | The picklist "{PicklistName}" was created. | +| `Process.List.Delete` | The picklist "{PicklistName}" was deleted. | +| `Process.List.ListAddValue` | Picklist value {PicklistValue} was added. | +| `Process.List.ListRemoveValue` | Picklist value {PicklistValue} was removed. | +| `Process.List.Update` | The picklist "{PicklistName}" was updated. | +| `Process.Page.Add` | Page "{PageName}" added to work item type "{WorkItemTypeReferenceName}". | +| `Process.Page.Delete` | Page "{PageName}" deleted from work item type "{WorkItemTypeReferenceName}". | +| `Process.Page.Update` | Page "{PageName}" updated for work item type "{WorkItemTypeReferenceName}". | +| `Process.Process.CloneXmlToInherited` | The process "{ParentProcessName}" was cloned to an inherited process called "{TargetProcessName}". | +| `Process.Process.Delete` | Process "{ProcessName}" was set as deleted. | +| `Process.Process.Edit` | Process with the name "{OldProcessName}" was modified, and has the following name {NewProcessInformation}. | +| `Process.Process.EditWithoutNewInformation` | Process with the name "{OldProcessName}" was modified. | +| `Process.Process.Import` | New process "{ProcessName}" was imported. | +| `Process.Process.MigrateXmlToInherited` | Process for project "{ProjectName}" was changed from "{OldProcess}" to "{NewProcess}". | +| `Process.Rule.Add` | Rule "{RuleName}" added to "{WorkItemReferenceName}" for process "{ProcessName}". | +| `Process.Rule.Delete` | Rule "{RuleName}" deleted from "{WorkItemTypeReferenceName}" for process "{ProcessName}". | +| `Process.Rule.Update` | Rule "{RuleName}" updated in "{WorkItemTypeReferenceName}" for process "{ProcessName}". | +| `Process.State.Create` | State "{StateName}" added to "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.State.Delete` | State "{StateName}" deleted from "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.State.Update` | State "{StateName}" updated in "{WorkItemTypeReferenceName}" in process "{ProcessName}". | +| `Process.SystemControl.Update` | SystemControl "{ControlId}" updated in "{WorkItemTypeReferenceName}" for process "{ProcessName}". | +| `Process.WorkItemType.Create` | New work item type "{WorkItemTypeName}" created for process "{ProcessName}". | +| `Process.WorkItemType.Delete` | Work item type "{WorkItemTypeReferenceName}" deleted from process "{ProcessName}". | +| `Process.WorkItemType.Update` | Work item type "{WorkItemTypeReferenceName}" updated for process "{ProcessName}". | + +### Project events + +| Action | Description | +|--------|-------------| +| `Project.AreaPath.Create` | Area path "{Path}" was created. | +| `Project.AreaPath.Delete` | Area path "{Path}" was deleted. | +| `Project.AreaPath.Update` | Area path "{Path}" was updated. | +| `Project.CreateCompleted` | Project {ProjectName} was created successfully. | +| `Project.CreateFailed` | Project {ProjectName} failed to be created. | +| `Project.CreateQueued` | Project {ProjectName} creation was started. | +| `Project.DeleteCompleted` | Project {ProjectName} was {ProjectDeleteType} deleted successfully. | +| `Project.DeleteFailed` | Project {ProjectName} failed to be deleted. | +| `Project.DeleteQueued` | Project {ProjectName} deletion was started. | +| `Project.HardDeleteCompleted` | {PreviousProjectName} project was hard deleted successfully. | +| `Project.HardDeleteFailed` | {PreviousProjectName} project failed to be deleted. | +| `Project.HardDeleteQueued` | {PreviousProjectName} project deletion was started. | +| `Project.RestoreCompleted` | Project {ResolveProjectId:ProjectId} was restored successfully. | +| `Project.RestoreQueued` | Project {ResolveProjectId:ProjectId} restore was started. | +| `Project.SoftDeleteCompleted` | {PreviousProjectName} project was soft deleted successfully. | +| `Project.SoftDeleteFailed` | {PreviousProjectName} project failed to be deleted. | +| `Project.SoftDeleteQueued` | {PreviousProjectName} project deletion was started. | +| `Project.UpdateRenameCompleted` | Rename for project {PreviousProjectName} to {ProjectName} was successful. | +| `Project.UpdateRenameQueued` | Rename for project {PreviousProjectName} to {ProjectName} was started. | +| `Project.UpdateVisibilityCompleted` | Project {ResolveProjectId:ProjectId} visibility change from {PreviousProjectVisibility} to {ProjectVisibility} was successful. | +| `Project.UpdateVisibilityQueued` | Project {ResolveProjectId:ProjectId} visibility change from {PreviousProjectVisibility} to {ProjectVisibility} was started. | +| `Project.IterationPath.Create` | IterationPath {Path} has been created. | +| `Project.IterationPath.Update` | IterationPath {Path} has been updated. | +| `Project.IterationPath.Delete` | IterationPath {Path} has been deleted. | +| `Project.Process.Modify` | Process for project {ResolveProjectId:ProjectId} was changed from {OldProcessName} to {ProcessName}. | +| `Project.Process.ModifyWithoutOldProcess` | Process for project {ResolveProjectId:ProjectId} was changed to {ProcessName}. | + +### Release events + +| Action | Description | +|--------|-------------| +| `Release.ApprovalCompleted` | {ApprovalType} approval for deployment of release "{ReleaseName}" to stage "{StageName}" was {ApprovalResult} in Project {ResolveProjectId:ProjectId}. | +| `Release.ApprovalsCompleted` | Multiple {ApprovalType} approvals for deployment of release "{ReleaseName}" have been {ApprovalResult} in Project {ResolveProjectId:ProjectId}. | +| `Release.DeploymentCompleted` | Deployment of release "{ReleaseName}" on pipeline "{PipelineName}" to "{StageName}" in Project {ResolveProjectId:ProjectId} was {DeploymentResult}. | +| `Release.DeploymentsCompleted` | Deployments of multiple stages of release "{ReleaseName}" on pipeline "{PipelineName}" were {DeploymentResult} in Project {ResolveProjectId:ProjectId}. | +| `Release.ReleaseCreated` | Created release "{ReleaseName}" of Release Pipeline "{PipelineName}" in Project {ResolveProjectId:ProjectId}. | +| `Release.ReleaseDeleted` | Deleted release "{ReleaseName}" of Release Pipeline "{PipelineName}" in Project {ResolveProjectId:ProjectId}. | +| `Release.ReleasePipelineCreated` | Release Pipeline "{PipelineName}" created in Project {ResolveProjectId:ProjectId}. | +| `Release.ReleasePipelineDeleted` | Release Pipeline "{PipelineName}" deleted in Project {ResolveProjectId:ProjectId}. | +| `Release.ReleasePipelineModified` | Release Pipeline "{PipelineName}" modified in Project {ResolveProjectId:ProjectId}. | + +### Security events + +| Action | Description | +|--------|-------------| +| `Security.ModifyAccessControlLists` | Permission "{NamespaceName}\{ChangedPermission}" was set to {PermissionModifiedTo} for {ResolveIdentity:SubjectDescriptor}. | +| `Security.ModifyPermission` | Permission "{NamespaceName}\{ChangedPermission}" was set to {PermissionModifiedTo} for {ResolveIdentity:SubjectDescriptor}. | +| `Security.RemoveAccessControlLists` | All access control lists were removed on namespace {NamespaceName} on tokens {Tokens}. | +| `Security.RemoveAllAccessControlLists` | {ResolveIdentity:ActorId} removed all Access Control Lists. | +| `Security.RemoveIdentityACEs` | {ResolveIdentity:ActorId} removed an identity ACE. | +| `Security.RemovePermission` | All permissions were removed for {ResolveIdentity:Identities} on namespace {NamespaceName} and token {Token}. | +| `Security.ResetAccessControlLists` | {ResolveIdentity:ActorId} reset an access control list. | +| `Security.ResetPermission` | All permissions for the namespace {NamespaceName} on {ResolveIdentity:SubjectDescriptor} were reset back to default. | + +### Token events + +| Action | Description | +|--------|-------------| +| `Token.PatCreateEvent` | Personal Access Token "{DisplayName}" was created. | +| `Token.PatExpiredEvent` | Personal Access Token "{DisplayName}" expired. | +| `Token.PatPublicDiscoveryEvent` | Personal Access Token "{DisplayName}" associated with user "{OwnerName}" was discovered in a public repository. | +| `Token.PatRevokeEvent` | Personal Access Token "{DisplayName}" was revoked. | +| `Token.PatSystemRevokeEvent` | Personal Access Token "{DisplayName}" associated with user "{OwnerName}" was revoked by the system. | +| `Token.PatUpdateEvent` | Personal Access Token "{DisplayName}" was updated. | +| `Token.SshCreateEvent` | SSH Key "{DisplayName}" was created. | +| `Token.SshRevokeEvent` | SSH Key "{DisplayName}" was revoked. | +| `Token.SshUpdateEvent` | SSH Key "{DisplayName}" was updated. | ## Related articles - [Review audit log](azure-devops-auditing.md#review-audit-log) -- [Export audit events](azure-devops-auditing.md#export-auditing-events) +- [Export audit events](azure-devops-auditing.md#export-audit-events) - [Set up an audit stream](auditing-streaming.md) diff --git a/docs/organizations/audit/auditing-streaming.md b/docs/organizations/audit/auditing-streaming.md index 9f67e6d1594..d87ce4b8bd1 100644 --- a/docs/organizations/audit/auditing-streaming.md +++ b/docs/organizations/audit/auditing-streaming.md @@ -8,7 +8,7 @@ ms.author: chcomley author: chcomley ms.topic: quickstart monikerRange: '= azure-devops' -ms.date: 06/15/2023 +ms.date: 11/11/2024 --- # Create audit streaming @@ -35,26 +35,19 @@ Private linked workspaces aren't supported today. ## Prerequisites -By default, Project Collection Administrators (PCAs) are the only group that has access to the auditing feature. You must have the following permissions: - -- Manage audit streams -- View audit log - - :::image type="content" source="media/auditing-streaming/auditing-permissions.png" alt-text="Set audit permissions to Allow"::: - -These permissions can be given to any users or groups you wish to have manage your organization's streams. Additionally, there's also a *Delete audit streams* permission that you can add on for users or groups. +[!INCLUDE [prerequisites-auditing](includes/prerequisites-auditing.md)] ## Create a stream -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - - ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). +1. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. -3. Select **Auditing**. + ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) + +1. Select **Auditing**. ![Select Auditing in Organization settings](media/auditing-streaming/select-auditing-organization-settings.png) - + > [!NOTE] > If you don't see *Auditing* in Organization Settings, then auditing is not currently enabled for your organization. Someone in the organization owner or Project Collection Administrators (PCAs) group must [enable Auditing](azure-devops-auditing.md#enable-and-disable-auditing) in Organization Policies. You will then be able to see events on the Auditing page if you have the appropriate permissions. @@ -79,7 +72,7 @@ Streams send data to Splunk via the HTTP Event Collector endpoint. 1. Enable this feature in Splunk. For more information, see this [Splunk documentation](https://aka.ms/adostreamingsplunkdocumentation). - Once it's enabled, you should have an HTTP Event Collector token and the URL to your Splunk instance. You need both the token and URL to create a Splunk stream. + Once enabled, you should have an HTTP Event Collector token and the URL to your Splunk instance. You need both the token and URL to create a Splunk stream. > [!NOTE] > When you're creating a new Event Collector token in Splunk, don't check “Enable indexer acknowledgement”. If it's checked, then no events flow into Splunk. You can edit the token in Splunk to remove that setting. @@ -90,14 +83,18 @@ Streams send data to Splunk via the HTTP Event Collector endpoint. :::image type="content" source="media/auditing-streaming/create-stream-splunk.png" alt-text="Enter topic endpoint and access key that you noted earlier"::: -4. Select **Set up** and your stream's configured. +4. Select **Set up**. -Events begin to arrive on Splunk within half an hour or less. +Your stream gets configured and events begin to arrive on Splunk within half an hour or less. ### Set up an Event Grid stream -1. Create an Event Grid topic on Azure. -2. Make note of the “Topic Endpoint” and one of the two “Access Keys”. Use this information to create the Event Grid connection. +1. Create an Event Grid topic on Azure. + +> [!NOTE] +> Go to the **Advanced** tab and ensure that the Event Schema is set to **Event Grid Schema**. Other schemas are not supported by Azure DevOps. + +2. Make note of the "Topic Endpoint" and one of the two "Access Keys". Use this information to create the Event Grid connection. :::image type="content" source="media/auditing-streaming/azure-event-grid.png" alt-text="Azure Event Grid information"::: @@ -143,7 +140,7 @@ Parameters available for editing differ per stream type. ## Disable a stream 1. Next to the stream that you want to disable, move the **Enabled** toggle from *On* to *Off*. - When streams encounter a failure, they may become disabled. You can get details on the failure from the status shown next to the stream, or by selecting **Edit stream**. You can also disable a stream manually, and then re-enable it later. + When streams encounter a failure, they might become disabled. You can get details on the failure from the status shown next to the stream, or by selecting **Edit stream**. You can also disable a stream manually, and then re-enable it later. :::image type="content" source="media/auditing-streaming/disable-stream-move-toggle-off.png" alt-text="Move toggle to Off to disable stream"::: @@ -152,7 +149,7 @@ Parameters available for editing differ per stream type. You can re-enable a disabled stream. It catches up on any audit events that were missed for up to the previous seven days. That way you don't miss any events from the duration that the stream was disabled. > [!NOTE] -> If a stream is disabled for more than 7 days, events older than 7 days aren't included in the catch up. +> Events older than 7 days aren't included in the catch-up if a stream is disabled for more than 7 days. ## Delete a stream @@ -168,11 +165,11 @@ To delete a stream, make sure that you have the *Delete audit streams* permissio 3. Select **Confirm**. -Your stream gets removed. Any events that haven't been sent before the deletion aren't sent. +The system removes your stream. Any unsent events before the deletion don't get sent. ## Related articles -- [Review audit log](azure-devops-auditing.md#review-audit-log) -- [Export audit events](azure-devops-auditing.md#export-auditing-events) -- [List of audit events](auditing-events.md) -- [Introducing Azure DevOps Audit Stream on Azure DevOps blog](https://devblogs.microsoft.com/devops/introducing-azure-devops-audit-stream/) +- [Review the audit log](azure-devops-auditing.md#review-audit-log) +- [Export audit events](azure-devops-auditing.md#export-audit-events) +- [View the list of audit events](auditing-events.md) +- [Read about Azure DevOps Audit Stream on the Azure DevOps blog](https://devblogs.microsoft.com/devops/introducing-azure-devops-audit-stream/) diff --git a/docs/organizations/audit/azure-devops-auditing.md b/docs/organizations/audit/azure-devops-auditing.md index 63a319f4efd..8ba0a328c39 100644 --- a/docs/organizations/audit/azure-devops-auditing.md +++ b/docs/organizations/audit/azure-devops-auditing.md @@ -1,14 +1,15 @@ --- -title: Access, export, filter audit logs for Azure DevOps -titleSuffix: Azure DevOps -description: Get started accessing, reviewing, exporting, and filtering the Azure DevOps audit logs. +title: Access, export, filter audit logs +titleSuffix: Azure DevOps Service +description: Get started accessing, reviewing, exporting, and filtering the audit logs. ms.subservice: azure-devops-audit ms.assetid: 9F1D0A0F-02D5-4E06-A5EC-C220472A0F66 ms.author: chcomley author: chcomley -ms.topic: quickstart -monikerRange: '= azure-devops' -ms.date: 08/03/2022 +ai-usage: ai-assisted +ms.topic: how-to +monikerRange: 'azure-devops' +ms.date: 02/26/2025 --- # Access, export, and filter audit logs @@ -18,40 +19,28 @@ ms.date: 08/03/2022 > [!NOTE] > Auditing is still in public preview. -On the Auditing page of your Organization Settings, you can access, export, and filter audit logs, which track the many changes that occur within your Azure DevOps organization(s). With these logs, you can use them to meet your organization's compliance and governance goals. +Keeping track of activities within your Azure DevOps environment is crucial for security and compliance. Auditing helps you monitor and log these activities, providing transparency and accountability. This article explains the auditing features and shows how to set it up and use it effectively. [!INCLUDE [important-backed-by-azure-active-directory](includes/important-backed-by-azure-active-directory.md)] -Audit changes occur whenever a user or service identity within the organization edits the state of an artifact. You may see events logged for any of the following occurrences: +Audit changes occur whenever a user or service identity within the organization edits the state of an artifact. Events that might get logged include: -- permissions changes -- deleted resources -- branch policy changes -- auditing log access and downloads -- and much much more... +- Permissions changes +- Deleted resources +- Branch policy changes +- Log access and downloads +- Many other types of changes -Events get stored for 90 days, after which they're deleted. However, you can back up audit events to an external location to keep the data for longer than the 90-day period. +These logs provide a comprehensive record of activities, helping you monitor and manage the security and compliance of your Azure DevOps organization. -Auditing events can be accessed through two methods on the Auditing page in your Organization Settings: -- Through the Auditing logs available under the main Logs tab, and -- via any Auditing streams set up through the [Streams](auditing-streaming.md) tab. +Audit events are stored for 90 days before they're deleted. To retain the data for longer, you can back up audit events to an external location. > [!NOTE] -> Auditing isn't available for on-premises deployments of Azure DevOps Server. It is possible to connect an [Auditing stream](auditing-streaming.md) from an Azure DevOps Services instance to an on-premises or cloud-based instance of Splunk, but you must make sure you allow IP ranges for inbound connections. For details, see [Allowed address lists and network connections, IP addresses and range restrictions](../security/allow-list-ip-url.md#range-restrictions). +> Auditing isn't available for on-premises deployments of Azure DevOps. However, you can connect an [Auditing stream](auditing-streaming.md) from an Azure DevOps Services instance to an on-premises or cloud-based instance of Splunk. Ensure you allow IP ranges for inbound connections. For details, see [Allowed address lists and network connections, IP addresses and range restrictions](../security/allow-list-ip-url.md#range-restrictions). +### Prerequisites -## Prerequisites - -Auditing is turned off by default for all Azure DevOps Services organizations and can be [toggled on and off](#enable-and-disable-auditing) by organization Owners and Project Collection Administrators in the *Organization Settings* page. -By default, Project Collection Administrators are the only group that has full access to the Auditing feature. - -### Audit permissions - -- By default, members of the **organization Owners** and **Project Collection Administrators** groups have full access to all Auditing features. -- Specific Audit permissions can be granted to any group via the Security Permissions page in Organization Settings. - -> [!NOTE] -> If the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization, users added to the **Project-Scoped Users** group can't view **Auditing** and have limited visibility to **Organization settings** pages. For more information and important security-related mentions, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). +[!INCLUDE [prerequisites-auditing](includes/prerequisites-auditing.md)] ## Enable and disable auditing @@ -60,30 +49,27 @@ By default, Project Collection Administrators are the only group that has full a 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. 3. Select **Policies** under the **Security** header. -4. Toggle the **Log Audit Events** button ON. +4. Switch the **Log Audit Events** button to ON. ![Screenshot of Auditing policy enabled.](media/azure-devops-auditing/enable-auditing-policy.png) -The organization will now have Auditing enabled. You may need to refresh the page to see **Auditing** appear in the sidebar. Audit events will start appearing on Auditing Logs and through any audit streams that have been configured. - -5. If you no longer want to receive Auditing events, toggle the **Enable Auditing** button to OFF. When the button is toggled off, the **Auditing** page will no longer appear in the sidebar and the Auditing Logs page will be unavailable. Any audit streams will stop receiving events. + Auditing is enabled for the organization. Refresh the page to see **Auditing** appear in the sidebar. Audit events start appearing in Auditing Logs and through any configured audit streams. +5. If you no longer want to receive Auditing events, switch the **Enable Auditing** button to OFF. This action removes the **Auditing** page from the sidebar and makes the Auditing Logs page unavailable. Any audit streams stop receiving events. #### [Current page](#tab/current-page) 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. 3. Select **Policies** under the **Security** header. -4. Toggle the **Log Audit Events** button ON. +4. Switch the **Log Audit Events** button to ON. ![Screenshot of Auditing policy enabled.](media/azure-devops-auditing/enable-auditing-policy.png) -The organization will now have Auditing enabled. You may need to refresh the page to see **Auditing** appear in the sidebar. Audit events will start appearing on Auditing Logs and through any audit streams that have been configured. - -5. If you no longer want to receive Auditing events, toggle the **Enable Auditing** button to OFF. When the button is toggled off, the **Auditing** page will no longer appear in the sidebar and the Auditing Logs page will be unavailable. Any audit streams will stop receiving events. + Auditing is enabled for the organization. Refresh the page to see **Auditing** appear in the sidebar. Audit events start appearing in Auditing Logs and through any configured audit streams. +5. If you no longer want to receive Auditing events, switch the **Enable Auditing** button to OFF. This action removes the **Auditing** page from the sidebar and makes the Auditing Logs page unavailable. Any audit streams stop receiving events. * * * - ## Access auditing #### [Preview page](#tab/preview-page) @@ -101,11 +87,11 @@ The organization will now have Auditing enabled. You may need to refresh the pag ![Screenshot of highlighted Permissions tab.](media/azure-devops-auditing/select-permissions-preview.png) -5. Set **View audit log** to **allow**, and then select **Save changes**. +5. Set **View audit log** to **Allow**, and then select **Save changes**. ![Screenshot of Auditing access permission preview.](media/azure-devops-auditing/audit-log-permission-red-box-preview.png) -The user or group members will now have access to view your organization's audit events. + The user or group members have access to view your organization's audit events. #### [Current page](#tab/current-page) @@ -126,7 +112,7 @@ The user or group members will now have access to view your organization's audit ![Screenshot of Auditing access permission current view.](media/azure-devops-auditing/audit-log-permission-red-box.png) -The user or group members will now have access to view your organization's audit events. + The user or group members have access to view your organization's audit events. * * * @@ -149,61 +135,73 @@ Each audit event also records additional information to what's viewable on the a ### ID & correlation ID -Each audit event has unique identifiers called the “ID” and “CorrelationID”. The correlation ID is helpful for finding related audit events. For example, a created project can generate several dozen audit events. You can link these events together because they all have the same correlation ID. +Each audit event has unique identifiers called the `ID` and `CorrelationID`. The correlation ID is useful for finding related audit events. For example, creating a project can generate several dozen audit events, all linked by the same correlation ID. -When an audit event ID matches its correlation ID, it indicates that the audit event is the parent or original event. To see only originating events, look for the events where “ID” equals the “Correlation ID” in question. Then, if you want to investigate an event and its related events, you can look up all events with a correlation ID that matches the originating event's ID. Not all events have related events. +When an audit event ID matches its correlation ID, it indicates that the audit event is the parent or original event. To see only originating events, look for events where the `ID` equals the `Correlation ID`. If you want to investigate an event and its related events, look up all events with a correlation ID that matches the originating event's ID. Not all events have related events. ### Bulk events -Some audit events can contain multiple actions that took place at once, also known as "bulk audit events". You can distinguish these events from others with an "Information icon" on the far right of the event. You can find individual details on the actions included in the bulk audit events through the downloaded audit data. +Some audit events, known as "bulk audit events," can contain multiple actions that took place simultaneously. You can identify these events by the "Information icon" on the far right of the event. To view individual details of the actions included in bulk audit events, refer to the downloaded audit data. -![Auditing more information icon](media/azure-devops-auditing/audit-log-more-information-high-res.png) +![Screenshot shows auditing more information icon.](media/azure-devops-auditing/audit-log-more-information-high-res.png) -Selecting the information icon displays additional information about what happened in this audit event. +Selecting the information icon displays more details about the audit event. -As you look through the audit events, you may find the *Category* and *Area* columns of interest. These columns allow you to sift through to find only the types of events that you're interested in. The following tables are a list of categories and areas, and their descriptions: +As you review the audit events, the *Category* and *Area* columns can help you filter and find specific types of events. The following tables list the categories and areas, along with their descriptions: -### List of events +#### List of events -We try our best to add new auditing events monthly. If you would like to see an event that isn't currently tracked, consider sharing that with us in the [Developer Community](https://developercommunity.visualstudio.com/search?space=21). +We strive to add new auditing events on a monthly basis. If there's an event you'd like to see tracked that isn't currently available, share your suggestion with us in the [Developer Community](https://developercommunity.visualstudio.com/search?space=21). -For a full list of all events that we currently can emit through the Auditing feature, see the [Auditing Events List](/azure/devops/organizations/audit/auditing-events). +For a comprehensive list of all events that can be emitted through the Auditing feature, see the [Auditing Events List](/azure/devops/organizations/audit/auditing-events). > [!NOTE] > Want to find out what event areas your organization logs? Be sure to check out the [Audit Log Query API](/rest/api/azure/devops/audit/audit-log/query): `https://auditservice.dev.azure.com/{YOUR_ORGANIZATION}/_apis/audit/actions`, replacing {YOUR_ORGANIZATION} with the name of your organization. This API returns a list of all audit events (or actions) your organization could emit. ## Filter audit log by date and time -In the current Auditing UI, you can only filter events by a date or time range. To scope down the viewable audit events by a date range, select the time filter on the top-right-hand side of the page. +In the current Auditing UI, you can filter events only by date or time range. + +1. To narrow down the viewable audit events, select the time filter. -![Auditing entry filter by date & time](media/azure-devops-auditing/audit-log-date-time-picker.png) + ![Screenshot shows auditing entry filter by date & time.](media/azure-devops-auditing/audit-log-date-time-picker.png) -Use the filters to select any time range over the last 90 days and scope it down to the minute. Once you've selected a time range, select Apply on the time range selector to start the search. By default, the top 200 results are returned for that time selection. If there are more results, then you can scroll down to load them onto the page. +2. Use the filters to select any time range within the last 90 days and scope it down to the minute. -## Export auditing events +3. Select **Apply** on the time range selector to start the search. + By default, the top 200 results return for that time selection. If there are more results, you can scroll down to load more entries onto the page. -To do a more detailed search on the auditing data or store data for more than 90 days of data, you'll need to export existing audit events. The exported data can then be stored in another location or service. +## Export audit events -Select the **Download** button in the top-right-hand side of the auditing page to export auditing events. You can select to download as a CSV or JSON file. +To perform a more detailed search on the auditing data or store data for more than 90 days, export the existing audit events. You can store the exported data in another location or service. -Selecting either option starts the download. Events get downloaded based on the time range you've selected in the filter. If you have one day selected, then you get one day’s worth of data returned. Transversely, if you wanted all 90 days, select 90 days from the time range filter and then start the download. +To export auditing events, select the **Download** button. You can choose to download the data as a CSV or JSON file. + +The download includes events based on the time range you select in the filter. For example, if you select one day, you get one day's worth of data. To get all 90 days, select **90 days** from the time range filter and then start the download. > [!NOTE] -> For long-term storage and analysis of your auditing events, consider sending your events downstream to a Security Information and Event Management (SIEM) tool using the [Audit Streaming feature](auditing-streaming.md). Exporting the auditing logs is recommended for cursory data analysis. +> For long-term storage and analysis of your auditing events, consider using the [Audit Streaming feature](auditing-streaming.md) to send your events to a Security Information and Event Management (SIEM) tool. We recommend exporting the auditing logs for cursory data analysis. -To filter data by more than the date/time range, we recommend downloading logs as CSV files and importing Microsoft Excel or other CSV parsers to sift through Area and Category columns. For analysis on even larger datasets, we recommend uploading exported audit events into a Security Incident and Event Management (SIEM) tool using the [Audit Streaming function](auditing-streaming.md). Such tools allow you to keep greater than 90 days of events, searches, generated reports, and configured alerts based on audit events. +- To filter data beyond the date/time range, download logs as CSV files and import them into Microsoft Excel or other CSV parsers to sift through the Area and Category columns. +- To analyze larger datasets, upload exported audit events into a Security Incident and Event Management (SIEM) tool using the [Audit Streaming function](auditing-streaming.md). SIEM tools allow you to retain more than 90 days of events, perform searches, generate reports, and configure alerts based on audit events. ## Limitations -The following limitations exist for what can be audited. +The following limitations apply to what can be audited: + +* **Microsoft Entra group membership changes**: Auditing Logs include updates to Azure DevOps groups and group membership, when an event Area is `Groups`. However, if you manage membership via Microsoft Entra groups, additions and removals of users from those Microsoft Entra groups aren't included in these logs. Review the Microsoft Entra audit logs to see when a user or group was added or removed from a Microsoft Entra group. +* **Sign-in events**: Azure DevOps doesn't track sign-in events. To review sign-in events to your Microsoft Entra ID, view the Microsoft Entra audit logs. +* **Indirect user additions:** In some cases, users might get added to your organization indirectly and show in the audit log added by Azure DevOps Services. For instance, if a user is assigned to a work item, they might get added automatically to the organization. While an audit event gets generated for the user being added, there isn't a corresponding audit event for the work item assignment that triggered the user addition. To trace these events, consider the following actions: + * Review your work item history for the corresponding timestamps to see if this user was assigned to any work items. + * Check the audit log for any related events that might provide context. -* Azure Active Directory (Azure AD) group membership changes – Auditing Logs include updates to Azure DevOps groups and group membership (when an event Area is "Groups"). However, if you manage membership via Azure AD groups, such additions and removals of users from those Azure AD groups aren't audited by Azure DevOps in these logs. Review the Azure AD audit logs to see when a user or group was added or removed from an Azure AD group. -* Sign in events – We don't track sign in events for Azure DevOps. View the Azure AD audit logs to review sign in events to your Azure AD. ## Frequently asked questions ### Q: What is the DirectoryServiceAddMember group and why is it appearing on the audit log? -A: The DirectoryServiceAddMember group is a system group used to help manage membership to your Azure DevOps organization. Membership to this system group can be affected by many system, user, and administrative actions. As this group is a system group used only for internal processes, customers can disregard audit log entries that capture membership changes to this group. +A: The `DirectoryServiceAddMember` group helps manage membership in your organization. Many system, user, and administrative actions can affect membership in this system group. Since this group is used only for internal processes, you can disregard audit log entries that capture membership changes to this group. ## Related articles -- [Auditing streaming](auditing-streaming.md) + +- [Create audit streaming](auditing-streaming.md) +- [Learn about auditing events](auditing-events.md) diff --git a/docs/organizations/audit/includes/important-backed-by-azure-active-directory.md b/docs/organizations/audit/includes/important-backed-by-azure-active-directory.md index c8c951c3da5..24f0a424c00 100644 --- a/docs/organizations/audit/includes/important-backed-by-azure-active-directory.md +++ b/docs/organizations/audit/includes/important-backed-by-azure-active-directory.md @@ -6,4 +6,4 @@ author: chcomley --- > [!IMPORTANT] -> Auditing is only available for organizations backed by Azure Active Directory. For more information, see [Connect your organization to Azure Active Directory](../../accounts/connect-organization-to-azure-ad.md). +> Auditing is only available for organizations backed by Microsoft Entra ID. For more information, see [Connect your organization to Microsoft Entra ID](../../accounts/connect-organization-to-azure-ad.md). diff --git a/docs/organizations/audit/includes/prerequisites-auditing.md b/docs/organizations/audit/includes/prerequisites-auditing.md new file mode 100644 index 00000000000..ae9e6d52c3f --- /dev/null +++ b/docs/organizations/audit/includes/prerequisites-auditing.md @@ -0,0 +1,15 @@ +--- +ms.topic: include +ms.subservice: azure-devops-audit +ms.author: chcomley +author: chcomley +--- + +Auditing is turned off by default for all Azure DevOps Services organizations. Ensure that only authorized personnel have access to sensitive auditing information. + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | Member of the [Project Collection Administrators group](../../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. Or the following auditing permissions per user or group, set to **Allow**:
      - Manage audit streams
      - View audit log
      PCAs can grant these permissions to any users or groups for managing organization streams, including *Delete audit streams*. | + +> [!NOTE] +> If the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization, users in the **Project-Scoped Users** group can't view **Auditing** and have limited visibility to **Organization settings** pages. For more information and important security-related details, see [Limit user visibility for projects and more](../../../user-guide/manage-organization-collection.md#limit-user-visibility-for-projects-and-more). diff --git a/docs/organizations/audit/media/auditing-streaming/azure-monitor-log-keys.png b/docs/organizations/audit/media/auditing-streaming/azure-monitor-log-keys.png index 443d19007b8..137f181da7f 100644 Binary files a/docs/organizations/audit/media/auditing-streaming/azure-monitor-log-keys.png and b/docs/organizations/audit/media/auditing-streaming/azure-monitor-log-keys.png differ diff --git a/docs/organizations/audit/media/auditing-streaming/create-new-auditing-stream.png b/docs/organizations/audit/media/auditing-streaming/create-new-auditing-stream.png index 7b2da066c3d..76fd58e2bf0 100644 Binary files a/docs/organizations/audit/media/auditing-streaming/create-new-auditing-stream.png and b/docs/organizations/audit/media/auditing-streaming/create-new-auditing-stream.png differ diff --git a/docs/organizations/audit/media/auditing-streaming/select-auditing-organization-settings.png b/docs/organizations/audit/media/auditing-streaming/select-auditing-organization-settings.png index 85b023167ac..4e659bc09f5 100644 Binary files a/docs/organizations/audit/media/auditing-streaming/select-auditing-organization-settings.png and b/docs/organizations/audit/media/auditing-streaming/select-auditing-organization-settings.png differ diff --git a/docs/organizations/audit/media/azure-devops-auditing/access-audit-log-red-box.png b/docs/organizations/audit/media/azure-devops-auditing/access-audit-log-red-box.png index ba75d2a66d0..993129c93b3 100644 Binary files a/docs/organizations/audit/media/azure-devops-auditing/access-audit-log-red-box.png and b/docs/organizations/audit/media/azure-devops-auditing/access-audit-log-red-box.png differ diff --git a/docs/organizations/audit/media/azure-devops-auditing/enable-auditing-policy.png b/docs/organizations/audit/media/azure-devops-auditing/enable-auditing-policy.png index 876e888fb16..88906201d1e 100644 Binary files a/docs/organizations/audit/media/azure-devops-auditing/enable-auditing-policy.png and b/docs/organizations/audit/media/azure-devops-auditing/enable-auditing-policy.png differ diff --git a/docs/organizations/audit/toc.yml b/docs/organizations/audit/toc.yml index 05f2dd0bb84..40f8484a23e 100644 --- a/docs/organizations/audit/toc.yml +++ b/docs/organizations/audit/toc.yml @@ -2,11 +2,11 @@ displayName: policy, permission, resource, change, log, export, filter href: azure-devops-auditing.md - name: Create audit streaming - href: auditing-streaming.md displayName: data, process, processing, alert, alerting, Splunk, Event Grid, Azure Monitor Log + href: auditing-streaming.md - name: List of audit events - href: auditing-events.md displayName: audit, events, list + href: auditing-events.md - name: Export user list displayName: access level, account, member, log href: ../security/export-users-audit-log.md diff --git a/docs/organizations/billing/add-backup-billing-managers.md b/docs/organizations/billing/add-backup-billing-managers.md deleted file mode 100644 index 26a7c35ed69..00000000000 --- a/docs/organizations/billing/add-backup-billing-managers.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Add a user to manage billing -titleSuffix: Azure DevOps Services -description: Add a user who can set up and manage billing for Azure DevOps. -ms.custom: seodec18, freshness-fy22q1, engagement-fy23 -ms.subservice: azure-devops-billing -ms.assetid: bd87ec5c-84f2-4efa-bc37-a6999cb9532e -ms.topic: conceptual -ms.author: chcomley -author: chcomley -ms.date: 01/05/2023 -monikerRange: 'azure-devops' ---- - -# Add a user to manage billing - -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -Give another user access, so they can [set up billing](set-up-billing-for-your-organization-vs.md) or [change the Azure subscription used for billing](change-azure-subscription.md) for your Azure DevOps organization. - -Assign any of the following roles to a user under the subscription your organization uses for billing: [Owner](/azure/role-based-access-control/built-in-roles#owner), [Contributor](/azure/role-based-access-control/built-in-roles#contributor), [Service admin](/azure/billing/billing-add-change-azure-subscription-administrator), and [Co-admin](/azure/billing/billing-add-change-azure-subscription-administrator). For more information, see [Azure roles](/azure/role-based-access-control/rbac-and-directory-admin-roles). - -[!INCLUDE [pricing-calculator-tip](../../includes/pricing-calculator-tip.md)] - -## Prerequisites - -- You must be the [Azure Account Administrator](/azure/cost-management-billing/manage/add-change-subscription-administrator) to give another user access to manage billing. - -## Give a user access to manage billing - -1. [Sign in to the Azure portal](https://portal.azure.com/) as the Azure Account Administrator. - -2. Enter *subscriptions* in the search box, and then select **Subscriptions** from the drop-down menu. Choose the subscription to modify, if more that one subscription's listed. - - ![Screenshot of highlighted subscription to modify for backup billing manager.](media/add-backup-billing-manager/choose-subscription-to-modify.png) - -3. Select **Access control (IAM)**. - - ![Screenshot showing highlighted Access control (IAM) button in Azure portal.](media/add-backup-billing-manager/choose-access-control.png) - -4. Select **Add**. - - ![Screenshot showing highlighted Add button.](media/add-backup-billing-manager/add-role-assignment.png) - -5. Choose the user's *role* and *assignment* type from the dropdown menus. - - ![Screenshot showing user role and assignment type dropdown menus.](media/add-backup-billing-manager/choose-role-and-select-an-assignment-type.png) - -6. Select a user or group by entering their *name* or *email alias*. (Select a device by entering its *name*.) - - ![Screenshot showing selected member name and email alias.](media/add-backup-billing-manager/add-permissions-select-member-choose-save.png) - -7. Choose **Save**, once you're done with your update. - -Now you have a user who can [set up](set-up-billing-for-your-organization-vs.md) or [change billing](change-azure-subscription.md) for your organization. - -> [!NOTE] -> The user must accept their email invitation before they can access the Azure subscription, if they aren't in your directory. - -## Next steps - -> [!div class="nextstepaction"] -> [Learn about Azure Cost Management and Billing](/azure/cost-management-billing/cost-management-billing-overview) - -## Related articles - -* [Pay for Basic access for users](buy-basic-access-add-users.md) -* [Pay for Basic + Test Plans](buy-basic-access-add-users.md) -* [Pay for Azure Pipelines](../../pipelines/licensing/concurrent-jobs.md#how-much-do-parallel-jobs-cost) -* [Set up billing](set-up-billing-for-your-organization-vs.md) -* [Change the Azure subscription used for billing](change-azure-subscription.md) -* [Get Azure DevOps billing support](https://azure.microsoft.com/support/devops/) diff --git a/docs/organizations/billing/billing-faq.yml b/docs/organizations/billing/billing-faq.yml index c37343fe05c..533a0bc67b6 100644 --- a/docs/organizations/billing/billing-faq.yml +++ b/docs/organizations/billing/billing-faq.yml @@ -2,14 +2,14 @@ metadata: title: Billing FAQs titleSuffix: Azure DevOps - ms.custom: seodec18, freshness-fy22q1, engagement-fy23 + ms.custom: freshness-fy22q1, engagement-fy23 description: Find answers to frequently asked questions (FAQs) about billing for your organization in Azure DevOps. ms.subservice: azure-devops-billing ms.assetid: 62d94b8a-256a-4347-905a-3393f5d8a13f ms.topic: faq ms.author: chcomley author: chcomley - ms.date: 05/23/2023 + ms.date: 03/05/2025 monikerRange: '<= azure-devops' title: Billing FAQs summary: | @@ -25,7 +25,7 @@ sections: - question: | Q: What is user assignment-based billing? answer: | - A: With user assignment-based billing, you only pay for the users you assign an access level. When you remove the users, charges stop. There's no longer an extra step of increase/decreasing the paid count. + A: With user assignment-based billing, you pay for the users you assign an access level. When you remove the users, charges stop. In assignment-based billing, all organizations begin with new users added from projects with Stakeholder access. We don't charge for new users who only need free Stakeholder access. If you want all new users to get Basic, change the [default access level](#q--how-can-new-users-get-basic-instead-of-stakeholder-when-added-to-a-project-) for your organization to Basic. @@ -36,28 +36,26 @@ sections: - question: | Q: How can new users get Basic instead of Stakeholder when added to a Project? answer: | - A: When a user is new to the organization and is added to a project, previously they would get Basic access level. If you purchased Basic, but it wasn't yet assigned to a user. With assignment-based billing, you pay only for the users you assign, so there aren't any "unassigned" users. - - If you want all new users added to a project to get Basic, change the default access level (**Organization Settings** > **Billing**) to Basic. + A: If you want all new users added to a project to get Basic, change the default access level (**Organization Settings** > **Billing**) to Basic. ![Default access](media/shared/default-access-level-basic.png) - For more granular control over the access level that's assigned to new users, consider setting up group rules. [Group rules](../accounts/assign-access-levels-by-group-membership.md) take precedence over default access level. The default access level only applies when a user has zero group rules applied. Group rules assign access to users who aren't directly assigned an access level. To have these group rules apply to your existing users, you need to [remove direct assignments](../accounts/assign-access-levels-by-group-membership.md#remove-direct-assignments). + For more granular control over the access level assigned to new users, consider setting up group rules. [Group rules](../accounts/assign-access-levels-by-group-membership.md) take precedence over default access level. The default access level only applies when a user has zero group rules applied. Group rules assign access to users who aren't directly assigned an access level. To have these group rules apply to your existing users, you need to [remove direct assignments](../accounts/assign-access-levels-by-group-membership.md#remove-direct-assignments). - question: | - Q: Will I get charged for users even if they never sign in? + Q: Do I get charged for users even if they never sign in? answer: | A: If you add a user with Basic or Basic + Test Plans access level, you pay at the time of assignment. When you create a [group rule](../accounts/assign-access-levels-by-group-membership.md), applied to users without direct assignments, you don't start paying until they sign in and receive an access level. - question: | - Q: What happens when a user is deleted in Azure AD? + Q: What happens when a user is deleted in Microsoft Entra ID? answer: | - A: When a user is permanently deleted in Azure AD, within a few hours, they're removed from Azure DevOps and you're no longer be billed for their license. Guest users may need to be removed manually from Azure DevOps. For more information, see [Delete a user in Azure AD](https://learn.microsoft.com/troubleshoot/azure/active-directory/troubleshoot-user-creation-deletion-issues?tabs=azure-portal#delete-a-user) + A: When a user is permanently deleted in Microsoft Entra ID, within a few hours, they're removed from Azure DevOps and you're no longer be billed for their license. You might need to remove guest users manually from Azure DevOps. For more information, see [Delete a user in Microsoft Entra ID](/troubleshoot/azure/active-directory/troubleshoot-user-creation-deletion-issues?tabs=azure-portal#delete-a-user) - question: | Q: How can I stop paying for users who aren't actively using Azure DevOps? answer: | - A: If you have inactive users, stop paying for them by removing them or assigning them a free Stakeholder access level. Sort by **Last Access** to find users who haven't accessed the organization recently. Find out how recently they got added by exporting the list of users and checking the **Date Added** column. + A: If you have inactive users, stop paying for them by removing them or assigning them a free Stakeholder access level. Sort by **Last Access** to find users who aren't active. Find out how recently they got added by exporting the list of users and checking the **Date Added** column. ![Last access](media/shared/last-access.png) @@ -65,41 +63,53 @@ sections: Q: How can I pay only once per user across multiple organizations? answer: | A: Multi-organization billing/licensing is available. For more information, see [multi-organization billing](#multi-organization-billing). - - - question: | - Q: What's the difference between daily pro-rated charges instead of monthly committed purchases? - answer: | - A: As part of the change to user assignment-based billing, we've also switched from monthly to daily billing. When you give a user paid access for a few weeks, or even a few days, you pay only for the time they got assigned to the paid access, rather than for a full month. As we switch your organization from monthly to daily billing, your next Azure bill is likely lower than it was previously. The next month is back to normal once a full month of daily charges has accumulated. - question: | - Q: Do daily pro-rated charges apply to other purchases also? + Q: How are daily pro-rated charges calculated? answer: | - A: Pro-rated charges apply to all purchases including pipelines (self-hosted and MS hosted) and artifacts storage. For example, if you purchased five MS hosted pipelines on the 20th of the month, then the charges for that month for pipelines are pro-rated. In this case, you're charged one-third of the monthly cost of five hosted pipelines. - + A: The quantity for all Azure DevOps meters, Basic, Basic + Test Plans, MS-Hosted CI/CD, Self-Hosted CI/CD and Artifacts, pro-rates at 1/31st of a unit per day. So, your charges during a month with fewer than 31 days are slightly less than the published monthly rate. + - question: | Q: What happens if I set up billing before my Azure Test Plans trial expires? answer: | - A: If you [set up billing](set-up-billing-for-your-organization-vs.md) before your trial expires, you don't get charged until the trial ends. + A: If you [set up billing](set-up-billing-for-your-organization-vs.md#set-up-billing) before your trial expires, you don't get charged until the trial ends. - question: | Q: What happens if I don't set up billing and my Azure Test Plans trial expires? answer: | - A: Those users assigned Basic + Test Plans lose access until you do [set up billing](set-up-billing-for-your-organization-vs.md). + A: Those users assigned Basic + Test Plans lose access until you do [set up billing](set-up-billing-for-your-organization-vs.md#set-up-billing). - question: | Q: How did paid extensions change in the Azure DevOps Marketplace in July 2019? answer: | - A: Microsoft ended support for purchasing third party paid Azure DevOps extensions through your Azure bill on July 1, 2019. We're encouraging our publishers to offer paid access to their services directly. - + A: Microsoft ended support for purchasing non-Microsoft paid Azure DevOps extensions through your Azure bill on July 1, 2019. We're encouraging our publishers to offer paid access to their services directly. + - question: | - Q: Do I need to pay to add "Package Management" users in Team Foundation Server 2017 and 2018? + Q: How do I pay for Azure DevOps Server through Azure? answer: | - A: Since June 1, 2019, on-premises Azure Artifacts, for example, Package Management, is included with the Basic license. For Azure DevOps Server 2019, purchase a Basic license and assign it to the user. For TFS 2017 and 2018, no other purchase is required, but you still need to [assign users the Package Management extension license](../../artifacts/start-using-azure-artifacts.md) to use the feature. + A: You can [pay for Azure DevOps Server](https://azure.microsoft.com/pricing/details/devops/server/) through Azure on a monthly basis and you can cancel anytime. You need the following items: + - At least one Visual Studio subscription, which includes the server license. You can also buy the server license through [classic purchasing](https://azure.microsoft.com/pricing/details/devops/server/). + - A Client Access License (CAL) for each user accessing the server. + - Paid access to Test Plans for each user accessing Test Plans. + + **Buy Visual Studio subscriptions for users who need access to Visual Studio** + Visual Studio Subscriptions include one server license and one user CAL. Visual Studio Enterprise and Visual Studio Test Professional also include access to Test Plans. Test Professional is available as a standard subscription, so you can’t purchase through Azure. + - [Buy Visual Studio Enterprise (cloud subscription, monthly)](https://marketplace.visualstudio.com/items?itemName=ms.vs-enterprise-monthly) + - [Buy Visual Studio Professional (cloud subscription, monthly)](https://marketplace.visualstudio.com/items?itemName=ms.vs-professional-monthly) + - [Buy Visual Studio Test Professional (standard subscription, yearly)](https://visualstudio.microsoft.com/vs/test-professional/) + + **Buy Azure DevOps Basic or Basic + Test Plans for anyone else** + 1. [Create an Azure DevOps organization](/azure/devops/organizations/accounts/create-organization) or select one you already use. + 2. [Set up billing](/azure/devops/organizations/billing/set-up-billing-for-your-organization-vs) for the organization. + 3. [Add users who need access](/azure/devops/organizations/billing/buy-basic-access-add-users) to Azure DevOps Server, assigning them Basic or Basic + Test Plans. + + Each organization includes five free Basic users and doesn't include a CAL. Add five non-users to the server to ensure you’re paying for everyone who needs a server CAL. + - question: | Q: How do I pay for Azure DevOps support? answer: | - A: If you're already using Azure, chances are you already have an [Azure support plan](https://azure.microsoft.com/support/plans/). Also, you don't need to pay for [billing support](https://ms.portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/overview). Report a service outage from our [service status page](https://status.dev.azure.com/). + A: If you're already using Azure, chances are you already have an [Azure support plan](https://azure.microsoft.com/support/plans/). Also, you don't need to pay for [billing support](https://ms.portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/overview). If you need technical support with Azure DevOps and don't have an [Azure support plan](https://azure.microsoft.com/support/plans/) already, complete the following steps: @@ -117,7 +127,7 @@ sections: - question: | Q: Can I buy Azure DevOps by using a purchase order? answer: | - A: No. Azure DevOps must be purchased through an Azure subscription. (Think of it as your Azure billing account.) + A: No. You must purchase Azure DevOps through an Azure subscription. Think of it as your Azure billing account. - question: | Q: Can I use Azure DevOps for free? @@ -131,24 +141,15 @@ sections: answer: | A: You can buy Azure DevOps with most Azure subscriptions. We support Azure subscriptions connected to your [Enterprise Agreement (EA)](https://azure.microsoft.com/pricing/enterprise-agreement/), Azure subscriptions set up by - Cloud Solution Providers (CSPs), through Microsoft Open License resellers, and Pay-As-You-Go. You can also buy using Azure subscriptions that Visual Studio subscribers set up as a subscriber benefit. (But no, your monthly credit can't be used pay for more Visual Studio subscriptions.) + Cloud Solution Providers (CSPs), through Microsoft Open License resellers, and pay-as-you-go. - The only notable exclusion is that you can't use the [Azure free trial](https://azure.microsoft.com/pricing/free-trial/), Government, or National clouds. + The only notable exclusion is that you can't use the [Azure free trial](https://azure.microsoft.com/pricing/free-trial/), Government, or National cloud subscriptions. - - question: | - Q: Can I use the Azure free account to buy from the Visual Studio Marketplace? - answer: | - A: No. You can't use the [Azure free account](https://azure.microsoft.com/pricing/free-trial/) to pay for Visual Studio Marketplace purchases. Instead, set up a separate Pay-As-You-Go Azure subscription before or during your purchase. - question: | Q: Can I use the monthly Azure credits from my Visual Studio subscription to buy Azure DevOps? answer: | A: No, you can't use the monthly Azure credits from [Visual Studio subscriptions](https://visualstudio.microsoft.com/products/subscriber-benefits-vs) - to pay for Azure DevOps. Before you make purchases by using this type of Azure subscription, you must [remove your spending limit](https://azure.microsoft.com/pricing/spending-limits/). - - > [!div class="mx-imgBorder"] - > ![Screenshot of spending limit.](media/spending-limit.png) - - + to pay for Azure DevOps. You can use the subscription by [removing your spending limit](https://azure.microsoft.com/pricing/spending-limits/). > [!NOTE] > Remove your spending limit indefinitely, which prevents disabling your Azure subscription when your recurring monthly charges get billed the next month. @@ -158,27 +159,23 @@ sections: > ![Screenshot of removing spending limit indefinitely.](media/remove-spending-limit.png) - question: | - Q: Am I required to buy other Azure services? + Q: Can I use credits from the Azure Sponsorship Offer to pay for Azure DevOps Services? answer: | - A: Not at all. If you only want to buy Azure DevOps via Azure, that's okay. - + A: You can try to add the subscription with the Azure Sponsorship Offer and see if the system accepts it. If the subscription has a limit, then you can't use it. + - question: | - Q: Can I apply tags to organizations from the Azure portal? + Q: Am I required to buy other Azure services? answer: | - A: Yes. Select the Azure subscription that's linked to the desired Azure DevOps organization, in Settings > Resources. - :::image type="content" source="media/billing-faq/organization-under-subscription.png" alt-text="Screenshot of locating your organization"::: - - Select the desired organization from list and apply tags by selecting the action **Assign tags**. The tags you assign appear in your Azure bill for the charges associated with the selected Azure DevOps organization. - :::image type="content" source="media/billing-faq/apply-billing-tag-on-organization.png" alt-text="Screenshot of applying tags"::: - + A: Not at all. If you only want to buy Azure DevOps via Azure, that's okay. + ## Multi-organization billing - Multi-organization billing allows you to pay once per human user, for organizations under the same Azure billing subscription. This does not apply to service principals and managed identities, which will still be charged on a user assignment-based billing. Any service principal or managed identity will be charged once per organization that it has been added to. + Multi-organization billing allows you to pay once per human user, for organizations under the same Azure billing subscription. This scenario doesn't apply to service principals and managed identities, which still get charged on a user assignment-based billing. Any service principal or managed identity gets charged once per organization that it gets added to. - question: | Q: Does multi-organization billing make sense for all customers? answer: | - A: No. For example, with the default assignment-based billing, each organization gets five free Basic users. When you change to multi-organization billing the Azure subscription gets five free Basic users, to be shared amongst all the organizations that are linked to it. When most users access only one organization, then five free users are most cost effective. If many users access multiple organizations, then multi-organization billing is likely the best option. + A: No. For example, with the default assignment-based billing, each organization gets five free Basic users. When you change to multi-organization billing the Azure subscription gets five free Basic users, to be shared among all the organizations linked to it. When most users access only one organization, then five free users are most cost effective. If many users access multiple organizations, then multi-organization billing might be the best option. - question: | Q: Do I have to turn on multi-organization billing for each of my organizations? @@ -199,15 +196,15 @@ sections: Q: Can I still see multiple line items for each of my organizations on my detailed Azure bill? answer: | A: Yes. - - All organizations under the same billing Azure subscription are ordered. The ordering is consistent month to month, but it isn't configurable. + - All organizations under the same billing Azure subscription are in order. The ordering is consistent month to month, but it isn't configurable. - The five free Basic users apply to the first organization on the list. Any remaining value carries over to other organizations. - Users get billed in the first organization they're found in and not again in any other organization. - If there are any charges for an organization, then there's a separate line item for that organization on the detailed Azure bill. - question: | - Q: Can I tell what access level a user has assigned in a different organization? + Q: Can I tell what access level a user has in a different organization? answer: | - A: No. User assignments get applied in each organization independently. Administrators can't tell whether a user they're adding already has an access level that's assigned in another organization. + A: No. User assignments apply to each organization independently. Administrators can't tell whether a user they're adding already has an access level assigned in another organization. - question: | Q: What if a user is assigned Basic in one organization and Basic + Test Plans in another? @@ -222,7 +219,7 @@ sections: - question: | Q: Why are extra free user grants removed when multi-organization billing is enabled? answer: | - A: The most common reason customers have received extra free user license grants in the past is because Azure DevOps didn't support multi-organization billing. For that reason, when you enable multi-organization billing, extra free grants are removed. If you have a free grant, [contact our Microsoft Azure support team](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade) to request that the grant applied to your Azure subscription instead. For a free grant example, the [Microsoft Enterprise DevOps Accelerator Offer](https://info.microsoft.com/microsoft-enterprise-devops-accelerator-offer.html). + A: The most common reason customers received extra free user license grants in the past is because Azure DevOps didn't support multi-organization billing. For that reason, when you enable multi-organization billing, extra free grants get removed. If you have a free grant, [contact our Microsoft Azure support team](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade) to request that the grant applied to your Azure subscription instead. ## Understand your bill @@ -267,9 +264,9 @@ sections: - question: | Q: How can I split Azure DevOps charges by organization? answer: | - A: If you work in more than one Azure DevOps organization that's billed to the same Azure subscription, you can separate the charges for each organization. + A: If you work in more than one Azure DevOps organization billed to the same Azure subscription, you can separate the charges for each organization. - To make this split easier, we automatically add the tag `"_organizationname_"` and the name of your Azure DevOps organization associated with the charges. We started emitting this tag in Feb 2020, so you won't see it before that date. See the following two ways you can use this tag to drill into charges for a given organization. + To make this split easier, we automatically add the tag `"_organizationname_"` and the name of your Azure DevOps organization associated with the charges. We started emitting this tag in Feb 2020, so you don't see it before that date. See the following two ways you can use this tag to drill into charges for a given organization. 1. In the Azure portal, select **Subscriptions** > **Cost analysis**. @@ -290,8 +287,13 @@ sections: - question: | Q: Can I move between subscriptions? answer: | - A: No, you can't move the organization resource that appears in the Azure portal between Azure subscriptions via the Azure portal. But you can move it between subscriptions by [changing the subscription](change-azure-subscription.md) your organization uses for billing. + A: No, you can't move the organization resource that appears in the Azure portal between Azure subscriptions via the Azure portal. But you can move it between subscriptions by [changing the subscription](change-azure-subscription.md) your organization uses for billing. When you change the subscription, a new resource group gets created for your organization. You can then safely delete the old resource group. + - question: | + Q: Why don't I see a resource representing my Azure DevOps organization? + answer: | + A: If you [set up billing](set-up-billing-for-your-organization-vs.md#set-up-billing), but don't see your organization represented as an Azure resource, you might have an Azure policy that requires tags on new Resource Groups. Azure DevOps creates a new resource group without tags for the organization resource. Azure DevOps billing works with or without the organization resource. To enable Azure DevOps to create the organization resource, temporarily disable the Azure tag policy before you set up billing. Once the resource gets created, reenable the policy. For more information, see [Assign policy definitions for tag compliance](/azure/azure-resource-manager/management/tag-policies). + - question: | Q: Can I move between resource groups? answer: | @@ -307,29 +309,41 @@ sections: - question: | Q: Why is the location of my organization resource incorrect? answer: | - A: The location of your organization resource could be incorrect for various reasons, such as [changing your organization region](../accounts/change-organization-location.md#change-organization-region). To find the location of your organization, [check the region listed in Azure DevOps](../accounts/change-organization-location.md), which is the source of truth for Azure DevOps locations. If the location listed there doesn't match the location listed inside the Azure portal, you can update the portal by [removing billing](change-azure-subscription.md#remove-your-billing-subscription) from your organization and then [setting it up](set-up-billing-for-your-organization-vs.md) again. + A: The location of your organization resource could be incorrect for various reasons, such as [changing your organization region](../accounts/change-organization-location.md#change-organization-geography). To find the location of your organization, [check the geography listed in Azure DevOps](../accounts/change-organization-location.md), which is the source of truth for Azure DevOps locations. If the location listed there doesn't match the location listed inside the Azure portal, do these steps: + 1. In Azure DevOps Billing settings, [remove your billing subscription](change-azure-subscription.md#remove-your-billing-subscription). + 2. In the Azure portal, delete the Azure DevOps resource group if it's still there. + 3. In Azure DevOps Billing settings, [set up billing for your organization](set-up-billing-for-your-organization-vs.md#set-up-billing). + - question: | Q: Why is the name of my organization resource incorrect? answer: | - A: If you've [renamed your organization](../accounts/rename-organization.md) after you set up billing, then the name of the organization resource is the original name. To change the name of the organization resource to the new name, first [remove billing](change-azure-subscription.md#remove-your-billing-subscription), and then [set up billing](set-up-billing-for-your-organization-vs.md) again. + A: If you have [renamed your organization](../accounts/rename-organization.md) after you set up billing, then the name of the organization resource is the original name. To change the name of the organization resource to the new name, first [remove billing](change-azure-subscription.md#remove-your-billing-subscription), and then [set up billing](set-up-billing-for-your-organization-vs.md#set-up-billing) again. - question: | Q: What happens if I delete my organization resource? answer: | - A: Deleting the organization resource from the Azure portal [removes billing for your organization](change-azure-subscription.md#remove-your-billing-subscription) and your organization returns to its [free limits](billing-faq.yml#q--can-i-use-azure-devops-for-free-). To [delete your Azure DevOps organization](../accounts/delete-your-organization.md) and all the data it contains, you must delete it from within Azure DevOps administration. + A: Deleting the Azure DevOps organization resource in the Azure portal results in an error if it's actively being used for billing. + To delete the organization resource, first change billing to a different Azure subscription in the Azure DevOps organization (Organization settings > Billing > Change billing). For more information, see [Change billing in Azure DevOps](set-up-billing-for-your-organization-vs.md#change-your-billing-subscription). + + :::image type="content" source="media/delete-command-on-one-selected-item.png" alt-text="Screenshot of delete command on one selected item."::: + If the user removing billing has permission on the Azure subscription, the resource in the Azure portal gets removed automatically. If the user removing billing in Azure DevOps doesn't have access to the Azure subscription, the organization resource persists and a user with access to the Azure subscription can safely remove it later without error. + - question: | - Q: Can I use credits from the Azure Sponsorship Offer to pay for Azure DevOps Services? + Q: Can I apply tags to organizations from the Azure portal? answer: | - A: You can try to add the subscription with the Azure Sponsorship Offer and see if the system accepts it. If the subscription has a limit, then you likely can't use it. + A: Yes. Select the Azure subscription linked to the desired Azure DevOps organization, in Settings > Resources. + :::image type="content" source="media/billing-faq/organization-under-subscription.png" alt-text="Screenshot of locating your organization"::: + Select the desired organization from list and apply tags by selecting the action **Assign tags**. The tags you assign appear in your Azure bill for the charges associated with the selected Azure DevOps organization. + :::image type="content" source="media/billing-faq/apply-billing-tag-on-organization.png" alt-text="Screenshot of applying tags"::: - name: How charges get processed questions: - question: | Q: How are user charges and CI/CD concurrent job charges processed? answer: | - A: Charges are metered daily to the Azure subscription you selected when you set up billing. Charges accumulate and are included on the next Azure bill you receive. + A: Charges get calculated daily to the Azure subscription you selected when you set up billing. Charges accumulate and are included on the next Azure bill you receive. - question: | Q: How do reductions or cancellations work? @@ -339,9 +353,9 @@ sections: - name: Changes in Azure subscription status questions: - question: | - Q: What happens if I cancel my Azure subscription or my credit card expires? + Q: What happens if I cancel my Azure subscription, or my credit card expires? answer: | - A: When the Azure subscription used for billing on your organization isn't in active status - for example, because you canceled the subscription, or the credit card used for billing expired - your organization reverts to the [free tier](overview.md#free-tier) of service. To resume access to paid services, [reactivate your subscription](https://learn.microsoft.com/azure/cost-management-billing/manage/subscription-disabled) or [change your organization's billing subscription](change-azure-subscription.md). + A: When the Azure subscription used for billing on your organization isn't in active status - for example, because you canceled the subscription, or the credit card used for billing expired - your organization reverts to the [free tier](overview.md#free-tier) of service. To resume access to paid services, [reactivate your subscription](/azure/cost-management-billing/manage/subscription-disabled) or [change your organization's billing subscription](change-azure-subscription.md). ![Screenshot of invalid Azure billing subscription.](media/billing-faq/azure-subscription-invalid.png) @@ -351,24 +365,19 @@ sections: - question: | Q: Where can I check my bill or update billing details on my Azure subscription? answer: | - A: If you're the owner or contributor for the Azure subscription that's used for billing your organization, you can view your billing details in Azure DevOps **Organization settings** > **Billing** tab. If you're the Azure Account Administrator, go to the [Azure Account portal](https://account.windowsazure.com). + A: If you're the owner or contributor for the Azure subscription used for billing your organization, you can view your billing details in Azure DevOps **Organization settings** > **Billing** tab. If you're the Azure Account Administrator, go to [Cost Management + Billing](https://portal.azure.com/#view/Microsoft_Azure_Billing/BillingMenuBlade/~/Overview). - name: Enterprise Agreement customers questions: - question: | Q: Can I use an Enterprise Agreement to buy Azure DevOps? answer: | - A: Yes, you can. You need to be an owner or contributor for an Azure subscription that was created for your EA. - - - question: | - Q: Can I use an Enterprise Agreement to buy from the Visual Studio Marketplace? - answer: | - A: Yes. Buy directly from the Visual Studio Marketplace, Azure DevOps tab. Bill purchases to the Azure subscription that was created under your [Enterprise Agreement (EA)](https://azure.microsoft.com/pricing/enterprise-agreement/). Don't order Visual Studio Marketplace services through your reseller. - + A: Yes, you can. You need to be an owner or contributor for an Azure subscription created for your EA. + - question: | Q: How can I tell whether I have the necessary privileges to buy services through my organization's Enterprise Agreement? answer: | - A: The easiest approach to determine if you have the right privileges is to select the **Buy** button for a service. Select an Azure subscription, which is a billing account, from a presented list of Azure subscriptions that are linked to your sign-in credentials. Since the name of your Azure subscription defaults to the type of billing account, it's often clear whether the Azure subscription is part of your Enterprise Agreement. For example, subscriptions can be named "Pay-As-You-Go" or "Enterprise Agreement". + A: The easiest approach to determine if you have the right privileges is to [set up billing](/azure/devops/organizations/billing/set-up-billing-for-your-organization-vs) for your organization. Select an Azure subscription, which is a billing account, from a presented list of Azure subscriptions linked to your sign-in credentials. Since the name of your Azure subscription defaults to the type of billing account, it's often clear whether the Azure subscription is part of your Enterprise Agreement. For example, you can name subscriptions, "pay-as-you-go" or "Enterprise Agreement." Another approach is to try to visit the [Azure Enterprise Portal](https://ea.azure.com). If you can reach it successfully, then you already have either the enterprise admin or the organization owner role. Only organization owners can set up new Azure billing in an Enterprise Agreement. @@ -377,27 +386,19 @@ sections: - question: | Q: Can I use the Azure Monetary Commitment funds from my Enterprise Agreement to buy Azure DevOps? answer: | - A: Yes, you can use these prepaid funds for all services that Azure DevOps offers. Make sure to choose an Azure subscription that was created for your EA when you [set up billing for your organization](set-up-billing-for-your-organization-vs.md). + A: Yes, you can use these prepaid funds for all services that Azure DevOps offers. Make sure to choose an Azure subscription that was created for your EA when you [set up billing for your organization](set-up-billing-for-your-organization-vs.md#set-up-billing). - The only exclusion is for extensions offered by partners. These charges appear on your next "overage" invoice. Typically, charges occur monthly, but because of historical rules for some EA customers, an overage invoice might not be issued for several months. Consult a licensing specialist for your EA if you need to know what number of other purchases aren't eligible for Azure Monetary Commitment funds, trigger an overage invoice. - - - question: | - Q: Can I use the Azure Monetary Commitment funds from my Enterprise Agreement to buy from the Visual Studio Marketplace? - answer: | - A: Use the [Azure Prepayment](/marketplace/azure-consumption-commitment-benefit) (previously called monetary commitment) funds from your Enterprise Agreement to pay for the following items: [Azure DevOps users](buy-basic-access-add-users.md), and [Microsoft-published extensions for Azure DevOps](https://marketplace.visualstudio.com/azuredevops). You can't use these funds to pay for Visual Studio cloud subscriptions and non-Microsoft extensions for Azure DevOps. - - - name: Other questions questions: - question: | Q: Why don't I see Team Projects in the Azure portal? answer: | - A: You can't create Team Projects or view them in the Azure portal as of September 28, 2018. You can continue to **access** any Team Projects you create via the Azure portal through your organization URL (`https://dev.azure.com/{your_organization}`). You can always [create new organizations and projects from visualstudio.com](https://app.vsaex.visualstudio.com/me?mkt=en-US&campaign=o~msft~vscom~vssignin). The best way for Azure users to get started using Azure DevOps is to [create a project](https://azure.microsoft.com/features/devops-projects/). + A: You can't create Team Projects or view them in the Azure portal as of September 28, 2018. You can continue to **access** any Team Projects you create via the Azure portal through your organization URL (`https://dev.azure.com/{Your_Organization}`). You can always [create new organizations and projects from visualstudio.com](https://app.vsaex.visualstudio.com/me?mkt=en-US&campaign=o~msft~vscom~vssignin). The best way for Azure users to get started using Azure DevOps is to [create a project](https://azure.microsoft.com/features/devops-projects/). - question: | Q: Why is my organization already linked to an Azure subscription? answer: | - A: Someone already [set up billing](set-up-billing-for-your-organization-vs.md) for your organization. Each organization can use only one Azure subscription for billing. You can't split across multiple Azure subscriptions. + A: Someone already [set up billing](set-up-billing-for-your-organization-vs.md#set-up-billing) for your organization. Each organization can use only one Azure subscription for billing. You can't split across multiple Azure subscriptions. - question: | Q: Can I use the same Azure subscription for billing across multiple organizations? @@ -419,10 +420,7 @@ sections: additionalContent: | - ## Related articles - - * [Set up billing](set-up-billing-for-your-organization-vs.md) - * [Add backup billing managers](add-backup-billing-managers.md) - * [Change the Azure subscription for billing](change-azure-subscription.md) + ## Related articles + * [Azure DevOps pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) * [Azure DevOps billing support](https://azure.microsoft.com/support/devops/) diff --git a/docs/organizations/billing/buy-access-tfs-test-hub.md b/docs/organizations/billing/buy-access-tfs-test-hub.md index d3a5417c7d5..de2794b6191 100644 --- a/docs/organizations/billing/buy-access-tfs-test-hub.md +++ b/docs/organizations/billing/buy-access-tfs-test-hub.md @@ -1,27 +1,30 @@ --- title: Buy access to Azure Test Plans titleSuffix: Azure DevOps Server -ms.custom: seodec18, freshness-fy22q1, engagement-fy23 -description: Steps for how to buy monthly access to Azure Test Plans. +ms.custom: freshness-fy22q1, engagement-fy23 +description: Steps for how to buy monthly access to Azure Test Plans. ms.subservice: azure-devops-billing ms.assetid: B6BED64A-DA53-4AB0-B200-85F86A869D7B ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 12/13/2022 +ms.date: 03/05/2025 monikerRange: '< azure-devops' --- + # Buy access to Azure Test Plans [!INCLUDE [version-lt-azure-devops](../../includes/version-lt-azure-devops.md)] - For [Azure DevOps Server](https://visualstudio.microsoft.com/tfs/), you pay per user for [Basic](https://visualstudio.microsoft.com/team-services/compare-features/) features. Users with [Visual Studio subscriptions](https://visualstudio.microsoft.com/vs/pricing/) are free to add because Basic features are included in their subscription as a benefit. It's also free to add users with [Stakeholder access](../../organizations/security/get-started-stakeholder.md), which provides free access to a limited set of features. + For [Azure DevOps Server](https://visualstudio.microsoft.com/tfs/), you pay per user for Basic features. Users with [Visual Studio subscriptions](https://visualstudio.microsoft.com/vs/pricing/) are free to add because Basic features are included in their subscription as a benefit. It's also free to add users with [Stakeholder access](../../organizations/security/get-started-stakeholder.md), which provides free access to a limited set of features. -[Buy monthly access](buy-basic-access-add-users.md), rather than a Visual Studio subscription or [Azure DevOps Server Client Access License (CAL)](../../user-guide/about-azure-devops-services-tfs.md). With paid monthly access, users have access to both Azure DevOps Services and Azure DevOps Server. Users aren't required to use Azure DevOps Services, though. +[Buy monthly access](buy-basic-access-add-users.md), rather than a Visual Studio subscription or [Azure DevOps Server Client Access License (CAL)](../../user-guide/about-azure-devops-services-tfs.md). With paid monthly access, users have access to both Azure DevOps Services and Azure DevOps Server. Users aren't required to use Azure DevOps Services, though. For more information about access levels, see [Change access levels](../security/change-access-levels.md). ## Prerequisites -You must be a member of the Team Foundation Administrators group. The user who installed Azure DevOps Server gets automatically added to this group. For more information, see [Add or remove a team administrator](../settings/add-team-administrator.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the **Team Foundation Administrators** group. The user who installed Azure DevOps Server gets automatically added to this group. For more information, see [Add or remove a team administrator](../settings/add-team-administrator.md).| For more information about the requirements to access Azure Test Plans, see [Change access levels](../../organizations/security/change-access-levels.md). For more information about licensing, see the [pricing page](https://visualstudio.microsoft.com/team-services/tfs-pricing). To configure costs for Azure DevOps, see the [pricing calculator](https://azure.microsoft.com/pricing/calculator/?service=azure-devops). @@ -33,21 +36,17 @@ For more information about the requirements to access Azure Test Plans, see [Cha 2. Based on your total entitlements, pay for Basic users in your organization. - Free users can't access Azure DevOps Server. So, add five Basic users who won't use your server, to ensure everyone else has paid monthly access. + Free users can't access Azure DevOps Server. So, add five Basic users who don't use your server to ensure everyone else gets paid monthly access. Users get invited to your organization, but aren't required to use Azure DevOps. 3. As the Azure DevOps Server Administrator, [add these same users to Azure DevOps Server](../../organizations/security/add-users-team-project.md#add-users-team-project). 4. [Assign access levels for users](../../organizations/security/change-access-levels.md). - > [!NOTE] - > Azure DevOps Server doesn't detect what happens in Azure DevOps Services. Add these users to Azure DevOps Server and assign them the Basic access level. - > If you stop paying for these users within your organization, your administrator should remove them from Azure DevOps Server or buy them an Azure DevOps Server CAL. +::: moniker range=" < azure-devops > azure-devops-2020" ## Buy monthly access to Test Plans -::: moniker range="= azure-devops-2019 || azure-devops-2020" - 1. [Create an organization](../accounts/create-organization.md), if you don't have one already. 2. Based on the number of users who need Azure Test Plans access in Azure DevOps Server, [pay for Basic + Test Plan users](buy-basic-access-add-users.md#assign-basic-or-basic--test-plans) in your organization. @@ -61,45 +60,18 @@ For more information about the requirements to access Azure Test Plans, see [Cha Test Plans installs automatically in Azure DevOps Server. +> [!NOTE] +> **Benefits of paying for Azure DevOps Server users via Basic + Test Plans in Azure DevOps Services:** +> - Users can access both Azure DevOps Server and Azure DevOps Services for the same price. +> - Pay monthly for users who need temporary access. +> - Utilize all Azure purchasing options, including credit card, Cloud Solution Provider (CSP) partner, Enterprise Agreement, and more. +> +> **Important considerations:** +> - Azure DevOps Server doesn't detect activities in Azure DevOps Services. +> - Add these users to Azure DevOps Server and assign them the Basic access level. +> - If you stop paying for these users, your administrator should remove them from Azure DevOps Server or buy them an Azure DevOps Server CAL. ::: moniker-end -::: moniker range="tfs-2018" - -1. [Create an organization](../accounts/create-organization.md), if you don't have one already. - -2. Based on the number of users who need Azure Test Plans access in Azure DevOps Server, [buy paid access](buy-basic-access-add-users.md). - - Test Plans installs automatically in Azure DevOps Server. - -3. [Add users](../accounts/add-organization-users.md) to your organization. Assign them Basic + Test Plans access so you can track them. - -4. As the Azure DevOps Server administrator, [add these same users](../../organizations/security/add-users-team-project.md#add-users-team-project). [Give them Advanced access](../../organizations/security/change-access-levels.md) so they can use Azure Test Plans. - - > [!NOTE] - > Azure DevOps Server doesn't detect what happens in Azure DevOps Services. - > - > If you stop paying for these users, your administrator should remove those users from Azure DevOps Server. - -::: moniker-end - -## FAQs - - - -### Q: Why should I pay via Azure DevOps Services for my Azure DevOps Server users? - -A: You get the following benefits paying via Azure DevOps Services: - -- Users have the flexibility to access both Azure DevOps Server and Azure DevOps Services for the same price. -- You can pay monthly for users who need temporary access. -- You get all the purchasing capabilities that Azure offers like payment via credit card, through a Cloud Solution Provider (CSP) partner, through the Enterprise Agreement, and more. - -### Q: Where can I learn more about access levels for Azure Test Plans? - -A: See [Change access levels](../security/change-access-levels.md). - - - ## Next steps > [!div class="nextstepaction"] @@ -110,4 +82,4 @@ A: See [Change access levels](../security/change-access-levels.md). - [Buy Basic access for users](buy-basic-access-add-users.md) - [Sign up for Azure Artifacts](../../artifacts/start-using-azure-artifacts.md) - [Change your subscription for billing](change-azure-subscription.md) -- [Learn about Azure cost management and billing](/azure/cost-management-billing/cost-management-billing-overview) +- [Learn about Microsoft Cost Management and billing](/azure/cost-management-billing/cost-management-billing-overview) diff --git a/docs/organizations/billing/buy-basic-access-add-users.md b/docs/organizations/billing/buy-basic-access-add-users.md index 73df9bfea65..9d8df5c3573 100644 --- a/docs/organizations/billing/buy-basic-access-add-users.md +++ b/docs/organizations/billing/buy-basic-access-add-users.md @@ -1,14 +1,14 @@ --- title: Manage paid access for users titleSuffix: Azure DevOps -ms.custom: seodec18, freshness-fy22q1, engagement-fy23 +ms.custom: freshness-fy22q1, engagement-fy23 description: Assign paid access and control the default access of your new users in Azure DevOps. ms.subservice: azure-devops-billing ms.assetid: 02cb8774-6d1d-4f15-8818-b56541033b1f ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 01/05/2023 +ms.date: 03/05/2025 monikerRange: '<= azure-devops' --- @@ -24,35 +24,31 @@ Visual Studio subscribers get access included with their subscription, and their [!INCLUDE [pricing-calculator-tip](../../includes/pricing-calculator-tip.md)] -::: moniker range=" < azure-devops" +::: moniker range=" azure-devops" ## Prerequisites Ensure you have the following items in place: -* You must have [licensing set up for your organization via Azure](https://azure.microsoft.com/pricing/details/devops/server/) -* You must be a member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. - -## Pay via Azure - -Complete the following steps to pay via Azure. - -1. [Create an Azure DevOps organization](../accounts/create-organization.md), even if you don't intend to use it. -2. [Set up billing](set-up-billing-for-your-organization-vs.md) using an Azure subscription and add users or buy CI/CD. -3. Assign licenses to users. - -You're entitled to the same number of user licenses to be used in the server. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. | +|**Billing**| [Billing is set up](set-up-billing-for-your-organization-vs.md#set-up-billing) for your organization.| ::: moniker-end -::: moniker range="azure-devops" +::: moniker range=" < azure-devops" ## Prerequisites -Ensure you have the following items in place: +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. | +|**Licensing**| [Licensing set up for your organization via Azure](https://azure.microsoft.com/pricing/details/devops/server/)| -* [Billing is set up](set-up-billing-for-your-organization-vs.md) for your organization -* You have permissions allocated as [an organization Owner](../security/look-up-organization-owner.md) or [a member of the Project Collection Administrators group](../security/look-up-project-collection-administrators.md) +::: moniker-end + +::: moniker range=" azure-devops" @@ -62,10 +58,11 @@ The easiest way to control paid access is to manually assign an access level. Yo Keep the following information in mind: -- **Visual Studio subscribers** get detected automatically when they sign in. There's no extra charge for users with a Visual Studio subscription. -- **Stakeholder** is a [free access level with limited functionality](../security/get-started-stakeholder.md). -- **Basic** is free for the first 5 users, and paid for 6 or more users. -- **Basic + Test Plans** is paid only, but is [free to try for 30 days](try-additional-features-vs.md). +- **Visual Studio** subscribers get detected automatically when they sign in. There's no extra charge for users with a Visual Studio subscription. +- **GitHub Enterprise** users get detected automatically when they sign in. There's no extra charge for users with a GitHub Enterprise license. +- **Stakeholder** access is a [free access level with limited functionality](../security/get-started-stakeholder.md). +- **Basic** access is free for the first 5 users and paid for 6 or more users. +- **Basic + Test Plans** access is paid only, but [free to try for 30 days](try-additional-features-vs.md). ## Select default access level for new users @@ -73,7 +70,7 @@ All new users get the free Stakeholder access if they're added directly to a pro To change the access level for new users added to projects, do the following steps: -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. @@ -92,7 +89,7 @@ To change the access level for new users added to projects, do the following ste Group rules provide a great way to automate access level assignment for your organization. This way, you don't have to manually assign access each time a user gets added or removed. For more information, see [Group rules](../accounts/assign-access-levels-by-group-membership.md). > [!NOTE] -> A group rule supersedes the default access level. For instance, if a user's part of a group that's assigned Basic access level, they get Basic, even if the default access level's set to Stakeholder. The default access level applies to users who aren't part of any group rules. +> A group rule supersedes the default access level. For instance, if a user's part of a group assigned the **Basic** access level, they get **Basic** access, even if the default access is set to Stakeholder. The default access level applies to users who aren't part of any group rules. ## Reduce charges for users with no access @@ -110,17 +107,17 @@ To find out if you have users who are no longer using Azure DevOps, do the follo :::image type="content" source="media/shared/last-access.png" alt-text="Screenshot showing select Users and then sort by Last Access."::: -4. If there are users who have never signed in, you can find out how recently they were added by exporting the list of users and checking the **Date Created** column. +4. If there are users who haven't signed in, you can find out how recently they were added by exporting the list of users and checking the **Date Created** column. :::image type="content" source="media/shared/export-users.png" alt-text="Screenshot showing Export users."::: ## Pay for a user once across multiple organizations -If you're a member of more than one Azure DevOps organization, you can turn on multi-organization billing and pay for each **Basic** or **Basic + Test Plans** human user once, for all organizations under the same billing Azure subscription. This does not apply to [service principals](../../integrate/get-started/authentication/service-principal-managed-identity.md), which you must pay for each organization the service principal has been added to where the service principal has **Basic** or **Basic + Test Plans**. +If you're a member of more than one Azure DevOps organization, you can turn on multi-organization billing and pay for each **Basic** or **Basic + Test Plans** human user once, for all organizations under the same billing Azure subscription. Multi-organization billing doesn't apply to [service principals](../../integrate/get-started/authentication/service-principal-managed-identity.md), which you must pay for each organization the service principal was added to where the service principal has **Basic** or **Basic + Test Plans**. -For more information, see [multi-organization billing FAQs](./billing-faq.yml). Complete the following steps. +For more information, see [multi-organization billing FAQs](./billing-faq.yml). To pay for a user once across multiple organizations, do the following steps: -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. @@ -134,12 +131,26 @@ For more information, see [multi-organization billing FAQs](./billing-faq.yml). ![Screenshot showing selected button, Configure user billing.](media/buy-more-basic-access/select-configure-user-billing.png) -5. Select **Multi-organization**, and then select **Save**. +5. Select **Multi-organization** > **Save**. ![Screenshot showing selected Multi-organization in Configure user billing screen.](media/buy-more-basic-access/select-multi-organization-billing.png) ::: moniker-end +::: moniker range=" < azure-devops" + +## Pay via Azure + +To pay via Azure, do the following steps: + +1. [Create an Azure DevOps organization](../accounts/create-organization.md), even if you don't intend to use it. +2. [Set up billing](set-up-billing-for-your-organization-vs.md#set-up-billing) using an Azure subscription and add users or buy CI/CD. +3. Assign licenses to users. + +You're entitled to the same number of user licenses to be used in the server. + +::: moniker-end + ## Next steps > [!div class="nextstepaction"] @@ -147,7 +158,7 @@ For more information, see [multi-organization billing FAQs](./billing-faq.yml). ## Related articles -* [Set up billing](set-up-billing-for-your-organization-vs.md) +* [Set up billing](set-up-billing-for-your-organization-vs.md#set-up-billing) * [Change your Azure subscription for billing](change-azure-subscription.md) * [Learn about Azure DevOps pricing](https://azure.microsoft.com/pricing/details/visual-studio-team-services/) * [Get Azure DevOps billing support](https://azure.microsoft.com/support/devops/) diff --git a/docs/organizations/billing/change-azure-subscription.md b/docs/organizations/billing/change-azure-subscription.md deleted file mode 100644 index 05cb7cbea1d..00000000000 --- a/docs/organizations/billing/change-azure-subscription.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Change Azure subscription used for billing -titleSuffix: Azure DevOps Services -ms.custom: seodec18, contperf-fy21q1, freshness-fy22q1, contperf-fy22q3, engagement-fy23 -description: Unlink the Azure subscription that your organization uses for billing, link to a different one, and go back to free limits immediately. -ms.subservice: azure-devops-billing -ms.assetid: e447adb1-6208-49f6-a488-515aa4b2fdcf -ms.topic: how-to -ms.author: chcomley -author: chcomley -monikerRange: 'azure-devops' -ms.date: 01/05/2023 ---- - -# Change your organization's billing subscription - -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -Learn how to change the Azure subscription that your Azure DevOps organization uses for billing. You might do so if your organization is tied to a subscription of a user who's left the organization. In this case, you'd likely switch to a common subscription or remove the billing. You can [remove your billing subscription](#remove-your-billing-subscription) at any time. - -See also the following related articles: -- [Pay for users](buy-basic-access-add-users.md) -- [Buy access to Azure Test Plans](buy-access-tfs-test-hub.md) -- [Buy parallel jobs](../../pipelines/licensing/concurrent-jobs.md#how-much-do-parallel-jobs-cost) -- [Sign up for Azure Artifacts](../../artifacts/start-using-azure-artifacts.md) -- [Try Azure Test Plans](try-additional-features-vs.md) - -[!INCLUDE [pricing-calculator-tip](../../includes/pricing-calculator-tip.md)] - -## Prerequisites - -Have the following permissions to change your organization's billing subscription: - -- [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. -- [Owner or Contributor permission for the Azure subscription](add-backup-billing-managers.md), which you can use to purchase. - - - -## Change your billing subscription - -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). - -2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - - :::image type="content" source="../../media/settings/open-admin-settings-vert.png" alt-text="Screenshot showing highlighted Organization settings button."::: - -3. Select **Billing** > **Change billing**. If you don't see the **Change billing** button, you don't have the [right permissions for access](#prerequisites). - - :::image type="content" source="media/shared/select-change-billing.png" alt-text="Screenshot showing highlighted Billing and Change billing buttons."::: - -4. Choose your Azure subscription, and then select **Save**. - - :::image type="content" source="media/shared/select-azure-subscription.png" alt-text="Screenshot showing Azure subscription selection."::: - -Azure DevOps bills the newly saved subscription for your organization. - -## Remove your billing subscription - -> [!IMPORTANT] -> When you remove the billing subscription from your organization, any paid quantities of Basic, Azure Artifacts users, Azure Test Plans users, Microsoft-hosted CI/CD, and self-hosted CI/CD go back to the [free tier](billing-faq.yml) of service immediately. -> ->If you delete your organization resource in the Azure Portal, do so *after* you change the billing subscription in Azure DevOps and not before, to avoid your organization reverting to the free tier of service. - -1. Sign in to your organization, choose ![gear icon](../../media/icons/gear-icon.png) **Organization settings** > **Billing**, and then **Change billing**, following steps 1 through 4 provided in the [Change the subscription](#change-subscription) section. - -2. Choose **Remove billing**, and then choose **Save**. - -Azure DevOps removes your billing subscription from your organization. - -## Next steps - -> [!div class="nextstepaction"] -> [Pay for users](buy-basic-access-add-users.md) - -## Related articles - -* [Add a backup billing manager](add-backup-billing-managers.md) -* [Pay for Basic + Test Plans](buy-basic-access-add-users.md) -* [Pay for Azure Pipelines](../../pipelines/licensing/concurrent-jobs.md#how-much-do-parallel-jobs-cost) -* [Set up billing](set-up-billing-for-your-organization-vs.md) -* [Change the Azure subscription used for billing](change-azure-subscription.md) -* [Get Azure DevOps billing support](https://azure.microsoft.com/support/devops/) diff --git a/docs/organizations/billing/csp/buy-csp-azure-devops.md b/docs/organizations/billing/csp/buy-csp-azure-devops.md index 86b6a626395..2efc15756f7 100644 --- a/docs/organizations/billing/csp/buy-csp-azure-devops.md +++ b/docs/organizations/billing/csp/buy-csp-azure-devops.md @@ -22,9 +22,9 @@ If you're a partner in the Cloud Solution Provider (CSP) program, you can enable Before you enable your customer to purchase Azure DevOps by using a CSP-based Azure subscription, confirm the following statements are true: - The customer is a member of the [**Project Collection Administrators** group](../../security/look-up-project-collection-administrators.md) or the [**organization Owner**](../../security/look-up-organization-owner.md). -- The customer has [Contributor or Owner role permissions](../add-backup-billing-managers.md) to the CSP-based Azure subscription. +- The customer has [Contributor or Owner role permissions](../set-up-billing-for-your-organization-vs.md#give-a-user-access-to-manage-billing) to the CSP-based Azure subscription. -When your customer gains access to the CSP-based Azure subscription, they can [set up billing,](../set-up-billing-for-your-organization-vs.md) or [change billing](../change-azure-subscription.md) for their Azure DevOps organization. Any further charges are applied to your CSP subscription. +When your customer gains access to the CSP-based Azure subscription, they can [manage billing](../set-up-billing-for-your-organization-vs.md) for their Azure DevOps organization. Any further charges are applied to your CSP subscription. ## Change billing to CSP Azure subscription diff --git a/docs/organizations/billing/media/add-backup-billing-manager/add-co-administrator-to-subscription.png b/docs/organizations/billing/media/add-backup-billing-manager/add-co-administrator-to-subscription.png new file mode 100644 index 00000000000..5a0f5cce13d Binary files /dev/null and b/docs/organizations/billing/media/add-backup-billing-manager/add-co-administrator-to-subscription.png differ diff --git a/docs/organizations/billing/media/add-backup-billing-manager/add-role-assignment.png b/docs/organizations/billing/media/add-backup-billing-manager/add-role-assignment.png index 3e94dfe6027..fa71ed11446 100644 Binary files a/docs/organizations/billing/media/add-backup-billing-manager/add-role-assignment.png and b/docs/organizations/billing/media/add-backup-billing-manager/add-role-assignment.png differ diff --git a/docs/organizations/billing/media/add-backup-billing-manager/add-role-to-subscription.png b/docs/organizations/billing/media/add-backup-billing-manager/add-role-to-subscription.png new file mode 100644 index 00000000000..5bfcd2c9b77 Binary files /dev/null and b/docs/organizations/billing/media/add-backup-billing-manager/add-role-to-subscription.png differ diff --git a/docs/organizations/billing/media/add-backup-billing-manager/choose-access-control.png b/docs/organizations/billing/media/add-backup-billing-manager/choose-access-control.png deleted file mode 100644 index f5c12e6f71b..00000000000 Binary files a/docs/organizations/billing/media/add-backup-billing-manager/choose-access-control.png and /dev/null differ diff --git a/docs/organizations/billing/media/add-backup-billing-manager/choose-role-and-select-an-assignment-type.png b/docs/organizations/billing/media/add-backup-billing-manager/choose-role-and-select-an-assignment-type.png deleted file mode 100644 index 9b792ed7b80..00000000000 Binary files a/docs/organizations/billing/media/add-backup-billing-manager/choose-role-and-select-an-assignment-type.png and /dev/null differ diff --git a/docs/organizations/billing/media/add-backup-billing-manager/choose-subscription-to-modify.png b/docs/organizations/billing/media/add-backup-billing-manager/choose-subscription-to-modify.png deleted file mode 100644 index f436d5ff274..00000000000 Binary files a/docs/organizations/billing/media/add-backup-billing-manager/choose-subscription-to-modify.png and /dev/null differ diff --git a/docs/organizations/billing/media/add-backup-billing-manager/select-user-add.png b/docs/organizations/billing/media/add-backup-billing-manager/select-user-add.png new file mode 100644 index 00000000000..e085b6dea45 Binary files /dev/null and b/docs/organizations/billing/media/add-backup-billing-manager/select-user-add.png differ diff --git a/docs/organizations/billing/media/delete-command-on-one-selected-item.png b/docs/organizations/billing/media/delete-command-on-one-selected-item.png new file mode 100644 index 00000000000..d7ccf12d94a Binary files /dev/null and b/docs/organizations/billing/media/delete-command-on-one-selected-item.png differ diff --git a/docs/organizations/billing/media/shared/last-access.png b/docs/organizations/billing/media/shared/last-access.png index 722fe03ffd3..140d931bef6 100644 Binary files a/docs/organizations/billing/media/shared/last-access.png and b/docs/organizations/billing/media/shared/last-access.png differ diff --git a/docs/organizations/billing/media/shared/pipelines-parallel-jobs.png b/docs/organizations/billing/media/shared/pipelines-parallel-jobs.png deleted file mode 100644 index 15ea20639fa..00000000000 Binary files a/docs/organizations/billing/media/shared/pipelines-parallel-jobs.png and /dev/null differ diff --git a/docs/organizations/billing/media/shared/select-azure-subscription.png b/docs/organizations/billing/media/shared/select-azure-subscription.png index fe8f0fd114e..48d57445785 100644 Binary files a/docs/organizations/billing/media/shared/select-azure-subscription.png and b/docs/organizations/billing/media/shared/select-azure-subscription.png differ diff --git a/docs/organizations/billing/media/shared/select-billing-organization-settings.png b/docs/organizations/billing/media/shared/select-billing-organization-settings.png index 24c81514237..15b60c468f7 100644 Binary files a/docs/organizations/billing/media/shared/select-billing-organization-settings.png and b/docs/organizations/billing/media/shared/select-billing-organization-settings.png differ diff --git a/docs/organizations/billing/media/shared/select-change-billing.png b/docs/organizations/billing/media/shared/select-change-billing.png index 10e8b97f55a..c7a82edac8d 100644 Binary files a/docs/organizations/billing/media/shared/select-change-billing.png and b/docs/organizations/billing/media/shared/select-change-billing.png differ diff --git a/docs/organizations/billing/overview.md b/docs/organizations/billing/overview.md index f45977822bc..d49ffab9fcc 100644 --- a/docs/organizations/billing/overview.md +++ b/docs/organizations/billing/overview.md @@ -1,14 +1,14 @@ --- title: Billing overview -titleSuffix: Azure DevOps -ms.custom: seodec18, freshness-fy22q1, contperf-fy22q3, engagement-fy23 +titleSuffix: Azure DevOps +ms.custom: freshness-fy22q1, engagement-fy23 description: Understand billing management tasks, including how to set up billing, make purchases, and change the Azure subscription for billing. ms.subservice: azure-devops-billing ms.assetid: d5bd13e2-aa7c-4191-aefd-bd9f05663e7b ms.topic: overview ms.author: chcomley author: chcomley -ms.date: 12/13/2022 +ms.date: 03/05/2025 monikerRange: '<= azure-devops' --- @@ -16,29 +16,17 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -If you need more than the *free tier* of resources in your organization, you can [set up billing](set-up-billing-for-your-organization-vs.md). When you set up billing you can also buy other features offered by Microsoft or other companies. - -## Free tier - -The *free tier* includes the following aspects: - -[!INCLUDE [free-tier](../../includes/free-tier.md)] - -::: moniker range="azure-devops" - -All charges appear on your monthly Azure bill. Azure supports payment by credit card and invoiced billing through the Enterprise Agreement (EA), Cloud Solution Providers (CSP), and more. - -::: moniker-end +If you need more than the [free tier](#free-tier) of resources in your organization, [set up billing](set-up-billing-for-your-organization-vs.md#set-up-billing). When you set up billing you can buy other features offered by Microsoft or other companies. ## Services billed via Azure -During your first purchase for your organization, you're prompted to select the Azure subscription to use for billing. The subscription can be part of your Enterprise Agreement, Pay-As-You-Go, Cloud Solution Provider (CSP), or other types of Azure subscriptions. All services get billed via Azure. You aren't required to pay for or use any other Azure services. +During your first purchase for your organization, you're prompted to select the Azure subscription to use for billing. The subscription can be part of your Enterprise Agreement, pay-as-you-go, Cloud Solution Provider (CSP), or other types of Azure subscriptions. All services get billed via Azure. You aren't required to pay for or use any other Azure services. ::: moniker range=" azure-devops" [!INCLUDE [pricing-calculator-tip](../../includes/pricing-calculator-tip.md)] ::: moniker-end -See the following articles for information about the paid services offered by Microsoft: +For more information, see the following articles about the paid services offered by Microsoft: ::: moniker range="< azure-devops" * [Buy CALs or access to Test Services](buy-access-tfs-test-hub.md) @@ -51,14 +39,25 @@ See the following articles for information about the paid services offered by Mi [!INCLUDE [loadtest-deprecated-include](../../test/includes/loadtest-deprecated-include.md)] +## Free tier + +The *free tier* includes the following aspects: + +[!INCLUDE [free-tier](../../includes/free-tier.md)] + +::: moniker range="azure-devops" + +All charges appear on your monthly Azure bill. Azure supports payment by credit card and invoiced billing through the Enterprise Agreement (EA), Cloud Solution Providers (CSP), and more. + +::: moniker-end + ## Next steps > [!div class="nextstepaction"] -> [Set up billing](set-up-billing-for-your-organization-vs.md) +> [Set up billing](set-up-billing-for-your-organization-vs.md#set-up-billing) ## Related articles - [Change the Azure subscription for billing](change-azure-subscription.md) -- [Add user who can make purchases or backup billing manager](add-backup-billing-managers.md) - [Marketplace & Extensibility](../../marketplace-extensibility/index.yml) - [Buy Visual Studio cloud subscriptions](/visualstudio/subscriptions/vscloud-overview) diff --git a/docs/organizations/billing/set-up-billing-for-your-organization-vs.md b/docs/organizations/billing/set-up-billing-for-your-organization-vs.md index a079aebae8c..4bf57a09441 100644 --- a/docs/organizations/billing/set-up-billing-for-your-organization-vs.md +++ b/docs/organizations/billing/set-up-billing-for-your-organization-vs.md @@ -1,57 +1,135 @@ --- -title: Set up billing for your organization +title: Manage billing for your organization titleSuffix: Azure DevOps Services -ms.custom: seodec18, contperf-fy20q4, contperf-fy21q1, freshness-fy22q1, contperf-fy22q3, engagement-fy23 +ms.custom: freshness-fy22q1, engagement-fy23 description: Use an Azure subscription to configure billing and pay for users, CI/CD concurrency, and extensions for Azure DevOps. ms.subservice: azure-devops-billing ms.assetid: 87b994d6-2a92-46e5-b667-afe4eb198e25 ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 01/05/2023 +ms.date: 04/07/2025 monikerRange: 'azure-devops' --- -# Set up billing +# Manage billing [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Set up billing in Azure DevOps before you make purchases, so it's already in place once you're ready to buy. You only need to set up billing once for your organization. Once you select an Azure subscription for billing, you can purchase more user licenses by adding the user to the organization and assigning them a license. +Setting up billing in Azure DevOps is essential for managing costs associated with users, CI/CD concurrency, and extensions. This article guides you through the process to [set up billing](#set-up-billing-for-your-organization), [change your Azure subscription](#change-your-billing-subscription), [remove your billing subscription](#remove-your-billing-subscription), and [give a user access to manage billing](#give-a-user-access-to-manage-billing). *All services are billed via Azure*. You're not required to use any other Azure services. -[!INCLUDE [pricing-calculator-tip](../../includes/pricing-calculator-tip.md)] +> [!IMPORTANT] +> - When you remove the billing subscription from your organization, any paid quantities for the following types of users go back to the [free tier](billing-faq.yml) of service immediately: +> - Basic +> - Azure Artifacts +> - Azure Test Plans +> - Microsoft-hosted CI/CD +> - Self-hosted CI/CD +> - Before you delete your organization resource in the Azure portal, ensure you changed the billing subscription. Deleting the resource before this change might result in reverting to the free tier of service for your organization. For more information, see [Billing FAQs](billing-faq.yml#azure-portal-integration). +> - When billing gets canceled or changed, a resource group gets left behind in the old Azure subscription. Despite Azure's warning that "Dependent resources will be deleted," it's safe to delete these resource groups. The Azure DevOps organization won't be deleted or harmed. These resource groups take the naming format, `VisualStudioOnline-`. ## Prerequisites -* If you don't have an Azure subscription, [create one](https://azure.microsoft.com/pricing/purchase-options/) now. -* You must be a member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.
      - To give another user access to manage billing: [Azure Account Administrator](/azure/cost-management-billing/manage/add-change-subscription-administrator).
      - To change your organization's billing subscription:
      - [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.
      - [Owner or Contributor permission for the Azure subscription](set-up-billing-for-your-organization-vs.md#give-a-user-access-to-manage-billing), which you can use to purchase. | +|**Subscription**| An [Azure subscription](https://azure.microsoft.com/pricing/purchase-options/).| > [!NOTE] > Azure DevOps doesn't support the [Azure Free Trial](https://azure.microsoft.com/offers/ms-azr-0044p/). +       + ## Set up billing for your organization -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +Set up billing in Azure DevOps before making any purchases. This is a one-time setup per organization. Once you select an Azure subscription for billing, you can add users and assign licenses. + +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) - + 3. Select **Billing**. - ![Screenshot showing highlighted Billing selection in Organization settings.](media/shared/select-billing-organization-settings.png) - + ![Screenshot showing highlighted Billing selection in Organization settings.](media/shared/select-billing-organization-settings.png) + 4. Select **Set up billing**. ![Select Set up billing](media/shared/set-up-billing.png) - + 5. Select your Azure subscription, and then select **Save**. ![Select your Azure subscription](media/shared/select-azure-subscription.png) + +> [!TIP] +> If your desired Azure Subscription doesn't display, it’s likely because the Azure subscription you’re trying to use is tied to a different Microsoft Entra ID tenant than the one you use to access your Azure DevOps organization. Do the following steps to ensure this Azure Subscription shows when you're configuring billing: +> 1. Go directly to your profile (`https://aex.dev.azure.com/`). +> 2. From the dropdown menu, select the Microsoft Entra ID tenant tied to the Azure Subscription you want to use for billing. +> 3. Sign in to your organization (`https://dev.azure.com/{Your_Organization}`). +> 4. Select **Organization settings** > **Billing**> **Set up billing**. The subscription should display. Billing is set up for your Azure DevOps organization. You can [review your individual Azure subscription bill](/azure/cost-management-billing/understand/review-individual-bill) at any time. + + +## Change your billing subscription + +You might need to change the Azure subscription for your Azure DevOps organization's billing if the subscription is linked to a former user. Consider switching to a shared subscription or removing the billing arrangement. You can [remove your billing subscription](#remove-your-billing-subscription) anytime. [Migrating between resource groups isn't supported](billing-faq.yml). + +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). + +2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. + + :::image type="content" source="../../media/settings/open-admin-settings-vert.png" alt-text="Screenshot showing highlighted Organization settings button."::: + +3. Select **Billing** > **Change billing**. If you don't see the **Change billing** button, you don't have the [right permissions for access](#prerequisites). + + :::image type="content" source="media/shared/select-change-billing.png" alt-text="Screenshot showing highlighted Billing and Change billing buttons."::: + +4. Choose your Azure subscription, and then select **Save**. + + :::image type="content" source="media/shared/select-azure-subscription.png" alt-text="Screenshot showing Azure subscription selection."::: + +Azure DevOps bills the newly saved subscription for your organization. + +## Remove your billing subscription + +1. Sign in to your organization, choose ![gear icon](../../media/icons/gear-icon.png) **Organization settings** > **Billing** > **Change billing**, and do steps 1 through 4 of the [Change the subscription](#change-subscription) section. + +2. Select **Remove billing** > **Save**. + +Azure DevOps removes your billing subscription from your organization. + + + +## Give a user access to manage billing + +> [!IMPORTANT] +> Classic admins retired August 31, 2024. You can't add a new coadministrator using the Access control. Remove coadministrators and use Azure role-based access control (RBAC) for fine-grained access control. For more information, see [Azure classic subscription administrators](/azure/role-based-access-control/classic-administrators). + +Assign any of the following roles to a user under the subscription your organization uses for billing: [Owner](/azure/role-based-access-control/built-in-roles#owner), [Contributor](/azure/role-based-access-control/built-in-roles#contributor), or [Service admin](/azure/billing/billing-add-change-azure-subscription-administrator). For more information, see [Azure roles](/azure/role-based-access-control/rbac-and-directory-admin-roles). + +1. [Sign in to the Azure portal](https://portal.azure.com/) as the Azure Account Administrator. +2. Enter *subscriptions* in the search box and select **Subscriptions**. +3. Select the **subscription** > **Access control (IAM)** > **+ Add**. +4. Select the appropriate role from the dropdown menu. + + > [!div class="mx-imgBorder"] + > ![Screenshot of sequence of buttons to add role.](media/add-backup-billing-manager/add-role-to-subscription.png) + +5. Select **+ Select members**, search for a user by name or email address, highlight the user, and then choose **Select**. + + > [!div class="mx-imgBorder"] + > ![Screenshot of Add role assignment pop-out pane.](media/add-backup-billing-manager/add-role-assignment.png) + +6. Select **Review + assign**. + +> [!NOTE] +> The user must accept their email invitation before they can access the Azure subscription, if they aren't in your directory. + ## Next steps > [!div class="nextstepaction"] @@ -59,7 +137,6 @@ Billing is set up for your Azure DevOps organization. You can [review your indiv ## Related articles -* [Change your subscription for billing](change-azure-subscription.md) -* [Add a user who can set up or change billing for Azure DevOps](add-backup-billing-managers.md) +* [Increase Azure Artifacts storage limit](../../artifacts/start-using-azure-artifacts.md#increase-azure-artifacts-storage-limit) * [Buy Azure Test Plans](buy-basic-access-add-users.md) -* [Learn about Azure cost management and billing](/azure/cost-management-billing/cost-management-billing-overview) +* [Learn about cost management and billing](/azure/cost-management-billing/cost-management-billing-overview) diff --git a/docs/organizations/billing/toc.yml b/docs/organizations/billing/toc.yml index 911ed260c27..b8b74e0bc8d 100644 --- a/docs/organizations/billing/toc.yml +++ b/docs/organizations/billing/toc.yml @@ -1,35 +1,33 @@ - name: Billing overview displayName: services, Azure, subscription, monthly, bill, pricing - href: overview.md + href: overview.md?toc=/azure/devops/organizations/toc.json - name: Set up billing displayName: Azure, subscription, pay - href: set-up-billing-for-your-organization-vs.md + href: set-up-billing-for-your-organization-vs.md#set-up-billing - name: Manage paid access for users displayName: billing, assign, default, Azure, licensing, subscription, group, rules, reduce, multi-org href: buy-basic-access-add-users.md -- name: Try Azure Test Plans for free - displayName: billing, free, trial, access - href: try-additional-features-vs.md -- name: Buy parallel jobs - displayName: configure, hosted, public, private, project, purchase, quantity - href: ../../pipelines/licensing/concurrent-jobs.md +- name: Buy access to Azure Test Plans + displayName: monthly, basic, CALs, users + href: buy-access-tfs-test-hub.md - name: Buy Azure Artifacts displayName: signup, billing, basic, extension, license, storage href: ../../artifacts/start-using-azure-artifacts.md?toc=/azure/devops/organizations/toc.json -- name: Manage billing - items: - - name: Add user to manage billing - displayName: assign, subscription - href: add-backup-billing-managers.md - - name: Change Azure subscription - displayName: update, remove, billing - href: change-azure-subscription.md - - name: Buy access to Azure Test Plans - displayName: monthly, basic, CALs, users - href: buy-access-tfs-test-hub.md - - name: Billing FAQs - displayName: assignment, group, rules, basic, stakeholder, pro-rated, mulit-organization, subscription, charges - href: billing-faq.yml +- name: Buy parallel jobs + displayName: configure, hosted, public, private, project, purchase, quantity + href: ../../pipelines/licensing/concurrent-jobs.md +- name: Try Azure Test Plans for free + displayName: billing, free, trial, access + href: try-additional-features-vs.md +- name: Give user access to manage billing + displayName: assign, subscription + href: set-up-billing-for-your-organization-vs.md#give-a-user-access-to-manage-billing +- name: Change or remove subscription + displayName: update, remove, billing + href: change-azure-subscription.md +- name: Billing FAQs + displayName: assignment, group, rules, basic, stakeholder, pro-rated, multi-organization, subscription, charges + href: billing-faq.yml - name: Cloud Solution Providers items: - name: 'CSPs: Buy Azure DevOps' diff --git a/docs/organizations/billing/try-additional-features-vs.md b/docs/organizations/billing/try-additional-features-vs.md index bf27edba78b..22a7f3c5fea 100644 --- a/docs/organizations/billing/try-additional-features-vs.md +++ b/docs/organizations/billing/try-additional-features-vs.md @@ -1,14 +1,14 @@ --- title: Try Azure Test Plans for free titleSuffix: Azure DevOps Services -ms.custom: seodec18, contperf-fy22q3, freshness-fy22q1, engagement-fy23 +ms.custom: freshness-fy22q1, engagement-fy23 description: Get a free 30-day trial for Azure Test Plans (formerly Test Manager). ms.subservice: azure-devops-billing ms.assetid: 435fb3a4-1766-4172-928d-80c09cfb1410 ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 12/02/2022 +ms.date: 03/05/2025 monikerRange: 'azure-devops' --- @@ -22,7 +22,7 @@ Start a Test Plans trial and assign any of your users Basic + Test Plans for 30 ## Prerequisites -You must be a member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] ## Try Azure Test Plans @@ -39,13 +39,11 @@ You must be a member of the [Project Collection Administrators group](../securit ![Screenshot showing highlighted link to "Start free trial".](media/try-additional-features/start-free-trial.png) -5. Select **Start free trial**. - - ![Screenshot showing the "Start free trial" button.](media/try-additional-features/start-thirty-day-test-plans-trial.png) +5. Select **Start free trial** once more in the resulting window. 6. Assign users **Basic + Test Plans**, so they can access Test Plans during the trial. -For more information about using Azure Test Plans, see [Navigate Test Plans](../../test/navigate-test-plans.md). + During the trial, Test Plans users have full access to Test Plans and Basic users can execute tests only. After trial expiration, you need to buy a Basic + Test Plans license and assign it to specific users, so they can continue to use it. ## Next steps @@ -54,7 +52,8 @@ For more information about using Azure Test Plans, see [Navigate Test Plans](../ ## Related articles -- [Billing FAQs](billing-faq.yml) +- [Navigate Test Plans](../../test/navigate-test-plans.md) +- [Find answers in Billing FAQs](billing-faq.yml) - [Manage paid access for users](buy-basic-access-add-users.md) - [Buy parallel jobs for Azure DevOps](../../pipelines/licensing/concurrent-jobs.md#how-much-do-parallel-jobs-cost) -- [Azure DevOps billing overview](overview.md) +- [Understand Azure DevOps billing](overview.md) diff --git a/docs/organizations/index.yml b/docs/organizations/index.yml index 755a66f5657..97dc7f65b9c 100644 --- a/docs/organizations/index.yml +++ b/docs/organizations/index.yml @@ -10,8 +10,8 @@ metadata: description: Configure resources and manage settings for an organization, project, team, or user. ms.subservice: azure-devops-settings ms.topic: landing-page - author: KathrynEE - ms.author: kaelli + author: chcomley + ms.author: chcomley ms.date: 02/18/2022 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -27,7 +27,7 @@ landingContent: - text: About settings url: ./settings/about-settings.md - text: Get started as an administrator - url: ../user-guide/project-admin-tutorial.md?toc=/azure/devops/organizations/toc.json + url: ../user-guide/project-admin-tutorial.md?toc=/azure/devops/organizations/toc.json - linkListType: quickstart links: - text: Set user preferences @@ -46,7 +46,7 @@ landingContent: url: ../user-guide/plan-your-azure-devops-org-structure.md?toc=/azure/devops/organizations/toc.json - linkListType: concept links: - - text: Manage access with Azure Active Directory + - text: Manage access with Microsoft Entra ID url: ./accounts/access-with-azure-ad.md - linkListType: quickstart links: @@ -56,7 +56,7 @@ landingContent: links: - text: Add users to your organization url: ./accounts/add-organization-users.md?toc=/azure/devops/organizations/toc.json - - text: Connect your organization to Azure Active Directory + - text: Connect your organization to Microsoft Entra ID url: ./accounts/connect-organization-to-azure-ad.md?toc=/azure/devops/organizations/toc.json - title: Add & manage projects linkLists: @@ -149,4 +149,4 @@ landingContent: - linkListType: how-to-guide links: - text: Set test retention policies - url: ../test/how-long-to-keep-test-results.md?toc=/azure/devops/organizations/toc.json \ No newline at end of file + url: ../test/how-long-to-keep-test-results.md?toc=/azure/devops/organizations/toc.json diff --git a/docs/organizations/notifications/about-notifications.md b/docs/organizations/notifications/about-notifications.md index 89d6399e9fc..672a9259892 100644 --- a/docs/organizations/notifications/about-notifications.md +++ b/docs/organizations/notifications/about-notifications.md @@ -7,7 +7,7 @@ ms.custom: quarterly-update, engagement-fy23 ms.author: chcomley author: chcomley ms.topic: conceptual -ms.date: 02/13/2023 +ms.date: 12/17/2024 monikerRange: '<= azure-devops' --- @@ -48,14 +48,14 @@ You can create a subscription for the following categories and select from the f |Category |Template options | |---------|---------| -|Build |
      • a build completes
      • a build fails
      • a legacy XAML build controller or agent's status changes
      • a legacy XAML build's quality changes
      | -|Code (Git) |
      • a commit is pushed
      • a pull request is created or updated
      • a pull request my team is a reviewer on is updated
      • a comment is made on a pull request
      | -|Code (TFVC) |
      • code is checked in
      • code is checked in with a policy override
      • a file with a specific extension is checked in
      • a file under a specific path is checked in
      • any code review changes
      | -|Pipelines |
      • run stage waiting for approval
      • run stage waiting for Manual validation
      -|Work |
      • a work item is created
      • a work item is changed
      • a work item is deleted
      • a work item is restored
      • a work item is moved from this team project
      | -|Artifacts |
      • a package is changed
      | -|Extension management |
      • an extension is modified
      | -|Release |
      • an approval for a deployment is pending
      • a deployment is completed
      • a request for release creation failed
      • a manual intervention for a deployment is pending
      | +|Build |
        - a build completes
        - a build fails
        - a legacy XAML build controller or agent's status changes
        - a legacy XAML build's quality changes
      | +|Code (Git) |
        - a commit is pushed
        - a pull request is created or updated
        - a pull request my team is a reviewer on is updated
        - a comment is made on a pull request
      | +|Code (TFVC) |
        - code is checked in
        - code is checked in with a policy override
        - a file with a specific extension is checked in
        - a file under a specific path is checked in
        - any code review changes
      | +|Pipelines |
        - run stage waiting for approval
        - run stage waiting for Manual validation
      +|Work |
        - a work item is created
        - a work item is changed
        - a work item is deleted
        - a work item is restored
        - a work item is moved from this team project
      | +|Artifacts |
        - a package is changed
      | +|Extension management |
        - an extension is modified
      | +|Release |
        - an approval for a deployment is pending
        - a deployment is completed
        - a request for release creation failed
        - a manual intervention for a deployment is pending
      | :::moniker range=">= azure-devops-2020" @@ -133,7 +133,9 @@ There are no UI permissions associated with managing email notifications or aler ## Preferred email address -The preferred email address for your organization profile gets notifications, by default. It's typically the email address you signed into Azure DevOps with. You can manage this email address via your organization preferences profile page. +The preferred email address for your organization profile gets notifications, by default. It's typically the email address you signed into Azure DevOps with. You can manage this email address via your organization preferences profile page. + +If you're enrolled in the Microsoft Entra profile information preview, your profile information is pulled directly from Microsoft Entra and can't be edited. For more information, see [Set your preferences](../settings/set-your-preferences.md). > [!NOTE] > Your preferred email address applies across all of your organizations and cannot be changed on a per-organization basis. @@ -143,10 +145,9 @@ The preferred email address for your organization profile gets notifications, by ## Integrating with other services -If your team uses an external service to collaborate—such as Campfire or Slack—you can configure notifications for these services. We support the following out of the box services. +If your team uses an external service to collaborate—such as Trello or Slack—you can configure notifications for these services. We support the following out of the box services. -- [Campfire](../../service-hooks/overview.md?bc=%252fazure%252fdevops%252fnotifications%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fnotifications%252ftoc.json) -- [HipChat](../../service-hooks/overview.md?bc=%252fazure%252fdevops%252fnotifications%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fnotifications%252ftoc.json) +- [Trello](../../service-hooks/services/trello.md?toc=/azure/devops/organizations/notifications/toc.json&bc=/azure/devops/organizations/notifications/breadcrumb/toc.json) - [Slack](../../service-hooks/services/slack.md?toc=/azure/devops/organizations/notifications/toc.json&bc=/azure/devops/organizations/notifications/breadcrumb/toc.json) - [Microsoft Teams](../../service-hooks/services/teams.md?toc=/azure/devops/organizations/notifications/toc.json&bc=/azure/devops/organizations/notifications/breadcrumb/toc.json) diff --git a/docs/organizations/notifications/add-links-to-work-items.md b/docs/organizations/notifications/add-links-to-work-items.md deleted file mode 100644 index d22206a1c6c..00000000000 --- a/docs/organizations/notifications/add-links-to-work-items.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Link work items to other objects -titleSuffix: Azure DevOps -description: Learn how to link work items to internal Azure DevOps builds, commits, pull requests, and more, and external objects in Git and Team Foundation Version Control repositories. -ms.subservice: azure-devops-notifications -toc: show -ms.custom: contperf-fy21q2, cross-project, engagement-fy23 -ms.author: chcomley -author: chcomley -ms.topic: how-to -monikerRange: '<= azure-devops' -ms.date: 09/29/2021 ---- - -# Link work items to other objects - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -When you link work items to other objects, you maintain an audit trail of related work for your team. All users can add work item links to the following internal (Azure DevOps) and external (Git) objects. - -::: moniker range=">= azure-devops-2020" -- **Build**: found in build, integrated in build - - [Link work items to builds and deployments](../../boards/work-items/work-item-deployments-control.md) -- **Release**: integrated in release, integrated in release environment - - [Automatically link work items to builds or releases](../../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/boards/toc.json&bc=/azure/devops/boards/breadcrumb/toc.json) -- **Repository**: pull request, description, branch, commit, comment, tag - - [Configure repositories and branches to integrate with work tracking](../../repos/git/configure-repos-work-tracking.md?toc=/azure/devops/boards/toc.json&bc=/azure/devops/boards/breadcrumb/toc.json) - - [Link to work items from GitHub commits, pull requests, and issues](../../boards/github/link-to-from-github.md) - - [Azure Boards-GitHub integration](../../boards/github/index.md) -- **Wiki**: - - [Add & edit wiki pages](../../project/wiki/add-edit-wiki.md) - - [Wiki Markdown guidance](../../project/wiki/wiki-markdown-guidance.md#link-to-work-items-from-a-wiki-page) -::: moniker-end -::: moniker range="< azure-devops-2020" -- **Build**: found in build, integrated in build - - [Link work items to builds and deployments](../../boards/work-items/work-item-deployments-control.md) -- **Release**: integrated in release, integrated in release environment - - [Automatically link work items to builds or releases](../../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/boards/toc.json&bc=/azure/devops/boards/breadcrumb/toc.json) -- **Repository**: pull request, description, branch, commit, comment, tag - - [Configure repositories and branches to integrate with work tracking](../../repos/git/configure-repos-work-tracking.md?toc=/azure/devops/boards/toc.json&bc=/azure/devops/boards/breadcrumb/toc.json) - - [Link to work items from GitHub commits, pull requests, and issues](../../boards/github/link-to-from-github.md) - - [Azure Boards-GitHub integration](../../boards/github/index.md) -::: moniker-end - - - -## Link work items to pull requests -Link your work items to pull request commits, comments, description, and so on. - -1. Enter `#` to trigger the `#ID` work item picker in your pull request. You see a list of 50 work items that you've recently modified or are assigned to you. - - :::image type="content" source="media/link-pr-to-work-item.png" alt-text="Screenshot of work item list produced when entering # in PR description."::: - -2. Enter up to five keywords that match the work item type, ID, or title to narrow the list of suggested work items. - - :::image type="content" source="media/keyword-pr-link.png" alt-text="Screenshot of entering keyword after # and resulting work item in search"::: - -::: moniker range=">= azure-devops-2020" - -### Set work item state in pull request - -[!INCLUDE [temp](../../includes/set-work-item-state-pull-request.md)] - -Azure DevOps considers the following criteria (in this order) when it attempts to set the state of #mentioned work items: -1. State -1. State Category -1. Keyword - -#### Criteria logic for work item state -The following table describes the criteria logic for work item state. - -| **Criteria** | **Action** | -|--------------------|----------------------------| -| **If** the value matches a state, | **Then** set it to that state. | -| **Else If** the value matches a state category, | **Then** set the work item to first state in that category. See the following [note](#category-note).| -| **Else If** the value matches a keyword, | **Then** set the work item to matching keyword state. See the following [section](#criteria-logic-for-work-item-keyword). | -| **Else** | Ignore it and do nothing. | - -#### Criteria logic for work item keyword -The following table describes keyword logic, which helps with intent matching. For example, you might enter “Resolves”, but you really meant “Resolved”. - -| **Keyword** | **Action** | -|--------------------------------|:----------------------------------------------------------| -| Proposed, Proposes, Propose | Set to the first state in the Proposed category. | -| InProgress | Set to the first state in the In Progress category. | -| Completed, Completes, Complete | Set to the first state in the Completed category. | -| Resolved, Resolves, Resolve | Set to the first state in the Resolved category. | -| Fixes, Fixed, Fix | Close work item. Except Bug, which gets set to Resolved. | - - - -> [!NOTE] -> We don't support category matching on projects using a Hosted XML process. Category matching is only available for projects using an inherited process. - -::: moniker-end - - - -[!INCLUDE [temp](../../includes/link-work-item-builds-projects.md)] -For more information, see [Link work items to user stories, issues, bugs, and other work items](../../boards/backlogs/add-link.md) - -[!INCLUDE [temp](../../boards/includes/view-linked-objects.md)] - -> [!NOTE] -> You can't create a work item query to list linked objects. Work item queries only return work items that are linked to other work items. However, you can create a query that lists work items that contain external links. For more information, see [Query by link or attachment count](../../boards/queries/linking-attachments.md). - -## Related articles - -- [End-to-end traceability](../../cross-service/end-to-end-traceability.md) -- [Drive Git development from a work item](../..//boards/backlogs/connect-work-items-to-git-dev-ops.md) -- [Link type reference](../../boards/queries/link-type-reference.md) -- [Save work with commits](../../repos/git/commits.md) -- [View and manage pull requests](../../repos/git/pull-requests.md) diff --git a/docs/organizations/notifications/at-mentions.md b/docs/organizations/notifications/at-mentions.md index 0ad4e4e804b..0d5f24928b7 100644 --- a/docs/organizations/notifications/at-mentions.md +++ b/docs/organizations/notifications/at-mentions.md @@ -7,51 +7,52 @@ ms.custom: quarterly-update toc: show ms.author: chcomley author: chcomley +ai-usage: ai-assisted ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 03/23/2023 ---- - -# Use @mentions in work items and pull requests +ms.date: 01/06/2025 +--- + +# Use @mentions in work items and pull requests [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] ::: moniker range="azure-devops" -The **@mention** control allows you to quickly add a user or group to a work item or pull request discussion. Using the people picker of the **@mention** control, you can select a project member or group from the search list, and they receive an email notifying them of your comment. +The **@mention** control allows you to quickly add a user or group to a work item or pull request discussion. Using the people picker within the **@mention** control, you can select a project member or group from the search list. The mentioned user or group receives an email notification about your comment. -For organizations that manage their users and groups using Azure Active Directory (Azure AD), people pickers support searching all users and groups added to Azure AD, not only those users and groups added to your project. To limit the set to project members and groups, see [Manage your organization, Limit identity search and selection](../../user-guide/manage-organization-collection.md#limit-identity-selection). +For organizations that manage their users and groups using Microsoft Entra ID, people pickers support searching all users and groups within Microsoft Entra ID. You can search for users and groups beyond those users added to your project. For more information, see [Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#limit-user-visibility-for-projects-and-more). > [!NOTE] -> You can post an @mention via API. [Get the Azure DevOps User Id](/rest/api/azure/devops/graph/users/get?&preserve-view=true/view=azure-devops-rest-6.0), and then add the following html code: -> `
      @John Doe Testing mentioning
      ` -> For more information, see the [Microsoft Power Automate Community forum post](https://powerusers.microsoft.com/t5/Building-Flows/Mention-person-in-azure-devops-work-item/td-p/922467#:~:text=https%3A%2F%2Fdocs.microsoft.com%2Fen-us%2Frest%2Fapi%2Fazure%2Fdevops%2Fwit%2Fcomments%2Fadd%3Fview%3Dazure-devops-rest-6.0%20You%20can%20use%20a%20html%20in%20the,of%20the%20devops%20user%20you%20want%20to%20mention.). + +> You can post an @mention via API. To get the Azure DevOps User ID, see [Get the Azure DevOps User ID](/rest/api/azure/devops/graph/users/get?&preserve-view=true/view=azure-devops-rest-6.0). + +> +> - If your organization is using the existing HTML editor, add the following HTML code: +> ```html +>
      @John Doe Testing mentioning
      +> ``` +> - If your organization is using the new Markdown editor for comments, use the following code: +> ```markdown +> @ +> ``` ::: moniker-end ::: moniker range="< azure-devops" -The **@mention** control allows you to quickly add a user to a work item or pull request discussion. Using the people picker of the **@mention** control, you can select a project member from the search list, and they receive an email notifying them of your comment. +The **@mention** control allows you to quickly add a user to a work item or pull request discussion. Using the people picker within the **@mention** control, you can select a project member from the search list. The mentioned user receives an email notification about your comment. -For organizations that manage their users using Active Directory, people pickers provide support for searching all users added to the Active Directory, not only those users added to your project. +For organizations that manage their users using Active Directory, people pickers support searching all users within the Active Directory, not just those users added to your project. ::: moniker-end -Use the **@mention** control to start or continue a discussion within the following areas: +Use the **@mention** control to start or continue a discussion in the following areas: ::: moniker range=">= azure-devops-2020" -- A work item discussion or any rich-text field -- A pull request discussion -- Commit comments -- Changeset or shelveset comments - -::: moniker-end - -::: moniker range=" < azure-devops-2020" - -- A work item discussion -- A pull request discussion +- Work item discussions or any rich-text fields +- Pull request discussions - Commit comments - Changeset or shelveset comments @@ -65,80 +66,70 @@ Use the **@mention** control to start or continue a discussion within the follow ::: moniker-end +## Prerequisites + +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] + ## Identity search selection -When you leave a code comment in a pull request, enter **\@** to trigger the **\@mention** people picker. From the people picker, you see a list of users you've recently mentioned. To do a directory search, choose a name or enter the name of the user you're looking for. +1. Enter **@** in a code comment in a pull request to trigger the **@mention** people picker. +2. View the list of users you recently mentioned. +3. Search the directory by selecting a name from the list or entering the name of the user you're looking for. ::: moniker range="azure-devops" > [!WARNING] -> If you have permission to invite users to the organization, regardless of whether the **Restrict invitations** policy is disabled, you can **@mention** a user who isn't part of your organization. This action invites that user to your organization. For more information, see [Restrict new user invitations from project and team administrators](../../organizations/security/restrict-invitations.md). +> If you have permission to invite users to the organization, regardless of whether the **Restrict invitations** policy is disabled, you can **@mention** a user who isn't part of your organization. This action invites that user to your organization. For more information, see [Restrict new user invitations from project and team administrators](../../organizations/security/restrict-invitations.md). -To filter the list, enter the user name or alias until you've found a match. - -> [!div class="mx-imgBorder"] -> ![Screenshot of people picker](media/at-mention/identity-selector.png) +To filter the list, enter the user name or alias until you find a match. -::: moniker-end +> [!div class="mx-imgBorder"] +> ![Screenshot of people picker](media/at-mention/identity-selector.png) -::: moniker range=">= azure-devops-2020" - -You can also use group mentions. Enter the name of a team or a security group, choose :::image type="icon" source="../../media/icons/search-icon.png" border="false"::: **Search**, and then select from the options listed. +Names of mentioned users appear in blue text. Choose the **@mention link name** to open the user's contact information, providing more context for why they were added to the conversation. ::: moniker-end -To **\@mention** a user you've never selected previously, continue to enter the entire name to do your search against the full directory. - -Names of mentioned users appear in blue text. Choose the **\@mention link name** to open the user's contact information. The contact information provides more context for why they were added to the conversation. +::: moniker range=">= azure-devops-2020" -::: moniker range=">= azure-devops-2019" -> [!div class="mx-imgBorder"] -> ![Screenshot of discussion section with at mention made.](media/at-mention/at-mention-discussion.png) -::: moniker-end +You can also use group mentions. Enter the name of a team or a security group, choose :::image type="icon" source="../../media/icons/search-icon.png" border="false"::: **Search**, and then select from the options listed. -::: moniker range="< azure-devops-2019" -![Web portal, At mention user contact information accessible](media/at-mention-link-to-user-contact-card.png) ::: moniker-end +> [!div class="mx-imgBorder"] +> ![Screenshot of discussion section with at mention made.](media/at-mention/at-mention-discussion.png) > [!NOTE] -> Don't copy/paste **\@mention** users from a previous comment. While the resulting formatting looks identical to a properly entered mention, it doesn't register as a true mention nor send an email notification. - +> Don't copy and paste **@mention** users from a previous comment. Although the formatting may look identical to a properly entered mention, it doesn't register as a true mention and doesn't send an email notification. -Upon completion of your selection and text entry, your **@mention** user receives an email alerting them about the mention. +Upon completion of your selection and text entry, your **@mention** user receives an email alerting them about the mention. -::: moniker range=">= azure-devops-2019" -> [!div class="mx-imgBorder"] -> ![Screenshot of Email sent in Outlook.](media/at-mention/at-mention-work-item.png) -::: moniker-end - -::: moniker range="< azure-devops-2019" -![Email sent to at-mention user organization](media/mail-to-at-mention-user.png) -::: moniker-end +> [!div class="mx-imgBorder"] +> ![Screenshot of Email sent in Outlook.](media/at-mention/at-mention-work-item.png) +Use the **@mention** control in pull request discussions, commit comments, changeset comments, and shelveset comments. -Use the **\@mention** control in pull request discussions, commit comments, changeset comments, and shelveset comments. +> [!TIP] +> Since there's no direct `@CreatedBy` macro, you can use the `@Me` macro in combination with the "Created By" field to filter work items created by you. For example, to tag the creator of items with blank descriptions, you can run a query to identify such items and then manually tag the creators in the comments section of each work item, asking them to update the description. ::: moniker range="azure-devops" ## Limited identities in search selection -In general, people pickers search and select any user or group added to an organization's Azure AD. +People pickers generally search and select any user or group added to an organization's Microsoft Entra ID. -For organizations that manage their users and groups using Azure Active Directory (Azure AD), people pickers provide support for searching users and groups added to the Azure AD. For organizations that want to limit the search and selection to only those users and groups added to a specific project, they can do so by enabling the **Limit user visibility and collaboration to specific projects** preview feature for their organization. +For organizations using Microsoft Entra ID to manage users and groups, people pickers support searching all users and groups within the directory. To limit the search and selection to only those users and groups added to a specific project, enable the **Limit user visibility and collaboration to specific projects** preview feature for your organization. -[!INCLUDE [project-scoped-users-important-note](../../includes/project-scoped-users-important-note.md)] +When the **Limit user visibility and collaboration to specific projects** preview feature is enabled for an organization, the list of identities you can select from a people picker is limited in the following ways: -When the **Limit user visibility and collaboration to specific projects** preview feature is enabled for an organization, the list of identities you can select from a people picker is limited in one of the following ways: +- Users added to the **Project-Scoped Users** group can only select from an identity list that contains users and groups explicitly added to the project they're connected to. +- If all project members are added to the **Project-Scoped Users** group, people pickers are limited to only those users and groups added to the project. All project members can only select identities that match users and groups explicitly added to the project they're connected to. -- Users added to the **Project-Scoped Users** group are only able to select from an identity list that contains users and groups added explicitly to the project they're connected to. -- If all project members are added to the **Project-Scoped Users** group, then people pickers are limited to only those users and groups added to the project. All project members can only select identities that match users and groups added explicitly to the project they're connected to. - [!INCLUDE [project-scoped-users-warning](../../includes/project-scoped-users-warning.md)] ::: moniker-end ## Related articles -- [Work item form controls](../../boards/work-items/work-item-form-controls.md) +- [Work item form controls](../../boards/work-items/about-work-items.md#work-item-form-controls) - [Pull requests](../../repos/git/pull-requests.md) diff --git a/docs/organizations/notifications/change-email-address.md b/docs/organizations/notifications/change-email-address.md index 671040a4989..6ad7bc67ffa 100644 --- a/docs/organizations/notifications/change-email-address.md +++ b/docs/organizations/notifications/change-email-address.md @@ -7,7 +7,7 @@ ms.topic: conceptual ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 06/22/2023 +ms.date: 01/27/2025 --- # Change your preferred email address for notifications @@ -20,7 +20,8 @@ You can change your preferred email address for notifications from your organiza > [!NOTE] > - Your preferred email address applies across all of your organizations and can't be changed on a per-organization basis. -> - It may take some time for the settings to take effect. +> - Your settings might take some time to take effect. +> - If you're enrolled in the Microsoft Entra profile information preview, your profile information gets pulled directly from Microsoft Entra and therefore you can't edit it. For more information, see [Set user preferences, Microsoft Entra profile preview](../settings/set-your-preferences.md#microsoft-entra-profile-preview). ::: moniker-end ## Change your email address @@ -29,7 +30,7 @@ Do the following steps to update your preferred email address, where you receive ::: moniker range="azure-devops" -1. From your home page, open user settings, :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false":::, and then select **Profile**. +1. From your home page, open user settings :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false":::, and then select **Profile**. :::image type="content" source="../../media/open-user-settings-profile-preview.png" alt-text="Screenshot showing user settings profile open."::: @@ -39,7 +40,7 @@ Do the following steps to update your preferred email address, where you receive ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" **Subscribers** > your **Team** > **Delivery settings**. @@ -50,14 +50,6 @@ You can manage subscriptions and delivery settings at the team-level or organiza ::: moniker-end -::: moniker range="tfs-2018" - -1. In Organization settings, select your **Team** > **Subscribers** > **Delivery settings**. - - ![Screenshot showing organization-level settings.](media/email-team-subscribers-view.png) - -::: moniker-end - 2. Select from the following settings: * **Deliver to email address:** notifications get delivered to a specific email address. @@ -75,7 +67,7 @@ If you don't explicitly choose delivery settings for a team or group, it gets de The recipients for a custom team or group subscription get determined by the subscription. But, with certain delivery options, the team's default delivery setting is used to determine the set of recipients. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ![email-team-delivery-options](media/email-team-delivery-options-new.png) @@ -92,23 +84,6 @@ The following delivery options are available for a group or team subscription: ::: moniker-end -::: moniker range="tfs-2018" - -![Screenshot showing email team delivery options.](media/email-team-delivery-options.png) - -You can choose from the following delivery options for a group or team subscription: - -|Option |Recipients | -|---------|---------| -|**[Member of team by role](#member-of-team-by-role)** | Members of the team or group who have one of the selected roles, for example, work item assignee. | -|**[Team preference](#team-preference)** | Determined by the delivery setting of the team or group (_Do not deliver_, _preferred email address_, or _members of team_). | -|**[Custom email address](#custom-email-address)** | Specified email address. | -|**[Members of team](#members-of-team)** | Members of the team or group, except members who have opted out of the subscription. | - -> [!NOTE] -> The default delivery setting of each member is honored, including groups that are members of the team or group. - -::: moniker-end ### Member of team by role The email recipient list is determined by members that had a role in the event. For example, the user assigned the work item has the role _Assigned to (new)_ while the identity that was assigned the work item has the role _Assigned to (previous)_. The full list of roles for each event type is shown in the [supported event types](oob-supported-event-types.md). @@ -166,14 +141,14 @@ Let's look at a few scenarios. We use the following symbols to denote the types * `I`: individual user * `T`: nested team or group -* `A`: mail-enabled Azure Active Directory (Azure AD) group. +* `A`: mail-enabled Microsoft Entra group. | Scenario | Example | |--|--| | A member with _Do not deliver_ preference | The team has members `I1`, `I2`, and `T1`. `T1`'s delivery preference is _Do not deliver_. What happens: only `I1` and `I2` get notified via their preferred email addresses. Members of `T1` aren't notified. | | A member with _Deliver to individual members_ preference | The team has members `I1`, `I2`, and `T1`. `T1`'s delivery preference is _Deliver to individual members_. `T1` has members `I2` and `I3`. What happens: `T1` is expanded (because of its delivery preference) and so `I1`, `I2`, and `I3` get notified via their preferred email addresses. | | A nested group | The team has members `I1`, `I2`, and `T1`. `T1` has members `I2`, `I3`, and `T2`. `T1`'s delivery preference is _Do not deliver_. `T2` has members `I4` and `I5`. `T2`'s delivery preference is _Deliver to individual members_. What happens: because `T1` isn't expanded (because its delivery preference is "do not deliver"), only `I1` and `I2` get notified via their preferred email addresses. | -| A member that's an Azure AD group | The team has members `I1`, `I2`, and `A1`. What happens: only `I1` and `I2` get notified via their preferred email addresses. Members of `A1` don't get notified, as Azure DevOps doesn't expand AD groups when delivering notifications. | +| A member that's a Microsoft Entra group | The team has members `I1`, `I2`, and `A1`. What happens: only `I1` and `I2` get notified via their preferred email addresses. Members of `A1` don't get notified, as Azure DevOps doesn't expand AD groups when delivering notifications. | ## Related articles diff --git a/docs/organizations/notifications/exclude-self-from-email.md b/docs/organizations/notifications/exclude-self-from-email.md index 70280058d8d..417a31cb9da 100644 --- a/docs/organizations/notifications/exclude-self-from-email.md +++ b/docs/organizations/notifications/exclude-self-from-email.md @@ -7,7 +7,7 @@ ms.reviewer: wismythe ms.author: chcomley author: chcomley ms.topic: conceptual -ms.date: 12/30/2019 +ms.date: 01/30/2025 monikerRange: '<= azure-devops' --- @@ -19,16 +19,32 @@ When you create a team role-based notification subscription, you can choose the For example, if your team has a subscription for a _pull request created_ event, the user who creates the pull request in the project doesn't receive this notification email. Other members of the team receive the notification email. -This option is good for users who don't want notifications of events that they trigger. However, some users may feel left out when their teammates receive the email and they didn't. Let your team decide which option is best. +This option is good for users who don't want notifications of events that they trigger. However, some users might prefer to receive the same notifications as their teammates. Let your team decide which option is best. + +## Prerequisites + +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] + +## Skip initiator + +Do the following steps to opt out of receiving notifications that you create: + +1. Sign in to your project (`https://dev.azure.com/{Your_Organization/Your_Project}`). +2. Select **Project settings** > **Notifications**. +3. Create a new subscription or edit an existing one. +4. Select the notification. +5. Check the **Skip initiator** box. > [!div class="mx-imgBorder"] -> ![New subscription skip initiator](media/new-sub-skip-initiator.png) +> ![Screenshot shows new subscription skip initiator.](media/new-sub-skip-initiator.png) [!INCLUDE [note-smtp-server](includes/note-smtp-server.md)] +You don't receive notifications for events you trigger yourself. + #### Related articles - [Manage personal notification settings](manage-your-personal-notifications.md) - [Follow a specific work item](../../boards/work-items/follow-work-items.md) - [Manage notifications for a team](./manage-team-group-global-organization-notifications.md) -- [Change your preferred email address](change-email-address.md) \ No newline at end of file +- [Change your preferred email address](change-email-address.md) diff --git a/docs/organizations/notifications/faq-notifications.yml b/docs/organizations/notifications/faq-notifications.yml index 1aa837bf225..6b059a26936 100644 --- a/docs/organizations/notifications/faq-notifications.yml +++ b/docs/organizations/notifications/faq-notifications.yml @@ -3,14 +3,14 @@ metadata: title: Notification FAQs titleSuffix: Azure DevOps description: General questions and answers about notifications settings in Azure DevOps. - ms.technology: devops-collab toc: show ms.topic: faq ms.author: chcomley + ms.subservice: azure-devops-notifications author: chcomley - ms.date: 07/25/2022 + ms.date: 09/09/2024 monikerRange: '<= azure-devops' -title: Notifications FAQS +title: FAQs about Notifications summary: | [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -34,7 +34,7 @@ sections: - question: | Why do some emails have multiple recipients on the To line? answer: | - A default or team or group subscription can have multiple recipients, depending on how it's configured. When all users have permission to the resource related to the event, they get combined in one email. + A default or team or group subscription can have multiple recipients, depending on how it was configured. When all users have permission to the resource related to the event, they get combined in one email. Previously, each recipient received an individually addressed email, which could result in the same user getting multiple emails because of their membership in multiple groups. @@ -44,9 +44,42 @@ sections: Yes. For more information, see [Use @ mentions in work items and pull requests](at-mentions.md). - question: | - How do subscriptions at one level impact what notifications are sent based on subscriptions on another level? + How do subscriptions at one level affect what notifications are sent based on subscriptions on another level? answer: | - Subscriptions made at one level are fully and completely independent of each other. There is no interaction. If you turn something off at the project level but not at the user level, then you get the notification. + Subscriptions made at one level are independent of each other. There's no interaction. If you turn off something at the project level but not at the user level, then you get the notification. + + - question: | + Is it possible to translate notification messages in Azure DevOps? Even though my profile is in a different language, the email messages arrive in English. + answer: | + No. You can't customize the language of notification messages via Azure DevOps. Consider [integrating with a custom application or service](../../integrate/index.md?view=azure-devops) to achieve your desired results. + + - question: | + How can I troubleshoot @mentions that are denied due to permissions? + answer: | + If you encounter issues with @mentions being denied due to permissions, follow these steps: + + - **Check user permissions:** + - Ensure that the user you're trying to mention has the necessary permissions to access the work item or pull request. + - Users must have at least **Basic** access level to be mentioned in work items and pull requests. + - **Check project membership:** + - Verify that the user is a member of the project. Only project members can be mentioned using the @mention control. + - To add a user to the project, go to **Project settings** > **Permissions** > **Members** and add the user. + - **Check group membership:** + - Ensure that the group you're trying to mention has the necessary permissions to access the work item or pull request. + - Groups must have at least **Basic** access level to be mentioned in work items and pull requests. + - **Check group settings:** + - Verify that the group is correctly configured in Microsoft Entra ID. + - Ensure that the group is added to the project. To add a group to the project, go to **Project Settings** > **Permissions** > **Groups** and add the group. + - **Limit identity search and selection:** + - If your organization manages users and groups using Microsoft Entra ID, you can limit the set of users and groups to project members and groups. + - For more information, see [Limit identity search and selection](../../user-guide/manage-organization-collection.md). + - **Contact support:** + - If you verified permissions and project membership but still encounter issues, contact your Azure DevOps administrator or [support team](https://developercommunity.visualstudio.com/home) for further assistance. + + - question: | + How can I cc someone on a work item discussion? + answer: | + You can't cc someone on a work item discussion. But, you can mention them in the discussion by using the @mention control. To clarify that you just want them to be aware of the work item, include a brief message in your comment. additionalContent: | diff --git a/docs/organizations/notifications/includes/opt-out-notification.md b/docs/organizations/notifications/includes/opt-out-notification.md index 722e831401a..5de90fb7360 100644 --- a/docs/organizations/notifications/includes/opt-out-notification.md +++ b/docs/organizations/notifications/includes/opt-out-notification.md @@ -9,7 +9,7 @@ ms.date: 06/22/2023 ## Unsubscribe or opt out of a team or out-of-box (OOB) notification subscription -You can choose to not receive notifications for certain team notification subscriptions by opting out. +You can opt out of receiving notifications for specific team notification subscriptions. ::: moniker range="azure-devops" @@ -32,4 +32,13 @@ To unsubscribe from any notification, slide the state **On/Off** indicator to th ::: moniker-end > [!NOTE] -> Whether or not you're an administrator, when you move the toggle for a shared team notification subscription in your settings only impacts you and not other team members. +> Whether you're an administrator or not, toggling for a shared team notification subscription in your settings only affects your notifications, not those of other team members. + +## Disable work item notifications for a project + +To override organization settings and disable all work item notifications for a project in Azure DevOps, do the following steps: + +1. Sign in to your project (`https://dev.azure.com/{Your_Organization/Your_Project}`). +2. Select **Project settings** > **Notifications**. +3. Highlight the Work notification and select :::image type="icon" source="../../../media/icons/gear_icon.png" border="false"::: **Delivery settings**. +4. Choose **Do not deliver** and **Save**. diff --git a/docs/organizations/notifications/includes/prerequisites-notifications.md b/docs/organizations/notifications/includes/prerequisites-notifications.md new file mode 100644 index 00000000000..96fceb33ca1 --- /dev/null +++ b/docs/organizations/notifications/includes/prerequisites-notifications.md @@ -0,0 +1,11 @@ +--- +ms.subservice: azure-devops-security +ms.author: chcomley +author: chcomley +ms.topic: include +ms.date: 01/13/2025 +--- + +| Category | Requirements | +|--------------|-------------| +|**Permissions** |- **Team notifications:** Member of the [Project Administrators](../../security/change-project-level-permissions.md) group or [team administrator](../../settings/add-team-administrator.md) role.
      - **Project notifications:** Member of the [Project Administrators](../../security/change-project-level-permissions.md) group.
      - **Organization notifications:** Member of the [Project Collection Administrators](../../security/change-organization-collection-level-permissions.md) group.| diff --git a/docs/organizations/notifications/integrate-third-party-services.md b/docs/organizations/notifications/integrate-third-party-services.md index cf1be7f5ad0..cf2aadd1551 100644 --- a/docs/organizations/notifications/integrate-third-party-services.md +++ b/docs/organizations/notifications/integrate-third-party-services.md @@ -17,7 +17,6 @@ monikerRange: '<= azure-devops' Integrate with your favorite services by notifying them when events happen in Azure DevOps. We have multiple [messaging app integrations](../../service-hooks/services/workplace-messaging-apps.md) to help users receive notifications in response to events in Azure DevOps, complete workflows and take proactive actions such as allowing users to approve release deployments and creating work items from their channels. - See the following examples for specific service hook integrations: * [Send Azure DevOps notifications to a Slack channel](../../service-hooks/services/slack.md) diff --git a/docs/organizations/notifications/manage-team-group-global-organization-notifications.md b/docs/organizations/notifications/manage-team-group-global-organization-notifications.md index f30e3b43515..18ba8611da5 100644 --- a/docs/organizations/notifications/manage-team-group-global-organization-notifications.md +++ b/docs/organizations/notifications/manage-team-group-global-organization-notifications.md @@ -1,14 +1,14 @@ --- -title: Manage notifications for a team, project, organization or collection -titleSuffix: Azure DevOps -description: Learn how to configure team, project, and organization/collection notifications for when changes occur to source code, git, work items, and builds in Azure DevOps. +title: Manage notifications for a team, project, organization, or collection +titleSuffix: Azure DevOps +description: Learn how to configure team, project, and organization/collection notifications for when changes occur to source code, git, work items, and builds in Azure DevOps. ms.subservice: azure-devops-notifications ms.assetid: 6edc44d0-2729-46f5-8108-c8a5160a6a7a -ms.custom: contperf-fy21q2, cross-project +ms.custom: cross-project ms.author: chcomley author: chcomley ms.topic: how-to -ms.date: 04/24/2023 +ms.date: 09/05/2024 monikerRange: '<= azure-devops' --- @@ -22,15 +22,7 @@ For example, when a high priority work item is assigned to your team's area path ## Prerequisites -To manage notifications, you must be an administrator for the level you want to manage: -- Team: You must be a **Team Administrator** to modify subscriptions for a team. -- Project: You must be a member of the **Project Administrators** group to create or modify subscriptions for a project. -- Organization: You must be a member of the **Project Collection Administrators** group to create or modify subscriptions for an organization or collection. - -If you're not an administrator, get added as one. For more information, see the following articles: -- [Add a team administrator](../../organizations/settings/add-team-administrator.md) -- [Change permissions at the project-level](../../organizations/security/change-project-level-permissions.md) -- [Change permissions at the organization or collection-level](../../organizations/security/change-organization-collection-level-permissions.md) +[!INCLUDE [prerequisites-notifications](includes/prerequisites-notifications.md)] [!INCLUDE [note-smtp-server](includes/note-smtp-server.md)] @@ -76,15 +68,15 @@ A subscription lets you control what your team is notified of and how the team r > [!TIP] > For **Team members by role**, each role is fairly self-explanatory. However, the following two roles may need some further explanation. > - > **Changed reviewers** applies to any reviewer that's added or deleted, as a result of policies defined for the set of files. For example, a push to a pull request (PR) could introduce a change to File1.cs. If there’s a policy which says that Person A needs to review changes to File1.cs, they’d be in the Changed reviewers role for that iteration of the PR. + > **Changed reviewers** applies to any reviewer added or deleted, as a result of policies defined for the set of files. For example, a push to a pull request (PR) could introduce a change to File1.cs. If there’s a policy which says that Person A needs to review changes to File1.cs, they’d be in the Changed reviewers role for that iteration of the PR. > - > The **Reset reviewers** role is related to the “reset votes” policy. For example, the repo has configured the policy, “Reset votes on new pushes”. Person B, who was required on the PR, has already approved this PR. Because of the reset votes policy, their vote has been reset. Thus, she’s in the Reset reviewers role for that iteration. + > The **Reset reviewers** role is related to the “reset votes” policy. For example, the repo configured the policy, “Reset votes on new pushes”. Person B, who was required on the PR, already approved this PR. Because of the reset votes policy, their vote is reset. Thus, they're in the Reset reviewers role for that iteration. 2. Choose whether you want to receive notifications about activity in all projects or only a specific project. ![Screenshot of selected scope.](media/new-sub-scope.png) -3. Optionally, configure more filter criteria. +3. Optionally, configure more filter criteria. For fields, such as Created By, that require a user as a value, enter the username or email address of the user. ![Screenshot of configuring additional filter criteria.](media/new-sub-filter-conditions.png) @@ -92,26 +84,26 @@ A subscription lets you control what your team is notified of and how the team r ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="< azure-devops" 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -1. Select **Project settings** > **Notifications**. +2. Select **Project settings** > **Notifications**. :::image type="content" source="media/nav-team-notifications-hub-newnav.png" alt-text="Screenshot of Project settings and Notifications highlighted"::: -2. Select **New subscription**. +3. Select **New subscription**. ![New subscription is highlighted.](media/new-subscription-newnav.png) -3. Select the type of activity you want your team to be notified of. +4. Select the type of activity you want your team to be notified of. ![Select event category and template.](media/new-sub-page1.png) -1. Provide a description to help you identify the subscription later. +5. Provide a description to help you identify the subscription later. ![Provide a description.](media/new-sub-description.png) -1. Choose which team members should receive a notification: +6. Choose which team members should receive a notification: ![Select role.](media/new-sub-team-delivery-by-role.png) @@ -128,70 +120,22 @@ A subscription lets you control what your team is notified of and how the team r > [!TIP] > For **Team members by role**, each role is fairly self-explanatory. However, the following two roles may need some further explanation. - > **Changed reviewers** applies to any reviewer that's added or deleted, as a result of policies defined for the set of files. For example, a push to a pull request (PR) could introduce a change to File1.cs. If there’s a policy which says that Person A needs to review changes to File1.cs, they’d be in the Changed reviewers role for that iteration of the PR. - > The **Reset reviewers** role is related to the “reset votes” policy. For example, the repo has configured the policy, “Reset votes on new pushes”. Person B, who was required on the PR, has already approved this PR. Because of the reset votes policy, their vote has been reset. Thus, she’s in the Reset reviewers role for that iteration. + > **Changed reviewers** applies to any reviewer added or deleted, as a result of policies defined for the set of files. For example, a push to a pull request (PR) could introduce a change to File1.cs. If there’s a policy which says that Person A needs to review changes to File1.cs, they’d be in the Changed reviewers role for that iteration of the PR. + > The **Reset reviewers** role is related to the “reset votes” policy. For example, the repo configured the policy, “Reset votes on new pushes”. Person B, who was required on the PR, already approved this PR. Because of the reset votes policy, their vote is reset. Thus, they're in the Reset reviewers role for that iteration. -1. Choose whether you want to receive notifications about activity in all projects or only a specific project. +7. Choose whether you want to receive notifications about activity in all projects or only a specific project. ![Select scope](media/new-sub-scope.png) -1. Optionally, configure more filter criteria. +8. Optionally, configure more filter criteria. ![Configure additional filter criteria.](media/new-sub-filter-conditions.png) -1. Select **Finish** to save the new subscription. +9. Select **Finish** to save the new subscription. ::: moniker-end -::: moniker range="tfs-2018" - -1. Open the **Notifications** page in **Team settings**: `https://dev.azure.com/{organization}/{project}/_admin/_notifications?view=contents` - - > [!div class="mx-imgBorder"] - >![Go to team notifications page](media/nav-team-notifications-hub.png) - -2. Select **New subscription**. - - ![New subscription](media/new-subscription.png) - -3. Select the type of activity you want your team to be notified of. - - ![Select event category and template](media/new-sub-page1.png) - -4. Provide a description to help you identify the subscription later. - - ![Provide a description.](media/new-sub-description.png) - -5. Choose which team members should receive a notification: - - ![Select role](media/new-sub-team-delivery-by-role.png) - - Choose from one of the following delivery options: - - |Deliver to |Description | - |---------|---------| - |**Members of Azure DevOps by role** | Only certain team members associated with the event are notified. For example, for work item changes, you might only want the current assignee of the work item to receive a notification. | - |**Team preference** | use the team's default delivery preference. For more information, see [Manage delivery settings](#manage). | - |**Custom email address** | Send an email to a specified email address. | - |**Members of Azure DevOps** | Send an individual email to each member of the team. | - |**SOAP** | Send to an email address. | - - - For certain activities, when you select **Team members by role**, you can choose to have the user that initiated the activity receive a notification. This notification is controlled by the **Skip initiator** checkbox. By default, this box is checked, meaning the user that starts the change isn't notified about it. - -6. Choose whether you want to receive notifications about activity in all projects or only a specific project. - - ![Select scope](media/new-sub-scope.png) - -7. Optionally, configure more filter criteria. - - ![Configure additional filter criteria.](media/new-sub-filter-conditions.png) - -8. Select **Finish** to save the new subscription. - -::: moniker-end - - + > [!TIP] > If you don't want to receive a notification for an event that you initiated, you can turn on the option, *Skip initiator*. For more information, see [Exclude yourself from notification emails for events that you initiate](exclude-self-from-email.md). @@ -211,49 +155,7 @@ Choose to allow or block delivery of emails for all subscriptions owned by a tea ::: moniker range="azure-devops-2020" > [!TIP] -> You can send an email to all collections in an application tier. See [Configure an SMTP server and customize email for alerts and feedback requests](/azure/devops/server/admin/setup-customize-alerts). Also, you can generate a banner with the [**az devops banner command**](../../organizations/settings/manage-banners.md) that all users see when they sign in. - -::: moniker-end - -::: moniker range="< azure-devops-2020" -> [!TIP] -> You can send an email to all collections in an application tier. See [Configure an SMTP server and customize email for alerts and feedback requests](/azure/devops/server/admin/setup-customize-alerts). - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - - ![Open Organization settings](../../media/settings/open-admin-settings-vert.png) - -3. Select **Global notifications** > **Subscribers**, enter and find your group, and then select **Delivery settings**. - - ![Group notification settings](media/group-notification-settings.png) - -4. Choose which option best fits your group's needs, and then select **Save**. - - ![Delivery settings options for group.](media/group-delivery-settings.png) - -Your group delivery settings are updated for notifications. - -## Manage team and project delivery settings - -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -1. Select **Project settings** > **Notifications**. - - :::image type="content" source="media/nav-team-notifications-hub-newnav.png" alt-text="Screenshot of Project settings and Notifications highlighted."::: - -2. Choose **Delivery settings**: - - ![Delivery settings](media/delivery-settings-newnav.png) - -3. Choose which option best fits your team's needs: - - ![Delivery settings options for team and project.](media/delivery-settings-options.png) - -Your team delivery settings are updated for notifications. +> You can send an email to all collections in an application tier. See [Configure an SMTP server and customize email for alerts and feedback requests](/azure/devops/server/admin/setup-customize-alerts). Also, you can generate a banner to communication with users without sending out mass emails. For more information, see [Add and manage information banners in Azure DevOps](../../organizations/settings/manage-banners.md). ::: moniker-end @@ -261,8 +163,8 @@ Your team delivery settings are updated for notifications. ## Related articles -- [Manage personal notification settings](manage-your-personal-notifications.md) -- [Set your preferences](../../organizations/settings/set-your-preferences.md) -- [Default and supported notifications](oob-built-in-notifications.md) -- [Follow a specific work item](../../boards/work-items/follow-work-items.md) +- [Manage your personal notification settings](manage-your-personal-notifications.md) +- [Set your notification preferences](../../organizations/settings/set-your-preferences.md) +- [Review default and supported notifications](oob-built-in-notifications.md) +- [Follow a specific work item](../../boards/work-items/follow-work-items.md) - [Change your preferred email address](change-email-address.md) diff --git a/docs/organizations/notifications/manage-your-personal-notifications.md b/docs/organizations/notifications/manage-your-personal-notifications.md index fd6b364631f..c18ce998ee6 100644 --- a/docs/organizations/notifications/manage-your-personal-notifications.md +++ b/docs/organizations/notifications/manage-your-personal-notifications.md @@ -4,7 +4,7 @@ titleSuffix: Azure DevOps description: Get personally notified, when changes occur to source code, git, work items, and builds in Azure DevOps. ms.subservice: azure-devops-notifications ms.assetid: 644687b3-e30e-46b0-8d3e-3d4a4e34d13a -ms.custom: contperf-fy22q1, cross-project +ms.custom: cross-project ms.topic: how-to ms.author: chcomley author: chcomley @@ -32,8 +32,7 @@ For information about team and project-level notifications, see [Team and projec ## Prerequisites -- Every user can manage their personal notifications -- See [about notifications](about-notifications.md) +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] ## View your personal notifications @@ -58,7 +57,7 @@ The following table shows notification event examples. For more information, see ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="< azure-devops" 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). @@ -68,21 +67,9 @@ The following table shows notification event examples. For more information, see ::: moniker-end -::: moniker range=" tfs-2018" -Open **User settings**, and then select **Notification settings** from the resulting list. - :::image type="content" source="media/nav-personal-notifications-hub-newnav.png" alt-text="Screenshot showing personal notifications hub."::: - -::: moniker-end - -::: moniker range="tfs-2018" - -## View and edit all notification subscriptions - -The following view shows all notification subscriptions that either you or an administrator created. Notification subscriptions let you control what you get notified about. Subscribed notifications are indicated with the State as **On**. - -::: moniker-end + ::: moniker range="azure-devops" @@ -96,7 +83,7 @@ The following view shows all notification subscriptions that either you or an ad ::: moniker-end -::: moniker range=">= tfs-2018" +::: moniker range="<=azure-devops" A notification subscription can be only for you. But, if you're a team administrator you can ensure that it goes to everyone on the team. @@ -131,7 +118,7 @@ With custom personal notification subscriptions, you can define precise criteria ::: moniker-end -::: moniker range="> tfs-2018 < azure-devops" +::: moniker range=" [!NOTE] - > The fields available for filtering event criteria differ depending on the category and template that you select. - -3. Select **Finish** when you're done. The notification subscription appears in the list under the category that you selected. - - :::image type="content" source="media/manage-personal-notifications-subscription-added.png" alt-text="New subscription added."::: - -::: moniker-end [!INCLUDE [opt-out-notification](includes/opt-out-notification.md)] diff --git a/docs/organizations/notifications/media/ALM_CT_AddMembers.png b/docs/organizations/notifications/media/ALM_CT_AddMembers.png deleted file mode 100644 index 574b710450c..00000000000 Binary files a/docs/organizations/notifications/media/ALM_CT_AddMembers.png and /dev/null differ diff --git a/docs/organizations/notifications/media/delivery-settings-options.png b/docs/organizations/notifications/media/delivery-settings-options.png deleted file mode 100644 index 2f515665901..00000000000 Binary files a/docs/organizations/notifications/media/delivery-settings-options.png and /dev/null differ diff --git a/docs/organizations/notifications/media/email-personal-other.png b/docs/organizations/notifications/media/email-personal-other.png index 5f382f6623c..6ae3773280e 100644 Binary files a/docs/organizations/notifications/media/email-personal-other.png and b/docs/organizations/notifications/media/email-personal-other.png differ diff --git a/docs/organizations/notifications/media/email-personal-preferred.png b/docs/organizations/notifications/media/email-personal-preferred.png index ce8310c2970..962a7d965fe 100644 Binary files a/docs/organizations/notifications/media/email-personal-preferred.png and b/docs/organizations/notifications/media/email-personal-preferred.png differ diff --git a/docs/organizations/notifications/media/email-team-delivery-option-custom.png b/docs/organizations/notifications/media/email-team-delivery-option-custom.png index c45b1b89479..997054ba3fa 100644 Binary files a/docs/organizations/notifications/media/email-team-delivery-option-custom.png and b/docs/organizations/notifications/media/email-team-delivery-option-custom.png differ diff --git a/docs/organizations/notifications/media/group-notification-settings.png b/docs/organizations/notifications/media/group-notification-settings.png index 8d28cf72d6f..1900cc873e0 100644 Binary files a/docs/organizations/notifications/media/group-notification-settings.png and b/docs/organizations/notifications/media/group-notification-settings.png differ diff --git a/docs/organizations/notifications/media/keyword-pr-link.png b/docs/organizations/notifications/media/keyword-pr-link.png index f5f1aa6d64c..ec03dd3d282 100644 Binary files a/docs/organizations/notifications/media/keyword-pr-link.png and b/docs/organizations/notifications/media/keyword-pr-link.png differ diff --git a/docs/organizations/notifications/media/link-pr-to-work-item.png b/docs/organizations/notifications/media/link-pr-to-work-item.png index cfb5536fcb1..b2acf3297fd 100644 Binary files a/docs/organizations/notifications/media/link-pr-to-work-item.png and b/docs/organizations/notifications/media/link-pr-to-work-item.png differ diff --git a/docs/organizations/notifications/media/nav-ui/organization-notifications-s172.png b/docs/organizations/notifications/media/nav-ui/organization-notifications-s172.png index c470a77aa70..2ee336bde90 100644 Binary files a/docs/organizations/notifications/media/nav-ui/organization-notifications-s172.png and b/docs/organizations/notifications/media/nav-ui/organization-notifications-s172.png differ diff --git a/docs/organizations/notifications/media/personal/ALM_AN_Email.png b/docs/organizations/notifications/media/personal/ALM_AN_Email.png deleted file mode 100644 index 1f8830c5bf0..00000000000 Binary files a/docs/organizations/notifications/media/personal/ALM_AN_Email.png and /dev/null differ diff --git a/docs/organizations/notifications/media/personal/user-notifications.png b/docs/organizations/notifications/media/personal/user-notifications.png index ef165113582..34b4644e601 100644 Binary files a/docs/organizations/notifications/media/personal/user-notifications.png and b/docs/organizations/notifications/media/personal/user-notifications.png differ diff --git a/docs/organizations/notifications/media/team-delivery-settings-new-ui.png b/docs/organizations/notifications/media/team-delivery-settings-new-ui.png index 795a6a820ee..2aff02a82e0 100644 Binary files a/docs/organizations/notifications/media/team-delivery-settings-new-ui.png and b/docs/organizations/notifications/media/team-delivery-settings-new-ui.png differ diff --git a/docs/organizations/notifications/navigating-the-ui.md b/docs/organizations/notifications/navigating-the-ui.md index 6cc8070f61f..39cdbd0bdd3 100644 --- a/docs/organizations/notifications/navigating-the-ui.md +++ b/docs/organizations/notifications/navigating-the-ui.md @@ -34,14 +34,9 @@ You can set notifications at the following levels: ## Prerequisites -* Each user can manage their personal notifications -* To manage team notifications, you must be added as a [team administrator](../../organizations/settings/add-team-administrator.md) or be a member of [**Project Administrators** group](../../organizations/security/change-project-level-permissions.md) -* To manage project-level notifications, you must be a member of the [**Project Administrators** group](../../organizations/security/change-project-level-permissions.md) -* To manage organization or collection-level notifications, you must be a member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md). +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] -For more permission settings regarding notifications, see [Permissions and groups, Notifications or alerts](../../organizations/security/permissions.md#notifications-or-alerts). - - + ## Open your personal notifications @@ -56,39 +51,32 @@ Open your :::image type="icon" source="../../media/icons/user-settings-gear.png" ::: moniker range="< azure-devops" Open your profile menu and choose **Notification settings**. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] -> ![Go to personal notifications page](media/nav-personal-notifications-hub.png) -::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" -:::image type="content" source="media/personal/user-notifications.png" alt-text="View personal notifications page"::: -::: moniker-end For more information, see [Manage your notifications](manage-your-personal-notifications.md) - + ## Open team or project level notifications Enter the following URL to reach a team or project-level notifications page, replacing {organization} and {project} with your organization's and project's name. ```URL -https://dev.azure.com/{organization}/{project}/_settings/notifications +https://dev.azure.com/{Your_Organization}/{Your_Project}/_settings/notifications ``` > [!div class="mx-imgBorder"] -> ![Screenshot of team notifications page](media/nav-team-notifications-hub-newnav.png) +> ![Screenshot shows team notifications page.](media/nav-team-notifications-hub-newnav.png) For more information, see [Manage notifications for a team or group](manage-team-group-global-organization-notifications.md) - + ## Open Global notifications -::: moniker range="azure-devops" +::: moniker range="azure-devops" 1. Enter the following URL to reach the organization-level notifications page, replacing *OrganizationName* with your organization's name. @@ -106,7 +94,7 @@ For more information, see [Manage notifications for a team or group](manage-team ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="< azure-devops" Enter the following URL to reach the organization-level notifications page, replacing *ServerName* and *CollectionName* with your instance name. @@ -120,24 +108,12 @@ Enter the following URL to reach the organization-level notifications page, repl :::image type="content" source="../../media/settings/open-collection-settings-2020.png" alt-text="Open Collection settings"::: -2. Choose **Global Notifications**. +2. Select **Global Notifications**. :::image type="content" source="media/nav-ui/collection-notifications-2020.png" alt-text="Select to open Global Notifications"::: ::: moniker-end -::: moniker range="tfs-2018" - -```URL -https://dev.azure.com/{organization}/_admin/_notifications -``` - -:::image type="content" source="media/nav-organization-notifications-hub.png" alt-text="Screenshot showing notifications selection."::: - -:::image type="content" source="media/view-organization-notification-hub.png" alt-text="Screenshot showing notifications hub."::: - -::: moniker-end - For more information, see [Manage team and Global notifications](manage-team-group-global-organization-notifications.md) ## Related articles diff --git a/docs/organizations/notifications/oob-built-in-notifications.md b/docs/organizations/notifications/oob-built-in-notifications.md index 2cd8c7d54e9..a14c2e9c44c 100644 --- a/docs/organizations/notifications/oob-built-in-notifications.md +++ b/docs/organizations/notifications/oob-built-in-notifications.md @@ -81,4 +81,4 @@ You can create subscriptions using the following templates for yourself, a team, - [About notifications](about-notifications.md) - [Manage personal notifications](./manage-team-group-global-organization-notifications.md) -- [Unsubscribe from a notification](unsubscribe-default-notification.md) \ No newline at end of file +- [Unsubscribe from a notification](unsubscribe-default-notification.md) diff --git a/docs/organizations/notifications/toc.yml b/docs/organizations/notifications/toc.yml index ad6e6d451e2..c7957533c23 100644 --- a/docs/organizations/notifications/toc.yml +++ b/docs/organizations/notifications/toc.yml @@ -1,76 +1,75 @@ - name: About notifications - href: about-notifications.md displayName: view, set, see, edit, custom, subscription, team, project, personal, global + href: about-notifications.md - name: Navigate the UI - href: navigating-the-ui.md displayName: interface, personal, team, project, organization, collection, notification, settings + href: navigating-the-ui.md - name: How email recipients are determined - href: concepts-email-recipients.md displayName: subscription, delivery, preference, settings, preferred, team, group, alert + href: concepts-email-recipients.md - name: Manage notifications items: - name: Change your preferred email address - href: change-email-address.md displayName: organization, user, profile, update + href: change-email-address.md - name: Manage personal notifications - href: manage-your-personal-notifications.md displayName: change, update, email, alert, set, subscription + href: manage-your-personal-notifications.md - name: Unsubscribe from default notification - href: unsubscribe-default-notification.md displayName: stop, settings, turn, off, avoid + href: unsubscribe-default-notification.md - name: Manage team, group, Global notifications - href: manage-team-group-global-organization-notifications.md displayName: organization, project, collection, administrator, settings, email, alert + href: manage-team-group-global-organization-notifications.md - name: Limit your emails - href: exclude-self-from-email.md displayName: skip, initiator, trigger, events, subscription, avoid + href: exclude-self-from-email.md - name: Follow work, link work items, use @mentions items: - - name: "Follow work & pull requests" - href: ../../boards/work-items/follow-work-items.md + - name: Follow work & pull requests displayName: notification, subscription, subscribe, user, story, automatic - - name: "Use @mentions to further discussion" - href: at-mentions.md + href: ../../boards/work-items/follow-work-items.md + - name: Use @mentions displayName: add, user, group, conversation, comments, PR, story, directory - - name: "Use #ID to link to work items" - href: add-links-to-work-items.md - displayName: build, commit, pull, request, audit, connect, discussion, changeset, shelveset, comment + href: at-mentions.md + - name: Link work items and other objects + href: ../../boards/backlogs/add-link.md - name: Notifications to third parties items: - name: Send notifications to third-party services (Slack, Teams) - href: integrate-third-party-services.md displayName: service, hooks, integration, endpoint, webhook + href: integrate-third-party-services.md - name: Troubleshooting items: - name: Enable subscription logging for troubleshooting - href: use-subscription-logging.md displayName: diagnostic, information, event, matching - - name: FAQs - href: faq-notifications.yml + href: use-subscription-logging.md + - name: FAQs displayName: recipients, multiple, activity, organization + href: faq-notifications.yml - name: Why am I not getting an email - href: troubleshoot-not-getting-email.md displayName: event, subscription, filter, initiator, team, group, permission + href: troubleshoot-not-getting-email.md - name: Why am I getting this email - href: troubleshoot-unexpected-email.md displayName: group, trigger, subscription, footer + href: troubleshoot-unexpected-email.md - name: Why are my emails delayed - href: troubleshoot-delayed-email.md displayName: expected, notification, statistics, issue, filter, duplicate, subscription, volume - - name: Contacting support - href: troubleshoot-contact-support.md + href: troubleshoot-delayed-email.md + - name: Get support displayName: developer, community, version, platform, event, ID + href: ../../user-guide/provide-feedback.md - name: Reference items: - - name: Default permissions (Security) - href: ../../project/wiki/wiki-readme-permissions.md + - name: Default permissions (Security) displayName: personal, team, project, contributors, access, security, automatic + href: ../../project/wiki/wiki-readme-permissions.md - name: View notification statistics for your organization - href: view-organization-notification-statistics.md displayName: active, subscription, event, initiator, administrator, review + href: view-organization-notification-statistics.md - name: Default notifications - href: oob-built-in-notifications.md displayName: subscription, automatic, alert, role, targeted, trigger + href: oob-built-in-notifications.md - name: Events - href: oob-supported-event-types.md displayName: subscription, automatic, alert, trigger, notification + href: oob-supported-event-types.md diff --git a/docs/organizations/notifications/troubleshoot-contact-support.md b/docs/organizations/notifications/troubleshoot-contact-support.md deleted file mode 100644 index b6449695dd7..00000000000 --- a/docs/organizations/notifications/troubleshoot-contact-support.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Contacting support for notifications -titleSuffix: Azure DevOps -description: Open a support ticket for notifications in Azure DevOps. -ms.subservice: azure-devops-notifications -ms.reviewer: wismythe -ms.author: chcomley -author: chcomley -ms.topic: conceptual -ms.date: 12/30/2019 -monikerRange: '<= azure-devops' ---- - -# Contact support - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -If you've reviewed the troubleshooting sections and can't resolve your issue, [contact Support in the Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). - -When you're contacting support for notification issues, it's good to have answers to the following questions: - -1. What version or platform are you working from. If you don't know, review this section: [What platform or version am I using?](../../user-guide/provide-feedback.md#what-platformversion-am-i-using). -2. When did you start noticing the problem? -3. What emails are you not getting that you expect? -4. Are you getting other types of emails? -5. Is it only you or are others also not getting emails they expect? -6. Can you supply IDs such as work item, build, or pull request IDs of recent events and an approximate time of the event? -7. Can you forward a sample email of a delayed or unexpected email? If not, copy and provide the URL from the View Result on an email. - -It's best to have a recent event reference for the notification in question. Full details about the event and notification delivery are retained for a few days and are beneficial for resolution. You might be asked to reproduce the issue with a new event and provide the following information: -- time/date of the event -- IDs (build, pull request, and so on) associated with the event - -[!INCLUDE [note-smtp-server](includes/note-smtp-server.md)] diff --git a/docs/organizations/notifications/troubleshoot-delayed-email.md b/docs/organizations/notifications/troubleshoot-delayed-email.md index 565fe37c581..e286a0bdca6 100644 --- a/docs/organizations/notifications/troubleshoot-delayed-email.md +++ b/docs/organizations/notifications/troubleshoot-delayed-email.md @@ -18,7 +18,13 @@ monikerRange: '<= azure-devops' You might not receive an expected notification email. Learn how to check the notification statistics. -An email is generated when an [event](oob-supported-event-types.md) occurs within Azure DevOps Services that matches a notification subscription. For more information about notification subscriptions, see the [notifications overview](about-notifications.md). +## Prerequisites + +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] + +## Troubleshoot delayed notifications + +An email generates when an [event](oob-supported-event-types.md) occurs within Azure DevOps Services that matches a notification subscription. For more information about notification subscriptions, see the [notifications overview](about-notifications.md). [!INCLUDE [note-smtp-server](includes/note-smtp-server.md)] @@ -34,4 +40,4 @@ Poorly defined subscription filters or duplicate subscriptions might cause an un ## Contact customer support -If you can't resolve the issue with the previously mentioned steps, consider contacting [customer support](troubleshoot-contact-support.md). +If you can't resolve the issue with the previously mentioned steps, consider contacting [customer support](../../user-guide/provide-feedback.md). diff --git a/docs/organizations/notifications/troubleshoot-not-getting-email.md b/docs/organizations/notifications/troubleshoot-not-getting-email.md index ecd632369bc..a72d0bfac49 100644 --- a/docs/organizations/notifications/troubleshoot-not-getting-email.md +++ b/docs/organizations/notifications/troubleshoot-not-getting-email.md @@ -33,13 +33,19 @@ If you're not receiving an expected notification email, it could be for one of t * You're a member of an Azure Directory (AD) group and the subscription contains a @Me clause * You don't have permission to view the event details, which are included in the email +## Prerequisites + +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] + +## Troubleshoot missing notifications + Complete the following tasks to determine if any resolve the issue. -## Check other email folders +### Check other email folders Ensure the email wasn't delivered to a different email folder, including the junk folder. -## Locate the subscription and ensure it's enabled +### Locate the subscription and ensure it's enabled Go to your personal subscriptions and locate the subscription, which you feel should have produced an email. [Learn how to access to your personal subscriptions](navigating-the-ui.md#open-person-level). @@ -50,38 +56,38 @@ If the subscription is grayed-out in the user interface, then it's disabled. The A default subscription disables when an administrator opts out at the organization or team level, or if you opt out in your personal subscription settings. Custom subscriptions get disabled when an administrator disables the subscription at the organization or team level, or if you disable a personal custom subscription. -## Closely inspect subscription filter conditions +### Closely inspect subscription filter conditions An email is only generated if an Azure DevOps Services event matches _all_ of the filter conditions of the subscription. You can view the filter conditions by selecting the subscription link in the subscription user interface. You can view the filter conditions even if you don't have permission to change them. Closely inspect _all_ filter conditions to see if they matched the Azure DevOps Services event. -## Check the "Skip initiator" option +### Check the "Skip initiator" option The `Skip initiator` checkbox option on a subscription causes the initiator of the Azure DevOps Services event to be excluded from the recipient list of the generated email, while all others receive the event. For example, consider a subscription for a _work item changed_ event. You can choose `Skip initiator` to avoid being emailed for changes you make to the work item. [Learn more about excluding the initiator from notifications](exclude-self-from-email.md). -## Check "Do not deliver" setting for organization +### Check "Do not deliver" setting for organization Go to the organization-level notifications page and select **Settings**. [See how to manage notification settings](manage-team-group-global-organization-notifications.md). If the [delivery setting](#check-do-not-deliver-setting-for-your-team-or-group) is set to `Do not deliver`, then all teams or groups that don't have explicit delivery settings inherit this value. This setting alone doesn't necessarily indicate an email isn't delivered, but it could contribute to the problem. Next, see if a group or team delivery setting inherits this value and blocks delivery to your group or team. -## Check "Do not deliver" setting for your team or group +### Check "Do not deliver" setting for your team or group If the team or group defines a delivery setting for **Deliver to individual members**, it's still possible the team contains other groups. The other groups have a different delivery setting. To learn more about how team membership expands and how some members of the team could receive an email while others don't, see [How email recipients of notifications are determined](concepts-email-recipients.md). -## Check your configured email address +### Check your configured email address -Check if your preferred email address is set to the address you're expecting the email, which is a user profile setting. Hover over :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **your profile** to view your preferred email address. [Learn how to view the configured email address.](../../organizations/settings/set-your-preferences.md). +Check if your preferred email address is set to the address you're expecting the email, which is a user profile setting. Hover over :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **your profile** to view your preferred email address. [Learn how to view the configured email address](../../organizations/settings/set-your-preferences.md). -## Is this a team subscription, which contains a "@Me" filter clause? +### Is this a team subscription, which contains a "@Me" filter clause? If a team or group subscription has an @Me filter clause and the target email recipients are in an AD group, no members of the AD group match the filter clause. AD groups aren't expanded for filter matching. -## Do you have permission to see the event artifact? +### Do you have permission to see the event artifact? Recipients who don't have permission to view the artifact, don't receive an email, which contains event artifact data, such as a work item. The only way to know if an email was _filtered_ is to view notification delivery logs. Learn more about [enabling and retrieving subscription and delivery logging](use-subscription-logging.md). ## Known issue -If a subscription was created or last modified by a user who lost permissions to the project, then the notifications for that subscription won't be delivered and will be filtered silently. +If a subscription was created or last modified by a user who lost permissions to the project, then the notifications for that subscription get filtered silently and don't get delivered. -## Contact customer support +## Find support -If you're not able to resolve the issue with the previous steps, consider contacting [customer support](troubleshoot-contact-support.md) +If you're not able to resolve the issue with the previous steps, consider contacting [customer support](../../user-guide/provide-feedback.md). diff --git a/docs/organizations/notifications/troubleshoot-unexpected-email.md b/docs/organizations/notifications/troubleshoot-unexpected-email.md index 64a1ba955cf..766077c9b91 100644 --- a/docs/organizations/notifications/troubleshoot-unexpected-email.md +++ b/docs/organizations/notifications/troubleshoot-unexpected-email.md @@ -15,25 +15,28 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -If you receive a notification email that you didn't expect, it could be for one of the following reasons: +If you get a notification email that you didn't expect, it could be for one of the following reasons: * The email is sent to a group of which you're a member -* The email was triggered by a different subscription than you expected +* An unexpected subscription triggered the email + +## Prerequisites + +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] Do the following tasks to determine if any resolve the issue: ## Inspect the 'To:' line on the email -Your email address or a group address is on this line. If you're receiving unexpected emails, you may be part of a group that's receiving the email. The subscription administrator might have configured the email delivery preferences to a wider than intended group. +Your email address or a group address appears on this line. If you receive unexpected emails, you might be part of a group receiving the email. The subscription administrator maybe configured the email delivery preferences to a wider group than intended. ## Inspect the footer of the unexpected email -All emails have a footer, which contains a link to view the subscription that triggered the email. Select the link and view the subscription. You received the email because this subscription to which your are subscribed. If it's an organization or team subscription, you can opt out of the subscription. +All emails have a footer containing a link to view the subscription that triggered the email. Select the link to view the subscription. You received the email because you're subscribed to this subscription. If it's an organization or team subscription, you can opt out of it. > [!div class="mx-imgBorder"] ->![Email footer](media/email-footer-view.png) +>![Screenshot shows email footer.](media/email-footer-view.png) ## Contact customer support -If you can't resolve the issue with the previously mentioned steps, consider contacting [customer support](troubleshoot-contact-support.md). +If you can't resolve the issue with the previously mentioned steps, consider contacting [customer support](../../user-guide/provide-feedback.md). diff --git a/docs/organizations/notifications/unsubscribe-default-notification.md b/docs/organizations/notifications/unsubscribe-default-notification.md index 5136094b704..685f92973f1 100644 --- a/docs/organizations/notifications/unsubscribe-default-notification.md +++ b/docs/organizations/notifications/unsubscribe-default-notification.md @@ -1,4 +1,4 @@ ---- +--- title: View subscribed notifications titleSuffix: Azure DevOps description: View your notifications and unsubscribe from a default or built-in notification in Azure DevOps. @@ -15,63 +15,39 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -If you want to stop receiving select email notifications, you can do so by unsubscribing from them. For a description of each default subscription, see [Default notifications](oob-built-in-notifications.md). +If you want to stop receiving specific email notifications, you can do so by unsubscribing from them. For a description of each default subscription, see [Default notifications](oob-built-in-notifications.md). -## View subscriptions +## Prerequisites -::: moniker range=">= azure-devops-2019" +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] + +## View subscriptions 1. From your home page, select :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **Settings**, and then select **Profile**. - ![Open Azure DevOps profile](../../media/open-user-settings-profile-preview.png) + ![Screenshot shows opened Azure DevOps profile.](../../media/open-user-settings-profile-preview.png) 2. Select **Notifications**. Your subscribed notifications show the State as **On**. - ![Notifications turned On](media/notifications-turned-on.png) + ![Screenshot shows notifications turned on.](media/notifications-turned-on.png) The following image indicates a subscription is a default or out-of-the-box (OOB) subscription: - ![OOB notification](media/oob-notification.png) + ![Screenshot shows OOB notification.](media/oob-notification.png) You can't modify an OOB subscription, but you can view its definition from its context menu. -2. To unsubscribe, slide the toggle to the *Off* position. - - In the following image, the "Build completes" subscription is turned off. - - ![Notification is turned off](media/notification-turned-off.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -1. From the web portal, select your initials or picture, and select **Notification settings** from the drop-down menu. - - Open personal notification settings - - Your subscribed notifications show the State as **On**. - - Personal notification subscriptions - - The following image indicates a subscription is a default or out-of-the-box (OOB) subscription: - - ![OOB notification](media/oob-notification.png) - - You can't modify an OOB subscription, but you can view its definition from its context menu. - -2. To unsubscribe, slide the state **On/Off** indicator to the *Off* position. - - In the following image, the "Build completes" subscription is turned off. +3. To unsubscribe, slide the toggle to the *Off* position. - Unsubscribe from Build completes subscription + In the following image, the "Build completes" subscription is turned off. -::: moniker-end + ![Screenshot shows the notification is turned off.](media/notification-turned-off.png) ## Related articles - [Manage personal notifications](manage-your-personal-notifications.md) - [Manage notifications for a team, project, or organization](manage-team-group-global-organization-notifications.md) - [Use @mentions in work items and pull requests](at-mentions.md) -- [About notifications](about-notifications.md) +- [Learn about notifications](about-notifications.md) diff --git a/docs/organizations/notifications/use-subscription-logging.md b/docs/organizations/notifications/use-subscription-logging.md index 1ce9b057ed0..08ad8411b4f 100644 --- a/docs/organizations/notifications/use-subscription-logging.md +++ b/docs/organizations/notifications/use-subscription-logging.md @@ -20,14 +20,15 @@ monikerRange: '<= azure-devops' For certain activities, when you select **Team members by role**, you can choose to have the user that initiated the activity receive a notification. This notification is controlled by the **Skip initiator** checkbox. By default, this box is checked, meaning the user that starts the change isn't notified about it. -Subscription logging is a valuable tool for troubleshooting. It provides diagnostic information from the notifications pipeline and is disabled by default. Once enabled, up to 25 logs, or one hour's worth of logs, are collected for the subscription. +Subscription logging is a valuable tool for troubleshooting. It provides diagnostic information from the notifications pipeline and is disabled by default. Once enabled, up to 25 logs, or one hour's worth of logs, are collected for the subscription. -## Enabling subscription logging +## Prerequisites -> [!IMPORTANT] -> There's a known issue in TFS 2018 Update 2 and TFS 2018 Update 3, where enabling subscription logging for default ![globe](media/oob-notification.png) subscriptions may cause issues with notification delivery. If you're on one of those two versions, it's recommended that you not enable subscription logging for default subscriptions. +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] -Complete the following steps to enable subscription logging: +## Enable subscription logging + +To enable subscription logging, complete the following steps: 1. Enable diagnostics for your organization by entering the following URL in your browser: @@ -36,7 +37,7 @@ Complete the following steps to enable subscription logging: 2. The option _Enable Diagnostics_ appears in the subscription context menu. > [!div class="mx-imgBorder"] ->![Enable subscription logging](media/enable-subscription-logging.png) +>![Screenshot shows enabled subscription logging.](media/enable-subscription-logging.png) ## View subscription diagnostic logs for event matching @@ -66,8 +67,9 @@ Retrieve all notification delivery logs in a given time frame by entering the UR The result is JSON-formatted logging information. +## Related articles - - - - +- [Manage personal notifications](manage-your-personal-notifications.md) +- [Manage notifications for a team, project, or organization](manage-team-group-global-organization-notifications.md) +- [Use @mentions in work items and pull requests](at-mentions.md) +- [Learn about notifications](about-notifications.md) diff --git a/docs/organizations/notifications/view-organization-notification-statistics.md b/docs/organizations/notifications/view-organization-notification-statistics.md index 1274418f42d..269f197129b 100644 --- a/docs/organizations/notifications/view-organization-notification-statistics.md +++ b/docs/organizations/notifications/view-organization-notification-statistics.md @@ -19,6 +19,10 @@ Notification statistics show the top 10 most active subscriptions and top event [!INCLUDE [note-smtp-server](includes/note-smtp-server.md)] +## Prerequisites + +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] + ## View notification statistics for organization 1. [Open organization notifications settings](navigating-the-ui.md#open-org-level). @@ -26,11 +30,18 @@ Notification statistics show the top 10 most active subscriptions and top event 3. Analyze the most active subscriptions and top event initiators. > [!div class="mx-imgBorder"] ->![Organization notification settings delivery option](media/view-organization-notification-stats.png) +>![Screenshot shows organization notification settings delivery option.](media/view-organization-notification-stats.png) + +> [!NOTE] +> Information the user should notice even if skimming. +>* A context menu (`...`) on the most active subscriptions provides the option to edit, disable, or delete the subscription. +>* Both email and service hooks subscriptions are eligible for the most active subscriptions. +>* The integer subscription ID is shown in the description for a custom email subscription. +>* Results aren't a sliding 24-hour window and reset at the beginning of each day (00:00 UTC). -#### Notes: +## Related articles -* A context menu (`...`) on the most active subscriptions provides the option to edit, disable, or delete the subscription -* Both email and service hooks subscriptions are eligible for the most active subscriptions -* The integer subscription ID is shown in the description for a custom email subscription -* Results are not a sliding 24-hour window and reset at the beginning of each day (00:00 UTC) +- [Manage personal notifications](manage-your-personal-notifications.md) +- [Manage notifications for a team, project, or organization](manage-team-group-global-organization-notifications.md) +- [Use @mentions in work items and pull requests](at-mentions.md) +- [Learn about notifications](about-notifications.md) diff --git a/docs/organizations/projects/about-projects.md b/docs/organizations/projects/about-projects.md index cc56b21a405..6d44b118a04 100644 --- a/docs/organizations/projects/about-projects.md +++ b/docs/organizations/projects/about-projects.md @@ -2,44 +2,25 @@ title: About projects and scaling your organization titleSuffix: Azure DevOps ms.custom: engagement-fy23 -description: Understand how to structure your project to support collaboration on building software solutions. +description: Learn about projects and how to structure them to support collaboration on building software solutions. ms.subservice: azure-devops-projects +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '<= azure-devops' -ms.date: 03/23/2023 +monikerRange: "<=azure-devops" +ms.date: 03/12/2025 --- # About projects and scaling your organization -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -A project in Azure DevOps provides a place for users to plan, track progress, and collaborate on building software solutions. A project represents a fundamental container where you can store data and source code. +A project in Azure DevOps provides a space for users to plan, track progress, and collaborate on building software solutions. It serves as a fundamental container for storing data and source code. -When you create your project, Azure DevOps automatically creates a team of the same name, which is sufficient for small organizations. For enterprise-level organizations, it may be necessary to scale up and create more teams and projects. You can have up to 1000 projects within an organization in Azure DevOps. +When you create a project, Azure DevOps automatically creates a team with the same name, which is sufficient for small organizations. For enterprise-level organizations, you might need to scale up by creating more teams and projects. Azure DevOps supports up to 1,000 projects within an organization. -The following diagram shows one project and team versus multiple projects and teams in an organization or collection. This structure allows teams to configure the tools in ways that work for them and complete administrative tasks at the appropriate levels. As your organization grows, your tools can grow to support a [culture of team autonomy and organizational alignment](../../boards/plans/agile-culture.md). - ---- -:::row::: - :::column span="2"::: - **One project + team** - :::column-end::: - :::column span="2"::: - **Multiple projects + teams** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="2"::: - :::image type="content" source="media/about-projects/project-concept.png" alt-text="Conceptual image, Single collection-project-team."::: - :::column-end::: - :::column span="2"::: - :::image type="content" source="media/about-projects/multiple-projects-concept.png" alt-text="Conceptual image, Scaled collection-project-team."::: - :::column-end::: -:::row-end::: ---- +An organization with multiple projects allows teams to configure tools to suit their needs and complete administrative tasks at the appropriate levels. As your organization grows, your tools can scale to support a [culture of team autonomy and organizational alignment](../../boards/plans/agile-culture.md). For more information, see [Work tracking, process, and project limits](../settings/work/object-limits.md) and [Plan your organizational structure](../../user-guide/plan-your-azure-devops-org-structure.md). @@ -48,34 +29,33 @@ For more information, see [Work tracking, process, and project limits](../settin ## Manage work across your organization -When you connect to Azure DevOps, you connect to an organization or project collection. Within that container, one or more projects may be defined. At least one project must be created to use the system. +When you connect to Azure DevOps, you connect to an organization. Within this organization, you can define one or more projects. At least one project must be created to use the system. ::: moniker range="azure-devops" You can scale your organization in the following ways: -- To support different business units, you can add projects -- Within a project, you can add teams -- Add repositories and branches -- To support continuous integration and deployment, you can add agents, agent pools, and deployment pools -- To manage a large number of users, you can manage access through Azure Active Directory +- **Add projects**: Support different business units. +- **Add teams**: Create teams within a project. +- **Add repositories and branches**: Manage your source code. +- **Add agents, agent pools, and deployment pools**: Support continuous integration and deployment. +- **Manage access**: Use Microsoft Entra ID to handle a large number of users. ::: moniker-end ::: moniker range="< azure-devops" You can scale your on-premises Azure DevOps deployment in the following ways: -- To increase performance, you can add server instances -- To support different business units, you can add project collections and projects -- Within a project, you can add teams -- Add repositories and branches -- To support continuous integration and deployment, you can add agents, agent pools, and deployment pools -- To manage a large number of users, you can manage access through Active Directory +- **Add server instances**: Increase performance. +- **Add project collections and projects**: Support different business units. +- **Add teams**: Create teams within a project. +- **Add repositories and branches**: Manage your source code. +- **Add agents, agent pools, and deployment pools**: Support continuous integration and deployment. +- **Manage access**: Use Active Directory to handle a large number of users. ::: moniker-end ## View projects in your organization View the projects defined for your organization by opening the **Projects** page. -::: moniker range=">= azure-devops-2019" 1. Select :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: **Azure DevOps** to open **Projects**. > [!div class="mx-imgBorder"] @@ -84,110 +64,79 @@ View the projects defined for your organization by opening the **Projects** page 2. Choose a project from the list of projects. For more information, see [Create a project](create-project.md). -::: moniker-end - -::: moniker range="tfs-2018" -1. Select :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: **Azure DevOps** to open **Projects**. - > [!div class="mx-imgBorder"] - > ![Screenshot of open Projects button, horizontal nav](../../media/settings/open-project-hub-horz.png) - -2. Choose a project from the projects list. - - > [!div class="mx-imgBorder"] - > ![Choose a project from the set of projects listed.](media/about-projects/projects-hub-horz.png) - -::: moniker-end - - + ::: moniker range="azure-devops" -## Limit user visibility of projects - -By default, users added to an organization can view all organization and project information and settings. +## Limit project visibility -[!INCLUDE [project-scoped-users-important-note](../../includes/project-scoped-users-important-note.md)] - -The **Limit user visibility and collaboration to specific projects** preview feature for the organization limits user access in the following ways. -- Restricts views that display a list of users, list of projects, billing details, usage data, and more information accessed through **Organization settings**. -- Limits the set of users or groups that appear through people-picker search selections and the ability to @mention users. - -[!INCLUDE [project-scoped-users-warning](../../includes/project-scoped-users-warning.md)] - -### Limit access to organization settings - -To limit access to organization settings, [enable the **Limit user visibility and collaboration to specific projects** preview feature](../../project/navigation/preview-features.md#account-level). Users and groups in the "Project-scoped users group" can't access organization settings. They can only see the **Overview** and **Projects** pages and those projects to which they've been added. - -[!INCLUDE [version-all](../security/includes/hidden-security-groups.md)] - -### Limit user visibility within people pickers - -Organizations that are connected to Azure Active Directory (Azure AD) can use people pickers. People pickers support searching all users and groups added to Azure AD, not just those users and groups added to your project. People pickers support the following Azure DevOps functions: -- Select a user identity from a work tracking field, such as "Assigned to" -- Select a user or group with *@mention* in a work item discussion or field, pull request discussion, commit comments, or changeset or shelveset comments -- Select a user or group using *@mention* from a wiki page - -As shown in the following image, start to enter a user in the people picker box until you find a match to the user name or security group. - -> [!div class="mx-imgBorder"] -> ![Screenshot of people picker.](../../organizations/notifications/media/at-mention/identity-selector.png) - -Users and groups within the **Project-scoped users** group can only see and select users and groups in the project they're connected to from a people picker. To scope people pickers for all project members, see [Limit identity search and selection](../../user-guide/manage-organization-collection.md#limit-identity-selection). +By default, users added to an organization can view all organization and project information and settings. For more information, see [Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#limit-user-visibility-for-projects-and-more) and [Change project visibility to public or private](make-project-public.md). ### View historical data -All project members can view identities that were added to a comment, discussion, or assignment. For example, everyone in the project (even users with the new restriction) can still see a user's name assigned to a work item when the user's no longer part of the project. The same is true for @mentions in PRs, comments, discussions, and more. +All project members can view identities added to comments, discussions, or assignments. For example, everyone in the project (even users with new restrictions) can still see a user's name assigned to a work item when the user is no longer part of the project. The same applies to @mentions in PRs, comments, discussions, and more. ::: moniker-end ## Use a single project -We recommend that you use a single project to support your organization or enterprise. A single project minimizes the maintenance of administrative tasks and supports the most optimized and full-flexibility [cross-link object](../../boards/queries/link-work-items-support-traceability.md) experience. +One recommended approach is to use a single project to support your organization or enterprise. A single project can help minimize the maintenance of administrative tasks and provides the most optimized and flexible [cross-link object](../../boards/backlogs/add-link.md) experience. -Even if you have many teams working on hundreds of different applications and software projects, you can easily manage them within a single project. A project serves to isolate data stored within it and you can't easily move data from one project to another. When you move data from one project to another, you typically lose the history associated with that data. +Even if you have many teams working on hundreds of different applications and software projects, you can easily manage them within a single project. A project isolates the data stored within it, and moving data from one project to another results in the loss of associated history. For more information, see [How many projects do you need?](../../user-guide/plan-your-azure-devops-org-structure.md#how-many-projects-do-you-need). -### Add another project +## Add another project ::: moniker range="azure-devops" -You may want to add another project in the following instances: -- To prohibit or manage access to the information contained within a project to select groups -- To support custom work tracking processes for specific business units within your organization -- To support entirely separate business units that have their own administrative policies and administrators -- To support testing customization activities or adding extensions before rolling out changes to the working project -- To support an open-source software (OSS) project +Another feasible approach is to have multiple projects. This approach is recommended if your organization needs to: + +- Prohibit or manage access to the information contained within a project for select groups +- Support custom work tracking processes for specific business units within your organization +- Support entirely separate business units that have their own administrative policies and administrators +- Test customization activities or add extensions before rolling out changes to the working project +- Support an open-source software (OSS) project + ::: moniker-end ::: moniker range="< azure-devops" -You may want to add another project in following instances: -- To prohibit or manage access to the information contained within a project -- To support custom work tracking processes for specific business units within your organization -- To support entirely separate business units that have their own administrative policies and administrators -- To support testing customization activities or adding extensions before rolling out changes to the working project + +You might want to add another project in the following instances: + +- Prohibit or manage access to the information contained within a project +- Support custom work tracking processes for specific business units within your organization +- Support entirely separate business units that have their own administrative policies and administrators +- Test customization activities or add extensions before rolling out changes to the working project + ::: moniker-end ::: moniker range="azure-devops" ## Use private and public projects -You can have both private and public projects. You can also [change the visibility of a project from private to public](make-project-public.md). +You can have both private and public projects. You can also [change the visibility of a project from either one to the other](make-project-public.md). + +**Private projects**: +- Require adding and managing user access. +- Require users to sign in to gain access even for read-only access. +- Provide all project members access to the project and organization information. -**Private projects** require that you add and manage user access. Users must sign in to gain access to a project, even if it's read-only access. All project members have access to the project and organization information. For more information, see [Resources granted to project members](resources-granted-to-project-members.md). +For more information, see [Resources granted to project members](resources-granted-to-project-members.md). -**Public projects** don't require users to sign in to gain read-only access to many of the following services. Public projects provide support to share code with others and to support continuous integration/continuous deployment (CI/CD) of open-source software. +**Public projects**: +- Don't require users to sign in for read-only access to many services. +- Support sharing code with others. +- Support continuous integration/continuous deployment (CI/CD) of open-source software. -For more information about features and access levels for public projects, see [Make a private project public.](make-project-public.md) +For more information, see [Change visibility of a project](make-project-public.md). ## Version control support -Git repositories can be browsed and cloned, but only via HTTPS. -SSH and GVFS endpoints are unavailable. -Clients like Visual Studio and IntelliJ work with the HTTPS clone URL but don't offer the connected experience linking to work items and other collateral. +Git repositories can be browsed and cloned only via HTTPS. SSH and GVFS endpoints are unavailable. Clients like Visual Studio and IntelliJ work with the HTTPS clone URL but don't offer the connected experience linking to work items and other collateral. - + ## Dashboard widget support @@ -195,19 +144,19 @@ The following dashboard widgets don't display any useful information for nonmemb [!INCLUDE [temp](includes/unavailable-widgets.md)] -::: moniker-end +For more information, see [Add widgets to a dashboard](../../report/dashboards/add-widget-to-dashboard.md) and [FAQs about dashboards, charts, and reports](../../report/dashboards/faqs.yml). - +::: moniker-end ## Structure your project -Use the following elements to structure your project to support your business needs. +Use the following elements to structure your project to support your business needs: -- [Create a Git repository](../../repos/git/creatingrepo.md) for each subproject or application, or [create root folders within a TFVC repository](../../repos/tfvc/branch-folders-files.md) for each subproject. If you're using TFVC and heading toward a combined project model, create root folders for different teams and projects, just as you would create separate repos in Git. Secure folders as needed and control which segments of the repo you're actively using with workplace mappings. +- [Create a Git repository](../../repos/git/creatingrepo.md) for each subproject or application, or [create root folders within a TFVC repository](../../repos/tfvc/branch-folders-files.md) for each subproject. If you're using TFVC and heading toward a combined project model, create root folders for different teams and projects, just as you would create separate repos in Git. Secure folders as needed and control which segments of the repo you're actively using with workplace mappings. - [Define area paths](../settings/set-area-paths.md) to support different subprojects, products, features, or teams. - [Define iteration paths (also known as sprints)](../settings/set-iteration-paths-sprints.md) that can be shared across teams. - [Add a team](../../organizations/settings/add-teams.md) for each product team that develops a set of features for a product. Each team you create automatically creates a security group for that team, which you can use to manage permissions for a team. For more information, see [Portfolio management](../../boards/plans/portfolio-management.md). -- [Grant or restrict access to select features and functions](../security/restrict-access.md) using custom security groups. +- [Manage access to specific features and functions](../security/restrict-access.md) using custom security groups. - [Create query folders](../../boards/queries/organize-queries.md) to organize queries for teams or product areas into folders. - [Define or modify notifications](../../organizations/notifications/about-notifications.md) set at the project level. @@ -215,25 +164,12 @@ Use the following elements to structure your project to support your business ne You can configure and customize most services and applications to support your business needs or the way your teams work. Within each project, you can do the following tasks. For a comprehensive view of which resources can be configured, see [About team, project, and organizational-level settings](../settings/about-settings.md). -::: moniker range=">= azure-devops-2019" - **Dashboards**: Each team can [configure their set of dashboards](../../report/dashboards/dashboards.md) to share information and monitor progress. - **Source control**: For each [Git repository](../../repos/git/index.yml), you can apply branch policies and define branch permissions. For TFVC repositories, you can [set check-in policies](../../repos/tfvc/add-check-policies.md). - **Work tracking**: You can add fields, change the workflow, add custom rules, and add custom pages to the work item form of most work item types. You can also add custom work item types. For more information, see [Customize an inheritance process](../settings/work/inheritance-process-model.md). - **Azure Pipelines**: You can fully customize your build and release pipelines, and define build steps, release environments, and deployment schedule. For more information, see [Build and release](../../pipelines/index.yml). - **Azure Test Plans**: You can define and configure test plans, test suites, test cases, and test environments. You can also add test steps within your build pipelines. For more information, see [Exploratory and manual testing](../../test/index.yml) and [continuous testing for your builds](../../pipelines/ecosystems/dotnet-core.md#run-your-tests). -::: moniker-end - -::: moniker range="tfs-2018" -- **Dashboards**: Each team can [configure their set of dashboards](../../report/dashboards/dashboards.md) to share information and monitor progress. -- **Source control**: For each [Git repository](../../repos/git/index.yml), you can apply branch policies and define branch permissions. For TFVC repositories, you can [set check-in policies](../../repos/tfvc/add-check-policies.md). -- **Work tracking**: You can add fields, change the workflow, add custom rules, and add custom pages to the work item form of most work item types. You can also add custom work item types. For more information, see [Customize the on-premises XML process model](../../reference/on-premises-xml-process-model.md). -- **Build and release**: You can fully customize your build and release pipelines, and define build steps, release environments, and deployment schedule. For more information, see [Build and release](../../pipelines/index.yml). -- **Test**: You can define and configure test plans, test suites, test cases, and test environments. You can also add test steps within your build pipelines. For more information, see [Exploratory and manual testing](../../test/index.yml) and [continuous testing for your builds](../../pipelines/ecosystems/dotnet-core.md#run-your-tests). -::: moniker-end - - - ## Add a team As your organization grows, you can add teams equipped with configurable Agile tools to meet each team's workflow. For more information, see the following articles. @@ -258,14 +194,173 @@ Aside from connecting via a web browser, you can connect to a project from the f - [Test & Feedback extension](../../test/request-stakeholder-feedback.md) - [Microsoft Feedback Client](/previous-versions/azure/devops/project/feedback/give-feedback) - For more information, see [Compatibility with Azure DevOps Server versions](/azure/devops/server/compatibility). +## Key concepts + +Use the following index to quickly access concepts and tasks related to managing projects and teams. + +::: moniker range="azure-devops" + +:::row::: + :::column span=""::: +- [About projects](about-projects.md) +- [About teams](../settings/about-teams-and-settings.md) +- [Access levels](../security/access-levels.md) +- [Area paths](../settings/about-areas-iterations.md) +- [Dashboards](../../report/dashboards/overview.md) +- [Notifications and subscriptions](../../organizations/notifications/about-notifications.md) +- [GitHub connections](../../boards/github/connect-to-github.md) +- [Iteration paths](../settings/about-areas-iterations.md) + :::column-end::: + :::column span=""::: +- [Permissions](../security/about-permissions.md) +- [Process (Inherited)](../settings/work/inheritance-process-model.md) +- [Project resources viewable by members](resources-granted-to-project-members.md) +- [Project Wiki](../../project/wiki/provisioned-vs-published-wiki.md) +- [Project-level permissions](../security/permissions.md#project-level-permissions) +- [Project-level security groups](../security/permissions.md#project-level-groups) + :::column-end::: + :::column span=""::: +- [Project and process object limits](../settings/work/object-limits.md) +- [Projects page](../../project/navigation/work-across-projects.md) +- [Public vs private projects](about-projects.md) +- [Security groups](../security/about-permissions.md) +- [Service hooks](../../service-hooks/overview.md) +- [Service visibility](../settings/set-services.md) +- [Summary page](project-vision-status.md) + :::column-end::: +:::row-end::: + +::: moniker-end + +::: moniker range="< azure-devops" + +:::row::: + :::column span=""::: +- [About projects](about-projects.md) +- [About teams](../settings/about-teams-and-settings.md) +- [Access levels](../security/access-levels.md) +- [Area paths](../settings/about-areas-iterations.md) +- [Dashboards](../../report/dashboards/overview.md) +- [Notifications and subscriptions](../../organizations/notifications/about-notifications.md) +- [GitHub connections](../../boards/github/connect-to-github.md) +- [Iteration paths](../settings/about-areas-iterations.md) + :::column-end::: + :::column span=""::: +- [Permissions](../security/about-permissions.md) +- [Process (Inherited)](../settings/work/inheritance-process-model.md) +- [Process (On-premises XML)](../../reference/on-premises-xml-process-model.md) +- [Project and process object limits](../settings/work/object-limits.md) +- [Project resources viewable by members](resources-granted-to-project-members.md) +- [Project Wiki](../../project/wiki/provisioned-vs-published-wiki.md) + :::column-end::: + :::column span=""::: +- [Project-level permissions](../security/permissions.md#project-level-permissions) +- [Project-level security groups](../security/permissions.md#project-level-groups) +- [Projects page](../../project/navigation/work-across-projects.md) +- [Security groups](../security/about-permissions.md) +- [Service hooks](../../service-hooks/overview.md) +- [Service visibility](../settings/set-services.md) +- [Summary page](project-vision-status.md) + :::column-end::: +:::row-end::: + +::: moniker-end + +## User and administrative tasks + +Several of the following tasks require permissions granted to a member of the Project Administrators group or a team administrator. + +::: moniker range="azure-devops" + +:::row::: + :::column span=""::: +- [Add Git repository](../../repos/git/create-new-repo.md) +- [Add project administrators](../security/change-project-level-permissions.md) +- [Add project dashboard](../../report/dashboards/dashboards.md#add-a-dashboard) +- [Add project members](../security/add-users-team-project.md) +- [Add security groups](../security/add-ad-aad-built-in-security-groups.md) +- [Add team administrators](../settings/add-team-administrator.md) +- [Add team members](../security/add-users-team-project.md) +- [Add/manage service hooks](../../service-hooks/overview.md) +- [Connect to a project](connect-to-projects.md) +- [Connect to GitHub](../../boards/github/connect-to-github.md) + :::column-end::: + :::column span=""::: +- [Create project](create-project.md) +- [Delete project](delete-project.md) +- [Edit project Summary](project-vision-status.md) +- [Enable/disable project services](../settings/set-services.md) +- [Export list of projects](create-project.md) +- [Export list of teams](../settings/add-teams.md#list-teams) +- [Manage notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) +- [Manage your project](../../user-guide/project-admin-tutorial.md) +- [Navigate the Web portal](../../project/navigation/index.md) +- [Remove team](../settings/rename-remove-team.md) + :::column-end::: + :::column span=""::: +- [Rename project](create-project.md) +- [Rename team](../settings/rename-remove-team.md) +- [Restore project](delete-project.md#restore-a-deleted-project) +- [Change user access levels](../accounts/add-organization-users.md) +- [Search across projects](../../project/search/get-started-search.md) +- [Set area paths](../settings/set-area-paths.md) +- [Set favorites](../../project/navigation/set-favorites.md) +- [Set iteration paths](../settings/set-iteration-paths-sprints.md) +- [Set project-level permissions](../security/change-project-level-permissions.md) +- [Set project visibility](../projects/make-project-public.md) +- [Switch project, repository, team](../../project/navigation/go-to-project-repo.md) + :::column-end::: +:::row-end::: + +::: moniker-end + +::: moniker range="< azure-devops" + +:::row::: + :::column span=""::: +- [Add Git repository](../../repos/git/create-new-repo.md) +- [Add project administrators](../security/change-project-level-permissions.md) +- [Add project members](../security/add-users-team-project.md) +- [Add security groups](../security/add-ad-aad-built-in-security-groups.md) +- [Add team members](../security/add-users-team-project.md) +- [Add team administrators](../settings/add-team-administrator.md) +- [Add/manage service hooks](../../service-hooks/overview.md) +- [Change access levels](../security/change-access-levels.md) +- [Connect to a project](connect-to-projects.md) +- [Connect to GitHub](../../boards/github/connect-to-github.md) + :::column-end::: + :::column span=""::: +- [Create project](create-project.md) +- [Delete project](delete-project.md) +- [Edit project Summary](project-vision-status.md) +- [Enable/disable project services](../settings/set-services.md) +- [Manage notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) +- [Manage your project](../../user-guide/project-admin-tutorial.md) +- [Navigate the Web portal](../../project/navigation/index.md) +- [Remove team](../settings/rename-remove-team.md) + :::column-end::: + :::column span=""::: +- [Rename project](create-project.md) +- [Rename team](../settings/rename-remove-team.md) +- [Restore project](delete-project.md#restore-a-deleted-project) +- [Search across projects](../../project/search/get-started-search.md) +- [Set area paths](../settings/set-area-paths.md) +- [Set favorites](../../project/navigation/set-favorites.md) +- [Set iteration paths](../settings/set-iteration-paths-sprints.md) +- [Set project-level permissions](../security/change-project-level-permissions.md) +- [Switch project, repository, team](../../project/navigation/go-to-project-repo.md) + :::column-end::: +:::row-end::: + +::: moniker-end + ## Frequently asked questions (FAQs) ### Q: Can I move or transfer a project to another organization or collection? -**A:** Yes, but not without losing data. You can manually copy resources and leave some behind, or use a third-party tool, such as [OpsHub Visual Studio Migration Utility](https://www.opshub.com/products/opshub-visual-studio-migration-utility/), which copies data using the REST APIs. +**A:** Yes, but not without losing data. You can manually copy resources and leave some behind, or use a non-Microsoft tool. ### Q: What programmatic tools support projects? @@ -278,6 +373,6 @@ You can also use the [**az devops project** CLI](/cli/azure/devops/project). ## Related articles - [Get started as an administrator](../../user-guide/project-admin-tutorial.md) -- [Web portal navigation](../../project/navigation/index.md) -- [What do I get with a project?](../../user-guide/services.md?toc=/azure/devops/organizations/projects/toc.json&bc=/azure/devops/organizations/projects/breadcrumb/toc.json) +- [Navigate the web portal](../../project/navigation/index.md) +- [Understand what you get with a project](../../user-guide/services.md?toc=/azure/devops/organizations/projects/toc.json&bc=/azure/devops/organizations/projects/breadcrumb/toc.json) - [Understand differences between Azure DevOps](../../user-guide/about-azure-devops-services-tfs.md?toc=/azure/devops/organizations/projects/toc.json&bc=/azure/devops/organizations/projects/breadcrumb/toc.json) diff --git a/docs/organizations/projects/connect-to-projects.md b/docs/organizations/projects/connect-to-projects.md index a5846a80947..b38a3838783 100644 --- a/docs/organizations/projects/connect-to-projects.md +++ b/docs/organizations/projects/connect-to-projects.md @@ -1,21 +1,21 @@ --- title: Connect to project from browser/supported client titleSuffix: Azure DevOps -description: Learn how to connect a client to the cloud service Azure DevOps or on-premises +description: Learn how to connect a browser or client, like Visual Studio, to a project in Azure DevOps. ms.subservice: azure-devops-projects ms.topic: quickstart ms.assetid: 1372e56c-b34f-42c2-b72c-94b57620c75c ms.author: sdanie author: steved0x -monikerRange: '<= azure-devops' -ms.date: 12/16/2022 +monikerRange: "<=azure-devops" +ms.date: 11/11/2024 --- -# Connect to a project in Azure DevOps +# Connect to a project -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Learn how to connect to a project to share code, build apps, track work, and collaborate with team members. You can use any of the following clients: +Learn how to connect to a project from a client, to share code, build apps, track work, and collaborate with team members. You can connect to a project from any of the following clients: - [Web portal](#web-portal) - [Visual Studio or Team Explorer](#visual-studio) @@ -23,78 +23,38 @@ Learn how to connect to a project to share code, build apps, track work, and col - [IntelliJ with the Azure DevOps Services Plugin for IntelliJ](/previous-versions/azure/devops/all/java/download-intellij-plug-in) - [Visual Studio Code](/previous-versions/azure/devops/all/java/vscode-extension) -A project defines a process and data storage in which you manage your software projects from planning to deployment. When you connect to a project, you connect to an organization or project collection. One or more projects may be defined within a collection. There must be at least one project. For more information, see [About projects and scaling your organization](about-projects.md). +A project defines a process and data storage in which you manage your software projects from planning to deployment. When you connect to a project, you connect to an organization or project collection. For more information, see [About projects and scaling your organization](about-projects.md). ## Prerequisites -- If you don't have a project yet, [create one](create-project.md). - -- If you need to add a team, see [Add teams](../../organizations/settings/add-teams.md). If you don't have access to the project, [get invited to the team](../security/add-users-team-project.md). - -- From each of these clients, you can switch context to a different project and connect as a different user. If you work remotely, configure your client to [connect to an Azure DevOps Proxy Server](#proxy). - -- To get started with a code base, [set up Git](../../repos/git/gitquickstart.md) or [set up TFVC](../../repos/tfvc/index.yml). +| Category | Requirements | +|--------------|-------------| +|**Project membership** |[Project member](../projects/create-project.md). | +|**Remote work** |If you work remotely, configure your client to [connect to an Azure DevOps Proxy Server](#proxy). From each client, you can switch context to a different project and connect as a different user. | +|**Code base setup**| [Set up Git](../../repos/git/gitquickstart.md) or [Set up Team Foundation Version Control (TFVC)](../../repos/tfvc/index.yml).| ## Connect from the web portal -1. If you're not a member of a security group, ask your Project Administrator to add you. - -1. Open a browser and enter a URL that uses the following form: - - ::: moniker range="azure-devops" - 
      https://dev.azure.com/OrganizationName/ProjectName
      - ::: moniker-end - - ::: moniker range=">= azure-devops-2019 < azure-devops" - 
      http://ServerName/DefaultCollection/ProjectName
      - - For example, to connect to the server named **FabrikamPrime**, type: **http://FabrikamPrime/DefaultCollection**. - ::: moniker-end - ::: moniker range="< azure-devops-2019" - 
      http://ServerName:8080/tfs/DefaultCollection/ProjectName
      - - For example, to connect to the server named **FabrikamPrime**, type: **http://FabrikamPrime:8080/tfs/DefaultCollection**. - - The default Port is 8080. If you don't use default values, specify the port number and directory for your server. - ::: moniker-end - -1. When you access the server for the first time, a Windows Identity dialog box appears. Enter your credentials and choose **OK**. - - > [!TIP] - > If you select **Remember me**, you won't have to enter your credentials the next time you connect. - -1. Choose your project, team, or page of interest. - - ::: moniker range=">= azure-devops-2019" - - From the project summary page, hover over a service and then choose the page you want. To choose another project, choose **Azure DevOps**. ![Azure DevOps logo](../../media/icons/project-icon.png) - - > [!div class="mx-imgBorder"] - > ![Choose a service page, horizontal nav](media/connect-projects/project-summary-page-choose-app-vert.png) - - ::: moniker-end - - ::: moniker range="tfs-2018" - - From the project summary page, hover over a service and then choose the page you want. To choose another project, choose the ![Azure DevOps logo](../../media/icons/project-icon.png) Azure DevOps logo. - - > [!div class="mx-imgBorder"] - > ![Choose a service page, horizontal nav](media/connect-projects/project-summary-page-choose-app-horz.png) +::: moniker range="azure-devops" +- Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). +::: moniker-end - ::: moniker-end +::: moniker range=" < azure-devops" +- Sign in to your project (```http://ServerName/{DefaultCollection}/{Project_Name}```). +::: moniker-end -To learn more about each page and the tasks you can do, see [Web portal navigation](../../project/navigation/index.md). +For more information, see [Web portal navigation](../../project/navigation/index.md). ### Sign in with different credentials -1. Open your profile menu and choose **Sign out**. +1. Open your profile menu and select **Sign in with a different account**. - > [!div class="mx-imgBorder"] - > ![Sign out](media/sign-out.png) + > [!div class="mx-imgBorder"] + > ![Screenshot of Sign in with a different account button selected.](media/sign-out.png) 1. Choose **Sign in** and enter your credentials. @@ -102,7 +62,7 @@ To learn more about each page and the tasks you can do, see [Web portal navigati Open the web portal from the home page. -![Connect to the web portal](media/connect-tp-open-web-portal.png) +![Screenshot showing Connecting to the web portal.](media/connect-tp-open-web-portal.png) @@ -110,112 +70,142 @@ Open the web portal from the home page. If you haven't already, [download and install a version of Visual Studio](https://visualstudio.microsoft.com/downloads/download-visual-studio-vs). -If you're not a member of an Azure DevOps security group, [get added to one](../security/add-users-team-project.md). Check with a team member. You'll need the names of the server, project collection, and project to connect to. +If you're not a member of an Azure DevOps security group, [get added to one](../security/add-users-team-project.md). Check with a team member. You need the names of the server, project collection, and project to connect to. + +# [Visual Studio 2022](#tab/visual-studio-2022) + +1. Select the **Manage Connections** icon in Team Explorer, and then **Connect to a Project**. + + :::image type="content" source="media/team-explorer-connect-to-project-visual-studio-2022.png" alt-text="Screenshot of Connect to projects highlighted for selection."::: + + All the projects that you can connect to are displayed, along with the repos in those projects. + + ![Screenshot of Connect to a Project dialog box.](media/connect-projects/connect-to-a-project-and-github.png) + +2. Select **Add Azure DevOps Server** to connect to a project in Azure DevOps Server. Enter the URL to your server and select **Add**. + + ![Screenshot of server URL field to connect to.](media/connect-projects-tfs/vs2017_add_tfs_server.png) + +3. Select a project from the list and then select **Connect**. # [Visual Studio 2019](#tab/visual-studio-2019) ### Visual Studio 2019 -1. Select the **Manage Connections** button in Team Explorer to open the **Connect** page. Choose **Connect to a Project** to select a project to connect to. +1. Select the **Manage Connections** icon in Team Explorer, and then choose **Connect to a Project**. - ![connect to projects](media/te-connect-page-connect-to-project-vs2019.png) + ![Screenshot of Connect to projects selection.](media/te-connect-page-connect-to-project-vs2019.png) - **Connect to a Project** shows the projects you can connect to, along with the repos in those projects. + All the projects that you can connect to are displayed, along with the repos in those projects - ![Connect to a Project dialog box](media/connect-projects/connect-to-a-project-and-github.png) + ![Screenshot of Connect to a Project dialog box.](media/connect-projects/connect-to-a-project-and-github.png) -1. Select **Add Azure DevOps Server** to connect to a project in Azure DevOps Services. Enter the URL to your server and select **Add**. +2. Select **Add Azure DevOps Server** to connect to a project in Azure DevOps Services. Enter the URL to your server and select **Add**. - ![ALM\_EXL\_AddServer](media/connect-projects-tfs/vs2017_add_tfs_server.png) + ![Screenshot of field to enter for server URL.](media/connect-projects-tfs/vs2017_add_tfs_server.png) -1. Select a project from the list and select **Connect**. +3. Select a project from the list and select **Connect**. # [Visual Studio 2017](#tab/visual-studio-2017) ### Visual Studio 2017 - + 1. Select the **Manage Connections** button in Team Explorer to open the **Connect** page. Choose the **Connect to Team Project** link to select a project to connect to. - ![connect to projects](media/te-connect-page-connect-to-team-project.png) + ![Screenshot of Connect to projects button to select.](media/te-connect-page-connect-to-team-project.png) - **Connect to a Project** shows the projects you can connect to, along with the repos in those projects. + All the projects that you can connect to are displayed, along with the repos in those projects - ![Connect to a Project dialog box](media/connect-projects-tfs/vs2017_connect_dialog.png) + ![Screenshot of Connect to Project dialog box.](media/connect-projects-tfs/vs2017_connect_dialog.png) -1. Select **Add Server** to connect to a project in Team Foundation Server. Enter the URL to your TFS server and select **Add**. +2. Select **Add Server** to connect to a project. Enter the URL to your server and select **Add**. - ![ALM\_EXL\_AddServer](media/connect-projects-tfs/vs2017_add_tfs_server.png) + ![Screenshot of Enter server URL window.](media/connect-projects-tfs/vs2017_add_tfs_server.png) -1. Select a project from the list and select **Connect**. +3. Select a project from the list and select **Connect**. # [Visual Studio 2015](#tab/visual-studio-2015) ### Visual Studio 2015 - - + + + -1. Select the **Manage Connections** button in Team Explorer to open the **Connect** page. Choose **Connect to Team Project** to select a different organization, TFS, or project to connect to. +1. Select the **Manage Connections** button in Team Explorer to open the **Connect** page. Choose **Connect to Team Project** to select a different organization or project to connect to. - ![connect to projects](media/te-connect-page-connect-to-team-project.png) + ![Screenshot of icon and selection to Connect to projects.](media/te-connect-page-connect-to-team-project.png) -1. Select the projects to work on. +2. Select the projects to work on. - ![Select the projects to work on.](media/connect-projects-tfs/IC671574.png) + ![Screenshot showing selection of projects to work on.](media/connect-projects-tfs/IC671574.png) - If it's your first time connecting, add TFS to the list of recognized servers. + If it's your first time connecting, add Azure DevOps to the list of recognized servers. - ![ALM\_EXL\_AddServer](media/connect-projects-tfs/IC658167.png) + ![Screenshot of URL entry field for server.](media/connect-projects-tfs/IC658167.png) -If you selected just one project, you'll see the **Home** page for that project. The pages differ based on the resources enabled and the source control system selected for your project. +If you selected just one project, you see the **Home** page for that project. The pages differ based on the resources enabled and the source control system selected for your project. Team Explorer displays the **Home** page for that project. The pages that appear differ based on the resources enabled and the source control system selected for your project. -> [!div class="mx-tdBreakAll"] > |Home page with Git |Home page with TFVC | > |-------------|----------| -> |Team Explorer Home page with Git as source control|Team Explorer Home page w/ TFVC as source control| +> |:::image type="content" source="media/te-home-page-git-repo.png" alt-text="Screenshot of Team Explorer Home page with Git as source control.":::|:::image type="content" source="media/te-home-page-tfvc-repo.png" alt-text="Screenshot of Team Explorer Home page w/ TFVC as source control.":::| -To learn more about each page and the tasks you can do, see [Navigate in Visual Studio Team Explorer](../../user-guide/work-team-explorer.md). +For more information, see [Navigate in Visual Studio Team Explorer](../../user-guide/work-team-explorer.md). -Your client remembers the set of connections you've configured. You can switch from one project to another from the **Connect** page. +Your client remembers the set of connections you configure. You can switch from one project to another from the **Connect** page. --- ### Change sign-in credentials +# [Visual Studio 2022](#tab/visual-studio-2022) + +### Visual Studio 2022 + +1. Select the **Manage Connections** icon in Team Explorer, and then **Connect to a Project**. + + :::image type="content" source="media/team-explorer-connect-to-project-visual-studio-2022.png" alt-text="Screenshot showing Connect to projects highlighted for selection."::: + +2. Select a different user or select **Add an account** to access a project using different credentials. + + ![Screenshot of Connect with VS using different credentials to sign in.](media/connect-projects-tfs/choose-different-user-vs2017.png) + +3. Sign in with a Microsoft or GitHub account associated with an Azure DevOps project. + # [Visual Studio 2019](#tab/visual-studio-2019) ### Visual Studio 2019 -1. From **Connect**, choose the **Connect to a Project** link to sign in with different credentials. +1. Select the **Manage Connections** icon in Team Explorer, and then choose **Connect to a Project**. - ![Sign in with different credentials.](media/te-connect-page-connect-to-project-vs2019.png) + ![Screenshot of Sign in with different credentials.](media/te-connect-page-connect-to-project-vs2019.png) -1. Select a different user or select **Add an account** to access a project using different credentials. +2. Select a different user or select **Add an account** to access a project using different credentials. - ![Connect with VS using different credentials to sign in](media/connect-projects-tfs/choose-different-user-vs2017.png) + ![Screenshot of Connect with VS using different credentials to sign in.](media/connect-projects-tfs/choose-different-user-vs2017.png) -1. Sign in using an account that is associated with an Azure DevOps project, either a valid Microsoft account or GitHub account. +3. Sign in using an account that is associated with an Azure DevOps project, either a valid Microsoft account or GitHub account. # [Visual Studio 2017](#tab/visual-studio-2017) ### Visual Studio 2017 - - + + 1. From **Connect**, choose **Connect to Team Project** to sign in with different credentials. - ![Sign in with different credentials.](media/te-connect-page-connect-to-team-project.png) + ![Screenshot of Sign in with different credentials page.](media/te-connect-page-connect-to-team-project.png) 1. Select a different user from the drop-down or select **Add an account** to access a project using different credentials. - ![Connect with VS 2017 using different credentials to sign in](media/connect-projects-tfs/choose-different-user-vs2017.png) + ![Screenshot of Connect with VS 2017 using different credentials to sign in.](media/connect-projects-tfs/choose-different-user-vs2017.png) -1. Sign in using a valid Microsoft account that is associated with an Azure DevOps Services or TFS project. +2. Sign in using a valid Microsoft account associated with an Azure DevOps project. # [Visual Studio 2015](#tab/visual-studio-2015) @@ -223,13 +213,13 @@ Your client remembers the set of connections you've configured. You can switch f 1. From **Connect**, choose **Connect to Team Project** to sign in with different credentials. - ![Sign in with different credentials.](media/te-connect-page-connect-to-team-project.png) + ![Screenshot of Sign in with different credentials window.](media/te-connect-page-connect-to-team-project.png) - The **Switch User** link appears only when you're actively connected to a project on Azure DevOps Services. + The **Switch User** link appears only when you're actively connected to a project on Azure DevOps. - ![Connect to Team Foundation Server dialog box](media/connect-projects-tfs/IC719958.png) + ![Screenshot of the Connect to Team Foundation Server dialog box.](media/connect-projects-tfs/IC719958.png) -1. Sign in using a valid Microsoft account that is associated with Azure DevOps Services or a TFS project. +2. Sign in using a valid Microsoft account associated with Azure DevOps. --- @@ -239,48 +229,42 @@ You can run Visual Studio with credentials different from your current Windows u Select Shift and right-click *devenv.exe*, then select **Run as different user**. -![Context menu for Visual Studio devenv.exe](media/connect-projects-tfs/IC719959.png) +![Screenshot of Context menu for Visual Studio devenv.exe.](media/connect-projects-tfs/IC719959.png) ### User accounts and licensing for Visual Studio -To connect to a project, you need your user account added to the project. The **Organization owner** for Azure DevOps Services or a member of the **Project Administrators** group usually adds user accounts. To learn more, see [Add organization users and manage access](../accounts/add-organization-users.md) or [Add or remove users or groups, manage security groups](../security/add-remove-manage-user-group-security-group.md). +To connect to a project, you need your user account added to the project. The **Organization owner** for Azure DevOps or a member of the **Project Administrators** group usually adds user accounts. For more information, see [Add organization users and manage access](../accounts/add-organization-users.md) or [Add or remove users or groups, manage security groups](../security/add-remove-manage-user-group-security-group.md). ::: moniker range="azure-devops" Azure DevOps Services provides access to the first five account users free. After that, you need to [pay for more users](../billing/buy-basic-access-add-users.md). ::: moniker-end -::: moniker range="tfs-2018" - -For on-premises TFS, each user account must have a TFS client access license (CAL). All Visual Studio subscriptions and paid Azure DevOps Services users include a TFS CAL. Find out more about licensing from the [Team Foundation Server pricing page](https://visualstudio.microsoft.com/team-services/tfs-pricing). - -::: moniker-end - -You can also provide access to Stakeholders in your organization who have limited access to select features as described in [Work as a Stakeholder](../security/get-started-stakeholder.md). +You can also provide access to Stakeholders in your organization with limited access to specific features as described in [Work as a Stakeholder](../security/get-started-stakeholder.md). ## Configure Visual Studio to connect to Azure DevOps Proxy Server -If your remote team uses a [Azure DevOps Proxy Server](/azure/devops/server/install/install-proxy-setup-remote) to cache files, you can configure Visual Studio to connect through that proxy server and download files under Team Foundation version control. +If your remote team uses an [Azure DevOps Proxy Server](/azure/devops/server/install/install-proxy-setup-remote) to cache files, you can configure Visual Studio to connect through that proxy server and download files under Team Foundation version control. -1. First, make sure that you've connected to Azure DevOps Server as described [in the previous section](#visual-studio). +1. Make sure you're connected to Azure DevOps, as described [in the previous section](#visual-studio). -1. From the Visual Studio **Tools** menu, select **Options**, then select **Source Control** > **Plug-in Selection**. Select **Visual Studio Team Foundation Server**. +2. From the Visual Studio **Tools** menu, select **Options**, and then select **Source Control** > **Plug-in Selection**. Select **Visual Studio Team Foundation Server**. - ![Plug-in Selection page, Options dialog box](media/connect-projects-tfs/plug-in-selection-for-visual-studio.png) + ![Screenshot of Plug-in Selection page, Options dialog box.](media/connect-projects-tfs/plug-in-selection-for-visual-studio.png) -1. For **Visual Studio Team Foundation Server**, enter the name and port number for the Azure DevOps Proxy Server. Select **Use SSL encryption (https) to connect**. +3. For **Visual Studio Team Foundation Server**, enter the name and port number for the Azure DevOps Proxy Server. Select **Use SSL encryption (https) to connect**. - ![VS TFVC proxy configuration page, Options dialog](media/connect-projects-tfs/visual-studio-proxy-server-options.png) + ![Screenshot of VS TFVC proxy configuration page, Options dialog.](media/connect-projects-tfs/visual-studio-proxy-server-options.png) - Make sure you specify the port number that your administrator assigned to TFS Proxy. + Make sure you specify the port number that your administrator assigned to Azure DevOps Proxy. To associate a file type with a compare or merge tool, see [Associate a file type with a file-comparison tool](../../repos/tfvc/associate-file-type-file-comparison-tool.md) or [Associate a file type with a merge tool](../../repos/tfvc/associate-file-type-merge-tool.md). ### Requirements and client compatibility -Some tasks or features aren't available when you connect to a later version of Azure DevOps Server than your client supports. For more information, see [client compatibility](/azure/devops/server/compatibility). +Some tasks or features aren't available when you connect to a later version of Azure DevOps than your client supports. For more information, see [client compatibility](/azure/devops/server/compatibility). ### Determine your platform version @@ -288,13 +272,12 @@ See [Look up your Azure DevOps platform and version](../../user-guide/lookup-pla ## Next steps -Learn more about how to: +> [!div class="nextstepaction"] +> [Get started with Agile tools to plan and track work](../../boards/get-started/what-is-azure-boards.md). + +## Related articles - [Work in web portal](../../project/navigation/index.md) - [Work in Team Explorer](../../user-guide/work-team-explorer.md) - [Work in Office Excel or Project](../../boards/backlogs/office/track-work.md) - [Troubleshoot connection](../../user-guide/troubleshoot-connection.md) - -If all you need is a code repository and bug tracking solution, then start with the [Get Started with Azure Repos](../../repos/git/gitquickstart.md) and [Manage bugs](../../boards/backlogs/manage-bugs.md). - -To start planning and tracking work, see [Get started with Agile tools to plan and track work](../../boards/get-started/what-is-azure-boards.md). diff --git a/docs/organizations/projects/create-project.md b/docs/organizations/projects/create-project.md index bd9782f2bc6..cdcc070ef1f 100644 --- a/docs/organizations/projects/create-project.md +++ b/docs/organizations/projects/create-project.md @@ -1,29 +1,24 @@ --- title: Create a project titleSuffix: Azure DevOps -ms.custom: seodec18, contperf-fy20q4, devx-track-azurecli, engagement-fy23 +ms.custom: devx-track-azurecli, engagement-fy23 description: Learn how to create a new project where your team can plan, track progress, and collaborate on building software solutions. ms.assetid: 21F3C364-34F4-41B0-9EFC-6D4A141D81E0 ms.subservice: azure-devops-projects ms.topic: how-to ms.author: chcomley author: chcomley -monikerRange: '<= azure-devops' -ms.date: 11/04/2022 +monikerRange: "<=azure-devops" +ms.date: 03/11/2025 --- - # Create a project in Azure DevOps -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Create an Azure DevOps project to establish a repository for source code and to plan and track work. You can manage and structure your project to support your business needs. Each project provides boundaries to isolate data from other projects. For more information, see [About projects and scaling your organization](about-projects.md). - -[!INCLUDE [version-selector](../../includes/version-selector-minimize.md)] +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -If you don't want to create a project in Azure DevOps, you can create [Azure DevOps Projects](/azure/devops-project/). +Create an Azure DevOps project to set up a source code repository and organize your work. You can tailor and manage your project to meet your business requirements. Each project isolates its data from other projects. For more information, see [About projects and scaling your organization](about-projects.md). - +[!INCLUDE [version-selector](../../includes/version-selector.md)] ::: moniker range="< azure-devops" > [!NOTE] @@ -34,21 +29,26 @@ If you don't want to create a project in Azure DevOps, you can create [Azure Dev ::: moniker range="azure-devops" -- You need an organization before you can create a project. If you haven't created an organization yet, create one by following the instructions in [Sign up, sign in to Azure DevOps](../../user-guide/sign-up-invite-teammates.md), which also creates a project. Or see [Create an organization or project collection](../accounts/create-organization.md). -- You must be a member of the Project Collection Administrators group or have the collection-level "Create new projects" permission set to *Allow*. If you're the Organization owner, you're automatically added to the Project Collection Administrators group. For more information, see [Change project collection-level permissions](../security/change-organization-collection-level-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Organization** |An [organization](../accounts/create-organization.md). | +|**Permissions** |Member of the [Project Collection Administrators](../security/change-organization-collection-level-permissions.md) group or the collection-level "Create new projects" permission set to *Allow*. Organization owners are automatically members of this group.| + ::: moniker-end ::: moniker range=" < azure-devops" -- You need a project collection before you can create a project. If you don't have one, [create a project collection now](/azure/devops/server/admin/manage-project-collections?view=azure-devops-2020#create-a-project-collection&preserve-view=true). -- You must be a member of the Project Collection Administrators group or have the "Create new projects permission" set to *Allow*. For more information, see [Change project collection-level permissions](../security/change-organization-collection-level-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Project collection**| A [project collection](/azure/devops/server/admin/manage-project-collections?view=azure-devops-2020#create-a-project-collection&preserve-view=true).| +|**Permissions** |Be a member of the [Project Collection Administrators](../security/change-organization-collection-level-permissions.md) group or have the collection-level "Create new projects" permission set to *Allow*. Organization owners are automatically members of this group.| ::: moniker-end ::: moniker range="azure-devops" > [!IMPORTANT] -> To create a public project or to make a private project public, see the information in [Make a private project public](../projects/make-project-public.md). You must enable additional policy settings to work with public projects. Then, return to this article to create your project. +> To create a public project or [make a private project public](../projects/make-project-public.md), enable other policy settings to work with public projects, and then return to this article to create your project. ::: moniker-end @@ -56,7 +56,7 @@ If you don't want to create a project in Azure DevOps, you can create [Azure Dev ::: moniker range="azure-devops" -You can create up to 1000 projects within an organization in Azure DevOps. For more information, see [Work tracking, process, and project limits](../settings/work/object-limits.md). +You can create up to 1,000 projects within an organization in Azure DevOps. For more information, see [Work tracking, process, and project limits](../settings/work/object-limits.md). ::: moniker-end @@ -71,9 +71,9 @@ There isn't a limit on the number of projects that you can create within a proje #### [Browser](#tab/browser) -::: moniker range=">= azure-devops-2020" +::: moniker range=">= azure-devops" -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. Select **New project**. @@ -87,7 +87,7 @@ There isn't a limit on the number of projects that you can create within a proje For more information, see [Choosing the right version control for your project](../../repos/tfvc/comparison-git-tfvc.md) and [Choose a process](../../boards/work-items/guidance/choose-process.md). > [!div class="mx-imgBorder"] - > ![Screenshot of create new project form.](media/create-project/create-new-project-form-new-nav.png) + > ![Screenshot of create new project form.](media/create-project/create-new-project-form-new-nav-2.png) When you choose public visibility, anyone on the internet can view your project. With private visibility, only users you give access to can view your project. For more information about features and access levels for public projects, see [Make a private project public](make-project-public.md). If the **Public** option isn't available, you need to change the policy. @@ -104,15 +104,15 @@ There isn't a limit on the number of projects that you can create within a proje - **Pipelines**: Define a pipeline. See [Azure Pipelines documentation](../../pipelines/index.yml). - **Test Plans**: Define test plans and test suites. See [Create test plans and test suites](../../test/create-a-test-plan.md). - **Artifacts**: Discover, install, and publish NuGet, npm, and Maven packages. See the [Azure Artifacts overview](../../artifacts/start-using-azure-artifacts.md). - - **manage your services**: Disable the visibility of services. See [Turn a service on or off](../settings/set-services.md). + - **Manage your services**: Disable the visibility of services. See [Turn a service on or off](../settings/set-services.md). ::: moniker-end -::: moniker range="azure-devops-2019" +::: moniker range="< azure-devops" -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your collection (```https:///```). -2. Select **New project**. +2. Select **New project**. You can also [create a project from a process](../settings/work/manage-process.md). > [!div class="mx-imgBorder"] > ![Screenshot of listed projects and highlighted New projects button.](media/create-project/select-new-project.png) @@ -124,7 +124,7 @@ There isn't a limit on the number of projects that you can create within a proje For more information, see [Choosing the right version control for your project](../../repos/tfvc/comparison-git-tfvc.md) and [About processes and process templates](../../boards/work-items/guidance/choose-process.md). > [!div class="mx-imgBorder"] - > ![Screenshot of create new project form.](media/create-project/create-new-project-form-new-nav.png) + > ![Screenshot of create new project form.](media/create-project/create-new-project-form-new-nav-2.png) When you choose public visibility, anyone on the internet can view your project. With private visibility, only people who you give access to can view your project. For more information about public projects, see [Create a public project in your organization](../projects/create-project.md). If the **Public** option isn't available, you need to change the policy. @@ -144,22 +144,6 @@ There isn't a limit on the number of projects that you can create within a proje ::: moniker-end -::: moniker range="tfs-2018" - -1. Select ![Azure DevOps logo.](../../media/icons/project-icon.png) **Azure DevOps** to open the **Projects** page. Then, select **New project**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of highlighted New Project button.](media/create-project/projects-hub-horz-new-project.png) - -2. Enter a name for your new project, initial source control type, and work item process. - - Azure DevOps displays the project summary. For more information, see [Share your project, view project activity](project-vision-status.md). - - > [!div class="mx-imgBorder"] - > ![Screenshot of new project created.](media/create-project/new-team-project-tfs-2017.png) - -::: moniker-end - #### [Team Explorer](#tab/team-explorer) > [!NOTE] @@ -169,7 +153,7 @@ There isn't a limit on the number of projects that you can create within a proje #### [Azure DevOps CLI](#tab/azure-devops-cli) - + ::: moniker range="azure-devops" @@ -192,7 +176,7 @@ az devops project create --name - **description**: Optional. Short description of the project, enclosed in quotes. - **open**: Optional. Once the command creates a project, it opens in the default web browser. - **org**: Optional. Azure DevOps organization URL. Required if not configured as default or picked up by using `git config`. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Example: `https://dev.azure.com/MyOrganizationName/`. -- **process**: Optional. The process model to use, such as *Agile*, *Basic*, *Scrum*, *CMMI*, or other custom process model. Agile is the default. To learn more, see [About process customization and inherited processes](../settings/work/inheritance-process-model.md). +- **process**: Optional. The process model to use, such as *Agile*, *Basic*, *Scrum*, *CMMI*, or other custom process model. Agile is the default. For more information, see [About process customization and inherited processes](../settings/work/inheritance-process-model.md). - **source-control**: Optional. Type of source control repository to create for the project: *git* (default) or *tfvc*. If not, name or ID of the project. Example: `--project "Fabrikam Fiber"`. - **visibility**: Optional. Project visibility. Accepted values: *private* (default), *public*. @@ -232,25 +216,6 @@ View a list of projects from your web browser. ::: moniker-end -::: moniker range=">= tfs-2018 <= azure-devops-2019" - -1. To view the projects defined for a collection, select ![Azure DevOps logo](../../media/icons/project-icon.png) **Azure DevOps** to open the **Projects** page. - -2. Choose the collection to view the list of projects. The page lists the last two or three projects you connected to at the upper screen. Choose any project to connect to that project. - - > [!div class="mx-imgBorder"] - > ![Screenshot of projects list.](media/create-project/list-projects-2019.png) - -Or - -1. Select **Admin settings** and then choose **Projects** to list all projects. - - > [!div class="mx-imgBorder"] - > ![Screenshot of selected Admin settings and Projects.](media/create-project/list-projects-admin-settings-2019.png) - - You can choose a project to open project settings for that project on this page. For more information, see [About settings at the user, team, project, or organization-level](../settings/about-settings.md). Or, you can [rename a project](rename-project.md) or [delete a project](delete-project.md). - -::: moniker-end #### [Team Explorer](#tab/team-explorer) @@ -272,8 +237,6 @@ From Team Explorer, you can view a list of projects by connecting to an organiza #### [Azure DevOps CLI](#tab/azure-devops-cli) - - ::: moniker range="azure-devops" ### List projects with CLI @@ -315,7 +278,7 @@ aba0ed07-3174-4793-9f2c-d2c5fa6b44d7 MyPublicProject Public ``` - + ### Show project information in the web portal @@ -352,24 +315,19 @@ ID Name Visibility Process * * * - - - ## Add a repository to your project -You can add Git (distributed) or TFVC (centralized) repositories to your project. You can create many Git repositories, but only a single TFVC repository for a project. More steps to address permissions may be required. For more information, see [Use Git and TFVC repos in the same project](../../repos/git/team-projects.md). +You can add Git (distributed) or TFVC (centralized) repositories to your project. You can create many Git repositories, but only a single TFVC repository for a project. More steps to address permissions might be required. For more information, see [Use Git and TFVC repos in the same project](../../repos/git/team-projects.md). ## Next steps > [!div class="nextstepaction"] -> [Structure your project](about-projects.md#project-structure) +> [Structure your project](about-projects.md#structure-your-project) ## Related articles - [Rename a project](rename-project.md) -- [Save project data](save-project-data.md) - [Delete a project](delete-project.md) -- [Restore a project](restore-project.md) - [Get started as an administrator](../../user-guide/project-admin-tutorial.md) - [Install extensions](../../marketplace/install-extension.md) @@ -387,29 +345,9 @@ A: If you receive an error message that states you don't have permission to crea ### Q: How do I resolve Error TF30321? -A: **Error TF30321: The name you entered is already used for another project on the Team Foundation Server** indicates that you should use a different name for your project. The name you entered is either in active use or has undergone partial deletion, but not full deletion. - -Even when you've deleted a project, you may get the same name error. Some components could be created or deleted even though others aren't. In this event, you can't reuse the name associated with the project. - -::: moniker range="tfs-2018" - -To verify project deletion or remove remaining components associated with a partially deleted project, use the [Delete project command line tool(TFSDeleteProject)](/azure/devops/server/command-line/tfsdeleteproject-cmd). Then try again to create the project with the same name. +A: **Error TF30321: The name you entered is already used for another project on the Team Foundation Server** indicates that you should use a different name for your project. The name you entered is either in active use or is partially deleted, but not fully deleted. -Even with troubleshooting, you might not be able to use the same name. Some components of the deleted project could be scheduled for deletion but not yet deleted. - -### Q: How do I resolve an error message related to a plug-in? - -A: The process template used to create the project contains several XML plug-in files. If one of these files contains a format or other error, an error message appears. - -Review the project creation log to determine the plug-in that caused the error. After you discover the problem, you can either contact the developer or vendor that provided the plug-in, or attempt to fix the problem yourself. For more information, see [Customize a process template](../../reference/process-templates/customize-process.md). - -### Q: How do I resolve a problem connecting to a server? - -A: If you receive an error message about a problem connecting to a server, retrieving information from a server, or checking permissions to create projects, an incorrectly configured server in the deployment could have caused it. This problem is especially common after a server move, failover, or other maintenance activity. - -Contact the TFS system administrator and request that they verify the server configuration. - -::: moniker-end +Even when you deleted a project, you might get the same name error. Some components could be created or deleted even though others aren't. In this event, you can't reuse the name associated with the project. ::: moniker range="< azure-devops" ### Q: How do I add my custom process template to the list? @@ -421,9 +359,9 @@ A: [Upload your template](../../boards/work-items/guidance/manage-process-templa A: The log file is stored in $:\\Users\\*user name*\\AppData\\Local\\Temp and labeled vso\_TeamProjectCreation\_*yyyy\_mm\_dd\_hh\_mm\_ss*.log. -The log shows each action taken by the wizard at the time of the failure and may include more details about the error. You can review the log entries to find network or file related issues by searching for **Exception** or **Error**. +The log shows each action taken by the wizard at the time of the failure and might include more details about the error. You can review the log entries to find network or file related issues by searching for **Exception** or **Error**. ### Q: How do I add SQL Server Reporting services? A: See [Add reports to a project](/previous-versions/azure/devops/report/admin/add-reports-to-a-team-project). -::: moniker-end +::: moniker-end \ No newline at end of file diff --git a/docs/organizations/projects/delete-project.md b/docs/organizations/projects/delete-project.md index 255ecbf7b5a..06de966eb2e 100644 --- a/docs/organizations/projects/delete-project.md +++ b/docs/organizations/projects/delete-project.md @@ -1,49 +1,67 @@ --- -title: Delete, remove project +title: Delete, remove, restore project titleSuffix: Azure DevOps -ms.custom: seodec18, contperf-fy21q3, engagement-fy23 -description: Delete or remove a project from your organization in Azure DevOps. +ms.custom: engagement-fy23 +description: Delete or remove a project from your organization in Azure DevOps. Restore a recently deleted project. ms.assetid: f8638962-1732-4600-94bb-3dc34e0ac48e -ms.subservice: azure-devops-organizations +ms.subservice: azure-devops-projects ms.topic: conceptual ms.author: chcomley author: chcomley -monikerRange: '<= azure-devops' -ms.date: 08/16/2021 +monikerRange: "<=azure-devops" +ms.date: 03/11/2025 --- # Delete a project -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)]  +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -If you have a project that's no longer valid, you can delete it from your organization or collection in Azure DevOps. Or, if you are migrating from an on-premises Azure DevOps Server to Azure DevOps Services, you'll need to delete project(s). Deleting projects also helps to simplify navigating to only those projects that are in use. - -::: moniker range=" > tfs-2018" +If a project becomes obsolete, you can [delete it](#delete-project) from your organization or collection in Azure DevOps. If you're migrating from an on-premises Azure DevOps Server to Azure DevOps Services, you might also need to delete the project. Removing unused projects can enhance navigation by limiting it to only those projects that are currently in use. > [!CAUTION] -> Deleting projects from the web portal generate a soft-delete where projects get permanently deleted if not restored within 28 days. Projects deleted from the on-premises Azure DevOps Administration Console undergo a hard delete and cannot be restored. For more information on restoring projects, see [Restore a project](restore-project.md). If you want to access project data while the project is deleted (without [restoring it](restore-project.md)) you should [save project data](save-project-data.md). +> - Soft-deleted projects from the web portal are permanently removed if not restored within 28 days. +> - In rare cases, our deletion process might take up to 70 days due to backend retries and the need to delete data from multiple sources. +> - Hard-deleted projects from the on-premises Azure DevOps Administration Console can't be restored. +> For more information, see [Restore a project](#restore-a-deleted-project) and [Save project data](#save-project-data). + +## Prerequisites -::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="azure-devops" -> [!Caution] -> Deleting projects in TFS 2018 is permanent. All projects deleted from the on-premises TFS 2018 undergo a hard delete and cannot be restored. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.
      - **Delete team project** permission set to **Allow**. For more information, see [View project-level permissions](../security/view-permissions.md#view-project-level-permissions).| +|**Optional**| [Save project data](#save-project-data) before deleting a project if you want to access project data without restoring it.| ::: moniker-end -## Prerequisites +::: moniker range=" < azure-devops" -::: moniker range="azure-devops" +| Category | Requirements | +|--------------|-------------| +|**Permissions**| **Delete team project** permission set to **Allow**. For more information, see [View permissions](../security/view-permissions.md).| +|**Optional**| [Save project data](#save-project-data), as deleting a project results in irreversible data loss.| -- You must be a member of the **Project Administrators** group or have the project-level **Delete team project** permission set to **Allow**. Organization owners are automatically members of this group. For more information, see [Change project-level permissions](../security/change-project-level-permissions.md). +::: moniker-end -::: moniker-end +## Save project data -::: moniker range=" < azure-devops" +Use the following procedures to save data that users most care about, such as source code, build data, and work items. This procedure is optional and something you might consider before you delete a project. -- You must be a member of the **Project Administrators** group or have the **Delete team project** permission set to **Allow**. For more information, see [Change project-level permissions](../security/change-project-level-permissions.md). +* **Source code and custom build templates:** Download your files as a zip file. Select ![Repository actions](../../media/icons/actions-icon.png) for the repository, file, or folder and select **Download as Zip**. Or, select :::image type="icon" source="../../boards/media/icons/download-icon.png" border="false"::: **Download** to download either all of the files in the currently selected folder, or the currently selected file. -::: moniker-end + > [!div class="mx-imgBorder"] + > ![Screenshot of Downloading code.](media/public/download-zip-file.png) + + This process doesn't save any change history or links to other artifacts. If you use Git, [clone your repositories](../../repos/git/gitquickstart.md) to retain the full project history and all the branches. + +* **Build data**: To save logs and data in your drop build folders, see [View build results](/previous-versions/ms181733(v=vs.140)). + +* **Work item tracking data:** Create a work item query and open it [using Excel](../../boards/backlogs/office/bulk-add-modify-work-items-excel.md). Save the Excel spreadsheet. + + This process doesn't save any attachments, change history, or links to other artifacts. + +For more information, see our [Data Protection Overview](../../organizations/security/data-protection.md). ::: moniker range=">= azure-devops-2020" @@ -53,47 +71,30 @@ If you have a project that's no longer valid, you can delete it from your organi #### [Browser](#tab/browser) -Use your web browser to perform a soft-delete. After 28 days, projects will be permanently deleted if not restored within that time. +Use your web browser to perform a soft-delete. After 28 days, projects are permanently deleted if not restored within that time. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). 2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - ![Select Open Organization settings.](../../media/settings/open-admin-settings-vert.png) + ![Screenshot of selection, Organization settings.](../../media/settings/open-admin-settings-vert.png) -3. Select **Projects**, and then check one or more projects to delete. Select **Delete**. +3. Select **Projects**, check one or more projects to delete, and then select **Delete**. - :::image type="content" source="media/delete-project/delete-multiple-projects.png" alt-text="In Organization settings, select Projects, check each project, delete"::: + :::image type="content" source="media/delete-project/delete-project-organization-settings.png" alt-text="Screenshot of sequence selected Projects, check each project, and delete."::: 4. Confirm deletion by entering the project name, and then select **Delete** in the popup screen. - ![popup confirmation delete project screen](media/delete-project/confirm-delete-project.png) - -::: moniker-end - - -::: moniker range=" tfs-2018" - -1. Choose the :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: gear icon to open **Collection Settings**. - - > [!div class="mx-imgBorder"] - > ![Organization settings, Policy page, Security policies](../../media/settings/open-organization-settings.png) - -2. From there, you can choose a page. Settings are organized based on the service they support. - - > [!div class="mx-imgBorder"] - > ![Organization settings, Projects](../../media/settings/open-admin-settings-horizontal.png) + ![Screenshot of popup confirmation delete project screen.](media/delete-project/confirm-delete-project.png) ::: moniker-end Your project is deleted and can be restored up to 28 days afterward. Your deleted project is removed from your projects list. - #### [Administration Console](#tab/admin-console) -       ::: moniker range="azure-devops" @@ -102,26 +103,23 @@ The Administration Console is only supported for on-premises Azure DevOps Server ::: moniker-end ::: moniker range="< azure-devops" - Use the Azure DevOps Administration Console to perform a hard delete. Projects are permanently deleted and not subject to restoration. -Using the administration console, you can delete a project from a project collection. Afterwards, you'll need to manually delete any associated reports and SharePoint project portal. Or, you can use the [TFSDeleteProject command line tool](/azure/devops/server/command-line/tfsdeleteproject-cmd) to delete all artifacts. +Using the administration console, you can delete a project from a project collection. Afterwards, you need to manually delete any associated reports and SharePoint project portal. Or, you can use the [TFSDeleteProject command line tool](/azure/devops/server/command-line/tfsdeleteproject-cmd) to delete all artifacts. 1. If you're not a member of one or more of the following administrator groups, [get permissions now](/azure/devops/server/admin/add-administrator): - Team Foundation Administrators group (required). - - SQL Server System Administrators group (required). - - Farm Administrators group for SharePoint Products (required when your deployment uses SharePoint Products). 2. Open the administration console and delete the project from its project collection. - :::image type="content" source="media/delete-project/delete-project-2019-1.png" alt-text="Admin Console, Delete project."::: + :::image type="content" source="media/delete-project/delete-project-2019-1.png" alt-text="Screenshot of Admin Console, Delete project."::: 3. Choose whether to delete external data associated with the project and then start the delete action. - :::image type="content" source="media/delete-project/confirm-deletion.png" alt-text="Delete team projects dialog."::: + :::image type="content" source="media/delete-project/confirm-deletion.png" alt-text="Screenshot of Delete team projects dialog."::: 4. (Optional) To review the status of the delete action, open the **Status** tab. @@ -160,7 +158,6 @@ az devops project delete --id 9a61d475-b1a7-4da7-b9db-80df15ac985c --yes [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] *** - ::: moniker range="< azure-devops" @@ -168,59 +165,119 @@ az devops project delete --id 9a61d475-b1a7-4da7-b9db-80df15ac985c --yes If your project used SQL Server reporting and you didn't delete external artifacts, you can delete the reports using SQL Server Report Manager. From the project collection page, delete the folder that corresponds to the deleted project. -![context menu with delete command](media/delete-project/ic686857.png) +![Screenshot of the context menu with delete command.](media/delete-project/ic686857.png) ::: moniker-end -::: moniker range="tfs-2018" +## Restore a deleted project -## Remove the project portal +If you inadvertently delete a project in Azure DevOps, you can restore it within 28 days of its deletion. -If your project had a project portal, all links to that portal get removed from TWA and Team Explorer. But, the SharePoint site or website that acted as the portal doesn't get deleted. If you want to delete the portal, you must do so manually after the project has been deleted. See [How to: Create, Edit, and Delete Windows SharePoint Services Sites](/previous-versions/visualstudio/visual-studio-2010/ms253110(v%3dvs.100)). +::: moniker range="azure-devops" -::: moniker-end +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). +2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. -## FAQs + ![Screenshot showing the gear icon, Organization settings.](../../media/settings/open-admin-settings-vert.png) -See the following frequently asked questions about deleting projects in Azure DevOps. +3. Select **Overview**, and then scroll down to "recently deleted projects." -### Q: After deleting one project, why do work items in a remaining project still have links to the deleted project work items? + ![Screenshot that shows recently deleted projects.](media/delete-project/recently-deleted-projects.png) -A: Work items get deleted within 24 hours after your project is deleted. +4. Highlight the project you want to restore, and then select **Restore**. + + ![Screenshot showing highlighted project, and Restore button.](media/restore-project/recently-deleted-projects.png) +::: moniker-end -::: moniker range=" > tfs-2018" +::: moniker range=" [!WARNING] +> To restore a project with an existing name, rename the project first. To rename the project, enter the following text in the request body: `"name":"new name"`. -A: Review the status and log files for the delete action. Open the **Status** tab and for **Deleted**, review the additional information in parentheses, and take the indicated action. +1. Open a browser window and enter a URL that uses the following form: -- (**Processing**) means that the process has started and is in progress. + 'http://ServerName:8080/tfs/DefaultCollection/ProjectName' -- (**Pending**) means that the deletion process has started from a client application. The deletion might be in progress or might have failed. Because the process was started from a client application, the server can't accurately report the status of the deletion. + For example, to connect to the server named **FabrikamPrime**, enter: 'http://FabrikamPrime:8080/tfs/'. - If a project deletion remains pending for a long time, try to delete the project again from the administration console. + The default Port is 8080. Specify the port number and directory for your server if defaults aren't used. -- (**Failed**) means that the deletion process started but didn't successfully finish. The log file contains specific information about the failure. +2. Get a list of deleted projects using the following request: - Review the information about the failure, and then try to delete the project again. + ``` + GET http://ServerName:8080/tfs/DefaultCollection/_apis/projects?stateFilter= + deleted&api-version=5.0-preview.3 + ``` - If partial data remains, you can also use the [TFSDeleteProject](/azure/devops/server/command-line/tfsdeleteproject-cmd) command-line tool. +3. Restore a deleted project using the following request: -::: moniker-end + ``` + PATCH http://ServerName:8080/tfs/DefaultCollection/_apis/projects/{projectId}? + api-version=5.0-preview.3 + ``` + Request body + + ``` + { + "state" : "wellFormed" + } + ``` + +### Restore project with PowerShell + +1. Execute the following PowerShell script to get a list of deleted projects and make sure to update `$collectionUrl`. + + ``` + $collectionUrl = "https://localhost/defaultcollection" + (irm -Uri "$collectionUrl/_apis/projects?stateFilter= + deleted&api-version=5.0-preview.3" -UseDefaultCredentials).value + ``` + +2. Use the following script to restore a project. Be sure to update `$collectionUrl` and `$projectName`. + + ``` + $collectionUrl = "https://localhost/defaultcollection" + $projectName = 'Project1' + $project = (irm -Uri "$collectionUrl/_apis/projects?stateFilter= + deleted&api-version=5.0-preview.3" -UseDefaultCredentials).value + | where {$_.name -eq $projectName} + irm -Uri ($project.url + "?api-version=5.0-preview.3") + -UseDefaultCredentials -Method PATCH -Body '{"state":"wellFormed"}' + -ContentType 'application/json' + ``` + +Your project and associated data are restored. + +## FAQs + +See the following frequently asked questions about deleting projects in Azure DevOps. + +### Q: After you delete one project, why do work items in a remaining project still have links to the deleted project work items? + +A: Work items get deleted within 24 hours after your project is deleted. + +### Q: I deleted a project in Azure DevOps, but in Visual Studio Team Explorer it's still there, what do I do? + +A: Wait 28 days before the project is permanently deleted. ## Related articles - [Create a project](create-project.md) -- [Restore a project](restore-project.md) +- [Restore a project](delete-project.md#restore-a-deleted-project) - [Delete a project with REST API](/rest/api/azure/devops/core/projects/delete) -- [TFSDeleteProject command line tool](/azure/devops/server/command-line/tfsdeleteproject-cmd) - +- [ Use the TFSDeleteProject command line tool](/azure/devops/server/command-line/tfsdeleteproject-cmd) diff --git a/docs/organizations/projects/make-project-public.md b/docs/organizations/projects/make-project-public.md index 2b21361e1f8..4cd275f98db 100644 --- a/docs/organizations/projects/make-project-public.md +++ b/docs/organizations/projects/make-project-public.md @@ -1,7 +1,7 @@ --- -title: Make your private project public -titleSuffix: Azure DevOps Services Public Project -description: Change your project visibility from private to public and learn about access levels and feature restrictions for public projects. +title: Change project to public or private +titleSuffix: Azure DevOps Services Public and Private Projects +description: Change your project visibility (private or public) and learn about access levels and feature restrictions for public projects. ms.subservice: azure-devops-public-projects ms.assetid: ms.reviewer: @@ -9,50 +9,57 @@ ms.author: chcomley author: chcomley ms.topic: quickstart monikerRange: 'azure-devops' -ms.date: 11/07/2022 +ms.date: 11/11/2024 --- -# Make your private project public +# Change project visibility to public or private [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -When you choose to make a project public, all of its contents are included. You can't choose specific repositories, area paths, or build folders to keep private. +In this article, learn how to change the visibility of your project to public or private. -Access is limited when the user isn't signed in. These users are also referred to as anonymous users or public users. Also, there are users, ones who are signed in to Azure DevOps, but aren't members of a project. Both of these types of users are granted limited, read-only access as indicated in the following table. +When you switch a private project to public visibility, all its contents become public. It's not possible to selectively keep certain repositories, area paths, or build folders private. -All members of the project experience the following effects when a private project is made public: +## Security -* Permissions marked **Deny** aren't honored. The permissions automatically granted to a non-member act as a "floor" on the capabilities that can be assigned to any member in the project. -* If a build pipeline specifies a Project Collection scope, it runs with Project scope instead, which reduces the risks of a malicious user obtaining the build service's authentication token. -* Stakeholders have full access to **Repos** or **Code** features in public projects, but they have no access in private projects. -* Stakeholders have full access to **Boards** or **Work** in public projects, but they have partial access in private projects. For more information, see [Stakeholder access quick reference](../security/stakeholder-access.md). -* Basic + Test Plans users can view and run tests from **Test Plans** or **Test**. Basic users need to upgrade their access level to Basic + Test Plans to get full access, which includes capability to create test plans and add test cases. +When you switch a private project to public, project members experience the following changes: -|Hub / Settings |Non-member access |Stakeholder access |Basic access|Reader access |Contributor access |Project Admin access | +* **Permissions**: Permissions marked **Deny** aren't recognized. Nonmembers are automatically given a minimum level of capabilities that can be assigned to any project member. +* **Build pipelines**: If a build pipeline is set to *Project Collection* scope, it runs with a *Project* scope instead, reducing the risk of malicious users gaining access to the build service's authentication token. +* **Stakeholders**: + - **Repos**: Stakeholders have full access to these features in public projects but have no access in private projects. + - **Boards**: Stakeholders have full access in public projects but only partial access in private projects. For more information, see [Stakeholder access quick reference](../security/stakeholder-access.md). +* **Basic + Test Plans users**: Basic + Test Plans users can view and run tests from Test Plans. Basic users can upgrade their access level to Basic + Test Plans to gain full access, including the capability to create test plans and add test cases. + +### Access + +Access is restricted for users who aren't signed in (anonymous/public users) and users who are signed in, but aren't members of a project (nonproject members). Both categories of users, referred to as nonmembers, are given limited, read-only access as outlined in the following table. + +|Hub / Settings |Nonmember access |Stakeholder access |Basic access|Reader access |Contributor access |Project administrator access | |---------|---------|---------|---------| -|**Dashboards** | read (many widgets aren't available) | partial | full | read | read-write | read-write-administer | +|**Dashboards** | read, + many widgets aren't available | partial | full | read | read-write | read-write-administer | |**Wiki** | read | full | full | read | read-write | read-write-administer | -|**Boards (Work)** | read | partial | full | read | read-write | read-write-administer | -|**Repos (Code)** | read | full | full | read | read-write | read-write-administer | -|**Pipelines (Build and Release)** | read | full | full | read | read-write | Read-Write-Administer | -|**Test Plans** | no access | no access | partial access (see last bullet above table) | read |read-write | Read-Write-Administer | -|**Notifications** | no access | Full | Full | Read | read-write | read-write-administer | +|**Boards** | read | partial | full | read | read-write | read-write-administer | +|**Repos** | read | full | full | read | read-write | read-write-administer | +|**Pipelines** | read | full | full | read | read-write | read-write-administer | +|**Test Plans** | no access | no access | partial access | read |read-write | read-write-administer | +|**Notifications** | no access | full | full | read | read-write | read-write-administer | |**Search** | full| full | full | full | full | full | -|**Settings** | No access| Full | Full | Read | Read | Read-Write-Administer | +|**Settings** | no access| full | full | read | read | read-write-administer | ## Prerequisites -- You must have an organization created in Azure DevOps. If you don't have one, [do that now](../../user-guide/sign-up-invite-teammates.md). -- You must be a member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. -- Understand [access levels and unavailable features for public projects](#access-levels-and-unavailable-features-for-public-projects). -- Be aware of [partial migration options](#partial-migration). -- Review items in the [migration checklist](#migration-checklist). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +|**Organization** |An [organization](../../user-guide/sign-up-invite-teammates.md).| +|**Tasks**| - Understand [access levels and unavailable features for public projects](../security/access-levels.md).
      - Awareness of [partial migration options](#partial-migration).
      - Review items in the [migration checklist](#migration-checklist). | ### Migration checklist -Most existing private projects contain a large amount of historical data. Old work items, early commits, and previous build pipelines might have content you don't want to share publicly. +Most private projects contain a large amount of historical data. Old work items, early commits, and previous build pipelines might contain information you don't want to share publicly. -The following checklist indicates those items you may want to review before making a project public. It also provides tips for migrating work items or files to a new project so that you can expose only current and future content. +The following checklist indicates those items you might want to review before you make a project public. It also provides tips for migrating work items or files to a new project so that you can expose only current and future content. :::row::: :::column span="1"::: @@ -90,8 +97,7 @@ The following checklist indicates those items you may want to review before maki :::column span="2"::: :::image type="icon" source="../../media/icons/checkmark.png" border="false":::Confirm that your work items, even closed ones, don't contain sensitive details: undisclosed security flaws, credentials, and customer data. Work-items maintain their history when they're migrated from a private to public project. All discussions and descriptions are available. Check that none contains problematic speech. -:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Confirm that none of your area paths have special, locked-down security settings. Denied permissions aren't enforced in a public project, so restricted area paths become public. If you aren't comfortable exposing the whole work item database, there are migration options. -For more information, see [Instructions for moving work items](#move-work-items). +:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Confirm that none of your area paths have special locked-down security settings. Denied permissions aren't enforced in a public project, so restricted area paths become public. :::column-end::: :::row-end::: :::row::: @@ -101,7 +107,7 @@ For more information, see [Instructions for moving work items](#move-work-items) :::column span="2"::: :::image type="icon" source="../../media/icons/checkmark.png" border="false":::Confirm that you have no sensitive details in your repositories' history: unpatched security bugs, credentials, and code you don't have the right to distribute. -:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Be aware that all file contents and commit messages are available. Check that none contains problematic speech. If you aren't comfortable exposing an entire repository, you can migrate the tip to another project. +:::image type="icon" source="../../media/icons/checkmark.png" border="false":::All file contents and commit messages are available. Check that none contains problematic speech. If you aren't comfortable exposing an entire repository, you can migrate the tip to another project. For more information, see [Instructions for a tip migration](#migrate-git-tip-only). :::column-end::: :::row-end::: @@ -112,7 +118,7 @@ For more information, see [Instructions for a tip migration](#migrate-git-tip-on :::column span="2"::: :::image type="icon" source="../../media/icons/checkmark.png" border="false":::Confirm that none of your pipelines expose sensitive data: credentials/secrets, obscure URLs, and private environment names. -:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Confirm that non-members don't require access to your private feeds. Builds can still access feeds, but non-members can't. If you need to migrate build pipelines to a new project, you can import and export them using [YAML](../../pipelines/create-first-pipeline.md). +:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Confirm that nonmembers don't require access to your private feeds. Builds can still access feeds, but nonmembers can't. If you need to migrate build pipelines to a new project, you can import and export them using [YAML](../../pipelines/create-first-pipeline.md). :::column-end::: :::row-end::: :::row::: @@ -120,7 +126,7 @@ For more information, see [Instructions for a tip migration](#migrate-git-tip-on **Test** :::column-end::: :::column span="2"::: -:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Understand that manual and cloud load testing features aren't available to non-members in a public project. +:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Understand that manual and cloud load testing features aren't available to nonmembers in a public project. :::column-end::: :::row-end::: :::row::: @@ -128,7 +134,7 @@ For more information, see [Instructions for a tip migration](#migrate-git-tip-on **Analytics and dashboards** :::column-end::: :::column span="2"::: -:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Consider building a dashboard intended for the public. Some [widgets are unavailable](about-projects.md#dashboard-widget-support) to non-members. +:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Consider building a dashboard intended for the public. Some [widgets are unavailable](about-projects.md#dashboard-widget-support) to nonmembers. :::column-end::: :::row-end::: :::row::: @@ -146,52 +152,37 @@ For more information, see [Instructions for a tip migration](#migrate-git-tip-on :::column span="2"::: :::image type="icon" source="../../media/icons/checkmark.png" border="false":::Confirm whether there are any extensions vital to your project's experience. For instance, do you have a control on your work item form that renders data in a particular way? Are there custom extensions that expose important details? -:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Confirm that each extension's author has made it available for non-members by testing it. -If not, ask the extension author to add support for non-members. For details, see [Extensions and public project support](../../extend/develop/public-project.md). +:::image type="icon" source="../../media/icons/checkmark.png" border="false":::Confirm that each extension's author made it available for nonmembers by testing it. +If not, ask the extension author to add support for nonmembers. :::column-end::: :::row-end::: ## 1. Enable anonymous access to projects -Before you can change a private project to a public project, you must enable anonymous access for your organization. +Before changing a private project to a public project, enable anonymous access for your organization by doing the following steps: -1. From your web browser, sign in to Azure DevOps. You must be signed in to create a public project. +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Choose :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: **Azure DevOps** to open **Projects**. Then choose **Organization settings**. +2. Select **Organization settings**. > [!div class="mx-imgBorder"] > ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) -3. Choose the **Policies** page, and select **On** for **Allow public projects**. +3. Select **Policies**, and then turn on the **Allow public projects** security policy. - > [!div class="mx-imgBorder"] - > ![Screenshot showing Organization settings, Policy page, Security policies flow.](media/public/org-policies-change-anon.png) - -## 2. Make a private project public + :::image type="content" source="media/rename-project/org-policies-change-anon.png" alt-text="Screenshot showing Organization settings, Policy page, Security policies flow."::: -1. Choose **Project Settings** in the sidebar. - > [!div class="mx-imgBorder"] - > ![Screenshot showing highlighted Project settings button.](media/open-project-settings-public-vert-brn.png) +## 2. Set project visibility -2. Choose **Overview**. - -3. To switch from private to public, choose **Public** from the **Visibility** menu of options. +1. Sign in to your project (```https://dev.azure.com/{Your_Oganization}{Your_Project}```). +2. Select **Project settings** > **Overview** > the **Visibility** dropdown menu, choose **Public** or **Private**, and then **Save**. > [!div class="mx-imgBorder"] > ![Screenshot showing Project Settings, Overview, Visibility flow.](media/switch-to-public.png) - To switch from public to private, choose **Private** from the **Visibility** menu of options. - -4. Choose **Save**. - -## Access levels and unavailable features for public projects - -A project member has access to features based on the access level assigned. Non-members / public users are granted limited access automatically. -To contribute to a public project, you must be added as a member of that project and assigned either Stakeholder, Basic, or Basic + Test Plans access. Access levels determine the user interfaces that you can access. The security group you're assigned to determines the features you can exercise. For more information, see [About access levels](../security/access-levels.md). - -You [add project members](../accounts/add-organization-users.md) in the same way you do for private projects. Be sure you understand what it means to [invite an external user](../accounts/add-external-user.md) to have access to your project. If you created the project, you're automatically assigned to the Project Administrators group. +## Limited UI elements for public projects -The following user interface elements are hidden for non-members. +The following user interface elements are hidden for nonmembers. :::row::: :::column span="1"::: @@ -238,7 +229,7 @@ The following user interface elements are hidden for non-members. Analytics :::column-end::: :::column span="2"::: - Analytics views is hidden, and the Analytics OData feed isn't supported for non-members. Power BI integration in general isn't supported. + Analytics views are hidden, and the Analytics OData feed isn't supported for nonmembers. Power BI integration in general isn't supported. :::column-end::: :::row-end::: :::row::: @@ -250,29 +241,29 @@ The following user interface elements are hidden for non-members. :::column-end::: :::row-end::: -> [!NOTE] -> When you enable the **Free access to Pipelines for Stakeholders** preview feature for the organization, Stakeholders get access to all **Pipeline** features. Without this feature enabled, Stakeholders can only view and approve releases. For more information, see [Provide Stakeholders access to edit build and release pipelines](../security/provide-stakeholder-pipeline-access.md). - -Also, non-members can't do the following tasks: +Nonmembers can't do the following tasks: * Edit or create artifacts, such as files, work items, and pipelines. * Favorite and follow existing artifacts. -* View project members' email addresses and other contact information; non-members can only see name and picture. Also, filter lists of artifacts by identity. -* Switch between two public projects in the same organization; non-members must go directly to a public project using a URL. +* View project members' email addresses and other contact information; nonmembers can only see names and pictures. Also, filter lists of artifacts by identity. +* Switch between two public projects in the same organization; nonmembers can only go directly to a public project using a URL. * Perform code or work item searches across an organization. -## Partial migration +## Add contributors to a public project + +To contribute to a public project, get added as a member and assigned either Stakeholder, Basic, or Basic + Test Plans access. For more information, see [About access levels](../security/access-levels.md). -Organizations containing sensitive material shouldn't enable the public projects policy. -In that case, we recommend that you create an entirely separate organization to host your public projects. +You [add project members](../accounts/add-organization-users.md) the same way you do for private projects. Ensure you understand the implications of [inviting an external user](../accounts/add-external-user.md). If you created the project, you're automatically assigned to the Project Administrators group. + +## Partial migration - +If your organization contains sensitive material, you shouldn't turn on the public projects policy. +We recommend that you create an entirely separate organization to host your public projects. ### Move work items to a private project -If one or a handful of work items are sensitive, you can [move them](../../boards/backlogs/move-change-type.md#move) into a separate, private project. -Cross-project links continue to work for members. -Non-members won't have access to the content since it resides in a private project. +If any work items are sensitive, you can [move them](../../boards/backlogs/move-change-type.md#move) into a separate, private project. +Cross-project links continue to work for members, but nonmembers don't have access to the content since it resides in a private project. If you have a large number of sensitive work items, consider keeping your current project private. Instead, create a new public project in another organization. Migrating work items can be accomplished using the open source [WiMigrator](https://github.com/Microsoft/vsts-work-item-migrator) maintained by Microsoft. @@ -284,21 +275,29 @@ Keep the project containing the problematic repository private. Create the new repository in a project that you don't mind making public. > [!WARNING] -> The new repository won't have connection to the old one. -> You won't easily be able to migrate changes between them in the future. -> Also, your pull request history won't be migrated. - -1. Clone the existing repository: `git clone ` -2. Make sure you're in the root of the repository: `cd ` -3. Ensure you're on the tip of the branch you want to start from: `git checkout main` -4. Delete the Git data: `rmdir /s .git` on Windows, `rm -rf .git` on macOS or Linux -5. Initialize a new Git repository: `git init` -6. Create a new, empty repository in your public project. -7. Add the new repository as your origin remote: `git remote add origin ` -8. Push up your new repository: `git push --set-upstream origin main` +> - The new repository doesn't connect to the old one. +> - You can't easily migrate changes between them in the future. +> - Your pull request history doesn't migrate. + +Do the following steps to migrate the Git tip only: +1. Clone the existing repository: `git clone `. +2. Make sure you're in the root of the repository: `cd `. +3. Ensure you're on the tip of the branch you want to start from: `git checkout main`. +4. Delete the Git data: `rmdir /s .git` on Windows, `rm -rf .git` on macOS or Linux. +5. Initialize a new Git repository: `git init`. +6. Create a new, empty repository in your public project. +7. Add the new repository as your origin remote: `git remote add origin `. +8. Push your new repository: `git push --set-upstream origin main`. ## Next steps > [!div class="nextstepaction"] > [Code with Git](../../user-guide/code-with-git.md) + +## Related articles + +- [Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#limit-user-visibility-for-projects-and-more) +- [Delete a project](delete-project.md) +- [Add external users](../accounts/add-external-user.md) +- [Add a privacy policy URL](../accounts/add-privacy-policy-url.md) diff --git a/docs/organizations/projects/media/connect-projects/connect-to-a-project-and-github.png b/docs/organizations/projects/media/connect-projects/connect-to-a-project-and-github.png index dd25aaf3931..ac0eef84938 100644 Binary files a/docs/organizations/projects/media/connect-projects/connect-to-a-project-and-github.png and b/docs/organizations/projects/media/connect-projects/connect-to-a-project-and-github.png differ diff --git a/docs/organizations/projects/media/create-project/create-new-project-form-new-nav-2.png b/docs/organizations/projects/media/create-project/create-new-project-form-new-nav-2.png new file mode 100644 index 00000000000..d9ba6884fed Binary files /dev/null and b/docs/organizations/projects/media/create-project/create-new-project-form-new-nav-2.png differ diff --git a/docs/organizations/projects/media/create-project/create-new-project-form-new-nav.png b/docs/organizations/projects/media/create-project/create-new-project-form-new-nav.png index 2852b443072..5f23d528932 100644 Binary files a/docs/organizations/projects/media/create-project/create-new-project-form-new-nav.png and b/docs/organizations/projects/media/create-project/create-new-project-form-new-nav.png differ diff --git a/docs/organizations/projects/media/create-project/list-projects-org-settings.png b/docs/organizations/projects/media/create-project/list-projects-org-settings.png index 6db1c4f9540..11fff9bca11 100644 Binary files a/docs/organizations/projects/media/create-project/list-projects-org-settings.png and b/docs/organizations/projects/media/create-project/list-projects-org-settings.png differ diff --git a/docs/organizations/projects/media/delete-project/delete-project-organization-settings.png b/docs/organizations/projects/media/delete-project/delete-project-organization-settings.png new file mode 100644 index 00000000000..48b13154aac Binary files /dev/null and b/docs/organizations/projects/media/delete-project/delete-project-organization-settings.png differ diff --git a/docs/organizations/projects/media/delete-project/recently-deleted-projects.png b/docs/organizations/projects/media/delete-project/recently-deleted-projects.png new file mode 100644 index 00000000000..2ffb289abd9 Binary files /dev/null and b/docs/organizations/projects/media/delete-project/recently-deleted-projects.png differ diff --git a/docs/organizations/projects/media/public/org-policies-change-anon.png b/docs/organizations/projects/media/public/org-policies-change-anon.png deleted file mode 100644 index ee97d42c02a..00000000000 Binary files a/docs/organizations/projects/media/public/org-policies-change-anon.png and /dev/null differ diff --git a/docs/organizations/projects/media/rename-project/org-policies-change-anon.png b/docs/organizations/projects/media/rename-project/org-policies-change-anon.png new file mode 100644 index 00000000000..2932f37947c Binary files /dev/null and b/docs/organizations/projects/media/rename-project/org-policies-change-anon.png differ diff --git a/docs/organizations/projects/media/restore-project/deleted-projects-powershell-script-2019.png b/docs/organizations/projects/media/restore-project/deleted-projects-powershell-script-2019.png deleted file mode 100644 index d1ed0b79e14..00000000000 Binary files a/docs/organizations/projects/media/restore-project/deleted-projects-powershell-script-2019.png and /dev/null differ diff --git a/docs/organizations/projects/media/restore-project/recently-deleted-projects.png b/docs/organizations/projects/media/restore-project/recently-deleted-projects.png index 3f54b712bf3..611bae935cd 100644 Binary files a/docs/organizations/projects/media/restore-project/recently-deleted-projects.png and b/docs/organizations/projects/media/restore-project/recently-deleted-projects.png differ diff --git a/docs/organizations/projects/media/sign-out.png b/docs/organizations/projects/media/sign-out.png index 810debba96b..ed3711ed2a7 100644 Binary files a/docs/organizations/projects/media/sign-out.png and b/docs/organizations/projects/media/sign-out.png differ diff --git a/docs/organizations/projects/media/switch-to-public.png b/docs/organizations/projects/media/switch-to-public.png index 4d5a6fd7431..325cf7e66df 100644 Binary files a/docs/organizations/projects/media/switch-to-public.png and b/docs/organizations/projects/media/switch-to-public.png differ diff --git a/docs/organizations/projects/media/team-explorer-connect-to-project-visual-studio-2022.png b/docs/organizations/projects/media/team-explorer-connect-to-project-visual-studio-2022.png new file mode 100644 index 00000000000..e2e0aeb45c6 Binary files /dev/null and b/docs/organizations/projects/media/team-explorer-connect-to-project-visual-studio-2022.png differ diff --git a/docs/organizations/projects/project-team-quick-reference.md b/docs/organizations/projects/project-team-quick-reference.md deleted file mode 100644 index 7db54791e9e..00000000000 --- a/docs/organizations/projects/project-team-quick-reference.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: Index to project and team tasks and concepts -titleSuffix: Azure DevOps -description: Find project and team tasks and related concepts -ms.subservice: azure-devops-projects -ms.manager: mijacobs -ms.author: chcomley -author: chcomley -ms.topic: conceptual -monikerRange: '<= azure-devops' -ms.date: 04/04/2022 ---- - -# Project and team quick reference - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Use this index to quickly access concepts and tasks related to managing projects and teams. - -## Key concepts - -::: moniker range="azure-devops" - -:::row::: - :::column span=""::: -- [About projects](about-projects.md) -- [About teams](../settings/about-teams-and-settings.md) -- [Access levels](../security/access-levels.md) -- [Area paths](../settings/about-areas-iterations.md) -- [Dashboards](../../report/dashboards/overview.md) -- [Notifications and subscriptions](../../organizations/notifications/about-notifications.md) -- [GitHub connections](../../boards/github/connect-to-github.md) -- [Iteration paths](../settings/about-areas-iterations.md) - :::column-end::: - :::column span=""::: -- [Permissions](../security/about-permissions.md) -- [Process (Inherited)](../settings/work/inheritance-process-model.md) -- [Project resources viewable by members](resources-granted-to-project-members.md) -- [Project Wiki](../../project/wiki/provisioned-vs-published-wiki.md) -- [Project-level permissions](../security/permissions.md#project-level-permissions) -- [Project-level security groups](../security/permissions.md#project-level-groups) - :::column-end::: - :::column span=""::: -- [Project and process object limits](../settings/work/object-limits.md) -- [Projects page](../../project/navigation/work-across-projects.md) -- [Public vs private projects](about-projects.md) -- [Security groups](../security/about-permissions.md) -- [Service hooks](../../service-hooks/overview.md) -- [Service visibility](../settings/set-services.md) -- [Summary page](project-vision-status.md) - :::column-end::: -:::row-end::: - -::: moniker-end - - -::: moniker range=">= azure-devops-2019 < azure-devops" - -:::row::: - :::column span=""::: -- [About projects](about-projects.md) -- [About teams](../settings/about-teams-and-settings.md) -- [Access levels](../security/access-levels.md) -- [Area paths](../settings/about-areas-iterations.md) -- [Dashboards](../../report/dashboards/overview.md) -- [Notifications and subscriptions](../../organizations/notifications/about-notifications.md) -- [GitHub connections](../../boards/github/connect-to-github.md) -- [Iteration paths](../settings/about-areas-iterations.md) - :::column-end::: - :::column span=""::: -- [Permissions](../security/about-permissions.md) -- [Process (Inherited)](../settings/work/inheritance-process-model.md) -- [Process (On-premises XML)](../../reference/on-premises-xml-process-model.md) -- [Project and process object limits](../settings/work/object-limits.md) -- [Project resources viewable by members](resources-granted-to-project-members.md) -- [Project Wiki](../../project/wiki/provisioned-vs-published-wiki.md) - :::column-end::: - :::column span=""::: -- [Project-level permissions](../security/permissions.md#project-level-permissions) -- [Project-level security groups](../security/permissions.md#project-level-groups) -- [Projects page](../../project/navigation/work-across-projects.md) -- [Security groups](../security/about-permissions.md) -- [Service hooks](../../service-hooks/overview.md) -- [Service visibility](../settings/set-services.md) -- [Summary page](project-vision-status.md) - :::column-end::: -:::row-end::: - -::: moniker-end - - - -::: moniker range=" tfs-2018" - -:::row::: - :::column span=""::: -- [About projects](about-projects.md) -- [About teams](../settings/about-teams-and-settings.md) -- [Access levels](../security/access-levels.md) -- [Area paths](../settings/about-areas-iterations.md) -- [Dashboards](../../report/dashboards/overview.md) -- [Notifications and subscriptions](../../organizations/notifications/about-notifications.md) -- [Iteration paths](../settings/about-areas-iterations.md) - :::column-end::: - :::column span=""::: -- [Permissions](../security/about-permissions.md) -- [Process (On-premises XML)](../../reference/on-premises-xml-process-model.md) -- [Project and process object limits](../settings/work/object-limits.md) -- [Project resources viewable by members](resources-granted-to-project-members.md) -- [Project Wiki](../../project/wiki/provisioned-vs-published-wiki.md) - :::column-end::: - :::column span=""::: -- [Project-level permissions](../security/permissions.md#project-level-permissions) -- [Project-level security groups](../security/permissions.md#project-level-groups) -- [Projects page](../../project/navigation/work-across-projects.md) -- [Security groups](../security/about-permissions.md) -- [Service hooks](../../service-hooks/overview.md) -- [Summary page](project-vision-status.md) - :::column-end::: -:::row-end::: - -::: moniker-end - - -## User and administrative tasks - -Several of the following tasks require permissions granted to a member of the Project Administrators group or a team administrator. - - -::: moniker range="azure-devops" - -:::row::: - :::column span=""::: -- [Add Git repository](../../repos/git/create-new-repo.md) -- [Add project administrators](../security/change-project-level-permissions.md) -- [Add project dashboard](../../report/dashboards/dashboards.md#add-a-dashboard) -- [Add project members](../security/add-users-team-project.md) -- [Add security groups](../security/add-ad-aad-built-in-security-groups.md) -- [Add team administrators](../settings/add-team-administrator.md) -- [Add team members](../security/add-users-team-project.md) -- [Add/manage service hooks](../../service-hooks/overview.md) - :::column-end::: - :::column span=""::: -- [Connect to a project](connect-to-projects.md) -- [Connect to GitHub](../../boards/github/connect-to-github.md) -- [Create project](create-project.md) -- [Delete project](delete-project.md) -- [Edit project Summary](project-vision-status.md) -- [Enable/disable project services](../settings/set-services.md) -- [Export list of projects](create-project.md#list-and-connect-to-projects) -- [Export list of teams](../settings/add-teams.md#list-teams) -- [Manage notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) -- [Manage your project](../../user-guide/project-admin-tutorial.md) -- [Navigate the Web portal](../../project/navigation/index.md) -- [Remove team](../settings/rename-remove-team.md) -- [Rename project](create-project.md) -- [Rename team](../settings/rename-remove-team.md) - :::column-end::: - :::column span=""::: -- [Restore project](restore-project.md) -- [Change user access levels](../accounts/add-organization-users.md) -- [Search across project(s)](../../project/search/get-started-search.md) -- [Set area paths](../settings/set-area-paths.md) -- [Set favorites](../../project/navigation/set-favorites.md) -- [Set iteration paths](../settings/set-iteration-paths-sprints.md) -- [Set project-level permissions](../security/change-project-level-permissions.md) -- [Set project visibility](../projects/make-project-public.md) -- [Switch project, repository, team](../../project/navigation/go-to-project-repo.md) - :::column-end::: -:::row-end::: - -::: moniker-end - - - -::: moniker range=">= azure-devops-2019 < azure-devops" - -:::row::: - :::column span=""::: -- [Add Git repository](../../repos/git/create-new-repo.md) -- [Add project administrators](../security/change-project-level-permissions.md) -- [Add project members](../security/add-users-team-project.md) -- [Add security groups](../security/add-ad-aad-built-in-security-groups.md) -- [Add team members](../security/add-users-team-project.md) -- [Add team administrators](../settings/add-team-administrator.md) -- [Add/manage service hooks](../../service-hooks/overview.md) -- [Change access levels](../security/change-access-levels.md) -- [Connect to a project](connect-to-projects.md) -- [Connect to GitHub](../../boards/github/connect-to-github.md) - :::column-end::: - :::column span=""::: -- [Create project](create-project.md) -- [Delete project](delete-project.md) -- [Edit project Summary](project-vision-status.md) -- [Enable/disable project services](../settings/set-services.md) -- [Manage notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) -- [Manage your project](../../user-guide/project-admin-tutorial.md) -- [Navigate the Web portal](../../project/navigation/index.md) -- [Remove team](../settings/rename-remove-team.md) - :::column-end::: - :::column span=""::: -- [Rename project](create-project.md) -- [Rename team](../settings/rename-remove-team.md) -- [Restore project](restore-project.md) -- [Search across project(s)](../../project/search/get-started-search.md) -- [Set area paths](../settings/set-area-paths.md) -- [Set favorites](../../project/navigation/set-favorites.md) -- [Set iteration paths](../settings/set-iteration-paths-sprints.md) -- [Set project-level permissions](../security/change-project-level-permissions.md) -- [Switch project, repository, team](../../project/navigation/go-to-project-repo.md) - :::column-end::: -:::row-end::: - -::: moniker-end - - -::: moniker range="tfs-2018" - -:::row::: - :::column span=""::: -- [Add Git repository](../../repos/git/create-new-repo.md) -- [Add project administrators](../security/change-project-level-permissions.md) -- [Add project members](../security/add-users-team-project.md) -- [Add security groups](../security/add-ad-aad-built-in-security-groups.md) -- [Add team administrators](../settings/add-team-administrator.md) -- [Add team members](../security/add-users-team-project.md) -- [Add/manage service hooks](../../service-hooks/overview.md) - :::column-end::: - :::column span=""::: -- [Change access levels](../security/change-access-levels.md) -- [Connect to a project](connect-to-projects.md) -- [Create project](create-project.md) -- [Delete project](delete-project.md) -- [Edit project Summary](project-vision-status.md) -- [Manage notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) -- [Manage your project](../../user-guide/project-admin-tutorial.md) -- [Navigate the Web portal](../../project/navigation/index.md) -- [Remove team](../settings/rename-remove-team.md) - :::column-end::: - :::column span=""::: -- [Rename project](create-project.md) -- [Rename team](../settings/rename-remove-team.md) -- [Restore project](restore-project.md) -- [Search across project(s)](../../project/search/get-started-search.md) -- [Set area paths](../settings/set-area-paths.md) -- [Set favorites](../../project/navigation/set-favorites.md) -- [Set iteration paths](../settings/set-iteration-paths-sprints.md) -- [Set project-level permissions](../security/change-project-level-permissions.md) -- [Switch project, repository, team](../../project/navigation/go-to-project-repo.md) - :::column-end::: -:::row-end::: - -::: moniker-end - -## Related articles - -- [Get started as an administrator](../../user-guide/project-admin-tutorial.md) -- [Web portal navigation](../../project/navigation/index.md) -- [What do I get with a project?](../../user-guide/services.md?toc=/azure/devops/organizations/projects/toc.json&bc=/azure/devops/organizations/projects/breadcrumb/toc.json) -- [Understand differences between Azure DevOps](../../user-guide/about-azure-devops-services-tfs.md?toc=/azure/devops/organizations/projects/toc.json&bc=/azure/devops/organizations/projects/breadcrumb/toc.json) - diff --git a/docs/organizations/projects/project-vision-status.md b/docs/organizations/projects/project-vision-status.md index cf4f7523537..0a9e17f4101 100644 --- a/docs/organizations/projects/project-vision-status.md +++ b/docs/organizations/projects/project-vision-status.md @@ -1,21 +1,28 @@ --- -title: Project Summary, vision, & view project activity +title: Project summary page, view project activity titleSuffix: Azure DevOps -description: View or update your project Summary to share project vision, objectives, and activity for Azure DevOps +description: Learn how to view and update your project summary page to share project vision, objectives, and activity for Azure DevOps. ms.topic: quickstart ms.subservice: azure-devops-projects ms.assetid: A9ED2BF5-BD0B-4114-A7BD-693C5D747E16 ms.author: chcomley author: chcomley -monikerRange: '<= azure-devops' -ms.date: 08/24/2021 +monikerRange: "<=azure-devops" +ms.date: 11/11/2024 --- -# Share your project vision, view project activity +# View and update project summary page -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Each project provides a **Summary** or home page to share information and showcase the latest project activity. Use this page to perform one or more of the following tasks. +Each project provides a summary or home page to share information and showcase the latest project activity. This page serves as a central hub for team members to stay informed and up-to-date on the project's progress. Use this page for the following tasks: + +- Share important project updates and announcements +- Highlight recent activities and milestones +- Provide quick access to key project resources and documentation +- Facilitate team collaboration and communication + +Use the project summary page to also perform more specific tasks: :::row::: :::column span="1"::: @@ -27,25 +34,17 @@ Each project provides a **Summary** or home page to share information and showca :::row-end::: :::row::: :::column span="1"::: - ::: moniker range=">= azure-devops-2019" - Add a short project description - Choose a README file or wiki for project information - Invite people to contribute to your project - Set project tags - ::: moniker-end - ::: moniker range="tfs-2018" - - Choose a README file or wiki for project information - - Invite people to contribute to your project - ::: moniker-end :::column-end::: :::column span="1"::: - ::: moniker range=">= azure-devops-2019" - View project information - View project activity - Favorite a project - Email or initiate a chat with a team member - Initiate a search across your project - ::: moniker-end - View project information - Email or initiate a chat with a team member - View project activity @@ -54,102 +53,74 @@ Each project provides a **Summary** or home page to share information and showca ::: moniker range="azure-devops" > [!NOTE] -> Hosted projects can be designated as **Private** or **Public**. For public projects, anonymous users can view the project **Summary**, except for the **Members** section. Also the **Like** and **Favorite** icons aren't visible to anonymous users. To learn more about public projects, see [What is a public project?](../projects/about-projects.md) +> You can designate hosted projects as **Private** or **Public**. For public projects, anonymous users can view the project **Summary**, except for the **Members** section. Also the **Like** and **Favorite** icons aren't visible to anonymous users. For more information, see [What is a public project?](../projects/about-projects.md) ::: moniker-end -::: moniker range=">= azure-devops-2019" :::image type="content" source="media/summary/project-summary-page-intro.png" alt-text="Screenshot of summary page."::: -::: moniker-end -::: moniker range=" tfs-2018" -:::image type="content" source="media/summary/project-summary-page-intro-tfs-2018.png" alt-text="Screenshot of summary page, TFS-2018."::: -::: moniker-end - -> [!NOTE] -> If you want to use a project wiki for your project Summary information, then first [create a Wiki for your project](../../project/wiki/wiki-create-repo.md). You can then [change the project summary page to point to the wiki](#update). ## Prerequisites -- You must be a member of the [**Project Administrators** group](../security/change-project-level-permissions.md) or have your **Edit project-level information** permission set to **Allow** to do the following: - - Edit information on the project page - - Change the repository that you use to share project information - - Manage project membership -- To edit a page, you must be a contributor to the repository or branch or have the **Contribute** permissions set to **Allow**. -- To view the project **Summary**, you must be a valid member of the project. For more information, see [About security, membership, and permissions; Valid user groups](../security/about-permissions.md#validusers). -- To add or edit project **Tags**, you must have the project-level **Manage properties** permission set to **Allow**. This permission controls the project properties REST API. The project properties REST API is used to drive the project tags experience in the product. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|Member of the [Project Administrators](../security/change-project-level-permissions.md) group or **Edit project-level information** permission set to **Allow** to do the following tasks:
      - Edit information on the project page.
      - Change the repository that you use to share project information.
      - Manage project membership.
      **Specific tasks:**
      - To edit a project page: **Contributor** to the repository or branch or **Contribute** permissions set to **Allow**.
      - To view the project summary: [Valid member of the project](../security/about-permissions.md#valid-user-groups).
      - To add or edit project tags: Project-level **Manage properties** permission set to **Allow**. This permission controls the project properties REST API.| > [!TIP] -> If you don't have permissions to edit a page or use a feature, the corresponding icons and links aren't visible. +> If you don't have the necessary permissions to edit a page or use a feature, the corresponding icons and links aren't visible to you. -::: moniker range=">= azure-devops-2019" -## Open project Summary +## Open project summary -From your web browser, choose **Overview>Summary**. If you don't have a project yet, [create a project](../../organizations/projects/create-project.md). +From your web browser, select **Overview** > **Summary**. If you don't have a project yet, [create a project](../../organizations/projects/create-project.md). -If you haven't set up your project summary yet, you'll see this welcome page: +If your project summary isn't set up yet, a welcome page displays: > [!div class="mx-imgBorder"] -> ![Open project summary, new nav](media/share-project/welcome-page-new-nav.png) +> ![Screenshot shows project welcome page.](media/share-project/welcome-page-new-nav.png) Select one of the following tasks to get started: -- **Invite** to begin [adding others to your project](../../organizations/security/add-users-team-project.md). You can only invite users who have already been [added to your organization](../security/add-users-team-project.md#add-users-to-a-project)). +- **Invite** to begin [adding others to your project](../../organizations/security/add-users-team-project.md). You can only invite users who are [added to your organization](../security/add-users-team-project.md#add-users-to-a-project). - **Boards** to begin [adding work items](../../boards/work-items/view-add-work-items.md). - **Repos** to open [Repos>Files](../../repos/git/clone.md) page where you can clone or import a repository, or [initialize a README file](#initialize-a-readme-file-for-a-git-repo) for your project summary page. - **Pipelines** to start [defining a pipeline](../../pipelines/index.yml). - **Test Plans** to start [defining test plans and test suites](../../test/create-a-test-plan.md). - [Manage your services](../../organizations/settings/set-services.md) to disable the visibility of one or more services. -::: moniker-end - -::: moniker range=" tfs-2018" - -## Open project Home page -From your web browser, open the team project drop down menu and select the home page. If you don't have a project, [create a team project](../../organizations/projects/create-project.md). - -![Open Project Summary](media/share-project/project-vision-status-project-home-page.png) - -To define a README file for your project, see [Initialize a README file for your Git repo](#initialize-git) or [Initialize a README file for your TFVC repo](#initialize-tfvc). - -::: moniker-end - -       +## Update the summary page -## Update the page +The summary page displays either the README file defined in a project repository or the home page of a project wiki. To use the project wiki home page, [create a wiki for your project](../../project/wiki/wiki-create-repo.md) and then you can change the project summary page to point to the wiki. -The **Summary** page displays either the **README** file defined in a project repository or the home page of a project wiki. If you want to use the project wiki home page, first set that up as described in [Create a Wiki for your project](../../project/wiki/wiki-create-repo.md). +1. Edit the page: -1. To edit the page: - - - If it is the first time editing the page, choose **Add Project Description**. + - If it's your first time editing the page, select **Add Project Description**. :::image type="content" source="media/summary/add-project-description.png" alt-text="Screenshot of summary page, first time editing."::: - - If editing the page after it's been set up, choose the :::image type="icon" source="../../media/icons/edit.png" border="false"::: **Edit project information**. This icon is only visible to members with permissions to edit the project **Summary** page. + - If it's not your first time editing the page, select the :::image type="icon" source="../../media/icons/edit.png" border="false"::: **Edit project information**. This icon is only visible to members with permissions to edit the project **Summary** page. -1. Provide a brief description of the project purpose in the **Description** box. +2. Provide a brief description of the project purpose in the **Description** box. :::image type="content" source="media/summary/about-this-project-dialog.png" alt-text="About this project dialog."::: -1. Optionally add one or more **Tags** for your project. These tags are similar to [work item tags](../../boards/queries/add-tags-to-work-items.md). You can add several tags at a time by using the comma or semicolon delimiters. Tags must conform to the following rules: +3. (Optional) Add one or more **Tags** for your project. These tags are similar to [work item tags](../../boards/queries/add-tags-to-work-items.md). You can add several tags at a time by using the comma or semicolon delimiters. Tags must conform to the following rules: - Tags must be 40 characters or less - - Tags can;t contain the forward slash (/) character or end with hyphen character (-) + - Tags can't contain the forward slash (/) character or end with hyphen character (-) - No more than 15 tags can be added to a project - Tags are case-insensitive and no duplicate tags or empty tags are allowed. > [!NOTE] > The search and filter functions can't be used to search or filter on project tags. -1. Choose whether to reference a **README** file or the project wiki home page for the rest of the Summary page contents. +4. Choose whether to reference a **README** file or the project wiki home page for the rest of the Summary page contents. > [!TIP] > A default README is created within the repository added when you created your project. You can choose this README or create another repository and README file for this purpose. - If choosing a **Readme file**, select the repository for the README. A preview of the current text for the README file is shown. + If you choose a **Readme file**, select the repository for the README. A preview of the current text for the README file is shown. - :::image type="content" source="media/summary/select-readme-repository.png" alt-text="About this project dialog, choose and select README repository."::: + :::image type="content" source="media/summary/select-readme-repository.png" alt-text="About this project dialog, choose, and select README repository."::: - If choosing **Wiki**, note that the Wiki home page is referenced and must be the first file within the Wiki TOC. You can't change that reference. + If you choose a **Wiki**, the Wiki home page is referenced and must be the first file within the Wiki TOC. You can't change that reference. -1. To update the contents of the referenced README file or wiki, edit the corresponding file. For more information, see [Create a README for your repo](../../repos/git/create-a-readme.md) or [Add and edit wiki pages](../../project/wiki/add-edit-wiki.md). +5. To update the contents of the referenced README file or wiki, edit the corresponding file. For more information, see [Create a README for your repo](../../repos/git/create-a-readme.md) or [Add and edit wiki pages](../../project/wiki/add-edit-wiki.md). Consider including the following types of information in your **Summary** page: - Ways in which users can contribute to your project @@ -160,48 +131,31 @@ The **Summary** page displays either the **README** file defined in a project re - Links to templates to file a bug, issue, or request - Links to distribution lists to email a question or post a question on Slack or Teams channel. -## Invite people to contribute to your project +## Invite contributors to your project -::: moniker range=">= azure-devops-2019" -You can send an email to invite users to contribute to your project by choosing **Invite**. To learn more, see [Add users or groups to a team or project, Invite users from the Summary page](../security/add-users-team-project.md#invite-users-from-the-summary-page). +Send an email to invite users to contribute to your project by choosing **Invite**. For more information, see [Add users or groups to a team or project, Invite users from the Summary page](../security/add-users-team-project.md#invite-users-from-the-summary-page). :::image type="content" source="../security/media/add-users/summary-invite-users.png" alt-text="Screenshot of Summary page, Invite button."::: -::: moniker-end - -::: moniker range="tfs-2018" - -To add users to the project, choose the **Add** button. To learn more, see [Add users to a team project or team](../../organizations/security/add-users-team-project.md). - -:::image type="content" source="media/summary/invite-members-tfs-2018.png" alt-text="Screenshot of Summary page, Add members button."::: -::: moniker-end ::: moniker range="< azure-devops" > [!NOTE] -> For on-premises Azure DevOps, all email actions require an [SMTP server to be configured](/azure/devops/server/admin/setup-customize-alerts). +> For Azure DevOps Server, all email actions require an [SMTP server to be configured](/azure/devops/server/admin/setup-customize-alerts). ::: moniker-end - - ## View project activity From the **Project stats** or **Activity** section, you can view updates made to the project in the last 1, 7, or 30 days. Choose the view option as shown in the following image. -::: moniker range=">= azure-devops-2019" :::image type="content" source="media/summary/project-stats.png" alt-text="Screenshot of Summary page, Stats section."::: - ::: moniker-end -::: moniker range="tfs-2018" -:::image type="content" source="media/summary/project-summary-activity-tfs-2018.png" alt-text="Screenshot of Summary page, Activity section, TFS-2018."::: -::: moniker-end - -## Email or chat with a project member +## Chat with a project member or send an email -From the **Members** section, you can see some of the members that have been added to the project, and connect to them via email or chat with a member. +From the **Members** section, you can see some of the members added to the project, and connect to them via email or chat with a member. :::image type="content" source="media/summary/project-members.png" alt-text="Screenshot of Summary page, Members section."::: > [!NOTE] -> 100+ indicates that 100 or more members have been added to the project. +> 100+ indicates that 100 or more members are added to the project. To email or initiate a chat session, choose the team member shown and select your option. @@ -212,22 +166,15 @@ To email or initiate a chat session, choose the team member shown and select you > For on-premises Azure DevOps, all email actions require an [SMTP server to be configured](/azure/devops/server/admin/setup-customize-alerts). ::: moniker-end -::: moniker range=">= azure-devops-2019" +## Search a project -## Initiate a project search +From the **Summary** page, you can initiate a search of your code, work items, and wiki. For more information, see [Get started with search](../../project/search/get-started-search.md). -From the **Summary** page, you can initiate a search of your code, work items, and wiki. To learn more, see [Get started with search](../../project/search/get-started-search.md). :::image type="content" source="media/summary/project-search.png" alt-text="Screenshot of Summary page, search box."::: -::: moniker-end - - - ## Initialize a README file for a Git repo -You can share your project and objective, as well as ways for team members to contribute to the project through a project README file. For Git projects, the README.md file needs to be at the root of each repository in the default branch. For Git based projects the left pane supports navigation to other repositories. A separate Welcome page/README.md file can be created for each repository. - -::: moniker range=">= azure-devops-2019" +You can share your project and objective, and ways for team members to contribute to the project through a project README file. For Git projects, the README.md file needs to be at the root of each repository in the default branch. For Git based projects, the left pane supports navigation to other repositories. A separate Welcome page/README.md file can be created for each repository. 1. Open **Repos>Files**. This page guides you to get started quickly by adding code to your repository when you choose one of the options to clone, push, import, or initialize a repo. @@ -241,113 +188,67 @@ You can share your project and objective, as well as ways for team members to co 3. Return to **Overview** > **Summary** and choose the README file for the project page. Select :::image type="icon" source="../../media/icons/edit.png" border="false"::: **Edit**. > [!div class="mx-imgBorder"] - > ![Choose README file, new nav](media/share-project/choose-readme-file-new-nav.png) + > ![Screenshot of Choose README file.](media/share-project/choose-readme-file-new-nav.png) 4. Select the project repository where you initialized the README file. > [!div class="mx-imgBorder"] - > ![Choose Repository where the README file exists, new nav](media/share-project/choose-readme-file-dialog-new-nav.png) + > ![Screenshot of Choose Repository where the README file exists.](media/share-project/choose-readme-file-dialog-new-nav.png) 5. To edit the README file, choose the README file link. > [!div class="mx-imgBorder"] - > ![Edit the README file, new nav](media/share-project/edit-readme-file.png) - - You're directed to the **Repos>Files** page for the README file. You can edit and modify the README Markdown file like you would any other file in a Git repository. You can use Markdown language to format the README file and add images. To learn more about adding a README file, see [Create a README for your repo](../../repos/git/create-a-readme.md) and [Markdown guidance](../../project/wiki/markdown-guidance.md). - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Open the Project home page. - -2. With the **Add a README** check box checked, choose **Initialize**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Initialize README file, new nav](media/share-project/initialize-readme-prev-nav.png) + > ![Screenshot of Edit the README file.](media/share-project/edit-readme-file.png) - A default README file is added to the project repository, in this case, the **Fabrikam Test** repo. - -3. To edit the project README.md file, choose **Edit**. - - > [!div class="mx-imgBorder"] - > ![Git new project summary page](media/share-project/git-start-page-readme.png) - - Use Markdown language to format the README file and add images. To learn more about adding a README file, see [Create a README for your repo](../../repos/git/create-a-readme.md) and [Markdown guidance](../../project/wiki/markdown-guidance.md). - -::: moniker-end + You're directed to the **Repos>Files** page for the README file. You can edit and modify the README Markdown file like you would any other file in a Git repository. You can use Markdown language to format the README file and add images. For more information, see [Create a README for your repo](../../repos/git/create-a-readme.md) and [Markdown guidance](../../project/wiki/markdown-guidance.md). ## Initialize a README file for a TFVC repo -For projects that selected TFVC for version control, the README.md file needs to be at the root of your team project folder (i.e. $/TeamProject/README.md). +For projects that selected TFVC for version control, the README.md file needs to be at the root of your team project folder, for example, $/TeamProject/README.md. -::: moniker range=">= azure-devops-2019" - -1. Open **Repos>Files**. +1. Open **Repos** > **Files**. 2. Select **Add Project Description**. > [!div class="mx-imgBorder"] - > ![Welcome page, TFVC new project, create readme, new nav](media/share-project/welcome-page-tfvc-new-nav.png) + > ![Screenshot of Welcome page, TFVC new project, create readme.](media/share-project/welcome-page-tfvc-new-nav.png) -3. Select the TFVC repository and choose **Save**. If no README file has been created yet in the repo, you'll see the following message. +3. Select the TFVC repository and choose **Save**. If no README file is in the repo, you see the following message. > [!div class="mx-imgBorder"] - > ![About this project dialog, new nav](media/share-project/about-this-project-form.png) + > ![Screenshot of About this project dialog.](media/share-project/about-this-project-form.png) 4. To create a README file, choose **Repos>Files** and choose new file to add a file to the project repository. 5. Name the file as **README.md**. > [!div class="mx-imgBorder"] - > ![Add new file dialog, new nav](media/share-project/create-readme-file-web-portal.png) + > ![Screenshot of Add new file dialog.](media/share-project/create-readme-file-web-portal.png) 6. Add the contents of your README file in Markdown format, and then choose **Check in...**. > [!div class="mx-imgBorder"] - > ![Enter README file contents, new nav](media/share-project/tfvc-readme-file.png) + > ![Screenshot of Enter README file contents.](media/share-project/tfvc-readme-file.png) -7. Select **Check in** to complete the check in process of the README file. +7. Select **Check in** to complete the check-in process of the README file. > [!div class="mx-imgBorder"] - > ![Check-in README file dialog, new nav](media/share-project/tfvc-readme-checkin.png) + > ![Screenshot of Check-in README file dialog.](media/share-project/tfvc-readme-checkin.png) 8. Select **Overview>Summary** to review your project summary page with the README file displayed. > [!div class="mx-imgBorder"] - > ![Project summary page with the README file displayed.](media/share-project/tfvc-project-summary-with-readme.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Open the Project home page. - -2. Select **Create README**. - - > [!div class="mx-imgBorder"] - > ![Welcome page, TFVC new project, create README](media/share-project/welcome-page-tfvc-prev-nav.png) - - A default README file is added to the project repository, in this case, the **Fabrikam Fiber TFVC** repo. - -3. You can immediately edit the README file. When you're done, select **Check in**. - - > [!div class="mx-imgBorder"] - > ![Edit page, new nav](media/share-project/tfvc-checkin-page.png) -Any additional Markdown files you have (ones with a *.md extension) in the root of the project folder also appear in the left pane for easy navigation between them so you can provide additional information. - -::: moniker-end - + > ![Screenshot of Project summary page with the README file displayed.](media/share-project/tfvc-project-summary-with-readme.png) ## Related articles -- [About Wikis, READMEs, and Markdown](../../project/wiki/about-readme-wiki.md) +- [Learn about Wikis, READMEs, and Markdown](../../project/wiki/about-readme-wiki.md) - [Get started as an administrator](../../user-guide/project-admin-tutorial.md) -- [Web portal navigation](../../project/navigation/index.md) -- [What do I get with a project?](../../user-guide/services.md?toc=/azure/devops/organizations/projects/toc.json&bc=/azure/devops/organizations/projects/breadcrumb/toc.json) +- [Navigate the web portal](../../project/navigation/index.md) +- [Discover what you get with a project](../../user-guide/services.md?toc=/azure/devops/organizations/projects/toc.json&bc=/azure/devops/organizations/projects/breadcrumb/toc.json) **REST APIs** -- [Projects - Get Project Properties](/rest/api/azure/devops/core/projects/get-project-properties) -- [Projects - Set Project Properties](/rest/api/azure/devops/core/projects/set-project-properties) +- [Get project properties](/rest/api/azure/devops/core/projects/get-project-properties) +- [Set project properties](/rest/api/azure/devops/core/projects/set-project-properties) diff --git a/docs/organizations/projects/rename-project.md b/docs/organizations/projects/rename-project.md index 89e9ba6476d..e7449e03cb4 100644 --- a/docs/organizations/projects/rename-project.md +++ b/docs/organizations/projects/rename-project.md @@ -1,52 +1,38 @@ --- title: Rename a project - Azure DevOps titleSuffix: Azure DevOps -ms.custom: seodec18, contperf-fy21q3, content-perf-fy23q2, engagement-fy23 +ms.custom: content-perf-fy23q2, engagement-fy23 description: Learn how to rename your project, including tasks you need to complete to work with the renamed project. ms.subservice: azure-devops-projects ms.assetid: 23729f9a-9947-4fc1-89b0-07e3b52298ac toc: show -ms.topic: conceptual +ms.topic: how-to ms.author: chcomley author: chcomley -monikerRange: '<= azure-devops' -ms.date: 12/16/2022 +monikerRange: "<=azure-devops" +ms.date: 11/11/2024 --- # Rename a project in Azure DevOps -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -When you rename a project, Azure DevOps updates the project name in the following areas: -- Version control paths -- Work items -- Queries -- Other project artifacts - -You can rename a single project multiple times and reuse older names. After you rename a project, there may be some [required team member actions](#required-user-actions-for-working-with-the-renamed-project). +Renaming a project in Azure DevOps updates the project name in version control paths, work items, queries, and other project artifacts. You can rename a single project multiple times, and use old names. Some [actions might be required from team members](#required-user-actions-for-working-with-the-renamed-project) after you rename the project. > [!WARNING] -> When you rename a project, Azure DevOps sends email notifications to everyone in the project if there are less than 1,000 users. If there are greater than 1,000 users in your project, only Project Collection Administrators receive email notifications. +>- Upon renaming a project, Azure DevOps notifies all project members via email if the user count is less than 1,000. For projects with more than 1,000 users, only Project Collection Administrators receive these notifications. +> +>- Renaming a project breaks workload identity federation subjects in Azure Resource Manager service connections. ## Prerequisites -::: moniker range="azure-devops" - -- You must be a member of the **Project Administrators** group or have the project-level **Rename team project** permission set to **Allow**. For more information, see [Change project-level permissions](../security/change-project-level-permissions.md). - -::: moniker-end - -::: moniker range="< azure-devops" - -- You must be a member of the **Project Administrators** group or have the project-level **Rename team project** permission set to **Allow**. For more information, see [Change project-level permissions](../security/change-project-level-permissions.md). - -::: moniker-end +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the **Project Administrators** group or project-level **Rename team project** permission set to **Allow**. For more information, see [Change project-level permissions](../security/change-project-level-permissions.md).| ## Rename a project -::: moniker range=">= azure-devops-2019" - -1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```), and then open the project that you want to rename. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). 2. Select **Project settings** > **Overview**, and then enter a new name and select **Save**. @@ -56,33 +42,14 @@ You can rename a single project multiple times and reuse older names. After you ![Screenshot showing new name confirmation screen with save button.](media/rename-project/rename-project-confirm.png) -::: moniker-end - -::: moniker range="tfs-2018" - -1. Sign in to your organization. -2. From the Projects page, choose :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: **actions** for the project that you want to rename, and then choose **Rename**. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing highlighted Rename selection.](media/rename-project/choose-rename-menu-option.png) - -3. Edit the name. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing new project name entry and OK button.](media/rename-project/rename-project-dialog.png) - - If you can't find the **Rename project** option, then you're not a member of the **Project Administrators** group for that project. - -::: moniker-end - ### Results of the rename -The following results occur following the rename operation. +The following results occur after the rename operation. * Azure DevOps renames the project. * All project members receive an email notification of the name change, if less than 1,000 members. * The URL continues to work for both the new team name and the old team name. This functionality is intended to avoid breaking links. -* If the project in the URL is a valid project in the organization, we show the work item ID provided. The following example shows an organization with projects named "Example1" and "Example2". +* If the project in the URL is a valid project in the organization, we show the work item ID provided. The following example shows an organization with projects named "Example1" and "Example2." `https://dev.azure.com/MyOrg/Example1/_workitems/edit/40/` - Displays work item 40 `https://dev.azure.com/MyOrg/Example2/_workitems/edit/40/` - Displays work item 40 @@ -91,19 +58,14 @@ The following results occur following the rename operation. * Work item IDs are unique in the organization and therefore the links don't expire. * The old project name can be used again. - - ## Required user actions for working with the renamed project Each user within your team must [restart their clients](#restart-clients) and do some of the following actions, based on the features they use: - [Update Git remotes](#update-git-remotes) - [Update Team Foundation Version Control (TFVC) server workspaces](#update-tfvc-server-workspaces) - [Update TFVC local workspaces](#update-tfvc-local-workspaces) -::: moniker range="tfs-2018" -- [Update your Team Foundation Server (TFS) SharePoint and reporting integrations](#update-your-tfs-sharepoint-and-reporting-integrations) -::: moniker-end - - +- [Update OData feeds](#update-odata-feeds) +- [Update Analytics views](#update-analytics-views) ### Restart clients @@ -114,24 +76,20 @@ For the following clients, save your work in each and then restart: - Visual Studio Team Explorer - Microsoft Excel, if your team uses the [Azure DevOps Office Integration 2019](https://visualstudio.microsoft.com/downloads/#other-family) - - ### Update Git remotes -If your project uses Git, then your remote references for each repository from the renamed project must be updated. These updates are necessary because the remote repository URL contains the project and the repository name. Git uses remote references to fetch and push changes between your local repository and the remote version that's stored on the server. Each member of your team must update their local Git repositories to continue connecting from their dev machines. +If your project uses Git, then your remote references for each repository from the renamed project must be updated. These updates are necessary because the remote repository URL contains the project and the repository name. Git uses remote references to fetch and push changes between your local repository and the remote version stored on the server. Each member of your team must update their local Git repositories to continue connecting from their dev machines. For more information, see [Update the Git remotes on your dev machines](../../repos/git/repo-rename.md#update-the-git-remotes-on-your-dev-machines). - - ### Update TFVC server workspaces If your project uses TFVC with [server workspaces](../../repos/tfvc/decide-between-using-local-server-workspace.md), these workspaces must be updated with the new project name. -For Visual Studio clients, execute a get or check-in and then the workspace mapping gets corrected to use the new project name. +For Visual Studio clients, execute a get or check in and then the workspace mapping gets corrected to use the new project name. ![Screenshot of source control explorer, showing get latest version selection.](media/rename-project/tfvc-get.png) - +For more information, see [Rename command (TFVC)](../../repos/tfvc/rename-command-team-foundation-version-control.md). ### Update TFVC local workspaces @@ -141,68 +99,34 @@ For Visual Studio, execute a get or check-in and the workspace mapping is correc We recommend you update your clients to the latest update or release, if possible. For all other supported Visual Studio versions, you must create a new local workspace mapped to the new project name. Local workspaces get managed locally and not on the server. Older clients without the updated rename logic can't update local workspaces to the new project name. - -::: moniker range="tfs-2018" - - - -### Update your TFS SharePoint and reporting integrations - -Both SharePoint and Reporting Services integrations continue to work, but some reports don't work as expected until the new project name gets populated. -The old project name is still present until caches are updated with the new name. -The reporting and SharePoint server administrator can manually run these jobs to immediately populate the new name. - -- If your team uses reports, they reflect the new names after the next incremental analysis job runs for the data warehouse. By default, the job runs every two hours. But you can [manually run the warehouse jobs and incremental analysis job](/previous-versions/azure/devops/report/admin/manually-process-data-warehouse-and-cube). Then, the new name gets synced to warehouse and reports start using the new name. Reports don't work as expected until the jobs have run. -- If your team uses SharePoint Integration and has custom queries or web parts that directly reference the project name, - update the name in each to the new project name. You don't need to update default queries and web parts, as they continue to work. - Use of @project also continues to work after a project rename and also doesn't need updating. -- Excel reports and Excel web parts on MOSS don't show the right data until you execute the following. - - 1. Warehouse job - [Run the warehouse jobs](/previous-versions/azure/devops/report/admin/manually-process-data-warehouse-and-cube) - so that Excel reports contain the correct data. - If the new project name isn't synced to the warehouse, - Excel reports don't show the correct data. - To avoid this outcome, manually run warehouse jobs. - 2. SharePoint timer job - Run the "Team Foundation Server Dashboard Update" job - from the SharePoint central admin to update Excel web parts on the dashboard. - By default, it runs every 30 minutes. - Until this job runs, the Excel web parts on the dashboard - and the reports coming directly from the reporting folder - won't work. Those web parts use either the wrong project name or the wrong reporting folder. - 3. SharePoint cache - Manually clear the SharePoint cache to avoid stale data, - such as report folder locations, appearing in the dashboards. - By default, this cache clears about every hour. - You can also clear some TFS-specific cache using the TFS redirect URL - and providing a "clear_cache" parameter. For example: - - ``` - http:///sites///_layouts/TfsRedirect.aspx?tf:type=Report&tf:clearcache=1 - ``` -::: moniker-end + +### Update OData feeds + +If you use OData feeds in Power BI, update the feed URL to use the new project name. Updating the feed URL is essential to maintain data connections and avoid errors in reporting. For more information, see [Overview of sample reports using OData queries](../../report/powerbi/sample-odata-overview.md). + +### Update Analytics views + +If you created custom Analytics views using the old project name, you need to update the views with the new name. For more information, see [Analytics views](../../report/powerbi/analytics-views-manage.md#edit-an-existing-view). ## Related articles - [Delete a project](delete-project.md) -- [Restore a project](restore-project.md) - [Git and Azure Repos](../../repos/git/index.yml) -- [Team Foundation version control](../../repos/tfvc/index.yml) -- [Go to Visual Studio Team Explorer](../../user-guide/work-team-explorer.md) -- [Git experience in Visual Studio](/visualstudio/ide/git-with-visual-studio) ## Frequently asked questions (FAQs) ### Q: Why did my attempt to reuse a project name fail due to existing work spaces? -A: You can't reuse a project name if there are still workspace mappings addressing it. This function helps avoid the ambiguity case where a workspace could be mapped to two projects. Contact the users who have these mappings, and either delete them or [update them](rename-project.md#tfvc-server) to use the new name. +A: You can't reuse a project name if there are still workspace mappings addressing it. This function helps avoid the ambiguity case where a workspace could be mapped to two projects. Contact the users who have these mappings, and either delete them or [update them](#update-tfvc-server-workspaces)) to use the new name. If the user's machine containing the workspace is no longer available, then you can delete the workspace by running the following command from Visual Studio's developer command prompt: ```tf workspace /delete [/collection:TeamProjectCollectionUrl] workspacename[;workspaceowner]``` -### Q: How does renaming a project impact my browser navigation experience? +### Q: How does renaming a project affect my browser navigation experience? -A: After you rename a project, any browsers with the project opened may encounter some errors. These errors are due to caches held by the browser, which include the old project name. +A: After you rename a project, any browsers with the project opened might encounter some errors. These errors are due to caches held by the browser, which include the old project name. Refresh to make these errors go away since the cache gets repopulated with the new project name. -### Q: Do other artifacts in the project get renamed when it's renamed? +### Q: Do other artifacts in the project get renamed? A: Yes, all artifacts that share the same name get renamed along with the project. The only exceptions are for the default team and repo. The rename of these artifacts is performed as a best effort. For example, if a project *Foo* was renamed to *Bar*, the default team *Foo* wouldn't be renamed if a team named *Bar* already existed in the project. diff --git a/docs/organizations/projects/resources-granted-to-project-members.md b/docs/organizations/projects/resources-granted-to-project-members.md deleted file mode 100644 index dc8276badf3..00000000000 --- a/docs/organizations/projects/resources-granted-to-project-members.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Resources granted to project members -titleSuffix: Azure DevOps -ms.custom: seodec18 -description: Learn about security and data access considerations and resources granted when you add members to a project or organization -ms.subservice: azure-devops-projects -ms.assetid: -toc: show -ms.topic: conceptual -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 02/17/2021 ---- - -# Resources granted to project members - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -An Azure DevOps project is a container and security boundary for your software development assets: work items, code, builds, etc. -When you add someone as a member of a project, you are also trusting that person with some additional privileges. -A project member has access to organization-level resources and additional groups (or scopes) beyond the project. -If someone is not already a member of your organization, when you add them to a project, you implicitly grant them this additional access. - - -::: moniker range="azure-devops" - -> [!NOTE] -> If the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization, users added to the **Project-Scoped Users** group won't be able to access projects that they haven't been added to. For more information and important security-related call-outs, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). - -::: moniker-end - - -## Additional groups and scopes - -Under the hood, a project member belongs to one or more [project-related security groups](../security/about-permissions.md#security-group-membership) such as "Project Valid Users" and "Project Contributors". -That person is also a member of an organization-level group known as "Project Collection Valid Users". -Also, that person's identity appears in the [identity service](../security/about-security-identity.md#authentication) which backs the organization. -User accounts backed by [Azure Active Directory](/azure/active-directory/) can have [native identities](/azure/active-directory/add-users-azure-active-directory) or [guest identities](/azure/active-directory/active-directory-b2b-what-is-azure-ad-b2b), which grant different levels of access. - -## Organization-level resources - -Project members have access to resources beyond the specific project. -Those resources include those defined at the organization-level (cloud) or project collection level (on-premises): - -* Information about other members, including their email address and other contact details, that is hidden from non-members. -* The Settings area, including security groups and permissions. -* All installed extensions. -* [Process](../settings/work/manage-process.md) metadata from all processes in the organization, which includes the work item types, its fields and picklist items. Picklist items could show sensitive information such as release dates, as shown in the following image: - - ![Edit field release in feature](media/edit-field-release-in-feature.png) - -* When the WIT Client OM is used, which includes the usage of Excel and Visual Studio integration, it stores sensitive information in a cache on the local disk. This cache includes the metadata of all processes in the organization and the identities and group memberships of all members of the organization. -* When a user is added to the project-level Build Administrators group, they have the ability to create pipelines which run with project collection (account-wide) scope. A pipeline with project collection scope may access resources in another project, such as Git repositories, that the user cannot. (You can change this by [removing the Read permission from Project Collection Build Service](../../repos/git/set-git-repository-permissions.md#pcbs-has-read-by-default)). - -## The trust decision - -These resources and groups are required for the proper functioning of a member of a project. -Your collaborators are typically colleagues and others with whom you have an existing relationship. -Before you add someone from outside this trusted group, think carefully about whether they should have access to the previously mentioned items. diff --git a/docs/organizations/projects/restore-project.md b/docs/organizations/projects/restore-project.md deleted file mode 100644 index 7c550cc084b..00000000000 --- a/docs/organizations/projects/restore-project.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Restore project -titleSuffix: Azure DevOps Services -ms.custom: seodec18, contperf-fy21q4 -description: Restore a recently deleted project in Azure DevOps. -ms.assetid: f8638962-1732-4600-94bb-3dc34e0ac48e -ms.subservice: azure-devops-projects -ms.topic: conceptual -ms.author: chcomley -author: chcomley -monikerRange: '>= azure-devops-2019' -ms.date: 06/20/2023 ---- - -# Restore a project - -[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] - -If you delete a project in Azure DevOps by mistake, you can restore the project up to 28 days after it was deleted. - -## Prerequisites - -::: moniker range="azure-devops" - -* You must be a member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. - -* You must have the **Delete project** permission set to **Allow**. For more information, see [View permissions](../security/view-permissions.md). - -::: moniker-end - -::: moniker range=" < azure-devops" - -To restore a project, you must have the **Delete project** permission set to **Allow**. For more information, see [View permissions](../security/view-permissions.md). - -::: moniker-end - -## Restore project - -::: moniker range="azure-devops" - -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). - -2. Choose ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - - ![Screenshot showing how to choose the gear icon, Organization settings.](../../media/settings/open-admin-settings-vert.png) - -3. Select **Overview**, and then scroll down to "recently deleted projects." - - ![Screenshot that shows recently deleted projects.](../accounts/media/shared/organization-settings-select-overview.png) - -1. Highlight the project you want to restore, and then select **Restore**. - - ![Screenshot showing how to Highlight the project, and then select Restore.](media/restore-project/recently-deleted-projects.png) - - -::: moniker-end - -::: moniker range=" > azure-devops-2019 < azure-devops" - -1. Sign in to your instance (```http://{ServerName:8080/tfs/}/{CollectionName}```) -2. Choose ![gear icon](../../media/icons/gear-icon.png) **Admin settings**. - - :::image type="content" source="../../media/settings/open-admin-settings-server.png" alt-text="Screenshot showing Admin settings button surrounded by red box."::: - -3. Select **Projects**, and then scroll down to **Recently deleted projects**. - -4. Highlight the project you want to restore, and then select **Restore**. - - ![Screenshot showing how to Highlight the project, and then select Restore for Azure DevOps Server. ](media/restore-project/recently-deleted-projects.png) - -::: moniker-end - -::: moniker range="azure-devops-2019" - -> [!NOTE] -> The UI doesn't support restoring a team project for Azure DevOps Server 2019. Use the following REST API or PowerShell methods to restore a deleted team project. For more information, see [Projects-Update REST API](/rest/api/azure/devops/core/projects/update) - -::: moniker-end - -### Restore with REST API - -> [!WARNING] -> To restore a project with a name that's already taken, you must rename the project before you can restore it. To rename the project, enter the following text in the request body: `"name":"new name"` - -1. Open a browser window and enter a URL that uses the following form: - - 'http://ServerName:8080/tfs/DefaultCollection/ProjectName' - - For example, to connect to the server named **FabrikamPrime**, enter: 'http://FabrikamPrime:8080/tfs/'. - - The default Port is 8080. Specify the port number and directory for your server if defaults aren't used. - -2. Get a list of deleted projects using the following request: - - ``` - GET http://ServerName:8080/tfs/DefaultCollection/_apis/projects?stateFilter= - deleted&api-version=5.0-preview.3 - ``` - -3. Restore a deleted project using the following request: - - ``` - PATCH http://ServerName:8080/tfs/DefaultCollection/_apis/projects/{projectId}? - api-version=5.0-preview.3 - ``` - Request body - - ``` - { - "state" : "wellFormed" - } - ``` - -### Restore using PowerShell - -1. Execute the following PowerShell script to get a list of deleted projects and make sure to update `$collectionUrl`. - - ``` - $collectionUrl = "https://localhost/defaultcollection" - (irm -Uri "$collectionUrl/_apis/projects?stateFilter= - deleted&api-version=5.0-preview.3" -UseDefaultCredentials).value - ``` - - Something similar to the following screenshot appears: - ![Screenshot of PowerShell script return example for deleted projects.](media/restore-project/deleted-projects-powershell-script-2019.png) - -2. Use the following script to restore a project. Be sure to update `$collectionUrl` and `$projectName`. - - -``` -$collectionUrl = "https://localhost/defaultcollection" -$projectName = 'Project1' -$project = (irm -Uri "$collectionUrl/_apis/projects?stateFilter= -deleted&api-version=5.0-preview.3" -UseDefaultCredentials).value - | where {$_.name -eq $projectName} -irm -Uri ($project.url + "?api-version=5.0-preview.3") --UseDefaultCredentials -Method PATCH -Body '{"state":"wellFormed"}' - -ContentType 'application/json' -``` - -Your project and associated data are restored. - -## Related articles - -* [Delete a project](delete-project.md) -* [Save project data](save-project-data.md) -* [Create a project](create-project.md) -* [Disconnect your organization from Azure Active Directory (Azure AD)](../accounts/disconnect-organization-from-azure-ad.md) diff --git a/docs/organizations/projects/save-project-data.md b/docs/organizations/projects/save-project-data.md deleted file mode 100644 index 26e8121e63d..00000000000 --- a/docs/organizations/projects/save-project-data.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Save project data - Azure DevOps -titleSuffix: Azure DevOps -ms.custom: seodec18 -description: Save project data, like source code, custom build templates, build data, and work items. -ms.assetid: b944f980-81c0-4100-b0d8-2fc575c65693 -ms.subservice: azure-devops-projects -ms.topic: conceptual -ms.author: chcomley -author: chcomley -ms.date: 12/07/2018 -monikerRange: '<= azure-devops' ---- - -# Save project data - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -When you delete a project, you can't recover its data later. So, you should save project data. - -You can use the following procedures to save data that users most care about, such as source code, build data, and work items. - -* **Source code and custom build templates:** You can download your files as a zip file. Open ![Repository actions](../../media/icons/actions-icon.png) **actions** for the repository, file, or folder and choose **Download as Zip**. You can also **Download** from the right side of the screen to download either all of the files in the currently selected folder, or the currently selected file. - - > [!div class="mx-imgBorder"] - > ![Download code ](media/public/download-zip-file.png) - - This process doesn't save any change history or links to other artifacts. - - If you use Git, [clone your repositories](../../repos/git/gitquickstart.md) to retain the full project history and all the branches. - -* **Build data**: To save logs and data in your drop build folders, see [View build results](/previous-versions/ms181733(v=vs.140)). - -* **Work item tracking data:** Create a work item query and open it [using Excel](../../boards/backlogs/office/bulk-add-modify-work-items-excel.md). Save the Excel spreadsheet. - - This process doesn't save any attachments, change history, or links to other artifacts. - -To learn more about how we manage and protect your data, read our [Data Protection Overview](../../organizations/security/data-protection.md). - -::: moniker range="tfs-2018" - -You can easily save data stored for a project collection -by [making a backup of the database](/azure/devops/server/admin/backup/config-backup-sched-plan). You can also -use the previously mentioned steps. - -::: moniker-end diff --git a/docs/organizations/projects/tf31002-unable-connect-tfs.md b/docs/organizations/projects/tf31002-unable-connect-tfs.md deleted file mode 100644 index dfd5b591ae8..00000000000 --- a/docs/organizations/projects/tf31002-unable-connect-tfs.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: TF31002-Unable to connect -titleSuffix: Azure DevOps & TFS -description: Receive the error when you try to connect to Azure DevOps Services or an on-premises Azure DevOps Server. -ms.service: azure-devops-boards -ms.assetid: b5566a0b-55f8-4c76-aea2-6d1581a2c90d -ms.author: chcomley -author: chcomley -ms.topic: troubleshooting -ms.date: 04/22/2019 ---- -# TF31002: Unable to connect - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -You might receive this error when you try to connect to Azure DevOps Services or an on-premises Azure DevOps Server from Visual Studio. - -## You receive this error when you try to connect to Azure DevOps Services - -|Problem|Resolution| -|-------------|----------------| -|You don't have an active account or license.|Check with your administrator that you're a member of the account and have an active, valid license. See [Assign licenses to users](../accounts/add-organization-users.md) for details.| -|Your Azure DevOps Services organization is connected to the Azure Active Directory.|When your Azure DevOps Services organization is connected to a directory that is associated with a Microsoft 365 or Microsoft Azure subscription, only members in the directory can access the account.

      Check with your directory administrator to have them [create an organizational account for you or add your account to the directory as external member](/azure/active-directory/active-directory-create-users).| -|You can't switch between different organizational accounts.|If you work with several organizations that connect to different directories, such as accounts created from the Microsoft Azure Portal, the sign-out function might not work as expected. For example, you can't switch between different organizational accounts to connect to multiple accounts that are linked to directory tenants.

      When this problem occurs, you see a flashing blank sign in dialog box several times. Then, you receive either TF31002 or TF31003 error after you connect to or add a new connection in "Connect to Team Foundation Server" dialog box.

      To resolve this problem, apply the most recent [Visual Studio update](https://visualstudio.microsoft.com/downloads) .

      To learn more, see [You can't switch between different organizational accounts in Visual Studio Online](/troubleshoot/visualstudio/general/cannot-switch-accounts).| -|You want to sign in to Azure DevOps Services from Visual Studio using different credentials.|See [Connect to projects, Sign in with different credentials](connect-to-projects.md).| - -## When you try to connect to an on-premises Azure DevOps Server from your client computer - - If you determine that you're receiving this error from one computer but not others, or others aren't receiving this error, then check the problem resolutions that are outlined below. - -|Problem|Resolution| -|-------------|----------------| -|Your password has expired.|Verify that you entered your user ID and password correctly, and that your password hasn't expired.| -|You've entered an incorrect server URL.|Verify that you've entered the server URL correctly including the server name, port number, and protocol (http/https). See [Connect to projects](connect-to-projects.md) to learn more.| -|The TFS configuration has changed.|If the configuration for the on-premises Azure DevOps Server has changed, you must create a new connection. You might also need to [clear the client cache](connect-to-projects.md).| -|You work remotely and need to connect to a TFS Proxy server to check in files to Team Foundation version control.| [Configure Visual Studio to connect to TFS Proxy](connect-to-projects.md).| -|You're connecting to a later version of TFS than your Visual Studio client version.|Your version of Visual Studio or Team Explorer might be incompatible with Team Foundation Server. You might need to install one or more GDR packs. See [Requirements and compatibility](/azure/devops/server/requirements) for details.| -|Your firewall is blocking TFS services.|See [Allow a program to communicate through Windows Firewall](/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc766312(v=ws.10)).| -|Visual Studio stops responding when you run a query in Visual Studio.|Your computer might be configured to bypass the proxy server. Verify the configuration of the BypassProxyOnLocal setting on your computer. For more information, see [BypassProxyOnLocal Configuration](/previous-versions/visualstudio/visual-studio-2008/ee248646(v=vs.90)).| - -## Several users can't connect to an on-premises Azure DevOps Server - - If the problem occurs on more than one computer, contact your administrator to confirm whether the server is operational and available on the network. - - As an administrator, check the event logs for the application-tier server to try to pinpoint the problem. Also, you can use the following table to determine whether the server is misconfigured. In the table, problems that are more likely to occur appear first. Try the resolutions in the order in which they appear, which increases the chance that you can solve the problem quickly. - -|Problem|Resolution| -|-------------|----------------| -|The *TFSService* account password has expired or is incorrect.|Many services for Team Foundation Server will stop running when the service account for Team Foundation has expired. For more information, see [Change the service account or password for Team Foundation Server](/azure/devops/server/admin/change-service-account-password).| -|The application-tier server for Team Foundation is unavailable.|Verify whether each required service is running. If a required service isn't running, you must restart it. If necessary, set it to start automatically. For more information, see [Stop and start services, application pools, and websites](/azure/devops/server/admin/stop-start-services-pools).| -|The network is unavailable.|Verify whether your network is operational.| -|A website identity for Team Foundation is configured incorrectly.|Verify or correct the server binding assignments that are made to websites for Team Foundation. | -|Access to a website for Team Foundation has been restricted.|Verify or correct restrictions that are made to those websites that are based on IP addresses and domain names. | -|The firewall or ports are configured incorrectly.|Verify or correct port binding assignments for websites and port assignments for the firewall. First, you should open the administration console for Team Foundation, display the Application Tier page, and review the URL assignments. If necessary, you can click **Change URL** to modify the URL of a website. Next, you should verify the port assignments for Internet Information Services (IIS) and the ports that are allowed through the firewall. For more information, see [Review Server Status and Settings](/azure/devops/server/admin/stop-start-services-pools) and [Verify or Correct Port Assignments](/azure/devops/server/architecture/required-ports).| -|Trust relationships between domains aren't configured correctly.|If a group of users can't access Team Foundation Server, you might have trust issues between domains.| -|When users connect to different versions of TFS from Visual Studio, for example, they connect to TFS 2012 and then TFS 2008, they can get the TF31002 error.|This error can occur because the GUIDs for the TFS 2012 collection are the same as TFS 2008. The local client cache gets confused because it tries to maintain the same GUID-based local cache for both the 2008 server and the new Project Collection in 2012.

      To fix, run the **TFSConfig ChangeServerID** command. See [TFSConfig ChangeServerID command](/azure/devops/server/command-line/tfsconfig-cmd#changeserverid).| - \ No newline at end of file diff --git a/docs/organizations/projects/toc.yml b/docs/organizations/projects/toc.yml index 36c31d6e2ff..0e445fe1489 100644 --- a/docs/organizations/projects/toc.yml +++ b/docs/organizations/projects/toc.yml @@ -1,9 +1,6 @@ - name: About projects href: about-projects.md displayname: private, public, customize, configure, Agile, connect -- name: Project & team quick reference - href: project-team-quick-reference.md - displayname: administrator, users, actions, manage, concepts - name: Project summary href: project-vision-status.md displayname: readme, wiki, objective, administrator, summary, view, activity, members @@ -28,8 +25,8 @@ - name: Add users or groups to a project displayName: create, new, account, default, custom, access, permission href: ../security/add-users-team-project.md -- name: Work across projects FAQs - href: ../../project/work-across-projects-faqs.yml?toc=/azure/devops/organizations/toc.json +- name: Work across projects FAQs + href: ../../project/work-across-projects-faqs.yml?toc=/azure/devops/organizations/toc.json - name: Project configuration items: - name: Area & iteration paths @@ -53,7 +50,7 @@ href: delete-project.md displayname: remove, permission, allow, administrator - name: Restore a project - href: restore-project.md + href: delete-project.md#restore-a-deleted-project displayname: deleted, reinstate, settings - name: Change service visibility href: ../settings/set-services.md @@ -62,11 +59,8 @@ href: ../projects/make-project-public.md displayname: make, change, vs, repo, repository, - name: Save project data - href: save-project-data.md + href: delete-project.md#save-project-data displayname: export, backup, download, source, code, build, work, item - - name: Resources granted to project members - href: resources-granted-to-project-members.md - displayname: scope, group, organization, project, collection - name: Public projects items: - name: About public projects diff --git a/docs/organizations/security/about-permissions.md b/docs/organizations/security/about-permissions.md index bb4a0d97d84..34d42d98576 100644 --- a/docs/organizations/security/about-permissions.md +++ b/docs/organizations/security/about-permissions.md @@ -1,7 +1,7 @@ --- -title: Get started with permissions, access levels, and security groups +title: About permissions and security groups titleSuffix: Azure DevOps -description: Understand how you can manage permissions and access in Azure DevOps +description: Learn about permissions and access levels in Azure DevOps via inheritance, security groups, roles, and more. ms.subservice: azure-devops-security ms.assetid: toc: show @@ -9,44 +9,152 @@ ms.topic: conceptual ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 06/22/2023 +ai-usage: ai-assisted +ms.date: 02/10/2025 --- -# Get started with permissions and access +# About permissions and security groups [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -In this article, learn about how you can manage access levels and permissions via inheritance, security groups, roles, and more in Azure DevOps. Get started by understanding the following key concepts. +In this article, learn about access levels and permissions via inheritance, security groups, roles, and more in Azure DevOps. -- **[About permissions](#permissions)**: - - All users added to Azure DevOps are added to one or more default *security groups*. - - Security groups are assigned *permissions*, which either **Allow** or **Deny** access to a feature or task. - - Members of a security group *inherit the permissions* assigned to the group. - - Permissions are defined at different levels: organization/collection, project, or object. - - Other permissions are managed through *role-based assignments*, such as team administrator, extension management, and various pipeline resource roles. - - Administrators can define custom security groups to manage permissions for different functional areas. +For an overview of default permissions, see [Default permissions quick reference](permissions-access.md). -- **[About access levels](#access-levels)**: - - All users added to Azure DevOps are assigned to an *access level*, which grants or restricts access to select web portal features. - - There are three main access levels: **Stakeholder**, **Basic**, and **Basic + Test Plans**. - - Stakeholder access provides free access to an unlimited number of users to a limited set of features. For more information, see [Stakeholder access quick reference](stakeholder-access.md). +For more information, see [Security overview](security-overview.md). -::: moniker range="azure-devops" -- **[About preview features](#preview-features)**: - - As new features are introduced, users can enable or disable them through **Preview features** to access them. - - A small subset of new features is managed at the organization level and enabled or disabled by organization owners. -::: moniker-end +## Access levels + +All Azure DevOps users have an *access level*, which grants or restricts access to specific web portal features. + +There are three main access levels: **Stakeholder**, **Basic**, and **Basic + Test Plans**. + +Stakeholder access provides free access to an unlimited number of users with a limited set of features. Use this access level for users who don’t need paid access. +Don't use Stakeholder access instead of more limited permissions. Users with a Visual Studio subscription or a GitHub Enterprise license automatically get upgraded from Stakeholder to Basic access when they sign in. For more information, see [Stakeholder access quick reference](stakeholder-access.md). +To give a user access to Agile portfolio management or test case management features, [change access levels](change-access-levels.md), not permissions. For more information, see [About access levels](access-levels.md). -For example, most Azure DevOps users are added to the **Contributors** security group and granted **Basic** access level. The **Contributors** group provides read and write access to repositories, work tracking, pipelines, and more. **Basic** access provides access to all features and tasks for using Azure Boards, Azure Repos, Azure Pipelines, and Azure Artifacts. Users who require access to manage Azure Test Plans need to be granted **Basic + Test Plans** or **Advanced** access. +## Permissions + +All users in Azure DevOps belong to one or more default *security groups*. Security groups get assigned *permissions* that either **Allow** or **Deny** access to features or tasks. + +- Members inherit the permissions assigned to their security group. +- Permissions get defined at different levels: organization/collection, project, or object. +- Some permissions get managed through *role-based assignments* (for example, team administrator, extension management, or pipeline resource roles). +- Administrators can define custom security groups to manage permissions for different functional areas. + +Managing permissions in Azure DevOps involves two key groups: Project Collection Administrators and Project Administrators. + +**Project Collection Administrators:** +- Hold the highest authority within an organization or project collection. +- Perform all operations for the entire collection. +- Manage settings, policies, and processes for the organization. +- Create and manage all projects and extensions. + +**Project Administrators:** +- Operate at the project level. +- Manage security groups and permissions from the Project settings in the web portal. +- Handle permissions for specific objects contributors create within the project. + +### Permission states + +Assign permissions to grant or restrict access: + +**User or group has permission:** +- Allow +- Allow (inherited) +- Allow (system) + +**User or group doesn't have permission:** +- Deny +- Deny (inherited) +- Deny (system) +- Not set + +|Permission state |Description | +|---------|---------| +|**Allow** |Explicitly grants users to perform specific tasks, and isn't inherited from group membership. | +|**Allow (inherited)** |Grants group members to perform specific tasks. | +|**Allow (system)** |Grants permission that takes precedence before user permissions. Uneditable and stored in a configuration database, invisible to users. | +|**Deny** |Explicitly restricts users from performing specific tasks, and isn't inherited from group membership. For most groups and almost all permissions, **Deny** overrides **Allow**. If a user belongs to two groups, and one of them has a specific permission set to **Deny**, that user can't perform tasks that require that permission even if they belong to a group that has that permission set to **Allow**. | +|**Deny (inherited)** |Restricts group members from performing specific tasks. Overrides an explicit **Allow**. | +|**Deny (system)** | Restricts permission that takes precedence before user permissions. Uneditable and stored in a configuration database, invisible to users. | +|**Not set** | Implicitly denies users the ability to perform tasks that require that permission, but allows membership in a group that does have that permission to take precedence, also known as **Allow (inherited)** or **Deny (inherited)**. | + +Members of the **Project Collection Administrators** or **Team Foundation Administrators** groups might always receive permissions even if denied in another group. The following examples explain this scenario further: +- A user might still access project settings or manage users. However, for tasks like work item deletion or pipeline management, being a member of the Project Collection Administrators group doesn't override **Deny** permissions set elsewhere. +- If a user is denied permission to delete work items in a specific project, they can't delete work items even if they're part of the Project Collection Administrators group. Similarly, if pipeline permissions are denied, they can't manage or run pipelines despite their administrative role. + +> [!WARNING] +> When you modify a permission for a group it affects all users in that group. Even a single permission change can impact hundreds of users, so it’s crucial to consider the potential effects before making any adjustments. + +## Permission inheritance + +Permissions follow a hierarchy, allowing inheritance from a parent node or overriding it. + +**Group inheritance:** + +- Users inherit permissions from the groups they belong to. +- If a user has an **Allow** permission directly or through group membership but also has a **Deny** permission through another group, the **Deny** permission takes precedence. +- Members of Project Collection Administrators or Team Foundation Administrators retain most allowed permissions, even if they belong to other groups that deny those permissions (except for work item operations). + +**Object-level inheritance:** + +Object-level permissions, assigned to nodes like areas, iterations, version control folders, and work item query folders, get inherited down the hierarchy. + +**Permission inheritance and specificity rules:** + +- Explicit permissions always take precedence over inherited ones. +- Permissions set at a higher-level node get inherited by all subnodes unless explicitly overridden. +- If a permission isn't explicitly allowed or denied for a subnode, it inherits the permission from its parent. +- If a permission is explicitly set for a subnode, the parent’s permission isn't inherited, regardless of whether allowed or denied. + +**Specificity:** + +In the object hierarchy, specificity trumps inheritance. The most specific permission takes precedence if conflicting permissions exist. + +**Example:** + +- Explicitly **Deny** on ‘area-1’ (parent node). +- Explicitly **Allow** for ‘area-1/sub-area-1’ (child node). +- In this case, the user receives an **Allow** on ‘area-1/sub-area-1’, overriding the inherited **Deny** from the parent node. + +To understand why a permission is inherited, you can pause over a permission setting, and then select **Why?** To open a **Security** page, see [View permissions](view-permissions.md). + +::: moniker range="= azure-devops" -Administrators should be added to the Project Collection Administrators or Project Administrators group. Administrators manage security groups and permissions from the web portal, primarily from **Project settings**. Contributors manage permissions for objects they create from the web portal as well. +> [!NOTE] +> To enable the **Project Permissions settings page** preview page, see [Enable preview features](../../project/navigation/preview-features.md). + +::: moniker-end + +#### [Preview page](#tab/preview-page) -For an overview of default permissions, see [Default permissions quick reference](permissions-access.md). +::: moniker range="= azure-devops" +> [!div class="mx-imgBorder"] +> ![Screenshot showing Permissions dialog, preview page, Why link annotated.](media/view-permissions/about-permissions-information-preview.png) - +A new dialog opens that shows the inheritance information for that permission. +::: moniker-end -## Security groups and membership +::: moniker range="< azure-devops" +The preview user interface for the Project Permissions settings page isn't available for Azure DevOps Server 2020 and earlier versions. +::: moniker-end + +#### [Current page](#tab/current-page) + +> [!div class="mx-imgBorder"] +> ![Screenshot showing Permissions dialog, current page, Why link annotated.](media/about-permissions-why.png) + +A new window shows the inheritance information for that permission. + +![Screenshot showing the Permissions trace dialog.](media/about-permissions-trace.png) + +* * * + +## Security groups and membership + +Security groups assign specific permissions to their members. With the creation of an organization, collection, or project—Azure DevOps creates a set of default security groups, which are automatically assigned default permissions. More security groups are defined with the following actions: - When you create custom security groups at the following levels: @@ -59,307 +167,153 @@ You can't create an object-level security group, but you can assign a custom gro ### Default security groups -::: moniker range="azure-devops" +Most Azure DevOps users get added to the **Contributors** security group and granted **Basic** access level. The **Contributors** group provides read and write access to repositories, work tracking, pipelines, and more. **Basic** access provides access to all features and tasks for using Azure Boards, Azure Repos, Azure Pipelines, and Azure Artifacts. Users who require access to manage Azure Test Plans need to be granted **Basic + Test Plans** or **Advanced** access. +::: moniker range="azure-devops" The following security groups are defined by default for each project and organization. You typically add users or groups to the **Readers**, **Contributors**, or **Project Administrators** groups. -> [!div class="mx-tdBreakAll"] -> | Project | Organization or Collection| -> |-------------|----------| -> |- Build Administrators
      - Contributors
      - Project Administrators
      - Project Valid Users
      - Readers
      - Release Administrators
      - *TeamName* Team |- Project Collection Administrators
      - Project Collection Build Administrators
      - Project Collection Build Service Accounts
      - Project Collection Proxy Service Accounts
      - Project Collection Service Accounts
      - Project Collection Test Service Accounts
      - Project Collection Valid Users
      - Project-Scoped Users
      - Security Service Group | + +| Project | Organization or Collection| +|-------------|----------| +|- Build Administrators
      - Contributors
      - Project Administrators
      - Project Valid Users
      - Readers
      - Release Administrators
      - *TeamName* Team |- Project Collection Administrators
      - Project Collection Build Administrators
      - Project Collection Build Service Accounts
      - Project Collection Proxy Service Accounts
      - Project Collection Service Accounts
      - Project Collection Test Service Accounts
      - Project Collection Valid Users
      - Project-scoped Users
      - Security Service Group | For a description of each of these groups, see [Security groups, service accounts, and permissions](permissions.md). For default permission assignments made to the most common default security groups, see [Default permissions and access](permissions-access.md). - ::: moniker-end ::: moniker range="< azure-devops" - The following security groups are defined by default for each project and project collection. You typically add users or groups to the **Readers**, **Contributors**, or **Project Administrators** groups. -The following list indicates the latest groups defined for TFS 2017 and later versions. For earlier versions of Azure DevOps, the list may differ. Only add service accounts to [Azure DevOps service account groups](/azure/devops/server/admin/service-accounts-dependencies). To understand valid user groups, see [Valid user groups](#validusers) later in this article. - -> [!div class="mx-tdBreakAll"] -> | Project level | Collection level| -> |-------------|----------| -> |- Build Administrators
      - Contributors
      - Project Administrators
      - Project Valid Users
      - Readers
      - Release Administrators
      - *TeamName* Team |- Project Collection Administrators
      - Project Collection Build Administrators
      - Project Collection Build Service Accounts
      - Project Collection Proxy Service Accounts
      - Project Collection Service Accounts
      - Project Collection Test Service Accounts
      - Project Collection Valid Users
      - Security Service Group | +Only add service accounts to [Azure DevOps service account groups](/azure/devops/server/admin/service-accounts-dependencies). To understand valid user groups, see [Valid user groups](#valid-user-groups) later in this article. + +| Project level | Collection level| +|-------------|----------| +|- Build Administrators
      - Contributors
      - Project Administrators
      - Project Valid Users
      - Readers
      - Release Administrators
      - *TeamName* Team |- Project Collection Administrators
      - Project Collection Build Administrators
      - Project Collection Build Service Accounts
      - Project Collection Proxy Service Accounts
      - Project Collection Service Accounts
      - Project Collection Test Service Accounts
      - Project Collection Valid Users
      - Security Service Group | ::: moniker-end -For users tasked with managing project-level features—such as, teams, area and iteration paths, repositories, service hooks, and service end points—add them to the **Project Administrators** group. -For users tasked with managing organization or collection-level features—such as, projects, policies, processes, retention policies, agent and deployment pools, and extensions—add them to the **Project Collection Administrators** group. For more information, see [About user, team, project, and organization-level settings](../settings/about-settings.md). +For users tasked with managing project-level features—such as, teams, area and iteration paths, repositories, service hooks, and service end points—add them to the **Project Administrators** group. -For a description of each group and each permission, see [Permissions and groups reference, Groups](permissions.md#groups). +For users tasked with managing organization or collection-level features—such as, projects, policies, processes, retention policies, agent and deployment pools, and extensions—add them to the **Project Collection Administrators** group. For more information, see [About user, team, project, and organization-level settings](../settings/about-settings.md). ### Membership, permission, and access level management Azure DevOps controls access through these three inter-connected functional areas: - **Membership management** supports adding individual user accounts and groups to default security groups. Each default group is associated with a set of default permissions. All users added to any security group are added to the Valid Users group. A valid user is someone who can connect to a project, collection, or organization. - -- **Permission management** controls access to specific functional tasks at different levels of the system. Object-level permissions set permissions on a file, folder, build pipeline, or a shared query. Permission settings correspond to **Allow**, **Deny**, **Inherited allow**, **Inherited deny**, **System allow**, **System deny**, and **Not set**. For more information, see [Permission inheritance and security groups](#inheritance) later in this article. - -- **Access level management** controls access to web portal features. Based on what has been purchased for a user, administrators set the user's access level to **Stakeholder**, **Basic**, **Basic + Test**, or **Visual Studio Enterprise** (previously **Advanced**). +- **Permission management** controls access to specific functional tasks at different levels of the system. Object-level permissions set permissions on a file, folder, build pipeline, or a shared query. Permission settings correspond to **Allow**, **Deny**, **Inherited allow**, **Inherited deny**, **System allow**, **System deny**, and **Not set**. +- **Access level management** controls access to web portal features. Based on purchased for a user, administrators set the user's access level to **Stakeholder**, **Basic**, **Basic + Test**, or **Visual Studio Enterprise** (previously **Advanced**). Each functional area uses security groups to simplify management across the deployment. You add users and groups through the web administration context. Permissions are automatically set based on the security group that you add users to. Or permissions get based on the object, project, collection, or server level to which you add groups. ::: moniker range="azure-devops" -Security group members can be a combination of users, other groups, and Azure Active Directory groups. +Security group members can be a combination of users, other groups, and Microsoft Entra groups. ::: moniker-end + ::: moniker range="< azure-devops" Security group members can be a combination of users, other groups, and Active Directory groups or a Workgroup. You can create [local groups or Active Directory (AD) groups to manage your users](/azure/devops/server/admin/setup-ad-groups). - - ::: moniker-end - -       +### Active Directory and Microsoft Entra security groups -### Active Directory and Azure Active Directory security groups - -You can populate security groups by adding individual users. However, for ease of management, it's easier if you populate these groups by using Azure Active Directory (Azure AD) for Azure DevOps Services and Active Directory (AD) or Windows user groups for Azure DevOps Server. This method enables you to manage group membership and permissions more efficiently across multiple computers. +You can populate security groups by adding individual users. But, for ease of management, it's more efficient to populate these groups using Microsoft Entra ID for Azure DevOps Services and Active Directory (AD) or Windows user groups for Azure DevOps Server. This approach allows you to manage group membership and permissions more effectively across multiple computers. -If you only have to manage a small set of users, then you can skip this step. However, if you foresee that your organization may grow, you may want to set up AD or Azure AD. Also, if you plan on paying for extra services, you need to set up Azure AD for use with Azure DevOps to support billing. +If you only need to manage a small set of users, you can skip this step. But, if you anticipate that your organization might grow, consider setting up Active Directory or Microsoft Entra ID. Also, if you plan to use extra services, it's essential to configure Microsoft Entra ID for use with Azure DevOps to support billing. > [!NOTE] -> Without Azure AD, all Azure DevOps users must sign in using Microsoft accounts, and you must manage account access by individual user accounts. Even if you manage account access using Microsoft accounts, you need to set up an [Azure subscription in order to manage billing](../billing/set-up-billing-for-your-organization-vs.md). +> Without Microsoft Entra ID, all Azure DevOps users must sign in using Microsoft accounts, and you must manage account access by individual user accounts. Even if you manage account access using Microsoft accounts, set up an [Azure subscription to manage billing](../billing/set-up-billing-for-your-organization-vs.md#set-up-billing). ::: moniker range="azure-devops" +To set up Microsoft Entra ID for use with Azure DevOps Services, see [Connect your organization to Microsoft Entra ID](../accounts/connect-organization-to-azure-ad.md). -To set up Azure Active Directory for use with Azure DevOps Services, see [Connect your organization to Azure Active Directory](../accounts/connect-organization-to-azure-ad.md). - -When your organization is connected to Azure Active Directory, there are many organization policies that you can enable or disable to secure your organization. For more information, see [About security, authentication, and authorization, Security-policies](about-security-identity.md#security-policies). - -To manage organizational access with Azure AD, refer to the following articles: +When your organization is connected to Microsoft Entra ID, you can define and manage various organization policies to enhance security and streamline access to applications. For more information, see [About security, Security-policies](about-security-identity.md#security-policies). -* [Add or delete users using Azure Active Directory](/azure/active-directory/fundamentals/add-users-azure-active-directory) -* [Troubleshoot access with Azure Active Directory](../accounts/faq-azure-access.yml) +To manage organizational access with Microsoft Entra ID, see the following articles: -Azure DevOps registers the changes that get made to an Azure AD group within an hour of that change in Azure AD. Any permissions that are inherited via group membership get refreshed. If you want to refresh your Azure AD membership and inherited permissions in Azure DevOps, sign out and then sign back in, or trigger a [refresh to reevaluate your permission](request-changes-permissions.md#refresh-or-re-evaluate-your-permissions). +* [Add or delete users using Microsoft Entra ID](/azure/active-directory/fundamentals/add-users-azure-active-directory) +* [Troubleshoot access with Microsoft Entra ID](../accounts/faq-azure-access.yml) +Azure DevOps registers the changes that get made to a Microsoft Entra group within an hour of that change in Microsoft Entra ID. Any inherited permissions via group membership get refreshed. To refresh your Microsoft Entra membership and inherited permissions in Azure DevOps, sign out and then sign back in, or [trigger a refresh to reevaluate your permission](request-changes-permissions.md#refresh-or-reevaluate-your-permissions). ::: moniker-end ::: moniker range="< azure-devops" - To set up Active Directory for use with Azure DevOps Server, see the following articles: * [Install Active Directory Domain Services (Level 100)](/windows-server/identity/ad-ds/deploy/install-active-directory-domain-services--level-100-) * [Active Directory Domain Services Getting Started](/windows-server/identity/ad-ds/ad-ds-getting-started). -Install Active Directory prior to installing Azure DevOps Server. - +Install Active Directory before you install Azure DevOps Server. ::: moniker-end - - ### Valid user groups -When you add accounts of users directly to a security group, they're automatically added to one of the valid user groups. +When you add accounts of users directly to a security group, they automatically get added to one of the following valid user groups. ::: moniker range="azure-devops" -- Project Collection Valid Users: All members added to an organization-level group. -- Project Valid Users: All members added to a project-level group. +- **Project Collection Valid Users:** All members added to an organization-level group. +- **Project Valid Users:** All members added to a project-level group. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" - - - - ::: moniker range="azure-devops" -### Project-Scoped Users group +### Project-scoped users group -By default, users added to an organization can view all organization and project information and settings. These settings include list of users, list of projects, billing details, usage data, and more that is accessed through **Organization settings**. +By default, users added to an organization can view all organization and project information and settings. These settings include the list of users, the list of projects, billing details, usage data, and more, which you can access through **Organization settings**. -[!INCLUDE [project-scoped-users-important-note](../../includes/project-scoped-users-important-note.md)] - -To restrict select users, such as Stakeholders, Azure Active Directory guest users, or members of a particular security group, you can enable the **Limit user visibility and collaboration to specific projects** preview feature for the organization. Once that is enabled, any user or group added to the **Project-Scoped Users** group, are restricted from accessing the **Organization settings** pages, except for **Overview** and **Projects**; and are restricted to accessing only those projects to which they've been added to. +To restrict specific users, such as Stakeholders, Microsoft Entra guest users, or members of a particular security group, you can enable the **Limit user visibility and collaboration to specific projects** preview feature for the organization. Once enabled, any user or group added to the **Project-scoped Users** group is restricted from accessing the **Organization settings** pages, except for **Overview** and **Projects**. Also, they only have access to the projects to which they're added. [!INCLUDE [project-scoped-users-warning](../../includes/project-scoped-users-warning.md)] -To enable this feature, see [Manage or enable features](../../project/navigation/preview-features.md#account-level). +For more information, see [Manage preview features](../../project/navigation/preview-features.md). [!INCLUDE [version-all](./includes/hidden-security-groups.md)] ::: moniker-end + -## Access levels - -Access levels control which features are visible to users in the web portal. Access depends on user licenses. +## Role-based permissions -If you want to give a user access to Agile portfolio management or test case management features, [change access levels](change-access-levels.md), not permissions. - -Setting the access level for users or groups doesn't provide them access to a project or the web portal. Only users or groups added to a team or security group can connect to a project and the web portal. Make sure your users have both the permissions and the access level they need. You do so by making sure they're [added to the project or a team](add-users-team-project.md). +With Role-based permissions, you assign user accounts or security groups to a role, with each role assigned one or more permissions. Here are the primary roles and links to more information. - +- [Artifact or package feed security roles](../../artifacts/feeds/feed-permissions.md): Roles support various permission levels to edit and manage package feeds. +- [Marketplace extension Manager role](../../marketplace/grant-permissions.md): Members of the Manager role can install extensions and respond to requests for extensions to be installed. +- [Pipeline security roles](about-security-roles.md): Several roles are used to manage library resources, project-level, and collection-level pipeline resources. +- [Team administrator role](../settings/manage-teams.md) Team administrators are able to manage all team tools. -## Permissions +For more information, see [About security roles](about-security-roles.md). ::: moniker range="azure-devops" - -As shown in the following image, security groups defined at the project and collection-level can be assigned to permissions assigned at the object, project, and organization-level. +The following image illustrates how security groups defined at the project and collection level can assign permissions to objects, projects, and the organization. :::image type="content" source="media/about-security/security-groups-permission-management-cloud.png" alt-text="Conceptual image mapping default security groups to permission levels, cloud"::: - ::: moniker-end ::: moniker range="< azure-devops" +The following image illustrates how security groups defined at the project and collection-level can be assigned to permissions assigned at the object, project, and collection level. You can only define server-level security groups to server-level permissions. -As shown in the following image, security groups defined at the project and collection-level can be assigned to permissions assigned at the object, project, and collection level. You can only define server-level security groups to server-level permissions. -::: moniker-end - -::: moniker range=">= azure-devops-2019 <= azure-devops-2020" :::image type="content" source="media/about-security/security-groups-permission-management-on-premises.png" alt-text="Conceptual image mapping default security groups to permission levels, on-premises"::: - -::: moniker-end - -::: moniker range="< azure-devops-2019" -![Conceptual image of security groups and permission levels, TFS-2018 and earlier versions](media/permissions/permissions-overview.png) -::: moniker-end - -For a description of each default security group, see [Security groups, service accounts, and permissions](permissions.md#groups). - - -### Permission states - -A permission can have the following assignments. They grant or restrict access as indicated. - -User or group *has* permissions to perform a task: -- **Allow** -- **Allow (inherited)** -- **Allow (system)** - -User or group *doesn't have* permission to perform a task: -- **Deny** -- **Deny (inherited)** -- **Deny (system)** -- **Not set** - -|Permission state |Description | -|---------|---------| -|**Allow** |Explicitly grants users to perform specific tasks, and isn't inherited from group membership. | -|**Allow (inherited)** |Grants group members to perform specific tasks. | -|**Allow (system)** |Grants permission that takes precedence before user permissions. Uneditable and stored in a configuration database, invisible to users. | -|**Deny** |Explicitly restricts users from performing specific tasks, and isn't inherited from group membership. For most groups and almost all permissions, **Deny** overrides **Allow**. If a user belongs to two groups, and one of them has a specific permission set to **Deny**, that user can't perform tasks that require that permission even if they belong to a group that has that permission set to **Allow**. | -|**Deny (inherited)** |Restricts group members from performing specific tasks. Overrides an explicit **Allow**. | -|**Deny (system)** | Restricts permission that takes precedence before user permissions. Uneditable and stored in a configuration database, invisible to users. | -|**Not set** | Implicitly denies users the ability to perform tasks that require that permission, but allows membership in a group that does have that permission to take precedence, also known as **Allow (inherited)** or **Deny (inherited)**. | - -In some cases, members of the **Project Collection Administrators** or **Team Foundation Administrators** groups may always get the permission even if they're denied that permission in a different group. In other cases such as work item deletion or pipelines, being a member of Project Collection Administrators group doesn't bypass **Deny** permissions set elsewhere. - -> [!WARNING] -> When you change a permission for a group, it changes that permission for all users who are members of that group. Depending on the size of the group, you might affect the ability of hundreds of users to do their jobs by changing just one permission. So make sure you understand the potential effects before you make a change. - - - -## Permission inheritance and security groups - -Some permissions are managed through a hierarchy. Within this hierarchy, -permissions can be inherited from the parent or overridden. Security groups assign a set of permissions to those members of the group. For example, members of the **Contributors** group or **Project Administrators** group are assigned the permissions that are set as **Allowed** to those groups. - -If a permission isn't directly allowed or denied for a user, then it may be inherited in the following ways. - -- Users inherit permissions from the groups to which they belong. When a user has a direct or group membership **Allow** permission, a direct or group membership **Deny** permission overrides it. - - Members of **Project Collection Administrators** or **Team Foundation Administrators** retain most allowed permissions, even if they belong to other groups that deny those permissions. Work item operation permissions are the exception to this rule. -- Object-level permissions that are assigned for nodes of a hierarchy - -areas, iterations, version control folders, work item query folders - -are inherited down the hierarchy. -That is, a user's permissions that are set at `area-1` get inherited by `area-1/sub-area-1`, -if the same permission isn't explicitly allowed or denied for `area-1/sub-area-1`. -If a permission is set explicitly for an object, like `area-1/sub-area-1`, -then the parent node isn't inherited, regardless of whether it's denied or allowed. -If it's not set, then the permissions for that node are inherited from the closest ancestor -that has the permission explicitly set. Lastly, in the object hierarchy, specificity trumps inheritance. For example, a user whose permissions are explicitly set to **Deny** on 'area-1' but are also explicitly set to **Allow** for 'area-1/sub-area-1' receives an **Allow** on 'area-1/sub-area-1'. - -To understand why a permission is inherited, you can pause over a permission setting, and then choose **Why?** To open a **Security** page, see [View permissions](view-permissions.md). - -::: moniker range="= azure-devops" - -> [!NOTE] -> To enable the **Project Permissions settings page** preview page, see [Enable preview features](../../project/navigation/preview-features.md). - ::: moniker-end -#### [Preview page](#tab/preview-page) - -::: moniker range="= azure-devops" - -> [!div class="mx-imgBorder"] -> ![Permissions dialog, preview page, Why link annotated.](media/view-permissions/about-permissions-information-preview.png) - -A new dialog opens that shows the inheritance information for that permission. - -::: moniker-end - -::: moniker range="< azure-devops" - -The preview user interface for the Project Permissions settings page isn't available for Azure DevOps Server 2020 and earlier versions. - -::: moniker-end - -#### [Current page](#tab/current-page) - -> [!div class="mx-imgBorder"] -> ![Permissions dialog, current page, Why link annotated.](media/about-permissions-why.png) - -A new window opens that shows the inheritance information for that permission. - -![Permissions trace dialog.](media/about-permissions-trace.png) - -* * * - -### Best practices for permissions - -**Do:** -- Use Azure Active Directory, Active Directory, or Windows security groups when you manage lots of users. -- When you add a team, consider which permissions you want to assign to team leads, scrum masters, and other team members. Consider who creates and modifies area paths, iteration paths, and queries. -- When you add many teams, consider creating a **Team Administrators** custom group where you can allocate a subset of the permissions available to **Project Administrators**. -- Consider granting the [work item query folders **Contribute**](../../boards/queries/set-query-permissions.md) permission to users or groups that require the ability to create and share work item queries for the project. - -**Don't:** -- Don't add users to multiple security groups, which contain different permission levels. In certain cases, a **Deny** permission level may override an **Allow** permission level. -- Don't change the default assignments made to the Valid Users groups. If you remove or set the **View instance-level information** permission to **Deny** for one of the Valid Users groups, no users in the group are able to access the project, collection, or deployment, depending on the group you set. -- Don't assign permissions that are noted as 'Assign only to service accounts' to user accounts. - - - -## Role-based permissions - -With Role-based permissions, you assign user accounts or security groups to a role, with each role assigned one or more permissions. Here are the primary roles and links to more information. - -- [Artifact or package feed security roles](../../artifacts/feeds/feed-permissions.md): Roles support various permission levels to edit and manage package feeds. -- [Marketplace extension Manager role](../../marketplace/grant-permissions.md): Members of the Manager role can install extensions and respond to requests for extensions to be installed. -- [Pipeline security roles](about-security-roles.md): Several roles are used to manage library resources, project-level and collection-level pipeline resources. -- [Team administrator role](../settings/manage-teams.md) Team administrators are able to manage all team tools. - Members of the Project Administrators or Project Collection Administrators groups can manage all team tools for all teams. -## Preview features - -Feature flags control access to select, new features. Periodically, Azure DevOps introduces new features by placing them behind a feature flag. Project members and organization owners can enable or disable preview features. For more information, see [Manage or enable features](../../project/navigation/preview-features.md). +## Preview features + +Feature flags control access to new features. Azure DevOps periodically introduces new features behind a feature flag. Project members and organization owners can enable or disable preview features. For more information, see [Manage or enable features](../../project/navigation/preview-features.md). ## Next steps @@ -371,30 +325,17 @@ Feature flags control access to select, new features. Periodically, Azure DevOps ::: moniker range="= azure-devops" - [Troubleshoot access and permission issues](troubleshoot-permissions.md) -- [About security, authentication, and authorization](about-security-identity.md) -- [What is Azure Active Directory?](/azure/active-directory/active-directory-whatis) -- [Get started with Azure AD](/azure/active-directory/get-started-azure-ad) -- [Permissions and groups reference](permissions.md) -- [Security and permission management tools](security-tools-reference.md) -- [Add users to an organization](../accounts/add-organization-users.md) +- [Learn about security, authentication, and authorization](about-security-identity.md) +- [Reference permissions and groups](permissions.md) - [Add and manage security groups](add-manage-security-groups.md) -- [Manage tokens, namespaces, permissions](manage-tokens-namespaces.md) -- [How billing works](../billing/overview.md) -- [Set up billing to pay for users, pipelines, and cloud-based load testing in Azure DevOps](../billing/set-up-billing-for-your-organization-vs.md) -::: moniker-end +::: moniker-end ::: moniker range="< azure-devops" -- [Troubleshoot access and permission issues](troubleshoot-permissions.md)[About security, authentication, and authorization](about-security-identity.md) -- [Active Directory Domain Services Overview](/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview) -- [AD DS Getting Started](/windows-server/identity/ad-ds/ad-ds-getting-started) -- [Permissions and groups reference](permissions.md) -- [Security and permission management tools](security-tools-reference.md) +- [Get started with AD DS](/windows-server/identity/ad-ds/ad-ds-getting-started) +- [Reference permissions and groups](permissions.md) - [Add users to a team or a project](../../organizations/security/add-users-team-project.md) - [Add and manage security groups](add-manage-security-groups.md) -- [Manage tokens, namespaces, permissions](manage-tokens-namespaces.md) -- [Permissions and groups reference](permissions.md) -- [Security and permission management tools](security-tools-reference.md) + ::: moniker-end - diff --git a/docs/organizations/security/about-security-identity.md b/docs/organizations/security/about-security-identity.md index 13b3909a3d9..7521ab5b231 100644 --- a/docs/organizations/security/about-security-identity.md +++ b/docs/organizations/security/about-security-identity.md @@ -7,16 +7,16 @@ ms.author: chcomley author: chcomley ms.topic: overview monikerRange: '<= azure-devops' -ms.date: 03/23/2023 +ms.date: 07/11/2024 --- # About security, authentication, and authorization [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Azure DevOps employs many security concepts to ensure only those users who should have access to features, functions, and data have access. Accounts get access to Azure DevOps through authentication of their security credentials and authorization of their account entitlements to access a feature or function. +Azure DevOps employs various security concepts to ensure that only authorized users can access features, functions, and data. Users gain access to Azure DevOps through the authentication of their security credentials and the authorization of their account entitlements. The combination of both determine the user's access to specific features or functions. -This article builds on the information provided in [Get started with permissions, access, and security groups](../security/about-permissions.md). Administrators benefit from understanding the account types, authentication methods, authorization methods, and policies used to secure Azure DevOps. +This article builds on the information provided in [Get started with permissions, access, and security groups](../security/about-permissions.md). Administrators can benefit from understanding the account types, authentication methods, authorization methods, and policies used to secure Azure DevOps. ::: moniker range="azure-devops" @@ -30,7 +30,6 @@ This article builds on the information provided in [Get started with permissions - Service principals or managed identities - Job agents - **Authentication** - User credentials - Windows authentication @@ -48,7 +47,6 @@ This article builds on the information provided in [Get started with permissions - Feature flags - Security namespaces & permissions - **Policies** - Privacy policy URL - Application connection and security policies @@ -100,114 +98,103 @@ This article builds on the information provided in [Get started with permissions [!INCLUDE [alt-creds-deprecation-notice](../../includes/alt-creds-deprecation-notice.md)] -Both our cloud service, Azure DevOps Services, and on-premises server, Azure DevOps Server, support software development projects, from planning through deployment. Azure DevOps uses Microsoft Azure's Platform as a Service infrastructure and many of Azure's services, including Azure SQL databases, to deliver a reliable, globally available service for your development projects. +Both Azure DevOps Services (cloud) and Azure DevOps Server (on-premises) support software development from planning to deployment. Each platform leverages Microsoft Azure's Platform as a Service infrastructure and services, including Azure SQL databases, to provide a reliable, globally available service for your projects. ::: moniker range="azure-devops" -For more information about the steps Microsoft takes to keep your projects in Azure DevOps Services safe, available, secure, and private, see this white paper, [Azure DevOps Services Data Protection Overview](../../organizations/security/data-protection.md). +For more information about how Microsoft ensures your Azure DevOps Services projects are safe, available, secure, and private, see the [Azure DevOps Services data protection overview](../../organizations/security/data-protection.md). ::: moniker-end - + ## Accounts -While the main types of accounts of interest are the human user accounts that you add to your organization or project, Azure DevOps supports other types of accounts to perform various operations. These include the following account types. - +While human user accounts are the primary focus, Azure DevOps also supports various other account types for different operations: ::: moniker range="azure-devops" -- **Organization owner**: The creator of an Azure DevOps Services organization or assigned owner. To learn who is the organization owner for your organization, see [Look up the organization owner](look-up-organization-owner.md). -- **Service accounts**: Internal Azure DevOps accounts used to support a specific service, such as Agent Pool Service, PipelinesSDK. For descriptions of service accounts, see [Security groups, service accounts, and permissions](permissions.md#collection-level-groups). -- **Service principals or managed identities**: [Azure AD applications or managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) that have been added to your organization to perform actions on behalf of a third-party application. Some service principals refer to internal Azure DevOps accounts to support internal operations. +- **Organization owner**: The creator of an Azure DevOps Services organization or assigned owner. To find the owner for your organization, see [Look up the organization owner](look-up-organization-owner.md). +- **Service accounts**: Internal Azure DevOps organization used to support a specific service, such as Agent Pool Service, PipelinesSDK. For descriptions of service accounts, see [Security groups, service accounts, and permissions](permissions.md#collection-level-groups). +- **Service principals or managed identities**: [Microsoft Entra applications or managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) added to your organization to perform actions on behalf of a third-party application. Some service principals refer to internal Azure DevOps organization to support internal operations. - **Job agents**: Internal accounts used to run specific jobs on a regular schedule. - **Third party accounts**: Accounts that require access to support Web hooks, service connections, or other third-party applications. -Throughout these docs, users can refer to all identities that have been added to the Users Hub, which can include human users and service principals. +Throughout our security-related articles, "users" refers to all identities added to the Users Hub, which can include human users and service principals. ::: moniker-end ::: moniker range="< azure-devops" -- **Service accounts**: Internal Azure DevOps accounts used to support a specific service, such as Agent Pool Service, PipelinesSDK. For descriptions of service accounts, see [Security groups, service accounts, and permissions](permissions.md#collection-level-groups). -- **Service principals or managed identities**: Azure AD applications or managed identities that have been added to your organization to perform actions on behalf of a third-party application. Some service principals refer to internal Azure DevOps accounts to support internal operations. +- **Service accounts**: Internal Azure DevOps organization used to support a specific service, such as Agent Pool Service, PipelinesSDK. For descriptions of service accounts, see [Security groups, service accounts, and permissions](permissions.md#collection-level-groups). +- **Service principals or managed identities**: Microsoft Entra applications or managed identities added to your organization to perform actions on behalf of a third-party application. Some service principals refer to internal Azure DevOps organization to support internal operations. - **Job agents**: Internal accounts used to run specific jobs on a regular schedule. - **Third party accounts**: Accounts that require access to support Web hooks, service connections, or other third-party applications. ::: moniker-end -The most effective means for managing accounts is by [adding them to security groups](about-permissions.md#security-group-membership). +The most effective way to manage accounts is by [adding them to security groups](about-permissions.md#security-groups-and-membership). > [!NOTE] -> The organization owner and members of the Project Collection Administrators group are granted full access to most all features and functions. +> The organization owner and members of the Project Collection Administrators group are granted full access to nearly all features and functions. - + ## Authentication -Authentication verifies an account identity based on the credentials provided when they sign into Azure DevOps. These systems integrate with and rely upon the security features provided by these other systems: -- Azure Active Directory (Azure AD) +Authentication verifies an account's identity based on the credentials provided during sign-in to Azure DevOps. These systems integrate with and rely on the security features of the following other systems: +- Microsoft Entra ID - Microsoft account (MSA) - Active Directory (AD) -Azure AD and MSA support cloud authentication. We recommend Azure AD when you need to manage a large group of users. Otherwise, if you have a small user base accessing your organization in Azure DevOps, you can use Microsoft accounts. For more information, see [About accessing Azure DevOps with Azure Active Directory (Azure AD)](../accounts/access-with-azure-ad.md). +Microsoft Entra ID and MSA support cloud authentication. We recommend using Microsoft Entra ID for managing a large group of users. For a small user base accessing your Azure DevOps organization, Microsoft accounts are sufficient. For more information, see [About accessing Azure DevOps with Microsoft Entra ID](../accounts/access-with-azure-ad.md). -For on-premises deployments, AD is recommended when managing a large group of users. For more information, see [Set up groups for use in on-premises deployments](/azure/devops/server/admin/setup-ad-groups). +For on-premises deployments, AD is recommended for managing a large group of users. For more information, see [Set up groups for use in on-premises deployments](/azure/devops/server/admin/setup-ad-groups). ### Authentication methods, integrating with other services and apps -Other applications and services can integrate with services and resources in Azure DevOps. To access your account without asking for user credentials multiple times, apps can use the following authentication methods. +Other applications and services can integrate with Azure DevOps. To access your account without repeatedly asking for user credentials, apps can use the following authentication methods: -- [Personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md) to generate tokens on behalf of yourself for: - - Accessing specific resources or activities, like builds or work items - - Clients like Xcode and NuGet that require usernames and passwords as basic credentials and don't support Microsoft account and Azure Active Directory features like multi-factor authentication - - Accessing [Azure DevOps REST APIs](/rest/api/azure/devops/) +- [OAuth](../../integrate/get-started/authentication/oauth.md) to generate tokens on users' behalf for accessing [REST APIs](/rest/api/azure/devops/). + - There are two OAuth app models available: **Azure DevOps OAuth is planned for deprecation in 2026. Use [Microsoft Entra OAuth](../../integrate/get-started/authentication/entra-oauth.md) to build on-behalf-of user apps.** + - You can also generate Microsoft Entra tokens for ad-hoc operations on your own behalf, for accessing resources like builds or work items or accessing [Azure DevOps REST APIs](/rest/api/azure/devops/). -- [Azure DevOps OAuth](../../integrate/get-started/authentication/oauth.md) -to generate tokens on behalf of users for accessing [REST APIs](/rest/api/azure/devops/). The [Accounts](/rest/api/azure/devops/account) -and [Profiles](/rest/api/azure/devops/profile) -APIs support only OAuth. +- [Service principals or managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) to generate Microsoft Entra tokens on behalf of an application or service, typically automating workflows that need to access Azure DevOps resources. Most actions traditionally performed by a service account and a PAT can be done using a service principal or managed identity. -- [SSH authentication](../../repos/git/use-ssh-keys-to-authenticate.md) -to generate encryption keys for yourself when you use Linux, macOS, -or Windows running [Git for Windows](https://www.git-scm.com/download/win) -and can't use -[Git credential managers](../../repos/git/set-up-credential-managers.md) -or [personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md) -for HTTPS authentication. +- [Personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md) (PATs) to generate tokens on your behalf. PATs might be helpful for clients like Xcode and NuGet that don't support Microsoft accounts or features, like multifactor authentication (MFA). -- [Service principals or managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) to generate Azure AD tokens on behalf of an application or service, that typically automates some workflow that needs to access Azure DevOps resources. Most actions traditionally done by a service account and a PAT can be done using a service principal or managed identity. +- [SSH authentication](../../repos/git/use-ssh-keys-to-authenticate.md) to generate encryption keys for yourself when you use Linux, macOS, or Windows running [Git for Windows](https://www.git-scm.com/download/win) and can't use [Git credential managers](../../repos/git/set-up-credential-managers.md) or [PATs](../accounts/use-personal-access-tokens-to-authenticate.md) for HTTPS authentication. By default, your account or collection allows access for all authentication methods. -You can limit access, but you must specifically restrict access for each method. -When you deny access to an authentication method, -no app can use that method to access your account. -Any app that previously had access gets an -authentication error and can't access your account. +You can limit access by specifically restricting each method. When you deny access to an authentication method, no app can use that method to access your account. Any app that previously had access receives an authentication error and can't access your account. -For more information about how we store your credentials, see [Credential storage for Azure DevOps](credential-storage.md). +For more information, see the following articles: +- [Credential storage for Azure DevOps](credential-storage.md). +- [Guidance for authentication](../../integrate/get-started/authentication/authentication-guidance.md). -For more information about how to choose the right authentication mechanism, see [Guidance for authentication](../../integrate/get-started/authentication/authentication-guidance.md). - - + ## Authorization -Authorization verifies that the identity that is attempting to connect has the necessary permissions to access a service, feature, function, object, or method. Authorization always occurs after successful authentication. If a connection isn't authenticated, it fails before any authorization checking is performed. If authentication of a connection succeeds, a specific action might still be disallowed because the user or group didn't have authorization to perform that action. +Authorization verifies that the identity attempting to connect has the necessary permissions to access a service, feature, function, object, or method. Authorization always occurs after successful authentication. If a connection isn't authenticated, it fails before any authorization checks are performed. Even if authentication succeeds, a specific action might still be disallowed if the user or group lacks authorization. -Authorization depends on the permissions assigned to the account. Permissions are granted either directly to an account, or through membership in a security group or security role. Access levels and feature flags can also grant or restrict access to a feature. For more information about these authorization methods, see [Get started with permissions, access, and security groups](../security/about-permissions.md). +Authorization depends on the permissions assigned to the user, either directly or through membership in a security group or security role. Access levels and feature flags can also manage access to specific features. For more information about these authorization methods, see [Get started with permissions, access, and security groups](../security/about-permissions.md). - + ## Security namespaces and permissions -Security namespaces store data that determines the level of access that Azure DevOps accounts have to perform a specific action on a specific resource. Each family of resources, such as work items or Git repositories, is secured through a unique namespace. Each security namespace contains zero or more access control lists (ACLs). Each ACL contains a token, an inherit flag, and a set of zero or more access control entries (ACEs). Each ACE contains an identity descriptor, an allowed permissions bitmask, and a denied permissions bitmask. +Security namespaces determine user access levels for specific actions on resources. +- Each resource family, such as work items or Git repositories, has a unique namespace. +- Each namespace contains zero or more access control lists (ACLs). + - Each ACL includes a token, an inherit flag, and access control entries (ACEs). + - Each ACE has an identity descriptor, an allowed permissions bitmask, and a denied permissions bitmask. For more information, see [Security namespaces and permission reference](namespace-reference.md). - + ## Security policies ::: moniker range="azure-devops" -To secure your organization and code, you can set many policies. Specifically, you can enable or disable the following policies: +To secure your organization and code, you can set various policies. Specifically, you can enable or disable the following policies: ### General @@ -215,35 +202,33 @@ To secure your organization and code, you can set many policies. Specifically, y ### Application connection and security policies -Use the Azure Active Directory (Azure AD) tenant policy to restrict creating new organizations to desired users only. This policy is turned off by default and only valid when the organization is connected to Azure Active Directory. Check [restrict organization creation](../accounts/azure-ad-tenant-policy-restrict-org-creation.md) for more details. +Use the Microsoft Entra tenant policy to restrict creating new organizations to desired users only. This policy is turned off by default and only valid when the organization is connected to Microsoft Entra ID. For more information, see [Restrict organization creation](../accounts/azure-ad-tenant-policy-restrict-org-creation.md). -The following policies determine the access you want to give users and applications to your organizations: -- [Third-party application access via OAuth](../accounts/change-application-access-policies.md#application-connection-policies). -- [SSH authentication access](../accounts/change-application-access-policies.md#application-connection-policies). -- **Allow public projects**: When enabled, users can create public projects that allow nonmembers of a project and users who aren't signed in read-only, limited access to the project's artifacts and services. Learn more at [Make your project public](../projects/make-project-public.md). +The following policies determine the access granted to users and applications within your organizations: +- [Non-Microsoft application access via OAuth](../accounts/change-application-access-policies.md#change-application-connection-policies). +- [SSH authentication access](../accounts/change-application-access-policies.md#change-application-connection-policies). +- **Allow public projects**: When enabled, users can create public projects that allow nonmembers of a project and users who aren't signed in read-only, limited access to the project's artifacts and services. For more information, see [Make your project public](../projects/make-project-public.md). - **Log Audit events** - Turn on the ability to track [Auditing events and streams](../audit/azure-devops-auditing.md) for your organization. -- [Enable Azure Active Directory (Azure AD) Conditional Access Policy (CAP) validation](../accounts/change-application-access-policies.md#conditional-access-policies). +- [Enable Microsoft Entra Conditional Access Policy (CAP) validation](../accounts/change-application-access-policies.md#cap-support-on-azure-devops). ### User policies -- **External guest access** (*Only valid when the organization is connected to Azure Active Directory.*): When enabled, invitations can be sent to email accounts of users who aren't members of the tenant Azure Active Directory through the **Users** page. For more information, see [Add external users to your organization](../accounts/add-external-user.md). -- **Allow team and project administrators to invite new users**: Only valid when the organization is connected to Azure Active Directory. When enabled, team and project administrators can add users through the **Users** page. For more information, see [Restrict new user invitations from Project and Team Administrators](restrict-invitations.md). -- **Request access**: Only valid when the organization is connected to Azure Active Directory. When enabled, users can request access to a resource. A request results in an email notification to the administrators asking for review and access, as needed. For more information, see [Add external users to your organization](../accounts/add-external-user.md). -- **Invite GitHub users**: Only valid when the organization isn't connected to Azure Active Directory. When enabled, administrators can add users based on their GitHub user accounts from the **Users** page. For more information, see [Authenticating & inviting GitHub users FAQs](faq-github-authentication.yml#github-users). +- **External guest access** (*Only valid when the organization is connected to Microsoft Entra ID.*): When enabled, invitations can be sent to email accounts of users who aren't members of the tenant's Microsoft Entra ID via the **Users** page. For more information, see [Add external users to your organization](../accounts/add-external-user.md). +- **Allow team and project administrators to invite new users**: Only valid when the organization is connected to Microsoft Entra ID. When enabled, team and project administrators can add users via the **Users** page. For more information, see [Restrict new user invitations from Project and Team Administrators](restrict-invitations.md). +- **Request access**: Only valid when the organization is connected to Microsoft Entra ID. When enabled, users can request access to a resource. A request results in an email notification to the administrators asking for review and access, as needed. For more information, see [Add external users to your organization](../accounts/add-external-user.md). +- **Invite GitHub users**: Only valid when the organization isn't connected to Microsoft Entra ID. When enabled, administrators can add users based on their GitHub user accounts from the **Users** page. For more information, see [Connect to GitHub/FAQs](../../boards/github/connect-to-github.md#faqs). - + ### Project-Scoped Users group -By default, users added to an organization can view all organization and project information and settings. This includes viewing list of users, list of projects, billing details, usage data, and more that is accessed through **Organization Settings**. - -[!INCLUDE [project-scoped-users-important-note](../../includes/project-scoped-users-important-note.md)] +By default, users added to an organization can view all organization and project information and settings, including user lists, project lists, billing details, usage data, and more. -To restrict select users, such as Stakeholders, Azure Active Directory guest users, or members of a particular security group, you can enable the **Limit user visibility and collaboration to specific projects** preview feature for the organization. Once that is enabled, any user or group added to the **Project-Scoped Users** group, are restricted in the following ways: -- Can only access the **Overview** and **Projects** pages of **Organization Settings**. -- Can only connect and view those projects to which they've been added to explicitly (see [Add users to a project or team](add-users-team-project.md). -- Can only select user and group identities that have been added explicitly to the project they're connected to. +To restrict certain users, such as Stakeholders, Microsoft Entra guest users, or members of a specific security group, you can enable the **Limit user visibility and collaboration to specific projects** preview feature for the organization. Once enabled, any user or group added to the **Project-Scoped Users** group, are restricted in the following ways: +- Can only access the **Overview** and **Projects** pages of **Organization settings**. +- Can only connect and view those projects that they are [added to explicitly](add-users-team-project.md). +- Can only select user and group identities added explicitly to the project they're connected to. -For more information, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). To enable the feature, see [Manage or enable features](../../project/navigation/preview-features.md#account-level). +For more information, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group) and [Manage preview features](../../project/navigation/preview-features.md). [!INCLUDE [project-scoped-users-warning](../../includes/project-scoped-users-warning.md)] @@ -258,7 +243,7 @@ For more information, see [Manage your organization, Limit user visibility for ::: moniker range="< azure-devops" -To secure your code, you can set many Git repository and branch policies. For more information, see the following articles. +To secure your code, you can set various Git repository and branch policies. For more information, see the following articles. - [Configure repository settings and policies](../../repos/git/repository-settings.md) - [Configure branch policies](../../repos/git/branch-policies.md) @@ -273,12 +258,12 @@ Since repositories and build and release pipelines pose unique security challeng - [Securing Azure Pipelines](../../pipelines/security/overview.md) - [Plan how to secure your YAML pipelines](../../pipelines/security/approach.md) -- [Repository protection](../../pipelines/security/repos.md) +- [Repository protection](../../pipelines/security/misc.md#protect-repositories) - [Pipeline resources](../../pipelines/security/resources.md) -- [Recommendations to securely structure projects in your pipeline](../../pipelines/security/projects.md) +- [Recommendations to securely structure projects in your pipeline](../../pipelines/security/misc.md#protect-projects) - [Security through templates](../../pipelines/security/templates.md) - [How to securely use variables and parameters in your pipeline](../../pipelines/security/inputs.md) -- [Recommendations to secure shared infrastructure in Azure Pipelines](../../pipelines/security/infrastructure.md) +- [Recommendations to secure shared infrastructure in Azure Pipelines](../../pipelines/security/misc.md#protect-shared-infrastructure) - [Other security considerations](../../pipelines/security/misc.md) ## Next steps @@ -289,8 +274,7 @@ Since repositories and build and release pipelines pose unique security challeng ## Related articles - [Default permissions and access assignments](permissions-access.md) -- [Add or delete users using Azure Active Directory](/azure/active-directory/fundamentals/add-users-azure-active-directory) +- [Add or delete users using Microsoft Entra ID](/azure/active-directory/fundamentals/add-users-azure-active-directory) - [Set up groups for use in on-premises deployments](/azure/devops/server/admin/setup-ad-groups) - [Setting up HTTPS with Secure Sockets Layer (SSL)](/azure/devops/server/admin/setup-secure-sockets-layer) - [Default permissions and access assignments](permissions-access.md) - diff --git a/docs/organizations/security/about-security-roles.md b/docs/organizations/security/about-security-roles.md index 20c8ab5b221..f740104ce69 100644 --- a/docs/organizations/security/about-security-roles.md +++ b/docs/organizations/security/about-security-roles.md @@ -1,77 +1,77 @@ --- title: About pipeline security roles titleSuffix: Azure DevOps -description: Learn about security roles and where they are used to manage select pipeline permissions +description: Discover how security roles are utilized to manage specific pipeline permissions effectively. ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 10/11/2021 +ai-usage: ai-assisted +ms.date: 08/21/2024 --- # About pipeline security roles [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - + -While the majority of features and functional tasks are managed by [individual permissions](about-permissions.md), there are several artifacts and features that the system manages through role-based permissions. You can add users or groups to a role. Each role determines the set of operations that the user can perform as described in the following sections. - -Many role-based permissions can be set for all artifacts of a specific type in a project, or for the project or collection and then selectively inherited for a specific artifact. Role memberships for individual items automatically inherit those set for the project or collection. If required, you can turn off Inheritance for a specific artifact. +Security for build and release pipelines, and task groups, is managed using [task-based permissions](about-permissions.md). Several pipeline resources use role-based permissions, which can be assigned to users or groups. Each role defines the operations a user can perform. +Role-based permissions apply to all resources of a specific type within a project, organization, or collection. Individual resources inherit permissions from project-level settings, but you can turn off inheritance for specific artifacts if needed. ## Default role assignments -By default, all contributors in a project are members of the User role on each hosted queue. This allows every contributor in a project to author and run build and release pipelines using hosted queues. +By default, all project contributors are members of the User role for each hosted queue. This role allows them to author and run build and release pipelines using hosted queues. - + ## Agent pool security roles, project-level -You [add users to the following security roles](../../pipelines/policies/set-permissions.md) from the project-level admin context, **Agent Pools** page. For information on adding and managing agent pools, see [Agent pools](../../pipelines/agents/pools-queues.md). +You can add users to security roles from the project-level admin context on the **Agent Pools** page. For information on adding and managing agent pools, see [Agent pools](../../pipelines/agents/pools-queues.md). [!INCLUDE [temp](includes/agent-queue-roles.md)] - + ## Agent pool security roles, organization or collection-level -You [add users to the following security roles](../../pipelines/policies/set-permissions.md) from the **Organization settings** or collection-level admin settings, **Agent Pools** page. For information on adding and managing agent pools, see [Agent pools](../../pipelines/agents/pools-queues.md). +Add users to the following security roles from the **Organization settings** > **Agent Pools** page. For information on adding and managing agent pools, see [Agent pools](../../pipelines/agents/pools-queues.md). [!INCLUDE [temp](includes/agent-pool-roles.md)] ## Deployment group security roles -You [add users to the following roles](../../pipelines/policies/set-permissions.md) from **Pipelines** or **Build and Release**. For information on adding and managing deployment groups, see [Deployment groups](../../pipelines/release/deployment-groups/index.md). +Add users to the following roles from the **Pipelines** or **Build and Release** page. For information on adding and managing deployment groups, see [Deployment groups](../../pipelines/release/deployment-groups/index.md). [!INCLUDE [temp](includes/deployment-group-roles.md)] ## Deployment pool security roles -You [add users to the following roles](../../pipelines/policies/set-permissions.md) from the collection-level admin context, **Deployment Pools** page. To create and manage deployment pools, see [Deployment groups](../../pipelines/release/deployment-groups/index.md). +Add users to the following roles from the **Deployment Pools** page. For information on creating and managing deployment pools, see [Deployment groups](../../pipelines/release/deployment-groups/index.md). [!INCLUDE [temp](includes/deployment-pool-roles.md)] - + ## Library asset security roles: Variable groups and secure files -You [add users to a library role](../../pipelines/policies/set-permissions.md) from **Pipelines** or **Build and Release**. To learn more about using these library assets, see [Variable groups](../../pipelines/library/variable-groups.md) and [Secure files](../../pipelines/library/secure-files.md) +Add users to a library role from **Pipelines** or **Build and Release**. For more information about using these library assets, see [Variable groups](../../pipelines/library/variable-groups.md) and [Secure files](../../pipelines/library/secure-files.md). [!INCLUDE [temp](includes/library-roles.md)] - + ## Service connection security roles -You [add users to the following roles](../../pipelines/policies/set-permissions.md) from the project-level admin context, **Services** page. To create and manage these resources, see [Service connections for build and release](../../pipelines/library/service-endpoints.md). +Add users to the following roles from the **Services** page. For information about creating and managing these resources, see [Service connections for build and release](../../pipelines/library/service-endpoints.md). [!INCLUDE [temp](includes/service-endpoint-roles.md)] ## Related articles -- [Get started with permissions, access, and security groups](about-permissions.md) -- [Permissions and groups reference](permissions.md) -- [Add or delete users using Azure Active Directory](/azure/active-directory/fundamentals/add-users-azure-active-directory) - \ No newline at end of file +- [Start managing permissions, access, and security groups](about-permissions.md) +- [Reference permissions and groups](permissions.md) +- [Add or delete users with Microsoft Entra ID](/azure/active-directory/fundamentals/add-users-azure-active-directory) + diff --git a/docs/organizations/security/access-levels.md b/docs/organizations/security/access-levels.md index 759d440b401..7beadf52f48 100644 --- a/docs/organizations/security/access-levels.md +++ b/docs/organizations/security/access-levels.md @@ -1,34 +1,25 @@ --- title: About access levels titleSuffix: Azure DevOps -description: Learn how access levels are used to grant or restrict access to web portal features through stakeholder, basic, basic+Test Plans, or VS Enterprise access levels +description: Understand how access levels control the features and functions of Azure DevOps. Learn about assigning and changing access levels for users and groups. ms.subservice: azure-devops-security ms.assetid: E2C63C7B-6273-41D7-BD14-BFB340DF8D65 ms.topic: conceptual ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 04/04/2025 --- - # About access levels [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Access levels grant or restrict access to select web portal features. This is in addition to permissions granted through security groups, which provide or restrict specific tasks. Access levels enable administrators to provide their user base access to the features they need and only pay for those features. - -[!INCLUDE [temp](../../includes/version-selector-minimize.md)] +Access levels in Azure DevOps control which web portal features are available or not. Access levels supplement security groups, which allow or deny specific tasks. Administrators ensure that their user base has access to the features they need and only pay for those specific features. It’s an efficient way to manage costs while providing the necessary functionality to users. For more information, see [Stakeholder access quick reference](stakeholder-access.md) and [Manage users and access](../accounts/add-organization-users.md). -When you add a user or group to a team or project, they're automatically granted access to those features supported by the default access level and those supported by the security group to which they are added. Most users can access most features by being assigned to the **Basic** access level and **Contributors** security group. For a simplified overview of the permissions assigned to the most common groups **Readers**, **Contributors**, and **Project Administrators**, see [Default permissions](permissions-access.md). +[!INCLUDE [temp](../../includes/version-selector.md)] -::: moniker range="azure-devops" -To add user accounts or groups to specific access levels, see [Manage users and access](../accounts/add-organization-users.md). Make sure to set each user's access level based on what you've purchased for that user. -::: moniker-end - -::: moniker range="< azure-devops" -To add user accounts or groups to specific access levels, see [Change access levels](change-access-levels.md). Make sure to set each user's access level based on what you've purchased for that user. -::: moniker-end +When you add a user or group to a team or project, they automatically gain access to the features associated with the default access level and security group. For most users, assigning them to the **Basic** access level and the **Contributors** security group provides access to most features. For a simplified overview of the permissions assigned to the most common groups **Readers**, **Contributors**, and **Project Administrators**, see [Default permissions](permissions-access.md). ## Supported access levels @@ -37,41 +28,31 @@ Assign users or groups of users to one of the following access levels: ::: moniker range="azure-devops" - **Basic**: Provides access to most features. Assign to users with a Visual Studio Professional subscription, an Azure DevOps Server CAL, and to users for whom you're paying for Basic access in an organization. -- **Basic + Test Plans**: Provides access to all features included in **Basic**, as well as Azure Test Plans. Assign to users with a Visual Studio Test Professional or MSDN Platforms subscription, and to users for whom you're paying for Basic + Test Plans access in an organization. -- **Stakeholder**: Can be assigned to unlimited users for free. Provides partial access to private projects and mostly full access to public projects. Assign to users with no license or subscriptions who need access to a limited set of features. For feature access details, see [Stakeholder access quick reference](stakeholder-access.md). -- **Visual Studio Subscriber**: Assign to users who already have a Visual Studio subscription. The system automatically recognizes the user's subscription—Visual Studio Enterprise, Visual Studio Professional, Visual Studio Test Professional, or MSDN Platform—and enables any other features that are included in their subscription level. If you assign **Basic** or **Stakeholder**, they also receive their Visual Studio subscription benefits upon sign-in. - -> [!TIP] -> As a best practice when adding new users, we recommend assigning the **Visual Studio Subscriber** level when appropriate (as opposed to Basic) to prevent being charged the **Basic** rate before the user signs in for the first time. +- **Basic + Test Plans**: Provides access to all features included in **Basic** and Azure Test Plans. Assign to users with a Visual Studio Test Professional or MSDN Platforms subscription, and to users for whom you're paying for Basic + Test Plans access in an organization. +- **Stakeholder**: Provides limited access to private projects and nearly full access to public projects. Assign to an unlimited number of users without requiring a license or subscription, ideal for those needing access to a restricted set of features. Stakeholders can perform various, including viewing work items, participating in discussion, and accessing dashboards. +- **Visual Studio subscriber**: Assign to users who already have a Visual Studio subscription. The system automatically recognizes the user's subscription—Visual Studio Enterprise, Visual Studio Professional, Visual Studio Test Professional, or MSDN Platform—and enables any other features included in their subscription level. If you assign **Basic** or **Stakeholder**, they also receive their Visual Studio subscription benefits upon sign-in. + > [!TIP] + > As a best practice when adding new users, we recommend assigning the **Visual Studio Subscriber** level when appropriate (as opposed to Basic) to prevent being charged the **Basic** rate before the user signs in for the first time. +- **GitHub Enterprise**: The system automatically recognizes users with a GitHub Enterprise license the next time they sign in to Azure DevOps. Regardless of a user's assigned access level (for example, they could be assigned **Stakeholder** access), they receive **Basic** access when they're associated with a GitHub Enterprise license. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" + --- ::: moniker range="azure-devops" + :::row::: :::column span="3"::: **Feature** @@ -80,7 +61,7 @@ The following table indicates those features available for each supported access **Stakeholder** :::column-end::: :::column span="1"::: - **Basic** &
      **Visual Studio Professional** + **Basic**, **GitHub Enterprise**, &
      **Visual Studio Professional** :::column-end::: :::column span="1"::: **Basic + Test Plans &**
      **Visual Studio Enterprise** @@ -88,7 +69,9 @@ The following table indicates those features available for each supported access :::row-end::: --- ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" + +::: moniker range=" < azure-devops" + :::row::: :::column span="3"::: **Feature** @@ -105,23 +88,7 @@ The following table indicates those features available for each supported access :::row-end::: --- ::: moniker-end -::: moniker range="tfs-2018" -:::row::: - :::column span="3"::: - **Feature** - :::column-end::: - :::column span="1"::: - **Stakeholder** - :::column-end::: - :::column span="1"::: - **Basic** &
      **Visual Studio Professional** - :::column-end::: - :::column span="1"::: - **Advanced** &
      **Visual Studio Enterprise** - :::column-end::: -:::row-end::: ---- -::: moniker-end + :::row::: :::column span="3"::: [**Administer organization**](../settings/about-settings.md) @@ -173,7 +140,7 @@ The following table indicates those features available for each supported access :::row::: :::column span="3"::: **Advanced portfolio management** - Includes full access to define features and epics from a [portfolio backlog](../../boards/backlogs/define-features-epics.md) or [Kanban board](../../boards/boards/kanban-epics-features-stories.md). + Includes full access to define features and epics from a [portfolio backlog](../../boards/backlogs/define-features-epics.md) or [board](../../boards/boards/kanban-epics-features-stories.md). :::column-end::: :::column span="1"::: @@ -187,10 +154,11 @@ The following table indicates those features available for each supported access :::row-end::: --- ::: moniker range=">= azure-devops-2020" + :::row::: :::column span="3"::: **Agile boards** - Stakeholders have limited access to [Kanban boards](../../boards/boards/kanban-quickstart.md) and [Taskboards](../../boards/sprints/task-board.md). Stakeholders can add work items and update status through drag-and-drop, but can't update fields displayed on cards (except for the work item State) and can't [view or set capacity](../../boards/sprints/set-capacity.md). + Stakeholders get limited access to [boards](../../boards/boards/kanban-quickstart.md) and [Taskboards](../../boards/sprints/task-board.md). Stakeholders use drag-and-drop to create and change work items, but only change the State field on cards. They only view [the sprint capacity settings](../../boards/sprints/set-capacity.md). :::column-end::: :::column span="1"::: ✔️ @@ -204,28 +172,11 @@ The following table indicates those features available for each supported access :::row-end::: --- ::: moniker-end -::: moniker range="< azure-devops-2020" -:::row::: - :::column span="3"::: - **Agile boards** - Stakeholders have limited access to [Kanban boards](../../boards/boards/kanban-quickstart.md) and [Taskboards](../../boards/sprints/task-board.md). Stakeholders can't add work items, drag-and-drop cards to update status, update fields displayed on cards, nor [view or set capacity](../../boards/sprints/set-capacity.md). - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: ---- -::: moniker-end + :::row::: :::column span="3"::: **Agile Portfolio Management** - Includes limited access to [portfolio backlogs](../../boards/backlogs/define-features-epics.md) and [Kanban boards](../../boards/boards/kanban-epics-features-stories.md). Stakeholders can't change the backlog priority order, can't assign items to an iteration, use the mapping pane, or exercise forecasting. + Includes limited access to [portfolio backlogs](../../boards/backlogs/define-features-epics.md) and [ boards](../../boards/boards/kanban-epics-features-stories.md). Stakeholders can't change the backlog priority order, can't assign items to an iteration, use the mapping pane, or exercise forecasting. :::column-end::: :::column span="1"::: ✔️ @@ -240,7 +191,7 @@ The following table indicates those features available for each supported access :::row::: :::column span="3"::: [**Artifacts**](../../artifacts/start-using-azure-artifacts.md) - Includes full access to all Azure Artifacts features, up to 2 GiB free storage. + Includes full access to all Azure Artifacts features, up to 2-GiB free storage. :::column-end::: :::column span="1"::: ✔️ @@ -256,10 +207,10 @@ The following table indicates those features available for each supported access :::row::: :::column span="3"::: **Author Release Pipelines and Manage Releases** - Includes defining [release pipelines](../../pipelines/release/index.md), [multi-stage continuous deployment (CD) pipelines](../../pipelines/release/define-multistage-release-process.md), and [using approvals and gates to control deployments](../../pipelines/release/deploy-using-approvals.md); when the [**Free access to Pipelines Preview** feature is enabled](provide-stakeholder-pipeline-access.md), Stakeholders gain access to all Azure Pipelines features. + Includes defining [release pipelines](../../pipelines/release/index.md), [multi-stage continuous deployment (CD) pipelines](../../pipelines/release/define-multistage-release-process.md), and [using approvals and gates to control deployments](../../pipelines/release/deploy-using-approvals.md). :::column-end::: :::column span="1"::: - + ✔️ :::column-end::: :::column span="1"::: ✔️ @@ -271,7 +222,7 @@ The following table indicates those features available for each supported access :::row::: :::column span="3"::: **Basic backlog and sprint planning tools** - Includes limited access to add and modify items on [backlogs](../../boards/backlogs/backlogs-overview.md) and [sprint backlogs and taskboards](../../boards/sprints/scrum-overview.md). Stakeholders can't assign items to an iteration, use the mapping pane, or forecasting. + Includes limited access to add and modify items on [backlogs](../../boards/backlogs/backlogs-overview.md) and [sprint backlogs and Taskboards](../../boards/sprints/scrum-overview.md). Stakeholders can't assign items to an iteration, use the mapping pane, or forecasting. :::column-end::: :::column span="1"::: @@ -289,7 +240,7 @@ The following table indicates those features available for each supported access Includes full access to all features to [manage continuous integration and continuous delivery of software](../../pipelines/get-started/what-is-azure-pipelines.md). :::column-end::: :::column span="1"::: - + ✔️ :::column-end::: :::column span="1"::: ✔️ @@ -317,7 +268,7 @@ The following table indicates those features available for each supported access :::row::: :::column span="3"::: **Chart Viewing** - Can only view work tracking query charts. Stakeholders can't view query charts from the Queries page, however can view them when added to a dashboard. + Can only view work tracking query charts. Stakeholders can't view query charts from the Queries page. They can view them when added to a dashboard. :::column-end::: :::column span="1"::: @@ -367,7 +318,7 @@ The following table indicates those features available for each supported access ::: moniker range="< azure-devops" :::row::: :::column span="3"::: - [**Delivery Plans**](../../boards/extensions/delivery-plans.md) + [**Delivery Plans**](../../boards/plans/review-team-plans.md) Includes full access to add and view Delivery plans. :::column-end::: :::column span="1"::: @@ -401,7 +352,7 @@ The following table indicates those features available for each supported access :::row::: :::column span="3"::: **Standard Features** - Includes [working across projects](../../project/navigation/work-across-projects.md), [View dashboards](../../report/dashboards/dashboards.md), [View wikis](../../project/wiki/filter-print-wiki.md), and [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md). Stakeholders can't view Markdown README files defined for repositories and can only read wiki pages. + Includes [working across projects](../../project/navigation/work-across-projects.md), [View dashboards](../../report/dashboards/dashboards.md), [View wikis](../../project/wiki/filter-print-wiki.md), and [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md). Stakeholders can't view Markdown README files defined for repositories and can only view wiki pages. Access might be restricted based on specific project or organization permissions. For full functionality, including the ability to view all wiki features, a **Basic** license is recommended. :::column-end::: :::column span="1"::: ✔️ @@ -497,7 +448,7 @@ The following table indicates those features available for each supported access :::row::: :::column span="3"::: **View Releases and Manage Approvals** - Includes [viewing releases](../../pipelines/release/approvals/index.md) and [approving releases](../../pipelines/release/approvals/index.md); when the [**Free access to Pipelines Preview** feature is enabled](provide-stakeholder-pipeline-access.md) feature is enabled, Stakeholders gain access to all Azure Pipelines features. + Includes [viewing releases](../../pipelines/release/approvals/index.md) and [approving releases](../../pipelines/release/approvals/index.md). :::column-end::: :::column span="1"::: ✔️ @@ -511,16 +462,15 @@ The following table indicates those features available for each supported access :::row-end::: --- - - + ::: moniker range="azure-devops" ## Visual Studio subscription access -Visual Studio subscribers are entitled to **Visual Studio subscription** features as a subscriber benefit. When you add those users, be sure to assign them the **Visual Studio subscription** access level. +Visual Studio subscribers get **Visual Studio subscription** features as a subscriber benefit. When you add those users, be sure to assign them the **Visual Studio subscription** access level. -The system automatically recognizes their subscription and enables any other features that are included, based on their subscription level. +The system automatically recognizes their subscription and enables any other features included, based on their subscription level. ::: moniker-end @@ -528,34 +478,22 @@ The system automatically recognizes their subscription and enables any other fea ## VS Enterprise access -Visual Studio Enterprise subscribers are entitled to **VS Enterprise** access as a subscriber benefit. When you add those users, be sure to assign them the **VS Enterprise** access level. - -With VS Enterprise access, users have access to any fee-based, Marketplace extension published by Microsoft Marketplace extension published by Microsoft that is included for active Visual Studio Enterprise subscribers. - -::: moniker-end - - -::: moniker range="< azure-devops-2019" +Visual Studio Enterprise subscribers get **VS Enterprise** access as a subscriber benefit. When you add those users, be sure to assign them the **VS Enterprise** access level. -## Advanced access - -Users assigned Advanced access can manage test cases when you have [purchased the Test Manager extension](https://marketplace.visualstudio.com/items?itemName=ms.vss-testmanager-web) for Azure Test Plans and assigned to the user accounts to gain full access to [Web-based test case management tools](../../test/create-a-test-plan.md). +With Visual Studio Enterprise (VS Enterprise) access, users gain access to any fee-based, Marketplace extension published by Microsoft that is included for active Visual Studio Enterprise subscribers. ::: moniker-end ::: moniker range="< azure-devops" -Users assigned Advanced access have all the Basic features, plus [web-based test case management tools](../../test/create-a-test-plan.md). You can [buy monthly access](../billing/buy-access-tfs-test-hub.md#buy-monthly-access-to-test-plans) or add users who already have a Visual Studio Test Professional with MSDN or MSDN Platforms subscription. +Advanced access gives users all the Basic features, plus [web-based test case management tools](../../test/create-a-test-plan.md). You can [buy monthly access](../billing/buy-access-tfs-test-hub.md#buy-monthly-access-to-test-plans) or add users who already have a Visual Studio Test Professional with MSDN or MSDN Platforms subscription. ::: moniker-end - - - + ## Programmatic mapping of access levels - ::: moniker range="azure-devops" You can manage access levels programmatically using the [`az devops user add` (Azure DevOps Services only)](../accounts/add-organization-users.md) or the [User Entitlement - Add REST API](/rest/api/azure/devops/memberentitlementmanagement/user-entitlements/add). The following table provides a mapping of the access level selected through the user interface and the `AccountLicenseType`, `licensingSource`, and `msdnLicenseType` parameters. @@ -566,15 +504,15 @@ You can manage access levels programmatically using the [`az devops user add` (A | Basic + Test Plans | advanced | account | none | | Visual Studio Subscriber | none | msdn | eligible | | Stakeholder | stakeholder | account | none | -| Visual Studio Enterprise subscription | none | msdn | enterprise | - +| Visual Studio Enterprise subscription | none | msdn | enterprise| +| GitHub Enterprise | express | account |enterprise | > [!NOTE] > The `earlyAdopter` accountLicenseType is an internal value used solely by Microsoft. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="licenseDisplayName | accountLicenseType | licensingSource | msdnLicenseType | -| ------------------------------------------------------|--------------------|----------------|------------------| -| Basic | express | account | none | -| Advanced | advanced | account | none | -| Stakeholder | stakeholder | account | none | -| VS Enterprise | none | msdn | enterprise | - -::: moniker-end - - ::: moniker range="< azure-devops" -## What features are available to users who are added to two different access levels? +## What features are available to users who added to two different access levels? If a user belongs to a group that has **Basic** access and another group that has **VS Enterprise** access, the user has access to all features available through **VS Enterprise**, which is a superset of **Basic**. ## Service account access -Azure DevOps Server [service accounts](/azure/devops/server/admin/service-accounts-dependencies) are added to the default access level. If you make Stakeholder the default access level, you must add the service accounts to Basic or Advanced/VS Enterprise access. +Azure DevOps [service accounts](/azure/devops/server/admin/service-accounts-dependencies) added to the default access level. If you make Stakeholder the default access level, you must add the service accounts to Basic or Advanced/VS Enterprise access. Service accounts don't require a CAL or other purchase. @@ -622,21 +545,16 @@ Service accounts don't require a CAL or other purchase. ::: moniker range="azure-devops" - [Stakeholder access quick reference](stakeholder-access.md) -- [Free access to Pipelines Preview](provide-stakeholder-pipeline-access.md) -- [Manage users and access](../accounts/add-organization-users.md) - [Get started as a Stakeholder](get-started-stakeholder.md) - [Export a list of users and their access levels](export-users-audit-log.md) - [Default permissions and access](permissions-access.md) ::: moniker-end - ::: moniker range="< azure-devops" - [Stakeholder access quick reference](stakeholder-access.md) - [Change access levels](change-access-levels.md) - [Get started as a Stakeholder](get-started-stakeholder.md) -- [Export a list of users and their access levels](export-users-audit-log.md) -- [Default permissions and access](permissions-access.md) - [Compare features between plans](https://azure.microsoft.com/services/devops/compare-features/) ::: moniker-end diff --git a/docs/organizations/security/add-ad-aad-built-in-security-groups.md b/docs/organizations/security/add-ad-aad-built-in-security-groups.md index 6f11215c31d..222b9645364 100644 --- a/docs/organizations/security/add-ad-aad-built-in-security-groups.md +++ b/docs/organizations/security/add-ad-aad-built-in-security-groups.md @@ -1,213 +1,165 @@ --- -title: Add AD/Azure AD groups to security groups +title: Add Active Directory / Microsoft Entra group to a built-in security group titleSuffix: Azure DevOps -description: Manage large groups of users by adding AD/Azure AD groups to built-in security groups +description: Efficiently manage large user groups by adding Active Directory / Microsoft Entra groups to built-in security groups. ms.subservice: azure-devops-security ms.assetid: ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 03/23/2023 +ai-usage: ai-assisted +ms.date: 08/26/2024 --- -# Add AD/Azure AD users or groups to a built-in security group +# Add an Active Directory / Microsoft Entra group to a built-in security group [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -As described in [About security, authentication, and authorization](about-security-identity.md), there are two main types of built-in security groups: project-level and collection-level. In general, you add users and groups to a project-level group such as Contributors and Readers. For users that need to administrate select features and functions, add them or associated groups to the Build Administrators or Project Administrators groups. - -Review [Default permissions and access](permissions-access.md) to gain insight into the default permissions provided to the built-in, project-level security groups. - ::: moniker range="azure-devops" -Learn how to do the following task: -> [!div class="checklist"] -> * Add an Azure AD user or group to a built-in security group +In this article, learn how to manage large user groups by adding Microsoft Entra groups to built-in security groups in Azure DevOps. As outlined in [About security, authentication, and authorization](about-security-identity.md), there are two main types of built-in security groups: project-level and collection-level. Typically, you add groups to project-level groups like Contributors and Readers. For more information, see [Default permissions and access](permissions-access.md). + +The process for adding a Microsoft Entra group to a built-in security group is the same, no matter the access level at which you add them. ::: moniker-end -::: moniker range="< azure-devops" +::: moniker range=" < azure-devops" -Learn how to do the following task: -> [!div class="checklist"] -> * Add an Active Directory user or group to a built-in security group +In this article, learn how to manage large user groups by adding Active Directory groups to built-in security groups in Azure DevOps. As outlined in [About security, authentication, and authorization](about-security-identity.md), there are two main types of built-in security groups: project-level and collection-level. Typically, you add groups to project-level groups like Contributors and Readers. For more information, see [Default permissions and access](permissions-access.md). -::: moniker-end +The process for adding an Active Directory group to a built-in security group is the same, no matter the access level at which you add them. -The method for adding a user or group to a built-in security group is the same, no matter at what level you add them. +::: moniker-end -::: moniker range="azure-devops" +::: moniker range="azure-devops" -> [!NOTE] -> If the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization, users added to the **Project-Scoped Users** group won't be able to access projects that they haven't been added to. For more information, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). +## Prerequisites -[!INCLUDE [project-scoped-users-warning](../../includes/project-scoped-users-warning.md)] +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +|**Access levels**| At least **Basic** access.| +|**Organization connection**| Organization [connected to Microsoft Entra ID](../accounts/connect-organization-to-azure-ad.md).| -::: moniker-end +::: moniker-end ::: moniker range="azure-devops" -## Add Azure AD user or group to a built-in security group + -> [!IMPORTANT] -> If you're adding a user to Azure DevOps for the first time, see [Add users for Azure DevOps](../accounts/add-organization-users.md?toc=/azure/devops/organizations/security/toc.json). -> To manage the permissions of an Azure AD group in Azure DevOps, you must first add the Azure AD group to a built-in security group. Once you complete this task, you can then manage your Azure AD group permissions throughout Azure DevOps. +## Add Microsoft Entra group to a built-in security group > [!NOTE] > To enable the **Project Permissions Settings Page** preview page, see [Enable preview features](../../project/navigation/preview-features.md). #### [Preview page](#tab/preview-page) -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +1. Sign in to your project (```https://dev.azure.com/{Your_Organization/Your_Project}```). -2. Choose **Project settings**, and then **Permissions**. +2. Select **Project settings** > **Permissions**. - ![Choose Project settings, and then Permissions](media/permissions/choose-project-settings-permissions.png) + > [!div class="mx-imgBorder"] + > ![Screenshot shows highlighted selections, Project settings and Permissions buttons.](media/permissions/choose-project-settings-permissions.png) -3. Open **Security** and under the **Groups** section, choose one of the following actions: - - To add users who require read-only access to the project, choose **Readers**. - - To add users who need to contribute fully to the project or who have been granted Stakeholder access, choose **Contributors**. - - For users who need to administrate the project, choose **Project Administrators**. +3. Do one of the following actions: + - Select **Readers** to add users who require read-only access to the project. + - Select **Contributors** to add users who need full contribution access or Stakeholder access. + - Select **Project Administrators** to add users who need administrative access to the project. + + In the following example, we select the **Contributors** group. + > [!div class="mx-imgBorder"] + > ![Screenshot shows highlighted Contributors group selection.](media/add-users/selected-contributors.png) -4. Next, choose the **Members** tab. +4. Select **Members** > **Add**. - Here we choose the **Contributors** group. + > [!div class="mx-imgBorder"] + > ![Screenshot shows highlighted Members tab for Contributors group.](media/add-users/selected-members-in-contributor-group.png) - > [!div class="mx-imgBorder"] - > ![Admin context, Security page, Contributors group, Membership page](media/add-users/add-members-to-contributors-group.png) + The default team group and all other teams you add to the project are included as members of the Contributors group. So, you can choose to [add a new user as a member of a team](add-users-team-project.md#add-team-members) instead, and the user automatically inherits Contributor permissions. - By default, the default team group and all other teams you add to the project are included as members of the Contributors group. So, you can choose to [add a new user as a member of a team](add-users-team-project.md#add-team-members) instead, and the user would automatically inherit Contributor permissions. +5. Enter the group name into the text box. You can enter multiple identities, separated by commas. The system automatically searches for matches. Select the matching identity or identities that meet your criteria. -5. Choose :::image type="icon" source="../../media/icons/add-light-icon.png" border="false":::**Add** to add a user or a user group. - -6. Enter the name of the user into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. - - ![Add users and group dialog](media/project-level-permissions-add-a-user.png) + > [!div class="mx-imgBorder"] + > ![Screenshot shows the Invite members group dialog.](media/add-users/invite-members-to-contributors-group.png) > [!NOTE] - > The first time you add a user or group, - > you can't browse to it or check the friendly name. - > After the identity has been added, you can just enter the friendly name. + > The first time you add a group, you can't browse for it or check the friendly name. After adding the identity, you can enter the friendly name directly. #### [Current page](#tab/current-page) -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +1. Sign in to your project (```https://dev.azure.com/{Your_Organization/Your_Project}```). -2. Choose **Project Settings**, and then **Security**. +2. Select **Project settings** > **Security**. - [![Project Settings>Security](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) + [![Screenshot show selections, Project settings, Security page.](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) -3. Open **Security** and under the **Groups** section, choose one of the following actions: - - To add users who require read-only access to the project, choose **Readers**. - - To add users who need to contribute fully to the project or who have been granted Stakeholder access, choose **Contributors**. - - For users who need to administrate the project, choose **Project Administrators**. +3. Do one of the following actions: + - Select **Readers** to add users who require read-only access to the project. + - Select **Contributors** to add users who need full contribution access or Stakeholder access. + - Select **Project Administrators** to add users who need administrative access to the project. -4. Next, choose the **Members** tab. +4. Select **Members**. Here we choose the **Contributors** group. > [!div class="mx-imgBorder"] - > ![Admin context, Security page, Contributors group, Membership page](media/add-users/add-members-to-contributors-group.png) + > ![Screenshot shows Admin context, Security page, Contributors group, Membership page selections.](media/add-users/add-members-to-contributors-group.png) - By default, the default team group and all other teams you add to the project are included as members of the Contributors group. So, you can choose to [add a new user as a member of a team](add-users-team-project.md#add-team-members) instead, and the user would automatically inherit Contributor permissions. + The default team group and all other teams you add to the project are included as members of the Contributors group. So, you can choose to [add a new user as a member of a team](add-users-team-project.md#add-team-members) instead, and the user automatically inherits Contributor permissions. -5. Choose :::image type="icon" source="../../media/icons/add-light-icon.png" border="false":::**Add** to add a user or a user group. +5. Choose :::image type="icon" source="../../media/icons/add-light-icon.png" border="false":::**Add** to add a group. -6. Enter the name of the user into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. +6. Enter the name of the user into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match that meets your choice. - ![Add users and group dialog](media/project-level-permissions-add-a-user.png) + ![Screenshot showing the Add users and group dialog.](media/project-level-permissions-add-a-user.png) - > [!NOTE] - > The first time you add a user or group, - > you can't browse to it or check the friendly name. - > After the identity has been added, you can just enter the friendly name. + > [!TIP] + > The first time you add a group, you can't browse or check the friendly name. + > After you add the identity, you can enter the friendly name directly. ::: moniker-end --- - ::: moniker range="< azure-devops" -## Add an Active Directory user or group to a built-in security group - -::: moniker-end - -::: moniker range="= azure-devops-2019 || azure-devops-2020" +## Add an Active Directory group to a built-in security group 1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). 2. Choose **Project Settings**, and then **Security**. - [![Project Settings>Security](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) + [![Screenshot of Project Settings>Security selections.](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) -3. Open **Security** and under the **Groups** section, choose one of the following actions: - - To add users who require read-only access to the project, choose **Readers**. - - To add users who need to contribute fully to the project or who have been granted Stakeholder access, choose **Contributors**. - - For users who need to administrate the project, choose **Project Administrators**. +3. Select **Security** and under the **Groups** section, and then do one of the following actions: + - Select **Readers** to add users who require read-only access to the project. + - Select **Contributors** to add users who need full contribution access or Stakeholder access. + - Select **Project Administrators** to add users who need administrative access to the project. 4. Next, choose the **Members** tab. - Here we choose the **Contributors** group. + In the following example, we choose the **Contributors** group. > [!div class="mx-imgBorder"] - > ![Admin context, Security page, Contributors group, Membership page](media/add-users/add-members-to-contributors-group.png) + > ![Screenshot showing selection sequence, Admin context, Security page, Contributors group, Membership page.](media/add-users/add-members-to-contributors-group.png) - By default, the default team group and all other teams you add to the project are included as members of the Contributors group. So, you can choose to [add a new user as a member of a team](add-users-team-project.md#add-team-members) instead, and the user would automatically inherit Contributor permissions. + The default team group and all other teams you add to the project are included as members of the Contributors group. So, you can choose to [add a new user as a member of a team](add-users-team-project.md#add-team-members) instead, and the user automatically inherits Contributor permissions. -5. Choose :::image type="icon" source="../../media/icons/add-light-icon.png" border="false":::**Add** to add a user or a user group. +5. Select :::image type="icon" source="../../media/icons/add-light-icon.png" border="false":::**Add** to add a group. -6. Enter the name of the user into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. +6. Enter the group name in the text box. You can enter multiple groups, separated by commas. The system automatically searches for matches. Select the match that meets your criteria. - ![Add users and group dialog](media/project-level-permissions-add-a-user.png) + ![Screenshot showing the Add users and group dialog.](media/project-level-permissions-add-a-user.png) - > [!NOTE] - > The first time you add a user or group, - > you can't browse to it or check the friendly name. - > After the identity has been added, you can just enter the friendly name. - -::: moniker-end - - -::: moniker range="tfs-2018" - -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). - -2. Choose the :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: gear icon to open **Project Settings**. - - ![Open Project Settings, horizontal nav](../../media/settings/open-project-settings-horz.png) - -3. Open **Security** and under the **Groups** section, choose one of the following actions: - - To add users who require read-only access to the project, choose **Readers**. - - To add users who need to contribute fully to the project or who have been granted Stakeholder access, choose **Contributors**. - - For users who need to administrate the project, choose **Project Administrators**. - -4. Next, choose the **Members** tab. - - Here we choose the **Contributors** group. - - > [!div class="mx-imgBorder"] - > ![Admin context, Security page, Contributors group, Membership page](media/add-users/add-members-to-contributors-group.png) - - By default, the default team group and all other teams you add to the project are included as members of the Contributors group. So, you can choose to [add a new user as a member of a team](add-users-team-project.md#add-team-members) instead, and the user automatically inherits Contributor permissions. - -5. Choose :::image type="icon" source="../../media/icons/add-light-icon.png" border="false":::**Add** to add a user or a user group. - -6. Enter the name of the user into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. - - ![Add users and group dialog](media/project-level-permissions-add-a-user.png) - - > [!NOTE] - > The first time you add a user or group, - > you can't browse to it or check the friendly name. - > After the identity has been added, you can just enter the friendly name. + > [!TIP] + > The first time you add a group, you can't browse or check the friendly name. + > After you add the identity, you can enter the friendly name directly. ::: moniker-end - ## Next steps > [!div class="nextstepaction"] @@ -218,4 +170,4 @@ The method for adding a user or group to a built-in security group is the same, - [Get started with permissions, access, and security groups](about-permissions.md) - [Change project-level permissions](change-project-level-permissions.md) - [Change project collection-level permissions](change-organization-collection-level-permissions.md) -- [About security, authentication, and authorization](about-security-identity.md) +- [Learn about security, authentication, and authorization](about-security-identity.md) diff --git a/docs/organizations/security/add-manage-security-groups.md b/docs/organizations/security/add-manage-security-groups.md index 08ff93c3092..51ea585baa5 100644 --- a/docs/organizations/security/add-manage-security-groups.md +++ b/docs/organizations/security/add-manage-security-groups.md @@ -27,13 +27,12 @@ Azure DevOps is pre-configured with default security groups. You can add and man > [!NOTE] > This article applies to Azure DevOps Services only. For Azure DevOps Server, you can manage security groups using the [**TFSSecurity** command](/azure/devops/server/command-line/tfssecurity-cmd). - ## Prerequisites -- To add and manage security groups, you must be a member of the Project Collection Administrators security group. -- You must have installed the Azure DevOps CLI extension as described in [Get started with Azure DevOps CLI](../../cli/index.md). -- Sign into Azure DevOps using `az login`. -- For the examples in this article, set the default organization as follows: `az devops configure --defaults organization=YourOrganizationURL`. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. For more information on tokens, see [Security namespace and permission reference](namespace-reference.md). | +|**Tools**| [Azure DevOps CLI extension](../../cli/index.md). Sign in using `az login`. | ## Security group commands @@ -72,10 +71,10 @@ az devops security group create [--description] ### Optional parameters - **description**: Description of the new security group. -- **email-id**: Create new group using the email address as a reference to an existing group from an Azure Active Directory backed provider. Required if **name** or **origin-id** is missing. +- **email-id**: Create new group using the email address as a reference to an existing group from a Microsoft Entra backed provider. Required if **name** or **origin-id** is missing. - **groups**: A comma-separated list of descriptors referencing groups you want the newly created group to join. - **name**: Name of the new security group. Required if **origin-id** or **email-id** is missing. -- **origin-id**: Create new group using the OriginID as a reference to an existing group from an Azure AD backed provider. Required if **name** or **email-id** is missing. +- **origin-id**: Create new group using the OriginID as a reference to an existing group from a Microsoft Entra backed provider. Required if **name** or **email-id** is missing. - **project**: Name or ID of the project in which the group should be created. - **scope**: Create group at project or organization level. Accepted values are *organization* and *project* (default). @@ -328,4 +327,3 @@ az devops security group membership remove --group-id vssgp.Uy0xLTktMTU1MTM3NDI0 - [Manage tokens and namespaces](manage-tokens-namespaces.md) - [Security REST API](/rest/api/azure/devops/security/) - [TFSSecurity command](/azure/devops/server/command-line/tfssecurity-cmd) -- [Security glossary](security-glossary.md) diff --git a/docs/organizations/security/add-remove-manage-user-group-security-group.md b/docs/organizations/security/add-remove-manage-user-group-security-group.md index 04652b8f407..83095751309 100644 --- a/docs/organizations/security/add-remove-manage-user-group-security-group.md +++ b/docs/organizations/security/add-remove-manage-user-group-security-group.md @@ -8,35 +8,26 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 10/20/2023 --- - -# Add or remove users or groups, manage security groups +# Use security groups to manage users and groups [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The recommended method for managing permissions and access is to assign users to a security group. You can assign users to a default security group or create a custom group to grant or restrict permissions. You can add users and groups to more than one security group. For example, you add most developers to the **Contributors** group. When that same user is added as a member to a team, then they are added to the team's system-generated security group. - -This article shows how to perform the following tasks: - -- Create a custom security group at the project or collection level -- Add or remove users or groups to a security group -- Change a group name, image, or description -- Delete a custom security group +To manage permissions and access, use security groups. You can use default or custom groups to set permissions. You can add users and groups to multiple groups. For instance, you add most developers to the **Contributors** group. When they join a team, they also join the team’s group. -For information on the following related tasks, see the corresponding articles: +For more information, see the following articles: - - [Add AD/Azure AD users or groups to a built-in security group](add-ad-aad-built-in-security-groups.md) + - [Add Active Directory / Microsoft Entra users or groups to a built-in security group](add-ad-aad-built-in-security-groups.md) - [Add users & manage access](../accounts/add-organization-users.md) - [Add users or groups to a team or project](add-users-team-project.md) - - [Remove user accounts](remove-users-prohibit-access.md) - - [Grant or restrict access using permissions](restrict-access.md) + - [Remove user accounts](/azure/active-directory/add-users-azure-active-directory#delete-a-user) + - [Manage access using permissions](restrict-access.md) - [Change project-level permissions](../security/change-project-level-permissions.md) - [Change project collection-level permissions](../security/change-organization-collection-level-permissions.md) -> [!NOTE] -> Users inherit permissions from the group(s) that they belong to. If a permission is set to **Allow** for one group and **Deny** for another group to which the user belongs, then their effective permission assignment is **Deny**. To learn more about permission inheritance, see [Get started with permissions, access, and security groups, Permission inheritance and security groups](about-permissions.md#inheritance). +Users inherit permissions from the group(s) that they belong to. If a permission is set to **Allow** for one group and **Deny** for another group to which the user belongs, then their effective permission assignment is **Deny**. For more information, see [About permissions/Inheritance](about-permissions.md#security-groups-and-membership). ## How Azure DevOps uses security groups @@ -50,134 +41,119 @@ Azure DevOps uses security groups for the following purposes: - Add a group to a role-based permission - Set object-level permissions to a security group - [!INCLUDE [version-all](./includes/hidden-security-groups.md)] - - ## Prerequisites -* To manage permissions or groups at the project level, you must be a member of the **Project Administrators** Group. If you created the project, you are automatically added as a member of this group. -* To manage permissions or groups at the collection or instance level, you must be a member of the **Project Collection Administrators** Group. If you created the organization or collection, you are automatically added as a member of this group. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - To manage permissions or groups at the project level: Member of the **Project Administrators** security group.
      - To manage permissions or groups at the collection level: Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. | ::: moniker range="azure-devops" > [!NOTE] -> Users added to the **Project-Scoped Users** group can't access most **Organization Settings** pages, including Permissions. To learn more, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). +> Users added to the **Project-Scoped Users** group can't access most **Organization settings** pages, including permissions. For more information, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). ::: moniker-end - + ## Create a custom security group -You create a custom security group from the **Project settings>Permissions** or **Organization settings>Permissions** pages. -Choose to create a project-level group when you want to manage permissions at the project or object-level for a project. Create a collection-level group when you want to manage permissions at the collection level. To learn more about setting permissions for these areas, see [Change project-level permissions](change-project-level-permissions.md) and [Change project collection-level permissions](change-organization-collection-level-permissions.md). - +Create a project-level group when you want to manage permissions at the project- or object-level for a project. Create a collection-level group when you want to manage permissions at the collection level. For more information, see [Change project-level permissions](../security/change-project-level-permissions.md) and [Change project collection-level permissions](../security/change-organization-collection-level-permissions.md). ::: moniker range="azure-devops" - > [!NOTE] -> To enable the **Project Permissions Settings Page** or the **Organization Permissions Settings Page v2** preview pages, see [Enable preview features](../../project/navigation/preview-features.md). Both preview pages provide a group settings page that the current page does not. +> To turn on the **Project Permissions Settings Page** or the **Organization Permissions Settings Page v2** preview pages, see [Enable preview features](../../project/navigation/preview-features.md). Both preview pages provide a group settings page that the current page doesn't. ::: moniker-end ::: moniker range="azure-devops" #### [Preview page](#tab/preview-page) -### To create a project-level group +### Create a project-level group -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +1. Open the web portal and select the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). -2. Choose **Project settings**, and then **Permissions**. +2. Select **Project settings** > **Permissions**. ![Screenshot, open Project settings, Permissions.](media/permissions/project-settings-permissions.png) -1. Choose **New Group** to open the dialog for adding a group. +3. Select **New Group** to open the dialog for adding a group. -### To create a project collection-level group +### Create a project collection-level group -1. Open the web portal, choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps icon, and then select :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: **Organization settings**. +1. Open the web portal and select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps icon, and then select :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: **Organization settings**. - > [!div class="mx-imgBorder"] - > ![Open Organization settings](../../media/settings/open-admin-settings-vert-2.png) + ![Screenshot of opening Organization settings.](../../media/settings/open-admin-settings-vert-2.png) -1. Under **Security**, choose **Permissions**, and then choose **New group** to open the dialog for adding a group. +2. Under **Security**, select **Permissions**, and then choose **New group** to open the dialog for adding a group. - > [!div class="mx-imgBorder"] - > ![Create security group at the organization-level](media/project-collection/organization-permissions-add-group.png) + ![Screenshot showing creating a security group at the organization-level.](media/project-collection/organization-permissions-add-group.png) - -### To define the new group +### Define the new group 1. In the dialog that opens, enter a **Name** for the group. Optionally, add members and a description for the group. For example, here we define a Work Tracking Administrators group. - > [!div class="mx-imgBorder"] - > ![Security group dialog, Add a security group at the organization-level](media/project-collection/create-new-group-at-org-level.png) + :::image type="content" source="media/project-collection/create-new-group-at-org-level.png" alt-text="Screenshot of the security group dialog, Add a security group at the organization-level."::: - Choose **Create** when done. +2. Choose **Create** when you're done. #### [Current page](#tab/current-page) +### Create a project-level group -### To create a project-level group - -1. Open the web portal and choose the project where you want to add users or groups. +1. Open the web portal and select the project where you want to add users or groups. -2. Choose **Project settings**, and then **Security**. +2. Select **Project settings** > **Security**. :::image type="content" source="media/add-groups/create-group.png" alt-text="Screenshot of Create group button."::: -1. Choose **Create Group** to open the dialog for adding a group. +1. Select **Create Group** to open the dialog for adding a group. -### To create a project collection-level group +### Create a project collection-level group -1. Open the web portal. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps icon, then :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: **Organization settings**, and then **Security**. +1. Open the web portal and select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps icon, then :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: **Organization settings** > **Security**. - > [!div class="mx-imgBorder"] - > ![Open Organization settings](../../media/settings/open-admin-settings-vert-2.png) + ![Screenshot of Opening Organization settings.](../../media/settings/open-admin-settings-vert-2.png) 1. Under **Security**, choose **Permissions**, and then choose **New group** to open the dialog for adding a group. - > [!div class="mx-imgBorder"] - > ![Create security group at the organization-level](media/project-collection/organization-permissions-add-group.png) + ![Screenshot of Creating a security group at the organization-level.](media/project-collection/organization-permissions-add-group.png) +### Define the new group -### To define the new group - -3. In the dialog that opens, enter a **Name** for the group. Optionally, add members and a description for the group. +1. In the dialog that opens, enter a **Name** for the group. Optionally, add members and a description for the group. For example, here we define a Work Tracking Administrators group. - > [!div class="mx-imgBorder"] - > ![Security group dialog, Add a security group at the organization-level](media/project-collection/create-new-group-at-org-level.png) + ![Screenshot of security group dialog, Add a security group at the organization-level.](media/project-collection/create-new-group-at-org-level.png) - Choose **Create** when done. +2. Select **Create** when you're done. --- ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" **Security**. *To see the full image, select to expand*. - [![Project Settings>Security](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) + [![Screenshot of Project Settings, Security page.](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) 3. Under **Groups**, choose one of the following options: - **Readers**: To add users who require read-only access to the project, choose. - **Contributors**: To add users who contribute fully to this project or who have been granted Stakeholder access. - - **Project Administrators**: To add users who need to administrate the project. To learn more, see [Change project-level permissions](change-project-level-permissions.md). + - **Project Administrators**: To add users who need to administrate the project. For more information, see [Change project-level permissions](change-project-level-permissions.md). -4. Next, choose the **Members** tab. +4. Select the **Members** tab. Here we choose the **Contributors** group. - > [!div class="mx-imgBorder"] - > ![Security page, Contributors group, Membership page](media/add-users/add-members-to-contributors-group.png) + ![Screenshot showing the security page, Contributors group, Membership page.](media/add-users/add-members-to-contributors-group.png) The default team group, and any other teams you add to the project, get included as members of the **Contributors** group. Add a new user as a member of a team instead, and the user automatically inherits Contributor permissions. @@ -188,80 +164,31 @@ Choose to create a project-level group when you want to manage permissions at th 6. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. choose the match(es) that meets your requirements. - ![Add users and group dialog, server version.](media/project-level-permissions-add-a-user.png) - - > [!NOTE] - > The first time you add a user or group to Azure DevOps, - > you can't browse to it or check the friendly name. - > After the identity has been added, you can just enter the friendly name. - - Choose **Save changes** when complete. - -7. (Optional) You can customize a user's permission for other functionality in the project. For example, in [areas and iterations](set-permissions-access-work-tracking.md) or [shared queries](../../boards/queries/set-query-permissions.md). - - > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see [Permissions and access](permissions-access.md). - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). - -2. Choose the :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: gear icon to open the administrative context. - - :::image type="content" source="../../media/settings/open-project-settings-horz.png" alt-text="Open Project Settings, horizontal nav"::: - -3. Choose **Security** and under **Groups**, choose one of the following options: - - **Readers**: To add users who require read-only access to the project, choose. - - **Contributors**: To add users who contribute fully to this project or who have been granted Stakeholder access. - - **Project Administrators**: To add users who need to administrate the project. To learn more, see [Change project-level permissions](change-project-level-permissions.md). - -4. Next, choose the **Members** tab. - - Here we choose the Contributors group. - - > [!div class="mx-imgBorder"] - > ![Security page, Contributors group, Membership page](media/add-users/add-members-to-contributors-group.png) - - > [!TIP] - > Managing users is much easier [using groups](../../organizations/security/about-permissions.md), not individual users. - - By default, the default team group and any other teams you add to the project, are included as members of the **Contributors** group. Add a new user as a member of a team instead, and the user automatically inherits Contributor permissions. + ![Screenshot showing Add users and group dialog, server version.](media/project-level-permissions-add-a-user.png) -5. Choose ![gear icon](../../media/icons/add-light-icon.png)**Add** to add a user or a user group. + The first time you add a user or group to Azure DevOps, you can't browse to it or check the friendly name. After the identity gets added, you can just enter the friendly name. -6. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. +7. Choose **Save changes** when you're done. - ![Add users and group dialog](media/project-level-permissions-add-a-user.png) +8. (Optional) You can customize a user's permission for other functionality in the project. For example, in [areas and iterations](set-permissions-access-work-tracking.md) or [shared queries](../../boards/queries/set-query-permissions.md). > [!NOTE] - > The first time you add a user or group to Azure DevOps, - > you can't browse to it or check the friendly name. - > After the identity has been added, you can just enter the friendly name. - -7. (Optional) You can customize user permissions for other functionality within the project, such as [areas and iterations](set-permissions-access-work-tracking.md) or [shared queries](../../boards/queries/set-query-permissions.md). - - > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see [Permissions and access](permissions-access.md). + > Users with limited access, such as Stakeholders, can't access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). ::: moniker-end - - - + ## Add users or groups to a security group As roles and responsibilities change, you might need to change the permission levels for individual members of a project. The easiest way to do that is to add the user or a group of users to either a default or custom security group. If roles change, you can then remove the user from a group. -Here we show how to add a user to the built-in **Project Administrators** group. The method is similar no matter what group you are adding. If your organization is connected to Azure Active Directory or Active Directory, then you can add security groups defined in those directories to Azure DevOps security groups. To learn more, see [Add AD/Azure AD users or groups to a built-in security group](add-ad-aad-built-in-security-groups.md). - +Here we show how to add a user to the built-in **Project Administrators** group. The method is similar no matter what group you're adding. If your organization is connected to Microsoft Entra ID or Active Directory, then you can add security groups defined in those directories to Azure DevOps security groups. For more information, see [Add Active Directory / Microsoft Entra users or groups to a built-in security group](add-ad-aad-built-in-security-groups.md). If you need to add more than 10k users or groups to an Azure DevOps security group, we recommend adding an Azure Directory / Microsoft Entra group containing the users, instead of adding the users directly. ::: moniker range="azure-devops" > [!NOTE] -> To enable the **Project Permissions Settings Page** or the **Organization Permissions Settings Page v2** preview pages, see [Enable preview features](../../project/navigation/preview-features.md). Both preview pages provide a group settings page that the current page does not. +> To turn on the **Project Permissions Settings Page** or the **Organization Permissions Settings Page v2** preview pages, see [Enable preview features](../../project/navigation/preview-features.md). Both preview pages provide a group settings page that the current page doesn't. ::: moniker-end ::: moniker range="azure-devops" @@ -275,17 +202,17 @@ Here we show how to add a user to the built-in **Project Administrators** group. For example, here we choose the **Project Administrators** group, **Members**, and then **Add**. > [!div class="mx-imgBorder"] - > ![Project Settings > Permissions, Add member](media/project-collection/project-admin-members-add-s154.png) + > ![Project Settings > Permissions, Add member](media/project-collection/project-admin-members-add.png) -4. Enter the name of the user account into the text box and then select from the match that appears. You can enter several identities recognized by the system into the **Add users and/or groups** box. The system automatically searches for matches. Choose the matches that meet your choices. +2. Enter the name of the user account into the text box and then select from the match that appears. You can enter several identities recognized by the system into the **Add users and/or groups** box. The system automatically searches for matches. Choose the matches that meet your choices. > [!div class="mx-imgBorder"] > ![Add users and group dialog, preview page.](media/project-collection/add-member-project-admin.png) > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see [Permissions and access](permissions-access.md). + > Users with limited access, such as Stakeholders, can't access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). -5. Choose **Save**. +3. Select **Save**. #### [Current page](#tab/current-page) @@ -295,25 +222,22 @@ Here we show how to add a user to the built-in **Project Administrators** group. For example, here we choose the **Project Administrators** group, **Members**, and then **Add**. - > [!div class="mx-imgBorder"] - > ![Screenshot of Project Settings>Security, Add member.](media/project-level-permissions-add-member.png) + ![Screenshot of Project Settings>Security, Add member.](media/project-level-permissions-add-member.png) -4. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. +2. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. - > [!div class="mx-imgBorder"] - > ![Add users and group dialog, current page.](media/project-level-permissions-add-a-user.png) + ![Screenshot of Add users and group dialog, current page.](media/project-level-permissions-add-a-user.png) > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see [Permissions and access](permissions-access.md). + > Users with limited access, such as Stakeholders, can't access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). -5. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. +3. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. * * * ::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] - > ![Project Settings>Security, Add member](media/project-level-permissions-add-member.png) + ![Screenshot of Project Settings, Security, Add member page.](media/project-level-permissions-add-member.png) 1. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. - > [!div class="mx-imgBorder"] - > ![Add users and group dialog, on-premises.](media/project-level-permissions-add-a-user.png) + ![Screenshot of Add users and group dialog, on-premises.](media/project-level-permissions-add-a-user.png) > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see [Permissions and access](permissions-access.md). + > Users with limited access, such as Stakeholders, can't access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). -1. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. +2. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. ::: moniker-end -::: moniker range="< azure-devops-2019" - -1. Open the **Permissions** page for either the project-level or organization-level as described in the previous section, [Create a custom security group](#create-custom-group). - -1. Choose the security group whose members you want to manage, then choose the **Members** tab, and then choose **Add**. - - For example, here we choose the **Project Administrators** group, **Members**, and then **Add**. - - > [!div class="mx-imgBorder"] - > ![Project Settings>Security, Add member](media/project-level-permissions-add-member.png) - -3. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. - - > [!div class="mx-imgBorder"] - > ![Add users and group dialog, TFS 2018 and earlier versions.](media/project-level-permissions-add-a-user.png) - - > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see [Permissions and access](permissions-access.md). - -4. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. - -::: moniker-end - ## Change permissions for a user or group -To change the permissions for a user or group, you need to open the security dialog for the user or group. Because permissions are defined at different levels, review the following articles to open the dialog for the permissions you want to change: +Because permissions are defined at different levels, review the following articles to open the dialog for the permissions you want to change: - [Object-level permissions](set-object-level-permissions.md) - [Project-level permissions](change-project-level-permissions.md) @@ -369,19 +268,15 @@ To change the permissions for a user or group, you need to open the security dia ## Remove users or groups from a security group -You add or remove users from a group from the **Members** tab of a selected group. - ::: moniker range="azure-devops" -1. For the user or group you want to remove, choose :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More options**, and then **Remove**. +1. For the user or group you want to remove, select :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More options** > **Remove**. - > [!div class="mx-imgBorder"] - > ![Screenshot of Remove a user, cloud version.](media/project-collection/remove-admin-member-s157.png) + ![Screenshot of Remove a user, cloud version.](media/project-collection/remove-admin-member-s157.png) -1. Choose **Delete** to confirm removal of the group member. +2. Select **Delete** to confirm removal of the group member. - > [!div class="mx-imgBorder"] - > ![Remove user confirmation dialog, cloud version.](media/project-collection/delete-member-confirm-dialog.png) + ![Screenshot of Remove user confirmation dialog, cloud version.](media/project-collection/delete-member-confirm-dialog.png) ::: moniker-end @@ -389,31 +284,28 @@ You add or remove users from a group from the **Members** tab of a selected grou - To remove a user from a group, choose **Remove** next to the user's name that you want to remove. - > [!div class="mx-imgBorder"] - > ![Remove user confirmation dialog, on-premises versions.](media/project-collection/remove-admin-member-server.png) + ![Screenshot of Remove user confirmation dialog, on-premises versions.](media/project-collection/remove-admin-member-server.png) ::: moniker-end - ## Manage group settings ::: moniker range="azure-devops" > [!NOTE] -> To enable the **Project Permissions Settings Page** or the **Organization Permissions Settings Page v2** preview pages, see [Enable preview features](../../project/navigation/preview-features.md). Both preview pages provide a group settings page that the current page does not. +> To turn on the **Project Permissions Settings Page** or the **Organization Permissions Settings Page v2** preview pages, see [Enable preview features](../../project/navigation/preview-features.md). Both preview pages provide a group settings page that the current page doesn't. #### [Preview page](#tab/preview-page) 1. Open the **Permissions** page for either the project-level or organization-level as described earlier in this article, [Create a custom security group](#create-custom-group). -1. Choose the **Settings** tab. You can change a group description, add a group image, or delete a group through the group **Settings** page. +1. Choose the **Settings** tab. You can change a group description, add a group image, or delete a group through the group **Settings** page. -From the **Project settings > Permissions** or **Organization settings > Permissions** page, choose the group you want to manage, and then choose **Settings**. +From the **Project settings > Permissions** or **Organization settings** > **Permissions** page, choose the group you want to manage, and then choose **Settings**. For example, here we open the Settings for the Work Tracking Administrators group. -> [!div class="mx-imgBorder"] -> ![Screenshot of Open group settings, preview page.](media/project-collection/group-settings.png) +![Screenshot of Open group settings, preview page.](media/project-collection/group-settings.png) You can modify the group name, group description, upload an image, or delete the group. @@ -423,18 +315,17 @@ You can change a group description or add a group image by editing the group pro ### Manage project-level groups -1. From the **Project settings > Security** page, choose the group you want to manage, and choose from the **Edit** menu to either **Edit profile** or **Delete**. +1. From the **Project settings** > **Security** page, select the group you want to manage, and choose from the **Edit** menu to either **Edit profile** or **Delete**. For example, here we open the **Edit profile** for the Stakeholder Access group. - > [!div class="mx-imgBorder"] - > ![Edit group profile](media/project-collection/edit-group-profile-delete-project-level-current.png) + ![Screenshot of Edit group profile.](media/project-collection/edit-group-profile-delete-project-level-current.png) - . . . and change the description. Note that you can change the name of the group as well. + . . . and change the description. You can change the name of the group as well. > [!div class="mx-imgBorder"] > ![Screenshot of Edit group profile description](media/project-collection/edit-project-level-group-current.png) -1. Choose **Save** to save your changes. +2. Choose **Save** to save your changes. ### Manage organization-level groups @@ -445,7 +336,7 @@ You can change a group description or add a group image by editing the group pro > [!div class="mx-imgBorder"] > ![Screenshot of context menu for Custom group](media/project-collection/org-permissions-group-edit-delete-v1.png) - . . . and change the description. Note that you can change the name of the group as well. + . . . and change the description. You can change the name of the group as well. > [!div class="mx-imgBorder"] > ![Edit group profile description, cloud version](media/project-collection/edit-org-group-dialog-v1.png) @@ -469,7 +360,7 @@ You can change a group name, description, add a group image, or delete a group. > [!div class="mx-imgBorder"] > ![Open Edit group profile, on-premises versions.](media/project-collection/edit-group-profile-delete-project-level-current.png) - . . . and change the description. Note that you can change the name of the group as well. + . . . and change the description. You can change the name of the group as well. > [!div class="mx-imgBorder"] > ![Edit group dialog profile description, on-premises versions.](media/project-collection/edit-project-level-group-current.png) @@ -478,7 +369,7 @@ You can change a group name, description, add a group image, or delete a group. ## On-premises deployments -For on-premises deployments, see these additional articles: +For on-premises deployments, see these other articles: - [Add a user as an Azure DevOps Server administrator](/azure/devops/server/admin/add-administrator) - [Azure DevOps Server service account groups](/azure/devops/server/admin/service-accounts-dependencies) @@ -487,12 +378,10 @@ For on-premises deployments, see these additional articles: ::: moniker range="< azure-devops" -If your on-premises deployment is integrated with SQL Server Reports, you'll need to manage membership for those products separately from their websites. See [Grant permissions to view or create SQL Server reports in TFS](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports). +If your on-premises deployment is integrated with SQL Server Reports, you need to manage membership for those products separately from their websites. See [Grant permissions to view or create SQL Server reports in TFS](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports). ::: moniker-end - - ## Next steps > [!div class="nextstepaction"] @@ -505,4 +394,3 @@ If your on-premises deployment is integrated with SQL Server Reports, you'll nee - [Permissions lookup reference](permissions-lookup-guide.md) - [Permissions and groups reference](permissions.md) - [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) - diff --git a/docs/organizations/security/add-users-team-project.md b/docs/organizations/security/add-users-team-project.md index 63f420af3e9..224eb488673 100644 --- a/docs/organizations/security/add-users-team-project.md +++ b/docs/organizations/security/add-users-team-project.md @@ -1,65 +1,55 @@ --- title: Add users or groups to a team or project -description: How to guide to add users or groups to a team or project +description: How to add users or groups to a team, or add members or groups to a project. ms.assetid: 3cfefdd2-b161-4e04-8dc0-e2deeac50262 ms.subservice: azure-devops-security -ms.custom: contperf-fy21q4 ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 12/27/2022 +ms.date: 01/22/2024 --- - # Add users or groups to a team or project [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] ::: moniker range="azure-devops" -You add users to a team or project so they can contribute to the team and project. For enterprise organizations with large user bases, we recommend you use Azure Active Directory to add and manage new users through security groups. However, to enable flexibility for all size organizations, the following operations are supported: - -- Team and project administrators can add new users to their team or project, unless the policy [Allow team and project administrators to invite new users](restrict-invitations.md) is disabled. New users are ones that haven't been added to the organization. -- When you add new users through the team and project user interfaces, the system automatically assigns an access level to the user. -- Adding users to a team or project automatically adds them to the Contributors group for the project. Members of the Contributors group have permissions to most features needed to contribute. -- By adding users to a team, you make team-specific tools aware of them, such as the team security group, Team Members widget, and sprint capacity planning tools. -- Once users have been added to a project or organization, you can browse for their display name or user name (email alias) from any people-picker tool. +In this article, learn how to add users or groups to a team or project. For organizations with large user bases, we recommend you use Microsoft Entra ID to add and manage new users through security groups. However, to enable flexibility for all size organizations, Azure DevOps supports the following operations. ::: moniker-end ::: moniker range="< azure-devops" -You add users to a team or project so they can contribute to the team and project. For enterprise organizations with large user bases, we recommend you use Active Directory or Windows Group to manage users through security groups. However, to enable flexibility for all size organizations, the following operations are supported: - -- Team and project administrators can add existing users to their team or project. Existing users are ones known to the project collection through Active Directory or Windows group. -- Adding users to a team or project automatically adds them to the Contributors group for the project. Members of the Contributors group have permissions to most features needed to contribute. -- By adding users to a team, you make team-specific tools aware of them, such as the team security group, Team Members widget, and sprint capacity planning tools. -- Once users have been added to a project or organization, you can browse for their display name or user name (email alias) from any people-picker tool. +In this article, learn how to add users to a team or project. For organizations with large user bases, we recommend you use Active Directory or Windows Group to manage users through security groups. However, to enable flexibility for all size organizations, Azure DevOps supports the following operations. ::: moniker-end -You add projects to an organization or project collection and you add teams to projects. For more information, see: -- [Create a project](../projects/create-project.md) -- [Add team, go from one default team to others](../settings/add-teams.md) +## Prerequisites -[!INCLUDE [version-all](../../includes/version-selector-minimize.md)] +[!INCLUDE [temp](../../includes/prerequisites-add-users-org.md)] +[!INCLUDE [temp](../../includes/prerequisites-add-users-server.md)] -## Supported options for adding users +**Recommended**: If you're new to Azure DevOps, familiarize yourself with the information in the following articles: -::: moniker range="azure-devops" +- [Get started with permissions, access levels, and security groups](about-permissions.md) +- [About projects and scaling your organization](../projects/about-projects.md) +- [Default permissions and access quick reference](permissions-access.md) +- [About teams and Azure Boards tools](../settings/about-teams-and-settings.md) -Depending on the interface you use, you can exercise different options for adding new or existing users to teams or projects. + +## Supported options for adding users + +::: moniker range="azure-devops" +Depending on your administrator level and interface, you can add new or existing users to teams or projects in the following ways. ::: moniker-end ::: moniker range="< azure-devops" - Team and project administrators can add existing users to their team or project. Existing users are ones that are known to a project collection through the Active Directory or Windows Group created for the server that hosts the on-premises Azure DevOps Server. - ::: moniker-end - :::row::: :::column span="1"::: **Administrator level** @@ -80,19 +70,20 @@ Team and project administrators can add existing users to their team or project. [Team Members dashboard widget](#widget) :::column-end::: :::column span="2"::: - Add new or existing users to a team. Send new users an invite. + - Add new or existing users to a team. + - Send new users an invitation. :::column-end::: :::row-end::: ::: moniker-end :::row::: :::column span="1"::: - Team administrators + :::column-end::: :::column span="2"::: - [**Project Settings>Teams>Team>Members**](#teams-page) + [**Project settings** > **Teams** > **Team** > **Members**](#teams-page) :::column-end::: :::column span="2"::: - Add existing users or groups to a team, or remove a member. + Add existing users or groups to a team. :::column-end::: :::row-end::: :::row::: @@ -100,21 +91,24 @@ Team and project administrators can add existing users to their team or project. Project Administrators :::column-end::: :::column span="2"::: - [Project **Summary** page, **Invite**](#summary-page) + [Project **Summary** page > **Invite**](#summary-page) :::column-end::: :::column span="2"::: - Add new or existing users. Send new users an invite. Optionally add users to one or more teams. + - Add new or existing users. + - Send new users an invite. + - Optionally add users to one or more teams. :::column-end::: :::row-end::: :::row::: :::column span="1"::: - Project Administrators + :::column-end::: :::column span="2"::: - [**Project Settings** > **Permissions** > **Groups** > **Group** > **Members**](#project-permissions) + [**Project settings** > **Permissions** > **Groups** > **Group** > **Members**](#project-permissions) :::column-end::: :::column span="2"::: - Add existing users or groups to a security group. By adding to a team group, you effectively add them to the team. Optionally remove a user from a group. + - Add existing users or groups to a security group. By adding to a team group, you effectively add them to the team. + - Optionally remove a user from a group. :::column-end::: :::row-end::: ::: moniker range="azure-devops" @@ -123,15 +117,17 @@ Team and project administrators can add existing users to their team or project. Project Collection Administrators :::column-end::: :::column span="2"::: - [**Organization Settings** > **Users**](../accounts/add-organization-users.md) + [**Organization settings** > **Users**](../accounts/add-organization-users.md) :::column-end::: :::column span="2"::: - Add new users to an organization and send an invite. Must specify the access level. Optionally add them to select projects. Can use [Group rules](../accounts/assign-access-levels-by-group-membership.md) to further manage groups being added. + - Add new users to an organization and send an invite. Must specify the access level. + - Optionally add users to select projects. + - Use [Group rules](../accounts/assign-access-levels-by-group-membership.md) to further manage groups. :::column-end::: :::row-end::: :::row::: :::column span="1"::: - Project Collection Administrators + :::column-end::: :::column span="2"::: [`az devops user` CLI](../accounts/add-organization-users.md#add-users-to-your-organization) @@ -144,13 +140,13 @@ Team and project administrators can add existing users to their team or project. ::: moniker range="azure-devops" :::row::: :::column span="1"::: - Azure Active Directory Administrators + Microsoft Entra Administrators :::column-end::: :::column span="2"::: - Azure Active Directory + Microsoft Entra ID :::column-end::: :::column span="2"::: - Users you add to Azure Active Directory connected to Azure DevOps Services are added to the Project Collection Valid Users group. For more information, see [Connect your organization to Azure Active Directory](../accounts/connect-organization-to-azure-ad.md). + Add users to Microsoft Entra, connected to Azure DevOps Services. These users get added to the Project Collection Valid Users group. For more information, see [Connect your organization to Microsoft Entra ID](../accounts/connect-organization-to-azure-ad.md). :::column-end::: :::row-end::: ::: moniker-end @@ -163,82 +159,37 @@ Team and project administrators can add existing users to their team or project. Active Directory or Windows Group :::column-end::: :::column span="2"::: - Users you add to Active Directory or Windows Group connected to Azure DevOps are added as members of the Project Collection Valid Users group. They have access to all projects within a project collection. For more information, see [Set up groups for use in Azure DevOps on-premises](/azure/devops/server/admin/setup-ad-groups?view=azure-devops-2020&preserve-view=true). + Add users to Active Directory or Windows Group, connected to Azure DevOps. These users get added as members of the Project Collection Valid Users group and have access to all projects within a project collection. For more information, see [Set up groups for use in Azure DevOps on-premises](/azure/devops/server/admin/setup-ad-groups?view=azure-devops-2020&preserve-view=true). :::column-end::: :::row-end::: ::: moniker-end - -## Prerequisites - -[!INCLUDE [temp](../../includes/prerequisites-add-users-org.md)] - -[!INCLUDE [temp](../../includes/prerequisites-add-users-server.md)] - -If you're new to Azure DevOps, you may want to familiarize yourself with the information provided in these articles: - -- [Get started with permissions, access levels, and security groups](about-permissions.md) -- [About projects and scaling your organization](../projects/about-projects.md) -- [Default permissions and access quick reference](permissions-access.md) -- [About teams and Azure Boards tools](../settings/about-teams-and-settings.md) - - - - ::: moniker range="azure-devops" ## Add a user from the Team Members widget -As a team administrator, you can add new or existing members from the **Team Members** dashboard widget. To add this widget to a dashboard, see [Add widgets to a dashboard](../../report/dashboards/add-widget-to-dashboard.md). +As a team administrator, you can add new or existing members from the **Team Members** dashboard widget. For more information, see [Add widgets to a dashboard](../../report/dashboards/add-widget-to-dashboard.md). -1. To invite someone to your team, choose the plus button on the Team Members widget. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization/Your_Project}```). +2. Select **Dashboards** and then choose your dashboard. + + :::image type="content" source="../../report/dashboards/media/dashboards/open-dashboards-vert.png" alt-text="Screenshot shows Dashboards tab selected."::: + +3. Select :::image type="icon" source="../../media/icons/add-team-member-plus-sign-blue.png" border="false"::: **Manage team members** on the Team Members widget. :::image type="content" source="media/add-users/team-member-widget.png" alt-text="Screenshot of Team Members widget added to a dashboard, plus icon."::: -2. For new users, enter their email address. For existing users, type their name until it resolves as a known name to the system. You can add several email addresses or account names by separating them with a semicolon (;). - :::row::: - :::column span=""::: - Choose the entry listed under **Add users** to complete the entry. - > [!NOTE] - > Any valid email address is acceptable. When the user accepts the invitation and signs into Azure DevOps, they register their email address as a Microsoft account and choose a password. - :::column-end::: - :::column span=""::: - Choose the name that appears to complete the entry. - :::column-end::: - :::row-end::: - :::row::: - :::column span=""::: - :::image type="content" source="media/add-users/invite-members-dialog.png" alt-text="Invite members to a team dialog, enter an unknown user email address."::: - :::column-end::: - :::column span=""::: - :::image type="content" source="media/add-users/invite-members-known-user.png" alt-text="Invite members to a team dialog, enter a known user account."::: - :::column-end::: - :::row-end::: +4. Enter email addresses for new users. For existing users, enter their name until it resolves as a known name to the system. Separate multiple entries with a semicolon (;). Select **Add**. -2. Complete the addition. - :::row::: - :::column span=""::: - When the user is unknown, you'll get a notification that an access level must be assigned. To complete the invitation, choose **Add**. - :::column-end::: - :::column span=""::: - Choose **Add** to complete adding the user. Known users don't receive an invitation. - :::column-end::: - :::row-end::: - :::row::: - :::column span=""::: - :::image type="content" source="media/add-users/invite-members-dialog-add-info.png" alt-text="Invite members to a team dialog, Add new user account. "::: - :::column-end::: - :::column span=""::: - :::image type="content" source="media/add-users/invite-members-dialog-complete-add.png" alt-text="Invite members to a team dialog, Add button."::: - :::column-end::: - :::row-end::: + When the user's unknown, a notification advises that an access level must be assigned. To complete the invitation, select **Add**. + :::image type="content" source="media/add-users/invite-members-dialog-add-info.png" alt-text="Screenshot of the Invite members to a team dialog, Add new user account."::: - When you add a new user, the system assigns Stakeholder as the access level when all free five Basic access levels have been assigned. Active contributors to a project need to have Basic access as a minimum. A Project Collection Administrator can change the access level and resend invitations from the [**Organization Settings>Users** page](#manage-users). + When you add a new user, the system assigns Stakeholder as the access level when all free five Basic access levels are already assigned. Active contributors to a project need to have Basic access as a minimum. A Project Collection Administrator can change the access level and resend invitations from the [**Organization Settings** > **Users** page](#manage-users). - > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). + > [!NOTE] + > Users with limited access, such as Stakeholders, can't access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). -1. (Optional) A message will briefly display on the screen to indicate success or failure. Choose **Details** to open the notification and review details. +5. (Optional) A notification briefly displays to indicate success or failure. Select **Details** to open the notification and review details. :::row::: :::column span=""::: @@ -248,14 +199,6 @@ As a team administrator, you can add new or existing members from the **Team Mem :::image type="content" source="media/add-users/notification-failure.png" alt-text="Screenshot of notification failure message. "::: :::column-end::: :::row-end::: - :::row::: - :::column span=""::: - A success message indicates the status of adding the user to the system. - :::column-end::: - :::column span=""::: - A failure message indicates why the addition of the user failed. - :::column-end::: - :::row-end::: :::row::: :::column span=""::: :::image type="content" source="media/add-users/summary-invite-notifications-success.png" alt-text="Notification dialog of Success. "::: "::: @@ -265,32 +208,28 @@ As a team administrator, you can add new or existing members from the **Team Mem :::column-end::: :::row-end::: -1. New users receive an email inviting them to sign in to the project. Existing users don't receive any formal notification. +6. New users receive an email invitation to sign in to the project. Existing users don't receive a formal notification. ::: moniker-end - + ## Add users or groups to a team -Add existing users or security groups to a team from the **Project settings> Teams** page. From this interface you can view, add, or remove users and security groups to/from a team. To add a custom security group, see [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md). +Do the following steps to add existing users or security groups to a team. To add a custom security group, see [Manage security groups](add-remove-manage-user-group-security-group.md). ::: moniker range="azure-devops" [!INCLUDE [note-new-teams-page](../../includes/note-new-teams-page.md)] ::: moniker-end -#### [Preview UI](#tab/preview-page) - -::: moniker range="azure-devops" +#### [Preview page](#tab/preview-page) -You can toggle between direct or expanded membership views. The **Direct Members** view displays users and groups that have been added to the team. The **Expanded Members** view replaces any Azure DevOps groups with the members that belong to those groups. Azure Active Directory or Active Directory groups aren't expanded. +::: moniker range="azure-devops" -1. Open a backlog or board for a team and choose the :::image type="icon" source="../../media/icons/team.png" border="false"::: team profile icon. Then choose **Team Settings**. - - Here we open the Board for the Web team and from there the team profile. +1. Select **Boards** > **Boards** > **Show team profile** > **Team Settings**. > [!div class="mx-imgBorder"] > ![Screenshot of Work Backlog or Board, choose team profile icon.](../settings/media/team-defaults/open-team-profile-choose-team-settings.png) @@ -299,39 +238,34 @@ You can toggle between direct or expanded membership views. The **Direct Members :::image type="content" source="media/add-users/change-team-context.png" alt-text="Screenshot of Project Settings>Teams>Team and Teams breadcrumb."::: -3. Choose **Add**. +3. Select **Add**. > [!div class="mx-imgBorder"] > ![Screenshot of Team Profile, choose Add, preview page.](media/add-users/new-teams-page-add-member.png) -4. Enter the sign-in addresses or display name for each account you want to add. You can also add a project security group—such as another team group, custom group, or Azure Active Directory group when used by the organization. Add them one at a time or all at the same time. You can enter several identities into the text box, separated by commas. + You can toggle between direct or expanded membership views. The **Direct Members** view displays users and groups added to the team. The **Expanded Members** view replaces any Azure DevOps groups with the members who belong to those groups. Microsoft Entra ID or Active Directory groups don't expand. - :::image type="content" source="media/add-users/change-team-context.png" alt-text="Screenshot of Invite members to team dialog, choose user account."::: +4. Enter the sign-in address or display name one at a time or all together, separated by commas. You can also add a project security group--such as another team group, custom group, or Microsoft Entra group if used by the organization. - > [!TIP] - > You must enter user and group names one at a time. However, after entering a name, the account is added to the list, and you can enter another name in the Identities text box before choosing to save your changes. + :::image type="content" source="media/add-users/change-team-context.png" alt-text="Screenshot of Invite members to team dialog, choose user account."::: - You may need to choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see your updates. + Select :::image type="icon" source="../../media/icons/refresh.png" border="false"::: **Refresh** if you don't see your updates. -6. To add an account as a team administrator, choose the Settings page and then choose **Add** under the Administrators section. For details, see [Add a team administrator](../../organizations/settings/add-team-administrator.md) +5. To [add an account as a Team administrator](../../organizations/settings/add-team-administrator.md), go to the **Settings** page and select **Add** in the Administrators section. ::: moniker-end ::: moniker range="< azure-devops" -Choose the **Current page** tab for information on adding a user to a team. The **New Teams Page** preview feature is only available for Azure DevOps Services at this time. +Select the **Current page** tab for information on adding a user to a team. The **New Teams Page** preview feature is only available for Azure DevOps Services at this time. ::: moniker-end -#### [Current UI](#tab/current-page) - -::: moniker range=">= azure-devops-2019" +#### [Current page](#tab/current-page) -You can toggle between direct or expanded membership views. The **direct** view displays users and groups that have been added to the team. The **expanded** view replaces any Azure DevOps groups with the members that belong to those groups. Azure Active Directory or Active Directory groups aren't expanded. +::: moniker range="<=azure-devops" You add team members from **Project Settings>Work>Team configuration**. You can quickly navigate to it from a team work tracking backlog, board, or dashboard. -1. Open a backlog or board for a team and choose the **Show Team Profile** :::image type="icon" source="../../media/icons/team.png" border="false":::. Then choose **Team Settings**. - - Here we open the Board for the Web team and from there the team profile. +1. Select **Boards** > **Show team profile** > **Team Settings**. > [!div class="mx-imgBorder"] > ![Screenshot of Work Backlog or Board, choose team profile icon.](../settings/media/team-defaults/open-team-profile-choose-team-settings.png) @@ -341,42 +275,18 @@ You add team members from **Project Settings>Work>Team configuration**. You can > [!div class="mx-imgBorder"] > ![Screenshot of Team Configuration, Team breadcrumb.](../settings/media/team-defaults/select-team-context.png) -3. Choose **Add**. +3. Select **Add**. > [!div class="mx-imgBorder"] > ![Screenshot of Team Profile, choose Add, current page.](media/add-users/team-profile-choose-add.png) -4. Enter the sign-in addresses or display name for each account you want to add. Add them one at a time or all at the same time. You can enter several identities into the text box, separated by commas. +4. Enter the sign-in address or display name for each account you want to add. Add them one at a time or all at the same time, separated by commas, and then **Save changes**. ![Screenshot of Add users and group dialog, current page.](media/project-level-permissions-add-a-user.png) - > [!TIP] - > You must enter user and group names one at a time. However, after entering a name, the account is added to the list, and you can enter another name in the Identities text box before choosing to save your changes. + Select :::image type="icon" source="../../media/icons/refresh.png" border="false"::: **Refresh** if you don't see your updates. - You may need to choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see your updates. - -6. To add an account as a team administrator, choose **Add** located in the Team Profile page. For details, see [Add a team administrator](../../organizations/settings/add-team-administrator.md) - -::: moniker-end - -::: moniker range="tfs-2018" - -1. From the project admin context, open the **Overview** page, and then choose the team you want to add team members to. - - ![Screenshot of Project Settings, Overview page, Choose team.](media/add-users/overview-page-select-team.png) - -2. Choose the ![plus icon](../../media/icons/add-light-icon.png)**Add** to add a user or a user group. - -3. Enter the sign-in addresses or display name for each user you want to add. Add them one at a time or all at the same time. You can enter several identities into the text box, separated by commas. - - ![Screenshot of Add users and group dialog, 2018 and earlier.](media/project-level-permissions-add-a-user.png) - - > [!TIP] - > You must enter user and group names one at a time. However, after entering a name, it is added to the list, and you can enter another name in the Identities text box before choosing to save your changes. - - You may need to choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see your updates. - -5. To add an account as a team administrator, choose **Add** located in the Team Profile page. For details, see [Add a team administrator](../../organizations/settings/add-team-administrator.md). +5. To add an account as a Team administrator, select **Add** on the Team Profile page. For more information, see [Add a team administrator](../../organizations/settings/add-team-administrator.md) ::: moniker-end @@ -387,13 +297,13 @@ You add team members from **Project Settings>Work>Team configuration**. You can ## Remove users or groups from a team -From the team's **Members** page, you can remove members. +Do the following steps to remove a user or group from a team. #### [Preview UI](#tab/preview-page) ::: moniker range="azure-devops" -1. To remove members, open the team's **Members** page, choose **Direct Members**, check the checkbox of the user you want to remove, choose :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More options**, and then choose **Remove**. +1. Select **Project settings** > **Teams** > **Members** > **Direct Members**. For the user to be removed, select :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More options** >**Remove**. > [!div class="mx-imgBorder"] > ![Screenshot of Team profile page, remove a team member, new nav.](media/add-users/direct-members-remove.png) @@ -401,7 +311,7 @@ From the team's **Members** page, you can remove members. > [!TIP] > To remove a team administrator as a team member, you must first remove them as an administrator. -1. Confirm the removal by choosing **Delete** in the confirmation message. +2. Select **Delete** to confirm. :::image type="content" source="media/add-users/remove-user-confirmation.png" alt-text="Screenshot of Delete member dialog confirmation."::: @@ -413,7 +323,7 @@ Choose the **Current page** tab for information on adding a user to a team. The #### [Current UI](#tab/current-page) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. To remove members, open the team's **Members** page, choose **direct** membership, return to this page, highlight the user name and choose **Remove**. @@ -425,117 +335,8 @@ Choose the **Current page** tab for information on adding a user to a team. The ::: moniker-end -::: moniker range="tfs-2018" - -1. To remove members, return to this page, highlight the user name, and then choose **Remove**. - - ![Screenshot of Team profile page, remove a team member, highlight and remove.](media/add-users/team-page-remove-team-member.png) - - > [!NOTE] - > To remove a team administrator as a team member, you must first remove them as an administrator. - -::: moniker-end - --- - - - - - -## Invite users from the Summary page - -As a member of the Project Administrators group, you can add members to a project from the **Summary** page and optionally add them to one or more teams. For more information about the **Summary** page, see [Share your project vision, view project activity](../../organizations/projects/project-vision-status.md). - -::: moniker range="< azure-devops" -> [!NOTE] -> For on-premises Azure DevOps, all email actions require an [SMTP server to be configured](/azure/devops/server/admin/setup-customize-alerts). -::: moniker-end -::: moniker range="> azure-devops-2019" -1. Open the **Project>Summary** page, and choose **Invite**. - - :::image type="content" source="media/add-users/summary-invite-users.png" alt-text="Screenshot of Summary page, Invite button."::: -::: moniker-end -::: moniker range="tfs-2018" -1. Open the **Project>Summary** page, and choose the **Add** button. - :::image type="content" source="../projects/media/summary/invite-members-tfs-2018.png" alt-text="Screenshot of Summary page, Add members button."::: -::: moniker-end - -1. For new users, enter their email address. For existing users, type their name until it resolves as a known name to the system. You can add several email addresses or account names by separating them with a semicolon (;). - - :::row::: - :::column span=""::: - Choose the entry listed under **Add users** to complete the entry. - :::column-end::: - :::column span=""::: - If you're adding a user known by the organization or collection, type the name or email address and then choose the name that appears to complete the entry. - :::column-end::: - :::row-end::: - :::row::: - :::column span=""::: - :::image type="content" source="media/add-users/summary-page-invite-dialog-new-unknown-user.png" alt-text="Invite members to a project dialog, unknown user."::: - :::column-end::: - :::column span=""::: - :::image type="content" source="media/add-users/summary-invite-known-user.png" alt-text="Invite members to a project dialog, enter a known user account."::: - :::column-end::: - :::row-end::: - - > [!NOTE] - > Any valid email address is acceptable. When the user accepts the invitation and signs into Azure DevOps, they register their email address as a Microsoft account and choose a password. - -1. Optionally, select the teams you want to add the user to and then choose **Add** to complete the invitation. - - :::row::: - :::column span=""::: - When the user is unknown, you'll get a notification that an access level must be assigned. To complete the invitation, choose **Add**. - :::column-end::: - :::column span=""::: - Choose **Add** to complete the invitation. - :::column-end::: - :::row-end::: - :::row::: - :::column span=""::: - :::image type="content" source="media/add-users/summary-invite-dialog-new-user-selected-team.png" alt-text="Invite members to a project dialog, unknown user, select teams to add."::: - :::column-end::: - :::column span=""::: - :::image type="content" source="media/add-users/summary-page-invite-project-members.png" alt-text="Invite members to a project dialog, known user, select teams to add."::: - :::column-end::: - :::row-end::: - - When you add a new user, the system assigns Stakeholder as the access level when all free five Basic access levels have been assigned. Active contributors to a project need to have Basic access as a minimum. A Project Collection Administrator can change the access level from the [**Organization Settings>Users** page](#manage-users). - - > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). - -1. (Optional) A message will briefly display on the screen to indicate success or failure. Choose **Details** to open the notification and review details. - - :::row::: - :::column span=""::: - :::image type="content" source="media/add-users/notification-success.png" alt-text="Screenshot of notification success message. "::: - :::column-end::: - :::column span=""::: - :::image type="content" source="media/add-users/notification-failure.png" alt-text="Screenshot of notification failure message. "::: - :::column-end::: - :::row-end::: - :::row::: - :::column span=""::: - A success message indicates the status of adding the user to the system. - :::column-end::: - :::column span=""::: - A failure message indicates why the addition of the user failed. - :::column-end::: - :::row-end::: - :::row::: - :::column span=""::: - :::image type="content" source="media/add-users/summary-invite-notifications-success.png" alt-text="Notification dialog of Success. "::: "::: - :::column-end::: - :::column span=""::: - :::image type="content" source="media/add-users/notification-failure-outside-directory.png" alt-text="Notification dialog of failure. "::: - :::column-end::: - :::row-end::: - -1. New users receive an email inviting them to sign in to the project. Existing users don't receive any formal notification. - @@ -543,28 +344,26 @@ As a member of the Project Administrators group, you can add members to a projec As a member of the **Project Administrators** group, you can add users or groups to a project from the **Project settings> Permissions** page by adding them to a security group. To add a custom security group, see [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md). - ::: moniker range="azure-devops" > [!NOTE] > To enable the **Project Permissions Settings Page** preview page, see [Enable preview features](../../project/navigation/preview-features.md). ::: moniker-end - + #### [Preview UI](#tab/preview-page) - ::: moniker range="azure-devops" -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +1. Sign in to your project (`https://dev.azure.com/{Your_Organization/Your_Project}`). -2. Choose **Project settings**, and then **Permissions**. +2. Select **Project settings** > **Permissions**. ![Screenshot of project settings permissions.](media/permissions/project-settings-permissions.png) 3. Under **Groups**, choose one of the following options: - **Readers**: To add users who require read-only access to the project, choose. - - **Contributors**: To add users who contribute fully to this project or who have been granted Stakeholder access. + - **Contributors**: To add users who contribute fully to this project or have Stakeholder access. - **Project Administrators**: To add users who need to administrate the project. For more information, see [Change project-level permissions](change-project-level-permissions.md). Or, you can choose any team group to add users to a specific team. @@ -597,9 +396,7 @@ As a member of the **Project Administrators** group, you can add users or groups Choose **Save** when done. -7. You may customize user permissions for other functionality in the project. For example, in [areas and iterations](set-permissions-access-work-tracking.md) or [shared queries](../../boards/queries/set-query-permissions.md). - - +7. You might customize user permissions for other functionality in the project. For example, in [areas and iterations](set-permissions-access-work-tracking.md) or [shared queries](../../boards/queries/set-query-permissions.md). ::: moniker-end @@ -611,19 +408,17 @@ Choose the **Current page** tab for information on adding a user to a project. T #### [Current UI](#tab/current-page) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +1. Sign in to your project (`https://dev.azure.com/{Your_Organization/Your_Project}`). -2. Choose **Project Settings** and then **Security**. +2. Select **Project settings** > **Security**. - *To see the full image, select to expand*. - - [![Screenshot of Project Settings>Security.](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) + ![Screenshot of Project settings, Security.](media/view-permissions/open-security-project-level-vert.png) 3. Under **Groups**, choose one of the following options: - **Readers**: To add users who require read-only access to the project. - - **Contributors**: To add users who contribute fully to this project or who have been granted Stakeholder access. + - **Contributors**: To add users who contribute fully to this project or have Stakeholder access. - **Project Administrators**: To add users who need to administrate the project. For more information, see [Change project-level permissions](change-project-level-permissions.md). 4. Next, choose the **Members** tab. @@ -645,9 +440,7 @@ Choose the **Current page** tab for information on adding a user to a project. T ![Screenshot of Add users and group dialog, server version.](media/project-level-permissions-add-a-user.png) > [!NOTE] - > The first time you add a user or group to Azure DevOps, - > you can't browse to it or check the friendly name. - > After the identity has been added, you can just enter the friendly name. + > The first time you add a user or group to Azure DevOps, you can't browse to it or check the friendly name. After the identity has been added, you can just enter the friendly name. Choose **Save changes** when complete. @@ -658,83 +451,125 @@ Choose the **Current page** tab for information on adding a user to a project. T ::: moniker-end -::: moniker range="tfs-2018" +--- -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). + -2. Choose the :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: gear icon to open the administrative context. +## Invite users from the Summary page - ![Screenshot of Open Project Settings, horizontal nav.](../../media/settings/open-project-settings-horz.png) +As a member of the Project Administrators group, you can add members to a project from the [**Summary** page](../../organizations/projects/project-vision-status.md) and optionally add them to one or more teams. -3. Choose **Security** and under **Groups**, choose one of the following options: - - **Readers**: To add users who require read-only access to the project, choose. - - **Contributors**: To add users who contribute fully to this project or who have been granted Stakeholder access. - - **Project Administrators**: To add users who need to administrate the project. For more information, see [Change project-level permissions](change-project-level-permissions.md). +::: moniker range="< azure-devops" -4. Next, choose the **Members** tab. +> [!NOTE] +> For on-premises Azure DevOps, all email actions require an [SMTP server to be configured](/azure/devops/server/admin/setup-customize-alerts). +::: moniker-end - Here we choose the Contributors group. +::: moniker range="<=azure-devops" - > [!div class="mx-imgBorder"] - > ![Screenshot of Security page, Contributors group, Membership page.](media/add-users/add-members-to-contributors-group.png) +1. Open your **Project** > **Summary** page, and select **Invite**. - > [!TIP] - > Managing users is much easier [using groups](../../organizations/security/about-permissions.md), not individual users. + :::image type="content" source="media/add-users/summary-invite-users.png" alt-text="Screenshot of Summary page, Invite button."::: - By default, the default team group and any other teams you add to the project, are included as members of the **Contributors** group. Add a new user as a member of a team instead, and the user automatically inherits Contributor permissions. +::: moniker-end -5. Choose ![gear icon](../../media/icons/add-light-icon.png)**Add** to add a user or a user group. +2. For new users, enter their email address. For existing users, enter their name until it resolves as a known name to the system. You can add several email addresses or account names by separating them with a semicolon (;). -6. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. + :::row::: + :::column span=""::: + Choose the entry listed under **Add users** to complete the entry. + :::column-end::: + :::column span=""::: + If you're adding a user known by the organization or collection, enter the name or email address and then choose the name that appears to complete the entry. + :::column-end::: + :::row-end::: + :::row::: + :::column span=""::: + :::image type="content" source="media/add-users/summary-page-invite-dialog-new-unknown-user.png" alt-text="Screenshot of the Invite members to a project dialog, showing unknown user."::: + :::column-end::: + :::column span=""::: + :::image type="content" source="media/add-users/summary-invite-known-user.png" alt-text="Screenshot of the Invite members to a project dialog, entering a known user account."::: + :::column-end::: + :::row-end::: - ![Screenshot of Add users and group dialog.](media/project-level-permissions-add-a-user.png) + > [!NOTE] + > Any valid email address is acceptable. When the user accepts the invitation and signs into Azure DevOps, they register their email address as a Microsoft account and choose a password. - > [!NOTE] - > The first time you add a user or group to Azure DevOps, - > you can't browse to it or check the friendly name. - > After the identity has been added, you can just enter the friendly name. +2. Optionally, select the teams you want to add the user to and then choose **Add** to complete the invitation. -7. (Optional) You can customize user permissions for other functionality within the project, such as [areas and iterations](set-permissions-access-work-tracking.md) or [shared queries](../../boards/queries/set-query-permissions.md). + :::row::: + :::column span=""::: + When the user is unknown, a notification alerts that an access level must be assigned. To complete the invitation, choose **Add**. + :::column-end::: + :::column span=""::: + Choose **Add** to complete the invitation. + :::column-end::: + :::row-end::: + :::row::: + :::column span=""::: + :::image type="content" source="media/add-users/summary-invite-dialog-new-user-selected-team.png" alt-text="Screenshot of the Invite members to a project dialog, unknown user, selecting teams to add."::: + :::column-end::: + :::column span=""::: + :::image type="content" source="media/add-users/summary-page-invite-project-members.png" alt-text="Screenshot of the Invite members to a project dialog, known user, selecting teams to add."::: + :::column-end::: + :::row-end::: - > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). + When you add a new user, the system assigns Stakeholder as the access level when all free five Basic access levels get assigned. Active contributors to a project need to have Basic access as a minimum. A Project Collection Administrator can change the access level from the [**Organization settings** > **Users** page](#manage-users). -::: moniker-end + > [!NOTE] + > Users with limited access, such as Stakeholders, can't access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). + +3. (Optional) A message briefly displays on the screen to indicate success or failure. Select **Details** to open the notification and review details. ---- + :::row::: + :::column span=""::: + :::image type="content" source="media/add-users/notification-success.png" alt-text="Screenshot of notification success message. "::: + :::column-end::: + :::column span=""::: + :::image type="content" source="media/add-users/notification-failure.png" alt-text="Screenshot of notification failure message. "::: + :::column-end::: + :::row-end::: + :::row::: + :::column span=""::: + A success message indicates the status of adding the user to the system. + :::column-end::: + :::column span=""::: + A failure message indicates why the addition of the user failed. + :::column-end::: + :::row-end::: + :::row::: + :::column span=""::: + :::image type="content" source="media/add-users/summary-invite-notifications-success.png" alt-text="Screenshot of the Notification dialog of Success."::: "::: + :::column-end::: + :::column span=""::: + :::image type="content" source="media/add-users/notification-failure-outside-directory.png" alt-text="Screenshot of the Notification dialog of failure."::: + :::column-end::: + :::row-end::: + +4. New users receive an email inviting them to sign in to the project. Existing users don't receive any formal notification. ::: moniker range="azure-devops" - + ## Manage users or resend invitations -Project Collection Administrators can update user assignments and resend invitations. The various options they have are: -- Change the access level -- Manage user - add them to select projects -- Resend invite -- Remove direct assignments -- Remove from organization +Project Collection Administrators can update user assignments and resend invitations. For more information, see [Add account users for Azure DevOps](../accounts/add-organization-users.md). -For more information, see [Add account users for Azure DevOps](../accounts/add-organization-users.md). - -:::image type="content" source="media/add-users/users-page-manage-options.png" alt-text="Screenshot of Organization Settings>Users page, Manage user options. "::: +:::image type="content" source="media/add-users/users-page-manage-options.png" alt-text="Screenshot of More options to manage users."::: ::: moniker-end - ::: moniker range="azure-devops" ## List team members or team details From the Azure DevOps CLI command, you can see details about a team or list the individual members of that team. To first see a list of all teams in your organization, use the [az devops team list](/cli/azure/devops/team#az-devops-team-list) command. -[List team members](#list-members) | [Show team details](#show-details) +[List team members](#list-team-members) | [Show team details](#show-details) > [!NOTE] -> You can use the [`az devops user`](../accounts/add-organization-users.md#add-users-to-your-organization) command to add users to an organization. There is no comparable command for adding users to a team or project. - - +> You can use the [`az devops user`](../accounts/add-organization-users.md#add-users-to-your-organization) command to add users to an organization. There is no comparable command for adding users to a team or project. ### List team members @@ -772,7 +607,7 @@ d291b0c4-a05c-4ea6-8df1-4b41d5f39eff Jamal Hartnett fabrikamfiber4@hotmail. bd30c189-db0f-4dd6-9418-5d8b41dc1754 Raisa Pokrovskaya fabrikamfiber5@hotmail.com ``` - + ### Show team details @@ -803,13 +638,12 @@ a48cb46f-7366-4f4b-baf5-b3632398ed1e Fabrikam Team The default project team. W ``` ::: moniker-end - ::: moniker range="< azure-devops" ## Add users or groups to an access level -For on-premises deployments, you may need to set the access level for a user or group, particularly if those groups don't belong to the default access level. For more information, see [Change access levels](change-access-levels.md). +For on-premises deployments, you might need to set the access level for a user or group, particularly if those groups don't belong to the default access level. For more information, see [Change access levels](change-access-levels.md). ::: moniker-end @@ -817,11 +651,10 @@ For on-premises deployments, you may need to set the access level for a user or ## Add users or groups to SQL Server Reports -If your on-premises deployment is integrated with SQL Server Reports, you need to manage membership for those products separately from their websites. See [Grant permissions to view or create SQL Server reports in Azure DevOps](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports). +If your on-premises deployment is integrated with SQL Server Reports, you must manage membership for those products separately from their websites. See [Grant permissions to view or create SQL Server reports in Azure DevOps](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports). ::: moniker-end - ## Next steps > [!div class="nextstepaction"] @@ -833,16 +666,10 @@ If your on-premises deployment is integrated with SQL Server Reports, you need t * [Add users and manage access](../accounts/add-organization-users.md) * [Resources granted to project members](../projects/resources-granted-to-project-members.md) -* [Manage your organization, Limit identity search and selection](../../user-guide/manage-organization-collection.md#limit-identity-selection) -* [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group) * [Manage permissions with command line tool](manage-tokens-namespaces.md) -* [Grant or restrict access using permissions](restrict-access.md). +* [Change project visibility to public or private](../projects/make-project-public.md) ::: moniker-end - ::: moniker range="< azure-devops" * [Resources granted to project members](../projects/resources-granted-to-project-members.md) -* [Grant or restrict access using permissions](restrict-access.md). ::: moniker-end - - diff --git a/docs/organizations/security/allow-list-ip-url.md b/docs/organizations/security/allow-list-ip-url.md index a0e2fab0ab5..5637754f30a 100644 --- a/docs/organizations/security/allow-list-ip-url.md +++ b/docs/organizations/security/allow-list-ip-url.md @@ -1,42 +1,43 @@ --- -title: Allowed address lists and network connections +title: Allowed address lists and network connections titleSuffix: Azure DevOps -description: Add IP addresses and domain URLs to the allowlist for Azure DevOps and troubleshoot network connections. +description: Add IP addresses and domain URLs to the allowlist for Azure DevOps and troubleshoot network connections. ms.topic: reference -ms.custom: contperf-fy21q4 ms.subservice: azure-devops-security ms.reviewer: jominana ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 03/27/2023 +ms.date: 04/02/2025 --- # Allowed IP addresses and domain URLs [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -If your organization's secured with a firewall or proxy server, you must add certain internet protocol (IP) addresses and domain uniform resource locators (URLs) to the **allowlist**. Adding these IPs and URLs to the allowlist helps to ensure that you have the best experience with Azure DevOps. You know that you need to update your allowlist if you can't access Azure DevOps on your network. See the following sections in this article: +If your organization is secured with a firewall or proxy server, you must add certain internet protocol (IP) addresses and domain uniform resource locators (URLs) to the **allowlist**. Adding these IPs and URLs to the allowlist helps to ensure that you have the best experience with Azure DevOps. You know that you need to update your allowlist if you can't access Azure DevOps on your network. See the following sections in this article: - [Allowed domain URLs](#allowed-domain-urls) - [IP addresses and range restrictions](#ip-addresses-and-range-restrictions) > [!TIP] -> So that Visual Studio and Azure Services work well with no network issues, you should open select ports and protocols. For more information, see [Install and use Visual Studio behind a firewall or proxy server, Use Visual Studio and Azure Services](/visualstudio/install/install-and-use-visual-studio-behind-a-firewall-or-proxy-server#use-visual-studio-and-azure-services). +> So that Visual Studio and Azure Services work well with no network issues, open select ports and protocols. For more information, see [Install and use Visual Studio behind a firewall or proxy server, Use Visual Studio and Azure Services](/visualstudio/install/install-and-use-visual-studio-behind-a-firewall-or-proxy-server#use-visual-studio-and-azure-services). - + ## IP addresses and range restrictions +::: moniker range="azure-devops" + ### Outbound connections -_Outbound connections_ originate from inside your organization and that target Azure DevOps or other dependent sites. Examples of such connections include: +_Outbound connections_ target other dependent sites. Examples of such connections include: - Browsers connecting to Azure DevOps website as users go to and use features of Azure DevOps - Azure Pipelines agents installed on your organization's network connecting to Azure DevOps to poll for pending jobs -- CI events sent from a source code repository that's hosted within your organization's network to Azure DevOps +- CI events sent from a source code repository hosted within your organization's network to Azure DevOps -Ensure the following IP addresses are allowed for outbound connection, so your organization works with any existing firewall or IP restrictions. The endpoint data in the following chart lists requirements for connectivity from a machine in your organization to Azure DevOps Services. +Ensure the following IP addresses are allowed for outbound connections, so your organization works with any existing firewall or IP restrictions. The endpoint data in the following chart lists requirements for connectivity from a machine in your organization to Azure DevOps Services. #### [IP V4 ranges](#tab/IP-V4) @@ -46,6 +47,12 @@ Ensure the following IP addresses are allowed for outbound connection, so your o 13.107.9.0/24 13.107.42.0/24 13.107.43.0/24 +150.171.22.0/24 +150.171.23.0/24 +150.171.73.0/24 +150.171.74.0/24 +150.171.75.0/24 +150.171.76.0/24 ``` #### [IP V6 ranges](#tab/IP-V6) @@ -56,6 +63,9 @@ Ensure the following IP addresses are allowed for outbound connection, so your o 2620:1ec:a92::/48 2620:1ec:21::/48 2620:1ec:22::/48 +2620:1ec:50::/48 +2620:1ec:51::/48 +2603:1061:10::/48 ``` --- @@ -63,7 +73,9 @@ Ensure the following IP addresses are allowed for outbound connection, so your o If you're currently allowing the `13.107.6.183` and `13.107.9.183` IP addresses, leave them in place, as you don't need to remove them. > [!NOTE] -> [Azure Service Tags](/azure/virtual-network/service-tags-overview) aren't supported for *outbound* connection. +> [Azure Service Tags](/azure/virtual-network/service-tags-overview) aren't supported for *outbound* connections. + +::: moniker-end ### Inbound connections @@ -74,32 +86,35 @@ _Inbound connections_ originate from Azure DevOps and target resources within yo - Azure Pipelines connecting to on-premises source code repositories such as [GitHub Enterprise](../../pipelines/repos/github-enterprise.md) or [Bitbucket Server](../../pipelines/repos/on-premises-bitbucket.md) - Azure DevOps Services [Audit Streaming](../audit/auditing-streaming.md) connecting to on-premises or cloud-based Splunk -Ensure the following IP addresses are allowed for inbound connection, so your organization works with any existing firewall or IP restrictions. The endpoint data in the following chart lists requirements for connectivity from Azure DevOps Services to your on-premises or other cloud services. +Ensure the following IP addresses are allowed for inbound connections, so your organization works with any existing firewall or IP restrictions. The endpoint data in the following chart lists requirements for connectivity from Azure DevOps Services to your on-premises or other cloud services. > [!div class="mx-tdCol2BreakAll"] -> |  Region  | IP V4 ranges | -> |------|---------| -> | Australia East | 20.37.194.0/24 | -> | Australia South East | 20.42.226.0/24 | -> | Brazil South | 191.235.226.0/24 | -> | Central Canada | 52.228.82.0/24 | -> | Asia Pacific (Singapore) | 20.195.68.0/24 | -> | South India | 20.41.194.0/24 | -> | Central United States | 20.37.158.0/23 | -> | West Central United States | 52.150.138.0/24 | -> | East United States | 20.42.5.0/24 | -> | East 2 United States | 20.41.6.0/23 | -> | North United States | 40.80.187.0/24 | -> | South United States | 40.119.10.0/24 | -> | West United States | 40.82.252.0/24 | -> | West 2 United States | 20.42.134.0/23 | -> | Western Europe | 40.74.28.0/23 | -> | United Kingdom South | 51.104.26.0/24 | - -Azure Service Tags are supported for *inbound* connection. Instead of allowing the previously listed IP ranges, you may use the **AzureDevOps** service tag for Azure Firewall and Network Security Group (NSG) or on-premises firewall via a JSON file download. +> |  Geography | Region  | IP V4 ranges | +> |------|------|---------| +> | Australia | Australia East | 20.37.194.0/24 | +> | | Australia South East | 20.42.226.0/24 | +> | Brazil | Brazil South | 191.235.226.0/24 | +> | Canada | Central Canada | 52.228.82.0/24 | +> | Asia Pacific | Southeast Asia (Singapore) | 20.195.68.0/24 | +> | India | South India | 20.41.194.0/24 | +> | | Central India | 20.204.197.192/26 | +> | United States | Central United States | 20.37.158.0/23 | +> | | West Central United States | 52.150.138.0/24 | +> | | East United States | 20.42.5.0/24 | +> | | East 2 United States | 20.41.6.0/23 | +> | | North United States | 40.80.187.0/24 | +> | | South United States | 40.119.10.0/24 | +> | | West United States | 40.82.252.0/24 | +> | | West 2 United States | 20.42.134.0/23 | +> | | West 3 United States | 20.125.155.0/24 | +> | Europe | Western Europe | 40.74.28.0/23 | +> | | North Europe | 20.166.41.0/24 | +> | United Kingdom | United Kingdom South | 51.104.26.0/24 | + +Azure Service Tags are supported only for *inbound* connections. Instead of allowing the previously listed IP ranges, you may use the **AzureDevOps** service tag for Azure Firewall and Network Security Group (NSG) or on-premises firewall via a JSON file download. > [!NOTE] -> The Service Tag or previously mentioned inbound IP addresses don't apply to Microsoft Hosted agents. Customers are still required to allow the [entire geography for the Microsoft Hosted agents](../../pipelines/agents/hosted.md#agent-ip-ranges). If allowing the entire geography is a concern, we recommend using the [Azure Virtual Machine Scale Set agents](../../pipelines/agents/scale-set-agents.md). The Scale Set agents are a form of self-hosted agents that can be auto-scaled to meet your demands. +> The Service Tag or previously mentioned inbound IP addresses don't apply to Microsoft Hosted agents. Customers are still required to allow the [entire geography for the Microsoft Hosted agents](../../pipelines/agents/hosted.md#agent-ip-ranges). If allowing the entire geography is a concern, we recommend using the [Microsoft Managed DevOps Pools](../../managed-devops-pools/overview.md). Alternatively, you can also use [Azure Virtual Machine Scale Set agents](../../pipelines/agents/scale-set-agents.md). Managed DevOps Pools and Scale Set agents are a form of self-hosted agents that can be auto-scaled to meet your demands. Hosted macOS agents are hosted in GitHub's macOS cloud. IP ranges can be retrieved using the [GitHub metadata API](https://docs.github.com/en/rest/reference/meta#get-github-meta-information) using the instructions provided [here](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#ip-addresses). ### Other IP addresses @@ -140,6 +155,24 @@ If your organization uses ExpressRoute, ensure the following IP addresses are al 13.107.43.18/32 13.107.43.19/32 13.107.43.20/32 +150.171.73.14/32 +150.171.73.15/32 +150.171.73.16/32 +150.171.74.14/32 +150.171.74.15/32 +150.171.74.16/32 +150.171.75.14/32 +150.171.75.15/32 +150.171.75.16/32 +150.171.76.14/32 +150.171.76.15/32 +150.171.76.16/32 +150.171.22.17/32 +150.171.22.18/32 +150.171.22.19/32 +150.171.23.17/32 +150.171.23.18/32 +150.171.23.19/32 ``` #### [IP V6 ranges](#tab/IP-V6) @@ -157,6 +190,24 @@ If your organization uses ExpressRoute, ensure the following IP addresses are al 2620:1ec:22::18/128 2620:1ec:22::19/128 2620:1ec:22::20/128 +2603:1061:10::14/128 +2603:1061:10::15/128 +2603:1061:10::16/128 +2603:1061:10:1::14/128 +2603:1061:10:1::15/128 +2603:1061:10:1::16/128 +2603:1061:10:2::14/128 +2603:1061:10:2::15/128 +2603:1061:10:2::16/128 +2603:1061:10:3::14/128 +2603:1061:10:3::15/128 +2603:1061:10:3::16/128 +2620:1ec:50::17/128 +2620:1ec:50::18/128 +2620:1ec:50::19/128 +2620:1ec:51::17/128 +2620:1ec:51::18/128 +2620:1ec:51::19/128 ``` --- @@ -195,7 +246,6 @@ https://microsoftonline.com https://static2.sharepointonline.com https://visualstudio.com https://vsrm.dev.azure.com -https://vstsagentpackage.azureedge.net https://*.windows.net https://{organization_name}.visualstudio.com https://{organization_name}.vsrm.visualstudio.com @@ -203,6 +253,10 @@ https://{organization_name}.vstmr.visualstudio.com https://{organization_name}.pkgs.visualstudio.com https://{organization_name}.vssps.visualstudio.com +Azure DevOps uses the following URLs to provide the agent software for download for self-hosted agents. +https://vstsagentpackage.azureedge.net +https://download.agent.dev.azure.com + Azure DevOps uses content delivery network (CDN) to serve static content. The following URLs are part of that. https://cdn.vsassets.io https://*.vsassets.io @@ -214,8 +268,8 @@ https://azurecomcdn.azureedge.net ``` The following endpoints are used to authenticate Azure DevOps organizations using a Microsoft Account (MSA). -These are only needed for Azure DevOps organizations backed by Microsoft Accounts (MSA). -Azure DevOps organizations backed an Azure Active Directory tenant does not need the following URLs. +These endpoints are only needed for Azure DevOps organizations backed by Microsoft Accounts (MSA). +Azure DevOps organizations backed a Microsoft Entra tenant doesn't need the following URLs. ``` https://live.com @@ -240,14 +294,13 @@ We recommend you open port `443` to all traffic on the following IP addresses an |More domain URLs |Descriptions | |---------|---------| |https://login.microsoftonline.com |Authentication and sign-in related | -|https://app.vssps.visualstudio.com | Authentication and sign-in related | |https://*.vssps.visualstudio.com |Authentication and sign-in related | |https://*gallerycdn.vsassets.io |Hosts Azure DevOps extensions | |https://*vstmrblob.vsassets.io | Hosts Azure DevOps TCM log data | |https://cdn.vsassets.io | Hosts Azure DevOps Content Delivery Networks (CDNs) content | |https://static2.sharepointonline.com | Hosts some resources that Azure DevOps uses in "office fabric" UI kit for fonts, and so on | |https://vsrm.dev.azure.com | Hosts releases | -|https://vstsagentpackage.azureedge.net | Required to set up self-hosted agent in machines within your network | +|https://vstsagentpackage.azureedge.net
      https://download.agent.dev.azure.com | Required to set up self-hosted agent in machines within your network | |https://amp.azure.net | Needed for deploying to Azure app service | |https://go.microsoft.com | Accesses go links | @@ -258,6 +311,7 @@ Ensure the following domain URLs are allowed for Azure Artifacts: ```AzureArtifactsDomainURLs https://*.blob.core.windows.net https://*.visualstudio.com +https://*.dedup.microsoft.com ``` Also allow all IP addresses in the "name": "Storage.{region}" section of the following file (updated weekly): [Azure IP ranges and Service Tags - Public Cloud](https://www.microsoft.com/download/details.aspx?id=56519). {region} is the same Azure Geography as your organization. @@ -267,8 +321,8 @@ Also allow all IP addresses in the "name": "Storage.{region}" section of the fol Ensure the following domain URLs are allowed for NuGet connections: ``` NuGetDomainURLs -https://azurewebsites.net -https://nuget.org +https://*.azurewebsites.net +https://*.nuget.org ``` > [!NOTE] @@ -288,18 +342,31 @@ Also allow IP addresses in the "name": "AzureDevOps" section of [this downloadab ### Azure Pipelines Microsoft-hosted agents -If you use Microsoft-hosted agent to run your jobs and you need the information about what IP addresses are used, see [Microsoft-hosted agents IP ranges](../../pipelines/agents/hosted.md#agent-ip-ranges). See all [Azure Virtual Machine Scale Set agents](../../pipelines/agents/scale-set-agents.md?preserve-view=true&view=azure-devops). +If you use Microsoft-hosted agent to run your jobs and you need the information about what IP addresses are used, see [Microsoft-hosted agents IP ranges](../../pipelines/agents/hosted.md#agent-ip-ranges). See all [Microsoft Managed DevOps Pools](../../managed-devops-pools/overview.md) and [Azure Virtual Machine Scale Set agents](../../pipelines/agents/scale-set-agents.md?preserve-view=true&view=azure-devops). -For more information about hosted Windows, Linux and macOS agents, see [Microsoft-hosted agent IP ranges](../../pipelines/agents/hosted.md#agent-ip-ranges). +For more information about hosted Windows, Linux, and macOS agents, see [Microsoft-hosted agent IP ranges](../../pipelines/agents/hosted.md#agent-ip-ranges). + +### Azure Pipelines self-hosted agents -### Azure Pipelines Self-hosted agents If you're running a firewall and your code is in Azure Repos, see [Self-hosted Linux agents FAQs](../../pipelines/agents/linux-agent.md#im-running-a-firewall-and-my-code-is-in-azure-repos-what-urls-does-the-agent-need-to-communicate-with), [Self-hosted macOS agents FAQs](../../pipelines/agents/osx-agent.md#im-running-a-firewall-and-my-code-is-in-azure-repos-what-urls-does-the-agent-need-to-communicate-with) or [Self-hosted Windows agents FAQs](../../pipelines/agents/windows-agent.md#im-running-a-firewall-and-my-code-is-in-azure-repos-what-urls-does-the-agent-need-to-communicate-with). This article has information about which domain URLs and IP addresses your private agent needs to communicate with. +> [!IMPORTANT] +> [Edgio CDN for Azure DevOps is being retired](https://devblogs.microsoft.com/devops/important-switching-cdn-providers/), which requires a new domain URL to be allow-listed in firewall rules for agent software download. +> The new domain to allow-list for agent download is `https://*.dev.azure.com`. If your firewall rules don't allow wildcards, use `https://download.agent.dev.azure.com`. +> +> The Azure DevOps team recommends to make this change by the following date: +> - May 1, 2025 for Azure DevOps Services +> - May 15, 2025 for Azure DevOps Server +> +> For more information, see [CDN Domain URL change for Agents in Pipelines](https://devblogs.microsoft.com/devops/cdn-domain-url-change-for-agents-in-pipelines/). ## Azure DevOps import service During the import process, we highly recommend that you restrict access to your virtual machine (VM) to only IP addresses from Azure DevOps. To restrict access, allow only connections from the set of Azure DevOps IP addresses, which were involved in the collection database import process. For information about identifying the correct IP addresses, see [(Optional) Restrict access to Azure DevOps Services IPs only](../../migrate/migration-import-large-collections.md#ips). +> [!NOTE] +> Azure DevOps doesn't natively support allowlisting directly within its settings. However, you can manage allowlisting at the network level using your organization's firewall or proxy settings. + ## Related articles - [Available service tags](/azure/virtual-network/service-tags-overview) diff --git a/docs/organizations/security/change-access-levels.md b/docs/organizations/security/change-access-levels.md index 358d2c6f2b2..8e81258d120 100644 --- a/docs/organizations/security/change-access-levels.md +++ b/docs/organizations/security/change-access-levels.md @@ -1,173 +1,97 @@ --- -title: Add users or groups to an access level +title: Change access levels titleSuffix: Azure DevOps -description: Learn how to set the access level for a user or group based on their license +description: Learn how to set the access level for a user or group based on their license. ms.subservice: azure-devops-security ms.assetid: 84B0D454-09A7-414B-A9E0-FE9A9ACD7E99 -ms.topic: quickstart +ms.topic: how-to ms.reviewer: ms.author: chcomley author: chcomley -monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +monikerRange: '< azure-devops' +ms.date: 09/28/2023 --- -# Add users or groups to an access level +# Change access levels -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-lt-azure-devops](../../includes/version-lt-azure-devops.md)] -Users must be added to a group with the appropriate permissions, to connect and use the functions and features that Azure DevOps Server provides. To use select web portal features, they must also belong to the access level that enables access to that feature. For an overview of each access level, see [About access levels](access-levels.md). +> [!NOTE] +> This article applies to Azure DevOps Server (on-premises). To manage access levels for Azure DevOps Services (cloud), see [Add users to your organization or project](../accounts/add-organization-users.md). -This article applies to managing access levels for project collections defined on an on-premises Azure DevOps. To manage access levels for the Azure DevOps Services (the cloud service), see [Add users to your organization or project](../accounts/add-organization-users.md). - -> [!IMPORTANT] -> Make sure that you select the correct version of this article for Azure DevOps Services or Azure DevOps Server, renamed from Team Foundation Server (TFS). The version selector is located above the table of contents.
      -> ![Content version selector](../../media/version-selector.png) +Access levels manage access to use the functions and features that Azure DevOps Server provides. Access levels are in addition to permissions granted through security groups, which provide or restrict specific tasks. In this article, learn how to change access levels for users and groups. For more information, see [About access levels](access-levels.md). For a simplified overview of the permissions that are assigned to the most common groups—Readers, Contributors, and Project Administrators—and the Stakeholder access group, see [Permissions and access](permissions-access.md). -::: moniker range="< azure-devops" - -> [!NOTE] -> Even if you set a user or group's access level, you must [add them to a project](add-users-team-project.md) for them to connect to a project and access features available through a supported client or the web portal. - -Make sure to set each user's access level based on what you've purchased for that user. Basic access includes all Stakeholder features - Basic + Test Plans, Advanced and Visual Studio Enterprise subscriber access levels include all Basic features. In the images provided below, the circled features indicate the features made available from the previous access level. - - +[!INCLUDE [version-selector](../../includes/version-selector.md)] ## Prerequisites -* You must be a member of the Administrators group. If you aren't a member, [get added now](/azure/devops/server/admin/add-administrator). -* If you're managing access for a large group of users, it's a best practice to first create either a [Windows group, a group in Active Directory, or Azure DevOps security group](/azure/devops/server/admin/setup-ad-groups), and then add individuals to those groups. - -::: moniker-end - -::: moniker range="< azure-devops" +| Category | Requirements | +|-------------|-------------| +| **Permissions** | Member of the [**Project Administrators** group](change-project-level-permissions.md). | +| **Group membership** | To manage access for a large group of users: Create either a [Windows, Active Directory, or Azure DevOps security group](/azure/devops/server/admin/setup-ad-groups), and then add users to those groups. | +| **Project access** | Ensure users are [members of the project](add-users-team-project.md). | ## Open access levels -You manage access levels for the collections defined on the application tier. The default access level you set applies to all projects defined for all collections. Users or groups that you add to teams, projects, or collections are granted the access level that you set as the default. To change the access level for a specific group or user, add them specifically to a non-default access level. - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - -- From the web portal home page for a project collection (for example, `http://MyServer:8080/tfs/DefaultCollection/`), open **Access levels**. If you are at a project level, choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo and then choose **Access levels**. +You can manage access levels for the collections defined on the application tier. The default access level affects all the projects in all the collections. When you add users or groups to teams, projects, or collections, they get the default access level. To give a different access level to a certain user or group, you need to add them to a non-default access level. - > [!div class="mx-imgBorder"] - > ![web portal, Open Access levels dialog](media/change-access-levels/open-access-levels-2019.png) +- From the web portal home page for a project collection (for example, `http://MyServer:8080/tfs/DefaultCollection/`), open **Access levels**. If you're at a project level, choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo and then choose **Access levels**. - If you don't see **Access levels**, you aren't an administrator and don't have permission. [Here's how to get permissions](/azure/devops/server/admin/add-administrator). + ![Screenshot of web portal, Open Access levels dialog.](media/change-access-levels/open-access-levels-2019.png) -::: moniker-end - -::: moniker range="tfs-2018" - -From a user context, open **Server Settings** by choosing the :::image type="icon" source="../../boards/media/icons/gear_icon.png" border="false"::: gear icon. The tabs and pages available differ depending on which settings level you access. - -- From the web portal home page for a project (for example, `http://MyServer:8080/tfs/DefaultCollection/MyProject/`), open **Server settings**. - - TFS 2017, Web portal, open the Server settings admin context - -::: moniker-end - - - - -::: moniker range="< azure-devops" + If you don't see **Access levels**, you aren't an administrator and need to [get permission](/azure/devops/server/admin/add-administrator). ## Add a user or group to an access level -Changes you make to the access level settings take affect immediately. You can add or change the access level for a user or group through this interface. - -::: moniker-end +Changes you make to the access level settings take effect immediately. -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="<=azure-devops" 1. Select the access level you want to manage. For example, here we choose **Basic**, and then **Add** to add a group to Basic access. - > [!div class="mx-imgBorder"] - > ![Basic access level, add group](media/change-access-levels/basic-access-2019.png) + ![Screenshot of Basic access level, adding group.](media/change-access-levels/basic-access-2019.png) 1. Enter the name of the user or group into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the matches that meet your choice. - > [!div class="mx-imgBorder"] - > ![Add users and group dialog](media/project-level-permissions-add-a-user.png) + ![Screenshot of Add users and group dialog.](media/project-level-permissions-add-a-user.png) -1. Choose **Save changes**. +2. Choose **Save changes**. ::: moniker-end -::: moniker range="tfs-2018" - -1. From **Access levels**, select the access level you want to manage. For example, here we choose **Stakeholder**, and then **Add** to add a group to Stakeholder access. - - TFS 2017, Web portal, Server settings admin context, Access levels, Stakeholder access level, Add user or group - - If you don't see **Access levels**, you aren't a TFS administrator and don't have permission. [Here's how to get permissions](/azure/devops/server/admin/add-administrator). - -2. Enter the name of the user or group into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the matches that meet your choice. - - > [!div class="mx-imgBorder"] - > ![Add users and group dialog](media/project-level-permissions-add-a-user.png) - -3. Choose **Save changes**. - -::: moniker-end - -::: moniker range="< azure-devops" - ## Change the access level for a user or group -To change the access level for a user or group, first remove them from their existing access level, and then add them to the access level you want them to have. - -1. Choose the user or group and then select **Remove**. +To assign a different access level to a user or group, you need to first delete their current access level and then grant them the new one. - > [!div class="mx-imgBorder"] - > ![Collection level permissions and groups](media/change-access-levels/remove-user-from-access-level.png) - -2. Add the user or group to the other access level following the steps provided in the [previous section](#add). - -::: moniker-end +Make sure to set each user's access level based on what you've purchased for that user. Basic access includes all Stakeholder features - Basic + Test Plans. Advanced and Visual Studio Enterprise subscriber access levels include all Basic features. +1. Choose the user or group and then select **Remove**. - + ![Screenshot of Collection level permissions and groups page.](media/change-access-levels/remove-user-from-access-level.png) -::: moniker range="< azure-devops" +2. Add the user or group to the other access level following the steps provided in the [previous section](#add-a-user-or-group-to-an-access-level). ## Change the default access level -Change the default access level to match the access you have licenses for. If you change the default access level to Stakeholder, all users not explicitly added to the Basic or an advanced level are limited to the features provided through Stakeholder access. +Make sure the default access level is the same as the access you're licensed for. When you set the default access level to Stakeholder, only the users who are given the Basic or a higher level can access more features than the Stakeholder level. -You set an access level from its page. Choose **Set as default access level** as shown. +You can set an access level from its page. Choose **Set as default access level** as shown. -::: moniker-end +::: moniker range="<=azure-devops" -::: moniker range=">= azure-devops-2019 < azure-devops" -> [!div class="mx-imgBorder"] -> ![Stakeholder access level, set as default](media/change-access-levels/set-stakeholder-as-default-2019.png) +![Screenshot of Stakeholder access level, set as default.](media/change-access-levels/set-stakeholder-as-default-2019.png) ::: moniker-end -::: moniker range="tfs-2018" -Admin context, Control panel, Access levels, Stakeholder tab, set as default access level -::: moniker-end - -::: moniker range="< azure-devops" > [!IMPORTANT] -> Service accounts are added to the default access level. If you set Stakeholder as the default access level, you must add the Azure DevOps service accounts to the Basic or an advanced access level group. -::: moniker-end - - - -## Guide to features and access levels - -For details on the features available to each access level, see [About access levels](access-levels.md). +> Service accounts get added to the default access level. If you set Stakeholder as the default access level, you must add the Azure DevOps service accounts to the Basic or an advanced access level group. ## Related articles - [About access levels](access-levels.md) - [Export a list of users and their access levels](export-users-audit-log.md) - [Default permissions and access](permissions-access.md) -- [Web portal navigation](../../project/navigation/index.md) \ No newline at end of file +- [Web portal navigation](../../project/navigation/index.md) diff --git a/docs/organizations/security/change-organization-collection-level-permissions.md b/docs/organizations/security/change-organization-collection-level-permissions.md index c0b72c77deb..829fce91458 100644 --- a/docs/organizations/security/change-organization-collection-level-permissions.md +++ b/docs/organizations/security/change-organization-collection-level-permissions.md @@ -8,7 +8,8 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ai-usage: ai-assisted +ms.date: 08/19/2024 --- @@ -16,206 +17,166 @@ ms.date: 04/04/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Several permissions are set at the organization or collection level. You can grant these permissions by adding a user or group to the **Project Collection Administrators** group. Or, you can grant select collection-level permissions to a custom security group or to a user. +This article shows you how to manage permissions at the organization or collection level. Several permissions are set at these levels. You can only grant these permissions if you're a member of the **Project Collection Administrators** group. ::: moniker range="azure-devops" -An organization is the container for several projects that share resources. For more information about projects and project collections, see [Plan your organizational structure](../../user-guide/plan-your-azure-devops-org-structure.md). +An organization is the container for several projects that share resources. For more information, see [Plan your organizational structure](../../user-guide/plan-your-azure-devops-org-structure.md). ::: moniker-end ::: moniker range="< azure-devops" -A project collection is the container for several projects that share resources. For more information about projects and project collections, see [About projects and scaling your organization](../../organizations/projects/about-projects.md). +A project collection is the container for several projects that share resources. For more information, see [About projects and scaling your organization](../../organizations/projects/about-projects.md). ::: moniker-end +You might find the following articles helpful: -See the following articles for related information: - +- [Look up a project collection administrator](look-up-project-collection-administrators.md) +- [Manage users, groups, and security groups](add-remove-manage-user-group-security-group.md) - [Request an increase in permission levels](request-changes-permissions.md) - [Change project-level permissions](change-project-level-permissions.md) -- [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md) - [Set object-level permissions](set-object-level-permissions.md) -- [Look up a project collection administrator](look-up-project-collection-administrators.md) -- [Look up the organization owner](look-up-organization-owner.md) [!INCLUDE [hidden-security-groups](./includes/hidden-security-groups.md)] - ## Collection-level permissions [!INCLUDE [collection-level-permissions](./includes/collection-level-permissions.md)] > [!NOTE] -> The permission to add or remove organization or collection-level security groups, add and manage organization or collection-level group membership, and edit collection and project-level permission ACLs is assigned to all members of the **Project Collection Administrator**s group. It isn't controlled by a permissions surfaced within the user interface. - +> **Project Collection Administrators** can manage organization or collection-level security groups, group membership, and edit permission ACLs. This permission isn't controlled through the user interface. ## Prerequisites -- To manage permissions or groups at the organization or collection level, you must be a member of the **Project Collection Administrators** security group. If you created the organization or collection, you are automatically added as a member of this group. To get added to this group, you need to request permissions from a member of the **Project Collection Administrators** group. See [Look up a project collection administrator](look-up-project-collection-administrators.md). -- If want to add security groups defined in Azure Active Directory or Active Directory, make sure those are first defined. To learn more, see [Add AD/Azure AD users or groups to a built-in security group](add-ad-aad-built-in-security-groups.md). +|Category | Requirements | +|-------------|-------------| +| **Permissions** | Member of the [**Project Collection Administrators** group](look-up-project-collection-administrators.md). If you created the organization or collection, you're automatically a member of this group. | +| **Directory services** | [Security groups defined in Microsoft Entra ID or Active Directory](add-ad-aad-built-in-security-groups.md) before adding them to Azure DevOps. | - -::: moniker range="azure-devops" +::: moniker range="azure-devops" > [!NOTE] -> Users added to the **Project-Scoped Users** group can't access most **Organization Settings** pages, including **Permissions**. To learn more, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). -> -> Also, users granted **Stakeholder** access, won't be able to access select features even if granted permissions to those features. To learn more, see [Stakeholder access quick reference](stakeholder-access.md). +>- Users in the **Project-scoped Users** group can't access most organization settings, including permissions. For more information, see [Manage your organization, limit user visibility for projects, and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). +>- Users with **Stakeholder** access can't access specific features even if they have permissions to those features. For more information, see [Stakeholder access quick reference](stakeholder-access.md). ::: moniker-end ::: moniker range="< azure-devops" > [!NOTE] -> Users granted **Stakeholder** access, won't be able to access select features even if granted permissions to those features. To learn more, see [Stakeholder access quick reference](stakeholder-access.md). +> Users with **Stakeholder** access can't access specific features even if they have permissions to those features. For more information, see [Stakeholder access quick reference](stakeholder-access.md). ::: moniker-end + - - -## Add members to the Project Collection Administrators group +## Add members to the Project Administrators group -You can add users who've been added to a project, organization, or collection to the **Project Collection Administrators** group, or any other group at the organization or collection-level. To add a custom security group, first create the group as described in [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md). - -Here we show how to add a user to the **Project Collection Administrators** group. The method is similar to adding an Azure Active Directory or Active Directory group. +Do the following steps to add users to the **Project Administrators** group or any other group at the organization or collection level. To add a custom security group, first [create the group](add-remove-manage-user-group-security-group.md). ::: moniker range="azure-devops" > [!NOTE] -> To enable the **Organization Permissions Settings Page v2** preview page, see [Enable preview features](../../project/navigation/preview-features.md). +> To turn on the **Organization Permissions Settings Page v2** preview page, see [Enable preview features](../../project/navigation/preview-features.md). #### [Preview page](#tab/preview-page) -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). -2. Choose **Organization settings** and then **Permissions**. +2. Select **Organization settings** > **Permissions**. - ![Choose Organization settings, and then Permissions](media/permissions/open-project-settings-permissions-preview.png) + ![Screenshot showing Organization settings and Permissions selections.](media/permissions/open-project-settings-permissions-preview.png) -3. Choose **Project Administrators** group, **Members**, and then **Add**. +3. Select **Project Administrators** group, **Members**, and then **Add**. > [!div class="mx-imgBorder"] - > ![Project Settings > Permissions, Add member](media/project-collection/project-admin-members-add-s154.png) + > ![Screenshot showing Project Settings > Permissions, Add member.](media/project-collection/project-admin-members-add.png) -4. Enter the name of the user account or custom security group into the text box and then select from the match that appears. You can enter several identities recognized by the system into the **Add users and/or groups** box. The system automatically searches for matches. Choose the matches that meet your choices. +4. Enter the name of the user account or custom security group into the text box and select the matching result. You can enter multiple identities into the **Add users and/or groups** box, and the system automatically searches for matches. Select the appropriate matches. > [!div class="mx-imgBorder"] - > ![Add users and group dialog, preview page.](media/project-collection/add-member-project-admin.png) + > ![Screenshot showing Add users and group dialog, preview page.](media/project-collection/add-member-project-admin.png) -5. Choose **Save**. +5. Select **Save**. #### [Current page](#tab/current-page) -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). -2. Choose **Project Settings** and then **Security**. +2. Select **Project Settings** and then **Security**. - *To see the full image, click to expand*. + *To see the full image, select to expand*. - [![Project Settings>Security](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) + [![Screenshot showing selections, Project Settings and Security.](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) -3. Choose **Project Administrators** group, **Members**, and then **Add**. +3. Select **Project Administrators** group, **Members**, and then **Add**. > [!div class="mx-imgBorder"] - > ![Screenshot of Project Settings>Security, Add member.](media/project-level-permissions-add-member.png) + > ![Screenshot of Project Settings, Security, Add member selections.](media/project-level-permissions-add-member.png) -4. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. +4. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Select one or more matches. > [!div class="mx-imgBorder"] - > ![Add users and group dialog, current page.](media/project-level-permissions-add-a-user.png) + > ![Screenshot showing Add users and group dialog, current page.](media/project-level-permissions-add-a-user.png) -5. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. +5. Select **Save changes**. Select the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon and the additions reflect. * * * ::: moniker-end +::: moniker range="< azure-devops" -::: moniker range=">= azure-devops-2019 < azure-devops" - -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). - -2. Choose **Project Settings** and then **Security**. +1. Open the web portal and choose the collection where you want to add users or groups. - *To see the full image, click to expand*. +2. Select **Collection Settings** > **Security**. - [![Project Settings>Security](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) + [![Screenshot of Project Settings, Security selection.](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) -1. Choose **Project Administrators** group, **Members**, and then **Add**. +3. Select **Project Administrators** > **Members** > **Add**. > [!div class="mx-imgBorder"] - > ![Project Settings>Security, Add member](media/project-level-permissions-add-member.png) + > ![Screenshot of Project Settings>Security, Add member selection sequence.](media/project-level-permissions-add-member.png) -1. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. +4. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Select one or more matches. > [!div class="mx-imgBorder"] - > ![Add users and group dialog, on-premises.](media/project-level-permissions-add-a-user.png) + > ![Screenshot of Add users and group dialog, on-premises.](media/project-level-permissions-add-a-user.png) -1. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. +5. Select **Save changes** and the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. ::: moniker-end -::: moniker range="tfs-2018" - -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). - -1. Choose the :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: gear icon to open the administrative context. - - > [!div class="mx-imgBorder"] - > ![Open Project Settings, horizontal nav](../../media/settings/open-project-settings-horz.png) - -2. Choose **Security**, **Project Administrators** group, **Members**, and then **Add**. - - > [!div class="mx-imgBorder"] - > ![Project Settings>Security, Add member](media/project-level-permissions-add-member.png) - -3. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. - - > [!div class="mx-imgBorder"] - > ![Add users and group dialog, TFS 2018 and earlier versions.](media/project-level-permissions-add-a-user.png) - - > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see [Permissions and access](permissions-access.md). - -4. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. - -::: moniker-end - - ## Change permissions for a group -You can change the permissions for any organization or collection-level group, except the **Project Collection Administrators** group. You can add security groups to a collection in a similar manner to adding a security group to a project. See [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md). To understand permission assignments and inheritance, see [About permissions, Permission states](about-permissions.md#permission-states). - +You can change the permissions for any organization or collection-level group, except the **Project Collection Administrators** group. Adding security groups to a collection is similar to adding them to a project. For more information, see [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md) and [About permissions, Permission states](about-permissions.md#permission-states). ::: moniker range="azure-devops" > [!NOTE] -> To enable the **Organization Permissions Settings Page v2** preview page, see [Enable preview features](../../project/navigation/preview-features.md). +> To turn on the **Organization Permissions Settings Page v2** preview page, see [Enable preview features](../../project/navigation/preview-features.md). #### [Preview page](#tab/preview-page) -1. Open the **Permissions** page as described in the previous section, [Add a user or group to the Project Administrators group](#add-user-group). +1. Go to the **Permissions** page as described in the previous section, [Add a user or group to the Project Administrators group](#add-user-group). > [!NOTE] - > You can't change the permission settings for the **Project Collection Administrators** group. This is by design. + > By design, you can't change the permission settings for the **Project Collection Administrators** group. -2. From the **Permissions** page, choose the group whose permissions you want to change. +2. Choose the group whose permissions you want to change. - For example, here we choose the **Stakeholders Limited** group, and change several permissions. + In the following example, we choose the **Stakeholders Limited** group, and change several permissions. - :::image type="content" source="media/change-project-collection-level/change-project-collection-level-permission-for-group.png" alt-text="Screenshot of Collection-level Prmissions for a selected group, preview page."::: + :::image type="content" source="media/change-project-collection-level/change-project-collection-level-permission-for-group.png" alt-text="Screenshot of Collection-level Permissions for a selected group, preview page."::: - Your changes are automatically saved. + Your changes automatically save. - #### [Current page](#tab/current-page) -1. Open the **Security** page as described in the previous section, [Add a user or group to the Project Collection Administrators group](#add-user-group). +1. Go to the **Security** page as described in the previous section, [Add a user or group to the Project Collection Administrators group](#add-user-group). -1. From the **Security** page, choose the group whose permissions you want to change. +1. Choose the group whose permissions you want to change. - For example, here we choose the **Stakeholders Limited** group, and change several permissions. + In the following example, we choose the **Stakeholders Limited** group, and change several permissions. - :::image type="content" source="media/change-project-collection-level/change-project-collection-level-permission-for-groups-current-page.png" alt-text="Screenshot of Collection-level Prmissions for a selected group, current page."::: + :::image type="content" source="media/change-project-collection-level/change-project-collection-level-permission-for-groups-current-page.png" alt-text="Screenshot of Collection-level Permissions for a selected group, current page."::: -1. Choose **Save changes**. +1. Select **Save changes**. * * * @@ -223,60 +184,56 @@ You can change the permissions for any organization or collection-level group, e ::: moniker range="< azure-devops" +1. Go to the **Security** page as described in the previous section, [Add a user or group to the Project Collection Administrators group](#add-user-group). -1. Open the **Security** page as described in the previous section, [Add a user or group to the Project Collection Administrators group](#add-user-group). - -1. From the **Security** page, choose the group whose permissions you want to change. +1. Choose the group whose permissions you want to change. - For example, here we choose the **Stakeholders Limited** group, and change several permissions. + In the following example, we choose the **Stakeholders Limited** group and change several permissions. - :::image type="content" source="media/change-project-collection-level/change-project-collection-level-permission-for-groups-current-page.png" alt-text="Screenshot of Collection-level Prmissions for a selected group, current page."::: - -1. Choose **Save changes**. + :::image type="content" source="media/change-project-collection-level/change-project-collection-level-permission-for-groups-current-page.png" alt-text="Screenshot of Collection-level Permissions for a selected group, current page."::: +1. Select **Save changes**. ::: moniker-end - ## Change permissions for a user -You can change the collection-level permissions for a specific user. To understand permission assignments and inheritance, see [About permissions, Permission states](about-permissions.md#permission-states). +You can change the collection-level permissions for a specific user. For more information, see [About permissions, Permission states](about-permissions.md#permission-states). - ::: moniker range="azure-devops" > [!NOTE] -> To enable the **Organization Permissions Settings Page v2** preview page, see [Enable preview features](../../project/navigation/preview-features.md). +> To turn on the **Organization Permissions Settings Page v2** preview page, see [Enable preview features](../../project/navigation/preview-features.md). #### [Preview page](#tab/preview-page) -1. Open the **Permissions** page as described in the previous section, [Add a user or group to the Project Administrators group](#add-user-group). +1. Go to the **Permissions** page as described in the previous section, [Add a user or group to the Project Administrators group](#add-user-group). -1. From the **Permissions** page, choose **Users**, and then choose the user whose permissions you want to change. +2. Select **Users**, then choose the user whose permissions you want to change. :::image type="content" source="media/change-project-level/choose-users-select-user.png" alt-text="Screenshot of Users tab, choose a user."::: -1. From the **Permissions** page, change the assignment for one or more permissions. +3. Change the assignment for one or more permissions. - For example, here we change the **Edit project-level information** for Christie Church. + In the following example, we change the **Edit project-level information** for Christie Church. :::image type="content" source="media/change-project-collection-level/change-project-level-permission-for-user.png" alt-text="Screenshot of selected users, Permissions."::: - Dismiss the dialog when done. Your changes are automatically saved. + Dismiss the dialog and your changes automatically save. #### [Current page](#tab/current-page) -1. Open the **Security** page as described in the previous section, [Add a user or group to the Project Administrators group](#add-user-group). +1. Go to the **Security** page as described in the previous section, [Add a user or group to the Project Administrators group](#add-user-group). -1. From the **Security** page, in the **Filter users and groups** text box, enter the name of the user whose permissions you want to change. +1. In the **Filter users and groups** text box, enter the name of the user whose permissions you want to change. 1. Change the assignment for one or more permissions. - For example, here we change the **Edit project-level information** for Christie Church. + In the following example, we change the **Edit project-level information** for Christie Church. - :::image type="content" source="media/change-project-collection-level/change-project-level-permission-for-user-current-page.png" alt-text="Screenshot of selected user , change Edit project-level information permission level."::: + :::image type="content" source="media/change-project-collection-level/change-project-level-permission-for-user-current-page.png" alt-text="Screenshot of selected user, change Edit project-level information permission level."::: -1. Choose **Save changes**. +1. Select **Save changes**. * * * @@ -286,16 +243,15 @@ You can change the collection-level permissions for a specific user. To understa 1. Open the **Security** page as described in the previous section, [Add a user or group to the Project Administrators group](#add-user-group). -1. From the **Security** page, in the **Filter users and groups** text box, enter the name of the user whose permissions you want to change. +1. In the **Filter users and groups** text box, enter the name of the user whose permissions you want to change. 1. Change change the assignment for one or more permissions. - For example, here we change the **Edit project-level information** for Christie Church. + In the following example, we change the **Edit project-level information** for Christie Church. - :::image type="content" source="media/change-project-collection-level/change-project-level-permission-for-user-current-page.png" alt-text="Screenshot of selected user , change Edit project-level information permission level."::: - -1. Choose **Save changes**. + :::image type="content" source="media/change-project-collection-level/change-project-level-permission-for-user-current-page.png" alt-text="Screenshot of selected user, change Edit project-level information permission level."::: +1. Select **Save changes**. ::: moniker-end @@ -303,7 +259,7 @@ You can change the collection-level permissions for a specific user. To understa ## On-premises deployments -For on-premises deployments, see these additional articles: +For on-premises deployments, see the following articles: - [Add a user as an Azure DevOps Server administrator](/azure/devops/server/admin/add-administrator) - [Azure DevOps Server service account groups](/azure/devops/server/admin/service-accounts-dependencies) @@ -312,42 +268,35 @@ For on-premises deployments, see these additional articles: ::: moniker range="< azure-devops" -If your on-premises deployment is integrated with SQL Server Reports, you'll need to manage membership for those products separately from their websites. See [Grant permissions to view or create SQL Server reports in TFS](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports). +If your on-premises deployment is integrated with SQL Server Reports, manage membership for those products separately from their websites. For more information, see [Grant permissions to view or create SQL Server reports](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports). ::: moniker-end - - ::: moniker range="< azure-devops" ## FAQs #### Q: When do I need to add someone to the Project Collection Administrator role? -A: It varies. For most organizations that use Azure DevOps, Project Collection Administrators manage the collections that members of the **Team Foundation Administrators** group create. Members of the **Project Collection Administrators** group don't create the collections themselves. Project collection administrators also do many operations required to maintain the collection. Operations include creating team projects, adding users to groups, modifying the settings for the collection, and so on. +A: It varies. In most organizations, Project Collection Administrators manage the collections created by the **Team Foundation Administrators** group. They don’t create collections themselves but handle tasks like creating team projects, adding users to groups, and modifying collection settings. #### Q: What are the optimal permissions to administer a project collection across all of its components and dependencies? -A: Project collection administrators must be members of the following groups or have the following permissions: +A: Project Collection Administrators need the following permissions: -- Team Foundation Server: A member of the **Project Collection Administrators** group, or have the appropriate [collection-level permissions](../../organizations/security/permissions.md#collection) set to **Allow**. - -- SharePoint Products: If the collection is configured with a site collection resource, then a member of the **Site Collection Administrators** group. - -- Reporting Services: If the collection is configured with reporting resources, then a member of the **Team Foundation Content Manager** group. +- **Team Foundation Server:** Members of the **Project Collection Administrators** group, or have the necessary [collection-level permissions](../../organizations/security/permissions.md#collection) set to **Allow**. +- **SharePoint Products:** Members of the **Site Collection Administrators** group if the collection includes a site collection resource. +- **Reporting Services:** Members of the **Team Foundation Content Manager** group if the collection includes reporting resources. #### Q: I'm an admin, but I don't have permission to add a Project Collection Administrator. What do I need? -A: The following permissions are required: - -- You must be a **Project Collection Administrator**, or your **View Server-Level Information** and **Edit Server-Level Information** permissions must be set to **Allow**. +A: You need the following permissions: +- **Project Collection Administrator** or **View Server-Level Information and Edit Server-Level Information** set to **Allow**. +- For SharePoint Products, membership in the **Site Collection Administrators or Farm Administrators** groups. +- For Reporting Services, membership in the **Content Managers** or **Team Foundation Content Managers** groups. -- To add permissions for SharePoint Products, you must be a member of the **Site Collection Administrators** or **Farm Administrators** groups for SharePoint Products. - -- To add permissions for Reporting Services, you must be a member of the **Content Managers** or **Team Foundation Content Managers** groups for Reporting Services. - -> [!Important] -> To perform administrative tasks like creating project collections, your user requires administrative permissions. The service account that the Team Foundation Background Job Agent uses must have certain permissions granted to it. For more information, see [Service accounts and dependencies in Team Foundation Server](/azure/devops/server/admin/service-accounts-dependencies) and [Team Foundation Background Job Agent](/azure/devops/server/architecture/background-job-agent). +> [!IMPORTANT] +> To create project collections and perform other administrative tasks, users need administrative permissions. Additionally, the service account for the Team Foundation Background Job Agent must have specific permissions. For more information, see [Service accounts and dependencies in Team Foundation Server](/azure/devops/server/admin/service-accounts-dependencies) and [Team Foundation Background Job Agent](/azure/devops/server/architecture/background-job-agent). ::: moniker-end @@ -358,8 +307,8 @@ A: The following permissions are required: ## Related articles +- [Look up a project collection administrator](look-up-project-collection-administrators.md) +- [Manage users, groups, and security groups](add-remove-manage-user-group-security-group.md) +- [Request an increase in permission levels](request-changes-permissions.md) +- [Change project-level permissions](change-project-level-permissions.md) - [Set object-level permissions](set-object-level-permissions.md) -- [Get started with permissions, access, and security groups](about-permissions.md) -- [Permissions lookup reference](permissions-lookup-guide.md) -- [Permissions and groups reference](permissions.md) -- [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) diff --git a/docs/organizations/security/change-project-level-permissions.md b/docs/organizations/security/change-project-level-permissions.md index d9d06e7e1b2..77e4f9138be 100644 --- a/docs/organizations/security/change-project-level-permissions.md +++ b/docs/organizations/security/change-project-level-permissions.md @@ -8,55 +8,45 @@ ms.author: chcomley author: chcomley ms.topic: quickstart monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 05/21/2024 --- - # Change project-level permissions [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Several permissions are set at the project level. You can grant these permissions by adding a user or group to the **Project Administrators** group. Or, you can grant select project-level permissions to a custom security group or to a user. - -Consider adding users to the **Project Administrators** group when they are tasked with adding or managing teams, area and -iteration paths, repositories, service hooks, and service end points. - +Many permissions get set at the project level. You can grant these permissions by adding a user or group to the **Project Administrators** group. Or, you can grant specific project-level permissions to a custom security group or to a user. -See the following articles for related information: - -- [Request an increase in permission levels](request-changes-permissions.md) -- [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md) -- [Look up a project administrator ](look-up-project-administrators.md) -- [Set object-level permissions](set-object-level-permissions.md) -- [Change permissions at the organization or collection-level](change-organization-collection-level-permissions.md) +Consider adding users to the **Project Administrators** group when they're tasked with adding or managing teams, area and iteration paths, repositories, service hooks, and service end points. ## Project-level permissions [!INCLUDE [project-level-permissions](./includes/project-level-permissions.md)] > [!NOTE] -> The permission to add or remove project-level security groups and add and manage project-level group membership is assigned to all members of the **Project Administrator**s group. It isn't controlled by a permissions surfaced within the user interface. +> The permission to add or remove project-level security groups and add and manage project-level group membership is assigned to all members of the **Project Administrators** group. It isn't controlled by a permission surfaced within the user interface. ### Create tag definition permission -By default, members of the **Contributors** group are assigned the **Create tag definition** permission. Although the **Create tag definition** permission appears in the security settings at the project-level, tagging permissions are actually collection-level permissions that are scoped at the project level when they appear in the user interface. To scope tagging permissions to a single project when using a command-line tool, you must provide the GUID for the project as part of the command syntax. Otherwise, your change will apply to the entire collection. To learn more about work item tagging permissions, see [Security groups, service accounts, and permissions, Work item tags](permissions.md#work-item-tags). +By default, members of the **Contributors** group are assigned the **Create tag definition** permission. Although the **Create tag definition** permission appears in the security settings at the project-level, tagging permissions are actually collection-level permissions that are scoped at the project level when they appear in the user interface. To scope tagging permissions to a single project when using a command-line tool, you must provide the GUID for the project as part of the command syntax. Otherwise, your change applies to the entire collection. For more information, see [Security groups, service accounts, and permissions, Work item tags](permissions.md#work-item-tags). ## Prerequisites -- To manage permissions or groups at the project level, you must be a member of the **Project Administrators** security group. If you created the project, you are automatically added as a member of this group. To get added to this group, you need to request permissions from a member of the **Project Administrators** group. See [Look up a project administrator](look-up-project-administrators.md). -- If want to add security groups defined in Azure Active Directory or Active Directory, make sure those are first defined. To learn more, see [Add AD/Azure AD users or groups to a built-in security group](add-ad-aad-built-in-security-groups.md). +|Category | Requirements | +|-------------|-------------| +| **Permissions** | Member of the [**Project Administrators** security group](look-up-project-administrators.md). If you created the organization or collection, you're automatically a member of this group. | +| **Directory services** | [Security groups defined in Microsoft Entra ID or Active Directory](add-ad-aad-built-in-security-groups.md) before adding them to Azure DevOps. | > [!NOTE] -> Users granted **Stakeholder** access, aren't able to access select features even if granted permissions to those features. To learn more, see [Stakeholder access quick reference](stakeholder-access.md). +> Users granted **Stakeholder** access can't access select features even if granted permissions to those features. For more information, see [Stakeholder access quick reference](stakeholder-access.md). - - + ## Add members to the Project Administrators group -You can add users who've been added to a project, organization, or collection to the Project Administrators group. To add a custom security group, first create the group as described in [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md). +You can add users who are associated with a project, organization, or collection to the Project Administrators group. This group has specific permissions at the organizations or collection level. To add a custom security group, first create the group as described in [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md). -Here we show how to add a user to the built-in **Project Administrators** group. The method is similar to adding an Azure Active Directory or Active Directory group. +Here we show how to add a user to the built-in **Project Administrators** group. The method is similar to adding a Microsoft Entra ID or Active Directory group. ::: moniker range="azure-devops" @@ -65,110 +55,76 @@ Here we show how to add a user to the built-in **Project Administrators** group. #### [Preview page](#tab/preview-page) -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Choose **Project settings** and then **Permissions**. +2. Select **Project settings** > **Permissions**. - ![Choose Project settings, and then Permissions](media/permissions/open-project-settings-permissions-preview.png) + ![Screenshot showing selections, Project settings > Permissions.](media/permissions/open-project-settings-permissions-preview.png) -3. Choose **Project Administrators** group, **Members**, and then **Add**. +3. Select **Project Administrators** group > **Members** > **Add**. > [!div class="mx-imgBorder"] - > ![Project Settings > Permissions, Add member](media/project-collection/project-admin-members-add-s154.png) + > ![Screenshot showing button selections, Project Settings > Permissions, Add member.](media/project-collection/project-admin-members-add.png) -4. Enter the name of the user account or custom security group into the text box and then select from the match that appears. You can enter several identities recognized by the system into the **Add users and/or groups** box. The system automatically searches for matches. Choose the matches that meet your choices. +4. Enter the name of the user account or custom security group into the text box. You can enter several identities recognized by the system into the **Add users and/or groups** box. The system automatically searches for matches. Choose one or more matches. > [!div class="mx-imgBorder"] - > ![Add users and group dialog, preview page.](media/project-collection/add-member-project-admin.png) - - + > ![Screenshot showing the Add users and group dialog, preview page.](media/project-collection/add-member-project-admin.png) -5. Choose **Save**. +5. Select **Save**. #### [Current page](#tab/current-page) -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Choose **Project Settings** and then **Security**. +2. Select **Project settings** > **Security**. - *To see the full image, click to expand*. + [![Screenshot showing Project settings, Security selections.](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) - [![Project Settings>Security](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) - -3. Choose **Project Administrators** group, **Members**, and then **Add**. +3. Select **Project Administrators** group > **Members** > **Add**. > [!div class="mx-imgBorder"] - > ![Screenshot of Project Settings>Security, Add member.](media/project-level-permissions-add-member.png) + > ![Screenshot of Project Settings, Security, Add member selections.](media/project-level-permissions-add-member.png) -4. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. +4. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose one or more matches. > [!div class="mx-imgBorder"] - > ![Add users and group dialog, current page.](media/project-level-permissions-add-a-user.png) + > ![Screenshot of Add users and group dialog, current page.](media/project-level-permissions-add-a-user.png) -5. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. +5. Select **Save changes** > :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon, and then view the additions. * * * ::: moniker-end +::: moniker range=" **Security**. - *To see the full image, click to expand*. + [![Screenshot showing selected Project settings and Security buttons.](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) - [![Project Settings>Security](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) - -1. Choose **Project Administrators** group, **Members**, and then **Add**. +3. Select **Project Administrators** group > **Members** > **Add**. > [!div class="mx-imgBorder"] - > ![Project Settings>Security, Add member](media/project-level-permissions-add-member.png) + > ![Screenshot showing Project Settings, Security, Add member selections.](media/project-level-permissions-add-member.png) -1. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. +4. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose one or more matches. > [!div class="mx-imgBorder"] - > ![Add users and group dialog, on-premises.](media/project-level-permissions-add-a-user.png) + > ![Screenshot showing Add users and group dialog, on-premises.](media/project-level-permissions-add-a-user.png) > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see [Permissions and access](permissions-access.md). + > Users with limited access, such as Stakeholders, can't access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). -1. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. +5. Select **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon, and then view the additions. ::: moniker-end -::: moniker range="tfs-2018" - -1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). - -1. Choose the :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: gear icon to open the administrative context. - - > [!div class="mx-imgBorder"] - > ![Open Project Settings, horizontal nav](../../media/settings/open-project-settings-horz.png) - -2. Choose **Security**, **Project Administrators** group, **Members**, and then **Add**. - - > [!div class="mx-imgBorder"] - > ![Project Settings>Security, Add member](media/project-level-permissions-add-member.png) - -3. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice. - - > [!div class="mx-imgBorder"] - > ![Add users and group dialog, TFS 2018 and earlier versions.](media/project-level-permissions-add-a-user.png) - - > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see [Permissions and access](permissions-access.md). - -4. Choose **Save changes**. Choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see the additions. - -::: moniker-end - - ## Change permissions for a group -You can change the project-level permissions for any project-level group, except the **Project Administrators** group. Each team added to a project is automatically added as a project-level group. To add security groups to a project, see [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md). To understand permission assignments and inheritance, see [About permissions, Permission states](about-permissions.md#permission-states). +You can modify project-level permissions for any group associated with a project, except for the **Project Administrators** group. Also, each team that is added to a project is automatically included as a project-level group. To add security groups to a project, see [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md). To understand permission assignments and inheritance, see [About permissions, Permission states](about-permissions.md#permission-states). ::: moniker range="azure-devops" @@ -184,7 +140,7 @@ You can change the project-level permissions for any project-level group, except 2. From the **Permissions** page, choose the group whose permissions you want to change. - For example, here we choose the **Contributors** group, change their permissions for **Delete and restore work items** to **Allow**. + For example, we choose the **Contributors** group and change their permissions for **Delete and restore work items** to **Allow**. > [!div class="mx-imgBorder"] > ![Screenshot of Contributors group, permissions, preview page.](media/project-collection/delete-restore-work-items-permissions-s154.png) @@ -192,22 +148,20 @@ You can change the project-level permissions for any project-level group, except Your changes are automatically saved. > [!TIP] - > In general, if you add a user to the **Contributors** group, they can add and modify work items. You can restrict permissions of users or user groups to add and modify work items based on the **Area Path**. For details, see [Set permissions and access for work tracking, Modify work items under an area path](set-permissions-access-work-tracking.md#set-permissions-area-path). - + > If you add a user to the **Contributors** group, they can add and modify work items. You can restrict permissions of users or user groups to add and modify work items based on the **Area Path**. For more information, see [Modify work items under an area path](set-permissions-access-work-tracking.md#set-permissions-area-path). #### [Current page](#tab/current-page) - 1. Open the **Security** page as described in the previous section, [Add a user or group to the Project Administrators group](#add-user-group). 1. From the **Security** page, choose the group whose permissions you want to change. - For example, here we grant permission to the **Contributors** group to **Delete and restore work items**. + For example, we grant permission to the **Contributors** group to **Delete and restore work items**. > [!div class="mx-imgBorder"] > ![Screenshot of Contributors group, permissions, current page.](media/project-level-permissions-contributors-group.png) -1. Choose **Save changes**. +2. Select **Save changes**. * * * @@ -217,29 +171,25 @@ You can change the project-level permissions for any project-level group, except 1. From the **Security** page, choose the group whose permissions you want to change. - For example, here we grant permission to the Contributors group to delete and restore work items. + For example, we grant permission to the Contributors group to delete and restore work items. > [!div class="mx-imgBorder"] > ![Screenshot of Contributors group, permissions, on-premises versions.](media/project-level-permissions-contributors-group.png) > [!TIP] - > In general, if you add a user to the Contributors group, they can add and modify work items. You can restrict permissions of users or user groups to add and modify work items based on the area path. For details, see [Set permissions and access for work tracking, Modify work items under an area path](set-permissions-access-work-tracking.md#set-permissions-area-path). + > If you add a user to the Contributors group, they can add and modify work items. You can restrict permissions of users or user groups to add and modify work items based on the area path. For more information, see [Modify work items under an area path](set-permissions-access-work-tracking.md#set-permissions-area-path). For a description of each permission, see [Permissions and groups reference, project-level permissions](permissions.md#project-level-permissions). > [!NOTE] > You can't change the permission settings for the Project Administrators group. This is by design. -2. Choose **Save changes**. - +2. Select **Save changes**. ::: moniker-end - - ## Change permissions for a user - You can change the project-level permissions for a specific user. To understand permission assignments and inheritance, see [About permissions, Permission states](about-permissions.md#permission-states). ::: moniker range="azure-devops" @@ -251,17 +201,17 @@ You can change the project-level permissions for a specific user. To understand 1. Open the **Permissions** page as described in the previous section, [Add a user or group to the Project Administrators group](#add-user-group). -1. From the **Permissions** page, choose **Users**, and then choose the user whose permissions you want to change. +1. From the **Permissions** page, select **Users**, and then choose the user whose permissions you want to change. :::image type="content" source="media/change-project-level/choose-users-select-user.png" alt-text="Screenshot of Users tab, choose a user."::: 1. From the **Permissions** page, change the assignment for one or more permissions. - For example, here we change the **Edit project-level information** for Christie Church. + For example, we change the **Edit project-level information** for Christie Church. :::image type="content" source="media/change-project-level/change-project-level-permission-for-user.png" alt-text="Screenshot of selected users, Permissions."::: - Dismiss the dialog when done. Your changes are automatically saved. + Dismiss the dialog when you're done. Your changes are automatically saved. #### [Current page](#tab/current-page) @@ -271,11 +221,11 @@ You can change the project-level permissions for a specific user. To understand 1. Change change the assignment for one or more permissions. - For example, here we change the **Edit project-level information** for Christie Church. + For example, we change the **Edit project-level information** for Christie Church. - :::image type="content" source="media/change-project-level/change-project-level-permission-for-user-current-page.png" alt-text="Screenshot of selected user , change Edit project-level information permission level."::: + :::image type="content" source="media/change-project-level/change-project-level-permission-for-user-current-page.png" alt-text="Screenshot of selected user, change Edit project-level information permission level."::: -1. Choose **Save changes**. +2. Select **Save changes**. * * * @@ -289,16 +239,14 @@ You can change the project-level permissions for a specific user. To understand 1. Change change the assignment for one or more permissions. - For example, here we change the **Edit project-level information** for Christie Church. - - :::image type="content" source="media/change-project-level/change-project-level-permission-for-user-current-page.png" alt-text="Screenshot of selected user , change Edit project-level information permission level."::: + For example, we change the **Edit project-level information** for Christie Church. -1. Choose **Save changes**. + :::image type="content" source="media/change-project-level/change-project-level-permission-for-user-current-page.png" alt-text="Screenshot of selected user, change Edit project-level information permission level."::: +2. Select **Save changes**. ::: moniker-end - ## Next steps > [!div class="nextstepaction"] @@ -308,7 +256,6 @@ You can change the project-level permissions for a specific user. To understand - [Set object-level permissions](set-object-level-permissions.md) - [Get started with permissions, access, and security groups](about-permissions.md) -- [Permissions lookup reference](permissions-lookup-guide.md) -- [Permissions and groups reference](permissions.md) +- [Look up permissions](permissions-lookup-guide.md) +- [Learn about permissions and groups](permissions.md) - [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) - diff --git a/docs/organizations/security/credential-storage.md b/docs/organizations/security/credential-storage.md deleted file mode 100644 index 8368f7e897e..00000000000 --- a/docs/organizations/security/credential-storage.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: How we store your credentials -titleSuffix: Azure DevOps Services -description: Learn how Microsoft stores your credentials for Azure DevOps -ms.topic: article -ms.subservice: azure-devops-security -ms.author: chcomley -author: chcomley -monikerRange: 'azure-devops' -ms.date: 10/01/2020 ---- - -# How we store your credentials for Azure DevOps Services - -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -[!INCLUDE [alt-creds-deprecation-notice](../../includes/alt-creds-deprecation-notice.md)] - -## Credential security - -Microsoft is committed to ensuring that your projects remain safe and secure, without exception. In Azure DevOps, your projects benefit from multiple layers of security and governance technologies, operational practices, and compliance policies. We enforce data privacy and integrity both at rest and in transit. In addition, we adhere to the following practices with respect to the credentials or secrets that Azure DevOps stores. To learn more about how to choose the right authentication mechanism, see [Guidance for authentication](../../integrate/get-started/authentication/authentication-guidance.md). - -## Personal access tokens (PATs) - -* We store a hash of the PAT -* Raw PAT is generated in-memory on the server side as 32 bytes randomly generated through RNGCryptoServiceProvider then shared with the caller as a base-32-encoded string. This value is NOT stored -* PAT hash is generated in-memory on the server side as an *HMACSHA256Hash* of the raw PAT using a 64-byte symmetric signing key stored in our key vault -* Hash is stored in our database - -## Secure shell (SSH) keys - -* We store a hash of the enclosing organization ID and the SSH public key -* Raw public key is provided directly by the caller over SSL -* SSH hash is generated in-memory on the server side as an *HMACSHA256Hash* of the organization ID and raw public key using a 64-byte symmetric signing key stored in our key vault -* Hash is stored in our database - -## OAuth credentials (JWTs) - -* These are issued as fully self-describing JSON web tokens (JWTs) and are NOT stored in our service -* The claims in JWTs issued and presented to our service are validated using a certificate stored in our key vault diff --git a/docs/organizations/security/data-location.md b/docs/organizations/security/data-location.md index 185586ee29c..3bf42b90e6e 100644 --- a/docs/organizations/security/data-location.md +++ b/docs/organizations/security/data-location.md @@ -1,13 +1,13 @@ --- title: Data locations for Azure DevOps titleSuffix: Azure DevOps Services -description: Learn where your data is stored for Azure DevOps +description: Learn where your data is stored for Azure DevOps. ms.topic: article ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.reviewer: jominana -ms.date: 03/28/2023 +ms.date: 12/15/2023 monikerRange: 'azure-devops' --- @@ -15,11 +15,11 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -You can choose the location for your data during initial sign-up and creation of your organization. Azure DevOps operates in the following geographical locations, or “geos”. +You can choose the location for your data during initial sign-up and creation of your organization. ## Data locations -Azure DevOps data is available in the following eight geographies across the world: +Azure DevOps data is available in the following geographical locations: - Australia - Brazil @@ -27,58 +27,56 @@ Azure DevOps data is available in the following eight geographies across the wor - Asia Pacific - Europe (EU) - India -- United Kingdom +- United Kingdom (UK) - United States (US) -We default your organization to your closest geography. However, you can choose a different geography. If you change your mind afterward, you can [migrate your organization to a different geography](../accounts/change-organization-location.md). - -For more information, see [Data residency in Azure](https://azure.microsoft.com/global-infrastructure/data-residency/#overview). +By default, your organization uses the closest location. However, you can choose a different location when you create your organization. If you change your mind later, you can [migrate your organization to a different location](../accounts/change-organization-location.md). ## Customer data -Except [as noted](#transferring-your-data), Azure DevOps maintains all customer data within your selected geography. Customer data includes the following data types: +Except [as noted later in this article](#transferring-your-data), Azure DevOps maintains all customer data within your selected geographical location. Customer data includes the following data types: - Source code - Work items - Test results - Geo-redundant mirrors and offsite backups -Azure DevOps works with and uses many Microsoft Azure services. For more information and details on customer data retention by location, see [Data residency in Azure](https://azure.microsoft.com/global-infrastructure/data-residency/). +Azure DevOps works with and uses many Microsoft Azure services. For more information on customer data retention by location, see [Data residency in Azure](https://azure.microsoft.com/global-infrastructure/data-residency/). ### Profile data -Azure DevOps stores information that's global in nature, such as user identities and profile information as follows: +Azure DevOps stores information that's global in nature, such as user identities and profile data, as follows: -- US-based users: profile data is in US data center -- EU-based users: profile data is in EU data center -- UK-based users: profile data is in UK data center -- Users from all other countries and regions: profile data is in US data center +- For US-based users: in the US datacenter +- For EU-based users: in the EU datacenter +- For UK-based users: in the UK datacenter +- For users from all other countries and regions: in the US datacenter ### Token data -Azure DevOps considers token information, such as personal access tokens (PATs) and SSH keys, global in nature, and stores this information in a US data center. +Azure DevOps stores token data, such as personal access tokens and Secure Shell (SSH) keys, in a US datacenter. ## Allowlist data for tenant policies -We recommend using groups with your tenant policy allow list(s). If you use a named user, be aware that a reference to the named user's identity resides in the United States, Europe (EU), and Southeast Asia (Singapore). +We recommend using groups with your tenant policy allowlists. If you use a named user, be aware that a reference to the named user's identity resides in the US, EU, and Southeast Asia (Singapore). ## Transferring your data -We don't transfer customer data outside of your selected geography. However, we transfer your data if we need to do any of the following actions: +We don't transfer customer data outside your selected location. However, we transfer your data if we need to take any of the following actions: -- provide customer support -- troubleshoot the service -- comply with legal requirements +- Provide customer support +- Troubleshoot the service +- Comply with legal requirements -If needed, you can transfer your data using preview, beta, or other prerelease services. These services typically store your data in the United States, but may store it globally. +If necessary, you can transfer your data by using preview, beta, or other prerelease services. These services typically store your data in the United States, but they might store it globally. > [!NOTE] -> For builds and releases running on Microsoft-provided macOS agents, your data will be transferred to a GitHub data center in the US. This data center location is owned and managed by GitHub with compliance certifications, such as SOC 1 & 2 Type II reports available [here](https://github.com/security). +> For builds and releases that run on Microsoft-provided macOS agents, your data is transferred to a GitHub datacenter in the United States. GitHub owns and manages this datacenter location with compliance certifications, such as [SOC 1 Type 2 and SOC 2 Type 2](https://github.com/security). -Microsoft doesn't control or limit the geographies from which you or your users may access your data. +Microsoft doesn't control or limit the locations from which you or your users can access your data. > [!NOTE] -> Because there's only one region in Brazil, customer data is replicated to south-central United States for disaster recovery and load balancing purposes. For more information, see [Data residency in Azure](https://azure.microsoft.com/global-infrastructure/data-residency/). +> Because there's only one region in Brazil, customer data in Brazil is replicated to the South Central US region for disaster recovery and load balancing. For more information, see [Data residency in Azure](https://azure.microsoft.com/global-infrastructure/data-residency/). ## Related articles diff --git a/docs/organizations/security/data-protection.md b/docs/organizations/security/data-protection.md index 1ce7c89ae31..f5c6e1b7893 100644 --- a/docs/organizations/security/data-protection.md +++ b/docs/organizations/security/data-protection.md @@ -8,90 +8,89 @@ ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.reviewer: jominana -ms.date: 05/17/2023 +ms.date: 02/17/2025 monikerRange: 'azure-devops' --- - # Data protection overview [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Azure DevOps Services is a cloud-hosted application for your development projects, from planning through deployment. Based on the on-premises capabilities, with additional cloud services, we manage your source code, work items, builds, and tests. Azure DevOps uses platform as a service (PaaS) infrastructure and many Azure services, including Azure SQL, to deliver a reliable, globally available service for your development projects. +Azure DevOps Services is a cloud-hosted application for your development projects, from planning through deployment. Based on the on-premises capabilities, with more cloud services, we manage your source code, work items, builds, and tests. Azure DevOps uses platform as a service (PaaS) infrastructure and many Azure services, including Azure SQL, to deliver a reliable, globally available service for your development projects. -This article discusses the steps that Microsoft takes to help keep your projects safe, available, secure, and private. Also, it describes the role you play in keeping your projects safe and secure. +This article discusses the steps that Microsoft takes to help keep your projects safe, available, secure, and private. It describes the role that you play in keeping your projects safe and secure. -This article is intended for organization administrators and IT professionals who manage their project assets daily. It will be most useful to individuals who are already familiar with Azure DevOps and want to know more about how Microsoft protects stored assets in Azure DevOps. +This article is for organization administrators and IT professionals who manage their project assets daily. It's most useful to individuals who are already familiar with Azure DevOps and want to know more about how Microsoft protects stored assets in Azure DevOps. ## Our commitment Microsoft helps to ensure that your projects remain safe -and secure, without exception. When stored in Azure DevOps, your projects benefit -from multiple layers of security and governance technologies, -operational practices, and compliance policies. We enforce data privacy -and integrity both at rest and in transit. +and secure, without exception. When you store your projects in Azure DevOps, they benefit from multiple layers of security and governance technologies, operational practices, and compliance policies. We enforce data privacy and integrity both at rest and in transit. -The threats you face boil down to four basic categories: data availability, service -availability, service security, and data privacy. This article explores specific threats within each category, and explains what Azure DevOps does to address them. First, the article describes how data is stored and how Azure DevOps manages access to your data. +The threats that you face are in four basic categories: data availability, service availability, service security, and data privacy. This article explores specific threats within each category and explains what Azure DevOps does to address them. The article begins by describing how data is stored and how Azure DevOps manages access to your data. -Data protection requires active engagement of administrators and users, who must know what steps to take -to protect your assets from unauthorized disclosure and tampering. Be explicit when you grant permissions to user access points, so only the right people are accessing data within Azure DevOps. +Data protection requires the active engagement of administrators and users who know what steps to take to protect your assets from unauthorized disclosure and tampering. Be explicit when you grant permissions to user access points, so only the right people access data within Azure DevOps. -Whatever your approach, you should consider all data potentially -"at risk," no matter where it is or how it's being used. This is true -for both data in the cloud and data stored in a private -data center. It's important to classify your data, its sensitivity and risk, and the damage it might do if it becomes compromised. Also, categorize your data relative to an overall information security management policy. +You should consider all data to be potentially at risk, no matter where it's located or how it's being used. This statement is true for both data stored in the cloud and data stored in a private datacenter. It's important to classify your data, its sensitivity and risk, and the damage that it might do if it becomes compromised. Also, categorize your data relative to an overall policy for managing information security. ## Built on Azure -![Diagram of Azure DevOps high-level architecture.](media/data-protection/Figure1_VSOArchitecture.png) +![Diagram of the high-level architecture of Azure DevOps.](media/data-protection/Figure1_VSOArchitecture.png) + +We host Azure DevOps entirely in Azure datacenters. Azure DevOps uses many core Azure services, including compute, storage, networking, Azure SQL, identity and access management, and Azure Service Bus. -We host Azure DevOps entirely in Azure data centers. Azure DevOps uses many core Azure services, including compute, storage, networking, Azure SQL, identity and access management, and Azure Service Bus. +Azure DevOps uses Azure Storage as the primary repository for service metadata and customer data. Depending on the type of data and the storage and retrieval requirements, Azure DevOps uses Azure Blob Storage and Azure SQL Database storage. -Azure DevOps uses Azure Storage as the primary repository for service metadata and customer data. Depending on the type of data and the storage and retrieval needs, Azure DevOps uses Azure Blob Storage (for binary large objects) and Azure SQL data storage. To understand the Azure DevOps Services approach to data protection, some background on these elements is important. +To help you understand the Azure DevOps Services approach to data protection, here's some background on the storage services: -- **Azure Blob Storage** stores large chunks of unstructured data. All projects use the Azure Blob Storage service. Data includes potentially sensitive or private information, like the contents of source files and attachments for work items. For most projects, the majority of storage in use is this type of unstructured blob storage. For more information, see [Azure Blob Storage](/azure/storage/blobs/storage-quickstart-blobs-dotnet). +- [Azure Blob Storage](/azure/storage/blobs/storage-quickstart-blobs-dotnet) stores large chunks of unstructured data. All projects use this service. Data includes potentially sensitive or private information, like the contents of source files and attachments for work items. For most projects, most storage in use is this type of unstructured blob storage. -- **Azure SQL Database storage** stores the structured and transactional aspects of your organization, including project metadata, the versioned source control history, and work item details. Database storage gives you fast access to the important elements of your project, and provides indexes into the blob storage to look up files and attachments. For more information, see [Azure SQL Database](/azure/azure-sql/database). +- [Azure SQL Database](/azure/azure-sql/database) stores the structured and transactional aspects of your organization, including project metadata, the versioned source-control history, and details of work items. Database storage gives you fast access to the important elements of your project. It provides indexes into the blob storage to look up files and attachments. -Administrators can manage access to resources by [granting or restricting permissions](/previous-versions/azure/devops/reference/process-templates/configure-initial-groups-teams-members-permissions) on user identities or groups. Azure DevOps uses federated authentication of user identities via [Azure Active Directory](../accounts/access-with-azure-ad.md) (Azure AD) and Microsoft accounts. +Administrators can manage access to resources by [granting or restricting permissions](/previous-versions/azure/devops/reference/process-templates/configure-initial-groups-teams-members-permissions) on user identities or groups. Azure DevOps uses federated authentication of user identities via [Microsoft Entra ID](../accounts/access-with-azure-ad.md) and Microsoft accounts. -During authentication, the user is routed to the authentication provider, where they provide their credentials. After the authentication provider has verified the user's credentials, Azure DevOps issues an authentication cookie to the user, which allows the user to remain authenticated against Azure DevOps. +During authentication, the user is routed to the authentication provider, where they provide their credentials. After the authentication provider verifies the user's credentials, Azure DevOps issues an authentication cookie to the user. This cookie allows the user to remain authenticated against Azure DevOps. -In this way, the user's credential information is never shared directly with Azure DevOps. For each Azure DevOps resource that the user attempts to access, permissions are validated based on the user's explicit permissions, as well as permissions inherited through group membership. Administrators can use access controls to protect [access to the organization](../accounts/connect-organization-to-azure-ad.md), project collections, team projects, and team-scoped data and functionality. Administrators can also protect more specific assets like version control folders and work item area paths. +In this way, the user's credential information is never shared directly with Azure DevOps. For each Azure DevOps resource that the user tries to access, validation of permissions is based on the user's explicit permissions and on permissions that the user inherited through group membership. + +Administrators can use access controls to help protect [access to the organization](../accounts/connect-organization-to-azure-ad.md), project collections, team projects, and team-scoped data and functionality. Administrators can also use access controls for specific assets like folders for version control and area paths for work items. ## Data availability -Azure DevOps uses many Azure Storage features to ensure data availability if there's a hardware failure, service disruption, or region disaster. Also, the Azure DevOps team follows procedures to protect data from accidental or malicious deletion. +Azure DevOps uses many Azure Storage features to help ensure data availability if there's a hardware failure, service disruption, or regional disaster. Also, the Azure DevOps team follows procedures to help protect data from accidental or malicious deletion. ### Data redundancy -To protect data during hardware or service failures, Azure Storage geo-replicates customer data between two regions in the same geography. For example, Azure can geo-replicate data between North and West Europe or between North and South United States. +To help protect data during hardware or service failures, Azure Storage geo-replicates customer data between two regions in the same geographical location. For example, Azure Storage can geo-replicate data between North and West Europe or between North and South United States. -For Azure Blob Storage, customer data gets replicated three times within a single region, and is replicated asynchronously to a second region in the same geography. As such, Azure always maintains the equivalent of six copies of your data. This enables you to fail over to a separate region if there's a major outage or disaster, while also having local redundancy for hardware failures within a region. For Azure SQL Database storage, daily backups are maintained offsite if there's a regional disaster. +For Azure Blob Storage, customer data is replicated three times within a single region. Customer data is replicated asynchronously to a second region in the same geographical location. As such, Azure always maintains the equivalent of six copies of your data. -> [!NOTE] -> Regarding data redundancy and failover: -> * There's an inherent delta, measured in minutes, when Microsoft replicates your data between the primary and secondary region. -> * Failover to the secondary region is a decision that Microsoft must make centrally, as it affects all customers on the affected scale unit. Except in extreme circumstances, Microsoft opts to not fail over so that customer data isn't lost. -> * Azure DevOps offers a 99.9 percent uptime SLA guarantee, and refunds a portion of the monthly charges if that SLA is missed in a specific month. -> * Because there is only one region in Brazil, customer data in Brazil is replicated to the South Central US region for disaster recovery purposes. +Having multiple copies enables you to fail over to a separate region if there's a major outage or disaster, while also having local redundancy for hardware failures within a region. For Azure SQL Database storage, daily backups are maintained offsite if there's a regional disaster. + +Regarding data redundancy and failover: + +- There's an inherent delta, measured in minutes, when Microsoft replicates your data between the primary and secondary region. +- Failover to the secondary region is a decision that Microsoft must make centrally, because it affects all customers on a particular scale unit. Except in extreme circumstances, Microsoft opts to avoid failing over so that customer data isn't lost. +- Azure DevOps offers a service-level agreement (SLA) of 99.9 percent uptime. Azure DevOps refunds a portion of the monthly charges if it misses that SLA in a specific month. +- Because there's only one region in Brazil, customer data in Brazil is replicated to the South Central US region for disaster recovery purposes. ### Mistakes happen -To protect against accidental deletion of data, Microsoft also takes point-in-time backups of both the blobs in Azure Blob Storage, and the databases in Azure SQL Database. There's a separate copy of all blobs, and changes are appended to each storage account. Because this data is immutable, you don't need to rewrite any existing storage as part of the backup procedures. +To safeguard against accidental data loss, Microsoft employs point-in-time backups for both blobs stored in Azure Blob Storage and databases within Azure SQL Database. Each storage account maintains a separate copy of all blobs, with changes being appended to the existing data. These backups are immutable, eliminating the need to rewrite any existing storage during backup procedures. -Backups are a standard part of Azure SQL Database, and Azure DevOps makes use of this. We maintain 28 days' worth of your data. In both cases, these backups are also replicated in a paired region, helping to ensure that we recover from a regional outage. +Azure SQL Database includes standard backup features utilized by Azure DevOps. Your data is retained for 28 days, with these backups also being replicated in a paired region to facilitate recovery during a regional outage. -A further protection is that customers can recover their deleted organizations or projects for up to 28 days after deletion. Deleted organizations and projects are in a "soft deleted" stage for 28 days allowing customers to recover as needed. After 28 days they are permanently deleted and cannot be restored. +You can recover deleted organizations or projects within the 28-day window following deletion. But, once this time period elapses, these entities are permanently deleted and can't be restored. While these backups serve as a crucial component for disaster recovery, it's essential for customers to practice appropriate data management and backup strategies to ensure comprehensive protection of their data. >[!IMPORTANT] -> Accidental deletion here refers to scenarios that arise as a result of an incident on our services and doesn't include accidental deletion of assets (e.g., repositories, work items, attachments, artifacts) by customers. We do not support restoring assets that are accidently deleted by customers as these backups are meant for business continuity and aid recovery from outage or disaster scenarios only. +> - *Accidental deletion* here refers to scenarios that arise as a result of an incident on our services. It doesn't include customers' accidental deletion of assets (for example, repositories, work items, attachments, or artifacts). +> - We don't support restoring assets that customers accidentally delete. These backups are meant only for business continuity and to aid recovery from outage or disaster scenarios. +> - In rare cases, our deletion process might take up to 70 days due to backend retries and the need to delete data from multiple sources. ### Practice is critical -Having multiple, redundant backups of your data is good but without practice, restoring can be unpredictable. It's been said that "backups never fail, the restores do." While technically incorrect, the sentiment is right. +Having multiple backups of your data is good, but without practice, restoring can be unpredictable. People say that "backups never fail; the restores do." Though the statement is technically incorrect, the sentiment is right. -Microsoft regularly practices restoring various datasets from backup. Geo-redundant storage from Azure is tested regularly. There are many combinations of disaster and data corruption scenarios, which we continue to plan and run new tests for regularly. +Microsoft regularly practices restoring datasets from backup. We regularly test geo-redundant storage from Azure. There are many combinations of disaster and data corruption scenarios. We continue to plan and run new tests for these scenarios regularly. ## Service availability @@ -99,225 +98,262 @@ Azure DevOps offers distributed denial-of-service (DDoS) protections and live si ### DDoS protections -In some cases, a malicious DDoS attack can affect service availability. Azure has a DDoS defense system that helps prevent attacks against our service. It uses standard detection and mitigation techniques such as SYN cookies, rate limiting, and connection limits. The system is designed to withstand attacks not only from the outside but also from within Azure. +In some cases, a malicious DDoS attack can affect service availability. Azure has a DDoS defense system that helps prevent attacks against our service. It uses standard detection and mitigation techniques such as SYN cookies, rate limiting, and connection limits. The system is designed to withstand attacks not only from the outside but also from within Azure. -For application-specific attacks that can penetrate the Azure defense systems, Azure DevOps establishes application and organization level quotas and throttling. This helps prevent any overuse of key service resources during an attack or accidental misuse of resources. +For application-specific attacks that can penetrate the Azure defense systems, Azure DevOps establishes application-level and organization-level quotas and throttling. This practice helps prevent any overuse of key service resources during an attack or accidental misuse of resources. ### Live site response -In rare circumstances, you might require a live site response to a problem with service availability. We have an operations team available 24x7, to rapidly identify the issue and to engage the necessary development team resources. Those resources then address the problem. They also aim to update the service status page within minutes of detecting an issue that affects the service. After the team has addressed an issue, they identify the root cause of the issue and track the necessary changes to prevent similar issues in the future. +In rare circumstances, you might require a live site response to a problem with service availability. We have an operations team that's constantly available to rapidly identify the problem and to engage the necessary development team resources. + +The development team resources then address the problem. They also aim to update the service status page within minutes of detecting a problem that affects the service. After development team resources address a problem, they identify the root cause and track the necessary changes to prevent similar problems in the future. -Azure DevOps live site management processes focus on your experience and the health of your service. These processes minimize the time to detect, respond to, and mitigate problems. All engineering disciplines are involved and responsible, so there are continual improvements evolving out of direct experience. This means that monitoring, diagnostics, resiliency, and quality assurance processes improve over time. +Azure DevOps processes for live site management focus on your experience and the health of the service. These processes minimize the time to detect, respond to, and mitigate problems. All engineering disciplines are involved and responsible, so continual improvements evolve out of direct experience. Monitoring, diagnostics, resiliency, and quality assurance processes then improve over time. Live site management in Azure DevOps has three distinct tracks: telemetry, incident management, and live site review. Here's what these tracks entail: -![Image of the Azure DevOps Services live site management process.](media/data-protection/figure-2-site-management-process.png) +![Image of the Azure DevOps Services process for live site management.](media/data-protection/figure-2-site-management-process.png) The operations team also monitors the availability metrics for individual organizations. These metrics provide insights into specific conditions that might affect only some of our customers. Investigations into this data can often result in targeted improvements to address customer-specific issues. In some cases, Microsoft might even contact you directly to understand your experience and work with you to improve the service. -Microsoft publishes a service-level agreement (SLA) and provides a financial guarantee to ensure that we meet this agreement each month. For more information, see [SLA for Azure DevOps](https://azure.microsoft.com/support/legal/sla/azure-devops/v2_1/). +Microsoft publishes an SLA and provides a financial guarantee to ensure that we meet this agreement each month. For more information, see [SLA for Azure DevOps](https://azure.microsoft.com/support/legal/sla/azure-devops/v2_1/). -Sometimes partner teams or dependencies have incidents that affect Azure DevOps. All partner teams follow similar approaches to identifying, resolving, and learning from these service outages. +Sometimes, partner teams or dependencies have incidents that affect Azure DevOps. All partner teams follow similar approaches to identifying, resolving, and learning from these service outages. ## Service security Service security requires constant vigilance, from proper design and coding techniques to operational factors. Microsoft actively invests in the prevention of security holes and in breach detection. If there's a breach, Microsoft uses security response plans to minimize data leakage, loss, or corruption. For more information, see [About security, authentication, and authorization](about-security-identity.md). -### Secure by design +### Security by design -Azure DevOps is designed to be secure. Azure DevOps uses the Microsoft Security Development Lifecycle at the core of its development process. The Microsoft Operational Security Assurance program guides its cloud operation procedures. The following methodologies specify the following requirements: +Azure DevOps is designed to be secure. Azure DevOps uses the Microsoft Security Development Lifecycle at the core of its development process. The Microsoft Operational Security Assurance program guides cloud operation procedures in Azure DevOps. -- Threat modeling during service design. -- Following design and code best practices. -- Verifying security with standard tooling and testing. -- Limiting access to operational and customer data. -- Gating rollout of new features through a rigid approval process. +The Azure DevOps team has annual training requirements for all engineers and operations personnel. The team also sponsors informal meetings hosted by Microsoft engineers. After the team solves a problem that surfaces in a meeting, it shares the lessons learned with other teams. -The Azure DevOps team has annual training requirements for all engineers and operations personnel, and sponsors informal "brown bag" meetings hosted by Microsoft engineers. After they've solved an issue raised in a brown bag meeting, they share what they learned with the rest of the team. +The following methodologies specify the training requirements: -A cloud service is only as secure as the host platform. Azure DevOps uses PaaS for much of its infrastructure. PaaS automatically provides regular updates for known security vulnerabilities. VMs hosted in Azure use infrastructure as a service (IaaS), such as for a [hosted build service](../../pipelines/agents/hosted.md). Such images receive regular updates to include the latest security patches available from Windows Update. The same update rigor applies for on-premises machines, including those used for deployment, monitoring, and reporting. +- Threat modeling during service design +- Following best practices for design and code +- Verifying security with standard tooling and testing +- Limiting access to operational and customer data +- Gating rollout of new features through a rigid approval process -The Azure DevOps team conducts regular, security-focused penetration testing of Azure DevOps. Using the same techniques and mechanisms as malicious attackers, penetration testing tries to exploit the live production services and infrastructure of Azure DevOps. The goal is to identify real-world vulnerabilities, configurations, errors, or other security gaps in a controlled process. The team reviews the results to identify other areas of improvement and to increase the quality of the preventative systems and training. You can review the results of recent Azure DevOps penetration tests on the [Service Trust Portal](https://servicetrust.microsoft.com/ViewPage/TrustDocumentsV3?command=Download&downloadType=Document&downloadId=ce44654a-f397-4aab-a45c-876fe4dd9cbf&tab=7f51cb60-3d6c-11e9-b2af-7bb9f5d2d913&docTab=7f51cb60-3d6c-11e9-b2af-7bb9f5d2d913_Pen_Test_and_Security_Assessments). +A cloud service is only as secure as the host platform. Azure DevOps uses PaaS for much of its infrastructure. PaaS automatically provides regular updates for known security vulnerabilities. + +Virtual machines hosted in Azure use infrastructure as a service (IaaS), such as for a [hosted build service](../../pipelines/agents/hosted.md). Such images receive regular updates to include the latest security patches available from Windows Update. The same update rigor applies for on-premises machines, including those machines used for deployment, monitoring, and reporting. + +The Azure DevOps team conducts regular, security-focused penetration testing of Azure DevOps. Penetration testing tries to exploit the live production services and infrastructure of Azure DevOps by using the same techniques and mechanisms that malicious attackers use. The goal is to identify real-world vulnerabilities, configurations, errors, or other security gaps in a controlled process. + +The team reviews the results of these tests to identify other areas of improvement and to increase the quality of the preventative systems and training. You can review the results of recent Azure DevOps penetration tests on the [Microsoft Service Trust Portal](https://servicetrust.microsoft.com/ViewPage/TrustDocumentsV3?command=Download&downloadType=Document&downloadId=ce44654a-f397-4aab-a45c-876fe4dd9cbf&tab=7f51cb60-3d6c-11e9-b2af-7bb9f5d2d913&docTab=7f51cb60-3d6c-11e9-b2af-7bb9f5d2d913_Pen_Test_and_Security_Assessments). ### Credential security -Your credentials in Azure DevOps are stored using industry best practices. Learn more about [credential storage](credential-storage.md). +Microsoft is committed to ensuring that your projects remain safe and secure, without exception. In Azure DevOps, your projects benefit from multiple layers of security and governance technologies, operational practices, and compliance policies. We enforce data privacy and integrity both at rest and in transit. In addition, we adhere to the following practices with respect to the credentials or secrets that Azure DevOps stores. To learn more about how to choose the right authentication mechanism, see [Guidance for authentication](../../integrate/get-started/authentication/authentication-guidance.md). -### Reporting security issues +[!INCLUDE [alt-creds-deprecation-notice](../../includes/alt-creds-deprecation-notice.md)] -If during your penetration testing you believe you've discovered a potential security flaw related to the Azure DevOps service, report it to Microsoft within 24 hours. For more information, see [Report a computer security vulnerability](https://technet.microsoft.com/organizations/security/ff852094). +#### Personal access tokens (PATs) ->[!IMPORTANT] ->Although notifying Microsoft of penetration testing activities is no longer required, you must still comply with the [Microsoft Cloud Unified Penetration Testing Rules of Engagement](https://technet.microsoft.com/mt784683). +* We store a hash of the PAT. +* Raw PATs generate in-memory on the server side. 32 bytes randomly generate through the RNGCryptoServiceProvider and get shared with the caller as a base-32-encoded string. This value is NOT stored. +* PAT hash generates in-memory on the server side as an *HMACSHA256Hash* of the raw PAT using a 64-byte symmetric signing key stored in our key vault. +* Hash gets stored in our database. + +#### Secure shell (SSH) keys + +* We store a hash of the enclosing organization ID and the SSH public key. +* Raw public keys get provided directly by the caller over SSL. +* SSH hash generates in-memory on the server side as an *HMACSHA256Hash* of the organization ID and raw public key using a 64-byte symmetric signing key stored in our key vault. +* Hash gets stored in our database. + +#### OAuth credentials (JWTs) + +* OAuth credentials issue as fully self-describing JSON web tokens (JWTs) and aren't stored in our service. +* The claims in JWTs issued and presented to our service get validated using a certificate stored in our key vault. + +### Reporting security flaws + +If you believe that your penetration testing revealed a potential security flaw related to the Azure DevOps service, report it to Microsoft within 24 hours. For more information, see the [Microsoft webpage for reporting a computer security vulnerability](https://technet.microsoft.com/organizations/security/ff852094). + +> [!IMPORTANT] +> Although you don't need to notify Microsoft about penetration testing activities, you must comply with the [Microsoft Penetration Testing Rules of Engagement](https://technet.microsoft.com/mt784683). ### Bounty program -Azure DevOps participates in the [Microsoft Online Services Bounty Program](https://www.microsoft.com/msrc/bounty-microsoft-cloud). This program rewards security researchers who report issues to us, and encourages more people to help keep Azure DevOps secure. For more information, see the [Azure DevOps Bounty Program](https://www.microsoft.com/msrc/bounty-azure-devops). +Azure DevOps participates in the Microsoft Bug Bounty program. This program rewards security researchers who report problems to us, and it encourages more people to help keep Azure DevOps secure. For more information, see [Microsoft Azure DevOps Bounty Program](https://www.microsoft.com/msrc/bounty-azure-devops). ### Restricting access -Microsoft maintains strict control over who gets access to our production environment and customer data. Access gets granted at the level of least privilege that's required and only after proper justifications get provided and verified. If a team member needs access to resolve an urgent issue or deploy a configuration change, they must apply for "just-in-time" access to the production service. Access is revoked as soon as the situation is resolved. +Microsoft maintains strict control over who gets access to our production environment and customer data. We grant access at the level of least privilege required, and only after verification of a user's justifications. If a team member needs access to resolve an urgent problem or deploy a configuration change, they must apply for just-in-time access to the production service. Access is revoked as soon as the situation is resolved. -Access requests and approvals get tracked and monitored in a separate system. All access to the system correlates against these approvals and if we detect unapproved access, the operations team gets alerted to investigate. +We track and monitor access requests and approvals in a separate system. All access to the system correlates against these approvals. If we detect unapproved access, we alert the operations team to investigate. -We use two-factor authentication for all remote system access. So, if the username and password for one of our developers or operation staff got stolen, the data remains protected. This means additional authentication checks via smart card or a phone call to a pre-approved number must occur before any remote access to the service is permitted. +We use two-factor authentication for all remote system access. If the username and password for one of our developers or operations staff are stolen, the data remains protected. More authentication checks via smart card or a phone call to a preapproved number must occur before we permit any remote access to the service. -In addition, Microsoft uses secrets to manage and maintain the service, such as RDP passwords, SSL certificates, and encryption keys. These are all managed, stored, and transmitted securely through the Azure portal. Any access to these secrets requires specific permission, which is logged and recorded in a secure manner. All secrets are rotated on a regular cadence, and can be rotated on-demand if there's a security event. +To manage and maintain the service, Microsoft uses secrets such as RDP passwords, SSL certificates, and encryption keys. These secrets are all managed, stored, and transmitted securely through the Azure portal. Any access to these secrets requires specific permission, which is logged and recorded securely. All secrets are rotated on a regular cadence, and we can rotate them on demand if there's a security event. -The Azure DevOps operations team uses hardened administrator workstations to manage the service. These machines run a minimal number of applications and operate in a logically segmented environment. Operations team members must provide specific credentials with two-factor authentication to access the workstations. All access is monitored and securely logged. To isolate the service from outside tampering, we don't permit applications such as Outlook and Office, as they're often targets of spear-phishing and other types of attacks. +The Azure DevOps operations team uses hardened administrator workstations to manage the service. These machines run a minimal number of applications and operate in a logically segmented environment. -### Intrusion protection and response +Operations team members must provide specific credentials with two-factor authentication to access the workstations. All access is monitored and securely logged. To isolate the service from outside tampering, we don't permit applications such as Outlook and Office, because they're often targets of spear phishing and other types of attacks. -We encrypt data via HTTPS and SSL to ensure it isn't intercepted or modified while in transit between you and Azure DevOps. +### Intrusion protection and response -Also, data we store on your behalf in Azure DevOps gets encrypted as follows: +We encrypt data via HTTPS and SSL to help ensure that it isn't intercepted or modified while in transit between you and Azure DevOps. Data that we store on your behalf in Azure DevOps is encrypted as follows: -* Data stored in Azure SQL databases gets encrypted using [Transparent Data Encryption (TDE)](/sql/relational-databases/security/encryption/transparent-data-encryption). TDE protects against the threat of malicious activity by doing real-time encryption of the database, associated backups, and transaction log files at rest. +- Data stored in Azure SQL databases is encrypted via [transparent data encryption](/sql/relational-databases/security/encryption/transparent-data-encryption). This feature helps protect against malicious activity by doing real-time encryption of the database, associated backups, and transaction log files at rest. -* Azure Blob Storage connections get encrypted to protect your data in transit. To protect data at rest stored in Azure Blob Storage, Azure DevOps uses [Azure Storage Service Encryption (SSE)](/azure/storage/common/storage-service-encryption). +- Azure Blob Storage connections are encrypted to help protect your data in transit. For data at rest stored in Azure Blob Storage, Azure DevOps uses [service-side encryption](/azure/storage/common/storage-service-encryption). -> [!NOTE] -> Azure DevOps is not Federal Information Processing Standards (FIPS) 140-2 or 140-3 compliant. +The Azure DevOps team uses the Azure infrastructure to log and monitor key aspects of the service. Logging and monitoring help ensure that activities within the service are legitimate, and they help detect breaches or attempted breaches. -The Azure infrastructure helps the Azure DevOps team to log and monitor key aspects of the service. This helps ensure that activities within the service are legitimate, and detects breaches or attempted breaches. In addition, all deployment and administrator activities are securely logged, as is operator access to production storage. Real-time alerts are raised because the log information is automatically analyzed to uncover potentially malicious or unauthorized behavior. +All deployment and administrator activities are securely logged, as is operator access to production storage. The log information is automatically analyzed, and any potentially malicious or unauthorized behavior raises real-time alerts. -Where a possible intrusion or high priority security vulnerability gets identified, the team has a clear response plan. This plan outlines responsible parties, steps required to secure customer data, and how to engage with security experts at Microsoft. The team also notifies any organization owners if data was disclosed or corrupted, so that they can take appropriate steps to remedy the situation. +When the Azure DevOps team identifies a possible intrusion or high-priority security vulnerability, it has a clear response plan. This plan outlines responsible parties, required steps for securing customer data, and instructions on how to engage with security experts at Microsoft. The team also notifies any organization owners if data was disclosed or corrupted, so that they can take appropriate steps to remedy the situation. -Finally, to help combat emerging threats, Azure DevOps employs an "Assume Breach" strategy. A highly specialized group of security experts within Microsoft, known as the Red Team, assumes the role of sophisticated adversaries. This team tests breach detection and response, to accurately measure readiness and the impacts of real-world attacks. This strategy strengthens threat detection, response, and defense of the service. It also allows the team to validate and improve the effectiveness of the entire security program. +To help combat emerging threats, Azure DevOps employs an *assume breach* strategy. A highly specialized team of security experts within Microsoft assumes the role of sophisticated adversaries. This team tests breach detection and response, to accurately measure readiness and the impacts of real-world attacks. This strategy strengthens threat detection, response, and defense of the service. It also allows the team to validate and improve the effectiveness of the entire security program. -### Ransomware attack protection overview +### Ransomware attack protection -Azure DevOps is built on Azure and uses Azure's best-in-class controls to help prevent, detect, and respond to a ransomware attack. For more information about how Azure protects customers from ransomware attacks, see [Azure defenses for ransomware attack](https://azure.microsoft.com/resources/azure-defenses-for-ransomware-attack/). +Azure DevOps uses Azure controls to help prevent, detect, and respond to a ransomware attack. For more information about how Azure helps protect customers from ransomware attacks, see [Ransomware protection in Azure](/azure/security/fundamentals/ransomware-protection). ## Data privacy -You should have confidence that your data is being handled appropriately and for legitimate uses. Part of that assurance involves appropriately restricting usage so that your data is used only for legitimate reasons. +You should have confidence that we're handling your data appropriately and for legitimate uses. Part of that assurance involves carefully restricting usage. -### General Data Protection Regulation (GDPR) +### General Data Protection Regulation -The General Data Protection Regulation (GDPR) is the biggest change in data protection laws in Europe since the 1995 introduction of the European Union (EU) Data Protection Directive 95/46/EC. For more information about the GDPR regulation, see the [overview page in the Microsoft Trust Center](https://www.microsoft.com/TrustCenter/Privacy/gdpr/default.aspx). +The General Data Protection Regulation (GDPR) is the biggest change in data protection laws in Europe since the 1995 introduction of the European Union (EU) Data Protection Directive 95/46/EC. For more information about GDPR, see the [overview page in the Microsoft Trust Center](https://www.microsoft.com/TrustCenter/Privacy/gdpr/default.aspx). ### Data residency and sovereignty -Azure DevOps is available in the following eight geographies across the world: United States, Canada, Europe, United Kingdom, India, Australia, Asia Pacific, and Brazil. By default, your organization is assigned to your closest geography, but you do have the option to choose a different geography. If you change your mind later, it's possible to migrate your organization to a different geography, with the assistance of Microsoft support. +Azure DevOps is available in the following eight geographical locations across the world: United States, Canada, Europe, United Kingdom, India, Australia, Asia Pacific, and Brazil. By default, your organization is assigned to your closest location. However, you can choose a different location when you create your organization. If you change your mind later, you can migrate the organization to a different location with the assistance of Microsoft support. -Azure DevOps doesn't move or replicate customer data outside of the chosen geography. Instead, your data is geo-replicated to a second region within the same geography. The only exception is Brazil, which replicates data to the South Central US geography for disaster recovery purposes. +Azure DevOps doesn't move or replicate customer data outside the chosen location. Instead, your data is geo-replicated to a second region within the same location. The only exception is Brazil, which replicates data to the South Central US region for disaster recovery purposes. > [!NOTE] -> For builds and releases running on Microsoft-provided macOS agents, your data will be transferred to a GitHub data center in the US. +> For builds and releases that run on Microsoft-provided macOS agents, your data is transferred to a GitHub datacenter in the United States. -To learn more, see [Azure DevOps data location](data-location.md). +For more information, see [Data locations for Azure DevOps](data-location.md). ### Law enforcement access -In some cases, third parties such as law enforcement entities might approach Microsoft to obtain access to customer data stored within Azure DevOps. We attempt to redirect the requests to the organization owner for resolution. When compelled by court order to disclose customer data to a third party, Microsoft makes a reasonable effort to notify the organization owner in advance, unless we’re legally prohibited from doing so. +In some cases, third parties such as law enforcement entities might approach Microsoft to obtain access to customer data stored in Azure DevOps. We try to redirect the requests to the organization owner for resolution. When a court order compels Microsoft to disclose customer data to a third party, Microsoft makes a reasonable effort to notify the organization owner in advance, unless we're legally prohibited from doing so. -Some customers require their data storage in a particular geographic location to ensure a specific legal jurisdiction for any law enforcement activities. All customer data, such as source code, work items, test results, and geo-redundant mirrors and offsite backups, get maintained within one of the previously mentioned geographies. +Some customers require their data storage in a particular geographical location to ensure a specific legal jurisdiction for any law enforcement activities. All customer data, such as source code, work items, test results, and geo-redundant mirrors and offsite backups, is maintained within one of the previously mentioned locations. ### Microsoft access -From time to time, Microsoft employees need to obtain access to customer data stored within Azure DevOps. As a precaution, all employees who have or might ever have access to customer data must pass a background check, which verifies previous employment and criminal convictions. We permit access to the production systems only when there's a live site incident or other approved maintenance activity, which gets logged and monitored. +From time to time, Microsoft employees need to obtain access to customer data stored in Azure DevOps. As a precaution, all employees who have (or might ever have) access to customer data must pass a background check that includes previous employment and criminal convictions. We permit access to the production systems only when there's a live site incident or other approved maintenance activity, which is logged and monitored. -Because not all data within our system gets treated the same, we classify data to distinguish between the following data types: +Because not all data within our system is treated the same way, we classify data into these types: -- Customer data - what you upload to Azure DevOps. -- Organization data - information used when you sign up for or administer your organization. -- Microsoft data - information required for or collected through the operation of the service. +- **Customer data**: What you upload to Azure DevOps. +- **Organization data**: Information that you submit when you sign up for or administer your organization. +- **Microsoft data**: Information required for or collected through the operation of the service. Based on the classification, we control usage scenarios, geo-location requirements, access restrictions, and retention requirements. ### Microsoft promotional use -Microsoft occasionally wants to contact customers to let them know about additional features and services that might be useful. Because not all customers want to be contacted about these offers, you can opt in and opt out of marketing email communications. +Microsoft occasionally wants to contact customers to let them know about more features and services that might be useful. Because not all customers want to be contacted about these offers, you can opt in and opt out of marketing email communications. Microsoft never uses customer data to target specific offers for specific users or organizations. Instead, we use organization data and aggregate usage statistics at the organization level to determine groups that should receive specific offers. +### Managing privacy policies for admins to control user feedback collection + +The feedback toggle feature allows Azure DevOps organization owners to control whether users are prompted to provide feedback and submit it. This feature is essential for ensuring that feedback practices align with your organization’s privacy and governance policies. + ## Building confidence -You can be confident in other efforts Microsoft makes on behalf of Azure DevOps. These efforts include internal adoption policies at Microsoft, the level of transparency provided into the state of our service, and progress towards receiving certification of our information security management systems. +You can be confident in other efforts that Microsoft makes on behalf of Azure DevOps. These efforts include internal adoption policies at Microsoft, the level of transparency into the state of our service, and progress toward receiving certification of our systems for managing information security. ### Internal adoption -Teams across Microsoft are adopting Azure DevOps internally. The Azure DevOps team moved into an organization in 2014 and uses it extensively. More broadly, we have established guidelines to enable the adoption plans for other teams. +Microsoft teams are adopting Azure DevOps internally. The Azure DevOps team moved into an organization in 2014 and uses it extensively. We established guidelines to enable the adoption plans for other teams. -Obviously, large teams move more gradually than smaller ones, given their investments in existing DevOps systems. For teams able to move quickly, we have established a project classification approach. It assesses risk tolerance, based on project characteristics, to determine if the project is appropriate for Azure DevOps. For larger teams, the adoption typically occurs in phases, with more planning. +Large teams move more gradually than smaller ones, because of their investments in existing DevOps systems. For teams that move quickly, we established a project classification approach. It assesses risk tolerance, based on project characteristics, to determine if the project is appropriate for Azure DevOps. For larger teams, the adoption typically occurs in phases, with more planning. -Additional requirements for internal projects include associating the organization with Azure AD to ensure proper user identity life cycle and password complexity. For more sensitive projects, two-factor authentication is also required. +More requirements for internal projects include associating the organization with Microsoft Entra ID to ensure the proper user-identity lifecycle and password complexity. Projects that are more sensitive also require two-factor authentication. ### Compliance certifications -Some of you want to understand third-party -evaluation of our data security procedures. Azure DevOps has achieved the following certifications: +You might be interested in understanding third-party evaluation of our procedures for data security. Azure DevOps achieved the following certifications: - ISO 27001:2013 - ISO 27018:2019 -- HIPAA (Health Insurance Portability and Accountability Act) -- BAA (Business Associate Agreement) +- ISO 26262:2023 +- Health Insurance Portability and Accountability Act (HIPAA) +- Business Associate Agreement (BAA) - EU Model Clauses -- SOC 1 Type 2 +- System and Organization Controls (SOC) 1 Type 2 - SOC 2 Type 2 -- Germany C5 +- Germany C5 +- Australia IRAP +- ENS-Spain -The SOC audit for Azure DevOps covers controls for data security, availability, -processing integrity, and confidentiality. The SOC reports for Azure DevOps are available through the [Microsoft Service Trust Portal](https://servicetrust.microsoft.com/ViewPage/MSComplianceGuide?docTab=4ce99610-c9c0-11e7-8c2c-f908a777fa4d_SOC%20/%20SSAE%2016%20Reports). +The SOC audit for Azure DevOps covers controls for data security, availability, processing integrity, and confidentiality. The SOC reports for Azure DevOps are available through the [Microsoft Service Trust Portal](https://servicetrust.microsoft.com/ViewPage/MSComplianceGuide?docTab=4ce99610-c9c0-11e7-8c2c-f908a777fa4d_SOC%20/%20SSAE%2016%20Reports). + +The Consensus Assessment Initiative Questionnaire (CAIQ) helps organizations assess and evaluate the security practices and capabilities of cloud service providers. In alignment with our commitment to security and transparency, we recently completed the CAIQ assessment for Azure DevOps. We invite you to review the full report on the [Microsoft Service Trust Portal](https://servicetrust.microsoft.com/ViewPage/MSComplianceGuide?docTab=4ce99610-c9c0-11e7-8c2c-f908a777fa4d_SOC%20/%20SSAE%2016%20Reports). ## Steps you can take -Proper data protection requires your active engagement, as well as that of your administrators and users. Your project data stored within Azure DevOps is only as secure as the end-user access points. Match the level of permission strictness and granularity for those organizations with your project's sensitivity level. +Proper data protection requires active engagement from you, your administrators, and your users. Your project data stored in Azure DevOps is only as secure as the user access points. Match the level of permission strictness and granularity for those organizations with your project's sensitivity level. ### Classify your data -The first step is to classify your data. Classify data based on sensitivity and risk -horizon, and the damage that might occur if it gets compromised. Many -enterprises have existing classification methods that can be reused when -projects move to Azure DevOps. For more information, you can download the "Data classification for cloud readiness" document from Microsoft Trustworthy Computing. +The first step is to classify your data. Classify data based on sensitivity and risk horizon, along with the damage that might occur if compromised. Many enterprises have existing classification methods that they can reuse when projects move to Azure DevOps. For more information, you can download [Data classification for cloud readiness](https://download.microsoft.com/download/0/a/3/0a3be969-85c5-4dd2-83b6-366aa71d1fe3/data-classification-for-cloud-readiness.pdf) from Microsoft Trustworthy Computing. + + -### Adopt Azure Active Directory +### Adopt Microsoft Entra ID -Use Azure Active Directory (Azure AD) to manage your organization's access to Azure DevOps. Azure AD provides another way to improve the security of your users' credentials. Azure AD allows your IT department to manage its end-user access policy, password complexity, password refreshes, and expiration if the user leaves your organization. Through Active Directory federation, you can directly link Azure AD to your organization's central directory, so you have only one location to manage these details for your enterprise. +Use Microsoft Entra ID to manage your organization's access to Azure DevOps. Microsoft Entra ID provides another way to improve the security of your users' credentials. -The following table compares Microsoft account and Azure AD characteristics relative to Azure DevOps access: +Microsoft Entra ID allows your IT department to manage its user access policy, password complexity, password refreshes, and expiration when users leave your organization. Through Active Directory federation, you can directly link Microsoft Entra ID to your organization's central directory, so you have only one location to manage these details for your enterprise. -| Properties | Microsoft account | Azure AD | +The following table compares Microsoft account and Microsoft Entra characteristics relative to Azure DevOps access: + +| Property | Microsoft account | Microsoft Entra ID | | :-------------------------------------|:---------------------------|:-----| | Identity creator | User | Organization | -| Single username / password for all work assets | No | Yes | -| Password lifetime & complexity control | User | Organization| -| Azure DevOps membership limits | Any Microsoft account (MSA) | Organization's directory +| Single username and password for all work assets | No | Yes | +| Password lifetime and complexity control | User | Organization| +| Azure DevOps membership limits | Any Microsoft account | Organization's directory | Traceable identity | No | Yes -| Organization & IP ownership | Unclear | Organization +| Organization and IP ownership | Unclear | Organization | Two-factor authentication enrollment | User | Organization | Device-based conditional access | No | Organization -Learn more about [configuring this support for your organization](../accounts/access-with-azure-ad.md). +[Learn more about configuring this support for your organization](../accounts/access-with-azure-ad.md). ### Require two-factor authentication -You might want to restrict access to your organization by requiring more than one factor to sign in. You can require multiple factors with Azure AD. For example, you can require phone authentication, in addition to a username and password, for all authentication requests. +You might want to restrict access to your organization by requiring more than one factor to sign in. You can require multiple factors by using Microsoft Entra ID. For example, you can require phone authentication, in addition to a username and password, for all authentication requests. ### Use BitLocker -For sensitive projects, you can use BitLocker on your Windows laptop or desktop computer. BitLocker encrypts the entire drive on which Windows and your data reside. When BitLocker is enabled, it automatically encrypts any file you save on that drive. If your laptop or desktop machine falls into the wrong hands, BitLocker prevents unauthorized access of local copies of data from your projects. +For sensitive projects, you can use BitLocker on your Windows laptop or desktop computer. BitLocker encrypts the entire drive on which Windows and your data reside. When BitLocker is enabled, it automatically encrypts any file you save on that drive. If your computer falls into the wrong hands, BitLocker prevents unauthorized access of local copies of data from your projects. ### Limit use of alternate authentication credentials -The default authentication mechanism for Git-related tooling is alternate authentication (sometimes referred to as basic authentication). This mechanism allows the end user to set up an alternate username and password for use during Git command-line operations. This username and password combination can also be used to access any other data for which that user has permissions. By its nature, alternate authentication credentials are less secure than the default federated authentication. +The default authentication mechanism for Git-related tooling is alternate authentication (sometimes called *basic authentication*). This mechanism allows a user to set up an alternate username and password for use during Git command-line operations. The user can use this username/password combination to access any other data for which that user has permissions. By its nature, alternate authentication credentials are less secure than the default federated authentication. + +You can still make choices for increased security. All communication is sent over HTTPS, and there are password complexity requirements. Your organization should continue to evaluate whether it needs more policies to meet your projects' security requirements. -You can still make choices for increased security. All communication gets sent over HTTPS, and there are password complexity requirements. Your organization should continue to evaluate whether additional policies are required to meet your project security requirements. You can disable alternate authentication credentials altogether if you decide that it doesn't meet your organization's security requirements. For more information, see [Change application connection & security policies for your organization](../accounts/change-application-access-policies.md). +You can disable alternate authentication credentials if you decide that it doesn't meet your organization's security requirements. For more information, see [Change application connection & security policies for your organization](../accounts/change-application-access-policies.md). ### Secure access to your organization -Azure AD provides the ability for administrators to control access to Azure resources and applications such as Azure DevOps. With conditional access control in place, Azure AD checks for the specific conditions you set for a user to access an application. After access requirements are met, the user is authenticated and can access the application. +Administrators can use Microsoft Entra ID to control access to Azure resources and applications, such as Azure DevOps. With conditional access control in place, Microsoft Entra ID checks for the specific conditions that you set for a user to access an application. After the user meets access requirements, the user is authenticated and can access the application. -Azure DevOps supports enforcing certain types of conditional access policies (for example, IP fencing) for custom Azure DevOps authentication mechanisms. These mechanisms include personal access tokens, alternate authentication, OAuth, and SSH keys. If your users are accessing Azure DevOps through a third-party client, only IP-based policies (IPv4 based only) are honored. +Azure DevOps supports enforcing certain types of conditional access policies (for example, IP fencing) for custom Azure DevOps authentication mechanisms. These mechanisms include personal access tokens, alternate authentication, OAuth, and Secure Shell (SSH) keys. If your users access Azure DevOps through a third-party client, only IPv4-based policies are honored. -## Additional resources +## More resources - [Azure DevOps home page](https://azure.microsoft.com/services/devops/) -- [Azure DevOps data location](data-location.md) +- [Data locations for Azure DevOps](data-location.md) - [Microsoft privacy statement](https://privacy.microsoft.com/privacystatement) -- [Azure DevOps support](https://developercommunity.visualstudio.com/spaces/21/index.html) +- [Azure DevOps Support](https://developercommunity.visualstudio.com/spaces/21/index.html) - [Features and services included with Azure DevOps](../../user-guide/services.md) -- [Azure trust center](https://azure.microsoft.com/support/trust-center/) +- [Azure Trust Center](https://azure.microsoft.com/support/trust-center/) - [Microsoft Security Development Lifecycle](https://www.microsoft.com/sdl/) - diff --git a/docs/organizations/security/default-git-permissions.md b/docs/organizations/security/default-git-permissions.md index 1af160d608c..a440529f1c2 100644 --- a/docs/organizations/security/default-git-permissions.md +++ b/docs/organizations/security/default-git-permissions.md @@ -23,8 +23,6 @@ To change permissions or set policies for Git repositories or branches, see the - [Git repository settings and policies](../../repos/git/repository-settings.md) - [Set Git repository permissions](../../repos/git/set-git-repository-permissions.md). - [Set permissions for a specific branch and set branch policies](../../repos/git/branch-permissions.md). - -[!INCLUDE [tip-search-settings](../../includes/tip-find-setting-permission.md)] ## Related articles diff --git a/docs/organizations/security/default-tfvc-permissions.md b/docs/organizations/security/default-tfvc-permissions.md index 384654e40d6..0cde4b16d7a 100644 --- a/docs/organizations/security/default-tfvc-permissions.md +++ b/docs/organizations/security/default-tfvc-permissions.md @@ -21,8 +21,6 @@ All members of the Contributors group with Basic access can contribute to a TFVC To change permissions for TFVC repositories or branches, see [Set TFVC repository permissions](../../repos/tfvc/set-tfvc-repository-permissions.md). -[!INCLUDE [tip-search-settings](../../includes/tip-find-setting-permission.md)] - ## Related articles - [Default permissions and access](permissions-access.md) diff --git a/docs/organizations/security/download-permissions-report-release.md b/docs/organizations/security/download-permissions-report-release.md index c6225ece8d0..2eb69b99613 100644 --- a/docs/organizations/security/download-permissions-report-release.md +++ b/docs/organizations/security/download-permissions-report-release.md @@ -14,17 +14,13 @@ ms.date: 07/07/2022 [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -To determine the effective permissions of users and groups for a release, you can download the permissions report. Requesting the report generates an email with a link to download the report. The report lists the effective permissions for the release you select, for each user and group specified at the time the report is generated. Inherited permissions come from a parent group which you can view from the web portal. The report is a json-formatted report that you can open using Power BI or other json reader. +To determine the effective permissions of users and groups for a release, you can download the permissions report. Requesting the report generates an email with a link to download the report. The report lists the effective permissions for the release you select, for each user and group specified at the time the report is generated. Inherited permissions come from a parent group that you can view from the web portal. The report is a json-formatted report that you can open using Power BI or other json reader. You can also use the [Permissions Report REST API](/rest/api/azure/devops/permissionsreport/?view=azure-devops-rest-6.1&preserve-view=true) to download the report. ## Prerequisites -- To download the permissions report, you must be a member of the **Project Collection Administrators** group. The user interface button won't appear for users who aren't a member of this group. - - To find a member of the **Project Collection Administrators** group, see [Look up a project collection administrator](look-up-project-collection-administrators.md). - +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] ## Open the security dialog for the release @@ -53,7 +49,7 @@ You can download the report for a specific release from the release's Security d ## Related articles -- [Set different levels of pipeline permissions](../../pipelines/policies/permissions.md) +- [Set different levels of pipeline permissions](../../pipelines/policies/permissions.md#pipeline-permissions) - [Manage permissions with command line tool](manage-tokens-namespaces.md) - [Permissions Report REST API](/rest/api/azure/devops/permissionsreport/?view=azure-devops-rest-6.1&preserve-view=true) diff --git a/docs/organizations/security/download-permissions-report.md b/docs/organizations/security/download-permissions-report.md index 59d545ea29c..0ad101fb7ba 100644 --- a/docs/organizations/security/download-permissions-report.md +++ b/docs/organizations/security/download-permissions-report.md @@ -21,8 +21,7 @@ You can also use the [Permissions Report REST API](/rest/api/azure/devops/permis ## Prerequisites -- To download the permissions report, you must be a member of the Project Collection Administrators group. The user interface button won't appear for users who aren't a member of this group. - +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] ## Open Project Settings>Repositories diff --git a/docs/organizations/security/export-users-audit-log.md b/docs/organizations/security/export-users-audit-log.md index 39385565456..e191617216c 100644 --- a/docs/organizations/security/export-users-audit-log.md +++ b/docs/organizations/security/export-users-audit-log.md @@ -1,130 +1,54 @@ --- title: Export a list of users and their access levels titleSuffix: Azure DevOps -description: Determine the access level-stakeholder, basic, advanced, or VS Enterprise-granted to user accounts +description: Determine the access level-stakeholder, basic, advanced, or Visual Studio Enterprise-granted to user accounts. ms.subservice: azure-devops-security ms.assetid: ms.topic: how-to ms.reviewer: ms.author: chcomley author: chcomley -monikerRange: '<= azure-devops' -ms.date: 02/16/2023 +monikerRange: 'azure-devops' +ms.date: 04/08/2025 --- # Export a list of users and their access levels -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -::: moniker range="azure-devops" You can get a list of users and groups that have access to your organization in Azure DevOps by exporting users. The downloaded list also indicates access levels. -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" -You can get a list of users and groups that have access to your Azure DevOps Server instance by exporting the audit log. The audit log also indicates access levels. -::: moniker-end - -::: moniker range="tfs-2018" -You can get a list of users and groups that have access to your Team Foundation Server (TFS) instance by exporting the audit log. The audit log also indicates access levels. -::: moniker-end ## Prerequisites -::: moniker range="azure-devops" - -* You must be the **Organization owner** or a member of the **Project Collection Administrators** group. See [Change project collection-level permissions](change-organization-collection-level-permissions.md) - ::: moniker-end - - ::: moniker range="< azure-devops" -* You must be a member of the Azure DevOps Server Administrators group. If you aren't a member, get added now. See [Add administrators](/azure/devops/server/admin/add-administrator). - ::: moniker-end +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] ## Export a list of users -::: moniker range="azure-devops" - -From your web portal or the Azure DevOps CLI command, you can get a list of the users in your organization and view their access level information. - -::: moniker-end - -::: moniker range="< azure-devops" - -From your web portal, you can get a list of the users in your organization and view their access level information. - -::: moniker-end +From your web portal or the Azure DevOps CLI command, get a list of the users in your organization and view their access level information. #### [Browser](#tab/browser) -::: moniker range="azure-devops" - -1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Then choose **Admin settings**. +1. Select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Then choose **Organization settings**. > [!div class="mx-imgBorder"] - > ![Screenshot of Open Organization settings.](../../media/settings/open-admin-settings-vert.png) + > ![Screenshot of highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) -2. Choose **Users**, and then **Export users**. +2. Select **Users** > **Export users**. > [!div class="mx-imgBorder"] - > ![Screenshot of Export users.](media/export-users-audit/export-new-nav.png) - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - -You can get a list of users and groups that have accessed your Azure DevOps Server instance by exporting the audit log. The audit log also indicates access levels. - -1. From the web portal home page for a project, choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo, (1) the project collection, and (2) **Access levels**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Open Access levels.](media/export-users-audit/open-access-levels-2019.png) - - > [!NOTE] - > If you're not a member of the Team Foundation Server Administrators group, the **Access levels** page won't appear. - -2. Choose **Export audit log**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Export audit log, Azure DevOps Server 2019 and 2020, Web portal, ](media/export-users-audit/export-audit-log-2019.png) - -3. The user log file saves as a .csv file to your Download folder. - - To determine the access level assigned to each user or group, open the file in Excel. - -::: moniker-end - -::: moniker range="tfs-2018" - -You can get a list of users and groups that have access to your TFS instance by exporting the audit log. The audit log also indicates access levels. - -1. From the web portal home page for a project, choose the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: gear icon and select **Server settings**. - - Screenshot of Open Server settings admin context, TFS 2018. - -2. Choose **Access levels**, and then **Export audit log**. - - Screenshot of Export audit log, TFS 2018. - - > [!NOTE] - > If you're not a member of the Team Foundation Server Administrators group, the link to the **Access levels** page won't appear. - -3. The user log file saves as a .csv file to your Download folder. - To determine the access level assigned to each user or group, open the file in Excel. - -::: moniker-end + > ![Screenshot of Export users button.](media/export-users-audit/export-new-nav.png) #### [Azure DevOps CLI](#tab/azure-devops-cli) -::: moniker range="azure-devops" - [Add a user](../accounts/add-organization-users.md#add-user) | [List users](#list-users) | [Remove a user](../accounts/delete-organization-users.md#remove-user) | [Update a user](../accounts/add-organization-users.md#update-user) | [Show users](../accounts/add-organization-users.md#show-users) - + ### List users -You can list the users in an organization with the [az devops user list](/cli/azure/devops/user#az-devops-user-list) command, which doesn't apply to users added via Azure Active Directory groups. To get started, see [Azure DevOps CLI](../../cli/index.md). +You can list the users in an organization with the [az devops user list](/cli/azure/devops/user#az-devops-user-list) command. This action doesn't apply to users added via Microsoft Entra groups, as certain commands or features might not directly apply to users added via Microsoft Entra. When you export the list, you might notice that group users get indicated with an "assignmentSource" of "groupRule." This assignment signifies that their access gets determined by the group membership rules, rather than individual settings. To get started, see [Azure DevOps CLI](../../cli/index.md). ```azurecli az devops user list [--org] [--skip] [--top] @@ -132,10 +56,9 @@ az devops user list [--org] [--skip] [--top] #### Parameters -- **org**: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- - **skip**: Optional. Number of users to skip. -- **top**: Optional. Maximum number of users to return. The maximum value is 10000; the default value is 100. - +- **org**: Azure DevOps organization URL. Configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. For example, `--org https://dev.azure.com/MyOrganizationName/`. +- **skip**: Optional. Number of users to skip. +- **top**: Optional. Maximum number of users to return. The maximum value is 10000; the default value is 100. #### Example @@ -153,29 +76,12 @@ f14a4f19-9910-6116-9836-cccd6dd1b7b7 contoso2@contoso.com contoso2@contoso.c 74be024c-ebf5-4993-81eb-81ae1551e45f Helena Petersen fabrikamfiber8@contoso.com stakeholder Stakeholder active ``` -::: moniker-end - -[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] * * * - ## Related articles -::: moniker range="azure-devops" - - [About access levels](access-levels.md) - [Manage users and access in Azure DevOps](../accounts/add-organization-users.md) -- [Azure DevOps Feature Matrix](https://visualstudio.microsoft.com/pricing/visual-studio-online-feature-matrix-vs) -- [Default permissions and access](permissions-access.md). - -::: moniker-end - -::: moniker range="< azure-devops" - -- [About access levels](access-levels.md) -- [Change access levels](change-access-levels.md) -- [Azure DevOps Feature Matrix](https://visualstudio.microsoft.com/pricing/visual-studio-online-feature-matrix-vs) -- [Default permissions and access](permissions-access.md). +- [Default permissions and access](permissions-access.md) -::: moniker-end \ No newline at end of file diff --git a/docs/organizations/security/faq-github-authentication.yml b/docs/organizations/security/faq-github-authentication.yml deleted file mode 100644 index d7882159531..00000000000 --- a/docs/organizations/security/faq-github-authentication.yml +++ /dev/null @@ -1,43 +0,0 @@ -### YamlMime:FAQ -metadata: - title: Authenticate & invite GitHub user FAQ - description: Learn about frequently asked questions (FAQ) on authenticating with a GitHub identity and inviting other GitHub users to Azure DevOps. - ms.subservice: azure-devops-security - ms.assetid: - ms.topic: faq - ms.author: chcomley - author: chcomley - ms.date: 08/19/2020 - monikerRange: 'azure-devops' - -title: Authenticate & invite GitHub user FAQ -summary: | - [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - - If you're having issues either connecting to Azure DevOps using your GitHub identity, or inviting other GitHub users, see the following frequently asked questions (FAQ) and answers. - - -sections: - - name: Ignored - questions: - - question: | - Q: Some of my users in Azure DevOps have GitHub identities. Do I need to add them as new GitHub users into my organization? - answer: | - A: No. Ask your users to sign out, and then from a fresh browser session, sign back in to the organization with their GitHub credentials. This action will help establish the users as having valid GitHub identities. - - - question: | - Q: I'm an organization Administrator and I turned on the policy that enables inviting GitHub users. Why can't I invite new GitHub users? - answer: | - A: Once the setting is changed, sign out of Azure DevOps, and then from a fresh browser session, sign back in to the organization `dev.azure.com/{organizationName}` or `organizationName.visualstudio.com` with your GitHub credentials. - - question: | - Q: I signed in with my GitHub credentials, but why can't I invite GitHub users? - answer: | - A: Only organization or project Administrators can invite new users to join the organization. You might not have the permission required to add new users. Work with your administrator to get you the right permissions or ask them to add the user for you. - -additionalContent: | - - ## Related articles - - * [Sign up, sign in to Azure DevOps](../../user-guide/sign-up-invite-teammates.md) - * [Add organization users to Azure DevOps](../accounts/add-organization-users.md) - * [Permission and access FAQ](faq-permissions.yml) diff --git a/docs/organizations/security/faq-permissions.yml b/docs/organizations/security/faq-permissions.yml deleted file mode 100644 index 1aedc1ac1fb..00000000000 --- a/docs/organizations/security/faq-permissions.yml +++ /dev/null @@ -1,61 +0,0 @@ -### YamlMime:FAQ -metadata: - title: Permissions and access frequently asked questions - description: Learn about frequently asked questions (FAQs) on permissions and access in Azure DevOps. - titleSuffix: Azure DevOps - ms.subservice: azure-devops-security - ms.author: chcomley - author: chcomley - ms.topic: FAQ - monikerRange: 'azure-devops' - ms.date: 03/30/2021 - -title: Access and permissions FAQs - -summary: | - [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - - See the following frequently asked questions (FAQs) and answers for access and permissions in Azure DevOps. For troubleshooting information, see [Troubleshoot access and permission issues](troubleshoot-permissions.md). - -sections: - - name: General - questions: - - question: Why can't users access some features? - answer: | - They may need a different [access level](access-levels.md#supported-access-levels) assigned. This is in addition to permissions granted through security groups. For example, [Stakeholder access](stakeholder-access.md) access level provides partial support to select features, allowing users to view and modify work items, but not to use all features. - - - question: How do I find my administrator? - answer: | - See one of the following articles: [Look up a project administrator](look-up-project-administrators.md), [Look up a project collection administrator](look-up-project-collection-administrators.md), or [Look up the organization owner](look-up-organization-owner.md). - - - question: I accidentally removed my permissions and am unable to grant them again. What should I do? - answer: | - The only way to resolve this scenario is to [Request an increase in permission levels](request-changes-permissions.md). - - - name: Users and guest users - questions: - - question: How do I remove users from Azure DevOps? - answer: | - See [How to remove users from Azure DevOps](../accounts/delete-organization-users.md). - - - question: I added a user to my project. Why can't they see the project? - answer: | - Verify that the user hasn't been added to a group where the project-level **View project-level information** permission is not set or is set to **Deny**. To learn more, see [Change project-level permissions](change-project-level-permissions.md). - - - question: Why can't guest users search for Azure Active Directory users? - answer: | - By default, [Access via Azure AD FAQs. Azure AD guests can't search the Azure AD in the manner required by Azure DevOps](../accounts/faq-azure-access.yml#no-identities). - - - name: Organizations - questions: - - question: Why can't I create an organization? - answer: | - Contact your administrator to determine if your organization is using [the Azure AD tenant policy to restrict new organization creation](../accounts/azure-ad-tenant-policy-restrict-org-creation.md). - -additionalContent: | - ## Related articles - - [Troubleshoot access and permission issues in Azure DevOps](troubleshoot-permissions.md) - - [Azure access FAQs](../accounts/faq-azure-access.yml) - - [Security best practices](security-best-practices.md) - - *Have a question that didn't get answered? Feel free to ask it through one of the feedback links provided below.* \ No newline at end of file diff --git a/docs/organizations/security/get-started-stakeholder.md b/docs/organizations/security/get-started-stakeholder.md index 8752d8f0163..d4fbb1be786 100644 --- a/docs/organizations/security/get-started-stakeholder.md +++ b/docs/organizations/security/get-started-stakeholder.md @@ -1,272 +1,246 @@ --- title: Get started with Stakeholder access titleSuffix: Azure DevOps -description: Add & update work items, view work tracking progress with Stakeholder access. +description: Learn how to add and update work items and view work tracking progress with Stakeholder access in Azure Boards. ms.service: azure-devops-boards ms.assetid: D76507F1-3154-4EE5-A23A-9179C2F5A365 ms.author: chcomley author: chcomley -ms.topic: tutorial +ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/25/2023 +ms.date: 10/11/2024 +#customer intent: As a stakeholder, I want to understand how to use my access to manage work items for my team in Azure Boards. --- # Get started as a Stakeholder [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="azure-devops" -Stakeholders are users with free but limited access to Azure DevOps features and functions. With Stakeholder access, you can add and modify work items, manage build and release pipelines, and view dashboards. You can check project status and provide direction, feedback, feature ideas, and business alignment to a team. For information about working with pipelines, see [Build your GitHub repository](../../pipelines/create-first-pipeline.md) and [Build OSS repositories](../../pipelines/repos/index.md). +::: moniker range="azure-devops" +*Stakeholders* are users with free but limited access to Azure DevOps features and functions. With Stakeholder access, you can add and modify work items, manage build and release pipelines, and view dashboards. You can check project status and provide direction, feedback, feature ideas, and business alignment to a team. For more information, see [Create your first pipeline](../../pipelines/create-first-pipeline.md) and [Supported source repositories](../../pipelines/repos/index.md). ::: moniker-end ::: moniker range="< azure-devops" -Stakeholders are users with free but limited access to Azure DevOps features and functions. With Stakeholder access, you can add and modify work items, view and approve pipelines, and view dashboards. You can check project status and provide direction, feedback, feature ideas, and business alignment to a team. +*Stakeholders* are users with free but limited access to Azure DevOps features and functions. With Stakeholder access, you can add and modify work items, view and approve pipelines, and view dashboards. You can check project status and provide direction, feedback, feature ideas, and business alignment to a team. ::: moniker-end -For more information, see the [Stakeholder access quick reference](stakeholder-access.md). To compare Stakeholder versus Basic access, see the [feature matrix](https://azure.microsoft.com/services/devops/compare-features/). +For more information, see the [Stakeholder access quick reference](stakeholder-access.md) and the [feature matrix](https://azure.microsoft.com/services/devops/compare-features/). -In this tutorial, learn how to: +## Prerequisites -> [!div class="checklist"] -> * Understand Stakeholder access and available features -> * [Sign in to a project](#sign-in-to-a-project) -> * [Understand work items and types](#understand-work-items-and-types) -> * [Open your Kanban board](#open-your-kanban-board) -> * [Add work items](#add-work-items) -> * [Update work items](#update-work-items) -> * [View the backlog](#view-as-backlog) -> * [Find work items](#find-work-items) +::: moniker range="azure-devops" -## Prerequisites +| Category | Requirements | +|--------------|-------------| +| **Private project:** | | +| **Access levels** | **Stakeholder** access. To get access as a Stakeholder, ask your organization owner or Project Collection Administrator to add you to a project with Stakeholder access. For more information, see [Add organization users and manage access](../accounts/add-organization-users.md). | +| **Permissions** | Member of the **Contributors** or **Project Administrators** group. You can view boards, open and modify work items, and add child tasks to a checklist. You can't reorder or reparent a backlog item by using the drag-and-drop method. You can't update a field on a card. | +| **Public project:** | | +| **Access levels** | **Stakeholder** access. | +| **Permissions** | Member of the **Contributors** or **Project Administrators** group for full access. For more information, see [Default permissions quick reference](../security/permissions-access.md). | -- You must have Stakeholder access for a *private project* and be a member of the Contributors or Project Administrators group. You can view boards, open and modify work items, and add child tasks to a checklist. But, you can't reorder or reparent a backlog item using drag-and-drop, nor update a field on a card. -- You must have Stakeholder access for a *public project* and be a member of the Contributors or Project Administrators group to have full access to all Boards features. For more information, see [Default roles and access for public projects](../security/permissions-access.md) +::: moniker-end -::: moniker range="azure-devops" -To get access as a Stakeholder, ask your organization owner or Project Collection Administrator to [add you to a project with Stakeholder access](../accounts/add-organization-users.md). -::: moniker-end ::: moniker range="< azure-devops" -To get access as a Stakeholder, ask your server administrator to [add you to a security group that has Stakeholder access](change-access-levels.md). -::: moniker-end -## Sign in to a project +| Category | Requirements | +|--------------|-------------| +| **Private project:** | | +| **Access levels** | **Stakeholder** access. To get access as a Stakeholder, ask your server administrator to add you to a security group that has Stakeholder access. For more information, see [Change access levels](change-access-levels.md). | +| **Permissions** | Member of the **Contributors** or **Project Administrators** group. You can view boards, open and modify work items, and add child tasks to a checklist. You can't reorder or reparent a backlog item by using the drag-and-drop method. You can't update a field on a card. | +| **Public project:** | | +| **Access levels** | **Stakeholder** access. | +| **Permissions** | Member of the **Contributors** or **Project Administrators** group for full access. For more information, see [Default permissions quick reference](../security/permissions-access.md). | -1. Select the link provided in your email invitation or open a browser window and enter the URL for the web portal. - ::: moniker range="azure-devops" - `https://dev.azure.com/OrganizationName/ProjectName` - ::: moniker-end - ::: moniker range="< azure-devops" - `http://ServerName:8080/tfs/DefaultCollection/ProjectName` - For example, to connect to the server named *FabrikamPrime* and project named *Contoso*, enter ```http://FabrikamPrime:8080/tfs/DefaultCollection/Contoso```. - ::: moniker-end +::: moniker-end -2. Enter your credentials. If you can't sign in, ask the organization owner or Project Administrator to add you as a member of the project with Stakeholder access. +## Sign in to a project -## Understand work items and types +1. Select the link provided in your email invitation or open a browser window and enter the URL for the web portal. -Work items support planning and tracking work. Each work item is based on a work item type and is assigned an identifier, which is unique within an organization or project collection. + ::: moniker range="azure-devops" + `https://dev.azure.com/OrganizationName/ProjectName` + ::: moniker-end + ::: moniker range="< azure-devops" + `http://ServerName:8080/tfs/DefaultCollection/ProjectName` -Different work items are used to track different types of work, as described in [About work items](../../boards/work-items/about-work-items.md). The work item types available are based on the [process used when your project was created](../../boards/work-items/guidance/choose-process.md)—Agile, Basic, Scrum, or CMMI—as illustrated in the following images. + For example, to connect to the server named **FabrikamPrime** and the project named **Contoso**, enter `http://FabrikamPrime:8080/tfs/DefaultCollection/Contoso`. + ::: moniker-end -[!INCLUDE [temp](../../boards/includes/work-item-types.md)] +1. Enter your credentials. If you can't sign in, ask the organization owner or Project Administrator to add you as a member of the project with Stakeholder access. -## Open your Kanban board +## Understand work items and types -You can view work items once you connect to a project. +Work items support planning and tracking work. Each work item is based on a work item type. Each work item is assigned an identifier, which is unique in an organization or project collection. -::: moniker range="azure-devops" -1. In your project, and select **Boards** > **Boards**, and then select a **team board** from the dropdown menu. +Different work items track different types of work. The work item types available are based on the [process that was used when your project was created](../../boards/work-items/guidance/choose-process.md). The options are *Agile*, *Basic*, *Scrum*, or *Capability Maturity Model Integration (CMMI)*, as illustrated in the following images. For more information, see [About work items and work item types](../../boards/work-items/about-work-items.md). - > [!div class="mx-imgBorder"] - > ![Screenshot of Open your Kanban board, cloud version.](/azure/devops/boards/boards/media/quickstart/open-kanban-board-agile.png) +[!INCLUDE [work item types](../../boards/includes/work-item-types.md)] - You can also enter a keyword in the search box or select **View Board directory** to see a list of available team boards. +## Open your board - > [!div class="mx-imgBorder"] - > ![Screenshot of Select another team's board.](/azure/devops/boards/boards/media/quickstart/select-kanban-team-board.png) +After you connect to a project, you can view work items. - > [!TIP] - > Select the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to make a team board a favorite. Favorite artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorite icon) appear at the top of the team selector list. +::: moniker range="azure-devops" +1. In your project, select **Boards** > **Boards**. From the dropdown menu, select a team board. -2. Check that you selected **Stories** for Agile, **Issues** for Basic, **Backlog items** for Scrum, or **Requirements** for CMMI as the backlog level. + :::image type="content" source="../../boards/boards/media/quickstart/open-kanban-board-agile.png" alt-text="Screenshot that shows opening your board, cloud version."::: - > [!div class="mx-imgBorder"] - > ![Screenshot of menu to select product backlog level, Backlog items, Stories, or Requirements.](/azure/devops/boards/sprints/media/assign-items-sprint/select-product-backlog-agile.png) + You can also enter a keyword in the search box or select **View Board directory** to see a list of available team boards. -::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" + :::image type="content" source="../../boards/boards/media/quickstart/select-kanban-team-board.png" alt-text="Screenshot that shows selecting another team's board."::: -1. In your project select **Boards** > **Boards**, and then select the **team board** from the dropdown menu. + > [!TIP] + > Select the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to make a team board a favorite. Favorite artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorite icon) appear at the top of the team selector list. - ![Screenshot of Open your Kanban board, on-premises versions.](/azure/devops/boards/boards/media/quickstart/open-kanban-board-agile.png) +1. Ensure that for the backlog level, you select: - To select another team's board, open the selector. Then select a different team, or select the ![home icon](../../media/icons/home-icon.png) **Browse all team boards** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. + - **Stories** for Agile. + - **Issues** for Basic. + - **Backlog items** for Scrum. + - **Requirements** for CMMI. - > [!div class="mx-imgBorder"] - > ![Screenshot of select another team's board, on-premises versions.](/azure/devops/boards/boards/media/quickstart/select-kanban-team-board.png) + :::image type="content" source="../../boards/sprints/media/assign-items-sprint/select-product-backlog-agile.png" alt-text="Screenshot that shows the menu to select the product backlog level option of Backlog items, Stories, Issues, or Requirements."::: - > [!TIP] - > Select the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to make a team board a favorite. Favorite artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorite icon) appear at the top of the team selector list. +::: moniker-end +::: moniker range=" **Boards**. From the dropdown menu, select a team board. - > [!div class="mx-imgBorder"] - > ![Screenshot of select product backlog level, Backlog items, Stories, or Requirements, on-premises versions.](/azure/devops/boards/sprints/media/assign-items-sprint/select-product-backlog-agile.png) + :::image type="content" source="../../boards/boards/media/quickstart/open-kanban-board-agile.png" alt-text="Screenshot that shows opening your board in on-premises versions."::: -::: moniker-end -::: moniker range="tfs-2018" -1. In your project select **Work** > **Backlogs** > **Stories**, and then select **Board**. + To select another team's board, open the selector. Then select a different team, or select the :::image type="icon" source="../../media/icons/home-icon.png"::: **Browse all team boards** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - ![Open Portfolio Kanban board, features](/azure/devops/boards/boards/media/quickstart/open-kanban-board.png) + :::image type="content" source="../../boards/boards/media/quickstart/select-kanban-team-board.png" alt-text="Screenshot that shows selecting another team's board in on-premises versions."::: - If you don't see **Work**, your screen size might be reduced. Select the three dots (:::image type="icon" source="../../media/ellipses-reduced-screen-size.png" border="false":::) icon. Then select **Work** > **Backlogs** > **Board**. + > [!TIP] + > Select the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to make a team board a favorite. Favorite artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorite icon) appear at the top of the team selector list. - ![Open Work when screen size is reduced](/azure/devops/boards/boards/media/kanban-quickstart-reduced-screensize.png) +1. Check that for the backlog level you selected: -2. To select another team, open the project and team selector. Select a different team, or select the **Browse** option. + - **Stories** for Agile. + - **Issues** for Basic. + - **Backlog items** for Scrum. + - **Requirements** for CMMI. - > [!div class="mx-imgBorder"] - > ![Select another team](/azure/devops/boards/sprints/media/assign-items-sprint/team-selector-backlogs-standard.png) + :::image type="content" source="../../boards/boards/media/quickstart/select-product-backlog-agile.png" alt-text="Screenshot that shows selecting the product backlog level option of Backlog items, Stories, Issues, or Requirements for on-premises versions."::: - Your Kanban board appears. - ![Kanban board, Agile template](/azure/devops/boards/boards/media/kanban-basics-intro.png) -::: moniker-end +::: moniker-end -## Add work items +## Add work items ::: moniker range="azure-devops" -From your board, select the :::image type="icon" source="../../media/icons/add-icon.png" border="false"::: plus sign, enter a title, and then select **Enter**. +From your board, select the :::image type="icon" source="../../media/icons/add-icon.png" border="false"::: plus sign, enter a title, and then select **Enter**. -> [!div class="mx-imgBorder"] -> ![Screenshot showing highlighted New item button.](../../boards/boards/media/quickstart/add-new-item-agile-s155.png) +:::image type="content" source="../../boards/boards/media/quickstart/add-new-item-agile-s155.png" alt-text="Screenshot that shows the highlighted New item button."::: ::: moniker-end ::: moniker range="< azure-devops" -From the Kanban board, you can't add work items, but you can open them and annotate them. To add work items, open the backlog by choosing the **Backlog** link. Also, you can't update the status of a work item by drag-and-drop to a different column or reorder cards within a column. +From the board, you can't add work items, but you can open them and annotate them. To add work items, open the backlog by selecting the **Backlog** link. Also, you can't update the status of a work item by using the drag-and-drop method to move a different column or reorder cards within a column. ::: moniker-end -For more information, see [View and add work items from the Work Items page](../../boards/work-items/view-add-work-items.md). +For more information, see [View and add work items](../../boards/work-items/view-add-work-items.md). ::: moniker range=">= azure-devops-2020" ## Update work items -The work item forms you see may differ from the following images. The basic functionality is the same, however, changes have been made with different versions of Azure DevOps. + +Your work item forms might differ from the following images, but the functionality is the same. ### Change status -Drag and drop a work item to move it downstream as you complete work. +Drag a work item downstream as you finish work. -![Screenshot of Kanban board, Agile template, update status of work item.](../../boards/boards/media/alm-cc-move-card.png) +:::image type="content" source="../../boards/boards/media/alm-cc-move-card.png" alt-text="Screenshot that shows a board that uses an Agile template to update the status of a work item."::: ::: moniker-end ::: moniker range="azure-devops-2020" -> [!NOTE] -> Stakeholders can only drag-and-drop cards to different columns with the Azure DevOps Server 2020.1 update. For more information, see [Azure DevOps Server 2020 Update 1 RC1 Release Notes, Boards](/azure/devops/server/release-notes/azuredevops2020u1#stakeholders-can-move-work-items-across-board-columns). +> [!NOTE] +> Stakeholders can only use the drag-and-drop method to move cards to different columns with the Azure DevOps Server 2020.1 update. For more information, see the [Release Notes](/azure/devops/server/release-notes/azuredevops2020u1#stakeholders-can-move-work-items-across-board-columns). ::: moniker-end ### Add details -To open a work item, double-click the title or highlight it, and then select **Enter**. -Here we show how to assign work. You can only assign work to a user who is added to the project. - -#### [Agile process](#tab/agile-process) -For example, here we assign the story to Raisa Pokrovskaya and we add a discussion note, at-mentioning Raisa. When you're done, select **Save & Close**. +To open a work item, double-click the title or highlight it, and then select **Enter**. This example shows how to assign work. You can only assign work to a user who was added to the project. -> [!div class="mx-imgBorder"] -> ![Screenshot of User Story work item form, add details.](../../boards/get-started/media/plan-track-work/user-story-form-add-details.png) +#### [Agile process](#tab/agile-process) -#### [Basic process](#tab/basic-process) +This example assigns the story to Raisa Pokrovskaya and at-mentions Raisa in a discussion note. When you're finished, select **Save & Close**. -For example, here we assign the issue to Raisa Pokrovskaya and we add a discussion note, at-mentioning Raisa. When you're done, select **Save & Close**. +:::image type="content" source="../../boards/get-started/media/plan-track-work/user-story-form-add-details.png" alt-text="Screenshot that shows details in the Discussion box on the User Story work item form."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of Issues work item form, add details](../../boards/get-started/media/track-issues/issue-form-add-details.png) +#### [Basic process](#tab/basic-process) -#### [Scrum process](#tab/scrum-process) +This example assigns the issue to Raisa Pokrovskaya and at-mentions Raisa in a discussion note. When you're finished, select **Save & Close**. -For example, here we assign the Product Backlog Item to Jamal Hartnett and add a description and tags. When you're done, select **Save & Close**. +:::image type="content" source="../../boards/get-started/media/track-issues/issue-form-add-details.png" alt-text="Screenshot that shows details in the Discussion box on the Issues work item form."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of Scrum Product Backlog work item form, add details.](../../boards/media/pbi-form-cloud.png) +#### [Scrum process](#tab/scrum-process) -#### [CMMI process](#tab/cmmi-process) +This example assigns the Product backlog item to Jamal Hartnett and adds a description and tags. When you're finished, select **Save & Close**. -For example, here we assign the Requirement to Jamal Hartnett. When you're done, select **Save & Close**. +:::image type="content" source="../../boards/media/pbi-form-cloud.png" alt-text="Screenshot that shows adding details to the Scrum Product backlog work item form."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of Requirement work item form](../../boards/media/requirement-form-cloud.png) +#### [CMMI process](#tab/cmmi-process) + +This example assigns the Requirement work item to Jamal Hartnett. When you're finished, select **Save & Close**. + +:::image type="content" source="../../boards/media/requirement-form-cloud.png" alt-text="Screenshot that shows the Requirement work item form."::: #### CMMI-specific field descriptions -[!INCLUDE [temp](../../boards/includes/section-cmmi-field-descriptions.md)] +[!INCLUDE [cmmi field descriptions](../../boards/includes/section-cmmi-field-descriptions.md)] *** -Add more details by changing field values, adding a description or tags, and adding comments. For more information, see the following articles: +To add more details, change field values, add a description or tags, and add comments. For more information, see: -- [Update fields: Descriptions and usage](../../boards/get-started/plan-track-work.md) +- [Plan and track work in Azure Boards](../../boards/get-started/plan-track-work.md). - [Add tags to work items](../../boards/queries/add-tags-to-work-items.md). As a Stakeholder, you can add existing tags to a work item, but you can't add new tags. -- [Capture comments in the Discussion section](../../boards/get-started/plan-track-work.md#capture-comments-in-the-discussion-section) +- [Capture comments in the Discussion section](../../boards/get-started/plan-track-work.md#capture-comments-in-the-discussion-section). -## View as Backlog +## View as backlog -Check the product backlog to see how the team prioritized their work. Backlog items appear in priority order. Work item types may include bugs depending on the [process used when your project was created](../../boards/work-items/guidance/choose-process.md). +Check the product backlog to see how the team prioritized their work. Backlog items appear in priority order. Work item types might include bugs, depending on the process used when your project was created. For more information, see [About default processes and process templates](../../boards/work-items/guidance/choose-process.md). ::: moniker range="azure-devops" -From the Kanban board, choose **View as Backlog**. -> [!div class="mx-imgBorder"] -> ![Screenshot of link to view Backlog, cloud version.](../../boards/media/switch-to-backlog-cloud.png) -::: moniker-end +From the board, select **View as backlog**. -::: moniker range=">= azure-devops-2019 < azure-devops" -From the Kanban board, choose **View as backlog**. -> [!div class="mx-imgBorder"] -> ![Screenshot of link to view Backlog, on-premises version.](../../boards/media/switch-to-backlog-2019.png) +:::image type="content" source="../../boards/media/switch-to-backlog-cloud.png" alt-text="Screenshot that shows View as backlog in a cloud version."::: ::: moniker-end -::: moniker range="tfs-2018" -From the Kanban board, choose **Backlog**. -> [!div class="mx-imgBorder"] -> ![Screenshot of link to view Backlog, TFDS 2018 and earlier versions.](../../boards/media/switch-to-backlog-2015.png) +::: moniker range=" < azure-devops" +From the board, select **View as backlog**. +:::image type="content" source="../../boards/media/switch-to-backlog-2019.png" alt-text="Screenshot that shows View as backlog in an on-premises version."::: ::: moniker-end -You should see the list of backlog items listed in priority order. You can add a backlog item, which goes to the bottom of the list. With Stakeholder access, you can't reprioritize work. +The list of backlog items appears in priority order. You can add a backlog item, which goes to the bottom of the list. With Stakeholder access, you can't reprioritize work. ## Find work items -::: moniker range=">= azure-devops-2019" -Choose **Boards** > **Work Items** > and then select an option from the dropdown menu. Here we chose **Assigned to me**. +::: moniker range="<=azure-devops" -> [!div class="mx-imgBorder"] -> ![Screenshot showing selections of Work, Work Items page, and Choose Assigned to Me.](media/stakeholder/work-items-assigned-to-me.png) +Select **Boards** > **Work Items**. Then select an option from the dropdown menu. For example, select **Assigned to me**. -For more information, see the following articles: -- [View, run, or email a work item query](../../boards/queries/view-run-query.md) -- [View and add work items using the Work Items page](../../boards/work-items/view-add-work-items.md) - ::: moniker-end +:::image type="content" source="media/stakeholder/work-items-assigned-to-me.png" alt-text="Screenshot that shows selections of work on the Work Items page and choosing Assigned to me."::: -::: moniker range="tfs-2018" -1. Open **Work** > **Queries** and select **Assigned to me** to see the list of work items assigned to you. - ![Screenshot of the queries page, items assigned to you.](media/work-as-a-stakeholder-query.png) +For more information, see: - Or, open any of the queries defined in the Shared Queries folder. - ![Screenshot showing running a shared query.](media/work-as-a-stakeholder-open-shared-query.png) +- [View, run, or email a work item query](../../boards/queries/view-run-query.md) +- [View and add work items](../../boards/work-items/view-add-work-items.md) -2. [Create new queries or edit existing queries](../../boards/queries/using-queries.md) and save them under My Queries folder. - ![Screenshot showing Query Editor.](media/work-as-a-stakeholder-edit-query.png) ::: moniker-end ## Next steps > [!div class="nextstepaction"] > [Create your product backlog](../../boards/backlogs/create-your-backlog.md) - + ## Related articles -- [Add work items](../../boards/backlogs/add-work-items.md) -- [Kanban quickstart](../../boards/boards/kanban-quickstart.md) -- [Access levels](access-levels.md) -- [Change access levels](change-access-levels.md) \ No newline at end of file +- [Add work items](../../boards/backlogs/add-work-items.md) +- [Get started with Kanban boards](../../boards/boards/kanban-quickstart.md) +- [Learn about access levels](access-levels.md) +- [Change access levels](change-access-levels.md) diff --git a/docs/organizations/security/includes/agent-pool-roles.md b/docs/organizations/security/includes/agent-pool-roles.md index d9d97f8bddd..2f4912c7ffe 100644 --- a/docs/organizations/security/includes/agent-pool-roles.md +++ b/docs/organizations/security/includes/agent-pool-roles.md @@ -5,22 +5,13 @@ author: chcomley ms.topic: include --- -> [!div class="mx-tdCol2BreakAll"] -> | Role (organization-level) | Description | -> |------|---------| -> | **Reader** | Can view the pool as well as agents. You typically add operators to this role that are responsible for monitoring the agents and their health. | -> | **Service Account** | Can use the pool to create an agent in a project. If you follow the guidelines for [creating new pools](../../../pipelines/agents/pools-queues.md), you typically do not have to add any members to this role. | -> | **Administrator** | Can register or unregister agents from the pool and manage membership for all pools, as well as view and create pools. They can also use the agent pool when creating an agent in a project. The system automatically adds the user that created the pool to the Administrator role for that pool. | +| Role (organization-level) | Description | +|------|---------| +| **Reader** | View the pool and agents. Typically, add operators to this role to monitor the agents and their health. | +| **Service Account** | Use the pool to create an agent in a project. Following the guidelines for [creating new pools](../../../pipelines/agents/pools-queues.md) usually means you don't need to add members to this role. | +| **Administrator** | Register or unregister agents from the pool, manage membership for all pools, and view and create pools. Use the agent pool when creating an agent in a project. The system automatically adds the user who created the pool to the Administrator role for that pool. | -To manage role settings for an organization or collection-level agent pools, open **Organization settings** and choose **Agent Pools**. - -- To set permissions for all pools within the organization or collection, choose **Security**, and then add a user or group and select their role. - - > [!div class="mx-imgBorder"] - > ![Set agent pools security roles for all pools.](/azure/devops/organizations/security/media/security-roles/agent-pools-pipeline-all-security-roles-org.png) - -- To set permissions for a specific pool, choose the pool and then **Security**. Then add a user or group and select their role. - - > [!div class="mx-imgBorder"] - > ![Set agent pools security roles for a specific pool.](/azure/devops/organizations/security/media/security-roles/agent-pools-pipeline-individual-security-roles-org.png) \ No newline at end of file +Manage role settings for organization or collection-level agent pools from the **Organization settings** > **Agent Pools** page. +- To set permissions for all pools within the organization or collection, select **Security**, then add a user or group and choose their role. +- To set permissions for a specific pool, select the pool and then **Security**. Add a user or group and choose their role. diff --git a/docs/organizations/security/includes/agent-queue-roles.md b/docs/organizations/security/includes/agent-queue-roles.md index e88c896ce59..8d0e75e382b 100644 --- a/docs/organizations/security/includes/agent-queue-roles.md +++ b/docs/organizations/security/includes/agent-queue-roles.md @@ -5,27 +5,21 @@ author: chcomley ms.topic: include --- - - - -> [!div class="mx-tdCol2BreakAll"] -> | Role (project-level) | Description | -> |------|---------| -> | **Reader** | Can view the pool. You typically add operators to this role that are responsible for monitoring the build and deployment jobs in that pool. | -> | **User** | Can view and use the pool when authoring build or release pipelines. | -> | **Creator** | Can create and use the pool when authoring build or release pipelines. | -> | **Administrator** | Can manage membership for all roles of the pool, as well as view and use the pools. The user that created a pool is automatically added to the Administrator role for that pool. - -You control the security of all project agent pools from the **Security** tab. Role memberships for individual project agent pools automatically inherit from what those roles. By default, the following groups are added to the Administrator role of 'All agent pools': Build Administrators, Release Administrators, Project Administrators. - -To manage role settings for a project agent pool, open **Project settings** and choose **Agent Pools**. - -- To set permissions for all pools within the project, choose **Security**, and then add a user and select their role. - - > [!div class="mx-imgBorder"] - > ![Agent pools security roles for all pools within the project.](/azure/devops/organizations/security/media/security-roles/pipeline-all-security-roles.png) - -- To set permissions for a specific pool, choose the pool and then **Security**. Then add a user and select their role. - - > [!div class="mx-imgBorder"] - > ![Agent pools security roles for a specific pool within the project.](/azure/devops/organizations/security/media/security-roles/pipline-individual-security-role.png) + +| Role (project-level) | Description | +|------|---------| +| **Reader** | View the pool. Typically, add operators to this role to monitor build and deployment jobs in the pool. | +| **User** | View and use the pool when authoring build or release pipelines. | +| **Creator** | Create and use the pool when authoring build or release pipelines. | +| **Administrator** | Manage membership for all roles of the pool, and view and use the pools. The user who created a pool is automatically added to the Administrator role for that pool. | + +Manage the security of all project agent pools from the **Security** tab. Role memberships for individual project agent pools automatically inherit from these roles. + +By default, the following groups are added to the Administrator role of 'All agent pools': +- Build Administrators +- Release Administrators +- Project Administrators. + +Manage role settings for a project agent pool on the **Project settings** > **Agent Pools** page. +- To set permissions for all pools within the project, select **Security**, then add a user and choose their role. +- To set permissions for a specific pool, select the pool and then **Security**. Under **Pipeline permissions**, view which pipelines have access to the pool. Explicitly allow a pipeline using the `+` button or allow all pipelines using the `⋮` button. Under **User permissions**, add a user or group and choose their role. diff --git a/docs/organizations/security/includes/analytics.md b/docs/organizations/security/includes/analytics.md index a4ee96e0ee1..9f491d5ee8b 100644 --- a/docs/organizations/security/includes/analytics.md +++ b/docs/organizations/security/includes/analytics.md @@ -20,6 +20,7 @@ ms.topic: include **Project admins** :::column-end::: :::row-end::: +--- :::row::: :::column span="2"::: View Analytics @@ -76,4 +77,5 @@ ms.topic: include ✔️ :::column-end::: :::row-end::: - \ No newline at end of file + +--- diff --git a/docs/organizations/security/includes/boards-backlogs.md b/docs/organizations/security/includes/boards-backlogs.md index 8c48ef51365..924e0bea378 100644 --- a/docs/organizations/security/includes/boards-backlogs.md +++ b/docs/organizations/security/includes/boards-backlogs.md @@ -64,7 +64,7 @@ ms.date: 04/04/2022 ✔️ :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="2"::: Add child items to a backlog item; prioritize or reorder a backlog; parent items using the Mapping pane; Assign items to a sprint using the Planning pane @@ -80,22 +80,7 @@ ms.date: 04/04/2022 :::column-end::: :::row-end::: ::: moniker-end -::: moniker range="tfs-2018" -:::row::: - :::column span="2"::: - Add child items to a backlog item; prioritize or reorder a backlog; parent items using the Mapping pane; Assign items to a sprint using drag-and-drop - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: -::: moniker-end + :::row::: :::column span="2"::: Configure team settings, backlog levels, show bugs, work days off @@ -111,5 +96,4 @@ ms.date: 04/04/2022 :::column-end::: :::row-end::: - \ No newline at end of file diff --git a/docs/organizations/security/includes/boards-sprints.md b/docs/organizations/security/includes/boards-sprints.md index 69f29dc23c5..1f42e578651 100644 --- a/docs/organizations/security/includes/boards-sprints.md +++ b/docs/organizations/security/includes/boards-sprints.md @@ -66,7 +66,7 @@ ms.topic: include View team capacity and work details :::column-end::: :::column span="1"::: - + ✔️ :::column-end::: :::column span="1"::: ✔️ @@ -83,7 +83,7 @@ ms.topic: include :::column-end::: :::column span="1"::: - ✔️ + :::column-end::: :::column span="1"::: ✔️ diff --git a/docs/organizations/security/includes/boards-work-items.md b/docs/organizations/security/includes/boards-work-items.md index e6fc050006e..4c639731646 100644 --- a/docs/organizations/security/includes/boards-work-items.md +++ b/docs/organizations/security/includes/boards-work-items.md @@ -6,16 +6,13 @@ ms.topic: include ms.date: 02/02/2023 --- - - -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!NOTE] > You can change the work item type or move work items to another project within a project collection. These features require that the data warehouse is disabled. With the data warehouse disabled, you can use the [Analytics Service](../../../report/powerbi/what-is-analytics.md) to support your reporting needs. To learn more about disabling the data warehouse, see [Disable the data warehouse and cube](/previous-versions/azure/devops/report/admin/disable-data-warehouse). ::: moniker-end - :::row::: :::column span="2"::: **Task or permission** @@ -92,7 +89,7 @@ ms.date: 02/02/2023 ✔️ :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="2"::: **Change work item type** @@ -211,6 +208,6 @@ ms.date: 02/02/2023 :::column-end::: :::row-end::: - > [!NOTE] -> Work items are subject to rules applied to them. Conditional rules based on user or group membership are cached for your web browser. If you find yourself restricted to update a work item, you may have encountered one of these rules. If you believe you've encountered an issue that doesn't apply to you, see [Work item form IndexDB caching issues](../../settings/work/troubleshoot-work-item-form-caching-issues.md). To learn more about conditional rules, see [Rules and rule evaluation](../../settings/work/rule-reference.md). \ No newline at end of file +> Work items are subject to rules applied to them. Conditional rules based on user or group membership are cached for your web browser. If you find yourself restricted to update a work item, you may have encountered one of these rules. If you believe you've encountered an issue that doesn't apply to you, see [Work item form IndexDB caching issues](../../settings/work/troubleshoot-work-item-form-caching-issues.md). For more information, see [Rules and rule evaluation](../../settings/work/rule-reference.md). + \ No newline at end of file diff --git a/docs/organizations/security/includes/code-git.md b/docs/organizations/security/includes/code-git.md index 810f7fe5285..1e991b24f03 100644 --- a/docs/organizations/security/includes/code-git.md +++ b/docs/organizations/security/includes/code-git.md @@ -9,7 +9,6 @@ ms.subservice: azure-devops-repos-git - :::row::: :::column span="2"::: **Permission** @@ -96,46 +95,8 @@ ms.subservice: azure-devops-repos-git ✔️ :::column-end::: :::row-end::: -::: moniker range="< azure-devops-2019" -:::row::: - :::column span="2"::: - **Force push** (rewrite history, delete branches and tags) - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range="< azure-devops-2019" -:::row::: - :::column span="2"::: - **Bypass policies when completing pull requests** - (not set for any security group) - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019" + +::: moniker range="<=azure-devops" :::row::: :::column span="2"::: **Bypass policies when completing pull requests**, **Bypass policies when pushing**, **Force push** (rewrite history, delete branches and tags) @@ -159,4 +120,3 @@ ms.subservice: azure-devops-repos-git - diff --git a/docs/organizations/security/includes/collection-level-permissions-reference-table-cloud.md b/docs/organizations/security/includes/collection-level-permissions-reference-table-cloud.md index 293c8df91b5..1808871fdcb 100644 --- a/docs/organizations/security/includes/collection-level-permissions-reference-table-cloud.md +++ b/docs/organizations/security/includes/collection-level-permissions-reference-table-cloud.md @@ -19,7 +19,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Administer build resource permissions + Administer build resource permissions `BuildAdministration, AdministerBuildResourcePermissions` :::column-end::: :::column span="2"::: @@ -32,7 +32,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Administer process permissions + Administer process permissions `Process, AdministerProcessPermissions` :::column-end::: :::column span="2"::: @@ -43,7 +43,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Administer shelved changes + Administer shelved changes `VersionControlPrivileges, AdminWorkspaces` :::column-end::: :::column span="2"::: @@ -52,7 +52,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Administer workspaces + Administer workspaces `Workspaces, Administer` :::column-end::: :::column span="2"::: @@ -61,7 +61,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Alter trace settings + Alter trace settings `Collection, DIAGNOSTIC_TRACE` :::column-end::: :::column span="2"::: @@ -70,7 +70,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Create a workspace + Create a workspace `VersionControlPrivileges, CreateWorkspace` :::column-end::: :::column span="2"::: @@ -79,7 +79,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Create new projects (formerly Create new team projects) + Create new projects (formerly Create new team projects) `Collection, CREATE_PROJECTS` :::column-end::: :::column span="2"::: @@ -88,7 +88,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Create process + Create process `Process, Create` :::column-end::: :::column span="2"::: @@ -97,7 +97,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Delete field from organization + Delete field from organization (formerly Delete field from account) `Collection, DELETE_FIELD` :::column-end::: @@ -117,7 +117,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Delete team project + Delete team project `Project, DELETE` :::column-end::: :::column span="2"::: @@ -137,7 +137,7 @@ ms.date: 10/19/2022 :::column span="4"::: > [!NOTE] > **Edit instance-level information** includes the ability to perform these tasks for all projects defined in an organization or collection: - > - Modify organization **Overview** settings, **Extensions**, and **Azure Active Directory** settings + > - Modify organization **Overview** settings, **Extensions**, and **Microsoft Entra ID** settings > - Modify version control permissions and repository settings > - Edit [event subscriptions](#alerts) or alerts for global notifications, project-level, and team-level events > - Edit all project and team-level settings for projects defined in the collections. @@ -145,7 +145,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Edit process + Edit process `Process, Edit` :::column-end::: :::column span="2"::: @@ -154,7 +154,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Make requests on behalf of others + Make requests on behalf of others `Server, Impersonate` :::column-end::: :::column span="2"::: @@ -164,7 +164,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Manage build resources + Manage build resources `BuildAdministration, ManageBuildResources` :::column-end::: :::column span="2"::: @@ -191,7 +191,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Manage process template + Manage process template `Collection, MANAGE_TEMPLATE` :::column-end::: :::column span="2"::: @@ -200,7 +200,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Manage test controllers + Manage test controllers `Collection, MANAGE_TEST_CONTROLLERS` :::column-end::: :::column span="2"::: @@ -209,7 +209,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Trigger events + Trigger events `Collection, TRIGGER_EVENT` `Server, TRIGGER_EVENT` :::column-end::: @@ -219,7 +219,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Use build resources + Use build resources `BuildAdministration, UseBuildResources` :::column-end::: :::column span="2"::: @@ -228,7 +228,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - View build resources + View build resources `BuildAdministration, ViewBuildResources` :::column-end::: :::column span="2"::: @@ -237,7 +237,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - View instance-level information + View instance-level information `Collection, GENERIC_READ` :::column-end::: :::column span="2"::: @@ -246,11 +246,11 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - View system synchronization information + View system synchronization information `Collection, SYNCHRONIZE_READ` :::column-end::: :::column span="2"::: Can call the synchronization application programming interfaces. Assign only to service accounts. :::column-end::: :::row-end::: - \ No newline at end of file + diff --git a/docs/organizations/security/includes/collection-level-permissions-reference-table.md b/docs/organizations/security/includes/collection-level-permissions-reference-table.md index 7f606027c7d..e782fbfbd64 100644 --- a/docs/organizations/security/includes/collection-level-permissions-reference-table.md +++ b/docs/organizations/security/includes/collection-level-permissions-reference-table.md @@ -21,7 +21,7 @@ ms.date: 10/19/2022 --- :::row::: :::column span="2"::: - Administer build resource permissions + Administer build resource permissions `BuildAdministration, AdministerBuildResourcePermissions` :::column-end::: :::column span="2"::: @@ -33,10 +33,10 @@ ms.date: 10/19/2022 :::column-end::: :::row-end::: ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="Administer process permissions + Administer process permissions `Process, AdministerProcessPermissions` :::column-end::: :::column span="2"::: @@ -49,7 +49,7 @@ ms.date: 10/19/2022 ::: moniker range="< azure-devops" :::row::: :::column span="2"::: - Administer shelved changes + Administer shelved changes `VersionControlPrivileges, AdminWorkspaces` :::column-end::: :::column span="2"::: @@ -58,7 +58,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Administer workspaces + Administer workspaces `Workspaces, Administer` :::column-end::: :::column span="2"::: @@ -67,7 +67,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Alter trace settings + Alter trace settings `Collection, DIAGNOSTIC_TRACE` :::column-end::: :::column span="2"::: @@ -76,7 +76,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Create a workspace + Create a workspace `VersionControlPrivileges, CreateWorkspace` :::column-end::: :::column span="2"::: @@ -85,7 +85,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Create new projects + Create new projects (formerly Create new team projects) `Collection, CREATE_PROJECTS` :::column-end::: @@ -94,10 +94,10 @@ ms.date: 10/19/2022 :::column-end::: :::row-end::: ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="Create process + Create process `Process, Create` :::column-end::: :::column span="2"::: @@ -106,7 +106,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Delete field from organization + Delete field from organization (formerly Delete field from account) `Collection, DELETE_FIELD` :::column-end::: @@ -128,7 +128,7 @@ ms.date: 10/19/2022 ::: moniker range="< azure-devops" :::row::: :::column span="2"::: - Delete team project + Delete team project `Project, DELETE` :::column-end::: :::column span="2"::: @@ -146,22 +146,21 @@ ms.date: 10/19/2022 :::column-end::: :::column span="2"::: Can set organization and project-level settings. -:::row-end::: -:::row::: - :::column span="4"::: + > [!NOTE] > **Edit collection-level information** includes the ability to perform these tasks for all projects defined in an organization or collection: > - Modify **Extensions**, and **Analytics** settings > - Modify version control permissions and repository settings > - Edit [event subscriptions](#alerts) or alerts for global notifications, project-level, and team-level events - > - Edit all project and team-level settings for projects defined in the collections. + > - Edit all project and team-level settings for projects defined in the collections. + :::column-end::: :::row-end::: ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="Edit process + Edit process `Process, Edit` :::column-end::: :::column span="2"::: @@ -172,7 +171,7 @@ ms.date: 10/19/2022 ::: moniker range="< azure-devops" :::row::: :::column span="2"::: - Make requests on behalf of others + Make requests on behalf of others `Server, Impersonate` :::column-end::: :::column span="2"::: @@ -182,7 +181,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Manage build resources + Manage build resources `BuildAdministration, ManageBuildResources` :::column-end::: :::column span="2"::: @@ -206,7 +205,7 @@ ms.date: 10/19/2022 ::: moniker range="< azure-devops" :::row::: :::column span="2"::: - Manage process template + Manage process template `Collection, MANAGE_TEMPLATE` :::column-end::: :::column span="2"::: @@ -215,7 +214,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Manage test controllers + Manage test controllers `Collection, MANAGE_TEST_CONTROLLERS` :::column-end::: :::column span="2"::: @@ -224,7 +223,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Trigger events + Trigger events `Collection, TRIGGER_EVENT` `Server, TRIGGER_EVENT` :::column-end::: @@ -234,7 +233,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - Use build resources + Use build resources `BuildAdministration, UseBuildResources` :::column-end::: :::column span="2"::: @@ -243,7 +242,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - View build resources + View build resources `BuildAdministration, ViewBuildResources` :::column-end::: :::column span="2"::: @@ -252,7 +251,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - View instance-level information + View instance-level information or View collection-level information `Collection, GENERIC_READ` :::column-end::: @@ -262,7 +261,7 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="2"::: - View system synchronization information + View system synchronization information `Collection, SYNCHRONIZE_READ` :::column-end::: :::column span="2"::: diff --git a/docs/organizations/security/includes/collection-level-permissions.md b/docs/organizations/security/includes/collection-level-permissions.md index 6dadaac9da4..38460c03861 100644 --- a/docs/organizations/security/includes/collection-level-permissions.md +++ b/docs/organizations/security/includes/collection-level-permissions.md @@ -7,7 +7,7 @@ ms.date: 02/28/2022 --- -The following table lists the permissions assigned at the organization or collection-level. All of these permissions, except for the **Make requests on behalf of others** permission, are granted to members of the **Project Collection Administrators** group. For a description of each permission, see [Permissions and groups reference, Groups](../permissions.md#collection-level). +The following table lists the permissions assigned at the organization or collection level. All permissions, except for **Make requests on behalf of others**, are granted to members of the **Project Collection Administrators** group. For more information, see [Permissions and groups reference, Groups](../permissions.md#collection-level). :::row::: :::column span=""::: @@ -25,16 +25,14 @@ The following table lists the permissions assigned at the organization or collec **Boards** :::column span=""::: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - Administer process permissions - Create process - Delete field from organization or account - Delete process - Edit process ::: moniker-end - ::: moniker range="tfs-2018" - - Delete field from organization or account - ::: moniker-end + **Repos** (TFVC) - Administer shelved changes @@ -43,19 +41,14 @@ The following table lists the permissions assigned at the organization or collec :::column-end::: :::column span=""::: **Pipelines** - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - Administer build resource permissions - Manage build resources - Manage pipeline policies - Use build resources - View build resources ::: moniker-end - ::: moniker range="< azure-devops-2019" - - Administer build resource permissions - - Manage build resources - - Use build resources - - View build resources - ::: moniker-end + **Test Plans** - Manage test controllers ::: moniker range="azure-devops" @@ -64,7 +57,7 @@ The following table lists the permissions assigned at the organization or collec - Manage audit streams - View audit log ::: moniker-end - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" **Policies** - Manage enterprise policies ::: moniker-end diff --git a/docs/organizations/security/includes/deployment-group-roles.md b/docs/organizations/security/includes/deployment-group-roles.md index c373d9df69c..2d24311bced 100644 --- a/docs/organizations/security/includes/deployment-group-roles.md +++ b/docs/organizations/security/includes/deployment-group-roles.md @@ -1,9 +1,7 @@ - -> [!div class="mx-tdCol2BreakAll"] -> | Role | Description | -> |------|---------| -> | **Reader** | Can only view deployment groups. | -> | **Creator** | Can view and create deployment groups. | -> | **User** | Can view and use but cannot manage or create deployment groups. | -> | **Administrator** | Can administer roles, manage, view and use deployment groups. | \ No newline at end of file +| Role | Description | +|------|---------| +| **Reader** | View deployment groups. | +| **Creator** | View and create deployment groups. | +| **User** | View and use deployment groups, but cannot manage or create them. | +| **Administrator** | Administer roles, manage, view, and use deployment groups. | diff --git a/docs/organizations/security/includes/deployment-pool-roles.md b/docs/organizations/security/includes/deployment-pool-roles.md index 8377e95cfaf..dff4a205497 100644 --- a/docs/organizations/security/includes/deployment-pool-roles.md +++ b/docs/organizations/security/includes/deployment-pool-roles.md @@ -1,9 +1,8 @@ - -> [!div class="mx-tdCol2BreakAll"] -> | Role | Description | -> |------|---------| -> | **Reader** | Can only view deployment pools. | -> | **Service Account** | Can view agents, create sessions, and listen for jobs from the agent pool. | -> | **User** | Can view and use the deployment pool for creating deployment groups. | -> | **Administrator** | Can administer, manage, view and use deployment pools. | \ No newline at end of file + +| Role | Description | +|------|---------| +| **Reader** | View deployment pools. | +| **Service Account** | View agents, create sessions, and listen for jobs from the agent pool. | +| **User** | View and use the deployment pool to create deployment groups. | +| **Administrator** | Administer, manage, view, and use deployment pools. | diff --git a/docs/organizations/security/includes/environment-roles.md b/docs/organizations/security/includes/environment-roles.md index 0dd947d9858..564e6825e69 100644 --- a/docs/organizations/security/includes/environment-roles.md +++ b/docs/organizations/security/includes/environment-roles.md @@ -1,4 +1,17 @@ +::: moniker range="azure-devops" +> [!div class="mx-tdCol2BreakAll"] +> | Role | Description | +> |------------------------------------|---------| +> | **Creator** | Global role, available from environments hub security option. Members of this role can create the environment in the project. Contributors are added as members by default. Required to trigger a YAML pipeline when the environment does not already exist.| +> | **Reader** | Members of this role can view the environment. | +> | **User** | Members of this role can use the environment when creating or editing YAML pipelines. | +> | **Administrator** | Members of this role can administer permissions, create, manage, view and use environments. For a particular environment, its creator is added as Administrator by default. Administrators can also open access to an environment to all pipelines. | +::: moniker-end + +::: moniker range="< azure-devops" +> [!IMPORTANT] +> When you create an environment, only the creator has the administrator role. > [!div class="mx-tdCol2BreakAll"] > | Role | Description | @@ -7,3 +20,4 @@ > | **Reader** | Members of this role can view the environment. | > | **User** | Members of this role can use the environment when creating or editing YAML pipelines. | > | **Administrator** | In addition to using the environment, members of this role can manage membership of all other roles for the environment. Creators are added as members by default. | +::: moniker-end diff --git a/docs/organizations/security/includes/hidden-security-groups.md b/docs/organizations/security/includes/hidden-security-groups.md index 3e8735d4e01..2e3e5563c52 100644 --- a/docs/organizations/security/includes/hidden-security-groups.md +++ b/docs/organizations/security/includes/hidden-security-groups.md @@ -3,26 +3,20 @@ ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.topic: include -ms.date: 04/04/2022 +ms.date: 10/20/2023 --- ::: moniker range="azure-devops" > [!NOTE] -> All security groups are organization-level entities, even those groups that only have permissions to a specific project. From the web portal, visibility of some security groups may be limited based on user permissions. However, you can discover the names of all groups in an organization using the **azure devops** CLI tool or our REST APIs. To learn more, see [Add and manage security groups](../add-manage-security-groups.md). +> Security groups are managed at the organization level, even if they are used for specific projects. Depending on user permissions, some groups might be hidden in the web portal. To view all group names within an organization, you can use the Azure DevOps CLI tool or our REST APIs. For more information, see [Add and manage security groups](../add-manage-security-groups.md). ::: moniker-end ::: moniker range=">= azure-devops-2020 < azure-devops" > [!NOTE] -> All security groups are collection-level entities, even those groups that only have permissions to a specific project. From the web portal, visibility of some security groups may be limited based on user permissions. However, you can discover the names of all groups in an organization using the **azure devops** CLI tool or our REST APIs. To learn more, see [Add and manage security groups](../add-manage-security-groups.md). +> Security groups are managed at the collection level, even if they are used for specific projects. Depending on user permissions, some groups might be hidden in the web portal. To view all group names within a collection, you can use the Azure DevOps CLI tool or our REST APIs. For more information, see [Add and manage security groups](../add-manage-security-groups.md). ::: moniker-end -::: moniker range="< azure-devops-2020" - -> [!NOTE] -> All security groups are collection-level entities, even those groups that only have permissions to a specific project. From the web portal, visibility of some security groups may be limited based on user permissions. However, you can discover the names of all groups in an organization using the REST APIs. To learn more, see [Add and manage security groups](/rest/api/azure/devops/security/?view=azure-devops-rest-6.0&preserve-view=true). - -::: moniker-end diff --git a/docs/organizations/security/includes/library-roles.md b/docs/organizations/security/includes/library-roles.md index 367b5a0fa3c..725509de110 100644 --- a/docs/organizations/security/includes/library-roles.md +++ b/docs/organizations/security/includes/library-roles.md @@ -1,9 +1,8 @@ -> [!div class="mx-tdCol2BreakAll"] -> | Role | Description | -> |------------|-------------| -> | **Administrator** | Can edit/delete and manage security for library items. | -> | **Creator** | Can create library items. | -> | **Reader** | Can only read library items. | -> | **User** | Can consume library items in pipelines. | +| Role | Description | +|------------|-------------| +| **Administrator** | Edit, delete, and manage security for library assets. The creator of an asset is automatically assigned this role for the asset. | +| **Creator** | Create library assets. | +| **Reader** | Read library assets. | +| **User** | Consume library assets in pipelines. | diff --git a/docs/organizations/security/includes/note-collection-level-permissions.md b/docs/organizations/security/includes/note-collection-level-permissions.md index f800832f9d9..8fa900c07a8 100644 --- a/docs/organizations/security/includes/note-collection-level-permissions.md +++ b/docs/organizations/security/includes/note-collection-level-permissions.md @@ -8,7 +8,7 @@ ms.date: 10/25/2022 > [!IMPORTANT] -> The permission to add or remove organization or collection-level security groups, add and manage organization or collection-level group membership, and edit collection and project-level permission ACLs is assigned to all members of the **Project Collection Administrator**s group. It isn't controlled by a permissions surfaced within the user interface. +> The permission to add or remove organization or collection-level security groups, add and manage organization or collection-level group membership, and edit collection and project-level permission ACLs is assigned to all members of the **Project Collection Administrators** group. It isn't controlled by a permissions surfaced within the user interface. > > You can't change the permissions for the **Project Collection Administrators** group. Also, while you can change the permission assignments for a member of this group, their effective permissions will still conform to those assigned to the administrator group for which they are a member. \ No newline at end of file diff --git a/docs/organizations/security/includes/note-group-rules.md b/docs/organizations/security/includes/note-group-rules.md index f4489465da8..46f90d58c3a 100644 --- a/docs/organizations/security/includes/note-group-rules.md +++ b/docs/organizations/security/includes/note-group-rules.md @@ -3,10 +3,11 @@ ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/24/2023 +ms.date: 10/22/2024 --- > [!NOTE] -> We recommend that you regularly review the rules listed on the "Group rules" tab of the "Users" page. If there are any changes made to the Active Directory (AD) group membership, these changes will be reflected in the next re-evaluation of the group rules, which can be done on demand, when a group rule is modified, or automatically every 24 hours. Azure DevOps updates Azure AD group membership every hour, but it may take up to 24 hours for Azure AD to update [dynamic group membership](/azure/active-directory/enterprise-users/groups-dynamic-membership). - \ No newline at end of file +> - Changes made to **project readers** through group rules don't persist. To adjust project readers, consider alternative methods such as [direct assignment](../change-access-levels.md) or [custom security groups](../add-remove-manage-user-group-security-group.md). +> - Regularly review the rules listed on the "Group rules" tab of the "Users" page. Changes to Microsoft Entra ID group membership will appear in the next re-evaluation of the group rules, which can be done on-demand, when a group rule is modified, or automatically every 24 hours. Azure DevOps updates Microsoft Entra group membership every hour, but it may take up to 24 hours for Microsoft Entra ID to update [dynamic group membership](/azure/active-directory/enterprise-users/groups-dynamic-membership). + diff --git a/docs/organizations/security/includes/package-feeds.md b/docs/organizations/security/includes/package-feeds.md index a1acfed3c6b..e4f58f3bddc 100644 --- a/docs/organizations/security/includes/package-feeds.md +++ b/docs/organizations/security/includes/package-feeds.md @@ -5,44 +5,26 @@ ms.date: 04/04/2022 ::: moniker range=">= azure-devops-2020" -Feeds have four permission roles: Readers, Collaborators, Contributors, and Owners. Owners can add user accounts or security groups to any role. - -| Permission | Reader | Collaborator | Contributor | Owner | -| ---------- | ------ | ------------ | ----------- | ----- | -| List, install, and restore packages | ✔️ | ✔️ | ✔️ | ✔️ | -| Push packages | | | ✔️ | ✔️ | -| Unlist/deprecate packages | | | ✔️ | ✔️ | -| Delete/unpublish package | | | | ✔️ | -| Promote a package to a view | | | ✔️ | ✔️ | -| Add/remove upstream sources | | | | ✔️ | -| Save packages from upstream sources | | ✔️ | ✔️ | ✔️ | -| Edit feed permissions | | | | ✔️ | +Feeds have four permission roles: **Feed Reader**, **Feed and Upstream Reader (Collaborator)**, **Feed Publisher (Contributor)**, and **Feed Owner**. Feed Owners can add user accounts or security groups to any role. + +| Permission | Feed Reader | Feed and Upstream Reader (Collaborator) | Feed Publisher (Contributor) | Feed Owner | +| ------------------------------------ | --- | --- | --- | --- | +| List packages in the feed | ✔️ | ✔️ | ✔️ | ✔️ | +| Download/install/restore packages | ✔️ | ✔️ | ✔️ | ✔️ | +| Save packages from upstream sources | | ✔️ | ✔️ | ✔️ | +| Publish packages | | | ✔️ | ✔️ | +| Promote packages to a view | | | ✔️ | ✔️ | +| Deprecate/unlist/yank packages | | | ✔️ | ✔️ | +| Delete/unpublish packages | | | | ✔️ | +| Add/remove upstream sources | | | | ✔️ | +| Allow external package versions | | | | ✔️ | +| Edit feed settings and permissions | | | | ✔️ | By default, the Project Collection Build Service is a Contributor and your project team is a Reader. > [!NOTE] -> To access a feed in a different organization, a user must be given access to the project hosting that feed. +> In Azure Artifacts, feeds may be scoped to a single project or to the entire organization. +> To access a project-scoped feed, a user must also have access to the project containing that feed. ::: moniker-end -::: moniker range="< azure-devops-2020" - -Feeds have three permission roles: Readers, Contributors, and Owners. Owners can add user accounts or security groups -to any role. - - -| Permission | Reader | Contributor | Owner | -| ---------- | ------ | ----------- | ----- | -| List and restore/install packages | ✔️ | ✔️ | ✔️ | -| Push packages | | ✔️| ✔️ | -| Unlist/deprecate packages | | ✔️ | ✔️ | -| Delete/unpublish package | | | ✔️ | -| Edit feed permissions | | | ✔️ | -| [Rename and delete feed](../../../artifacts/index.yml) | | | ✔️ | - - -By default, the Project Collection Build Service is a Contributor and your project team is a Reader. - -> [!NOTE] -> To access a feed in a different organization, a user must be given access to the project hosting that feed. - -::: moniker-end \ No newline at end of file diff --git a/docs/organizations/security/includes/pipelines-build.md b/docs/organizations/security/includes/pipelines-build.md index ad02efa4355..b21224631d9 100644 --- a/docs/organizations/security/includes/pipelines-build.md +++ b/docs/organizations/security/includes/pipelines-build.md @@ -4,27 +4,48 @@ ms.author: chcomley author: chcomley ms.topic: include ms.date: 08/18/2021 +monikerRange: '<= azure-devops' --- - ---> - +::: moniker range="<=azure-devops-2022" +| Task | Readers | Contributors | Build Admins | Project Admins | +|------|:-------:|:------------:|:------------:|:--------------:| +| View builds |✔️|✔️|✔️|✔️| +| View build pipeline |✔️|✔️|✔️|✔️| +| Administer build permissions| | |✔️|✔️| +| Delete or edit build pipeline| |✔️|✔️|✔️| +| Delete or destroy builds | |✔️|✔️|✔️| +|Edit build quality | |✔️|✔️|✔️| +|Manage build qualities | | |✔️|✔️| +|Manage build queue | | |✔️|✔️| +|Override check-in validation by build| | | |✔️| +|Queue builds | |✔️|✔️|✔️| +|Retain indefinitely ||✔️|✔️|✔️| +|Stop builds ||✔️|✔️|✔️| +|Update build information ||✔️|✔️|✔️| -| Task | Readers | Contributors | Build Admins | Project Admins | -|-------------------------|---------|--------------|--------------|----------------| -| View builds | ✔️ | ✔️ | ✔️ | ✔️ | -| View build pipeline | ✔️ | ✔️ | ✔️ | ✔️ | -| Administer build permissions| | | ✔️ | ✔️ | -| Delete or edit build pipeline| | ✔️ | ✔️ | ✔️ | -| Delete or destroy builds | | | ✔️ | ✔️ | -|Edit build quality | | ✔️ | ✔️ | ✔️ | -|Manage build qualities | | | ✔️ | ✔️ | -|Manage build queue | | | ✔️ | ✔️ | -|Override check-in validation by build| | | | ✔️ | -|Queue builds | | ✔️ | ✔️ | ✔️ | -|Retain indefinitely | ✔️| ✔️ | ✔️ | ✔️ | -|Stop builds | ||✔️|✔️| -|Update build information ||||✔️| +::: moniker-end + +::: moniker range="azure-devops" + +| Task | Readers | Contributors | Build Admins | Project Admins | +|------|:-------:|:------------:|:------------:|:--------------:| +| View builds |✔️|✔️|✔️|✔️| +| View build pipeline |✔️|✔️|✔️|✔️| +| Administer build permissions| | |✔️|✔️| +| Create build pipeline| |✔️|✔️|✔️| +| Delete or edit build pipeline| |✔️|✔️|✔️| +| Delete or destroy builds | | |✔️|✔️| +|Edit build quality | |✔️|✔️|✔️| +|Manage build qualities | | |✔️|✔️| +|Manage build queue | | |✔️|✔️| +|Override check-in validation by build| | | |✔️| +|Queue builds | |✔️|✔️|✔️| +|Retain indefinitely ||✔️|✔️|✔️| +|Stop builds | | |✔️|✔️| +|Update build information | | | |✔️| + +::: moniker-end diff --git a/docs/organizations/security/includes/pipelines-cloud.md b/docs/organizations/security/includes/pipelines-cloud.md index cf0cea87018..fe932b044ed 100644 --- a/docs/organizations/security/includes/pipelines-cloud.md +++ b/docs/organizations/security/includes/pipelines-cloud.md @@ -29,6 +29,7 @@ ms.date: 08/18/2021 \ No newline at end of file +--> diff --git a/docs/organizations/security/includes/pipelines-release.md b/docs/organizations/security/includes/pipelines-release.md index 30a002a79d7..b27f4b08d46 100644 --- a/docs/organizations/security/includes/pipelines-release.md +++ b/docs/organizations/security/includes/pipelines-release.md @@ -20,19 +20,19 @@ View releases --> -| Task | Stakeholders | Readers | Contributors | Project Admins | Release Admins | -|-------------------------|---------------|----------|---------------|-------------|----------------| -| Approve releases | ✔️ | | ✔️ | ✔️ | ✔️ | -| View releases | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| View release pipeline | | ✔️ | ✔️ | ✔️ | ✔️ | -| Administer release permissions | | | | ✔️ | ✔️ | -| Delete release pipeline or stage | | | ✔️ | ✔️ | ✔️ | -| Delete releases | | | ✔️ | ✔️ | ✔️ | -| Edit release pipeline | | | | ✔️ | ✔️ | -| Edit release stage | | | ✔️ | ✔️ | ✔️ | -| Manage deployments | | | | ✔️ | ✔️ | -| Manage release approvers | | | ✔️ | ✔️ | ✔️ | -| Manage releases | | | | ✔️ | ✔️ | +| Task | Stakeholders | Readers | Contributors | Project Admins | Release Admins | +|------|:------------:|:-------:|:------------:|:--------------:|:--------------:| +| Approve releases |✔️| |✔️|✔️|✔️| +| View releases |✔️|✔️|✔️|✔️|✔️| +| View release pipeline | |✔️|✔️|✔️|✔️| +| Administer release permissions | | | |✔️|✔️| +| Delete release pipeline or stage | | |✔️|✔️|✔️| +| Delete releases | | |✔️|✔️|✔️| +| Edit release pipeline | | | ✔️|✔️|✔️| +| Edit release stage | | |✔️|✔️|✔️| +| Manage deployments | | | ✔️|✔️|✔️| +| Manage release approvers | | |✔️|✔️|✔️| +| Manage releases | | |✔️|✔️|✔️| diff --git a/docs/organizations/security/includes/prerequisites-server-level.md b/docs/organizations/security/includes/prerequisites-server-level.md index 1afb27f90fd..3e4698a28c5 100644 --- a/docs/organizations/security/includes/prerequisites-server-level.md +++ b/docs/organizations/security/includes/prerequisites-server-level.md @@ -5,13 +5,17 @@ ms.topic: include ## Prerequisites ::: moniker range="azure-devops" - -* You must be the **organization Owner** or a member of the **Project Collection Administrators** group. For more information, see [Change project collection-level permissions](../security/change-organization-collection-level-permissions.md). + +| Category | Requirements | +|--------------|-------------| +|**Permissions** | Member of the [Project Collection Administrators group](../organizations/security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| ::: moniker-end -::: moniker range="< azure-devops" +::: moniker range="< azure-devops" -* You must be a member of the Azure DevOps Server Administrators group. If you aren't a member, get added now. For more information, see [Add server-level administrators](/azure/devops/server/admin/add-administrator). +| Category | Requirements | +|--------------|-------------| +|**Permissions** | Member of the [Azure DevOps Server Administrators group](/azure/devops/server/admin/add-administrator) | -::: moniker-end \ No newline at end of file +::: moniker-end diff --git a/docs/organizations/security/includes/project-level-permissions-reference-table-cloud.md b/docs/organizations/security/includes/project-level-permissions-reference-table-cloud.md index b8ac2a630d9..66bed1cbc74 100644 --- a/docs/organizations/security/includes/project-level-permissions-reference-table-cloud.md +++ b/docs/organizations/security/includes/project-level-permissions-reference-table-cloud.md @@ -33,7 +33,7 @@ ms.date: 10/19/2022 `Project, CHANGE_PROCESS` :::column-end::: :::column span="2"::: - When combined with the 'Edit project-level information' permission, allows users to change the Inheritance process for a project. To learn more, see [Create and manage inherited processes](../../settings/work/manage-process.md). + When combined with the 'Edit project-level information' permission, allows users to change the Inheritance process for a project. For more information, see [Create and manage inherited processes](../../settings/work/manage-process.md). :::column-end::: :::row-end::: :::row::: @@ -47,8 +47,9 @@ ms.date: 10/19/2022 :::row-end::: :::row::: :::column span="4"::: + > [!NOTE] - > All users granted Stakeholder access can only add existing tags. Even if the **Create tag definition** permission is set to **Allow**, stakeholders can't add tags. This is part of the Stakeholder access settings. To learn more, see [Stakeholder access quick reference](../stakeholder-access.md). + > All users granted Stakeholder access can only add existing tags. Even if the **Create tag definition** permission is set to **Allow**, stakeholders can't add tags. This is part of the Stakeholder access settings. For more information, see [Stakeholder access quick reference](../stakeholder-access.md). > Although the **Create tag definition** permission appears > in the security settings at the project-level, > tagging permissions are actually collection level permissions that are scoped @@ -65,7 +66,7 @@ ms.date: 10/19/2022 `Project, PUBLISH_TEST_RESULTS` :::column-end::: :::column span="2"::: - Can add and remove test results and add or modify test runs. To learn more, see [Control how long to keep test results](../../../test/how-long-to-keep-test-results.md) and [Run manual tests](../../../test/run-manual-tests.md). + Can add and remove test results and add or modify test runs. For more information, see [Control how long to keep test results](../../../test/how-long-to-keep-test-results.md) and [Run manual tests](../../../test/run-manual-tests.md). :::column-end::: :::row-end::: :::row::: diff --git a/docs/organizations/security/includes/project-level-permissions.md b/docs/organizations/security/includes/project-level-permissions.md index ece73161143..c8ac02b0c11 100644 --- a/docs/organizations/security/includes/project-level-permissions.md +++ b/docs/organizations/security/includes/project-level-permissions.md @@ -6,15 +6,11 @@ ms.topic: include ms.date: 02/28/2022 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" The following table lists the permissions assigned at the project-level. All of these permissions are granted to members of the **Project Administrators** group, except for the **Delete shared Analytics views** and **Edit shared Analytics views** permissions which are not set. For a description of each permission, see [Permissions and groups reference, Groups](../permissions.md#project-level-permissions). ::: moniker-end -::: moniker range="< azure-devops-2019" -The following table lists the permissions assigned at the project-level. All of these permissions are granted to members of the **Project Collection Administrators** group. For a description of each permission, see [Permissions and groups reference, Groups](../permissions.md#project-level-permissions). -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!NOTE] > Permissions associated with Analytics requires that the Inherited process model is selected for an on-premises project collection. ::: moniker-end @@ -31,7 +27,7 @@ The following table lists the permissions assigned at the project-level. All of - Update project visibility - View project-level information ::: moniker-end - ::: moniker range=">= azure-devops-2019 < azure-devops" + ::: moniker range=" [!div class="mx-tdCol2BreakAll"] -> | Role | Description | -> |-------------|---------| -> | **User** | Can use the endpoint when authoring build or release pipelines. | -> | **Administrator** | Can manage membership of all other roles for the service connection as well as use the endpoint to author build or release pipelines. The system automatically adds the user that created the service connection to the Administrator role for that pool. | \ No newline at end of file + +| Role | Description | +|-------------|---------| +| **User** | Use the endpoint when authoring build or release pipelines. | +| **Administrator** | Manage membership of all other roles for the service connection and use the endpoint to author build or release pipelines. The system automatically assigns the user who created the service connection to the Administrator role for that pool. | diff --git a/docs/organizations/security/includes/task-groups.md b/docs/organizations/security/includes/task-groups.md index 5f7f5a1fe18..9738c24d773 100644 --- a/docs/organizations/security/includes/task-groups.md +++ b/docs/organizations/security/includes/task-groups.md @@ -15,8 +15,8 @@ Edit task group --> -|Task|Readers|Contributors|Build Admins|Project Admins|Release Admins| -|----|-------|------------|------------|--------------|--------------| -|Administer task group permissions| | |✔️|✔️|✔️| -|Delete task group| | |✔️|✔️|✔️| -|Edit task group| | |✔️|✔️|✔️| +|Task |Readers|Contributors|Build Admins|Project Admins|Release Admins| +|---- |:-------:|:------------:|:------------:|:--------------:|--------------| +|Administer task group permissions| | |✔️ |✔️ |✔️ | +|Delete task group | | |✔️ |✔️ |✔️ | +|Edit task group | |✔️ |✔️ |✔️ |✔️ | diff --git a/docs/organizations/security/includes/test.md b/docs/organizations/security/includes/test.md index 91593369c16..de843c2c7ed 100644 --- a/docs/organizations/security/includes/test.md +++ b/docs/organizations/security/includes/test.md @@ -7,7 +7,6 @@ ms.date: 09/15/2021 --- - :::row::: :::column span="2"::: **Permission** @@ -151,8 +150,7 @@ ms.date: 09/15/2021 :::column-end::: :::row-end::: - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!NOTE] > The **Change work item type** permission doesn't apply to test-specific work items. Even if you choose this feature from the work item form, changing the work item type is disallowed. ::: moniker-end \ No newline at end of file diff --git a/docs/organizations/security/index.yml b/docs/organizations/security/index.yml index f230505c490..a2d2438193d 100644 --- a/docs/organizations/security/index.yml +++ b/docs/organizations/security/index.yml @@ -9,9 +9,9 @@ metadata: description: Assign users to security groups, manage permissions, access levels, and billing for Azure DevOps. ms.subservice: azure-devops-security ms.topic: landing-page - author: KathrynEE - ms.author: kaelli - ms.date: 02/18/2022 + author: chcomley + ms.author: chcomley + ms.date: 07/03/2024 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -25,6 +25,8 @@ landingContent: links: - text: About permissions, access, and security groups url: about-permissions.md + - text: Security overview + url: security-overview.md - linkListType: quickstart links: - text: View permissions @@ -37,7 +39,7 @@ landingContent: url: request-changes-permissions.md - text: Add or remove users or security groups url: add-remove-manage-user-group-security-group.md - - title: Access levels + - title: Manage access linkLists: - linkListType: concept links: @@ -47,36 +49,22 @@ landingContent: url: stakeholder-access.md - linkListType: quickstart links: - - text: Add users or groups to an access level (on-premises) + - text: Change access levels (on-premises) url: change-access-levels.md?view=azure-devops-2020&preserve-view=true + - text: Add users or groups to a team or project (on-premises) + url: add-users-team-project.md - linkListType: tutorial links: - text: Get started as a Stakeholder url: get-started-stakeholder.md - - title: Manage user access (cloud) - linkLists: - - linkListType: quickstart + - linkListType: how-to-guide links: - text: Create an organization url: ../accounts/create-organization.md?toc=/azure/devops/organizations/security/toc.json - - linkListType: how-to-guide - links: - text: Add users to your organization url: ../accounts/add-organization-users.md?toc=/azure/devops/organizations/security/toc.json - - text: Connect your organization to Azure Active Directory + - text: Connect your organization to Microsoft Entra ID url: ../accounts/connect-organization-to-azure-ad.md?toc=/azure/devops/organizations/security/toc.json - - text: Provide Stakeholders access to edit pipelines - url: provide-stakeholder-pipeline-access.md - - title: Manage user access (on-premises) - linkLists: - - linkListType: quickstart - links: - - text: Change access levels - url: change-access-levels.md - - linkListType: how-to-guide - links: - - text: Add users or groups to a team or project - url: add-users-team-project.md - title: Manage billing linkLists: - linkListType: overview @@ -88,10 +76,10 @@ landingContent: - text: Buy Basic access url: ../billing/buy-basic-access-add-users.md - text: Set up billing for your organization - url: ../billing/set-up-billing-for-your-organization-vs.md + url: ../billing/set-up-billing-for-your-organization-vs.md#set-up-billing - text: Try Azure Test Plans for free url: ../billing/try-additional-features-vs.md - - title: Authenticate, PATs, & secure applications + - title: Authenticate, use PATs, & secure applications linkLists: - linkListType: concept links: @@ -129,20 +117,12 @@ landingContent: linkLists: - linkListType: overview links: - - text: Security quick reference index - url: quick-reference-index-security.md - text: Default permissions quick reference url: permissions-access.md - - text: Security management tools - url: security-tools-reference.md - - linkListType: concept - links: - - text: Security key concepts - url: security-glossary.md - linkListType: reference links: - text: Permissions lookup guide url: permissions-lookup-guide.md - text: Permissions and groups reference url: permissions.md - \ No newline at end of file + diff --git a/docs/organizations/security/look-up-organization-owner.md b/docs/organizations/security/look-up-organization-owner.md index 8be6f9f44a0..9551c2195fc 100644 --- a/docs/organizations/security/look-up-organization-owner.md +++ b/docs/organizations/security/look-up-organization-owner.md @@ -1,43 +1,45 @@ --- -title: Find or lookup the organization owner +title: Find or look up the organization owner titleSuffix: Azure DevOps -description: How-to guide to learn who is the owner of your organization +description: How-to guide for finding the owner of your organization. ms.subservice: azure-devops-security ms.custom: security-refresh ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: 'azure-devops' -ms.date: 02/7/2022 +ms.date: 07/29/2024 --- # Look up the organization owner [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Each organization has one and only one owner. The **Organization owner** has permissions to add users, change the access level for a user or group, manage permissions at all levels, and configure and customize all projects defined for the organization. +Each organization has a single owner who can add users, adjust access levels, manage permissions, and customize projects. You can find the owner in your organization settings. To change the **Organization owner**, see [Change organization owner](../accounts/change-organization-ownership.md). ## Prerequisites -* You must be a member of the **Project Collection Valid Users** group to look up the organization owner or view organization settings. Users added to a project are automatically added to this group. - +[!INCLUDE [prerequisites-project-collection-valid-users-group](../../includes/prerequisites-project-collection-valid-users-group.md)] -## Look up the organization owner +## Find the organization owner -1. Choose the Azure DevOps logo :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: to open **Projects**, and then choose :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: **Organization settings**. +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). - ![Open organization settings](../../media/open-organization-settings-preview.png) + :::image type="content" source="../../media/open-organization-settings-preview.png" alt-text="Screenshot showing Organization settings button in Azure DevOps."::: -2. Choose **Overview** and scroll down to show the **Organization owner**. +2. Select **Overview**. + + :::image type="content" source="../accounts/media/shared/organization-settings-select-overview.png" alt-text="Screenshot showing the Overview button highlighted in Azure DevOps."::: + +3. Scroll to view the **Organization owner**. > [!div class="mx-imgBorder"] - > ![Organization settings, Organization owner](../../media/settings/organization-settings-info.png) + > ![Screenshot showing the Organization owner on the Overview page.](../../media/settings/organization-settings-info.png) - ## Next steps > [!div class="nextstepaction"] @@ -47,6 +49,5 @@ To change the **Organization owner**, see [Change organization owner](../account - [Request an increase in permission levels](request-changes-permissions.md) - [Look up a project administrator](look-up-project-administrators.md) -- [Change project collection-level permissions](change-organization-collection-level-permissions.md) - [Permissions lookup guide](permissions-lookup-guide.md) -- [Default permissions and access](permissions-access.md). +- [About permissions, access, & security](about-permissions.md) diff --git a/docs/organizations/security/look-up-project-administrators.md b/docs/organizations/security/look-up-project-administrators.md index 40f3ab9b42a..e6a8642d44a 100644 --- a/docs/organizations/security/look-up-project-administrators.md +++ b/docs/organizations/security/look-up-project-administrators.md @@ -1,43 +1,40 @@ --- title: Find a project administrator titleSuffix: Azure DevOps -description: Quickstart guide to learn who is a member of the Project Administrators group in Azure DevOps +description: Quickly identify members of the Project Administrators group in Azure DevOps. ms.subservice: azure-devops-security ms.custom: security-refresh ms.author: chcomley author: chcomley ms.topic: quickstart monikerRange: '<= azure-devops' -ms.date: 02/11/2022 +ms.date: 07/12/2024 --- # Look up a project administrator [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The **Project Administrators** group is the main administrative security group defined for a project. Members of the **Project Administrators** group have permissions to perform the following common tasks: +The **Project Administrators** group is the primary administrative security group for a project, with members authorized to do the following tasks: -- Delete and rename the project -- Add users and teams to the project -- Add and manage **Area Paths** and **Iteration Paths** -- Add and manage shared query folders -- Add members and groups to the **Project Administrators** group or any other project-level group -- Manage permissions at the project-level or for any object defined for the project. +- **Delete or rename** a project +- **Add users and teams** to a project +- **Manage Area Paths and Iteration Paths** +- **Organize shared query folders** +- **Adjust group memberships**, including adding members to the **Project Administrators** group or other project-level groups +- **Control permissions** at the project level and for project-defined objects -To add members to the **Project Administrators** group or change a project-level permission see [Change project-level permissions](change-project-level-permissions.md). - -For a description of each project-level group, see [Security groups, service accounts, and permissions, Project-level groups](permissions.md#project-level-groups). To understand how security groups are used to manage permissions, see [Get started with permissions, access, and security groups](about-permissions.md). +To add users to the **Project Administrators** group or change a project-level permission see [Change project-level permissions](change-project-level-permissions.md). ## Prerequisites -* You must be a member of the **Project Collection Valid Users** group to look up members of the **Project Administrators** group. Users added to a project are automatically added to this group. +[!INCLUDE [prerequisites-project-collection-valid-users-group](../../includes/prerequisites-project-collection-valid-users-group.md)] -## Show members of the Project Administrators group +## Identify members of the Project Administrators group -Choose the **Project Administrators** group from the **Project Settings > Permissions** page to see members. +Do the following steps to identify members of the **Project Administrators** group. ::: moniker range="azure-devops" - > [!NOTE] > To enable the **Project Permissions Settings Page** preview page, see [Enable preview features](../../project/navigation/preview-features.md). @@ -47,82 +44,62 @@ Choose the **Project Administrators** group from the **Project Settings > Permis #### [Preview page](#tab/preview-page) -1. Open the web portal and choose your project. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). -2. Choose **Project settings**, and then **Permissions**. +2. Select **Project settings** > **Permissions**. - ![Choose Project settings > Permissions](../settings/media/shared/open-project-settings-permissions-preview.png) + ![Screenshot showing Choose Project settings > Permissions.](../settings/media/shared/open-project-settings-permissions-preview.png) -3. Choose **Project Administrators** group, and then **Members**. +3. Select **Project Administrators** > **Members**. > [!div class="mx-imgBorder"] - > ![Project Settings, Permissions page, Add member](media/project-collection/project-admin-members-tab-s154.png) + > ![Screenshot showing Project Settings, Permissions page, Add member option.](media/project-collection/project-admin-members-tab-s154.png) -4. Enter the name of the user account into the text box and then select from the match that appears. You can enter several identities recognized by the system into the **Add users and/or groups** box. The system automatically searches for matches. Choose the matches that meet your choices. +4. Enter the name of the user account into the text box and then select from the match that appears. You can enter several identities recognized by the system into the **Add users and/or groups** box. The system automatically searches for matches. Select your match. > [!div class="mx-imgBorder"] > ![Add users and group dialog](media/project-collection/add-member-project-admin.png) > [!NOTE] - > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see [Permissions and access](permissions-access.md). + > Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. For more information, see [Permissions and access](permissions-access.md). -5. Choose **Save**. +5. Select **Save**. #### [Current page](#tab/current-page) -1. Open the web portal and choose your project. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). - -2. Choose **Project Settings**, and then **Security**. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). - *To see the full image, click to expand*. +2. Select **Project settings** > **Security**. - [![Project Settings>Security](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) + [![Screenshot of Project Settings>Security selection.](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) -3. Choose **Project Administrators** group, and then the **Members** tab. The list of members is shown. +3. Select **Project Administrators** > **Members**. > [!div class="mx-imgBorder"] - > ![Project Settings>Security, Add member](media/project-level-permissions-add-member.png) - -* * * + > ![Screenshot of Project Settings>Security, Add member option.](media/project-level-permissions-add-member.png) -::: moniker-end +The display presents a list of the Project Collection Administrators group's members. -::: moniker range=">= azure-devops-2019 < azure-devops" +* * * +::: moniker-end -1. Open the web portal and choose your project. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). +::: moniker range="< azure-devops" -2. Choose **Project Settings**, and then **Security**. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). - *To see the full image, click to expand*. +2. Select **Project Settings** > **Security**. - [![Project Settings>Security](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) + [![Screenshot shows Project Settings>Security.](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) -3. Choose the **Members** tab. The list of members is shown. +3. Select **Members**. > [!div class="mx-imgBorder"] > ![Web portal, Security tab, Project Administrators Group, Members tab](media/view-permissions-project-level-membership.png) -::: moniker-end - - -::: moniker range="tfs-2018" - -1. Open the web portal and choose your project. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). - -2. Choose the :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: gear icon to open **Project Settings**. - - ![Open Project Settings, horizontal nav](../../media/settings/open-project-settings-horz.png) - -3. Choose the **Security** page, **Project Administrators** group, and then the **Members** tab. - - The list of members is shown. - - > [!div class="mx-imgBorder"] - > ![Web portal, Security tab, Project Administrators Group, Members tab](media/view-permissions-project-level-membership.png) +The display presents a list of the Project Collection Administrators group's members. ::: moniker-end - ## Next steps diff --git a/docs/organizations/security/look-up-project-collection-administrators.md b/docs/organizations/security/look-up-project-collection-administrators.md index 2a64d5bcf2a..f8ccc207d4e 100644 --- a/docs/organizations/security/look-up-project-collection-administrators.md +++ b/docs/organizations/security/look-up-project-collection-administrators.md @@ -1,115 +1,84 @@ --- title: Look up a project collection administrator titleSuffix: Azure DevOps -description: How-to guide to learn who is a member of the Project Collection Administrators group in Azure DevOps +description: Learn how to identify members of the Project Collection Administrators group in Azure DevOps. ms.subservice: azure-devops-security ms.custom: security-refresh ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 02/7/2022 +ms.date: 07/12/2024 --- # Look up a project collection administrator [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -The **Project Collection Administrators** group is the main administrative security group defined for an organization or project collection. Members of the **Project Collection Administrators** group have permissions to perform the following common tasks: - -::: moniker range="azure-devops" -- Add users to a collection -- Create and manage all projects in the organization or collection -- Create and manage all Inherited processes defined for a collection -- Install and uninstall extensions -- Add members and groups to the **Project Collection Administrators** group or any other project-level group -- Manage permissions at all levels. -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" -- Add users to a collection -- Create and manage all projects in the organization or collection -- Create and manage all Inherited processes defined for a collection -- Import and export On-premises XML process templates to a collection -- Install and uninstall extensions -- Add members and groups to the **Project Collection Administrators** group or any other project-level group -- Manage permissions at all levels. -::: moniker-end - -::: moniker range="< azure-devops-2019" -- Add users to a collection -- Create and manage all projects in the organization or collection -- Import and export On-premises XML process templates to a collection -- Install and uninstall extensions -- Add members and groups to the **Project Collection Administrators** group or any other project-level group -- Manage permissions at all levels. -::: moniker-end +The **Project Collection Administrators** group is a pivotal security group within an organization or collection, with members empowered to do the following tasks: +::: moniker range="azure-devops" +- **Add users** to a collection +- **Create and manage projects** within an organization or collection +- **Define and oversee Inherited processes** for a collection +- **Install and uninstall extensions** +- **Modify group memberships**, including adding members to the Project Collection Administrators group or other project-level groups +- **Manage permissions** across all levels +::: moniker-end +::: moniker range="< azure-devops" +- **Add users** to a collection +- **Create and manage projects** within an organization or collection +- **Create and manage Inherited processes** defined for a collection +- **Import and export On-premises XML process templates** to a collection +- **Install and uninstall extensions** +- **Add members and groups to the Project Collection Administrators group** or any other project-level group +- **Manage permissions** across all levels +::: moniker-end To add members to the **Project Collection Administrators** group or change a project collection-level permission see [Change project collection-level permissions](change-organization-collection-level-permissions.md). -For a description of each project collection-level group, see [Security groups, service accounts, and permissions, Collection-level groups](permissions.md#collection-level-groups). To understand how security groups are used to manage permissions, see [Get started with permissions, access, and security groups](about-permissions.md). +For more information, see [Get started with permissions and security groups](about-permissions.md). ## Prerequisites -* You must be a member of the **Project Collection Valid Users** group to look up members of the **Project Collection Administrators** group. Users added to a project are automatically added to this group. - - -::: moniker range="azure-devops" -> [!NOTE] -> Users added to the **Project-Scoped Users** group won't be able to access **Organization Settings** other than the **Overview** section if the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization. For more information including important security-related call-outs, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). +[!INCLUDE [prerequisites-project-collection-valid-users-group](../../includes/prerequisites-project-collection-valid-users-group.md)] -::: moniker-end ## Show members of the Project Collection Administrators group ::: moniker range="azure-devops" -To find out who is a member of the **Project Collection Administrators** group, check the **Permissions** settings at the collection level. +To identify members of the **Project Collection Administrators** group, do the following steps. > [!NOTE] -> To enable the **Organization Permissions Settings Page v2** preview page, see [Enable preview features](../../project/navigation/preview-features.md). The preview page provides a group settings page that the current page does not. +> To enable the **Organization Permissions Settings Page v2** preview page, see [Enable preview features](../../project/navigation/preview-features.md). The preview page provides a group settings page that the current page doesn't. -1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open your projects, and then choose :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: **Organization settings**. +1. Select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open your projects, and then select :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: **Organization settings**. - ![Open Organization settings](../../media/open-organization-settings-preview.png) + ![Screenshot showing Opening Organization settings.](../../media/open-organization-settings-preview.png) -2. Choose **Permissions** under the Security group, and then **Project Collection Administrators** > **Members** tab. +2. Select **Permissions** > **Project Collection Administrators** > **Members**. > [!div class="mx-imgBorder"] - > ![Security, Project Collection Administrators group, Members tab](media/project-collection/project-collection-admins-members-tab-s157.png) + > ![Screenshot of Security, Project Collection Administrators group, Members tab.](media/project-collection/project-collection-admins-members-tab-s157.png) ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="< azure-devops" -To find out who is a member, check the **Security** settings at the collection level. +To identify members, do the following steps. -1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**, and then choose **Organization settings**. +1. Select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**, and then select **Organization settings**. - ![Open Organization settings](../../pipelines/agents/media/agent-pools-tab/organization-settings.png) + ![Screenshot of opening Organization settings.](../../pipelines/agents/media/agent-pools-tab/organization-settings.png) -2. Choose **Security**, the **Project Collection Administrators** group, and then **Members**. +2. Select **Security** > **Project Collection Administrators** > **Members**. > [!div class="mx-imgBorder"] - > ![Security, Project Collection Administrators group, Members tab](media/view-permissions/collection-admins-vert.png) + > ![Screenshot of Security, Project Collection Administrators group, Members tab.](media/view-permissions/collection-admins-vert.png) ::: moniker-end -::: moniker range="tfs-2018" - -1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: settings icon and choose **Collection settings**. - - > [!div class="mx-imgBorder"] - > ![Open Organization Settings](../../media/settings/open-account-settings.png) - -2. Choose **Security**, **Project Collection Administrators** group, and then **Members**. - - ![Security, Project Collection Administrators group, Members tab](media/view-permissions/collection-admins.png) - -::: moniker-end - - +The display shows a list of users who are part of the **Project Collection Administrators** group. ## Next steps @@ -120,4 +89,6 @@ To find out who is a member, check the **Security** settings at the collection l - [Change project collection-level permissions](change-organization-collection-level-permissions.md) - [Permissions lookup guide](permissions-lookup-guide.md) -- [Default permissions and access](permissions-access.md). +- [Default permissions and access](permissions-access.md) +- [Get started with permissions, access, and security groups](about-permissions.md) +- [Look up the organization owner](look-up-organization-owner.md) diff --git a/docs/organizations/security/manage-tokens-namespaces.md b/docs/organizations/security/manage-tokens-namespaces.md index 5101912e17f..716dfe1733b 100644 --- a/docs/organizations/security/manage-tokens-namespaces.md +++ b/docs/organizations/security/manage-tokens-namespaces.md @@ -18,23 +18,21 @@ ms.date: 03/31/2022 Permissions grant access to perform a specific action on a specific resource as described in [Get started with permissions, access, and security groups](about-permissions.md). You manage most permissions through the web portal. However, you can manage permissions using command line tools or the REST API. -Azure DevOps grants a number of permissions by default to members of default security groups. You can add and manage permissions at a more granular level with the `az devops security permission` commands. Use these commands to: +Azure DevOps grants many permissions by default to members of default security groups. You can add and manage permissions at a more granular level with the `az devops security permission` commands. Use these commands to: - View the permissions associated with security namespaces - View details about those permissions - Update or reset permissions > [!NOTE] -> Namespaces and tokens are valid for all versions of Azure DevOps. Those listed here are valid for Azure DevOps 2019 and later versions. Namespaces are subject to change over time. To get the latest list of namespaces, exercise one of the command line tools or REST API. Some namespaces have been deprecated as listed in the [Security namespace and permission reference, Deprecated and read-only namespaces](namespace-reference.md#deprecated-namespaces).. +> Namespaces and tokens are valid for all versions of Azure DevOps. Namespaces are subject to change over time. To get the latest list of namespaces, exercise one of the command line tools or REST API. Some namespaces have been deprecated as listed in the [Security namespace and permission reference, Deprecated and read-only namespaces](namespace-reference.md#deprecated-namespaces). > ## Prerequisites -- To manage tokens and namespaces, you must be a member of the Project Collection Administrators security group. For more information on tokens, see [Security namespace and permission reference](namespace-reference.md). -- You must have installed the Azure DevOps CLI extension as described in [Get started with Azure DevOps CLI](../../cli/index.md). -- Sign into Azure DevOps using `az login`. -- For the examples in this article, set the default organization as follows: - - For **Azure DevOps Services**: `az devops configure --defaults organization=YourOrganizationURL`. - - For **Azure DevOps Server**: `az devops configure --defaults organization=https://ServerName/CollectionName` +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the [Project Collection Administrators group](../security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group. For more information on tokens, see [Security namespace and permission reference](namespace-reference.md). | +|**Tools**| [Azure DevOps CLI extension](../../cli/index.md).
      - Sign in using `az login`.
      - For the examples in this article, set the default organization as follows:
      - **Azure DevOps Services**: `az devops configure --defaults organization=YourOrganizationURL`.
      - **Azure DevOps Server**: `az devops configure --defaults organization=https://ServerName/CollectionName`| ## Security permission commands @@ -61,11 +59,11 @@ The following parameters are optional for all commands, and not listed in the ex - **detect**: Automatically detect organization. Accepted values: false, true. Default is true. - **org**: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up via git config. Example: `--org https://dev.azure.com/MyOrganizationName/`. - + ## List security namespaces -You can list all available namespaces for an organization with the [az devops security permission namespace list](/cli/azure/devops/security/permission/namespace#az-devops-security-permission-namespace-list) command. For a description of all security namespaces and associated tokens, see [Security namespace and permission reference](namespace-reference.md). +You can list all available namespaces for an organization with the [az devops security permission namespace list](/cli/azure/devops/security/permission/namespace#az-devops-security-permission-namespace-list) command. For a description of all security namespaces and associated tokens, see [Security namespace and permission reference](namespace-reference.md). > [!div class="tabbedCodeSnippets"] ```azurecli @@ -74,10 +72,9 @@ az devops security permission namespace list [--local-only] ### Parameters -- **local-only**: Optional. If true, retrieve only local security namespaces. - - Security namespaces may have their data mastered in one microservice, but still be visible in other microservices. If a security namespace's data is mastered in microservice X, it is said to be local to that microservice. Otherwise, it is said to be remote. +**local-only**: Optional. If true, retrieve only local security namespaces. +Security namespaces might have their data managed in one microservice, but still be visible in other microservices. If a security namespace's data is managed in microservice X, it's local to that microservice. Otherwise, it's remote. Enter `az devops security permission namespace list` to list the namespaces defined for your organization or on-premises server. @@ -236,7 +233,7 @@ az devops security permission list --id ### Parameters -- - **id** or **namespace-id**: Required. ID of security namespace. To obtain the ID, use the [az devops security permission namespace list](#list-namespaces) command. +- **id** or **namespace-id**: Required. ID of security namespace. To obtain the ID, use the [az devops security permission namespace list](#list-namespaces) command. - **subject**: Required. The email address or group descriptor of the user. - **recurse**: Optional. If true, and the namespace is hierarchical, this parameter returns the child ACLs of the tokens. - **token**: Optional. Specify an individual security token. @@ -263,11 +260,11 @@ $/56af920d-393b-4236-9a07-24439ccaa85c 0 0 $/69265579-a1e0-4a30-a141-ac9e3bb82572 0 0 ``` - + ## Show namespace details -You can show details of permissions available in each namespace with the [az devops security permission namespace show](/cli/azure/devops/security/permission/namespace#az-devops-security-permission-namespace-show) command. +Show details of permissions available in each namespace with the [az devops security permission namespace show](/cli/azure/devops/security/permission/namespace#az-devops-security-permission-namespace-show) command. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -298,7 +295,7 @@ ReadEuii Read EUII data ## Reset permissions -You can reset the permission bits for a specified user or group with the [az devops security permission reset](/cli/azure/devops/security/permission#az-devops-security-permission-reset) command. +Reset the permission bits for a specified user or group with the [az devops security permission reset](/cli/azure/devops/security/permission#az-devops-security-permission-reset) command. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -411,12 +408,15 @@ az devops security permission update --id ### Parameters -- **id** or **namespace-id**: Required. ID of security namespace. -- **subject**: Required. The email address or group descriptor of the user. -- **token**: Required. Individual security token. -- **allow-bit**: Optional. Allow bit or addition of bits. Required if **--deny-bit** is missing. -- **deny-bit**: Optional. Deny bit or addition of bits. Required if **--allow-bit** is missing. -- **merge**: Optional. If set, the existing access control entry (ACE) has its allow and deny merged with the incoming ACE's allow and deny. If unset, the existing ACE is displaced. The accepted values are *false* or *true*. +- **id** or **namespace-id**: *Required.* The ID of the security namespace. +- **subject**: *Required.* The email address or group descriptor of the user. +- **token**: *Required.* An individual security token. +- **allow-bit**: *Optional.* Specifies the allow bit or adds more bits. **Required** if **deny-bit** isn't provided. +- **deny-bit**: *Optional.* Specifies the deny bit or adds other bits. **Required** if **allow-bit** isn't provided. +- **merge**: *Optional.* Determines whether to merge with existing access control entries (ACE). + - If set to **true**, the existing ACEs allow and deny permissions merge with those permissions of the incoming ACE. + - If set to **false** or omitted, the existing ACE is replaced. + - Accepted values are `true` or `false`. ### Example @@ -438,8 +438,5 @@ See [Security namespace and permission reference for Azure DevOps](namespace-ref ## Related articles - [Security namespace and permission reference](namespace-reference.md) -- [Security Namespaces REST API](/rest/api/azure/devops/security/security%20namespaces) -- [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd) -- [Security glossary](security-glossary.md) - - +- [Security namespaces REST API](/rest/api/azure/devops/security/security%20namespaces) +- [Use TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd) diff --git a/docs/organizations/security/media/about-security/add-azure-active-directory-groups.png b/docs/organizations/security/media/about-security/add-azure-active-directory-groups.png deleted file mode 100644 index 89d5dfa38b9..00000000000 Binary files a/docs/organizations/security/media/about-security/add-azure-active-directory-groups.png and /dev/null differ diff --git a/docs/organizations/security/media/add-groups/add-new-group-dialog.png b/docs/organizations/security/media/add-groups/add-new-group-dialog.png deleted file mode 100644 index ce36c21d0f3..00000000000 Binary files a/docs/organizations/security/media/add-groups/add-new-group-dialog.png and /dev/null differ diff --git a/docs/organizations/security/media/add-users/add-members-to-contributors-group.png b/docs/organizations/security/media/add-users/add-members-to-contributors-group.png index 31df3004960..f60934fed22 100644 Binary files a/docs/organizations/security/media/add-users/add-members-to-contributors-group.png and b/docs/organizations/security/media/add-users/add-members-to-contributors-group.png differ diff --git a/docs/organizations/security/media/add-users/direct-members-remove.png b/docs/organizations/security/media/add-users/direct-members-remove.png index c2f6958e1c6..3556ba3a684 100644 Binary files a/docs/organizations/security/media/add-users/direct-members-remove.png and b/docs/organizations/security/media/add-users/direct-members-remove.png differ diff --git a/docs/organizations/security/media/add-users/invite-members-to-contributors-group.png b/docs/organizations/security/media/add-users/invite-members-to-contributors-group.png new file mode 100644 index 00000000000..a02ca1c56b0 Binary files /dev/null and b/docs/organizations/security/media/add-users/invite-members-to-contributors-group.png differ diff --git a/docs/organizations/security/media/add-users/selected-contributors.png b/docs/organizations/security/media/add-users/selected-contributors.png new file mode 100644 index 00000000000..7b4d5d5937c Binary files /dev/null and b/docs/organizations/security/media/add-users/selected-contributors.png differ diff --git a/docs/organizations/security/media/add-users/selected-members-in-contributor-group.png b/docs/organizations/security/media/add-users/selected-members-in-contributor-group.png new file mode 100644 index 00000000000..bc95f04289d Binary files /dev/null and b/docs/organizations/security/media/add-users/selected-members-in-contributor-group.png differ diff --git a/docs/organizations/security/media/add-users/team-profile-choose-add-preview.png b/docs/organizations/security/media/add-users/team-profile-choose-add-preview.png deleted file mode 100644 index 2a3fd9c715b..00000000000 Binary files a/docs/organizations/security/media/add-users/team-profile-choose-add-preview.png and /dev/null differ diff --git a/docs/organizations/security/media/change-project-level/choose-users-select-user.png b/docs/organizations/security/media/change-project-level/choose-users-select-user.png index e07c4c28182..70f95b95843 100644 Binary files a/docs/organizations/security/media/change-project-level/choose-users-select-user.png and b/docs/organizations/security/media/change-project-level/choose-users-select-user.png differ diff --git a/docs/organizations/security/media/permissions/choose-project-settings-permissions.png b/docs/organizations/security/media/permissions/choose-project-settings-permissions.png index fff1ffac229..137bf8f01b7 100644 Binary files a/docs/organizations/security/media/permissions/choose-project-settings-permissions.png and b/docs/organizations/security/media/permissions/choose-project-settings-permissions.png differ diff --git a/docs/organizations/security/media/permissions/collection-level-permissions-new.png b/docs/organizations/security/media/permissions/collection-level-permissions-new.png index c0cec7049f4..1ca8ac7b8c2 100644 Binary files a/docs/organizations/security/media/permissions/collection-level-permissions-new.png and b/docs/organizations/security/media/permissions/collection-level-permissions-new.png differ diff --git a/docs/organizations/security/media/permissions/create-group-dialog.png b/docs/organizations/security/media/permissions/create-group-dialog.png deleted file mode 100644 index 57254e565ec..00000000000 Binary files a/docs/organizations/security/media/permissions/create-group-dialog.png and /dev/null differ diff --git a/docs/organizations/security/media/permissions/edit-build-pipeline-object-level-permissions-s163.png b/docs/organizations/security/media/permissions/edit-build-pipeline-object-level-permissions-s163.png index 13193a32a87..9e34d654284 100644 Binary files a/docs/organizations/security/media/permissions/edit-build-pipeline-object-level-permissions-s163.png and b/docs/organizations/security/media/permissions/edit-build-pipeline-object-level-permissions-s163.png differ diff --git a/docs/organizations/security/media/permissions/open-project-settings-permissions-preview.png b/docs/organizations/security/media/permissions/open-project-settings-permissions-preview.png index 34fce1cba43..d2bc5797313 100644 Binary files a/docs/organizations/security/media/permissions/open-project-settings-permissions-preview.png and b/docs/organizations/security/media/permissions/open-project-settings-permissions-preview.png differ diff --git a/docs/organizations/security/media/permissions/pipeline-object-level-permissions-cloud.png b/docs/organizations/security/media/permissions/pipeline-object-level-permissions-cloud.png index df493e75442..2952e803e46 100644 Binary files a/docs/organizations/security/media/permissions/pipeline-object-level-permissions-cloud.png and b/docs/organizations/security/media/permissions/pipeline-object-level-permissions-cloud.png differ diff --git a/docs/organizations/security/media/permissions/project-permissions-contributors.png b/docs/organizations/security/media/permissions/project-permissions-contributors.png index 1712aec7762..56c911f863d 100644 Binary files a/docs/organizations/security/media/permissions/project-permissions-contributors.png and b/docs/organizations/security/media/permissions/project-permissions-contributors.png differ diff --git a/docs/organizations/security/media/project-collection/add-member-project-admin.png b/docs/organizations/security/media/project-collection/add-member-project-admin.png index 706a17823bf..cf497d77bbb 100644 Binary files a/docs/organizations/security/media/project-collection/add-member-project-admin.png and b/docs/organizations/security/media/project-collection/add-member-project-admin.png differ diff --git a/docs/organizations/security/media/project-collection/create-new-group-at-org-level.png b/docs/organizations/security/media/project-collection/create-new-group-at-org-level.png index baf4ff543b4..c799c2cab7a 100644 Binary files a/docs/organizations/security/media/project-collection/create-new-group-at-org-level.png and b/docs/organizations/security/media/project-collection/create-new-group-at-org-level.png differ diff --git a/docs/organizations/security/media/project-collection/delete-restore-work-items-permissions-s154.png b/docs/organizations/security/media/project-collection/delete-restore-work-items-permissions-s154.png index d28ead1ccfd..6ad99147f9a 100644 Binary files a/docs/organizations/security/media/project-collection/delete-restore-work-items-permissions-s154.png and b/docs/organizations/security/media/project-collection/delete-restore-work-items-permissions-s154.png differ diff --git a/docs/organizations/security/media/project-collection/project-admin-members-add-s154.png b/docs/organizations/security/media/project-collection/project-admin-members-add-s154.png deleted file mode 100644 index b526936f7a9..00000000000 Binary files a/docs/organizations/security/media/project-collection/project-admin-members-add-s154.png and /dev/null differ diff --git a/docs/organizations/security/media/project-collection/project-admin-members-add.png b/docs/organizations/security/media/project-collection/project-admin-members-add.png new file mode 100644 index 00000000000..3f2550418d3 Binary files /dev/null and b/docs/organizations/security/media/project-collection/project-admin-members-add.png differ diff --git a/docs/organizations/security/media/project-collection/project-collection-admins-members-tab-s157.png b/docs/organizations/security/media/project-collection/project-collection-admins-members-tab-s157.png index 84251b253a0..90bc2b10029 100644 Binary files a/docs/organizations/security/media/project-collection/project-collection-admins-members-tab-s157.png and b/docs/organizations/security/media/project-collection/project-collection-admins-members-tab-s157.png differ diff --git a/docs/organizations/security/media/project-collection/remove-admin-member-s157.png b/docs/organizations/security/media/project-collection/remove-admin-member-s157.png index 2321cbda41b..17ccf6a171b 100644 Binary files a/docs/organizations/security/media/project-collection/remove-admin-member-s157.png and b/docs/organizations/security/media/project-collection/remove-admin-member-s157.png differ diff --git a/docs/organizations/security/media/project-collection/remove-admin-member-server.png b/docs/organizations/security/media/project-collection/remove-admin-member-server.png index e4ac9dc5eee..520a7cf9564 100644 Binary files a/docs/organizations/security/media/project-collection/remove-admin-member-server.png and b/docs/organizations/security/media/project-collection/remove-admin-member-server.png differ diff --git a/docs/organizations/security/media/project-level-permissions-add-a-user.png b/docs/organizations/security/media/project-level-permissions-add-a-user.png index fb137c2d176..8a4a8f7e671 100644 Binary files a/docs/organizations/security/media/project-level-permissions-add-a-user.png and b/docs/organizations/security/media/project-level-permissions-add-a-user.png differ diff --git a/docs/organizations/security/media/project-level-permissions-add-member.png b/docs/organizations/security/media/project-level-permissions-add-member.png index 8fcf640771a..8b2f49f8d19 100644 Binary files a/docs/organizations/security/media/project-level-permissions-add-member.png and b/docs/organizations/security/media/project-level-permissions-add-member.png differ diff --git a/docs/organizations/security/media/security-roles/agent-pools-pipeline-all-security-roles-org.png b/docs/organizations/security/media/security-roles/agent-pools-pipeline-all-security-roles-org.png deleted file mode 100644 index fd52b24f7d0..00000000000 Binary files a/docs/organizations/security/media/security-roles/agent-pools-pipeline-all-security-roles-org.png and /dev/null differ diff --git a/docs/organizations/security/media/security-roles/agent-pools-pipeline-individual-security-roles-org.png b/docs/organizations/security/media/security-roles/agent-pools-pipeline-individual-security-roles-org.png deleted file mode 100644 index 359ec7a1081..00000000000 Binary files a/docs/organizations/security/media/security-roles/agent-pools-pipeline-individual-security-roles-org.png and /dev/null differ diff --git a/docs/organizations/security/media/security-roles/pipeline-all-security-roles.png b/docs/organizations/security/media/security-roles/pipeline-all-security-roles.png deleted file mode 100644 index e7e5de8769f..00000000000 Binary files a/docs/organizations/security/media/security-roles/pipeline-all-security-roles.png and /dev/null differ diff --git a/docs/organizations/security/media/security-roles/pipline-individual-security-role.png b/docs/organizations/security/media/security-roles/pipline-individual-security-role.png deleted file mode 100644 index aeee728df3d..00000000000 Binary files a/docs/organizations/security/media/security-roles/pipline-individual-security-role.png and /dev/null differ diff --git a/docs/organizations/security/media/stakeholder-security/add-new-group.png b/docs/organizations/security/media/stakeholder-security/add-new-group.png deleted file mode 100644 index 8fa4eae2bfb..00000000000 Binary files a/docs/organizations/security/media/stakeholder-security/add-new-group.png and /dev/null differ diff --git a/docs/organizations/security/media/test-permissions/set-project-level-test-permissions-new-ui.png b/docs/organizations/security/media/test-permissions/set-project-level-test-permissions-new-ui.png index 6bc90e09b29..59950e797aa 100644 Binary files a/docs/organizations/security/media/test-permissions/set-project-level-test-permissions-new-ui.png and b/docs/organizations/security/media/test-permissions/set-project-level-test-permissions-new-ui.png differ diff --git a/docs/organizations/security/media/troubleshoot-permissions/re-evaluate-permissions-button.png b/docs/organizations/security/media/troubleshoot-permissions/re-evaluate-permissions-button.png index 4278423bda9..80365d1f39d 100644 Binary files a/docs/organizations/security/media/troubleshoot-permissions/re-evaluate-permissions-button.png and b/docs/organizations/security/media/troubleshoot-permissions/re-evaluate-permissions-button.png differ diff --git a/docs/organizations/security/media/user-policy-invite-new-users.png b/docs/organizations/security/media/user-policy-invite-new-users.png index 8ec3c552257..bdd6cb11cbc 100644 Binary files a/docs/organizations/security/media/user-policy-invite-new-users.png and b/docs/organizations/security/media/user-policy-invite-new-users.png differ diff --git a/docs/organizations/security/media/view-permissions/collection-admins.png b/docs/organizations/security/media/view-permissions/collection-admins.png deleted file mode 100644 index 2149e4b5370..00000000000 Binary files a/docs/organizations/security/media/view-permissions/collection-admins.png and /dev/null differ diff --git a/docs/organizations/security/media/view-permissions/member-of-view-s154.png b/docs/organizations/security/media/view-permissions/member-of-view-s154.png index 265ca0e0fd6..d6b3b9a205d 100644 Binary files a/docs/organizations/security/media/view-permissions/member-of-view-s154.png and b/docs/organizations/security/media/view-permissions/member-of-view-s154.png differ diff --git a/docs/organizations/security/media/view-permissions/user-permissions-s154.png b/docs/organizations/security/media/view-permissions/user-permissions-s154.png index aeb5d1a217b..734064be1e5 100644 Binary files a/docs/organizations/security/media/view-permissions/user-permissions-s154.png and b/docs/organizations/security/media/view-permissions/user-permissions-s154.png differ diff --git a/docs/organizations/security/namespace-reference.md b/docs/organizations/security/namespace-reference.md index c47a24c6f41..3b5a5e34fc0 100644 --- a/docs/organizations/security/namespace-reference.md +++ b/docs/organizations/security/namespace-reference.md @@ -1,47 +1,47 @@ --- title: Namespace reference titleSuffix: Azure DevOps -description: Understand the set of namespaces used to manage security +description: Learn about the security namespaces used to manage access control in Azure DevOps, including associated permissions and detailed information. ms.subservice: azure-devops-security ms.custom: quarterly-review ms.topic: reference ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 11/18/2024 --- # Security namespace and permission reference for Azure DevOps [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Security namespaces are used to store access control lists (ACLs) on tokens. Data stored in security namespaces determines the level of access the following entities have to perform a specific action on a specific resource. -- Azure DevOps user -- Azure DevOps Organization owner -- Member of an Azure DevOps security group -- Azure DevOps service account -- Azure DevOps service principal - -Each family of resources, such as work items or Git repositories, is secured through a unique namespace. Each security namespace contains zero or more ACLs. Each ACL contains a token, an inherit flag, and a set of zero or more access control entries (ACEs). Each ACE contains an identity descriptor, an allowed permissions bitmask, and a denied permissions bitmask. Tokens are arbitrary strings representing resources in Azure DevOps. +This article describes the valid security namespaces, lists the associated permissions, and provides links to more information. Security namespaces store access control lists ([ACLs](/rest/api/azure/devops/security/access-control-lists/query)) on tokens, determining the level of access various entities have to perform specific actions on specific resources. These entities include: -> [!NOTE] -> Namespaces and tokens are valid for all versions of Azure DevOps. Those listed here are valid for Azure DevOps 2019 and later versions. Namespaces are subject to change over time. To get the latest list of namespaces, exercise one of the command line tools or REST API. Some namespaces have been deprecated as listed in the [Deprecated and read-only namespaces](#deprecated-namespaces) section later in this article. +- Azure DevOps users +- Azure DevOps organization owners +- Members of Azure DevOps security groups +- Azure DevOps service accounts +- Azure DevOps service principals +Each family of resources, such as work items or Git repositories, is secured through a unique namespace. Each security namespace contains zero or more ACLs. An ACL includes a token, an inherit flag, and a set of zero or more access control entries (ACEs). Each ACE consists of an identity descriptor, an allowed permissions bitmask, and a denied permissions bitmask. Tokens are arbitrary strings representing resources in Azure DevOps. + +> [!NOTE] +> Namespaces and tokens are valid for all versions of Azure DevOps. Those listed here are valid for Azure DevOps 2019 and later versions. Namespaces are subject to change over time. To get the latest list of namespaces, exercise one of the command line tools or REST API. Some namespaces have been deprecated as listed in the [Deprecated and read-only namespaces](#deprecated-namespaces) section later in this article. For more information, see [Security namespaces query](/rest/api/azure/devops/security/security-namespaces/query) ## Permission management tools -The recommended method for managing permissions is through the web portal. However, if you need to set a permission that isn't surfaced through the web portal or to set more granular permissions, you can use one of the command line tools or REST API. -- For Azure DevOps Server 2020 and Azure DevOps Services, you can use the `az devops security permission` commands. -- For on-premises Azure DevOps instances, you can use the [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd) commands. -- For Azure DevOps git repositories,[Tf git permission command-line tool](../../repos/tfvc/git-permission-command.md) -- For Team Foundation Version Control (TFVC) repositories, [Tf TFVC permission command-line tool](../../repos/tfvc/permission-command.md) +The recommended method for managing permissions is through the web portal. However, to set permissions that are unavailable through the portal or to manage granular permissions, use command line tools or the REST API: -For all Azure DevOps instances, you can use the [Security REST API](/rest/api/azure/devops/security). +- For Azure DevOps Services, use the `az devops security permission` commands. +- For Azure DevOps Server, use the TFSSecurity commands. +- For Azure DevOps Git repositories, use the [tf git permission command-line tool](../../repos/tfvc/git-permission-command.md). +- For Team Foundation Version Control (TFVC) repositories, use the [TFVC permission command-line tool](../../repos/tfvc/permission-command.md). -## Security namespaces and their IDs +For all Azure DevOps instances, you can also use the [Security REST API](/rest/api/azure/devops/security). -This article describes the valid namespaces, lists the associated permissions, and provides links to more information. Many security namespaces correspond to permissions you set through a **Security** or **Permissions** web portal page. Other namespaces or select permissions aren't surface through the web portal. They grant access by default to members of security groups or Azure DevOps service principals. Namespaces have been grouped into the following categories based on how they're managed through the web portal. +## Security namespaces and their IDs +Many security namespaces correspond to permissions you set through a **Security** or **Permissions** web portal page. Other namespaces or specific permissions aren't visible through the web portal and grant access by default to members of security groups or Azure DevOps service principals. These namespaces are grouped into the following categories based on how they're managed through the web portal: - Object-level - Project-level @@ -50,19 +50,18 @@ This article describes the valid namespaces, lists the associated permissions, a - Role-based - Internal only - ### Hierarchy and tokens -A security namespace can be either hierarchical or flat. Tokens in a hierarchical namespace exist in a hierarchy with effective permissions inherited from parent tokens to child tokens. Tokens in a flat namespace have no concept of a parent-child relationship between any two tokens. +A security namespace can be either hierarchical or flat. In a hierarchical namespace, tokens exist in a hierarchy where effective permissions are inherited from parent tokens to child tokens. In contrast, tokens in a flat namespace have no concept of a parent-child relationship between any two tokens. Tokens in a hierarchical namespace either have a fixed length for each path part, or variable length. If the tokens have variable-length path parts, then a separator character is used to distinguish where one path part ends and another begins. -Security tokens are case-insensitive. Token examples for different namespaces are provided in the following sections. +Security tokens are case-insensitive. Example of tokens for different namespaces are provided in the following sections. ## Object-level namespaces and permissions -The following table describes the namespaces that manage object-level permissions. Most of the listed permissions are managed through the web portal page for each object. Permissions are set at the project-level and inherited at the object-level unless changed. +The following table describes the namespaces that manage object-level permissions. Most of these permissions are managed through the web portal page for each object. Permissions are set at the project level and inherited at the object level unless explicitly changed. --- :::row::: @@ -77,10 +76,10 @@ The following table describes the namespaces that manage object-level permission :::column-end::: :::row-end::: --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: - AnalyticsViews + AnalyticsViews :::column-end::: :::column span="1"::: `Read` @@ -90,7 +89,7 @@ The following table describes the namespaces that manage object-level permission `ManagePermissions` :::column-end::: :::column span="2"::: - [Manages Analytics views permissions at the project-level and object-level](permissions.md#analytics-views-permissions) to read, edit, delete, and generate reports. You can manage these permissions for each [Analytics view from the user interface](../../report/powerbi/analytics-security.md). + [Manages Analytics views permissions at the project-level and object-level](permissions.md#analytics-views-object-level) to read, edit, delete, and generate reports. You can manage these permissions for each [analytics view from the user interface](../../report/powerbi/analytics-security.md).
      **Token format for project level permissions**: `$/Shared/PROJECT_ID` **Example**: `$/Shared/xxxxxxxx-a1de-4bc8-b751-188eea17c3ba` @@ -125,7 +124,7 @@ The following table describes the namespaces that manage object-level permission [Manages build permissions at the project-level and object-level](permissions.md#build-object-level).
      **Token format for project-level build permissions**: `PROJECT_ID` - If you need to update permissions for a particular build definition ID, for example, 12, security token for that build definition looks as follows: + If you need to update permissions for a particular build definition ID, for example, 12, security token for that build definition looks like the following example: **Token format for project-level, specific build permissions**: `PROJECT_ID/12` **Example**: `xxxxxxxx-a1de-4bc8-b751-188eea17c3ba/12`
      @@ -148,7 +147,8 @@ The following table describes the namespaces that manage object-level permission `MANAGE_TEST_SUITES` :::column-end::: :::column span="2"::: - [Manages area path object-level permissions](permissions.md#area-path-object-level) to create, edit, and delete child nodes and set permissions to view or edit work items in a node. You can manage these permissions through the [Set permissions and access for work tracking, Create child nodes, modify work items under an area path](set-permissions-access-work-tracking.md#set-permissions-area-path). + [Manages area path object-level permissions](permissions.md#area-path-object-level) to create, edit, and delete child nodes and set permissions to view or edit work items in a node. For more information, see [Set permissions and access for work tracking, Create child nodes, modify work items under an area path](set-permissions-access-work-tracking.md#set-permissions-area-path). + **Token format example:** `POST https://dev.azure.com/{organization}/_apis/securitynamespaces/{namespaceId}/permissions?api-version=6.0 { "token": "vstfs:///Classification/Node/{area_node_id}", "permissions": { "allow": 1, "deny": 0 } }`
      **ID:** `83e28ad4-2d72-4ceb-97b0-c7726d5502c3` :::column-end::: @@ -156,7 +156,7 @@ The following table describes the namespaces that manage object-level permission --- :::row::: :::column span="1"::: - DashboardsPrivileges + DashboardsPrivileges :::column-end::: :::column span="1"::: `Read` @@ -167,7 +167,7 @@ The following table describes the namespaces that manage object-level permission `MaterializeDashboards` :::column-end::: :::column span="2"::: - [Manages dashboard object-level permissions](permissions.md#dashboard-permissions) to edit and delete dashboards and manage permissions for a project dashboard. You can manage these permissions through the [Dashboards user interface](../../report/dashboards/dashboard-permissions.md#set-permissions-for-a-project-dashboard). + [Manages dashboard object-level permissions](permissions.md#dashboards-object-level) to edit and delete dashboards and manage permissions for a project dashboard. You can manage these permissions through the [dashboards user interface](../../report/dashboards/dashboard-permissions.md#set-permissions-for-a-project-dashboard).
      **ID:** `8adf73b7-389a-4276-b638-fe1653f7efc7` :::column-end::: @@ -175,7 +175,7 @@ The following table describes the namespaces that manage object-level permission --- :::row::: :::column span="1"::: - GitRepositories + Git Repositories :::column-end::: :::column span="1"::: `Administer` @@ -196,15 +196,17 @@ The following table describes the namespaces that manage object-level permission `PullRequestBypassPolicy` :::column-end::: :::column span="2"::: - [Manages Git repository permissions at the project-level and object-level](permissions.md#git-repository-permissions-object-level). You can manage these permissions through the [Project settings, Repositories administrative interface](../../repos/git/set-git-repository-permissions.md). + [Manages Git repository permissions at the project-level and object-level](permissions.md#git-repository-object-level). You can manage these permissions through the [Project settings, Repositories administrative interface](../../repos/git/set-git-repository-permissions.md).
      - The `Administer` permission was divided into several more granular permissions [in 2017](/previous-versions/azure/devops/2017/jan-25-team-services#repo-admin-permission-changes), and should not be used. + The `Administer` permission was divided into several more granular permissions [in 2017](/previous-versions/azure/devops/2017/jan-25-team-services#repo-admin-permission-changes), and shouldn't be used.
      **Token format for project-level permissions**: `repoV2/PROJECT_ID` You need to append `RepositoryID` to update repository-level permissions.
      **Token format for repository-specific permissions**: `repoV2/PROJECT_ID/REPO_ID`
      + **Token format for branch-level permissions** is described in [Git repo tokens for the security service](https://devblogs.microsoft.com/devops/git-repo-tokens-for-the-security-service/). +

      **ID:** `2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87` :::column-end::: :::row-end::: @@ -232,7 +234,7 @@ The following table describes the namespaces that manage object-level permission      – TeamIteration2ChildIteration1      – TeamIteration2ChildIteration2
      - To update permissions for `ProjectIteration1\TeamIteration1\TeamIteration1ChildIteration1`, the security token looks as follows: + To update permissions for `ProjectIteration1\TeamIteration1\TeamIteration1ChildIteration1`, the security token looks like the following example: `vstfs:///Classification/Node/ProjectIteration1_Identifier:vstfs:///Classification/Node/TeamIteration1_Identifier:vstfs:///Classification/Node/TeamIteration1ChildIteration1_Identifier`
      **ID:** `bf7bfa03-b2b7-47db-8113-fa2e002cc5b1` @@ -249,13 +251,13 @@ The following table describes the namespaces that manage object-level permission `Delete` :::column-end::: :::column span="2"::: - [Manages task group permissions](permissions.md) to edit and delete task groups, and administer task group permissions. To manage through the web portal, see [Pipeline permissions and security roles, Task group permissions](../../pipelines/policies/permissions.md#set-task-group-permissions). + [Manages task group permissions](permissions.md) to edit and delete task groups, and administer task group permissions. To manage through the web portal, see [Pipeline permissions and security roles, Task group permissions](../../pipelines/policies/permissions.md#task-group-permissions).

      **Token format for project-level permissions**: `PROJECT_ID`
      **Token format for metaTask-level permissions**: `PROJECT_ID/METATASK_ID`

      - If MetaTask has parentTaskId then the Security token looks as follows: + If MetaTask has parentTaskId, then the Security token looks like the following example:
      **Token Format**: `PROJECT_ID/PARENT_TASK_ID/METATASK_ID`

      @@ -274,7 +276,7 @@ The following table describes the namespaces that manage object-level permission `Manage` :::column-end::: :::column span="2"::: - [Manages permissions for Delivery Plans](permissions.md#plan-permissions) to view, edit, delete, and manage delivery plans. You can manage these permissions through the [web portal for each plan](set-permissions-access-work-tracking.md#edit-or-manage-permissions-for-delivery-plans). + [Manages permissions for Delivery Plans](permissions.md) to view, edit, delete, and manage delivery plans. You can manage these permissions through the [web portal for each plan](set-permissions-access-work-tracking.md).
      **ID:** `bed337f8-e5f3-4fb9-80da-81e17d06e7a8` :::column-end::: @@ -330,17 +332,17 @@ The following table describes the namespaces that manage object-level permission `RecordQueryExecutionInfo` :::column-end::: :::column span="2"::: - [Manages permissions for work item queries and query folders](permissions.md#query). To manage these through the web portal, see [Set permissions and access for work tracking, Set permissions on queries or query folders](set-permissions-access-work-tracking.md#work-item-queries). + [Manages permissions for work item queries and query folders](permissions.md#query). To manage these permissions through the web portal, see [Set permissions on queries or query folders](set-permissions-access-work-tracking.md#work-item-queries). + **Token format example:** `POST https://dev.azure.com/{organization}/_apis/securitynamespaces/{namespaceId}/permissions?api-version=6.0 { "token": "/{project_id}/{shared_queries_id}", "permissions": { "allow": 1, "deny": 0 } }`.
      **ID:** `71356614-aad7-4757-8f2c-0fb3bff6f680` :::column-end::: :::row-end::: --- - ## Project-level namespaces and permissions -The following table describes the namespaces that manage project-level permissions. Most of the listed permissions are managed through the [web portal admin context](change-project-level-permissions.md). Project Administrators are granted all project-level permissions. Other project-level groups have select permission assignments. +The following table describes the namespaces that manage project-level permissions. Most of the listed permissions are managed through the [web portal admin context](change-project-level-permissions.md). Project Administrators are granted all project-level permissions, while other project-level groups have specific permission assignments. --- :::row::: @@ -388,7 +390,7 @@ The following table describes the namespaces that manage project-level permissio :::column-end::: :::column span="2"::: [Manages Project-level permissions](permissions.md#project-level-permissions). - The `AGILETOOLS_BACKLOG` permission manages access to Azure Boards backlogs. This is an internal permission setting and shouldn't be changed. + The `AGILETOOLS_BACKLOG` permission manages access to Azure Boards backlogs. This setting is an internal permission setting and shouldn't be changed.
      **Root token format**: `$PROJECT` Token to secure permissions for each project in your organization. @@ -398,7 +400,7 @@ The following table describes the namespaces that manage project-level permissio `az devops project show --project "Test Project 1"` The command returns a project-id, for example, `xxxxxxxx-a1de-4bc8-b751-188eea17c3ba`. Therefore, the token to secure project-related permissions for `Test Project 1` is: - `'$PROJECT:vstfs:///Classification/TeamProject/xxxxxxxx-a1de-4bc8-b751-188eea17c3ba'` + `'$PROJECT:vstfs:///Classification/TeamProject/xxxxxxxx-a1de-4bc8-b751-188eea17c3ba'`
      **ID:** `52d39943-cb85-4d7f-8fa8-c6baac873819` :::column-end::: @@ -406,7 +408,7 @@ The following table describes the namespaces that manage project-level permissio --- :::row::: :::column span="1"::: -       Tagging + Tagging :::column-end::: :::column span="1"::: `Enumerate` @@ -415,7 +417,7 @@ The following table describes the namespaces that manage project-level permissio `Delete` :::column-end::: :::column span="2"::: - Manages permissions to create, delete, enumerate, and use work item tags. You can manage the **Create tag definition** permission through the [Project settings, Permissions administrative interface](change-project-level-permissions.md). + Manages permissions to create, delete, enumerate, and use work item tags. You can manage the **Create tag definition** permission through the [permissions administrative interface](change-project-level-permissions.md).
      **Token format for project-level permissions**: `/PROJECT_ID` **Example**: `/xxxxxxxx-a1de-4bc8-b751-188eea17c3ba` @@ -444,7 +446,7 @@ The following table describes the namespaces that manage project-level permissio `ManageBranch` :::column-end::: :::column span="2"::: - Manages permissions for a [Team Foundation Version Control (TFVC) repository](permissions.md#tfvc). There is only one TFVC repository for a project. You can manage these permissions through the [Project settings, Repositories administrative interface](../../repos/tfvc/set-tfvc-repository-permissions.md). + Manages permissions for a [Team Foundation Version Control (TFVC) repository](permissions.md#tfvc). There's only one TFVC repository for a project. You can manage these permissions through the [repositories administrative interface](../../repos/tfvc/set-tfvc-repository-permissions.md).
      **ID:** `a39371cf-0841-4c16-bbd3-276e341bc052` :::column-end::: @@ -455,19 +457,18 @@ The following table describes the namespaces that manage project-level permissio ## Organization-level namespaces and permissions -The following table describes the namespaces that manage organization-level permissions. Most of the listed permissions are managed through the web portal **Organization settings** context. The **Organization owner** and members of the **Project Collection Administrators** group are granted most of these permissions. To learn more, see [Change project collection-level permissions](change-organization-collection-level-permissions.md). +The following table describes the namespaces that manage organization-level permissions. Most of the listed permissions are managed through the web portal **Organization settings** context. The **Organization owner** and members of the **Project Collection Administrators** group are granted most of these permissions. For more information, see [Change project collection-level permissions](change-organization-collection-level-permissions.md). ::: moniker-end ::: moniker range="< azure-devops" ## Collection-level namespaces and permissions - -The following table describes the namespaces that manage organization-level permissions. Most of the listed permissions are managed through the web portal **Collection settings** context. Members of the **Project Collection Administrators** group are granted most of these permissions. To learn more, see [Change project collection-level permissions](change-organization-collection-level-permissions.md). +The following table describes the namespaces that manage organization-level permissions. Most of the listed permissions are managed through the web portal **Collection settings** context. Members of the **Project Collection Administrators** group are granted most of these permissions. For more information, see [Change project collection-level permissions](change-organization-collection-level-permissions.md). ::: moniker-end - + --- :::row::: @@ -544,7 +545,7 @@ The following table describes the namespaces that manage organization-level perm :::column-end::: :::row-end::: --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: Process @@ -610,7 +611,7 @@ The following table describes the namespaces that manage organization-level perm ## Server-level namespaces and permissions -The following table describes those security namespaces and permissions defined for on-premises instances of Azure DevOps Server. You can manage these permissions, which are granted to members of the Team Foundation Administrators group, through the [Azure DevOps Server administration console](/azure/devops/server/admin/add-administrator). For descriptions of these permissions, see [Permissions and groups, Server-level permissions](permissions.md#server-permissions). +The following table describes those security namespaces and permissions defined for on-premises instances of Azure DevOps Server. You can manage these permissions, which are granted to members of the Team Foundation Administrators group, through the [Azure DevOps Server administration console](/azure/devops/server/admin/add-administrator). For descriptions of these permissions, see [Permissions and groups, Server-level permissions](permissions.md#server-permissions). --- @@ -652,7 +653,7 @@ The following table describes those security namespaces and permissions defined `TriggerEvent` :::column-end::: :::column span="2"::: - Manages permissions set at the server-level. This includes permissions to edit instance-level information, make requests on behalf of others, and trigger events. + Manages permissions set at the server-level. Includes permissions to edit instance-level information, make requests on behalf of others, and trigger events.
      **ID:** `1f4179b3-6bac-4d01-b421-71ea09171400` :::column-end::: @@ -675,10 +676,8 @@ The following table describes those security namespaces and permissions defined ::: moniker-end - ## Role-based namespaces and permissions - The following table describes the security namespaces and permissions used to manage role-based security. You can manage role assignments through the web portal for pipeline resources as described [Pipeline permissions and security roles](../../pipelines/policies/permissions.md). --- @@ -767,12 +766,12 @@ The following table describes the security namespaces and permissions used to ma `Owner` :::column-end::: :::column span="2"::: - Manages permissions to create and manage library items, which include secure files and variable groups. Role memberships for individual items are automatically inherited from those of the Library node. By default, the following permissions are assigned: + Manages permissions to create and manage library items, which include secure files and variable groups. Role memberships for individual items are automatically inherited from the Library. By default, the following permissions are assigned: - **Reader** role (`View` permissions only) to all members of the Project Valid Users group and the Project Collection Build Service account - **Creator** role (`View`, `Use`, and `Create` permissions) to all members of the Contributors group - **Creator** role (`View`, `Use`, `Create`, and `Owner` permissions) to the member who created the library item - **Administrator** role (all permissions) to members of the Build Administrators, Project Administrators, and Release Administrators groups. - To learn more, see [Library asset security roles](../../pipelines/library/index.md).

      + For more information, see [Library asset security roles](../../pipelines/library/index.md).

      **ID:** `b7e84409-6553-448a-bbb2-af228e07cbeb` :::column-end::: :::row-end::: @@ -789,7 +788,7 @@ The following table describes the security namespaces and permissions used to ma `ViewEndpoint` :::column-end::: :::column span="2"::: - Manages permissions to create and manage service connections. Role memberships for individual items are automatically inherited from those defined at the project-level. By default, the following roles are assigned: + Manages permissions to create and manage service connections. Role memberships for individual items are automatically inherited from the project-level roles. By default, the following roles are assigned: - **Reader** role (`View` permissions only) to all members of the Project Valid Users group and the Project Collection Build Service account - **Creator** role (`View`, `Use`, and `Create` permissions) to members of the Endpoint Creators service security group. - **Administrator** role (all permissions) to members of the Endpoint Administrators service security group. @@ -799,11 +798,11 @@ The following table describes the security namespaces and permissions used to ma :::row-end::: --- - + ## Internal namespaces and permissions -The following table describes the security namespaces and permissions that aren't surfaced through the web portal. They are primarily used to grant access to members of default security groups or to internal resources. We strongly recommend that you don't alter these permission settings in any way. +The following table describes the security namespaces and permissions that aren't surfaced through the web portal. They're primarily used to grant access to members of default security groups or to internal resources. We strongly recommend that you don't alter these permission settings in any way. --- :::row::: @@ -834,7 +833,7 @@ The following table describes the security namespaces and permissions that aren' :::column-end::: :::row-end::: --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: Analytics @@ -887,7 +886,7 @@ The following table describes the security namespaces and permissions that aren' `Manage` :::column-end::: :::column span="2"::: - Manages permissions and access to Kanban boards. + Manages permissions and access to boards.
      **ID:** `251e12d9-bea3-43a8-bfdb-901b98c0125e` :::column-end::: @@ -1071,7 +1070,7 @@ The following table describes the security namespaces and permissions that aren' `Project-Scoped Users` :::column-end::: :::column span="2"::: - Applies a system-level deny permission on the namespace which supports the Project-Scoped User Group. Members of the group have limited visibility to organization-level data. To learn more, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group).
      + Applies a system-level deny permission on the namespace, which supports the Project-Scoped User Group. Members of the group receive limited visibility to organization-level data. For more information, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group).
      **ID:** `F0003BCE-5F45-4F93-A25D-90FC33FE3AA9` :::column-end::: :::row-end::: @@ -1171,7 +1170,7 @@ The following table describes the security namespaces and permissions that aren' `QueryUsageSummary` :::column-end::: :::column span="2"::: - Manages permissions to query usage. By default, all members of the Project Collection Administrators groups and users granted Stakeholder access are granted permission to query usage summary for everyone. To learn more, see [Rate limits](../../integrate/concepts/rate-limits.md). + Manages permissions to query usage. By default, all members of the Project Collection Administrators groups and users granted Stakeholder access are granted permission to query usage summary for everyone. For more information, see [Rate limits](../../integrate/concepts/rate-limits.md). **Token format**: `/`
      @@ -1204,7 +1203,7 @@ The following table describes the security namespaces and permissions that aren' `ManageLinkTypes` :::column-end::: :::column span="2"::: - Manages permissions for changing work tracking processes and managing link types. The WorkItemTrackingProvision namespace is an older security namespace that is mostly used for TFS-2018 and earlier versions. The [Process](#process) namespace replaces this namespace for managing processes in Azure DevOps Server 2019 and later versions. + Manages permissions for changing work tracking processes and managing link types. The WorkItemTrackingProvision namespace is an older security namespace that is mostly used for earlier on-premises versions. The [Process](#process) namespace replaces this namespace for managing processes in Azure DevOps Server 2019 and later versions.
      **Root token format**: `/$` **Token format for a specific project**: `$/PROJECT_ID` @@ -1214,8 +1213,7 @@ The following table describes the security namespaces and permissions that aren' :::row-end::: --- - - + ## Deprecated and read-only namespaces @@ -1257,9 +1255,8 @@ The following namespaces are either deprecated or read-only. You shouldn't use t ## Related articles -- [About security, authentication, and authorization](about-security-identity.md) -- [Security Namespaces REST API](/rest/api/azure/devops/security/) -- [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd) -- [Security glossary](security-glossary.md) -- [Git repo tokens for the security service](https://devblogs.microsoft.com/devops/git-repo-tokens-for-the-security-service/) +- [Learn about security, authentication, and authorization](about-security-identity.md) +- [Use the security Namespaces REST API](/rest/api/azure/devops/security/) +- [Use TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd) +- [Understand security terms with the security glossary](security-glossary.md) diff --git a/docs/organizations/security/permissions-access-work-tracking.md b/docs/organizations/security/permissions-access-work-tracking.md deleted file mode 100644 index 67464a297ce..00000000000 --- a/docs/organizations/security/permissions-access-work-tracking.md +++ /dev/null @@ -1,386 +0,0 @@ ---- -title: Default work tracking permissions & access -titleSuffix: Azure Boards -description: Default permissions and access levels for tracking work in Azure Boards -ms.custom: boards-permissions, linked-from-support, engagement-fy23 -ms.subservice: azure-devops-security -ms.assetid: 5AD0BF62-C91E-46DD-8C1A-C8D1F8F8D05F -ms.author: chcomley -author: chcomley -ms.topic: overview -monikerRange: '<= azure-devops' -ms.date: 02/02/2023 ---- - -# Permissions and access for work tracking - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range=">= azure-devops-2019" - -As a member of an Azure DevOps project, you can use most of the features to track work. Limitations to select features are based on the *access level* and *security group* to which a user is assigned. The **Basic** access level and higher supports full access to all Azure Boards features. **Stakeholder** access level provides partial support to select features, allowing users to view and modify work items, but not use all features. The built-in security groups—**Readers**, **Contributors**, and **Project Administrators**— and team administrator role grant permissions to specific features. - -::: moniker-end - -::: moniker range="tfs-2018" - -As a member of an Azure DevOps project, you can use most of the features to track work. Limitations to select features are based on the *access level* and *security group* to which a user is assigned. The **Basic** access level and higher supports full access to all features under the **Work** hub. **Stakeholder** access level provides partial support to select features, allowing users to view and modify work items, but not use all features. The built-in security groups—**Readers**, **Contributors**, and **Project Administrators**— and team administrator role grant permissions to specific features. - -::: moniker-end - -In the tables provided in this article, a ✔️ indicates that the corresponding access level or security group has access to a feature by default. - -> [!NOTE] -> Team administrators can configure settings for their team's tools. Organization owners and members of the **Project Administrators** group can configure settings for all teams. To be added as an administrator, see [Add team administrators](../settings/add-team-administrator.md) or [Change project-level permissions](change-project-level-permissions.md). - -For a comparison chart of Stakeholder versus Basic access, see the [Feature matrix](https://azure.microsoft.com/services/devops/compare-features/). To assign or change an access level, see [Add users and assign licenses](../accounts/add-organization-users.md). If you need to [grant specific users select permissions](request-changes-permissions.md), you can do so. - -## Work items - -You can use work items to track anything you need to track. To learn more, see [Understand how work items are used to track issues, tasks, and epics](../../boards/work-items/about-work-items.md). - -[!INCLUDE [temp](includes/boards-work-items.md)] - -## Boards - -You use [**Boards**](../../boards/boards/kanban-quickstart.md) to implement Kanban methods. Boards present work items as cards and support quick status updates through drag-and-drop. - -[!INCLUDE [temp](includes/boards-boards.md)] - -## Backlogs - -[**Backlogs**](../../boards/backlogs/create-your-backlog.md) display work items as lists. A product backlog represents your project plan and a repository of all the information you need to track and share with your team. Portfolio backlogs allow you to group and organize your backlog into a hierarchy. - -[!INCLUDE [temp](includes/boards-backlogs.md)] - -## Sprints - -You use sprint tools to implement Scrum methods. The [**Sprints**](../../boards/sprints/assign-work-sprint.md) set of tools provide filtered views of work items that a team has assigned to specific iteration paths or sprints. - -[!INCLUDE [temp](includes/boards-sprints.md)] - -## Queries and semantic search - -[**Queries**](../../boards/queries/view-run-query.md) are filtered lists of work items based on criteria that you define by using a query editor. [Adhoc searches](../../boards/queries/search-box-queries.md) are powered by a semantic search engine. - -> [!TIP] -> By default, Contributors can't create and save shared queries. We recommend that Project Administrators create a query folder for each team and give the team administrators or the team group query permissions to manage their folder. You need **Delete** permissions to rename or move a shared query or folder, and **Contribute** permissions for the folder where you move the query to. To learn more, see [Set permissions on queries and query folders](../../boards/queries/set-query-permissions.md). - -[!INCLUDE [temp](includes/boards-queries.md)] - -## Delivery plans - -[Delivery plans](../../boards/plans/review-team-plans.md) display work items as cards against a calendar view. This format can be an effective communication tool with managers, partners, and stakeholders for a team. Users granted **Stakeholder** access for private projects have no access to delivery plans, while users granted **Stakeholder** access for public projects has the same access as regular Contributors granted **Basic** access. - -For more information, see [Manage Delivery Plan permissions](set-permissions-access-work-tracking.md#edit-or-manage-permissions-for-delivery-plans). - -[!INCLUDE [temp](includes/boards-plans.md)] - - -## Test management - -Test plans, test suites, test cases and other test artifacts are specific work item types that support manual and exploratory testing. You set [test permissions at the project level](change-project-level-permissions.md) from the **Project settings>Security** page. - -[!INCLUDE [temp](includes/test.md)] - -Area permissions for web-based test case management and test execution control access to the following actions. - -The **Manage test suites** permission enables users to: -- Create and modify test suites -- Add or remove test cases to/from test suites -- Change test configurations associated with test suites -- Modify the suite hierarchy by moving a test suite - -The **Manage test plans** permission enables users to: -- Create and modify test plans -- Add or remove test suites to or from test plans -- Change test plan properties such as build and test settings - -## Project-level resources - -You set project-level information permissions from **Project settings** > **Permissions**. You set permissions for area and iteration paths under **Project settings**> **Project configuration**. These resources are defined for a project which all valid users of the project can view. - ---- -:::row::: - :::column span="2"::: - **Task** - :::column-end::: - :::column span="1"::: - **Stakeholder** - :::column-end::: - :::column span="1"::: - **Readers** - :::column-end::: - :::column span="1"::: - **Contributors** - :::column-end::: - :::column span="1"::: - **Team Admins** - :::column-end::: - :::column span="1"::: - **Project Admins** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="2"::: - [View project-level information](change-project-level-permissions.md) - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="2"::: - [Edit work items under the node](../../organizations/settings/set-area-paths.md) - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="2"::: - [Area nodes and Iteration nodes: Create, delete, edit child nodes](../../organizations/settings/set-iteration-paths-sprints.md) - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="2"::: - [Edit project-level information](change-organization-collection-level-permissions.md) - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="2"::: - [Area nodes and Iteration nodes: Create, delete, edit child nodes](../../organizations/settings/set-iteration-paths-sprints.md) - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: ---- - -The **Edit project-level information** permission includes the ability to perform these tasks for the project: -- Create and modify areas and iterations -- Edit check-in policies -- Edit shared work item queries -- Edit project level permission ACLs -- Create and modify global lists -- Edit [event subscriptions](permissions.md#alerts) (email or SOAP) on project level events. - -## Team administrator role and permissions - -The following table summarizes a subset of the default permissions assigned to the project Readers, Contributors and Project Administrators groups and the Team Administrator role. Team admin permissions extend only to the team for which they're an administrator. Project Administrator permissions extend across all teams defined for the project. - -:::row::: - :::column span="1"::: - **Permission** - :::column-end::: - :::column span="1"::: - **Readers** - :::column-end::: - :::column span="1"::: - **Contributors** - :::column-end::: - :::column span="1"::: - **Team Administrators** - :::column-end::: - :::column span="1"::: - **Project Administrators** - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Add a team administrator](../../organizations/settings/add-team-administrator.md) - :::column-end::: - :::column span="1"::: -    - :::column-end::: - :::column span="1"::: -    - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Add team members](../../organizations/settings/add-teams.md) - :::column-end::: - :::column span="1"::: -    - :::column-end::: - :::column span="1"::: -    - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [View shared work item queries](../../boards/queries/using-queries.md) - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Manage shared query and query folder permissions](../../boards/queries/set-query-permissions.md) - (Contribute, Delete, Manage Permissions) - :::column-end::: - :::column span="1"::: -    - :::column-end::: - :::column span="1"::: -    - :::column-end::: - :::column span="1"::: -    - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Add and edit dashboards](../../report/dashboards/dashboards.md) - :::column-end::: - :::column span="1"::: -    - :::column-end::: - :::column span="1"::: -    - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: - - - -## Stakeholder access - -Stakeholder access supports business owners and analysts and other team members who don't contribute to code, build, and test activities. They contribute by adding ideas to the backlog, adding context and information to work items, and reviewing status and progress. All members of an organization who don't use Visual Studio but want to contribute to work item tracking and monitor progress can be assigned as a stakeholder. To learn more about Stakeholder access, see [Work as a stakeholder](get-started-stakeholder.md). - -For a comparison chart of Stakeholder versus basic access, see the [Feature Matrix](https://azure.microsoft.com/services/devops/compare-features/). - -For information about each access level, see [About access levels](access-levels.md). To assign access levels, see: -- **Azure DevOps Services**: [Add users and assign licenses in Azure DevOps](../accounts/add-organization-users.md) -- **Azure DevOps Server**: [Change access levels](change-access-levels.md) - - - -## Grant team members additional permissions - -For teams to work autonomously, you may want to provide them with permissions that they don't have by default. Suggested tasks include providing team administrators or team leads permissions to: - -- [Create and edit child nodes under their default area path](set-permissions-access-work-tracking.md) -- [Create and edit child nodes under an existing iteration node](set-permissions-access-work-tracking.md) -- [Create shared queries and folders under the Shared Queries folder](../../boards/queries/set-query-permissions.md). - -By default, team members inherit the permissions afforded to members of the project Contributors group. Members of this group can add and modify source code, create and delete test runs, and create and modify work items. They can [collaborate on a Git project](../../repos/git/gitquickstart.md) or collaborate with other team members and [check in work to the team's code base (TFVC)](../../repos/tfvc/check-your-work-team-codebase.md). - -![Default permissions assigned to team contributors](../settings/media/add-team/default-permissions-assigned-to-team-contributors.png) - -::: moniker range="< azure-devops-2022" - -If your on-premises deployment includes reporting, add users to those resources. See [Grant permissions to view or create SQL Server reports](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports). - -::: moniker-end - - -## Related notes - -- [Set permissions and access for work tracking](set-permissions-access-work-tracking.md) -- [Get started as a Stakeholder](get-started-stakeholder.md) -- [Add another team](../../organizations/settings/add-teams.md) -- [Manage teams and configure team tools](../settings/manage-teams.md) -- [Work item form IndexDB caching issues](../settings/work/troubleshoot-work-item-form-caching-issues.md) diff --git a/docs/organizations/security/permissions-access.md b/docs/organizations/security/permissions-access.md index f5630c57951..4e005ef2149 100644 --- a/docs/organizations/security/permissions-access.md +++ b/docs/organizations/security/permissions-access.md @@ -1,7 +1,7 @@ --- title: Default permissions quick reference titleSuffix: Azure DevOps -description: Default permissions and access to common user tasks for Azure DevOps +description: Default permissions and access to common user tasks for Azure DevOps. ms.custom: "permissions, engagement-fy23" ms.subservice: azure-devops-security ms.assetid: B656A277-BA3D-472D-824D-CDD4E067053E @@ -10,69 +10,57 @@ ms.author: chcomley author: chcomley ms.topic: overview monikerRange: '<= azure-devops' -ms.date: 02/02/2023 +ms.date: 10/06/2023 --- -# Default permissions quick reference for Azure DevOps +# Default permissions quick reference [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -To use Azure DevOps features, users must be added to a security group with the appropriate permissions and granted access to the web portal. Limitations to select features are based on the *access level* and *security group* to which a user is assigned. The **Basic** access level and higher supports full access to most Azure DevOps Services, except for Azure Test Plans. **Stakeholder** access level provides partial support to Azure Boards and Azure Pipelines. To learn more about access levels, see [About access levels](access-levels.md) and [Stakeholder access quick reference](stakeholder-access.md). +To use Azure DevOps features, users must be added to a security group with the appropriate permissions and granted access to the web portal. Limitations to select features are based on the *access level* and *security group* to which a user is assigned. The **Basic** access level and higher supports full access to most Azure DevOps services, except for Azure Test Plans. **Stakeholder** access level provides partial support to Azure Boards and Azure Pipelines. To learn more about access levels, see [About access levels](access-levels.md) and [Stakeholder access quick reference](stakeholder-access.md). +## Assign users to a security group -## Assign users to a security group +The most common built-in security groups—**Readers**, **Contributors**, and **Project Administrators**—and team administrator role grant permissions to specific features. -The most common built-in security groups—**Readers**, **Contributors**, and **Project Administrators**— and team administrator role grant permissions to specific features. +In general, use the following guidance when assigning users to a security group: -In general, use the following guidance when assigning users to a security group: - Add to the **Contributors** security group full-time workers who contribute to the code base or manage projects. -- Add to the **Project Administrators** security group users tasked with managing project resources. I +- Add to the **Project Administrators** security group users tasked with managing project resources. - Add to the **Project Collection Administrators** security group users tasked with managing organization or collection resources. -To learn more about administrative tasks see [About user, team, project, and organization-level settings](../settings/about-settings.md). For a complete reference of all built-in groups and permissions, see [Permissions and groups](permissions.md). For information about access levels, see [About access levels](access-levels.md). +To learn more about administrative tasks see [About user, team, project, and organization-level settings](../settings/about-settings.md). For a complete reference of all built-in groups and permissions, see [Permissions and groups](permissions.md). For information about access levels, see [About access levels](access-levels.md). + +In the tables provided in this article, a ✔️ (checkmark) indicates that the corresponding access level or security group has access to a feature by default. -In the tables provided in this article, a ✔️ (checkmark) indicates that the corresponding access level or security group has access to a feature by default. - To assign or change an access level, see [Add users and assign licenses](../accounts/add-organization-users.md). If you need to [grant specific users select permissions](request-changes-permissions.md), you can do so. - - -::: moniker range=">= azure-devops-2019" + + +::: moniker range="<=azure-devops" ## Azure Boards You can plan and track work from the web portal **Boards** hub, and using Visual Studio, Excel, and other clients. For an overview of work tracking features, see [About Agile tools](../../boards/get-started/what-is-azure-boards.md). To change permissions, see [Set permissions and access for work tracking](set-permissions-access-work-tracking.md). In addition to the permissions set at the [project level via the built-in groups](change-project-level-permissions.md), you can set permissions for the following objects: [area and iteration paths](set-permissions-access-work-tracking.md) and individual [queries and query folders](../../boards/queries/set-query-permissions.md). -::: moniker-end - -::: moniker range="tfs-2018" - -## Work tracking - -You can plan and track work from the web portal **Work** hub, and using Eclipse, Visual Studio, Excel, Project, and other clients. - ::: moniker-end -> [!NOTE] -> Team administrators can configure settings for their team's tools. Organization owners and members of the **Project Administrators** group can configure settings for all teams. To be added as an administrator, see [Add team administrators](../settings/add-team-administrator.md) or [Change project-level permissions](change-project-level-permissions.md). +> [!NOTE] +> Team administrators can configure settings for their team's tools. Organization owners and members of the **Project Administrators** group can configure settings for all teams. To be added as an administrator, see [Add team administrators](../settings/add-team-administrator.md) or [Change project-level permissions](change-project-level-permissions.md). -Access to the following tasks is controlled by each user's access level or by permission assignments. Members of the Readers, Contributors, or Project Administrators group are assumed to have Basic access or greater. +Each user's access level or permission assignment controls access to the following tasks. Members of the Readers, Contributors, or Project Administrators group are assumed to have at least Basic access. ### General work item permissions -You can use work items to track anything you need to track. To learn more, see [Understand how work items are used to track issues, tasks, and epics](../../boards/work-items/about-work-items.md). - -::: moniker range="tfs-2018" -> [!NOTE] -> There are no UI permissions associated with [managing tags](../../boards/queries/add-tags-to-work-items.md). Instead, you can manage them using the [TFSSecurity command line tool](/azure/devops/server/command-line/tfssecurity-cmd#collection-level-permissions). -::: moniker-end +You can use work items to track anything you need to track. For more information, see [Understand how work items are used to track issues, tasks, and epics](../../boards/work-items/about-work-items.md). + [!INCLUDE [temp](includes/boards-work-items.md)] ### Boards -You use [**Boards**](../../boards/boards/kanban-quickstart.md) to implement Kanban methods. Boards present work items as cards and support quick status updates through drag-and-drop. +You use [**Boards**](../../boards/boards/kanban-quickstart.md) to implement Kanban/Agile methods. Boards present work items as cards and support quick status updates through drag-and-drop. [!INCLUDE [temp](includes/boards-boards.md)] @@ -82,29 +70,25 @@ You use [**Boards**](../../boards/boards/kanban-quickstart.md) to implement Kanb [!INCLUDE [temp](includes/boards-backlogs.md)] - ### Sprints -You use sprint tools to implement Scrum methods. The [**Sprints**](../../boards/sprints/assign-work-sprint.md) set of tools provide filtered views of work items that a team has assigned to specific iteration paths or sprints. +You use sprint tools to implement Scrum methods. The [**Sprints**](../../boards/sprints/assign-work-sprint.md) set of tools provide filtered views of work items that a team has assigned to specific iteration paths or sprints. [!INCLUDE [temp](includes/boards-sprints.md)] -### Queries +### Queries [**Queries**](../../boards/queries/view-run-query.md) are filtered lists of work items based on criteria that you define by using a query editor. [Adhoc searches](../../boards/queries/search-box-queries.md) are powered by a semantic search engine. [!INCLUDE [temp](includes/boards-queries.md)] - ### Delivery plans [Delivery plans](../../boards/plans/review-team-plans.md) display work items as cards against a calendar view. This format can be an effective communication tool with managers, partners, and stakeholders for a team. [!INCLUDE [temp](includes/boards-plans.md)] - - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Azure Repos @@ -118,9 +102,9 @@ Stakeholders for private projects have no access to **Repos**. Stakeholders for ::: moniker-end -::: moniker range="azure-devops" +::: moniker range="azure-devops" -### Advanced Security +### Advanced Security You can use [Advanced Security](../../repos/security/configure-github-advanced-security-features.md) to identify security vulnerabilities in your repository. @@ -130,10 +114,9 @@ You can use [Advanced Security](../../repos/security/configure-github-advanced-s [!INCLUDE [temp](includes/advanced-security.md)] - ## Code: Source control -You can connect to your code from the web portal **Code** hub, or using Xcode, Eclipse, IntelliJ, Android Studio, Visual Studio, or Visual Studio Code. Stakeholders for private projects have no access to **Code**. +You can connect to your code from the web portal **Code** hub, or using Xcode, Eclipse, IntelliJ, Android Studio, Visual Studio, or Visual Studio Code. Stakeholders for private projects have no access to **Code**. ::: moniker-end @@ -143,20 +126,15 @@ You can use [Git repositories](../../repos/git/index.yml) to host and collaborat [!INCLUDE [temp](includes/code-git.md)] - - ### TFVC - - -[Team Foundation Version Control (TFVC)](../../repos/tfvc/index.yml) provides a centralized version control system to manage your source control. +[Team Foundation Version Control (TFVC)](../../repos/tfvc/index.yml) provides a centralized version control system to manage your source control. [!INCLUDE [temp](includes/code-tfvc.md)] + - - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Azure Pipelines @@ -170,13 +148,13 @@ You can define and manage your builds and releases from the web portal **Pipelin ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="Permissions**. - ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="<=azure-devops" -## Test +## Azure Test Plans -Users granted **Visual Studio Enterprise** or **Advanced** access level can define and manage manual tests from the web portal. For an overview of manual test features and functions, see [Testing overview](../../test/index.yml). You set several [test permissions at the project level](change-project-level-permissions.md) from **Project Settings>Permissions**. +Users granted **Basic + Test Plans** or **Visual Studio Enterprise** access level can define and manage manual tests from the web portal. For an overview of manual test features and functions, see [Testing overview](../../test/index.yml). You set several [test permissions at the project level](change-project-level-permissions.md) from **Project Settings>Permissions**. ::: moniker-end [!INCLUDE [temp](includes/test.md)] -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Azure Artifacts -::: moniker-end - -::: moniker range="azure-devops" - -You can manage feeds from the web portal, **Artifacts**. Users granted Stakeholder or Basic access, or higher can access Azure Artifacts features. To set permissions, see [Secure feeds using permissions](../../artifacts/feeds/feed-permissions.md). ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="azure-devops" -You can manage feeds from the web portal, **Artifacts**. Users granted Basic access or higher can access Azure Artifacts features. Users granted Stakeholder access have no access to Azure Artifacts. To set permissions, see [Secure feeds using permissions](../../artifacts/feeds/feed-permissions.md). +You can manage feeds from the web portal, **Artifacts**. Users with at least Stakeholder or Basic access can access Azure Artifacts features. To set permissions, see [Secure feeds using permissions](../../artifacts/feeds/feed-permissions.md). ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range=" Packages**. Users granted Basic access or higher can access Package management features. Users granted Stakeholder access have no access. To set permissions, see [Secure feeds using permissions](../../artifacts/feeds/feed-permissions.md). +You can manage feeds from the web portal, **Artifacts**. Users with at least Basic access can access Azure Artifacts features. Users with Stakeholder access can't. To set permissions, see [Secure feeds using permissions](../../artifacts/feeds/feed-permissions.md). ::: moniker-end [!INCLUDE [temp](includes/package-feeds.md)] - -## Notifications, alerts, and team collaboration tools +## Notifications, alerts, and team collaboration tools To manage notifications, see [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md) and [Manage team notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md). @@ -261,12 +205,11 @@ To manage notifications, see [Manage personal notifications](../../organizations [!INCLUDE [temp](includes/collaborate.md)] - ## Dashboards, charts, reports, and widgets ::: moniker range="azure-devops" -You can define and manage team and project dashboards from the web portal, **Dashboards**. For an overview of dashboard and chart features, see [Dashboards](../../report/dashboards/overview.md). You can set [individual dashboard permissions](../../report/dashboards/dashboard-permissions.md) to grant or restrict the ability to edit or delete dashboards. +You can define and manage team and project dashboards from the web portal, **Dashboards**. For an overview of dashboard and chart features, see [Dashboards](../../report/dashboards/overview.md). You can set [individual dashboard permissions](../../report/dashboards/dashboard-permissions.md) to grant or restrict the ability to edit or delete dashboards. Users granted Stakeholder access to private projects can't view or create query charts. Stakeholder access to public projects can view and create query charts. @@ -274,17 +217,17 @@ Users granted Stakeholder access to private projects can't view or create query ::: moniker range="< azure-devops" -You can define and manage team dashboards from the web portal, **Dashboards**. For an overview of dashboard and chart features, see [Dashboards](../../report/dashboards/overview.md). You set [dashboard permissions at the team level](../../report/dashboards/dashboard-permissions.md) from the team dashboard page. +You can define and manage team dashboards from the web portal, **Dashboards**. For an overview of dashboard and chart features, see [Dashboards](../../report/dashboards/overview.md). You set [dashboard permissions at the team level](../../report/dashboards/dashboard-permissions.md) from the team dashboard page. ::: moniker-end [!INCLUDE [temp](includes/report.md)] -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Power BI Integration and Analytics views -From the web portal **Analytics views**, you can create and manage Analytics views. An Analytics view provides a simplified way to specify the filter criteria for a Power BI report based on the Analytics Service data store. The Analytics Service is the reporting platform for Azure DevOps. To learn more, see [What is the Analytics Service?](../../report/powerbi/what-is-analytics.md). +From the web portal **Analytics views**, you can create and manage Analytics views. An Analytics view provides a simplified way to specify the filter criteria for a Power BI report based on the Analytics Service data store. The Analytics Service is the reporting platform for Azure DevOps. For more information, see [What is the Analytics Service?](../../report/powerbi/what-is-analytics.md). You set [permissions](../../report/powerbi/analytics-security.md) for the service at the project level, and for shared Analytics views at the object level. Users with **Stakeholder** access have no access to view or edit Analytics views. @@ -292,13 +235,10 @@ You set [permissions](../../report/powerbi/analytics-security.md) for the servic ::: moniker-end - ## Related articles - [Add users to a project or team](../../organizations/security/add-users-team-project.md) -- [Security and permission management tools](security-tools-reference.md) - [Permissions and groups reference](permissions.md) - [About access levels](access-levels.md) -- [Web portal navigation](../../project/navigation/index.md) +- [Web portal navigation](../../project/navigation/index.md) - [Troubleshoot permissions](troubleshoot-permissions.md) - diff --git a/docs/organizations/security/permissions-lookup-guide.md b/docs/organizations/security/permissions-lookup-guide.md index 2591f371408..fb3eb5752ad 100644 --- a/docs/organizations/security/permissions-lookup-guide.md +++ b/docs/organizations/security/permissions-lookup-guide.md @@ -11,14 +11,14 @@ monikerRange: '<= azure-devops' ms.date: 04/04/2022 --- -# Permissions lookup guide for Azure DevOps +# Permissions lookup guide [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] Use this index to locate the article on how to manage a specific permission. Most permissions are managed through the user interface for an object, project, or collection. Other permissions are managed by adding users and groups to a role. > [!NOTE] -> You can manage permissions through a command line tool or REST API. Some permissions are only managed through these tools. To learn more, see [Security and permission management tools](security-tools-reference.md) and [Security namespace and permission reference](namespace-reference.md). +> You can manage permissions through a command line tool or REST API. Some permissions are only managed through these tools. For more information, see [Security namespace and permission reference](namespace-reference.md). If you're new to Azure DevOps, review [Get started with permissions, access, and security groups](about-permissions.md) and [About security roles](about-security-roles.md). @@ -26,41 +26,39 @@ Values in parenthesis indicate what level the permission is managed: ::: moniker range="azure-devops" -- **Object**: Permissions are managed at the object-level -- **Project**: Permissions are managed at the project level -- **Collection**: Permissions are managed at the organization level +- **Object**: Permissions are managed at the object level. +- **Project**: Permissions are managed at the project level. +- **Collection**: Permissions are managed at the organization level. - **Role**: Permissions are managed through a security role. - **Team**: Permissions are managed via the team administrator role. ::: moniker-end ::: moniker range="< azure-devops" -- **Object**: Permissions are managed at the object-level -- **Project**: Permissions are managed at the project level -- **Collection**: Permissions are managed at the account or project collection level +- **Object**: Permissions are managed at the object level. +- **Project**: Permissions are managed at the project level. +- **Collection**: Permissions are managed at the account or project collection level. - **Role**: Permissions are managed through a security role. -- **Server**: Permissions are managed at the instance level for a server +- **Server**: Permissions are managed at the instance level for a server. - **Team**: Permissions are managed via the team administrator role. ::: moniker-end - - :::row::: :::column span="1"::: ### A ::: moniker range="azure-devops" - - [Administer build permissions (Object)](../../pipelines/policies/permissions.md) + - [Administer build permissions (Object)](../../pipelines/policies/permissions.md#pipeline-permissions) - [Administer build resource permissions (Collection)](change-organization-collection-level-permissions.md) - - [Administer release permissions (Object)](../../pipelines/policies/permissions.md) + - [Administer release permissions (Object)](../../pipelines/policies/permissions.md#release-pipeline-permissions) - [Administer process permissions (Collection)](change-organization-collection-level-permissions.md) - [Administer shelved changes (Collection)](change-organization-collection-level-permissions.md) - - [Administer task group permissions (Object)](../../pipelines/policies/permissions.md) + - [Administer task group permissions (Object)](../../pipelines/policies/permissions.md#task-group-permissions) - [Administer shelved changes (Collection)](change-organization-collection-level-permissions.md) - [Administer workspaces (Collection)](change-organization-collection-level-permissions.md) - [Advanced Security](../../repos/security/github-advanced-security-permissions.md) - - [Agent queues (Project, Role)](../../pipelines/policies/set-permissions.md) - - [Agent pools (Collection, Role)](../../pipelines/policies/set-permissions.md) + - [Agent queues (Project, Role)](../../pipelines/policies/permissions.md#agent-pool-permissions) + - [Agent pools (Collection, Role)](../../pipelines/policies/permissions.md#agent-pool-permissions) - [Alerts (Collection)](/azure/devops/server/command-line/tfssecurity-cmd#collection-level-permissions) - [Alerts (Team)](../../organizations/notifications/manage-team-group-global-organization-notifications.md) - [Analytics Service (Project)](../../report/powerbi/analytics-security.md) @@ -70,17 +68,17 @@ Values in parenthesis indicate what level the permission is managed: - [Audit log](permissions.md#manage-audit-streams-permission) - [Audit streams](permissions.md#view-audit-log-permission) ::: moniker-end - ::: moniker range=">= azure-devops-2019 < azure-devops" - - [Administer build permissions (Object)](../../pipelines/policies/permissions.md) + ::: moniker range=" +--- > [!NOTE] -> The images you see from your web portal may differ from the images you see in this topic. These differences result from updates made to Azure DevOps. However, the basic functionality available to you remains the same unless explicitly mentioned. - - +> The images shown in your web portal might differ from the images in this article due to system updates, but the basic functionality remains the same unless explicitly mentioned. ## Service accounts - There are a few service accounts that are generated by the system to support specific operations. These include those described in the following table. These user accounts are added at the organization or collection level. +The system generates a few service accounts to support specific operations. The following table describes these user accounts, which get added at the organization or collection level. | User name | Description | | ----------| ----------- | -| Agent Pool Service | Has permission to listen to the message queue for the specific pool to receive work. In most cases, you should not have to manage members of this group. The agent registration process takes care of it for you. The service account you specify for the agent (commonly Network Service) is automatically added when you register the agent. Responsible for performing Azure Boards read/write operations and updating work items when GitHub objects are updated. | -| Azure Boards | Added when Azure Boards is [connected to GitHub](../../boards/github/connect-to-github.md). You should not have to manage members of this group. Responsible for managing the link creation between GitHub and Azure Boards. | +| Agent Pool Service | Has permission to listen to the message queue for the specific pool to receive work. In most cases, you don't need to manage group members directly - the agent registration process handles it for you. When you register the agent, the service account you specify (typically Network Service) automatically gets added. Responsible for performing Azure Boards read/write operations and updating work items when GitHub objects change. | +| Azure Boards | Added when Azure Boards is [connected to GitHub](../../boards/github/connect-to-github.md). You shouldn't have to manage members of this group. Responsible for managing the link creation between GitHub and Azure Boards. | | PipelinesSDK | Added as needed to support the Pipelines policy service scope tokens. This user account is similar to the build service identities but supports locking down permissions separately. In practice, the tokens that involve this identity are granted read-only permissions to pipeline resources and the one-time ability to approve policy requests. This account should be treated in the same way that the build service identities are treated. | -| *ProjectName* Build Service | Has permissions to run build services for the project. This is a legacy user used for XAML builds. It is added to the Security Service Group, which is used to store users who have been granted permissions, but not added to any other security group. | -| Project Collection Build Service | Has permissions to run build services for the collection. It is added to the Security Service Group, which is used to store users who have been granted permissions, but not added to any other security group. | +| *ProjectName* Build Service | Has permissions to run build services for the project and is a legacy user used for XAML builds. It's automatically a member of the Security Service Group, which is used to store users who are granted permissions, but no other security group. | +| Project Collection Build Service | Has permissions to run build services for the collection. It's automatically a member of the Security Service Group, which is used to store users who are granted permissions, but no other security group. | - + ## Groups - Permissions can be granted directly to an individual, or to a group. - Using groups makes things a lot simpler. - The system provides several built-in groups for that purpose. - These groups and the default permissions they're assigned are defined at different levels: - server (on-premises deployment only), project collection, project, and specific objects. - You can also create your own groups and grant them the specific set of permissions - that are appropriate for certain roles in your organization. +You can grant permissions directly to an individual, or to a group. +Using groups makes things simpler and the system provides several built-in groups for that purpose. +These groups and the default permissions they're assigned get defined at different levels: server (on-premises deployment only), project collection, project, and specific objects. You can also create your own groups and grant them the specific set of permissions that are appropriate for certain roles in your organization. ::: moniker range="azure-devops" [!INCLUDE [version-all](./includes/hidden-security-groups.md)] ::: moniker-end - - - - - + ::: moniker range="< azure-devops" ## Server-level groups -When you install Azure DevOps Server, the system creates default groups that have [deployment-wide, server-level permissions](#server-permissions). You cannot remove or delete the built-in server-level groups. - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" +When you install Azure DevOps Server, the system creates default groups that have [deployment-wide, server-level permissions](#server-permissions). You can't remove or delete the built-in server-level groups. > [!div class="mx-imgBorder"] > ![Screenshot of Azure DevOps Security group dialog.](media/permissions/server-level-groups-azdo-2019-update1.png) -::: moniker-end - -::: moniker range="< azure-devops-2019" - -![Screenshot of Azure DevOps Security group dialog, TFS-2018 version.](media/permissions/server-groups-and-permissions.png) - -::: moniker-end - -::: moniker range="< azure-devops" +You can't remove or delete the default server level groups. - You can't remove or delete the default server level groups. - -> [!NOTE] -> The full name of each of these groups is **[Team Foundation]\\{group name}**. -> So the full name of the server level administrators group is -> **[Team Foundation]\\Team Foundation Administrators**. +The full name of each of these groups is **[Team Foundation]\\{group name}**. So the full name of the server level administrators group is **[Team Foundation]\\Team Foundation Administrators**. - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - :::row::: :::column span="1"::: **Group name** @@ -189,9 +142,7 @@ When you install Azure DevOps Server, the system creates default groups that hav and not user accounts or groups that contain user accounts. By default, this group is a member of **Team Foundation Administrators**. - If you need to add an account to this group after you install Azure DevOps Server, you can do so using - the TFSSecurity.exe utility in the **Tools** subfolder of your on-premises installation directory. - The command to do this is `TFSSecurity /g+ "[TEAM FOUNDATION]\Team Foundation Service Accounts" n:domain\username /server:http(s)://tfsservername` + To add an account to this group after you install Azure DevOps Server, use the TFSSecurity.exe utility in the **Tools** subfolder of your on-premises installation directory. Use the following command: `TFSSecurity /g+ "[TEAM FOUNDATION]\Team Foundation Service Accounts" n:domain\username /server:http(s)://azuredevopsservername`. :::column-end::: :::row-end::: :::row::: @@ -199,12 +150,12 @@ When you install Azure DevOps Server, the system creates default groups that hav Azure DevOps Proxy Service Accounts :::column-end::: :::column span="1"::: - Has service level permissions for Team Foundation Server Proxy, + Has service level permissions for Azure DevOps Server Proxy, and some service-level permissions. > [!NOTE] - > This account is created when you [install the Azure DevOps proxy service](/azure/devops/server/install/install-proxy-setup-remote). + > This account gets created when you [install the Azure DevOps proxy service](/azure/devops/server/install/install-proxy-setup-remote). :::column-end::: - :::column span="1"::: + :::column span="2"::: This group should contain only service accounts and not user accounts or groups that contain user accounts. :::column-end::: @@ -235,8 +186,7 @@ When you install Azure DevOps Server, the system creates default groups that hav *Server* **\Team Foundation Service Accounts** group and the members of the **\Project Server Integration Service Accounts** group. - This group should be restricted to the smallest possible number of users - who need total administrative control over server-level operations. + Limit this group to the fewest users who require full administrative control over server-level operations. > [!NOTE] > If your deployment uses Reporting, consider [adding the members of this group](/azure/devops/server/admin/add-administrator) to the Content Managers groups in Reporting Services. @@ -245,134 +195,43 @@ When you install Azure DevOps Server, the system creates default groups that hav ::: moniker-end -::: moniker range="< azure-devops-2019" +## Collection-level groups -:::row::: - :::column span="1"::: - **Group name** - :::column-end::: - :::column span="1"::: - **Permissions** - :::column-end::: - :::column span="1"::: - **Membership** - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Team Foundation Administrators - :::column-end::: - :::column span="1"::: - Has permissions to perform all server-level operations. - :::column-end::: - :::column span="1"::: - **Local Administrators** group (BUILTIN\Administrators) - for any server that hosts Azure DevOPs/Team Foundation application services. +When you create an organization or project collection in Azure DevOps, the system creates collection-level groups that have [permissions in that collection](#collection-level). You can't remove or delete the built-in collection-level groups. - *Server* **\Team Foundation Service Accounts** group - and the members of the **\Project Server Integration Service Accounts** group. + - This group should be restricted to the smallest possible number of users - who need total administrative control over server-level operations. +::: moniker range="azure-devops" +> [!NOTE] +> To enable the **Organizations Permissions Settings Page v2** preview page,see [Enable preview features](../../project/navigation/preview-features.md). The preview page provides a group settings page that the current page doesn't. +::: moniker-end - > [!NOTE] - > If your deployment uses Reporting, consider [adding the members of this group to the Content Managers groups in Reporting Services](/azure/devops/server/admin/add-administrator). +#### [Preview page](#tab/preview-page) - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Team Foundation Proxy Service Accounts - :::column-end::: - :::column span="1"::: - Has service level permissions for Team Foundation Server Proxy, - and some service-level permissions. - > [!NOTE] - > This account is created when you [install the TFS proxy service](/azure/devops/server/install/install-proxy-setup-remote). - :::column-end::: - :::column span="1"::: - This group should contain only service accounts and not user accounts or groups - that contain user accounts. - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Team Foundation Service Accounts - :::column-end::: - :::column span="1"::: - Has service-level permissions for the server instance. - :::column-end::: - :::column span="1"::: - Contains the service account that was supplied during installation - - This group should contain only service accounts - and not user accounts or groups that contain user accounts. - By default, this group is a member of **Team Foundation Administrators**. +::: moniker range="< azure-devops" - If you need to add an account to this group after you install Azure DevOps Server, you can do so using - the TFSSecurity.exe utility in the **Tools** subfolder of your TFS installation directory. - The command to do this is `TFSSecurity /g+ "[TEAM FOUNDATION]\Team Foundation Service Accounts" n:domain\username /server:http(s)://tfsservername` - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - Team Foundation Valid Users - :::column-end::: - :::column span="1"::: - Has permission to view server instance-level information. - > [!NOTE] - > If you set the **View instance-level information** permission to **Deny** or **Not set** for this group, no users will be able to access the deployment. - :::column-end::: - :::column span="1"::: - Contains all users known to exist in the server instance. - You can't modify the membership of this group. - :::column-end::: -:::row-end::: +Preview page is not available for on-premises versions. ::: moniker-end - - - - -## Collection-level groups - - When you create an organization or project collection in Azure DevOps, the system creates collection-level groups that have [permissions in that collection](#collection-level). You cannot remove or delete the built-in collection-level groups. - - - ::: moniker range="azure-devops" -> [!NOTE] -> To enable the **Organizations Permissions Settings Page v2** preview page,see [Enable preview features](../../project/navigation/preview-features.md). The preview page provides a group settings page that the current page does not. - > [!div class="mx-imgBorder"] > ![Screenshot of Project collection groups, new user interface.](media/permissions/collection-admin-permissions-vsts-new.png) ::: moniker-end -::: moniker range="< azure-devops" +#### [Current page](#tab/current-page) > [!div class="mx-imgBorder"] > ![Screenshot of Project collection groups, on-premises versions.](media/permissions/collection-admin-permissions-vsts.png) -::: moniker-end - +--- The full name of each of these groups is **[{collection name}]\\{group name}**. So the full name of the administrator group for the default collection is **[Default Collection]\\Project Collection Administrators**. - :::row::: :::column span="1"::: **Group name** @@ -393,9 +252,9 @@ So the full name of the administrator group for the default collection is :::column-end::: :::column span="2"::: Contains the **Local Administrators** group (BUILTIN\Administrators) - for the server where the application-tier services have been installed. - Also, contains the members of the *CollectionName*/**Service Accounts** group. - This group should be restricted to the smallest possible number of users who need total administrative control over the collection. + for the server where the application-tier services are installed. + Contains the members of the *CollectionName*/**Service Accounts** group. + Limit this group to the fewest users who require full administrative control over the collection. ::: moniker range="< azure-devops-2022" > [!NOTE] > If your deployment uses Reporting Services, consider adding the members of this group to the [Team Foundation Content Managers groups in Reporting Services](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports). @@ -410,7 +269,7 @@ So the full name of the administrator group for the default collection is Has permissions to administer build resources and permissions for the collection. :::column-end::: :::column span="2"::: - Limit this group to the smallest possible number of users who need total administrative control over build servers and services for this collection. + Limit this group to the fewest users who require full administrative control over build servers and services for this collection. :::column-end::: :::row-end::: :::row::: @@ -465,21 +324,21 @@ So the full name of the administrator group for the default collection is Has permissions to access team projects and view information in the collection. :::column-end::: :::column span="2"::: - Contains all users and groups that have been added anywhere within the collection. You cannot modify the membership of this group. + Contains all users and groups added anywhere within the collection. You can't modify the membership of this group. :::column-end::: :::row-end::: ::: moniker range="azure-devops" :::row::: :::column span="1"::: - Project-Scoped Users + Project-Scoped Users :::column-end::: :::column span="1"::: - Has limited access to view organization settings and projects other than those projects they are specifically added to. Also, people picker options are limited to those users and groups that have been explicitly added to the project the user is connected to. + Has limited access to view organization settings and projects other than those projects they are specifically added to. Also, people picker options are limited to those users and groups explicitly added to the project the user is connected to. :::column-end::: :::column span="2"::: - Add users to this group when you want to limit their visibility and access to those projects that you explicitly add them to. Do not add users to this group if they are also added to the Project Collection Administrators group. + Add users to this group when you want to limit their visibility and access to those projects that you explicitly add them to. don't add users to this group if they are also added to the Project Collection Administrators group. > [!NOTE] - > The **Project-Scoped Users** group becomes available with restricted access when the organization-level preview feature, **Limit user visibility and collaboration to specific projects** is enabled. For more information including important security-related call-outs, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). + > The **Project-Scoped Users** group becomes available with limited access when the organization-level preview feature, **Limit user visibility and collaboration to specific projects** is enabled. For more information including important security-related call-outs, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). :::column-end::: :::row-end::: ::: moniker-end @@ -488,10 +347,10 @@ So the full name of the administrator group for the default collection is Security Service Group :::column-end::: :::column span="1"::: - Used to store users who have been granted permissions, but not added to any other security group. + Used to store users with permissions, but not added to any other security group. :::column-end::: :::column span="2"::: - Don't assign users to this group. If you are removing users from all security groups, check if you need to remove them from this group. + Don't assign users to this group. If you're removing users from all security groups, check whether you need to remove them from this group. :::column-end::: :::row-end::: @@ -505,41 +364,35 @@ So the full name of the administrator group for the default collection is Release Administrators [team name] --> - - + ## Project-level groups For each project that you create, the system creates the followings project-level groups. These groups are assigned [project-level permissions](#team-project-level-permissions). - -::: moniker range="azure-devops" - > [!NOTE] > To enable the preview page for the **Project Permissions Settings Page**, see [Enable preview features](../../project/navigation/preview-features.md). -#### [Preview page](#tab/preview-page) - -:::image type="content" source="media/permissions/project-level-groups-new.png" alt-text="Project-level groups and permissions, Azure DevOps preview version."::: +#### [Preview page](#tab/preview-page) -#### [Current page](#tab/current-page) - -:::image type="content" source="media/permissions/project-level-groups-current.png" alt-text="Project-level groups and permissions, Azure DevOps current."::: +::: moniker range="< azure-devops" -* * * +Preview page is not available for on-premises versions. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - -:::image type="content" source="media/permissions/project-level-groups-current.png" alt-text="Project-level groups and permissions, Azure DevOps current."::: +::: moniker range="azure-devops" -::: moniker-end +:::image type="content" source="media/permissions/project-level-groups-new.png" alt-text="Screenshot of Project-level groups and permissions, Azure DevOps preview version."::: -::: moniker range="tfs-2018" -:::image type="content" source="media/permissions/project-level-groups-permissions-tfs-2018.png" alt-text="Project-level groups and permissions, TFS-2018 and earlier versions."::: ::: moniker-end +#### [Current page](#tab/current-page) + +:::image type="content" source="media/permissions/project-level-groups-current.png" alt-text="Screenshot of Project-level groups and permissions, Azure DevOps current."::: + +--- + > [!TIP] > The full name of each of these groups is **[{project name}]\\{group name}**. > For example, the contributors group for a project called "My Project" is @@ -572,7 +425,7 @@ For each project that you create, the system creates the followings project-leve Contributors :::column-end::: :::column span="1"::: - Has permissions to contribute fully to the project code base and work item tracking. The main permissions they don't have are those that manage or administer resources. + Has permissions to contribute fully to the project code base and work item tracking. The main permissions they don't have are permissions that manage or administer resources. :::column-end::: :::column span="2"::: By default, the team group created when you create a project is added to this group, and any user you add to the team or project is a member of this group. In addition, any team you create for a project is added to this group. @@ -591,13 +444,13 @@ For each project that you create, the system creates the followings project-leve :::row-end::: :::row::: :::column span="1"::: - Project Administrators + Project Administrators :::column-end::: :::column span="1"::: Has permissions to administer all aspects of teams and project, although they can't create team projects. :::column-end::: :::column span="2"::: - Assign to users who manage user permissions, create or edit teams, modify team settings, define area an iteration path, or customize work item tracking. Members of the Project Administrators group are granted permissions to perform the following tasks: + Assign to users who require the following functions: Manage user permissions, create or edit teams, modify team settings, define area or iteration paths, or customize work item tracking. Members of the Project Administrators group have permissions to perform the following tasks: - Add and remove users from project membership - Add and remove custom security groups from a project - Add and administer all project teams and team-related features @@ -613,7 +466,7 @@ For each project that you create, the system creates the followings project-leve Has permissions to access and view project information. :::column-end::: :::column span="2"::: - Contains all users and groups that have been added anywhere to the project. You cannot modify the membership of this group. + Contains all users and groups added anywhere to the project. You can't modify the membership of this group. > [!NOTE] > We recommend that you don't change the default permissions for this group. :::column-end::: @@ -628,29 +481,27 @@ For each project that you create, the system creates the followings project-leve :::column span="2"::: Assign to users who define and manage release pipelines. > [!NOTE] - > The Release Administrator group is created at the same time the first release pipeline is defined. It isn't created by default when the project is created. + > The Release Administrator group gets created at the same time the first release pipeline is defined. It isn't created by default when the project is created. :::column-end::: :::row-end::: :::row::: :::column span="1"::: - *TeamName* + *TeamName* :::column-end::: :::column span="1"::: Has permissions to contribute fully to the project code base and work item tracking. :::column-end::: :::column span="2"::: - The default Team group is created when you create a project, and by default is added to the Contributors group for the project. Any new teams you create will also have a group created for them and added to the Contributors group. + The default Team group is created when you create a project, and by default is added to the Contributors group for the project. Any new teams you create also have a group created for them and added to the Contributors group. Add members of the team to this group. To grant access to configure team settings, [add a team member to the team administrator role](../settings/add-team-administrator.md). :::column-end::: :::row-end::: - - - ## Team administrator role -For each team that you add, you can assign one or more team members as administrators. The team admin role isn't a group with a set of defined permissions. Instead, the team admin role is tasked with managing team assets. To learn more, see [Manage teams and configure team tools](../settings/manage-teams.md). To add a user as a team administrator, see [Add a team administrator](../settings/add-team-administrator.md). +For each team that you add, you can assign one or more team members as administrators. The team admin role isn't a group with a set of defined permissions. Instead, the team admin role is tasked with managing team assets. For more information, see [Manage teams and configure team tools](../settings/manage-teams.md). To add a user as a team administrator, see [Add a team administrator](../settings/add-team-administrator.md). > [!NOTE] > Project Administrators can manage all team administrative areas for all teams. @@ -669,11 +519,11 @@ For each team that you add, you can assign one or more team members as administr ## Permissions ::: moniker range="azure-devops" -The system manages permissions at different levels—organization, project, object as well as role-based permissions—and by default assigns them to one or more built-in groups. You can manage most permissions through the web portal. Additional permissions can be managed using one or more [security management tools](security-tools-reference.md) by specifying a namespace permission. +The system manages permissions at different levels—organization, project, object, and role-based permissions—and by default assigns them to one or more built-in groups. You can manage most permissions through the web portal. Manage more permissions with the [command line tool (CLI)](manage-tokens-namespaces.md). ::: moniker-end ::: moniker range="< azure-devops" -The system manages permissions at different levels—server, collection, project, object as well as role-based permissions—and by default assigns them to one or more built-in groups. You manage most permissions through the web portal. Additional permissions can be managed using one or more [security management tools](security-tools-reference.md) by specifying a namespace permission. +The system manages permissions at different levels—server, collection, project, object, and role-based permissions—and by default assigns them to one or more built-in groups. You can manage most permissions through the web portal. Manage more permissions with the [command line tool (CLI)](manage-tokens-namespaces.md). ::: moniker-end In the following sections, the namespace permission is provided following the permission label that displays in the user interface. For example: @@ -681,16 +531,13 @@ In the following sections, the namespace permission is provided following the pe `Tagging, Create` For more information, see [Security namespace and permission reference](namespace-reference.md). - - - ::: moniker range="< azure-devops" ## Server-level permissions - You manage server-level permissions through the [Team Foundation Administration Console](/azure/devops/server/admin/add-administrator) or [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#permissions). Team Foundation Administrators are granted all server-level permissions. Other server-level groups have select permission assignments. +Manage server-level permissions through the [Team Foundation Administration Console](/azure/devops/server/admin/add-administrator) or [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#permissions). Team Foundation Administrators are granted all server-level permissions. Other server-level groups have select permission assignments. > [!div class="mx-imgBorder"] > ![Screenshot of Server-level permissions.](media/permissions/global-security-azdo-server-2019-update-1.png) @@ -708,19 +555,21 @@ For more information, see [Security namespace and permission reference](namespac :::row::: :::column span="2"::: Administer warehouse + `Warehouse, Administer` :::column-end::: :::column span="2"::: - This permission is only valid for Azure DevOps Server 2020 and earlier versions that are configured to support SQL Server reports. Can process or change settings for the data warehouse or SQL Server Analysis cube + Only valid for Azure DevOps Server 2020 and earlier versions that are configured to support SQL Server reports. Can process or change the settings for the data warehouse or SQL Server Analysis cube by using the [Warehouse Control Web Service](/previous-versions/azure/devops/report/admin/manage-reports-data-warehouse-cube). - Additional permissions may be required to fully process + More permissions might be required to fully process or [rebuild the data warehouse and Analysis cube](/previous-versions/azure/devops/report/admin/rebuild-data-warehouse-and-cube). :::column-end::: :::row-end::: :::row::: :::column span="2"::: Create project collection + `CollectionManagement, CreateCollection` :::column-end::: :::column span="2"::: @@ -730,28 +579,27 @@ For more information, see [Security namespace and permission reference](namespac :::row::: :::column span="2"::: Delete project collection + `CollectionManagement, DeleteCollection` :::column-end::: :::column span="2"::: Can delete a collection from the deployment. > [!NOTE] - > Deleting a collection won't delete the collection database from SQL Server. + > Deleting a collection doesn't delete the collection database from SQL Server. :::column-end::: :::row-end::: :::row::: :::column span="2"::: Edit instance-level information + `Server, GenericWrite` :::column-end::: :::column span="2"::: Can edit server-level permissions for users and groups, and add or remove server level groups from the collection. - :::column-end::: -:::row-end::: -:::row::: - :::column span="4"::: + > [!NOTE] > **Edit instance-level information** includes the ability to perform these tasks defined in all collections defined for the instance: > - Modify **Extensions** and **Analytics** settings @@ -761,11 +609,13 @@ For more information, see [Security namespace and permission reference](namespac > - Create and modify global lists > > To grant all these permissions at a command prompt, you must use the `tf.exe Permission` command to grant the `AdminConfiguration` and `AdminConnections` permissions in addition to `GENERIC_WRITE`. + :::column-end::: :::row-end::: :::row::: :::column span="2"::: Make requests on behalf of others + `Server, Impersonate` :::column-end::: :::column span="2"::: @@ -775,6 +625,7 @@ For more information, see [Security namespace and permission reference](namespac :::row::: :::column span="2"::: Trigger events + `Server, TriggerEvent` :::column-end::: :::column span="2"::: @@ -788,18 +639,17 @@ For more information, see [Security namespace and permission reference](namespac :::column-end::: :::column span="2"::: - Can use all on-premises Web portal features. This permission has been deprecated with Azure DevOps Server 2019 and later versions. - :::column-end::: -:::row-end::: -:::row::: - :::column span="4"::: + Can use all on-premises Web portal features. This permission is deprecated with Azure DevOps Server 2019 and later versions. + > [!NOTE] - > If the **Use full Web Access** features permission is set to Deny, the user will only see those features permitted for the **Stakeholder** group (see [Change access levels](change-access-levels.md)). A Deny will override any implicit Allow, even for accounts that are members of administrative groups such as Team Foundation Administrators. + > If the **Use full Web Access** features permission is set to **Deny**, the user only sees those features permitted for the **Stakeholder** group (see [Change access levels](change-access-levels.md)). A Deny overrides any implicit Allow, even for accounts that are members of administrative groups such as Team Foundation Administrators. + :::column-end::: :::row-end::: :::row::: :::column span="2"::: View instance-level information + `Server, GenericRead` :::column-end::: :::column span="2"::: @@ -809,23 +659,20 @@ For more information, see [Security namespace and permission reference](namespac :::column-end::: :::row-end::: - ::: moniker-end - - ::: moniker range="azure-devops" ## Organization-level permissions -You manage organization-level permissions through the [web portal admin context](../../project/navigation/go-to-service-page.md#collection-admin-context) or with the [az devops security group](add-manage-security-groups.md) commands. Project Collection Administrators are granted all organization-level permissions. Other organization-level groups have select permission assignments. +Manage organization-level permissions through the [web portal admin context](../../project/navigation/go-to-service-page.md#collection-admin-context) or with the [az devops security group](add-manage-security-groups.md) commands. Project Collection Administrators are granted all organization-level permissions. Other organization-level groups have select permission assignments. > [!NOTE] > To enable the preview page for the **Project Permissions Settings Page**, see [Enable preview features](../../project/navigation/preview-features.md). -#### [Preview page](#tab/preview-page) +#### [Preview page](#tab/preview-page) > [!div class="mx-imgBorder"] > ![Screenshot of Organization-level permissions and groups, Azure DevOps Services.](media/permissions/collection-level-permissions-new.png) @@ -852,6 +699,7 @@ You manage organization-level permissions through the [web portal admin context] `Collection, DIAGNOSTIC_TRACE` :::column-end::: :::column span="2"::: + Can [change the trace settings](/previous-versions/ms400797%28v%3dvs.80%29) for gathering more detailed diagnostic information about Azure DevOps Web services. :::column-end::: :::row-end::: @@ -862,7 +710,8 @@ You manage organization-level permissions through the [web portal admin context] `Collection, CREATE_PROJECTS` :::column-end::: :::column span="2"::: - Can [add a project](../projects/create-project.md) to an organization or project collection. Additional permissions may be required depending on your on-premises deployment. + + Can [add a project](../projects/create-project.md) to an organization or project collection. More permissions may be required depending on your on-premises deployment. :::column-end::: :::row-end::: :::row::: @@ -871,7 +720,8 @@ You manage organization-level permissions through the [web portal admin context] `Project, DELETE` :::column-end::: :::column span="2"::: - Can [delete a project](../projects/delete-project.md). Deleting a project deletes all data that is associated with the project. You cannot undo the deletion of a project except by restoring the collection to a point before the project was deleted. + + Can [delete a project](../projects/delete-project.md). Deleting a project deletes all data that is associated with the project. You can't undo the deletion of a project except by restoring the collection to a point before the project was deleted. :::column-end::: :::row-end::: :::row::: @@ -881,16 +731,13 @@ You manage organization-level permissions through the [web portal admin context] :::column-end::: :::column span="2"::: Can set organization and project-level settings. - :::column-end::: -:::row-end::: -:::row::: - :::column span="4"::: + > [!NOTE] > **Edit instance-level information** includes the ability to perform these tasks for all projects defined in an organization or collection: - > - Modify organization **Overview** settings, **Extensions**, and **Azure Active Directory** settings + > - Modify organization **Overview** settings and **Extensions** > - Modify version control permissions and repository settings > - Edit [event subscriptions](#alerts) or alerts for global notifications, project-level, and team-level events - > - Edit all project and team-level settings for projects defined in the collections. + > - Edit all project and team-level settings for projects defined in the collections :::column-end::: :::row-end::: :::row::: @@ -904,6 +751,7 @@ You manage organization-level permissions through the [web portal admin context] :::row-end::: :::row::: :::column span="4"::: + #### Service Account :::column-end::: :::row-end::: @@ -938,6 +786,7 @@ You manage organization-level permissions through the [web portal admin context] :::row-end::: :::row::: :::column span="4"::: + #### Boards :::column-end::: :::row-end::: @@ -990,13 +839,14 @@ You manage organization-level permissions through the [web portal admin context] :::row-end::: :::row::: :::column span="4"::: + #### Repos Applies only to Team Foundation version control (TFVC) :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Administer shelved changes + Administer shelved changes `VersionControlPrivileges, AdminWorkspaces` :::column-end::: :::column span="2"::: @@ -1023,6 +873,7 @@ You manage organization-level permissions through the [web portal admin context] :::row-end::: :::row::: :::column span="4"::: + #### Pipelines :::column-end::: :::row-end::: @@ -1032,13 +883,14 @@ You manage organization-level permissions through the [web portal admin context] `BuildAdministration, AdministerBuildResourcePermissions` :::column-end::: :::column span="2"::: - Can modify permissions for build resources at the organization or project collection-level. This includes: + Can modify permissions for build resources at the organization or project collection-level, which includes: - [Set retention policies](../../pipelines/policies/retention.md) - [Set resource limits for pipelines](../../pipelines/licensing/concurrent-jobs.md) - [Add and manage agent pools](../../pipelines/agents/pools-queues.md) - [Add and manage deployment pools](../../pipelines/release/deployment-groups/index.md) + > [!NOTE] - > In addition to this permission, Azure DevOps provides role-based permissions governing the [security of agent pools](../../pipelines/policies/permissions.md#set-agent-pool-permissions). Other, [object-level settings](#build-object-level) will override those set at the organization or project-level. + > In addition to this permission, Azure DevOps provides role-based permissions governing the [security of agent pools](../../pipelines/policies/permissions.md). Other, [object-level settings](#build-object-level) will override those set at the organization or project-level. :::column-end::: :::row-end::: :::row::: @@ -1079,6 +931,7 @@ You manage organization-level permissions through the [web portal admin context] :::row-end::: :::row::: :::column span="4"::: + #### Test Plans :::column-end::: :::row-end::: @@ -1088,12 +941,13 @@ You manage organization-level permissions through the [web portal admin context] `Collection, MANAGE_TEST_CONTROLLERS` :::column-end::: :::column span="2"::: - Can register and de-register test controllers. + Can register and deregister test controllers. :::column-end::: :::row-end::: :::row::: :::column span="4"::: + #### Auditing :::column-end::: :::row-end::: @@ -1103,7 +957,7 @@ You manage organization-level permissions through the [web portal admin context] `AuditLog, Delete_Streams` :::column-end::: :::column span="2"::: - Can delete an audit stream. Audit streams are in preview. For details, see [Create audit streaming](../audit/auditing-streaming.md). + Can delete an audit stream. Audit streams are in preview. For more information, see [Create audit streaming](../audit/auditing-streaming.md). :::column-end::: :::row-end::: :::row::: @@ -1112,7 +966,7 @@ You manage organization-level permissions through the [web portal admin context] `AuditLog, Manage_Streams` :::column-end::: :::column span="2"::: - Can add an audit stream. Audit streams are in preview. For details, see [Create audit streaming](../audit/auditing-streaming.md). + Can add an audit stream. Audit streams are in preview. For more information, see [Create audit streaming](../audit/auditing-streaming.md). :::column-end::: :::row-end::: :::row::: @@ -1121,11 +975,12 @@ You manage organization-level permissions through the [web portal admin context] `AuditLog, Read` :::column-end::: :::column span="2"::: - Can view and export audit logs. Audit logs are in preview. For details, see [Access, export, and filter audit logs](../audit/azure-devops-auditing.md). + Can view and export audit logs. Audit logs are in preview. For more information, see [Access, export, and filter audit logs](../audit/azure-devops-auditing.md). :::column-end::: :::row-end::: :::row::: :::column span="4"::: + #### Policies :::column-end::: :::row-end::: @@ -1144,27 +999,19 @@ You manage organization-level permissions through the [web portal admin context] > [!div class="mx-imgBorder"] > ![Screenshot of Collection-level permissions dialog, Azure DevOps Services current page and on-premises.](media/permissions/collection-level-permissions.png) - [!INCLUDE [note-collection-level-permissions](includes/note-collection-level-permissions.md)] - [!INCLUDE [collection-level-permissions-reference-table](includes/collection-level-permissions-reference-table-cloud.md)] -* * * - +--- + ::: moniker-end ::: moniker range="< azure-devops" ## Collection-level permissions -::: moniker-end - -::: moniker range="< azure-devops" -You manage collection-level permissions through the [web portal admin context](../../project/navigation/go-to-service-page.md#collection-admin-context) or the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#collection-level-permissions). Project Collection Administrators are granted all collection-level permissions. Other collection-level groups have select permission assignments. -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" +Manage collection-level permissions through the [web portal admin context](../../project/navigation/go-to-service-page.md#collection-admin-context) or the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#collection-level-permissions). Project Collection Administrators are granted all collection-level permissions. Other collection-level groups have select permission assignments. The permissions available for Azure DevOps Server 2019 and later versions vary depending on the process model configured for the collection. For an overview of process models, see [Customize work tracking](../../reference/customize-work.md). @@ -1176,6 +1023,7 @@ The permissions available for Azure DevOps Server 2019 and later versions vary d **On-premises XML process model** :::column-end::: :::row-end::: +--- :::row::: :::column span="2"::: > [!div class="mx-imgBorder"] @@ -1186,44 +1034,53 @@ The permissions available for Azure DevOps Server 2019 and later versions vary d > ![Screenshot of Collection level permissions, on-premises, On-premises XML process model.](media/permissions/collection-level-permissions-2020-xml-on-premises-1.png) :::column-end::: :::row-end::: -::: moniker-end - -::: moniker range="tfs-2018" - -> [!div class="mx-imgBorder"] -> ![Collection level permissions and groups](media/permissions/collection-level-permissions-2018.png) - -::: moniker-end - [!INCLUDE [note-collection-level-permissions](includes/note-collection-level-permissions.md)] - [!INCLUDE [collection-level-permissions-reference-table](includes/collection-level-permissions-reference-table.md)] - +::: moniker-end + + - + ## Project-level permissions +> [!IMPORTANT] +> To access project-level resources, the **View project-level information** permission must be set to **Allow**. This permission gates all other project-level permissions. + ::: moniker range="azure-devops" -You manage project-level permissions through the [web portal admin context](change-project-level-permissions.md) or with the [az devops security group](add-manage-security-groups.md) commands. Project Administrators are granted all project-level permissions. Other project-level groups have select permission assignments. +Manage project-level permissions through the [web portal admin context](change-project-level-permissions.md) or with the [az devops security group](add-manage-security-groups.md) commands. Project Administrators are granted all project-level permissions. Other project-level groups have select permission assignments. > [!NOTE] > To enable the **Project Permissions Settings Page** preview page, see [Enable preview features](../../project/navigation/preview-features.md). -#### [Preview page](#tab/preview-page) +::: moniker-end + +::: moniker range="< azure-devops" + +Manage project-level permissions through the [web portal admin context](change-project-level-permissions.md). Project Administrators are granted all project-level permissions. Other project-level groups have select permission assignments. + +::: moniker-end + +#### [Preview page](#tab/preview-page) + +::: moniker range="< azure-devops" + +Preview page is not available for on-premises versions. + +::: moniker-end + +::: moniker range="azure-devops" > [!div class="mx-imgBorder"] > ![Screenshot of Project-level permissions dialog, Azure DevOps Services preview page.](media/permissions/project-permissions-contributors.png) - [!INCLUDE [note-project-level-permissions](includes/note-project-level-permissions.md)] - :::row::: :::column span="2"::: ### Permission (UI) @@ -1232,7 +1089,7 @@ You manage project-level permissions through the [web portal admin context](chan :::column span="2"::: ### Description :::column-end::: -:::row-end::: +:::row-end::: :::row::: :::column span="4"::: #### General @@ -1241,17 +1098,19 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: Delete team project + `Project, DELETE` :::column-end::: :::column span="2"::: Can [delete a project](../projects/delete-project.md) from an organization or project collection. > [!NOTE] - > Even if you set this permission to **Deny**, users granted permission at the project level may be able to delete the project for which they have permission. To ensure that a user isn't able to delete a project, make sure you set the **Delete team project** at the project-level to **Deny** as well. + > Even if you set this permission to **Deny**, users granted permission at the project level can likely delete the project for which they have permission. To ensure that a user can't delete a project, make sure you set the **Delete team project** at the project-level to **Deny** as well. :::column-end::: :::row-end::: :::row::: :::column span="2"::: Edit project-level information + `Project, MANAGE_PROPERTIES` :::column-end::: :::column span="2"::: @@ -1266,6 +1125,7 @@ You manage project-level permissions through the [web portal admin context](chan :::column span="2"::: Manage project properties + `Project, MANAGE_SYSTEM_PROPERTIES` :::column-end::: :::column span="2"::: @@ -1275,6 +1135,7 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: Rename project + `Project, RENAME` :::column-end::: :::column span="2"::: @@ -1284,17 +1145,19 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: Suppress notifications for work item updates + `Project, SUPPRESS_NOTIFICATIONS` :::column-end::: :::column span="2"::: - Users with this permission can update work items without generating notifications. This is useful when performing migrations of bulk updates by tools and want to skip generating notifications. - - Consider granting this permission to service accounts or users who have been granted the **Bypass rules on work item updates** permission. You can set the `suppressNotifications` parameter to `true` when updating working via [Work Items - update REST API](/rest/api/azure/devops/wit/work-items/update). + Users with this permission can update work items without generating notifications. This feature is useful when performing migrations of bulk updates by tools and want to skip generating notifications. + + Consider granting this permission to service accounts or users with the **Bypass rules on work item updates** permission. You can set the `suppressNotifications` parameter to `true` when updating working via [Work Items - update REST API](/rest/api/azure/devops/wit/work-items/update). :::column-end::: :::row-end::: :::row::: :::column span="2"::: Update project visibility + `Project, UPDATE_VISIBILITY` :::column-end::: :::column span="2"::: @@ -1303,11 +1166,12 @@ You manage project-level permissions through the [web portal admin context](chan :::row-end::: :::row::: :::column span="2"::: - View project-level information + View project-level information + `Project, GENERIC_READ` :::column-end::: :::column span="2"::: - Can view project-level information, including security information group membership and permissions. If you set this permission to **Deny** for a user, they aren't able to view the project or sign into the project. + Can view project-level information, including security information group membership and permissions. If you set this permission to **Deny** for a user, they can't view the project or sign in to the project. :::column-end::: :::row-end::: :::row::: @@ -1317,127 +1181,134 @@ You manage project-level permissions through the [web portal admin context](chan :::row-end::: :::row::: :::column span="2"::: - Bypass rules on work item updates + Bypass rules on work item updates
      `Project, BYPASS_RULES` :::column-end::: :::column span="2"::: - Users with this permission can save a work item that ignores rules, such as [copy, constraint, or conditional rules](../settings/work/rule-reference.md), defined for the work item type. Scenarios where this is useful are migrations where you don't want to update the by/date fields on import, or when you want to skip the validation of a work item. - Rules can be bypassed in one of two ways. The first is through the [Work Items - update REST API](/rest/api/azure/devops/wit/work-items/update) and setting the `bypassRules` parameter to `true`. The second is through the client object model, by initializing in bypassrules mode (initialize `WorkItemStore` with `WorkItemStoreFlags.BypassRules`). + Users with this permission can save a work item that ignores rules, such as [copy, constraint, or conditional rules](../settings/work/rule-reference.md), defined for the work item type. Useful scenarios are migrations where you don't want to update the by/date fields on import or when you want to skip the validation of a work item.
      + Rules can be bypassed in one of two ways. The first is through the [Work Items - update REST API](/rest/api/azure/devops/wit/work-items/update) and setting the `bypassRules` parameter to `true`. The second is through the client object model, by initializing in bypass rules mode (initialize `WorkItemStore` with `WorkItemStoreFlags.BypassRules`). :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Change process of project + Change process of project
      `Project, CHANGE_PROCESS` :::column-end::: :::column span="2"::: - When combined with the 'Edit project-level information' permission, allows users to change the Inheritance process for a project. To learn more, see [Create and manage inherited processes](../settings/work/manage-process.md). + + When combined with the 'Edit project-level information' permission, allows users to change the Inheritance process for a project. For more information, see [Create and manage inherited processes](../settings/work/manage-process.md). :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Create tag definition + Create tag definition
      `Tagging, Create` :::column-end::: :::column span="2"::: - [Can add tags to a work item](../../boards/queries/add-tags-to-work-items.md). By default, all members of the Contributors group have this permission. Also, you can set additional tagging permissions through security management tools. See [Security namespace and permission reference, Tagging](namespace-reference.md). -:::row-end::: -:::row::: - :::column span="4"::: + + [Can add tags to a work item](../../boards/queries/add-tags-to-work-items.md). By default, all members of the Contributors group have this permission. Also, you can set more tagging permissions through security management tools. For more information, see [Security namespace and permission reference, Tagging](namespace-reference.md). + > [!NOTE] - > All users granted Stakeholder access for a private project can only add existing tags. Even if the **Create tag definition** permission is set to **Allow**, stakeholders can't add tags. This is part of the Stakeholder access settings. Azure DevOps Services users granted Stakeholder access for a public project are granted this permission by default. To learn more, see [Stakeholder access quick reference](stakeholder-access.md). + > All users granted Stakeholder access for a private project can only add existing tags. Even if the **Create tag definition** permission is set to **Allow**, stakeholders can't add tags. This is part of the Stakeholder access settings. Azure DevOps Services users granted Stakeholder access for a public project are granted this permission by default. For more information, see [Stakeholder access quick reference](stakeholder-access.md). > Although the **Create tag definition** permission appears > in the security settings at the project-level, > tagging permissions are actually collection level permissions that are scoped > at the project level when they appear in the user interface. > To scope tagging permissions to a single project when using the **TFSSecurity** command, > you must provide the GUID for the project as part of the command syntax. - > Otherwise, your change will apply to the entire collection. + > Otherwise, your change applies to the entire collection. > Keep this in mind when changing or setting these permissions. + :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Delete and restore work items - - or Delete work items in this project + Delete and restore work items or Delete work items in this project.
      `Project, WORK_ITEM_DELETE` :::column-end::: :::column span="2"::: + Can [mark work items in the project as deleted](../../boards/backlogs/remove-delete-work-items.md). Azure DevOps Services users granted Stakeholder access for a public project are granted this permission by default. :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Move work items out of this project + Move work items out of this project
      `Project, WORK_ITEM_MOVE` :::column-end::: :::column span="2"::: + Can [move a work item from one project to another project](../../boards/backlogs/remove-delete-work-items.md) within the collection. :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Permanently delete work items in this project + Permanently delete work items in this project
      `Project, WORK_ITEM_PERMANENTLY_DELETE` :::column-end::: :::column span="2"::: + Can [permanently delete work items](../../boards/backlogs/remove-delete-work-items.md) from this project. :::column-end::: :::row-end::: :::row::: :::column span="4"::: + #### Analytics - In addition to the `AnalyticsView` namespace permissions listed in this section, you can set [object-level permissions on each view](#analytics-views-permissions). + In addition to the `AnalyticsView` namespace permissions listed in this section, you can set [object-level permissions on each view](#analytics). :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Delete shared Analytics view + Delete shared Analytics view
      `AnalyticsViews, Delete` :::column-end::: :::column span="2"::: + Can delete [Analytics views](../../report/powerbi/analytics-views-manage.md) - that have been saved under the Shared area. + under the Shared area. :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Edit shared Analytics view + Edit shared Analytics view
      `AnalyticsViews, Edit` :::column-end::: :::column span="2"::: + Can create and modify [shared Analytics views](../../report/powerbi/analytics-views-manage.md). :::column-end::: :::row-end::: :::row::: :::column span="2"::: - View analytics + View analytics
      `AnalyticsViews, Read` :::column-end::: :::column span="2"::: - Can access data available from the [Analytics service](../../report/powerbi/what-is-analytics.md). For details, see [Permissions required to access the Analytics service](../../report/powerbi/analytics-security.md). + Can access data available from the [Analytics service](../../report/powerbi/what-is-analytics.md). For more information, see [Permissions required to access the Analytics service](../../report/powerbi/analytics-security.md). :::column-end::: :::row-end::: :::row::: :::column span="4"::: + #### Test Plans :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Create test runs - `Project, PUBLISH_TEST_RESULTS` + Create test runs
      + `Project, PUBLISH_TEST_RESULTS` :::column-end::: :::column span="2"::: - Can add and remove test results and add or modify test runs. To learn more, see [Control how long to keep test results](../../test/how-long-to-keep-test-results.md) and [Run manual tests](../../test/run-manual-tests.md). + + Can add and remove test results and add or modify test runs. For more information, see [Control how long to keep test results](../../test/how-long-to-keep-test-results.md) and [Run manual tests](../../test/run-manual-tests.md). :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Delete test runs + Delete test runs
      `Project, DELETE_TEST_RESULTS` :::column-end::: :::column span="2"::: @@ -1446,7 +1317,7 @@ You manage project-level permissions through the [web portal admin context](chan :::row-end::: :::row::: :::column span="2"::: - Manage test configurations + Manage test configurations
      `Project, MANAGE_TEST_CONFIGURATIONS` :::column-end::: :::column span="2"::: @@ -1455,7 +1326,7 @@ You manage project-level permissions through the [web portal admin context](chan :::row-end::: :::row::: :::column span="2"::: - Manage test environments + Manage test environments
      `Project, MANAGE_TEST_ENVIRONMENTS` :::column-end::: :::column span="2"::: @@ -1464,7 +1335,7 @@ You manage project-level permissions through the [web portal admin context](chan :::row-end::: :::row::: :::column span="2"::: - View test runs + View test runs
      `Project, VIEW_TEST_RESULTS` :::column-end::: :::column span="2"::: @@ -1472,39 +1343,23 @@ You manage project-level permissions through the [web portal admin context](chan :::column-end::: :::row-end::: -#### [Current page](#tab/current-page) +::: moniker-end + +#### [Current page](#tab/current-page) > [!div class="mx-imgBorder"] > ![Screenshot of Project-level permissions dialog, Azure DevOps Services current page.](media/permissions/project-level-permissions.png) [!INCLUDE [project-level-permissions-reference-table](includes/project-level-permissions-reference-table-cloud.md)] -* * * - -::: moniker-end - -::: moniker range="< azure-devops" - -You manage project-level permissions through the [web portal admin context](change-project-level-permissions.md) or the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#collection-level-permissions). Project Administrators are granted all project-level permissions. Other project-level groups have select permission assignments. +Manage project-level permissions through the [web portal admin context](change-project-level-permissions.md) or the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#collection-level-permissions). Project Administrators are granted all project-level permissions. Other project-level groups have select permission assignments. > [!NOTE] -> Several permissions are granted to members of the [Project Administrators group](#project-administrator-group) and aren't surfaced within the user interface. -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - - > [!div class="mx-imgBorder"] - > ![Project-level permissions, on-premises, Inherited process model](media/permissions/project-level-permissions.png) -::: moniker-end -::: moniker range="tfs-2018" - -> [!div class="mx-imgBorder"] -> ![Screenshot of Project-level permissions dialog, TFS-2018.](media/permissions/project-level-permissions-2018.png) - -::: moniker-end +> Several permissions granted to members of the [Project Administrators group](#project-administrator-group) don't surface within the user interface. +> [!div class="mx-imgBorder"] +> ![Screenshot of Project-level permissions, on-premises, Inherited process model.](media/permissions/project-level-permissions.png) -::: moniker range="< azure-devops" :::row::: :::column span="2"::: ### Permission (UI) @@ -1514,47 +1369,41 @@ You manage project-level permissions through the [web portal admin context](chan ### Description :::column-end::: :::row-end::: -::: moniker-end -::: moniker range="< azure-devops" :::row::: :::column span="2"::: - Bypass rules on work item updates + Bypass rules on work item updates
      `Project, BYPASS_RULES` :::column-end::: :::column span="2"::: - Users with this permission can save a work item that ignores rules, such as [copy, constraint, or conditional rules](../settings/work/rule-reference.md), defined for the work item type. Scenarios where this is useful are migrations where you don't want to update the by or date fields on import, or when you want to skip the validation of a work item. + Users with this permission can save a work item that ignores rules, such as [copy, constraint, or conditional rules](../settings/work/rule-reference.md), defined for the work item type. Useful for migrations where you don't want to update the `by` or `date` fields on import, or when you want to skip the validation of a work item. Rules can be bypassed in one of two ways. The first is through the [Work Items - update REST API](/rest/api/azure/devops/wit/work-items/update) and setting the `bypassRules` parameter to `true`. The second is through the client object model, by initializing in bypass rules mode (initialize `WorkItemStore` with `WorkItemStoreFlags.BypassRules`). :::column-end::: :::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" :::row::: :::column span="2"::: - Change process of project + Change process of project
      `Project, CHANGE_PROCESS` :::column-end::: :::column span="2"::: - When combined with the 'Edit project-level information' permission, allows users to change the Inheritance process for a project. To learn more, see [Create and manage inherited processes](../settings/work/manage-process.md). + When combined with the 'Edit project-level information' permission, allows users to change the Inheritance process for a project. For more information, see [Create and manage inherited processes](../settings/work/manage-process.md). :::column-end::: :::row-end::: -::: moniker-end -::: moniker range="< azure-devops" :::row::: :::column span="2"::: - Create tag definition + Create tag definition
      `Tagging, Create` :::column-end::: :::column span="2"::: - [Can add tags to a work item](../../boards/queries/add-tags-to-work-items.md). By default, all members of the Contributors group have this permission. Also, you can set additional tagging permissions through security management tools. See [Security namespace and permission reference, Tagging](namespace-reference.md). + [Can add tags to a work item](../../boards/queries/add-tags-to-work-items.md). By default, all members of the Contributors group have this permission. Also, you can set more tagging permissions through security management tools. For more information, see [Security namespace and permission reference, Tagging](namespace-reference.md). :::column-end::: :::row-end::: :::row::: :::column span="4"::: > [!NOTE] - > All users granted Stakeholder access can only add existing tags. Even if the **Create tag definition** permission is set to **Allow**, stakeholders can't add tags. This is part of the Stakeholder access settings. To learn more, see [Stakeholder access quick reference](stakeholder-access.md). + > All users granted Stakeholder access can only add existing tags. Even if the **Create tag definition** permission is set to **Allow**, stakeholders can't add tags. This is part of the Stakeholder access settings. For more information, see [Stakeholder access quick reference](stakeholder-access.md). > Although the **Create tag definition** permission appears > in the security settings at the project-level, > tagging permissions are actually collection level permissions that are scoped @@ -1568,44 +1417,37 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: - Create test runs - `Project, PUBLISH_TEST_RESULTS` + Create test runs
      + `Project, PUBLISH_TEST_RESULTS` :::column-end::: :::column span="2"::: - Can add and remove test results and add or modify test runs. To learn more, see [Control how long to keep test results](../../test/how-long-to-keep-test-results.md) and [Run manual tests](../../test/run-manual-tests.md). + Can add and remove test results and add or modify test runs. For more information, see [Control how long to keep test results](../../test/how-long-to-keep-test-results.md) and [Run manual tests](../../test/run-manual-tests.md). :::column-end::: :::row-end::: :::row::: :::column span="2"::: - Delete and restore work items - - or Delete work items in this project + Delete and restore work items or Delete work items in this project
      `Project, WORK_ITEM_DELETE` :::column-end::: :::column span="2"::: Can [mark work items in the project as deleted](../../boards/backlogs/remove-delete-work-items.md). The Contributors group has **Delete and restore work items** at the project-level set to **Allow** by default. :::column-end::: :::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" :::row::: :::column span="2"::: - Delete shared Analytics view + Delete shared Analytics view
      `AnalyticsViews, Delete` :::column-end::: :::column span="2"::: - Can delete [Analytics views](../../report/powerbi/analytics-views-manage.md) - that have been saved under the Shared area. + Can delete [Analytics views](../../report/powerbi/analytics-views-manage.md) under the Shared area. :::column-end::: :::row-end::: -::: moniker-end -::: moniker range="< azure-devops" :::row::: :::column span="2"::: - Delete project + Delete project
      `Project, DELETE` :::column-end::: :::column span="2"::: @@ -1615,7 +1457,7 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: - Delete test runs + Delete test runs
      `Project, DELETE_TEST_RESULTS` :::column-end::: :::column span="2"::: @@ -1625,7 +1467,7 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: - Edit project-level information + Edit project-level information
      `Project, MANAGE_PROPERTIES` :::column-end::: :::column span="2"::: @@ -1636,24 +1478,20 @@ You manage project-level permissions through the [web portal admin context](chan > The permission to add or remove project-level security groups and add and manage project-level group membership is assigned to all members of the **Project Administrators** group. It isn't controlled by a permissions surfaced within the user interface. :::column-end::: :::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" :::row::: :::column span="2"::: - Edit shared Analytics view + Edit shared Analytics view
      `AnalyticsViews, Edit` :::column-end::: :::column span="2"::: Can create and modify [shared Analytics views](../../report/powerbi/analytics-views-manage.md). :::column-end::: :::row-end::: -::: moniker-end -::: moniker range="< azure-devops" :::row::: :::column span="2"::: - Manage project properties + Manage project properties
      `Project, MANAGE_SYSTEM_PROPERTIES` :::column-end::: :::column span="2"::: @@ -1663,7 +1501,7 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: - Manage test configurations + Manage test configurations
      `Project, MANAGE_TEST_CONFIGURATIONS` :::column-end::: :::column span="2"::: @@ -1673,7 +1511,7 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: - Manage test environments + Manage test environments
      `Project, MANAGE_TEST_ENVIRONMENTS` :::column-end::: :::column span="2"::: @@ -1683,7 +1521,7 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: - Move work items out of this project + Move work items out of this project
      `Project, WORK_ITEM_MOVE` :::column-end::: :::column span="2"::: @@ -1693,7 +1531,7 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: - Permanently delete work items in this project + Permanently delete work items in this project
      `Project, WORK_ITEM_PERMANENTLY_DELETE` :::column-end::: :::column span="2"::: @@ -1702,8 +1540,8 @@ You manage project-level permissions through the [web portal admin context](chan :::row-end::: :::row::: :::column span="2"::: - - Rename project + + Rename project
      `Project, RENAME` :::column-end::: :::column span="2"::: @@ -1713,19 +1551,18 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: - Suppress notifications for work item updates + Suppress notifications for work item updates
      `Project, SUPPRESS_NOTIFICATIONS` :::column-end::: :::column span="2"::: - Users with this permission can update work items without generating notifications. This is useful when performing migrations of bulk updates by tools and want to skip generating notifications. - - Consider granting this permission to service accounts or users who have been granted the **Bypass rules on work item updates** permission. You can set the `suppressNotifications` parameter to `true` when updating working via [Work Items - update REST API](/rest/api/azure/devops/wit/work-items/update). + Users with this permission can update work items without generating notifications. Useful for performing migrations of bulk updates by tools and skipping generating notifications.
      + Consider granting this permission to service accounts or users with the **Bypass rules on work item updates** permission. You can set the `suppressNotifications` parameter to `true` when updating working via [Work Items - update REST API](/rest/api/azure/devops/wit/work-items/update). :::column-end::: :::row-end::: :::row::: :::column span="2"::: - - Update project visibility + + Update project visibility
      `Project, UPDATE_VISIBILITY` :::column-end::: :::column span="2"::: @@ -1734,18 +1571,18 @@ You manage project-level permissions through the [web portal admin context](chan :::row-end::: :::row::: :::column span="2"::: - - View analytics + + View analytics
      `AnalyticsViews, Read` :::column-end::: :::column span="2"::: - Can access data available from the [Analytics service](../../report/powerbi/what-is-analytics.md). For details, see [Permissions required to access the Analytics service](../../report/powerbi/analytics-security.md). + Can access data available from the [Analytics service](../../report/powerbi/what-is-analytics.md). For more information, see [Permissions required to access the Analytics service](../../report/powerbi/analytics-security.md). :::column-end::: :::row-end::: :::row::: :::column span="2"::: - View project-level information + View project-level information
      `Project, GENERIC_READ` :::column-end::: :::column span="2"::: @@ -1755,34 +1592,28 @@ You manage project-level permissions through the [web portal admin context](chan :::row::: :::column span="2"::: - View test runs + View test runs
      `Project, VIEW_TEST_RESULTS` :::column-end::: :::column span="2"::: Can view test plans under the project area path. :::column-end::: :::row-end::: -::: moniker-end - - - - -::: moniker range=">= azure-devops-2019" +--- ## Analytics views (object-level) -With shared Analytics views, you can grant specific permissions to view, edit, or delete a view that you create. You manage the security of Analytics views from the [web portal](../../report/powerbi/analytics-security.md). -::: moniker-end +With shared Analytics views, you can grant specific permissions to view, edit, or delete a view that you create. Manage the security of Analytics views from the [web portal](../../report/powerbi/analytics-security.md). + ::: moniker range="azure-devops" -:::image type="content" source="media/permissions/set-analytics-view-shared-permissions.png" alt-text="Shared Analytics view security dialog, change permissions for a user."::: -::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" -:::image type="content" source="media/permissions/analytics-view-permissions.png" alt-text="Manage Shared Analytics view security dialog, change permissions for a user, Azure DevOps Server."::: -::: moniker-end -::: moniker range=">= azure-devops-2019" -The following permissions are defined for each shared Analytics view. All valid users are automatically granted all permissions to manage Analytics views. Consider granting select permissions to specific shared views to other team members or security group that you create. See also, [What are Analytics views](../../report/powerbi/what-are-analytics-views.md)? Additional namespace permissions are supported as defined in [Security namespace and permission reference](namespace-reference.md#analytic-views-namespace). +:::image type="content" source="media/permissions/set-analytics-view-shared-permissions.png" alt-text="Screenshot of Shared Analytics view security dialog, change permissions for a user."::: +::: Moniker-end +::: moniker range=" < azure-devops" +:::image type="content" source="media/permissions/analytics-view-permissions.png" alt-text="Screenshot of Manage Shared Analytics view security dialog, change permissions for a user, Azure DevOps Server."::: +::: Moniker-end +The following permissions are defined for each shared Analytics view. All valid users are automatically granted all permissions to manage Analytics views. Consider granting select permissions to specific shared views to other team members or security group that you create. For more information, see [What are Analytics views?](../../report/powerbi/what-are-analytics-views.md) and [Security namespace and permission reference](namespace-reference.md#analytic-views-namespace). :::row::: :::column span="2"::: ### Permission (UI) @@ -1792,9 +1623,11 @@ The following permissions are defined for each shared Analytics view. All valid ### Description :::column-end::: :::row-end::: +--- :::row::: :::column span="2"::: - Delete shared Analytics views + Delete shared Analytics views + `AnalyticsViews, Delete` :::column-end::: :::column span="2"::: @@ -1803,7 +1636,8 @@ The following permissions are defined for each shared Analytics view. All valid :::row-end::: :::row::: :::column span="2"::: - Edit shared Analytics views + Edit shared Analytics views + `AnalyticsViews, Edit` :::column-end::: :::column span="2"::: @@ -1813,6 +1647,7 @@ The following permissions are defined for each shared Analytics view. All valid :::row::: :::column span="2"::: View shared Analytics views + `AnalyticsViews, Read` :::column-end::: :::column span="2"::: @@ -1820,37 +1655,28 @@ The following permissions are defined for each shared Analytics view. All valid :::column-end::: :::row-end::: - -::: moniker-end - - - - ## Dashboards (object-level) ::: moniker range="azure-devops" -Permissions for team and project dashboards can be set individually. The default permissions for a team can be set for a project. You manage the security of dashboards from the web portal. Additional namespace permissions are supported as defined in [Security namespace and permission reference](namespace-reference.md#dashboard-previleges-namespace). -::: moniker-end - -::: moniker range="azure-devops" +Permissions for team and project dashboards can be set individually. The default permissions for a team can be set for a project. Manage the security of dashboards from the web portal. More namespace permissions are supported as defined in [Security namespace and permission reference](namespace-reference.md#dashboard-previleges-namespace). ### Project dashboard permissions > [!div class="mx-imgBorder"] -> ![Screenshot of Project dashboard permissions dialog](../../report/dashboards/media/set-permissions/add-user-project-permissions.png) +> ![Screenshot of Project dashboard permissions dialog.](../../report/dashboards/media/set-permissions/add-user-project-permissions.png) - By default, the creator of the project dashboard is the dashboard owner and granted all permissions for that dashboard. +By default, the creator of the project dashboard is the dashboard owner and granted all permissions for that dashboard. -|**Permission**
      `Namespace permission` | **Description** | +|**Permission**
      `Namespace permission` | **Description** | |-----------| ----------- | -|Delete dashboard
      `DashboardsPrivileges, Delete` | Can delete the project dashboard. | -|Edit dashboard
      `DashboardsPrivileges, Edit` | Can add widgets to and change the layout of the project dashboard. | -|Manage Permissions
      `DashboardsPrivileges, ManagePermissions` | Can manage permissions for the project dashboard. | +|Delete dashboard
      `DashboardsPrivileges, Delete` | Can delete the project dashboard. | +|Edit dashboard
      `DashboardsPrivileges, Edit` | Can add widgets to and change the layout of the project dashboard. | +|Manage Permissions
      `DashboardsPrivileges, ManagePermissions` | Can manage permissions for the project dashboard. | ::: moniker-end ::: moniker range="< azure-devops" - Permissions for team dashboards can be set individually. The default permissions for a team can be set for a project. You manage the security of dashboards from the web portal. + Permissions for team dashboards can be set individually. The default permissions for a team can be set for a project. Manage the security of dashboards from the web portal. ::: moniker-end ### Team dashboard default permissions @@ -1858,13 +1684,13 @@ Permissions for team and project dashboards can be set individually. The default > [!div class="mx-imgBorder"] > ![Screenshot of Team dashboard permissions dialog.](../../report/dashboards/media/set-permissions/project-setting-permissions.png) - By default, team administrators are granted all permissions for their team dashboards, including managing default and individual dashboard permissions. +By default, team administrators are granted all permissions for their team dashboards, including managing default and individual dashboard permissions. -|**Permission**
      `Namespace permission` | **Description** | +|**Permission**
      `Namespace permission` | **Description** | |-----------| ----------- | -|Create dashboards
      `DashboardsPrivileges, MaterializeDashboards` | Can create a team dashboard. | -|Delete dashboards
      `DashboardsPrivileges, Delete` | Can delete a team dashboard. | -|Edit dashboards
      `DashboardsPrivileges, Edit` | Can add widgets to and change the layout of a team dashboard. | +|Create dashboards
      `DashboardsPrivileges, Create` | Can create a team dashboard. | +|Delete dashboards
      `DashboardsPrivileges, Delete` | Can delete a team dashboard. | +|Edit dashboards
      `DashboardsPrivileges, Edit` | Can add widgets to and change the layout of a team dashboard. | ### Individual team dashboard permissions @@ -1873,44 +1699,36 @@ Permissions for team and project dashboards can be set individually. The default Team administrators can change the permissions for individual team dashboards by changing the following two permissions. -|**Permission**
      `Namespace permission` | **Description** | +|**Permission**
      `Namespace permission` | **Description** | |-----------| ----------- | -|Delete dashboard
      `DashboardsPrivileges, Delete` | Can delete the specific team dashboard. | -|Edit dashboard
      `DashboardsPrivileges, Edit` | Can add widgets to and change the layout of the specific team dashboard. | - +|Delete dashboard
      `DashboardsPrivileges, Delete` | Can delete the specific team dashboard. | +|Edit dashboard
      `DashboardsPrivileges, Edit` | Can add widgets to and change the layout of the specific team dashboard. | ## Pipeline or Build (object-level) -You manage pipeline permissions [for each pipeline defined in the web portal](../../pipelines/policies/set-permissions.md) or using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#build-permissions). Project Administrators are granted all pipeline permissions and Build Administrators are assigned most of these permissions. You can set pipeline permissions for all pipelines defined for a project or for each pipeline definition. +Manage pipeline permissions [for each pipeline defined in the web portal](../../pipelines/policies/permissions.md#pipeline-permissions) or using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#build-permissions). Project Administrators are granted all pipeline permissions and Build Administrators are assigned most of these permissions. You can set pipeline permissions for all pipelines defined for a project or for each pipeline definition. ::: moniker range="azure-devops" :::image type="content" source="media/permissions/pipeline-object-level-permissions-cloud.png" alt-text="Screenshot of pipeline object-level security dialog, cloud."::: -::: moniker-end +::: Moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" > [!div class="mx-imgBorder"] > ![Screenshot of Pipeline object-level permissions dialog.](media/permissions/edit-build-pipeline-object-level-permissions-s163.png) ::: moniker-end -::: moniker range="< azure-devops-2019" +Permissions in Build follow a hierarchical model. Defaults for all the permissions can be set at the project level and can be overridden on an individual build definition. -> [!div class="mx-imgBorder"] -> ![Screenshot of Build object-level permissions dialog, Azure DevOps Server 2019 and earlier on-premises versions.](media/permissions/build-permissions-vsts.png) - -::: moniker-end +To set the permissions at project level for all build definitions in a project, choose **Security** from the action bar on the main page of Builds hub. - Permissions in Build follow a hierarchical model. Defaults for all the permissions can be set at the project level and can be overridden on an individual build definition. +To set or override the permissions for a specific build definition, choose **Security** from the context menu of the build definition. - To set the permissions at project level for all build definitions in a project, choose **Security** from the action bar on the main page of Builds hub. - - To set or override the permissions for a specific build definition, choose **Security** from the context menu of the build definition. - - The following permissions are defined in Build. All of these can be set at both the levels. +You can define the following permissions in Build at both levels. :::row::: :::column span="2"::: @@ -1921,6 +1739,7 @@ You manage pipeline permissions [for each pipeline defined in the web portal](.. ### Description :::column-end::: :::row-end::: +--- :::row::: :::column span="2"::: @@ -1931,6 +1750,27 @@ You manage pipeline permissions [for each pipeline defined in the web portal](.. Can administer the build permissions for other users. :::column-end::: :::row-end::: +::: moniker range="azure-devops" +:::row::: + :::column span="2"::: + + Create build pipeline + `Build, CreateBuildPipeline` + :::column-end::: + :::column span="2"::: + Can create pipeline lines and edit those pipelines. + :::column-end::: +:::row-end::: +::: moniker-end +:::row::: + :::column span="2"::: + Create build pipeline + `Build, CreateBuildDefinition` + :::column-end::: + :::column span="2"::: + Can create pipelines. + :::column-end::: +:::row-end::: :::row::: :::column span="2"::: Delete build definition @@ -1946,7 +1786,7 @@ You manage pipeline permissions [for each pipeline defined in the web portal](.. `Build, DeleteBuilds` :::column-end::: :::column span="2"::: - Can delete a completed build. Builds that are deleted are [retained](../../pipelines/policies/retention.md) in the **Deleted** tab for a period of time before they are destroyed. + Can delete a completed build. Builds that are deleted are [retained](../../pipelines/policies/retention.md) in the **Deleted** tab for some time before they're destroyed. :::column-end::: :::row-end::: :::row::: @@ -1961,23 +1801,23 @@ You manage pipeline permissions [for each pipeline defined in the web portal](.. :::row::: :::column span="2"::: - Edit build pipeline
      Edit build definition + Edit build pipeline
      Edit build definition `Build, EditBuildDefinition` :::column-end::: :::column span="2"::: - - **Edit build pipeline** Can save any changes to a build pipeline, including configuration variables, triggers, repositories, and retention policy. Available with Azure DevOps Services, Azure DevOps Server 2019 1.1, and later versions. Replaces Edit build definition. - **Edit build definition** Can create and modify build definitions for this project. + + **Edit build pipeline**: Can save any changes to a build pipeline, including configuration variables, triggers, repositories, and retention policy. Available with Azure DevOps Services, Azure DevOps Server 2019 1.1, and later versions. Replaces Edit build definition. Cannot create new pipelines. + **Edit build definition*:* Can create and modify build definitions for this project. :::column-end::: :::row-end::: :::row::: :::column span="4"::: > [!NOTE] - > You turn **Inheritance Off** for a build definition when you want to control permissions for specific build definitions. + > To control permissions for specific build definitions, turn off **inheritance**. > - > When **inheritance is On**, the build definition respects the build permissions defined at the project level or a group or user. For example, a custom Build Managers group has permissions set to manually queue a build for project Fabrikam. Any build definition with inheritance On for project Fabrikam would allow a member of the Build Managers group the ability to manually queue a build. + > When inheritance is turned _on_, the build definition respects the build permissions defined at the project level or a group or user. For example, a custom Build Managers group has permissions set to manually queue a build for project Fabrikam. Any build definition with inheritance for project Fabrikam allows a member of the Build Managers group to manually queue a build. > - > However, by turning **Inheritance Off** for project Fabrikam, you can set permissions that only allow Project Administrators to manually queue a build for a specific build definition. This would then allow me to set permissions for that build definition specifically. + > When inheritance is turned _off_, you can set permissions so only Project Administrators can manually queue a build for a specific build definition. :::column-end::: :::row-end::: :::row::: @@ -2013,16 +1853,10 @@ You manage pipeline permissions [for each pipeline defined in the web portal](.. `Build, OverrideBuildCheckInValidation` :::column-end::: :::column span="2"::: - Can commit a TFVC change set that affects a gated build definition + Can commit a TFVC changeset that affects a gated build definition without triggering the system to shelve and build their changes first. :::column-end::: :::row-end::: -:::row::: - :::column span="4"::: - > [!NOTE] - > > Assign the** Override check-in validation by build** permission only to service accounts for build services and to build administrators who are responsible for the quality of the code. Applies to [TFVC gated check-in builds](../../pipelines/build/triggers.md). This does not apply to PR builds. For more information, see [Check in to a folder that is controlled by a gated check-in build process](../../repos/tfvc/check-folder-controlled-by-gated-check-build-process.md). - :::column-end::: -:::row-end::: :::row::: :::column span="2"::: Queue builds @@ -2033,13 +1867,24 @@ You manage pipeline permissions [for each pipeline defined in the web portal](.. They can also stop the builds that they have queued. :::column-end::: :::row-end::: +::: moniker range="azure-devops" +:::row::: + :::column span="2"::: + Edit queue build configuration + `Build, EditPipelineQueueConfigurationPermission` + :::column-end::: + :::column span="2"::: + Can specify values for free-text parameters (e.g., of type `object` or `array`) and pipeline variables when queueing new builds. + :::column-end::: +:::row-end::: +::: moniker-end :::row::: :::column span="2"::: Retain indefinitely `Build, RetainIndefinitely` :::column-end::: :::column span="2"::: - Can toggle the retain indefinitely flag on a build. This feature marks a build so that the system won't automatically delete it based on any applicable retention policy. + Can toggle the retain flag on a build to indefinitely. This feature marks a build so that the system doesn't automatically delete it based on any applicable retention policy. :::column-end::: :::row-end::: :::row::: @@ -2067,7 +1912,7 @@ You manage pipeline permissions [for each pipeline defined in the web portal](.. `Build, ViewBuildDefinition` :::column-end::: :::column span="2"::: - Can view the build definitions that have been created for the project. + Can view the build definitions created for the project. :::column-end::: :::row-end::: :::row::: @@ -2080,12 +1925,11 @@ You manage pipeline permissions [for each pipeline defined in the web portal](.. :::column-end::: :::row-end::: - - - - - - +> [!NOTE] +> - Turn **Inheritance Off** for a build definition when you want to control permissions for specific build definitions. +> - When **inheritance is On**, the build definition respects the build permissions defined at the project level or a group or user. For example, a custom Build Managers group has permissions set to manually queue a build for project Fabrikam. Any build definition with inheritance On for project Fabrikam would allow a member of the Build Managers group the ability to manually queue a build. +> - However, by turning **Inheritance Off** for project Fabrikam, you can set permissions that only allow Project Administrators to manually queue a build for a specific build definition. This would then allow me to set permissions for that build definition specifically. +> - Assign the **Override check-in validation by build** permission only to service accounts for build services and to build administrators who are responsible for the quality of the code. Applies to [TFVC gated check-in builds](../../pipelines/build/triggers.md). This doesn't apply to PR builds. For more information, see [Check in to a folder that is controlled by a gated check-in build process](../../repos/tfvc/check-folder-controlled-by-gated-check-build-process.md). ## Git repository (object-level) @@ -2105,20 +1949,12 @@ You manage pipeline permissions [for each pipeline defined in the web portal](.. Rename Repository --> - You manage the security of each [Git repository](../../repos/git/set-git-repository-permissions.md) or [branch](../../repos/git/branch-permissions.md) from the web portal, the [TF command line tool](../../repos/tfvc/git-permission-command.md), or using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#git-repo-permissions). Project Administrators are granted most of these permissions (which appear only for a project that's been configured with a Git repository). You can manage these permissions for all Git repositories, or for a specific Git repo. - +Manage the security of each [Git repository](../../repos/git/set-git-repository-permissions.md) or [branch](../../repos/git/branch-permissions.md) from the web portal, the [TF command line tool](../../repos/tfvc/git-permission-command.md), or using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#git-repo-permissions). Project Administrators are granted most of these permissions (which appear only for a project that configured with a Git repository). You can manage these permissions for all Git repositories, or for a specific Git repo. ::: moniker range="azure-devops" > [!div class="mx-imgBorder"] -> ![Git repository permissions dialog](media/permissions/git-repo-permissions-vsts.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -> [!div class="mx-imgBorder"] -> ![Git repository permissions dialog, TFS](media/permissions/git-repo-permissions-tfs.png) +> ![Screenshot of Git repository permissions dialog.](media/permissions/git-repo-permissions-vsts.png) ::: moniker-end @@ -2127,7 +1963,6 @@ You manage pipeline permissions [for each pipeline defined in the web portal](.. To manage Git repo and branch permissions, see [Set branch permissions](../../repos/git/branch-permissions.md). - :::row::: :::column span="2"::: ### Permission (UI) @@ -2137,6 +1972,7 @@ To manage Git repo and branch permissions, see [Set branch permissions](../../re ### Description :::column-end::: :::row-end::: +--- :::row::: :::column span="2"::: Bypass policies when completing pull requests @@ -2145,7 +1981,7 @@ To manage Git repo and branch permissions, see [Set branch permissions](../../re :::column span="2"::: Can opt in to override branch policies by checking **Override branch policies and enable merge** when completing a PR. > [!NOTE] - > Bypass policies when completing pull requests and **Bypass policies when pushing** replace **Exempt From Policy Enforcement**. Applies to Azure DevOps Server 2019 and later versions. + > Bypass policies when completing pull requests and **Bypass policies when pushing** replace **Exempt From Policy Enforcement**. :::column-end::: :::row-end::: :::row::: @@ -2155,7 +1991,7 @@ To manage Git repo and branch permissions, see [Set branch permissions](../../re :::column span="2"::: Can push to a branch that has branch policies enabled. When a user with this permission makes a push that would override branch policy, the push automatically bypasses branch policy with no opt-in step or warning. > [!NOTE] - > Bypass policies when completing pull requests and **Bypass policies when pushing** replace **Exempt From Policy Enforcement**. Applies to Azure DevOps Server 2019 and later versions. + > Bypass policies when completing pull requests and **Bypass policies when pushing** replace **Exempt From Policy Enforcement**. :::column-end::: :::row-end::: :::row::: @@ -2165,9 +2001,9 @@ To manage Git repo and branch permissions, see [Set branch permissions](../../re :::column-end::: :::column span="2"::: - At the repository level, can push their changes to existing branches in the repository and can complete pull requests. Users who lack this permission but who have the **Create branch** permission may push changes to new branches. Does not override restrictions in place from [branch policies](../../repos/git/branch-policies.md). + At the repository level, can push their changes to existing branches in the repository and can complete pull requests. Users who lack this permission but who have the **Create branch** permission might push changes to new branches. Doesn't override restrictions in place from [branch policies](../../repos/git/branch-policies.md). - At the branch level, can push their changes to the branch and lock the branch. Locking a branch blocks any new commits from being added to the branch by others and prevents other users from changing the existing commit history. + At the branch level, can push their changes to the branch and lock the branch. Locking a branch blocks any new commits from others and prevents other users from changing the existing commit history. :::column-end::: :::row-end::: :::row::: @@ -2186,10 +2022,10 @@ To manage Git repo and branch permissions, see [Set branch permissions](../../re :::column-end::: :::column span="2"::: Can create and publish branches in the repository. - Lack of this permission does not limit users from creating branches in their local repository; it merely prevents them from publishing local branches to the server. + Lack of this permission doesn't limit users from creating branches in their local repository; it merely prevents them from publishing local branches to the server. > [!NOTE] - > When a user creates a new branch on the server, they have Contribute, Edit Policies, Force Push, Manage Permissions, and Remove Others' Locks permissions for that branch by default. This means that users can add new commits to the repo via their branch. + > When you create a new branch on the server, you have Contribute, Edit Policies, Force Push, Manage Permissions, and Remove Others' Locks permissions for that branch by default. This means that you can add new commits to the repo via your branch. :::column-end::: :::row-end::: :::row::: @@ -2300,12 +2136,12 @@ To manage Git repo and branch permissions, see [Set branch permissions](../../re ## TFVC (object-level) -You manage the security of each TFVC branch from the [web portal](../../repos/tfvc/set-tfvc-repository-permissions.md) or using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#tfvc-permissions). Project Administrators are granted most of these permissions which appear only for a project that's been configured to use Team Foundation Version Control as a source control system. In version control permissions, explicit deny takes precedence over administrator group permissions. +Manage the security of each TFVC branch from the [web portal](../../repos/tfvc/set-tfvc-repository-permissions.md) or using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#tfvc-permissions). Project Administrators are granted most of these permissions, which appear only for a project that was configured to use Team Foundation Version Control as a source control system. In version control permissions, explicit deny takes precedence over administrator group permissions. These permissions appear only for a project setup to use Team Foundation Version Control as the source control system. > [!div class="mx-imgBorder"] -> ![TFVC permissions dialog](media/permissions/tfvc-repo-permissions-vsts.png) +> ![Screenshot of TFVC permissions dialog.](media/permissions/tfvc-repo-permissions-vsts.png) In version control permissions, explicit **Deny** takes precedence over administrator group permissions. @@ -2318,6 +2154,7 @@ In version control permissions, explicit **Deny** takes precedence over administ ### Description :::column-end::: :::row-end::: +--- :::row::: :::column span="2"::: Administer labels @@ -2333,10 +2170,9 @@ In version control permissions, explicit **Deny** takes precedence over administ `VersionControlItems, Checkin` :::column-end::: :::column span="2"::: - Can check in items and revise any committed change set comments. - Pending changes are committed at check-in. - > [!NOTE] - > Consider adding these permissions to any manually added users or groups that contributes to the development of the project; any users who should be able to check in and check out changes, make a pending change to items in a folder, or revise any committed change set comments. + Can check in items and revise any committed changeset comments. + Pending changes are committed at check-in.* + :::column-end::: :::row-end::: :::row::: @@ -2347,7 +2183,6 @@ In version control permissions, explicit **Deny** takes precedence over administ :::column span="2"::: Can check in changes that were made by other users. Pending changes are committed at check-in. - :::column-end::: :::row-end::: :::row::: @@ -2360,14 +2195,8 @@ In version control permissions, explicit **Deny** takes precedence over administ Examples of pending changes include adding, editing, renaming, deleting, undeleting, branching, and merging a file. Pending changes must be checked in, - so users will also need the Check-in permission - to share their changes with the team. - :::column-end::: -:::row-end::: -:::row::: - :::column span="4"::: - > [!NOTE] - > Consider adding these permissions to any manually added users or groups that contributes to the development of the project; any users who should be able to check in and check out changes, make a pending change to items in a folder, or revise any committed change set comments. + so users also must have the Check-in permission + to share their changes with the team.* :::column-end::: :::row-end::: :::row::: @@ -2399,8 +2228,8 @@ In version control permissions, explicit **Deny** takes precedence over administ edit its properties, reparent it, and convert it to a folder. Users who have this permission can branch this branch only if they also have the Merge permission for the target path. - Users cannot create branches from a branch - for which they do not have the Manage Branch permission. + Users can't create branches from a branch + for which they don't have the Manage Branch permission. :::column-end::: :::row-end::: :::row::: @@ -2409,9 +2238,7 @@ In version control permissions, explicit **Deny** takes precedence over administ `VersionControlItems, AdminProjectRights` :::column-end::: :::column span="2"::: - Can manage other users' permissions for folders and files in version control. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that contributes to the development of the project and that must be able to create private branches, unless the project is under more restrictive development practices. + Can manage other users' permissions for folders and files in version control.* :::column-end::: :::row-end::: :::row::: @@ -2421,9 +2248,7 @@ In version control permissions, explicit **Deny** takes precedence over administ `VersionControlItems, AdminProjectRights` :::column-end::: :::column span="2"::: - Can merge changes into this path. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that contribute to the development of the project and that must be able to merge source files, unless the project is under more restrictive development practices. + Can merge changes into this path.* :::column-end::: :::row-end::: :::row::: @@ -2435,7 +2260,7 @@ In version control permissions, explicit **Deny** takes precedence over administ Can read the contents of a file or folder. If a user has Read permissions for a folder, the user can see the contents of the folder and the properties of the files in it, - even if the user does not have permission to open the files. + even if the user doesn't have permission to open the files. :::column-end::: :::row-end::: :::row::: @@ -2444,9 +2269,7 @@ In version control permissions, explicit **Deny** takes precedence over administ `VersionControlItems, ReviseOther` :::column-end::: :::column span="2"::: - Can edit the comments on checked-in files, even if another user checked in the file. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that are responsible for supervising or monitoring the project and that might or must change the comments on checked-in files, even if another user checked in the file. + Can edit the comments on checked-in files, even if another user checked in the file.* :::column-end::: :::row-end::: :::row::: @@ -2455,9 +2278,7 @@ In version control permissions, explicit **Deny** takes precedence over administ `VersionControlItems, UndoOther` :::column-end::: :::column span="2"::: - Can undo a pending change made by another user. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that are responsible for supervising or monitoring the project and that might or must change the comments on checked-in files, even if another user checked in the file. + Can undo a pending change made by another user.* :::column-end::: :::row-end::: :::row::: @@ -2466,33 +2287,27 @@ In version control permissions, explicit **Deny** takes precedence over administ `VersionControlItems, UnlockOther` :::column-end::: :::column span="2"::: - Can unlock files locked by other users. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that are responsible for supervising or monitoring the project and that might or must change the comments on checked-in files, even if another user checked in the file. + Can unlock files locked by other users.* :::column-end::: :::row-end::: - - - +`*` Consider adding this permission to any manually added users or groups that are responsible for supervising or monitoring the project and that might or must change the comments on checked-in files, even if another user checked in the file. ## Area path (object-level) - Area path permissions grant or restrict access to branches of the area hierarchy - and to the work items in those areas. - You manage the security of each area path from the [web portal](../../organizations/security/set-permissions-access-work-tracking.md) or using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#area). Area permissions grant or restrict access to create and manage area paths as well as create and modify work items defined under area paths. +Area path permissions manage access to branches of the area hierarchy and to the work items in those areas. Manage the security of each area path from the [web portal](../../organizations/security/set-permissions-access-work-tracking.md) or using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#area). Area permissions manage access to create and manage area paths as well as create and modify work items defined under area paths. - Members of the Project Administrators group are automatically granted permissions to manage area paths for a project. Consider granting team administrators or team leads permissions to create, edit, or delete area nodes. +Members of the Project Administrators group are automatically granted permissions to manage area paths for a project. Consider granting team administrators or team leads permissions to create, edit, or delete area nodes. > [!NOTE] -> Multiple teams may contribute to a project. +> Multiple teams can contribute to a project. > When that's the case, you can set up teams that are associated with an area. > Permissions for the team's work items are assigned by assigning permissions to the area. > There are other [team settings](../settings/manage-teams.md) > that configure the team's agile planning tools. > [!div class="mx-imgBorder"] -> ![Area path permissions dialog](media/permissions/area-path-permissions-vsts.png) +> ![Screenshot of area path permissions dialog.](media/permissions/area-path-permissions-vsts.png) :::row::: :::column span="1"::: @@ -2503,6 +2318,7 @@ In version control permissions, explicit **Deny** takes precedence over administ ### Description :::column-end::: :::row-end::: +--- :::row::: :::column span="1"::: Create child nodes @@ -2511,7 +2327,9 @@ In version control permissions, explicit **Deny** takes precedence over administ :::column span="2"::: Can create area nodes. Users who have both this permission and the **Edit this node** permission - can move or reorder any child area nodes. Consider adding this permission to any manually added users or groups that may need to delete, add, or rename area nodes. + can move or reorder any child area nodes. + + Consider adding this permission to any manually added users or groups that might need to delete, add, or rename area nodes. :::column-end::: :::row-end::: :::row::: @@ -2524,8 +2342,8 @@ In version control permissions, explicit **Deny** takes precedence over administ Users who have both this permission and the **Edit this node** permission for another node can delete area nodes and reclassify existing work items from the deleted node. If the deleted node has child nodes, those nodes are also deleted. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that may need to delete, add, or rename area nodes. + + Consider adding this permission to any manually added users or groups that might need to delete, add, or rename area nodes. :::column-end::: :::row-end::: :::row::: @@ -2535,8 +2353,8 @@ In version control permissions, explicit **Deny** takes precedence over administ :::column-end::: :::column span="2"::: Can set permissions for this node and rename area nodes. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that may need to delete, add, or rename area nodes. + + Consider adding this permission to any manually added users or groups that might need to delete, add, or rename area nodes. :::column-end::: :::row-end::: :::row::: @@ -2546,8 +2364,8 @@ In version control permissions, explicit **Deny** takes precedence over administ :::column-end::: :::column span="2"::: Can edit work items in this area node. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that may need to edit work items under the area node. + + Consider adding this permission to any manually added users or groups that might need to edit work items under the area node. :::column-end::: :::row-end::: :::row::: @@ -2557,8 +2375,8 @@ In version control permissions, explicit **Deny** takes precedence over administ :::column-end::: :::column span="2"::: Can modify test plan properties such as build and test settings. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that may need to manage test plans or test suites under this area node. + + Consider adding this permission to any manually added users or groups that might need to manage test plans or test suites under this area node. :::column-end::: :::row-end::: :::row::: @@ -2571,8 +2389,8 @@ In version control permissions, explicit **Deny** takes precedence over administ add, and remove test cases from test suites, change test configurations associated with test suites, and modify suite hierarchy (move a test suite). - > [!NOTE] - > Consider adding this permission to any manually added users or groups that may need to manage test plans or test suites under this area node. + + Consider adding this permission to any manually added users or groups that might need to manage test plans or test suites under this area node. :::column-end::: :::row-end::: :::row::: @@ -2586,28 +2404,28 @@ In version control permissions, explicit **Deny** takes precedence over administ :::row::: :::column span="1"::: View work items in this node + `CSS, GENERIC_READ` :::column-end::: :::column span="2"::: Can view, but not change, work items in this area node. > [!NOTE] - > If you set the **View work items in this node** to **Deny**, the user will not be able to see any work items in this area node. A **Deny** will override any implicit allow, even for users that are members of an administrative groups. + > If you set the **View work items in this node** to **Deny**, the user can't see any work items in this area node. A **Deny** overrides any implicit allow, even for users that are members of an administrative groups. :::column-end::: :::row-end::: -## Iteration Path (object-level) +## Iteration path (object-level) - Iteration path permissions grant or restrict access to create and manage iteration paths, also referred to as sprints. +Iteration path permissions manage access to create and manage iteration paths, also referred to as sprints. - You manage the security of each iteration path from the [web portal](../../organizations/security/set-permissions-access-work-tracking.md) or using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#iteration-permissions). +Manage the security of each iteration path from the [web portal](../../organizations/security/set-permissions-access-work-tracking.md) or using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#iteration-permissions). - Members of the Project Administrators group are automatically granted these permissions for each iteration defined for a project. Consider granting team administrators, scrum masters, or team leads permissions to create, edit, or delete iteration nodes. +Members of the Project Administrators group are automatically granted these permissions for each iteration defined for a project. Consider granting team administrators, scrum masters, or team leads permissions to create, edit, or delete iteration nodes. > [!div class="mx-imgBorder"] -> ![Iteration Path permissions dialog](media/permissions/iteration-path-permissions-vsts.png) - +> ![Screenshot of Iteration Path permissions dialog.](media/permissions/iteration-path-permissions-vsts.png) :::row::: :::column span="1"::: @@ -2618,6 +2436,7 @@ In version control permissions, explicit **Deny** takes precedence over administ ### Description :::column-end::: :::row-end::: +--- :::row::: :::column span="1"::: Create child nodes @@ -2627,8 +2446,8 @@ In version control permissions, explicit **Deny** takes precedence over administ Can create iteration nodes. Users who have both this permission and the **Edit this node** permission can move or reorder any child iteration nodes. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that might need to delete, add, or rename iteration nodes. + + Consider adding this permission to any manually added users or groups that might need to delete, add, or rename iteration nodes. :::column-end::: :::row-end::: :::row::: @@ -2640,8 +2459,8 @@ In version control permissions, explicit **Deny** takes precedence over administ Users who have both this permission and the **Edit this node** permission for another node can delete iteration nodes and reclassify existing work items from the deleted node. If the deleted node has child nodes, those nodes are also deleted. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that might need to delete, add, or rename iteration nodes. + + Consider adding this permission to any manually added users or groups that might need to delete, add, or rename iteration nodes. :::column-end::: :::row-end::: :::row::: @@ -2651,8 +2470,8 @@ In version control permissions, explicit **Deny** takes precedence over administ :::column-end::: :::column span="2"::: Can set permissions for this node and rename iteration nodes. - > [!NOTE] - > Consider adding this permission to any manually added users or groups that might need to delete, add, or rename iteration nodes. + + Consider adding this permission to any manually added users or groups that might need to delete, add, or rename iteration nodes. :::column-end::: :::row-end::: :::row::: @@ -2667,21 +2486,20 @@ In version control permissions, explicit **Deny** takes precedence over administ :::column-end::: :::row-end::: - + ## Work item query and query folder (object-level) - You manage query and query folder permissions through the [web portal](../../boards/queries/set-query-permissions.md). Project Administrators are granted all of these permissions. Contributors are granted Read permissions only. Consider granting the Contribute permissions to users or groups that require the ability to create and share work item queries for the project. +Manage query and query folder permissions through the [web portal](../../boards/queries/set-query-permissions.md). Project Administrators are granted all of these permissions. Contributors are granted Read permissions only. > [!div class="mx-imgBorder"] -> ![Query folder permissions dialog](media/permissions/query-folder-permissions-vsts.png) +> ![Screenshot of Query folder permissions dialog.](media/permissions/query-folder-permissions-vsts.png) - Consider granting the **Contribute** permissions to users or groups that require the ability to create and share work item queries for the project. To learn more, see [Set permissions on queries](../../boards/queries/set-query-permissions.md). +Consider granting the **Contribute** permissions to users or groups that require the ability to create and share work item queries for the project. For more information, see [Set permissions on queries](../../boards/queries/set-query-permissions.md). > [!NOTE] > To create query charts [you need Basic access](change-access-levels.md). - :::row::: :::column span="2"::: ### Permission (UI) @@ -2691,6 +2509,7 @@ In version control permissions, explicit **Deny** takes precedence over administ ### Description :::column-end::: :::row-end::: +--- :::row::: :::column span="2"::: Contribute @@ -2725,17 +2544,15 @@ In version control permissions, explicit **Deny** takes precedence over administ :::column-end::: :::column span="2"::: Can view and use the query or the queries in a folder, - but cannot modify the query or query folder contents. + but can't modify the query or query folder contents. :::column-end::: :::row-end::: - - + ## Delivery Plans (object-level) -You manage plan permissions through the [web portal](set-permissions-access-work-tracking.md#plan-permissions). You manage permissions for each plan through its Security dialog. Project Administrators are granted all permissions to create, edit, and manage plans. Valid users are granted View (read-only) permissions. - +Manage plan permissions through the [web portal](set-permissions-access-work-tracking.md#plan-permissions). Manage permissions for each plan through its Security dialog. Project Administrators are granted all permissions to create, edit, and manage plans. Valid users are granted View (read-only) permissions. :::row::: :::column span="1"::: @@ -2746,6 +2563,7 @@ You manage plan permissions through the [web portal](set-permissions-access-work ### Description :::column-end::: :::row-end::: +--- :::row::: :::column span="1"::: Delete @@ -2779,17 +2597,13 @@ You manage plan permissions through the [web portal](set-permissions-access-work `Plan, View` :::column-end::: :::column span="2"::: - Can view the lists of plans, open, and interact with a plan, but cannot modify the plan configuration or settings. + Can view the lists of plans, open, and interact with a plan, but can't modify the plan configuration or settings. :::column-end::: :::row-end::: - - -::: moniker range=">= azure-devops-2019" - ## Process (object-level) -You can manage the permissions for each inherited process that you create through the [web portal](set-permissions-access-work-tracking.md#process-permissions). You manage permissions for each process through its Security dialog. Project Collection Administrators are granted all permissions to create, edit, and manage processes. Valid users are granted View (read-only) permissions. +You can manage the permissions for each inherited process that you create through the [web portal](set-permissions-access-work-tracking.md#process-permissions). Manage permissions for each process through its Security dialog. Project Collection Administrators are granted all permissions to create, edit, and manage processes. Valid users are granted View (read-only) permissions. :::row::: :::column span="2"::: @@ -2800,6 +2614,7 @@ You can manage the permissions for each inherited process that you create throug ### Description :::column-end::: :::row-end::: +--- :::row::: :::column span="2"::: Administer process permissions @@ -2828,11 +2643,6 @@ You can manage the permissions for each inherited process that you create throug :::column-end::: :::row-end::: -::: moniker-end - - - - ## Work item tags ::: moniker range="azure-devops" @@ -2841,15 +2651,13 @@ You can manage tagging permissions using [az devops security permission](manage- ::: moniker range="< azure-devops" You can manage tagging permissions using the [TFSSecurity command-line tool](/azure/devops/server/command-line/tfssecurity-cmd#tagging-permissions). Contributors can add tags to work items and use them to quickly filter a backlog, board, or query results view. ::: moniker-end - - :::row::: :::column span="1"::: ### Permission (UI) `Namespace permission` :::column-end::: :::column span="2"::: - ### Description + ### Description :::column-end::: :::row-end::: --- @@ -2859,14 +2667,11 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az `Tagging, Create` :::column-end::: :::column span="2"::: + [Can create new tags and apply them to work items.](../../boards/queries/add-tags-to-work-items.md) Users without this permission can only select from the existing set of tags for the project. - :::column-end::: -:::row-end::: -:::row::: - :::column span="4"::: - > [!NOTE] - > By default, Contributors are assigned the **Create tag definition** permission. Although the **Create tag definition** permission appears in the security settings at the project-level, tagging permissions are actually collection-level permissions that are scoped at the project level when they appear in the user interface. To scope tagging permissions to a single project when usinga command-line tool, you must provide the GUID for the project as part of the command syntax. Otherwise, your change will apply to the entire collection. Keep this in mind when changing or setting these permissions. + + By default, Contributors are assigned the **Create tag definition** permission. Although the **Create tag definition** permission appears in the security settings at the project-level, tagging permissions are actually collection-level permissions that are scoped at the project level when they appear in the user interface. To scope tagging permissions to a single project when you're using a command-line tool, you must provide the GUID for the project as part of the command syntax. Otherwise, your change applies to the entire collection. Keep this in mind when changing or setting these permissions. :::column-end::: :::row-end::: :::row::: @@ -2876,12 +2681,8 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az :::column-end::: :::column span="2"::: Can remove a tag from the list of available tags for that project. - :::column-end::: -:::row-end::: -:::row::: - :::column span="4"::: - > [!NOTE] - > This permission doesn't appear in the UI. It can only be set by using a command-line tool. There is also no UI to explicitly delete a tag. Instead, when a tag has not been in use for 3 days, the system automatically deletes it. + + This permission doesn't appear in the UI. You can only set it by using a command-line tool. There's also no UI to explicitly delete a tag. Instead, when a tag has not been in use for three days, the system automatically deletes it. :::column-end::: :::row-end::: :::row::: @@ -2891,15 +2692,10 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az :::column-end::: :::column span="2"::: Can view a list of tags available for the work item within the project. - Users without this permission will not have a list of available tags + Users without this permission don't have a list of available tags from which to choose in the work item form or in the query editor. - :::column-end::: -:::row-end::: -:::row::: - :::column span="4"::: - > [!NOTE] - > This permission doesn't appear in the UI. It can only be set by using a command-line tool. - > The **View project-level information** implicitly allows users to view existing tags. + + This permission doesn't appear in the UI. It can only be set by using a command-line tool. The **View project-level information** implicitly allows users to view existing tags. :::column-end::: :::row-end::: :::row::: @@ -2909,44 +2705,26 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az :::column-end::: :::column span="2"::: Can rename a tag by using the REST API. - > [!NOTE] - > This permission doesn't appear in the UI. It can only be set by using a command-line tool. + + This permission doesn't appear in the UI. It can only be set by using a command-line tool. :::column-end::: :::row-end::: - - - - - - + + ## Release (object-level) - You manage permissions [for each release defined in the web portal](../../pipelines/policies/set-permissions.md). Project Administrators and Release Administrators are granted all release management permissions. These permissions can be granted or denied in a hierarchical model at the project level, for a specific release pipeline, or for a specific environment in a release pipeline. Within this hierarchy, permissions can be inherited from the parent or overridden. - +Manage permissions [for each release defined in the web portal](../../pipelines/policies/permissions.md#pipeline-permissions). Project Administrators and Release Administrators are granted all release management permissions. These permissions work in a hierarchical model at the project level, for a specific release pipeline, or for a specific environment in a release pipeline. Within this hierarchy, permissions can be inherited from the parent or overridden. -:::image type="content" source="media/permissions/release-object-level-permissions.png" alt-text="Releases object-level permissions."::: +:::image type="content" source="media/permissions/release-object-level-permissions.png" alt-text="Screenshot showing Releases object-level permissions."::: > [!NOTE] -> The project-level Release Administrator's group is created at the same time the first release pipeline is defined. +> The project-level Release Administrator's group gets created when you define your first release pipeline. - In addition, you can assign approvers to specific steps within a release pipeline to ensure that the applications being deployed meet quality standards. +In addition, you can assign approvers to specific steps within a release pipeline to ensure that the applications being deployed meet quality standards. - The following permissions are defined in Release Management. The scope column explains whether the permission can be set at the project, release pipeline, or environment level. +The following permissions are defined in Release Management. The scope column explains whether the permission can be set at the project, release pipeline, or environment level. :::row::: :::column span="1"::: @@ -2959,6 +2737,7 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az **Scopes** :::column-end::: :::row-end::: +--- :::row::: :::column span="1"::: Administer release permissions @@ -2995,7 +2774,7 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az :::column-end::: :::column span="2"::: - Can delete release pipeline(s). + Can delete release pipelines. :::column-end::: :::column span="1"::: @@ -3010,7 +2789,7 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az :::column-end::: :::column span="2"::: - Can delete environment(s) in release pipeline(s). + Can delete environments in release pipelines. :::column-end::: :::column span="1"::: @@ -3039,14 +2818,10 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az Edit release pipeline :::column-end::: :::column span="2"::: - Can add and edit a release pipeline, including configuration variables, triggers, artifacts, and retention policy as well as configuration within an environment of the release pipeline. To make changes to a specific environment in a release pipeline, the user also needs **Edit release environment** permission. - :::column-end::: :::column span="1"::: - Project, Release pipeline - :::column-end::: :::row-end::: :::row::: @@ -3054,29 +2829,21 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az Edit release environment :::column-end::: :::column span="2"::: - - Can edit environment(s) in release pipeline(s). To save the changes to the release pipeline, the user also needs **Edit release pipeline** permission. This permission also controls whether a user can edit the configuration inside the environment of a specific release instance. The user also needs **Manage releases** permission to save the modified release. - + Can edit environments in release pipelines. To save the changes to the release pipeline, the user also needs **Edit release pipeline** permission. This permission also controls whether a user can edit the configuration inside the environment of a specific release instance. The user also needs **Manage releases** permission to save the modified release. :::column-end::: :::column span="1"::: - Project, Release pipeline, Environment - :::column-end::: :::row-end::: :::row::: :::column span="1"::: Manage deployments :::column-end::: - :::column span="2"::: - + :::column span="2"::: Can initiate a direct deployment of a release to an environment. This permission is only for direct deployments that are manually initiated by selecting the **Deploy** action in a release. If the condition on an environment is set to any type of automatic deployment, the system automatically initiates deployment without checking the permission of the user that created the release. - :::column-end::: :::column span="1"::: - Project, Release pipeline, Environment - :::column-end::: :::row-end::: :::row::: @@ -3084,14 +2851,10 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az Manage release approvers :::column-end::: :::column span="2"::: - - Can add or edit approvers for environment(s) in release pipeline(s). This permission also controls whether a user can edit the approvers inside the environment of a specific release instance. - + Can add or edit approvers for environments in release pipelines. This permission also controls whether a user can edit the approvers inside the environment of a specific release instance. :::column-end::: :::column span="1"::: - Project, Release pipeline, Environment - :::column-end::: :::row-end::: :::row::: @@ -3099,14 +2862,10 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az Manage releases :::column-end::: :::column span="2"::: - Can edit a release configuration, such as stages, approvers, and variables. To edit the configuration of a specific environment in a release instance, the user also needs **Edit release environment** permission. - :::column-end::: :::column span="1"::: - Project, Release pipeline - :::column-end::: :::row-end::: :::row::: @@ -3114,14 +2873,10 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az View release pipeline :::column-end::: :::column span="2"::: - - Can view release pipeline(s). - + Can view release pipelines. :::column-end::: :::column span="1"::: - Project, Release pipeline - :::column-end::: :::row-end::: :::row::: @@ -3129,20 +2884,14 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az View releases :::column-end::: :::column span="2"::: - - Can view releases belonging to release pipeline(s). - + Can view releases belonging to release pipelines. :::column-end::: :::column span="1"::: - Project, Release pipeline - :::column-end::: :::row-end::: - - Default values for all of these permissions are set for team - project collections and project groups. For example, +Default values for all of these permissions are set for team project collections and project groups. For example, **Project Collection Administrators**, **Project Administrators**, and **Release Administrators** are given all of the above permissions by default. **Contributors** are given all permissions except @@ -3150,35 +2899,28 @@ You can manage tagging permissions using the [TFSSecurity command-line tool](/az are denied all permissions except **View release pipeline** and **View releases**. - + ## Task group (Build and Release) permissions - You manage permissions [for task groups from the **Build and Release** hub](../../pipelines/policies/set-permissions.md) of the web portal. Project, Build, and Release Administrators are granted all permissions. Task group permissions follow a hierarchical model. Defaults for all the permissions can be set at the project - level and can be overridden on an individual task group definition. +Manage permissions [for task groups from the **Build and Release** hub](../../pipelines/policies/permissions.md#pipeline-permissions) of the web portal. Project, Build, and Release Administrators are granted all permissions. Task group permissions follow a hierarchical model. Defaults for all the permissions can be set at the project level and can be overridden on an individual task group definition. - You use task groups to encapsulate a sequence of tasks already defined in a build or a release definition into a single reusable task. You [define and manage task groups](../../pipelines/library/task-groups.md) in the **Task groups** tab of the **Build and Release** hub. - -> [!div class="tdCol2BreakAll"] +Use task groups to encapsulate a sequence of tasks already defined in a build or a release definition into a single reusable task. [Define and manage task groups](../../pipelines/library/task-groups.md) in the **Task groups** tab of the **Build and Release** hub. + > | Permission | Description | > |------------|-------------| > | **Administer task group permissions** | Can add and remove users or groups to task group security. | > | **Delete task group** | Can delete a task group. | > | **Edit task group** | Can create, modify, or delete a task group. | - - + ## Notifications or alerts -::: moniker range=">= azure-devops-2020" -There are no UI permissions associated with [managing email notifications or alerts](../../organizations/notifications/manage-your-personal-notifications.md). Instead, you can manage them using [az devops security permission](manage-tokens-namespaces.md) or [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd#tagging-permissions) command-line tools. -::: moniker-end -::: moniker range="< azure-devops-2020" +::: moniker range="=azure-devops-2020" There are no UI permissions associated with [managing email notifications or alerts](../../organizations/notifications/manage-your-personal-notifications.md). Instead, you can manage them using the [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd#tagging-permissions) command-line tool. ::: moniker-end - - By default, members of the project level **Contributors** group can subscribe to alerts for themselves. - Members of the **Project Collection Administrators** group, or users who have the **Edit collection-level information** @@ -3189,7 +2931,7 @@ There are no UI permissions associated with [managing email notifications or ale ::: moniker range="< azure-devops" - You can manage alert permissions using [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd). +You can manage alert permissions using [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd). :::row::: :::column span=""::: @@ -3206,6 +2948,7 @@ There are no UI permissions associated with [managing email notifications or ale **Project Collection Service Accounts** :::column-end::: :::row-end::: +--- :::row::: :::column span=""::: `CREATE_SOAP_SUBSCRIPTION` @@ -3265,15 +3008,11 @@ There are no UI permissions associated with [managing email notifications or ale ::: moniker-end - ## Related articles -- [Get started with permissions, access, and security groups](about-permissions.md) -- [Security and permission management tools](security-tools-reference.md) -- [Security namespace and permission reference for Azure DevOps](namespace-reference.md) -- [Service accounts and dependencies](/azure/devops/server/admin/service-accounts-dependencies) +- [Get started with permissions, access, and security groups](about-permissions.md) +- [Security namespace and permission reference for Azure DevOps](namespace-reference.md) - [Add users to an organization (Azure DevOps Services)](../accounts/add-organization-users.md) -- [Add users to a team or a project](../../organizations/security/add-users-team-project.md) -- [Add users to an administrator role](/azure/devops/server/admin/add-administrator) +- [Add users to a team or a project](../../organizations/security/add-users-team-project.md) - [Make a user a team administrator](../settings/manage-teams.md) - [Troubleshoot permissions](troubleshoot-permissions.md) diff --git a/docs/organizations/security/provide-stakeholder-pipeline-access.md b/docs/organizations/security/provide-stakeholder-pipeline-access.md deleted file mode 100644 index 4e64a26996c..00000000000 --- a/docs/organizations/security/provide-stakeholder-pipeline-access.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: Provide free access to pipelines for Stakeholders -titleSuffix: Azure DevOps Services -description: Add & update work items, approve releases, view work tracking progress with Stakeholder access -ms.subservice: azure-devops-security -ms.assetid: -ms.author: chcomley -author: chcomley -ms.topic: how-to -monikerRange: 'azure-devops' -ms.date: 07/28/2020 ---- - - -# Provide Stakeholders access to edit build and release pipelines - -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -To provide Stakeholders permissions to create, edit, and manage build and release pipelines, you can enable the **Free access to Pipelines for Stakeholders** account-level preview feature. This feature essentially enables an unlimited number of free users to manage and configure pipelines in your projects. - -> [!IMPORTANT] -> The **Free access to Pipelines for Stakeholders** preview feature is turned on by default for all organizations created after July, 7th 2018. It is only available from Azure DevOps Services. - -Without this feature enabled, stakeholders can only [view and approve releases](permissions-access.md#pipelines). - -## Turn on Free access to Pipelines for Stakeholders - -To enable the **Free access to Pipelines for Stakeholders** feature, see [Manage or enable features](../../project/navigation/preview-features.md). You can only enable it at the account level. - -> [!div class="mx-imgBorder"] -> ![Preview feature, account level](media/stakeholder-security/preview-features-s172.png) - -When the feature is turned on, all Stakeholders in your account have full access to **Pipelines** and it's associated features. This includes the ability to view, create, and delete automated test runs. For a complete list of associated features and tasks, see [Build and release permissions and roles](../../pipelines/policies/permissions.md). - -Stakeholders are still subject to the permissions set for their security group. For example, if they are in the Project Readers security group they have Read-only access to **Build and Release**. If you need more fine grained control over what features Stakeholders can access, you can create a custom security group and set more fine grained permissions to certain groups of users as described in the next section. - - -## Limit access to select Stakeholders to CI/CD features - -After turning on the **Free access to Pipelines for Stakeholders** preview feature, you can limit access to select features or tasks by setting permissions. The general steps are: - -1. Create a custom, project-level, security group in Azure DevOps. -2. Add users to this group -3. Set permissions to **Deny** or **Not set** for those CI/CD features you want to limit access to. You can set permissions for these CI/CD artifacts: - - All build pipelines or select build pipelines - - All release pipelines or select release pipelines - - Task groups -1. Add the security group to a Library security role for these artifacts: - - Variable groups - - Secure files - - Deployment groups - - -## Create a custom security group - -Create a custom security group at the project-level or the collection-level. The method for creating a custom security group is the same, no matter at what level you add it. - -> [!TIP] -> You only need to create a project-level security group if you are going to limit CI/CD tasks at the project level. - -To create a project-level security group, open the web portal and choose the project where you want to add users or groups. - -> [!NOTE] -> To enable the Project Permissions Settings Page user interface that is in preview, see [Enable preview features](../../project/navigation/preview-features.md). - -#### [Preview page](#tab/preview-page) - -1. Choose **Project settings**, and then **Permissions**. - - ![Choose Project settings, and then Permissions](media/permissions/choose-project-settings-permissions.png) - -2. Choose **New group** to open the dialog for adding a group. - - ![Choose New group](media/permissions/permissions-select-new-group.png) - -3. Enter a name for the group, add users or groups, and optionally a description. Choose **Create**. - - :::image type="content" source="media/stakeholder-security/add-new-group.png" alt-text="Create group dialog"::: - -#### [Current page](#tab/current-page) - -1. Choose **Project Settings** in the sidebar. - - > [!div class="mx-imgBorder"] - > ![Web portal, open project admin context, vertical nav](../../media/settings/open-project-settings-vert-brn.png) - -2. Open the **Security** page and choose **Create group** to open the dialog for adding a group. - - > [!div class="mx-imgBorder"] - > ![Create security group](media/stakeholder-security/create-group-option-vert.png) - -3. Enter a name for the group, and optionally a description. - - For example, here we define a *Stakeholder Access* group. - - > [!div class="mx-imgBorder"] - > ![Create group dialog](media/stakeholder-security/create-group-dialog.png) - -4. Choose **Create group**. - -* * * - -## Add members to the custom security group - -#### [Preview page](#tab/preview-page) - -1. To add members to the group, choose the security group, choose **Members**, and then choose **Add**. - - :::image type="content" source="media/stakeholder-security/add-users-to-group.png" alt-text="Permissions, Group, Members tab, Choose Add"::: - -1. Type the name of the user account into the text box. You can enter several identities into the text box, separated by commas. Specify individual emails, groups defined in an existing Azure Active Directory or existing Azure DevOps groups. The system automatically searches for matches. Choose the matches that meet your requirements. - - :::image type="content" source="media/stakeholder-security/invite-members-dialog.png" alt-text="Invite members dialog"::: - -1. Choose **Save**. - -1. To remove a user account from the group, select the checkbox of the account and choose **Remove**. - - :::image type="content" source="media/stakeholder-security/remove-member.png" alt-text="Remove a member from group"::: - - Confirm your removal by choosing Remove in the dialog that appears. - -#### [Current page](#tab/current-page) - -1. To add members to the group, choose the security group, choose **Members**, and then choose **Add**. - - > [!div class="mx-imgBorder"] - > ![Add members](media/stakeholder-security/choose-members-add.png) - -1. Type the name of the user account into the text box. You can enter several identities into the text box, separated by commas. Specify individual emails, groups defined in an existing Azure Active Directory or existing Azure DevOps groups. The system automatically searches for matches. Choose the matches that meet your requirements. - - Add users and group dialog - -2. Choose **Save changes**. - -* * * - - - -## Set permissions for build pipelines - -Open the Security dialog for all or a select build pipeline. - -1. To set the permissions for all build pipelines, choose **Pipelines>Builds**, choose the :::image type="icon" source="../../media/icons/folder.png" border="false"::: folder icon, and then, with **All build pipelines** selected, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false":::actions icon and select **Security**. - - > [!div class="mx-imgBorder"] - > ![Open the Security dialog for all build pipelines, vertical nav](media/stakeholder-security/open-security-all-build-pipelines-new-nav.png) - -1. To set the permissions for a specific build pipeline, open the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the specific build and choose **Security**. - - > [!div class="mx-imgBorder"] - > ![Open the security dialog for a build pipeline](media/stakeholder-security/open-security-build-pipeline-new-nav.png) - - -## Add and set permissions for the custom security group - -1. Enter the name of the group you want to add to the Permissions dialog. For example, here we enter *Stakeholder Access* group to the Permissions dialog. - - > [!div class="mx-imgBorder"] - > ![Enter custom security group name into the search box](media/stakeholder-security/pipeline-stakeholder-group-permissions.png) - - Set the permissions you want for the group and then close the dialog. Change the permission settings to **Deny** for those permissions you want to limit access to. - - There is no Save button. - - - - -## Set permissions for release definitions - -You can follow the steps provided in the previous two procedures to set permissions for release definitions. - -Open the Security dialog for all or a select release pipeline. - -1. To set the permissions for a specific release pipeline, open the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon menu for the build and choose **Security**. - -2. Enter the custom security group, such as *Stakeholder Access*, to the search box on the Permissions page. - - Change the permission settings to **Deny** for those permissions you want to limit access to. - - > [!div class="mx-imgBorder"] - > ![Choose Add link to add a group](media/stakeholder-security/release-permissions-dialog.png) - - Set the permissions you want for the group and then close the dialog. Change the permission settings to **Deny** for those permissions you want to limit access to. - - There is no Save button. - -## Limit access to Library resources - -To prevent Stakeholders from editing Library resources, add your custom security group to the Library reader role. To learn how, see [Manage Library roles for variable groups, secure files, and deployment groups](../../pipelines/policies/set-permissions.md). - - -## Limit access to task group - -To prevent Stakeholders from editing task groups, add your custom security group to the task group permissions and set all permissions to **Deny**. To learn how, see [Manage Library roles for variable groups, secure files, and deployment groups](../../pipelines/policies/set-permissions.md). - - -## Related articles - -- [Set build and release permissions](../../pipelines/policies/set-permissions.md) -- [Build and release permissions and roles (Security)](../../pipelines/policies/permissions.md) -- [Get started as a stakeholder](get-started-stakeholder.md) diff --git a/docs/organizations/security/quick-reference-index-security.md b/docs/organizations/security/quick-reference-index-security.md deleted file mode 100644 index 6f62aa92ecf..00000000000 --- a/docs/organizations/security/quick-reference-index-security.md +++ /dev/null @@ -1,324 +0,0 @@ ---- -title: Quick reference index to Azure DevOps security -titleSuffix: Azure DevOps -description: Index to concepts and tasks for configuring security. -ms.custom: quick-reference-index -ms.subservice: azure-devops-security -ms.topic: overview -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 01/13/2022 ---- - -# Security quick reference index - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Use this index to quickly access concepts and tasks related to securing Azure DevOps. If you're new to Azure DevOps, see [What is Azure DevOps?](../../user-guide/what-is-azure-devops.md) - - - -## Get started - -As individual contributors to Azure DevOps, learn about how permissions and access to features are managed, default permission assignments, how to view your permissions, and how to increase or trace your permissions. - -- [About permissions, access, & security groups](about-permissions.md) -- [Default permissions & access](permissions-access.md) -- [View permissions](view-permissions.md) -- [Troubleshoot permissions](troubleshoot-permissions.md) -- [Request an increase in permission levels](request-changes-permissions.md) -- [Add an alternate account to your Visual Studio subscription](/visualstudio/subscriptions/vs-alternate-identity?toc=/azure/devops/organizations/toc.json) - -::: moniker range="azure-devops" - -For organization owners or project administrators, learn about authentication and authorization, how to add and manage users and their access, and set organization policies. - -- [About security, authentication, & authorization](about-security-identity.md) -- [About access levels](access-levels.md ) -- [Add users & manage access (cloud)](../accounts/add-organization-users.md) -- [Add users to a project or team](add-users-team-project.md) - -::: moniker-end - -::: moniker range="< azure-devops" - -For project collection and project administrators, learn more about security and how to add and manage user access, and secure projects and deployment. - -- [About security, authentication, & authorization](about-security-identity.md) -- [About access levels](access-levels.md ) -- [Change access levels (on-premises)](change-access-levels.md) -- [Add users to a project or team](add-users-team-project.md) - -::: moniker-end - -## Concepts - ---- -:::row::: - :::column span="1"::: - - [Access control entries (ACE)](about-security-identity.md#namespaces) - - [Access control list (ACL)](about-security-identity.md#namespaces) - - [Access level](access-levels.md) - - [Accounts](about-security-identity.md#accounts) - - [Active Directory](about-permissions.md#aad) - - [Auditing](../audit/azure-devops-auditing.md) - - [Authentication](about-security-identity.md#authentication) - - [Authorization](about-security-identity.md#authorization) - - [Azure Active Directory](about-permissions.md#aad) - - [Basic access](access-levels.md) - - [Collections](../projects/about-projects.md) - - [Conditional access](../accounts/change-application-access-policies.md#conditional-access-policies) - - [Git credential manager](../../repos/git/set-up-credential-managers.md?toc=/azure/devops/organizations/toc.json) - :::column-end::: - :::column span="1"::: - - [Inheritance](about-permissions.md#inheritance) - - [Namespaces](about-security-identity.md#namespaces) - - [OAuth](../../integrate/get-started/authentication/oauth.md) - - [Organizations](../../user-guide/plan-your-azure-devops-org-structure.md) - - [Organization owner](look-up-organization-owner.md) - - [Permissions](about-permissions.md#permissions) - - [Permission states](about-permissions.md#permission-states) - - [Personal Access Tokens (PATs)](about-security-identity.md#authentication) - - [Preview features](../../project/navigation/preview-features.md?toc=/azure/devops/organizations/toc.json) - - [Project-scoped User Groups](../../user-guide/manage-organization-collection.md#project-scoped-user-group) - - [Projects](../projects/about-projects.md) - - [Resources granted to project members](../projects/resources-granted-to-project-members.md) - :::column-end::: - :::column span="1"::: - - [Security best practices](security-best-practices.md) - - [Security groups](about-permissions.md#security-group-membership) - - [Security policies](about-security-identity.md#application-connection-and-security-policies) - - [Security roles](about-security-roles.md) - - [Service accounts](about-security-identity.md#accounts) - - [Service principal](about-security-identity.md#accounts) - - [Secure Sockets Layer (SSL)](data-protection.md) - - [SSH authentication](../../repos/git/use-ssh-keys-to-authenticate.md?toc=/azure/devops/organizations/toc.json) - - [Stakeholder access](access-levels.md) - - [Team group](../settings/about-teams-and-settings.md#team-groups) - - [Tenant](../accounts/change-organization-location.md) - - [Token](namespace-reference.md) - - [Valid users](about-permissions.md#validusers) - :::column-end::: -:::row-end::: ---- - - -## Tasks - -The primary tasks for administrators to secure Azure DevOps are to assign access levels, set permissions, assign security roles, and set policies. Development leads and pipeline administrators should become familiar with setting permissions and policies on repositories, branches, and pipeline resources. - - ---- -:::row::: - :::column span="1"::: - **Access levels** - ::: moniker range="azure-devops" - - [Change a user's access level](../accounts/add-organization-users.md) - - [Provide Stakeholders access to edit pipelines](provide-stakeholder-pipeline-access.md) - ::: moniker-end - ::: moniker range="< azure-devops" - - [Change access levels](change-access-levels.md) - ::: moniker-end - - - **Set project-level permissions** - - [Request an increase in permission levels](request-changes-permissions.md) - - [Change project-level permissions](change-project-level-permissions.md) - - [Grant or restrict permissions to select tasks](restrict-access.md) - - [Dashboard permissions](../../report/dashboards/dashboard-permissions.md?toc=/azure/devops/organizations/toc.json) - - [Analytics permissions](../../report/powerbi/analytics-security.md?toc=/azure/devops/organizations/toc.json) - - [Wiki permissions](../../project/wiki/manage-readme-wiki-permissions.md?toc=/azure/devops/organizations/toc.json) - - [Feedback permissions]/previous-versions/azure/devops/project/feedback/give-permissions-feedback) - :::column-end::: - :::column span="1"::: - **Authentication** - - [Choose authentication method](../../integrate/get-started/authentication/authentication-guidance.md?toc=/azure/devops/organizations/toc.json) - - [Authenticate access with PATs](../accounts/use-personal-access-tokens-to-authenticate.md?toc=/azure/devops/organizations/toc.json) - - [Manage personal access tokens using API](../accounts/manage-personal-access-tokens-via-api.md?toc=/azure/devops/organizations/toc.json) - - [Use SSH key authentication](../../repos/git/use-ssh-keys-to-authenticate.md?toc=/azure/devops/organizations/toc.json) - - [Use OAuth 2.0 to authorize access to REST APIs](../../integrate/get-started/authentication/oauth.md?toc=/azure/devops/organizations/toc.json) - - [Authorize a service, manage authorizations](../settings/manage-authorizations.md) - - [Revoke users' PATs (for admins)](../accounts/admin-revoke-user-pats.md?toc=/azure/devops/organizations/toc.json) - - [Set up Git credential manager](../../repos/git/set-up-credential-managers.md?toc=/azure/devops/organizations/toc.json) - - [Git authentication](../../repos/git/auth-overview.md?toc=/azure/devops/organizations/toc.json) - - [Authenticate extensions](../../extend/develop/auth.md?toc=/azure/devops/organizations/toc.json) - :::column-end::: -:::row-end::: ---- -::: moniker range="azure-devops" -:::row::: - :::column span="1"::: - **Azure Active Directory** - - [Connect organization to Azure AD](../accounts/connect-organization-to-azure-ad.md) - - [Add users to Azure Active Directory](/azure/active-directory/fundamentals/add-users-azure-active-directory?bc=%252fazure%252fdevops%252forganizations%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252forganizations%252ftoc.json) - - [Add Azure AD security groups to Azure DevOps security groups](add-ad-aad-built-in-security-groups.md) - - [Manage Azure Active Directory groups](../accounts/manage-azure-active-directory-groups.md) - - [Manage group rules](../accounts/assign-access-levels-by-group-membership.md) - - [Change Azure AD connection](../accounts/change-azure-ad-connection.md) - - [Disconnect from Azure AD](../accounts/disconnect-organization-from-azure-ad.md) - - [List organizations connected to Azure AD](../accounts/get-list-of-organizations-connected-to-azure-active-directory.md) - - - **Set organization or collection-level permissions** - - [Change organization-level permissions](change-organization-collection-level-permissions.md) - - [Change project collection-level permissions](change-organization-collection-level-permissions.md) - - [Change process permissions](set-permissions-access-work-tracking.md#process-permissions) - - [Set permissions to manage extensions](../../marketplace/grant-permissions.md?toc=/azure/devops/organizations/toc.json) - - [Enable Project-Scoped Users Group](../../user-guide/manage-organization-collection.md#project-scoped-user-group) - - - - **Set object-level permissions** - - [Set object-level permissions](set-object-level-permissions.md) - :::column-end::: - :::column span="1"::: - **Set organization policies** - - [Manage security & app access policies](../accounts/change-application-access-policies.md) - - [Add external users](../accounts/add-external-user.md) - - [Disable Request Access policy](../accounts/disable-request-access-policy.md) - - [Restrict admins from inviting new users](../security/restrict-invitations.md) - - [Restrict users from creating new organizations with Azure Active Directory policy](../accounts/azure-ad-tenant-policy-restrict-org-creation.md) - - [Enable Conditional Access or Multi-factor Authentication](/azure/active-directory/authentication/tutorial-enable-azure-mfa) - - - **Secure data and networks** - - [Allowed address lists & network connections](allow-list-ip-url.md) - - [Install and use Visual Studio and Azure Services behind a firewall or proxy server](/visualstudio/install/install-and-use-visual-studio-behind-a-firewall-or-proxy-server) - - [Save project data](../projects/save-project-data.md) - - [Data protection overview ](data-protection.md) - - [Data location](data-location.md) - - [Data Subject Requests for the GDPR & CCPA](/microsoft-365/compliance/gdpr-dsr-vsts?toc=/azure/devops/organizations/toc.json) - - [Credential storage ](credential-storage.md) -:::row-end::: ---- -::: moniker-end ---- -::: moniker range="< azure-devops" -:::row::: - :::column span="1"::: - **Active Directory** - - [Manage Active Directory groups](/azure/devops/server/admin/setup-ad-groups?toc=/azure/devops/organizations/toc.json) - - [Add Active Directory security groups to Azure DevOps security groups](add-ad-aad-built-in-security-groups.md) - - **Set collection and server instance permissions** - - [Change project collection-level permissions](change-organization-collection-level-permissions.md) - - [Change process permissions](set-permissions-access-work-tracking.md#process-permissions) - - [Set permissions to manage extensions](../../marketplace/grant-permissions.md?toc=/azure/devops/organizations/toc.json) - - [Add server administrators](/azure/devops/server/admin/add-administrator) - :::column-end::: - :::column span="1"::: - **Secure on-premises deployments** - - [Allowed address lists & network connections](allow-list-ip-url.md) - - [Install and use Visual Studio and Azure Services behind a firewall or proxy server](/visualstudio/install/install-and-use-visual-studio-behind-a-firewall-or-proxy-server) - - [Ports required for Azure DevOps Server](/azure/devops/server/architecture/required-ports) - - [Save project data](../projects/save-project-data.md) - - [Set up secure sockets layer](/azure/devops/server/admin/setup-secure-sockets-layer?toc=/azure/devops/organizations/toc.json) - - [Web site settings & security](/azure/devops/server/admin/websitesettings?toc=/azure/devops/organizations/toc.json) - - [TFSSecurity command](/azure/devops/server/command-line/tfssecurity-cmd?toc=/azure/devops/organizations/toc.json) - - [Set SQL Server report permissions](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports) -:::row-end::: ---- -::: moniker-end -:::row::: - :::column span="1"::: - **Set Boards/work tracking permissions** - - [Create tag definition](change-project-level-permissions.md) - - [Delete and restore work items](set-permissions-access-work-tracking.md#move-delete-permissions) - - [Delete field from organization](change-organization-collection-level-permissions.md) - - [Delivery plans](set-permissions-access-work-tracking.md#edit-or-manage-permissions-for-delivery-plans) - - [Move work items out of a project](set-permissions-access-work-tracking.md#move-delete-permissions) - - [Manage area and iteration paths](set-permissions-access-work-tracking.md#set-permissions-area-path) - - [Modify work items under an area path](set-permissions-access-work-tracking.md#set-permissions-area-path) - - [Permanently delete work items](change-project-level-permissions.md) - - [Process permissions](set-permissions-access-work-tracking.md#process-permissions) - - [Queries and query folders](../../boards/queries/set-query-permissions.md) - - - **Set test permissions** - - [Create, delete, and view test runs](set-permissions-access-test.md#delete-test-artifacts) - - [Manage test configurations](change-project-level-permissions.md) - - [Manage test environments](change-project-level-permissions.md) - - [Manage test controllers](set-permissions-access-test.md#test-controllers) - - [Manage test plans and test suites under an area path](set-permissions-access-test.md#manage-test-artifacts) - - [Set access, license requirements](../../test/manual-test-permissions.md) - :::column-end::: - :::column span="1"::: - **Set repository and branch permissions** - - [Git repository permissions](../../repos/git/set-git-repository-permissions.md) - - [TFVC repository permissions](../../repos/tfvc/set-tfvc-repository-permissions.md) - - [Git branch permissions](../../repos/git/branch-permissions.md?toc=/azure/devops/organizations/toc.json) - - [Administer shelved changes (TFVC)](change-project-level-permissions.md) - - [Administer workspaces (TFVC)](change-project-level-permissions.md) - - [Create a workspace (TFVC)](change-project-level-permissions.md) - - - **Set Git repository and branch policies** - - [Git repository settings and policies](../../repos/git/repository-settings.md) - - [Git branch policies](../../repos/git/branch-policies.md) - - [Git branch policy for an external service](../../repos/git/pr-status-policy.md) - - [Use Azure Functions to create custom Git branch policies](../../repos/git/create-pr-status-server-with-azure-functions.md) - - - **Secure code** - - [Secure Development Documentation](/azure/security/develop/) - - [About Microsoft Security Code Analysis](/azure/security/develop/security-code-analysis-overview) - - [Microsoft Threat Modeling Tool](/azure/security/develop/threat-modeling-tool) - - [Security in DevOps (DevSecOps)](/devops/operate/security-in-devops) - - [Enable DevSecOps with Azure and GitHub](/devops/devsecops/enable-devsecops-azure-github) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - **Set pipeline permissions and policies** - - [Assign pipeline security roles](../../pipelines/policies/permissions.md) - - [Grant version control permissions to the build service](../../pipelines/scripts/git-commands.md) - - [Administer build resource permissions](change-project-level-permissions.md) - - [Manage build resources](change-project-level-permissions.md) - - [Manage pipeline policies](change-project-level-permissions.md) - - [Use build resources](change-project-level-permissions.md) - - [View build resources](change-project-level-permissions.md) - - [Set pipeline permissions](../../pipelines/policies/set-permissions.md?toc=/azure/devops/organizations/toc.json) - :::column-end::: - :::column span="1"::: -     - - [Pipelines security walkthrough](../../pipelines/security/overview.md?toc=/azure/devops/organizations/toc.json) - - [Approach to securing YAML pipelines](../../pipelines/security/approach.md?toc=/azure/devops/organizations/toc.json) - - [Repository protection](../../pipelines/security/repos.md?toc=/azure/devops/organizations/toc.json) - - [Pipeline resources](../../pipelines/security/resources.md?toc=/azure/devops/organizations/toc.json) - - [Project structure](../../pipelines/security/projects.md?toc=/azure/devops/organizations/toc.json) - - [Security through templates](../../pipelines/security/templates.md?toc=/azure/devops/organizations/toc.json) - - [Variables and parameters](../../pipelines/security/inputs.md?toc=/azure/devops/organizations/toc.json) - - [Shared infrastructure](../../pipelines/security/infrastructure.md?toc=/azure/devops/organizations/toc.json) - - [Other security considerations](../../pipelines/security/misc.md?toc=/azure/devops/organizations/toc.json) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - **Set feed permissions** - - [Secure and share packages using feed permissions](../../artifacts/feeds/feed-permissions.md) - :::column-end::: -:::row-end::: ---- - - -## Reference - -- [Permissions lookup guide](permissions-lookup-guide.md) -- [Permissions & groups](permissions.md) -- [Security management tools](security-tools-reference.md) -- [Security namespaces & permissions](namespace-reference.md) -- [Manage security groups with CLI](add-manage-security-groups.md) -- [Manage permissions with CLI](manage-tokens-namespaces.md) - - -## Related articles -- [About settings for users, teams, projects, or organizations](../settings/about-settings.md) -- [Visual Studio subscriptions](/visualstudio/subscriptions/) -- [Azure Boards settings quick reference index](../../reference/quick-reference-index-boards-settings.md) - - - - diff --git a/docs/organizations/security/remove-users-prohibit-access.md b/docs/organizations/security/remove-users-prohibit-access.md deleted file mode 100644 index 95e89c0509e..00000000000 --- a/docs/organizations/security/remove-users-prohibit-access.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Remove users from AD/Azure AD security groups -titleSuffix: Azure DevOps -description: Manage changes to an organization when users leave a project or company by removing their user account from AD/Azure AD security groups -ms.subservice: azure-devops-security -ms.assetid: -ms.author: chcomley -author: chcomley -ms.topic: tutorial -monikerRange: '<= azure-devops' -ms.date: 10/14/2019 ---- - -# Remove user accounts from Azure Active Directory or Active Directory - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -When a user with access to Azure DevOps leaves a company, an administrator would typically remove them from Azure Active Directory or Active Directory. This automatically voids their user account and remove their ability to access or connect to Azure DevOps. - -::: moniker range="azure-devops" -If you manage your Azure DevOps users with Microsoft Service Accounts (MSA), then you'll need to [remove their account](../accounts/delete-organization-users.md). - -In this article you'll find: -> [!div class="checklist"] -> * A checklist to review when removing user accounts -> * Options for removing users from organizations in Azure DevOps -> * Links to articles for removing user accounts from AD or Azure AD -::: moniker-end - -::: moniker range="< azure-devops" - -In this article you'll find: -> [!div class="checklist"] -> * A checklist to review when removing user accounts -> * Links to articles for removing user accounts from AD or Azure AD -::: moniker-end - - -## Consider when removing users - -* Do users have any tokens that you need to revoke? -* Have you granted individual user accounts special permissions that need to be revoked? -* Have you reassigned work users you are removing to current team members? - -::: moniker range="azure-devops" - -## Remove users from an organization in Azure DevOps - -If your organization uses MSA accounts, then to you must remove users from the organization as you have no other way to prevent access. When you do so, you'll not be able to create a query for work items assigned to the removed user account. To learn more, see [Delete users from Azure DevOps](../accounts/delete-organization-users.md). - -If your organization is backed by Azure AD, then you can disable or delete the Azure AD user account while leaving their Azure DevOps account active. In this way, you can continue to query their work item history using their account name. - -::: moniker-end - -## Remove users from AD or Azure AD - -For information on removing users from AD or Azure AD, see one of the following articles: - -* [Delete users from Azure AD](/azure/active-directory/add-users-azure-active-directory#delete-a-user) -* [Delete a User Account from Active Directory](/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc753730(v=ws.11)) - -## Related articles - -* [About permissions and inheritance](../../organizations/security/about-permissions.md) -- [Change project-level permissions](change-project-level-permissions.md) -- [Change project collection-level permissions](change-organization-collection-level-permissions.md) -* [About security, authentication, and authorization](about-security-identity.md) \ No newline at end of file diff --git a/docs/organizations/security/request-changes-permissions.md b/docs/organizations/security/request-changes-permissions.md index cee21093e4d..6585cf55e9d 100644 --- a/docs/organizations/security/request-changes-permissions.md +++ b/docs/organizations/security/request-changes-permissions.md @@ -4,53 +4,53 @@ titleSuffix: Azure DevOps description: How-to guide for finding and increasing permission levels needed to perform select tasks in Azure DevOps. ms.subservice: azure-devops-security ms.custom: security-refresh +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 02/11/2022 +ms.date: 11/27/2024 --- -# Request an increase in permission levels +# Request a permission increase [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -To get access to certain tasks, you might need to request an increase to your permissions or be added to a security role. Typically, you'll do this upon receiving an information or error message indicating you have insufficient permissions. Such a message will indicate the permission levels you need. - -Prior to requesting a change in permission levels, make sure you understand the basics by reviewing [Get started with permissions, access, and security groups](about-permissions.md). +To access certain tasks, you might need to request higher permissions or be assigned to a specific security role. This scenario typically occurs when you encounter an informational or error message indicating insufficient permissions, which specify the required permission levels. ## Common permissions to request -Most users added to the **Contributors** group are granted the permissions they need to perform most tasks. However, the following tasks require membership in the **Project Administrators** group or a change in permissions. +Most members of the **Contributors** group have the permissions they need to perform most tasks. However, the following tasks require membership in the **Project Administrators** group or a change in permissions. -- **Work tracking** - - Add or change **Area Paths** or **Iteration Paths**: Requires elevated permissions to an Area Path or Iteration Path node. To learn more, see [Set work tracking permissions, Create child nodes](set-permissions-access-work-tracking.md#set-permissions-area-path). - - Create shared queries or query folders: Requires elevated permissions set for a shared query folder. To learn more, see [Set work tracking permissions, Set permissions on queries or query folders](set-permissions-access-work-tracking.md#work-item-queries). - - Change team settings—such as Kanban board settings: Requires addition as a team administrator. To learn more, see [Add or remove a team administrator](../settings/add-team-administrator.md) +- **Work tracking**: + - **Add or change Area Paths or Iteration Paths**: Requires elevated permissions to an Area Path or Iteration Path node. For more information, see [Set work tracking permissions, Create child nodes](set-permissions-access-work-tracking.md#set-permissions-area-path). + - **Create shared queries or query folders**: Requires elevated permissions set for a shared query folder. For more information, see [Set work tracking permissions, Set permissions on queries or query folders](set-permissions-access-work-tracking.md#work-item-queries). + - **Change team settings—such as board settings**: Requires addition as a team administrator. For more information, see [Add or remove a team administrator](../settings/add-team-administrator.md). -- **Source code, Git repositories**, the following tasks require elevated permissions for Git repositories or a specific repository. To learn more, see [Set Git repository permissions](../../repos/git/set-git-repository-permissions.md). +- **Source code, Git repositories**: The following tasks require elevated permissions for Git repositories or a specific repository. For more information, see [Set Git repository permissions](../../repos/git/set-git-repository-permissions.md). - Create, delete, or rename a Git repository - Manage repository permissions - Bypass policies The following tasks require membership in the **Project Collection Administrators** group or a change in permissions at the collection-level or addition to a specific role. -- **Collection-level configurations** - - Create projects: Requires elevated permissions at the [collection level](change-organization-collection-level-permissions.md). - - Add, edit, or manage a process: Requires elevated permissions at the collection level or [process-level permissions](set-permissions-access-work-tracking.md#process-permissions). - - Install, uninstall, or disable extensions: Requires addition to the [Manager role](../../marketplace/grant-permissions.md) for extensions. +- **Collection-level configurations**: + - **Create projects**: Requires elevated permissions at the [collection level](change-organization-collection-level-permissions.md). + - **Add, edit, or manage a process**: Requires elevated permissions at the collection level or [process-level permissions](set-permissions-access-work-tracking.md#process-permissions). + - **Install, uninstall, or disable extensions**: Requires addition to the [Manager role](../../marketplace/grant-permissions.md) for extensions. For an overview of built-in security groups and default permission assignments, see [Default permissions and access](permissions-access.md). ## Prerequisites -- To view permissions, you must be a member of the **Project Valid Users** group. Users added to a project are automatically added to this security group. To learn more, see [View permissions for yourself or others](view-permissions.md). -- To look up an administrator for your project or project collection, you must be a member of the **Project Valid Users** group. - +| Category | Requirements | +|--------------|-------------| +| **Permissions** | To view permissions and to look up a project administrator: Member of the **Project Valid Users** group. Project members are automatically part of this security group. For more information, see [View permissions for yourself or others](view-permissions.md). | +| **Knowledge** | Before you request a permission change, ensure you understand the basics by reviewing [Get started with permissions, access, and security groups](about-permissions.md). | ::: moniker range="azure-devops" > [!NOTE] -> Users added to the **Project-Scoped Users** group won't be able to access **Organization Settings** other than the **Overview** section if the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization. For more information including important security-related call-outs, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). +> Users added to the **Project-scoped users** group don't have access to **Organization settings** other than the **Overview** section if the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization. For more information including important security-related call-outs, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). ::: moniker-end @@ -59,7 +59,6 @@ For an overview of built-in security groups and default permission assignments, Before you request a change to permission levels, review your permission assignments as described in [View permissions for yourself or others](view-permissions.md). Verify that your permission assignments are preventing you from accomplishing a task you need to perform. - ## Request a change to a permission level or role change @@ -75,18 +74,19 @@ To request a change or increase in your permission levels, take the following ac 1. Contact the person you identified in step 2 and make your request. Make sure you specify the permission you want changed. +## Refresh or reevaluate your permissions -## Refresh or re-evaluate your permissions +After your permission levels get changed, you might need to refresh your permissions for Azure DevOps to recognize the updates. This step is recommended when: -After your permission levels are changed, you may need to refresh your permissions for Azure DevOps to recognize the changes. This step is recommended when a change is made to your permission level, role level, or if you are added to a new or different Azure DevOps, Azure Active Directory, or Active Directory security group. When you are added to a new or different security group, your inherited permissions may change. +- **Permission or role changes:** Your permission level or role was modified. +- **Security group modifications:** You were added to a new or different security group in Azure DevOps, Microsoft Entra ID, or Active Directory. -By refreshing your permissions, you cause Azure DevOps to re-evaluate your permission assignments. Otherwise, your permission assignments won't be refreshed until you sign-off, close your browser, and sign-in again. +Getting added to a new security group can alter your inherited permissions. -To refresh your permissions, choose **User settings**, on the **Permissions** page, you can select **Re-evaluate permissions**. This function reevaluates your group memberships and permissions, and then any recent changes take effect immediately. +**Refresh your permissions**, which prompts Azure DevOps to reevaluate your permission assignments immediately. If you don't refresh, your permission assignments don't update until you sign out, close your browser, and sign back in. :::image type="content" source="media/troubleshoot-permissions/re-evaluate-permissions-button.png" alt-text="Reevaluate permissions control"::: - ## Related articles - [Permissions lookup guide](permissions-lookup-guide.md) @@ -94,4 +94,4 @@ To refresh your permissions, choose **User settings**, on the **Permissions** pa - [Troubleshoot permissions](troubleshoot-permissions.md) - [Look up a project administrator](look-up-project-administrators.md) - [Look up a project collection administrator](look-up-project-collection-administrators.md) - \ No newline at end of file + diff --git a/docs/organizations/security/restrict-access.md b/docs/organizations/security/restrict-access.md index f045a423481..64fecfd9437 100644 --- a/docs/organizations/security/restrict-access.md +++ b/docs/organizations/security/restrict-access.md @@ -1,67 +1,50 @@ --- -title: Grant or restrict access to select features +title: Manage access to specific features titleSuffix: Azure DevOps -description: How to set permissions to grant or restrict access to select build, version control, or work tracking functions +description: How to set permissions to grant or restrict access to specific build, version control, or work tracking functions. ms.assetid: ee4c4a8f-0478-4ade-8b12-4e5ffd0054c7 ms.topic: overview ms.subservice: azure-devops-security ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 03/23/2023 +ms.date: 01/05/2025 --- -# Grant or restrict access using permissions +# Manage access to specific features [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can grant or restrict access to resources that you manage in Azure DevOps. You may want to open up or close down access to a select set of features and for a select set of users. While the built-in security groups provide a standard set of permission assignments, you may need more security requirements not met by these assignments. +Managing access to specific features in Azure DevOps can be crucial for maintaining the right balance of openness and security. Whether you're looking to grant or restrict access to certain functionalities for a group of users, understanding the flexibility beyond the standard permissions provided by built-in security groups is key. -If you're new to administrating permissions and groups, review [Get started with permissions, access, and security groups](about-permissions.md) to learn about permission states and inheritance. +If you're new to the permissions and groups landscape, see [Get started with permissions, access, and security groups](about-permissions.md). This article covers the essentials of permission states and how they inherit. -In this article you learn how to do the following tasks: +> [!TIP] +> The structure of your project in Azure DevOps plays a pivotal role in determining the granularity of permissions at an object level, such as repositories and area paths. This structure is the foundation that allows you to fine-tune access controls, enabling you to specifically delineate which areas are accessible or restricted. For more information, see [About projects and scaling your organization](../projects/about-projects.md). -::: moniker range="azure-devops" +## Prerequisites -> [!div class="checklist"] -> * Recommended method for granting and restricting permissions -> * Delegate tasks by assigning select permissions to specific roles -> * Limit user visibility to organization information -> * Limit people picker to project users and groups -> * Restrict access to view or modify objects -> * Restrict modification of work items based on a user or group -::: moniker-end +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] -::: moniker range="< azure-devops" +## Use security groups -> [!div class="checklist"] -> * Recommended method for granting and restricting permissions -> * Delegate tasks by assigning select permissions to specific roles -> * Restrict access to view or modify objects -> * Restrict modification of work items based on a user or group -::: moniker-end +For optimal maintenance, we recommend using the default security groups or establishing [custom security groups to manage permissions](add-remove-manage-user-group-security-group.md). The permission settings for the **Project Administrators** and **Project Collection Administrators** groups are fixed by design and can't be altered. However, you have the flexibility to modify permissions for all other groups. -> [!TIP] -> Because you set many permissions at an object-level, such as repositories and area paths, how you structure your project determines the areas you can open up or close down. +Managing permissions for a few users individually might seem feasible, but custom security groups provide a more organized approach. They streamline the oversight of roles and their associated permissions, ensuring clarity and ease of management design and can't be altered. But, you have the flexibility to modify permissions for all other groups. -## Recommended method for granting and restricting permissions - -For maintenance purposes, we recommend you use either the built-in security groups or [custom security groups to manage permissions](add-remove-manage-user-group-security-group.md). +## Delegate tasks to specific roles -You can't change the permission settings for the Project Administrators group or the Project Collection Administrators group, which is by design. However, for all other groups, you can change the permissions. +As an administrator or organization owner, delegating administrative tasks to team members who oversee specific areas is a strategic approach. The primary built-in roles equipped with predefined permissions and role assignments include: -If you manage a few users, then you may find changing individual permissions a valid option. However, custom security groups allow you to better track roles and permissions assigned to those roles. +- **Readers:** Have read-only access to the project. +- **Contributors:** Can contribute to the project by adding or modifying content. +- **Team Administrator:** Manage team-related settings and permissions. +- **Project Administrators:** Have administrative rights over the project. +- **Project Collection Administrators:** Oversee the entire project collection and have the highest level of permissions. -## Delegate tasks to specific roles +These roles facilitate the distribution of responsibilities and streamline the management of project areas. -As an administrator or account owner, it's a good idea to delegate administrative tasks to those team members who lead or manage an area. Several of the main built-in roles that come with default permissions and role assignments are: -- Readers -- Contributors -- Team Administrator (role) -- Project Administrators -- Project Collection Administrators - -For a summary of permissions for the above roles, see [Default permissions and access](permissions-access.md), or for the Project Collection Administrators, see [Change project collection-level permissions](change-organization-collection-level-permissions.md). +For for more information, see [Default permissions and access](permissions-access.md) and [Change project collection-level permissions](change-organization-collection-level-permissions.md). To delegate tasks to other members within your organization, consider creating a custom security group and then granting permissions as indicated in the following table. @@ -90,7 +73,7 @@ To delegate tasks to other members within your organization, consider creating a :::row-end::: :::row::: :::column span="1"::: - Development lead (TFVC) + Development lead (Team Foundation Version Control (TFVC)) :::column-end::: :::column span="1"::: Manage repository and branches @@ -196,55 +179,70 @@ To delegate tasks to other members within your organization, consider creating a For an account or collection, Edit instance-level (or collection-level) information To understand the scope of these permissions, see [Permission lookup guide](permissions-lookup-guide.md). To request a change in permissions, See [Request an increase in permission levels](request-changes-permissions.md). - You can also grant permissions to manage permissions for the following objects: +In addition to assigning permissions to individuals, you can manage permissions for various objects within Azure DevOps. These objects include: - - [Set Git repository permissions](../../repos/git/set-git-repository-permissions.md) - - [Manage Git branch permissions](../../repos/git/branch-permissions.md) - - [Set TFVC repository permissions](../../repos/tfvc/set-tfvc-repository-permissions.md) - - [Administer build and release permissions](../../pipelines/policies/set-permissions.md) - - [Manage Wiki permissions](../../project/wiki/manage-readme-wiki-permissions.md). + - [Git repositories](../../repos/git/set-git-repository-permissions.md) + - [Git branches](../../repos/git/branch-permissions.md) + - [TFVC repositories](../../repos/tfvc/set-tfvc-repository-permissions.md) + - [Build and release pipelines](../../pipelines/policies/permissions.md#pipeline-permissions) + - [Wikis](../../project/wiki/manage-readme-wiki-permissions.md). :::column-end::: :::row-end::: - - -::: moniker range="azure-devops" - -## Limit user visibility to organization and project information +These links provide detailed steps and guidelines for setting up and managing permissions effectively for the respective areas in Azure DevOps. -[!INCLUDE [project-scoped-users-important-note](../../includes/project-scoped-users-important-note.md)] + -By default, users added to an organization can view all organization and project information and settings. To restrict access to only those projects that you add users to, you can enable the **Limit user visibility and collaboration to specific projects** preview feature for the organization. To enable this feature, see [Manage or enable features](../../project/navigation/preview-features.md#account-level). +::: moniker range="azure-devops" -With this feature enabled, users added to the **Project-Scoped Users** group can't view most **Organization settings** and can only connect to those projects to which they've been added. +## Limit user visibility [!INCLUDE [project-scoped-users-warning](../../includes/project-scoped-users-warning.md)] -::: moniker-end +### Organizations and projects -::: moniker range="azure-devops" +By default, users added to an organization can view all organization and project information and settings. You can restrict specific users, such as Stakeholders, Microsoft Entra users, or members of a particular security group, with the **Limit user visibility and collaboration to specific projects** preview feature for the organization. Once the feature [gets turned on](#turn-on-the-preview-feature-and-add-users-to-the-security-group), any user or group that [gets added to the **Project-Scoped Users** group](#identity-search-and-selection) is restricted in the following ways: + +- Access is confined to only the projects to which they're explicitly added. +- Views displaying lists of users, projects, billing details, usage data, and more accessed through **Organization settings** are restricted. +- The set of people or groups that appear in people-picker search selections and the ability to **@mention** people is limited. -## Limit people picker to project users and groups +### Identity search and selection -For organizations that manage their users and groups using Azure Active Directory (Azure AD), people pickers support searching all users and groups added to Azure AD, not just those users or groups added to a project. People pickers support the following Azure DevOps functions: +With Microsoft Entra ID, you can use people pickers to search for any user or group in your organization, not just the ones in your current project. People pickers support the following Azure DevOps functions: - Selection of a user identity from a work tracking identity field such as **Assigned To** - Selection of a user or group using **@mention** in a work item discussion or rich-text field, a pull request discussion, commit comments, or changeset or shelveset comments - Selection of a user or group using **@mention** from a wiki page -As shown in the following image, you simply start typing into a people picker box until you find a match to a user name or security group. - -> [!div class="mx-imgBorder"] -> ![Screenshot of people picker](../../organizations/notifications/media/at-mention/identity-selector.png) +As shown in the following image, start entering a user or security group name into a people picker box until you find a match. + + :::image type="content" source="../../organizations/notifications/media/at-mention/identity-selector.png" alt-text="Screenshot of people picker."::: -Users and groups who are added to the **Project-Scoped Users** group can only see and select users and groups in the project they're connected to from a people picker. To scope people pickers for all project members, see [Manage your organization, Limit identity search and selection](../../user-guide/manage-organization-collection.md#limit-identity-selection). +Users and groups who are added to the **Project-Scoped Users** group can only see and select users and groups in the project they're connected to from a people picker. + +### Turn on the preview feature and add users to the security group + +Do the following steps to turn on the preview feature and add users and group to the Project-Scoped Users group: + +1. Turn on the **Limit user visibility and collaboration to specific projects** [preview feature](../../project/navigation/preview-features.md) for the organization. +2. Add the users to your project as described in [Add users to a project or team](../../organizations/security/add-users-team-project.md). Users added to a team are automatically added to the project and team group. +3. Open **Organizations settings** > **Security** > **Permissions** and choose **Project-Scoped Users**. Select the **Members** tab. +4. Add all users and groups that you want to scope to the project they're added to. For more information, see [Set permissions at the project- or collection-level](../../organizations/security/change-organization-collection-level-permissions.md). + + The **Project-Scoped Users** group only appears under the **Permissions** > **Groups** when the **Limit user visibility and collaboration to specific projects** preview feature is turned on. + +All security groups in Azure DevOps are considered organization-level entities, even if they only have permissions for a specific project. This means that security groups get managed at the organization level. + +From the web portal, the visibility of some security groups might be restricted based on the user's permissions. However, you can still discover the names of all security groups within an organization by using the **azure devops** CLI tool or the REST APIs. For more information, see [Add and manage security groups](../../organizations/security/add-manage-security-groups.md). ::: moniker-end ## Restrict access to view or modify objects -Azure DevOps is designed to enable all valid users to view all objects defined in the system. You can restrict access to resources by setting the permission state to **Deny**. You can set permissions for members that belong to a custom security group or for an individual user. To learn more about how to set these types of permissions, see [Request an increase in permission levels](request-changes-permissions.md). +Azure DevOps is designed to allow all authorized users to view all defined objects within the system. However, you can tailor access to resources by setting the permission state to **Deny**. +You can set permissions for members who belong to a custom security group or for individual users. For more information, see [Request an increase in permission levels](request-changes-permissions.md). :::row::: :::column span="1"::: @@ -260,6 +258,7 @@ Azure DevOps is designed to enable all valid users to view all objects defined i :::column-end::: :::column span="1"::: View, Contribute + See [Set Git repository permissions](../../repos/git/set-git-repository-permissions.md) or [Set TFVC repository permissions](../../repos/tfvc/set-tfvc-repository-permissions.md). :::column-end::: :::row-end::: @@ -279,7 +278,7 @@ Azure DevOps is designed to enable all valid users to view all objects defined i :::column span="1"::: Edit build pipeline, View build pipeline Edit release pipeline, View release pipeline - You set these permissions at the object level. See [Set build and release permissions](../../pipelines/policies/set-permissions.md). + You set these permissions at the object level. See [Set build and release permissions](../../pipelines/policies/permissions.md#pipeline-permissions). :::column-end::: :::row-end::: :::row::: @@ -292,7 +291,7 @@ Azure DevOps is designed to enable all valid users to view all objects defined i :::column-end::: :::row-end::: - + ## Restrict modification of work items or select fields @@ -301,21 +300,19 @@ For examples that illustrate how to restrict modification of work items or selec ## Next steps > [!div class="nextstepaction"] -> [Remove user accounts](remove-users-prohibit-access.md) +> [Remove user accounts](/azure/active-directory/add-users-azure-active-directory#delete-a-user?toc=/azure/devops/organizations/security/toc.json) ## Related articles -- [Troubleshoot permissions](troubleshoot-permissions.md) -- [Rules and rule evaluation](../settings/work/rule-reference.md) -- [Default permissions and access](permissions-access.md) -- [Permission lookup guide](permissions-lookup-guide.md) +- [View default permissions and access](permissions-access.md) +- [Use the permission lookup guide](permissions-lookup-guide.md) - [Get started with permissions, access, and security groups](about-permissions.md) -- [Permissions and groups reference](permissions.md) +- [Refer to permissions and groups](permissions.md) - [Change project-level permissions](change-project-level-permissions.md) - [Change project collection-level permissions](change-organization-collection-level-permissions.md) diff --git a/docs/organizations/security/restrict-invitations.md b/docs/organizations/security/restrict-invitations.md index 4f42d4b1e71..fa713f5a8cf 100644 --- a/docs/organizations/security/restrict-invitations.md +++ b/docs/organizations/security/restrict-invitations.md @@ -8,15 +8,14 @@ ms.subservice: azure-devops-security ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 03/02/2023 +ms.date: 11/30/2023 --- -# Restrict new user invitations from Project and Team Administrators +# Restrict administrators from inviting new users [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -By default, all administrators can invite new users to their Azure DevOps organization. Disabling this policy blocks Team and Project Administrators from inviting new users. Project Collection Administrators (PCAs) can add new users to the organization, regardless of the policy status. If a user is already a member of the organization, Project and Team Administrators can add that user to a project. - +By default, all administrators can invite new users to their Azure DevOps organization. Disabling this policy prevents Team and Project Administrators from inviting new users. However, Project Collection Administrators (PCAs) can still add new users to the organization regardless of the policy status. Additionally, if a user is already a member of the organization, Project and Team Administrators can add that user to specific projects. - -::: moniker range="azure-devops" - -## Audit log - -Audit logs contain many changes that occur throughout an Azure DevOps organization. Changes occur when a user or service identity within the organization edits the state of an artifact, including changes to permissions. For more information, see [Access, export, and filter audit logs](../audit/azure-devops-auditing.md). - -::: moniker-end - -## Authentication - -Authentication verifies a user's identify based on the credentials provided when they sign into an organization in Azure DevOps. These services/servers typically integrate with and rely upon the security features provided by services such as Active Directory or Azure Active Directory. For more information, see [About security, authentication, and authorization](about-security-identity.md). - -## Authorization - -Authorization is the operations that are performed to verify that the identity that's attempting to connect to a service or server instance has the necessary permissions to access a service, feature, function, object, or method. For more information, see [About security, authentication, and authorization](about-security-identity.md). - -## Basic member - -A user account that has been granted membership to an organization in Azure DevOps instance with Basic access. For more information, see [About access levels](access-levels.md). - -[!INCLUDE [temp](../../includes/glossary-terms/collections.md)] - -## Conditional access - -Conditional access provides support for securing Azure DevOps resources backed by an Azure Active Directory (Azure AD) tenant. For example, you can enable multi-factor authentication to help protect against the risk of compromised credentials. For more information, see [Manage conditional access to Azure DevOps](../accounts/change-application-access-policies.md). - -## Inheritance - -Permissions that aren't directly allowed or denied for a user, may be inherited. For more information, see [Get started with permissions, access, and security groups](../security/about-permissions.md). - - - -## Microsoft Authentication Library - -The Microsoft Authentication Library (MSAL) enables application developers to acquire tokens from the Microsoft identity platform to authenticate users and access secured web APIs. It can be used to provide secure access to Microsoft Graph, other Microsoft APIs, third-party web APIs, or your own web API. MSAL supports many different application architectures and platforms including .NET, JavaScript, Java, Python, Android, and iOS. For more information, see the [Overview of Microsoft Authentication Library](/azure/active-directory/develop/msal-overview#languages-and-frameworks). - -## Namespace - -Each family of Azure DevOps resources (work items, Git repositories, etc.) is secured using a different namespace. Each security namespace contains zero or more ACLs. Each ACL contains a token, an inherit flag and a set of zero or more ACEs. Each ACE contains an identity descriptor, an allowed permissions bitmask and a denied permissions bitmask. - -For a list of Azure DevOps namespaces, see [Security namespace and permission reference](namespace-reference.md). - -## OAuth - -OAuth 2.0 is an industry-standard protocol for authorization. OAuth 2.0 is supported for Azure DevOps Services to authenticate REST APIs. For more information, see [Authorize access to REST APIs with OAuth 2.0](../../integrate/get-started/authentication/oauth.md). - - - - -::: moniker range="azure-devops" - -## Organization owner - -The person who created the organization or was later assigned as the organization owner. The organization owner has access to all Azure DevOps features and functions, and can grant access to others to features and functions. To look up or change organization owner, see [Change the organization owner](../accounts/change-organization-ownership.md). - -::: moniker-end - -## Personal Access Token (PAT) - -Personal access tokens (PATs) are alternate passwords that you can use to authenticate into Azure DevOps. To learn how to create and revoke PATs, see [Authenticate access with personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md). - - -## Permission - -The assignment made to a user or group to use a feature or function. Permissions are assigned to default security groups. For more information, see [Get started with permissions, access, and security groups](../security/about-permissions.md). - -## Permission state - -The state assigned to a feature or function to a user's or group's permission. Users have permission to access a feature if their permission is set to **Allow**, **Inherited Allow**, or **System Allow**. They don't have permission when the state is set to **Deny**, **Inherited deny**, **System deny**, or **Not set**. For more information, see [Get started with permissions, access, and security groups](../security/about-permissions.md). - - -## Role-based permissions - -A security model that limits actions based on membership within a role and permissions assigned to that role. For more information, see [About permissions, access, and security groups, Role-based permissions](about-permissions.md#security-roles). - -## Security group - -A method by which you can organize users and other domain objects to simplify administration of permissions and access. Azure DevOps supports many default security groups and the ability to create custom groups. For more information, see [Get started with permissions, access, and security groups](../security/about-permissions.md). - -## Service account - -An account used to monitor or manage select services, such as build or test services. - -## Service principal - -A service principal is the local representation, or application instance, of a global application object in a single tenant or directory. When an application is given permission to access resources in a tenant (upon registration or consent), a service principal object is created. For more information, see [Application and service principal objects in Azure Active Directory](/azure/active-directory/develop/app-objects-and-service-principals) and [service principal and managed identity support in Azure DevOps](../../integrate/get-started/authentication/service-principal-managed-identity.md). - -## Secure Sockets Layer (SSL) - -SSL is a protocol used to strengthen the security of cloud-hosted and on-premises applications by configuring it to use Hypertext Transfer Protocol Secure (HTTPS) with Secure Sockets Layer (SSL). - -SSL is always used to protect Azure DevOps data. For more information, see [Data Protection Overview](./data-protection.md). - -For on-premises deployments, SSL is optional. For more information, see [Setting up HTTPS with Secure Sockets Layer (SSL)](/azure/devops/server/admin/setup-secure-sockets-layer). - -## Stakeholder - -A user account that has been granted membership to an organization in an Azure DevOps instance with Stakeholder access. With Stakeholder access, you can add and modify work items, check project status, manage pipelines, and view and manage dashboards. For more information, see [Get started as a Stakeholder](get-started-stakeholder.md). - -## Team group - -A security group that is defined when a team is created and automatically populated with members as they're added to the team. - -::: moniker range="azure-devops" - -## Tenant - -An Azure Active Directory used to manage access or billing. For more information, see [Change Azure AD tenant](../accounts/change-organization-location.md) - -::: moniker-end - -## Token - -Tokens are arbitrary strings representing resources in Azure DevOps. Token format differs per resource type, however hierarchy and separator characters are common between all tokens. For details, see [REST API Security](/rest/api/azure/devops/security). - -*Each family of Azure DevOps resources (work items, Git repositories, and so on) is secured using a different namespace. Each security namespace contains zero or more ACLs. Each ACL contains a token, an inherit flag and a set of zero or more ACEs. Each ACE contains an identity descriptor, an allowed permissions bitmask and a denied permissions bitmask*. - -For Azure DevOps Services, you can manage tokens and namespaces using the **az devops security permission** commands. For details, see [Manage tokens and namespaces](manage-tokens-namespaces.md). - -For Azure DevOps Server, see [Use TFSSecurity to manage groups and permissions for Azure DevOps](/azure/devops/server/command-line/tfssecurity-cmd). - - - - -## Valid users - -Valid users are users that Azure DevOps recognizes as being able to connect to the account or a project. When you add accounts of users directly to a built-in group or through a Windows, Active Directory, or Azure Active Directory group, they're automatically added to one of the valid user groups. For more information, see [Get started with permissions, access, and security groups](about-permissions.md). - - - -## Related articles - -- [Permissions lookup guide](permissions-lookup-guide.md) -- [REST API Security](/rest/api/azure/devops/security) diff --git a/docs/organizations/security/security-overview.md b/docs/organizations/security/security-overview.md new file mode 100644 index 00000000000..9aef6027dc4 --- /dev/null +++ b/docs/organizations/security/security-overview.md @@ -0,0 +1,214 @@ +--- +title: Make your Azure DevOps secure +titleSuffix: Azure DevOps +description: An overview of actions to ensure the security of your Azure DevOps environment, data, and users. +ms.topic: overview +ms.subservice: azure-devops-security +ms.author: chcomley +author: chcomley +monikerRange: '<= azure-devops' +ms.date: 04/23/2025 +--- + +# Make your Azure DevOps secure + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +When you're handling information and data, especially in a cloud-based solution like Azure DevOps Services, security should be your top priority. While Microsoft ensures the security of the underlying cloud infrastructure, it's your responsibility to configure security within Azure DevOps. This article provides an overview of necessary security-related configurations to protect your Azure DevOps environment against threats and vulnerabilities. + +## Secure your network + +Securing your network is crucial when you're working with Azure DevOps to protect your data and resources from unauthorized access and potential threats. Implement network security measures to help ensure that only trusted sources can access your Azure DevOps environment. To secure your network when you're working with Azure DevOps, do the following actions: + +- **Set up IP allowlisting:** Restrict access to specific IP addresses to allow traffic only from trusted sources, reducing the attack surface. For instructions, see [Set up IP allowlisting](allow-list-ip-url.md). +- **Use data encryption:** Always encrypt data in transit and at rest. Secure communication channels using protocols like HTTPS. For more information, see [Use data encryption](/azure/security/fundamentals/encryption-overview). +- **Validate certificates:** Ensure certificates are valid and issued by trusted authorities when establishing connections. For more information, see [Validate certificates](/azure/security/fundamentals/azure-ca-details?tabs=root-and-subordinate-cas-list). +- **Implement Web Application Firewalls (WAFs):** Filter, monitor, and block malicious web-based traffic with WAFs for an extra layer of protection against common attacks. For more information, see [Implement Web Application Firewalls (WAFs)](/azure/web-application-firewall/). +- **Enable network security groups (NSGs):** Use NSGs to control inbound and outbound traffic to Azure resources, ensuring only authorized traffic is allowed. For more information, see the [Network security groups (NSGs) overview](/azure/virtual-network/network-security-groups-overview). +- **Use Azure Firewall:** Deploy Azure Firewall to provide a centralized network security policy across multiple Azure subscriptions and virtual networks. For more information, see the [Azure Firewall overview](/azure/firewall/overview). +- **Monitor network traffic:** Use Azure Network Watcher to monitor and diagnose network issues, ensuring the security and performance of your network. For more information, see the [Azure Network Watcher overview](/azure/network-watcher/network-watcher-monitoring-overview). +- **Implement DDoS protection:** Enable Azure DDoS Protection to safeguard your applications from distributed denial-of-service (DDoS) attacks. For more information, see [Azure DDoS Protection](/azure/ddos-protection/ddos-protection-overview). + +For more information, see [Application management best practices](/azure/active-directory/manage-apps/application-management-fundamentals). + +## Secure your Azure DevOps environment + +To ensure that your Azure DevOps environment complies with industry standards and regulations, implement security measures and policies. Compliance with standards such as ISO/IEC 27001, SOC 1/2/3, and General Data Protection Regulation (GDPR) helps protect your environment and maintain trust with your users. + +- **Ensure compliance with industry standards:** Azure DevOps complies with various industry standards and regulations, such as ISO/IEC 27001, SOC 1/2/3, and GDPR. Ensure your environment adheres to these standards. +- **Enforce policies:** Implement policies to enforce security best practices across your organization. This action includes requiring code reviews and enforcing [branch policies](../../repos/git/branch-policies.md), [compliance policies for pipelines](/azure/governance/policy/tutorials/policy-devops-pipelines), and [security policies](../accounts/change-application-access-policies.md). +- **Onboard to Component Governance for CI/CD for the following reasons:** + - Security vulnerability detection: Alerts you to known vulnerabilities in open-source components. + - License compliance: Ensures components comply with your organization's licensing policies. + - Policy enforcement: Ensures only approved versions are used. + - Visibility with tracking: Provides visibility into components across repositories for easier management. + +### Manage project and organization-level permissions + +- **Limit access to projects and repos:** Reduce the risk of leaking sensitive information and deploying insecure code by limiting access to projects and repositories. Use built-in or custom security groups manage permissions. For more information, see [Limit access to projects and repositories](restrict-access.md). +- **Disable *“Allow public projects”*:** In your organization’s policy settings, disable the option to create public projects. Switch project visibility from public to private as needed. Users who never signed in have read-only access to public projects, while signed-in users can be granted access to private projects and make permitted changes. For more information, see [Change application connection and security policies for your organization](../accounts/change-application-access-policies.md). +- **Restrict organization creation:** Prevent users from creating new projects to maintain control over your environment. For more information, see [Restrict organization creation via Microsoft Entra tenant policy](../accounts/azure-ad-tenant-policy-restrict-org-creation.md). + +## Use security features and tools + +The following security features and tools can help you monitor, manage, and enhance the security of your projects: + +- **Use OAuth instead of personal access tokens (PATs):** Use OAuth flow instead of PATs and don't use personal GitHub accounts as service connections. For more information, see the [OAuth overview](../../integrate/get-started/authentication/oauth.md). +- **Use code scanning and analysis:** Utilize tools like [Microsoft Defender](https://apps.microsoft.com/detail/9p6pmztm93lr?hl=en-US&gl=US) to scan your code for vulnerabilities, secrets, and misconfigurations. This action helps identify and remediate security issues early in the development process. +- **Use Git Credential Manager:** Support [two-factor authentication with GitHub repositories](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) and authenticate to Azure Repos. For more information, see [Set up Git Credential Manager](../../repos/git/set-up-credential-managers.md). +- **Use Azure DevOps Credential Scanner (CredScan) for GitHub:** When using a managed identity isn't an option, ensure that credentials get stored in secure locations such as Azure Key Vault, instead of embedding them into the code and configuration files. Implement Azure DevOps Credential Scanner to identify credentials within the code. For more information, see [Getting started with CredScan](https://secdevtools.azurewebsites.net/helpcredscan.html). +- **Use native secret scanning for GitHub:** When using a managed identity isn't an option, ensure that secrets get stored in secure locations such as Azure Key Vault, instead of embedding them into the code and configuration files. Use the native secret scanning feature to identify secrets within the code. For more information, see [About secret scanning](https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning). + +For more information, see the [GitHub advanced security overview](../../repos/security/github-advanced-security-security-overview.md). + +## Secure your services + +To ensure the security and integrity of your services in Azure DevOps, implement security measures for each service. These measures include setting permissions, managing access, and using security features specific to each service. + +- **Secure Azure Boards:** Protect your work tracking data by setting appropriate permissions and managing access levels. + - [Set work tracking permissions](set-permissions-access-work-tracking.md) + - [Set permissions for queries and query folders](../../boards/queries/set-query-permissions.md) + - [Manage team administrators](../settings/add-team-administrator.md) + - [Learn about default permissions and access levels for Azure Boards](../../boards/get-started/permissions-access-boards.md) +- **Secure Azure Repos:** Ensure the security of your code repositories by configuring Git settings, branch permissions, and policies. + - [Learn about default Git settings and policies](default-git-permissions.md) + - [Set permissions for a specific branch](../../repos/git/branch-permissions.md) + - [Set branch policies](../../repos/git/branch-policies.md) + - [Configure GitHub Advanced Security for Azure DevOps](../../repos/security/configure-github-advanced-security-features.md) + - [Learn about GitHub Advanced Security](../../repos/security/github-advanced-security-security-overview.md) +- **Secure Azure Pipelines:** Safeguard your CI/CD processes by setting permissions, using security templates, and securing agents and containers. + - [Learn about Azure Pipelines security](../../pipelines/security/overview.md) + - [Add users to Azure Pipelines](../../pipelines/policies/set-permissions.md) + - [Use templates for security](../../pipelines/process/templates.md) + - [Secure agents, projects, and containers](../../pipelines/security/misc.md) + - [Secure access to Azure Repos from pipelines](../../pipelines/security/secure-access-to-repos.md) + - [Secure pipelines resources](../../pipelines/security/resources.md) + - [Determine your approach for securing YAML pipelines](../../pipelines/security/approach.md) + - [Protect secrets in Azure Pipelines](../../pipelines/security/secrets.md) +- **Secure Azure Test Plans:** Ensure that your team has the appropriate access to efficiently manage and execute test plans. + - [Learn default manual test and access permissions](../../test/manual-test-permissions.md) + - [Set permissions and access for testing](set-permissions-access-test.md) +- **Secure Azure Artifacts:** Manage access to your packages and control who can interact with them. + - [Manage Azure Artifacts permissions](../../artifacts/feeds/feed-permissions.md) + - [Set feed scopes](../../artifacts/feeds/project-scoped-feeds.md) + +## Control access + +Provide the minimum necessary [permissions](about-permissions.md) and [access levels](access-levels.md) to ensure that only authorized individuals and services can access sensitive information and perform critical actions. This practice helps to minimize the risk of unauthorized access and potential data breaches. + +Regularly review and update these settings to adapt to changes in your organization, such as role changes, new hires, or departures. Implementing a periodic [audit](#enable-and-review-auditing-events) of permissions and access levels can help identify and rectify any discrepancies, ensuring that your security posture remains robust and aligned with best practices. + +### Scope permissions + +To ensure secure and efficient management of permissions, properly scope permissions within your Azure DevOps environment. Scoping permissions involves defining and assigning the appropriate level of access to users and groups based on their roles and responsibilities. This practice helps to minimize the risk of unauthorized access and potential data breaches by ensuring that only authorized individuals have access to sensitive information and critical actions. + +To scope permissions effectively, do the following actions: + +- **Disable inheritance:** Avoid inheritance, preventing unintended access. Inheritance can inadvertently grant permissions to users who shouldn't have them, due to its allow-by-default nature. Carefully manage and explicitly set permissions to ensure that only the intended users have access. For more information, see [Permissions inheritance](about-permissions.md#permission-inheritance). +- **Segment environments:** Use separate Azure accounts for different environments, such as Development, Testing, and Production, to enhance security and prevent conflicts. This approach minimizes the risk of resource conflicts and data contamination between environments and allows for better management and isolation of resources. For more information, see [Azure Landing Zone](/azure/cloud-adoption-framework/ready/landing-zone/). +- **Control access and ensure compliance:** Use Azure Policy to restrict access to unused Azure regions and services, ensuring compliance with organizational standards. This action helps enforce best practices and maintain a secure environment by preventing unauthorized access and usage. For more information, see the [Azure Policy overview](/azure/governance/policy/overview). +- **Implement Azure role-based control (ABAC):** Use ABAC with properly tagged resources, limiting unauthorized access. This action ensures that access permissions get granted based on specific attributes, enhancing security by preventing unauthorized resource creation and access. For more information, see [Implement Azure role-based control (ABAC)](/azure/role-based-access-control/conditions-overview). +- **Use security groups:** Use security groups to efficiently manage permissions for multiple users. This method simplifies granting and revoking access compared to assigning permissions individually and ensures consistency and easier management across your organization. + - Use Microsoft Entra ID, Active Directory, or Windows security groups when you're managing lots of users. + - Take advantage of built-in roles and default to Contributor for developers. Admins get assigned to the Project Administrator security group for elevated permissions, allowing them to configure security permissions. + - Keep groups as small as possible, restricting access. + - For more information, see [Manage security groups](add-manage-security-groups.md). +- **Choose the right authentication method:** Set up secure authentication methods and manage authorization policies. For more information, see the [Choose the right authentication method](#choose-the-right-authentication-method) section in this article and [Authentication methods](about-security-identity.md). +- **Integrate with Microsoft Entra ID:** Use Microsoft Entra ID for unified identity management. For more information, see [Connect your organization to Microsoft Entra ID](../accounts/connect-organization-to-azure-ad.md). + - To enhance security for built-in administrator groups, consider implementing just-in-time access using a Microsoft Entra [Privileged Identity Management (PIM) group](/azure/active-directory/privileged-identity-management/concept-pim-for-groups). This approach allows you to grant elevated permissions only when needed, reducing the risk associated with permanent access. For more information, see [Configure just-in-time-access for admin groups](../accounts/manage-azure-active-directory-groups.md#configure-just-in-time-access-for-admin-groups). +- **Enable Microsoft Entra multifactor authentication (MFA):** Add an extra layer of security with MFA. For more information, see [Enable Microsoft Entra multifactor authentication](/entra/identity/authentication/tutorial-enable-azure-mfa). +- **Change security policies:** Manage security policies, including conditional access. for more information, see [Change application connection & security policies for your organization](../accounts/change-application-access-policies.md). + +For more information about permissions, see the following articles: +- [Permissions and role lookup guide](permissions-lookup-guide.md) +- [Set individual permissions](/azure/devops/organizations/security/request-changes-permissions) +- [Permissions, security groups, and service accounts reference](permissions.md) + + + + +### Choose the right authentication method + +When you're choosing the appropriate authentication method for your Azure DevOps environment, consider the security and management benefits of different options. Using secure authentication methods helps protect your resources and ensures that only authorized users and services can access your Azure DevOps environment. Consider using service principals, managed identities, and Microsoft Entra to enhance security and streamline access management. + +- **Use service principals:** Represent security objects within a Microsoft Entra application. Define what an application can do in a given tenant. Set up during application registration in the Azure portal. Configure to access Azure resources, including Azure DevOps. Useful for apps needing specific access and control. +- **Use managed identities:** Similar to an application’s service principal. Provide identities for Azure resources. Allow services supporting Microsoft Entra authentication to share credentials. Azure handles credential management and rotation automatically. Ideal for seamless sign-in details management. +- **Use Microsoft Entra ID:** + - Create a single plane for identity by connecting Azure DevOps to Microsoft Entra ID. This consistency reduces confusion and minimizes security risks from manual configuration errors. + - [Access your organization with Microsoft Entra ID](../accounts/access-with-azure-ad.md) and assign different roles and permissions to specific groups across various resource scopes. This action implements fine-grained governance, ensures controlled access, and aligns with security best practices. + - Use [Conditional Access Policies](../accounts/change-application-access-policies.md), which define access rules based on conditions like [location, device, or risk level](/azure/active-directory/conditional-access/howto-conditional-access-policy-location). + +### Manage external guest access + +To ensure the security and proper management of external guest access, implement specific measures that control and monitor how external users interact with your Azure DevOps environment. External guest access can introduce potential security risks if not managed properly. By following these actions, you can minimize these risks and ensure that external guests have the appropriate level of access without compromising the security of your environment. + +- **Block external guest access:** Disable the ["Allow invitations to be sent to any domain" policy](/azure/active-directory/external-identities/allow-deny-list) to prevent external guest access if there's no business need for it. +- **Use distinct emails or UPNs:** Use different email addresses or user principal names (UPNs) for personal and business accounts to eliminate ambiguity between personal and work-related accounts. +- **Group external guest users:** Place all external guest users in a single Microsoft Entra group and [manage permissions for this group appropriately](../accounts/assign-access-levels-by-group-membership.md). Remove direct assignments to ensure group rules apply to these users. +- **Reevaluate rules regularly:** Regularly review rules on the Group rules tab of the Users page. Consider any group membership changes in Microsoft Entra ID that might affect your organization. Microsoft Entra ID can take up to 24 hours to update dynamic group membership, and rules are automatically reevaluated every 24 hours and whenever a group rule changes. + +For more information, see [B2B guests in the Microsoft Entra ID](/azure/active-directory/external-identities/delegate-invitations). + +### Implement Zero Trust + +To enhance security, adopt Zero Trust principles across your DevOps processes. This approach ensures that every access request is thoroughly verified, regardless of its origin. Zero Trust operates on the principle of "never trust, always verify," meaning that no entity, whether inside or outside the network, is trusted by default. By implementing Zero Trust, you can significantly reduce the risk of security breaches and ensure that only authorized users and devices can access your resources. + +- **Embrace the Zero Trust approach:** Implement [Zero Trust](/azure/security/fundamentals/zero-trust) principles to fortify your [DevOps platform](/security/zero-trust/develop/secure-devops-platform-environment-zero-trust), safeguard your [development environment](/security/zero-trust/develop/secure-dev-environment-zero-trust), and integrate Zero Trust seamlessly into your [developer workflows](/security/zero-trust/develop/embed-zero-trust-dev-workflow). Zero Trust helps to protect against lateral movement within the network, ensuring that even if there's a compromised part of the network, the threat is contained and can't spread. + +For more information, see the [Zero Trust Assessment guide](https://microsoft.github.io/zerotrustassessment/guide). + +### Remove users + +To ensure that only active and authorized users have access to your Azure DevOps environment, regularly review and manage user access. Removing inactive or unauthorized users helps maintain a secure environment and reduces the risk of potential security breaches. By following these actions, you can ensure that your Azure DevOps environment remains secure and that only the necessary individuals have access. + +- **Remove inactive users from Microsoft accounts (MSAs):** Directly remove inactive users from your organization if they're using MSAs. You can't create queries for work items assigned to removed MSA accounts. For more information, see [Remove users from your organization](../accounts/delete-organization-users.md). +- **Disable or delete Microsoft Entra user accounts:** If connected to Microsoft Entra ID, disable or delete the Microsoft Entra user account while keeping the Azure DevOps user account active. This action allows you to continue querying work item history using your Azure DevOps user ID. +- **Revoke user PATs:** Ensure secure management of these critical authentication tokens by regularly reviewing and revoking any existing user PATs. For more information, see [Revoke user PATs for administrators](../accounts/admin-revoke-user-pats.md). +- **Revoke special permissions granted to individual users:** Audit and revoke any special permissions granted to individual users to ensure alignment with the principle of least privilege. +- **Reassign work from removed users:** Before removing users, reassign their work items to current team members to distribute the load effectively. + +## Scope service accounts + +Service accounts are used to run automated processes and services, and they often have elevated permissions. By properly scoping and managing service accounts, you can minimize security risks and ensure that these accounts are used appropriately. + +- **Create single-purpose service accounts:** Each service should have its dedicated account to minimize risk. Avoid using regular user accounts as [service accounts](permissions.md#service-accounts). +- **Use Azure Resource Manager:** Authenticate with Azure resources using workload identity federation with either an app registration or managed identity instead of using an app registration with a secret. For more information, see [Use Azure Resource Manager](../../pipelines/library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-that-uses-workload-identity-federation). +- **Identify and disable unused service accounts:** Regularly review and identify accounts no longer in use. Disable unused accounts before considering deletion. +- **Restrict privileges:** Limit service account privileges to the minimum necessary. Avoid interactive sign-in rights for service accounts. +- **Use separate identities for report readers:** If using domain accounts for service accounts, use a different identity for report readers to [isolate permissions and prevent unnecessary access](/azure/devops/server/admin/service-accounts-dependencies?view=azure-devops&preserve-view=true). +- **Use local accounts for workgroup installations:** When installing components in a workgroup, use local accounts for user accounts. Avoid domain accounts in this scenario. +- **Use service connections:** Use service connections whenever possible to securely connect to services without passing secret variables directly to builds. Restrict connections to specific use cases. for more information, see the [Scope service connections](#scope-service-connections) section in this article. +- **Monitor service account activity:** Implement auditing and create [audit streams](../audit/auditing-streaming.md) to monitor service account activity. + +## Scope service connections + +To ensure secure and efficient access to Azure resources, properly scope service connections. Service connections allow Azure DevOps to connect to external services and resources, and by scoping these connections, you can limit access to only the necessary resources and reduce the risk of unauthorized access. + +- **Limit access:** Limit access by scoping your [Azure Resource Manager](/azure/azure-resource-manager/management/overview) service connections to specific resources and groups. Don't grant broad contributor rights across the entire Azure subscription. +- **Use Azure Resource Manager:** Authenticate with Azure resources using workload identity federation with either an app registration or managed identity instead of using an app registration with a secret. For more information, see [Create an Azure Resource Manager service connection that uses workload identity federation](../../pipelines/library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-that-uses-workload-identity-federation). +- **Scope resource groups:** Ensure resource groups contain only the Virtual Machines (VMs) or resources needed for the build process. +- **Avoid classic service connections:** Opt for modern Azure Resource Manager service connections instead of classic ones, which lack scoping options. +- **Use purpose-specific team service accounts:** Authenticate service connections using purpose-specific team service accounts to maintain security and control. + +For more information, see [Common service connection types](../../pipelines/library/service-endpoints.md). + +## Enable and review auditing events + +To enhance security and monitor usage patterns within your organization, enable and regularly review auditing events. Auditing helps track user actions, permissions changes, and security incidents, allowing you to identify and address potential security issues promptly. + +- **Enable auditing:** Track and view events related to user actions, permissions, changes, and security incidents. For more information, see [Enable or disable auditing](../audit/azure-devops-auditing.md#enable-and-disable-auditing). +- **Review audit events regularly:** Regularly review audit logs to monitor user activities and detect any suspicious behavior. Look for unexpected usage patterns, especially by administrators and other users. This action helps identify potential security breaches and takes corrective actions. For more information, see [Review audit log](../audit/azure-devops-auditing.md#review-audit-log) and [Auditing events](../audit/auditing-events.md). +- **Configure security alerts:** Configure alerts to notify you of any security incidents or policy violations. This action ensures timely response to potential threats. + +## Protect your data + +To ensure the security and integrity of your data, implement data protection measures. Protecting your data involves encryption, backup, and recovery strategies to safeguard against data loss and unauthorized access. + +- **Protect your data:** Protect your data by using encryption, backup, and recovery strategies. For more information, see [Data protection](data-protection.md). +- **Add IPs and URLs to allowlist:** If your organization is secured with a firewall or proxy server, add IPs and URLs to the allowlist. For more information, see [Allowed IP addresses and domain URLs](allow-list-ip-url.md). + +## Related articles + +- [Data locations for Azure DevOps](data-location.md) +- [Microsoft Security Development Lifecycle](https://www.microsoft.com/sdl/) +- [Azure Trust Center](https://azure.microsoft.com/support/trust-center/) diff --git a/docs/organizations/security/security-tools-reference.md b/docs/organizations/security/security-tools-reference.md deleted file mode 100644 index 22a98d1a212..00000000000 --- a/docs/organizations/security/security-tools-reference.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: Security and permission management tools -titleSuffix: Azure DevOps -description: Learn about the available tools to manage security and permissions for Azure DevOps -ms.subservice: azure-devops-security -ms.author: chcomley -author: chcomley -ms.topic: overview -monikerRange: '<= azure-devops' -ms.date: 04/04/2022 ---- - -# Security and permission management tools for Azure DevOps - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -While you set most permissions through the web portal, you can use other tools to manage security groups and permissions. For permissions that aren't available to manage through the web portal,you have the option to manage them using a command line tool. - -To learn more about permissions not available through a user interface, see the [Security namespace and permission reference, Internal namespaces and permissions](namespace-reference.md#internal). - - -[!INCLUDE [version-selector-minimize](../../includes/version-selector-minimize.md)] - -Additional options include the following tools: - -::: moniker range="azure-devops" - -- Manage security groups using [az devops security CLI](add-manage-security-groups.md) -- Manage permissions using [az devops permissions CLI](manage-tokens-namespaces.md) -- [Tf Team Foundation Version Control (TFVC) permission command-line tool](../../repos/tfvc/permission-command.md) -- [Tf git permission command-line tool](../../repos/tfvc/git-permission-command.md) -- [Security REST API commands](/rest/api/azure/devops/security/) - -::: moniker-end - -::: moniker range="< azure-devops" - -- [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd) -- [Tf Team Foundation Version Control (TFVC) permission command-line tool](../../repos/tfvc/permission-command.md) -- [Tf git permission command-line tool](../../repos/tfvc/git-permission-command.md) -- [Security REST API commands](/rest/api/azure/devops/security/) - -::: moniker-end - -::: moniker range="< azure-devops" - -You manage server-level permissions and security groups through the [Team Foundation Administration Console](/azure/devops/server/admin/add-administrator), as well as a few select collection-level permissions. - -::: moniker-end - -You can use the tools listed in the following table to set permissions. Links in the table connect you to the article for setting permissions through the web portal. - -::: moniker range="azure-devops" - -| Permission level | Web portal security pages | az devops CLI | Tf CLI | -|------------------|:---------------------------:|:--------------:|:---------------------:| -| [Add users to an organization](../accounts/add-organization-users.md) | ✔️ | ✔️ | | -| [Organization-level, auditing, enterprise policies, process, workspaces](change-organization-collection-level-permissions.md) | ✔️ | ✔️ | | -| [Project-level, test management, create tags](change-project-level-permissions.md) | ✔️ | ✔️ | | -| [Git repository](../../repos/git/set-git-repository-permissions.md) | ✔️ | ✔️ | ✔️ | -| [Team Foundation Version Control](../../repos/tfvc/set-tfvc-repository-permissions.md) | ✔️ | ✔️ | ✔️ | -| [Builds, Task groups](../../pipelines/policies/permissions.md#set-pipeline-permissions) | ✔️ | ✔️ | | -| [Build resources](change-organization-collection-level-permissions.md) | ✔️ | ✔️ | | -| [Pipeline security roles](../../pipelines/policies/permissions.md) | ✔️ | ✔️ | | -| [Releases](../../pipelines/policies/permissions.md#set-release-permissions) | ✔️ | ✔️ | | -| [Area path (CSS)](set-permissions-access-work-tracking.md#set-permissions-area-path) | ✔️ | ✔️ | | -| [Iteration path](set-permissions-access-work-tracking.md#set-permissions-area-path) | ✔️ | ✔️ | | -| [Delivery plans](set-permissions-access-work-tracking.md#plan-permissions) | ✔️ | ✔️ | | -| [Work item query](set-permissions-access-work-tracking.md#work-item-queries) | ✔️ | ✔️ | | -| [Work item tags](set-permissions-access-work-tracking.md#tags) | ✔️ | ✔️ | | -| [Analytics views](../../report/powerbi/analytics-security.md) | ✔️ | ✔️ | | -| [Dashboards](../../report/dashboards/dashboard-permissions.md) | ✔️ | ✔️ | | -| [Notifications or alerts](permissions.md#alerts) | | ✔️ | | - -::: moniker-end - - -::: moniker range="> tfs-2018 < azure-devops" - -| Permission level | Web portal security pages | TFSSecurity CLI | Tf CLI | -|---------------------------|:-------------------:|:-----------:|:-------------------:| -| [Add users to a server instance](../accounts/add-organization-users.md) | ✔️ | ✔️ | | -| [Collection-level, process, workspaces](change-organization-collection-level-permissions.md) | ✔️ | ✔️ | | -| [Project-level, test management, create tags](change-project-level-permissions.md) | ✔️ | ✔️ | | -| [Git repository](../../repos/git/set-git-repository-permissions.md) | ✔️ | ✔️ | ✔️ | -| [Team Foundation Version Control](../../repos/tfvc/set-tfvc-repository-permissions.md) | ✔️ | ✔️ | ✔️ | -| [Builds](../../pipelines/policies/permissions.md#set-pipeline-permissions) | ✔️ | ✔️ | | -| [Build resources](change-organization-collection-level-permissions.md) | ✔️ | ✔️ | | -| [Pipeline security roles](../../pipelines/policies/permissions.md) | ✔️ | ✔️ | | -| [Releases](../../pipelines/policies/permissions.md#set-release-permissions) | ✔️ | ✔️ | | -| [Area path](set-permissions-access-work-tracking.md#set-permissions-area-path) | ✔️ | ✔️ | | -| [Iteration path](set-permissions-access-work-tracking.md#set-permissions-area-path) | ✔️ | ✔️ | | -| [Delivery plans](set-permissions-access-work-tracking.md#plan-permissions) | ✔️ | ✔️ | | -| [Work item query](set-permissions-access-work-tracking.md#work-item-queries) | ✔️ | ✔️ | | -| [Work item tags](set-permissions-access-work-tracking.md#tags) | ✔️ | ✔️ | | -| [Analytics views](../../report/powerbi/analytics-security.md) | ✔️ | ✔️ | | -| [Dashboards](../../report/dashboards/dashboard-permissions.md) | ✔️ | ✔️ | | -| [Notifications or alerts](permissions.md#alerts) | ✔️ | ✔️ | | - - -::: moniker-end - -::: moniker range="tfs-2018" - -| Permission level | Web portal security pages | TFSSecurity CLI | Tf CLI | -|---------------------------|:-------------------:|:-----------:|:-------------------:| -| [Add users to a server instance](../accounts/add-organization-users.md) | ✔️ | ✔️ | | -| [Collection-level, workspaces](change-organization-collection-level-permissions.md) | ✔️ | ✔️ | | -| [Project-level, test management, create tags](change-project-level-permissions.md) | ✔️ | ✔️ | | -| [Git repository](../../repos/git/set-git-repository-permissions.md) | ✔️ | ✔️ | ✔️ | -| [Team Foundation Version Control](../../repos/tfvc/set-tfvc-repository-permissions.md) | ✔️ | ✔️ | ✔️ | -| [Builds](../../pipelines/policies/permissions.md#set-pipeline-permissions) | ✔️ | ✔️ | | -| [Build resources](change-organization-collection-level-permissions.md) | ✔️ | ✔️ | | -| [Pipeline security roles](../../pipelines/policies/permissions.md) | ✔️ | ✔️ | | -| [Releases](../../pipelines/policies/permissions.md#set-release-permissions) | ✔️ | ✔️ | | -| [Area path (CSS)](set-permissions-access-work-tracking.md#set-permissions-area-path) | ✔️ | ✔️ | | -| [Iteration path](set-permissions-access-work-tracking.md#set-permissions-area-path) | ✔️ | ✔️ | | -| [Delivery plans](set-permissions-access-work-tracking.md#plan-permissions) | ✔️ | ✔️ | | -| [Work item query](set-permissions-access-work-tracking.md#work-item-queries) | ✔️ | ✔️ | | -| [Work item tags](set-permissions-access-work-tracking.md#tags) | ✔️ | ✔️ | | -| [Dashboards](../../report/dashboards/dashboard-permissions.md) | ✔️ | ✔️ | | -| [Notifications or alerts](permissions.md#alerts) | ✔️ | ✔️ | | - -::: moniker-end - - -::: moniker range="<= azure-devops-2020" - -## Setting permissions for SQL Server reports - -For information about how to set permissions in Reporting Services, -see [Grant permissions to view or create SQL Server reports in TFS](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports). -::: moniker-end - - -## Related articles - -::: moniker range="azure-devops" - -- [Change project-level permissions](change-project-level-permissions.md) -- [Add users to a project or team](add-users-team-project.md) -- [Add and manage security groups CLI](add-manage-security-groups.md) -- [Manage permissions CLI](manage-tokens-namespaces.md) -- [Permissions and groups reference](permissions.md) -- [Security namespace and permission reference](namespace-reference.md) -- [Troubleshoot permissions](troubleshoot-permissions.md) -::: moniker-end - - -::: moniker range="< azure-devops" - -- [Change project-level permissions](change-project-level-permissions.md) -- [Add users to a project or team](add-users-team-project.md) -- [Team Foundation Administration Console](/azure/devops/server/admin/add-administrator) -- [Permissions and groups reference](permissions.md) -- [Security namespace and permission reference](namespace-reference.md) -- [Troubleshoot permissions](troubleshoot-permissions.md) -::: moniker-end diff --git a/docs/organizations/security/set-object-level-permissions.md b/docs/organizations/security/set-object-level-permissions.md index 6d9567fbf18..baa4de71b54 100644 --- a/docs/organizations/security/set-object-level-permissions.md +++ b/docs/organizations/security/set-object-level-permissions.md @@ -8,7 +8,7 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 07/15/2024 --- # Set object-level permissions @@ -19,204 +19,76 @@ As you manage security for your organization, you can set permissions at the org The following items are considered objects: -- General: Dashboards, Analytic views, Wikis, and notifications -- Boards: Area Paths, Iteration Paths, Shared queries and query folders, and more -- Pipelines: Build and release pipelines, deployment groups, task groups, and more -- Repos: Git repositories and branches, TFVC folders or branches -- Artifacts: Artifacts and feeds +- **General**: Dashboards, Analytic views, Wikis, and notifications +- Azure Boards: Area Paths, Iteration Paths, Shared queries and query folders, and more +- **Azure Pipelines**: Build and release pipelines, deployment groups, task groups, and more +- **Azure Repos**: Git repositories and branches, TFVC folders or branches +- **Azure Artifacts**: Artifacts and feeds -Work items, work item tags, Git repository tags, test plans, test suites, test cases, and other test artifacts aren't objects, but are subject to the security settings or permissions, typically set at the project level or for an area path. +Work items, tags, test plans, and other test artifacts are subject to the security settings typically set at the project level or for an area path. -To set most object-level permissions, you must be a member of the Project Administrators group, or granted explicit permission through the individual object security dialog. Any permissions granted to Project Administrators are also granted to members of the Project Collection Administrators group. +## Prerequisites + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | Member of the **Project Administrators** group or explicit permissions through the individual object security dialog.| > [!NOTE] > TFVC only supports a single repository per project. You can set permissions for the repository or repo folders/branches, which inherit from the repo. -For more information, see [Security concepts](quick-reference-index-security.md#concepts) and [Security tasks](quick-reference-index-security.md#tasks). - ## Open the permissions dialog for an object section -There are various ways to get to the Permissions dialog for an object. The simplest way is to start from the object, and then select **More** ... > **Security**. +To access the Permissions dialog for an object, follow these steps: +1. Go to the specific object. +2. Select **More** `...`. +3. Select **Security** from the dropdown menu. :::image type="content" source="media/permissions-dialog.png" alt-text="Screenshot showing how to get to permission settings for an object."::: > [!NOTE] -> Some objects, such as repositories and Analytics views, require Basic access or higher levels. For more information, see [Access levels](access-levels.md). +> Some objects, such as repositories and Analytics views, require at least Basic access levels. For more information, see [Access levels](access-levels.md). ## Set permissions for Dashboards, Wikis, and Analytic views You can set permissions at the project-level and organization/collection-level for some general items, such as creating, deleting, and renaming projects. The following table provides information about setting permissions at the object-level for Dashboards, Wiki, and Analytic views. -:::row::: - :::column span="1"::: - **Object** - :::column-end::: - :::column span="1"::: - **Default group membership** - :::column-end::: - :::column span="1"::: - **How to access security** - :::column-end::: - :::column span="1"::: - **Inherited?** - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Dashboards](../../report/dashboards/dashboard-permissions.md) - :::column-end::: - :::column span="1"::: - Contributor - :::column-end::: - :::column span="1"::: - Open **Dashboards**, select the area path, and then **More** ... > **Security**. - :::column-end::: - :::column span="1"::: - ✔️ (project settings for team dashboard) - :::column-end::: -:::row-end::: -::: moniker range=">= azure-devops-2019" -:::row::: - :::column span="1"::: - [Wiki](../../project/wiki/manage-readme-wiki-permissions.md) - :::column-end::: - :::column span="1"::: - Contributor - :::column-end::: - :::column span="1"::: - Open the wiki, choose **More** ... > **Wiki security**. For more information, see [Manage Wiki permissions](../../project/wiki/manage-readme-wiki-permissions.md). - :::column-end::: - :::column span="1"::: - no - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Analytic views](../../report/powerbi/analytics-security.md) - :::column-end::: - :::column span="1"::: - Contributor and Basic - :::column-end::: - :::column span="1"::: - Open the analytic view, choose **More** ... > **Security**. - :::column-end::: - :::column span="1"::: - no - :::column-end::: -:::row-end::: -::: moniker-end +|Object |Default group membership |How to access security|Inherited? | +|---------|---------|---------|---------| +|[Dashboards](../../report/dashboards/dashboard-permissions.md)| Contributor | Open **Dashboards**, select the area path, and then **More** ... > **Security**. | ✔️ (project settings for team dashboard)| +|[Wiki](../../project/wiki/manage-readme-wiki-permissions.md) |Contributor |Open the wiki, choose **More** ... > **Wiki security**. For more information, see [Manage Wiki permissions](../../project/wiki/manage-readme-wiki-permissions.md). | no | +|[Analytic views](../../report/powerbi/analytics-security.md) | Contributor & Basic|Open the analytic view, choose **More** ... > **Security**. | no | + ## Set permissions for Boards objects The following table provides information about setting permissions at the object-level for area and iteration paths, work items, and more. -:::row::: - :::column span="1"::: - **Object** - :::column-end::: - :::column span="1"::: - **Default group membership** - :::column-end::: - :::column span="1"::: - **How to access security** - :::column-end::: - :::column span="1"::: - **Inherited?** - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Area path](set-permissions-access-work-tracking.md) - :::column-end::: - :::column span="1"::: - [Project Administrator](../../organizations/security/permissions.md#project-level-groups) - :::column-end::: - :::column span="1"::: - Open **Project settings** > **Project configuration** > **Areas** > next to an area, **More** ... > **Security**. - :::column-end::: - :::column span="1"::: - ✔️ (child node from parent node) - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Iteration path](set-permissions-access-work-tracking.md) - :::column-end::: - :::column span="1"::: - [Project Administrator](../../organizations/security/permissions.md#project-level-groups) - :::column-end::: - :::column span="1"::: - Open **Project settings** > **Project configuration** > **Iterations** > next to an iteration, **More** ... > **Security**. - :::column-end::: - :::column span="1"::: - ✔️ (child node from parent node) - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Work item](set-permissions-access-work-tracking.md) - :::column-end::: - :::column span="1"::: - Contributor - :::column-end::: - :::column span="1"::: - Open **Project settings** > **Project configuration** > **Areas** > **Area path** > the work item. - :::column-end::: - :::column span="1"::: - no - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Work item query and query folder](../../boards/queries/set-query-permissions.md) - :::column-end::: - :::column span="1"::: - Creator of the query or folder or [Project Administrator](../../organizations/security/permissions.md#project-level-groups) - :::column-end::: - :::column span="1"::: - Open the work item query or query folder > **More** ... > **Security**. - :::column-end::: - :::column span="1"::: - no - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Delivery Plans](set-permissions-access-work-tracking.md#edit-or-manage-permissions-for-delivery-plans) - :::column-end::: - :::column span="1"::: - [Project Administrator](../../organizations/security/permissions.md#project-level-groups) or creator of the Delivery Plan. - :::column-end::: - :::column span="1"::: - Open **Boards** > **Delivery Plans** > next to a delivery plan, **More** ... > **Security**. - :::column-end::: - :::column span="1"::: - no - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Process](../../boards/get-started/permissions-access-boards.md) - :::column-end::: - :::column span="1"::: - [Project Administrator](../../organizations/security/permissions.md#project-level-groups) - :::column-end::: - :::column span="1"::: - Select **More** ... > **Security**. - :::column-end::: - :::column span="1"::: - ✔️ (from Organization/Collection settings) - :::column-end::: -:::row-end::: + +|Object |Default group membership |How to access security |Inherited? | +|---------|---------|---------|---------| +|[Area path](set-permissions-access-work-tracking.md) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups) |Open **Project settings** > **Project configuration** > **Areas** > next to an area, **More** ... > **Security**. | ✔️ (child node from parent node) | +|[Iteration path](set-permissions-access-work-tracking.md) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups) | Open **Project settings** > **Project configuration** > **Iterations** > next to an iteration, **More** ... > **Security**. | ✔️ (child node from parent node) | +|[Work item](set-permissions-access-work-tracking.md) | Contributor | Open **Project settings** > **Project configuration** > **Areas** > **Area path** > the work item. | no | +|[Work item query and query folder](../../boards/queries/set-query-permissions.md) | Creator of the query or folder or [Project Administrator](../../organizations/security/permissions.md#project-level-groups) |Open the work item query or query folder > **More** ... > **Security**. | no | +|[Delivery Plans](set-permissions-access-work-tracking.md) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups) or creator of the Delivery Plan |Open **Boards** > **Delivery Plans** > next to a delivery plan, **More** ... > **Security**. | no | +|[Process](../../boards/get-started/permissions-access-boards.md) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups) | Select **More** ... > **Security**. | ✔️ (from Organization/Collection settings) | > [!NOTE] > Work item tags - permissions get set at the project level, **Create tag definition**. Work item tags don't qualify as an object, they're defined through work items. ### Tips -For [**Team members by role**](../../organizations/notifications/manage-team-group-global-organization-notifications.md), the following two roles are explained. - - **Changed reviewers** applies to any reviewer that's added or deleted, because of policies defined for the set of files. For example, a push to a pull request (PR) can introduce a change to File1.cs. If a policy says Person A needs to review changes to File1.cs, they're in the Changed reviewers role for that iteration of the PR. - - The **Reset reviewers** role is related to the “reset votes” policy. For example, the repo has configured the policy, “Reset votes on new pushes”. Person B, who was required on the PR, has already approved this PR. Because of the "reset votes policy", their vote gets reset. So, they're in the Reset reviewers role for that iteration. +Let's break down the following roles related to reviewers: + +- **Changed reviewers:** + - This role applies to any reviewer who was added or removed, due to policies defined for a set of files. + - For example, consider a pull request (PR) where changes are made to `File1.cs`. + - If a policy specifies that Person A needs to review changes to `File1.cs`, they fall into the "Changed reviewers" role for that iteration of the PR. +- **Reset reviewers:** + - This role is related to the "reset votes" policy. + - Suppose the repository has the policy “Reset votes on new pushes” configured. + - If Person B, who was required to review the PR, already approved it, their vote gets reset due to the policy. + - As a result, they're in the "Reset reviewers" role for that iteration. ## Set permissions for Repos objects @@ -225,17 +97,25 @@ The following table provides information about setting permissions at the object | Object | Default group membership | How to access security | Inherited? | |--|--|--|--| | [Repos](../../repos/git/set-git-repository-permissions.md#open-security-for-a-repository) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups) | Open **Project settings**, **Repositories** > highlight your repo > **Security**. | ✔️ | -| [Git repository](../../repos/git/set-git-repository-permissions.md) |[Project Administrator](../security/change-project-level-permissions.md) | Open **Project settings** > **Repositories** and the Git repository. | ✔️ (from project settings for Git repository) | +| [Git repository](../../repos/git/set-git-repository-permissions.md) |[Project Administrator](../security/change-project-level-permissions.md) | Open **Project settings** > **Repositories** and the Git repository. | ✔️ (from project settings for Git repository) | | [Git branch](../../repos/git/branch-permissions.md) |[Project Administrator](../security/change-project-level-permissions.md) | Open **Repos** > **Branches** > your branch > **More** ... > **Branch security**. | ✔️ | -| [TFVC repository](../../repos/tfvc/set-tfvc-repository-permissions.md) |[Project Administrator](../security/change-project-level-permissions.md) | Open **Project settings** > **Repositories** and the TFVC repository. | ✔️ | +| [TFVC repository](../../repos/tfvc/set-tfvc-repository-permissions.md) |[Project Administrator](../security/change-project-level-permissions.md) | Open **Project settings** > **Repositories** and the TFVC repository. | ✔️ | ### Tips -- Branches inherit a subset of permissions from assignments made at the repository level. For more information about branch permissions and policies, see [Set branch permissions](../../repos/git/branch-permissions.md) and [Improve code quality with branch policies](../../repos/git/branch-policies.md) -- Create a shared query folder for each team and provide permissions to create and edit queries under that folder to all members of the team. -- If you add a user to the Contributors group, they can add and modify work items. You can restrict user and group permissions based on the area path. For more information, see [Set permissions and access for work tracking, Modify work items under an area path](set-permissions-access-work-tracking.md#set-permissions-area-path). +- **Branch permissions:** + - Branches inherit a subset of permissions from assignments made at the repository level. + - For more information, see [Set branch permissions](../../repos/git/branch-permissions.md) and [Improve code quality with branch policies](../../repos/git/branch-policies.md) +- **Shared query folders:** + - Create a shared query folder for each team. + - Provide permissions to create and edit queries under that folder to all team members. +- **Contributors group:** + - Adding a user to the Contributors group allows them to add and modify work items. + - You can restrict user and group permissions based on the area path. For more information, see [Set permissions and access for work tracking, Modify work items under an area path](set-permissions-access-work-tracking.md#set-permissions-area-path). ::: moniker range="azure-devops" -- Project Collection Administrators can [download the permissions report for a repository](download-permissions-report.md). The user interface button won't appear for users who aren't members of this group. +- **Permissions report:** + - Project Collection Administrators can [download the permissions report for a repository](download-permissions-report.md). + - The user interface button for this feature doesn't appear for users who aren't members of the Project Collection Administrators group. ::: moniker-end ## Set permissions for Pipelines objects @@ -244,16 +124,16 @@ The following table provides information about setting permissions at the object | Object | Default group membership | How to access security | Inherited? | |--|--|--|--| -| [**Pipelines**](../../pipelines/policies/set-permissions.md#verify-permissions-for-contributors) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups)| Open **Pipelines** > **Pipelines** > **All** > your pipeline > **More** ... > **Manage security**. | ✔️ | +| [**Pipelines**](../../pipelines/policies/permissions.md) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups)| Open **Pipelines** > **Pipelines** > **All** > your pipeline > **More** ... > **Manage security**. | ✔️ | | [Build pipelines](../../pipelines/policies/permissions.md) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups)| Open your build pipeline > **More** ... > **Manage security.** | ✔️ | -|[Build pipeline runs](../../pipelines/policies/set-permissions.md) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups)| Open your build pipeline run > **More** ... > **Manage security.** | ✔️ | -| [Release pipelines](../../pipelines/policies/permissions.md) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups)| Open your release pipeline > **More** ... > **Manage security.** | ✔️ | -| [Task groups (Classic)](../../pipelines/policies/permissions.md) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups)|Open your task group > **More** ... > **Manage security.** | ✔️ | -| [Deployment groups](../../pipelines/policies/permissions.md) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups)|Open your deployment group > **More** ... > **Manage security.** | ✔️ | -| [Deployment pools](../../pipelines/policies/permissions.md) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups) |Open your deployment pool > **More** ... > **Manage security.** | ✔️ | -| [Environments](../../pipelines/policies/permissions.md) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups)|Open your environment > **More** ... > **Manage security.** | ✔️ (from Environments permission settings) | -| [Variable groups](../../pipelines/library/index.md) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups)|Open your variable group > **More** ... > **Manage security.** |✔️ (from Library permission settings) | -| [Secure files](../../pipelines/policies/permissions.md) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups)|Open your secure file > **More** ... > **Manage security.** |✔️ (from Library permission settings) | +|[Build pipeline runs](../../pipelines/policies/permissions.md#pipeline-permissions) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups)| Open your build pipeline run > **More** ... > **Manage security.** | ✔️ | +| [Release pipelines](../../pipelines/policies/permissions.md#release-pipeline-permissions) | [Project Administrator](../../organizations/security/permissions.md#project-level-groups)| Open your release pipeline > **More** ... > **Manage security.** | ✔️ | +| [Task groups (Classic)](../../pipelines/policies/permissions.md#task-group-permissions) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups)|Open your task group > **More** ... > **Manage security.** | ✔️ | +| [Deployment groups](../../pipelines/policies/permissions.md#deployment-group-permissions) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups)|Open your deployment group > **More** ... > **Manage security.** | ✔️ | +| [Deployment pools](../../pipelines/policies/permissions.md#deployment-group-permissions) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups) |Open your deployment pool > **More** ... > **Manage security.** | ✔️ | +| [Environments](../../pipelines/policies/permissions.md#environment-permissions) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups)|Open your environment > **More** ... > **Manage security.** | ✔️ (from Environments permission settings) | +| [Variable groups](../../pipelines/policies/permissions.md#library-permissions) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups)|Open your variable group > **More** ... > **Manage security.** |✔️ (from Library permission settings) | +| [Secure files](../../pipelines/policies/permissions.md#library-permissions) |[Project Administrator](../../organizations/security/permissions.md#project-level-groups)|Open your secure file > **More** ... > **Manage security.** |✔️ (from Library permission settings) | ## Set permissions for Artifacts objects @@ -266,21 +146,21 @@ The following table provides information about setting permissions at the object ## Set permissions for Test plans objects -- Test plans, test suites, test cases, and other test objects are managed similarly to work items. This is because they represent test-specific work item types, as discussed in [Test objects and terms](/azure/devops/organizations/security/set-permissions-access-test). +- Test plans, test suites, test cases, and other test objects are managed similarly to work items because they represent test-specific work item types, as discussed in [Test objects and terms](/azure/devops/organizations/security/set-permissions-access-test). - You can manage test-level permissions through project-level settings or through Area Path object-level settings. For more information, see [Set permissions and access for testing](/azure/devops/organizations/security/set-permissions-access-test). ::: moniker range="azure-devops" ## Set object permissions through the command line -You can use the [az devops security command line tool](manage-tokens-namespaces.md) to view and manage permissions. +You can use the [az devops security command line tool](manage-tokens-namespaces.md), which allows you to view and manage permissions for various objects and features. -Some more granular permissions and permissions for select objects and features can only be managed through the command line. For example: +Here are some examples of more granular permissions that can be managed through the command line: -- Notifications using the `EventSubscription` and `EventSubscriber` namespaces -- Read or create dashboards using the `DashboardPriveliges` namespace -- Use, manage, or view service endpoints through the `ServiceEndpoints` namespace -- View delivery plans through the `Plans` namespace +- **Notifications:** Use the `EventSubscription` and `EventSubscriber` namespaces. +- **Dashboards:** Read or create dashboards using the `DashboardPrivileges` namespace. +- **Service endpoints:** Use, manage, or view service endpoints through the `ServiceEndpoints` namespace. +- **Delivery plans:** View delivery plans through the `Plans` namespace. For more information about namespaces, see [Security namespace and permission reference](namespace-reference.md). @@ -288,20 +168,27 @@ For more information about namespaces, see [Security namespace and permission re ## Set permissions for object notifications -Notifications can be set at the user, team, project, and organization/collection level. While there isn't a user interface for setting notification permissions, some permissions can be set through command line tools and the `EventSubscription` namespace. For more information, see [Security namespace and permission reference](namespace-reference.md). +While there isn't a user interface for setting notification permissions, some permissions can be set through command line tools and the `EventSubscription` namespace. For more information, see [Security namespace and permission reference](namespace-reference.md). -Here are some additional tips for managing notifications. +Here are some more tips for managing notifications: -- If you don't want to receive a notification for an event that you started, you can turn on the option, **Skip initiator**. For more information, see [Exclude yourself from notification emails for events that you start](../../organizations/notifications/exclude-self-from-email.md). -- We don't support organization-wide notifications. As an alternative, you can provide an email distribution list that goes to your entire organization. Also, you can generate a banner with the `az devops banner` command that all users see when they sign in. +- **Notification levels:** + - Notifications can be set at different levels: User, team, project, and organization/collection. + - Unfortunately, there isn’t a user interface specifically for setting notification permissions. + - However, some permissions can be configured through command-line tools and the EventSubscription namespace. +- **Skip initiator option:** + - If you don’t want to receive notifications for events that you initiated, enable the Skip initiator option. + - This prevents notifications for actions you started. + - For more information, see [Exclude yourself from notification emails for events that you start](../../organizations/notifications/exclude-self-from-email.md). +- **Organization-wide notifications:** + - Azure DevOps doesn’t directly support organization-wide notifications. + - As an alternative, consider providing an email distribution list that reaches your entire organization. + - In Azure DevOps Services you can create a banner using the `az devops banner` command that all users see when they sign in. ## Related articles +- [Manage permissions for specific tasks](restrict-access.md) +- [Manage permissions with command line tool](manage-tokens-namespaces.md) - [Change project-level permissions](change-project-level-permissions.md) -- [Change project collection-level permissions](change-organization-collection-level-permissions.md) - [Download permissions report for a repository](download-permissions-report.md) -- [Manage permissions with command line tool](manage-tokens-namespaces.md) - [Get started with permissions, access, and security groups](about-permissions.md) -- [Permissions lookup reference](permissions-lookup-guide.md) -- [Manage teams and configure team tools](../../organizations/settings/manage-teams.md) -- [Security and permission management tools](security-tools-reference.md) diff --git a/docs/organizations/security/set-permissions-access-test.md b/docs/organizations/security/set-permissions-access-test.md index 080d5db418f..fdc69177e9c 100644 --- a/docs/organizations/security/set-permissions-access-test.md +++ b/docs/organizations/security/set-permissions-access-test.md @@ -8,193 +8,149 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 05/24/2023 +ms.date: 10/17/2024 --- # Set permissions and access for testing [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -To exercise the full features of Azure Test Plans, you must be granted [Basic + Test Plans](https://marketplace.visualstudio.com/items?itemName=ms.vss-testmanager-web) access level or have one of the following subscriptions: - -- [Enterprise](https://visualstudio.microsoft.com/vs/enterprise/) -- [Test Professional](https://visualstudio.microsoft.com/vs/test-professional/) -- [MSDN Platforms](https://visualstudio.microsoft.com/msdn-platforms/) - -In addition, you can grant or restrict access to various manual test features by granting users or groups specific permissions for an object or project. Many test artifacts correspond to test-specific work item types. So, work-tracking permissions apply to test-specific work items, such as test plans, test suites, test cases and more. You set permissions for work items and manual testing features for area paths and at the project-level. You set permissions to manage test controllers at the organization or collection level. Test controllers are used in performing load tests. - -- **Object-level, Area path level** - - **Edit work items in this node**: Add or edit test-specific work items, such as test plans, test suites, test cases, shared steps, or shared parameters. - - **Manage test plans**: Modify test plan properties such as build and test settings. - - **Manage test suites**: Create and delete test suites, add, and remove test cases from test suites, change test configurations associated with test suites, and modify a test suite hierarchy (move a test suite). -- **Project-level** - - **Manage test configurations**: Add or edit [test configurations and configuration variables](../../test/test-different-configurations.md). - - **Manage test environments**: Add or edit [test plan settings](../../test/run-automated-tests-from-test-hub.md). - - **Create test runs**: [Run manual tests](../../test/run-manual-tests.md) - - **Delete and restore work items**: [Delete test-specific work items](../../boards/backlogs/remove-delete-work-items.md) - - **Delete test runs**: [Delete test results](../../boards/backlogs/delete-test-artifacts.md) - - **Manage test configurations**: Add or edit [test configurations and configuration variables](../../test/test-different-configurations.md). - - **Manage test environments**: Add or edit [test plan settings](../../test/run-automated-tests-from-test-hub.md). - - **Move work items out of this project**: [Move work items from one project to another](../../boards/backlogs/move-change-type.md) - - **Permanently delete work items**: [Permanently delete test-specific work items](../../boards/backlogs/remove-delete-work-items.md) -- **Organization or collection-level** - - **Manage test controllers**: Permission associated with a deprecated feature for TFS 2018 and later versions. To learn more, see [Overview of test agents and test controllers for running load tests](/visualstudio/test/configure-test-agents-and-controllers-for-load-tests) and [Install test agents and test controllers](/visualstudio/test/lab-management/install-configure-test-agents). +To fully utilize Azure Test Plans, it's crucial to understand and configure the necessary permissions and access levels. This article outlines the steps, so you can do the following tasks: + +- Grant access to manual testing features +- Manage test plans and test suites +- Set permissions for creating and deleting test artifacts + +By following these guidelines, you can ensure that your team has the appropriate access to efficiently manage and execute test plans. + +To manage access to manual test features, you can grant specific permissions to users or groups at the **object** or **project** level for the following tasks: + +- **Object-level (Area path):** + - **Edit work items in this node**: Add or edit test-specific work items like test plans, test suites, and test cases. + - **Manage test plans**: Modify test plan properties, such as build and test settings. + - **Manage test suites**: Create, delete, and modify test suites. +- **Project-level:** + - **Manage test configurations**: [Add or edit test configurations and variables](../../test/test-different-configurations.md). + - **Manage test environments**: [Adjust test plan settings](../../test/run-automated-tests-from-test-hub.md). + - **[Create test runs](../../test/run-manual-tests.md)**. + - **[Delete and restore test-specific work items](../../boards/backlogs/remove-delete-work-items.md)**. + - **[Delete test runs](../../boards/backlogs/delete-test-artifacts.md)**. + +[Test controllers](/visualstudio/test/configure-test-agents-and-controllers-for-load-tests), used for load tests, are managed at the organization or collection level. For more information, see [Install test agents and test controllers](/visualstudio/test/lab-management/install-configure-test-agents). ## Prerequisites ::: moniker range="azure-devops" - -- To manage access levels or organization-level permissions, you must be a member of the **Project Collection Administrators** security group, or have your **Edit instance-level information** set to **Allow**. -- To manage project or object-level test-related permissions, you must be a member of the **Project Administrators** security group. - -For more information, see the following articles: -- [About access levels](access-levels.md) -- [Add organization users and manage access](../accounts/add-organization-users.md) -- [Change access levels for users or groups](change-access-levels.md) -- [Change project-level permissions](change-project-level-permissions.md) -- [Change project collection-level permissions](change-organization-collection-level-permissions.md) +| Category | Requirements | +|--------------|-------------| +|**Access levels**| **[Basic + Test Plans](https://marketplace.visualstudio.com/items?itemName=ms.vss-testmanager-web)** or specific subscriptions like **[Enterprise](https://visualstudio.microsoft.com/vs/enterprise/)**, **[Test Professional](https://visualstudio.microsoft.com/vs/test-professional/)**, or **[MSDN Platforms](https://visualstudio.microsoft.com/msdn-platforms/)**.| +| **Permissions**| - To manage project or object-level test-related permissions or to permanently delete test artifacts: Member of the **Project Administrators** security group.
      - To manage access levels or organization-level permissions: Member of the **Project Collection Administrators** security group or **Edit instance-level information** set to **Allow**. | + ::: moniker-end ::: moniker range="< azure-devops" -- To manage access-levels, you must be a member of the **Azure DevOps Server Administrators** group. -- To manage project or object-level test-related permissions, you must be a member of the **Project Administrators** security group. -- To manage collection-level permissions or manage access levels, you must be a member of the **Project Collection Administrators** security group, or have your **Edit instance-level information** set to **Allow**. -For more information, see the following articles: +| Category | Requirements | +|--------------|-------------| +|**Access levels**|member of the **Azure DevOps Server Administrators** security group. | +| **Permissions**| - To manage project or object-level test-related permissions or to permanently delete test artifacts: Member of the **Project Administrators** security group.
      - To manage access levels or organization-level permissions: Member of the **Project Collection Administrators** security group or **Edit instance-level information** set to **Allow**. | + -- [About access levels](access-levels.md) -- [Add a server-level administrator](/azure/devops/server/admin/add-administrator) -- [Change access levels for users or groups](change-access-levels.md) -- [Change project-level permissions](change-project-level-permissions.md) -- [Change project collection-level permissions](change-organization-collection-level-permissions.md) ::: moniker-end +For more information, see [About access levels](access-levels.md) and [Change access levels for users or groups](change-access-levels.md). + ## Grant access to manual testing features -To have full access to the Test feature set, your [access level must be set to Basic + Test Plans](change-access-levels.md). Users with Basic access and with permissions to permanently delete work items and manage test artifacts can only delete orphaned test cases. +For full access to Test Plans, users must have [**Basic + Test Plans**](change-access-levels.md) access level. Users with **Basic** access and permissions to permanently delete work items and manage test artifacts can only delete orphaned test cases. ## Manage test plans and test suites under an area path -Area path permissions let you grant or restrict access to edit or modify test plans or test suites assigned to those areas. You can restrict access to users or groups. +Do the following steps to grant permissions for managing test artifacts at the area path level. -In addition to the project-level permissions set in the previous section, team members need permissions to manage test artifacts, which are set for an area path. +1. Sign in to your project (`https://dev.azure.com/{Your_Organization/Your_Project}`). +2. Select **Project settings** > **Project configuration**. +3. Select **Areas** > **...**(ellipses) > **Security**. -[Open the **Security** page for area paths](set-permissions-access-work-tracking.md#set-permissions-area-path) and choose the user or group you want to grant permissions. + :::image type="content" source="media/delete-test-plans-open-area-permissions.png" alt-text="Screenshot showing opened Area path permissions for project."::: -:::image type="content" source="media/delete-test-plans-open-area-permissions.png" alt-text="Screenshot showing opened Area path permissions for project."::: +4. Set the permissions for **Manage test plans** and **Manage test suites** to **Allow**. -Set the permissions for **Manage test plans** and **Manage test suites** to **Allow**. + :::image type="content" source="media/manage-test-plans-test-suites-access.png" alt-text="Screenshot showing access set to Allow for test plans and suites."::: -:::image type="content" source="media/manage-test-plans-test-suites-access.png" alt-text="Screenshot showing access set to Allow for test plans and suites."::: +## Set permissions for managing test artifacts -## Set permissions to create and delete test artifacts +When it comes to testing artifacts like test plans, test suites, and test cases, the process for deleting them is distinct from deleting nontest work items. -While test artifacts such as test plans, test suites, test cases, and so on, are types of work items, the method for deleting them differs from deleting nontest work items. +Users with Basic access and with permissions to permanently delete work items and manage test artifacts can only delete orphaned test cases. That is, they can delete test cases created from **Work** that aren't linked to any test plans or test suites. > [!IMPORTANT] -> We only support permanent deletion of test artifacts such as test plans, test suites, test cases, shared steps and shared parameters. Deleted test artifacts won't appear in the recycle bin and cannot be restored. Deletion of test artifacts not only deletes the selected test artifact but also all its associated child items such as child test suites, test points across all configurations, testers (the underlying test case work item doesn't get deleted), test results history, and other associated history. - -When you delete test artifacts, the following actions occur: - -1. Removes the deleted test artifact from the test case management (TCM) data store and deletes the underlying work item -2. Runs a job to delete all the child items both from the TCM side and the underlying work items. This action may take time (up to a few minutes) depending on the number of artifacts to be deleted. -3. Causes all information in the work item tracking data store and TCM data store to be deleted and can't be reactivated or restored. - - -::: moniker range=">= azure-devops-2019" - -You must be a member of the Project Administrators group or have the [**Delete test artifacts** permission set to **Allow**](../../organizations/security/set-permissions-access-work-tracking.md#delete-test-permissions). You must also have your [access level](../../organizations/security/access-levels.md) set to **Basic + Test Plans** or **Visual Studio Enterprise**, which provides access to the full Test feature set. Users with Basic access and with permissions to permanently delete work items and manage test artifacts can only delete orphaned test cases. That is, they can delete test cases created from **Work** that aren't linked to any test plans or test suites. - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -You must be a member of the Project Administrators group or have the [**Delete test runs** permission set to **Allow**](../../organizations/security/set-permissions-access-work-tracking.md#delete-test-permissions). You must also have your [access level set to Basic+Test Plans or Advanced](../../organizations/security/change-access-levels.md), which provides access to the full Test feature set. Users with Basic access and with permissions to permanently delete work items and manage test artifacts can only delete orphaned test cases. That is, they can delete test cases created from **Work** that aren't linked to any test plans or test suites. - -For more information, see [Delete test artifacts](../../boards/backlogs/delete-test-artifacts.md). - -As a project admin you can grant a user, team group, or other group you've created to have these permissions. Open the Security page for the project and choose the user or group you want to grant permissions. To learn how to access project-level **Security**, see [Change project-level permissions](change-project-level-permissions.md). - -::: moniker-end - +> When you delete test artifacts like test plans, test suites, and test cases, note the following information: +> - **Permanent deletion:** We only support permanent deletion of these artifacts. +> - **No recycle bin:** Deleted test artifacts don’t appear in the recycle bin and you can't restore them. +> - **Associated child items:** Deletion affects associated child items, including child test suites, test points across all configurations, testers (the underlying test case work item remains unaffected), test results history, and other related history. +> - **Removal from TCM data store:** The deleted test artifact is removed from the test case management (TCM) data store, and the underlying work item is deleted. +> - **Child item deletion:** A job runs to delete all child items both from the TCM side and the underlying work items. This process may up to a few minutes depending on the number of artifacts being deleted. +> - **Irreversible deletion:** All information in the work item tracking data store and TCM data store is permanently deleted and cannot be reactivated or restored. ::: moniker range="azure-devops" > [!NOTE] -> To enable the **Project Permissions Settings Page** preview page, see [Enable preview features](../../project/navigation/preview-features.md). +> To turn on the **Project Permissions Settings Page** preview page, see [Enable preview features](../../project/navigation/preview-features.md). -In this example, we grant members assigned to the Team Admin group permissions to create and view test runs and manage test configurations and environments. +Do the following steps to set permissions for managing test artifacts. #### [Preview page](#tab/preview-page) -> ![Screenshot of Set project-level test permissions for a custom group, Team Admin.](media/test-permissions/set-project-level-test-permissions-new-ui.png) +1. Sign in to your project (`https://dev.azure.com/{Your_Organization/Your_Project}`). +2. Select **Project settings** > **Permissions**. + + ![Screenshot showing Choose Project settings > Permissions.](../settings/media/shared/open-project-settings-permissions-preview.png) -#### [Current page](#tab/current-page) +3. Select a user or group. +4. Select from the dropdown menus to change the permissions for each item. -> [!div class="mx-imgBorder"] -> ![Screenshot of Set project-level test permissions for a custom group, Team Admin.](media/test-permissions/project-level-permissions-2020-earlier.png) + In the following example, we grant users assigned to the Team Admin group permissions to view test runs and manage test configurations and environments. -::: moniker-end + :::image type="content" source="media/test-permissions/set-project-level-test-permissions-new-ui.png" alt-text="Screenshot of Set project-level test permissions for a custom group, Team Admin."::: -* * * - -::: moniker range="< azure-devops" - -In this example, we grant members assigned to the Test Admin group permissions to delete test runs. - -> [!div class="mx-imgBorder"] -> ![Set project-level permissions for a custom group, Team Admin](media/set-permissions-project-level-dialog.png) - -::: moniker-end + Updated permissions automatically save. - - -## Set permissions to manage test controllers - -Test controllers are used to perform load testing. To learn more, see [Overview of test agents and test controllers for running load tests](/visualstudio/test/configure-test-agents-and-controllers-for-load-tests). - -To set permissions for managing test controllers, open **Organization** settings and choose **Security** or **Permissions**. Choose the group you want to grant permissions. To learn how to access organization or collection-level **Security**, see [Change project collection-level permissions](change-organization-collection-level-permissions.md). - -In this example, we grant members assigned to the Team Collection Admin group permissions to manage test controllers. - -::: moniker range="azure-devops" - -> [!NOTE] -> To enable the **Organization Permissions Settings Page v2** preview page, see [Enable preview features](../../project/navigation/preview-features.md). - - -#### [Preview page](#tab/preview-page) +#### [Current page](#tab/current-page) -> [!div class="mx-imgBorder"] -> ![Set collection-level test permissions for a custom group, Team Admin](media/test-permissions/set-collection-level-test-permissions-new-ui.png) +1. Sign in to your project (`https://dev.azure.com/{Your_Organization/Your_Project}`). +2. Select **Project settings** > **Permissions**. +3. Select a user or group. +4. Select from the dropdown menus to change the permissions for each item. + In the following example, we grant users assigned to the Team Admin group permissions to view test runs and manage test configurations and environments. -#### [Current page](#tab/current-page) + :::image type="content" source="media/test-permissions/project-level-permissions-2020-earlier.png" alt-text="Screenshot of Set project-level test permissions for a custom group, Team Admin."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of set project-level test permissions for a custom group, Team Admin.](media/test-permissions/set-collection-level-test-permissions-old-ui.png) + Updated permissions automatically save. +::: moniker-end * * * -::: moniker-end - ::: moniker range="< azure-devops" -> [!div class="mx-imgBorder"] -> ![Set project-level test permissions for a custom group, Team Admin](media/test-permissions/set-collection-level-test-permissions-old-ui.png) +In the following example, we grant members assigned to the Test Admin group permissions to delete test runs. + +:::image type="content" source="media/set-permissions-project-level-dialog.png" alt-text="Screenshot of Set project-level permissions for a custom group, Team Admin."::: ::: moniker-end +## Next steps + +> [!div class="nextstepaction"] +> [Navigate Test Plans](../../test/navigate-test-plans.md) ## Related articles -- [Grant or restrict access](restrict-access.md) -- [Permissions and access for work tracking](permissions-access-work-tracking.md) +- [Manage access](restrict-access.md) - [Set permissions and access for work tracking](set-permissions-access-work-tracking.md) -- [Permissions and groups reference](permissions.md) -- [Troubleshoot permissions](troubleshoot-permissions.md) diff --git a/docs/organizations/security/set-permissions-access-work-tracking.md b/docs/organizations/security/set-permissions-access-work-tracking.md index a8897ae0ef2..b5c53189abb 100644 --- a/docs/organizations/security/set-permissions-access-work-tracking.md +++ b/docs/organizations/security/set-permissions-access-work-tracking.md @@ -1,7 +1,7 @@ --- title: Set permissions for work tracking titleSuffix: Azure DevOps -description: How to grant or restrict access to work tracking tasks by setting object or project-level permissions for Azure DevOps +description: Learn how to grant or restrict access to work tracking tasks by setting object or project-level permissions for Azure DevOps, and default permissions for objects. ms.custom: boards-permissions, linked-from-support, engagement-fy23 ms.subservice: azure-devops-security ms.assetid: 5AD0BF62-C91E-46DD-8C1A-C8D1F8F8D05F @@ -9,43 +9,43 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 05/24/2023 +ms.date: 08/22/2023 --- # Set work tracking permissions [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can grant or restrict access to various work tracking features by granting users or groups specific permissions for an object, project, or collection. Or, you can specify custom rules for a process or project that apply to users or groups that may restrict or require users to perform a select action. In general, you want to add users to a project's Contributors group to provide access to most features as listed in [Permissions and access for work tracking](permissions-access-work-tracking.md). +To manage work tracking effectively, assign specific permissions to users or groups for particular [objects, projects, or collections](#business-workflows). You can also [define custom rules](#use-custom-rules) for processes or projects that apply to specific users or groups, controlling their actions accordingly. For most features, we recommend adding users to the project's **Contributors** group, which grants comprehensive access and ensures a seamless and efficient work tracking experience. ::: moniker range="azure-devops" > [!NOTE] -> For public projects, Stakeholder access gives users greater access to work tracking features and full access to Azure Pipelines. To learn more, see [Stakeholder access quick reference](stakeholder-access.md). +> For public projects, Stakeholder access gives users greater access to work tracking features and full access to Azure Pipelines. For more information, see [Stakeholder access quick reference](stakeholder-access.md). ::: moniker-end ## Prerequisites +::: moniker range="azure-devops" -- To set work tracking permissions, you must be a member of the [**Project Administrators** group](change-project-level-permissions.md), or have explicit permissions to manage the work tracking area as described in this article. -- To set process permissions, you must be a member of the [**Project Collection Administrators** group](change-organization-collection-level-permissions.md), or have explicit permissions to edit a collection process. - - - -## Support business workflows through custom rules +| Category | Requirements | +|--------------|-------------| +| **Permissions**| Member of the [**Project Administrators** group](change-project-level-permissions.md) or explicit permission to manage the work tracking area as described in this article. | + +::: moniker-end +::: moniker range="< azure-devops" -Custom rules don't control permissions, but they do affect the permissions of a user at run-time to modify a work item or set the value of a work item field. Azure Boards supports the following work tracking customizations that support business workflows. +| Category | Requirements | +|--------------|-------------| +| **Permissions**| Member of the [**Project Collection Administrators** group](change-organization-collection-level-permissions.md) or have explicit permissions to edit a collection process. | -- Apply select rules upon work item creation, state change, specified state. For example, make a field required or read-only. -- Apply select rules when a field value is empty, set to a specific value, or was changed or not changed to a value. For example, clear or set the value of a field, or copy a field value to another field or hide a field. -- Restrict the transition to a specific state when moving from a specified state. For example, reassign a work item based on state change, or state transitions of parent work items based on state changes made to their child work items. -- Apply select rules based on user or group membership of the user modifying a work item. For example, you can specify rules that effectively restrict a group of users from creating a work item, transitioning a work item to a closed or completed state, or changing the value of a field. +::: moniker-end -Some restrictions are placed on applying custom rules to system fields. For example, you can't specify rules that set or clear the value for **Area Path** or **Iteration Path** as these are system fields. To learn more about custom rules you can define and system field restrictions on custom rules, see [Rules and rule evaluation](../settings/work/rule-reference.md). For sample scenarios that define custom rules, see [Sample rule scenarios](../settings/work/rule-samples.md). + -## Work tracking roles and permission levels +## Understand roles and permission levels for work tracking -The following table summarizes the different permissions you can set at the object, project, or collection level. The team administrator role provides access to add and modify team resources. +The following table summarizes the different permissions you can set at the object, project, or collection level. The team administrator role provides access to add and modify team resources. Also, see Default permissions for Boards, Backlogs, Sprints, Delivery Plans, Test Management, and Queries, further in this article. --- :::row::: @@ -60,7 +60,7 @@ The following table summarizes the different permissions you can set at the obje :::row::: :::column span="1"::: **Team administrator role**
      - To add a user to the team administrator role, see [Add a team administrator](../../organizations/settings/add-team-administrator.md). + [Add a team administrator](../../organizations/settings/add-team-administrator.md) :::column-end::: :::column span="2"::: - [Manage teams and configure team tools](../settings/manage-teams.md) @@ -78,7 +78,7 @@ The following table summarizes the different permissions you can set at the obje - [Modify work items under an area path](#set-permissions-area-path) - [Create and edit nodes under an area path or iteration path](#set-permissions-area-path) - [Define and edit queries or query folders](#work-item-queries) - - [Define and edit Delivery Plans](set-permissions-access-work-tracking.md#edit-or-manage-permissions-for-delivery-plans) + - [Define and edit Delivery Plans](set-permissions-access-work-tracking.md) :::column-end::: :::row-end::: @@ -96,51 +96,55 @@ The following table summarizes the different permissions you can set at the obje - [Add teams and team administrators](../settings/add-team-administrator.md)) - [Edit project-level permissions](change-project-level-permissions.md) ::: moniker-end - ::: moniker range="< azure-devops-2020" - - [Create work item tags](../../boards/queries/add-tags-to-work-items.md) - - [Permanently delete work items](#move-delete-permissions) - - [Edit shared work item queries](../../boards/queries/set-query-permissions.md) - - [Add teams and team administrators](../settings/add-team-administrator.md)) - - [Edit project-level permissions](change-project-level-permissions.md) - ::: moniker-end + :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **Project collection-level permissions** + **Project collection-level permissions**
      + Includes all permissions you can set at the collection-level. :::column-end::: :::column span="2"::: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - [Create, delete, or edit a process (Inheritance process model)](#process-permissions) - [Delete field from account (Inheritance process model)](change-organization-collection-level-permissions.md) - [Manage process permissions (Inheritance process model)](change-organization-collection-level-permissions.md) - [Edit collection level permissions](change-organization-collection-level-permissions.md)
      Project collection-level permissions include all permissions you can set at the collection-level. ::: moniker-end - ::: moniker range="< azure-devops-2019" - - [Edit collection level permissions](change-organization-collection-level-permissions.md)
      Project collection-level permissions include all permissions you can set at the collection-level. - ::: moniker-end + :::column-end::: :::row-end::: --- - -> [!NOTE] -> If you haven't defined the group yet whose permissions you want to set, then first create the group, usually at the project level. To learn how, see [Add or remove users or groups, manage security groups](add-remove-manage-user-group-security-group.md). - - + +### Default permissions for Boards, backlogs, and sprints + +#### Boards default permissions + +[!INCLUDE [temp](includes/boards-boards.md)] + +#### Backlogs default permissions + +[!INCLUDE [temp](includes/boards-backlogs.md)] + +#### Sprints default permissions + +[!INCLUDE [temp](includes/boards-sprints.md)] + + ## Create child nodes, modify work items under an area or iteration path -Area path permissions let you grant or restrict access to edit or modify work items, test cases, or test plans assigned to those areas. You can restrict access to users or groups. You can also set permissions for who can add or modify areas or iterations for the project. +Area path permissions let you manage access to edit or modify work items, test cases, or test plans assigned to those areas. You can restrict access to users or groups. You can also set permissions for who can add or modify areas or iterations for the project. > [!NOTE] -> Project members granted permissions to create or edit **Area Paths** or **Iteration Paths** is separate from the permissions that control configuring team **Area Paths** and **Iteration Paths**. To configure team settings, you must be added to the [team administrator role](../settings/add-team-administrator.md), or be a member of the [**Project Administrators** group](change-project-level-permissions.md). -* +> Project members with permissions to create or edit **Area Paths** or **Iteration Paths** can't set team **Area Paths** and **Iteration Paths**. To configure team settings, be added to the [team administrator role](../settings/add-team-administrator.md) or be a member of the [**Project Administrators** group](change-project-level-permissions.md). + ::: moniker range="azure-devops" -Define both areas and iterations for a project from the **Project Settings** > **Project configuration**. +Do the following steps to define both areas and iterations for a project. -1. Choose (1) **Project Settings**, then choose (2) **Project configuration** under **Boards**, and then choose (3) **Areas** or **Iterations** to modify Area Paths or Iteration Paths. +1. Choose **Project settings** > **Project configuration** > **Boards**, and then select **Areas** or **Iterations** to modify Area Paths or Iteration Paths. :::image type="content" source="../settings/media/areas/open-project-work-areas-settings-vert.png" alt-text="Screenshot showing opening Project Settings, Work, Project Configuration."::: @@ -154,70 +158,67 @@ Define both areas and iterations for a project from the **Project Settings** > * :::image type="content" source="media/work-tracking/set-area-node-permissions-with-work-item-comments.png" alt-text="Screenshot of Area Path node Security, selected group, and setting Deny permissions. "::: - You can specify two explicit authorization states for permissions: **Deny** and **Allow**. In addition, permissions can exist in one of three other states. To learn more, see [Get started with permissions, access, and security groups](about-permissions.md). + You can specify two explicit authorization states for permissions: **Deny** and **Allow**. In addition, permissions can exist in one of the three other states. For more information, see [About permissions, access, and security groups](about-permissions.md). 4. (Optional) Choose the **Inheritance** slider to disable inheritance. Disabling **Inheritance** persists all inherited permissions as explicit Access Control Entries (ACEs). -5. When you're done, close the dialog. Your changes are automatically saved. +5. When you're done, close the dialog. Your changes automatically save. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="< azure-devops" -You define both areas and iterations for a project from the **Project Settings>Project configuration**. +Do the following steps to define both areas and iterations for a project. -1. Choose (1) **Project Settings**, then choose (2) **Project configuration** under **Boards**, and then choose (3) **Areas**. +1. Select (1) **Project settings** > (2) **Project configuration** > (3) **Areas**. - > [!div class="mx-imgBorder"] - > ![Screenshot showing opening Project Settings>Work>Project Configuration for on-premises server.](../settings/media/areas/open-project-work-areas-settings-vert.png) + :::image type="content" source="../settings/media/areas/open-project-work-areas-settings-vert.png" alt-text="Screenshot of sequence, opening Project Settings>Work>Project Configuration for on-premises server."::: -1. Choose the **...** context menu for the node you want to manage and select **Security**. +2. Choose the **...** context menu for the node you want to manage and select **Security**. - :::image type="content" source="media/work-tracking/set-permissions-area-node-open.png" alt-text="Screenshot of context menu for Area Path, choose Security, Azure DevOps Server 2020."::: + :::image type="content" source="media/work-tracking/set-permissions-area-node-open.png" alt-text="Screenshot of context menu for Area Path, choose Security, Azure DevOps Server 2020."::: -1. Select the group or team member, and then change the permission settings. To add a user or group, enter their name in the search box. +3. Select the group or team member, and then change the permission settings. To add a user or group, enter their name in the search box. - For example, here we've added the *Disallow Access Group*, and disallowed members of this group the ability to view, modify, or edit work items in the Customer Service area path. + In the following example, we added the *Disallow Access Group*, and disallowed members of this group the ability to view, modify, or edit work items in the Customer Service area path. :::image type="content" source="media/work-tracking/set-permissions-area-node-dialog.png" alt-text="Screenshot of Area Path node Security, selected group, and setting Deny permissions, Azure DevOps Server 2022 and earlier versions. "::: - You can specify two explicit authorization states for permissions: **Deny** and **Allow**. In addition, permissions can exist in one of three other states. To learn more, see [Get started with permissions, access, and security groups](about-permissions.md). + You can specify two explicit authorization states for permissions: **Deny** and **Allow**. Permissions can also exist in one of the three other states. For more information, see [About permissions, access, and security groups](about-permissions.md). -1. (Optional) Toggle **Inheritance** to **Off** to disable inheritance. Disabling **Inheritance** persists all inherited permissions as explicit Access Control Entries (ACEs). +4. (Optional) Toggle **Inheritance** to **Off** to disable inheritance. Disabling **Inheritance** persists all inherited permissions as explicit Access Control Entries (ACEs). -2. When you're done, close the dialog. Your changes are automatically saved. +5. When you're done, close the dialog. Your changes automatically save. ::: moniker-end -::: moniker range="tfs-2018" - -1. From the web portal for the project, choose the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: gear icon. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing opening Web portal, Open Admin context, project level for TFS 2018.](../settings/media/areas/modify-areas-its-open-admin-context-ts.png) - - If you're currently working from a team context, then hover over the ![gear icon](../../media/icons/gear_icon.png) and choose **Project settings**. + - > [!div class="mx-imgBorder"] - > ![Screenshot showing Open Project Settings for TFS 2018.](../../media/settings/open-project-settings-horz.png) +### Default permissions for work items -2. Choose **Work** and then **Areas**. +[!INCLUDE [temp](includes/boards-work-items.md)] -1. Choose the ... context menu for the node you want to manage and select **Security**. +## Use custom rules - ![Screenshot showing context menu, select Security for TFS 2018.](media/work-tracking/set-permissions-area-node-open.png) +Custom rules don't control permissions, but they affect whether a user can modify a work item or set the value of a work item field. Azure Boards supports the following work tracking customizations that support business workflows. -::: moniker-end +|Customization |Examples | +|---------|---------| +|Apply rules upon work item creation, state change, and specified state. | - Make a field read-only
      - Make a field required | +|Apply rules when a field value is empty, set to a specific value, or change or not changed to a value. |- Clear the value of a field if it's empty or meets certain criteria
      - Set a predefined value for the field if it's empty or meets specific conditions
      - Copy the value of one field to another field
      - Hide a field based on certain conditions or values | +|Apply rules that dictate what state a work item can get moved to from a given state. |- Reassign a work item based on state changes
      - Specify that a work item can only transition from "State A" to "State B"
      - Manage the state transitions of parent work items based on the state changes of their child work items | +|Apply rules based on user or group membership of the user modifying a work item. |Specify rules that restrict a group from creating a work item, transitioning a work item to a closed or completed state, or changing the value of a field | +There are some restrictions for applying custom rules to system fields. For example, you can't specify rules that set or clear the value for **Area Path** or **Iteration Path** as they're system fields. For more information, see [Rules and rule evaluation](../settings/work/rule-reference.md) and [Sample rule scenarios](../settings/work/rule-samples.md). ## Set permissions on queries or query folders You can specify who can add or edit query folders or queries at the object-level. -To manage permissions for a query or query folder, you must be the creator of the query or folder, a member of the Project Administrators or Project Collection Administrators group, or granted explicit access through the object's **Security** dialog. +To manage permissions for a query or query folder, be the creator of the query or folder, a member of the Project Administrators or Project Collection Administrators group or granted explicit access through the object's **Security** dialog. -**Query folder Permissions dialog** +**Query folder permissions dialog** ::: moniker range="azure-devops" :::image type="content" source="../../boards/queries/media/permissions/permissions-dialog-query-folder-azure-devops.png" alt-text="Screenshot of Permissions dialog for a query folder."::: @@ -225,28 +226,37 @@ To manage permissions for a query or query folder, you must be the creator of th ::: moniker range="< azure-devops" -> [!div class="mx-imgBorder"] -> ![Screenshot of Permissions dialog for a query folder, Azure DevOps Server 2022 and earlier versions.](../../boards/queries/media/permissions/permissions-dialog-query-folder.png) +:::image type="content" source="../../boards/queries/media/permissions/permissions-dialog-query-folder.png" alt-text="Screenshot of Permissions dialog for a query folder, Azure DevOps Server 2022 and earlier versions."::: + ::: moniker-end -To learn more about queries, see [Create managed queries to list, update, or chart work items](../../boards/queries/about-managed-queries.md). +For more information, see [Create managed queries to list, update, or chart work items](../../boards/queries/about-managed-queries.md). - +### Default permissions for queries +> [!TIP] +> By default, Contributors can't create and save shared queries. We recommend that Project Administrators create a query folder for each team and give the team administrators or the team group query permissions to manage their folder. You need **Delete** permissions to rename or move a shared query or folder, and **Contribute** permissions for the folder where you move the query to. For more information, see [Set permissions on queries and query folders](../../boards/queries/set-query-permissions.md). -## Set permissions on work item tags +[!INCLUDE [temp](includes/boards-queries.md)] -By default, all users of the Contributors group can create and add tags to work items. To set permissions for a group or user to restrict this ability, you can set the **Create tag definition** to **Deny** at the project-level. To learn how, see [Change the permission level for a project-level group](change-project-level-permissions.md). +[Adhoc searches](../../boards/queries/search-box-queries.md) are powered by a semantic search engine. + + +## Set permissions for work item tags + +By default, all users of the Contributors group can create and add tags to work items. To set permissions for a group or user to restrict this ability, you can set the **Create tag definition** to **Deny** at the project-level. To learn how, see [Change the permission level for a project-level group](change-project-level-permissions.md). ## Manage permissions for Delivery Plans -Delivery Plans are an object within a project. You manage plan permissions for each plan similar to the way you manage permissions for shared queries or query folders. The creator of a Delivery Plan and all members of the Project Collection Administrators and Project Administrators groups have permissions to edit, manage, and delete plans. +Delivery Plans are an object within a project. You can manage permissions for each plan like the way you manage permissions for shared queries or query folders. The creator of a Delivery Plan and all members of the Project Collection Administrators and Project Administrators groups have permissions to edit, manage, and delete plans. + +Users granted **Stakeholder** access for private projects have no access to delivery plans, while users granted **Stakeholder** access for public projects has the same access as regular Contributors granted **Basic** access. For a comparison chart of Stakeholder versus basic access, see the [Feature Matrix](https://azure.microsoft.com/services/devops/compare-features/). -To edit the permissions for a Delivery Plan, you must be the creator of the plan, a member of the Project Administrators or Project Collection Administrators group, or granted explicit permission through the plan's **Security** dialog. +To edit the permissions for a Delivery Plan, be the creator of the plan, a member of the Project Administrators or Project Collection Administrators group, or granted explicit permission through the plan's **Security** dialog. ::: moniker range=">= azure-devops-2022" @@ -262,23 +272,21 @@ To edit the permissions for a Delivery Plan, you must be the creator of the plan 4. With the user or group selected, set the permission you want them to have to **Allow**. **Manage** set to **Allow** enables the user to manage permissions for the plan. - For example, here we grant permission to Cristina to edit the plan. + :::image type="content" source="../../boards/plans/media/permissions/permissions-dialog-change-s186.png" alt-text="Screenshot showing example permissions dialog for delivery plan."::: - :::image type="content" source="../../boards/plans/media/permissions/permissions-dialog-change-s186.png" alt-text="Screenshot showing permissions dialog for delivery plan."::: - -5. When you're done, close the dialog. The changes are automatically saved. +5. When you're done, close the dialog. Your changes automatically save. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops-2022" +::: moniker range="< azure-devops-2022" -1. Open **Boards>Plans**. For details, see [Review team delivery plans](../../boards/extensions/delivery-plans.md). +1. Open **Boards** > **Plans**. For more information, see [Review team delivery plans](../../boards/plans/review-team-plans.md). 2. To grant permissions to a group or user to manage or edit a specific plan, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon to open the **Security** dialog for the plan. :::image type="content" source="../../boards/plans/media/permissions/open-plans-security.png" alt-text="Screenshot showing the Security button for plan permissions, highlighted by a red box."::: -3. Add a user, team group, or other security group who you want to grant permissions to or restrict access. For details, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). By default, nonadministrators can't delete or edit a plan. +3. Add a user, team group, or other security group who you want to grant permissions to or restrict access. For details, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). By default, non-administrators can't delete or edit a plan. 4. With the user or group selected, set the permission you want them to have to **Allow**. **Manage** set to **Allow** enables the user to manage permissions for the plan. @@ -286,33 +294,19 @@ To edit the permissions for a Delivery Plan, you must be the creator of the plan :::image type="content" source="../../boards/plans/media/permissions/permissions-plans-dialog.png" alt-text="Screenshot showing the permissions dialog for a delivery plan."::: -5. Choose **Save changes** when done. +5. **Save** when you're done. ::: moniker-end -::: moniker range="tfs-2018" - -1. Select **Work** > **Plans**. For more information, see [Review team delivery plans](../../boards/plans/review-team-plans.md). - -2. To grant permissions to a group or user to manage or edit a specific plan, choose the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon to open the **Security** dialog for the plan. - - :::image type="content" source="../../boards/plans/media/permissions/open-plans-security.png" alt-text="Screenshot showing the Security button for plan permissions, highlighted by a red box."::: - -3. Add a user, team group, or other security group who you want to grant permissions to or restrict access. (For details, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md)). By default, nonadministrators can't delete or edit a plan. - -4. With the user or group selected, set the permission you want them to have to **Allow**. + - For example, here we grant permission to Raisa to edit the plan. - - :::image type="content" source="../../boards/plans/media/permissions/permissions-plans-dialog.png" alt-text="Screenshot showing the permissions dialog for a delivery plan."::: +### Default permissions for Delivery Plans -5. Choose **Save changes** when you're done. - -::: moniker-end +[!INCLUDE [temp](includes/boards-plans.md)] -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Move or permanently delete work items @@ -321,9 +315,9 @@ By default, Project Administrators and Contributors can change the work item typ For example, as a project admin you can grant a user, team group, or other group you've created to have these permissions. Open the Security page for the project and choose the user or group you want to grant permissions. To learn how to access project-level **Security**, see [Change project-level permissions](../security/change-project-level-permissions.md). > [!NOTE] -> The **Move work items out of this project** permission requires the project uses the Inherited process model. +> The **Move work items out of this project** permission requires the [Inherited process model](../settings/work/inheritance-process-model.md) for the project. -In this example, we grant members assigned to the team administrator role, who belong to the Team Admin groups, permissions to move work items to another project and to permanently delete work items. +In the following example, we granted members who are assigned to the team administrator role, and who belong to the Team Admin group, permissions to move work items to another project and permanently delete work items. :::image type="content" source="media/set-permissions-project-level-dialog.png" alt-text="Screenshot showing setting project-level permissions for a custom security group."::: @@ -346,9 +340,28 @@ Set the permissions for **Manage test plans** and **Manage test suites** to **Al To have full access to the Test feature set, your [access level must be set to Basic + Test Plans](change-access-levels.md). Users with Basic access and with permissions to permanently delete work items and manage test artifacts can only delete orphaned test cases. - +### Default permissions for test management + +Test plans, test suites, test cases and other test artifacts are specific work item types that support manual and exploratory testing. For more information, see [Set test permissions at the project level](change-project-level-permissions.md). + +[!INCLUDE [temp](includes/test.md)] + +Area permissions for web-based test case management and test execution control access to the following actions. -::: moniker range=">= azure-devops-2019" +The **Manage test suites** permission enables users to do the following tasks: +- Create and modify test suites +- Add or remove test cases to/from test suites +- Change test configurations associated with test suites +- Modify the suite hierarchy by moving a test suite + +The **Manage test plans** permission enables users to do the following tasks: +- Create and modify test plans +- Add or remove test suites to or from test plans +- Change test plan properties such as build and test settings + + + +::: moniker range="<=azure-devops" ## Customize an inherited process @@ -359,41 +372,48 @@ To customize a process, you need to grant **Edit process** permissions to a use ::: moniker-end ::: moniker range="azure-devops" - > [!NOTE] -> Users added to the **Project-Scoped Users** group won't be able to access Process settings if the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization. For more information including important security-related call-outs, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). - +> Users added to the **Project-Scoped Users** group can't access Process settings if the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization. For more information including important security-related callouts, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Open the … context menu for the inherited process and choose **Security**. To open this page, see [Customize a project using an inherited process](../settings/work/customize-process.md). :::image type="content" source="media/process/mprocess-open-security-dialog-inherited.png" alt-text="Screenshot showing open Process, Open security dialog."::: -2. Add the account name of the person you want to grant permissions to, set the permissions to **Allow** that you want them to have, and then you can exit the page and it automatically saves. - - Here we add Christie Church and allow Christie to edit the process. +2. Enter the user name, set the applicable permissions to **Allow**, and then exit. The page automatically saves. :::image type="content" source="media/process/mprocess-security-dialog-inherited.png" alt-text="Screenshot showing permissions for a process dialog."::: > [!NOTE] -> Each process is a securable unit and has individual access control lists (ACLs) that govern creating, editing, and deleting inherited processes. At the collection level, project collection administrators can choose which processes can be inherited from and by whom. When you create a new inherited process, the process creator as well as project collection administrators have full control of the process and can also set individual ACLs for other users and groups to edit and delete the process. +> Processes are securable entities with distinct ACLs for creation, editing, and deletion. **Project Collection Administrators** at the collection level determine the inherited processes. New inherited processes grant full control to the creator and Project Collection Administrators, who can also assign ACLs to others for process management. ::: moniker-end -::: moniker range="<= azure-devops-2019" - -## More options for restricting access to work items +## More access options for work items For more information about options for customizing work item types to support restrictions, see [Restrict access, Restrict modification of work items based on a user or group](restrict-access.md#restrict-modifications-wits). +### Grant team members additional permissions + +For teams to work autonomously, you may want to provide them with permissions that they don't have by default. Suggested tasks include providing team administrators or team leads permissions to: + +- [Create and edit child nodes under their default area path](set-permissions-access-work-tracking.md) +- [Create and edit child nodes under an existing iteration node](set-permissions-access-work-tracking.md) +- [Create shared queries and folders under the Shared Queries folder](../../boards/queries/set-query-permissions.md). + +By default, team members inherit the permissions afforded to members of the project Contributors group. Members of this group can add and modify source code, create and delete test runs, and create and modify work items. They can [collaborate on a Git project](../../repos/git/gitquickstart.md) or collaborate with other team members and [check in work to the team's code base (TFVC)](../../repos/tfvc/check-your-work-team-codebase.md). + +![Screenshot of default permissions assigned to team contributors.](../settings/media/add-team/default-permissions-assigned-to-team-contributors.png) + +::: moniker range="< azure-devops-2022" +If your on-premises deployment includes reporting, add users to those resources. See [Grant permissions to view or create SQL Server reports](/previous-versions/azure/devops/report/admin/grant-permissions-to-reports). ::: moniker-end ## Related articles -- [Grant or restrict access](restrict-access.md) +- [Manage permissions for specific tasks](restrict-access.md) - [Rules and rule evaluation](../settings/work/rule-reference.md) -- [Permissions and access for work tracking](permissions-access-work-tracking.md) -- [Permissions and groups reference](permissions.md) -- [Delete test artifacts](../../boards/backlogs/delete-test-artifacts.md#prerequisites) +- [Set project-level permissions](set-permissions-access-work-tracking.md) +- [Set object-level permissions](set-permissions-access-work-tracking.md) diff --git a/docs/organizations/security/stakeholder-access.md b/docs/organizations/security/stakeholder-access.md index 6fa3e74c402..328f3311914 100644 --- a/docs/organizations/security/stakeholder-access.md +++ b/docs/organizations/security/stakeholder-access.md @@ -7,45 +7,38 @@ toc: show ms.author: chcomley author: chcomley ms.topic: overview -monikerRange: '<= azure-devops' -ms.date: 08/03/2022 +monikerRange: "<=azure-devops" +ms.date: 04/07/2025 --- # Stakeholder access quick reference +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +**Stakeholder** access provides free access to a limited set of features for an unlimited number of users. Generally, **Stakeholder** access users get restricted access to Azure Boards and collaboration tools, while they don't have access to code repositories. -**Stakeholder** access is available to support free access to a limited set of features by an unlimited set of stakeholders. In general, **Stakeholder** access users gain limited access to Azure Boards, Azure Pipelines, and collaboration tools. They have no access to code repositories. +**Stakeholder** access users can create and modify work items, as well as create and save queries. They can view and approve release pipelines and perform administrative tasks if granted administrative permissions or added to an administrative group. However, if they need to contribute to the code base, assign them at least **Basic** access. -**Stakeholder** access users can create and modify work items and create and save queries. They can also view and approve release pipelines and perform administrative tasks when granted administrative permissions or added to an administrative group. If they need to contribute to the code base, then you must assign them **Basic** or higher-level access. - -If you've been assigned **Stakeholder** access and want to start using Azure Boards to track work, see [Get started as a Stakeholder](get-started-stakeholder.md). If you've been tasked to support administrative tasks, see [Manage your project](../../user-guide/project-admin-tutorial.md). +If you have **Stakeholder** access and want to start using Azure Boards to track work, see [Get started as a Stakeholder](get-started-stakeholder.md). If you're responsible for administrative tasks, see [Manage your project](../../user-guide/project-admin-tutorial.md) for guidance. - -## Assign Stakeholder access users to a security group +## Assign Stakeholder access users to a security group In general, use the following guidance when assigning **Stakeholder** access users to a security group: -- Add to the **Contributors** security group managers or users who don't actively contribute to the code base but want to check project status and provide direction, feedback, feature ideas, and business alignment to a team. -- Add to the **Project Administrators** security group users tasked with managing project resources. -- Add to the **Project Collection Administrators** security group users tasked with managing organization or collection resources. - - - +- Add to the **Contributors** security group for managers or users who don't actively contribute to the code base but want to check project status and provide direction, feedback, feature ideas, and business alignment to a team. +- Add to the **Project Administrators** security group for users tasked with managing project resources. +- Add to the **Project Collection Administrators** security group for users tasked with managing organization or collection resources. - ::: moniker range="azure-devops" - + ## Public versus private feature access -Users granted **Stakeholder** access are granted different access to features depending on whether it is a private or a public project. For private projects, Stakeholders have limited access to select work tracking functions, whereas for public projects, Stakeholders enjoy full access to work tracking features. To learn more about public projects, see [What is a public project?](../projects/about-projects.md). - +Users with **Stakeholder** access privileges can access features based on whether the project is private or public. For private projects, Stakeholders receive limited access to specific work tracking functions, whereas for public projects, Stakeholders enjoy full access to work tracking features. For more information about public projects, see [What is a public project?](../projects/about-projects.md). > [!div class="mx-tdBreakAll"] > | Service, application, or setting | Private project | Public project| @@ -65,21 +58,15 @@ Users granted **Stakeholder** access are granted different access to features de ::: moniker-end -::: moniker range=">= azure-devops-2019" ## Azure Boards -::: moniker-end - -::: moniker range="< azure-devops-2019" -## Work tracking -::: moniker-end -The following table summarizes the features Stakeholder access users have access to from Azure Boards. Stakeholders access users can view and edit all work items for which they have Area Path permissions, which by default is set to Allow for all user security groups. To learn more, see [Set permissions and access for work tracking](set-permissions-access-work-tracking.md#set-permissions-area-path). +The following table summarizes the features Stakeholders have access to from Azure Boards. Stakeholders can view and edit all work items for which they have Area Path permissions, which by default is set to Allow for all user security groups. For more information, see [Set permissions and access for work tracking](set-permissions-access-work-tracking.md#set-permissions-area-path). For an overview of work tracking features, see [What is Azure Boards?](../../boards/get-started/what-is-azure-boards.md) -::: moniker range="azure-devops" +::: moniker range="azure-devops" > [!NOTE] -> Public project **Stakeholder** access users have full access to all features. +> Users with **Stakeholder** access in public projects can view Delivery Plans, but can't add or edit them. ::: moniker-end :::row::: @@ -93,7 +80,6 @@ For an overview of work tracking features, see [What is Azure Boards?](../../boa **Features can't use** :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" :::row::: :::column span="1"::: **Work Items** @@ -112,25 +98,6 @@ For an overview of work tracking features, see [What is Azure Boards?](../../boa - Move work items to another project :::column-end::: :::row-end::: -::: moniker-end -::: moniker range="< azure-devops-2019" -:::row::: - :::column span="1"::: - **Work Items** - :::column-end::: - :::column span="2"::: - - View, add, and edit work items - - Assign existing tags to work items - - Email work items - - Apply a work item template - :::column-end::: - :::column span="2"::: - - Add new work item tags - - Delete work items - - Move work items to another project - :::column-end::: -:::row-end::: -::: moniker-end ::: moniker range=">= azure-devops-2022" :::row::: :::column span="1"::: @@ -169,26 +136,7 @@ For an overview of work tracking features, see [What is Azure Boards?](../../boa :::column-end::: :::row-end::: ::: moniker-end -::: moniker range="< azure-devops-2020" -:::row::: - :::column span="1"::: - **Boards** - :::column-end::: - :::column span="2"::: - - View boards, open and edit work items - - Add work items to a board; update status through drag-and-drop - - Add child items to a checklist - - Assign to a sprint (from card field) - - Configure team boards2 - :::column-end::: - :::column span="2"::: - - Add work items to a board - - Update status through drag-and-drop - - Change the priority of an item within a board - - Change fields on cards on a board, except for State field - :::column-end::: -:::row-end::: -::: moniker-end + :::row::: :::column span="1"::: **Backlogs** @@ -219,7 +167,7 @@ For an overview of work tracking features, see [What is Azure Boards?](../../boa - Change the priority of an item within a backlog - Change fields on cards on a Taskboard, except for State field - View or set team capacity - - Add tasks a sprint backlog + - Add tasks to a sprint backlog :::column-end::: :::row-end::: :::row::: @@ -268,85 +216,22 @@ For an overview of work tracking features, see [What is Azure Boards?](../../boa 1. Controllable through project-level permission. 2. Requires assignment as a team administrator or member of the Project Administrators Group. - -::: moniker range=">= azure-devops-2019" - -## Azure Pipelines - -::: moniker-end - - -::: moniker range="azure-devops" -The following table summarizes the features available to **Stakeholder** access users for Private and Public projects. When the **Free access to Pipelines for Stakeholders** preview feature is enabled for the organization, Stakeholders get access to all features listed under **Public project**. Without this feature enabled, **Stakeholder** access users can only view and approve releases. To learn more, see [Provide Stakeholders access to edit build and release pipelines](provide-stakeholder-pipeline-access.md). - -For an overview of pipelines features and functions, see [Continuous integration on any platform](../../pipelines/get-started/what-is-azure-pipelines.md). - -:::row::: - :::column span="2"::: - **Private project** - :::column-end::: - :::column span="2"::: - **Public project** - :::column-end::: -:::row-end::: -:::row::: - :::column span="2"::: - - View and approve releases - - View build pipelines - :::column-end::: - :::column span="2"::: - - View release pipelines - - Define builds with continuous integration - - Define releases and manage deployments - - Approve releases - - Azure Artifacts (5 users free) - - Queue builds, edit build quality - - Manage build queues and build qualities - - Manage build retention policies, delete and destroy builds - - Administer build permissions - - Manage release permissions - - Create and edit task groups - - Manage task group permissions - - Can view library items such as variable groups - - Use and manage library items such as variable groups - :::column-end::: -:::row-end::: - -::: moniker-end - - -::: moniker range=">= azure-devops-2019 < azure-devops" - -Users granted **Stakeholder** access can perform the following build and release tasks. For an overview of pipelines features and functions, see [Continuous integration on any platform](../../pipelines/get-started/what-is-azure-pipelines.md). -- View and approve releases -- View build pipelines -::: moniker-end - - -::: moniker range=">= azure-devops-2019" ## Azure Test Plans -::: moniker-end - -::: moniker range="< azure-devops-2019" -## Test -::: moniker-end -Users granted **Stakeholder** access can perform the following tasks related to testing. For an overview of manual test features and functions, see [Testing overview](../../test/index.yml). +Users with **Stakeholder** access can perform the following tasks related to testing. For an overview of manual test features and functions, see [Testing overview](../../test/index.yml). - Provide feedback using the Test & Feedback extension - Apply a work item template to a test case - ## Dashboards, notifications, READMEs, and wikis The following table summarizes the features **Stakeholder** access users have to these areas: [Dashboards](../../report/dashboards/overview.md), [Notifications](../../organizations/notifications/about-notifications.md), [Project pages](../../project/navigation/work-across-projects.md), [READMEs](../../project/wiki/about-readme-wiki.md#readmes), and [Wikis](../../project/wiki/provisioned-vs-published-wiki.md). -::: moniker range="azure-devops" +::: moniker range="azure-devops" > [!NOTE] -> Public project **Stakeholder** access users have full access to all dashboard and Wiki features. +> Users with **Stakeholder** access in public projects have full access to all dashboard and Wiki features. ::: moniker-end - :::row::: :::column span="1"::: **Feature area** @@ -372,19 +257,7 @@ The following table summarizes the features **Stakeholder** access users have to :::column-end::: :::row-end::: ::: moniker-end -::: moniker range="< azure-devops-2020" -:::row::: - :::column span="1"::: - Dashboards - :::column-end::: - :::column span="2"::: - - View dashboards - :::column-end::: - :::column span="2"::: - - Add and configure team dashboards - :::column-end::: -:::row-end::: -::: moniker-end + :::row::: :::column span="1"::: Notifications @@ -448,4 +321,4 @@ The following table summarizes the features **Stakeholder** access users have to :::row-end::: **Notes:** -1. Requires team administrator role or addition to Project Administrators group. \ No newline at end of file +1. Requires team administrator role or addition to Project Administrators group. diff --git a/docs/organizations/security/toc.yml b/docs/organizations/security/toc.yml index 7f1ac9eabb6..10ef2dc7fa8 100644 --- a/docs/organizations/security/toc.yml +++ b/docs/organizations/security/toc.yml @@ -1,325 +1,269 @@ - name: Security, Permissions, & Access href: index.yml -- name: Security quick reference index - href: quick-reference-index-security.md -- name: Security best practices - href: security-best-practices.md +- name: Security overview + href: security-overview.md - name: Get started - expanded: true items: - - name: About permissions, access, & security groups - href: about-permissions.md + - name: About permissions, access, & security groups displayName: security, group, membership, inheritance, roles + href: about-permissions.md - name: Add users to a team or project - href: add-users-team-project.md displayName: create, new, account, default, custom, access, permission - - name: View permissions - href: view-permissions.md + href: add-users-team-project.md + - name: View permissions displayName: default, project, object, valid, user, group + href: view-permissions.md - name: Request change in permissions displayName: security, role, refresh, object, collection href: request-changes-permissions.md - - name: Add or remove users or groups + - name: Manage users or groups href: add-remove-manage-user-group-security-group.md + expanded: true - name: Access levels and Stakeholder access items: - name: About access levels + displayName: security, understand, groups, levels href: access-levels.md - displayName: security, understand, groups, levels - name: Get started as a Stakeholder href: get-started-stakeholder.md - name: Stakeholder access quick reference - href: stakeholder-access.md displayName: public, private - - name: Change access levels + href: stakeholder-access.md + - name: Change access levels href: change-access-levels.md - displayName: update, security, permission, project, collection - - name: Provide Stakeholders access to edit pipelines - href: provide-stakeholder-pipeline-access.md - name: Manage user access (cloud) items: - - name: Add users & manage access - href: ../accounts/add-organization-users.md + - name: Add users & manage access displayName: create, new, identity, direct, assignment + href: ../accounts/add-organization-users.md - name: Remove users from Azure DevOps displayName: delete, revoke, organization, members - href: ../accounts/delete-organization-users.md - - name: Remove user accounts from Active Directory - displayName: delete, revoke, organization, members - href: remove-users-prohibit-access.md - - name: Manage access with Azure Active Directory + href: ../accounts/delete-organization-users.md + - name: Manage access with Microsoft Entra ID items: - - name: Connect organization to Azure AD - href: ../accounts/connect-organization-to-azure-ad.md + - name: Connect organization to Entra ID displayName: link, attach, security - - name: Add or delete users in Azure AD - href: /azure/active-directory/fundamentals/add-users-azure-active-directory?toc=/azure/devops/organizations/security/toc.json + href: ../accounts/connect-organization-to-azure-ad.md + - name: Manage users in Entra ID displayName: create, remove, account - - name: Add AD/Azure AD security groups to built-in security groups - href: add-ad-aad-built-in-security-groups.md + href: /azure/active-directory/fundamentals/add-users-azure-active-directory?toc=/azure/devops/organizations/security/toc.json + - name: Add AD or Entra ID security groups to built-in security groups displayName: update, permission, access, security + href: add-ad-aad-built-in-security-groups.md - name: Manage groups - href: ../accounts/manage-azure-active-directory-groups.md displayName: users, access, authenticate + href: ../accounts/manage-azure-active-directory-groups.md - name: Manage group rules - href: ../accounts/assign-access-levels-by-group-membership.md displayName: update, add, assignment - - name: Change Azure AD connection - href: ../accounts/change-azure-ad-connection.md + href: ../accounts/assign-access-levels-by-group-membership.md + - name: Change Entra ID connection displayName: update, add, remove - - name: Disconnect from Azure AD - href: ../accounts/disconnect-organization-from-azure-ad.md + href: ../accounts/change-azure-ad-connection.md + - name: Disconnect from Entra ID displayName: remove, update, detach, unlink - - name: Get list of organizations backed by Azure AD - href: ../accounts/get-list-of-organizations-connected-to-azure-active-directory.md + href: ../accounts/disconnect-organization-from-azure-ad.md + - name: Get list of organizations backed by Entra ID displayName: record, catalog, inventory, name, owner, URL, ID + href: ../accounts/get-list-of-organizations-connected-to-azure-active-directory.md - name: Manage user access (on-premises) items: - name: Remove users from Azure DevOps displayName: delete, revoke, organization, members - href: ../accounts/delete-organization-users.md + href: ../accounts/delete-organization-users.md - name: Remove user accounts from Active Directory displayName: delete, revoke, organization, members - href: remove-users-prohibit-access.md -- name: Billing - href: ../billing/toc.yml -- name: Authenticate, PATs, & secure applications + href: /azure/active-directory/add-users-azure-active-directory#delete-a-user?toc=/azure/devops/organizations/security/toc.json +- name: Authenticate, use PATs, & secure applications items: - name: About security, authentication, & authorization - href: about-security-identity.md displayName: concepts, understand, credentials, accounts, authorization, policies - - name: Authentication guidance - href: ../../integrate/get-started/authentication/authentication-guidance.md?toc=/azure/devops/marketplace-extensibility/toc.json + href: about-security-identity.md + - name: Authentication guidance displayName: permission, security, mechanism, type, application + href: ../../integrate/get-started/authentication/authentication-guidance.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Use personal access tokens (PATs) - href: ../accounts/use-personal-access-tokens-to-authenticate.md?toc=/azure/devops/organizations/security/toc.json displayName: permission, security, credential, sign, in + href: ../accounts/use-personal-access-tokens-to-authenticate.md?toc=/azure/devops/organizations/security/toc.json - name: Manage PATs via API - href: ../accounts/manage-personal-access-tokens-via-api.md?toc=/azure/devops/organizations/security/toc.json displayName: lifecycle, authenticate + href: ../accounts/manage-personal-access-tokens-via-api.md?toc=/azure/devops/organizations/security/toc.json - name: Revoke user PATs (for admins) - href: ../accounts/admin-revoke-user-pats.md?toc=/azure/devops/organizations/security/toc.json displayName: delete, remove, token, administrator + href: ../accounts/admin-revoke-user-pats.md?toc=/azure/devops/organizations/security/toc.json - name: Authorize access to REST APIs with OAuth 2.0 - href: ../../integrate/get-started/authentication/oauth.md?toc=/azure/devops/organizations/security/toc.json displayName: authenticate, access, token, app, security + href: ../../integrate/get-started/authentication/oauth.md?toc=/azure/devops/organizations/security/toc.json - name: Authorize access with service principals and managed identities - href: ../../integrate/get-started/authentication/service-principal-managed-identity.md?toc=/azure/devops/organizations/security/toc.json - displayName: authenticate, access, security, service, principal, managed, identity + displayName: authenticate, access, security, service, principal, managed, identity + href: ../../integrate/get-started/authentication/service-principal-managed-identity.md?toc=/azure/devops/organizations/security/toc.json - name: Use SSH key authentication - href: ../../repos/git/use-ssh-keys-to-authenticate.md?toc=/azure/devops/organizations/security/toc.json displayName: access, security - - name: Use Git Credential Manager - href: ../../repos/git/set-up-credential-managers.md?toc=/azure/devops/organizations/security/toc.json + href: ../../repos/git/use-ssh-keys-to-authenticate.md?toc=/azure/devops/organizations/security/toc.json + - name: Use Git Credential Manager displayName: authenticate, access, security + href: ../../repos/git/set-up-credential-managers.md?toc=/azure/devops/organizations/security/toc.json - name: Secure projects items: - - name: Look up a project administrator + - name: Look up a project administrator href: look-up-project-administrators.md - name: Change project-level permissions displayName: access, security, add, remove, project, administrators - href: change-project-level-permissions.md + href: change-project-level-permissions.md - name: Set object-level permissions - href: set-object-level-permissions.md displayName: artifacts, boards, repos, projects, area, iteration, path, work items, access - - name: Grant or restrict permissions to select tasks - href: restrict-access.md + href: set-object-level-permissions.md + - name: Manage permissions for specific tasks displayName: give, revoke, access, users + href: restrict-access.md - name: Set dashboard permissions - href: ../../report/dashboards/dashboard-permissions.md?toc=/azure/devops/organizations/security/toc.json displayName: access, users, view, settings + href: ../../report/dashboards/dashboard-permissions.md?toc=/azure/devops/organizations/security/toc.json - name: Set Wiki permissions - href: ../../project/wiki/manage-readme-wiki-permissions.md??toc=/azure/devops/organizations/security/toc.json displayName: project, access, settings, users - - name: Set feedback permissions - href: ../../project/feedback/give-permissions-feedback.md?toc=/azure/devops/organizations/security/toc.json - displayName: users, access, settings, response + href: ../../project/wiki/manage-readme-wiki-permissions.md??toc=/azure/devops/organizations/security/toc.json - name: Secure organizations/collections items: - name: Look up the organization owner href: look-up-organization-owner.md - - name: Look up a project collection administrator + - name: Look up a project collection administrator href: look-up-project-collection-administrators.md - name: Change permissions at the organization or collection-level displayName: Project Collection Administrators, project collection build service, add, remove, administrators, collection href: change-organization-collection-level-permissions.md - name: Set permissions to manage extensions - href: ../../marketplace/grant-permissions.md?toc=/azure/devops/organizations/security/toc.json displayName: Marketplace, access, settings, users + href: ../../marketplace/grant-permissions.md?toc=/azure/devops/organizations/security/toc.json - name: Manage access policies (cloud) items: - name: Manage security & app access policies - href: ../accounts/change-application-access-policies.md displayName: application, settings, add, update, remove + href: ../accounts/change-application-access-policies.md - name: Add external users - href: ../accounts/add-external-user.md displayName: create, outside, new, access, B2B + href: ../accounts/add-external-user.md - name: Disable Request Access policy - href: ../accounts/disable-request-access-policy.md displayName: administrator, stop, settings, policies + href: ../accounts/disable-request-access-policy.md - name: Restrict admins from inviting new users - href: restrict-invitations.md displayName: administrators, add, adding, creating, member - - name: Secure data and networks + href: restrict-invitations.md + - name: Secure data and networks items: - name: Allowed address lists & network connections - href: allow-list-ip-url.md displayName: IP, URL, accepted + href: allow-list-ip-url.md - name: Data protection overview (cloud) - href: data-protection.md displayName: about, information, security + href: data-protection.md - name: Data location (cloud) href: data-location.md displayname: Personal access tokens, PATs, basic auth, Oauth, SSH - name: Data Subject Requests for the GDPR & CCPA - href: /microsoft-365/compliance/gdpr-dsr-vsts?toc=/azure/devops/organizations/security/toc.json - - name: Credential storage (cloud) - href: credential-storage.md - displayName: password, user, name, token, safety + href: /microsoft-365/compliance/gdpr-dsr-vsts?toc=/azure/devops/organizations/security/toc.json +- name: Secure Azure Artifacts + items: + - name: Set feed permissions + displayName: artifact, create, settings + href: ../../artifacts/feeds/feed-permissions.md?toc=/azure/devops/organizations/security/toc.json - name: Secure Azure Boards items: - - name: Default Azure Boards permissions - href: permissions-access-work-tracking.md + - name: Set work tracking & plan permissions displayName: area paths, iteration paths, test, process - - name: Set work tracking & plan permissions href: set-permissions-access-work-tracking.md - displayName: area paths, iteration paths, test, process - name: Add members to a team administrator role - href: ../settings/add-team-administrator.md?toc=/azure/devops/organizations/security/toc.json - - name: Set query permissions - href: ../../boards/queries/set-query-permissions.md?toc=/azure/devops/organizations/security/toc.json -- name: Secure Azure Repos - items: - - name: Default Git repository and branch permissions - href: default-git-permissions.md - - name: Set Git repository permissions - href: ../../repos/git/set-git-repository-permissions.md?toc=/azure/devops/organizations/security/toc.json - displayName: settings, access, security - - name: Set Git branch permissions - href: ../../repos/git/branch-permissions.md?toc=/azure/devops/organizations/security/toc.json - displayName: settings, access, security - - name: Default TFVC permissions - href: default-tfvc-permissions.md - - name: Set TFVC repository permissions - href: ../../repos/tfvc/set-tfvc-repository-permissions.md?toc=/azure/devops/organizations/security/toc.json - displayName: settings, access, security - - name: Download repository permissions report - href: download-permissions-report.md - displayName: json + href: ../settings/add-team-administrator.md?toc=/azure/devops/organizations/security/toc.json + - name: Set query permissions + href: ../../boards/queries/set-query-permissions.md?toc=/azure/devops/organizations/security/toc.json + - name: Default permissions and access to Azure Boards + displayName: settings, access, security, default, permissions + href: ../../boards/get-started/permissions-access-boards.md?toc=/azure/devops/organizations/security/toc.json - name: Secure Azure Pipelines items: - name: About pipeline security roles - href: about-security-roles.md displayName: access, group, user, role + href: about-security-roles.md - name: Set pipeline permissions - href: ../../pipelines/policies/set-permissions.md?toc=/azure/devops/organizations/security/toc.json displayName: access, user, group, security + href: ../../pipelines/policies/set-permissions.md?toc=/azure/devops/organizations/security/toc.json - name: Pipelines security walkthrough - href: ../../pipelines/security/overview.md?toc=/azure/devops/organizations/security/toc.json displayName: about, overview, access, permissions + href: ../../pipelines/security/overview.md?toc=/azure/devops/organizations/security/toc.json - name: Approach to securing YAML pipelines - href: ../../pipelines/security/approach.md?toc=/azure/devops/organizations/security/toc.json displayName: security, access, how, to - - name: Repository protection - href: ../../pipelines/security/repos.md?toc=/azure/devops/organizations/security/toc.json - displayName: security, repo + href: ../../pipelines/security/approach.md?toc=/azure/devops/organizations/security/toc.json - name: Pipeline resources - href: ../../pipelines/security/resources.md?toc=/azure/devops/organizations/security/toc.json displayName: permissions, access, information - - name: Project structure - href: ../../pipelines/security/projects.md?toc=/azure/devops/organizations/security/toc.json - displayName: about, build, security + href: ../../pipelines/security/resources.md?toc=/azure/devops/organizations/security/toc.json - name: Security through templates - href: ../../pipelines/security/templates.md?toc=/azure/devops/organizations/security/toc.json displayName: access, permissions + href: ../../pipelines/security/templates.md?toc=/azure/devops/organizations/security/toc.json - name: Variables and parameters - href: ../../pipelines/security/inputs.md?toc=/azure/devops/organizations/security/toc.json displayName: inputs, security - - name: Shared infrastructure - href: ../../pipelines/security/infrastructure.md?toc=/azure/devops/organizations/security/toc.json - displayName: security + href: ../../pipelines/security/inputs.md?toc=/azure/devops/organizations/security/toc.json - name: Other security considerations - href: ../../pipelines/security/misc.md?toc=/azure/devops/organizations/security/toc.json displayName: miscellaneous, secure, details, information + href: ../../pipelines/security/misc.md?toc=/azure/devops/organizations/security/toc.json - name: Download release permissions report + displayName: json href: download-permissions-report-release.md +- name: Secure Azure Repos + items: + - name: Default Git repository and branch permissions + href: default-git-permissions.md + - name: Set Git repository permissions + displayName: settings, access, security + href: ../../repos/git/set-git-repository-permissions.md?toc=/azure/devops/organizations/security/toc.json + - name: Set Git branch permissions + displayName: settings, access, security + href: ../../repos/git/branch-permissions.md?toc=/azure/devops/organizations/security/toc.json + - name: Default TFVC permissions + href: default-tfvc-permissions.md + - name: Set TFVC repository permissions + displayName: settings, access, security + href: ../../repos/tfvc/set-tfvc-repository-permissions.md?toc=/azure/devops/organizations/security/toc.json + - name: Download repository permissions report displayName: json + href: download-permissions-report.md - name: Secure Azure Test Plans items: - name: Set permissions & access for testing - href: set-permissions-access-test.md displayName: create, update, add, user, group, security, settings -- name: Secure Azure Artifacts - items: - - name: Set package feed permissions - href: ../../artifacts/feeds/feed-permissions.md?toc=/azure/devops/organizations/security/toc.json - displayName: artifact, create, settings -- name: Secure on-premises deployments + href: set-permissions-access-test.md +- name: Secure on-premises deployments items: - name: Set up secure sockets layer - href: /azure/devops/server/admin/setup-secure-sockets-layer?toc=/azure/devops/organizations/security/toc.json displayName: security, administrator, settings + href: /azure/devops/server/admin/setup-secure-sockets-layer?toc=/azure/devops/organizations/security/toc.json - name: Web site settings & security (on-premises) - href: /azure/devops/server/admin/websitesettings?toc=/azure/devops/organizations/security/toc.json displayName: about, administrators, server, set + href: /azure/devops/server/admin/websitesettings?toc=/azure/devops/organizations/security/toc.json - name: TFSSecurity command (on-premises) - href: /azure/devops/server/command-line/tfssecurity-cmd?toc=/azure/devops/organizations/security/toc.json displayName: secure, server + href: /azure/devops/server/command-line/tfssecurity-cmd?toc=/azure/devops/organizations/security/toc.json - name: Set SQL Server report permissions - href: /previous-versions/azure/devops/report/admin/grant-permissions-to-reports displayName: create, update, user, group, access, security + href: /previous-versions/azure/devops/report/admin/grant-permissions-to-reports - name: Set SharePoint project portal permissions - href: /previous-versions/azure/devops/report/sharepoint-dashboards/set-sharepoint-permissions displayName: access, settings + href: /previous-versions/azure/devops/report/sharepoint-dashboards/set-sharepoint-permissions - name: Troubleshooting items: - name: Troubleshoot permissions - href: troubleshoot-permissions.md displayName: security, investigate, access, problem - - name: User & permissions management FAQs - href: ../accounts/faq-user-and-permissions-management.yml?toc=/azure/devops/organizations/security/toc.json - - name: Access and permissions FAQs - href: faq-permissions.yml - - name: Authenticate & invite with GitHub - href: faq-github-authentication.yml - - name: Access with Azure Active Directory FAQs - href: ../accounts/faq-azure-access.yml?toc=/azure/devops/organizations/security/toc.json + href: troubleshoot-permissions.md + - name: User & permissions management FAQs + href: ../accounts/faq-user-and-permissions-management.yml?toc=/azure/devops/organizations/security/toc.json + - name: Connect to GitHub, FAQs + href: ../../boards/github/connect-to-github.md?toc=/azure/devops/organizations/security/toc.json + - name: Access Microsoft Entra ID FAQs + href: ../accounts/faq-azure-access.yml?toc=/azure/devops/organizations/security/toc.json - name: Set up Visual Studio - href: ../accounts/faq-set-up-vs.yml?toc=/azure/devops/organizations/security/toc.json + href: ../accounts/faq-set-up-vs.yml?toc=/azure/devops/organizations/security/toc.json - name: Resolve connection issues - href: ../../user-guide/troubleshoot-connection.md?toc=/azure/devops/organizations/security/toc.json displayName: problem, project, access, organization - - name: "TF31002: Unable to connect" - href: ../projects/tf31002-unable-connect-tfs.md?toc=/azure/devops/organizations/security/toc.json + href: ../../user-guide/troubleshoot-connection.md?toc=/azure/devops/organizations/security/toc.json + - name: 'Resolve TF31002: Unable to connect' displayName: error, troubleshoot, permission, credentials, account, license -- name: Reference - items: - - name: Default permissions - href: permissions-access.md - displayName: security, group, role, Basic, administrator - - name: Permission lookup guide - href: permissions-lookup-guide.md - displayName: index, reference, manage, roles, groups - - name: Permissions & groups - href: permissions.md - - name: Security management tools - href: security-tools-reference.md - - name: Security namespaces & permissions - href: namespace-reference.md - - name: Manage security groups with CLI - href: add-manage-security-groups.md - - name: Manage permissions with CLI - href: manage-tokens-namespaces.md - - name: Enable DevSecOps with Azure and GitHub - href: /devops/devsecops/enable-devsecops-azure-github - - name: Security key concepts - href: security-glossary.md - displayName: definitions, terms, manage, authentication, permission -- name: Resources - items: - - name: Get started - href: ../../get-started/index.yml - - name: Settings & Usage - href: ../index.yml - - name: DevOps Resource Center - href: /devops/ + href: ../projects/tf31002-unable-connect-tfs.md?toc=/azure/devops/organizations/security/toc.json +- name: Billing + href: ../billing/toc.yml diff --git a/docs/organizations/security/troubleshoot-permissions.md b/docs/organizations/security/troubleshoot-permissions.md index b5da594b189..50c47c699ab 100644 --- a/docs/organizations/security/troubleshoot-permissions.md +++ b/docs/organizations/security/troubleshoot-permissions.md @@ -8,54 +8,55 @@ ms.topic: troubleshooting ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 02/24/2023 +ms.date: 02/10/2025 --- # Troubleshoot access and permission issues [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Due to the extensive security and permission structure of Azure DevOps, you might investigate why a user doesn't have access to a project, service, or feature that they expect. Find step-by-step guidance to understand and address problems a project member may be having in connecting to a project or accessing an Azure DevOps service or feature. +Due to the extensive security and permission structure of Azure DevOps, you might need to investigate why a user lacks access to a project, service, or feature they expect. Find step-by-step guidance to understand and address issues a user might encounter when connecting to a project or accessing an Azure DevOps service or feature. -Before using this guide, we recommend that you're familiar with the following content: -- [Get started with permissions, access, and security groups](about-permissions.md) -- [Default permissions and access quick reference.](permissions-access.md) -- [Quick reference index to Azure DevOps security](quick-reference-index-security.md) +## Prerequisites + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | To manage permissions or groups at the organization or collection level: Member of the [**Project Collection Administrators** security group](look-up-project-collection-administrators.md). If you created the organization or collection, you're automatically a member of this group. | +| **Recommendation** | Before using this guide, we recommend getting familiar with the following content:
      - [Get started with permissions, access, and security groups](about-permissions.md)
      - [Default permissions and access quick reference](permissions-access.md). | > [!TIP] -> When you're creating an Azure DevOps security group, label it in a way that is easy to discern if it's created to limit access. +> When you create an Azure DevOps security group, label it clearly to indicate whether it's intended to limit access. -Permissions get set at one of the following levels: -- object level -- project level -- organization or project collection level -- security role -- team administrator role +You can set permissions at the following levels: +- Object level +- Project level +- Organization or project collection level +- Security role +- Team administrator role ## Common access and permission issues -See the following most common reasons a project member can’t access a project, service, or feature: - +See the most common reasons a project member can’t access a project, service, or feature: |**Issue** |**Troubleshooting action** | |---------|---------| |Their access level doesn’t support access to the service or feature. | To determine whether it's the cause, [determine the user's access level and subscription status](#determine-a-users-access-level-and-subscription-status). | -|Their membership within a security group doesn’t support access to a feature or they have been explicitly denied permission to a feature. | To determine whether it's the cause, [trace a permission](#trace-a-permission). | -|The user has been recently granted permission, however a refresh is required for their client to recognize the changes. | Have the user [refresh or reevaluate their permissions](#refresh-or-reevaluate-permissions). | -|The user's trying to exercise a feature granted only to a team administrator for a specific team, however they haven’t been granted that role. |To add them to the role, see [Add, remove team administrator](../settings/add-team-administrator.md). | -|The user hasn’t enabled a preview feature. | Have the user open the Preview features and determine the on/off status for the specific feature. For more information, see [Manage preview features](../../project/navigation/preview-features.md). | -|Project member has been added to a limited scope security group, such as the Project-Scoped Users group. | To determine whether it's the cause, [look up the user’s security group memberships](#group-rules-with-lesser-permissions). | +|Their membership within a security group doesn’t support access to a feature or they were explicitly denied permission to a feature. | To determine whether it's the cause, [trace a permission](#trace-a-permission). | +|The user was recently granted permission but their client needs a refresh to recognize the changes. | Have the user [refresh or reevaluate their permissions](#refresh-or-reevaluate-permissions). | +|The user's trying to exercise a feature granted only to a team administrator for a specific team, however they aren't granted that role. |To add them to the role, see [Add, remove team administrator](../settings/add-team-administrator.md). | +|The user didn't enable a preview feature. | Have the user open the Preview features and determine the on/off status for the specific feature. For more information, see [Manage preview features](../../project/navigation/preview-features.md). | +|Project member was added to a limited scope security group, such as the Project-Scoped Users group. | To determine whether it's the cause, [look up the user’s security group memberships](#group-rules-with-lesser-permissions). | ### Less common access and permission issues -Less common reasons for limited access are when one of the following events has occurred: +Less common reasons for limited access are when one of the following events occurred: |**Issue** |**Troubleshooting action** | |---------|---------| |A project administrator disabled a service. In this case, no one has access to the disabled service. | To determine whether a service is disabled, see [Turn an Azure DevOps service on or off](../settings/set-services.md). | |A Project Collection Administrator disabled a preview feature, which disables it for all project members in the organization. | See [Manage preview features](../../project/navigation/preview-features.md). | |Group rules governing the user’s access level or project membership are restricting access. |See [Determine a user's access level and subscription status](#determine-a-users-access-level-and-subscription-status). | -|Custom rules have been defined to a work item type’s workflow. |see [Rules applied to a work item type that restrict select operation](#rules-applied-to-a-work-item-type-that-restrict-select-operations). | +|Custom rules were defined to a work item type’s workflow. |see [Rules applied to a work item type that restrict select operation](#rules-applied-to-a-work-item-type-that-restrict-select-operations). | ## Determine a user's access level and subscription status @@ -64,21 +65,21 @@ You can assign users or groups of users to one of the following access levels: - Basic - Basic + Test Plans - Visual Studio subscription +- GitHub Enterprise -For more information about access level restriction in Azure DevOps, see [Supported access levels](access-levels.md#supported-access-levels). +For more information about restricting access levels in Azure DevOps, see [Supported access levels](access-levels.md#supported-access-levels). -To use Azure DevOps features, users must be added to a security group with the appropriate permissions. Users also need access to the web portal. Limitations to select features get based on the access level and security group to which a user is assigned. +To use Azure DevOps features, users must be added to a security group with the appropriate permissions and have access to the web portal. Feature limitations are based on the user's access level and security group. Users can lose access for the following reasons: - |**Reason for loss of access** |**Troubleshooting action**| |---------|---------| -|The user's Visual Studio subscription has expired. | Meanwhile, this user can [work as a Stakeholder](../../organizations/security/get-started-stakeholder.md), or you can give the user Basic access until the user renews their subscription. After the user signs in, Azure DevOps restores access automatically. | +|The user's Visual Studio subscription expired. | This user can [work as a Stakeholder](../../organizations/security/get-started-stakeholder.md), or you can give the user Basic access until the user renews their subscription. After the user signs in, Azure DevOps restores access automatically. | |The Azure subscription used for billing is no longer active. | All purchases made with this subscription are affected, including Visual Studio subscriptions. To fix this issue, visit the [Azure account portal](https://portal.azure.com). | -|The Azure subscription used for billing was removed from your organization. | Learn more about [linking your organization](../billing/set-up-billing-for-your-organization-vs.md) | +|The Azure subscription used for billing was removed from your organization. | Learn more about [linking your organization](../billing/set-up-billing-for-your-organization-vs.md#set-up-billing) | -Otherwise, on the first day of the calendar month, users who haven't signed in to your organization for the longest time lose access first. If your organization has users who don't need access anymore, [remove them from your organization](../accounts/delete-organization-users.md). +Otherwise, users who didn't sign in to your organization for the longest time lose access first. If your organization has users who don't need access anymore, [remove them from your organization](../accounts/delete-organization-users.md). For more information about permissions, see [Permissions and groups](permissions.md) and the [Permissions lookup guide](permissions-lookup-guide.md). @@ -89,7 +90,7 @@ Use permission tracing to determine why a user's permissions aren't allowing the ::: moniker range=" azure-devops" -If a user's having permissions issues and you use default security groups or custom groups for permissions, you can investigate where those permissions are coming from by using our permissions tracing. Permissions issues could be because of delayed changes. It can take up to 1 hour for Azure AD group memberships or permissions changes to propagate throughout Azure DevOps. If a user's having issues that don't resolve immediately, wait a day to see if they resolve. For more information about user and access management, see [Manage users and access in Azure DevOps](../accounts/add-organization-users.md). +If a user is having permissions issues, and you use default security groups or custom groups for permissions, use tracing to investigate where those permissions are coming from. Permissions issues could be because of delayed changes. It can take up to 1 hour for Microsoft Entra group memberships or permissions changes to propagate throughout Azure DevOps. If a user's having issues that don't resolve immediately, wait a day to see if they resolve. For more information about user and access management, see [Manage users and access in Azure DevOps](../accounts/add-organization-users.md). ::: moniker-end @@ -103,7 +104,7 @@ Users can receive their effective permissions either directly or via groups. Complete the following steps so administrators can understand where exactly those permissions are coming from and adjust them, as needed. -::: moniker range="azure-devops" +::: moniker range=" azure-devops" 1. Select **Project settings** > **Permissions** > **Users**, and then select the user. @@ -119,7 +120,7 @@ The resulting trace lets you know how they're inheriting the listed permission. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="< azure-devops" 1. Select **Project settings** > **Security**, and then enter the user name into the filter box. @@ -137,38 +138,19 @@ The resulting trace lets you know how they're inheriting the listed permission. ::: moniker-end -::: moniker range="tfs-2018" - -1. Go to the Security page for the project that the user is having access problems. -2. Enter their name into the box in the upper left-hand corner. - - :::image type="content" source="media/security-page-enter-user-name.png" alt-text="Screenshot of Enter user name to view permissions, TFS 2018."::: - - You should have a user-specific view that shows what permissions they have. - -3. Trace why a user does or doesn't have any of the listed permissions. Hover over the permission, and then choose **Why**. - - :::image type="content" source="media/permissions-list-view-project-level-information.png" alt-text="Screenshot of Select Why to trace the permissions, TFS 2018."::: - -The resulting trace lets you know how they're inheriting the listed permission. You can then adjust the user's permissions by adjusting those permissions provided to the groups they're in. - -::: moniker-end - -For more information, see [Grant or restrict access to select features and functions](restrict-access.md) or [Request an increase in permission levels](request-changes-permissions.md). - - - +For more information, see [Manage access to specific features and functions](restrict-access.md) or [Request an increase in permission levels](request-changes-permissions.md). + ## Refresh or reevaluate permissions -See the following scenario where refreshing or reevaluating permissions may be necessary. +See the following scenario where refreshing or reevaluating permissions might be necessary. ### Problem ::: moniker range=" azure-devops" -Users get added to an Azure DevOps or Azure AD group. This action grants inherited access to an organization or project. But, they don't get access immediately. Users must either wait or sign out, close their browser, and then sign back in to get their permissions refreshed. +Users get added to an Azure DevOps or Microsoft Entra group. This action grants inherited access to an organization or project. But, they don't get access immediately. Users must either wait or sign out, close their browser, and then sign back in to get their permissions refreshed. ::: moniker-end @@ -180,14 +162,10 @@ Users get added to an Azure DevOps group. This action grants inherited access to ### Solution -::: moniker range=" <= azure-devops" - -Within **User settings**, on the **Permissions** page, you can select **Re-evaluate permissions**. This function reevaluates your group memberships and permissions, and then any recent changes take effect immediately. +Go to :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **User settings** > **Permissions** > **Re-evaluate permissions**. This function reevaluates your group memberships and permissions, and then any recent changes take effect immediately. :::image type="content" source="media/troubleshoot-permissions/re-evaluate-permissions-button.png" alt-text="Screenshot of Reevaluate permissions control."::: -::: moniker-end - ## Rules applied to a work item type that restrict select operations Before you customize a process, we recommend that you review [Configure and customize Azure Boards](../../boards/configure-customize.md), which provides guidance on how to customize Azure Boards to meet your business needs. @@ -200,61 +178,38 @@ For more information about work item type rules that apply toward restricting op ## Hide organization settings from users -If a user's limited to seeing only their projects, or from seeing the organization settings, the following information may explain why. To restrict users from accessing organization settings, you can enable the **Limit user visibility and collaboration to specific projects** preview feature. For more information including important security-related call-outs, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). +If a user is limited to seeing only their projects or can't access organization settings, the following information might explain why. To restrict users from accessing organization settings, enable the **Limit user visibility and collaboration to specific projects** preview feature. For more information, including important security-related call-outs, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). ::: moniker range=" azure-devops" -Examples of restricted users include Stakeholders, Azure Active Directory (Azure AD) guest users, or members of a security group. Once enabled, any user or group added to the Project-Scoped Users group gets restricted from accessing the Organization Settings pages, except for Overview and Projects. They're restricted to accessing only those projects to which they've been added. +Examples of restricted users include Stakeholders, Microsoft Entra guest users, or members of a security group. Once enabled, any user or group added to the Project-Scoped Users group is restricted from accessing the **Organization settings** pages, except for **Overview** and **Projects**. They can only access the projects to which they get added. ::: moniker-end -::: moniker range=" <= azure-devops" - -Examples of restricted users include Stakeholders, or members of a security group. Once enabled, any user or group added to the Project-Scoped Users group gets restricted from accessing the Organization Settings pages, except for Overview and Projects. They're restricted to accessing only those projects to which they've been added. +::: moniker range=" < azure-devops" +Examples of restricted users include Stakeholders, or members of a security group. Once enabled, any user or group added to the Project-Scoped Users group gets restricted from accessing the Organization Settings pages, except for Overview and Projects. They can only access the projects to which they get added. ::: moniker-end -For more information about hiding organization settings from users, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). +For more information, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). ::: moniker range=" azure-devops" ## View, add, and manage permissions with CLI -You can view, add, and manage permissions at a more granular level with the `az devops security permission` commands. For more information, see [Manage permissions with command line tool](./manage-tokens-namespaces.md). - -::: moniker-end - -::: moniker range=" < azure-devops-2019" - -### Use tools to fix permission - -You can use the following tools to fix a user's permission issue. - -- TFSSecurity.exe - TFSSecurity is a command-line tool that can be used to view and update and delete permissions or groups. - - Example usage: - `tfssecurity /a+ Identity "81e4e4b5-bde0-4f2c-a7a5-4d25c2e8a81f\" Read "Project Collection Valid Users" ALLOW /collection:{collectionUrl}` -`tfssecurity /a- Identity "3c7a0a47-27b4-4def-8d42-aab9b405fc8a\" Write n:"[Project1]\Contributors" DENY /collection:{collectionUrl}` - -- Use the public sproc - - Example usage: - Use `prc_pSetAccessControlEntry` or `prc_pRemoveAccessControlEntries` to add or remove ACEs directly from the security tables if TFSSecurity doesn't work for you. - -For more information, see [Use TFSSecurity to manage groups and permissions for Azure DevOps](/azure/devops/server/command-line/tfssecurity-cmd). +You can view, add, and manage permissions at a granular level with the `az devops security permission` commands. For more information, see [Manage permissions with command line tool](./manage-tokens-namespaces.md). ::: moniker-end - - + ::: moniker range=" azure-devops" ## Group rules with lesser permissions -Group rule types get ranked in the following order: Subscriber > Basic + Test Plans > Basic > Stakeholder. -Users always get the best access level between all the group rules, including Visual Studio (VS) subscription. +Group rule types are ranked in the following order: Subscriber > Basic + Test Plans > Basic > Stakeholder. +Users always receive the highest access level available to them across all group rules, including any Visual Studio (VS) subscriptions. [!INCLUDE [note-group-rules](includes/note-group-rules.md)] @@ -273,13 +228,15 @@ I have a Visual Studio Test Pro subscription and I'm in a group rule that gives Expected: I get detected as a Visual Studio Test Pro subscriber, because the access is the same as the group rule. I'm already paying for the Visual Studio Test Pro, so I don't want to pay again. ## Work with GitHub -See the following troubleshooting information for when you're trying to deploy code in Azure DevOps with GitHub. + +See the following troubleshooting information for deploying code in Azure DevOps with GitHub. + ### Problem - You can't bring the rest of your team into the organization and project, despite adding them as organization and project members. They receive emails but when signing in they receive an error 401. +You can't bring the rest of your team into the organization and project, despite adding them as members. They receive emails, but when signing in, they get a 401 error. ### Solution -You're likely signed into Azure DevOps with an incorrect identity. Complete the following steps. +You might be signed into Azure DevOps with an incorrect identity. Do the following steps: 1. Close all browsers, including browsers that aren't running Azure DevOps. @@ -287,14 +244,12 @@ You're likely signed into Azure DevOps with an incorrect identity. Complete the 3. Go to the following URL: https://aka.ms/vssignout. - A message displays that says, "Sign out in progress." After you sign out, you're redirected to dev.azure.microsoft.com. + A message displays, "Sign out in progress." After you sign out, you get redirected to `dev.azure.microsoft.com`. -4. Sign in to [Azure DevOps](https://dev.azure.com/VSTS-Catapult) again. Select your other identity. +4. Sign in to [Azure DevOps](https://dev.azure.com/VSTS-Catapult) again and choose a different identity. ::: moniker-end -::: moniker range=">= azure-devops-2019" - ## Other areas where permissions might be applied - [Area path permissions](set-permissions-access-work-tracking.md) @@ -307,12 +262,9 @@ You're likely signed into Azure DevOps with an incorrect identity. Complete the - [Custom backlogs and boards](../settings/work/customize-process-backlogs-boards.md) - [Custom controls](../settings/work/custom-controls-process.md) -::: moniker-end - ## Related articles - [Manage permissions with the command line tool](manage-tokens-namespaces.md) - [Change individual or group permissions](/azure/devops/organizations/security/request-changes-permissions) -- [Security best practices](security-best-practices.md) -- [Security and permission management tools](security-tools-reference.md) +- [Security overview](security-overview.md) - [Add users to an administrator role](/azure/devops/server/admin/add-administrator) diff --git a/docs/organizations/security/view-permissions.md b/docs/organizations/security/view-permissions.md index 7b533cc9750..a436d338aa9 100644 --- a/docs/organizations/security/view-permissions.md +++ b/docs/organizations/security/view-permissions.md @@ -1,86 +1,89 @@ --- title: View permissions for yourself or others titleSuffix: Azure DevOps -description: How to find what permissions you or a team member have, including project-level, collection-level, and object-level permissions +description: How you can view the permissions assigned to you or your team members, including project-level, collection-level, and object-level permissions. ms.assetid: ms.subservice: azure-devops-security +ai-usage: ai-assisted ms.topic: quickstart ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 10/17/2024 --- # View permissions for yourself or others [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Learn how to view your permissions or the permissions that are set for others in Azure DevOps. If you don't have a permission to access a feature or function, you can request it from the right resource. +In this article, learn how to view your permissions or the permissions for other users in Azure DevOps. If you don't have permission to access a feature or function, you can request it from the right resource. -Permissions are set at the collection, project, and object level as described in [Get started with permissions, access, and security groups](about-permissions.md). So to view the permissions you have, you need to open the permissions at the object, project, or collection level. - -> [!NOTE] -> This article shows how to view permissions assigned to a user at the project-level or collection-level. However, the steps are similar when you work from the Security dialog of an object. +You can set and view permissions at the following three levels: +- [Project-level](#view-project-level-permissions) +- [Organization or Collection-level](#view-organization-or-collection-level-permissions) +- [Object-level](#view-object-level-permissions) + +For more information, see [Get started with permissions, access, and security groups](about-permissions.md). ## Prerequisites -* You must have a project to connect to. If you don't have a project yet, [create one](../projects/create-project.md). -* You must be a member of the Project Valid Users Group or Project Collection Valid Users Group to view permissions. +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](add-users-team-project.md). | +| **Permissions**| Member of the **Project Valid Users** group or **Project Collection Valid Users** group.| ## View project-level permissions +Do the following steps to view project-level permissions for you or other users. + ::: moniker range="azure-devops" > [!NOTE] -> To enable the preview feature, for the new user interface for the **Project Permissions Settings Page**, see [Enable preview features](../../project/navigation/preview-features.md). +> To get the new user interface for the **Project Permissions Settings Page**, [enable the preview feature](../../project/navigation/preview-features.md). #### [Preview page](#tab/preview-page) -1. Choose **Project Settings** and then **Permissions**. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization/Your_Project}```). +2. Select **Project settings** > **Permissions**. - ![Open Project settings > Permissions](../settings/media/shared/open-project-settings-permissions-preview.png) + :::image type="content" source="../settings/media/shared/open-project-settings-permissions-preview.png" alt-text="Screenshot shows Project settings and Permissions buttons."::: -2. Choose **Users**. To filter the list, enter a name into the *Search groups or users* box. +3. Select **Users**. To filter the list, enter a name into the *Search users* box. - > [!div class="mx-imgBorder"] - > ![Screenshot of find a user or group name, preview page.](media/view-permissions/search-user-name-s154.png) + :::image type="content" source="media/view-permissions/search-user-name-s154.png" alt-text="Screenshot shows finding a user, preview page."::: -3. Choose the name you want. The project-level permissions for that user displays. These permissions are based on the groups the user belongs to or the permissions set specifically for the user's account. - > [!div class="mx-imgBorder"] - > ![Permissions set for a user account](media/view-permissions/user-permissions-s154.png) + If your project administration is done using groups, **Expand search** after you begin to enter the user name. -4. Choose **Member of** to see which security groups and teams that the user belongs to. +4. Choose the user you want. The project-level permissions for that user display. These permissions are based on the groups the user belongs to or the permissions set specifically for the user's account. + + :::image type="content" source="media/view-permissions/user-permissions-s154.png" alt-text="Screenshot shows Permissions set for a user."::: - Here we see that *Jamal Hartnett* belongs to several teams and the Project Collection Administrators group for several projects. +5. Select **Member of** to see which security groups and teams that the user belongs to. - > [!div class="mx-imgBorder"] - > ![Permissions tab, User name, Members tab](media/view-permissions/member-of-view-s154.png) + In the following example, *Jamal Hartnett* belongs to several teams and the Project Collection Administrators group for several projects. -#### [Current page](#tab/current-page) + :::image type="content" source="media/view-permissions/member-of-view-s154.png" alt-text="Screenshot shows Permissions, Member of tab."::: -1. Choose **Project Settings** and then **Security**. +#### [Current page](#tab/current-page) - *To see the full image, click to expand*. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization/Your_Project}```). +1. Select **Project settings** > **Security**. - > [!div class="mx-imgBorder"] - > [![Project Settings>Security](media/view-permissions/open-security-project-level-vert.png)](media/view-permissions/open-security-project-level-vert-expanded.png#lightbox) + :::image type="content" source="media/view-permissions/open-security-project-level-vert.png" alt-text="Screenshot shows the Project settings and Security buttons."::: -2. Begin entering the name into the *Filter users and groups* box. The system automatically shows the names that begin with the characters you enter. +1. Enter the user name into the *Filter users and groups* box. The system automatically shows the names that begin with the characters you enter. - > [!div class="mx-imgBorder"] - > ![Screenshot of find a user or group name, current page.](media/view-permissions/search-user-name-vert-nav.png) + :::image type="content" source="media/view-permissions/search-user-name-vert-nav.png" alt-text="Screenshot of find a user or group name, current page."::: -3. Choose the name you want. The project-level permissions you have set are based on the groups you belong to or the permissions set for your account. +2. Choose the user name you want. The project-level permissions are based on the groups the user belongs to or the permissions set for the user. - > [!div class="mx-imgBorder"] - > ![Project Administrators Group, Members tab](media/view-permissions/project-level-user-permissions-vsts.png) + :::image type="content" source="media/view-permissions/project-level-user-permissions-vsts.png" alt-text="Screenshot shows Project Administrators Group, Members tab."::: -4. Choose **Member of** to see which security groups the user belongs to. +3. Select **Member of** to see which security groups the user belongs to. - Here we see that *Jamal Hartnett* belongs to several teams and the Project Collection Administrators group. + In the following example, *Jamal Hartnett* belongs to several teams and the Project Collection Administrators group. - > [!div class="mx-imgBorder"] - > ![Security tab, User name, Members tab](media/view-permissions/project-level-member-of-permissions-vsts.png) + :::image type="content" source="media/view-permissions/project-level-member-of-permissions-vsts.png" alt-text="Screenshot shows Security tab, User name, Members tab."::: * * * @@ -88,88 +91,74 @@ Permissions are set at the collection, project, and object level as described in ::: moniker range="< azure-devops" -1. Open **Project Settings**. Choose the ![gear icon](media/icons/gear_icon.png) gear settings icon, and choose **Security**. +1. Open **Project settings**. Choose the ![gear icon](media/icons/gear_icon.png) gear settings icon, and select **Security**. - > [!div class="mx-imgBorder"] - > ![Open Project Settings>Security, previous nav](media/view-permissions/open-project-level-security-horz.png) + :::image type="content" source="media/view-permissions/open-project-level-security-horz.png" alt-text="Screenshot shows Open Project Settings, Security, previous nav."::: -2. Begin entering the name into the *Filter users and groups* box. The system automatically shows the names that begin with the characters you enter. +2. Enter the user name into the *Filter users and groups* box. The system automatically shows the names that begin with the characters you enter. - ![Find a user account name](media/view-permissions/search-user-name.png) + :::image type="content" source="media/view-permissions/search-user-name.png" alt-text="Screenshot shows searching for user name."::: -3. Choose the name you want. The project-level permissions you have set are based on the groups you belong to or the permissions set for your account. +3. Choose the user name you want. The project-level permissions are based on the groups the user belongs to or the permissions set for the user. - > [!div class="mx-imgBorder"] - > ![Project level permissions for a user, TFS](media/view-permissions/project-level-user-permissions-tfs.png) + :::image type="content" source="media/view-permissions/project-level-user-permissions-tfs.png" alt-text="Screenshot shows Project level permissions for a user."::: - For a description of each permission, see [Permissions and groups reference](permissions.md#project-level). +4. Select **Member of** to see which security groups the user belongs to. -4. Choose **Member of** to see which security groups the user belongs to. + In the following example, *Jamal Hartnett* belongs to several teams and the Project Collection Administrators group. - Here we see that *Jamal Hartnett* belongs to several teams and the Project Collection Administrators group. + :::image type="content" source="media/view-permissions/view-permissions-member-of.png" alt-text="Screenshot shows Web portal, Security tab, User name, Members of."::: - ![Web portal, Security tab, User name, Members of](media/view-permissions/view-permissions-member-of.png) - - For a description of each group, see [Permissions and groups reference](permissions.md#project-level-groups). +For more information, see [Permissions and groups reference](permissions.md#project-level-groups). ::: moniker-end +> [!TIP] +> If there's an asterisk (*) next to a 'Deny' permission, it indicates that the denial applies to all child objects or resources under the specified scope. This means that if a user is denied a permission at a higher level, they're also denied that permission for all related resources, regardless of any other permissions that might be granted at lower levels. +> +> For example, if a user has 'Deny' permission for 'View project' with an asterisk (*) at the project level, they can't view any of the repositories, boards, or pipelines within that project, even if they are granted 'Allow' permissions at those lower levels. + ## View organization or collection-level permissions -Open admin settings for the organization or a project collection. +Do the following steps to view organization or collection-level permissions for you or other users. ::: moniker range="azure-devops" -1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Then choose **Organization settings**. +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Select **Organization settings**. - > [!div class="mx-imgBorder"] - > ![Open Organization settings](../../media/settings/open-admin-settings-vert.png) + :::image type="content" source="../../media/settings/open-admin-settings-vert.png" alt-text="Screenshot shows Organization settings button."::: -2. Choose **Permissions**, the **Project Collection Administrators** group, and then **Members**. +2. Select **Permissions** > **Project Collection Administrators** > **Members**. - > [!div class="mx-imgBorder"] - > ![Permissions, Project Collection Administrators group, Members tab](media/view-permissions/project-collection-admin-users-s154.png) + :::image type="content" source="media/view-permissions/project-collection-admin-users-s154.png" alt-text="Screenshot shows Members tab in Permissions for Project Collection Administrators group."::: -3. Follow steps 2 through 4 in the procedure outlined previously for view project-level permissions. +3. View the user's permissions and group membership. For more information, see the previous steps in [View project-level permissions](#view-project-level-permissions). ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - -1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Then choose **Admin settings**. +::: moniker range=" < azure-devops" - > [!div class="mx-imgBorder"] - > ![Open Organization settings](../../media/settings/open-admin-settings-vert.png) +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). +2. Select **Admin settings**. -1. Choose **Security**, the **Project Collection Administrators** group, and then **Members**. + :::image type="content" source="../../media/settings/open-admin-settings-vert.png" alt-text="Screenshot shows the Admin settings button."::: - > [!div class="mx-imgBorder"] - > ![Security, Project Collection Administrators group, Members tab](media/view-permissions/collection-admins-vert.png) +3. Select **Security** > **Project Collection Administrators** > **Members**. -2. Follow steps 2 through 4 in the procedure outlined previously for view project-level permissions. +4. View the user's permissions and group membership. For more information, see the previous steps in [View project-level permissions](#view-project-level-permissions). ::: moniker-end -::: moniker range="tfs-2018" -1. Choose the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: settings icon and select **Organization settings** or **Collection settings**. - - > [!div class="mx-imgBorder"] - > ![Open Organization Settings](../../media/settings/open-account-settings.png) - -1. Choose **Security**, **Project Collection Administrators** group, and then **Members**. - - ![Security, Project Collection Administrators group, Members tab](media/view-permissions/collection-admins.png) - -2. Follow steps 2 through 4 in the procedure outlined previously for view project-level permissions. - -::: moniker-end ## View object-level permissions -You can define the security or permissions for a number of objects. You access them from the context menu of the object. +Do the following steps to view object-level permissions for you or other users. -From the web portal, open the Security dialog for the object whose permissions you want to set. For specific instructions, see the following articles: +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +2. Go to the object and open the Security dialog for the object. + For specific instructions, see the following articles: :::row::: :::column span="1"::: @@ -181,10 +170,10 @@ From the web portal, open the Security dialog for the object whose permissions y :::row-end::: :::row::: :::column span="1"::: - Wiki & Dashboard permissions + Wiki & dashboard permissions :::column-end::: :::column span="1"::: - - [README & Wiki](../../project/wiki/manage-readme-wiki-permissions.md) + - [README & wiki](../../project/wiki/manage-readme-wiki-permissions.md) - [Dashboards](../../report/dashboards/dashboard-permissions.md) :::column-end::: :::row-end::: @@ -196,14 +185,14 @@ From the web portal, open the Security dialog for the object whose permissions y - [Git branch](../../repos/git/branch-permissions.md) - [Git repository](../../repos/git/set-git-repository-permissions.md) - [TFVC](../../repos/tfvc/set-tfvc-repository-permissions.md) - - [Builds](../../pipelines/policies/set-permissions.md) - - [Release pipeline security](../../pipelines/policies/set-permissions.md) + - [Builds](../../pipelines/policies/permissions.md#pipeline-permissions) + - [Release pipeline security](../../pipelines/policies/permissions.md#release-pipeline-permissions) - [Approvals and approvers](../../pipelines/release/approvals/index.md) :::column-end::: :::row-end::: :::row::: :::column span="1"::: - Azure Boards/Work tracking permissions + Azure Boards & work tracking permissions :::column-end::: :::column span="1"::: - [Area and iteration paths](../../organizations/security/set-permissions-access-work-tracking.md) @@ -217,8 +206,7 @@ From the web portal, open the Security dialog for the object whose permissions y > [!div class="nextstepaction"] > [Look up a member of the Project Administrators group](look-up-project-administrators.md) - ## Related articles - [Troubleshoot permissions](troubleshoot-permissions.md) -- [Permissions and role lookup guide](permissions-lookup-guide.md) \ No newline at end of file +- [Look up permissions and roles](permissions-lookup-guide.md) diff --git a/docs/organizations/settings/about-areas-iterations.md b/docs/organizations/settings/about-areas-iterations.md index 98ece520eb3..b74ba988126 100644 --- a/docs/organizations/settings/about-areas-iterations.md +++ b/docs/organizations/settings/about-areas-iterations.md @@ -1,28 +1,29 @@ --- title: How are area and iteration paths used? titleSuffix: Azure DevOps -description: Understand how area paths and iteration paths are used in Azure DevOps. +description: Learn how to effectively use area paths and iteration paths in Azure DevOps to organize and manage your projects. ms.subservice: azure-devops-settings ms.custom: teams, linked-from-support ms.author: chcomley author: chcomley ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ai-usage: ai-assisted +ms.date: 10/17/2024 --- -# About area and iteration (sprint) paths +# Area and iteration paths [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Area paths allow you to group work items by team, product, or feature area. Iteration paths allow you to group work into sprints, milestones, or other event-specific or time-related period. Both these fields allow you to define a hierarchy of paths. +Area paths group work items by team, product, or feature area. Iteration paths group work into sprints, milestones, or other time-related periods. Both fields support hierarchical paths. -You define area and iteration paths for a project. Teams can then choose which paths are used to support their backlog and other Agile tools. To understand how Agile tools use area and iteration paths, see [Agile tools that rely on areas and iterations](about-teams-and-settings.md). +Define area and iteration paths for a project, and teams can select which paths to use for their backlog and Agile tools. Learn how Agile tools use these paths in [Agile tools that rely on areas and iterations](about-teams-and-settings.md). ::: moniker range="azure-devops" -> [!NOTE] -> Area paths and iteration paths are also referred to as *Classification Nodes*. You can manage them programmatically via the [Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) or the Azure DevOps CLI command [az boards iteration](/cli/azure/boards/iteration). +> [!NOTE] +> Area paths and iteration paths are also known as *Classification Nodes*. You can manage them programmatically using the [Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) or the Azure DevOps CLI command [az boards iteration](/cli/azure/boards/iteration). ::: moniker-end @@ -33,8 +34,7 @@ You define area and iteration paths for a project. Teams can then choose which p ::: moniker-end - -The areas and iterations you see depend on the process you used to create your project. Here we show the defaults defined for the Scrum process. No dates are set. You set dates to correspond to your sprint or release schedules. +The areas and iterations depend on the process used to create your project. This example shows the default settings for the Scrum process. Dates aren't set by default; you need to set dates to match your sprint or release schedules. > [!div class="mx-tdBreakAll"] > |Iterations| Areas | @@ -44,68 +44,64 @@ The areas and iterations you see depend on the process you used to create your p [!INCLUDE [note-delete-area-paths](../../boards/includes/note-delete-area-paths.md)] - - ## Define and assign area paths -If you're new to managing projects and teams, the most straight forward sequence for configuring your project and teams is as follows. +If you're new to managing projects and teams, follow these steps to configure your project and teams: -1. Determine the number and names of **Area Paths** that you want to support to categorize your work. At a minimum, add one area path for each team that you define. -2. Determine the number and names of teams you want to support. For guidance, review [About teams and Agile tools](about-teams-and-settings.md). -3. Open **Project settings > Project configuration** and define the area paths to support steps 1 and 2 at the project level. Follow the steps provided later in this article: [Open Project Settings, Project configuration](set-area-paths.md#open-project-settings) and [Add area paths](set-area-paths.md#add-areas). -4. Define the teams you need to support step 2. For guidance, see [Add a team, move from one default team to several teams](add-teams.md). -5. Open the team configuration and assign the default and additional area path(s) to each team. Follow the steps provided later in this article: [Open team settings](set-area-paths.md#open-team-settings) and [Set team default area path(s)](set-area-paths.md#team-area-paths). -6. Assign the area path of work items to an area path you defined. Use [bulk modify](../../boards/backlogs/bulk-modify-work-items.md) to modify several work items at once. +1. **Determine area paths**: Identify the number and names of **Area Paths** needed to categorize your work. At a minimum, add one area path for each team you define. +2. **Decide on teams**: Decide on the number and names of teams you want to support. For more information, see [About teams and Agile tools](about-teams-and-settings.md). +3. **Define area paths**: Define the area paths to support steps 1 and 2 at the project level. Follow these steps: [Add area paths](set-area-paths.md#add-an-area-path). +4. **Define teams**: Define the teams needed to support step 2. For more information, see [Add a team, move from one default team to several teams](add-teams.md). +5. **Configure team settings**: Use these steps to [assign the default and other area paths](set-area-paths.md#set-team-area-paths) to each team. +6. **Assign work items**: Assign work items to the area paths you defined. Use [bulk modify](../../boards/backlogs/bulk-modify-work-items.md) to modify several work items at once. -> [!NOTE] -> Organizations are limited to defining a maximum of 10,000 **Area Paths**, and assigning a maximum of 300 **Area Paths** to a single team. To learn more, see [Work tracking, process, and project limits](work/object-limits.md). +> [!NOTE] +> You can define up to 10,000 **Area Paths** per project and assign up to 300 **Area Paths** to a single team. For more information, see [Work tracking, process, and project limits](work/object-limits.md). > -> Also, while you can assign the same **Area Path** to more than one team, this can cause problems if two teams claim ownership over the same set of work items. To learn more, see [About boards and Kanban, Limitations of multi-team Kanban board views](../../boards/boards/kanban-overview.md#limits-multi-team). +> You can assign the same **Area Path** to more than one team, but this can cause problems if two teams claim ownership over the same set of work items. For more information, see [Limitations of multi-team board views](../../boards/boards/kanban-overview.md). -As needed, you can do the following actions at any time: +You can do the following actions at any time: -- Add additional child nodes +- Add more child nodes - Rename an area path (except the root area path) - Move a child node under another node - Delete a child node - Rename a team - Change the area path assignments made to a team -See also, [Configure a hierarchy of teams](../../boards/plans/configure-hierarchical-teams.md). +For more information, see [Configure a hierarchy of teams](../../boards/plans/configure-hierarchical-teams.md). ## How many areas should a team define? -You add areas to support your team's trace-ability and security requirements. Use areas to represent logical or physical components, and then create child areas to represent specific features. - -Add areas when you have these requirements: -* Filter queries based on a product or feature area -* Organize or group work items by team or subteams -* Restrict access to work items based on their area. +Add areas to support your team's traceability and security requirements. Use areas to represent logical or physical components, and create child areas to represent specific features. -Each team can create a hierarchy of areas under which the team can organize their backlog items, user stories, requirements, tasks, and bugs. +Add areas when you need to do any of the following tasks: +- Filter queries based on a product or feature area +- Organize or group work items by team or subteams +- Restrict access to work items based on their area -Avoid creating an area structure that is too complex. You can create areas to partition permissions on work items, but complex trees require significant overhead for permission management. You might find that it's too much work to duplicate the structure and permissions in other projects. +Each team can create a hierarchy of areas to organize their backlog items, user stories, requirements, tasks, and bugs. +Avoid creating an overly complex area structure. While you can use areas to partition permissions on work items, complex trees require significant overhead for permission management. Duplicating the structure and permissions in other projects can become cumbersome. - ## Define and assign iteration paths -Use the following guidance to configure **Iteration Paths** for your project and teams: +Follow these steps to configure **Iteration Paths** for your project and teams: -1. First, define the area paths and teams following the guidance provided in [Define area paths and assign to a team](set-area-paths.md#guidance). -1. Determine the length of the iteration you want to support. Recommended practice is to have all teams use the same sprint cadence. -2. Determine if you want a flat structure or hierarchy of sprints and releases. -3. Open **Project settings > Project configuration** and define the iteration paths to support steps 2 and 3 at the project level. Follow the steps provided later in this article: [Open Project Settings, Project configuration](set-iteration-paths-sprints.md#open-project-settings) and [Add iterations and set iteration dates](set-iteration-paths-sprints.md#iterations). -4. Open the team configuration and assign the default, backlog, and additional iteration path(s) to each team. Follow the steps provided later in this article: [Open team settings](set-iteration-paths-sprints.md#open-team-settings) and [Set team default iteration path(s)](set-iteration-paths-sprints.md#activate). -5. Each team should assign an iteration path to their work items that falls under the **Backlog iteration** path. Those work items will then show up on their product backlogs and boards. Use [bulk modify](../../boards/backlogs/bulk-modify-work-items.md) to modify several work items at once. See also [Assign backlog items to a sprint](../../boards/sprints/assign-work-sprint.md). +1. Define the area paths and teams using the guidance in [Define area paths and assign to a team](set-area-paths.md#get-started). +2. Determine the length of the iteration you want to support. We recommend that all teams use the same sprint cadence. +3. Decide whether you want a flat structure or a hierarchy of sprints and releases. +4. Define the iteration paths to support steps 2 and 3 at the project level. Follow these steps: [Add iterations and set iteration dates](set-iteration-paths-sprints.md#add-iterations-and-set-iteration-dates). +5. Open the team configuration and assign the default, backlog, and other iteration paths to each team. Follow these steps: [Open team settings](set-iteration-paths-sprints.md#list-team-iterations) and [Set team default iteration paths](set-iteration-paths-sprints.md#list-team-iterations). +6. Each team should assign an iteration path to their work items that falls under the **Backlog iteration** path. These work items appear on their product backlogs and boards. Use [bulk modify](../../boards/backlogs/bulk-modify-work-items.md) to modify several work items at once. See also [Assign backlog items to a sprint](../../boards/sprints/assign-work-sprint.md). > [!NOTE] -> Organizations are limited to defining a maximum of 10,000 **Iteration Paths**, and assigning a maximum of 300 **Iteration Paths** to a single team. To learn more, see [Work tracking, process, and project limits](work/object-limits.md). +> You can define up to 10,000 **Iteration Paths** per project and assign up to 300 **Iteration Paths** to a single team. For more information, see [Work tracking, process, and project limits](work/object-limits.md). - -As needed, you can do the following actions at any time: -- Add additional child iteration nodes +You can do the following actions at any time: + +- Add more child iteration nodes - Rename an iteration path (except the root path) - Move a child iteration path under another node - Delete a child iteration path @@ -113,57 +109,39 @@ As needed, you can do the following actions at any time: ## How many iterations should a team define? -You define as many child iterations as you need to reflect your project lifecycle. These paths represent a series of events, such as sprints, pre-beta and beta results, and other release milestones. A team usually leaves work items assigned to the team's default iteration if they aren't yet scheduled for work or for a release. +Define as many child iterations as needed to reflect your project lifecycle. These iterations can represent various events, such as sprints, prebeta and beta phases, and other release milestones. Teams typically leave work items assigned to the team's default iteration if they aren't yet scheduled for work or release. -Add iterations to support these requirements: -* Define sprints your Scrum teams use to [plan and execute their sprints](../../boards/sprints/assign-work-sprint.md) +Add iterations to support the following requirements: +* Define sprints for your Scrum teams to [plan and execute their sprints](../../boards/sprints/assign-work-sprint.md) * Set up more complex multi-release and sprint cycles -* Filter queries based on sprints, milestones, or cycle time for your project -* Support future work that you're not ready to assign to a target release cycle. +* Filter queries based on sprints, milestones, or cycle time for your project +* Support future work that isn't ready to be assigned to a target release cycle. -In the following example, Beta 1, Beta 2, Release 1.0, and Release 2.0 are defined for the MyApplication project. +In the following example, Beta 1, Beta 2, Release 1.0, and Release 2.0 are defined for the MyApplication project. -Flat iteration hierarchy +Screenshot of Flat iteration hierarchy. -As you create the backlog of product features and tasks, assign them to milestones. Assign the features and task by which you expect the team to finish. -As your needs change, you can add events under each major milestone that reflect how your team schedules and manages its work. +As you create the backlog of product features and tasks, assign them to milestones based on when you expect the team to complete them. As your needs change, you can add events under each major milestone to reflect how your team schedules and manages its work. -As the following example shows, the Beta 1 iteration now contains three child nodes, one for each sprint in the Beta 1 time period. +For example, the Beta 1 iteration now contains three child nodes, one for each sprint in the Beta 1 time period. -Hierarchical Iteration Hierarchy +Screenshot of Hierarchical Iteration Hierarchy. -Iterations don't enforce any rules. For example, you can assign a task to an iteration but not close or complete it during that iteration. At the end of an iteration, you should find all work items that remain active or open for that iteration and take appropriate action. You can, for example, move them to a different iteration or return them to the backlog. +Iterations don't enforce any rules. For example, you can assign a task to an iteration without closing or completing it during that iteration. At the end of an iteration, identify all work items that remain active or open and take appropriate action. You can move them to a different iteration or return them to the backlog. +You can run queries to find features and work items that are assigned to a specific iteration or a set of iterations and then bulk modify the work items to change their iteration paths. For more information, see [Query by date or current iteration](../../boards/queries/query-by-date-or-current-iteration.md) - ## Naming restrictions The **Area Path** and **Iteration Path** fields, [data type=TreePath](../../boards/work-items/work-item-fields.md), consist of multiple node items separated by the backslash (\) character. Minimize the names of nodes and make sure you conform to the following restrictions when you're adding child nodes. - [!INCLUDE [area-iteration-paths](includes/name-restrictions/area-iteration-paths.md)] - - -::: moniker range="tfs-2018" - -## Supported field rules - -You can [specify only a small subset of rules](../../organizations/settings/work/rule-reference.md#system), such as ```HELPTEXT``` and ```READONLY``` to System.XXX fields. - -::: moniker-end - - ## Related articles - -As you can see, areas and iterations play a major role in supporting Agile tools and managing work items. You can learn more about working with these fields from the following articles. - [Define area paths and assign to a team](set-area-paths.md) -- [Define iteration (sprint) paths and configure team iterations](set-iteration-paths-sprints.md) -- [Agile tools and sprint definitions](../../boards/sprints/define-sprints.md) -- [Query by date or current iteration](../../boards/queries/query-by-date-or-current-iteration.md) - - - +- [Define iteration paths and configure team iterations](set-iteration-paths-sprints.md) +- [Use Agile tools and define sprints](../../boards/sprints/define-sprints.md) +- [Query by date or current iteration](../../boards/queries/query-by-date-or-current-iteration.md) diff --git a/docs/organizations/settings/about-settings.md b/docs/organizations/settings/about-settings.md index 0c4df0527a0..568ebb0f4cb 100644 --- a/docs/organizations/settings/about-settings.md +++ b/docs/organizations/settings/about-settings.md @@ -16,12 +16,12 @@ ms.date: 07/27/2022 ::: moniker range="azure-devops" -You configure resources either for yourself or for your team, project, or organization from an administrative **Settings** page. The settings you can configure depend on the security group or administrative role that you belong to. +You can configure resources for yourself, your team, project, or organization from the administrative **Settings** page. The settings available to you depend on your security group membership or administrative role. -If you're just getting started as a Project Administrator, see [Get started as an administrator](../../user-guide/project-admin-tutorial.md). To quickly find a setting or related settings, see [Search organization settings](search-settings.md). +If you're new to being a Project Administrator, see [Get started as an administrator](../../user-guide/project-admin-tutorial.md) for a comprehensive guide. > [!NOTE] -> You can delegate several tasks to a user with Stakeholder or Basic access by adding them to the [**Project Collection Administrators** group](../security/change-organization-collection-level-permissions.md). For more information about Stakeholder access, see [Stakeholder access quick reference](../security/stakeholder-access.md). +> You can delegate several tasks to a user with Basic or Stakeholder access by adding them to the [**Project Collection Administrators** group](../security/change-organization-collection-level-permissions.md). For more information, see [Stakeholder access quick reference](../security/stakeholder-access.md). ::: moniker-end @@ -35,7 +35,7 @@ If you're just getting started as a Project Administrator, see [Get started as a ## User settings -Individual contributors can set their user preferences, enable features that are in preview, and manage their favorites and notifications. +Individual contributors can customize their experience in Azure DevOps by setting user preferences, enabling preview features, and managing their favorites and notifications. The following table outlines the various user settings available: :::row::: :::column span="1"::: @@ -64,20 +64,7 @@ Individual contributors can set their user preferences, enable features that are :::row-end::: --- ::: moniker-end -::: moniker range="< azure-devops-2020" -:::row::: - :::column span="1"::: - **General** - :::column-end::: - :::column span="2"::: - - [Set your preferences](set-your-preferences.md) - :::column-end::: - :::column span="2"::: - For an overview of default permission assignments by role, see [Default permissions and access](../security/permissions-access.md) - :::column-end::: -:::row-end::: ---- -::: moniker-end + :::row::: :::column span="1"::: **Security** @@ -144,18 +131,18 @@ Individual contributors can set their user preferences, enable features that are - [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md) :::column-end::: :::column span="2"::: - Notifications alert you through email messages when changes occur to work items, code reviews, pull requests, source control files, builds, and more. When a project is created, a number of notifications are defined. If you want to opt out of these, you can. + Notifications alert you through email messages when changes occur to work items, code reviews, pull requests, source control files, builds, and more. When a project is created, a number of notifications are defined. If you want to opt out, you can. :::column-end::: :::row-end::: --- - + ## Team administrator role and managing teams -Team administrators configure team resources, which mostly correspond to Agile tools and dashboards. To configure team resources, you must be added as a [team administrator for the specific team](../../organizations/settings/add-team-administrator.md), or be a member of the Project Administrators or Project Collection Administrators groups. +Team administrators are responsible for configuring team resources, which primarily include Agile tools and dashboards. To configure these resources, get added as a [team administrator for the specific team](../../organizations/settings/add-team-administrator.md) or be a member of the Project Administrators or Project Collection Administrators groups. -For a complete overview of all Agile tools that you can configure, see [Manage teams and configure team tools](manage-teams.md). +The following table provides an overview of the Agile tools and resources that team administrators can configure. For a comprehensive guide, see [Manage teams and configure team tools](manage-teams.md). :::row::: :::column span="1"::: @@ -189,13 +176,12 @@ For a complete overview of all Agile tools that you can configure, see [Manage t :::column span="2"::: - [Backlog levels](select-backlog-navigation-levels.md?toc=/azure/devops/organizations/settings/toc.json&bc=/azure/devops/organizations/settings/breadcrumb/toc.json) - [Show bugs on backlogs & boards](show-bugs-on-backlog.md) - - [Set working days](set-working-days.md?toc=/azure/devops/organizations/settings/toc.json&bc=/azure/devops/organizations/settings/breadcrumb/toc.json) - [Configure area paths](set-area-paths.md?toc=/azure/devops/organizations/settings/toc.json&bc=/azure/devops/organizations/settings/breadcrumb/toc.json) - [Select active iteration paths (sprints)](set-iteration-paths-sprints.md?toc=/azure/devops/organizations/settings/toc.json&bc=/azure/devops/organizations/settings/breadcrumb/toc.json) - [Define work item templates](../../boards/backlogs/work-item-template.md?toc=/azure/devops/organizations/settings/toc.json&bc=/azure/devops/organizations/settings/breadcrumb/toc.json) :::column-end::: :::column span="2"::: - For an overview of team resources, see [About teams and Agile tools](about-teams-and-settings.md). You configure Kanban boards from the board view - [Columns](../../boards/boards/add-columns.md), [Swimlanes](../../boards/boards/expedite-work.md), [Cards](../../boards/boards/customize-cards.md), [WIP limits](../../boards/boards/wip-limits.md). + For an overview of team resources, see [About teams and Agile tools](about-teams-and-settings.md). Configure boards from the board view - [Columns](../../boards/boards/add-columns.md), [Swimlanes](../../boards/boards/expedite-work.md), [Cards](../../boards/boards/customize-cards.md), [WIP limits](../../boards/boards/wip-limits.md). :::column-end::: :::row-end::: --- @@ -225,8 +211,7 @@ For a complete overview of all Agile tools that you can configure, see [Manage t :::row-end::: --- - - + ## Project Administrator role and managing projects @@ -248,24 +233,13 @@ From the administrative **Project settings** page, you can configure settings av ![Screenshot of Project settings page, Azure DevOps Server 2022.](media/about/project-settings-server-2022.png) ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops-2022" +::: moniker range=" [!NOTE] -> Project settings differ depending on your on-premises TFS version. Some settings aren't available for earlier versions of TFS. - -::: moniker-end - :::row::: :::column span="1"::: **Area** @@ -307,7 +281,7 @@ From the administrative **Project settings** page, you can configure settings av :::row-end::: --- ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: **Services** @@ -349,7 +323,7 @@ From the administrative **Project settings** page, you can configure settings av - [Set dashboard permissions](../security/../../report/dashboards/dashboard-permissions.md) - [Set Wiki permissions](../../project/wiki/manage-readme-wiki-permissions.md) - [Set feedback permissions](/previous-versions/azure/devops/project/feedback/give-permissions-feedback) - - [Set build and release permissions](../../pipelines/policies/set-permissions.md) + - [Set build and release permissions](../../pipelines/policies/permissions.md#pipeline-permissions) :::column-end::: :::column span="2"::: Project Administrators can add users to a project or a team. When you add a user to a team, you automatically add them to the project. Users added to a project can only view and contribute to that specific project. For an overview of security concepts, see [Get started with permissions, access, and security groups](../security/about-permissions.md) and [About access levels](../security/access-levels.md). For a list of project-level permissions, see [Permissions and groups reference, Project-level permissions](../security/permissions.md#project-level-permissions). @@ -376,7 +350,7 @@ From the administrative **Project settings** page, you can configure settings av - [Configure service hooks](../../service-hooks/overview.md) :::column-end::: :::column span="2"::: - With service hooks, you can automate a task on other services, such as [Campfire, HipChat, and more](../../service-hooks/overview.md). You can use service hooks in custom apps and services to drive activities as events happen. + With service hooks, you can automate a task on other services, such as [Trello, Datadog, and more](../../service-hooks/overview.md). You can use service hooks in custom apps and services to drive activities as events happen. :::column-end::: :::row-end::: --- @@ -401,7 +375,7 @@ From the administrative **Project settings** page, you can configure settings av - [Define iteration paths or sprints](set-iteration-paths-sprints.md) :::column-end::: :::column span="2"::: - Area and iteration paths set at the project level are then used to set team defaults. To configure additional product backlogs, Kanban boards, and dashboards, you first [add a team](add-teams.md). + Area and iteration paths set at the project level are then used to set team defaults. To configure more product backlogs, boards, and dashboards, you first [add a team](add-teams.md). :::column-end::: :::row-end::: --- @@ -416,7 +390,7 @@ From the administrative **Project settings** page, you can configure settings av - [Set retention policies](../../pipelines/policies/retention.md) :::column-end::: :::column span="2"::: - Area and iteration paths set at the project level are then used to set team defaults. To configure additional product backlogs, Kanban boards, and dashboards, you first [add a team](add-teams.md). + Area and iteration paths set at the project level are then used to set team defaults. To configure more product backlogs, boards, and dashboards, you first [add a team](add-teams.md). :::column-end::: :::row-end::: --- @@ -425,7 +399,7 @@ From the administrative **Project settings** page, you can configure settings av **Repos, Code version control** :::column-end::: :::column span="2"::: - - [Create additional Git repositories](../../repos/git/creatingrepo.md) + - [Create Git repositories](../../repos/git/creatingrepo.md) - [Set Git repository permissions](../../repos/git/set-git-repository-permissions.md) - [Set TFVC repository permissions](../../repos/tfvc/set-tfvc-repository-permissions.md) - [Manage branch policies](../../repos/git/branch-policies.md) @@ -510,7 +484,7 @@ From the administrative **Project settings** page, you can configure settings av **Service connections** :::column-end::: :::column span="2"::: - - [Manage service connections in Azure Pipelines](../../pipelines/library/service-endpoints.md#project-level-permissions) + - [Manage service connections in Azure Pipelines](../../pipelines/policies/permissions.md#set-service-connection-project-permissions) :::column-end::: :::column span="2"::: For more information, see a [list of common service connection types](../../pipelines/library/service-endpoints.md#common-service-connection-types). @@ -518,7 +492,7 @@ From the administrative **Project settings** page, you can configure settings av :::row-end::: --- - + ## Project Collection Administrator (PCA) role and managing collections of projects @@ -532,7 +506,6 @@ From the administrative **Organization settings** page, you can configure settin > [!NOTE] > If the **Limit user visibility and collaboration to specific projects** preview feature is enabled for the organization, users added to the **Project-Scoped Users** group won't be able to access **Organization Settings** other than the **Overview** and **Projects** pages. For more information including important security-related call-outs, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). - > [!div class="mx-imgBorder"] > ![Screenshot of Organization settings options, cloud.](media/about/organization-settings-options-cloud.png) @@ -546,7 +519,7 @@ From the administrative page for a collection, you can configure the settings sh ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops-2022" +::: moniker range=" [!NOTE] -> Project collection settings differ depending on your on-premises TFS version. Some settings aren't available for earlier versions of TFS. - -![Screenshot of Collection settings options, TFS.](media/about/collection-settings-tfs-nav.png) - -::: moniker-end - ::: moniker range="azure-devops" For an overview of managing your organization, see [About organization management](../accounts/organization-management.md). @@ -610,7 +571,7 @@ For an overview of managing collections, see [Configure and manage Azure DevOps :::column-end::: :::column span="2"::: - Add and manage organization information: [change organization owner](../accounts/change-organization-ownership.md), [Rename](../accounts/rename-organization.md), [Delete](../accounts/delete-your-organization.md)- [Recover](../accounts/recover-your-organization.md), [Find or change your organization location](../accounts/change-organization-location.md) - - [Set up billing](../billing/set-up-billing-for-your-organization-vs.md) + - [Set up billing](../billing/set-up-billing-for-your-organization-vs.md#set-up-billing) :::column-end::: :::column span="2"::: From the **Overview** page, you can manage the time zone, owner, region, and other settings that apply to all projects. @@ -643,7 +604,7 @@ For an overview of managing collections, see [Configure and manage Azure DevOps - [Remove users](../accounts/delete-organization-users.md) :::column-end::: :::column span="2"::: - For large organizations with a sizable number of users, we recommend that you [manage user access through Azure Active Directory](../accounts/access-with-azure-ad.md). For a small number of users, you can manage user access by adding their Microsoft Service Account (MSA) email. From the account-level Users page, you can also [export the set of users and their access levels](../security/export-users-audit-log.md). + For large organizations with a sizable number of users, we recommend that you [manage user access through Microsoft Entra ID](../accounts/access-with-azure-ad.md). For a few users, you can manage user access by adding their Microsoft Service Account (MSA) email. From the account-level Users page, you can also [export the set of users and their access levels](../security/export-users-audit-log.md). :::column-end::: :::row-end::: --- @@ -654,11 +615,11 @@ For an overview of managing collections, see [Configure and manage Azure DevOps **Billing** :::column-end::: :::column span="2"::: - - [Set up billing](../billing/set-up-billing-for-your-organization-vs.md) + - [Set up billing](../billing/set-up-billing-for-your-organization-vs.md#set-up-billing) - [Try Azure Test Plans for free](../billing/try-additional-features-vs.md) - [Pay for users (Basic)](../billing/buy-basic-access-add-users.md) - [Buy parallel jobs](../../pipelines/licensing/concurrent-jobs.md#how-much-do-parallel-jobs-cost) - - [Add a user to make purchases](../billing/add-backup-billing-managers.md) + - [Add a user to make purchases](../billing/set-up-billing-for-your-organization-vs.md#give-a-user-access-to-manage-billing) :::column-end::: :::column span="2"::: All billing gets managed through Azure. For more information, see [Billing overview](../billing/overview.md). @@ -676,7 +637,7 @@ For an overview of managing collections, see [Configure and manage Azure DevOps - [Create audit streaming](../audit/auditing-streaming.md) :::column-end::: :::column span="2"::: - The auditing page provides a simple view into the audit events recorded for your organization. For more information, see [Review audit log](../audit/azure-devops-auditing.md#review-audit-log), [Export audit events](../audit/azure-devops-auditing.md#export-auditing-events), or learn more about Audit [events](../audit/auditing-events.md). + The auditing page provides a simple view into the audit events recorded for your organization. For more information, see [Review audit log](../audit/azure-devops-auditing.md#review-audit-log), [Export audit events](../audit/azure-devops-auditing.md#export-audit-events), or learn more about Audit [events](../audit/auditing-events.md). :::column-end::: :::row-end::: --- @@ -731,7 +692,7 @@ For an overview of managing collections, see [Configure and manage Azure DevOps - [Manage application access policies](../accounts/change-application-access-policies.md) - [Add external users](../accounts/add-external-user.md) - [Disable Request Access policy](../accounts/disable-request-access-policy.md) - - [Restrict users from creating new organizations with Azure Active Directory policy](../accounts/azure-ad-tenant-policy-restrict-org-creation.md) + - [Restrict users from creating new organizations with Microsoft Entra policy](../accounts/azure-ad-tenant-policy-restrict-org-creation.md) - [Restrict Team and Project Administrators from inviting new users](../security/restrict-invitations.md) - [Enable Conditional Access or Multi-Factor Authentication](/azure/active-directory/authentication/tutorial-enable-azure-mfa) :::column-end::: @@ -750,8 +711,8 @@ For an overview of managing collections, see [Configure and manage Azure DevOps - [Look up the organization owner](../security/look-up-organization-owner.md) - [Look up a project collection administrator ](../security/look-up-project-collection-administrators.md) - [Add administrators, set organization-level permissions](../security/change-organization-collection-level-permissions.md) - - [Add Azure Active Directory groups](../accounts/manage-azure-active-directory-groups.md) - - [Connect to Azure Active Directory](../accounts/connect-organization-to-azure-ad.md) + - [Add Microsoft Entra groups](../accounts/manage-azure-active-directory-groups.md) + - [Connect to Microsoft Entra ID](../accounts/connect-organization-to-azure-ad.md) - [Set permissions to manage extensions](../../marketplace/grant-permissions.md) - [Manage conditional access](../accounts/change-application-access-policies.md) :::column-end::: @@ -770,7 +731,7 @@ For an overview of managing collections, see [Configure and manage Azure DevOps - [Look up the organization owner](../security/look-up-organization-owner.md) - [Look up a project collection administrator ](../security/look-up-project-collection-administrators.md) - [Add administrators, set organization-level permissions](../security/change-organization-collection-level-permissions.md) - - [Grant or restrict access to select features](../security/restrict-access.md) + - [Manage access to specific features](../security/restrict-access.md) :::column-end::: :::column span="2"::: For an overview of security concepts, see [Get started with permissions, access, and security groups](../security/about-permissions.md) and [About access levels](../security/access-levels.md). For a list of collection-level permissions, see [Permissions and groups reference, Collection-level permissions](../security/permissions.md#organization-level-permissions). @@ -778,7 +739,7 @@ For an overview of managing collections, see [Configure and manage Azure DevOps :::row-end::: --- ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: **Boards: Process** @@ -818,7 +779,7 @@ For an overview of managing collections, see [Configure and manage Azure DevOps - [Artifacts storage consumption](../../artifacts/artifact-storage.md) :::column-end::: :::column span="2"::: - Each organization gets Azure Artifacts for free, up until 2 GB of storage is reached. For more information, see [Artifacts free tier and upgrade](../../artifacts/start-using-azure-artifacts.md#artifacts-free-tier-and-upgrade). + Each organization gets Azure Artifacts for free, up until 2 GB of storage is reached. For more information, see [Start using Azure Artifacts](../../artifacts/start-using-azure-artifacts.md#increase-azure-artifacts-storage-limit). :::column-end::: :::row-end::: --- @@ -826,7 +787,7 @@ For an overview of managing collections, see [Configure and manage Azure DevOps ::: moniker range="< azure-devops" - + ## Server Administrator role diff --git a/docs/organizations/settings/about-teams-and-settings.md b/docs/organizations/settings/about-teams-and-settings.md index 527afe5c7f1..8079385006f 100644 --- a/docs/organizations/settings/about-teams-and-settings.md +++ b/docs/organizations/settings/about-teams-and-settings.md @@ -8,61 +8,62 @@ ms.assetid: 24C97BED-88F4-4D91-98D1-4AC0B39AB7D7 ms.author: chcomley author: chcomley ms.topic: conceptual +ai-usage: ai-assisted monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 12/23/2024 --- # About teams and Agile tools [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - - -Learn how you can structure and use your teams and Agile tools to support your growing organization. When your team grows beyond its intended size—typically anywhere from 6 to 9 members—you might consider moving from a one team structure to a two-team structure. You can then set up a hierarchical team structure, which provides several advantages to managers for tracking progress across teams. For the step-by-step procedure to add a team, see [Add another team](add-teams.md). +Learn how you can structure and use your teams and Agile tools to support your growing organization. When your team grows beyond its intended size—typically anywhere from 6 to 9 members—you might consider moving from a one team structure to a two-team structure. You can then set up a hierarchical team structure, which provides several advantages to managers for tracking progress across teams. For more information, see [Add another team](add-teams.md). [!INCLUDE [temp](../../boards/includes/note-configure-customize.md)] -Depending on the size of your organization and your tracking needs, you can set up a team structure similar to the following image shown. Do so by defining teams and their associated area path(s). +Depending on the size of your organization and your tracking needs, you can set up a team structure similar to the following image shown. Do so by defining teams and their associated area paths. ![Each team has its own view of the work](../../boards/plans/media/pm-team-structure.png) The following scenarios apply: -- each feature team can be associated with a single feature area path—such as *Customer Profile*, *Shopping Cart*, *Email*—or several area paths -- each management team, which focuses on a set of features, can choose several area paths to monitor -- each feature team has its distinct backlog to plan, determine priority, and track work -- portfolio or product owners can create their idea, road map, and goals for each release, monitor progress across their portfolio of projects, and manage risks and dependencies. For more information, see [Portfolio management](../../boards/plans/portfolio-management.md) + +- Each feature team can be associated with a single feature area path—such as *Customer Profile*, *Shopping Cart*, *Email*—or several area paths. +- Each management team, which focuses on a set of features, can choose several area paths to monitor. +- Each feature team has its distinct backlog to plan, determine priority, and track work. +- Portfolio or product owners can create their vision, roadmap, and goals for each release, monitor progress across their portfolio of projects, and manage risks and dependencies. For more information, see [Portfolio management](../../boards/plans/portfolio-management.md). ## About area paths, feature teams, and management teams -Area paths serve the following purposes in Azure Boards: -1. Filter the work items that appear on a team backlog or board. -2. Apply additional filtering to the work items that appear on a backlog or board, for details, see [Interactively filter backlogs, boards, queries, and plans](../../boards/backlogs/filter-backlogs-boards-plans.md). -3. Group work that shares some relationship, such as belonging to the same product, feature, or other work-level grouping. -4. Restrict access to work by setting permissions. Permissions can be set for security groups to restrict modification of work items based on area path. +Area paths serve the following purposes in Azure Boards: + +- **Filter work items:** Determine which work items appear on a team backlog or board. +- **Apply additional filtering:** Further refine the work items that appear on a backlog or board. For details, see [Interactively filter backlogs, boards, queries, and plans](../../boards/backlogs/filter-backlogs-boards-plans.md). +- **Group related work:** Organize work that shares a relationship, such as belonging to the same product, feature, or other work-level grouping. +- **Restrict access:** Set permissions to restrict modification of work items based on area path. Permissions can be configured for security groups. + +Teams make their selections as follows: -Teams make their selections as follows: -- Feature teams can choose one or more area paths to specify which work items will appear on their backlogs and boards. -- Management teams typically choose all area paths that their feature teams work on. -- Additionally, management teams may only focus on Features and Epics, while Feature teams may focus only on product backlog items such as User Stories (Agile), Product Backlog Items (Scrum), and Requirements (CMMI). +- **Feature teams:** Choose one or more area paths to specify which work items will appear on their backlogs and boards. +- **Management teams:** Typically select all area paths that their feature teams work on. They might focus on Features and Epics, while feature teams concentrate on product backlog items such as User Stories (Agile), Product Backlog Items (Scrum), and Requirements (CMMI). > [!NOTE] -> Teams can be assigned a maximum of 300 **Area Paths**. To learn more, see [Work tracking, process, and project limits](work/object-limits.md). +> Teams can be assigned a maximum of 300 **Area Paths**. For more information, see [Work tracking, process, and project limits](work/object-limits.md). -For steps to define area paths and assign them to a team, see [Define area paths and assign to a team](set-area-paths.md). +For more information, see [Define area paths and assign to a team](set-area-paths.md). ## The default team -Each new project is configured with a default team with the project name. For example, the *Fabrikam* project is automatically configured with the *Fabrikam* team. +Each new project is configured with a default team named after the project. For example, the *Fabrikam* project is automatically configured with the *Fabrikam* team. -Backlogs, boards, and dashboards are automatically configured for this default team so that you can start defining work items and your backlog. +Backlogs, boards, and dashboards are set up for this default team, allowing you to start defining work items and your backlog immediately. -You can rename the default team and reassign a new team as the default. +You can rename the default team and assign a different team as the default if needed. ## Each team gets their own set of tools -Each team you create gets access to a suite of Agile tools and team assets. These tools let teams work autonomously and collaborate with other teams across the enterprise. Each team can configure and customize each tool to support how they work. +Each team you create gains access to a suite of Agile tools and team assets. These tools enable teams to work autonomously while collaborating with other teams across the enterprise. Each team can configure and customize these tools to support their unique workflows and processes. -![Agile tools, team assets](media/agile-tools/agile-tools-team-assets-post-2018.png) +![Screenshot showing Agile tools, team assets.](media/agile-tools/agile-tools-team-assets-post-2018.png) ::: moniker range=">= azure-devops-2020" @@ -71,37 +72,33 @@ Each team you create gets access to a suite of Agile tools and team assets. Thes ::: moniker-end - These tools automatically filter the set of work items they display by referencing the following items: -- default area path -- iteration path -- selected sprints - -For more information about each tool and the configuration settings for each tool, see the following corresponding articles. -[!INCLUDE [team-configuration](../../boards/includes/team-configuration.md)] +- Default area path +- Iteration path +- Selected sprints +For more information about each tool and its configuration settings, see the following articles. -Many of these tools are built from system queries that reference the team area path. For instance, a team's default area path filters the work items that appear on a team's backlog. Work items created using an Agile tool auto-assign the areas and iterations based on team defaults. +[!INCLUDE [team-configuration](../../boards/includes/team-configuration.md)] - +Many of these tools are built from system queries that reference the team's area path. For example, a team's default area path filters the work items that appear on the team's backlog. Work items created using an Agile tool automatically assign areas and iterations based on team defaults. ## Team defaults referenced by backlogs and boards -What work items appear on team backlogs and boards? When you add work items to a backlog or board, how are team defaults used to assign field values? +Work items that appear on team backlogs and boards are determined by the team's **Area Paths** and **Iteration Paths**. When you add work items to a backlog or board, team defaults are used to assign field values. -Teams are associated with one or more **Area Paths** and **Iteration Paths**. These paths determine what items appear on their backlogs and boards. +When you define a team, you specify the following: -When you define a team, you define the team's: -- Selected Area Path(s) +- Selected Area Path(s) - Default Area Path - Selected Iteration Path(s) - Backlog Iteration Path -- Default Iteration Path +- Default Iteration Path -All Agile tools reference the Area Path(s) defined for a team. The set of work items that appear on a backlog or board depend on the current **State** of a work item or its parent-child status. +All Agile tools reference the Area Path(s) defined for a team. The set of work items that appear on a backlog or board depends on the current **State** of a work item or its parent-child status. -Several tools also reference the team's default and selected Iteration Path or sprints. When you add a new work item from a team's backlog or Kanban board, the system assigns the team's **Default Area Path** and **Default Iteration Path** to it. +Several tools also reference the team's default and selected Iteration Path or sprints. When you add a new work item from a team's backlog or board, the system assigns the team's **Default Area Path** and **Default Iteration Path** to it. > [!NOTE] > New work items added through the **Work Items** page or the **New Work Items** widget on a team dashboard don't reference the **Default Iteration Path** assigned to the team. Instead, new work items are assigned the last **Iteration Path** selected by the user. New work items added through a team's **Sprints** backlog or taskboard are always assigned the **Iteration Path** associated with the selected sprint backlog or taskboard. @@ -139,7 +136,7 @@ Several tools also reference the team's default and selected Iteration Path or s :::row::: :::column span="1"::: - Kanban boards (see note 4) + Boards (see note 4) :::column-end::: :::column span="1"::: Selected area path(s) @@ -199,22 +196,21 @@ Several tools also reference the team's default and selected Iteration Path or s > [!NOTE] -> 1. Agile tools filter items based on the team's selected area path(s). Teams can choose [whether to include or exclude items assigned to subarea paths](../../organizations/settings/set-area-paths.md#team-area-paths). +> 1. Agile tools filter items based on the team's selected area path(s). Teams can choose [whether to include or exclude items assigned to subarea paths](../../organizations/settings/set-area-paths.md#set-team-area-paths). > 2. Work items whose **State** equals *Closed*, *Done*, or *Removed* (corresponding to a *Completed* category state) don't appear on portfolio and product backlogs. > 3. You can add custom workflow states and assign them to one of three state categories. The [state categories](../../boards/work-items/workflow-and-state-categories.md)"> determine which work items appear on backlog and board views. -> 4. Kanban boards, sprint backlogs, and taskboards only show the last node in a hierarchy, called the leaf node. For example, if you link items within a hierarchy that is four levels deep, only the items at the fourth level appear on the Kanban board, sprint backlog, and task board. To learn more, see [parent-child links between items](../../boards/backlogs/resolve-backlog-reorder-issues.md#leaf-nodes). +> 4. Boards, sprint backlogs, and taskboards only show the last node in a hierarchy, called the leaf node. For example, if you link items within a hierarchy that is four levels deep, only the items at the fourth level appear on the board, sprint backlog, and task board. For more information, see [parent-child links between items](../../boards/backlogs/resolve-backlog-reorder-issues.md). > 5. Work items whose **State** equals *Removed* don't appear on boards. ## Structure hierarchical teams or scale agility within an enterprise -Although there's no concept of subteams, you can create teams whose area paths are under another team, which effectively creates a hierarchy of teams. To learn more, see [Add another team](../../organizations/settings/add-teams.md). +Although there's no concept of subteams, you can create teams whose area paths are under another team, which effectively creates a hierarchy of teams. For more information, see [Add another team](../../organizations/settings/add-teams.md). Also, the following articles walk you through the steps for configuring teams, area paths, and iterations to support portfolio management or enterprise organizations: - [Portfolio management](../../boards/plans/portfolio-management.md) - [Implement Scaled Agile Framework to support epics, release trains, and multiple backlogs](../../boards/plans/scaled-agile-framework.md) - ## Team groups @@ -222,7 +218,7 @@ When you add a team, a security group is automatically created with the team nam ![Web portal, Queries page, Query that uses In Group operator and team group name](../../boards/plans/media/query-in-group-email-team-work-in-progress.png) -You can also use the **\@mention** control within discussions and pull requests to notify all members of a team. Start entering the name of a team or a security group, select the search icon, and then select from the options listed. To learn more, see [Use @mentions to further discussion](../../organizations/notifications/at-mentions.md). +You can also use the **\@mention** control within discussions and pull requests to notify all members of a team. Start entering the name of a team or a security group, select the search icon, and then select from the options listed. For more information, see [Use @mentions to further discussion](../../organizations/notifications/at-mentions.md). ## Work on more than one team @@ -236,16 +232,16 @@ By default, team members inherit the permissions afforded to members of the proj ![Default permissions assigned to team contributors](media/add-team/default-permissions-assigned-to-team-contributors.png) -Limit access to select features by making a user a [Stakeholder](../security/get-started-stakeholder.md) or limiting their access to read-only. For more information, see [Permissions and access for work tracking](../security/permissions-access-work-tracking.md). +For more information about limiting access, see [Set permissions and access for work tracking](../security/set-permissions-access-work-tracking.md). ## Summary -- Every team owns their own backlog, to create a new backlog you [create a new team](../../organizations/settings/add-teams.md) -- Every backlog has a corresponding [Kanban board](../../boards/boards/kanban-overview.md) you can use to track progress and update status -- The team's specified area and iteration paths determine which work items appear on the backlog and Kanban board—you can easily decide to include or exclude work items under a specific area path -- Each team can control how [bugs show up on their backlogs and boards](show-bugs-on-backlog.md) -- For an overview of all team assets and how to configure them, see [Manage teams and configure team tools](manage-teams.md) -- To have work done by several teams roll up in to a portfolio backlog, you'll want to [setup the team hierarchy](../../boards/plans/portfolio-management.md) +- Each team owns its own backlog. To create a new backlog, [create a new team](../../organizations/settings/add-teams.md). +- Each backlog has a corresponding [board](../../boards/boards/kanban-overview.md) to track progress and update status. +- The team's specified area and iteration paths determine which work items appear on the backlog and board. You can easily decide to include or exclude work items under a specific area path. +- Each team can control how [bugs show up on their backlogs and boards](show-bugs-on-backlog.md). +- For an overview of all team assets and how to configure them, see [Manage teams and configure team tools](manage-teams.md). +- To have work done by several teams roll up into a portfolio backlog, [set up the team hierarchy](../../boards/plans/portfolio-management.md). - To add fields or work item types, see [Customize your work tracking experience](../../reference/customize-work.md). ## Related articles diff --git a/docs/organizations/settings/add-team-administrator.md b/docs/organizations/settings/add-team-administrator.md index 9e2d3e871a5..4567052341b 100644 --- a/docs/organizations/settings/add-team-administrator.md +++ b/docs/organizations/settings/add-team-administrator.md @@ -9,17 +9,16 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 11/12/2024 --- # Add or remove a team administrator [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Learn how to add or remove an administrator for your team. It's always a good idea to have more than one user with administration permissions for a team. Team administrators can [manage teams and configure team tools](manage-teams.md) and manage projects. You may want to remove a user's administration permissions, for instance if the user is no longer active. +Learn how to add or remove team administrators. We recommend having multiple users with administration permissions for redundancy. Team administrators can [manage teams and configure team tools](manage-teams.md) and oversee projects. Remove a user's administration permissions if the user is no longer active. To add a team, see [Add teams](add-teams.md). To add or remove a project administrator, see [Change project-level permissions](../security/change-project-level-permissions.md). @@ -27,15 +26,12 @@ To add a team, see [Add teams](add-teams.md). To add or remove a project adminis ## Prerequisites -- To add or remove a user as a team administrator, you must be a member of the [**Project Administrators** group](../security/change-project-level-permissions.md), or a team administrator for the team you want to update. -- To be added as a team administrator, you must be granted **Basic** or higher access-level. Users granted **Stakeholder** access can't be added as a team administrator. +[!INCLUDE [prerequisites-project-administrator-and-basic](../../includes/prerequisites-project-administrator-and-basic.md)] ## Add an administrator -To get added as a team administrator, ask another team administrator or a member of the **Project Administrators** group. See [Look up a project administrator](../security/look-up-project-administrators.md). - ::: moniker range="azure-devops" > [!NOTE] @@ -43,8 +39,8 @@ To get added as a team administrator, ask another team administrator or a member #### [New Teams Page](#tab/preview-page) -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and select a project. -2. Choose **Project settings**, and then choose **Teams**. +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```) and select a project. +2. Select **Project settings** > **Teams**. > [!div class="mx-imgBorder"] > ![Screenshot of Project settings and Teams buttons for selection.](media/shared/open-project-settings-teams-preview.png) @@ -54,24 +50,26 @@ To get added as a team administrator, ask another team administrator or a member > [!div class="mx-imgBorder"] > ![Screenshot of dialog for adding user identity, new teams page view for Azure DevOps Services.](media/add-team-admin/settings-add-team-administrator-preview.png) -3. Enter the user's identity you want to add to the administrator role, and then select **Save**. +4. Enter the user's identity you want to add to the administrator role, and then select **Save**. > [!div class="mx-imgBorder"] > ![Screenshot of Add team administrator dialog on the New Teams page.](media/add-team-admin/add-team-administrator-dialog-preview.png) #### [Current page](#tab/current-page) -1. Choose **Project settings**, and then choose **Teams**. +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```) and select a project. + +2. Choose **Project settings** > **Teams**. > [!div class="mx-imgBorder"] > ![Screenshot of selected Project settings and Teams buttons.](media/shared/open-project-settings-team-new-nav.png) -2. Select the team to configure, and then select **Settings** > **Add**. +3. Select the team to configure, and then select **Settings** > **Add**. > [!div class="mx-imgBorder"] > ![Screenshot of the Add button for selection.](media/add-team-admin/settings-add-team-administrator.png) -3. Enter the user identity that you want to add to the administrator role, and then select **Save**. +4. Enter the user identity that you want to add to the administrator role, and then select **Save**. > [!div class="mx-imgBorder"] > ![Screenshot of Add team administrator dialog on current page for Azure DevOps Server 2019 and up.](media/add-team-admin/add-administrators-dialog.png) @@ -80,10 +78,9 @@ To get added as a team administrator, ask another team administrator or a member ::: moniker-end +::: moniker range=" < azure-devops" -::: moniker range=">= azure-devops-2019 < azure-devops" - -1. Choose **Project settings**, and then choose **Teams**. +1. Select **Project settings** > **Teams**. > [!div class="mx-imgBorder"] > ![Screenshot of selected Project settings and Teams buttons.](media/shared/open-project-settings-team-new-nav.png) @@ -100,42 +97,21 @@ To get added as a team administrator, ask another team administrator or a member ::: moniker-end -::: moniker range="tfs-2018" - -1. From the web portal and team context, choose **Team Settings** :::image type="icon" source="../../media/icons/gear_icon.png" border="false":::. - - > [!div class="mx-imgBorder"] - > ![Screenshot of open Team Settings.](media/add-team-admin/open-team-settings-horz.png) - - If you choose **Project settings** :::image type="icon" source="../../media/icons/gear_icon.png" border="false":::, then choose **Overview**, and select the team you want to configure. - -2. Choose the **Add** link to open the dialog for adding user identities. - - ![Screenshot of Open team administrator context.](media/add-team/admin-link.png) - -3. Enter the identities you want to add to the team administrator role. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Add team administrator dialog for TFS 2017 through 2018.](media/add-team-admin/add-team-admin-dialog.png) - -::: moniker-end - - -* * * +*** ## Remove an administrator -Each team must have at least one administrator. To remove an administrator, you must first add at least a second administrator. +Each team has at least one administrator. To remove an administrator, first add at least a second administrator. Open the **Teams** page as described in the previous section. -::: moniker range="azure-devops" +::: moniker range="azure-devops" #### [New Teams Page](#tab/preview-page) -Choose **Settings** and scroll down to the Administrators section. Choose ![remove icon](../../media/icons/remove-icon.png) for the user that you want to remove as a team administrator. +Select **Settings** and scroll down to the Administrators section. Select ![remove icon](../../media/icons/remove-icon.png) for the user that you want to remove as a team administrator. ![Screenshot of X selected to remove team administrator.](media/add-team-admin/remove-admin-new-ui-page.png) @@ -145,27 +121,18 @@ Choose **Settings** and scroll down to the Administrators section. Choose ![remo From the Administrators section, choose ![delete icon](../../media/icons/delete-icon.png) for the user that you want to remove as a team administrator. > [!div class="mx-imgBorder"] -> ![Remove a team admin](media/add-team-admin/remove-admin-prev-ui.png) +> ![Screenshot shows removing a team administrator.](media/add-team-admin/remove-admin-prev-ui.png) * * * ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - -From the Administrators section, choose ![delete icon](../../media/icons/delete-icon.png) for the user that you want to remove as a team administrator. - -> [!div class="mx-imgBorder"] -> ![Remove a team admin](media/add-team-admin/remove-admin-prev-ui.png) - -::: moniker-end - -::: moniker range="< azure-devops-2019" +::: moniker range=" < azure-devops" From the Administrators section, choose ![delete icon](../../media/icons/delete-icon.png) for the user that you want to remove as a team administrator. > [!div class="mx-imgBorder"] -> ![Screenshot of current UI for Remove a team administrator.](media/add-team-admin/remove-admin-prev-ui.png) +> ![Screenshot shows removing a team administrator.](media/add-team-admin/remove-admin-prev-ui.png) ::: moniker-end @@ -176,8 +143,8 @@ From the Administrators section, choose ![delete icon](../../media/icons/delete- ## Related articles -- [Add teams](add-teams.md) -- [About teams & Agile tools](../../organizations/settings/about-teams-and-settings.md) +- [Add teams](add-teams.md) +- [Learn about teams & Agile tools](../../organizations/settings/about-teams-and-settings.md) - [Configure and customize Azure Boards](../../boards/configure-customize.md) - [Set team favorites](../../project/navigation/set-favorites.md) diff --git a/docs/organizations/settings/add-teams.md b/docs/organizations/settings/add-teams.md index fecc71161f0..261d8da0bdc 100644 --- a/docs/organizations/settings/add-teams.md +++ b/docs/organizations/settings/add-teams.md @@ -1,7 +1,7 @@ --- title: Create or add a team titleSuffix: Azure DevOps -description: Learn how to create or add a team to a project to scale Azure DevOps. +description: Learn how to create or add a team to a project in Azure DevOps to scale your development processes, collaborate effectively, and manage project resources. ms.subservice: azure-devops-settings ms.custom: teams, devx-track-azurecli ms.assetid: 9F1D0A0F-02D5-4E06-A5EC-C220472A0F66 @@ -9,61 +9,53 @@ ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 05/19/2022 +ms.date: 11/12/2024 --- # Create or add a team [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +This article explains how to create new teams, add members, configure team settings, and follow best practices for team management in Azure DevOps. - As your organization grows, you add teams to support that growth. You create a team in Azure DevOps that corresponds to a group of project members focused on specific products, services, or feature areas. You add teams to provide them the tools they need to manage their backlog, plan sprints, configure dashboards, define alerts, and set team favorites. +As your organization grows, add teams to manage specific products, services, or feature areas. Equip teams with tools to manage backlogs, plan sprints, configure dashboards, define alerts, and set team favorites. -Each new project is configured with a default team with the project name. For example, the project named Fabrikam Fiber is configured with the default team Fabrikam Fiber Team. You can rename the default team and you can reassign a new team as the default. +Each new project includes a default team named after the project that you can rename or reassign as needed. -For a good understanding on how to remain Agile as you add teams, review [Scale Agile to Large Teams](/devops/plan/scaling-agile). For more information about team-configurable tools, see [About teams and Agile tools](about-teams-and-settings.md). +To maintain Agile practices while scaling teams, review [Scale Agile to Large Teams](/devops/plan/scaling-agile). For more information on team-configurable tools, see [About teams and Agile tools](about-teams-and-settings.md). +> [!NOTE] +> This article explains how to add teams or team members to an Azure DevOps project. For information on Microsoft Teams or integrating it with Azure Boards, see [Welcome to Microsoft Teams](/microsoftteams/teams-overview) or [Use the Azure Boards app in Microsoft Teams](../../boards/integrations/boards-teams.md). +> +> To move work items between teams, see [Move work items from one team to another](../../boards/work-items/move-work-items.md). -> [!NOTE] -> This article describes how to add a team or team members to a project defined in Azure DevOps. To learn about Microsoft Teams or the integration of Microsoft Teams with Azure Boards, see [Welcome to Microsoft Teams](/microsoftteams/teams-overview) or [Use the Azure Boards app in Microsoft Teams](../../boards/integrations/boards-teams.md). +## Prerequisites -Use this article to learn how to perform the following tasks: ::: moniker range="azure-devops" -> [!div class="checklist"] -> * Create a team and add team administrators and team members -> * Set the default team for a project -> * List teams using Azure CLI -> * Grant additional permissions to teams -::: moniker-end -::: moniker range="< azure-devops" -> [!div class="checklist"] -> * Create a team and add team administrators and team members -> * Set the default team for a project -> * Grant additional permissions to teams -::: moniker-end -To move work items assigned to one team to another team, see [Move work items from one team to another](../../boards/work-items/move-work-items.md). +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - Member of the **Project Administrators** security group.
      - To add members to a team or change its configuration, be a [team administrator](add-team-administrator.md) or member of the [Project Administrators](../security/change-project-level-permissions.md) group. | +|**Tools**| To use Azure CLI commands: [Azure DevOps CLI](../../cli/index.md).| -## Prerequisites - -::: moniker range="azure-devops" -- To create a team or set the default team, you must be a member of the **Project Administrators** group. See [Change project-level permissions](../security/change-project-level-permissions.md). Only members of the Project Administrators group can add and delete teams. -- To add members to a team or change its configuration, you must be a team administrator or member of the Project Administrators group. To get added as a team administrator, see [Add or remove a team administrator](add-team-administrator.md). -- To use Azure CLI commands, you must first install Azure CLI as described in [Get started with Azure DevOps CLI](../../cli/index.md). ::: moniker-end + ::: moniker range="< azure-devops" -- To create a team or set the default team, you must be a member of the **Project Administrators** group. See [Change project-level permissions](../security/change-project-level-permissions.md). Only members of the Project Administrators group can add and delete teams. -- To add members to a team or change its configuration, you must be a team administrator or member of the Project Administrators group. To get added as a team administrator, see [Add or remove a team administrator](add-team-administrator.md). + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - Member of the **Project Administrators** security group.
      - To add members to a team or change its configuration, be a [team administrator](add-team-administrator.md) or member of the [Project Administrators](../security/change-project-level-permissions.md) group. | + ::: moniker-end ## Create a team and add team members -From your web browser, you can view, create, and configure teams. Only members of the Project Administrators group can create teams. +To create a team, do the following steps. -> [!NOTE] -> When you create a team, you can automatically create the **Area Path** the team will use as a child node of the main project node. If you plan on creating a hierarchical team structure, you may want to first define the **Area Paths** at the project level, then create your teams, and then assign the **Area Path(s)** to be used by each team. To learn more about this team structure, see [Configure a hierarchy of teams](../../boards/plans/configure-hierarchical-teams.md). +> [!NOTE] +> When you create a team, you can automatically generate the **Area Path** as a child node of the main project. To establish a hierarchical team structure, first define the **Area Paths** at the project level, then create your teams, and assign the appropriate **Area Paths** to each team. For more information, see [Configure a hierarchy of teams](../../boards/plans/configure-hierarchical-teams.md). ::: moniker range="azure-devops" @@ -76,102 +68,71 @@ From the Azure CLI tool, you can [list teams](#list-teams), [create a team](#add #### [New Teams UI](#tab/preview-page) ::: moniker range="azure-devops" -1. From the web portal, choose **Project settings** and open **Teams**. +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). +2. Select **Project settings** > **Teams**. - ![Screenshot of Open Project settings, and then Teams buttons on New Teams page.](media/shared/open-project-settings-teams-preview.png) + ![Screenshot of Open Project settings, and then Teams buttons on New Teams page.](media/shared/open-project-settings-teams-preview.png) -1. Choose **New team**. +3. Select **New team**. :::image type="content" source="media/add-team/new-team-button-new-teams-preview.png" alt-text="Screenshot of choose New Team button, New Teams preview feature enabled."::: -1. Enter a team name and the names of project members who you want to assign to the team. Optionally, enter a description. You must add at least one name as a team **Administrator**. Select **Create an area path with the name of the team**, or leave it unchecked and assign the **Area Path** for the team after it's created. You can choose an existing area path or add a new one at that time. +4. Enter a team name and the names of project members who you want to assign to the team. Optionally, enter a description. Add at least one name as a team **Administrator**. Select **Create an area path with the name of the team**, or leave it unchecked and assign the **Area Path** for the team after it gets created. You can choose an existing area path or add a new one at that time. :::image type="content" source="media/add-team/create-new-team-dialog-new-teams-preview.png" alt-text="Screenshot of Create a new team dialog, New Teams preview feature enabled."::: > [!NOTE] - > Consider adding one or more users as team administrators. Team administrators have the necessary permissions to add team members and configure all team settings—including backlogs, Kanban boards, and Taskboards. To learn more, see [Manage and configure team tools](manage-teams.md). + > Consider adding one or more users as team administrators. Team administrators have the necessary permissions to add team members and configure all team settings—including backlogs, boards, and Taskboards. For more information, see [Manage and configure team tools](manage-teams.md). -1. When finished, select **Create**. +5. When you're ready, select **Create**. -1. Select the team to add a team image, or configure other team elements. +6. Select the team to add a team image, or configure other team elements. -1. Choose **Settings** to upload an image, change the team name, add a team administrator, or delete the team. +7. Select **Settings** to upload an image, change the team name, add a team administrator, or delete the team. :::image type="content" source="media/add-team/team-settings-dialog-new-teams-preview.png" alt-text="Screenshot of Team Settings dialog, New Teams preview feature enabled."::: -1. Choose **Save** to save any changes you made. +8. Choose **Save**. -1. Choose **Iterations and areas** to set the **Area Paths** and **Iteration Paths** for the team to use. +9. Select **Iterations and areas** to set the **Area Paths** and **Iteration Paths** for the team to use. :::image type="content" source="media/add-team/team-settings-select-iterations-areas-new-teams-preview.png" alt-text="Screenshot of team settings, Iterations and areas highlighted, New Teams preview feature enabled."::: - To learn how, see the following articles: - - [Define area paths and assign to a team](set-area-paths.md) - - [Define iteration paths, also known as sprints, and configure team iterations](set-iteration-paths-sprints.md). + For more information, see the following articles: + - [Define area paths and assign to a team](set-area-paths.md) + - [Define iteration paths, also known as sprints, and configure team iterations](set-iteration-paths-sprints.md). ::: moniker-end ::: moniker range="< azure-devops" -Choose the **Current UI** tab. The New Teams Page UI is only available for Azure DevOps Services. +Select the **Current UI** tab. The New Teams Page UI is only available for Azure DevOps Services. ::: moniker-end #### [Current UI](#tab/current-page) -::: moniker range=">= azure-devops-2019" - -1. From the web portal, choose **Project settings** and open **Teams**. +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). +2. Select **Project settings** > **Teams**. ![Screenshot of Open Project settings button, and then Teams button selection on Current page](media/shared/open-project-settings-team-new-nav.png) -::: moniker-end -::: moniker range="tfs-2018" -1. From the web portal, choose **Project settings > Overview** :::image type="icon" source="../../media/icons/gear_icon.png" border="false":::. +3. Select **New team**. Give the team a name, and optionally a description. Choose a security group to add team members to. - ![Open project admin page](media/add-team/open-team-settings-tfs-2018.png) + ![Screenshot of New team subteam with its own area path on Current page](media/add-team/create-new-team-new-nav.png) -::: moniker-end -2. Choose **New team**. Give the team a name, and optionally a description. Choose a security group to add team members to. - - ![Screenshot of New team subteam with its own area path on Current page](media/add-team/create-new-team-new-nav.png) +4. When you're ready, select **Create team**. As the creator of the team, you automatically get added as the team administrator. You can remove yourself as an administrator and assign others to that role in the following steps. -1. When finished, select **Create team**. As the creator of the team, you are automatically added as the team administrator. You can remove yourself as an administrator and assign others to that role in the following steps. - -1. Select the team to add team administrators, team members, configure iterations and areas. The Team Profile opens. - From the team profile, you can perform these additional tasks: - - [Add team members](#add-team-members) +5. Select the team to add team administrators, team members, configure iterations and areas. The Team Profile opens. + + From the team profile, you can do the following tasks: - [Add and remove team administrators](add-team-administrator.md) - - [Navigate to team notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) - - [Navigate to and set default team dashboard permissions](../../report/dashboards/dashboard-permissions.md) - - + - [Manage team notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) + - [Set default team dashboard permissions](../../report/dashboards/dashboard-permissions.md) + - [Define area paths and assign to a team](set-area-paths.md) + - [Define iteration paths, also known as sprints, and configure team iterations](set-iteration-paths-sprints.md) -1. To add team members, choose **Add**. - - > [!div class="mx-imgBorder"] - > ![Team Profile, choose Add, currect page](../security/media/add-users/team-profile-choose-add.png) - -4. Enter the sign-in addresses or display name for each account you want to add. Add them one at a time or all at the same time. You can enter several identities into the text box, separated by commas. - - ![Add users and group dialog, current page](../security/media/project-level-permissions-add-a-user.png) - - > [!TIP] - > You must enter user and group names one at a time. However, after entering a name, the account is added to the list, and you can enter another name in the Identities text box before choosing to save your changes. - - You may need to choose the :::image type="icon" source="../../media/icons/refresh.png" border="false"::: refresh icon to see your updates. - -6. To add an account as a team administrator, choose **Add** under the **Team Profile, Administrators** section. For details, see [Add a team administrator](add-team-administrator.md). To remove yourself as an administrator, choose the :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: **Delete** next to your name. - -1. To configure the **Area Paths** and **Iteration Paths** for the team to use, choose **Iterations and areas**. - - ![Screenshot of team profile, choose Iterations and areas link on Current page](media/add-team/team-profile-choose-iterations-and-areas.png) - - To learn how, see these articles: - - [Define area paths and assign to a team](set-area-paths.md) - - [Define iteration paths, also known as sprints, and configure team iterations](set-iteration-paths-sprints.md). - #### [Azure DevOps CLI](#tab/azure-devops-cli) - + ::: moniker range="azure-devops" @@ -185,12 +146,12 @@ az devops team create --name [--description] [--project] #### Parameters - **name**: Required. Name of the new team. -- **description**: Optional. Description of the new team, enclose within parenthesis. +- **description**: Optional. Description of the new team enclosed within parenthesis. - **project**: Optional. Name or ID of the project. Example: `--project "Fabrikam Fiber"`. #### Example -The following command adds a team named **Production Planning** to the *fabrikamprime* organization, *Fabrikam Fiber* project, and returns a number of properties assigned to the team in YAML output format. +The following command adds a team named **Production Planning** to the *fabrikamprime* organization, *Fabrikam Fiber* project, and returns many properties assigned to the team in YAML output format. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -198,7 +159,7 @@ az devops team create --name "Production Planning" --description "Team tasked wi description: Team tasked with planning operations and new processes. ``` -The YAML output listed below provides information on each of the attributes defined for the team. +The YAML output listed as follows provides information on each of the attributes defined for the team. > [!div class="tabbedCodeSnippets"] ```YAML @@ -264,13 +225,13 @@ url: https://fabrikamprime.visualstudio.com/_apis/projects/854a3f67-9962-43d1-a9 ::: moniker-end -[!INCLUDE [note-cli-not-supported-on-premises](../../includes/note-cli-not-supported-on-premises.md)] +[!INCLUDE [note-cli-not-supported](../../includes/note-cli-not-supported.md)] * * * Upon creation of a team, the following items are automatically configured: - Security group with the team name containing the members assigned to the team, for example, **[Fabrikam Fiber]\Production Planning**. You can use this name to filter queries or to **@mention** all members of the team. -- Default notifications assigned to the team. To learn more, see [Manage notifications for a team, project, or organization](../../organizations/notifications/manage-team-group-global-organization-notifications.md). +- Default notifications assigned to the team. For more information, see [Manage notifications for a team, project, or organization](../../organizations/notifications/manage-team-group-global-organization-notifications.md). - Default dashboard named **Overview** assigned to the team. To configure the dashboard, see [Add widgets to a dashboard](../../report/dashboards/add-widget-to-dashboard.md). > [!IMPORTANT] @@ -278,7 +239,6 @@ Upon creation of a team, the following items are automatically configured: > > If you are moving from one team to two or more teams, you may want to review and revise the **Area Paths** assigned to the default project team. - To configure other team features, see [Manage teams and configure team tools](manage-teams.md). @@ -291,7 +251,7 @@ Each project has a default team assigned. You can change which project is assign ::: moniker range="azure-devops" 1. Open **Project settings > Teams** as indicated in the previous section. -1. Choose :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More options** for the team you want to designate as the default, and choose **Set team as project default**. +2. Choose :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More options** for the team you want to designate as the default, and choose **Set team as project default**. ![Screenshot of Teams page, More options menu selection, New Teams Page enabled.](media/add-team/set-team-project-default-new-ui.png) ::: moniker-end @@ -302,13 +262,11 @@ Choose the **Current UI** tab. The New Teams Page UI is only available for Azure #### [Current UI](#tab/current-page) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Open **Project settings > Teams** as indicated in the previous section. ::: moniker-end -::: moniker range="tfs-2018" -1. Open **Project Settings > Overview** as indicated in the previous section. -::: moniker-end -1. Choose :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: to open the context menu for the team you want to designate as the default, and choose **Set team as project default**. + +2. Choose :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: to open the context menu for the team you want to designate as the default, and choose **Set team as project default**. ![Screenshot of Teams page, More options menu selection, New Teams Page enabled.](media/add-team/set-team-project-default-current.png) @@ -318,19 +276,17 @@ Choose the **Current UI** tab. The New Teams Page UI is only available for Azure There isn't an Azure CLI command to set the default team project. ::: moniker-end - -[!INCLUDE [note-cli-not-supported-on-premises](../../includes/note-cli-not-supported-on-premises.md)] +[!INCLUDE [note-cli-not-supported](../../includes/note-cli-not-supported.md)] * * * - - + ::: moniker range="azure-devops" ## List teams with Azure CLI -You can list teams using [Azure DevOps team list](/cli/azure/devops/team#az-devops-team-list). To learn how to list team members, see [Add users to a team or project, List team members](../security/add-users-team-project.md#list-members). +You can list teams using [Azure DevOps team list](/cli/azure/devops/team#az-devops-team-list). To learn how to list team members, see [Add users to a team or project, List team members](../security/add-users-team-project.md#list-team-members). > [!div class="tabbedCodeSnippets"] ```azurecli @@ -344,7 +300,7 @@ az devops team list [--project] #### Parameters -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up via git config. +- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber." You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up via git config. - **skip**: Optional. Number of teams to skip. - **top**: Optional. Maximum number of teams to return. @@ -359,7 +315,7 @@ Each team is assigned a unique ID. az devops team list --project "Fabrikam Fiber" --output table ``` -The table output listed below provides information on each of the attributes defined for the team. +The following table output provides information on each of the attributes defined for the team. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -382,9 +338,9 @@ cda2b9b0-0335-4a0d-8bd0-67611d64ce9d Voice Feature team focused o -## Grant team members additional permissions +## Grant team members permissions -For teams to work autonomously, you may want to provide them with permissions that they don't have by default. Suggested tasks include providing team administrators or team leads permissions to: +For teams to work autonomously, give them permissions that they don't have by default. Suggested tasks include providing team administrators or team leads permissions to: - [Create and edit child nodes under their default area path](../security/set-permissions-access-work-tracking.md#create-child-nodes-modify-work-items-under-an-area-or-iteration-path) - [Create shared queries and folders under the **Shared Queries** folder](../../boards/queries/set-query-permissions.md) @@ -397,7 +353,6 @@ If your deployment is integrated with SQL Server Reports, you need to [Grant per ::: moniker-end - ## Next steps > [!div class="nextstepaction"] @@ -407,10 +362,10 @@ If your deployment is integrated with SQL Server Reports, you need to [Grant per ## Related articles - [Rename or remove a team](rename-remove-team.md) -- [About teams and Agile tools](about-teams-and-settings.md) +- [Learn about teams and Agile tools](about-teams-and-settings.md) - [Add users to a team or project](../security/add-users-team-project.md) -**Rest API resources** -- [Azure DevOps Teams CLI](/cli/azure/devops/team) -- [Teams (REST API)](/rest/api/azure/devops/core/teams) -- [Work Items (REST API)](/rest/api/azure/devops/wit) +**REST API Resources** +- [Use the Azure DevOps Teams CLI](/cli/azure/devops/team) +- [Use the Teams REST API](/rest/api/azure/devops/core/teams) +- [Use the Work Items REST API](/rest/api/azure/devops/wit) diff --git a/docs/organizations/settings/includes/automatic-update-project.md b/docs/organizations/settings/includes/automatic-update-project.md index 1aeacc099e1..f334c2afb06 100644 --- a/docs/organizations/settings/includes/automatic-update-project.md +++ b/docs/organizations/settings/includes/automatic-update-project.md @@ -4,9 +4,9 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include -ms.date: 04/07/2021 +ms.date: 05/31/2024 --- > [!NOTE] -> As you customize an inherited process, all projects that use that process are updated automatically to reflect the customizations. For this reason, we recommend that you create a test process and test project when you have a number of customizations to make in order to test the customizations prior to rolling them out to your organization. To learn more, see [Create and manage inherited processes](../work/manage-process.md). \ No newline at end of file +> When you customize an inherited process, any projects using that process automatically reflect the customizations. To ensure a smooth transition, we recommend creating a test process and project, which allows you to test your customizations before you implement them organization-wide. For more information, see [Create and manage inherited processes](../work/manage-process.md). diff --git a/docs/organizations/settings/includes/change-process-manual-steps.md b/docs/organizations/settings/includes/change-process-manual-steps.md index e0084db8c7e..a2a7bf451bb 100644 --- a/docs/organizations/settings/includes/change-process-manual-steps.md +++ b/docs/organizations/settings/includes/change-process-manual-steps.md @@ -2,5 +2,5 @@ ms.topic: include --- -> [!IMPORTANT] -> If you have existing work items, this process requires manual updates to work items and board configuration. Make sure you follow the steps provided in this article to ensure you address the manual steps required after you change the process used by a project. \ No newline at end of file +> [!WARNING] +> If you have existing work items, this process requires manual updates to work items and board configuration. Make sure you follow the steps provided in this article to ensure you address the manual steps required after you change the process used by a project. diff --git a/docs/organizations/settings/includes/change-project-to-inherited-process.md b/docs/organizations/settings/includes/change-project-to-inherited-process.md index 6a8bc441ddc..a51593398a3 100644 --- a/docs/organizations/settings/includes/change-project-to-inherited-process.md +++ b/docs/organizations/settings/includes/change-project-to-inherited-process.md @@ -38,23 +38,3 @@ After you've verified your customizations, you can now apply the process to your ::: moniker-end -::: moniker range="azure-devops-2019" - -1. Open the … context menu for the process and choose the **Change team projects**… option. - - Here we open the menu for the MyAgile inherited process. - - > [!div class="mx-imgBorder"] - > ![Agile process context menu, Choose Change team projects to use MyAgile](/azure/devops/organizations/settings/work/media/process/add-custom-change-process.png) - -1. Check the check box of those projects you want to change to use the Agile process. The system lists only those projects that are valid for the current process. - - Here we choose to use the Agile process for the Fabrikam Fiber A and Fabrikam Fiber projects. Only those projects created from the Agile process or one that inherits from Agile appears under the Available projects column. - - > [!div class="mx-imgBorder"] - > ![Change process to an inherited process dialog](/azure/devops/organizations/settings/work/media/process/customize-change-process-dialog.png) - -1. After you've confirmed that the projects you want to change are correct, choose **Ok**. - -::: moniker-end - diff --git a/docs/organizations/settings/includes/create-inherited-process.md b/docs/organizations/settings/includes/create-inherited-process.md deleted file mode 100644 index 9d8078054f3..00000000000 --- a/docs/organizations/settings/includes/create-inherited-process.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -ms.topic: include -ms.author: chcomley -author: chcomley -ms.date: 08/03/2022 ---- - - - -## Create an inherited process - -The first step is to create an inherited process that you can customize. The default, system processes are locked from being customized. - -1. From the **Process** page, open the **…** context menu of the process you'll use to create an inherited process, and then choose **Create inherited process**. Choose the same system process—[Agile](../../../boards/work-items/guidance/agile-process.md), [Basic](../../../boards/get-started/plan-track-work.md), [Scrum](../../../boards/work-items/guidance/scrum-process.md), or [CMMI](../../../boards/work-items/guidance/cmmi-process.md)—that was used to create the project that you want to customize. - - Here, we create an inherited process from the Agile system process. - ::: moniker range="azure-devops" - > [!div class="mx-imgBorder"] - > ![Context menu, Choose Create inherited process, Azure DevOps.](/azure/devops/organizations/settings/work/media/process/create-inherited-process-menu-agile.png) - ::: moniker-end - ::: moniker range=">= azure-devops-2020 < azure-devops" - > [!div class="mx-imgBorder"] - > ![Context menu, Choose Create inherited process, Azure DevOps Server 2020.](/azure/devops/organizations/settings/work/media/process/create-inherited-process-2020.png) - ::: moniker-end - ::: moniker range="azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Context menu, Choose Create inherited process, Azure DevOps Server 2019.](/azure/devops/organizations/settings/work/media/process/create-inherited-process-menu-agile.png) - ::: moniker-end - ::: moniker range=">= azure-devops-2019 < azure-devops" - > [!IMPORTANT] - > If you don't see the **Create inherited process** menu option, then the collection you've selected is set to work with the On-premises XML process model. You can import and export process templates and use the features supported for the [On-premises XML process model](../../../reference/customize-work.md). - ::: moniker-end - -2. Enter a name for your process and optionally a description. Process names must be unique and no more than 128 characters. For additional restrictions, see [Create and manage inheritance processes, Process name restrictions](../work/inheritance-process-model.md#process-naming). Optionally, add a description. - - ![Create inherited process dialog](/azure/devops/organizations/settings/work/media/process/create-inherited-process-dialog.png) \ No newline at end of file diff --git a/docs/organizations/settings/includes/fields-become-invalid-after-customization.md b/docs/organizations/settings/includes/fields-become-invalid-after-customization.md index ec64564e879..9e7e70b292b 100644 --- a/docs/organizations/settings/includes/fields-become-invalid-after-customization.md +++ b/docs/organizations/settings/includes/fields-become-invalid-after-customization.md @@ -4,7 +4,8 @@ ms.topic: include > [!NOTE] -> When you change a project to use an inherited process, you may find one or more Agile tools or work items appear in an invalid state. For example: +> When you transition a project to an inherited process, you might encounter Agile tools or work items in an invalid state per the following examples: > -> - If you make a field required, work items with that field undefined show an error message. You'll need to resolve the errors to make additional changes and save the work item. -> - If you add or remove/hide workflow states of a WIT that appears on the Kanban board, you'll need to update the Kanban board column configurations for all teams defined in the project. \ No newline at end of file +> - If you designate a field as required, work items lacking that field display an error message. To proceed with further changes and save the work item, resolve these errors. +> - If you add, remove, or hide workflow states for a WIT that appears on the board, ensure you update the board column configurations for all teams defined in the project. Also, consider maintaining single ownership of work items by team area path or formalizing columns with custom states share across teams. +> \ No newline at end of file diff --git a/docs/organizations/settings/includes/name-restrictions/area-iteration-paths.md b/docs/organizations/settings/includes/name-restrictions/area-iteration-paths.md index d1292ce41d4..dcc982f8db6 100644 --- a/docs/organizations/settings/includes/name-restrictions/area-iteration-paths.md +++ b/docs/organizations/settings/includes/name-restrictions/area-iteration-paths.md @@ -4,7 +4,7 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include -ms.date: 03/28/2023 +ms.date: 10/17/2024 --- @@ -12,7 +12,7 @@ ms.date: 03/28/2023 |---------|---------| |Node length | Must not contain more than 255 characters. | |Reserved names | - Must not consist only of a period `.` or two periods `..`.
      - Must not be a system-reserved name, such as PRN, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM10, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, NUL, CON, or AUX. For more information about reserved names, see [File Names, Paths, and Namespaces](/windows/win32/fileio/naming-a-file). | -|Special characters for nodes | - Must not contain Unicode control characters.
      - Must not contain any one of the following characters: `\ / : * ? " < > | ; # $ * { } , + = [ ]`.
      - Must not contain characters prohibited by the local file system. For more information about Windows character restrictions, see [Naming Files, Paths, and Namespaces](/windows/win32/fileio/naming-a-file). | +|Special characters for nodes | - Must not contain Unicode control characters.
      - Must not contain any one of the following characters: `\ / : * ? " < > | # $ & * +`.
      - Must not contain characters prohibited by the local file system. For more information about Windows character restrictions, see [Naming Files, Paths, and Namespaces](/windows/win32/fileio/naming-a-file). | |Path length | Must not contain more than 4,000 Unicode characters. | |Path hierarchy depth | Must be fewer than 14 levels deep. | diff --git a/docs/organizations/settings/includes/note-audit-log-support-process.md b/docs/organizations/settings/includes/note-audit-log-support-process.md index eeab284f1da..5836e8cc62f 100644 --- a/docs/organizations/settings/includes/note-audit-log-support-process.md +++ b/docs/organizations/settings/includes/note-audit-log-support-process.md @@ -7,11 +7,9 @@ ms.topic: include ms.date: 04/07/2021 --- - ::: moniker range="azure-devops" > [!NOTE] -> You can review changes made to an inherited process through the audit log. To learn more, see [Access, export, and filter audit logs](../../audit/azure-devops-auditing.md). - +> Review changes made to an inherited process through the audit log. For more information, see [Access, export, and filter audit logs](../../audit/azure-devops-auditing.md). -::: moniker-end \ No newline at end of file +::: moniker-end diff --git a/docs/organizations/settings/includes/note-on-prem-link.md b/docs/organizations/settings/includes/note-on-prem-link.md index 448a83d49a4..53a41c0ec71 100644 --- a/docs/organizations/settings/includes/note-on-prem-link.md +++ b/docs/organizations/settings/includes/note-on-prem-link.md @@ -4,22 +4,12 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include -ms.date: 04/07/2021 +ms.date: 06/03/2024 --- - -::: moniker range="azure-devops" - -> [!IMPORTANT] -> This article applies to Azure DevOps Services and Azure DevOps Server 2019 and later versions. To customize any project defined on a collection for TFS 2018 or earlier, see [On-premises XML process model](../../../reference/on-premises-xml-process-model.md). - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" > [!IMPORTANT] -> You can only use the Inheritance process model for projects defined on a project collection configured to support the Inheritance process model. If your on-premises collection is configured to use the On-premises XML process model, you can only use that process model to customize the work tracking experience. To learn more, see [Customize work tracking, Choose the process model for your project collection](../../../reference/customize-work.md?preserve-view=true&view=azure-devops-2019#choose-process-model). -> -> To customize any project defined on a collection for TFS 2018 or earlier, see [On-premises XML process model](../../../reference/on-premises-xml-process-model.md). +> The Inheritance process model is available for projects configured to support it. If you’re using an older collection, check the process model compatibility. If your on-premises collection is configured to use the on-premises XML process model, you can only use that process model to customize the work tracking experience. For more information, see [Choose the process model for your project collection](../../../reference/customize-work.md?preserve-view=true&view=azure-devops-2019#choose-process-model). -::: moniker-end \ No newline at end of file +::: moniker-end diff --git a/docs/organizations/settings/includes/open-process-admin-context-ts-only.md b/docs/organizations/settings/includes/open-process-admin-context-ts-only.md index f3d0221f368..15cf1b89cec 100644 --- a/docs/organizations/settings/includes/open-process-admin-context-ts-only.md +++ b/docs/organizations/settings/includes/open-process-admin-context-ts-only.md @@ -2,25 +2,26 @@ ms.topic: include ms.author: chcomley author: chcomley -ms.date: 07/17/2020 +ms.date: 04/08/2025 --- -## Open Settings>Process +## Open Settings > Process -You create, manage, and make customizations to processes from **Organization settings>Process**. +Create, manage, and make customizations to processes from the **Process** page. -1. Choose the :::image type="icon" source="../../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Then choose **Organization settings**. +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). +2. Select :::image type="icon" source="../../../media/icons/gear-icon.png" border="false"::: **Organization settings**. - > [!div class="mx-imgBorder"] - > ![Open Organization settings](../../../media/settings/open-admin-settings-vert.png) + > [!div class="mx-imgBorder"] + > ![Screenshot shows highlighted Organization settings button.](../../../media/settings/open-admin-settings-vert.png) -1. Then, choose **Process**. +3. Select **Process**. > [!div class="mx-imgBorder"] - > ![Organization Settings, Process page](/azure/devops/organizations/settings/work/media/process/open-process-page-s150.png) + > ![Screenshot shows Organization settings, Process page.](/azure/devops/organizations/settings/work/media/process/open-process-page-s150.png) > [!IMPORTANT] - > If you don't see **Process**, then you're working from TFS-2018 or earlier version. The **Process** page isn't supported. You must use the features supported for the [On-premises XML process model](../../../reference/customize-work.md). \ No newline at end of file + > If you don't see **Process**, then you're working from an earlier version where the **Process** page isn't supported. Use the features supported for the [On-premises XML process model](../../../reference/customize-work.md). diff --git a/docs/organizations/settings/includes/open-process-admin-context-ts.md b/docs/organizations/settings/includes/open-process-admin-context-ts.md index ea10e63c3a2..0c0bd6d48e0 100644 --- a/docs/organizations/settings/includes/open-process-admin-context-ts.md +++ b/docs/organizations/settings/includes/open-process-admin-context-ts.md @@ -7,62 +7,27 @@ ms.date: 08/03/2022 - - -::: moniker range=">= azure-devops-2019" - -## Open Settings>Process - -::: moniker-end +## Open organization process settings ::: moniker range="azure-devops" -You create, manage, and make customizations to processes from **Organization settings>Process**. - -1. Choose the :::image type="icon" source="../../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Then choose **Organization settings**. - - > [!div class="mx-imgBorder"] - > ![Open Projects>Organization settings.](../../../media/settings/open-admin-settings-vert.png) - -1. Then, choose **Process**. - - > [!div class="mx-imgBorder"] - > ![Then, choose Process.](/azure/devops/organizations/settings/work/media/process/open-process-page-s150.png) +1. Sign in to your organization (`https://dev.azure.com/{yourorganization}`). +1. Select :::image type="icon" source="../../../media/icons/gear-icon.png"::: **Organization settings**. + + :::image type="content" source="../../../media/settings/open-admin-settings-vert.png" alt-text="Screenshot showing Organization settings button for selection."::: - > [!IMPORTANT] - > If you don't see **Process**, then you're working from TFS-2018 or earlier version. The **Process** page isn't supported. You must use the features supported for the [On-premises XML process model](../../../reference/customize-work.md). +1. Select **Process**. + :::image type="content" source="../work/media/process/open-process-page-s150.png" alt-text="Screenshot showing highlighted Process button for selection."::: ::: moniker-end -::: moniker range=">= azure-devops-2020 < azure-devops" +::: moniker range="< azure-devops" -You create, manage, and make customizations to processes from **Collection Settings>Process**. +1. Sign in to your collection (`https://dev.azure.com/{Your_Collection}`). +1. Select **Collection Settings** or **Admin settings**. +1. Select **Process**. -1. Choose the :::image type="icon" source="../../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Choose the project collection whose processes you want to customize, and then choose **Collection Settings**. - - > [!div class="mx-imgBorder"] - > ![Open Projects>Organization settings](/azure/devops/organizations/settings/work/media/process/open-process-page-2020.png) - -1. Then, choose **Process**. - - > [!div class="mx-imgBorder"] - > ![Then, choose Process.](/azure/devops/organizations/settings/work/media/process/open-process-2020.png) + :::image type="content" source="../work/media/process/open-process-2020.png" alt-text="Screenshot showing highlighted Process button in Collection settings."::: ::: moniker-end - -::: moniker range="azure-devops-2019" - -You create, manage, and make customizations to processes from **Admin settings>Process**. - -1. Choose the :::image type="icon" source="../../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Then choose **Admin settings**. - - > [!div class="mx-imgBorder"] - > ![Open Project>Organization settings.](../../../media/settings/open-admin-settings-2019.png) - -1. Then, choose **Process**. - - > [!div class="mx-imgBorder"] - > ![Then, choose Process.](/azure/devops/organizations/settings/work/media/process/open-process-page-2019.png) - -::: moniker-end \ No newline at end of file diff --git a/docs/organizations/settings/includes/prerequisites-change-process.md b/docs/organizations/settings/includes/prerequisites-change-process.md index fe3789c70a4..ec2ab065b80 100644 --- a/docs/organizations/settings/includes/prerequisites-change-process.md +++ b/docs/organizations/settings/includes/prerequisites-change-process.md @@ -3,13 +3,11 @@ ms.topic: include ms.author: chcomley author: chcomley ms.reviewer: dahellem -ms.date: 07/17/2020 +ms.date: 11/12/2024 --- -## Prerequisites -- To change a process: - - To create, delete or edit a process, you must be a member of the [**Project Collection Administrators** group](../../security/change-organization-collection-level-permissions.md), or have the corresponding collection-level permissions **Create process**, **Delete process**, **Edit process**, or **Delete a field from organization** set to **Allow**. See [Set permissions and access for work tracking, Customize an inherited process](../../security/set-permissions-access-work-tracking.md#customize-an-inherited-process). - - Users granted **Basic** or **Stakeholder** access can be granted permissions to create, edit, and delete processes, and administer process permissions. -- To update Kanban boards, you must be the team administrator for the boards or a member of the [**Project Administrators** group](../../security/change-project-level-permissions.md) -- To update and change the work item type of existing work items, you must be a member of the project. \ No newline at end of file +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To create, delete, or edit a process: Member of the [Project Collection Administrators](../../security/change-organization-collection-level-permissions.md) group or specific collection-level permissions **Create process**, **Delete process**, **Edit process**, or **Delete a field from organization**. For more information, see [Set permissions and access for work tracking, Customize an inherited process](../../security/set-permissions-access-work-tracking.md#customize-an-inherited-process).
      - To update boards: [Team Administrator](../add-team-administrator.md) or a member of the [Project Administrators](../../security/change-project-level-permissions.md) group. | +| **Access** | - Even if you have **Basic** or lower access, you can still change a process if someone gives you permissions to do so.
      - To update and change the type of your existing work items: [Project member](../../security/add-users-team-project.md). | diff --git a/docs/organizations/settings/includes/prerequisites-team-settings.md b/docs/organizations/settings/includes/prerequisites-team-settings.md index d3ebfe4d9d3..f1288154fab 100644 --- a/docs/organizations/settings/includes/prerequisites-team-settings.md +++ b/docs/organizations/settings/includes/prerequisites-team-settings.md @@ -2,10 +2,8 @@ ms.topic: include --- - - -## Prerequisites - -To configure team settings, you must be added to the Team Administrator role or be a member of the **Project Administrators** security group. To get added, see [Add a team administrator](../add-team-administrator.md) or [Change project-level permissions](../../security/change-project-level-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| [Team administrator](../add-team-administrator.md) or member of the [Project Administrators](../../security/change-project-level-permissions.md) group.| diff --git a/docs/organizations/settings/includes/process-customize-backlogs.md b/docs/organizations/settings/includes/process-customize-backlogs.md index a32682a4f8f..628b470310b 100644 --- a/docs/organizations/settings/includes/process-customize-backlogs.md +++ b/docs/organizations/settings/includes/process-customize-backlogs.md @@ -4,10 +4,9 @@ ms.author: chcomley author: chcomley ms.prod: azure-devops ms.topic: include -ms.date: 04/07/2021 +ms.date: 07/16/2024 --- - Backlogs and boards are essential Agile tools for creating and managing work for a team. The standard backlogs—product, iteration, and portfolio—inherited from the system process are fully customizable. In addition, you can add custom portfolio backlogs for a total of five portfolio backlogs. --- @@ -25,7 +24,7 @@ Backlogs and boards are essential Agile tools for creating and managing work for **Inherited backlogs** :::column-end::: :::column span="2"::: - - [Add a custom work item type](../work/customize-process-backlogs-boards.md#edit-product-backlog) + - [Add a custom work item type (WIT)](../work/customize-process-backlogs-boards.md#edit-product-backlog) ::: moniker range=">= azure-devops-2020" - [Add an inherited work item type](../work/customize-process-backlogs-boards.md#add-oob-to-backlog) ::: moniker-end @@ -39,36 +38,31 @@ Backlogs and boards are essential Agile tools for creating and managing work for **Custom portfolio backlogs** :::column-end::: :::column span="2"::: - - [Add a portfolio backlog which displays custom work item types](../work/customize-process-backlogs-boards.md#add-portfolio-backlog) + - [Add a portfolio backlog that displays custom work item types (WITs)](../work/customize-process-backlogs-boards.md#add-portfolio-backlog) - [Edit or rename a portfolio backlog](../work/customize-process-backlogs-boards.md#edit-portfolio-backlog) - [Delete the top-level custom portfolio backlog](../work/customize-process-backlogs-boards.md#edit-portfolio-backlog) :::column-end::: :::row-end::: --- - -**What you can't customize** +**Unsupported customizations:** ::: moniker range=">= azure-devops-2020" -- You can't remove an inherited portfolio level from the product (but you can rename the portfolio level and you can disable an inherited work item type) -- You can't insert a backlog level within the existing set of defined backlogs -- You can't reorder the backlog levels -- You can't add a work item type to two different backlog levels -- You can't create a custom task backlog level, although you can add custom WITs to the iteration backlog -- You can't add the *Bug* WIT to any backlog level. Instead, the system allows each team to decide how they want to manage bugs. To learn more, see [Show bugs on backlogs and boards](../show-bugs-on-backlog.md). +- **Removing an inherited portfolio level:** + - While you can’t directly remove an inherited portfolio level from a product, you have a couple of options: + - **Rename the portfolio level:** You can rename the inherited portfolio level to better suit your needs. + - **Disable an inherited WIT:** If the inherited portfolio level includes WITs that you don’t want to use, you can disable them. This action prevents teams from creating new work items of those types. +- **Inserting a backlog level:** + - You can't insert a new backlog level within the existing set of defined backlogs. The predefined backlog levels are typically fixed (for example, Epics, Features, User Stories, Tasks), and you can’t add custom ones in between. +- **Reordering backlog levels:** + - Unfortunately, you can't reorder the backlog levels. They usually follow a predefined hierarchy, and changing their order isn’t supported. +- **Adding a WIT to multiple backlog levels:** + - Each WIT can only belong to one backlog level. You can't add a WIT to two different backlog levels simultaneously. +- **Creating a custom task backlog level:** + - Although you can't create a custom task-specific backlog level, you can still add custom WITs to the iteration backlog. For example, you could create a custom WIT called "Enhancement" or "Maintenance" and associate it with the iteration backlog. +- **Managing bugs:** + - The Bug WIT doesn’t belong to any specific backlog level by default. Instead, each team can decide how they want to manage bugs. You can choose to [show bugs on backlogs and boards or handle them separately](../show-bugs-on-backlog.md). ::: moniker-end - -::: moniker range="azure-devops-2019" - -- You can't add or remove an inherited WIT to or from a backlog, for example, you can't add the Issue WIT to the product backlog -- You can't remove an inherited portfolio level from the product (but you can rename the portfolio level and you can disable an inherited work item type) -- You can't insert a backlog level within the existing set of defined backlogs -- You can't reorder the backlog levels -- You can't add a work item type to two different backlog levels -- You can't create a custom task level, although you can add custom work item types to the iteration backlog -- You can't add the *Bug* WIT to any backlog level. Instead, the system allows each team to decide how they want to manage bugs. To learn more, see [Show bugs on backlogs and boards](../show-bugs-on-backlog.md). - -::: moniker-end \ No newline at end of file diff --git a/docs/organizations/settings/includes/process-customize-workflow.md b/docs/organizations/settings/includes/process-customize-workflow.md index 8086282df4c..f137f259caf 100644 --- a/docs/organizations/settings/includes/process-customize-workflow.md +++ b/docs/organizations/settings/includes/process-customize-workflow.md @@ -7,19 +7,12 @@ ms.topic: include ms.date: 07/17/2020 --- -You can customize the workflow of any work item type (WIT) by hiding inherited states or adding custom states. Inherited states differ based on the system process —[Agile, Basic, Scrum, or CMMI](../../../boards/work-items/guidance/choose-process.md#workflow-states), —you chose from which to create your custom process. +You can customize the workflow of any work item type (WIT) by hiding inherited states or adding custom states. Inherited states vary based on the system process that you selected to create your custom process. The options are *Agile*, *Basic*, *Scrum*, or *Capability Maturity Model Integration (CMMI)*. For more information, see [Workflow states, transitions, and reasons](../../../boards/work-items/guidance/choose-process.md#workflow-states). -Each default workflow for each WIT defines between two and four States and specifies the following workflow operations: - -- Forward and backward transitions between each state -- Default reasons for each state transition - -For example, the Basic process, Issue WIT is characterized by the three States—**To Do**, **Doing**, and **Done**—and transitions shown in the following image. - - -> [!div class="mx-imgBorder"] -> ![Basic Process, Issue work item type, workflow state model](/azure/devops/organizations/settings/work/media/customize-workflow/basic-process-issue-workflow.png) +Each default workflow for each WIT defines between two and four states and specifies the following workflow operations: +- Forward and backward transitions between each state. For example, the Basic process Issue WIT includes three states—**To Do**, **Doing**, and **Done**. +- Default reasons for each state transition --- :::row::: @@ -33,7 +26,7 @@ For example, the Basic process, Issue WIT is characterized by the three States&m --- :::row::: :::column span=""::: - ![Inherited icon](/azure/devops/organizations/settings/work/media/process/inherited-icon.png) Inherited states + :::image type="icon" source="/azure/devops/organizations/settings/work/media/process/inherited-icon.png"::: Inherited states :::column-end::: :::column span="2"::: - [Hide or unhide a state](../work/customize-process-workflow.md#hide-state) @@ -54,36 +47,24 @@ For example, the Basic process, Issue WIT is characterized by the three States&m --- -### Workflow states must conform to the following rules +### Workflow states must conform to the following rules -- You must define at least one state for either the *Proposed* or *In Progress* State categories +- Define at least one state for either the *Proposed* or *In Progress* State categories. > [!NOTE] - > Before adding a workflow state, review [Workflow states and state categories](../../../boards/work-items/workflow-and-state-categories.md) to learn how workflow states map to state categories. -- You must define at least two workflow States -- You can define a maximum of 32 workflow States per work item type + > Before you add a workflow state, see [About workflow states in backlogs and boards](../../../boards/work-items/workflow-and-state-categories.md) to learn how workflow states map to state categories. +- Define at least two workflow States. +- Define a maximum of 32 workflow States per work item type. -### Unsupported workflow customizations +### Unsupported workflow customizations ::: moniker range=">= azure-devops-2020" -- You can't modify an inherited state (you can't change its name, color, or category), but you can hide it -- You can only have one state in the *Completed* state category. If you add a custom state to the Completed category, any other state is removed or hidden -- You can't change the name of a custom state -- You can't specify a Reason for a state, instead, default reasons are defined such as *Moved to state Triaged*, *Moved out of state Triaged* -- You can't change the location of the State and Reason fields on the form -- You can't customize state category names +- Hide inherited states if you don't want them visible (you can't change their name, color, or category). +- Ensure only one state exists in the *Completed* state category. Adding a custom state to this category removes or hides any other state. +- Keep the name of custom states as is; you can't change them. +- Use default reasons for state transitions, such as *Moved to state Triaged* and *Moved out of state Triaged*; you can't specify custom reasons. +- Accept the default location of the State and Reason fields on the form; you can't change their placement. +- Use the default state category names; you can't customize them. ::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops-2020" - -- You can't modify an inherited state (you can't change its name, color, or category), but you can hide it -- You can only have one state in the *Completed* state category. The system disallows adding any custom state to this category -- You can't change the name of a custom state -- You can't change the order of states, states are listed in their natural sequence based on their state category within the drop-down list of a work item form -- You can't specify a Reason for a state, instead, default reasons are defined such as *Moved to state Triaged*, *Moved out of state Triaged* -- You can't change the location of the State and Reason fields on the form -- You can't restrict transitions, all transitions are defined from any state to another state. - -::: moniker-end diff --git a/docs/organizations/settings/includes/process-prerequisites.md b/docs/organizations/settings/includes/process-prerequisites.md index 461dfbbfc8f..392eac31755 100644 --- a/docs/organizations/settings/includes/process-prerequisites.md +++ b/docs/organizations/settings/includes/process-prerequisites.md @@ -2,21 +2,11 @@ ms.topic: include --- -## Prerequisites - -Prior to customizing a process, we recommend that you review [Configure and customize Azure Boards](../../../boards/configure-customize.md), which provides guidance on how to customize Azure Boards to meet your business needs. For a description of the different backlogs and boards, see [Tasks supported by Backlogs, Boards, Taskboards, and Plans](../../../boards/backlogs/backlogs-boards-plans.md). - -::: moniker range="azure-devops" - -- You must have an organization created in Azure DevOps Services. If you haven't created one yet, [do that now](../../../user-guide/sign-up-invite-teammates.md). -- To create, edit, and manage processes, you must be a member of the [**Project Collection Administrators** group](../../security/change-organization-collection-level-permissions.md), or have the corresponding collection-level permissions **Create process**, **Delete process**, **Edit process**, or **Delete a field from organization** set to **Allow**. See [Set permissions and access for work tracking, Customize an inherited process](../../security/set-permissions-access-work-tracking.md#customize-an-inherited-process). - - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - -- You must have selected the Inheritance process model for the project collection where the project is created. To learn more, see [Choose the process model for your project collection](../../../reference/customize-work.md#choose-the-process-model-for-your-project-collection). -- To create, edit, and manage processes, you must be a member of the [**Project Collection Administrators** group](../../security/change-organization-collection-level-permissions.md), or have the corresponding permissions **Create process**, **Delete process**, **Edit process**, or **Delete a field from organization** set to **Allow**. See [Set permissions and access for work tracking, Customize an inherited process](../../security/set-permissions-access-work-tracking.md). - -::: moniker-end \ No newline at end of file +For guidance on tailoring Azure Boards to align with your specific business requirements, see [About configuring and customizing Azure Boards](../../../boards/configure-customize.md). + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To create, delete, or edit a process: Member of the [Project Collection Administrators](../../security/change-organization-collection-level-permissions.md) group or specific collection-level permissions **Create process**, **Delete process**, **Edit process**, or **Delete a field from organization** set to **Allow**. For more information, see [Set permissions and access for work tracking, Customize an inherited process](../../../security/set-permissions-access-work-tracking.md#customize-an-inherited-process).
      - To update boards: [Team Administrator](../add-team-administrator.md) or a member of the [Project Administrators](../../security/change-project-level-permissions.md) group. | +| **Access** | - Even if you have **Basic** or lower access, you can still change a process if someone gives you permissions to do so.
      - To update and change the type of your existing work items: Member of the project. | +| **Project process model** | - Have the [Inheritance process model](../../../reference/customize-work.md#choose-the-process-model-for-your-project-collection) for the project collection containing the project.
      - If migrating data to Azure DevOps Services, use the [Team Foundation Server Database Import Service](../../../migrate/migration-overview.md). | +| **Knowledge** | Familiarity with the [customization and process models](../../../reference/customize-work.md). | diff --git a/docs/organizations/settings/manage-authorizations.md b/docs/organizations/settings/manage-authorizations.md index f1d4df1a67a..d6bf2cc298e 100644 --- a/docs/organizations/settings/manage-authorizations.md +++ b/docs/organizations/settings/manage-authorizations.md @@ -7,58 +7,65 @@ ms.assetid: 314a28cd-b2ae-41a0-8dfb-330222c1aed0 monikerRange: 'azure-devops' ms.author: chcomley author: chcomley -ms.date: 06/22/2023 +ms.date: 10/21/2024 --- # Authorize other services to access Azure DevOps [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -You can authorize other services to access Azure DevOps. The OAuth 2.0 framework provides safe, secure access to your resources. Some of these resources include work items, source code, and build results. +> [!IMPORTANT] +> This article applies to Azure DevOps OAuth authorizations. Azure DevOps OAuth is slated for deprecation in 2026. [Learn more in our blog post](https://devblogs.microsoft.com/devops/no-new-azure-devops-oauth-apps-beginning-february-2025/). -- A service uses the authorization, bound to your credentials, to access resources in any organization that you have access to. -- Use your Microsoft account, like ```me@live.com```, or your work account, your account in Azure AD - like ```me@my-workplace.com```, to authorize the service. -- The service that you authorize never has access to your Azure DevOps credentials. -- Revoke any authorizations that you've granted to other services. +You can grant other services access to Azure DevOps using the OAuth 2.0 framework. This secure authorization allows services to access resources like work items, source code, and build results. When authorizing a service, use your Microsoft account (for example, `me@live.com`) or your work account (for example, `me@my-workplace.com`). The authorized service doesn't have access to your Azure DevOps credentials, and you can revoke authorizations as needed. + +## Prerequisites + +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - Member of the **Project Administrators** security group.
      - The service has the **Contributor** role or a custom role with similar permissions on the resources it needs to access.| +|**Service compatibility**| The service you intend to authorize supports OAuth 2.0 integration with Azure DevOps.| ## Authorize a service A typical authorization flow might be similar to the following example: -1. You're using a service that uses Azure DevOps resources, so the service requests authorization. +1. When you're using a service that relies on Azure DevOps resources, the service requests authorization. -2. If you're not already signed in, Azure DevOps prompts you for your credentials. +2. If you're not already signed in, Azure DevOps prompts you to enter your credentials. :::image type="content" source="../../service-hooks/media/authorize/vso-sign-in.png" alt-text="Screenshot of the Visual Studio sign in prompt."::: -3. After you've signed in, you get the authorization approval page. +3. After signing in, you get the authorization approval page. :::image type="content" source="../../service-hooks/media/authorize/vso-authorize.png" alt-text="Screenshot of Accept or Deny buttons for authorization of the application."::: - A service can only request full access through the REST APIs, so the authorization request may not be specific. + A service can only request full access through the REST APIs, so the authorization request might not be specific. 4. Review the request and approve the authorization. -5. The authorized service uses that authorization to access resources in your Azure DevOps organization. + The authorized service can access resources within your Azure DevOps organization. -To ensure an authorization request is legitimate, do the following actions: +5. To ensure an authorization request is legitimate, do the following actions: -- Look for the Azure DevOps branding across the upper portion of the authorization approval page. -- Ensure the authorization approval page URL begins with ```https://app.vssps.visualstudio.com/```. -- Pay attention to any HTTPS-related security warnings in your browser. -- Remember that other services don't ask for your credentials directly. They let you provide them to Azure DevOps through the authorization approval page. + - Check for the Azure DevOps branding at the top of the approval page. + - Ensure the approval page URL starts with ```https://app.vssps.visualstudio.com/```. + - Be alert for any HTTPS-related security warnings in your browser. + - Remember that services don't directly ask for your credentials; they rely on the authorization approval page provided by Azure DevOps. ## Manage authorizations -View the services that you've authorized to access your organization. +Review the services that you granted authorization to access your organization. 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Choose :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **User settings**, and then choose **Profile**. -3. Choose **Authorizations**. +2. Select :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **User settings** > **Profile**. +3. Select **Authorizations**. :::image type="content" source="media/profile-settings-authorizations.png" alt-text="Screenshot of profile settings with Authorizations selected."::: -You can revoke any authorizations so the service can no longer access your organization on your behalf. +4. To revoke an authorization so the service can't access your organization on your behalf, select :::image type="icon" source="../../boards/media/icons/trash-can.png" border="false"::: **Revoke** > **Revoke**. + + :::image type="content" source="media/revoke-authorized-app.png" alt-text="Screenshot showing highlighted Revoke trash can for selection."::: ## Next steps @@ -68,7 +75,7 @@ You can revoke any authorizations so the service can no longer access your organ ## Related articles - [Change application access policies](../accounts/change-application-access-policies.md) -- [Service accounts and dependencies](/azure/devops/server/admin/service-accounts-dependencies) -- [Add users to an organization (Azure DevOps Services)](../accounts/add-organization-users.md) -- [Add users to a team or a project](../../organizations/security/add-users-team-project.md) -- [Add users to an administrator role](/azure/devops/server/admin/add-administrator) +- [Manage service accounts and dependencies](/azure/devops/server/admin/service-accounts-dependencies) +- [Add users to an organization (Azure DevOps Services)](../accounts/add-organization-users.md) +- [Add users to a team or project](../../organizations/security/add-users-team-project.md) +- [Assign users to an administrator role](/azure/devops/server/admin/add-administrator) diff --git a/docs/organizations/settings/manage-banners.md b/docs/organizations/settings/manage-banners.md index 836ad970a37..28b66ec2bf4 100644 --- a/docs/organizations/settings/manage-banners.md +++ b/docs/organizations/settings/manage-banners.md @@ -7,77 +7,74 @@ ms.custom: devx-track-azurecli ms.author: chcomley author: chcomley ms.topic: how-to -monikerRange: '>= azure-devops-2019' -ms.date: 04/25/2022 +monikerRange: "<=azure-devops" +ms.date: 09/11/2024 --- # Add and manage information banners in Azure Devops [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -A quick and effective way to communicate with your Azure DevOps users is through information banners. Use banners to alert users to upcoming changes or events without sending out mass emails. +Use information banners to quickly and effectively communicate with your Azure DevOps users. Alert users to upcoming changes or events without sending mass emails. -You can specify one of three types of banners: error, information, and warning. Only one banner, the last one added or updated, is displayed at a time. Banners remain in effect until their expiration date. +Specify one of three types of banners: error, information, or warning. Only the last added or updated banner is displayed at a time. Banners remain in effect until their expiration date. -The following image shows how an information message is displayed. Users can cancel the message by selecting **Close** :::image type="icon" source="../../media/icons/close-filter.png" border="false":::. +The following image shows an information message. Users can cancel the message by selecting **Close** :::image type="icon" source="../../media/icons/close-filter.png" border="false":::. :::image type="content" source="media/banners/show-banner-info.png" alt-text="Information banner"::: -Banners are restricted to a length of thirty words. Banners are prioritized by level. For example, if you have posted a warning message and an info message, the info message will only be shown after a user closes the warning message, or you delete the warning message. - +We limit banners to 30 words prioritize by level. So, if you post a warning message and an info message, the info message only shows after the user closes or you delete the warning message. ## Prerequisites ::: moniker range="azure-devops" -- To add or manage banners, you must be a member of the **Project Collection Administrators** security group. To get added, see [Change permissions at the organization or collection-level](../security/change-organization-collection-level-permissions.md). -- To manage banners using the Banner Settings extension, you must first install it. See [Banner Settings](https://marketplace.visualstudio.com/items?itemName=ms-eswm.banner-settings-hub) and [Install extensions](../../marketplace/install-extension.md) -- To manage banners using the command line, you must install the Azure DevOps CLI extension as described in [Get started with Azure DevOps CLI](../../cli/index.md). - - Sign into Azure DevOps using `az login`. - - For the examples in this article, set the default organization using `az devops configure --defaults organization=YourOrganizationURL`. -::: moniker-end +| Category | Requirements | +|--------------|-------------| +|**Permissions** | Member of the [Project Collection Administrators](../security/change-organization-collection-level-permissions.md) group.| +|**Extensions** |- [Banner Settings](https://marketplace.visualstudio.com/items?itemName=ms-eswm.banner-settings-hub). For more information, see [Install extensions](../../marketplace/install-extension.md).
      - [Azure DevOps CLI](../../cli/index.md).
      - Sign into Azure DevOps using `az login`.
      - For the examples in this article, set the default organization using `az devops configure --defaults organization=YourOrganizationURL`.| +::: moniker-end ::: moniker range="< azure-devops" -- To add or manage banners, you must be a member of the **Project Collection Administrators** security group. To get added, see [Change permissions at the organization or collection-level](../security/change-organization-collection-level-permissions.md). -- You must install the free [Banner Settings](https://marketplace.visualstudio.com/items?itemName=ms-eswm.banner-settings-hub) marketplace extension on the project collection where you want to manage banners. See also [Install extensions for on-premises servers](../../marketplace/get-tfs-extensions.md). + +| Category | Requirements | +|--------------|-------------| +|**Permissions** | Member of the [Project Collection Administrators](../security/change-organization-collection-level-permissions.md) group.| +|**Extensions** |- [Banner Settings](https://marketplace.visualstudio.com/items?itemName=ms-eswm.banner-settings-hub). For more information, see [Install extensions for on-premises servers](../../marketplace/get-tfs-extensions.md).| + ::: moniker-end ## Manage banners using the Banner Settings extension ::: moniker range="azure-devops" -The Banner Settings extension provides a settings pane under **Organization Settings** to add and manage sitewide banners. The extension supports the following features: +The Banner Settings extension provides a settings pane under **Organization settings** to add and manage sitewide banners. The extension supports the following features: ::: moniker-end ::: moniker range="< azure-devops" -The Banner Settings extension provides a settings pane under **Collection Settings** to add and manage sitewide banners. The extension supports the following features: +The Banner Settings extension provides a settings pane under **Collection settings** to add and manage sitewide banners. The extension supports the following features: ::: moniker-end - Show banners on any page in Azure DevOps - Choose between three levels of messages: Info, Warning, and Error - Choose an expiration date for a message -- Include hyperlinks in banners using markdown syntax. +- Include hyperlinks in banners using markdown syntax ::: moniker range="azure-devops" ### Open Organization settings -To add or delete a banner, open **Organization settings**, scroll down to the **Extensions** section, and choose **Banner**. - -Organization settings configure resources for all projects or the entire organization. For an overview of all organization settings, see [Project collection administrator role and managing collections of projects](about-settings.md#admin). +To add or delete a banner, open **Organization settings**, scroll down to the **Extensions** section, and choose **Banner**. -1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**, and then choose **Collection settings**. - - > [!div class="mx-imgBorder"] - > ![Open Organization settings](../../media/settings/open-admin-settings-vert.png) +Organization settings configure resources for all projects respectively for the entire organization. For an overview of all organization settings, see [Project collection administrator role and managing collections of projects](about-settings.md#admin). -2. Select a service from the sidebar. Settings are organized based on the service they support. Expand or collapse the major sections such as **Boards** and **Pipelines** to choose a page. +1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**, and then choose **Organization settings**. > [!div class="mx-imgBorder"] - > ![Organization settings, Projects](../../media/settings/admin-organization-settings.png) + > ![Screenshot of opening Organization settings.](../../media/settings/open-admin-settings-vert.png) ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" ### Open Admin settings @@ -94,7 +91,9 @@ Admin settings configure resources for all projects in a project collection. For ### Add and manage banners -1. If no banners have been defined, choose **Create a new banner**. +#### [Web portal](#tab/browser) + +1. If no banners are defined, select **Create a new banner**. Otherwise, select **Edit more** for the banner and go to step 3. ::: moniker range="azure-devops" :::image type="content" source="media/banners/open-banner-extension-cloud.png" alt-text="Create first banner, on-premises"::: @@ -103,11 +102,14 @@ Admin settings configure resources for all projects in a project collection. For :::image type="content" source="media/banners/open-banner-extension-on-premises.png" alt-text="Create first banner, on-premises"::: ::: moniker-end -1. Enter the banner text into the text box. Choose **Edit more** to change the message level and set the expiration date. +2. Enter the banner text into the text box. Select **Edit more** to change the message level and set the expiration date. :::image type="content" source="media/banners/banner-extension-test-message.png" alt-text="Add test banner message"::: -1. Choose :::image type="icon" source="media/banners/banner-save-icon.png" border="false"::: **Save** to save your changes. +3. :::image type="icon" source="media/banners/banner-save-icon.png" border="false"::: **Save** your changes. +4. (Optional) **Delete all banners** or select the trash can icon to delete a specific banner. + +#### [Azure CLI](#tab/AzureCLI/) ::: moniker range="azure-devops" @@ -141,8 +143,11 @@ az devops admin banner add --message ### Parameters -- **message**: Required. Text string that specifies the banner message to display. Text strings are limited to a maximum of thirty words. -- **expiration**: Optional. Date/time when the banner should no longer be displayed to users. For example, "2019-06-10 17:21:00 UTC", "2019-06-10". +- **message**: Required. Text string that specifies the banner message to display. Text strings are limited to a maximum of 30 words. + + The message might contain links in HTML format (`Link text`). Any ampersand in the url, for example in the query string, must be escaped in the xml entity format (`&`). + +- **expiration**: Optional. Date/time when the banner should no longer be displayed to users. For example, "2019-06-10 17:21:00 UTC", "2019-06-10." - **ID**: Optional. ID of the banner to update. This identifier is needed to change or remove the message later. A unique identifier is automatically created if one isn't specified. - **type**: Optional. Type of banner to display. Valid values: **error**, **info**, **warning**. Default is **info**. @@ -152,7 +157,7 @@ For example, the following command adds an information banner, which expires on > [!div class="tabbedCodeSnippets"] ```azurecli -az devops admin banner add --message "INFORMATION: Network domain updates will occur on September 3" --expiration 2019-09-04 --type info +az devops admin banner add --message "INFORMATION: Network domain updates will occur on September 3. More information" --expiration 2019-09-04 --type info { "3d584103-6a94-4f46-8696-f424278da072": { "expirationDate": "2019-09-04T00:00:00-07:00", @@ -161,7 +166,8 @@ az devops admin banner add --message "INFORMATION: Network domain updates will o } } ``` - + + ## List banners @@ -176,7 +182,7 @@ az devops admin banner list If you don't specify the output, the list displays in json format. For other output format options, see [Output formats for Azure CLI commands](/cli/azure/format-output-azure-cli). -For example, the following command indicates that two banners have been defined. +For example, the following command indicates that two banners are defined. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -250,9 +256,9 @@ Here we list the details for banner with `id=7653f414-3c01-424f-8f84-e51aa99b797 az devops admin banner show --id 7653f414-3c01-424f-8f84-e51aa99b797c { "7653f414-3c01-424f-8f84-e51aa99b797c": { - "expirationDate": "2019-09-04T07:00:00+00:00", + "expirationDate": "2024-09-04T07:00:00+00:00", "level": "info", - "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce ac lectus eget erat porttitor dapibus vulputate in ipsum. Etiam id faucibus nisi, at ornare tellus. Curabitur faucibus pharetra orci, id finibus leo iaculis et. Morbi nec felis facilisis, ultricies magna nec, convallis sem. Sed pharetra porta mi eu venenatis. Cras consectetur et dui a accumsan. Maecenas non dolor eu lacus mollis pulvinar. Fusce gravida id lacus sed consequat. Cras tempus ante tincidunt purus rhoncus, at consectetur tellus sollicitudin. Proin sed tellus vel libero maximus ornare. Nullam facilisis, nibh sit amet faucibus rutrum, diam massa ullamcorper purus, sed tempor est erat in sapien. Sed sit amet lectus vel massa facilisis interdum id sit amet nisi. Vestibulum eu purus et mi ultricies consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum fermentum mattis rutrum. Nulla hendrerit nibh ut sapien viverra faucibus." + "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit." } } ``` @@ -272,7 +278,7 @@ az devops admin banner update --id ### Parameters - **ID**: Required. ID of the banner to update. -- **expiration**: Optional. Date/time when the banner should no longer be displayed to users. To unset the expiration for the banner, supply an empty value to this argument, for example, "2019-06-10 17:21:00 UTC", "2019-06-10". +- **expiration**: Optional. Date/time when the banner should no longer be displayed to users. To unset the expiration for the banner, supply an empty value to this argument, for example, "2019-06-10 17:21:00 UTC", "2019-06-10." - **message**: Text string that specifies the banner message to display. - **type**: Optional. Type of banner to display. Valid values: **error**, **info**, **warning**. Default is **info**. @@ -282,26 +288,32 @@ For example, the following command updates the message string for the banner and > [!div class="tabbedCodeSnippets"] ```azurecli -az devops admin banner update --id 7653f414-3c01-424f-8f84-e51aa99b797c --message "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce ac lectus eget erat porttitor dapibus vulputate in ipsum. Etiam id faucibus nisi, at ornare tellus. Curabitur faucibus pharetra orci, id finibus leo iaculis et. Morbi nec felis facilisis, ultricies magna nec, convallis sem. Sed pharetra porta mi eu venenatis. Cras consectetur et dui a accumsan. Maecenas non dolor eu lacus mollis pulvinar. Fusce gravida id lacus sed consequat. Cras tempus ante tincidunt purus rhoncus, at consectetur tellus sollicitudin. Proin sed tellus vel libero maximus ornare. Nullam facilisis, nibh sit amet faucibus rutrum, diam massa ullamcorper purus, sed tempor est erat in sapien. Sed sit amet lectus vel massa facilisis interdum id sit amet nisi. Vestibulum eu purus et mi ultricies consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum fermentum mattis rutrum. Nulla hendrerit nibh ut sapien viverra faucibus. " --expiration 2019-12-31 +az devops admin banner update --id 7653f414-3c01-424f-8f84-e51aa99b797c --message "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce ac lectus eget erat porttitor dapibus vulputate in ipsum.." --expiration 2019-12-31 { "7653f414-3c01-424f-8f84-e51aa99b797c": { "expirationDate": "2019-12-31T00:00:00-08:00", "level": "info", - "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce ac lectus eget erat porttitor dapibus vulputate in ipsum. Etiam id faucibus nisi, at ornare tellus. Curabitur faucibus pharetra orci, id finibus leo iaculis et. Morbi nec felis facilisis, ultricies magna nec, convallis sem. Sed pharetra porta mi eu venenatis. Cras consectetur et dui a accumsan. Maecenas non dolor eu lacus mollis pulvinar. Fusce gravida id lacus sed consequat. Cras tempus ante tincidunt purus rhoncus, at consectetur tellus sollicitudin. Proin sed tellus vel libero maximus ornare. Nullam facilisis, nibh sit amet faucibus rutrum, diam massa ullamcorper purus, sed tempor est erat in sapien. Sed sit amet lectus vel massa facilisis interdum id sit amet nisi. Vestibulum eu purus et mi ultricies consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum fermentum mattis rutrum. Nulla hendrerit nibh ut sapien viverra faucibus. " + "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.." } } ``` ::: moniker-end +::: moniker range=" < azure-devops" +[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] +::: moniker-end + +* * * + ## Related articles ::: moniker range="azure-devops" - [Get started managing your organization or project collection](../../user-guide/manage-organization-collection.md) -- [About projects and scaling your organization](../projects/about-projects.md) +- [Learn about projects and scaling your organization](../projects/about-projects.md) - [Get started with Azure DevOps CLI](../../cli/index.md) -- [az devops admin banner commands](/cli/azure/devops/admin/banner) +- [Use az devops admin banner commands](/cli/azure/devops/admin/banner) ::: moniker-end ::: moniker range="< azure-devops" - [Get started managing your organization or project collection](../../user-guide/manage-organization-collection.md) -- [About projects and scaling your organization](../projects/about-projects.md) +- [Learn about projects and scaling your organization](../projects/about-projects.md) ::: moniker-end diff --git a/docs/organizations/settings/manage-teams.md b/docs/organizations/settings/manage-teams.md index f0744f9d2ba..87f281b47c8 100644 --- a/docs/organizations/settings/manage-teams.md +++ b/docs/organizations/settings/manage-teams.md @@ -1,19 +1,19 @@ --- title: Manage teams, configure team tools titleSuffix: Azure DevOps -description: Administrators learn how access team tools, add users, configure backlogs, iteration paths, Kanban boards, and more in Azure DevOps. +description: Administrators learn how access team tools, add users, configure backlogs, iteration paths, boards, and more in Azure DevOps. ms.subservice: azure-devops-settings ms.custom: teams ms.author: chcomley author: chcomley -ms.topic: overview -monikerRange: '<= azure-devops' -ms.date: 02/28/2023 +ms.topic: how-to +monikerRange: "<=azure-devops" +ms.date: 11/12/2024 --- # Manage and configure team tools -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] If you're a team administrator, you have the flexibility to tailor your backlogs and boards to align with your team's workflow. In case you require a new team, you can ask a Project Administrator group member to create one for you, which takes only a minute. Team administrators have the ability to set up and oversee all team tools. @@ -27,24 +27,21 @@ Team administrators perform the following tasks for team tools: ## Prerequisites -- To perform any team configuration task, you must be a team administrator for the team to be modified, or be a member of the **Project Administrators** group. For more information, see [Change project-level permissions](../security/change-project-level-permissions.md). -- To add a team, you must be a member of the **Project Administrators** group. For more information, see [Add teams](add-teams.md). +|Category | Requirements | +|--------------|-------------| +|**Permissions** |- To manage teams: [Team administrator](add-team-administrator.md) or member of the [Project Administrators](../security/change-project-level-permissions.md) group.
      - To add a team: Member of the [Project Administrators](../security/change-project-level-permissions.md) group. For more information, see [Add teams](add-teams.md).| [!INCLUDE [temp](../../boards/includes/note-configure-customize.md)] -::: moniker range=">= azure-devops-2019" - ## Open your team profile Open your team profile to quickly access items defined for your team. -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```), and then open your project. -2. Select **Project settings** > **Teams** > your team name. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). +2. Select **Project settings** > **Teams** > your team. :::image type="content" source="media/open-project-settings-teams-cloud.png" alt-text="Screenshot of sequence to open a team."::: -::: moniker-end - ## Add users to a team Tools like capacity planning, team alerts, and dashboard widgets operate within the scope of a team. They automatically access the user information of team members to facilitate planning tasks or issue alerts. @@ -76,29 +73,30 @@ After project administrators add the project's area and iteration paths using [S Settings include making the following associations for each team: - **Select team area paths** - Can select the default area path(s) associated with the team. These settings affect many Agile tools available to the team. + Can select the default area paths associated with the team. These settings affect many Agile tools available to the team. - **Select team iteration paths or sprints** - Can select the default area path(s) associated with the team. These settings affect many Agile tools available to the team. + Can select the default area paths associated with the team. These settings affect many Agile tools available to the team. For more information, see [Define area paths and assign to a team](set-area-paths.md) and [Define iteration paths and configure team iterations](set-iteration-paths-sprints.md). - + ## Configure team backlogs, boards, and general settings As a team administrator, you have the flexibility to customize your team's workflow to suit your needs. One way to do so is by choosing which backlog levels are active for your team. For instance, a feature team might only want to display the product backlog, while a management team might prefer to show the feature and epic backlogs only. Also, you can choose how to treat bugs within your workflow, either as user stories and requirements or as tasks. -Another way to customize your team's workflow is by selecting non-working days for the team. By doing so, sprint planning and tracking tools can automatically take these days off into account when calculating capacity and sprint burndown. +Another way to customize your team's workflow is by selecting nonworking days for the team. By doing so, sprint planning and tracking tools can automatically take these days off into account when calculating capacity and sprint burndown. -Most of these team settings can be easily configured from the common configuration dialog, providing a convenient way to manage your team's workflow in one central location. +Most of these team settings can be easily configured from the common configuration dialog, providing a convenient way to manage your team's workflow in one central location. You can also [set team automation rules to update work items when child item states change](../../boards/work-items/automate-work-item-state-transitions.md). [!INCLUDE [temp](../../boards/includes/setup-backlogs-boards.md)] ::: moniker range=">= azure-devops-2022" 1. Check that you selected the correct project, and then choose **Boards** > **Boards**, and select the correct team from the team selector dropdown menu. For more information, see [Use breadcrumbs and selectors to navigate and open artifacts](../../project/navigation/use-breadcrumbs-selectors.md). - :::image type="content" source="media/open-kanban-board-cloud.png" alt-text="Screenshot of steps to open the kanban board."::: + + :::image type="content" source="media/open-kanban-board-cloud.png" alt-text="Screenshot of steps to open the board."::: 2. Choose **Team settings** :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: to configure the board and set general team settings. @@ -110,14 +108,14 @@ Most of these team settings can be easily configured from the common configurati ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops-2022" +::: moniker range=" **Boards**, and then (3) select the correct team from the team selector menu. > [!div class="mx-imgBorder"] - > ![Open Kanban board, versions Azure DevOps Server 2019 and on.](../../boards/boards/media/quickstart/open-kanban-board-agile.png) + > ![Open board, versions Azure DevOps Server 2019 and on.](../../boards/boards/media/quickstart/open-kanban-board-agile.png) -2. Make sure that you select the team backlog or board that you want to configure using the team selector. To learn more, see [Use breadcrumbs and selectors to navigate and open artifacts](../../project/navigation/use-breadcrumbs-selectors.md). +2. Make sure that you select the team backlog or board that you want to configure using the team selector. For more information, see [Use breadcrumbs and selectors to navigate and open artifacts](../../project/navigation/use-breadcrumbs-selectors.md). 3. Choose the product or portfolio backlog from the board-selection menu. > [!div class="mx-imgBorder"] @@ -135,126 +133,50 @@ Most of these team settings can be easily configured from the common configurati ::: moniker-end -::: moniker range="tfs-2018" - -1. Make sure that you select the team from the project/team selector. You can switch your team focus to one that you've recently viewed from the project/team selector. If you don't see the team or project you want, choose **Browse…** or choose **Azure DevOps** :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: to [access the **Projects** page](../../project/navigation/work-across-projects.md). - - ![Choose another team from the project menu](../../media/work-web-portal-ts-switch-team-focus.png) - -2. Open **Work** > **Backlogs** > **Board**. - - > [!div class="mx-imgBorder"] - >![Open Kanban board, versions TFS 2017-2018.](../../boards/boards/media/kanban-basics-intro.png) - -3. Choose the board you want to configure and then choose **Team settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: to configure the board and set general team settings. - - For example, from the Kanban board ... - - > [!div class="mx-imgBorder"] - > ![Kanban board, open common configuration settings, versions TFS 2017-2018.](media/configure-team/open-settings-vsts-horz.png) - -4. Choose a tab under **Cards** or **Board** to configure the cards and Kanban board columns and swimlanes. - - > [!div class="mx-imgBorder"] - > ![Common configuration dialog team settings]../.../boards/boards/media/customize-cards/common-config-141.png) - -::: moniker-end +Team administrators have complete control over customizing their team's boards for both the product and portfolio backlogs. To set up a board, you can define the columns and work-in-progress (WIP) limits through the common configuration dialog. For more information, see [Board overview](../../boards/boards/kanban-overview.md) and [Board quickstart](../../boards/boards/kanban-quickstart.md). -Team administrators have complete control over customizing their team's Kanban boards for both the product and portfolio backlogs. To set up a Kanban board, you can define the columns and work-in-progress (WIP) limits through the common configuration dialog. For more information, see [Kanban overview](../../boards/boards/kanban-overview.md) and [Kanban quickstart](../../boards/boards/kanban-quickstart.md). +For detailed information on each configuration option, see the following articles: -For detailed information on each configuration option, you can explore the following articles: - ---- -:::row::: - :::column span="1"::: - **General** - - [Backlogs](select-backlog-navigation-levels.md) - - [Working days](set-working-days.md) - - [Working with bugs](show-bugs-on-backlog.md) - **Cards** - - [Add fields](../../boards/boards/customize-cards.md) - - [Define styles](../../boards/boards/customize-cards.md#define-style-rules-to-highlight-cards) - - [Add tag colors](../../boards/boards/customize-cards.md#assign-a-color-to-a-tag) - - [Enable annotations](../../boards/boards/customize-cards.md#enable-annotations) - - [Configure inline tests](../../boards/boards/customize-cards.md#configure-inline-tests) - :::column-end::: - :::column span="1"::: - **Boards** - ::: moniker range=">= azure-devops-2019" - - [Add columns](../../boards/boards/add-columns.md) - - [Split columns](../../boards/boards/split-columns.md) - - [WIP limits](../../boards/boards/wip-limits.md) - - [Definition of Done](../../boards/boards/add-columns.md#definition-of-done) - - [Add swimlanes](../../boards/boards/expedite-work.md) - - [Card reordering](../../boards/boards/customize-cards.md#reorder-cards) - - [Configure status badges](../../boards/github/configure-status-badges.md) - ::: moniker-end - ::: moniker range="tfs-2018" - - [Add columns](../../boards/boards/add-columns.md) - - [Split columns](../../boards/boards/split-columns.md) - - [WIP limits](../../boards/boards/wip-limits.md) - - [Definition of Done](../../boards/boards/add-columns.md#definition-of-done) - - [Add swimlanes](../../boards/boards/expedite-work.md) - - [Reorder cards](../../boards/boards/customize-cards.md#reorder-cards) - ::: moniker-end - **Chart** - - [Configure cumulative flow chart](../../report/dashboards/cumulative-flow.md) - :::column-end::: -:::row-end::: ---- +|Category |Articles | +|---------|---------| +|General |- [Backlogs](select-backlog-navigation-levels.md)
      - [Working with bugs](show-bugs-on-backlog.md) | +|Cards | - [Add fields](../../boards/boards/customize-cards.md)
      - [Define styles](../../boards/boards/customize-cards.md#define-style-rules-to-highlight-cards)
      - [Add tag colors](../../boards/boards/customize-cards.md)
      - [Enable annotations](../../boards/boards/customize-cards.md)
      - [Configure inline tests](../../boards/boards/customize-cards.md#configure-inline-tests) | +|Chart | - [Configure cumulative flow chart](../../report/dashboards/cumulative-flow.md) | +|Boards | - [Add columns](../../boards/boards/add-columns.md)
      - [Split columns](../../boards/boards/split-columns.md)
      - [WIP limits](../../boards/boards/wip-limits.md)
      - [Definition of Done](../../boards/boards/add-columns.md#definition-of-done)
      - [Add swimlanes](../../boards/boards/expedite-work.md)
      - [Card reordering](../../boards/boards/customize-cards.md#reorder-cards)
      - [Configure status badges](../../boards/github/configure-status-badges.md) | ## Configure sprint taskboards ::: moniker range=">= azure-devops-2020" -Similar to Kanban boards, you can customize each sprint taskboard to support information-rich color-coded cards and columns. For more information, see [Customize sprint taskboards](../../boards/sprints/customize-taskboard.md). - -::: moniker-end - -::: moniker range="< azure-devops-2020" - -Similar to Kanban boards, each sprint taskboard can be customized to support information-rich, color-coded cards. For more information, see [Customize sprint taskboards](../../boards/sprints/customize-taskboard.md). +Similar to boards, you can customize each sprint Taskboard to support information-rich color-coded cards and columns. For more information, see [Customize sprint taskboards](../../boards/sprints/customize-taskboard.md). ::: moniker-end :::image type="content" source="media/configure-sprint-taskboard.png" alt-text="Screenshot of taskboard selection."::: - + ## Add and manage team dashboards -::: moniker range=">= azure-devops-2019" By default, all team members can add and edit team dashboards. In addition, team administrators can manage permissions for team dashboards. For more information, see [Add and manage dashboards](../../report/dashboards/dashboard-permissions.md#set-permissions). -::: moniker-end - -::: moniker range="tfs-2018" -Team administrators can add, configure, and manage permissions for team dashboards. For more information, see [Add and manage dashboards](../../report/dashboards/dashboard-permissions.md#set-permissions). -::: moniker-end :::image type="content" source="media/manage-team-dashboards.png" alt-text="Screenshot of dashboard button surrounded by red square."::: - + ## Update team name, description, and image ::: moniker range=">= azure-devops-2020" -Team settings also include the team name, description, and team profile image. To add a team picture, select the image icon. The maximum file size is 2.5 MB. - +Team settings also include the team name, description, and team profile image. To add a team picture, select the image icon. The maximum file size is 2.5 MB and 2560 x 1,024 px, and then we resize to 200 x 200. ![Screenshot to Update team profile picture.](media/team-defaults/update-team-profile-pic-preview.png) ::: moniker-end -::: moniker range="<= azure-devops-2019" - -Team settings also include the team name, description, and team profile image. To add a team picture. Open the Team Profile and choose the picture icon. The maximum file size is 4 MB. - -::: moniker-end - ## Manage notifications -Team administrators have the ability to add and edit alerts, allowing the team to receive email notifications as changes occur to work items, code reviews, source control files, and builds. Various alerts are pre-defined for each team. For more information, see [Manage team alerts](../../organizations/notifications/manage-team-group-global-organization-notifications.md). +Team administrators have the ability to add and edit alerts, allowing the team to receive email notifications as changes occur to work items, code reviews, source control files, and builds. Various alerts are predefined for each team. For more information, see [Manage team alerts](../../organizations/notifications/manage-team-group-global-organization-notifications.md). :::image type="content" source="media/manage-notifications.png" alt-text="Screenshot of highlighted Notifications button."::: @@ -264,3 +186,4 @@ Team administrators have the ability to add and edit alerts, allowing the team t - [About teams and Agile tools](about-teams-and-settings.md) - [Add teams](add-teams.md) - [Add a team administrator](add-team-administrator.md) +- [Automate work item state transitions](../../boards/work-items/automate-work-item-state-transitions.md) diff --git a/docs/organizations/settings/media/about/organization-settings-options-cloud.png b/docs/organizations/settings/media/about/organization-settings-options-cloud.png index 6bb6c62b22f..bb1f34af4f8 100644 Binary files a/docs/organizations/settings/media/about/organization-settings-options-cloud.png and b/docs/organizations/settings/media/about/organization-settings-options-cloud.png differ diff --git a/docs/organizations/settings/media/about/organization-settings-services.png b/docs/organizations/settings/media/about/organization-settings-services.png deleted file mode 100644 index 42e00457d7d..00000000000 Binary files a/docs/organizations/settings/media/about/organization-settings-services.png and /dev/null differ diff --git a/docs/organizations/settings/media/about/project-settings-new-nav.png b/docs/organizations/settings/media/about/project-settings-new-nav.png index 894a3e636db..9d2da78ba1f 100644 Binary files a/docs/organizations/settings/media/about/project-settings-new-nav.png and b/docs/organizations/settings/media/about/project-settings-new-nav.png differ diff --git a/docs/organizations/settings/media/add-team-member.png b/docs/organizations/settings/media/add-team-member.png index 75d63158033..845a0ef15d0 100644 Binary files a/docs/organizations/settings/media/add-team-member.png and b/docs/organizations/settings/media/add-team-member.png differ diff --git a/docs/organizations/settings/media/add-team/add-account-as-team-admin.png b/docs/organizations/settings/media/add-team/add-account-as-team-admin.png deleted file mode 100644 index 2509cc40c2c..00000000000 Binary files a/docs/organizations/settings/media/add-team/add-account-as-team-admin.png and /dev/null differ diff --git a/docs/organizations/settings/media/add-team/team-admin-dialog.png b/docs/organizations/settings/media/add-team/team-admin-dialog.png deleted file mode 100644 index e55a5f13127..00000000000 Binary files a/docs/organizations/settings/media/add-team/team-admin-dialog.png and /dev/null differ diff --git a/docs/organizations/settings/media/agile-tools/agile-tools-team-assets.png b/docs/organizations/settings/media/agile-tools/agile-tools-team-assets.png index 53a355f19aa..35c26065d66 100644 Binary files a/docs/organizations/settings/media/agile-tools/agile-tools-team-assets.png and b/docs/organizations/settings/media/agile-tools/agile-tools-team-assets.png differ diff --git a/docs/organizations/settings/media/areas/new-area-path.png b/docs/organizations/settings/media/areas/new-area-path.png new file mode 100644 index 00000000000..12622680e7a Binary files /dev/null and b/docs/organizations/settings/media/areas/new-area-path.png differ diff --git a/docs/organizations/settings/media/areas/new-area-preview.png b/docs/organizations/settings/media/areas/new-area-preview.png index 439afc628de..80764418202 100644 Binary files a/docs/organizations/settings/media/areas/new-area-preview.png and b/docs/organizations/settings/media/areas/new-area-preview.png differ diff --git a/docs/organizations/settings/media/banners/open-banner-extension-cloud.png b/docs/organizations/settings/media/banners/open-banner-extension-cloud.png index 5d63f572f63..8b8aa1fb4f8 100644 Binary files a/docs/organizations/settings/media/banners/open-banner-extension-cloud.png and b/docs/organizations/settings/media/banners/open-banner-extension-cloud.png differ diff --git a/docs/organizations/settings/media/configure-team/open-board-settings.png b/docs/organizations/settings/media/configure-team/open-board-settings.png index 46b60009503..2bf6af05a3a 100644 Binary files a/docs/organizations/settings/media/configure-team/open-board-settings.png and b/docs/organizations/settings/media/configure-team/open-board-settings.png differ diff --git a/docs/organizations/settings/media/entra-profile-preview.png b/docs/organizations/settings/media/entra-profile-preview.png new file mode 100644 index 00000000000..c206e4410d3 Binary files /dev/null and b/docs/organizations/settings/media/entra-profile-preview.png differ diff --git a/docs/organizations/settings/media/locale-user-settings-2019.png b/docs/organizations/settings/media/locale-user-settings-2019.png index 295c0fd2604..ad99e6e6d45 100644 Binary files a/docs/organizations/settings/media/locale-user-settings-2019.png and b/docs/organizations/settings/media/locale-user-settings-2019.png differ diff --git a/docs/organizations/settings/media/manage-dashboards.png b/docs/organizations/settings/media/manage-dashboards.png deleted file mode 100644 index 4b1c3156d2f..00000000000 Binary files a/docs/organizations/settings/media/manage-dashboards.png and /dev/null differ diff --git a/docs/organizations/settings/media/manage-other-team-settings.png b/docs/organizations/settings/media/manage-other-team-settings.png deleted file mode 100644 index 37173d890f1..00000000000 Binary files a/docs/organizations/settings/media/manage-other-team-settings.png and /dev/null differ diff --git a/docs/organizations/settings/media/manage-team-profile.png b/docs/organizations/settings/media/manage-team-profile.png deleted file mode 100644 index cfe89abb85b..00000000000 Binary files a/docs/organizations/settings/media/manage-team-profile.png and /dev/null differ diff --git a/docs/organizations/settings/media/open-profile-user-settings.png b/docs/organizations/settings/media/open-profile-user-settings.png index a40a4a69771..1c25e59422f 100644 Binary files a/docs/organizations/settings/media/open-profile-user-settings.png and b/docs/organizations/settings/media/open-profile-user-settings.png differ diff --git a/docs/organizations/settings/media/profile-settings-authorizations.png b/docs/organizations/settings/media/profile-settings-authorizations.png index e88c6cfc734..73ea331c3aa 100644 Binary files a/docs/organizations/settings/media/profile-settings-authorizations.png and b/docs/organizations/settings/media/profile-settings-authorizations.png differ diff --git a/docs/organizations/settings/media/revoke-authorized-app.png b/docs/organizations/settings/media/revoke-authorized-app.png new file mode 100644 index 00000000000..9daf419f430 Binary files /dev/null and b/docs/organizations/settings/media/revoke-authorized-app.png differ diff --git a/docs/organizations/settings/media/select-directory-and-switch.png b/docs/organizations/settings/media/select-directory-and-switch.png deleted file mode 100644 index 2a504f016f8..00000000000 Binary files a/docs/organizations/settings/media/select-directory-and-switch.png and /dev/null differ diff --git a/docs/organizations/settings/media/select-nav-backlog-levels-config-ts.png b/docs/organizations/settings/media/select-nav-backlog-levels-config-ts.png index 20a6c5f0db0..7adbd6c933e 100644 Binary files a/docs/organizations/settings/media/select-nav-backlog-levels-config-ts.png and b/docs/organizations/settings/media/select-nav-backlog-levels-config-ts.png differ diff --git a/docs/organizations/settings/media/shared/open-project-settings-permissions-preview.png b/docs/organizations/settings/media/shared/open-project-settings-permissions-preview.png index 34fce1cba43..2ecfd46ff06 100644 Binary files a/docs/organizations/settings/media/shared/open-project-settings-permissions-preview.png and b/docs/organizations/settings/media/shared/open-project-settings-permissions-preview.png differ diff --git a/docs/organizations/settings/media/team-defaults/open-areas-fabrikam-team-preview.png b/docs/organizations/settings/media/team-defaults/open-areas-fabrikam-team-preview.png index df77c2e7482..dc8ec15f5e7 100644 Binary files a/docs/organizations/settings/media/team-defaults/open-areas-fabrikam-team-preview.png and b/docs/organizations/settings/media/team-defaults/open-areas-fabrikam-team-preview.png differ diff --git a/docs/organizations/settings/media/team-defaults/open-team-profile-choose-team-settings.png b/docs/organizations/settings/media/team-defaults/open-team-profile-choose-team-settings.png index 0ee74e3587a..5afb1f0c713 100644 Binary files a/docs/organizations/settings/media/team-defaults/open-team-profile-choose-team-settings.png and b/docs/organizations/settings/media/team-defaults/open-team-profile-choose-team-settings.png differ diff --git a/docs/organizations/settings/media/team-defaults/team-profile-choose-iterations-and-areas-preview.png b/docs/organizations/settings/media/team-defaults/team-profile-choose-iterations-and-areas-preview.png deleted file mode 100644 index c53399cefaf..00000000000 Binary files a/docs/organizations/settings/media/team-defaults/team-profile-choose-iterations-and-areas-preview.png and /dev/null differ diff --git a/docs/organizations/settings/media/turn-off-entra-profile-information.png b/docs/organizations/settings/media/turn-off-entra-profile-information.png new file mode 100644 index 00000000000..263291a15fc Binary files /dev/null and b/docs/organizations/settings/media/turn-off-entra-profile-information.png differ diff --git a/docs/organizations/settings/media/working-with-bugs-navigation.png b/docs/organizations/settings/media/working-with-bugs-navigation.png index 70996be81cf..af0141579df 100644 Binary files a/docs/organizations/settings/media/working-with-bugs-navigation.png and b/docs/organizations/settings/media/working-with-bugs-navigation.png differ diff --git a/docs/organizations/settings/naming-restrictions.md b/docs/organizations/settings/naming-restrictions.md index c4c7befecb4..a7af9c750df 100644 --- a/docs/organizations/settings/naming-restrictions.md +++ b/docs/organizations/settings/naming-restrictions.md @@ -1,15 +1,14 @@ --- title: Restrictions and conventions for naming objects titleSuffix: Azure DevOps -ms.custom: seodec18 -description: Requirements for consistency in labeling objects like organizations, projects, tags, templates, and more, by length, uniqueness, and special characters. +description: Requirements for consistency in labeling objects like organizations, projects, tags, templates, and more, by length, uniqueness, and special characters. ms.subservice: azure-devops-settings ms.topic: conceptual ms.assetid: F4ED2B52-EDE9-4F2B-B3B5-A3FB504D84B9 ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 03/28/2023 +ms.date: 05/30/2024 --- # Naming restrictions and conventions @@ -20,8 +19,12 @@ Most components in Azure DevOps must follow naming restrictions and conventions. Common restrictions include not exceeding the character length for a name, not containing special characters, and maintaining uniqueness of names within an object set. -> [!NOTE] -> For limits on the number of items you can define, see [Work tracking, process, and project limits](work/object-limits.md). +> [!IMPORTANT] +> When using the API, rather than user interface (UI), the API allows you to directly specify a name, which includes characters that might be restricted in the UI. +> +> **Best practices:** +> - Follow the UI restrictions to maintain consistency and prevent unintended issues. +> - Validate names programmatically and handle any special characters appropriately. @@ -31,7 +34,10 @@ The length restrictions in this article get measured by the number of Unicode ch As with other operating system files, ASCII control characters (ASCII 1-31) and surrogate combinations are also not allowed. For general information about the operating system restrictions applied to file names, see [Naming Files, Paths, and Namespaces](/windows/win32/fileio/naming-a-file). - +> [!NOTE] +> - For limits on the number of items you can define, see [Work tracking, process, and project limits](work/object-limits.md). + + ### System reserved names @@ -60,12 +66,12 @@ Universal packages must conform to the following restrictions. ## Azure Boards - - + + You use work items to capture information to plan and track your software development projects. With work items, you can describe the work to be done, assign work, track status, and coordinate efforts within your team. Different types of work items—such as user stories, tasks, bugs, and issues—track different types of information. For more information, see [Azure Boards documentation](../../boards/index.yml). -All work item tracking objects are associated with one or more names. Most have friendly display names, except work item types and global lists, which are associated with reference names. A friendly name is a unique, user-visible identifier for a field. Using friendly names ensures consistency across projects and work item types in a project collection. The system uses the reference name internally and you can't change it after it's defined. +All work item tracking objects are associated with one or more names. Most have friendly display names, except work item types and global lists, which are associated with reference names. A friendly name is a unique, user-visible identifier for a field. Using friendly names ensures consistency across projects and work item types in a project collection. The system uses the reference name internally and you can't change it once defined. There are restrictions on several elements that are associated with work items, including reference and friendly names, field names, and attachment size. @@ -92,42 +98,42 @@ Files attached to work items must conform to the following restrictions. ::: moniker range="< azure-devops" |Restriction type |Restriction | |---------|---------| -|File size | Must not exceed the maximum size:
      - Default maximum size: 4,096 kilobytes.
      - Absolute maximum size: 2 gigabytes. For more information, see [Change the maximum attachment size for work items](/previous-versions/azure/devops/reference/xml/change-maximum-attachment-size-work-items). | +|File size | Must not exceed the maximum size:
      - Default maximum size: 4,096 kilobytes.
      - Absolute maximum size: 2 gigabytes. For more information, see [Change the maximum attachment size for work items](/previous-versions/azure/devops/reference/xml/change-maximum-attachment-size-work-items). | ::: moniker-end - + ### Board column and swimlane names -Your [Kanban board](../../boards/boards/kanban-overview.md) turns your backlog into an interactive signboard, providing a visual flow of work. As work progresses from idea to completion, you update the items on the board. Each column represents a work stage, and each card represents a user story (blue cards) or a bug (red cards) at that stage of work. +Your [board](../../boards/boards/kanban-overview.md) turns your backlog into an interactive signboard, providing a visual flow of work. As work progresses from idea to completion, you update the items on the board. Each column represents a work stage, and each card represents a user story (blue cards) or a bug (red cards) at that stage of work. -Customize your Kanban boards by adding, removing, or renaming [columns](../../boards/boards/add-columns.md) and [swimlanes](../../boards/boards/expedite-work.md). Columns support the flow of work across the board. Swimlanes allow you to manage different classes of work as horizontal lanes on the board. +Customize your board by adding, removing, or renaming [columns](../../boards/boards/add-columns.md) and [swimlanes](../../boards/boards/expedite-work.md). Columns support the flow of work across the board. Swimlanes allow you to manage different classes of work as horizontal lanes on the board. Column and swimlane names must conform to the following restrictions. |Restriction type |Restriction | |---------|---------| |Length | Must not contain more than 256 Unicode characters. | -|Uniqueness |- Column names must not be the same as any other column name on the Kanban board.
      - Swimlane names must not be the same as any other swimlane name on the Kanban board. | +|Uniqueness |- Column names must not be the same as any other column name on the board.
      - Swimlane names must not be the same as any other swimlane name on the board. | |Special characters | Must not contain any Unicode control characters or surrogate characters. | ### Field names -Each work item type contains one or more work item fields. These fields define the information stored for work items based on the work item type. Each work item field has an associated field reference name. The field reference name uniquely identifies each field and can't be changed after it's assigned. For more information about out-of-box work item fields, see [Work item field index](../../boards/work-items/guidance/work-item-field.md). +Each work item type contains one or more work item fields. These fields define the information stored for work items based on the work item type. Each work item field has an associated field reference name. The field reference name uniquely identifies each field and can't be changed once assigned. For more information about out-of-box work item fields, see [Work item field index](../../boards/work-items/guidance/work-item-field.md). Work item field names must conform to the following restrictions. |Restriction type |Restriction | |-----------------|------------| |Length | Must not contain more than 128 Unicode characters. | -|Uniqueness|- Field names must contain at least one alphabetic character.
      - Must not contain any one of the following characters: `.,;':~\/\*|?"&%$!+=()[]{}<>-`.
      - Must not contain leading or trailing spaces.
      - Must not contain two or more consecutive spaces. | +|Uniqueness|- Field names must contain at least one alphabetic character.
      - Must not contain any one of the following characters: `. , ; ' : ~ \ / \ * ? " & % $ ! + = () [] {} <> - |`.
      - Must not contain leading or trailing spaces.
      - Must not contain two or more consecutive spaces. | |Special characters | Must be unique within the organization or project collection. Work item field names are scoped to the project collection. If you rename a field name, you change it for all work items and WITs defined within all projects in the collection. | #### Field reference names and portability -The work item type definition language includes the concept of a *field reference name*. Field reference names can help you to port definitions between Team Foundation project collections and also to allow third-party integrations to find and refer to specific fields. These names are globally unique, just as a namespace in the .NET Framework application is globally unique. +The work item type definition language includes the concept of a *field reference name*. Field reference names can help you to port definitions between Team Foundation project collections and also to allow non-Microsoft integrations to find and refer to specific fields. These names are globally unique, just as a namespace in the .NET Framework application is globally unique. The **System** namespace is used only to define all core system fields that are mandatory for Team Foundation system functions. You can't create your own System.X field because it might impede functionality. @@ -155,7 +161,7 @@ The following examples show valid field reference names, in various namespaces. The system displays help text at run time to help users know what to enter into the field. Help text is scoped to a specific work item type in a specific project. -For the Inheritance process, you specify help text for a field through the **Edit field** dialog, **Definition** tab, **Description**. See [Add a custom field to a work item type](work/add-custom-field.md). For the On-premises XML process, you specify help text by using the `HELPTEXT` element. See [Add or modify a field to track work](../../reference/add-modify-field.md#add-rules-to-a-field). +For the Inheritance process, you specify help text for a field through the **Edit field** dialog, **Definition** tab, **Description**. See [Add a custom field to a work item type](work/add-custom-field.md). For the On-premises XML process, you specify help text by using the `HELPTEXT` element. See [Add or modify a field for work tracking](../../reference/add-modify-field.md#add-rules-to-a-field). Help text that you add must conform to the following restrictions. @@ -165,7 +171,7 @@ Help text that you add must conform to the following restrictions. ### Global lists -A global list is a set of list item values that you can use globally across all project collections within an instance of an on-premises Azure DevOps Server. As you define work item types, you may find that some work item fields share the same set of allowed or suggested values. Global lists enable you to define these values one time and share them across multiple work item types and projects. For details, see [Define global lists](/previous-versions/azure/devops/reference/xml/define-global-lists). +A global list is a set of list item values that you can use globally across all project collections within an instance of an on-premises Azure DevOps Server. As you define work item types, you might find that some work item fields share the same set of allowed or suggested values. Global lists enable you to define these values one time and share them across multiple work item types and projects. For details, see [Define global lists](/previous-versions/azure/devops/reference/xml/define-global-lists). A global list, defined using the `GLOBALLIST` element contains one or more list items, specified using the `LISTITEM` element. @@ -216,15 +222,15 @@ Azure Pipeline definitions must conform to the following restrictions. |Restriction type |Restriction | |---------|---------| -|Job name |- Must only contain alphanumeric characters and `'_'`.
      - Must not start with a number.
      - Must have a unique name.
      - Must not contain keywords, for example: "deployment". | -|Stage name | - Must only contain alphanumeric characters and `'_'`.
      - Must not start with a number.
      - Must not contain keywords, for example: "deployment". | +|Job name |- Must only contain alphanumeric characters and `'_'`.
      - Must not start with a number.
      - Must have a unique name.
      - Must not contain keywords, for example: "deployment." | +|Stage name | - Must only contain alphanumeric characters and `'_'`.
      - Must not start with a number.
      - Must not contain keywords, for example: "deployment." | |Expressions | Must start with `a-Z` or `_AND`, followed by `a-Z`, `0-9`, or `_`. | For more information, see [Azure Pipelines documentation](../../pipelines/index.yml). ## Azure Repos (Git) -Each Azure DevOps project can contain multiple Git repositories. The names you assign to Git repositories must conform to the following restrictions. To learn more, see [Azure Repos Git documentation](../../repos/git/index.yml).For more information on naming restrictions for other Git items such as branches and tags, see [git check-ref-format](https://git-scm.com/docs/git-check-ref-format). +Each Azure DevOps project can contain multiple Git repositories. The names you assign to Git repositories must conform to the following restrictions. For more information, see [Azure Repos Git documentation](../../repos/git/index.yml). For more information on naming restrictions for other Git items such as branches and tags, see [git check-ref-format](https://git-scm.com/docs/git-check-ref-format). > [!IMPORTANT] > Although you can include spaces within repo names, we don't recommend that you do so. @@ -233,13 +239,13 @@ Each Azure DevOps project can contain multiple Git repositories. The names you a |---------|---------| |Length | Must not contain more than 64 Unicode characters. | |Uniqueness | Must not be identical to any other Git repo name in the project. | -|Special characters | - Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `\ / : * ? " < > | ; # $ * { } , + = [ ]`.
      - Must not start with an underscore `_`.
      - Must not start or end with a period `.`.
      - Must not be a [system reserved name](#reserved). | +|Special characters | - Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `\ / : * ? " < > ; # $ * { } , + = [ ] |`.
      - Must not start with an underscore `_`.
      - Must not start or end with a period `.`.
      - Must not be a [system reserved name](#reserved). | ## Azure Repos (TFVC) -Team Foundation version control (TFVC) provides a central repository for files and the commands that are required to manage those files across a team. It also provides customizable check-in policies, branching, merging, shelving, and many other features. To learn more, see [Azure Repos TFVC documentation](../../repos/tfvc/index.yml) +Team Foundation version control (TFVC) provides a central repository for files and the commands that are required to manage those files across a team. It also provides customizable check-in policies, branching, merging, shelving, and many other features. For more information, see [Azure Repos TFVC documentation](../../repos/tfvc/index.yml) Version control paths must conform to the following restrictions. See also [Optimize your workspace](../../repos/tfvc/optimize-your-workspace.md). @@ -259,8 +265,8 @@ Files and folders you add to Team Foundation version control must conform to the |Restriction type |Restriction | |---------|---------| -|Files and folders |- Names must not contain the following printable characters: `\ / : * ? " < > | ;`.
      - Folders must not be outside the mapped directory for the active workspace. | -|File names | - Must not begin with a `$`.
      - Must not contain the following printable characters: `\ / : * ? " < > | ;`. | +|Files and folders |- Names must not contain the following printable characters: `\ / : * ? " < > ;`.
      - Folders must not be outside the mapped directory for the active workspace. | +|File names | - Must not begin with a `$`.
      - Must not contain the following printable characters: `\ / : * ? " < > ; |`. | ### TFVC labels @@ -269,7 +275,7 @@ In Team Foundation version control (TFVC), a label is a name applied to a specif |Restriction type |Restriction | |---------|---------| |Length |Must not contain more than 64 Unicode characters. | -|Special characters | - Can't end with a space `( )` or period `.`.
      - Must not contain the following printable characters: `\ / : * ? " < > | ; @`. | +|Special characters | - Can't end with a space `( )` or period `.`.
      - Must not contain the following printable characters: `\ / : * ? " < > ; @ |`. | ### TFVC Shelvesets @@ -281,7 +287,7 @@ Shelveset names must conform to the following restrictions. |Restriction type |Restriction | |---------|---------| |Length |Must not contain more than 64 Unicode characters. | -|Special characters | Must not contain the following printable characters: `\ / : * ? " < > | ;`. | +|Special characters | Must not contain the following printable characters: `\ / : * ? " < > & ;` |. | ### TFVC workspaces @@ -292,7 +298,7 @@ Workspace names must conform to the following restrictions. |Restriction type |Restriction | |---------|---------| |Length |Must not contain more than 64 Unicode characters. | -|Special characters | - Must not end with a space `( )`.
      - Must not contain the following printable characters: `\ / : * ? " < > | ;`. | +|Special characters | - Must not end with a space `( )`.
      - Must not contain the following printable characters: `\ / : * ? " < > ;` |. | ::: moniker range="< azure-devops" @@ -349,7 +355,7 @@ Names you assign to project collections must conform to the following restrictio |Length | Must not contain more than 64 Unicode characters. | |Uniqueness | - Must not be identical to any other collection name in your on-premises deployment.
      - If your deployment includes SharePoint Products or SQL Server Reporting Services, they can't be identical to the name and full path of an existing SharePoint site, report server, or Reporting Services website. | |Reserved names | Must not be a [system reserved name](#reserved). | -|Special characters | - Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `\ / : * ? " < > | ; # $ * { } , + = [ ]`.
      - Must not contain an ellipsis `...` or a double period `..`.
      - Must not start with an underscore `_`.
      - Must not start or end with a period `.`.
      | +|Special characters | - Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `\ / : * ? " < > ; # $ * { } , + = [ ] |`.
      - Must not contain an ellipsis `...` or a double period `..`.
      - Must not start with an underscore `_`.
      - Must not start or end with a period `.`.
      | ::: moniker-end @@ -366,7 +372,7 @@ Names you assign to projects that you create must conform to the following restr |Length | Must not contain more than 64 Unicode characters. | |Uniqueness | Must not be identical to any other name in the project collection, the SharePoint Web application that supports the collection, or the instance of SQL Server Reporting Services that supports the collection. | |Reserves names | - Must not be a [system reserved name](#reserved).
      - Must not be one of the hidden segments used for IIS request filtering like App_Browsers, App_code, App_Data, App_GlobalResources, App_LocalResources, App_Themes, App_WebResources, bin, or web.config. | -| Special characters | - Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `\ / : * ? " < > | ; # $ * { } , + = [ ]`.
      - Must not start with an underscore `_`.
      - Must not start or end with a period `.`. | +| Special characters | - Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `\ / : * ? " ' < > ; # $ * { } , + = [ ] |`.
      - Must not start with an underscore `_`.
      - Must not start or end with a period `.`. | @@ -374,7 +380,7 @@ Names you assign to projects that you create must conform to the following restr With Azure DevOps security groups, you can apply certain rights or permissions to a group of users. -On-premises groups may consist of Active Directory group accounts, Azure DevOps security groups, Windows user accounts, Windows group accounts, or any mixture of these types. For more information, see [Add AD/Azure AD users or groups to a built-in security group](../../organizations/security/add-ad-aad-built-in-security-groups.md). +On-premises groups might consist of Active Directory group accounts, Azure DevOps security groups, Windows user accounts, Windows group accounts, or any mixture of these types. For more information, see [Add Active Directory / Microsoft Entra users or groups to a built-in security group](../../organizations/security/add-ad-aad-built-in-security-groups.md). Security groups must conform to the following restrictions. @@ -383,7 +389,7 @@ Security groups must conform to the following restrictions. |Security group account name length | Must not contain more than 256 Unicode characters. | |Uniqueness | - Project-level group accounts must not match any other group name in the same project.
      - Collection-level group accounts must not match any other name of a group account in the project collection. | |Reserved group names |Must not be named with a $NAMESPACE at either the project or the server level. | -| Special characters |- Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `/ \ [ ] : | < > + = ; ? *`.
      - Must not include nonprintable characters in the ASCII value range of 1-31.
      - Must not end in a period `.`.
      - Must not include commas `,`. | +| Special characters |- Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `/ \ [ ] : < > + = ; ? * |`.
      - Must not include nonprintable characters in the ASCII value range of 1-31.
      - Must not end in a period `.`.
      - Must not include commas `,`. | ::: moniker range="< azure-devops" @@ -393,7 +399,7 @@ Team Foundation Build lets you manage all the aspects of the build process on a ### Build computer -Team Foundation Build is a separate installation from the Azure DevOps Server application tier, data tier, or Visual Studio client. You may choose a separate computer. Otherwise, you can install the build side by side on the client computer or on the servers. +Team Foundation Build is a separate installation from the Azure DevOps Server application tier, data tier, or Visual Studio client. You can choose a separate computer. Otherwise, you can install the build side by side on the client computer or on the servers. Your on-premises build computer must conform to the following restrictions. @@ -443,20 +449,20 @@ Team names must conform to the following restrictions. |Length | Must not contain more than 64 Unicode characters. | |Uniqueness |Must not be identical to any other name in the project. | |Reserved names | Must not be a [system reserved name](#reserved). | -|Special characters | - Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `\ / : * ? " < > | ; # $ * { } , + = [ ]`.
      - Must not contain an ellipsis `...` or a double period `..`.
      - Must not start with an underscore `_`.
      - Must not start or end with a period `.`. | +|Special characters | - Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `\ / : * ? " < > ; # $ * { } , + = [ ] |`.
      - Must not contain an ellipsis `...` or a double period `..`.
      - Must not start with an underscore `_`.
      - Must not start or end with a period `.`. | ## User account names -User accounts identify people added to a project or project collection. User accounts might correspond to entries within Active Directory, Azure Active Directory, Windows server group. +User accounts identify people added to a project or project collection. User accounts might correspond to entries within Active Directory, Microsoft Entra ID, Windows server group. User accounts that you add to an organization or collection must conform to the following restrictions. To add user accounts to a project, see [Add users to a project or team](../../organizations/security/add-users-team-project.md). |Restriction type |Restriction | |---------|---------| -|Account name length | Must not contain more than 256 Unicode characters. | -|Uniqueness | Must not match any other user account added to the project collection. | -|Reserved group names | Must not be named with a $NAMESPACE at either the project or the server level. | -|Special characters | - Must not include the following printable characters: `"/ \ [ ] : | < > + = ; ? *`.
      - Must not include nonprintable characters in the ASCII value range of 1-31.
      - Must not end in a period `.` or a dollar sign `$`.
      - Must not include commas `,`.
      - Must not include the following Unicode categories: LineSeparator, ParagraphSeparator, Control, Format, OtherNotAssigned. | +|Account name length | Must not contain more than 256 Unicode characters. | +|Uniqueness | Must not match any other user account added to the project collection. | +|Reserved group names| Must not be named with a `$NAMESPACE` at either the project or the server level. | +|Special characters | - Must not include the following printable characters: `"/ \ [ ] : < > + = ; ? * |`.
      - Must not include nonprintable characters in the ASCII value range of 1-31.
      - Must not end in a period `.` or a dollar sign `$`.
      - Must not include commas `,`.
      - Must not include the following Unicode categories: LineSeparator, ParagraphSeparator, Control, Format, OtherNotAssigned. | ## Wiki page and file names diff --git a/docs/organizations/settings/rename-remove-team.md b/docs/organizations/settings/rename-remove-team.md index 32755cd2ed9..ecffd184bde 100644 --- a/docs/organizations/settings/rename-remove-team.md +++ b/docs/organizations/settings/rename-remove-team.md @@ -8,29 +8,30 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 11/12/2024 --- # Rename or remove a team [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -As your organization changes, you may need to rename or remove a team. +As your organization evolves, you might need to rename or remove a team to better align with new roles, projects, or organizational structures. -When you rename a team, the new name propagates throughout Azure DevOps. The following team artifacts are automatically renamed: -- Team security group +When you rename a team, the new name automatically propagates throughout Azure DevOps, ensuring consistency and avoiding confusion. The following team artifacts automatically get renamed: +- Team security group - Team backlogs and boards -- Team dashboards - +- Team dashboards + +Automatic renaming maintains access controls, project tracking, and dashboard configurations without manual updates. Removing a team deletes its configurations and reassigns its members to other teams, ensuring workflow continuity and organizational clarity. + > [!TIP] -> Update any queries that reference the old team security group name. +> Update any queries that reference the old team security group name. -When you remove or delete a team, all of its configuration settings get deleted. These settings include team dashboards, backlogs, and boards. Data defined for work items that are assigned to the team are left unchanged. Once deleted, you can't recover the team configurations. +Deleting a team removes all configuration settings, including dashboards, backlogs, and boards. Work item data remains unchanged. Team configurations cannot be recovered after deletion. ## Prerequisites -- To rename a team, you must be a team administrator or a member of the [**Project Administrators** group](../security/(../security/change-project-level-permissions.md) -- To remove or delete a team, you must be a member of the **Project Administrators** group. +[!INCLUDE [prerequisites-project-administrator-only](../../includes/prerequisites-project-administrator-only.md)] ## Rename a team @@ -45,65 +46,37 @@ When you remove or delete a team, all of its configuration settings get deleted. ::: moniker range="azure-devops" -1. From the web portal, choose **Project settings** and open **Teams**. +1. From your project in the web portal, select **Project settings** > **Teams**. ![Screenshot of Open Project settings, and then Teams, new Teams page.](media/shared/open-project-settings-teams-preview.png) + +2. Choose the team you want to rename, and then select **Settings**. -1. Choose the team you want to rename, and then choose **Settings**. - -1. Under **Team Details**, enter a new name for the team. Optionally, add a new description. - - > [!div class="mx-imgBorder"] - > ![Team profile, choose Iterations and areas link, new teams page.](media/rename-remove-team/rename-team.png) +3. Under **Team Details**, enter a new name for the team. Optionally, add a new description. -1. Choose **Save**. +4. **Save** your changes. ::: moniker-end [!INCLUDE [temp](../../includes/note-new-teams-not-supported.md)] -#### [Current page](#tab/current-page) - -::: moniker range=">= azure-devops-2019" +#### [Current page](#tab/current-page) -1. From the web portal, choose **Project settings** and open **Teams**. +1. From your project in the web portal, select **Project settings** > **Teams**. ![Screenshot of Open Project settings, and then Teams, current page.](media/shared/open-project-settings-team-new-nav.png) - -1. Choose the team you want to rename. Under the Team Profile, enter the new name and optionally update the description. Choose **Save** when done. - - > [!div class="mx-imgBorder"] - > ![Create a subteam with its own area path, current page.](media/rename-remove-team/rename-team-prev-ui.png) + +2. Choose the team you want to rename. Under the Team Profile, enter the new name and optionally update the description. **Save** your changes. To configure other team features, see [Manage teams and configure team tools](manage-teams.md). -::: moniker-end - -::: moniker range="tfs-2018" - - - -1. From the web portal, choose **Project settings** :::image type="icon" source="../../media/icons/gear_icon.png" border="false":::. - - ![Open project administration page.](media/add-team/open-admin-context-tfs-2017.png) - -1. Choose the team you want to rename. Under the Team Profile, enter the new name and optionally update the description. Choose **Save** when done. - - > [!div class="mx-imgBorder"] - > ![Create a subteam with its own area path.](media/rename-remove-team/rename-team-prev-ui.png) - -To configure other team features, see [Manage teams and configure team tools](manage-teams.md). - -::: moniker-end - - #### [Azure DevOps CLI](#tab/azure-devops-cli) - + ::: moniker range="azure-devops" -You can rename a team or its description using [Azure DevOps team update](/cli/azure/devops/team#az-devops-team-update). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). +You can rename a team or its description using [Azure DevOps team update](/cli/azure/devops/team#az-devops-team-update). For more information, see [Get started with Azure DevOps CLI](../../cli/index.md). > [!div class="tabbedCodeSnippets"] ```azurecli @@ -119,8 +92,7 @@ az devops team update --team - **description**: Optional. Description to apply to the team. - **name**: Optional. Name to apply to rename the team. - **org**: Optional. URL of organization. You can configure the default organization using `az devops configure -d org=URL`. Required if not configured as default or picked up via git config. -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up via git config. - +- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber." You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up via git config. #### Example @@ -214,17 +186,17 @@ az devops team update --team "Account Management" --name "Organization Managemen ## Set a team as the default -When a project is created, a default team is created based on the project name. - -To change the default, open **Project Settings>Teams**, choose :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More options** next to the team you want as the new default, and select **Set team as project default**. +When a project gets created, a default team also gets created based on the project name. +1. Open **Project settings** > **Teams**. +2. Select :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More options** next to the team you want as the new default, and then select **Set team as project default**. ## Delete a team You can delete any team except the default team. At least one team must be defined for a project. > [!IMPORTANT] -> Deleting a team deletes all team configuration settings, including team dashboards, backlogs, and boards. Data defined for work items assigned to the team are left unchanged. Once deleted, you can't recover the team configurations. +> Deleting a team removes all team configuration settings (dashboards, backlogs, boards). Work item data remains unchanged. Team configurations cannot be recovered once deleted. ::: moniker range="azure-devops" @@ -237,55 +209,41 @@ You can delete any team except the default team. At least one team must be defin ::: moniker range="azure-devops" -1. From the web portal, choose **Project settings** and open **Teams** as shown in the previous section. - -1. Choose the team you want to delete and then scroll down to the Delete Team section. Choose **Delete Team**. +1. From your project in the web portal, select **Project settings** > **Teams** as shown in the previous section. - > [!div class="mx-imgBorder"] - > ![Delete team](media/rename-remove-team/delete-team-operation.png) +2. Select the team you want to delete and then select **Settings**. +3. Scroll down and select **Delete Team**. -1. Choose **Delete** in the confirmation box to complete the delete operation. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Delete team confirmation dialog, new teams page.](media/rename-remove-team/delete-team-confirmation.png) +4. Select **Delete** in the confirmation box to complete the delete operation. + > [!div class="mx-imgBorder"] + > ![Screenshot of Delete team confirmation dialog, new teams page.](media/rename-remove-team/delete-team-confirmation.png) + ::: moniker-end [!INCLUDE [temp](../../includes/note-new-teams-not-supported.md)] #### [Current page](#tab/current-page) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -1. To delete a team, choose **Project Settings > Teams** > **…** for the team you want to delete, and select the **Delete** option. +1. From your project in the web portal, select **Project settings** > **Teams** > **…** for the team you want to delete, and then select **Delete**. > [!div class="mx-imgBorder"] - > ![Project Settings > Teams > Delete team](media/add-team/delete-team-vert.png) + > ![Screenshot of Project Settings > Teams > Delete team sequence of choices.](media/add-team/delete-team-vert.png) > [!IMPORTANT] > Deleting a team deletes all team configuration settings, including team dashboards, backlogs, and boards. Data defined for work items assigned to the team are left unchanged. Once deleted, you can't recover the team configurations. -2. To complete the delete operation, you must enter the name of the WIT as shown. - - ![Delete team confirmation dialog](media/add-team/multiple-teams-delete-team-confirmation-dialog.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -1. To delete a team, choose **Project Settings** > **Work** > **Overview** > **…** for the team you want to delete, and select the **Delete** option. - - ![Web portal, admin context-project level, Delete team](media/add-team/multiple-teams-delete-team.png) - -2. To complete the delete operation, you must enter the name of the WIT as shown. +2. To complete the delete operation, you must enter the name of the work item type as shown in the following example. - ![Delete team confirmation dialog](media/add-team/multiple-teams-delete-team-confirmation-dialog.png) + ![Screenshot of Delete team confirmation dialog.](media/add-team/multiple-teams-delete-team-confirmation-dialog.png) ::: moniker-end #### [Azure DevOps CLI](#tab/azure-devops-cli) - + ::: moniker range="azure-devops" @@ -301,7 +259,7 @@ az devops team delete --id #### Parameters - **id**: Required. The ID of the team to delete. -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". +- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber." - **yes**: Optional. Specify to not prompt for confirmation. #### Example @@ -322,7 +280,7 @@ Are you sure you want to delete this team? (y/n): y ## Related articles - [Add teams](add-teams.md) -- [About teams and Agile tools](about-teams-and-settings.md) -- [Azure DevOps Teams CLI](/cli/azure/devops/team) -- [Teams (REST API)](/rest/api/azure/devops/core/teams) -- [Work Items (REST API)](/rest/api/azure/devops/wit) +- [Learn about teams and Agile tools](about-teams-and-settings.md) +- [Use the Azure DevOps Teams CLI](/cli/azure/devops/team) +- [Use the Teams REST API](/rest/api/azure/devops/core/teams) +- [Use the Work Items REST API](/rest/api/azure/devops/wit) diff --git a/docs/organizations/settings/scale/toc.yml b/docs/organizations/settings/scale/toc.yml index af8b0969742..2ba484a4e5f 100644 --- a/docs/organizations/settings/scale/toc.yml +++ b/docs/organizations/settings/scale/toc.yml @@ -21,8 +21,6 @@ href: ../select-backlog-navigation-levels.md - name: Show bugs on backlogs & boards href: ../show-bugs-on-backlog.md - - name: Set working days - href: ../set-working-days.md - name: Enterprise teams items: - name: Portfolio management diff --git a/docs/organizations/settings/search-settings.md b/docs/organizations/settings/search-settings.md deleted file mode 100644 index a4793a5f67f..00000000000 --- a/docs/organizations/settings/search-settings.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Search settings, organization, project, and user -titleSuffix: Azure DevOps -description: Learn how to search organization, project, and user settings in Azure DevOps. -ms.subservice: azure-devops-settings -ms.author: chcomley -author: chcomley -ms.topic: how-to -monikerRange: 'azure-devops' -ms.date: 12/17/2020 ---- - -# Search organization settings - -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -The preview feature, **New Settings Search in the organization settings panel**, enables a search box for searching within **Organization Settings**. To enable this feature, see [Manage or enable preview features](../../project/navigation/preview-features.md). - -## Perform a search - -Enter a keyword to search all settings within your organization. For example, here we search on **Notifications**. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Organizational Settings, Search box.](media/search/org-search-settings.png) - -Search results return findings with links to the settings. Settings include Organization, project, and user. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Organizational Settings Search Results.](media/search/organization-settings-search-results.png) - -To navigate to one of the settings listed, choose the card in which it appears. - -## Keywords - -Each setting is tagged with a number of keywords. These keywords capture the level of setting, such as organization, project, or user, as well as other categories. Entering a keyword with any part of a setting label or description should return it within the results. - -## Related articles - -- [About settings](about-settings.md) - - \ No newline at end of file diff --git a/docs/organizations/settings/select-backlog-navigation-levels.md b/docs/organizations/settings/select-backlog-navigation-levels.md index 307ce1a6d08..1142a618248 100644 --- a/docs/organizations/settings/select-backlog-navigation-levels.md +++ b/docs/organizations/settings/select-backlog-navigation-levels.md @@ -1,7 +1,7 @@ --- title: Select backlog navigation levels titleSuffix: Azure DevOps -description: Choose which backlog and portfolio backlogs are active for your team in Azure DevOps. +description: Learn how to choose and configure multiple backlog and portfolio backlog levels for your team in Azure DevOps to suit your workflow. ms.service: azure-devops-boards ms.custom: teams ms.assetid: BB1E56B6-988A-4D0A-AA56-560F2DF681DD @@ -9,26 +9,22 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/24/2023 +ms.date: 10/31/2024 --- -# Select backlog navigation levels for your team +# Select backlog navigation levels [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Each team has the flexibility to choose their preferred backlog levels. Feature teams may focus on their product backlog, while management teams may only display feature and epic backlogs (the default portfolio backlogs). You can configure backlog levels through team settings. +Each team has the flexibility to choose and configure multiple backlog levels according to their needs. Feature teams might focus on their product backlog, while management teams might display both feature and epic backlogs (the default portfolio backlogs). You can add and configure these backlog levels through team settings to suit your team's workflow. -::: moniker range=">= azure-devops-2019" If you need more portfolio backlogs, see the following articles based on the process model you use: - **Inheritance**: [Customize your backlogs or boards for a process](work/customize-process-backlogs-boards.md) -- **On-premises XML**: [Add portfolio backlogs](../../reference/add-portfolio-backlogs.md). +- **On-premises XML**: [Add portfolio backlogs](../../reference/add-portfolio-backlogs.md). For an overview of process models, see [Customize your work tracking experience](../../reference/customize-work.md). -::: moniker-end -::: moniker range="< azure-devops-2019" -If you need more portfolio backlogs, see [Add portfolio backlogs](../../reference/add-portfolio-backlogs.md). -::: moniker-end +## Prerequisites [!INCLUDE [temp](includes/prerequisites-team-settings.md)] @@ -36,51 +32,30 @@ If you need more portfolio backlogs, see [Add portfolio backlogs](../../referenc ## Set your team's preferences for backlog levels -This setting impacts the backlog and board views for all team members. You can modify the setting from either the backlog or board view. In this article, we show you from the board view. - -::: moniker range=">= azure-devops-2019" +This setting affects the backlog and board views for all team members, ensuring a consistent experience across the team. You can modify this setting from either the backlog or board view, depending on your preference. In this article, we show how to adjust the setting from the board view. 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Choose **Boards**, and then open your Kanban board. +2. Select **Boards**, and then open your board. -3. Select **Configure team settings** :::image type="icon" source="../../media/icons/blue-gear.png" border="false":::. +3. Select :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: **Configure team settings**. > [!div class="mx-imgBorder"] - > ![Open board settings for a team, vert nav](media/configure-team/open-board-settings.png) + > ![Screenshot shows Open board settings for a team.](media/configure-team/open-board-settings.png) -4. Choose **Backlogs** and check the boxes of those backlog levels you want your team to manage. +4. Check the boxes of those backlog levels you want your team to manage. - ![Team settings dialog, Backlogs tab](media/select-nav-backlog-levels-config-ts.png) + ![Screenshot shows Team settings dialog, Backlogs tab.](media/select-nav-backlog-levels-config-ts.png) -5. When you're done with your changes, choose **Save and close**. +5. Select **Save**. 6. To see the changes, open or refresh your team's [backlog](../../boards/backlogs/create-your-backlog.md). -::: moniker-end - -::: moniker range="tfs-2018" - -1. [Open your Kanban board](../../boards/boards/kanban-quickstart.md). - -2. Select **Configure team settings** :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: to open the settings dialog. - - > [!div class="mx-imgBorder"] - > ![Open board settings for a team](media/configure-team/open-settings-tfs.png) - -3. Choose **Backlogs** and check the boxes of those backlog levels you want your team to manage. - - ![Team settings dialog, Backlogs tab](media/select-nav-backlog-levels-config-ts.png) - -4. When you're done with your changes, choose **Save**. - -5. To see the changes, open or refresh your team's [backlog](../../boards/backlogs/create-your-backlog.md). - -::: moniker-end + Your customized backlog and board view reflect the selected backlog levels. ## Related articles - [Get started with Agile tools to plan and track work](../../boards/get-started/what-is-azure-boards.md) -- [Backlogs, boards, and plans](../../boards/backlogs/backlogs-boards-plans.md) -- [Create your backlog](../../boards/backlogs/create-your-backlog.md) +- [Understand backlogs, boards, and plans](../../boards/backlogs/backlogs-boards-plans.md) +- [Create your backlog](../../boards/backlogs/create-your-backlog.md) - [Define features and epics](../../boards/backlogs/define-features-epics.md) -- [Organize your backlog](../../boards/backlogs/organize-backlog.md) +- [Organize your backlog](../../boards/backlogs/organize-backlog.md) diff --git a/docs/organizations/settings/set-area-paths.md b/docs/organizations/settings/set-area-paths.md index 7c90fff846b..499b6636280 100644 --- a/docs/organizations/settings/set-area-paths.md +++ b/docs/organizations/settings/set-area-paths.md @@ -9,15 +9,16 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 02/10/2023 +ms.date: 11/14/2024 --- # Define area paths and assign to a team [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +Add area paths to organize teams and group work items by product, feature, or business areas. Assigning area paths to teams ensures that work items under those paths appear on the respective team's backlogs and boards. By default, all work items are assigned to the root area path and appear in the project's default team. -Add area paths to support teams and group work items based on product, feature, or business areas. Once you define area paths at the project level, you assign them to a team under the team configuration. You can also create a hierarchy of area paths to support sub-areas, up to 14 levels deep. +After you define area paths at the project level, assign them to teams within the team configuration. You can also create a hierarchical structure of area paths to support subareas, with up to 14 levels deep. [!INCLUDE [temp](../../boards/includes/list-area-dependent-tools-tasks.md)] @@ -25,110 +26,57 @@ To understand how the system uses area paths, see [About area and iteration path ## Prerequisites - +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To set team area or iteration paths: [Team administrator](add-team-administrator.md) or a member of the [Project Administrators](../security/change-project-level-permissions.md) group. By default, the user who created the project has these permissions.
      - To add an area path under the root node or edit or delete any child node: Member of the [Project Administrators](../security/change-project-level-permissions.md) group.
      - To add, edit, and manage area paths under a node: One or more of the following permissions set to **Allow**:
      - **Create child nodes**
      - **Delete this node**
      - **Edit this node**
      - **View permissions in this node**| -- If you don't have a project yet, [create one now](../projects/create-project.md). -- Ensure you're a member of the **Project Administrators** group to add an area path under the root node or edit or delete any child node. To acquire these permissions, see [Change project-level permissions](../security/change-project-level-permissions.md). -- Have one or more of the following permissions set to **Allow**, to add, edit, and manage area paths under a node: - - **Create child nodes** - - **Delete this node** - - **Edit this node** - - **View permissions in this node** +For more information, see [Set permissions and access for work tracking](../security/set-permissions-access-work-tracking.md#set-permissions-area-path). - By default, the user who created the project has these permissions already set. For more information, see [Set permissions and access for work tracking](../security/set-permissions-access-work-tracking.md#set-permissions-area-path). -- Ensure you're [added as a team administrator](add-team-administrator.md) or are a member of the **Project Administrators** group to set team area paths. - -For naming restrictions on area paths, see [About areas and iterations, Naming restrictions](about-areas-iterations.md#name-restrictions). - - +For naming restrictions on area paths, see [About areas and iterations, Naming restrictions](about-areas-iterations.md#naming-restrictions). ## Get started -Each team has access to a number of Agile tools as described in [About teams and Agile tools](about-teams-and-settings.md). Each tool references the team's default area path(s). Most teams choose one area path and several iteration paths to support their work tracking activities. However, to support other scenarios, it's possible for teams to choose several area paths to appear on their backlogs and boards. +Each team has access to various Agile tools, as described in [About teams and Agile tools](about-teams-and-settings.md). These tools reference the team's default area paths. Most teams use one area path and several iteration paths for work tracking, but teams can also use multiple area paths on their backlogs and boards to support different scenarios. -New projects contain a single, root area that corresponds to the project name. A team is created with the same project name and the root area path is assigned to that team. +New projects include a single root area corresponding to the project name and a default team with the same name assigned to this root area path. -If you're new to managing projects and teams, the most straight forward sequence for configuring your project and teams is as follows: +If you're new to managing projects and teams, follow these steps to configure your project and teams: -1. Determine the number and names of area paths that you want to support to categorize your work. At a minimum, add one area path for each team you define. For more information, review [About areas and iterations](about-areas-iterations.md). -2. Determine the number and names of teams you want to support. For more information, review [About teams and Agile tools](about-teams-and-settings.md). -3. Open **Project settings>Project configuration** and define the area paths to support steps 1 and 2 at the project level. Follow the steps provided later in this article: [Open Project Settings, Project configuration](#open-project-settings) and [Add area paths](#add-areas). -4. Define the teams you need to support step 2. For more information, see [Add a team, move from one default team to several teams](add-teams.md). -5. Open the team configuration and assign the default and additional area path(s) to each team. Follow the steps provided later in this article: [Open team settings](#open-team-settings) and [Set team default area path(s)](#team-area-paths). -6. Assign the area path of work items to an area path you defined. Use [bulk modify](../../boards/backlogs/bulk-modify-work-items.md) to modify several work items at once. +1. **Define area paths**: Determine the number and names of area paths needed to categorize your work. Add at least one area path per team. For more information, see [About areas and iterations](about-areas-iterations.md). +1. **Define teams**: Decide the number and names of teams required. For more information, see [About teams and Agile tools](about-teams-and-settings.md). +1. **Configure area paths**: Go to **Project settings** > **Project configuration** > **Areas** and define the area paths for your project. Follow the steps in [Add area paths](#add-an-area-path). +1. **Create teams**: Create the necessary teams based on step 2. For more information, see [Add a team, move from one default team to several teams](add-teams.md). +1. **Assign area paths to teams**: In the team configuration, assign the default and other area paths to each team. Do the steps in [Set team default area paths](#set-team-area-paths). +1. **Assign area paths to work items**: Assign work items to the defined area paths using [bulk modify](../../boards/backlogs/bulk-modify-work-items.md) to update multiple items at once. > [!NOTE] -> While you can assign the same area path to more than one team, doing so can cause problems if two teams claim ownership over the same set of work items. To learn more, see [About boards and Kanban, Limitations of multi-team Kanban board views](../../boards/boards/kanban-overview.md#limits-multi-team). - +> Assigning the same area path to multiple teams may cause conflicts over work item ownership. For more information, see [Limitations of multi-team board views](../../boards/boards/kanban-overview.md). As needed, you can do the following actions at any time: -- Add additional child nodes +- Add other child nodes - Rename an area path (except the root area path) - Move a child node under another node - Delete a child node - Rename a team - Change the area path assignments made to a team - - - - - -[!INCLUDE [temp](../../includes/version-selector-minimize.md)] - -## Open Project Settings, list project areas - -::: moniker range=">= azure-devops-2019" +## List project areas -Define both areas and iterations for a project from the **Project Settings** > **Boards** > **Project configuration**. - -::: moniker-end - -::: moniker range="tfs-2018" - -Define both areas and iterations from the **Work** pages of the **Project Settings** context. From the user context, open the admin context by choosing **Settings** :::image type="icon" source="../../media/icons/gear-icon.png" border="false":::. - -::: moniker-end +To list project areas, do the following steps: #### [Browser](#tab/browser/) -::: moniker range=">= azure-devops-2019 " - -- From your web portal, choose (1) **Project settings**, choose (2) **Project configuration** and then (3) **Areas**. - - > [!div class="mx-imgBorder"] - > ![Project Settings>Project Configuration](media/areas/open-project-work-areas-settings-vert.png) - -::: moniker-end - - - - -::: moniker range="tfs-2018" - -1. From the web portal for the project, choose **Project settings** :::image type="icon" source="../../media/icons/gear_icon.png" border="false":::. - - > [!div class="mx-imgBorder"] - > ![Open Admin context, project level](media/areas/modify-areas-its-open-admin-context-ts.png) - - If you're currently working from a team context, then hover over **Settings** ![gear icon](../../media/icons/gear_icon.png) and choose **Project settings**. - - > [!div class="mx-imgBorder"] - > ![Open Project Settings, horizontal nav](../../media/settings/open-project-settings-horz.png) - -2. Choose **Work**. - -::: moniker-end +From your web portal, select (1) **Project settings** > (2) **Project configuration** > (3) **Areas**. +> [!div class="mx-imgBorder"] +> ![Screenshot shows selections, Project settings, Project configuration.](media/areas/open-project-work-areas-settings-vert.png) #### [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" -[List project area paths](#list-areas) | [Add a project area path](#add-area) | [List team areas paths](#list-team-area-paths) | [Set team area paths](#set-team-area-paths) | [Rename or move a project area path](#rename-move-project-area-path) | [Remove area path from a team](#remove-area-path-from-team) - - +[List project area paths](#list-project-areas) | [Add a project area path](#add-an-area-path) | [List team areas paths](#list-team-area-paths) | [Set team area paths](#set-team-area-paths) | [Rename or move a project area path](#rename-or-move-an-area-path) | [Remove area path from a team](#remove-an-area-path-from-a-team) You can list the area paths defined for a project using [az boards area project list](/cli/azure/boards/area/project#az-boards-area-project-list). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). @@ -141,10 +89,9 @@ az boards area project list [--depth] #### Parameters -- **depth**: Optional. Depth of child nodes to be listed. Example: --depth 3. When not specified, only the top-level area paths are returned. -- **path**: Optional. Absolute path of an area. `\Area\` must follow after the `\ProjectName`, which distinguishes this path from an iteration path. For example, --path \ProjectName\Area\AreaName. If spaces are used within a node, then enclose in double-quotes, for example, --path "\Fabrikam Fiber\Area\Service Delivery\Performance". When not specified, lists area paths from the root level. -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". - +- **depth**: Optional. Depth of child nodes to be listed. Example: `--depth 3`. When not specified, only the top-level area paths are returned. +- **path**: Optional. Absolute path of an area. `\Area\` must follow after the `\ProjectName`, which distinguishes this path from an iteration path. For example, `--path \ProjectName\Area\AreaName`. If spaces are used within a node, then enclose in double-quotes, for example, `--path "\Fabrikam Fiber\Area\Service Delivery\Performance"`. When not specified, lists area paths from the root level. +- **project**: Optional. Name or ID of the project. Example: `--project "Fabrikam Fiber"`. #### Example @@ -166,42 +113,57 @@ ID Identifier Name Path 55382 4235f40d-753b-49dd-868f-82372065ec83 Shopping Cart \Fabrikam Fiber\Area\Account Management\Shoppin... False 55383 49d34650-6c65-446c-aff6-79edd3a21a75 Customer Profile \Fabrikam Fiber\Area\Account Management\Custome... False ``` - ::: moniker-end [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - -
      -       - +--- -## Add an area path +## Add an area path -Only one area is defined, by default. Add area paths under the root area path for the project, or as a child to another area path. +Only one root area is defined by default. Add new and child area paths under the root area path for the project, or as a child to another area path or team. New area paths are added to the root node by default. > [!div class="mx-imgBorder"] -> ![Areas, defaults defined for project](media/areas/modify-areas-its-areas-ts.png) +> ![Screenshot shows Areas, defaults defined for project.](media/areas/modify-areas-its-areas-ts.png) +You can also add new and child area paths to a team. For more information, see [Set team area paths](#set-team-area-paths). #### [Browser](#tab/browser/) -- To add a child node, highlight the area path and then choose **New child**. Optionally, you can select:::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: for the area path and choose **New child**. +To add a new area path, do the following steps: + +1. Highlight the area path and then choose **New child**. Optionally, you can select:::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: for an area path and choose **New**, or select the **New** menu item at the top of the area list. - Enter a name (255 characters or less) for the node. For additional name restrictions, see [About areas and iterations, Naming restrictions](about-areas-iterations.md#naming-restrictions). +1. Enter a name (255 characters or less) for the node. For more name restrictions, see [About areas and iterations, Naming restrictions](about-areas-iterations.md#naming-restrictions). > [!div class="mx-imgBorder"] - > ![Add a new area path](media/areas/new-area-preview.png) + > ![Add a new area path](media/areas/new-area-path.png) -#### [Azure DevOps CLI](#tab/azure-devops-cli) +1. Select **Save and close** + +All new areas are added as a child node to the root area path. + +To add a child area path, do the following steps: - +1. Highlight the area path and then choose **New child**. Optionally, you can select:::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: for the area path and choose **New child** or select **New child** from the menu at the top of the area list. -::: moniker range="azure-devops" +1. Enter a name (255 characters or less) for the node. For more name restrictions, see [About areas and iterations, Naming restrictions](about-areas-iterations.md#naming-restrictions). + + > [!div class="mx-imgBorder"] + > ![Add a new child area path](media/areas/new-area-preview.png) + +1. Select **Save and close** + +You can also add area paths to a team on the **Team configuration** > **Areas** page. + +#### [Azure DevOps CLI](#tab/azure-devops-cli) + +::: moniker range="azure-devops" You can add area paths to a project using [az boards area project create](/cli/azure/boards/area/project#az-boards-area-project-create). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). +If you specify the `--path` parameter, the new area path is added as a child node to the specified path. If you don't specify the `--path` parameter, the new area path is added as a child node to the root node. + > [!div class="tabbedCodeSnippets"] ```azurecli az boards area project create --name @@ -213,7 +175,7 @@ az boards area project create --name - **name**: Required. Area path name. - **path**: Optional. Absolute path of an area. Example: --path \ProjectName\Area\AreaName. When not specified, adds an area at the root level. -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". +- **project**: Optional. Name or ID of the project. Example: `--project "Fabrikam Fiber"`. #### Example: JSON format @@ -237,7 +199,7 @@ az boards area project create --name Voice --project "Fabrikam Fiber" #### Example: Table format -And, here is the same command with the table output format. +And, here's the same command with the table output format. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -251,47 +213,25 @@ ID Identifier Name Path [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - - - +--- -## Open team settings, list team area paths +## List team area paths You set team defaults from team settings. If you're not a team administrator, [get added as one](add-team-administrator.md). Only team or project administrators can change team settings. - #### [Browser](#tab/browser/) -::: moniker range=">= azure-devops-2019" - 1. Open your project, and then select **Project settings** > **Team configuration** > **Areas**. - ![Project settings, Team configuration page](media/areas/project-settings-team-configuration-preview.png) + ![Screenshot shows Project settings, Team configuration page.](media/areas/project-settings-team-configuration-preview.png) -2. If you need to switch the team context, use the team selector within the breadcrumbs. +1. If you need to switch the team context, use the team selector within the breadcrumbs. > [!div class="mx-imgBorder"] - > ![Team Configuration, Team breadcrumb](media/team-defaults/select-team-context-preview.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -You open team settings from the upper navigation bar. Select the team you want and then choose **Team settings** :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: . For more information about switching your team focus, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md#switch-team-context) - -> [!div class="mx-imgBorder"] -> ![Open team settings](media/team-defaults/open-team-settings-horz.png) - -::: moniker-end - - + > ![Screenshot shows Team Configuration, Team breadcrumb.](media/team-defaults/select-team-context-preview.png) #### [Azure DevOps CLI](#tab/azure-devops-cli) - - ::: moniker range="azure-devops" You can list the area paths defined for a team using [az boards area team list](/cli/azure/boards/area/team#az-boards-area-team-list). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). @@ -305,7 +245,7 @@ az boards area team list --team #### Parameters - **team**: Required. Name or ID of the team. -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". +- **project**: Optional. Name or ID of the project. Example: `--project "Fabrikam Fiber"`. For example, the following command lists the area paths for the Service Delivery team. For other output format options, see [Output formats for Azure CLI commands](/cli/azure/format-output-azure-cli) @@ -321,10 +261,7 @@ Fabrikam Fiber\Service Delivery True True [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - -::: moniker range=">= azure-devops-2019" +--- ## Open team settings from the team profile @@ -335,98 +272,68 @@ You define both areas and iterations from **Project Settings > Team configuratio Here we open the Board for the Fabrikam Fiber team and from there the team profile. > [!div class="mx-imgBorder"] - > ![Work Backlog or Board, choose team profile icon](media/team-defaults/open-team-profile-choose-team-settings.png) + > ![Screenshot shows work backlog or board, choose team profile icon.](media/team-defaults/open-team-profile-choose-team-settings.png) -2. Choose **Iterations and areas**. +1. Choose **Iterations and areas**. > [!div class="mx-imgBorder"] - > ![Team Profile, choose Iterations and area](media/team-defaults/team-profile-choose-iterations-areas.png) + > ![Screenshot shows Team Profile, choose Iterations and area.](media/team-defaults/team-profile-choose-iterations-areas.png) -3. If you need to switch the team context, use the team selector within the breadcrumbs. +1. If you need to switch the team context, use the team selector within the breadcrumbs. > [!div class="mx-imgBorder"] - > ![Team Configuration, Team breadcrumb, TFS 2019](media/team-defaults/select-team-context.png) - -::: moniker-end - - - + > ![Screenshot shows Team Configuration, Team breadcrumb, version 2019.](media/team-defaults/select-team-context.png) -## Set team area path(s) +## Set team area paths All work items that are assigned to a team area path appear on the backlogs and boards for that team. You can select one or more area paths and optionally include their subarea paths. Choose to include subarea paths when you want to support rollup views of work done across several teams or areas. - > [!NOTE] -> Teams can be assigned a maximum of 300 **Area Paths**. To learn more, see [Work tracking, process, and project limits](work/object-limits.md). +> Teams can be assigned a maximum of 300 **Area Paths**. For more information, see [Work tracking, process, and project limits](work/object-limits.md). The default area path determines the default area path assigned to work items that are created from the team context. > [!IMPORTANT] -> Work items that appear on more than one team's Kanban board can yield query results that don't meet your expectations. Because each team can customize the Kanban board [columns](../../boards/boards/add-columns.md) and [swimlanes](../../boards/boards/expedite-work.md), the values assigned to work items which appear on different boards may not be the same. The primary work around for this issue is to maintain single ownership of work items by team area path. +> Work items that appear on more than one team's board can yield query results that don't meet your expectations. Because each team can customize the board [columns](../../boards/boards/add-columns.md) and [swimlanes](../../boards/boards/expedite-work.md), the values assigned to work items which appear on different boards may not be the same. The primary work around for this issue is to maintain single ownership of work items by team area path. - #### [Browser](#tab/browser/) ::: moniker range=">= azure-devops-2020" -1. Open **Areas** for the team context. +You can select existing area paths or create new or child area paths from the team settings. + +1. Select **Project settings** > **Team configuration** > **Areas**. +1. Select the team you want to configure from the drop-down list at the top of the page. Here, we show the Areas for the Fabrikam Fiber team. > [!div class="mx-imgBorder"] - > ![Area page for team](media/team-defaults/open-areas-fabrikam-team-preview.png) + > ![Screenshot shows Area page for team.](media/team-defaults/open-areas-fabrikam-team-preview.png) -2. Choose the area path(s) to be active for each team. +1. Choose one or more area paths to be active for the team. > [!div class="mx-imgBorder"] - > ![Work, Iterations page for team](media/team-defaults/stdefaults-add-area-paths-preview.png) + > ![Screenshot shows Work, Iterations page for team.](media/team-defaults/stdefaults-add-area-paths-preview.png) In this instance, we choose to activate the subarea paths for the project. The management team can now track progress across all teams. - ![Multiple area paths assigned to team](media/team-defaults/stdefaults-set-team-area-paths-team-services-list-preview.png) - -3. When you've finished, refresh the product backlog page for the team, and you'll see those work items assigned to the team. Add area path to the columns shown to see the assignments made to work items. - - ![Backlog view of default team](media/team-defaults/area-path-assigned-to-item.png) - - ![Add area path column to backlog](media/team-defaults/add-a-column-backlog.png) - -::: moniker-end - -::: moniker range="< azure-devops-2020" + ![Screenshot shows multiple area paths assigned to team.](media/team-defaults/stdefaults-set-team-area-paths-team-services-list-preview.png) -1. Open **Areas** for the team context. +1. When you finish, refresh the product backlog page for the team, and you see those work items assigned to the team. Add area path to the columns shown to see the assignments made to work items. - Here, we show the Areas for the Fabrikam Fiber team. + ![Screenshot shows backlog view of default team.](media/team-defaults/area-path-assigned-to-item.png) - > [!div class="mx-imgBorder"] - > ![Area page for team, on-premises versions](media/team-defaults/open-areas-fabrikam-team.png) - -2. Choose the area path(s) to be active for each team. - - > [!div class="mx-imgBorder"] - > ![Work, Iterations page for team, on-premises versions](media/team-defaults/stdefaults-add-area-paths.png) - - In this instance, we choose to activate all three subarea paths for the project. The management team can now track progress across all three teams. - - ![Multiple area paths assigned to team, on-premises versions](media/team-defaults/stdefaults-set-team-area-paths-management-team-team-services-list.png) - -3. When you've finished, refresh the product backlog page for the team, and you'll see those work items assigned to the team. Add area path to the columns shown to see the assignments made to work items. - - > [!div class="mx-imgBorder"] - > ![Backlog view of default team, on-premises versions](media/add-team/product-backlog-default-team-horz.png) + ![Screenshot shows added area path column to backlog.](media/team-defaults/add-a-column-backlog.png) ::: moniker-end + #### [Azure DevOps CLI](#tab/azure-devops-cli) - - ::: moniker range="azure-devops" -You can set the default area path for a team or add an area path, using [az boards area team add](/cli/azure/boards/area/team#az-boards-area-team-add). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). +You can set the default area path for a team or add an area path, using [az boards area team add](/cli/azure/boards/area/team#az-boards-area-team-add). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). > [!div class="tabbedCodeSnippets"] ```azurecli @@ -438,15 +345,15 @@ az boards area team add --path --team #### Parameters -- **path**: Required. Absolute path of an area. Example: --path \ProjectName\AreaName. +- **path**: Required. Absolute path of an area. Example: `--path \ProjectName\AreaName`. - **team**: Required. Name or ID of the team. - **include-sub-areas**: Optional. Include child nodes of the area path. Accepted values: false, true. -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". +- **project**: Optional. Name or ID of the project. Example: `--project "Fabrikam Fiber"`. - **set-as-default**: Optional. Specify as the default area path for the team. Default: False. #### Example -For example, the following command adds the Voice area path to the Voice team for the Fabrikam Fiber project, sets it as the default and to include sub-areas. +For example, the following command adds the Voice area path to the Voice team for the Fabrikam Fiber project, sets it as the default and to include subareas. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -460,10 +367,7 @@ Fabrikam Fiber\Voice True True [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - - +--- ## Rename or move an Area Path @@ -477,11 +381,11 @@ The system automatically updates work items and queries that reference your upda :::image type="content" source="media/areas/edit-area-rename-project-configuration.png" alt-text="Screenshot of open context menu for an Area Path node, choose Edit option."::: -2. In the dialog that opens, enter the new name. +1. In the dialog that opens, enter the new name. :::image type="content" source="media/areas/edit-area-rename-dialog.png" alt-text="Screenshot of Edit area dialog."::: -3. To move the node within the hierarchy, change the **Location** field. +1. To move the node within the hierarchy, change the **Location** field. > [!NOTE] > When you rename or change the **Location** field for a node, the system automatically updates the existing work items that reference the **Area Path**. @@ -490,7 +394,6 @@ The system automatically updates work items and queries that reference your upda ::: moniker range="azure-devops" - ### Rename or move an area path from a project You can rename or move an area path for a project, using [`az boards area project update`](/cli/azure/boards/area/project#az-boards-area-project-update) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). @@ -503,10 +406,10 @@ az boards area project update --path [--project] ``` -- **path**: Required. Absolute path of an area. Example: --path \ProjectName\AreaName. +- **path**: Required. Absolute path of an area. Example: `--path \ProjectName\AreaName`. - **child-id**: Optional. Moves an existing area path and adds it as a child node for the specified path name or ID. - **name**: Optional. Specifies the new name of the area path. -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". +- **project**: Optional. Name or ID of the project. Example: `--project "Fabrikam Fiber"`. #### Example @@ -520,8 +423,6 @@ ID Identifier Name Path 55412 b00f86a2-3d49-4ad2-af01-da2537947baa Voice and Web \Fabrikam Fiber\Area\Voice and Web False ``` - - ### Remove an area path from a team To remove an area path from a team, use [`az boards area team remove`](/cli/azure/boards/area/team#az-boards-area-team-remove). @@ -534,10 +435,10 @@ az boards area team remove --path ``` #### Parameters -- **path**: Required. Absolute path of an area. Example: --path \ProjectName\AreaName. -- **team**: Required. Name or ID of the team. -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". +- **path**: Required. Absolute path of an area. Example: `--path \ProjectName\AreaName`. +- **team**: Required. Name or ID of the team. +- **project**: Optional. Name or ID of the project. Example: `--project "Fabrikam Fiber"`. #### Example @@ -552,9 +453,7 @@ az boards area team remove --path "\Fabrikam Fiber\Service Delivery\Voice" --tea [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - +--- ## Delete an Area Path @@ -574,13 +473,7 @@ When you delete an **Area Path**, you must provide an **Area Path** to use to up You can quickly generate [queries](../../boards/queries/using-queries.md) to view the progress based on an area path. For example, [visualize progress of work items that are assigned to each team's area path](../../report/dashboards/charts.md), as shown in the following stacked bar chart. Choose Node Name to get the leaf node of the area path. -![Stacked bar chart by area and state](media/areas/stacked-bar-chart.png) - -## Q & A - -### Q: Do I have to assign an area path to a team? - -**A:** No. You assign area paths to teams so that the work items assigned to that area path appear on the team's backlogs and boards. By default, all work items get assigned to the root area path. These work items appear in the default team that's defined for the project. +![Screenshot shows stacked bar chart by area and state.](media/areas/stacked-bar-chart.png) ## Next steps @@ -591,29 +484,28 @@ You can quickly generate [queries](../../boards/queries/using-queries.md) to vie As you can see, area paths play a major role in supporting Agile tools, teams, and managing work items. Learn more about working with these fields from the following articles: -- [About areas and iterations](about-areas-iterations.md) -- [Add another team](../../organizations/settings/add-teams.md) +- [Learn about areas and iterations](about-areas-iterations.md) +- [Add another team](../../organizations/settings/add-teams.md) - [Configure team settings and add team administrators](manage-teams.md) -- [Agile tools that rely on areas or iterations](about-teams-and-settings.md) -- [Query by area or iteration path](../../boards/queries/query-by-area-iteration-path.md) +- [Use Agile tools that rely on areas or iterations](about-teams-and-settings.md) +- [Query by area or iteration path](../../boards/queries/query-by-area-iteration-path.md) - [Set permissions and access for work tracking](../security/set-permissions-access-work-tracking.md) - ### Programmatic resources Area paths and iteration paths are also referred to as *Classification Nodes*. ::: moniker range="azure-devops" -- [az boards area (Azure DevOps CLI)](/cli/azure/boards/area) -- [Teams (REST API)](/rest/api/azure/devops/core/teams) -- [Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) +- [Use the az boards area (Azure DevOps CLI)](/cli/azure/boards/area). +- [Use the Teams (REST API)](/rest/api/azure/devops/core/teams) to manage team configurations. +- [Utilize the Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) to organize work item classifications. ::: moniker-end ::: moniker range="< azure-devops" -- [Teams (REST API)](/rest/api/azure/devops/core/teams) -- [Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) -- [Define the classification plug-in (Process Template)](/previous-versions/azure/devops/reference/process-templates/define-classification-plug-in) +- [Use the Teams (REST API)](/rest/api/azure/devops/core/teams) to manage team configurations. +- [Utilize the Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) to organize work item classifications. +- [Configure the process by defining the classification plug-in (Process Template)](/previous-versions/azure/devops/reference/process-templates/define-classification-plug-in). ::: moniker-end diff --git a/docs/organizations/settings/set-iteration-paths-sprints.md b/docs/organizations/settings/set-iteration-paths-sprints.md index 2f2f7314ec8..08a9add7206 100644 --- a/docs/organizations/settings/set-iteration-paths-sprints.md +++ b/docs/organizations/settings/set-iteration-paths-sprints.md @@ -9,132 +9,82 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 02/10/2023 +ms.date: 11/12/2024 --- # Define iteration paths (sprints) and configure team iterations [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Iteration Paths, also referred to as *sprints*, support assignment of work items to time-box intervals. You define iteration paths at the project level, and then each team selects the paths that they want to use. Iteration paths are a shared resource used by all teams that select them. You can create a flat set of iteration paths or a hierarchy of paths to support releases, sub-releases, and sprints. +Iteration Paths, also known as *sprints*, assign work items to specific time-box intervals. Define iteration paths at the project level and have each team select the paths they use. Iteration paths are shared among all selected teams. You can create a flat or hierarchical structure of iteration paths to support releases, subreleases, and sprints. If your team doesn't use sprints for planning and tracking work, retain the default team assignments and utilize product and portfolio backlogs and boards, though sprint planning tools won’t be applicable. [!INCLUDE [temp](../../boards/includes/list-sprint-dependent-tools.md)] - -For information about naming restrictions and limits placed on addition of Iteration Paths, see [About areas and iterations, Naming restrictions](about-areas-iterations.md#name-restrictions). +For information about naming restrictions and limits placed on addition of Iteration Paths, see [About areas and iterations, Naming restrictions](about-areas-iterations.md#naming-restrictions). > [!TIP] -> If all you need to do is change the iteration dates, you can do that quickly as shown in [Change sprint dates](../../boards/sprints/define-sprints.md). However, if you need to define the iteration paths and tree structure, then follow the guidance provided in this article. - - +> To quickly update iteration dates, see [Change sprint dates](../../boards/sprints/define-sprints.md). However, if you need to define the iteration paths and tree structure, then follow the guidance provided in this article. ## Prerequisites -- To add an iteration path to a project, you must be a member of the **Project Administrators** group. If you don't have a project yet, [create one now](../projects/create-project.md). By default, the user who created the project has these permissions set. -- To add, edit, and manage iteration paths under a node, you must have one or more of the following permissions set to **Allow** for the node that you want to manage: **Create child nodes**, **Delete this node**, **Edit this node**, and **View permissions for this node**. -- To set team iteration paths, you must be [added as the team administrator](add-team-administrator.md) or be a member of the **Project Administrators** group. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To set team area or iteration paths: [Team administrator](add-team-administrator.md) or a member of the [Project Administrators](../security/change-project-level-permissions.md) group. By default, the user who created the project has these permissions.
      - To add an area path under the root node or edit or delete any child node: Member of the [Project Administrators](../security/change-project-level-permissions.md) group.
      - To add, edit, and manage area paths under a node: One or more of the following permissions set to **Allow**:
      - **Create child nodes**
      - **Delete this node**
      - **Edit this node**
      - **View permissions in this node**| For more information about acquiring permissions, see [Change project-level permissions](../security/change-project-level-permissions.md) or [Set permissions and access for work tracking](../security/set-permissions-access-work-tracking.md#set-permissions-area-path). ## Get started -Newly created projects contain a single, root area path that corresponds to the project name. You add area paths under this root. Also, each project typically specifies a predefined set of iteration paths to help you get started tracking your work. You only need to specify the dates. +New projects start with a single root area path matching the project name. Add other area paths under this root and use predefined iteration paths for tracking work by setting dates. -If you're new to managing projects and teams, complete the following steps. +If you're new to managing projects and teams, follow these steps to configure your project and teams: -1. Review [Configure and customize Azure Boards](../../boards/configure-customize.md). -1. Define the area paths and teams following the guidance provided in [Define area paths and assign to a team](set-area-paths.md#guidance). -1. Determine the length of the iteration you want to support. Recommended practice is to have all teams use the same sprint cadence. For guidance, review [About areas and iterations](about-areas-iterations.md). -1. Determine if you want a flat structure or hierarchy of sprints and releases. -1. Open **Project settings>Project configuration** and define the iteration paths to support steps 2 and 3 at the project level. Follow the steps provided later in this article: [Open Project Settings, Project configuration](#open-project-settings) and [Add iterations and set iteration dates](#iterations). -1. Open the team configuration and assign the default and additional area path(s) to each team. Follow the steps provided later in this article: [Open team settings](#open-team-settings) and [Set team default iteration path(s)](#activate). -1. Each team should assign the default iteration path they selected to their work items. Do so for those work items to show up on their product backlogs and boards. Use [bulk modify](../../boards/backlogs/bulk-modify-work-items.md) to modify several work items at once. See also [Assign backlog items to a sprint](../../boards/sprints/assign-work-sprint.md). +1. **Configure Azure Boards**: Review [Configure and customize Azure Boards](../../boards/configure-customize.md). +2. **Define area paths and teams**: Follow [Define area paths and assign to a team](set-area-paths.md#get-started), ensuring at least one area path per team. +3. **Set iteration length**: Decide on iteration lengths, preferably consistent across teams. See [About areas and iterations](about-areas-iterations.md). +4. **Choose sprint structure**: Choose between a flat or hierarchical sprint and release structure. +5. **Define iteration paths**. +6. **Create teams**: Create necessary teams based on step 2. See [Add a team, move from one default team to several teams](add-teams.md). +7. **Assign area paths to teams**: In team configuration, assign default and other area paths to each team. Follow [Set team default iteration paths](#select-team-sprints-and-set-the-default-iteration-path). +8. **Assign iteration paths to work items**: Use [bulk modify](../../boards/backlogs/bulk-modify-work-items.md) to assign work items to iteration paths for visibility on backlogs and boards. Also, see [Assign backlog items to a sprint](../../boards/sprints/assign-work-sprint.md). As needed, you can do the following tasks at any time: -- Add additional child iteration nodes +- Add more child iteration nodes - Rename an iteration path (except the root path) - Move a child iteration path under another node - Delete a child iteration path - Change the default and selected iteration paths assigned to a team - - ### Team backlog iteration versus default iteration -Each team has access to many Agile tools, as described in [About teams and Agile tools](about-teams-and-settings.md). Each tool references the team's default area path(s). Several tools reference the team's default and selected iteration paths or sprints. Most teams choose one area path and several iteration paths to support their work tracking activities. However, to support other scenarios, it's possible for teams to choose several area paths to appear on their backlogs and boards. - - -Teams can set a default iteration different from the backlog iteration. The backlog iteration determines which items appear on the team's backlogs and boards. And, the default iteration determines what value is assigned to work items created from the team context. - -All work items that you create from your team context are automatically assigned both the team's default area path and default iteration path. - - -[!INCLUDE [temp](../../includes/version-selector-minimize.md)] - +Each team has access to various Agile tools, as detailed in [About teams and Agile tools](about-teams-and-settings.md). These tools reference the team's default area paths and selected iteration paths or sprints. Typically, teams use one area path and multiple iteration paths for work tracking, but you can use multiple area paths on backlogs and boards to support different scenarios. - - +Teams can set a default iteration separate from the backlog iteration. The backlog iteration determines which items appear on the team's backlogs and boards, while the default iteration assigns values to newly created work items. -## Open Project Settings, list project iterations +All work items created within the team context are automatically assigned the team's default area path and default iteration path. -::: moniker range=">= azure-devops-2019" +## List project iterations -You define both areas and iterations for a project from the **Project Settings > Boards > Project configuration**. - -::: moniker-end - -::: moniker range="tfs-2018" - -You define both areas and iterations from the **Work** pages of the **Project Settings** context. From the user context, you open the admin context by choosing **Settings** :::image type="icon" source="../../media/icons/gear-icon.png" border="false":::. - -::: moniker-end +To list project iterations, do the following steps: #### [Browser](#tab/browser/) ::: moniker range=">= azure-devops-2020" +1. Sign in to your project `https://dev.azure.com/{Your_Organization/Your_Project}`. -From the web portal, open **Project Settings**. - -Define both areas and iterations for a project from the **Project settings** > **Boards** > **Project configuration**. - -1. Choose (1) **Project Settings**, expand **Boards** if needed, and then choose (2) **Project configuration** and (3) **Iterations**. +1. Select (1) **Project settings** > (2) **Project configuration** > (3) **Iterations**. > [!div class="mx-imgBorder"] > ![Screenshot of Project Settings, Project Configuration.](media/iterations/open-work-project-config-iterations-preview.png) ::: moniker-end -::: moniker range="azure-devops-2019" - -From the web portal, open **Project Settings**. - -Define both areas and iterations for a project from the **Project configuration > Iterations**. - -1. From the web portal, choose **Project settings**(1), select **Project configuration**(2), and then **Iterations**(3). - - > [!div class="mx-imgBorder"] - > ![Screenshot of Project Settings, Project Configuration for Azure DevOps Server 2019.](media/iterations/open-work-project-config-iterations-vert.png) - -::: moniker-end - - - -::: moniker range="tfs-2018" - -From the web portal, choose **Project settings** :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: to open project administration pages. Then, choose **Iterations**. - -![Screenshot of Open the project administration page for TFS 2018.](../../media/settings/open-project-settings-tfs-2015.png) - -::: moniker-end - #### [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" -[List project iteration paths](#iteration-project-list) | [Add a project iteration](#add-project-iteration) | [List team iteration paths](#list-team-iteration-paths) | [Set team iteration paths](#set-team-iteration-paths) | [Delete or update a project iteration path](#delete-update-iteration-paths) - - +[List project iteration paths](#list-project-iterations) | [Add a project iteration](#add-iterations-and-set-iteration-dates) | [List team iteration paths](#list-team-iterations) | [Set team iteration paths](#select-team-sprints-and-set-the-default-iteration-path) | [Delete or update a project iteration path](#rename-or-move-an-iteration) List the iterations defined for a project using [az boards iteration project list](/cli/azure/boards/iteration/project#az-boards-iteration-project-list). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). @@ -148,9 +98,8 @@ az boards iteration project list [--depth] #### Parameters - **depth**: Optional. Depth of child nodes to be listed. Example: --depth 3. -- **path**: Optional. Absolute path of an iteration. `\Iteration\` must follow after the `\ProjectName`, which distinguishes it from an area path. Example: --path \ProjectName\Iteration\IterationName. If spaces are used within a node, then enclose in double-quotes, for example,--path "\Fabrikam Fiber\Iteration\Sprint 1". When not specified, lists iteration paths from the root level. -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". - +- **path**: Optional. Absolute path of an iteration. `\Iteration\` must follow after the `\ProjectName`, which distinguishes it from an area path. Example: --path \ProjectName\Iteration\IterationName. If spaces are used within a node, then enclose in double-quotes, for example,`--path "\Fabrikam Fiber\Iteration\Sprint 1"`. When not specified, lists iteration paths from the root level. +- **project**: Optional. Name or ID of the project. Example: `--project "Fabrikam Fiber"`. #### Example @@ -179,101 +128,43 @@ ID Identifier Name Path [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - - +--- ## Add iterations and set iteration dates -You can add iterations in the same way that you add areas. For more information about working within a sprint cadence, see [Scrum and sprint planning tools](../../boards/sprints/scrum-key-concepts.md). + Add iterations in the same way that you add areas. For more information about working within a sprint cadence, see [Scrum and sprint planning tools](../../boards/sprints/scrum-key-concepts.md). #### [Browser](#tab/browser/) ::: moniker range=">= azure-devops-2020" -1. Add and modify area paths from **Project settings** > **Project configuration** > **Iterations**. +1. Add and modify iterations from **Project settings** > **Project configuration** > **Iterations**. For Scrum-based projects, you see the following set of sprints. :::image type="content" source="media/areas/modify-areas-its-iterations-preview.png" alt-text="Screenshot of Project Settings context, project configuration, Iterations page."::: -2. To schedule the start and end dates for each sprint that your teams use, highlight the sprint and choose **Set dates**. Or, you can select **Actions** :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: for the iteration path and choose **Edit**. +1. To schedule the start and end dates for each sprint that your teams use, highlight the sprint and choose **Set dates**. Or, select **Actions** :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: for the iteration path and choose **Edit**. :::image type="content" source="media/iterations/set-dates-preview.png" alt-text="Screenshot of dialog to Set dates."::: -3. Choose the calendar icon to select new dates. +1. To select new dates, choose the calendar icon. :::image type="content" source="media/iterations/schedule-sprints-calendar-preview.png" alt-text="Screenshot of Iterations page, and calendar icon for selecting new dates."::: -4. When you're finished, you have a set of sprints scheduled - similar to the following image: +1. When you finish, you have a set of sprints scheduled - similar to the following image: :::image type="content" source="media/areas/modify-areas-its-iterations-preview.png" alt-text="Screenshot of Iterations page, scheduled set of sprints."::: - Your next step is to [choose the sprints each team uses](#activate-team-services). - -::: moniker-end - -::: moniker range="azure-devops-2019" - -From **Iterations**, you can add iterations that teams can then select for their use. - - - -1. Add and modify area paths from the **Work** > **Iterations** page from the project admin or settings context. - - For Scrum-based projects, you see the following set of sprints. - - :::image type="content" source="media/areas/modify-areas-its-iterations-ts.png" alt-text="Screenshot of Project Settings Context, Work, Iterations page."::: - -2. To schedule the start and end dates for each sprint your teams use, Highlight the sprint and choose **Set dates**. Or, you can select **Actions** :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: context menu for the iteration path and choose **Edit**. - - Choose the calendar icon to choose new dates. - - :::image type="content" source="media/iterations/schedule-sprints-calendar.png" alt-text="Screenshot of Work, Iterations page, and calendar icon to choose for new dates for Azure DevOps Server 2019."::: - -3. When you're finished, you have a set of sprints scheduled - like this: - - :::image type="content" source="media/areas/modify-areas-its-iterations-ts.png" alt-text="Screenshot of Work, Iterations page, scheduled set of sprints for Azure DevOps Server 2019."::: - - Your next step is to [choose the sprints each team uses](#activate-team-services). - -::: moniker-end - -::: moniker range="tfs-2018" - - - -Add and modify area paths from the **Work** > **Iterations** page from the project admin or settings context. - -For Scrum-based projects, you see the following set of sprints. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Project Settings, Work, Iterations page for TFS 2018.](media/areas/modify-areas-its-iterations-ts.png) - -1. To schedule the start and end dates for each sprint your teams use, Highlight the sprint and choose **Set dates**. Or, you can select **Actions** :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: for the iteration path and choose **Edit**. - - Choose the calendar icon to choose new dates. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Work, Iterations page, and calendar icon for setting new dates in TFS 2018.](media/iterations/schedule-sprints-calendar.png) - -2. When you're finished, you have a set of sprints scheduled - like this: - - :::image type="content" source="media/areas/modify-areas-its-iterations-scheduled-ts.png" alt-text="Screenshot of Work, Iterations page, scheduled set of sprints for TFS 2018."::: - - Your next step is to [choose the sprints each team uses](#activate-team-services). + Your next step is to [choose the sprints each team uses](#select-team-sprints-and-set-the-default-iteration-path). ::: moniker-end - #### [Azure DevOps CLI](#tab/azure-devops-cli) - - ::: moniker range="azure-devops" -You can add iteration paths to a project using [az boards iteration project create](/cli/azure/boards/iteration/project#az-boards-iteration-project-create). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). + Add iteration paths to a project using [az boards iteration project create](/cli/azure/boards/iteration/project#az-boards-iteration-project-create). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). > [!div class="tabbedCodeSnippets"] ```azurecli @@ -287,12 +178,11 @@ az boards iteration project create --name #### Parameters - **name**: Required. Enter the name of the iteration path. -- **finish-date**: Optional. Finish date of the iteration. Example: "2019-06-21". +- **finish-date**: Optional. Finish date of the iteration. Example: "--finish-date 2019-06-21". - **path**: Optional. Absolute path of an iteration. Example: \ProjectName\Iteration\IterationName. When not specified, adds an iteration at the root level. -- **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". +- **project**: Optional. Name or ID of the project. Example:` --project "Fabrikam Fiber"`. - **start-date**: Optional. Enter the start date of the iteration path. Example: "2019-06-03". Must be earlier than the finish-date. - #### Example For example, the following command adds Sprint 36, which starts on September 1, 2019 and ends September 30, 2019 as an iteration path to the default project at the root node. @@ -320,23 +210,18 @@ az boards iteration project create --name "Sprint 36" --start-date 2019-09-01 -- [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - - +--- -## Open team settings, list team iterations +## List team iterations -You can set team defaults from team settings. If you're not a team administrator, [get added as one](add-team-administrator.md). Only team or project administrators can change team settings. + Set team defaults from team settings. If you're not a team administrator, [get added as one](add-team-administrator.md). Only team or project administrators can change team settings. > [!NOTE] -> Teams can be assigned a maximum of 300 **Iteration Paths**. To learn more, see [Work tracking, process, and project limits](work/object-limits.md). +> Teams can be assigned a maximum of 300 **Iteration Paths**. For more information, see [Work tracking, process, and project limits](work/object-limits.md). #### [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" - -You define both areas and iterations from **Project settings > Boards > Team configuration**. You can quickly navigate to it from a team work tracking backlog, board, or dashboard. +Define both areas and iterations from **Project settings > Boards > Team configuration**. Quickly navigate to it from a team work tracking backlog, board, or dashboard. 1. Open a backlog or board for a team and choose :::image type="icon" source="../../media/icons/team.png" border="false"::: **Team profile** and then **Team Settings**. @@ -350,29 +235,16 @@ You define both areas and iterations from **Project settings > Boards > Team con > [!div class="mx-imgBorder"] > ![Screenshot of Team Profile, choose Iterations and area.](media/team-defaults/team-profile-choose-iterations-areas.png) -3. If you need to switch the team context, use the team selector within the breadcrumbs. +3. To switch the team context, use the team selector within the breadcrumbs. > [!div class="mx-imgBorder"] - > ![Screenshot of Team Configuration, Team breadcrumb.](media/team-defaults/select-team-context.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -You open team settings from the upper navigation bar. Select the team you want and then choose **Team settings** :::image type="icon" source="../../media/icons/gear_icon.png" border="false":::. For more information about switching your team focus, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md#switch-team-context) - -> [!div class="mx-imgBorder"] -> ![Screenshot of Open team settings for TFS 2018.](media/team-defaults/open-team-settings-horz.png) - -::: moniker-end + > ![Screenshot of Team Configuration, Team breadcrumb.](media/team-defaults/select-team-context.png) #### [Azure DevOps CLI](#tab/azure-devops-cli) - - ::: moniker range="azure-devops" -You can list the iteration paths defined for a team using [az boards area team list](/cli/azure/boards/area/team#az-boards-area-team-list). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). + List the iteration paths defined for a team using [az boards area team list](/cli/azure/boards/area/team#az-boards-area-team-list). To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). > [!div class="tabbedCodeSnippets"] ```azurecli @@ -387,7 +259,6 @@ az boards iteration team list --team - **project**: Optional. Name or ID of the project. - **timeframe**: Optional. A filter for which iterations are returned based on relative time. Only *Current* is supported. - #### Example For example, the following command lists the area paths for the Service Delivery team. For other output format options, see [Output formats for Azure CLI commands](/cli/azure/format-output-azure-cli) @@ -406,20 +277,14 @@ dd10f1bf-bedd-4c6f-926f-b2abea81bb50 Sprint 2 2019-01-21T00:00:00+00:00 2019 [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - +--- ## Select team sprints and set the default iteration path You [define sprints for the project](../../boards/sprints/define-sprints.md) and then select them to be active for each team. You assign the default iteration to use when creating new work items. - - #### [Browser](#tab/browser/) -::: moniker range=">= azure-devops-2019" - 1. Open **Project settings > Boards > Team Configuration > Iterations** for a team. Here, we navigate to the Fabrikam Fiber Team. @@ -433,7 +298,7 @@ You [define sprints for the project](../../boards/sprints/define-sprints.md) and Also, all work items added through a team's backlog or board are assigned the backlog iteration. -3. **Default iteration**. The default iteration defines the iteration that's used when you create a work item from the team backlog or Kanban board. You can specify any iteration defined under the **Backlog iteration** path. To assign new work items to the current iteration, specify **@CurrentIteration**. The same macro used in [queries to list work items assigned to the currently active iteration assigned to the team](../../boards/queries/query-by-date-or-current-iteration.md#current-iteration) is used. +3. **Default iteration**. The default iteration defines the iteration to use when you create a work item from the team backlog or board. specify any iteration defined under the **Backlog iteration** path. To assign new work items to the current iteration, specify **@CurrentIteration**. The same macro used in [queries to list work items assigned to the currently active iteration assigned to the team](../../boards/queries/query-by-date-or-current-iteration.md#current-iteration) is used. For example, you might want all new work items added to a future iteration path, which you use to triage and assign to specific sprints at periodic intervals. @@ -447,59 +312,17 @@ You [define sprints for the project](../../boards/sprints/define-sprints.md) and > [!div class="mx-imgBorder"] > ![Screenshot of Work, Iterations page for team, select sprints.](media/team-defaults/select-iterations.png) - When you're done, you should see a list of sprints, similar to the following. + When you finish, you should see a list of sprints, similar to the following. > [!div class="mx-imgBorder"] > ![Screenshot of Work, Iterations page for team, activates sprint list.](media/team-defaults/selected-iterations.png) - If you don't see the sprints or dates that you need, you can add or edit iterations for the project, provided you have the required permissions. For more information, see [Define iteration (sprint) paths](set-iteration-paths-sprints.md). - -5. To see the newly activated sprint backlogs, refresh your team's [product backlog page](../../boards/backlogs/create-your-backlog.md). - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Open **Work** > **Iterations** for a team. - - Here, we navigate to the Fabrikam Fiber Team. - - ![Screenshot of Work, Iterations page for a team.](../../boards/sprints/media/dsprints-team-work-iterations-page.png) - - -2. **Backlog iteration**. Only work items assigned to an iteration equal to or under this backlog iteration appear in the team's backlogs and boards. - - ![Screenshot of Work, Iterations page for a team, set team backlog iteration for backlogs and boards.](media/team-defaults/stdefaults-team-backlog-iteration.png) - - Also, all work items added through a team's backlog or board are assigned the backlog iteration. - -3. **Default iteration**. The default iteration defines the iteration that's used when you create a work item from the team dashboard and queries page. You can use an explicit value or use @CurrentIteration to assign new work items to the team's current iteration. The same macro used in [queries to list work items assigned to the currently active iteration assigned to the team](../../boards/queries/query-by-date-or-current-iteration.md#current-iteration) is used. - - For example, you might want all new work items added to a future iteration path, which you use to triage and assign to specific sprints at periodic intervals. - - ![Screenshot of Work, Iterations page for team, set team default for new work items for TFS 2018.](media/team-defaults/stdefaults-team-default-iteration.png) - -4. **Active sprints**. Add an iteration for each sprint backlog you want active for the team. Add each sprint, one by one, by selecting it from the menu. - - ![Screenshot of Work, Iterations page for team, select sprint to activate for TFS 2018.](../../boards/sprints/media/dsprints-add-sprints-to-team-iterations-page.png) - - When you're done, you should see a list of sprints, similar to the following. - - ![Screenshot of Work, Iterations page for team, activates sprint list for TFS 2018.](../../boards/sprints/media/dsprints-selected-active-sprints.png) - - If you don't see the sprints or dates that you need, then [return to the project administration context and define them there](set-iteration-paths-sprints.md#define-sprints-team-services). + If you don't see the sprints or dates that you need, add or edit iterations for the project, provided you have the required permissions. For more information, see [Define iteration (sprint) paths](set-iteration-paths-sprints.md). 5. To see the newly activated sprint backlogs, refresh your team's [product backlog page](../../boards/backlogs/create-your-backlog.md). -::: moniker-end - - - - #### [Azure DevOps CLI](#tab/azure-devops-cli) - - ::: moniker range="azure-devops" Add iteration paths, set the default iteration path, or set the backlog iteration path for a team using one of the following [az boards iteration team](/cli/azure/boards/iteration/team)[Azure DevOps CLI](../../cli/index.md) commands. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). @@ -522,7 +345,7 @@ az boards iteration team set-backlog-iteration --id --team - **team**: Required. Name or ID of the team. - **default-iteration-macro**: Optional. Default iteration macro, the only valid entry is @CurrentIteration. -- **id**: Optional. Enter the ID of an iteration path. To determine the ID, list the iteration paths using [az boards iteration project list](#iteration-project-list). +- **id**: Optional. Enter the ID of an iteration path. To determine the ID, list the iteration paths using [az boards iteration project list](#list-project-iterations). - **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". #### Example @@ -549,13 +372,11 @@ az boards iteration team add --id a0554e98-b1f1-4230-8500-733c739a0113 --team "S [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - +--- ## Rename or move an iteration -When you rename an iteration, or move the node within the tree hierarchy, the system automatically updates the work items and queries that reference the existing path(s). +When you rename an iteration, or move the node within the tree hierarchy, the system automatically updates the work items and queries that reference the existing paths. #### [Browser](#tab/browser/) @@ -580,9 +401,7 @@ When you rename an iteration, or move the node within the tree hierarchy, the sy ::: moniker range="azure-devops" -You can rename, move, or delete an iteration path for a project, using the following [az boards iteration project](/cli/azure/boards/iteration/project) commands. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). - - + Rename, move, or delete an iteration path for a project, using the following [az boards iteration project](/cli/azure/boards/iteration/project) commands. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). ### Rename or move a project iteration path @@ -607,7 +426,7 @@ az boards iteration project update --path - **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". - **finish-date**: Optional. Finish date of the iteration. Example: "2019-06-21". - **start-date**: Optional. Start date of the iteration path. Example: "2019-06-03". Must be earlier than the finish-date. -- **yes**: Optional. Do not prompt for confirmation. +- **yes**: Optional. Don't prompt for confirmation. #### Example @@ -626,10 +445,7 @@ ID Identifier Name Start Date Fin [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - - +--- ## Delete an Iteration Path @@ -664,47 +480,42 @@ az boards iteration project delete --path - **path**: Required. Absolute path of an iteration. Example: \ProjectName\Iteration\IterationName. - **project**: Optional. Name or ID of the project. Example: --project "Fabrikam Fiber". -- **yes**: Optional. Do not prompt for confirmation. +- **yes**: Optional. Don't prompt for confirmation. ::: moniker-end [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - - +--- ### Export/import iteration paths -You can't export or import the structure of tree paths for one project to use with another project. +You can't export or import the structure of tree paths for one project to use with another project. -::: moniker range=">= azure-devops-2020" +::: moniker range="azure-devops" + +Using the Azure CLI, you can use the `az boards iteration` command to list the iterations defined for one project and then add them to another project. Once you add the iterations to another project, you can then use the `az boards iteration team` command to add them to a team and set the default and backlog iteration path for the team. -However, using the `az boards iteration` commands you can list the iterations defined for one project and then add them to another project. Once they are added, you can then use the `az boards iteration team` commands to add them to a team and set the default and backlog iteration path for the team. Using the [Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) and [Teams (REST API)](/rest/api/azure/devops/core/teams), you can perform similar actions. +You can use the [Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) and [Teams (REST API)](/rest/api/azure/devops/core/teams) to perform similar actions. ::: moniker-end +::: moniker range="< azure-devops" + You can use the [Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) to list the iterations defined in one project. Once you add the iterations to another project, use the [Teams (REST API)](/rest/api/azure/devops/core/teams) to add them to a team and set the default and backlog iteration path for the team. +::: moniker-end ## Archive iteration paths -After a while, you may want to archive iteration paths that were used for sprints that are a year or more out of date. You can do that by moving the iteration path under a node that you label "Archive". All work items are updated with the moved iteration path. Also, teams can de-select those sprints that have past. All data is maintained in the data store with the new iteration path assignments. +After a while, you might want to archive iteration paths that were used for sprints that are a year or more out of date. You can do so by moving the iteration path under a node that you label "Archive". All work items are updated with the moved iteration path. Also, teams can de-select those sprints that have past. All data is maintained in the data store with the new iteration path assignments. -Before you archive the iterations, consider if you've captured all the reports that you may want. - +Before you archive the iterations, consider if you captured all the reports that you want. ## Chart progress by iteration You can quickly generate [queries](../../boards/queries/using-queries.md) to view the progress for those areas. For example, you can [visualize progress of work items that are assigned to sprints](../../report/dashboards/charts.md), as shown in the following stacked bar chart. -![Stacked bar chart by area](media/areas/ALM_CW_StackedBarChart.png) - -## Q & A - -### Q: Do I have to assign iteration paths to a team? - -**A:** If your team doesn't use sprints to plan and track work, then no. You can leave the defaults assigned to the team as they are. You can then use the product and portfolio backlogs and boards, however you can't gain much use of sprint planning tools. +![Stacked bar chart by area](media/areas/ALM_CW_StackedBarChart.png) ## Related articles @@ -720,16 +531,16 @@ Area paths and iteration paths are also referred to as *Classification Nodes*. ::: moniker range="azure-devops" -- [az boards iteration (Azure DevOps CLI)](/cli/azure/boards/iteration) -- [Teams (REST API)](/rest/api/azure/devops/core/teams) -- [Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) +- [Use the az boards iteration (Azure DevOps CLI)](/cli/azure/boards/iteration) +- [Use the Teams (REST API)](/rest/api/azure/devops/core/teams) +- [Utilize the Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) ::: moniker-end ::: moniker range="< azure-devops" -- [Teams (REST API)](/rest/api/azure/devops/core/teams) -- [Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) +- [Use the Teams (REST API)](/rest/api/azure/devops/core/teams) +- [Utilize the Classification Nodes (REST API)](/rest/api/azure/devops/wit/classification%20nodes) - [Define the classification plug-in (Process Template)](/previous-versions/azure/devops/reference/process-templates/define-classification-plug-in) ::: moniker-end diff --git a/docs/organizations/settings/set-services.md b/docs/organizations/settings/set-services.md index aa7f5bc88a1..b8773bef962 100644 --- a/docs/organizations/settings/set-services.md +++ b/docs/organizations/settings/set-services.md @@ -1,69 +1,58 @@ --- title: Turn a service on or off titleSuffix: Azure DevOps -ms.custom: contperf-fy22q4 -description: Control which services are available for a project from the web portal for Azure DevOps. +description: Control which services are available for a project from the web portal for Azure DevOps. ms.subservice: azure-devops-settings ms.author: chcomley author: chcomley ms.topic: how-to -monikerRange: '>= azure-devops-2019' -ms.date: 07/27/2022 +monikerRange: "<=azure-devops" +ms.date: 11/12/2024 --- # Turn a service on or off [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Control which services are available through the web portal, by turning a service on or off. Turning off a service hides the service to all members of the project. However, if you choose to enable a service later, all your existing data is available. +Manage the availability of Azure DevOps services through the web portal by enabling or disabling them as needed. Disabling a service hides it from all project members, helping to streamline the user interface and focus on the tools that are currently in use. This customization allows you to tailor the portal to your team's specific needs and workflows. If you choose to re-enable a service later, all existing data associated with that service remain intact and accessible. ## Prerequisites -::: moniker range="azure-devops" - -- You must have an organization in Azure DevOps. If you don't have one, [do that now](../../user-guide/sign-up-invite-teammates.md). -- As an organization owner or member of the Project Administrators group, you can change policies and change project information. If you're not a member, [get added as one](../security/change-project-level-permissions.md). -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - -- You must have an Azure DevOps project. If you don't have one, [add one now](../projects/create-project.md). -- As a member of the Project Administrators group, you can change policies and change project information. If you're not a member, [get added as one](../security/change-project-level-permissions.md). -::: moniker-end +[!INCLUDE [prerequisites-project-administrator-only](../../includes/prerequisites-project-administrator-only.md)] ## Change the visibility for a service Enable and disable services within your project overview settings. -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and select a project. -2. Choose **Project settings** in the sidebar. +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```) and select a project. +2. Select **Project settings**. > [!div class="mx-imgBorder"] - > ![Open project settings](../../media/settings/open-project-settings-vert-brn.png) + > ![Screenshot shows Project settings button.](../../media/settings/open-project-settings-vert-brn.png) 3. Select **Overview**, and then choose the slider for the service that you want to enable or disable. > [!div class="mx-imgBorder"] - > ![Project Settings > Overview to services](media/services/set-service-visibility.png) + > ![Screenshot shows Project Settings > Overview to services.](media/services/set-service-visibility.png) 4. Confirm your action. In our example, we remove the Test Plans service. > [!div class="mx-imgBorder"] - > ![Disable a service confirmation dialog](media/services/remove-test-service.png) + > ![Screenshot shows Disable a service confirmation dialog.](media/services/remove-test-service.png) -5. Refresh your web browser to view the updates. +5. To view the updates, refresh your web browser. -The service we disabled is no longer present in the side bar of Azure DevOps. +The service you disabled is no longer present in the side bar of Azure DevOps. ## Related articles ::: moniker range="azure-devops" -- [About projects and scaling the organization](../projects/about-projects.md) -- [About user, team, project, and organization-level settings](about-settings.md) +- [Learn about projects and scaling the organization](../projects/about-projects.md) +- [Learn about user, team, project, and organization-level settings](about-settings.md) - [Change the project visibility, public or private](../projects/make-project-public.md) ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" -- [About projects and scaling the organization](../projects/about-projects.md) -- [About user, team, project, and collection-level settings](about-settings.md) +::: moniker range=" < azure-devops" +- [Learn about projects and scaling the organization](../projects/about-projects.md) +- [Learn about user, team, project, and collection-level settings](about-settings.md) ::: moniker-end diff --git a/docs/organizations/settings/set-working-days.md b/docs/organizations/settings/set-working-days.md deleted file mode 100644 index 6078db0a1a6..00000000000 --- a/docs/organizations/settings/set-working-days.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Set working days off -titleSuffix: Azure DevOps -description: Learn how to choose your team's working days for capacity planning purposes in Azure Boards. -ms.service: azure-devops-boards -ms.custom: teams -ms.assetid: 02771DE7-1AF7-46B1-AE4A-219351C570DC -ms.author: chcomley -author: chcomley -ms.topic: how-to -monikerRange: '<= azure-devops' -ms.date: 04/24/2023 ---- - -# Configure working days - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Learn how to align your team's work hours with your organization's requirements, optimize productivity, and manage workloads effectively by configuring working days in Azure DevOps. - -> [!NOTE] -> The **Working days** setting specifies the days that teams regularly take off each week. To specify additional non-working days off, such as holidays or a team day off, set these through the **Capacity** page as described in [Set sprint capacity, Set capacity for the team and team members](../../boards/sprints/set-capacity.md#set-team-capacity). - -[!INCLUDE [temp](includes/prerequisites-team-settings.md)] - - - -## Set working days - -::: moniker range="azure-devops" - -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). - -2. Choose **Boards** > **Sprints**. - - :::image type="content" source="media/configure-team/azure-boards-sprints-tab-selection.png" alt-text="Screenshot of selection of Azure Boards, and then the Sprints tab, with red boxes."::: - -3. Select **Capacity** > **Settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: > **Working days**. - - ![Screenshot showing selected buttons highlighted with red boxes by sequence for Capacity page, Settings, Working days.](media/capacity-planning-open-team-settings-new-nav.png) - -4. Select the checkbox next to the appropriate working days, and then select **Save and close**. - - Your team's working days are updated. - -::: moniker-end - -::: moniker range="< azure-devops" - -1. From Azure Boards, select **Capacity** > :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: > **Working days**. - - ![Capacity page, Settings, Working days](../../boards/plans/media/capacity-planning-open-team-settings-tfs-15.png) - -2. Select the checkbox next to the appropriate working days, and then select **Save and close**. - - Your team's working days are updated. - -::: moniker-end - -## Related articles - -- [About Sprints, Scrum and project management](../../boards/sprints/scrum-overview.md) -- [Scrum and sprint planning tools](../../boards/sprints/scrum-key-concepts.md) -- [Manage teams and configure team tools](manage-teams.md) diff --git a/docs/organizations/settings/set-your-preferences.md b/docs/organizations/settings/set-your-preferences.md index db550d58461..06fec73740f 100644 --- a/docs/organizations/settings/set-your-preferences.md +++ b/docs/organizations/settings/set-your-preferences.md @@ -1,15 +1,13 @@ --- -title: Set user preferences +title: Set user preferences titleSuffix: Azure DevOps -ms.custom: contperf-fy22q4 -description: Learn how to change a user's picture, preferred email, and other user preferences from the user's Azure DevOps profile. +description: Learn how to change a user's picture, preferred email address, and other user preferences from the user's Azure DevOps profile. ms.subservice: azure-devops-settings -ms.assetid: ms.author: chcomley author: chcomley -ms.topic: quickstart +ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 07/27/2022 +ms.date: 12/19/2024 --- # Set user preferences @@ -18,65 +16,44 @@ ms.date: 07/27/2022 ::: moniker range="azure-devops" -You can set user preferences on the user profile page in Azure DevOps. Changes can include the picture, display name, preferred email, and UI theme. These settings only apply to Azure DevOps. - -> [!TIP] -> - To change the settings for your work or school account, see [Change work or school account settings in the My Account portal](https://support.microsoft.com/account-billing/change-work-or-school-account-settings-in-the-my-account-portal-e50bfccb-58e9-4d42-939c-a60cb6d56ced). -> - You can't change the UI theme if you're using Internet Explorer. For more information about the browsers we support, see [Azure DevOps client compatibility](/azure/devops/server/compatibility?view=azure-devops&preserve-view=true). -> - Language settings apply only to your profile page. - -See the following articles for setting other user preferences: - -- [Change time and locale](../accounts/change-time-zone.md#change-user-profile-time-zone): Change the preferred language, date and time patterns, and time zone. -- [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md): Add or review subscriptions to event changes. -- [Refresh or re-evaluate your permissions](../security/troubleshoot-permissions.md#refresh-permissions): Use to refresh permissions and make any recent changes take effect. -- [Manage preview features](../../project/navigation/preview-features.md): Enable or disable a preview feature for your user account. +You can set user preferences on the user profile page in Azure DevOps. Changes can include the user picture, display name, preferred email address, and UI theme. These settings only apply to Azure DevOps. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - -On the Azure DevOps user profile page, you can change the user picture, display name, preferred email, language, date and time pattern, time zone, and other user interface preferences. - -See the following articles for setting more user preferences: +::: moniker range=" < azure-devops" -- [Use personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md) -- [Use SSH key authentication](../../repos/git/use-ssh-keys-to-authenticate.md) -- [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md) +On the Azure DevOps user profile page, you can change the user picture, display name, preferred email address, language, date and time pattern, time zone, and other user interface preferences. ::: moniker-end -::: moniker range="tfs-2018" +## Set preferences -On your user profile page, you can change your picture, display name, preferred email, language, date and time pattern, time zone, and other user interface preferences. +#### [Current page](#tab/current-page) -Other tools for setting your Azure DevOps preferences include [Notifications](../../organizations/notifications/manage-your-personal-notifications.md) to add or review subscriptions to event changes. - -::: moniker-end -## Set preferences +Do the following steps to set your preferences. ::: moniker range="azure-devops" 1. From the home page, select :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **User settings**, and then select **Profile**. - ![Screenshot to open Azure DevOps profile.](../../media/open-user-settings-profile-preview.png) + ![Screenshot shows buttons to get to Azure DevOps profile.](../../media/open-user-settings-profile-preview.png) -2. From the **Profile** page, you can change the profile picture, display name, contact information, and country/region. Select **Save**. Select the **Time and Locale** tab to change more settings, like language, date and time pattern, time zone, and UI theme. +2. From the **Profile** page, you can change the profile picture, display name, contact email address, and region. Select **Save**. ![Screenshot to choose and edit the Profile page.](media/edit-about-page-preview.png) ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" -1. To change the user preferences, open the user profile menu, and then select **My profile**. +1. Open the user profile menu, and then select **My profile**. :::image type="content" source="media/user-preferences/open-profile-menu-2020.png" alt-text="Screenshot of select the user profile menu, and then My profile."::: 2. From the **General** tab, you can change the following information: - Profile picture - Display name - - Preferred email + - Preferred email address - Whether borders appear for fields on work item forms. :::image type="content" source="media/user-preferences/user-profile-dialog-general-tab.png" alt-text="Screenshot of User Profile dialog, General tab."::: @@ -90,39 +67,53 @@ Other tools for setting your Azure DevOps preferences include [Notifications](.. ::: moniker-end -::: moniker range="tfs-2018" +User profile settings get updated. -1. To change the user preferences, open the user profile menu. +#### [Microsoft Entra profile preview](#tab/preview-page) - ![Screenshot to Open Profile menu for TFS 2018.](../../media/settings/open-profile-tfs-2017.png) + -2. Choose **Edit profile**. +::: moniker range="azure-devops" - > [!div class="mx-imgBorder"] - > ![Screenshot of highlighted Edit profile button.](../../media/settings/profile-jamal-h.png) +We're previewing the ability to use your profile picture, display name, contact email address, and region as configured in Microsoft Entra within Azure DevOps. -3. From the **About** page, you can change the user profile picture, display name, contact information, and country/region. +From the Azure DevOps home page, select :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **User settings**, and then select **Profile**. - > [!div class="mx-imgBorder"] - > ![Screenshot of the About User profile page.](../../media/settings/edit-profile-about-dialog.png) +:::image type="content" source="media/entra-profile-preview.png" alt-text="Screenshot shows Microsoft Entra profile information in the Profile page."::: -4. From the **Preferences** page, you can change the following information: - - preferred language - - date and time pattern - - time zone - - UI theme +If you encounter any issues using Microsoft Entra profile information, let us know! You can [turn it off](../../project/navigation/preview-features.md) and restore your original profile information, and when you do, be sure to share detailed feedback. We review the feedback carefully to address any concerns. - > [!div class="mx-imgBorder"] - > ![Screenshot of Preferences page with Save button highlighted.](../../media/settings/edit-profile-preferences-dialog.png) +:::image type="content" source="media/turn-off-entra-profile-information.png" alt-text="Screenshot shows window for entering feature improvements and feedback for Microsoft Entra profile information."::: + +To receive information, tips, and resources related to Azure DevOps, enter a check in the box and select **Save**. + +User profile settings get updated. + +## FAQs + +See the following frequently asked questions and answers. + +#### Q: How can I change my profile picture in Microsoft Entra? +A: +1. Sign in to your [Microsoft 365 account](https://www.microsoft365.com/). +2. Select the camera icon or **Change Photo**, next to your current profile picture. +3. Upload a new photo from your device and adjust it as needed. +4. **Save** your changes. + +#### Q: Why did I stop getting email notifications from Azure DevOps? + +A: Azure DevOps sends notification emails to the email address configured for your account in Microsoft Entra. If you're not getting notifications, make sure an email address is configured in Microsoft Entra. ::: moniker-end -User profile settings are updated. +[!INCLUDE [temp](../../includes/note-new-teams-not-supported.md)] + +--- ## Related articles -- [Time zone settings and usage](../settings/timezone-settings-usage.md) -- [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md) -- [Usage](../../integrate/concepts/rate-limits.md) -- [Set favorites](../../organizations/notifications/manage-your-personal-notifications.md) -- [Personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md) +- [Set your time zone](../settings/timezone-settings-usage.md) +- [Manage your personal notifications](../../organizations/notifications/manage-your-personal-notifications.md) +- [Understand usage and rate limits](../../integrate/concepts/rate-limits.md) +- [Set your favorites](../../organizations/notifications/manage-your-personal-notifications.md) +- [Use personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md) diff --git a/docs/organizations/settings/show-bugs-on-backlog.md b/docs/organizations/settings/show-bugs-on-backlog.md index 9d31e6fa03e..063d16809b0 100644 --- a/docs/organizations/settings/show-bugs-on-backlog.md +++ b/docs/organizations/settings/show-bugs-on-backlog.md @@ -1,7 +1,7 @@ --- title: Show bugs on backlogs and boards titleSuffix: Azure DevOps -description: Choose how to get bugs and user stories to appear on Agile tools in Azure Boards and Azure DevOps. +description: Choose how to get bugs and user stories to appear on Agile tools in Azure Boards. You can track bugs as requirements or tasks. ms.service: azure-devops-boards ms.custom: teams. engagement-fy23 ms.assetid: 27DCB879-30F6-44F3-998A-755DF66D6E24 @@ -9,127 +9,89 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 03/03/2023 +ms.date: 11/12/2024 +#customer intent: As a team administrator, I want to be able to track code defects as part of the backlog in Azure Boards so the team can track them in the same way as requirements or tasks. --- # Show bugs on backlogs and boards [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -As your team identifies code defects or bugs, they can add them to the backlog and track them similar to tracking requirements. Or, they can schedule bugs to be fixed within a sprint along with other tasks. +As your team identifies code defects or bugs, they can add them to the backlog and track them similar to tracking requirements. You can schedule bugs to be fixed within a sprint along with other tasks. -When you *track bugs as **requirements***, they appear on the product Backlogs and Kanban boards. When you *track bugs as **tasks***, the bugs appear on Sprint Backlogs and Taskboards. For more information about other work item types, see [Add other work item types to backlogs or boards](#add-other-wits). +When you track bugs as *requirements*, they appear on the product Backlogs and boards. When you track bugs as *tasks*, the bugs appear on Sprint Backlogs and Taskboards. For more information about other work item types, see [Add other work item types to backlogs or boards](#add-other-wits). -::: moniker range=">= azure-devops-2019" - -You can define your team's tracking setting for the [Agile](../../boards/work-items/guidance/agile-process.md), [Scrum](../../boards/work-items/guidance/scrum-process.md), and [CMMI](../../boards/work-items/guidance/cmmi-process.md) processes. The Bug work item type isn't defined for the [Basic](../../boards/get-started/plan-track-work.md) process, so there isn't a team setting for Basic. Instead, you should track bugs and code defects using the Issue work item type. -::: moniker-end +You can define your team's tracking setting for the [Agile](../../boards/work-items/guidance/agile-process.md), [Scrum](../../boards/work-items/guidance/scrum-process.md), and [Capability Maturity Model Integration (CMMI)](../../boards/work-items/guidance/cmmi-process.md) processes. The Bug work item type isn't defined for the [Basic](../../boards/get-started/plan-track-work.md) process, so there isn't a team setting for Basic. Instead, you should track bugs and code defects using the Issue work item type. [!INCLUDE [requirements-term](../../boards/includes/note-requirements-terms.md)] -[!INCLUDE [temp](includes/prerequisites-team-settings.md)] +## Prerequisites + +[!INCLUDE [prerequisites](includes/prerequisites-team-settings.md)] ## Choose from options for bug tracking -The following table summarizes the options teams have for tracking bugs. Before you make your choice, we recommend you review the information provided in [Define, capture, triage, and manage bugs](../../boards/backlogs/manage-bugs.md), which provides an overview of the Bug work item type and supported tools for managing bugs. +The following table summarizes the options teams have for tracking bugs. Before you make your choice, we recommend you review the information provided in [Define, capture, triage, and manage bugs](../../boards/backlogs/manage-bugs.md), which provides an overview of the Bug work item type and supported tools for managing bugs. -[!INCLUDE [temp](../../boards/includes/show-bugs-matrix-options.md)] +[!INCLUDE [bug track options](../../boards/includes/show-bugs-matrix-options.md)] -## Set your team's preference for bug tracking +## Set your team preference for bug tracking -You can change settings from a backlog or board view, or from **Project settings** > **Team configuration**. +You can change settings from a backlog or board view, or from **Project settings** > **Team configuration**. -:::image type="content" source="media/working-with-bugs-navigation.png" alt-text="Screenshot showing sequence of navigation selection for working with bugs from project settings."::: +:::image type="content" source="media/working-with-bugs-navigation.png" alt-text="Screenshot showing sequence of navigation selection for working with bugs from project settings." lightbox="media/working-with-bugs-navigation.png"::: -In the following steps, we show how to change it from the board view. - -::: moniker range=">= azure-devops-2019" +The following steps show how to change it from the board view. -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and select your project. -2. [Open your Kanban board](../../boards/boards/kanban-quickstart.md). If you're not a team admin, [get added as one](add-team-administrator.md). Only team and project admins can customize the Kanban board. -3. Choose **Board settings** :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: to configure the board and set general team settings. +1. Sign in to your organization (`https://dev.azure.com/{yourorganization}`) and select your project. +2. [Open your board](../../boards/boards/kanban-quickstart.md). If you're not a team administrator, [get added as one](add-team-administrator.md). Only team and project administrators can customize the board. +3. Choose **Board settings** :::image type="icon" source="../../media/icons/blue-gear.png" border="false"::: to configure the board and set general team settings. - > [!div class="mx-imgBorder"] - > ![Open board settings for a team, vert nav](media/configure-team/open-board-settings.png) + :::image type="content" source="media/configure-team/open-board-settings.png" alt-text="Screenshot shows the Open board settings button for a team."::: 4. Choose **Working with bugs** and then choose the option that best meets your team's way of working. - > [!div class="mx-imgBorder"] - > ![Settings, working with bugs dialog](media/show-bugs-dialog.png) + :::image type="content" source="media/show-bugs-dialog.png" alt-text="Screenshot shows the Settings page with the Working with bugs tabs selected."::: 5. When you're done with your changes, choose **Save**. -6. To see the changes, open or refresh the team's [backlog](../../boards/backlogs/create-your-backlog.md) or [Kanban board](../../boards/boards/kanban-overview.md). - -::: moniker-end - -::: moniker range="tfs-2018" - -1. [Open your Kanban board](../../boards/boards/kanban-quickstart.md). If you're not a team admin, [get added as one](add-team-administrator.md). Only team and project admins can customize the Kanban board. - -2. Choose **Board settings** :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: to open the settings dialog. - - > [!div class="mx-imgBorder"] - > ![Open board settings for a team](media/configure-team/open-settings-tfs.png) - -3. Choose **Working with bugs** and then choose the option that best meets your team's way of working. - - > [!div class="mx-imgBorder"] - > ![Settings, working with bugs dialog](media/show-bugs-dialog.png) +6. To see the changes, open or refresh the team's [backlog](../../boards/backlogs/create-your-backlog.md) or [board](../../boards/boards/kanban-overview.md). -4. When done with your changes, choose **Save**. +## Nest items -5. To see the changes, open or refresh your team's [backlog](../../boards/backlogs/create-your-backlog.md) or [Kanban board](../../boards/boards/kanban-overview.md). - -::: moniker-end - - -## Nest items - -When you manage bugs with requirements or tasks, they appear on one or more of your Agile tool backlogs and boards. However, if you nest items—create parent-child links of items that belong in either the Requirements or Task categories—not all items may appear on your backlogs and boards. To learn more about how nested items are treated, see [How backlogs and boards display hierarchical (nested) items](../../boards/backlogs/resolve-backlog-reorder-issues.md). +When you manage bugs with requirements or tasks, they appear on one or more of your Agile tool backlogs and boards. However, if you nest items, by creating parent-child links of items that belong in either the Requirements or Task categories, not all items can appear on your backlogs and boards. To learn more about how nested items are treated, see [Troubleshoot reordering and nesting issues](../../boards/backlogs/resolve-backlog-reorder-issues.md). > [!TIP] -> If, after refreshing a backlog or board, you don't see bugs where you expect to see them, review [How backlogs and boards display hierarchical (nested) items](../../boards/backlogs/resolve-backlog-reorder-issues.md). Only leaf nodes of nested items appear on the Kanban or task boards. -> - +> If, after refreshing a backlog or board, you don't see bugs where you expect to see them, review [Troubleshoot reordering and nesting issues](../../boards/backlogs/resolve-backlog-reorder-issues.md). Only leaf nodes of nested items appear on the or task boards. +> + ## Add other work item types to your backlogs or boards -Bugs are a common item that teams want to track, and choose how they track them. For more information, see [Manage bugs](../../boards/backlogs/manage-bugs.md). +Bugs are a common item that teams want to track, and choose how they track them. For more information, see [Manage bugs](../../boards/backlogs/manage-bugs.md). -However, what if you want to track other work item types on your backlogs and boards? +However, what if you want to track other work item types on your backlogs and boards? -::: moniker range=">= azure-devops-2019" +You can add other work item types by customizing your process or project, based on the process model that you use. These items include change requests, issues, and impediments. -You can add other work item types—such as change requests, issues, or impediments—by customizing your process or project, based on the process model you use. For details, -- For the Inheritance process model, see [Customize your backlogs or boards for a process](work/customize-process-backlogs-boards.md). +- For the Inheritance process model, see [Customize your backlogs or boards](work/customize-process-backlogs-boards.md). - For Hosted XML and On-premises XML process models, see [Add a work item type to a backlog and board](../../reference/add-wits-to-backlogs-and-boards.md). -::: moniker-end - -::: moniker range="tfs-2018" - -You can add other work item types—such as change requests, issues, or impediments—by customizing your process or project, based on the process model you use. For details, see [Add a work item type to a backlog and board](../../reference/add-wits-to-backlogs-and-boards.md). - -::: moniker-end - For an overview of process models, see [Customize your work tracking experience](../../reference/customize-work.md). -## Create, list, and manage bugs +## Create, list, and manage bugs -Bugs that are managed with requirements can be added through the [product backlog](../../boards/backlogs/create-your-backlog.md) or [Kanban board](../../boards/boards/kanban-quickstart.md). When bugs are managed along with tasks, you can add them to a [sprint backlog or task board](../../boards/sprints/add-tasks.md). Or, capture them using other tools. For more information, see [Define, triage, and manage bugs](../../boards/backlogs/manage-bugs.md). +Bugs that are managed with requirements can be added through the [product backlog](../../boards/backlogs/create-your-backlog.md) or [board](../../boards/boards/kanban-quickstart.md). When bugs are managed along with tasks, you can add them to a [sprint backlog or task board](../../boards/sprints/add-tasks.md). Or, capture them using other tools. For more information, see [Define, triage, and manage bugs](../../boards/backlogs/manage-bugs.md). > [!TIP] -> Effort should automatically be part of a bug, but if you don't see it, customize the bug work item type for it to appear. +> Effort should automatically be part of a bug. If you don't see it, customize the bug work item type for it to appear. -You can review bugs defined for your project by creating a query and specifying the **Work Item Type=Bug**. Or, open a predefined query, **Active Bugs** (Agile and CMMI), or **Work in Progress** (Scrum). +You can review bugs defined for your project by creating a query and specifying the **Work Item Type=Bug**. Or, open a predefined query: **Active Bugs** (Agile and CMMI) or **Work in Progress** (Scrum). ## Related articles - - [Define, capture, triage, and manage bugs](../../boards/backlogs/manage-bugs.md) -- [Enable backlog levels of interest to your team](select-backlog-navigation-levels.md) +- [Select backlog navigation levels for your team](select-backlog-navigation-levels.md) - [Manage teams and configure team tools](manage-teams.md) - [View, run, or email a work item query](../../boards/queries/view-run-query.md) -- [Triage work items](../../boards/queries/triage-work-items.md) - [Query by assignment or workflow changes](../../boards/queries/query-by-workflow-changes.md) diff --git a/docs/organizations/settings/timezone-settings-usage.md b/docs/organizations/settings/timezone-settings-usage.md index 30387ff2fcb..fbe50361c81 100644 --- a/docs/organizations/settings/timezone-settings-usage.md +++ b/docs/organizations/settings/timezone-settings-usage.md @@ -7,7 +7,7 @@ ms.author: chcomley author: chcomley ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 11/17/2021 +ms.date: 02/29/2024 --- # Time zone settings and usage @@ -28,26 +28,15 @@ To configure the time zone settings, see [Change the time zone in Azure DevOps]( ## Organization time zone -The organization time zone setting is the main time zone setting. This setting is used by Azure DevOps to store all date and time data. In other words, when you set your organization to EST, all timestamps are stored in EST time zone. +The organization time zone setting is the time zone setting that's used for data that doesn't specify a time zone. All date and time data is stored in UTC and localized using this setting if the time and date isn't localized using profile settings. In other words, when you set your organization to EST, all timestamps that don't follow client localization appear in EST time zone. -The following objects display time stamps using the organization time zone setting. +Most areas of Azure DevOps localize using your Profile settings, but the following areas don't: -- Boards: Work item fields such as Created Date, Changed Date, and other Date-Time fields -- Repos: - - File History - - Commits, Pushes, Branches, Tags, and Pull Requests -- Pipelines: - - Recent, All, Runs - - Environment - - Releases - - Library - - Task groups -- Notifications -- [Export Users](../security/export-users-audit-log.md) +- Audit TimeStamps are always in UTC. -By default, build pipeline `cron` schedules in YAML are in UTC. In classic pipelines, they are in the organization's time zone. To learn more about configuring your pipeline to run with a `cron` job, see [Configure schedules for pipelines](../../pipelines/process/scheduled-triggers.md). +- Scheduled triggers in code, for example, run with a `cron` job, don't require a time zone to be included. If you don't add a time zone to your trigger, the organization's time zone is used. In classic pipelines, the schedules are in the organization's time zone. For more information about configuring your pipeline to run with a `cron` job, see [Configure schedules for pipelines](../../pipelines/process/scheduled-triggers.md). -If you change the organization time zone, it impacts future time stamps, but doesn't retroactively update existing time stamps. +If you change the organization time zone, it doesn't retroactively update existing time stamps that aren't localized. For example, if your organization is set to UTC and you set up a YAML pipeline with a `cron` job set to 12PM without including EST, this pipeline runs at 5PM EST. If you change the organization's time zone to EST, then this pipeline runs at midnight. If you specify 5PM EST in the code, after the change, it continues to run at 5PM. ## User profile time zone diff --git a/docs/organizations/settings/work/add-custom-field.md b/docs/organizations/settings/work/add-custom-field.md index 65c1733ac0d..3e2b9732873 100644 --- a/docs/organizations/settings/work/add-custom-field.md +++ b/docs/organizations/settings/work/add-custom-field.md @@ -8,50 +8,54 @@ ms.assetid: D6616411-43D4-4A81-8951-772D98BD1569 ms.author: chcomley author: chcomley ms.topic: quickstart -monikerRange: '>= azure-devops-2019' +monikerRange: '<= azure-devops' ms.date: 08/03/2022 --- # Add a custom field to a work item type (Inheritance process) -[!INCLUDE [version-gt-eq-2019](../../../includes/version-gt-eq-2019.md)] +[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] You add a custom field to support tracking data requirements you have that aren't met with the existing set of fields. For example, you can add a custom field to track a customer ticket number. For a list of all fields defined for your organization—which includes all fields defined for system and inherited processes—see [View work item fields and attributes](../../../boards/work-items/work-item-fields.md). For a description of each field defined with a system process, see [Work item field index](../../../boards/work-items/guidance/work-item-field.md). [!INCLUDE [temp](../includes/note-on-prem-link.md)] -To learn more about what you can customize, see [About process customization and inherited processes](inheritance-process-model.md). +For more information, see [About process customization and inherited processes](inheritance-process-model.md). > [!TIP] > To customize a single project, always start by [creating an inherited process and updating your project to that process](manage-process.md). Then, all the customizations that you make to the inherited process automatically appear for the project you migrated. +## Prerequisites + [!INCLUDE [temp](../includes/process-prerequisites.md)] [!INCLUDE [temp](../includes/open-process-admin-context-ts.md)] -[!INCLUDE [temp](../includes/create-inherited-process.md)] +## Create inherited process + +For more information, see [Create inherited process](manage-process.md#create-an-inherited-process). ## Add a field -You always add a field to an existing work item type. +Do the following steps to add a field to an existing work item type. You can't use the **Steps** control on a custom work item type based on the Test Case work item type. -1. From the **Process** page of the selected inherited process, choose the work item type you want to add the custom field to. +1. From the **Process** page of the selected inherited process, choose the work item type you want to add the custom field to. - Here we choose the Bug WIT. Note the breadcrumb links that allow you to move back to the **All Processes** and **MyAgile** process page. + Here we choose the Bug WIT. The breadcrumb links allow you to move back to the **All Processes** and **MyAgile** process page. > [!div class="mx-imgBorder"] > ![All Processes-Process-WIT breadcrumb links](media/field/breadcrumbs-bug-wit.png) - If the New field and other options are disabled, you don't have the necessary permissions to edit the process. See [Set permissions and access for work tracking, Customize an inherited process](../../../organizations/security/set-permissions-access-work-tracking.md#customize-an-inherited-process). + If the **New field** and other options are disabled, you don't have the necessary permissions to edit the process. See [Set permissions and access for work tracking, Customize an inherited process](../../../organizations/security/set-permissions-access-work-tracking.md#customize-an-inherited-process). -1. With the WIT selected, choose the :::image type="icon" source="media/process/new-field-icon.png" border="false"::: New field. +2. With the WIT selected, choose the :::image type="icon" source="media/process/new-field-icon.png" border="false"::: **New field**. > [!div class="mx-imgBorder"] > ![Process Work Item Types page, Add a field to a WIT](media/field/bug-new-field.png) -1. Name the field and select the field type from one of the supported data types. Field names must be unique and no more than 128 characters. For additional restrictions, see [What is a field? How are field names used?](inheritance-process-model.md#field-reference). Optionally, add a Description. +3. Name the field and select the field type from one of the supported data types. Field names must be unique and no more than 128 characters. For additional restrictions, see [What is a field? How are field names used?](inheritance-process-model.md#field-reference). Optionally, add a Description. > [!NOTE] > Once created, you can't change the field name or data type. @@ -63,20 +67,20 @@ You always add a field to an existing work item type. Additional data types you can add include: [Picklist](customize-process-field.md#add-a-picklist), [Identity](customize-process-field.md#add-an-identity-field), [Rich-text, HTML](customize-process-field.md#add-a-rich-text-html-field), and [Checkbox](customize-process-field.md#add-a-checkbox-field). -1. (Optional) On the **Options** tab, indicate if the field is required and specify a default value. Or leave these blank. +4. (Optional) On the **Options** tab, indicate if the field is required and specify a default value. Or leave these blank. Add a field to Use story, specify options By making a field Required, users must specify a value for the field in order to save it. The default value you specify is set when you create a work item as well as every time a work item is opened and the field is empty. -1. (Optional) On the **Layout** tab, you can enter a different form label than the name of the field. Also, you can choose the page and group where the field appears on the form. +5. (Optional) On the **Layout** tab, you can enter a different form label than the name of the field. Also, you can choose the page and group where the field appears on the form. Here, we add the Customer Ticket field to a new group labeled Customer focus. Add a field to Use story, specify layout -1. Choose **Add field** to complete adding the field. If you haven't specified it's layout location, it is added to the first group of fields on the layout form. +6. Choose **Add field** to complete adding the field. If you haven't specified its layout location, it is added to the first group of fields on the layout form. > [!TIP] > Once you've added a field, you can drag-and-drop it within a page to relocate it on the form. If you have several fields you want to add to a custom page or group, then you may want to [add those elements first](customize-process-form.md) and then add your fields. You can't add a field to the gray area within the form where the Assigned To, State, and Reason fields are located. @@ -97,12 +101,9 @@ We recommend that you create a test project and apply your customized inherited > [!div class="mx-imgBorder"] > ![Create a project from the selected process](media/add-custom-field/choose-new-team-project.png) ::: moniker-end - ::: moniker range="azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Create a project from the selected process](media/process/add-new-team-project.png) - ::: moniker-end + -1. The Create new project page opens. Fill out the form. +2. The Create new project page opens. Fill out the form. ::: moniker range="azure-devops" > [!div class="mx-imgBorder"] @@ -112,22 +113,19 @@ We recommend that you create a test project and apply your customized inherited > [!div class="mx-imgBorder"] > ![Create new project form](media/add-custom-field/create-new-project-2020.png) ::: moniker-end - ::: moniker range="azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Create new project form](media/process/create-test-project.png) - ::: moniker-end + -1. Open **Work Items**. (1) Check that you have selected the right project, then (2) choose **Work>Work Items**. +3. Open **Work Items**. (1) Check that you have selected the right project, then (2) choose **Work>Work Items**. > [!div class="mx-imgBorder"] > ![Open Work>Work Items](../../../boards/work-items/media/view-add/open-work-items-agile.png) -1. Select the WIT you customized. Here we choose **Bug**. +4. Select the WIT you customized. Here we choose **Bug**. > [!div class="mx-imgBorder"] > ![Work, Work Items Page, Add New Work Item, Bug](media/process/add-custom-field-verify-bug.png) -1. Verify that the field you added appears on the form. Note that the :::image type="icon" source="../../../media/icons/required-icon.png" border="false"::: (exclamation mark) icon indicates the field is required. +5. Verify that the field you added appears on the form. Note that the :::image type="icon" source="../../../media/icons/required-icon.png" border="false"::: (exclamation mark) icon indicates the field is required. > [!div class="mx-imgBorder"] > ![Bug form, Customer Ticket field added to Customer Focus group](media/process/add-custom-field-verify-bug-form.png) @@ -135,8 +133,7 @@ We recommend that you create a test project and apply your customized inherited [!INCLUDE [temp](../includes/change-project-to-inherited-process.md)] - -## Try this next +## Next steps > [!div class="nextstepaction"] > [Add a custom work item type](add-custom-wit.md) @@ -151,4 +148,3 @@ We recommend that you create a test project and apply your customized inherited - [Add and manage fields for an inherited process](customize-process-field.md#show-hide-field) - [Customize a project using an inherited process](customize-process.md) - [Create and manage inherited processes](manage-process.md) - diff --git a/docs/organizations/settings/work/add-custom-wit.md b/docs/organizations/settings/work/add-custom-wit.md index 402ceceac70..bf5c55cd4ef 100644 --- a/docs/organizations/settings/work/add-custom-wit.md +++ b/docs/organizations/settings/work/add-custom-wit.md @@ -8,7 +8,7 @@ ms.assetid: DBF41880-62A4-43A9-9A31-8DB701EB888E ms.author: chcomley author: chcomley ms.topic: quickstart -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 08/03/2022 --- @@ -27,16 +27,18 @@ For example, you may want to capture customer issues in a custom WIT labeled Tic To learn more about what you can customize, see [About process customization and inherited processes](inheritance-process-model.md). - > [!TIP] > To customize a single project, always start by [creating an inherited process and migrating project(s) to that process](manage-process.md). Then, all the customizations that you make to the inherited process automatically appear for the project you migrated. +## Prerequisites [!INCLUDE [temp](../includes/process-prerequisites.md)] [!INCLUDE [temp](../includes/open-process-admin-context-ts.md)] -[!INCLUDE [temp](../includes/create-inherited-process.md)] +## Create inherited process + +For more information, see [Create inherited process](manage-process.md#create-an-inherited-process). @@ -52,7 +54,7 @@ To learn more about what you can customize, see [About process customization and Choose **Create** to save. - Each new WIT comes predefined with a Details page with the Description field, and Discussion, Development, and Related Work groups. Also added, but not shown nor editable, are the standard elements included with the header of the form as shown in the following image, as well as the history, links, and attachment pages. To learn more, see [About work items](../../../boards/work-items/about-work-items.md). + Each new WIT comes predefined with a Details page with the Description field, and Discussion, Development, and Related Work groups. Also added, but not shown nor editable, are the standard elements included with the header of the form as shown in the following image, as well as the history, links, and attachment pages. For more information, see [About work items](../../../boards/work-items/about-work-items.md). ![WIT header details](media/process/weblayout-system-controls-details-page.png) @@ -82,7 +84,7 @@ To learn more about what you can customize, see [About process customization and ![Add a field to Use story, specify layout](media/process/cpfield-customer-ticket-layout.png) -6. Choose **Add field** to complete adding the field. If you haven't specified it's layout location, it is added to the first group of fields on the layout form. +6. Choose **Add field** to complete adding the field. If you didn't specify its layout location, it gets added to the first group of fields on the layout form. > [!TIP] > Once you've added a field, you can drag-and-drop it within a page to relocate it on the form. If you have several fields you want to add to a custom page or group, then you may want to [add those elements first](customize-process-form.md) and then add your fields. @@ -101,10 +103,7 @@ We recommend that you create a test project and apply your customized inherited > [!div class="mx-imgBorder"] > ![Create a project from the selected process](media/add-custom-field/choose-new-team-project.png) ::: moniker-end - ::: moniker range="azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Create a project from the selected process](media/process/add-new-team-project.png) - ::: moniker-end + 1. The Create new project page opens. Fill out the form. @@ -116,10 +115,7 @@ We recommend that you create a test project and apply your customized inherited > [!div class="mx-imgBorder"] > ![Create new project form](media/add-custom-field/create-new-project-2020.png) ::: moniker-end - ::: moniker range="azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Create new project form](media/process/create-test-project.png) - ::: moniker-end + 2. Open **Work Items**. (1) Check that you have selected the right project, then (2) choose **Work>Work Items**. @@ -138,15 +134,12 @@ We recommend that you create a test project and apply your customized inherited > [!div class="mx-imgBorder"] > ![Ticket form, Customer Ticket field added to Customer Focus group](media/process/add-custom-field-verify-ticket-form.png) - [!INCLUDE [temp](../includes/change-project-to-inherited-process.md)] - ## Q & A [!INCLUDE [temp](includes/qa-custom-work-item-on-backlog.md)] - ## Try this next > [!div class="nextstepaction"] > [Customize the web layout](customize-process-form.md) @@ -155,10 +148,8 @@ We recommend that you create a test project and apply your customized inherited ## Related articles - [!INCLUDE [temp](../includes/note-audit-log-support-process.md)] - - [Customize a project using an inherited process](customize-process.md) - [Create and manage inherited processes](manage-process.md) - [Customize the workflow states](customize-process-workflow.md). @@ -168,7 +159,3 @@ We recommend that you create a test project and apply your customized inherited - - - - diff --git a/docs/organizations/settings/work/apply-rules-to-workflow-states.md b/docs/organizations/settings/work/apply-rules-to-workflow-states.md index 52b222b1198..f4a2942da62 100644 --- a/docs/organizations/settings/work/apply-rules-to-workflow-states.md +++ b/docs/organizations/settings/work/apply-rules-to-workflow-states.md @@ -1,115 +1,83 @@ --- -title: Restrict workflow transitions, apply rules to workflow states +title: Restrict workflow transitions and apply rules to workflow states titleSuffix: Azure DevOps Services -description: Apply rules to workflow states to restrict transitions +description: Learn how to apply rules to workflow states to restrict transitions. ms.custom: inherited-process ms.service: azure-devops-boards ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.topic: tutorial -ms.date: 04/07/2021 +ms.date: 09/11/2024 --- - # Apply rules to workflow states (Inheritance process) [!INCLUDE [version-gt-eq-2019](../../../includes/version-gt-eq-2019.md)] -After you add or modify your workflow states for a work item type, you may want to define one or more rules that are applied depending on the workflow state change. Adding rules to workflow states supports the following scenarios: - +After you add or modify your workflow states for a work item type, define rules that apply based on the workflow state change. Adding rules to workflow states supports the following scenarios: ::: moniker range="azure-devops" - - Support an approval process - Prevent unauthorized users from setting an invalid state -- Make a field required or read-only or other value based on State changes +- Make a field required or read-only or another value based on State changes - Restrict transition from one state to another - Restrict or allow State transitions to specific users or groups -- Maintain a controlled workflow process to support auditing requirements +- Maintain a controlled workflow process, supporting auditing requirements - Automate closure of parent work items ::: moniker-end ::: moniker range=">= azure-devops-2020 < azure-devops" - - Support an approval process - Prevent unauthorized users from setting an invalid state -- Make a field required or read-only or other value based on State changes +- Make a field required or read-only or another value based on State changes - Restrict transition from one state to another - Automate closure of parent work items ::: moniker-end -::: moniker range="azure-devops-2019" - -- Support an approval process -- Make a field required or read-only or other value based on State changes -- Automate closure of parent work items - -::: moniker-end - -Review this article to understand how to define rules that apply when you change a workflow state. - -::: moniker range="azure-devops" - ->[!div class="checklist"] -> - Understand the types of workflow rules -> - Workflow state and rule limits and best practices -> - Set a field value or make a field read-only or required based on State selection -> - Restrict state transitions -> - Restrict or allow State transitions to specific users or groups -> - Automate state transitions of parent work items - -::: moniker-end - -::: moniker range=">= azure-devops-2020 < azure-devops" - ->[!div class="checklist"] -> - Understand the types of workflow rules -> - Workflow state and rule limits and best practices -> - Set a field value or make a field read-only or required based on State selection -> - Restrict state transitions -> - Automate state transitions of parent work items - -::: moniker-end - -::: moniker range="azure-devops-2019" - ->[!div class="checklist"] -> - Understand the types of workflow rules -> - Workflow state and rule limits and best practices -> - Set a field value or make a field read-only or required based on State selection -> - Automate state transitions of parent work items +[!INCLUDE [temp](../includes/note-on-prem-link.md)] -::: moniker-end +## Prerequisites -[!INCLUDE [temp](../includes/note-on-prem-link.md)] +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - To manage security groups and permissions at the project level, which includes setting rules for workflow states: **Project Administrator**.
      - To manage the work tracking area: **Project Administrator** or specifically assigned the **Work Item Tracking** permission. | +| **Access levels** | **Basic** access, which is typically sufficient for most users who need to manage work items and apply rules to workflow states. | -## Workflow rules +## Understand workflow rules ::: moniker range="azure-devops" +The following table outlines the three groups of workflow rules you can define: -The following table indicates the three groups of workflow rules you can define. The first group applies standard actions when a work item is created, in a selected state, or is moved from one state to another. These standard actions set the value of a field or makes a field read-only or required. In this group, you can specify one or two conditions and several actions. +1. **Standard actions:** + - Apply when a work item is created, in a selected state, or moved from one state to another. + - Actions include setting the value of a field, making a field read-only, or making a field required. + - You can specify one or two conditions and several actions. -The second and third groups support restricting state transitions. These two groups allow you to specify one and only one condition indicating the state a work item has moved to. You can then specify one or more actions to restrict the transition from that state to other states. +2. **Restricting state transitions (group 1):** + - Specify one condition indicating the state a work item moved from. + - Define actions to restrict transitions from that state to other states. +3. **Restricting state transitions (group 2):** + - Similar to the first group, specify one condition indicating the state a work item moved from. + - Define actions to restrict transitions from that state to other states. ::: moniker-end ::: moniker range=">= azure-devops-2020 < azure-devops" +The following table outlines the two groups of workflow rules you can define: -The following table indicates the two groups of workflow rules you can define. The first group applies standard actions when a work item is created, in a selected state, or is moved from one state to another. These standard actions set the value of a field or makes a field read-only or required. In this group, you can specify one or two conditions and several actions. - -The second group supports restricting state transitions. In this second group, you can specify one and only one condition indicating the state a work item has moved to. You can then specify one or more actions to restrict the transition from that state to other states. +1. **Standard actions:** + - Apply when a work item is created, in a selected state, or moved from one state to another. + - Actions include setting the value of a field, making a field read-only, or making a field required. + - You can specify one or two conditions and several actions. +2. **Restricting state transitions:** + - Specify one condition indicating the state a work item moved from. + - Define one or more actions to restrict transitions from that state to other states. ::: moniker-end [!INCLUDE [temp](../../../boards/includes/note-azure-devops-2020-1-updates.md)] -::: moniker range="azure-devops-2019" - -Workflow conditions and actions you can set are illustrated in the following images. You can apply standard actions when a work item is created, in a selected state, or is moved from one state to another. These standard actions set the value of a field or make a field read-only or required. For this set of rules you can specify one or two conditions and several actions. - -::: moniker-end - --- :::row::: :::column span="2"::: @@ -190,53 +158,47 @@ Workflow conditions and actions you can set are illustrated in the following ima --- ::: moniker-end - - - [!INCLUDE [temp](../includes/automatic-update-project.md)] -## Workflow state and rule limits +## Understand workflow state and rule limits + +Workflow rules get applied when you add or modify work items through any of the following interfaces: +- **Web portal:** Work item form, bulk updates, updates in query view ​ +- **Web portal:** Board or Taskboard, move work item to column​ +- **Visual Studio 2017** and earlier versions, work item form +- **CSV file format:** Bulk import or update +- **Excel​:** Bulk import or update +- **REST API​:** Add or modify work items The following table summarizes the workflow state and rule limits for the Inheritance process. - |Object|Inheritance limit| |------|-----------------| | Work item types defined for a process | 64 | | Workflow states defined for a work item type | 32 | | Rules defined for a work item type | 1024 | - - -When defining workflow states and rules, we recommend that you consider the following guidance in order to minimize performance issues. -- Minimize the number of rules you define for a WIT. While you can create multiple rules for a WIT, addition rules can negatively impact performance when a user adds and modifies work items. When users save work items, the system validates all rules associated with the fields for its work item type. Under certain conditions, the rule validation expression is too complex for SQL to evaluate. -- Minimize the number of custom WITs you define. - -Workflow rules are applied when adding or modifying work items through any of the following interfaces: -- Web portal: Work item form, bulk updates, updates in query view ​ -- Web portal: Kanban board or Taskboard, move work item to column​ -- Visual Studio 2017 and earlier versions, work item form -- CSV file format: bulk import or update -- Excel​: bulk import or update -- REST API​: add or modify work items +When you define workflow states and rules, follow these guidelines to minimize performance issues: +- **Limit the number of rules for a WIT:** While you can create multiple rules for a work item type (WIT), more rules can negatively affect performance when users add or modify work items. The system validates all rules associated with the fields for the work item type when users save work items. In some cases, the rule validation expression might become too complex for SQL to evaluate. +- **Limit the number of custom work item types:** Reducing the number of custom work item types can help maintain optimal performance. ## Define a rule -Prior to defining a rule based on workflow states, make sure you first define the following elements: -- The workflow states that you want as described in [Customize a workflow](customize-process-workflow.md) -- If your rule requires specification of a custom field, add that field to the work item type as described in [Add and manage fields](customize-process-field.md) -- If your rule requires specification of a security group to grant or restrict changes based on user or group membership, define that security group as described in [Add or remove users or groups, manage security groups](../../security/add-remove-manage-user-group-security-group.md). +Before you define a rule based on workflow states, ensure the following elements are in place: -For the basics of defining rules, see [Add a custom rule](custom-rules.md). You must meet the prerequisites defined in that article. +- **Workflow states:** Define the workflow states as described in [Customize a workflow](customize-process-workflow.md). +- **Custom fields:** If your rule requires a custom field, add it to the work item type as described in [Add and manage fields](customize-process-field.md). +- **Security groups:** If your rule requires a security group to grant or restrict changes that are based on user or group membership, define the security group as described in [Add or remove users or groups, manage security groups](../../security/add-remove-manage-user-group-security-group.md). +For more information about defining rules, see [Add a custom rule](custom-rules.md). ## Set field value or make field read-only or required With the first grouping of rules, you can specify one or two conditions and up to 10 actions per rule. -#### Example of ensuring team lead approval prior to active work +#### Example of ensuring team lead approval before active work -In this example, development teams want to ensure that no User Story is worked on until approved by a team lead. The default workflow states are in use and only a single custom field, *Approved By*, and security group, *Team Leads Group*, are added. +In this example, development teams want to ensure that no User Story gets worked on until approved by a team lead. The default workflow states are used, with the addition of a custom field, *Approved By*, and a security group, *Team Leads Group*. #### Default workflow states @@ -245,18 +207,16 @@ In this example, development teams want to ensure that no User Story is worked o #### Rule requirements -To ensure approval prior to active work, the following rules must be defined: +To ensure approval before active work, define the following rules: -- Require the *Approved By* field be filled in when the State moves from *New* to *Active* -- Restrict users who don't belong to the *Team Leads Group* to fill in the *Approved By* field +- Require the *Approved By* field to be filled in when the State moves from *New* to *Active* +- Restrict users who aren't in the *Team Leads Group* from filling in the *Approved By* field - Clear the *Approved By* field when the State moves to *New* or *Removed* #### Rule definitions The rule requirements translate to the following four rule definitions. -    - --- :::row::: :::column span=""::: @@ -315,14 +275,13 @@ The rule requirements translate to the following four rule definitions. :::column-end::: :::row-end::: ---- - +--- ::: moniker range=">= azure-devops-2020" ## Restrict state transitions -When specifying the condition, `A work item state moved from ...`, you can specify only that condition. You can specify up to 10 actions. +When you specify the condition, `A work item state moved from ...`, you can specify only that condition. You can specify up to 10 actions. ::: moniker-end ::: moniker range="azure-devops-2020" > [!NOTE] @@ -333,7 +292,7 @@ When specifying the condition, `A work item state moved from ...`, you can speci #### Example of restricting state transitions and Approved state -In keeping with the terminology used by a business group, the following workflow states are defined for the User Story. The *New*, *Resolved*, and *Removed* inherited states are hidden. Instead, *Proposed*, *In Review*, and *Cut* States are used. In addition, three additional States are defined: *Investigate*, *Design*, and *Approved*. These States should follow the sequence as shown in the following image. +The following workflow states are defined for the User Story. The *New*, *Resolved*, and *Removed* inherited states are hidden. Instead, *Proposed*, *In Review*, and *Cut* States are used. In addition, three more States are defined: *Investigate*, *Design*, and *Approved*. These States should follow the sequence as shown in the following image. > [!div class="mx-imgBorder"] > ![User Story, workflow states](media/customize-workflow/user-story-states-renamed.png) @@ -342,32 +301,32 @@ Without any restrictions, users can move from one State to any other State, both #### Rule requirements -To support a more controlled workflow, the business group decided to institute rules that would support the following forward and reverse state transitions on the User Story work item type. +To support a more controlled workflow, the business group decided to institute rules that support the following forward and reverse state transitions on the User Story work item type. -- *Proposed* can only move to *Research* and *Cut* -- *Research* can only move to *Design* and *Cut* -- *Design* can only move to *Research*, *Approved*, and *Cut* -- *Approved* can only move to *Design*, *Active*, and *Cut* -- *Active* can only move to *In Review* -- *In Review* can only move to *Active* (Additional work found), *Closed* or *Cut* -- *Closed* can move to *Research*, *Design*, *Active*, *In Review* (Allows for cases where user closed the work item in error) -- *Cut* can only move to *Proposed*. +|State |Transition rule | +|---------|---------| +|Proposed | Can only move to *Research* and *Cut* | +|Research | Can only move to *Design* and *Cut* | +|Design | Can only move to *Research*, *Approved*, and *Cut* | +|Approved | Can only move to *Design*, *Active*, and *Cut* | +|Active | Can only move to *In Review* | +|In Review | Can only move to *Active* (More work found), *Closed* or *Cut* | +|Closed | Can move to *Research*, *Design*, *Active*, *In Review* (Allows for cases where user closed the work item in error) | +|Cut | can only move to *Proposed* | > [!NOTE] -> When restricting state transitions, consider those cases where a user moves a state in error. You want users to be able to recover gracefully. +> When you restrict state transitions, account for cases where a user might move a state in error. Ensure users can recover gracefully. -Additionally, the business group wants to apply rules for required fields: +Additionally, the business group wants to apply the following rules for required fields: -- Require the *Approved By* field be filled in when the State moves from Approved to Active -- Only allow users who belong to the Authorized Approvers group to fill in the *Approved By* field -- Clear the *Approved By* field when the State moves to *Cut* -- Require the *Acceptance Criteria* is filled in when the State moves to *Active* +- Require the *Approved By* field to be filled in when the state moves from *Approved* to *Active*. +- Allow only users in the *Authorized Approvers* group to fill in the *Approved By* field. +- Clear the *Approved By* field when the state moves to *Cut*. +- Require the *Acceptance Criteria* field to be filled in when the state moves to *Active*. #### Rule definitions -To implement the above restrictions, the process administrator adds a custom *Approved By* identity field, an *Authorized Approvers* security group, and the following eleven rules. - -    +To implement the previously mentioned restrictions, the process administrator adds a custom *Approved By* identity field, an *Authorized Approvers* security group, and the following rules. --- :::row::: @@ -537,9 +496,9 @@ To implement the above restrictions, the process administrator adds a custom *Ap #### Verify state transition restrictions -Once the rules are defined for the process and the project updated with the process, refresh your browser and check the operations through the work item form and from the Kanban browser. +Once you define the rules for the process and update the project, refresh your browser. Verify the operations through the work item form and the browser. -For the rules defined in the previous table, you should see the following State drop-down menus. Open the Kanban board and check the ability to move from one State to another. +For the rules defined in the previous table, check the State drop-down menus. Open the board and ensure you can move from one state to another. |**Proposed**|**Research**|**Design**|**Approved**| |:----------:|:----------:|:--------:|:--------:| @@ -553,48 +512,34 @@ For the rules defined in the previous table, you should see the following State ## Restrict state transition based on user or group membership -When specifying one of the two conditions based on user or group membership, `Current user is member of group ...` or `Current user is not member of group ...`, you can specify only one condition. Also, if specifying the action `Restrict the transition to state...`, you can only specify one action. - +When you specify one of the two conditions based on user or group membership, `Current user is member of group ...` or `Current user is not member of group ...`, you can only specify one condition. Additionally, if you specify the action `Restrict the transition to state...`, you can only specify one action. [!INCLUDE [temp](../../../boards/includes/note-work-item-caching-rules-simple.md)] - ::: moniker-end ## Automate state transitions of parent work items -To automate State transitions of parent work items based on the State assignments made to their child work items, you can add a web hook and use the code and configuration provided in the [Automate State Transitions](https://github.com/microsoft/azure-boards-automate-state-transitions) GitHub project. - -> [!NOTE] -> The [Automate State Transitions](https://github.com/microsoft/azure-boards-automate-state-transitions) GitHub project is not a supported feature of Azure Boards and therefore not supported by the product team. For questions, suggestions, or issues you have when using these extensions, raise them in the GitHub project page. - - - +To automate State transitions for parent work items that are based on the State assignments of their child work items, see [Automate work item state transitions](../../../boards/backlogs/automate-work-item-state-transitions.md). + ::: moniker range=">= azure-devops-2020" ## Automate reassignment based on state change -The Agile process bug work item type previously had a rule which reassigned the bug to the person who created it. This rule has been removed from the default system process. You can reinstate the rule or add a similar rule to other work item types using the following condition and action: +The Agile process bug work item type previously had a rule that reassigned the bug to its creator. We removed this rule from the default system process. You can reinstate the rule or add a similar rule to other work item types using the following condition and action: **When** `A work item state changes to` *Resolved* **Then** `Copy the value from `*Created By* **to** *Assigned To*. ::: moniker-end - - ## Related articles -[!INCLUDE [temp](../includes/note-audit-log-support-process.md)] - -- [Customize a workflow](customize-process-workflow.md) - [Add a custom rule](custom-rules.md) - [Work item form caching](troubleshoot-work-item-form-caching-issues.md) - - +- [Access, export, and filter audit logs](../../audit/azure-devops-auditing.md) +- [Customize a workflow](customize-process-workflow.md) diff --git a/docs/organizations/settings/work/change-process-agile-to-scrum.md b/docs/organizations/settings/work/change-process-agile-to-scrum.md index d285c2519ff..eb1b63440d4 100644 --- a/docs/organizations/settings/work/change-process-agile-to-scrum.md +++ b/docs/organizations/settings/work/change-process-agile-to-scrum.md @@ -1,7 +1,6 @@ --- title: Change process from Agile to Scrum titleSuffix: Azure Boards -ms.custom: seodec18 description: Change the process for your project from Agile to Scrum ms.topic: how-to ms.service: azure-devops-boards @@ -37,11 +36,13 @@ Reasons you might want to change your process from Agile to Scrum: [!INCLUDE [temp](../includes/change-process-manual-steps.md)] +## Prerequisites + [!INCLUDE [temp](../includes/prerequisites-change-process.md)] [!INCLUDE [temp](../includes/open-process-admin-context-ts-plus-2020.md)] - + ## Create and customize a Scrum inherited process @@ -90,20 +91,17 @@ The first step is to create an inherited process that you can customize. The def > ![Step 3 of 3 of change process dialog](media/agile-to-scrum/change-process-agile-to-scrum-wizard-complete.png) Steps to manually update your work items and board settings: -- Update the column to state mapping for each team Kanban board +- Update the column to state mapping for each team board - Update existing work items using the work item types set by the target process - Update existing work items using the correct state model of the target process. -## Update Kanban board column-to-state settings - -You can customize Kanban boards to display intermediate columns. For each column added, you must choose a valid workflow state for the work item types displayed on the board. To learn more, see [Workflow states & state categories](../../../boards/work-items/workflow-and-state-categories.md). +## Update board column-to-state settings -1. For each team, [open your Kanban board](../../../boards/get-started/plan-track-work.md). +You can customize boards to display intermediate columns. For each column added, you must choose a valid workflow state for the work item types displayed on the board. For more information, see [Workflow states & state categories](../../../boards/work-items/workflow-and-state-categories.md). - > [!div class="mx-imgBorder"] - > ![Open team Kanban board](media/agile-to-scrum/open-kanban-board.png) +1. For each team, [open your board](../../../boards/get-started/plan-track-work.md). -1. Choose the **Correct this now** link or the :::image type="icon" source="../../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board settings. +2. Choose the **Correct this now** link or the :::image type="icon" source="../../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board settings. The Settings dialog opens. Those tabs that display a :::image type="icon" source="../../../media/icons/required-icon.png" border="false"::: required icon need correction. @@ -113,7 +111,7 @@ You can customize Kanban boards to display intermediate columns. For each column Rename each column and choose the correct state for each column so that the column-to-state mapping is correct. As needed, add one or more columns. When done, choose **Save and close**. > [!div class="mx-imgBorder"] - > ![Kanban board fixed.](media/agile-to-scrum/board-column-settings-fixed.png) + > ![Board fixed.](media/agile-to-scrum/board-column-settings-fixed.png) ## Update work items @@ -179,7 +177,7 @@ Your next step is to bulk update work items. The recommended sequence is: > [!div class="mx-imgBorder"] > ![View team board](media/agile-to-scrum/verify-boards.png) - To add columns or change column names, see [Add columns to your Kanban board](../../../boards/boards/add-columns.md). + To add columns or change column names, see [Add columns to your board](../../../boards/boards/add-columns.md). ## Optional updates @@ -192,8 +190,8 @@ After changing the process, you may want to make additional updates as follows: ## Related articles - [Bulk modify work items](../../../boards/backlogs/bulk-modify-work-items.md) -- [Change the process used by a project](./manage-process.md#change-the-process-used-by-a-project) -- [Create an inherited process](./manage-process.md#create-an-inherited-process) +- [Change the process used by a project](./manage-process.md#migrate) +- [Create an inherited process](manage-process.md#create-an-inherited-process) - [Add and manage work item types](./customize-process-work-item-type.md) - [Show bugs on backlogs and boards](../show-bugs-on-backlog.md) - [Customize your boards](../../../boards/configure-customize.md) diff --git a/docs/organizations/settings/work/change-process-basic-to-agile.md b/docs/organizations/settings/work/change-process-basic-to-agile.md index 7ff37ea8136..a20faee9a07 100644 --- a/docs/organizations/settings/work/change-process-basic-to-agile.md +++ b/docs/organizations/settings/work/change-process-basic-to-agile.md @@ -1,177 +1,165 @@ --- -title: Change process from Basic to Agile +title: Change project process from Basic to Agile titleSuffix: Azure Boards -ms.custom: seodec18 -description: Change the process for your project from Basic to Agile +description: Steps to change the process for your project from Basic to Agile. ms.service: azure-devops-boards ms.topic: how-to -ms.assetid: ms.author: chcomley author: chcomley ms.reviewer: dahellem monikerRange: ">= azure-devops-2020" -ms.date: 07/17/2020 +ms.date: 07/16/2024 --- # Change a project process from Basic to Agile [!INCLUDE [version-gt-eq-2020](../../../includes/version-gt-eq-2020.md)] -You can change a project based on the Basic process to use an inherited Agile process. This article provides the steps needed to make this change. +If you want to switch from the Basic process to an inherited Agile process for your project, follow the steps in this article. -Prior to making this change, we recommend you familiarize yourself with the process you are changing to. The Task and Epic work item types are the same for both Basic and Agile processes. Most State and Reason field values, however, are different. +Before you change your process, you should learn about the new process you're switching to. The Basic and Agile processes have the same Task and Epic work item types, but most of the values for the State and Reason fields are different. |  Process | Work item types | Workflow | |------|---------|---------| |**Basic** | ![Basic work item types](../../../boards/get-started/media/about-boards/basic-process-epics-issues-tasks-2.png)|![basic workflow](../../../boards/get-started/media/track-issues/basic-process-workflow.png)| |**Agile** | ![Agile work item types](media/scrum-to-agile/agile-process-plan-wits.png)|![Agile workflow](../../../boards/get-started/media/about-boards/agile-process-workflow.png)| -For more information, see [About processes and process templates](../../../boards/work-items/guidance/choose-process.md). - -Reasons you might want to change your process from Basic to Agile: +Let's break down some of the benefits of transitioning your process from Basic to Agile: -- You want to track code defects using bugs separate from issues and user stories -- You want to use the Agile workflow states in place of those defined for the Basic process -- You want access to both Feature and Epic portfolio backlogs to organize your work items -- Your organization is requiring everyone to standardize their tracking with a customized inherited process based on the Agile process. +- **Separate bug tracking:** In the Agile process, you can create separate work items specifically for tracking code defects (bugs). This action allows you to manage them independently from other work items like issues and user stories. +- **Agile workflow states:** Unlike the Basic process, Agile introduces different workflow states. These states align with Agile principles and help you manage work items more effectively. For example, you have states like "To Do," "In Progress," "Done," and others. +- **Portfolio backlogs:** Agile provides access to both Feature and Epic portfolio backlogs. These backlogs allow you to organize and prioritize work items at a higher level, making it easier to plan and manage your project. +- **Customized inherited process:** If your organization requires a customized process based on Agile principles, transitioning to Agile ensures compliance. You can tailor the process to your team’s specific needs while still following Agile practices. -[!INCLUDE [temp](../includes/change-process-manual-steps.md)] +For more information, see [About processes and process templates](../../../boards/work-items/guidance/choose-process.md). +## Prerequisites + [!INCLUDE [temp](../includes/prerequisites-change-process.md)] -[!INCLUDE [temp](../includes/open-process-admin-context-ts-plus-2020.md)] +[!INCLUDE [image-differences](../../../includes/image-differences.md)] ## Change the process -1. Choose the process that contains the project you want to change. To change from Basic to Agile, choose **Basic**. +:::moniker range="azure-devops" - > [!div class="mx-imgBorder"] - > ![Choose the Basic process](media/change-process/choose-basic-process.png) +1. Sign in to your organization: ```https://dev.azure.com/{Your_Organization}```. -1. Choose **Projects**. +1. Select :::image type="icon" source="../../../media/icons/gear-icon.png" border="false"::: **Organization settings**. - > [!div class="mx-imgBorder"] - > ![Choose Projects tab](media/change-process/choose-basic-process-projects.png) + :::image type="content" source="../../../media/open-organization-settings.png" alt-text="Screenshot of highlighted Organization settings button."::: -1. For the project you want to change, choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon and select **Change process** and follow the steps in the wizard. +2. Select **Process**, and then choose **Basic**. - > [!div class="mx-imgBorder"] - > ![Choose Change process](media/change-process/change-process-basic-to-agile.png) + :::image type="content" source="../../../media/settings/open-process-page-basic.png" alt-text="Screenshot of highlighted Process tab."::: -1. Choose the Agile process that you want to change to and then choose **Save**. You can select the system Agile process or an inherited Agile process. +3. Select **Projects**. - > [!div class="mx-imgBorder"] - > ![Step 1 of 3 of change process dialog, Choose the process](media/change-process/change-process-basic-to-agile-wizard-choose-agile.png) + :::image type="content" source="media/change-process/choose-basic-process-projects.png" alt-text="Screenshot of highlighted Projects tab."::: -1. Upon completion, the wizard displays the following information. Make a note of the steps to follow and then choose **Close**. +4. For the project you want to change, select the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon and select **Change process** and follow the steps in the wizard. - > [!div class="mx-imgBorder"] - > ![Step 3 of 3 of change process dialog](media/change-process/change-process-basic-to-agile-wizard-choose-agile-complete.png) + :::image type="content" source="media/change-process/change-process-basic-to-agile.png" alt-text="Screenshot of highlighted Change process selection."::: -Steps to manually update your work items and board settings: -- Update the column to state mapping for each team Kanban board -- Update existing work items using the work item types set by the target process -- Update existing work items using the correct state model of the target process. +5. Choose **Agile** from the dropdown menu, and then select **Save**. -## Update Kanban board column-to-state settings + :::image type="content" source="media/change-process/change-process-basic-to-agile-wizard-choose-agile.png" alt-text="Screenshot of Agile process selection."::: -You can customize Kanban boards to display intermediate columns. For each column added, you must choose a valid workflow state for the work item types displayed on the board. To learn more, see [Workflow states & state categories](../../../boards/work-items/workflow-and-state-categories.md). + The wizard displays the following information. Notice the steps to manually update your work items and board settings and **Close** the window. -1. For each team, [open your Kanban board](../../../boards/get-started/plan-track-work.md). + :::image type="content" source="media/change-process/change-process-basic-to-agile-wizard-choose-agile-complete.png" alt-text="Screenshot of completion page."::: - > [!div class="mx-imgBorder"] - > ![Open team Kanban board](media/change-process/open-kanban-board.png) +6. (Optional) If you had existing work items, manually update work items and board settings. + 1. Update the column to state mapping for each team board. + 2. Update existing work items using the work item types set by the target process. + 3. Update existing work items using the correct state model of the target process. +::: moniker-end -1. Choose the **Correct this now** link or the :::image type="icon" source="../../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board settings. +:::moniker range="< azure-devops" - The Settings dialog opens. Those tabs that display a :::image type="icon" source="../../../media/icons/required-icon.png" border="false"::: required icon need correction. +1. Sign in to your collection. - > [!div class="mx-imgBorder"] - > ![Columns dialog](media/change-process/kanban-stories-column-settings-to-correct.png) +2. Select :::image type="icon" source="../../../media/icons/gear-icon.png" border="false"::: **Collection settings** > **Process** > **Basic** > **Projects**. - Rename each column and choose the correct state for each column so that the column-to-state mapping is correct. As needed, add one or more columns. When done, choose **Save and close**. +3. For the project you want to change, select the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon and select **Change process** and follow the steps in the wizard. - > [!div class="mx-imgBorder"] - > ![Columns dialog, corrected](media/change-process/kanban-stories-column-settings-corrected.png) + :::image type="content" source="media/change-process/change-process-basic-to-agile.png" alt-text="Screenshot of highlighted Change process selection."::: +4. Choose **Agile** from the dropdown menu, and then select **Save**. -## Update work items + :::image type="content" source="media/change-process/change-process-basic-to-agile-wizard-choose-agile.png" alt-text="Screenshot of Agile process selection."::: -Your next step is to bulk update work items. The recommended sequence is: + The wizard displays the following information. Notice the steps to manually update your work items and board settings and **Close** the window. -- Create a work item query that displays all work items -- Perform a bulk update to change the work item type of Issue work items to User Story -- Perform a bulk update on all States to change from Basic states—To Do, Doing, and Done—to Agile process states—New, Active, and Closed. + :::image type="content" source="media/change-process/change-process-basic-to-agile-wizard-choose-agile-complete.png" alt-text="Screenshot of completion page."::: -1. [Create a query](../../../boards/queries/using-queries.md) to get a list of all Issues, Tasks, and Epics. +5. (Optional) If you had existing work items, manually update work items and board settings. + 1. Update the column to state mapping for each team board. + 2. Update existing work items using the work item types set by the target process. + 3. Update existing work items using the correct state model of the target process. + +:::moniker-end - > [!div class="mx-imgBorder"] - > ![Query all items](media/change-process/query-basic-items.png) +## Update board column-to-state settings -1. Choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon and then select **Column options**. Choose to show the State and Reason fields. Choose the **Sort** tab, and set it to sort the list by work item type and state value. +You can customize boards to display intermediate columns. For each column added, you must choose a valid workflow state for the work item types displayed on the board. For more information, see [Workflow states & state categories](../../../boards/work-items/workflow-and-state-categories.md). - > [!div class="mx-imgBorder"] - > ![Column options dialog, sort tab](media/change-process/query-column-sort.png) +1. For each team, [open your board](../../../boards/get-started/plan-track-work.md), and then select **Correct this now** or select the :::image type="icon" source="../../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board settings. -1. Choose **Results** to just show the list of work items. + The Settings dialog opens. Those tabs that display a :::image type="icon" source="../../../media/icons/required-icon.png" border="false"::: required icon need correction. -1. Highlight all Issues, choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon, select **Change type**, and change the type to User Story. + :::image type="content" source="media/change-process/kanban-stories-column-settings-to-correct.png" alt-text="Screenshot of Column dialog with settings to correct."::: - > [!div class="mx-imgBorder"] - > ![Change type dialog](media/change-process/change-type-to-user-story.png) +2. Rename each column and choose the correct state for each column so that the column-to-state mapping is correct. As needed, add one or more columns. **Save** your work. For more information, see [Manage columns on your board.](../../../boards/boards/add-columns.md) - For more details, see [Move, change, or delete work items, Change the work item type](../../../boards/backlogs/move-change-type.md#change-type). +## Update work items - Choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon and select **Save items**. +1. [Create a query](../../../boards/queries/using-queries.md) to get a list of all Issues, Tasks, and Epics. - It's possible that you will receive errors where the work item type and the state are mismatched. In that case, you can't save your changes until you update the state as described in the next step. + :::image type="content" source="media/change-process/query-basic-items.png" alt-text="Screenshot of querying all items."::: - > [!div class="mx-imgBorder"] - > ![Error state of changed work item type](media/change-process/error-mismatch-type-state.png) +2. Edit your columns to be sure you show the State and Reason fields. Select the **Sorting** tab, and then set it to sort the list by work item type and state value. -1. Sort the work items by the State column, highlight all work items of the same State, such as Doing, choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon, and then select **Edit**. Add the State field and select Active for the value. For details, see [Bulk edit work items](../../../boards/backlogs/bulk-modify-work-items.md). + :::image type="content" source="media/change-process/query-column-sort.png" alt-text="Screenshot of column options dialog, sort tab."::: - > [!div class="mx-imgBorder"] - > ![Edit work item dialog](media/change-process/edit-doing-work-item-state.png) + For more information, see [Bulk add and modify work items in Excel](../../../boards/boards/add-columns.md). -1. Choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon and select **Save items**. +3. Select **Results** to show the list of work items. -1. Repeat these steps for the Done state, changing to Closed; and the To Do state, changing to New. +4. Highlight all Issues, choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon, select **Change type**, and change the type to User Story and **Save**. -1. When done, make sure you save all your changes. Choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon and select **Save items**. + :::image type="content" source="media/change-process/change-type-to-user-story.png" alt-text="Screenshot of the Change type dialog."::: + You might receive errors where the work item type and the state are mismatched. In that case, you can't save your changes until you update the state, which is described in the next step. -## Verify your changes + :::image type="content" source="media/change-process/edit-doing-work-item-state.png" alt-text="Screenshot showing error state of changed work item type."::: -1. Go to your team backlog and review the user stories. +5. Sort the work items by the State column, highlight all work items of the same State, such as Doing, choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon, and then select **Edit**. Add the State field and select Active for the value. For more information, see [Bulk edit work items](../../../boards/backlogs/bulk-modify-work-items.md). + + :::image type="content" source="media/change-process/edit-doing-work-item-state.png" alt-text="Screenshot of editing a work item state."::: - > [!div class="mx-imgBorder"] - > ![View team backlog](media/change-process/backlog-basic-to-agile.png) +6. Repeat these steps for the Done state, changing it to Closed; and the To Do state, changing it to New. - If you want to change any user stories to bugs, do that now using bulk update and **Change type**. If you want to show bugs at the same level as user stories, then make that change now. For details, see [Show bugs on backlogs and boards](../show-bugs-on-backlog.md). +7. **Save** your changes. -1. Go to your team board and verify that the column settings are valid. +## Verify your changes - > [!div class="mx-imgBorder"] - > ![View team board](media/change-process/board-user-story.png) +1. Go to your team backlog and review the user stories. - To add columns or change column names, see [Add columns to your Kanban board](../../../boards/boards/add-columns.md). + :::image type="content" source="media/change-process/backlog-basic-to-agile.png" alt-text="Screenshot of team backlog."::: -## Optional updates + To change any user stories to bugs, do so now using [bulk update](../../../boards/boards/add-columns.md) and update the **Change type**. If you want to show bugs at the same level as user stories, make that change now. For more information, see [Show bugs on backlogs and boards](../show-bugs-on-backlog.md). -After changing the process, you may want to make additional updates as follows: +2. Go to your team board and verify that the column settings are valid. -- [Change the project name](../../../organizations/projects/rename-project.md) -- [Update your project summary or vision](../../../organizations/projects/project-vision-status.md) + :::image type="content" source="media/change-process/board-user-story.png" alt-text="Screenshot of board columns."::: ## Related articles -- [Bulk modify work items](../../../boards/backlogs/bulk-modify-work-items.md) -- [Change the process used by a project](./manage-process.md#change-the-process-used-by-a-project) +- [Modify work items in bulk](../../../boards/backlogs/bulk-modify-work-items.md) - [Create an inherited process](./manage-process.md#create-an-inherited-process) - [Add and manage work item types](./customize-process-work-item-type.md) - [Show bugs on backlogs and boards](../show-bugs-on-backlog.md) -- [Customize your boards](../../../boards/configure-customize.md) - [Create and saved managed queries with the query editor](../../../boards/queries/using-queries.md) diff --git a/docs/organizations/settings/work/change-process-from-hosted-to-inherited.md b/docs/organizations/settings/work/change-process-from-hosted-to-inherited.md index 4d987319ed1..61c33c0c930 100644 --- a/docs/organizations/settings/work/change-process-from-hosted-to-inherited.md +++ b/docs/organizations/settings/work/change-process-from-hosted-to-inherited.md @@ -22,12 +22,13 @@ Once you've [cloned your Hosted XML process to an inherited process](upgrade-hos ## Prerequisites -- You must be a member of the Project Administrators group for the project you want to change, or a member of the Project Collection Administrators group. +[!INCLUDE [prerequisites-change-process](../includes/prerequisites-change-process.md)] [!INCLUDE [temp](../includes/open-process-admin-context-ts-only.md)] + ## Change the project process to an inherited process After you've verified your customizations, you can now apply the inherited process to your existing project. diff --git a/docs/organizations/settings/work/change-process-scrum-to-agile.md b/docs/organizations/settings/work/change-process-scrum-to-agile.md index 03dbfddf7e0..f1201c65337 100644 --- a/docs/organizations/settings/work/change-process-scrum-to-agile.md +++ b/docs/organizations/settings/work/change-process-scrum-to-agile.md @@ -1,11 +1,9 @@ --- title: Change process from Scrum to Agile titleSuffix: Azure Boards -ms.custom: seodec18 description: Change the process for your project from Scrum to Agile ms.service: azure-devops-boards ms.topic: how-to -ms.assetid: ms.author: chcomley author: chcomley ms.reviewer: dahellem @@ -38,11 +36,13 @@ Reasons you might want to change your process from Scrum to Agile: [!INCLUDE [temp](../includes/change-process-manual-steps.md)] +## Prerequisites + [!INCLUDE [temp](../includes/prerequisites-change-process.md)] [!INCLUDE [temp](../includes/open-process-admin-context-ts-plus-2020.md)] - + ## Create and customize an Agile inherited process @@ -89,20 +89,17 @@ Reasons you might want to change your process from Scrum to Agile: > ![Step 3 of 3 of change process dialog](media/scrum-to-agile/change-process-scrum-to-agile-wizard-complete.png) Steps to manually update your work items and board settings: -- Update the column to state mapping for each team Kanban board +- Update the column to state mapping for each team board - Update existing work items using the work item types set by the target process - Update existing work items using the correct state model of the target process. -## Update Kanban board column-to-state settings - -You can customize Kanban boards to display intermediate columns. For each column added, you must choose a valid workflow state for the work item types displayed on the board. To learn more, see [Workflow states & state categories](../../../boards/work-items/workflow-and-state-categories.md). +## Update board column-to-state settings -1. For each team, [open your Kanban board](../../../boards/get-started/plan-track-work.md). +You can customize boards to display intermediate columns. For each column added, you must choose a valid workflow state for the work item types displayed on the board. For more information, see [Workflow states & state categories](../../../boards/work-items/workflow-and-state-categories.md). - > [!div class="mx-imgBorder"] - > ![Open team Kanban board](media/scrum-to-agile/open-kanban-board.png) +1. For each team, [open your board](../../../boards/get-started/plan-track-work.md). -1. Choose the **Correct this now** link or the :::image type="icon" source="../../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board settings. +2. Choose the **Correct this now** link or the :::image type="icon" source="../../../media/icons/blue-gear.png" border="false"::: gear icon to configure the board settings. The Settings dialog opens. Those tabs that display a :::image type="icon" source="../../../media/icons/required-icon.png" border="false"::: required icon need correction. @@ -112,7 +109,7 @@ You can customize Kanban boards to display intermediate columns. For each column Rename each column and choose the correct state for each column so that the column-to-state mapping is correct. As needed, add one or more columns. When done, choose **Save and close**. > [!div class="mx-imgBorder"] - > ![Kanban board fixed.](media/scrum-to-agile/column-settings-fixed.png) + > ![Board fixed.](media/scrum-to-agile/column-settings-fixed.png) ## Update work items @@ -178,7 +175,7 @@ Your next step is to bulk update work items. The recommended sequence is: > [!div class="mx-imgBorder"] > ![View team board](media/scrum-to-agile/verify-boards.png) - To add columns or change column names, see [Add columns to your Kanban board](../../../boards/boards/add-columns.md). + To add columns or change column names, see [Add columns to your board](../../../boards/boards/add-columns.md). ## Optional updates @@ -191,9 +188,9 @@ After changing the process, you may want to make additional updates as follows: ## Related articles - [Bulk modify work items](../../../boards/backlogs/bulk-modify-work-items.md) -- [Change the process used by a project](./manage-process.md#change-the-process-used-by-a-project) -- [Create an inherited process](./manage-process.md#create-an-inherited-process) -- [Add and manage work item types](./customize-process-work-item-type.md) +- [Change the process used by a project](manage-process.md#migrate) +- [Create an inherited process](manage-process.md#create-an-inherited-process) +- [Add and manage work item types](customize-process-work-item-type.md) - [Show bugs on backlogs and boards](../show-bugs-on-backlog.md) - [Customize your boards](../../../boards/configure-customize.md) - [Create and saved managed queries with the query editor](../../../boards/queries/using-queries.md) diff --git a/docs/organizations/settings/work/custom-controls-process.md b/docs/organizations/settings/work/custom-controls-process.md index 931fdef9bc1..13c62177d18 100644 --- a/docs/organizations/settings/work/custom-controls-process.md +++ b/docs/organizations/settings/work/custom-controls-process.md @@ -8,7 +8,7 @@ ms.assetid: 7FC3CF0F-1E2B-4AAE-876C-5E358E7B2B72 ms.author: chcomley author: chcomley ms.topic: how-to -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 11/19/2018 --- @@ -31,15 +31,16 @@ For example, you can add the [**Who recently viewed a work item?** extension](ht ![Work item form, group extension example, Who viewed this](media/process/custom-controls-group-extension-example-who-recently-viewed.png) +## Prerequisites + [!INCLUDE [temp](../includes/process-prerequisites.md)] -To add extensions or edit a process, you must be a member of the Project Collection Administrators group or be [granted explicit permissions to edit a specific process](../../../organizations/security/set-permissions-access-work-tracking.md#process-permissions). +To add extensions or edit a process, be a member of the Project Collection Administrators group or be [granted explicit permissions to edit a specific process](../../../organizations/security/set-permissions-access-work-tracking.md#process-permissions). [!INCLUDE [temp](../includes/open-process-admin-context-ts.md)] [!INCLUDE [temp](../includes/automatic-update-project.md)] - ## Review installed Marketplace extensions From the **Settings** context, **Extensions**, you can view the extensions that are already installed. You may need to choose ![Refresh](media/process/custom-controls-refresh_extensions.png) to refresh the page to show newly installed extensions. @@ -74,7 +75,6 @@ You can [browse the Marketplace](https://marketplace.visualstudio.com/search?ter > [!div class="mx-imgBorder"] > ![Group extension on Bug work item form](media/process/cpfield-add-checklist-extension.png) - ## Add a field-level contribution or custom control @@ -139,7 +139,6 @@ When you add group-level and page-level contributions, they are automatically ad If you've installed a group or page contribution, refresh your browser, and then open a work item to view the placement of the contribution on the form. To move or hide the contribution, [follow the guidance provided for the Layout tab](customize-process-form.md). - ## Action-level contributions Action-level contributions are added to the context menu of inherited and customizable WITs for both system and inherited processes. All action-level contributions are added to all work item types and cannot be hidden or removed without [uninstalling or disabling the extension](../../../marketplace/install-extension.md#uninstall-disable-extension). @@ -154,7 +153,6 @@ You can use these REST APIs to work with extensions: - [Extend the work item form](../../../extend/develop/add-workitem-extension.md) - [Add a custom control to the work item form](../../../extend/develop/custom-control.md) - ## Related articles [!INCLUDE [temp](../includes/note-audit-log-support-process.md)] diff --git a/docs/organizations/settings/work/custom-rules.md b/docs/organizations/settings/work/custom-rules.md index 9b54ccde0ba..dcb25d40189 100644 --- a/docs/organizations/settings/work/custom-rules.md +++ b/docs/organizations/settings/work/custom-rules.md @@ -7,7 +7,7 @@ ms.service: azure-devops-boards ms.assetid: 17A6AF2C-81E9-4717-971E-2621613AEB31 ms.author: chcomley author: chcomley -monikerRange: ">= azure-devops-2019" +monikerRange: "<=azure-devops" ms.topic: how-to ms.date: 06/07/2021 --- @@ -34,7 +34,8 @@ With a custom rule, you can define a number of actions based on specific conditi > You make a field required and specify a field default through the [**Options** tab for the field](customize-process-field.md#options). Prior to defining a custom rule, review [Rules and rule evaluation, Inherited process rule composition](rule-reference.md#ip-rule-composition). For examples that illustrate common scenarios for applying rules, see [Sample rule scenarios](rule-samples.md). - + +## Prerequisites [!INCLUDE [temp](../includes/process-prerequisites.md)] @@ -76,7 +77,6 @@ You delete or disable the rule from the actions menu of the rule. ![Delete or disable a rule](media/process/custom-rule-delete-disable-rule.png) - ## Related articles [!INCLUDE [temp](../includes/note-audit-log-support-process.md)] diff --git a/docs/organizations/settings/work/customize-process-backlogs-boards.md b/docs/organizations/settings/work/customize-process-backlogs-boards.md index 01e661e17c2..496eab3cd6b 100644 --- a/docs/organizations/settings/work/customize-process-backlogs-boards.md +++ b/docs/organizations/settings/work/customize-process-backlogs-boards.md @@ -1,41 +1,39 @@ --- title: Customize backlogs and boards titleSuffix: Azure Boards -description: Learn how to add and edit backlog levels for the Inheritance process model +description: Learn how to add and edit backlog levels for the Inheritance process model. ms.custom: inherited-process ms.service: azure-devops-boards ms.assetid: 4B6014AA-5CD8-47B9-A1E3-BFB0CCA721AF ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' +monikerRange: '<= azure-devops' ms.topic: how-to -ms.date: 04/07/2021 +ms.date: 07/16/2024 --- -# Customize your backlogs or boards (Inheritance process) +# Customize backlogs and boards (Inheritance process) -[!INCLUDE [version-gt-eq-2019](../../../includes/version-gt-eq-2019.md)] +[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -You can customize your backlogs to add more levels or add custom work item types to them. As shown below, we've added a third level portfolio backlog labeled *Initiatives* which tracks the custom *Initiative* work item type, and we've renamed the product backlog to *Stories and Tickets* to indicate that we not only track *User Stories*, but also *Customer Tickets* on the product backlog. - -> [!div class="mx-imgBorder"] -> ![Changes made to the backlog levels](media/process/portfolio-backlogs-modified.png) - -Your project defines two portfolio backlogs: Features and Epics. However, if you need one or more additional portfolio backlogs, you can add them. +In your project, you currently have two predefined portfolio backlogs: "Features” and “Epics." +But, if your project requires more portfolio backlogs, you can create them. [!INCLUDE [temp](../includes/note-on-prem-link.md)] +**Benefits of portfolio backlogs:** +- **Organizing work:** Portfolio backlogs allow you to organize work based on business initiatives, user scenarios, or other relevant criteria. +- **Hierarchical view:** By [structuring backlogs into portfolios](../../../boards/backlogs/organize-backlog.md), you gain a hierarchical view of work, which includes items defined in lower-level backlogs (such as user stories, features, or tasks). +- **Cross-team visibility:** Program managers can track the status of backlog items across multiple teams. They can drill down to ensure that all work is adequately represented. -Portfolio backlogs are useful for organizing your backlog under various business initiatives and user scenarios. When you [organize your backlogs into portfolios](../../../boards/backlogs/organize-backlog.md), you can gain a hierarchical view of the work defined in lower-level backlogs, including work in progress across several teams. Program managers can track the status of those backlog items of interest and drill down to ensure that all work is represented. +For more information, see [About process customization and inherited processes](inheritance-process-model.md). + +In the following example, we added a third level portfolio backlog labeled *Initiatives*, which tracks the custom *Initiative* work item type. We also renamed the product backlog to *Stories and Tickets* to indicate that we not only track *User Stories*, but also *Customer Tickets* on the product backlog. + +> [!div class="mx-imgBorder"] +> ![Screenshot showing Changes made to the backlog levels.](media/process/portfolio-backlogs-modified.png) -To learn more about what you can customize, see [About process customization and inherited processes](inheritance-process-model.md). - - -::: moniker range="azure-devops-2019" -> [!NOTE] -> You can't add an inherited work item type to any backlog level. For example, you can't add the Issue or Impediment work item type to the product backlog. -::: moniker-end ## Supported customizations @@ -43,13 +41,13 @@ To learn more about what you can customize, see [About process customization and [!INCLUDE [temp](../../../boards/includes/note-azure-devops-2020-1-updates.md)] - + ::: moniker range=">= azure-devops-2020" ## Add a system work item type to a backlog -If you want to track Issues or Impediments or other inherited work item types within a backlog or board, you can by editing the corresponding backlog. The following table lists the available work item types you can add to a backlog. +If you want to track Issues or Impediments or other inherited work item types within a backlog or board, edit the corresponding backlog. The following table lists the available work item types you can add to a backlog. ::: moniker-end ::: moniker range="azure-devops-2020" @@ -97,89 +95,93 @@ If you want to track Issues or Impediments or other inherited work item types wi :::row-end::: --- -Each **Edit backlog level** dialog automatically includes inherited and custom work item types which haven't been assigned to other backlog levels. For example, unassigned Agile work item types are listed under the **Other work item types** section as shown in the following image +Each **Edit backlog level** dialog automatically includes inherited and custom work item types that aren't assigned to other backlog levels. For example, unassigned Agile work item types are listed under the **Other work item types** section as shown in the following image > [!div class="mx-imgBorder"] -> ![Web portal, Process, Backlog levels, Other work item types section, Agile process](media/backlogs/other-work-item-types-agile.png) +> ![Screenshot showing Web portal, Process, Backlog levels, Other work item types section, Agile process.](media/backlogs/other-work-item-types-agile.png) -These same work item types, along with any custom work item types, appear in the **Edit backlog level** dialog of all backlog levels, until they are assigned to a particular backlog level. +These same work item types, along with any custom work item types, appear in the **Edit backlog level** dialog of all backlog levels, until they get assigned to a particular backlog level. > [!div class="mx-imgBorder"] -> ![Web portal, Process, Backlog levels, Edit backlog level dialog](media/backlogs/edit-backlog-level-requirements-agile.png) +> ![Screenshot of Web portal, Process, Backlog levels, Edit backlog level dialog.](media/backlogs/edit-backlog-level-requirements-agile.png) - > [!NOTE] > You can't remove the default, inherited work item type from any backlog level, but you can disable the corresponding work item type. For example, you can disable the User Story work item type for the Agile Requirement backlog as long as you have added another work item type to support that backlog. - ::: moniker-end - - ## Fields added to work item types -When you add a work item type to a backlog level, the following fields are added to the work item type definition as hidden fields (that is, they don't appear on the work item form) to support select Agile tool features. - -| Backlog level | Fields added | -|---------------|--------------| -| Portfolio backlog |- Stack rank (Agile, CMMI)
      - Backlog Priority (Scrum) | -| Requirement backlog |- Stack Rank, Story Points (Agile)
      - Stack Rank, Size (CMMI)
      - Backlog Priority, Effort (Scrum) | -| Iteration backlog |- Activity, Remaining Work, Stack Rank (Agile)
      - Discipline, Remaining Work, Stack Rank (CMMI)
      - Activity, Remaining Work, Backlog Priority (Scrum) | +When you add a WIT to a backlog level, certain fields are automatically added to the WIT definition as hidden fields. These fields don't appear on the work item form but are essential for supporting specific Agile tool features. -The Stack Rank and Backlog Priority fields capture the relative priority of work items as they are reordered on a backlog or board. For details on its usage, see [Behind the scenes: the Backlog Priority or Stack Rank field](https://blogs.msdn.microsoft.com/devops/2014/05/14/behind-the-scenes-the-backlog-priority-or-stack-rank-field/). +| Backlog level | Fields added | Description | +|---------------|--------------|-------------| +| Portfolio backlog |- Stack rank (Agile, CMMI)
      - Backlog Priority (Scrum) | The Stack Rank and Backlog Priority fields capture the relative priority of work items as they get reordered on a backlog or board. For more information, see [Behind the scenes: the Backlog Priority or Stack Rank field](https://blogs.msdn.microsoft.com/devops/2014/05/14/behind-the-scenes-the-backlog-priority-or-stack-rank-field/). | +| Requirement backlog |- Stack Rank, Story Points (Agile)
      - Stack Rank, Size (CMMI)
      - Backlog Priority, Effort (Scrum) |The Story Points, Size, and Effort fields capture the relative work required to complete a WIT assigned to the Requirement backlog. This value is used to compute [velocity](../../../report/dashboards/team-velocity.md).| +| Iteration backlog |- Activity, Remaining Work, Stack Rank (Agile)
      - Discipline, Remaining Work, Stack Rank (CMMI)
      - Activity, Remaining Work, Backlog Priority (Scrum) |Remaining Work is used in [Sprint burndown and capacity charts](../../../boards/sprints/define-sprints.md).| -The Story Points, Size, and Effort fields capture the relative work required to complete a WIT assigned to the Requirement backlog. This value is used to compute [velocity](../../../report/dashboards/team-velocity.md). +## Prerequisites -And, lastly, Remaining Work is used in [Sprint burndown and capacity charts](../../../boards/sprints/define-sprints.md). - -[!INCLUDE [temp](../includes/process-prerequisites.md)] - -[!INCLUDE [temp](../includes/open-process-admin-context-ts.md)] +[!INCLUDE [temp](../includes/process-prerequisites.md)] [!INCLUDE [temp](../includes/automatic-update-project.md)] - ## Add or edit portfolio backlogs -The Agile, Scrum, and CMMI system processes defines two default portfolio backlogs, Epics and Features. Each is associated with their corresponding work item types, Epic and Feature. The Basic process only defines the Epics backlog and Epic work item type. For more information, see [About processes and process templates](../../../boards/work-items/guidance/choose-process.md). +The Agile, Scrum, and CMMI system processes define two default portfolio backlogs, Epics and Features. Each is associated with their corresponding work item types, Epic, and Feature. The Basic process only defines the Epics backlog and Epic work item type. For more information, see [About processes and process templates](../../../boards/work-items/guidance/choose-process.md). -You can add a custom work item type when adding or editing a portfolio backlog, or you can choose a work item type you've previously added. Only those work item types that don't belong to another backlog level appear for selection. - +You can add a custom WIT or select one that you previously added. Keep in mind that only WITs not associated with another backlog level appear for selection. ### Add a portfolio backlog You can add a portfolio backlog and custom work item type following these steps. + +:::moniker range="azure-devops" + +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). +2. Select ![gear icon](../../../media/icons/gear-icon.png) **Organization settings**. + + ![Screenshot showing Organization settings button highlights.](../../../media/settings/open-admin-settings-vert.png) + +3. Select **Process**. + +::: moniker-end + +::: moniker range="< azure-devops" + +1. Sign in to your collection (```https://dev.azure.com/{Your_Collection}```). +2. Select **Collection Settings** or **Admin settings**. +3. Select **Process**. + + > [!div class="mx-imgBorder"] + > ![Screenshot showing highlighted Process button in Collection settings.](../work/media/process/open-process-2020.png) + +::: moniker-end -1. From the **Backlog levels** page, choose :::image type="icon" source="../../../media/icons/blue-add-icon.png" border="false"::: **New top level portfolio backlog**. +4. From the **Backlog levels** page, choose :::image type="icon" source="../../../media/icons/blue-add-icon.png" border="false"::: **New top level portfolio backlog**. > [!div class="mx-imgBorder"] - > ![Web portal, Admin context, Process page, select Process](media/process/process-new-portfolio-backlog.png) + > ![Screenshot showing Web portal, Admin context, Process page, select Process.](media/process/process-new-portfolio-backlog.png) -1. Name the backlog level, select the backlog level color, and add the work item type to associate with this level. Click **Add**. +5. Name the backlog level, select the backlog level color, and add the work item type to associate with this level, and then select **Add**. ::: moniker range=">= azure-devops-2020" > [!div class="mx-imgBorder"] - > ![Web portal, Add a portfolio backlog dialog, Add new work item type](media/backlogs/add-portfolio-backlog-initiative-s173.png) - ::: moniker-end - ::: moniker range="azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Web portal, Add a portfolio backlog dialog, Add new work item type](media/process/process-add-portfolio-backlog-dialog.png) + > ![Screenshot showing Web portal, Add a portfolio backlog dialog, Add new work item type.](media/backlogs/add-portfolio-backlog-initiative-s173.png) ::: moniker-end + -1. If you are associating only one work item type with the backlog, then choose **Save** to save your changes. Otherwise, you can add more work item types as needed. +6. If you're associating only one work item type with the backlog, then choose **Save** to save your changes. Otherwise, you can add more work item types as needed. ::: moniker range=">= azure-devops-2020" > [!div class="mx-imgBorder"] - > ![Web portal, Add a portfolio backlog dialog, Save changes.](media/backlogs/add-portfolio-backlog-initiative-save.png) - ::: moniker-end - ::: moniker range="azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Web portal, Add a portfolio backlog dialog, Save changes](media/process/process-add-portfolio-backlog-dialog-save.png) + > ![Screenshot showing Web portal, Add a portfolio backlog dialog, Save changes.](media/backlogs/add-portfolio-backlog-initiative-save.png) ::: moniker-end + @@ -187,11 +189,11 @@ You can add a portfolio backlog and custom work item type following these steps. From the **Backlog levels** page, choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: context menu of a portfolio backlog to edit, rename, or delete it. -![Choose the context menu of a portfolio backlog to edit, rename, or delete it.](media/process/process-portfolio-backlog-context-menu.png) +![Screenshot showing Choose the context menu of a portfolio backlog to edit, rename, or delete it.](media/process/process-portfolio-backlog-context-menu.png) -Deleting a backlog level removes the backlog and board associated with the level for all teams, including customizations made to them. The work items defined with the associated work item types are not deleted or affected in any way. +Deleting a backlog level removes the backlog and board associated with the level for all teams, including customizations made to them. The work items defined with the associated work item types aren't deleted or affected in any way. -![Deleting a backlog level removes the backlog and board associated with the level.](media/process/process-edit-portfolio-backlog-dialog.png) +![Screenshot showing Deleting a backlog level removes the backlog and board associated with the level.](media/process/process-edit-portfolio-backlog-dialog.png) > [!NOTE] > You can't remove the default, inherited work item type from the Epics or Features portfolio backlogs. However, you can disable these work item types and that effectively removes them from the user interface. @@ -200,28 +202,20 @@ Deleting a backlog level removes the backlog and board associated with the level ## Edit or rename the requirement backlog -The Requirement backlog, also referred to as the product backlog, defines the work item types that appear on the product backlog and Kanban board. The default work item type for Agile is User Story; for Basic, Issue; for Scrum, Product Backlog Item; and for CMMI, Requirement. +The Requirement backlog, also referred to as the product backlog, defines the work item types that appear on the product backlog and board. The default work item type for Agile is User Story; for Basic, Issue; for Scrum, Product Backlog Item; and for CMMI, Requirement. You can rename the backlog, change the color, add work item types, and change the default work item type. Open the Edit backlog dialog from the context menu for the Requirements backlog. - ::: moniker range=">= azure-devops-2020" -Here, we've renamed the backlog, added **Customer Ticket** and **Issue**, and changed the default type to *Customer Ticket*. Check those boxes of the work item types to include on the backlog. +In the following example, we renamed the backlog, added **Customer Ticket** and **Issue**, and changed the default type to *Customer Ticket*. Check those boxes of the work item types to include on the backlog. -:::image type="content" source="media/backlogs/add-oob-issue-to-backlog.png" alt-text="On Edit backlog, Stories and Tickets is entered in Name, and there is a list of work item types for this backlog level."::: +:::image type="content" source="media/backlogs/add-oob-issue-to-backlog.png" alt-text="On Edit backlog, Stories and Tickets is entered in Name, and there's a list of work item types for this backlog level."::: - ::: moniker-end -::: moniker range="azure-devops-2019" - -Here, we've renamed the backlog, added *Customer Ticket*, and changed the default type to *Customer Ticket*. - -![Example of renaming the backlog, adding Customer Ticket, and changing the default type to Customer Ticket.](media/process/process-edit-backlog-dialog-modified.png) -::: moniker-end + - > [!NOTE] > You can't remove the default, inherited work item type from the Requirements backlog. However, you can disable the work item type and that effectively removes it from the user interface. @@ -233,29 +227,17 @@ The Iteration backlog, also referred to as the sprint backlogs, defines the work For the iteration backlog, you can add work item types and change the default work item type. Open the Edit backlog dialog from the context menu for the Iteration backlog. -Here, we've added the *Ticket* work item type which is tracked along with tasks. +In the following example, we added the *Ticket* work item type that is tracked along with tasks. -![Example of adding the Ticket work item.](media/process/process-edit-iteration-backlog-dialog-modified.png) +![Screenshot showing Example of adding the Ticket work item.](media/process/process-edit-iteration-backlog-dialog-modified.png) > [!NOTE] > You can't remove the default, inherited work item type from the Iteration backlog. However, you can disable the work item type and that effectively removes it from the user interface. +## Related articles - - -## Related articles - -[!INCLUDE [temp](../includes/note-audit-log-support-process.md)] - +- [Organize your backlog, work with portfolio backlogs](../../../boards/backlogs/organize-backlog.md) - [Add a custom work item type](add-custom-wit.md) -- [Customize a project using an inherited process](customize-process.md) -- [Backlogs, boards, and plans](../../../boards/backlogs/backlogs-boards-plans.md) -- [Create your backlog](../../../boards/backlogs/create-your-backlog.md) -- [Organize your backlog, work with portfolio backlogs](../../../boards/backlogs/organize-backlog.md) - - - - - - - +- [Learn about backlogs, boards, and plans](../../../boards/backlogs/backlogs-boards-plans.md) +- [Customize a project using an inherited process](customize-process.md) +- [View changes made to an inherited process through the audit log](../../audit/azure-devops-auditing.md). diff --git a/docs/organizations/settings/work/customize-process-field.md b/docs/organizations/settings/work/customize-process-field.md index 05e4a01d32e..96191341d4d 100644 --- a/docs/organizations/settings/work/customize-process-field.md +++ b/docs/organizations/settings/work/customize-process-field.md @@ -7,7 +7,7 @@ ms.service: azure-devops-boards ms.assetid: D6616411-43D4-4A81-8951-772D98BD1569 ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.topic: how-to ms.date: 01/11/2022 --- @@ -24,6 +24,7 @@ For a list of all fields defined for your organization—which includes all Once you've added a custom field, you can create [queries](../../../boards/queries/using-queries.md), [charts](../../../report/dashboards/charts.md), or [Analytics views and Power BI reports](../../../report/powerbi/create-quick-report.md) to track data related to it. +## Prerequisites [!INCLUDE [temp](../includes/process-prerequisites.md)] @@ -31,12 +32,10 @@ Once you've added a custom field, you can create [queries](../../../boards/queri [!INCLUDE [temp](../includes/automatic-update-project.md)] - - ## Custom field names When you add a custom field to an inherited process, Azure DevOps assigns a reference name prefixed with *Custom* and then then name of the field with spaces removed. For example, you add a field named DevOps Triage, the reference name is **Custom.DevOpsTriage**. No spaces are allowed within the reference name. @@ -84,7 +83,7 @@ You can add fields and specify the group and page where they should appear. Also Add a field to Use story, specify layout > [!NOTE] - > While you can change the form label, you must use the field name when you are adding fields to cards ([Kanban](../../../boards/boards/customize-cards.md#fields), [Taskboard](../../../boards/sprints/customize-taskboard.md)) or [creating queries](../../../boards/queries/using-queries.md) based on the field. + > While you can change the form label, you must use the field name when you are adding fields to cards ([Board](../../../boards/boards/customize-cards.md#fields), [Taskboard](../../../boards/sprints/customize-taskboard.md)) or [creating queries](../../../boards/queries/using-queries.md) based on the field. 1. Choose Add field to complete adding the field. If you don't specify its layout location, the system adds it to the first group of fields on the form. @@ -95,13 +94,11 @@ You can add fields and specify the group and page where they should appear. Also > [!div class="mx-imgBorder"] > ![Bug form, Customer Ticket field added to Customer focus group](media/process/cpfield-bug-form-customized-customer-ticket.png) - - + ### Add a picklist - [Work tracking, process, and project limits](object-limits.md) ::: moniker range=">= azure-devops-2020" @@ -138,12 +135,11 @@ You can add a new field and define a pick list or customize the pick list of an ![Add a custom picklist](media/process/customize-field-reorder-list.png) --> - ### Add an Identity field -Use an Identity-based field to add a field similar to the Assigned To field. Identity-based fields act in the same way as the Assigned To field, providing a search and identity picker function. When your organization manages users with Azure Active Directory or Active Directory, the system synchronizes Identity-based fields with the names defined in these directories. +Use an Identity-based field to add a field similar to the Assigned To field. Identity-based fields act in the same way as the Assigned To field, providing a search and identity picker function. When your organization manages users with Microsoft Entra ID or Active Directory, the system synchronizes Identity-based fields with the names defined in these directories. 1. Start by choosing ![add new field icon](media/process/new-field-icon.png) New field, then the field name, Identity type, and optionally a description. @@ -184,7 +180,7 @@ Use an Identity-based field to add a field similar to the Assigned To field. Ide 4. By default, the field is added to the last group defined in the second column. Open the Layout tab to drag and drop the field to another group on the form. > [!NOTE] - > The field appears as a checkbox in the work item form. Check the box to indicate a True value. If you display the field on the Kanban or Taskboard, then the field values of True and False display (not a checkbox). + > The field appears as a checkbox in the work item form. Check the box to indicate a True value. If you display the field on the board or Taskboard, then the field values of True and False display (not a checkbox). @@ -200,7 +196,6 @@ Here we add the Customer Ticket field to the User Story WIT. Optionally, specify the [Required/Default values](#options) and [placement within the form](#layout) for the field. - ## Relabel a field @@ -211,8 +206,7 @@ Here, we relabel the Customer Ticket field to Ticket Number. ![Layout tab, Relabel a field](media/process/cpfield-relabel-customer-ticket.png) - - + ## Modify Description help text @@ -222,17 +216,10 @@ Description help text displays when users hover over a field in the work item fo - **For inherited fields**: Description help text can be defined differently for each work item type and process. - **For custom fields**: Description help text appears the same for the field across all work item types and all processes. - ::: moniker-end [!INCLUDE [temp](../../../boards/includes/note-azure-devops-2020-1-updates.md)] -::: moniker range="azure-devops-2019" - -Description help text displays when users hover over a field in the work item form. You can only modify the description help text on a custom field. That help text propagates to all work item types and all processes. You can't customize the help text by process or work item type. - -::: moniker-end - To modify the **Description** help text, choose the work item type you want to modify, choose **Edit** for the field and choose the **Definition** tab. The modified value only affects that field in the process and for that work item type. ::: moniker range=">= azure-devops-2020" @@ -244,18 +231,6 @@ Here we modify the Story Points field for User Story. ::: moniker-end - -::: moniker range="azure-devops-2019" - -Here we modify the custom Published field for User Story. - -> [!div class="mx-imgBorder"] -> ![Edit field dialog, User Story, Published custom field.](media/custom-field/edit-field-dialog-definition-description-help-text-custom-field.png) - - -::: moniker-end - - ## Show, hide, or remove a field @@ -266,29 +241,19 @@ You can choose to show or hide any field or custom control from appearing on a f ::: moniker-end -::: moniker range="azure-devops-2019" - -You can choose to show or hide an inherited field or a custom control from appearing on a form. For custom fields, you can remove it from the form. If you want to reinstate it by choosing **Show on layout**. These actions differ from the [**Delete**](#delete-field) option, which deletes the field from the organization. - -::: moniker-end - > [!NOTE] > Data defined for an inherited field, even if you hide it, is maintained in the data store and work item history. You can view a record of it by viewing the history tab for a work item. > > When you remove a custom field from the layout, it is maintained in the data store but stripped from the history. You can view it from the query results. If you add the field back to the form, then the history for it is restored.To delete a custom field from a project collection, see [Delete a field](#delete-field). - - ::: moniker range=">= azure-devops-2020" ### Hide a field or custom control ::: moniker-end -::: moniker range="azure-devops-2019" -### Hide an inherited field or custom control -::: moniker-end + 1. Open the context menu for the field or control and choose **Hide from layout**. @@ -310,7 +275,6 @@ You can choose to show or hide an inherited field or a custom control from appea 1. To add a custom field that's been removed, choose **New field** and select **Use an existing field**. - ## Revert field to preset defaults @@ -320,7 +284,6 @@ You may discard changes you made to an inherited field. From the **Layout** page > [!div class="mx-imgBorder"] > ![Layout page, Field context menu, choose Revert option](media/process/cpfield-revert.png) - ## Delete a custom field @@ -337,12 +300,11 @@ Deleting a field deletes all data associated with that field, including historic > https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItemTypeFields?$filter=FieldReferenceName eq {CustomFieldReferenceName}&$select=WorkItemType > ``` - 1. You delete the field from the **All processes>Fields** page. ![Delete field](media/process/cpfield-delete-field.png) - To delete fields, you must be a member of the Project Collection Administrators group or be [granted explicit permissions to Delete field from account](../../../organizations/security/set-permissions-access-work-tracking.md#process-permissions). + To delete fields, be a member of the Project Collection Administrators group or be [granted explicit permissions to Delete field from account](../../../organizations/security/set-permissions-access-work-tracking.md#process-permissions). 2. To complete the delete operation, you must type the name of the field as shown. @@ -361,13 +323,11 @@ Deleting a field deletes all data associated with that field, including historic - [Show bugs on backlogs and boards](../show-bugs-on-backlog.md) - [Work tracking, process, and project limits](object-limits.md) - If you're working with test plans or test cases, see these articles: - [Create a test plan](../../../test/create-a-test-plan.md) - [Create manual test cases](../../../test/create-test-cases.md) - +- [Use the REST API to manage processes](/rest/api/azure/devops/processes/processes/list) +- [Create an inherited process and change the project to use that process](manage-process.md). +- [Learn work tracking object limits](object-limits.md) diff --git a/docs/organizations/settings/work/faqs.yml b/docs/organizations/settings/work/faqs.yml index 8ac82e43d1a..2fe1ada9698 100644 --- a/docs/organizations/settings/work/faqs.yml +++ b/docs/organizations/settings/work/faqs.yml @@ -25,20 +25,19 @@ sections: - question: Can sub hubs within Azure Boards be disabled? answer: | - **No**. While you can disable an entire service— such as Azure Boards, Azure Repos, Azure Pipelines— you can't disable individual pages within a service. To learn more, see [Turn a service on or off](../set-services.md). + **No**. While you can disable an entire service— such as Azure Boards, Azure Repos, Azure Pipelines— you can't disable individual pages within a service. For more information, see [Turn a service on or off](../set-services.md). - question: Are there set limits regarding configuration or customization? answer: | There are a number of limits Azure DevOps imposes such as the number of Area Paths and Iteration Paths you can define for a project, the number of processes you can define, and more. For a full list, see [Work tracking, process, and project limits](object-limits.md). - - name: Configuration questions: - question: Who has permissions to configure Azure Boards? answer: | - In general, you need to be a member of the Project Administrators group to configure the following project-level objects. Or, you can provide permissions at the node level or object level to individual members or groups. To learn more, see [Change project-level permissions](../../security/change-project-level-permissions.md). + In general, you need to be a member of the Project Administrators group to configure the following project-level objects. Or, you can provide permissions at the node level or object level to individual members or groups. For more information, see [Change project-level permissions](../../security/change-project-level-permissions.md). - [Area Paths](../set-area-paths.md) - [Modify work items under an area path](../../security/set-permissions-access-work-tracking.md#set-permissions-area-path) - [Iteration Paths](../set-iteration-paths-sprints.md) @@ -58,21 +57,19 @@ sections: ::: moniker-end In general, you need to be a member of a team or granted the [Team Administrator](../add-team-administrator.md) role to configure the following team-level objects. - - [Default and selected Area Paths](../set-area-paths.md#team-area-paths) - - [Default and selected Iteration Paths](../set-iteration-paths-sprints.md#activate) + - [Default and selected Area Paths](../set-area-paths.md#set-team-area-paths) + - [Default and selected Iteration Paths](../set-iteration-paths-sprints.md#list-team-iterations) - [Define work item templates](../../../boards/backlogs/work-item-template.md) - - name: Customization questions: - - question: Who has permissions to customize Azure Boards? answer: | - ::: moniker range=">= azure-devops-2019" - In general, you need to be a member of the Project Collection Administrators group to customize an Inherited process. Or, you must have the following explicit collection-level permissions set to **Allow**: + ::: moniker range="<=azure-devops" + In general, you need to be a member of the Project Collection Administrators group to customize an Inherited process. Or, have the following explicit collection-level permissions set to **Allow**: - [Create process](manage-process.md) - [Delete field from organization](customize-process-field.md) - [Delete process](manage-process.md) @@ -81,17 +78,16 @@ sections: To grant a project member permissions, see [Change project-level permissions](../../security/change-project-level-permissions.md). ::: moniker-end ::: moniker range="< azure-devops" - To modify an On-premises XML process, you need to be a member of the **Project Collection Administrators** group to manage process templates or the **Project Administrators** group to exercise a [**witadmin** commmand](../../../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md). Or, you must have the following explicit collection-level permissions set to **Allow**: + To modify an On-premises XML process, you need to be a member of the **Project Collection Administrators** group to manage process templates or the **Project Administrators** group to exercise a [**witadmin** command](../../../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md). Or, have the following explicit collection-level permissions set to **Allow**: - [Delete field](../../../reference/add-modify-field.md) - [Manage process template](../../../boards/work-items/guidance/manage-process-templates.md) To grant a project member permissions, see [Change project collection-level permissions](../../security/change-organization-collection-level-permissions.md). ::: moniker-end - - question: Is there a way to determine who changed what within a process? answer: | - ::: moniker range=">= azure-devops-2019" - Auditing of process changes is available for Azure DevOps Services (cloud) only. To learn more, see [Access, export, and filter audit logs](../../audit/azure-devops-auditing.md). + ::: moniker range="<=azure-devops" + Auditing of process changes is available for Azure DevOps Services (cloud) only. For more information, see [Access, export, and filter audit logs](../../audit/azure-devops-auditing.md). ::: moniker-end A best practice is to maintain process templates under source control. In that way, changes made to a process is available through standard source control versioning. @@ -99,8 +95,8 @@ sections: answer: | Picklist value entries are dependent on the data type. Refer to the following articles based on the field type of interest: - **Numeric or string picklist fields**: You can customize the menu values for fields such as [Priority](../../../boards/queries/planning-ranking-priorities.md), [Activity](../../../boards/queries/query-numeric.md), [Discipline](../../../boards/queries/query-numeric.md), and so on. See [Add and manage fields (Inherited process)](customize-process-field.md) or [Add or modify a field, customize a picklist (On-premises XML process)](../../../reference/add-modify-field.md). - - **Area Path or Iteration Path**: These tree-path fields are configured for each project. To learn more, see [About area and iteration (sprint) paths](../about-areas-iterations.md). - - **Person-name or Identity fields**: To add values for fields associated with user accounts such as Assigned To, [add users to a project security group or a team](../../security/add-users-team-project.md). By default, the list for these fields contain the account names for all users and groups that have been added to your organization or on-premises collection. These accounts are often synchronized with Active Directory or Azure Active Directory. See [Add AD/Azure AD users or groups to a built-in security group](../../security/add-ad-aad-built-in-security-groups.md). + - **Area Path or Iteration Path**: These tree-path fields are configured for each project. For more information, see [About area and iteration (sprint) paths](../about-areas-iterations.md). + - **Person-name or Identity fields**: To add values for fields associated with user accounts such as Assigned To, [add users to a project security group or a team](../../security/add-users-team-project.md). By default, the list for these fields contain the account names for all users and groups that have been added to your organization or on-premises collection. These accounts are often synchronized with Active Directory or Microsoft Entra ID. See [Add Active Directory / Microsoft Entra users or groups to a built-in security group](../../security/add-ad-aad-built-in-security-groups.md). - question: Can I add or rename a portfolio backlog? answer: | @@ -120,7 +116,6 @@ sections: **Yes**. Conditional rules based on user or group membership are cached for your web browser. If you find yourself restricted to update a work item, you may have encountered one of these rules. If you believe you've encountered an issue that doesn't apply to you, see [Work item form IndexDB caching issues](troubleshoot-work-item-form-caching-issues.md). To learn more about conditional rules, see [Rules and rule evaluation](rule-reference.md). - - question: Can I upload my own custom work item type icons for an Inherited process? answer: | **Example request**: *When I create a new work item type, I get an option to choose an icon. The icon set is limited and doesn't support the icons that we would prefer for our use case. Is there a way to associate custom icon to new work item type?* diff --git a/docs/organizations/settings/work/hosted-xml-process-model.md b/docs/organizations/settings/work/hosted-xml-process-model.md index 7d549685a2c..1f7ec3c7dc7 100644 --- a/docs/organizations/settings/work/hosted-xml-process-model.md +++ b/docs/organizations/settings/work/hosted-xml-process-model.md @@ -117,11 +117,11 @@ You can perform the following tasks with the Hosted XML process model. :::column-end::: :::row-end::: - + ## Add release deployment support to a work item type -The release deployments control shows release information for only those work items that have been associated to a commit that is part of a build being released. To add the release deployments control to a work item type, you need to add the following syntax to a work item type XML definition. To learn more about this control, see [Link work items to deployments](../../../boards/work-items/work-item-deployments-control.md). +The release deployments control shows release information for only those work items that have been associated to a commit that is part of a build being released. To add the release deployments control to a work item type, you need to add the following syntax to a work item type XML definition. To learn more about this control, see [Link work items to deployments](../../../boards/backlogs/add-link.md). > [!div class="tabbedCodeSnippets"] ```XML @@ -130,7 +130,7 @@ The release deployments control shows release information for only those work it       ``` -This syntax has been been added to the following work item type definitions of the default process templates. +This syntax is added to the following work item type definitions of the default process templates. > [!div class="mx-tdBreakAll"] > |Agile|Basic|Scrum|CMMI | diff --git a/docs/organizations/settings/work/import-process/customize-process.md b/docs/organizations/settings/work/import-process/customize-process.md index d1775b45a55..2ebc315af68 100644 --- a/docs/organizations/settings/work/import-process/customize-process.md +++ b/docs/organizations/settings/work/import-process/customize-process.md @@ -86,6 +86,10 @@ A process is a zip file that contains a set of interdependent files. These files There are differences between what Azure DevOps Services supports and what on-premises Team Foundation Server supports. For a summary of these differences, see [Process template customizations differences](differences.md). +## Prerequisites + +[!INCLUDE [process-prerequisites](../../includes/process-prerequisites.md)] + ## How to customize a process When you customize a process, starting with a well-defined process is easier than building a new one. @@ -143,20 +147,29 @@ The following section lists limitations that the system imposes. You can import up to 32 processes into Azure DevOps Services. Your custom processes must conform to all of the following summarized rules. Otherwise, validation error messages might appear upon import. -* [Process](#process) - * [Process configuration](#process-configuration) - * [Categories](#categories) - * [Work item types](#work-item-types) - * [Fields](#work-item-fields) - * [Limits](#limits) - * [Required fields](#required-fields) - * [Rule restrictions](#rule-restrictions) - * [Consistent names and attributes](#consistent-names-attributes) - * [Identity fields](#identity-fields) - * [Workflow](resolve-errors.md#wit-workflow-definitions) - * [Global lists](#wit-global-list-definitions) - * [Workflow](#work-item-workflow) - * [Form layout](#work-item-form-layout) +- [Customize a Hosted XML process](#customize-a-hosted-xml-process) + - [How to customize a process](#how-to-customize-a-process) + - [Export and import a process](#export-and-import-a-process) + - [Supported customizations](#supported-customizations) + - [Restrictions](#restrictions) + - [Process template](#process-template) + - [Process configuration](#process-configuration) + - [Categories](#categories) + - [Work item types](#work-item-types) + - [Work item fields](#work-item-fields) + - [Limit restrictions](#limit-restrictions) + - [Required fields](#required-fields) + - [Rule restrictions](#rule-restrictions) + - [Consistent names and attributes](#consistent-names-and-attributes) + - [Identity fields](#identity-fields) + - [Add a custom identity field](#add-a-custom-identity-field) + - [Rule restrictions on identity fields](#rule-restrictions-on-identity-fields) + - [Correct example](#correct-example) + - [Incorrect example](#incorrect-example) + - [Workflow](#workflow) + - [Global lists](#global-lists) + - [Form layout](#form-layout) + - [Related articles](#related-articles) @@ -207,7 +220,7 @@ The Categories.xml definition file must conform to the syntax and rules describe A **WITD** element and its child elements must conform to the syntax and rules described in [WITD XML element reference](/previous-versions/azure/devops/reference/xml/all-witd-xml-elements-reference). Also, it must meet the following conditions: -* There are at most 512 fields within a single WIT and 512 fields across all WITs. +* There are at most 1024 fields within a single WIT and 1024 fields across all WITs. * The friendly name and required **refname** attribute assigned to a WIT are unique within the set of WIT definition files. * The required **refname** attribute value doesn't contain disallowed characters or use the disallowed namespaces System.*Name* and Microsoft.*Name*. * Reference names contain at least one period (.), and all other characters are letters with no spaces. @@ -229,7 +242,7 @@ A **FIELD** element and its child elements can contain a **GLOBALLIST** element. #### Limit restrictions -* A **FIELDS** element is limited to 512 fields. +* A **FIELDS** element is limited to 1024 fields. * A work item type is limited to 64 person-name fields. A person-name field is one with the attribute and value ```syncnamechanges=true```. * An **ALLOWEDVALUES** or **SUGGESTEDVALUES** element is limited to 512 **LISTITEM** elements. * A field is limited to 1,024 rules. @@ -345,7 +358,7 @@ For a description of state category and mappings, see [Workflow states and state For the Hosted XML process model, the following limits are placed on global-list import: * There are at most 64 global lists. -* There are at most 512 items per list. +* There are at most 1,024 items per list. * Approximately 10,000 items can be defined in total among all global lists that are specified across all WITs. diff --git a/docs/organizations/settings/work/import-process/differences.md b/docs/organizations/settings/work/import-process/differences.md index 0899abb2119..b216e17bd81 100644 --- a/docs/organizations/settings/work/import-process/differences.md +++ b/docs/organizations/settings/work/import-process/differences.md @@ -11,7 +11,7 @@ monikerRange: 'azure-devops' ms.date: 03/20/2018 --- -# Process template customizations differences between Azure DevOps Services and TFS +# Process template customization differences [!INCLUDE [version-eq-azure-devops](../../../../includes/version-eq-azure-devops.md)] @@ -22,14 +22,14 @@ ms.date: 03/20/2018 > >To learn more about process models, see [Customize work tracking](../../../../reference/customize-work.md). -Azure DevOps Services uses a different model than Team Foundation Server (TFS) for relating projects and process. -* In TFS, process templates are used as starting points for projects and once a project is created, the project is the scope you customize. +Azure DevOps Services uses a different model than Azure DevOps Server for relating projects and process. +* In Azure DevOps Server, process templates are used as starting points for projects and once a project is created, the project is the scope you customize. * In Azure DevOps Services, process is shared across multiple projects and is the scope you customize. -The structure and overall syntax used in defining process templates remains the same, with only a few minor differences existing between templates you customize for import into Azure DevOps Services and those you upload to support an on-premises TFS. +The structure and overall syntax used in defining process templates remains the same, with only a few minor differences existing between templates you customize for import into Azure DevOps Services and those you upload to support an on-premises version. > [!NOTE] -> Migration of projects or collections from Hosted XML to the inherited model is not support for Azure DevOps Server. It is only available on the Azure DevOps Sevice. +> Migration of projects or collections from Hosted XML to the inherited model is not support for Azure DevOps Server. It is only available on the Azure DevOps Services. ## Unsupported customizations and unreferenced plug-in files @@ -81,4 +81,4 @@ When you connect to Azure DevOps Services, you can use the following tools subje - [Work tracking object limits](../object-limits.md) - [Customize work tracking](../../../../reference/customize-work.md) -- [Differences between Inheritance and Hosted XML](../inheritance-versus-hosted-xml.md) \ No newline at end of file +- [Differences between Inheritance and Hosted XML](../inheritance-versus-hosted-xml.md) diff --git a/docs/organizations/settings/work/import-process/import-process.md b/docs/organizations/settings/work/import-process/import-process.md index 21a0c7fc78e..399d9e5a2de 100644 --- a/docs/organizations/settings/work/import-process/import-process.md +++ b/docs/organizations/settings/work/import-process/import-process.md @@ -4,11 +4,12 @@ titleSuffix: Azure DevOps Services description: Import a Hosted XML process to support Azure Boards customization in Azure DevOps Services ms.service: azure-devops-boards ms.assetid: AF7ABA0F-D3E8-48CA-9164-ABC966BAAA77 +ai-usage: ai-assisted ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 03/06/2020 +ms.date: 04/08/2025 --- # Import and export a Hosted XML process @@ -16,50 +17,42 @@ ms.date: 03/06/2020 [!INCLUDE [version-eq-azure-devops](../../../../includes/version-eq-azure-devops.md)] > [!IMPORTANT] -> Import process supports the Hosted XML process model which allows you to manage customizations through updating the WIT definition of a process template. This feature is only available for organizations that have been migrated to Azure DevOps Services using the [TFS Database Import Service](../../../../migrate/migration-overview.md). -> -> If you use the Inheritance process model, you can customize your work tracking through the user interface by [creating an inherited process](../manage-process.md). If you use the On-premises XML process model, you can customize a process template, see [Upload or download a process template](../../../../boards/work-items/guidance/manage-process-templates.md) and [Customize a process template](../../../../reference/process-templates/customize-process.md). -> -> To learn more about process models, see [Customize work tracking](../../../../reference/customize-work.md). +> The import process supports the Hosted XML process model, which allows you to manage customizations by updating the WIT (Work Item Type) definition of a process template. This feature is only available for organizations migrated to Azure DevOps Services using the [Database Import Service](../../../../migrate/migration-overview.md). -In Azure DevOps Services, you manage customization of work tracking objects through a process. -Hosted XML processes are imported and exported through a web based administration experience. +If you use the Inheritance process model, you can customize your work tracking directly through the user interface by [creating an inherited process](../manage-process.md). For organizations using the on-premises XML process model, you can customize a process template. For more information, see the following articles: +- [Upload or download a process template](../../../../boards/work-items/guidance/manage-process-templates.md) +- [Customize a process template](../../../../reference/process-templates/customize-process.md) +- [Customize work tracking](../../../../reference/customize-work.md) -When you import a new process, you're able to create new projects using it. -When you import an existing process, all projects that use that process are updated to reflect the changes. +In Azure DevOps Services, you can customize work tracking objects using processes. Hosted XML processes allow you to import and export processes through a web-based administration interface, enabling flexibility and control over your organization's workflows. -For example, updates made to any of the custom processes listed below automatically update the two projects that use the process. - -![Custom processes mapped to projects](media/ALM_IP_ProcessUse.png) +When you import a new process, you can create new projects based on it. Importing an existing process updates all projects that use that process to reflect the changes automatically. For example, any updates made to the custom process automatically apply to the projects that use the process. -As you discover additional customizations that you need to make, you can export the existing process, update the process XML definition files, -zip the result and re-import the newly updated process. Your changes are applied to all your existing projects that use that process. +If you need to make other customizations, you can export the existing process, modify the process XML definition files, zip the updated files, and reimport the process. These changes are applied to all existing projects that use the updated process, ensuring consistency across your organization. -Import process supports the following scenarios: -* [Import an existing process from an on-premises Azure DevOps Server](#import-from-TFS) -* [Import a new process created from an existing exported process](#import-process) -* [Import an update to an existing process, and have all projects using that process be updated](#update-process) +The import process supports the following scenarios: +- [Import an existing process from an on-premises Azure DevOps Server](#import-from-TFS) +- [Import a new process created from an existing exported process](#import-process) +- [Import an update to an existing process, and update all projects using that process](#update-process) - - -## Import a process from an on-premises Azure DevOps +## Prerequisites -If you want to test your process in an on-premises Azure DevOps Server (formerly named Team Foundation Server (TFS)) to see if it works in Azure DevOps Services, perform the steps that follow. +[!INCLUDE [process-prerequisites](../../includes/process-prerequisites.md)] -In an on-premises Azure DevOps Server, each project has its own copy of a process so careful consideration needs to be made as to which processes should exist for your organization. -Migration to Azure DevOps Services is a great time to think about process alignment across your organization and reducing the number of variants of that centralized process. - -1. Run the [process export script](customize-process.md#open-process-wit) to generate a process for a given project. - -2. (Optional) Edit the ProcessTemplate.xml file name and description. Ensure it conforms to the rules and constraints outlined in [Customize a process](customize-process.md). + -3. Create a zip file of the process folder and files. +## Import a process from an on-premises Azure DevOps -4. [Import the zip file of your custom process by following the steps in the next section](#import-process). +In an on-premises Azure DevOps Server, each project maintains its own copy of a process. Therefore, it's important to carefully evaluate which processes should exist for your organization. Migration to Azure DevOps Services provides an excellent opportunity to align processes across your organization and reduce the number of process variants. Streamlining your processes ensures consistency and simplifies management in the cloud environment. -5. Repeat the above process for each process you want to import to Azure DevOps Services. +To test your process in an on-premises Azure DevOps Server to ensure it works in Azure DevOps Services, follow these steps: -6. Using the imported process(es), create projects on Azure DevOps Services for each you want to migrate. +1. Run the [process export script](customize-process.md#open-process-wit) to generate a process for a specific project. +2. (Optional) Edit the `ProcessTemplate.xml` file to update the name and description. Ensure it adheres to the rules and constraints outlined in [Customize a process](customize-process.md). +3. Compress the process folder and files into a zip file. +4. [Import the zip file of your custom process by following the steps in the next section](#import-process). +5. Repeat these steps for each process you want to import into Azure DevOps Services. +6. Once the process is imported, use it to create projects in Azure DevOps Services for each project you want to migrate. @@ -69,83 +62,76 @@ Migration to Azure DevOps Services is a great time to think about process alignm ## Import a process -Prior to importing a process, you'll want to [customize it to support your work tracking needs](customize-process.md). -Name your process something other than Scrum, Agile, or CMMI. These system processes are locked and you're prevented from overwriting them. - -1. Only members of the **Project Collection Administrators** group can import a process. To learn more, see [Change project collection-level permissions](../../../security/change-organization-collection-level-permissions.md). +Before you import a process, ensure you [customize it to meet your work tracking needs](customize-process.md). Name your process something other than Scrum, Agile, or CMMI, as these system processes are locked and you can't overwrite them. -2. From the **Processes** tab, choose import and then drag-and-drop or browse to the zip file of the process you've customized. - - > [!NOTE] - > If you don't see the **Import process** link, then your organization isn't set up to support the Hosted XML process model. You should work with the [Inheritance process model](../manage-process.md) for your customization needs. The Hosted XML process model is only supported if your account was created through the [Data Import Service](../../../../migrate/migration-overview.md). +1. From the **Processes** tab, select **Import process**, and either drag-and-drop or browse to the zip file of the customized process. - > [!div class="mx-imgBorder"] - > ![Import Process link ](media/import-process-import-link.png) + > [!NOTE] + > If the **Import process** link isn't visible, your organization isn't configured to support the Hosted XML process model. In this case, use the [Inheritance process model](../manage-process.md) for your customization needs. The Hosted XML process model is only available for accounts created through the [Data Import Service](../../../../migrate/migration-overview.md). -3. Choose the file to upload. Your [custom process must meet specific constraints](customize-process.md) in order to pass validation checks during import. + > [!div class="mx-imgBorder"] + > ![Screenshot shows Import Process link.](media/import-process-import-link.png) - > [!div class="mx-imgBorder"] - > ![Import Process dialog, choose process file to import](media/import-process-dialog.png) + Ensure that your [custom process meets specific constraints](customize-process.md) to pass validation checks during the import. - Check the **Replace existing template** if you are updating an existing template. The import process overwrites any template that has the same name as the one you import and requires that you check this box to confirm you want it replaced. + > [!div class="mx-imgBorder"] + > ![Screenshot shows Import Process dialog, choose process file to import.](media/import-process-dialog.png) - > [!IMPORTANT] - > You can't update one of the locked processes: Agile, CMMI, and Scrum. + If you're updating an existing template, check the **Replace existing template** box. This action overwrites any template with the same name as the one you're importing and requires confirmation. -3. Upon successful import, you'll see the following message. + > [!IMPORTANT] + > You can't update locked processes, such as Agile, CMMI, and Scrum. - > [!div class="mx-imgBorder"] - > ![Import Process success dialog](media/import-process-success-dialog.png) + Upon successful import, the following confirmation message displays. - If the process doesn't pass the validation checks performed on import, you'll receive a list of error messages. - [Correct each error](resolve-errors.md) and then retry the import. + > [!div class="mx-imgBorder"] + > ![Screenshot shows Import Process success dialog.](media/import-process-success-dialog.png) -4. You can immediately create a project using the newly imported process. + If the process fails validation, you receive a list of error messages. [Resolve each error](resolve-errors.md) and retry the import. - > [!div class="mx-imgBorder"] - > ![Import process actions menu, Create new team project from imported process](media/import-process-new-team-project.png) +2. Once the process successfully imports, you can immediately create a project using the new process. -5. Fill out the form that appears. To learn more about the different options, see [Create a project](../../../projects/create-project.md). + > [!div class="mx-imgBorder"] + > ![Screenshot shows Import process actions menu, Create new team project from imported process.](media/import-process-new-team-project.png) - > [!div class="mx-imgBorder"] - > ![Create new project dialog](media/create-project-from-hosted.png) +3. Complete the form that appears to create the project. For more information about the available options, see [Create a project](../../../projects/create-project.md). + > [!div class="mx-imgBorder"] + > ![Screenshot shows Create new project dialog.](media/create-project-from-hosted.png) ## Update an existing process -Once you've added a process, you can update it by importing a zip file where you've modified one or more files within the process template. +Once you add a process, you can update it by importing a zip file where you modified one or more files within the process template. > [!NOTE] ->It's a best practice to [Export a process](#export-process) before making changes so that you don't accidentally overwrite changes made by other users. - -1. Import the process according to steps 2 and 3 from the previous procedure. +> It's a best practice to [Export a process](#export-process) before making changes so that you don't accidentally overwrite changes made by other users. -2. Check the **Replace existing template** to indicate you want to overwrite the existing process. +1. Import the process according to steps 2 and 3 from the previous procedure. - > [!div class="mx-imgBorder"] - > ![Import Process dialog, replace existing process](media/import-replace-process.png) +2. Check the **Replace existing template** to indicate you want to overwrite the existing process. -3. The Import Process dialog indicates that the system is updating projects that reference the Hosted XML process. + > [!div class="mx-imgBorder"] + > ![Screenshot shows Import Process dialog, replace existing process.](media/import-replace-process.png) -4. Upon successful import, you'll see the following message. All projects that were created with the process are updated with the modifications. + The Import Process dialog indicates that the system is updating projects that reference the Hosted XML process. - > [!div class="mx-imgBorder"] - > ![Process page, Import Process success dialog, successfully imported and updated projects](media/import-process-successful-dialog.png) +3. Upon successful import, the following message displays. All projects created with the process get updated with the modifications. -5. If you renamed or deleted fields or work item types, you receive a confirmation message. - Go ahead and check the box and proceed with the import. To learn more about each message, select the forward link provided. - [Information messages](resolve-errors.md#info-only) don't require any action on your part. + > [!div class="mx-imgBorder"] + > ![Screenshot shows Process page, Import Process success dialog, successfully imported and updated projects.](media/import-process-successful-dialog.png) - ![Deleted field confirmation dialog](media/ALM_IP_InfoMessage.png) +4. If you renamed or deleted fields or work item types, you receive a confirmation message. Check the box and proceed with the import. For more information about each message, select the forward link provided. [Information messages](resolve-errors.md#info-only) don't require any action on your part. + > [!div class="mx-imgBorder"] + > ![Screenshot shows Deleted field confirmation dialog.](media/ALM_IP_InfoMessage.png) ## Set the default process -Set a process as the default to have it preselected for all new projects you plan to create. +Set a process as the default to preselect it for all new projects you plan to create. > [!div class="mx-imgBorder"] > ![Process page, hosted XML process, set as default process menu option](media/set-default-process.png) @@ -154,13 +140,18 @@ Set a process as the default to have it preselected for all new projects you pla ## Export a process -Export a process when you want to update it or use it as the basis for creating another process. +Exporting a process allows you to update an existing process or use it as a template for creating a new one. This action is useful when you need to make customizations or standardize processes across multiple projects in your organization. + +When you export a process, the system generates a zip file containing an XML representation of the process. This file includes all the process definitions, such as work item types, fields, and workflows. You can modify these XML files to meet your specific requirements and then reimport the updated process to apply the changes. + +For example, you might export a process to: +- Add custom fields or work item types. +- Adjust workflows to better align with your team's practices. +- Create a new process based on an existing one to support a different project or team. -The system exports a zip file containing an XML representation of the process. This can be modified and later imported. +After making the necessary modifications, you can reimport the process to update existing projects or create new ones using the customized process. This action ensures consistency and flexibility in managing work tracking across your Azure DevOps organization. ## Related articles - [Customize a Hosted XML process](customize-process.md) -- [Change a project from Hosted XML to an inherited process](../change-process-from-hosted-to-inherited.md) - [Clone a Hosted XML process to an Inheritance process](../upgrade-hosted-to-inherited.md) -- [Supported operations when moving from Hosted XML to an inherited process](../upgrade-support-hosted-to-inherited.md) \ No newline at end of file diff --git a/docs/organizations/settings/work/import-process/resolve-errors.md b/docs/organizations/settings/work/import-process/resolve-errors.md index 1b3e07d170b..4c203de9339 100644 --- a/docs/organizations/settings/work/import-process/resolve-errors.md +++ b/docs/organizations/settings/work/import-process/resolve-errors.md @@ -9,7 +9,7 @@ ms.topic: troubleshooting ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 01/17/2023 +ms.date: 02/10/2025 --- # Resolve validation errors for process import @@ -17,24 +17,26 @@ ms.date: 01/17/2023 [!INCLUDE [version-eq-azure-devops](../../../../includes/version-eq-azure-devops.md)] > [!IMPORTANT] -> Import process supports the Hosted XML process model which allows you to manage customizations through updating the WIT definition of a process template. This feature is only available for organizations that have been migrated to Azure DevOps Services using the [Azure DevOps data import service](../../../../migrate/migration-overview.md). [Contact us](mailto:vsocustpt@microsoft.com) if you have any questions about Azure DevOps Services process customization. +> Import process supports the Hosted XML process model which allows you to manage customizations through updating the WIT definition of a process template. This feature is only available for organizations migrated to Azure DevOps Services using the [Azure DevOps data import service](../../../../migrate/migration-overview.md). > -> If you use the Inheritance process model, you can customize your work tracking through the user interface by [creating an inherited process](../manage-process.md). If you use the On-premises XML process model, you can customize a process template, see [Upload or download a process template](../../../../boards/work-items/guidance/manage-process-templates.md) and [Customize a process template](../../../../reference/process-templates/customize-process.md). +> If you use the Inheritance process model, you can customize your work tracking through the user interface by [creating an inherited process](../manage-process.md). If you use the On-premises XML process model, you can customize a process template: [Upload or download a process template](../../../../boards/work-items/guidance/manage-process-templates.md) and [Customize a process template](../../../../reference/process-templates/customize-process.md). > ->To learn more about process models, see [Customize work tracking](../../../../reference/customize-work.md). - +> For more information, see [Customize work tracking](../../../../reference/customize-work.md). During process import, the process is validated to ensure the system works as expected for the custom process. -You'll receive a list of error messages if the process fails validation. +You receive a list of error messages if the process fails validation. ![Process successfully imported](media/ALM_IP_ValidationErrors_list_775.png) -If you've received a validation error when you tried [import process](import-process.md), you'll need to resolve the error before retrying the import. +If you received a validation error when you tried [import process](import-process.md), resolve the error before retrying the import. Each error has a link to learn more about the specific validation failure and guidance on how to correct it. -Apply the resolution fix(es) provided for the message(s) that you received, zip up the updated files, and retry the import operation. +Apply the resolution fix provided for the message that you received, zip up the updated files, and retry the import operation. If you're just starting your customization, [review the validation rules provided](customize-process.md). +## Prerequisites + +[!INCLUDE [process-prerequisites](../../includes/process-prerequisites.md)] @@ -43,7 +45,7 @@ If you're just starting your customization, [review the validation rules provide ### TF402555: Field *[refName]* is deleted. -The process that you're importing doesn't include the named field in the process being updated, therefore it is removed as part of the update operation. +The process that you're importing doesn't include the named field in the process being updated, therefore it gets removed as part of the update operation. #### Scenario example @@ -60,11 +62,11 @@ The system displays an information message about the field to be deleted. -### TF402591: Field with reference name *[refName]* cannot be renamed to '*[name1]*' from '*[name2]*' in existing processes *[processName]*. +### TF402591: Field with reference name *[refName]* can't be renamed to '*[name1]*' from '*[name2]*' in existing processes *[processName]*. -The process that you're importing contains a renamed field that uses the same `refname` in the current process(es). +The process that you're importing contains a renamed field that uses the same `refname` in the current process. -Field names cannot be renamed. +You can't rename field names. @@ -90,7 +92,7 @@ The system displays an information message about the deletion. ### TF402601: Work item type *[witName]* is renamed to *[name1]* from *[name2]*. The process contains a renamed WIT. The WIT is renamed in the existing process. -The process that you're updating contains a WIT that's been renamed from the name in the current process. +The process that you're updating contains a WIT that gets renamed from the name in the current process. As part of updating the existing process, the system renames the WIT in the current process. All work items in existing projects that reference the process are also renamed. #### Scenario example @@ -125,7 +127,7 @@ From the error message, determine and correct the source of the malformed XML. ### TF402594: File violates the schema with the following error: *[Error message]* -Each XML file in the process zip file must conform to the given schema. Schema violation errors are caused by custom XML tags or attributes within the XML file. Read the error message to determine the source of schema violation and fix accordingly. +Each XML file in the process zip file must conform to the given schema. Schema violation errors are due to custom XML tags or attributes within the XML file. Read the error message to determine the source of schema violation and fix accordingly. The schema definition for work item tracking defines all child elements within the `FORM` element as camel case and all other elements as all capitalized. If you encounter errors when validating your type definition files, check the case structure of your elements. Also, the case structure of opening and closing tags must match according to the rules for XML syntax. @@ -155,7 +157,7 @@ Correct the schema error in the named file. ## Process template plug-in errors The ProcessTemplate.xml is the root file that defines the entire process and all XML definition files that -will be imported to add or update a process. This file contains all of the plug-ins and task groups that are referenced +are imported to add or update a process. This file contains all of the plug-ins and task groups that are referenced when creating a project. Each task group references a subordinate XML file (often in a subfolder) where the specific tasks are defined. In general, you specify one task group for each plug-in. @@ -169,7 +171,7 @@ Correct the process zip package to include the named file. ### VS402452: The process template did not specify a version, or specified an invalid version. -Edit the ProcessTemplate.xml file to specify a version. +To specify a version, edit the ProcessTemplate.xml file. #### Error example @@ -210,7 +212,7 @@ Then, either update the plug-in to remove the missing named file, or add the nam #### Error example The WorkItemTracking plug-in specifies `fileName="WorkItem Tracking\TypeDefinitions\Epic.xml`, -however it hasn't been added to the WorkItem Tracking\TypeDefinitions folder. +however it isn't added to the WorkItem Tracking\TypeDefinitions folder. ```xml @@ -272,7 +274,7 @@ The WorkItems.xml file contains two `CATEGORIES` statements. #### Resolution example -The WorkItems.xml file has been updated to contain only one `CATEGORIES` statement. +The WorkItems.xml file is updated to contain only one `CATEGORIES` statement. ```xml @@ -305,7 +307,8 @@ The WorkItems.xml file contains duplicate `ProjectConfiguration` statements. ``` #### Resolution example -The WorkItems.xml file has been updated to contain only one `ProjectConfiguration` statement. +The WorkItems.xml file is updated to contain only one `ProjectConfiguration` statement. + ```xml @@ -335,7 +338,8 @@ The configuration specified is out-of-date and specifies two files that aren't c #### Resolution example -The WorkItems.xml file has been updated to contain the correct configuration `ProjectConfiguration` statement. +The WorkItems.xml file is updated to contain the correct configuration `ProjectConfiguration` statement. + ```xml @@ -448,7 +452,7 @@ Update your Categories.xml file to define the missing *[name]* category. #### Error example -ProcessConfiguration references the Epic Category, however it is missing from the Categories.xml definition file. +ProcessConfiguration references the Epic Category, however it's missing from the Categories.xml definition file. #### Resolution example @@ -468,7 +472,7 @@ Update your Categories.xml file to define the missing *[categoryName]* category. -### TF402560: You've defined *[n]* categories. Only *[nn]* are allowed. +### TF402560: You defined *[n]* categories. Only *[nn]* are allowed. Review your Categories.xml file for all `CATEGORY` element statements and determine which ones you can delete so as not exceed the allowed limit. Then, review your ProcessConfiguration.xml file to replace values that reference deleted categories. @@ -502,11 +506,11 @@ The name of the WIT referenced for Microsoft.EpicCategory is misspelled. ### TF402597: Custom category *[categoryName]* isn't supported because ProcessConfiguration doesn't reference it. You can only specify custom categories that you use to configure an Agile tool feature in the ProcessConfiguration. -Review your ProcessConfiguration.xml file and determine if you've missed adding support for a category. Otherwise, remove *[categoryName]* from the Categories.xml file. +Review your ProcessConfiguration.xml file and determine if you missed adding support for a category. Otherwise, remove *[categoryName]* from the Categories.xml file. #### Error example -ProcessConfiguration doesn't reference Microsoft.EpicCategory, although it's defined in the Categories.xml definition file. +ProcessConfiguration doesn't reference Microsoft.EpicCategory, although defined in the Categories.xml definition file. #### Resolution example @@ -523,9 +527,9 @@ Add `PortfolioBacklog` to ProcessConfiguration to reference Microsoft.EpicCatego - - - + + + @@ -572,7 +576,7 @@ Remove the duplicate statement. -### TF402512: File *[fileName]* does not exist. +### TF402512: File *[fileName]* doesn't exist. The file specified in the Classification.xml file isn't present in the specified path or the path is misspelled. @@ -598,12 +602,12 @@ The Classification folder path is misspelled. ### TF402513: Name *[pathName]* in the Classification plug-in doesn't conform to TreePath naming restrictions. -Review the `Node` elements you've specified and change the names to conform to supporting naming conventions. +Review the `Node` elements you specified and change the names to conform to supporting naming conventions. Reference: [Add and modify area and iteration paths](../../../settings/set-area-paths.md). #### Error example -The Path names include the # character which is not allowed. +The Path names include the # character which isn't allowed. ```xml @@ -615,7 +619,8 @@ The Path names include the # character which is not allowed. ``` #### Resolution example -The Path names have been corrected. +The Path names are corrected. + ```xml @@ -629,16 +634,17 @@ The Path names have been corrected. -### TF402514: Node StructureType *[structureTypeName]* in the Classification plug-in is not supported. +### TF402514: Node StructureType *[structureTypeName]* in the Classification plug-in isn't supported. The `StructureType` attribute only allows the following values: `ProjectModelHierarchy` and `ProjectLifecycle`. -Review the `Node` elements that you've specified and remove any unsupported attributes. +Review the `Node` elements that you specified and remove any unsupported attributes. #### Error example -`ProjectLifecycle` has been misspelled. +`ProjectLifecycle` is misspelled. + ```xml - + @@ -648,7 +654,8 @@ Review the `Node` elements that you've specified and remove any unsupported attr ``` #### Resolution example -Misspelled name has been corrected. +Misspelled name is corrected. + ```xml @@ -665,20 +672,21 @@ Misspelled name has been corrected. ### TF402515: A property attribute in the Classification plug-in is either missing or not supported. The `property` element only allows the following attributes: `name` , `value` , and `isFile`. -Review the `property` elements you've specified and remove any unsupported attributes. +Review the `property` elements you specified and remove any unsupported attributes. #### Error example The `value` attribute is misspelled. ```xml - + ``` #### Resolution example -Misspelled attribute has been corrected. +Misspelled attribute is corrected. + ```xml @@ -687,9 +695,9 @@ Misspelled attribute has been corrected. ``` -### TF402516: The Classification plug-in contains more than two root level Nodes, which is not supported. +### TF402516: The Classification plug-in contains more than two root level Nodes, which isn't supported. -Review the `Node` elements you've specified and remove extra root level nodes. +Review the `Node` elements you specified and remove extra root level nodes. #### Error example @@ -778,13 +786,13 @@ Update GroupsandPermissions.xml to use sprints. -### TF402561: You've defined *[n]* custom link types. Only *[nn]* are allowed. +### TF402561: You defined *[n]* custom link types. Only *[nn]* are allowed. Review your WorkItems.xml plug-in file for all `LINKTYPE` element statements. Remove statements associated with custom link types so as not exceed the allowed limit. And then, remove the corresponding link type definition file from the LinkTypes folder. -Also, remove any references to the custom link types that you've added to a WIT definition within a `LinksControlOptions` section under the `FORM` section. +Also, remove any references to the custom link types that you added to a WIT definition within a `LinksControlOptions` section under the `FORM` section. @@ -814,7 +822,7 @@ The following `LINKTYPE` element statements within the WorkItems.xml plug-in fil -### TF402564: You've defined *[n]* global lists. Only *[nn]* are allowed. +### TF402564: You defined *[n]* global lists. Only *[nn]* are allowed. One or more WITs defined in the custom process template contain a `GLOBALLIST` element. Search through your WIT definition files and replace any `GLOBALLIST` elements with `ALLOWEDVALUES` or `SUGGESTEDVALUES` elements. @@ -822,7 +830,7 @@ For reference syntax, see [Define pick lists](/previous-versions/azure/devops/re -### TF402565: You've defined *[n]* items in global list *[globalListName]*. A maximum of *[nn]* is allowed. +### TF402565: You defined *[n]* items in global list *[globalListName]*. A maximum of *[nn]* is allowed. The named `GLOBALLIST` element contains more items than allowed. Either reduce the number of list items contained in the `GLOBALLIST` element, or segment the global list into two or more elements so that neither list exceeds the maximum number of allowed items. @@ -856,7 +864,7 @@ ProcessConfiguration.xml `RequirementBacklog` element is missing a metastate map #### Resolution example -Missing metastate mappings have been added. +Missing metastate mappings are added. ```xml @@ -880,8 +888,7 @@ named element in the ProcessConfiguration.xml file to provide the missing metast ### TF402548: Element *[elementName]* requires that you map at least one state to metastate *[metastateName]*. - -Update the `States` section within the named element in the ProcessConfiguration.xml file to provide the missing metastate mapping. +To provide the missing metastate mapping, update the `States` section within the named element in the ProcessConfiguration.xml file. #### Error example @@ -900,7 +907,7 @@ ProcessConfiguration.xml `RequirementBacklog` element is missing a metastate map #### Resolution example -Missing metastate mappings have been added. +Missing metastate mappings are added. ```xml @@ -917,7 +924,7 @@ Missing metastate mappings have been added. ### TF402550: Element *[elementName]* includes more than one metastate mapping for workflow state *[stateName]*. -Metastate value cannot be mapped to more than one workflow state. +Metastate value can't be mapped to more than one workflow state. #### Error example @@ -936,7 +943,8 @@ ProcessConfiguration.xml `RequirementBacklog` element contains two metastate map #### Resolution example -Metastate mappings have been corrected. +Metastate mappings are corrected. + ```xml @@ -953,12 +961,12 @@ Metastate mappings have been corrected. ### TF402551: Work item type *[witName]* doesn't define workflow state *[stateName]*, which is required because ProcessConfiguration maps it to a metastate for element *[elementName]*. -Either correct the ProcessConfiguration.xml file or the `WORKFLOW` section of the named WIT to add the missing `STATE` and `TRANSITION` elements. +To add the missing `STATE` and `TRANSITION` elements, either correct the ProcessConfiguration.xml file or the `WORKFLOW` section of the named WIT. #### Error example -ProcessConfiguration.xml `RequirementBacklog` element specifies `value="Committed"`, however UserStory.xml doesn't define Committed as a State. +The ProcessConfiguration.xml `RequirementBacklog` element specifies `value="Committed"`, however UserStory.xml doesn't define Committed as a State. ```xml @@ -1009,7 +1017,7 @@ ProcessConfiguration.xml `RequirementBacklog` element is missing the state `New` #### Resolution example -Metastate mapping has been corrected. +Metastate mapping is corrected. ```xml @@ -1036,7 +1044,7 @@ ProcessConfiguration.xml `RequirementBacklog` element contains a misspelled meta ```xml - + @@ -1047,7 +1055,7 @@ ProcessConfiguration.xml `RequirementBacklog` element contains a misspelled meta #### Resolution example -Metastate mapping has been corrected. +Metastate mapping is corrected. ```xml @@ -1071,7 +1079,7 @@ Review [ProcessConfiguration XML element reference](../../../../reference/xml/pr ### TF402572: Cannot find specified file in the process template package. -A file specified in a plug-in file for upload is missing from the zip file. Review all files specified for upload and make sure they are included in the process zip file. +A file specified in a plug-in file for upload is missing from the zip file. Review all files specified for upload and make sure they're included in the process zip file. Review [ProcessConfiguration XML element reference](../../../../reference/xml/process-configuration-xml-element.md) for required elements. @@ -1085,17 +1093,18 @@ Review [ProcessConfiguration XML element reference](../../../../reference/xml/pr #### Example -The Scrum process specifies the following `TypeField` elements. If any of these are missing, you'll receive error TF402574. +The Scrum process specifies the following `TypeField` elements. If any of these elements are missing, you receive error TF402574. + ```xml - - - - - - - + + + + + + + @@ -1109,7 +1118,7 @@ The Scrum process specifies the following `TypeField` elements. If any of these -### TF402588: Several portfolio backlogs *[backlogNames]* have defined *[backlogName]* as their parent. A parent backlog may have only one child backlog. +### TF402588: Several portfolio backlogs *[backlogNames]* have defined *[backlogName]* as their parent. A parent backlog might have only one child backlog. Only one child portfolio backlog can map to a single parent backlog. @@ -1129,7 +1138,8 @@ Edit ProcessConfiguration to correct the parent-child backlog specifications. #### Resolution example -Change the parent on the Feature backlog to point to the Epic backlog. +To point to the Epic backlog, change the parent on the Feature backlog. + ```xml ... @@ -1167,8 +1177,8 @@ Add the Epic `PortfolioBacklog` to the ProcessConfiguration.xml file. - - + + @@ -1178,7 +1188,7 @@ Add the Epic `PortfolioBacklog` to the ProcessConfiguration.xml file. ### TF402590: Several portfolio backlogs *[Backlog 1, Backlog 2]* don't define their parent. -Only one portfolio backlog, the top backlog, may be unparented. All other backlogs must include a `parent="Microsoft.FooCategory"` attribute and value. +Only one portfolio backlog, the top backlog, might be unparented. All other backlogs must include a `parent="Microsoft.FooCategory"` attribute and value. #### Resolution example @@ -1221,7 +1231,7 @@ For more information, see [ProcessConfiguration XML element reference](../../../ ### TF400507: Each work item type must support an initial state value that matches one of the states defined in: BugWorkItems. -This error occurs when a work item type included in the `Microsoft.BugCategory` specifies an initial state that isn't included in the `BugWorkItems` section of the ProcessConfiguration XML file. Either fix the XML definition workflow states for the named work item types, or update the `BugWorkItems` section to include the missing state(s). +This error occurs when a work item type included in the `Microsoft.BugCategory` specifies an initial state that isn't included in the `BugWorkItems` section of the ProcessConfiguration XML file. Either fix the XML definition workflow states for the named work item types, or update the `BugWorkItems` section to include the missing state. For more information, see [ProcessConfiguration XML element reference](../../../../reference/xml/process-configuration-xml-element.md). @@ -1229,7 +1239,7 @@ For more information, see [ProcessConfiguration XML element reference](../../../ ### TF400572: The Project Process Settings must be configured for this feature to be used. -This is caused by templates that are from TFS 2010 or earlier versions, before the Project Process Settings existed. Try running [Configure features after an upgrade](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) to resolve, or add the [ProcessConfiguration XML file](../../../../reference/xml/process-configuration-xml-element.md) to the process template. +This error stems from old templates, before the Project Process Settings existed. Try running [Configure features after an upgrade](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) to resolve, or add the [ProcessConfiguration XML file](../../../../reference/xml/process-configuration-xml-element.md) to the process template. @@ -1238,18 +1248,18 @@ This is caused by templates that are from TFS 2010 or earlier versions, before t -### TF402570: You've defined *[n]* work item types. A maximum of *[witLimit]* is allowed. +### TF402570: You defined *[n]* work item types. A maximum of *[witLimit]* is allowed. -You've defined more WITs that are allowed in the process. Review your WorkItems.xml file and reduce the number of `WORKITEMTYPE` statements it contains and remove the associated WIT definition files from the process. +You defined more WITs that are allowed in the process. Review your WorkItems.xml file and reduce the number of `WORKITEMTYPE` statements it contains and remove the associated WIT definition files from the process. ### TF402573: Work item type WIT doesn't specify required `refname` attribute. -Work item types (Bug, User Story, Task, etc.) require the `refname` attribute. The refname value must be unique and cannot contain any reserved namespaces. -The namespaces-System.*XXX* and Microsoft.VSTS.*XXX*-are reserved by Azure DevOps. +Work item types (Bug, User Story, Task, etc.) require the `refname` attribute. The refname value must be unique and can't contain any reserved namespaces. +The namespaces-System.*XXX* and Microsoft.AzureDevOps.*XXX*-are reserved by Azure DevOps. -See [All WITD XML elements reference](/previous-versions/azure/devops/reference/xml/all-witd-xml-elements-reference) for more information. +For more information, see [All WITD XML elements reference](/previous-versions/azure/devops/reference/xml/all-witd-xml-elements-reference) for more information. #### Error example @@ -1267,14 +1277,14 @@ See [All WITD XML elements reference](/previous-versions/azure/devops/reference/ ### TF402599: The work item type refname *[refName]* isn't valid as it uses a disallowed namespace [namespace]. -Reference names of custom fields and WITs can't use reserved namespaces: System.*XXX* and Microsoft.VSTS.*XXX*. +Reference names of custom fields and WITs can't use reserved namespaces: System.*XXX* and Microsoft.AzureDevOps.*XXX*. Edit the `refname` attribute of the named WIT. #### Error example ```xml - + ``` #### Resolution example @@ -1288,7 +1298,7 @@ Edit the `refname` attribute of the named WIT. WIT reference names must adhere to established naming conventions: only letters, no spaces, and at least one period (.) -Edit the `refname` attribute of the named WIT to meet naming requirements.. +Edit the `refname` attribute of the named WIT to meet naming requirements. #### Error example @@ -1318,8 +1328,8 @@ The following rules are **not** supported for import to Azure DevOps: ### TF402539: Field *[refName]* only allows the following rules: *[ruleNames]*. -Edit your WIT definitions for the named field and remove any non-allowed rule(s). Review both the `FIELDS` and `WORKFLOW` sections. -Most system fields do not allow specifying rules. +Edit your WIT definitions for the named field and remove any nonallowed rules. Review both the `FIELDS` and `WORKFLOW` sections. +Most system fields don't allow specifying rules. #### Valid rules to use with System fields @@ -1334,7 +1344,7 @@ Most system fields do not allow specifying rules. ### TF402540: Work item type *[witName]* isn't valid because it specifies global list *[GLOBALLIST]*. Global lists aren't supported. -Global lists are not supported in VSTS. +Global lists aren't supported in Azure DevOps. Replace all instances of `GLOBALLIST` elements with `ALLOWEDVALUES` and `LISTITEM` elements in all WIT definition files. Reference: [Define pick lists](/previous-versions/azure/devops/reference/xml/define-pick-lists). @@ -1367,7 +1377,7 @@ Reference: [Define pick lists](/previous-versions/azure/devops/reference/xml/de ### TF402541: Work item type *[witName]* isn't valid because it references global list *[globalListName]*. Global lists aren't supported. -Global lists are not supported in VSTS. Replace all instances of `GLOBALLIST` elements with +Global lists aren't supported in Azure DevOps. Replace all instances of `GLOBALLIST` elements with `ALLOWEDVALUES` and `LISTITEM` elements in all WIT definition files. Reference: [Define pick lists](/previous-versions/azure/devops/reference/xml/define-pick-lists). @@ -1400,7 +1410,7 @@ Reference: [Define pick lists](/previous-versions/azure/devops/reference/xml/def ### TF402542: The custom field refname *[refName]* isn't valid as it uses disallowed namespace *[namespace]*. -The namespaces-System.*XXX* and Microsoft.VSTS.*XXX*-are reserved in VSTS. +The namespaces-System.*XXX* and Microsoft.AzureDevOps.*XXX*-are reserved in Azure DevOps. Reference names of custom fields and types can't use these namespaces. To fix this error, rename the `refname` attribute for the named field in the WIT definition files where it appears. @@ -1412,7 +1422,7 @@ To fix this error, rename the `refname` attribute for the named field in the WIT - OR - - + ``` @@ -1429,21 +1439,21 @@ To fix this error, rename the `refname` attribute for the named field in the WIT Edit the named field in the named WIT to provide the missing `ALLOWEDVALUES` rule, referencing the named element for more details. -The ProcessConfiguration.xml file element, `TypeField refname="Microsoft.VSTS.Common.Activity" type="Activity"`, -requires a pick list is defined for the Microsoft.VSTS.Common.Activity field in all WITs that belong to the Task Category. +The ProcessConfiguration.xml file element, `TypeField refname="Microsoft.AzureDevOps.Common.Activity" type="Activity"`, +requires a pick list is defined for the Microsoft.AzureDevOps.Common.Activity field in all WITs that belong to the Task Category. ```xml - + ``` -If you have added bugs to the Task Category, you must ensure that the Bug.xml file contains the +If you added bugs to the Task Category, ensure that the Bug.xml file contains the named field and specifies the same pick list as is defined for it in the Task.xml file. #### Error example Bug.xml has the field defined, but not the pick list. ```xml - + Type of work involved ``` @@ -1452,7 +1462,7 @@ Bug.xml has the field defined, but not the pick list. Corrected Bug.xml ```xml - + Type of work involved @@ -1499,7 +1509,7 @@ Missing `FIELD` elements added to the UserStory.xml file. ### To support ProcessConfiguration element *[elementName]*, work item type *[witName]* must define TypeField *[typeField]* (field refname [refName]). -In the ProcessConfiguration you created a `TypeField` with `TypeFieldValues`. In your work item type you have to reference that same `TypeField`. +In the ProcessConfiguration you created a `TypeField` with `TypeFieldValues`. In your work item type, reference that same `TypeField`. #### Error example @@ -1517,10 +1527,10 @@ ProcessConfiguration.xml ``` -FeedbackRequest.xml is using the Microsoft.VSTS.Feedback.ApplicationType field when it should be using the Custom.ApplicationType field. +FeedbackRequest.xml is using the Microsoft.AzureDevOps.Feedback.ApplicationType field when it should be using the Custom.ApplicationType field. ```xml - + ... ``` @@ -1539,29 +1549,29 @@ FeedbackRequest.xml ### TF402556: For field *[refName]* to be well defined, you must name it *[fieldName]* and set its type to *[fieldType]*. Provided *[refName]* is *[fieldName]* and type is *[fieldType]*. -If you are on an on-premises server and running **tfsMigrator**, this error is usually generated when your process is out-of-date and a system field is not properly defined. In the majority of those cases you need to use the `witadmin /changefield` command to properly rename the field. +If you are on an on-premises server and running **tfsMigrator**, this error is generated when your process is out-of-date and a system field isn't properly defined. In most cases, use the `witadmin /changefield` command to properly rename the field. #### Examples of Reserved Fields -Reserved System.*XXX* and Microsoft.VSTS.*XXX* fields have required name and type values. +Reserved System.*XXX* and Microsoft.AzureDevOps.*XXX* fields require `name` and `type` values. | Field | Name | Type | |----------------------------------------------------------|-----------------------------|------------------| | System.Id | ID | Integer | | System.Title | Title | String | -| Microsoft.VSTS.Scheduling.StoryPoints | Story Points | Double | -| Microsoft.VSTS.Scheduling.RemainingWork | Remaining Work | Double | -| Microsoft.VSTS.Scheduling.OriginalEstimate | Original Estimate | Double | -| Microsoft.VSTS.Scheduling.CompletedWork | Completed Work | Double | +| Microsoft.AzureDevOps.Scheduling.StoryPoints | Story Points | Double | +| Microsoft.AzureDevOps.Scheduling.RemainingWork | Remaining Work | Double | +| Microsoft.AzureDevOps.Scheduling.OriginalEstimate | Original Estimate | Double | +| Microsoft.AzureDevOps.Scheduling.CompletedWork | Completed Work | Double | #### Error example -TF402556: For field Microsoft.VSTS.TCM.ReproSteps to be well defined, you must name it Repro Steps and set its type to HTML. Provided Microsoft.VSTS.TCM.ReproSteps is My Repro Steps and type is HTML. +TF402556: For field Microsoft.AzureDevOps.TCM.ReproSteps to be well defined, you must name it Repro Steps and set its type to HTML. Provided Microsoft.AzureDevOps.TCM.ReproSteps is My Repro Steps and type is HTML. -In Bug.xml, the friendly field name has been changed to "My Repro Steps". +In Bug.xml, the friendly field name changed to "My Repro Steps." ```xml - + How to see the bug. End by contrasting expected with actual behavior. ``` @@ -1569,7 +1579,7 @@ In Bug.xml, the friendly field name has been changed to "My Repro Steps". Bug.xml ```xml - + How to see the bug. End by contrasting expected with actual behavior. ``` @@ -1592,7 +1602,7 @@ UserStory.xml ```xml ``` -Notice that the `name` and `type` attributes differ from that in the Bug.xml work item type +Notice that the `name` and `type` attributes differ from the Bug.xml work item type. #### Resolution example @@ -1609,9 +1619,9 @@ UserStory.xml ### TF402558: The definition of field *[refName]* is inconsistent with the existing definition of the field in the following templates: *[templateNames]*. -Fields must be defined consistently across processes that have been or that you plan to import to Azure DevOps Services. +Define fields consistently across processes you're importing to Azure DevOps Services. The system doesn't allow you to import a process that contains a `FIELD` element which is defined -one way in Process A and another way in Process B. All `FIELD` element attributes must match. +one way in Process A and another way in Process B. All `FIELD` element attributes must match. #### Example @@ -1639,43 +1649,42 @@ Notice how different values are specified for `name` and `type` attributes. ### Resolution -Ensure that fields of the same `refname` are defined the same across all processes that -have been imported or that you plan to import to Azure DevOps Services. +Ensure that fields of the same `refname` are defined the same across all processes imported or that you plan to import to Azure DevOps Services. ### TF402559: The definition for field *[refName]* is inconsistent with an existing field. The `type` is *[typeName]* but should be *[typeName]*. -Edit the WIT file(s) that contains the named field to ensure the specified `type` attribute value is consistent across all WITs. +Edit the WIT file that contains the named field to ensure the specified `type` attribute value is consistent across all WITs. -### TF402562: You've defined *[n]* fields for work item type *[witName]*. Only *[fieldLimit]* are allowed. +### TF402562: You defined *[n]* fields for work item type *[witName]*. Only *[fieldLimit]* are allowed. -You've defined *[n]* fields for work item type *[witName]*. Only *[fieldLimit]* are allowed. Within a single WIT, you can specify only the specified number of fields. +You defined *[n]* fields for work item type *[witName]*. Only *[fieldLimit]* are allowed. Within a single WIT, you can specify only the specified number of fields. Edit the named WIT and remove the extra custom fields to reduce the total number of fields to be within the allowed limit. -### TF402563: You've defined a total of *[n]* fields for all work item types. Only *[fieldLimit]* are allowed. +### TF402563: You defined a total of *[n]* fields for all work item types. Only *[fieldLimit]* are allowed. -You've defined *[n]* fields for all WITs defined in the process. Only *[fieldLimit]* are allowed. This includes System.*XXX* and Microsoft.VSTS.*XXX* namespace fields as well as custom fields. +You defined *[n]* fields for all WITs defined in the process. Only *[fieldLimit]* are allowed, which includes System.*XXX* and Microsoft.AzureDevOps.*XXX* namespace fields and custom fields. Review the `FIELDS` and `WORKFLOW` sections and determine which custom fields to remove. -### TF402566: You've defined *[n]* field rules for work item type *[witName]*. A maximum of *[ruleLimit]* is allowed. +### TF402566: You defined *[n]* field rules for work item type *[witName]*. A maximum of *[ruleLimit]* is allowed. -You've defined *[n]* field rules for the named WIT which exceeds the allowed number of field rules for any one WIT. +You defined *[n]* field rules for the named WIT which exceeds the allowed number of field rules for any one WIT. Edit the named WIT and remove the extra field rules to reduce the total number of fields to be within the allowed limit. -### TF402568: You've defined *[n]* fields with `syncnamechanges="true"` for work item type *[witName]*. A maximum of 64 is allowed. +### TF402568: You defined *[n]* fields with `syncnamechanges="true"` for work item type *[witName]*. A maximum of 64 is allowed. -The number of fields with `syncnamechanges="true"` defined for the named WIT exceeds the allowed limit. This includes System.*XXX* and Microsoft.VSTS.*XXX* namespace fields as well as custom fields. +The number of fields with `syncnamechanges="true"` defined for the named WIT exceeds the allowed limit, which includes System.*XXX* and Microsoft.AzureDevOps.*XXX* namespace fields and custom fields. Review the `FIELDS` section of the named WIT and determine which custom fields to remove or modify. @@ -1689,7 +1698,7 @@ Review the `FIELDS` section of the named WIT and determine which custom fields t -### TF402569: You've defined *[n]* values for field *[fieldName]* in work item type *[witName]*. A maximum of *[listLimit]* is allowed. +### TF402569: You defined *[n]* values for field *[fieldName]* in work item type *[witName]*. A maximum of *[listLimit]* is allowed. The number of `LISTITEM` elements defined for the named field in the named WIT exceeds the allowed limit. @@ -1714,7 +1723,7 @@ Notice the bug and user story `refname` values are different. ### TF402584: Field rule attributes "for" or "not" aren't supported. -The `"for"` and `"not"` attributes are not supported at all for any field rule for import to Azure DevOps Services. +The `"for"` and `"not"` attributes aren't supported at all for any field rule for import to Azure DevOps Services. Review the `FIELDS` and `WORKFLOW` sections for the presence of `"for"` and `"not"` attributes and remove them. #### Error example @@ -1737,9 +1746,8 @@ Review the `FIELDS` and `WORKFLOW` sections for the presence of `"for"` and `"no ### TF402593: Field rules aren't supported for field *[fieldName]*. -Most System and Microsoft.VSTS fields do not support rules. -See [Rules and rule evaluation](../rule-reference.md) -for a complete list of supported field rules. +Most System and Microsoft.AzureDevOps fields don't support rules. +For more information, see [Rules and rule evaluation](../rule-reference.md). Edit the definition files for work item types that contain the named field and remove the field rules specified for it. @@ -1747,28 +1755,29 @@ Edit the definition files for work item types that contain the named field and r ### TF402602: The field *[refName]* must have exactly these values *[values]*. -All fields defined by VSTS in the reserved namespaces-System.*XXX* and Microsoft.VSTS.*XXX*-must not be altered. If you wish to have a different list of values in these pick list fields, define your own custom field. +- **Don't alter reserved fields**: Don't alter any fields defined in the reserved namespaces `System.*XXX*` and `Microsoft.AzureDevOps.*XXX*`. +- **Define custom fields**: To have a different list of values in the pick list fields, define your own custom field. #### Error example Bug.xml has the priority field defined, but has a different list of values than expected. ```xml - + - - - + + + - + ``` #### Resolution example Corrected Bug.xml including a new field ```xml - + Business importance. 1=must fix; 4=unimportant. @@ -1792,9 +1801,9 @@ Corrected Bug.xml including a new field -### VS402504: User or group cannot be found *[project]\Group Name*. Verify that the users and groups used in your work item type definition exist. +### VS402504: User or group can't be found *[project]\Group Name*. Verify that the users and groups used in your work item type definition exist. -Custom project scoped groups are not supported. You can only reference account level scoped groups. +Custom project scoped groups aren't supported. You can only reference account level scoped groups. #### Error example @@ -1812,11 +1821,11 @@ Create a new account (collection) level group "Organization Leaders" and referen ``` > [!NOTE] -> A freshly created global group might take a little while before being found by the import process. +> A freshly created global group might take a little while before the import process locates it. -### TF237094: Field name '[fieldName]' is used by the field '[refName]', so it cannot be used by the field '[refName]'. +### TF237094: Field name '[fieldName]' is used by the field '[refName]', so it can't be used by the field '[refName]'. Field name already exist with that same name on a different field. Change the name of the field. @@ -1837,13 +1846,13 @@ Change the field name of Custom.NewField.ExternalID -### VS403104: Work item type *[witName]* references the required field *[refName]* which is not included in all layouts. +### VS403104: Work item type *[witName]* references the required field *[refName]* which isn't included in all layouts. This warning is generated if you have a required field in a work item type that is referenced in the `` node but not the ``. The `` is used to modify the layout of the new form. See [WebLayout xml reference](/previous-versions/azure/devops/reference/xml/weblayout-xml-elements) for details. -### VS403073: Group & ``: violates the rule that a group can only contain a single HTML or WebPage control preceded by label controls.. +### VS403073: Group & ``: violates the rule that a group can only contain a single HTML or WebPage control preceded by label controls. In the new form layout, a group can only contain one HTMLFieldControl or WebPageControl. @@ -1858,7 +1867,7 @@ In the new form layout, a group can only contain one HTMLFieldControl or WebPage ``` -To resolve this, create two separate groups that contain one control each. +To resolve this error, create two separate groups that contain one control each. #### Resolution example @@ -1875,7 +1884,7 @@ To resolve this, create two separate groups that contain one control each. -### TF402594: File violates the schema with the following error: The element 'Control' cannot contain child element 'Link' because the parent element's content model is empty. +### TF402594: File violates the schema with the following error: The element 'Control' can't contain child element 'Link' because the parent element's content model is empty. #### Error example @@ -1904,11 +1913,11 @@ To resolve this, create two separate groups that contain one control each. -### TF402567: You've defined *[n]* workflow states for work item type *[witName]*. A maximum of *[stateLimit]* is allowed. +### TF402567: You defined *[n]* workflow states for work item type *[witName]*. A maximum of *[stateLimit]* is allowed. -You've defined *[n]* workflow states for the named WIT which exceeds the allowed number of workflow states for any one WIT. +You defined *[n]* workflow states for the named WIT which exceeds the allowed number of workflow states for any one WIT. -Edit the `WORKFLOW` section of the named WIT and remove the extra `STATE` elements to reduce the total number of states to be within the allowed limit. +To reduce the total number of states to be within the allowed limit, edit the `WORKFLOW` section of the named WIT and remove the extra `STATE` elements. @@ -1953,7 +1962,7 @@ Process B, Bug.xml Because both fields share the same reference name, `refname="MyCompany.CustomFields.Foo"`, they must also specify the same friendly name ` @@ -2008,7 +2017,8 @@ UserStory.xml ```xml ``` -notice both `refname` values equal "MyCompany.Name" + +Both `refname` values equal "MyCompany.Name" #### Resolution example @@ -2027,13 +2037,13 @@ UserStory.xml -### TF402582: Work item type *[witName]* contains custom control *[controlName]* which is not supported. +### TF402582: Work item type *[witName]* contains custom control *[controlName]* which isn't supported. -Custom controls are not supported in Azure DevOps Services. Review the `FORM` section for the named WIT and remove any custom controls that are defined. +Custom controls aren't supported in Azure DevOps Services. Review the `FORM` section for the named WIT and remove any custom controls that are defined. #### Error example -`Type="OneViewMultiValueControl"` specifies a custom control. This must be removed or replaced to a supported control. +`Type="OneViewMultiValueControl"` specifies a custom control. Remove or replace this custom control to a supported control. ```xml @@ -2068,10 +2078,10 @@ Correct the named tasked in your TestManagement.xml file. #### Error example -The `TestResolutionStates` element has been misspelled. +The `TestResolutionStates` element is misspelled. ```xml - + ``` diff --git a/docs/organizations/settings/work/inheritance-process-model.md b/docs/organizations/settings/work/inheritance-process-model.md index 144303e21c2..f33cb1f2ef7 100644 --- a/docs/organizations/settings/work/inheritance-process-model.md +++ b/docs/organizations/settings/work/inheritance-process-model.md @@ -8,7 +8,7 @@ ms.assetid: ms.author: chcomley author: chcomley ms.topic: overview -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 07/08/2022 --- @@ -16,9 +16,9 @@ ms.date: 07/08/2022 [!INCLUDE [version-gt-eq-2019](../../../includes/version-gt-eq-2019.md)] - + -To customize the work tracking system, you *customize* an inherited process through the administrative user interface for the organization. All projects that use an inherited process get the customizations made to that process. On the other hand, you *configure* your Agile tools—[Backlogs, Sprints, Kanban boards, and Taskboard](../about-teams-and-settings.md)—for each team. +To customize the work tracking system, you *customize* an inherited process through the administrative user interface for the organization. All projects that use an inherited process get the customizations made to that process. On the other hand, you *configure* your Agile tools—[Backlogs, Sprints, boards, and Taskboards](../about-teams-and-settings.md)—for each team. > [!IMPORTANT] > To customize an on-premises project or update XML definition files to support customization, see [On-premises XML process model](../../../reference/on-premises-xml-process-model.md). This article applies to Azure DevOps Services and Azure DevOps Server 2019 only. @@ -33,8 +33,6 @@ Below you'll find an index to those tasks you can perform to customize an inheri [!INCLUDE [temp](../../../boards/includes/note-configure-customize.md)] - - ## System versus inherited processes You'll see two types of processes: @@ -42,11 +40,6 @@ You'll see two types of processes: - ![locked icon](media/process/locked-icon.png) System processes —[Agile, Basic, Scrum, and CMMI](../../../boards/work-items/guidance/choose-process.md)—which are locked from being changed. - ![inherited icon](media/process/inherited-process-icon.png) Inherited processes, which you can customize and that inherit definitions from the system process from which they were created. System processes are owned and updated periodically by Microsoft. Any updates made to a system process automatically cause an update to your inherited processes and their child inherited processes. Updates to processes are documented in the [Release Notes for Azure DevOps Server](/azure/devops/server/release-notes/azuredevops2020u1). -::: moniker range="azure-devops-2019" -> [!NOTE] -> The Basic process is available with Azure DevOps Server 2019 Update 1 and later versions. -::: moniker-end - In addition, all processes are shared. That is, one or more projects can use a single process. Instead of customizing a single project, you customize a process. Changes made to the process automatically update all projects that use that process. Once you've created an inherited process, you can customize it, create projects based on it, make a copy of it, and change existing projects to use it. @@ -87,7 +80,6 @@ Making changes to an inherited process is straight forward and safe. However, it Each inherited process you create inherits the WITs defined in the system process—Basic, Agile, Scrum, or CMMI. For example, the Agile process provides bug, task, user story, feature, epic, issue and test-related WITs. - #### [Agile process](#tab/agile-process) ![Conceptual image of Agile process work item hierarchy.](../../../boards/work-items/guidance/media/ALM_PT_Agile_WIT_Artifacts.png) @@ -111,8 +103,7 @@ Each inherited process you create inherits the WITs defined in the system proces You can add fields and modify the workflow and work item form for all inherited WITs that display on the **Work Item Types** page. If you don't want users to create a WIT, you can disable it. In addition, you can add custom WITs. - - + ## Field customizations @@ -195,22 +186,7 @@ In addition, you can [add an existing field](customize-process-field.md#add-exis - You can't change the field name or data type once you've defined it - You can't modify the gray area on the form where the State, Reason, Area Path, and iteration path fields are located -- You can't import or define a global list as supported by the Hosted XML and On-premises XML process models. To learn more, see [Define global lists](/previous-versions/azure/devops/reference/xml/define-global-lists). - -::: moniker-end - -::: moniker range="azure-devops-2019" - -- You can't change the field name or data type once you've defined it -- You can't modify the gray area on the form where the State, Reason, Area Path, and iteration path fields are located -- With regards to picklists, you currently can't perform these operations: - - Change the picklist of an inherited field, such as the Activity or Discipline field - - Change the picklist order, picklists display in alphabetic order -- You can't modify the Description help text of inherited fields -- Import or define a global list as supported by the Hosted XML and On-premises XML process models. To learn more, see [Define global lists](/previous-versions/azure/devops/reference/xml/define-global-lists). - -> [!NOTE] -> With the inherited process, you can't modify the picklists of predefined fields—such as [Activity](../../../boards/queries/query-numeric.md), [Automation Status](../../../boards/queries/build-test-integration.md), [Discipline](../../../boards/queries/query-numeric.md), [Priority](../../../boards/queries/planning-ranking-priorities.md), plus others. +- You can't import or define a global list as supported by the Hosted XML and On-premises XML process models. For more information, see [Define global lists](/previous-versions/azure/devops/reference/xml/define-global-lists). ::: moniker-end @@ -222,14 +198,13 @@ The following picklists are configured for each project and not customizable thr Picklists associated with person-name fields, such as Assigned To and Changed By, are managed based on the users you [add to a project or team](../../security/add-users-team-project.md). - ### Can I rename a field or change its data type? Renaming a field or changing the data type aren't supported actions. However, you can change the label that appears for a field on the work item form from the Layout tab. When selecting the field in a query you need to select the field name and not the field label. - + ### Can I delete or restore a deleted field? @@ -241,7 +216,6 @@ Instead of deleting a field, you may want to instead hide or remove the field fr [!INCLUDE [temp](../includes/fields-become-invalid-after-customization.md)] - ## Custom rules and system rules @@ -282,10 +256,9 @@ For example, you can make the Title or the State field Read-only for select user ::: moniker-end - ### Restrict modification of work items based on Area Path -You can disallow users from modifying select work items by setting permissions on an Area path. This is not a rule setting, but a permission setting. To learn more, see [Create child nodes, modify work items under an area path](../../security/set-permissions-access-work-tracking.md#set-permissions-area-path). +You can disallow users from modifying select work items by setting permissions on an Area path. This is not a rule setting, but a permission setting. For more information, see [Create child nodes, modify work items under an area path](../../security/set-permissions-access-work-tracking.md#set-permissions-area-path). ## Work item type (WIT) customizations @@ -334,7 +307,6 @@ Here are your customization options for inherited and custom WITs. :::row-end::: --- - #### What you can't customize - You can't add or remove an inherited WIT to or from a backlog @@ -342,7 +314,6 @@ Here are your customization options for inherited and custom WITs. - You can't remove the inherited portfolio level from the product (but you can rename them) - You can't change the name of a custom WIT. - ### Work item form customizations You can make the following customizations to a WIT form. @@ -402,7 +373,6 @@ You can make the following customizations to a WIT form. :::row-end::: --- - ### Layout and resizing @@ -441,5 +411,3 @@ When you change the default WIT for a backlog level, it causes that WIT to appea For a list of limits placed on the number of fields, WITs, backlog levels, and other objects you can customize, see [Work tracking object limits](object-limits.md). - - diff --git a/docs/organizations/settings/work/inheritance-versus-hosted-xml.md b/docs/organizations/settings/work/inheritance-versus-hosted-xml.md index 36439a66d18..d864dbbb91d 100644 --- a/docs/organizations/settings/work/inheritance-versus-hosted-xml.md +++ b/docs/organizations/settings/work/inheritance-versus-hosted-xml.md @@ -40,6 +40,8 @@ If you are currently on Hosted XML and looking to move your process to Inherited | Disable process | Supported | Supported | | REST API | Supported | Not supported | | Work item extensions | Supported | Supported | +| Steps (for other than Test Case) | Not supported | Supported | + ## Related articles diff --git a/docs/organizations/settings/work/manage-process.md b/docs/organizations/settings/work/manage-process.md index 1340867a435..0f16ead24ea 100644 --- a/docs/organizations/settings/work/manage-process.md +++ b/docs/organizations/settings/work/manage-process.md @@ -1,206 +1,194 @@ --- title: Create and manage an inherited process titleSuffix: Azure DevOps Services -description: Add custom fields, work item types, and more by creating and applying an inherited process to a project +description: Add custom fields, work item types, and more by creating and applying an inherited process to a project. ms.custom: inherited-process ms.service: azure-devops-boards ms.assetid: 6EB45080-22E2-43AD-92F9-77D03D5C136F ms.author: chcomley author: chcomley ms.topic: tutorial -monikerRange: '>= azure-devops-2019' -ms.date: 07/08/2022 +monikerRange: '<= azure-devops' +ms.date: 06/03/2024 --- - # Create and manage inherited processes -[!INCLUDE [version-gt-eq-2019](../../../includes/version-gt-eq-2019.md)] - -You customize your project, Agile tools, and the work tracking system through an inherited process. The customizations you make are in effect for all projects that use the process. A process defines the building blocks of the work tracking system. Whenever you create a project, you select the process you want your project to use. +[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -[!INCLUDE [temp](../includes/note-on-prem-link.md)] +In Azure DevOps, you have the flexibility to customize your project, Agile tools, and the work tracking system by using inherited processes. These customizations apply to all projects that utilize the same process. -To learn more about what you can customize, see [About process customization and inherited processes](inheritance-process-model.md). +An inherited process serves as the foundation for your work tracking system. When you create a new project, you choose a process to define its building blocks. These building blocks include work item types, states, fields, and rules. By customizing an inherited process, you tailor it to your team’s specific needs. -Learn how to perform these tasks: +[!INCLUDE [temp](../includes/note-on-prem-link.md)] -> [!div class="checklist"] -> * Open **Settings>Process** -> * Create an inherited process -> * Customize an inherited process -> * Copy an inherited process -> * Change projects to use an inherited process or a system process -> * Add a project based on a process -> * Enable or disable a process -> * Set a process as the default to use when adding projects +For more information about what you can customize, see [About process customization and inherited processes](inheritance-process-model.md). [!INCLUDE [temp](../includes/note-audit-log-support-process.md)] -[!INCLUDE [temp](../includes/process-prerequisites.md)] +## Prerequisites -[!INCLUDE [temp](../includes/open-process-admin-context-ts.md)] +[!INCLUDE [temp](../includes/process-prerequisites.md)] +## Create an inherited process + +Do the following steps to create an inherited process that you can customize. The default, system processes are locked, so you can't customize them. + +::: moniker range="azure-devops" + +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +2. Select ![gear icon](../../../media/icons/gear-icon.png) **Organization settings**. + ![Screenshot showing highlighted Organization settings button.](../../../media/settings/open-admin-settings-vert.png) +3. Select **Process** > **...** (More actions) > **Create inherited process**. + Choose the same system process—[Agile](../../../boards/work-items/guidance/agile-process.md), [Basic](../../../boards/get-started/plan-track-work.md), [Scrum](../../../boards/work-items/guidance/scrum-process.md), or [CMMI](../../../boards/work-items/guidance/cmmi-process.md)—that was used to create the project that you want to customize. + + In the following example, we create an inherited process from the Agile system process. -## Create an inherited process + > [!div class="mx-imgBorder"] + :::image type="content" source="media/process/create-inherited-process-menu-agile.png" alt-text="Screenshot of Context menu, Choose Create inherited process, Azure DevOps."::: + + If you don't have access to these options, ask a member of your **Project Collection Administrators** group to grant you permissions. To find a member, see [Look up a Project Collection Administrator](../../security/look-up-project-collection-administrators.md). -You can create an inherited process from any one of the four system processes: [Basic](../../../boards/get-started/plan-track-work.md), [Agile](../../../boards/work-items/guidance/agile-process.md), [Scrum](../../../boards/work-items/guidance/scrum-process.md), or [CMMI](../../../boards/work-items/guidance/cmmi-process.md). +2. Enter a name for your process and optionally a description. + Process names must be unique and no more than 128 characters. For other restrictions, see [Create and manage inheritance processes, Process name restrictions](../work/inheritance-process-model.md#process-naming). -1. From the **Process** page, open the **…** context menu of the process you'll use to create an inherited process, and then choose **Create inherited process**. + ![Screenshot showing the Create inherited process dialog.](media/process/create-inherited-process-dialog.png) - Here, we create an inherited process from the Agile system process. +::: moniker-end +::: moniker range=" < azure-devops" + +1. Sign in to your collection. +2. Select **Collection settings** or **Admin settings**. +3. Select **Process**. + > [!div class="mx-imgBorder"] - > ![Screenshot of Context menu, Choose Create inherited process.](media/process/create-inherited-process.png) + > ![Screenshot showing highlighted Process button.](media/process/open-process-2020.png) - If you don't have access to these options, ask a member of your **Project Collection Administrators** group to grant you permissions. To find a member, see [Look up a project collection administrator](../../security/look-up-project-collection-administrators.md). + > [!IMPORTANT] + > If you don't have the **Create inherited process** menu option, then the collection you selected is set to work with the on-premises XML process model. For more information, see [On-premises XML process model](../../../reference/customize-work.md). -1. Enter a name for your process and optionally a description. (For naming restrictions, see [About process customization and inherited processes, Process name restrictions](inheritance-process-model.md#process-naming). +Inherited child processes automatically update, based on their parent system processes. Updates to processes are documented in [Release Notes for Azure DevOps Server](/azure/devops/server/release-notes/azuredevops2020u1). - Create inherited process dialog. +::: moniker-end -Once you've defined the inherited process, you can perform these actions: +After you define the inherited process, you can do the following tasks: - [Customize a project using an inherited process](customize-process.md) - [Create a project](#create-team-project) that uses the inherited process -- [Change project(s) to use the inherited process](#migrate) - -> [!NOTE] -> All inherited processes and their child processes are automatically updated with any updates made to their parent system processes. Updates to processes are documented in [Release Notes for Azure DevOps Server](/azure/devops/server/release-notes/azuredevops2020u1). - +- [Change project to use the inherited process](#migrate) +## Change a project's process -## Change the process used by a project - -You can change the process a project uses from a system process or inherited process to another inherited process. There are two mechanisms to change a projects process. The first is to switch to a process where the project is derived from the same system process. Meaning, you can move a project between processes that use the same base process like Agile or Scrum. +You can change a project’s process from one inherited process to another with the following methods: -The second method is to migrate your project from one process model to another process model. For example, change the process model used by the project from Agile to Scrum, or Basic to Agile. +- **Switch within the same base process:** Move a project between processes that share the same base, such as Agile or Scrum. +- **Migrate to a different process model:** Change the project’s process model, for instance, from Agile to Scrum or Basic to Agile. -For the second method, we have provided detailed steps for three common scenarios of changing the process used by a project. +We provide detailed steps for the second method, covering the following common scenarios of process change: - [Scrum to Agile](./change-process-scrum-to-agile.md) - [Agile to Scrum](./change-process-agile-to-scrum.md) - [Basic to Agile](./change-process-basic-to-agile.md) > [!NOTE] -> You can change the process of a project as long as you don't have any undeleted work items of a custom work item type that isn't also defined in the target process. -> -> Also, if you change a project to a system process or other inherited process that doesn't contain the same custom fields, data is still maintained. However, the custom fields that aren't represented in the current process won't appear on the work item form. You can still access the field data through a query or REST APIs. These fields are essentially locked from changes and appear as read-only values. +> - You can change the process of a project as long as you don't have any undeleted work items of a custom work item type that isn't also defined in the target process. +> - If you change a project to a system process or other inherited process that doesn't contain the same custom fields, data is still maintained. But, the custom fields that aren't represented in the current process won't appear on the work item form. You can still access the field data through a query or REST APIs. These fields are essentially locked from changes and appear as read-only values. -1. Choose the process that contains the project you want to change. For example, say you want to change a project from Agile to Scrum, then choose the **Agile** process. +1. Select your project's process. For example, to change a project from Agile to Scrum, then choose the **Agile** process. > [!div class="mx-imgBorder"] > ![Screenshot of Choose the Agile process.](media/agile-to-scrum/choose-agile.png) -2. Choose **Projects**, and then choose the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon for the project you want to change, and select **Change process**. +2. Select **Projects** > the :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: actions icon for the project > **Change process**. > [!div class="mx-imgBorder"] > ![Screenshot of Choose Projects tab.](media/agile-to-scrum/choose-projects-myfirstproject.png) -Follow the steps in the wizard +3. Complete the steps in the wizard. > [!IMPORTANT] -> When you change a project to use an inherited process, you may find one or more Agile tools or work items appear in an invalid state. For example: -> -> - If you make a field required, work items with that field undefined show an error message. You'll need to resolve the errors to make additional changes and save the work item. -> - If you add or remove/hide workflow states of a WIT that appears on the Kanban board, you'll need to update the Kanban board column configurations for all teams defined in the project. +> When you switch a project to an inherited process, some Agile tools or work items might become invalid. For example: +> - If you designate a field as required, work items lacking that field display an error message. Resolve these errors to proceed with further changes and save the work item. +> - When you add or modify workflow states for a WIT visible on your board, remember to update the board column configurations for all teams within the project. ## Create a project from a process -1. Open the … context menu for the process you want to use and choose **New team project**. +1. Open the … context menu for the process you want to use and select **New team project**. ::: moniker range=">= azure-devops-2020" > [!div class="mx-imgBorder"] > ![Screenshot of Create a project from the selected process.](media/process/new-team-project-from-inherited-process-menu.png) ::: moniker-end - ::: moniker range="azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Screenshot of Create a project from selected process, Azure DevOps Server 2019.](media/process/add-new-team-project.png) - ::: moniker-end + -2. The Create new project page opens. Fill out the form. To learn more, see [Create a project](../../projects/create-project.md). +2. Enter your project information, and then select **Create**. For more information, see [Create a project](../../projects/create-project.md). ::: moniker range=">= azure-devops-2020" > [!div class="mx-imgBorder"] - > ![Create new project dialog.](media/process/create-test-project-sprint166.png) - ::: moniker-end - ::: moniker range="azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Create new project form dialog, Azure DevOps Server 2019.](media/process/create-test-project.png) + > ![Screenshot of Create new project dialog.](media/process/create-test-project-sprint166.png) ::: moniker-end + ## Copy a process -It's a good practice to test the customizations you make before rolling out the changes to your organization. To test your customization, you create a copy of a process, make your updates, verify the updates appear as desired, and then move projects to the new process. +Before you implement customizations across your organization, it's essential to test them by doing the following steps. -> [!TIP] -> If you make a change to a process that is used by one or more projects, each project that uses the process updates immediately to the incremental process change. To bundle your process changes before you roll them out to all projects, following the steps outlined next. +> [!TIP] +> If you modify a process used by multiple projects, each project immediately reflects the incremental process change. To bundle process changes before rolling them out to all projects, do the following steps. -1. Create a copy of the process that you want to change. From the **Process** page, open the … context menu for the process you want to copy and choose **Copy process**. +1. From the Process page, open the … context menu for the process and select **Create copy of process**. > [!div class="mx-imgBorder"] > ![Screenshot of selection to Make a copy of an inherited process.](media/process/copy-process.png) -2. Fill out the form with the name of the copied process and choose **Copy process**. +2. Enter a name and optional description for the copied process and select **Copy process**. > [!div class="mx-imgBorder"] - > ![Copy process dialog.](media/process/copy-process-dialog.png) + > ![Screenshot of Copy process dialog.](media/process/copy-process-dialog.png) -1. Make your changes to the copied process. Since no project is using this process, these changes do not impact any project. - -1. To verify your changes, create a test project based on the copied and updated process. If you have already created a test project, change the process of the test project using the [**Change project to use ProcessName**](#migrate) option from the context menu. - -1. Once you have fully tested your customizations, you're ready to roll out your changes to all projects. To roll out your changes, change the process of the projects that need the new changes. Select the [**Change project to use ProcessName**](#migrate) option from the context menu. - -1. Disable or delete the original process. - +3. Make your changes to the copied process. Since no project is using this process, these changes don't affect any projects. +4. Verify your changes by creating a test project based on the copied and updated process. If you already created a test project, select [**Change project to use ProcessName**](#migrate). +5. Roll out your updates by changing the process of the projects that need the new changes. Select [**Change project to use ProcessName**](#migrate). +6. Disable or delete the original process. ## Enable/disable a process -To prevent projects being created from a process, you disable it. You might choose this option when you want to apply several customizations and don't want the process used until they are complete. Or, you might want to retire use of a process in favor of moving projects to a new process. - -All system processes and newly created inherited processes are enabled by default. - -- To disable or enable a process, open the … context menu for the process and choose **Disable process** or **Enable process**. +To prevent projects being created from a specific process, you can disable it. You might choose this option when you want to apply several customizations and don't want the process used until they're complete. Or, you might retire use of a specific process in favor of moving projects to a new process. +All system processes and newly created inherited processes are enabled by default. To disable or enable a process, open the … context menu for the process and choose **Disable process** or **Enable process**. ## Set the default process -Set an inherited process as the default to have it pre-selected for other projects you plan to create. +To have an inherited process preselected for other projects you plan to create, set it as the default. This action ensures that any new projects automatically use the inherited process you choose. To set a process as the default, open the … context menu for the inherited process and choose **Set as default process**. This option isn't available with any of the system processes. Project Collection Administrators can [add projects](../../projects/create-project.md) from the **Projects** page. -## Try this next +## Next steps > [!div class="nextstepaction"] > [Add and manage fields for an inherited process](customize-process-field.md) -> Or +> or > [Add and manage work item types](customize-process-work-item-type.md) - ## Related articles - [About process customization and inherited processes](inheritance-process-model.md) - [Customize a project using an inherited process](customize-process.md). - - +- [Use the REST API for processes](/rest/api/azure/devops/processes/processes/list). - -### Programmatically work with processes - -You can get, create, update, and delete processes defined for an organization using the [REST API, Processes](/rest/api/azure/devops/processes/processes/list). diff --git a/docs/organizations/settings/work/media/change-process/change-process-basic-to-agile-wizard-choose-agile-complete.png b/docs/organizations/settings/work/media/change-process/change-process-basic-to-agile-wizard-choose-agile-complete.png index 0a7c05ba422..486603ce50a 100644 Binary files a/docs/organizations/settings/work/media/change-process/change-process-basic-to-agile-wizard-choose-agile-complete.png and b/docs/organizations/settings/work/media/change-process/change-process-basic-to-agile-wizard-choose-agile-complete.png differ diff --git a/docs/organizations/settings/work/media/change-process/change-process-basic-to-agile-wizard-choose-agile.png b/docs/organizations/settings/work/media/change-process/change-process-basic-to-agile-wizard-choose-agile.png index a3078603246..e3b5f33bd23 100644 Binary files a/docs/organizations/settings/work/media/change-process/change-process-basic-to-agile-wizard-choose-agile.png and b/docs/organizations/settings/work/media/change-process/change-process-basic-to-agile-wizard-choose-agile.png differ diff --git a/docs/organizations/settings/work/media/process/add-custom-field-verify-bug.png b/docs/organizations/settings/work/media/process/add-custom-field-verify-bug.png index 8a4a8b2855a..12116ba1144 100644 Binary files a/docs/organizations/settings/work/media/process/add-custom-field-verify-bug.png and b/docs/organizations/settings/work/media/process/add-custom-field-verify-bug.png differ diff --git a/docs/organizations/settings/work/media/process/backlog-levels.png b/docs/organizations/settings/work/media/process/backlog-levels.png new file mode 100644 index 00000000000..80329ee4c1a Binary files /dev/null and b/docs/organizations/settings/work/media/process/backlog-levels.png differ diff --git a/docs/organizations/settings/work/media/process/cpfield-add-checklist-extension.png b/docs/organizations/settings/work/media/process/cpfield-add-checklist-extension.png index f296c774800..8be3806e5cb 100644 Binary files a/docs/organizations/settings/work/media/process/cpfield-add-checklist-extension.png and b/docs/organizations/settings/work/media/process/cpfield-add-checklist-extension.png differ diff --git a/docs/organizations/settings/work/media/process/cpwit-add-new-wit.png b/docs/organizations/settings/work/media/process/cpwit-add-new-wit.png index ea91835e4a0..8a43b71177b 100644 Binary files a/docs/organizations/settings/work/media/process/cpwit-add-new-wit.png and b/docs/organizations/settings/work/media/process/cpwit-add-new-wit.png differ diff --git a/docs/organizations/settings/work/media/process/install-work-item-checklist-extension.png b/docs/organizations/settings/work/media/process/install-work-item-checklist-extension.png new file mode 100644 index 00000000000..46203af0554 Binary files /dev/null and b/docs/organizations/settings/work/media/process/install-work-item-checklist-extension.png differ diff --git a/docs/organizations/settings/work/media/process/marketplace-extension-work-item-checklist.png b/docs/organizations/settings/work/media/process/marketplace-extension-work-item-checklist.png new file mode 100644 index 00000000000..f5a04d5c48a Binary files /dev/null and b/docs/organizations/settings/work/media/process/marketplace-extension-work-item-checklist.png differ diff --git a/docs/organizations/settings/work/media/process/open-process-page-s150.png b/docs/organizations/settings/work/media/process/open-process-page-s150.png index b4fad825486..2b8a5bc3583 100644 Binary files a/docs/organizations/settings/work/media/process/open-process-page-s150.png and b/docs/organizations/settings/work/media/process/open-process-page-s150.png differ diff --git a/docs/organizations/settings/work/media/process/open-process-page.png b/docs/organizations/settings/work/media/process/open-process-page.png new file mode 100644 index 00000000000..2313ecf1c59 Binary files /dev/null and b/docs/organizations/settings/work/media/process/open-process-page.png differ diff --git a/docs/organizations/settings/work/media/process/portfolio-backlogs-modified.png b/docs/organizations/settings/work/media/process/portfolio-backlogs-modified.png index 8d2662f7c92..299c29f0362 100644 Binary files a/docs/organizations/settings/work/media/process/portfolio-backlogs-modified.png and b/docs/organizations/settings/work/media/process/portfolio-backlogs-modified.png differ diff --git a/docs/organizations/settings/work/media/process/process-backlog-levels-open.png b/docs/organizations/settings/work/media/process/process-backlog-levels-open.png index 0d3f3461f25..839be8135a3 100644 Binary files a/docs/organizations/settings/work/media/process/process-backlog-levels-open.png and b/docs/organizations/settings/work/media/process/process-backlog-levels-open.png differ diff --git a/docs/organizations/settings/work/media/process/projects-list.png b/docs/organizations/settings/work/media/process/projects-list.png index 7203bd3a235..7ac23ef2d3c 100644 Binary files a/docs/organizations/settings/work/media/process/projects-list.png and b/docs/organizations/settings/work/media/process/projects-list.png differ diff --git a/docs/organizations/settings/work/object-limits.md b/docs/organizations/settings/work/object-limits.md index 084b99ac165..f4b970cb3db 100644 --- a/docs/organizations/settings/work/object-limits.md +++ b/docs/organizations/settings/work/object-limits.md @@ -1,7 +1,7 @@ --- title: Work tracking, process, and project limits titleSuffix: Azure DevOps Services -description: Limits placed on the number of objects that can be specified for work tracking objects, queries and more +description: Limits placed on the number of objects that can be specified for work tracking objects, queries, and more. ms.custom: "inherited-process, linked-from-support, cross-project" ms.service: azure-devops-boards ms.assetid: E5FABB7C-ECA8-4FA5-9488-4AD78C60869A @@ -9,18 +9,18 @@ ms.author: chcomley author: chcomley ms.topic: conceptual monikerRange: "<= azure-devops" -ms.date: 07/07/2022 +ms.date: 09/10/2024 --- # Work tracking, process, and project limits [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -This article defines operational and object limits placed on work tracking operations and work tracking customization. In addition to the specified hard limits on select objects, certain practical limits apply. When you customize work item types (WITs), consider the limits placed on objects. +This article defines operational and object limits placed on work tracking operations and work tracking customization. In addition to the specified hard limits on specific objects, some practical limits apply. When you customize work item types (WITs), consider the limits placed on objects. ## Work items and queries -When defining work items or running queries, the following operational limits apply. +When you define work items or running queries, keep the following operational limits in mind: ::: moniker range="azure-devops" @@ -28,7 +28,7 @@ When defining work items or running queries, the following operational limits ap |--------|-------| | Attachments added to a work item | 100 | | Attachment size | 60 MB | -| Long text field | 1 M characters | +| Long text field | 1-M characters | | Query execution time | 30 seconds | | Query results | 20,000 items | | Query length | 32,000 characters | @@ -36,10 +36,9 @@ When defining work items or running queries, the following operational limits ap | Work item links assigned to a work item | 1,000 | | Work item tags assigned to a work item | 100 | | Work item revisions (REST API) | 10,000 | +| Favorite queries per project | 200 queries | -A work item revision limit of 10,000 is in effect for updates made through the REST API for Azure DevOps Services. This limit restricts updates from the REST API, however, updates from the web portal are not affected. - - +The REST API for Azure DevOps Services enforces a work item revision limit of 10,000 updates. This limit restricts updates made through the REST API, but updates from the web portal aren't affected. ::: moniker-end @@ -47,7 +46,7 @@ A work item revision limit of 10,000 is in effect for updates made through the R | Object | Limit | |--------|-------| -| Long text field | 1 M characters | +| Long text field | 1-M characters | | Work item tags assigned to a work item | 100 | | Work item links assigned to a work item | 1,000 | | Attachments added to a work item | 100 | @@ -56,51 +55,57 @@ A work item revision limit of 10,000 is in effect for updates made through the R | Query results | 20,000 items | | Query length | 32,000 characters | | Shared queries under a folder | 999 queries | +| Favorite queries per project | 200 queries | The default maximum attachment size is 4 MB. You can [change the maximum size up to 2 GB](/previous-versions/azure/devops/reference/xml/change-maximum-attachment-size-work-items). ::: moniker-end -To improve query performance, see [Guidance to create high-performing queries](../../../boards/queries/high-performing-queries.md). +To improve query performance, see [Define a query/Best practices](../../../boards/queries/using-queries.md#best-practices). ## Backlogs, boards, dashboards, and teams ::: moniker range="azure-devops" -When working with teams, work item tags, backlogs, and boards, the following operational display and object limits apply. +When you work with teams, work item tags, backlogs, and boards, the following operational display and object limits apply. | User interface | Limit | |--------|-------| | Backlogs | 10,000 work items | -| Boards | 1,000 cards (excluding those cards in the *[Proposed](../../../boards/work-items/workflow-and-state-categories.md)*[ and ](../../../boards/work-items/workflow-and-state-categories.md)*[Completed](../../../boards/work-items/workflow-and-state-categories.md)*[ workflow state categories](../../../boards/work-items/workflow-and-state-categories.md)) | +| Boards | 1,000 cards (excluding those cards in the *Proposed* and *Completed* [workflow state categories](../../../boards/work-items/workflow-and-state-categories.md)) | | Taskboard | 1,000 tasks | -| Area Paths | 10,000 per organization | +| Area Paths | 10,000 per project | | Area Path Depth | 14 | | Area Paths per team | 300 | -| Iteration Paths | 10,000 per organization | +| Iteration Paths | 10,000 per project | | Iteration Path Depth | 14 | | Iteration Paths per team | 300 | -| Project Dashboards | 500 per project | -| Team Dashboards | 500 per team | +| Project Dashboards | 500 per project. Accessible at the project level and anyone with access to the project can use. | +| Team Dashboards | 500 per team. Specific to the team and used to track team-specific metrics and data. | | Teams | 5,000 per project | | Work item tags | 150,000 tag definitions per organization or collection | -| Delivery plans per project | 1,000 | +| Delivery plans per project | 1,500 | | Templates per work item type | 100 | +Each backlog can display up to 10,000 work items. This limit applies to what the backlog can display, not to the number of work items you can define, as there's no specific limit. If your backlog exceeds this limit, consider adding a team and moving some work items to the new team's backlog. -Each backlog can display up to 10,000 work items. This is a limit on what the backlog can display, not a limit on the number of work items you can define. If your backlog exceeds this limit, then you may want to consider adding a team and moving some of the work items to the other team's backlog. - -#### Additional notes: +> [!TIP] +> If you're approaching the dashboards limits, see the following steps to manage and clean up your dashboards: +> - **Review usage:** Identify dashboards that are no longer in use or are duplicates. You can do this by checking the last accessed date or by consulting with team members. +> - **Consolidate dashboards:** Combine similar dashboards to reduce the total number. This can be done by adding multiple widgets to a single dashboard. +> - **Archive old dashboards:** If certain dashboards are no longer needed but you want to keep the data, consider exporting the data and archiving the dashboards. +> - **Use the Object Limit Tracker feature:** Provides real-time visibility into resource usage, including dashboards. This feature can help you [proactively manage your limits and avoid potential issues](https://devblogs.microsoft.com/devops/introducing-object-limit-tracker-in-azure-devops/). -- Completed or closed work items don't display on the backlogs and boards once their **Changed Date** is greater than a year old. You can still list these items using a query. If you want them to show up on a backlog or board, then you can make a minor change to them which resets the clock for display. -- Avoid nesting backlog items of the same type. To learn more, see [Fix reordering and nesting issues](../../../boards/backlogs/resolve-backlog-reorder-issues.md). -- Avoid assigning the same area paths to more than one team. To learn more, see [Limitations of multi-team Kanban board views](../../../boards/boards/kanban-overview.md#limitations-of-multi-team-kanban-board-views). -- By default, work item limits might be initially configured to lower values. +#### Other notes: +- Completed or closed work items don't display on backlogs and boards once their **Changed Date** is older than a year. You can still list these items using a query. To make them show up on a backlog or board, make a minor change to reset the display clock. +- Avoid nesting backlog items of the same type. For more information, see [Fix reordering and nesting issues](../../../boards/backlogs/resolve-backlog-reorder-issues.md). +- Avoid assigning the same area paths to more than one team. For more information, see [Limitations of multi-team board views](../../../boards/boards/kanban-overview.md). +- By default, work item limits might be set to lower values initially. ::: moniker-end ::: moniker range="< azure-devops" -When working with teams, work item tags, backlogs, and boards, the following operational limits apply. Default and maximum limits. +When you work with teams, work item tags, backlogs, and boards, the following operational limits apply. Default and maximum limits. | User interface | Limit | |--------|-------| @@ -112,34 +117,42 @@ When working with teams, work item tags, backlogs, and boards, the following ope | Work item tags | 150,000 tag definitions per project | | Templates per work item type | 100 | -Each backlog can display up to 999 work items. If your backlog exceeds this limit, then you may want to consider adding a team and moving some of the work items to the other team's backlog. +Each backlog can display up to 999 work items. If your backlog exceeds this limit, consider creating a team and moving some of the work items to the new team's backlog. -#### Additional notes: +#### Other notes: -- Avoid nesting backlog items of the same type. To learn more, see [Fix reordering and nesting issues](../../../boards/backlogs/resolve-backlog-reorder-issues.md). -- Avoid assigning the same area paths to more than one team. To learn more, see [Limitations of multi-team Kanban board views](../../../boards/boards/kanban-overview.md#limitations-of-multi-team-kanban-board-views). +- Avoid nesting backlog items of the same type. For more information, see [Fix reordering and nesting issues](../../../boards/backlogs/resolve-backlog-reorder-issues.md). +- Avoid assigning the same area paths to multiple teams. For more information, see [Limitations of multi-team board views](../../../boards/boards/kanban-overview.md). -For the On-premises XML process model, you can modify the backlog and taskboard limits by editing the ProcessConfiguration.xml file. For details, see [Process configuration XML element reference](../../../reference/xml/process-configuration-xml-element.md). +For the On-premises XML process model, you can modify the backlog and Taskboard limits by editing the `ProcessConfiguration.xml` file. For details, see [Process configuration XML element reference](../../../reference/xml/process-configuration-xml-element.md). ::: moniker-end +## GitHub integration + +If you [integrate your project with GitHub](../../../cross-service/github-integration.md), the following limits apply. + +| Integration | Limit | +|--------|-------| +| Azure Boards: Connected GitHub repositories (UX) | 1,000 repositories per connection. | +| Azure Boards: Connected GitHub repositories (API) | 2,000 repositories per connection. [Learn more](/rest/api/azure/devops/wit/github-connections/get-github-connections?view=azure-devops-rest-7.2&tabs=HTTP&preserve-view=true). | + ## Projects -Azure DevOps Services limits each organization to 1000 projects per organization, an increase over the previous limit of 300 projects. +Azure DevOps Services limits each organization to 1,000 projects per organization, an increase over the previous limit of 300 projects. > [!NOTE] -> Above 300 projects certain experiences, such as connecting to a project from Visual Studio, may start to degrade. -For on-premises Azure DevOps Server, there are no hard limits to the number of projects. However, you may find performance issues if the number of projects approaches 300. If you plan to migrate your on-premises collection to Azure DevOps Services, you'll need to observe the maximum limit of 1000 projects. If your collection has more than 1000 projects, you'll either need to split the collection or delete older projects. +> Above 300 projects, certain experiences, like connecting to a project from Visual Studio, might degrade. For on-premises Azure DevOps Server, there are no hard limits, but performance issues may arise as the number of projects nears 300. When migrating to Azure DevOps Services, observe the maximum limit of 1,000 projects. If your collection exceeds this limit, split the collection or delete older projects. For more information, see [Migrate data from Azure DevOps Server to Azure DevOps Services](../../../migrate/migration-overview.md). ## Process customization -A number of limits are imposed on the number of objects that you can define for a process. To learn about process models, see [Customize your work tracking experience](../../../reference/customize-work.md). +Many limits are imposed on the number of objects you can define for a process. For more information, see [Customize your work tracking experience](../../../reference/customize-work.md). ::: moniker range="azure-devops" -The following table lists the maximum number of objects that you can define for the Inheritance and Hosted XML process models. While these represent hard limits, practical limits may also apply. +The following table lists the maximum number of objects you can define for the Inheritance and Hosted XML process models. While these limits are hard limits, practical limits might also apply. | Object | Inheritance | Hosted XML | | --------------------------------------------------- | ----------: | ---------: | @@ -153,6 +166,7 @@ The following table lists the maximum number of objects that you can define for | Picklist item character length | 256 | - | | Workflow states defined for a work item type | 32 | 16 | | Rules defined for a work item type | 1024 | 1024 | +| Actions defined for a work item type | 1024 | 1024 | | Actions defined for a rule | 10 | 10 | | Portfolio backlog levels defined for a process | 5 | 5 | | Categories defined for a process | - | 32 | @@ -160,15 +174,15 @@ The following table lists the maximum number of objects that you can define for | List items defined within a global list | - | 1024 | | Work item attachment size | 60 MB | 60 MB | -For additional restrictions and conformance requirements of the Hosted XML process model, see [Customize a process when using Hosted XML](../../../organizations/settings/work/import-process/customize-process.md). +For other restrictions and conformance requirements of the Hosted XML process model, see [Customize a process when using Hosted XML](../../../organizations/settings/work/import-process/customize-process.md). > [!NOTE] -> For the Hosted XML process model, you can define an approximate total of 10K items for all global lists specified across all WITs. +> For the Hosted XML process model, you can define approximately 10,000 items across all global lists specified in all WITs. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!NOTE] -> For the On-premises XML process model, you can define an approximate total of 10K items for all global lists specified across all WITs. -::: moniker-end - -::: moniker range="tfs-2018" - -The following table lists the maximum number of objects that you can define for the ON-premises XML process model. While these represent hard limits, practical limits may apply. - -| Object | On-premises XML | -| --------------------------------------------------- | ---------: | -| Number of processes you can have in an organization | 64 | -| Work item types defined for a process | 64 | -| Fields defined for a collection | 1024 | -| Fields defined for a process | 1024 | -| Fields defined for a work item type | 1024 | -| Picklists defined for a collection | N/A | -| Picklist items defined for a list | 2048 | -| Picklist item character length | N/A | -| Workflow states defined for a work item type | 16 | -| Rules defined for a work item type | 1024 | -| Portfolio backlog levels defined for a process | 5 | -| Categories defined for a process | 32 | -| Global lists defined for a process | 256 | -| List items defined within a global list | 1024 | -| Size of imported process template | 2 GB | - > [!NOTE] > For the On-premises XML process model, you can define an approximate total of 10K items for all global lists specified across all WITs. ::: moniker-end ## Practical limits -We recommend that you consider the following guidance in order to minimize performance issues. +To minimize performance issues, we recommend following this guidance: ::: moniker range="azure-devops" -- Minimize the number of custom fields you define. All custom fields contribute to the total allowed for a process, collection, or organization. Note that you can specify different behavior for the same field in a different WIT. That is, you can specify different rules, picklists, and more. -- Minimize the number of rules you define for a WIT. While you can create multiple rules for a WIT, addition rules can negatively impact performance when a user adds and modifies work items. When users save work items, the system validates all rules associated with the fields for its work item type. Under certain conditions, the rule validation expression is too complex for SQL to evaluate. -- Minimize the number of custom WITs you define. +- Limit the number of custom fields you define. All custom fields contribute to the total allowed for a process, collection, or organization. You can specify different behaviors, such as rules and picklists, for the same field in different WITs. +- Limit the number of rules you define for a WIT. While you can create multiple rules for a WIT, other rules can negatively affect performance when users add or modify work items. When users save work items, the system validates all rules associated with the fields for that work item type. In some cases, the rule validation expression might be too complex for SQL to evaluate efficiently. +- Limit the number of custom WITs you define. ::: moniker-end ::: moniker range="< azure-devops" -- Minimize the number of custom fields you define. All custom fields contribute to the total allowed for a process, collection, or organization. Note that you can specify different behavior for the same field in a different WIT. That is, you can specify different rules, picklists, and more. -- Minimize the number of rules you define for a WIT. While you can create multiple rules for a WIT, addition rules can negatively impact performance when a user adds and modifies work items. When users save work items, the system validates all rules associated with the fields for its work item type. Under certain conditions, the rule validation expression is too complex for SQL to evaluate. -- Minimize the number of custom WITs you define. -- Minimize the number of reportable fields you define. Reportable fields impact performance of your data warehouse. +- Limit the number of custom fields you define. All custom fields contribute to the total allowed for a process, collection, or organization. You can specify different behaviors, such as rules and picklists, for the same field in different WITs. +- Limit the number of rules you define for a WIT. While you can create multiple rules for a WIT, other rules can negatively affect performance when users add or modify work items. When users save work items, the system validates all rules associated with the fields for that work item type. In some cases, the rule validation expression might be too complex for SQL to evaluate efficiently. +- Limit the number of custom WITs you define. +- Limit the number of reportable fields you define. Reportable fields can affect the performance of your data warehouse. ::: moniker-end > [!NOTE] -> **Work Item Rules Validation Exceeds SQL Limits**: A single SQL expression is defined per project to validate work items whenever they are created or updated. This expression grows with the number of rules you specify for all work item types defined for the project. Each behavioral qualifier specified for a field results in an increase in the number of sub-expressions. Nested rules, rules that apply only on a transition or conditioned on the value of some other field, cause more conditions to be added to an IF statement. Once the expression reaches a certain size or complexity, SQL can't evaluate it any more and generates an error. Removing some WITs or eliminating some rules, can resolve the error. - +> **Work Item Rules Validation Exceeds SQL Limits**: A single SQL expression is defined per project to validate work items whenever they are created or updated. This expression grows with the number of rules specified for all work item types in the project. Each behavioral qualifier for a field increases the number of sub-expressions. Nested rules, rules that apply only on a transition, or rules conditioned on the value of another field add more conditions to an IF statement. Once the expression reaches a certain size or complexity, SQL can no longer evaluate it and generates an error. To resolve this error, remove some WITs or eliminate some rules. ::: moniker range="azure-devops" ## Rate limits -To reduce costs and to enhance scalability and performance, Azure DevOps Services, like many Software-as-a-Service solutions, uses multi-tenancy. To ensure good performance and reduce the likelihood of outages, Azure DevOps Services limits the resources individuals can consume and the number of requests they can make to certain commands. When these limits are exceeded, subsequent requests may be either delayed or blocked. +To reduce costs and enhance scalability and performance, Azure DevOps Services, like many Software-as-a-Service solutions, uses multi-tenancy. To ensure good performance and minimize the risk of outages, Azure DevOps Services limits the resources individuals can consume and the number of requests they can make to certain commands. When these limits are exceeded, subsequent requests might be delayed or blocked. -Most rate limits are reached through REST API calls or non-optimized queries. To learn more, see the following articles: - -- [Rate limits](../../../integrate/concepts/rate-limits.md) -- [Best practices (to avoid hitting rate limits)](../../../integrate/concepts/integration-bestpractices.md) +Most rate limits are reached through REST API calls or nonoptimized queries. For more information, see [Rate limits](../../../integrate/concepts/rate-limits.md) and [Best practices (to avoid hitting rate limits)](../../../integrate/concepts/integration-bestpractices.md). ::: moniker-end ## Migrate and import limits -When determining to migrate from on-premises to Azure DevOps Services, there are several size limits that you may encounter. These limits include: +When migrating from on-premises to Azure DevOps Services, you might encounter several size limits, including: -- Database size is above the recommended size -- Largest table size is above the recommended size -- The database metadata size is above the supported size +- Database size exceeding the recommended size +- Largest table size exceeding the recommended size +- Database metadata size exceeding the supported size -To learn more, see [Migrate data from Azure DevOps Server to Azure DevOps Services](../../../migrate/migration-overview.md) and [Troubleshoot import and migration errors](../../../migrate/migration-troubleshooting.md). +For more information, see [Migrate data from Azure DevOps Server to Azure DevOps Services](../../../migrate/migration-overview.md) and [Troubleshoot import and migration errors](../../../migrate/migration-troubleshooting.md). ## Related articles ::: moniker range="azure-devops" -- [Guidance to create high-performing queries](../../../boards/queries/high-performing-queries.md) -- [About process customization and inherited processes](inheritance-process-model.md) -- [Create an Inheritance process](manage-process.md) -- [Best practices](../../../integrate/concepts/integration-bestpractices.md) -- [Naming restrictions and conventions](../naming-restrictions.md) - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - -- [Guidance to create high-performing queries](../../../boards/queries/high-performing-queries.md) -- [Customize your work tracking experience](../../../reference/customize-work.md) -- [About process customization and inherited processes](inheritance-process-model.md) -- [On-premises XML process customization](../../../reference/on-premises-xml-process-model.md) -- [Rules and rule evaluation](../../../organizations/settings/work/rule-reference.md) -- [Naming restrictions and conventions](../naming-restrictions.md) +- [Learn about process customization and inherited processes](inheritance-process-model.md) +- [Create an inheritance process](manage-process.md) +- [Follow best practices](../../../integrate/concepts/integration-bestpractices.md) +- [Adhere to naming restrictions and conventions](../naming-restrictions.md) ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range=" < azure-devops" -- [Guidance to create high-performing queries](../../../boards/queries/high-performing-queries.md) - [Customize your work tracking experience](../../../reference/customize-work.md) -- [On-premises XML process customization](../../../reference/on-premises-xml-process-model.md) -- [Rules and rule evaluation](../../../organizations/settings/work/rule-reference.md) -- [Naming restrictions and conventions](../naming-restrictions.md) +- [Learn about process customization and inherited processes](inheritance-process-model.md) +- [Customize on-premises XML processes](../../../reference/on-premises-xml-process-model.md) +- [Understand rules and rule evaluation](../../../organizations/settings/work/rule-reference.md) +- [Follow naming restrictions and conventions](../naming-restrictions.md) ::: moniker-end ## Related resources - [Tags Manager](https://marketplace.visualstudio.com/items?itemName=YodLabs.TagsManager2&ssr=false#overview) -- [WIQL Editor](https://marketplace.visualstudio.com/items?itemName=ottostreifel.wiql-editor) -- [Process Template Editor](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.msdevlabs-pte) - +- [WIQL Editor](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.wiql-editor) diff --git a/docs/organizations/settings/work/rule-reference.md b/docs/organizations/settings/work/rule-reference.md index 77ff63cce44..50285a680be 100644 --- a/docs/organizations/settings/work/rule-reference.md +++ b/docs/organizations/settings/work/rule-reference.md @@ -65,7 +65,7 @@ Default rules and behaviors that govern these fields include: 1. These rules are needed when a work item type has custom states, or the work item type is a custom work item type. 1. These rules only apply to inherited processes; they are never generated for the Hosted XML or On-premises XML processes. -Workflow states are associated with state categories to support the workflow on Kanban boards. To learn more, see [How workflow states and state categories are used in Backlogs and Boards](../../../boards/work-items/workflow-and-state-categories.md). +Workflow states are associated with state categories to support the workflow on boards. For more information, see [How workflow states and state categories are used in Backlogs and Boards](../../../boards/work-items/workflow-and-state-categories.md). ### State Change Date field rules @@ -73,7 +73,7 @@ Workflow states are associated with state categories to support the workflow on These rules are technically a lot simpler than Closed By/Closed Date rules because they are not dependent on any particular state. For any work item type, the same rules will always work. They need to be auto-generated because some OOB work item types do not contain the State Change Date field, so when the user adds this field to a custom work item type, these rules need to be auto-generated as well. The same principles for Closed By/Closed Date rules apply here as well. - + ## Custom rules @@ -92,7 +92,7 @@ Note the following: ### Rule composition - + # [Inheritance process](#tab/inheritance) @@ -198,7 +198,7 @@ The On-premises XML process defines rules using XML elements. All of these rule When you want a rule to apply to a field throughout the life of the work item, specify it within the `FIELD` section. For example, a field that is required for a bug that is new and active remains required until the bug is closed. Otherwise, if you want it applied based on a change in State, Reason, or transition, specify it within the `WORKFLOW` section. -**State** (System.State) and **Reason** (System.Reason) fields are defined within the `WORKFLOW` section. You can specify most field rules to apply to a field during a change of state, selection of a reason, or for a specific transition. To learn more, see [Change the workflow for a work item type](../../../reference/add-modify-wit.md). +**State** (System.State) and **Reason** (System.Reason) fields are defined within the `WORKFLOW` section. You can specify most field rules to apply to a field during a change of state, selection of a reason, or for a specific transition. For more information, see [Change the workflow for a work item type](../../../reference/add-modify-wit.md). Otherwise, specify a rule to be evaluated only during a change in state. These rules are defined within the `WORKFLOW` section under the `STATE`, `REASON`, or `TRANSITION` elements. All rules, except for `HELPTEXT`, can be applied within a `FIELD` (Workflow) element. @@ -273,13 +273,13 @@ The rule engine restricts setting conditions or actions to system fields except If you don't see a field listed in the drop-down menu of the rule user interface for the Inheritance process, this is why. For example, if you try to make **Area Path** (System.AreaPath) read-only based on a condition, the Area Path field isn't available for selection. Even if you're able to specify a system field, the rule engine may restrict you from saving the rule. - + ## Default and copy rules Default and copy rules modify the values of work item fields. They define run-time behavior and constraints, such as specifying default values, clearing fields, requiring fields to be defined, and more. -::: moniker range="tfs-2018 || azure-devops-2020 || azure-devops" +::: moniker range="=azure-devops-2020 || =azure-devops" You can restrict application of these rules based on the current user's group membership as described in [User or group membership rule restrictions](#membership). ::: moniker-end @@ -405,13 +405,13 @@ These rules support setting defaults, copying values from one field to another, --- - + ## Constraint rules Constraint rules restrict changing the value of a field. They define the valid states for a work item. Each constraint operates on a single field. Constraints are evaluated on the server on work item save, and if any constraint is violated the save operation is rejected. -::: moniker range="tfs-2018 || azure-devops-2020 || azure-devops" +::: moniker range="=azure-devops-2020 || =azure-devops" You can restrict application of these rules based on the current user's group membership as described in [User or group membership rule restrictions](#membership). ::: moniker-end @@ -588,7 +588,7 @@ Most of these rule actions can be applied with the selection of any condition. --- - + ## Pick lists @@ -695,7 +695,7 @@ To avoid validation errors that would otherwise occur when members leave the tea - + ## Conditional field values or changes @@ -827,9 +827,9 @@ For syntax structure and examples, see [Assign conditional-based values and rule --- - - - + + + ## User or group membership rule restrictions @@ -840,7 +840,7 @@ You can restrict application of a rule based on the current user's membership. W > [!TIP] -> To avoid rule evaluation issues that may arise, specify Azure DevOps security groups and not Azure Active Directory or Active Directory security groups. To learn more, see [Default rules and the rule engine](rule-reference.md). +> To avoid rule evaluation issues that may arise, specify Azure DevOps security groups and not Microsoft Entra ID or Active Directory security groups. For more information, see [Default rules and the rule engine](rule-reference.md). # [Inheritance process](#tab/inheritance) @@ -936,7 +936,7 @@ To restrict a rule based on the current user's membership, you specify either th - + ### Use tokens to reference users or groups @@ -951,7 +951,7 @@ Examples of tokens include the following: - [*CollectionName*], such as [fabrikam], [myorganization] -To learn about the scopes available for your project or organization, go to the **Project Settings>Permissions>Groups** or **Organization Settings>Permissions>Groups** page, you can filter the list as needed. For example, the following image shows the first four entries to a filtered list based on *Azure DevOps*. To learn more, see [Change project-level permissions](../../security/change-project-level-permissions.md) or +To learn about the scopes available for your project or organization, go to the **Project Settings>Permissions>Groups** or **Organization Settings>Permissions>Groups** page, you can filter the list as needed. For example, the following image shows the first four entries to a filtered list based on *Azure DevOps*. For more information, see [Change project-level permissions](../../security/change-project-level-permissions.md) or [Change project collection-level permissions](../../security/change-organization-collection-level-permissions.md). :::image type="content" source="media/rules/permissions-group-scope.png" alt-text="Screenshot of filtered Permissions groups list."::: @@ -985,7 +985,7 @@ Examples of tokens include the following: > [!NOTE] > [Project], [GLOBAL], and [Team Foundation] are used as is. You don't replace them with the name of the project, collection, or server name. -To learn about the scopes available for your project or collection, go to the **Project Settings>Permissions>Groups** or **Collection Settings>Permissions>Groups** page. Filter the list as needed. For example, the following image shows the first four entries to a filtered list based on *Azure DevOps*. To learn more, see [Change project-level permissions](../../security/change-project-level-permissions.md) or +To learn about the scopes available for your project or collection, go to the **Project Settings>Permissions>Groups** or **Collection Settings>Permissions>Groups** page. Filter the list as needed. For example, the following image shows the first four entries to a filtered list based on *Azure DevOps*. For more information, see [Change project-level permissions](../../security/change-project-level-permissions.md) or [Change project collection-level permissions](../../security/change-organization-collection-level-permissions.md). :::image type="content" source="media/rules/permissions-group-scope.png" alt-text="Screenshot of filtered Permissions groups list."::: @@ -1008,7 +1008,7 @@ To learn more about default security groups, see [Permissions and groups](../../ Rules that specify a condition based on the user or group membership of the user modifying a work item are evaluated in one of two ways. When the rule is evaluated, the application needs to determine whether the rule applies to the current user by checking if that user is or isn't a member of the specified group. -- When modifying the work item from the web portal, REST API, or **azure boards** command, a request to the Azure Active Directory or Active Directory is made. No problems occur for this operation. +- When modifying the work item from the web portal, REST API, or **azure boards** command, a request to the Microsoft Entra ID or Active Directory is made. No problems occur for this operation. - When modifying the work item from Visual Studio, Excel or other custom tool using the WIT Client Object Model, the request to evaluate membership is based on a client cache. The client cache is not aware of Active Directory groups. > [!NOTE] diff --git a/docs/organizations/settings/work/rule-samples.md b/docs/organizations/settings/work/rule-samples.md index 501cc0b1755..e960f84e3de 100644 --- a/docs/organizations/settings/work/rule-samples.md +++ b/docs/organizations/settings/work/rule-samples.md @@ -9,18 +9,16 @@ monikerRange: "<= azure-devops" ms.topic: sample ms.date: 06/30/2021 - #Customer intent: As a process designer, I need examples that illustrate how to define rules, so I can add the right rules to support my business processes. --- -# Sample custom rule scenarios +# Sample custom rule scenarios [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] This article provides examples of custom rule definitions. All custom rules are defined for a work item type. Examples are provided for both the Inherited and On-premises XML process models. Prior to adding custom rules, read [Rules and rule evaluation](rule-reference.md) and [Add a rule to a work item type (Inheritance process)](custom-rules.md). - @@ -56,7 +54,6 @@ You specify a `WHEN` rule statement for the field definition within the `FIELDS` --- - ## Clear the value of a dependent field @@ -65,7 +62,6 @@ The following example illustrates defining a custom rule to clear the value for # [Inheritance process](#tab/inheritance) - :::image type="content" source="media/sample-rules/clear-story-points-start-date-change.png" alt-text="Screenshot of custom rule to clear the value of Story Points when Start Date changes."::: # [On-premises XML process](#tab/on-premises) @@ -89,7 +85,6 @@ You specify a `WHENCHANGED` rule statement for the field definition within the ` --- - ## Set a dependent field value @@ -100,12 +95,10 @@ The following examples illustrate how to map the values of the **Size** field de The **Tee-Shirt Size** pick-list consists of four values *Small*, *Medium*, *Large*, and *X-Large*. Four custom rules are defined to assign the **Size** field when the **Tee-Shirt Size** field is changed to a specific value. To simplify usage, the default value of the **Tee-Shirt Size** is *Small*. - **Edit field dialog for Tee-Shirt Size field** :::image type="content" source="media/sample-rules/tee-shirt-size-edit-field-dialog.png" alt-text="Screenshot of Edit field dialog for Tee-Shirt Size field."::: - **Custom rule** :::image type="content" source="media/sample-rules/set-tshirt-size-small-rule.png" alt-text="Screenshot of custom rule to set Size value when Tee-Shirt Size is set to Small."::: @@ -153,8 +146,6 @@ You specify the value of the **Size** field in the `FIELDS` section of the work --- - - ## Require a field value upon State changes @@ -196,10 +187,8 @@ To automate clearing the **Remaining Work** field upon closing a task, define a :::image type="content" source="media/sample-rules/clear-remaining-work-closed-state.png" alt-text="Screenshot of custom rule to zero out Remaining Work required when State is changed to Closed."::: - # [On-premises XML process](#tab/on-premises) - > [!div class="tabbedCodeSnippets"] > ```XML > @@ -217,8 +206,6 @@ To automate clearing the **Remaining Work** field upon closing a task, define a --- - - ## Restrict creation of work items by a group A custom rule that restricts the transition to the *Proposed* state category of a work item type effectively disallows creation of work items of that type. By applying the rule to a specific group, you effectively disallow that group from creating work items of that type. @@ -248,7 +235,6 @@ The following custom rule restricts the Fabrikam Review Team (*for* attribute) f --- - ## Restrict modification of work items by a group For an Inheritance process, you can prevent users from modifying a work item by setting the deny permission for a group on an Area Path. For an On-premises XML process, you can place restrictions on each workflow state for a group that prevents them from saving the work item in any state. @@ -257,7 +243,7 @@ For an Inheritance process, you can prevent users from modifying a work item by It's not possible to define a custom rule that restricts modification of work items of a specific type. You can only specify restriction by state. If the user doesn't change the state, then they can modify other fields, unless all fields are made read-only for the group. -Instead, if you want to restrict a group of users from modifying select work items of any type, you can assign those work items to an Area Path. Define a security group, and then set restrictions for editing work items for that Area Path for that group as shown in the following image. To learn more, see [Set permissions and access for work tracking, Create child nodes and modify work items under an area path](../../security/set-permissions-access-work-tracking.md#set-permissions-area-path) +Instead, if you want to restrict a group of users from modifying select work items of any type, you can assign those work items to an Area Path. Define a security group, and then set restrictions for editing work items for that Area Path for that group as shown in the following image. For more information, see [Set permissions and access for work tracking, Create child nodes and modify work items under an area path](../../security/set-permissions-access-work-tracking.md#set-permissions-area-path) :::image type="content" source="media/sample-rules/restrict-modifications-by-area-path-permissions.png" alt-text="Screenshot of Permissions dialog for an Area Path to restrict modifications of work items."::: @@ -287,10 +273,9 @@ The following custom rule restricts the Fabrikam Review Team (*for* attribute) f --- - ## Restrict state transitions -For inherited processes, any-to-any state transitions are automatically defined. This allows users to advanced the workflow state from new to completed, but also to move backwards in case that is needed. When defining custom rules to restrict a transition, keep in mind that if a user makes a mistake in updating the workflow, they may not be able to correct it. For example, they could update the status by moving a work item card to a later stage on the Kanban board, but not move it back. +For inherited processes, any-to-any state transitions are automatically defined. This allows users to advanced the workflow state from new to completed, but also to move backwards in case that is needed. When defining custom rules to restrict a transition, keep in mind that if a user makes a mistake in updating the workflow, they may not be able to correct it. For example, they could update the status by moving a work item card to a later stage on the board, but not move it back. > [!TIP] > Consider restricting a state transition for some but not all users. That way, if a user makes a mistake, they can ask another team member to reset the State value to bypass the restriction. @@ -298,7 +283,7 @@ For inherited processes, any-to-any state transitions are automatically defined. Before defining state transition rules, review [Rules and rule evaluation, Auto-generated rules](rule-reference.md#auto-generated-rules) and [How workflow states and state categories are used in Backlogs and Boards](../../../boards/work-items/workflow-and-state-categories.md). - + ## Restrict modification of closed work items @@ -308,7 +293,6 @@ Depending on your business processes, you may want to prevent users from continu For the Inherited process, you can add a rule that restricts state transition. For example, the following rule restricts transitioning from closed to the other two States, New and Active. - > [!NOTE] > The `A work item state moved from ...` condition is available for Azure DevOps Server 2020 and later versions. @@ -341,7 +325,6 @@ For on-premises deployments, you can add rules to a work item type to prevent re > ``` - --- ::: moniker range=">= azure-devops-2020" @@ -354,25 +337,16 @@ For example, the following condition indicates that the Justification field is h :::image type="content" source="media/rules/rule-hide-justification-field.png" alt-text="Custom rule, Current user is not a member of a group, Hide Justification field"::: - [!INCLUDE [temp](../../../boards/includes/note-work-item-caching-rules-simple.md)] ::: moniker-end - - + ## Restrict modification of select fields based on a user or group You can customize work item types to restrict who can modify a specific field for a work item type. - -::: moniker range="azure-devops-2019" -> [!NOTE] -> For Azure DevOps Server 2019 and earlier versions, you can only restrict modification of work items based on a user or group with the On-premises XML process model. -::: moniker-end - - # [Inheritance process](#tab/inheritance) Using one of the following two conditions, you can make select fields required for a user of a security group or who are not a member of a security group. @@ -381,7 +355,7 @@ Using one of the following two conditions, you can make select fields required f - `current user is not a member of a group...` > [!TIP] -> To avoid rule evaluation issues that may arise, specify Azure DevOps security groups and not Azure Active Directory or Active Directory security groups. To learn more, see [Default rules and the rule engine](rule-reference.md). +> To avoid rule evaluation issues that may arise, specify Azure DevOps security groups and not Microsoft Entra ID or Active Directory security groups. For more information, see [Default rules and the rule engine](rule-reference.md). For example, you can make the **Title** or the **State** fields **Read-only** for select users or groups. @@ -405,8 +379,6 @@ You restrict access to work tracking objects in one of two ways: --- - - ## Related articles - [Apply rules to workflow states (Inheritance process)](apply-rules-to-workflow-states.md) diff --git a/docs/organizations/settings/work/troubleshoot-work-item-form-caching-issues.md b/docs/organizations/settings/work/troubleshoot-work-item-form-caching-issues.md deleted file mode 100644 index 992b0c37f84..00000000000 --- a/docs/organizations/settings/work/troubleshoot-work-item-form-caching-issues.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Troubleshoot work item form caching issues -titleSuffix: Azure Boards -description: Resolve work item cache rules that cause delay in server-side rule evaluations -ms.service: azure-devops-boards -ms.author: chcomley -author: chcomley -ms.topic: troubleshooting -monikerRange: "<= azure-devops" -ms.date: 04/04/2022 ---- - -# Troubleshoot work item form caching issues - -[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] - -To quickly render work items in your client or browser, several data elements are cached by the IndexDB process. A known issue exists in the cache rules that can cause a delay in server-side rule re-evaluations. - -This issue may cause rules added to a work item type to evaluate improperly. Specifically, this issue occurs when modifying a work item in a web browser and a change to a user's group membership causes a change in how a conditional rule should be evaluated. For example, a user is added to a group that lifts a restricted state change, but the user's browser doesn't immediately accept the change in the user's status. - -If you come across this issue and take no action, the issue will self-resolve. Each user's cache automatically updates every three days with a full update of membership information. Otherwise, you can resolve the issue by following the instructions provided in [Clear the IndexDB cache](#clear-cache) later in this article. - -## Background information on issue cause - -Each work item uses IndexedDB to cache work item type information and other meta data. Included in the information are rules added to the work item type. User and group-based rule restrictions are evaluated on the server-side. Permissions that prohibit or allow certain actions are applied to the user based on the evaluation. - -For the **Inherited process model**, conditional rules include rules with the following conditions: - -:::image type="content" source="media/customize-workflow/conditions-user-group-membership.png" alt-text="User and group membership conditions, Inherited process"::: - -For the **Hosted XML** and **On-premises XML** process models, conditional rules include rules with the **for** or **not** attributes, such as: - -```xml - - - -``` - -Rules are always evaluated from the web cache. Rules that are impacted by user or group membership changes aren't reevaluated in real time. While a potential solution is to invalidate the cache when updates to memberships are made, this solution runs up against performance constraints. - -## How to avoid the issue - -To avoid triggering this issue in the first place, consider adding yourself to all relevant teams before you create a work item. This action ensures that the cache stores the correct information. - - - -## Clear the IndexDB cache - -If your cache stores outdated rules, you can wait for the client cache to expire within three days or you can clear the cache. To clear the cache, run the following command in the browser command window and then refresh the browser: - -`window.indexedDB.deleteDatabase("wit")` - -## Related resources - -- [Set permissions and access for work tracking](../../security/set-permissions-access-work-tracking.md) -- [Apply rules to workflow states (Inheritance process)](apply-rules-to-workflow-states.md) -- [Add a rule to a work item type (Inheritance process)](custom-rules.md) -- [Apply or ignore rules based on user or group (On-premises XML process)](../../../organizations/settings/work/rule-reference.md#apply-or-ignore-rules-based-on-user-or-group) - diff --git a/docs/organizations/settings/work/upgrade-hosted-to-inherited.md b/docs/organizations/settings/work/upgrade-hosted-to-inherited.md index 6b9a8166f55..38f4efd1f1e 100644 --- a/docs/organizations/settings/work/upgrade-hosted-to-inherited.md +++ b/docs/organizations/settings/work/upgrade-hosted-to-inherited.md @@ -19,12 +19,9 @@ Cloning your Hosted XML process to the Inheritance process model allows you to m Before you clone a Hosted XML process, we recommend that you review [Supported operations when moving from Hosted XML process to inherited process](upgrade-support-hosted-to-inherited.md). - ## Prerequisites -- Your account currently uses the Hosted XML process model -- You must be a member of the Project Collection Administrators group, the organization owner, or be granted explicit permissions to edit, create, or manage a specific process and to create a project. - +[!INCLUDE [prerequisites-change-process](../includes/prerequisites-change-process.md)] ## Sequence of steps diff --git a/docs/organizations/settings/work/upgrade-support-hosted-to-inherited.md b/docs/organizations/settings/work/upgrade-support-hosted-to-inherited.md index bf7d4e6e9f3..5f7f0b09204 100644 --- a/docs/organizations/settings/work/upgrade-support-hosted-to-inherited.md +++ b/docs/organizations/settings/work/upgrade-support-hosted-to-inherited.md @@ -38,7 +38,7 @@ When you clone a Hosted XML process to an inherited process, the customizations > | Work item types (WITs) | All system and custom WITs are preserved. Customizations made to WIT color and icon are preserved. | > | Work item fields | All custom fields are preserved. Fields that reference global lists are updated with picklists. All default values are ignored. To learn more about supported field customizations, see [About process customization and inherited processes, Field customizations](inheritance-process-model.md#field-customizations). | > | Workflow states | All system and custom workflow states are preserved. | -> | Workflow state categories | All customizations made to the ProcessConfiguration XML file to map a workflow state to a state category (*Proposed, In Progress, Resolved, Completed*) are preserved. Only one workflow state can be assigned to the *Completed* state category. If you have assigned a custom workflow state to the *Completed* state category, it is preserved upon clone.

      Any workflow state for a work item type that isn't included in a backlog level gets assigned to the *In Progress* state category. Check all custom workflow states post clone. To learn more, see [Workflow states and state categories](../../../boards/work-items/workflow-and-state-categories.md). | +> | Workflow state categories | All customizations made to the ProcessConfiguration XML file to map a workflow state to a state category (*Proposed, In Progress, Resolved, Completed*) are preserved. Only one workflow state can be assigned to the *Completed* state category. If you have assigned a custom workflow state to the *Completed* state category, it is preserved upon clone.

      Any workflow state for a work item type that isn't included in a backlog level gets assigned to the *In Progress* state category. Check all custom workflow states post clone. For more information, see [Workflow states and state categories](../../../boards/work-items/workflow-and-state-categories.md). | > | Work item form layout | A best effort is made to preserve the customizations made to the web form layout. However, any customizations made to the header area are ignored. Specifically, the **Weblayout** `ShowEmptyReadOnlyFields` attribute assignment is ignored. | > | Backlog levels | Additions and customizations made to the product backlog and portfolio backlog levels are preserved. | > | Global lists | Global lists are converted to picklists for individual fields. | @@ -61,6 +61,7 @@ When you clone a Hosted XML process to an inherited process, the customizations > | Extensions | The inherited process supports an opt-out model for custom control extensions, while the Hosted XML process supports an opt-in model. This means that work item types defined within the cloned inherited process show all contributions from all installed and enabled extensions. You can selectively hide or remove them as needed. | > | Categories | Changes made to a [default category](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types#process) are preserved, but any custom categories are ignored. Also note that system work item types such as Issue or Impediment are not supported on a backlog level. | > | Identity fields with string values | Lists that contain an identity value in ALLOWEDVALUES or PROHIBITEDVALUES are automatically converted into the Identity field type. Any other string values in the list are ignored. | +> | Test Steps | Test steps are not supported in any work item type other than Test Case. | [!INCLUDE [temp](../includes/post-upgrade-steps.md)] diff --git a/docs/organizations/toc.yml b/docs/organizations/toc.yml index 3f35923b49c..358e82fcd72 100644 --- a/docs/organizations/toc.yml +++ b/docs/organizations/toc.yml @@ -8,9 +8,6 @@ - name: Get started as an administrator displayName: add, grant, restrict, user, permission, policies, define, customize, review, update href: ../user-guide/project-admin-tutorial.md?toc=/azure/devops/organizations/toc.json - - name: Search administrative settings - displayName: organization, keyword, notification - href: ./settings/search-settings.md?toc=/azure/devops/organizations/toc.json - name: Time zone settings displayName: timezone, organization href: ./settings/timezone-settings-usage.md?toc=/azure/devops/organizations/toc.json @@ -31,12 +28,9 @@ - name: Use personal access tokens displayName: alternate, password, create, modify, revoke href: ./accounts/use-personal-access-tokens-to-authenticate.md?toc=/azure/devops/organizations/toc.json - - name: SSH public keys - displayName: Git, repo, repository, encription, public, private, configure + - name: Use SSH public keys + displayName: Git, repo, repository, encryption, public, private, configure href: ../repos/git/use-ssh-keys-to-authenticate.md?toc=/azure/devops/organizations/toc.json - - name: Alternate credentials - displayName: Git, repository, HTTPS, SSH, OAuth, PATs - href: ../repos/git/auth-overview.md?toc=/azure/devops/organizations/toc.json - name: Manage authorizations displayName: OAuth, services, access href: ./settings/manage-authorizations.md @@ -138,14 +132,14 @@ - name: Resources items: - name: Get started - href: ../get-started/index.yml + href: ../get-started/index.yml - name: Security, Permissions, & Access - href: security/index.yml + href: security/index.yml - name: Azure Boards customization - href: ../reference/index.yml + href: ../reference/index.yml - name: Service hooks href: ../service-hooks/overview.md?toc=/azure/devops/organizations/toc.json - name: Marketplace & extensibility - href: ../marketplace-extensibility/index.yml + href: ../marketplace-extensibility/index.yml - name: Get extensions for Visual Studio >> href: /visualstudio/ide/finding-and-using-visual-studio-extensions?view=vs-2019&preserve-view=true#install-or-uninstall-visual-studio-extensions diff --git a/docs/pipelines/.openpublishing.redirection.pipelines.json b/docs/pipelines/.openpublishing.redirection.pipelines.json index 1b9518d5721..b795042c8b8 100644 --- a/docs/pipelines/.openpublishing.redirection.pipelines.json +++ b/docs/pipelines/.openpublishing.redirection.pipelines.json @@ -35,6 +35,10 @@ "redirect_url":"/azure/devops/pipelines/targets/azure-functions#deploy-a-container", "redirect_document_id": false }, + { + "source_path_from_root":"/docs/pipelines/tasks/transforms-variable-substitution.md", + "redirect_url":"/previous-versions/azure/devops/pipelines/tasks/transforms-variable-substitution?view=tfs-2018" + }, { "source_path_from_root":"/docs/pipelines/targets/webapp-on-container-linux.md", "redirect_url":"/azure/devops/pipelines/apps/cd/deploy-docker-webapp", @@ -136,6 +140,110 @@ { "source_path_from_root":"/docs/pipelines/agents/v2-osx.md", "redirect_url":"/azure/devops/pipelines/agents/osx-agent" + }, + { + "source_path_from_root":"/docs/pipelines/ecosystems/github-actions.md", + "redirect_url":"/azure/developer/github" + }, + { + "source_path_from_root":"/docs/pipelines/build/migrate-from-xaml-builds.md", + "redirect_url":"/previous-versions/azure/devops/pipelines/build/migrate-from-xaml-builds" + }, + { + "source_path_from_root":"/docs/pipelines/get-started-multiplatform.md", + "redirect_url":"/azure/devops/pipelines/yaml-schema/jobs-job-strategy#examples" + }, + { + "source_path_from_root": "/docs/pipelines/process/demands.md", + "redirect_url": "/azure/devops/pipelines/yaml-schema/pool-demands" + }, + { + "source_path_from_root": "/docs/pipelines/targets/scvmm.md", + "redirect_url": "/azure/devops/pipelines/process/environments-virtual-machines" + }, + { + "source_path": "docs/pipelines/targets/vmware.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/targets/vmware" + }, + { + "source_path": "docs/pipelines/apps/cd/azure/deploy-provision-devtest-lab.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/cd/azure/deploy-provision-devtest-lab" + }, + { + "source_path": "docs/pipelines/release/visualize-release-test-progress.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/release/visualize-release-test-progress" + }, + { + "source_path": "docs/pipelines/apps/cd/deploy-webdeploy-iis-winrm.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/cd/deploy-webdeploy-iis-winrm" + }, + { + "source_path": "docs/pipelines/apps/cd/azure/deploy-provision-azure-vm.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/cd/azure/deploy-provision-azure-vm" + }, + { + "source_path": "docs/pipelines/apps/cd/azure/deploy-azure-scaleset.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/apps/cd/azure/deploy-azure-scaleset" + }, + { + "source_path": "docs/pipelines/packages/jenkins.md", + "redirect_url": "/azure/devops/pipelines/artifacts/nuget" + }, + { + "source_path_from_root": "/docs/pipelines/release/configure-workflow-identity.md", + "redirect_url": "/azure/devops/pipelines/release/configure-workload-identity" + }, + { + "source_path_from_root": "/docs/pipelines/release/troubleshoot-workflow-identity.md", + "redirect_url": "/azure/devops/pipelines/release/troubleshoot-workload-identity" + }, + { + "source_path_from_root": "/docs/pipelines/release/integrate-jenkins-pipelines-cicd.md", + "redirect_url": "/azure/devops/pipelines/release/artifacts" + }, + { + "source_path_from_root": "/docs/pipelines/apps/cd/deploy-webdeploy-iis-deploygroups.md", + "redirect_url": "/azure/devops/pipelines/release/deploy-webdeploy-iis-deploygroups" + }, + { + "source_path_from_root": "/docs/pipelines/release/dsc-cicd.md", + "redirect_url": "/azure/devops/pipelines/release/define-multistage-release-process" + }, + { + "source_path_from_root": "/docs/pipelines/ecosystems/xamarin.md", + "redirect_url": "/azure/devops/pipelines/ecosystems/dotnet-core" + }, + { + "source_path_from_root": "/docs/pipelines/process/parameters.md", + "redirect_url": "/azure/devops/pipelines/release/parameters" + }, + { + "source_path_from_root": "/docs/pipelines/library/task-groups.md", + "redirect_url": "/azure/devops/pipelines/release/task-groups" + }, + { + "source_path_from_root": "/docs/pipelines/process/pipeline-triggers-classic.md", + "redirect_url": "/azure/devops/pipelines/release/pipeline-triggers-classic" + }, + { + "source_path_from_root": "/docs/pipelines/build/options.md", + "redirect_url": "/azure/devops/pipelines/release/options" + }, + { + "source_path_from_root": "/docs/pipelines/publish-pipeline-artifact.md", + "redirect_url": "/azure/devops/pipelines/release/publish-pipeline-artifact" + }, + { + "source_path_from_root": "/docs/pipelines/process/deployment-group-phases.md", + "redirect_url": "/azure/devops/pipelines/release/deployment-group-phases" + }, + { + "source_path_from_root": "/docs/pipelines/migrate/from-classic-pipelines.md", + "redirect_url": "/azure/devops/pipelines/release/from-classic-pipelines" + }, + { + "source_path_from_root": "/docs/pipelines/build/history.md", + "redirect_url": "/azure/devops/pipelines/release/history" } ] } diff --git a/docs/pipelines/.openpublishing.redirection.tasks.json b/docs/pipelines/.openpublishing.redirection.tasks.json index 4859eaee550..3a874c41fa6 100644 --- a/docs/pipelines/.openpublishing.redirection.tasks.json +++ b/docs/pipelines/.openpublishing.redirection.tasks.json @@ -539,6 +539,14 @@ { "source_path_from_root": "/docs/pipelines/tasks/deploy/copy-files-over-ssh.md", "redirect_url": "/azure/devops/pipelines/tasks/reference/copy-files-over-ssh-v0" + }, + { + "source_path_from_root": "/docs/pipelines/release/publish-pipeline-artifact.md", + "redirect_url": "/azure/devops/pipelines/artifacts/pipeline-artifacts" + }, + { + "source_path_from_root": "/docs/pipelines/artifacts/pull-package-gradle.md", + "redirect_url": "/azure/devops/pipelines/artifacts/build-publish-artifacts-gradle" } ] } \ No newline at end of file diff --git a/docs/pipelines/agents/agent-authentication-options.md b/docs/pipelines/agents/agent-authentication-options.md new file mode 100644 index 00000000000..d49f54ad8d4 --- /dev/null +++ b/docs/pipelines/agents/agent-authentication-options.md @@ -0,0 +1,120 @@ +--- +title: Self-hosted agent authentication options +description: Learn about authentication options for registering a self-hosted agent +ms.topic: conceptual +ms.date: 03/26/2025 +ms.custom: arm2024 +monikerRange: '<= azure-devops' +--- + +# Self-hosted agent authentication options + +Azure Pipelines provides a choice of several authentication options you can use when you are registering an agent. These methods of authentication are used only during agent registration. See [Agents communication](./agents.md#communication) for details of how agents communicate after registration. + +| Agent registration method | Azure DevOps Services | Azure DevOps Server & TFS | +|--------------------------|-----------------------|---------------------------| +| [Personal access token (PAT)](#personal-access-token-pat) | Supported | Supported when server is configured with HTTPS | +| [Service Principal (SP)](#service-principal) | Supported | Currently not supported | +| [Device code flow (Microsoft Entra ID)](#device-code-flow) | Supported | Currently not supported | +| [Integrated](#integrated) | Not supported | Windows agents only | +| [Negotiate](#negotiate) | Not supported | Windows agents only | +| [Alternate (ALT)](#alternate-alt) | Not supported | Supported when server is configured with HTTPS | + +## Personal access token (PAT) + +Specify **PAT** for authentication type during agent configuration to use a personal access token to authenticate during agent registration, then specify a personal access token (PAT) with **Agent Pools (read, manage)** scope (or **Deployment group (read, manage)** scope for a [deployment group](../release/deployment-groups/index.md) agent) can be used for agent registration. + +For more information, see [Register an agent using a personal access token (PAT)](./personal-access-token-agent-registration.md) + +## Service Principal + +Specify **SP** for authentication type during agent configuration to use a service principal to authenticate during agent registration. + +For more information, see [Register an agent using a Service Principal](./service-principal-agent-registration.md). + +## Device code flow + +Specify `AAD` for authentication type during agent configuration to use device code flow to authenticate during agent registration. + +For more information, see [Register an agent using device code flow](./device-code-flow-agent-registration.md). + +## Integrated + +:::moniker range="azure-devops" + +Integrated windows authentication for agent registration is only available for Windows agent registration on Azure DevOps Server and TFS. + +:::moniker-end + +:::moniker range="< azure-devops" + +Specify **Integrated** for authentication type during agent configuration to use integrated Windows authentication to authenticate during agent registration. + +Connect a Windows agent to TFS using the credentials of the signed-in user through a Windows authentication scheme such as NTLM or Kerberos. + +To use this method of authentication, you must first configure your TFS server. + +1. Sign into the machine where you are running TFS. + +1. Start Internet Information Services (IIS) Manager. Select your TFS site and make sure Windows Authentication is enabled with a valid provider such as NTLM or Kerberos. + +![Screenshot of IIS TFS windows authentication configuration.](media/configure-tfs-authentication/iis-tfs-authentication-windows.png) + +![Screenshot of IIS TFS windows authentication with NTLM provider configuration.](media/configure-tfs-authentication/iis-tfs-authentication-windows-ntlm-provider.png) + +:::moniker-end + +## Negotiate + +:::moniker range="azure-devops" + +The negotiate authentication method for agent registration is only available for Windows agent registration on Azure DevOps Server and TFS. + +:::moniker-end + +:::moniker range="< azure-devops" + +Connect to TFS as a user other than the signed-in user through a Windows authentication scheme such as NTLM or Kerberos. + +To use this method of authentication, you must first configure your TFS server. + +1. Log on to the machine where you are running TFS. + +1. Start Internet Information Services (IIS) Manager. Select your TFS site and make sure Windows Authentication is enabled with the Negotiate provider and with another method such as NTLM or Kerberos. + +![Screenshot of IIS TFS windows authentication configuration.](media/configure-tfs-authentication/iis-tfs-authentication-windows.png) + +![Screenshot of IIS TFS windows authentication with negotiate and NTLM provider configuration.](media/configure-tfs-authentication/iis-tfs-authentication-windows-negotiate-and-ntlm-providers.png) + +:::moniker-end + +## Alternate (ALT) + +:::moniker range="azure-devops" + +The alternate (basic) authentication method for agent registration is only available on Azure DevOps Server and TFS. + +:::moniker-end + +:::moniker range="< azure-devops" + +Connect to TFS using Basic authentication. To use this method, you must first [configure HTTPS on TFS](/azure/devops/server/admin/websitesettings). + +To use this method of authentication, you must configure your TFS server as follows: + +1. Sign in to the machine where you are running TFS. + +1. Configure basic authentication. See [Using `tfx` against Team Foundation Server 2015 using Basic Authentication](https://github.com/Microsoft/tfs-cli/blob/master/docs/configureBasicAuth.md). + +> [!NOTE] +> By product design, IIS anonymous authentication is required for OAuth authentication to work. +> This OAuth authentication is being used by Azure DevOps for the agent and pipeline functionality. For this reason even if we have agents already configured, those agents will become unusable if we disable the +> anonymous authentication. +> Azure DevOps products already have an excellent security approach. The TFS/Azure DevOps server application in IIS will not let unauthenticated requests through. That just lets it through the IIS front door to the +> application, which enforces OAuth. For example, in a pipeline run, the build server generates an OAuth token per build, which is scoped to the build and expires after the build. So even though the token is guarded, if +> leaked, it's useless after the build - contrary to an identity. The OAuth token is also not available to code run by the build process (unit tests checked in by developers). If it relied on the Windows identity the +> Windows service ran as, then developers running unit tests in the CI could elevate to access or delete code they don't have permissions to. + +:::moniker-end + + diff --git a/docs/pipelines/agents/agents.md b/docs/pipelines/agents/agents.md index aa36a508a15..f2cffa179e1 100644 --- a/docs/pipelines/agents/agents.md +++ b/docs/pipelines/agents/agents.md @@ -1,10 +1,10 @@ --- title: Azure Pipelines Agents -ms.topic: conceptual -ms.custom: seodec18 -description: Learn about building your code or deploying your software using agents in Azure Pipelines and Team Foundation Server +ms.topic: concept-article +ms.custom: devx-track-azurecli +description: Learn about building your code or deploying your software using agents in Azure Pipelines. ms.assetid: 5C14A166-CA77-4484-8074-9E0AA060DE58 -ms.date: 06/20/2023 +ms.date: 01/24/2025 monikerRange: '<= azure-devops' --- @@ -12,18 +12,21 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - -To build your code or deploy your software using Azure Pipelines, you need at least one agent. As you add more code and people, you'll eventually need more. +To build your code or deploy your software using Azure Pipelines, you need at least one agent. As your codebase and team grow, you need more agents. When your pipeline runs, the system begins one or more jobs. An agent is computing infrastructure with installed agent software that runs one job at a time. -::: moniker range=">= azure-devops-2019" +Azure Pipelines provides several different types of agents. + +| Agent type | Description | Availability | +|------------|-------------|--------------| +| [Microsoft-hosted agents](#microsoft-hosted-agents) | Agents hosted and managed by Microsoft | Azure DevOps Services | +| [Self-hosted agents](#install) | Agents that you configure and manage, hosted on your VMs | Azure DevOps Services, Azure DevOps Server | +| [Managed DevOps Pools agents](#managed-devops-pools-agents) | Managed DevOps Pools is a fully managed service where virtual machines or containers powering the agents live in a Microsoft Azure subscription and not in your own Azure subscription | Azure DevOps Services | +| [Azure Virtual Machine Scale Set agents](#azure-virtual-machine-scale-set-agents) | A form of self-hosted agents, using Azure Virtual Machine Scale Sets, that can be autoscaled to meet demands.

      If you're considering using auto-scalable self-hosted agent pools, we recommend looking at Managed DevOps Pools. For more information, see [Compare Managed DevOps Pools with Azure Virtual Machine Scale Set agents](../../managed-devops-pools/migrate-from-scale-set-agents.md) and [Managed DevOps Pools overview](../../managed-devops-pools/overview.md). | Azure DevOps Services | + +::: moniker range="<=azure-devops" Jobs can be run [directly on the host machine of the agent](../process/phases.md) or [in a container](../process/container-phases.md). ::: moniker-end @@ -37,20 +40,22 @@ Jobs can be run [directly on the host machine of the agent](../process/phases.md ::: moniker-end -

      Self-hosted agents

      +       + +## Self-hosted agents An agent that you set up and manage on your own to run jobs is a **self-hosted agent**. -You can use self-hosted agents in Azure Pipelines or Azure DevOps Server, formerly named Team Foundation Server (TFS). +You can use self-hosted agents in Azure Pipelines or Azure DevOps Server. Self-hosted agents give you more control to install dependent software needed for your builds and deployments. Also, machine-level caches and configuration persist from run to run, which can boost speed. > [!NOTE] -> Although multiple agents can be installed per machine, we strongly suggest to only install one agent per machine. Installing two or more agents may adversely affect performance and the result of your pipelines. +> Although multiple agents can be installed per machine, we strongly suggest to only install one agent per machine. Installing two or more agents might adversely affect performance and the result of your pipelines. ::: moniker range="azure-devops" > [!TIP] -> Before you install a self-hosted agent you might want to see if a Microsoft-hosted agent pool will work for you. In many cases this is the simplest way to get going. [Give it a try](hosted.md). +> Before you install a self-hosted agent, you might want to see if a Microsoft-hosted agent pool works for you. In many cases, a Microsoft-hosted agent pool is the simplest way to get going. [Give it a try](hosted.md). :::moniker-end @@ -72,7 +77,7 @@ You can install the agent on Linux, macOS, or Windows machines. You can also ins > tar xvfz vsts-agent-osx-x64-V.v.v.tar.gz > ``` -After you've installed the agent on a machine, you can install any other software on that machine as required by your jobs. +After you install the agent on a machine, you can install any other software on that machine as required by your jobs. ::: moniker range="azure-devops" @@ -85,35 +90,49 @@ After you've installed the agent on a machine, you can install any other softwar The agent ships with several versions of NodeJS libraries to support target tasks that use different Node handlers. -All official Azure DevOps tasks use Node 10 as a universal handler, however, customers may still use custom tasks -that use the outdated Node 6 library. To support backward compatibility with Node that has currently reached End-of-Life, we provide the following self-service methods to install the designated Node runner manually. +All official Azure DevOps tasks use Node 20 as a universal handler, however, customers might still use custom tasks that use the end-of-life Node 6, Node 10, or Node 16 libraries. To support backward compatibility with Node that reached End-of-Life, we provide the following self-service methods to install the designated Node runner manually. -* Manually install the Node 6 runner. For more information on manually installing the Node 6 runner, see [Node 6 support](https://github.com/microsoft/azure-pipelines-agent/blob/master/docs/noderunner.md) for more details. -* Use the [NodeTaskRunnerInstaller@0](/azure/devops/pipelines/tasks/reference/node-task-runner-installer-v0) task in your pipelines that require the outdated Node 6 library. -* Install an agent package that includes Node 6. +* Manually install the Node 6 or 10 runner. For more information, see [Node runner support](https://github.com/microsoft/azure-pipelines-agent/blob/master/docs/noderunner.md). +* Use the [NodeTaskRunnerInstaller@0](/azure/devops/pipelines/tasks/reference/node-task-runner-installer-v0) task in your pipelines that require the outdated Node 6 or 10 library. +* Install an agent package that includes Node 6 and 10. Azure Pipelines provides two versions of agent packages. - * **vsts-agent-\*** packages support Node 6. - * **pipelines-agent-\*** packages do not support Node 6. This version of the package will become the default agent package in the future. + * **vsts-agent-\*** packages support Node 6 and 10. + * **pipelines-agent-\*** packages don't support Node 6 and 10. This version of the package will become the default agent package in the future. - If you know that you are not using any Node 6 dependant tasks, and you don't want Node 6 installed on your agent machine, you can install the agent from the **Alternate Agent Downloads** section from [https://github.com/microsoft/azure-pipelines-agent/releases](https://github.com/microsoft/azure-pipelines-agent/releases). + If you know that you aren't using any Node 6 or 10 dependant tasks, and you don't want Node 6 or 10 installed on your agent machine, you can install the agent from the **Alternate Agent Downloads** section from [https://github.com/microsoft/azure-pipelines-agent/releases](https://github.com/microsoft/azure-pipelines-agent/releases). ## Azure Virtual Machine Scale Set agents -Azure Virtual Machine Scale Set agents are a form of self-hosted agents that can be auto-scaled to meet your demands. This elasticity reduces your need to run dedicated agents all the time. Unlike Microsoft-hosted agents, you have flexibility over the size and the image of machines on which agents run. +Azure Virtual Machine Scale Set agents are a form of self-hosted agents that can be autoscaled to meet your demands. This elasticity reduces your need to run dedicated agents all the time. Unlike Microsoft-hosted agents, you have flexibility over the size and the image of machines on which agents run. -You specify a Virtual Machine Scale Set, a number of agents to keep on standby, a maximum number of virtual machines in the scale set, and Azure Pipelines manages the scaling of your agents for you. +You specify a Virtual Machine Scale Set, the number of agents to keep on standby, a maximum number of virtual machines in the scale set, and Azure Pipelines manages the scaling of your agents for you. For more information, see [Azure Virtual Machine Scale Set agents](scale-set-agents.md). +[!INCLUDE [mdp-recommended](../../managed-devops-pools/includes/mdp-recommended.md)] + +## Managed DevOps Pools agents + +Managed DevOps Pools empowers development teams to quickly and easily spin up Azure DevOps agent pools that are tailored to a team's specific needs. + +Managed DevOps Pools: + +- implements security best practices +- provides knobs to balance cost and performance +- provides paths for the most common scenarios +- significantly reduces time spent in creating and maintaining custom pools + +Managed DevOps Pools is an evolution of Azure DevOps Virtual Machine Scale Set agent pools, They simplify custom pool creation even further by improving scalability and reliability of custom pools. Managed DevOps Pools is a fully managed service where virtual machines or containers powering the agents live in a Microsoft Azure subscription and not in your own Azure subscription, like when using Azure DevOps Virtual Machine Scale Set agent pools. For more information, see the [Managed DevOps Pools](../../managed-devops-pools/index.yml) documentation. + ::: moniker-end ## Parallel jobs ::: moniker range="azure-devops" -**Parallel jobs** represents the number of jobs you can run at the same time in your organization. If your organization has a single parallel job, you can run a single job at a time in your organization, with any additional concurrent jobs being queued until the first job completes. To run two jobs at the same time, you need two parallel jobs. In Azure Pipelines, you can run parallel jobs on Microsoft-hosted infrastructure or on your own (self-hosted) infrastructure. +**Parallel jobs** represents the number of jobs you can run at the same time in your organization. If your organization has a single parallel job, you can run a single job at a time in your organization, with any other concurrent jobs being queued until the first job completes. To run two jobs at the same time, you need two parallel jobs. In Azure Pipelines, you can run parallel jobs on Microsoft-hosted infrastructure or on your own (self-hosted) infrastructure. Microsoft provides a free tier of service by default in every organization that includes at least one parallel job. Depending on the number of concurrent pipelines you need to run, you might need more parallel jobs to use multiple Microsoft-hosted or self-hosted agents at the same time. For more information on parallel jobs and different free tiers of service, see [Parallel jobs in Azure Pipelines](../licensing/concurrent-jobs.md). @@ -123,38 +142,67 @@ Microsoft provides a free tier of service by default in every organization that You might need more parallel jobs to use multiple agents at the same time: -* [Parallel jobs in TFS](../licensing/concurrent-pipelines-tfs.md) +* [Parallel jobs in Azure DevOps Server](../licensing/concurrent-pipelines-tfs.md) ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!IMPORTANT] -> Starting with Azure DevOps Server 2019, you do not have to pay for self-hosted concurrent jobs in releases. You are only limited by the number of agents that you have. +> Starting with Azure DevOps Server 2019, you don't have to pay for self-hosted concurrent jobs in releases. You're only limited by the number of agents that you have. ::: moniker-end

      Capabilities

      -Every self-hosted agent has a set of capabilities that indicate what it can do. Capabilities are name-value pairs that are either automatically discovered by the agent software, in which case they are called **system capabilities**, or those that you define, in which case they are called **user capabilities**. +Every self-hosted agent has a set of capabilities that indicate what it can do. Capabilities are name-value pairs that are either automatically discovered by the agent software, called **system capabilities**, or capabilities that you define, called **user capabilities**. The agent software automatically determines various system capabilities such as the name of the machine, type of operating system, and versions of certain software installed on the machine. Also, environment variables defined in the machine automatically appear in the list of system capabilities. > [!NOTE] -> Storing environment variables as capabilities means that when an agent runs, the stored capability values are used to set the environment variables. Also, any changes to environment variables that are made while the agent is running won't be picked up and used by any task. If you have sensitive environment variables that change and you don't want them to be stored as capabilities, you can have them ignored by setting the `VSO_AGENT_IGNORE` environment variable, with a comma-delimited list of variables to ignore. For example, `PATH` is a critical variable that you might want to ignore if you're installing software. +> Storing environment variables as capabilities means that when an agent runs, the stored capability values are used to set the environment variables. Also, any changes to environment variables that are made while the agent is running aren't picked up and used by any task. If you have sensitive environment variables that change and you don't want them to be stored as capabilities, you can have them ignored by setting the `VSO_AGENT_IGNORE` environment variable, with a comma-delimited list of variables to ignore. For example, `PATH` is a critical variable that you might want to ignore if you're installing software. -When you author a pipeline, you specify certain **demands** of the agent. The system sends the job only to agents that have capabilities matching the [demands](../process/demands.md) specified in the pipeline. As a result, agent capabilities allow you to direct jobs to specific agents. +When you author a pipeline, you specify certain **demands** of the agent. The system sends the job only to agents that have capabilities matching the [demands](/azure/devops/pipelines/yaml-schema/pool-demands) specified in the pipeline. As a result, agent capabilities allow you to direct jobs to specific agents. > [!NOTE] > > Demands and capabilities are designed for use with self-hosted agents so that jobs can be matched with an agent that > meets the requirements of the job. When using Microsoft-hosted agents, you select an image for the agent that -> matches the requirements of the job, so although it is possible to add capabilities to a Microsoft-hosted agent, you don't need +> matches the requirements of the job. Although it's possible to add capabilities to a Microsoft-hosted agent, you don't need > to use capabilities with Microsoft-hosted agents. +### Configure demands + +# [YAML](#tab/yaml) + +:::moniker range="<=azure-devops" + +To add a demand to your YAML build pipeline, add the `demands:` line to the `pool` section. + +```yaml +pool: + name: Default + demands: SpecialSoftware # exists check for SpecialSoftware +``` + +You can check for the existence of a capability, or make a comparison with the value of a capability. For more information, see [YAML schema - Demands](/azure/devops/pipelines/yaml-schema/pool-demands). + +:::moniker-end + +# [Classic](#tab/classic) + +In the Tasks tab of the pipeline, add the demand to your agent job. + +| Name | Condition | Value | +|---|---|---| +| SpecialSoftware | exists | N/A | +| Agent.OS | equals | Linux | + +--- + ### Configure agent capabilities -#### [Browser](#tab/browser) +#### [Azure Pipelines UI](#tab/browser) You can view the details of an agent, including its version and system capabilities, and manage its user capabilities, by navigating to **Agent pools** and selecting the **Capabilities** tab for the desired agent. @@ -170,9 +218,9 @@ You can view the details of an agent, including its version and system capabilit #### [Azure DevOps CLI](#tab/azure-devops-cli/) -::: moniker range="> azure-devops-2019" +::: moniker range="azure-devops" -You can view the details of an agent, including its version, and system and user capabilities, by using the following [az pipelines agent](/cli/azure/pipelines/agent) Azure CLI methods. +You can view the details of an agent, including its version and capabilities, by using the following [az pipelines agent](/cli/azure/pipelines/agent) Azure CLI methods. [List agents](#list-agents) | [Show agent details](#show-agent-details) @@ -205,7 +253,7 @@ az pipelines agent list --pool-id - **include-capabilities**: Whether to include the agents' capabilities in the response. Accepted values: **false**, **true** - **include-last-completed-request**: Whether to include details about the agents' most recent completed work. Accepted values: **false**, **true** - **org** or **organization**: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`. -- **subscription**: Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID. +- **subscription**: Name or ID of subscription. You can configure the default subscription using az account set `-s NAME_OR_ID`. #### Example @@ -242,20 +290,13 @@ az pipelines agent show --agent-id - **include-assigned-request**: Whether to include details about the agents' current work. Accepted values: **false**, **true** - **include-capabilities**: Whether to include the agents' capabilities in the response. Accepted values: **false**, **true** - **include-last-completed-request**: Whether to include details about the agents' most recent completed work. Accepted values: **false**, **true** -- **org** or **organization**: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`. -- **subscription**: Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID. +- To run tasks using Windows authentication to access an external service, the agent must run under an account with access to that service in pipelines or variable groups when exchanged with the agent. -#### Example +The payload of the messages exchanged between the agent and Azure Pipelines are secured using asymmetric encryption. Each agent has a public-private key pair, and the public key is exchanged with the server during registration. The server uses the public key to encrypt the payload of the job before sending it to the agent. The agent decrypts the job content using its private key.gentCloudRequest": null, + -The following example displays agent details for the agent with the ID of `3`. This example uses the following default configuration: `az devops configure --defaults organization=https://dev.azure.com/fabrikam-tailspin project=FabrikamFiber` +```json -```azurecli -az pipelines agent show --agent-id 3 --pool-id 4 --include-capabilities true -This command group is in preview. It may be changed/removed in a future release. -{ - "accessPoint": null, - "assignedAgentCloudRequest": null, - "status": "offline", @@ -271,29 +312,20 @@ This command group is in preview. It may be changed/removed in a future release. "sh": "", "subversion": "", "svn": "", - "xcode": "" - }, - "userCapabilities": null, - "version": "2.160.1" -} -} + "To run tasks using Windows authentication to access an external service, the agent must run under an account with access to that service. ``` -You can also use `--output table` which returns an abbreviated version of the same information. +However, if you're running UI tests such as Selenium or Coded UI tests that require a browser, the browser is launched in the context of the agent account. -```azurecli -az pipelines pool show --id 4 --output table +On Windows, you should consider using a service account such as Network Service or Local Service. These accounts have restricted permissions and nonexpiring passwords, reducing the need for agent management over time. -ID Name Is Hosted Pool Type ----- ------------------------------- ----------- ----------- -4 Hosted Windows 2019 with VS2019 True automation -``` +These credentials are different from the credentials that you use when you register the agent with Azure Pipelines or Azure DevOps Server. ::: moniker-end -[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] +[!INCLUDE [note-cli-not-supported](../../includes/note-cli-not-supported.md)] -* * * +--- > [!TIP] > @@ -307,19 +339,13 @@ ID Name Is Hosted Pool Type ::: moniker-end -::: moniker range=">tfs-2018 [!NOTE] +> The agent provides support for UTF-8 client encoding output. +> However, if your system has a different encoding from UTF-8, you might encounter some problems with the output of logs. For example, the logs might contain characters that your system’s encoding doesn't recognize, so they might appear as garbled or missing symbols. ::: moniker range="azure-devops" @@ -352,10 +382,7 @@ connectivity to Azure websites and servers running in Azure. > [Agent IP ranges](hosted.md#agent-ip-ranges) where Microsoft-hosted agents are deployed > so you can configure the firewall rules for your Azure VNet to allow access by the agent. -If your on-premises environments do not have connectivity to a Microsoft-hosted agent pool -(which is typically the case due to intermediate firewalls), you'll need to -manually configure a self-hosted agent on on-premises computer(s). The agents must have connectivity to the target -on-premises environments, and access to the Internet to connect to Azure Pipelines or Team Foundation Server, +If your on-premises environments don't have connectivity to a Microsoft-hosted agent pool, which is typically the case due to intermediate firewalls, you need to manually configure self-hosted agents on on-premises computers. The agents must have connectivity to the target on-premises environments, and access to the internet to connect to Azure Pipelines or Team Foundation Server, as shown in the following schematic. ![Agent connectivity for on-premises environments](media/agent-connections-devops.png) @@ -364,90 +391,44 @@ as shown in the following schematic. ## Authentication -To register an agent, you need to be a member of the [administrator role](pools-queues.md#security) in the agent pool. The identity of agent pool administrator is needed only at the time of registration and is not persisted on the agent, and is not used in any subsequent communication between the agent and Azure Pipelines or Azure DevOps Server. In addition, you must be a local administrator on the server in order to configure the agent. - -::: moniker range="azure-devops" - -Your agent can authenticate to Azure Pipelines using the following method: - -::: moniker-end - -::: moniker range="< azure-devops" - -Your agent can authenticate to Azure DevOps Server or TFS using one of the following methods: - -::: moniker-end - - -### Personal Access Token (PAT): -[Generate](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) and use a PAT to connect an agent with Azure Pipelines or TFS 2017 and newer. PAT is the only scheme that works with Azure Pipelines. The PAT must have **Agent Pools (read, manage)** scope (for a [deployment group](../release/deployment-groups/index.md) agent, the PAT must have **Deployment group (read, manage)** scope), and while a single PAT can be used for registering multiple agents, the PAT is used only at the time of registering the agent, and not for subsequent [communication](#communication). For more information, see the Authenticate with a personal access token (PAT) section in the [Windows](windows-agent.md#authenticate-with-a-personal-access-token-pat), [Linux](linux-agent.md#authenticate-with-a-personal-access-token-pat), or [macOS](osx-agent.md#authenticate-with-a-personal-access-token-pat) self-hosted agents articles. - -To use a PAT with Azure DevOps Server, your server must be configured with HTTPS. See [Web site settings and security](/azure/devops/server/admin/websitesettings). - -::: moniker range="< azure-devops" - -### Integrated - -Connect a Windows agent to TFS using the credentials of the signed-in user through a Windows authentication scheme such as NTLM or Kerberos. - -To use this method of authentication, you must first configure your TFS server. - -1. Sign into the machine where you are running TFS. - -1. Start Internet Information Services (IIS) Manager. Select your TFS site and make sure Windows Authentication is enabled with a valid provider such as NTLM or Kerberos. +To register an agent, you need to be a member of the [administrator role](pools-queues.md#security) in the agent pool. The identity of agent pool administrator is needed only at the time of registration and isn't persisted on the agent. It isn't used in any subsequent communication between the agent and Azure Pipelines or Azure DevOps Server. In addition, you must be a local administrator on the server in order to configure the agent. -![IIS TFS windows authentication](media/configure-tfs-authentication/iis-tfs-authentication-windows.png) +When you register an agent, choose from the following authentication types, and agent setup prompts you for the specific additional information required for each authentication type. For more information, see [Self-hosted agent authentication options](./agent-authentication-options.md). -![IIS TFS windows authentication with ntlm provider](media/configure-tfs-authentication/iis-tfs-authentication-windows-ntlm-provider.png) +[!INCLUDE [agent-setup-authentication-type](./includes/agent-setup-authentication.md)] -### Negotiate +:::moniker range="<= azure-devops-2022" -Connect to TFS as a user other than the signed-in user through a Windows authentication scheme such as NTLM or Kerberos. +Additionally, Windows agents have the following two authentication options on Azure DevOps Server. -To use this method of authentication, you must first configure your TFS server. +* [**Negotiate**](./agent-authentication-options.md#negotiate) Connect to Azure DevOps Server as a user other than the signed-in user via a Windows authentication scheme such as New Technology LAN Manager (NTLM) or Kerberos. After selecting Negotiate, you're prompted for credentials. +* [**Integrated**](./agent-authentication-options.md#integrated) (Default) Connect a Windows agent to Azure DevOps Server using the credentials of the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. You won't be prompted for credentials after you choose this method. -1. Log on to the machine where you are running TFS. - -1. Start Internet Information Services (IIS) Manager. Select your TFS site and make sure Windows Authentication is enabled with the Negotiate provider and with another method such as NTLM or Kerberos. - -![IIS TFS windows authentication](media/configure-tfs-authentication/iis-tfs-authentication-windows.png) - -![IIS TFS windows authentication with negotiate and ntlm provider](media/configure-tfs-authentication/iis-tfs-authentication-windows-negotiate-and-ntlm-providers.png) - - -### Alternate -Connect to TFS using Basic authentication. To use this method, you must first [configure HTTPS on TFS](/azure/devops/server/admin/websitesettings). - -To use this method of authentication, you must configure your TFS server as follows: - -1. Sign in to the machine where you are running TFS. +> [!IMPORTANT] +> Your server must be [configured to support the authentication method](agents.md#configure-tfs-authentication) to use Alternate, Negotiate, or Integrated authentication. -1. Configure basic authentication. See [Using `tfx` against Team Foundation Server 2015 using Basic Authentication](https://github.com/Microsoft/tfs-cli/blob/master/docs/configureBasicAuth.md). +:::moniker-end -::: moniker-end +The authentication method used for registering the agent is used only during agent registration. To learn more about how agents communicate with Azure Pipelines after registration, see [Communication with Azure Pipelines or Azure DevOps Server](#communication).

      Interactive vs. service

      You can run your self-hosted agent as either a service or an interactive process. -After you've configured the agent, we recommend you first try it + +After you configure the agent, we recommend you first try it in interactive mode to make sure it works. Then, for production use, we recommend you run the agent in one of the following modes so that it reliably remains in a running state. These modes also ensure that the agent starts automatically if the machine is restarted. -1. **As a service**. You can leverage the service manager of the - operating system to manage the lifecycle of the agent. In addition, the - experience for auto-upgrading the agent is better when it is run - as a service. +1. **As a service**. You can use the service manager of the + operating system to manage the lifecycle of the agent. In addition, the experience for autoupgrading the agent is better when you run the agent as a service. 1. **As an interactive process with auto-logon enabled**. In some cases, you might need to run the agent interactively for production use - such as to run UI tests. When the agent is configured to run in this - mode, the screen saver is also disabled. Some domain policies may - prevent you from enabling auto-logon or disabling the screen saver. In - such cases, you may need to seek an exemption from the domain policy, - or run the agent on a workgroup computer where the domain policies - do not apply. + mode, the screen saver is also disabled. Some domain policies might + prevent you from enabling autologon or disabling the screen saver. In such cases, you might need to seek an exemption from the domain policy, or run the agent on a workgroup computer where the domain policies don't apply. > [!NOTE] > There are security risks when you enable automatic logon @@ -456,9 +437,9 @@ ensure that the agent starts automatically if the machine is restarted. > in this way, you must ensure the computer is physically protected; > for example, located in a secure facility. If you use > Remote Desktop to access the computer on which an agent is running - > with auto-logon, simply closing the Remote Desktop causes the - > computer to be locked and any UI tests that run on this agent may - > fail. To avoid this, use the [tscon](/windows-server/administration/windows-commands/tscon) + > with autologon, simply closing the Remote Desktop causes the + > computer to be locked and any UI tests that run on this agent might + > fail. To avoid this issue, use the [tscon](/windows-server/administration/windows-commands/tscon) > command to disconnect from Remote Desktop. For example: > > `%windir%\System32\tscon.exe 1 /dest:console` @@ -466,19 +447,13 @@ ensure that the agent starts automatically if the machine is restarted.

      Agent account

      Whether you run an agent as a service or interactively, you can choose -which computer account you use to run the agent. (Note that this is different -from the credentials that you use when you register the agent with -Azure Pipelines or Azure DevOps Server.) The choice of agent account depends solely on the needs -of the tasks running in your build and deployment jobs. +which computer account you use to run the agent. The choice of agent account depends solely on the needs of the tasks running in your build and deployment jobs. + +For example, to run tasks using Windows authentication to access an external service, the agent must run using an account with access to that service. However, if you're running UI tests such as Selenium or Coded UI tests that require a browser, the browser is launched in the context of the agent account. -For example, to run tasks that use Windows authentication to access an external -service, you must run the agent using an account that has access -to that service. However, if you are running UI tests such as Selenium or Coded UI tests that -require a browser, the browser is launched in the context of the agent account. +On Windows, you should consider using a service account such as Network Service or Local Service. These accounts permissions are restricted and their passwords don't expire, meaning the agent requires less management over time. -On Windows, you should consider using a service account such as Network Service or Local Service. -These accounts have restricted permissions and their passwords don't expire, meaning -the agent requires less management over time. +These credentials are different from the credentials that you use when you register the agent with Azure Pipelines or Azure DevOps Server. ## Agent version and upgrades @@ -486,15 +461,11 @@ the agent requires less management over time. We update the agent software every few weeks in Azure Pipelines. We indicate the agent version in the format `{major}.{minor}`. -For instance, if the agent version is `2.1`, then the major version is 2 and the minor version is 1. +For instance, if the agent version is `2.1`, then the major version is `2` and the minor version is `1`. -Microsoft-hosted agents are always kept up-to-date. -If the newer version of the agent is only different in _minor_ version, self-hosted agents can usually be updated automatically (configure this setting in **Agent pools**, select your agent, **Settings** - the default is enabled) by Azure Pipelines. -An upgrade is requested when a platform feature or one of the tasks used in the pipeline requires a newer version of the agent. +Microsoft-hosted agents are always kept up-to-date. If the newer version of the agent is only different in _minor_ version, Azure Pipelines can automatically update self-hosted agents. You can configure this setting in **Agent pools**, select your agent, **Settings** - the default is enabled. An upgrade is requested when a platform feature or one of the tasks used in the pipeline requires a newer version of the agent. -If you run a self-hosted agent interactively, or if there is a newer _major_ version of the agent available, then you may have to manually upgrade the agents. -You can do this easily from the **Agent pools** tab under your organization. -Your pipelines won't run until they can target a compatible agent. +If you run a self-hosted agent interactively, or if there's a newer _major_ version of the agent available, then you might have to manually upgrade the agents. You can upgrade the agents easily from the **Agent pools** tab under your organization. Pipelines can't run without a compatible agent ### To update self-hosted agents @@ -520,27 +491,34 @@ Your pipelines won't run until they can target a compatible agent. ::: moniker range="< azure-devops" -We update the agent software with every update in Azure DevOps Server and TFS. +We update the agent software with every update in Azure DevOps Server. We indicate the agent version in the format `{major}.{minor}`. For instance, if the agent version is `2.1`, then the major version is 2 and the minor version is 1. -When your Azure DevOps Server or TFS server has a newer version of the agent, and that newer agent is only different in _minor_ version, it can usually be automatically upgraded. +When your Azure DevOps Server has a newer version of the agent, and that newer agent is only different in _minor_ version, it can usually be automatically upgraded. An upgrade is requested when a platform feature or one of the tasks used in the pipeline requires a newer version of the agent. Starting with Azure DevOps Server 2019, you don't have to wait for a new server release. -You can [upload a new version of the agent to your application tier](#can-i-update-my-v2-agents-that-are-part-of-an-azure-devops-server-pool), and that version will be offered as an upgrade. +You can [upload a new version of the agent to your application tier](#can-i-update-my-agents-that-are-part-of-an-azure-devops-server-pool), and that version is offered as an upgrade. -If you run the agent interactively, or if there is a newer _major_ version of the agent available, then you may have to manually upgrade the agents. -You can do this easily from the **Agent pools** tab under your project collection. -Your pipelines won't run until they can target a compatible agent. +If you run the agent interactively, or if there's a newer _major_ version of the agent available, then you might have to manually upgrade the agents. You can easily upgrade the agent from the **Agent pools** tab under your project collection. Pipelines can't run without a compatible agent. ::: moniker-end You can view the version of an agent by navigating to **Agent pools** and selecting the **Capabilities** tab for the desired agent, as described in [Configure agent capabilities](#configure-agent-capabilities). -To trigger agent update programmatically you can use Agent update API as described in section [How can I trigger agent updates programmatically for specific agent pool?](#how-can-i-trigger-agent-updates-programmatically-for-specific-agent-pool). +To trigger agent update programmatically, you can use Agent update API as described in section [How can I trigger agent updates programmatically for specific agent pool?](#how-can-i-trigger-agent-updates-programmatically-for-specific-agent-pool). > [!NOTE] -> For servers with no internet access, manually copy the agent zip file to `%\ProgramData%\Microsoft\Azure DevOps\Agents\` to use as a local file. Create the **Agents** folder if it is not present. +> For servers with no internet access, manually copy the agent zip file to the following folder to use as a local file. Create the **Agents** folder if it isn't present. +> * Windows: `%ProgramData%\Microsoft\Azure DevOps\Agents` +> * Linux: `usr/share/Microsoft/Azure DevOps/Agents` +> * macOS: `usr/share/Microsoft/Azure DevOps/Agents` + + Create the **Agents** folder if it isn't present. + +## Agent directory structure + +[!INCLUDE [include](includes/agent-directory-structure.md)] ## FAQ @@ -550,7 +528,7 @@ To trigger agent update programmatically you can use Agent update API as describ In many cases, yes. Specifically: -* If you use a self-hosted agent, you can run incremental builds. For example, if you define a pipeline that does not clean the repo and does not perform a clean build, your builds will typically run faster. When you use a Microsoft-hosted agent, you don't get these benefits because the agent is destroyed after the build or release pipeline is completed. +* If you use a self-hosted agent, you can run incremental builds. For example, if you define a pipeline that doesn't clean the repo and doesn't perform a clean build, your builds typically run faster. You don't get these benefits with a Microsoft-hosted agent unless you use features such as [caching](../release/caching.md) because the agent is destroyed after the pipeline is completed. * A Microsoft-hosted agent can take longer to start your build. While it often takes just a few seconds for your job to be assigned to a Microsoft-hosted agent, it can sometimes take several minutes for an agent to be allocated depending on the load on our system. @@ -562,7 +540,7 @@ You might find that in other cases you don't gain much efficiency by running mul You might also run into problems if parallel build jobs are using the same singleton tool deployment, such as npm packages. For example, one build might update a dependency while another build is in the middle of using it, which could cause unreliable results and errors. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### What’s the behavior of agents when the pipeline jobs are canceled? @@ -570,7 +548,14 @@ For Microsoft-hosted agents, the agent is torn down and returned to the Azure Pi For self-hosted agents: -When a pipeline is canceled, the agent sends a sequence of commands to the process executing the current step. The first command is sent with a timeout of 7.5 seconds. If the process has not terminated, a second command is sent with a timeout of 2.5 seconds. If the process has not terminated, the agent issues a command to kill the process. If the process does not honor the two initial termination requests, it will be killed. From the initial request to termination takes approximately 10 seconds. +When a pipeline is canceled, the agent sends a sequence of commands to the process executing the current step. + +* The first command is sent with a time out of 7.5 seconds. +* If the process doesn't terminate, a second command is sent with a 2.5-second time out. +* If the process doesn't terminate, the agent commands it to be killed. +* If the process ignores the two initial termination requests, it's forcibly killed. + +From the initial request to termination takes approximately 10 seconds. The commands issued to the process to cancel the pipeline differ based on the agent operating system. @@ -579,22 +564,39 @@ The commands issued to the process to cancel the pipeline differ based on the ag ### How can I trigger agent updates programmatically for specific agent pool? -You can trigger agent updates for the pool by using next API: +You can trigger agent updates for the pool by using the following API: + +::: moniker-end + +::: moniker range="azure-devops" ``` POST https://dev.azure.com/{organization}/_apis/distributedtask/pools/{poolId}/messages?agentId={agentId}&api-version=6.0 ``` +::: moniker-end + +::: moniker range=" [!NOTE] +> For more information in API and Azure DevOps Server version mapping, see [API and Azure DevOps Server version mapping](/rest/api/azure/devops#api-and-tfs-version-mapping) + +::: moniker-end + +::: moniker range="<=azure-devops" + #### URI Parameters | Name | In | Required | Type | Description | | -------------- | ----- | -------- | ------------- | -------------------------------------------------------------------------------------- | -| `agentId` | query | False | string | The agent to update. If not specified - update will be triggered for all agents. | +| `agentId` | query | False | string | The agent to update. If not specified - update is triggered for all agents. | | `organization` | path | True | string | The name of the Azure DevOps organization. | | `poolId` | path | True | integer int32 | The agent pool to use | -| `api-version` | query | False | string | Version of the API to use. This should be set to '6.0' to use this version of the api. | - - +| `api-version` | query | False | string | Version of the API to use. The value should be set to '6.0' to use this version of the API. | To trigger agent update - request body should be empty. diff --git a/docs/pipelines/agents/certificate.md b/docs/pipelines/agents/certificate.md index 5d82e9789c5..8a58a30ce9c 100644 --- a/docs/pipelines/agents/certificate.md +++ b/docs/pipelines/agents/certificate.md @@ -1,6 +1,5 @@ --- title: Run the agent with a self-signed certificate -ms.custom: seodec18 description: Learn how to run the build and release agent with a self-signed certificate for Azure Pipelines and Team Foundation Server (TFS) ms.topic: conceptual ms.assetid: 09E36E4D-D94B-4F5B-BE4D-9E7B4E7B68E2 @@ -88,7 +87,7 @@ There are 2 approaches to solve the problem. > [!NOTE] > > Git SChannel has more restrict requirement for your self-signed certificate. - > Self-singed certificate that generated by IIS or PowerShell command may not be capable with SChanel. + > Self-singed certificate that generated by IIS or PowerShell command may not be capable with SChannel. ## Work with SSL client certificate diff --git a/docs/pipelines/agents/device-code-flow-agent-registration.md b/docs/pipelines/agents/device-code-flow-agent-registration.md new file mode 100644 index 00000000000..3d60cfd2ced --- /dev/null +++ b/docs/pipelines/agents/device-code-flow-agent-registration.md @@ -0,0 +1,42 @@ +--- +title: Register an agent using device code flow +description: Learn how to register a self-hosted agent using device code flow +ms.topic: conceptual +ms.date: 10/09/2023 +monikerRange: '> azure-devops-2022' +--- + +# Register an agent using device code flow + +You can register an agent using device code flow starting with [agent version 3.227.1](https://github.com/microsoft/azure-pipelines-agent/releases/tag/v3.227.1) by specifying `AAD` when prompted for the agent authentication type. + +## Grant the user access to the agent pool + +Before registering an agent using device code flow, you must grant the desired user permission to access the agent pool. + +1. Open a browser and navigate to the **Agent pools** tab for your Azure Pipelines organization. + + [!INCLUDE [agent-pools-tab](./includes/agent-pools-tab/agent-pools-tab.md)] + +1. Select the desired agent pool on the right side of the page and then choose **Security**. Choose Add, and add the user with the **Administrator** role. + + :::image type="content" source="./media/agent-registration/agent-pool-security.png" alt-text="Screenshot of agent pool security tab."::: + +1. If the user account you're going to use is not shown, then get an administrator to add it, granting the account the administrator role for the agent pool. The administrator can be an agent pool administrator, an [Azure DevOps organization owner](../../organizations/accounts/faq-user-and-permissions-management.yml#find-owner), or a [TFS or Azure DevOps Server administrator](/azure/devops/server/admin/add-administrator). + + If it's a [deployment group](../release/deployment-groups/index.md) agent, the administrator can be a deployment group administrator, an [Azure DevOps organization owner](../../organizations/accounts/faq-user-and-permissions-management.yml#find-owner), or a [TFS or Azure DevOps Server administrator](/azure/devops/server/admin/add-administrator). + + You can add the desired account to the deployment group administrator role in the **Security** tab on the **Deployment Groups** page in **Azure Pipelines**. + +> [!NOTE] +> If you see a message like this: **Sorry, we couldn't add the identity. Please try a different identity.** or **Cannot modify the role for self identity. Please try with a different identity.**, you probably followed the above steps for an organization owner or TFS or Azure DevOps Server administrator. You don't need to do anything; you already have permission to administer the agent pool. +> +> If you are adding the user account to the agent pool security group using **Project Settings**, **Agent pools**, you must first add the user account as an organization user with **Basic** **Access level** (recommended) or higher. + +## Register the agent using device code flow + +1. Specify `AAD` when prompted for authentication type during agent configuration to use a Service Principal to authenticate during agent registration. You'll receive a prompt similar to the following message: **Please finish device code flow in browser (https://microsoft.com/devicelogin), user code: A12WDTGEFD** + +1. Go to the specified link, enter the user code, and complete the sign-in process there. + +1. Specify the name of the agent pool for which you granted administrator permission for the Service Principal, and continue the agent registration steps. \ No newline at end of file diff --git a/docs/pipelines/agents/docker.md b/docs/pipelines/agents/docker.md index 854036a2b0c..59c67b4ee22 100644 --- a/docs/pipelines/agents/docker.md +++ b/docs/pipelines/agents/docker.md @@ -1,10 +1,11 @@ --- title: Run a self-hosted agent in Docker ms.topic: conceptual +ms.custom: linux-related-content description: Instructions for running your Azure Pipelines agent in Docker ms.assetid: e34461fc-8e77-4c94-8f49-cf604a925a19 -ms.date: 11/15/2021 -monikerRange: '>= azure-devops-2019' +ms.date: 04/05/2024 +monikerRange: "<=azure-devops" --- # Run a self-hosted agent in Docker @@ -13,17 +14,9 @@ monikerRange: '>= azure-devops-2019' This article provides instructions for running your Azure Pipelines agent in Docker. You can set up a self-hosted agent in Azure Pipelines to run inside a Windows Server Core (for Windows hosts), or Ubuntu container (for Linux hosts) with Docker. This is useful when you want to run agents with outer orchestration, such as [Azure Container Instances](/azure/container-instances/). In this article, you'll walk through a complete container example, including handling agent self-update. -Both [Windows](#windows) and [Linux](#linux) are supported as container hosts. Windows containers should run on a Windows `vmImage`. +Both [Windows](#windows) and [Linux](#linux) are supported as container hosts. Windows containers should run on a Windows `vmImage`. To run your agent in Docker, you'll pass a few [environment variables](#environment-variables) to `docker run`, which configures the agent to connect to Azure Pipelines or Azure DevOps Server. Finally, you [customize the container](#add-tools-and-customize-the-container) to suit your needs. Tasks and scripts might depend on specific tools being available on the container's `PATH`, and it's your responsibility to ensure that these tools are available. -::: moniker range="azure-devops-2019" - -This feature requires agent version 2.149 or later. -Azure DevOps 2019 didn't ship with a compatible agent version. -However, you can [upload the correct agent package to your application tier](agents.md#can-i-update-my-v2-agents-that-are-part-of-an-azure-devops-server-pool) if you want to run Docker agents. - -::: moniker-end - ## Windows ### Enable Hyper-V @@ -54,80 +47,84 @@ By default, Docker for Windows is configured to use Linux containers. To allow r Next, create the Dockerfile. 1. Open a command prompt. + 2. Create a new directory: - ```shell - mkdir C:\dockeragent + ```powershell + mkdir "C:\azp-agent-in-docker\" ``` -3. Change directories to this new directory: +3. Go to this new directory: - ```shell - cd C:\dockeragent + ```powershell + cd "C:\azp-agent-in-docker\" ``` -4. Save the following content to a file called `C:\dockeragent\Dockerfile` (no file extension): +4. Save the following content to a file called `C:\azp-agent-in-docker\azp-agent-windows.dockerfile`: + + ```dockerfile + FROM mcr.microsoft.com/windows/servercore:ltsc2022 + + WORKDIR /azp/ + + COPY ./start.ps1 ./ - ```docker - FROM mcr.microsoft.com/windows/servercore:ltsc2019 - - WORKDIR /azp - - COPY start.ps1 . - CMD powershell .\start.ps1 ``` -5. Save the following content to `C:\dockeragent\start.ps1`: +5. Save the following content to `C:\azp-agent-in-docker\start.ps1`: ```powershell + function Print-Header ($header) { + Write-Host "`n${header}`n" -ForegroundColor Cyan + } + if (-not (Test-Path Env:AZP_URL)) { Write-Error "error: missing AZP_URL environment variable" exit 1 } - + if (-not (Test-Path Env:AZP_TOKEN_FILE)) { if (-not (Test-Path Env:AZP_TOKEN)) { Write-Error "error: missing AZP_TOKEN environment variable" exit 1 } - + $Env:AZP_TOKEN_FILE = "\azp\.token" $Env:AZP_TOKEN | Out-File -FilePath $Env:AZP_TOKEN_FILE } - + Remove-Item Env:AZP_TOKEN - + if ((Test-Path Env:AZP_WORK) -and -not (Test-Path $Env:AZP_WORK)) { New-Item $Env:AZP_WORK -ItemType directory | Out-Null } - + New-Item "\azp\agent" -ItemType directory | Out-Null - + # Let the agent ignore the token env variables $Env:VSO_AGENT_IGNORE = "AZP_TOKEN,AZP_TOKEN_FILE" - + Set-Location agent - - Write-Host "1. Determining matching Azure Pipelines agent..." -ForegroundColor Cyan - + + Print-Header "1. Determining matching Azure Pipelines agent..." + $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$(Get-Content ${Env:AZP_TOKEN_FILE})")) $package = Invoke-RestMethod -Headers @{Authorization=("Basic $base64AuthInfo")} "$(${Env:AZP_URL})/_apis/distributedtask/packages/agent?platform=win-x64&`$top=1" $packageUrl = $package[0].Value.downloadUrl - + Write-Host $packageUrl - - Write-Host "2. Downloading and installing Azure Pipelines agent..." -ForegroundColor Cyan - + + Print-Header "2. Downloading and installing Azure Pipelines agent..." + $wc = New-Object System.Net.WebClient $wc.DownloadFile($packageUrl, "$(Get-Location)\agent.zip") - + Expand-Archive -Path "agent.zip" -DestinationPath "\azp\agent" - - try - { - Write-Host "3. Configuring Azure Pipelines agent..." -ForegroundColor Cyan - + + try { + Print-Header "3. Configuring Azure Pipelines agent..." + .\config.cmd --unattended ` --agent "$(if (Test-Path Env:AZP_AGENT_NAME) { ${Env:AZP_AGENT_NAME} } else { hostname })" ` --url "$(${Env:AZP_URL})" ` @@ -137,14 +134,12 @@ Next, create the Dockerfile. --work "$(if (Test-Path Env:AZP_WORK) { ${Env:AZP_WORK} } else { '_work' })" ` --replace - Write-Host "4. Running Azure Pipelines agent..." -ForegroundColor Cyan - + Print-Header "4. Running Azure Pipelines agent..." + .\run.cmd - } - finally - { - Write-Host "Cleanup. Removing Azure Pipelines agent..." -ForegroundColor Cyan - + } finally { + Print-Header "Cleanup. Removing Azure Pipelines agent..." + .\config.cmd remove --unattended ` --auth PAT ` --token "$(Get-Content ${Env:AZP_TOKEN_FILE})" @@ -153,30 +148,41 @@ Next, create the Dockerfile. 6. Run the following command within that directory: - ```shell - docker build -t dockeragent:latest . + ```powershell + docker build --tag "azp-agent:windows" --file "./azp-agent-windows.dockerfile" . ``` - This command builds the Dockerfile in the current directory. - - The final image is tagged `dockeragent:latest`. - You can easily run it in a container as `dockeragent`, because the `latest` tag is the default if no tag is specified. + The final image is tagged `azp-agent:windows`. ### Start the image -Now that you have created an image, you can run a container. +Now that you have created an image, you can run a container. This installs the latest version of the agent, configures it, and runs the agent. It targets the specified agent pool (the `Default` agent pool by default) of a specified Azure DevOps or Azure DevOps Server instance of your choice: -1. Open a command prompt. -2. Run the container. This installs the latest version of the agent, configures it, and runs the agent. It targets the `Default` pool of a specified Azure DevOps or Azure DevOps Server instance of your choice: +```powershell +docker run -e AZP_URL="" -e AZP_TOKEN="" -e AZP_POOL="" -e AZP_AGENT_NAME="Docker Agent - Windows" --name "azp-agent-windows" azp-agent:windows +``` - ```shell - docker run -e AZP_URL= -e AZP_TOKEN= -e AZP_AGENT_NAME=mydockeragent dockeragent:latest - ``` +You might need to specify the `--network` parameter if you run into network issues. + +```powershell +docker run --network "Default Switch" < . . . > +``` + +You might need to specify `--interactive` and `--tty` flags (or simply `-it`) if you want to be able to stop the container and remove the agent with `Ctrl` + `C`. + +```powershell +docker run --interactive --tty < . . . > +``` + +If you want a fresh agent container for every pipeline job, pass [the `--once` flag](windows-agent.md#run-once) to the `run` command. -Optionally, you can control the pool and agent work directory by using additional [environment variables](#environment-variables). +```powershell +docker run < . . . > --once +``` -If you want a fresh agent container for every pipeline run, pass the [`--once` flag](windows-agent.md#run-once) to the `run` command. -You must also use a container orchestration system, like Kubernetes or [Azure Container Instances](https://azure.microsoft.com/services/container-instances/), to start new copies of the container when the work completes. +With the `--once` flag, you might want to use a container orchestration system, like Kubernetes or [Azure Container Instances](https://azure.microsoft.com/services/container-instances/), to start a new copy of the container when the job completes. + +You can control the agent name, the agent pool, and the agent work directory by using optional [environment variables](#environment-variables). ## Linux @@ -189,130 +195,138 @@ Depending on your Linux Distribution, you can either install [Docker Community E Next, create the Dockerfile. 1. Open a terminal. + 2. Create a new directory (recommended): - ```shell - mkdir ~/dockeragent + ```bash + mkdir ~/azp-agent-in-docker/ ``` -3. Change directories to this new directory: +3. Go to this new directory: - ```shell - cd ~/dockeragent + ```bash + cd ~/azp-agent-in-docker/ ``` -4. Save the following content to `~/dockeragent/Dockerfile`: - * For Ubuntu 20.04: - ```Dockerfile - FROM ubuntu:20.04 - RUN DEBIAN_FRONTEND=noninteractive apt-get update - RUN DEBIAN_FRONTEND=noninteractive apt-get upgrade -y - - RUN DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends \ - apt-transport-https \ - apt-utils \ - ca-certificates \ - curl \ - git \ - iputils-ping \ - jq \ - lsb-release \ - software-properties-common +4. Save the following content to `~/azp-agent-in-docker/azp-agent-linux.dockerfile`: - RUN curl -sL https://aka.ms/InstallAzureCLIDeb | bash + * For Alpine, using the technique described in [this issue](https://github.com/Azure/azure-cli/issues/19591): + ```dockerfile + FROM python:3-alpine + ENV TARGETARCH="linux-musl-x64" + + # Another option: + # FROM arm64v8/alpine + # ENV TARGETARCH="linux-musl-arm64" + + RUN apk update && \ + apk upgrade && \ + apk add bash curl gcc git icu-libs jq musl-dev python3-dev libffi-dev openssl-dev cargo make - # Can be 'linux-x64', 'linux-arm64', 'linux-arm', 'rhel.6-x64'. - ENV TARGETARCH=linux-x64 + # Install Azure CLI + RUN pip install --upgrade pip + RUN pip install azure-cli - WORKDIR /azp + WORKDIR /azp/ - COPY ./start.sh . - RUN chmod +x start.sh + COPY ./start.sh ./ + RUN chmod +x ./start.sh + + RUN adduser -D agent + RUN chown agent ./ + USER agent + # Another option is to run the agent as root. + # ENV AGENT_ALLOW_RUNASROOT="true" ENTRYPOINT [ "./start.sh" ] ``` - * For Ubuntu 18.04: - ```Dockerfile - FROM ubuntu:18.04 - - # To make it easier for build and release pipelines to run apt-get, - # configure apt to not require confirmation (assume the -y argument by default) - ENV DEBIAN_FRONTEND=noninteractive - RUN echo "APT::Get::Assume-Yes \"true\";" > /etc/apt/apt.conf.d/90assumeyes - - RUN apt-get update && apt-get install -y --no-install-recommends \ - ca-certificates \ - curl \ - jq \ - git \ - iputils-ping \ - libcurl4 \ - libicu60 \ - libunwind8 \ - netcat \ - libssl1.0 \ - && rm -rf /var/lib/apt/lists/* - - RUN curl -LsS https://aka.ms/InstallAzureCLIDeb | bash \ - && rm -rf /var/lib/apt/lists/* - - # Can be 'linux-x64', 'linux-arm64', 'linux-arm', 'rhel.6-x64'. - ENV TARGETARCH=linux-x64 - - WORKDIR /azp - - COPY ./start.sh . - RUN chmod +x start.sh - - ENTRYPOINT ["./start.sh"] + + * For Ubuntu 22.04: + ```dockerfile + FROM ubuntu:22.04 + ENV TARGETARCH="linux-x64" + # Also can be "linux-arm", "linux-arm64". + + RUN apt update && \ + apt upgrade -y && \ + apt install -y curl git jq libicu70 + + # Install Azure CLI + RUN curl -sL https://aka.ms/InstallAzureCLIDeb | bash + + WORKDIR /azp/ + + COPY ./start.sh ./ + RUN chmod +x ./start.sh + + # Create agent user and set up home directory + RUN useradd -m -d /home/agent agent + RUN chown -R agent:agent /azp /home/agent + + USER agent + # Another option is to run the agent as root. + # ENV AGENT_ALLOW_RUNASROOT="true" + + ENTRYPOINT [ "./start.sh" ] ``` + + Uncomment the `ENV AGENT_ALLOW_RUNASROOT="true"` line and remove adding the `agent` user before this line if you want to run the agent as root. + > [!NOTE] > Tasks might depend on executables that your container is expected to provide. > For instance, you must add the `zip` and `unzip` packages - > to the `RUN apt-get` command in order to run the `ArchiveFiles` and `ExtractFiles` tasks. + > to the `RUN apt install -y` command in order to run the `ArchiveFiles` and `ExtractFiles` tasks. > Also, as this is a Linux Ubuntu image for the agent to use, you can customize the image as you need. - > E.g.: if you need to build .NET applications you can follow the document + > E.g.: if you need to build .NET applications you can follow the document > [Install the .NET SDK or the .NET Runtime on Ubuntu](/dotnet/core/install/linux-ubuntu) - > and add that to your image. - + > and add that to your image. -5. Save the following content to `~/dockeragent/start.sh`, making sure to use Unix-style (LF) line endings: +5. Save the following content to `~/azp-agent-in-docker/start.sh`, making sure to use Unix-style (LF) line endings: - ```shell + ```bash #!/bin/bash set -e - if [ -z "$AZP_URL" ]; then + if [ -z "${AZP_URL}" ]; then echo 1>&2 "error: missing AZP_URL environment variable" exit 1 fi - if [ -z "$AZP_TOKEN_FILE" ]; then - if [ -z "$AZP_TOKEN" ]; then + if [ -n "$AZP_CLIENTID" ]; then + echo "Using service principal credentials to get token" + az login --allow-no-subscriptions --service-principal --username "$AZP_CLIENTID" --password "$AZP_CLIENTSECRET" --tenant "$AZP_TENANTID" + # adapted from https://learn.microsoft.com/en-us/azure/databricks/dev-tools/user-aad-token + AZP_TOKEN=$(az account get-access-token --query accessToken --output tsv) + echo "Token retrieved" + fi + + if [ -z "${AZP_TOKEN_FILE}" ]; then + if [ -z "${AZP_TOKEN}" ]; then echo 1>&2 "error: missing AZP_TOKEN environment variable" exit 1 fi - AZP_TOKEN_FILE=/azp/.token - echo -n $AZP_TOKEN > "$AZP_TOKEN_FILE" + AZP_TOKEN_FILE="/azp/.token" + echo -n "${AZP_TOKEN}" > "${AZP_TOKEN_FILE}" fi + unset AZP_CLIENTSECRET unset AZP_TOKEN - if [ -n "$AZP_WORK" ]; then - mkdir -p "$AZP_WORK" + if [ -n "${AZP_WORK}" ]; then + mkdir -p "${AZP_WORK}" fi - export AGENT_ALLOW_RUNASROOT="1" - cleanup() { - if [ -e config.sh ]; then + trap "" EXIT + + if [ -e ./config.sh ]; then print_header "Cleanup. Removing Azure Pipelines agent..." - + # If the agent has some running jobs, the configuration removal process will fail. # So, give it some time to finish the job. while true; do - ./config.sh remove --unattended --auth PAT --token $(cat "$AZP_TOKEN_FILE") && break + ./config.sh remove --unattended --auth "PAT" --token $(cat "${AZP_TOKEN_FILE}") && break echo "Retrying in 30 seconds..." sleep 30 @@ -321,46 +335,47 @@ Next, create the Dockerfile. } print_header() { - lightcyan='\033[1;36m' - nocolor='\033[0m' - echo -e "${lightcyan}$1${nocolor}" + lightcyan="\033[1;36m" + nocolor="\033[0m" + echo -e "\n${lightcyan}$1${nocolor}\n" } # Let the agent ignore the token env variables - export VSO_AGENT_IGNORE=AZP_TOKEN,AZP_TOKEN_FILE + export VSO_AGENT_IGNORE="AZP_TOKEN,AZP_TOKEN_FILE" print_header "1. Determining matching Azure Pipelines agent..." AZP_AGENT_PACKAGES=$(curl -LsS \ - -u user:$(cat "$AZP_TOKEN_FILE") \ - -H 'Accept:application/json;' \ - "$AZP_URL/_apis/distributedtask/packages/agent?platform=$TARGETARCH&top=1") + -u user:$(cat "${AZP_TOKEN_FILE}") \ + -H "Accept:application/json" \ + "${AZP_URL}/_apis/distributedtask/packages/agent?platform=${TARGETARCH}&top=1") - AZP_AGENT_PACKAGE_LATEST_URL=$(echo "$AZP_AGENT_PACKAGES" | jq -r '.value[0].downloadUrl') + AZP_AGENT_PACKAGE_LATEST_URL=$(echo "${AZP_AGENT_PACKAGES}" | jq -r ".value[0].downloadUrl") - if [ -z "$AZP_AGENT_PACKAGE_LATEST_URL" -o "$AZP_AGENT_PACKAGE_LATEST_URL" == "null" ]; then + if [ -z "${AZP_AGENT_PACKAGE_LATEST_URL}" -o "${AZP_AGENT_PACKAGE_LATEST_URL}" == "null" ]; then echo 1>&2 "error: could not determine a matching Azure Pipelines agent" - echo 1>&2 "check that account '$AZP_URL' is correct and the token is valid for that account" + echo 1>&2 "check that account "${AZP_URL}" is correct and the token is valid for that account" exit 1 fi print_header "2. Downloading and extracting Azure Pipelines agent..." - curl -LsS $AZP_AGENT_PACKAGE_LATEST_URL | tar -xz & wait $! + curl -LsS "${AZP_AGENT_PACKAGE_LATEST_URL}" | tar -xz & wait $! source ./env.sh - trap 'cleanup; exit 0' EXIT - trap 'cleanup; exit 130' INT - trap 'cleanup; exit 143' TERM + trap "cleanup; exit 0" EXIT + trap "cleanup; exit 130" INT + trap "cleanup; exit 143" TERM print_header "3. Configuring Azure Pipelines agent..." + # Despite it saying "PAT", it can be the token through the service principal ./config.sh --unattended \ --agent "${AZP_AGENT_NAME:-$(hostname)}" \ - --url "$AZP_URL" \ - --auth PAT \ - --token $(cat "$AZP_TOKEN_FILE") \ + --url "${AZP_URL}" \ + --auth "PAT" \ + --token $(cat "${AZP_TOKEN_FILE}") \ --pool "${AZP_POOL:-Default}" \ --work "${AZP_WORK:-_work}" \ --replace \ @@ -368,59 +383,71 @@ Next, create the Dockerfile. print_header "4. Running Azure Pipelines agent..." - trap 'cleanup; exit 0' EXIT - trap 'cleanup; exit 130' INT - trap 'cleanup; exit 143' TERM - chmod +x ./run.sh - # To be aware of TERM and INT signals call run.sh + # To be aware of TERM and INT signals call ./run.sh # Running it with the --once flag at the end will shut down the agent after the build is executed ./run.sh "$@" & wait $! ``` + > [!NOTE] - >You must also use a container orchestration system, like Kubernetes or [Azure Container Instances](https://azure.microsoft.com/services/container-instances/), to start new copies of the container when the work completes. + > You must also use a container orchestration system, like Kubernetes or [Azure Container Instances](https://azure.microsoft.com/services/container-instances/), to start new copies of the container when the work completes. + 6. Run the following command within that directory: - ```shell - docker build -t dockeragent:latest . + ```bash + docker build --tag "azp-agent:linux" --file "./azp-agent-linux.dockerfile" . ``` - This command builds the Dockerfile in the current directory. - - The final image is tagged `dockeragent:latest`. - You can easily run it in a container as `dockeragent`, because the `latest` tag is the default if no tag is specified. + The final image is tagged `azp-agent:linux`. ### Start the image -Now that you have created an image, you can run a container. +Now that you have created an image, you can run a container. This installs the latest version of the agent, configures it, and runs the agent. It targets the specified agent pool (the `Default` agent pool by default) of a specified Azure DevOps or Azure DevOps Server instance of your choice: -1. Open a terminal. -2. Run the container. This installs the latest version of the agent, configures it, and runs the agent. It targets the `Default` pool of a specified Azure DevOps or Azure DevOps Server instance of your choice: +```bash +docker run -e AZP_URL="" -e AZP_TOKEN="" -e AZP_POOL="" -e AZP_AGENT_NAME="Docker Agent - Linux" --name "azp-agent-linux" azp-agent:linux +``` - ```shell - docker run -e AZP_URL= -e AZP_TOKEN= -e AZP_AGENT_NAME=mydockeragent dockeragent:latest - ``` +You might need to specify `--interactive` and `--tty` flags (or simply `-it`) if you want to be able to stop the container and remove the agent with `Ctrl` + `C`. - If you want a fresh agent container for every pipeline job, pass the [`--once` flag](linux-agent.md#run-once) to the `run` command. +```bash +docker run --interactive --tty < . . . > +``` - ```shell - docker run -e AZP_URL= -e AZP_TOKEN= -e AZP_AGENT_NAME=mydockeragent dockeragent:latest --once - ``` +If you want a fresh agent container for every pipeline job, pass [the `--once` flag](linux-agent.md#run-once) to the `run` command. -Optionally, you can control the pool and agent work directory by using additional [environment variables](#environment-variables). +```bash +docker run < . . . > --once +``` +With the `--once` flag, you might want to use a container orchestration system, like Kubernetes or [Azure Container Instances](https://azure.microsoft.com/services/container-instances/), to start a new copy of the container when the job completes. + +You can control the agent name, the agent pool, and the agent work directory by using optional [environment variables](#environment-variables). ## Environment variables -| Environment variable | Description | -|----------------------|-------------------------------------------------------------| +| Environment variable | Description | +|----------------------|--------------------------------------------------------------| | AZP_URL | The URL of the Azure DevOps or Azure DevOps Server instance. | -| AZP_TOKEN | [Personal Access Token (PAT)](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **Agent Pools (read, manage)** scope, created by a user who has permission to [configure agents](pools-queues.md#create-agent-pools), at `AZP_URL`. | +| AZP_TOKEN | [Personal Access Token (PAT)](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) | +| AZP_CLIENTID | [Service principal](../../pipelines/agents/service-principal-agent-registration.md) client ID | +| AZP_CLIENTSECRET | Service principal client secret | +| AZP_TENANTID | Service principal tenant ID | | AZP_AGENT_NAME | Agent name (default value: the container hostname). | | AZP_POOL | Agent pool name (default value: `Default`). | | AZP_WORK | Work directory (default value: `_work`). | +### Authentication + +One of the following is required: + +- If using a PAT: `AZP_TOKEN` +- If using a service principal: `AZP_CLIENTID`, `AZP_CLIENTSECRET`, and `AZP_TENANTID` + +### Authorization + +The token or service principal must have the **Agent Pools (read, manage)** scope at the Organization level of `AZP_URL`. If using a PAT, the token must be created by a user who has permission to [configure agents](pools-queues.md#create-agent-pools). ## Add tools and customize the container @@ -443,10 +470,10 @@ If you're sure you want to do this, see the [bind mount](https://docs.docker.com ## Use Azure Kubernetes Service cluster > [!CAUTION] -> Please, consider that any docker based tasks will not work on AKS 1.19 or later due to docker in docker restriction. +> Please, consider that any docker based tasks will not work on AKS 1.19 or later due to docker in docker restriction. > [Docker was replaced with containerd](/azure/aks/cluster-configuration#container-runtime-configuration) in Kubernetes 1.19, and Docker-in-Docker became unavailable. -### Deploy and configure Azure Kubernetes Service +### Deploy and configure Azure Kubernetes Service Follow the steps in [Quickstart: Deploy an Azure Kubernetes Service (AKS) cluster by using the Azure portal](/azure/aks/kubernetes-walkthrough-portal). After this, your PowerShell or Shell console can use the `kubectl` command line. @@ -458,85 +485,85 @@ Follow the steps in [Quickstart: Create an Azure container registry by using the 1. Create the secrets on the AKS cluster. - ```shell - kubectl create secret generic azdevops \ - --from-literal=AZP_URL=https://dev.azure.com/yourOrg \ - --from-literal=AZP_TOKEN=YourPAT \ - --from-literal=AZP_POOL=NameOfYourPool - ``` + ```bash + kubectl create secret generic azdevops \ + --from-literal=AZP_URL=https://dev.azure.com/yourOrg \ + --from-literal=AZP_TOKEN=YourPAT \ + --from-literal=AZP_POOL=NameOfYourPool + ``` 2. Run this command to push your container to Container Registry: - ```shell - docker push /dockeragent:latest - ``` + ```bash + docker push "/azp-agent:" + ``` 3. Configure Container Registry integration for existing AKS clusters. - > [!NOTE] - > If you have multiple subscriptions on the Azure Portal, please, use this command first to select a subscription - >```azurecli - >az account set --subscription subscription name> - >``` - - ```azurecli - az aks update -n myAKSCluster -g myResourceGroup --attach-acr - ``` - -4. Save the following content to `~/AKS/ReplicationController.yaml`: - - ```yml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: azdevops-deployment - labels: - app: azdevops-agent - spec: - replicas: 1 #here is the configuration for the actual agent always running - selector: - matchLabels: - app: azdevops-agent - template: - metadata: - labels: - app: azdevops-agent - spec: - containers: - - name: kubepodcreation - image: /dockeragent:latest - env: - - name: AZP_URL - valueFrom: - secretKeyRef: - name: azdevops - key: AZP_URL - - name: AZP_TOKEN - valueFrom: - secretKeyRef: - name: azdevops - key: AZP_TOKEN - - name: AZP_POOL - valueFrom: - secretKeyRef: - name: azdevops - key: AZP_POOL - volumeMounts: - - mountPath: /var/run/docker.sock - name: docker-volume - volumes: - - name: docker-volume - hostPath: - path: /var/run/docker.sock - ``` - - This Kubernetes YAML creates a replica set and a deployment, where `replicas: 1` indicates the number or the agents that are running on the cluster. + > [!NOTE] + > If you have multiple subscriptions on the Azure portal, please, use this command first to select a subscription + >```azurecli + >az account set --subscription "" + >``` + + ```azurecli + az aks update -n "" -g "" --attach-acr "" + ``` + +4. Save the following content to `~/AKS/ReplicationController.yml`: + + ```yml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: azdevops-deployment + labels: + app: azdevops-agent + spec: + replicas: 1 # here is the configuration for the actual agent always running + selector: + matchLabels: + app: azdevops-agent + template: + metadata: + labels: + app: azdevops-agent + spec: + containers: + - name: kubepodcreation + image: /azp-agent: + env: + - name: AZP_URL + valueFrom: + secretKeyRef: + name: azdevops + key: AZP_URL + - name: AZP_TOKEN + valueFrom: + secretKeyRef: + name: azdevops + key: AZP_TOKEN + - name: AZP_POOL + valueFrom: + secretKeyRef: + name: azdevops + key: AZP_POOL + volumeMounts: + - mountPath: /var/run/docker.sock + name: docker-volume + volumes: + - name: docker-volume + hostPath: + path: /var/run/docker.sock + ``` + + This Kubernetes YAML creates a replica set and a deployment, where `replicas: 1` indicates the number or the agents that are running on the cluster. 5. Run this command: - ```shell - kubectl apply -f ReplicationController.yaml - ``` + ```bash + kubectl apply -f ReplicationController.yml + ``` Now your agents will run the AKS cluster. @@ -544,11 +571,13 @@ Now your agents will run the AKS cluster. Allow specifying MTU value for networks used by container jobs (useful for docker-in-docker scenarios in k8s cluster). -You need to set the environment variable AGENT_MTU_VALUE to set the MTU value, and then restart the self-hosted agent. You can find more about agent restart [here](./windows-agent.md?#how-do-i-restart-the-agent) and about setting different environment variables for each individual agent [here](./windows-agent.md?#how-do-i-set-different-environment-variables-for-each-individual-agent). +You need to set the environment variable AGENT_DOCKER_MTU_VALUE to set the MTU value, and then restart the self-hosted agent. You can find more about agent restart [here](./windows-agent.md?#how-do-i-restart-the-agent) and about setting different environment variables for each individual agent [here](./windows-agent.md?#how-do-i-set-different-environment-variables-for-each-individual-agent). This allows you to set up a network parameter for the job container, the use of this command is similar to the use of the next command while container network configuration: -```-o com.docker.network.driver.mtu=AGENT_MTU_VALUE``` +```bash +-o com.docker.network.driver.mtu=AGENT_DOCKER_MTU_VALUE +``` ## Mounting volumes using Docker within a Docker container @@ -556,47 +585,48 @@ If a Docker container runs inside another Docker container, they both use host's For example, if we want to mount path from host into outer Docker container, we can use this command: - ``` - docker run ... -v : ... - ``` +```bash +docker run ... -v ":" ... +``` And if we want to mount path from host into inner Docker container, we can use this command: - ``` - docker run ... -v : ... - ``` +```bash +docker run ... -v ":" ... +``` But we can't mount paths from outer container into the inner one; to work around that, we have to declare an ENV variable: - ``` - docker run ... --env DIND_USER_HOME=$HOME ... - ``` +```bash +docker run ... --env DIND_USER_HOME=$HOME ... +``` After this, we can start the inner container from the outer one using this command: - ``` - docker run ... -v $DIND_USER_HOME: ... - ``` +```bash +docker run ... -v "${DIND_USER_HOME}:" ... +``` ## Common errors -If you're using Windows, and you get the following error: +If you're using Windows, and you get the following error: - ```shell - ‘standard_init_linux.go:178: exec user process caused "no such file or directory" - ``` +``` +standard_init_linux.go:178: exec user process caused "no such file or directory" +``` Install Git Bash by downloading and installing [git-scm](https://git-scm.com/download/win). Run this command: - ```shell - dos2unix ~/dockeragent/Dockerfile - dos2unix ~/dockeragent/start.sh - git add . - git commit -m 'Fixed CR' - git push - ``` +```bash +dos2unix ~/azp-agent-in-docker/Dockerfile +dos2unix ~/azp-agent-in-docker/start.sh +git add . +git commit -m "Fixed CR" +git push +``` + Try again. You no longer get the error. ## Related articles diff --git a/docs/pipelines/agents/hosted.md b/docs/pipelines/agents/hosted.md index 5d8a9a5405e..30073331677 100644 --- a/docs/pipelines/agents/hosted.md +++ b/docs/pipelines/agents/hosted.md @@ -1,16 +1,15 @@ --- title: Microsoft-hosted agents for Azure Pipelines -ms.custom: seodec18, contperf-fy20q4 description: Learn about using the Microsoft-hosted agents provided in Azure Pipelines ms.topic: conceptual ms.assetid: D17E9C01-8026-41E8-B44A-AB17EDE4AFBD -ms.date: 06/20/2023 +ms.date: 04/11/2025 monikerRange: '<= azure-devops' --- # Microsoft-hosted agents -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-eq-azure-devops.md)] ::: moniker range="< azure-devops" @@ -30,32 +29,45 @@ The **Azure Pipelines** agent pool offers several virtual machine images to choo | Image | Classic Editor Agent Specification | YAML VM Image Label | Included Software | | --- | --- | --- | --- | -| Windows Server 2022 with Visual Studio 2022 | *windows-2022* | `windows-latest` OR `windows-2022` | [Link](https://github.com/actions/runner-images/blob/main/images/win/Windows2022-Readme.md) | -| Windows Server 2019 with Visual Studio 2019 | *windows-2019* | `windows-2019` | [Link](https://github.com/actions/runner-images/blob/main/images/win/Windows2019-Readme.md) | -| Ubuntu 22.04 | *ubuntu-22.04* | `ubuntu-latest` OR `ubuntu-22.04` | [Link](https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md) -| Ubuntu 20.04 | *ubuntu-20.04* | `ubuntu-20.04` | [Link](https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2004-Readme.md) -| macOS 13 Ventura | *macOS-13* | `macOS-13` | [Link](https://github.com/actions/runner-images/blob/main/images/macos/macos-13-Readme.md) | -| macOS 12 Monterey | *macOS-12* | `macOS-latest` OR `macOS-12` | [Link](https://github.com/actions/runner-images/blob/main/images/macos/macos-12-Readme.md) | -| macOS 11 Big Sur | *macOS-11* | `macOS-11` | [Link](https://github.com/actions/runner-images/blob/main/images/macos/macos-11-Readme.md) | +| Windows Server 2025 with Visual Studio 2022 (preview) | *windows-2025* | `windows-2025` | [Link](https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md) | +| Windows Server 2022 with Visual Studio 2022 | *windows-2022* | `windows-latest` OR `windows-2022` | [Link](https://aka.ms/windows-2022-readme) | +| Windows Server 2019 with Visual Studio 2019 | *windows-2019* | `windows-2019` | [Link](https://aka.ms/windows-2019-readme) | +| Ubuntu 24.04 | *ubuntu-24.04* | `ubuntu-latest`1 OR `ubuntu-24.04` | [Link](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md) +| Ubuntu 22.04 | *ubuntu-22.04* | `ubuntu-22.04` | [Link](https://aka.ms/ubuntu-22.04-readme) +| Ubuntu 20.04 | *ubuntu-20.04* | `ubuntu-20.04` | [Link](https://aka.ms/ubuntu-20.04-readme) +| macOS 15 Sequoia (preview) | *macOS-15* | `macOS-15` | [Link](https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md) | +| macOS 14 Sonoma | *macOS-14* | `macOS-latest` OR `macOS-14` | [Link](https://aka.ms/macOS-14-readme) | +| macOS 13 Ventura | *macOS-13* | `macOS-13` | [Link](https://aka.ms/macOS-13-readme) | The default agent image for classic build pipelines is *windows-2019*, and the default agent image for YAML build pipelines is `ubuntu-latest`. For more information, see [Designate a pool in your pipeline](pools-queues.md#designate-a-pool-in-your-pipeline). -You can see the installed software for each hosted agent by choosing the **Included Software** link in the table. When using macOS images, you can manually select from tool versions. [See below](#mac-pick-tools). +You can see the installed software for each hosted agent by choosing the **Included Software** link in the table. When using macOS images, you can manually select from tool versions. [Read more](#mac-pick-tools). + +1 The `ubuntu-latest` label is in the process of transitioning from `ubuntu-22.04` to `ubuntu-24.04`. Until the transition is complete, your pipelines using `ubuntu-latest` might still use `ubuntu-22.04`. ### Recent updates -* The macOS 13 image is available +* The windows-2025 image is available in preview +* The macOS-12 Monterey image has been retired +* The macOS-15 Sequoia image is available in preview +* The Ubuntu-24.04 image is available +* The macOS-12 Monterey image is deprecated and will be retired December 3, 2024. +* The Ubuntu-22.04 image is available +* The macOS-14 Sonoma image is available in preview +* The macOS-11 Big Sur image is deprecated and will be retired June 28, 2024. +* All Microsoft hosted agents will start using PowerShell 7.2 LTS to PowerShell 7.4 LTS starting January 28. For more information, including potential breaking changes, see [Microsoft hosted agents use PowerShell 7.4](/azure/devops/release-notes/2024/sprint-233-update#microsoft-hosted-agents-use-powershell-74). +* The macOS 13 image is generally available * The macOS 10.15 image is fully unsupported as of 4/24/2023 -* Ubuntu 18.04 has been retired -* [`ubuntu-latest` images will use `ubuntu-22.04`](https://github.com/actions/runner-images/issues/6399). +* The Ubuntu 18.04 image is retired +* [`ubuntu-latest` images use `ubuntu-22.04`](https://github.com/actions/runner-images/issues/6399). * [General availability of Ubuntu 22.04 for Azure Pipelines hosted pools](/azure/devops/release-notes/2022/sprint-208-update#general-availability-of-ubuntu-2204-for-azure-pipelines-hosted-pools). * [The Ubuntu 18.04 image will begin deprecation on 8/8/22 and will be fully unsupported by 4/1/2023](https://github.com/actions/runner-images/issues/6002). * [The macOS 10.15 image will begin deprecation on 5/31/22 and will be fully unsupported by 12/1/2022](https://github.com/actions/runner-images/issues/5583). -* [`windows-latest` images will use `windows-2022`](https://github.com/actions/runner-images/issues/4856). -* [`macOS-latest` images will use `macOS-11`](https://github.com/actions/runner-images/issues/4060). +* [`windows-latest` images use `windows-2022`](https://github.com/actions/runner-images/issues/4856). +* [`macOS-latest` images use `macOS-14`](https://devblogs.microsoft.com/devops/upcoming-deprecation-of-macos-12-hosted-pipeline-image/). * [The Ubuntu 16.04 hosted image was removed September 2021](https://github.com/actions/runner-images/issues/3287). -* The Windows Server 2016 with Visual Studio 2017 image has been deprecated and will be retired June 30 2022. Read [this blog post](https://devblogs.microsoft.com/devops/hosted-pipelines-image-deprecation/#windows) on how to identify pipelines using deprecated images. +* The Windows Server 2016 with Visual Studio 2017 image is deprecated and was retired June 30 2022. Read [this blog post](https://devblogs.microsoft.com/devops/hosted-pipelines-image-deprecation/#windows) on how to identify pipelines using deprecated images. * In December 2021, we removed the following Azure Pipelines hosted image: * macOS X Mojave 10.14 (`macOS-10.14`) * In March 2020, we removed the following Azure Pipelines hosted images: @@ -89,7 +101,7 @@ You can also query job history for deprecated images across projects using the s # [YAML](#tab/yaml) -In YAML pipelines, if you do not specify a pool, pipelines will default to the Azure Pipelines agent pool. You simply need to specify which virtual machine image you want to use. +In YAML pipelines, if you do not specify a pool, pipelines default to the Azure Pipelines agent pool. You simply need to specify which virtual machine image you want to use. ```yaml jobs: @@ -139,13 +151,13 @@ Agents that run macOS images are provisioned on Mac pros with a 3 core CPU, 14 G All of these machines have at least 10 GB of free disk space available for your pipelines to run. This free space is consumed when your pipeline checks out source code, downloads packages, pulls docker images, or generates intermediate files. > [!IMPORTANT] -> We cannot honor requests to increase disk space on Microsoft-hosted agents, or to provision more powerful machines. If the specifications of Microsoft-hosted agents do not meet your needs, then you should consider [self-hosted agents](agents.md) or [scale set agents](scale-set-agents.md). +> We cannot honor requests to increase disk space on Microsoft-hosted agents, or to provision more powerful machines. If the specifications of Microsoft-hosted agents do not meet your needs, then you should consider [self-hosted agents](agents.md) or [scale set agents](scale-set-agents.md) or [Managed DevOps Pools](../../managed-devops-pools/overview.md#usage-scenarios). ## Networking -In some setups, you may need to know the range of IP addresses where agents are deployed. For instance, if you need to grant the hosted agents access through a firewall, you may wish to restrict that access by IP address. Because Azure DevOps uses the Azure global network, IP ranges vary over time. We publish a [weekly JSON file](https://www.microsoft.com/download/details.aspx?id=56519) listing IP ranges for Azure datacenters, broken out by region. This file is updated weekly with new planned IP ranges. The new IP ranges become effective the following week. We recommend that you check back frequently (at least once every week) to ensure you keep an up-to-date list. If agent jobs begin to fail, a key first troubleshooting step is to make sure your configuration matches the latest list of IP addresses. The IP address ranges for the hosted agents are listed in the weekly file under `AzureCloud.`, such as `AzureCloud.westus` for the West US region. +In some setups, you may need to know the range of IP addresses where agents are deployed. For instance, if you need to grant the hosted agents access through a firewall, you may wish to restrict that access by IP address. Because Azure DevOps uses the Azure global network, IP ranges vary over time. Microsoft publishes a [weekly JSON file](https://www.microsoft.com/download/details.aspx?id=56519) listing IP ranges for Azure datacenters, broken out by region. This file is updated weekly with new planned IP ranges. Only the latest version of the file is available for download. If you need previous versions, you must download and archive them each week as they become available. The new IP ranges become effective the following week. We recommend that you check back frequently (at least once every week) to ensure you keep an up-to-date list. If agent jobs begin to fail, a key first troubleshooting step is to make sure your configuration matches the latest list of IP addresses. The IP address ranges for the hosted agents are listed in the weekly file under `AzureCloud.`, such as `AzureCloud.westus` for the West US region. Your hosted agents run in the same [Azure geography](https://azure.microsoft.com/global-infrastructure/geographies/) as your organization. Each geography contains one or more regions. While your agent may run in the same region as your organization, it is not guaranteed to do so. To obtain the complete list of possible IP ranges for your agent, you must use the IP ranges from all of the regions that are contained in your geography. For example, if your organization is located in the **United States** geography, you must use the IP ranges for all of the regions in that geography. @@ -188,24 +200,26 @@ namespace WeeklyFileIPRanges class Program { // Path to the locally saved weekly file - const string weeklyFilePath = @"C:\MyPath\ServiceTags_Public_20210823.json"; + const string weeklyFilePath = @"C:\MyPath\ServiceTags_Public_20230904.json"; static void Main(string[] args) { // United States geography has the following regions: - // Central US, East US, East US 2, North Central US, - // South Central US, West Central US, West US, West US 2 - // This list is accurate as of 8/26/2021 + // Central US, East US, East US 2, East US 3, North Central US, + // South Central US, West Central US, West US, West US 2, West US 3 + // This list is accurate as of 9/8/2023 List USGeographyRegions = new List { "centralus", "eastus", "eastus2", + "eastus3", "northcentralus", "southcentralus", "westcentralus", "westus", - "westus2" + "westus2", + "westus3" }; // Load the weekly file @@ -214,12 +228,12 @@ namespace WeeklyFileIPRanges foreach (string region in USGeographyRegions) { - string azureCloudRegion = $"AzureCloud.{region}"; - Console.WriteLine(azureCloudRegion); + string tag = $"AzureCloud.{region}"; + Console.WriteLine(tag); var ipList = from v in values - where (string)v["name"] == azureCloudRegion + where tag.Equals((string)v["name"], StringComparison.OrdinalIgnoreCase) select v["properties"]["addressPrefixes"]; foreach (var ip in ipList.Children()) @@ -244,7 +258,7 @@ Microsoft-hosted agents run on secure Azure platform. However, you must be aware - Microsoft-hosted agents are run in individual VMs, which are re-imaged after each run. Each agent is dedicated to a single organization, and each VM hosts only a single agent. - There are several benefits to running your pipeline on Microsoft-hosted agents, from a security perspective. If you run untrusted code in your pipeline, such as contributions from forks, it is safer to run the pipeline on Microsoft-hosted agents than on self-hosted agents that reside in your corporate network. - When a pipeline needs to access your corporate resources behind a firewall, you have to allow the IP address range for the Azure geography. This may increase your exposure as the range of IP addresses is rather large and since machines in this range can belong to other customers as well. The best way to prevent this is to avoid the need to access internal resources. For information on deploying artifacts to a set of servers, see [Communication to deploy to target servers](agents.md#communication-to-deploy-to-target-servers). -- Hosted images do not conform to [CIS hardening benchmarks](https://www.cisecurity.org/benchmark/azure/). To use CIS-hardened images, you must create either self-hosted agents or scale-set agents. +- Hosted images do not conform to [CIS hardening benchmarks](https://www.cisecurity.org/benchmark/azure/). To use CIS-hardened images, you must create either self-hosted agents or scale-set agents or Managed DevOps pools. ## Capabilities and limitations @@ -257,21 +271,23 @@ Microsoft-hosted agents: * Public project: 10 free Microsoft-hosted parallel jobs that can run for up to 360 minutes (6 hours) each time, with no overall time limit per month. [Contact us](https://azure.microsoft.com/support/devops/) to get your free tier limits increased. * Private project: One free parallel job that can run for up to 60 minutes each time, until you've used 1,800 minutes (30 hours) per month. You can pay for additional capacity per parallel job. Paid parallel jobs remove the monthly time limit and allow you to run each job for up to 360 minutes (6 hours). [Buy Microsoft-hosted parallel jobs](https://marketplace.visualstudio.com/items?itemName=ms.build-release-hosted-pipelines). * When you create a new Azure DevOps organization, you are not given these free grants by default. To request the free grant for public or private projects, submit [a request](https://aka.ms/azpipelines-parallelism-request). -* Run on Microsoft Azure general purpose virtual machines [Standard_DS2_v2](/azure/virtual-machines/dv2-dsv2-series#dsv2-series) -* Run as an administrator on Windows and a passwordless sudo user on Linux -* (Linux only) Run steps in a `cgroup` that offers 6 GB of physical memory and 13 GB of total memory +* Run on Microsoft Azure general purpose virtual machines [Standard_DS2_v2](/azure/virtual-machines/dv2-dsv2-series#dsv2-series). +* Run as an administrator on Windows and a passwordless sudo user on Linux. +* (Linux only) Run steps in a `cgroup` that offers 6 GB of physical memory and 13 GB of total memory. +* Use VM images that are regularly updated (every 3 weeks). Microsoft-hosted agents do not offer: * The ability to remotely connect. -* The ability to [drop artifacts to a UNC file share](../artifacts/build-artifacts.md#publish-from-tfs-to-a-unc-file-share). +* The ability to [drop artifacts to a UNC file share](/previous-versions/azure/devops/pipelines/artifacts/build-artifacts?view=tfs-2018&preserve-view=true#publish-from-tfs-to-a-unc-file-share). * The ability to join machines directly to your corporate network. * The ability to get bigger or more powerful build machines. * The ability to pre-load custom software. You can install software during a pipeline run, such as through [tool installer tasks](../process/tasks.md#tool-installers) or in a script. * Potential performance advantages that you might get by using self-hosted agents that might start and run builds faster. [Learn more](agents.md#private-agent-performance-advantages) * The ability to run [XAML builds](/previous-versions/visualstudio/visual-studio-2013/ms181709(v=vs.120)). +* The ability to roll back to a previous VM image version. You always use the latest version. -If Microsoft-hosted agents don't meet your needs, then you can deploy your own [self-hosted agents](agents.md#install) or use [scale set agents](scale-set-agents.md). +If Microsoft-hosted agents don't meet your needs, then you can deploy your own [self-hosted agents](agents.md#install) or use [scale set agents](scale-set-agents.md) or [Managed DevOps Pools](../../managed-devops-pools/overview.md#usage-scenarios). ## FAQ @@ -298,7 +314,7 @@ You can also use a self-hosted agent that includes the exact versions of softwar ### What if I need a bigger machine with more processing power, memory, or disk space? -We can't increase the memory, processing power, or disk space for Microsoft-hosted agents, but you can use [self-hosted agents](agents.md#install) or [scale set agents](scale-set-agents.md) hosted on machines with your desired specifications. +We can't increase the memory, processing power, or disk space for Microsoft-hosted agents, but you can use [self-hosted agents](agents.md#install) or [scale set agents](scale-set-agents.md) or [Managed DevOps Pools](../../managed-devops-pools/overview.md#usage-scenarios) hosted on machines with your desired specifications. ### I can't select a Microsoft-hosted agent and I can't queue my build or deployment. What should I do? @@ -310,7 +326,7 @@ By default, all project contributors in an organization have access to the Micro If your pipeline has recently become slower, review our [status page](https://status.dev.azure.com/) for any outages. We could be having issues with our service. Or else, review any changes that you made in your application code or pipeline. Your repository size during check-out might have increased, you may be uploading larger artifacts, or you may be running more tests. -If you are just setting up a pipeline and are comparing the performance of Microsoft-hosted agents to your local machine or a self-hosted agent, then note the [specifications](#capabilities-and-limitations) of the hardware that we use to run your jobs. We are unable to provide you with bigger or powerful machines. You can consider using [self-hosted agents](agents.md) or [scale set agents](scale-set-agents.md) if this performance is not acceptable. +If you are just setting up a pipeline and are comparing the performance of Microsoft-hosted agents to your local machine or a self-hosted agent, then note the [specifications](#capabilities-and-limitations) of the hardware that we use to run your jobs. We are unable to provide you with bigger or powerful machines. You can consider using [self-hosted agents](agents.md) or [scale set agents](scale-set-agents.md) or [Managed DevOps Pools](../../managed-devops-pools/overview.md#usage-scenarios) if this performance is not acceptable. ### I need more agents. What can I do? @@ -320,9 +336,9 @@ All Azure DevOps organizations are provided with several free parallel jobs for Your self-hosted agent probably has all the right dependencies installed on it, whereas the same dependencies, tools, and software are not installed on Microsoft-hosted agents. First, carefully review the list of software that is installed on Microsoft-hosted agents by following the link to **Included software** in the table above. Then, compare that with the software installed on your self-hosted agent. In some cases, Microsoft-hosted agents may have the tools that you need (for example, Visual Studio), but all of the necessary optional components may not have been installed. If you find differences, then you have two options: -- You can create a new issue on the [repository](https://github.com/actions/runner-images), where we track requests for additional software. Contacting support will not help you with setting up new software on Microsoft-hosted agents. +- You can create a new issue on the [repository](https://github.com/actions/runner-images), where we track requests for additional software. Contacting support can't help you set up new software on Microsoft-hosted agents. -- You can use [self-hosted agents](agents.md) or [scale set agents](scale-set-agents.md). With these agents, you are fully in control of the images that are used to run your pipelines. +- You can use [self-hosted agents](agents.md) or [scale set agents](scale-set-agents.md) or [Managed DevOps Pools](../../managed-devops-pools/overview.md#usage-scenarios). With these agents, you are fully in control of the images that are used to run your pipelines. ### My build succeeds on my local machine, but fails on Microsoft-hosted agents. What should I do? @@ -330,11 +346,11 @@ Your local machine probably has all the right dependencies installed on it, wher - You can create a new issue on the [repository](https://github.com/actions/runner-images), where we track requests for additional software. This is your best bet for getting new software installed. Contacting support will not help you with setting up new software on Microsoft-hosted agents. -- You can use [self-hosted agents](agents.md) or [scale set agents](scale-set-agents.md). With these agents, you are fully in control of the images that are used to run your pipelines. +- You can use [self-hosted agents](agents.md) or [scale set agents](scale-set-agents.md) or [Managed DevOps Pools](../../managed-devops-pools/overview.md#usage-scenarios). With these agents, you are fully in control of the images that are used to run your pipelines. ### My pipeline fails with the error: "no space left on device". -Microsoft-hosted agents only have 10 GB of disk space available for running your job. This space is consumed when you check out source code, when you download packages, when you download docker images, or when you produce intermediate files. Unfortunately, we cannot increase the free space available on Microsoft-hosted images. You can restructure your pipeline so that it can fit into this space. Or, you can consider using [self-hosted agents](agents.md) or [scale set agents](scale-set-agents.md). +Microsoft-hosted agents only have 10 GB of disk space available for running your job. This space is consumed when you check out source code, when you download packages, when you download docker images, or when you produce intermediate files. Unfortunately, we cannot increase the free space available on Microsoft-hosted images. You can restructure your pipeline so that it can fit into this space. Or, you can consider using [self-hosted agents](agents.md) or [scale set agents](scale-set-agents.md) or [Managed DevOps Pools](../../managed-devops-pools/overview.md#usage-scenarios). ### My pipeline running on Microsoft-hosted agents requires access to servers on our corporate network. How do we get a list of IP addresses to allow in our firewall? @@ -350,46 +366,22 @@ If you get an SAS error code, it is most likely because the IP address ranges fr 1. [Manage the IP network rules for your Azure Storage account](/azure/storage/common/storage-network-security?tabs=azure-portal#managing-ip-network-rules) and add the [IP address ranges for your hosted agents](#networking). 2. In your pipeline, use [Azure CLI to update the network ruleset for your Azure Storage account](/powershell/module/az.storage/update-azstorageaccountnetworkruleset) right before you access storage, and then restore the previous ruleset. -3. Use [self-hosted agents](agents.md#install) or [Scale set agents](scale-set-agents.md). +3. Use [self-hosted agents](agents.md#install) or [Scale set agents](scale-set-agents.md) or [Managed DevOps Pools](../../managed-devops-pools/overview.md#usage-scenarios). ### How can I manually select versions of tools on the Hosted macOS agent? -#### Xamarin - - **Hosted macOS** agent stores Xamarin SDK versions and the associated Mono versions as a set of symlinks to Xamarin SDK locations that are available by a single bundle symlink. - - To manually select a Xamarin SDK version to use on the **Hosted macOS** agent, execute the following bash command before your Xamarin build task as a part of your build, specifying the symlink to Xamarin versions bundle that you need. - - `/bin/bash -c "sudo $AGENT_HOMEDIRECTORY/scripts/select-xamarin-sdk.sh "` - - The list of all available Xamarin SDK versions and symlinks can be found in the agents documentation: - - [macOS 11](https://github.com/actions/runner-images/blob/main/images/macos/macos-11-Readme.md#xamarin) - - [macOS 12](https://github.com/actions/runner-images/blob/main/images/macos/macos-12-Readme.md#xamarin) - -This command does not select the Mono version beyond the Xamarin SDK. To manually select a Mono version, see instructions below. - - In case you are using a non-default version of Xcode for building your Xamarin.iOS or Xamarin.Mac apps, you should additionally execute this command line: - - `/bin/bash -c "echo '##vso[task.setvariable variable=MD_APPLE_SDK_ROOT;]'$(xcodeRoot);sudo xcode-select --switch $(xcodeRoot)/Contents/Developer"` - - where `$(xcodeRoot)` = `/Applications/Xcode_13.2.app` - - Xcode versions on the **Hosted macOS** agent pool can be found [here](https://github.com/actions/runner-images/blob/main/images/macos/macos-11-Readme.md#xcode) for the `macos-11` agent and [here](https://github.com/actions/runner-images/blob/main/images/macos/macos-12-Readme.md#xcode) for the `macos-12` agent. - #### Xcode If you use the [Xcode task](/azure/devops/pipelines/tasks/reference/xcode-v5) included with Azure Pipelines and TFS, you can select a version of Xcode in that task's properties. Otherwise, to manually set the Xcode version to use on the **Hosted macOS** agent pool, before your `xcodebuild` build task, execute this command line as part of your build, replacing the Xcode version number 13.2 as needed: `/bin/bash -c "sudo xcode-select -s /Applications/Xcode_13.2.app/Contents/Developer"` - Xcode versions on the **Hosted macOS** agent pool can be found [here](https://github.com/actions/runner-images/blob/main/images/macos/macos-11-Readme.md#xcode) for the `macos-11` agent and [here](https://github.com/actions/runner-images/blob/main/images/macos/macos-12-Readme.md#xcode) for the `macos-12` agent. - - This command does not work for Xamarin apps. To manually select an Xcode version for building Xamarin apps, see instructions above. + Xcode versions on the **Hosted macOS** agent pool can be found [here](https://github.com/actions/runner-images/blob/main/images/macos/). #### Mono - To manually select a Mono version to use on the **Hosted macOS** agent pool, execute this script in each job of your build before your Mono build task, specifying the symlink with the required Mono version (list of all available symlinks can be found in the [Xamarin section](#xamarin) above): + To manually select a Mono version to use on the **Hosted macOS** agent pool, execute this script in each job of your build before your Mono build task, specifying the symlink with the required Mono version: ```bash SYMLINK= diff --git a/docs/pipelines/agents/includes/agent-capabilities-tab.md b/docs/pipelines/agents/includes/agent-capabilities-tab.md index 777d988d11b..8b1d28f537e 100644 --- a/docs/pipelines/agents/includes/agent-capabilities-tab.md +++ b/docs/pipelines/agents/includes/agent-capabilities-tab.md @@ -19,15 +19,3 @@ ms.date: 08/07/2020 ::: moniker-end -::: moniker range="azure-devops-2019" - -[!INCLUDE [agent-capabilities](agent-capabilities-tab/agent-capabilities-tab-server-2019.md)] - -::: moniker-end - -::: moniker range="tfs-2018" - -[!INCLUDE [agent-capabilities](agent-capabilities-tab/agent-capabilities-tab-tfs-2018.md)] - -::: moniker-end - diff --git a/docs/pipelines/agents/includes/agent-directory-structure.md b/docs/pipelines/agents/includes/agent-directory-structure.md new file mode 100644 index 00000000000..2a058ee7c7b --- /dev/null +++ b/docs/pipelines/agents/includes/agent-directory-structure.md @@ -0,0 +1,45 @@ +--- +ms.topic: include +ms.service: azure-devops-pipelines +ms.manager: mijacobs +ms.author: sdanie +ms.date: 01/28/2025 +--- + +When pipeline jobs are run on agents, a directory structure is created to store the source code, binaries, and artifacts. + +The agent's home directory is the directory where the agent is installed. The directory is typically located: + +- **Microsoft-hosted agents:** `C:\agents\` on Windows, `/Users/runner/runners/` on macOS, and `/home/vsts/agents/` on Linux. +- **Self-hosted agents:** `C:\agent` on Windows, `Users//agent` (`~/agent`) on macOS, and `/home/vsts/agent` on Linux. + +The agent's work directory contains the workspace where the source and jobs output is stored. The work directory is typically located: + +- **Microsoft-hosted agent:** `C:\a` on Windows, `/Users/runner/work` on macOS, and`/home/vsts/work` on Linux. +- **Self-hosted agent:** `C:\agent\_work` on Windows, `~/agent/work` on macOS, and `/home/agent/_work` on Linux. + +The work directory structure is as follows: + +```plaintext + + - /work directory + - /1 build directory/pipeline workspace + - /s source/working directory + - /b binaries directory + - /a artifacts staging directory + - /TestResults Test results directory +``` + +| Directory | Description | Examples | Predefined variables | +|-----------|-------------|----------|------------| +|Agent home directory| Where the agent is installed | **Microsoft-hosted agent:**
         Windows: `C:\agents\3.248.0`
         Linux: `/home/vsts/agents/3.248.0`
         macOS: `/Users/runner/runners/3.248.0`
      **Self-hosted agent:**
         Windows: `C:\agent`
         Linux: `home/agent`
         macOS: `~/agent` | `Agent.HomeDirectory` | +|Work directory| Where the agent stores the source code, binaries, and artifacts | **Microsoft-hosted agent:**
         Windows: `C:\a`
         Linux: `/home/vsts/work`
         macOS: `/Users/runner/work`
      **Self-hosted agent:**
         Windows: `C:\agent\_work`
         Linux: `/home/agent/_work`
         macOS: `~/agent/work` | `Agent.WorkFolder`
      `Agent.RootDirectory`
      `System.WorkFolder`| +|Build directory/workspace | Where the pipeline job runs | **Microsoft-hosted agent:**
         Windows: `C:\a\1`
         Linux: `/home/vsts/work/1`
         macOS: `/Users/runner/work/1`
      **Self-hosted agent:**
         Windows: `C:\agent\_work\1`
         Linux: `/home/agent/_work/1`
         macOS: `~/agent/work/1`| `Agent.BuildDirectory`
      `Pipeline.Workspace`| +| `s` - Source/working directory | Contains the source code that is checked out from the repository. [If you have multiple `checkout` steps in your job, your source code is checked out into directories named after the repositories as a subfolder of `s`](../../repos/multi-repo-checkout.md#checkout-path). | **Microsoft-hosted agent:**
         Windows: `C:\a\1\s`
         Linux: `/home/vsts/work/1/s`
         macOS: `/Users/runner/work/1/s`
      **Self-hosted agent:**
         Windows: `C:\agent\_work\1\s`
         Linux: `/home/agent/_work/1/s`
         macOS: `~/agent/work/1/s` | `Build.SourcesDirectory`
      `Build.RepositoryLocalPath`
      `System.DefaultWorkingDirectory`| +| `b` - Binaries directory | Contains the build outputs. | **Microsoft-hosted agent:**
         Windows: `C:\a\1\b`
         Linux: `/home/vsts/work/1/b`
         macOS: `/Users/runner/work/1/b`
      **Self-hosted agent:**
         Windows: `C:\agent\_work\1\b`
         Linux: `/home/agent/_work/1/b`
         macOS: `~/agent/work/1/b` | `Build.BinariesDirectory`| +| `a` - Artifacts staging directory | Contains the build artifacts. Is cleaned between runs on self-hosted agents. | **Microsoft-hosted agent:**
         Windows: `C:\a\1\a`
         Linux: `/home/vsts/work/1/a`
         macOS: `/Users/runner/work/1/a`
      **Self-hosted agent:**
         Windows: `C:\agent\_work\1\a`
         Linux: `/home/agent/_work/1/a`
         macOS: `~/agent/work/1/a`| `Build.StagingDirectory`
      `Build.ArtifactStagingDirectory`
      `System.ArtifactsDirectory`| +| TestResults directory | Contains the test results. Is cleaned between runs on self-hosted agents.| **Microsoft-hosted agent:**
         Windows: `C:\a\1\TestResults`
         Linux: `/home/vsts/work/1/TestResults`
         macOS: `/Users/runner/work/1/TestResults`
      **Self-hosted agent:**
         Windows: `C:\agent\_work\1\TestResults`
         Linux: `/home/agent/_work/1/TestResults`
         macOS: `~/agent/work/1/TestResults`| `Common.TestResultsDirectory`| + +On Microsoft-hosted agents, a different agent is used on each run, therefore the work directory isn't retained between runs. On self-hosted agents, only the artifacts staging directory and test results directories are cleaned by default between runs. For more information about the workspace clean option, see [Workspace](../../process/phases.md#workspace). + +For more information about predefined variables, see [Predefined variables](../../build/variables.md). \ No newline at end of file diff --git a/docs/pipelines/agents/includes/agent-pools-tab.md b/docs/pipelines/agents/includes/agent-pools-tab.md index 52b877fd8ac..57d3bcdcc25 100644 --- a/docs/pipelines/agents/includes/agent-pools-tab.md +++ b/docs/pipelines/agents/includes/agent-pools-tab.md @@ -19,15 +19,3 @@ ms.date: 08/07/2020 ::: moniker-end -::: moniker range="azure-devops-2019" - -[!INCLUDE [agent-pools-tab](agent-pools-tab/agent-pools-tab-server-2019.md)] - -::: moniker-end - -::: moniker range="tfs-2018" - -[!INCLUDE [agent-pools-tab](agent-pools-tab/agent-pools-tab-tfs-2018.md)] - -::: moniker-end - diff --git a/docs/pipelines/agents/includes/agent-queues-tab.md b/docs/pipelines/agents/includes/agent-queues-tab.md index d60049de590..fa195a33867 100644 --- a/docs/pipelines/agents/includes/agent-queues-tab.md +++ b/docs/pipelines/agents/includes/agent-queues-tab.md @@ -19,15 +19,3 @@ ms.date: 08/07/2020 ::: moniker-end -::: moniker range="azure-devops-2019" - -[!INCLUDE [agent-queues-tab](agent-queues-tab/agent-queues-tab-server-2019.md)] - -::: moniker-end - -::: moniker range="tfs-2018" - -[!INCLUDE [agent-queues-tab](agent-queues-tab/agent-queues-tab-tfs-2018.md)] - -::: moniker-end - diff --git a/docs/pipelines/agents/includes/agent-setup-authentication.md b/docs/pipelines/agents/includes/agent-setup-authentication.md new file mode 100644 index 00000000000..79516fa8f2b --- /dev/null +++ b/docs/pipelines/agents/includes/agent-setup-authentication.md @@ -0,0 +1,23 @@ +--- +ms.topic: include +ms.service: azure-devops-pipelines +ms.manager: mijacobs +ms.author: sdanie +author: steved0x +ms.date: 10/09/2023 +--- + +:::moniker range="azure-devops" + +* [Personal access token](../personal-access-token-agent-registration.md) +* [Device code flow](../device-code-flow-agent-registration.md) +* [Service principal](../service-principal-agent-registration.md) + +:::moniker-end + +:::moniker range="<= azure-devops-2022" + +* [Personal access token](../personal-access-token-agent-registration.md) +* [Alternate](../agent-authentication-options.md#alternate-alt) Connect to Azure DevOps Server or TFS using Basic authentication. When you select **Alternate** you'll be prompted for your credentials. + +:::moniker-end diff --git a/docs/pipelines/agents/includes/hosted-agent-intro.md b/docs/pipelines/agents/includes/hosted-agent-intro.md index 8ff0700ad87..169e38dfe6c 100644 --- a/docs/pipelines/agents/includes/hosted-agent-intro.md +++ b/docs/pipelines/agents/includes/hosted-agent-intro.md @@ -7,11 +7,11 @@ author: steved0x ms.date: 02/12/2020 --- -If your pipelines are in Azure Pipelines, then you've got a convenient option to run your jobs using a **Microsoft-hosted agent**. With Microsoft-hosted agents, maintenance and upgrades are taken care of for you. Each time you run a pipeline, you get a fresh virtual machine for each job in the pipeline. The virtual machine is discarded after one job (which means any change that a job makes to the virtual machine file system, such as checking out code, will be unavailable to the next job). Microsoft-hosted agents can run jobs [directly on the VM](../../process/phases.md) or [in a container](../../process/container-phases.md). +If your pipelines are in Azure Pipelines, then you've got a convenient option to run your jobs using a **Microsoft-hosted agent**. With Microsoft-hosted agents, maintenance and upgrades are taken care of for you. You always get the latest version of the VM image you specify in your pipeline. Each time you run a pipeline, you get a fresh virtual machine for each job in the pipeline. The virtual machine is discarded after one job (which means any change that a job makes to the virtual machine file system, such as checking out code, will be unavailable to the next job). Microsoft-hosted agents can run jobs [directly on the VM](../../process/phases.md) or [in a container](../../process/container-phases.md). Azure Pipelines provides a predefined agent pool named **Azure Pipelines** with Microsoft-hosted agents. -For many teams this is the simplest way to run your jobs. You can try it first and see if it works for your build or deployment. If not, you can use a self-hosted agent. +For many teams this is the simplest way to run your jobs. You can try it first and see if it works for your build or deployment. If not, you can use [scale set agents](../scale-set-agents.md) or a self-hosted agent. > [!TIP] > diff --git a/docs/pipelines/agents/includes/v2/configure-help-unix.md b/docs/pipelines/agents/includes/v2/configure-help-unix.md index e67d5d14d19..6dd6d8dc221 100644 --- a/docs/pipelines/agents/includes/v2/configure-help-unix.md +++ b/docs/pipelines/agents/includes/v2/configure-help-unix.md @@ -12,7 +12,7 @@ ms.date: 02/12/2020 The agent can be set up from a script with no human intervention. You must pass `--unattended` and the answers to all questions. -::: moniker range="> tfs-2018" +::: moniker range="<=azure-devops" [!INCLUDE [unattend](./unattended-config.md)] diff --git a/docs/pipelines/agents/includes/v2/prepare-permissions.md b/docs/pipelines/agents/includes/v2/prepare-permissions.md index a8d4ebe6b2f..81a8e6eea1d 100644 --- a/docs/pipelines/agents/includes/v2/prepare-permissions.md +++ b/docs/pipelines/agents/includes/v2/prepare-permissions.md @@ -35,13 +35,7 @@ Learn more about [how agents communicate](../../agents.md#communication). ::: moniker-end -::: moniker range="< azure-devops-2019" - -1. Sign in with the user account you plan to use in your Team Foundation Server web portal (`https://{your-server}:8080/tfs/`). - -::: moniker-end - -::: moniker range=" >= azure-devops-2019 < azure-devops" +::: moniker range=" If you are configuring a deployment group agent, or if you see an error when registering a VM environment resource, you must set the PAT scope to **All accessible organizations**. > :::image type="content" source="../../media/prepare-permissions-pat-scope.png" alt-text="Screenshot of setting PAT scope to all accessible organizations."::: - ::: moniker-end ::: moniker range="azure-devops" diff --git a/docs/pipelines/agents/includes/v2/qa-agent-version.md b/docs/pipelines/agents/includes/v2/qa-agent-version.md index 9d8382bab15..d53125958dd 100644 --- a/docs/pipelines/agents/includes/v2/qa-agent-version.md +++ b/docs/pipelines/agents/includes/v2/qa-agent-version.md @@ -7,7 +7,7 @@ author: steved0x ms.date: 02/12/2020 --- -### How do I make sure I have the latest v2 agent version? +### How do I make sure I have the latest agent version? 1. Navigate to the **Agent pools** tab: @@ -27,7 +27,7 @@ ms.date: 02/12/2020 ::: moniker range="< azure-devops" -### Can I update my v2 agents that are part of an Azure DevOps Server pool? +### Can I update my agents that are part of an Azure DevOps Server pool? Yes. Beginning with Azure DevOps Server 2019, you can configure your server to look for the agent package files on a local disk. diff --git a/docs/pipelines/agents/includes/v2/qa-firewall.md b/docs/pipelines/agents/includes/v2/qa-firewall.md index 8aead98f767..9da8f119a70 100644 --- a/docs/pipelines/agents/includes/v2/qa-firewall.md +++ b/docs/pipelines/agents/includes/v2/qa-firewall.md @@ -4,7 +4,7 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: sdanie author: steved0x -ms.date: 02/12/2020 +ms.date: 04/02/2025 --- ### I'm running a firewall and my code is in Azure Repos. What URLs does the agent need to communicate with? @@ -28,9 +28,9 @@ If you're running an agent in a secure network behind a firewall, make sure the | `https://*.vstmr.visualstudio.com` | Azure DevOps Test Management Services for organizations using the `dev.azure.com` domain| | `https://app.vssps.visualstudio.com` | For organizations using the `{organization_name}.visualstudio.com` domain | | `https://dev.azure.com` | For organizations using the `dev.azure.com` domain | -| `https://login.microsoftonline.com` | Azure Active Directory sign in | -| `https://management.core.windows.net` | Azure Management API's | -| `https://vstsagentpackage.azureedge.net` | Agent package | +| `https://login.microsoftonline.com` | Microsoft Entra sign-in | +| `https://management.core.windows.net` | Azure Management APIs | +| `https://vstsagentpackage.azureedge.net`
      `https://download.agent.dev.azure.com` | Agent package | To ensure your organization works with any existing firewall or IP restrictions, ensure that `dev.azure.com` and `*dev.azure.com` are open and update your allow-listed IPs to include the following IP addresses, based on your IP version. If you're currently allow-listing the `13.107.6.183` and `13.107.9.183` IP addresses, leave them in place, as you don't need to remove them. diff --git a/docs/pipelines/agents/includes/v2/unattended-config.md b/docs/pipelines/agents/includes/v2/unattended-config.md index 44a18a901c8..d82352042a4 100644 --- a/docs/pipelines/agents/includes/v2/unattended-config.md +++ b/docs/pipelines/agents/includes/v2/unattended-config.md @@ -4,7 +4,7 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: sdanie author: steved0x -ms.date: 02/12/2020 +ms.date: 04/17/2024 --- To configure an agent, it must know the URL to your organization or collection and credentials of someone authorized to set up agents. @@ -50,6 +50,7 @@ agent and should not be shared between multiple agents. - `--windowsLogonAccount ` - used with `--runAsService` or `--runAsAutoLogon` to specify the Windows user name in the format `domain\userName` or `userName@domain.com` - `--windowsLogonPassword ` - used with `--runAsService` or `--runAsAutoLogon` to specify Windows logon password (not required for [Group Managed Service Accounts](https://aka.ms/gmsa) and Windows built in accounts such as 'NT AUTHORITY\NETWORK SERVICE') +- `--enableservicesidtypeunrestricted` - used with `--runAsService` to configure the agent with service SID type as `SERVICE_SID_TYPE_UNRESTRICTED` (requires administrator permission) - `--overwriteAutoLogon` - used with `--runAsAutoLogon` to overwrite the existing auto logon on the machine - `--noRestart` - used with `--runAsAutoLogon` to stop the host from restarting after agent configuration completes diff --git a/docs/pipelines/agents/includes/v2/web-proxy-bypass.md b/docs/pipelines/agents/includes/v2/web-proxy-bypass.md index 10a50dcbeb1..b58526c0492 100644 --- a/docs/pipelines/agents/includes/v2/web-proxy-bypass.md +++ b/docs/pipelines/agents/includes/v2/web-proxy-bypass.md @@ -4,7 +4,7 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: sdanie author: steved0x -ms.date: 02/12/2020 +ms.date: 04/02/2025 --- ### How do I configure the agent to bypass a web proxy and connect to Azure Pipelines? @@ -31,6 +31,7 @@ https://*.dev.azure.com https://login.microsoftonline.com https://management.core.windows.net https://vstsagentpackage.azureedge.net +https://download.agent.dev.azure.com https://vssps.dev.azure.com ``` diff --git a/docs/pipelines/agents/includes/v3/configure-help-unix.md b/docs/pipelines/agents/includes/v3/configure-help-unix.md index 5c8290446d2..1dc97b94ac0 100644 --- a/docs/pipelines/agents/includes/v3/configure-help-unix.md +++ b/docs/pipelines/agents/includes/v3/configure-help-unix.md @@ -12,9 +12,9 @@ ms.date: 06/13/2023 The agent can be set up from a script with no human intervention. You must pass `--unattended` and the answers to all questions. -::: moniker range="> tfs-2018" +::: moniker range="<=azure-devops" -[!INCLUDE [unattend](./unattended-config.md)] +[!INCLUDE [unattend](./unattended-config-unix.md)] ::: moniker-end diff --git a/docs/pipelines/agents/includes/v3/prepare-permissions.md b/docs/pipelines/agents/includes/v3/prepare-permissions.md index a8d4ebe6b2f..c70c77aadd6 100644 --- a/docs/pipelines/agents/includes/v3/prepare-permissions.md +++ b/docs/pipelines/agents/includes/v3/prepare-permissions.md @@ -4,18 +4,18 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: sdanie author: steved0x -ms.date: 02/12/2020 +ms.date: 09/22/2023 --- ### Information security for self-hosted agents The user configuring the agent needs pool admin permissions, but the user running the agent does not. -The folders controlled by the agent should be restricted to as few users as possible and they contain secrets that could be decrypted or exfiltrated. +The folders controlled by the agent should be restricted to as few users as possible because they contain secrets that could be decrypted or exfiltrated. The Azure Pipelines agent is a software product designed to execute code it downloads from external sources. It inherently could be a target for Remote Code Execution (RCE) attacks. -Therefore, it is important to consider the threat model surrounding each individual usage of Pipelines Agents to perform work, and decide what are the minimum permissions could be granted to the user running the agent, to the machine where the agent runs, to the users who have write access to the Pipeline definition, the git repos where the yaml is stored, or the group of users who control access to the pool for new pipelines. +Therefore, it is important to consider the threat model surrounding each individual usage of Pipelines Agents to perform work, and decide what are the minimum permissions that could be granted to the user running the agent, to the machine where the agent runs, to the users who have write access to the Pipeline definition, the git repos where the yaml is stored, or the group of users who control access to the pool for new pipelines. It is a best practice to have the identity running the agent be different from the identity with permissions to connect the agent to the pool. The user generating the credentials (and other agent-related files) is different than the user that needs to read them. Therefore, it is safer to carefully consider access granted to the agent machine itself, and the agent folders which contain sensitive files, such as logs and artifacts. @@ -29,70 +29,6 @@ must complete these steps. The agent will not use this person's credentials in everyday operation, but they're required to complete registration. Learn more about [how agents communicate](../../agents.md#communication). -::: moniker range="<= azure-devops" - -#### Authenticate with a personal access token (PAT) - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -1. Sign in with the user account you plan to use in your Team Foundation Server web portal (`https://{your-server}:8080/tfs/`). - -::: moniker-end - -::: moniker range=" >= azure-devops-2019 < azure-devops" - -1. Sign in with the user account you plan to use in your Azure DevOps Server web portal (`https://{your-server}/DefaultCollection/`). - -::: moniker-end - -::: moniker range="azure-devops" - -1. Sign in with the user account you plan to use in your Azure DevOps organization (`https://dev.azure.com/{your_organization}`). - -::: moniker-end - -::: moniker range="< azure-devops" - -2. From your home page, open your profile. Go to your security details. - - ![Go to your security details.](/azure/devops/repos/git/media/my-profile-team-services.png) - -3. [Create a personal access token](../../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). - - ![Create a personal access token.](/azure/devops/repos/git/media/add-personal-access-token.png) - - > [!NOTE] - > If you are configuring a deployment group agent, or if you see an error when registering a VM environment resource, you must set the PAT scope to **All accessible organizations**. - > :::image type="content" source="../../media/prepare-permissions-pat-scope.png" alt-text="Screenshot of setting PAT scope to all accessible organizations."::: - - -::: moniker-end - -::: moniker range="azure-devops" - -2. From your home page, open your user settings, and then select **Personal access tokens**. - - ![Go to your security details.](/azure/devops/repos/git/media/select-personal-access-tokens.jpg) - -3. [Create a personal access token](../../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). - - ![Create a personal access token.](/azure/devops/repos/git/media/select-new-token.png) - -::: moniker-end - -::: moniker range="<= azure-devops" - -4. For the scope select **Agent Pools (read, manage)** and make sure all the other boxes are cleared. - If it's a [deployment group](../../../release/deployment-groups/index.md) agent, for the scope select **Deployment group (read, manage)** and make sure all the other boxes are cleared. - - Select **Show all scopes** at the bottom of the **Create a new personal access token window** window to see the complete list of scopes. - -5. Copy the token. You'll use this token when you configure the agent. - -::: moniker-end - ### Confirm the user has permission Make sure the user account that you're going to use has permission to register the agent. @@ -114,4 +50,4 @@ Otherwise: You can add a user to the deployment group administrator role in the **Security** tab on the **Deployment Groups** page in **Azure Pipelines**. > [!NOTE] -> If you see a message like this: **Sorry, we couldn't add the identity. Please try a different identity.**, you probably followed the above steps for an organization owner or TFS or Azure DevOps Server administrator. You don't need to do anything; you already have permission to administer the agent queue. +> If you see a message like this: **Sorry, we couldn't add the identity. Please try a different identity.**, you probably followed the above steps for an organization owner or TFS or Azure DevOps Server administrator. You don't need to do anything; you already have permission to administer the agent pool. diff --git a/docs/pipelines/agents/includes/v3/qa-agent-version.md b/docs/pipelines/agents/includes/v3/qa-agent-version.md index b52018844c9..9a560a37dd2 100644 --- a/docs/pipelines/agents/includes/v3/qa-agent-version.md +++ b/docs/pipelines/agents/includes/v3/qa-agent-version.md @@ -36,7 +36,12 @@ This scenario also applies when the server doesn't have access to the internet. 1. From a computer with Internet access, download the latest version of the agent package files (in .zip or .tar.gz form) from the [Azure Pipelines Agent GitHub Releases page](https://github.com/Microsoft/azure-pipelines-agent/releases). -2. Transfer the downloaded package files to each Azure DevOps Server Application Tier by using a method of your choice (such as USB drive, Network transfer, and so on). Place the agent files under the `%ProgramData%\Microsoft\Azure DevOps\Agents` folder. Create the **Agents** folder if it is not present. +2. Transfer the downloaded package files to each Azure DevOps Server Application Tier by using a method of your choice (such as USB drive, Network transfer, and so on). Place the agent files under the following folder: + * Windows: `%ProgramData%\Microsoft\Azure DevOps\Agents` + * Linux: `usr/share/Microsoft/Azure DevOps/Agents` + * macOS: `usr/share/Microsoft/Azure DevOps/Agents` + + Create the **Agents** folder if it is not present. 3. You're all set! Your Azure DevOps Server will now use the local files whenever the agents are updated. Each agent automatically updates itself when it runs a task that requires a newer version of the agent. But if you want to manually update some agents, right-click the pool, and then choose **Update all agents**. diff --git a/docs/pipelines/agents/includes/v3/qa-firewall.md b/docs/pipelines/agents/includes/v3/qa-firewall.md index 37b5e62a338..691d27cfbb2 100644 --- a/docs/pipelines/agents/includes/v3/qa-firewall.md +++ b/docs/pipelines/agents/includes/v3/qa-firewall.md @@ -4,7 +4,7 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: sdanie author: steved0x -ms.date: 02/12/2020 +ms.date: 04/02/2025 --- ### I'm running a firewall and my code is in Azure Repos. What URLs does the agent need to communicate with? @@ -28,26 +28,53 @@ If you're running an agent in a secure network behind a firewall, make sure the | `https://*.vstmr.visualstudio.com` | Azure DevOps Test Management Services for organizations using the `dev.azure.com` domain| | `https://app.vssps.visualstudio.com` | For organizations using the `{organization_name}.visualstudio.com` domain | | `https://dev.azure.com` | For organizations using the `dev.azure.com` domain | -| `https://login.microsoftonline.com` | Azure Active Directory sign in | +| `https://login.microsoftonline.com` | Microsoft Entra sign-in | | `https://management.core.windows.net` | Azure Management APIs | -| `https://vstsagentpackage.azureedge.net` | Agent package | +| `https://vstsagentpackage.azureedge.net`
      `https://download.agent.dev.azure.com` | Agent package | +> [!IMPORTANT] +> [Edgio CDN for Azure DevOps is being retired](https://devblogs.microsoft.com/devops/important-switching-cdn-providers/), which requires a new domain URL to be allow-listed in firewall rules for agent software download. +> The new domain to allow-list for agent download is `https://*.dev.azure.com`. If your firewall rules don't allow wildcards, use `https://download.agent.dev.azure.com`. +> +> The Azure DevOps team recommends to make this change by the following date: +> - May 1, 2025 for Azure DevOps Services +> - May 15, 2025 for Azure DevOps Server +> +> For more information, see [CDN Domain URL change for Agents in Pipelines](https://devblogs.microsoft.com/devops/cdn-domain-url-change-for-agents-in-pipelines/). To ensure your organization works with any existing firewall or IP restrictions, ensure that `dev.azure.com` and `*dev.azure.com` are open and update your allow-listed IPs to include the following IP addresses, based on your IP version. If you're currently allow-listing the `13.107.6.183` and `13.107.9.183` IP addresses, leave them in place, as you don't need to remove them. -**IPv4 ranges** +#### [IP V4 ranges](#tab/IP-V4) -* `13.107.6.0/24` -* `13.107.9.0/24` -* `13.107.42.0/24` -* `13.107.43.0/24` +```IP V4 ranges -**IPv6 ranges** +13.107.6.0/24 +13.107.9.0/24 +13.107.42.0/24 +13.107.43.0/24 +150.171.22.0/24 +150.171.23.0/24 +150.171.73.0/24 +150.171.74.0/24 +150.171.75.0/24 +150.171.76.0/24 +``` + +#### [IP V6 ranges](#tab/IP-V6) + +```IP V6 ranges + +2620:1ec:4::/48 +2620:1ec:a92::/48 +2620:1ec:21::/48 +2620:1ec:22::/48 +2620:1ec:50::/48 +2620:1ec:51::/48 +2603:1061:10::/48 +``` + +--- -* `2620:1ec:4::/48` -* `2620:1ec:a92::/48` -* `2620:1ec:21::/48` -* `2620:1ec:22::/48` > [!NOTE] > For more information about allowed addresses, see [Allowed address lists and network connections](../../../../organizations/security/allow-list-ip-url.md). diff --git a/docs/pipelines/agents/includes/v3/unattended-config-unix.md b/docs/pipelines/agents/includes/v3/unattended-config-unix.md new file mode 100644 index 00000000000..c139660aaf6 --- /dev/null +++ b/docs/pipelines/agents/includes/v3/unattended-config-unix.md @@ -0,0 +1,56 @@ +--- +ms.topic: include +ms.service: azure-devops-pipelines +ms.manager: mijacobs +ms.author: sdanie +author: steved0x +ms.date: 02/12/2020 +--- + +To configure an agent, it must know the URL to your organization or collection and credentials of someone authorized to set up agents. +All other responses are optional. +Any command-line parameter can be specified using an environment variable instead: +put its name in upper case and prepend `VSTS_AGENT_INPUT_`. +For example, `VSTS_AGENT_INPUT_PASSWORD` instead of specifying `--password`. + +### Required options + +- `--unattended` - agent setup will not prompt for information, and all settings must be provided on the command line +- `--url ` - URL of the server. For example: https://dev.azure.com/myorganization or http://my-azure-devops-server:8080/tfs +- `--auth ` - authentication type. Valid values are: + - `pat` (Personal access token) - PAT is the only scheme that works with Azure DevOps Services. + - `alt` (Basic authentication) + +### Authentication options + +- If you chose `--auth pat`: + - `--token ` - specifies your personal access token + - PAT is the only scheme that works with Azure DevOps Services. +- If you chose `--auth negotiate` or `--auth alt`: + - `--userName ` - specifies a username + - `--password ` - specifies a password + +### Pool and agent names +- `--pool ` - pool name for the agent to join +- `--agent ` - agent name +- `--replace` - replace the agent in a pool. If another agent is listening by the same name, it will start failing with a conflict + +### Agent setup +- `--work ` - work directory where job data is stored. Defaults to `_work` under the +root of the agent directory. The work directory is owned by a given +agent and should not be shared between multiple agents. +- `--acceptTeeEula` - accept the Team Explorer Everywhere End User License Agreement (macOS and Linux only) +- `--disableloguploads` - don't stream or send console log output to the server. Instead, you may retrieve them from the agent host's filesystem after the job completes. + +### Deployment group only +- `--deploymentGroup` - configure the agent as a deployment group agent +- `--deploymentGroupName ` - used with `--deploymentGroup` to specify the deployment group for the agent to join +- `--projectName ` - used with `--deploymentGroup` to set the project name +- `--addDeploymentGroupTags` - used with `--deploymentGroup` to indicate that deployment group tags should be added +- `--deploymentGroupTags ` - used with `--addDeploymentGroupTags` to specify the comma separated list of tags for +the deployment group agent - for example "web, db" + +### Environments only +- `--addvirtualmachineresourcetags` - used to indicate that environment resource tags should be added +- `--virtualmachineresourcetags ` - used with `--addvirtualmachineresourcetags` to specify the comma separated list of tags for +the environment resource agent - for example "web, db" diff --git a/docs/pipelines/agents/includes/v3/unattended-config.md b/docs/pipelines/agents/includes/v3/unattended-config.md index 44a18a901c8..6881c0ec547 100644 --- a/docs/pipelines/agents/includes/v3/unattended-config.md +++ b/docs/pipelines/agents/includes/v3/unattended-config.md @@ -4,7 +4,7 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: sdanie author: steved0x -ms.date: 02/12/2020 +ms.date: 04/17/2024 --- To configure an agent, it must know the URL to your organization or collection and credentials of someone authorized to set up agents. @@ -18,7 +18,8 @@ For example, `VSTS_AGENT_INPUT_PASSWORD` instead of specifying `--password`. - `--unattended` - agent setup will not prompt for information, and all settings must be provided on the command line - `--url ` - URL of the server. For example: https://dev.azure.com/myorganization or http://my-azure-devops-server:8080/tfs - `--auth ` - authentication type. Valid values are: - - `pat` (Personal access token) - PAT is the only scheme that works with Azure DevOps Services. + - `pat` (Personal access token) + - `SP` (Service Principal) (Requires [agent version 3.227.1](https://github.com/microsoft/azure-pipelines-agent/releases/tag/v3.227.1) or newer) - `negotiate` (Kerberos or NTLM) - `alt` (Basic authentication) - `integrated` (Windows default credentials) @@ -27,10 +28,16 @@ For example, `VSTS_AGENT_INPUT_PASSWORD` instead of specifying `--password`. - If you chose `--auth pat`: - `--token ` - specifies your personal access token - - PAT is the only scheme that works with Azure DevOps Services. + - You can also pass an OAuth 2.0 token as the `--token` parameter. - If you chose `--auth negotiate` or `--auth alt`: - `--userName ` - specifies a Windows username in the format `domain\userName` or `userName@domain.com` - `--password ` - specifies a password +- If you chose `--auth SP`: + - `--clientID ` - specifies the Client ID of the Service Principal with access to register agents + - `--tenantId ` - specifies the Tenant ID which the Service Principal is registered in + - `--clientSecret ` - specifies the Client Secret of the Service Principal + - See [Register an agent using a service principal](../../service-principal-agent-registration.md) for more information + ### Pool and agent names - `--pool ` - pool name for the agent to join @@ -50,6 +57,7 @@ agent and should not be shared between multiple agents. - `--windowsLogonAccount ` - used with `--runAsService` or `--runAsAutoLogon` to specify the Windows user name in the format `domain\userName` or `userName@domain.com` - `--windowsLogonPassword ` - used with `--runAsService` or `--runAsAutoLogon` to specify Windows logon password (not required for [Group Managed Service Accounts](https://aka.ms/gmsa) and Windows built in accounts such as 'NT AUTHORITY\NETWORK SERVICE') +- `--enableservicesidtypeunrestricted` - used with `--runAsService` to configure the agent with service SID type as `SERVICE_SID_TYPE_UNRESTRICTED` (requires administrator permission) - `--overwriteAutoLogon` - used with `--runAsAutoLogon` to overwrite the existing auto logon on the machine - `--noRestart` - used with `--runAsAutoLogon` to stop the host from restarting after agent configuration completes diff --git a/docs/pipelines/agents/includes/v3/unix-authentication-types.md b/docs/pipelines/agents/includes/v3/unix-authentication-types.md deleted file mode 100644 index 469d6c112f4..00000000000 --- a/docs/pipelines/agents/includes/v3/unix-authentication-types.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -ms.topic: include -ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: sdanie -author: steved0x -ms.date: 05/05/2023 ---- - -#### Azure Pipelines - -Choose **PAT**, and then paste the [PAT token you created](#permissions) into the command prompt window. - -> [!NOTE] -> When using PAT as the authentication method, the PAT token is used only for the initial configuration of the agent. Learn more at [Communication with Azure Pipelines or TFS](../../agents.md#communication). - diff --git a/docs/pipelines/agents/includes/v3/web-proxy-bypass.md b/docs/pipelines/agents/includes/v3/web-proxy-bypass.md index 10a50dcbeb1..d90aead9aff 100644 --- a/docs/pipelines/agents/includes/v3/web-proxy-bypass.md +++ b/docs/pipelines/agents/includes/v3/web-proxy-bypass.md @@ -4,7 +4,7 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: sdanie author: steved0x -ms.date: 02/12/2020 +ms.date: 04/02/2025 --- ### How do I configure the agent to bypass a web proxy and connect to Azure Pipelines? @@ -31,24 +31,42 @@ https://*.dev.azure.com https://login.microsoftonline.com https://management.core.windows.net https://vstsagentpackage.azureedge.net +https://download.agent.dev.azure.com https://vssps.dev.azure.com ``` To ensure your organization works with any existing firewall or IP restrictions, ensure that `dev.azure.com` and `*dev.azure.com` are open and update your allow-listed IPs to include the following IP addresses, based on your IP version. If you're currently allow-listing the `13.107.6.183` and `13.107.9.183` IP addresses, leave them in place, as you don't need to remove them. -**IPv4 ranges** +#### [IP V4 ranges](#tab/IP-V4) -* `13.107.6.0/24` -* `13.107.9.0/24` -* `13.107.42.0/24` -* `13.107.43.0/24` +```IP V4 ranges -**IPv6 ranges** +13.107.6.0/24 +13.107.9.0/24 +13.107.42.0/24 +13.107.43.0/24 +150.171.22.0/24 +150.171.23.0/24 +150.171.73.0/24 +150.171.74.0/24 +150.171.75.0/24 +150.171.76.0/24 +``` + +#### [IP V6 ranges](#tab/IP-V6) + +```IP V6 ranges -* `2620:1ec:4::/48` -* `2620:1ec:a92::/48` -* `2620:1ec:21::/48` -* `2620:1ec:22::/48` +2620:1ec:4::/48 +2620:1ec:a92::/48 +2620:1ec:21::/48 +2620:1ec:22::/48 +2620:1ec:50::/48 +2620:1ec:51::/48 +2603:1061:10::/48 +``` + +--- > [!NOTE] > This procedure enables the agent to bypass a web proxy. Your build pipeline and scripts must still handle bypassing your web proxy for each task and tool you run in your build. diff --git a/docs/pipelines/agents/linux-agent.md b/docs/pipelines/agents/linux-agent.md index 80744576700..9a1101b64a6 100644 --- a/docs/pipelines/agents/linux-agent.md +++ b/docs/pipelines/agents/linux-agent.md @@ -1,10 +1,10 @@ --- title: Deploy an Azure Pipelines agent on Linux -ms.custom: seodec18 description: Learn how you can easily deploy a self-hosted agent on Linux for Azure Pipelines. ms.topic: conceptual +ms.custom: linux-related-content ms.assetid: 834FFB19-DCC5-40EB-A3AD-18B7EDCA976E -ms.date: 05/05/2023 +ms.date: 05/06/2024 monikerRange: '<= azure-devops' --- @@ -14,18 +14,11 @@ monikerRange: '<= azure-devops' :::moniker range="<=azure-devops" -> [!IMPORTANT] -> This article provides guidance for using the [3.x agent software](v3-agent.md) with Azure DevOps Services. If you're using Azure DevOps Server or TFS, see [Self-hosted Linux agents (Agent version 2.x)](v2-linux-agent.md). +This article provides guidance for using the [3.x agent software](v3-agent.md) with Azure DevOps Services and current versions of Azure DevOps Server. For a list of Azure DevOps Server versions that support the 3.x agent, see [Does Azure DevOps Server support the 3.x agent](v3-agent.md#does-azure-devops-server-support-the-3x-agent). :::moniker-end -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - -To run your jobs, you'll need at least one agent. A Linux agent can build and deploy different kinds of apps, including Java and Android apps. See [Check prerequisites](#check-prerequisites) for a list of supported Linux distributions. +To run your jobs, you need at least one agent. A Linux agent can build and deploy different kinds of apps, including Java and Android apps. See [Check prerequisites](#check-prerequisites) for a list of supported Linux distributions. > [!NOTE] > This article describes how to configure a [self-hosted agent](agents.md#self-hosted-agents). If you're using Azure DevOps Services and a [Microsoft-hosted agent](hosted.md) meets your needs, you can skip setting up a self-hosted Linux agent. @@ -34,7 +27,7 @@ To run your jobs, you'll need at least one agent. A Linux agent can build and de ## Check prerequisites -::: moniker range="> tfs-2018" +::: moniker range="<=azure-devops" The agent is based on .NET 6. You can run this agent on several Linux distributions. @@ -42,7 +35,6 @@ We support the following subset of .NET 6 supported distributions: * Supported distributions * x64 - * CentOS 7, 8 * Debian 10+ * Fedora 36+ * openSUSE 15+ @@ -51,10 +43,13 @@ We support the following subset of .NET 6 supported distributions: * SUSE Enterprise Linux 12 SP2 or later * Ubuntu 22.04, 20.04, 18.04, 16.04 * Azure Linux 2.0 + * Oracle Linux 7 and higher * ARM64 * Debian 10+ * Ubuntu 22.04, 20.04, 18.04 -* **Git** - Regardless of your platform, you will need to install Git 2.9.0 or higher. + * Alpine x64 + * [Alpine Linux](https://alpinelinux.org/) 3.13 and higher ([requires agent 3.227 or higher](/azure/devops/release-notes/2023/sprint-228-update#azure-pipelines-agent-now-supports-alpine-linux)) +* **Git** - Regardless of your platform, you need to install Git 2.9.0 or higher. We strongly recommend installing the latest version of Git. * **.NET** - The agent software runs on .NET 6, but installs its own version of .NET so there is no .NET prerequisite. * **Subversion** - If you're building from a Subversion repo, you must install the Subversion client on the machine. @@ -86,7 +81,7 @@ After you get a feel for how agents work, or if you want to automate setting up ### Azure Pipelines -1. Log on to the machine using the account for which you've prepared permissions as explained above. +1. Log on to the machine using the account for which you've prepared permissions as explained in the previous section. 1. In your web browser, sign in to Azure Pipelines, and navigate to the **Agent pools** tab: @@ -100,7 +95,7 @@ After you get a feel for how agents work, or if you want to automate setting up 1. On the right pane, click the **Download** button. -1. Follow the instructions on the page.
      • +1. Follow the instructions on the page.
      1. Unpack the agent into the directory of your choice. `cd` to that directory and run `./config.sh`. @@ -117,7 +112,9 @@ Azure Pipelines: `https://dev.azure.com/{your-organization}` ### Authentication type -[!INCLUDE [include](includes/v3/unix-authentication-types.md)] +When you register an agent, choose from the following authentication types, and agent setup prompts you for the specific additional information required for each authentication type. For more information, see [Self-hosted agent authentication options](./agent-authentication-options.md). + +[!INCLUDE [agent-setup-authentication-type](./includes/agent-setup-authentication.md)] ## Run interactively @@ -136,7 +133,7 @@ To run the agent interactively: To restart the agent, press Ctrl+C and then run `run.sh` to restart it. To use your agent, run a [job](../process/phases.md) using the agent's pool. -If you didn't choose a different pool, your agent will be in the **Default** pool. +If you didn't choose a different pool, your agent is placed in the **Default** pool. ### Run once @@ -147,7 +144,7 @@ To run in this configuration: ./run.sh --once ``` -Agents in this mode will accept only one job and then spin down gracefully (useful for running in [Docker](docker.md) on a service like Azure Container Instances). +Agents in this mode accept only one job and then spin down gracefully (useful for running in [Docker](docker.md) on a service like Azure Container Instances). ## Run as a systemd service @@ -187,7 +184,7 @@ Command: sudo ./svc.sh install [username] ``` -This command creates a service file that points to `./runsvc.sh`. This script sets up the environment (more details below) and starts the agents host. If `username` parameter is not specified then the username is taken from the $SUDO_USER environment variable which is set by sudo command. This variable is always equal to the name of the user who invoked the `sudo` command. +This command creates a service file that points to `./runsvc.sh`. This script sets up the environment (more details below) and starts the agents host. If `username` parameter is not specified, the username is taken from the $SUDO_USER environment variable set by sudo command. This variable is always equal to the name of the user who invoked the `sudo` command. #### Start @@ -245,7 +242,7 @@ When you install the service, some service files are put in place. #### systemd service file -A systemd service file is created: +A `systemd` service file is created: `/etc/systemd/system/vsts.agent.{tfs-name}.{agent-name}.service` @@ -269,7 +266,7 @@ You can use the template described above as to facilitate generating other kinds ## Use a cgroup to avoid agent failure -It's important to avoid situations in which the agent fails or become unusable because otherwise the agent can't stream pipeline logs or report pipeline status back to the server. You can mitigate the risk of this kind of problem being caused by high memory pressure by using cgroups and a lower `oom_score_adj`. After you've done this, Linux reclaims system memory from pipeline job processes before reclaiming memory from the agent process. [Learn how to configure cgroups and OOM score](https://github.com/Microsoft/azure-pipelines-agent/blob/master/docs/start/resourceconfig.md). +It's important to avoid situations in which the agent fails or become unusable because otherwise the agent can't stream pipeline logs or report pipeline status back to the server. You can mitigate the risk of this kind of problem being caused by high memory pressure by using `cgroups` and a lower `oom_score_adj`. After you've done this, Linux reclaims system memory from pipeline job processes before reclaiming memory from the agent process. [Learn how to configure `cgroups` and OOM score](https://github.com/Microsoft/azure-pipelines-agent/blob/master/docs/start/resourceconfig.md). [!INCLUDE [include](includes/v3/replace-agent.md)] @@ -335,14 +332,14 @@ If you'll be using TFVC, you'll also need the [Oracle Java JDK 1.6](https://www. (The Oracle JRE and OpenJDK aren't sufficient for this purpose.) [TEE plugin](https://github.com/microsoft/team-explorer-everywhere) is used for TFVC functionality. -It has an EULA, which you'll need to accept during configuration if you plan to work with TFVC. +It has an EULA, which you need to accept during configuration if you plan to work with TFVC. Since the TEE plugin is no longer maintained and contains some out-of-date Java dependencies, starting from Agent 2.198.0 it's no longer included in the agent distribution. However, the TEE plugin will be downloaded during checkout task execution if you're checking out a TFVC repo. The TEE plugin will be removed after the job execution. > [!NOTE] > Note: You may notice your checkout task taking a long time to start working because of this download mechanism. -If the agent is running behind a proxy or a firewall, you'll need to ensure access to the following site: `https://vstsagenttools.blob.core.windows.net/`. The TEE plugin will be downloaded from this address. +If the agent is running behind a proxy or a firewall, you need to ensure access to the following site: `https://vstsagenttools.blob.core.windows.net/`. The TEE plugin will be downloaded from this address. If you're using a self-hosted agent and facing issues with TEE downloading, you may install TEE manually: 1. Set `DISABLE_TEE_PLUGIN_REMOVAL` environment or pipeline variable to `true`. This variable prevents the agent from removing the TEE plugin after TFVC repository checkout. diff --git a/docs/pipelines/agents/media/agent-pool-delete.png b/docs/pipelines/agents/media/agent-pool-delete.png new file mode 100644 index 00000000000..595ed678eee Binary files /dev/null and b/docs/pipelines/agents/media/agent-pool-delete.png differ diff --git a/docs/pipelines/agents/media/agent-registration/agent-pool-security.png b/docs/pipelines/agents/media/agent-registration/agent-pool-security.png new file mode 100644 index 00000000000..b5eb10f7043 Binary files /dev/null and b/docs/pipelines/agents/media/agent-registration/agent-pool-security.png differ diff --git a/docs/pipelines/agents/media/agent-registration/service-principal-client-secret.png b/docs/pipelines/agents/media/agent-registration/service-principal-client-secret.png new file mode 100644 index 00000000000..4063028afe4 Binary files /dev/null and b/docs/pipelines/agents/media/agent-registration/service-principal-client-secret.png differ diff --git a/docs/pipelines/agents/media/agent-registration/service-principal-ids.png b/docs/pipelines/agents/media/agent-registration/service-principal-ids.png new file mode 100644 index 00000000000..adba26538d7 Binary files /dev/null and b/docs/pipelines/agents/media/agent-registration/service-principal-ids.png differ diff --git a/docs/pipelines/agents/osx-agent.md b/docs/pipelines/agents/osx-agent.md index 47231795de2..8f8c0baa273 100644 --- a/docs/pipelines/agents/osx-agent.md +++ b/docs/pipelines/agents/osx-agent.md @@ -1,10 +1,9 @@ --- title: Deploy a build and release agent on macOS -ms.custom: seodec18 description: Learn how to deploy a macOS agent to build and deploy your iOS application for Azure Pipelines and Team Foundation Server (TFS) ms.topic: conceptual ms.assetid: 3D487E4E-D940-4DA9-BDE1-1F60E74DD6F1 -ms.date: 05/05/2023 +ms.date: 04/01/2025 monikerRange: '<= azure-devops' --- @@ -14,12 +13,11 @@ monikerRange: '<= azure-devops' :::moniker range="<=azure-devops" -> [!IMPORTANT] -> This article provides guidance for using the [3.x agent software](v3-agent.md) with Azure DevOps Services. If you're using Azure DevOps Server or TFS, see [Self-hosted macOS agents (Agent version 2.x)](v2-osx-agent.md). +This article provides guidance for using the [3.x agent software](v3-agent.md) with Azure DevOps Services and current versions of Azure DevOps Server. For a list of Azure DevOps Server versions that support the 3.x agent, see [Does Azure DevOps Server support the 3.x agent](v3-agent.md#does-azure-devops-server-support-the-3x-agent). :::moniker-end -To build and deploy Xcode apps or Xamarin.iOS projects, you'll need at least one macOS agent. This agent can also build and deploy Java and Android apps. +To build and deploy Xcode apps, you need at least one macOS agent. This agent can also build and deploy Java and Android apps. > [!NOTE] > This article describes how to configure a [self-hosted agent](agents.md#self-hosted-agents). If you're using Azure DevOps Services and a [Microsoft-hosted agent](hosted.md) meets your needs, you can skip setting up a self-hosted macOS agent. @@ -34,12 +32,16 @@ To build and deploy Xcode apps or Xamarin.iOS projects, you'll need at least one * macOS 11.0 "Big Sur" * macOS 12.0 "Monterey" * macOS 13.0 "Ventura" + * macOS 14.0 "Sonoma" + * macOS 15.0 "Sequoia" * ARM64 * macOS 11.0 "Big Sur" * macOS 12.0 "Monterey" * macOS 13.0 "Ventura" - * Note: Not all Azure Pipeline tasks have been updated to support ARM64 yet -- **Git** - Git 2.9.0 or higher (latest version strongly recommended - you can easily install with [Homebrew](https://brew.sh/)) + * macOS 14.0 "Sonoma" + * macOS 15.0 "Sequoia" + +- **Git** - Git 2.9.0 or higher (latest version recommended - you can easily install with [Homebrew](https://brew.sh/)) * **.NET** - The agent software runs on .NET 6, but installs its own version of .NET so there is no .NET prerequisite. * **TFVC** - If you're building from a TFVC repo, see [TFVC prerequisites](#tfvc-prerequisites). @@ -59,7 +61,7 @@ After you get a feel for how agents work, or if you want to automate setting up ### Azure Pipelines -1. Log on to the machine using the account for which you've prepared permissions as explained above. +1. Log on to the machine using the account for which you've prepared permissions as explained in the previous section. 1. In your web browser, sign in to Azure Pipelines, and navigate to the **Agent pools** tab: @@ -95,7 +97,9 @@ Azure DevOps Server: `https://{your_server}/tfs` ### Authentication type -[!INCLUDE [include](includes/v3/unix-authentication-types.md)] +When you register an agent, choose from the following authentication types, and agent setup prompts you for the specific additional information required for each authentication type. For more information, see [Self-hosted agent authentication options](./agent-authentication-options.md). + +[!INCLUDE [agent-setup-authentication-type](./includes/agent-setup-authentication.md)] ## Run interactively @@ -114,7 +118,7 @@ To run the agent interactively: To restart the agent, press Ctrl+C and then run `run.sh` to restart it. To use your agent, run a [job](../process/phases.md) using the agent's pool. -If you didn't choose a different pool, your agent will be in the **Default** pool. +If you didn't choose a different pool, your agent is placed in the **Default** pool. ### Run once @@ -124,24 +128,24 @@ For agents configured to run interactively, you can choose to have the agent acc ./run.sh --once ``` -Agents in this mode will accept only one job and then spin down gracefully (useful for running on a service like Azure Container Instances). +Agents in this mode accept only one job and then spin down gracefully (useful for running on a service like Azure Container Instances). ## Run as a launchd service -We provide the `./svc.sh` script for you to run and manage your agent as a launchd LaunchAgent service. This script will be generated after you configure the agent. The service has access to the UI to run your UI tests. +We provide the `./svc.sh` script for you to run and manage your agent as a `launchd` LaunchAgent service. This script is generated after you configure the agent. The service has access to the UI to run your UI tests. > [!NOTE] > If you prefer other approaches, you can use whatever kind of service mechanism you prefer. See [Service files](#service-files). ### Tokens -In the section below, these tokens are replaced: +In the following section, these tokens are replaced: * `{agent-name}` * `{tfs-name}` -For example, you have configured an agent (see above) with the name `our-osx-agent`. In the following examples, `{tfs-name}` will be either: +For example, you have configured an agent (as shown in the previous example) with the name `our-osx-agent`. In the following examples, `{tfs-name}` is either: * Azure Pipelines: the name of your organization. For example if you connect to `https://dev.azure.com/fabrikam`, then the service name would be `vsts.agent.fabrikam.our-osx-agent` @@ -166,7 +170,7 @@ Command: ./svc.sh install ``` -This command creates a launchd plist that points to `./runsvc.sh`. This script sets up the environment (more details below) and starts the agent's host. +This command creates a `launchd` plist that points to `./runsvc.sh`. This script sets up the environment (more details in the following section) and starts the agent's host. #### Start @@ -245,7 +249,7 @@ Command: Normally, the agent service runs only after the user logs in. If you want the agent service to automatically start when the machine restarts, you can configure the machine to automatically login and lock on startup. See [Set your Mac to automatically login during startup - Apple Support](https://support.apple.com/HT201476). > [!NOTE] -> For more information, see the [Terminally Geeky: use automatic login more securely](https://www.engadget.com/2011/03/07/terminally-geeky-use-automatic-login-more-securely/) blog. The .plist file mentioned in that blog may no longer be available at the source, but a copy can be found here: [Lifehacker - Make OS X load your desktop before you log in](https://lifehacker.com/5779922/make-os-x-load-your-desktop-before-you-log-in). +> For more information, see the [Terminally Geeky: use automatic login more securely](https://www.engadget.com/2011/03/07/terminally-geeky-use-automatic-login-more-securely/) blog. The .plist file mentioned in that blog may no longer be available at the source, but a copy can be found here: [Lifehacker - Make OS X load your desktop before you log in](https://lifehacker.com/make-os-x-load-your-desktop-before-you-log-in-5779922).

      Update environment variables

      @@ -289,7 +293,7 @@ For example: ~/Library/LaunchAgents/vsts.agent.fabrikam.our-osx-agent.plist ``` -`sudo ./svc.sh install` generates this file from this template: `./bin/vsts.agent.plist.template` +`./svc.sh install` generates this file from this template: `./bin/vsts.agent.plist.template` #### .service file @@ -297,7 +301,7 @@ For example: ### Alternative service mechanisms -We provide the `./svc.sh` script as a convenient way for you to run and manage your agent as a launchd LaunchAgent service. But you can use whatever kind of service mechanism you prefer. +We provide the `./svc.sh` script as a convenient way for you to run and manage your agent as a `launchd` LaunchAgent service. But you can use whatever kind of service mechanism you prefer. You can use the template described above as to facilitate generating other kinds of service files. For example, you modify the template to generate a service that runs as a launch daemon if you don't need UI tests and don't want to configure automatic log on and lock. See [Apple Developer Library: Creating Launch Daemons and Agents](https://developer.apple.com/library/content/documentation/macOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html). @@ -363,14 +367,14 @@ If you'll be using TFVC, you'll also need the [Oracle Java JDK 1.6](https://www. (The Oracle JRE and OpenJDK aren't sufficient for this purpose.) [TEE plugin](https://github.com/microsoft/team-explorer-everywhere) is used for TFVC functionality. -It has an EULA, which you'll need to accept during configuration if you plan to work with TFVC. +It has an EULA, which you must to accept during configuration if you plan to work with TFVC. -Since the TEE plugin is no longer maintained and contains some out-of-date Java dependencies, starting from Agent 2.198.0 it's no longer included in the agent distribution. However, the TEE plugin will be downloaded during checkout task execution if you're checking out a TFVC repo. The TEE plugin will be removed after the job execution. +Since the TEE plugin is no longer maintained and contains some out-of-date Java dependencies, starting from Agent 2.198.0 it's no longer included in the agent distribution. However, the TEE plugin is downloaded during checkout task execution if you're checking out a TFVC repo. The TEE plugin is removed after the job execution. > [!NOTE] > Note: You may notice your checkout task taking a long time to start working because of this download mechanism. -If the agent is running behind a proxy or a firewall, you'll need to ensure access to the following site: `https://vstsagenttools.blob.core.windows.net/`. The TEE plugin will be downloaded from this address. +If the agent is running behind a proxy or a firewall, you must accept to ensure access to the following site: `https://vstsagenttools.blob.core.windows.net/`. The TEE plugin is downloaded from this address. If you're using a self-hosted agent and facing issues with TEE downloading, you may install TEE manually: 1. Set `DISABLE_TEE_PLUGIN_REMOVAL` environment or pipeline variable to `true`. This variable prevents the agent from removing the TEE plugin after TFVC repository checkout. diff --git a/docs/pipelines/agents/personal-access-token-agent-registration.md b/docs/pipelines/agents/personal-access-token-agent-registration.md new file mode 100644 index 00000000000..bb46ebb8e9a --- /dev/null +++ b/docs/pipelines/agents/personal-access-token-agent-registration.md @@ -0,0 +1,77 @@ +--- +title: Register an agent using a personal access token (PAT) +description: Learn how to register a self-hosted agent using a personal access token (PAT) +ms.topic: conceptual +ms.date: 09/22/2023 +monikerRange: '<= azure-devops' +--- + +# Register an agent using a personal access token (PAT) + +Specify **PAT** for authentication type during agent configuration to use a personal access token to authenticate during agent registration, then specify a personal access token (PAT) with **Agent Pools (read, manage)** scope (or **Deployment group (read, manage)** scope for a [deployment group](../release/deployment-groups/index.md) agent) can be used for agent registration. + +A single PAT can be used for registering multiple agents, the PAT is used only at the time of registering the agent, and not for subsequent [communication](./agents.md#communication). + +To use a PAT with Azure DevOps Server, your server must be configured with HTTPS. See [Web site settings and security](/azure/devops/server/admin/websitesettings). + +## Create a personal access token for agent registration + +::: moniker range=" [!NOTE] + > If you are configuring a deployment group agent, or if you see an error when registering a VM environment resource, you must set the PAT scope to **All accessible organizations**. + > :::image type="content" source="media/prepare-permissions-pat-scope.png" alt-text="Screenshot of setting PAT scope to all accessible organizations."::: + +::: moniker-end + +::: moniker range="azure-devops" + +2. From your home page, open your user settings, and then select **Personal access tokens**. + + ![Screenshot of security details.](../../repos/git/media/select-personal-access-tokens.png) + +3. [Create a personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). + + ![Screenshot of creating a personal access token.](../../repos/git/media/select-new-token.png) + +::: moniker-end + +::: moniker range="<= azure-devops" + +4. For the scope select **Agent Pools (read, manage)** and make sure all the other boxes are cleared. + If it's a [deployment group](../release/deployment-groups/index.md) agent, for the scope select **Deployment group (read, manage)** and make sure all the other boxes are cleared. + + Select **Show all scopes** at the bottom of the **Create a new personal access token window** window to see the complete list of scopes. + +5. Copy the token. You'll use this token when you configure the agent. + +::: moniker-end + +> [!NOTE] +> When using PAT as the authentication method, the PAT token is used only for the initial configuration of the agent. Learn more at [Communication with Azure Pipelines or TFS](./agents.md#communication). + +## Next steps + +* [Self-hosted Windows agents](./windows-agent.md) +* [Self-hosted Linux agents](./linux-agent.md) +* [Self-hosted macOS agents](./osx-agent.md) diff --git a/docs/pipelines/agents/pools-queues.md b/docs/pipelines/agents/pools-queues.md index e0a47a5e5f3..0111d2ddf62 100644 --- a/docs/pipelines/agents/pools-queues.md +++ b/docs/pipelines/agents/pools-queues.md @@ -1,10 +1,10 @@ --- title: Create and manage agent pools ms.topic: conceptual -ms.custom: seodec18 +ms.custom: devx-track-azurecli description: Learn about organizing agents into pools for builds and releases in Azure Pipelines and Team Foundation Server ms.assetid: BD5478A8-48CF-4859-A0CB-6E1948CE2C89 -ms.date: 06/20/2023 +ms.date: 08/30/2024 monikerRange: '<= azure-devops' --- @@ -12,31 +12,12 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - -::: moniker range="tfs-2018" - -An agent pool is a collection of agents. Instead of managing each [agent](agents.md) individually, you organize agents into **agent pools**. In TFS, pools are scoped to the entire server; so you can share an agent pool across project collections and projects. - -An **agent queue** provides access to an **agent pool** within a project. When you create a build or release pipeline, you specify which queue it uses. Queues are scoped to your project in TFS 2017 and newer, so you can only use them across build and release pipelines within a project. - -To share an agent pool with multiple projects, in each of those projects, you create an agent queue pointing to the same agent pool. While multiple queues across projects can use the same agent pool, multiple queues within a project cannot use the same agent pool. Also, each agent queue can use only one agent pool. - -::: moniker-end - -::: moniker range="tfs-2018" - -![TFS 2017 and TFS 2018 build system architecture](media/build-system-architecture.png) - -::: moniker-end - ::: moniker range="= azure-devops" -An agent pool is a collection of agents. Instead of managing each [agent](agents.md) individually, you organize agents into agent pools. When you configure an agent, it is registered with a single pool, and when you create a pipeline, you specify the pool in which the pipeline runs. When you run the pipeline, it runs on an agent from that pool that meets the [demands](../process/demands.md) of the pipeline. +An agent pool is a collection of agents. Instead of managing each [agent](agents.md) individually, you organize agents into agent pools. When you configure an agent, it is registered with a single pool, and when you create a pipeline, you specify the pool in which the pipeline runs. When you run the pipeline, it runs on an agent from that pool that meets the [demands](/azure/devops/pipelines/yaml-schema/pool-demands) of the pipeline. + +> [!NOTE] +> Managed DevOps Pools agent pools are managed in the Azure Portal. If you're using Managed DevOps Pools, see [Create your first Managed DevOps Pool](../../managed-devops-pools/quickstart-azure-portal.md). ::: moniker-end @@ -46,35 +27,31 @@ In Azure Pipelines, pools are scoped to the entire organization; so you can shar ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!NOTE] > Agent pool jobs run a job on a single agent. If you need to run a job on all agents, such as a deployment group for classic release pipelines, see [Provision deployment groups](../release/deployment-groups/index.md). ::: moniker-end -::: moniker range="tfs-2018" -You create and manage agent pools from the agent pools tab in admin settings. -::: moniker-end +::: moniker range="<=azure-devops" -::: moniker range=">= azure-devops-2019" If you are an organization administrator, you create and manage agent pools from the agent pools tab in admin settings. + ::: moniker-end [!INCLUDE [agent-pools-tab](includes/agent-pools-tab.md)] -::: moniker range="tfs-2018" -You create and manage agent queues from the agent queues tab in project settings. -::: moniker-end +::: moniker range="<=azure-devops" -::: moniker range=">= azure-devops-2019" If you are a project team member, you create and manage agent pools from the agent pools tab in project settings. + ::: moniker-end [!INCLUDE [agent-queues-tab](includes/agent-queues-tab.md)] @@ -92,7 +69,6 @@ The following agent pools are provided by default: > [!NOTE] > The Azure Pipelines hosted pool replaces the previous hosted pools that had names that mapped to the corresponding images. Any jobs you had in the previous hosted pools are automatically redirected to the correct image in the new Azure Pipelines hosted pool. In some circumstances, you may still see the old pool names, but behind the scenes the hosted jobs are run using the Azure Pipelines pool. For more information, see the [Single hosted pool](/azure/devops/release-notes/2019/sprint-154-update#single-hosted-pool) release notes from the [July 1 2019 - Sprint 154 release notes](/azure/devops/release-notes/2019/sprint-154-update). - By default, all contributors in a project are members of the **User** role on hosted pools. This allows every contributor in a project to author and run pipelines using Microsoft-hosted agents. ::: moniker-end @@ -101,13 +77,7 @@ By default, all contributors in a project are members of the **User** role on ho # [YAML](#tab/yaml) -:::moniker range="Security of agent pools Understanding how security works for agent pools helps you control sharing and use of agents. @@ -423,12 +376,6 @@ Pipeline permissions for the *Azure Pipelines* agent pool cannot be configured, ::: moniker-end -::: moniker range="<= azure-devops-2019" - -The **All agent pools** node in the Agent pools tab is used to control the security of _all_ project agent pools in a project. Role memberships for individual project agent pools are automatically inherited from those of the 'All agent pools' node. By default, the following groups are added to the Administrator role of 'All agent pools': Build Administrators, Release Administrators, Project Administrators. - -::: moniker-end - ::: moniker range="azure-devops" The **Security** action in the Agent pools tab is used to control the security of _all_ project agent pools in a project. Role memberships for individual project agent pools are automatically inherited from what you define here. By default, the following groups are added to the Administrator role of 'All agent pools': Build Administrators, Release Administrators, Project Administrators. @@ -443,7 +390,7 @@ If no window is scheduled, then the agents in that pool will not run the mainten ### What is a maintenance job? -You can configure agent pools to periodically clean stale working directories and repositories. This should reduce the potential for the agents to run out of disk space. Maintenance jobs are configured at the project collection or organization level in agent pool settings. +You can configure agent pools to periodically clean stale working directories and repositories. This should reduce the potential for the agents to run out of disk space. Maintenance jobs are configured at the organization level in agent pool settings. To configure maintenance job settings: @@ -454,23 +401,17 @@ Choose the desired pool and choose **Settings** to configure maintenance job set > [!IMPORTANT] > You must have the [Manage build queues](../../organizations/security/permissions-access.md) permission to configure maintenance job settings. If you don't see the **Settings** tab or the **Maintenance History** tab, you don't have that permission, which is granted by default to the **Administrator** role. For more information, see [Security of agent pools](#security). -:::moniker range="> tfs-2018" +:::moniker range="<=azure-devops" :::image type="content" source="media/maintenance-job-settings.png" alt-text="Maintenance job settings"::: :::moniker-end -:::moniker range="<= tfs-2018" - -:::image type="content" source="media/maintenance-job-settings-tfs.png" alt-text="Maintenance job settings for TFS"::: - -:::moniker-end - Configure your desired settings and choose **Save**. Select **Maintenance History** to see the maintenance job history for the current agent pool. You can download and review logs to see the cleaning steps and actions taken. -:::moniker range="> tfs-2018" +:::moniker range="<=azure-devops" :::image type="content" source="media/maintenance-job-history.png" alt-text="Maintenance job history"::: diff --git a/docs/pipelines/agents/proxy.md b/docs/pipelines/agents/proxy.md index 0cca8d04518..dad8baf833c 100644 --- a/docs/pipelines/agents/proxy.md +++ b/docs/pipelines/agents/proxy.md @@ -1,6 +1,5 @@ --- title: Run the agent behind a web proxy -ms.custom: seodec18 description: Learn how you can run a v2 private build and release agent behind a web proxy for Azure Pipelines and Team Foundation Server (TFS) ms.topic: conceptual ms.assetid: 6AC4BA22-9F6F-44B5-BB15-445A7CFD2AD4 @@ -12,18 +11,14 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end When your self-hosted agent requires a web proxy, you can inform the agent about the proxy during configuration. This allows your agent to connect to Azure Pipelines or TFS through the proxy. This in turn allows the agent to get sources and download artifacts. Finally, it passes the proxy details through to tasks which also need proxy settings in order to reach the web. -::: moniker range=">= tfs-2018" +::: moniker range="<=azure-devops" ## Azure Pipelines, TFS 2018 RTM and newer diff --git a/docs/pipelines/agents/scale-set-agents.md b/docs/pipelines/agents/scale-set-agents.md index bb1346de0c9..c9729a255e0 100644 --- a/docs/pipelines/agents/scale-set-agents.md +++ b/docs/pipelines/agents/scale-set-agents.md @@ -2,11 +2,11 @@ title: Azure Virtual Machine Scale Set agents description: Use Azure Virtual Machine Scale Sets to create agents ms.topic: reference -ms.custom: devx-track-azurecli +ms.custom: devx-track-azurecli, arm2024 ms.manager: mijacobs ms.author: sdanie author: steved0x -ms.date: 01/10/2023 +ms.date: 04/02/2025 monikerRange: azure-devops --- @@ -14,6 +14,8 @@ monikerRange: azure-devops [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] +[!INCLUDE [mdp-recommended](../../managed-devops-pools/includes/mdp-recommended.md)] + Azure Virtual Machine Scale Set agents, hereafter referred to as scale set agents, are a form of self-hosted agents that can be autoscaled to meet your demands. This elasticity reduces your need to run dedicated agents all the time. Unlike Microsoft-hosted agents, you have flexibility over the size and the image of machines on which agents run. If you like Microsoft-hosted agents but are limited by what they offer, you should consider scale set agents. Here are some examples: @@ -24,7 +26,7 @@ If you like Microsoft-hosted agents but are limited by what they offer, you shou - You need to open corporate firewall to specific IP addresses so that Microsoft-hosted agents can communicate with your servers. - You need to restrict network connectivity of agent machines and allow them to reach only approved sites. - You can't get enough agents from Microsoft to meet your needs. -- Your jobs exceed the Microsoft-hosted agent timeout. +- Your jobs exceed the Microsoft-hosted agent time-out. - You can't partition Microsoft-hosted parallel jobs to individual projects or teams in your organization. - You want to run several consecutive jobs on an agent to take advantage of incremental source and machine-level package caches. - You want to run configuration or cache warmup before an agent begins accepting jobs. @@ -38,9 +40,9 @@ If you like self-hosted agents but wish that you could simplify managing them, y > [!NOTE] > - You cannot run Mac agents using scale sets. You can only run Windows or Linux agents this way. > -> - Using VMSS agent pools for Azure DevOps Services is only supported for Azure Public (global service) cloud. Currently, VMSS agent pools does not support any other [national cloud offerings](/azure/active-directory/develop/authentication-national-cloud). +> - Using Virtual Machine Scale Sets agent pools for Azure DevOps Services is only supported for Azure Public (global service) cloud. Currently, Virtual Machine Scale Sets agent pools does not support any other [national cloud offerings](/azure/active-directory/develop/authentication-national-cloud). > -> - You should not associate a VMSS to multiple pools. +> - You should not associate a virtual machine scale sets to multiple pools. ## Create the scale set @@ -76,14 +78,14 @@ In the following example, a new resource group and Virtual Machine Scale Set are --name vmssagents ``` -4. Create a Virtual Machine Scale Set in your resource group. In this example, the UbuntuLTS VM image is specified. +4. Create a Virtual Machine Scale Set in your resource group. In this example, the Ubuntu2204 VM image is specified. ```azurecli az vmss create \ --name vmssagentspool \ --resource-group vmssagents \ - --image UbuntuLTS \ - --vm-sku Standard_D2_v3 \ + --image Ubuntu2204 \ + --vm-sku Standard_D2_v4 \ --storage-sku StandardSSD_LRS \ --authentication-type SSH \ --generate-ssh-keys \ @@ -92,7 +94,8 @@ In the following example, a new resource group and Virtual Machine Scale Set are --upgrade-policy-mode manual \ --single-placement-group false \ --platform-fault-domain-count 1 \ - --load-balancer "" + --load-balancer "" \ + --orchestration-mode Uniform ``` > [!NOTE] @@ -116,7 +119,7 @@ In the following example, a new resource group and Virtual Machine Scale Set are > [!IMPORTANT] > Ephemeral OS disks are not supported on all VM sizes. For list of supported VM sizes, see [Ephemeral OS disks for Azure VMs](/azure/virtual-machines/ephemeral-os-disks). - Select any Linux or Windows image - either from Azure Marketplace or your own custom image - to create the scale set. Don't pre-install Azure Pipelines agent in the image. Azure Pipelines automatically installs the agent as it provisions new virtual machines. In the above example, we used a plain `UbuntuLTS` image. For instructions on creating and using a custom image, see [FAQ](#faq). + Select any Linux or Windows image - either from Azure Marketplace or your own custom image - to create the scale set. Don't pre-install Azure Pipelines agent in the image. Azure Pipelines automatically installs the agent as it provisions new virtual machines. In the above example, we used a plain `UbuntuLTS` image. For instructions on creating and using a custom image, see [FAQ](#faqs). Select any VM SKU and storage SKU. @@ -146,6 +149,10 @@ In the following example, a new resource group and Virtual Machine Scale Set are > [!IMPORTANT] > Azure Pipelines does not support [instance protection](/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-instance-protection). Make sure you have the *scale-in* and *scale set actions* instance protections disabled. +### Orchestration mode + +Azure virtual machine scale sets can be configured with Uniform [orchestration mode](/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-orchestration-modes). Azure Pipelines support for the Uniform orchestration mode is generally available, to all customers. + ## Create the scale set agent pool 1. Navigate to your Azure DevOps **Project settings**, select **Agent pools** under **Pipelines**, and select **Add pool** to create a new agent pool. @@ -158,7 +165,7 @@ In the following example, a new resource group and Virtual Machine Scale Set are 2. Select **Azure Virtual Machine Scale Set** for the pool type. Select the **Azure subscription** that contains the scale set, choose **Authorize**, and choose the desired Virtual Machine Scale Set from that subscription. If you have an existing [service connection](../library/service-endpoints.md), you can choose that from the list instead of the subscription. > [!IMPORTANT] - > - To configure a scale set agent pool, you must have either [Owner](/azure/role-based-access-control/built-in-roles#owner) or [User Access Administrator](/azure/active-directory/users-groups-roles/directory-assign-admin-roles#user-administrator-permissions) permissions on the selected subscription. If you have one of these permissions but get an error when you choose **Authorize**, see [troubleshooting](../release/azure-rm-endpoint.md#insufficient-privileges-to-complete-the-operation). + > - To configure a scale set agent pool, you must have either [Owner](/azure/role-based-access-control/built-in-roles#owner) or [User Access Administrator](/azure/active-directory/users-groups-roles/directory-assign-admin-roles#user-administrator-permissions) permissions on the selected subscription. If you have one of these permissions but get an error when you choose **Authorize**, see [troubleshooting](../release/azure-rm-endpoint.md). > > - The only service connection currently supported is an Azure Resource Manager (ARM) service connection based on a service principal key. ARM service connections based on a certificate credential or a Managed Identity will fail. When you attempt to list the existing scale sets in your subscription, you'll see an error like this: > @@ -187,7 +194,7 @@ Using a scale set agent pool is similar to any other agent pool. You can use it > [!IMPORTANT] > Caution must be exercised when making changes directly to the scale set in the Azure portal. -> - You may not change many of the the scale set configuration settings in the Azure portal. Azure Pipelines updates the configuration of the scale set. Any manual changes you make to the scale set may interfere with the operation of Azure Pipelines. +> - You may not change many of the scale set configuration settings in the Azure portal. Azure Pipelines updates the configuration of the scale set. Any manual changes you make to the scale set may interfere with the operation of Azure Pipelines. > - You may not rename or delete a scale set without first deleting the scale set pool in Azure Pipelines. ## How Azure Pipelines manages the scale set @@ -294,8 +301,8 @@ Here's the flow of operations for an Azure Pipelines Virtual Machine Scale Set A 1. If the Custom Script Extension is installed, it's executed before the Azure Pipelines Agent extension. If the Custom Script Extension returns a non-zero exit code, the VM creation process is aborted and will be deleted. 1. The Azure Pipelines Agent extension is executed. This extension downloads the latest version of the Azure Pipelines Agent along with the latest version of configuration script. The configuration scripts can be found at URLs with the following formats: - - Linux: `https://vstsagenttools.blob.core.windows.net/tools/ElasticPools/Linux//enableagent.sh`, for example, [version 14](https://vstsagenttools.blob.core.windows.net/tools/ElasticPools/Linux/14/enableagent.sh) - - Windows: `https://vstsagenttools.blob.core.windows.net/tools/ElasticPools/Windows//enableagent.ps1`, for example, [version 16](https://vstsagenttools.blob.core.windows.net/tools/ElasticPools/Windows/16/enableagent.ps1) + - Linux: `https://vstsagenttools.blob.core.windows.net/tools/ElasticPools/Linux//enableagent.sh`, for example, [version 15](https://vstsagenttools.blob.core.windows.net/tools/ElasticPools/Linux/15/enableagent.sh) + - Windows: `https://vstsagenttools.blob.core.windows.net/tools/ElasticPools/Windows//enableagent.ps1`, for example, [version 17](https://vstsagenttools.blob.core.windows.net/tools/ElasticPools/Windows/17/enableagent.ps1) 1. The configuration script creates a local user named `AzDevOps` if the operating system is Windows Server or Linux. For Windows 10 Client OS, the agent runs as LocalSystem. The script then unzips, installs, and configures the Azure Pipelines Agent. As part of configuration, the agent registers with the Azure DevOps agent pool and appears in the agent pool list in the Offline state. @@ -449,50 +456,38 @@ To delete the saved agent when you're done with your investigation, navigate to :::image type="content" source="media/scale-set-agents/saved-agents-card-delete.png" alt-text="Saved agents card delete button."::: -## FAQ - -* [Where can I find the images used for Microsoft-hosted agents?](#where-can-i-find-the-images-used-for-microsoft-hosted-agents) -* [How do I configure scale set agents to run UI tests?](#how-do-i-configure-scale-set-agents-to-run-ui-tests) -* [How can I delete agents?](#how-can-i-delete-agents) -* [Can I configure the scale set agent pool to have zero agents on standby?](#can-i-configure-the-scale-set-agent-pool-to-have-zero-agents-on-standby) -* [How much do scale set agents cost?](#how-much-do-scale-set-agents-cost) -* [What are some common issues and their solutions?](#what-are-some-common-issues-and-their-solutions) - * [You observe more idle agents than desired at various times](#you-observe-more-idle-agents-than-desired-at-various-times) - * [VMSS scale up isn't happening in the expected five-minute interval](#vmss-scale-up-isnt-happening-in-the-expected-five-minute-interval) - * [Azure DevOps Linux VM Scale Set frequently fails to start the pipeline](#azure-devops-linux-vm-scale-set-frequently-fails-to-start-the-pipeline) - * [You check the option to automatically tear down virtual machines after every use for the agent pool, but you see that the VMs aren't re-imaging as they should and just pick up new jobs as they're queued](#you-check-the-option-to-automatically-tear-down-virtual-machines-after-every-use-for-the-agent-pool-but-you-see-that-the-vms-arent-re-imaging-as-they-should-and-just-pick-up-new-jobs-as-theyre-queued) - * [VMSS shows the agent as offline if the VM restarts](#vmss-shows-the-agent-as-offline-if-the-vm-restarts) - * [You can see multiple tags like _AzureDevOpsElasticPoolTimeStamp for VMSS in cost management](#you-can-see-multiple-tags-like-_azuredevopselasticpooltimestamp-for-vmss-in-cost-management) - * [You can't create a new scale set agent pool and get an error message that a pool with the same name already exists](#you-cant-create-a-new-scale-set-agent-pool-and-get-an-error-message-that-a-pool-with-the-same-name-already-exists) - * [VMSS maintenance job isn't running on agents or getting logs](#vmss-maintenance-job-isnt-running-on-agents-or-getting-logs) - * [If you specify `AzDevOps` as the primary administrator in your script for VMSS, you may observe issues with the agent configurations on scale set instances](#if-you-specify-azdevops-as-the-primary-administrator-in-your-script-for-vmss-you-may-observe-issues-with-the-agent-configurations-on-scale-set-instances) - * [Agent extension installation fails on scale set instances due to network security and firewall configurations](#agent-extension-installation-fails-on-scale-set-instances-due-to-network-security-and-firewall-configurations) - * [I want to increase my pool size. What should I take into consideration?](#i-want-to-increase-my-pool-size-what-should-i-take-into-consideration) - -### Where can I find the images used for Microsoft-hosted agents? - -Licensing considerations limit us from distributing Microsoft-hosted images. We're unable to provide these images for you to use in your scale set agents. But, the [scripts](https://github.com/actions/runner-images/tree/main/images) that we use to generate these images are open source. You're free to use these scripts and create your own custom images. - -### How do I configure scale set agents to run UI tests? - -Create a Scale Set with a Windows Server OS and when creating the Agent Pool select the "Configure VMs to run interactive tests" option. -### How can I delete agents? -` -Navigate to your Azure DevOps **Project settings**, select **Agent pools** under **Pipelines**, and select your agent pool. Select the tab labeled **Agents**. -Click the 'Enabled' toggle button to disable the agent. The disabled agent will complete the pipeline it's currently running and won't pick up additional work. Within a few minutes after completing its current pipeline job, the agent will be deleted. - -### Can I configure the scale set agent pool to have zero agents on standby? - -Yes, if you set **Number of agents to keep on standby** to zero, for example to conserve cost for a low volume of jobs, Azure Pipelines starts a VM only when it has a job. - -### How much do scale set agents cost? - -Pricing for scale set agents is similar to other self-hosted agents. You provide the infrastructure on which to run the agent software and the jobs, and you pay for the desired number of jobs that can run concurrently by purchasing parallel jobs. - -For scale set agents, the infrastructure to run the agent software and jobs is Azure Virtual Machine Scale Sets, and the pricing is described in [Virtual Machine Scale Sets pricing](https://azure.microsoft.com/pricing/details/virtual-machine-scale-sets/linux/). - -For information on purchasing parallel jobs, see [Configure and pay for parallel jobs](../licensing/concurrent-jobs.md). +## FAQs + +- [Azure Virtual Machine Scale Set agents](#azure-virtual-machine-scale-set-agents) + - [Create the scale set](#create-the-scale-set) + - [Orchestration mode](#orchestration-mode) + - [Create the scale set agent pool](#create-the-scale-set-agent-pool) + - [Use scale set agent pool](#use-scale-set-agent-pool) + - [How Azure Pipelines manages the scale set](#how-azure-pipelines-manages-the-scale-set) + - [Customizing Pipeline Agent Configuration](#customizing-pipeline-agent-configuration) + - [Customizing Virtual Machine Startup via the Custom Script Extension](#customizing-virtual-machine-startup-via-the-custom-script-extension) + - [Lifecycle of a Scale Set Agent](#lifecycle-of-a-scale-set-agent) + - [Create a scale set with custom image, software, or disk size](#create-a-scale-set-with-custom-image-software-or-disk-size) + - [Update an existing scale set with a new custom image](#update-an-existing-scale-set-with-a-new-custom-image) + - [Supported Operating Systems](#supported-operating-systems) + - [Known issues](#known-issues) + - [Troubleshooting issues](#troubleshooting-issues) + - [Unhealthy Agents](#unhealthy-agents) + - [FAQs](#faqs) + - [What are some common issues and their solutions?](#what-are-some-common-issues-and-their-solutions) + - [You observe more idle agents than desired at various times](#you-observe-more-idle-agents-than-desired-at-various-times) + - [Virtual Machine Scale Sets scale up isn't happening in the expected five-minute interval](#virtual-machine-scale-sets-scale-up-isnt-happening-in-the-expected-five-minute-interval) + - [Azure DevOps Linux VM Scale Set frequently fails to start the pipeline](#azure-devops-linux-vm-scale-set-frequently-fails-to-start-the-pipeline) + - [You check the option to automatically tear down virtual machines after every use for the agent pool, but you see that the VMs aren't re-imaging as they should and just pick up new jobs as they're queued](#you-check-the-option-to-automatically-tear-down-virtual-machines-after-every-use-for-the-agent-pool-but-you-see-that-the-vms-arent-re-imaging-as-they-should-and-just-pick-up-new-jobs-as-theyre-queued) + - [Virtual Machine Scale Sets shows the agent as offline if the VM restarts](#virtual-machine-scale-sets-shows-the-agent-as-offline-if-the-vm-restarts) + - [You can see multiple tags like \_AzureDevOpsElasticPoolTimeStamp for Virtual Machine Scale Sets in cost management](#you-can-see-multiple-tags-like-_azuredevopselasticpooltimestamp-for-virtual-machine-scale-sets-in-cost-management) + - [You can't create a new scale set agent pool and get an error message that a pool with the same name already exists](#you-cant-create-a-new-scale-set-agent-pool-and-get-an-error-message-that-a-pool-with-the-same-name-already-exists) + - [Virtual Machine Scale Sets maintenance job isn't running on agents or getting logs](#virtual-machine-scale-sets-maintenance-job-isnt-running-on-agents-or-getting-logs) + - [If you specify `AzDevOps` as the primary administrator in your script for Virtual Machine Scale Sets, you may observe issues with the agent configurations on scale set instances](#if-you-specify-azdevops-as-the-primary-administrator-in-your-script-for-virtual-machine-scale-sets-you-may-observe-issues-with-the-agent-configurations-on-scale-set-instances) + - [Agent extension installation fails on scale set instances due to network security and firewall configurations](#agent-extension-installation-fails-on-scale-set-instances-due-to-network-security-and-firewall-configurations) + - [Why does my scale set agent configuration script call Add-MpPreference and configure Windows Defender on the agent?](#why-does-my-scale-set-agent-configuration-script-call-add-mppreference-and-configure-windows-defender-on-the-agent) + - [I want to increase my pool size. What should I take into consideration?](#i-want-to-increase-my-pool-size-what-should-i-take-into-consideration) ### What are some common issues and their solutions? @@ -500,7 +495,7 @@ For information on purchasing parallel jobs, see [Configure and pay for parallel To better understand why this happens, see [How Azure Pipelines manages the scale set](#how-azure-pipelines-manages-the-scale-set). Throughout the scaling operation, the goal for Azure Pipelines is to reach the desired number of idle agents on standby. Pools scale out and in slowly. Over a day, the pool will scale out as requests are queued in the morning and scale in as the load subsides in the evening. This is an expected behavior as Azure Pipelines converges gradually to the constraints that you specify. -#### VMSS scale up isn't happening in the expected five-minute interval +#### Virtual Machine Scale Sets scale up isn't happening in the expected five-minute interval The scaling job runs every five minutes, but if only one operation is processed, you may observe that scale up isn’t happening within five minutes; this is currently by design. @@ -518,14 +513,14 @@ Only VMs for which agents fail to start are saved. If a VM has a failed state du The option to tear down the VM after each build will only work for Windows Server and supported Linux images. It isn’t supported for Windows client images. -#### VMSS shows the agent as offline if the VM restarts +#### Virtual Machine Scale Sets shows the agent as offline if the VM restarts Showing the agents as offline if the VM restarts is the expected behavior. The agent service runs in the systemd context only. However, if the machine restarts for some reason, it's considered an unhealthy VM and deleted. For more information, see [Unhealthy Agents](#unhealthy-agents). When agents or virtual machines fail to start, can't connect to Azure DevOps, or go offline unexpectedly, Azure DevOps logs the failures to the Agent Pool's **Diagnostics** tab and tries to delete the associated virtual machine. Networking configuration, image customization, and pending reboots may cause these issues. To avoid the issue, disable the software update on the image. You can also connect to the VM to debug and gather logs to help investigate the issue. -#### You can see multiple tags like _AzureDevOpsElasticPoolTimeStamp for VMSS in cost management +#### You can see multiple tags like _AzureDevOpsElasticPoolTimeStamp for Virtual Machine Scale Sets in cost management When the pool is created, a tag is added to the scale set to mark the scale set as in use (to avoid two pools using the same scale set), and another tag is added for the timestamp that updates each time the configuration job runs (every two hours). @@ -533,11 +528,11 @@ When the pool is created, a tag is added to the scale set to mark the scale set You may get an error message like `This virtual machine scale set is already in use by pool ` because the tag still exists on the scale set even after it's deleted. When an agent pool is deleted, you attempt to delete the tag from the scale set, but this is a best-effort attempt, and you give up after three retries. Also, there can be a maximum of a two-hour gap, in which a Virtual Machine Scale Set that isn't used by any agent pool can't be assigned to a new one. The fix for this is to wait for that time interval to pass, or manually delete the tag for the scale set from the Azure portal. When viewing the scale set in the Azure portal, select the **Tags** link on the left and delete the tag labeled **_AzureDevOpsElasticPool**. -#### VMSS maintenance job isn't running on agents or getting logs +#### Virtual Machine Scale Sets maintenance job isn't running on agents or getting logs The maintenance job runs once every 24 hours. It's possible that VMs are getting filled up before this time. Consider increasing the disk size on the VM and adding a script in the pipeline to delete the contents. -#### If you specify `AzDevOps` as the primary administrator in your script for VMSS, you may observe issues with the agent configurations on scale set instances +#### If you specify `AzDevOps` as the primary administrator in your script for Virtual Machine Scale Sets, you may observe issues with the agent configurations on scale set instances If you specify `AzDevOps` as the primary administrator in your script for Virtual Machine Scale Set, you may observe issues with the agent configurations on scale set instances (the password for the user is changed if it already exists). @@ -548,7 +543,11 @@ This issue occurs because agent extension scripts attempt to create the user `Az #### Agent extension installation fails on scale set instances due to network security and firewall configurations -The extension needs to be able to download the build agent files from `https://vstsagentpackage.azureedge.net/agent`, and the build agent needs to be able to register with Azure DevOps Services. Make sure that this URL and Azure DevOps Services-related IPs and URLs are open on the instance. For IPs and URLs that need to be unblocked on your firewall, see [Allowed IP addresses and domain URLs](/azure/devops/organizations/security/allow-list-ip-url). +The extension needs to be able to download the build agent files from `https://vstsagentpackage.azureedge.net/agent` and `https://download.agent.dev.azure.com`, and the build agent needs to be able to register with Azure DevOps Services. Make sure that this URL and Azure DevOps Services-related IPs and URLs are open on the instance. For IPs and URLs that need to be unblocked on your firewall, see [Allowed IP addresses and domain URLs](/azure/devops/organizations/security/allow-list-ip-url). + +#### Why does my scale set agent configuration script call Add-MpPreference and configure Windows Defender on the agent? + +To improve performance and reliability, the configuration scripts call [Add-MpPreference](/powershell/module/defender/add-mppreference) with an `ExclusionPath` containing `C:\` and `D:\`, which disables Windows Defender scheduled and real-time scanning for files in these folders on the agent. To change the default behavior, set an environment variable named `ELASTIC_POOLS_SKIP_DEFENDER_EXCLUSION` to `true`. #### I want to increase my pool size. What should I take into consideration? diff --git a/docs/pipelines/agents/service-principal-agent-registration.md b/docs/pipelines/agents/service-principal-agent-registration.md new file mode 100644 index 00000000000..3a29c334d43 --- /dev/null +++ b/docs/pipelines/agents/service-principal-agent-registration.md @@ -0,0 +1,68 @@ +--- +title: Register an agent using a service principal +description: Learn how to register a self-hosted agent using a Service Principal +ms.topic: conceptual +ms.date: 04/26/2024 +monikerRange: 'azure-devops' +ms.custom: arm2024 +--- + +# Register an agent using a service principal + +You can register an agent using a Service Principal starting with [agent version 3.227.1](https://github.com/microsoft/azure-pipelines-agent/releases/tag/v3.227.1) by specifying **SP** as the agent authentication option. + +## Grant the Service Principal access to the agent pool + +Before registering an agent using a Service Principal you must have [created a Service Principal](../../integrate/get-started/authentication/service-principal-managed-identity.md) and granted it permission to access the agent pool. + +> [!IMPORTANT] +> To grant a Service Principal access to the agent pool, you must be an agent pool administrator, an [Azure DevOps organization owner](../../organizations/accounts/faq-user-and-permissions-management.yml#find-owner), or a [TFS or Azure DevOps Server administrator](/azure/devops/server/admin/add-administrator). +> +> If your agent is a [deployment group](../release/deployment-groups/index.md) agent, you must be a deployment group administrator, an [Azure DevOps organization owner](../../organizations/accounts/faq-user-and-permissions-management.yml#find-owner), or a [TFS or Azure DevOps Server administrator](/azure/devops/server/admin/add-administrator). + +1. Open a browser and navigate to the **Agent pools** tab for your Azure Pipelines organization. + + [!INCLUDE [agent-pools-tab](./includes/agent-pools-tab/agent-pools-tab.md)] + +1. Select the desired agent pool on the right side of the page and then choose **Security**. Choose Add, and add the Service Principal with the **Administrator** role. + + :::image type="content" source="./media/agent-registration/agent-pool-security.png" alt-text="Screenshot of agent pool security tab."::: + +1. If the Service Principal you're going to use is not shown, then get an administrator to add it, granting the Service Principal the administrator role for the agent pool. The administrator can be an agent pool administrator, an [Azure DevOps organization owner](../../organizations/accounts/faq-user-and-permissions-management.yml#find-owner), or a [TFS or Azure DevOps Server administrator](/azure/devops/server/admin/add-administrator). + + If it's a [deployment group](../release/deployment-groups/index.md) agent, the administrator can be a deployment group administrator, an [Azure DevOps organization owner](../../organizations/accounts/faq-user-and-permissions-management.yml#find-owner), or a [TFS or Azure DevOps Server administrator](/azure/devops/server/admin/add-administrator). + + You can add a Service Principal to the deployment group administrator role in the **Security** tab on the **Deployment Groups** page in **Azure Pipelines**. + +> [!NOTE] +> If you see a message like this: **Sorry, we couldn't add the identity. Please try a different identity.** or **Cannot modify the role for self identity. Please try with a different identity.**, you probably followed the above steps for an organization owner or TFS or Azure DevOps Server administrator. You don't need to do anything; you already have permission to administer the agent pool. +> +> If you are adding the Service Principal to the agent pool security group using **Project Settings**, **Agent pools**, you must first add the Service Principal as an organization user with **Basic** **Access level** (recommended) or higher. + +## Register the agent using a Service Principal + +1. Specify **SP** when prompted for authentication type during agent configuration to use a Service Principal to authenticate during agent registration. + +1. When prompted, supply the **Client(App) ID** and the **Tenant ID**. + + :::image type="content" source="./media/agent-registration/service-principal-ids.png" alt-text="Screenshot of application IDs."::: + +1. Specify the client secret. The client secret is used only during agent registration. + + :::image type="content" source="./media/agent-registration/service-principal-client-secret.png" alt-text="Screenshot of client secret."::: + +1. Specify the name of the agent pool for which you granted administrator permission for the Service Principal, and continue the agent registration steps. + +For more information about using Service Principal with Azure DevOps, see [Use service principals & managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md). + +> [!NOTE] +> If you are configuring an agent from Azure China Cloud to an Azure DevOps organization in Azure Public Cloud using a service principal (in Azure Public Cloud), you may get the following error: +> +> `ClientSecretCredential authentication failed: AADSTS90002: Tenant 'xxxxxxxxxxxxxx' not found. Check to make sure you have the correct tenant ID and are signing into the correct cloud. Check with your subscription administrator, this may happen if there are no active subscriptions for the tenant.` +> +> To resolve this error, set the login URL to Azure Public Cloud login by setting the environment variable `$AZURE_AUTHORITY_HOST` to +`https://login.microsoftonline.com`, then run the agent config.cmd. +> +> For more information, see [Azure in China developer guide](/azure/china/resources-developer-guide), +> [Help on agent registration options](/azure/devops/pipelines/agents/windows-agent#help-on-other-options), and +> [EnvironmentCredentialClass](/python/api/azure-identity/azure.identity.environmentcredential). diff --git a/docs/pipelines/agents/v2-linux-agent.md b/docs/pipelines/agents/v2-linux-agent.md index ade1a51c9ed..78224cdecfb 100644 --- a/docs/pipelines/agents/v2-linux-agent.md +++ b/docs/pipelines/agents/v2-linux-agent.md @@ -1,8 +1,8 @@ --- title: Deploy an Azure Pipelines agent on Linux (2.x) -ms.custom: seodec18 description: Learn how you can easily deploy a self-hosted agent on Linux for Azure Pipelines and Team Foundation Server (TFS) (2.x). ms.topic: conceptual +ms.custom: linux-related-content ms.assetid: 834FFB19-DCC5-40EB-A3AD-18B7EDCA976E ms.date: 05/05/2023 monikerRange: '<= azure-devops' @@ -19,13 +19,7 @@ monikerRange: '<= azure-devops' :::moniker-end -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - -To run your jobs, you'll need at least one agent. A Linux agent can build and deploy different kinds of apps, including Java and Android apps. We support Ubuntu, Red Hat, and CentOS. +To run your jobs, you need at least one agent. A Linux agent can build and deploy different kinds of apps, including Java and Android apps. We support Ubuntu and Red Hat. > Before you begin: > * If your pipelines are in [Azure Pipelines](https://visualstudio.microsoft.com/products/visual-studio-team-services-vs) and a [Microsoft-hosted agent](hosted.md) meets your needs, you can skip setting up a private Linux agent. @@ -35,13 +29,12 @@ To run your jobs, you'll need at least one agent. A Linux agent can build and de ## Check prerequisites -::: moniker range="> tfs-2018" +::: moniker range="<=azure-devops" The agent is based on .NET Core 3.1. You can run this agent on several Linux distributions. We support the following subset of .NET Core supported distributions: - x64 - - CentOS 7, 6 (see note 1) - Debian 9 - Fedora 30, 29 - Linux Mint 18, 17 @@ -59,7 +52,7 @@ We support the following subset of .NET Core supported distributions: - Ubuntu 21.04, 20.04, 18.04 > [!NOTE] -> Note 1: RHEL 6 and CentOS 6 require installing the specialized `rhel.6-x64` version of the agent. +> Note 1: RHEL 6 requires installing the specialized `rhel.6-x64` version of the agent. > [!IMPORTANT] > As of February 2023, no more agent releases support RHEL 6. For more information, see [Customers using Red Hat Enterprise Linux (RHEL) 6 should upgrade the OS on Self-hosted agents](https://devblogs.microsoft.com/devops/customers-using-red-hat-enterprise-linux-rhel-6-should-upgrade-the-os-on-self-hosted-agents/). @@ -72,7 +65,7 @@ We support the following subset of .NET Core supported distributions: > Azure Linux OS distribution currently has partial support from the Azure DevOps Agent. > We are providing a mechanism for detection of this OS distribution in `installdependencies.sh` script, but due to lack of support from the [.Net Core](https://github.com/dotnet/core/issues/6379) side, we couldn't guarantee full operability of all agent functions when running on this OS distribution. -Regardless of your platform, you will need to install Git 2.9.0 or higher. +Regardless of your platform, you need to install Git 2.9.0 or higher. We strongly recommend installing the latest version of Git. > [!NOTE] @@ -85,20 +78,6 @@ You can install those dependencies on supported Linux platforms by running `./bi > > For issues with dependencies installation (like 'dependency was not found in repository' or 'problem retrieving the repository index file') - you can reach out to distribution owner for further support. - -::: moniker-end - -::: moniker range="tfs-2018" - -**TFS 2018 RTM and older**: The shipped agent is based on CoreCLR 1.0. -We recommend that, if able, you should upgrade to a later agent version (2.125.0 or higher). -See [Azure Pipelines agent prereqs](?view=azure-devops&preserve-view=true#check-prerequisites) for more about what's required to run a newer agent. - -If you must stay on the older agent, make sure your machine is prepared with our prerequisites for either of the supported distributions: - -* [Ubuntu systems](https://aka.ms/vstsagentubuntusystem) -* [Red Hat/CentOS systems](https://aka.ms/vstsagentredhatsystem) - ::: moniker-end ### Subversion @@ -110,18 +89,18 @@ After you get a feel for how agents work, or if you want to automate setting up ### TFVC -If you'll be using TFVC, you'll also need the [Oracle Java JDK 1.6](https://www.oracle.com/technetwork/java/javaseproducts/downloads/index.html) or higher. +If you are using TFVC, you also need the [Oracle Java JDK 1.6](https://www.oracle.com/technetwork/java/javaseproducts/downloads/index.html) or higher. (The Oracle JRE and OpenJDK aren't sufficient for this purpose.) [TEE plugin](https://github.com/microsoft/team-explorer-everywhere) is used for TFVC functionality. -It has an EULA, which you'll need to accept during configuration if you plan to work with TFVC. +It has an EULA, which you need to accept during configuration if you plan to work with TFVC. -Since the TEE plugin is no longer maintained and contains some out-of-date Java dependencies, starting from Agent 2.198.0 it's no longer included in the agent distribution. However, the TEE plugin will be downloaded during checkout task execution if you're checking out a TFVC repo. The TEE plugin will be removed after the job execution. +Since the TEE plugin is no longer maintained and contains some out-of-date Java dependencies, starting from Agent 2.198.0 it's no longer included in the agent distribution. However, the TEE plugin is downloaded during checkout task execution if you're checking out a TFVC repo. The TEE plugin is removed after the job execution. > [!NOTE] > Note: You may notice your checkout task taking a long time to start working because of this download mechanism. -If the agent is running behind a proxy or a firewall, you'll need to ensure access to the following site: `https://vstsagenttools.blob.core.windows.net/`. The TEE plugin will be downloaded from this address. +If the agent is running behind a proxy or a firewall, you need to ensure access to the following site: `https://vstsagenttools.blob.core.windows.net/`. The TEE plugin is downloaded from this address. If you're using a self-hosted agent and facing issues with TEE downloading, you may install TEE manually: 1. Set `DISABLE_TEE_PLUGIN_REMOVAL` environment or pipeline variable to `true`. This variable prevents the agent from removing the TEE plugin after TFVC repository checkout. @@ -153,13 +132,13 @@ If you're using a self-hosted agent and facing issues with TEE downloading, you 1. On the right pane, click the **Download** button. -1. Follow the instructions on the page. +1. Follow the instructions on the page.
      1. Unpack the agent into the directory of your choice. `cd` to that directory and run `./config.sh`. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" +1. Click **Download agent**.
      -1. On the **Get agent** dialog box, click **Linux**. +1. On the **Get agent** dialog box, click **Linux**.
      1. On the left pane, select the specific flavor. We offer x64 or ARM for most Linux distributions. 1. On the right pane, click the **Download** button. -1. Follow the instructions on the page. +1. Follow the instructions on the page.
      1. Unpack the agent into the directory of your choice. `cd` to that directory and run `./config.sh`. ::: moniker-end -::: moniker range="tfs-2018" - -### TFS 2018 - -1. Log on to the machine using the account for which you've prepared permissions as explained above. - -1. In your web browser, sign in to TFS, and navigate to the **Agent pools** tab: - - [!INCLUDE [include](includes/agent-pools-tab/agent-pools-tab-tfs-2018.md)] - -1. Click **Download agent**. - -1. On the **Get agent** dialog box, click **Linux**. - -1. Click the **Download** button. - -1. Follow the instructions on the page. - -1. Unpack the agent into the directory of your choice. `cd` to that directory and run `./config.sh`. Make sure that the path to the directory contains no spaces because tools and scripts don't always properly escape spaces. - -::: moniker-end - - ### Server URL ::: moniker range="azure-devops" @@ -214,19 +170,6 @@ Azure Pipelines: `https://dev.azure.com/{your-organization}` ::: moniker-end -::: moniker range="azure-devops-2019" - -Azure DevOps Server 2019: `https://{your_server}/DefaultCollection` - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -TFS 2018: `https://{your_server}/tfs` - -::: moniker-end - - ### Authentication type [!INCLUDE [include](includes/v2/unix-authentication-types.md)] @@ -248,7 +191,7 @@ To run the agent interactively: To restart the agent, press Ctrl+C and then run `run.sh` to restart it. To use your agent, run a [job](../process/phases.md) using the agent's pool. -If you didn't choose a different pool, your agent will be in the **Default** pool. +If you didn't choose a different pool, your agent is placed in the **Default** pool. ### Run once @@ -269,7 +212,7 @@ If your agent is running on these operating systems you can run the agent as a ` * Red Hat 7.1 or newer We provide an example `./svc.sh` script for you to run and manage your agent as a `systemd` service. -This script will be generated after you configure the agent. +This script is generated after you configure the agent. We encourage you to review, and if needed, update the script before running it. Some important caveats: @@ -361,7 +304,7 @@ A systemd service file is created: `/etc/systemd/system/vsts.agent.{tfs-name}.{agent-name}.service` -For example, you have configured an agent (see above) with the name `our-linux-agent`. The service file will be either: +For example, you have configured an agent (see above) with the name `our-linux-agent`. The service file is either: * **Azure Pipelines**: the name of your organization. For example if you connect to `https://dev.azure.com/fabrikam`, then the service name would be `/etc/systemd/system/vsts.agent.fabrikam.our-linux-agent.service` diff --git a/docs/pipelines/agents/v2-osx-agent.md b/docs/pipelines/agents/v2-osx-agent.md index 40468bf9c23..b57eaef75d7 100644 --- a/docs/pipelines/agents/v2-osx-agent.md +++ b/docs/pipelines/agents/v2-osx-agent.md @@ -1,6 +1,5 @@ --- title: Deploy a build and release agent on macOS (2.x) -ms.custom: seodec18 description: Learn how to deploy a macOS agent to build and deploy your iOS application for Azure Pipelines and Team Foundation Server (TFS) (2.x) ms.topic: conceptual ms.assetid: 3D487E4E-D940-4DA9-BDE1-1F60E74DD6F1 @@ -19,13 +18,7 @@ monikerRange: '<= azure-devops' :::moniker-end -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - -To build and deploy Xcode apps or Xamarin.iOS projects, you'll need at least one macOS agent. This agent can also build and deploy Java and Android apps. +To build and deploy Xcode apps, you need at least one macOS agent. This agent can also build and deploy Java and Android apps. > Before you begin: > * If your pipelines are in [Azure Pipelines](https://visualstudio.microsoft.com/products/visual-studio-team-services-vs) and a [Microsoft-hosted agent](hosted.md) meets your needs, you can skip setting up a self-hosted macOS agent. @@ -35,7 +28,7 @@ To build and deploy Xcode apps or Xamarin.iOS projects, you'll need at least one ## Check prerequisites -::: moniker range=">= tfs-2018" +::: moniker range="<=azure-devops" Make sure your machine has these prerequisites: - macOS 10.15 "Catalina", macOS 11.0 "Big Sur", or macOS 12.0 "Monterey" @@ -101,7 +94,7 @@ After you get a feel for how agents work, or if you want to automate setting up ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!NOTE] -> For more information, see the [Terminally Geeky: use automatic login more securely](https://www.engadget.com/2011/03/07/terminally-geeky-use-automatic-login-more-securely/) blog. The .plist file mentioned in that blog may no longer be available at the source, but a copy can be found here: [Lifehacker - Make OS X load your desktop before you log in](https://lifehacker.com/5779922/make-os-x-load-your-desktop-before-you-log-in). +> For more information, see the [Terminally Geeky: use automatic login more securely](https://www.engadget.com/2011/03/07/terminally-geeky-use-automatic-login-more-securely/) blog. The .plist file mentioned in that blog may no longer be available at the source, but a copy can be found here: [Lifehacker - Make OS X load your desktop before you log in](https://lifehacker.com/make-os-x-load-your-desktop-before-you-log-in-5779922).

      Update environment variables

      diff --git a/docs/pipelines/agents/v2-windows-agent.md b/docs/pipelines/agents/v2-windows-agent.md index 1f089bc4dfc..7e8f1087ccc 100644 --- a/docs/pipelines/agents/v2-windows-agent.md +++ b/docs/pipelines/agents/v2-windows-agent.md @@ -1,10 +1,9 @@ --- title: Deploy an Azure Pipelines agent on Windows (2.x) -ms.custom: contperf-fy21q1 -description: Learn how to use Windows agents to build and deploy your Windows and Azure code for Azure Pipelines and TFS (2.x) +description: Learn how to use Windows agents to build and deploy your Windows and Azure code for Azure Pipelines and Azure DevOps Server (2.x) ms.topic: conceptual ms.assetid: 20409B8F-A3A9-49A0-A418-1840BD7ADA8E -ms.date: 05/05/2023 +ms.date: 04/17/2024 monikerRange: '<= azure-devops' --- @@ -15,15 +14,14 @@ monikerRange: '<= azure-devops' :::moniker range="azure-devops" > [!IMPORTANT] -> This article provides guidance for using the 2.x version agent software with Azure DevOps Server and TFS. If you're using Azure DevOps Services, see [Self-hosted Windows agents](windows-agent.md). +> This article provides guidance for using the 2.x version agent software with Azure DevOps Server. If you're using Azure DevOps Services, see [Self-hosted Windows agents](windows-agent.md). :::moniker-end -To build and deploy Windows, Azure, and other Visual Studio solutions you'll need at least one Windows agent. Windows agents can also build Java and Android apps. +To build and deploy Windows, Azure, and other Visual Studio solutions you need at least one Windows agent. Windows agents can also build Java and Android apps. > Before you begin: > * If your code is in [Azure Pipelines](https://visualstudio.microsoft.com/products/visual-studio-team-services-vs) and a [Microsoft-hosted agent](hosted.md) meets your needs, you can skip setting up a self-hosted Windows agent. -> * If your code is in an on-premises Team Foundation Server (TFS) 2015 server, see [Deploy an agent on Windows for on-premises TFS 2015](/previous-versions/azure/devops/pipelines/agents/v1-windows). > * Otherwise, you've come to the right place to set up an agent on Windows. Continue to the next section. [!INCLUDE [include](includes/concepts.md)] @@ -42,7 +40,6 @@ Make sure your machine has these prerequisites: Recommended: - [Visual Studio build tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=16) (2015 or higher) - If you're building from a Subversion repo, you must install the [Subversion client](https://subversion.apache.org/) on the machine. You should run agent setup manually the first time. @@ -50,8 +47,8 @@ After you get a feel for how agents work, or if you want to automate setting up ### Hardware specs -The hardware specs for your agents will vary with your needs, team size, etc. -It's not possible to make a general recommendation that will apply to everyone. +The hardware specs for your agents vary with your needs, team size, etc. +It's not possible to make a general recommendation that applies to everyone. As a point of reference, the Azure DevOps team builds the hosted agents code using pipelines that utilize [hosted agents](hosted.md). On the other hand, the bulk of the Azure DevOps code is built by 24-core server class machines running 4 self-hosted agents apiece. @@ -67,7 +64,7 @@ running 4 self-hosted agents apiece. ### Azure Pipelines -1. Log on to the machine using the account for which you've prepared permissions as explained above. +1. Log on to the machine using the account for which you've prepared permissions as explained in the previous section. 1. In your web browser, sign in to Azure Pipelines, and navigate to the **Agent pools** tab: @@ -85,11 +82,11 @@ If you aren't sure which version of Windows is installed, [follow these instruct 1. Follow the instructions on the page to download the agent. -1. Unpack the agent into the directory of your choice. Make sure that the path to the directory contains no spaces because tools and scripts don't always properly escape spaces. A recommended folder is `C:\agents`. Extracting in the download folder or other user folders may cause permission issues. Then run `config.cmd`. This will ask you a series of questions to configure the agent. +1. Unpack the agent into the directory of your choice. Make sure that the path to the directory contains no spaces because tools and scripts don't always properly escape spaces. A recommended folder is `C:\agents`. Extracting in the download folder or other user folders may cause permission issues. Then run `config.cmd`, and respond to a series of questions to configure the agent. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" +1. Click **Download agent**.
      -1. On the **Get agent** dialog box, click **Windows**. +1. On the **Get agent** dialog box, click **Windows**.
      1. On the left pane, select the processor architecture of the installed Windows OS version on your machine. The x64 version is intended for 64-bit Windows, whereas the x86 version is intended for 32-bit Windows. @@ -115,28 +112,6 @@ If you aren't sure which version of Windows is installed, [follow these instruct ::: moniker-end -::: moniker range="tfs-2018" - -### TFS 2018 - -1. Log on to the machine using the account for which you've prepared permissions as explained above. - -1. In your web browser, sign in to TFS, and navigate to the **Agent pools** tab: - - [!INCLUDE [include](includes/agent-pools-tab/agent-pools-tab-tfs-2018.md)] - -1. Click **Download agent**. - -1. On the **Get agent** dialog box, click **Windows**. - -1. Click the **Download** button. - -1. Follow the instructions on the page to download the agent. - -1. Unpack the agent into the directory of your choice. Make sure that the path to the directory contains no spaces because tools and scripts don't always properly escape spaces. A recommended folder is `C:\agents`. Extracting in the download folder or other user folders may cause permission issues. Then run `config.cmd`. - -::: moniker-end - > [!IMPORTANT] > We strongly recommend you configure the agent from an elevated PowerShell window. > If you want to configure as a service, this is **required**. @@ -146,7 +121,6 @@ If you aren't sure which version of Windows is installed, [follow these instruct > [!IMPORTANT] > For security reasons we strongly recommend making sure the agents folder (`C:\agents`) is only editable by admins. - > [!Note] > Please avoid using mintty based shells, such as git-bash, for agent configuration. Mintty is not fully compatible with native Input/Output Windows API ([here](https://github.com/mintty/mintty/wiki/Tips#inputoutput-interaction-with-alien-programs) is some info about it) and we couldn't guarantee correct work of setup script in this case. @@ -174,20 +148,20 @@ Then paste the [PAT token you created](#permissions) into the command prompt win > > Make sure your server is [configured to support the authentication method](agents.md#configure-tfs-authentication) you want to use. -When you configure your agent to connect to TFS, you've got the following options: +When you configure your agent to connect to Azure DevOps Server, you've got the following options: -* **Alternate** Connect to TFS using Basic authentication. After you select Alternate you'll be prompted for your credentials. +* **Alternate** Connect to Azure DevOps Server using Basic authentication. After you select Alternate you're prompted for your credentials. -* **Negotiate** Connect to TFS as a user other than the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. After you select Negotiate you'll be prompted for credentials. +* **Negotiate** Connect to Azure DevOps Server as a user other than the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. After you select Negotiate you're prompted for credentials. -* **Integrated** (Default) Connect a Windows agent to TFS using the credentials of the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. You won't be prompted for credentials after you choose this method. +* **Integrated** (Default) Connect a Windows agent to Azure DevOps Server using the credentials of the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. You won't be prompted for credentials after you choose this method. -* **PAT** Supported only on Azure Pipelines and TFS 2017 and newer. After you choose PAT, paste the [PAT token you created](#permissions) into the command prompt window. Use a personal access token (PAT) if your TFS instance and the agent machine are not in a trusted domain. PAT authentication is handled by your TFS instance instead of the domain controller. +* **PAT** After you choose PAT, paste the [PAT token you created](#permissions) into the command prompt window. Use a personal access token (PAT) if your Azure DevOps Server instance and the agent machine are not in a trusted domain. PAT authentication is handled by your Azure DevOps Server instance instead of the domain controller. > [!NOTE] > When using PAT as the authentication method, the PAT token is used only for the initial configuration of the agent. If the PAT needs to be regenerated, no further changes are needed to the agent. -Learn more at [Communication with Azure Pipelines or TFS](agents.md#communication). +Learn more at [Communication with Azure Pipelines or Azure DevOps Server](agents.md#communication). ::: moniker-end @@ -223,9 +197,17 @@ Agents in this mode will accept only one job and then spin down gracefully (usef ### Run as a service If you configured the agent to run as a service, it starts automatically. You can view and control the agent running status from the services snap-in. Run `services.msc` and look for one of: -- "Azure Pipelines Agent (*name of your agent*)". -- "VSTS Agent (*name of your agent*)". -- "vstsagent.(*organization name*).(*name of your agent*)". +- `Azure Pipelines Agent (*name of your agent*)` +- `VSTS Agent (*name of your agent*)` +- `vstsagent.(*organization name*).(*name of your agent*)` + +> [!Note] +> To allow more flexibility with access control of an agent running as a service it +> is possible to set up the agent service SID type as [`SERVICE_SID_TYPE_UNRESTRICTED`] via +> flag or prompt during interactive configuration flow. +> By default, the agent service is configured with `SERVICE_SID_TYPE_NONE`. +> +> For more details about [SID](/windows-server/identity/ad-ds/manage/understand-security-identifiers) types please check this [documentation](/windows/win32/api/winsvc/ns-winsvc-service_sid_info#members). To restart the agent, right-click the entry and choose **Restart**. @@ -295,6 +277,9 @@ The help provides information on authentication alternatives and unattended conf ### How do I run the agent with self-signed certificate? +> [!NOTE] +> Running the agent with a self-signed certificate only applies to Azure DevOps Server. + [Run the agent with self-signed certificate](certificate.md) ### How do I run the agent behind a web proxy? @@ -303,7 +288,7 @@ The help provides information on authentication alternatives and unattended conf ### How do I restart the agent -If you are running the agent interactively, see the restart instructions in [Run interactively](#run-interactively). If you are running the agent as a service, restart the agent by following the steps in [Run as a service](#run-as-a-service). +If you're running the agent interactively, see the restart instructions in [Run interactively](#run-interactively). If you're running the agent as a service, restart the agent by following the steps in [Run as a service](#run-as-a-service). ::: moniker range="azure-devops" ### How do I set different environment variables for each individual agent? diff --git a/docs/pipelines/agents/v3-agent.md b/docs/pipelines/agents/v3-agent.md index 3a417e553fd..4e5f5c74446 100644 --- a/docs/pipelines/agents/v3-agent.md +++ b/docs/pipelines/agents/v3-agent.md @@ -1,15 +1,22 @@ --- title: Agent software version 3 description: Learn how to run pipelines using the version 3 agent software. -monikerRange: '= azure-devops' +monikerRange: '>= azure-devops-2022' ms.topic: conceptual -ms.date: 05/01/2023 +ms.date: 05/17/2024 --- # Agent software version 3 + The pipelines team is upgrading the agent software from version 2.x (using .NET Core 3.1) to version 3.x (using .NET 6). The new agent version supports new Apple silicon hardware and newer operating systems like Ubuntu 22.04, or Windows on ARM64. +:::moniker range="=azure-devops-2022" + +[!INCLUDE [feature-added-2022-1](../../includes/feature-added-2022-1.md)] + +:::moniker-end + ## Upgrade to 3.x agent on supported operating systems If you're running your self-hosted agents on newer operating systems [supported by .NET 6](https://github.com/dotnet/core/blob/main/release-notes/6.0/supported-os.md), the upgrade to the new agent version is automatic. @@ -18,7 +25,6 @@ The following operating systems are supported by the 3.x agent. * **Linux** * x64 - * CentOS 7, 8 * Debian 10+ * Fedora 36+ * openSUSE 15+ @@ -27,27 +33,32 @@ The following operating systems are supported by the 3.x agent. * SUSE Enterprise Linux 12 SP2 or later * Ubuntu 22.04, 20.04, 18.04, 16.04 * Azure Linux 2.0 + * Oracle Linux 7 and higher * ARM64 * Debian 10+ * Ubuntu 22.04, 20.04, 18.04 + * Alpine x64 + * [Alpine Linux](https://alpinelinux.org/) 3.13 and higher ([requires agent 3.227 or higher](/azure/devops/release-notes/2023/sprint-228-update#azure-pipelines-agent-now-supports-alpine-linux)) * **macOS** * x64 * macOS 10.15 "Catalina" * macOS 11.0 "Big Sur" * macOS 12.0 "Monterey" * macOS 13.0 "Ventura" + * macOS 14.0 "Sonoma" * ARM64 * macOS 11.0 "Big Sur" * macOS 12.0 "Monterey" * macOS 13.0 "Ventura" - * Note: Not all Azure Pipeline tasks have been updated to support ARM64 yet + * macOS 14.0 "Sonoma" * **Windows** * Client OS * Windows 7 SP1 [ESU](/troubleshoot/windows-client/windows-7-eos-faq/windows-7-extended-security-updates-faq) * Windows 8.1 * Windows 10 + * Windows 11 * Server OS - * Windows Server 12 or higher + * Windows Server 2012 or higher ## Upgrade to 3.x agent on unsupported operating systems @@ -57,7 +68,6 @@ The following list of operating systems are commonly used for self-hosted 2.x ag | System/Distribution | Version not supported by .NET 6 | |---------------------|---------------------------------| -| CentOS | < 7 | | Debian | <= 4.9 | | Fedora | <= 32 | | RedHat Enterprise Linux | <= 6 | @@ -114,9 +124,35 @@ You don't have to install .NET 6 on your agent machine before installing and con The version of .NET used to run the 3.x agent is self-contained in the agent installation, and isn't used to build your code. The version of .NET that is used to build your code depends on the pipeline and the version or versions of .NET you have installed onto your agent machine. -### I use Azure DevOps Server and not Azure DevOps Service. Does this change impact me? +### I use Azure DevOps Server and not Azure DevOps Services. Does this change impact me? + +Yes, if you are using any of the versions of Azure DevOps Server listed in the following section. + +The pipelines team recommends that you update your agent machines to newer operating systems that are supported by .NET 6 starting now, if you plan to keep up with the Azure DevOps Server releases in the future. + +### Does Azure DevOps Server support the 3.x agent + +Azure DevOps Server versions support the version of the agent that is deployed with that version. The following table lists each [supported Azure DevOps Server version](/azure/devops/server/install/servicing#supported-versions) and its supported agent version. + +| Azure DevOps Server version | Agent version | +|-----------------------------|---------------| +| [Azure DevOps Server 2022.2](/azure/devops/server/release-notes/azuredevops2022u2) | 3.238.0 | +| [Azure DevOps Server 2020.1.2](/azure/devops/server/release-notes/azuredevops2020u1) | 3.225.0 | +| [Azure DevOps Server 2019.1.2](/azure/devops/server/release-notes/azuredevops2019u1) | 3.225.0 | + +Azure DevOps Server is serviced through security or servicing patches that provide targeted cumulative bug fixes for existing features in the product. For the best and most secure product experience, we strongly encourage and recommend that all customers use the latest, most secure release of Azure DevOps Server. You can download the latest version of the product, from the [Azure DevOps Server download page](/azure/devops/server/download/azuredevopsserver). + +After installing an Azure DevOps Server update or new version, [update your agents](/azure/devops/pipelines/agents/agents#to-update-self-hosted-agents). + +The following table lists the versions of Azure DevOps Server that first included a version of the 3.x agent. -No. The new agent is only applicable for Azure DevOps Service customers at this time. However, a future version of Azure DevOps Server will include the new agent. The pipelines team recommends that you update your agent machines to newer operating systems that are supported by .NET 6 starting now, if you plan to keep up with the Azure DevOps Server releases in the future. +* [Azure DevOps Server 2022 Update 2](/azure/devops/server/release-notes/azuredevops2022u2) +* [Azure DevOps Server 2022 Update 1](/azure/devops/server/release-notes/azuredevops2022u1) +* [Azure DevOps Server 2022 Update 0.1 Patch 4 and later](/azure/devops/server/release-notes/azuredevops2022#azure-devops-server-2022-update-01-patch-4-release-date-october-10-2023) +* [Azure DevOps Server 2020 Update 1.2 Patch 9 and later](/azure/devops/server/release-notes/azuredevops2020u1#azure-devops-server-2020-update-12-patch-9-release-date-october-10-2023) +* [Azure DevOps Server 2020 Update 0.2 Patch 4 and later](/azure/devops/server/release-notes/azuredevops2020#azure-devops-server-2020-update-02-patch-4-release-date-september-12-2023) +* [Azure DevOps Server 2019 Update 1.2 Patch 5 and later](/azure/devops/server/release-notes/azuredevops2019u1#azure-devops-server-2019-update-12-patch-5-release-date-september-12-2023) +* [Azure DevOps Server 2019 - patch 15 and later](/azure/devops/server/release-notes/azuredevops2019#azure-devops-server-201901-patch-15-release-date-september-12-2023) ### What is the timeline for agent version 3 deployment? diff --git a/docs/pipelines/agents/v4-agent.md b/docs/pipelines/agents/v4-agent.md new file mode 100644 index 00000000000..08a9fe491bf --- /dev/null +++ b/docs/pipelines/agents/v4-agent.md @@ -0,0 +1,148 @@ +--- +title: Agent software version 4 +description: Learn how to run pipelines using the version 4 agent software. +monikerRange: 'azure-devops' +ms.topic: conceptual +ms.date: 11/27/2024 +--- + +# Agent software version 4 + + +The pipelines team is upgrading the agent software from version 3.x to version 4.x (using .NET 8). + +## Upgrade to 4.x agent on supported operating systems + +If you're running your self-hosted agents on newer operating systems [supported by .NET 8](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md#net-8---supported-os-versions), the upgrade to the new agent version is automatic. + +The following operating systems are supported by the 4.x agent. + +> [!NOTE] +> See [.NET 8 - Supported OS versions](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md#net-8---supported-os-versions) for the full list of operating systems. + +* **Linux** + * x64 + * Debian 12 + * Fedora 39 & 40 + * openSUSE 15.5 & 15.6 + * Red Hat Enterprise Linux 8 & 9 + * SUSE Enterprise Linux 15.5 + * Ubuntu 24.04, 22.04, 20.04 + * Azure Linux 2.0 + * Oracle Linux 8 & 9 + * ARM64 + * Debian 11 & 12 + * Ubuntu 24.04, 22.04, 20.04 + * Alpine x64 + * [Alpine Linux](https://alpinelinux.org/) 3.17 to 3/20 +* **macOS** + * x64 + * macOS 13.0 "Ventura" + * macOS 14.0 "Sonoma" + * macOS 15.0 "Sequoia" + * ARM64 + * macOS 13.0 "Ventura" + * macOS 14.0 "Sonoma" + * macOS 15.0 "Sequoia" +* **Windows** + * Windows 10 + * 21H2, 1809, 1607 + * Windows 11 + * 23H2, 22H2, 21H2 + * Server OS + * Windows Server 2012 or higher + +## Upgrade to 4.x agent on unsupported operating systems + +If you're running your self-hosted agents on an operating system that isn't supported by .NET 8, you must update your machines to use a newer supported operating system [supported by .NET 8](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md#net-8---supported-os-versions). + +The following list of operating systems were supported for self-hosted 3.x agents, but aren't supported by .NET 8 and can't be used to run version 4.x agents. + +> [!NOTE] +> See [.NET 8 - Out of support OS versions](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md#out-of-support-os-versions) for the full list of operating systems that are out of support for .NET 8. + +* **Linux** + * x64 + * Debian 10 & 11 + * Fedora 36 + * openSUSE 15 + * Red Hat Enterprise Linux 7 + * SUSE Enterprise Linux 12 SP2 + * Ubuntu 18.04, 16.04 + * Oracle Linux 7 + * ARM64 + * Debian 10 & 11 + * Ubuntu 18.04 + * Alpine x64 + * [Alpine Linux](https://alpinelinux.org/) 3.13 +* **macOS** + * x64 + * macOS 10.15 "Catalina" + * macOS 11.0 "Big Sur" + * ARM64 + * macOS 11.0 "Big Sur" +* **Windows** + * Client OS + * Windows 7 SP1 [ESU](/troubleshoot/windows-client/windows-7-eos-faq/windows-7-extended-security-updates-faq) + * Windows 8.1 + * Windows 10 + * [21H2 (E)](/lifecycle/products/windows-10-enterprise-and-education) + * Windows 11 + * [21H2 (E) & 22H2 (E)](/windows/release-health/windows11-release-information) + +## FAQ + +### What is the difference between the 3.x and 4.x agents? + +The 3.x agents use .NET 6 and the 4.x agents use .NET 8. + +### How can I check my agents to see if they can upgrade to 4.x? + +Compare the operating system of your agent with the supported list from the previous [Upgrade to 4.x agent on supported operating systems](#upgrade-to-4x-agent-on-supported-operating-systems) section. + +You can also use a [script](https://github.com/microsoft/azure-pipelines-agent/tree/master/tools/FindAgentsNotCompatibleWithAgent) to predict whether the agents in your self-hosted pools will be able to upgrade to 4.x. + +### How will security issues in the agent be patched going forward? + +There will be no patches done, in general, for the previous versions of the agent software. The patches will be done only for the 4.x agents. However, we also have Azure DevOps Server customers that will still be relying on 3.x agents. So, we'll review the security issues on a case by case basis to decide. + +### What do I need to do when I’m on an unsupported OS? + +You should migrate to a newer operating system that is supported by .NET 8 now. Otherwise, your agent may attempt to upgrade, and it will fail as .NET 8 can't be installed on your OS. We'll publish some guidance in a follow-up blog post that will prevent auto-upgrades of the agent. However, that is only meant to be a temporary solution to give you some more time to upgrade your agent machines. + +### Can I stay on 2.x or 3.x agents if I'm not working on any changes in my project anymore? + +No. The pipelines team is regularly adding new features to Azure Pipelines and some of them may require an update to the agent even though your pipeline doesn't explicitly depend on that feature. When you prevent auto-upgrades of the agent using the guidance in a follow-up blog, that agent can't be used to schedule the pipeline. If no agent with the required capabilities can be found, the pipeline execution will fail. + +### Do I have to install .NET 8 before installing the 4.x agent software? + +You don't have to install .NET 8 on your agent machine before installing and configuring the 4.x agent software. All .NET dependencies the 4.x agent requires are part of the agent itself. + +### Do I have to build my code using .NET 8 if I'm using the 4.x agent? + +The version of .NET used to run the 4.x agent is self-contained in the agent installation, and isn't used to build your code. The version of .NET that is used to build your code depends on the pipeline and the version or versions of .NET you have installed onto your agent machine. + +### I use Azure DevOps Server and not Azure DevOps Services. Does this change impact me? + +At this time, the current versions of Azure DevOps Server still use the 3.x agent software, so there is no immediate impact. + +The pipelines team recommends that you update your agent machines to newer operating systems that are supported by .NET 8 starting now, if you plan to keep up with the Azure DevOps Server releases in the future. + +### Does Azure DevOps Server support the 4.x agent + +Azure DevOps Server versions support the version of the agent that is deployed with that version. Currently, the latest Azure DevOps Server versions support the 3.x agent software versions. For more information, see [Does Azure DevOps Server support the 3.x agent](./v3-agent.md#does-azure-devops-server-support-the-3x-agent). + +> [!NOTE] +> Azure DevOps Server 2020 and higher will support the 4.x agent software through updates. When those updates are released, this article will be updated with the corresponding agent version. + +Azure DevOps Server is serviced through security or servicing patches that provide targeted cumulative bug fixes for existing features in the product. For the best and most secure product experience, we strongly encourage and recommend that all customers use the latest, most secure release of Azure DevOps Server. You can download the latest version of the product, from the [Azure DevOps Server download page](/azure/devops/server/download/azuredevopsserver). + +After installing an Azure DevOps Server update or new version, [update your agents](/azure/devops/pipelines/agents/agents#to-update-self-hosted-agents). + +### What is the timeline for agent version 4 deployment? + +Agent version 4.x was released October 2024. + +### What will happen when a task requires an agent to be updated to agent version 4? + +Normally, when a task requires a newer version of the agent, it will automatically update itself. For now, while agent version 3 continues to be updated, we have disabled auto update from agent version 3 to agent version 4. Once we enable it, for Operating Systems that aren't compatible with agent version 4, agent version 3.248 and newer won't attempt to update itself to the v4 agent. Instead, a warning will be shown informing users they need to upgrade the Operating System first: `The operating system the agent is running on is , which will not be supported by the .NET 8 based v4 agent. Please upgrade the operating system of this host to ensure compatibility with the v4 agent. See https://aka.ms/azdo-pipeline-agent-version` diff --git a/docs/pipelines/agents/windows-agent.md b/docs/pipelines/agents/windows-agent.md index af329e3c6a5..d2124dff620 100644 --- a/docs/pipelines/agents/windows-agent.md +++ b/docs/pipelines/agents/windows-agent.md @@ -1,9 +1,8 @@ --- title: Deploy an Azure Pipelines agent on Windows -ms.custom: contperf-fy21q1 description: Learn how to use Windows agents to build and deploy your Windows and Azure code for Azure Pipelines ms.topic: conceptual -ms.date: 05/05/2023 +ms.date: 05/06/2024 monikerRange: '<= azure-devops' --- @@ -15,8 +14,7 @@ To build and deploy Windows, Azure, and other Visual Studio solutions you'll nee :::moniker range="<=azure-devops" -> [!IMPORTANT] -> This article provides guidance for using the [3.x agent software](v3-agent.md) with Azure DevOps Services. If you're using Azure DevOps Server or TFS, see [Self-hosted Windows agents (Agent version 2.x)](v2-windows-agent.md). +This article provides guidance for using the [3.x agent software](v3-agent.md) with Azure DevOps Services and current versions of Azure DevOps Server. For a list of Azure DevOps Server versions that support the 3.x agent, see [Does Azure DevOps Server support the 3.x agent](v3-agent.md#does-azure-devops-server-support-the-3x-agent). :::moniker-end @@ -37,10 +35,10 @@ Make sure your machine has these prerequisites: * Windows 11 * Server OS * Windows Server 2012 or higher -* The agent software installs its own version of .NET so there is no .NET prerequisite. -- [PowerShell 3.0](/powershell/scripting/install/installing-windows-powershell) or higher +* The agent software installs its own version of .NET so there's no .NET prerequisite. +* [PowerShell 3.0](/powershell/scripting/install/installing-windows-powershell) or higher * **Subversion** - If you're building from a Subversion repo, you must install the Subversion client on the machine. -* Recommended - [Visual Studio build tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=16) (2015 or higher) +* Recommended - [Visual Studio build tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) (2015 or higher) You should run agent setup manually the first time. @@ -52,7 +50,7 @@ The hardware specs for your agents will vary with your needs, team size, etc. It's not possible to make a general recommendation that will apply to everyone. As a point of reference, the Azure DevOps team builds the hosted agents code using pipelines that utilize [hosted agents](hosted.md). On the other hand, the bulk of the Azure DevOps code is built by 24-core server class machines -running 4 self-hosted agents apiece. +running four self-hosted agents apiece.

      Prepare permissions

      @@ -81,7 +79,7 @@ If you aren't sure which version of Windows is installed, [follow these instruct 1. Follow the instructions on the page to download the agent. -1. Unpack the agent into the directory of your choice. Make sure that the path to the directory contains no spaces because tools and scripts don't always properly escape spaces. A recommended folder is `C:\agents`. Extracting in the download folder or other user folders may cause permission issues. Then run `config.cmd`. This will ask you a series of questions to configure the agent. +1. Unpack the agent into the directory of your choice. Make sure that the path to the directory contains no spaces because tools and scripts don't always properly escape spaces. A recommended folder is `C:\agents`. Extracting in the download folder or other user folders may cause permission issues. > [!IMPORTANT] > We strongly recommend you configure the agent from an elevated PowerShell window. @@ -94,40 +92,53 @@ If you aren't sure which version of Windows is installed, [follow these instruct > [!Note] -> Please avoid using mintty based shells, such as git-bash, for agent configuration. Mintty is not fully compatible with native Input/Output Windows API ([here](https://github.com/mintty/mintty/wiki/Tips#inputoutput-interaction-with-alien-programs) is some info about it) and we couldn't guarantee correct work of setup script in this case. +> Please avoid using mintty based shells, such as git-bash, for agent configuration. Mintty is not fully compatible with native Input/Output Windows API ([here](https://github.com/mintty/mintty/wiki/Tips#inputoutput-interaction-with-alien-programs) is some info about it) and we can't guarantee the setup script will work correctly in this case. + +## Install the agent + +1. Start an elevated (PowerShell) window and set the location to where you unpacked the agent. + + ```ps + cd C:\agents -### Server URL and authentication +1. Run `config.cmd`. This will ask you a series of questions to configure the agent. + + ```ps + .\config.cmd + +### Server URL + +:::moniker range="azure-devops" When setup asks for your server URL, for Azure DevOps Services, answer `https://dev.azure.com/{your-organization}`. +:::moniker-end + +:::moniker range=" [!NOTE] -> When using PAT as the authentication method, the PAT token is only used during the initial configuration of the agent. Later, if the PAT expires or needs to be renewed, no further changes are required by the agent. +:::moniker-end -::: moniker range="< azure-devops" -> [!IMPORTANT] -> -> Make sure your server is [configured to support the authentication method](agents.md#configure-tfs-authentication) you want to use. - -When you configure your agent to connect to TFS, you've got the following options: +### Agent setup authentication type -* **Alternate** Connect to TFS using Basic authentication. After you select Alternate you'll be prompted for your credentials. +When you register an agent, choose from the following authentication types, and setup will prompt you for the specific additional information required for each authentication type. For more information, see [Self-hosted agent authentication options](./agent-authentication-options.md). -* **Negotiate** Connect to TFS as a user other than the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. After you select Negotiate you'll be prompted for credentials. +[!INCLUDE [agent-setup-authentication-type](./includes/agent-setup-authentication.md)] -* **Integrated** (Default) Connect a Windows agent to TFS using the credentials of the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. You won't be prompted for credentials after you choose this method. - -* **PAT** Supported only on Azure Pipelines and TFS 2017 and newer. After you choose PAT, paste the [PAT token you created](#permissions) into the command prompt window. Use a personal access token (PAT) if your TFS instance and the agent machine are not in a trusted domain. PAT authentication is handled by your TFS instance instead of the domain controller. +:::moniker range="<= azure-devops-2022" -> [!NOTE] -> When using PAT as the authentication method, the PAT token is used only for the initial configuration of the agent. If the PAT needs to be regenerated, no further changes are needed to the agent. +Windows agents have the following two additional authentication options on Azure DevOps Server and TFS. -Learn more at [Communication with Azure Pipelines or TFS](agents.md#communication). +* [**Negotiate**](./agent-authentication-options.md#negotiate) Connect to TFS as a user other than the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. After you select Negotiate you'll be prompted for credentials. +* [**Integrated**](./agent-authentication-options.md#integrated) (Default) Connect a Windows agent to TFS using the credentials of the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. You won't be prompted for credentials after you choose this method. -::: moniker-end +> [!IMPORTANT] +> Your server must be [configured to support the authentication method](agents.md#configure-tfs-authentication) to use Alternate, Negotiate, or Integrated authentication. + +:::moniker-end + +The authentication method used for registering the agent is used only during agent registration. To learn more about how agents communicate with Azure Pipelines after registration, see [Communication with Azure Pipelines or TFS](agents.md#communication). ### Choose interactive or service mode @@ -139,18 +150,32 @@ If you choose to run as a service (which we recommend), the username you run as ### Run interactively -If you configured the agent to run interactively, to run it: +If you configured the agent to run interactively, run the following the command to start the agent. ```ps .\run.cmd ``` -To restart the agent, press Ctrl+C to stop the agent and then run `run.cmd` to restart it. +To restart the agent, press Ctrl+C to stop the agent, and then run `run.cmd` to restart it. + +> [!NOTE] +> If you are running the agent from PowerShell Core to execute Windows PowerShell tasks, your pipeline may fail with an error such as `Error in TypeData "System.Security.AccessControl.ObjectSecurity": The member is already present`. This is because +> Windows PowerShell inherits the `PSModulePath` environment variable, which includes PowerShell Core module locations, from its parent process. +> +> As a workaround, you can set the agent's knob `AZP_AGENT_CLEANUP_PSMODULES_IN_POWERSHELL` to `true` in the pipeline. This will allow the agent to reset `PSModulePath` +> before executing tasks. +> +> ```yml +> variables: +> AZP_AGENT_CLEANUP_PSMODULES_IN_POWERSHELL: "true" +> ``` +> +> If this workaround does not resolve your issue, or if you need to use custom module locations, you can set the `$Env:PSModulePath` variable as needed in your PowerShell Core window before running the agent. -### Run once +#### Run once -For agents configured to run interactively, you can choose to have the agent accept only one job. -To run in this configuration: +You can also choose to have the agent accept only one job and then exit. +To run in this configuration, use the following command. ```ps .\run.cmd --once @@ -161,22 +186,30 @@ Agents in this mode will accept only one job and then spin down gracefully (usef ### Run as a service If you configured the agent to run as a service, it starts automatically. You can view and control the agent running status from the services snap-in. Run `services.msc` and look for one of: -- "Azure Pipelines Agent (*name of your agent*)". -- "VSTS Agent (*name of your agent*)". -- "vstsagent.(*organization name*).(*name of your agent*)". +- "Azure Pipelines Agent (*name of your agent*)" +- "VSTS Agent (*name of your agent*)" +- "vstsagent.(*organization name*).(*name of your agent*)" + +> [!Note] +> To allow more flexibility with access control of an agent running as a service it +> is possible to set up the agent service SID type as [`SERVICE_SID_TYPE_UNRESTRICTED`] via +> flag or prompt during interactive configuration flow. +> By default, the agent service is configured with `SERVICE_SID_TYPE_NONE`. +> +> For more details about [SID](/windows-server/identity/ad-ds/manage/understand-security-identifiers) types please check this [documentation](/windows/win32/api/winsvc/ns-winsvc-service_sid_info#members). To restart the agent, right-click the entry and choose **Restart**. > [!Note] > If you need to change the agent's logon account, don't do it from the Services -> snap-in. Instead, see the information below to re-configure the agent. +> snap-in. Instead, see the information below to reconfigure the agent. To use your agent, run a [job](../process/phases.md) using the agent's pool. If you didn't choose a different pool, your agent will be in the **Default** pool. [!INCLUDE [include](includes/v3/replace-agent.md)] -## Remove and re-configure an agent +## Remove and reconfigure an agent To remove the agent: @@ -233,8 +266,6 @@ The help provides information on authentication alternatives and unattended conf [!INCLUDE [include](includes/system-prefer-git-from-path.md)] -[!INCLUDE [include](includes/v3/qa-agent-version.md)] - [!INCLUDE [include](includes/v3/qa-agent-version.md)] @@ -245,6 +276,9 @@ The help provides information on authentication alternatives and unattended conf ### How do I run the agent with self-signed certificate? +> [!NOTE] +> Running the agent with a self-signed certificate only applies to Azure DevOps Server. + [Run the agent with self-signed certificate](certificate.md) ### How do I run the agent behind a web proxy? @@ -253,7 +287,7 @@ The help provides information on authentication alternatives and unattended conf ### How do I restart the agent -If you are running the agent interactively, see the restart instructions in [Run interactively](#run-interactively). If you are running the agent as a service, restart the agent by following the steps in [Run as a service](#run-as-a-service). +If you're running the agent interactively, see the restart instructions in [Run interactively](#run-interactively). If you're running the agent as a service, restart the agent by following the steps in [Run as a service](#run-as-a-service). ::: moniker range=">=azure-devops-2020" ### How do I set different environment variables for each individual agent? diff --git a/docs/pipelines/apps/aspnet/build-aspnet-4.md b/docs/pipelines/apps/aspnet/build-aspnet-4.md index b44c971dd97..d2097acb828 100644 --- a/docs/pipelines/apps/aspnet/build-aspnet-4.md +++ b/docs/pipelines/apps/aspnet/build-aspnet-4.md @@ -1,10 +1,10 @@ --- -title: .NET Framework -description: Use .NET Framework to build ASP.NET apps in Azure Pipelines +title: Build apps with .NET Framework +description: Use .NET Framework to build ASP.NET apps in Azure Pipelines. ms.topic: conceptual ms.assetid: 840F4B48-D9F1-4B5F-98D9-00945501FA98 -ms.custom: seodec18, devx-track-dotnet -ms.date: 01/09/2023 +ms.custom: devx-track-dotnet +ms.date: 10/16/2024 monikerRange: '<= azure-devops' --- @@ -12,115 +12,174 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" +This article describes how to build a .NET Framework project with Azure Pipelines. For .NET Core projects, see [Build, test, and deploy .NET Core apps](../../ecosystems/dotnet-core.md). -[!INCLUDE [temp](../../includes/concept-rename-note.md)] +## Create an Azure DevOps project -::: moniker-end +1. In your Azure DevOps organization or collection, select **New project** or **Create project**. +1. Enter a **Project name**. +1. Select the **Visibility** for your project. +1. Select **Create**. -> [!NOTE] -> -> This article focuses on building .NET Framework projects with Azure Pipelines. For help with .NET Core projects, see [.NET Core](../../ecosystems/dotnet-core.md). -## Create your first pipeline +## Get the sample app -::: moniker range=">=azure-devops-2020" +The sample app is a Visual Studio solution that uses .NET 4.8. To get the app, fork the GitHub repo at: -> Are you new to Azure Pipelines? If so, then we recommend you try this section before moving on to other sections. +``` html +https://github.com/Azure-Samples/app-service-web-dotnet-get-started -::: moniker-end +``` -### Get the code +## Create and build the pipeline -::: moniker range=">=azure-devops-2020" +Once you have the sample code in your own repository, create a pipeline in your Azure DevOps project by using the instructions in [Create your first pipeline](../../create-first-pipeline.md). -[!INCLUDE [include](../../ecosystems/includes/get-code-before-sample-repo.md)] +Select the **ASP.NET** template. This choice automatically adds the *azure-pipelines.yml* file with the tasks required to build the code to the sample repository. The template includes the VSTest@2 task to run tests. The sample repository doesn't contain tests, so you can remove the VSTest@2 task from the pipeline. -::: moniker-end +Your pipeline should look like the following example: -::: moniker range="azure-devops-2019" +::: moniker range="azure-devops" -Import this repo into your Git repo in Azure DevOps Server 2019: +```yaml +# ASP.NET +# Build and test ASP.NET projects. +# Add steps that publish symbols, save build artifacts, deploy, and more: +# https://docs.microsoft.com/azure/devops/pipelines/apps/aspnet/build-aspnet-4 -::: moniker-end +trigger: +- main -::: moniker range="< azure-devops-2019" +pool: + vmImage: 'windows-latest' -Import this repo into your Git repo in TFS: +variables: + solution: '**/*.sln' + buildPlatform: 'Any CPU' + buildConfiguration: 'Release' -::: moniker-end +steps: +- task: NuGetToolInstaller@1 + +- task: NuGetCommand@2 + inputs: + restoreSolution: '$(solution)' + +- task: VSBuild@1 + inputs: + solution: '$(solution)' + msbuildArgs: '/p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:PackageLocation="$(build.artifactStagingDirectory)"' + platform: '$(buildPlatform)' + configuration: '$(buildConfiguration)' ``` -https://github.com/Azure-Samples/app-service-web-dotnet-get-started -``` - -The sample app is a Visual Studio solution that uses .NET 4.8. +::: moniker-end +::: moniker range="< azure-devops" -::: moniker range=">=azure-devops-2020" +```yaml +# ASP.NET +# Build and test ASP.NET projects. +# Add steps that publish symbols, save build artifacts, deploy, and more: +# https://docs.microsoft.com/azure/devops/pipelines/apps/aspnet/build-aspnet-4 -### Sign in to Azure Pipelines +trigger: +- main + +pool: + name: default + +variables: + solution: '**/*.sln' + buildPlatform: 'Any CPU' + buildConfiguration: 'Release' + +steps: +- task: NuGetToolInstaller@1 + +- task: NuGetCommand@2 + inputs: + restoreSolution: '$(solution)' -[!INCLUDE [include](../../ecosystems/includes/sign-in-azure-pipelines.md)] +- task: VSBuild@1 + inputs: + solution: '$(solution)' + msbuildArgs: '/p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:PackageLocation="$(build.artifactStagingDirectory)"' + platform: '$(buildPlatform)' + configuration: '$(buildConfiguration)' -[!INCLUDE [include](../../ecosystems/includes/create-project.md)] +``` ::: moniker-end +Select **Save and run** and select **Jobs** to see the pipeline in action. + +To publish the build artifacts, add the following task to the end of your YAML file: + +::: moniker range="azure-devops" + +```yaml +- task: PublishPipelineArtifact@1 + inputs: + targetPath: '$(Pipeline.Workspace)' + artifact: 'myartifact' + publishLocation: 'pipeline' +``` -::: moniker range="< azure-devops" -> [!NOTE] -> This scenario works on TFS, but some of the following instructions might not exactly match the version of TFS that you are using. Also, you'll need to set up a self-hosted agent, possibly also installing software. If you are a new user, you might have a better learning experience by trying this procedure out first using a free Azure DevOps organization. Then change the selector in the upper-left corner of this page from Team Foundation Server to **Azure DevOps**. ::: moniker-end -* After you have the sample code in your own repository, create a pipeline using the instructions in [Create your first pipeline](../../create-first-pipeline.md) and select the **ASP.NET** template. This automatically adds the tasks required to build the code in the sample repository. +::: moniker range="< azure-devops" + +```yaml + +- task: PublishBuildArtifacts@1 + inputs: + pathToPublish: '$(Build.ArtifactStagingDirectory)' + artifactName: drop + +``` +::: moniker-end -* Save the pipeline and queue a build to see it in action. ## Build environment -::: moniker range=">=azure-devops-2020" +::: moniker range=">=azure-devops" -You can use Azure Pipelines to build your .NET Framework projects without needing to set up any infrastructure of your own. The [Microsoft-hosted agents](../../agents/hosted.md) in Azure Pipelines have several released versions of Visual Studio pre-installed to help you build your projects. -* Use `windows-2022` for Windows Server 2022 with Visual Studio 2022 +You can use Azure Pipelines to build your .NET Framework projects without needing to set up any infrastructure of your own. The [Microsoft-hosted agents](../../agents/hosted.md) in Azure Pipelines have several released versions of Visual Studio preinstalled to help you build your projects. Use `windows-2022` for Windows Server 2022 with Visual Studio 2022. -You can also use a [self-hosted agent](../../agents/agents.md#install) to run your builds. This is helpful if you have a large repository and you want to avoid downloading the source code to a fresh machine for every build. +You can also use a [self-hosted agent](../../agents/agents.md#install) to run your builds. Using a self-hosted agent is helpful if you have a large repository and you want to avoid downloading the source code to a fresh machine for every build. ::: moniker-end ::: moniker range="< azure-devops" -Your builds run on a [self-hosted agent](../../agents/agents.md#install). -Make sure that you have the necessary version of the Visual Studio installed on the agent. +Your builds run on a [self-hosted agent](../../agents/agents.md#install). Make sure that you have the necessary version of Visual Studio installed on the agent. -## Build multiple configurations +::: moniker-end -It is often required to build your app in multiple configurations. The following steps extend the example above to build the app on four configurations: [Debug, x86], [Debug, x64], [Release, x86], [Release, x64]. +## Build multiple configurations -1. Click the **Variables** tab and modify these variables: +You might need to build your app in multiple configurations. The following steps build the example app on four configurations: `Debug, x86`, `Debug, x64`, `Release, x86`, and `Release, x64`. - * `BuildConfiguration` = `debug, release` - * `BuildPlatform` = `x86, x64` +1. In the pipeline UI, select the **Variables** tab and modify the following variables: -2. Select **Tasks** and click on the **agent job** to change the options for the job: + - `BuildConfiguration` = `debug, release` + - `BuildPlatform` = `x86, x64` - * Select **Multi-configuration**. - * Specify **Multipliers:** `BuildConfiguration, BuildPlatform` +1. Select **Tasks** and then select **agent job** to change the following options for the job: -3. Select **Parallel** if you have multiple build agents and want to build your configuration/platform pairings in parallel. -::: moniker-end + - Select **Multi-configuration**. + - Specify **Multipliers:** `BuildConfiguration, BuildPlatform` -::: moniker range=">=azure-devops-2020" +1. Select **Parallel** if you have multiple build agents and want to build your configuration/platform pairings in parallel. ## Restore dependencies -You can use the [NuGet task](/azure/devops/pipelines/tasks/reference/nuget-command-v2) to install and update NuGet package dependencies. -You can also download NuGet packages from Azure Artifacts, NuGet.org, or some other external or internal NuGet repository with the NuGet task. +You can use the [NuGet task](/azure/devops/pipelines/tasks/reference/nuget-command-v2) to install and update NuGet package dependencies. You can also use the NuGet task to download NuGet packages from Azure Artifacts, NuGet.org, or other external or internal NuGet repositories. -This code restores a solution from a project-scoped feed in the same organization. +The following example restores a solution from a project-scoped feed in the same organization. ```yaml -# Restore from a project scoped feed in the same organization - task: NuGetCommand@2 inputs: command: 'restore' @@ -130,4 +189,11 @@ This code restores a solution from a project-scoped feed in the same organizatio restoreSolution: '**/*.sln' ``` -::: moniker-end +> [!NOTE] +> If you're using Ubuntu 24.04 or higher, you must use the `NuGetAuthenticate` task with the .NET CLI instead of the `NuGetCommand@2` task. See [Support for newer Ubuntu hosted images](/azure/devops/pipelines/tasks/reference/nuget-command-v2#support-for-newer-ubuntu-hosted-images) for more details. + +## Related content + +- [Publish NuGet packages with Azure Pipelines](../../artifacts/nuget.md) +- [Quickstart: Get started with NuGet packages in Azure Artifacts](../../../artifacts/get-started-nuget.md) +- [Azure Pipelines agents](../../agents/agents.md#install) \ No newline at end of file diff --git a/docs/pipelines/apps/c-cpp/gcc.md b/docs/pipelines/apps/c-cpp/gcc.md deleted file mode 100644 index 6e799130a18..00000000000 --- a/docs/pipelines/apps/c-cpp/gcc.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Build your GCC C/C++ app -ms.custom: seodec18 -description: Learn how you can use continuous integration in Azure Pipelines to automatically build your GCC C/C++ app. -ms.assetid: 73a50551-0c2c-4d62-b582-6ba7ba51509e -ms.date: 04/04/2022 -ms.topic: quickstart -monikerRange: '<= azure-devops' ---- - -# Build your GCC C/C++ app - -[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] - - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../includes/concept-rename-note.md)] -::: moniker-end - -Azure Pipelines provides a highly customizable continuous integration (CI) pipeline to automatically build your C/C++ application whenever your team pushes or checks in code. In this quickstart you learn how to define your CI pipeline for a C/C++ application compiled with GCC/g++. - -## Prerequisites - -* You need an Azure DevOps organization. If you don't have one, you can [create one for free](https://go.microsoft.com/fwlink/?LinkId=307137). If your team already has one, then make sure you're an administrator of the Azure DevOps project that you want to use. (An Azure DevOps organization is different from your GitHub organization. Give them the same name if you want alignment between them.) - -* While the simplest way to try this quickstart is to use an Azure DevOps organization, you can also use a TFS server instead of an Azure DevOps organization. Make sure that you have [configured a build agent](../../agents/agents.md) for your project, and that you have GCC installed on the agent machine. - -## Get sample app code - -[!INCLUDE [include](../includes/get-sample-code-intro.md)] - -``` -https://github.com/adventworks/cpp-gpp-sample -``` - -# [Azure Repos](#tab/vsts) - -[!INCLUDE [include](../includes/get-sample-code-repos-update-2.md)] - -# [GitHub repo](#tab/github) - -[!INCLUDE [include](../includes/get-sample-code-github.md)] - ---- - -## Set up continuous integration - -[!INCLUDE [include](../../includes/ci-quickstart-intro.md)] - -[//]: # (TODO: Restore use of includes when we get support for using them in a list.) - -1. Create a new build pipeline. - - # [Azure Repos or TFS repo](#tab/vsts) - - Under the **Build and Release** menu, select **Builds** then **New** to create a new build definition. - - :::image type="content" source="../media/set-up-first-build.png" alt-text="Create a new build definition for a repository"::: - - Select a source and chose your team project, repository, and default branch then select **Continue**. - - **Select a template** or start with an **Empty process** to create your build pipeline. - - # [GitHub repo](#tab/github) - - Navigate to the **Builds** tab in Azure Pipelines or TFS, and then click **+ New**. You are asked to **Select a template** for the new build pipeline. - - --- - -2. In the right panel, select **Empty**, and then click **Apply**. This template allows starting from scratch and adding your own build tasks. - -3. For the **Agent pool**: - - * **Azure Pipelines:** Select _Hosted Ubuntu 1604_ or _Hosted macOS_. This uses an Azure Pipelines pool of agents that have the software needed to build your app. - - * **TFS:** Select a pool that includes a [Linux or macOS build agent](../../agents/agents.md). - -4. Click **Get sources** and then: - - # [Azure Repos or TFS repo](#tab/vsts) - - Observe that the new build pipeline is automatically linked to your repository. - - # [GitHub repo](#tab/github) - - Select your version control repository. You'll need to authorize access to your repo. - -5. Click the **+** icon on **Job 1** of the build and then: - -::: moniker range=">= tfs-2018" - - ### Azure Pipelines and TFS 2018 - - 1. Search for the **Shell Script** task and click **Add** to add it to your build. - - 1. Click the **Shell Script** task and set its field values as follows: - - Field | Value - ------- | ----- - Version | `3.*` or later - Type | `Inline` - Script | `make` - -::: moniker-end - - ### Finish - -1. Click the **Triggers** tab and enable the **Continuous Integration** trigger. This will ensure that the build pipeline is automatically triggered every time you commit a change to your repository. - -1. Click **Save & queue** to kick off your first build. On the **Save build pipeline and queue** dialog box, click **Save & queue**. - -1. A new build is started. You'll see a link to the new build on the top of the page. Click the link to watch the new build as it happens. - -[//]: # (TODO:> [!TIP]) -[//]: # (TODO:> To learn more about GitHub CI builds, see [Define CI build pipeline for your Git repo](#) - -## View the build summary - -[!INCLUDE [include](../includes/view-build-summary.md)] - -## Publish your build output - -Add the [Copy Files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish Build Artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks to your build to save its compiled output as a build artifact. - -## Next steps - -[!INCLUDE [include](../includes/ci-web-app-next-steps.md)] diff --git a/docs/pipelines/apps/cd/azure/build-data-pipeline.md b/docs/pipelines/apps/cd/azure/build-data-pipeline.md index b15edd13a96..31faedeb46a 100644 --- a/docs/pipelines/apps/cd/azure/build-data-pipeline.md +++ b/docs/pipelines/apps/cd/azure/build-data-pipeline.md @@ -4,8 +4,8 @@ description: Learn how to use an Azure CI/CD data pipeline to ingest, process, a ms.author: jukullam author: JuliaKM ms.subservice: azure-devops-pipelines-apps -ms.custom: devx-track-azurecli, devx-track-arm-template -ms.date: 06/20/2023 +ms.custom: devx-track-azurecli, devx-track-arm-template, arm2024 +ms.date: 10/30/2024 ms.topic: how-to monikerRange: '=azure-devops' --- @@ -150,9 +150,9 @@ To make commands easier to run, start by selecting a default region. After you s --name data-factory-cicd-dev \ --resource-group $rgName ``` - 3. Copy the subscription ID. Your data factory will use this ID later. + 3. Copy the subscription ID. Your data factory uses this ID later. -1. [Create a second data factory](https://ms.portal.azure.com/#create/hub) by using the portal UI or the Azure CLI. You'll use this data factory for testing. +1. [Create a second data factory](https://ms.portal.azure.com/#create/hub) by using the portal UI or the Azure CLI. You use this data factory for testing. * Name: `data-factory-cicd-test` * Version: `V2` @@ -169,7 +169,7 @@ To make commands easier to run, start by selecting a default region. After you s --resource-group $rgName ``` - 2. Copy the subscription ID. Your data factory will use this ID later. + 2. Copy the subscription ID. Your data factory uses this ID later. 1. [Add a new Azure Databricks service](https://ms.portal.azure.com/#create/hub): * Resource group: `data-pipeline-cicd-rg` @@ -190,7 +190,7 @@ To make commands easier to run, start by selecting a default region. After you s --location eastus2 \ --sku trial ``` - 3. Copy the subscription ID. Your Databricks service will use this ID later. + 3. Copy the subscription ID. Your Databricks service uses this ID later. ## Upload data to your storage container @@ -202,7 +202,7 @@ To make commands easier to run, start by selecting a default region. After you s ## Set up Key Vault -You'll use Azure Key Vault to store all connection information for your Azure services. +You use Azure Key Vault to store all connection information for your Azure services. ### Create a Databricks personal access token 1. In the Azure portal, go Databricks and then open your workspace. @@ -234,10 +234,11 @@ You'll use Azure Key Vault to store all connection information for your Azure se ## Add an Azure Resource Manager service connection 1. Create an Azure Resource Manager [service connection](../../../library/service-endpoints.md). -1. Select **Service Principal (automatic)**. +1. Select **App registration (automatic)** and **Workload identity federation**. +1. Select your subscription. 1. Choose the **data-pipeline-cicd-rg** resource group. 1. Name the service connection `azure_rm_connection`. -1. Select **Grant access permission to all pipelines**. You'll need to have the Service Connections Administrator role to select this option. +1. Select **Grant access permission to all pipelines**. You need to have the Service Connections Administrator role to select this option. ## Add pipeline variables @@ -269,8 +270,8 @@ You'll use Azure Key Vault to store all connection information for your Azure se "STORAGE_CONTAINER_NAME=rawdata" ``` -1. Create a second variable group named `keys-vg`. This group will pull data variables from Key Vault. -1. Select **Link secrets from an Azure key vault as variables**. For more information, see [Link secrets from an Azure key vault](../../../library/variable-groups.md#link-secrets-from-an-azure-key-vault). +1. Create a second variable group named `keys-vg`. This group pulls data variables from Key Vault. +1. Select **Link secrets from an Azure key vault as variables**. For more information, see [Link a variable group to secrets in Azure Key Vault](../../../library/link-variable-groups-to-key-vaults.md). 1. Authorize the Azure subscription. 1. Choose all of the available secrets to add as variables (`databricks-token`,`StorageConnectString`,`StorageKey`). @@ -342,7 +343,7 @@ Follow these steps to run the continuous integration and continuous delivery (CI 1. Select **Azure Repos Git** as the location of your source code. 1. When the list of repositories appears, select your repository. 1. As you set up your pipeline, select **Existing Azure Pipelines YAML file**. Choose the YAML file: **/azure-data-pipeline/data_pipeline_ci_cd.yml**. -1. Run the pipeline. If your pipeline hasn't been run before, you might need to give permission to access a resource during the run. +1. Run the pipeline. When running your pipeline for the first time, you might need to give permission to access a resource during the run. ## Clean up resources diff --git a/docs/pipelines/apps/cd/azure/cicd-data-overview.md b/docs/pipelines/apps/cd/azure/cicd-data-overview.md index 594c1d9ebb8..f4f7a40112e 100644 --- a/docs/pipelines/apps/cd/azure/cicd-data-overview.md +++ b/docs/pipelines/apps/cd/azure/cicd-data-overview.md @@ -1,43 +1,49 @@ --- -title: Overview of CI/CD data pipelines on Microsoft Azure -description: Learn why to use a CI/CD data pipeline to ingest, process, and share data +title: CI/CD data pipelines in Azure +description: Learn about continuous integration and continuous delivery (CI/CD) pipelines that ingest, process, and share data in Azure. ms.subservice: azure-devops-pipelines-apps ms.topic: conceptual ms.author: jukullam author: JuliaKM -ms.date: 01/26/2023 +ms.date: 07/15/2024 monikerRange: '=azure-devops' --- -# Why data pipelines? +# Azure CI/CD data pipelines [!INCLUDE [version-eq-azure-devops](../../../../includes/version-eq-azure-devops.md)] +This article explains Azure continuous integration and continuous delivery (CI/CD) data pipelines and their importance for data science. + You can use data pipelines to: -* Ingest data from various data sources -* Process and transform the data -* Save the processed data to a staging location for others to consume -![Data pipeline overview](media/data-pipeline-overview.png) +- Ingest data from various data sources. +- Process and transform the data. +- Save the processed data to a staging location for others to consume. + +![Diagram that shows a data pipeline overview.](media/data-pipeline-overview.png) -Data pipelines in the enterprise can evolve into more complicated scenarios with multiple source systems and supporting various downstream applications. +Enterprise data pipelines can evolve into more complicated scenarios with multiple source systems and various supported downstream applications. Data pipelines provide: -* Consistency: Data pipelines transform data into a consistent format for users to consume -* Error reduction: Automated data pipelines eliminate human errors when manipulating data -* Efficiency: Data professionals save time spent on data processing transformation. Saving time allows then to focus on their core job function - getting the insight out of the data and helping business makes better decisions -## What is CI/CD? -Continuous integration and continuous delivery (CI/CD) is a software development approach where all developers work together on a shared repository of code – and as changes are made, there are automated build process for detecting code issues. The outcome is a faster development life cycle and a lower error rate. +- Consistency, by transforming data into a consistent format for users to consume. +- Error reduction, by using automated data pipelines to eliminate human errors when manipulating data. +- Efficiency, by reducing time spent on data processing transformation. + +Data pipelines let data professionals focus on their core job functions, getting insights from the data and helping businesses make better decisions. + +## Continuous integration and continuous delivery (CI/CD) + +Continuous integration and continuous delivery (CI/CD) is a software development approach where all developers work together in a shared code repository of code. As developers make changes, automated processes detect code issues. The outcome of using CI/CD is a faster development lifecycle with lower error rates. -## What is a CI/CD data pipeline and why does it matter for data science? -The building of machine learning models is similar to traditional software development in the sense that the data scientist needs to write code to train and score machine learning models. +## CI/CD data pipelines in data science -Unlike traditional software development where the product is based on code, data science machine learning models are based on both the code (algorithm, hyper parameters) and the data used to train the model. That’s why most data scientists will tell you that they spend 80% of the time doing data preparation, cleaning and feature engineering. +Building machine learning models is similar to traditional software development in that data scientists write code to train and score machine learning models. But unlike traditional software based on code, data science machine learning models are based on both code, such as algorithms and hyperparameters, and the data used to train the models. Most data scientists say they spend 80% of their time doing data preparation, cleaning, and feature engineering. -To complicate the matter even further – to ensure the quality of the machine learning models, techniques such as A/B testing are used. With A/B testing, there could be multiple machine learning models being used concurrently. There's usually one control model and one or more treatment models for comparison – so that the model performance can be compared and maintained. Having multiple models adds another layer of complexity for the CI/CD of machine learning models. +To ensure the quality of machine learning models, techniques such as A/B testing are also used to compare and maintain model performance. A/B testing usually uses one control model and one or more treatment models. -Having a CI/CD data pipeline is crucial for the data science team to deliver the machine learning models to the business in a timely and quality manner. +Multiple machine learning models might be used concurrently, adding another layer of complexity for the CI/CD of machine learning models. A CI/CD data pipeline is crucial for the data science team to deliver quality machine learning models to the business in a timely manner. ## Next steps > [!div class="nextstepaction"] diff --git a/docs/pipelines/apps/cd/azure/deploy-arm-template.md b/docs/pipelines/apps/cd/azure/deploy-arm-template.md index 297b7782daf..e663b36a3a6 100644 --- a/docs/pipelines/apps/cd/azure/deploy-arm-template.md +++ b/docs/pipelines/apps/cd/azure/deploy-arm-template.md @@ -6,7 +6,7 @@ ms.author: jukullam author: JuliaKM ms.date: 02/22/2022 monikerRange: '=azure-devops' -ms.custom: subject-armqs, contperf-fy21q2, devx-track-arm-template +ms.custom: subject-armqs, devx-track-arm-template, arm2024, linux-related-content --- # Quickstart: Use an ARM template to deploy a Linux web app to Azure @@ -70,7 +70,14 @@ The template defines several resources: 6. Replace the content of your pipeline with this code: - :::code language="yml" source="~/../snippets/pipelines/azure/arm-template.yml" range="4-8"::: + ```yaml + trigger: + - none + + pool: + vmImage: 'ubuntu-latest' + ``` + 7. Create three variables: `siteName`, `administratorLogin`, and `adminPass`. `adminPass` needs to be a secret variable. * Select **Variables**. @@ -86,12 +93,36 @@ The template defines several resources: 8. Map the secret variable `$(adminPass)` so that it is available in your Azure Resource Group Deployment task. At the top of your YAML file, map `$(adminPass)` to `$(ARM_PASS)`. - :::code language="yml" source="~/../snippets/pipelines/azure/arm-template.yml" range="1-8" highlight="1-2"::: - + ```yaml + variables: + ARM_PASS: $(adminPass) + + trigger: + - none + + pool: + vmImage: 'ubuntu-latest' + ``` 9. Add the Copy Files task to the YAML file. You will use the `101-webapp-linux-managed-mysql` project. For more information, see [Build a Web app on Linux with Azure database for MySQL](https://github.com/Azure/azure-quickstart-templates/tree/master/quickstarts/microsoft.web/webapp-linux-managed-mysql) repo for more details. - :::code language="yml" source="~/../snippets/pipelines/azure/arm-template.yml" range="1-15" highlight="10-15"::: + ```yaml + variables: + ARM_PASS: $(adminPass) + + trigger: + - none + + pool: + vmImage: 'ubuntu-latest' + + steps: + - task: CopyFiles@2 + inputs: + SourceFolder: 'quickstarts/microsoft.web/webapp-linux-managed-mysql/' + Contents: '**' + TargetFolder: '$(Build.ArtifactStagingDirectory)' + ``` 10. Add and configure the **Azure Resource Group Deployment** task. @@ -109,7 +140,39 @@ The template defines several resources: - **Override template parameters (overrideParameters)**: Set to `-siteName $(siteName) -administratorLogin $(adminUser) -administratorLoginPassword $(ARM_PASS)` to use the variables you created earlier. These values will replace the parameters set in your template parameters file. - **Deployment mode (deploymentMode)**: The way resources should be deployed. Set to `Incremental`. Incremental keeps resources that are not in the ARM template and is faster than `Complete`. `Validate` mode lets you find problems with the template before deploying. - :::code language="yml" source="~/../snippets/pipelines/azure/arm-template.yml" range="1-29" highlight="17-29"::: + + ```yaml + variables: + ARM_PASS: $(adminPass) + + trigger: + - none + + pool: + vmImage: 'ubuntu-latest' + + steps: + - task: CopyFiles@2 + inputs: + SourceFolder: 'quickstarts/microsoft.web/webapp-linux-managed-mysql/' + Contents: '**' + TargetFolder: '$(Build.ArtifactStagingDirectory)' + + - task: AzureResourceManagerTemplateDeployment@3 + inputs: + deploymentScope: 'Resource Group' + azureResourceManagerConnection: '' + subscriptionId: '' + action: 'Create Or Update Resource Group' + resourceGroupName: 'ARMPipelinesLAMP-rg' + location: '' + templateLocation: 'Linked artifact' + csmFile: '$(Build.ArtifactStagingDirectory)/azuredeploy.json' + csmParametersFile: '$(Build.ArtifactStagingDirectory)/azuredeploy.parameters.json' + overrideParameters: '-siteName $(siteName) -administratorLogin $(adminUser) -administratorLoginPassword $(ARM_PASS)' + deploymentMode: 'Incremental' + ``` + 11. Click **Save and run** to deploy your template. The pipeline job will be launched and after few minutes, depending on your agent, the job status should indicate `Success`. @@ -133,7 +196,14 @@ The template defines several resources: 1. Replace the content of your pipeline with this code: - :::code language="yml" source="~/../snippets/pipelines/azure/arm-template-bicep.yml" range="8-12"::: + ```yaml + trigger: + - none + + pool: + vmImage: $(vmImageName) + ``` + 1. Create three variables: `siteName`, `administratorLogin`, and `administratorLoginPassword`. `administratorLoginPassword` needs to be a secret variable. * Select **Variables**. @@ -149,7 +219,15 @@ The template defines several resources: 1. At the top of your YAML file, map values for `location` and `resourceGroupName`. Your location should be the location of the resource group. Your resource group needs to already exist. - :::code language="yml" source="~/../snippets/pipelines/azure/arm-template-bicep.yml" range="1-6" highlight="3-4"::: + ```yaml + variables: + vmImageName: 'ubuntu-latest' + resourceGroupName: '' # Needs to already exist + location: '' + templateFile: './main.bicep' + sourceFolder: 'quickstarts/microsoft.web/webapp-linux-managed-mysql/' + ``` + 1. If you do not already have an Azure Resource Manager service connection, [create a service connection](../../../library/service-endpoints.md#create-a-service-connection). Learn more about [connecting to Azure](../../../library/connect-to-azure.md). * The service connection be in the same resource group as your `resourceGroupName`. @@ -161,7 +239,33 @@ The template defines several resources: * The **Script Type** is *Shell*. * The Script Location is *Inline script*. - :::code language="yml" source="~/../snippets/pipelines/azure/arm-template-bicep.yml" range="1-24" highlight="17-24"::: + ```yaml + variables: + vmImageName: 'ubuntu-latest' + resourceGroupName: '' # Needs to already exist + location: '' + templateFile: './main.bicep' + sourceFolder: 'quickstarts/microsoft.web/webapp-linux-managed-mysql/' + + trigger: + - none + + pool: + vmImage: $(vmImageName) + + name: Bicep deploy template + + steps: + - task: AzureCLI@2 + inputs: + azureSubscription: '' + scriptType: bash + scriptLocation: inlineScript + inlineScript: | + az deployment group create --resource-group $(resourceGroupName) --template-file $(sourceFolder)$(templateFile) \ + --parameters administratorLogin=$(administratorLogin) administratorLoginPassword=$(administratorLoginPassword) + ``` + --- @@ -202,7 +306,33 @@ ___ You can also use an ARM template to delete resources. Change the `action` value in your **Azure Resource Group Deployment** task to `DeleteRG`. You can also remove the inputs for `templateLocation`, `csmFile`, `csmParametersFile`, `overrideParameters`, and `deploymentMode`. - :::code language="yml" source="~/../snippets/pipelines/azure/arm-template-cleanup.yml" range="1-24" highlight="17-24"::: +```yaml +variables: + ARM_PASS: $(adminPass) + +trigger: +- none + +pool: + vmImage: 'ubuntu-latest' + +steps: +- task: CopyFiles@2 + inputs: + SourceFolder: 'quickstarts/microsoft.web/webapp-linux-managed-mysql/' + Contents: '**' + TargetFolder: '$(Build.ArtifactStagingDirectory)' + +- task: AzureResourceManagerTemplateDeployment@3 + inputs: + deploymentScope: 'Resource Group' + azureResourceManagerConnection: '' + subscriptionId: '' + action: 'DeleteRG' + resourceGroupName: 'ARMPipelinesLAMP-rg' + location: ''' +``` + # [Bicep](#tab/bicep) diff --git a/docs/pipelines/apps/cd/azure/deploy-azure-scaleset.md b/docs/pipelines/apps/cd/azure/deploy-azure-scaleset.md deleted file mode 100644 index 36911df3f58..00000000000 --- a/docs/pipelines/apps/cd/azure/deploy-azure-scaleset.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Deploy apps to an Azure Virtual Machine Scale Set (Classic) -description: Implement deployment of your app to an Azure Virtual Machine Scale Set without learning concepts such as provisioners and builders -ms.assetid: C08EC3FB-6787-4956-86D3-B4085B69FCBA -ms.topic: conceptual -ms.custom: seodec18 -ms.author: atulmal -author: azooinmyluggage -ms.date: 09/07/2021 -monikerRange: '<= azure-devops' ---- - -# Implement continuous deployment of your app to an Azure Virtual Machine Scale Set - -[!INCLUDE [version-lt-eq-azure-devops](../../../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../../includes/concept-rename-note.md)] -::: moniker-end - -The **Build Machine Image** task makes it easy for users who are new to immutable -VHD-based deployments to use **Packer** without learning concepts such as provisioners -and builders. If you are deploying to virtual machines by using deployment scripts, -you can use this task for either creating new virtual machine instances or for -creating and updating virtual machine scale sets. - -The autogenerate mode of the task generates the **Packer** configuration with: - -* Builder for Azure -* Provisioners that depend on the type of base operating system selected. - For Linux, this is shell script. For Windows, this is PowerShell script. - The deployment script provided is used by the provisioner. - -A custom **Packer** configuration JSON file can also be used. - -## Get set up - -### Begin with a CI build - -Before you begin, you need a CI build that creates your app. To set up CI, see: - -* [Build and deploy your app](/previous-versions/azure/devops/pipelines/apps/) - -## Create the release pipeline - -1. Open the **Releases** tab of **Azure Pipelines** and choose the - "**+**" icon to create a new release pipeline. - -1. In the **Create release pipeline** dialog, select the **Empty** template and choose **Next**. - -1. In the next page, select the build pipeline you created - earlier and choose **Create**. This creates a new release pipeline - with one default stage. - -1. In the new release pipeline, select **+ Add tasks** and add these tasks: - - * **Build Machine Image** - * **Azure PowerShell**

      - - The **Build Machine Image** uses **Packer** to create a VHD. The entire process is: - - * Create a new virtual machine with the selected base operating system - * Install all the prerequisites and the application on the VM by using a deployment script - * Create a VHD and store it in the Azure storage account - * Delete the new virtual machine that was created

      - -1. Configure the **Build Machine Image** task as follows: - - ![Build Machine Image](../../../tasks/deploy/media/build-machine-image.png) [Deploy: Build Machine Image](https://devblogs.microsoft.com/devops/deploying-applications-to-azure-vm-scale-sets/) - Build machine image using Packer. - - - **Packer template**: You can use your own packer configuration JSON file or use the autogenerate feature where the task generates a packer template for you. This example uses the autogenerated packer configuration. - - - **Azure subscription**: Select a connection from the list under **Available Azure Service Connections** or create a more restricted permissions - connection to your Azure subscription. For more information, see [Azure Resource Manager service connection](../../../library/connect-to-azure.md). - - - **Storage location**: The location of storage account where the VHD will be stored. This should be the same location where the virtual machine scale set is located, or where it will be created. - - - **Base Image Source**: You can choose from either a curated gallery of OS images, or provide the URL of your custom image. For example, `Ubuntu 16.04 LTS` - - - **Deployment Package**: Specify the path of the deployment package directory relative to **$(System.DefaultWorkingDirectory)**. For example, `$(System.DefaultWorkingDirectory)/Packer-NodeJs/drop` - - - **Deployment Script**: Specify the relative path to the PowerShell script (for Windows) or shell script (for Linux) that deploys the package. This script should be within the deployment package path selected above. For example, `Deploy/ubuntu/deployNodejsApp.sh`. The script may need to install Curl, Node.js, NGINX, and PM2; copy the application; and then configure NGINX and PM2 to run the application. - - - **Output - Image URL**: Provide a name for the output variable that will hold the URL of the generated machine image. For example, `bakedImageUrl`

      - - ![Azure PowerShell](../../../tasks/deploy/media/azure-powershell-icon.png) [Deploy: Azure PowerShell](https://github.com/Microsoft/azure-pipelines-tasks/tree/master/Tasks/AzurePowerShellV3) - Run a PowerShell script to update the Virtual Machine Scale Set with the new VHD. - - - **Azure Connection Type**: Select `Azure Resource Manager` - - - **Azure RM Subscription**: Select a connection from the list under **Available Azure Service Connections** or create a more restricted permissions - connection to your Azure subscription. For more information, see [Azure Resource Manager service connection](../../../library/connect-to-azure.md). - - - **Script type**: Select `Inline Script` - - - **Inline Script**: Enter the script shown below to update the virtual machine scale set.

      - - Use the following script for the **Inline Script** parameter of the **Azure PowerShell** task: - - ```powershell - # get the VMSS model - - $vmss = Get-AzureRmVmss -ResourceGroupName resource_group_name -VMScaleSetName VM_scale_set_name - - # set the new version in the model data - - $vmss.virtualMachineProfile.storageProfile.osDisk.image.uri="$(bakedImageUrl)" - - # update the virtual machine scale set model - - Update-AzureRmVmss -ResourceGroupName resource_group_name -Name resource_group_name -VirtualMachineScaleSet $vmss - ``` - - You can use variables to pass values such as the resource group and virtual machine scale set names to the script if you wish. - -1. In the **Deployment conditions** dialog for the stage, ensure that the **Trigger** section is set to **After release creation**. - -1. Enter a name for the release pipeline and save it. - -1. Create a new release, select the latest build, and - ensure that the application has been deployed correctly and has generated the VHD. - -## FAQ - - - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../../includes/qa-versions.md)] -::: moniker-end - - - - -[!INCLUDE [rm-help-support-shared](../../../includes/rm-help-support-shared.md)] \ No newline at end of file diff --git a/docs/pipelines/apps/cd/azure/deploy-provision-azure-vm.md b/docs/pipelines/apps/cd/azure/deploy-provision-azure-vm.md deleted file mode 100644 index 781689b498a..00000000000 --- a/docs/pipelines/apps/cd/azure/deploy-provision-azure-vm.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Deploy an Azure VM using an RM template -description: Provision Azure virtual machines (VMs) using ARM templates by using Azure Pipelines -ms.assetid: E6CF9C79-4A2A-45EF-8278-EA6AFA81CBAD -ms.topic: conceptual -ms.custom: seodec18 -ms.author: ronai -author: RoopeshNair -ms.date: 09/07/2021 -monikerRange: '<= azure-devops' ---- - -# CD of an Azure virtual machine using a Resource Manager template - -[!INCLUDE [version-lt-eq-azure-devops](../../../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../../includes/concept-rename-note.md)] -::: moniker-end - -In just a few steps, you can provision Azure virtual machines (VMs) -using [Resource Manager (RM) templates](/azure/azure-resource-manager/templates/deploy-powershell). -Managing the pipelines for virtual machines in this -way is considered **Infrastructure as code** and is -a good DevOps practice. - -## Prerequisites - -Before you begin, you need a CI build that creates your Azure RM template. To set up CI, see: - -* [Build an Azure virtual machine using an Azure RM template](./deploy-arm-template.md) - -## Define and test your CD release pipeline - -Carry out the following steps to deploy the Azure Resource Group. - -1. Open the **Releases** tab of **Azure Pipelines** and choose the - "**+**" icon to create a new release pipeline. - -2. In the **Create release pipeline** dialog, select the **Empty** template, and choose **Next**. - -3. In the next page, select the build pipeline you created - earlier and choose **Create**. This creates a new release pipeline - with one default stage. - -4. In the new release pipeline, select **+ Add tasks** and add an **Azure Resource Group Deployment** task. - Optionally edit the name to help identify the task, such as **Provision Windows 2012 R2 VM**. - -5. Configure the **Azure Resource Group Deployment** task as follows: - - ![Azure Resource Group Deployment](../../../tasks/deploy/media/azure-resource-group-deployment-icon.png) [Deploy: Azure Resource Group Deployment](https://github.com/Microsoft/azure-pipelines-tasks/tree/master/Tasks/AzureResourceGroupDeploymentV2) - Deploy files to an Azure Resource Group. - - - **Azure Subscription**: Select a connection from the list under **Available Azure Service Connections** or create a more restricted permissions - connection to your Azure subscription. For more information, see [Azure Resource Manager service connection](../../../library/connect-to-azure.md). - - - **Action**: `Create or Update Resource Group` - - - **Resource Group**: The name for a new resource group, or an existing resource group name. - - - **Template location**: The path of the Resource Manager template; for example:
      `$(System.DefaultWorkingDirectory)\ASPNet4.CI\drop\HelloWorldARM\Templates\WindowsVirtualMachine.json` - - - **Template Parameters**: The path of the Resource Manager template parameters file; for example:
      `$(System.DefaultWorkingDirectory)\ASPNet4.CI\drop\HelloWorldARM\Templates\WindowsVirtualMachine.parameters.json` - - - **Override Template Parameters**: A list of values for the parameters in the template; for example:
      `-adminUsername $(vmuser) -adminPassword (ConvertTo-SecureString -String $(vmpassword) -AsPlainText -Force) -dnsNameForPublicIP $(dns)'`
      Use the **...** button to open the parameters editor dialog. - - - **Enable Deployment Prerequisites**: Checked. - - - **Output - Resource Group**: The name of the Resource Group output from the task as a value that can be used as an input to further deployment tasks.

      - - >Checking the **Enable Deployment Prerequisites** checkbox - configures WinRM on the virtual machine and enables - execution of remote PowerShell scripts, which may be - required to deploy an application. Also notice the use of - **ConvertTo-SecureString** to specify the value for **adminPassword**. - You must do this because **adminPassword** is defined as a **SecureString** - type in the Resource Manager template file. - -6. If you used [variables](../../../release/variables.md) - in the parameters of the **Azure Resource Group Deployment** task, - such as **vmuser**, **vmpassword**, and **dns**, set the values for them in the - stage configuration variables. Encrypt the value - of **vmpassword** by selecting the "padlock" icon. - -7. Enter a name for the release pipeline and save it. - -8. Create a new release, select the latest build, and - deploy it to the single stage. diff --git a/docs/pipelines/apps/cd/azure/deploy-provision-devtest-lab.md b/docs/pipelines/apps/cd/azure/deploy-provision-devtest-lab.md deleted file mode 100644 index 75c8d2829ee..00000000000 --- a/docs/pipelines/apps/cd/azure/deploy-provision-devtest-lab.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: Manage a VM in DevTest Labs -description: Create, manage, and delete Azure virtual machines (VMs) in Azure DevTest Labs in Azure Pipelines and TFS -ms.assetid: 4FC75F92-EC04-4458-8069-53EEBF855D2F -ms.topic: conceptual -ms.custom: seodec18 -ms.author: ronai -author: RoopeshNair -ms.date: 09/07/2021 -monikerRange: '<= azure-devops' ---- - -# Manage a virtual machine in Azure DevTest Labs - -[!INCLUDE [version-lt-eq-azure-devops](../../../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../../includes/concept-rename-note.md)] -::: moniker-end - -The [Azure DevTest Labs](https://azure.microsoft.com/services/devtest-lab/) -service lets you quickly provision development and test stages using reusable -templates. You can use pre-created images, minimize waste with quotas and policies, -and minimize costs by using automated shutdown. - -By using an extension installed in Azure Pipelines, you -can easily integrate your build and release pipeline with Azure DevTest Labs. -The extension installs three tasks to create a VM, create a custom image from -a VM, and delete a VM. This makes it easy to, for example, quickly deploy a -"golden image" for specific test task, then delete it when the test is finished. - -This example shows how to create and deploy a VM, create a custom image, then -delete the VM. It does so as one complete pipeline, though it reality you -would use the tasks individually in your own custom build-test-deploy pipeline. - -## Get set up - -Start by installing the -[Azure DevTest Labs Tasks](https://marketplace.visualstudio.com/items?itemName=ms-azuredevtestlabs.tasks) -extension from Visual Studio Marketplace, Azure DevOps tab: - -* For Azure Pipelines, choose **Install** -* For TFS, choose **Download** and install the extension on your server. - -## Create an Azure RM template - -Carry out these tasks to create the Azure Resource Manager (ARM) template that you can -use to create an Azure Virtual Machine on demand. - -1. Follow the steps in [these documents](/azure/devtest-labs/devtest-lab-overview) - on the Azure website to create an ARM template in your subscription. - -1. Follow the steps in [these documents](/azure/devtest-labs/devtest-lab-overview) - on the Azure website to save the ARM template as a file - on your computer. Name the file **CreateVMTemplate.json**. - -1. Edit the **CreateVMTemplate.json** file to configure it for Windows Remote - Management (WinRM). - - >WinRM access is required to use deploy tasks such as - **Azure File Copy** and **PowerShell on Target Machines**. - -1. Check the template into your source control system. - -1. Open a text editor and copy the following script into it. - - ```powershell - Param( [string] $labVmId) - - $labVmComputeId = (Get-AzureRmResource -Id $labVmId).Properties.ComputeId - - # Get lab VM resource group name - $labVmRgName = (Get-AzureRmResource -Id $labVmComputeId).ResourceGroupName - - # Get the lab VM Name - $labVmName = (Get-AzureRmResource -Id $labVmId).Name - - # Get lab VM public IP address - $labVMIpAddress = (Get-AzureRmPublicIpAddress -ResourceGroupName $labVmRgName - -Name $labVmName).IpAddress - - # Get lab VM FQDN - $labVMFqdn = (Get-AzureRmPublicIpAddress -ResourceGroupName $labVmRgName - -Name $labVmName).DnsSettings.Fqdn - - # Set a variable labVmRgName to store the lab VM resource group name - Write-Host "##vso[task.setvariable variable=labVmRgName;]$labVmRgName" - - # Set a variable labVMIpAddress to store the lab VM Ip address - Write-Host "##vso[task.setvariable variable=labVMIpAddress;]$labVMIpAddress" - - # Set a variable labVMFqdn to store the lab VM FQDN name - Write-Host "##vso[task.setvariable variable=labVMFqdn;]$labVMFqdn" - -1. Check the script into your source control system. Name - it something like **GetLabVMParams.ps1**. - - >This script, when run on the agent as part of the release pipeline, - collects values that you'll need to deploy your app to the VM - if you use task steps such as **Azure File Copy** or - **PowerShell on Target Machines**. These are the tasks you - typically use to deploy apps to an Azure VM, and they require values - such as the VM Resource Group name, IP address, and - fully-qualified domain name (FQDN). - -## Deploy - -Carry out the following steps to create the -release pipeline in Azure Pipelines. - -1. Open the **Releases** tab of **Azure Pipelines** and choose the - "**+**" icon to create a new release pipeline. - -1. In the **Create release pipeline** dialog, - select the **Empty** template and choose **Next**. - -1. In the next page, select **Choose Later** and then choose **Create**. - This creates a new release pipeline with one - default stage and no linked artifacts. - -1. In the new release pipeline, choose the ellipses (**...**) next - to the stage name to open the shortcut menu - and select **Configure variables**. - -1. In the **Configure - stage** dialog, enter the following values - for the variables you will use in the release pipeline tasks: - - **vmName**: Enter the name you assigned to the VM when - you created the ARM template in the Azure portal. - - **userName**: Enter the username you assigned to the VM when - you created the ARM template in the Azure portal. - - **password**: Enter the password you assigned to the VM when - you created the ARM template in the Azure portal. - Use the "padlock" icon to hide and secure the password.

      - -1. The first stage in this deployment is to create the VM - you will use as the "golden image" for subsequent deployments. - You create this within your Azure DevTestsLab instance using the - task specially developed for this purpose. - In the release pipeline, select **+ Add tasks** - and add an **Azure DevTest Labs Create VM** task - from the **Deploy** tab. - -1. Configure the **Azure DevTest Labs Create VM** task as follows: - - ![Azure DevTest Labs Tasks](media/devtestlabs-icon.png) [Azure DevTest Labs Tasks](https://marketplace.visualstudio.com/items?itemName=ms-azuredevtestlabs.tasks) - Create the VM to use for subsequent deployments. - - - **Azure RM Subscription**: Select a connection from the list under **Available Azure Service Connections** or create a more restricted permissions - connection to your Azure subscription. For more information, see [Azure Resource Manager service connection](../../../library/connect-to-azure.md). - - - **Lab Name**: Select the name of the instance you created earlier. - - - **Template Name**: Enter the full path and name of the template file you saved into your source code repository. You can use the built-in properties of Azure Pipelines to simplify the path, for example: `$(System.DefaultWorkingDirectory)/Contoso/ARMTemplates/CreateVMTemplate.json`. - - - **Template Parameters**: Enter the parameters for the variables defined in the template. Use the names of the variables you defined in the stage, for example: `-newVMName '$(vmName)' -userName '$(userName)' -password (ConvertTo-SecureString -String '$(password)' -AsPlainText -Force)`. - - - **Output Variables - Lab VM ID**: You will need the ID of the newly created VM in subsequent tasks. The default name of the stage variable that will automatically be populated with this ID is set in the **Output Variables** section. You can edit this if necessary, but remember to use the correct name in subsequent tasks. The Lab VM ID is in the form: `/subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}/virtualMachines/{vmName}`.

      - -1. The next stage is to execute the script you created earlier - to collect the details of the DevTest Labs VM. - In the release pipeline, select **+ Add tasks** - and add an **Azure PowerShell** task from the **Deploy** tab. - Configure the task as follows: - - ![Azure PowerShell](../../../tasks/deploy/media/azure-powershell-icon.png) [Deploy: Azure PowerShell](https://github.com/Microsoft/azure-pipelines-tasks/tree/master/Tasks/AzurePowerShellV3) - Execute the script to collect the details of the DevTest Labs VM. - - - **Azure Connection Type**: `Azure Resource Manager`. - - - **Azure RM Subscription**: Select a connection from the list under **Available Azure Service Connections** or create a more restricted permissions - connection to your Azure subscription. For more information, see [Azure Resource Manager service connection](../../../library/connect-to-azure.md). - - - **Script Type**: `Script File`. - - - **Script Path**: Enter the full path and name of the script you saved into your source code repository. You can use the built-in properties of Azure Pipelines to simplify the path, for example: `$(System.DefaultWorkingDirectory/Contoso/Scripts/GetLabVMParams.ps1`. - - - **Script Arguments**: Enter as the script argument the name of the stage variable that was automatically populated with the ID of the lab VM by the previous task, for example: `-labVmId '$(labVMId)'`. | - - >The script collects the values you will require and stores them in - stage variables within the release pipeline so that you can - easily refer to them in subsequent tasks. - -1. Now you can deploy your app to the new DevTest Labs VM. - The tasks you will typically use for this are - **Azure File Copy** and **PowerShell on Target Machines**. - - The information about the VM you'll need for the parameters of these - tasks is stored in three configuration variables - named **labVmRgName**, **labVMIpAddress**, and **labVMFqdn** within the release pipeline. - - If you just want to experiment with creating a DevTest Labs - VM and a custom image, without deploying an app to it, just - skip this step.

      - -1. The next stage is to create an image of the newly deployed - VM in your Azure DevTest Labs instance. You can then use - this image to create copies of the VM on demand, whenever - you want to execute a dev task or run some tests. - In the release pipeline, select **+ Add tasks** - and add an **Azure DevTest Labs Create Custom Image** task - from the **Deploy** tab. Configure it as follows: - - ![Azure DevTest Labs Tasks](media/devtestlabs-icon.png) [Azure DevTest Labs Tasks](https://marketplace.visualstudio.com/items?itemName=ms-azuredevtestlabs.tasks) - Create an image of the VM. - - - **Azure RM Subscription**: Select a connection from the list under **Available Azure Service Connections** or create a more restricted permissions - connection to your Azure subscription. For more information, see [Azure Resource Manager service connection](../../../library/connect-to-azure.md). - - - **Lab Name**: Select the name of the instance you created earlier. - - - **Custom Image Name**: Enter a name for the custom image you will create. - - - **Description**: Optionally enter a description to make it easy to select the correct image later. - - - **Source Lab VM - Source Lab VM ID**: If you changed the default name of the stage variable that was automatically populated with the ID of the lab VM by an earlier task, edit it here. The default is `$(labVMId)`. - - - **Output Variables - Lab VM ID**: You will need the ID of the newly created image when you want to manage or delete it. The default name of the stage variable that will automatically be populated with this ID is set in the **Output Variables** section. You can edit this if necessary.

      - -1. The final stage in this example is to delete the VM you deployed - in your Azure DevTest Labs instance. In reality you will - do this _after_ you execute the dev tasks or run the tests you need - on the deployed VM. In the release pipeline, select - **+ Add tasks** and add an **Azure DevTest Labs Delete VM** task - from the **Deploy** tab. Configure it as follows: - - ![Azure DevTest Labs Tasks](media/devtestlabs-icon.png) [Azure DevTest Labs Tasks](https://marketplace.visualstudio.com/items?itemName=ms-azuredevtestlabs.tasks) - Delete the VM. - - - **Azure RM Subscription**: Select a connection from the list under **Available Azure Service Connections** or create a more restricted permissions - connection to your Azure subscription. For more information, see [Azure Resource Manager service connection](../../../library/connect-to-azure.md). - - - **Lab VM ID**: If you changed the default name of the stage variable that was automatically populated with the ID of the lab VM by an earlier task, edit it here. The default is `$(labVMId)`.

      - -1. Enter a name for the release pipeline and save it. - -1. Create a new release, select the latest build, - and deploy it to the single stage in the pipeline. - -1. At each stage, refresh the view of your DevTest Labs instance - in the Azure portal to see the VM and image being created, and the - VM being deleted again. You can now use the custom image to create - VMs when required. - - >For more information, or if you have any suggestions for - improvements to the extension, visit the - [DevTest Labs feedback forum](https://feedback.azure.com/d365community/forum/502dba10-7726-ec11-b6e6-000d3a4f032c). - -## FAQ - - - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../../includes/qa-versions.md)] -::: moniker-end - - - -[!INCLUDE [rm-help-support-shared](../../../includes/rm-help-support-shared.md)] diff --git a/docs/pipelines/apps/cd/azure/deploy-virtual-scale-set-java.md b/docs/pipelines/apps/cd/azure/deploy-virtual-scale-set-java.md index 3ee6c0da185..c820fb81897 100644 --- a/docs/pipelines/apps/cd/azure/deploy-virtual-scale-set-java.md +++ b/docs/pipelines/apps/cd/azure/deploy-virtual-scale-set-java.md @@ -2,7 +2,7 @@ title: Tutorial - Deploy to a Linux virtual machine scale set description: Learn how to use the Azure CLI to create and deploy a Java application on Linux VMs using a virtual machine scale set ms.topic: tutorial -ms.custom: devx-track-azurecli, devx-track-extended-java +ms.custom: devx-track-azurecli, devx-track-extended-java, linux-related-content ms.author: jukullam author: JuliaKM ms.date: 10/03/2022 diff --git a/docs/pipelines/apps/cd/deploy-docker-webapp.md b/docs/pipelines/apps/cd/deploy-docker-webapp.md index 2f7037d91fb..8fa01b8dcb3 100644 --- a/docs/pipelines/apps/cd/deploy-docker-webapp.md +++ b/docs/pipelines/apps/cd/deploy-docker-webapp.md @@ -1,25 +1,24 @@ --- -title: Deploy a web app to Azure Web App for Containers -description: How to deploy web apps to Azure Web App for Containers +title: Deploy a container to Azure App Service with Azure Pipelines +description: How to deploy containerized web apps to Azure App Service with Azure Pipelines ms.assetid: 78815F3C-4347-4C8B-AB4B-F36FC0D41531 ms.topic: quickstart -ms.custom: seodec18 -ms.date: 06/14/2022 +ms.date: 11/08/2023 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Deploy to Azure Web App for Containers +# Deploy a custom container to Azure App Service with Azure Pipelines [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -Using Azure Pipelines, you can build, test, and automatically deploy your web app to Azure Web App for Containers. In this article, you will learn how to use YAML or Classic pipelines to: +Using Azure Pipelines, you can build, test, and automatically deploy your web app to an Azure App Service Web App container on Linux. In this article, you will learn how to use YAML or Classic pipelines to: > [!div class="checklist"] > > - Build and publish a Docker image to Azure Container Registry -> - Create a Web App for Containers -> - Deploy to Azure Web App for Container +> - Create an Azure Web App +> - Deploy a container to Azure App Service > - Deploy to deployment slots ## Prerequisites @@ -31,7 +30,7 @@ Using Azure Pipelines, you can build, test, and automatically deploy your web ap ## Get the code -[Fork](../../../repos/git/forks.md) the sample app in GitHub or Azure Repos to follow along with this tutorial. +Fork the following sample app at GitHub. #### [Java](#tab/java) @@ -120,9 +119,7 @@ To complete this section successfully, you must have an [Azure Container Registr 1. To deploy your image from the container registry, you must enable the admin user account. Navigate to your container registry in Azure portal, and select **Access keys**. Next, select the toggle button to **Enable Admin user**. - :::image type="content" source="media/enable-admin-user.png" alt-text="Enable Admin user"::: - -## Create a Web App for Containers +## Create a Web App 1. Navigate to [Azure portal](https://portal.azure.com). @@ -134,9 +131,7 @@ To complete this section successfully, you must have an [Azure Container Registr :::image type="content" source="media/configure-web-app.png" alt-text="Configure the web app"::: -1. In the **SKU and Size** section, select **Change size** to specify the pricing tier. Select the **Dev/Test** plan, and then choose the **F1 Free plan**. Select **Apply** when you are done. - - :::image type="content" source="media/pricing-tier.png" alt-text="Change pricing tier to free"::: +1. In the **Pricing plans** section, choose the **F1 Free plan**. 1. Select **Review and create**. Review your configuration, and select **Create** when you are done. @@ -192,7 +187,7 @@ stages: inputs: azureSubscription: $(azureSubscription) appName: $(appName) - imageName: $(containerRegistry)/$(imageRepository):$(tag) + containers: $(containerRegistry)/$(imageRepository):$(tag) ``` # [Classic](#tab/classic/) @@ -243,7 +238,7 @@ The following YAML snippet shows how to deploy to a staging slot, and then swap inputs: azureSubscription: '' appName: '' - imageName: $(containerRegistry)/$(imageRepository):$(tag) + containers: $(containerRegistry)/$(imageRepository):$(tag) deployToSlotOrASE: true resourceGroupName: '' slotName: staging @@ -276,4 +271,4 @@ A: Navigate to [Azure portal](https://portal.azure.com), and then select your We - [Deploy to Azure](../../overview-azure.md) - [Use ARM templates](./azure/deploy-arm-template.md) -- [Define and target environments](../../process/environments.md) \ No newline at end of file +- [Define and target environments](../../process/environments.md) diff --git a/docs/pipelines/apps/cd/deploy-linuxvm-deploygroups.md b/docs/pipelines/apps/cd/deploy-linuxvm-deploygroups.md deleted file mode 100644 index 02805781f99..00000000000 --- a/docs/pipelines/apps/cd/deploy-linuxvm-deploygroups.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Deploy web apps to an NGINX web server on a Linux VM (Classic) -description: How to use classic pipelines to deploy a web application to an NGINX web server on a Linux virtual machine -ms.assetid: 9EBB0342-7FD2-473C-9809-9BCA2250CBC3 -ms.topic: quickstart -ms.custom: seodec18 -ms.author: ronai -author: RoopeshNair -ms.date: 06/13/2022 -monikerRange: '<= azure-devops' ---- - -# Deploy a web app to an NGINX web server running on a Linux Virtual Machine (Classic) - -[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] - -> [!NOTE] -> If you want to deploy your application to a Linux virtual machine using YAML pipelines, see [Deploy to a Linux virtual machine](../../ecosystems/deploy-linux-vm.md). - -Learn how to use Classic Azure Pipelines to build and deploy your web app to an NGINX web server running on a Linux virtual machine. - -## Prerequisites - -- An Azure DevOps Organization. [Create one for free](../../../organizations/accounts/create-organization.md). -- An Azure account with an active subscription. [Create an Azure account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) for free if you don't have one already. -- A GitHub account. [Create one for free](https://github.com). - -## Linux VM Prerequisites - -#### [JavaScript](#tab/javascript) - -- If you don't have a Linux VM with an Nginx web server, follow the steps in this [Quickstart](/azure/virtual-machines/linux/quick-create-cli) to create one in Azure. - -#### [Java](#tab/java) - -- Use Ubuntu 16.04 or higher. -- For Java Spring Boot and Spring Cloud apps, create a Linux VM in Azure using this [template](https://azuremarketplace.microsoft.com/marketplace/apps/azul.azul-zulu13-ubuntu-2004), which provides a fully supported OpenJDK-based runtime. -- For Java servlets on Tomcat server, create a Linux VM using this [template](https://azuremarketplace.microsoft.com/marketplace/apps/azul.azul-zulu13-ubuntu-2004) and then [setup Tomcat](https://www.digitalocean.com/community/tutorials/how-to-install-apache-tomcat-8-on-ubuntu-16-04#step-5-create-a-systemd-service-file) 9.x as a service. -- For Java EE apps, use one of the following templates to create a [Linux VM, Java and WebSphere 9.x](https://azuremarketplace.microsoft.com/marketplace/apps/midvision.websphere-application-server-nde-90), a [Linux VM, Java and WebLogic](https://azuremarketplace.microsoft.com/marketplace/apps/oracle.20191009-arm-oraclelinux-wls-admin), or a [Linux VM and Java 13.x](https://azuremarketplace.microsoft.com/marketplace/apps/azul.azul-zulu13-ubuntu-2004) and WildFly/JBoss 14. - -- - - - -## Get the code - -If you don't have a repository, use the following sample project follow along with this tutorial: - -#### [JavaScript](#tab/javascript) - -``` -https://github.com/MicrosoftDocs/pipelines-javascript -``` - -#### [Java](#tab/java) - -``` -https://github.com/MicrosoftDocs/pipelines-java -``` - -- - - - -## Build your app - -#### [JavaScript](#tab/javascript) - -- [Build JavaScript apps](../../ecosystems/javascript.md) - -#### [Java](#tab/java) - -- [Build Java apps](../../ecosystems/java.md) - -- - - - -## Set up a deployment group - -Deployment groups make it easier to organize the servers you want to use to host your app. A deployment group is a collection of machines with an Azure Pipelines agent on each of them. Each machine interacts with Azure Pipelines to coordinate deployment of your app. - -1. Open an SSH session to your Linux VM. You can do this using the Cloud Shell button in the upper-right of the [Azure portal](https://portal.azure.com/). - - :::image type="content" source="../media/cloud-shell-menu-image.png" alt-text="A screenshot showing the azure cloud shell button"::: - -1. Run the following command to initiate the session. Replace the placeholder with the IP address of your VM: - - ```command - ssh - ``` - -1. Run the following command to install the required dependencies to set up the build and release agent on a Linux virtual machine. See [Self-hosted Linux agents](../../agents/linux-agent.md) for more details. - - ```command - sudo apt-get install -y libunwind8 libcurl3 - ``` - -1. in Azure DevOps web portal, select **Pipelines**, and then select **Deployment groups**. - -1. Select **Add a deployment group** (or **New** if you have existing deployment groups). - -1. Enter a name for the group such as **myNginx** and then select **Create**. - -1. Select **Linux** for the **Type of target to register** and make sure that **Use a personal access token in the script for authentication** is checked. Select **Copy script to the clipboard**. This script will install and configure an agent on your VM. - -1. Back in the SSH session in Azure portal, paste and run the script. - -1. When you're prompted to configure tags for the agent, press _Enter_ to skip. - -1. Wait for the script to finish and display the message *Started Azure Pipelines Agent*. Type *"q"* to exit the file editor and return to the shell prompt. - -1. Back in Azure DevOps portal, on the **Deployment groups** page, open the **myNginx** deployment group. Select the **Targets** tab, and verify that your VM is listed. - -## Create a release pipeline - -1. Select **Pipelines** > **Releases**, and then select **New pipeline**. - -1. Select **Empty job**. - -1. Select **Add an artifact** to link your build artifact. Select **Build**, and then select your **Project** and **Source** from the dropdown menu. Select **Add** when you are done. - -1. Select the **Continuous deployment** icon, and the click the toggle button to enable the continuous deployment trigger. Add the *main* branch as a **Build branch filter**. - - :::image type="content" source="media/deploy-linuxvm-deploygroups/confirm-or-set-cd-trigger.png" alt-text="A screenshot showing how to set up the continuous deployment trigger"::: - -1. Select **Tasks**, and then select the **Agent job** and remove it. - - :::image type="content" source="media/deploy-linuxvm-deploygroups/remove-agent-phase-image.png" alt-text="A screenshot showing how to remove the agent job"::: - -1. Select the ellipsis icon, and then select **Add a deployment group job**. The tasks you will add to this job will run on each server in your deployment group. - - :::image type="content" source="media/deploy-linuxvm-deploygroups/add-deployment-group-phase.png" alt-text="A screenshot showing how to add a deployment group job"::: - -1. Select the deployment group you created earlier from the **Deployment group** dropdown menu. - - :::image type="content" source="media/deploy-linuxvm-deploygroups/select-deployment-group.png" alt-text="A screenshot showing how to select your deployment group."::: - -1. Select **+** to add a new task. Search for **Bash** and then select **Add** to add it to your pipeline. - - :::image type="content" source="media/deploy-linuxvm-deploygroups/add-shellscript-task.png" alt-text="A screenshot showing how to add the bash task."::: - -1. Select the browse button to add the path of your *deploy.sh* script file. See a sample nodeJS deployment script [here](https://github.com/azure-devops/fabrikam-node/blob/master/deployscript.sh). - - :::image type="content" source="media/deploy-linuxvm-deploygroups/configure-shellscript-task.png" alt-text="A screenshot showing how to add the script path."::: - -1. Select **Save** when you are done. - - :::image type="content" source="media/deploy-linuxvm-deploygroups/save-definition-image.png" alt-text="A screenshot showing how to save a release pipeline."::: - -## Deploy your app - -1. Select **Releases**, and then select **Create a release**. - -1. Make sure that the artifact version you want to use is selected and then select **Create**. - -1. Select the release link in the information bar message. For example: "Release **Release-1** has been queued". - -1. Select the status link in **Stages** to see the deployment logs. - -1. After the release is complete, navigate to your app and verify its contents. - -## Related articles - -- [Extend your deployments to IIS Deployment Groups](howto-webdeploy-iis-deploygroups.md) -- [Deploy to IIS servers with Azure Pipelines and WinRM](deploy-webdeploy-iis-winrm.md) -- [Deploy to a Windows Virtual Machine](deploy-webdeploy-iis-deploygroups.md) -- [Create and remove deployment groups dynamically](howto-webdeploy-iis-deploygroups.md#depgroup) diff --git a/docs/pipelines/apps/cd/deploy-webdeploy-iis-deploygroups.md b/docs/pipelines/apps/cd/deploy-webdeploy-iis-deploygroups.md deleted file mode 100644 index eaa93709e3d..00000000000 --- a/docs/pipelines/apps/cd/deploy-webdeploy-iis-deploygroups.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Deploy apps to an IIS server on a Windows VM (Classic) -description: Deploy web apps to an IIS web server on a Windows virtual machine using Deployment Groups -ms.assetid: 979E4504-C88A-4D0A-A912-6E5998D87445 -ms.topic: quickstart -ms.custom: seodec18 -ms.author: ronai -author: RoopeshNair -ms.date: 04/25/2022 -monikerRange: '<= azure-devops' ---- - -# Deploy apps to a Windows Virtual Machine - -[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] - -Learn how to use Azure Pipelines to build and deploy your ASP.NET, ASP.NET Core, or Node.js web app to an IIS web server running on a Windows Virtual Machine. - -## Prerequisites - -- An Azure DevOps Organization. [Create an organization](../../../organizations/accounts/create-organization.md), if you don't have one already. -- [Build pipeline](#build-pipeline) -- [Configure IIS web server](#configure-iis-web-server) - -### Build Pipeline - -Set up a build pipeline if you don't have one already. - -#### [.NET](#tab/net/) - -- [Build ASP.NET apps](../aspnet/build-aspnet-4.md) - -#### [.NET Core](#tab/netcore/) - -- [Build .NET Core apps](../../ecosystems/dotnet-core.md) - -#### [Node](#tab/node/) - -- [Build Node.js apps](../../ecosystems/javascript.md) - ---- - -### Configure IIS web server - -Configure your IIS server if you haven't done so already - -#### [.NET](#tab/net/) - -[!INCLUDE [prepare-aspnet-windows-vm](../includes/prepare-aspnet-windows-vm.md)] - -#### [.NET Core](#tab/netcore/) - -- [Host ASP.NET Core on Windows with IIS](/aspnet/core/host-and-deploy/iis/). - -#### [Node](#tab/node/) - -- [Hosting node.js applications in IIS on Windows](https://github.com/Azure/iisnode) - ---- - -## Create a deployment group - -Deployment groups make it easier to organize the servers that you want to use to host your app. A deployment group is a collection of machines with an Azure Pipelines agent on each of them. Each machine interacts with Azure Pipelines to coordinate the deployment of your app. - -1. Select **Pipelines**, and then select **Deployment groups**. - -1. Select **Add a deployment group** (or **New** if there are already deployment groups in place). - -1. Enter a name for your group, and then select **Create**. - -1. In the machine registration section, make sure that **Windows** is selected from the dropdown menu, and that the **Use a personal access token in the script for authentication** checkbox is also selected. Select **Copy script to clipboard** when you are done. The script that you've copied to your clipboard will download and configure an agent on the VM so that it can receive new web deployment packages and apply them to IIS. - -1. Log in to your VM, open an elevated PowerShell command prompt window and run the script. - -1. When you're prompted to configure tags for the agent, press Enter to skip. (tags are optional) - -1. When you're prompted for the user account, press **Enter** to accept the defaults. - - > [!NOTE] - > The agent running the pipeline must have access to the *C:\Windows\system32\inetsrv\* directory. See [Security groups, service accounts, and permissions](../../../organizations/security/permissions-access.md) for more details. - -1. You should see the following message when the script is done *Service vstsagent.account.computername started successfully*. - -1. Navigate to **Deployment groups**, and then select your deployment group. Select the **Targets** tab and make sure your VM is listed. - -## Create a release pipeline - -Using release pipelines, you can deploy your build artifacts to your IIS servers. - -1. Select **Pipelines**, and then select **Releases**. Select **New pipeline**. - -1. Use the search bar to find the **IIS Website Deployment** template, and then select **Apply**. - - :::image type="content" source="media/iis-web-template.png" alt-text="A screenshot showing how to add the IIS website deployment template."::: - -1. Select **Add an artifact** to add your build artifact. - -1. Select **Build**, and then select your **Project** and your **Source (build pipeline)**. Select **Add** when you are done. - -1. Select the **Continuous deployment trigger** icon in the **Artifacts** section. Enable the **Continuous deployment trigger**, - and add the **main** branch as a filter. - -1. Select **Tasks**, and then select **IIS Deployment**. Select the deployment group you created earlier from the dropdown menu. - - :::image type="content" source="media/iis-deployment-group.png" alt-text="A screenshot showing how to set up the IIS deployment group."::: - -1. Select **Save** when you are done. - -## Deploy your app - -1. Select **Pipelines** > **Releases**, and then select **Create release**. - -1. Check that the artifact version you want to use is selected and then select **Create**. - -1. Select the release link in the information bar message. For example: "Release **Release-1** has been queued". - -1. Navigate to your pipeline **Logs** to see the logs and agent output. - -## Related articles - -- [Deploy to Linux VMs](./deploy-linuxvm-deploygroups.md) -- [Deploy from multiple branches](../..//release/deploy-multiple-branches.md) -- [Deploy pull request Artifacts](../../release/deploy-pull-request-builds.md) diff --git a/docs/pipelines/apps/cd/deploy-webdeploy-iis-winrm.md b/docs/pipelines/apps/cd/deploy-webdeploy-iis-winrm.md deleted file mode 100644 index a342b1a88fa..00000000000 --- a/docs/pipelines/apps/cd/deploy-webdeploy-iis-winrm.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: Deploy to IIS servers using WinRM -description: How to deploy web apps to IIS servers with Azure Pipelines and Windows Remote Management (WinRM) -ms.assetid: 0D65C5BE-DF92-42F6-B6A4-217F0509D425 -ms.topic: conceptual -ms.custom: seodec18 -ms.author: ronai -author: RoopeshNair -ms.date: 04/28/2022 -monikerRange: '<= azure-devops' ---- - -# Deploy to IIS servers with Azure Pipelines and WinRM - -[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] - -Learn how to use Azure Pipelines and WinRM to set up a continuous delivery pipeline to deploy your ASP.NET, ASP.NET Core, or Node.js web apps to one or more IIS servers. - -## Prerequisites - -- An Azure DevOps Organization. [Create an organization](../../../organizations/accounts/create-organization.md), if you don't have one already. -- [Build pipeline](#build-pipeline) -- [Configure WinRM](#configure-winrm) -- [Configure IIS servers](#configure-iis-servers) - -### Build pipeline - -Set up a build pipeline if you don't have one already. - -#### [.NET](#tab/net/) - -- [Build ASP.NET apps](../aspnet/build-aspnet-4.md) - -#### [.NET Core](#tab/netcore/) - -- [Build .NET Core apps](../../ecosystems/dotnet-core.md) - -#### [Node](#tab/node/) - -- [Build Node.js apps](../../ecosystems/javascript.md) - ---- - -### Configure WinRM - -Windows Remote Management (WinRM) requires target servers to be: - -- Domain-joined or workgroup-joined. -- Able to communicate using the HTTP or HTTPS protocol. -- Addressed by using a fully qualified domain name (FQDN) or an IP address. - -This table shows the supported scenarios for WinRM. Make sure that your IIS servers are set up in one of the following configurations. For example, do not use WinRM over HTTP to communicate with a Workgroup machine. Similarly, do not use an IP address to access the target server(s) when you use HTTP protocol. Instead, use HTTPS for both scenarios. - -| Joined to a | Protocol | Addressing mode | -| --------- | -------- | --------------- | -| Workgroup | HTTPS | FQDN or IP address | -| Domain | HTTPS | FQDN or IP address | -| Domain | HTTP | FQDN | - -> [!NOTE] -> If you need to deploy to a server that is not in the same workgroup or domain, add it to the trusted hosts in your [WinRM configuration](/windows/win32/winrm/installation-and-configuration-for-windows-remote-management). - -Follow these steps to configure each target server. - -1. Enable File and Printer Sharing. Run the following command in an elevated command prompt: - - ```cmd - netsh advfirewall firewall set rule group="File and Printer Sharing" new enable=yes - ``` - -1. Make sure you have PowerShell v4.0 or above installed on every target machine. To display the current - PowerShell version, run the following command in an elevated PowerShell command prompt: - - ```powershell - $PSVersionTable.PSVersion - ``` - -1. Make sure you have the .NET Framework v4.5 or higher installed on every target machine. See [How to: Determine Which .NET Framework Versions Are Installed](/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed) for details. - -1. Download the configuration script and copy them to every target machine. You will use them to configure WinRM in the following steps. - - - Windows 10 and Windows Server 2016: [ConfigureWinRM.ps1 win10-ser16](https://github.com/Microsoft/vsts-rm-extensions/blob/master/TaskModules/powershell/WinRM/WinRM-Http-Https/ConfigureWinRM.ps1) - - Previous versions of Windows: [ConfigureWinRM.ps1](https://github.com/Microsoft/vsts-rm-extensions/blob/master/TaskModules/powershell/WinRM/WinRM-Http-Https-With-Makecert/ConfigureWinRM.ps1) - -1. Decide if you want to use HTTP or HTTPS to communicate with the target machine(s). - - - If you want to use the HTTP protocol, run the following command in an elevated command prompt to create an HTTP WinRM listener and open port 5985: - - ```command - ConfigureWinRM.ps1 {FQDN} http - ``` - - - If you want to use the HTTPS protocol, you can use either a FQDN or an IP address to access the target machine(s). To use a FQDN to access the target machine(s), run the following command in an elevated PowerShell command prompt: - - ```powershell - ConfigureWinRM.ps1 {FQDN} https - ``` - - To use an IP address to access the target machine(s), run the following command in an elevated PowerShell command prompt: - - ```powershell - ConfigureWinRM.ps1 {ipaddress} https - ``` - - The script is using **MakeCert.exe** to create a test certificate and use it to create an HTTPS WinRM listener and open port 5986. The script will also increase the WinRM **MaxEnvelopeSizekb** setting to prevent certain errors such as "Request size exceeded the configured MaxEnvelopeSize quota". By default, this value is set to 500 KB in Windows Server machines. - -### Configure IIS servers - -#### [ASP.NET](#tab/net/) - -- [Install IIS](https://www.asp.net/web-forms/overview/deployment/visual-studio-web-deployment/deploying-to-iis) - -#### [ASP.NET Core](#tab/netcore/) - -- [Host ASP.NET Core on Windows with IIS](/aspnet/core/publishing/iis). - -#### [Node](#tab/node/) - -- [Hosting node.js applications in IIS on Windows](https://github.com/Azure/iisnode) - ---- - -## Create a release pipeline - -1. Select **Pipelines**, and then select **Releases**. Select **New pipeline**. - -1. Select **Empty job**. - -1. Select **+ Add** to add your build artifact, and then select your **Project** and **Source**. Select **Add** when you are done. - - :::image type="content" source="../media/confirm-or-add-artifact.png" alt-text="A screenshot showing how to add a build artifact."::: - -1. Choose the **Continuous deployment trigger** icon in the **Artifacts** section, and then enable the **Continuous deployment trigger** and add a build branch filter to include the **main** branch. - - :::image type="content" source="../media/confirm-or-set-cd-trigger.png" alt-text="A screenshot showing how to add a continuous deployment trigger."::: - -1. Select **Variables**, and create a variable **WebServers** with a list of IIS servers for its value; for example *machine1,machine2,machine3*. - -1. Select your stage, and add the following tasks to your pipeline: - - :::image type="icon" source="../../tasks/deploy/media/windows-machine-file-copy-icon.png" border="false"::: [Windows Machine File Copy](../../tasks/deploy/windows-machine-file-copy.md) - Copy the Web Deploy package to the IIS servers. - - - **Source**: Select the Web deploy package path. - - - **Machines**: *$(WebServers)* - - - **Admin Login**: The administrator login on the target servers. For workgroup-joined computers, use the format *.\username*. For domain-joined computers, use the format *domain\username*. - - - **Password**: The administrator password on the target servers. - - - **Destination Folder**: The folder on the target machines to which the files will be copied. - - :::image type="icon" source="../../tasks/deploy/media/iis-web-application-deployment-icon.png" border="false"::: [WinRM - IIS Web App Deployment](https://marketplace.visualstudio.com/items?itemName=ms-vscs-rm.iiswebapp) - Deploy your package. - - - **Machines**: $(WebServers) - - - **Admin Login**: The administrator login on the target servers. For workgroup-joined computers, use the format *.\username*. For domain-joined computers, use the format *domain\username*. - - - **Password**: The administrator password on the target servers. - - - **Protocol**: Select *HTTP* or *HTTPS* (depending on how you configured the target machine earlier). Note that if the target machine is workgroup-joined, you must choose *HTTPS*. You can use HTTP only if the target machine is domain-joined and configured to use a FQDN. - - - **Web Deploy Package**: Fully qualified path of the zip file you copied to the target server in the previous task. - - - **Website Name**: *Default Web Site* (or the name of the website if you configured a different one earlier). - -1. Select **Save** when you are done and then select **OK**. - -## Deploy your app - -1. Select **Pipelines** > **Releases**, and then select **Create release**. - -1. Check that the artifact version you want to use is selected and then select **Create**. - -1. Select the release link in the information bar message. For example: "Release **Release-1** has been queued". - -1. Navigate to your pipeline **Logs** to see the logs and agent output. - -## Related articles - -- [Deploy apps to Windows VMs](./deploy-webdeploy-iis-deploygroups.md). -- [Deploy apps to Linux VMs](./deploy-linuxvm-deploygroups.md). -- [Deploy apps to VMware vCenter Server](../../targets/vmware.md). diff --git a/docs/pipelines/apps/cd/howto-webdeploy-iis-deploygroups.md b/docs/pipelines/apps/cd/howto-webdeploy-iis-deploygroups.md deleted file mode 100644 index 88373338158..00000000000 --- a/docs/pipelines/apps/cd/howto-webdeploy-iis-deploygroups.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Deploy apps & databases with Deployment Groups -description: Deploy an app to IIS servers using Deployment Groups in Azure Pipelines -ms.assetid: 9FC7A7FC-0386-478A-BE1D-0A0B8104ED42 -ms.topic: conceptual -ms.custom: seodec18 -ms.author: ronai -author: RoopeshNair -ms.date: 09/07/2021 -monikerRange: '<= azure-devops' ---- - -# How To: Extend your deployments to IIS Deployment Groups - -[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] - -You can quickly and easily deploy your ASP.NET or Node.js app to an IIS Deployment Group using -Azure Pipelines, -as demonstrated in [this example](deploy-webdeploy-iis-deploygroups.md). -In addition, you can extend your deployment in a range of ways -depending on your scenario and requirements. This topic shows you how to: - -* [Dynamically create and remove a deployment group](#depgroup) -* [Apply stage-specific configurations](#envirconfig) -* [Perform a safe rolling deployment](#rolling) -* [Deploy a database with your app](#database) - -## Prerequisites - -You should have worked through the example [CD to an IIS Deployment Group](deploy-webdeploy-iis-deploygroups.md) before you attempt any of these steps. -This ensures that you have the release pipeline, build artifacts, and websites required. - - -## Dynamically create and remove a deployment group - -You can create and remove deployment groups dynamically if you prefer by using -the [Azure Resource Group Deployment task](https://aka.ms/argtaskreadme) -to install the agent on the machines in a deployment group using ARM templates. -See [Provision deployment group agents](../../release/deployment-groups/howto-provision-deployment-group-agents.md). - - -## Apply stage-specific configurations - -If you deploy releases to multiple stages, you can substitute configuration settings in **Web.config** and other configuration files of your website using these steps: - -1. Define stage-specific configuration settings in the **Variables** tab of a stage in a release pipeline; for example, - ` = `. - -2. In the **IIS Web App Deploy** task, select the checkbox for **XML variable substitution** under **File Transforms and Variable Substitution Options**. - - > If you prefer to manage stage configuration settings in - > your own database or Azure KeyVault, add a task to the stage to read and emit those values using - > `##vso[task.setvariable variable=connectionString;issecret=true]`. - > - > At present, you cannot apply a different configuration to individual IIS servers. - - -## Perform a safe rolling deployment - -If your deployment group consists of many IIS target servers, you can deploy to a subset of servers at a time. -This ensures that your application is always available to your customers. -Select the **Deployment group job** and use the slider to configure the **Maximum number of targets in parallel**. - -![Configuring safe rolling deployment for the proportion of stages to update in parallel](media/howto-webdeploy-iis-deploygroups/safe-rolling-deployment.png) - - -## Deploy a database with your app - -To deploy a database with your app: - -1. Add both the IIS target servers and database servers to your deployment group. - Tag all the IIS servers as `web` and all database servers as `database`. - -1. Add two machine group jobs to stages in the release pipeline, and a task in each job as follows: - - **First [Run on deployment group job](../../process/phases.md)** for configuration of web servers. - - - **Deployment group**: Select the deployment group you created in the [previous example](deploy-webdeploy-iis-deploygroups.md). - - - **Required tags**: `web`

      - - Then add an **IIS Web App Deploy** task to this job. - - **Second [Run on deployment group job](../../process/phases.md)** for configuration of database servers. - - - **Deployment group**: Select the deployment group you created in the [previous example](deploy-webdeploy-iis-deploygroups.md). - - - **Required tags**: `database`

      - - Then add a **SQL Server Database Deploy** task to this job. diff --git a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/add-deployment-group-phase.png b/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/add-deployment-group-phase.png deleted file mode 100644 index 9412f03e33a..00000000000 Binary files a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/add-deployment-group-phase.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/add-shellscript-task.png b/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/add-shellscript-task.png deleted file mode 100644 index 36379f5b8de..00000000000 Binary files a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/add-shellscript-task.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/configure-shellscript-task.png b/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/configure-shellscript-task.png deleted file mode 100644 index ca5691ed8c4..00000000000 Binary files a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/configure-shellscript-task.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/confirm-or-set-cd-trigger.png b/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/confirm-or-set-cd-trigger.png deleted file mode 100644 index 7f4a05ac804..00000000000 Binary files a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/confirm-or-set-cd-trigger.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/remove-agent-phase-image.png b/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/remove-agent-phase-image.png deleted file mode 100644 index 3a24e3d70ce..00000000000 Binary files a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/remove-agent-phase-image.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/save-definition-image.png b/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/save-definition-image.png deleted file mode 100644 index a0f6bec933f..00000000000 Binary files a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/save-definition-image.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/select-deployment-group.png b/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/select-deployment-group.png deleted file mode 100644 index 55b3e6abc28..00000000000 Binary files a/docs/pipelines/apps/cd/media/deploy-linuxvm-deploygroups/select-deployment-group.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/enable-admin-user.png b/docs/pipelines/apps/cd/media/enable-admin-user.png deleted file mode 100644 index 99d8ddbe765..00000000000 Binary files a/docs/pipelines/apps/cd/media/enable-admin-user.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/howto-webdeploy-iis-deploygroups/safe-rolling-deployment.png b/docs/pipelines/apps/cd/media/howto-webdeploy-iis-deploygroups/safe-rolling-deployment.png deleted file mode 100644 index 8f3f90cf9f3..00000000000 Binary files a/docs/pipelines/apps/cd/media/howto-webdeploy-iis-deploygroups/safe-rolling-deployment.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/iis-deployment-group.png b/docs/pipelines/apps/cd/media/iis-deployment-group.png deleted file mode 100644 index cabf6798095..00000000000 Binary files a/docs/pipelines/apps/cd/media/iis-deployment-group.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/iis-web-template.png b/docs/pipelines/apps/cd/media/iis-web-template.png deleted file mode 100644 index ee1d4ead934..00000000000 Binary files a/docs/pipelines/apps/cd/media/iis-web-template.png and /dev/null differ diff --git a/docs/pipelines/apps/cd/media/validate-and-configure.png b/docs/pipelines/apps/cd/media/validate-and-configure.png index e642effda93..c17ea4f000a 100644 Binary files a/docs/pipelines/apps/cd/media/validate-and-configure.png and b/docs/pipelines/apps/cd/media/validate-and-configure.png differ diff --git a/docs/pipelines/apps/includes/add-service-endpoint-azure.md b/docs/pipelines/apps/includes/add-service-endpoint-azure.md deleted file mode 100644 index 74847ff4540..00000000000 --- a/docs/pipelines/apps/includes/add-service-endpoint-azure.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -ms.topic: include -ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: sdanie -author: steved0x -ms.date: 02/14/2020 ---- - -

      -If a subscription is not available, then add a service connection: -

      - -
        - -
      1. - -![Manage](../media/azure-web-app-deployment-step-azure-subscription-manage.png) - -
        2. - -
      2. Click New service connection, and then click Azure.
        3. - -

      3. On the Add Azure Subscription dialog box:

        1. Select Certificate.
        2. Click the link to download your publishsettings xml file and then open the file.
        3. Copy the ID and certificate values from the file and paste them into the Add Azure Subscription dialog box.
        4. - -
      - -
      diff --git a/docs/pipelines/apps/includes/azure-web-app-setup.md b/docs/pipelines/apps/includes/azure-web-app-setup.md deleted file mode 100644 index 276711d0348..00000000000 --- a/docs/pipelines/apps/includes/azure-web-app-setup.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -ms.topic: include -ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: jukullam -author: juliakm -ms.date: 02/13/2020 ---- - -### Create the Azure App Aervice - -An [Azure App Service](/azure/app-service/overview) is where you'll deploy your application. Technically speaking, an app service is a resource with a specific pricing tier in Azure that can then host multiple, distinct applications. In this example we'll use a [Web App](/azure/app-service/overview). -If you're creating a new App Service for this example, you can use the [Free pricing tier](https://azure.microsoft.com/pricing/details/app-service/). - -To create a new Web App, simply go to the App Services blade on the Azure portal, click **+Add**, select the **Web App** template, click **Create**, and enter a name and other details. The web app URL will then be `{name}.azurewebsites.net.` - -

      Can I use an existing Azure account?

      -If you have an existing Azure account, you can certainly use a new or existing App Service in that account for this walkthrough. -

      - -

      How do I create a new Azure account with free credits?

      -If you don't yet have an Azure account, you can get started for free through Visual Studio Dev Essentials. -

      - -

      Can I just use a temporary App Service instead?

      - Yes, just visit Create your Azure App Service App to set up a Web App for temporary use (1 hour). On that page, do the following: - -
        -
      1. Select Web App and choose Next.
        2. -
      2. Select Empty Site and choose Create (we use an empty site because you already have the necessary application code in your Visual Studio project).
        3. -
      3. Enter your Microsoft account credentials when requested.
        4. -
      -In a few moments the site will then give you a URL such as https://df8381c9-0ee0-4-aaa-aaaa.azurewebsites.net/. This is the URL of your live site to which we'll deploy the application. -

      - -Learn more at the [Web Apps Overview](/azure/app-service/overview). \ No newline at end of file diff --git a/docs/pipelines/apps/includes/ci-web-app-next-steps.md b/docs/pipelines/apps/includes/ci-web-app-next-steps.md index caa88d3e1f1..b18db5e6590 100644 --- a/docs/pipelines/apps/includes/ci-web-app-next-steps.md +++ b/docs/pipelines/apps/includes/ci-web-app-next-steps.md @@ -7,10 +7,10 @@ author: juliakm ms.date: 02/14/2020 --- -You've just put your own CI pipeline in place to automatically build and validate whatever code is checked in by your team. You can also automatically deploy your app. To learn more, see one of these topics: +You've just put your own CI pipeline in place to automatically build and validate whatever code is checked in by your team. You can also automatically deploy your app. For more information, see one of these topics: * [Deploy to Azure Web App](../cd/deploy-webdeploy-webapps.md) -* [Deploy to a Linux VM](../cd/deploy-linuxvm-deploygroups.md) +* [Deploy to a Linux VM](/azure/devops/pipelines/apps/cd/deploy-linuxvm-deploygroups) * [Deploy to a Windows VM](../cd/deploy-webdeploy-iis-deploygroups.md) You can also modify this build pipeline to meet the needs of your team. To learn more see one of these topics: diff --git a/docs/pipelines/apps/includes/create-azure-linux-vm.md b/docs/pipelines/apps/includes/create-azure-linux-vm.md index 84bb61846aa..bd73b5b18f4 100644 --- a/docs/pipelines/apps/includes/create-azure-linux-vm.md +++ b/docs/pipelines/apps/includes/create-azure-linux-vm.md @@ -1,6 +1,7 @@ --- ms.topic: include ms.service: azure-devops-pipelines +ms.custom: linux-related-content ms.manager: mijacobs ms.author: jukullam author: juliakm diff --git a/docs/pipelines/apps/includes/create-linux-deployment-group.md b/docs/pipelines/apps/includes/create-linux-deployment-group.md index 5f311d39d1d..fa9611611aa 100644 --- a/docs/pipelines/apps/includes/create-linux-deployment-group.md +++ b/docs/pipelines/apps/includes/create-linux-deployment-group.md @@ -1,6 +1,7 @@ --- ms.topic: include ms.service: azure-devops-pipelines +ms.custom: linux-related-content ms.manager: mijacobs ms.author: jukullam author: juliakm diff --git a/docs/pipelines/apps/includes/uwp-ci-vsbuild-arguments.md b/docs/pipelines/apps/includes/uwp-ci-vsbuild-arguments.md deleted file mode 100644 index 0765a1cc7b8..00000000000 --- a/docs/pipelines/apps/includes/uwp-ci-vsbuild-arguments.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -ms.topic: include -ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: jukullam -author: juliakm -ms.date: 02/14/2020 ---- - -

    • MSBuild Arguments: Leave it set to the default:

      -
      /p:AppxBundlePlatforms="$(BuildPlatform)" /p:AppxPackageDir="$(Build.BinariesDirectory)\AppxPackages&quot; /p:AppxBundle=Always
-
      -

      Q: Why do I need these arguments? A:

      -
        -
      • /p:AppxBundlePlatforms="$(BuildPlatform)" The template is setup with BuildPlatform="x86|x64|ARM" so the bundle will include all three platforms. -
        • -
      • /p:AppxPackageDir="$(Build.BinariesDirectory)\AppxPackages\" Location where the bundle directories are created. -
        • -
      • /p:AppxBundle=Always Always produce a bundle. -
        • -
      -
      • -
    • Platform: Leave it blank. (The bundle platforms are specified in the above MSBuild Arguments.) -
      • -

    • Configuration: Leave it set to $(BuildConfiguration)

      -

      Note: By default BuildConfiguration is set to release on the Variables tab. With the Universal Windows Platform, there is now a new native compiler that will improve the runtime performance of your app. With this change, it is highly recommended that you test your app in this compilation environment. By default, the Release build configuration enables the .NET native toolchain, so it is important to test your app with this Release configuration and check that your app behaves as expected. -

      -
      • diff --git a/docs/pipelines/apps/media/cloud-shell-menu-image.png b/docs/pipelines/apps/media/cloud-shell-menu-image.png deleted file mode 100644 index dd4dfd5933f..00000000000 Binary files a/docs/pipelines/apps/media/cloud-shell-menu-image.png and /dev/null differ diff --git a/docs/pipelines/apps/mobile/app-signing.md b/docs/pipelines/apps/mobile/app-signing.md index 68447d830fc..6eb67e041fc 100644 --- a/docs/pipelines/apps/mobile/app-signing.md +++ b/docs/pipelines/apps/mobile/app-signing.md @@ -1,260 +1,290 @@ --- -title: Sign Your Mobile App During CI -ms.custom: seodec18 -description: How to sign your mobile app during CI with Azure Pipelines +title: Sign a mobile app +description: See how to sign a mobile app during continuous integration (CI) with Azure Pipelines. ms.topic: conceptual ms.assetid: 1b9de1a8-0749-40af-87e8-857fb86cf0ae ms.reviewer: dastahel -ms.date: 01/25/2023 +ms.date: 07/20/2024 monikerRange: '<= azure-devops' --- -# Sign your mobile app +# Sign a mobile app [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -When developing an app for Android or Apple operating systems, you'll eventually need to manage signing certificates, and in the case of Apple apps, [provisioning profiles](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppStoreDistributionTutorial/Introduction/Introduction.html#//apple_ref/doc/uid/TP40013839). This article describes how to securely manage them for signing and provisioning your app. +To sign and provision a mobile app for Android or Apple operating systems, you need to manage signing certificates and Apple [provisioning profiles](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppStoreDistributionTutorial/Introduction/Introduction.html#//apple_ref/doc/uid/TP40013839). This article describes how to securely manage certificates and profiles for signing and provisioning your app in Azure Pipelines. -> [!TIP] -> Use a Microsoft-hosted Linux, macOS, or Windows build agent, or set up your own agent. See [Build and release agents](../../agents/agents.md). +> [!NOTE] +> You need at least one agent to run a build or release. You can use a Microsoft-hosted Linux, macOS, or Windows build agent, or set up your own agent. For more information, see [Build and release agents](../../agents/agents.md). -This article covers: -- [Sign your Android app](#android) -- [Sign your Apple iOS, macOS, tvOS, or watchOS app](#apple) + +## Sign your Android app -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../includes/concept-rename-note.md)] -::: moniker-end +Follow these steps to sign your Android app while keeping your signing certificate secure. - +### Upload the keystore file -## Sign your Android app +1. Obtain a keystore file that contains your signing certificate. The [Android documentation](https://developer.android.com/studio/publish/app-signing.html#generate-key) describes the process of generating a keystore file and its corresponding key. + +1. In Azure Pipelines, go to **Libraries** > **Secure files**. Select **+ Secure file** and upload your keystore file to the [secure files library](../../library/secure-files.md). During upload, your keystore is encrypted and securely stored. + +### Add the signing task to the pipeline -Follow these steps to sign your Android app while keeping your signing certificate secure: +# [YAML](#tab/yaml) -1. First, obtain a keystore file that contains your signing certificate. The [Android documentation](https://developer.android.com/studio/publish/app-signing.html#generate-key) describes the process of generating a keystore file and its corresponding key. +Add the [AndroidSigning@3](/azure/devops/pipelines/tasks/reference/android-signing-v3) task to your YAML pipeline after the step that builds your app. In the `AndroidSigning@3` task: -1. Create your build pipeline from the Android or Xamarin.Android build template. Or, if you already have a build pipeline, add the [Android Signing](/azure/devops/pipelines/tasks/reference/android-signing-v3) task after the task that builds your APK. +- `` is required and is the path and names of the APK files to be signed. The default is `**/*.apk`. +- `` must be `true`, which is the default. +- `` is the name of your uploaded keystore file in the secure files library. +- `` is the password to the unencrypted keystore file. +- `` is the key alias for the signing certificate. +- `` is the password for the key associated with the specified alias. -1. Find the Android Signing task's **Sign the APK** checkbox and enable it. +You can set and use variables in the YAML, or you can set the variables using the **Variables** tab in the Azure Pipelines UI and refer to them in the YAML. -1. Next to the **Keystore file** field, select the settings icon and upload your keystore file to the [Secure Files library](../../library/secure-files.md). During upload, your keystore will be encrypted and securely stored. +```yaml +variables: + keystore-password: + key-alias: + key-password: + +steps: +- task: AndroidSigning@3 + displayName: 'Signing and aligning APK file(s) **/*.apk' + inputs: + apkFiles: '**/*.apk' + apksign: true + apksignerKeystoreFile: + apksignerKeystorePassword: $(keystore-password) + apksignerKeystoreAlias: $(key-alias) + apksignerKeyPassword: $(key-password) +``` -1. Once your keystore has been uploaded to the Secure Files library, select it in the **Keystore file** dropdown. +# [Classic](#tab/classic) -1. Go to the **Variables** tab and add the following variables. In their **Value** column, enter your **Keystore password**, **Key alias**, and **Key password**. +1. Create your build pipeline from the Android build template. Or if you already have a build pipeline, make sure the [Android signing](/azure/devops/pipelines/tasks/reference/android-signing-v3) task is present after the task that builds your app. - - **keystore-password**: Password to the unencrypted keystore file. _Be sure to select the **lock** icon._ This will secure your password and obscure it in logs. - - **key-alias**: The key alias for the signing certificate you generated. - - **key-password**: The password for the key associated with the specified alias. _Again, be sure to select the **lock** icon._ +1. In the Android signing task, select the **Sign the APK** checkbox under **Signing Options**. - ![Android signing variables](media/secure-certs/android-signing-variables.png) +1. Select the settings icon next to the **Keystore file** field, and select the uploaded keystore file from the **Keystore file** dropdown. -1. Go back to the **Tasks** tab and reference the names of your newly created variables in the signing options. +1. Select the **Variables** tab for the pipeline and add the following variables: - ![Android signing input values](media/secure-certs/android-signing-input-values.png) + |Name|Value| + |--------|-----| + |**keystore-password**|Password to the unencrypted keystore file. Be sure to select the **lock** icon to secure your password and obscure it in logs.| + |**key-alias**|The key alias for the signing certificate you generated.| + |**key-password**|The password for the key associated with the specified alias. Be sure to select the **lock** icon.| -Save your build pipeline, and you're all set! Any build agent will now be able to securely sign your app without any certificate management on the build machine itself. +1. On the **Tasks** tab, select the Android signing task and reference the names of your newly created variables in the **Signing Options** as `$(keystore-password)`, `$(key-alias)`, and `$(key-password)`. +--- - +Any build agent can now securely sign your app without any certificate management on the build machine itself. + ## Sign your Apple iOS, macOS, tvOS, or watchOS app -For your Xcode or Xamarin.iOS build to sign and provision your app, it needs access to your P12 signing certificate and one or more provisioning profiles. The following sections explain how to obtain these files. +To sign and provision your app, your Xcode build needs access to your P12 signing certificate and one or more provisioning profiles. The following steps explain how to obtain these files. -### Obtain your P12 signing certificate +### Get your P12 signing certificate -After creating your development or distribution signing certificate, export it to a `.p12` file using either Xcode or the Keychain Access app on macOS. +1. Export your development or distribution signing certificate to a *.p12* file by using either Xcode or the Keychain Access app on macOS. -1. To export using Xcode 8 or lower, go to **Xcode** > **Preferences...** > **Accounts** and select your Apple Developer account. -1. Select **View Details...**, right-click on the signing identity you wish to export, and select **Export...**. -1. Enter a filename and password. Take note of the password as you'll need it later. + - To export using Xcode: - ![Xcode Export Cert](media/secure-certs/secure-certs-1.png) + 1. Go to **Xcode** > **Preferences** > **Accounts**. + 1. In the left column, select your Apple ID. + 1. On the right side, select your personal or team account and select **Manage Certificates**. + 1. Ctrl+Select the certificate you want to export and select **Export certificate** from the menu. -1. Alternatively, follow a similar process using the **Keychain Access** app on macOS or generate a signing certificate on Windows. Use the procedure [described in this article](https://github.com/phonegap/phonegap-docs/blob/master/docs/4-phonegap-build/3-signing/2-ios.html.md) if you prefer this method. + ![Screenshot of exporting a certificate using Xcode.](media/secure-certs/secure-certs.png) -### Obtain your provisioning profile + 1. In the dialog box, enter the certificate name, location to save the file, and a password to secure the certificate. -You can download your app provisioning profile from the Apple Developer portal, unless your app uses automatic signing. [Learn how to download a provisioning profile in the Apple Developer portal.](https://developer.apple.com/help/account/manage-profiles/edit-download-or-delete-profiles/) + - Or, use the procedure described in [iOS Signing](https://github.com/phonegap/phonegap-docs/blob/master/docs/4-phonegap-build/3-signing/2-ios.html.md) to follow a similar process using the **Keychain Access** app on macOS or generate a signing certificate on Windows. -You can also use Xcode to access those that are installed on your Mac. -1. Using Xcode 8 or lower, go to **Xcode** > **Preferences...** > **Accounts** and select your Apple Developer account. -1. Right-click the provisioning profile you want to use and select **Show in Finder**. -1. Copy the highlighted file from Finder to another location and give it a descriptive filename. +1. Upload your P12 file to the Azure Pipelines [secure files library](../../library/secure-files.md). During upload, your certificate is encrypted and securely stored. - ![Xcode Show in Finder](media/secure-certs/secure-certs-2.png) +1. In your pipeline, go to the **Variables** tab and add a variable named **P12password** with your certificate password as the value. Be sure to select the **lock** icon to secure your password and obscure it in logs. -### Configure your build +### Get your provisioning profile -There are two recommended ways for your build to access signing certificates and provisioning profiles for signing and provisioning your app: +If your app doesn't use automatic signing, you can download your app provisioning profile from the Apple Developer portal. For more information, see [Edit, download, or delete provisioning profiles](https://developer.apple.com/help/account/manage-profiles/edit-download-or-delete-profiles/). -1. Installing them during the build -1. Preinstalling them on a macOS build agent +You can also use Xcode to access provisioning profiles that are installed on your Mac. In Xcode, go to **Xcode** > **Preferences** > **Accounts**. Select your Apple ID and your team and then select **Download Manual Profiles**. -Choose either of the tabs below for details. +In Azure Pipelines, upload your provisioning profile to the [secure files library](../../library/secure-files.md). During upload, your file is encrypted and securely stored. -# [Install them during the build](#tab/apple-install-during-build) +### Add the signing and provisioning tasks to the pipeline -Use this method when you don't have enduring access to the build agent, such as the [hosted macOS agents](../../agents/hosted.md). The P12 certificate and provisioning profile are installed at the beginning of the build and removed when the build completes. +To sign and provision your app, you can either install the certificate and profile during each build, or [preinstall the files on a macOS build agent](#preinstall-the-certificate-and-profile-on-a-macos-build-agent). -#### Install the P12 certificate during your build +#### Install the certificate and profile during each build -##### Visual Editor +Install the certificate and profile during each build when you don't have enduring access to the build agent, for example when you use [hosted macOS agents](../../agents/hosted.md). The P12 certificate and provisioning profile are installed at the beginning of the build and removed when the build completes. -1. Add the [Install Apple Certificate](/azure/devops/pipelines/tasks/reference/install-apple-certificate-v2) task to your build before the Xcode or Xamarin.iOS task. -1. Next to the **Certificate (P12)** field, select the settings icon and upload your P12 file to the [Secure Files library](../../library/secure-files.md). During upload, your certificate will be encrypted and securely stored. -1. Once your certificate has been uploaded to the Secure Files library, select it in the **Certificate (P12)** dropdown. -1. Go to the **Variables** tab and add a variable named `P12password`. Set its value to the password of your certificate. _Be sure to select the **lock** icon._ This will secure your password and obscure it in logs. -1. Go back to the **Tasks** tab. In the **Install Apple Certificate** task's settings, reference your newly created variable in the **Certificate (P12) password** field as: `$(P12password)` +# [YAML](#tab/yaml) -##### Sample YAML +- Add the [InstallAppleCertificate@2](/azure/devops/pipelines/tasks/reference/install-apple-certificate-v2) task to your YAML pipeline before the Xcode task. In the code, replace `` with the name of your uploaded *.p12* file. Use the variable for the secure `P12password`. -1. Upload your P12 file to the [Secure Files library](../../library/secure-files.md). During upload, your certificate will be encrypted and securely stored. -1. Go to the **Variables** tab and add a variable named `P12password`. Set its value to the password of your certificate. _Be sure to select the **lock** icon._ This will secure your password and obscure it in logs. -1. Add the [Install Apple Certificate](/azure/devops/pipelines/tasks/reference/install-apple-certificate-v2) task to your YAML before the Xcode or Xamarin.iOS task: + ```yaml + - task: InstallAppleCertificate@2 + inputs: + certSecureFile: '' + certPwd: '$(P12password)' + ``` - ```yaml - - task: InstallAppleCertificate@2 - inputs: - certSecureFile: 'my-secure-file.p12' # replace my-secure-file.p12 with the name of your P12 file. - certPwd: '$(P12password)' - ``` + >[!NOTE] + >In the `InstallAppleCertificate@2` task, the `deleteCert` parameter defaults to `true`, which removes the certificate after build. -#### Install the provisioning profile during your build +- Add the [InstallAppleProvisioningProfile@1](/azure/devops/pipelines/tasks/reference/install-apple-provisioning-profile-v1) task to your YAML before the Xcode task. Replace `` with the name of your provisioning profile file. -##### Visual Editor + ```yaml + - task: InstallAppleProvisioningProfile@1 + inputs: + provProfileSecureFile: '' + ``` -1. Add the [Install Apple Provisioning Profile](/azure/devops/pipelines/tasks/reference/install-apple-provisioning-profile-v1) task to your build before the Xcode or Xamarin.iOS task. -1. For the **Provisioning profile location** option, choose **Secure Files** (in YAML, `secureFiles`). -1. Next to the **Provisioning profile** field, select the settings icon and upload your provisioning profile file to the [Secure Files library](../../library/secure-files.md). During upload, your certificate will be encrypted and securely stored. -1. Once your certificate has been uploaded to the Secure Files library, select it in the **Provisioning profile** dropdown. -1. Enable the checkbox labeled **Remove profile after build**. This will ensure that the provisioning profile isn't left on the agent machine. + >[!NOTE] + >In the `InstallAppleProvisioningProfile@1` task, the `removeProfile` parameter defaults to `true`, which removes the profile after build. -##### Sample YAML +# [Classic](#tab/classic) -1. Upload your provisioning profile to the [Secure Files library](../../library/secure-files.md). During upload, your certificate will be encrypted and securely stored. -1. Add the [Install Apple Provisioning Profile](/azure/devops/pipelines/tasks/reference/install-apple-provisioning-profile-v1) task to your YAML before the Xcode or Xamarin.iOS task: +- Add the [Install Apple Certificate](/azure/devops/pipelines/tasks/reference/install-apple-certificate-v2) task to your build before the Xcode task. - ```yaml - - task: InstallAppleProvisioningProfile@1 - inputs: - provProfileSecureFile: 'my-provisioning-profile.mobileprovision' # replace my-provisioning-profile.mobileprovision with the name of your provisioning profile file. - ``` + In the **Install Apple Certificate** task settings: + + - Next to the **Certificate (P12)** field, select your uploaded certificate from the **Certificate (P12)** dropdown. + - In the **Certificate (P12) password** field, reference the *$(P12password)* variable. - > [NOTE] - > **Remove profile after build** defaults to *true*. +- Add the [Install Apple Provisioning Profile](/azure/devops/pipelines/tasks/reference/install-apple-provisioning-profile-v1) task to your build before the Xcode task. -#### Reference the files in your Xcode task + In the **Install Apple Provisioning Profile** task settings: + + - For the **Provisioning profile location** option, choose **Secure Files**, and select your uploaded file in the **Provisioning profile** dropdown. + - Select the checkbox labeled **Remove profile after build** to ensure that the provisioning profile isn't left on the agent machine. -##### Visual Editor +--- -1. Select the **Xcode** task. -1. For the **Signing style** option, choose **Manual signing**. -1. In the **Signing identity** field, enter `$(APPLE_CERTIFICATE_SIGNING_IDENTITY)`. This variable is automatically set by the **Install Apple Certificate** task for the certificate you selected. -1. In the **Provisioning profile UUID** field, enter `$(APPLE_PROV_PROFILE_UUID)`. This variable is automatically set by the **Install Apple Provisioning Profile** task for the provisioning profile you selected. +Any build agent can now securely sign your app without any certificate or profile management on the build machine itself. -##### Sample YAML +#### Preinstall the certificate and profile on a macOS build agent -```yaml -- task: Xcode@5 - inputs: - signingOption: 'manual' - signingIdentity: '$(APPLE_CERTIFICATE_SIGNING_IDENTITY)' - provisioningProfileUuid: '$(APPLE_PROV_PROFILE_UUID)' -``` +Instead of installing the signing certificate and provisioning profiles during the build, you can preinstall them on a macOS build agent. The files are then available for continued use by builds. Use this method only when you trust the people and processes that have access to the macOS keychain on the agent machine. + +**Preinstall the P12 certificate** + +1. To install the P12 certificate in the default keychain, run the following command from a macOS Terminal window on the build agent. Replace `` with the path and name of your P12 file. Replace `` with your P12 file's encryption password. -#### Reference the files in your Xamarin.iOS task + ``` + sudo security import -P + ``` -##### Visual Editor +1. Add a new variable to your pipeline named **KEYCHAIN_PWD**. Set the value as the password to the default keychain, which is normally the password for the user that starts the agent. Be sure to select the **lock** icon to secure this password. -1. Select the **Xamarin.iOS** task. -1. For the **Override using** option, choose **Identifiers**. -1. In the **Signing identity** field, enter `$(APPLE_CERTIFICATE_SIGNING_IDENTITY)`. This variable is automatically set by the **Install Apple Certificate** task for the certificate you selected. -1. In the **Provisioning profile UUID** field, enter `$(APPLE_PROV_PROFILE_UUID)`. This variable is automatically set by the **Install Apple Provisioning Profile** task for the provisioning profile you selected. +**Preinstall the provisioning profile** -##### Sample YAML +1. Find the full name of your signing identity by opening a macOS Terminal window and entering `security find-identity -v -p codesigning`. You see a list of signing identities in the form `iPhone Developer/Distribution: Developer Name (ID)`. If an identity is invalid, you see something like `(CSSMERR_TP_CERT_REVOKED)` after the identity. -```yaml -- task: XamariniOS@2 - inputs: - solutionFile: '**/*.iOS.csproj' - signingIdentity: '$(APPLE_CERTIFICATE_SIGNING_IDENTITY)' - signingProvisioningProfileID: '$(APPLE_PROV_PROFILE_UUID)' -``` +1. To install the provisioning profile on the agent machine, run the following command from a macOS Terminal window. Replace `` with the path to your provisioning profile file, and replace `` with the provisioning profile UUID, which is the provisioning profile filename without the `.mobileprovision` extension. -Save your build pipeline, and you're all set! The build agent will now be able to securely sign and provision your app. + ``` + sudo cp ~/Library/MobileDevice/Provisioning Profiles/.mobileprovision + ``` -# [Preinstall them on a macOS build agent](#tab/apple-preinstall) +**Add signing and provisioning tasks that use the default keychain** -Use this method only when you trust the people and processes that have access to the macOS keychain on the agent machine where these files will be installed. They'll be available for continued use by builds. +# [YAML](#tab/yaml) -#### Install the P12 certificate -Run the following command from a macOS Terminal window of the build agent machine to install the P12 certificate in the default keychain. Replace `` with the path to your P12 file. Replace `` with your P12 file's encryption password. +- Add the [InstallAppleCertificate@2](/azure/devops/pipelines/tasks/reference/install-apple-certificate-v2) task to your YAML pipeline before the Xcode task. In the code, set the following values: -``` -sudo security import -P -``` + - `certSecureFile`: The name of your uploaded *.p12* file. + - `certPwd`: The variable for the secure `P12password`. + - `signingIdentity`: The full name of your signing identity. + - `keychain`: `default`, to allow access to the default keychain. + - `keychainPassword`: The `KEYCHAIN_PWD` variable. + - `deleteCert`: `false`, to retain the certificate between builds. -#### Install the provisioning profile + ```yaml + - task: InstallAppleCertificate@2 + inputs: + certSecureFile: '' + certPwd: '$(P12password)' + signingIdentity: + keychain: default + keychainPassword: `$(KEYCHAIN_PWD) + deleteCert: false + ``` -Follow these steps: +- Add the [InstallAppleProvisioningProfile@1](/azure/devops/pipelines/tasks/reference/install-apple-provisioning-profile-v1) task. In the code: -1. Find the full name of your signing identity by opening the Terminal app and typing the following: + - Set `provProfileSecureFile` to the name of your provisioning profile file. + - Set `removeProfile` to `false` so the profile is retained between builds. - ``` - security find-identity -v -p codesigning - ``` + ```yaml + - task: InstallAppleProvisioningProfile@1 + inputs: + provProfileSecureFile: '' + removeProfile: false + ``` - You'll see a list of signing identities in the form `iPhone Developer/Distribution: Developer Name (ID)`. If the identity is invalid, you'll see something like `(CSSMERR_TP_CERT_REVOKED)` after the identity. +# [Classic](#tab/classic) - Take note of the identity you want to use including the ID. +- Add the [Install Apple Certificate](/azure/devops/pipelines/tasks/reference/install-apple-certificate-v2) task to your build before the Xcode task. In the **Install Apple Certificate** task settings: -1. Find the UUID for the provisioning profile you want to use by following these steps: + - Next to the **Certificate (P12)** field, select your uploaded certificate from the **Certificate (P12)** dropdown. + - In the **Certificate (P12) password** field, reference the *$(P12password)* variable. + - Under **Advanced**, set **Keychain** to **Default Keychain**. + - Set **Keychain password** to the keychain password variable. + - Deselect the **Delete certificate from keychain** checkbox to keep the certificate on the agent machine after the build. - 1. Open Xcode and go to **Xcode** > **Preferences...** > **Accounts** and select your Apple Developer account. - 1. Select **View Details...**, right-click the provisioning profile you want, and select **Show in Finder**. - ![Xcode Show in Finder](media/secure-certs/secure-certs-2.png) - 1. The name of the file that is highlighted in Finder is the UUID of your provisioning profile. +- Add the [Install Apple Provisioning Profile](/azure/devops/pipelines/tasks/reference/install-apple-provisioning-profile-v1) task to your build before the Xcode task. In the **Install Apple Provisioning Profile** task settings: -1. Run the following command from a macOS Terminal window of the build agent machine to install the provisioning profile. Replace `` with the path to your provisioning profile file. Replace `` with the UUID of the provisioning profile, obtained above. + - For the **Provisioning profile location** option, choose **Secure Files**, and select your uploaded file in the **Provisioning profile** dropdown. + - Deselect the **Remove profile after build** checkbox to keep the provisioning profile on the agent machine after the build. -``` -sudo cp ~/Library/MobileDevice/Provisioning\ Profiles/.mobileprovision -``` +--- + +The macOS build agent can now securely sign and provision your app for all builds without further certificate or profile management. + +### Reference the secure files in the Xcode build task -#### Reference the files in your Xcode task +To use the secure certificate and profile in your pipelines, configure the following settings in your Xcode build tasks. -1. Select the **Xcode** task. -1. For the **Signing style** option, choose **Manual signing**. -1. In the **Signing identity** field, enter the full signing identity you found using the security command above. -1. In the **Provisioning profile UUID** field, enter the UUID of the provisioning profile from the filename above. +The secure files references in the build tasks use variables for the `signingIdentity` and the `provisioningProfileUuid`. These variables are automatically set by the **Install Apple Certificate** and **Install Apple Provisioning Profile** tasks for the certificate and provisioning profile you selected. -#### Reference the files in your Xamarin.iOS task +# [YAML](#tab/yaml) -1. Select the **Xamarin.iOS** task. -1. For the **Override using** option, choose **Identifiers**. -1. In the **Signing identity** field, enter the full signing identity you found using the security command above. -1. In the **Provisioning profile UUID** field, enter the UUID of the provisioning profile from the filename above. +For Xcode: + +```yaml +- task: Xcode@5 + inputs: + signingOption: 'manual' + signingIdentity: '$(APPLE_CERTIFICATE_SIGNING_IDENTITY)' + provisioningProfileUuid: '$(APPLE_PROV_PROFILE_UUID)' +``` -#### Authorize the agent to access the keychain -1. If you're using the Xamarin.iOS task and running the build agent as a launchd service, you'll need to set up the build to unlock the default keychain. +# [Classic](#tab/classic) - 1. Go to the **Variables** tab and add a new variable named `KEYCHAIN_PWD`. Set its value to the password to the default keychain. This is normally the password for the user that is starting the agent. _Be sure to select the "lock" icon to secure this password._ - 1. For the Xamarin.iOS task, under the **Signing & Provisioning** section, enable the **Unlock default keychain** checkbox and set the **Default keychain password** field to: `$(KEYCHAIN_PWD)` +For the **Xcode** task settings: -Save your build pipeline, and you're all set! The build agent will now be able to securely sign and provision your app. +- For the **Signing style** option, choose **Manual signing**. +- In the **Signing identity** field, enter `$(APPLE_CERTIFICATE_SIGNING_IDENTITY)`. +- In the **Provisioning profile UUID** field, enter `$(APPLE_PROV_PROFILE_UUID)`. --- -## FAQ - - +The pipeline build agent now securely signs and provisions your app without further certificate or profile management on the build machine itself. -[!INCLUDE [temp](../../includes/qa-agents.md)] +## Related content -::: moniker range="< azure-devops" -[!INCLUDE [temp](../../includes/qa-versions.md)] -::: moniker-end +For more information about: - +- Pipelines for Android apps, see [Build, test, and deploy Android apps](../../ecosystems/android.md). +- Pipelines for iOS apps, see [Build, test, and deploy Xcode apps](../../ecosystems/xcode.md). +- Agents, see [Azure Pipelines agents](../../agents/agents.md). +- Agent pools and queues, see [Create and manage agent pools](../../agents/pools-queues.md). +- Variables in pipelines, see [Define variables](../../process/variables.md). +- Pipeline troubleshooting, see [Troubleshoot pipeline runs](../../troubleshooting/troubleshooting.md). diff --git a/docs/pipelines/apps/mobile/includes/xamarin-license-credential-arguments.md b/docs/pipelines/apps/mobile/includes/xamarin-license-credential-arguments.md deleted file mode 100644 index 05d4e83f54c..00000000000 --- a/docs/pipelines/apps/mobile/includes/xamarin-license-credential-arguments.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -ms.topic: include -ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: jukullam -author: juliakm -ms.date: 02/14/2020 ---- - -
    • Email: $(xamarin.email)
      • -
    • Password: $(xamarin.password)
      • diff --git a/docs/pipelines/apps/mobile/media/secure-certs/android-signing-input-values.png b/docs/pipelines/apps/mobile/media/secure-certs/android-signing-input-values.png deleted file mode 100644 index 1cfc15c6344..00000000000 Binary files a/docs/pipelines/apps/mobile/media/secure-certs/android-signing-input-values.png and /dev/null differ diff --git a/docs/pipelines/apps/mobile/media/secure-certs/android-signing-variables.png b/docs/pipelines/apps/mobile/media/secure-certs/android-signing-variables.png deleted file mode 100644 index 6909df246a6..00000000000 Binary files a/docs/pipelines/apps/mobile/media/secure-certs/android-signing-variables.png and /dev/null differ diff --git a/docs/pipelines/apps/mobile/media/secure-certs/secure-certs.png b/docs/pipelines/apps/mobile/media/secure-certs/secure-certs.png new file mode 100644 index 00000000000..33d911d369e Binary files /dev/null and b/docs/pipelines/apps/mobile/media/secure-certs/secure-certs.png differ diff --git a/docs/pipelines/apps/windows/cpp.md b/docs/pipelines/apps/windows/cpp.md deleted file mode 100644 index b0f9e6961ae..00000000000 --- a/docs/pipelines/apps/windows/cpp.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Build C++ Windows apps -ms.custom: seodec18, devdivchpfy22 -ms.date: 06/08/2022 -description: Automatically build your C++ Windows app with Azure Pipelines, Azure DevOps, & Team Foundation Server -ms.assetid: 49886DF3-3689-48B3-8F1C-CA99DAFD1E49 -ms.topic: quickstart -monikerRange: '<= azure-devops' ---- - -# Build C++ Windows apps - -[!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../includes/concept-rename-note.md)] -::: moniker-end - -This article explains how to build C++ projects on Windows automatically. - -## Example - -This example shows how to build a C++ project. To start, import (into Azure Repos or TFS) or fork (into GitHub) this repo: - -``` -https://github.com/MicrosoftDocs/pipelines-cpp -``` - -::: moniker range="< azure-devops" - -> [!NOTE] -> This scenario works on TFS, but some of the following instructions might not exactly match the version of TFS that you are using. You'll need to set up a self-hosted agent, possibly also installing software. If you are a new user, you might have a better learning experience by trying this procedure out first using a free Azure DevOps organization. Then change the selector in the upper-left corner of this page from Team Foundation Server to **Azure DevOps**. - -::: moniker-end - -* After you have the sample code in your own repository, create a pipeline using the instructions in [Create your first pipeline](../../create-first-pipeline.md) and select the **.NET Desktop** template. This automatically adds the tasks required to build the code in the sample repository. - -* Save the pipeline and queue a build to see it in action. - -## Build multiple configurations - -It's often required to build your app in multiple configurations. The following steps extend the example above to build the app on four configurations: [Debug, x86], [Debug, x64], [Release, x86], [Release, x64]. - -1. Select the **Variables** tab and modify these variables: - - * `BuildConfiguration` = `debug, release` - - * `BuildPlatform` = `x86, x64` - -1. Select **Tasks** and click on the **agent job**. From the **Execution plan** section, select **Multi-configuration** to change the options for the job: - - * Specify **Multipliers:** `BuildConfiguration, BuildPlatform` - - * Specify **Maximum number of agents** - -1. Select **Parallel** if you have multiple build agents and want to build your configuration/platform pairings in parallel. - -## Copy output - -To copy the results of the build to Azure Pipelines select the [Copy Files task](/azure/devops/pipelines/tasks/reference/copy-files-v2). Specify the following arguments: - -``` - contents: '**\$(BuildConfiguration)\**\?(*.exe|*.dll|*.pdb)' -``` diff --git a/docs/pipelines/architectures/devops-pipelines-azure-web-apps-architecture.md b/docs/pipelines/architectures/devops-pipelines-azure-web-apps-architecture.md index 3cad3f173c1..8fa1f2a90ef 100644 --- a/docs/pipelines/architectures/devops-pipelines-azure-web-apps-architecture.md +++ b/docs/pipelines/architectures/devops-pipelines-azure-web-apps-architecture.md @@ -7,17 +7,7 @@ ms.category: - devops - web - featured -ms.custom: - - acom-architecture - - devops - - continuous integration - - continuous delivery - - CI/CD - - continuous deployment - - interactive-diagram - - pricing-calculator - - is-deployable - - "https://azure.microsoft.com/solutions/architecture/azure-devops-continuous-integration-and-continuous-deployment-for-azure-web-apps" +ms.custom: acom-architecture, devops, continuous integration, continuous delivery, CI/CD, continuous deployment, interactive-diagram, pricing-calculator, is-deployable, 'https://azure.microsoft.com/solutions/architecture/azure-devops-continuous-integration-and-continuous-deployment-for-azure-web-apps', devx-track-extended-java name: CI/CD for Azure Web Apps with Azure Pipelines azureCategories: - devops diff --git a/docs/pipelines/architectures/devops-pipelines-baseline-architecture.md b/docs/pipelines/architectures/devops-pipelines-baseline-architecture.md index e7f367e8088..31b8b22035e 100644 --- a/docs/pipelines/architectures/devops-pipelines-baseline-architecture.md +++ b/docs/pipelines/architectures/devops-pipelines-baseline-architecture.md @@ -1,7 +1,7 @@ --- title: Azure Pipelines baseline architecture description: This architecture illustrates building a continuous integration and deployment pipeline using Azure Pipelines. -ms.date: 05/08/2023 +ms.date: 01/24/2025 ms.topic: example-scenario ms.custom: - devops @@ -22,12 +22,12 @@ monikerRange: '<= azure-devops' This article describes a high-level DevOps workflow for deploying application changes to staging and production environments in Azure. The solution uses continuous integration/continuous deployment (CI/CD) practices with Azure Pipelines. > [!IMPORTANT] -> This article covers a general CI/CD architecture using Azure Pipelines. It is not intended to cover the specifics of deploying to different environments, such as Azure App Services, Virtual Machines, and Azure Power Platform. Deployment platform specifics are covered in separate articles. +> This article covers a general CI/CD architecture using Azure Pipelines. It isn't intended to cover the specifics of deploying to different environments, such as Azure App Services, Virtual Machines, and Azure Power Platform. Deployment platform specifics are covered in separate articles. ## Architecture :::image type="complex" source="media/azure-devops-ci-cd-architecture.svg" lightbox="media/azure-devops-ci-cd-architecture.svg" alt-text="Architecture diagram of a CI/CD pipeline using Azure Pipelines." border="false"::: -Architecture diagram of an Azure pipeline. The diagram shows the following steps: 1. An engineer pushing code changes to an Azure DevOps Git repository. 2. An Azure Pipelines PR pipeline getting triggered. This pipeline shows the following tasks: linting, restore, build, and unit tests. 3. An Azure Pipelines CI pipeline getting triggered. This pipeline shows the following tasks: get secrets, linting, restore, build, unit tests, integration tests and publishing build artifacts. 3. An Azure Pipelines CD pipeline getting triggered. This pipeline shows the following tasks: download artifacts, deploy to staging, tests, manual intervention, and release. 4. Shows the CD pipeline deploying to a staging environment. 5. Shows the CD pipeline releasing to a production environment. 6. Shows an operator monitoring the pipeline, taking advantage of Azure Monitor, Azure Application Insights and Azure Analytics Workspace. +Architecture diagram of an Azure pipeline. The diagram shows the following steps: 1. An engineer pushing code changes to an Azure DevOps Git repository. 2. An Azure Pipelines PR pipeline getting triggered. This pipeline shows the following tasks: linting, restore, build, and unit tests. 3. An Azure Pipelines CI pipeline getting triggered. This pipeline shows the following tasks: get secrets, linting, restore, build, unit tests, integration tests, and publishing build artifacts. 3. An Azure Pipelines CD pipeline getting triggered. This pipeline shows the following tasks: download artifacts, deploy to staging, tests, manual intervention, and release. 4. Shows the CD pipeline deploying to a staging environment. 5. Shows the CD pipeline releasing to a production environment. 6. Shows an operator monitoring the pipeline, taking advantage of Azure Monitor, Azure Application Insights, and Azure Analytics Workspace. :::image-end::: *Download a [Visio file](https://arch-center.azureedge.net/azure-devops-ci-cd-architecture.vsdx) of this architecture.* @@ -47,28 +47,29 @@ The data flows through the scenario as follows: If any of the checks fail, the pipeline run ends and the developer will have to make the required changes. If all checks pass, the pipeline should require a PR review. If the PR review fails, the pipeline ends and the developer will have to make the required changes. If all the checks and PR reviews pass, the PR will successfully merge. -1. **CI pipeline** - A merge to Azure Repos Git triggers a CI pipeline. This pipeline runs the same checks as the PR pipeline with some important additions. The CI pipeline runs integration tests. These integration tests shouldn't require the deployment of the solution, as the build artifacts haven't been created yet. If the integration tests require secrets, the pipeline gets those secrets from Azure Key Vault. If any of the checks fail, the pipeline ends and the developer will have to make the required changes. The result of a successful run of this pipeline is the creation and publishing of build artifacts +1. **CI pipeline** - A merge to Azure Repos Git triggers a CI pipeline. This pipeline runs the same checks as the PR pipeline with some important additions. The CI pipeline runs integration tests. Integration tests can be resource-intensive, so running them in the CI pipeline balances development speed and bug detection. It's also important to note that passing tests in a PR does not always ensure they will succeed after merging, as changes in the main branch can introduce new issues, highlighting the need for post-merge testing. These factors make the CI pipeline a better place for integration tests than the PR pipeline. +These integration tests shouldn't require the deployment of the solution, as the build artifacts haven't been created yet. If the integration tests require secrets, the pipeline gets those secrets from Azure Key Vault. If any of the checks fail, the pipeline ends and the developer will have to make the required changes. The result of a successful run of this pipeline is the creation and publishing of build artifacts. 1. **CD pipeline trigger** - The publishing of artifacts [triggers the CD pipeline](/azure/devops/pipelines/process/pipeline-triggers). 1. **CD release to staging** - The CD pipeline downloads the build artifacts that are created in the CI pipeline and deploys the solution to a staging environment. The pipeline then runs acceptance tests against the staging environment to validate the deployment. If any acceptance test fails, the pipeline ends and the developer will have to make the required changes. If the tests succeed, a [manual validation task](/azure/devops/pipelines/tasks/utility/manual-validation?tabs=yaml) can be implemented to require a person or group to validate the deployment and resume the pipeline. -1. **CD release to production** - If the manual intervention is resumed, or there's no manual intervention implemented, the pipeline releases the solution to production. The pipeline should run smoke tests in production to ensure the release is working as expected. If a manual intervention step results in a cancel, the release fails, or the smoke tests fail, the release is rolled back, the pipeline ends and the developer will have to make the required changes. +1. **CD release to production** - If the manual intervention is resumed, or there's no manual intervention implemented, the pipeline releases the solution to production. The pipeline should run smoke tests in production to ensure the release is working as expected. If a manual intervention step results in a cancel, the release fails, or the smoke tests fail, the release is rolled back, the pipeline ends, and the developer will have to make the required changes. 1. **Monitoring** - Azure Monitor collects observability data such as logs and metrics so that an operator can analyze health, performance, and usage data. Application Insights collects all application-specific monitoring data, such as traces. Azure Log Analytics is used to store all that data. ### Components -- An [Azure Repos](https://azure.microsoft.com/products/devops/repos) Git repository serves as a code repository that provides version control and a platform for collaborative projects. +- An [Azure Repos](/azure/devops/repos) Git repository serves as a code repository that provides version control and a platform for collaborative projects. -- [Azure Pipelines](https://azure.microsoft.com/products/devops/pipelines) provides a way to build, test, package and release application and infrastructure code. This example has three distinct pipelines with the following responsibilities: - - PR pipelines validate code before allowing a PR to merge through linting, building and unit testing. +- [Azure Pipelines](https://azure.microsoft.com/products/devops/pipelines) provides a way to build, test, package, and release application and infrastructure code. This example has three distinct pipelines with the following responsibilities: + - PR pipelines validate code before allowing a PR to merge through linting, building, and unit testing. - CI pipelines run after code is merged. They perform the same validation as PR pipelines, but add integration testing and publish build artifacts if everything succeeds. - CD pipelines deploy build artifacts, run acceptance tests, and release to production. - [Azure Artifact Feeds](/azure/devops/artifacts/concepts/feeds) allow you to manage and share software packages, such as Maven, npm, and NuGet. Artifact feeds allow you to manage the lifecycle of your packages, including versioning, promoting, and retiring packages. This helps you to ensure that your team is using the latest and most secure versions of your packages. -- [Key Vault](https://azure.microsoft.com/services/key-vault) provides a way to manage secure data for your solution, including secrets, encryption keys, and certificates. In this architecture, it's used to store application secrets. These secrets are accessed through the pipeline. Secrets can be accessed by Azure Pipelines with a [Key Vault task](/azure/devops/pipelines/tasks/deploy/azure-key-vault) or by [linking secrets from Key Vault](/azure/devops/pipelines/library/variable-groups?tabs=yaml#link-secrets-from-an-azure-key-vault). +- [Key Vault](/azure/key-vault) provides a way to manage secure data for your solution, including secrets, encryption keys, and certificates. In this architecture, it's used to store application secrets. These secrets are accessed through the pipeline. Secrets can be accessed by Azure Pipelines with a [Key Vault task](/azure/devops/pipelines/tasks/deploy/azure-key-vault) or by [linking secrets from Key Vault](/azure/devops/pipelines/library/variable-groups?tabs=yaml#link-secrets-from-an-azure-key-vault). - [Monitor](https://azure.microsoft.com/services/monitor) is an observability resource that collects and stores metrics and logs, application telemetry, and platform metrics for the Azure services. Use this data to monitor the application, set up alerts, dashboards, and perform root cause analysis of failures. @@ -80,7 +81,7 @@ The data flows through the scenario as follows: While this article focuses on Azure Pipelines, you could consider these alternatives: -- [Azure DevOps Server](https://azure.microsoft.com/services/devops/server) (previously known as Team Foundation Server) could be used as an on-premises substitute. +- [Azure DevOps Server](https://azure.microsoft.com/services/devops/server) could be used as an on-premises substitute. - [Jenkins](/azure/jenkins) is an open source tool used to automate builds and deployments. @@ -90,13 +91,13 @@ While this article focuses on Azure Pipelines, you could consider these alternat This article focuses on general CI/CD practices with Azure Pipelines. The following are some compute environments to which you could consider deploying: -- [App Services](https://azure.microsoft.com/services/app-service/web) is an HTTP-based service for hosting web applications, REST APIs, and mobile back ends. You can develop in your favorite language, and applications run and scale with ease on both Windows and Linux-based environments. Web Apps supports deployment slots like staging and production. You can deploy an application to a staging slot and release it to the production slot. +- [App Service](/azure/app-service) is an HTTP-based service for hosting web applications, REST APIs, and mobile back ends. You can develop in your favorite language, and applications run and scale with ease on both Windows and Linux-based environments. Web Apps supports deployment slots like staging and production. You can deploy an application to a staging slot and release it to the production slot. -- [Azure Virtual Machines](/azure/app-service/choose-web-site-cloud-service-vm) handles workloads that require a high degree of control, or depend on OS components and services that aren't possible with Web Apps (for example, the Windows GAC, or COM). +- [Azure Virtual Machines](/azure/virtual-machines) handles workloads that require a high degree of control, or depend on OS components and services that aren't possible with Web Apps. -- [Azure Power Platform](https://powerplatform.microsoft.com/) is a collection of cloud services that enable users to build, deploy, and manage applications without the need for infrastructure or technical expertise. +- [Azure Power Platform](/power-platform) is a collection of cloud services that enable users to build, deploy, and manage applications without the need for infrastructure or technical expertise. -- [Azure Functions](https://azure.microsoft.com/services/functions) is a serverless compute platform that you can use to build applications. With Functions, you can use triggers and bindings to integrate services. Functions also support deployment slots like staging and production. You can deploy an application to a staging slot and release it to the production slot. +- [Azure Functions](/azure/azure-functions/) is a serverless compute platform that you can use to build applications. With Functions, you can use triggers and bindings to integrate services. Functions also support deployment slots like staging and production. You can deploy an application to a staging slot and release it to the production slot. - [Azure Kubernetes Service (AKS)](/azure/aks) is a managed Kubernetes cluster in Azure. Kubernetes is an open source container orchestration platform. @@ -116,7 +117,7 @@ Using proven CI and CD practices to deploy application or infrastructure changes Consider Azure Pipelines and CI/CD processes for: -- Accelerating application development and development lifecycles. +- Accelerating application development and deployment lifecycles. - Building quality and consistency into an automated build and release process. - Increasing application stability and uptime. @@ -128,9 +129,9 @@ These considerations implement the pillars of the Azure Well-Architected Framewo - Consider implementing [Infrastructure as Code (IaC)](/devops/deliver/what-is-infrastructure-as-code) to define your infrastructure and to deploy it in your pipelines. -- Consider using one of the [tokenization tasks](https://marketplace.visualstudio.com/search?term=token&target=VSTS&category=All%20categories&sortBy=Relevance) available in the VSTS marketplace. +- Consider using one of the [Tokenization Tasks](https://marketplace.visualstudio.com/search?term=token&target=VSTS&category=All%20categories&sortBy=Relevance) available in the VSTS marketplace, in the context often refer to a process where sensitive information (such as API keys, passwords, or other secrets) is replaced with tokens or placeholders during deployment or configuration. -- Use [release variables](/azure/devops/pipelines/release/variables) in your release definitions to drive configuration changes of your environments. Release variables can be scoped to an entire release or a given environment. When using variables for secret information, ensure that you select the padlock icon. +- Use [Release Variables](/azure/devops/pipelines/release/variables) in your release definitions to drive configuration changes of your environments. Release variables can be scoped to an entire release or a given environment. When using variables for secret information, ensure that you select the padlock icon. - Consider using [Self-hosted agents](/azure/devops/pipelines/agents/agents?tabs=browser#install) if you're deploying to resources running in a secured virtual network. You might also consider self-hosted agents if you're running a high volume of builds. In cases of high build volumes, self-hosted agents can be used to speed up builds in a cost efficient manner. @@ -152,7 +153,7 @@ Azure DevOps costs depend on the number of users in your organization that requi This [pricing calculator](https://azure.com/e/498aa024454445a8a352e75724f900b1) provides an estimate for running Azure DevOps with 20 users. -Azure DevOps is billed on a per-user per-month basis. There might be more charges depending on concurrent pipelines needed, in addition to any additional test users or user basic licenses. +Azure DevOps is billed on a per-user per-month basis. There might be more charges depending on concurrent pipelines needed, in addition to any more test users or user basic licenses. ## Security @@ -168,7 +169,6 @@ Review the following resources to learn more about CI/CD and Azure DevOps: - [What is DevOps?](/devops/what-is-devops) - [DevOps at Microsoft - How we work with Azure DevOps](https://azure.microsoft.com/solutions/devops/devops-at-microsoft) -- [Step-by-step Tutorials: DevOps with Azure DevOps](https://www.azuredevopslabs.com/labs/vstsextend/azuredevopsprojectdotnet) - [Create a CI/CD pipeline for .NET with Azure DevOps Projects](/azure/devops-project/azure-devops-project-aspnet-core) - [What is Azure Repos?](/azure/devops/repos/get-started/what-is-repos) - [What is Azure Pipelines?](/azure/devops/pipelines/get-started/what-is-azure-pipelines) diff --git a/docs/pipelines/artifacts/artifacts-overview.md b/docs/pipelines/artifacts/artifacts-overview.md index 19c7f4b804f..bac3d5f9f0a 100644 --- a/docs/pipelines/artifacts/artifacts-overview.md +++ b/docs/pipelines/artifacts/artifacts-overview.md @@ -1,10 +1,9 @@ --- title: Artifacts in Azure Pipelines -ms.custom: seodec18 -description: Supported Artifacts in Azure Pipelines +description: Overview of Artifacts in Azure Pipelines ms.assetid: 34874DFA-2364-4C1D-A092-B8F67C499AB0 ms.topic: reference -ms.date: 01/11/2022 +ms.date: 12/05/2023 monikerRange: '<= azure-devops' "recommendations": "true" --- @@ -13,58 +12,100 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Azure Artifacts enable developers to consume and publish different types of packages to Artifacts feeds and public registries such as NuGet.org and npmjs.com. You can use Azure Artifacts in conjunction with Azure Pipelines to deploy packages, publish build artifacts, or integrate files between your pipeline stages to build, test, or deploy your application. +Azure Artifacts allow developers to publish and consume various types of packages from feeds and public registries like PyPI, Maven Central, and NuGet.org. You can combine Azure Artifacts with Azure Pipelines to publish build and pipeline artifacts, deploy packages, or integrate files across different stages of your pipeline for building, testing, or deploying your application. -## Supported artifact types +::: moniker range="azure-devops" + +## Supported artifacts | Artifact type | Description | |----------------------------------------------|------------------------------------------------------------------------------------------------------------------------| -| [Build artifacts](build-artifacts.md) | The files generated by a build. Example: .dll, .exe, or .PDB files. | -| [NuGet](nuget.md) | Publish NuGet packages to Azure Artifacts feeds or public registries such as nuget.org. | -| [npm](npm.md) | Publish npm packages to Azure Artifacts feeds or public registries such as nmpjs.com. | -| [Maven](publish-maven-artifacts.md) | Publish Maven packages to Azure Artifacts feeds. | -| [Python](pypi.md) | Publish Python packages to Azure Artifacts feeds or PyPI.org. | -| [Universal Packages](universal-packages.md) | Publish Universal Packages to Azure Artifacts feeds. | -| [Symbols](symbols.md) | Symbol files contain debugging information about the compiled executables. You can publish symbols to Azure Artifacts symbol server or to a file share. Symbol servers enable debuggers to automatically retrieve the correct symbol files without knowing the specific product, package, or build information. | - -## Publish and consume artifacts +| [Build artifacts](build-artifacts.md) | The files generated by a build. Example: .dll, .exe, and .PDB files. | +| [Pipeline artifacts](pipeline-artifacts.md) | Recommended for faster performance if you are using Azure DevOps Services. Not supported in release pipelines. | +| NuGet | Publish NuGet packages to Azure Artifacts feeds or public registries such as nuget.org. | +| npm | Publish npm packages to Azure Artifacts feeds or public registries such as npmjs.com. | +| Maven | Publish Maven packages to Azure Artifacts feeds or public registries such as Maven Central, Google Maven Repository, Gradle Plugins, and JitPack. | +| Python | Publish Python packages to Azure Artifacts feeds or public registries such as PyPI.org. | +| Cargo | Publish Cargo packages to Azure Artifacts feeds or public registries such as Crates.io. | +| Universal Packages | Publish Universal Packages to Azure Artifacts feeds or Universal Packages upstream sources. | +| Symbols | Publish symbols to Azure Artifacts symbol server or to a file share. | + +## Publish artifacts #### [NuGet](#tab/nuget/) -- [Publish a NuGet package using the command line](../../artifacts/nuget/publish.md) -- [Publish to NuGet feeds (YAML/Classic)](nuget.md) -- [Consume NuGet packages](../../artifacts/nuget/consume.md) +[Publish NuGet packages with Azure Pipelines (YAML/Classic)](nuget.md) #### [Npm](#tab/npm/) -- [Publish an npm package from the command line](../../artifacts/npm/publish.md) -- [Publish npm packages (YAML/Classic)](../tasks/package/npm.md#publish-npm-packages) -- [Consume npm packages](../../artifacts/get-started-npm.md) +[Publish npm packages (YAML/Classic)](../tasks/package/npm.md#publish-npm-packages) #### [Python](#tab/python/) -- [Publish Python packages](pypi.md) -- [Consume Python packages](../../artifacts/quickstarts/python-cli.md) +[Publish Python packages with Azure Pipelines](pypi.md) #### [Maven](#tab/maven/) -- [Maven quickstart](../../artifacts/get-started-maven.md) -- [Publish Maven Artifacts with Azure Pipelines](publish-maven-artifacts.md) -- [Publish Maven Artifacts with Gradle](pull-package-gradle.md) +[Publish Maven artifacts with Azure Pipelines](publish-maven-artifacts.md) + +#### [Gradle](#tab/gradle/) + +[Build and publish artifacts with Gradle and Azure Pipelines](build-publish-artifacts-gradle.md) #### [Universal Packages](#tab/universal-packages/) -- [Publish Universal Packages](./universal-packages.md#publish-a-universal-package) -- [Consume Universal Packages](./universal-packages.md#download-a-universal-package) +[Publish and download Universal Packages with Azure Pipelines](./universal-packages.md) + +* * * + +::: moniker-end + +::: moniker range="<=azure-devops-2022" + +## Supported artifacts + +| Artifact type | Description | +|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------| +| [Build artifacts](build-artifacts.md) | The files generated by a build. Example: .dll, .exe, and .PDB files. | +| NuGet | Publish NuGet packages to Azure Artifacts feeds or public registries such as nuget.org. | +| npm | Publish npm packages to Azure Artifacts feeds or public registries such as npmjs.com. | +| Maven | Publish Maven packages to Azure Artifacts feeds or public registries such as Maven Central, Google Maven Repository, Gradle Plugins, and JitPack. | +| Python | Publish Python packages to Azure Artifacts feeds or public registries such as PyPI.org. | +| Symbols | Publish symbols to Azure Artifacts symbol server or to a file share. | + +## Publish artifacts + +#### [NuGet](#tab/nugetserver/) + +[Publish NuGet packages with Azure Pipelines (YAML/Classic)](nuget.md) + +#### [Npm](#tab/npmserver/) + +[Publish npm packages (YAML/Classic)](../tasks/package/npm.md#publish-npm-packages) + +#### [Maven](#tab/mavenserver/) + +[Publish Maven artifacts with Azure Pipelines](publish-maven-artifacts.md) + +#### [Gradle](#tab/gradleserver/) + +[Build and publish artifacts with Gradle and Azure Pipelines](build-publish-artifacts-gradle.md) + +#### [Python](#tab/pythonserver/) + +[Publish Python packages with Azure Pipelines](pypi.md) * * * +::: moniker-end + > [!TIP] > If your organization is using a firewall or a proxy server, make sure you allow [Azure Artifacts Domain URLs and IP addresses](../../organizations/security/allow-list-ip-url.md#azure-artifacts). -## Next steps +## Related articles + +- [Publish and download pipeline artifacts](pipeline-artifacts.md) + +- [Publish and download build artifacts](build-artifacts.md) -> [!div class="nextstepaction"] -> [Publish and download Pipeline Artifacts](pipeline-artifacts.md) -> [Build Artifacts](build-artifacts.md) -> [Release artifacts and artifact sources](../release/artifacts.md) +- [Artifact sources](../release/artifacts.md) diff --git a/docs/pipelines/artifacts/build-artifacts.md b/docs/pipelines/artifacts/build-artifacts.md index 928f8dd7dc1..df67f3e5507 100644 --- a/docs/pipelines/artifacts/build-artifacts.md +++ b/docs/pipelines/artifacts/build-artifacts.md @@ -1,14 +1,13 @@ --- title: Publish and download build artifacts -description: How to use Artifacts in Azure Pipelines -ms.custom: seodec18 +description: How to publish and download build artifacts with Azure Pipelines ms.assetid: 34874DFA-2364-4C1D-A092-B8F67C499AB0 ms.topic: reference ms.date: 04/21/2022 monikerRange: '<= azure-devops' --- -# Artifacts in Azure Pipelines +# Publish and download build artifacts [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -26,28 +25,29 @@ Azure Artifacts enables teams to use feeds and upstream sources to manage their Artifacts can be published at any stage of your pipeline. You can use YAML or the classic Azure DevOps editor to publish your packages. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ```yaml - powershell: gci env:* | sort-object name | Format-Table -AutoSize | Out-File $env:BUILD_ARTIFACTSTAGINGDIRECTORY/environment-variables.txt +- task: CopyFiles@2 + inputs: + sourceFolder: '$(Build.SourcesDirectory)' + contents: '**/$(BuildConfiguration)/**/?(*.exe|*.dll|*.pdb)' + targetFolder: '$(Build.ArtifactStagingDirectory)' - task: PublishBuildArtifacts@1 inputs: pathToPublish: '$(Build.ArtifactStagingDirectory)' artifactName: drop ``` -* **pathToPublish**: the path of your artifact. This can be an absolute or a relative path. Wildcards are not supported. +* **pathToPublish**: the path of your artifact. This can be an absolute or a relative path. Wildcards aren't supported. * **artifactName**: the name of your artifact. > [!NOTE] -> Make sure you are not using one of the reserved folder names when publishing your artifact. See [Application Folders](/previous-versions/ex526337(v=vs.140)#application-folders) for more details. +> Make sure you aren't using one of the reserved folder names when publishing your artifact. See [Application Folders](/previous-versions/ex526337(v=vs.140)#application-folders) for more details. ::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) Add the **Publish Build Artifacts** task to your pipeline and fill out the required fields. Make sure your file is at the root of your repository. @@ -59,10 +59,15 @@ Add the **Publish Build Artifacts** task to your pipeline and fill out the requi ### Example: Use multiple tasks #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ```yaml - powershell: gci env:* | sort-object name | Format-Table -AutoSize | Out-File $env:BUILD_ARTIFACTSTAGINGDIRECTORY/environment-variables.txt +- task: CopyFiles@2 + inputs: + sourceFolder: '$(Build.SourcesDirectory)' + contents: '**/$(BuildConfiguration)/**/?(*.exe|*.dll|*.pdb)' + targetFolder: '$(Build.ArtifactStagingDirectory)' - task: PublishBuildArtifacts@1 inputs: pathToPublish: '$(Build.ArtifactStagingDirectory)' @@ -73,15 +78,11 @@ Add the **Publish Build Artifacts** task to your pipeline and fill out the requi artifactName: drop2 ``` -* **pathToPublish**: the path of your artifact. This can be an absolute or a relative path. Wildcards are not supported. +* **pathToPublish**: the path of your artifact. This can be an absolute or a relative path. Wildcards aren't supported. * **artifactName**: the name of your artifact. ::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) You can add multiple **Publish Build Artifacts** tasks to your pipelines. Make sure your file is at the root of your repository. @@ -93,7 +94,7 @@ You can add multiple **Publish Build Artifacts** tasks to your pipelines. Make s ### Example: Copy and publish binaries #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ```yaml - powershell: gci env:* | sort-object name | Format-Table -AutoSize | Out-File $env:BUILD_ARTIFACTSTAGINGDIRECTORY/environment-variables.txt @@ -110,7 +111,7 @@ You can add multiple **Publish Build Artifacts** tasks to your pipelines. Make s * **sourceFolder**: the folder that contains the files you want to copy. If you leave this empty, copying will be done from **$(Build.SourcesDirectory)**. * **contents**: File paths to include as part of the copy. * **targetFolder**: destination folder. -* **pathToPublish**: the folder or file path to publish. It can be an absolute or a relative path. Wildcards are not supported. +* **pathToPublish**: the folder or file path to publish. It can be an absolute or a relative path. Wildcards aren't supported. * **artifactName**: the name of the artifact that you want to create. > [!NOTE] @@ -118,10 +119,6 @@ You can add multiple **Publish Build Artifacts** tasks to your pipelines. Make s ::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) :::image type="icon" source="../tasks/utility/media/copy-files.png" border="false"::: **Utility: Copy Files** @@ -140,10 +137,13 @@ YAML is not supported in TFS. * * * +> [!NOTE] +> `Build.ArtifactStagingDirectory` path is cleaned up after each build. If you're using this path to publish your artifact, make sure you copy the content you wish to publish into this directory before the publishing step. + ## Download artifacts #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ```yaml - powershell: gci env:* | sort-object name | Format-Table -AutoSize | Out-File $env:BUILD_ARTIFACTSTAGINGDIRECTORY/environment-variables.txt @@ -161,10 +161,6 @@ YAML is not supported in TFS. ::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) :::image type="icon" source="../tasks/utility/media/downloadbuildartifacts.png" border="false"::: **Utility: Download Build Artifacts** @@ -180,9 +176,9 @@ YAML is not supported in TFS. * * * > [!NOTE] -> If you are using a deployment task, you can reference your build artifacts using **$(Agent.BuildDirectory)**. See [Agent variables](../build/variables.md#agent-variables) for more details. +> If you're using a deployment task, you can reference your build artifacts using **$(Agent.BuildDirectory)**. See [Agent variables](../build/variables.md#agent-variables) for more details. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" When your pipeline run is completed, navigate to **Summary** to explore or download your artifact. @@ -191,41 +187,55 @@ When your pipeline run is completed, navigate to **Summary** to explore or downl ::: moniker-end -::: moniker range="tfs-2018" +## Download a specific artifact -When your pipeline run is completed, select **Artifacts** to download your artifact. +#### [YAML](#tab/yaml/) -> [!div class="mx-imgBorder"] -> ![Published build artifact TFS](media/build-artifact-tab.png) +```yaml +steps: +- task: DownloadBuildArtifacts@1 + displayName: 'Download Build Artifacts' + inputs: + buildType: specific + project: 'xxxxxxxxxx-xxxx-xxxx-xxxxxxxxxxx' + pipeline: 20 + buildVersionToDownload: specific + buildId: 128 + artifactName: drop + extractTars: false +``` -::: moniker-end +#### [Classic](#tab/classic/) -::: moniker range="tfs-2018" +Add the :::image type="icon" source="../tasks/utility/media/downloadbuildartifacts.png" border="false"::: **Download Build Artifacts** task to your pipeline definition and configure it as follows: -## Publish from TFS to a UNC file share +:::image type="content" source="media/download-specific-build-artifact.png" alt-text="A screenshot that shows a Maven package deployed to a feed." lightbox="media/download-specific-build-artifact.png"::: -If you're using a private Windows agent, you can set the **artifact publish location** option (**TFS 2018 RTM and older**: artifact type) to publish your files to a UNC **file share**. +- **Download artifacts produced by**: Specific build. -> [!NOTE] -> Use a Windows build agent. This option doesn't work for macOS and Linux agents. +- **Project**: select your project from the dropdown menu. -Choose **file share** to copy the artifact to a file share. Common reasons to do this: +- **Build pipeline**: select your build pipeline. -* The size of your drop is large and consumes too much time and bandwidth to copy. +- **Build version to download**: select specific version. -* You need to run some custom scripts or other tools against the artifact. +- **Build**: select your build from the dropdown menu. -If you use a file share, specify the UNC file path to the folder. You can control how the folder is created for each build by using [variables](../build/variables.md). For example: ```\\my\share\$(Build.DefinitionName)\$(Build.BuildNumber)```. +- **Download type**: specific artifact. -::: moniker-end +- **Artifact name**: select your artifact from the dropdown menu. + +- **Destination directory**: default $(System.ArtifactsDirectory). + +* * * ## Tips -- Disable IIS Basic Authentication if you are using Azure DevOps Server to allow authentication with your Personal Access Token. See [IIS Basic Authentication and PATs](../../integrate/get-started/authentication/iis-basic-auth.md) for more details. +- Disable IIS Basic Authentication if you're using Azure DevOps Server to allow authentication with your Personal Access Token. For more information, see [Why did my PAT stop working?](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#q-why-did-my-pat-stop-working). - Use forward slashes in file path arguments. Backslashes don't work in macOS/Linux agents. -- Build artifacts are stored on a Windows filesystem, which causes all UNIX permissions to be lost, including the execution bit. You might need to restore the correct UNIX permissions after downloading your artifacts from Azure Pipelines or TFS. +- Build artifacts are stored on a Windows filesystem, which causes all UNIX permissions to be lost, including the execution bit. You might need to restore the correct UNIX permissions after downloading your artifacts from Azure Pipelines. - `Build.ArtifactStagingDirectory` and `Build.StagingDirectory` are interchangeable. @@ -233,7 +243,7 @@ If you use a file share, specify the UNC file path to the folder. You can contro - Deleting a build associated with packages published to a file share will result in the deletion of all Artifacts in that UNC path. -- If you are publishing your packages to a file share, make sure you provide access to the build agent. +- If you're publishing your packages to a file share, make sure you provide access to the build agent. - Make sure you allow [Azure Artifacts Domain URLs and IP addresses](../../organizations/security/allow-list-ip-url.md#azure-artifacts) if your organization is using a firewall. diff --git a/docs/pipelines/artifacts/build-publish-artifacts-gradle.md b/docs/pipelines/artifacts/build-publish-artifacts-gradle.md new file mode 100644 index 00000000000..88a2c56c0e1 --- /dev/null +++ b/docs/pipelines/artifacts/build-publish-artifacts-gradle.md @@ -0,0 +1,90 @@ +--- +title: Build and publish pipeline artifacts with Gradle +description: Learn how to build and publish your pipeline artifact with Gradle and Azure Pipelines. +ms.reviewer: dastahel +ms.topic: how-to +ms.date: 02/10/2025 +monikerRange: '<= azure-devops' +"recommendations": "true" +--- + +# Build and publish pipeline artifacts with Gradle and Azure Pipelines + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +Gradle is a popular build tool for Java applications and the primary build tool for Android. Using Azure Pipelines, you can build and publish your pipeline artifacts using both YAML and Classic pipelines. + +## Prerequisites + +- An [Azure DevOps organization](../../organizations/accounts/create-organization.md). + +- An [Azure DevOps project](../../organizations/projects/create-project.md#create-a-project). + +## Build and publish pipeline artifacts + +#### [YAML](#tab/yaml/) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select your pipeline definition. + +1. Select **Edit**, and then add the following snippet to your YAML pipeline. + + ```yaml + steps: + - task: Gradle@4 + displayName: 'gradlew build' + + - task: CopyFiles@2 + displayName: 'Copy Files to: $(Pipeline.Workspace)' + inputs: + TargetFolder: '$(Pipeline.Workspace)' + + - task: PublishPipelineArtifact@1 + displayName: 'Publish Pipeline Artifact' + ``` + +### [Classic](#tab/classic/) + +::: moniker range="azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +::: moniker-end + +::: moniker range="< azure-devops" + +1. Sign in to your Azure DevOps collection, and then navigate to your project. + +::: moniker-end + +::: moniker range="<=azure-devops" + +2. Select **Pipelines**, and then select your pipeline definition. + +::: moniker-end + +3. Select **Edit**, and then select the `+` sign to add a new task. Add the *Gradle*, *Copy Files*, and *Publish Pipeline Artifact* tasks to your pipeline definition and configure them as follows: + + 1. **Gradle**: leave the default settings. + + 1. **Copy Files**: set the *Target Folder* to $(Pipeline.Workspace). + + 1. **Publish Pipeline Artifact**: make sure the *File or directory path* is set to $(Pipeline.Workspace) and the *Artifact publish location* is Azure Pipelines. + +4. Select **Save & queue** when you're done. + +5. You can view your published artifact in your pipeline **Summary** once the run is complete. + + :::image type="content" source="media\published-artifact.png" alt-text="Screenshot showing the published artifact in the pipeline summary."::: + +--- + +> [!TIP] +> To keep the Gradle daemon running, consider adding `org.gradle.daemon=true` to your *gradle.properties* file. + +## Related content + +- [Publish and download pipeline Artifacts](./pipeline-artifacts.md) +- [Artifact sources in Classic release pipelines](../release/artifacts.md) +- [Use the .artifactignore file](../../artifacts/reference/artifactignore.md) \ No newline at end of file diff --git a/docs/pipelines/artifacts/caching-nuget.md b/docs/pipelines/artifacts/caching-nuget.md index d923985cc22..7667720b2b6 100644 --- a/docs/pipelines/artifacts/caching-nuget.md +++ b/docs/pipelines/artifacts/caching-nuget.md @@ -1,25 +1,35 @@ --- -title: Cache NuGet packages to reduce build time -description: How to cache NuGet packages in Azure Pipelines -ms.topic: conceptual +title: Cache NuGet packages +description: Learn how to cache NuGet packages in Azure Pipelines +ms.topic: how-to ms.author: rabououn author: ramiMSFT -ms.date: 06/06/2023 -monikerRange: 'azure-devops' +ms.date: 03/10/2025 +monikerRange: ">= azure-devops-2020" "recommendations": "true" --- # Cache NuGet packages -**Azure DevOps Services** +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] + +Pipeline caching helps reduce build time by storing dependencies for reuse in future runs. In this article, you learn how to use the [Cache task](/azure/devops/pipelines/tasks/reference/cache-v2) to cache and restore your NuGet packages. + +> [!NOTE] +> Pipeline caching is not supported in Classic release pipelines. + +## Prerequisites + +| **Product** | **Requirements** | +|-------------------|------------------| +| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).
      - **Permissions:**
          - To grant access to all pipelines in the project, you must be a member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md). | -With pipeline caching, you can reduce your build time by caching your dependencies to be reused in later runs. In this article, you'll learn how to use the [Cache task](/azure/devops/pipelines/tasks/reference/cache-v2) to cache and restore your NuGet packages. ## Lock dependencies -To set up the cache task, we must first lock our project's dependencies and create a **package.lock.json** file. We'll use the hash of the content of this file to generate a unique key for our cache. +Before setting up the cache task, you need to lock your project's dependencies and generate a **package.lock.json** file. The unique cache key is derived from the hash of the content of this lock file to ensure consistency across builds. -To lock your project's dependencies, set the **RestorePackagesWithLockFile** property in your *csproj* file to **true**. NuGet restore generates a lock file **packages.lock.json** at the root directory of your project. Make sure you check your **packages.lock.json** file into your source code. +To lock your project's dependencies, add the **RestorePackagesWithLockFile** property to your *csproj* file and set it to **true**. When you run `nuget restore`, it generates a **packages.lock.json** file in your project's root directory. Make sure you check your **packages.lock.json** file into your source code. ```XML @@ -29,18 +39,18 @@ To lock your project's dependencies, set the **RestorePackagesWithLockFile** pro ## Cache NuGet packages -We'll need to create a pipeline variable to point to the location of our packages on the agent running the pipeline. +To cache NuGet packages, define a pipeline variable that points to the location of the packages on the agent running the pipeline. -In this example, the content of the **packages.lock.json** will be hashed to produce a dynamic cache key. This ensures that every time the file is modified, a new cache key is generated. +In the example below, the content of the **packages.lock.json** is hashed to generate a dynamic cache key. This ensures that whenever the file changes, a new cache key is created. -:::image type="content" source="media/cache-key-hash.png" alt-text="A screenshot showing how the cache key is generated in Azure Pipelines."::: +:::image type="content" source="media/cache-key-hash.png" alt-text="A screenshot displaying how the cache key is generated in Azure Pipelines." lightbox="media/cache-key-hash.png"::: ```YAML variables: NUGET_PACKAGES: $(Pipeline.Workspace)/.nuget/packages - task: Cache@2 - displayName: Cache + displayName: Cache v2 task inputs: key: 'nuget | "$(Agent.OS)" | **/packages.lock.json,!**/bin/**,!**/obj/**' restoreKeys: | @@ -50,9 +60,12 @@ variables: cacheHitVar: 'CACHE_RESTORED' ``` +> [!NOTE] +> Caches are immutable, once a cache is created, its contents cannot be modified. + ## Restore cache -This task will only run if the `CACHE_RESTORED` variable is false. +The following task will only run if the `CACHE_RESTORED` variable is **false**. This means that if a cache hit occurs (the packages are already available in the cache), the restore step is skipped to save time and resources. If no cache is found, the restore command runs to download the necessary dependencies. ```YAML - task: NuGetCommand@2 @@ -62,13 +75,25 @@ This task will only run if the `CACHE_RESTORED` variable is false. restoreSolution: '**/*.sln' ``` -If you encounter the error message "project.assets.json not found" during your build task, you can resolve it by removing the condition `condition: ne(variables.CACHE_RESTORED, true)` from your restore task. By doing so, the restore command will be executed, generating your project.assets.json file. The restore task will not download packages that are already present in your corresponding folder. +> [!NOTE] +> If you're using Ubuntu 24.04 or later, you must use the `NuGetAuthenticate` task with the .NET CLI instead of the `NuGetCommand@2` task. See [Support for newer Ubuntu hosted images](/azure/devops/pipelines/tasks/reference/nuget-command-v2#support-for-newer-ubuntu-hosted-images) for more details. + +#### Handle "project.assets.json not found" errors + +If you encounter the error *"project.assets.json not found"* during your build task, remove the condition `condition: ne(variables.CACHE_RESTORED, true)` from your restore task. This ensures the restore command runs and generates the *project.assets.json* file. The restore task won't redownload packages that are already present in the corresponding folder. + +> [!NOTE] +> A pipeline can include multiple caching tasks, and jobs and tasks within the same pipeline can access and share the same cache. ## Performance comparison -Pipeline caching is a great way to speed up your pipeline execution. Here's a side-by-side performance comparison for two different pipelines. Before adding the caching task (right), the restore task took approximately 41 seconds. We added the caching task to a second pipeline (left) and configured the restore task to run when a cache miss is encountered. The restore task in this case took 8 seconds to complete. +Pipeline caching significantly reduces the time required to restore dependencies, leading to faster builds. The following comparison illustrates the impact of caching on pipeline execution time for two different pipelines: + +- **Without caching (right)**: The restore task took approximately 41 seconds. + +- **With caching (left)**: We added the caching task to a second pipeline and configured the restore task to run only when a cache miss occurs. The restore task in this case completed in just 8 seconds. -:::image type="content" source="media/caching-performance.png" alt-text="A screenshot showing the pipeline performance with and without caching."::: +:::image type="content" source="media/caching-performance.png" alt-text="A screenshot displaying the pipeline performance with and without caching."::: Below is the full YAML pipeline for reference: @@ -111,8 +136,12 @@ steps: configuration: '$(buildConfiguration)' ``` -## Related articles +This approach also applies to .NET Core projects, provided your project uses *packages.lock.json* to lock package versions. You can enable this by setting `RestorePackagesWithLockFile` to `True` in your * Csproj* file, or by running the following command: `dotnet restore --use-lock-file`. + +## Related content - [Pipeline caching](../release/caching.md) -- [Deploy from multiple branches](../release/deploy-multiple-branches.md) -- [Deploy pull request Artifacts](../release/deploy-pull-request-builds.md) \ No newline at end of file + +- [Deploy pull request Artifacts (Classic)](../release/deploy-pull-request-builds.md) + +- [Deploy to different stages (Classic)](../release/deploy-multiple-branches.md) diff --git a/docs/pipelines/artifacts/cargo-pipelines.md b/docs/pipelines/artifacts/cargo-pipelines.md new file mode 100644 index 00000000000..9619f12ad60 --- /dev/null +++ b/docs/pipelines/artifacts/cargo-pipelines.md @@ -0,0 +1,194 @@ +--- +title: Publish Cargo packages with Azure Pipelines +description: Learn how to publish Cargo packages to an Azure Artifacts feed with Azure Pipelines. +ms.subservice: azure-devops-pipelines-artifacts +ms.author: rabououn +author: ramiMSFT +ms.topic: quickstart +ms.date: 12/17/2024 +monikerRange: '>= azure-devops-2022' +"recommendations": "true" +--- + +# Publish Cargo packages with Azure Pipelines + +[!INCLUDE [version-gt-eq-2022](../../includes/version-gt-eq-2022.md)] + +Azure Pipelines enables developers to publish Cargo packages to Azure Artifacts feeds and public registries such as Crates.io. In this article, you will learn how to publish your Cargo packages to an Azure Artifacts feed using both YAML and Classic pipelines. + +## Prerequisites + +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- An Azure Artifacts feed. [Create a feed](../../artifacts/concepts/feeds.md#create-a-public-feed) if you don't have one already. + +## Authenticate with a feed + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Artifacts**, and then select your feed. + +1. Select **Connect to feed**, and then select **Cargo** from the left pane. + +1. Copy the provided snippet from the **Project setup** section and add it to your *config.toml* file in your source repository. You file should look like this: + + - Project-scoped feed: + + ``` + [registries] + = { index = "sparse+https://pkgs.dev.azure.com///_packaging//Cargo/index/" } + + [source.crates-io] + replace-with = "" + ``` + + - Organization-scoped feed: + + ``` + [registries] + = { index = "sparse+https://pkgs.dev.azure.com//_packaging//Cargo/index/" } + + [source.crates-io] + replace-with = "" + ``` + +1. Create a [Personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scopes to authenticate with your feed. + +# [YAML](#tab/yaml) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select your pipeline definition. + +1. Select **Edit**, and then add the following snippet to your YAML pipeline. + + ```yaml + - task: CargoAuthenticate@0 + displayName: 'Cargo Authenticate' + inputs: + configFile: '.cargo/config.toml' ## Path to the config.toml file that specifies the registries you want to work with. Select the file, not the folder e.g. "/.cargo/config.toml" + ``` + +# [Classic](#tab/classic) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, select your pipeline definition, and then select **Edit**. + +1. Select the `+` sign to add a new task. Search for the **Cargo Authenticate** task, and then select **Add** to add it to your pipeline. + +1. Select the ellipsis icon to open a new window displaying your repository contents, and then choose your *config.toml* file. + + :::image type="content" source="media/cargo-publish-classic.png" alt-text="A screenshot displaying how to configure the Cargo authenticate task in a Classic pipeline."::: + +* * * + +## Publish crates to a feed + +# [YAML](#tab/yaml) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select your pipeline definition. + +1. Select **Edit**, and then add the following snippet to your YAML pipeline. + + ```yaml + - powershell: | + cargo publish --registry ## Replace the placeholder with your feed name + env: + SYSTEM_ACCESSTOKEN: $(system.accesstoken) + ``` + +# [Classic](#tab/classic) + +1. From your Azure DevOps project, select **Pipelines**, select your pipeline definition, and then select **Edit**. + +1. Select the `+` sign to add a new task, then add the **Command line** task to your pipeline definition. + +1. Give your task a name, and then paste the following command into the **Script** textbox, replacing the placeholder with your feed name: + + ```PowerShell + cargo publish --registry + ``` + +1. Select your agent job, scroll down to **Additional options**, and make sure you check the **Allow scripts to access the OAuth token** checkbox. + +:::image type="content" source="media/publish-crate-cl-pipeline.png" alt-text="A screenshot displaying how to configure the publish task in a Classic pipeline."::: + +* * * + +## Example + +The following example shows how to install Rustup on the agent, configure the PATH environment variable, build the project, authenticate with CargoAuthenticate, and publish to an Azure Artifacts feed: + +# [Windows](#tab/windows) + +```yaml +trigger: +- main + +pool: + vmImage: windows-latest + +steps: +- powershell: | + Invoke-WebRequest -Uri https://sh.rustup.rs -OutFile rustup-init.sh + bash .\rustup-init.sh -y + echo "##vso[task.prependpath]$env:USERPROFILE\.cargo\bin" + displayName: Install + +- task: CargoAuthenticate@0 + displayName: 'cargo Authenticate' + inputs: + configFile: '.cargo/config.toml' + +- script: | + cargo build --all + displayName: Build + +- powershell: | + cargo publish --registry CargoInternalFeed + displayName: Publish +``` + +# [Linux](#tab/linux) + +```yaml +trigger: +- main + +pool: + vmImage: ubuntu-latest + +steps: +- script: | + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y + echo "##vso[task.prependpath]$HOME/.cargo/bin" + displayName: Install + +- task: CargoAuthenticate@0 + displayName: 'cargo Authenticate' + inputs: + configFile: '.cargo/config.toml' + +- script: | + cargo build --all + displayName: Build + +- powershell: | + cargo publish --registry CargoInternalFeed + displayName: Publish +``` + +* * * + +Once your pipeline run completes, your crate should be available in your feed, as shown below: + +:::image type="content" source="media/published-crate-to-feed.png" alt-text="A screenshot showing the hello-world-cargo crate published to the feed."::: + +## Related articles + +- [Delete/Yank Cargo packages](../../artifacts/how-to/delete-and-recover-packages.md?tabs=cargo) +- [Promote a package to a view](../../artifacts/feeds/views.md) +- [Feed permissions](../../artifacts/feeds/feed-permissions.md) diff --git a/docs/pipelines/artifacts/cargo-publish-classic.png b/docs/pipelines/artifacts/cargo-publish-classic.png new file mode 100644 index 00000000000..97452e1833f Binary files /dev/null and b/docs/pipelines/artifacts/cargo-publish-classic.png differ diff --git a/docs/pipelines/artifacts/includes/package-management-permissions-for-web-build.md b/docs/pipelines/artifacts/includes/package-management-permissions-for-web-build.md index 5dee061516f..dbe6b649ebf 100644 --- a/docs/pipelines/artifacts/includes/package-management-permissions-for-web-build.md +++ b/docs/pipelines/artifacts/includes/package-management-permissions-for-web-build.md @@ -7,7 +7,7 @@ author: ramiMSFT ms.date: 02/19/2020 --- -To publish packages to an Azure Artifacts feed from your pipeline, set the identity under which the build runs as a feed **Contributor**.If your build pipeline is configured to run using the project collection scope, add the **Project Collection Build Service** identity as a feed **Contributor**. +To publish packages to an Azure Artifacts feed from your pipeline, set the identity under which the build runs as a **Feed Publisher (Contributor)**. If your build pipeline is configured to run using the project collection scope, add the **Project Collection Build Service** identity as a feed **Feed Publisher (Contributor)**. If your build pipeline is configured to run using project scope, then the **Project Build Service** identity should be given contributor access to the feed. You can check the scope in which your builds run by opening the pipeline editor and checking the **Options** tab. diff --git a/docs/pipelines/artifacts/includes/package-management-permissions-for-yaml-build.md b/docs/pipelines/artifacts/includes/package-management-permissions-for-yaml-build.md index 0f0fdc3fead..d2103dfe48c 100644 --- a/docs/pipelines/artifacts/includes/package-management-permissions-for-yaml-build.md +++ b/docs/pipelines/artifacts/includes/package-management-permissions-for-yaml-build.md @@ -6,4 +6,4 @@ ms.author: rabououn author: ramiMSFT ms.date: 02/19/2020 --- -To publish to an Azure Artifacts feed, set the **Project Collection Build Service** identity to be a **Contributor** on the feed. To learn more about permissions to Package Management feeds, see [Secure and share packages using feed permissions](../../../artifacts/feeds/feed-permissions.md). \ No newline at end of file +To publish to an Azure Artifacts feed, set the **Project Collection Build Service** identity to be a **Feed Publisher (Contributor)** on the feed. To learn more about permissions to Package Management feeds, see [Secure and share packages using feed permissions](../../../artifacts/feeds/feed-permissions.md). diff --git a/docs/pipelines/artifacts/media/cargo-authenticate-classic.png b/docs/pipelines/artifacts/media/cargo-authenticate-classic.png new file mode 100644 index 00000000000..7e9fb852f47 Binary files /dev/null and b/docs/pipelines/artifacts/media/cargo-authenticate-classic.png differ diff --git a/docs/pipelines/artifacts/media/cargo-pat-variable.png b/docs/pipelines/artifacts/media/cargo-pat-variable.png new file mode 100644 index 00000000000..7b244c39ed8 Binary files /dev/null and b/docs/pipelines/artifacts/media/cargo-pat-variable.png differ diff --git a/docs/pipelines/artifacts/media/cargo-private-feed.png b/docs/pipelines/artifacts/media/cargo-private-feed.png new file mode 100644 index 00000000000..5cd7c9b7370 Binary files /dev/null and b/docs/pipelines/artifacts/media/cargo-private-feed.png differ diff --git a/docs/pipelines/artifacts/media/cargo-publish-classic.png b/docs/pipelines/artifacts/media/cargo-publish-classic.png new file mode 100644 index 00000000000..97452e1833f Binary files /dev/null and b/docs/pipelines/artifacts/media/cargo-publish-classic.png differ diff --git a/docs/pipelines/artifacts/media/classic-pipeline-link-process-parameters.png b/docs/pipelines/artifacts/media/classic-pipeline-link-process-parameters.png new file mode 100644 index 00000000000..abc2941170a Binary files /dev/null and b/docs/pipelines/artifacts/media/classic-pipeline-link-process-parameters.png differ diff --git a/docs/pipelines/artifacts/media/classic-pipeline-new-process-parameters.png b/docs/pipelines/artifacts/media/classic-pipeline-new-process-parameters.png new file mode 100644 index 00000000000..87c61438114 Binary files /dev/null and b/docs/pipelines/artifacts/media/classic-pipeline-new-process-parameters.png differ diff --git a/docs/pipelines/artifacts/media/classic-pipeline-process-parameters-unlink-all.png b/docs/pipelines/artifacts/media/classic-pipeline-process-parameters-unlink-all.png new file mode 100644 index 00000000000..1cf0190a26b Binary files /dev/null and b/docs/pipelines/artifacts/media/classic-pipeline-process-parameters-unlink-all.png differ diff --git a/docs/pipelines/artifacts/media/classic-pipeline-process-parameters-unlink.png b/docs/pipelines/artifacts/media/classic-pipeline-process-parameters-unlink.png new file mode 100644 index 00000000000..1ad25327996 Binary files /dev/null and b/docs/pipelines/artifacts/media/classic-pipeline-process-parameters-unlink.png differ diff --git a/docs/pipelines/artifacts/media/classic-pipeline-process-parameters.png b/docs/pipelines/artifacts/media/classic-pipeline-process-parameters.png new file mode 100644 index 00000000000..1040c7da3ce Binary files /dev/null and b/docs/pipelines/artifacts/media/classic-pipeline-process-parameters.png differ diff --git a/docs/pipelines/artifacts/media/download-pipeline-artifacts-specific-version.png b/docs/pipelines/artifacts/media/download-pipeline-artifacts-specific-version.png new file mode 100644 index 00000000000..377d4744760 Binary files /dev/null and b/docs/pipelines/artifacts/media/download-pipeline-artifacts-specific-version.png differ diff --git a/docs/pipelines/artifacts/media/download-specific-build-artifact.png b/docs/pipelines/artifacts/media/download-specific-build-artifact.png new file mode 100644 index 00000000000..dfca08d4bf6 Binary files /dev/null and b/docs/pipelines/artifacts/media/download-specific-build-artifact.png differ diff --git a/docs/pipelines/artifacts/media/multiple-publish-tasks.png b/docs/pipelines/artifacts/media/multiple-publish-tasks.png index fcce39d6873..6b5d7ad3d5d 100644 Binary files a/docs/pipelines/artifacts/media/multiple-publish-tasks.png and b/docs/pipelines/artifacts/media/multiple-publish-tasks.png differ diff --git a/docs/pipelines/artifacts/media/nuget/authenticate-and-publish-tasks-external-feed.png b/docs/pipelines/artifacts/media/nuget/authenticate-and-publish-tasks-external-feed.png new file mode 100644 index 00000000000..c4d5e0c8e09 Binary files /dev/null and b/docs/pipelines/artifacts/media/nuget/authenticate-and-publish-tasks-external-feed.png differ diff --git a/docs/pipelines/artifacts/media/nuget/authenticate-and-publish-tasks.png b/docs/pipelines/artifacts/media/nuget/authenticate-and-publish-tasks.png new file mode 100644 index 00000000000..8dc611d7b1e Binary files /dev/null and b/docs/pipelines/artifacts/media/nuget/authenticate-and-publish-tasks.png differ diff --git a/docs/pipelines/artifacts/media/nuget/cli-push-nuget.png b/docs/pipelines/artifacts/media/nuget/cli-push-nuget.png new file mode 100644 index 00000000000..7b0d68249e2 Binary files /dev/null and b/docs/pipelines/artifacts/media/nuget/cli-push-nuget.png differ diff --git a/docs/pipelines/artifacts/media/nuget/nuget-push-cli-task.png b/docs/pipelines/artifacts/media/nuget/nuget-push-cli-task.png new file mode 100644 index 00000000000..3c9a3a5ca6f Binary files /dev/null and b/docs/pipelines/artifacts/media/nuget/nuget-push-cli-task.png differ diff --git a/docs/pipelines/artifacts/media/nuget/nuget-service-connection-external-devops-server.png b/docs/pipelines/artifacts/media/nuget/nuget-service-connection-external-devops-server.png new file mode 100644 index 00000000000..fa5df112c32 Binary files /dev/null and b/docs/pipelines/artifacts/media/nuget/nuget-service-connection-external-devops-server.png differ diff --git a/docs/pipelines/artifacts/media/nuget/package-published-to-external-feed.png b/docs/pipelines/artifacts/media/nuget/package-published-to-external-feed.png new file mode 100644 index 00000000000..07b08887e8b Binary files /dev/null and b/docs/pipelines/artifacts/media/nuget/package-published-to-external-feed.png differ diff --git a/docs/pipelines/artifacts/media/publish-crate-cl-pipeline.png b/docs/pipelines/artifacts/media/publish-crate-cl-pipeline.png new file mode 100644 index 00000000000..ec5bedef345 Binary files /dev/null and b/docs/pipelines/artifacts/media/publish-crate-cl-pipeline.png differ diff --git a/docs/pipelines/artifacts/media/publish-task.png b/docs/pipelines/artifacts/media/publish-task.png index 243f318d738..11a60c3ff35 100644 Binary files a/docs/pipelines/artifacts/media/publish-task.png and b/docs/pipelines/artifacts/media/publish-task.png differ diff --git a/docs/pipelines/artifacts/media/publish-to-feed-python-classic.png b/docs/pipelines/artifacts/media/publish-to-feed-python-classic.png new file mode 100644 index 00000000000..7cf40306346 Binary files /dev/null and b/docs/pipelines/artifacts/media/publish-to-feed-python-classic.png differ diff --git a/docs/pipelines/artifacts/media/published-crate-to-feed.png b/docs/pipelines/artifacts/media/published-crate-to-feed.png new file mode 100644 index 00000000000..4abb419abaf Binary files /dev/null and b/docs/pipelines/artifacts/media/published-crate-to-feed.png differ diff --git a/docs/pipelines/artifacts/media/twine-authenticate-publish-to-feed.png b/docs/pipelines/artifacts/media/twine-authenticate-publish-to-feed.png new file mode 100644 index 00000000000..edb3cf37007 Binary files /dev/null and b/docs/pipelines/artifacts/media/twine-authenticate-publish-to-feed.png differ diff --git a/docs/pipelines/artifacts/npm.md b/docs/pipelines/artifacts/npm.md index e68b0bcea04..34f8570a878 100644 --- a/docs/pipelines/artifacts/npm.md +++ b/docs/pipelines/artifacts/npm.md @@ -1,115 +1,165 @@ --- -title: Publishing npm packages using Azure Pipelines -ms.custom: seodec18, devx-track-js -description: How to publish your npm packages with Azure Pipelines -services: vsts +title: Publish npm packages with Azure Pipelines +ms.custom: devx-track-js +description: Learn how to publish npm packages to internal and external feed using Azure Pipelines. ms.assetid: F4C61B91-2C5B-4848-A4BF-B658F549673A ms.topic: conceptual -ms.date: 07/14/2022 +ms.date: 11/14/2024 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Publish npm packages (YAML/Classic) +# Publish npm packages with Azure Pipelines (YAML/Classic) [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Using Azure Pipelines, you can publish your npm packages to Azure Artifacts feeds or to public registries such as *npmjs.com*. In this article, you will learn how to publish your npm packages using YAML and Classic pipelines. +With Azure Pipelines, you can publish your npm packages to Azure Artifacts feeds within your organization and in other organizations. This article will guide you through publishing your npm packages to internal and external feeds using YAML and Classic pipelines. -## Publish to Azure Artifacts feeds +## Prerequisites -#### [YAML](#tab/yaml/) +- Create an Azure DevOps [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- Create a [new feed](../../artifacts/get-started-nuget.md#create-feed) if you don't have one already. + +- If you're using a self-hosted agent, make sure that it has [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). -::: moniker range=">= azure-devops-2019" +## Publish packages to a feed in the same organization > [!NOTE] -> The **Project Collection Build Service** and your project's **Build Service** identity must be set to **Contributor** to publish your packages to a feed using Azure Pipelines. See [Add new users/groups](../../artifacts/feeds/feed-permissions.md#configure-feed-settings) for more details. +> To publish your packages to a feed using Azure Pipelines, ensure that both the **Project Collection Build Service** and your project's **Build Service** identity are configured as a **Feed Publisher (Contributor)**. See [Add new users/groups](../../artifacts/feeds/feed-permissions.md#feed-settings) for more details. + +#### [YAML](#tab/yaml/) ```yaml -- task: Npm@1 +steps: +- task: NodeTool@0 inputs: - command: publish - publishRegistry: useFeed - publishFeed: ## For project-scoped feeds, use: / + checkLatest: true + +- task: npmAuthenticate@0 + displayName: 'Authenticate to Azure Artifacts feed' + inputs: + workingFile: .npmrc + +- script: | + npm publish + displayName: Publish ``` -- **publishRegistry**: Options: *useExternalRegistry*, *useFeed*. Select *useFeed* to use a feed within your organization. -- **publishFeed**: Required when publishRegistry = useFeed. The feed you want to publish to. +#### [Classic](#tab/classic/) -> [!TIP] -> Using the YAML editor to add the npm publish task will generate the project and feed IDs for your `publishFeed`. +::: moniker range="azure-devops" -::: moniker-end +1. Sign in to your Azure DevOps organization, and then navigate to your project. -::: moniker range="tfs-2018" -YAML is not supported in TFS. ::: moniker-end -#### [Classic](#tab/classic/) +::: moniker range="< azure-devops" + +1. Sign in to your Azure DevOps collection, and then navigate to your project. + +::: moniker-end -1. From within your pipeline, select the `+` sign to add a task to your pipeline, then search for the *npm* task. Select **Add** to add it to your pipeline. +::: moniker range="<=azure-devops" - :::image type="content" source="./media/add-npm-task.png" alt-text="A screenshot showing how to find and add the npm task."::: +2. Select **Pipelines**, and then select your pipeline definition. -1. Name your task and select **Publish** from the dropdown menu. Select your package.json path, your **Registry location** and your **Target registry** +::: moniker-end - :::image type="content" source="./media/npm-publish.png" alt-text="A screenshot showing how to configure the npm publish task."::: +3. Select **Edit**, and then select the `+` sign to add a new task. Add the *Node.js tool installer*, *npm Authenticate* and *Command line* tasks to your pipeline definition. You can leave the *Node.js tool installer* task with the default settings and configure the *npm Authenticate* and *Command line* tasks as follows: -- **Working folder that contains package.json**: path to the folder containing the target package.json and .npmrc files. Leave this blank if those files are at the root of your repo. -- **Registry location**: select **Registry I select here** to publish to an Azure Artifacts feed. select your feed from the dropdown menu. + 1. **npm Authenticate task**: Select the path to the *.npmrc* file. + + 1. **Command line task**: + - **Display name**: Publish. + - **Script**: + ``` + npm publish + ``` * * * -## Publish to a public registry +## Publish packages to a feed in another organization + +To publish your packages to a feed in another Azure DevOps organization, you must first create a personal access token in the target organization. + +Navigate to the organization hosting your target feed and [Create a personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **Packaging** > **Read & write** scope. Copy your personal access token as you'll need it in the following section. -To publish your packages to a public npm registry such as *npmjs.com*, you must first create a service connection to connect to the desired external service. +#### Create a service connection -1. Select **Project settings**, and then select **Service connections**. +1. Sign in to the Azure DevOps organization where your pipeline will run, and then navigate to your project. -1. Select **Create service connection** to create a new service connection. +1. Navigate to your **Project settings** > **Service connections**. - :::image type="content" source="./media/create-service-connection.png" alt-text="Screenshot showing how to create a new service connection"::: +1. Select **New service connection**, select **npm**, and then select **Next**. -1. Select **npm** and then select **Next**. Fill out the required fields, and then select **Save** when you are done. +1. Select **Username and Password** as the **Authentication method**, and then enter your **Registry URL**. Enter your **Username** (a placeholder, as Azure Pipelines will use your `.npmrc` configuration file and the personal access token you created earlier to authenticate). For **Password**, paste your personal access token. Provide a name for your service connection, and check the **Grant access permission to all pipelines** checkbox. + +1. Select **Save** when you're done. + +#### Publish packages #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +1. Sign in to your Azure DevOps organization, and then navigate to your project. -```yaml -- task: Npm@1 - inputs: - command: publish - publishRegistry: useExternalRegistry - publishEndpoint: '' -``` +1. Select **Pipelines**, and then select your pipeline definition. -- **publishRegistry**: Select *useExternalRegistry* to publish to a public registry. Options: useExternalRegistry | useFeed. -- **publishEndpoint**: required when `publishRegistry == useExternalRegistry`. Replace the placeholder with the name of the service connection you created earlier. +1. Select **Edit**, and then add the following snippet to your YAML pipeline. -::: moniker-end + ```yaml + - task: NodeTool@0 + inputs: + checkLatest: true -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end + - task: npmAuthenticate@0 + displayName: 'Authenticate to Azure Artifacts feed' + inputs: + workingFile: .npmrc + customEndpoint: + + - script: | + npm publish + displayName: Publish + ``` #### [Classic](#tab/classic/) -1. From within your pipeline, select the `+` sign to add a task to your pipeline, then search for the *npm* task. Select **Add** to add it to your pipeline. +::: moniker range="azure-devops" - :::image type="content" source="./media/add-npm-task.png" alt-text="Screenshot showing how to find and add the npm task"::: +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Name your task, and then select **Publish** from the dropdown menu. Select your *package.json* path, your **Registry location** and your **External registry**. +::: moniker-end - :::image type="content" source="./media/npm-publish-registry.png" alt-text="A screenshot showing how to configure the npm publish task to publish packages to public registries."::: +::: moniker range="< azure-devops" -- **Working folder that contains package.json**: path to the folder containing the target package.json and .npmrc files. Leave this blank if those files are at the root of your repo. -- **Registry location**: select **External npm registry** to publish to public registries such as npmjs.com. Enter the name of the service connection you created earlier. +1. Sign in to your Azure DevOps collection, and then navigate to your project. -* * * +::: moniker-end + +::: moniker range="<=azure-devops" + +2. Select **Pipelines**, and then select your pipeline definition. + +::: moniker-end + +3. Select **Edit**, and then select the `+` sign to add a new task. Add the *Node.js tool installer*, *npm Authenticate* and *Command line* tasks to your pipeline definition. You can leave the *Node.js tool installer* task with the default settings and configure the *npm Authenticate* and *Command line* tasks as follows:. + + 1. **npm Authenticate task**: + 1. Select the path to your *.npmrc* file. + 1. Select the service connection you created earlier from the **Credentials for registries outside this organization/collection** dropdown menu. + + 1. **Command line task**: + - **Display name**: Publish. + - **Script**: + ``` + npm publish + ``` + +*** -## Related articles +## Related content -- [Publish and download Artifacts in Azure Pipelines](./pipeline-artifacts.md). -- [Publish npm packages from the command line](../../artifacts/npm/publish.md). -- [Use packages from npmjs.com](../../artifacts/npm/upstream-sources.md). +- [Publish and download pipeline artifacts](../artifacts/build-artifacts.md) +- [Use the .artifactignore file](../../artifacts/reference/artifactignore.md) +- [Deploy pull request Artifacts](../release/deploy-pull-request-builds.md). diff --git a/docs/pipelines/artifacts/nuget.md b/docs/pipelines/artifacts/nuget.md index e7612b253f2..1bad039318a 100644 --- a/docs/pipelines/artifacts/nuget.md +++ b/docs/pipelines/artifacts/nuget.md @@ -1,250 +1,300 @@ --- -title: Publish NuGet packages with Pipeline tasks or the classic editor -ms.custom: seodec18 -description: How to publish NuGet packages with Azure Pipelines using YAML and the classic editor -services: vsts +title: Publish NuGet packages with Azure Pipelines +description: Learn how to publish NuGet packages to internal and external feeds using Classic and YAML Pipelines. ms.assetid: 29101A33-7C17-437C-B61D-DF7AA4CB9EA2 -ms.topic: conceptual -ms.date: 01/04/2023 -monikerRange: '<= azure-devops' +ms.topic: tutorial +ms.date: 09/11/2024 +monikerRange: '>= azure-devops-2020' +"recommendations": "true" --- # Publish NuGet packages with Azure Pipelines (YAML/Classic) [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -In Azure Pipelines, you can use the classic editor or the YAML tasks to publish your NuGet packages within your pipeline, to your Azure Artifacts feed, or to public registries such as *nuget.org*. +Using Azure Pipelines, you can publish your NuGet packages to Azure Artifacts feeds in your organization, in other organizations, and to public registries such as *nuget.org*, using either Classic or YAML pipelines. In this article, you'll learn how to: -## Create a NuGet package +> [!div class="checklist"] +> +> * Publish packages to an internal feed +> * Publish packages to a feed in a different organization +> * Package versioning -There are various ways to create your NuGet packages such as using Visual Studio to pack your NuGet packages. If you're already using MSBuild or some other task to create your packages, skip this section and jump to the [publish NuGet packages](#publish-nuget-packages) section. +## Prerequisites -#### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +- Create an Azure DevOps [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. -To create a NuGet package, add the following snippet to your pipeline YAML file. See [NuGet task](/azure/devops/pipelines/tasks/reference/nuget-command-v2) for more details. +- Create a [new feed](../../artifacts/get-started-nuget.md#create-feed) if you don't have one already. -```yaml -- task: NuGetCommand@2 - inputs: - command: pack - packagesToPack: '**/*.csproj' - packDestination: '$(Build.ArtifactStagingDirectory)' -``` +- If you're using a self-hosted agent, make sure that it has the [.NET Core SDK (2.1.400+)](https://dotnet.microsoft.com/en-us/download) and [NuGet (4.8.0.5385+)](https://www.nuget.org/downloads) installed. -- **packagesToPack**: pattern to search for csproj directories to pack -- **packDestination**: directory where packages will be created +> [!NOTE] +> If you're using Ubuntu 24.04 or higher, you must use the `NuGetAuthenticate` task with the .NET CLI instead of the *nuget.exe*. See [Support for newer Ubuntu hosted images](/azure/devops/pipelines/tasks/reference/nuget-command-v2#support-for-newer-ubuntu-hosted-images) for more details. -::: moniker-end +## Publish NuGet packages to a feed in the same organization -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end +::: moniker range="azure-devops-2020" -#### [Classic](#tab/classic/) +#### [YAML](#tab/yaml/) -From your pipeline definition, add the **NuGet task** to your pipeline to create a NuGet package. Make sure to add this task below the one building your application and above any tasks that require your NuGet package. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -- **Command:** the NuGet command to run. -- **Path to csproj or nuspec file(s) to pack**: pattern to search for csproj directories to pack. -- **Configuration to package**: when using a csproj file this specifies the configuration to package. -- **Package folder**: directory where packages will be created. +1. Select **Pipelines**, and then select your pipeline definition. -:::image type="content" source="media/nuget/create-packages-in-team-build.png" alt-text="Screenshot showing the NuGet pack task in Azure Pipelines."::: +1. Select **Edit**, and then add the following snippet to your YAML pipeline. -- - - +```yaml +steps: +- task: NuGetToolInstaller@1 # Minimum required NuGet version: 4.8.0.5385+. + displayName: 'NuGet Tool Installer' + +- task: NuGetAuthenticate@0 + displayName: 'NuGet Authenticate' + +- script: | + nuget.exe push -Source "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" -ApiKey az $(Build.ArtifactStagingDirectory)\*.nupkg + displayName: Push +``` -## Package versioning +#### [Classic](#tab/classic/) + +1. Navigate to the Azure DevOps portal, and then select your project. -NuGet packages are distinguished by their names and version numbers. Employing Semantic Versioning is a recommended strategy for effectively managing package versions. Semantic versions consist of three numeric components: Major, Minor, and Patch. +1. Select **Pipelines**, and then select your pipeline definition. -The *Patch* is usually incremented after fixing a bug. When you release a new backward-compatible feature, you increment the *Minor* version and reset the *Patch* version to 0, and when you make a backward-incompatible change, you increment the *Major* version and reset the *Minor* and *Patch* versions to 0. +1. Select **Edit**, and then select the `+` sign to add a new task. Add the *NuGet tool installer*, *NuGet Authenticate* and *Command line* tasks to your pipeline definition. You can leave the *NuGet tool installer* and *NuGet Authenticate* tasks with their default settings and configure the *Command line* task as follows: -With Semantic Versioning, you can also use prerelease labels to tag your packages. To do so, enter a hyphen followed by your prerelease tag: E.g.**1.0.0-beta**. Semantic Versioning is supported in Azure Pipelines and can be configured in your NuGet task as follows: + :::image type="content" source="media/nuget/nuget-push-cli-task.png" alt-text="A screenshot displaying how to configure the publish task in Azure Pipelines." lightbox="media/nuget/nuget-push-cli-task.png"::: -- **Use the date and time** (Classic): **byPrereleaseNumber** (YAML). Your package version will be in the format: *Major.Minor.Patch-ci-datetime* where you have the flexibility to choose the values of your Major, Minor, and Patch. + - **Display name**: *Push*. + - **Script**: + ```script + nuget.exe push -Source "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" -ApiKey az $(Build.ArtifactStagingDirectory)\*.nupkg + ``` -- **Use an environment variable** (Classic): **byEnvVar** (YAML). Your package version will be set to the value of the environment variable you specify. +- - - -- **Use the build number** (Classic): **byBuildNumber** (YAML). Your package version will be set to the build number. Make sure you set your build number format under your pipeline **Options** to `$(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)`. To do this in YAML, add a property `name:` at the root of your pipeline and add your format. +::: moniker-end -The following example shows how to use the date and time versioning option. This will generate a SemVer compliant version formatted as: `Major.Minor.Patch-ci-datetime`. +::: moniker range=">= azure-devops-2022" #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +1. Sign in to your Azure DevOps organization, and then navigate to your project. -```yaml -variables: - Major: '1' - Minor: '0' - Patch: '0' +1. Select **Pipelines**, and then select your pipeline definition. + +1. Select **Edit**, and then add the following snippet to your YAML pipeline. +```yaml steps: -- task: NuGetCommand@2 - inputs: - command: pack - versioningScheme: byPrereleaseNumber - majorVersion: '$(Major)' - minorVersion: '$(Minor)' - patchVersion: '$(Patch)' -``` -::: moniker-end +- task: NuGetToolInstaller@1 # Minimum required NuGet version: 4.8.0.5385+. + displayName: 'NuGet Tool Installer' -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end +- task: NuGetAuthenticate@1 + displayName: 'NuGet Authenticate' + +- script: | + nuget.exe push -Source "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" -ApiKey az $(Build.ArtifactStagingDirectory)\*.nupkg + displayName: Push +``` #### [Classic](#tab/classic/) -1. From your classic pipeline definition, select your NuGet task, select **Pack options** and then select **Use the date and time**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select your pipeline definition. + +1. Select **Edit**, and then select the `+` sign to add a new task. Add the *NuGet tool installer*, *NuGet Authenticate* and *Command line* tasks to your pipeline definition. You can leave the *NuGet tool installer* and *NuGet Authenticate* tasks with their default settings and configure the *Command line* task as follows: - :::image type="content" source="media/package-versioning-classic.png" alt-text="Screenshot showing how to enable package versioning in the NuGet task."::: + :::image type="content" source="media/nuget/nuget-push-cli-task.png" alt-text="A screenshot displaying how to configure the CLI publish task in Azure Pipelines." lightbox="media/nuget/nuget-push-cli-task.png"::: + + - **Display name**: *Push*. + - **Script**: + ```script + nuget.exe push -Source "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" -ApiKey az $(Build.ArtifactStagingDirectory)\*.nupkg + ``` - - - +::: moniker-end + > [!NOTE] -> `DotNetCore` and `DotNetStandard` packages should be packaged with the `DotNetCoreCLI@2` task to avoid System.InvalidCastExceptions. See the [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) for more details. +> To publish your packages to a feed using Azure Pipelines, make sure that both the **Project Collection Build Service** and your project's **Build Service** identities are granted the **Feed Publisher (Contributor)** role assigned in your feed settings. See [Manage permissions](../../artifacts/feeds/feed-permissions.md) for more details. +## Publish NuGet packages to a feed in another organization -```yaml -task: DotNetCoreCLI@2 -inputs: - command: pack - versioningScheme: byPrereleaseNumber - majorVersion: '$(Major)' - minorVersion: '$(Minor)' - patchVersion: '$(Patch)' -``` +To publish your NuGet packages to a feed in a different Azure DevOps organization, you must first create a personal access token (PAT) in the target organization. Navigate to the organization hosting your target feed and [Create a personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **Packaging** > **Read & write** scope. +Once the PAT is created, copy and store it in a secure location, as you'll need it in the following section to set up a service connection. -## Publish NuGet packages +1. Sign in to the Azure DevOps organization where your pipeline will run, and then navigate to your project. -To publish packages to an Azure Artifacts feed from your pipeline, you must set the **Project Collection Build Service** identity to be a **Contributor** on your feed. See [Configure feed settings](../../artifacts/feeds/feed-permissions.md#configure-feed-settings) for more details. +1. Navigate to your **Project settings** > **Service connections**. -#### [YAML](#tab/yaml/) +1. Select **New service connection**, select **NuGet**, and then select **Next**. -::: moniker range=">= azure-devops-2019" +1. Select **External Azure DevOps Server** as the **Authentication method**, and then enter your target **Feed URL**. Paste the **Personal Access Token** you created earlier, provide a name for your service connection, and check **Grant access permission to all pipelines** if applicable to your scenario. -```yaml -steps: -- task: NuGetAuthenticate@0 - displayName: 'NuGet Authenticate' -- task: NuGetCommand@2 - displayName: 'NuGet push' - inputs: - command: push - publishVstsFeed: '/' - allowPackageConflicts: true -``` +1. Select **Save** when you're done. -To publish a package to an external NuGet feed, you must first create a service connection to connect to that feed. You can do this by going to **Project settings** > **Service connections** > **New service connection**. Select **NuGet**, and then select **Next**. Fill out the form and then select **Save** when you're done. See [Manage service connections](../library/service-endpoints.md) for more details. + :::image type="content" source="media/nuget/nuget-service-connection-external-devops-server.png" alt-text="A screenshot displaying how to set up a NuGet service connection to authenticate with an external feed in a different organization." lightbox="media/nuget/nuget-service-connection-external-devops-server.png"::: -To publish a package to an external NuGet feed, add the following snippet to your YAML pipeline. +::: moniker range=">= azure-devops-2022" -**Using the** [Command line task](/azure/devops/pipelines/tasks/reference/cmd-line-v2) (with NuGet.exe): +#### [YAML](#tab/yaml/) -```yaml - - task: NuGetAuthenticate@1 - inputs: - nuGetServiceConnections: - - - script: | - nuget push -src https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json -ApiKey - displayName: "Push" -``` +1. Sign in to your Azure DevOps organization, and then navigate to your project. -**Using the** [Command line task](/azure/devops/pipelines/tasks/reference/cmd-line-v2) (with dotnet): +1. Select **Pipelines**, and then select your pipeline definition. + +1. Select **Edit**, and then add the following snippet to your YAML pipeline. + + ```yaml + - task: NuGetToolInstaller@1 # Minimum required NuGet version: 4.8.0.5385+. + displayName: 'NuGet Tool Installer' - ```yaml - task: NuGetAuthenticate@1 inputs: - nuGetServiceConnections: + nuGetServiceConnections: - script: | - dotnet build --configuration - dotnet pack -p:PackageVersion= --output --configuration - dotnet nuget push --source https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json --api-key - displayName: "Build, pack and push" - ``` + nuget.exe push -Source "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" -ApiKey az $(Build.ArtifactStagingDirectory)\*.nupkg + displayName: Push + ``` -> [!NOTE] -> The `ApiKey` is required, but you can use any arbitrary value when pushing to Azure Artifacts feeds. +#### [Classic](#tab/classic/) -::: moniker-end +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select your pipeline definition. + +1. Select **Edit**, and then select the `+` sign to add a new task. Add the *NuGet tool installer*, *NuGet Authenticate* and *Command line* tasks to your pipeline definition. You can leave the *NuGet tool installer* with its default settings and configure the other tasks as follows: + + :::image type="content" source="media/nuget/nuget-push-cli-task.png" alt-text="A screenshot displaying how to configure the publish task to a feed in another organization." lightbox="media/nuget/nuget-push-cli-task.png"::: + + 1. **NuGet Authenticate task**: select your service connection from the *Service connection credentials for feeds outside this organization* dropdown menu. + + 1. **Command line task**: + - **Display name**: *Push*. + - **Script**: + ```script + nuget.exe push -Source "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" -ApiKey az $(Build.ArtifactStagingDirectory)\*.nupkg + ``` + +- - - -::: moniker range="tfs-2018" -YAML is not supported in TFS. ::: moniker-end -#### [Classic](#tab/classic/) +::: moniker range="azure-devops-2020" -To publish NuGet packages with Azure Pipelines, add the **NuGet** task to your pipeline definition and configure it as follows: +#### [YAML](#tab/yaml/) -- **Command**: the NuGet command to run. -- **Path to NuGet package(s) to publish**:the pattern to match or path to nupkg files to be uploaded. -- **Target feed location**: You can publish to your current organization or an external NuGet server. -- **Target feed**: Select the feed that you want to publish to. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -:::image type="content" source="media/nuget/publish-packages-from-team-build.png" alt-text="Screenshot showing how to configure the NuGet task in Azure Pipelines"::: +1. Select **Pipelines**, and then select your pipeline definition. -::: moniker range="tfs-2018" +1. Select **Edit**, and then add the following snippet to your YAML pipeline. -> [!NOTE] -> If you are running TFS Update 2 or older, **Nuget** is not a service endpoint option. You must use the **Generic** service connection. + ```yaml + - task: NuGetToolInstaller@1 # Minimum required NuGet version: 4.8.0.5385+. + displayName: 'NuGet Tool Installer' -::: moniker-end + - task: NuGetAuthenticate@0 + inputs: + nuGetServiceConnections: + + - script: | + nuget.exe push -Source "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" -ApiKey az $(Build.ArtifactStagingDirectory)\*.nupkg + displayName: Push + ``` -- - - +#### [Classic](#tab/classic/) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select your pipeline definition. -## Publish to NuGet.Org +1. Select **Edit**, and then select the `+` sign to add a new task. Add the *NuGet tool installer*, *NuGet Authenticate* and *Command line* tasks to your pipeline definition. You can leave the *NuGet tool installer* with its default settings and configure the other tasks as follows: -1. [Generate an API key](../../artifacts/nuget/publish-to-nuget-org.md#generate-an-api-key) + :::image type="content" source="media/nuget/nuget-push-cli-task.png" alt-text="A screenshot displaying how to configure the CLI publish task to a feed in another organization." lightbox="media/nuget/nuget-push-cli-task.png"::: -1. Navigate to your Azure DevOps project and then select ![gear icon](../../media/icons/gear-icon.png) **Project settings**. + 1. **NuGet Authenticate task**: select your service connection from the *Service connection credentials for feeds outside this organization* dropdown menu. + + 1. **Command line task**: + - **Display name**: *Push*. + - **Script**: + ```script + nuget.exe push -Source "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" -ApiKey az $(Build.ArtifactStagingDirectory)\*.nupkg + ``` -1. Select **Service Connections**, and then select **New service connection**. +- - - + +::: moniker-end + +:::image type="content" source="media/nuget/package-published-to-external-feed.png" alt-text="A screenshot displaying the package successfully published to a feed in a different organization." lightbox="media/nuget/package-published-to-external-feed.png"::: -1. Select **NuGet**, and then select **Next**. +## NuGet task package versioning -1. Select **ApiKey** as your authentication method. Use the following url for your **Feed URL**: *https://api.nuget.org/v3/index.json*. +Azure Pipelines supports [Semantic Versioning](https://semver.org/) and provides the following configuration options for NuGet tasks: -1. Enter the **ApiKey** you generated earlier, and then enter a **Service connection name**. +- **Use the date and time** (Classic) | **byPrereleaseNumber** (YAML): + Your package version will follow the format: *Major.Minor.Patch-ci-datetime* where you have the flexibility to customize the Major, Minor, and Patch values. -1. Select **Grant access permission to all pipelines**, and then select **Save** when you're done. To select this option, you'll need the [service connection **Administrator** role](../library/add-resource-protection.md). +- **Use an environment variable** (Classic) | **byEnvVar** (YAML): + Your package version is set to the value of the specified environment variable. +- **Use the build number** (Classic) | **byBuildNumber** (YAML): + Your package version is set to the build number. Make sure you define the build number format in your pipeline **Options** as `$(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)`. To specify the format in YAML, add a `name:` property at the root of your pipeline and define your format. + +The following is an example demonstrating how to use the date and time versioning to generate a SemVer-compliant package formatted as: *Major.Minor.Patch-ci-datetime*. #### [YAML](#tab/yaml/) -Add the following YAML snippet to your pipeline definition: +```yaml +variables: + Major: '1' + Minor: '0' + Patch: '0' -```yml steps: - task: NuGetCommand@2 - displayName: 'NuGet push' inputs: - command: push - nuGetFeedType: external - publishFeedCredentials: nuget.org + command: pack + versioningScheme: byPrereleaseNumber + majorVersion: '$(Major)' + minorVersion: '$(Minor)' + patchVersion: '$(Patch)' ``` -#### [Classic](#tab/classic/) -Add the NuGet task to your pipeline definition and configure it as follows: +> [!NOTE] +> `DotNetCore` and `DotNetStandard` packages should be packaged with the `DotNetCoreCLI@2` task to avoid System.InvalidCastExceptions. See the [.NET Core CLI](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) task for more details. -1. Select the Push **Command**. +```yaml +task: DotNetCoreCLI@2 +inputs: + command: pack + versioningScheme: byPrereleaseNumber + majorVersion: '$(Major)' + minorVersion: '$(Minor)' + patchVersion: '$(Patch)' +``` -1. Select the **Path to NuGet package(s) to publish** or keep the default value. +#### [Classic](#tab/classic/) -1. Select **External NuGet server** for your **Target feed location**, and then select the service connection you created earlier. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Save & queue** when you're done. +1. Select **Pipelines**, and then select your pipeline definition. -:::image type="content" source="media/push-to-nuget-org.png" alt-text="Screenshot showing how to configure the NuGet push task in Azure Pipelines"::: +1. Select **Edit**, and then select your NuGet task. -* * * +1. Make sure the command is set to **Pack**, then under **Pack options**, select **Use the date and time** from the dropdown menu. + + :::image type="content" source="media/package-versioning-classic.png" alt-text="A screenshot displaying how to enable package versioning in a classic pipeline."::: + +- - - -## Related articles +## Related content -- [Publish npm packages with Azure Pipelines](./npm.md) -- [Publish and download Universal Packages in Azure Pipelines](./universal-packages.md) -- [Releases in Azure Pipelines](../release/releases.md) -- [Release artifacts and artifact sources](../release/artifacts.md) +- [Publish NuGet packages to NuGet.org](publish-public-registry.md) +- [Use packages from the NuGet.org upstream](../../artifacts/nuget/upstream-sources.md) +- [Publish and download Universal Packages](./universal-packages.md) diff --git a/docs/pipelines/artifacts/pipeline-artifacts.md b/docs/pipelines/artifacts/pipeline-artifacts.md index 7afbb363383..eabb7aad042 100644 --- a/docs/pipelines/artifacts/pipeline-artifacts.md +++ b/docs/pipelines/artifacts/pipeline-artifacts.md @@ -1,7 +1,6 @@ --- -title: Publish and download artifacts in your pipeline -ms.custom: seodec18 -description: How to publish and consume pipeline artifacts +title: Publish and download pipeline artifacts +description: How to publish and download pipeline artifacts ms.assetid: 028dcda8-a8fa-48cb-bb35-cdda8ac52e2c ms.topic: reference ms.date: 08/30/2021 @@ -9,7 +8,7 @@ monikerRange: 'azure-devops' "recommendations": "true" --- -# Publish and download pipeline Artifacts +# Publish and download pipeline artifacts [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] @@ -66,11 +65,11 @@ steps: --- -Although the artifact's name is optional, it is a good practice to specify a name that accurately reflects the contents of your artifact. If you plan to consume the artifact from a job running on a different OS, you must ensure all the file paths are valid for the target environment. For example, a file name containing the character `\` or `*` will fail to download on Windows. +Although the artifact's name is optional, it's a good practice to specify a name that accurately reflects the contents of your artifact. If you plan to consume the artifact from a job running on a different OS, you must ensure all the file paths are valid for the target environment. For example, a file name containing the character `\` or `*` will fail to download on Windows. The path of the file/folder that you want to publish is required. This can be an absolute or a relative path to `$(System.DefaultWorkingDirectory)`. -Packages in Azure Artifacts are immutable. Once you publish a package, its version will be permanently reserved. rerunning failed jobs will fail if the package has been published. A good way to approach this if you want to be able to rerun failed jobs without facing an error *package already exists*, is to use [Conditions](../process/conditions.md) to only run if the previous job succeeded. +Packages in Azure Artifacts are immutable. Once you publish a package, its version is permanently reserved. Rerunning failed jobs will fail if the package has been published. A good way to approach this if you want to be able to rerun failed jobs without facing an error *package already exists*, is to use [Conditions](../process/conditions.md) to only run if the previous job succeeded. ```yml jobs: @@ -85,7 +84,7 @@ Packages in Azure Artifacts are immutable. Once you publish a package, its versi ``` > [!NOTE] -> You will not be billed for storing Pipeline Artifacts. Pipeline Caching is also exempt from storage billing. See [Which artifacts count toward my total billed storage](../../artifacts/start-using-azure-artifacts.md#q-which-artifacts-count-toward-my-total-billed-storage). +> You will not be billed for storing Pipeline Artifacts. Pipeline Caching is also exempt from storage billing. See [Which artifacts count toward my total billed storage](../../artifacts/start-using-azure-artifacts.md#q-which-artifacts-contribute-to-my-total-billed-storage). > [!CAUTION] > Deleting a pipeline run will result in the deletion of all Artifacts associated with that run. @@ -128,7 +127,7 @@ steps: > You can use [Pipeline resources](../process/resources.md#define-a-pipelines-resource) to define your source in one place and use it anywhere in your pipeline. > [!NOTE] -> The `download` keyword is a shortcut for the [Download Pipeline Artifact](/azure/devops/pipelines/tasks/reference/download-pipeline-artifact-v2) task. +> The `download` keyword downloads artifacts. For more information, see [steps.download](/azure/devops/pipelines/yaml-schema/steps-download). # [YAML (task)](#tab/yaml-task) @@ -162,7 +161,8 @@ steps: --- -By default, files are downloaded to **$(Pipeline.Workspace)**. If an artifact name was not specified, a subdirectory will be created for each downloaded artifact. You can use matching patterns to limit which files get downloaded. See [File matching patterns](../tasks/file-matching-patterns.md) for more details. +To download a pipeline artifact from a different project within your organization, make sure that you have the appropriate [permissions](../../artifacts/feeds/project-scoped-feeds.md#q-how-can-i-download-a-pipeline-artifact-from-another-project-within-the-same-organization) configured for both the downstream project and the pipeline generating the artifact. +By default, files are downloaded to **$(Pipeline.Workspace)**. If an artifact name wasn't specified, a subdirectory will be created for each downloaded artifact. You can use matching patterns to limit which files get downloaded. See [File matching patterns](../tasks/file-matching-patterns.md) for more details. ```yml steps: @@ -181,7 +181,7 @@ A single download step can download one or more artifacts. To download multiple When an artifact name is specified: -1. Only files for that specific artifact are downloaded. If the artifact does not exist, the task will fail. +1. Only files for that specific artifact are downloaded. If the artifact doesn't exist, the task will fail. 1. File matching patterns are evaluated relative to the root of the artifact. For example, the pattern `*.jar` matches all files with a `.jar` extension at the root of the artifact. @@ -276,6 +276,66 @@ Not available. --- +#### Download a specific artifact + +The following example demonstrates how to download pipeline artifacts from a specific build version produced by a particular run: + +# [YAML](#tab/yaml) + +```yaml +resources: + pipelines: + - pipeline: myPipeline + project: 'xxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx' + source: '79' + version: '597' + +steps: +- download: myPipeline + artifact: drop + patterns: '**' + displayName: 'Download Pipeline Artifact' +``` + +# [YAML (task)](#tab/yaml-task) + +```yaml +steps: +- task: DownloadPipelineArtifact@2 + displayName: 'Download Pipeline Artifact' + inputs: + buildType: specific + project: 'xxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx' + definition: 79 + buildVersionToDownload: specific + pipelineId: 597 + artifactName: drop +``` + +# [Classic](#tab/classic) + +- Add the :::image type="icon" source="../tasks/utility/media/download-pipeline-artifact.png" border="false"::: **Download Pipeline Artifact** task. + +- Fill out the following fields: + - **Display name**: task display name + - **Download artifacts produced by**: specific run + - **Project**: the project from which to download the pipeline artifacts + - **Build pipeline**: select from the dropdown menu + - **Build version to download**: specific version + - **Build**: the build from which to download the artifacts + - **Artifact name**: the name of the artifact to download + - **Matching patterns**: one or more file matching patterns that limit which files get downloaded + - **Destination directory**: Default: $(Pipeline.Workspace) + +:::image type="content" source="media/download-pipeline-artifacts-specific-version.png" alt-text="A screenshot displaying how to configure the download pipeline artifacts task to download a specific artifact."::: + +# [Azure CLI](#tab/azure-cli) + +Not available. + +--- + + ## Artifacts in release and deployment jobs Artifacts are only downloaded automatically in deployment jobs. By default, artifacts are downloaded to `$(Pipeline.Workspace)`. The download artifact task will be auto injected only when using the `deploy` lifecycle hook in your deployment. To stop artifacts from being downloaded automatically, add a `download` step and set its value to none. @@ -351,21 +411,37 @@ When migrating from build artifacts to pipeline artifacts: ```yaml - task: PublishPipelineArtifact@1 - displayName: 'Publish' + displayName: 'Publish pipeline artifact' inputs: - targetPath: $(Build.ArtifactStagingDirectory)/** + targetPath: '$(Pipeline.Workspace)' ${{ if eq(variables['Build.SourceBranchName'], 'main') }}: - artifactName: 'prod' + artifact: 'prod' ${{ else }}: - artifactName: 'dev' - artifactType: 'pipeline' + artifact: 'dev' + publishLocation: 'pipeline' ``` -- **targetPath**: The path of the file or directory to publish. Can be absolute or relative to the default working directory. Can include variables, but wildcards are not supported. +- **targetPath**: (Required) The path of the file or directory to publish. Can be absolute or relative to the default working directory. Can include [variables](../build/variables.md), but wildcards are not supported. Default: $(Pipeline.Workspace). + +- **publishLocation**: (Required) Artifacts publish location. Choose whether to store the artifact in Azure Pipelines, or to copy it to a file share that must be accessible from the pipeline agent. Options: `pipeline`, `filepath`. Default: pipeline. + +- **artifact**: (Optional) Name of the artifact to publish. If not set, defaults to a unique ID scoped to the job. + +## View published Artifacts + +Once your pipeline run is complete, follow these steps to view or download your published artifact: + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, select your pipeline run, and then select the **Summary** tab. + +1. In the related section, select the published artifact. + + :::image type="content" source="../media/published-artifact.png" alt-text="A screenshot showing how to find published artifacts in a pipeline run."::: -- **artifactName**: Name of the artifact to publish. If not set, defaults to a unique ID scoped to the job. +1. Expand the drop folder to locate your artifact. You can then download your Artifact and explore its content. -- **artifactType**: Choose whether to store the artifact in Azure Pipelines, or to copy it to a file share that must be accessible from the pipeline agent. Options: `pipeline`, `filepath`. + :::image type="content" source="../media/drop-artifacts.png" alt-text="A screenshot displaying the content of a published artifact."::: ## FAQ diff --git a/docs/pipelines/artifacts/publish-maven-artifacts.md b/docs/pipelines/artifacts/publish-maven-artifacts.md index c77ecd14818..486cb0dd4a9 100644 --- a/docs/pipelines/artifacts/publish-maven-artifacts.md +++ b/docs/pipelines/artifacts/publish-maven-artifacts.md @@ -1,110 +1,163 @@ --- title: Publish Maven artifacts -description: How to publish Maven artifacts with Azure Pipelines -ms.topic: conceptual -ms.date: 10/24/2022 +description: Learn how to publish Maven artifacts to internal and external feed using Azure Pipelines. +ms.topic: how-to +ms.date: 11/18/2024 monikerRange: '<= azure-devops' --- -# Publish Maven artifacts with Azure Pipelines +# Publish Maven artifacts with Azure Pipelines (YAML/Classic) -Using Azure Pipelines, you can publish your Maven packages to Azure Artifacts feeds, public registries, or as a pipeline artifact. +Using Azure Pipelines, you can publish your Maven artifacts to Azure Artifacts feeds in your organization, in other organizations, and to public registries such as Maven Central. This article will guide you through publishing your Maven artifacts using both YAML and Classic pipelines. -## Set up your project +## Prerequisites -1. Add the following snippet to the `repositories` and `distributionManagement` sections in your *pom.xml* file. Replace the placeholders with your organization name, project name, and your feed name. +- An Azure DevOps organization. [Create one for free](../../organizations/accounts/create-organization.md). - ```XML - - MavenDemo - https://pkgs.dev.azure.com/ORGANIZATION-NAME/PROJECT-NAME/_packaging/FEED-NAME/maven/v1 - - true - - - true - - - ``` +- An Azure DevOps project. Create a new [project](../../organizations/projects/create-project.md#create-a-project) if you don't have one already. -1. Configure your *settings.xml* file as follows. Replace the placeholders with your organization name, your project name, and your personal access token. +- An Azure Artifacts feed. [Create one for free](../../artifacts/get-started-maven.md#create-a-feed). - ```XML - - PROJECT-NAME - ORGANIZATION-NAME - PERSONAL-ACCESS-TOKEN - - ``` +## Publish packages to a feed in the same organization -1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging read & write** scope and paste it into the `password` tag in your *settings.xml* file. +#### [YAML](#tab/yaml/) -## Build your code +::: moniker range="azure-devops" +1. Sign in to your Azure DevOps organization, and then navigate to your project. +::: moniker-end -In this example, we're using the [Maven task](../tasks/build/maven.md) to build the project with Azure Pipelines. +::: moniker range="< azure-devops" +1. Sign in to your Azure DevOps collection, and then navigate to your project. +::: moniker-end + +::: moniker range="<=azure-devops" +2. Select **Pipelines**, and then select your pipeline definition. +::: moniker-end + +3. Select **Edit**, and then add the following snippet to your YAML pipeline. ```yml -- task: Maven@3 +steps: +- task: MavenAuthenticate@0 + displayName: 'Authenticate to Azure Artifacts feed' inputs: - mavenPomFile: 'my-app/pom.xml' // Path to your pom file - mavenOptions: '-Xmx3072m' - javaHomeOption: 'JDKVersion' - jdkVersionOption: '1.8' - jdkArchitectureOption: 'x64' - publishJUnitResults: true - testResultsFiles: '**/surefire-reports/TEST-*.xml' - goals: 'package' + artifactsFeeds: 'MavenDemo,MavenDemoFeed2' ## Select one or multiple feeds to authenticate with. +- script: | + mvn deploy + displayName: 'Publish' ``` -## Publish packages to your pipeline +#### [Classic](#tab/classic/) -The following example illustrates how to publish your artifact to *drop* in your pipeline. Use the [Copy files](../tasks/utility/copy-files.md) task to copy your packages to a target folder, then use [Publish Build Artifacts](../tasks/utility/publish-build-artifacts.md) to publish your build artifacts to Azure Pipelines. +::: moniker range="azure-devops" +1. Sign in to your Azure DevOps organization, and then navigate to your project. +::: moniker-end -```yml -- task: CopyFiles@2 - inputs: - Contents: '**' - TargetFolder: '$(build.artifactstagingdirectory)' -- task: PublishBuildArtifacts@1 - inputs: - PathtoPublish: '$(Build.ArtifactStagingDirectory)' - ArtifactName: 'drop' - publishLocation: 'Container' -``` +::: moniker range="< azure-devops" +1. Sign in to your Azure DevOps collection, and then navigate to your project. +::: moniker-end -:::image type="content" source="media/published-maven-pipeline.png" alt-text="A screenshot showing the build artifact published to drop in Azure Pipelines."::: +::: moniker range="<=azure-devops" +2. Select **Pipelines**, and then select your pipeline definition. +::: moniker-end -## Publish packages to your feed +3. Select **Edit**, and then select the `+` sign to add a new task. Add the *Maven Authenticate* and *Command line* tasks to your pipeline definition and configure them as follows: -To publish your package to an Azure Artifacts feed, use the Maven task to deploy your artifact to your feed. + 1. **Maven Authenticate**: Select one or multiple feeds from the **Feeds** dropdown menu. -```yml -- task: Maven@3 + 1. **Command line task**: + - **Display name**: Publish. + - **Script**: + ``` + mvn deploy + ``` + +4. Select **Save & queue** when you're done. + +--- + +> [!NOTE] +> To publish packages to a feed using Azure Pipelines, make sure that both the *Project Collection Build Service* and your project's *Build Service* identities have the **Feed Publisher (Contributor)** role in your feed settings. See [Manage permissions](../../artifacts/feeds/feed-permissions.md#pipelines-permissions) for more details. + +## Publish packages to a feed in another organization + +To publish your packages to a feed in another Azure DevOps organization, you must first create a personal access token in the target organization. + +Navigate to the organization hosting your target feed and [Create a personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **Packaging** > **Read & write** scope. Copy your personal access token as you'll need it in the following section. + +#### Create a service connection + +1. Sign in to the Azure DevOps organization where your pipeline will run, and then navigate to your project. + +1. Navigate to your **Project settings** > **Service connections**. + +1. Select **New service connection**, select **Maven**, and then select **Next**. + +1. Select **Username and Password** as the **Authentication method**, and then enter your **Repository URL** and your **Repository Id**. + +1. Enter your **Username** (a placeholder, as Azure Pipelines will use your `pom.xml` configuration file and the personal access token you created earlier to authenticate). For **Password**, paste your personal access token. Provide a **Name** for your service connection, and check the **Grant access permission to all pipelines** checkbox. + +1. Select **Save** when you're done. + +#### Publish packages + +#### [YAML](#tab/yaml/) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select your pipeline definition. + +1. Select **Edit**, and then add the following snippet to your YAML pipeline. + +```yaml +steps: +- task: MavenAuthenticate@0 + displayName: 'Authenticate to Azure Artifacts feed' inputs: - mavenPomFile: 'my-app/pom.xml' - mavenOptions: '-Xmx3072m' - javaHomeOption: 'JDKVersion' - jdkVersionOption: '1.8' - jdkArchitectureOption: 'x64' - mavenAuthenticateFeed: true - publishJUnitResults: false - testResultsFiles: '**/surefire-reports/TEST-*.xml' - goals: 'deploy' + MavenServiceConnections: + +- script: | + mvn deploy + displayName: 'Publish' ``` -:::image type="content" source="media/maven-published-to-feed.png" alt-text="A screenshot showing the build artifact published to a feed."::: +#### [Classic](#tab/classic/) + +::: moniker range="azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +::: moniker-end + +::: moniker range="< azure-devops" + +1. Sign in to your Azure DevOps collection, and then navigate to your project. + +::: moniker-end + +::: moniker range="<=azure-devops" + +2. Select **Pipelines**, and then select your pipeline definition. + +::: moniker-end + +3. Select **Edit**, and then select the `+` sign to add a new task. Add the *Maven Authenticate* and *Command line* tasks to your pipeline definition and configure them as follows: -## Q&A + 1. **Maven Authenticate**: Select your service connection from the **Credentials for repositories outside this organization/collection** dropdown menu. -#### Q: How to authenticate with MavenAuthenticate? + 1. **Command line task**: + - **Display name**: Publish. + - **Script**: + ``` + mvn deploy + ``` -A: You can use the [MavenAuthenticate](/azure/devops/pipelines/tasks/reference/maven-authenticate-v0) task to authenticate with Maven feeds inside and outside your organization. See the examples below for more details: +4. Select **Save & queue** when you're done. -- [Authenticate with Maven feeds inside your organization](/azure/devops/pipelines/tasks/reference/maven-authenticate-v0#authenticate-maven-feeds-inside-your-organization) -- [Authenticate with Maven feeds outside your organization](/azure/devops/pipelines/tasks/reference/maven-authenticate-v0#authenticate-maven-feeds-outside-your-organization) +- - - -## Related articles +## Related content -- [Publish npm packages with Azure Pipelines](./npm.md) -- [Release artifacts and artifact sources](../release/artifacts.md) -- [Publish NuGet packages with Azure Pipelines](./nuget.md) \ No newline at end of file +- [Maven Authenticate v0 task](/azure/devops/pipelines/tasks/reference/maven-authenticate-v0) +- [Use the .artifactignore file](../../artifacts/reference/artifactignore.md) +- [Publish and download pipeline artifacts](pipeline-artifacts.md) \ No newline at end of file diff --git a/docs/pipelines/artifacts/publish-public-registry.md b/docs/pipelines/artifacts/publish-public-registry.md index 6ae598740f7..4966f5e4f57 100644 --- a/docs/pipelines/artifacts/publish-public-registry.md +++ b/docs/pipelines/artifacts/publish-public-registry.md @@ -1,32 +1,27 @@ --- -title: Publish NuGet packages to NuGet.org with Azure Pipelines (Classic/YAML) +title: Publish NuGet packages to NuGet.org (Classic/YAML) description: Learn how to publish NuGet packages to NuGet.org using Azure Pipelines. +ms.custom: peer-review-program ms.topic: conceptual -ms.date: 05/14/2023 +ms.date: 12/23/2024 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Publish NuGet packages to NuGet.org with Azure Pipelines +# Publish NuGet packages to NuGet.org (Classic/YAML) -Using Azure Pipelines, developers can streamline the process of publishing their NuGet packages to feeds and public registries. In this tutorial, we'll explore how to leverage YAML and classic pipelines to publish NuGet packages to NuGet.org. In this article, you'll learn how to: - -> [!div class="checklist"] -> * Authenticate with NuGet.org. -> * Create service connections. -> * Publish packages to NuGet.Org. +Using Azure Pipelines, developers can streamline the process of publishing their NuGet packages to feeds and public registries. This article will walk you through publishing your NuGet packages to NuGet.org. ## Prerequisites -- An Azure DevOps organization and a project. [Create one for free](../get-started/pipelines-sign-up.md), if you don't have one already. - - The [**Administrator** role for service connections](../library/add-resource-protection.md) in your Azure DevOps project. - -- A [nuget.org](/nuget/nuget-org/individual-accounts#add-a-new-individual-account) account. - +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).
      - **Permissions:**
          - To grant access to all pipelines in the project, you must be a member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md).
          - To create service connections, you must have the *Administrator* or *Creator* role for [service connections](../library/add-resource-protection.md). | +| **NuGet.org** | - A [NuGet](/nuget/nuget-org/individual-accounts#add-a-new-individual-account) account. | ## Create an API key -1. Navigate to [NuGet.org](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) and sign in to your account. +1. Navigate to [NuGet.org](https://www.nuget.org/) and sign in to your account. 1. Select your user name icon, and then select **API Keys**. @@ -34,75 +29,75 @@ Using Azure Pipelines, developers can streamline the process of publishing their 1. Select **Create** when you're done. -1. Select **Copy** and save your API key in a safe location. +1. Select **Copy** and save your API key in a secure location. ## Create a service connection -1. Sign in to your Azure DevOps organization `https://dev.azure.com/` and then navigate to your project. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select ![gear icon](../../media/icons/gear-icon.png) **Project settings** located at the bottom left corner of the page. +1. Select ![gear icon](../../media/icons/gear-icon.png) **Project settings** in the bottom left corner of the page. 1. Select **NuGet**, and then select **Next**. -1. Select **ApiKey** as your authentication method and set the **Feed URL** to the following: `https://api.nuget.org/v3/index.json`. +1. Select **ApiKey** as your authentication method and set the **Feed URL** to: `https://api.nuget.org/v3/index.json`. -1. Enter the ApiKey you generated earlier in the **ApiKey** field, and then provide a name for your service connection. +1. Enter the ApiKey you created earlier in the **ApiKey** field, and provide a name for your service connection. -1. Check the **Grant access permission to all pipelines** checkbox, and then select **Save** when you're done. To select this option, you'll need the service connection **Administrator** role. +1. Select the **Grant access permission to all pipelines** checkbox, and then select **Save** when you're done. ## Publish packages -1. Sign in to your Azure DevOps organization `https://dev.azure.com/` and then navigate to your project. +> [!NOTE] +> If you're using Ubuntu 24.04 or higher, you must use the `NuGetAuthenticate` task with the .NET CLI instead of the `NuGetCommand@2` task. See [Support for newer Ubuntu hosted images](/azure/devops/pipelines/tasks/reference/nuget-command-v2#support-for-newer-ubuntu-hosted-images) for more details. + +#### [YAML](#tab/yaml/) -1. Select **Pipelines**, and then select your pipeline. Select **Edit** to edit your pipeline. +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, select your pipeline definition, and then select **Edit**. + +1. Add the following snippet to your YAML pipeline. Replace the placeholder with the name of the service connection you created earlier: + + ```yml + steps: + - task: DotNetCoreCLI@2 + displayName: 'dotnet pack' + inputs: + command: pack + - task: NuGetCommand@2 + displayName: 'NuGet push' + inputs: + command: push + nuGetFeedType: external + publishFeedCredentials: + ``` #### [Classic](#tab/classic/) -3. Select **+** to add a new task, and then search for the **.NET Core** task. select **Add** to add it to your pipeline. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -4. Select the **pack** command from the command's dropdown menu, and then select the **Path to csproj or nuspec file(s) to pack**. You can keep the default values for the other fields depending on your scenario. +1. Select **Pipelines**, select your pipeline definition, and then select **Edit**. - :::image type="content" source="media/dotnet-pack-task.png" alt-text="A screenshot showing how to configure the dotnet pack task in a classic pipeline."::: +1. Select **+** to add a new task, and then add the **.NET Core** task to your pipeline. -5. Select **+** to add a new task, and then search for the **NuGet** task. select **Add** to add it to your pipeline. +1. From the command dropdown, select **pack**, and then select the **Path to csproj or nuspec file(s) to pack**. You can leave the default values for the other fields. -6. Select the **push** command from the command's dropdown menu, and then select the **Path to NuGet package(s) to publish**. +1. Select **+** to add another task, then add the **NuGet** task to your pipeline. -7. Select **External NuGet server** for your **Target feed location**. Then, in the **NuGet server** field, select the service connection you created earlier. +1. From the command dropdown, select **push**, and then select the **Path to NuGet package(s) to publish**. - :::image type="content" source="media/nuget-push-task.png" alt-text="A screenshot showing how to configure a NuGet push task to an external NuGet server."::: +1. Select **External NuGet server** for the **Target feed location**, and then select the service connection you created earlier from **NuGet server** dropdown menu. -#### [YAML](#tab/yaml/) + :::image type="content" source="media/nuget-push-task.png" alt-text="A screenshot displaying how to configure a NuGet push task to an external NuGet server."::: -3. Add the following task to build your project and create your NuGet package. - -```yml -steps: -- task: DotNetCoreCLI@2 - displayName: 'dotnet pack' - inputs: - command: pack -``` - -4. Add the following tasks to your YAML pipeline to publish your NuGet package to NuGet.org. Replace the placeholder with the name of the service connection you created earlier. - -```yml -steps: -- task: NuGetCommand@2 - displayName: 'NuGet push' - inputs: - command: push - nuGetFeedType: external - publishFeedCredentials: -``` --- -Once completed, you can visit the [packages](https://www.nuget.org/account/Packages) page on nuget.org, where you can find your recently published package listed at the top. +Once the pipeline completes successfully, navigate to the [packages](https://www.nuget.org/account/Packages) page on *NuGet.org*, where you will find your recently published package listed at the top. -:::image type="content" source="media/published-package.png" alt-text="A screenshot showing the published packages in nuget.org."::: +:::image type="content" source="media/published-package.png" alt-text="A screenshot showing the published packages on NuGet.org."::: -## Related articles +## Related content -- [Release triggers](../release/triggers.md) -- [Deploy from multiple branches](../release/deploy-multiple-branches.md) +- [Publish packages to internal and external feeds](nuget.md) +- [Restore NuGet packages with Azure Pipelines](../packages/nuget-restore.md) - [Pipeline caching](../release/caching.md) \ No newline at end of file diff --git a/docs/pipelines/artifacts/pull-package-gradle.md b/docs/pipelines/artifacts/pull-package-gradle.md deleted file mode 100644 index 6151ed4dd2a..00000000000 --- a/docs/pipelines/artifacts/pull-package-gradle.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Build and publish Artifacts using Gradle -description: How to build and publish artifact with Gradle and Azure Pipelines -ms.reviewer: dastahel -ms.topic: conceptual -ms.date: 08/18/2022 -monikerRange: '<= azure-devops' -"recommendations": "true" ---- - -# Build and publish artifacts with Gradle and Azure Pipelines - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Gradle is a popular build tool for Java applications and the primary build tool for Android. Using Azure Pipelines, we can add the gradle task to our build definition and build and publish our build artifacts. - -## Prerequisites - -- [Install Java](https://www.oracle.com/technetwork/java/javase/downloads/index.html). -- [Install Gradle](https://gradle.org/install/). - -To make sure you have all the prerequisites set up, run the following command in an elevated command prompt to check which Java version is installed on your machine. - -```Command -java -version -``` - -If the above command doesn't return a java version, make sure you go back and install the Java JDK or JRE first. - -To confirm the installation of Gradle, run the following command in an elevated command prompt: - -```Command -gradle -v -``` - -## Set up authentication - -::: moniker range=">= azure-devops-2019" - -1. Select **User settings**, and then select **Personal access tokens** - - :::image type="content" source="media/create-pat.png" alt-text="Screenshot showing how to create a personal access token"::: - -2. Select **New Token**, and then fill out the required fields. Make sure you select the **Packaging** > **Read & write** scope. - - :::image type="content" source="media/create-packaging-pat.png" alt-text="Screenshot showing how to create a new personal access token."::: - -3. Select **Create** when you're done. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Select your profile icon, and then select **Security**. - -2. Select **New Token**, and then name your token and set its expiration date. - -3. Select the **Packaging (Read & write)** scope. - - :::image type="content" source="media/select-scope.png" alt-text="Screenshot showing the available scopes for a pat."::: - -::: moniker-end - -4. Copy your token and save it in a secure location. - -5. Create a new file in your `.gradle` folder and name it **gradle.properties**. The path to your gradle folder is usually in `%INSTALLPATH%/gradle/user/home/.gradle/`. - -6. Open the **gradle.properties** file with a text editor and add the following snippet: - - ``` - vstsMavenAccessToken= - ``` - -7. Save your file when you're done. - -## Build projects with Gradle CLI - -1. Open your *build.gradle* file and make sure it starts with the following: - - ```groovy - apply plugin: 'java' - ``` - -1. Add the following snippet to your *build.gradle* file to download your artifact during the build. Replace the placeholders with your groupID, artifactID, and versionNumber. For example: `compile(group: 'siteOps', name: 'odata-wrappers', version: '1.0.0.0') - - ```groovy - dependencies { - compile(group: '', name: '', version: '') - } - ``` - -To test this, we can create a sample Java console app and build it with Gradle. - -```java -public class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, world!"); - } -} -``` - -Run the following command to build your project. Your build output should return: `BUILD SUCCESSFUL` - -```Command -gradle build -``` - -## Use Gradle in Azure Pipelines - -1. Run the following command to create the Gradle wrapper **gradlew**. - - ```cli - gradle wrapper - ``` - -1. Push your changes to your remote branch. We will need this file later when we add the **Gradle** task. - -1. Navigate to your pipeline definition. If you don't have one, create a new pipeline, select **Use the classic editor** and then select the **Gradle** template. - - :::image type="content" source="media/select-gradle-template.png" alt-text="Screenshot showing how to use the Gradle pipeline template"::: - -1. You can use the default settings with the **gradlew build** task. - - :::image type="content" source="media/gradle-build-template.png" alt-text="Screenshot showing the Gradle task"::: - -1. The **Publish build artifacts** task will publish our artifact to Azure Pipelines. - - :::image type="content" source="media\publish-gradle-pipeline.png" alt-text="Screenshot showing the publish artifacts task."::: - -1. Select **Save & queue** when you're done. - -1. You can view your published artifact in your pipeline **Summary** once the run is complete. - - :::image type="content" source="media\published-artifact.png" alt-text="Screenshot showing the published artifact in pipeline summary."::: - -## Related articles - -- [Publish and download pipeline Artifacts](./pipeline-artifacts.md) -- [Restore NuGet packages in Azure Pipelines](../packages/nuget-restore.md) -- [Artifacts in Azure Pipelines](./build-artifacts.md) diff --git a/docs/pipelines/artifacts/pypi.md b/docs/pipelines/artifacts/pypi.md index 9818c3063cb..f4871da51a9 100644 --- a/docs/pipelines/artifacts/pypi.md +++ b/docs/pipelines/artifacts/pypi.md @@ -1,139 +1,139 @@ --- -title: Publish Python packages -ms.custom: seodec18, devx-track-python -description: How to publish Python packages with Azure Pipelines +title: Publish Python packages with Azure Pipelines +ms.custom: devx-track-python +description: Learn how to publish Python packages to an Azure Artifacts feed using Azure Pipelines. services: vsts ms.topic: conceptual -ms.date: 02/03/2022 -monikerRange: azure-devops +ms.date: 12/13/2024 +monikerRange: "<=azure-devops" "recommendations": "true" --- # Publish Python packages with Azure Pipelines -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] -Using Azure Pipelines, you can publish your Python packages to Azure Artifacts feeds, public registries, or as a pipeline artifacts. +Azure Pipelines enables developers to publish Python packages to Azure Artifacts feeds and public registries such as PyPi. This article will guide you through how to publish Python packages to your Azure Artifacts feed. -This article will show you how to: +## Prerequisites -> [!div class="checklist"] -> * Install `Twine` -> * Authenticate with your Azure Artifacts feeds -> * Publish Python packages to an Azure Artifacts feed +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. -## Install twine +- An Azure Artifacts feed. [Create a feed](../../artifacts/concepts/feeds.md#create-a-public-feed) if you don't have one already. -#### [YAML](#tab/yaml/) +## Authenticate with a feed -```yaml -- script: 'pip install twine' -``` +To publish Python packages using twine, you must first authenticate with your Azure Artifacts feed. The [TwineAuthenticate task](/azure/devops/pipelines/tasks/reference/twine-authenticate-v1) provides twine credentials to a `PYPIRC_PATH` environment variable. This variable is then used by`twine` to publish packages directly from your pipeline. -#### [Classic](#tab/classic/) +> [!IMPORTANT] +> The credentials stored in the `PYPIRC_PATH` environment variable take precedence over those in the `.ini` and `.conf` files. +> +> If you add multiple *TwineAuthenticate* tasks at different stages in your pipeline, each task execution will extend **(not override)** the existing `PYPIRC_PATH` environment variable. -1. From your pipeline definition, select `+` to add a new task. Search for the **PowerShell** task ![PowerShell icon](../tasks/utility/media/powershell.png). +# [YAML](#tab/yaml) -1. Select **Add** to add the task to your pipeline. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Inline** for your script **Type** +1. Select **Pipelines**, and then select your pipeline definition. -1. Enter the following command in the script area +1. Select **Edit**, and then add the following snippet to your YAML pipeline. - ```Command - pip install twine + ```yaml + steps: + - task: UsePythonVersion@0 + displayName: 'Use Python 3.x' + + - task: TwineAuthenticate@1 + inputs: + artifactFeed: ## For an organization-scoped feed, use: artifactFeed: ``` -:::image type="content" source="media/powershell-pipelines.png" alt-text="Screenshot of the PowerShell task in Azure Pipelines"::: +# [Classic](#tab/classic) -* * * +1. Sign in to your Azure DevOps organization, and then navigate to your project. -## Authenticate with Azure Artifacts +1. Select **Pipelines**, select your pipeline definition, and then select **Edit**. -To use `twine` to publish your Python packages, you must first set up authentication to your Azure Artifacts feed. The [TwineAuthenticate](/azure/devops/pipelines/tasks/reference/twine-authenticate-v1) task stores your credentials in a `PYPIRC_PATH` environment variable. `twine` will reference this variable to publish your packages from your pipeline. +1. Select the `+` sign to add a new task, then add the **Use Python version** and the **Python twine upload authenticate** tasks to your pipeline definition. You can leave the *UsePythonVersion@0* task with the default settings and configure the *TwineAuthenticate@1* as follows: -# [YAML](#tab/yaml) + 1. Select your feed from the **My feed name** dropdown menu. To authenticate with a feed outside your organization, select a **Feed from external organizations** and create a new service connection. -```yaml -- task: TwineAuthenticate@1 - inputs: - artifactFeed: #For an organization-scoped feed, artifactFeed: - pythonUploadServiceConnection: -``` + :::image type="content" source="media/twine-authenticate-publish-to-feed.png" alt-text="A screenshot displaying how to configure the twine upload authenticate task in Azure Pipelines."::: -- **artifactFeed**: The name of your feed. -- **pythonUploadServiceConnection**: a [service connection](../library/service-endpoints.md#python-package-upload-service-connection) to authenticate with twine. +* * * -# [Classic](#tab/classic) +## Publish Python packages to a feed -1. From your pipeline definition, select `+` to add a new task. Search for the **Python twine upload authenticate** task :::image type="icon" source="../tasks/package/media/python-twine-authenticate.png" border="false"::: +> [!NOTE] +> To publish your packages to a feed using Azure Pipelines, make sure that both the **Project Collection Build Service** and your project's **Build Service** identities are assigned the **Feed Publisher (Contributor)** role in your feed settings. See [Manage permissions](../../artifacts/feeds/feed-permissions.md) for details. -1. Select **Add** to add the task to your pipeline. +# [YAML](#tab/yaml) -1. Select your feed from the **My feed** dropdown menu or select a **Feed from external organizations** if you want to authenticate with a feed outside your organization. +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select your pipeline definition. + +1. Select **Edit**, and then add the following snippet to your YAML pipeline. + + ```YAML + steps: + - task: UsePythonVersion@0 + displayName: 'Use Python 3.x' + + - script: | + pip install build + pip install twine + displayName: 'Install build and twine' + + - script: | + python -m build -w + displayName: 'Python build' + + - task: TwineAuthenticate@1 + inputs: + artifactFeed: ## For an organization-scoped feed, use: artifactFeed: + displayName: 'Twine Authenticate' + + - script: | + python -m twine upload -r --config-file $(PYPIRC_PATH) dist/*.whl + displayName: 'Upload to feed' + ``` -:::image type="content" source="media/twine-authenticate.png" alt-text="Screenshot of the Python twine task in Azure Pipelines"::: +# [Classic](#tab/classic) -* * * +1. Sign in to your Azure DevOps organization, and then navigate to your project. -> [!TIP] -> The credentials stored in the `PYPIRC_PATH` environment variable supersede those in your `.ini` and `.conf` files. -> If you add multiple TwineAuthenticate tasks at different stages in your pipeline, each additional task execution will extend **(not override)** the existing `PYPIRC_PATH` environment variable. +1. Select **Pipelines**, select your pipeline definition, and then select **Edit**. -## Publish Python packages to Azure Artifacts feeds +1. Select the `+` sign to add a new task, then add the **Use Python version** task to your pipeline. In this example we're setting the **Version spec** to *>= 3.7*. -# [YAML](#tab/yaml) +1. Add the **Command line** task to your pipeline, and paste the following commands into the **Script** textbox to install *build* and *twine* on your agent: -```YAML -- script: | -   pip install wheel -   pip install twine -  -- script: | -   python setup.py bdist_wheel -  -- task: TwineAuthenticate@1 -  displayName: Twine Authenticate -  inputs: -    artifactFeed: #For an organization-scoped feed, artifactFeed: . -  -- script: | -   python -m twine upload -r --config-file $(PYPIRC_PATH) dist/*.whl -``` - -Example using [Python build](https://pypi.org/project/build/) and [twine](https://pypi.org/project/twine/) to publish a Python package to an Azure Artifacts feed. - -```YAML -- script: | - pip install twine + ```command pip install build + pip install twine + ``` -- script: | +1. Add another **Command line** task to your pipeline, and then paste the following command into the **Script** textbox to build your project: + + ```command python -m build -w + ``` -- task: TwineAuthenticate@1 - inputs: - artifactFeed: +1. Add for the **Twine Authenticate** task to your pipeline, and select your feed from the **My feed name** dropdown menu. -- script: | +1. Add another **Command line** task to your pipeline, and paste the following command into the **Script** textbox to publish your package to your feed, replacing the placeholder with your feed's name: + + ```command python -m twine upload -r --config-file $(PYPIRC_PATH) dist/*.whl - displayName: 'upload' -``` - -# [Classic](#tab/classic) - -- **Twine Authenticate**: - - :::image type="content" source="media/twine-authenticate.png" alt-text="Screenshot of the twine authenticate task to publish python packages."::: - -- **PowerShell**: + ``` - :::image type="content" source="media/powershell-pipelines.png" alt-text="Screenshot of the PowerShell task to publish python packages."::: + :::image type="content" source="media/publish-to-feed-python-classic.png" alt-text="A screenshot displaying a Classic pipeline to publish Python packages to an Azure Artifacts feed."::: * * * -## Related articles +## Related content -- [Publish and download pipeline Artifacts](./pipeline-artifacts.md) -- [Artifacts in Azure Pipelines](./build-artifacts.md) -- [Release artifacts and artifact sources](../release/artifacts.md) +- [Publish and download pipeline artifacts](build-artifacts.md) +- [Set up upstream sources](../../artifacts/how-to/set-up-upstream-sources.md) +- [Use the .artifactignore file](../../artifacts/reference/artifactignore.md) diff --git a/docs/pipelines/artifacts/symbols.md b/docs/pipelines/artifacts/symbols.md index 9b7bfb296fe..5b0350ffbbb 100644 --- a/docs/pipelines/artifacts/symbols.md +++ b/docs/pipelines/artifacts/symbols.md @@ -1,14 +1,13 @@ --- -title: Publish symbols with Azure Pipelines -ms.custom: seodec18, contperf-fy22q1 -description: How to publish symbols to Azure Artifacts symbol server +title: Publish symbols for debugging +description: How to publish symbols to Azure Artifacts symbol server and file shares using Azure Pipelines ms.assetid: 8794A5F8-B646-4E2F-A426-47CC62ABFF5D -ms.date: 04/08/2022 +ms.date: 09/22/2023 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Publish symbols for debugging +# Publish symbols with Azure Pipelines [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -17,78 +16,115 @@ With Azure Pipelines, you can publish your symbols to Azure Artifacts symbol ser > [!NOTE] > The [Index sources and publish symbols](/azure/devops/pipelines/tasks/reference/publish-symbols-v2) task is not supported in release pipelines. -::: moniker range="azure-devops" - ## Publish symbols to Azure Artifacts symbol server -To publish your symbols to Azure Artifacts symbols server, you can use the *Index Sources & Publish Symbols* task. +# [Classic](#tab/classic) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, select your pipeline, and then select **Edit** to modify your pipeline. 1. From your pipeline definition, select `+` to add a new task. 1. Search for the **Index sources and publish symbols** task. Select **Add** to add it to your pipeline. - :::image type="content" source="media/index-sources-publish-symbols.png" alt-text="Screenshot showing how to add the index sources and publish symbols to the current pipeline"::: - 1. Fill out the required fields as follows: - :::image type="content" source="media/publish-to-symbol-server.png" alt-text="Screenshot showing the index sources and publish symbols task to publish symbols to Azure Artifacts symbol server"::: + - **Task version**: **2.\\***. + + - **Display name**: task display name. + + - **Path to symbols folder**: path to the folder hosting the symbol files. -- **Task version**: **2.\\***. + - **Search pattern**: the pattern used to locate the *.pdb* files in the folder you've designated under *Path to symbols folder*. Single-folder wildcard (`*`) and recursive wildcards (`**`) are both supported. Example: ***\bin\**\*.pdb*: will search for all *.pdb* files within all subdirectories named *bin*. -- **Display name**: task display name. + - **Index sources**: indicates whether to inject source server information into the PDB files. -- **Path to symbols folder**: path to the folder hosting the symbol files. + - **Publish symbols**: indicates whether to publish the symbol files. + - **Symbol server type**: select **Symbol Server in this organization/collection (requires Azure Artifacts)** to publish your symbols to Azure Artifacts symbol server. -- **Search pattern**: the pattern used to find the pdb files in the folder that you specified in **Path to symbols folder**. Single-folder wildcard (`*`) and recursive wildcards (`**`) are supported. Example: ***\bin\**\*.pdb* searches for all .pdb files in all the *bin* subdirectories. + - **Verbose logging**: include more information in your logs. -- **Index sources**: indicates whether to inject source server information into the PDB files. + :::image type="content" source="media/publish-to-symbol-server.png" alt-text="Screenshot showing how to configure the index sources and publish symbols task to publish symbols to Azure Artifacts symbol server."::: -- **Publish symbols**: indicates whether to publish the symbol files. - - **Symbol server type**: select **Symbol Server in this organization/collection (requires Azure Artifacts)** to publish your symbols to Azure Artifacts symbol server. +# [YAML](#tab/yaml) -- **Verbose logging**: check to include more information in your logs. +To publish your symbols to Azure Artifacts symbol server add the following snippet to your YAML pipeline: -::: moniker-end +```yml +- task: PublishSymbols@2 + inputs: + SymbolsFolder: '$(Build.SourcesDirectory)' + SearchPattern: '**/bin/**/*.pdb' + IndexSources: true + PublishSymbols: true + SymbolServerType: 'TeamServices' + SymbolExpirationInDays: '36530' + IndexableFileFormats: 'Default' + DetailedLog: true + SymbolsArtifactName: 'Symbols_$(BuildConfiguration)' +``` + +--- ## Publish symbols to a file share Aside from Azure Artifacts symbol server, you can also publish your symbols to a file share using the *Index Sources and Publish Symbols* task. +# [Classic](#tab/classic) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, select your pipeline, and then select **Edit** to modify your pipeline. + 1. From your pipeline definition, select `+` to add a new task. 1. Search for the **Index sources and publish symbols** task. Select **Add** to add it to your pipeline. - :::image type="content" source="media/index-sources-publish-symbols.png" alt-text="Screenshot showing how to add the index sources and publish symbols to the current pipeline"::: - 1. Fill out the required fields as follows: - :::image type="content" source="media/publish-to-file-share.png" alt-text="Screenshot showing the index sources and publish symbols task to publish symbols to a file share"::: + - **Task version**: **2.\\***. + + - **Display name**: task display name. + + - **Path to symbols folder**: path to the folder hosting the symbol files. -- **Task version**: **2.\\***. + - **Search pattern**: the pattern used to locate the *.pdb* files in the folder you've designated under *Path to symbols folder*. -- **Display name**: task display name. + - **Index sources**: indicates whether to inject source server information into the PDB files. -- **Path to symbols folder**: path to the folder hosting the symbol files. + - **Publish symbols**: indicates whether to publish the symbol files. + - **Symbol server type**: select **File share** to publish your symbols to a file share. + - **Path to publish symbols**: the file share that will host your symbols. -- **Search pattern**: the pattern used to find the pdb files in the folder that you specified in **Path to symbols folder**. + - **Verbose logging**: check to include more information in your logs. -- **Index sources**: indicates whether to inject source server information into the PDB files. + :::image type="content" source="media/publish-to-file-share.png" alt-text="Screenshot showing how to configure the index sources and publish symbols task to publish symbols to a file share."::: -- **Publish symbols**: indicates whether to publish the symbol files. - - **Symbol server type**: select **File share** to publish your symbols to a file share. - - **Path to publish symbols**: the file share that will host your symbols. +# [YAML](#tab/yaml) -- **Verbose logging**: check to include more information in your logs. +To publish your symbols to a file share add the following snippet to your YAML pipeline: -::: moniker range="azure-devops" +```yml +- task: PublishSymbols@2 + inputs: + SymbolsFolder: '$(Build.SourcesDirectory)' + SearchPattern: '**/bin/**/*.pdb' + IndexSources: true + PublishSymbols: true + SymbolServerType: 'FileShare' + SymbolsPath: '\\server\shareName' +``` + +--- ## Publish portable PDBs to Azure Artifacts symbol server Portable PDBs are symbol files that can be created and used on all platforms unlike the traditional PDBs which are used on Windows only. For portable PDBs, the build does the indexing, but you still need to use the **Index Sources and Publish Symbols** task to publish your symbols. -### Use Source Link in .NET projects +#### Use Source Link in .NET projects -Source link is a set of tools that allow developers to debug their source code by mapping from the .NET assemblies back to the source code. Check out the [dotnet/sourcelink](https://github.com/dotnet/sourcelink) GitHub repository to learn about the different packages included. +Source Link is a set of tools that allow developers to debug their source code by mapping from the .NET assemblies back to the source code. Check out the [dotnet/sourcelink](https://github.com/dotnet/sourcelink) GitHub repository to learn about the different packages included. - For projects hosted on GitHub, add the `Microsoft.SourceLink.GitHub` package reference to your project file. @@ -98,7 +134,7 @@ Source link is a set of tools that allow developers to debug their source code b ``` -- For projects hosted on Azure Repos, add the `Microsoft.SourceLink.AzureRepos.Git` package reference to your project file. +- For projects hosted on Azure Repos (former Visual Studio Team Services), add the `Microsoft.SourceLink.AzureRepos.Git` package reference to your project file. ```xml @@ -106,7 +142,7 @@ Source link is a set of tools that allow developers to debug their source code b ``` -- For projects hosted on Azure DevOps Server, add the `Microsoft.SourceLink.AzureDevOpsServer.Git` package reference to your project file. +- For projects hosted on Azure DevOps Server (former Team Foundation Server), add the `Microsoft.SourceLink.AzureDevOpsServer.Git` package reference to your project file. ```xml @@ -114,36 +150,51 @@ Source link is a set of tools that allow developers to debug their source code b ``` -### Set up the publish task +#### Set up the publish task + +The Index Sources & Publish Symbols task is used to index your source code and publish your symbols to Azure Artifacts symbols server and file shares. Because we're using **Source Link**, we'll have to **disable indexing** in the publish task. -The Index Sources & Publish Symbols task is used to index your source code and publish your symbols to Azure Artifacts symbols server. Because we are using Source Link, we will disable indexing in the publish task. +# [Classic](#tab/classic) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, select your pipeline, and then select **Edit** to modify your pipeline. 1. From your pipeline definition, select `+` to add a new task. 1. Search for the **Index sources and publish symbols** task. Select **Add** to add it to your pipeline. - :::image type="content" source="media/index-sources-publish-symbols.png" alt-text="Screenshot showing how to add the index sources and publish symbols to the current pipeline"::: +1. Fill out the required fields and select *Symbol Server* for the **Symbol server type**. Make sure you uncheck **Index sources** to disable indexing. -1. Fill out the required fields as follows: + :::image type="content" source="media/publish-to-symbol-server-indexing-disabled.png" alt-text="A screenshot showing how to configure the publish task to publish portable PDBs to Azure Artifacts symbol server."::: - :::image type="content" source="media/publish-to-symbol-server-indexing-disabled.png" alt-text="Screenshot showing how to configure the publish task to publish symbols to Azure Artifacts symbol server"::: +# [YAML](#tab/yaml) -- **Task version**: **2.\\***. +To publish your portable PDBs to Azure Artifacts symbol server add the following snippet to your YAML pipeline: -- **Index sources**: Uncheck to disable indexing. Source indexing in the publish task is not needed when using Source Link. +```yml +- task: PublishSymbols@2 + inputs: + SymbolsFolder: '$(Build.SourcesDirectory)' + SearchPattern: '**/bin/**/*.pdb' + IndexSources: false + PublishSymbols: true + SymbolServerType: 'TeamServices' + SymbolExpirationInDays: '36530' + IndexableFileFormats: 'Default' + DetailedLog: true + SymbolsArtifactName: 'Symbols_$(BuildConfiguration)' +``` -- **Publish symbols**: indicates whether to publish the symbol files. - - **Symbol server type**: select **Symbol Server in this organization/collection (requires Azure Artifacts)** to publish your symbols to Azure Artifacts symbol server. +--- > [!IMPORTANT] -> To delete symbols that were published using the *Index Sources & Publish Symbols* task, you must first delete the build that generated those symbols. This can be accomplished by using [retention policies](../build/ci-build-git.md#use-retention-policies-to-clean-up-your-completed-builds) or by manually [deleting the run](../policies/retention.md#delete-a-run). - -::: moniker-end +> To delete symbols published via the *Index Sources & Publish Symbols* task, you must first delete the build that generated those symbols. This can be accomplished by using [retention policies](../policies/retention.md) or by manually [deleting the run](../policies/retention.md#delete-a-run). ## Set up Visual Studio > [!NOTE] -> Visual Studio for Mac does not support provide support debugging using symbol servers. +> Visual Studio for Mac does not support debugging using symbol servers. Before starting to consume our symbols from Azure Artifacts symbol server, let's make sure that Visual Studio is set up properly: @@ -153,24 +204,24 @@ Before starting to consume our symbols from Azure Artifacts symbol server, let's 1. Select the `+` sign to add a new symbol server location. - :::image type="content" source="../../artifacts/symbols/media/vs-symbols-location.png" alt-text="Screenshot showing how to add a new symbol server location"::: + :::image type="content" source="../../artifacts/symbols/media/vs-symbols-location.png" alt-text="Screenshot showing how to add a new symbol server location."::: -1. A new dialog box will open, select your account from the dropdown menu, and then select the organization that you wish to connect to. Select **Connect** when you are done. +1. A new dialog box will appear, select your account from the dropdown menu, and then select the organization that you wish to connect to. Select **Connect** when you're done. 1. Select **General** from the same **Debugging** section. Scroll down and check **Enable Source Link support** to enable support for portable PDBs. - :::image type="content" source="../../artifacts/symbols/media/enable-source-link-support.png" alt-text="Enable source link support"::: + :::image type="content" source="../../artifacts/symbols/media/enable-source-link-support.png" alt-text="A screenshot showing how to enable source link support in Visual studio."::: > [!NOTE] -> Checking the **Enable source server support** option enables you to use [Source Server](/visualstudio/debugger/general-debugging-options-dialog-box) when there is no source code on the local machine or the symbol file does not match the source code. If you want to enable third-party source code debugging, uncheck the **Enable Just My Code** checkbox. +> Checking the **Enable source server support** option allows you to use [Source Server](/visualstudio/debugger/general-debugging-options-dialog-box) in cases where the source code isn't available locally or the symbol file does not match the source code. If you want to enable debugging for third-party source code, deselect the **Enable Just My Code** checkbox. ## FAQs -### Q: What is the duration for which symbols are retained? +##### Q: What is the duration for which symbols are retained? A: A symbol file has the same retention period as the build that generated it. When you delete a build either manually or using retention policies, the symbols that were generated by that build will be deleted as well. -### Q: Can I use source indexing on a portable PDB generated from a .NET Core assembly? +##### Q: Can I use source indexing on a portable PDB generated from a .NET Core assembly? A: This is not possible at the moment. Source indexing is not currently supported for portable PDBs. The recommended approach is to configure your build to do the indexing. diff --git a/docs/pipelines/artifacts/universal-packages.md b/docs/pipelines/artifacts/universal-packages.md index 76150b0e464..7415fd58fc1 100644 --- a/docs/pipelines/artifacts/universal-packages.md +++ b/docs/pipelines/artifacts/universal-packages.md @@ -1,11 +1,9 @@ --- title: Publish & download Universal Packages -ms.custom: seodec18, contperf-fy21q4 -description: Publish and download Universal Packages with Azure Pipelines YAML/Classic -services: vsts +description: Learn how to publish and download Universal Packages with Azure Pipelines YAML/Classic ms.assetid: 6c980df0-9e90-4625-88c9-955b11d54f10 -ms.topic: conceptual -ms.date: 05/05/2023 +ms.topic: how-to +ms.date: 02/27/2025 monikerRange: 'azure-devops' --- @@ -13,133 +11,140 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Universal Packages allow you to package any number of files of any type and share them with your team. Using the Universal Package task in Azure Pipelines, you can pack, publish, and download packages of various sizes, up to 4 TB. Each package is uniquely identified with a name and a version number. You can use Azure CLI or Azure Pipelines to publish and consume packages from your Artifacts feeds. +Universal Packages lets you package and share any number of files, regardless of type, with your team or target audience. Using the Universal Package task in Azure Pipelines, you can pack, publish, and download packages as large as 4 TiB. Each package is identified by a unique name and version number. You can use Azure CLI or Azure Pipelines to publish and download packages from your Artifacts feeds. > [!NOTE] > Universal Packages are only available in Azure DevOps Services. +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).
      - **Permissions:**
          - To grant access to all pipelines in the project, you must be a member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md).
          - To create service connections, you must have the *Administrator* or *Creator* role for [service connections](../library/add-resource-protection.md). | + ## Copy files -The Universal Packages task in Azure Pipelines is set to use `$(Build.ArtifactStagingDirectory)` as the default publish directory. To ready your Universal Package for publishing, move the files you wish to publish to that directory. You can also use the [Copy Files](/azure/devops/pipelines/tasks/reference/copy-files-v2) utility task to copy those files to the publish directory. +The Universal Packages task in Azure Pipelines uses `$(Build.ArtifactStagingDirectory)` as the default location for the files you wish to publish. To prepare your Universal Package for publishing, move the files you want to publish to this directory. You can also use the [Copy Files](/azure/devops/pipelines/tasks/reference/copy-files-v2) utility task to copy the files to the publish directory. ## Publish a Universal Package -# [YAML](#tab/yaml) +### [YAML](#tab/yaml) -To publish a Universal Package to your Azure Artifacts feed, add the following task to your pipeline's YAML file. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -```yaml -- task: UniversalPackages@0 - displayName: Publish a Universal Package - inputs: - command: publish - publishDirectory: '$(Build.ArtifactStagingDirectory)' - vstsFeedPublish: '/' - vstsFeedPackagePublish: '' - packagePublishDescription: '' -``` +1. Select **Pipelines**, and then select your pipeline definition. -| Argument | Description | -|-----------------------------|---------------------------------------------------------------------------------------------------------------------------| -| publishDirectory | Location of the files you wish to publish. | -| vstsFeedPublish | The project and feed name to publish to. If you're working with an organization-scoped feed, specify only the feed name. | -| vstsFeedPackagePublish | The package name. Must be lower case. Use only letters, numbers, and dashes. | -| packagePublishDescription | Description of the package content. | +1. Select **Edit**, and then add the following snippet to your YAML pipeline. -To publish packages to an Azure Artifacts feed from your pipeline, you must add the **Project Collection Build Service** identity as a **Contributor** from your feed's settings. See [Adding users/groups permissions to a feed](../../artifacts/feeds/feed-permissions.md) for more details. + ```yaml + - task: UniversalPackages@0 + displayName: Publish + inputs: + command: publish + publishDirectory: '$(Build.ArtifactStagingDirectory)' ## Location of the files you wish to publish + vstsFeedPublish: '/' ## The project and feed name to publish to. If you're working with an organization-scoped feed, specify only the feed name + vstsFeedPackagePublish: '' ## The package name. Must be lower case. Use only letters, numbers, and dashes + packagePublishDescription: '' ## Description of the package content + ``` -To publish to an external feed, you must first create a service connection to authenticate with your feed. see [Manage service connection](../library/service-endpoints.md) for more details. +### [Classic](#tab/classic) -# [Classic](#tab/classic) +1. Sign in to your Azure DevOps organization, and then navigate to your project. -To publish your Universal Package, add the **Universal Package** task to your pipeline and fill out the required fields as follows +1. Select **Pipelines**, and then select your pipeline definition. -- **Command:** Publish -- **Path to file(s) to publish:** The path to the list of files to be published. Default: `$(Build.ArtifactStagingDirectory)`. -- **Feed location:** Publish to an Azure Artifacts feed in your current organization or in another organization. -- **Destination feed:** Select the feed that you want to publish to. -- **Package name:** Select an existing package (to publish a new version of that package), or enter a new package name (to publish the first version of a new package). +1. Select **Edit**, and then select the `+` sign to add a new task. Add the **Universal Packages** task and configure it as follows: - :::image type="content" source="media/universal-packages/publish.png" alt-text="A screenshot showing how to publish a universal package using a classic pipeline."::: + :::image type="content" source="media/universal-packages/publish.png" alt-text="A screenshot displaying how to publish a Universal Packages using Classic pipelines."::: -[!INCLUDE [package management permissions](includes/package-management-permissions-for-web-build.md)] - -To publish to an external feed, you must first create a service connection to point to that feed. see [Manage service connection](../library/service-endpoints.md) for details. +- **Command:** Publish +- **Path to file(s) to publish:** Specify the path to the files you want to publish. Default: `$(Build.ArtifactStagingDirectory)`. +- **Feed location:** Publish to an Azure Artifacts feed in your current organization or in a different organization. +- **Destination feed:** Select the feed where you want to publish the package. +- **Package name:** Select an existing package to publish a new version, or enter a new package name to publish the first version of a new package. --- +> [!NOTE] +> To publish packages to a feed from your Pipelines, make sure that both the **Project Collection Build Service** and your project's **Build Service** identities have been granted the **Feed Publisher (Contributor)** role in the feed settings. See [Manage permissions](../../artifacts/feeds/feed-permissions.md) for more details. + ## Package versioning -Universal Packages follow the semantic versioning specification and can be identified by their names and version numbers. Semantic version numbers are composed of three numeric components, Major, Minor, and Patch, in the format: `Major.Minor.Patch`. +Universal Packages adhere to semantic versioning, which is based on three numeric components: Major, Minor, and Patch. The versioning format is `Major.Minor.Patch`. -The minor version number is incremented when new features are added that are backward compatible with previous versions, in this case, you increment the minor version and reset the patch version to 0 (`1.4.17` to `1.5.0`). The major version number is incremented when there are significant changes that could break compatibility with previous versions. In this case, you increment the major version and reset the minor and patch versions to 0 (`2.6.5` to `3.0.0`). The patch version number should be incremented when only bug fixes or other small changes are made that do not affect compatibility with previous versions (`1.0.0` to `1.0.1`). +- The minor version is increased when new features are added that are backward-compatible with previous versions. In this case, the minor version is incremented, and the patch version is reset to 0 (e.g., 1.4.17 to 1.5.0). +- The major version is incremented when there are significant changes that could break compatibility with previous versions, resetting both the minor and patch versions to 0 (e.g., 2.6.5 to 3.0.0). +- The patch version is incremented when bug fixes or other small changes that do not affect compatibility are applied (e.g., 1.0.0 to 1.0.1). When publishing a new package, the Universal Packages task will automatically select the next major, minor, or patch version for you. -# [YAML](#tab/yaml) +### [YAML](#tab/yaml) -To enable versioning for your package, add a `versionOption` input to your YAML file. The options for publishing a new package version are: `major`, `minor`, `patch`, or `custom`. +To enable versioning for your package, add a `versionOption` input to your UniversagePackage task. The available options for publishing a new version are: `major`, `minor`, `patch`, or `custom`. -Selecting `custom` enables you to manually specify your package version. The other options will get the latest package version from your feed and increment the chosen version segment by 1. So if you have a *testPackage 1.0.0*, and select the *major* option, your new package will be *testPackage 2.0.0*. If you select the *minor* option, your package version will be *1.1.0*, and if you select the *patch* option, your package version will be *1.0.1*. +Selecting `custom` enables you to manually specify your package version. The other options get the latest package version from your feed and increment the selected version segment by 1. For example, if you have a package *testPackage 1.0.0*: -Note that if you choose the `custom` option, you must also specify a `versionPublish` value as follows: +- Selecting `major` will update the version to testPackage 2.0.0. +- Selecting `minor` will update the version to 1.1.0. +- Selecting `patch` will update the version to 1.0.1. + +If you choose the `custom` option, you must also specify a `versionPublish` value as follows: ```yaml - task: UniversalPackages@0 - displayName: Publish a Universal Package + displayName: Publish inputs: command: publish - publishDirectory: '$(Build.ArtifactStagingDirectory)' - vstsFeedPublish: '/' - vstsFeedPackagePublish: '' - versionOption: custom - versionPublish: '' - packagePublishDescription: '' + publishDirectory: '$(Build.ArtifactStagingDirectory)' ## Location of the files you wish to publish + vstsFeedPublish: '/' ## The project and feed name to publish to. If you're working with an organization-scoped feed, specify only the feed name + vstsFeedPackagePublish: '' ## The package name. Must be lower case. Use only letters, numbers, and dashes + versionOption: custom ## Select a versioning strategy. Options: `major`, `minor`, `patch`, `custom` + versionPublish: '' ## The custom package version + packagePublishDescription: '' ## Description of the package content ``` -| Argument | Description | -|------------------------------|---------------------------------------------------------------------------------------------------------------------------| -| publishDirectory | Location of the files you wish to publish. | -| vstsFeedPublish | The project and feed name to publish to. If you're working with an organization-scoped feed, specify only the feed name. | -| vstsFeedPackagePublish | The package name. Must be lower case. Use only letters, numbers, and dashes. | -| versionOption | Select a versioning strategy. Options: `major`, `minor`, `patch`, `custom`. | -| versionPublish | The custom package version. | -| packagePublishDescription | Description of the package content. | +### [Classic](#tab/classic) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select your pipeline definition. -# [Classic](#tab/classic) +1. Select **Edit**, and then select the `+` sign to add a new task. Add the **Universal Packages** task and configure it as follows: -From the Universal Packages task form, select a versioning strategy, or select **Custom** to enter your package version manually. + :::image type="content" source="media/universal-packages/publish-versioning.png" alt-text="A screenshot displaying how to use a versioning strategy in a Classic pipeline."::: -:::image type="content" source="media/universal-packages/publish-versioning.png" alt-text="A screenshot showing how to use a versioning strategy in classic pipeline."::: +- **Command:** Publish +- **Path to file(s) to publish:** Specify the path to the files you want to publish. Default: `$(Build.ArtifactStagingDirectory)`. +- **Feed location:** Publish to an Azure Artifacts feed in your current organization or in a different organization. +- **Destination feed:** Select the feed where you want to publish the package. +- **Package name:** Select an existing package to publish a new version, or enter a new package name to publish the first version of a new package. +- **Version** Select a versioning strategy, or select **Custom** and enter your package version manually. --- ## Download a Universal Package -#### [YAML](#tab/yaml/) +### [YAML](#tab/yaml/) -To download a Universal Package from a feed in your organization, use the Universal Package task with the `download` command as follows: +1. Sign in to your Azure DevOps organization, and then navigate to your project. -```yaml -steps: -- task: UniversalPackages@0 - displayName: Download a Universal Package - inputs: - command: download - vstsFeed: '/' - vstsFeedPackage: '' - vstsPackageVersion: '' - downloadDirectory: '$(Build.SourcesDirectory)\someFolder' -``` +1. Select **Pipelines**, and then select your pipeline definition. -| Argument | Description | -| ------------------------------ | ------------------------------------------------------------------- | -| vstsFeed | The Artifacts feed hosting the package to be downloaded. | -| vstsFeedPackage | Name of the package to be downloaded. | -| vstsPackageVersion | Version of the package to be downloaded. | -| downloadDirectory | The package destination folder. Default value: $(System.DefaultWorkingDirectory). | +1. Select **Edit**, and then add the following snippet to your YAML pipeline. -To download a Universal Package from an external source, use the following snippet: + ```yaml + steps: + - task: UniversalPackages@0 + displayName: Download + inputs: + command: download + vstsFeed: '/' ## The Artifacts feed hosting the package to be downloaded + vstsFeedPackage: '' ## Name of the package to be downloaded + vstsPackageVersion: '' ## Version of the package to be downloaded + downloadDirectory: '$(Build.SourcesDirectory)\someFolder' ## The download folder. Default value: $(System.DefaultWorkingDirectory). + ``` + +To download a Universal Package from an external source, you can use the following example: ```yaml steps: @@ -147,24 +152,22 @@ steps: displayName: Download a Universal Package inputs: command: download - feedsToUse: external - externalFeedCredentials: 'MSENG2' - feedDownloadExternal: 'fabrikamFeedExternal' - packageDownloadExternal: 'fabrikam-package' - versionDownloadExternal: 1.0.0 + feedsToUse: external ## Set the value to `external` when downloading from an external source + externalFeedCredentials: 'MSENG2' ## Name of the service connection to the external feed + feedDownloadExternal: 'fabrikamFeedExternal' ## Name of the external feed + packageDownloadExternal: 'fabrikam-package' ## The package name you wish to download + versionDownloadExternal: 1.0.0 ## The version of the package you wish to download ``` -| Argument | Description | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -| feedsToUse | Set the value to `external` when downloading from an external source. | -| externalFeedCredentials | Name of the service connection to the external feed. See [manage service connections](../library/service-endpoints.md) for more details. | -| feedDownloadExternal | Name of the external feed. | -| packageDownloadExternal | The package name you wish to download. | -| versionDownloadExternal | The version of the package you wish to download. | +### [Classic](#tab/classic/) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. -#### [Classic](#tab/classic/) +1. Select **Pipelines**, and then select your pipeline definition. -To download a Universal Package, add the **Universal Package** task to your pipeline and fill out the required fields as follows: +1. Select **Edit**, and then select the `+` sign to add a new task. Add the **Universal Packages** task and configure it as follows: + + :::image type="content" source="media/universal-packages/download.png" alt-text="A screenshot displaying how to download a Universal Package with a Classic pipeline."::: - **Command:** Download - **Destination directory**: Folder path where the packages will be downloaded. Default value: `$(System.DefaultWorkingDirectory)`. @@ -173,15 +176,16 @@ To download a Universal Package, add the **Universal Package** task to your pipe - **Package name:** Name of the package to be downloaded. - **Version:** The version of the package that you want to download. -:::image type="content" source="media/universal-packages/download.png" alt-text="A screenshot showing how to download a Universal Package with classic pipeline."::: - --- > [!TIP] -> You can use wildcards to download the latest version of a Universal Package. See [Download the latest version](../../artifacts/quickstarts/universal-packages.md#download-the-latest-version) for more details. +> Wildcards can be used to download the latest version of a Universal Package. See [Download the latest version](../../artifacts/quickstarts/download-universal-packages.md#download-the-latest-version) for more details. -## Related articles +## Related content - [Universal Packages upstream sources](../../artifacts/universal-packages/universal-packages-upstream.md) -- [Search for packages in upstream sources](../../artifacts/how-to/search-upstream.md) -- [Feed permissions](../../artifacts/feeds/feed-permissions.md) \ No newline at end of file + +- [Feed permissions](../../artifacts/feeds/feed-permissions.md) + +- [Use the .artifactignore file](../../artifacts/reference/artifactignore.md) + diff --git a/docs/pipelines/build/build-tag.md b/docs/pipelines/build/build-tag.md new file mode 100644 index 00000000000..bd796ef06d6 --- /dev/null +++ b/docs/pipelines/build/build-tag.md @@ -0,0 +1,130 @@ +--- +title: Use build tags +description: Learn how to add, remove, and use build tags. +ms.topic: how-to +ms.date: 06/18/2023 +ms.custom: template-how-to-pattern +ai-usage: ai-assisted +ms.author: jukullam +author: juliakm +monikerRange: '>= azure-devops-2020' +--- + +# How to add, remove, and use build tags + +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] + +Build tags in Azure DevOps let you categorize and organize your builds. Tags make it easier to filter and search for specific builds. In this article, learn how to add, remove, and use build tags in Azure DevOps. + +## Prerequisites + +An Azure DevOps organization and access to a project where you are a member of the **Contributors** group. + +## Add a build tag to a completed build + +#### [Azure Pipelines UI](#tab/azure-pipelines-ui) + +To add a tag to a completed build: + +1. Open your Azure DevOps project and go to **Pipelines**. +1. Select the pipeline where you want to add a tag. + + :::image type="content" source="media/tags/select-pipeline.png" alt-text="Screenshot of selecting the pipeline to add a tag. "::: + +1. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and choose **Add tags** to add your first tag or **Edit tags** if you have an existing tag. + + :::image type="content" source="media/tags/add-tag-more-actions.png" alt-text="Screenshot of select option to add tag."::: + +1. Enter a tag name (example: contoso). + + :::image type="content" source="media/tags/add-tag-name.png" alt-text="Screenshot of adding a new build tag."::: + +1. Press **Enter** to save the tags. + +#### [Azure DevOps CLI](#tab/azure-devops-cli) + +To create a build tag, use the [az pipelines build tag add](/cli/azure/pipelines/build/tag#az-pipelines-build-tag-add) command. + +For example, the following command creates a build tag named `prod` in the `contoso` organization and `webapp` project for the build `1234`. + +```azurecli +az pipelines build tag add --build-id 1234 + --tags prod + --org https://dev.azure.com/Contoso/ + --project contoso +``` +Output: + +```json +[ + "prod" +] +``` + +--- + + +## Remove a build tag + +#### [Azure Pipelines UI](#tab/azure-pipelines-ui) + +To remove build tags from your builds in Azure DevOps, follow these steps: + +1. Open your Azure DevOps project and go to **Pipelines**. +1. Select the pipeline where you want to remove a tag. +1. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and choose **Edit tags**. +1. Select the **X** next to the tag name to remove your tag. + + :::image type="content" source="media/tags/remove-build-tag.png" alt-text="Screenshot of removing build tag."::: + +1. Press **Save** to save the changes. + +#### [Azure DevOps CLI](#tab/azure-devops-cli) + +To remove a build tag, use the [az pipelines build tag delete](/cli/azure/pipelines/build/tag#az-pipelines-build-tag-delete) command. + +For example, the following command removes a build tag named `prod` in the `contoso` organization and `webapp` project for the build `1234`. + +```azurecli +az pipelines build tag delete --build-id 1234 + --tag prod + --org https://dev.azure.com/Contoso/ + --project contoso +``` + +Output: + +```json +[ +] +``` + +--- + +## Add a build tag to a future build + +To add a build tag to a build in a YAML pipeline, use the [`addbuildtag` logging command](../scripts/logging-commands.md#addbuildtag-add-a-tag-to-the-build). + +In the following example a new tag gets added in a script task with a variable that includes the current date. + +```yaml +steps: +- script: | + last_scanned="last_scanned-$(date +%Y%m%d)" + echo "##vso[build.addbuildtag]$last_scanned" + displayName: 'Apply last scanned tag' +``` +--- + +## Filter with a build tag + +Once you have added build tags to your builds, you can use them to filter and search for specific builds. To use build tags in Azure DevOps, follow these steps: + +1. Open your Azure DevOps project and go to **Pipelines**. +1. Select **Runs** tab. +1. In the filter bar, select the tag that you want to filter by. + + :::image type="content" source="media/tags/filter-tag.png" alt-text="Screenshot of selecting tag to filter by."::: + +1. Azure DevOps will filter the builds based on the specified tag, allowing you to find the runs you need. + diff --git a/docs/pipelines/build/history.md b/docs/pipelines/build/history.md deleted file mode 100644 index 743605d726a..00000000000 --- a/docs/pipelines/build/history.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Build pipeline history -ms.custom: seodec18 -description: Learn about how you can determine what changed, when it happened, and who did it on Azure Pipelines and Team Foundation Server (TFS). -ms.topic: reference -ms.assetid: AB81E23E-DD84-4BDB-ACD9-AE03D783A303 -ms.date: 3/15/2018 -monikerRange: '<= azure-devops' ---- - -# Build pipeline history - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - -From the **History** tab you can see a list of changes that includes who made the change and when the change occurred. - -To work with a change, select it, click **...**, and then click **Compare Difference** or **Revert Pipeline**. - - -## FAQ - - - -### Can I edit the JSON source directly? - -No - -[!INCLUDE [temp](../includes/qa-agents.md)] - -::: moniker range="< azure-devops" -[!INCLUDE [temp](../includes/qa-versions.md)] -::: moniker-end - - diff --git a/docs/pipelines/build/includes/variables-build-sources-directory.md b/docs/pipelines/build/includes/variables-build-sources-directory.md index 4b4a1baabe6..b3de1275568 100644 --- a/docs/pipelines/build/includes/variables-build-sources-directory.md +++ b/docs/pipelines/build/includes/variables-build-sources-directory.md @@ -4,9 +4,8 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 02/13/2020 +ms.date: 01/22/2025 --- -The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the [Repository tab](../../repos/index.md). -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. \ No newline at end of file +The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s` For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      On self-hosted agents, new build pipelines update only the changed files by default. You can modify how files are downloaded on the [Repository tab](../../repos/index.md).

      +This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. \ No newline at end of file diff --git a/docs/pipelines/build/includes/variables-hosted.md b/docs/pipelines/build/includes/variables-hosted.md index a6e9a7e9522..8ed80c04b7b 100644 --- a/docs/pipelines/build/includes/variables-hosted.md +++ b/docs/pipelines/build/includes/variables-hosted.md @@ -4,7 +4,7 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 02/13/2020 +ms.date: 04/08/2025 --- @@ -12,24 +12,27 @@ ms.date: 02/13/2020 > [!NOTE] > You can use agent variables as environment variables in your scripts and as parameters in your build tasks. -> You cannot use them to customize the build number or to apply a version control label or tag. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Agent.BuildDirectory -

      The local path on the agent where all folders for a given build pipeline are created. This variable has the same value as Pipeline.Workspace.

      -

      For example: /home/vsts/work/1

      -
      Agent.ContainerMapping -

      A mapping from container resource names in YAML to their Docker IDs at runtime.

      -

      For example: 

      +> You can't use them to customize the build number or to apply a version control label or tag.
+
+| Variable | Description |
+|:---------|:------------|
+| Agent.BuildDirectory | The local path on the agent where all folders for a given build pipeline are created. This variable has the same value as `Pipeline.Workspace`. For example: `/home/vsts/work/1`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure). |
+| Agent.ContainerMapping | A mapping from container resource names in YAML to their Docker IDs at runtime.

      Example follows table. |
+| Agent.HomeDirectory | The directory the agent is installed into. This variable contains the agent software. For example: `c:\agent`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).|
+| Agent.Id | The ID of the agent. |
+| Agent.JobName | The name of the running job. This name is usually `Job`; or `__default`, but in multi-config scenarios, it's the configuration. |
+| Agent.JobStatus | The status of the build.
      • `Canceled`
      • `Failed`
      • `Succeeded`
      • `SucceededWithIssues` (partially successful)
      • `Skipped` (last job) 
      The environment variable should be referenced as `AGENT_JOBSTATUS`. The older `agent.jobstatus` is available for backwards compatibility. |
+| Agent.MachineName | The name of the machine on which the agent is installed. |
+| Agent.Name | The name of the agent that is registered with the pool.

      If you're using a self-hosted agent, you specify the name. See [agents](../../agents/agents.md). |
+| Agent.OS | The operating system of the agent host. Valid values are:
      • `Windows_NT`
      • `Darwin`
      • `Linux`
      If you're running in a container, the agent host and container can  run different operating systems. |
+| Agent.OSArchitecture | The operating system processor architecture of the agent host. Valid values are:
      • `X86`
      • `X64`
      • `ARM`
       |
+| Agent.TempDirectory | A temporary folder that is cleaned after each pipeline job. This directory is used by tasks such as [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) to hold temporary items like test results before they're published.

      For example: `/home/vsts/work/_temp` for Ubuntu. |
+| Agent.ToolsDirectory | The directory used by tasks such as [Node Tool Installer](/azure/devops/pipelines/tasks/reference/node-tool-v0) and [Use Python Version](/azure/devops/pipelines/tasks/reference/use-python-version-v0) to switch between multiple versions of a tool.

      These tasks add tools from this directory to `PATH` so that subsequent build steps can use them.

      Learn about [managing this directory on a self-hosted agent](https://go.microsoft.com/fwlink/?linkid=2008884). |
+| Agent.WorkFolder | The working directory for this agent.

      For example: `c:\agent_work`.

      Note: This directory isn't guaranteed to be writable by pipeline tasks (for example, when mapped into a container). For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure). |
+
+Example of **Agent.ContainerMapping**:
+
+```yaml
 {
   "one_container": {
     "id": "bdbb357d73a0bd3550a1a5b778b62a4c88ed2051c7802a0659f1ff6e76910190"
@@ -38,790 +41,121 @@ ms.date: 02/13/2020
     "id": "82652975109ec494876a8ccbb875459c945982952e0a72ad74c91216707162bb"
   }
 }
-
      -

      -
      Agent.HomeDirectoryThe directory the agent is installed into. This contains the agent software. For example: c:\agent.
      Agent.IdThe ID of the agent.
      Agent.JobNameThe name of the running job. This will usually be "Job" or "__default", but in multi-config scenarios, will be the configuration.
      Agent.JobStatusThe status of the build. -
        -
      • Canceled -
      • Failed -
      • Succeeded -
      • SucceededWithIssues (partially successful) -
      -

      The environment variable should be referenced as AGENT_JOBSTATUS. The older agent.jobstatus is available for backwards compatibility.

      -
      Agent.MachineNameThe name of the machine on which the agent is installed.
      Agent.Name -

      The name of the agent that is registered with the pool.

      -

      If you're using a self-hosted agent, then this name is specified by you. See agents.

      -
      Agent.OS -The operating system of the agent host. Valid values are: -
        -
      • Windows_NT -
      • Darwin -
      • Linux -
      -If you're running in a container, the agent host and container may be running different operating systems. -
      Agent.OSArchitecture -The operating system processor architecture of the agent host. Valid values are: -
        -
      • X86 -
      • X64 -
      • ARM -
      -
      Agent.TempDirectory -

      A temporary folder that is cleaned after each pipeline job. This directory is used by tasks such as .NET Core CLI task to hold temporary items like test results before they're published.

      -

      For example: /home/vsts/work/_temp for Ubuntu

      -
      Agent.ToolsDirectory -The directory used by tasks such as Node Tool Installer and Use Python Version to switch between multiple versions of a tool. -These tasks add tools from this directory to PATH so that subsequent build steps can use them. -

      -Learn about managing this directory on a self-hosted agent. -
      Agent.WorkFolder -The working directory for this agent. -For example: c:\agent_work. -

      -Note: This directory isn't guaranteed to be writable by pipeline tasks (for example, when mapped into a container) -
      +``` ## Build variables (DevOps Services) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescriptionAvailable in templates?
      Build.ArtifactStagingDirectory - - -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent_work\1\a -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. -

      -Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself. -

      -See Artifacts in Azure Pipelines. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -      		No
      Build.BuildIdThe ID of the record for the completed build.No
      Build.BuildNumberThe name of the completed build, also known as the run number. You can specify what is included in this value.

      -A typical use of this variable is to make it part of the label format, which you specify on the repository tab. -

      - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.BuildUriThe URI for the build. For example: vstfs:///Build/Build/1430. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.BinariesDirectoryThe local path on the agent you can use as an output folder for compiled binaries. -

      -By default, new build pipelines aren't set up to clean this directory. You can define your build to clean it up on the Repository tab. -

      -For example: c:\agent_work\1\b. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.ContainerIdThe ID of the container for your artifact. When you upload an artifact in your pipeline, it's added to a container that is specific for that particular artifact.No
      Build.DefinitionNameThe name of the build pipeline. -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -      		Yes
      Build.DefinitionVersionThe version of the build pipeline.Yes
      Build.QueuedBySee "How are the identity variables set?". -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -      		Yes
      Build.QueuedByIdSee "How are the identity variables set?".Yes
      Build.ReasonThe event that caused the build to run. -
        -
      • Manual: A user manually queued the build.
        • -
      • IndividualCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in.
        • -
      • BatchedCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in, and the Batch changes was selected.
        • -
      • Schedule: Scheduled trigger.
        • -
      • ValidateShelveset: A user manually queued the build of a specific TFVC shelveset.
        • -
      • CheckInShelveset: Gated check-in trigger.
        • -
      • PullRequest: The build was triggered by a Git branch policy that requires a build.
        • -
      • BuildCompletion: The build was triggered by another build
        • -
      • ResourceTrigger: The build was triggered by a resource trigger or it was triggered by another build.
        • -
      -See Build pipeline triggers, Improve code quality with branch policies. -      		Yes
      Build.Repository.CleanThe value you've selected for Clean in the source repository settings. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      Build.Repository.LocalPath - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. - -Important note: If you check out only one Git repository, this path is the exact path to the code. -If you check out multiple repositories, the behavior is as follows (and might differ from the value of the Build.SourcesDirectory variable): -
        -
      • If the checkout step for the self (primary) repository has no custom checkout path defined, or the checkout path is the multi-checkout default path $(Pipeline.Workspace)/s/<RepoName> for the self repository, the value of this variable reverts to its default value, which is $(Pipeline.Workspace)/s.
        • -
      • If the checkout step for the self (primary) repository does have a custom checkout path defined (and it's not its multi-checkout default path), this variable contains the exact path to the self repository.
        • -
      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.Repository.IDThe unique identifier of the repository. -

      -This won't change, even if the name of the repository does. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      Build.Repository.NameThe name of the triggering repository. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      Build.Repository.ProviderThe type of the triggering repository. - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -No
      Build.Repository.Tfvc.WorkspaceDefined if your repository is Team Foundation Version Control. The name of the TFVC workspace used by the build agent. -


      For example, if the Agent.BuildDirectory is c:\agent_work\12 and the Agent.Id is 8, the workspace name could be: ws_12_8 -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.Repository.UriThe URL for the triggering repository. For example: - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -No
      Build.RequestedForSee "How are the identity variables set?". -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -      		Yes
      Build.RequestedForEmailSee "How are the identity variables set?".Yes
      Build.RequestedForIdSee "How are the identity variables set?".Yes
      Build.SourceBranchThe branch of the triggering repo the build was queued for. Some examples: -
        -
      • Git repo branch: refs/heads/main
        • -
      • Git repo pull request: refs/pull/1/merge
        • -
      • TFVC repo branch: $/teamproject/main
        • -
      • TFVC repo gated check-in: Gated_2016-06-06_05.20.51.4369;username@live.com
        • -
      • TFVC repo shelveset build: myshelveset;username@live.com
        • -
      • When your pipeline is triggered by a tag: refs/tags/your-tag-name
        • -
      -When you use this variable in your build number format, the forward slash characters (/) are replaced with underscore characters _). -

      -Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. -      		Yes
      Build.SourceBranchNameThe name of the branch in the triggering repo the build was queued for. -
        -
      • Git repo branch, pull request, or tag: The last path segment in the ref. For example, in refs/heads/main this value is main. In refs/heads/feature/tools this value is tools. In refs/tags/your-tag-name this value is your-tag-name.
        • -
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example, in $/teamproject/main this value is main.
        • -
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, Gated_2016-06-06_05.20.51.4369;username@live.com or myshelveset;username@live.com.
        • -
      -Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. -      		Yes
      Build.SourcesDirectory - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. - -Important note: If you check out only one Git repository, this path is the exact path to the code. If you check out multiple repositories, it reverts to its default value, which is $(Pipeline.Workspace)/s, even if the self (primary) repository is checked out to a custom path different from its multi-checkout default path $(Pipeline.Workspace)/s/<RepoName> (in this respect, the variable differs from the behavior of the Build.Repository.LocalPath variable). -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.SourceVersionThe latest version control change of the triggering repo that is included in this build. - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -Yes
      Build.SourceVersionMessageThe comment of the commit or changeset for the triggering repo. We truncate the message to the first line or 200 characters, whichever is shorter. - -The `Build.SourceVersionMessage` corresponds to the message on `Build.SourceVersion` commit. The `Build.SourceVersion` commit for a PR build is the merge commit (not the commit on the source branch). - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -Also, this variable is only available on the step level and is not available in the job or stage levels (that is, the message isn't extracted until the job starts and the code is checked out). - -Note: This variable is available in TFS 2015.4. - -> [!NOTE] -> The **Build.SourceVersionMessage** variable does not work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. -No
      Build.StagingDirectory - - -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent_work\1\a -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. -

      -Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself. -

      -See Artifacts in Azure Pipelines. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -      		No
      Build.Repository.Git.SubmoduleCheckoutThe value you've selected for Checkout submodules on the repository tab. With multiple repos checked out, this value tracks the triggering repository's setting. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      Build.SourceTfvcShelvesetDefined if your repository is Team Foundation Version Control. -


      If you're running a gated build or a shelveset build, this is set to the name of the shelveset you're building. -

      -Note: This variable yields a value that is invalid for build use in a build number format. -      		No
      Build.TriggeredBy.BuildIdIf the build was triggered by another build, then this variable is set to the BuildID of the triggering build. In Classic pipelines, this variable is triggered by a build completion trigger. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -

      -If you're triggering a YAML pipeline using resources, you should use the resources variables instead. -      		No
      Build.TriggeredBy.DefinitionIdIf the build was triggered by another build, then this variable is set to the DefinitionID of the triggering build. In Classic pipelines, this variable is triggered by a build completion trigger. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -

      -If you're triggering a YAML pipeline using resources, you should use the resources variables instead. -      		No
      Build.TriggeredBy.DefinitionNameIf the build was triggered by another build, then this variable is set to the name of the triggering build pipeline. In Classic pipelines, this variable is triggered by a build completion trigger. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -

      -If you're triggering a YAML pipeline using resources, you should use the resources variables instead. -      		No
      Build.TriggeredBy.BuildNumberIf the build was triggered by another build, then this variable is set to the number of the triggering build. In Classic pipelines, this variable is triggered by a build completion trigger. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -

      -If you're triggering a YAML pipeline using resources, you should use the resources variables instead. -      		No
      Build.TriggeredBy.ProjectIDIf the build was triggered by another build, then this variable is set to ID of the project that contains the triggering build. In Classic pipelines, this variable is triggered by a build completion trigger. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -

      -If you're triggering a YAML pipeline using resources, you should use the resources variables instead. -      		No
      Common.TestResultsDirectoryThe local path on the agent where the test results are created. For example: c:\agent_work\1\TestResults -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      - -## Pipeline variables (DevOps Services) - - - - - - - - - - - -
      VariableDescription
      Pipeline.WorkspaceWorkspace directory for a particular pipeline. This variable has the same value as Agent.BuildDirectory.

      -For example, /home/vsts/work/1.
      +When you use a variable in a template that isn't marked as available in templates, the variable doesn't render. The variable doesn't render because its value isn't accessible within the template's scope. + +| Variable | Description | Available in [templates](../../process/templates.md)? | +|:---------|:------------|:------------------------------------------------------| +| Build.ArtifactStagingDirectory | The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: `c:\agent_work\1\a`.

      A typical way to use this folder is to publish your build artifacts with the [Copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish build artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks.

      Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

      See [Artifacts in Azure Pipelines](../../artifacts/artifacts-overview.md). For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.BuildId | The ID of the record for the completed build. | No | +| Build.BuildNumber | The name of the completed build, also known as the run number. You can specify [what is included](../../process/run-number.md) in this value.

      A typical use of this variable is to make it part of the label format, which you specify on the [repository tab](../../repos/index.md).

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.BuildUri | The URI for the build. For example: `vstfs:///Build/Build/1430`.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.BinariesDirectory | The local path on the agent you can use as an output folder for compiled binaries.

      On self-hosted agents, new build pipelines aren't set up to clean this directory by default. You can define your build to clean it up on the [Repository tab](../../repos/index.md).

      For example: `c:\agent_work\1\b`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.ContainerId | The ID of the container for your artifact. When you upload an artifact in your pipeline, it's added to a container that is specific for that particular artifact. | No | +| Build.CronSchedule.DisplayName | The `displayName` of the cron schedule that triggered the pipeline run. This variable is only set if a YAML scheduled trigger triggers the pipeline run. For more information, see [schedules.cron definition - Build.CronSchedule.DisplayName variable](/azure/devops/pipelines/yaml-schema/schedules-cron#buildcronscheduledisplayname-variable) | Yes | +| Build.DefinitionName | The name of the build pipeline.

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | Yes | +| Build.DefinitionVersion | The version of the build pipeline. | Yes | +| Build.QueuedBy | See [How are the identity variables set?](#identity_values).

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | Yes | +| Build.QueuedById | See [How are the identity variables set?](#identity_values). | Yes | +| Build.Reason | The event that caused the build to run.
      • `Manual`: A user manually queued the build.
      • `IndividualCI`: **Continuous integration (CI)** triggered by a Git push or a Team Foundation Version Control (TFVC) check-in.
      • `BatchedCI`: **Continuous integration (CI)** triggered by a Git push or a TFVC check-in, and the **Batch changes** was selected.
      • `Schedule`: **Scheduled** trigger.
      • `ValidateShelveset`: A user manually queued the build of a specific TFVC shelveset.
      • `CheckInShelveset`: **Gated check-in** trigger.
      • `PullRequest`: A Git branch policy that requires a build triggers the build.
      • `BuildCompletion`: [Another build triggers](../../process/pipeline-triggers.md) the build.
      • `ResourceTrigger`: [A resource trigger](../../process/resources.md) or [another build triggers](../../process/pipeline-triggers.md) the build.
      See [Build pipeline triggers](../triggers.md), [Improve code quality with branch policies](../../../repos/git/branch-policies.md). | Yes | +| Build.Repository.Clean | The value you selected for **Clean** in the [source repository settings](../../repos/index.md).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.LocalPath | The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`.

      On self-hosted agents, new build pipelines update only the changed files by default. You can modify how files are downloaded on the [Repository tab](../../repos/index.md).

      Important note: If you check out only one Git repository, this path is the exact path to the code.

      If you check out multiple repositories, the behavior is as follows (and might differ from the value of the Build.SourcesDirectory variable):
      • If the checkout step for the self (primary) repository has no custom checkout path defined, or the checkout path is the multi-checkout default path `$(Pipeline.Workspace)/s/&` for the self repository, the value of this variable reverts to its default value, which is `$(Pipeline.Workspace)/s`.
      • If the checkout step for the self (primary) repository had a custom checkout path defined that is not its multi-checkout default path, this variable contains the exact path to the self repository.
      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.ID | The unique identifier of the [repository](../../repos/index.md).

      This value doesn't change, even if the name of the repository does. | Yes | +| Build.Repository.Name | The name of the triggering [repository](../../repos/index.md). | Yes | +| Build.Repository.Provider | The type of the triggering [repository](../../repos/index.md).
      • `TfsGit`: [TFS Git repository](../../../repos/git/index.yml)
      • `TfsVersionControl`: [Team Foundation Version Control](../../../repos/tfvc/what-is-tfvc.md)
      • `Git`: Git repository hosted on an external server
      • `GitHub`
      • `Svn`: Subversion
      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.Tfvc.Workspace | Defined if your [repository](../../repos/index.md) is Team Foundation Version Control. The name of the [TFVC workspace](../../../repos/tfvc/create-work-workspaces.md) used by the build agent.

      For example, if the Agent.BuildDirectory is `c:\agent_work\12` and the Agent.Id is `8`, the workspace name could be: `ws_12_8`

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.Uri | The URL for the triggering repository. For example:
      • Git: [https://fabrikamfiber@dev.azure.com/fabrikamfiber/_git/Scripts](https://fabrikamfiber@dev.azure.com/fabrikamfiber/_git/Scripts)
      • TFVC: [https://dev.azure.com/fabrikamfiber/](https://dev.azure.com/fabrikamfiber/)
      This variable can't be used as part of the build number or as a version control tag. | Yes | +| Build.RequestedFor | See [How are the identity variables set?](#identity_values).

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | Yes | +| Build.RequestedForEmail | See [How are the identity variables set?](#identity_values). | Yes | +| Build.RequestedForId | See [How are the identity variables set?](#identity_values). | Yes | +| Build.SourceBranch | The branch of the triggering repo the build was queued for. Some examples:
      • Git repo branch: `refs/heads/main`
      • Git repo pull request: `refs/pull/1/merge`
      • TFVC repo branch: `$/teamproject/main`
      • TFVC repo gated check-in: `Gated_2016-06-06_05.20.51.4369;username@live.com`
      • TFVC repo shelveset build: `myshelveset;username@live.com`
      • When a tag triggers your pipeline: `refs/tags/your-tag-name`
      When you use this variable in your build number format, the forward slash characters (`/`) are replaced with underscore characters (`_`).

      Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. | Yes | +| Build.SourceBranchName | The name of the branch in the triggering repo the build was queued for.
      • Git repo branch, pull request, or tag: The last path segment in the ref. For example, in `refs/heads/main` this value is `main`. In `refs/heads/feature/tools`, this value is `tools`. In `refs/tags/your-tag-name`, the value is `your_tag_name`, with hyphens (`-`) replaced by underscores (`_`).
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example, in `$/teamproject/main` this value is `main`.
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, `Gated_2016-06-06_05.20.51.4369;username@live.com` or `myshelveset;username@live.com`.
      Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. | Yes | +| Build.SourcesDirectory | The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`.

      On self-hosted agents, new build pipelines update only the changed files. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      Important note: If you check out only one Git repository, this path is the exact path to the code. If you check out multiple repositories, it reverts to its default value, which is `$(Pipeline.Workspace)/s`, even if the self (primary) repository is checked out to a custom path different from its multi-checkout default path `$(Pipeline.Workspace)/s/` (in this respect, the variable differs from the behavior of the Build.Repository.LocalPath variable).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.SourceVersion | The latest version control change of the triggering repo that is included in this build.
      • Git: The [commit](../../../repos/git/commits.md) ID.
      • TFVC: the [changeset](../../../repos/tfvc/find-view-changesets.md).
      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | Yes | +| Build.SourceVersionMessage | The comment of the commit or changeset for the triggering repo. We truncate the message to the first line or 200 characters, whichever is shorter.

      The `Build.SourceVersionMessage` corresponds to the message on `Build.SourceVersion` commit. The `Build.SourceVersion` commit for a PR build is the merge commit (not the commit on the source branch).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      Also, this variable is only available on the step level and isn't available in the job or stage levels. That is, the message isn't extracted until the job starts and the code is checked out.

      Note: The **Build.SourceVersionMessage** variable doesn't work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. | No | +| Build.StageRequestedBy | The person who triggered the stage when the stage runs manually, or `Microsoft.VisualStudio.Services.TFS` otherwise.

      Note: This value can contain whitespace or other invalid label characters. | No | +| Build.StageRequestedForId | The GUID of identity of the person who triggered the stage when the stage runs manually, or `00000002-0000-8888-8000-000000000000` otherwise. | No | +| Build.StagingDirectory | The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: `c:\agent_work\1\a`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      A typical way to use this folder is to publish your build artifacts with the [Copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish build artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks.

      Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

      See [Artifacts in Azure Pipelines](../../artifacts/artifacts-overview.md).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.Git.SubmoduleCheckout | The value you selected for **Checkout submodules** on the [repository tab](../../repos/index.md). With multiple repos checked out, this value tracks the triggering repository's setting.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.SourceTfvcShelveset | Defined if your [repository](../../repos/index.md) is Team Foundation Version Control.

      If you're running a [gated build](../../repos/tfvc.md#gated) or a [shelveset build](../../create-first-pipeline.md#queueabuild), this variable is set to the name of the [shelveset](../../../repos/tfvc/suspend-your-work-manage-your-shelvesets.md) you're building.

      Note: This variable yields a value that is invalid for build use in a build number format. | No | +| Build.TriggeredBy.BuildId | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the BuildID of the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      If you're triggering a YAML pipeline using `resources`, you should use the [resources variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#the-pipeline-resource-metadata-as-predefined-variables) instead. | No | +| Build.TriggeredBy.DefinitionId | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the DefinitionID of the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      If you're triggering a YAML pipeline using `resources`, you should use the [resources variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#the-pipeline-resource-metadata-as-predefined-variables) instead. | No | +| Build.TriggeredBy.DefinitionName | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the name of the triggering build pipeline. In Classic pipelines, a build completion trigger triggers this variable.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      If you're triggering a YAML pipeline using `resources`, you should use the [resources variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#the-pipeline-resource-metadata-as-predefined-variables) instead. | No | +| Build.TriggeredBy.BuildNumber | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the number of the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      If you're triggering a YAML pipeline using `resources`, you should use the [resources variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#the-pipeline-resource-metadata-as-predefined-variables) instead. | No | +| Build.TriggeredBy.ProjectID | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to ID of the project that contains the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      If you're triggering a YAML pipeline using `resources`, you should use the [resources variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#the-pipeline-resource-metadata-as-predefined-variables) instead. | No | +| Common.TestResultsDirectory | The local path on the agent where the test results are created. For example: `c:\agent_work\1\TestResults`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | + +## Pipeline variables + + +| Variable | Description | +|:---------|:------------| +| Pipeline.Workspace | Workspace directory for a particular pipeline. This variable has the same value as `Agent.BuildDirectory`. For example, `/home/vsts/work/1`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).| > [!TIP] -> If you are using classic release pipelines, you can use [classic releases and artifacts variables](../../release/variables.md) to store and access data throughout your pipeline. - -## Deployment job variables (DevOps Services) - - - -These variables are scoped to a specific [Deployment job](../../process/deployment-jobs.md) and will be resolved only at job execution time. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Environment.NameName of the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, smarthotel-dev.
      Environment.IdID of the environment targeted in the deployment job. For example, 10.
      Environment.ResourceNameName of the specific resource within the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, bookings which is a Kubernetes namespace that has been added as a resource to the environment smarthotel-dev.
      Environment.ResourceIdID of the specific resource within the environment targeted in the deployment job to run the deployment steps. For example, 4.
      Strategy.NameThe name of the deployment strategy: canary, runOnce, or rolling.
      Strategy.CycleNameThe current cycle name in a deployment. Options are PreIteration, Iteration, or PostIteration.
      - - -## System variables (DevOps Services) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescriptionAvailable in templates?
      System.AccessTokenUse the OAuth token to access the REST API. -

      -Use System.AccessToken from YAML scripts. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		Yes
      System.CollectionIdThe GUID of the TFS collection or Azure DevOps organization.Yes
      System.CollectionUriThe URI of the TFS collection or Azure DevOps organization. For example: https://dev.azure.com/fabrikamfiber/.Yes
      System.DefaultWorkingDirectory - -[!INCLUDE [include](../includes/variables-build-sources-directory.md)] - -Yes
      System.DefinitionIdThe ID of the build pipeline.Yes
      System.HostTypeSet to build if the pipeline is a build. For a release, the values are deployment for a Deployment group job, gates during evaluation of gates, and release for other (Agent and Agentless) jobs.Yes
      System.JobAttemptSet to 1 the first time this job is attempted, and increments every time the job is retried.No
      System.JobDisplayNameThe human-readable name given to a job.No
      System.JobIdA unique identifier for a single attempt of a single job. The value is unique to the current pipeline.No
      System.JobNameThe name of the job, typically used for expressing dependencies and accessing output variables.No
      System.PhaseAttemptSet to 1 the first time this phase is attempted, and increments every time the job is retried.
      -
      -Note: "Phase" is a mostly redundant concept, which represents the design-time for a job (whereas job was the runtime version of a phase). We've mostly removed the concept of "phase" from Azure Pipelines. Matrix and multi-config jobs are the only place where "phase" is still distinct from "job." One phase can instantiate multiple jobs, which differ only in their inputs.      		No
      System.PhaseDisplayNameThe human-readable name given to a phase.No
      System.PhaseNameA string-based identifier for a job, typically used for expressing dependencies and accessing output variables.No
      System.PlanIdA string-based identifier for a single pipeline run.No
      System.PullRequest.IsForkIf the pull request is from a fork of the repository, this variable is set to True. -Otherwise, it's set to False.Yes
      System.PullRequest.PullRequestIdThe ID of the pull request that caused this build. For example: 17. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy).No
      System.PullRequest.PullRequestNumberThe number of the pull request that caused this build. This variable is populated for pull requests from GitHub that have a different pull request ID and pull request number. This variable is only available in a YAML pipeline if the PR is affected by a branch policy.No
      System.PullRequest.targetBranchNameThe name of the target branch for a pull request. This variable can be used in a pipelines to conditionally execute tasks or steps based on the target branch of the pull request. For example, you might want to trigger a different set of tests or code analysis tools depending on the branch that the changes are being merged into. -No
      System.PullRequest.SourceBranchThe branch that is being reviewed in a pull request. For example: refs/heads/users/raisa/new-feature for Azure Repos. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy). This variable is only available in a YAML pipeline if the PR is affected by a branch policy.No
      System.PullRequest.SourceRepositoryURIThe URL to the repo that contains the pull request. For example: https://dev.azure.com/ouraccount/_git/OurProject. No
      System.PullRequest.TargetBranchThe branch that is the target of a pull request. For example: refs/heads/main when your repository is in Azure Repos and main when your repository is in GitHub. This variable is initialized only if the build ran because of a Git PR affected by a branch policy. This variable is only available in a YAML pipeline if the PR is affected by a branch policy.No
      System.StageAttemptSet to 1 the first time this stage is attempted, and increments every time the job is retried.No
      System.StageDisplayNameThe human-readable name given to a stage.No
      System.StageNameA string-based identifier for a stage, typically used for expressing dependencies and accessing output variables.No
      System.TeamFoundationCollectionUriThe URI of the TFS collection or Azure DevOps organization. For example: https://dev.azure.com/fabrikamfiber/. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		Yes
      System.TeamProjectThe name of the project that contains this build.Yes
      System.TeamProjectIdThe ID of the project that this build belongs to.Yes
      System.TimelineIdA string-based identifier for the execution details and logs of a single pipeline run.No
      TF_BUILDSet to True if the script is being run by a build task. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      +> If you're using classic release pipelines, you can use [classic releases and artifacts variables](../../release/variables.md) to store and access data throughout your pipeline. + +## Deployment job variables + + +These variables are scoped to a specific [Deployment job](../../process/deployment-jobs.md) and is resolved only at job execution time. + +| Variable | Description | +|:---------|:------------| +| Environment.Name | Name of the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, `smarthotel-dev`. | +| Environment.Id | ID of the environment targeted in the deployment job. For example, `10`. | +| Environment.ResourceName | Name of the specific resource within the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, `bookings` which is a Kubernetes namespace that is added as a resource to the environment `smarthotel-dev`. | +| Environment.ResourceId | ID of the specific resource within the environment targeted in the deployment job to run the deployment steps. For example, `4`. | +| Strategy.Name | The name of the deployment strategy: `canary`, `runOnce`, or `rolling`. | +| Strategy.CycleName | The current cycle name in a deployment. Options are `PreIteration`, `Iteration`, or `PostIteration`. | + +## System variables + +When you use a variable in a template that isn't marked as available in templates, the variable doesn't render. The variable doesn't render because its value isn't accessible within the template's scope. + +| Variable | Description | Available in [templates](../../process/templates.md)? | +|:---------|:------------|:------------------------------------------------------| +| System.AccessToken | [Use the OAuth token to access the REST API](../../scripts/powershell.md#example-powershell-script-access-rest-api).

      [Use System.AccessToken from YAML scripts](../variables.md#systemaccesstoken).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | Yes | +| System.CollectionId | The GUID of the Azure DevOps organization or collection. | Yes | +| System.CollectionUri | The URI of the Azure DevOps organization or collection. For example: `https://dev.azure.com/fabrikamfiber/`. | Yes | +| System.DefaultWorkingDirectory | [!INCLUDE [include](../includes/variables-build-sources-directory.md)] | Yes | +| System.DefinitionId | The ID of the build pipeline. | Yes | +| System.HostType | Set to `build` if the pipeline is a build. For a release, the values are `deployment` for a Deployment group job, `gates` during evaluation of gates, and `release` for other (Agent and Agentless) jobs. | Yes | +| System.JobAttempt | Set to 1 the first time this job is attempted, and increments every time the job is retried. | No | +| System.JobDisplayName | The human-readable name given to a job. | No | +| System.JobId | A unique identifier for a single attempt of a single job. The value is unique to the current pipeline. | No | +| System.JobName | The name of the job, typically used for expressing dependencies and accessing output variables. | No | +| System.OidcRequestUri | Generate an `idToken` for authentication with Entra ID using OpenID Connect (OIDC). [Learn more](/azure/devops/release-notes/2024/sprint-240-update#pipelines-and-tasks-populate-variables-to-customize-workload-identity-federation-authentication). | Yes | +| System.PhaseAttempt | Set to 1 the first time this phase is attempted, and increments every time the job is retried.

      Note: "Phase" is a mostly redundant concept, which represents the design-time for a job (whereas job was the runtime version of a phase). The concept of *phase* is mostly removed from Azure Pipelines. Matrix and multi-config jobs are the only place where a phase is still distinct from a job. One phase can instantiate multiple jobs, which differ only in their inputs. | No | +| System.PhaseDisplayName | The human-readable name given to a phase. | No | +| System.PhaseName | A string-based identifier for a job, typically used for expressing dependencies and accessing output variables. | No | +| System.PlanId | A string-based identifier for a single pipeline run. | No | +| System.PullRequest.IsFork | If the pull request is from a fork of the repository, this variable is set to `True`.

      Otherwise, it's set to `False`. | Yes | +| System.PullRequest.PullRequestId | The ID of the pull request that caused this build. For example: `17`. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation)). | No | +| System.PullRequest.PullRequestNumber | The number of the pull request that caused this build. This variable is populated for pull requests from GitHub that have a different pull request ID and pull request number. This variable is only available in a YAML pipeline if a branch policy affects the PR. | No | +| System.PullRequest.targetBranchName | The name of the target branch for a pull request. This variable can be used in a pipeline to conditionally execute tasks or steps based on the target branch of the pull request. For example, you might want to trigger a different set of tests or code analysis tools depending on the branch that the changes are being merged into. | No | +| System.PullRequest.SourceBranch | The branch that is being reviewed in a pull request. For example: `refs/heads/users/raisa/new-feature` for Azure Repos. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation)). This variable is only available in a YAML pipeline if a branch policy affects the PR. | No | +| System.PullRequest.SourceCommitId | The commit that is being reviewed in a pull request. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation)). This variable is only available in a YAML pipeline if a branch policy affects the PR. | +| System.PullRequest.SourceRepositoryURI | The URL to the repo that contains the pull request. For example: `https://dev.azure.com/ouraccount/_git/OurProject`. | No | +| System.PullRequest.TargetBranch | The branch that is the target of a pull request. For example: `refs/heads/main` when your repository is in Azure Repos and `main` when your repository is in GitHub. This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation). This variable is only available in a YAML pipeline if a branch policy affects the PR. | No | +| System.StageAttempt | Set to 1 the first time this stage is attempted, and increments every time the stage is retried. | No | +| System.StageDisplayName | The human-readable name given to a stage. | No | +| System.StageName | A string-based identifier for a stage, typically used for expressing dependencies and accessing output variables. | No | +| System.TeamFoundationCollectionUri | The URI of the Azure DevOps organization or collection. For example: `https://dev.azure.com/fabrikamfiber/`.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | Yes | +| System.TeamProject | The name of the project that contains this build. | Yes | +| System.TeamProjectId | The ID of the project that this build belongs to. | Yes | +| System.TimelineId | A string-based identifier for the execution details and logs of a single pipeline run. | No | +| TF_BUILD | Set to `True` if a build task runs the script.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | ## Checks variables (DevOps Services) - - - - - - -
      VariableDescription
      Checks.StageAttemptSet to 1 the first time this stage is attempted, and increments every time the stage is retried. -

      -This variable can only be used within an approval or check for an environment. For example, you could use $(Checks.StageAttempt) within an Invoke REST API check.

      - Add the stage attempt as a parameter. -
      +| Variable | Description | +|:---------|:------------| +| Checks.StageAttempt | Set to 1 the first time this stage is attempted, and increments every time the stage is retried.

      This variable can only be used within an [approval or check](../../process/approvals.md) for an environment. For example, you could use `$(Checks.StageAttempt)` within an [Invoke REST API check](../../process/approvals.md#invoke-rest-api).

      :::image type="content" source="../media/checks-stageattempt-var.png" alt-text="Add the stage attempt as a parameter."::: | diff --git a/docs/pipelines/build/includes/variables-server-2020.md b/docs/pipelines/build/includes/variables-server-2020.md index a7310d5fd37..26793df6d24 100644 --- a/docs/pipelines/build/includes/variables-server-2020.md +++ b/docs/pipelines/build/includes/variables-server-2020.md @@ -8,742 +8,126 @@ ms.date: 02/13/2020 --- -## Agent variables (DevOps Server) +## Agent variables (DevOps Server 2020) > [!NOTE] > You can use agent variables as environment variables in your scripts and as parameters in your build tasks. -> You cannot use them to customize the build number or to apply a version control label or tag. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Agent.BuildDirectory -

      The local path on the agent where all folders for a given build pipeline are created. This variable has the same value as Pipeline.Workspace.

      -

      For example: /home/vsts/work/1

      -
      Agent.HomeDirectoryThe directory the agent is installed into. This contains the agent software. For example: c:\agent.
      Agent.IdThe ID of the agent.
      Agent.JobNameThe name of the running job. This will usually be "Job" or "__default", but in multi-config scenarios, will be the configuration.
      Agent.JobStatusThe status of the build. -
        -
      • Canceled -
      • Failed -
      • Succeeded -
      • SucceededWithIssues (partially successful) -
      -

      The environment variable should be referenced as AGENT_JOBSTATUS. The older agent.jobstatus is available for backwards compatibility.

      -
      Agent.MachineNameThe name of the machine on which the agent is installed.
      Agent.Name -

      The name of the agent that is registered with the pool.

      -

      If you're using a self-hosted agent, then this name gets set by you. See agents.

      -
      Agent.OS -The operating system of the agent host. Valid values are: -
        -
      • Windows_NT -
      • Darwin -
      • Linux -
      -If you're running in a container, the agent host and container may be running different operating systems. -
      Agent.OSArchitecture -The operating system processor architecture of the agent host. Valid values are: -
        -
      • X86 -
      • X64 -
      • ARM processor -
      -
      Agent.TempDirectory -

      A temporary folder that is cleaned after each pipeline job. This directory is used by tasks such as .NET Core CLI task to hold temporary items like test results before they're published.

      -

      For example: /home/vsts/work/_temp for Ubuntu

      -
      Agent.ToolsDirectory -The directory used by tasks such as Node Tool Installer and Use Python Version to switch between multiple versions of a tool. -These tasks add tools from this directory to PATH so that subsequent build steps can use them. -

      -Learn about managing this directory on a self-hosted agent. -
      Agent.WorkFolder -The working directory for this agent. -For example: c:\agent_work. -

      -Note: This directory isn't guaranteed to be writable by pipeline tasks (for example, when mapped into a container) -
      - -## Build variables (DevOps Server) +> You can't use them to customize the build number or to apply a version control label or tag. + +| Variable | Description | +|:---------|:------------| +| Agent.BuildDirectory | The local path on the agent where all folders for a given build pipeline are created. This variable has the same value as `Pipeline.Workspace`. For example: `/home/vsts/work/1`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).| +| Agent.HomeDirectory | The directory the agent is installed into and contains the agent software. For example: `c:\agent`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).| +| Agent.Id | The ID of the agent. | +| Agent.JobName | The name of the running job. The name is usually `Job` or `_default`, but in multi-config scenarios, is the configuration. | +| Agent.JobStatus | The status of the build.
      • `Canceled`
      • `Failed`
      • `Succeeded`
      • `SucceededWithIssues` (partially successful)
      • `Skipped` (last job)
      The environment variable should be referenced as `AGENT_JOBSTATUS`. The older `agent.jobstatus` is available for backwards compatibility. | +| Agent.MachineName | The name of the machine on which the agent is installed. | +| Agent.Name | The name of the agent that is registered with the pool.

      If you're using a self-hosted agent, then this name gets set by you. See [agents](../../agents/agents.md). | +| Agent.OS | The operating system of the agent host. Valid values are:
      • `Windows_NT`
      • `Darwin`
      • `Linux`
      If you're running in a container, the agent host and container might be running different operating systems. | +| Agent.OSArchitecture | The operating system processor architecture of the agent host. Valid values are:
      • `X86`
      • `X64`
      • `ARM processor`
      | +| Agent.TempDirectory | A temporary folder that is cleaned after each pipeline job. This directory is used by tasks such as .NET Core CLI task to hold temporary items like test results before they're published.
      For example: `/home/vsts/work/_temp` for Ubuntu. | +| Agent.ToolsDirectory | The directory used by tasks such as [Node Tool Installer](/azure/devops/pipelines/tasks/reference/node-tool-v0) and [Use Python Version](/azure/devops/pipelines/tasks/reference/use-python-version-v0) to switch between multiple versions of a tool.

      These tasks add tools from this directory to `PATH` so that subsequent build steps can use them.

      Learn about [managing this directory on a self-hosted agent](https://go.microsoft.com/fwlink/?linkid=2008884). | +| Agent.WorkFolder | The working directory for this agent. For example: `c:\agent_work`.

      Note: This directory isn't guaranteed to be writable by pipeline tasks (for example, when mapped into a container). For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).| + +## Build variables (DevOps Server 2020) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescriptionAvailable in templates?
      Build.ArtifactStagingDirectory - - -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent_work\1\a -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. -

      -Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself. -

      -See Artifacts in Azure Pipelines. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -      		No
      Build.BuildIdThe ID of the record for the completed build.No
      Build.BuildNumberThe name of the completed build, also known as the run number. You can specify what is included in this value.

      -A typical use of this variable is to make it part of the label format, which you specify on the repository tab. -

      - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.BuildUriThe URI for the build. For example: vstfs:///Build/Build/1430. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.BinariesDirectoryThe local path on the agent you can use as an output folder for compiled binaries. -

      -By default, new build pipelines aren't set up to clean this directory. You can define your build to clean it up on the Repository tab. -

      -For example: c:\agent_work\1\b. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.ContainerIdThe ID of the container for your artifact. When you upload an artifact in your pipeline, it's added to a container that is specific for that particular artifact.No
      Build.DefinitionNameThe name of the build pipeline. -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail. - -      		Yes
      Build.DefinitionVersionThe version of the build pipeline.Yes
      Build.QueuedBySee "How are the identity variables set?". -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -      		Yes
      Build.QueuedByIdSee "How are the identity variables set?".Yes
      Build.ReasonThe event that caused the build to run. -
        -
      • Manual: A user manually queued the build.
        • -
      • IndividualCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in.
        • -
      • BatchedCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in, and the Batch changes was selected.
        • -
      • Schedule: Scheduled trigger.
        • -
      • ValidateShelveset: A user manually queued the build of a specific TFVC shelveset.
        • -
      • CheckInShelveset: Gated check-in trigger.
        • -
      • PullRequest: The build was triggered by a Git branch policy that requires a build.
        • -
      • BuildCompletion: The build was triggered by another build
        • -
      • ResourceTrigger: The build was triggered by a resource trigger or it was triggered by another build.
        • -
      -See Build pipeline triggers, Improve code quality with branch policies. -      		Yes
      Build.Repository.CleanThe value you've selected for Clean in the source repository settings. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      Build.Repository.LocalPath - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. - -Important note: If you check out only one Git repository, this path will be the exact path to the code. -If you check out multiple repositories, the behavior is as follows (and might differ from the value of the Build.SourcesDirectory variable): -
        -
      • If the checkout step for the self (primary) repository has no custom checkout path defined, or the checkout path is the multi-checkout default path $(Pipeline.Workspace)/s/<RepoName> for the self repository, the value of this variable will revert to its default value, which is $(Pipeline.Workspace)/s.
        • -
      • If the checkout step for the self (primary) repository does have a custom checkout path defined (and it's not its multi-checkout default path), this variable will contain the exact path to the self repository.
        • -
      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.Repository.IDThe unique identifier of the repository. -

      -This won't change, even if the name of the repository does. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      Build.Repository.NameThe name of the triggering repository. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      Build.Repository.ProviderThe type of the triggering repository. - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -No
      Build.Repository.Tfvc.WorkspaceDefined if your repository is Team Foundation Version Control. The name of the TFVC workspace used by the build agent. -


      For example, if the Agent.BuildDirectory is c:\agent_work\12 and the Agent.Id is 8, the workspace name could be: ws_12_8 -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.Repository.UriThe URL for the triggering repository. For example: - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -No
      Build.RequestedForSee "How are the identity variables set?". -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -      		Yes
      Build.RequestedForEmailSee "How are the identity variables set?".Yes
      Build.RequestedForIdSee "How are the identity variables set?".Yes
      Build.SourceBranchThe branch of the triggering repo the build was queued for. Some examples: -
        -
      • Git repo branch: refs/heads/main
        • -
      • Git repo pull request: refs/pull/1/merge
        • -
      • TFVC repo branch: $/teamproject/main
        • -
      • TFVC repo gated check-in: Gated_2016-06-06_05.20.51.4369;username@live.com
        • -
      • TFVC repo shelveset build: myshelveset;username@live.com
        • -
      • When your pipeline is triggered by a tag: refs/tags/your-tag-name
        • -
      -When you use this variable in your build number format, the forward slash characters (/) are replaced with underscore characters _). -

      -Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you cannot use this variable in your build number format. -      		Yes
      Build.SourceBranchNameThe name of the branch in the triggering repo the build was queued for. -
        -
      • Git repo branch, pull request, or tag: The last path segment in the ref. For example, in refs/heads/main this value is main. In refs/heads/feature/tools this value is tools. In refs/tags/your-tag-name this value is your-tag-name.
        • -
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example, in $/teamproject/main this value is main.
        • -
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, Gated_2016-06-06_05.20.51.4369;username@live.com or myshelveset;username@live.com.
        • -
      -Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. -      		Yes
      Build.SourcesDirectory - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. - -Important note: If you check out only one Git repository, this path is the exact path to the code. If you check out multiple repositories, it reverts to its default value, which is $(Pipeline.Workspace)/s, even if the self (primary) repository is checked out to a custom path different from its multi-checkout default path $(Pipeline.Workspace)/s/<RepoName> (in this respect, the variable differs from the behavior of the Build.Repository.LocalPath variable). -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -      		No
      Build.SourceVersionThe latest version control change of the triggering repo that is included in this build. - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -Yes
      Build.SourceVersionMessageThe comment of the commit or changeset for the triggering repo. We truncate the message to the first line or 200 characters, whichever is shorter. - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -Also, this variable is only available on the step level and is not available in the job or stage levels (that is, the message isn't extracted until the job had started and checked out the code). - -Note: This variable is available in TFS 2015.4. - -> [!NOTE] -> The **Build.SourceVersionMessage** variable does not work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. -No
      Build.StagingDirectory - - -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent_work\1\a -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. -

      -Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself. -

      -See Artifacts in Azure Pipelines. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -      		No
      Build.Repository.Git.SubmoduleCheckoutThe value you've selected for Checkout submodules on the repository tab. With multiple repos checked out, this value tracks the triggering repository's setting. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      Build.SourceTfvcShelvesetDefined if your repository is Team Foundation Version Control. -


      If you're running a gated build or a shelveset build, this is set to the name of the shelveset you're building. -

      -Note: This variable yields a value that is invalid for build use in a build number format. -      		No
      Build.TriggeredBy.BuildIdIf the build was triggered by another build, then this variable is set to the BuildID of the triggering build. In Classic pipelines, this variable is triggered by a build completion trigger. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.       		No
      Build.TriggeredBy.DefinitionIdIf the build was triggered by another build, then this variable is set to the DefinitionID of the triggering build. In Classic pipelines, this variable is triggered by a build completion trigger. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.       		No
      Build.TriggeredBy.DefinitionNameIf the build was triggered by another build, then this variable is set to the name of the triggering build pipeline. In Classic pipelines, this variable is triggered by a build completion trigger. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      Build.TriggeredBy.BuildNumberIf the build was triggered by another build, then this variable is set to the number of the triggering build. In Classic pipelines, this variable is triggered by a build completion trigger. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.       		No
      Build.TriggeredBy.ProjectIDIf the build was triggered by another build, then this variable is set to ID of the project that contains the triggering build. In Classic pipelines, this variable is triggered by a build completion trigger. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      Common.TestResultsDirectoryThe local path on the agent where the test results are created. For example: c:\agent_work\1\TestResults -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      - -## Pipeline variables (DevOps Server) +When you use a variable in a template that isn't marked as available in templates. The variable doesn't render because its value isn't accessible within the template's scope. + + +| Variable | Description | Available in templates? | +|:---------|:------------|:------------------------| +| Build.ArtifactStagingDirectory | The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: `c:\agent_work\1\a`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      A typical way to use this folder is to publish your build artifacts with the [Copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish build artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks.

      Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

      See [Artifacts in Azure Pipelines](../../artifacts/artifacts-overview.md).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.BuildId | The ID of the record for the completed build. | No | +| Build.BuildNumber | The name of the completed build, also known as the run number. You can specify [what is included](../../process/run-number.md) in this value.

      A typical use of this variable is to make it part of the label format, which you specify on the [repository tab](../../repos/index.md).

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.BuildUri | The URI for the build. For example: `vstfs:///Build/Build/1430`.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.BinariesDirectory | The local path on the agent you can use as an output folder for compiled binaries. For example: `c:\agent_work\1\b`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      By default, new build pipelines aren't set up to clean this directory. You can define your build to clean it up on the [Repository tab](../../repos/index.md).



      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.ContainerId | The ID of the container for your artifact. When you upload an artifact in your pipeline, it's added to a container that is specific for that particular artifact. | No | +| Build.DefinitionName | The name of the build pipeline.

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | Yes | +| Build.DefinitionVersion | The version of the build pipeline. | Yes | +| Build.QueuedBy | See [How are the identity variables set?](#identity_values).

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | Yes | +| Build.QueuedById | See [How are the identity variables set?](#identity_values). | Yes | +| Build.Reason | The event that caused the build to run.
      • `Manual`: A user manually queued the build.
      • `IndividualCI`: **Continuous integration (CI)** triggered by a Git push or a TFVC check-in.
      • `BatchedCI`: **Continuous integration (CI)** triggered by a Git push or a TFVC check-in, and the **Batch changes** was selected.
      • `Schedule`: **Scheduled** trigger.
      • `ValidateShelveset`: A user manually queued the build of a specific TFVC shelveset.
      • `CheckInShelveset`: **Gated check-in** trigger.
      • `PullRequest`: A Git branch policy that requires a build triggers the build.
      • `BuildCompletion`: [another build](../../process/pipeline-triggers.md) triggers the build
      • `ResourceTrigger`: A [resource trigger](../../process/resources.md) or [another build](../../process/pipeline-triggers.md) triggers the build.
      See [Build pipeline triggers](../triggers.md), [Improve code quality with branch policies](../../../repos/git/branch-policies.md). | Yes | +| Build.Repository.Clean | The value you selected for **Clean** in the [source repository settings](../../repos/index.md).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.LocalPath | The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`.

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the [Repository tab](../../repos/index.md).

      Important note: If you check out only one Git repository, this path is the exact path to the code.

      If you check out multiple repositories, the behavior is as follows (and might differ from the value of the Build.SourcesDirectory variable):
      • If the checkout step for the self (primary) repository has no custom checkout path defined, or the checkout path is the multi-checkout default path `$(Pipeline.Workspace)/s/<RepoName>` for the self repository, the value of this variable reverts to its default value, which is `$(Pipeline.Workspace)/s`.
      • If the checkout step for the self (primary) repository has a custom checkout path defined and it's not its multi-checkout default path, this variable contains the exact path to the self repository.
      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.ID | The unique identifier of the [repository](../../repos/index.md).

      The value doesn't change, even if the name of the repository does. | Yes | +| Build.Repository.Name | The name of the triggering [repository](../../repos/index.md). | Yes | +| Build.Repository.Provider | The type of the triggering [repository](../../repos/index.md).
      • `TfsGit`: [TFS Git repository](../../../repos/git/index.yml)
      • `TfsVersionControl`: [Team Foundation Version Control](../../../repos/tfvc/what-is-tfvc.md)
      • `Git`: Git repository hosted on an external server
      • `GitHub`
      • `Svn`: Subversion
      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.Tfvc.Workspace | Defined if your [repository](../../repos/index.md) is Team Foundation Version Control. The name of the [TFVC workspace](../../../repos/tfvc/create-work-workspaces.md) used by the build agent.

      For example, if the Agent.BuildDirectory is `c:\agent_work\12` and the Agent.Id is `8`, the workspace name could be: `ws_12_8`.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.Uri | The URL for the triggering repository. For example:
      • Git: [https://dev.azure.com/fabrikamfiber/_git/Scripts](https://dev.azure.com/fabrikamfiber/_git/Scripts)
      • TFVC: [https://dev.azure.com/fabrikamfiber/](https://dev.azure.com/fabrikamfiber/)
      This variable can't be used as part of the build number or as a version control tag. | Yes | +| Build.RequestedFor | See [How are the identity variables set?](#identity_values).

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | Yes | +| Build.RequestedForEmail | See [How are the identity variables set?](#identity_values). | Yes | +| Build.RequestedForId | See [How are the identity variables set?](#identity_values). | Yes | +| Build.SourceBranch | The branch of the triggering repo the build was queued for. Some examples:
      • Git repo branch: `refs/heads/main`
      • Git repo pull request: `refs/pull/1/merge`
      • TFVC repo branch: `$/teamproject/main`
      • TFVC repo gated check-in: `Gated_2016-06-06_05.20.51.4369;username@live.com`
      • TFVC repo shelveset build: `myshelveset;username@live.com`
      • When a tag triggers your pipeline: `refs/tags/your-tag-name`
      When you use this variable in your build number format, the forward slash characters (`/`) are replaced with underscore characters `_`).

      Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. | Yes | +| Build.SourceBranchName | The name of the branch in the triggering repo the build was queued for.
      • Git repo branch, pull request, or tag: The last path segment in the ref. For example, in `refs/heads/main` this value is `main`. In `refs/heads/feature/tools`, this value is `tools`. In `refs/tags/your-tag-name`, this value is `your-tag-name`.
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example, in `$/teamproject/main` this value is `main`.
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, `Gated_2016-06-06_05.20.51.4369;username@live.com` or `myshelveset;username@live.com`.
      Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. | Yes | +| Build.SourcesDirectory | The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      By default, new build pipelines update only the changed files.

      Important note: If you check out only one Git repository, this path is the exact path to the code. If you check out multiple repositories, it reverts to its default value, which is `$(Pipeline.Workspace)/s`, even if the self (primary) repository is checked out to a custom path different from its multi-checkout default path `$(Pipeline.Workspace)/s/` (in this respect, the variable differs from the behavior of the Build.Repository.LocalPath variable).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.SourceVersion | The latest version control change of the triggering repo that is included in this build.
      • Git: The [commit](../../../repos/git/commits.md) ID.
      • TFVC: the [changeset](../../../repos/tfvc/find-view-changesets.md).
      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | Yes | +| Build.SourceVersionMessage | The comment of the commit or changeset for the triggering repo. We truncate the message to the first line or 200 characters, whichever is shorter.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      Also, this variable is only available on the step level. It isn't available in the job or stage levels. That is, the message isn't extracted until the job starts and checks out the code.

      Note: The **Build.SourceVersionMessage** variable doesn't work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. | No | +| Build.StagingDirectory | The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: `c:\agent_work\1\a`.

      A typical way to use this folder is to publish your build artifacts with the [Copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish build artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks.

      Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

      See [Artifacts in Azure Pipelines](../../artifacts/artifacts-overview.md).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.Git.SubmoduleCheckout | The value you select for **Checkout submodules** on the [repository tab](../../repos/index.md). With multiple repos checked out, this value tracks the triggering repository's setting.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.SourceTfvcShelveset | Defined if your [repository](../../repos/index.md) is Team Foundation Version Control (TFVC).

      If you're running a [gated build](../../repos/tfvc.md#gated) or a [shelveset build](../../create-first-pipeline.md#queueabuild), this variable is set to the name of the [shelveset](../../../repos/tfvc/suspend-your-work-manage-your-shelvesets.md) you're building.

      Note: This variable yields a value that is invalid for build use in a build number format. | No | +| Build.TriggeredBy.BuildId | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the BuildID of the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.TriggeredBy.DefinitionId | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the DefinitionID of the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.TriggeredBy.DefinitionName | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the name of the triggering build pipeline. In Classic pipelines, a build completion trigger triggers this variable.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.TriggeredBy.BuildNumber | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the number of the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.TriggeredBy.ProjectID | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to ID of the project that contains the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Common.TestResultsDirectory | The local path on the agent where the test results are created. For example: `c:\agent_work\1\TestResults`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | + +## Pipeline variables (DevOps Server 2020) - - - - - - - +| Variable | Description | +|:---------|:------------| +| Pipeline.Workspace | Workspace directory for a particular pipeline. This variable has the same value as `Agent.BuildDirectory`. For example, `/home/vsts/work/1`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).| -
      VariableDescription
      Pipeline.WorkspaceWorkspace directory for a particular pipeline. This variable has the same value as Agent.BuildDirectory.

      -For example, /home/vsts/work/1.
      - -## Deployment job variables (DevOps Server) +## Deployment job variables (DevOps Server 2020) -These variables are scoped to a specific [Deployment job](../../process/deployment-jobs.md) and will be resolved only at job execution time. - - - +These variables are scoped to a specific [Deployment job](../../process/deployment-jobs.md) and is resolved only at job execution time. - - - - +| Variable | Description | +|:---------|:------------| +| Environment.Name | Name of the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, `smarthotel-dev`. | +| Environment.Id | ID of the environment targeted in the deployment job. For example, `10`. | +| Environment.ResourceName | Name of the specific resource within the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, `bookings` which is a Kubernetes namespace that is added as a resource to the environment `smarthotel-dev`. | +| Environment.ResourceId | ID of the specific resource within the environment targeted in the deployment job to run the deployment steps. For example, `4`. | - - - - - - - - - - - - - - - -
      VariableDescription
      Environment.NameName of the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, smarthotel-dev.
      Environment.IdID of the environment targeted in the deployment job. For example, 10.
      Environment.ResourceNameName of the specific resource within the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, bookings which is a Kubernetes namespace that has been added as a resource to the environment smarthotel-dev.
      Environment.ResourceIdID of the specific resource within the environment targeted in the deployment job to run the deployment steps. For example, 4.
      - - -## System variables (DevOps Server) +## System variables (DevOps Server 2020) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescriptionAvailable in templates?
      System.AccessTokenUse the OAuth token to access the REST API. -

      -Use System.AccessToken from YAML scripts. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		Yes
      System.CollectionIdThe GUID of the TFS collection or Azure DevOps organizationYes
      System.CollectionUriA string Team Foundation Server collection URI.Yes
      System.DefaultWorkingDirectory - -[!INCLUDE [include](../includes/variables-build-sources-directory.md)] - -No
      System.DefinitionIdThe ID of the build pipeline.Yes
      System.HostTypeSet to build if the pipeline is a build. For a release, the values are deployment for a Deployment group job, gates during evaluation of gates, and release for other (Agent and Agentless) jobs.Yes
      System.JobAttemptSet to 1 the first time this job is attempted, and increments every time the job is retried.No
      System.JobDisplayNameThe human-readable name given to a job.No
      System.JobIdA unique identifier for a single attempt of a single job. The value is unique to the current pipeline.No
      System.JobNameThe name of the job, typically used for expressing dependencies and accessing output variables.No
      System.PhaseAttemptSet to 1 the first time this phase is attempted, and increments every time the job is retried.
      -
      -Note: "Phase" is a mostly redundant concept, which represents the design-time for a job (whereas job was the runtime version of a phase). We've mostly removed the concept of "phase" from Azure Pipelines. Matrix and multi-config jobs are the only place where "phase" is still distinct from "job". One phase can instantiate multiple jobs, which differ only in their inputs.      		No
      System.PhaseDisplayNameThe human-readable name given to a phase.No
      System.PhaseNameA string-based identifier for a job, typically used for expressing dependencies and accessing output variables.No
      System.StageAttemptSet to 1 the first time this stage is attempted, and increments every time the job is retried.No
      System.StageDisplayNameThe human-readable name given to a stage.No
      System.StageNameA string-based identifier for a stage, typically used for expressing dependencies and accessing output variables.Yes
      System.PullRequest.IsForkIf the pull request is from a fork of the repository, this variable is set to True. -Otherwise, it's set to False.Yes
      System.PullRequest.PullRequestIdThe ID of the pull request that caused this build. For example: 17. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy).No
      System.PullRequest.PullRequestNumberThe number of the pull request that caused this build. This variable is populated for pull requests from GitHub which have a different pull request ID and pull request number. This variable is only available in a YAML pipeline if the PR is affected by a branch policy.No
      System.PullRequest.targetBranchNameThe name of the target branch for a pull request. This variable can be used in a pipelines to conditionally execute tasks or steps based on the target branch of the pull request. For example, you might want to trigger a different set of tests or code analysis tools depending on the branch that the changes are being merged into. -No
      System.PullRequest.SourceBranchThe branch that is being reviewed in a pull request. For example: refs/heads/users/raisa/new-feature. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy). This variable is only available in a YAML pipeline if the PR is affected by a branch policy.No
      System.PullRequest.SourceRepositoryURIThe URL to the repo that contains the pull request. For example: https://dev.azure.com/ouraccount/_git/OurProject. No
      System.PullRequest.TargetBranchThe branch that is the target of a pull request. For example: refs/heads/main when your repository is in Azure Repos and main when your repository is in GitHub. This variable is initialized only if the build ran because of a Git PR affected by a branch policy. This variable is only available in a YAML pipeline if the PR is affected by a branch policy.No
      System.TeamFoundationCollectionUriThe URI of the team foundation collection. For example: https://dev.azure.com/fabrikamfiber/ -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		Yes
      System.TeamProjectThe name of the project that contains this build.Yes
      System.TeamProjectIdThe ID of the project that this build belongs to.Yes
      TF_BUILDSet to True if the script is being run by a build task. -

      -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.      		No
      +When you use a variable in a template that isn't marked as available in templates. The variable doesn't render because its value isn't accessible within the template's scope. + +| Variable | Description | Available in templates? | +|:---------|:------------|:------------------------| +| System.AccessToken | [Use the OAuth token to access the REST API](../../scripts/powershell.md#example-powershell-script-access-rest-api).

      [Use System.AccessToken from YAML scripts](../variables.md#systemaccesstoken).

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | Yes | +| System.CollectionId | The GUID of the TFS collection or Azure DevOps organization | Yes | +| System.CollectionUri | A string Team Foundation Server collection URI. | Yes | +| System.DefaultWorkingDirectory | [!INCLUDE [include](../includes/variables-build-sources-directory.md)] | No | +| System.DefinitionId | The ID of the build pipeline. | Yes | +| System.HostType | Set to `build` if the pipeline is a build. For a release, the values are `deployment` for a Deployment group job, `gates` during evaluation of gates, and `release` for other (Agent and Agentless) jobs. | Yes | +| System.JobAttempt | Set to 1 the first time this job is attempted, and increments every time the job is retried. | No | +| System.JobDisplayName | The human-readable name given to a job. | No | +| System.JobId | A unique identifier for a single attempt of a single job. The value is unique to the current pipeline. | No | +| System.JobName | The name of the job, typically used for expressing dependencies and accessing output variables. | No | +| System.PhaseAttempt | Set to 1 the first time this phase is attempted, and increments every time the job is retried.

      Note: *Phase* is a mostly redundant concept, which represents the design-time for a job (whereas job was the runtime version of a phase). The concept of phase is mostly removed from Azure Pipelines. Matrix and multi-config jobs are the only place where a phase is still distinct from a job. One phase can instantiate multiple jobs, which differ only in their inputs. | No | +| System.PhaseDisplayName | The human-readable name given to a phase. | No | +| System.PhaseName | A string-based identifier for a job, typically used for expressing dependencies and accessing output variables. | No | +| System.StageAttempt | Set to 1 the first time this stage is attempted, and increments every time the job is retried. | No | +| System.StageDisplayName | The human-readable name given to a stage. | No | +| System.StageName | A string-based identifier for a stage, typically used for expressing dependencies and accessing output variables. | Yes | +| System.PullRequest.IsFork | If the pull request is from a fork of the repository, this variable is set to `True`. Otherwise, its value is `False`. | Yes | +| System.PullRequest.PullRequestId | The ID of the pull request that caused this build. For example: `17`. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation)). | No | +| System.PullRequest.PullRequestNumber | The number of the pull request that caused this build. This variable is populated for pull requests from GitHub which have a different pull request ID and pull request number. This variable is only available in a YAML pipeline if a branch policy affects the PR. | No | +| System.PullRequest.targetBranchName | The name of the target branch for a pull request. This variable can be used in a pipeline to conditionally execute tasks or steps based on the target branch of the pull request. For example, you might want to trigger a different set of tests or code analysis tools depending on the branch that the changes are being merged into. | No | +| System.PullRequest.SourceBranch | The branch that is being reviewed in a pull request. For example: `refs/heads/users/raisa/new-feature`. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation)). This variable is only available in a YAML pipeline if a branch policy affects the PR. | No | +| System.PullRequest.SourceCommitId | The commit that is being reviewed in a pull request. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation)). This variable is only available in a YAML pipeline if a branch policy affects the PR. | +| System.PullRequest.SourceRepositoryURI | The URL to the repo that contains the pull request. For example: `https://dev.azure.com/ouraccount/_git/OurProject`. | No | +| System.PullRequest.TargetBranch | The branch that is the target of a pull request. For example: `refs/heads/main` when your repository is in Azure Repos and `main` when your repository is in GitHub. This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation). This variable is only available in a YAML pipeline if a branch policy affects the PR. | No | +| System.TeamFoundationCollectionUri | The URI of the team foundation collection. For example: `https://dev.azure.com/fabrikamfiber/`.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | Yes | +| System.TeamProject | The name of the project that contains this build. | Yes | +| System.TeamProjectId | The ID of the project that this build belongs to. | Yes | +| TF_BUILD | Set to `True` if a build task runs the script.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | diff --git a/docs/pipelines/build/includes/variables-server-2022.md b/docs/pipelines/build/includes/variables-server-2022.md new file mode 100644 index 00000000000..9956995e999 --- /dev/null +++ b/docs/pipelines/build/includes/variables-server-2022.md @@ -0,0 +1,162 @@ +--- +ms.topic: include +ms.service: azure-devops-pipelines +ms.manager: mijacobs +ms.author: jukullam +author: juliakm +ms.date: 02/13/2020 +--- + + +## Agent variables (DevOps Server 2022) + +> [!NOTE] +> You can use agent variables as environment variables in your scripts and as parameters in your build tasks. +> You can't use them to customize the build number or to apply a version control label or tag. + +| Variable | Description | +|:---------|:------------| +| Agent.BuildDirectory | The local path on the agent where all folders for a given build pipeline are created. This variable has the same value as `Pipeline.Workspace`. For example: `/home/vsts/work/1`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).| +| Agent.ContainerMapping | A mapping from container resource names in YAML to their Docker IDs at runtime. Example follows table. | +| Agent.HomeDirectory | The directory the agent is installed into and contains the agent software. For example: `c:\agent`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).| +| Agent.Id | The ID of the agent. | +| Agent.JobName | The name of the running job. The name is usually `Job` or `__default`, but in multi-config scenarios, it's the configuration. | +| Agent.JobStatus | The status of the build.
      • `Canceled`
      • `Failed`
      • `Succeeded`
      • `SucceededWithIssues` (partially successful)
      • `Skipped` (last job)
      The environment variable should be referenced as `AGENT_JOBSTATUS`. The older `agent.jobstatus` is available for backwards compatibility. | +| Agent.MachineName | The name of the machine on which the agent is installed. | +| Agent.Name | The name of the agent that is registered with the pool.

      If you're using a self-hosted agent, then this value is the name you specify. See [agents](../../agents/agents.md). | +| Agent.OS | The operating system of the agent host. Valid values are:
      • `Windows_NT`
      • `Darwin`
      • `Linux`
      If you're running in a container, the agent host and container might be running different operating systems. | +| Agent.OSArchitecture | The operating system processor architecture of the agent host. Valid values are:
      • `X86`
      • `X64`
      • `ARM`
      | +| Agent.TempDirectory | A temporary folder that is cleaned after each pipeline job. This directory is used by tasks such as [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) to hold temporary items like test results before they're published.

      For example: `/home/vsts/work/_temp` for Ubuntu. | +| Agent.ToolsDirectory | The directory used by tasks such as [Node Tool Installer](/azure/devops/pipelines/tasks/reference/node-tool-v0) and [Use Python Version](/azure/devops/pipelines/tasks/reference/use-python-version-v0) to switch between multiple versions of a tool.

      These tasks add tools from this directory to `PATH` so that subsequent build steps can use them.

      Learn about [managing this directory on a self-hosted agent](https://go.microsoft.com/fwlink/?linkid=2008884). | +| Agent.WorkFolder | The working directory for this agent. For example: `c:\agent_work`.

      Note: This directory isn't guaranteed to be writable by pipeline tasks (for example, when mapped into a container). For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).| + +Example of **Agent.ContainerMapping**: + +```yaml +{ + "one_container": { + "id": "bdbb357d73a0bd3550a1a5b778b62a4c88ed2051c7802a0659f1ff6e76910190" + }, + "another_container": { + "id": "82652975109ec494876a8ccbb875459c945982952e0a72ad74c91216707162bb" + } +} +``` + +## Build variables (DevOps Server 2022) + + + +When you use a variable in a template that isn't marked as available in templates, the variable doesn't render. The variable doesn't render because its value isn't accessible within the template's scope. + + +| Variable | Description | Available in [templates](../../process/templates.md)? | +|:---------|:------------|:------------------------------------------------------| +| Build.ArtifactStagingDirectory | The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: `c:\agent_work\1\a`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      A typical way to use this folder is to publish your build artifacts with the [Copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish build artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks.

      Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

      See [Artifacts in Azure Pipelines](../../artifacts/artifacts-overview.md).

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.BuildId | The ID of the record for the completed build. | No | +| Build.BuildNumber | The name of the completed build, also known as the run number. You can specify [what is included](../../process/run-number.md) in this value.

      A typical use of this variable is to make it part of the label format, which you specify on the [repository tab](../../repos/index.md).

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.BuildUri | The URI for the build. For example: `vstfs:///Build/Build/1430`.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.BinariesDirectory | The local path on the agent you can use as an output folder for compiled binaries. For example: `c:\agent_work\1\b`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      By default, new build pipelines aren't set up to clean this directory. You can define your build to clean it up on the [Repository tab](../../repos/index.md).



      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.ContainerId | The ID of the container for your artifact. When you upload an artifact in your pipeline, it's added to a container that is specific for that particular artifact. | No | +| Build.CronSchedule.DisplayName | The `displayName` of the cron schedule that triggered the pipeline run. This variable is only set if a YAML scheduled trigger triggers the pipeline run. For more information, see [schedules.cron definition - Build.CronSchedule.DisplayName variable](/azure/devops/pipelines/yaml-schema/schedules-cron#buildcronscheduledisplayname-variable). This variable is available in Azure DevOps Server 2022.1 and higher. | Yes | +| Build.DefinitionName | The name of the build pipeline.

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | Yes | +| Build.DefinitionVersion | The version of the build pipeline. | Yes | +| Build.QueuedBy | See [How are the identity variables set?](#identity_values).

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | Yes | +| Build.QueuedById | See [How are the identity variables set?](#identity_values). | Yes | +| Build.Reason | The event that caused the build to run.
      • `Manual`: A user manually queued the build.
      • `IndividualCI`: **Continuous integration (CI)** triggered by a Git push or a TFVC check-in.
      • `BatchedCI`: **Continuous integration (CI)** triggered by a Git push or a TFVC check-in, and the **Batch changes** was selected.
      • `Schedule`: **Scheduled** trigger.
      • `ValidateShelveset`: A user manually queued the build of a specific TFVC shelveset.
      • `CheckInShelveset`: **Gated check-in** trigger.
      • `PullRequest`: A Git branch policy that requires a build triggers the build.
      • `BuildCompletion`: [another build](../../process/pipeline-triggers.md) triggers the build
      • `ResourceTrigger`: A [resource trigger](../../process/resources.md) or [another build](../../process/pipeline-triggers.md) triggers the build.
      See [Build pipeline triggers](../triggers.md), [Improve code quality with branch policies](../../../repos/git/branch-policies.md). | Yes | +| Build.Repository.Clean | The value you select for **Clean** in the [source repository settings](../../repos/index.md).

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.LocalPath | The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`.

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the [Repository tab](../../repos/index.md).

      Important note: If you check out only one Git repository, this path is the exact path to the code. If you check out multiple repositories, the behavior is as follows (and might differ from the value of the Build.SourcesDirectory variable):
      • If the checkout step for the self (primary) repository has no custom checkout path defined, or the checkout path is the multi-checkout default path `$(Pipeline.Workspace)/s/` for the self repository, the value of this variable reverts to its default value, which is `$(Pipeline.Workspace)/s`.
      • If the checkout step for the self (primary) repository has a custom checkout path defined and it's not its multi-checkout default path, this variable contains the exact path to the self repository.
      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.ID | The unique identifier of the [repository](../../repos/index.md). | Yes | +| Build.Repository.Name | The name of the triggering [repository](../../repos/index.md). | Yes | +| Build.Repository.Provider | The type of the triggering [repository](../../repos/index.md).
      • `TfsGit`: [TFS Git repository](../../../repos/git/index.yml)
      • `TfsVersionControl`: [Team Foundation Version Control](../../../repos/tfvc/what-is-tfvc.md) (TFVC)
      • `Git`: Git repository hosted on an external server
      • `GitHub`
      • `Svn`: Subversion
      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.Tfvc.Workspace | Defined if your [repository](../../repos/index.md) is Team Foundation Version Control. The name of the [TFVC workspace](../../../repos/tfvc/create-work-workspaces.md) used by the build agent.

      For example, if the Agent.BuildDirectory is `c:\agent_work\12` and the Agent.Id is `8`, the workspace name could be: `ws_12_8`.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.Uri | The URL for the triggering repository. For example:
      • Git: [https://fabrikamfiber@dev.azure.com/fabrikamfiber/_git/Scripts](https://fabrikamfiber@dev.azure.com/fabrikamfiber/_git/Scripts)
      • TFVC: [https://dev.azure.com/fabrikamfiber/](https://dev.azure.com/fabrikamfiber/)
      This variable can't be used as part of the build number or as a version control tag. | Yes | +| Build.RequestedFor | See "[How are the identity variables set?](#identity_values)".

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | Yes | +| Build.RequestedForEmail | See "[How are the identity variables set?](#identity_values)". | Yes | +| Build.RequestedForId | See "[How are the identity variables set?](#identity_values)". | Yes | +| Build.SourceBranch | The branch of the triggering repo the build was queued for. Some examples:
      • Git repo branch: `refs/heads/main`
      • Git repo pull request: `refs/pull/1/merge`
      • TFVC repo branch: `$/teamproject/main`
      • TFVC repo gated check-in: `Gated_2016-06-06_05.20.51.4369;username@live.com`
      • TFVC repo shelveset build: `myshelveset;username@live.com`
      • When a tag triggers your pipeline: `refs/tags/your-tag-name`
      When you use this variable in your build number format, the forward slash characters (`/`) are replaced with underscore characters `_`).

      Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. | Yes | +| Build.SourceBranchName | The name of the branch in the triggering repo the build was queued for.
      • Git repo branch, pull request, or tag: The last path segment in the ref. For example, in `refs/heads/main`, this value is `main`. In `refs/heads/feature/tools`, this value is `tools`. In `refs/tags/your-tag-name`, this value is `your-tag-name`.
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example, in `$/teamproject/main`, this value is `main`.
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, `Gated_2016-06-06_05.20.51.4369;username@live.com` or `myshelveset;username@live.com`.
      Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. | Yes | +| Build.SourcesDirectory | The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      By default, new build pipelines update only the changed files.

      Important note: If you check out only one Git repository, this path is the exact path to the code. If you check out multiple repositories, it reverts to its default value, which is `$(Pipeline.Workspace)/s`, even if the self (primary) repository is checked out to a custom path different from its multi-checkout default path `$(Pipeline.Workspace)/s/` (in this respect, the variable differs from the behavior of the Build.Repository.LocalPath variable).

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.SourceVersion | The latest version control change of the triggering repo that is included in this build.
      • Git: The [commit](../../../repos/git/commits.md) ID.
      • TFVC: the [changeset](../../../repos/tfvc/find-view-changesets.md).
      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | Yes | +| Build.SourceVersionMessage | The comment of the commit or changeset for the triggering repo. We truncate the message to the first line or 200 characters, whichever is shorter.

      The `Build.SourceVersionMessage` corresponds to the message on `Build.SourceVersion` commit. The `Build.SourceVersion` commit for a PR build is the merge commit (not the commit on the source branch).

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      Also, this variable is only available on the step level. It isn't available in the job or stage levels. That is, the message isn't extracted until the job starts and the code is checked out.

      >Note: The **Build.SourceVersionMessage** variable doesn't work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. | No | +| Build.StagingDirectory | The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: `c:\agent_work\1\a`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      A typical way to use this folder is to publish your build artifacts with the [Copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish build artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks.

      Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

      See [Artifacts in Azure Pipelines](../../artifacts/artifacts-overview.md).

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.Repository.Git.SubmoduleCheckout | The value you select for **Checkout submodules** on the [repository tab](../../repos/index.md). With multiple repos checked out, this value tracks the triggering repository's setting.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | +| Build.SourceTfvcShelveset | Defined if your [repository](../../repos/index.md) is Team Foundation Version Control.

      If you're running a [gated build](../../repos/tfvc.md#gated) or a [shelveset build](../../create-first-pipeline.md#queueabuild), this variable is set to the name of the [shelveset](../../../repos/tfvc/suspend-your-work-manage-your-shelvesets.md) you're building.

      Note: This variable yields a value that is invalid for build use in a build number format. | No | +| Build.TriggeredBy.BuildId | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the BuildID of the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      If you're triggering a YAML pipeline using `resources`, you should use the [resources variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#the-pipeline-resource-metadata-as-predefined-variables) instead. | No | +| Build.TriggeredBy.DefinitionId | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the DefinitionID of the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      If you're triggering a YAML pipeline using `resources`, you should use the [resources variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#the-pipeline-resource-metadata-as-predefined-variables) instead. | No | +| Build.TriggeredBy.DefinitionName | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the name of the triggering build pipeline. In Classic pipelines, a build completion trigger triggers this variable.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      If you're triggering a YAML pipeline using `resources`, you should use the [resources variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#the-pipeline-resource-metadata-as-predefined-variables) instead. | No | +| Build.TriggeredBy.BuildNumber | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to the number of the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      If you're triggering a YAML pipeline using `resources`, you should use the [resources variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#the-pipeline-resource-metadata-as-predefined-variables) instead. | No | +| Build.TriggeredBy.ProjectID | If [another build triggers](../../process/pipeline-triggers.md) the build, then this variable is set to ID of the project that contains the triggering build. In Classic pipelines, a build completion trigger triggers this variable.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag.

      If you're triggering a YAML pipeline using `resources`, you should use the [resources variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#the-pipeline-resource-metadata-as-predefined-variables) instead. | No | +| Common.TestResultsDirectory | The local path on the agent where the test results are created. For example: `c:\agent_work\1\TestResults`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | + +## Pipeline variables (DevOps Server 2022) + + + +| Variable | Description | +|:---------|:------------| +| Pipeline.Workspace | Workspace directory for a particular pipeline. This variable has the same value as `Agent.BuildDirectory`. For example, `/home/vsts/work/1`. For more information about the agent directory structure, see [Agent directory structure](../../agents/agents.md#agent-directory-structure).| + +> [!TIP] +> If you're using classic release pipelines, you can use [classic releases and artifacts variables](../../release/variables.md) to store and access data throughout your pipeline. + +## Deployment job variables (DevOps Server 2022) + + + +These variables are scoped to a specific [Deployment job](../../process/deployment-jobs.md) and is resolved only at job execution time. + +| Variable | Description | +|:---------|:------------| +| Environment.Name | Name of the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, `smarthotel-dev`. | +| Environment.Id | ID of the environment targeted in the deployment job. For example, `10`. | +| Environment.ResourceName | Name of the specific resource within the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, `bookings` which is a Kubernetes namespace that is added as a resource to the environment `smarthotel-dev`. | +| Environment.ResourceId | ID of the specific resource within the environment targeted in the deployment job to run the deployment steps. For example, `4`. | +| Strategy.Name | The name of the deployment strategy: `canary`, `runOnce`, or `rolling`. | +| Strategy.CycleName | The current cycle name in a deployment. Options are `PreIteration`, `Iteration`, or `PostIteration`. | + +## System variables (DevOps Server 2022) + + + +When you use a variable in a template that isn't marked as available in templates, the variable doesn't render. The variable doesn't render because its value isn't accessible within the template's scope. + +| Variable | Description | Available in [templates](../../process/templates.md)? | +|:---------|:------------|:------------------------------------------------------| +| System.AccessToken | [Use the OAuth token to access the REST API](../../scripts/powershell.md#example-powershell-script-access-rest-api).

      [Use System.AccessToken from YAML scripts](../variables.md#systemaccesstoken).

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | Yes | +| System.CollectionId | The GUID of the Azure DevOps organization or collection. | Yes | +| System.CollectionUri | The URI of the Azure DevOps organization or collection. For example: `https://dev.azure.com/fabrikamfiber/`. | Yes | +| System.DefaultWorkingDirectory | [!INCLUDE [include](../includes/variables-build-sources-directory.md)] | Yes | +| System.DefinitionId | The ID of the build pipeline. | Yes | +| System.HostType | Set to `build` if the pipeline is a build. For a release, the values are `deployment` for a Deployment group job, `gates` during evaluation of gates, and `release` for other (Agent and Agentless) jobs. | Yes | +| System.JobAttempt | Set to 1 the first time this job is attempted, and increments every time the job is retried. | No | +| System.JobDisplayName | The human-readable name given to a job. | No | +| System.JobId | A unique identifier for a single attempt of a single job. The value is unique to the current pipeline. | No | +| System.JobName | The name of the job, typically used for expressing dependencies and accessing output variables. | No | +| System.PhaseAttempt | Set to 1 the first time this phase is attempted, and increments every time the job is retried.

      Note: *Phase* is a mostly redundant concept, which represents the design-time for a job (whereas job was the runtime version of a phase). The concept of phase is mostly removed from Azure Pipelines. Matrix and multi-config jobs are the only place where a phase is still distinct from a job. One phase can instantiate multiple jobs, which differ only in their inputs. | No | +| System.PhaseDisplayName | The human-readable name given to a phase. | No | +| System.PhaseName | A string-based identifier for a job, typically used for expressing dependencies and accessing output variables. | No | +| System.PlanId | A string-based identifier for a single pipeline run. | No | +| System.PullRequest.IsFork | If the pull request is from a fork of the repository, this variable is set to `True`. Otherwise, it's set to `False`. | Yes | +| System.PullRequest.PullRequestId | The ID of the pull request that caused this build. For example: `17`. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation)). | No | +| System.PullRequest.PullRequestNumber | The number of the pull request that caused this build. This variable is populated for pull requests from GitHub that have a different pull request ID and pull request number. This variable is only available in a YAML pipeline if a branch policy affects the PR. | No | +| System.PullRequest.targetBranchName | The name of the target branch for a pull request. This variable can be used in a pipeline to conditionally execute tasks or steps based on the target branch of the pull request. For example, you might want to trigger a different set of tests or code analysis tools depending on the branch that the changes are being merged into. | No | +| System.PullRequest.SourceBranch | The branch that is being reviewed in a pull request. For example: `refs/heads/users/raisa/new-feature` for Azure Repos. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation)). This variable is only available in a YAML pipeline if a branch policy affects the PR. | No | +| System.PullRequest.SourceRepositoryURI | The URL to the repo that contains the pull request. For example: `https://dev.azure.com/ouraccount/_git/OurProject`. | No | +| System.PullRequest.TargetBranch | The branch that is the target of a pull request. For example: `refs/heads/main` when your repository is in Azure Repos and `main` when your repository is in GitHub. This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation). This variable is only available in a YAML pipeline if a branch policy affects the PR. | No | +| System.StageAttempt | Set to 1 the first time this stage is attempted, and increments every time the stage is retried. | No | +| System.StageDisplayName | The human-readable name given to a stage. | No | +| System.StageName | A string-based identifier for a stage, typically used for expressing dependencies and accessing output variables. | No | +| System.TeamFoundationCollectionUri | The URI of the Azure DevOps organization or collection. For example: `https://dev.azure.com/fabrikamfiber/`.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | Yes | +| System.TeamProject | The name of the project that contains this build. | Yes | +| System.TeamProjectId | The ID of the project that this build belongs to. | Yes | +| System.TimelineId | A string-based identifier for the execution details and logs of a single pipeline run. | No | +| TF_BUILD | Set to `True` if a build task runs the script.

      It can be used as an environment variable in a script and as a parameter in a build task. It can't be used as part of the build number or as a version control tag. | No | + +## Checks variables (DevOps Server 2022) + + + +| Variable | Description | +|:---------|:------------| +| Checks.StageAttempt | Set to 1 the first time this stage is attempted, and increments every time the stage is retried.
      This variable can only be used within an [approval or check](../../process/approvals.md) for an environment. For example, you could use `$(Checks.StageAttempt)` within an [Invoke REST API check](../../process/approvals.md#invoke-rest-api).
      :::image type="content" source="../media/checks-stageattempt-var.png" alt-text="Add the stage attempt as a parameter."::: | diff --git a/docs/pipelines/build/includes/variables-server2019.md b/docs/pipelines/build/includes/variables-server2019.md index 69b22537f6d..a51b1f88ebf 100644 --- a/docs/pipelines/build/includes/variables-server2019.md +++ b/docs/pipelines/build/includes/variables-server2019.md @@ -15,542 +15,81 @@ ms.date: 06/29/2023 > You can use agent variables as environment variables in your scripts and as parameters in your build tasks. > You cannot use them to customize the build number or to apply a version control label or tag. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Agent.BuildDirectory -

      The local path on the agent where all folders for a given build pipeline are created.

      -

      For example: c:\agent_work\1

      -
      Agent.HomeDirectoryThe directory the agent is installed into. This contains the agent software. For example: c:\agent.
      Agent.IdThe ID of the agent.
      Agent.JobNameThe name of the running job. This will usually be "Job" or "__default", but in multi-config scenarios, will be the configuration.
      Agent.JobStatusThe status of the build. -
        -
      • Canceled -
      • Failed -
      • Succeeded -
      • SucceededWithIssues (partially successful) -
      -

      The environment variable should be referenced as AGENT_JOBSTATUS. The older agent.jobstatus is available for backwards compatibility.

      -
      Agent.MachineNameThe name of the machine on which the agent is installed.
      Agent.Name -

      The name of the agent that is registered with the pool.

      -

      If you're using a self-hosted agent, then this name get set by you. See agents.

      -
      Agent.OS -The operating system of the agent host. Valid values are: -
        -
      • Windows_NT -
      • Darwin -
      • Linux -
      -If you're running in a container, the agent host and container may be running different operating systems. -
      Agent.OSArchitecture -The operating system processor architecture of the agent host. Valid values are: -
        -
      • X86 -
      • X64 -
      • ARM processor -
      -
      Agent.TempDirectory -A temporary folder that is cleaned after each pipeline job. This directory is used by tasks such as .NET Core CLI task to hold temporary items like test results before they're published. -
      Agent.ToolsDirectory -The directory used by tasks such as Node Tool Installer and Use Python Version to switch between multiple versions of a tool. -These tasks add tools from this directory to PATH so that subsequent build steps can use them. -

      -Learn about managing this directory on a self-hosted agent. -
      Agent.WorkFolder -The working directory for this agent. -For example: c:\agent_work. -

      -This directory isn't guaranteed to be writable by pipeline tasks (for example, when mapped into a container)
      +| Variable | Description | +|:---------|:------------| +| Agent.BuildDirectory | The local path on the agent where all folders for a given build pipeline are created. For example: `c:\agent_work\1`. | +| Agent.HomeDirectory | The directory the agent is installed into. This contains the agent software. For example: `c:\agent`. | +| Agent.Id | The ID of the agent. | +| Agent.JobName | The name of the running job. This will usually be "Job" or "__default", but in multi-config scenarios, will be the configuration. | +| Agent.JobStatus | The status of the build.
      • `Canceled`
      • `Failed`
      • `Succeeded`
      • `SucceededWithIssues` (partially successful)
      • `Skipped` (last job)
      The environment variable should be referenced as `AGENT_JOBSTATUS`. The older `agent.jobstatus` is available for backwards compatibility. | +| Agent.MachineName | The name of the machine on which the agent is installed. | +| Agent.Name | The name of the agent that is registered with the pool.

      If you're using a self-hosted agent, then this name get set by you. See [agents](../../agents/agents.md). | +| Agent.OS | The operating system of the agent host. Valid values are:
      • `Windows_NT`
      • `Darwin`
      • `Linux`
      If you're running in a container, the agent host and container may be running different operating systems. | +| Agent.OSArchitecture | The operating system processor architecture of the agent host. Valid values are:
      • `X86`
      • `X64`
      • `ARM processor`
      | +| Agent.TempDirectory | A temporary folder that is cleaned after each pipeline job. This directory is used by tasks such as [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) to hold temporary items like test results before they're published. | +| Agent.ToolsDirectory | The directory used by tasks such as [Node Tool Installer](/azure/devops/pipelines/tasks/reference/node-tool-v0) and [Use Python Version](/azure/devops/pipelines/tasks/reference/use-python-version-v0) to switch between multiple versions of a tool.

      These tasks add tools from this directory to `PATH` so that subsequent build steps can use them.

      Learn about [managing this directory on a self-hosted agent](https://go.microsoft.com/fwlink/?linkid=2008884). | +| Agent.WorkFolder | The working directory for this agent. For example: `c:\agent_work`.

      This directory isn't guaranteed to be writable by pipeline tasks (for example, when mapped into a container). | ## Build variables (DevOps Server 2019) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Build.ArtifactStagingDirectory - - -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent_work\1\a -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. -

      -Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself. -

      -See Artifacts in Azure Pipelines. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -
      Build.BuildIdThe ID of the record for the completed build.
      Build.BuildNumberThe name of the completed build. You can specify the build number format that generates this value in the pipeline options. -

      -A typical use of this variable is to make it part of the label format, which you specify on the repository tab. -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.BuildUriThe URI for the build. For example: vstfs:///Build/Build/1430. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.BinariesDirectoryThe local path on the agent you can use as an output folder for compiled binaries. -

      -By default, new build pipelines aren't set up to clean this directory. You can define your build to clean it up on the Repository tab. -

      -For example: c:\agent_work\1\b. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.DefinitionNameThe name of the build pipeline. -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail. - -
      Build.DefinitionVersionThe version of the build pipeline.
      Build.QueuedBySee "How are the identity variables set?". -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -
      Build.QueuedByIdSee "How are the identity variables set?".
      Build.ReasonThe event that caused the build to run. -
        -
      • Manual: A user manually queued the build.
        • -
      • IndividualCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in.
        • -
      • BatchedCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in, and the Batch changes was selected.
        • -
      • Schedule: Scheduled trigger.
        • -
      • ValidateShelveset: A user manually queued the build of a specific TFVC shelveset.
        • -
      • CheckInShelveset: Gated check-in trigger.
        • -
      • PullRequest: The build was triggered by a Git branch policy that requires a build.
        • -
      • BuildCompletion: The build was triggered by another build
        • -
      -See Build pipeline triggers, Improve code quality with branch policies. -
      Build.Repository.CleanThe value you've selected for Clean in the source repository settings. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.Repository.LocalPath - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -

      This variable is synonymous with Build.SourcesDirectory.

      -
      Build.Repository.NameThe name of the repository. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.Repository.ProviderThe type of repository you selected. - -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.Repository.Tfvc.WorkspaceDefined if your repository is Team Foundation Version Control. The name of the TFVC workspace used by the build agent. -


      For example, if the Agent.BuildDirectory is c:\agent_work\12 and the Agent.Id is 8, the workspace name could be: ws_12_8 -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.Repository.UriThe URL for the repository. For example: - -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.RequestedForSee "How are the identity variables set?". -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -
      Build.RequestedForEmailSee "How are the identity variables set?".
      Build.RequestedForIdSee "How are the identity variables set?".
      Build.SourceBranchThe branch the build was queued for. Some examples: -
        -
      • Git repo branch: refs/heads/main
        • -
      • Git repo pull request: refs/pull/1/merge
        • -
      • TFVC repo branch: $/teamproject/main
        • -
      • TFVC repo gated check-in: Gated_2016-06-06_05.20.51.4369;username@live.com
        • -
      • TFVC repo shelveset build: myshelveset;username@live.com
        • -
      -When you use this variable in your build number format, the forward slash characters (/) are replaced with underscore characters _). -

      -Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. -
      Build.SourceBranchNameThe name of the branch the build was queued for. -
        -
      • Git repo branch, pull request, or tag: The last path segment in the ref. For example, in refs/heads/main this value is main. In refs/heads/feature/tools this value is tools. In refs/tags/your-tag-name this value is your-tag-name.
        • -
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example in $/teamproject/main this value is main.
        • -
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, Gated_2016-06-06_05.20.51.4369;username@live.com or myshelveset;username@live.com.
        • -
      -Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. -
      Build.SourcesDirectory - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -

      This variable is synonymous with Build.Repository.LocalPath.

      -
      Build.SourceVersionThe latest version control change that is included in this build. - -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.SourceVersionMessageThe comment of the commit or changeset. We truncate the message to the first line or 200 characters, whichever is shorter. - -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -Note: This variable is available in TFS 2015.4. - -> [!NOTE] -> The **Build.SourceVersionMessage** variable does not work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. -
      Build.StagingDirectory - - -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent_work\1\a -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. -

      -Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself. -

      -See Artifacts in Azure Pipelines. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -
      Build.Repository.Git.SubmoduleCheckoutThe value you've selected for Checkout submodules on the repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.SourceTfvcShelvesetDefined if your repository is Team Foundation Version Control. -


      If you're running a gated build or a shelveset build, this is set to the name of the shelveset you're building. -

      -Note: This variable yields a value that is invalid for build use in a build number format. -
      Build.TriggeredBy.BuildIdIf the build was triggered by another build, then this variable is set to the BuildID of the triggering build. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.TriggeredBy.DefinitionIdIf the build was triggered by another build, then this variable is set to the DefinitionID of the triggering build. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.TriggeredBy.DefinitionNameIf the build was triggered by another build, then this variable is set to the name of the triggering build pipeline. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.TriggeredBy.BuildNumberIf the build was triggered by another build, then this variable is set to the number of the triggering build. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.TriggeredBy.ProjectIDIf the build was triggered by another build, then this variable is set to ID of the project that contains the triggering build. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Common.TestResultsDirectoryThe local path on the agent where the test results are created. For example: c:\agent_work\1\TestResults -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      +| Variable | Description | +|:---------|:------------| +| Build.ArtifactStagingDirectory | The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: `c:\agent_work\1\a`.

      A typical way to use this folder is to publish your build artifacts with the [Copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish build artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks.

      Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

      See [Artifacts in Azure Pipelines](../../artifacts/artifacts-overview.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.BuildId | The ID of the record for the completed build. | +| Build.BuildNumber | The name of the completed build. You can specify the build number format that generates this value in the [pipeline options](../options.md).

      A typical use of this variable is to make it part of the label format, which you specify on the [repository tab](../../repos/index.md).

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.BuildUri | The URI for the build. For example: `vstfs:///Build/Build/1430`.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.BinariesDirectory | The local path on the agent you can use as an output folder for compiled binaries.

      By default, new build pipelines aren't set up to clean this directory. You can define your build to clean it up on the [Repository tab](../../repos/index.md).

      For example: `c:\agent_work\1\b`.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.DefinitionName | The name of the build pipeline.

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) will fail. | +| Build.DefinitionVersion | The version of the build pipeline. | +| Build.QueuedBy | See "[How are the identity variables set?](#identity_values)".

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | +| Build.QueuedById | See "[How are the identity variables set?](#identity_values)". | +| Build.Reason | The event that caused the build to run.
      • `Manual`: A user manually queued the build.
      • `IndividualCI`: **Continuous integration (CI)** triggered by a Git push or a TFVC check-in.
      • `BatchedCI`: **Continuous integration (CI)** triggered by a Git push or a TFVC check-in, and the **Batch changes** was selected.
      • `Schedule`: **Scheduled** trigger.
      • `ValidateShelveset`: A user manually queued the build of a specific TFVC shelveset.
      • `CheckInShelveset`: **Gated check-in** trigger.
      • `PullRequest`: The build was triggered by a Git branch policy that requires a build.
      • `BuildCompletion`: The build was [triggered by another build](../../process/pipeline-triggers.md).
      See [Build pipeline triggers](../triggers.md), [Improve code quality with branch policies](../../../repos/git/branch-policies.md). | +| Build.Repository.Clean | The value you've selected for **Clean** in the [source repository settings](../../repos/index.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.Repository.LocalPath | The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the [Repository tab](../../repos/index.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.

      This variable is synonymous with Build.SourcesDirectory. | +| Build.Repository.Name | The name of the [repository](../../repos/index.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.Repository.Provider | The type of [repository you selected](../../repos/index.md).
      • `TfsGit`: [TFS Git repository](../../../repos/git/index.yml)
      • `TfsVersionControl`: [Team Foundation Version Control](../../../repos/tfvc/what-is-tfvc.md)
      • `Git`: Git repository hosted on an external server
      • `GitHub`
      • `Svn`: Subversion
      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.Repository.Tfvc.Workspace | Defined if your [repository](../../repos/index.md) is Team Foundation Version Control. The name of the [TFVC workspace](../../../repos/tfvc/create-work-workspaces.md) used by the build agent.

      For example, if the Agent.BuildDirectory is `c:\agent_work\12` and the Agent.Id is `8`, the workspace name could be: `ws_12_8`.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.Repository.Uri | The URL for the repository. For example:
      • Git: [https://dev.azure.com/fabrikamfiber/_git/Scripts](https://dev.azure.com/fabrikamfiber/_git/Scripts)
      • TFVC: [https://dev.azure.com/fabrikamfiber/](https://dev.azure.com/fabrikamfiber/)
      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.RequestedFor | See "[How are the identity variables set?](#identity_values)".

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | +| Build.RequestedForEmail | See "[How are the identity variables set?](#identity_values)". | +| Build.RequestedForId | See "[How are the identity variables set?](#identity_values)". | +| Build.SourceBranch | The branch the build was queued for. Some examples:
      • Git repo branch: `refs/heads/main`
      • Git repo pull request: `refs/pull/1/merge`
      • TFVC repo branch: `$/teamproject/main`
      • TFVC repo gated check-in: `Gated_2016-06-06_05.20.51.4369;username@live.com`
      • TFVC repo shelveset build: `myshelveset;username@live.com`
      When you use this variable in your build number format, the forward slash characters (`/`) are replaced with underscore characters (`_`).

      Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. | +| Build.SourceBranchName | The name of the branch the build was queued for.
      • Git repo branch, pull request, or tag: The last path segment in the ref. For example, in `refs/heads/main` this value is `main`. In `refs/heads/feature/tools` this value is `tools`. In `refs/tags/your-tag-name` this value is `your-tag-name`.
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example in `$/teamproject/main` this value is `main`.
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, `Gated_2016-06-06_05.20.51.4369;username@live.com` or `myshelveset;username@live.com`.
      Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. | +| Build.SourcesDirectory | The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`.

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the [Repository tab](../../repos/index.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.

      This variable is synonymous with Build.Repository.LocalPath. | +| Build.SourceVersion | The latest version control change that is included in this build.
      • Git: The [commit](../../../repos/git/commits.md) ID.
      • TFVC: the [changeset](../../../repos/tfvc/find-view-changesets.md).
      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.SourceVersionMessage | The comment of the commit or changeset. We truncate the message to the first line or 200 characters, whichever is shorter.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.

      Note: This variable is available in TFS 2015.4.

      Note: The **Build.SourceVersionMessage** variable does not work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. | +| Build.StagingDirectory | The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: `c:\agent_work\1\a`.

      A typical way to use this folder is to publish your build artifacts with the [Copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish build artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks.

      Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

      See [Artifacts in Azure Pipelines](../../artifacts/artifacts-overview.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.Repository.Git.SubmoduleCheckout | The value you've selected for **Checkout submodules** on the [repository tab](../../repos/index.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.SourceTfvcShelveset | Defined if your [repository](../../repos/index.md) is Team Foundation Version Control.

      If you're running a [gated build](../../repos/tfvc.md#gated) or a [shelveset build](../../create-first-pipeline.md#queueabuild), this is set to the name of the [shelveset](../../../repos/tfvc/suspend-your-work-manage-your-shelvesets.md) you're building.

      Note: This variable yields a value that is invalid for build use in a build number format. | +| Build.TriggeredBy.BuildId | If the build was [triggered by another build](../../process/pipeline-triggers.md), then this variable is set to the BuildID of the triggering build.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.TriggeredBy.DefinitionId | If the build was [triggered by another build](../../process/pipeline-triggers.md), then this variable is set to the DefinitionID of the triggering build.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.TriggeredBy.DefinitionName | If the build was [triggered by another build](../../process/pipeline-triggers.md), then this variable is set to the name of the triggering build pipeline.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.TriggeredBy.BuildNumber | If the build was [triggered by another build](../../process/pipeline-triggers.md), then this variable is set to the number of the triggering build.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.TriggeredBy.ProjectID | If the build was [triggered by another build](../../process/pipeline-triggers.md), then this variable is set to ID of the project that contains the triggering build.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Common.TestResultsDirectory | The local path on the agent where the test results are created. For example: `c:\agent_work\1\TestResults`.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | ## System variables (DevOps Server 2019) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      System.AccessTokenUse the OAuth token to access the REST API. -

      -Use System.AccessToken from YAML scripts. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      System.CollectionIdThe GUID of the TFS collection or Azure DevOps organization
      System.DefaultWorkingDirectory - -[!INCLUDE [include](../includes/variables-build-sources-directory.md)] - -
      System.DefinitionIdThe ID of the build pipeline.
      System.HostTypeSet to build if the pipeline is a build. For a release, the values are deployment for a Deployment group job and release for an Agent job. -
      System.PullRequest.IsForkIf the pull request is from a fork of the repository, this variable is set to True. -Otherwise, it is set to False.
      System.PullRequest.PullRequestIdThe ID of the pull request that caused this build. For example: 17. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)
      System.PullRequest.PullRequestNumberThe number of the pull request that caused this build. This variable is populated for pull requests from GitHub, which have a different pull request ID and pull request number.
      System.PullRequest.SourceBranchThe branch that is being reviewed in a pull request. For example: refs/heads/users/raisa/new-feature. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)
      System.PullRequest.SourceRepositoryURIThe URL to the repo that contains the pull request. For example: https://dev.azure.com/ouraccount/_git/OurProject. (This variable is initialized only if the build ran because of a Azure Repos Git PR affected by a branch policy. It isn't initialized for GitHub PRs.)
      System.PullRequest.TargetBranchThe branch that is the target of a pull request. For example: refs/heads/main. This variable is initialized only if the build ran because of a Git PR affected by a branch policy.
      System.TeamFoundationCollectionUriThe URI of the team foundation collection. For example: https://dev.azure.com/fabrikamfiber/. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      System.TeamProjectThe name of the project that contains this build.
      System.TeamProjectIdThe ID of the project that this build belongs to.
      TF_BUILDSet to True if the script is being run by a build task. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      \ No newline at end of file +[Example PowerShell script: access REST API](../../scripts/powershell.md#example-powershell-script-access-rest-api) + +| Variable | Description | +|:---------|:------------| +| System.AccessToken | [Use the OAuth token to access the REST API](../../scripts/powershell.md#example-powershell-script-access-rest-api).

      [Use System.AccessToken from YAML scripts](../variables.md#systemaccesstoken).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| System.CollectionId | The GUID of the TFS collection or Azure DevOps organization | +| System.DefaultWorkingDirectory | [!INCLUDE [include](../includes/variables-build-sources-directory.md)] | +| System.DefinitionId | The ID of the build pipeline. | +| System.HostType | Set to `build` if the pipeline is a build. For a release, the values are `deployment` for a Deployment group job and `release` for an Agent job. +| System.PullRequest.IsFork | If the pull request is from a fork of the repository, this variable is set to `True`. Otherwise, it is set to `False`. | +| System.PullRequest.PullRequestId | The ID of the pull request that caused this build. For example: `17`. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation).) | +| System.PullRequest.PullRequestNumber | The number of the pull request that caused this build. This variable is populated for pull requests from GitHub, which have a different pull request ID and pull request number. | +| System.PullRequest.SourceBranch | The branch that is being reviewed in a pull request. For example: `refs/heads/users/raisa/new-feature`. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation).) | +| System.PullRequest.SourceCommitId | The commit that is being reviewed in a pull request. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation).) | +| System.PullRequest.SourceRepositoryURI | The URL to the repo that contains the pull request. For example: `https://dev.azure.com/ouraccount/_git/OurProject`. (This variable is initialized only if the build ran because of a [Azure Repos Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation). It isn't initialized for GitHub PRs.) | +| System.PullRequest.TargetBranch | The branch that is the target of a pull request. For example: `refs/heads/main`. This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation). | +| System.TeamFoundationCollectionUri | The URI of the team foundation collection. For example: `https://dev.azure.com/fabrikamfiber/`.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| System.TeamProject | The name of the project that contains this build. | +| System.TeamProjectId | The ID of the project that this build belongs to. | +| TF_BUILD | Set to `True` if the script is being run by a build task.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | diff --git a/docs/pipelines/build/includes/variables-tfs2015.md b/docs/pipelines/build/includes/variables-tfs2015.md deleted file mode 100644 index be01b48172a..00000000000 --- a/docs/pipelines/build/includes/variables-tfs2015.md +++ /dev/null @@ -1,459 +0,0 @@ ---- -ms.topic: include -ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: jukullam -author: juliakm -ms.date: 02/13/2020 ---- - - - -## Agent variables (TFS 2015) - -> [!NOTE] -> You can use agent variables as environment variables in your scripts and as parameters in your build tasks. -> You cannot use them to customize the build number or to apply a version control label or tag. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Agent.BuildDirectory -

      The local path on the agent where all folders for a given build pipeline are created.

      -

      For example:

      -
        -
      • TFS 2015.4: C:\TfsData\Agents\Agent-MACHINENAME_work\1
        • -
      • TFS 2015 RTM user-installed agent: C:\Agent_work\6c3842c6
        • -
      • TFS 2015 RTM built-in agent: C:\TfsData\Build_work\6c3842c6
        • -
      -
      Agent.HomeDirectory -

      The directory the agent is installed into. This contains the agent software.

      -

      For example:

      -
        -
      • TFS 2015.4: C:\TfsData\Agents\Agent-MACHINENAME
        • -
      • TFS 2015 RTM user-installed agent: C:\Agent
        • -
      • TFS 2015 RTM built-in agent: C:\Program Files\Microsoft Team Foundation Server 14.0\Build
        • -
      -
      Agent.IdThe ID of the agent.
      Agent.JobStatusThe status of the build. -
        -
      • Canceled -
      • Failed -
      • Succeeded -
      • SucceededWithIssues (partially successful) -
      -

      Note: The environment variable can be referenced only as agent.jobstatus. AGENT_JOBSTATUS was not present in TFS 2015.

      -
      Agent.MachineNameThe name of the machine on which the agent is installed. -This variable is available in TFS 2015.4, not in TFS 2015 RTM.
      Agent.Name -

      The name of the agent that is registered with the pool.

      -

      This name is specified by you. See agents.

      -
      Agent.WorkFolder -The working directory for this agent. -For example: c:\agent_work. -
      - -## Build variables (TFS 2015) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Build.ArtifactStagingDirectoryThe local path on the agent where any artifacts are copied to before being pushed to their destination. -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. See Artifacts in Azure Pipelines. -

      -For example: -
        -
      • TFS 2015.4: C:\TfsData\Agents\Agent-MACHINENAME_work\1\a -
      • TFS 2015 RTM default agent: C:\TfsData\Build_work\6c3842c6\artifacts -
      • TFS 2015 RTM agent installed by you: C:\Agent_work\6c3842c6\artifacts -
      -This directory is purged before each new build, so you don't have to clean it up yourself. -

      -In TFS 2015.4, Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.BuildIdThe ID of the record for the completed build.
      Build.BuildNumberThe name of the completed build. You can specify the build number format that generates this value in the pipeline options. - -A typical use of this variable is to make it part of the label format, which you specify on the repository tab. - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of a version control tag. -
      Build.BuildUriThe URI for the build. For example: vstfs:///Build/Build/1430. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.BinariesDirectory -The local path on the agent you can use as an output folder for compiled binaries. Available in TFS 2015.4. -

      -By default, new build pipelines are not set up to clean this directory. You can define your build to clean it up on the Repository tab. -

      -For example: C:\TfsData\Agents\Agent-MACHINENAME_work\1\b -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.DefinitionNameThe name of the build pipeline. - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail. -
      Build.DefinitionVersionThe version of the build pipeline.
      Build.QueuedBySee "How are the identity variables set?". - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail.
      Build.QueuedByIdSee "How are the identity variables set?".
      Build.Repository.CleanThe value you've selected for Clean in the source repository settings. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.Repository.LocalPath - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -

      This variable is synonymous with Build.SourcesDirectory.

      -
      Build.Repository.NameThe name of the repository. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.Repository.ProviderThe type of repository you selected. - -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.Repository.Tfvc.WorkspaceDefined if your repository is Team Foundation Version Control. The name of the TFVC workspace used by the build agent. -

      -For example, if the Agent.BuildDirectory is c:\agent_work\12 and the Agent.Id is 8, the workspace name could be: ws_12_8 -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.Repository.UriThe URL for the repository. For example: -
        -
      • Git: https://fabrikamfiber/tfs/DefaultCollection/Scripts/_git/Scripts -
      • TFVC: https://fabrikamfiber/tfs/DefaultCollection/ -
      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.RequestedForSee "How are the identity variables set?". - -[!INCLUDE [include](../includes/variables-invalid-label-characters.md)] - -
      Build.RequestedForIdSee "How are the identity variables set?".
      Build.SourceBranchThe branch the build was queued for. Some examples: -
        -
      • Git repo branch: refs/heads/main
        • -
      • Git repo pull request: refs/pull/1/merge
        • -
      • TFVC repo branch: $/teamproject/main
        • -
      • TFVC repo gated check-in: Gated_2016-06-06_05.20.51.4369;username@live.com
        • -
      • TFVC repo shelveset build: myshelveset;username@live.com
        • -
      -When you use this variable in your build number format, the forward slash characters (/) are replaced with underscore characters _). -

      -Note: In TFVC, if you are running a gated check-in build or manually building a shelveset, you cannot use this variable in your build number format. -
      Build.SourceBranchNameThe name of the branch the build was queued for. -
        -
      • Git repo branch or pull request: The last path segment in the ref. For example, in refs/heads/main this value is master. In refs/heads/feature/tools this value is tools.
        • -
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example in $/teamproject/main this value is main.
        • -
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, Gated_2016-06-06_05.20.51.4369;username@live.com or myshelveset;username@live.com.
        • -
      -Note: In TFVC, if you are running a gated check-in build or manually building a shelveset, you cannot use this variable in your build number format. -
      Build.SourcesDirectory - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -

      This variable is synonymous with Build.Repository.LocalPath.

      -
      Build.SourcesDirectoryHash -Note: This variable is available in TFS 2015 RTM, but not in TFS 2015.4. -
      Build.SourceVersionThe latest version control change that is included in this build. - -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.SourceVersionMessageThe comment of the commit or changeset. We truncate the message to the first line or 200 characters, whichever is shorter. - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -Note: This variable is available in TFS 2015.4. - -> [!NOTE] -> The **Build.SourceVersionMessage** variable does not work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. -
      Build.StagingDirectory -TFS 2015 RTM -

      -The local path on the agent you can use as an output folder for compiled binaries. For example: C:\TfsData\Build_work\6c3842c6\staging. -

      -By default, new build pipelines are not set up to clean this directory. You can define your build to clean it up on the Repository tab. -

      -TFS 2015.4 -

      -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: C:\TfsData\Agents\Agent-MACHINENAME_work\1\a -

      -This directory is purged before each new build, so you don't have to clean it up yourself. -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. See Artifacts in Azure Pipelines. -

      -In TFS 2015.4, Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. -

      -All versions of TFS 2015 -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.Repository.Git.SubmoduleCheckoutThe value you've selected for Checkout submodules on the repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.SourceTfvcShelvesetDefined if your repository is Team Foundation Version Control. -

      -If you are running a gated build or a shelveset build, this is set to the name of the shelveset you are building. -

      -Note: This variable yields a value that is invalid for build use in a build number format. -
      Common.TestResultsDirectoryThe local path on the agent where the test results are created. For example: c:\agent_work\1\TestResults. Available in TFS 2015.4. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      - -## System variables (TFS 2015) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      System.AccessTokenAvailable in TFS 2015.4. Use the OAuth token to access the REST API. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      System.CollectionIdThe GUID of the TFS collection or Azure DevOps organization
      System.DefaultWorkingDirectory - -[!INCLUDE [include](../includes/variables-build-sources-directory.md)] - -
      System.DefinitionIdThe ID of the build pipeline.
      System.HostTypeSet to build if the pipeline is a build or release if the pipeline is a release.
      System.PullRequest.PullRequestIdThe ID of the pull request that caused this build. For example: 17. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)
      System.PullRequest.SourceBranchThe branch that is being reviewed in a pull request. For example: refs/heads/users/raisa/new-feature. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)
      System.PullRequest.SourceRepositoryURIThe URL to the repo that contains the pull request. For example: http://our-server:8080/tfs/DefaultCollection/_git/OurProject. (This variable is initialized only if the build ran because of a Azure Repos Git PR affected by a branch policy.)
      System.PullRequest.TargetBranchThe branch that is the target of a pull request. For example: refs/heads/main. This variable is initialized only if the build ran because of a Git PR affected by a branch policy.
      System.TeamFoundationCollectionUriThe URI of the team foundation collection. For example: http://our-server:8080/tfs/DefaultCollection/. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      System.TeamProjectThe name of the project that contains this build.
      System.TeamProjectIdThe ID of the project that this build belongs to.
      TF_BUILDSet to True if the script is being run by a build task. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      diff --git a/docs/pipelines/build/includes/variables-tfs2017.md b/docs/pipelines/build/includes/variables-tfs2017.md deleted file mode 100644 index d2764282422..00000000000 --- a/docs/pipelines/build/includes/variables-tfs2017.md +++ /dev/null @@ -1,453 +0,0 @@ ---- -ms.topic: include -ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: jukullam -author: juliakm -ms.date: 02/13/2020 ---- - - -## Agent variables (TFS 2017) - -> [!NOTE] -> You can use agent variables as environment variables in your scripts and as parameters in your build tasks. -> You cannot use them to customize the build number or to apply a version control label or tag. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Agent.BuildDirectory -

      The local path on the agent where all folders for a given build pipeline are created.

      -

      For example: c:\agent_work\1

      -
      Agent.ComputerNameThe name of the machine on which the agent is installed.
      Agent.HomeDirectoryThe directory the agent is installed into. This contains the agent software. For example: c:\agent.
      Agent.IdThe ID of the agent.
      Agent.JobStatusThe status of the build. -
        -
      • Canceled -
      • Failed -
      • Succeeded -
      • SucceededWithIssues (partially successful) -
      -

      The environment variable should be referenced as AGENT_JOBSTATUS. The older agent.jobstatus is available for backwards compatibility.

      -
      Agent.Name -

      The name of the agent that is registered with the pool.

      -

      This name is specified by you. See agents.

      -
      Agent.WorkFolder -The working directory for this agent. -For example: c:\agent_work. -
      - -## Build variables (TFS 2017) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Build.ArtifactStagingDirectoryThe local path on the agent where any artifacts are copied to before being pushed to their destination. -

      - - -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent_work\1\a -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. -

      -Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself. -

      -See Artifacts in Azure Pipelines. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -
      Build.BuildIdThe ID of the record for the completed build.
      Build.BuildNumberThe name of the completed build. You can specify the build number format that generates this value in the pipeline options. -

      -A typical use of this variable is to make it part of the label format, which you specify on the repository tab. -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail. - -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as a version control tag. -
      Build.BuildUriThe URI for the build. For example: vstfs:///Build/Build/1430. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.BinariesDirectoryThe local path on the agent you can use as an output folder for compiled binaries. -

      -By default, new build pipelines are not set up to clean this directory. You can define your build to clean it up on the Repository tab. -

      -For example: c:\agent_work\1\b. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.DefinitionNameThe name of the build pipeline. - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail. - -
      Build.DefinitionVersionThe version of the build pipeline.
      Build.QueuedBySee "How are the identity variables set?". - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail. - -
      Build.QueuedByIdSee "How are the identity variables set?".
      Build.ReasonThe event that caused the build to run. Available in TFS 2017.3. -
        -
      • Manual: A user manually queued the build.
        • -
      • IndividualCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in.
        • -
      • BatchedCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in, and the Batch changes was selected.
        • -
      • Schedule: Scheduled trigger.
        • -
      • ValidateShelveset: A user manually queued the build of a specific TFVC shelveset.
        • -
      • CheckInShelveset: Gated check-in trigger.
        • -
      • PullRequest: The build was triggered by a Git branch policy that requires a build.
        • -
      -See Build pipeline triggers, Improve code quality with branch policies. -
      Build.Repository.CleanThe value you've selected for Clean in the source repository settings. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.Repository.LocalPath - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -

      This variable is synonymous with Build.SourcesDirectory.

      -
      Build.Repository.NameThe name of the repository. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.Repository.ProviderThe type of repository you selected. - -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.Repository.Tfvc.WorkspaceDefined if your repository is Team Foundation Version Control. The name of the TFVC workspace used by the build agent. -

      -For example, if the Agent.BuildDirectory is c:\agent_work\12 and the Agent.Id is 8, the workspace name could be: ws_12_8 -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.Repository.UriThe URL for the repository. For example: -
        -
      • Git: https://fabrikamfiber/tfs/DefaultCollection/Scripts/_git/Scripts -
      • TFVC: https://fabrikamfiber/tfs/DefaultCollection/ -
      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.RequestedForSee "How are the identity variables set?". - -[!INCLUDE [include](../includes/variables-invalid-label-characters.md)] - -
      Build.RequestedForEmailSee "How are the identity variables set?".
      Build.RequestedForIdSee "How are the identity variables set?".
      Build.SourceBranchThe branch the build was queued for. Some examples: -
        -
      • Git repo branch: refs/heads/master
        • -
      • Git repo pull request: refs/pull/1/merge
        • -
      • TFVC repo branch: $/teamproject/main
        • -
      • TFVC repo gated check-in: Gated_2016-06-06_05.20.51.4369;username@live.com
        • -
      • TFVC repo shelveset build: myshelveset;username@live.com
        • -
      -When you use this variable in your build number format, the forward slash characters (/) are replaced with underscore characters _). -

      -Note: In TFVC, if you are running a gated check-in build or manually building a shelveset, you cannot use this variable in your build number format. -
      Build.SourceBranchNameThe name of the branch the build was queued for. -
        -
      • Git repo branch or pull request: The last path segment in the ref. For example, in refs/heads/master this value is master. In refs/heads/feature/tools this value is tools.
        • -
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example in $/teamproject/main this value is main.
        • -
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, Gated_2016-06-06_05.20.51.4369;username@live.com or myshelveset;username@live.com.
        • -
      -Note: In TFVC, if you are running a gated check-in build or manually building a shelveset, you cannot use this variable in your build number format. -
      Build.SourcesDirectory - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -

      This variable is synonymous with Build.Repository.LocalPath.

      -
      Build.SourceVersionThe latest version control change that is included in this build. - -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.SourceVersionMessageThe comment of the commit or changeset. We truncate the message to the first line or 200 characters, whichever is shorter. - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -Note: This variable is available in TFS 2015.4. - -> [!NOTE] -> The **Build.SourceVersionMessage** variable does not work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. -
      Build.StagingDirectory - - -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent_work\1\a -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. -

      -Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself. -

      -See Artifacts in Azure Pipelines. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -
      Build.Repository.Git.SubmoduleCheckoutThe value you've selected for Checkout submodules on the repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.SourceTfvcShelvesetDefined if your repository is Team Foundation Version Control. -

      -If you are running a gated build or a shelveset build, this is set to the name of the shelveset you are building. -

      -Note: This variable yields a value that is invalid for build use in a build number format. -
      Common.TestResultsDirectoryThe local path on the agent where the test results are created. For example: c:\agent_work\1\TestResults -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      - -## System variables (TFS 2017) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      System.AccessTokenUse the OAuth token to access the REST API.
      System.CollectionIdThe GUID of the TFS collection or Azure DevOps organization
      System.DefaultWorkingDirectory - -[!INCLUDE [include](../includes/variables-build-sources-directory.md)] - -
      System.DefinitionIdThe ID of the build pipeline.
      System.HostTypeSet to build if the pipeline is a build or release if the pipeline is a release.
      System.PullRequest.PullRequestIdThe ID of the pull request that caused this build. For example: 17. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)
      System.PullRequest.SourceBranchThe branch that is being reviewed in a pull request. For example: refs/heads/users/raisa/new-feature. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)
      System.PullRequest.SourceRepositoryURIThe URL to the repo that contains the pull request. For example: http://our-server:8080/tfs/DefaultCollection/_git/OurProject. (This variable is initialized only if the build ran because of a Azure Repos Git PR affected by a branch policy.)
      System.PullRequest.TargetBranchThe branch that is the target of a pull request. For example: refs/heads/master. This variable is initialized only if the build ran because of a Git PR affected by a branch policy.
      System.TeamFoundationCollectionUriThe URI of the team foundation collection. For example: http://our-server:8080/tfs/DefaultCollection/. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      System.TeamProjectThe name of the project that contains this build.
      System.TeamProjectIdThe ID of the project that this build belongs to.
      TF_BUILDSet to True if the script is being run by a build task. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      \ No newline at end of file diff --git a/docs/pipelines/build/includes/variables-tfs2018.md b/docs/pipelines/build/includes/variables-tfs2018.md index 9750e89ffb2..b331c39ddef 100644 --- a/docs/pipelines/build/includes/variables-tfs2018.md +++ b/docs/pipelines/build/includes/variables-tfs2018.md @@ -15,461 +15,71 @@ ms.date: 06/29/2023 > You can use agent variables as environment variables in your scripts and as parameters in your build tasks. > You cannot use them to customize the build number or to apply a version control label or tag. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Agent.BuildDirectory -

      The local path on the agent where all folders for a given build pipeline are created.

      -

      For example: c:\agent_work\1

      -
      Agent.HomeDirectoryThe directory the agent is installed into. This contains the agent software. For example: c:\agent.
      Agent.IdThe ID of the agent.
      Agent.JobStatusThe status of the build. -
        -
      • Canceled -
      • Failed -
      • Succeeded -
      • SucceededWithIssues (partially successful) -
      -

      The environment variable should be referenced as AGENT_JOBSTATUS. The older agent.jobstatus is available for backwards compatibility.

      -
      Agent.MachineNameThe name of the machine on which the agent is installed.
      Agent.Name -

      The name of the agent that is registered with the pool.

      -

      This name is specified by you. See agents.

      -
      Agent.TempDirectory -A temporary folder that is cleaned after each pipeline job. This directory is used by tasks such as .NET Core CLI task to hold temporary items like test results before they're published. -
      Agent.ToolsDirectory -The directory used by tasks such as Node Tool Installer and Use Python Version to switch between multiple versions of a tool. -These tasks add tools from this directory to PATH so that subsequent build steps can use them. -

      -Learn about managing this directory on a self-hosted agent. -
      Agent.WorkFolder -The working directory for this agent. -For example: c:\agent_work. -
      +| Variable | Description | +|:---------|:------------| +| Agent.BuildDirectory | The local path on the agent where all folders for a given build pipeline are created. For example: `c:\agent_work\1`. | +| Agent.HomeDirectory | The directory the agent is installed into. This contains the agent software. For example: `c:\agent`. | +| Agent.Id | The ID of the agent. | +| Agent.JobStatus | The status of the build.
      • `Canceled`
      • `Failed`
      • `Succeeded`
      • `SucceededWithIssues` (partially successful)
      The environment variable should be referenced as `AGENT_JOBSTATUS`. The older `agent.jobstatus` is available for backwards compatibility. | +| Agent.MachineName | The name of the machine on which the agent is installed. | +| Agent.Name | The name of the agent that is registered with the pool.

      This name is specified by you. See [agents](../../agents/agents.md). | +| Agent.TempDirectory | A temporary folder that is cleaned after each pipeline job. This directory is used by tasks such as [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) to hold temporary items like test results before they're published. | +| Agent.ToolsDirectory | The directory used by tasks such as [Node Tool Installer](/azure/devops/pipelines/tasks/reference/node-tool-v0) and [Use Python Version](/azure/devops/pipelines/tasks/reference/use-python-version-v0) to switch between multiple versions of a tool.

      These tasks add tools from this directory to `PATH` so that subsequent build steps can use them.

      Learn about [managing this directory on a self-hosted agent](https://go.microsoft.com/fwlink/?linkid=2008884). | +| Agent.WorkFolder | The working directory for this agent. For example: `c:\agent_work`. | ## Build variables (TFS 2018) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      Build.ArtifactStagingDirectoryThe local path on the agent where any artifacts are copied to before being pushed to their destination. -

      - - -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent_work\1\a -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. -

      -Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself. -

      -See Artifacts in Azure Pipelines. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -
      Build.BuildIdThe ID of the record for the completed build.
      Build.BuildNumberThe name of the completed build. You can specify the build number format that generates this value in the pipeline options. -

      -A typical use of this variable is to make it part of the label format, which you specify on the repository tab. -

      - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. - -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as a version control tag. -
      Build.BuildUriThe URI for the build. For example: vstfs:///Build/Build/1430. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.BinariesDirectoryThe local path on the agent you can use as an output folder for compiled binaries. -

      -By default, new build pipelines aren't set up to clean this directory. You can define your build to clean it up on the Repository tab. -

      -For example: c:\agent_work\1\b. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.DefinitionNameThe name of the build pipeline. - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails. -
      Build.DefinitionVersionThe version of the build pipeline.
      Build.QueuedBySee "How are the identity variables set?". - - -Note: This value can contain whitespace or other invalid label characters. In these cases, the label format fails.
      Build.QueuedByIdSee "How are the identity variables set?".
      Build.ReasonThe event that caused the build to run. -
        -
      • Manual: A user manually queued the build from the UI or an API call.
        • -
      • IndividualCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in.
        • -
      • BatchedCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in, and the Batch changes was selected.
        • -
      • Schedule: Scheduled trigger.
        • -
      • ValidateShelveset: A user manually queued the build of a specific TFVC shelveset.
        • -
      • CheckInShelveset: Gated check-in trigger.
        • -
      • PullRequest: The build was triggered by a Git branch policy that requires a build.
        • -
      -See Build pipeline triggers, Improve code quality with branch policies. -
      Build.Repository.CleanThe value you've selected for Clean in the source repository settings. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.Repository.LocalPath - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -

      This variable is synonymous with Build.SourcesDirectory.

      -
      Build.Repository.NameThe name of the repository. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.Repository.ProviderThe type of repository you selected. - -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.Repository.Tfvc.WorkspaceDefined if your repository is Team Foundation Version Control. The name of the TFVC workspace used by the build agent. -

      -For example, if the Agent.BuildDirectory is c:\agent_work\12 and the Agent.Id is 8, the workspace name could be: ws_12_8 -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.Repository.UriThe URL for the repository. For example: -
        -
      • Git: https://fabrikamfiber/tfs/DefaultCollection/Scripts/_git/Scripts -
      • TFVC: https://fabrikamfiber/tfs/DefaultCollection/ -
      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.RequestedForSee "How are the identity variables set?". - -[!INCLUDE [include](../includes/variables-invalid-label-characters.md)] - -
      Build.RequestedForEmailSee "How are the identity variables set?".
      Build.RequestedForIdSee "How are the identity variables set?".
      Build.SourceBranchThe branch the build was queued for. Some examples: -
        -
      • Git repo branch: refs/heads/main
        • -
      • Git repo pull request: refs/pull/1/merge
        • -
      • TFVC repo branch: $/teamproject/main
        • -
      • TFVC repo gated check-in: Gated_2016-06-06_05.20.51.4369;username@live.com
        • -
      • TFVC repo shelveset build: myshelveset;username@live.com
        • -
      -When you use this variable in your build number format, the forward slash characters (/) are replaced with underscore characters _). -

      -Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. -
      Build.SourceBranchNameThe name of the branch the build was queued for. -
        -
      • Git repo branch, pull request, or tag: The last path segment in the ref. For example, in refs/heads/main this value is main. In refs/heads/feature/tools this value is tools.
        • -
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example in $/teamproject/main this value is main. In refs/tags/your-tag-name this value is your-tag-name.
        • -
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, Gated_2016-06-06_05.20.51.4369;username@live.com or myshelveset;username@live.com.
        • -
      -Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. -
      Build.SourcesDirectory - - -The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -

      This variable is synonymous with Build.Repository.LocalPath.

      -
      Build.SourceVersionThe latest version control change that is included in this build. - -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. -
      Build.SourceVersionMessageThe comment of the commit or changeset. We truncate the message to the first line or 200 characters, whichever is shorter. - -This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -Note: This variable is available in TFS 2015.4. - -> [!NOTE] -> The **Build.SourceVersionMessage** variable does not work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. -
      Build.StagingDirectory - - -The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent_work\1\a -

      -A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. -

      -Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself. -

      -See Artifacts in Azure Pipelines. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. - -
      Build.Repository.Git.SubmoduleCheckoutThe value you've selected for Checkout submodules on the repository tab. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      Build.SourceTfvcShelvesetDefined if your repository is Team Foundation Version Control. -

      -If you're running a gated build or a shelveset build, this is set to the name of the shelveset you are building. -

      -Note: This variable yields a value that is invalid for build use in a build number format. -
      Common.TestResultsDirectoryThe local path on the agent where the test results are created. For example: c:\agent_work\1\TestResults -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      +| Variable | Description | +|:---------|:------------| +| Build.ArtifactStagingDirectory | The local path on the agent where any artifacts are copied to before being pushed to their destination.

      The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: `c:\agent_work\1\a`.

      A typical way to use this folder is to publish your build artifacts with the [Copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish build artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks.

      Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

      See [Artifacts in Azure Pipelines](../../artifacts/artifacts-overview.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.BuildId | The ID of the record for the completed build. | +| Build.BuildNumber | The name of the completed build. You can specify the build number format that generates this value in the [pipeline options](../options.md).

      A typical use of this variable is to make it part of the label format, which you specify on the [repository tab](../../repos/index.md).

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as a version control tag. | +| Build.BuildUri | The URI for the build. For example: `vstfs:///Build/Build/1430`.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.BinariesDirectory | The local path on the agent you can use as an output folder for compiled binaries.

      By default, new build pipelines aren't set up to clean this directory. You can define your build to clean it up on the [Repository tab](../../repos/index.md).

      For example: `c:\agent_work\1\b`.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.DefinitionName | The name of the build pipeline.

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | +| Build.DefinitionVersion | The version of the build pipeline. | +| Build.QueuedBy | See "[How are the identity variables set?](#identity_values)".

      Note: This value can contain whitespace or other invalid label characters. In these cases, the [label format](../../../repos/tfvc/labels-command.md) fails. | +| Build.QueuedById | See "[How are the identity variables set?](#identity_values)". | +| Build.Reason | The event that caused the build to run.
      • `Manual`: A user manually queued the build from the UI or an API call.
      • `IndividualCI`: **Continuous integration (CI)** triggered by a Git push or a TFVC check-in.
      • `BatchedCI`: **Continuous integration (CI)** triggered by a Git push or a TFVC check-in, and the **Batch changes** was selected.
      • `Schedule`: **Scheduled** trigger.
      • `ValidateShelveset`: A user manually queued the build of a specific TFVC shelveset.
      • `CheckInShelveset`: **Gated check-in** trigger.
      • `PullRequest`: The build was triggered by a Git branch policy that requires a build.
      See [Build pipeline triggers](../triggers.md), [Improve code quality with branch policies](../../../repos/git/branch-policies.md). | +| Build.Repository.Clean | The value you've selected for **Clean** in the [source repository settings](../../repos/index.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.Repository.LocalPath | The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`.

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the [Repository tab](../../repos/index.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.

      This variable is synonymous with Build.SourcesDirectory. | +| Build.Repository.Name | The name of the [repository](../../repos/index.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.Repository.Provider | The type of [repository you selected](../../repos/index.md).
      • `TfsGit`: [TFS Git repository](../../../repos/git/index.yml)
      • `TfsVersionControl`: [Team Foundation Version Control](../../../repos/tfvc/what-is-tfvc.md)
      • `Git`: Git repository hosted on an external server
      • `Svn`: Subversion
      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.Repository.Tfvc.Workspace | Defined if your [repository](../../repos/index.md) is Team Foundation Version Control. The name of the [TFVC workspace](../../../repos/tfvc/create-work-workspaces.md) used by the build agent.

      For example, if the Agent.BuildDirectory is `c:\agent_work\12` and the Agent.Id is `8`, the workspace name could be: `ws_12_8`.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.Repository.Uri | The URL for the repository. For example:
      • Git: `https://fabrikamfiber/tfs/DefaultCollection/Scripts/_git/Scripts`
      • TFVC: `https://fabrikamfiber/tfs/DefaultCollection/`
      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.RequestedFor | See "[How are the identity variables set?](#identity_values)".

      [!INCLUDE [include](../includes/variables-invalid-label-characters.md)] | +| Build.RequestedForEmail | See "[How are the identity variables set?](#identity_values)". | +| Build.RequestedForId | See "[How are the identity variables set?](#identity_values)". | +| Build.SourceBranch | The branch the build was queued for. Some examples:
      • Git repo branch: `refs/heads/main`
      • Git repo pull request: `refs/pull/1/merge`
      • TFVC repo branch: `$/teamproject/main`
      • TFVC repo gated check-in: `Gated_2016-06-06_05.20.51.4369;username@live.com`
      • TFVC repo shelveset build: `myshelveset;username@live.com`
      When you use this variable in your build number format, the forward slash characters (`/`) are replaced with underscore characters (`_`).

      Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. | +| Build.SourceBranchName | The name of the branch the build was queued for.
      • Git repo branch, pull request, or tag: The last path segment in the ref. For example, in `refs/heads/main` this value is `main`. In `refs/heads/feature/tools` this value is `tools`.
      • TFVC repo branch: The last path segment in the root server path for the workspace. For example in `$/teamproject/main` this value is `main`. In `refs/tags/your-tag-name` this value is `your-tag-name`.
      • TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, `Gated_2016-06-06_05.20.51.4369;username@live.com` or `myshelveset;username@live.com`.
      Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. | +| Build.SourcesDirectory | The local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`.

      By default, new build pipelines update only the changed files. You can modify how files are downloaded on the [Repository tab](../../repos/index.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.

      This variable is synonymous with Build.Repository.LocalPath. | +| Build.SourceVersion | The latest version control change that is included in this build.
      • Git: The [commit](../../../repos/git/commits.md) ID.
      • TFVC: the [changeset](../../../repos/tfvc/find-view-changesets.md).
      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.SourceVersionMessage | The comment of the commit or changeset. We truncate the message to the first line or 200 characters, whichever is shorter.

      This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.

      Note: This variable is available in TFS 2015.4.

      Note: The **Build.SourceVersionMessage** variable does not work with classic build pipelines in Bitbucket repositories when **Batch changes while a build is in progress** is enabled. | +| Build.StagingDirectory | The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: `c:\agent_work\1\a`.

      A typical way to use this folder is to publish your build artifacts with the [Copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish build artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks.

      Note: Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

      See [Artifacts in Azure Pipelines](../../artifacts/artifacts-overview.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.Repository.Git.SubmoduleCheckout | The value you've selected for **Checkout submodules** on the [repository tab](../../repos/index.md).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| Build.SourceTfvcShelveset | Defined if your [repository](../../repos/index.md) is Team Foundation Version Control.

      If you're running a [gated build](../../repos/tfvc.md#gated) or a [shelveset build](../../create-first-pipeline.md#queueabuild), this is set to the name of the [shelveset](../../../repos/tfvc/suspend-your-work-manage-your-shelvesets.md) you are building.

      Note: This variable yields a value that is invalid for build use in a build number format. | +| Common.TestResultsDirectory | The local path on the agent where the test results are created. For example: `c:\agent_work\1\TestResults`.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | ## System variables (TFS 2018) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      VariableDescription
      System.AccessTokenUse the OAuth token to access the REST API. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      System.CollectionIdThe GUID of the TFS collection or Azure DevOps organization
      System.DefaultWorkingDirectory - -[!INCLUDE [include](../includes/variables-build-sources-directory.md)] - -
      System.DefinitionIdThe ID of the build pipeline.
      System.HostTypeSet to build if the pipeline is a build or release if the pipeline is a release.
      System.PullRequest.IsForkIf the pull request is from a fork of the repository, this variable is set to True. -Otherwise, it's set to False. Available in TFS 2018.2.
      System.PullRequest.PullRequestIdThe ID of the pull request that caused this build. For example: 17. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)
      System.PullRequest.SourceBranchThe branch that is being reviewed in a pull request. For example: refs/heads/users/raisa/new-feature. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)
      System.PullRequest.SourceRepositoryURIThe URL to the repo that contains the pull request. For example: http://our-server:8080/tfs/DefaultCollection/_git/OurProject. (This variable is initialized only if the build ran because of a Azure Repos Git PR affected by a branch policy.)
      System.PullRequest.TargetBranchThe branch that is the target of a pull request. For example: refs/heads/main. This variable is initialized only if the build ran because of a Git PR affected by a branch policy.
      System.TeamFoundationCollectionUriThe URI of the team foundation collection. For example: http://our-server:8080/tfs/DefaultCollection/. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      System.TeamProjectThe name of the project that contains this build.
      System.TeamProjectIdThe ID of the project that this build belongs to.
      TF_BUILDSet to True if the script is being run by a build task. -

      -This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
      +| Variable | Description | +|:---------|:------------| +| System.AccessToken | [Use the OAuth token to access the REST API](../../scripts/powershell.md#example-powershell-script-access-rest-api).

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| System.CollectionId | The GUID of the TFS collection or Azure DevOps organization | +| System.DefaultWorkingDirectory | [!INCLUDE [include](../includes/variables-build-sources-directory.md)] | +| System.DefinitionId | The ID of the build pipeline. | +| System.HostType | Set to `build` if the pipeline is a build or `release` if the pipeline is a release. | +| System.PullRequest.IsFork | If the pull request is from a fork of the repository, this variable is set to `True`. Otherwise, it's set to `False`. Available in **TFS 2018.2**. | +| System.PullRequest.PullRequestId | The ID of the pull request that caused this build. For example: `17`. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation).) | +| System.PullRequest.SourceBranch | The branch that is being reviewed in a pull request. For example: `refs/heads/users/raisa/new-feature`. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation).) | +| System.PullRequest.SourceCommitId | The commit that is being reviewed in a pull request. (This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation).) | +| System.PullRequest.SourceRepositoryURI | The URL to the repo that contains the pull request. For example: `http://our-server:8080/tfs/DefaultCollection/_git/OurProject`. (This variable is initialized only if the build ran because of a [Azure Repos Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation).) | +| System.PullRequest.TargetBranch | The branch that is the target of a pull request. For example: `refs/heads/main`. This variable is initialized only if the build ran because of a [Git PR affected by a branch policy](../../../repos/git/branch-policies.md#build-validation). | +| System.TeamFoundationCollectionUri | The URI of the team foundation collection. For example: `http://our-server:8080/tfs/DefaultCollection/`.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | +| System.TeamProject | The name of the project that contains this build. | +| System.TeamProjectId | The ID of the project that this build belongs to. | +| TF_BUILD | Set to `True` if the script is being run by a build task.

      This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. | diff --git a/docs/pipelines/build/media/tags/add-tag-more-actions.png b/docs/pipelines/build/media/tags/add-tag-more-actions.png new file mode 100644 index 00000000000..f40210337cf Binary files /dev/null and b/docs/pipelines/build/media/tags/add-tag-more-actions.png differ diff --git a/docs/pipelines/build/media/tags/add-tag-name.png b/docs/pipelines/build/media/tags/add-tag-name.png new file mode 100644 index 00000000000..a0d6f5f7e3b Binary files /dev/null and b/docs/pipelines/build/media/tags/add-tag-name.png differ diff --git a/docs/pipelines/build/media/tags/filter-tag.png b/docs/pipelines/build/media/tags/filter-tag.png new file mode 100644 index 00000000000..16cc65c9c13 Binary files /dev/null and b/docs/pipelines/build/media/tags/filter-tag.png differ diff --git a/docs/pipelines/build/media/tags/remove-build-tag.png b/docs/pipelines/build/media/tags/remove-build-tag.png new file mode 100644 index 00000000000..d355f731050 Binary files /dev/null and b/docs/pipelines/build/media/tags/remove-build-tag.png differ diff --git a/docs/pipelines/build/media/tags/select-pipeline.png b/docs/pipelines/build/media/tags/select-pipeline.png new file mode 100644 index 00000000000..5fe62d7c951 Binary files /dev/null and b/docs/pipelines/build/media/tags/select-pipeline.png differ diff --git a/docs/pipelines/build/migrate-from-xaml-builds.md b/docs/pipelines/build/migrate-from-xaml-builds.md deleted file mode 100644 index 2ae0cf77dc6..00000000000 --- a/docs/pipelines/build/migrate-from-xaml-builds.md +++ /dev/null @@ -1,381 +0,0 @@ ---- -title: Migrate from XAML builds -ms.custom: seodec18 -description: How to migrate from XAML builds to new builds in your Azure Pipelines or Team Foundation Server (TFS) -ms.topic: conceptual -ms.assetid: 77D7057E-FE9B-4DF8-89CC-244E2A38CA35 -ms.date: 04/17/2018 -monikerRange: '<= azure-devops' ---- - -# Migrate from XAML builds to new builds - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - -We introduced XAML build automation capabilities based on the Windows Workflow Foundation in Team Foundation Server (TFS) 2010. We released another version of [XAML builds](/previous-versions/visualstudio/visual-studio-2013/ms181709(v=vs.120)) in TFS 2013. - -After that we sought to expand beyond .NET and Windows and add support for other kinds of apps that are based on operating systems such as macOS and Linux. It became clear that we needed to switch to a more open, flexible, web-based foundation for our build automation engine. In early 2015 in Azure Pipelines, and then in TFS 2015, we introduced a simpler task- and script-driven cross-platform build system. - -Because the systems are so different, there's no automated or general way to migrate a XAML build pipeline into a new build pipeline. The migration process is to manually create the new build pipelines that replicate what your XAML builds do. - -If you're building standard .NET applications, you probably used our default templates as provided out-of-the-box. In this case the process should be reasonably easy. - -If you have customized your XAML templates or added custom tasks, then you'll need to also take other steps including writing scripts, installing extensions, or creating custom tasks. - -## Overview of the migration effort - -Here are the steps to migrate from XAML builds to newer builds: - -1. If you're using a private TFS server, [set up agents](../agents/windows-agent.md) to run your builds. - -2. To get familiar with the new build system, create a ["Hello world" build pipeline](../create-first-pipeline.md). - -3. Create a new build pipeline intended to replace one of your XAML build pipelines. - - 1. Create a new build pipeline. - - 1. Port your XAML settings. - -4. On the [General tab](#general-tab), disable the XAML build pipeline. - -5. Repeat the previous two steps for each of your XAML build pipelines. - -6. Take advantage of new build features and learn more about the kinds of apps you can build. - -7. Learn how to customize, and if necessary extend your system. - -8. When you no longer need the history and artifacts from your XAML builds, delete the XAML builds, and then the XAML build pipelines. - - > [!WARNING] - > After you delete the XAML builds and pipelines, you cannot get them back. - -## Create new build pipelines - -If you're building a standard .NET app, you're probably using one of the out-of-the-box build templates such as TfvcTemplate.12.xaml or GitTemplate.12.xaml. In this case, it will probably just take you a few clicks to create build pipelines in the new build system. - -
        - - -

      1. Open your project in your web browser

        -Browse to project - -

        (If you don't see your project listed on the home page, select Browse.)

        -
          -
        • On-premises TFS: http://{your_server}:8080/tfs/DefaultCollection/{your_project}
          • -
        • Azure Pipelines: https://dev.azure.com/{your_organization}/{your_project}
          • -
        -

        The TFS URL doesn't work for me. How can I get the correct URL?

        -
        2. - -

      2. Create a build pipeline (Pipelines tab > Builds)

        -Build tab -

        -

        3. - -
      3. Select a template to add commonly used tasks to your build pipeline.
        4. - -
      4. Make any necessary changes to your build pipeline to replicate your XAML build pipeline. The tasks added by the template should simply work in many cases. But if you changed process parameters or other settings in your XAML build pipelines, below are some pointers to get you started replicating those changes.
        5. -
      - -## Port your XAML settings - -In each of the following sections we show the XAML user interface, and then provide a pointer to the place where you can port the setting into your new build pipeline. - -### General tab - -![xaml build general tab](media/migrate-from-xaml-builds/xaml-build-general-tab.png) - -| XAML setting | TFS 2017 equivalent | Azure Pipelines and TFS 2018 and newer equivalent | -|-|-|-| -| Build pipeline name | You can change it whenever you save the pipeline. |

      When editing the pipeline: On the **Tasks** tab, in left pane click **Pipeline**, and the **Name** field appears in right pane.

      In the **Builds** hub (**Mine** or **All pipelines** tab), open the action menu and choose **Rename**.

      | -| Description (optional) | Not supported. | Not supported. | -| Queue processing | Not yet supported. As a partial alternative, disable the triggers. | Not yet supported. As an alternative, disable the triggers. | - -### Source Settings tab - -#### TFVC - -![xaml build source settings tfvc](media/migrate-from-xaml-builds/xaml-build-source-settings-tfvc.png) - -| XAML setting | TFS 2017 and newer equivalent | Azure Pipelines equivalent | -|-|-|-| -| Source Settings tab | On the **Repository** tab specify your mappings with Active paths as **Map** and Cloaked paths as **Cloak**. | On the **Tasks** tab, in left pane click **Get sources**. Specify your workspace mappings with Active paths as **Map** and Cloaked paths as **Cloak**. | - -The new build pipeline offers you some new options. The specific extra options you'll see depend on the version you're using of TFS or Azure Pipelines. If you're using Azure Pipelines, first make sure to display **Advanced settings**. See [Build TFVC repositories](../repos/tfvc.md). - -#### Git - -![xaml build source settings git tfs](media/migrate-from-xaml-builds/xaml-build-source-settings-git-tfs.png) - -| XAML setting | TFS 2017 and newer equivalent | Azure Pipelines equivalent | -|-|-|-| -| Source Settings tab | On the **Repository** tab specify the repository and default branch. | On the **Tasks** tab, in left pane click **Get sources**. Specify the repository and default branch. | - -The new build pipeline offers you some new options. The specific extra options you'll see depend on the version you're using of TFS or Azure Pipelines. If you're using Azure Pipelines, first make sure to display **Advanced settings**. See [Pipeline options for Git repositories](../repos/pipeline-options-for-git.md). - -### Trigger tab - -![xaml build trigger tab](media/migrate-from-xaml-builds/xaml-build-trigger-tab.png) - -| XAML setting | TFS 2017 and newer, Azure Pipelines equivalent | -|-|-| -|Trigger tab | On the **Triggers** tab, select the trigger you want to use: CI, scheduled, or gated. | - -The new build pipeline offers you some new options. For example: - -* You can potentially create fewer build pipelines to replace a larger number of XAML build pipelines. This is because you can use a single new build pipeline with multiple triggers. And if you're using Azure Pipelines, then you can add multiple scheduled times. - -* The **Rolling builds** option is replaced by the **Batch changes** option. You can't specify minimum time between builds. But if you're using Azure Pipelines, you can specify the maximum number of parallel jobs per branch. - -* If your code is in TFVC, you can add folder path filters to include or exclude certain sets of files from triggering a CI build. - -* If your code is in TFVC and you're using the gated check-in trigger, you've got the option to also run CI builds or not. You can also use the same workspace mappings as your repository settings, or specify different mappings. - -* If your code is in Git, then you specify the branch filters directly on the **Triggers** tab. And you can add folder path filters to include or exclude certain sets of files from triggering a CI build. - -The specific extra options you'll see depend on the version you're using of TFS or Azure Pipelines. See [Build pipeline triggers](../build/triggers.md) - -We don't yet support the **Build even if nothing has changed since the previous build** option. - -### Build Defaults tab - -![xaml build build defaults tab](media/migrate-from-xaml-builds/xaml-build-build-defaults-tab.png) - -| XAML process parameter | TFS 2017 and newer equivalent | Azure Pipelines equivalent | -|-|-|-| -| Build controller | On the **General** tab, select the default agent pool. | On the **Options** tab, select the default agent pool. | -| Staging location | On the **Tasks** tab, specify arguments to the Copy Files and Publish Build Artifacts tasks. See [Build artifacts](../artifacts/pipeline-artifacts.md). | On the **Tasks** tab, specify arguments to the Copy Files and Publish Build Artifacts tasks. See [Build artifacts](../artifacts/pipeline-artifacts.md). | - -The new build pipeline offers you some new options. For example: - -* You don't need a controller, and the new agents are easier to set up and maintain. See [Build and release agents](../agents/agents.md). - -* You can exactly specify which sets of files you want to publish as build artifacts. See [Build artifacts](../artifacts/pipeline-artifacts.md). - -### Process tab - -#### TF Version Control - -![XAML source settings, TFVC.](media/migrate-from-xaml-builds/xaml-build-template-12-tf-version-control.png) - -| XAML process parameter | TFS 2017 and newer equivalent | Azure Pipelines equivalent | -|-|-|-| -| Clean workspace | On the **Repository** tab, open the **Clean** menu, and then select **true**. | On the **Tasks** tab, in left pane click **Get sources**. Display **Advanced settings**, and then select **Clean**. (We plan to move this option out of advanced settings.) | -| Get version | You can't specify a changeset in the build pipeline, but you can specify one when you manually queue a build. | You can't specify a changeset in the build pipeline, but you can specify one when you manually queue a build. | -| Label Sources | On the **Repository** tab, select an option from the **Label sources** menu. | **Tasks** tab, in left pane click **Get sources**. Select one of the **Tag sources** options. (We plan to change the name of this to **Label sources**.) | - -The new build pipeline offers you some new options. See [Build TFVC repositories](../repos/tfvc.md). - -#### Git - -![XAML source settings, Git.](media/migrate-from-xaml-builds/git-template-12-xaml-git.png) - -| XAML process parameter | TFS 2017 and newer equivalent | Azure Pipelines equivalent | -|-|-|-| -| Clean repository | **Repository** tab, open **Clean** menu, select **true**. | On the **Tasks** tab, in left pane click **Get sources**. Show **Advanced settings**, and then select **Clean**. (We plan to move this option out of advanced settings.) | -| Checkout override | You can't specify a commit in the build pipeline, but you can specify one when you manually queue a build. | You can't specify a commit in the build pipeline, but you can specify one when you manually queue a build. | - -The new build pipeline offers you some new options. See [Pipeline options for Git repositories](../repos/pipeline-options-for-git.md). - -#### Build - -![XAML source settings, Build.](media/migrate-from-xaml-builds/xaml-build-template-12-build.png) - -On the **Build** tab (TFS 2017 and newer) or the **Tasks** tab (Azure Pipelines), after you select the Visual Studio Build task, you'll see the arguments that are equivalent to the XAML build parameters. - -| XAML process parameter | TFS 2017 and newer, Azure Pipelines equivalent argument | -|-|-| -| Projects | Solution | -| Configurations | Platform, Configuration. See [Visual Studio Build: How do I build multiple configurations for multiple platforms?](../tasks/build/visual-studio-build.md#how-do-i-build-multiple-configurations-for-multiple-platforms) | -| Clean build | Clean | -| Output location | The Visual Studio Build task builds and outputs files in the same way you do it on your dev machine, in the local workspace. We give you full control of publishing artifacts out of the local workspace on the agent. See [Artifacts in Azure Pipelines](../artifacts/pipeline-artifacts.md). | -| Advanced, MSBuild arguments | MSBuild Arguments | -| Advanced, MSBuild platform | Advanced, MSBuild Architecture | -| Advanced, Perform code analysis | Use an MSBuild argument such as`/p:RunCodeAnalysis=true` | -| Advanced, post- and pre-build scripts | You can run one or more scripts at any point in your build pipeline by adding one or more instances of the PowerShell, Batch, and Command tasks. For example, see [Use a PowerShell script to customize your build pipeline](../scripts/powershell.md). | - -> [!IMPORTANT] -> -> In the Visual Studio Build arguments, on the **Visual Studio Version** menu, make sure to select version of Visual Studio that you're using. - -The new build pipeline offers you some new options. See [Visual Studio Build](/azure/devops/pipelines/tasks/reference/vsbuild-v1). - -Learn more: [Visual Studio Build task](/azure/devops/pipelines/tasks/reference/vsbuild-v1) (for building solutions), [MSBuild task](/azure/devops/pipelines/tasks/reference/msbuild-v1) (for building individual projects). - -#### Test - -![XAML source settings, Test.](media/migrate-from-xaml-builds/xaml-build-template-12-test.png) - -See [continuous testing](../ecosystems/dotnet-core.md#run-your-tests) and [Visual Studio Test task](/azure/devops/pipelines/tasks/reference/vstest-v2). - -#### Publish Symbols - -![XAML source settings, Publish.](media/migrate-from-xaml-builds/xaml-build-template-12-publish-symbols.png) - -| XAML process parameter | TFS 2017 and newer, Azure Pipelines equivalent | -|-|-| -| Path to publish symbols | Click the Publish Symbols task and then copy the path into the **Path to publish symbols** argument. | - -#### Advanced - -![XAML source settings, Advanced.](media/migrate-from-xaml-builds/xaml-build-template-12-advanced.png) - -| XAML process parameter | TFS 2017 and newer equivalent| Azure Pipelines equivalent | -|-|-|-| -| Maximum agent execution time | None | On the **Options** tab you can specify **Build job timeout in minutes**. | -| Maximum agent reservation wait time | None | None | -| Name filter, Tag comparison operator, Tags filter | A build pipeline asserts demands that are matched with agent capabilities. See [Agent capabilities](../agents/agents.md#capabilities). | A build pipeline asserts demands that are matched with agent capabilities. See [Agent capabilities](../agents/agents.md#capabilities). | -| Build number format | On the **General** tab, copy your build number format into the **Build number format** field. | On the **General** tab, copy your build number format into the **Build number format** field. | -| Create work item on failure | On the **Options** tab, select this check box. | On the **Options** tab, enable this option. | -| Update work items with build number | None | On the **Options** tab you can enable **Automatically link new work in this build**. | - -The new build pipeline offers you some new options. See: - -* [Agent capabilities](../agents/agents.md#capabilities) - -* [Build number format](../process/run-number.md) - -### Retention Policy tab - -![xaml build retention policy tab](media/migrate-from-xaml-builds/xaml-build-retention-policy-tab.png) - -| XAML process parameter | TFS 2017 and newer, Azure Pipelines equivalent | -|-|-| -| Retention Policy tab | On the **Retention** tab specify the policies you want to implement. | - -The new build pipeline offers you some new options. See [Build and release retention policies](../policies/retention.md). - -## Build and release different kinds of apps - -In XAML builds you had to create your own custom templates to build different types of apps. In the new build system you can pick from a set of predefined templates. The largest and most current set of templates are available on Azure Pipelines and in our newest version of TFS. - -### Build - -Here are a few examples of the kinds of apps you can build: - -* [Build your ASP.NET 4 app](../apps/aspnet/build-aspnet-4.md). - -* Build your ASP.NET Core app - -* [Build your Universal Windows Platform app](/previous-versions/azure/devops/pipelines/apps/windows/universal) - -* [Build your Xamarin app](../ecosystems/xamarin.md) - -* [C++ apps for Windows](../apps/windows/cpp.md) - -### Release - -The new build system is tightly integrated with Azure Pipelines. So it's easier than ever to automatically kick-off a deployment after a successful build. Learn more: - -* [Create your first pipeline](../create-first-pipeline.md) - -* [Release pipelines](../release/index.md) - -* [Triggers](../release/triggers.md) - -A few examples include: - -* [Continuous deployment of your app to an Azure web site](../apps/cd/deploy-webdeploy-webapps.md) - -* [IIS using deployment groups](../apps/cd/deploy-webdeploy-iis-deploygroups.md) - -### Other apps and tasks - -For more examples of apps you can build and deploy, see [Build and deploy your app](/previous-versions/azure/devops/pipelines/apps/). - -For a complete list of our build, test, and deployment tasks, see [Build and release tasks](../tasks/index.md). - -## Customize your tasks - -In XAML builds you created custom XAML tasks. In the new builds, you've got a range of options that begin with easier and lighter-weight approaches. - -### Get tasks from the Marketplace - -[Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops) -offers hundreds of extensions that you can install to add tasks that extend your build and deployment capabilities. - -### Write a script - -A major feature of the new build system is its emphasis on using scripts to customize your build pipeline. You can check your scripts into version control and customize your build using any of these methods: - -* [PowerShell scripts](/azure/devops/pipelines/tasks/reference/powershell-v2) (Windows) -* [Batch scripts](/azure/devops/pipelines/tasks/reference/batch-script-v1) (Windows) -* [Command prompt](/azure/devops/pipelines/tasks/reference/cmd-line-v2) -* [Shell scripts](/azure/devops/pipelines/tasks/reference/shell-script-v2) (macOS and Linux) - -> [!TIP] -> -> If you're using TFS 2017 or newer, you can write a short PowerShell script directly inside your build pipeline. - -![inline powershell script](media/migrate-from-xaml-builds/inline-powershell-script.png) -_TFS 2017 or newer inline PowerShell script_ - -For all these tasks we offer a set of built-in variables, and if necessary, you can define your own variables. See [Build variables](../build/variables.md). - -### Write a custom task - -If necessary, you can write your own [custom extensions](../../integrate/index.md) to [custom tasks](../../extend/develop/add-build-task.md) for your builds and releases. - -## Reuse patterns - -In XAML builds you created custom XAML templates. In the new builds, it's easier to create reusable patterns. - -### Create a template - -If you don't see a template for the kind of app you can start from an empty pipeline and [add the tasks you need](../tasks/index.md). After you've got a pattern that you like, you can clone it or save it as a template directly in your web browser. See [Create your first pipeline](../create-first-pipeline.md). - -### Task groups (TFS 2017 or newer) - -In XAML builds, if you change the template, then you also change the behavior of all pipelines based on it. In the new build system, templates don't work this way. Instead, a template behaves as a traditional template. After you create the build pipeline, subsequent changes to the template have no effect on build pipelines. - -If you want to create a reusable and automatically updated piece of logic, then [create a task group](../library/task-groups.md). You can then later modify the task group in one place and cause all the pipelines that use it to automatically be changed. - -## FAQ - - - -::: moniker range=">=tfs-2018" - -### I don't see XAML builds. What do I do? - -XAML builds are deprecated. We strongly recommend that you migrate to the new builds as explained above. - -::: moniker-end - -::: moniker range=">=azure-devops-2020" - -If you're not yet ready to migrate, then to enable XAML builds you must connect a XAML build controller to your organization. See [Configure and manage your build system](/previous-versions/visualstudio/visual-studio-2013/ms252495(v=vs.120)). - -::: moniker-end - -::: moniker range="tfs-2018" - -If you're not yet ready to migrate, then to enable XAML builds: - -1. Install [TFS 2018.2](https://visualstudio.microsoft.com/downloads/?q=tfs). - -1. Connect your XAML build servers to your TFS instance. See [Configure and manage your build system](/previous-versions/visualstudio/visual-studio-2013/ms252495(v=vs.120)). - -::: moniker-end - -### How do I add conditional logic to my build pipeline? - -Although the new build pipelines are essentially linear, we do give you control of the conditions under which a task runs. - -On TFS 2015 and newer: You can select Enabled, Continue on error, or Always run. - -On Azure Pipelines, you can specify one of four built-in choices to control when a task is run. If you need more control, you can specify custom conditions. For example: - -``` -and(failed(), in(variables['Build.Reason'], 'IndividualCI', 'BatchedCI'), startsWith(variables['Build.SourceBranch'], 'refs/heads/features/')) -``` - -See [Specify conditions for running a task](../process/conditions.md). - - diff --git a/docs/pipelines/build/options.md b/docs/pipelines/build/options.md deleted file mode 100644 index 0817c0bcacf..00000000000 --- a/docs/pipelines/build/options.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Build options -ms.custom: seodec18 -description: Learn about building your code or deploying your software using build options on Azure Pipelines and Team Foundation Server (TFS). -ms.topic: reference -ms.assetid: 7C469647-117D-4867-B094-8BC811C0003E -ms.date: 06/19/2021 -monikerRange: '<= azure-devops' ---- - -# Build options - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - -## Create a work item on failure - -If the build pipeline fails, you can automatically create a work item to track getting the problem fixed. You can specify the work item type. - -You can also select if you want to assign the work item to the requestor. For example, if this is a CI build, and a team member checks in some code that breaks the build, then the work item is assigned to that person. - -**Additional Fields:** You can set the value of work item fields. For example: - -| Field | Value | -|---|---| -| ```System.Title``` | ```Build $(Build.BuildNumber) failed``` | -| ```System.Reason``` | ```Build failure``` | - -**Q:** What other work item fields can I set? **A:** [Work item field index](../../boards/work-items/guidance/work-item-field.md) - - -## Allow scripts to access the OAuth token - -Select this check box in classic build pipelines if you want to enable your script to use the build pipeline OAuth token. This check box is located under the "additional settings" section after selecting the agent job in the pipeline. - -For an example, see [Use a script to customize your build pipeline](../scripts/powershell.md). - - -## Default agent pool - -Select the [pool](../agents/pools-queues.md) that's attached to the pool that contains the agents you want to run this pipeline. - -> [!TIP] -> If your code is in Azure Pipelines and you run your builds on Windows, in many cases the simplest option is to use the [Hosted pool](../agents/hosted.md). - -## Build job authorization scope - -Specify the authorization scope for a build job. Select: - -* **Project Collection** if the build needs access to multiple projects. -* **Current Project** if you want to restrict this build to have access only the resources in the current project. - -For more information, see [Understand job access tokens](../process/access-tokens.md). - -## Build (run) number - -This documentation has moved to [Build (run) number](../process/run-number.md). diff --git a/docs/pipelines/build/run-retention.md b/docs/pipelines/build/run-retention.md index 8dbbb5feb7c..aca69e1ba59 100644 --- a/docs/pipelines/build/run-retention.md +++ b/docs/pipelines/build/run-retention.md @@ -105,7 +105,7 @@ This is similar to above, only the condition needs to change: ```yaml - task: PowerShell@2 - condition: and(succeeded(), not(canceled()), startsWith(variables['Build.SourceBranchName'], 'releases/')) + condition: and(succeeded(), not(canceled()), startsWith(variables['Build.SourceBranch'], 'releases/')) name: RetainReleaseBuildOnSuccess displayName: Retain Release Build on Success inputs: @@ -168,7 +168,7 @@ To [_update_ a retention lease](/rest/api/azure/devops/build/leases/update) requ $headers = @{ Authorization = 'Bearer $(System.AccessToken)' }; $rawRequest = @{ daysValid = 365 }; $request = ConvertTo-Json $rawRequest; - $uri = "$(System.CollectionUri)$(System.TeamProject)/_apis/build/retention/leases/$newLeaseId?api-version=7.1-preview.2"; + $uri = "$(System.CollectionUri)$(System.TeamProject)/_apis/build/retention/leases/$(newLeaseId)?api-version=7.1-preview.2"; Invoke-RestMethod -uri $uri -method PATCH -Headers $headers -ContentType $contentType -Body $request; ``` diff --git a/docs/pipelines/build/triggers.md b/docs/pipelines/build/triggers.md index f76e8617c19..bfed7512d52 100644 --- a/docs/pipelines/build/triggers.md +++ b/docs/pipelines/build/triggers.md @@ -2,10 +2,9 @@ title: Triggers in Azure Pipelines description: Learn about how you can specify CI, scheduled, gated, and other triggers in Azure Pipelines ms.topic: conceptual -ms.custom: seodec18 ms.author: vijayma author: vijayma -ms.date: 01/25/2023 +ms.date: 11/15/2024 monikerRange: '<= azure-devops' --- @@ -13,9 +12,7 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end + Use triggers to run a pipeline automatically. Azure Pipelines supports many types of triggers. Based on your pipeline's type, select the appropriate trigger from the lists below. @@ -32,6 +29,7 @@ Continuous integration (CI) triggers vary based on the type of repository you bu - [CI triggers in GitHub](../repos/github.md#ci-triggers) - [CI triggers in Bitbucket Cloud](../repos/bitbucket.md#ci-triggers) - [CI triggers in TFVC](../repos/tfvc.md#ci-triggers) +- [CI trigger YAML schema reference](/azure/devops/pipelines/yaml-schema/trigger) Pull request validation (PR) triggers also vary based on the type of repository. @@ -39,6 +37,7 @@ Pull request validation (PR) triggers also vary based on the type of repository. - [PR triggers in Azure Repos Git](../repos/azure-repos-git.md#pr-triggers) - [PR triggers in GitHub](../repos/github.md#pr-triggers) - [PR triggers in Bitbucket Cloud](../repos/bitbucket.md#pr-triggers) +- [PR trigger YAML schema reference](/azure/devops/pipelines/yaml-schema/pr) [Gated check-in](../repos/tfvc.md#gated) is supported for TFVC repositories. @@ -60,14 +59,13 @@ YAML pipelines can have different versions of the pipeline in different branches | GitHub pull request comment triggers | The version of the pipeline in the source branch for the pull request is used. | | Scheduled triggers | See [Branch considerations for scheduled triggers](../process/scheduled-triggers.md?tabs=yaml#branch-considerations-for-scheduled-triggers). | | Pipeline completion triggers | See [Branch considerations for pipeline completion triggers](../process/pipeline-triggers.md?tabs=yaml#branch-considerations). | -| [Azure Pipelines Action](https://github.com/marketplace/actions/azure-pipelines-action) | See [Branch considerations](../ecosystems/github-actions.md#branch-considerations). | ## Classic release pipelines -[Continuous deployment triggers](../release/triggers.md#release-triggers) help you start classic releases after a classic build or YAML pipeline completes. +[Continuous deployment triggers](../release/triggers.md#continuous-deployment-triggers) help you start classic releases after a classic build or YAML pipeline completes. -[Scheduled release triggers](../release/triggers.md#scheduled-triggers) allow you to run a release pipeline according to a schedule. +[Scheduled release triggers](../release/triggers.md#scheduled-release-triggers) allow you to run a release pipeline according to a schedule. [Pull request release triggers](../release/triggers.md) are used to deploy a pull request directly using classic releases. -[Stage triggers in classic release](../release/triggers.md#env-triggers) are used to configure how each stage in a classic release is triggered. +[Stage triggers in classic release](../release/triggers.md#stage-triggers) are used to configure how each stage in a classic release is triggered. diff --git a/docs/pipelines/build/variables.md b/docs/pipelines/build/variables.md index bbb022c9b82..494eb197893 100644 --- a/docs/pipelines/build/variables.md +++ b/docs/pipelines/build/variables.md @@ -1,12 +1,12 @@ --- title: Predefined variables -ms.custom: seodec18 description: A comprehensive list of all available predefined variables ms.topic: reference ms.assetid: 3A1C529F-DF6B-470A-9047-2758644C3D95 ms.author: jukullam author: juliakm -ms.date: 06/29/2023 +ms.date: 12/12/2024 +ms.custom: copilot-scenario-highlight monikerRange: '<= azure-devops' --- @@ -14,8 +14,6 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -[!INCLUDE [temp](../includes/concept-rename-note.md)] - Variables give you a convenient way to get key bits of data into various parts of your pipeline. This is a list of predefined variables that are available for your use. There may be a few other predefined variables, but they're mostly for internal use. @@ -31,6 +29,13 @@ For classic pipelines, you can use [release variables](../release/variables.md) Learn more about [working with variables](../process/variables.md). +::: moniker range="azure-devops" + +> [!TIP] +> You can ask [Copilot](/copilot/) for help with variables. To learn more, see [Ask Copilot to generate a stage with a condition based on variable values](#ask-copilot-to-generate-a-stage-with-a-condition-based-on-variable-values). + +::: moniker-end + ## Build.Clean This is a deprecated variable that modifies how the build agent cleans up source. @@ -43,18 +48,16 @@ To learn how to clean up source, see [Clean the local repo on the agent](../repo # [YAML](#tab/yaml) In YAML, you must explicitly map `System.AccessToken` into the pipeline using a -variable. You can do this at the step or task level: +variable. You can do this at the step or task level. For example, you can use `System.AccessToken` to authenticate with a container registry. ```yaml steps: - - bash: echo This script could use $SYSTEM_ACCESSTOKEN - env: - SYSTEM_ACCESSTOKEN: $(System.AccessToken) - - powershell: | - Write-Host "This is a script that could use $env:SYSTEM_ACCESSTOKEN" - Write-Host "$env:SYSTEM_ACCESSTOKEN = $(System.AccessToken)" - env: - SYSTEM_ACCESSTOKEN: $(System.AccessToken) +- task: Docker@2 + inputs: + command: login + containerRegistry: '' + env: + SYSTEM_ACCESSTOKEN: $(System.AccessToken) ``` You can configure the default scope for `System.AccessToken` using [build job authorization scope](../process/access-tokens.md#job-authorization-scope). @@ -76,7 +79,6 @@ pushes and pulls in your scripts. For more detailed logs to debug pipeline problems, define `System.Debug` and set it to `true`. - 1. Edit your pipeline. 1. Select **Variables**. 1. Add a new variable with the name `System.Debug` and value `true`. @@ -105,32 +107,24 @@ When `System.Debug` is set to `true`, an extra variable named `Agent.Diagnostic` For more information, see [Review logs to diagnose pipeline issues](../troubleshooting/review-logs.md). - ::: moniker range=">=azure-devops" [!INCLUDE [include](includes/variables-hosted.md)] ::: moniker-end -::: moniker range=">= azure-devops-2020 <= azure-devops-2022" - -[!INCLUDE [include](includes/variables-server-2020.md)] - -::: moniker-end - -::: moniker range="azure-devops-2019" +::: moniker range="= azure-devops-2022" -[!INCLUDE [include](includes/variables-server2019.md)] +[!INCLUDE [include](includes/variables-server-2022.md)] ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="= azure-devops-2020" -[!INCLUDE [include](includes/variables-tfs2018.md)] +[!INCLUDE [include](includes/variables-server-2020.md)] ::: moniker-end - ### How are the identity variables set? @@ -143,3 +137,20 @@ The value depends on what caused the build and are specific to Azure Repos repos | In TFVC by a [gated check-in trigger](triggers.md) | The person who checked in the changes. | The person who checked in the changes. | | In Git or TFVC by the [Scheduled triggers](triggers.md) | The system identity, for example: `[DefaultCollection]\Project Collection Service Accounts` | The system identity, for example: `[DefaultCollection]\Project Collection Service Accounts` | | Because you clicked the **Queue build** button | You | You | + +::: moniker range="azure-devops" + +## Ask Copilot to generate a stage with a condition based on variable values + +Use [Copilot](/copilot/) to generate a stage with a condition determined by the value of a variable. + +This example prompt defines a stage that runs when `Agent.JobStatus` indicates that the previous stage ran successfully: + +> Create a new Azure DevOps stage that only runs when `Agent.JobStatus` is `Succeeded` or `SucceededWithIssues`. + +You can customize the prompt to use values that meet your requirements. For example, you can ask for help creating a stage that only runs when a pipeline fails. + +> [!NOTE] +> GitHub Copilot is powered by AI, so surprises and mistakes are possible. Make sure to verify any generated code or suggestions. For more information about the general use of GitHub Copilot, product impact, human oversight, and privacy, see [GitHub Copilot FAQs](https://github.com/features/copilot#faq). + +::: moniker-end \ No newline at end of file diff --git a/docs/pipelines/create-first-pipeline.md b/docs/pipelines/create-first-pipeline.md index ef3974ec2a4..983275d89a3 100644 --- a/docs/pipelines/create-first-pipeline.md +++ b/docs/pipelines/create-first-pipeline.md @@ -1,12 +1,12 @@ --- title: Create your first pipeline -ms.custom: seodec18, devx-track-azurecli, py-fresh-zinc +ms.custom: devx-track-azurecli, py-fresh-zinc description: Create your first pipeline in Azure Pipelines, Azure DevOps, & Team Foundation Server ms.topic: conceptual ms.assetid: 038A5329-1B8F-46D9-A0C3-DA3FCFA43996 ms.author: sdanie author: steved0x -ms.date: 06/06/2023 +ms.date: 03/31/2025 monikerRange: '<= azure-devops' --- @@ -16,7 +16,11 @@ monikerRange: '<= azure-devops' ::: moniker range="azure-devops" -This is a step-by-step guide to using Azure Pipelines to build a sample application. This guide uses YAML pipelines configured with the [YAML pipeline editor](get-started/yaml-pipeline-editor.md). If you'd like to use Classic pipelines instead, see [Define your Classic pipeline](release/define-multistage-release-process.md). +This is a step-by-step guide to using Azure Pipelines to build a sample application from a Git repository. This guide uses YAML pipelines configured with the [YAML pipeline editor](get-started/yaml-pipeline-editor.md). + +For more information on the different sections in a YAML pipeline, see [pipeline](/azure/devops/pipelines/yaml-schema/pipeline) in the [Azure Pipelines YAML schema](/azure/devops/pipelines/yaml-schema/) and [Customize your YAML pipeline](./customize-pipeline.md). + +If you'd like to use Classic pipelines instead, see [Define your Classic pipeline](release/define-multistage-release-process.md). For guidance on using TFVC, see [Build TFVC repositories](./repos/tfvc.md). ## Prerequisites - Azure DevOps @@ -144,11 +148,13 @@ https://github.com/Azure-Samples/js-e2e-express-server Learn more about [working with JavaScript](ecosystems/javascript.md) in your pipeline. + + + + + --- ::: moniker-end -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" ## View and manage your pipelines @@ -280,7 +291,7 @@ The details page for a pipeline allows you to view and manage that pipeline. ![Screenshot of pipeline details page.](get-started/media/pipeline-overview.png) -Choose **Edit** to edit your pipeline. For more information, see [YAML pipeline editor](get-started/yaml-pipeline-editor.md). +Choose **Edit** to edit your pipeline. For more information, see [YAML pipeline editor](get-started/yaml-pipeline-editor.md). You can also edit your pipeline by modifying the **azure-pipelines.yml** file directly in the repository that hosts the pipeline. ### View pipeline run details @@ -328,25 +339,17 @@ From the **More actions** :::image type="icon" source="../media/icons/more-actio ::: moniker-end -::: moniker range="<= azure-devops-2020" - -[!INCLUDE [temp](includes/concept-rename-note.md)] +::: moniker range="=azure-devops-2020" ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" @@ -391,7 +384,7 @@ Create a PowerShell script that prints `Hello world`. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" File' option](media/get-started-designer/add-a-file-tfs-2018-2.png) - - #### [TFS 2018 RTM](#tab/tfs-2018-rtm) - ![Select the 'New -> File' option](media/get-started-designer/add-a-file-tfs-2018.png) - - * * * - - ::: moniker-end - -::: moniker range="< azure-devops-2019" - -1. In the dialog box, name your new file and create it. - ``` - HelloWorld.ps1 - ``` - -2. Copy and paste this script. - ```ps - Write-Host "Hello world" - ``` - -3. **Commit** (save) the file. - -::: moniker-end + -::: moniker range="<= azure-devops-2020" +::: moniker range="=azure-devops-2020" > In this tutorial, our focus is on CI/CD, so we're keeping the code part simple. We're working in an Azure Repos Git repository directly in your web browser. > @@ -463,7 +422,7 @@ Create a build pipeline that prints "Hello world." ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" A build pipeline is the entity through which you define your automated build pipeline. In the build pipeline, you compose a set of tasks, each of which perform a step in your build. The task catalog provides a rich set of tasks for you to get started. You can also add PowerShell or shell scripts to your build pipeline. @@ -544,7 +476,7 @@ A typical build produces an artifact that can then be deployed to various stages ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" Artifacts are the files that you want your build to produce. Artifacts can be nearly anything your team needs to test or deploy your app. For example, you've got a .DLL and .EXE executable files and .PDB symbols file of a C# or C++ .NET Windows app. > @@ -597,7 +512,7 @@ Save and queue a build manually and test your build pipeline. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" You can view a summary of all the builds or drill into the logs for each build at any time by navigating to the **Builds** tab in **Azure Pipelines**. For each build, you can also view a list of commits that were built and the work items associated with each commit. You can also run tests in each build and analyze the test failures. - -::: moniker-end - -::: moniker range="<= azure-devops-2020" +::: moniker range="=azure-devops-2020" ## Add some variables and commit a change to your script @@ -670,26 +551,16 @@ We'll pass some build variables to the script to make our pipeline a bit more in ::: moniker-end - ::: moniker range=">= azure-devops-2019 < azure-devops" + ::: moniker range=" [!div class="mx-imgBorder"] > ![Open the PowerShell task in the build console](media/get-started-designer/powershell-task-2-azure-devops-newnavon.png) ::: moniker-end - ::: moniker range="tfs-2018" - - #### [TFS 2018.2](#tab/tfs-2018-2) - ![PowerShell task - TFS 2018.2](media/get-started-designer/powershell-task-2-tfs-2018-2.png) - - #### [TFS 2018 RTM](#tab/tfs-2018-rtm) - ![PowerShell task - 2018 RTM](media/get-started-designer/powershell-task-2.png) - - * * * - - ::: moniker-end + - ::: moniker range="<= azure-devops-2020" + ::: moniker range="=azure-devops-2020" **Arguments** @@ -720,19 +591,13 @@ Next you'll add the arguments to your script. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] > ![Build a summary PowerShell script log](media/get-started-designer/build-summary-powershell-script-log-azure-devops-newnav.png) ::: moniker-end - ::: moniker range="tfs-2018" - - > [!div class="mx-imgBorder"] - > ![build summary powershell script log](media/get-started-designer/build-summary-powershell-script-log.png) - - ::: moniker-end + -::: moniker range="<= azure-devops-2020" +::: moniker range="=azure-devops-2020" > We just introduced the concept of build variables in these steps. We printed the value of a variable that is automatically predefined and initialized by the system. You can also define custom variables and use them either in arguments to your tasks, or as environment variables within your scripts. To learn more about variables, see [Build variables](build/variables.md). @@ -768,7 +628,7 @@ Define the process for running the script in two stages. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] - > ![trigger continuous deployment - TFS 2018.2](media/get-started-designer/trigger-continuous-deployment-release-environment-tfs-2018-2.png) - - #### [TFS 2018 RTM](#tab/tfs-2018-rtm) - > [!div class="mx-imgBorder"] - > ![trigger continuous deployment - TFS 2018 RTM](media/get-started-designer/trigger-continuous-deployment-release-environment-tfs-2018-rtm-new-editor.png) - - * * * - -7. Select the **Tasks** tab and select your **QA** stage. - -8. Select the plus sign **( + )** for the job to add a task to the job. - -9. On the **Add tasks** dialog box, select **Utility**, locate the **PowerShell** task, and then select its **Add** button. - -10. On the left side, select your new **PowerShell** script task. - -11. For the **Script Path** argument, select the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: button to browse your artifacts and select the script you created. - -12. Add these **Arguments**: - - ``` - -greeter "$(Release.RequestedFor)" -trigger "$(Build.DefinitionName)" - ``` - -13. On the **Pipeline** tab, select the **QA** stage and select **Clone**. - - > [!div class="mx-imgBorder"] - > ![clone the release environment](media/get-started-designer/clone-release-environment-tfs-2018-2.png) - > - -14. Rename the cloned stage **Production**. - -15. Rename the release pipeline **Hello world**. - - > [!div class="mx-imgBorder"] - > ![rename the release pipeline](media/get-started-designer/rename-release-definition-tfs-2018-2.png) - > - -16. Save the release pipeline. - -::: moniker-end - -::: moniker range="<= azure-devops-2020" +::: moniker range="=azure-devops-2020" > A release pipeline is a collection of stages to which the application build artifacts are deployed. It also defines the actual deployment pipeline for each stage, as well as how the artifacts are promoted from one stage to another. > @@ -890,7 +692,7 @@ Run the script in each stage. ::: moniker-end - ::: moniker range=">= azure-devops-2019 < azure-devops" + ::: moniker range=" You can track the progress of each release to see if it has been deployed to all the stages. You can track the commits that are part of each release, the associated work items, and the results of any test runs that you've added to the release pipeline. @@ -961,7 +747,7 @@ Your new code automatically is deployed in the **QA** stage, and then in the **P ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] > ![release script step final log - DevOps 2019 and 2020](media/get-started-designer/release-script-step-final-log-azure-devops-newnavon.png) @@ -969,15 +755,7 @@ Your new code automatically is deployed in the **QA** stage, and then in the **P ::: moniker-end -::: moniker range="tfs-2018" - -> [!div class="mx-imgBorder"] -> ![release script step final log - - TFS 2018](media/get-started-designer/release-script-step-final-log-tfs-2018-2.png) -> - -::: moniker-end - -::: moniker range="<= azure-devops-2020" +::: moniker range="=azure-devops-2020" > In many cases, you probably would want to edit the release pipeline so that the production deployment happens only after some testing and approvals are in place. See [Approvals and gates overview](release/approvals/index.md). @@ -994,7 +772,7 @@ Your new code automatically is deployed in the **QA** stage, and then in the **P :::moniker-end -::: moniker range=">= tfs-2018 <= azure-devops-2020" +::: moniker range="=azure-devops-2020" You've learned the basics of creating and running a pipeline. Now you're ready to configure your build pipeline for the programming language you're using. @@ -1048,7 +826,7 @@ When you're ready to get going with CI/CD for your app, you can use the version ::: moniker-end -::: moniker range="<= azure-devops-2020" +::: moniker range="=azure-devops-2020" * Clients @@ -1067,7 +845,7 @@ When you're ready to get going with CI/CD for your app, you can use the version ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" > If you're using the **New Build Editor**, then your custom templates are shown at the bottom of the list. - ### How do I work with drafts? If you're editing a build pipeline and you want to test some changes that are not yet ready for production, you can save it as a draft. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] > ![save-as-draft](media/get-started-designer/save-as-draft-newnav.png) @@ -1112,19 +883,13 @@ If you're editing a build pipeline and you want to test some changes that are no ::: moniker-end -::: moniker range="tfs-2018" - -![Screenshot that shows saving as draft.](media/get-started-designer/save-as-draft.png) - -::: moniker-end - -::: moniker range="<= azure-devops-2020" +::: moniker range="=azure-devops-2020" You can edit and test your draft as needed. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] > ![edit draft - DevOps 2019 and 2020](media/get-started-designer/edit-draft-newnav.png) @@ -1132,13 +897,13 @@ You can edit and test your draft as needed. ::: moniker-end -::: moniker range="<= azure-devops-2020" +::: moniker range="=azure-devops-2020" When you're ready, you can publish the draft to merge the changes into your build pipeline. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] > ![publish draft - DevOps 2019 and 2020](media/get-started-designer/publish-draft-newnav.png) @@ -1146,13 +911,7 @@ When you're ready, you can publish the draft to merge the changes into your buil ::: moniker-end -::: moniker range="tfs-2018" - -![publish draft - TFS 2018](media/get-started-designer/publish-draft.png) - -::: moniker-end - -::: moniker range="<= azure-devops-2020" +::: moniker range="=azure-devops-2020" Or, if you decide to discard the draft, you can delete it from the **All Pipeline** tab shown above. @@ -1169,7 +928,7 @@ To delete a pipeline, navigate to the summary page for that pipeline, and choose ::: moniker-end -::: moniker range="<= azure-devops-2020" +::: moniker range="=azure-devops-2020" You can queue builds [automatically](build/triggers.md) or manually. @@ -1179,7 +938,7 @@ When you manually queue a build, you can, for a single run of the build: * Add and modify some [variables](build/variables.md). -* Add [demands](process/demands.md). +* Add [demands](/azure/devops/pipelines/yaml-schema/pool-demands). * In a Git repository @@ -1205,7 +964,7 @@ When you manually queue a build, you can, for a single run of the build: * Add and modify some [variables](build/variables.md). -* Add [demands](process/demands.md). +* Add [demands](/azure/devops/pipelines/yaml-schema/pool-demands). * In a Git repository @@ -1217,20 +976,6 @@ When you manually queue a build, you can, for a single run of the build: ### Where can I learn more about pipeline settings? -::: moniker range="tfs-2018" - -To learn more about build pipeline settings, see: - -* [Getting sources](repos/index.md) -* [Tasks](tasks/index.md) -* [Variables](build/variables.md) -* [Triggers](build/triggers.md) -* [Options](build/options.md) -* [Retention](policies/retention.md) -* [History](build/history.md) - -::: moniker-end - ::: moniker range="azure-devops" To learn more about pipeline settings, see: diff --git a/docs/pipelines/customize-pipeline.md b/docs/pipelines/customize-pipeline.md index 0a2035b040f..8309b579395 100644 --- a/docs/pipelines/customize-pipeline.md +++ b/docs/pipelines/customize-pipeline.md @@ -1,14 +1,14 @@ --- title: Customize your pipeline -ms.custom: seodec18, devx-track-azurecli +ms.custom: devx-track-azurecli description: Step-by-step tutorial to customize a pipeline ms.topic: quickstart ms.assetid: b3a9043e-aa64-4824-9999-afb2be72f141 ms.manager: jepling ms.author: vijayma author: vijayma -ms.date: 01/30/2023 -monikerRange: ">= azure-devops-2019" +ms.date: 08/17/2023 +monikerRange: "<=azure-devops" --- # Customize your pipeline @@ -28,7 +28,7 @@ A pipeline is defined using a YAML file in your repo. Usually, this file is name Navigate to the **Pipelines** page in Azure Pipelines, select the pipeline you created, and choose **Edit** in the context menu of the pipeline to open the YAML editor for the pipeline. > [!NOTE] -> For instructions on how to view and manage your pipelines in the Azure DevOps portal, see [Navigating pipelines](get-started/multi-stage-pipelines-experience.md). +> For instructions on how to view and manage your pipelines in the Azure DevOps portal, see [View and manage your pipelines](create-first-pipeline.md#view-and-manage-your-pipelines). Examine the contents of the YAML file. @@ -247,7 +247,7 @@ From the **Pipeline settings** pane you can configure the following settings. * **Processing of new run requests** - Sometimes you'll want to prevent new runs from starting on your pipeline. * By default, the processing of new run requests is **Enabled**. This setting allows standard processing of all trigger types, including manual runs. * **Paused** pipelines allow run requests to be processed, but those requests are queued without actually starting. When new request processing is enabled, run processing resumes starting with the first request in the queue. - * **Disabled** pipelines prevent users from starting new runs. All triggers are also disabled while this setting is applied. + * **Disabled** pipelines prevent users from starting new runs. All triggers are also disabled while this setting is applied. All build policies using a disabled pipeline will show "Unable to queue Build" message next to the build policy in the PR overview window and the status of the build policy will be broken. * **YAML file path** - If you ever need to direct your pipeline to use a different YAML file, you can specify the path to that file. This setting can also be useful if you need to move/rename your YAML file. * **Automatically link work items included in this run** - The changes associated with a given pipeline run may have work items associated with them. Select this option to link those work items to the run. When **Automatically link work items included in this run** is selected, you must specify either a specific branch, or `*` for all branches, which is the default. If you specify a branch, work items are only associated with runs of that branch. If you specify `*`, work items are associated for all runs. @@ -255,7 +255,6 @@ From the **Pipeline settings** pane you can configure the following settings. * To get notifications when your runs fail, see how to [Manage notifications for a team](../organizations/notifications/manage-team-group-global-organization-notifications.md) - ### Manage security You can configure pipelines security on a project level from the **More actions** :::image type="icon" source="../media/icons/more-actions.png"::: on the pipelines landing page, and on a pipeline level on the pipeline details page. @@ -263,8 +262,11 @@ You can configure pipelines security on a project level from the **More actions* ![Screenshot of pipeline security menu options.](get-started/media/pipelines-context-menu.png) To support security of your pipeline operations, you can add users to a built-in security group, set individual permissions for a user or group, or add users to predefined roles. You can manage security for Azure Pipelines in the web portal, either from the user or admin context. For more information on configuring pipelines security, see [Pipeline permissions and security roles](policies/permissions.md). + ## Create work item on failure +::: moniker range="azure-devops" + YAML pipelines don't have a [Create work item on failure](build/options.md#create-a-work-item-on-failure) setting like classic build pipelines. Classic build pipelines are single stage, and **Create work item on failure** applies to the whole pipeline. YAML pipelines can be multi-stage, and a pipeline level setting may not be appropriate. To implement **Create work item on failure** in a YAML pipeline, you can use methods such as the [Work Items - Create](/rest/api/azure/devops/wit/work-items/create) REST API call or the Azure DevOps CLI [az boards work-item create](/cli/azure/boards/work-item#az-boards-work-item-create) command at the desired point in your pipeline. The following example has two jobs. The first job represents the work of the pipeline, but if it fails, the second job runs, and creates a bug in the same project as the pipeline. @@ -312,12 +314,80 @@ jobs: ``` > [!NOTE] -> Azure Boards allows you to configure your work item tracking using several different processes, such as Agile or Basic. Each process has different work item types, and not every work item type is available in each process. For a list of work item types supported by each process, see [Work item types (WITs)](../boards/work-items/about-work-items.md#work-item-types-wits). +> Azure Boards allows you to configure your work item tracking using several different processes, such as Agile or Basic. Each process has different work item types, and not every work item type is available in each process. For a list of work item types supported by each process, see [Work item types (WITs)](../boards/work-items/about-work-items.md#track-work-with-different-work-item-types). The previous example uses [Runtime parameters](process/runtime-parameters.md) to configure whether the pipeline succeeds or fails. When manually running the pipeline, you can set the value of the `succeed` parameter. The second `script` step in the first job of the pipeline evaluates the `succeed` parameter and only runs when `succeed` is set to false. The second job in the pipeline has a dependency on the first job and only runs if the first job fails. The second job uses the Azure DevOps CLI [az boards work-item create](/cli/azure/boards/work-item#az-boards-work-item-create) command to create a bug. For more information on running Azure DevOps CLI commands from a pipeline, see [Run commands in a YAML pipeline](../cli/azure-devops-cli-in-yaml.md). +::: moniker-end + +::: moniker range="< azure-devops" + +YAML pipelines don't have a [Create work item on failure](build/options.md#create-a-work-item-on-failure) setting like classic build pipelines. Classic build pipelines are single stage, and **Create work item on failure** applies to the whole pipeline. YAML pipelines can be multi-stage, and a pipeline level setting may not be appropriate. To implement **Create work item on failure** in a YAML pipeline, you can use the [Work Items - Create](/rest/api/azure/devops/wit/work-items/create) REST API call at the desired point in your pipeline. + +The following example has two jobs. The first job represents the work of the pipeline, but if it fails, the second job runs, and creates a bug in the same project as the pipeline. + +```yml +# When manually running the pipeline, you can select whether it +# succeeds or fails. +parameters: +- name: succeed + displayName: Succeed or fail + type: boolean + default: false + +trigger: +- main + +pool: + vmImage: ubuntu-latest + +jobs: +- job: Work + steps: + - script: echo Hello, world! + displayName: 'Run a one-line script' + + # This malformed command causes the job to fail + # Only run this command if the succeed variable is set to false + - script: git clone malformed input + condition: eq(${{ parameters.succeed }}, false) + +# This job creates a work item, and only runs if the previous job failed +- job: ErrorHandler + dependsOn: Work + condition: failed() + steps: + - bash: | + curl \ + -X POST \ + -H 'Authorization: Basic $(System.AccessToken)' \ + -H 'Content-Type: application/json-patch+json' \ + -d '[ + { + "op": "add", + "path": "/fields/System.Title", + "from": null, + "value": "git clone failed" + } + ]' \ + "$(System.CollectionUri)$(System.TeamProject)/_apis//wit/workitems/$Bug?api-version=7.1-preview.3 +" + env: + SYSTEM_ACCESSTOKEN: $(System.AccessToken) + displayName: 'Create work item on failure' +``` + +> [!NOTE] +> Azure Boards allows you to configure your work item tracking using several different processes, such as Agile or Basic. Each process has different work item types, and not every work item type is available in each process. For a list of work item types supported by each process, see [Work item types (WITs)](../boards/work-items/about-work-items.md#track-work-with-different-work-item-types). + +The previous example uses [Runtime parameters](process/runtime-parameters.md) to configure whether the pipeline succeeds or fails. When manually running the pipeline, you can set the value of the `succeed` parameter. The second `script` step in the first job of the pipeline evaluates the `succeed` parameter and only runs when `succeed` is set to false. + +The second job in the pipeline has a dependency on the first job and only runs if the first job fails. The second job uses the Azure DevOps API [az boards work-item create](/cli/azure/boards/work-item#az-boards-work-item-create) command to create a bug. + +::: moniker-end + This example uses two jobs, but this same approach could be used across [multiple stages](process/stages.md). > [!NOTE] diff --git a/docs/pipelines/ecosystems/anaconda.md b/docs/pipelines/ecosystems/anaconda.md index c1b64c6bd1e..76c8d9ccda9 100644 --- a/docs/pipelines/ecosystems/anaconda.md +++ b/docs/pipelines/ecosystems/anaconda.md @@ -4,7 +4,6 @@ description: Set up and use Anaconda environments with Azure Pipelines, Azure De ms.topic: quickstart ms.assetid: 50ed6bb4-5f35-4e1e-aafc-295eb10198df ms.reviewer: vijayma -ms.custom: seodec18 ms.date: 01/24/2022 monikerRange: azure-devops author: JuliaKM diff --git a/docs/pipelines/ecosystems/android.md b/docs/pipelines/ecosystems/android.md index 9a038fb8f68..11cbb1e7260 100644 --- a/docs/pipelines/ecosystems/android.md +++ b/docs/pipelines/ecosystems/android.md @@ -5,70 +5,59 @@ ms.topic: quickstart ms.assetid: 7b2856ea-290d-4fd4-9734-ea2d48cb19d3 ms.author: vijayma ms.reviewer: dastahel -ms.custom: seodec18, freshness-fy22q2 -ms.date: 12/22/2021 +ms.custom: freshness-fy22q2 +ms.date: 02/04/2025 monikerRange: azure-devops author: vijayma --- -# Build, test, & deploy Android apps +# Build, test, and deploy Android apps [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -You can set up pipelines to automatically build, test, and deploy Android applications. -## Prerequisites - -You must have the following items: -- GitHub account. If you don't have a GitHub account, [create one now](https://github.com). -- Azure DevOps project. If you don't have a project, [create one now](../../organizations/projects/create-project.md). +This quickstart shows you how to set up a YAML pipeline in Azure Pipelines to automatically build, test, and deploy an Android app. -## Set up pipeline +## Prerequisites -Do the following tasks to set up a pipeline for a sample Android application. +- An Azure DevOps organization and project where you have permission to create pipelines and deploy apps. To create a project, see [Create a project in Azure DevOps](../../organizations/projects/create-project.md). +- A GitHub account. -1. Fork the following repository to your GitHub account to get the code for a simple Android application. + >[!IMPORTANT] + >During GitHub procedures, you might be prompted to create a [GitHub service connection](../library/service-endpoints.md#github-service-connection) or be redirected to GitHub to sign in, install Azure Pipelines, authorize Azure Pipelines, or authenticate to GitHub organizations. Follow the onscreen instructions to complete the process. For more information, see [Access to GitHub repositories](../repos/github.md#access-to-github-repositories). - ``` - https://github.com/MicrosoftDocs/pipelines-android - ``` +## Create and run the pipeline -2. Sign in to your Azure DevOps organization and go to your project. +Do the following tasks to set up a pipeline for a simple Android application. -3. Select **Pipelines** > **Create pipeline** or **New pipeline**. +1. To get the code for the sample app, fork the [Android sample app](https://github.com/MicrosoftDocs/pipelines-android) repository to your GitHub account. +1. In your Azure DevOps project, select **Pipelines** > **New pipeline**, or **Create pipeline** if this pipeline is the first in the project. +1. Select **GitHub** as the location of your source code. +1. On the **Select a repository** screen, select your forked Android sample repository. +1. On the **Configure your pipeline** screen, select **Android**. +1. Azure Pipelines provides a starter pipeline based on the [Android](https://github.com/microsoft/azure-pipelines-yaml/blob/master/templates/android.yml) template. Review the pipeline code. +1. Select **Save and run**. +1. Optionally, edit the **Commit message** and provide a description. Then select **Save and run** again to commit the *azure-pipelines.yml* file to your repository and start a build. -4. Select **GitHub** as the location of your source code. - - :::image type="content" source="../media/python/where-is-your-code.png" alt-text="Screenshot showing list of repositories to select from."::: - - You might be redirected to GitHub to sign in. If so, enter your GitHub credentials. +The build run page shows build details and progress. If you want to watch your pipeline in action, select **Job** on the lower part of the page. -5. Select the **-android** repository that you previously forked. +You now have a working Android YAML pipeline, *azure-pipelines.yml*, in your repository that's ready to customize. -6. Select **Approve and install** on the screen that follows. - - Azure Pipelines generates a YAML file for your pipeline. +## Customize your pipeline -7. Select **Run**. -8. **Commit directly to the main branch**, and then choose **Run** again. +To make changes to your pipeline, select **Edit** on the pipeline page. The following sections describe some common ways to customize your Android pipeline. -9. Wait for the run to finish. +### Configure Gradle -You have a working YAML file (`azure-pipelines.yml`) in your repository that's ready for you to customize. +The starter YAML pipeline uses Gradle, a common open-source build tool for Android projects. For more information, see the [Gradle task](/azure/devops/pipelines/tasks/reference/gradle-v3). -> [!TIP] -> To make changes to the YAML file, select the pipeline in the **Pipelines** page, and then **Edit** the `azure-pipelines.yml` file. +In the example task, the `tasks` parameter builds the `assembleDebug` build type. You can adjust the `tasks` value for the build variants you want, such as `build`, `test`, and `assembleRelease`. -## Build with Gradle +The example task also assumes that your `gradlew` file is at the root of the repository. If not, adjust the `workingDirectory` and `gradleWrapperFile` values accordingly. -Gradle is a common build tool used for building Android projects. For more information about your options, see the [Gradle](/azure/devops/pipelines/tasks/reference/gradle-v3) task. +The `workingDirectory` should be similar to the root of the repository, such as `AndroidApps/MyApp` or `$(system.defaultWorkingDirectory)/AndroidApps/MyApp`. The `gradleWrapperFile` path should be similar to the root of the repository, such as `AndroidApps/MyApp/gradlew` or `$(system.defaultWorkingDirectory)/AndroidApps/MyApp/gradlew`. ```yaml -# https://learn.microsoft.com/azure/devops/pipelines/ecosystems/android -pool: - vmImage: 'macOS-latest' - -steps: -- task: Gradle@2 +- task: Gradle@3 inputs: workingDirectory: '' gradleWrapperFile: 'gradlew' @@ -78,33 +67,13 @@ steps: tasks: 'assembleDebug' ``` -### Adjust the build path - -- Adjust the **workingDirectory** value if your `gradlew` file isn't in the root of the repository. -The directory value should be similar to the root of the repository, -such as `AndroidApps/MyApp` or `$(system.defaultWorkingDirectory)/AndroidApps/MyApp`. - -- Adjust the **gradleWrapperFile** value if your `gradlew` file isn't in the root of the repository. -The file path value should be similar to the root of the repository, -such as `AndroidApps/MyApp/gradlew` or `$(system.defaultWorkingDirectory)/AndroidApps/MyApp/gradlew`. +For more information about using Gradle tasks, see [Using tasks](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) in the Gradle documentation. For more information about build tasks, see [Build a debug APK](https://developer.android.com/studio/build/building-cmdline#DebugMode) and [Configure build variants](https://developer.android.com/studio/build/build-variants.html) in the Google Android development documentation. -### Adjust Gradle tasks +### Sign and align the Android package (APK) -Adjust the **tasks** value for the build variant you prefer, such as `assembleDebug` or `assembleRelease`. -For more information, see the following Google Android development documentation: -- [Build a debug APK](https://developer.android.com/studio/build/building-cmdline#DebugMode) and -- [Configure build variants](https://developer.android.com/studio/build/build-variants.html). +To run on a device instead of an emulator, the Android Application Package (APK) must be signed. Zipaligning reduces the RAM the application consumes. If your build doesn't already [sign and zipalign](https://developer.android.com/studio/publish/app-signing) the APK, add the [Android Signing](/azure/devops/pipelines/tasks/reference/android-signing-v3) task to the pipeline. For more information, see [Sign a mobile app](../apps/mobile/app-signing.md). -### Sign and align an Android Package (APK) - -If your build doesn't already [sign and zipalign](https://developer.android.com/studio/publish/app-signing) the APK, -add the [Android Signing](/azure/devops/pipelines/tasks/reference/android-signing-v3) task to the YAML. -An APK must be signed to run on a device instead of an emulator. Zipaligning reduces the RAM consumed by the application. - -> [!IMPORTANT] -> We recommend storing each of the following passwords in a [secret variable](../process/variables.md#secret-variables). - -::: moniker range="> tfs-2018" +For security, store the `jarsignerKeystorePassword` and `jarsignerKeyPassword` in [secret variables](../process/variables.md#secret-variables) and use those variables in your pipeline. ```yaml - task: AndroidSigning@2 @@ -118,58 +87,70 @@ An APK must be signed to run on a device instead of an emulator. Zipaligning red zipalign: true ``` -::: moniker-end - -## Test - -### Test on the Android Emulator +### Test on the Android emulator -> [!NOTE] -> The Android Emulator is currently available only on the **Hosted macOS** agent. +To install and run the Android emulator, add the [Bash](/azure/devops/pipelines/tasks/reference/bash-v3) task to your pipeline, and paste in the following code. The emulator starts as a background process and is available in later tasks. Arrange the emulator parameters to fit your testing environment. -Create the [Bash](/azure/devops/pipelines/tasks/reference/bash-v3) task and copy paste the code below in order to install and run the emulator. -Don't forget to arrange the emulator parameters to fit your testing environment. - The emulator starts as a background process and is available in later tasks. +> [!IMPORTANT] +> If you're using a [Microsoft-hosted agent](../agents/hosted.md), use the MacOS agent image with the Android emulator. Current Android emulators require hardware acceleration to start. Azure DevOps hosted Ubuntu agents do not support hardware acceleration. -```bash -#!/usr/bin/env bash +```yaml +- task: Bash@3 + inputs: + targetType: 'inline' + script: | + #!/usr/bin/env bash -# Install AVD files -echo "y" | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install 'system-images;android-27;google_apis;x86' + # Install AVD files + echo "y" | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install 'system-images;android-35;google_apis;x86_64' -# Create emulator -echo "no" | $ANDROID_HOME/tools/bin/avdmanager create avd -n xamarin_android_emulator -k 'system-images;android-27;google_apis;x86' --force + # Create emulator + echo "y" | $ANDROID_HOME/cmdline-tools/latest/bin/avdmanager create avd -n xamarin_android_emulator -d "Nexus 10" -k 'system-images;android-35;google_apis;x86_64' --force -$ANDROID_HOME/emulator/emulator -list-avds + echo "y" | $ANDROID_HOME/emulator/emulator -list-avds -echo "Starting emulator" + echo "Starting emulator" -# Start emulator in background -nohup $ANDROID_HOME/emulator/emulator -avd xamarin_android_emulator -no-snapshot > /dev/null 2>&1 & -$ANDROID_HOME/platform-tools/adb wait-for-device shell 'while [[ -z $(getprop sys.boot_completed | tr -d '\r') ]]; do sleep 1; done; input keyevent 82' + # Start emulator in background + nohup $ANDROID_HOME/emulator/emulator -avd xamarin_android_emulator -no-snapshot -no-window -no-audio -no-boot-anim -accel on > /dev/null 2>&1 & + # Fixed quoting around "\r" + $ANDROID_HOME/platform-tools/adb wait-for-device shell 'while [[ -z $(getprop sys.boot_completed | tr -d "\r") ]]; do sleep 1; done; input keyevent 82' -$ANDROID_HOME/platform-tools/adb devices + $ANDROID_HOME/platform-tools/adb devices -echo "Emulator started" + echo "Emulator started" ``` ### Test on Azure-hosted devices -Add the [App Center Test](/azure/devops/pipelines/tasks/reference/app-center-test-v1) task to test the application in a hosted lab of iOS and Android devices. An [App Center](https://appcenter.ms) free trial is required, which must later be converted to paid. +To test your app in a hosted lab of Android devices in the Visual Studio App Center, add the [App Center Test](/azure/devops/pipelines/tasks/reference/app-center-test-v1) task to your pipeline. + +This task requires an [App Center](https://appcenter.ms) free trial account, which must be converted to paid after 30 days to continue to use the test lab. [Sign up for an App Center account](https://appcenter.ms/signup?utm_source=DevOps&utm_medium=Azure&utm_campaign=docs) before you use this task. + +> [!WARNING] +> Visual Studio App Center is scheduled for retirement on March 31, 2025. [Learn more about support timelines and recommended alternatives.](https://aka.ms/appcenter/retire) [Sign up with App Center](https://appcenter.ms/signup?utm_source=DevOps&utm_medium=Azure&utm_campaign=docs) first. -::: moniker range="> tfs-2018" +The following example runs an App Center test suite. The task uses a [service connection](../library/service-endpoints.md#visual-studio-app-center-service-connection) that you must set up. -[!INCLUDE [temp](../tasks/includes/yaml/AppCenterTestV1.md)] +For the complete task syntax and reference, see [App Center Test task](/azure/devops/pipelines/tasks/reference/app-center-test-v1). For more information, see [Using Azure DevOps for UI Testing](/appcenter/test-cloud/vsts-plugin). -::: moniker-end +```yml +- task: AppCenterTest@1 + inputs: + appFile: path/myapp.ipa + artifactsDirectory: '$(Build.ArtifactStagingDirectory)/AppCenterTest' + frameworkOption: 'appium' + appiumBuildDirectory: test/upload + serverEndpoint: 'My App Center service connection' + appSlug: username/appIdentifier + devices: 'devicelist' +``` ### Keep artifacts with the build record -Add the [Copy Files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish Build Artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks. Your APK gets stored with the build record or test, and gets deployed in later pipelines. For more information, see [Artifacts](../artifacts/pipeline-artifacts.md). - -::: moniker range="> tfs-2018" +To store your APK file with the build record or test and deploy it in subsequent pipelines, add the [Copy Files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish Build Artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks to your pipeline. For more information, see [Publish and download pipeline artifacts](../artifacts/pipeline-artifacts.md). ```yaml - task: CopyFiles@2 @@ -177,34 +158,36 @@ Add the [Copy Files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and contents: '**/*.apk' targetFolder: '$(build.artifactStagingDirectory)' - task: PublishBuildArtifacts@1 + inputs: + pathToPublish: $(Build.ArtifactStagingDirectory) + artifactName: MyBuildOutputs ``` -::: moniker-end - -## Deploy +### Deploy to App Center -### Add App Center +To distribute an app to a group of testers or beta users, or promote the app to Intune or Google Play, add the [App Center Distribute](/azure/devops/pipelines/tasks/reference/app-center-distribute-v3) task. The task requires a free [App Center](https://appcenter.ms) account that remains free of charge. -Add the [App Center Distribute](/azure/devops/pipelines/tasks/reference/app-center-distribute-v3) task to distribute an application to a group of testers or beta users, or promote the application to Intune or Google Play. A free [App Center](https://appcenter.ms) account is required (no payment is necessary). +The following example distributes an app to users. For the complete task syntax and reference, see [App Center Distribute](/azure/devops/pipelines/tasks/reference/app-center-distribute-v3). For more information, see [Deploy Azure DevOps Builds with App Center](/appcenter/distribution/vsts-deploy). -::: moniker range="> tfs-2018" - -[!INCLUDE [temp](../tasks/includes/yaml/AppCenterDistributeV1.md)] - -::: moniker-end +```yml +- task: AppCenterDistribute@3 + inputs: + serverEndpoint: 'AppCenter' + appSlug: '$(APP_CENTER_SLUG)' + appFile: '$(APP_FILE)' # Relative path from the repo root to the APK file you want to publish + symbolsOption: 'Android' + releaseNotesOption: 'input' + releaseNotesInput: 'Here are the release notes for this version.' + destinationType: 'groups' +``` -### Install Google Play +### Install the Google Play extension and deploy to Google Play -Install the [Google Play extension](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play) -and use the following tasks to automate interaction with Google Play. By default, these tasks authenticate to Google Play -using a [service connection](..//library/service-endpoints.md) that you configure. +To automate interaction with Google Play, install the [Google Play extension](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play) and then use the following tasks. By default, these tasks authenticate to Google Play by using a [service connection](..//library/service-endpoints.md) that you must configure. #### Release -Add the [Google Play Release](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play#user-content-google-play---release) -task to release a new Android app version to the Google Play store. - -::: moniker range="> tfs-2018" +To release a new Android app version to the Google Play store, add the [Google Play Release](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play#user-content-google-play---release) task to your pipeline. ```yaml - task: GooglePlayRelease@4 @@ -214,14 +197,9 @@ task to release a new Android app version to the Google Play store. track: 'internal' ``` -::: moniker-end - #### Promote -Add the [Google Play Promote](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play#user-content-google-play---promote) -task to promote a previously released Android application update from one track to another, such as `alpha` → `beta`. - -::: moniker range="> tfs-2018" +To promote a previously released Android application update from one track to another, such as `alpha` → `beta`, add the [Google Play Promote](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play#user-content-google-play---promote) task to your pipeline. ```yaml - task: GooglePlayPromote@3 @@ -232,14 +210,9 @@ task to promote a previously released Android application update from one track destinationTrack: 'alpha' ``` -::: moniker-end - #### Increase rollout -Add the [Google Play Increase Rollout](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play#user-content-google-play---increase-rollout) -task to increase the rollout percentage of an application that was previously released to the `rollout` track. - -::: moniker range="> tfs-2018" +To increase the rollout percentage of an application that was previously released to the `rollout` track, add the [Google Play Increase Rollout](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play#user-content-google-play---increase-rollout) task to your pipeline. ```yaml - task: GooglePlayIncreaseRollout@2 @@ -249,14 +222,9 @@ task to increase the rollout percentage of an application that was previously re userFraction: '0.5' # 0.0 to 1.0 (0% to 100%) ``` -::: moniker-end +#### Update status -#### Status update - -Add the [Google Play Status Update](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play#user-content-google-play---status-update) -task to update the rollout status for the application that was previously released to the `rollout` track. - -::: moniker range="> tfs-2018" +To update the rollout status for an application that was previously released to the `rollout` track, add the [Google Play Status Update](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play#user-content-google-play---status-update) task to your pipeline. ```yaml - task: GooglePlayStatusUpdate@2 @@ -267,48 +235,55 @@ task to update the rollout status for the application that was previously releas status: 'inProgress' # draft | inProgress | halted | completed ``` -::: moniker-end +## Create an app bundle -## Related extensions +You can build and sign an app bundle with an inline script and a secure file. -- [Codified Security](https://marketplace.visualstudio.com/items?itemName=codifiedsecurity.CodifiedSecurity) (Codified Security) -- [Google Play](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play) (Microsoft) -- [Mobile App Tasks for iOS and Android](https://marketplace.visualstudio.com/items?itemName=vs-publisher-473885.motz-mobile-buildtasks) (James Montemagno) -- [Mobile Testing Lab](https://marketplace.visualstudio.com/items?itemName=Perfecto.PerfectoCQ) (Perfecto Mobile) -- [React Native](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.react-native-extension) (Microsoft) +1. Download your keystore and store it as a [secure file](../library/secure-files.md) in the Azure Pipelines library. -## FAQ +1. Create variables for `keystore.password`, `key.alias`, and `key.password` in a [variable group](../library/variable-groups.md). -### Q: How do I create app bundles? +In your YAML pipeline: -A: You can build and sign your app bundle with an inline script and a secure file. To do so, first download your keystore and [store it as a secure file in the Library](../library/secure-files.md). Then, create variables for `keystore.password`, `key.alias`, and `key.password` in a [variable group](../library/variable-groups.md). +1. Add the [Download Secure File](/azure/devops/pipelines/tasks/reference/download-secure-file-v1) task to download the *app.keystore* secure file. -Next, use the [Download Secure File](/azure/devops/pipelines/tasks/reference/download-secure-file-v1) and [Bash](/azure/devops/pipelines/tasks/reference/bash-v3) tasks to download your keystore and build and sign your app bundle. + ```yaml + - task: DownloadSecureFile@1 + name: keyStore + displayName: "Download keystore from secure files" + inputs: + secureFile: app.keystore + ``` -In this YAML file, download an `app.keystore` secure file and use a bash script to generate an app bundle. Then, use [Copy Files](/azure/devops/pipelines/tasks/reference/copy-files-v2) to copy the app bundle. From there, create and save an artifact with [Publish Build Artifact](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) or use the [Google Play extension](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play) to publish. +1. Use the [Bash](/azure/devops/pipelines/tasks/reference/bash-v3) task with a Bash script to build and sign the app bundle. -::: moniker range="> tfs-2018" + ```yaml + - task: Bash@3 + displayName: "Build and sign App Bundle" + inputs: + targetType: "inline" + script: | + msbuild -restore $(Build.SourcesDirectory)/myAndroidApp/*.csproj -t:SignAndroidPackage -p:AndroidPackageFormat=aab -p:Configuration=$(buildConfiguration) -p:AndroidKeyStore=True -p:AndroidSigningKeyStore=$(keyStore.secureFilePath) -p:AndroidSigningStorePass=$(keystore.password) -p:AndroidSigningKeyAlias=$(key.alias) -p:AndroidSigningKeyPass=$(key.password) + ``` -```yaml -- task: DownloadSecureFile@1 - name: keyStore - displayName: "Download keystore from secure files" - inputs: - secureFile: app.keystore +1. Use the [Copy Files](/azure/devops/pipelines/tasks/reference/copy-files-v2) task to copy the app bundle. -- task: Bash@3 - displayName: "Build and sign App Bundle" - inputs: - targetType: "inline" - script: | - msbuild -restore $(Build.SourcesDirectory)/myAndroidApp/*.csproj -t:SignAndroidPackage -p:AndroidPackageFormat=aab -p:Configuration=$(buildConfiguration) -p:AndroidKeyStore=True -p:AndroidSigningKeyStore=$(keyStore.secureFilePath) -p:AndroidSigningStorePass=$(keystore.password) -p:AndroidSigningKeyAlias=$(key.alias) -p:AndroidSigningKeyPass=$(key.password) + ```yaml + - task: CopyFiles@2 + displayName: 'Copy deliverables' + inputs: + SourceFolder: '$(Build.SourcesDirectory)/myAndroidApp/bin/$(buildConfiguration)' + Contents: '*.aab' + TargetFolder: 'drop' + ``` -- task: CopyFiles@2 - displayName: 'Copy deliverables' - inputs: - SourceFolder: '$(Build.SourcesDirectory)/myAndroidApp/bin/$(buildConfiguration)' - Contents: '*.aab' - TargetFolder: 'drop' -``` +From here, you can either create and save an artifact with the [Publish Build Artifact](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) task or use the [Google Play extension](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play) to publish the app bundle. + +## Related extensions + +- [Codified Security](https://marketplace.visualstudio.com/items?itemName=codifiedsecurity.CodifiedSecurity) from Codified Security +- [Google Play](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.google-play) from Microsoft +- [Mobile App Tasks for iOS and Android](https://marketplace.visualstudio.com/items?itemName=vs-publisher-473885.motz-mobile-buildtasks) from James Montemagno +- [Mobile Testing Lab](https://marketplace.visualstudio.com/items?itemName=Perfecto.PerfectoCQ) from Perfecto Mobile +- [React Native](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.react-native-extension) from Microsoft -::: moniker-end diff --git a/docs/pipelines/ecosystems/containers/acr-template.md b/docs/pipelines/ecosystems/containers/acr-template.md index 08b37a15e4c..005b96ffeaa 100644 --- a/docs/pipelines/ecosystems/containers/acr-template.md +++ b/docs/pipelines/ecosystems/containers/acr-template.md @@ -1,104 +1,91 @@ --- -title: Build and push Docker images to Azure Container Registry with Docker templates -description: Build and push Docker images with Azure Pipelines and Docker templates +title: Use Docker YAML to build and push images to Azure Container Registry +description: Use an Azure Pipelines Docker template to create a YAML pipeline that builds and pushes a Docker image to Azure Container Registry. ms.topic: tutorial ms.assetid: 2ae9bd01-22ff-4147-a5bb-24d884812635 -ms.author: atulmal -author: azooinmyluggage -ms.date: 03/01/2022 +ms.author: ericvan +author: geekzter +ms.date: 08/12/2024 monikerRange: 'azure-devops' --- -# Build and push Docker images to Azure Container Registry using Docker templates +# Use Docker YAML to build and push Docker images to Azure Container Registry [!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] -In this step-by-step tutorial, you'll learn how to set up a continuous integration pipeline to build a containerized application. New pull requests trigger the pipeline to build and publish Docker images to Azure Container Registry. +This tutorial shows you how to use a pipeline based on an Azure Pipelines Docker template to build a containerized application and push it to Azure Container Registry. The template sets up a continuous integration YAML pipeline where new code repository changes trigger the pipeline to build and publish updated Docker images to the registry. -## Prerequisites - -* A GitHub account. [Create a free GitHub account](https://github.com), if you don't already have one. +The Docker container template pipeline uses Microsoft-hosted agents and creates a service principal-based service connection to Azure Container Registry. For a pipeline that does a similar process by using self-hosted agents and a service connection you create yourself, see [Build and push Docker images to Azure Container Registry](publish-to-acr.md). -* An Azure DevOps organization and a project. [Create a new organization](../../../organizations/accounts/create-organization.md) and/or a [new project](../../..//organizations/projects/create-project.md), if you don't already have one. +## Prerequisites -* An Azure account. Sign up for a [free Azure account](https://azure.microsoft.com/free/), if you don't already have one. +- An Azure account where you have permission to create and configure resources. If you don't have an Azure account, [sign up for a free account](https://azure.microsoft.com/free/). +- An Azure DevOps organization and project where you have permission to create pipelines and deploy apps. To create an organization or project, see [Create a new organization](../../../organizations/accounts/create-organization.md) or [Create a project in Azure DevOps](../../../organizations/projects/create-project.md). +- A GitHub account. -## Get the code + >[!IMPORTANT] + >When you use GitHub in the following procedures, you might be prompted to create a [GitHub service connection](../../library/service-endpoints.md#github-service-connection), sign in to GitHub, authenticate to GitHub organizations, install Azure Pipelines, or authorize Azure Pipelines. Follow the onscreen instructions to complete the process. For more information, see [Access to GitHub repositories](../../repos/github.md#access-to-github-repositories). -Fork or clone the *pipeline-javascript-docker* sample application: +## Get the sample app -``` -https://github.com/MicrosoftDocs/pipelines-javascript-docker -``` +In GitHub, fork or clone the [Sample Docker and Kubernetes Node.JS app](https://github.com/MicrosoftDocs/pipelines-javascript-docker) repository. ## Create a container registry -1. Sign in to [Azure](https://portal.azure.com/), and then select the **Azure Cloud Shell** button in the upper-right corner. +1. From the [Azure portal](https://portal.azure.com), sign in to Azure Cloud Shell by selecting the icon in the top menu bar. Make sure to use the **Bash** shell. - :::image type="content" source="../media/azure-cloud-shell.png" alt-text="Azure Cloud Shell button"::: + :::image type="content" source="../media/azure-cloud-shell.png" alt-text="Azure Cloud Shell button"::: -1. Run the following commands to create a resource group and an Azure Container Registry using the Azure CLI. +1. In the Cloud Shell, run the following commands to create a resource group and an Azure container registry by using the Azure CLI. The Container Registry name must be lowercase. - ```azurecli-interactive - # Create a resource group - az group create --name myapp-rg --location eastus - - # Create a container registry - az acr create --resource-group myapp-rg --name mycontainerregistry --sku Basic - ``` + ```azurecli + az group create --name myapp-rg --location eastus + az acr create --resource-group myapp-rg --name mycontainerregistry --sku Basic + ``` -> [!NOTE] -> A Container Registry name must be lowercase. +1. To deploy a Docker image to the Azure container registry, you must enable the admin user account for the registry, which is disabled by default. To enable the admin user for your registry, use the `--admin-enabled` parameter with the `az acr update` command. For more information and instructions, see [Admin account](/azure/container-registry/container-registry-authentication#admin-account). -You can also use the Azure portal web UI to create your Azure Container Registry. See the [Create a container registry](/azure/container-registry/container-registry-get-started-portal#create-a-container-registry) for details. + ```azurecli + az acr update -n --admin-enabled true + ``` -> [!IMPORTANT] -> You must enable the admin user account in order for you to deploy a Docker image from an Azure Container Registry. See [Container registry authentication](/azure/container-registry/container-registry-authentication#admin-account) for more details. +Alternatively, you can use the Azure portal UI to create your Azure container registry. For instructions, see [Create a container registry](/azure/container-registry/container-registry-get-started-portal#create-a-container-registry). Enable the admin account in **Properties** after you create the registry. ## Create the pipeline -1. Sign in to your Azure DevOps organization and navigate to your project. - -1. Select **Pipelines**, and then select **New Pipeline** to create a new pipeline. - - :::image type="content" source="../media/new-pipeline.png" alt-text="Create a new pipeline"::: - -1. Select **GitHub YAML**, and then select **Authorize Azure Pipelines** to provide the appropriate permissions to access your repository. +1. In your Azure DevOps project, select **Pipelines** > **New pipeline**, or **Create pipeline** if this pipeline is the first in the project. -1. You might be asked to sign in to GitHub. If so, enter your GitHub credentials, and then select your repository from the list of repositories. + :::image type="content" source="../media/new-pipeline.png" alt-text="Screenshot that shows the Create a new pipeline screen."::: + +1. Select **GitHub** as the location of your source code. +1. On the **Select a repository** screen, select your sample code repository. +1. On the **Configure your pipeline** screen, select the **Docker: Build and push an image to Azure Container Registry** pipeline. -1. From the **Configure** tab, select the **Docker - Build and push an image to Azure Container Registry** task. + :::image type="content" source="../media/docker-task.png" alt-text="Screenshot that shows the Build and push Docker image to Azure Container Registry pipeline selection."::: - :::image type="content" source="../media/docker-task.png" alt-text="Build and push Docker images to Azure Container Registry"::: +1. On the **Docker** screen, select your Azure subscription and then select **Continue**. +1. Select your **Container registry** from the dropdown menu, provide an **Image Name**, and then select **Validate and configure**. -1. Select your **Azure Subscription**, and then select **Continue**. + :::image type="content" source="../media/docker-container-registry.png" alt-text="Screenshot showing how to configure a Docker pipeline to build and publish an image to Azure Container Registry."::: -1. Select your **Container registry** from the dropdown menu, and then provide an **Image Name** to your container image. + Azure Pipelines generates an *azure-pipelines.yml* file that defines your pipeline. -1. Select **Validate and configure** when you are done. - - :::image type="content" source="../media/docker-container-registry.png" alt-text="A screenshot showing how to configure a docker pipeline to build and publish an image to Azure Container Registry"::: +1. Review the code in *azure-pipelines.yml*, and then select **Save and run**. - As Azure Pipelines creates your pipeline, it will: - - * Create a _Docker registry service connection_ to enable your pipeline to push images to your container registry. - - * Generate an *azure-pipelines.yml* file, which defines your pipeline. - -1. Review your pipeline YAML, and then select **Save and run** when you are ready. + :::image type="content" source="../media/review-your-pipeline.png" alt-text="Screenshot of the Save and run button in a new YAML pipeline."::: - :::image type="content" source="../media/review-your-pipeline.png" alt-text="Review your pipeline, save & run"::: +1. Optionally edit the **Commit message** and provide a description. Then select **Save and run** again to commit the *azure-pipelines.yml* file to your repository and start a build. -1. Add a **Commit message**, and then select **Save and run** to commit your changes and run your pipeline. +1. The build run page shows build details and progress. To watch your pipeline in action, select **Build** under **Jobs**. -1. As your pipeline runs, select the build job to watch your pipeline in action. + :::image type="content" source="../media/jobs-build.png" alt-text="Screenshot that shows the Build link on the job run page."::: - :::image type="content" source="../media/jobs-build.png" alt-text="Monitor builds"::: +## Pipeline details -## How we build your pipeline +The pipeline is generated from the [Docker container template](https://github.com/microsoft/azure-pipelines-yaml/blob/master/templates/docker-container.yml). The build stage uses the [Docker v2 task](/azure/devops/pipelines/tasks/reference/docker-v2) to build and push your Docker image to the container registry. -The pipeline that we just created in the previous section was generated from the _Docker container template_ YAML. The build stage uses the [Docker task](/azure/devops/pipelines/tasks/reference/docker-v2) `Docker@2` to build and push your Docker image to the container registry. +The Docker task uses a [Docker registry service connection](../../library/service-endpoints.md#docker-registry-service-connection) with service principal authentication to enable your pipeline to push images to your container registry. The Docker container template generates this service connection when it creates the pipeline. -```YAML +```yaml - stage: Build displayName: Build and push stage jobs: @@ -120,13 +107,13 @@ The pipeline that we just created in the previous section was generated from the ## Clean up resources -If you are not going to continue to use this application, you can delete the resources you created in this tutorial to avoid incurring ongoing charges. Run the following to delete your resource group. +When you finish using the resources you created in this tutorial, you can delete them to avoid incurring further charges. Run the following Cloud Shell command to delete your resource group and all the resources within it. -```azurecli-interactive +```azurecli az group delete --name myapp-rg ``` ## Related articles -- [Deploy to Azure Web App for Containers (Classic)](../../apps/cd/deploy-docker-webapp.md) +- [Deploy a custom container to Azure App Service with Azure Pipelines](../../apps/cd/deploy-docker-webapp.md) - [Docker Content Trust](./content-trust.md) diff --git a/docs/pipelines/ecosystems/containers/build-image.md b/docs/pipelines/ecosystems/containers/build-image.md index 91c2d212b90..fedfa961be7 100644 --- a/docs/pipelines/ecosystems/containers/build-image.md +++ b/docs/pipelines/ecosystems/containers/build-image.md @@ -2,9 +2,10 @@ title: Build container images to deploy apps description: Build Linux or Windows container images for app deployment using Azure Pipelines. ms.topic: quickstart +ms.custom: linux-related-content ms.assetid: 4fd7bae1-7484-4bb2-9bb9-a95ef17cb8fb -ms.date: 09/22/2022 -monikerRange: 'azure-devops' +ms.date: 01/23/2024 +monikerRange: '>=azure-devops-2020' --- # Quickstart: Build a container image to deploy apps using Azure Pipelines @@ -15,18 +16,27 @@ This quickstart shows how to build a container image for app deployment using Az ## Prerequisites -- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). -- A GitHub account. If you don't have one, [sign up for free](https://github.com/join). -- A GitHub repository with a Dockerfile. If you don't have a repository to use, fork the following repository, which contains a sample application and a Dockerfile: +| Category | Requirements | +|--------------|-------------| +| **Azure DevOps** | - An [Azure DevOps project](../../../organizations/projects/create-project.md).
      - An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../../licensing/concurrent-jobs.md) or you can request a free tier.
      - Basic knowledge of YAML and Azure Pipelines. For more information, see [Create your first pipeline](../../create-first-pipeline.md).
      - **Permissions:**
           To create a pipeline, users need to be in the **Contributors** group and the group needs to have *Create build pipeline* permission set to Allow. Members of the [Build Administrators and Project Administrators groups](../../../organizations/security/permissions.md#pipeline-or-build-object-level) can also manage pipelines. | +| **GitHub** | - A [GitHub](https://github.com) account.
      - A [GitHub service connection](../../library/service-endpoints.md) to authorize Azure Pipelines.| +| **Azure** | An [Azure subscription](https://azure.microsoft.com/free/). | - ``` + +## Fork the sample repository + +In your browser, go the following sample repository and fork it to your GitHub account. + + ```text https://github.com/MicrosoftDocs/pipelines-javascript-docker ``` ## Build a Linux or Windows image +::: moniker range=">=azure-devops" + 1. Sign in to your Azure DevOps organization, and go to your project. -1. Go to **Pipelines**, and select **New Pipeline**. +1. Go to **Pipelines**, and select **New Pipeline** or **Create Pipeline** if creating the first pipeline in the project. 1. Select **GitHub** as the location for your source code. 1. Select your repository, and then select **Starter pipeline**. @@ -56,10 +66,61 @@ This quickstart shows how to build a container image for app deployment using Az 1. When you're done, select **Save and run**. - When you add the **azure-pipelines.yml** file to your repository, you're prompted to add a commit message. +1. When you add the **azure-pipelines.yml** file to your repository, you're prompted to add a commit message. Enter a message, and then select **Save and run**. + +When using self-hosted agents, be sure that Docker is installed on the agent's host, and the Docker engine/daemon is running with elevated privileges. + +::: moniker-end + +::: moniker range="< azure-devops" + +To build the image, Docker must be installed on the agent's host and the Docker engine/daemon must be running with elevated privileges. Use the following steps to create your pipeline using the YAML pipeline editor. + +1. Go to your collection and create a project. +1. In your project, select **Pipelines**. +1. Select **Create Pipeline**. +1. Select **GitHub Enterprise Server** as the location for your source code. +1. If you haven't already, authorize Azure Pipelines to connect to your GitHub Enterprise Server account. + 1. Select **Connect to GitHub Enterprise Server**. + 1. Enter your account details, and then select **Verify and save**. +1. Select your repository. + If you're redirected to GitHub to install the Azure Pipelines app, select **Approve and install**. +1. To configure your pipeline, select the **Build a Docker image** template. +1. In the YAML pipeline editor, replace the contents of the YAML file with the following code. Replace the pool name with the name of the pool that contains your self-hosted agent with Docker capability. + +```yml +# Docker +# Build a Docker image +# https://docs.microsoft.com/azure/devops/pipelines/languages/docker + +trigger: +- main + +pool: + name: default + demands: docker + +variables: + imageName: 'pipelines-javascript-docker' + +steps: + - task: Docker@2 + displayName: Build an image + inputs: + repository: $(imageName) + command: build + Dockerfile: '$(Build.SourcesDirectory)/app/Dockerfile' + +``` + +1. Select **Save and run**. +1. On the **Save and run** page, select **Save and run** again. + +::: moniker-end -For more information, see the [Docker task](/azure/devops/pipelines/tasks/reference/docker-v2) used by this sample application. You can also directly invoke Docker commands using a [command line task](/azure/devops/pipelines/tasks/reference/cmd-line-v2). +For more information about building Docker images, see the [Docker task](/azure/devops/pipelines/tasks/reference/docker-v2) used by this sample application. You can also directly invoke Docker commands using a [command line task](/azure/devops/pipelines/tasks/reference/cmd-line-v2). +The container images are built and stored on the agent. You can push your image to Google Container Registry, Docker Hub, or Azure Container Registry. For more information, see [Push an image to Docker Hub or Google Container Registry](push-image.md) or [Push an image to Azure Container Registry](acr-template.md). ## Clean up resources If you don't plan to continue using this application, delete your pipeline and code repository. @@ -72,13 +133,13 @@ If you don't plan to continue using this application, delete your pipeline and c - You can build Windows container images using Microsoft-hosted Windows agents or Windows platform based self-hosted agents. All Microsoft-hosted Windows platform-based agents are shipped with the Moby engine and client needed for Docker builds. -- You currently can't use Microsoft-hosted macOS agents to build container images because the Moby engine needed for building the images isn't pre-installed on these agents. +- You currently can't use Microsoft-hosted macOS agents to build container images because the Moby engine needed for building the images isn't preinstalled on these agents. For more information, see the [Windows and Linux agent options available with Microsoft-hosted agents](../../agents/hosted.md). -### What pre-cached images are available on hosted agents? +### What precached Docker images are available on hosted agents? -To avoid spending long intervals pulling these images for every job from the container registry, some commonly used images are pre-cached on Microsoft-hosted agents. For the list of available pre-cached images, see the release notes in the [**azure-pipelines-image-generation** repository](https://github.com/actions/runner-images/releases). +To avoid spending long intervals pulling Docker images for every job from the container registry, some commonly used images are precached on Microsoft-hosted agents. ### How do I set the BuildKit variable for my Docker builds? @@ -109,9 +170,8 @@ steps: ### How can I use a self-hosted agent? -1. Before you create your container image, make sure to install Docker on your self-hosted machine. +Docker must be installed and the engine/daemon running on the agent's host. If Docker isn't installed on the agent's host, you can add the [Docker installer task](/azure/devops/pipelines/tasks/reference/docker-installer-v0) to your pipeline. You must add the **Docker Installer Task** before the **Docker Task**. -1. In your pipeline, *prior* to the [Docker task](/azure/devops/pipelines/tasks/reference/docker-v2) that builds your image, add the [Docker installer task](/azure/devops/pipelines/tasks/reference/docker-installer-v0). ### How can I create a script-based Docker build instead of using the Docker task? @@ -125,7 +185,7 @@ This command creates an image equivalent to one built with the Docker task. Inte ### Can I reuse layer caching during builds on Azure Pipelines? -If you're using Microsoft-hosted agents, every job is dispatched to a newly provisioned virtual machine, based on the image generated from [azure-pipelines-image-generation](https://github.com/microsoft/azure-pipelines-image-generation) repository templates. These virtual machines are cleaned up after the job completes. This ephemeral lifespan prevents reusing these virtual machines for subsequent jobs and the reuse of cached Docker layers. As a workaround, you can set up a multi-stage build that produces two images and pushes them to an image registry at an early stage. You can then tell Docker to use these images as a cache source with the `--cache-from` argument. +If you're using Microsoft-hosted agents, every job is dispatched to a newly provisioned virtual machine, based on the image generated from [**azure-pipelines-image-generation** repository](https://github.com/actions/runner-images) templates. These virtual machines are cleaned up after the job completes. This ephemeral lifespan prevents reusing these virtual machines for subsequent jobs and the reuse of cached Docker layers. As a workaround, you can set up a multi-stage build that produces two images and pushes them to an image registry at an early stage. You can then tell Docker to use these images as a cache source with the `--cache-from` argument. If you're using self-hosted agents, you can cache Docker layers without any workarounds because the ephemeral lifespan problem doesn't apply to these agents. diff --git a/docs/pipelines/ecosystems/containers/content-trust.md b/docs/pipelines/ecosystems/containers/content-trust.md index bdfd839f2ca..4388c29c2d6 100644 --- a/docs/pipelines/ecosystems/containers/content-trust.md +++ b/docs/pipelines/ecosystems/containers/content-trust.md @@ -3,8 +3,8 @@ title: Docker Content Trust in Azure Pipelines description: Use Azure Pipelines to sign and push trusted images to container registries ms.topic: quickstart ms.assetid: b66517e3-85de-4847-82f6-b1b0431d2915 -ms.author: atulmal -author: azooinmyluggage +ms.author: ericvan +author: geekzter ms.date: 02/11/2022 monikerRange: 'azure-devops' --- diff --git a/docs/pipelines/ecosystems/containers/publish-to-acr.md b/docs/pipelines/ecosystems/containers/publish-to-acr.md index c40a360afc6..0d3bf0c2e3b 100644 --- a/docs/pipelines/ecosystems/containers/publish-to-acr.md +++ b/docs/pipelines/ecosystems/containers/publish-to-acr.md @@ -4,12 +4,14 @@ description: How to create service connections and build and publish Docker imag ms.topic: tutorial ms.author: rabououn author: ramiMSFT -ms.date: 06/14/2023 +ms.date: 08/06/2024 monikerRange: 'azure-devops' --- # Build and publish Docker images to Azure Container Registry +[!INCLUDE [version-gt-eq-2022](../../../includes/version-gt-eq-2022.md)] + Using Azure Pipelines, you can set up a pipeline workflow to build and publish your Docker images to Azure Container Registry. In this article, you will learn how to: > [!div class="checklist"] @@ -27,8 +29,8 @@ Using Azure Pipelines, you can set up a pipeline workflow to build and publish y - [An Azure DevOps organization](../../../organizations/accounts/create-organization.md). - [An Azure DevOps project](../../..//organizations/projects/create-project.md). - - The [**Administrator** role for service connections](../../library/add-resource-protection.md) in your Azure DevOps project. +- The [**Administrator** role for service connections](../../library/add-resource-protection.md) in your Azure DevOps project. - An Azure account with an active subscription. [Sign up for free](https://azure.microsoft.com/free/) if you don't have one already. @@ -143,7 +145,7 @@ To use Managed Service Identity with Azure Pipelines to publish Docker images to ```PowerShell Invoke-WebRequest -URI -UseBasicParsing -OutFile - ##Example: Invoke-WebRequest -URI https://vstsagentpackage.azureedge.net/agent/2.213.2/vsts-agent-win-x64-2.213.2.zip -OutFile C:\vsts-agent-win-x64-2.213.2.zip + ##Example: Invoke-WebRequest -URI https://download.agent.dev.azure.com/agent/4.255.0/vsts-agent-win-x64-4.255.0.zip -OutFile C:\vsts-agent-win-x64-4.255.0.zip ``` 1. Run the following command to extract and create your agent. @@ -225,7 +227,7 @@ To use Managed Service Identity with Azure Pipelines to publish Docker images to 1. Select **Azure Container Registry**, and then select *Managed Service Identity* as your **Authentication Type**. -1. Enter your [Subscription ID](/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription) **Subscription name**, and your [Azure container registry login server](/azure/container-registry/container-registry-get-started-portal?tabs=azure-cli#create-a-container-registry). Paste your VM's system assigned Object ID that you created in the previous step in the **Tenant ID** text field. +1. Enter your [Subscription ID](/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription) **Subscription name**, and your [Azure container registry login server](/azure/container-registry/container-registry-get-started-portal?tabs=azure-cli#create-a-container-registry). Paste your VM's system assigned Tenant ID that you created in the previous step in the **Tenant ID** text field. 1. Enter a name for your service connection, and then check the **Grant access permission to all pipelines** checkbox. To select this option, you'll need the service connection **Administrator** role. @@ -253,6 +255,29 @@ To use Managed Service Identity with Azure Pipelines to publish Docker images to :::image type="content" source="../media/acr-service-connection.png" alt-text="A screenshot showing how to set up a docker registry service connection."::: +> [!NOTE] +> No additional permissions are required at the organization level for your service principal. See [Authenticate your Azure deployment pipeline by using service principals](/training/modules/authenticate-azure-deployment-pipeline-service-principals/) for more information. + +### [Workload Identity Federation](#tab/wif) + +1. From your project, select the gear icon ![gear icon](../../../media/icons/gear-icon.png) to navigate to your **Project settings**. + +1. Select **Service connections** from the left pane. + +1. Select **New service connection**, and then select **Docker Registry** then **Next**. + +1. Select **Azure Container Registry**, and then select *Workload Identity federation* as your **Authentication Type**. + +1. Select your **Subscription** from the dropdown menu. + +1. Select your **Azure container registry** from the list. + +1. Enter a name for your service connection. + +1. Select **Save** when you are done. + + :::image type="content" source="../media/docker-wif-connection.png" alt-text="A screenshot showing how to set up a docker registry service connection for workload identity federation."::: + * * * ## Build and publish to Azure Container Registry diff --git a/docs/pipelines/ecosystems/containers/push-image.md b/docs/pipelines/ecosystems/containers/push-image.md index 7ccf7fc4f85..79f19e78518 100644 --- a/docs/pipelines/ecosystems/containers/push-image.md +++ b/docs/pipelines/ecosystems/containers/push-image.md @@ -1,141 +1,276 @@ --- -title: Push an image -description: Push container images -ms.topic: conceptual +title: Use Azure Pipelines to build and push container images to registries +description: Use Azure Pipelines to build and push container images to Docker Hub and Azure Container Registry. +ms.topic: tutorial ms.assetid: 3ce59600-a7f8-4a5a-854c-0ced7fdaaa82 -ms.author: atulmal -author: azooinmyluggage -ms.date: 10/31/2022 +ms.author: jukullam +ms.date: 12/20/2024 monikerRange: 'azure-devops' +zone_pivot_groups: pipelines-docker-acr + --- -# Push an image +# Use Azure Pipelines to build and push container images to registries -[!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] +[!INCLUDE [version-eq-2022](../../../includes/version-eq-azure-devops.md)] -Use Azure Pipelines to push your image to a container registry such as [Azure Container Registry](/azure/container-registry/), Docker Hub, or Google Container Registry. Azure Container Registry is a managed registry service based on the open-source Docker Registry 2.0. +This article guides you through the creation of a pipeline to build and push a Docker image to an Azure Container Registry or Docker Hub. -For a tutorial on building and pushing images to a container registry, see [Build and push Docker images to Azure Container Registry](/azure/devops/pipelines/ecosystems/containers/acr-template). +## Prerequisites -To learn how to build a container image to deploy with Azure Pipelines, see [Build container images to deploy apps](build-image.md). +:::zone pivot="acr-registry" -## About the Docker task +| **Product** | **Requirements** | +|---|---| +| **Azure DevOps** | - An [Azure DevOps project](../../../organizations/projects/create-project.md).
      - **Permissions:**
          - To grant access to all pipelines in the project: You must be a member of the [Project Administrators group](../../../organizations/security/change-project-level-permissions.md).
          - To create service connections: You must have the *Administrator* or *Creator* role for [service connections](../../library/add-resource-protection.md).
      - If you're using a self-hosted agent, ensure Docker is installed and the Docker engine is running with elevated privileges. Microsoft-hosted agents have Docker preinstalled. | +| **GitHub** | - A [GitHub](https://github.com) account.
      - A GitHub repository with a Dockerfile. Use the [sample repository](https://github.com/MicrosoftDocs/pipelines-javascript-docker) if you don't have your own project.
      - A [GitHub service connection](../../library/service-endpoints.md#github-service-connection) to authorize Azure Pipelines.| +| **Azure** | - An [Azure subscription](https://azure.microsoft.com/free/).
      - An [Azure Container Registry](/azure/container-registry/container-registry-get-started-portal). | -You'll use the [Docker@2 task](/azure/devops/pipelines/tasks/reference/docker-v2) to build or push Docker images, login or logout, start or stop containers, or run a Docker command. +:::zone-end -The task uses a [Docker registry service connection](../../library/service-endpoints.md#docker-registry-service-connection) to log in and push to a container registry. The process for creating a Docker registry service connection differs depending on your registry. +::: zone pivot="docker-registry" -The Docker registry service connection stores credentials to the container registry before pushing the image. You can also directly reference service connections in Docker without an additional script task. +| **Product** | **Requirements** | +|---|---| +| **Azure DevOps** | - An [Azure DevOps project](../../../organizations/projects/create-project.md).
      - **Permissions:**
          - To grant access to all pipelines in the project: You must be a member of the [Project Administrators group](../../../organizations/security/change-project-level-permissions.md).
          - To create service connections: You must have the *Administrator* or *Creator* role for [service connections](../../library/add-resource-protection.md).
      - If you're using a self-hosted agent, ensure Docker is installed and the Docker engine is running with elevated privileges. Microsoft-hosted agents have Docker preinstalled. | +| **GitHub** | - A [GitHub](https://github.com) account.
      - A GitHub repository with a Dockerfile. Use the [sample repository](https://github.com/MicrosoftDocs/pipelines-javascript-docker) if you don't have your own project.
      - A [GitHub service connection](../../library/service-endpoints.md#github-service-connection) to authorize Azure Pipelines.| +| **Docker Hub** | - A [Docker Hub](https://hub.docker.com/) account.
      - A [Docker Hub](https://hub.docker.com/) image repository. | -## Create a Docker service connection +## Create a Docker registry service connection -You'll need to follow a different process to create a service connection for Azure Container Registry, Docker Hub, and Google Container Registry. +Before pushing container images to a registry, you need to create a service connection in Azure DevOps. This service connection stores the credentials required to securely authenticate with the container registry. For more information, see [Docker Registry service connections](../../library/service-endpoints.md#docker-registry-service-connection). -#### [Azure Container Registry](#tab/azure) -With the Azure Container Registry option, the subscription (associated with the Azure Active Directory identity of the user signed into Azure DevOps) and container registry within the subscription are used to create the service connection. +1. In your Azure DevOps project, select **Project settings** > **Service connections**. -When you create a new pipeline for a repository that contains a Dockerfile, Azure Pipelines will detect Dockerfile in the repository. To start this process, create a new pipeline and select the repository with your Dockerfile. + :::image type="content" source="../media/project-settings-selection.png" alt-text="Screenshot of Project settings selection."::: -1. From the **Configure** tab, select the **Docker - Build and push an image to Azure Container Registry** task. +1. Select **New service connection** and **Docker Registry**. - :::image type="content" source="../media/docker-task.png" alt-text="Screenshot of Build and push Docker images to Azure Container Registry."::: + :::image type="content" source="../media/docker-registry-selection.png" alt-text="Screenshot of Docker Registry selection."::: -1. Select your **Azure Subscription**, and then select **Continue**. +1. Select **Docker Hub** and enter the following information: -1. Select your **Container registry** from the dropdown menu, and then provide an **Image Name** to your container image. + | Field | Description | + |---|---| + | **Docker ID** | Enter your Docker ID. | + | **Docker Password** | Enter your Docker password. | + | **Service connection name** | Enter a name for the service connection. | + | **Grant access permission to all pipelines** | Select this option to grant access to all pipelines. | + + :::image type="content" source="../media/docker-hub-service-connection-dialog.png" alt-text="Screenshot of Docker Hub service connection dialog."::: + +1. Select **Verify and save**. + +:::zone-end + +## Create a pipeline to build and push a Docker image + +::: zone pivot="docker-registry" + +# [YAML](#tab/yaml) + +The Docker@2 task is used to build and push the image to the container registry. +The [Docker@2 task](/azure/devops/pipelines/tasks/build/docker) is designed to streamline the process of building, pushing, and managing Docker images within your Azure Pipelines. This task supports a wide range of Docker commands, including build, push, login, logout, start, stop, and run. + +Use the following steps to create a YAML pipeline that uses the Docker@2 task to build and push the image. -1. Select **Validate and configure** when you are done. - - :::image type="content" source="../media/docker-container-registry.png" alt-text="A screenshot showing how to configure a docker pipeline to build and publish an image to Azure Container Registry."::: - As Azure Pipelines creates your pipeline, it will: +1. In to your Azure DevOps project, select **Pipelines** and **New pipeline**. + +1. Select **GitHub** as the location of your source code and select your repository. + - If you're redirected to GitHub to sign in, enter your GitHub credentials. + - If you're redirected to GitHub to install the Azure Pipelines app, select **Approve and install**. +1. Select your repository. +1. Select the **Starter pipeline** template to create a basic pipeline configuration. +1. Replace the contents of **azure-pipelines.yml** with the following code: + + ```yaml + + trigger: + - main + + pool: + vmImage: 'ubuntu-latest' + + variables: + repositoryName: '' - * Create a _Docker registry service connection_ to enable your pipeline to push images to your container registry. + steps: + - task: Docker@2 + inputs: + containerRegistry: '' + repository: $(repositoryName) + command: 'buildAndPush' + Dockerfile: '**/Dockerfile' - * Generate an *azure-pipelines.yml* file, which defines your pipeline. + ``` + +1. Edit the pipeline YAML file as follows: + - Replace `` with the name of the repository in the container registry where you want to push the image. + - Replace `` with the name of the Docker registry service connection you created earlier. + +1. When you're done, select **Save and run** > **Save and run**. + +1. Select **Job** to view the logs and verify the pipeline ran successfully. + +# [Classic](#tab/classic) + +### Create a pipeline using the classic editor -For a more detailed overview, see [Build and Push to Azure Container Registry document](acr-template.md). +1. From your Azure DevOps project, select **Pipelines** and **New pipeline** +1. Select **Use the classic editor** from the **Where is your code?** page. +1. On the **Select a source** page, select **GitHub**. +1. Choose your repository and select **Continue**. +1. On the **Select a template** page, select **Empty pipeline** and **Apply**. +1. Select **ubuntu latest** for the **Agent Specification**. + :::image type="content" source="../media/classic-docker-pipeline-dialog.png" alt-text="Screenshot of classic Docker pipeline."::: -#### [Docker Hub](#tab/docker) +### Add the Docker@2 task to the pipeline -Choose the Docker Hub option under [Docker registry service connection](../../library/service-endpoints.md#docker-registry-service-connection) and provide your username and password to create a Docker service connection. +To build and push the image to the container registry, add the Docker@2 task to the pipeline. -#### [Google Container Registry](#tab/google) +1. Add a task to the **Agent job 1**. + + :::image type="content" source="../media/classic-pipeline-add-task.png" alt-text="Screenshot of add task icon."::: -To create a Docker service connection associated with Google Container Registry: +1. Select the **Docker** task, and **Add**. +1. Select the **buildAndPush** task. +1. For **Container Registry**, select the service connection you created earlier. If you don't have one, select ***+New*** to create a new Docker Hub service connection. -1. Open your project in the GCP Console and then open Cloud Shell -1. To save time typing your project ID and Compute Engine zone options, set default configuration values by running the following commands: + :::image type="content" source="../media/classic-pipeline-docker-2-build-and-push-task.png" alt-text="Screenshot of task to build and push image to Docker Hub."::: - ``` - gcloud config set project [PROJECT_NAME] - gcloud config set compute/zone [ZONE] - ``` +### Run the pipeline -1. Replace `[PROJECT_NAME]` with the name of your GCP project and replace `[ZONE]` with the name of the zone that you're going to use for creating resources. If you're unsure about which zone to pick, use `us-central1-a`. For example: +1. Select **Save and queue** > **Save and Queue**. +1. On the **Run pipeline** page, select **Save and run**. +1. Select **Job** to view the logs and verify the pipeline ran successfully. - ``` - gcloud config set project azure-pipelines-test-project-12345 - gcloud config set compute/zone us-central1-a - ``` -1. Enable the Container Registry API for your project: +--- + +:::zone-end - ``` - gcloud services enable containerregistry.googleapis.com - ``` +::: zone pivot="acr-registry" -1. Create a service account for Azure Pipelines to publish Docker images: +# [YAML](#tab/yaml) - ``` - gcloud iam service-accounts create azure-pipelines-publisher --display-name "Azure Pipelines Publisher" - ``` +1. Go to your Azure DevOps project and select **Pipelines** from the left-hand menu. -1. Assign the Storage Admin IAM role to the service account: +1. Select **New pipeline**. +1. Select **GitHub** as the location of your source code and select your repository. + - If you're redirected to GitHub to sign in, enter your GitHub credentials. + - If you're redirected to GitHub to install the Azure Pipelines app, select **Approve and install**. +1. Select the **Docker - Build and push an image to Azure Container Registry** template. +1. Select your Azure subscription and **Continue**. +1. Select your Container Registry, and then select **Validate and configure**. - ``` - PROJECT_NUMBER=$(gcloud projects describe \ - $(gcloud config get-value core/project) \ - --format='value(projectNumber)') + Example YAML pipeline: - AZURE_PIPELINES_PUBLISHER=$(gcloud iam service-accounts list \ - --filter="displayName:Azure Pipelines Publisher" \ - --format='value(email)') + ```yml + # Docker + # Build and push an image to Azure Container Registry + # https://docs.microsoft.com/azure/devops/pipelines/languages/docker + + trigger: + - main + + resources: + - repo: self + + variables: + # Container registry service connection established during pipeline creation + dockerRegistryServiceConnection: '7f9dc28e-5551-43ee-891f-33bf61a995de' + imageRepository: 'usernamepipelinesjavascriptdocker' + containerRegistry: 'repoistoryname.azurecr.io' + dockerfilePath: '$(Build.SourcesDirectory)/app/Dockerfile' + tag: '$(Build.BuildId)' - gcloud projects add-iam-policy-binding \ - $(gcloud config get-value core/project) \ - --member serviceAccount:$AZURE_PIPELINES_PUBLISHER \ - --role roles/storage.admin - ``` + # Agent VM image name + vmImageName: 'ubuntu-latest' + + stages: + - stage: Build + displayName: Build and push stage + jobs: + - job: Build + displayName: Build + pool: + vmImage: $(vmImageName) + steps: + - task: Docker@2 + displayName: Build and push an image to container registry + inputs: + command: buildAndPush + repository: $(imageRepository) + dockerfile: $(dockerfilePath) + containerRegistry: $(dockerRegistryServiceConnection) + tags: | + $(tag) + + ``` + +1. Select **Save and run** and **Save and run** again. +1. Select **Job** to view the logs and verify the pipeline ran successfully. + +The Docker template creates the service connection to your Azure Container Registry and uses the Docker@2 task to build and push the Docker image to the registry. + +The [Docker@2 task](/azure/devops/pipelines/tasks/reference/docker-v2) is designed to streamline the process of building, pushing, and managing Docker images within your Azure Pipelines. This task supports a wide range of Docker commands, including build, push, login, logout, start, stop, and run. -1. Generate a service account key: +# [Classic](#tab/classic) - ``` - gcloud iam service-accounts keys create \ - azure-pipelines-publisher.json --iam-account $AZURE_PIPELINES_PUBLISHER +### Create a pipeline using the classic editor - tr -d '\n' < azure-pipelines-publisher.json > azure-pipelines-publisher-oneline.json - ``` - Launch Code Editor by clicking the button in the upper-right corner of Cloud Shell: +1. From your Azure DevOps project, select **Pipelines** and **New pipeline**. +1. Select **Use the classic editor** from the **Where is your code?** page. +1. On the **Select a source** page, select **GitHub**. +1. Choose your repository and select **Continue**. +1. On the **Select a template** page, select **Empty pipeline** and **Apply**. +1. Select **ubuntu latest** for the **Agent Specification**. - > [!div class="mx-imgBorder"] - > ![Badge](../media/gcp-code-editor.png "GCP code editor") + :::image type="content" source="../media/classic-docker-pipeline-dialog.png" alt-text="Screenshot of classic Docker pipeline editor."::: -1. Open the file `named azure-pipelines-publisher-oneline.json`. You'll need the content of this file in one of the following steps: +### Add the Docker@2 task to the pipeline -1. In your Azure DevOps organization, select **Project settings** and then select **Pipelines -> Service connections**. +Add a **Docker@2** task to the pipeline to build and push the image to the container registry. -1. Select **New service connection** and choose **Docker Registry** +1. Add a task to **Agent job 1**. -1. In the dialog, enter values for the following fields: + :::image type="content" source="../media/classic-pipeline-add-task.png" alt-text="Screenshot of add task icon."::: - - **Docker Registry:** `https://gcr.io/[PROJECT-ID]`, where `[PROJECT-ID]` is the name of your GCP project. - - **Docker ID:** `_json_key` - - **Docker Password:** Paste the contents of `azure-pipelines-publisher-oneline.json` - - **Service connection name:** `gcrServiceConnection` +1. Select the **Docker** task, and **Add**. +1. Select the **buildAndPush** task. +1. Create a service connection select **+New**. -1. Select **Save** to create the service connection + :::image type="content" source="../media/classic-pipeline-new-service-connection-selection.png" alt-text="Screenshot of new service connection selection."::: + +1. Fill in the following fields: + + | Field | Description | + |---|---| + | **Subscription** | Select your Azure subscription. | + | **Azure container registry** | Select your Azure container registry. | + | **Service connection name** | Enter a name for the service connection. | + | **Grant access permission to all pipelines** | Select this option to grant access to all pipelines. | + + :::image type="content" source="../media/classic-pipeline-new-azure-container-registry-service-connection-dialog.png" alt-text="Screenshot of new Azure Container Registry service connection."::: + +1. Select **Save**. + +### Run the pipeline + +1. Select **Save and queue** > **Save and Queue**. +1. On the **Run pipeline** page, select **Save and run**. +1. Select **Job** to view the logs and verify the pipeline ran successfully. --- + +:::zone-end + +When using self-hosted agents, be sure that Docker is installed on the agent's host, and the Docker engine/daemon is running with elevated privileges. + +## Related articles + +- [Build a container image](build-image.md) +- [Docker content trust](content-trust.md) \ No newline at end of file diff --git a/docs/pipelines/ecosystems/customize-javascript.md b/docs/pipelines/ecosystems/customize-javascript.md index af36f348d94..c959b56c77b 100644 --- a/docs/pipelines/ecosystems/customize-javascript.md +++ b/docs/pipelines/ecosystems/customize-javascript.md @@ -2,8 +2,8 @@ title: Customize JavaScript for Azure Pipelines description: Customize how you use JavaScript with Azure Pipelines ms.topic: conceptual -ms.custom: seodec18, seo-javascript-september2019, contperf-fy20q4, devx-track-js, freshness-fy22q2, contperf-fy22q2 -ms.date: 06/20/2022 +ms.custom: devx-track-js, freshness-fy22q2 +ms.date: 11/02/2023 monikerRange: '<= azure-devops' --- @@ -26,9 +26,9 @@ If you need a version of Node.js and npm that isn't already installed on the Mic > The hosted agents are regularly updated, and setting up this task results in spending significant time updating to a newer minor version every time the pipeline is run. Use this task only when you need a specific Node version in your pipeline. ```yaml -- task: NodeTool@0 +- task: UseNode@1 inputs: - versionSpec: '16.x' # replace this value with the version that you need for your project + version: '16.x' # replace this value with the version that you need for your project ``` ::: moniker-end @@ -64,9 +64,9 @@ strategy: node_version: 18.x steps: -- task: NodeTool@0 +- task: UseNode@1 inputs: - versionSpec: $(node_version) + version: $(node_version) - script: npm install ``` @@ -75,7 +75,7 @@ steps: ::: moniker range="< azure-devops" -See [multi-configuration execution](../process/phases.md#parallelexec). +See [multi-configuration execution](../process/phases.md#multi-job-configuration). ::: moniker-end @@ -131,7 +131,7 @@ Use the [npm](/azure/devops/pipelines/tasks/reference/npm-v1) or [command-line]( ## Manage dependencies -In your build, use [Yarn](https://yarnpkg.com) or Azure Artifacts to download packages from the public npm registry. This registry is a type of private npm registry that you specify in the .npmrc file. +In your build, use [Yarn](https://yarnpkg.com) or Azure Artifacts to download packages from the public npm registry. This registry is a type of private npm registry that you specify in the `.npmrc` file. ### Use npm @@ -176,7 +176,7 @@ Use the [npm](/azure/devops/pipelines/tasks/reference/npm-v1) or [npm authentica ::: moniker-end -::: moniker range=">= tfs-2018" +::: moniker range="<=azure-devops" If your builds occasionally fail because of connection issues when you restore packages from the npm registry, you can use Azure Artifacts with [upstream sources](../../artifacts/concepts/upstream-sources.md), @@ -290,11 +290,9 @@ The following example uses [nyc](https://github.com/istanbuljs/nyc), the Istanbu npm test -- --reporter mocha-junit-reporter --reporter-options mochaFile=./test-results.xml displayName: 'Build code coverage report' -- task: PublishCodeCoverageResults@1 +- task: PublishCodeCoverageResults@2 inputs: - codeCoverageTool: Cobertura # or JaCoCo summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml' - reportDirectory: '$(System.DefaultWorkingDirectory)/**/coverage' ``` ::: moniker-end @@ -405,7 +403,7 @@ All the dependencies for your React and Vue apps are captured in your *package.j ::: moniker-end -The build files are in a new folder, `dist` (for Vue) or `build` (for React). This snippet builds an artifact, `www`, that is ready for release. It uses the [Node Installer](/azure/devops/pipelines/tasks/reference/node-tool-v0), [Copy File](/azure/devops/pipelines/tasks/reference/copy-files-v2)s, and [Publish Build Artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks. +The build files are in a new folder, `dist` (for Vue) or `build` (for React). This snippet builds an artifact - `www` - that is ready for release. It uses the [Node Installer](/azure/devops/pipelines/tasks/reference/node-tool-v0), [Copy File](/azure/devops/pipelines/tasks/reference/copy-files-v2)s, and [Publish Build Artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks. ::: moniker range=">=azure-devops-2020" @@ -417,9 +415,9 @@ pool: vmImage: 'ubuntu-latest' steps: -- task: NodeTool@0 +- task: UseNode@1 inputs: - versionSpec: '16.x' + version: '16.x' displayName: 'Install Node.js' - script: | @@ -536,7 +534,7 @@ Grunt gets preinstalled on Microsoft-hosted agents. To run the grunt command in - script: grunt # include any additional options that are needed ``` -If the steps in your `Gruntfile.js` file require authentication with a npm registry: +If the steps in your `Gruntfile.js` file require authentication with an npm registry: ```yaml - task: npmAuthenticate@0 @@ -707,7 +705,7 @@ A: [Build, release, and test tasks](../tasks/index.md) ### Q: How do I fix a pipeline failure with the message 'FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory'? -A: This failure type happens when the Node.js package has exceeded the memory usage limit. To resolve the issue, add a variable like `NODE_OPTIONS` and assign it a value of ***--max_old_space_size=16384***. +A: This failure type happens when the Node.js package exceeds the memory usage limit. To resolve the issue, add a variable like `NODE_OPTIONS` and assign it a value of ***--max_old_space_size=16384***. ### Q: How can I version my npm packages as part of the build process? @@ -734,9 +732,9 @@ steps: # Checking out connected repo workingFile: .npmrc customEndpoint: 'my-npm-connection' -- task: NodeTool@0 +- task: UseNode@1 inputs: - versionSpec: '16.x' + version: '16.x' displayName: 'Install Node.js' - script: | diff --git a/docs/pipelines/ecosystems/customize-python.md b/docs/pipelines/ecosystems/customize-python.md index 736318ffb13..d8947831629 100644 --- a/docs/pipelines/ecosystems/customize-python.md +++ b/docs/pipelines/ecosystems/customize-python.md @@ -1,21 +1,29 @@ --- -title: Customize Python for Azure Pipelines -description: Customize how you use Python with Azure Pipelines +title: Customize Python pipelines +description: See how to use Azure Pipelines to customize, build, test, package, and deliver Python apps and code. ms.topic: conceptual -ms.custom: contperf-fy22q4, devx-track-python -ms.date: 12/14/2022 +ms.custom: devx-track-python +ms.date: 07/12/2024 monikerRange: '<= azure-devops' --- -# Customize Python for Azure Pipelines +# Customize Python pipelines -You can use Azure Pipelines to build your Python apps without having to set up any infrastructure of your own. Tools that you commonly use to build, test, and run Python apps - like pip - get pre-installed on [Microsoft-hosted agents](../agents/hosted.md) in Azure Pipelines. +This article describes how to customize building, testing, packaging, and delivering Python apps and code in Azure Pipelines. To create your first pipeline with Python, see the [Python quickstart](python.md). -To create your first pipeline with Python, see the [Python quickstart](python.md). +::: moniker range=">=azure-devops" +With [Microsoft-hosted agents](../agents/hosted.md) in Azure Pipelines, you can build your Python apps without having to set up your own infrastructure. Tools that you commonly use to build, test, and run Python apps, including `pip`, are preinstalled. + +You might need to [request the free grant of parallel jobs](https://aka.ms/azpipelines-parallelism-request) or purchase a [parallel job](../licensing/concurrent-jobs.md) to run your pipelines. +::: moniker-end + +::: moniker range="< azure-devops" +To build Python apps with Azure Pipelines, you need a [self-hosted agent](../agents/agents.md#self-hosted-agents) with Python installed. To install Python on your agent, see [UsePythonVersion](/azure/devops/pipelines/tasks/reference/use-python-version-v0#how-can-i-configure-a-self-hosted-agent-to-use-this-task). +::: moniker-end ### Use a specific Python version -To use a specific version of Python in your pipeline, add the [Use Python Version task](/azure/devops/pipelines/tasks/reference/use-python-version-v0) to *azure-pipelines.yml*. This snippet sets the pipeline to use Python 3.11: +To use a specific version of Python in your pipeline, add the [Use Python version task](/azure/devops/pipelines/tasks/reference/use-python-version-v0) to *azure-pipelines.yml*. The following example YAML pipeline definition sets the pipeline to use Python 3.11. ```yaml steps: @@ -26,13 +34,13 @@ steps: ### Use multiple Python versions -To run a pipeline with multiple Python versions, for example to test a package against those versions, define a `job` with a `matrix` of Python versions. Then set the `UsePythonVersion` task to reference the `matrix` variable. +To run a pipeline with multiple Python versions, for example to test a package against those versions, define a `job` with a `matrix` of Python versions. Then set the `UsePythonVersion` task to reference the `matrix` variable. For example: ```yaml jobs: - job: 'Test' pool: - vmImage: 'ubuntu-latest' # other options: 'macOS-latest', 'windows-latest' + vmImage: 'ubuntu-latest' strategy: matrix: Python38: @@ -48,17 +56,17 @@ jobs: versionSpec: '$(python.version)' ``` -You can add tasks to run using each Python version in the matrix. +You can add tasks that use each Python version in the matrix. ## Run Python scripts -To run Python scripts in your repository, use a `script` element and specify a filename. For example: +To run Python scripts from your repository, use a `script` element and specify a filename. For example: ```yaml - script: python src/example.py ``` -You can also run inline Python scripts with the [Python Script task](/azure/devops/pipelines/tasks/reference/python-script-v0): +You can also use the [Python script task](/azure/devops/pipelines/tasks/reference/python-script-v0) to run inline Python scripts. ```yaml - task: PythonScript@0 @@ -69,7 +77,7 @@ You can also run inline Python scripts with the [Python Script task](/azure/devo print('Hello world 2') ``` -To parameterize script execution, use the `PythonScript` task with `arguments` values to pass arguments into the executing process. You can use `sys.argv` or the more sophisticated `argparse` library to parse the arguments. +To parameterize script execution, use the `PythonScript` task with `arguments` values to pass arguments into the running process. You can use `sys.argv` or the more sophisticated `argparse` library to parse the arguments. ```yaml - task: PythonScript@0 @@ -89,7 +97,7 @@ To parameterize script execution, use the `PythonScript` task with `arguments` v ### Install dependencies -You can use scripts to install specific PyPI packages with `pip`. For example, this YAML installs or upgrades `pip` and the `setuptools` and `wheel` packages. +You can use scripts to install specific PyPI packages with `pip`. The following example installs or upgrades `pip` and the `setuptools` and `wheel` packages. ```yaml - script: python -m pip install --upgrade pip setuptools wheel @@ -98,7 +106,7 @@ You can use scripts to install specific PyPI packages with `pip`. For example, t ### Install requirements -After you update `pip` and friends, a typical next step is to install dependencies from *requirements.txt*: +After you update `pip` and friends, a typical next step is to install dependencies from *requirements.txt*. ```yaml - script: pip install -r requirements.txt @@ -106,14 +114,13 @@ After you update `pip` and friends, a typical next step is to install dependenci ``` - ## Run tests -Use scripts to install and run various tests in your pipeline. +You can use scripts to install and run various tests in your pipeline. ### Run lint tests with flake8 -To install or upgrade `flake8` and use it to run lint tests, use this YAML: +The following YAML code installs or upgrades `flake8` and uses it to run lint tests. ```yaml - script: | @@ -124,7 +131,7 @@ To install or upgrade `flake8` and use it to run lint tests, use this YAML: ### Test with pytest and collect coverage metrics with pytest-cov -Use this YAML to install `pytest` and `pytest-cov`, run tests, output test results in JUnit format, and output code coverage results in Cobertura XML format: +The following YAML code installs `pytest` and `pytest-cov` and runs tests, outputting test results in JUnit format and outputting code coverage results in Cobertura XML format. ```yaml - script: | @@ -133,10 +140,9 @@ Use this YAML to install `pytest` and `pytest-cov`, run tests, output test resul pytest --doctest-modules --junitxml=junit/test-results.xml --cov=. --cov-report=xml displayName: 'pytest' ``` -::: moniker range=">=azure-devops-2020" ### Run tests with Tox -Azure Pipelines can run parallel Tox test jobs to split up the work. On a development computer, you have to run your test environments in series. This sample uses `tox -e py` to run whichever version of Python is active for the current job. +Azure Pipelines can run parallel Tox test jobs to split up the work. On a development computer, you have to run your test environments in series. The following example uses `tox -e py` to run whichever version of Python is active for the current job. ```yaml - job: @@ -167,7 +173,7 @@ Azure Pipelines can run parallel Tox test jobs to split up the work. On a develo ### Publish test results -Add the [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) to publish JUnit or xUnit test results to the server: +Add the [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) to publish JUnit or xUnit test results to the server. ```yaml - task: PublishTestResults@2 @@ -179,10 +185,10 @@ Add the [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publ ### Publish code coverage results -Add the [Publish Code Coverage Results task](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v1) to publish code coverage results to the server. You can see coverage metrics in the build summary and download HTML reports for further analysis. +Add the [Publish code coverage results task](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v2) to publish code coverage results to the server. You can see coverage metrics in the build summary, and download HTML reports for further analysis. ```yaml -- task: PublishCodeCoverageResults@1 +- task: PublishCodeCoverageResults@2 inputs: codeCoverageTool: Cobertura summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/coverage.xml' @@ -190,7 +196,7 @@ Add the [Publish Code Coverage Results task](/azure/devops/pipelines/tasks/refer ## Package and deliver code -To authenticate with `twine`, use the [Twine Authenticate task](/azure/devops/pipelines/tasks/reference/twine-authenticate-v1) to store authentication credentials in the `PYPIRC_PATH` environment variable. +To authenticate with `twine`, use the [Python twine upload authenticate task](/azure/devops/pipelines/tasks/reference/twine-authenticate-v1) to store authentication credentials in the `PYPIRC_PATH` environment variable. ```yaml - task: TwineAuthenticate@0 @@ -199,7 +205,7 @@ To authenticate with `twine`, use the [Twine Authenticate task](/azure/devops/pi pythonUploadServiceConnection: '' ``` -Then, add a custom [script](/azure/devops/pipelines/yaml-schema/steps-script) that uses `twine` to publish your packages. +Then add a custom [script](/azure/devops/pipelines/yaml-schema/steps-script) that uses `twine` to publish your packages. ```yaml - script: | @@ -208,9 +214,10 @@ Then, add a custom [script](/azure/devops/pipelines/yaml-schema/steps-script) th You can also use Azure Pipelines to [build an image](containers/build-image.md) for your Python app and [push it to a container registry](containers/push-image.md). -::: moniker-end - -## Related extensions +## Related content -- [Azure DevOps plugin for PyCharm (IntelliJ)](https://plugins.jetbrains.com/plugin/7981) (Microsoft) -- [Python in Visual Studio Code](https://code.visualstudio.com/docs/python) (Microsoft) +- [Azure DevOps plugin for PyCharm (IntelliJ)](https://plugins.jetbrains.com/plugin/7981) +- [Getting Started with Python in VS Code](https://code.visualstudio.com/docs/python) +- [Build and publish a Python app](python.md) +- [Azure Pipelines task reference](/azure/devops/pipelines/tasks/reference) +- [Azure Pipelines agents](../agents/agents.md) \ No newline at end of file diff --git a/docs/pipelines/ecosystems/deploy-linux-vm.md b/docs/pipelines/ecosystems/deploy-linux-vm.md index 5f217052213..e0e57776336 100644 --- a/docs/pipelines/ecosystems/deploy-linux-vm.md +++ b/docs/pipelines/ecosystems/deploy-linux-vm.md @@ -1,143 +1,112 @@ --- -title: Deploy a Linux VM to an environment +title: Deploy to Linux VMs description: Deploy a web application to a web server on a Linux VM with an environment. ms.assetid: 9EBB0342-7FD2-473C-9809-9BCA2250CBC3 ms.topic: quickstart -ms.custom: seodec18, freshness-fy22q2 -ms.date: 01/24/2023 -monikerRange: 'azure-devops' +ms.custom: freshness-fy22q2, linux-related-content +ms.date: 07/18/2024 +monikerRange: 'azure-devops' --- -# Deploy to a Linux Virtual Machine +# Deploy to Linux VMs in an environment [!INCLUDE [version-eq-azure-devops](../../includes/version-gt-eq-2020.md)] -Learn how to set up an Azure DevOps pipeline for multi-virtual machine deployments that uses an [environment](../process/environments.md) and [virtual machine resources](../process/environments-virtual-machines.md). - -Use the instructions in this article for any app that publishes a web deployment package. - -> [!NOTE] -> If you want to deploy your application to a Linux virtual machine using the classic editor, see [Deploy web apps to Linux virtual machines (VMs)](../apps/cd/deploy-linuxvm-deploygroups.md). +In this quickstart, you learn how to set up an Azure DevOps pipeline for deployment to multiple Linux [virtual machine (VM) resources](../process/environments-virtual-machines.md) in an [environment](../process/environments.md). You can use these instructions for any app that publishes a web deployment package. ## Prerequisites - An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). -- An active Azure DevOps organization. [Sign up for Azure Pipelines](../get-started/pipelines-sign-up.md). -- A Linux virtual machine (VM) hosted in Azure. - - To install a JavaScript or Node.js app, set up a Linux VM with Nginx in Azure, see [Create a Linux VM with Azure CLI](/azure/virtual-machines/linux/quick-create-cli). - - To deploy a Java Spring Boot and Spring Cloud based apps, create a Linux VM in Azure using [Java 13 on Ubuntu 20.04](https://azuremarketplace.microsoft.com/marketplace/apps/azul.azul-zulu13-ubuntu-2004) template, which provides a fully supported OpenJDK-based runtime. +- An Azure DevOps organization and project. [Sign up for Azure Pipelines](../get-started/pipelines-sign-up.md). +#### [JavaScript](#tab/javascript) -## Get your sample code +For JavaScript or Node.js apps, [at least two Linux VMs set up with Nginx on Azure](/azure/virtual-machines/linux/quick-create-cli). -#### [JavaScript](#tab/javascript) +#### [Java](#tab/java) + +For Java Spring Boot and Spring Cloud based apps, [at least two Linux VMs created in Azure using the Java 13 on Ubuntu 20.04 template](https://azuremarketplace.microsoft.com/marketplace/apps/azul.azul-zulu13-ubuntu-2004), which provides a fully supported OpenJDK-based runtime. + +--- + +## Fork the sample code [!INCLUDE [include](includes/get-code-before-sample-repo-option-to-use-own-code.md)] +#### [JavaScript](#tab/javascript) + ``` https://github.com/MicrosoftDocs/pipelines-javascript ``` #### [Java](#tab/java) -[!INCLUDE [include](includes/get-code-before-sample-repo-option-to-use-own-code.md)] - ``` https://github.com/spring-projects/spring-petclinic ``` > [!NOTE] -> Petclinic is a [Spring Boot](https://spring.io/guides/gs/spring-boot) application built using [Maven](https://spring.io/guides/gs/maven/). +> Petclinic is a [Spring Boot](https://spring.io/guides/gs/spring-boot) application built using [Maven](https://docs.spring.io/spring-boot/docs/2.3.0.RELEASE/maven-plugin/reference/html/#build-image). + +--- +## Create an environment with Linux VMs -* * * +You can add VMs as resources within [environments](../process/environments.md) and target them for multi-VM deployments. The deployment history for the environment provides traceability from the VM to the commit. -## Create an environment with virtual machines +### Add a VM resource -You can add virtual machines as resources within [environments](../process/environments.md) and target them for multi-VM deployments. The deployment history view provides traceability from the VM to the commit. +1. In your Azure DevOps project, go to **Pipelines** > **Environments** and then select **Create environment** or **New environment**. +1. On the first **New environment** screen, add a **Name** and an optional **Description**. +1. Under **Resource**, select **Virtual machines**, and then select **Next**. +1. On the next **New environment** screen, choose Linux under **Operating system**. +1. Copy the Linux registration script. The script is the same for all the Linux VMs added to the environment. -1. Sign into your Azure DevOps organization and navigate to your project. -2. Go to the Pipelines page and select **Environments** > **Create Environment**. -3. Specify a **Name** (required) for the environment and a **Description**. -4. Choose **Virtual Machines** as a **Resource** to be added to the environment, and then select **Next**. -5. Choose Linux for the **Operating System** and copy the registration script. -6. Run the registration script on each of the target VMs registered with the environment. + :::image type="content" source="media/vm-creation.png" alt-text="Screenshot of VM creation."::: > [!NOTE] - > - The Personal Access Token (PAT) of the signed in user gets pre-inserted in the script and expires after three hours. - > - If your VM already has any agent running on it, provide a unique name to register with the environment. -7. Once VM is registered, it will start appearing as an environment resource under **Resources**. + > The Personal Access Token (PAT) of the signed in user is pre-inserted in the script and expires after three hours. + +1. Select **Close**, and note that the new environment is created. +1. Run the copied script on each target VM that you want to register with the environment. - :::image type="content" source="media/vm-creation.png" alt-text="Screenshot of VM creation."::: + > [!NOTE] + > If the VM already has another agent running on it, provide a unique name for **agent** to register with the environment. -8. To add more VMs, copy the script again. Select **Add resource** and choose **Virtual Machines**. This script is the same for all the VMs you want to add to the same environment. - - Each machine interacts with Azure Pipelines to coordinate deployment of your app. +Once the VM is registered, it appears as a resource under the **Resources** tab of the environment. - :::image type="content" source="media/vm-resourceview.png" alt-text="Screenshot of VM resource view."::: +:::image type="content" source="media/vm-resourceview.png" alt-text="Screenshot of VM resource view."::: -9. You can add or remove tags for the VM. Select on the dots at the end of each VM resource in **Resources**. - - Tags limit deployment to specific VMs when the environment's used in a deployment job. Each tag is limited to 256 characters. There's no limit to the number of tags you can create. - - :::image type="content" source="media/vm-tags.png" alt-text="Screenshot of tags view."::: + To copy the script again for creating more resources, for example if your PAT expires, select **Add resource** on the environment's page. -* * * +### Add and manage tags -## Define your CI build pipeline +Tags are a way to target a specific set of VMs in an environment for deployment. There's no limit to the number of tags that you can use. Tags are limited to 256 characters each. -You need a CI build pipeline that publishes your web app. You also need a deployment script that can be run locally on the Ubuntu server. Set up a CI build pipeline based on the runtime you want to use. +You can add tags or remove tags for VMs in the interactive registration script or through the UI by selecting **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: for a VM resource. For this quickstart, assign a different tag to each VM in your environment. -1. Sign in to your Azure DevOps organization and go to your project. +:::image type="content" source="media/vm-tags.png" alt-text="Screenshot of tags view."::: -2. In your project, go to the **Pipelines** page, and then choose the action to create a new pipeline. +## Define a CI build pipeline -3. Select **GitHub** as the location of your source code. +You need a continuous integration (CI) build pipeline that publishes your web app, and a deployment script to run locally on the Linux server. Set up your CI build pipeline based on the runtime you want to use. - You may be redirected to GitHub to sign in. If so, enter your GitHub credentials. +>[!IMPORTANT] +>During GitHub procedures, you might be prompted to create a [GitHub service connection](../library/service-endpoints.md#github-service-connection) or be redirected to GitHub to sign in, install Azure Pipelines, or authorize Azure Pipelines. Follow the onscreen instructions to complete the process. For more information, see [Access to GitHub repositories](../repos/github.md#access-to-github-repositories). -4. When the list of repositories appears, select the sample app repository that you want. +1. In your Azure DevOps project, select **Pipelines** > **Create Pipeline**, and then select **GitHub** as the location of your source code. +1. On the **Select a repository** screen, select your forked sample repository. +1. On the **Configure your pipeline** screen, select **Starter pipeline**. Azure Pipelines generates a YAML file called *azure-pipelines.yml* for your pipeline. +1. Select the dropdown caret next to **Save and run**, select **Save**, and then select **Save** again. The file is saved to your forked GitHub repository. -5. Azure Pipelines analyzes your repository and recommends a suitable pipeline template. +### Edit the code - #### [Java](#tab/java) - - Select the **starter** template and copy this YAML snippet to build your Java project and run tests with Apache Maven. You'll add to this YAML in future steps. : - - ```YAML - trigger: - - main - - pool: - vmImage: ubuntu-latest - - stages: - - stage: Build - displayName: Build stage - jobs: - - job: Build - displayName: Build Maven Project - steps: - - task: Maven@4 - displayName: 'Maven Package' - inputs: - mavenPomFile: 'pom.xml' - - task: CopyFiles@2 - displayName: 'Copy Files to artifact staging directory' - inputs: - SourceFolder: '$(System.DefaultWorkingDirectory)' - Contents: '**/target/*.?(war|jar)' - TargetFolder: $(Build.ArtifactStagingDirectory) - - upload: $(Build.ArtifactStagingDirectory) - artifact: drop - ``` - - For more information, review the steps in [Build your Java app with Maven](java.md) for creating a build. - - #### [JavaScript](#tab/javascript) - - Select the **starter** template and copy this YAML snippet to build a general Node.js project with npm. You'll add to this YAML in future steps. - - ```YAML +Select **Edit**, and replace the contents of the *azure-pipelines.yml* file with the following code. You add to this YAML in future steps. + +#### [JavaScript](#tab/javascript) + +The following code builds your Node.js project with npm. + +```yaml trigger: - main @@ -151,9 +120,9 @@ You need a CI build pipeline that publishes your web app. You also need a deploy - job: Build displayName: Build steps: - - task: NodeTool@0 + - task: UseNode@1 inputs: - versionSpec: '16.x' + version: '16.x' displayName: 'Install Node.js' - script: | npm install @@ -170,113 +139,151 @@ You need a CI build pipeline that publishes your web app. You also need a deploy replaceExistingArchive: true - upload: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip artifact: drop - ``` - For more guidance, review the steps mentioned in [Build your Node.js app with gulp](javascript.md) for creating a build. - - - Select **Save and run** > **Commit directly to the main branch** > **Save and run**. - - A new run starts. Wait for the run to complete. - - * * * +``` -## Define CD steps to deploy to the Linux VM +For more information, review the steps in [Build your Node.js app with gulp](javascript.md) for creating a build. -1. Edit your pipeline and add a [deployment job](../process/deployment-jobs.md) by referencing the environment and the VM resources you created earlier. Update `tags` to refer to tags for your virtual machine. +#### [Java](#tab/java) - ```YAML - jobs: - - deployment: VMDeploy - displayName: Web deploy - environment: - name: - resourceType: VirtualMachine - tags: web1 # Update or remove value to match your tag - strategy: - ``` - To learn more about the `environment` keyword and resources targeted by a deployment job, [see the YAML schema](/azure/devops/pipelines/yaml-schema/jobs-deployment-environment). +The following code builds your Java project and runs tests with Apache Maven. + +```yaml + trigger: + - main + + pool: + vmImage: ubuntu-latest + + stages: + - stage: Build + displayName: Build stage + jobs: + - job: Build + displayName: Build Maven Project + steps: + - task: Maven@4 + displayName: 'Maven Package' + inputs: + mavenPomFile: 'pom.xml' + - task: CopyFiles@2 + displayName: 'Copy Files to artifact staging directory' + inputs: + SourceFolder: '$(System.DefaultWorkingDirectory)' + Contents: '**/target/*.?(war|jar)' + TargetFolder: $(Build.ArtifactStagingDirectory) + - upload: $(Build.ArtifactStagingDirectory) + artifact: drop +``` + +For more information, review the steps in [Build your Java app with Maven](java.md) for creating a build. -2. Select specific sets of VMs from the environment to receive the deployment by specifying the **tags** that you've defined for each VM in the environment. +--- - For more information, see the [complete YAML schema for deployment job](/azure/devops/pipelines/yaml-schema/jobs-deployment). +## Run your pipeline -3. Specify either `runOnce` or `rolling` as a deployment strategy. +Select **Validate and save**, then select **Save**, select **Run**, and select **Run** again. - `runOnce` is the simplest deployment strategy. All the life-cycle hooks, namely `preDeploy` `deploy`, `routeTraffic`, and `postRouteTraffic`, get executed once. Then, either `on:` `success` or `on:` `failure` gets executed. +After your pipeline runs, verify that the job ran successfully and that you see a published artifact. - See the following example of a deployment job for `runOnce`: - ```YAML - jobs: - - deployment: VMDeploy - displayName: Web deploy - environment: - name: - resourceType: VirtualMachine - strategy: - runOnce: - deploy: - steps: - - script: echo my first deployment - ``` +## Deploy to the Linux VMs -4. See the following example of a YAML snippet for the rolling strategy with a Java pipeline. You can update up to five targets gets in each iteration. `maxParallel` determines the number of targets that can be deployed to, in parallel. The selection accounts for absolute number or percentage of targets that must remain available at any time, excluding the targets being deployed to. It's also used to determine the success and failure conditions during deployment. +1. Edit your pipeline to add the following [deployment job](../process/deployment-jobs.md). Replace `` with the name of the environment you created earlier. Select specific VMs from the environment to receive the deployment by specifying the `` that you defined for each VM. - ```YAML - jobs: + ```yaml + jobs: - deployment: VMDeploy - displayName: web + displayName: Web deploy environment: - name: + name: resourceType: VirtualMachine + tags: # Update value for VMs to deploy to strategy: - rolling: - maxParallel: 2 #for percentages, mention as x% - preDeploy: - steps: - - download: current - artifact: drop - - script: echo initialize, cleanup, backup, install certs - deploy: - steps: - - task: Bash@3 - inputs: - targetType: 'inline' - script: | - # Modify deployment script based on the app type - echo "Starting deployment script run" - sudo java -jar '$(Pipeline.Workspace)/drop/**/target/*.jar' - routeTraffic: - steps: - - script: echo routing traffic - postRouteTraffic: - steps: - - script: echo health check post-route traffic - on: - failure: - steps: - - script: echo Restore from backup! This is on failure - success: - steps: - - script: echo Notify! This is on success ``` - With each run of this job, deployment history gets recorded against the `` environment that you've created and registered the VMs. - -## Pipeline traceability views in environment - -The **Deployments** view provides complete traceability of commits and work items, and a cross-pipeline deployment history per environment. + + For more information, see the complete [jobs.deployment definition](/azure/devops/pipelines/yaml-schema/jobs-deployment). + + For more information about the `environment` keyword and resources targeted by a deployment job, see the [jobs.deployment.environment definition](/azure/devops/pipelines/yaml-schema/jobs-deployment-environment). + +1. Specify either `runOnce` or `rolling` as a deployment `strategy`. + + - `runOnce` is the simplest deployment strategy. The `preDeploy` `deploy`, `routeTraffic`, and `postRouteTraffic` lifecycle hooks each execute once. Then either `on:` `success` or `on:` `failure` executes. + + The following code shows a deployment job for `runOnce`: + + ```yaml + jobs: + - deployment: VMDeploy + displayName: Web deploy + environment: + name: + resourceType: VirtualMachine + tags: + strategy: + runOnce: + deploy: + steps: + - script: echo my first deployment + ``` + + - The following code shows a YAML snippet for the `rolling` deployment strategy, using a Java pipeline. You can update up to five targets in each iteration. The `maxParallel` parameter specifies the number of targets that can be deployed to in parallel. + + The `maxParallel` selection accounts for absolute number or percentage of targets that must remain available at any time, excluding the targets being deployed to, and determines success and failure conditions during deployment. + + ```yaml + jobs: + - deployment: VMDeploy + displayName: web + environment: + name: + resourceType: VirtualMachine + tags: + strategy: + rolling: + maxParallel: 2 #for percentages, mention as x% + preDeploy: + steps: + - download: current + artifact: drop + - script: echo initialize, cleanup, backup, install certs + deploy: + steps: + - task: Bash@3 + inputs: + targetType: 'inline' + script: | + # Modify deployment script based on the app type + echo "Starting deployment script run" + sudo java -jar '$(Pipeline.Workspace)/drop/**/target/*.jar' + routeTraffic: + steps: + - script: echo routing traffic + postRouteTraffic: + steps: + - script: echo health check post-route traffic + on: + failure: + steps: + - script: echo Restore from backup! This is on failure + success: + steps: + - script: echo Notify! This is on success + ``` + + With each run of this job, deployment history is recorded against the environment you created and registered the VMs in. + +## Access pipeline traceability in environment + +The environment **Deployments** view provides complete traceability of commits and work items and a cross-pipeline deployment history for the environment. :::image type="content" source="media/vm-deployments.png" alt-text="Screenshot of deployments view."::: - -## Next steps - -> [!div class="nextstepaction"] -> [Learn more about Jobs](../process/phases.md) - -## Related articles +## Related content +- [Jobs](../process/phases.md) - [Tasks](../process/tasks.md) -- [Catalog of Tasks](../tasks/index.md) +- [Catalog of tasks](../tasks/index.md) - [Variables](../process/variables.md) - [Triggers](../build/triggers.md) -- [Troubleshooting](../troubleshooting/troubleshooting.md). -- [YAML schema reference](/azure/devops/pipelines/yaml-schema). +- [Troubleshooting](../troubleshooting/troubleshooting.md) +- [YAML schema reference](/azure/devops/pipelines/yaml-schema) + diff --git a/docs/pipelines/ecosystems/dotnet-core.md b/docs/pipelines/ecosystems/dotnet-core.md index a3e2f180b57..dd7df251e04 100644 --- a/docs/pipelines/ecosystems/dotnet-core.md +++ b/docs/pipelines/ecosystems/dotnet-core.md @@ -1,158 +1,335 @@ --- title: Build, test, and deploy .NET Core apps -description: Use .NET Core to build apps with Azure Pipelines, Azure DevOps, & Team Foundation Server. +description: Use .NET Core to build apps with Azure Pipelines. ms.topic: conceptual ms.assetid: 95ACB249-0598-4E82-B155-26881A5AA0AA ms.reviewer: vijayma -ms.date: 11/02/2022 -ms.custom: contperf-fy20q4, freshness-fy22q2, content-freshness, devx-track-dotnet -monikerRange: '<= azure-devops' +ms.date: 01/26/2024 +ms.custom: freshness-fy22q2, content-freshness, devx-track-dotnet +monikerRange: "<=azure-devops" --- # Build, test, and deploy .NET Core apps [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Use a pipeline to automatically build and test your .NET Core projects. Learn how to do the following tasks: +Use an Azure Pipeline to automatically build, test, and deploy your .NET Core projects. This article shows you how to do the following tasks: + +::: moniker range="<=azure-devops-2022" + +* Set up your build environment with [self-hosted](../agents/agents.md) agents. +* Restore dependencies, build your project, and test with the [.NET Core task (DotNetCoreCLI@2)](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) or a [script](../scripts/cross-platform-scripting.md). +* Test your code and use the [publish code coverage task](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v2) to publish code coverage results. +* Package and deliver your build output to: + * your pipeline. + * a [NuGet feed](../artifacts/nuget.md). + * a `.zip` file to deploy a [web app to Azure](../targets/webapp.md). +::: moniker-end + +::: moniker range=">= azure-devops" * Set up your build environment with [Microsoft-hosted](../agents/hosted.md) or [self-hosted](../agents/agents.md) agents. -* Restore dependencies, build your project, and test with the [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) or a [script](../scripts/cross-platform-scripting.md). -* Use the [publish code coverage task](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v1) to publish code coverage results. -* Package and deliver your code with the [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) and the [publish build artifacts task](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1). -* Publish to a [NuGet feed](../artifacts/nuget.md). -* Deploy your [web app to Azure](../targets/webapp.md). +* Restore dependencies, build your project, and test with the [.NET Core task (DotNetCoreCLI@2)](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) or a [script](../scripts/cross-platform-scripting.md). +* Test your code and use the [publish code coverage task](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v2) to publish code coverage results. +* Package and deliver your build output to: + * your pipeline. + * a [NuGet feed](../artifacts/nuget.md). + * a `.zip` file to deploy a [web app to Azure](../targets/webapp.md). + +::: moniker-end > [!NOTE] > For help with .NET Framework projects, see [Build ASP.NET apps with .NET Framework](../apps/aspnet/build-aspnet-4.md). -[!INCLUDE [temp](../includes/concept-rename-note.md)] +## Prerequisites +::: moniker range=">=azure-devops" -## Create your first pipeline +| **Product** | **Requirements** | +|---|---| +| **Azure DevOps** | - An Azure DevOps organization and project. [Create one for free](../get-started/pipelines-sign-up.md).
      - **Permissions:**
          - To grant access to all pipelines in the project: You must be a member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md).
          - To create service connections: You must have the *Administrator* or *Creator* role for [service connections](../library/add-resource-protection.md).
      - An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can request a free tier. | +| **GitHub** | - A [GitHub](https://github.com) account.| -::: moniker range=">=azure-devops-2020" +::: moniker-end -Are you new to Azure Pipelines? If so, then we recommend you try the following section first. +::: moniker range="< azure-devops" + +| **Product** | **Requirements** | +|---|---| +| **Azure DevOps** | - An Azure DevOps collection.
      - **Permissions:**
          - To grant access to all pipelines in the project: You must be a member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md).
          - To create service connections: You must have the *Administrator* or *Creator* role for [service connections](../library/add-resource-protection.md).| +| **GitHub** | - A [GitHub](https://github.com) account.| ::: moniker-end +## Create your first pipeline + +Are you new to Azure Pipelines? If so, then we recommend you try the following section first. + [!INCLUDE [include](../includes/dotnet-setup.md)] -::: moniker range=">=azure-devops-2020" +### Create a DevOps project + +Create a new Azure DevOps project to host your pipeline. + +::: moniker range="azure-devops" + +1. In a browser, go to [dev.azure.com](https://dev.azure.com) and sign in. +1. Select your organization. +1. Create a new project by selecting **New project** or **Create project** if creating the first project in the organization. +1. Enter a **Project name**. +1. Select the **Visibility** for your project. +1. Select **Create**. + +::: moniker-end + +::: moniker range="< azure-devops" + +1. In a browser, go to your Azure DevOps Server. +1. Select your collection. +1. Create a new project by selecting **New project** or **Create project** if creating the first project in the collection. +1. Enter a **Project name**. +1. Select the **Visibility** for your project. +1. Select **Create**. + +::: moniker-end + + +### Set up your build environment + +::: moniker range="<=azure-devops-2022" + +Your builds run on [self-hosted agents](../agents/agents.md#install). Make sure that you have the necessary version of the .NET Core SDK and runtime installed on the agents. You can build your .NET Core projects by using the .NET Core SDK and runtime on [Windows](../agents/windows-agent.md), [Linux](../agents/linux-agent.md), [macOS](../agents/osx-agent.md), and [Docker](../agents/docker.md). + +You can install a specific version of .NET SDK by adding the UseDotNet@2 task in your pipeline YAML file or add the task to your pipeline using the classic editor. + +Example YAML snippet: + +```yaml +steps: +- task: UseDotNet@2 + inputs: + version: '8.x' +``` + +::: moniker-end -### Sign in to Azure Pipelines +::: moniker range=">=azure-devops" -[!INCLUDE [include](includes/sign-in-azure-pipelines.md)] +Your builds run on [Microsoft-hosted agents](../agents/hosted.md). You can build your .NET Core projects by using the .NET Core SDK and runtime on Windows, Linux, and macOS. -[!INCLUDE [include](includes/create-project.md)] +Alternatively, you can use a [self-hosted agent](../agents/agents.md). With a self-hosted agent, you can use preview or private SDKs not officially supported by Azure DevOps Services and run incremental builds. ::: moniker-end -### Create the pipeline +### Create your pipeline + +You can use the YAML pipeline editor or the classic editor to create your pipeline. To use the classic editor, select **Use the classic editor**. + +# [YAML](#tab/yaml-editor) + +::: moniker range=">=azure-devops" -::: moniker range=">=azure-devops-2020" +##### Create a new pipeline and select your source [!INCLUDE [include](includes/create-pipeline-before-template-selected.md)] -When the **Configure** tab appears, select **ASP.NET Core**. +##### Configure your pipeline -1. Examine your new pipeline to see what the YAML does. When you're ready, select **Save and run**. +1. When the **Configure** tab appears, select **Show more** and select the [ASP.NET Core](https://github.com/Microsoft/azure-pipelines-yaml/blob/master/templates/asp.net-core.yml) pipeline template from the list. + +1. Examine your new pipeline to see what the YAML does. + +You can customize the YAML file for your requirements. For example, you can specify the agent pool or add a [task to install different .NET SDK](#build-environment). + +##### Save and run your pipeline + +1. When you're ready, select **Save and run**. > [!div class="mx-imgBorder"] > ![Save and run button in a new YAML pipeline](media/save-and-run-button-new-yaml-pipeline.png) -2. Commit a new _azure-pipelines.yml_ file to your repository. After you're happy with the message, select **Save and run** again. +1. Optionally, you can edit the commit message. +1. Commit the new _azure-pipelines.yml_ file to your repository by selecting **Save and run**. +1. To watch your pipeline in action, select the job in the **Jobs** section. - If you want to watch your pipeline in action, select the build job. +::: moniker-end - Because your code appeared to be a good match for the [ASP.NET Core](https://github.com/Microsoft/azure-pipelines-yaml/blob/master/templates/asp.net-core.yml) template, we automatically created the pipeline for you. +::: moniker range="< azure-devops" + +### Create and run your pipeline + +You can create a pipeline by using the YAML pipeline editor or the classic editor. + +1. Go to your project and select **Pipelines**. +1. Select **Create pipeline** or **New pipeline** if creating the first pipeline for this project. + +##### Select your source - You now have a working YAML pipeline (`azure-pipelines.yml`) in your repository that's ready for you to customize! +1. Select your source repository. For this example, use **GitHub Enterprise Server**. -3. When you're ready to make changes to your pipeline, select it in the **Pipelines** page, and then **Edit** the `azure-pipelines.yml` file. + 1. Enter the URL for your GitHub account. For example, `https://github.com/`. + 1. Enter your personal access token for your GitHub account. + 1. Enter a Service connection name. For example, `my-github`. + 1. Select **Create**. +1. Select your GitHub repository. + +##### Configure your pipeline + +1. On the **Configure** tab, select **Show more** and select the [ASP.NET Core](https://github.com/Microsoft/azure-pipelines-yaml/blob/master/templates/asp.net-core.yml) pipeline template from the list. + +1. Examine your new pipeline to see what the YAML does. + +You can customize the YAML file for your requirements. For example, you can add tasks to install a .NET SDK or to test and publish your project. -Read further to learn some of the more common ways to customize your pipeline. +##### Save and run your pipeline ::: moniker-end -::: moniker range="azure-devops-2019" +::: moniker range=">= azure-devops-2020 <= azure-devops-2022" -### YAML +1. Select **Save and run**. -1. Add an `azure-pipelines.yml` file in your repository. Customize the following snippet for your build. + > [!div class="mx-imgBorder"] + > ![Screenshot showing the Save and run button in a new YAML pipeline.](media/save-and-run-button-new-yaml-pipeline.png) -```yaml -trigger: -- main +1. To commit the new *azure-pipelines.yml* file to your repository, edit the commit message as needed and select **Save and run**. -pool: Default +To watch your pipeline in action, select the job in the **Jobs** section. -variables: - buildConfiguration: 'Release' +::: moniker-end -# do this before all your .NET Core tasks -steps: -- task: DotNetCoreInstaller@2 - inputs: - version: '2.2.402' # replace this value with the version that you need for your project -- script: dotnet build --configuration $(buildConfiguration) - displayName: 'dotnet build $(buildConfiguration)' -``` -2. [Create a pipeline](../create-first-pipeline.md) and select the **YAML** template. +# [Classic](#tab/classic-editor) + +Use these steps to create your pipeline using the classic editor. + +##### Create pipeline + +1. Go to your project and select **Pipelines**. + +1. Select **Create pipeline** or **New pipeline** if you're not creating the first pipeline for this project. +1. Select **Use the classic editor**. + +::: moniker range="< azure-devops" -3. Set the **Agent pool** and **YAML file path** for your pipeline. +##### Select your source -4. Save the pipeline and queue a build. When the **Build #nnnnnnnn.n has been queued** message appears, select the number link to see your pipeline in action. +1. Select your source. For this example, select **GitHub Enterprise Server**. +1. Select **Connect to GitHub Enterprise Server**. +1. Enter your GitHub credentials to create a GitHub service connection to use in your pipeline. +1. Select your repository and select **Continue**. -5. When you're ready to make changes to your pipeline, **Edit** it. +::: moniker-end + +::: moniker range=">= azure-devops" + +##### Select your source -Read further to learn some of the more common ways to customize your pipeline. +1. Select your source. For this example, select **GitHub**. +1. Enter your GitHub credentials to create a GitHub service connection to use in your pipeline. +1. Select your repository and select **Continue**. ::: moniker-end -::: moniker range="< azure-devops" +##### Configure your pipeline + +1. From **Select a template**, find then select **ASP.NET Core**. + + The pipeline page opens where you can configure your pipeline. Here you can add tasks, specify the agent pools and agents and configure other build options. -### Classic +1. In the **Tasks** tab, select your **Agent pool** (usually *Default*) +1. Select the **Agent specification**. For this example, select **windows-latest**. + + You can add other tasks to the Agent job by selecting **+** on the agent job and selecting another task from the catalog. For example, you might want to add the **Use .NET Core** task as the first task to install the necessary version of the .NET SDK. -1. [Create a pipeline](../create-first-pipeline.md) and select the **Empty Pipeline** template. +##### Save and run your pipeline -2. In the task catalog, find and add the **.NET Core** task. The following task runs `dotnet build` to build the code in the sample repository. +::: moniker range=">=azure-devops" -3. Save the pipeline and queue a build. When the **Build #nnnnnnnn.n has been queued** message appears, select the number link to see your pipeline in action. +1. Select **Save and queue** from the **Save & queue** dropdown list at the top of the page. +1. In **Run pipeline**, enter a comment and select **Save and Run**. - You now have a working pipeline that's ready for you to customize! +You can see your pipeline in action by selecting the job from the **Jobs** section on the **Summary** tab. -4. When you're ready to make changes to your pipeline, **Edit** it. +::: moniker-end + +::: moniker range="< azure-devops-2022" + +1. From the **Save & queue** dropdown list, select **Save and queue** . +1. From the **Save build pipeline and queue** dialog, select **Save and queue**. -Read further to learn some of the more common ways to customize your pipeline. +When the **Build #nnnnnnnn.n has been queued** message appears, select the link to see your pipeline in action. ::: moniker-end +::: moniker range="azure-devops-2022" + +1. From the **Save & queue** dropdown list at the top of the page, select **Save and queue** . +1. On the **Run pipeline** dialog, add a **Save comment** and select **Save and run**. + +You can see your pipeline in action by selecting the job from the **Jobs** section on the **Summary** tab. + +::: moniker-end + +--- + +You now have a working pipeline that's ready for you to customize! Read further to learn some of the common ways to customize your pipeline. + ## Build environment -::: moniker range=">=azure-devops-2020" +::: moniker range="<=azure-devops-2022" + +Azure Pipelines uses self-hosted agents to build your .NET Core projects. Make sure that you have the necessary version of the .NET Core SDK and runtime installed on the agents. You can build your .NET Core projects by using the .NET Core SDK and runtime on [Windows](../agents/windows-agent.md), [Linux](../agents/linux-agent.md), [macOS](../agents/osx-agent.md), and [Docker](../agents/docker.md). -Use Azure Pipelines to build your .NET Core projects. Build your projects on Windows, Linux, or macOS without the need to set up infrastructure. The [Microsoft-hosted agents](../agents/hosted.md) in Azure Pipelines include several preinstalled versions of the .NET Core SDKs. +For example, to select a pool and agent capabilities in the pipeline YAML file: -Ubuntu is set here in the YAML file. +You can select the agent pool and agent for your build job. Agents are specified based on their capabilities. + +```yml +pool: + name: myPrivateAgents + demands: + - agent.os -equals Darwin + - anotherCapability -equals somethingElse +``` + +You can install a specific version of .NET SDK by adding the UseDotNet@2 task in your pipeline. Keep in mind that for agents that run on physical systems, installing SDKs and tools through your pipeline alters the build environment on the agent's host. + +To install a newer SDK, set `performMultiLevelLookup` to `true` in the following snippet: + +```yaml +steps: +- task: UseDotNet@2 + displayName: 'Install .NET Core SDK' + inputs: + version: 8.x + performMultiLevelLookup: true + includePreviewVersions: true # Required for preview versions +``` + +::: moniker-end + +::: moniker range=">=azure-devops" + +You can use Azure Pipelines to build your .NET Core projects on Windows, Linux, or macOS without the need to set up infrastructure. + +For example, Ubuntu is set here in the pipeline YAML file. ```yaml pool: vmImage: 'ubuntu-latest' ``` -See [Microsoft-hosted agents](../agents/hosted.md) for a complete list of images and [Pool](/azure/devops/pipelines/yaml-schema/pool) for further examples. +See [Microsoft-hosted agents](../agents/hosted.md) for a complete list of images and further configuration examples. -The Microsoft-hosted agents don't include some of the older versions of the .NET Core SDK. -They also don't typically include prerelease versions. If you need these kinds of SDKs on Microsoft-hosted agents, add the [UseDotNet@2](/azure/devops/pipelines/tasks/reference/use-dotnet-v2) task to your YAML file. +The [Microsoft-hosted agents](../agents/hosted.md) in Azure Pipelines include several preinstalled versions of supported .NET Core SDKs. Microsoft-hosted agents don't include some of the older versions of the .NET Core SDK. They also don't typically include prerelease versions. If you need these versions of the SDK on Microsoft-hosted agents, install them using the [UseDotNet@2](/azure/devops/pipelines/tasks/reference/use-dotnet-v2) task. -To install 6.0.x SDK for building, add the following snippet: +For example, to install 5.0.x SDK, add the following snippet: ```yaml steps: - task: UseDotNet@2 inputs: - version: '6.x' + version: '5.x' ``` Windows agents already include a .NET Core runtime. To install a newer SDK, set `performMultiLevelLookup` to `true` in the following snippet: @@ -162,33 +339,24 @@ steps: - task: UseDotNet@2 displayName: 'Install .NET Core SDK' inputs: - version: 6.x + version: 8.x performMultiLevelLookup: true includePreviewVersions: true # Required for preview versions ``` > [!TIP] -> To save the cost of running the tool installer, you can set up a [self-hosted agent](../agents/agents.md#install). See [Linux](../agents/linux-agent.md), [macOS](../agents/osx-agent.md), or [Windows](../agents/windows-agent.md). -> You can also use self-hosted agents to save additional time if you have a large repository or you run incremental builds. A self-hosted agent can also help you in using the preview or private SDKs that aren't officially supported by Azure DevOps or you have available on your corporate or on-premises environments only. - -::: moniker-end - -::: moniker range="< azure-devops" - -You can build your .NET Core projects by using the .NET Core SDK and runtime on Windows, Linux, or macOS. Your builds run on a [self-hosted agent](../agents/agents.md#install). -Make sure that you have the necessary version of the .NET Core SDK and runtime installed on the agent. +> To save the cost of running the tool installer, you can set up a [Linux](../agents/linux-agent.md), [macOS](../agents/osx-agent.md), or [Windows](../agents/windows-agent.md) [self-hosted agent](../agents/agents.md#install). +> You can also use self-hosted agents to save time if you have a large repository or you run incremental builds. A self-hosted agent can also help you in using the SDKs that aren't included in Azure DevOps or are only available on your corporate or on-premises environments. ::: moniker-end ## Restore dependencies -NuGet is a popular way to depend on code that you don't build. You can download NuGet packages and project-specific tools that are specified in the project file by running the `dotnet restore` command either through the [.NET Core](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) task or directly in a script in your pipeline. - -::: moniker range=">= tfs-2018" +NuGet is a popular way to depend on code that you don't build. You can download NuGet packages and project-specific tools that are specified in the project file by running the `dotnet restore` command either through the **.NET Core** task or directly in a script in your pipeline. For more information, see [.NET Core task (DotNetCoreCLI@2)](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2). -You can download NuGet packages from Azure Artifacts, NuGet.org, or some other external or internal NuGet repository. The **.NET Core** task is especially useful to restore packages from authenticated NuGet feeds. If your feed is in the same project as your pipeline, you do not need to authenticate. +You can download NuGet packages from Azure Artifacts, NuGet.org, or some other external or internal NuGet repository. The **.NET Core** task is especially useful to restore packages from authenticated NuGet feeds. If your feed is in the same project as your pipeline, you don't need to authenticate. -This pipeline uses an artifact feed for `dotnet restore` in the [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2). +This pipeline uses an Azure Artifact feed for `dotnet restore` in the **DotNetCoreCLI@2** task. ```yaml trigger: @@ -197,6 +365,14 @@ trigger: pool: vmImage: 'windows-latest' +steps: +- task: UseDotNet@2 + displayName: 'Install .NET Core SDK' + inputs: + version: 8.x + performMultiLevelLookup: true + includePreviewVersions: true # Required for preview versions + variables: buildConfiguration: 'Release' @@ -214,47 +390,42 @@ steps: displayName: 'dotnet build $(buildConfiguration)' ``` -::: moniker-end - -::: moniker range="tfs-2018" - -You can download NuGet packages from NuGet.org. +The `dotnet restore` command uses the `NuGet.exe` packaged with the .NET Core SDK and can only restore packages specified in the .NET Core project `.csproj` files. -::: moniker-end - -`dotnet restore` internally uses a version of `NuGet.exe` that's packaged with the .NET Core SDK. `dotnet restore` can only restore packages specified in the .NET Core project `.csproj` files. If you also have a Microsoft .NET Framework project in your solution or use `package.json` to specify your dependencies, use the **NuGet** task to restore those dependencies. -::: moniker range="tfs-2018" - -In .NET Core SDK version 2.0 and newer, packages get restored automatically when running other commands such as `dotnet build`. - -::: moniker-end +```yaml +- task: NuGetCommand@2 + inputs: + command: 'restore' + restoreSolution: '**/*.sln' + feedsToUse: 'select' +``` -::: moniker range=">= tfs-2018" +> [!NOTE] +> If you're using Ubuntu 24.04 or higher, you must use the `NuGetAuthenticate` task with the .NET CLI instead of the `NuGetCommand@2` task. For more information, see [Support for newer Ubuntu hosted images](/azure/devops/pipelines/tasks/reference/nuget-command-v2#support-for-newer-ubuntu-hosted-images). -In .NET Core SDK version 2.0 and newer, packages get restored automatically when running other commands such as `dotnet build`. However, you might still need to use the **.NET Core** task to restore packages if you use an authenticated feed. +In .NET Core SDK version 2.0 and newer, packages are restored automatically when running commands such as `dotnet build`. However, you would still need to use the **.NET Core** task to restore packages if you use an authenticated feed. -::: moniker-end +Your builds can fail because of connection issues when you restore packages from NuGet.org. You can use Azure Artifacts with [upstream sources](../../artifacts/concepts/upstream-sources.md) to cache the packages. The credentials of the pipeline are automatically used when it connects to Azure Artifacts. These credentials are typically derived from the **Project Collection Build Service** account. To learn more about using Azure Artifacts to cache your NuGet packages, see [Connect to Azure Artifact feeds](../../artifacts/nuget/nuget-exe.md). -::: moniker range=">= tfs-2018" +To specify a NuGet repository, put the URL in a `NuGet.config` file in your repository. If your feed is authenticated, manage its credentials by creating a NuGet service connection in the **Services** tab under **Project Settings**. -Your builds may sometimes fail because of connection issues when you restore packages from NuGet.org. You can use Azure Artifacts with [upstream sources](../../artifacts/concepts/upstream-sources.md) and cache the packages. The credentials of the pipeline get automatically used when it connects to Azure Artifacts. These credentials are typically derived from the **Project Collection Build Service** account. +::: moniker range=">=azure-devops" -If you want to specify a NuGet repository, put the URLs in a `NuGet.config` file in your repository. -If your feed is authenticated, manage its credentials by creating a NuGet service connection in the **Services** tab under **Project Settings**. +When you use Microsoft-hosted agents, you get a new machine every time you run a build, which restores the packages with each run. Restoration can take a significant amount of time. To mitigate, you can either use Azure Artifacts or a self-hosted agent with the benefit of using the package cache. ::: moniker-end -::: moniker range=">=azure-devops-2020" +For more information about NuGet service connections, see [publish to NuGet feeds](../artifacts/nuget.md). -If you use Microsoft-hosted agents, you get a new machine every time your run a build, which means restoring the packages every time. Restoration can take a significant amount of time. To mitigate, you can either use Azure Artifacts or a self-hosted agent with the benefit of using the package cache. +### Restore packages from an external feed -::: moniker-end +Do the following to restore packages from an external feed. -::: moniker range=">=azure-devops-2020" +# [YAML](#tab/yaml-editor) -To restore packages from an external custom feed, use the following **.NET Core** task: +You can add the restore command to your pipeline using the YAML pipeline editor by directly inserting the following snippet into your `azure-pipelines.yml` file or using the task assistant to add the **.NET Core** task. ```yaml # do this before your build tasks @@ -267,35 +438,46 @@ steps: feedsToUse: config nugetConfigPath: NuGet.config # Relative to root of the repository externalFeedCredentials: -# ... ``` + Replace the \ with your service connection name. -For more information about NuGet service connections, see [publish to NuGet feeds](../artifacts/nuget.md). +To use the task assistant: -::: moniker-end +To add a build task using the task assistant, do the following steps: -::: moniker range="< azure-devops" +1. Go to the position in the YAML file where you want to insert the task. -1. Select **Tasks** in the pipeline. Select the job that runs your build tasks. Then, select **+** to add a new task to that job. +1. Select the **.NET Core** from the task catalog. +1. Select the **restore** command from the **Command** dropdown list. +1. In the **Path to project(s)** field, enter the path to your `.csproj` files. +1. Select **Add**. +1. Select **Save** to commit the change. -1. In the task catalog, find and add the **.NET Core** task. +# [Classic](#tab/classic-editor) -1. Select the task and, for **Command**, select **restore**. +Use these steps to add a restore task using the classic editor: -1. Specify any other options you need for this task. Then save the build. +1. Select **Tasks** in your pipeline and select the job that runs your build tasks. + +1. Select **+** to add a new task to that job. +1. In the task catalog, find and select **.NET Core** task and select **Add**. +1. Select the task to open the task editor. +1. Select **restore** in the **Command** list and specify any other options you need for this task. +1. In the task list, drag the task to position it before the build task. +1. From the **Save & queue** dropdown list, select an option to save the change. + +--- > [!NOTE] > Make sure the custom feed is specified in your `NuGet.config` file and that credentials are specified in the NuGet service connection. -::: moniker-end - ## Build your project -You build your .NET Core project either by running the `dotnet build` command in your pipeline or by using the .NET Core task. +Build your .NET Core projects by running the `dotnet build` command. You can add the command to your pipeline as a command line script or by using the .NET Core task. -::: moniker range=">=azure-devops-2020" +### Build with the .NET Core task -To build your project by using the .NET Core task, add the following snippet to your `azure-pipelines.yml` file: +YAML example to build using the DotNetCoreCLI@2 task: ```yaml steps: @@ -304,34 +486,127 @@ steps: inputs: command: build projects: '**/*.csproj' - arguments: '--configuration $(buildConfiguration)' # Update this to match your need + arguments: '--configuration $(buildConfiguration)' # Update this to match your needs ``` -You can run any custom dotnet command in your pipeline. The following example shows how to install and use a .NET global tool, [dotnetsay](https://www.nuget.org/packages/dotnetsay/): +# [YAML](#tab/yaml-editor) -```yaml +You can add a build task using the YAML pipeline editor by directly editing the file or adding the **.NET Core** task using the task assistant. + +To add a build task using the task assistant, do the following steps: + +1. Go to the position in the YAML file where you want to insert the task. + +1. Select the **.NET Core** from the task catalog. +1. Select the **build** command from the **Command** dropdown list. +1. In the **Path to project(s)** field, enter the path to your `.csproj` files. +1. Select **Add**. +1. Select **Save** to commit the change. + +# [Classic](#tab/classic-editor) + +To add a build task using the classic editor, do the following steps: + +1. Select **Tasks** in your pipeline. + +1. Select the job that runs your build tasks. +1. Select **+** to add a new task to that job. +1. In the task catalog, find and add the **.NET Core** task. +1. Select the task and select **build** from the **Command** dropdown list. +1. In the **Path to project(s)** field, enter the path to your `.csproj` files. +1. Drag the task to position it in the correct task sequence in the pipeline. +1. Select the **Save and queue** dropdown list and select an option to save your changes. + +--- + +### Build .NET Core with a command line script + +YAML example to build using `dotnet build` as a script: + +```yml steps: -- task: DotNetCoreCLI@2 - displayName: 'Install dotnetsay' - inputs: - command: custom - custom: tool - arguments: 'install -g dotnetsay' +- script: dotnet build --configuration $(buildConfiguration) + displayName: 'dotnet build $(buildConfiguration)' ``` -::: moniker-end +# [YAML](#tab/yaml-editor) -::: moniker range="< azure-devops" +You can add a build task using the YAML pipeline editor by directly editing the file or adding the [Command Line](/azure/devops/pipelines/tasks/reference/cmd-line-v2) task. + +Use the following steps to add the **Command Line** task: + +1. Go to the position in the YAML file where you want to insert the task. + +1. Select the **Command Line** from the task catalog. +1. Optionally, add a **Display name**. +1. Enter the `dotnet build` command with parameters. For example, `dotnet build --configuration $(buildConfiguration)`. +1. Enter the path to the `.csproj` file as the working directory. +1. Select **Add**. +1. Select **Save** to commit the change. + +# [Classic](#tab/classic-editor) + +To add a build task using the classic editor, do the following steps: + +1. Select **Tasks** in your pipeline. + +1. Select the job that runs your build tasks. +1. Select **+** to add a new task to that job. +1. In the task catalog, find and **Add** the **Command Line** task. +1. Optionally, add a **Display name**. +1. Enter the `dotnet build` command with parameters. For example, `dotnet build --configuration $(buildConfiguration)`. +1. Enter the path to the `.csproj` file as the working directory. +1. Drag the task to position it in the correct task sequence in the pipeline. +1. Select the **Save and queue** dropdown list and select an option to save your changes. + +--- + +## Add .NET SDK commands to your pipeline + +You can add .NET SDK commands to your project as a script or using the .NET Core task. The [.NET Core task (DotNetCoreCLI@2)](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) task allows you to easily add dotnet CLI commands to your pipeline. You can add **.NET Core** tasks by editing your YAML file or using the classic editor. + +### Add a .NET CLI command with the .NET Core task + +# [YAML](#tab/yaml-editor) + +To add a .NET Core CLI command using the YAML pipeline editor, do the following steps: -### Build +1. Go to the position in the YAML file where you want to insert the task. -1. Select **Tasks** in the pipeline. Select the job that runs your build tasks. Then select **+** to add a new task to that job. +1. Select **.NET Core** from the task catalog. +1. Select the command you want to run. +1. Configure any options needed. +1. Select **Add**. +1. Select **Save** to commit the change. +# [Classic](#tab/classic-editor) + +To add .NET Core task using the classic editor, do the following steps: + +1. Select **Tasks** in your pipeline. + +1. Select the job that runs your build tasks. +1. Select **+** to add a new task to that job. 1. In the task catalog, find and add the **.NET Core** task. +1. Select the task and select the **Command** that you want to run. +1. Configure any options needed. +1. Drag the task to position it in the correct task sequence in the pipeline. +1. From the **Save and queue** dropdown list, select an option to save your changes. + +--- -1. Select the task and, for **Command**, select **build** or **publish**. +### Add a .NET Core CLI command in a script -1. Specify any other options you need for this task, and then save the build. +You can add .NET Core CLI commands as a `script` in your `azure-pipelines.yml` file. + +Example: + +```yml + +steps: +# ... +- script: dotnet test +``` ### Install a tool @@ -342,20 +617,15 @@ To install a .NET Core global tool like [dotnetsay](https://www.nuget.org/packag * **Path to projects**: _leave empty_. * **Custom command**: tool. * **Arguments**: `install -g dotnetsay`. - -2. Add a **Command Line** task and set the following properties: +1. To run the tool, add a **Command Line** and set the following properties: * **Script:** `dotnetsay`. -::: moniker-end - ## Run your tests -If you have test projects in your repository, then use the **.NET Core** task to run unit tests by using testing frameworks like MSTest, xUnit, and NUnit.The test project must reference [Microsoft.NET.Test.SDK](https://www.nuget.org/packages/Microsoft.NET.Test.SDK) version 15.8.0 or higher. -Test results get automatically published to the service. These results are available to you in the build summary and can be used for troubleshooting failed tests and test-timing analysis. +When you have test projects in your repository, you can use the **.NET Core** task to run unit tests by using testing frameworks like MSTest, xUnit, and NUnit. The test project must reference [Microsoft.NET.Test.SDK](https://www.nuget.org/packages/Microsoft.NET.Test.SDK) version 15.8.0 or higher. +Test results are automatically published to the service. These results are available to you in the build summary and can be used for troubleshooting failed tests and test-timing analysis. -::: moniker range=">=azure-devops-2020" - -Add the following snippet to your `azure-pipelines.yml` file: +You can add a test task to your pipeline using the **DotNetCoreCLI@2** task or add the following snippet to your `azure-pipelines.yml` file: ```yaml steps: @@ -368,7 +638,9 @@ steps: arguments: '--configuration $(buildConfiguration)' ``` -An alternative is to run the `dotnet test` command with a specific logger and then use the **Publish Test Results** task: +When using the **.NET Core** task editor, set **Command** to **test** and **Path to projects** should refer to the test projects in your solution. + +Alternatively, you can run the `dotnet test` command with a specific logger and then use the **Publish Test Results** task: ```yaml steps: @@ -382,22 +654,11 @@ steps: testResultsFiles: '**/*.trx' ``` -::: moniker-end - -::: moniker range="< azure-devops" - -Use the **.NET Core** task with **Command** set to **test**. -**Path to projects** should refer to the test projects in your solution. - -::: moniker-end - - ## Collect code coverage -If you're building on the Windows platform, code coverage metrics can be collected by using the built-in coverage data collector. The test project must reference [Microsoft.NET.Test.SDK](https://www.nuget.org/packages/Microsoft.NET.Test.SDK) version 15.8.0 or higher. -If you use the **.NET Core** task to run tests, coverage data is automatically published to the server. The **.coverage** file can be downloaded from the build summary for viewing in Visual Studio. +When you're building on the Windows platform, code coverage metrics can be collected by using the built-in coverage data collector. The test project must reference [Microsoft.NET.Test.SDK](https://www.nuget.org/packages/Microsoft.NET.Test.SDK) version 15.8.0 or higher. -::: moniker range=">=azure-devops-2020" +When you use the **.NET Core** task to run tests, coverage data is automatically published to the server. The ``.coverage`` file can be downloaded from the build summary for viewing in Visual Studio. Add the following snippet to your `azure-pipelines.yml` file: @@ -409,55 +670,47 @@ steps: inputs: command: test projects: '**/*Tests/*.csproj' - arguments: '--configuration $(buildConfiguration) --collect "Code coverage"' + arguments: '--configuration $(buildConfiguration) --collect "Code Coverage"' ``` +To add the **.NET Core** task through the task editor: + +1. Add the .NET Core task to your build job and set the following properties: + + 1. **Command**: test. + 1. **Path to projects**: _Should refer to the test projects in your solution_. + 1. **Arguments**: `--configuration $(BuildConfiguration) --collect "Code Coverage"`. + +1. Ensure that the **Publish test results** option remains selected. + If you choose to run the `dotnet test` command, specify the test results logger and coverage options. Then use the [Publish Test Results](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) task: ```yaml steps: # ... # do this after your tests have run -- script: dotnet test --logger trx --collect "Code coverage" +- script: dotnet test --logger trx --collect "Code Coverage" - task: PublishTestResults@2 inputs: testRunner: VSTest testResultsFiles: '**/*.trx' ``` -::: moniker-end - -::: moniker range="< azure-devops" - -1. Add the .NET Core task to your build job and set the following properties: - - * **Command**: test. - * **Path to projects**: _Should refer to the test projects in your solution_. - * **Arguments**: `--configuration $(BuildConfiguration) --collect "Code coverage"`. - -2. Ensure that the **Publish test results** option remains selected. - -::: moniker-end - - ### Collect code coverage metrics with Coverlet If you're building on Linux or macOS, you can use [Coverlet](https://github.com/tonerdo/coverlet) or a similar tool to collect code coverage metrics. -You can publish code coverage results to the server with the [Publish Code Coverage Results](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v1) task. The coverage tool must be configured to generate results in Cobertura or JaCoCo coverage format. +You can publish code coverage results to the server with the [Publish Code Coverage Results task (PublishCodeCoverageResults@2)](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v2) task. The coverage tool must be configured to generate results in Cobertura or JaCoCo coverage format. To run tests and publish code coverage with Coverlet, do the following tasks: -* Add a reference to the `coverlet.msbuild` NuGet package in your test project(s) for .NET projects below .NET 5. For .NET 5, add a reference to the `coverlet.collector` NuGet package. +* Add a reference to the `coverlet.collector` NuGet package. * Add the following snippet to your `azure-pipelines.yml` file: - -# [.NET >= 5](#tab/dotnetfive) - ```yaml - task: UseDotNet@2 inputs: - version: '6.x' + version: '8.x' includePreviewVersions: true # Required for preview versions - task: DotNetCoreCLI@2 @@ -474,46 +727,30 @@ To run tests and publish code coverage with Coverlet, do the following tasks: publishTestResults: true projects: 'MyTestLibrary' # update with your test project directory - - task: PublishCodeCoverageResults@1 + - task: PublishCodeCoverageResults@2 displayName: 'Publish code coverage report' inputs: codeCoverageTool: 'Cobertura' summaryFileLocation: '$(Agent.TempDirectory)/**/coverage.cobertura.xml' ``` -# [.NET < 5](#tab/netearlierversions) - - ```yaml - - task: DotNetCoreCLI@2 - displayName: 'dotnet test' - inputs: - command: 'test' - arguments: '--configuration $(buildConfiguration) --collect:"XPlat Code Coverage" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.Format=cobertura' - publishTestResults: true - projects: '**/test-library/*.csproj' # update with your test project directory - - - task: PublishCodeCoverageResults@1 - displayName: 'Publish code coverage report' - inputs: - codeCoverageTool: 'Cobertura' - summaryFileLocation: '$(Agent.TempDirectory)/**/coverage.cobertura.xml' - ``` - ---- - - ## Package and deliver your code -Upload the build output to Azure Pipelines. You can create and publish a NuGet package, or package the build output into a .zip file to deploy to a web application. +You can publish your build artifacts by: -::: moniker range=">=azure-devops-2020" +* Publishing to Azure Pipelines. +* Publishing packages to Azure Artifacts. +* Creating a NuGet package and publish to your NuGet feed. +* Creating a *.zip* archive to deploy your web app. ### Publish artifacts to Azure Pipelines -To publish the output of your .NET **build**, do the following tasks: +::: moniker range=">=azure-devops" -* Run `dotnet publish --output $(Build.ArtifactStagingDirectory)` on CLI or add the DotNetCoreCLI@2 task with publish command. -* Publish the artifact by using Publish artifact task. +To publish the output of your .NET **build** to your pipeline, do the following tasks: + +* Run `dotnet publish --output $(Build.ArtifactStagingDirectory)` on the .NET CLI or add the **DotNetCoreCLI@2** task with the publish command. +* Publish the artifact by using the [Publish Pipeline Artifact](/azure/devops/pipelines/tasks/reference/publish-pipeline-artifact-v1) task. Add the following snippet to your `azure-pipelines.yml` file: @@ -531,26 +768,59 @@ steps: - task: PublishPipelineArtifact@1 inputs: targetPath: '$(Build.ArtifactStagingDirectory)' - artifactName: 'myWebsiteName' + artifactName: 'myWebsite' ``` > [!NOTE] -> The `dotNetCoreCLI@2` task has a `publishWebProjects` input that is set to **true** by default. This task publishes _all_ web projects in your repo by default. You can find more help and information in the [open source task on GitHub](https://github.com/microsoft/azure-pipelines-tasks). +> The **DotNetCoreCLI@2** task has a `publishWebProjects` input that is set to **true** by default. This task publishes _all_ web projects in your repo by default. You can find more help and information in the [open source task on GitHub](https://github.com/microsoft/azure-pipelines-tasks). + +To copy more files to the build directory before publishing, use the [Copy Files (CopyFile@2)](/azure/devops/pipelines/tasks/reference/copy-files-v2) task. + +::: moniker-end -To copy more files to Build directory before publishing, use [Utility: copy files](/azure/devops/pipelines/tasks/reference/copy-files-v2). +::: moniker range="< azure-devops" + +To publish the output of your .NET **build** to your pipeline, do the following tasks: + +* Run `dotnet publish --output $(Build.ArtifactStagingDirectory)` on CLI or add the **DotNetCoreCLI@2** task with the publish command. +* Publish the artifact by using the [Publish build artifact (PublishBuildArtifacts@1)](/azure/devops/pipelines/tasks/reference/publish-pipeline-artifact-v1) task. + +To publish your build artifacts as a .zip file, add the following snippet to your `azure-pipelines.yml` file: + +```yaml +steps: + +- task: DotNetCoreCLI@2 + inputs: + command: publish + publishWebProjects: True + arguments: '--configuration $(BuildConfiguration) --output $(Build.ArtifactStagingDirectory)' + zipAfterPublish: True + +# this code takes all the files in $(Build.ArtifactStagingDirectory) and uploads them as an artifact of your build. +- task: PublishBuildArtifacts@1 + inputs: + PathtoPublish: '$(Build.ArtifactStagingDirectory)' + ArtifactName: 'drop' + +``` + +For more information, see [Publish and download build artifacts](../artifacts/build-artifacts.md). + +::: moniker-end ### Publish to a NuGet feed -To create and publish a NuGet package, add the following snippet: +To create a NuGet package and publish it to your NuGet feed, add the following snippet: ```yaml steps: # ... # do this near the end of your pipeline in most cases - script: dotnet pack /p:PackageVersion=$(version) # define version variable elsewhere in your pipeline -- task: NuGetAuthenticate@0 - input: +- task: NuGetAuthenticate@1 + inputs: nuGetServiceConnections: '' - task: NuGetCommand@2 inputs: @@ -561,11 +831,18 @@ steps: versionEnvVar: version ``` +> [!NOTE] +> The NuGetAuthenticate@1 task doesn't support NuGet API key authentication. If you're using a NuGet API key, use the NuGetCommand@2 task with the `command` input set to `push` with the `--api-key` argument. For example, `dotnet nuget push --api-key $(NuGetApiKey)`. + For more information about versioning and publishing NuGet packages, see [publish to NuGet feeds](../artifacts/nuget.md). +### Publish a NuGet package to Azure Artifacts + +You can publish your NuGet packages to your Azure Artifacts feed by using the [NuGetCommand@2](/azure/devops/pipelines/tasks/reference/nuget-command-v2) to push to your Azure Artifact feed. For example, see [Publish NuGet packages with Azure Pipelines](../artifacts/nuget.md). + ### Deploy a web app -To create a .zip file archive that's ready for publishing to a web app, add the following snippet: +To create a .zip file archive that's ready to publish to a web app, add the following snippet: ```yaml steps: @@ -582,68 +859,63 @@ steps: To publish this archive to a web app, see [Azure Web Apps deployment](../targets/webapp.md). -::: moniker-end - -::: moniker range="< azure-devops" - -### Publish artifacts to Azure Pipelines - -Use the **Publish Artifacts** task to publish the output of your build to Azure Pipelines. - -### Publish to a NuGet feed - -If you want to publish your code to a NuGet feed, take the following steps: +### Build an image and push to container registry -1. Use a .NET Core task with **Command** set to pack. +You can also [build an image](containers/build-image.md) for your app and [push it to a container registry](containers/push-image.md). -1. [Publish your package to a NuGet feed](../artifacts/nuget.md). - -### Deploy a web app - -1. Use a .NET Core task with **Command** set to publish. + -1. Make sure you've selected the option to create a .zip file archive. +### Publish symbols -1. To publish this archive to a web app, see [Azure Web Apps deployment](../targets/webapp.md). +You can use the **PublishSymbols@2** task to publish symbols to an Azure Artifacts symbol server or a file share. -::: moniker-end +For example, to publish symbols to a file share, add the following snippet to your `azure-pipelines.yml` file: -## Build an image and push to container registry +```yaml +- task: PublishSymbols@2 + inputs: + SymbolsFolder: '$(Build.SourcesDirectory)' + SearchPattern: '**/bin/**/*.pdb' + IndexSources: true + PublishSymbols: true + SymbolServerType: 'FileShare' + SymbolsPath: '\\server\shareName' +``` -For your app, you can also [build an image](containers/build-image.md) and [push it to a container registry](containers/push-image.md). +When using the classic editor, select **Index sources publish symbols** from the task catalog to add to your pipeline. - +For more information, see [Publish symbols](../artifacts/symbols.md). ## Troubleshoot If you can build your project on your development machine, but you're having trouble building it on Azure Pipelines, explore the following potential causes and corrective actions: -::: moniker range=">=azure-devops-2020" +::: moniker range=">=azure-devops" -* We don't install prerelease versions of the .NET Core SDK on Microsoft-hosted agents. After a new version of the .NET Core SDK gets released, it can take a few weeks to roll out to all the Azure Pipelines data centers. You don't have to wait for this rollout to complete. You can use the [**.NET Core Tool Installer**](#yaml) to install the version you want of the .NET Core SDK on Microsoft-hosted agents. +* Prerelease versions of the .NET Core SDK aren't installed on Microsoft-hosted agents. After a new version of the .NET Core SDK is released, it can take a few weeks to roll out to all the Azure Pipelines data centers. You don't have to wait for this rollout to complete. You can use the [Use .NET Core](#build-environment) task to install the .NET Core SDK version you want on Microsoft-hosted agents. ::: moniker-end -* Check the .NET Core SDK versions and runtime on your development machine and make sure they match the agent. You can include a command-line script `dotnet --version` in your pipeline to print the version of the .NET Core SDK. Either use the [**.NET Core Tool Installer**](#yaml) to deploy the same version on the agent, or update your projects and development machine to the newer version of the .NET Core SDK. +* Check the .NET Core SDK versions and runtime on your development machine and make sure they match the agent. You can include a command-line script `dotnet --version` in your pipeline to print the version of the .NET Core SDK. Either use the [.NET Core Tool Installer](#build-environment) to deploy the same version on the agent, or update your projects and development machine to the newer version of the .NET Core SDK. * You might be using some logic in the Visual Studio IDE that isn't encoded in your pipeline. Azure Pipelines runs each of the commands you specify in the tasks one after the other in a new process. Examine the logs from the pipelines build to see the exact commands that ran as part of the build. -Repeat the same commands in the same order on your development machine to locate the problem. +To locate the problem, repeat the same commands in the same order on your development machine. * If you have a mixed solution that includes some .NET Core projects and some .NET Framework projects, you should also use the **NuGet** task to restore packages specified in `packages.config` files. Add the **MSBuild** or **Visual Studio Build** task to build the .NET Framework projects. -* Your builds might fail intermittently while restoring packages: either NuGet.org is having issues, or there are networking problems between the Azure data center and NuGet.org. You may want to explore whether using Azure Artifacts with NuGet.org as an upstream source improves the reliability of your builds, as it's not in our control. +* Your builds might fail intermittently while restoring packages: either NuGet.org is having issues or there are networking problems between the Azure data center and NuGet.org. You can explore whether using Azure Artifacts with NuGet.org as an upstream source improves the reliability of your builds, as it's not in our control. -* Occasionally, when we roll out a new version of the .NET Core SDK or Visual Studio, your build might break. For example, if a newer version or feature of the NuGet tool gets shipped with the SDK. To isolate this issue, use the **.NET Core Tool Installer** task to specify the version of the .NET Core SDK that's used in your build. +* Occasionally, a when new version of the .NET Core SDK or Visual Studio is rolled out, your build might break. For example, a newer version or feature of the NuGet tool is shipped with the SDK could break your build. To isolate this issue, use the **.NET Core Tool Installer** task to specify the version of the .NET Core SDK used in your build. ## FAQ -### Q: Where can I learn more about Azure Artifacts and the TFS Package Management service? +### Q: Where can I learn more about Azure Artifacts? -A: [Package Management in Azure Artifacts](../../artifacts/index.yml) +A: [Azure Artifacts](../../artifacts/index.yml) ### Q: Where can I learn more about .NET Core commands? diff --git a/docs/pipelines/ecosystems/ecosystems.md b/docs/pipelines/ecosystems/ecosystems.md index 5360d7533a4..a634dbf6376 100644 --- a/docs/pipelines/ecosystems/ecosystems.md +++ b/docs/pipelines/ecosystems/ecosystems.md @@ -20,7 +20,7 @@ monikerRange: '<= azure-devops' You can select from the following languages and platforms to find guidance for building and deploying your app. -::: moniker range=" <= tfs-2018 || >= azure-devops-2019" +::: moniker range="<=azure-devops" ## Build your app @@ -28,7 +28,7 @@ Build your app with any of the following languages. ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column::: @@ -96,97 +96,17 @@ Build your app with any of the following languages. :::image type="icon" source="./media/index/logo_uwp.png"::: [UWP](/previous-versions/azure/devops/pipelines/apps/windows/universal) :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_xamarin.png"::: - [Xamarin](xamarin.md) - :::column-end::: :::column::: :::image type="icon" source="./media/index/logo_xcode.png"::: [Xcode](xcode.md) :::column-end::: -:::row-end::: - -::: moniker-end - -::: moniker range="tfs-2018" - -:::row::: - :::column::: - :::image type="icon" source="./media/index/logo_aspnetcore.png"::: - [.NET Core](dotnet-core.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_android.png"::: - [Android](android.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_net.png"::: - [ASP.NET](../apps/aspnet/build-aspnet-4.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_Cplusplus.png"::: - [C/C++ with GCC](../apps/c-cpp/gcc.md) - :::column-end::: -:::row-end::: - -:::row::: :::column::: - :::image type="icon" source="./media/index/logo_visual-studio.png"::: - [C/C++ with VC++](../apps/windows/cpp.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_dockercontainer.png"::: - [Containers](./containers/build-image.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_go.png"::: - [Go](go.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_java.png"::: - [Java](java.md) - :::column-end::: -:::row-end::: - -:::row::: - :::column::: - :::image type="icon" source="./media/index/logo_nodejs.png"::: - [JavaScript and Node.js](javascript.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_php.png"::: - [PHP](php.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_python.png"::: - [Python](python.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_ruby.png"::: - [Ruby](ruby.md) - :::column-end::: -:::row-end::: - -:::row::: - :::column::: - :::image type="icon" source="./media/index/logo_uwp.png"::: - [UWP](/previous-versions/azure/devops/pipelines/apps/windows/universal) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_xamarin.png"::: - [Xamarin](xamarin.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_xcode.png"::: - [Xcode](xcode.md) - :::column-end::: - :::column::: :::column-end::: :::row-end::: ::: moniker-end -::: moniker range="tfs-2018 || >= azure-devops-2019" +::: moniker range="<=azure-devops" ## Deploy your app @@ -194,7 +114,7 @@ Deploy your app to any of the following platforms. ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column::: @@ -218,7 +138,7 @@ Deploy your app to any of the following platforms. :::row::: :::column::: :::image type="icon" source="./media/index/logo_linux-color.png"::: - [Linux VM](../apps/cd/deploy-linuxvm-deploygroups.md) + [Linux VM](/azure/devops/pipelines/apps/cd/deploy-linuxvm-deploygroups) :::column-end::: :::column::: :::image type="icon" source="./media/index/logo_npm.png"::: @@ -230,14 +150,14 @@ Deploy your app to any of the following platforms. :::column-end::: :::column::: :::image type="icon" source="./media/index/virtualmachine.png"::: - [Virtual Machine Manager](../targets/scvmm.md) + [Virtual machine resources](../process/environments-virtual-machines.md) :::column-end::: :::row-end::: :::row::: :::column::: :::image type="icon" source="./media/index/virtualmachine.png"::: - [VMware](../targets/vmware.md) + [Virtual machine resources](../process/environments-virtual-machines.md) :::column-end::: :::column::: :::image type="icon" source="./media/index/appservice.png"::: @@ -253,57 +173,3 @@ Deploy your app to any of the following platforms. ::: moniker-end -::: moniker range="tfs-2018" - -:::row::: - :::column::: - :::image type="icon" source="./media/index/sqldatabase.png"::: - [Azure SQL database](../targets/azure-sqldb.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/app-service-web.png"::: - [Azure Web Apps](../targets/webapp.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_linux-color.png"::: - [Linux VM](../apps/cd/deploy-linuxvm-deploygroups.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/logo_npm.png"::: - [npm](../artifacts/npm.md) - :::column-end::: -:::row-end::: - -:::row::: - :::column::: - :::image type="icon" source="./media/index/logo_nuget.png"::: - [NuGet](../artifacts/nuget.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/virtualmachine.png"::: - [Virtual Machine Manager](../targets/scvmm.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/virtualmachine.png"::: - [VMware](../targets/vmware.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/appservice.png"::: - [Web App for Containers](../apps/cd/deploy-docker-webapp.md) - :::column-end::: -:::row-end::: - -:::row::: - :::column::: - :::image type="icon" source="./media/index/virtualmachine.png"::: - [Windows VM](../apps/cd/deploy-webdeploy-iis-deploygroups.md) - :::column-end::: - :::column::: - :::column-end::: - :::column::: - :::column-end::: - :::column::: - :::column-end::: -:::row-end::: - -::: moniker-end diff --git a/docs/pipelines/ecosystems/github-actions.md b/docs/pipelines/ecosystems/github-actions.md deleted file mode 100644 index af3bb3d430f..00000000000 --- a/docs/pipelines/ecosystems/github-actions.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Trigger an Azure Pipelines run from GitHub Actions -description: Start an Azure DevOps pipeline run from within a GitHub action -ms.author: jukullam -ms.custom: github-actions-azure, contperf-fy21q4, freshness-fy22q2 -ms.date: 10/25/2022 -monikerRange: azure-devops -author: juliakm -ms.topic: quickstart ---- -# Trigger an Azure Pipelines run from GitHub Actions - -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -Get started using [GitHub Actions](https://docs.github.com/en/actions) with Azure Pipelines. GitHub Actions help you automate your software development workflows from within GitHub. You can deploy workflows in the same place where you store code and collaborate on pull requests and issues. - -If you have both Azure Pipelines and GitHub Actions workflows, you might want to trigger a pipeline run from within a GitHub action. For example, you might have a specific set of pipeline tasks that you want to trigger from your GitHub Actions workflow. You can trigger a pipeline run with the [Azure Pipelines action](https://github.com/marketplace/actions/azure-pipelines-action). - -## Prerequisites - -- A working Azure pipeline. [Create your first pipeline](../create-first-pipeline.md). -- A GitHub account with a repository. [Join GitHub](https://github.com/join) and [create a repository](https://docs.github.com/en/github/getting-started-with-github/create-a-repo). -- An Azure DevOps personal access token (PAT) with the scope Build (Read & Execute) to use with GitHub Actions. [Create a PAT](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). - -## Authenticate with Azure Pipelines - -[!INCLUDE [include](~/../docs/reusable-content/github-actions/authenticate-with-pat.md)] - -## Create a GitHub workflow that triggers a pipeline - -[GitHub workflows](/azure/developer/github/github-actions) are a series of actions (like tasks in Azure Pipelines). Use the [Azure Pipelines Action](https://github.com/marketplace/actions/azure-pipelines-action) to trigger a pipeline run. - -Do the following steps to create a workflow from within GitHub Actions. Then, you can adapt the workflow to meet your needs. The relevant section for connecting to Azure Pipelines is the Azure Pipelines action. - -1. In your repository on GitHub, create a YAML file in the `.github/workflows` directory. - -2. Copy the following contents into your YAML file. Customize the `azure-devops-project-url` and `azure-pipeline-name` values. The `azure-devops-project-url` shouldn't have a trailing slash. - - ```yaml - name: CI - - # Run this workflow every time a commit gets pushed to main or a pull request gets opened against main - on: - push: - branches: - - main - pull_request: - branches: - - main - - jobs: - build: - name: Call Azure Pipeline - runs-on: ubuntu-latest - steps: - - name: Azure Pipelines Action - uses: Azure/pipelines@v1 - with: - azure-devops-project-url: https://dev.azure.com/organization/project-name - azure-pipeline-name: 'My Pipeline' - azure-devops-token: ${{ secrets.AZURE_DEVOPS_TOKEN }} - ``` - -3. Commit and push your workflow file. - -4. The workflow runs every time you push a commit to main or open a pull request against main. To verify that your action ran, open your GitHub repository and select **Actions**. - - :::image type="content" source="media/github-actions-header.png" alt-text="Select Actions in the GitHub navigation"::: - -5. Select the workflow title to see more information about the run. You should see a green check mark for the Azure Pipelines Action. Open the Action to see a direct link to the pipeline run. - - :::image type="content" source="media/pipeline-run-from-github.png" alt-text="GitHub Actions detailed run"::: - - -## Branch considerations - -The pipeline your branch runs on depends on whether your pipeline is in the same repo as your GitHub workflow file. - -* If the pipeline and the GitHub workflow are in different repositories, the triggered pipeline version in the branch specified by **Default branch for manual and scheduled builds** runs. -* If the pipeline and the GitHub workflow are in the same repository, the triggered pipeline version in the same branch as the triggering pipeline runs. - -To configure the **Default branch for manual and scheduled builds** setting, see [Default branch for manual and scheduled builds setting](../process/pipeline-default-branch.md). - -## Clean up resources - -If you're not going to continue to use your GitHub workflow, [disable the workflow](https://docs.github.com/actions/managing-workflow-runs/disabling-and-enabling-a-workflow). - - -## Next steps - -> [!div class="nextstepaction"] -> [Deploy to Azure using GitHub Actions](/azure/developer/github/github-actions) diff --git a/docs/pipelines/ecosystems/go.md b/docs/pipelines/ecosystems/go.md index 47bd15aa68a..957d476af7b 100644 --- a/docs/pipelines/ecosystems/go.md +++ b/docs/pipelines/ecosystems/go.md @@ -1,10 +1,10 @@ --- -title: Build and test Go projects +title: Build and test Go projects description: Build and test Go projects with Azure Pipelines & Azure DevOps ms.topic: quickstart ms.assetid: a72557df-6df4-4fb6-b437-be0730624e3c ms.reviewer: azooinmyluggage -ms.custom: seodec18, freshness-fy22q2, devdivchpfy22 +ms.custom: freshness-fy22q2, devdivchpfy22 ms.date: 05/05/2022 monikerRange: 'azure-devops' --- @@ -29,7 +29,13 @@ https://github.com/MicrosoftDocs/pipelines-go [!INCLUDE [include](includes/sign-in-azure-pipelines.md)] -[!INCLUDE [include](includes/create-project.md)] + +1. In a browser, go to [dev.azure.com](https://dev.azure.com) and sign in. +1. Select your organization. +1. Create a new project by selecting **New project** or **Create project** if creating the first project in the organization. +1. Enter a **Project name**. +1. Select the **Visibility** for your project. +1. Select **Create**. ## Create the pipeline @@ -179,7 +185,7 @@ Use `go build` to build your Go project. Add the following snippet to your `azur ## Test -Use `go test` to test your go module and its subdirectories (`./...`). Add the following snippet to your `azure-pipelines.yml` file: +Use `go test` to test your Go module and its subdirectories (`./...`). Add the following snippet to your `azure-pipelines.yml` file: ```yaml - task: Go@0 @@ -189,7 +195,7 @@ Use `go test` to test your go module and its subdirectories (`./...`). Add the f workingDirectory: '$(System.DefaultWorkingDirectory)' ``` -When you're ready, Commit a new _azure-pipelines.yml_ file to your repository and update the commit message. Select **Save and run**. +When you're ready, commit a new _azure-pipelines.yml_ file to your repository and update the commit message. Select **Save and run**. > [!div class="mx-imgBorder"] > ![Save and run button in a new YAML pipeline](media/save-and-run-button-new-yaml-pipeline.png) @@ -213,4 +219,4 @@ For your Go app, you can also [build an image](containers/build-image.md) and [p ## Related extensions -[Go extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go) (Microsoft) +[Go extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go) diff --git a/docs/pipelines/ecosystems/includes/create-pipeline-before-template-selected.md b/docs/pipelines/ecosystems/includes/create-pipeline-before-template-selected.md index 8ca7a98e90f..8c00904bf6d 100644 --- a/docs/pipelines/ecosystems/includes/create-pipeline-before-template-selected.md +++ b/docs/pipelines/ecosystems/includes/create-pipeline-before-template-selected.md @@ -4,13 +4,13 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 05/05/2022 +ms.date: 12/01/2023 ms.custom: devdivchpfy22 --- -1. Sign-in to your Azure DevOps organization and go to your project. +1. Sign in to your Azure DevOps organization and go to your project. -1. Go to **Pipelines**, and then select **New pipeline**. +1. Go to **Pipelines**, and then select **New pipeline** or **Create pipeline** if creating your first pipeline. 1. Do the steps of the wizard by first selecting **GitHub** as the location of your source code. @@ -18,4 +18,4 @@ ms.custom: devdivchpfy22 1. When you see the list of repositories, select your repository. -1. You might be redirected to GitHub to install the Azure Pipelines app. If so, select **Approve & install**. +1. You might be redirected to GitHub to install the Azure Pipelines app. If so, select **Approve & install**. \ No newline at end of file diff --git a/docs/pipelines/ecosystems/includes/create-project.md b/docs/pipelines/ecosystems/includes/create-project.md deleted file mode 100644 index beb55cc63cf..00000000000 --- a/docs/pipelines/ecosystems/includes/create-project.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -ms.topic: include -ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: jukullam -author: juliakm -ms.date: 05/05/2022 -ms.custom: devdivchpfy22 ---- - -Within your selected organization, create a _project_. If you don't have any projects in your organization, you see a **Create a project to get started** screen. Otherwise, select the **New Project** button in the upper-right corner of the dashboard. diff --git a/docs/pipelines/ecosystems/includes/create-service-connection.md b/docs/pipelines/ecosystems/includes/create-service-connection.md index 1b912ed0037..6183ec1db2b 100644 --- a/docs/pipelines/ecosystems/includes/create-service-connection.md +++ b/docs/pipelines/ecosystems/includes/create-service-connection.md @@ -4,7 +4,8 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 06/16/2023 +ms.date: 10/16/2024 +ms.custom: arm2024 --- ## Create the service connection @@ -13,16 +14,18 @@ ms.date: 06/16/2023 2. On the settings page, select **Pipelines** > **Service connections**, select **New service connection**, and then select **Azure Resource Manager**. -3. Select **Service principal (automatic)** and **Next**. +3. Select **App registration (automatic)** with the credential option **Workload identity federation**. -4. The **Add an Azure Resource Manager service connection** dialog box appears. +4. Set the service connection options: * **Scope** Select **Subscription**. * **Subscription** Select your Azure portal subscription. * **Resource Group** Select the resource group you created earlier. * **Service connection name** Type a name and then copy and paste it into a text file so you can use it later. - * Select **Grant access permission to all pipelines**. To select this option, you'll need the [service connection **Administrator** role](../../library/add-resource-protection.md). + * If desired, select **Grant access permission to all pipelines**. To select this option, you'll need the [service connection **Administrator** role](../../library/add-resource-protection.md). ![New service connection dialog box](../media/add-service-connection-dialog-box.png) > [!Tip] > If you need to create a connection to an Azure subscription that's owned by someone else, see [Create an Azure Resource Manager service connection with an existing service principal](../../library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-with-an-existing-service-principal). + +3. Select **Save** to create your new service connection. diff --git a/docs/pipelines/ecosystems/includes/ecosystems-prerequisites.md b/docs/pipelines/ecosystems/includes/ecosystems-prerequisites.md new file mode 100644 index 00000000000..a33f7dfcec0 --- /dev/null +++ b/docs/pipelines/ecosystems/includes/ecosystems-prerequisites.md @@ -0,0 +1,28 @@ +--- +ms.topic: include +ms.service: azure-devops-pipelines +ms.manager: mijacobs +ms.author: jukullam +author: juliakm +ms.date: 04/16/2025 +--- + +::: moniker range="azure-devops" + +| **Product** | **Requirements** | +|---|---| +| **Azure DevOps** | - An [Azure DevOps project](../../../organizations/projects/create-project.md).
      - An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../../licensing/concurrent-jobs.md) or you can request a free tier.
      - Basic knowledge of YAML and Azure Pipelines. For more information, see [Create your first pipeline](../../create-first-pipeline.md).
      - **Permissions:**
           - To create a pipeline: you must be in the **Contributors** group and the group needs to have *Create build pipeline* permission set to Allow. Members of the [Project Administrators group](../../../organizations/security/permissions.md) can manage pipelines.
          - To create service connections: You must have the *Administrator* or *Creator* role for [service connections](../../library/add-resource-protection.md). +| **GitHub** | - A [GitHub](https://github.com) account.
      - A [GitHub service connection](../../library/service-endpoints.md) to authorize Azure Pipelines.| +| **Azure** | An [Azure subscription](https://azure.microsoft.com/free/). | + +::: moniker-end + +::: moniker range="< azure-devops" + +| **Product** | **Requirements** | +|---|---| +| **Azure DevOps** | - An [Azure DevOps project](../../../organizations/projects/create-project.md).
      - A self-hosted agent. To create one, see [Self-hosted agents](../../agents/agents.md#self-hosted-agents).
      - Basic knowledge of YAML and Azure Pipelines. For more information, see [Create your first pipeline](../../create-first-pipeline.md).
      - **Permissions:**
          - To create a pipeline: you must be in the **Contributors** group and the group needs to have *Create build pipeline* permission set to Allow. Members of the [Project Administrators group](../../../organizations/security/permissions.md) can manage pipelines.
          - To create service connections: You must have the *Administrator* or *Creator* role for [service connections](../../library/add-resource-protection.md). +| **GitHub** | - A [GitHub](https://github.com) account.
      - A [GitHub service connection](../../library/service-endpoints.md) to authorize Azure Pipelines.| +| **Azure** | An [Azure subscription](https://azure.microsoft.com/free/). | + +::: moniker-end \ No newline at end of file diff --git a/docs/pipelines/ecosystems/java-webapp.md b/docs/pipelines/ecosystems/java-webapp.md index de428e72067..f73b05456da 100644 --- a/docs/pipelines/ecosystems/java-webapp.md +++ b/docs/pipelines/ecosystems/java-webapp.md @@ -2,10 +2,10 @@ title: Build and deploy to a Java web app on Linux description: Continuous integration and deployment (CI/CD) to a Java web app on Linux. ms.topic: tutorial -ms.custom: devx-track-extended-java +ms.custom: devx-track-extended-java, linux-related-content ms.assetid: 49253EA0-9CD6-4082-A303-95F78C7599C2 ms.date: 12/22/2021 -monikerRange: 'azure-devops' +monikerRange: "<=azure-devops" --- # Build & deploy to Java web app @@ -21,8 +21,7 @@ For more information, see [Java for Azure App Service](/azure/app-service/config ## Prerequisites -[!INCLUDE [include](../includes/prerequisites.md)] -[!INCLUDE [include](../includes/azure-prerequisites.md)] +[!INCLUDE [ecosystems-prerequisites](includes/ecosystems-prerequisites.md)] ## Get the code diff --git a/docs/pipelines/ecosystems/java.md b/docs/pipelines/ecosystems/java.md index c49d033ad84..5fab74d91e0 100644 --- a/docs/pipelines/ecosystems/java.md +++ b/docs/pipelines/ecosystems/java.md @@ -2,99 +2,100 @@ title: Build Java apps description: Automatically build Java apps with Azure Pipelines. ms.assetid: 604822a1-a46b-49d3-ad30-8152e9420758 -ms.reviewer: dastahel ms.custom: freshness-fy22q2, devdivchpfy22, devx-track-extended-java ms.topic: quickstart -ms.date: 10/03/2022 -monikerRange: '<= azure-devops' +ms.date: 02/08/2024 +monikerRange: "<=azure-devops" --- # Build Java apps [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -> [!NOTE] -> The following guidance uses YAML-based pipelines available in Azure Pipelines. Use tasks that correspond to those used in the following YAML. -::: moniker-end +You can use a pipeline to automatically: + +* Build your project using [Maven](https://maven.apache.org/), [Gradle](https://gradle.org/), or [Ant](https://ant.apache.org/). +* Run tests and code analysis tools. +* Publish your app to your pipeline and Azure Artifacts. +* Deploy your app to [Azure App Service](java-webapp.md), [Azure Functions](java-function.md), or [Azure Kubernetes Service](kubernetes/aks-template.md). -You can use a pipeline to automatically build and test your Java projects. After you build and test your app, you can deploy your app to [Azure App Service](java-webapp.md), [Azure Functions](java-function.md), or [Azure Kubernetes Service](kubernetes/aks-template.md). If you're working on an Android project, see [Build, test, and deploy Android apps](android.md). +If you're working on an Android project, see [Build, test, and deploy Android apps](android.md). ## Prerequisites -You must have the following items in Azure DevOps: +[!INCLUDE [ecosystems-prerequisites](includes/ecosystems-prerequisites.md)] -- A project. If you don't have one, [Create a project](../../organizations/projects/create-project.md) now. -- A pipeline. If you don't have one, [Create a pipeline](#build-your-code) now. +## Create a GitHub repository -### Create a pipeline +Fork the following repo to your GitHub account: -::: moniker range="> azure-devops-2019" +```text +https://github.com/MicrosoftDocs/pipelines-java +``` -1. Fork the following repo at GitHub: +## Create a pipeline - ``` - https://github.com/MicrosoftDocs/pipelines-java - ``` +::: moniker range=">= azure-devops" 1. Sign in to your Azure DevOps organization and go to your project. -1. Go to **Pipelines**, and then select **New pipeline**. +1. Go to **Pipelines**, and then select **New pipeline** or **Create pipeline** if creating the first pipeline in the project. 1. Perform the steps of the wizard by first selecting **GitHub** as the location of your source code. You might be redirected to GitHub to sign in. If so, enter your GitHub credentials. 1. Select your repo. You might be redirected to GitHub to install the Azure Pipelines app. If so, select **Approve & install**. -1. When you see the **Configure** tab, select **Maven** or **Gradle** or **Ant** depending on how you want to [build your code](#build-your-code). +1. When you see the **Configure your pipeline** tab, select **Maven**, **Gradle**, or **Ant** depending on how you want to [build your code](#build-your-code). -1. When you're ready, select **Save and run**. +1. A `azure-pipelines.yml` file containing your pipeline definition is created in your repo and opened in the YAML editor. You can customize the pipeline by adding more tasks or modifying the existing tasks. For more information about the build tasks, see [Build your code](#build-your-code). -1. Commit a new _azure-pipelines.yml_ file to your repo. Select **Save and run** again. +1. When you're finished editing the `azure-pipelines.yml`, select **Save and run**. - If you want to watch your pipeline in action, select the build job. +1. To commit the `azure-pipelines.yml` file to your repo, select **Save and run** again. - You just created and ran a pipeline, because your code appeared to be a good match for the [Maven](https://github.com/microsoft/azure-pipelines-yaml/blob/master/templates/maven.yml) template that we automatically created for you. + Select **Job** to watch your pipeline in action. - You now have a working YAML pipeline (`azure-pipelines.yml`) in your repo that's ready for you to customize! +::: moniker-end -1. When you're ready to make changes to your pipeline, select it in the **Pipelines** page, and then **Edit** the `azure-pipelines.yml` file. +::: moniker range="< azure-devops" -::: moniker-end +1. Go to your collection and select your project. -::: moniker range="azure-devops-2019" +1. Select **Pipelines**, and then select **New pipeline** or **Create pipeline** if creating the first pipeline in the project. -1. Import the following repo into your Git repo in Azure DevOps Server 2019: +1. Perform the steps of the wizard by first selecting **GitHub Enterprise Server** as the location of your source code. - ``` - https://github.com/MicrosoftDocs/pipelines-java - ``` +1. Use an existing GitHub service connection or create a new one. -1. Save the pipeline and queue a build. When the ```Build #nnnnnnnn.n has been queued``` message appears, select the number link to see your pipeline in action. You now have a working pipeline that's ready for you to customize anytime! -::: moniker-end + To create a service connection: + + 1. Select **Connect to GitHub Enterprise Server**. + 1. Enter your GitHub Enterprise Server URL. + 1. Enter your GitHub Enterprise Server personal access token. If you don't have a personal access token, you can create one in your GitHub Enterprise Server account. For more information, see [Creating a personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). + +1. Select your repository. You might be redirected to GitHub to install the Azure Pipelines app. If so, select **Approve & install**. -::: moniker range="< azure-devops-2019" +1. When you see the **Configure your pipeline** tab, select **Maven**, **Gradle**, or **Ant** depending on how you want to [build your code](#build-your-code). -1. Import the following repo into your Git repo in TFS: +1. An `azure-pipelines-yml` file containing your pipeline definition is created in your repo and opened in the YAML editor. You can customize the pipeline by adding more tasks or modifying the existing tasks. For more information about the build tasks, see [Build your code](#build-your-code). - ``` - https://github.com/MicrosoftDocs/pipelines-java - ``` +1. When you're finished editing the `azure-pipelines.yml`, select **Save and run**. - This template automatically adds the tasks you need to build the code in the sample repo. +1. To commit the `azure-pipelines.yml` file to your repo, select **Save and run** again. -1. Save the pipeline and queue a build. When the ```Build #nnnnnnnn.n has been queued``` message appears, select the number link to see your pipeline in action. You now have a working pipeline that's ready for you to customize anytime! + You can select **Job** to watch your pipeline in action. ::: moniker-end -Read further to learn some of the more common ways to customize your pipeline. +You now have a working YAML pipeline (`azure-pipelines.yml`) in your repo that's ready for you to customize! To make changes to your pipeline, select it in the **Pipelines** page, and then **Edit** the `azure-pipelines.yml` file. ## Build environment -::: moniker range=">=azure-devops-2020" +::: moniker range=">= azure-devops" -You can use Azure Pipelines to build Java apps without needing to set up any infrastructure of your own. You can build on Windows, Linux, or macOS images. The Microsoft-hosted agents in Azure Pipelines have modern JDKs and other tools for Java pre-installed. To know which versions of Java are installed, see [Microsoft-hosted agents](../agents/hosted.md). +You can use Azure Pipelines to build Java apps without needing to set up any infrastructure of your own. You can build on Windows, Linux, or macOS images. The Microsoft-hosted agents in Azure Pipelines have modern JDKs and other tools for Java preinstalled. To know which versions of Java are installed, see [Microsoft-hosted agents](../agents/hosted.md). -Update the following snippet in your `azure-pipelines.yml` file to select the appropriate image. +To select the appropriate image, update the following snippet in your `azure-pipelines.yml` file. ```yaml pool: @@ -103,23 +104,33 @@ pool: See [Microsoft-hosted agents](../agents/hosted.md) for a complete list of images. -As an alternative to using Microsoft-hosted agents, you can set up [self-hosted agents](../agents/agents.md#install) with Java installed. You can also use self-hosted agents to save more time if you have a large repo or you can run incremental builds. +As an alternative to using Microsoft-hosted agents, you can set up [self-hosted agents](../agents/agents.md#install) with Java installed. You can also use self-hosted agents to save more time if you have a large repo or you run incremental builds. ::: moniker-end ::: moniker range="< azure-devops" -Your builds run on a [self-hosted agent](../agents/agents.md#install). Make sure that you have Java installed on the agent. +Your builds run on a [self-hosted agent](../agents/agents.md#install). Make sure that you have Java and the tools necessary to build with your chosen method installed on the agent's host. -::: moniker-end +You can select your agent pool and the agent capabilities in the **Agent pool** and **Agent Specification** sections of the **Options** tab in the pipeline editor. -::: moniker range=">= azure-devops-2019" +For example to specify the agent pool and an agent with the Maven capability, add the following snippet to your `azure-pipelines.yml` file. + +```yaml +pool: + name: MyPool + demands: maven +``` + +::: moniker-end ## Build your code +You can build your Java app with Maven, Gradle, Ant, or a script. The following sections show you how to add a build step to your pipeline for each method. + ### Maven -With your Maven build, the following snippet gets added to your `azure-pipelines.yml` file. You can change values, such as the path to your `pom.xml` file, to match your project configuration. See the [Maven](/azure/devops/pipelines/tasks/reference/maven-v3) task for more information about these options. +With your Maven build, the following tasks are added to your `azure-pipelines.yml` file. Replace the values to match your project. For more information about the task options, see the [Maven task](/azure/devops/pipelines/tasks/reference/maven-v3). ```yaml steps: @@ -128,14 +139,14 @@ steps: mavenPomFile: 'pom.xml' mavenOptions: '-Xmx3072m' javaHomeOption: 'JDKVersion' - jdkVersionOption: '1.8' + jdkVersionOption: 'default' jdkArchitectureOption: 'x64' publishJUnitResults: true testResultsFiles: '**/TEST-*.xml' goals: 'package' ``` -For [Spring Boot](https://spring.io/projects/spring-boot), you can use the [Maven](/azure/devops/pipelines/tasks/reference/maven-v3) task as well. Make sure that your `mavenPomFile` value reflects the path to your `pom.xml` file. For example, if you're using the [Spring Boot sample repo](https://github.com/spring-guides/gs-spring-boot), your path will be `complete/pom.xml`. +For [Spring Boot](https://spring.io/projects/spring-boot), you can use the [Maven](/azure/devops/pipelines/tasks/reference/maven-v3) task as well. Make sure that your `mavenPomFile` value reflects the path to your `pom.xml` file. For example, if you're using the [Spring Boot sample repo](https://github.com/spring-guides/gs-spring-boot), your path is `complete/pom.xml`. #### Customize the build path @@ -143,13 +154,11 @@ Adjust the `mavenPomFile` value if your `pom.xml` file isn't in the root of the #### Customize Maven goals -Set the **goals** value to a space-separated list of goals for Maven to execute, such as `clean package`. - -For details about common Java phases and goals, see [Apache's Maven documentation](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html). +Set the **goals** value to a space-separated list of goals for Maven to execute, such as `clean package`. For details about common Java phases and goals, see [Apache's Maven documentation](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html). ### Gradle -With the Gradle build, the following snippet gets added to your `azure-pipelines.yml` file. For more information about these options, see the [Gradle](/azure/devops/pipelines/tasks/reference/gradle-v3) task. +With the Gradle build, the following task is added to your `azure-pipelines.yml` file. For more information about these options, see the [Gradle](/azure/devops/pipelines/tasks/reference/gradle-v3) task. ```yaml steps: @@ -159,16 +168,20 @@ steps: gradleWrapperFile: 'gradlew' gradleOptions: '-Xmx3072m' javaHomeOption: 'JDKVersion' - jdkVersionOption: '1.8' + jdkVersionOption: 'default' jdkArchitectureOption: 'x64' publishJUnitResults: true testResultsFiles: '**/TEST-*.xml' tasks: 'build' ``` +#### Gradle wrapper + +You need to have a `gradlew` file in your repo. If you don't have one, you can generate it by running `gradle wrapper` in your project's root directory. For information about creating a Gradle wrapper, see the [Gradle](/azure/devops/pipelines/tasks/reference/gradle-v3#how-do-i-generate-a-wrapper-from-my-gradle-project). + #### Choose the version of Gradle -The version of Gradle installed on the agent machine will be used unless your repo's `gradle/wrapper/gradle-wrapper.properties` file has a `distributionUrl` property that specifies a different Gradle version to download and use during the build. +The version of Gradle installed on the agent machine is used unless your repo's `gradle/wrapper/gradle-wrapper.properties` file has a `distributionUrl` property that specifies a different Gradle version to download and use during the build. #### Adjust the build path @@ -179,13 +192,11 @@ Adjust the `gradleWrapperFile` value if your `gradlew` file isn't in the root of #### Adjust Gradle tasks -Adjust the **tasks** value for the tasks that Gradle should execute, such as `build` or `check`. - -For more information about common Java Plugin tasks for Gradle, see [Gradle's documentation](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_tasks). +Adjust the **tasks** value for the tasks that Gradle should execute, such as `build` or `check`. For more information about common Java Plugin tasks for Gradle, see [Gradle's documentation](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_tasks). ### Ant -With Ant build, the following snippet is added to your `azure-pipelines.yml` file. Change values, such as the path to your `build.xml` file to match your project configuration. For more information about these options, see the [Ant](/azure/devops/pipelines/tasks/reference/ant-v1) task. +With Ant build, add the following task to your `azure-pipelines.yml` file. Change values, such as the path to your `build.xml` file, to match your project configuration. For more information about these options, see the [Ant](/azure/devops/pipelines/tasks/reference/ant-v1) task. If using the sample repo, you need to provide a `build.xml` file in your repo. ```yaml steps: @@ -194,7 +205,7 @@ steps: workingDirectory: '' buildFile: 'build.xml' javaHomeOption: 'JDKVersion' - jdkVersionOption: '1.8' + jdkVersionOption: 'default' jdkArchitectureOption: 'x64' publishJUnitResults: false testResultsFiles: '**/TEST-*.xml' @@ -218,7 +229,7 @@ steps: #### Script file -This snippet runs a script file that is in your repo. For details, see the [Shell Script](/azure/devops/pipelines/tasks/reference/shell-script-v2), [Batch script](/azure/devops/pipelines/tasks/reference/batch-script-v1), or [PowerShell](/azure/devops/pipelines/tasks/reference/powershell-v2) task. +This task runs a script file that is in your repo. For details, see the [Shell Script](/azure/devops/pipelines/tasks/reference/shell-script-v2), [Batch script](/azure/devops/pipelines/tasks/reference/batch-script-v1), or [PowerShell](/azure/devops/pipelines/tasks/reference/powershell-v2) task. ```YAML steps: @@ -229,17 +240,15 @@ steps: ## Next steps -After you've built and tested your app, you can upload the build output to Azure Pipelines, create and publish a Maven package, or package the build output into a _.war/jar_ file to be deployed to a web application. - -::: moniker-end +You can publish your build output to your pipeline. You can package and publish your app in a Maven package or a _.war/jar_ file to be deployed to a web application. ::: moniker range=">=azure-devops-2020" Learn more about creating a CI/CD pipeline for your deployment target: -- [Build and deploy to a Java web app](java-webapp.md) -- [Build and deploy Java to Azure Functions](java-function.md) -- [Build and deploy Java to Azure Kubernetes service](kubernetes/aks-template.md) +- [Azure App Service](java-webapp.md) +- [Azure Functions](java-function.md) +- [Azure Kubernetes service](kubernetes/aks-template.md) ::: moniker-end diff --git a/docs/pipelines/ecosystems/javascript.md b/docs/pipelines/ecosystems/javascript.md index 2462c39c1d9..1b4c83f1b88 100644 --- a/docs/pipelines/ecosystems/javascript.md +++ b/docs/pipelines/ecosystems/javascript.md @@ -1,93 +1,50 @@ --- -title: Quickstart - Use Azure Pipelines to build and publish a Node.js package -description: Build, deploy, and test JavaScript and Node.js apps with Azure Pipelines +title: Build and publish a Node.js package +description: Learn how to use Azure Pipelines to build, deploy, and test a Node.js app. ms.assetid: 5BB4D9FA-DCCF-4661-B52B-0C42006A2AE5 ms.reviewer: vijayma ms.topic: quickstart -ms.custom: seodec18, seo-javascript-september2019, contperf-fy20q4, devx-track-js, freshness-fy22q2, contperf-fy22q2 -ms.date: 04/17/2023 +ms.custom: devx-track-js, freshness-fy22q2 +ms.date: 07/08/2024 monikerRange: '<= azure-devops' -zone_pivot_groups: pipelines-version --- -# Quickstart - Use Azure Pipelines to build and publish a Node.js package +# Build and publish a Node.js package [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can use an Azure DevOps pipeline to build, deploy, and test JavaScript apps. - -This quickstart walks through how to use a pipeline to create a Node.js package with Node Package Manager (npm) and publish a pipeline artifact. - -::: moniker range=">=azure-devops-2020" +In this quickstart, you use a pipeline to create a Node.js package with Node Package Manager (npm) and publish a pipeline artifact. You learn how to use Azure Pipelines to build, deploy, and test your JavaScript apps. ## Prerequisites -You must have the following items in Azure DevOps: - -* A GitHub account where you can create a repository. [Create one for free](https://github.com). -* An Azure DevOps organization and project. [Create one for free](../get-started/pipelines-sign-up.md). -* An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can request a free tier. - -::: moniker-end - -::: zone pivot="pipelines-yaml" - -::: moniker range="tfs-2018" - -YAML is not available for TFS 2018. - -::: moniker-end - -::: moniker range=">=azure-devops-2020" - -## 1 - Fork the sample code - -Fork the following sample Express.js server app at GitHub. - -``` -https://github.com/Azure-Samples/js-e2e-express-server -``` - -## 2 - Create your pipeline - - -1. Sign in to [Azure Pipelines](https://azure.microsoft.com/services/devops/pipelines). Your browser will go to `https://dev.azure.com/my-organization-name` and display your Azure DevOps dashboard. - -1. Go to your project and select **Pipelines** > **Create a new pipeline**. - -1. Select **GitHub** as the location of your source code. - -1. If you're redirected to GitHub to sign in, enter your GitHub credentials. +[!INCLUDE [ecosystems-prerequisites](includes/ecosystems-prerequisites.md)] -1. When the list of repositories appears, select your Node.js sample repository. +## Fork the sample code -1. Azure Pipelines analyzes the code in your repository and recommends the `Node.js` template for your pipeline. Select that template. +Fork the sample Express.js server app. -1. Azure Pipelines generates a YAML file for your pipeline. Select **Save and run** > **Commit directly to the main branch**, and then choose **Save and run** again. +1. Go to the [js-e2e-express-server](https://github.com/Azure-Samples/js-e2e-express-server) repository. +1. Select **Fork** in the upper-right corner of the page. +1. Select your GitHub account. By default, the fork is named the same as the parent repository, but you can name it something different. -1. A new run starts. Wait for the run to finish. +>[!IMPORTANT] +>During the following procedures, you might be prompted to create a [GitHub service connection](../library/service-endpoints.md#github-service-connection) or redirected to GitHub to sign in, install Azure Pipelines, or authorize Azure Pipelines. Follow the onscreen instructions to complete the process. For more information, see [Access to GitHub repositories](../repos/github.md#access-to-github-repositories). -When you're done, you have a working YAML file *azure-pipelines.yml* in your repository that's ready for you to customize. +## Create your pipeline -::: moniker-end - -::: moniker range="azure-devops-2019" - -1. [Create a pipeline](../create-first-pipeline.md) and select the **YAML** template. +### [YAML](#tab/yaml) -1. Set the **Agent pool** and **YAML file path** for your pipeline. +1. In your Azure DevOps project, select **Pipelines** > **Create Pipeline**, and then select **GitHub** as the location of your source code. +1. On the **Select a repository** screen, select your forked sample repository. +1. On the **Configure your pipeline** screen, select **Starter pipeline**. Azure Pipelines generates a YAML file called *azure-pipelines.yml* for your pipeline. +1. Select the dropdown caret next to **Save and run**, select **Save**, and then select **Save** again. The file is saved to your forked GitHub repository. +1. On the next screen, select **Edit**. -1. Save the pipeline and queue a build. When the **Build #nnnnnnnn.n has been queued** message appears, select the number link to see your pipeline in action. +## Build the package and publish an artifact -::: moniker-end - -::: moniker range=">=azure-devops-2020" +Edit your *azure-pipelines.yml* file as follows. -## 3 - Build your package and publish an artifact - -1. **Edit** your *azure-pipelines.yml* file. - -1. Update the [Node.js Tool Installer task](/azure/devops/pipelines/tasks/reference/node-tool-v0) to use Node.js version 16 LTS. +1. Replace the contents of the file with the following code. The code updates the [Node.js tool installer task](/azure/devops/pipelines/tasks/reference/node-tool-v0) to use Node.js version 16 LTS. ```yaml trigger: @@ -97,9 +54,9 @@ When you're done, you have a working YAML file *azure-pipelines.yml* in your rep vmImage: 'ubuntu-latest' steps: - - task: NodeTool@0 + - task: UseNode@1 inputs: - versionSpec: '16.x' + version: '16.x' displayName: 'Install Node.js' - script: | @@ -109,9 +66,18 @@ When you're done, you have a working YAML file *azure-pipelines.yml* in your rep - script: | npm run build displayName: 'npm build' + + - script: + npm test + displayname: 'npm test' + ``` -1. Add new tasks to your pipeline to copy your npm package, package.json, and to publish your artifact. The [Copy Files task](/azure/devops/pipelines/tasks/reference/copy-files-v2) copies files from local path on the agent where your source code files are downloaded and saves files to a local path on the agent where any artifacts are copied to before being pushed to their destination. Only the `src` and `public` folders get copies. The [Publish Pipeline Artifact task](../artifacts/pipeline-artifacts.md) downloads the files from the earlier Copy Files tasks and makes them available as pipeline artifacts that will be published with your pipeline build. +1. Add the following new tasks to the pipeline: + + - The [copy files task](/azure/devops/pipelines/tasks/reference/copy-files-v2) copies the files from the *src* and *public* folders to the build artifact staging directory. + + - The [publish pipeline artifact task](../artifacts/pipeline-artifacts.md) gets the files from the artifact staging location and publishes them as artifacts to be output with pipeline builds. ```yaml - task: CopyFiles@2 @@ -131,59 +97,52 @@ When you're done, you have a working YAML file *azure-pipelines.yml* in your rep displayName: 'Publish npm artifact' ``` -## 4 - Run your pipeline +## Run your pipeline -Save and run your pipeline. After your pipeline runs, verify that the job ran successfully and that you see a published artifact. - -:::image type="content" source="media/node-artifact-run.png" alt-text="Screenshot of successful pipeline run with an artifact. "::: +Select **Validate and save**, then select **Save**, select **Run**, and select **Run** again. -::: moniker-end - -::: zone-end +After your pipeline runs, verify that the job ran successfully and that you see a published artifact. +::: moniker range=">=azure-devops-2020" +:::image type="content" source="media/node-artifact-run.png" alt-text="Screenshot of successful pipeline run with an artifact."::: -::: zone pivot="pipelines-classic" +::: moniker-end -1. Fork the following repo at GitHub. +### [Classic](#tab/classic) - ``` - https://github.com/Azure-Samples/js-e2e-express-server - ``` +1. Select **GitHub** as the source for your code. +1. Under **Repository**, select your forked repository, and select **Continue**. +1. Select **Empty pipeline**, and select **Apply**. +1. Under **Agent specification** in the right pane, select **ubuntu-latest**. -2. After you have the sample code in your own repository, [create your first pipeline](../create-first-pipeline.md) and select the **Empty process** template. +1. In the left pane, add the following tasks to the pipeline in order. For each task, select the **+** in **Agent job 1**, select the task at right and select **Add**, and configure the task if necessary. -3. Select **Process** under the **Tasks** tab in the pipeline editor and change the properties as follows: - * **Agent queue:** `Hosted Ubuntu Latest` + 1. **npm** -4. Add the following tasks to the pipeline in the specified order: - * **npm** - * **Command:** `install` + 1. **npm** + - **Display name:** *npm test* + - **Command:** **custom** + - **Command and arguments:** *test* - * **npm** - * **Display name:** `npm test` - * **Command:** `custom` - * **Command and arguments:** `test` + 1. **Publish Test Results** - * **Publish Test Results** - * Leave all the default values for properties + 1. **Archive files** + - **Root folder or file to archive:** *$(System.DefaultWorkingDirectory)* + - **Prepend root folder name to archive paths:** Uncheck - * **Archive Files** - * **Root folder or file to archive:** `$(System.DefaultWorkingDirectory)` - * **Prepend root folder name to archive paths:** Unchecked + 1. **Publish build artifacts** - * **Publish Build Artifacts** - * Leave all the default values for properties +1. Select **Save & queue**, and then select **Save and run**. -5. Save the pipeline and queue a build to see it in action. + :::image type="content" source="media/classic-node.png" alt-text="Screenshot of the classic pipeline. "::: +--- -::: zone-end +Congratulations, you successfully created and ran a pipeline that built and tested a Node.js package. You can build, test, and deploy Node.js apps as part of your Azure Pipelines continuous integration and continuous delivery (CI/CD) system. ## Next steps -Congratulations, you've successfully completed this quickstart! - > [!div class="nextstepaction"] > [Configure JavaScript](customize-javascript.md) diff --git a/docs/pipelines/ecosystems/kubernetes/canary-demo.md b/docs/pipelines/ecosystems/kubernetes/canary-demo.md index a8e085a2f5e..873729439ed 100644 --- a/docs/pipelines/ecosystems/kubernetes/canary-demo.md +++ b/docs/pipelines/ecosystems/kubernetes/canary-demo.md @@ -1,75 +1,60 @@ --- -title: Use a canary deployment strategy for Kubernetes deployments with Azure Pipelines -description: Demo of performing canary deployments on Kubernetes clusters by using Azure Pipelines -ms.topic: quickstart +title: Use a canary deployment strategy for Kubernetes +description: Learn how to perform and evaluate canary deployments on Kubernetes clusters by using Azure Pipelines. +ms.topic: tutorial ms.assetid: 33ffbd7f-746b-4338-8669-0cd6adce6ef4 -ms.date: 01/24/2023 +ms.date: 09/12/2024 ms.custom: fasttrack-edit -monikerRange: 'azure-devops' +monikerRange: '>= azure-devops-2022' --- -# Tutorial: Use a canary deployment strategy for Kubernetes deployments +# Tutorial: Use a canary deployment strategy for Kubernetes -[!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] +[!INCLUDE [version-eq-azure-devops](../../../includes/version-gt-eq-2022.md)] -A *canary* deployment strategy means deploying new versions of an application next to stable, production versions. You can then see how the canary version compares to the baseline, before promoting or rejecting the deployment. +This step-by-step guide covers how to use the [Kubernetes manifest task](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v1) with the `canary` strategy. A *canary* deployment strategy deploys new versions of an application next to stable, production versions. -This step-by-step guide covers how to use the [Kubernetes manifest task's](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v0) canary strategy. Specifically, you'll learn how to set up canary deployments for Kubernetes, and the associated workflow to evaluate code. You then use that code to compare baseline and canary app deployments, so you can decide whether to promote or reject the canary deployment. +You use the associated workflow to deploy the code and compare the baseline and canary app deployments. Based on the evaluation, you decide whether to promote or reject the canary deployment. -If you're using Azure Kubernetes Service, the Azure Resource Manager service connection type is the best way to connect to a private cluster, or a cluster that has local accounts disabled. +This tutorial uses Docker Registry and Azure Resource Manager service connections to connect to Azure resources. For an Azure Kubernetes Service (AKS) private cluster or a cluster that has local accounts disabled, an [Azure Resource Manager service connections](../../library/service-endpoints.md#azure-resource-manager-service-connection) is a better way to connect. -## Prerequisites - -* An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). -* A GitHub account. Create a free [GitHub account](https://github.com/join) if you don't have one already. -* An [Azure Container Registry](/azure/container-registry/container-registry-intro)with push privileges. [Create an Azure Container Registry](/azure/container-registry/container-registry-get-started-portal#create-a-container-registry) if you don't have one already. -* A Kubernetes cluster. [Deploy an Azure Kubernetes Service (AKS) cluster](/azure/aks/tutorial-kubernetes-deploy-cluster). - -## Sample code -Fork the following repository on GitHub. -``` -https://github.com/MicrosoftDocs/azure-pipelines-canary-k8s -``` +## Prerequisites -Here's a brief overview of the files in the repository that are used during this guide: +- An Azure DevOps project with at least **User** permissions. +- An Azure account. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). +- An [Azure Container Registry](/azure/container-registry/container-registry-get-started-portal#create-a-container-registry) instance with push privileges. +- An [Azure Kubernetes Service (AKS) cluster](/azure/aks/tutorial-kubernetes-deploy-cluster) deployed. You can attach the AKS cluster to your Azure Container registry cluster when you deploy the AKS cluster or afterwards. +- A GitHub account. [Create a free GitHub account](https://github.com/join). +- A fork of the [https://github.com/MicrosoftDocs/azure-pipelines-canary-k8s](https://github.com/MicrosoftDocs/azure-pipelines-canary-k8s) GitHub repository. -- *./app*: - - *app.py* - A simple, Flask-based web server that is instrumented by using the [Prometheus instrumentation library for Python applications](https://github.com/prometheus/client_python). A custom counter is set up for the number of good and bad responses given out, based on the value of the `success_rate` variable. - - *Dockerfile* - Used for building the image with each change made to *app.py*. With each change, the build pipeline is triggered and the image gets built and pushed to the container registry. -- *./manifests*: - - *deployment.yml* - Contains the specification of the `sampleapp` deployment workload corresponding to the image published earlier. You use this manifest file not just for the stable version of deployment object, but also for deriving the baseline and canary variants of the workloads. - - *service.yml* - Creates the `sampleapp` service. This service routes requests to the pods spun up by the deployments (stable, baseline, and canary) mentioned previously. -- *./misc* - - *service-monitor.yml* - Used to set up a [ServiceMonitor](https://github.com/coreos/prometheus-operator#customresourcedefinitions) object. This object sets up Prometheus metric scraping. - - *fortio-deploy.yml* - Used to set up a fortio deployment. This deployment is later used as a load-testing tool, to send a stream of requests to the `sampleapp` service deployed earlier. The stream of requests sent to `sampleapp` are routed to pods under all three deployments (stable, baseline, and canary). + >[!IMPORTANT] + >During the following procedures, you might be prompted to create a [GitHub service connection](../../library/service-endpoints.md#github-service-connection) or be redirected to GitHub to sign in, install Azure Pipelines, or authorize Azure Pipelines. Follow the onscreen instructions to complete the process. For more information, see [Access to GitHub repositories](../../repos/github.md#access-to-github-repositories). -> [!NOTE] -> In this guide, you use [Prometheus](https://prometheus.io/) for code instrumentation and monitoring. Any equivalent solution, like [Azure Application Insights](/azure/azure-monitor/learn/nodejs-quick-start), can be used as an alternative. +### GitHub repository files -## Install prometheus-operator +The GitHub repository contains the following files: -To install Prometheus on your cluster, use the following command from your development machine. You must have kubectl and Helm installed, and you must set the context to the cluster you want to deploy against. [Grafana](https://grafana.com), which you use later to visualize the baseline and canary metrics on dashboards, is installed as part of this Helm chart. -``` -helm install --name sampleapp stable/prometheus-operator -``` +|File|Description| +|----|-----------| +|*./app/app.py*|A simple, Flask-based web server . The file sets up a custom counter for the number of good and bad responses, based on the value of the `success_rate` variable.| +|*./app/Dockerfile*|Used for building the image with each change to *app.py*. Each change triggers the build pipeline to build the image and push it to the container registry.| +|*./manifests/deployment.yml*|Contains the specification of the `sampleapp` deployment workload corresponding to the published image. You use this manifest file for the stable version of the deployment object and for deriving the baseline and canary variants of the workloads.| +|*./manifests/service.yml*|Creates the `sampleapp` service. This service routes requests to the pods spun up by the stable, baseline, and canary deployments.| +|*./misc/fortio.yml*|Sets up a fortio deployment. This deployment is a load-testing tool that sends a stream of requests to the deployed `sampleapp` service. The request stream routes to pods under the three deployments: stable, baseline, and canary.| ## Create service connections -1. Go to **Project settings** > **Pipelines** > **Service connections** in the Azure DevOps menu. -1. Create a [Docker registry service connection](../../library/service-endpoints.md#docker-registry-service-connection) associated with your container registry. Name it **azure-pipelines-canary-k8s**. -1. Create a [Kubernetes service connection](../../library/service-endpoints.md#kubernetes-service-connection) for the Kubernetes cluster and namespace you want to deploy to. Name it **azure-pipelines-canary-k8s**. - - -> [!NOTE] -> If you're using Azure Kubernetes Service, the [Azure Resource Manager service connection type](../../library/service-endpoints.md#azure-resource-manager-service-connection) is the best way to connect to a private cluster, or a cluster that has local accounts disabled. +1. In your Azure DevOps project, go to **Project settings** > **Pipelines** > **Service connections**. +1. Create a [Docker Registry service connection](../../library/service-endpoints.md#azure-container-registry) named **azure-pipelines-canary-acr** that's associated with your Azure Container Registry instance. +1. Create a [Azure Resource Manager service connection with workload identity](../../library/service-endpoints.md) named **azure-pipelines-canary-k8s** for your resource group. +## Add the build stage -## Set up continuous integration - -1. Go to **Pipelines** > **Create Pipeline**, and select your repository. +1. In your Azure DevOps project, go to **Pipelines** > **Create Pipeline** or **New pipeline**. +1. Select **GitHub** for your code location, and select your forked **azure-pipelines-canary-k8s** repository. 1. On the **Configure** tab, choose **Starter pipeline**. -1. On the **Review** tab, replace the pipeline YAML with this code. +1. On the **Review** tab, replace the pipeline YAML with the following code. ```YAML trigger: @@ -79,47 +64,67 @@ helm install --name sampleapp stable/prometheus-operator vmImage: ubuntu-latest variables: - imageName: azure-pipelines-canary-k8s + imageName: azure-pipelines-canary-k8s # name of ACR image + dockerRegistryServiceConnection: azure-pipelines-canary-acr # name of ACR service connection + imageRepository: 'azure-pipelines-canary-k8s' # name of image repository + containerRegistry: example.azurecr.io # name of Azure container registry + tag: '$(Build.BuildId)' - steps: - - task: Docker@2 - displayName: Build and push image - inputs: - containerRegistry: azure-pipelines-canary-k8s #replace with name of your Docker registry service connection - repository: $(imageName) - command: buildAndPush - Dockerfile: app/Dockerfile - tags: | - $(Build.BuildId) + stages: + - stage: Build + displayName: Build stage + jobs: + - job: Build + displayName: Build + pool: + vmImage: ubuntu-latest + steps: + - task: Docker@2 + displayName: Build and push image + inputs: + containerRegistry: $(dockerRegistryServiceConnection) + repository: $(imageName) + command: buildAndPush + Dockerfile: app/Dockerfile + tags: | + $(tag) ``` - If the Docker registry service connection that you created is associated with `example.azurecr.io`, then the image is to `example.azurecr.io/azure-pipelines-canary-k8s:$(Build.BuildId)`, based on the preceding configuration. -## Edit manifest file + If the Docker registry service connection that you created is associated with a container registry named `example.azurecr.io`, then the image is set to `example.azurecr.io/azure-pipelines-canary-k8s:$(Build.BuildId)`. -In *manifests/deployment.yml*, replace `` with your container registry's URL. For example, after replacement, the image field should look something like `contosodemo.azurecr.io/azure-pipelines-canary-k8s`. +1. Select **Save and run** and ensure the job runs successfully. + +### Edit the manifest file + +In your repository fork, edit *manifests/deployment.yml* to replace `` with your container registry's URL, for example `example.azurecr.io/azure-pipelines-canary-k8s`. ## Set up continuous deployment -The following sections provide steps for setting up continuous deployment, including how to deploy the canary stage, and how to promote or reject the canary through manual intervention. +Now, set up continuous deployment, deploy the canary stage, and promote or reject the canary through manual approval. -### Deploy canary stage +### Create an environment You can deploy with YAML or Classic. #### [YAML](#tab/yaml/) -1. Go to **Pipelines** > **Environments** > **Create environment**. -1. Create a new environment. - - **Name**: *akscanary* - - **Resource**: Choose Kubernetes. -1. Select **Next**, and configure your Kubernetes resource as follows: - - **Provider**: Azure Kubernetes Service - - **Azure subscription**: Choose the subscription that holds your Kubernetes cluster. - - **Cluster**: Choose your cluster. - - **Namespace**: Create a new namespace, with the name *canarydemo*. -1. Select **Validate and Create**. -1. Go to **Pipelines**. Select the pipeline you created, and select **Edit**. -1. Change the step you created previously to now use a stage. Add two more steps to copy the manifests and *misc* directories as artifacts for use by consecutive stages. You might also want to move a couple of values to variables, for easier usage later in your pipeline. Your complete YAML should now look like this. +1. In your Azure DevOps project, go to **Pipelines** > **Environments** and then select **Create environment** or **New environment**. +1. On the first **New environment** screen, enter *akscanary* under **Name**, select **Kubernetes** under **Resource**, and select **Next**. +1. Fill out the **Kubernetes resource** screen as follows: + - **Provider**: Select **Azure Kubernetes Service**. + - **Azure subscription**: Select your Azure subscription. + - **Cluster**: Select your AKS cluster. + - **Namespace**: Select **New** and enter *canarydemo*. +1. Select **Validate and create**. + +### Add the canary stage + +1. Go to **Pipelines**, select the pipeline you created, and select **Edit**. +1. Replace the entire pipeline YAML with the following code. + + This code changes the `Docker@2` step you ran previously to use a stage, and adds two more steps to copy the manifests and *misc* directories as artifacts for consecutive stages to use. + + The code also moves some values to variables for easier usage later in the pipeline. In the `containerRegistry` variable, replace `` with the name of your container registry. ```YAML trigger: @@ -130,9 +135,9 @@ You can deploy with YAML or Classic. variables: imageName: azure-pipelines-canary-k8s - dockerRegistryServiceConnection: dockerRegistryServiceConnectionName #replace with name of your Docker registry service connection + dockerRegistryServiceConnection: azure-pipelines-canary-acr imageRepository: 'azure-pipelines-canary-k8s' - containerRegistry: example.azurecr.io #replace with the name of your container registry, Should be in the format example.azurecr.io + containerRegistry: .azurecr.io tag: '$(Build.BuildId)' stages: @@ -161,9 +166,47 @@ You can deploy with YAML or Classic. artifact: misc ``` - 1. Add a stage at the end of your YAML file to deploy the canary version. +1. Add another stage at the end of the YAML file to deploy the canary version. Replace the values `my-resource-group` and `my-aks-cluster` with your resource group and Azure Kubernetes Service cluster name. ```YAML + trigger: + - main + + pool: + vmImage: ubuntu-latest + + variables: + imageName: azure-pipelines-canary-k8s + dockerRegistryServiceConnection: azure-pipelines-canary-acr + imageRepository: 'azure-pipelines-canary-k8s' + containerRegistry: yourcontainerregistry.azurecr.io #update with container registry + tag: '$(Build.BuildId)' + + stages: + - stage: Build + displayName: Build stage + jobs: + - job: Build + displayName: Build + pool: + vmImage: ubuntu-latest + steps: + - task: Docker@2 + displayName: Build and push image + inputs: + containerRegistry: $(dockerRegistryServiceConnection) + repository: $(imageName) + command: buildAndPush + Dockerfile: app/Dockerfile + tags: | + $(tag) + + - publish: manifests + artifact: manifests + + - publish: misc + artifact: misc + - stage: DeployCanary displayName: Deploy canary dependsOn: Build @@ -174,38 +217,50 @@ You can deploy with YAML or Classic. displayName: Deploy canary pool: vmImage: ubuntu-latest - environment: 'akscanary.canarydemo' + environment: 'akscanary' strategy: runOnce: deploy: steps: - - task: KubernetesManifest@0 - displayName: Create imagePullSecret + - task: KubernetesManifest@1 + displayName: Create Docker Registry Secret inputs: - action: createSecret - secretName: azure-pipelines-canary-k8s - dockerRegistryEndpoint: azure-pipelines-canary-k8s - - - task: KubernetesManifest@0 + action: 'createSecret' + connectionType: 'azureResourceManager' + azureSubscriptionConnection: 'azure-pipelines-canary-sc' + azureResourceGroup: 'my-resource-group' + kubernetesCluster: 'my-aks-cluster' + secretType: 'dockerRegistry' + secretName: 'my-acr-secret' + dockerRegistryEndpoint: 'azure-pipelines-canary-acr' + + - task: KubernetesManifest@1 displayName: Deploy to Kubernetes cluster inputs: action: 'deploy' + connectionType: 'azureResourceManager' + azureSubscriptionConnection: 'azure-pipelines-canary-sc' + azureResourceGroup: 'my-resource-group' + kubernetesCluster: 'my-aks-cluster' strategy: 'canary' percentage: '25' manifests: | $(Pipeline.Workspace)/manifests/deployment.yml $(Pipeline.Workspace)/manifests/service.yml containers: '$(containerRegistry)/$(imageRepository):$(tag)' - imagePullSecrets: azure-pipelines-canary-k8s + imagePullSecrets: 'my-acr-secret' - - task: KubernetesManifest@0 - displayName: Deploy Forbio and ServiceMonitor + - task: KubernetesManifest@1 + displayName: Deploy Forbio to Kubernetes cluster inputs: action: 'deploy' - manifests: | - $(Pipeline.Workspace)/misc/* + connectionType: 'azureResourceManager' + azureSubscriptionConnection: 'azure-pipelines-canary-sc' + azureResourceGroup: 'my-resource-group' + kubernetesCluster: 'my-aks-cluster' + manifests: '$(Pipeline.Workspace)/misc/*' ``` -1. Save your pipeline by committing directly to the main branch. This commit should already run your pipeline successfully. +1. Select **Validate and save**, and save the pipeline directly to the main branch. #### [Classic](#tab/classic/) @@ -219,7 +274,7 @@ You can deploy with YAML or Classic. - Confirm your inputs by choosing **Add**. 1. Select **Add an artifact**, and choose **Azure container registry** or **Docker Hub**, depending on the container registry you chose earlier, in the "Prerequisites" section. Provide appropriate values for the input dropdown lists to locate your container registry. Provide *image* as the alias for this artifact, and confirm the inputs by choosing **Add**. When the artifact has been added, select the lightning bolt icon on the artifact card to enable the continuous deployment trigger. 1. In the **Deploy Canary** stage that you created, select the **1 job, 0 task** link to go to the window for adding jobs and stages. -1. Select **Agent job**. In the configuration window, in the **Agent pool** dropdown list, choose **Hosted Ubuntu 1604**. +1. Select **Agent job**. In the configuration window, in the **Agent pool** dropdown list, choose **Hosted Ubuntu 22.04**. 1. Select the **+** sign on the agent job row to add a new task. Add the **Deploy Kubernetes manifests** task, with the following configuration: - **Display name**: Create secret - **Action**: Create secret @@ -248,58 +303,66 @@ You can deploy with YAML or Classic. * * * -### Manual intervention for promoting or rejecting canary +### Add manual approval for promoting or rejecting canary deployment -You can intervene manually with YAML or Classic. +You can intervene manually with YAML or Classic. #### [YAML](#tab/yaml/) -1. Go to **Pipelines** > **Environments** > **New environment**. -1. Configure the new environment. - - **Name**: *akspromote* - - **Resource**: Choose Kubernetes. -1. Select **Next**, and configure your Kubernetes resource as follows: - - **Provider**: Azure Kubernetes Service - - **Azure subscription**: Choose the subscription that holds your Kubernetes cluster. - - **Cluster**: Choose your cluster. - - **Namespace**: Choose the namespace, *canarydemo*, that you created earlier. -1. Select **Validate and Create**. -1. Select your new `akspromote` environment from the list of environments. -1. Select **Approvals and checks** > **Approvals**. Then select the ellipsis icon (the three dots). -1. Configure your approval as follows: - - **Approvers**: Add your own user account. - - **Advanced**: Make sure that the **Allow approvers to approve their own runs** box is selected. +1. Create a new Kubernetes environment called *akspromote*. +1. Open the new **akspromote** environment from the list of environments, and select **Approvals** on the **Approvals and checks** tab. +1. On the **Approvals** screen, add your own user account under **Approvers**. +1. Expand **Advanced**, and make sure **Allow approvers to approve their own runs** is selected. 1. Select **Create**. -1. Go to **Pipelines**, and select the pipeline that you created. Then select **Edit**. -1. Add another stage, `PromoteRejectCanary`, at the end of your YAML file, to promote the changes. + +### Add promote and reject stages to the pipeline + +1. Go to **Pipelines**, select the pipeline you created, and select **Edit**. +1. Add the following `PromoteRejectCanary` stage at the end of your YAML file that promotes the changes. ```YAML - stage: PromoteRejectCanary displayName: Promote or Reject canary dependsOn: DeployCanary condition: succeeded() - + jobs: - deployment: PromoteCanary displayName: Promote Canary pool: vmImage: ubuntu-latest - environment: 'akspromote.canarydemo' + environment: 'akspromote' strategy: runOnce: deploy: - steps: - - task: KubernetesManifest@0 + steps: + - task: KubernetesManifest@1 + displayName: Create Docker Registry Secret for akspromote + inputs: + action: 'createSecret' + connectionType: 'azureResourceManager' + azureSubscriptionConnection: 'azure-pipelines-canary-sc' + azureResourceGroup: 'my-resource-group' + kubernetesCluster: 'my-aks-cluster' + secretType: 'dockerRegistry' + secretName: 'my-acr-secret' + dockerRegistryEndpoint: 'azure-pipelines-canary-acr' + + - task: KubernetesManifest@1 displayName: promote canary inputs: action: 'promote' + connectionType: 'azureResourceManager' + azureSubscriptionConnection: 'azure-pipelines-canary-sc' + azureResourceGroup: 'my-resource-group' + kubernetesCluster: 'my-aks-cluster' strategy: 'canary' manifests: '$(Pipeline.Workspace)/manifests/*' containers: '$(containerRegistry)/$(imageRepository):$(tag)' - imagePullSecrets: '$(imagePullSecret)' - ``` + imagePullSecrets: 'my-acr-secret' + ``` -1. Add another stage, `RejectCanary`, at the end of your YAML file, to roll back the changes. +1. Add the following `RejectCanary`stage at the end of the file that rolls back the changes. ```YAML - stage: RejectCanary @@ -312,19 +375,35 @@ You can intervene manually with YAML or Classic. displayName: Reject Canary pool: vmImage: ubuntu-latest - environment: 'akscanary.canarydemo' + environment: 'akscanary' strategy: runOnce: deploy: - steps: - - task: KubernetesManifest@0 - displayName: reject canary + steps: + - task: KubernetesManifest@1 + displayName: Create Docker Registry Secret for reject canary + inputs: + action: 'createSecret' + connectionType: 'azureResourceManager' + azureSubscriptionConnection: 'azure-pipelines-canary-sc' + azureResourceGroup: 'kubernetes-testing' + kubernetesCluster: 'my-aks-cluster' + secretType: 'dockerRegistry' + secretName: 'my-acr-secret' + dockerRegistryEndpoint: 'azure-pipelines-canary-acr' + - task: KubernetesManifest@1 + displayName: Reject canary deployment inputs: action: 'reject' + connectionType: 'azureResourceManager' + azureSubscriptionConnection: 'azure-pipelines-canary-sc' + azureResourceGroup: 'my-resource-group' + kubernetesCluster: 'my-aks-cluster' + namespace: 'default' strategy: 'canary' manifests: '$(Pipeline.Workspace)/manifests/*' - ``` -1. Save your YAML pipeline by selecting **Save**, and then commit it directly to the main branch. + ``` +1. Select **Validate and save**, and save the pipeline directly to the main branch. #### [Classic](#tab/classic/) @@ -333,7 +412,7 @@ You can intervene manually with YAML or Classic. 1. Add a **Manual Intervention** task to this job, and change the display name of the task to *Promote or reject canary*. 1. Configure the currently empty agent job placed after the **Promote/reject input** agentless job. - **Display name**: Promote canary - - **Agent pool**: Hosted Ubuntu 1604 + - **Agent pool**: Hosted Ubuntu 22.04 - **Run this job**: Choose to run only when all previous jobs have succeeded. 1. Add the **Deploy Kubernetes manifests** task, with the following configuration to the **Promote canary** job. - **Display name**: Promote canary @@ -347,7 +426,7 @@ You can intervene manually with YAML or Classic. - **ImagePullSecrets**: *azure-pipelines-canary-k8s* 1. Add another agent job with the following configuration, after the **Promote canary** agent job. - **Display name**: Reject canary - - **Agent pool**: Hosted Ubuntu 1604 + - **Agent pool**: Hosted Ubuntu 22.04 - **Run this job**: Choose to run only when a previous job has failed. 1. Add the **Deploy Kubernetes manifests** task, with the following configuration to the **Reject canary** job. - **Display name**: Reject canary @@ -362,83 +441,46 @@ You can intervene manually with YAML or Classic. ## Deploy a stable version +For the first run of the pipeline, the stable version of the workloads, and their baseline or canary versions, don't exist in the cluster. Deploy a stable version of the `sampleapp` workload as follows. + You can deploy a stable version with YAML or Classic. ### [YAML](#tab/yaml/) -For the first run of the pipeline the stable version of the workloads, and their baseline or canary versions don't exist in the cluster. To deploy the stable version: +1. In *app/app.py*, change `success_rate = 50` to `success_rate = 100`. This change triggers the pipeline, building and pushing the image to the container registry, and also triggers the `DeployCanary` stage. +1. Because you configured an approval on the `akspromote` environment, the release waits before running that stage. On the build run summary page, select **Review** and then select **Approve**. -1. In *app/app.py*, change `success_rate = 5` to `success_rate = 10`. This change triggers the pipeline, leading to a build and push of the image to the container registry. It will also trigger the `DeployCanary` stage. -1. Because you configured an approval on the `akspromote` environment, the release will wait before running that stage. -1. In the summary of the run, select **Review** > **Approve**. This deploys the stable version of the workloads (the `sampleapp` deployment in *manifests/deployment.yml*) to the namespace. +Once approved, the pipeline deploys the stable version of the `sampleapp` workload in *manifests/deployment.yml* to the namespace. ### [Classic](#tab/classic/) -For the first run of the pipeline the stable version of the workloads, and their baseline or canary versions don't exist in the cluster. To deploy the stable version: - -1. In *app/app.py*, change `success_rate = 5` to `success_rate = 10`. This change triggers the pipeline, leading to a build and push of the image to the container registry. The continuous deployment trigger, set up earlier on the image push event, results in triggering the release pipeline. +1. In *app/app.py*, change `success_rate = 50` to `success_rate = 100`. This change triggers the pipeline, leading to a build and push of the image to the container registry. The continuous deployment trigger, set up earlier on the image push event, results in triggering the release pipeline. 1. In the **CanaryK8sDemo** release pipeline, select the **Promote/reject canary** stage of the release, where it's waiting on manual intervention. 1. Select **Resume/Reject**, and then select **Resume** in the subsequent dialog box. This deploys the stable version of the workloads (the `sampleapp` deployment in *manifests/deployment.yml*) to the namespace. * * * -## Initiate canary workflow - -The stable version of the workload `sampleapp` now exists in the cluster. Next, make the following change to the simulation application: - -In *app/app.py*, change `success_rate = 10` to `success_rate = 20`. +## Initiate the canary workflow and reject the approval -This change triggers the build pipeline, resulting in the build and push of the image to the container registry. This process in turn triggers the release pipeline and begins the **Deploy canary** stage. +The stable version of the `sampleapp` workload now exists in the cluster. Next, make the following change to the simulation application. -## Simulate requests -On your development machine, run the following commands, and keep it running to send a constant stream of requests at the `sampleapp` service. `sampleapp` routes the requests to the pods spun by the stable `sampleapp` deployment, and to the pods spun up by the `sampleapp-baseline` and `sampleapp-canary` deployments. The selector specified for `sampleapp` is applicable to all of these pods. +### [YAML](#tab/yaml/) -``` -FORTIO_POD=$(kubectl get pod | grep fortio | awk '{ print $1 }') -kubectl exec -it $FORTIO_POD -c fortio /usr/bin/fortio -- load -allow-initial-errors -t 0 http://sampleapp:8080/ -``` +1. In *app/app.py*, change `success_rate = 50` to `success_rate = 100`. This change triggers the pipeline, building and pushing the image to the container registry, and also triggers the `DeployCanary` stage. +1. Because you configured an approval on the `akspromote` environment, the release waits before running that stage. +1. On the build run summary page, select **Review** and then select **Reject** in the subsequent dialog box. This rejects deployment. -## Set up Grafana dashboard +Once rejected, the pipeline prevents the code deployment. -1. Run the following port-forwarding command on your local development machine to be able to access Grafana. - ``` - kubectl port-forward svc/sampleapp-grafana 3000:80 - ``` -1. In a browser, open the following URL. - ``` - http://localhost:3000/login - ``` -1. When you're prompted for credentials, unless the `adminPassword` value was overridden during the `prometheus-operator` Helm chart installation, you can use the following values: - - username: admin - - password: prom-operator -1. From the menu on the left, choose **+** > **Dashboard** > **Graph**. -1. Select anywhere on the newly added panel, and type `e` to edit the panel. -1. On the **Metrics** tab, enter the following query: - ``` - rate(requests_total{pod=~"sampleapp-.*", custom_status="good"}[1m]) - ``` -1. On the **General** tab, change the name of this panel to **All sampleapp pods**. -1. In the overview bar at the top of the page, change the duration range to **Last 5 minutes** or **Last 15 minutes**. -1. To save this panel, select the save icon in the overview bar. -1. The preceding panel visualizes success rate metrics from all the variants. These include stable (from the `sampleapp` deployment), baseline (from the `sampleapp-baseline` deployment), and canary (from the `sampleapp-canary` deployment). You can visualize just the baseline and canary metrics by adding another panel, with the following configuration: - - On the **General** tab, for **Title**, select **sampleapp baseline and canary**. - - On the **Metrics** tab, use the following query: - ``` - rate(requests_total{pod=~"sampleapp-baseline-.*|sampleapp-canary-.*", custom_status="good"}[1m]) - ``` - - > [!NOTE] - > The panel for baseline and canary metrics will only have metrics available for comparison under certain conditions. These conditions are when the **Deploy canary** stage has successfully completed, and the **Promote/reject canary** stage is waiting on manual intervention. - - > [!TIP] - > Set up [annotations for Grafana dashboards](../../../service-hooks/services/grafana.md) to visually depict stage completion events for **Deploy canary** and **Promote/reject canary**. This is helpful so that you know when to start comparing the baseline with the canary, and when the promotion or rejection of the canary has completed, respectively. +### [Classic](#tab/classic/) -## Compare baseline and canary +1. In *app/app.py*, change `success_rate = 50` to `success_rate = 100`. This change triggers the pipeline, leading to a build and push of the image to the container registry. The continuous deployment trigger, set up earlier on the image push event, results in triggering the release pipeline. +1. In the **CanaryK8sDemo** release pipeline, select the **Promote/reject canary** stage of the release, where it's waiting on manual intervention. +1. Select **Resume/Reject**, and then select **Reject** in the subsequent dialog box. This rejects deployment. -1. At this point, the **Deploy canary** stage has successfully completed (based on the change of `success_rate` from `10` to `20`). The **Promote/reject canary** stage is waiting on manual intervention. You can now compare the success rate (as determined by `custom_status=good`) of the baseline and canary variants in the Grafana dashboard. It should look similar to the following: +* * * - > [!div class="mx-imgBorder"] - > ![Screenshot that shows a comparison of baseline and canary metrics.](../media/k8s-baseline-canary.png) +## Clean up -1. Based on the observation that the success rate is higher for canary, promote the canary. Select **Resume** in the manual intervention task. + If you're not going to continue to use this application, delete the resource group in Azure portal and the project in Azure DevOps. diff --git a/docs/pipelines/ecosystems/kubernetes/deploy.md b/docs/pipelines/ecosystems/kubernetes/deploy.md index b3285733540..4357e568d11 100644 --- a/docs/pipelines/ecosystems/kubernetes/deploy.md +++ b/docs/pipelines/ecosystems/kubernetes/deploy.md @@ -4,13 +4,13 @@ description: Use Azure Pipelines to deploy to Kubernetes clusters ms.topic: how-to ms.assetid: 710a03c9-d8ba-4013-bf8f-e672efc7abe4 ms.date: 05/11/2023 -monikerRange: 'azure-devops' +monikerRange: '>= azure-devops-2022' ms.custom: engagement-fy23 --- # Deploy to Kubernetes -[!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] +[!INCLUDE [version-eq-azure-devops](../../../includes/version-gt-eq-2022.md)] You can use Azure Pipelines to deploy to [Azure Kubernetes Service](/azure/aks/) and Kubernetes clusters offered by other cloud providers. Azure Pipelines has two tasks for working with Kubernetes: @@ -91,7 +91,7 @@ For more information on canary deployments with pipelines, see [Use a canary dep Kubernetes runs the same way on all cloud providers. Azure Pipelines can be used for deploying to Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (EKS), or clusters from any other cloud providers. -To set up multicloud deployment, [create an environment](../../process/environments.md#creation) and then add your Kubernetes resources associated with namespaces of Kubernetes clusters. +To set up multicloud deployment, [create an environment](../../process/environments.md#create-an-environment) and then add your Kubernetes resources associated with namespaces of Kubernetes clusters. * [Azure Kubernetes Service](../../process/environments-kubernetes.md#use-azure-kubernetes-service) * [Generic provider using existing service account](../../process/environments-kubernetes.md#use-an-existing-service-account) diff --git a/docs/pipelines/ecosystems/media/acr-image.png b/docs/pipelines/ecosystems/media/acr-image.png index cd1c8a653c9..2a0182f3bf9 100644 Binary files a/docs/pipelines/ecosystems/media/acr-image.png and b/docs/pipelines/ecosystems/media/acr-image.png differ diff --git a/docs/pipelines/ecosystems/media/acr-service-connection-msi.png b/docs/pipelines/ecosystems/media/acr-service-connection-msi.png index a36979959c5..8482dbe8f9c 100644 Binary files a/docs/pipelines/ecosystems/media/acr-service-connection-msi.png and b/docs/pipelines/ecosystems/media/acr-service-connection-msi.png differ diff --git a/docs/pipelines/ecosystems/media/acr-service-connection.png b/docs/pipelines/ecosystems/media/acr-service-connection.png index d21a5d7e0de..0482c3cfea6 100644 Binary files a/docs/pipelines/ecosystems/media/acr-service-connection.png and b/docs/pipelines/ecosystems/media/acr-service-connection.png differ diff --git a/docs/pipelines/ecosystems/media/classic-docker-pipeline-dialog.png b/docs/pipelines/ecosystems/media/classic-docker-pipeline-dialog.png new file mode 100644 index 00000000000..81dd1fe3c3d Binary files /dev/null and b/docs/pipelines/ecosystems/media/classic-docker-pipeline-dialog.png differ diff --git a/docs/pipelines/ecosystems/media/classic-node.png b/docs/pipelines/ecosystems/media/classic-node.png new file mode 100644 index 00000000000..b1c750f52b3 Binary files /dev/null and b/docs/pipelines/ecosystems/media/classic-node.png differ diff --git a/docs/pipelines/ecosystems/media/classic-pipeline-add-task.png b/docs/pipelines/ecosystems/media/classic-pipeline-add-task.png new file mode 100644 index 00000000000..effa4808ce2 Binary files /dev/null and b/docs/pipelines/ecosystems/media/classic-pipeline-add-task.png differ diff --git a/docs/pipelines/ecosystems/media/classic-pipeline-docker-2-build-and-push-task.png b/docs/pipelines/ecosystems/media/classic-pipeline-docker-2-build-and-push-task.png new file mode 100644 index 00000000000..146e4a45773 Binary files /dev/null and b/docs/pipelines/ecosystems/media/classic-pipeline-docker-2-build-and-push-task.png differ diff --git a/docs/pipelines/ecosystems/media/classic-pipeline-new-azure-container-registry-service-connection-dialog.png b/docs/pipelines/ecosystems/media/classic-pipeline-new-azure-container-registry-service-connection-dialog.png new file mode 100644 index 00000000000..30c5afc442b Binary files /dev/null and b/docs/pipelines/ecosystems/media/classic-pipeline-new-azure-container-registry-service-connection-dialog.png differ diff --git a/docs/pipelines/ecosystems/media/classic-pipeline-new-service-connection-selection.png b/docs/pipelines/ecosystems/media/classic-pipeline-new-service-connection-selection.png new file mode 100644 index 00000000000..eb12d041422 Binary files /dev/null and b/docs/pipelines/ecosystems/media/classic-pipeline-new-service-connection-selection.png differ diff --git a/docs/pipelines/ecosystems/media/classic-pipelines-docker-registry.png b/docs/pipelines/ecosystems/media/classic-pipelines-docker-registry.png new file mode 100644 index 00000000000..bb86d9d38a1 Binary files /dev/null and b/docs/pipelines/ecosystems/media/classic-pipelines-docker-registry.png differ diff --git a/docs/pipelines/ecosystems/media/docker-container-registry.png b/docs/pipelines/ecosystems/media/docker-container-registry.png index 3510c87318e..b2dd9eb769e 100644 Binary files a/docs/pipelines/ecosystems/media/docker-container-registry.png and b/docs/pipelines/ecosystems/media/docker-container-registry.png differ diff --git a/docs/pipelines/ecosystems/media/docker-hub-service-connection-dialog.png b/docs/pipelines/ecosystems/media/docker-hub-service-connection-dialog.png new file mode 100644 index 00000000000..716e58f50d2 Binary files /dev/null and b/docs/pipelines/ecosystems/media/docker-hub-service-connection-dialog.png differ diff --git a/docs/pipelines/ecosystems/media/docker-registry-selection.png b/docs/pipelines/ecosystems/media/docker-registry-selection.png new file mode 100644 index 00000000000..9608b5b354c Binary files /dev/null and b/docs/pipelines/ecosystems/media/docker-registry-selection.png differ diff --git a/docs/pipelines/ecosystems/media/docker-task.png b/docs/pipelines/ecosystems/media/docker-task.png index 89544e30df9..87dd4c93970 100644 Binary files a/docs/pipelines/ecosystems/media/docker-task.png and b/docs/pipelines/ecosystems/media/docker-task.png differ diff --git a/docs/pipelines/ecosystems/media/docker-wif-connection.png b/docs/pipelines/ecosystems/media/docker-wif-connection.png new file mode 100644 index 00000000000..2e46c008123 Binary files /dev/null and b/docs/pipelines/ecosystems/media/docker-wif-connection.png differ diff --git a/docs/pipelines/ecosystems/media/jobs-build.png b/docs/pipelines/ecosystems/media/jobs-build.png index 725e4296302..6ee1925455f 100644 Binary files a/docs/pipelines/ecosystems/media/jobs-build.png and b/docs/pipelines/ecosystems/media/jobs-build.png differ diff --git a/docs/pipelines/ecosystems/media/new-pipeline.png b/docs/pipelines/ecosystems/media/new-pipeline.png index 8ef17d56794..0de8cfc12af 100644 Binary files a/docs/pipelines/ecosystems/media/new-pipeline.png and b/docs/pipelines/ecosystems/media/new-pipeline.png differ diff --git a/docs/pipelines/ecosystems/media/node-artifact-run.png b/docs/pipelines/ecosystems/media/node-artifact-run.png index ca1491a40f6..0b6cf40c176 100644 Binary files a/docs/pipelines/ecosystems/media/node-artifact-run.png and b/docs/pipelines/ecosystems/media/node-artifact-run.png differ diff --git a/docs/pipelines/ecosystems/media/nodejs-tutorial/create-fork.png b/docs/pipelines/ecosystems/media/nodejs-tutorial/create-fork.png new file mode 100644 index 00000000000..2ba495d9b78 Binary files /dev/null and b/docs/pipelines/ecosystems/media/nodejs-tutorial/create-fork.png differ diff --git a/docs/pipelines/ecosystems/media/nodejs-tutorial/deploy-url.png b/docs/pipelines/ecosystems/media/nodejs-tutorial/deploy-url.png new file mode 100644 index 00000000000..128e914e878 Binary files /dev/null and b/docs/pipelines/ecosystems/media/nodejs-tutorial/deploy-url.png differ diff --git a/docs/pipelines/ecosystems/media/nodejs-tutorial/hello-world-site.png b/docs/pipelines/ecosystems/media/nodejs-tutorial/hello-world-site.png new file mode 100644 index 00000000000..8b59122ebdb Binary files /dev/null and b/docs/pipelines/ecosystems/media/nodejs-tutorial/hello-world-site.png differ diff --git a/docs/pipelines/ecosystems/media/nodejs-tutorial/select-fork.png b/docs/pipelines/ecosystems/media/nodejs-tutorial/select-fork.png new file mode 100644 index 00000000000..a321a1cca6b Binary files /dev/null and b/docs/pipelines/ecosystems/media/nodejs-tutorial/select-fork.png differ diff --git a/docs/pipelines/ecosystems/media/pipeline-artifacts-list-single-file.png b/docs/pipelines/ecosystems/media/pipeline-artifacts-list-single-file.png new file mode 100644 index 00000000000..1f9bb164d5a Binary files /dev/null and b/docs/pipelines/ecosystems/media/pipeline-artifacts-list-single-file.png differ diff --git a/docs/pipelines/ecosystems/media/pipeline-artifacts-list.png b/docs/pipelines/ecosystems/media/pipeline-artifacts-list.png new file mode 100644 index 00000000000..7e0fd9a9e16 Binary files /dev/null and b/docs/pipelines/ecosystems/media/pipeline-artifacts-list.png differ diff --git a/docs/pipelines/ecosystems/media/pipeline-summary-page-single-job.png b/docs/pipelines/ecosystems/media/pipeline-summary-page-single-job.png new file mode 100644 index 00000000000..88ea269e37e Binary files /dev/null and b/docs/pipelines/ecosystems/media/pipeline-summary-page-single-job.png differ diff --git a/docs/pipelines/ecosystems/media/pipeline-test-results.png b/docs/pipelines/ecosystems/media/pipeline-test-results.png new file mode 100644 index 00000000000..f5607ffd1a5 Binary files /dev/null and b/docs/pipelines/ecosystems/media/pipeline-test-results.png differ diff --git a/docs/pipelines/ecosystems/media/project-settings-selection.png b/docs/pipelines/ecosystems/media/project-settings-selection.png new file mode 100644 index 00000000000..b47436b9ee3 Binary files /dev/null and b/docs/pipelines/ecosystems/media/project-settings-selection.png differ diff --git a/docs/pipelines/ecosystems/media/published-artifacts-link.png b/docs/pipelines/ecosystems/media/published-artifacts-link.png new file mode 100644 index 00000000000..76f3795e185 Binary files /dev/null and b/docs/pipelines/ecosystems/media/published-artifacts-link.png differ diff --git a/docs/pipelines/ecosystems/media/python-successful-jobs.png b/docs/pipelines/ecosystems/media/python-successful-jobs.png index f18eb39ef4d..6d6d48651bd 100644 Binary files a/docs/pipelines/ecosystems/media/python-successful-jobs.png and b/docs/pipelines/ecosystems/media/python-successful-jobs.png differ diff --git a/docs/pipelines/ecosystems/media/review-your-pipeline.png b/docs/pipelines/ecosystems/media/review-your-pipeline.png index 68ca78c97ea..932745aa75b 100644 Binary files a/docs/pipelines/ecosystems/media/review-your-pipeline.png and b/docs/pipelines/ecosystems/media/review-your-pipeline.png differ diff --git a/docs/pipelines/ecosystems/media/save-and-run-button-new-yaml-pipeline-android.png b/docs/pipelines/ecosystems/media/save-and-run-button-new-yaml-pipeline-android.png new file mode 100644 index 00000000000..53e7fcf3e35 Binary files /dev/null and b/docs/pipelines/ecosystems/media/save-and-run-button-new-yaml-pipeline-android.png differ diff --git a/docs/pipelines/ecosystems/media/save-and-run-button-new-yaml-pipeline.png b/docs/pipelines/ecosystems/media/save-and-run-button-new-yaml-pipeline.png index d43f87eaf75..e1cf35a0b5f 100644 Binary files a/docs/pipelines/ecosystems/media/save-and-run-button-new-yaml-pipeline.png and b/docs/pipelines/ecosystems/media/save-and-run-button-new-yaml-pipeline.png differ diff --git a/docs/pipelines/ecosystems/media/server-2019-build-job-summary.png b/docs/pipelines/ecosystems/media/server-2019-build-job-summary.png new file mode 100644 index 00000000000..9cc80d2797d Binary files /dev/null and b/docs/pipelines/ecosystems/media/server-2019-build-job-summary.png differ diff --git a/docs/pipelines/ecosystems/media/server-2019-build-link.png b/docs/pipelines/ecosystems/media/server-2019-build-link.png new file mode 100644 index 00000000000..a78c64ee368 Binary files /dev/null and b/docs/pipelines/ecosystems/media/server-2019-build-link.png differ diff --git a/docs/pipelines/ecosystems/media/server-2019-test-results.png b/docs/pipelines/ecosystems/media/server-2019-test-results.png new file mode 100644 index 00000000000..3157a4b0ff1 Binary files /dev/null and b/docs/pipelines/ecosystems/media/server-2019-test-results.png differ diff --git a/docs/pipelines/ecosystems/media/service-connection-selection.png b/docs/pipelines/ecosystems/media/service-connection-selection.png new file mode 100644 index 00000000000..4dbf807f941 Binary files /dev/null and b/docs/pipelines/ecosystems/media/service-connection-selection.png differ diff --git a/docs/pipelines/ecosystems/media/system-assigned-id.png b/docs/pipelines/ecosystems/media/system-assigned-id.png index ab317439876..5292609ea00 100644 Binary files a/docs/pipelines/ecosystems/media/system-assigned-id.png and b/docs/pipelines/ecosystems/media/system-assigned-id.png differ diff --git a/docs/pipelines/ecosystems/media/vm-creation.png b/docs/pipelines/ecosystems/media/vm-creation.png index 302b9f2825f..7adc54b4c7d 100644 Binary files a/docs/pipelines/ecosystems/media/vm-creation.png and b/docs/pipelines/ecosystems/media/vm-creation.png differ diff --git a/docs/pipelines/ecosystems/nodejs-tutorial.md b/docs/pipelines/ecosystems/nodejs-tutorial.md new file mode 100644 index 00000000000..6a7f776b027 --- /dev/null +++ b/docs/pipelines/ecosystems/nodejs-tutorial.md @@ -0,0 +1,217 @@ +--- +title: 'Tutorial: Automate Node.js deployments with Azure Pipelines' +description: Tutorial that shows how to create an Azure Pipeline that builds and deploys a basic Node.js application to Azure App Service. +ms.topic: tutorial +ms.custom: devx-track-js +ms.date: 07/12/2023 +monikerRange: "<=azure-devops" +--- + +# Tutorial: Automate Node.js deployments with Azure Pipelines + +In this tutorial, you'll learn how Azure and Azure DevOps support Node.js applications by building an Azure DevOps pipeline that deploys a Node.js app to Azure App Service. With Azure Pipelines, you'll be able to deploy your Node.js app automatically and reduce the risk of errors and downtime with continuous integration and continuous delivery. + +In this tutorial, you learn how to: + +> [!div class="checklist"] +> * [Fork a sample application in GitHub](#fork-the-sample-application) +> * [Create Azure App Service resources](#create-azure-app-service-resources) +> * [Select the Azure Pipelines Node.js Express Web App to Linux on Azure Azure DevOps template](#create-the-pipeline-from-a-template) +> * [Deploy a basic Node.js application to Azure App Service](#deploy-the-nodejs-app-to-azure-app-service) + + +## Prerequisites + +[!INCLUDE [ecosystems-prerequisites](includes/ecosystems-prerequisites.md)] + +## Fork the sample application + +To fork the sample application, you'll need to sign in to GitHub, go to the sample repository, and create a fork. + +1. Go to [GitHub](https://github.com), and sign in. + +1. Navigate to the [Node.js sample](https://github.com/Azure-Samples/nodejs-docs-hello-world) project. + +1. Select **Fork**. + + :::image type="content" source="media/nodejs-tutorial/select-fork.png" alt-text="Screenshot of GitHub to select the Node.js project to fork. "::: + +1. Select **Create fork** to create a fork in your repository. + + :::image type="content" source="media/nodejs-tutorial/create-fork.png" alt-text="Screenshot of create fork in GitHub. "::: + +1. Verify that you now have a version of the repository in your GitHub account by checking the URL path in a browser. Your URL should be `https://github.com/{GitHub User}/nodejs-docs-hello-world`. + + +## Create Azure App Service resources + +Use the Azure CLI to add the resources needed to deploy and run an App Service instance. You'll access Azure CLI from Azure Cloud Shell. + +1. Go to the [Azure portal](https://portal.azure.com?azure-portal=true) and sign in. + +1. From the menu, select **Cloud Shell**. When prompted, select the **Bash** experience. + + :::image type="content" source="../apps/cd/azure/media/azure-portal-menu-cloud-shell.png" alt-text="A screenshot of the Azure portal showing the Cloud Shell menu item. "::: + + > [!NOTE] + > Cloud Shell requires an Azure storage resource to persist any files that you create in Cloud Shell. When you first open Cloud Shell, you're prompted to create a resource group, storage account, and Azure Files share. This setup is automatically used for all future Cloud Shell sessions. + +1. From Cloud Shell, run the following [az account list-locations](/cli/azure/account#az-account-list-locations) command to list the regions that are available from your Azure subscription. + + ```azurecli + az account list-locations \ + --query "[].{Name: name, DisplayName: displayName}" \ + --output table + ``` +1. From the `Name` column in the output, choose a region that's close to you. For example, choose `eastasia` or `westus2`. + +1. Run [az configure](/cli/azure/reference-index#az-configure) to set your default region. Replace `` with the name of the region you chose. This example sets `westus2` as the default region: + + ```azurecli + az configure --defaults location=westus2 + ``` + +1. Generate a random number to make your resource names unique. The advantage of having a unique value is that your App Service instance won't have a name conflict with other learners completing this tutorial. + + + ```bash + resourceSuffix=$RANDOM + ``` + +1. Create globally unique names for your App Service Web App, resource group, and App Service plan. + + ```bash + webName="helloworld-nodejs-${resourceSuffix}" + rgName='hello-world-nodejs-rg' + planName='helloworld-nodejs-plan' + ``` + +1. Run the following [az group create](/cli/azure/group#az-group-create) command to create a resource group using the name defined earlier. + + ```azurecli + az group create --name $rgName + ``` + +1. Run the following [az appservice plan create](/cli/azure/appservice/plan#az-appservice-plan-create) command to create an App Service plan using the name defined earlier. + + ```azurecli + az appservice plan create \ + --name $planName \ + --resource-group $rgName \ + --sku B1 \ + --is-linux + ``` + + The `--sku` argument specifies the B1 plan. This plan runs on the Basic tier. The `--is-linux` argument specifies to use Linux workers. + + > [!IMPORTANT] + > If the B1 SKU isn't available in your Azure subscription, [choose a different plan](https://azure.microsoft.com/pricing/details/app-service/linux/?azure-portal=true), such as S1 (Standard). + +1. Run the following [az webapp create](/cli/azure/webapp#az-webapp-create) command to create the App Service instance. + + ```azurecli + az webapp create \ + --name $webName \ + --resource-group $rgName \ + --plan $planName \ + --runtime "node|16-lts" + ``` + +1. Run the following [az webapp list](/cli/azure/webapp#az-webapp-list) command to list the host name and state of the App Service instance. + + ```azurecli + az webapp list \ + --resource-group $rgName \ + --query "[].{hostName: defaultHostName, state: state}" \ + --output table + ``` + +## Create the pipeline from a template + +This process generates a pipelines configuration file named *azure-pipelines.yml*, which lives in the root directory of your Git repository. + + +1. Sign into your account at [dev.azure.com](https://dev.azure.com?azure-portal=true). + +1. Select **+ New project**. + + The **Create new project** dialog box opens. + +1. Create a new project with the following options. + + | Field | Description | + |:-----------------------------------|:-------------| + | **Project name** | Enter a name such as *nodejs-hello-world*. | + | **Visibility** | Choose whether to make your project public or private. | + | **Advanced** > **Version control** | Select **Git**. | + + +1. Go to your ***nodejs-hello-world*** project. + +1. Go to **Pipelines**, and then select **Create pipeline**. + +1. Complete the steps of the wizard by first selecting **GitHub** as the location of your source code. + +1. You might be redirected to GitHub to sign in. If so, enter your GitHub credentials. + +1. When you see the list of repositories, select your repository. + +1. You might be redirected to GitHub to install the Azure Pipelines app. If so, select **Approve & install**. + +1. On the **Select** tab, select your ***nodejs-docs-hello-world*** repository. + +1. On the **Configure** tab, select **Node.js Express Web App to Linux on Azure**. + + When prompted: + + 1. Select the Azure subscription from which you created the resources earlier. + 1. Select **Continue**. + 1. Select the app name you created earlier, for example **helloworld-nodejs-16353**. + 1. Select **Validate and configure**. + +1. On the **Review** tab, review the code for your pipeline configuration. + +1. Select **Save** to save your changes. + + +## Deploy the Node.js app to Azure App Service + +Once you run your pipeline, the code deploys to Azure App Service. The pipeline is configured to run whenever a change is committed to the `main` branch. + +1. Make a small, insignificant change to your pipeline YAML such as adding a space. Select **Save and run** again to commit git changes and trigger the pipeline to run. + +1. In Azure DevOps, go to **Pipelines** > **Pipelines** and select your pipeline. + +1. Watch your pipeline run and trace its build. + +1. After the build succeeds, select the deploy task, and select the URL to view the deployed website. + + :::image type="content" source="media/nodejs-tutorial/deploy-url.png" alt-text="Screenshot of the web site URL location in Azure Pipelines."::: + +1. Go to the deployed website URL and verify that you see the site running on App Service. + + :::image type="content" source="media/nodejs-tutorial/hello-world-site.png" alt-text="Screenshot of the Node.js application running in a web browser."::: + + +## Clean up resources + +If you're not going to continue to use this application, delete the resource group in Azure portal and the project in Azure DevOps with the following steps: + +To clean up your resource group: + +1. Go to the [Azure portal](https://portal.azure.com?azure-portal=true) and sign in. +1. From the menu bar, select Cloud Shell. When prompted, select the **Bash** experience. + + :::image type="content" source="../apps/cd/azure/media/azure-portal-menu-cloud-shell.png" alt-text="A screenshot of the Azure portal showing selecting the Cloud Shell menu item. "::: + +1. Run the following [az group delete](/cli/azure/group#az-group-delete) command to delete the resource group that you used, `hello-world-nodejs-rg`. + + ```azurecli + az group delete --name hello-world-nodejs-rg + ``` +To delete your Azure DevOps project, including the build pipeline, see [Delete project](../../organizations/projects/delete-project.md). + +## Related content + +- [Customize JavaScript](customize-javascript.md) +- [Deploy to App Service using Azure Pipelines](/azure/app-service/deploy-azure-pipelines) diff --git a/docs/pipelines/ecosystems/php.md b/docs/pipelines/ecosystems/php.md index 06df921307c..83f0f225fd2 100644 --- a/docs/pipelines/ecosystems/php.md +++ b/docs/pipelines/ecosystems/php.md @@ -4,9 +4,9 @@ description: Build and test PHP apps with Azure Pipelines. ms.topic: conceptual ms.assetid: f8510914-9716-4a76-92be-333133fbd97b ms.author: jukullam -ms.custom: seodec18, freshness-fy22q2 -ms.date: 06/13/2022 -monikerRange: azure-devops +ms.custom: freshness-fy22q2 +ms.date: 05/20/2024 +monikerRange: "<=azure-devops" --- # Build and test PHP apps @@ -18,10 +18,12 @@ Use Azure Pipelines continuous integration and continuous delivery (CI/CD) to bu Learn how to create a PHP pipeline, deploy a pipeline with a sample project to Azure App Service, and how to configure your environment. To learn more about Azure App Service, see [Create a PHP web app in Azure App Service](/azure/app-service/quickstart-php). + ## Prerequisites -[!INCLUDE [include](../includes/prerequisites.md)] -[!INCLUDE [include](../includes/azure-prerequisites.md)] +[!INCLUDE [ecosystems-prerequisites](includes/ecosystems-prerequisites.md)] + +If you're going to deploy to Azure App Service, you need to have a webapp created. ## Get the code @@ -30,13 +32,15 @@ If you already have an app at GitHub that you want to deploy, you can create a p ``` https://github.com/Azure-Samples/basic-php-composer ``` - ## Create a pipeline 1. Sign in to your Azure DevOps organization and go to your project. +1. Go to pipelines, and then select **New pipeline**. +1. Select your source location (GitHub, Azure Repos Git, Bitbucket Cloud, or other Git repositories). +1. Select the repository where your code is located. 1. Select **PHP** in the **Configure** tab. - +1. Ensure the PHP version is 8.3. 1. Examine your new pipeline. When you're ready, select **Save and run**. > [!div class="mx-imgBorder"] @@ -58,7 +62,7 @@ Use a pipeline to build a PHP web app and deploy to Azure App Service. Azure App You can use tasks to archive your files, publish a build artifact, and then use the [Azure Web App task](/azure/devops/pipelines/tasks/reference/azure-web-app-v1) to deploy to Azure App Service. -This pipelines has two stages: Build and Deploy. In the Build stage, PHP 7.4 gets installed with composer. The app files are archived and uploaded into a package named `drop`. During the Deploy phase, the `drop` package gets deployed to Azure App Service as a web app. +This pipeline has two stages: Build and Deploy. In the Build stage, PHP 8.3 is installed with composer. The app files are archived and uploaded into a package named `drop`. During the Deploy phase, the `drop` package gets deployed to Azure App Service as a web app. ```yaml @@ -71,7 +75,7 @@ variables: # Web app name webAppName: 'web-app-name' # Agent VM image name - vmImageName: 'ubuntu-latest' + vmImageName: 'ubuntu-20.04' # Environment name environmentName: 'environment-name' # Root folder under which your composer.json file is available. @@ -81,7 +85,7 @@ stages: - stage: Build displayName: Build stage variables: - phpVersion: '7.4' + phpVersion: '8.3' jobs: - job: BuildJob pool: @@ -149,10 +153,10 @@ To use a PHP version other than the default, the symlink can be pointed to that ```yaml pool: - vmImage: 'ubuntu-latest' + vmImage: 'ubuntu-20.04' variables: - phpVersion: 7.2 + phpVersion: 8.2 steps: - script: | @@ -204,5 +208,4 @@ If your composer.json is in a subfolder instead of the root directory, you can u You can also specify the absolute path, using the built-in system variables: -```composer install --no-interaction --working-dir='$(system.defaultWorkingDirectory)/pkgs'``` - +```composer install --no-interaction --working-dir='$(system.defaultWorkingDirectory)/pkgs'``` \ No newline at end of file diff --git a/docs/pipelines/ecosystems/python-webapp.md b/docs/pipelines/ecosystems/python-webapp.md index c3dec059ab9..f292fa8e296 100644 --- a/docs/pipelines/ecosystems/python-webapp.md +++ b/docs/pipelines/ecosystems/python-webapp.md @@ -1,260 +1,574 @@ --- -title: Build and deploy Python web apps +title: Build and deploy Python web apps with Azure Pipelines description: Use CI/CD with Azure Pipelines to automatically build, test, and deploy Python web apps to Azure App Service on Linux. -ms.topic: tutorial +ms.topic: how-to ms.assetid: 6f79a177-702f-4fb4-b714-bfdd0ecf1d84 ms.author: jukullam -author: juliakm -ms.date: 01/19/2023 -monikerRange: 'azure-devops' -ms.custom: devx-track-python, devx-track-azurecli, freshness-fy22q2 +ms.date: 04/01/2024 +monikerRange: "<=azure-devops" +ms.custom: devx-track-python, freshness-fy22q2, arm2024, linux-related-content --- -# Use CI/CD to deploy a Python web app to Azure App Service on Linux +# Use Azure Pipelines to build and deploy a Python web app to Azure App Service [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Use Azure Pipelines continuous integration and continuous delivery (CI/CD) to deploy a Python web app to Azure App Service on Linux. Your pipeline automatically builds the code and deploys it to the App Service whenever there's a commit to the repository. You can add other functionalities in your pipeline, such as test scripts, security checks, multistages deployment, and so on. +Use Azure Pipelines for continuous integration and continuous delivery (CI/CD) to build and deploy a Python web app to Azure App Service on Linux. Your pipeline automatically builds and deploys your Python web app to App Service whenever there's a commit to the repository. + +In this article, you learn how to: + +> [!div class="checklist"] +> * Create a web app in Azure App Service. +> * Create a project in Azure DevOps. +> * Connect your DevOps project to Azure. +> * Create a Python-specific pipeline. +> * Run the pipeline to build and deploy your app to your web app in App Service. + +## Prerequisites + +[!INCLUDE [ecosystems-prerequisites](includes/ecosystems-prerequisites.md)] ## Create a repository for your app code -If you already have a Python web app to use, make sure it's committed to a GitHub repository. +Fork the sample repository at [https://github.com/Microsoft/python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial) to your GitHub account. -> [!NOTE] -> If your app uses Django and a SQLite database, it won't work for this tutorial. For more information, see [considerations for Django](#considerations-for-django) later in this article. If your Django app uses a separate database, you can use it with this tutorial. +On your local host, clone your GitHub repository. Use the following command, replacing `` with the URL of your forked repository. -If you need an app to work with, you can fork and clone the repository at [https://github.com/Microsoft/python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial). The code is from the tutorial [Flask in Visual Studio Code](https://code.visualstudio.com/docs/python/tutorial-flask). + ```git + git clone + ``` -To test the example app locally, from the folder containing the code, run the following appropriate commands for your operating system: +### Test your app locally +Build and run the app locally to make sure it works. -```bash -# Linux -sudo apt-get install python3-venv # If needed -python3 -m venv .env -source .env/bin/activate -python3 -m pip install --upgrade pip -python3 -m pip install -r ./requirements.txt -export set FLASK_APP=hello_app.webapp -python3 -m flask run -``` +1. Change to the cloned repository folder. -```powershell -# Windows -py -3 -m venv .env -.env\scripts\activate -pip install --target="./.python_packages/lib/site-packages" -r ./requirements.txt -$env:FLASK_APP = "hello_app.webapp" -python -m flask run -``` + ```bash + cd python-sample-vscode-flask-tutorial + ``` + +1. Build and run the app -Open a browser and go to *http:\//localhost:5000* to view the app. Verify that you see the title `Visual Studio Flask Tutorial`. + # [Linux](#tab/linux) + + ```bash + python -m venv .env + source .env/bin/activate + pip install --upgrade pip + pip install -r ./requirements.txt + export set FLASK_APP=hello_app.webapp + python3 -m flask run + ``` + + # [PowerShell](#tab/windows-powershell) + + ```powershell + py -m venv .env + .env\scripts\activate + pip install -r ./requirements.txt + $env:FLASK_APP = "hello_app.webapp" + flask run + ``` + + --- -When you're finished, close the browser and stop the Flask server with **Ctrl**+**C**. +1. To view the app, open a browser window and go to *http://localhost:5000*. Verify that you see the title `Visual Studio Flask Tutorial`. -## Provision the target Azure App Service +1. When you're finished, close the browser window and stop the Flask server with Ctrl+C. -The quickest way to create an App Service instance is to use the Azure command-line interface (CLI) through the interactive Azure Cloud Shell. In the following steps, you use [az webapp up](/cli/azure/webapp#az-webapp-up) to both provision the App Service and do the first deployment of your app. +### Open a Cloud Shell 1. Sign in to the Azure portal at [https://portal.azure.com](https://portal.azure.com). -1. Open the Azure CLI by selecting the Cloud Shell button on the portal's toolbar: +1. Open the Azure CLI by selecting the Cloud Shell button on the portal toolbar. - ![Azure Cloud Shell button on the Azure portal toolbar](../media/python/azure-cloud-shell-button.png) + :::image type="content" source="../media/python/azure-cloud-shell-button.png" alt-text="Screenshot of Azure Cloud Shell button on the Azure portal toolbar."::: -1. The Cloud Shell appears along the bottom of the browser. Select **Bash** from the dropdown: +1. The Cloud Shell appears along the bottom of the browser. Select **Bash** from the dropdown menu. - ![Azure Cloud Shell appearance](../media/python/azure-cloud-shell-interface.png) + :::image type="content" source="../media/python/azure-cloud-shell-interface.png" alt-text="Screenshot of Azure Cloud Shell."::: -1. In the Cloud Shell, clone your repository using `git clone`. For the example app, use: +1. To give you more space to work, select the maximize button. - ```bash - git clone https://github.com//python-sample-vscode-flask-tutorial - ``` +### Create an Azure App Service web app - > [!NOTE] - > The Cloud Shell is backed by an Azure Storage account in a resource group called *cloud-shell-storage-\*. That storage account contains an image of the Cloud Shell's file system, which stores the cloned repository. There's a small cost for this storage. You can delete the storage account at the end of this article, along with other resources you create. +Create your Azure App Service web app from the Cloud Shell in the Azure portal. - Replace `` with the name of the GitHub account you used to fork the repository. - - > [!TIP] - > To paste into the Cloud Shell, use **Ctrl**+**Shift**+**V**, or right-click and select **Paste** from the context menu. +> [!TIP] +> To paste into the Cloud Shell, use Ctrl+Shift+V or right-click and select **Paste** from the context menu. -2. In the Cloud Shell, change directories into the repository folder that has your Python app, so the `az webapp up` command will recognize the app as Python. +1. Clone your repository with the following command, replacing `` with the URL of your forked repository. ```bash - cd python-sample-vscode-flask-tutorial + git clone ``` -3. In the Cloud Shell, use `az webapp up` to create an App Service and initially deploy your app. +1. Change directory to the cloned repository folder, so the `az webapp up` command recognizes the app as a Python app. - ```azurecli - az webapp up -n + ```bash + cd python-sample-vscode-flask-tutorial ``` - Change `` to a name for your app service that's unique across Azure. Typically, you use a personal or company name along with an app identifier, such as `-flaskpipelines`. The app URL becomes *\.azurewebsites.net*. - - When the command completes, it shows JSON output in the Cloud Shell. +1. Use the [az webapp up](/cli/azure/webapp#az-webapp-up) command to both provision the App Service and do the first deployment of your app. Replace `` with a name that is unique across Azure. Typically, you use a personal or company name along with an app identifier, such as `-flaskpipelines`. The app URL becomes *\.azurewebsites.net*. - > [!TIP] - > If you encounter a "Permission denied" error with a *.zip* file, you may have tried to run the command from a folder that doesn't contain a Python app. The `az webapp up` command then tries to create a Windows app service plan, and fails. + ```azurecli + az webapp up --name + ``` -4. If your app uses a custom startup command, set the [az webapp config](/cli/azure/webapp/config#az-webapp-config-set) property. For example, the *python-sample-vscode-flask-tutorial* app contains a file named *startup.txt* that contains its specific startup command, so you set the `az webapp config` property to `startup.txt`. + The JSON output of the `az webapp up` command shows: + + ```json + { + "URL": , + "appserviceplan": , + "location": , + "name": , + "os": "Linux", + "resourcegroup": , + "runtime_version": "python|3.11", + "runtime_version_detected": "-", + "sku": , + "src_path": + } + ``` - 1. From the first line of output from the previous `az webapp up` command, copy the name of your resource group, which is similar to **\\_rg\_Linux\_\**. + Note the `URL` and the `runtime_version` values. You use the `runtime_version` in the pipeline YAML file. The `URL` is the URL of your web app. You can use it to verify that the app is running. - 2. Enter the following command, using your resource group name, your app service name (``), and your startup file or command (`startup.txt`). + > [!NOTE] + > The `az webapp up` command does the following actions: + > + >* Create a default [resource group](/cli/azure/group#az-group-create). + > + >* Create a default [App Service plan](/cli/azure/appservice/plan#az-appservice-plan-create). + > + >* [Create an app](/cli/azure/webapp#az-webapp-create) with the specified name. + > + >* [Zip deploy](/azure/app-service/deploy-zip) all files from the current working directory, with build automation enabled. + > + >* Cache the parameters locally in the *.azure/config* file so that you don't need to specify them again when deploying later with `az webapp up` or other `az webapp` commands from the project folder. The cached values are used automatically by default. + > + > You can override the default action with your own values using the command parameters. For more information, see [az webapp up](/cli/azure/webapp#az-webapp-up). + +1. The *python-sample-vscode-flask-tutorial* app has a *startup.txt* file that contains the specific startup command for the web app. Set the web app `startup-file` configuration property to `startup.txt`. + + 1. From the `az webapp up` command output, copy the `resourcegroup` value. + + 1. Enter the following command, using the resource group and your app name. ```azurecli - az webapp config set -g -n --startup-file + az webapp config set --resource-group --name --startup-file startup.txt ``` - - When the command completes, it shows JSON output in the Cloud Shell. -5. To see the running app, open a browser and go to *http:\//\.azurewebsites.net*. If you see a generic page, wait a few seconds for the App Service to start, and refresh the page. Verify that you see the title `Visual Studio Flask Tutorial`. + When the command completes, it shows JSON output that contains all of the configuration settings for your web app. - > [!NOTE] - > For a detailed description of the specific tasks performed by the `az webapp up` command, see [Provision an App Service with single commands](#provision-an-app-service-with-single-commands) at the end of this article. - -## Create an Azure DevOps project and connect to Azure +1. To see the running app, open a browser and go to the `URL` shown in the `az webapp up` command output. If you see a generic page, wait a few seconds for the App Service to start, then refresh the page. Verify that you see the title `Visual Studio Flask Tutorial`. -To deploy to Azure App Service from Azure Pipelines, you need to establish a *service connection* between the two services. +## Create an Azure DevOps project -1. In a browser, go to [dev.azure.com](https://dev.azure.com). If you don't yet have an account on Azure DevOps, select **Start free** and get a free account. If you have an account already, select **Sign in to Azure DevOps**. +Create a new Azure DevOps project. - > [!IMPORTANT] - > To simplify the service connection, use the same email address for Azure DevOps as you use for Azure. - -2. Once you sign in, the browser displays your Azure DevOps dashboard, at the URL *https:\//dev.azure.com/\*. If more than one organization is listed, select the one you want to use for this tutorial. By default, Azure DevOps creates a new organization using the email alias you used to sign in. - - A project is a grouping for boards, repositories, pipelines, and other aspects of Azure DevOps. If your organization doesn't have any projects, enter the project name *Flask Pipelines* under **Create a project to get started**, and then select **Create project**. +::: moniker range=">=azure-devops" - ![First view of Azure DevOps dashboard](../media/python/azure-devops-dashboard.png) - - If your organization already has projects, select **New project** on the organization page. In the **Create new project** dialog box, enter the project name *Flask Pipelines*, and select **Create**. +1. In a browser, go to [dev.azure.com](https://dev.azure.com) and sign in. +1. Select your organization. +1. Create a new project by selecting **New project** or **Create project** if creating the first project in the organization. +1. Enter a **Project name**. +1. Select the **Visibility** for your project. +1. Select **Create**. -3. From the new project page, select **Project settings** from the left navigation. +::: moniker-end - ![Project settings command on the project dashboard](../media/python/project-settings.png) +::: moniker range="< azure-devops" -4. On the **Project Settings** page, select **Pipelines** > **Service connections**, then select **New service connection**, and then select **Azure Resource Manager** from the dropdown. +1. In a browser, go to your Azure DevOps Server. +1. Select your collection. +1. Create a new project by selecting **New project** or **Create project** if creating the first project in the collection. +1. Enter a **Project name**. +1. Select the **Visibility** for your project. +1. Select **Create**. - ![Select Azure Resource Manager service connection](../media/python/service-connection-01.png) +::: moniker-end -5. In the **Add an Azure Resource Manager service connection** dialog box: - 1. Give the connection a name. Make note of the name to use later in the pipeline. - 2. For **Scope level**, select **Subscription**. - 3. Select the subscription for your App Service from the **Subscription** drop-down list. - 4. Under **Resource Group**, select your resource group from the dropdown. - 5. Make sure the option **Allow all pipelines to use this connection** is selected, and then select **OK**. - ![New service connection dialog box](../media/python/service-connection-02.png) +::: moniker range="< azure-devops" - The new connection appears in the **Service connections** list, and is ready for Azure Pipelines to use from the project. +## Create a service principal - > [!NOTE] - > If you want to use an Azure subscription from a different email account, follow the instructions on [Create an Azure Resource Manager service connection with an existing service principal](../library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-with-an-existing-service-principal). +A service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources. This access is restricted to the roles assigned to the service principal, giving you control over which resources can be accessed and at which level. +To create a service principal, go to cloud shell (bash) and run the following command. Replace `` with a name for your service principal, `` with your subscription ID, and `` with the resource group for the web app. -## Create a Python-specific pipeline to deploy to App Service +```azurecli +az ad sp create-for-rbac --display-name --role contributor --scopes /subscriptions//resourceGroups/ +``` -1. From your project page left navigation, select **Pipelines**. +The command returns a JSON object similar to the following example: - ![Selecting Pipelines on the project dashboard](../media/python/select-pipelines.png) +```json +{ + "clientId": "", + "clientSecret": "", + "subscriptionId": "", + "tenantId": "", + ... +} +``` -1. Select **Create Pipeline**: +Make note of the `clientId`, `clientSecret`, `subscriptionId`, and `tenantId` values. You need these values to create a service connection in the next section. - :::image type="content" source="media/create-first-pipeline.png" alt-text="New pipeline button on the pipelines list."::: +::: moniker-end -1. On the **Where is your code** screen, select **GitHub**. You may be prompted to sign into GitHub. +## Create a service connection - ![Where is your code prompt](../media/python/where-is-your-code.png) +A service connection allows you to create a connection to provide authenticated access from Azure Pipelines to external and remote services. To deploy to your Azure App Service web app, create a service connection to the resource group containing the web app. -1. On the **Select a repository** screen, select the repository that contains your app, such as your fork of the example app. +::: moniker range=">=azure-devops" - ![Select a repository](../media/python/select-repository.png) +1. On project page, select **Project settings**. -1. You may be prompted to enter your GitHub password again as a confirmation, and then GitHub prompts you to install the **Azure Pipelines** extension: + :::image type="content" source="../media/python/project-settings.png" alt-text="Screenshot of project settings button on the project dashboard."::: - ![Install Azure Pipelines extension on GitHub](../media/python/github-pipelines-install-01.png) +1. Select **Service connections** in the **Pipelines** section of the menu. +1. Select **Create service connection**. +1. Select **Azure Resource Manager** and select **Next**. - On this screen, scroll down to the **Repository access** section, choose whether to install the extension on all repositories or only selected ones, and then select **Approve and install**: + :::image type="content" source="../media/python/service-connection-type-devops-services.png" alt-text="Screenshot of Azure Resource Manager service connection selection."::: - ![Install Azure Pipelines extension on GitHub approval](../media/python/github-pipelines-install-02.png) +1. Select your authentication method and select **Next**. +1. In the **New Azure service connection** dialog, enter the information specific to the selected authentication method. For more information about authentication methods, see [Connect to Azure by using an Azure Resource Manager service connection](../library/connect-to-azure.md). + + For example, if you're using a **Workload Identity federation (automatic)** or **Service principal (automatic)** authentication method, enter the required information. -1. On the **Configure your pipeline** screen, select **Python to Linux Web App on Azure**. + :::image type="content" source="../media/azure-service-connection-settings-devops-services.png" alt-text="Screenshot of New service connection dialog box."::: - Your new pipeline appears. When prompted, select the Azure subscription in which you created your Web App. - - Select the Web App - - Select Validate and configure + |**Field**|**Description**| + |--|--| + |**Scope level**| Select **Subscription**.| + |**Subscription**| Your Azure subscription name.| + |**Resource group**| The name of the resource group containing your web app.| + |**Service connection name**| A descriptive name for the connection.| + |**Grant access permissions to all pipelines**| Select this option to grant access to all pipelines.| + +1. Select **Save**. - Azure Pipelines creates an **azure-pipelines.yml** file that defines your CI/CD pipeline as a series of *stages*, *Jobs*, and *steps*, where each step contains the details for different *tasks* and *scripts*. Take a look at the pipeline to see what it does. Make sure all the default inputs are appropriate for your code. +The new connection appears in the **Service connections** list, and is ready for use in your Azure Pipeline. +::: moniker-end -### YAML pipeline explained +::: moniker range="< azure-devops" -The YAML file contains the following key elements: +1. On project page, select **Project settings**. -- The `trigger` at the top indicates the commits that trigger the pipeline, such as commits to the `main` branch. -- The `variables` that parameterize the YAML template - - > [!TIP] - > To avoid hard-coding specific variable values in your YAML file, you can define variables in the pipeline's web interface instead. For more information, see [Variables - Secrets](../process/variables.md#secret-variables). -- The `stages` - - Build `stage`, which builds your project, and a Deploy stage, which deploys it to Azure as a Linux web app. - - Deploy `stage` that also creates an Environment with default name same as the Web App. You can choose to modify the environment name. -- Each stage has a `pool` element that specifies one or more virtual machines (VMs) in which the pipeline runs the `steps`. By default, the `pool` element contains only a single entry for an Ubuntu VM. You can use a pool to run tests in multiple environments as part of the build, such as using different Python versions for creating a package. -- The `steps` element can contain children like `task`, which runs a specific task as defined in the Azure Pipelines [task reference](../tasks/index.md), and `script`, which runs an arbitrary set of commands. + :::image type="content" source="../media/python/project-settings.png" alt-text="Screenshot of project settings button on the project dashboard."::: -- The first task under Build stage is [UsePythonVersion](/azure/devops/pipelines/tasks/reference/use-python-version-v0), which specifies the version of Python to use on the build agent. The `@` suffix indicates the version of the task. The `@0` indicates preview version. -Then we have script-based task that creates a virtual environment and installs dependencies from file (requirements.txt). +1. Select **Service connections** in the **Pipelines** section of the menu. +1. Select **Create service connection**. - ```yaml - steps: - - task: UsePythonVersion@0 - inputs: - versionSpec: '$(pythonVersion)' - displayName: 'Use Python $(pythonVersion)' - - script: | - python -m venv antenv - source antenv/bin/activate - python -m pip install --upgrade pip - pip install setup - pip install --target="./.python_packages/lib/site-packages" -r ./requirements.txt - workingDirectory: $(projectRoot) - displayName: "Install requirements" - ``` +1. Select **Azure Resource Manager** and select **Next**. + :::image type="content" source="../media/python/service-connection-type-devops-services.png" alt-text="Screenshot of Azure Resource Manager service connection selection."::: -- Next step creates the *.zip* file that the steps under deploy stage of the pipeline deploys. To create the *.zip* file, add an [ArchiveFiles](/azure/devops/pipelines/tasks/reference/archive-files-v2) task to the end of the YAML file: - - ```yaml - - task: ArchiveFiles@2 - inputs: - rootFolderOrFile: '$(Build.SourcesDirectory)' - includeRootFolder: false - archiveType: 'zip' - archiveFile: '$(Build.ArtifactStagingDirectory)/Application$(Build.BuildId).zip' - replaceExistingArchive: true - verbose: # (no value); this input is optional - - publish: $(Build.ArtifactStagingDirectory)/Application$(Build.BuildId).zip - displayName: 'Upload package' - artifact: drop - ``` +1. On **New Azure service connection**, select **Service principal (manual)** and select **Next** +1. On the next dialog, fill in the required information. + + :::image type="content" source="../media/azure-service-connection-settings-devops-server.png" alt-text="Screenshot of new service connection dialog box."::: + + + |**Field**|**Description**| + |--|--| + |**Environment**| Select `Azure Cloud`.| + |**Scope level**| Select **Subscription**.| + |**Subscription Id**| Your subscription ID.| + |**Subscription Name**| Your Azure subscription name.| + |**Service Principal Id**| The `appId` value from the JSON object returned by the `az ad sp create-for-rbac` command.| + |**Service Principal Key**| The `password` value from the JSON object returned by the `az ad sp create-for-rbac` command.| + |**Tenant Id**| The `tenant` value from the JSON object returned by the `az ad sp create-for-rbac` command.| + +1. Select **Verify** to verify the connection. +1. Enter a **Service connection name**. +1. Ensure **Grant access permissions to all pipelines** is selected. +1. Select **Verify and save**. + +The new connection appears in the **Service connections** list, and is ready for Azure Pipelines to use from the project. + +::: moniker-end + +::: moniker range="< azure-devops" + +## Configure a self-hosted agent + +If you're using your own self-hosted agent, you need to configure the agent to run Python. Downloading Python versions isn't supported on self-hosted agents. You must preinstall the Python version. Use the full installer to get a pip-compatible version of Python. + +To avoid incompatible issues, you should match the Python version with the runtime version on your Azure App Services web app. The runtime version is shown in the JSON output of the `az webapp up` command. + +The desired Python version needs to be added to the tool cache on the self-hosted agent so the task can use it. Normally, the tool cache is located under the _work/_tool directory of the agent; alternatively, the path can be overridden with the environment variable AGENT_TOOLSDIRECTORY. Under the tools directory, create the following directory structure based on of your Python version: + +```console +$AGENT_TOOLSDIRECTORY/ + Python/ + {version number}/ + {platform}/ + {tool files} + {platform}.complete +``` + +The version number should follow the format of 1.2.3. The platform should either be x86 or x64. The tool files should be the unzipped Python version files. The `{platform}.complete` should be a 0-byte file that looks like `x86.complete` or `x64.complete` and just signifies the tool is properly installed in the cache. + +For example, if you're using Python 3.11 on a 64-bit Windows machine, the directory structure would look like this: + +```console +$AGENT_TOOLSDIRECTORY/ + Python/ + 3.11.4/ + x64/ + {python files} + x64.complete +``` + +If you already have the Python version you want to use on the machine hosting your agent, you can copy the files to the tool cache. If you don't have the Python version, you can download it from the [Python website](https://www.python.org/downloads/). + +::: moniker-end + +## Create a pipeline + +Create a pipeline to build and deploy your Python web app to Azure App Service. To understand pipeline concepts, watch: - You use `$()` in a parameter value to reference variables. The built-in `Build.SourcesDirectory` variable contains the location on the build agent where the pipeline cloned the app code. The `archiveFile` parameter indicates where to place the *.zip* file. In this case, the `archiveFile` parameter uses the built-in variable `Build.ArtifactsStagingDirectory`. +> [!VIDEO https://learn-video.azurefd.net/vod/player?id=20e737aa-cadc-4603-9685-3816085087e9] - > [!IMPORTANT] - > When deploying to Azure App Service, be sure to use `includeRootFolder: false`. Otherwise, the contents of the *.zip* file are put in a folder named *s*, for "sources," which is replicated on the App Service. The App Service on Linux container then can't find the app code. +::: moniker range=">=azure-devops" -- Then we have the task to upload the artifacts. +1. On the left navigation menu, select **Pipelines**. -- In the Deploy stage, we use the `deployment` keyword to define a [deployment job](../process/deployment-jobs.md) targeting an [environment](../process/environments.md). By using the template, an environment with same name as the Web app is automatically created if it doesn't already exist. Instead, you can pre-create the environment and provide the `environmentName`. + :::image type="content" source="../media/python/select-pipelines.png" alt-text="Screenshot of Pipelines selection on the project dashboard."::: -- Within the deployment job, first task is [UsePythonVersion](/azure/devops/pipelines/tasks/reference/use-python-version-v0), which specifies the version of Python to use on the build agent. -- We then use the [AzureWebApp](/azure/devops/pipelines/tasks/reference/azure-web-app-v1) task to deploy the *.zip* file to the App Service you identified by the `azureServiceConnectionId` and `webAppName` variables at the beginning of the pipeline file. If you need to use a different service connection, select **Settings** for the `AzureWebApp@1` task and update the **Azure subscription** value. Paste the following code at the end of the file: +1. Select **Create Pipeline**. - ```yaml + :::image type="content" source="media/create-first-pipeline.png" alt-text="Screenshot of new pipeline button on the pipelines list."::: + +1. In the **Where is your code** dialog, select **GitHub**. You might be prompted to sign into GitHub. + + :::image type="content" source="../media/python/where-is-your-code.png" alt-text="Screenshot of select GitHub as the location of your code."::: + +1. On the **Select a repository** screen, select the forked sample repository. + + :::image type="content" source="../media/python/select-repository.png" alt-text="Screenshot of repository selection."::: + +1. You might be prompted to enter your GitHub password again as a confirmation. +1. If the Azure Pipelines extension isn't installed on GitHub, GitHub prompts you to install the **Azure Pipelines** extension. + + :::image type="content" source="../media/python/github-pipelines-install-01.png" alt-text="Install Azure Pipelines extension on GitHub."::: + + On this page, scroll down to the **Repository access** section, choose whether to install the extension on all repositories or only selected ones, and then select **Approve and install**. + + :::image type="content" source="../media/python/github-pipelines-install-02.png" alt-text="Screenshot of Approve and Install Azure Pipelines extension on GitHub."::: + +1. In the **Configure your pipeline** dialog, select **Python to Linux Web App on Azure**. +1. Select your Azure subscription and select **Continue**. +1. If you're using your username and password to authenticate, a browser opens for you to sign in to your Microsoft account. +1. Select your web app name from the dropdown list and select **Validate and configure**. + +Azure Pipelines creates a **azure-pipelines.yml** file and displays it in the YAML pipelines editor. The pipeline file defines your CI/CD pipeline as a series of *stages*, *Jobs*, and *steps*, where each step contains the details for different *tasks* and *scripts*. Take a look at the pipeline to see what it does. Make sure all the default inputs are appropriate for your code. + +::: moniker-end + +::: moniker range="< azure-devops" + +1. On the navigation menu, select **Pipelines**. + + :::image type="content" source="../media/python/select-pipelines.png" alt-text="Screenshot of Pipelines selection on the project dashboard."::: + +1. Select **Create Pipeline**. + + :::image type="content" source="media/create-first-pipeline.png" alt-text="Screenshot of New pipeline button."::: + +1. In the **Where is your code** dialog, select **GitHub Enterprise Server**. You might be prompted to sign into GitHub. + + :::image type="content" source="../media/python/where-is-your-code.png" alt-text="Screenshot of select GitHub as the location of your code."::: + +1. On the **Select a repository** tab, select the forked sample repository. + + :::image type="content" source="../media/python/select-repository.png" alt-text="Screenshot of repository selection."::: + +1. You might be prompted to enter your GitHub password again as a confirmation. +1. If the Azure Pipelines extension isn't installed on GitHub, GitHub prompts you to install the **Azure Pipelines** extension. + + :::image type="content" source="../media/python/github-pipelines-install-01.png" alt-text="Screenshot of Azure Pipelines extension on GitHub."::: + + On this page, scroll down to the **Repository access** section, choose whether to install the extension on all repositories or only selected ones, and then select **Approve and install**. + + :::image type="content" source="../media/python/github-pipelines-install-02.png" alt-text="Screenshot of Approve and Install Azure Pipelines extension on GitHub."::: + +1. In the **Configure your pipeline** dialog, select **Starter pipeline**. +1. Replace the contents of the **azure-pipelines.yml** file with the following code. + + ```yml + trigger: + - main + + variables: + # Azure Resource Manager connection created during pipeline creation + azureServiceConnectionId: '' + + # Web app name + webAppName: '' + + # Environment name + environmentName: '' + + # Project root folder. + projectRoot: $(System.DefaultWorkingDirectory) + + # Python version: + pythonVersion: '' + + stages: + - stage: Build + displayName: Build stage + jobs: + - job: BuildJob + pool: + name: '' + demands: python + steps: + - task: UsePythonVersion@0 + inputs: + versionSpec: '$(pythonVersion)' + displayName: 'Use Python $(pythonVersion)' + + - script: | + python -m venv antenv + source antenv/bin/activate + python -m pip install --upgrade pip + pip install -r requirements.txt + workingDirectory: $(projectRoot) + displayName: "Install requirements" + + - task: ArchiveFiles@2 + displayName: 'Archive files' + inputs: + rootFolderOrFile: '$(projectRoot)' + includeRootFolder: false + archiveType: zip + archiveFile: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip + replaceExistingArchive: true + + - task: PublishBuildArtifacts@1 + inputs: + PathtoPublish: '$(Build.ArtifactStagingDirectory)' + ArtifactName: 'drop' + publishLocation: 'Container' + + - stage: Deploy + displayName: 'Deploy Web App' + dependsOn: Build + condition: succeeded() + jobs: + - deployment: DeploymentJob + pool: + name: '' + inputs: + azureSubscription: $(azureServiceConnectionId) + appName: $(webAppName) + package: $(Pipeline.Workspace)/drop/$(Build.BuildId).zip + startUpCommand: 'startup.txt' + + ``` + +1. Replace the following placeholders with your own values: + + |**Placeholder**|**Description**| + |--|--| + |``|The name of the service connection you created.| + |``|The name your Azure App Service web app.| + |``|The name of the agent pool you want to use.| + |``|The version of Python running on your agent. It's a good idea to match this version with the Python version running on your web app. The web app version is shown in the JSON output of the `az webapp up` command.| + + +::: moniker-end + +### YAML pipeline file + +The following explanation describes the YAML pipeline file. To learn about the pipeline YAML file schema, see [YAML schema reference](/azure/devops/pipelines/yaml-schema/pipeline). + +::: moniker range="azure-devops" + +The complete example pipeline YAML file is shown below: + +```yml +trigger: +- main + +variables: + # Azure Resource Manager connection created during pipeline creation + azureServiceConnectionId: '' + + # Web app name + webAppName: '' + + # Agent VM image name + vmImageName: 'ubuntu-latest' + + # Environment name + environmentName: '' + + # Project root folder. Point to the folder containing manage.py file. + projectRoot: $(System.DefaultWorkingDirectory) + + pythonVersion: '3.11' + +stages: +- stage: Build + displayName: Build stage + jobs: + - job: BuildJob + pool: + vmImage: $(vmImageName) + steps: + - task: UsePythonVersion@0 + inputs: + versionSpec: '$(pythonVersion)' + displayName: 'Use Python $(pythonVersion)' + + - script: | + python -m venv antenv + source antenv/bin/activate + python -m pip install --upgrade pip + pip install setuptools + pip install -r requirements.txt + workingDirectory: $(projectRoot) + displayName: "Install requirements" + + - task: ArchiveFiles@2 + displayName: 'Archive files' + inputs: + rootFolderOrFile: '$(projectRoot)' + includeRootFolder: false + archiveType: zip + archiveFile: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip + replaceExistingArchive: true + + - upload: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip + displayName: 'Upload package' + artifact: drop + +- stage: Deploy + displayName: 'Deploy Web App' + dependsOn: Build + condition: succeeded() jobs: - deployment: DeploymentJob pool: @@ -264,101 +578,401 @@ Then we have script-based task that creates a virtual environment and installs d runOnce: deploy: steps: - + - task: UsePythonVersion@0 inputs: versionSpec: '$(pythonVersion)' displayName: 'Use Python version' - task: AzureWebApp@1 - displayName: 'Deploy Azure Web App : {{ webAppName }}' + displayName: 'Deploy Azure Web App : $(webAppName)' inputs: azureSubscription: $(azureServiceConnectionId) appName: $(webAppName) package: $(Pipeline.Workspace)/drop/$(Build.BuildId).zip - deploymentMethod: zipDeploy +``` + +::: moniker-end + +#### Variables + +::: moniker range=">=azure-devops" + +The `variables` section contains the following variables: + +```yml +variables: +# Azure Resource Manager connection created during pipeline creation +azureServiceConnectionId: '' - # The following parameter is specific to the Flask example code. You may - # or may not need a startup command for your app. +# Web app name +webAppName: '' - startUpCommand: 'gunicorn --bind=0.0.0.0 --workers=4 startup:app' +# Agent VM image name +vmImageName: 'ubuntu-latest' + +# Environment name +environmentName: '' + +# Project root folder. +projectRoot: $(System.DefaultWorkingDirectory) + +# Python version: 3.11. Change this to match the Python runtime version running on your web app. +pythonVersion: '3.11' + +``` + +|**Variable**|**Description**| +|--|---| +|`azureServiceConnectionId`|The ID or name of the Azure Resource Manager service connection.| +|`webAppName`|The name of the Azure App Service web app.| +|`vmImageName`|The name of the operating system to use for the build agent.| +|`environmentName`|The name of the environment used in the deployment stage. The environment is automatically created when the stage job is run.| +|`projectRoot`|The root folder containing the app code.| +|`pythonVersion`|The version of Python to use on the build and deployment agents.| + +::: moniker-end + +::: moniker range="< azure-devops" + +The `variables` section contains the following variables: + +```yml +variables: +# Azure Resource Manager connection created during pipeline creation +azureServiceConnectionId: '' + +# Web app name +webAppName: '' + +# Environment name +environmentName: '' + +# Project root folder. +projectRoot: $(System.DefaultWorkingDirectory) + +# Python version: 3.11. Change this to the version that is running on your agent and web app. +pythonVersion: '3.11' +``` + +|**Variable**|**Description**| +|--|---| +|`azureServiceConnectionId`|The name of the Azure Resource Manager service connection.| +|`webAppName`|The name of the web app.| +|`environmentName`|The name of the environment used in the deployment stage.| +|`projectRoot`|The folder containing the app code. The value is an automatic system variable. | +|`pythonVersion`|The version of Python to use on the build and deployment agents.| + +::: moniker-end + +#### Build stage + +::: moniker range=">=azure-devops" + +The build stage contains a single job that runs on the operating system defined in the vmImageName variable. + +```yml + - job: BuildJob + pool: + vmImage: $(vmImageName) +``` + +::: moniker-end + + +::: moniker range="< azure-devops" + +The build stage contains a single job that runs on an agent in the pool identified by the name parameter. You can specify the agent capabilities with the `demands` keyword. For example, `demands: python` specifies that the agent must have Python installed. To specify a self-hosted agent by name, you can use the `demands: Agent.Name -equals ` keyword. + +```yml + - job: BuildJob + pool: + name: + demands: python +``` + +::: moniker-end + +The job contains multiple steps: + +1. The [UsePythonVersion](/azure/devops/pipelines/tasks/reference/use-python-version-v0) task selects the version of Python to use. The version is defined in the `pythonVersion` variable. + + ```yml + - task: UsePythonVersion@0 + inputs: + versionSpec: '$(pythonVersion)' + displayName: 'Use Python $(pythonVersion)' + ``` + +1. This step uses a script to create a virtual Python environment and install the app's dependencies contained in the `requirements.txt` The `workingDirectory` parameter specifies the location of the app code. + + ```yml + - script: | + python -m venv antenv + source antenv/bin/activate + python -m pip install --upgrade pip + pip install setuptools + pip install -r ./requirements.txt + workingDirectory: $(projectRoot) + displayName: "Install requirements" + ``` + +1. The [ArchiveFiles](/azure/devops/pipelines/tasks/reference/archive-files-v2) task creates the *.zip* archive containing the web app. The `.zip` file is uploaded to the pipeline as the artifact named `drop`. The `.zip` file is used in the deployment stage to deploy the app to the web app. + + ```yml + - task: ArchiveFiles@2 + displayName: 'Archive files' + inputs: + rootFolderOrFile: '$(projectRoot)' + includeRootFolder: false + archiveType: zip + archiveFile: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip + replaceExistingArchive: true + + - upload: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip + displayName: 'Upload package' + artifact: drop + ``` + + |**Parameter**|**Description**| + |---|---| + |`rootFolderOrFile`|The location of the app code.| + |`includeRootFolder`|Indicates whether to include the root folder in the *.zip* file. Set this parameter to `false` otherwise, the contents of the *.zip* file are put in a folder named *s* and App Service on Linux container can't find the app code.| + |`archiveType`|The type of archive to create. Set to `zip`.| + |`archiveFile`|The location of the *.zip* file to create.| + |`replaceExistingArchive`|Indicates whether to replace an existing archive if the file already exists. Set to `true`.| + |`upload`|The location of the *.zip* file to upload.| + |`artifact`|The name of the artifact to create.| + +#### Deployment stage + +The deployment stage is run if the build stage completes successfully. The following keywords define this behavior: + +```yml + dependsOn: Build + condition: succeeded() +``` + +The deployment stage contains a single deployment job configured with the following keywords: + +::: moniker range=">=azure-devops" + +```yml + - deployment: DeploymentJob + pool: + vmImage: $(vmImageName) + environment: $(environmentName) +``` + +|**Keyword**|**Description**| +|--|---| +|`deployment`|Indicates that the job is a [deployment job](../process/deployment-jobs.md) targeting an [environment](../process/environments.md).| +|`pool`|Specifies deployment agent pool. The default agent pool if the name isn't specified. The `vmImage` keyword identifies the operating system for the agent's virtual machine image| +|`environment`|Specifies the environment to deploy to. The environment is automatically created in your project when the job is run.| + +::: moniker-end + +::: moniker range="< azure-devops" + +```yml + - deployment: DeploymentJob + pool: + name: + environment: $(environmentName) +``` + +|**Keyword**|**Description**| +|--|---| +|`deployment`|Indicates that the job is a [deployment job](../process/deployment-jobs.md) targeting an [environment](../process/environments.md).| +|`pool` Specifies the agent pool to use for deployment. This pool must contain an agent with the capability to run the python version specified in the pipeline.| +|`environment`|Specifies the environment to deploy to. The environment is automatically created in your project when the job is run.| + +::: moniker-end + +The `strategy` keyword is used to define the deployment strategy. The `runOnce` keyword specifies that the deployment job runs once. The `deploy` keyword specifies the steps to run in the deployment job. + +```yml + strategy: + runOnce: + deploy: + steps: +``` + +::: moniker range="azure-devops" + +The `steps` in the pipeline are: + +1. Use the [UsePythonVersion](/azure/devops/pipelines/tasks/reference/use-python-version-v0) task to specify the version of Python to use on the agent. The version is defined in the `pythonVersion` variable. + + ```yml + - task: UsePythonVersion@0 + inputs: + versionSpec: '$(pythonVersion)' + displayName: 'Use Python version' + ``` + +1. Deploy the web app using the [AzureWebApp@1](/azure/devops/pipelines/tasks/reference/azure-web-app-v1). This task deploys the pipeline artifact `drop` to your web app. + + ```yml + - task: AzureWebApp@1 + displayName: 'Deploy Azure Web App : ' + inputs: + azureSubscription: $(azureServiceConnectionId) + appName: $(webAppName) + package: $(Pipeline.Workspace)/drop/$(Build.BuildId).zip + ``` + + |**Parameter**|**Description**| + |--|---| + |`azureSubscription`|The Azure Resource Manager service connection ID or name to use.| + |`appName`|The name of the web app.| + |`package`|The location of the *.zip* file to deploy.| + + Also, because the *python-vscode-flask-tutorial* repository contains the same startup command in a file named *startup.txt*, you can specify that file by adding the parameter: `startUpCommand: 'startup.txt'`. + +::: moniker-end + +::: moniker range="< azure-devops" + +The `steps` in the pipeline are: + +1. Use the [UsePythonVersion](/azure/devops/pipelines/tasks/reference/use-python-version-v0) task to specify the version of Python to use on the agent. The version is defined in the `pythonVersion` variable. + + ```yml + - task: UsePythonVersion@0 + inputs: + versionSpec: '$(pythonVersion)' + displayName: 'Use Python version' + ``` + +1. Deploy the web app using the [AzureWebApp@1](/azure/devops/pipelines/tasks/reference/azure-web-app-v1). This task deploys the pipeline artifact `drop` to your web app. + + ```yml + - task: AzureWebApp@1 + displayName: 'Deploy Azure Web App : ' + inputs: + azureSubscription: $(azureServiceConnectionId) + appName: $(webAppName) + package: $(Pipeline.Workspace)/drop/$(Build.BuildId).zip + ``` + + |**Parameter**|**Description**| + |--|---| + |`azureSubscription`|The Azure Resource Manager service connection ID or name to use.| + |`appName`|The name of the web app.| + |`package`|The location of the *.zip* file to deploy.| + + Also, because the *python-vscode-flask-tutorial* repository contains the same startup command in a file named *startup.txt*, you can specify that file by adding the parameter: `startUpCommand: 'startup.txt'`. + + ```yml + - task: AzureWebApp@1 + displayName: 'Deploy Azure Web App : $(webAppName)' + inputs: + azureSubscription: $(azureServiceConnectionId) + appName: $(webAppName) + package: $(Pipeline.Workspace)/drop/$(Build.BuildId).zip + startUpCommand: 'startup.txt' ``` - The `StartupCommand` parameter shown is specific to the *python-vscode-flask-tutorial* example code, which defines the app in the *startup.py* file. By default, Azure App Service looks for the Flask app object in a file named *app.py* or *application.py*. If your code doesn't follow this pattern, customize the startup command. Django apps may not need customization at all. For more information, see [How to configure Python on Azure App Service - Customize startup command](/azure/app-service/containers/how-to-configure-python#customize-startup-command). + |**Parameter**|**Description**| + |--|---| + |`azureSubscription`|The Azure Resource Manager service connection ID or name to use.| + |`appName`|The name of the web app.| + |`package`|The location of the *.zip* file to deploy.| + |`startUpCommand`|The command to run after the app is deployed. The sample app uses `startup.txt`.| + + ::: moniker-end - Also, because the *python-vscode-flask-tutorial* repository contains the same startup command in a file named *startup.txt*, you could specify that file in the `StartupCommand` parameter rather than the command, by using `StartupCommand: 'startup.txt'`. ## Run the pipeline You're now ready to try it out! -1. Select **Save** at upper right in the editor, and in the pop-up window, add a commit message and select **Save**. - -1. Select **Run** on the pipeline editor, and select **Run** again in the **Run pipeline** dialog box. Azure Pipelines queues another pipeline run, acquires an available build agent, and has that build agent run the pipeline. - - The pipeline takes a few minutes to complete, especially the deployment steps. You should see green checkmarks next to each of the steps. - - If there's an error, you can quickly return to the YAML editor by selecting the vertical dots at upper right and selecting **Edit pipeline**: - - ![Edit pipeline comment from a build report](../media/python/edit-pipeline-command.png) - -1. From the build page, select the **Azure Web App task** to display its output. To visit the deployed site, hold down the **Ctrl** key and select the URL after **App Service Application URL**. - - If you're using the Flask example, the app should appear as follows: +1. In the editor, select **Save and run**. +1. In the **Save and run** dialog, add a commit message then select **Save and run**. - ![View of the Flask example code running on App Service](../media/python/app-results.png) + You can watch the pipeline as it runs by selecting the Stages or Jobs in the pipeline run summary. + + :::image type="content" source="../media/python/pipeline-summary-stages-section.png" alt-text="Screenshot of pipeline run summary stages section."::: + + There are green check marks next to each stage and job as it completes successfully. If errors occur, they're displayed in the summary or in the job steps. + + :::image type="content" source="../media/python/pipeline-stages.png" alt-text="Screenshot of pipeline stage steps."::: + + You can quickly return to the YAML editor by selecting the vertical dots at the upper right of the **Summary** page and selecting **Edit pipeline**: + + :::image type="content" source="../media/python/edit-pipeline-command.png" alt-text="Screenshot of edit pipeline comment from a build report."::: + +1. From the deployment job, select the **Deploy Azure Web App** task to display its output. To visit the deployed site, hold down Ctrl and select the URL after `App Service Application URL`. + If you're using the sample app, the app should appear as follows: + + :::image type="content" source="../media/python/app-results.png" alt-text="Screenshot of view of the sample app running on App Service."::: > [!IMPORTANT] > If your app fails because of a missing dependency, then your *requirements.txt* file was not processed during deployment. This behavior happens if you created the web app directly on the portal rather than using the `az webapp up` command as shown in this article. > -> The `az webapp up` command specifically sets the build action `SCM_DO_BUILD_DURING_DEPLOYMENT` to `true`. If you provisioned the app service through the portal, however, this action is not automatically set. +> The `az webapp up` command specifically sets the build action `SCM_DO_BUILD_DURING_DEPLOYMENT` to `true`. If you provisioned the app service through the portal, this action is not automatically set. > > The following steps set the action: +> > 1. Open the [Azure portal](https://portal.azure.com), select your App Service, then select **Configuration**. > 1. Under the **Application Settings** tab, select **New Application Setting**. > 1. In the popup that appears, set **Name** to `SCM_DO_BUILD_DURING_DEPLOYMENT`, set **Value** to `true`, and select **OK**. > 1. Select **Save** at the top of the **Configuration** page. > 1. Run the pipeline again. Your dependencies should be installed during deployment. -## Run a post-deployment script +## Trigger a pipeline run -A post-deployment script can, for example, define environment variables expected by the app code. Add the script as part of the app code and execute it using startup command. +To trigger a pipeline run, commit a change to the repository. For example, you can add a new feature to the app, or update the app's dependencies. -To avoid hard-coding specific variable values in your YAML file, you can instead define variables in the pipeline's web interface and then refer to the variable name in the script. For more information, see [Variables - Secrets](../process/variables.md#secret-variables). +1. Go to your GitHub repository. +1. Make a change to the code, such as changing the title of the app. +1. Commit the change to your repository. +1. Go to your pipeline and verify a new run is created. +1. When the run completes, verify the new build is deployed to your web app. + 1. In the Azure portal, go to your web app. + 1. Select **Deployment Center** and select the **Logs** tab. + 1. Verify that the new deployment is listed. ## Considerations for Django -As noted earlier in this article, you can use Azure Pipelines to deploy Django apps to Azure App Service on Linux, if you're using a separate database. You can't use a SQLite database, because App Service locks the *db.sqlite3* file, preventing both reads and writes. This behavior doesn't affect an external database. +You can use Azure Pipelines to deploy Django apps to Azure App Service on Linux if you're using a separate database. You can't use a SQLite database, because App Service locks the *db.sqlite3* file, preventing both reads and writes. This behavior doesn't affect an external database. -As described in [Configure Python app on App Service - Container startup process](/azure/app-service/containers/how-to-configure-python#container-startup-process), App Service automatically looks for a *wsgi.py* file within your app code, which typically contains the app object. If you want to customize the startup command in any way, use the `StartupCommand` parameter in the `AzureWebApp@1` step of your YAML pipeline file, as described in the previous section. +As described in [Configure Python app on App Service - Container startup process](/azure/app-service/containers/how-to-configure-python#container-startup-process), App Service automatically looks for a *wsgi.py* file within your app code, which typically contains the app object. If you want to customize the startup command in any way, use the `startUpCommand` parameter in the `AzureWebApp@1` step of your YAML pipeline file, as described in the previous section. -When using Django, you typically want to migrate the data models using `manage.py migrate` after deploying the app code. You can add `startUpCommand` with post-deployment script for this purpose: +When using Django, you typically want to migrate the data models using `manage.py migrate` after deploying the app code. You can add `startUpCommand` with a post-deployment script for this purpose. For example, here's the `startUpCommand` property in the AzureWebApp@1 task. -```yaml -startUpCommand: python3.7 manage.py migrate +```yml + - task: AzureWebApp@1 + displayName: 'Deploy Azure Web App : $(webAppName)' + inputs: + azureSubscription: $(azureServiceConnectionId) + appName: $(webAppName) + package: $(Pipeline.Workspace)/drop/$(Build.BuildId).zip + startUpCommand: 'python manage.py migrate' ``` ## Run tests on the build agent -As part of your build process, you may want to run tests on your app code. Tests run on the build agent, so you probably need to first install your dependencies into a virtual environment on the build agent computer. After the tests run, delete the virtual environment before you create the *.zip* file for deployment. The following script elements illustrate this process. Place them before the `ArchiveFiles@2` task in the *azure-pipelines.yml* file. For more information, see [Run cross-platform scripts](../scripts/cross-platform-scripting.md?tabs=yaml). +As part of your build process, you might want to run tests on your app code. Tests run on the build agent, so you need to install your dependencies into a virtual environment on the build agent. After the tests run, delete the virtual environment before you create the *.zip* file for deployment. The following script elements illustrate this process. Place them before the `ArchiveFiles@2` task in the *azure-pipelines.yml* file. For more information, see [Run cross-platform scripts](../scripts/cross-platform-scripting.md?tabs=yaml). -```yaml +```yml # The | symbol is a continuation character, indicating a multi-line script. # A single-line script can immediately follow "- script:". - script: | - python3.7 -m venv .env + python -m venv .env source .env/bin/activate - pip3.7 install setuptools - pip3.7 install -r requirements.txt + pip install setuptools + pip install -r requirements.txt # The displayName shows in the pipeline UI when a build runs displayName: 'Install dependencies on build agent' - script: | # Put commands to run tests here - displayName: 'Run tests' + displayName: 'Run tests' - script: | echo Deleting .env @@ -367,64 +981,19 @@ As part of your build process, you may want to run tests on your app code. Tests displayName: 'Remove .env before zip' ``` -You can also use a task like [PublishTestResults@2](../tasks/test/publish-test-results.md?tabs=yaml) to make test results appear in the pipeline results screen. For more information, see [Build Python apps - Run tests](customize-python.md#run-tests). - -## Provision an App Service with single commands - -The [az webapp up](/cli/azure/webapp#az-webapp-up) command is a convenient method to provision the App Service and initially deploy your app in a single step. If you want more control over the deployment process, you can use single commands to accomplish the same tasks. For example, you might want to use a specific name for the resource group, or create an App Service within an existing App Service Plan. - -The following steps do the equivalent of the `az webapp up` command: - -1. Create a resource group. - - A resource group is a collection of related Azure resources. Creating a resource group makes it easy to delete all those resources at once when you no longer need them. In the Cloud Shell, run the following command to create a resource group in your Azure subscription. Set a location for the resource group by specifying the value of ``. JSON output appears in the Cloud Shell when the command completes successfully. - - ```azurecli - az group create -l -n - ``` - -2. Create an App Service Plan. - - An App Service runs inside a VM defined by an App Service Plan. Run the following command to create an App Service Plan, replacing your own values for `` and ``. The `--is-linux` is required for Python deployments. If you want a pricing plan other than the default F1 Free plan, use the `sku` argument. The `--sku B1` specifies the lower-price compute tier for the VM. You can easily delete the plan later by deleting the resource group. - - ```azurecli - az appservice plan create -g -n --is-linux --sku B1 - ``` - - Again, you see JSON output in the Cloud Shell when the command completes successfully. - -3. Create an App Service instance in the plan. - - Run the following command to create the App Service instance in the plan, replacing `` with a name that's unique across Azure. Typically, you use a personal or company name along with an app identifier, such as `-flaskpipelines`. The command fails if the name is already in use. When you assign the App Service to the same resource group as the plan, it's easy to clean up all the resources at once. - - > [!NOTE] - > If you want to deploy your code at the same time you create the app service, you can use the `--deployment-source-url` and `--deployment-source-branch` arguments with the `az webapp create` command. For more information, see [az webapp create](/cli/azure/webapp?view=azure-cli-latest&preserve-view=true#az-webapp-create). - - ```azurecli - az webapp create -g -p -n --runtime "Python|3.7" - ``` - - > [!TIP] - > If you see the error message "The plan (name) doesn't exist", and you're sure that the plan name is correct, check that the resource group specified with the `-g` argument is also correct, and the plan you identify is part of that resource group. If you misspell the resource group name, the command doesn't find the plan in that nonexistent resource group, and gives this particular error. - -4. If your app requires a custom startup command, use the `az webapp config set` command, as described earlier in [Provision the target Azure App Service](#provision-the-target-azure-app-service). For example, to customize the App Service with your resource group, app name, and startup command, run: - - ```azurecli - az webapp config set -g -n --startup-file - ``` - - The App Service at this point contains only default app code. You can now use Azure Pipelines to deploy your specific app code. +You can also use a task like [PublishTestResults@2](../tasks/test/publish-test-results.md?tabs=yaml) to publish the test results to your pipeline. For more information, see [Build Python apps - Run tests](./customize-python.md#run-tests). ## Clean up resources -To avoid incurring charges on the Azure resources created in this tutorial, delete the resource group that contains the App Service and the App Service Plan. To delete the resource group from the Azure portal, select **Resource groups** in the left navigation. In the resource group list, select the **...** to the right of the resource group you want to delete, select **Delete resource group**, and follow the prompts. +To avoid incurring charges on the Azure resources created in this tutorial: + +* Delete the project that you created. Deleting the project deletes the pipeline and service connection. -You can also use [az group delete](/cli/azure/group#az-group-delete) in the Cloud Shell to delete resource groups. +* Delete the Azure resource group that contains the App Service and the App Service Plan. In the Azure portal, go to the resource group, select **Delete resource group**, and follow the prompts. -To delete the storage account that maintains the file system for Cloud Shell, which incurs a small monthly charge, delete the resource group that begins with **cloud-shell-storage-**. +* Delete the storage account that maintains the file system for Cloud Shell. Close the Cloud Shell then go to the resource group that begins with **cloud-shell-storage-**, select **Delete resource group**, and follow the prompts. ## Next steps -- [Build Python apps](python.md) -- [Learn about build agents](../agents/agents.md) -- [Configure Python app on App Service](/azure/app-service/containers/how-to-configure-python) \ No newline at end of file +* [Customize Python apps in Azure Pipelines](./customize-python.md) +* [Configure Python app on App Service](/azure/app-service/containers/how-to-configure-python) diff --git a/docs/pipelines/ecosystems/python.md b/docs/pipelines/ecosystems/python.md index 9db0d533485..2ffe081e404 100644 --- a/docs/pipelines/ecosystems/python.md +++ b/docs/pipelines/ecosystems/python.md @@ -1,151 +1,210 @@ --- -title: Quickstart - Use Azure Pipelines to build and publish a Python app -description: Automatically build and test Python apps with Azure Pipelines +title: Build and publish a Python app +description: Learn how to automatically build and test Python apps with Azure Pipelines. ms.topic: quickstart +ms.date: 07/08/2024 ms.assetid: 141149f8-d1a9-49fa-be98-ee9a825a951a -ms.date: 12/20/2022 -monikerRange: '>=azure-devops-2019' +monikerRange: "<=azure-devops" ms.custom: devx-track-python, freshness-fy22q2 +ms.author: jukullam --- -# Build Python apps +# Build and publish a Python app [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -You can use Azure Pipelines to build, test, and deploy Python apps and scripts as part of your CI/CD system. This article focuses on creating a basic pipeline. This quickstart walks through how to create a simple Flask app with three pages that use a common base template and deploy it with Azure DevOps. - -You don't have to set up anything for Azure Pipelines to build Python projects. Python is preinstalled on [Microsoft-hosted build agents](../agents/hosted.md) for Linux, macOS, or Windows. To see which Python versions are preinstalled, see [Use a Microsoft-hosted agent](../agents/hosted.md#software). - -To learn about configuring Python in pipelines, see [Customize Python](customize-python.md). - -If you want a more complex example, see [Use CI/CD to deploy a Python web app to Azure App Service on Linux](python-webapp.md). +In this quickstart, you create a pipeline that builds and tests a Python app. You see how to use Azure Pipelines to build, test, and deploy Python apps and scripts as part of your continuous integration and continuous delivery (CI/CD) system. ## Prerequisites -You must have the following items in Azure DevOps: -* A GitHub account where you can create a repository. [Create one for free](https://github.com). -* An Azure DevOps organization and project. [Create one for free](../get-started/pipelines-sign-up.md). -* An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can request a free tier. +[!INCLUDE [ecosystems-prerequisites](includes/ecosystems-prerequisites.md)] +::: moniker range=">=azure-devops" -## 1 - Fork the sample code - -::: moniker range="azure-devops-2019" - -Import this repo into your Git repo in Azure DevOps Server 2019: +Python is preinstalled on [Microsoft-hosted agents](../agents/hosted.md) for Linux, macOS, and Windows. You don't have to set up anything more to build Python projects. To see which Python versions are preinstalled, see [Use a Microsoft-hosted agent](../agents/hosted.md#software). ::: moniker-end -::: moniker range=">=azure-devops-2020" - -For the following sample Python Flask tutorial: - -::: moniker-end - -``` -https://github.com/Microsoft/python-sample-vscode-flask-tutorial -``` - -## 2 - Create your pipeline - -::: moniker range=">=azure-devops-2020" - -1. Sign in to [Azure Pipelines](https://azure.microsoft.com/services/devops/pipelines). Your browser will go to `https://dev.azure.com/my-organization-name` and display your Azure DevOps dashboard. +## Fork the sample code -1. Go to your project and select **Pipelines** > **Create a new pipeline**. +Fork the sample Python repository to your GitHub account. -1. Select **GitHub** as the location of your source code. +1. Go to the [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial) repository. +1. Select **Fork** in the upper-right corner of the page. +1. Select your GitHub account. By default, the fork is named the same as the parent repository, but you can name it something different. -1. If you're redirected to GitHub to sign in, enter your GitHub credentials. +>[!IMPORTANT] +>During the following procedures, you might be prompted to create a [GitHub service connection](../library/service-endpoints.md#github-service-connection) or redirected to GitHub to sign in, install Azure Pipelines, or authorize Azure Pipelines. Follow the onscreen instructions to complete the process. For more information, see [Access to GitHub repositories](../repos/github.md#access-to-github-repositories). -1. When the list of repositories appears, select your Python sample repository. +## Create your pipeline -1. Azure Pipelines analyzes the code in your repository and recommends the `Python package` template for your pipeline. Select that template. +1. In your Azure DevOps project, select **Pipelines** > **Create Pipeline**, and then select **GitHub** as the location of your source code. +1. On the **Select a repository** screen, select your forked sample repository. +1. On the **Configure your pipeline** screen, select **Starter pipeline**. -1. Azure Pipelines generates a YAML file for your pipeline. Select **Save and run** > **Commit directly to the main branch**, and then choose **Save and run** again. +## Customize your pipeline -1. A new run starts. Wait for the run to finish. +On the **Review your pipeline YAML** screen, replace the contents of the generated *azure-pipelines.yml* file with the following code. The code: -When you're done, you have a YAML file *azure-pipelines.yml* in your repository that's ready for you to customize. - -### Customize your pipeline - -1. Edit the `azure-pipelines.yml` file in your repository and update the Python version references. +- Installs required Python versions and dependencies. +- Packages build artifacts to a ZIP archive. +- Publishes the archive to your pipeline. +- Runs tests. +::: moniker range=">=azure-devops" ```yaml trigger: - main pool: vmImage: ubuntu-latest + strategy: matrix: - Python38: - python.version: '3.8' - Python39: - python.version: '3.9' Python310: python.version: '3.10' + Python311: + python.version: '3.11' + Python312: + python.version: '3.12' steps: -- task: UsePythonVersion@0 - inputs: - versionSpec: '$(python.version)' - displayName: 'Use Python $(python.version)' - -- script: | - python -m pip install --upgrade pip - pip install -r requirements.txt - displayName: 'Install dependencies' - -- script: | - pip install pytest pytest-azurepipelines - pytest - displayName: 'pytest' + - task: UsePythonVersion@0 + inputs: + versionSpec: '$(python.version)' + displayName: 'Use Python $(python.version)' + + - script: | + python -m pip install --upgrade pip + pip install -r requirements.txt + displayName: 'Install dependencies' + + - task: ArchiveFiles@2 + displayName: 'Archive files' + inputs: + rootFolderOrFile: $(System.DefaultWorkingDirectory) + includeRootFolder: false + archiveType: zip + archiveFile: $(Build.ArtifactStagingDirectory)/$(Build.BuildId)-$(python.version).zip + replaceExistingArchive: true + + - task: PublishBuildArtifacts@1 + inputs: + PathtoPublish: '$(Build.ArtifactStagingDirectory)' + ArtifactName: 'drop' + publishLocation: 'Container' + + - script: | + pip install pytest pytest-azurepipelines + pytest + displayName: 'pytest' ``` ::: moniker-end +::: moniker range="< azure-devops" -::: moniker range="azure-devops-2019" +Customize *azure-pipelines.yml* to match your project configuration. -1. Add an `azure-pipelines.yml` file in your repository. Customize this snippet for your build. +- If you have a different agent pool, change the pool `name` parameter. +- If necessary, change the Python version to a version installed on your self-hosted agent. -``` yaml -trigger: -- main +```yaml + trigger: + - main + + pool: + name: '' + + steps: + - task: UsePythonVersion@0 + inputs: + versionSpec: '3.12' + displayName: 'Use Python 3.12' + + - script: | + python -m pip install --upgrade pip + pip install -r requirements.txt + displayName: 'Install dependencies' + + + - task: ArchiveFiles@2 + displayName: 'Archive files' + inputs: + rootFolderOrFile: $(System.DefaultWorkingDirectory) + includeRootFolder: false + archiveType: zip + archiveFile: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip + replaceExistingArchive: true + + - task: PublishBuildArtifacts@1 + inputs: + PathtoPublish: '$(Build.ArtifactStagingDirectory)' + ArtifactName: 'drop' + publishLocation: 'Container' + + - script: | + pip install pytest pytest-azurepipelines + pytest + displayName: 'pytest' +``` -pool: Default +::: moniker-end -steps: -- script: python -m pip install --upgrade pip - displayName: 'Install dependencies' +## Run your pipeline -- script: pip install -r requirements.txt - displayName: 'Install requirements' -``` +::: moniker range="<=azure-devops" + +Select **Save and run**, and then select **Save and run** again. -2. Create a pipeline (if you don't know how, see [Create your first pipeline](../create-first-pipeline.md)), and for the template select **YAML**. +The **Summary** tab shows the status of your pipeline run. + +To view your build artifact, select the **published** link in the **Summary** tab. + +::: moniker-end -3. Set the **Agent pool** and **YAML file path** for your pipeline. +::: moniker range=">=azure-devops" -4. Save the pipeline and queue a build. When the **Build #nnnnnnnn.n has been queued** message appears, select the number link to see your pipeline in action. +:::image type="content" source="media/published-artifacts-link.png" alt-text="Screenshot of published build artifacts link."::: -5. When you're ready to make changes to your pipeline, **Edit** it. +The **Artifacts** page shows the published build artifacts. +:::image type="content" source="media/pipeline-artifacts-list.png" alt-text="Screenshot of published build artifacts."::: ::: moniker-end +::: moniker range=" [!div class="nextstepaction"] > [Configure Python](customize-python.md) + +> [!div class="nextstepaction"] +> [Use CI/CD to deploy a Python web app to Azure App Service](python-webapp.md). + diff --git a/docs/pipelines/ecosystems/ruby.md b/docs/pipelines/ecosystems/ruby.md index 7d9ddd6a26f..340402d29bb 100644 --- a/docs/pipelines/ecosystems/ruby.md +++ b/docs/pipelines/ecosystems/ruby.md @@ -6,7 +6,7 @@ ms.assetid: 61052605-ec85-45ca-b57e-8664cd41c0ea ms.author: vijayma author: vijayma ms.reviewer: dastahel -ms.custom: seodec18, freshness-fy22q2, kr2b-contr-experiment +ms.custom: freshness-fy22q2, kr2b-contr-experiment ms.date: 01/20/2022 monikerRange: azure-devops --- diff --git a/docs/pipelines/ecosystems/xamarin.md b/docs/pipelines/ecosystems/xamarin.md deleted file mode 100644 index 887ad1084b7..00000000000 --- a/docs/pipelines/ecosystems/xamarin.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: Build Xamarin apps -description: Learn how to build a pipeline that deploys a Xamarin app for automated builds. -ms.topic: quickstart -ms.assetid: 2bf80a9f-3f37-4582-8226-4a1d7e519265 -ms.reviewer: dastahel -ms.custom: seodec18,contperf-fy21q2, freshness-fy22q2 -ms.date: 12/28/2021 -monikerRange: 'azure-devops' -# Customer intent: As an Azure DevOps user, I want to build a pipeline that deploys a Xamarin app so that I can take advantage of automated builds. ---- - -# Build and deploy Xamarin apps with a pipeline - -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -Get started with [Xamarin](https://dotnet.microsoft.com/apps/xamarin) and Azure Pipelines by using a pipeline to deploy a Xamarin app. You can deploy Android and iOS apps in the same or separate pipelines. - -## Prerequisites - -Have the following items: - -- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). -- An active Azure DevOps organization. [Sign up for Azure Pipelines](../get-started/pipelines-sign-up.md). - -### Get code - -[!INCLUDE [include](includes/get-code-before-sample-repo.md)] - -``` -https://github.com/MicrosoftDocs/pipelines-xamarin -``` - -This sample is the `FirstApp` sample from the `https://github.com/xamarin/xamarin-forms-samples` repository. For more information on getting started with Xamarin, see [Build your first Xamarin.Forms App](/xamarin/get-started/first-app/?pivots=windows). - -## Sign in to Azure Pipelines - -[!INCLUDE [include](includes/sign-in-azure-pipelines.md)] - -[!INCLUDE [include](includes/create-project.md)] - -### Create the pipeline - -[!INCLUDE [include](includes/create-pipeline-before-template-selected.md)] - -7. On the **Configure** tab, select **Xamarin.Android** to build an Android project or **Xamarin.iOS** to build an iOS project. If you want to use the included sample `.yml` files, choose **Existing Azure Pipelines YAML file** and choose from one of the included sample pipelines (Android, iOS, or a combined pipeline that builds both). - -8. When your new pipeline appears, take a look at the YAML to see what it does. When you're ready, select **Save and run**. - - > [!div class="mx-imgBorder"] - > ![Save and run button in a new YAML pipeline](media/save-and-run-button-new-yaml-pipeline.png) - -9. If you created a new YAML file, commit a new _azure-pipelines.yml_ file to your repository. After you're happy with the message, select **Save and run** again. - - If you want to watch your pipeline in action, select the build job. - You now have a working YAML pipeline (`azure-pipelines.yml`) in your repository that's ready for you to customize! - -10. When you're ready to make changes to your pipeline, select it in the **Pipelines** page, and then **Edit** the `azure-pipelines.yml` file. - -Read further to learn some of the more common ways to customize your pipeline. - - -## Set up Xamarin tools - -You can use Azure Pipelines to build your Xamarin apps without setting up your own infrastructure. Xamarin tools are preinstalled on [Microsoft-hosted agents](../agents/hosted.md) in Azure Pipelines. You can use macOS or Windows agents to run Xamarin.Android builds, and macOS agents to run Xamarin.iOS builds. If you're using a self-hosted agent, install either of the following tools: -- [Visual Studio Tools for Xamarin](https://visualstudio.microsoft.com/xamarin/) for Windows agents -- [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/) for macOS agents - -For the exact versions of Xamarin that are preinstalled, refer to [Microsoft-hosted agents](../agents/hosted.md#software). - -Create a file named **azure-pipelines.yml** in the root of your repository. Then, add the following snippet to your `azure-pipelines.yml` file to select the appropriate agent pool: - -```yaml -# https://learn.microsoft.com/azure/devops/pipelines/ecosystems/xamarin -pool: - vmImage: 'macOS-10.15' # For Windows, use 'windows-2019' -``` - -## Build a Xamarin.Android app - -To build a Xamarin.Android app, add the following snippet to your `azure-pipelines.yml` file. Change values to match your project configuration. For more information about options, see the [Xamarin.Android](/azure/devops/pipelines/tasks/reference/xamarin-android-v1) task. - -```yaml -variables: - buildConfiguration: 'Release' - outputDirectory: '$(build.binariesDirectory)/$(buildConfiguration)' - -steps: -- task: NuGetToolInstaller@1 - -- task: NuGetCommand@2 - inputs: - restoreSolution: '**/*.sln' - -- task: XamarinAndroid@1 - inputs: - projectFile: '**/*Droid*.csproj' - outputDirectory: '$(outputDirectory)' - configuration: '$(buildConfiguration)' - msbuildVersionOption: '16.0' -``` - -### Sign a Xamarin.Android app - -For information about signing your app, see [Sign your mobile Android app during CI](../apps/mobile/app-signing.md#sign-your-android-app). - - -## Build a Xamarin.iOS app - -To build a Xamarin.iOS app, add the following snippet to your `azure-pipelines.yml` file. Change values to match your project configuration. For more information about options, see the [Xamarin.iOS](/azure/devops/pipelines/tasks/reference/xamarin-ios-v2) task. - -```yaml -variables: - buildConfiguration: 'Release' - -steps: -- task: XamariniOS@2 - inputs: - solutionFile: '**/*iOS.csproj' - configuration: '$(buildConfiguration)' - packageApp: false - buildForSimulator: true -``` - -### Sign and provision a Xamarin.iOS app - The PackageApp option - -To generate a signed and provisioned Xamarin.iOS app .ipa package, set `packageApp` to `true`. Make sure you already installed the right Apple Provisioning Profile and Apple Certificates that match your App Bundle ID into the agent running the job. - -To fulfill these mandatory requisites, use the Microsoft Provided tasks for [installing an Apple Provisioning Profile](/azure/devops/pipelines/tasks/reference/install-apple-provisioning-profile-v1) and [installing Apple Certificates](/azure/devops/pipelines/tasks/reference/install-apple-certificate-v2). - -```yaml -- task: XamariniOS@2 - inputs: - solutionFile: '**/*iOS.csproj' - configuration: 'AppStore' - packageApp: true -``` -> [!TIP] -> The Xamarin.iOS build task only generates an .ipa package if the agent running the job has the [appropriate provisioning profile and Apple certificate installed](../apps/mobile/app-signing.md?tabs=apple-install-during-build#sign-your-apple-ios-macos-tvos-or-watchos-app). If you enable the packageApp option and the agent doesn't have the appropriate apple provisioning profile(.mobileprovision) and apple certificate(.p12) the build may succeed, but the .ipa isn't generated. - -For Microsoft Hosted agents, the .ipa package is by default located under the following path: -`{iOS.csproj root}/bin/{Configuration}/{iPhone/iPhoneSimulator}/` - -You can configure the output path by adding an argument to the Xamarin.iOS task: - -# [YAML](#tab/yaml) -```yaml -- task: XamariniOS@2 - inputs: - solutionFile: '**/*iOS.csproj' - configuration: 'AppStore' - packageApp: true - args: /p:IpaPackageDir="/Users/vsts/agent/2.153.2/work/1/a" -``` - -This example locates the .ipa in the Build Artifact Staging Directory. It's ready to get pushed into Azure DevOps as an artifact to each build run. To push it into Azure DevOps, add a [Publish Artifact task](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) to the end of your pipeline. - -For more information about signing and provisioning your iOS app, -see [Sign your mobile iOS app during CI](../apps/mobile/app-signing.md?tabs=apple-install-during-build#sign-your-apple-ios-macos-tvos-or-watchos-app). - -### Set the Xamarin SDK version on macOS - -To set a specific Xamarin SDK version to use on the Microsoft-hosted macOS agent pool, add the following snippet before the `XamariniOS` task in your `azure-pipelines.yml` file. For details on properly formatting the version number (shown as **5_4_1** below), see [How can I manually select versions of tools on the Hosted macOS agent?](../agents/hosted.md#how-can-i-manually-select-versions-of-tools-on-the-hosted-macos-agent). - -```yaml -- script: sudo $AGENT_HOMEDIRECTORY/scripts/select-xamarin-sdk.sh 5_4_1 - displayName: 'Select Xamarin SDK version' -``` - -## Build Xamarin.Android and Xamarin.iOS apps with one pipeline - -You can build and test your Xamarin.Android app, Xamarin.iOS app, and related apps in the same pipeline by defining multiple [jobs](../process/phases.md) in `azure-pipelines.yml`. These jobs can run in parallel to save time. The following complete example builds a Xamarin.Android app on Windows, and a Xamarin.iOS app on macOS, using two jobs. - -```yaml -# Xamarin.Android and Xamarin.iOS -# Build a Xamarin.Android and Xamarin.iOS app. -# Add steps that test, sign, and distribute the app, save build artifacts, and more: -# https://learn.microsoft.com/azure/devops/pipelines/ecosystems/xamarin - -jobs: - -- job: Android - pool: - vmImage: 'windows-2019' - - variables: - buildConfiguration: 'Release' - outputDirectory: '$(build.binariesDirectory)/$(buildConfiguration)' - - steps: - - task: NuGetToolInstaller@1 - - - task: NuGetCommand@2 - inputs: - restoreSolution: '**/*.sln' - - - task: XamarinAndroid@1 - inputs: - projectFile: '**/*droid*.csproj' - outputDirectory: '$(outputDirectory)' - configuration: '$(buildConfiguration)' - msbuildVersionOption: '16.0' - - - task: AndroidSigning@3 - inputs: - apksign: false - zipalign: false - apkFiles: '$(outputDirectory)/*.apk' - - - task: PublishBuildArtifacts@1 - inputs: - pathtoPublish: '$(outputDirectory)' - -- job: iOS - pool: - vmImage: 'macOS-10.15' - - steps: - # To manually select a Xamarin SDK version on the Hosted macOS agent, enable this script with the SDK version you want to target - # https://go.microsoft.com/fwlink/?linkid=871629 - - script: sudo $AGENT_HOMEDIRECTORY/scripts/select-xamarin-sdk.sh 5_4_1 - displayName: 'Select Xamarin SDK version' - enabled: false - - - task: NuGetToolInstaller@1 - - - task: NuGetCommand@2 - inputs: - restoreSolution: '**/*.sln' - - - task: XamariniOS@2 - inputs: - solutionFile: '**/*.sln' - configuration: 'Release' - buildForSimulator: true - packageApp: false -``` - -# [Classic](#tab/classic) - -Expand menu Advanced for the Xamarin.iOS build task and add **/p:IpaPackageDir="/Users/vsts/agent/2.153.2/work/1/a"** in the input field Arguments to place the generated .ipa package in the Build Artifact Staging Directory. To push it into Azure DevOps, add a [Publish Artifact task](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) to the end of your pipeline. - ---- - -## Clean up resources - -If you don't need the example code, delete your GitHub repository and Azure Pipelines project. - -## Next steps - -> [!div class="nextstepaction"] -> [Learn more about using Xcode in pipelines](xcode.md) - -> [!div class="nextstepaction"] -> [Learn more about using Android in pipelines](android.md) diff --git a/docs/pipelines/ecosystems/xcode.md b/docs/pipelines/ecosystems/xcode.md index 0da0ea4dc75..ffc119ffe00 100644 --- a/docs/pipelines/ecosystems/xcode.md +++ b/docs/pipelines/ecosystems/xcode.md @@ -5,7 +5,7 @@ ms.topic: quickstart ms.assetid: e9dd0efb-8932-4a77-93be-28e209d486ca ms.author: vijayma author: vijayma -ms.date: 10/27/2021 +ms.date: 08/12/2024 monikerRange: '<= azure-devops' --- @@ -13,62 +13,41 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Learn how to build and deploy Xcode projects with Azure Pipelines. +This quickstart shows you how to build and deploy Xcode projects with YAML pipelines in Azure Pipelines. ## Prerequisites -* An Xcode 9+ project in a GitHub repository. If you do not have a project, see [Creating an Xcode Project for an App](https://developer.apple.com/documentation/xcode/creating-an-xcode-project-for-an-app) +- An Azure DevOps organization and project where you have permission to create pipelines and deploy apps. +- An Xcode 9+ project and app in a GitHub repository. For more information, see [Creating an Xcode Project for an App](https://developer.apple.com/documentation/xcode/creating-an-xcode-project-for-an-app). ## Create the pipeline -[!INCLUDE [include](includes/create-pipeline-before-template-selected.md)] +>[!IMPORTANT] +>During GitHub procedures, you might be prompted to create a [GitHub service connection](../library/service-endpoints.md#github-service-connection) or be redirected to GitHub to sign in, install Azure Pipelines, or authorize Azure Pipelines. Follow the onscreen instructions to complete the process. For more information, see [Access to GitHub repositories](../repos/github.md#access-to-github-repositories). -> When the **Configure** tab appears, select **Xcode**. +1. In your Azure DevOps project, select **Pipelines** > **New pipeline**, or **Create pipeline** if this pipeline is the first in the project. +1. Select **GitHub** as the location of your source code. +1. On the **Select a repository** screen, select the repository for your Xcode project. +1. On the **Configure your pipeline** screen, select **Xcode**. -7. When your new pipeline appears, take a look at the YAML to see what it does. When you're ready, select **Save and run**. +Azure Pipelines provides a starter pipeline based on the [Xcode](https://github.com/microsoft/azure-pipelines-yaml/blob/master/templates/xcode.yml) template. Review the code in *azure-pipelines.yml*. - > [!div class="mx-imgBorder"] - > ![Save and run button in a new YAML pipeline](media/save-and-run-button-new-yaml-pipeline.png) +### Build environment -8. You're prompted to commit a new _azure-pipelines.yml_ file to your repository. After you're happy with the message, select **Save and run** again. +Xcode is preinstalled on the [Microsoft-hosted macOS agents](../agents/hosted.md) in Azure Pipelines, so you don't have to set up any infrastructure. For the exact versions of Xcode that are preinstalled, see [Microsoft-hosted agents software](../agents/hosted.md#software). - If you want to watch your pipeline in action, select the build job. - - > You just created and ran a pipeline that we automatically created for you, because your code appeared to be a good match for the [Xcode](https://github.com/microsoft/azure-pipelines-yaml/blob/master/templates/xcode.yml) template. - - You now have a working YAML pipeline (`azure-pipelines.yml`) in your repository that's ready for you to customize! - -9. When you're ready to make changes to your pipeline, select it in the **Pipelines** page, and then **Edit** the `azure-pipelines.yml` file. - -See the sections below to learn some of the more common ways to customize your pipeline. - - -> [!Tip] -> To make changes to the YAML file as described in this topic, select the pipeline in **Pipelines** page, and then select **Edit** to open an editor for the `azure-pipelines.yml` file. - - -## Build environment - -You can use Azure Pipelines to build your apps with Xcode without needing to set up any infrastructure of your own. Xcode is preinstalled on [Microsoft-hosted macOS agents](../agents/hosted.md) in Azure Pipelines. You can use the macOS agents to run your builds. - -For the exact versions of Xcode that are preinstalled, refer to [Microsoft-hosted agents](../agents/hosted.md#software). - -Create a file named **azure-pipelines.yml** in the root of your repository. Then, add the following snippet to your `azure-pipelines.yml` file to select the appropriate agent pool: +The `pool` node at the top of your *azure-pipelines.yml* file selects the appropriate agent pool. ```yaml -# https://learn.microsoft.com/azure/devops/pipelines/ecosystems/xcode pool: vmImage: 'macOS-latest' ``` -## Build an app with Xcode +### Xcode build task -To build an app with Xcode, add the following snippet to your `azure-pipelines.yml` file. This is a minimal snippet for building an iOS project using its default scheme, for the Simulator, and without packaging. Change values to match your project configuration. See the [Xcode](/azure/devops/pipelines/tasks/reference/xcode-v5) task for more about these options. +The [Xcode](/azure/devops/pipelines/tasks/reference/xcode-v5) task builds, tests, or archives an Xcode workspace on macOS, and optionally can package an app. The Xcode step in the starter *azure-pipelines.yml* file builds the iOS project using its default scheme, for the Simulator, and without packaging. You can change values and add parameters to match your project configuration. ```yaml -pool: - vmImage: 'macos-latest' - steps: - task: Xcode@5 inputs: @@ -80,24 +59,35 @@ steps: xcodeVersion: 'default' # Options: 10, 11, 12, 13, 14, default, specifyPath ``` -### Signing and provisioning +## Save and run the pipeline + +When you finish reviewing the code in *azure-pipelines.yml*, select **Save and run**. + + :::image type="content" source="media/save-and-run-button-new-yaml-pipeline.png" alt-text="Screenshot of the Save and run button in a new YAML pipeline."::: + +Optionally, edit the **Commit message** and provide a description. Then select **Save and run** again to commit the *azure-pipelines.yml* file to your repository and start a build. -An Xcode app must be signed and provisioned to run on a device or be published to the App Store. The signing and provisioning process needs access to your P12 signing certificate and one or more provisioning profiles. The [Install Apple Certificate](/azure/devops/pipelines/tasks/reference/install-apple-certificate-v2) and [Install Apple Provisioning Profile](/azure/devops/pipelines/tasks/reference/install-apple-provisioning-profile-v1) tasks make these available to Xcode during a build. +The build run page shows build details and progress. If you want to watch your pipeline in action, select **Job** on the lower part of the page. -See [Sign your mobile app](../apps/mobile/app-signing.md) to learn more. +You now have a working YAML pipeline, *azure-pipelines.yml*, in your repository that's ready to customize. -### Carthage +## Customize your pipeline -If your project uses Carthage with a private Carthage repository, -you can set up authentication by setting an environment variable named -`GITHUB_ACCESS_TOKEN` with a value of a token that has access to the repository. -Carthage will automatically detect and use this environment variable. +To make changes to your pipeline, select **Edit** on the pipeline page. The following sections describe some common ways to customize your Xcode pipeline. -Do not add the secret token directly to your pipeline YAML. -Instead, create a new pipeline variable with its lock enabled on the Variables pane to encrypt this value. -See [secret variables](../process/variables.md#secret-variables). +### Add signing and provisioning tasks -Here is an example that uses a secret variable named `myGitHubAccessToken` for the value of the `GITHUB_ACCESS_TOKEN` environment variable. +An Xcode app must be signed and provisioned to be able to run on a device or publish to the App Store. The signing and provisioning process must access your P12 signing certificate and one or more provisioning profiles. For more information, see [Sign your mobile app](../apps/mobile/app-signing.md). + +To make the certificate and profile available to Xcode during a build, add the [Install Apple Certificate](/azure/devops/pipelines/tasks/reference/install-apple-certificate-v2) and [Install Apple Provisioning Profile](/azure/devops/pipelines/tasks/reference/install-apple-provisioning-profile-v1) tasks to your pipeline. + +### Use a Carthage environment variable + +If your project uses Carthage with a private Carthage repository, you can set up authentication by using an environment variable named `GITHUB_ACCESS_TOKEN` with a value of a token that has access to the repository. Carthage automatically detects and uses this environment variable. + +Don't add the secret token directly to your pipeline YAML. Instead, select **Variables** on the pipeline page to open the **Variables** pane and create a variable for this token. Be sure to enable the lock icon to encrypt the value of the variable. For more information, see [Set secret variables](../process/variables.md#secret-variables). + +The following pipeline code uses a secret variable named `myGitHubAccessToken` for the value of the `GITHUB_ACCESS_TOKEN` environment variable. ```yaml - script: carthage update --platform iOS @@ -105,18 +95,36 @@ Here is an example that uses a secret variable named `myGitHubAccessToken` for t GITHUB_ACCESS_TOKEN: $(myGitHubAccessToken) ``` -### Testing on Azure-hosted devices +### Test on Azure-hosted devices + +To test your app in a hosted lab of iOS devices in the Visual Studio App Center, add the [App Center Test](/azure/devops/pipelines/tasks/reference/app-center-test-v1) task to your pipeline. -Add the [App Center Test](/azure/devops/pipelines/tasks/reference/app-center-test-v1) task to test the app in a hosted lab of iOS and Android devices. An [App Center](https://appcenter.ms) free trial is required which must later be converted to paid. +This task requires an [App Center](https://appcenter.ms) free trial account, which must be converted to paid after 30 days to continue to use the test lab. [Sign up for an App Center account](https://appcenter.ms/signup?utm_source=DevOps&utm_medium=Azure&utm_campaign=docs) before you use this task. + +> [!WARNING] +> Visual Studio App Center is scheduled for retirement on March 31, 2025. [Learn more about support timelines and recommended alternatives.](https://aka.ms/appcenter/retire) [Sign up with App Center](https://appcenter.ms/signup?utm_source=DevOps&utm_medium=Azure&utm_campaign=docs) first. -[!INCLUDE [temp](../tasks/includes/yaml/AppCenterTestV1.md)] +The following example runs an App Center test suite. The task uses a [service connection](../library/service-endpoints.md#visual-studio-app-center-service-connection) that you must set up. -### Retain artifacts with the build record +For the complete task syntax and reference, see [App Center Test task](/azure/devops/pipelines/tasks/reference/app-center-test-v1). For more information, see [Using Azure DevOps for UI Testing](/appcenter/test-cloud/vsts-plugin). -Add the [Copy Files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish Build Artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks -to store your IPA with the build record or test and deploy it in subsequent pipelines. See [Artifacts](../artifacts/pipeline-artifacts.md). +```yml +- task: AppCenterTest@1 + inputs: + appFile: path/myapp.ipa + artifactsDirectory: '$(Build.ArtifactStagingDirectory)/AppCenterTest' + frameworkOption: 'appium' + appiumBuildDirectory: test/upload + serverEndpoint: 'My App Center service connection' + appSlug: username/appIdentifier + devices: 'devicelist' +``` + +### Keep artifacts with the build record + +To store your iOS AppStore Package (IPA) file with the build record or test and deploy it in subsequent pipelines, add the [Copy Files](/azure/devops/pipelines/tasks/reference/copy-files-v2) and [Publish Build Artifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) tasks to your pipeline. For more information, see [Publish and download pipeline artifacts](../artifacts/pipeline-artifacts.md). ```yaml - task: CopyFiles@2 @@ -130,63 +138,61 @@ to store your IPA with the build record or test and deploy it in subsequent pipe publishLocation: 'Container' ``` -## Deploy - -### App Center +### Deploy to App Center -Add the [App Center Distribute](/azure/devops/pipelines/tasks/reference/app-center-distribute-v3) task to distribute an app to a group of testers or beta users, -or promote the app to Intune or the Apple App Store. A free [App Center](https://appcenter.ms) account is required (no payment is necessary). +To distribute an app to a group of testers or beta users, or promote the app to Intune or the Apple App Store, add the [App Center Distribute](/azure/devops/pipelines/tasks/reference/app-center-distribute-v3) task. The task requires a free [App Center](https://appcenter.ms) account that remains free of charge. -[!INCLUDE [temp](../tasks/includes/yaml/AppCenterDistributeV1.md)] +The following example distributes an app to users. For the complete task syntax and reference, see [App Center Distribute](/azure/devops/pipelines/tasks/reference/app-center-distribute-v3). For more information, see [Deploy Azure DevOps Builds with App Center](/appcenter/distribution/vsts-deploy). -### Apple App Store +```yml +- task: AppCenterDistribute@3 + inputs: + serverEndpoint: 'AppCenter' + appSlug: '$(APP_CENTER_SLUG)' + appFile: '$(APP_FILE)' # Relative path from the repo root to the IPA file you want to publish + symbolsOption: 'Apple' + releaseNotesOption: 'input' + releaseNotesInput: 'Here are the release notes for this version.' + destinationType: 'groups' +``` -Install the [Apple App Store extension](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store) -and use the following tasks to automate interaction with the App Store. By default, these tasks authenticate to Apple -using a [service connection](..//library/service-endpoints.md) that you configure. +### Install the Apple App Store extension and deploy to Apple App Store -#### Release +To automate interaction with the Apple App Store, install the [Apple App Store extension](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store), and then use the following tasks in your pipeline. By default, these tasks authenticate to Apple by using a [service connection](..//library/service-endpoints.md) that you must configure. -Add the [App Store Release](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store#user-content-app-store-release) -task to automate the release of updates to existing iOS TestFlight beta apps or production apps in the App Store. +To automate the release of updates to existing iOS TestFlight beta apps or production apps in the App Store, add the [App Store Release](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store#:~:text=the%20App%20Store.-,App%20Store%20Release) task. -See [limitations](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store) -of using this task with Apple two-factor authentication, -since Apple authentication is region-specific and -fastlane session tokens expire quickly and must be recreated and reconfigured. +There are limitations of using this task with [Apple two-factor authentication](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store#:~:text=or%20release%20pipeline.-,Two%2DFactor%20Authentication). Apple authentication is region-specific, and fastlane session tokens expire quickly and must be recreated and reconfigured. ```yaml - task: AppStoreRelease@1 displayName: 'Publish to the App Store TestFlight track' inputs: - serviceEndpoint: 'My Apple App Store service connection' # This service connection must be added by you + serviceEndpoint: 'My Apple App Store service connection' appIdentifier: com.yourorganization.testapplication.etc ipaPath: '$(build.artifactstagingdirectory)/**/*.ipa' shouldSkipWaitingForProcessing: true shouldSkipSubmission: true ``` -#### Promote - -Add the [App Store Promote](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store#user-content-app-store-promote) -task to automate the promotion of a previously submitted app from iTunes Connect to the App Store. +To automate the promotion of a previously submitted app from iTunes Connect to the App Store, add the [App Store Promote](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store#:~:text=true%0A%20%20%20%20appSpecificId%3A%20%271234567890%27-,App%20Store%20Promote) task. ```yaml - task: AppStorePromote@1 displayName: 'Submit to the App Store for review' inputs: - serviceEndpoint: 'My Apple App Store service connection' # This service connection must be added by you + serviceEndpoint: 'My Apple App Store service connection' appIdentifier: com.yourorganization.testapplication.etc shouldAutoRelease: false ``` ## Related extensions -- [Apple App Store](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store) (Microsoft) -- [Codified Security](https://marketplace.visualstudio.com/items?itemName=codifiedsecurity.CodifiedSecurity) (Codified Security) -- [MacinCloud](https://marketplace.visualstudio.com/items?itemName=moboware.macincloud) (Moboware Inc.) -- [Mobile App Tasks for iOS and Android](https://marketplace.visualstudio.com/items?itemName=vs-publisher-473885.motz-mobile-buildtasks) (James Montemagno) -- [Mobile Testing Lab](https://marketplace.visualstudio.com/items?itemName=Perfecto.PerfectoCQ) (Perfecto Mobile) -- [Raygun](https://marketplace.visualstudio.com/items?itemName=Raygun.vsts-extension) (Raygun) -- [React Native](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.react-native-extension) (Microsoft) -- [Version Setter](https://marketplace.visualstudio.com/items?itemName=tomgilder.version-setter) (Tom Gilder) +- [Apple App Store](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store) from Microsoft +- [Codified Security](https://marketplace.visualstudio.com/items?itemName=codifiedsecurity.CodifiedSecurity) from Codified Security +- [MacinCloud](https://marketplace.visualstudio.com/items?itemName=moboware.macincloud) from Moboware Inc. +- [Mobile App Tasks for iOS and Android](https://marketplace.visualstudio.com/items?itemName=vs-publisher-473885.motz-mobile-buildtasks) from James Montemagno +- [Mobile Testing Lab](https://marketplace.visualstudio.com/items?itemName=Perfecto.PerfectoCQ) from Perfecto Mobile +- [Raygun](https://marketplace.visualstudio.com/items?itemName=Raygun.vsts-extension) from Raygun +- [React Native](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.react-native-extension) from Microsoft +- [Version Setter](https://marketplace.visualstudio.com/items?itemName=tomgilder.version-setter) from Tom Gilder diff --git a/docs/pipelines/get-started-multiplatform.md b/docs/pipelines/get-started-multiplatform.md deleted file mode 100644 index dedd33a9711..00000000000 --- a/docs/pipelines/get-started-multiplatform.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -title: Create a multi-platform pipeline -ms.custom: seodec18 -description: Build and test on macOS, Linux, and Windows -ms.topic: quickstart -ms.assetid: 4aaa98c7-f363-4fe6-b9dd-158108955e38 -ms.author: sdanie -author: steved0x -ms.date: 05/11/2020 -monikerRange: '>= azure-devops-2020' ---- - -# Create a multi-platform pipeline - -[!INCLUDE [version-gt-eq-2020](../includes/version-gt-eq-2020.md)] - -This is a step-by-step guide to using Azure Pipelines to build on macOS, Linux, and Windows. - -## Prerequisites - -[!INCLUDE [include](includes/prerequisites.md)] - -## Get the sample code - -You can use Azure Pipelines to build an app on written in any language, on multiple platforms at the same time. - -1. Go to https://github.com/Azure-Samples/js-e2e-express-server. - -1. Fork the repo into your own GitHub account. - -You should now have a sample app in your GitHub account. - -## Add a pipeline - -In the sample repo, there's no pipeline yet. -You're going to add jobs that run on three platforms. - -1. Go to your fork of the sample code on GitHub. - -1. Choose 'Create new file'. Name the file `azure-pipelines.yml`, and give it the contents below. - -```yaml -# Build NodeJS Express app using Azure Pipelines -# https://learn.microsoft.com/azure/devops/pipelines/ecosystems/javascript?view=azure-devops -strategy: - matrix: - linux: - imageName: 'ubuntu-latest' - mac: - imageName: 'macOS-latest' - windows: - imageName: 'windows-latest' - -pool: - vmImage: $(imageName) - -steps: -- task: NodeTool@0 - inputs: - versionSpec: '8.x' - -- script: | - npm install - npm test - -- task: PublishTestResults@2 - inputs: - testResultsFiles: '**/TEST-RESULTS.xml' - testRunTitle: 'Test results for JavaScript' - -- task: PublishCodeCoverageResults@1 - inputs: - codeCoverageTool: Cobertura - summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml' - reportDirectory: '$(System.DefaultWorkingDirectory)/**/coverage' - -- task: ArchiveFiles@2 - inputs: - rootFolderOrFile: '$(System.DefaultWorkingDirectory)' - includeRootFolder: false - -- task: PublishBuildArtifacts@1 -``` - -At the bottom of the GitHub editor, select **Commit changes**. - -Each job in this example runs on a different VM image. -By default, the jobs run at the same time in parallel. - -Note: `script` runs in each platform's native script interpreter: Bash on macOS and Linux, CMD on Windows. -See [multi-platform scripts](scripts/cross-platform-scripting.md) to learn more. - -## Create the pipeline - -Now that you've configured your GitHub repo with a pipeline, you're ready to build it. - -1. Sign in to your Azure DevOps organization and navigate to your project. - -1. In your project, go to the **Pipelines** page, and then select **New pipeline**. - -1. Select **GitHub** as the location of your source code. - - ![Select GitHub](media/get-started-yaml/new-pipeline.png) - -1. For **Repository**, select **Authorize** and then **Authorize with OAuth**. - -1. You might be redirected to GitHub to sign in. If this happens, then enter your GitHub credentials. After you're redirected back to Azure Pipelines, select the **sample app** repository. - -1. For the **Template**, Azure Pipelines analyzes the code in your repository. If your repository already contains an `azure-pipelines.yml` file (as in this case), then this step is skipped. Otherwise, Azure Pipelines recommends a starter template based on the code in your repository. - -1. Azure Pipelines shows you the YAML file that it will use to create your pipeline. - -1. Select **Save and run**, and then select the option to **Commit directly to the main branch**. - -1. The YAML file is pushed to your GitHub repository, and a new build is automatically started. Wait for the build to finish. - -## FAQ - -### Can I build my multi-platform pipeline on both self-hosted and Microsoft-hosted agents? - -You can, you would need to specify both a `vmImage` and a `Pool` variable, like the following example. For the hosted agent, specify `Azure Pipelines` as the pool name, and for self-hosted agents, leave the `vmImage` blank. The blank `vmImage` for the self-hosted agent may result in some unusual entries in the logs but they won't affect the pipeline. - -```yml -strategy: - matrix: - microsofthosted: - poolName: Azure Pipelines - vmImage: ubuntu-latest - - selfhosted: - poolName: FabrikamPool - vmImage: - -pool: - name: $(poolName) - vmImage: $(vmImage) - -steps: -- checkout: none -- script: echo test -``` - -## Next steps - -You've just learned the basics of using multiple platforms with Azure Pipelines. From here, you can learn more about: - -* [Jobs](process/phases.md?tabs=yaml) -* [Cross-platform scripting](scripts/cross-platform-scripting.md) -* [Templates](process/templates.md) to remove the duplication -* Building [Node.js](ecosystems/javascript.md) apps -* Building [.NET Core](ecosystems/dotnet-core.md), [Go](ecosystems/go.md), [Java](ecosystems/java.md), or [Python](ecosystems/python.md) apps - -For details about building GitHub repositories, see [Build GitHub repositories](repos/github.md). diff --git a/docs/pipelines/get-started/clone-import-pipeline.md b/docs/pipelines/get-started/clone-import-pipeline.md index 4a7abb5044c..9ceacdfecce 100644 --- a/docs/pipelines/get-started/clone-import-pipeline.md +++ b/docs/pipelines/get-started/clone-import-pipeline.md @@ -2,7 +2,7 @@ title: Clone or import a pipeline description: Create a pipeline by cloning or importing an existing pipeline ms.topic: conceptual -ms.date: 12/20/2022 +ms.date: 11/01/2023 monikerRange: '<= azure-devops' --- @@ -12,6 +12,8 @@ monikerRange: '<= azure-devops' One approach to creating a pipeline is to copy an existing pipeline and use it as a starting point. For YAML pipelines, the process is as easy as copying the YAML from one pipeline to another. For pipelines created in the classic editor, the procedure depends on whether the pipeline to copy is in the same project as the new pipeline. If the pipeline to copy is in the same project, you can clone it, and if it is in a different project you can export it from that project and import it into your project. +Cloning a classic pipeline also clones its settings, such as variables, triggers, and options. Security settings aren't cloned. Cloning a YAML pipeline only copies the YAML content, and you need to reconfigure any other settings. + :::moniker range="azure-devops" For information in migrating a classic build pipeline to YAML using **Export to YAML**, see [Migrate from classic pipelines](../migrate/from-classic-pipelines.md). @@ -22,70 +24,50 @@ For information in migrating a classic build pipeline to YAML using **Export to #### [YAML](#tab/yaml/) -:::moniker range=">= azure-devops-2019" +:::moniker range="<=azure-devops" For YAML pipelines, the process for cloning is to copy the YAML from the source pipeline and use it as the basis for the new pipeline. :::moniker-end -:::moniker range="azure-devops-2019" - -1. Navigate to your pipeline, and choose **Edit**. - - :::image type="content" source="media/pipeline-details-2019.png" alt-text="Pipeline details in Azure DevOps Server 2019"::: - -2. Copy the pipeline YAML from the editor, and paste it into the YAML editor for your new pipeline. - -3. To customize your newly cloned pipeline, see [Customize your pipeline](../customize-pipeline.md). - -:::moniker-end - -:::moniker range="> azure-devops-2019" +:::moniker range="> azure-devops-2020" 1. [Go](../create-first-pipeline.md#view-and-manage-your-pipelines) to the [pipeline details](../create-first-pipeline.md#view-pipeline-details) for your pipeline, and choose **Edit**. :::image type="content" source="media/pipeline-edit.png" alt-text="Edit pipeline."::: +1. Copy the pipeline YAML from the editor, and paste it into the YAML editor for your new pipeline. -2. Copy the pipeline YAML from the editor, and paste it into the YAML editor for your new pipeline. + > [!NOTE] + > When copying from a classic pipeline, select the agent job, **View YAML**, **Copy to clipboard**, then paste to the YAML editor for your new pipeline. You can repeat these actions for each job in the pipeline. -3. To customize your newly cloned pipeline, see [Customize your pipeline](../customize-pipeline.md). +1. To customize your newly cloned pipeline, see [Customize your pipeline](../customize-pipeline.md). :::moniker-end -:::moniker range="< azure-devops-2019" - -This version of TFS doesn't support YAML pipelines. - -:::moniker-end +> [!NOTE] +> When cloning a YAML pipeline, only the YAML content is copied. You need to reconfigure any other settings defined outside the scope of the YAML content, such as variables, triggers, security, and other settings. #### [Classic](#tab/classic/) If your new pipeline can be created by copying another classic pipeline in the same project, follow the instructions in this section. If your pipeline is in another project, you can use [import/export](#export-and-import-a-pipeline) to copy the pipeline. -You need `Edit release pipeline` or `Edit build pipeline` permissions to clone a Classic pipeline. +You need `Edit release pipeline` or `Create build pipeline` permissions to clone a Classic pipeline. -:::moniker range=">= azure-devops-2019" +:::moniker range="<=azure-devops" 1. Navigate to the pipeline details page for your pipeline. -2. Choose **...** and select **Clone**. +1. Choose **...** and select **Clone**. ![Clone pipeline menu](../media/get-started-designer/clone-pipeline.png) -3. Your pipeline is cloned with **-clone** appended to the name. Choose **Save** or **Save & queue** to save the cloned pipeline. +1. Your pipeline is cloned with **-clone** appended to the name. Choose **Save** or **Save & queue** to save the cloned pipeline. > [!NOTE] > The **Clone** entry is only present on the context menu if your pipeline was created in the classic editor. -:::moniker-end - -:::moniker range="< azure-devops-2019" - -1. To clone a build definition, navigate to **Build Definitions** on the **Builds** hub, choose **...** beside the desired build definition, and choose **Clone**. - - :::image type="content" source="media/clone-build-definition-tfs-2018.png" alt-text="Clone a build definition in TFS 2018."::: - -2. Your pipeline is cloned with **-clone** appended to the name. Choose **Save** or **Save & queue** to save the cloned pipeline. +> [!IMPORTANT] +> Security settings aren't cloned. You must reconfigure security settings for the cloned pipeline. :::moniker-end @@ -97,39 +79,21 @@ You can create a new classic pipeline by exporting an existing one and then impo #### [YAML](#tab/yaml/) -:::moniker range=">= azure-devops-2019" +:::moniker range="<=azure-devops" -In a YAML pipeline, exporting from one project and importing into another is the same process as cloning. You can simply copy the pipeline YAML from the editor and paste it into the YAML editor for your new pipeline. +In a YAML pipeline, exporting from one project and importing into another is the same process as cloning. You can copy the pipeline YAML from the editor and paste it into the YAML editor for your new pipeline. :::moniker-end -:::moniker range="azure-devops-2019" - -1. Navigate to your pipeline, and choose **Edit**. - - :::image type="content" source="media/pipeline-details-2019.png" alt-text="Pipeline details in Azure DevOps Server 2019"::: - -2. Copy the pipeline YAML from the editor, and paste it into the YAML editor for your new pipeline. - -3. To customize your newly cloned pipeline, see [Customize your pipeline](../customize-pipeline.md). - -:::moniker-end - -:::moniker range="> azure-devops-2019" +:::moniker range="<=azure-devops" 1. [Go](../create-first-pipeline.md#view-and-manage-your-pipelines) to the [pipeline details](../create-first-pipeline.md#view-pipeline-details) for your pipeline, and choose **Edit**. :::image type="content" source="media/pipeline-edit.png" alt-text="Edit pipeline."::: -2. Copy the pipeline YAML from the editor, and paste it into the YAML editor for your new pipeline. +1. Copy the pipeline YAML from the editor, and paste it into the YAML editor for your new pipeline. -3. To customize your newly cloned pipeline, see [Customize your pipeline](../customize-pipeline.md). - -:::moniker-end - -:::moniker range="< azure-devops-2019" - -This version of TFS doesn't support YAML pipelines. +1. To customize your newly cloned pipeline, see [Customize your pipeline](../customize-pipeline.md). :::moniker-end @@ -143,69 +107,57 @@ To copy a build definition from another project, you can export an existing defi 1. Navigate to the pipeline details page for your pipeline. -2. Choose **...** and select **Export to JSON**. +1. Choose **...** and select **Export to JSON**. > [!div class="mx-imgBorder"] > ![Export build pipeline](media/export-classic-pipeline.png) -3. When prompted, save the JSON file on your local machine. The browser will save the file in the download directory as per your browser settings. +1. When prompted, save the JSON file on your local machine. The browser saves the file in the download directory as per your browser settings. -4. To import the pipeline, navigate to the **Pipelines** page in your project. Choose **...**, select **Import a pipeline**, and select the corresponding import pipeline option. +1. To import the pipeline, navigate to the **Pipelines** page in your project. Choose **...**, select **Import a pipeline**, and select the corresponding import pipeline option. -5. You will now be prompted to select a JSON file to import its contents. Browse to and select the JSON file that you previously exported. +1. Browse to and select the JSON file that you previously exported. -6. After import is complete, you will be shown the new pipeline that is created. Note that exporting a pipeline strips any project specific data like agent pools, service connections etc. You will have to once again provide these details. +1. After import is complete, you'll be shown the new pipeline that is created. Exporting a pipeline strips any project specific data like agent pools, service connections, etc. You have to once again provide these details. > [!NOTE] > The **Export** item is only present on the context menu if your pipeline was created in the classic editor. ### Release pipeline -The procedure for exporting and importing a classic release pipeline is very similar to the classic build pipeline procedure, but the menus and UI are slightly different. +The procedure for exporting and importing a classic release pipeline is similar to the classic build pipeline procedure, but the menus and UI are slightly different. 1. To export a classic release pipeline, navigate to **Releases**, choose **...**, and select **Export**. > [!div class="mx-imgBorder"] > ![Export release pipeline](media/classic-export-definition.png) -2. To import a classic release pipeline, navigate to **Releases**, choose **+New**, and select **Import release pipeline**. +1. To import a classic release pipeline, navigate to **Releases**, choose **+New**, and select **Import release pipeline**. > [!div class="mx-imgBorder"] > ![Import release pipeline](media/classic-import-pipeline.png) :::moniker-end -:::moniker range="tfs-2018" - -To export a build definition, navigate to **Build Definitions** on the **Builds** hub, choose **...** beside the desired build definition, choose **Export**, and download the .json file that contains the build definition. - -:::image type="content" source="media/export-build-definition-tfs-2018.png" alt-text="Export a build definition in TFS 2018."::: - -To import a build definition, choose **+Import** from the **Build Definitions** page, and select the .json file saved from the previous step. - -:::image type="content" source="media/import-build-definition-tfs-2018.png" alt-text="Import a build definition in TFS 2018."::: - -:::moniker-end - -:::moniker range=">= azure-devops-2019 <= azure-devops-2020" +:::moniker range="=azure-devops-2020" 1. Navigate to the pipeline details page for your pipeline. -2. Choose **...** and select **Export**. +1. Choose **...** and select **Export**. > [!div class="mx-imgBorder"] > ![Export pipeline menu](media/classic-export-definition.png) -3. When prompted, save the JSON file on your local machine. The browser will save the file in the download directory as per your browser settings. +1. When prompted, save the JSON file on your local machine. The browser saves the file in the download directory as per your browser settings. -4. To import the pipeline, navigate to the **Builds** or **Releases** page in your project. Choose **+New** and select the corresponding import pipeline option. +1. To import the pipeline, navigate to the **Builds** or **Releases** page in your project. Choose **+New** and select the corresponding import pipeline option. > [!div class="mx-imgBorder"] > ![Import pipeline menu](media/classic-import-pipeline.png) -5. You will now be prompted to select a JSON file to import its contents. Browse to and select the JSON file that you previously exported. +1. Browse to and select the JSON file that you previously exported. -7. After import is complete, you will be shown the new pipeline that is created. Note that exporting a pipeline strips any project specific data like agent pools, service connections etc. You will have to once again provide these details. +1. After import is complete, you'll be shown the new pipeline that is created. Exporting a pipeline strips any project specific data like agent pools, service connections, etc. You have to once again provide these details. > [!NOTE] > The **Export** item is only present on the context menu if your pipeline was created in the classic editor. @@ -216,4 +168,4 @@ To import a build definition, choose **+Import** from the **Build Definitions** ## Next steps -Learn to [customize the pipeline](../customize-pipeline.md) you just cloned or imported. +Learn to [customize the pipeline](../customize-pipeline.md) you cloned or imported. diff --git a/docs/pipelines/get-started/key-pipelines-concepts.md b/docs/pipelines/get-started/key-pipelines-concepts.md index 9a603e6feaf..69e0d1d96c0 100644 --- a/docs/pipelines/get-started/key-pipelines-concepts.md +++ b/docs/pipelines/get-started/key-pipelines-concepts.md @@ -1,9 +1,8 @@ --- title: Azure Pipelines New User Guide - Key concepts -ms.custom: seodec18 description: Learn how Azure Pipelines works with your code and tools to automate build and deployment, and the key concepts behind it. ms.topic: overview -ms.date: 12/20/2022 +ms.date: 02/20/2024 monikerRange: 'azure-devops' --- @@ -11,22 +10,21 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Learn about the key concepts and components that make up a pipeline. Understanding the basic terms and parts of a pipeline can help you deliver better code more efficiently and reliably. -
      -> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWMlMo] +Learn about the key concepts and components that make up Azure Pipelines. Understanding the basic terms and parts of a pipeline can help you more effectively build, test, and deploy your code. +> [!VIDEO https://learn-video.azurefd.net/vod/player?id=20e737aa-cadc-4603-9685-3816085087e9] **Key concepts overview** ![key concepts graphic](media/key-concepts-overview.svg) -- A [trigger](#trigger) tells a Pipeline to run. +- A [trigger](#trigger) tells a pipeline to run. - A [pipeline](#pipeline) is made up of one or more [stages](#stage). A pipeline can deploy to one or more [environments](#environment). - A [stage](#stage) is a way of organizing [jobs](#job) in a pipeline and each stage can have one or more jobs. -- Each [job](#job) runs on one [agent](#agent). A job can also be agentless. +- Each [job](#job) runs on one [agent](#agent). A job can also be agentless. - Each [agent](#agent) runs a job that contains one or more [steps](#step). - A [step](#step) can be a [task](#task) or [script](#script) and is the smallest building block of a pipeline. -- A [task](#task) is a pre-packaged script that performs an action, such as invoking a REST API or publishing a build artifact. +- A [task](#task) is a prepackaged script that performs an action, such as invoking a REST API or publishing a build artifact. - An [artifact](#artifact) is a collection of files or packages published by a [run](#run). **Azure Pipelines terms** @@ -39,7 +37,7 @@ For more in-depth information about the different types of agents and how to use ## Approvals -[Approvals](../process/approvals.md) define a set of validations required before a deployment runs. Manual approval is a common check performed to control deployments to production environments. When checks are configured on an environment, pipelines will stop before starting a stage that deploys to the environment until all the checks are completed successfully. +[Approvals](../process/approvals.md) define a set of validations required before a deployment runs. Manual approval is a common check performed to control deployments to production environments. When checks are configured on an environment, a pipeline run pauses until all the checks are completed successfully. ## Artifact @@ -55,9 +53,9 @@ Continuous integration (CI) is the practice used by development teams to ## Deployment -For Classic pipelines, a deployment is the action of running the tasks for one stage, which can include running automated tests, deploying build artifacts, and any other actions are specified for that stage. +A classic pipeline deployment is the action of running the tasks for one stage. The deployment can include running automated tests, deploying build artifacts, and any other actions are specified for that stage. -For YAML pipelines, a deployment typically refers to a [deployment job](../process/deployment-jobs.md). A deployment job is a collection of steps that are run sequentially against an environment. You can use strategies like run once, rolling, and canary for deployment jobs. +For YAML pipelines, a deployment refers to a [deployment job](../process/deployment-jobs.md). A deployment job is a collection of steps that are run sequentially against an environment. You can use strategies like run once, rolling, and canary for deployment jobs. ## Deployment group @@ -65,30 +63,32 @@ A deployment group is a set of deployment target machines that have agents insta ## Environment -An [environment](../process/environments.md) is a collection of resources, where you deploy your application. It can contain one or more virtual machines, containers, web apps, or any service that's used to host the application being developed. A pipeline might deploy the app to one or more environments after build is completed and tests are run. +An [environment](../process/environments.md) is a collection of resources where you deploy your application. One environment can contain one or more virtual machines, containers, web apps, or any service. Pipelines deploy to one or more environments after a build is completed and tests are run. ## Job A stage contains one or more [jobs](../process/phases.md). Each job runs on an agent. A job represents an execution boundary of a set of steps. All of the steps run together on the same agent. Jobs are most useful when you want to run a series of steps in different environments. For example, you might want to build two configurations - x86 and x64. In this case, you have one stage and two jobs. One job would be for x86 and the other job would be for x64. +Agentless jobs run in Azure DevOps and Azure DevOps Server without using an agent. A [limited number of tasks](../process/phases.md#agentless-jobs-supported-tasks) support agentless jobs. + ## Pipeline A pipeline defines the continuous integration and deployment process for your app. It's made up of one or more stages. It can be thought of as a workflow that defines how your test, build, and deployment steps are run. -For Classic pipelines, a pipeline can also be referred to as a definition. +For classic pipelines, a pipeline can also be referred to as a definition. ## Release -For Classic pipelines, a [release](../release/releases.md) is a versioned set of artifacts specified in a pipeline. The release includes a snapshot of all the information required to carry out all the tasks and actions in the release pipeline, such as stages, tasks, policies such as triggers and approvers, and deployment options. You can create a release manually, with a deployment trigger, or with the REST API. +For classic pipelines, a [release](../release/releases.md) is a versioned set of artifacts specified in a pipeline. The release includes a snapshot of all the information required to carry out all the tasks and actions in the release pipeline, such as stages, tasks, policies such as triggers and approvers, and deployment options. You can create a release manually, with a deployment trigger, or with the REST API. For YAML pipelines, the build and release stages are in one, [multi-stage pipeline](multi-stage-pipelines-experience.md). ## Run -A run represents one execution of a pipeline. It collects the logs associated with running the steps and the results of running tests. During a run, Azure Pipelines will first process the pipeline and then send the run to one or more agents. Each agent will run jobs. Learn more about the [pipeline run sequence](../process/runs.md). +A run represents one execution of a pipeline. It collects the logs associated with running the steps and the results of running tests. During a run, Azure Pipelines will first process the pipeline and then send the run to one or more agents. Each agent runs jobs. Learn more about the [pipeline run sequence](../process/runs.md). -For Classic pipelines, a build represents one execution of a pipeline. +For classic pipelines, a build represents one execution of a pipeline. ## Script @@ -97,14 +97,14 @@ A script runs code as a step in your pipeline using command line, PowerShell, or ## Stage A [stage](../process/stages.md) is a logical boundary in the pipeline. It can be used to mark separation of concerns (for example, Build, QA, and production). Each stage contains one or more jobs. When you define multiple stages in a pipeline, by default, they run one after the other. You can specify the conditions for when a stage runs. -When you are thinking about whether you need a stage, ask yourself: +When you're thinking about whether you need a stage, ask yourself: - Do separate groups manage different parts of this pipeline? For example, you could have a test manager that manages the jobs that relate to testing and a different manager that manages jobs related to production deployment. In this case, it makes sense to have separate stages for testing and production. - Is there a set of [approvals](../process/approvals.md) that are connected to a specific job or set of jobs? If so, you can use stages to break your jobs into logical groups that require approvals. -- Are there jobs that need to run a long time? If you have part of your pipeline that will have an extended run time, it makes sense to divide them into their own stage. +- Are there jobs that need to run a long time? If a job in your pipeline has a long run time, it makes sense to put that job in its own stage. ## Step -A step is the smallest building block of a pipeline. For example, a pipeline might consist of build and test steps. A step can either be a script or a task. A task is simply a pre-created script offered as a convenience to you. To view the available tasks, see the [Build and release tasks](../tasks/index.md) reference. For information on creating custom tasks, see [Create a custom task](../../extend/develop/add-build-task.md). +A step is the smallest building block of a pipeline. For example, a pipeline might consist of build and test steps. A step can either be a script or a task. A task is simply a precreated script offered as a convenience to you. To view the available tasks, see the [Build and release tasks](../tasks/index.md) reference. For information on creating custom tasks, see [Create a custom task](../../extend/develop/add-build-task.md). ## Task @@ -116,7 +116,7 @@ A trigger is something that's set up to tell the pipeline when to run. You can c ## Library -The [Library](../library/index.md) includes **secure files** and **variable groups**. [Secure files](../library/secure-files.md) are a way to store files and share them across pipelines. You may need to save a file at the DevOps level and then use it during build or deployment. In that case, you can save the file within [Library](../library/index.md) and use it when you need it. [Variable groups](../library/variable-groups.md) store values and secrets that you might want to be passed into a YAML pipeline or make available across multiple pipelines. +The [Library](../library/index.md) includes **secure files** and **variable groups**. [Secure files](../library/secure-files.md) are a way to store files and share them across pipelines. For example, you may want to reference the same file for different pipelines. In that case, you can save the file within [Library](../library/index.md) and use it when you need it. [Variable groups](../library/variable-groups.md) store values and secrets that you might want to be passed into a YAML pipeline or make available across multiple pipelines. ### About the authors -- [Dave Jarvis](https://github.com/DaveJarvis) contributed to the key concepts overview graphic. +- Dave Jarvis contributed to the key concepts overview graphic. diff --git a/docs/pipelines/get-started/manage-pipelines-with-azure-cli.md b/docs/pipelines/get-started/manage-pipelines-with-azure-cli.md index deb0710c85d..1b9e4876618 100644 --- a/docs/pipelines/get-started/manage-pipelines-with-azure-cli.md +++ b/docs/pipelines/get-started/manage-pipelines-with-azure-cli.md @@ -1,177 +1,154 @@ --- -title: Manage your pipeline with Azure CLI -titleSuffix: Azure DevOps -description: Use Azure DevOps extension command line interface to manage your pipelines +title: Manage pipelines with the Azure DevOps CLI +description: Learn about the Azure DevOps CLI extension and about the az pipelines list, show, run, and update commands for managing your pipelines. ms.topic: conceptual ms.custom: devx-track-azurecli ms.author: sandrica author: silviuandrica -monikerRange: '>= azure-devops-2020' -ms.date: 11/12/2021 +monikerRange: 'azure-devops' +ms.date: 08/06/2024 --- -# Manage your pipeline with Azure CLI +# Manage pipelines with the Azure DevOps CLI [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -You can manage the pipelines in your organization using these `az pipelines` commands: +This article describes how you can manage existing pipelines in your Azure DevOps project by using the following [az pipelines](/cli/azure/pipelines) commands: -- [az pipelines run](#run-a-pipeline): Run an existing pipeline -- [az pipelines update](#update-a-pipeline): Update an existing pipeline -- [az pipelines show](#show-pipeline): Show the details of an existing pipeline +- [az pipelines list](/cli/azure/pipelines#az-pipelines-list) to list pipelines in a project +- [az pipelines show](/cli/azure/pipelines#az-pipelines-show) to show the details of a pipeline +- [az pipelines run](/cli/azure/pipelines#az-pipelines-run) to run a pipeline +- [az pipelines update](/cli/azure/pipelines#az-pipelines-update) to update a pipeline +- [az pipelines delete](/cli/azure/pipelines#az-pipelines-delete) to delete a pipeline -These commands require either the name or ID of the pipeline you want to manage. You can get the ID of a pipeline using the [az pipelines list](/cli/azure/pipelines#ext-azure-devops-az-pipelines-list) command. +>[!NOTE] +>The Azure DevOps CLI extension is available only for Azure DevOps Services, and doesn't support any version of Azure DevOps Server. -To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). +## Azure DevOps CLI extension -## Run a pipeline +The `az-pipelines` command group is a part of the [DevOps](/cli/azure/service-page/devops) extension to the Azure CLI, which requires Azure CLI version 2.30.0 or higher. The Azure DevOps extension installs automatically the first time you run an `azure pipelines` command. For more information on getting started, see [Get started with Azure DevOps CLI](../../cli/index.md). + +You can also use global Azure CLI parameters, such as `debug`, `help`, `only-show-errors`, `query`, `output`, and `verbose`, in your Azure DevOps CLI commands. The `table` value for the `--output` global parameter presents output in a friendly format. For more information, see [Output formats for Azure CLI commands](/cli/azure/format-output-azure-cli). + +You can set the default Azure DevOps organization for Azure DevOps CLI commands by using `az devops configure --defaults organization=`, or use the `--detect true` parameter to automatically detect the organization. You can configure the default Azure DevOps project by using `az devops configure -d project=`. + +If you don't detect the organization or configure a default organization or project, or pick up the organization and project via `git config`, you must specify the `org` and `project` parameters in each command. + +## List existing pipelines -You can queue (run) an existing pipeline with the [az pipelines run](/cli/azure/pipelines#ext-azure-devops-az-pipelines-run) command. +The `run`, `show`, `update`, and `delete` pipeline commands require either the `name` or `id` of the pipeline you want to manage. If you use `id`, the `name` parameter is ignored. To get a list of project pipelines, including their IDs, use the [az pipelines list](/cli/azure/pipelines#az-pipelines-list) command. You can filter or format the results list by using parameters. + +For example, the following command lists the project pipelines that have names beginning with `python*`, in table format. + +```azurecli +az pipelines list --name python* --output table +``` + +Output: + +```output +ID Path Name Status Default Queue +---- ------ -------------------------- -------- --------------- +17 \ python-sample-vscode-flask disabled Azure Pipelines +24 \ python-sample-get-started enabled Azure Pipelines +``` + +For the complete command reference, see [az pipelines list](/cli/azure/pipelines#az-pipelines-list). + + +## Show details for a pipeline + +To view the details of an existing pipeline, use the [az pipelines show](/cli/azure/pipelines#az-pipelines-show) command. For example, the following command shows the details of the pipeline with the `ID` of `12`, and opens the pipeline summary page in your web browser. ```azurecli -az pipelines run [--branch] - [--commit-id] - [--folder-path] - [--id] - [--name] - [--open] - [--org] - [--project] - [--variables] -``` - -### Parameters - -- **branch**: Name of the branch on which the pipeline run is to be queued, for example, *refs/heads/main*. -- **commit-id**: Commit-id on which the pipeline run is to be queued. -- **folder-path**: Folder path of pipeline. Default is root level folder. -- **id**: Required if **name** is not supplied. ID of the pipeline to queue. -- **name**: Required if **ID** is not supplied, but ignored if **ID** is supplied. Name of the pipeline to queue. -- **open**: Open the pipeline results page in your web browser. -- **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. -- **variables**: Space separated "name=value" pairs for the variables you would like to set. - -### Example - -The following command runs the pipeline named **myGithubname.pipelines-java** in the branch **pipeline** and shows the result in table format. +az pipelines show --id 12 --open +``` + +For the complete command reference, see [az pipelines show](/cli/azure/pipelines#az-pipelines-show). + +## Run a pipeline + +To queue and run an existing pipeline, use the [az pipelines run](/cli/azure/pipelines#az-pipelines-run) command. You can set `parameters` and `variables` to use in the run. + +For example, the following command runs the pipeline with `name` of `myGithubname.pipelines-java` in the `pipeline` branch, sets the value of variable `var1` to `100` for the run, and outputs results in `table` format. ```azurecli -az pipelines run --name myGithubname.pipelines-java --branch pipeline --output table +az pipelines run --name myGithubname.pipelines-java --branch pipeline --variables var1=100 --output table +``` + +Output: -Run ID Number Status Result Pipeline ID Pipeline Name Source Branch Queued Time Reason +```output +Run ID Number Status Result Pipeline ID Pipeline Name Source Branch Queued Time Reason -------- ---------- ---------- -------- ------------- --------------------------- --------------- -------------------------- -------- -123 20200123.2 notStarted 12 myGithubname.pipelines-java pipeline 2020-01-23 11:55:56.633450 manual +123 20200123.2 notStarted 12 myGithubname.pipelines-java pipeline 2020-01-23 11:55:56.633450 manual ``` -## Update a pipeline +For the complete command reference, see [az pipelines run](/cli/azure/pipelines#az-pipelines-run). -You can update an existing pipeline with the [az pipelines update](/cli/azure/pipelines#ext-azure-devops-az-pipelines-update) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). +## Update a pipeline -```azurecli -az pipelines update [--branch] - [--description] - [--id] - [--name] - [--new-folder-path] - [--new-name] - [--org] - [--project] - [--queue-id] - [--yaml-path] -``` - -### Parameters - -- **branch**: Name of the branch on which the pipeline run is to be configured, for example, *refs/heads/main*. -- **description**: New description for the pipeline. -- **id**: Required if **name** is not supplied. ID of the pipeline to update. -- **name**: Required if **ID** is not supplied. Name of the pipeline to update. -- **new-folder-path**: New full path of the folder to which the pipeline is moved, for example, *user1/production_pipelines*. -- **new-name**: New updated name of the pipeline. -- **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. -- **queue-id**: Queue ID of the agent pool where the pipeline needs to run. -- **yaml-path**: Path of the pipeline's yaml file in the repo. - - Global parameters include `debug`, `help`, `only-show-errors`, `query`, `output`, and `verbose`. - -> [!TIP] -> There are also global parameters you can use such as `--output`. -> The `--output` parameter is available for all commands. The **table** value presents output in a friendly format. For more information, see [Output formats for Azure CLI commands](/cli/azure/format-output-azure-cli). - -### Example - -The following command updates the pipeline with the **ID** of 12 with a new name and description and shows the result in table format. +To update an existing pipeline, use the [az pipelines update](/cli/azure/pipelines#az-pipelines-update) command. For example, the following command updates the pipeline with the `id` of `12` with a new name and description, and outputs the result in table format. ```azurecli az pipelines update --id 12 --description "rename pipeline" --new-name updatedname.pipelines-java --output table +``` + +Output: +```output ID Name Status Default Queue ---- -------------------------- -------- ------------------ 12 updatedname.pipelines-java enabled Hosted Ubuntu 1604 ``` -## Show pipeline +For the complete command reference, see [az pipelines update](/cli/azure/pipelines#az-pipelines-update). -You can view the details of an existing pipeline with the [az pipelines show](/cli/azure/pipelines#ext-azure-devops-az-pipelines-show) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). +## Delete a pipeline -```azurecli -az pipelines show [--folder-path] - [--id] - [--name] - [--open] - [--org] - [--project] - [--query-examples] - [--subscription] -``` - -### Parameters - -- **folder-path**: Folder path of pipeline. Default is root level folder. -- **id**: Required if **name** is not supplied. ID of the pipeline to show details. -- **name**: Required if **name** is not supplied, but ignored if **ID** is supplied. Name of the pipeline to show details. -- **open**: Open the pipeline summary page in your web browser. -- **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. -- **query examples**: Recommend a JMESPath string for you. -- **subscription**: Name or ID of subscription. You can configure the default subscription using `az account set -s NAME_OR_ID`. - -#### Example - -The following command shows the details of the pipeline with the **ID** of 12 and returns the result in table format. +To delete a pipeline, run the [az-pipelines-delete](/cli/azure/pipelines#az-pipelines-delete) command. For example, the following command deletes the pipeline with ID of `12`, and doesn't prompt for confirmation. If you don't include the `--yes` parameter, the command prompts for confirmation by default. -```azurecli -az pipelines show --id 12 --output table - -ID Name Status Default Queue ----- -------------------------- -------- ------------------ -12 updatedname.pipelines-java enabled Hosted Ubuntu 1604 +```azurecli +az pipelines delete --id 12 --yes ``` -## Next steps +For the complete command reference, see [az pipelines delete](/cli/azure/pipelines#az-pipelines-delete). + +## Programmatically create and configure pipelines -You can [customize your pipeline](../customize-pipeline.md) or learn more about configuring pipelines in the language of your choice: +To use the Azure DevOps CLI to create a YAML pipeline, see [az pipelines create](/cli/azure/pipelines#az-pipelines-create). To run Azure CLI commands in YAML pipelines, see [Azure DevOps CLI in Azure Pipelines YAML](/azure/devops/cli/azure-devops-cli-in-yaml). -* [.NET Core](../ecosystems/dotnet-core.md) -* [Go](../ecosystems/go.md) -* [Java](../ecosystems/java.md) -* [Node.js](../ecosystems/javascript.md) -* [Python](../ecosystems/python.md) -* [Containers](../ecosystems/containers/build-image.md) +You can create YAML pipelines to build, configure, test, and deploy apps in the language of your choice. For more information, see the following articles: -## FAQ +- [Build, test, and deploy .NET Core apps](../ecosystems/dotnet-core.md) +- [Build and test Go projects](../ecosystems/go.md) +- [Build Java apps](../ecosystems/java.md) +- [Build and publish a Node.js package](../ecosystems/javascript.md) +- [Build and publish a Python app](../ecosystems/python.md) +- [Build a container image to deploy apps](../ecosystems/containers/build-image.md) +- [Customize your pipeline](../customize-pipeline.md) -### How do I programmatically create a build pipeline? +### Azure DevOps Services REST API -[REST API Reference: Create a build pipeline](../../integrate/index.md) +You can build custom applications or services that integrate with Azure DevOps by using the REST APIs to make direct HTTP calls. For more information, see the [Azure DevOps Services REST API Reference](/rest/api/azure/devops). You can also use the [client libraries](/rest/api/azure/devops#client-libraries) for these APIs. -> [!NOTE] -> You can also manage builds and build pipelines from the command line or scripts using the [Azure Pipelines CLI](/cli/azure/). +### Skip a stage in a pipeline run + +You can use the [az rest](/cli/azure/use-azure-cli-rest-command) command with the [Run Pipeline](/rest/api/azure/devops/pipelines/runs/run-pipeline) REST API to skip a stage in a pipeline run, using the `stagesToSkip` parameter. + +For example: + +```azurecli +az rest --method post ` + --uri https://dev.azure.com/{organization}/{project}/_apis/pipelines/{pipelineId}/runs?api-version=7.1-preview.1 ` + --body "{'stagesToSkip': [''], 'resources': {'repositories': {'self': {'refName': 'refs/heads/{branch}'}}}}" ` + --resource 499b84ac-1321-427f-aa17-267ca6975798 +``` - +For more information, see [Use the Azure REST API with Azure CLI](/cli/azure/use-azure-cli-rest-command). -### Can I run multiple pipelines in Azure DevOps Services using a single command? +## Related content -Currently, the Azure CLI and Azure APIs don't offer commands that run multiple pipelines from the command line. You can use [Azure CLI commands](/cli/azure/pipelines) to list all pipelines and definitions and provide a *single* release or build ID as a parameter. All commands are designed to work for independent runs of independent pipelines, and they require unique ID requests that allow only one, unique value. To learn about pipeline triggers, see [Specify events that trigger pipelines](../build/triggers.md). +- [Get started with Azure DevOps CLI](../../cli/index.md) +- [Specify events that trigger pipelines](../build/triggers.md) +- [Output formats for Azure CLI commands](/cli/azure/format-output-azure-cli) diff --git a/docs/pipelines/get-started/media/yaml-pipeline-editor/yaml-pipeline-validate-and-save-button.png b/docs/pipelines/get-started/media/yaml-pipeline-editor/yaml-pipeline-validate-and-save-button.png new file mode 100644 index 00000000000..b3f79cece0b Binary files /dev/null and b/docs/pipelines/get-started/media/yaml-pipeline-editor/yaml-pipeline-validate-and-save-button.png differ diff --git a/docs/pipelines/get-started/media/yaml-pipeline-editor/yaml-pipeline-validate-and-save.png b/docs/pipelines/get-started/media/yaml-pipeline-editor/yaml-pipeline-validate-and-save.png new file mode 100644 index 00000000000..94c0e7bf3aa Binary files /dev/null and b/docs/pipelines/get-started/media/yaml-pipeline-editor/yaml-pipeline-validate-and-save.png differ diff --git a/docs/pipelines/get-started/pipelines-get-started.md b/docs/pipelines/get-started/pipelines-get-started.md index d89b49a3c46..5dc313d9c5d 100644 --- a/docs/pipelines/get-started/pipelines-get-started.md +++ b/docs/pipelines/get-started/pipelines-get-started.md @@ -1,165 +1,108 @@ --- -title: Use Azure Pipelines -ms.custom: seodec18 -description: Learn the basics about Azure Pipelines and how to use it to automatically build and release code. +title: YAML vs Classic Pipelines +description: Learn the basics about Azure Pipelines and explore the different features available for both YAML and Classic pipelines. ms.topic: overview ms.author: sdanie author: steved0x -ms.date: 06/07/2023 +ms.date: 06/12/2024 monikerRange: '<= azure-devops' --- -# Use Azure Pipelines +# YAML vs Classic Pipelines [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range=">= azure-devops-2019" +Azure Pipelines enables developers to automate a wide variety of tasks, ranging from executing a batch file to setting up a complete continuous integration (CI) and continuous delivery (CD) solution for their applications. -Azure Pipelines supports continuous integration (CI) and continuous -delivery (CD) to continuously test, build, and deploy your code. You accomplish this by defining a pipeline. +Azure Pipelines supports a wide range of languages, platforms, and tools, and offers two types of pipelines to choose from: [YAML-based](yaml-pipeline-editor.md) and [Classic pipeline](../release/define-multistage-release-process.md) editors. -The latest way to build pipelines is with the [YAML pipeline editor](yaml-pipeline-editor.md). You can also use Classic pipelines with the [Classic editor](../release/define-multistage-release-process.md). +> [!NOTE] +> If you are new to Azure Pipelines, it is recommended to start with YAML pipelines. For existing Classic pipelines, you can choose to continue using them or [migrate to YAML pipelines](../migrate/from-classic-pipelines.md). -::: moniker-end - -::: moniker range="tfs-2018" - -Azure Pipelines supports continuous integration (CI) and continuous -delivery (CD) to continuously test, build, and deploy your code. You accomplish this by defining a pipeline -using the user interface, also referred to as _Classic_. - -::: moniker-end - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -## Automate tests, builds, and delivery - -Continuous integration (CI) automates tests and builds for your project. CI helps to catch bugs or issues early in the development cycle, when they're easier and faster to fix. Items known as artifacts are produced from CI systems. They're used by the continuous delivery release pipelines to drive automatic deployments. - -Continuous delivery automatically deploys and tests code in multiple stages to help drive quality. Continuous integration systems produce deployable artifacts, which include infrastructure and apps. Automated release pipelines consume these artifacts to release new versions and fixes to the target of your choice. - -| Continuous integration (CI) | Continuous delivery (CD) | -| ----------------------------------------------------|-------------------------------------------------| -|- Increase code coverage
      - Build faster by splitting test and build runs
      - Automatically ensure you don't ship broken code
      - Run tests continually |- Automatically deploy code to production
      - Ensure deployment targets have latest code
      - Use tested code from CI process| - - -## Define pipelines using YAML syntax - -::: moniker range=">= azure-devops-2019" - -You define your pipeline in a YAML file called `azure-pipelines.yml` with the rest of your app. - -![Pipelines YAML intro image](../media/pipelines-image-yaml.png) - -* The pipeline is versioned with your code. It follows the same branching structure. You get validation of your changes through code reviews in pull requests and branch build policies. -* Every branch you use can modify the pipeline by modifying the `azure-pipelines.yml` file. Learn more about [branch consideration for YAML pipelines](../build/triggers.md#branch-considerations). -* A change to the build process might cause a break or result in an unexpected outcome. Because the change is in version control with the rest of your codebase, you can more easily identify the issue. +## Define pipelines using YAML -Follow these basic steps: +Your pipeline configuration resides in a YAML file named `azure-pipelines.yml`, alongside your application. -1. Configure Azure Pipelines to use your Git repo. -1. Edit your `azure-pipelines.yml` file to define your build. -1. Push your code to your version control repository. This action kicks off the default trigger to build and deploy and then monitor the results. +- The YAML file is versioned alongside your application code, adhering to the same branching structure. -Your code is now updated, built, tested, and packaged. It can be deployed to any target. +- Each branch can customize the pipeline by editing the `azure-pipelines.yml` file. -::: moniker-end - -::: moniker range="tfs-2018" +- Keeping the pipeline configuration in version control ensures that any changes that cause issues or unexpected outcomes can be easily identified within your codebase. -YAML pipelines aren't available in TFS 2018 and earlier versions. - -::: moniker-end +For instructions, see [Create your first pipeline](../create-first-pipeline.md) for a step by step guide to building a sample application from a Git repository. ## Define pipelines using the Classic interface - -Create and configure pipelines in the Azure DevOps web portal with the Classic user interface editor. -You define a *build pipeline* to build and test your code, and then to publish artifacts. You also define a *release pipeline* to consume and deploy those artifacts to deployment targets. -![Pipelines designer intro image](../media/pipelines-image-designer.png) +::: moniker range="<=azure-devops" -Follow these basic steps: +Classic pipelines are created in the Azure DevOps web portal with the Classic user interface editor. You can define a *pipeline* to build, test your code, and then publish your artifact (binary). Additionally, you can define a *release pipeline* to consume your binary (artifact) and deploy it to specific targets. -1. Configure Azure Pipelines to use your Git repo. -1. Use the Azure Pipelines classic editor to create and configure your build and release pipelines. -1. Push your code to your version control repository. This action triggers your pipeline and runs tasks such as building or testing code. - -The build creates an artifact that's used by the rest of your pipeline to run tasks such as deploying to staging or production. - -Your code is now updated, built, tested, and packaged. It can be deployed to any target. +::: moniker-end +For instructions, see [build](../build/ci-build-git.md) and [deploy](../release/define-multistage-release-process.md) for step by step guides to building and deploying your application with Classic Pipelines. ## Feature availability -::: moniker range=">= azure-devops-2019" - -Certain pipeline features are only available when using YAML or when defining build or release pipelines with the Classic interface. The following table indicates which features are supported and for which tasks and methods. - - -| Feature | YAML | Classic Build | Classic Release |Notes| -|---|:-:|:-:|:-:|---| -| [Agents](../agents/agents.md) | ✅ | ✅ | ✅ | Specifies a required resource on which the pipeline runs.| -| [Approvals](../release/approvals/index.md) | ✅ | ❌ | ✅ | Defines a set of validations required prior to completing a deployment stage. | -| [Artifacts](../artifacts/artifacts-overview.md) | ✅ | ✅ | ✅ | Supports publishing or consuming different package types. | -| [Caching](../release/caching.md) | ✅ | ✅ | ❌ | Reduces build time by allowing outputs or downloaded dependencies from one run to be reused in later runs. In Preview, available with Azure Pipelines only.| -| [Conditions](../process/conditions.md) | ✅ | ✅ | ✅ | Specifies conditions to be met prior to running a job. | -| [Container jobs](../process/container-phases.md) | ✅ | ❌ | ❌ | Specifies jobs to run in a container. | -| [Demands](../process/demands.md) | ✅ | ✅ | ✅ | Ensures pipeline requirements are met before running a pipeline stage. Requires self-hosted agents. | -| [Dependencies](../process/stages.md) | ✅ | ✅ | ✅ | Specifies a requirement that must be met in order to run the next job or stage. | -| [Deployment groups](../release/deployment-groups/index.md) | ❌ | ❌ | ✅ | Defines a logical set of deployment target machines. | -| [Deployment group jobs](../process/deployment-group-phases.md)| ❌ | ❌ | ✅ | Specifies a job to release to a deployment group. | -| [Deployment jobs](../process/deployment-jobs.md) | ✅ | ❌ | ❌ | Defines the deployment steps. | -| [Environment](../process/environments.md) | ✅ | ❌ | ❌ | Represents a collection of resources targeted for deployment. Available with Azure Pipelines only.| -| [Gates](../release/approvals/gates.md) | ❌ | ❌ | ✅ | Supports automatic collection and evaluation of external health signals prior to completing a release stage. Available with Classic Release only. | -| [Jobs](key-pipelines-concepts.md) | ✅ | ✅ | ✅ | Defines the execution sequence of a set of steps.| -| [Service connections](../library/service-endpoints.md) | ✅ | ✅ | ✅ | Enables a connection to a remote service that is required to execute tasks in a job. | -| [Service containers](../process/service-containers.md) | ✅ | ❌ | ❌ |Enables you to manage the lifecycle of a containerized service. | -| [Stages](key-pipelines-concepts.md) | ✅ | ❌ | ✅ |Organizes jobs within a pipeline. | -| [Task groups](../library/task-groups.md) | ❌ | ✅ | ✅ | Encapsulates a sequence of tasks into a single reusable task. If using YAML, see templates.| -| [Tasks](../process/tasks.md) | ✅ | ✅ | ✅ | Defines the building blocks that make up a pipeline. | -| [Templates](../process/templates.md) | ✅ | ❌ | ❌ | Defines reusable content, logic, and parameters. | -| [Triggers](../build/triggers.md) | ✅ | ✅| ✅ | Defines the event that causes a pipeline to run. | -| [Variables](../process/variables.md) | ✅ | ✅ | ✅ | Represents a value to be replaced by data to pass to the pipeline. | -| [Variable groups](../library/variable-groups.md) | ✅ | ✅ | ✅ | Use to store values that you want to control and make available across multiple pipelines.| +::: moniker range="azure-devops" + +| Feature | Description | YAML | Classic Pipeline | Classic Release | +|-------------------------------------------------------|------------------------------------------------------------------------------------------------|------------------|------------------|-----------------| +| **Agents** | A software component that runs on a virtual machine or a physical machine and is responsible for executing the tasks defined in your Azure Pipelines. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md) | +| **Approvals** | Control your deployment workflow by requiring designated approvers to approve before deploying to a stage. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/approvals.md#approvals) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/approvals/approvals.md#predeployment-approvals) | +| **Artifacts** | Download and publish your binaries and various types of packages to different destinations. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../artifacts/pipeline-artifacts.md?&tabs=yaml-task) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../artifacts/pipeline-artifacts.md?&tabs=yaml-task) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/deploy-multiple-branches.md#create-a-release-pipeline) | +| **Caching** | Reduce build time by caching and reusing dependencies from previous runs. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/caching.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/caching.md) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | +| **Conditions** | Specify conditions under which a step, job, or stage should run. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/conditions.md?tabs=yaml) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/conditions.md?tabs=classic) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/conditions.md?tabs=classic) | +| **Container jobs** | Specify jobs to run in a container. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/container-phases.md) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | +| **Demands** | Ensure that the capabilities your pipeline needs are present on the running agent. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md#configure-demands) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md?tabs=classic#configure-demands) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md?tabs=classic#configure-demands) | +| **Dependencies** | Specify a requirement that must be met in order to run the next stage. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/stages.md?tabs=yaml#specify-dependencies) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/stages.md?tabs=classic#specify-dependencies) | +| **Deployment groups & Environments** | Deployment groups (Classic): Define a set of target machines each equipped with a deployment agent.
      Environments (YAML): A collection of resources targeted for deployment. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/environments.md) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/deployment-groups/index.md#create-a-deployment-group) | +| **Deployment jobs** | A collection of deployment steps that are run sequentially against the environment. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/deployment-jobs.md) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | +| **Gates** | Automate release controls by evaluating health signals from external services before completing a deployment. | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/deploy-using-approvals.md#set-up-gates) | +| **Jobs** | A series of sequential steps that form the smallest unit of work that can be scheduled to run. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/phases.md?tabs=yaml) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/phases.md?tabs=classic) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/phases.md?tabs=classic) | +| **Library** | A collection of assets that can be used in your Azure Pipelines. The Library contains two types of assets: [Variable groups](../library/variable-groups.md) and [Secure files](../library/secure-files.md). | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/index.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/index.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/index.md) | +| **Service connections** | Enable connection to an external service required to execute tasks in a job. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/service-endpoints.md#create-a-service-connection) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/service-endpoints.md#create-a-service-connection) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/service-endpoints.md#create-a-service-connection) | +| **Service containers** | Enable you to manage the lifecycle of a containerized service. most commonly used with container jobs. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/service-containers.md) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | +| **Stages** | Organize jobs within a pipeline. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/stages.md?tabs=yaml#specify-stages) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/stages.md?tabs=classic#specify-stages) | +| **Task groups** | Encapsulate a sequence of tasks into a single reusable task. | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/task-groups.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/task-groups.md) | +| **Tasks** | The building blocks that define the steps that make up a pipeline job. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/tasks.md?tabs=yaml) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/tasks.md?tabs=classic) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/tasks.md?tabs=classic) | +| **Templates** | Define reusable content, logic, and parameters. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/templates.md) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | +| **Triggers** | Define the event that causes a pipeline to run. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/pipeline-triggers.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/pipeline-triggers-classic.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/triggers.md) | +| **Variables** | A placeholder for values that can be used throughout your pipeline's execution. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/variables.md?tabs=yaml#set-variables-in-pipeline) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/variables.md?tabs=classic#set-variables-in-pipeline) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/variables.md?tabs=classic#set-variables-in-pipeline) | +| **Variable groups** | Use to store values and secrets that you want to manage and share across multiple pipelines. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/variable-groups.md?tabs=yaml#use-variable-groups-in-pipelines) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/variable-groups.md?tabs=classic#use-variable-groups-in-pipelines) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/variable-groups.md?tabs=classic#use-variable-groups-in-pipelines) | ::: moniker-end - - -::: moniker range="tfs-2018" - -TFS 2015 through TFS 2018 supports the Classic interface only. The following table indicates which pipeline features are available when defining build or release pipelines. - -| Feature | Classic Build | Classic Release |Notes| -|---|:-:|:-:|---| -| [Agents](../agents/agents.md) | ✅ | ✅ | Specifies a required resource on which the pipeline runs.| -| [Approvals](../release/approvals/index.md) | ❌ | ✅ | Defines a set of validations required prior to completing a deployment stage. | -| [Artifacts](../artifacts/artifacts-overview.md) | ✅ | ✅ | Supports publishing or consuming different package types. | -| [Conditions](../process/conditions.md) | ✅ | ✅ | Specifies conditions to be met prior to running a job. | -| [Demands](../process/demands.md) | ✅ | ✅ | Ensures pipeline requirements are met before running a pipeline stage. Requires self-hosted agents. | -| [Dependencies](../process/stages.md) | ✅ | ✅ | Specifies a requirement that must be met in order to run the next job or stage. | -| [Deployment groups](../release/deployment-groups/index.md) | ❌ | ✅ | Defines a logical set of deployment target machines. | -| [Deployment group jobs](../process/deployment-group-phases.md)| ❌ | ✅ | Specifies a job to release to a deployment group. | -| [Jobs](key-pipelines-concepts.md) | ✅ | ✅ | Defines the execution sequence of a set of steps.| -| [Service connections](../library/service-endpoints.md) | ✅ | ✅ | Enables a connection to a remote service that is required to execute tasks in a job. | -| [Stages](key-pipelines-concepts.md) | ❌ | ✅ |Organizes jobs within a pipeline. | -| [Task groups](../library/task-groups.md) | ✅ | ✅ | Encapsulates a sequence of tasks into a single reusable task. If using YAML, see templates.| -| [Tasks](../process/tasks.md) | ✅ | ✅ | Defines the building blocks that make up a pipeline. | -| [Triggers](../build/triggers.md) | ✅ | ✅ |Defines the event that causes a pipeline to run. | -| [Variables](../process/variables.md) | ✅ | ✅ | Represents a value to be replaced by data to pass to the pipeline. | -| [Variable groups](../library/variable-groups.md) | ✅ | ✅ | Use to store values that you want to control and make available across multiple pipelines.| +::: moniker range="azure-devops-2020 || azure-devops-2022" + +| Feature | Description | YAML | Classic Pipeline | Classic Release | +|-------------------------------------------------------|------------------------------------------------------------------------------------------------|------------------|------------------|-----------------| +| **Agents** | A software component that runs on a virtual machine or a physical machine and is responsible for executing the tasks defined in your Azure Pipelines. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md) | +| **Approvals** | Control your deployment workflow by requiring designated approvers to approve before deploying to a stage. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/approvals.md#approvals) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/approvals/approvals.md#predeployment-approvals) | +| **Artifacts** | Download and publish your binaries and various types of packages to different destinations. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../artifacts/pipeline-artifacts.md?&tabs=yaml-task) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../artifacts/pipeline-artifacts.md?&tabs=yaml-task) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/deploy-multiple-branches.md#create-a-release-pipeline) | +| **Conditions** | Specify conditions under which a step, job, or stage should run. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/conditions.md?tabs=yaml) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/conditions.md?tabs=classic) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/conditions.md?tabs=classic) | +| **Container jobs** | Specify jobs to run in a container. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/container-phases.md) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | +| **Demands** | Ensure that the capabilities your pipeline needs are present on the running agent. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md#configure-demands) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md?tabs=classic#configure-demands) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../agents/agents.md?tabs=classic#configure-demands) | +| **Dependencies** | Specify a requirement that must be met in order to run the next stage. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/stages.md?tabs=yaml#specify-dependencies) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/stages.md?tabs=classic#specify-dependencies) | +| **Deployment groups & Environments** | Deployment groups (Classic): Define a set of target machines each equipped with a deployment agent.
      Environments (YAML): A collection of resources targeted for deployment. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/environments.md) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/deployment-groups/index.md#create-a-deployment-group) | +| **Deployment jobs** | A collection of deployment steps that are run sequentially against the environment. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/deployment-jobs.md) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | +| **Gates** | Automate release controls by evaluating health signals from external services before completing a deployment. | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/deploy-using-approvals.md#set-up-gates) | +| **Jobs** | A series of sequential steps that form the smallest unit of work that can be scheduled to run. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/phases.md?tabs=yaml) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/phases.md?tabs=classic) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/phases.md?tabs=classic) | +| **Library** | A collection of assets that can be used in your Azure Pipelines. The Library contains two types of assets: [Variable groups](../library/variable-groups.md) and [Secure files](../library/secure-files.md). | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/index.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/index.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/index.md) | +| **Service connections** | Enable connection to an external service required to execute tasks in a job. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/service-endpoints.md#create-a-service-connection) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/service-endpoints.md#create-a-service-connection) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/service-endpoints.md#create-a-service-connection) | +| **Stages** | Organize jobs within a pipeline. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/stages.md?tabs=yaml#specify-stages) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/stages.md?tabs=classic#specify-stages) | +| **Task groups** | Encapsulate a sequence of tasks into a single reusable task. | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/task-groups.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/task-groups.md) | +| **Tasks** | The building blocks that define the steps that make up a pipeline job. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/tasks.md?tabs=yaml) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/tasks.md?tabs=classic) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/tasks.md?tabs=classic) | +| **Templates** | Define reusable content, logic, and parameters. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/templates.md) | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | :::image type="icon" source="../../media/icons/delete-icon.png" border="false"::: | +| **Triggers** | Define the event that causes a pipeline to run. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/pipeline-triggers.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/pipeline-triggers-classic.md) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../release/triggers.md) | +| **Variables** | A placeholder for values that can be used throughout your pipeline's execution. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/variables.md?tabs=yaml#set-variables-in-pipeline) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/variables.md?tabs=classic#set-variables-in-pipeline) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../process/variables.md?tabs=classic#set-variables-in-pipeline) | +| **Variable groups** | Use to store values and secrets that you want to manage and share across multiple pipelines. | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/variable-groups.md?tabs=yaml#use-variable-groups-in-pipelines) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/variable-groups.md?tabs=classic#use-variable-groups-in-pipelines) | :::image type="icon" source="../../media/icons/checkmark.png" border="false"::: [doc](../library/variable-groups.md?tabs=classic#use-variable-groups-in-pipelines) | ::: moniker-end - - ## Next steps > [!div class="nextstepaction"] +> [Sign up for Azure Pipelines](pipelines-sign-up.md) > [Create your first pipeline](../create-first-pipeline.md) - -## Related articles - -- [Key concepts for new Azure Pipelines users](key-pipelines-concepts.md) - +> [Customize your pipeline](../customize-pipeline.md) diff --git a/docs/pipelines/get-started/pipelines-sign-up.md b/docs/pipelines/get-started/pipelines-sign-up.md index c733c37a783..02bcdec3e6b 100644 --- a/docs/pipelines/get-started/pipelines-sign-up.md +++ b/docs/pipelines/get-started/pipelines-sign-up.md @@ -1,11 +1,10 @@ --- title: Sign up for Azure Pipelines -ms.custom: seodec18 description: Walk through signing up for Azure Pipelines to begin managing CI/CD to deploy your code. ms.topic: overview ms.author: chcomley author: chcomley -ms.date: 08/24/2021 +ms.date: 03/13/2025 monikerRange: 'azure-devops' --- @@ -17,145 +16,25 @@ Sign up for an Azure DevOps organization and Azure Pipelines to begin managing C For more information about Azure Pipelines, see [What is Azure Pipelines](what-is-azure-pipelines.md). -You can sign up with either a [Microsoft account](#signup-microsoft) or a [GitHub account](#signup-github). +## Prerequisites - +| Category | Requirements | +|--------------|-------------| +|**Browser**| Latest version of one of the following web browsers: Microsoft Edge, Internet Explorer, Safari (Mac), Firefox, or Chrome.| -## Sign up with a Microsoft account +## Sign up -To sign up for Azure DevOps with a Microsoft account, complete the following steps. +Sign up for Azure Pipelines with either a Microsoft account or GitHub account. -1. Check that your account is up to date by logging into your Microsoft account. +# [Microsoft account](#tab/microsoft-account) -2. Open Azure Pipelines and select **Start free**. +[!INCLUDE [sign-up-msft-account](../../includes/sign-up-msft-account.md)] - ![Screenshot of Start free with Azure Pipelines page.](media/start-free-azure-pipelines.png) +# [GitHub account](#tab/github-account) -3. Log into your Microsoft account. +[!INCLUDE [sign-in-github-account](../../includes/sign-in-github-account.md)] -4. To get started with Azure Pipelines, select **Continue**. - - ![Choose Continue to sign up for Azure DevOps.](../../media/sign-up-azure-devops.png) - -5. Enter a name for your organization, select a host location from the drop-down menu, enter the characters you see, and then select **Continue**. - - :::image type="content" source="../media/almost-done-name-organization.png" alt-text="Screenshot of Almost done pane, name your organization."::: - - -Use the following URL to sign in to your organization at any time: `https://dev.azure.com/{yourorganization}` - -You're now prompted to [create a project](#create-project). - - - -## Sign up with a GitHub account - -To sign up for Azure DevOps with a GitHub account, complete the following steps. - -> [!IMPORTANT] -> If your GitHub email address is associated with an Azure AD-backed organization in Azure DevOps, you can't sign in with your GitHub account, rather you must sign in with your Azure AD account. - -1. Check that your account is up to date by logging into your GitHub account. - -2. Open Azure Pipelines and select **Start free with GitHub**. If you're already part of an Azure DevOps organization, choose **Start free**. - - ![Start Azure Pipelines with GitHub](media/start-free-github-pipelines.png) - -3. Enter your GitHub account credentials, and then select **Sign in**. - - ![Enter GitHub credentials](../../media/enter-github-credentials.png) - -4. Select **Authorize Microsoft-corp**. - - ![Authorize Microsoft](../../media/authorize-Microsoft-corp.png) - -5. Select **Next** to create a new Microsoft account linked to your GitHub credentials. - - ![Link GitHub account to Microsoft account](media/link-microsoft-account.png) - - For more information about GitHub authentication, see [FAQs](../../organizations/security/faq-github-authentication.yml). - -6. Fill in your name, email address, and country/region. - - ![Fill in name, email address, and country](media/fill-in-details-devops-github.png) - -7. To get started with Azure Pipelines, select **Continue**. - - ![Choose Continue to sign up for Azure DevOps.](../../media/sign-up-azure-devops.png) - -8. Enter a name for your organization, select a host location from the drop-down menu, enter the characters you see, and then select **Continue**. - - :::image type="content" source="../media/almost-done-name-organization.png" alt-text="Screenshot of Almost done pane, name your organization."::: - - -Use the following URL to sign in to your organization at any time: `https://dev.azure.com/{yourorganization}` - -You're now prompted to create a project. - - - -## Create a project - -You can create public or private projects. To learn more about public projects, see [What is a public project?](../../organizations/projects/about-projects.md). - -1. Enter a name for your project, select the visibility, and optionally provide a description. Then choose **Create project**. - - > [!div class="mx-imgBorder"] - >![Create new project dialog](../../boards/get-started/media/sign-up/nf-create-project.png) - - Special characters aren't allowed in the project name (such as / : \ ~ & % ; @ ' " ? < > | # $ * } { , + = [ ]). The project name also can't begin with an underscore, can't begin or end with a period, and must be 64 characters or less. Set your project visibility to either public or private. Public visibility allows for anyone on the internet to view your project. Private visibility is for only people who you give access to your project. - -2. When your project is created, if you signed up with a Microsoft account, the wizard to create a new pipeline automatically starts. If you signed up with a GitHub account, you're asked to select which services to use. - -You're now set to [create your first pipeline](../create-first-pipeline.md), or [invite other users](#invite-others) to collaborate with your project. - - - -## Invite team members - optional - -Add and invite others to work on your project by adding their email address to your organization and project. - -1. From your project web portal, choose :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps > ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. - - ![Open Organization settings](../../media/settings/open-admin-settings-vert-2.png) - -2. Select **Users** > **Add users**. - - :::image type="content" source="../../media/add-new-users.png" alt-text="Select Add users"::: - -3. Complete the form by entering or selecting the following information: - - - **Users:** Enter the email addresses (Microsoft accounts) or GitHub IDs for the users. You can add several email addresses by separating them with a semicolon (;). - - **Access level:** Assign one of the following access levels: - - **Basic:** Assign to users who must have access to all Azure Pipelines features. You can grant up to five users Basic access for free. - - **Stakeholder:** Assign to users for limited access to features to view, add, and modify work items. You can assign an unlimited amount of users Stakeholder access for free. - - **Visual Studio Subscriber:** Assign to users who already have a Visual Studio subscription. - - **Add to project:** Select the project you named in the preceding procedure. - - **Azure DevOps groups:** Select one of the following security groups, which will determine the permissions the users have to do select tasks. To learn more, see [Azure Pipelines resources](../security/resources.md). - - **Project Readers:** Assign to users who only require read-only access. - - **Project Contributors:** Assign to users who will contribute fully to the project. - - **Project Administrators:** Assign to users who will configure project resources. - - > [!NOTE] - > Add email addresses for [Microsoft accounts](https://account.microsoft.com/account) and IDs for GitHub accounts unless you plan to use [Azure Active Directory (Azure AD)](/azure/active-directory/fundamentals/active-directory-whatis) to authenticate users and control organization access. If a user doesn't have a Microsoft or GitHub account, ask the user to [sign up](https://signup.live.com/) for a Microsoft account or a GitHub account. - -4. When you're done, select **Add** to complete your invitation. - -For more information, see [Add organization users for Azure DevOps Services](../../organizations/accounts/add-organization-users.md). - -## Change organization or project settings - -You can rename and delete your organization, or change the organization location. For more information, see the following articles: - -- [Manage organizations](../../organizations/accounts/organization-management.md) -- [Rename an organization](../../organizations/accounts/rename-organization.md) -- [Change the location of your organization](../../organizations/accounts/change-organization-location.md) - -You can rename your project or change its visibility. To learn more about managing projects, see the following articles: - -- [Manage projects](../../organizations/projects/about-projects.md) -- [Rename a project](../../organizations/projects/rename-project.md) -- [Change the project visibility, public or private](../../organizations/projects/make-project-public.md) +--- ## Next steps @@ -164,6 +43,7 @@ You can rename your project or change its visibility. To learn more about managi ## Related articles +- [Create a project](../../organizations/projects/create-project.md) - [What is Azure Pipelines?](what-is-azure-pipelines.md) - [Key concepts for new Azure Pipelines users](key-pipelines-concepts.md) - [Customize your pipeline](../customize-pipeline.md) diff --git a/docs/pipelines/get-started/what-is-azure-pipelines.md b/docs/pipelines/get-started/what-is-azure-pipelines.md index bd0696881c5..99442ef1689 100644 --- a/docs/pipelines/get-started/what-is-azure-pipelines.md +++ b/docs/pipelines/get-started/what-is-azure-pipelines.md @@ -1,9 +1,8 @@ --- title: What is Azure Pipelines? -ms.custom: seodec18 description: Learn how to automatically build, test, and deploy your code with Azure Pipelines ms.topic: overview -ms.date: 04/12/2023 +ms.date: 07/01/2024 monikerRange: '<= azure-devops' --- @@ -11,97 +10,103 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Azure Pipelines automatically builds and tests code projects. It supports all major languages and project types and combines [continuous integration](#continuous-integration), [continuous delivery](#continuous-delivery), and [continuous testing](#continuous-testing) to build, test, and deliver your code to any destination. +Azure Pipelines is the part of Azure DevOps that automatically builds, tests, and deploys code projects. Azure Pipelines combines [continuous integration](#continuous-integration), [continuous testing](#continuous-testing), and [continuous delivery](#continuous-delivery) to build, test, and deliver your code to any destination. Azure Pipelines supports all major languages and project types. :::image type="content" source="media/pipelines-overview.png" alt-text="Screenshot of Azure Pipelines overview."::: -## Continuous Integration +## Azure Pipelines benefits -Continuous Integration (CI) is the practice used by development teams of automating, merging, and testing code. CI helps to catch bugs early in the development cycle, which makes them less expensive to fix. Automated tests execute as part of the CI process to ensure quality. CI systems produce artifacts and feed them to release processes to drive frequent deployments. -::: moniker range="< azure-devops" -The Build service in [Azure DevOps Server](https://azure.microsoft.com/services/devops/server/) helps you set up and manage CI for your applications. -::: moniker-end +Azure Pipelines provides a quick, easy, and safe way to automate building your projects with consistent and quality code that's readily available to users. -## Continuous Delivery +Azure Pipelines offers the following benefits: -Continuous Delivery (CD) is a process by which code is built, tested, and deployed to one or more test and production environments. Deploying and testing in multiple environments increases quality. CD systems produce deployable artifacts, including infrastructure and apps. Automated release processes consume these artifacts to release new versions and fixes to existing systems. Systems that monitor and send alerts run continually to drive visibility into the entire CD process. +- Works with any language or platform. +- Deploys to different types of targets at the same time. +- Integrates with Azure deployments. +- Builds on Windows, Linux, or Mac machines. +- Integrates with GitHub. +- Works with open-source projects. -## Continuous Testing +## Prerequisites -Whether your app is on-premises or in the cloud, you can automate build-deploy-test workflows and choose the technologies and frameworks. Then, you can [test your changes continuously](../ecosystems/dotnet-core.md#run-your-tests) in a fast, scalable, and efficient manner. Continuous testing offers the following benefits. +To use Azure Pipelines, you must: -* Maintain quality and find problems as you develop. Continuous testing with Azure DevOps Server ensures your app still works after every check-in and build, enabling you to find problems earlier by running tests automatically with each build. -* Use any test type and any test framework. Choose your preferred test technologies and frameworks. -* View rich analytics and reporting. When your build is done, review your test results to resolve any issues. Actionable build-on-build reports let you instantly see if your builds are getting healthier. But it's not just about speed - detailed and customizable test results measure the quality of your app. +- Have an Azure DevOps organization. If you don't have one, you can [create an organization](../../organizations/accounts/create-organization.md). +- Store your source code in a [version control system](#version-control-systems). +::: moniker range="< azure-devops" +- Download a [build agent](../agents/windows-agent.md) and install it on a build server. +::: moniker-end -## Version control systems +## Languages and applications -Azure Pipelines requires your source code to be in a version control system. Azure DevOps supports two forms of version control - [Git](../../repos/get-started/what-is-repos.md) and [Azure Repos](../../repos/get-started/what-is-repos.md). Any changes you push to your version control repository are automatically built and validated. +Azure Pipelines offers tasks to build, test, and deploy Node.js, Python, Java, PHP, Ruby, C#, C++, Go, XCode, .NET, Android, and iOS applications. You can run these apps in parallel on Linux, macOS, and Windows. -## Languages and applications +There are tasks to run tests in many testing frameworks and services. You can also run command line, PowerShell, or shell scripts in your automation. -You can build, test, and deploy Node.js, Python, Java, PHP, Ruby, C#, C++, Go, XCode, .NET, Android, and iOS applications. Run these apps in parallel on Linux, macOS, and Windows. +## Continuous integration -Azure DevOps offers tasks to build and test .NET, Java, Node, Android, Xcode, and C++ applications. Similarly, there are tasks to run tests using many testing frameworks and services. You can also run command line, PowerShell, or Shell scripts in your automation. +Continuous integration (CI) is a practice development teams use to automate merging and testing code. CI helps to catch bugs early in the development cycle, making them less expensive to fix. -## Deployment targets +To ensure quality, Azure Pipelines executes automated tests as part of the CI process. Azure Pipelines CI systems produce artifacts and feed them to release processes to drive continuous deployments. -Use Azure Pipelines to deploy your code to multiple targets. Targets include virtual machines, environments, containers, on-premises and cloud platforms, or PaaS services. You can also publish your mobile application to a store. +::: moniker range="< azure-devops" +The Build service in [Azure DevOps Server](https://azure.microsoft.com/services/devops/server/) helps you set up and manage CI for your applications. +::: moniker-end -Once you have continuous integration in place, create a release definition to automate the deployment of your application to one or more environments. This automation process is defined as a collection of tasks. +### Version control systems -## Package formats +Azure Pipelines requires your source code to be in a version control system. Azure Pipelines supports several forms of version control, including [Azure Repos Git, GitHub, and TFVC](../repos/index.md). You can set up Azure Pipelines to automatically build and validate any changes you push to your version control repository. -To produce packages that can be consumed by others, you can publish NuGet, npm, or Maven packages to the built-in package management repository in Azure Pipelines. You also can use any other package management repository of your choice. +## Continuous testing -## What do I need to use Azure Pipelines? +Azure Pipelines can automate build-deploy-test workflows in your chosen technologies and frameworks, whether your app is on-premises or in the cloud. You can [test your changes continuously](../ecosystems/dotnet-core.md#run-your-tests) in a fast, scalable, and efficient manner. Continuous testing lets you: -To use Azure Pipelines, complete the following tasks: +- Maintain quality and find problems during development. You can find problems earlier by running tests automatically with each build, ensuring your app still works after every checkin and build. -- Have an organization in Azure DevOps. If you don't have one, [create an organization](../../organizations/accounts/create-organization.md) now. -- Store your source code in a [version control system](#version-control-systems). -::: moniker range="< azure-devops" -- Download a [build agent](../agents/windows-agent.md) and install it on a build server. -::: moniker-end +- Use any test type and test framework. Choose your preferred test technologies. -### Pricing for Azure DevOps +- View rich analytics and reporting. When your build is done, you can review your test results to resolve any issues. Actionable build-on-build reports let you instantly see if your builds are getting healthier. Detailed and customizable test results measure the quality of your app. -**Azure DevOps Services** +## Continuous delivery -If you use public projects, Azure Pipelines is free, but you will need to request the free grant of parallel jobs. You can request this grant by submitting a [request](https://aka.ms/azpipelines-parallelism-request). Existing organizations and projects are not affected. +Continuous delivery (CD) is the process of building, testing, and deploying code to one or more test or production environments. Deploying and testing in multiple environments optimizes quality. -For more information, see [What is a public project](../../organizations/projects/about-projects.md). -If you use private projects, you can run up to 1,800 minutes (30 hours) of pipeline jobs for free every month. +Azure Pipelines CD systems produce deployable artifacts, including infrastructure and apps. Automated release processes consume these artifacts to release new versions and fixes to existing systems. Systems that continually monitor and send alerts drive visibility into the CD process. -For more information, see [Pricing based on parallel jobs](../licensing/concurrent-jobs.md) -and [Pricing for Azure DevOps Services](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). +### Deployment targets -**Azure DevOps Server** +Use Azure Pipelines to deploy your code to multiple targets. Targets include virtual machines, environments, containers, on-premises and cloud platforms, and platform-as-a-service (PaaS) services. You can also publish your mobile application to a store. -With five or less active users, [Azure DevOps Express](https://azure.microsoft.com/services/devops/server/) is free, simple to set up, and installs on both client and server operating systems. It supports all the same features as Azure DevOps Server 2019. +Once you have CI in place, you can create a release definition to automate the deployment of your application to one or more environments. The automation process is defined as a collection of tasks. -For more information, see [Pricing for Azure DevOps Server](https://azure.microsoft.com/pricing/details/devops/server/). +## Package formats -## Why should I use Azure Pipelines? +To produce packages that external users can consume, you can integrate package management into your CI/CD pipelines. You can publish NuGet, npm, Maven, or Python packages as artifacts to the built-in Azure Pipelines package management repository, or any other package management repository you choose. For more information about Azure Artifacts, see [Artifacts in Azure Pipelines](../artifacts/artifacts-overview.md). -Azure Pipelines provides a quick, easy, and safe way to automate building your projects with consistent and quality code that's readily available to users. +## Azure Pipelines pricing -Use Azure Pipelines to support the following scenarios: +::: moniker range=">= azure-devops" +If you use public projects, Azure Pipelines is free, but you need to [request the free grant of parallel jobs](https://aka.ms/azpipelines-parallelism-request). Existing organizations and projects don't need to request this grant. For more information, see [What is a public project](../../organizations/projects/about-projects.md). -* Works with any language or platform -* Deploys to different types of targets at the same time -* Integrates with Azure deployments -* Builds on Windows, Linux, or Mac machines -* Integrates with GitHub -* Works with open-source projects +If you use private projects, you can run up to 1,800 minutes or 30 hours of pipeline jobs free every month. -## Next steps +For more information, see [Pricing based on parallel jobs](../licensing/concurrent-jobs.md) +and [Pricing for Azure DevOps Services](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). -> [!div class="nextstepaction"] -> [Use Azure Pipelines](pipelines-get-started.md) +::: moniker-end -## Related articles +::: moniker range="< azure-devops" +For five or fewer active users, [Azure DevOps Express](https://azure.microsoft.com/services/devops/server/) is free, simple to set up, and installs on both client and server operating systems. It supports all the same features as Azure DevOps Server 2019. + +For more information, see [Pricing for Azure DevOps Server](https://azure.microsoft.com/pricing/details/devops/server/). + +::: moniker-end + +## Related content - [Sign up for Azure Pipelines](pipelines-sign-up.md) - [Create your first pipeline](../create-first-pipeline.md) - [Customize your pipeline](../customize-pipeline.md) + +> [!div class="nextstepaction"] +> [Use Azure Pipelines](pipelines-get-started.md) diff --git a/docs/pipelines/get-started/yaml-pipeline-editor.md b/docs/pipelines/get-started/yaml-pipeline-editor.md index 28a676ee450..20d3a333f65 100644 --- a/docs/pipelines/get-started/yaml-pipeline-editor.md +++ b/docs/pipelines/get-started/yaml-pipeline-editor.md @@ -2,10 +2,10 @@ title: YAML pipeline editor guide description: Learn how to author and edit pipelines with the YAML pipeline editor. ms.topic: reference -ms.date: 06/12/2023 +ms.date: 03/31/2025 author: steved0x ms.author: sdanie -monikerRange: '>=azure-devops-2019' +monikerRange: "<=azure-devops" --- # YAML pipeline editor @@ -14,34 +14,10 @@ monikerRange: '>=azure-devops-2019' Azure Pipelines provides a YAML pipeline editor that you can use to author and edit your pipelines. The YAML editor is based on the [Monaco Editor](https://github.com/microsoft/monaco-editor). The editor provides tools like Intellisense support and a task assistant to provide guidance while you edit a pipeline. -:::moniker range="azure-devops-2019" - -> [!IMPORTANT] -> The YAML pipeline editor was introduced in Azure DevOps Server 2019 Update 1. If you're using Azure DevOps Server 2019 RTW, the YAML pipeline editor described in this article isn't available, but you can edit your YAML using the text editor of your choice and check it into your pipeline's repository. - -:::moniker-end +This article shows you how to edit your pipelines using the YAML Pipeline editor, but you can also edit pipelines by modifying the **azure-pipelines.yml** file directly in your pipeline's repository using a text editor of your choice, or by using a tool like Visual Studio Code and the [Azure Pipelines for VS Code](https://github.com/Microsoft/azure-pipelines-vscode) extension. ## Edit a YAML pipeline -:::moniker range="= azure-devops-2019" - -To access the YAML pipeline editor, do the following steps. - -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Select your project, choose **Pipelines** > **Pipelines**, and then select the pipeline you want to edit. - - :::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-builds-2019-1.png" alt-text="Azure Pipelines builds in Azure DevOps Server 2019 Update 1."::: - -3. Choose **Edit**. - - :::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-edit-2019-1.png" alt-text="Azure Pipelines YAML edit button in Azure DevOps Server 2019 Update 1."::: - -4. Make edits to your pipeline using [Intellisense](#use-keyboard-shortcuts) keyboard shortcuts and the [task assistant](#use-task-assistant) for guidance. - - :::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-editor-2019-1.png" alt-text="YAML pipeline editor in Azure DevOps Server 2019.1."::: - -:::moniker-end - :::moniker range=">= azure-devops-2020" To access the YAML pipeline editor, do the following steps. @@ -55,16 +31,31 @@ To access the YAML pipeline editor, do the following steps. :::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-edit.png" alt-text="Azure Pipelines YAML edit button."::: + > [!IMPORTANT] + > The YAML pipeline editor is only available for YAML pipelines. If you are presented with a graphical user interface when you choose **Edit**, your pipeline was created using the classic pipeline designer. For information on converting your classic pipelines to YAML, see [Migrate your Classic pipeline to YAML](../release/from-classic-pipelines.md). + 4. Make edits to your pipeline using [Intellisense](#use-keyboard-shortcuts) and the [task assistant](#use-task-assistant) for guidance. :::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-editor.png" alt-text="YAML pipeline editor."::: :::moniker-end +:::moniker range=">= azure-devops-2020 < azure-devops" + 5. Choose **Save**. You can commit directly to your branch, or create a new branch and optionally start a pull request. :::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-save.png" alt-text="YAML pipeline editor save window."::: +:::moniker-end + +:::moniker range="azure-devops" + +5. Choose **Validate and save**. You can commit directly to your branch, or create a new branch and optionally start a pull request. + + :::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-validate-and-save.png" alt-text="Screenshot showing the YAML pipeline editor validate and save window."::: + +:::moniker-end + ### Use keyboard shortcuts The YAML pipeline editor provides several keyboard shortcuts, which we show in the following examples. @@ -99,14 +90,6 @@ The task assistant provides a method for adding tasks to your YAML pipeline. - Choose **Add** to insert the task YAML into your pipeline. -:::moniker range="= azure-devops-2019" - - :::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-task-assistant-task-added-2019-1.png" alt-text="Task assistant added in Azure DevOps Server 2019."::: - -- Edit the inserted YAML to make more configuration changes to the task. - -:::moniker-end - :::moniker range=">= azure-devops-2020" :::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-task-assistant-task-added.png" alt-text="Task assistant added."::: @@ -123,6 +106,24 @@ Validate your changes to catch syntax errors in your pipeline that prevent it fr :::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-validate.png" alt-text="Validate and Download full YAML."::: +:::moniker-end + +:::moniker range="azure-devops" + +Azure Pipelines validates your pipelines each time you save. Choose **Validate and save** to validate your pipeline before saving. If there are any errors, you can **Cancel** or **Save anyway**. To save your pipeline without validating, choose **Save without validating**. + +:::image type="content" source="media/yaml-pipeline-editor/yaml-pipeline-validate-and-save-button.png" alt-text="Screenshot showing the Validate and save button."::: + +:::moniker-end + +:::moniker range="azure-devops" + +Azure Pipelines detects incorrect variable definitions defined at the pipeline, stage, and job level and detects incorrect YAML conditions defined at the pipeline, stage, and job level. + +:::moniker-end + +:::moniker range=">= azure-devops-2020" + ## Download full YAML You can [preview the fully parsed YAML document](/azure/devops/release-notes/2020/sprint-165-update#preview-fully-parsed-yaml-document-without-committing-or-running-the-pipeline) without committing or running the pipeline. Choose **More actions** > **Download full YAML**. @@ -137,12 +138,6 @@ You can [preview the fully parsed YAML document](/azure/devops/release-notes/202 You can manage pipeline variables both from within your YAML pipeline and from the pipeline settings UI. -:::moniker range="= azure-devops-2019" - -With Azure DevOps 2019 Update 1, you can manage your pipeline variables using the pipeline settings UI. - -:::moniker-end - To manage pipeline variables, do the following steps. 1. Edit your YAML pipeline and choose **Variables** to manage pipeline variables. @@ -201,6 +196,16 @@ Some YAML pipeline settings are configured using the pipeline settings UI instea ## View and edit templates +:::moniker-end + +:::moniker range="=azure-devops-2022" + +[!INCLUDE [feature-added-2022-1](../../includes/feature-added-2022-1.md)] + +:::moniker-end + +:::moniker range=">= azure-devops-2022" + [Templates](../process/templates.md) are a commonly used feature in YAML pipelines. They're an easy way to share pipeline snippets and are a powerful mechanism for verifying and enforcing [security and governance](../security/templates.md) in your pipeline. Previously, the editor didn't support templates, so authors of YAML pipelines couldn't get intellisense assistance. Now Azure Pipelines supports a YAML editor, for which we're previewing support. To enable this preview, [go to preview features](../../project/navigation/preview-features.md) in your Azure DevOps organization, and enable **YAML templates editor**. diff --git a/docs/pipelines/includes/begin-create-build-definition.md b/docs/pipelines/includes/begin-create-build-definition.md index 435b0dc560f..e91e0e42f95 100644 --- a/docs/pipelines/includes/begin-create-build-definition.md +++ b/docs/pipelines/includes/begin-create-build-definition.md @@ -12,8 +12,8 @@ ms.date: 01/27/2023 :::image type="content" source="../media/browse-to-team-project.png" alt-text="Screenshot of Browse to project. "::: 1. (If you don't see your project listed on the home page, select **Browse**.) - * On-premises TFS: `http://{your_server}:8080/tfs/DefaultCollection/{your_project}` - * Azure Pipelines: `https://dev.azure.com/{your_organization}/{your_project}` + * On-premises TFS: `http://{your_server}:8080/tfs/DefaultCollection/{Your_Project}` + * Azure Pipelines: `https://dev.azure.com/{Your_Organization}/{Your_Project}` 1. Create a build pipeline (**Pipelines** > **Builds**). diff --git a/docs/pipelines/includes/concept-rename-note.md b/docs/pipelines/includes/concept-rename-note.md deleted file mode 100644 index 0865ef21ab1..00000000000 --- a/docs/pipelines/includes/concept-rename-note.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -ms.topic: include -ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: jukullam -author: juliakm -ms.date: 02/13/2020 ---- - -::: moniker range="tfs-2018" -> [!NOTE] -> In Microsoft Team Foundation Server (TFS) 2018 and previous versions, -build and release _pipelines_ are called _definitions_, -_runs_ are called _builds_, -_service connections_ are called _service endpoints_, -_stages_ are called _environments_, -and _jobs_ are called _phases_. - -::: moniker-end diff --git a/docs/pipelines/includes/create-first-pipeline-next-steps.md b/docs/pipelines/includes/create-first-pipeline-next-steps.md index b615a046220..288229f1dce 100644 --- a/docs/pipelines/includes/create-first-pipeline-next-steps.md +++ b/docs/pipelines/includes/create-first-pipeline-next-steps.md @@ -7,7 +7,7 @@ author: juliakm ms.date: 02/13/2020 --- -You've just learned how to create your first pipeline in Azure. Learn more about configuring pipelines in the language of your choice: +You learned how to create your first pipeline in Azure. Now, Learn more about configuring pipelines in the language of your choice: * [.NET Core](../ecosystems/dotnet-core.md) * [Go](../ecosystems/go.md) @@ -16,7 +16,7 @@ You've just learned how to create your first pipeline in Azure. Learn more about * [Python](../ecosystems/python.md) * [Containers](../ecosystems/containers/build-image.md) -Or, you can proceed to [customize the pipeline](../customize-pipeline.md) you just created. +Or, you can proceed to [customize the pipeline](../customize-pipeline.md) you created. To run your pipeline in a container, see [Container jobs](../process/container-phases.md). @@ -28,17 +28,20 @@ To find out what else you can do in YAML pipelines, see [YAML schema reference]( ### Clean up -If you created any test pipelines, they are easy to delete when you are done with them. +If you created any test pipelines, they're easy to delete when you finish with them. -#### [Browser](#tab/browser) +#### [Azure Pipelines UI](#tab/browser) To delete a pipeline, navigate to the summary page for that pipeline, and choose **Delete** from the **...** menu at the top-right of the page. Type the name of the pipeline to confirm, and choose **Delete**. ![Delete pipeline](../media/get-started-yaml/delete-pipeline.png) + #### [Azure DevOps CLI](#tab/azure-devops-cli/) -To delete a pipeline using Azure CLI, you can use the [az pipeline delete](/cli/azure/pipelines#ext-azure-devops-az-pipelines-delete) command. This command requires the `id` of the pipeline to delete, which you can get using the [az pipeline list](/cli/azure/pipelines#ext-azure-devops-az-pipelines-list) command. +::: moniker range="azure-devops" + +To delete a pipeline using Azure CLI, you can use the [az pipeline delete](/cli/azure/pipelines#ext-azure-devops-az-pipelines-delete) command. This command requires the `id` of the pipeline to delete, which you can find using the [az pipeline list](/cli/azure/pipelines#ext-azure-devops-az-pipelines-list) command. [List pipelines](#list-pipelines) | [Delete pipeline](#delete-pipeline) | [Example](#example) @@ -65,12 +68,12 @@ az pipelines list [--detect {false, true}] - **detect**: Automatically detect organization. Accepted values: **false**, **true** - **folder-path**: If specified, filters to definitions under this folder. -- **name**: Limit results to pipelines with this name or starting with this name. Examples: "FabCI" or "Fab*". +- **name**: Limit results to pipelines with this name or starting with this name. Examples: `FabCI` or `Fab*`. - **org** or **organization**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`. - **project** or **p**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up via git config. - **query-order**: Order of the results. Accepted values: **ModifiedAsc**, **ModifiedDesc**, **NameAsc**, **NameDesc**, **None** - **repository**: Limit results to pipelines associated with this repository. -- **repository-type**: Limit results to pipelines associated with this repository type. It is mandatory to pass **repository** argument along with this argument. Accepted values: **bitbucket**, **git**, **github**, **githubenterprise**, **svn**, **tfsgit**, **tfsversioncontrol** +- **repository-type**: Limit results to pipelines associated with this repository type. It's mandatory to pass **repository** argument along with this argument. Accepted values: **bitbucket**, **git**, **github**, **githubenterprise**, **svn**, **tfsgit**, **tfsversioncontrol** - **top**: Maximum number of pipelines to list. ### Delete pipeline @@ -91,7 +94,7 @@ az pipelines delete --id - **detect**: Automatically detect organization. Accepted values: **false**, **true** - **org** or **organization**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`. - **project** or **p**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up via git config. -- **yes** or **y**: Do not prompt for confirmation. +- **yes** or **y**: Don't prompt for confirmation. ### Example @@ -110,4 +113,8 @@ Are you sure you want to delete this pipeline? (y/n): y Pipeline 6 was deleted successfully. ``` -* * * +::: moniker-end + +[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] + +--- \ No newline at end of file diff --git a/docs/pipelines/includes/dotnet-setup.md b/docs/pipelines/includes/dotnet-setup.md index 731db31c49e..d4579028656 100644 --- a/docs/pipelines/includes/dotnet-setup.md +++ b/docs/pipelines/includes/dotnet-setup.md @@ -4,28 +4,31 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 11/05/2021 +ms.date: 12/01/2023 --- ### Create a .NET project -If you don't have a .NET project to work with, create a new one, and upload your code to your GitHub repository or Azure Repos. Start by installing the latest .NET 6.0 SDK. +If you don't have a .NET project to work with, create a new one on your local system. Start by installing the .NET 8.0 SDK . -Create a new .NET 6 webapp. +1. Open a terminal window. +1. Create a project directory and navigate to it. +1. Create a new .NET 8 webapp. -```dotnetcli -dotnet new webapp -f net6.0 -``` + ```dotnetcli + dotnet new webapp -f net8.0 + ``` -From the same terminal session, run the application locally using the [`dotnet run`](/dotnet/core/tools/dotnet-run) command from your project directory. +1. From the same terminal session, run the application locally using the [`dotnet run`](/dotnet/core/tools/dotnet-run) command from your project directory. -```dotnetcli -dotnet run -``` ---- + ```dotnetcli + dotnet run + ``` + +1. Once the application starts, press Ctrl-C to shut it down. + +### Create a git repo and connect it to GitHub -### Upload your code +1. From the project directory, [create a local git repository and commit the application code to the main branch](../../repos/git/creatingrepo.md#create-a-local-git-repo-from-an-existing-solution). -Upload your code to new webapp GitHub or Azure Repos: -* [Create a new Git repo in Azure Repos](../../repos/git/creatingrepo.md). -* [Create a new GitHub repository](https://docs.github.com/en/get-started/quickstart/create-a-repo). +1. [Connect your local Git repo to a GitHub repo](../../repos/git/creatingrepo.md#connect-a-local-git-repo-to-a-github-repo). diff --git a/docs/pipelines/includes/prerequisites.md b/docs/pipelines/includes/prerequisites.md index 7032c926a73..4836afad6aa 100644 --- a/docs/pipelines/includes/prerequisites.md +++ b/docs/pipelines/includes/prerequisites.md @@ -14,7 +14,7 @@ Make sure you have the following items: * An Azure DevOps organization. [Create one for free](../get-started/pipelines-sign-up.md). If your team already has one, then make sure you're an administrator of the Azure DevOps project that you want to use. -* An ability to run pipelines on Microsoft-hosted agents. To use Microsoft-hosted agents, your Azure DevOps organization must have access to Microsoft-hosted parallel jobs. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can [request a free grant](../troubleshooting/troubleshooting.md#check-for-available-parallel-jobs). +* An ability to run pipelines on Microsoft-hosted agents. To use Microsoft-hosted agents, your Azure DevOps organization must have access to Microsoft-hosted parallel jobs. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can [request a free grant](../troubleshooting/troubleshoot-start.md#check-for-available-parallel-jobs). diff --git a/docs/pipelines/includes/rm-help-support-shared.md b/docs/pipelines/includes/rm-help-support-shared.md index 12da6bbaa21..7a61fc68f00 100644 --- a/docs/pipelines/includes/rm-help-support-shared.md +++ b/docs/pipelines/includes/rm-help-support-shared.md @@ -4,12 +4,12 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 09/09/2020 +ms.date: 02/21/2024 --- ## Help and support -* See our [troubleshooting](../troubleshooting/troubleshooting.md) page -* Get advice on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops), - and feel free to post your questions, search for answers, or suggest a feature on our [Azure DevOps Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). [Support](https://azure.microsoft.com/support/devops/) page. - +* Explore [troubleshooting tips](../troubleshooting/troubleshooting.md). +* Get advice on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). +* Post your questions, search for answers, or suggest a feature in the [Azure DevOps Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). +* Get [support for Azure DevOps](https://azure.microsoft.com/support/devops/). diff --git a/docs/pipelines/includes/set-variables-in-scripts.md b/docs/pipelines/includes/set-variables-in-scripts.md index 2d19072295a..022cf765733 100644 --- a/docs/pipelines/includes/set-variables-in-scripts.md +++ b/docs/pipelines/includes/set-variables-in-scripts.md @@ -4,27 +4,23 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 08/19/2020 +ms.date: 08/16/2024 --- -

      Define and modify your variables in a script

      +#### Define and modify your variables in a script -To define or modify a variable from a script, use the `task.setvariable` logging command. -Note that the updated variable value is scoped to the job being executed, and does not flow across jobs or stages. -Variable names are transformed to uppercase, and the characters "." and " " are replaced by "_". +To define or modify a variable from a script, use the `task.setvariable` logging command. The updated variable value is scoped to the job being executed and doesn't persist across jobs or stages. Note that variable names are transformed to uppercase, with "." and " " replaced with "_". For example, `Agent.WorkFolder` becomes `AGENT_WORKFOLDER`. -On Windows, you access this as `%AGENT_WORKFOLDER%` or `$env:AGENT_WORKFOLDER`. -On Linux and macOS, you use `$AGENT_WORKFOLDER`. +- On Windows, access this variable as `%AGENT_WORKFOLDER%` or `$env:AGENT_WORKFOLDER`. +- On Linux and macOS, use `$AGENT_WORKFOLDER`. > [!TIP] > -> You can run a script on a: +> You can run a script on: > -> * [Windows agent](../agents/windows-agent.md) using either a [Batch script task](/azure/devops/pipelines/tasks/reference/batch-script-v1) or [PowerShell script task](/azure/devops/pipelines/tasks/reference/powershell-v2). -> * [macOS](../agents/osx-agent.md) or [Linux](../agents/linux-agent.md) agent using a [Shell script task](/azure/devops/pipelines/tasks/reference/shell-script-v2). - - +> - A [Windows agent](../agents/windows-agent.md) using either a [Batch script task](/azure/devops/pipelines/tasks/reference/batch-script-v1) or [PowerShell task](/azure/devops/pipelines/tasks/reference/powershell-v2). +> - A [macOS](../agents/osx-agent.md) or [Linux](../agents/linux-agent.md) agent using a [Shell script task](/azure/devops/pipelines/tasks/reference/shell-script-v2). # [Batch](#tab/batch) @@ -53,8 +49,7 @@ set sauceArgument=%~1 set secretSauceArgument=%~2 @echo No problem reading %sauceArgument% or %SAUCE% @echo But I cannot read %SECRET_SAUCE% -@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil - the secret) +@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil the secret) ``` # [PowerShell](#tab/powershell) @@ -86,8 +81,18 @@ Param( ) Write-Host No problem reading $env:SAUCE or $sauceArgument Write-Host But I cannot read $env:SECRET_SAUCE -Write-Host But I can read $secretSauceArgument "(but the log is redacted so I do not - spoil the secret)" +Write-Host But I can read $secretSauceArgument "(but the log is redacted so I do not spoil the secret)" +``` + +**Inline PowerShell script** + +Use the `sauce` and `secret.Sauce` variables in an inline script. + +```yaml +- pwsh: | + Write-Host No problem reading $(sauce) + Write-Host But I cannot read $env:SECRET_SAUCE + Write-Host But I can read $(secret.Sauce) "(but the log is redacted so I do not spoil the secret)" ``` # [Shell](#tab/shell) diff --git a/docs/pipelines/index.yml b/docs/pipelines/index.yml index 8f6a409da8b..b922a01d188 100644 --- a/docs/pipelines/index.yml +++ b/docs/pipelines/index.yml @@ -7,11 +7,10 @@ metadata: title: Azure Pipelines documentation titleSuffix: Azure DevOps description: Configure and manage continuous integration and continuous delivery (CI/CD) for the app and platform of your choice. - ms.technology: devops-cicd ms.assetid: 00f4ed452-fbb8-45f9-8f0a-343702aac5b8 ms.topic: landing-page - author: KathrynEE - ms.author: kaelli + author: steved0x + ms.author: sdanie ms.date: 09/27/2021 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -63,7 +62,7 @@ landingContent: - text: Python apps url: ./ecosystems/python.md - text: PHP - url: ./ecosystems/python-webapp.md + url: ./ecosystems/php.md - text: "See more >" url: ./ecosystems/ecosystems.md - title: Key concepts @@ -217,4 +216,4 @@ landingContent: - text: Integrate with Microsoft Teams url: ./integrations/microsoft-teams.md - text: Integrate with service hooks - url: ../service-hooks/overview.md \ No newline at end of file + url: ../service-hooks/overview.md diff --git a/docs/pipelines/integrations/configure-pipelines-work-tracking.md b/docs/pipelines/integrations/configure-pipelines-work-tracking.md index 768ea75d041..46259d29f2e 100644 --- a/docs/pipelines/integrations/configure-pipelines-work-tracking.md +++ b/docs/pipelines/integrations/configure-pipelines-work-tracking.md @@ -8,23 +8,22 @@ ms.author: chcomley author: chcomley ms.custom: cross-service monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 09/09/2024 --- # Configure pipelines to support work tracking [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -To support integration and traceability across Azure DevOps Services with pipelines, you can configure several options. You can report pipeline status, copy the syntax for status badges, and set up automatic linking of work items to builds and releases. - +To support integration and traceability across Azure DevOps Services with pipelines, you can configure several options. You can report pipeline status, copy the syntax for status badges, and set up automatic linking of work items to builds and releases. ## Supported pipeline and work tracking integration features -Several features provide support for end-to-end traceability as user stories and features move through the development cycle. As with Azure Repos, you can link work items to pipeline objects with the following link types: *Build, Integrated in build*, and *Integrated in release*. Note, that the *Integrated in release environment* link can only be created by enabling the **Report release status to Boards** option in Classic release pipelines. +Several features provide support for end-to-end traceability as user stories and features move through the development cycle. As with Azure Repos, you can link work items to pipeline objects with the following link types: *Build, Integrated in build*, and *Integrated in release*. The *Integrated in release environment* link can only be created by enabling the **Report release status to Boards** option in Classic release pipelines. :::image type="content" source="media/pipelines-integration/concept-link-types-pipelines.png" alt-text="Conceptual image of link types that link work items to Azure Pipelines objects."::: -The following table summarizes the integration points between Azure Boards and Azure Pipelines. Options and configuration steps differ depending on whether you are configuring a YAML or Classic pipeline, and your Azure DevOps version. Most options are supported for pipelines run against an Azure Repos Git repository unless otherwise noted. +The following table summarizes the integration points between Azure Boards and Azure Pipelines. Options and configuration steps differ depending on whether you're configuring a YAML or Classic pipeline, and your Azure DevOps version. Most options are supported for pipelines run against an Azure Repos Git repository unless otherwise noted. :::row::: :::column span="2"::: @@ -43,7 +42,7 @@ The following table summarizes the integration points between Azure Boards and A Manually link work items to builds :::column-end::: :::column span="2"::: - You can link from a work item to builds within the same project or other projects within the organization. For details, see [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md). + You can link from a work item to builds within the same project or other projects within the organization. For more information, see [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md). :::column-end::: :::column span="1"::: All versions @@ -55,7 +54,7 @@ The following table summarizes the integration points between Azure Boards and A View builds linked to from a work item :::column-end::: :::column span="2"::: - You can view all builds linked to from a work item, whether manual or automatically linked, from the Links tab. For details, see [Link to work items from other objects, View list of linked objects](../../organizations/notifications/add-links-to-work-items.md#view-list-links). + You can view all builds linked to from a work item, whether manual or automatically linked, from the Links tab. For more information, see [Link to work items from other objects, View list of linked objects](../../organizations/notifications/add-links-to-work-items.md#view-list-links). :::column-end::: :::column span="1"::: All versions @@ -67,11 +66,10 @@ The following table summarizes the integration points between Azure Boards and A Automatically link work items to builds :::column-end::: :::column span="2"::: - Required to populate the **Development** control with *Integrated in build* links. The work items or commits that are part of a release are computed from the versions of artifacts. For example, each build in Azure Pipelines is associated with a set of work items and commits. For details, see [Automatically link work items](#auto-link-work-items-builds) later in this article. + Required to populate the **Development** control with *Integrated in build* links. The work items or commits that are part of a release are computed from the versions of artifacts. For example, each build in Azure Pipelines is associated with a set of work items and commits. For more information, see [Automatically link work items](#auto-link-work-items-builds) later in this article. :::column-end::: :::column span="1"::: - YAML, Azure DevOps Server 2020 and later - Classic, TFS 2017.2 and later + YAML, Azure DevOps Server 2020 and later :::column-end::: :::row-end::: --- @@ -81,7 +79,7 @@ The following table summarizes the integration points between Azure Boards and A Automatically link work items to releases and report deployment status to a work item (Classic only) :::column-end::: :::column span="2"::: - Required to populate **Deployment** control in work item form with *Integrated in release stage* links. For details, see [Report deployment status to Boards](#classic-report-boards) later in this article. + Required to populate **Deployment** control in work item form with *Integrated in release stage* links. For more information, see [Report deployment status to Boards](#classic-report-boards) later in this article. :::column-end::: :::column span="1"::: Azure DevOps Server 2020 and later @@ -97,8 +95,7 @@ The following table summarizes the integration points between Azure Boards and A Review and open the work items included in a build or release. :::column-end::: :::column span="1"::: - YAML, Azure DevOps Server 2020 and later - Classic, TFS 2017.2 and later + YAML, Azure DevOps Server 2020 and later :::column-end::: :::row-end::: --- @@ -107,10 +104,10 @@ The following table summarizes the integration points between Azure Boards and A Create work item on failure (Classic) :::column-end::: :::column span="2"::: - Automatically create a work item when a build fails, and optionally set values for work item fields. For details, see [Create work item on failure](#create-work-item-on-failure) later in this article. + Automatically create a work item when a build fails, and optionally set values for work item fields. For more information, see [Create work item on failure](#create-work-item-on-failure) later in this article. :::column-end::: :::column span="1"::: - TFS 2018 and later versions + 2018 and later versions :::column-end::: :::row-end::: --- @@ -120,7 +117,7 @@ The following table summarizes the integration points between Azure Boards and A Query Work Items task, ensure the number of matching work items returned from a query is within a threshold. :::column-end::: :::column span="2"::: - Use this task to ensure the number of matching items returned by a work item query is within the configured thresholds. For details, see [Query Work Items task, Control deployments with gates and approvals](/azure/devops/pipelines/tasks/reference/query-work-items-v0). + Use this task to ensure the number of matching items returned by a work item query is within the configured thresholds. For more information, see [Query Work Items task, Control deployments with gates and approvals](/azure/devops/pipelines/tasks/reference/query-work-items-v0). :::column-end::: :::column span="1"::: Azure DevOps Server 2020 and later versions @@ -129,20 +126,17 @@ The following table summarizes the integration points between Azure Boards and A --- ::: moniker-end - ## Prerequisites - To configure the integration options for a Classic release pipeline, you must have permissions to edit the release. - To link work items to commits and pull requests, you must have your **Edit work items in this node** permissions set to **Allow** for the Area Path assigned to the work item. By default, the Contributors group has this permission set. - To view work items, you must have your **View work items in this node** permissions set to **Allow** for the Area Path assigned to the work item. - ## Open pipeline settings, build options, or integration options - # [YAML](#tab/yaml) - + **Open Pipeline settings** @@ -154,124 +148,87 @@ For YAML-defined release pipelines, you configure the integration through the ** :::image type="content" source="media/pipelines-integration/open-pipeline-settings.png " alt-text="Open Pipeline settings."::: - The Pipeline Settings dialog appears. For details on automatic linking, see [Automatically link work items](#auto-link-work-items-builds) later in this article. + The Pipeline Settings dialog appears. For more information on automatic linking, see [Automatically link work items](#auto-link-work-items-builds) later in this article. :::image type="content" source="media/pipelines-integration/pipeline-settings-enable-link-work-items.png" alt-text="YAML Pipeline settings dialog."::: -::: moniker-end -::: moniker range="< azure-devops-2020" -This setting isn't available for Azure DevOps Server 2019 or earlier versions. ::: moniker-end # [Classic Build](#tab/classic-build) - - - + + **Build properties** Open the build pipeline, choose to edit the pipeline, and then choose the **Options** tab. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::image type="content" source="media/pipelines-integration/open-classic-build-properties-options.png" alt-text="Screenshot of Classic Build pipeline, Options tab."::: ::: moniker-end -::: moniker range="tfs-2018" -:::image type="content" source="media/pipelines-integration/open-classic-build-properties-options-tfs-2018.png" alt-text="Build and Release pipeline Build properties dialog, TFS-2018."::: -::: moniker-end + The Build properties page appears. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::image type="content" source="media/pipelines-integration/classic-build-options.png" alt-text="Build properties dialog."::: -For details on each setting, use one of the following links: -- [Build number format](../release/index.md#how-do-i-manage-the-names-for-new-releases) +For more information on each setting, use one of the following links: +- [Build number format](../release/index.md#q-how-do-i-manage-the-naming-of-new-releases) - [Automatically link work items](#auto-link-work-items-builds) - [Create work item on failure](#create-work-item-on-failure) - [Status badge](#status-badge) ::: moniker-end -::: moniker range="tfs-2018" -:::image type="content" source="media/pipelines-integration/build-properties-tfs-2018.png" alt-text="Build properties dialog, TFS-2018."::: - -For details on each setting, use one of the following links: -- [Build number format](../release/index.md#how-do-i-manage-the-names-for-new-releases) -- [Badge enabled](#status-badge) -- [Automatically link work items](#auto-link-work-items-builds) -- [Create work item on failure](#create-work-item-on-failure) - -::: moniker-end - + # [Classic Release](#tab/classic-release) - + **Release integration options** For Classic release pipelines, open **Pipelines>Releases**, choose to edit your pipeline, then choose **Options** and then **Integrations**. - ::: moniker range=">= azure-devops-2020" > [!div class="mx-imgBorder"] > ![Screenshot of Integrations options for Classic pipelines](media/pipelines-integration/integration-options-classic.png) - -For details on each setting, use one of the following links: -- [Report deployment status to the repository host](../release/index.md#reportstatus) +For more information on each setting, use one of the following links: +- [Report deployment status to the repository host](#report-deployment-status-to-the-repository-host-classic) - [Report deployment status to Work](#auto-link-work-items-builds) - [Report deployment status to Boards](#classic-report-boards) -- [Report deployment status to Jira](../release/index.md#reportstatus) +- [Report deployment status to Jira](#report-deployment-status-to-jira-classic) - [Enable the deployment status badge](#enable-status-badge) ::: moniker-end -::: moniker range="<= azure-devops-2019" -> [!div class="mx-imgBorder"] -> ![Screenshot of Integrations options for Classic pipelines, Azure DevOps 2019 and earlier versions](../release/media/what-is-release-management/report-options.png) - -For details on each setting, use one of the following links: -- [Report deployment status to the repository host](../release/index.md#reportstatus) -- [Report deployment status to Work](#auto-link-work-items-builds) -- [Enable the deployment status badge](#status-badge) -::: moniker-end + *** - - - - - + ::: moniker range=">= azure-devops-2020" ## Automatically link work items to builds or releases -By enabling automatic linking, you can track the builds or releases that have incorporated work without having to manually search through a large set of builds or releases. Each successful build associated with the work item automatically appears in the **Development** control of the work item form. Each release stage associated with the work item automatically appears in the **Deployment** control of the work item form. +By enabling automatic linking, you can track the builds or releases that incorporated work without having to manually search through a large set of builds or releases. Every successful build associated with the work item automatically appears in the **Development** control of the work item form. Each release stage associated with the work item automatically appears in the **Deployment** control of the work item form. ::: moniker-end -::: moniker range="< azure-devops-2020" - -## Automatically link work items to builds - -By enabling automatic linking, you can track the builds that have incorporated work without having to manually search through a large set of builds. Each successful build associated with the work item automatically appears in the **Development** control of the work item form. - -::: moniker-end - - + + # [YAML](#tab/yaml) ::: moniker range=">= azure-devops-2020" -1. Open **Pipeline settings** as describe in [Open Pipeline settings](#yaml-open-settings). +1. Open **Pipeline settings** as described in [Open Pipeline settings](#yaml-open-settings). 1. Enable **Automatically link new work in this build**. @@ -280,14 +237,10 @@ By enabling automatic linking, you can track the builds that have incorporated w Once enabled, **Integrated in build** links are generated for all work items linked to the selected pull request with each release run. ::: moniker-end -::: moniker range="< azure-devops-2020" -This feature isn't supported for YAML pipelines in Azure DevOps Server 2019. -::: moniker-end - # [Classic Build](#tab/classic-build) -1. Open pipeline **Build properties** as describe in [Build properties](#classic-build-properties). +1. Open pipeline **Build properties** as described in [Build properties](#classic-build-properties). 1. Enable **Automatically link work items included in this run**. Add the branches to include or exclude. :::image type="content" source="media/pipelines-integration/auto-link-work-items-classic-build-pipeline.png" alt-text="Screenshot of Automatically link work items in this build property settings."::: @@ -302,17 +255,17 @@ This feature isn't supported for YAML pipelines in Azure DevOps Server 2019. # [Classic Release](#tab/classic-release) - + ::: moniker range=">= azure-devops-2020" -Prior to choosing your integration options, you should set up the release stages as described in [Define your multi-stage continuous deployment (CD) pipeline](../../pipelines/release/define-multistage-release-process.md). +Before you choose integration options, set up the release stages as described in [Define your multi-stage continuous deployment (CD) pipeline](../../pipelines/release/define-multistage-release-process.md). 1. Open **Options>Integrations** for the release pipeline as describe in [Release integration options](#classic-release-options). -1. Check the **Report deployment status to Boards** checkbox. Map the **Deployment type** to each stage, or leave **Unmapped**. Select this option if you want to create links to all work items that represent associated changes to the source, when a release is complete. This option must be enabled in order for the work item form [**Deployment**](../../boards/work-items/work-item-deployments-control.md) control to work. +2. Check the **Report deployment status to Boards** checkbox. Map the **Deployment type** to each stage, or leave **Unmapped**. Select this option if you want to create links to all work items that represent associated changes to the source, when a release is complete. This option must be enabled in order for the work item form [**Deployment**](../../boards/backlogs/add-link.md#link-work-items-to-deployments) control to work. - :::image type="content" source="media/pipelines-integration/release-settings-stages-1.png" alt-text="Screenshot of Report deployment status to Boards, Classic release, 5 stages."::: + :::image type="content" source="media/pipelines-integration/release-settings-stages-1.png" alt-text="Screenshot of Report deployment status to Boards, Classic release, five stages."::: To view a list of work items linked to the release, choose **Release (old view)** from :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: **More commands**, and then choose the **Work Items** tab. @@ -324,24 +277,19 @@ Prior to choosing your integration options, you should set up the release stages To verify the integration is working, perform the following steps: -1. Link one or more work items to a commit or pull request in Azure Repos Git repository. For details, see: +1. Link one or more work items to a commit or pull request in Azure Repos Git repository. For more information, see: - [Drive Git development from a work item](../../boards/backlogs/connect-work-items-to-git-dev-ops.md) - [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md) 1. Run the pipeline. -1. Open one of the linked work items and view the [**Deployment**](../../boards/work-items/work-item-deployments-control.md) control control. As shown in the following image, the **Deployment** control shows release information for two release stages those work items that have been linked to a Git commit or pull request for a release pipeline configured to integrate with Azure Boards. +2. Open one of the linked work items and view the [**Deployment**](../../boards/backlogs/add-link.md#link-work-items-to-deployments) control. As shown in the following image, the **Deployment** control shows release information for two release stages those work items that linked to a Git commit or pull request for a release pipeline configured to integrate with Azure Boards. :::image type="content" source="../../boards/work-items/media/deployments-control/deployment-control-intro.png " alt-text="Screenshot of Work item form, Deployment control."::: ::: moniker-end -::: moniker range="< azure-devops-2019" - -This feature isn't supported for Azure DevOps Server 2019 and earlier versions. -::: moniker-end - *** ### What work items are included in automatic linking? @@ -350,7 +298,7 @@ When developing your software, you can link work items when you create a branch, :::image type="content" source="media/pipelines-integration/create-branch-link-work-item.png" alt-text="Create branch dialog from work item form."::: -When automatically linking work items to builds, the following computations are made: +When you automatically link work items to builds, the following computations are made: - For a first-time build: - Identify all work items linked to the branch, commits, and pull requests associated with the build. @@ -361,7 +309,7 @@ When automatically linking work items to builds, the following computations are - Identify all work items associated with the commits between C1 and C2 in the commit tree. - + ## Create work item on build failure (Classic) @@ -372,9 +320,9 @@ If a build pipeline fails, you can automatically create a work item to track get > The option to **Create work item on failure** is only supported for Classic pipelines. To accomplish this with a YAML pipeline, you can use a marketplace extension like [Create Bug on Release failure](https://marketplace.visualstudio.com/items?itemName=AmanBedi18.CreateBugTask) or you can [implement it yourself using Azure CLI or REST API calls](../customize-pipeline.md#create-work-item-on-failure). - + -1. Open pipeline build options as describe in [Build properties](#classic-build-properties). +1. Open pipeline build options as described in [Build properties](#classic-build-properties). 2. Enable **Create work item on failure** and choose the type of work item to create. Optionally check the **Assign to requestor** checkbox to set the **Assign To** field and add fields to set within the work item to create. @@ -384,9 +332,9 @@ If a build pipeline fails, you can automatically create a work item to track get 3. Save your pipeline. -To learn the reference name for a field, look it up from the [Work item field index](../../boards/work-items/guidance/work-item-field.md). For custom fields you add through an inherited process, Azure DevOps assigns a reference name based on friendly field name prefixed with *Custom.*. For example, you add a field named **DevOps Triage**, the reference name is Custom.DevOpsTriage. No spaces are allowed within the reference name. +To learn the reference name for a field, look it up from the [Work item field index](../../boards/work-items/guidance/work-item-field.md). For custom fields you add through an inherited process, Azure DevOps assigns a reference name based on friendly field name prefixed with *Custom.* For example, you add a field named **DevOps Triage**. The reference name is Custom.DevOpsTriage. No spaces are allowed within the reference name. - + ## Get or enable a status badge @@ -400,12 +348,11 @@ To learn the reference name for a field, look it up from the [Work item field in :::image type="content" source="media/pipelines-integration/status-badge-yaml.png" alt-text="Screenshot of YAML pipeline status badge."::: - - + # [Classic Build](#tab/classic-build) -1. Open pipeline **Build properties** as describe in [Build properties](#classic-build-properties). +1. Open pipeline **Build properties** as described in [Build properties](#classic-build-properties). 1. Choose :::image type="icon" source="../../media/icons/copy.png" border="false"::: **Copy to clipboard** to copy the image or Markdown syntax. @@ -429,16 +376,14 @@ Select this option if you want to display the latest outcome of a stage deployme *** - - +For enhanced security, use the [Publish To Azure Service Bus v2 task](/azure/devops/pipelines/tasks/reference/publish-to-azure-service-bus-v2) instead of an Azure Service Bus service connection to send a message to Azure Service Bus. This version of the task supports Microsoft Entra ID and workload identity federation. ### Bitbucket Cloud service connection Use OAuth with **Grant authorization** or a username and password with **Basic Authentication** to define a connection to Bitbucket Cloud. For pipelines to keep working, your repository access must remain active. -### Grant authorization +| Parameter | Description | +|-----------------------|-----| +| Authentication method | Select **Grant authorization** or **Basic Authentication**.| +| OAuth configuration | Required for Grant authorization. OAuth connection to Bitbucket. | +| Username | Required for Basic authentication. The username to connect to the service.| +| Password | Required for Basic authentication. The password for the specified username.| +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | -| Parameter | Description | -| --------- | ----------- | -| OAuth configuration | Required. OAuth connection to Bitbucket. | +Select **Verify** or **Authorize** to validate your connection information. -### Basic authentication +### Cargo service connection + +Use the following parameters to define and secure a connection to a [Cargo](../../artifacts/get-started-cargo.md) artifact repository. | Parameter | Description | | --------- | ----------- | -| Connection name | Required. The name you use to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -| User name | Required. The username to connect to the service. | -| Password | Required. The password for the specified username. | +| Authentication method | Choose the authentication method to the artifacts repository: **Basic username/password (including Azure DevOps PATs)** or **Authorization value (including crates.io tokens)**. | +| Repository URL | Required. URL for the repository. For crates.io, use `https://crates.io` | +| Username | Required when Basic authentication is selected. Username for connecting to the endpoint. The value can be arbitrary if using personal access tokens or the Authorization value authentication method. | +| Password | Required when Basic authentication is selected. Password for connecting to the endpoint. Personal access tokens are applicable for Azure DevOps Services organizations. | +| Token | Required when **Authorization value** authentication is selected. | +| Service connection name | Name for the service connection | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | ### Chef service connection @@ -383,10 +265,13 @@ Use the following parameters to define and secure a connection to a [Chef](https | Parameter | Description | | --------- | ----------- | -| Connection name | Required. The name you use to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | | Server URL | Required. The URL of the Chef automation server. | -| Node Name (Username) | Required. The name of the node to connect to. Typically this is your username. | +| Node Name (Username) | Required. The name of the node to connect to. Typically this parameter is your username. | | Client Key | Required. The key specified in the Chef .pem file. | +| Service connection name | Name for the service connection | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | ### Docker Host service connection @@ -394,50 +279,96 @@ Use the following parameters to define and secure a connection to a Docker host. | Parameter | Description | | --------- | ----------- | -| Connection name | Required. The name you use to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | | Server URL | Required. The URL of the Docker host. | | CA certificate | Required. A trusted certificate authority certificate to use to authenticate with the host. | | Certificate | Required. A client certificate to use to authenticate with the host. | | Key | Required. The key specified in the Docker key.pem file. | +| Service connection name | Name for the service connection | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | For more information about protecting your connection to the Docker host, see [Protect the Docker daemon socket](https://docs.docker.com/engine/security/https/). ### Docker Registry service connection -Use the following parameters to define a connection to a container registry for either [Azure Container Registry](#azure-container-registry) or [Docker Hub or others](#docker-hub-or-others). +You can create a service connection to a Docker container registry. -#### Azure Container Registry +Select the registry type: -| Parameter | Description | -| --------- | ----------- | -| Connection name | Required. The name you use to refer to the service connection in task inputs. | -| Azure subscription | Required. The Azure subscription containing the container registry to be used for service connection creation. | -| Azure Container Registry | Required. The Azure Container Registry to be used for creation of service connection. | +::: moniker range="azure-devops" +* [Docker Hub](#docker-hub-or-others) +* [Others](#docker-hub-or-others) +* [Azure Container Registry](#azure-container-registry) +::: moniker-end +::: moniker range="< azure-devops" +* [Docker Hub](#docker-hub-or-others) +* [Others](#docker-hub-or-others) +::: moniker-end + +#### Docker Hub or Others -#### Docker Hub or others +Enter the following parameters to define a connection to a **Docker Hub** registry or **Others**. | Parameter | Description | | --------- | ----------- | -| Connection name | Required. The name you use to refer to the service connection in task inputs. | | Docker Registry | Required. The URL of the Docker registry. | | Docker ID | Required. The identifier of the Docker account user. | -| Password | Required. The password for the account user identified above. (Docker Hub requires a PAT instead of a password.) | +| Docker Password | Required. The password for the Docker ID. (Docker Hub requires a PAT instead of a password.) | | Email | Optional. An email address to receive notifications. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | -### Other Git service connection +You can select **Verify** to verify your credentials before entering the rest of the parameters. -Use the following parameters to define and secure a connection to an external Git repository server. -There's a specific service connection for [GitHub](#github-service-connection) and [GitHub Enterprise Server](#github-enterprise-server-service-connection). +#### Azure Container Registry + +::: moniker range="< azure-devops" +Azure Container Registry is not available in Azure DevOps Server. +::: moniker-end + +::: moniker range="azure-devops" +You can connect to an Azure Container Registry using either a [Service Principal](#service-principal-authentication-type), [Managed Identity](#managed-identity-authentication-type), or [Workload Identity federation](#workload-identity-federation-authentication-type) **Authentication Type**. + +##### Service Principal authentication type + +Enter the following parameters to define a connection to an Azure Container Registry using a service principal. | Parameter | Description | | --------- | ----------- | -| Connection name | Required. The name you use to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -| Server URL | Required. The URL of the Git repository server. | -| Attempt accessing this Git server from Azure Pipelines | When checked, Azure Pipelines attempts to connect to the repository before queuing a pipeline run. You can disable this setting to improve performance when working with repositories that are not publicly accessible. Note that [CI triggers](../repos/pipeline-options-for-git.md#trigger-options-for-other-git) will not work in when an **Other Git** repository is not publicly accessible. You can only start manual or scheduled pipeline runs. | -| User name | Required. The username to connect to the Git repository server. | -| Password/Token key | Required. The password or access token for the specified username. | +| Subscription | Required. The Azure subscription containing the container registry to be used for service connection creation. | +| Azure Container Registry | Required. The Azure Container Registry to be used for creation of service connection. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | -For more information, see [Artifact sources](../release/artifacts.md#artifact-sources). +##### Managed Identity authentication type + +Enter the following parameters to define a connection to an Azure Container Registry using a **Managed Service Identity**. + +| Parameter | Description | +| --------- | ----------- | +| Subscription ID | Required. The GUID-like identifier for your Azure subscription (not the subscription name). You can copy the subscription ID from the Azure portal. | +| Subscription name | Required. The name of your Microsoft Azure subscription. | +| Tenant ID | Required. The GUID-like identifier for your Microsoft Entra ID tenant. You can copy the tenant ID from the Azure portal. | +| Azure container registry login server | Required. The login server of the Azure Container Registry. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | + +##### Workload Identity federation authentication type + +Enter the following parameters to define a connection to an Azure Container Registry using **Workload Identity federation**. + +| Parameter | Description | +| --------- | ----------- | +| Subscription | Required. The Azure subscription containing the container registry to use for service connection creation. | +| Azure container registry | Required. The Azure Container Registry instance to use for creation of the service connection. | +| Connection name | Required. A name to use to refer to the service connection in task properties. For YAML pipelines, use the name as the **azureSubscription** or other connection name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | +::: moniker-end ### Generic service connection @@ -445,23 +376,28 @@ Use the following parameters to define and secure a connection to any generic ty | Parameter | Description | | --------- | ----------- | -| Connection name | Required. The name you use to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | | Server URL | Required. The URL of the service. | -| User name | Optional. The username to connect to the service. | +| Username | Optional. The username to connect to the service. | | Password/Token key | Optional. The password or access token for the specified username. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | ### GitHub service connection -Use the following parameters to define a connection to a GitHub repository. +Use the following parameters to define a connection to a GitHub repository. > [!TIP] > There's a specific service connection for [Other Git servers](#other-git-service-connection) and [GitHub Enterprise Server connections](#github-enterprise-server-service-connection). |Parameter | Description | -|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Choose authorization | Required. Either **Grant authorization** or **Personal access token**. See notes below.| -| Token| Required for Personal access token authorization. See notes below. | -|Connection name | Required. The name you use to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +|----------------------|----| +| Choose authorization | Required. Either **Grant authorization** or **Personal access token**. | +| Token| Required for Personal access token authorization. Your GitHub Personal Access Token (PAT). | +| Grant authorization | Required for Grant authorization. The OAuth Configuration to use to connect to the service. For example, select **AzurePipelines** to connect the Azure Pipeline. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | > [!NOTE] > If you select **Grant authorization** for the **Choose authorization** option, the dialog shows an **Authorize** button that opens the GitHub signing page. If you select **Personal access token**, paste it into the **Token** textbox. The dialog shows the recommended scopes for the token: **repo, user, admin:repo_hook**. For more information, see @@ -472,26 +408,28 @@ Then, complete the following steps to register your GitHub account in your profi 2. Choose **Personal access tokens**. 3. Select **Add** and enter the information required to create the token. -For more information, see [Artifact sources - version control](../release/artifacts.md#artifact-sources---version-control). +For more information, see [Artifact sources - version control](../release/artifacts.md#azure-repos-github-and-tfvc). ### GitHub Enterprise Server service connection -Use the following parameters to define a connection to a GitHub repository. +Use the following parameters to define a connection to a GitHub Enterprise repository. > [!TIP] > There's a specific service connection for [Other Git servers](#other-git-service-connection) and [standard GitHub service connections](#github-service-connection). | Parameter| Description | -|--------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|Choose authorization| Required. Either **Personal access token**, **Username and Password**, or **OAuth2**. See notes below. | -| Connection name| Required. The name you use to refer to the service connection in task properties. This isn't the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -| Server URL | Required. The URL of the service.| -| Accept untrusted TLS/SSL certificates| Set this option to allow clients to accept a self-signed certificate instead of installing the certificate in the TFS service role or the computers hosting the [agent](../agents/agents.md).| -| Token | Required for Personal access token authorization. See notes below. | -| User name| Required for Username and Password authentication. The username to connect to the service. | -|Password| Required for Username and Password authentication. The password for the specified username. | -| OAuth configuration | Required for OAuth2 authorization. The OAuth configuration specified in your account. | +|--|----| +|Choose authorization| Required. Either **Personal access token**, **Username and Password**, or **OAuth2**. | +| Server URL | Required. The URL of the service.| +| Accept untrusted TLS/SSL certificates| Set this option to allow clients to accept a self-signed certificate instead of installing the certificate in the Azure Pipelines service role or the computers hosting the [agent](../agents/agents.md).| +| Token | Required for Personal access token authorization. | +| Username| Required for Username and Password authentication. The username to connect to the service. | +| Password | Required for Username and Password authentication. The password for the specified username. | +| OAuth configuration | Required for OAuth2 authorization. You can use an existing OAuth configuration or create a new configuration. | | GitHub Enterprise Server configuration URL |The URL is fetched from OAuth configuration.| +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | > [!NOTE] > If you select **Personal access token** (PAT) you must paste the PAT into the **Token** textbox. The dialog shows the recommended scopes for the token: **repo, user, admin:repo_hook**. For more information, see @@ -502,51 +440,81 @@ Then, complete the following steps to register your GitHub account in your profi 2. Choose **Personal access tokens**. 3. Select **Add** and enter the information required to create the token. +### Incoming WebHook service connection + +Use the following parameters to create an incoming Webhook service connection. + +| Parameter | Description | +|--|--| +| WebHook Name | Required. The name of the WebHook. | +| Secret | Optional. The secret to use to authenticate with the WebHook. | +| HTTP Header | Optional. The headers name on which checksum is sent. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | + ### Jenkins service connection Use the following parameters to define a connection to the Jenkins service. | Parameter | Description | -|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Connection name | Required. The name you use to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -|Server URL | Required. The URL of the service.| -| Accept untrusted TLS/SSL certificates | Set this option to allow clients to accept a self-signed certificate instead of installing the certificate in the TFS service role or the computers hosting the [agent](../agents/agents.md).| -| User name | Required. The username to connect to the service. | +|--|--| +| Server URL | Required. The URL of the Jenkins server. | +| Accept untrusted TLS/SSL certificates | Set this option to allow clients to accept a self-signed certificate instead of installing the certificate in the Azure Pipelines service role or the computers hosting the [agent](../agents/agents.md).| +| Username | Required. The username to connect to the service. | | Password | Required. The password for the specified username.| +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | + +You can select **Verify** to verify your credentials before entering the rest of the parameters. -For more information, see [Azure Pipelines Integration with Jenkins](https://azuredevopslabs.com/labs/vstsextend/jenkins/) and [Artifact sources - Jenkins](../release/artifacts.md#artifact-sources---jenkins). +For more information, see [Azure Pipelines Integration with Jenkins](https://azuredevopslabs.com/labs/vstsextend/jenkins/) and [Artifact sources - Jenkins](../release/artifacts.md#jenkins). + +### Jira service connection + +Use the following parameters to define a connection to the Jira service. + +| Parameter | Description | +|--|--| +| Server URL | Required. The URL of the Jira server. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | ### Kubernetes service connection -Use the following parameters when you define a connection to a Kubernetes cluster. Choose from the following service connection options: +Use the following parameters when you define a connection to a Kubernetes cluster. Choose the **Authentication method** from the following options: -* Azure subscription -* Service account * Kubeconfig +* Service account +* Azure subscription -#### Azure subscription option +#### Kubeconfig option | Parameter | Description | -| --------- | ----------- | -| Connection name | Required. The name you use to refer to the service connection in task inputs. | -| Azure subscription | Required. The Azure subscription containing the cluster to be used for service connection creation. | -| Cluster | Name of the Azure Kubernetes Service cluster. | -| Namespace | Namespace within the cluster. | - -For an Azure RBAC enabled cluster, a ServiceAccount gets created in the chosen namespace along with RoleBinding object, so that the created ServiceAccount can do actions only on the chosen namespace. - -For an Azure RBAC disabled cluster, a ServiceAccount gets created in the chosen namespace, but, the created ServiceAccount has cluster-wide privileges (across namespaces). +| --------- | ----------| +| Kubeconfig | Required. Contents of the kubeconfig file. | +| Cluster context | Optional. Context within the kubeconfig file that is to be used for identifying the cluster. | +| Accept untrusted certificates | Set this option to allow clients to accept a self-signed certificate. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | > [!NOTE] -> This option lists all the subscriptions the service connection creator has access to *across different Azure tenants*. If you can't see subscriptions from other Azure tenants, check your Azure AD permissions in those tenants. +> User certificates issued by Azure Kubernetes Service are valid for two years. If you choose to use kubeconfig, you will need to reconfigure service connections after two years. +> To get user certificate issued by Azure Kubernetes Service from current context, use the command: `kubectl config view --raw -o jsonpath="{.users[?(@.name contains clusterUser_.*_$(kubectl config current-context))].user.client-certificate-data}" | base64 -d` +> To check when user certificate will expire, use the command: `cat | openssl x509 -enddate -noout -in -` #### Service account option | Parameter | Description | | --------- | ----------- | -| Connection name | Required. The name you use to refer to the service connection in task inputs. | | Server URL | Required. Cluster's API server URL. | -| Secret | Secret associated with the service account to be used for deployment | +| Secret | Secret associated with the service account to be used for deployment. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | Use the following command to fetch the Server URL. @@ -554,7 +522,7 @@ Use the following command to fetch the Server URL. kubectl config view --minify -o 'jsonpath={.clusters[0].cluster.server}' ``` -Use the following sequence of commands to fetch the Secret object that's required to connect and authenticate with the cluster. +Use the following sequence of commands to fetch the Secret object required to connect and authenticate with the cluster. ``` kubectl get serviceAccounts -n -o 'jsonpath={.secrets[*].name}' @@ -571,107 +539,182 @@ Copy and paste the Secret object fetched in YAML form into the Secret text-field > [!NOTE] > When using the service account option, [ensure that a RoleBinding exists](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#kubectl-create-rolebinding), which grants permissions in the `edit` `ClusterRole` to the desired service account. This is needed so that the service account can be used by Azure Pipelines for creating objects in the chosen namespace. -#### Kubeconfig option +#### Azure subscription option | Parameter | Description | | --------- | ----------- | -| Connection name | Required. The name you use to refer to the service connection in task inputs. | -| Kubeconfig | Required. Contents of the kubeconfig file. | -| Context | Context within the kubeconfig file that is to be used for identifying the cluster. | +| Azure subscription | Required. The Azure subscription containing the cluster to be used for service connection creation. | +| Cluster | Name of the Azure Kubernetes Service cluster. | +| Namespace | Namespace within the cluster. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | + +For an Azure RBAC enabled cluster, a ServiceAccount gets created in the chosen namespace along with RoleBinding object, so that the created ServiceAccount can do actions only on the chosen namespace. + +For an Azure RBAC disabled cluster, a ServiceAccount gets created in the chosen namespace, but, the created ServiceAccount has cluster-wide privileges (across namespaces). + +> [!NOTE] +> This option lists all the subscriptions the service connection creator has access to *across different Azure tenants*. If you can't see subscriptions from other Azure tenants, check your Microsoft Entra permissions in those tenants. ### Maven service connection Use the following parameters when you define and secure a connection to a Maven repository. | Parameter | Description | -|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Connection name | Required. The name you use to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -| Registry URL| Required. The URL of the Maven repository. | -| Registry ID | Required. This is the ID of the server that matches the ID element of the repository/mirror that Maven tries to connect to. | +|-----------------------|---------------| +| Authentication method | Required. Select **Username and Password** or **Authentication Token**. | +| Registry URL| Required. The URL of the Maven repository. | +| Registry ID | Required. The ID of the server that matches the ID element of the repository/mirror that Maven tries to connect to. | | Username | Required when connection type is **Username and Password**. The username for authentication.| | Password | Required when connection type is **Username and Password**. The password for the username. | | Personal Access Token | Required when connection type is **Authentication Token**. The token to use to authenticate with the service. [Learn more](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | ### npm service connection Use the following parameters when you define and secure a connection to an npm server. | Parameter | Description | -|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Connection name | Required. The name used to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -| Registry URL| Required. The URL of the npm server. | +|-----------------------|-------------| +| Authentication method | Required. Select **Username and Password** or **Authentication Token**. | +| Registry URL| Required. The URL of the Maven repository. | | Username | Required when connection type is **Username and Password**. The username for authentication.| | Password | Required when connection type is **Username and Password**. The password for the username. | -| Personal Access Token | Required when connection type is **External Azure Pipelines**. The token to use to authenticate with the service. [Learn more](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). | +| Personal Access Token | Required **Authentication Token** is selected. The personal access token (PAT) to authenticate with the service or registry. PATs are applicable to repositories that support them, for example https://registry.npmjs.org DevOps Services organizations or Azure DevOps Server. For more information, see [Use personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | ### NuGet service connection Use the following parameters when you define and secure a connection to a NuGet server. | Parameter | Description | -|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Connection name | Required. The name used to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +|-----------------------|---------------------| +| Authentication method | Required. Select **ApiKey**, **External Azure Pipelines**, or **Basic authentication**. | | Feed URL | Required. The URL of the NuGet server.| -| ApiKey| Required when connection type is **ApiKey**. The authentication key.| -| Personal Access Token | Required when connection type is **External Azure Pipelines**. The token to use to authenticate with the service. [Learn more](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). | +| ApiKey| Required when connection type is **ApiKey**. The authentication key.| +| Personal Access Token | Required when connection type is **External Azure Pipelines**. The token to use to authenticate with NuGet feeds on other Azure Services organizations or Azure DevOps Server. the service. For more information, see [Use personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md).| | Username | Required when connection type is **Basic authentication**. The username for authentication. | | Password | Required when connection type is **Basic authentication**. The password for the username. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | To configure NuGet to authenticate with Azure Artifacts and other NuGet repositories, see [NuGet Authenticate](/azure/devops/pipelines/tasks/reference/nuget-authenticate-v1). +### Other Git service connection + +Use the following parameters to define and secure a connection to an external Git repository server. +There's a specific service connection for [GitHub](#github-service-connection) and [GitHub Enterprise Server](#github-enterprise-server-service-connection). + +| Parameter | Description | +| --------- | ----------- | +| Git repository URL | Required. The URL of the Git repository server. | +| Attempt accessing this Git server from Azure Pipelines | When checked, Azure Pipelines attempts to connect to the repository before queuing a pipeline run. You can disable this setting to improve performance when working with repositories that aren't publicly accessible. [CI triggers](../repos/pipeline-options-for-git.md#trigger-options-for-other-git) don't work when an **Other Git** repository isn't publicly accessible. You can only start manual or scheduled pipeline runs. | +| Username | Optional. The username to connect to the Git repository server. | +| Password/Token | Optional. The password or access token for the specified username. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | + +For more information, see [Artifact sources](../release/artifacts.md#artifact-sources). + ### Python package download service connection Use the following parameters when you define and secure a connection to a Python repository for downloading Python packages. | Parameter | Description | -|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Connection name | Required. The name used to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -| Python repository url for download | Required. The URL of the Python repository. | -| Personal Access Token | Required when connection type is **Authentication Token**. The token to use to authenticate with the service. [Learn more](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). | +|----------------|-----------------| +| Authentication method | Required. Select **Username and Password** or **Authentication Token**. | +| Python repository url for download | Required. The URL of the Python feed. | +| Personal Access Token | Required when connection type is **Authentication Token**. The personal access token (PAT) to use to authenticate with Python feeds that support them and DevOps Services organizations. For more information see, see [Use personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). | | Username | Required when connection type is **Username and Password**. The username for authentication.| | Password | Required when connection type is **Username and Password**. The password for the username. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | ### Python package upload service connection Use the following parameters when you define and secure a connection to a Python repository for uploading Python packages. |Parameter | Description | -|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|Connection name | Required. The name used to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -| Python repository url for upload | Required. The URL of the Python repository. | -| EndpointName | Required. Unique repository name used for twine upload. Spaces and special characters aren't allowed. | -|Personal Access Token | Required when connection type is **Authentication Token**. The token to use to authenticate with the service. [Learn more](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). | +|-----------------------|-------------------| +| Authentication method | Required. Select **Username and Password** or **Authentication Token**. | +| Python repository url for upload | Required. The URL of the Python feed. | +| EndpointName | Required. The unique repository used for the twine upload. Spaces and special characters aren't allowed. | +| Personal Access Token | see [Use personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). | | Username | Required when connection type is **Username and Password**. The username for authentication.| | Password | Required when connection type is **Username and Password**. The password for the username. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | ### Service Fabric service connection -Use the following parameters when you define and secure a connection to a Service Fabric cluster. +When creating a service connection to a Service Fabric cluster, you have three options for the authentication method: **Certificate based**, **Microsoft Entra credential**, or **Windows security using gMSA**. + +#### Certificate based authentication option + +| Parameter | Description | +|-------------------------------|-------------------| +| Cluster Endpoint | Required. The client connection endpoint for the cluster. Prefix the value with *tcp://*. This value overrides the publish profile. | +| Server Certificate Lookup | Select **Thumbprint** or **Common Name** when connection type is **Certificate based** or **Microsoft Entra credential**. | +| Server Certificate Thumbprint(s) | Required when connection type is **Certificate based** or **Microsoft Entra credential** and **Server Certification Lookup** is **Thumbprint**. The thumbprints of the cluster's certificates used to verify the identity of the cluster. This value overrides the publish profile. Separate multiple thumbprints with a comma (',') | +| Client Certificate | Required when connection type is **Certificate based**. Base64 encoding of the cluster's client certificate file. You can use the following PowerShell script to encode the certificate: `[System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes("C:\path\to\certificate.pfx"))`| +| Username| Required when connection type is **Microsoft Entra credential**. The username for authentication.| +| Password| Required when connection type is **Microsoft Entra credential**. Optional when the authentication method is **Certificate based**. The certificate password.| +| Unsecured | Optional. Select this option to skip windows security authentication. | +| Cluster SPN | Optional. Applicable if Unsecured is selected. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | + +#### Microsoft Entra credential authentication option + +| Parameter | Description | +|-------------------------------|-------------------| +| Cluster Endpoint | Required. The client connection endpoint for the cluster. Prefix the value with *tcp://*. This value overrides the publish profile. | +| Server Certificate Lookup | Select **Thumbprint** or **Common Name** | +| Server Certificate Thumbprint(s) | Required when connection type is **Certificate based** or **Microsoft Entra credential** and **Server Certification Lookup** is **Thumbprint**. The thumbprints of the cluster's certificates used to verify the identity of the cluster. This value overrides the publish profile. Separate multiple thumbprints with a comma (',') | +| Server Certificate Common Name(s) | Required when the Server Certificate Lookup is **Common Name**. The common names of the cluster's certificates used to verify the identity of the cluster. This value overrides the publish profile. Separate multiple common names with a comma (',')| +| Client Certificate | Required when connection type is **Certificate based**. Base64 encoding of the cluster's client certificate file. You can use the following PowerShell script to encode the certificate: `[System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes("C:\path\to\certificate.pfx"))`| +| Password| Required when connection type is **Microsoft Entra credential**. Optional when the authentication method is **Certificate based**. The certificate password.| +| Unsecured | Optional. Select this option to skip windows security authentication. | +| Cluster SPN | Optional. Applicable if Unsecured is selected. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | + +#### Windows security using gMSA authentication option | Parameter | Description | -|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Connection name | Required. The name used to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -| Cluster Endpoint | Required. The TCP endpoint of the cluster. | -| Server Certificate Thumbprint | Required when connection type is **Certificate based** or **Azure Active Directory**. | -|Client Certificate | Required when connection type is **Certificate based**. | -| Password| Required when connection type is **Certificate based**. The certificate password.| -| Username| Required when connection type is **Azure Active Directory**. The username for authentication.| -| Password| Required when connection type is **Azure Active Directory**. The password for the username. | -| Use Windows security| Required when connection type is **Others**.| -| Cluster SPN | Required when connection type is **Others** and using Windows security. | +|-------------------------------|-------------------| +| Cluster Endpoint | Required. The client connection endpoint for the cluster. Prefix the value with *tcp://*. This value overrides the publish profile. | +| Unsecured | Optional. Select this option to skip windows security authentication. | +| Cluster SPN | Optional. Fully qualified domain SPN for gMSA account. This parameter is applicable only if **Unsecured** option is disabled. For more information about using gMSA with a cluster, see [Configure Windows security using gMSA](/azure/service-fabric/service-fabric-windows-cluster-windows-security#configure-windows-security-using-gmsa) | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | ### SSH service connection Use the following parameters when you define and secure a connection to a remote host using Secure Shell (SSH). -| Parameter | Description | -|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Connection name | Required. The name used to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Parameter | Description | +|-------------------------------|-------------------| | Host name | Required. The name of the remote host machine or the IP address. | -|Port number | Required. The port number of the remote host machine to which you want to connect. The default is port 22. | -| User name | Required. The username to use when connecting to the remote host machine. | -| Password or passphrase | The password or passphrase for the specified username if using a keypair as credentials. | -|Private key | The entire contents of the private key file if using this type of authentication.| +| Port number | Required. The port number of the remote host machine. The default is port 22. | +| Private Key | The entire contents of the private key file if using this type of authentication.| +| Username | Required. The username to use when connecting to the remote host machine. | +| Password/Passphrase | The password or passphrase for the specified username if using a keypair as credentials. | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | For more information, see [SSH task](/azure/devops/pipelines/tasks/reference/ssh-v0) and [Copy files over SSH](/azure/devops/pipelines/tasks/reference/copy-files-over-ssh-v0). @@ -680,58 +723,65 @@ For more information, see [SSH task](/azure/devops/pipelines/tasks/reference/ssh Use the following parameters when you define and secure a connection to the Subversion repository. | Parameter | Description | -|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Connection name | Required. The name used to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -| Server repository URL | Required. The URL of the repository. | -| Accept untrusted TLS/SSL certificates | Set this option to allow the client to accept self-signed certificates installed on the agent computer(s). | -| Realm name | Optional. If you use multiple credentials in a build or release pipeline, use this parameter to specify the realm containing the credentials specified for the service connection. | +|-----------------------------------|--------------| +| Subversion repository URL | Required. The URL of the Subversion repository. | +| Accept untrusted TLS/SSL certificates | Select this option to allow the SVN client to accept self-signed SSL server certificates without installing them into the Azure DevOps service role and build Agent computers. | +| Realm name | Required if the service connection for Subversion externals. If you use multiple credentials in a build or release pipeline, use this parameter to specify the realm containing the credentials specified for the service connection. | | User name | Required. The username to connect to the service. | | Password | Required. The password for the specified username.| +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | + +You can find the realm name in a few ways: + +* If you access the repository via HTTP or HTTPS: Open the repo in a web browser without saved credentials. It uses the realm name in the authentication dialog. + +* Use the svn command line. If you stored the credentials, run For example, `svn info https://svnserver/repo`. The realm name is displayed when it asks you to enter a password. + +* If you stored the credentials to access the repository, look for the realm name in one of the files in the Subversion authentication cache section of your user profile. For example, *~/.subversion/auth/svn/simple* or *C:\Users\yourname\Application Data\Subversion\auth\svn.simple*. ### Visual Studio App Center service connection Use the following parameters when you define and secure a connection to Visual Studio App Center. | Parameter | Description | -|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Connection name | Required. The name used to refer to the service connection in task properties. It's not the name of your Azure account or subscription. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | -| API token | Required. The token to use to authenticate with the service. For more information, see the [API docs](/appcenter/api-docs/). | +|-----------------|---------| +| Server URL | Required. The URL of the App Center service. | +| API Token | Required. The token to use to authenticate with the service. For more information, see the [API docs](/appcenter/api-docs/). | +| Connection name | Required. The name you use to refer to the service connection in task properties. If you're using YAML, use the name as the **azureSubscription** or the equivalent subscription name value in the script. | +| Description | Optional. The description of the service connection. | +| Security | Optional. Select **Grant access permission to all pipelines** to allow all pipelines to use this connection. If you don't select this option, you must explicitly authorize the service connection for each pipeline that uses it. | ## Extensions for other service connections Other service connection types and tasks can be installed as extensions. See the following examples of service connections available through extensions: -* [TFS artifacts for Azure Pipelines](https://marketplace.visualstudio.com/items?itemName=ms-vscs-rm.vss-services-externaltfs). - Deploy on-premises TFS builds with Azure Pipelines through a TFS service connection and the **Team Build (external)** artifact, even when the TFS machine isn't reachable directly from Azure Pipelines. For more information, see [External TFS](../release/artifacts.md#artifact-sources---tfs-server) and [this blog post](https://devblogs.microsoft.com/devops/deploy-artifacts-from-onprem-tfs-server-with-release-management-service/). - -* [TeamCity artifacts for Azure Pipelines](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vss-services-teamcity). - This extension provides integration with TeamCity through a TeamCity service connection, enabling artifacts produced in TeamCity to be deployed by using Azure Pipelines. For more information, see [TeamCity](../release/artifacts.md#artifact-sources---teamcity). - * [System Center Virtual Machine Manager (SCVMM) Integration](https://marketplace.visualstudio.com/items?itemname=ms-vscs-rm.scvmmapp). - Connect to an SCVMM server to provision virtual machines and do actions on them such as managing checkpoints, starting and stopping virtual machines (VMs), and running PowerShell scripts. + Connect to an SCVMM server to provision virtual machines and do actions on them such as: + * Managing checkpoints + * Starting and stopping virtual machines (VMs) + * Running PowerShell scripts * [VMware Resource Deployment](https://marketplace.visualstudio.com/items?itemname=ms-vscs-rm.vmwareapp). - Connect to a VMware vCenter Server from Visual Studio Team Services or TFS to provision. Start, stop, or snapshot VMware virtual machines. + Connect to a VMware vCenter Server from Visual Studio Team Services or Team Foundation Server to provision, start, stop, or snapshot VMware virtual machines. * [Power Platform Build Tools](https://marketplace.visualstudio.com/items?itemName=microsoft-IsvExpTools.PowerPlatform-BuildTools). - Use Microsoft Power Platform Build Tools to automate common build and deployment tasks related to apps built on [Microsoft Power Platform](/power-platform/alm/devops-build-tools). After installing the extension, the **Power Platform** service connection type has the following properties. - - | Parameter | Description | - |------------------------------------|--------------| - | Connection Name | Required. The name you will use to refer to this service connection in task properties. | - | Server URL | Required. The URL of the Power Platform instance. Example: `https://contoso.crm4.dynamics.com` | - | Tenant ID | Required. Tenant ID (also called directory ID in Azure portal) to authenticate to. Refer to [https://aka.ms/buildtools-spn](/power-platform/alm/devops-build-tools#configure-service-connections-using-a-service-principal) for a script that shows Tenant ID and configures Application ID and associated Client Secret. The application user must also be [created in CDS](/powerapps/developer/common-data-service/use-single-tenant-server-server-authentication#application-user-creation) | - | Application ID| Required. Azure Application ID to authenticate with. | - | Client secret of Application ID | Required. Client secret of the Service Principal associated to above Application ID used to prove identity. | - ---- + Use Microsoft Power Platform Build Tools to automate common build and deployment tasks related to apps built on [Microsoft Power Platform](/power-platform/alm/devops-build-tools). After you install the extension, the **Power Platform** service connection type has the following properties. + | Parameter | Description | + |------------------------------------|--------------| + | Connection Name | Required. The name you use to refer to this service connection in task properties. | + | Server URL | Required. The URL of the Power Platform instance. Example: `https://contoso.crm4.dynamics.com` | + | Tenant ID | Required. Tenant ID (also called directory ID in Azure portal) to authenticate to. Refer to [https://aka.ms/buildtools-spn](/power-platform/alm/devops-build-tools#configure-service-connections-using-a-service-principal) for a script that shows Tenant ID and configures Application ID and associated Client Secret. The application user must also be [created in CDS](/powerapps/developer/common-data-service/use-single-tenant-server-server-authentication#application-user-creation) | + | Application ID| Required. Azure Application ID to authenticate with. | + | Client secret of Application ID | Required. Client secret of the Service Principal associated to above Application ID used to prove identity. | You can also create your own [custom service connections](../../extend/develop/service-endpoints.md). - +## FAQs and Troubleshoot service connections - - +### Q: How does Azure DevOps ensure efficient usage of Entra ID resources? +Azure DevOps may internally cache Entra ID access tokens issued for target identities in service connections that use Entra ID authentication, such as [Azure Resource Manager](#azure-resource-manager-service-connection) and [Docker Registry](#docker-registry-service-connection). This helps prevent Entra ID throttling, which can occur due to a high number of server task executions and other actions that require Azure DevOps to authenticate with Entra ID to serve the request. Caching applies only to internal flows where the token is never exposed to the user. If you receive an Entra ID token - for example in your pipeline script - it will always be freshly issued. Modifying the service connection invalidates its token cache and temporarily disables caching for this service endpoint. If you're experiencing any issue due to the staleness of the token following changes made in Entra ID, wait for an hour or try updating the corresponding service endpoint. [!INCLUDE [rm-help-support-shared](../includes/rm-help-support-shared.md)] diff --git a/docs/pipelines/library/task-groups.md b/docs/pipelines/library/task-groups.md deleted file mode 100644 index 54eb5132561..00000000000 --- a/docs/pipelines/library/task-groups.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Task groups in Azure Pipelines and TFS (classic) -ms.custom: seodec18 -description: Understand Task Groups in Azure Pipelines and Team Foundation Server (TFS) -ms.assetid: 0FEAE814-2AF8-441B-A099-E77B1008D2F0 -ms.topic: conceptual -ms.author: ronai -author: RoopeshNair -ms.date: 04/02/2019 -monikerRange: '<= azure-devops' ---- - -# Task groups for builds and releases (classic) - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - -:::moniker range=">=azure-devops-2019" - -> [!NOTE] -> Task groups are not supported in YAML pipelines. Instead, in that case you can use templates. See [YAML schema reference](/azure/devops/pipelines/yaml-schema/steps-template). - -:::moniker-end - -A *task group* allows you to encapsulate a sequence of tasks, already defined -in a build or a release pipeline, into a single reusable task that can be -added to a build or release pipeline, just like any other task. You can -choose to extract the parameters from the encapsulated tasks as configuration -variables, and abstract the rest of the task information. - -The new task group is automatically added to the task catalog, ready to be added -to other release and build pipelines. Task groups are stored at the project level, -and are not accessible outside the project scope. - -Task groups are a way to standardize and centrally manage deployment steps for all your applications. -When you include a task group in your definitions, and then make a change centrally to the task group, -the change is automatically reflected in all the definitions that use the task group. There is no need -to change each one individually. - -## Before you create a task group... - -* Ensure that all of the tasks you want to include in a task group have - their parameters defined as variables, - such as **$(MyVariable)**, where you want to be able to configure these parameters - when you use the task group. Variables used in the tasks are automatically extracted and converted into parameters for the task group. - Values of these configuration variables will be converted into default values for the task group. - -* If you specify a value (instead of a variable) for a parameter, that - value becomes a fixed parameter value and cannot be exposed as a parameter to the task group. - -* Parameters of the encapsulated tasks for which - you specified a value (instead of a variable), or you didn't provide - a value for, are not configurable in the task group when added to a build - or release pipeline. - -* Task conditions (such as "Run this task only when a previous task has failed" for a - **PowerShell Script** task) can be configured in a task group and these settings are persisted with the task group. - -* When you save the task group, you can provide a name and a description for the - new task group, and select a category where you want it to appear in the - **Task catalog** dialog. You can also change the default values for each of the parameters. - -* When you queue a build or a release, the encapsulated tasks - are extracted and the values you entered for the task group parameters are applied to the tasks. - -* Changes you make to a task group are reflected in every instance of the task group. - -## Create a task group - -1. Ensure that all the tasks you intend to include do not contain any linked parameters. The easy - way to do this is to choose **Unlink all** in the settings panel for the entire process. - - ![Unlinking parameters for all tasks](media/unlink-task-group.png) - -2. Select a sequence of tasks in a build or release pipeline, open the shortcut menu, and then choose **Create task group**. - - ![Creating a task group from a release pipeline list of tasks](media/create-task-group.png) - -3. Specify a name and description for the new task group, and the category (tab in the Add tasks panel) you want to add it to. - -4. After you choose **Create**, the new task group is created and replaces the selected tasks in your pipeline. - -5. All the '$(vars)' from the underlying tasks, excluding the [predefined variables](../build/variables.md), will surface as the mandatory parameters for the newly created task group. - - For example, let's say you have a task input $(foobar), which you don't intend to parameterize. However, when you create a task group, the task input is converted into task group parameter 'foobar'. Now, you can provide the default value for the task group parameter 'foobar' as $(foobar). This ensures that at runtime, the expanded task gets the same input it's intended to. - -6. Save your updated pipeline. - -## Manage task groups - -All the task groups you create in the current project are listed in -the **Task Groups** page of **Azure Pipelines**. - -![Listing task groups](media/list-task-group.png) - -Use the **Export** shortcut command to save a copy of the task group as a JSON pipeline, -and the **Import** icon to import previously saved task group definitions. Use this feature to -transfer task groups between projects and enterprises, or replicate and save copies of your task groups. - -Select a task group name to open the details page. - -![Managing a task group](media/manage-task-group.png) - -* In the **Tasks** page you can edit the tasks that make up the task group. - For each encapsulated task you can change the parameter values for the - non-variable parameters, edit the existing parameter variables, - or convert parameter values to and from variables. When you save the changes, - all definitions that use this task group will pick up the changes. - -All the variable parameters of the task group will show up as mandatory parameters in the pipeline definition. You can also set the default value for the task group parameters. - -* In the **History** tab you can see the history of changes to the group. - -* In the **References** tab you can expand lists of all the build and release pipelines, - and other task groups, that use (reference) this task group. - This is useful to ensure changes do not have unexpected effects on other processes. - -## Create previews and updated versions of task groups - -All of the built-in tasks in Azure Pipelines and TFS are [versioned](../process/tasks.md#task-versions). -This allows build and release pipelines to continue to use the existing version of a task while -new versions are developed, tested, and released. In Azure Pipelines, you can version your own custom -task groups so that they behave in the same way and provide the same advantages. - -1. After you finish editing a task group, choose **Save as draft** instead of **Save**. - - ![Saving a draft update to a task group](media/save-draft-task-group.png) - -1. The string **-test** is appended to the task group version number. - When you are happy with the changes, choose **Publish draft**. You can choose - whether to publish it as a preview or as a production-ready version. - - ![Publishing a draft version of a task group](media/publish-preview-task-group.png) - -1. You can now use the updated task group in your build and release processes; - either by changing the version number of the task group in an existing pipeline - or by adding it from the **Add tasks** panel. - - ![Using a preview version of a task group](media/use-preview-task-group.png) - - > As with the built-in tasks, the default when you add a task group is the highest non-preview version. - -1. After you have finished testing the updated task group, choose **Publish preview**. - The **Preview** string is removed from the version number string. It will now appear - in definitions as a "production-ready" version. - - ![Publishing a preview version of a task group](media/publish-version-task-group.png) - -1. In a build or release pipeline that already contains this task group, you can now select the new "production-ready" version. - When you add the task group from the **Add tasks** panel, it automatically selects the new "production-ready" version. - - ![Using an updated version of a task group](media/use-version-task-group.png) - - - - -## Working with task group versions -Any task group update can be a minor or major version update. - -### Minor version -**Action:** You directly save the task group after edit instead of saving it as draft. - -**Effect:** The version number doesn’t change. Let’s say you have a task group of version `1.0`. You can have any number of minor version updates i.e. `1.1`, `1.2`, `1.3` etc. In your pipeline, the task group version shows as `1.*` The latest changes will show up in the pipeline definition automatically. - -**Reason:** This is supposed to be a small change in the task group and you expect the pipelines to use this new change without editing the version in the pipeline definition. - - -### Major version -**Action:** You save the task group as draft and then create a preview, validate the task group and then publish the preview as a major version. - -**Effect:** The task group bumps up to a new version. Let’s say you have a task group of version `1.*`. A new version gets published as `2.*`, `3.*`, `4.*` etc. And a notification about availability of new version shows up in all the pipeline definitions where this task group is used. User has to explicitly update to new version of the task group in pipelines. - -**Reason:** When you have a substantial change which might break the existing pipelines, you would like to test it out and roll out as a new version. Users can choose to upgrade to new version or choose to stay on the same version. This functionality is same as a normal task version update. - -However, if your task group update is not a breaking change but you would like to validate first and then enforce pipelines to consume the latest changes, you can follow below steps. -1. Update the task group with your desired changes and save it as a draft. A new draft task group ‘\-Draft’ will be created which contains the changes you have done. And this draft task group is accessible for you to consume in your pipelines. -1. Now, instead of publishing as preview, you can directly consume this draft task group in your test pipeline. -1. Validate this new draft task group in your test pipeline and once you are confident, go back to your main task group and do the same changes and save it directly. This will be taken as minor version update. -1. The new changes will now show up in all the pipelines where this task group is used. -1. Now you can delete your draft task group. - -## Related topics - -* [Tasks](../process/tasks.md) -* [Task jobs](../process/phases.md) - -[!INCLUDE [rm-help-support-shared](../includes/rm-help-support-shared.md)] diff --git a/docs/pipelines/library/variable-groups.md b/docs/pipelines/library/variable-groups.md index a32bc470540..838d4f4c703 100644 --- a/docs/pipelines/library/variable-groups.md +++ b/docs/pipelines/library/variable-groups.md @@ -1,571 +1,506 @@ --- -title: Variable groups for Azure Pipelines -ms.custom: seodec18, devx-track-azurecli, pipelinesresourcesrefresh +title: Manage variable groups +ms.custom: devx-track-azurecli, pipelinesresourcesrefresh description: Share common variables across pipelines using variable groups. ms.assetid: A8AA9882-D3FD-4A8A-B22A-3A137CEDB3D7 ms.topic: tutorial ms.author: ronai author: RoopeshNair -ms.date: 07/19/2022 +ms.date: 08/15/2024 monikerRange: '<= azure-devops' --- -# Add & use variable groups +# Manage variable groups [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Variable groups store values and secrets that you might want to be [passed into a YAML pipeline](variable-groups.md?tabs=yaml&view=azure-devops&preserve-view=true#use-a-variable-group) or make available across multiple pipelines. You can share and use variable groups in multiple pipelines in the same project. +This article explains how to create and use variable groups in Azure Pipelines. Variable groups store values and secrets that you can pass into a YAML pipeline or make available across multiple pipelines in a project. -Secret variables in Variables groups are [protected resources](../security/resources.md). You can add combinations of approvals, checks, and pipeline permissions to limit access to secret variables in a variable group. Access to non-secret variables is not limited by approvals, checks, and pipeline permissions. +Secret variables in variable groups are [protected resources](../security/resources.md). You can add combinations of approvals, checks, and pipeline permissions to limit access to secret variables in a variable group. Access to nonsecret variables isn't limited by approvals, checks, or pipeline permissions. -[!INCLUDE [temp](../includes/concept-rename-note.md)] +Variable groups follow the [library security model](index.md#library-security) for roles and permissions. -## Create a variable group +## Prerequisites -#### [YAML](#tab/yaml/) -You can't create variable groups in YAML, but they can be used as described in [Use a variable group](#use-a-variable-group). +::: moniker range="azure-devops" -#### [Classic](#tab/classic/) +* An Azure DevOps Services organization and project where you have permissions to create pipelines and variables. +* A project in your Azure DevOps organization or Azure DevOps Server collection. [Create a project](../../organizations/projects/create-project.md) if you don't have one. +* If you're using the Azure DevOps CLI, you need Azure CLI version 2.30.0 or higher with the Azure DevOps CLI extension. For more information, see [Get started with Azure DevOps CLI](../../cli/index.md). -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and select your project. +::: moniker-end -1. Select **Pipelines** > **Library** > **+ Variable group**. +::: moniker range="< azure-devops" - :::image type="content" source="media/add-variable-group.png" alt-text="Screenshot of Add variable group button highlighted with red box."::: +* An Azure DevOps Server collection and project where you have permissions to create pipelines and variables. +* A project in your Azure DevOps organization or Azure DevOps Server collection. [Create a project](../../organizations/projects/create-project.md) if you don't have one. -1. Enter a name and description for the group. +::: moniker-end + +::: moniker range="azure-devops" -1. Optional: Move the toggle to link secrets from an Azure key vault as variables. For more information, see [Use Azure Key Vault secrets](../release/azure-key-vault.md). +## Set up the CLI -1. Enter the name and value for each [variable](../release/variables.md#custom-variables) to include in the group, choosing **+ Add** for each one. If you want to encrypt and securely store the value, choose the "lock" icon at the end of the row. +If you're using the Azure DevOps CLI, you need to set up the CLI to work with your Azure DevOps organization and project. -1. When you're finished adding variables, select **Save**. +1. Sign in to your Azure DevOps organization by using the [az login](/cli/azure/authenticate-azure-cli) command. - ![Saving a variable group](media/save-variable-group.png) + ```azurecli + az login + ``` -Variable groups follow the [library security model](index.md#library-security). +1. If prompted, select your subscription from the list displayed in your terminal window. -#### [Azure DevOps CLI](#tab/azure-devops-cli) +1. Ensure you're running the latest version of the Azure CLI and the Azure DevOps extension by using the following commands. -::: moniker range="azure-devops" + ```azurecli + az upgrade + az extension add --name azure-devops --upgrade + ``` + +1. In Azure DevOps CLI commands, you can set the default organization and project by using: -Using the Azure DevOps Command Line Interface (CLI), you can create and update variable groups for the pipeline runs in your project. You can also [update the variable groups](#update-a-variable-group) and [update the individual variables within a variable group](#update-variables-in-a-variable-group). + ```azurecli + az devops configure --defaults organization= project= + ``` -## Prerequisites + If you haven't set the default organization and project, you can use the `detect=true` parameter in your commands to automatically detect the organization and project context based on your current directory. If the defaults aren't configured or detected, you need to explicitly specify the `org` and `project` parameters in your commands. -- Install the Azure DevOps CLI extension as described in [Get started with Azure DevOps CLI](../../cli/index.md). -- Sign into Azure DevOps using `az login`. -- For the examples in this article, set the default organization using `az devops configure --defaults organization=YourOrganizationURL`. +::: moniker-end -[Create a variable group](#create-variable-group) | [Update a variable group](#update-variable-group) +## Create a variable group - +You can create variable groups for the pipeline runs in your project. -## Create a variable group with CLI +>[!NOTE] +>To create a secret variable group to link secrets from an Azure key vault as variables, follow the instructions at [Link a variable group to secrets in Azure Key Vault](./link-variable-groups-to-key-vaults.md). -You can create a variable group with the [az pipelines variable-group create](/cli/azure/pipelines/variable-group#ext-azure-devops-az-pipelines-variable-group-create) command. If the Azure DevOps extension for Azure Command Line Interface (CLI) is new to you, see [Get started with Azure DevOps CLI](../../cli/index.md). -```azurecli -az pipelines variable-group create --name - --variables - [--authorize {false, true}] - [--description] - [--org] - [--project] -``` +# [Azure Pipelines UI](#tab/azure-pipelines-ui) + + +1. In your Azure DevOps project, select **Pipelines** > **Library** from the left menu. +1. On the **Library** page, select **+ Variable group**. -#### Parameters + :::image type="content" source="media/add-variable-group.png" alt-text="Screenshot of the Library screen and Add variable group button."::: -- **name**: Required. Name of the variable group. -- **variables**: Required. Variables in format `key=value` space-separated pairs. Secret variables should be managed using [az pipelines variable-group variable](#update-variables-in-a-variable-group) commands. -- **authorize**: Optional. Specify whether the variable group should be accessible by all pipelines. Accepted values are *false* and *true*. -- **description**: Optional. Description of the variable group. -- **org**: Azure DevOps organization URL. Configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. Configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. +1. On the new variable group page, under **Properties**, enter a name and optional description for the variable group. +1. Under **Variables**, select **+ Add**, and then enter a variable name and value to include in the group. If you want to encrypt and securely store the value, select the lock icon next to the variable. +1. Select **+ Add** to add each new variable. When you finish adding variables, select **Save**. -#### Example + :::image type="content" source="media/save-variable-group.png" alt-text="Screenshot of configuring and saving a variable group."::: -The following command creates a variable group named **new-app-variables**. It includes the variables **app-location=Head_Office** and **app-name=Fabrikam** and returns the result in YAML format. +You can now use this variable group in project pipelines. + +# [Azure DevOps CLI](#tab/azure-devops-cli) + +In Azure DevOps Services, you can create variable groups by using the Azure DevOps CLI. +[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] + +::: moniker range="azure-devops" + + +To create a variable group, use the [az pipelines variable-group create](/cli/azure/pipelines/variable-group#ext-azure-devops-az-pipelines-variable-group-create) command. + +For example, the following command creates a variable group named `home-office-config`, adds the variables `app-location=home-office` and `app-name=contoso`, and outputs results in YAML format. ```azurecli -az pipelines variable-group create --name new-app-variables --variables app-location=Head_Office app-name=Fabrikam --output yaml +az pipelines variable-group create --name home-office-config + --variables app-location=home-office app-name=contoso + --output yaml +``` +Output: + +```yaml authorized: false description: null id: 5 -name: new-app-variables +name: home-office-config providerData: null type: Vsts variables: app-location: isSecret: null - value: Head_Office + value: home-office app-name: isSecret: null - value: Fabrikam + value: contoso ``` - - -## Update a variable group - -You can update a variable group with the [az pipelines variable-group update](/cli/azure/pipelines/variable-group#ext-azure-devops-az-pipelines-variable-group-update) command. If the Azure DevOps extension for CLI is new to you, see [Get started with Azure DevOps CLI](../../cli/index.md). - -```azurecli -az pipelines variable-group update --group-id - [--authorize {false, true}] - [--description] - [--name] - [--org] - [--project] -``` +::: moniker-end -#### Parameters +--- -- **group-id**: Required. ID of the variable group. To find the variable group ID, see [List variable groups](#list-variable-groups). -- **authorize**: Required unless **description** or **name** is specified. Indicates whether the variable group should be accessible by all pipelines. Accepted values are *false* and *true*. -- **description**: Required unless **authorize** or **name** is specified. Use to change the description of the variable group. -- **name**: Required unless **authorize** or **description** is specified. Use to change the name of the variable group. -- **org**: Azure DevOps organization URL. Configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. Configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. -#### Example +## Update variable groups -The following command updates the variable group with the ID **4**. The **description** and **name** are changed and the results are shown in table format. +# [Azure Pipelines UI](#tab/azure-pipelines-ui) -```azurecli -az pipelines variable-group update --group-id 4 --name MyNewAppVariables --description "Variables for my new app" --output table +You can update variable groups by using the Azure Pipelines user interface. -ID Name Type Description Is Authorized Number of Variables ----- ----------------- ------ ------------------------ --------------- --------------------- -4 MyNewAppVariables Vsts Variables for my new app False 2 -``` +1. In your Azure DevOps project, select **Pipelines** > **Library** from the left menu. +1. On the **Library** page, select the variable group you want to update. You can also hover over the variable group listing, select the **More options** icon, and select **Edit** from the menu. +1. On the variable group page, change any of the properties, and then select **Save**. -::: moniker-end +# [Azure DevOps CLI](#tab/azure-devops-cli) +In Azure DevOps Services, you can update variable groups by using the Azure DevOps CLI. [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * +::: moniker range="azure-devops" -## Use a variable group +### List variable groups -#### [YAML](#tab/yaml/) +To update a variable group or the variables within it by using the Azure DevOps CLI, you use the variable group `group-id`. -::: moniker range="> tfs-2018" +You can get the value of the variable group ID from the output of the variable group creation command, or use the [az pipelines variable-group list](/cli/azure/pipelines/variable-group#ext-azure-devops-az-pipelines-variable-group-list) command. -To use a variable from a variable group, add a reference to the group in your YAML file: +For example, the following command lists the first three project variable groups in ascending order and returns the results, including variable group ID, in table format. -```yaml -variables: -- group: my-variable-group +```azurecli +az pipelines variable-group list --top 3 --query-order Asc --output table ``` -Then, variables from the variable group can be used in your YAML file. - -If you use both variables and variable groups, use the `name`/`value` syntax for the individual non-grouped variables: +Output: -```yaml -variables: -- group: my-variable-group -- name: my-bare-variable - value: 'value of my-bare-variable' +```output +ID Name Type Number of Variables +---- ----------------- ------ --------------------- +1 myvariables Vsts 2 +2 newvariables Vsts 4 +3 new-app-variables Vsts 3 ``` -To reference a variable group, use macro syntax or a runtime expression. In the following example, the group `my-variable-group` has a variable named `myhello`. +### Update a variable group -```yaml -variables: -- group: my-variable-group -- name: my-passed-variable - value: $[variables.myhello] # uses runtime expression +To update a variable group, use the [az pipelines variable-group update](/cli/azure/pipelines/variable-group#ext-azure-devops-az-pipelines-variable-group-update) command. -steps: -- script: echo $(myhello) # uses macro syntax -- script: echo $(my-passed-variable) -``` +> [!NOTE] +> You can't update a variable group of type `AzureKeyVault` using the Azure DevOps CLI. -You can reference multiple variable groups in the same pipeline. If multiple variable groups include the same variable, the variable group included last in your YAML file sets the variable's value. +For example, the following command updates the variable group with ID `4` to change the `name` and `description`, and outputs results in table format. -```yaml -variables: -- group: my-first-variable-group -- group: my-second-variable-group +```azurecli +az pipelines variable-group update --group-id 4 + --name my-new-variables + --description "New home office variables" + --output table ``` -You can also reference a variable group in a template. In the template `variables.yml`, the group `my-variable-group` is referenced. The variable group includes a variable named `myhello`. - -```yaml -# variables.yml -variables: -- group: my-variable-group -``` +Output: -In this pipeline, the variable `$(myhello)` from the variable group `my-variable-group` is included and `variables.yml` is referenced. +```output -```yaml -# azure-pipeline.yml -stages: -- stage: MyStage - variables: - - template: variables.yml - jobs: - - job: Test - steps: - - script: echo $(myhello) +ID Name Description Is Authorized Number of Variables +---- ---------------- ------------------------- ------------- ------------------- +4 my-new-variables New home office variables false 2 ``` -## Authorize a variable group - -To work with a variable group, you must authorize the group. If you only name the variable group in YAML, then anyone who can push code to your repository could extract the contents of secrets in the variable group. -To authorize the group, use one of the following techniques: - -- To authorize any pipeline to use the variable group, go to Azure Pipelines. This might be a good option if you don't have any secrets in the group. Select **Library** > **Variable groups**, and then select the variable group in question and enable the setting **Allow access to all pipelines**. - -- To authorize a variable group for a specific pipeline, open the pipeline, select **Edit**, and then queue a build manually. You see a resource authorization error and an "Authorize resources" action on the error. Choose this action to explicitly add the pipeline as an authorized user of the variable group. +### Show details for a variable group -> [!Note] -> If you add a variable group to a pipeline and don't get a resource authorization error in your build when you expected one, turn off the **Allow access to all pipelines** setting. +You can use the [az pipelines variable-group show](/cli/azure/pipelines/variable-group#ext-azure-devops-az-pipelines-variable-group-show) command to show details for a variable group. For example, the following command shows details for the variable group with ID `4` and returns the results in YAML format. -::: moniker-end +```azurecli +az pipelines variable-group show --group-id 4 --output yaml +``` -::: moniker range="tfs-2018" +Output: -YAML builds aren't available on TFS. +```yaml +authorized: false +description: Variables for my new app +id: 4 +name: my-new-variables +providerData: null +type: Vsts +variables: + app-location: + isSecret: null + value: home-office + app-name: + isSecret: null + value: contoso +``` ::: moniker-end -#### [Classic](#tab/classic/) - -::: moniker range=">= azure-devops-2019" +--- -To use a variable group, open your pipeline. Select **Variables** > **Variable groups**, and then choose **Link variable group**. -In a build pipeline, you see a list of available groups. In a release pipeline, for example, you -also see a drop-down list of stages in the pipeline. Link the variable group to one or more of these stages in the pipeline. -![Linking a variable group](media/link-variable-group.png) +## Delete a variable group -- **build pipeline**: The variable group gets linked to the pipeline. All the variables in the group are available for use within the pipeline. -- **release pipeline**: Link a variable group to the pipeline itself, or to a specific stage of the release pipeline. - - If you link to a release pipeline, all the variables in the group are available for use in the pipeline, in all stages. - - If you link to one or more stages in a release pipeline, the variables from the variable group get scoped to these stages and aren't accessible in the other stages of the same release. +# [Azure Pipelines UI](#tab/azure-pipelines-ui) -> [!NOTE] -> Linking a variable group to a specific stage is available only on Azure Pipelines and on TFS 2018 Update 2 and later. +You can delete variable groups in the Azure Pipelines user interface. -::: moniker-end +1. In your Azure DevOps project, select **Pipelines** > **Library** from the left menu. +1. On the **Library** page, hover over the variable group you want to delete and select the **More options** icon. +1. Select **Delete** from the menu, and then select **Delete** on the confirmation screen. #### [Azure DevOps CLI](#tab/azure-devops-cli) +In Azure DevOps Services, you can delete variable groups by using the Azure DevOps CLI. +[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] + ::: moniker range="azure-devops" +To delete a variable group, use the [az pipelines variable-group delete](/cli/azure/pipelines/variable-group#ext-azure-devops-az-pipelines-variable-group-delete) command. For example, the following command deletes the variable group with ID `1` and doesn't prompt for confirmation. -There's no [**az pipelines**](/cli/azure/pipelines) command that applies to using a variable group. +```azurecli +az pipelines variable-group delete --group-id 1 --yes +``` ::: moniker-end -[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - -* * * +--- -Access the variable values in a linked variable group the same way as [variables you define within the pipeline itself](../process/variables.md). -For example, to access the value of a variable named **customer** in a variable group linked to the pipeline, -use `$(customer)` in a task parameter or a script. But, you can't access secret variables (encrypted variables and key vault variables) directly in scripts - instead, they must be passed as arguments to a task. For more information, see [secrets](../process/variables.md#secret-variables) +## Manage variables in variable groups -Changes that you make to a variable group are automatically available to all the definitions or stages to which the variable group gets linked. +# [Azure Pipelines UI](#tab/azure-pipelines-ui) -::: moniker range="azure-devops" -## List variable groups +You can change, add, or delete variables in variable groups by using the Azure Pipelines user interface. -Use the CLI to list the variable groups for pipeline runs with the [az pipelines variable-group list](/cli/azure/pipelines/variable-group#ext-azure-devops-az-pipelines-variable-group-list) command. If the Azure DevOps extension for CLI is new to you, see [Get started with Azure DevOps CLI](../../cli/index.md). +1. In your Azure DevOps project, select **Pipelines** > **Library** from the left menu. +1. On the **Library** page, select the variable group you want to update. You can also hover over the variable group listing, select the **More options** icon, and select **Edit** from the menu. +1. On the variable group page, you can: + - Change any of the variable names or values. + - Delete any of the variables by selecting the garbage can icon next to the variable name. + - Change variables to secret or nonsecret by selecting the lock icon next to the variable value. + - Add new variables by selecting **+ Add**. +1. After making changes, select **Save**. -```azurecli -az pipelines variable-group list [--action {manage, none, use}] - [--continuation-token] - [--group-name] - [--org] - [--project] - [--query-order {Asc, Desc}] - [--top] -``` +# [Azure DevOps CLI](#tab/azure-devops-cli) -#### Optional parameters +In Azure DevOps Services, you can manage variables in variable groups by using the Azure DevOps CLI. +[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -- **action**: Specifies the action that can be performed on the variable groups. Accepted values are *manage*, *none*, and *use*. -- **continuation-token**: Lists the variable groups after a continuation token is provided. -- **group-name**: Name of the variable group. Wildcards are accepted, such as `new-var*`. -- **org**: Azure DevOps organization URL. Configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. Configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. -- **query-order**: Lists the results in either ascending or descending (the default) order. Accepted values are *Asc* and *Desc*. -- **top**: Number of variable groups to list. +::: moniker range="azure-devops" -#### Example +### List variables in a variable group -The following command lists the top three variable groups in ascending order and returns the results in table format. +To list the variables in a variable group, use the [az pipelines variable-group variable list](/cli/azure/pipelines/variable-group/variable#ext-azure-devops-az-pipelines-variable-group-variable-list) command. For example, the following command lists all the variables in the variable group with ID `4` and shows the result in table format. ```azurecli -az pipelines variable-group list --top 3 --query-order Asc --output table +az pipelines variable-group variable list --group-id 4 --output table +``` -ID Name Type Number of Variables ----- ----------------- ------ --------------------- -1 myvariables Vsts 2 -2 newvariables Vsts 4 -3 new-app-variables Vsts 3 +Output: + +```output +Name Is Secret Value +-------------- ----------- ----------- +app-location False home-office +app-name False contoso ``` - +### Add variables to a variable group -## Show details for a variable group +To add a variable to a variable group, use the [az pipelines variable-group variable create](/cli/azure/pipelines/variable-group/variable#ext-azure-devops-az-pipelines-variable-group-variable-create) command. -Display the details of a variable group in your project with the [az pipelines variable-group show](/cli/azure/pipelines/variable-group#ext-azure-devops-az-pipelines-variable-group-show) command. If the Azure DevOps extension for CLI is new to you, see [Get started with Azure DevOps CLI](../../cli/index.md). +For example, the following command creates a new variable named `requires-login` with a default value of `true` in the variable group with ID `4`. The result is shown in table format. ```azurecli -az pipelines variable-group show --group-id - [--org] - [--project] +az pipelines variable-group variable create --group-id 4 + --name requires-login + --value true + --output table ``` -#### Parameters +Output: +```output +Name Is Secret Value +-------------- ----------- ------- +requires-login False true +``` -- **group-id**: Required. ID of the variable group. To find the variable group ID, see [List variable groups](#list-variable-groups). -- **org**: Azure DevOps organization URL. Configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. Configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. +### Update variables in a variable group -#### Example +To update variables in a variable group, use the [az pipelines variable-group variable update](/cli/azure/pipelines/variable-group/variable#ext-azure-devops-az-pipelines-variable-group-variable-update) command. -The following command shows details for the variable group with the ID **4** and returns the results in YAML format. +> [!NOTE] +> You can't update variables in a variable group of type `AzureKeyVault` using the Azure DevOps CLI. You can update variables via the `az keyvault` commands. -```azurecli -az pipelines variable-group show --group-id 4 --output yaml +For example, the following command updates the `requires-login` variable with the new value `false` in the variable group with ID `4`, and shows the result in YAML format. The command specifies that the variable is a `secret`. -authorized: false -description: Variables for my new app -id: 4 -name: MyNewAppVariables -providerData: null -type: Vsts -variables: - app-location: - isSecret: null - value: Head_Office - app-name: - isSecret: null - value: Fabrikam +```azurecli +az pipelines variable-group variable update --group-id 4 + --name requires-login + --value false + --secret true + --output yaml ``` - +The output shows the value as `null` instead of `false` because it's a secret hidden value. -## Delete a variable group +```yaml +requires-login: + isSecret: true + value: null +``` -Delete a variable group in your project with the [az pipelines variable-group delete](/cli/azure/pipelines/variable-group#ext-azure-devops-az-pipelines-variable-group-delete) command. If the Azure DevOps extension for CLI is new to you, see [Get started with Azure DevOps CLI](../../cli/index.md). +### Manage secret variables -```azurecli -az pipelines variable-group delete --group-id - [--org] - [--project] - [--yes] -``` +To manage secret variables, use the [az pipelines variable-group variable update](/cli/azure/pipelines/variable-group/variable#ext-azure-devops-az-pipelines-variable-group-variable-update) command with the following parameters: -#### Parameters +- `secret`: Set to `true` to indicate that the variable's value is kept secret. +- `prompt-value`: Set to `true` to update the value of a secret variable by using an environment variable or prompt via standard input. +- `value`: For secret variables, use the `prompt-value` parameter to be prompted to enter the value via standard input. For noninteractive consoles, you can pick up the environment variable prefixed with `AZURE_DEVOPS_EXT_PIPELINE_VAR_`. For example, you can input a variable named `MySecret` by using the environment variable `AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret`. -- **group-id**: Required. ID of the variable group. To find the variable group ID, see [List variable groups](#list-variable-groups). -- **org**: Azure DevOps organization URL. Configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. Configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. -- **yes**: Optional. Doesn't prompt for confirmation. -#### Example +### Delete variables from a variable group -The following command deletes the variable group with the ID **1** and doesn't prompt for confirmation. +To delete a variable from a variable group, use the [az pipelines variable-group variable delete](/cli/azure/pipelines/variable-group/variable#ext-azure-devops-az-pipelines-variable-group-variable-delete) command. For example, the following command deletes the `requires-login` variable from the variable group with ID `4`. ```azurecli -az pipelines variable-group delete --group-id 1 --yes - -Deleted variable group successfully. +az pipelines variable-group variable delete --group-id 4 --name requires-login ``` -## Add variables to a variable group +The command prompts for confirmation because that is the default. Use the `--yes` parameter to skip the confirmation prompt. -With the Azure DevOps CLI, you can add a variable to a variable group in a pipeline with the [az pipelines variable-group variable create](/cli/azure/pipelines/variable-group/variable#ext-azure-devops-az-pipelines-variable-group-variable-create) command. If the Azure DevOps extension for CLI is new to you, see [Get started with Azure DevOps CLI](../../cli/index.md). - -```azurecli -az pipelines variable-group variable create --group-id - --name - [--org] - [--project] - [--secret {false, true}] - [--value] +```output +Are you sure you want to delete this variable? (y/n): y +Deleted variable 'requires-login' successfully. ``` -#### Parameters +::: moniker-end -- **group-id**: Required. ID of the variable group. To find the variable group ID, see [List variable groups](#list-variable-groups). -- **name**: Required. Name of the variable you're adding. -- **org**: Azure DevOps organization URL. Configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. Configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. -- **secret**: Optional. Indicates whether the variable's value is a secret. Accepted values are *false* and *true*. -- **value**: Required for non-secret variable. Value of the variable. For secret variables, if **value** parameter isn't provided, it's picked from environment variable prefixed with `AZURE_DEVOPS_EXT_PIPELINE_VAR_` or user is prompted to enter it via standard input. For example, a variable named **MySecret** can be input using the environment variable `AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret`. +--- -#### Example -The following command creates a variable in the variable group with ID of **4**. The new variable is named **requires-login** and has a value of **True**, and the result is shown in table format. +## Use variable groups in pipelines -```azurecli -az pipelines variable-group variable create --group-id 4 --name requires-login --value True --output table +You can use variable groups in YAML or Classic pipelines. Changes that you make to a variable group are automatically available to all the definitions or stages the variable group is linked to. -Name Is Secret Value --------------- ----------- ------- -requires-login False True -``` +# [YAML](#tab/yaml) - -## List variables in a variable group +If you only name the variable group in YAML pipelines, anyone who can push code to your repository could extract the contents of secrets in the variable group. Therefore, to use a variable group with YAML pipelines, you must authorize the pipeline to use the group. You can authorize a pipeline to use a variable group in the Azure Pipelines user interface or by using the Azure DevOps CLI. -You can list the variables in a variable group with the [az pipelines variable-group variable list](/cli/azure/pipelines/variable-group/variable#ext-azure-devops-az-pipelines-variable-group-variable-list) command. If the Azure DevOps extension for CLI is new to you, see [Get started with Azure DevOps CLI](../../cli/index.md). +### Authorization via the Pipelines UI -```azurecli -az pipelines variable-group variable list --group-id - [--org] - [--project] -``` +You can authorize pipelines to use your variable groups by using the Azure Pipelines user interface. -#### Parameters +1. In your Azure DevOps project, select **Pipelines** > **Library** from the left menu. +1. On the **Library** page, select the variable group you want to authorize. +1. On the variable group page, select the **Pipeline permissions** tab. +1. On the **Pipeline permissions** screen, select **+** and then select a pipeline to authorize. Or, select the **More actions** icon, select **Open access**, and select **Open access** again to confirm. -- **group-id**: Required. ID of the variable group. To find the variable group ID, see [List variable groups](#list-variable-groups). -- **org**: Azure DevOps organization URL. Configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. Configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. +Selecting a pipeline authorizes that pipeline to use the variable group. To authorize another pipeline, select the **+** icon again. Selecting **Open access** authorizes all project pipelines to use the variable group. Open access might be a good option if you don't have any secrets in the group. -#### Example +Another way to authorize a variable group is to select the pipeline, select **Edit**, and then queue a build manually. You see a resource authorization error and can then explicitly add the pipeline as an authorized user of the variable group. -The following command lists all of the variables in the variable group with ID of **4** and shows the result in table format. +### Authorization via the Azure DevOps CLI -```azurecli -az pipelines variable-group variable list --group-id 4 --output table +In Azure DevOps Services, you can authorize variable groups by using the Azure DevOps CLI. +[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -Name Is Secret Value --------------- ----------- ----------- -app-location False Head_Office -app-name False Fabrikam -requires-login False True -``` +::: moniker range="azure-devops" - +To authorize all project pipelines to use the variable group, set the `authorize` parameter in the [az pipelines variable-group create](/cli/azure/pipelines/variable-group#az-pipelines-variable-group-create) command to `true`. This open access might be a good option if you don't have any secrets in the group. -## Update variables in a variable group +::: moniker-end -Update a variable in a variable group with the [az pipelines variable-group variable update](/cli/azure/pipelines/variable-group/variable#ext-azure-devops-az-pipelines-variable-group-variable-update) command. If the Azure DevOps extension for CLI is new to you, see [Get started with Azure DevOps CLI](../../cli/index.md). +### Link a variable group to a pipeline -```azurecli -az pipelines variable-group variable update --group-id - --name - [--new-name] - [--org] - [--project] - [--prompt-value {false, true}] - [--secret {false, true}] - [--value] -``` +Once you authorize a YAML pipeline to use a variable group, you can use variables within the group in the pipeline. -#### Parameters +To use variables from a variable group, add a reference to the group name in your YAML pipeline file. +```yaml +variables: +- group: my-variable-group +``` -- **group-id**: Required. ID of the variable group. To find the variable group ID, see [List variable groups](#list-variable-groups). -- **name**: Required. Name of the variable you're adding. -- **new-name**: Optional. Specify to change the name of the variable. -- **org**: Azure DevOps organization URL. Configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. Configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. -- **prompt-value**: Set to **true** to update the value of a secret variable using environment variable or prompt via standard input. Accepted values are *false* and *true*. -- **secret**: Optional. Indicates whether the variable's value is kept secret. Accepted values are *false* and *true*. -- **value**: Updates the value of the variable. For secret variables, use the **prompt-value** parameter to be prompted to enter it via standard input. For non-interactive consoles, it can be picked from environment variable prefixed with `AZURE_DEVOPS_EXT_PIPELINE_VAR_`. For example, a variable named **MySecret** can be input using the environment variable `AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret`. +You can reference multiple variable groups in the same pipeline. If multiple variable groups include the variables with the same name, the last variable group that uses the variable in the file sets the variable's value. For more information about precedence of variables, see [Expansion of variables](../process/variables.md#expansion-of-variables). -#### Example +You can also reference a variable group in a template. The following *variables.yml* template file references the variable group `my-variable-group`. The variable group includes a variable named `myhello`. -The following command updates the **requires-login** variable with the new value **False** in the variable group with ID of **4**. It specifies that the variable is a **secret** and shows the result in YAML format. Notice that the output shows the value as **null** instead of **False** since it's a secret hidden value. +```yaml +variables: +- group: my-variable-group +``` -```azurecli -az pipelines variable-group variable update --group-id 4 --name requires-login --value False --secret true --output yaml +The YAML pipeline references the *variables.yml* template, and uses the variable `$(myhello)` from the variable group `my-variable-group`. -requires-login: - isSecret: true - value: null +```yaml +stages: +- stage: MyStage + variables: + - template: variables.yml + jobs: + - job: Test + steps: + - script: echo $(myhello) ``` - +### Use variables in a linked variable group -## Delete variables from a variable group +You access the variable values in a linked variable group the same way you access variables you define within the pipeline. For example, to access the value of a variable named `customer` in a variable group linked to the pipeline, you can use `$(customer)` in a task parameter or a script. -Delete a variable from a variable group with the [az pipelines variable-group variable delete](/cli/azure/pipelines/variable-group/variable#ext-azure-devops-az-pipelines-variable-group-variable-delete) command. If the Azure DevOps extension for CLI is new to you, see [Get started with Azure DevOps CLI](../../cli/index.md). +If you use both standalone variables and variable groups in your pipeline file, use the `name`-`value` syntax for the standalone variables. -```azurecli -az pipelines variable-group variable delete --group-id - --name - [--org] - [--project] - [--yes] +```yaml +variables: +- group: my-variable-group +- name: my-standalone-variable + value: 'my-standalone-variable-value' ``` -#### Parameters +To reference a variable in a variable group, you can use macro syntax or a runtime expression. In the following examples, the group `my-variable-group` has a variable named `myhello`. -- **group-id**: Required. ID of the variable group. To find the variable group ID, see [List variable groups](#list-variable-groups). -- **name**: Required. Name of the variable you're deleting. -- **org**: Azure DevOps organization URL. Configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. Configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. -- **yes**: Optional. Doesn't prompt for confirmation. +To use a runtime expression: -#### Example +```yaml +variables: +- group: my-variable-group +- name: my-passed-variable + value: $[variables.myhello] +- script: echo $(my-passed-variable) +``` -The following command deletes the **requires-login** variable from the variable group with ID of **4** and prompts for confirmation. +To use macro syntax: -```azurecli -az pipelines variable-group variable delete --group-id 4 --name requires-login +```yaml +variables: +- group: my-variable-group -Are you sure you want to delete this variable? (y/n): y -Deleted variable 'requires-login' successfully. +steps: +- script: echo $(myhello) ``` -::: moniker-end - -## Link secrets from an Azure key vault +You can't access secret variables, including encrypted variables and key vault variables, directly in scripts. You must pass these variables as arguments to a task. For more information, see [Secret variables](../process/variables.md#secret-variables). -[!INCLUDE [set secret variable in UI](../process/includes/variable-groups-link-secrets.md)] +# [Classic](#tab/classic) -## Expand variables in a group +### Use variable groups in Classic pipelines -#### [YAML](#tab/yaml/) +Classic pipelines can use variable groups without separate authorization. To use a variable group: -::: moniker range=">= azure-devops-2019" +1. Open your Classic pipeline. +1. Select **Variables** > **Variable groups**, and then select **Link variable group**. -When you set a variable in a group and use it in a YAML file, it's equal to other defined variables in the YAML file. -For more information about precedence of variables, see [Variables](../process/variables.md#expansion-of-variables). + * In a build pipeline, you see a list of available groups. Select a variable group and select **Link**. All the variables in the group are available for use within the pipeline. -::: moniker-end -::: moniker range="< azure-devops-2019" -YAML isn't supported in TFS. -::: moniker-end + * In a release pipeline, you also see a dropdown list of stages in the pipeline. Link the variable group to the pipeline itself, or to one or more specific stages of the release pipeline. If you link to one or more stages, the variables from the variable group are scoped to these stages and aren't accessible in the other stages of the release. -#### [Classic](#tab/classic/) + :::image type="content" source="media/link-variable-group.png" alt-text="Screenshot that shows linking a variable group."::: -When you set a variable with the same name in multiple scopes, the following precedence is used (highest precedence first). +When you set a variable with the same name in multiple scopes, the following precedence is used, highest first: 1. Variable set at queue time 1. Variable set in the pipeline 1. Variable set in the variable group -[!INCLUDE [variable-collision](../includes/variable-collision.md)] - -#### [Azure DevOps CLI](#tab/azure-devops-cli) - -::: moniker range="azure-devops" - -There isn't an [**az pipelines**](/cli/azure/pipelines) command that applies to the expansion of variables in a group. - -::: moniker-end +For more information about precedence of variables, see [Expansion of variables](../process/variables.md#expansion-of-variables). -[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] +[!INCLUDE [variable-collision](../includes/variable-collision.md)] -* * * +--- ## Related articles -- [Use Azure Key Vault secrets in Azure Pipelines](../release/azure-key-vault.md) -- [Define variables](../process/variables.md) -- [Use secret and nonsecret variables in variable groups](../scripts/cli/pipeline-variable-group-secret-nonsecret-variables.md) -- [Add approvals and checks](../process/approvals.md) +* [Define variables](../process/variables.md) +* [Define custom variables](../release/variables.md#custom-variables) +* [Use secret and nonsecret variables in variable groups](../scripts/cli/pipeline-variable-group-secret-nonsecret-variables.md) +* [Use Azure Key Vault secrets in Azure Pipelines](../release/azure-key-vault.md) +* [Add approvals and checks](../process/approvals.md) diff --git a/docs/pipelines/licensing/concurrent-jobs.md b/docs/pipelines/licensing/concurrent-jobs.md index 410797fb851..657ade9f3c2 100644 --- a/docs/pipelines/licensing/concurrent-jobs.md +++ b/docs/pipelines/licensing/concurrent-jobs.md @@ -1,12 +1,12 @@ --- title: Configure and pay for parallel jobs titleSuffix: Azure DevOps -ms.custom: seodec18,contperf-fy21q1 description: Configure parallel jobs in Azure Pipelines and pay for them ms.topic: how-to ms.assetid: FAFB2DE4-F462-4E9E-8312-4F343F2A35B8 ms.author: jukullam -ms.date: 04/27/2023 +author: juliakm +ms.date: 04/14/2025 monikerRange: '<= azure-devops' --- @@ -14,31 +14,32 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="< azure-devops-2019" +::: moniker range=" [!IMPORTANT] +> Starting with Azure DevOps Server 2019, you don't have to pay for self-hosted concurrent jobs in releases. You're only limited by the number of agents that you have. -One free parallel job is included with every collection in a Team Foundation Server. Every Visual Studio Enterprise subscriber in a Team Foundation Server contributes one more parallel job. +::: moniker-end -You can buy more private jobs from the Visual Studio Marketplace. There's a maximum limit of 25 parallel jobs for Microsoft-hosted agents. -::: moniker-end +::: moniker range="azure-devops" -::: moniker range=">= azure-devops-2019 < azure-devops" +Learn how to estimate how many parallel jobs you need and buy more parallel jobs for your organization. -> [!IMPORTANT] -> Starting with Azure DevOps Server 2019, you do not have to pay for self-hosted concurrent jobs in releases. You are only limited by the number of agents that you have. +> [!NOTE] +> The free grant of parallel jobs for public projects and for certain private projects in new organizations is temporarily disabled. However, you can request this grant by submitting [a request](https://aka.ms/azpipelines-parallelism-request). Existing organizations and projects aren't affected. It can take several business days to process your free tier requests. During certain time periods, processing times might be longer. ::: moniker-end -::: moniker range="azure-devops" +## Prerequisites -Learn how to estimate how many parallel jobs you need and buy more parallel jobs for your organization. -> [!NOTE] -> We have temporarily disabled the free grant of parallel jobs for public projects and for certain private projects in new organizations. However, you can request this grant by submitting [a request](https://aka.ms/azpipelines-parallelism-request). Existing organizations and projects are not affected. Please note that it takes us 2-3 business days to respond to your free tier requests. +| Category | Requirements | +|--------------|-------------| +| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).
      - Basic knowledge of YAML and Azure Pipelines. For more information, see [Create your first pipeline](../create-first-pipeline.md).
      - **Permissions:**
           Member of the [**Project Collection Administrators** security group](../../organizations/security/look-up-project-collection-administrators.md). If you created the organization or collection, you're automatically a member of this group.
      - **Billing:**
           Billing must be [set up for your organization](../../organizations/billing/set-up-billing-for-your-organization-vs.md).| +| **Azure** | An [Azure subscription](https://azure.microsoft.com/free/). | + +::: moniker range="azure-devops" ## What is a parallel job? @@ -47,9 +48,9 @@ When you define a pipeline, you can define it as a collection of [jobs](../proce In Azure Pipelines, you can run parallel jobs on Microsoft-hosted infrastructure or your own (self-hosted) infrastructure. Each parallel job allows you to run a single job at a time in your organization. You don't need to pay for parallel jobs if you're using an on-premises server. The concept of parallel jobs only applies to Azure DevOps Services. ### Microsoft-hosted vs. self-hosted parallel jobs -If you want to run your jobs on machines that Microsoft manages, use _Microsoft-hosted parallel jobs_. Your jobs will run on [Microsoft-hosted agents](../agents/hosted.md). +If you want to run your jobs on machines that Microsoft manages, use _Microsoft-hosted parallel jobs_. Your jobs run on [Microsoft-hosted agents](../agents/hosted.md). -If you want Azure Pipelines to orchestrate your builds and releases, but use your own machines to run them, use _self-hosted parallel jobs_. For self-hosted parallel jobs, you'll start by deploying our [self-hosted agents](../agents/agents.md) on your machines. You can register any number of these self-hosted agents in your organization. +If you want Azure Pipelines to orchestrate your builds and releases, but use your own machines to run them, use _self-hosted parallel jobs_. For self-hosted parallel jobs, you start by deploying our [self-hosted agents](../agents/agents.md#self-hosted-agents) on your machines. You can register any number of these self-hosted agents in your organization. ::: moniker-end @@ -58,19 +59,18 @@ If you want Azure Pipelines to orchestrate your builds and releases, but use you ## How much do parallel jobs cost? We provide a *free tier* of service by default in every organization for both hosted and self-hosted parallel jobs. -Parallel jobs are purchased at the organization level, and they're shared by all projects in an organization. +Parallel jobs are purchased at the organization level, and shared by all projects in an organization. # [Microsoft-hosted](#tab/ms-hosted) For Microsoft-hosted parallel jobs, you can get up to 10 free Microsoft-hosted parallel jobs that can run for up to 360 minutes (6 hours) each time for **public projects**. When you create a new Azure DevOps organization, you aren't given this free grant by default. -For **private projects**, you can get one free job that can run for up to 60 minutes each time. When you create a new Azure DevOps organization, you may not always be given this free grant by default. +For **private projects**, you can get one free job that can run for up to 60 minutes each time. When you create a new Azure DevOps organization, you might not always be given this free grant by default. To request the free grant for public or private projects, submit [a request](https://aka.ms/azpipelines-parallelism-request). - > [!NOTE] -> It takes us 2-3 business days to respond to your free tier request. +> It can take several business days to process your free tier request. During certain time periods, processing times might be longer. There's no time limit on parallel jobs for public projects and a 30 hour time limit per month for private projects. @@ -79,13 +79,13 @@ There's no time limit on parallel jobs for public projects and a 30 hour time li | **Public project** | Up to 10 free Microsoft-hosted parallel jobs that can run for up to 360 minutes (6 hours) each time | No overall time limit per month| | **Private project** | One free job that can run for up to 60 minutes each time | 1,800 minutes (30 hours) per month | -When the free tier is no longer sufficient, you can pay for additional capacity per parallel job. For pricing cost per parallel job, see the [Azure DevOps pricing page](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). Paid parallel jobs remove the monthly time limit and allow you to run each job for up to 360 minutes (6 hours). +When the free tier is no longer sufficient, you can pay for more capacity per parallel job. For pricing cost per parallel job, see the [Azure DevOps pricing page](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). Paid parallel jobs remove the monthly time limit and allow you to run each job for up to 360 minutes (6 hours). [Buy Microsoft-hosted parallel jobs](#how-do-i-buy-more-parallel-jobs). -New organizations have a maximum limit of 25 parallel jobs for Microsoft-hosted agents. [Contact support](https://azure.microsoft.com/support/devops/) to request a limit increase, subject to capacity in your organization's region. +New organizations have a maximum limit of 25 parallel jobs for Microsoft-hosted agents. [Contact support](https://azure.microsoft.com/support/devops/) to request a limit increase. Limit increases are subject to capacity in your organization's region. -When you purchase your first Microsoft-hosted parallel job, the number of parallel jobs you have in the organization is still one. To be able to run two jobs concurrently, you'll need to purchase two parallel jobs if you're currently on the free tier. The first purchase only removes the time limits on the first job. +When you purchase your first Microsoft-hosted parallel job, the number of parallel jobs you have in the organization is still one. To be able to run two jobs concurrently, you need to purchase two parallel jobs if you're currently on the free tier. The first purchase only removes the time limits on the first job. > [!TIP] > If your pipeline exceeds the maximum job timeout, try splitting your pipeline @@ -96,16 +96,14 @@ When you purchase your first Microsoft-hosted parallel job, the number of parall For self-hosted parallel jobs, you can register any number of [self-hosted agents](../agents/agents.md) in your organization. We charge based on the number of jobs you want to run at a time, not the number of agents registered. There are no time limits on self-hosted jobs. -For public projects that are self-hosted, you can have unlimited parallel jobs running. For private projects, you can have one job and one additional job for each active Visual Studio Enterprise subscriber who is a member of your organization. - +For public projects that are self-hosted, you can have unlimited parallel jobs running. For private projects, you can have one job plus one job for each active Visual Studio Enterprise subscriber who is a member of your organization. | | Number of parallel jobs | Time limit | |:----------|--------------------------| ------------| | **Public project** | Unlimited | None| -| **Private project** | One self-hosted job; For each active Visual Studio Enterprise subscriber who is a member of your organization, you get one additional self-hosted parallel job. | None | +| **Private project** | One self-hosted job plus one parallel job for each active Visual Studio Enterprise subscriber who is a member of your organization. | None | - -When the free tier is no longer sufficient for your self-hosted private project, you can purchase more additional capacity per parallel job. For pricing cost per parallel job, see the [Azure DevOps pricing page](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). +When the free tier is no longer sufficient for your self-hosted private project, you can purchase more capacity per parallel job. For pricing cost per parallel job, see the [Azure DevOps pricing page](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). [Buy self-hosted parallel jobs](#how-do-i-buy-more-parallel-jobs). @@ -113,16 +111,15 @@ When the free tier is no longer sufficient for your self-hosted private project, ::: moniker-end - ::: moniker range="azure-devops" ## How many parallel jobs do I need? -As the number of queued builds and releases exceeds the number of parallel jobs you have, your build and release queues grow longer. When you find the queue delays are too long, you can purchase additional parallel jobs as needed. There are several methods you can use to check your parallel job limits and job history. +As the number of queued builds and releases exceeds the number of parallel jobs you have, your build and release queues grow longer. When you find the queue delays are too long, you can purchase more parallel jobs as needed. There are several methods you can use to check your parallel job limits and job history. ### View job history using the pool consumption report -You can use the **Pool consumption report**, available on the **Analytics** tab of your agent pool, to see a chart of running and queued jobs graphed with your parallel jobs for the previous 30 days. If you have a backlog of queued jobs and your running jobs are at the concurrency limit, you may wish to purchase more parallel jobs. For more information, see [Pool consumption report](../agents/pool-consumption-report.md). +You can use the **Pool consumption report**, available on the **Analytics** tab of your agent pool, to see a chart of running and queued jobs graphed with your parallel jobs for the previous 30 days. If you have a backlog of queued jobs and your running jobs are at the concurrency limit, you might want to purchase more parallel jobs. For more information, see [Pool consumption report](../agents/pool-consumption-report.md). :::image type="content" source="../agents/media/pool-consumption-report/historical-graph-azure-pipelines.png" alt-text="Microsoft-hosted agent pool historical graph"::: @@ -134,7 +131,7 @@ Figure out how many parallel jobs you need by first seeing how many parallel job :::image type="content" source="media/concurrent-pipelines-vsts/control-panel-account-build-and-release-resource-limits.png" alt-text="Location of parallel jobs in organization settings."::: - URL example: `https://{your_organization}/_admin/_buildQueue?_a=resourceLimits` + URL example: `https://{Your_Organization}/_admin/_buildQueue?_a=resourceLimits` 2. View the maximum number of parallel jobs that are available in your organization. @@ -142,13 +139,13 @@ Figure out how many parallel jobs you need by first seeing how many parallel job ### Estimate costs -A simple rule of thumb: Estimate that you'll need one parallel job for every four to five users in your organization. +A simple rule of thumb: Estimate that you need one parallel job for every four to five users in your organization. In the following scenarios, you might need multiple parallel jobs: -* If you have multiple teams, and if each of them require CI, you'll likely need a parallel job for each team. -* If your CI trigger applies to multiple branches, you'll likely need a parallel job for each active branch. -* If you develop multiple applications by using one organization or server, you'll likely need additional parallel jobs: one to deploy each application at the same time. +* If you have multiple teams, and if each of them require CI, you might need a parallel job for each team. +* If your CI trigger applies to multiple branches, you might need a parallel job for each active branch. +* If you develop multiple applications by using one organization or server, you might need more parallel jobs: one to deploy each application at the same time. ::: moniker-end @@ -158,7 +155,7 @@ In the following scenarios, you might need multiple parallel jobs: To buy more parallel jobs: -* [Billing must be set up for your organization](../../organizations/billing/set-up-billing-for-your-organization-vs.md) +* [Billing must be set up for your organization](../../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing) * You need to be a member of the [**Project Collection Administrators** group](../../organizations/security/look-up-project-collection-administrators.md). ### Buy parallel jobs @@ -166,39 +163,34 @@ To buy more parallel jobs: Buy more parallel jobs within your organization settings: 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. +1. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. ![Open Organization settings](../../media/settings/open-admin-settings-vert.png) -3. Select **Parallel jobs** under Pipelines, and then select either **Change** for Microsoft-hosted jobs or **Change** for self-hosted jobs. +1. Select **Parallel jobs** under Pipelines, and then select either **Purchase parallel jobs** or **Change** for Microsoft-hosted jobs or **Change** for self-hosted jobs. :::image type="content" source="../../organizations/billing/media/shared/manage-parallel-jobs.png" alt-text="manage parallel jobs image"::: -4. Enter your desired amount, and then **Save**. +1. Enter your desired amount, and then **Save**. -5. It may take up to 30 minutes for your additional parallel jobs to become available to use. +1. It might take up to 30 minutes for your parallel jobs to become available to use. For pricing cost per parallel job, see the [Azure DevOps pricing page](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). ## How do I change the quantity of parallel jobs for my organization? 1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. +1. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. ![Open Organization settings](../../media/settings/open-admin-settings-vert.png) -3. Select **Parallel jobs** under Pipelines, and then select either **Purchase parallel jobs** or **Change** for Microsoft-hosted jobs or **Change** for self-hosted jobs. +1. Select **Parallel jobs** under Pipelines, and then select either **Purchase parallel jobs** or **Change** for Microsoft-hosted jobs or **Change** for self-hosted jobs. :::image type="content" source="../../organizations/billing/media/shared/manage-parallel-jobs.png" alt-text="image of manage parallel jobs"::: -4. Enter a lesser or greater quantity of Microsoft-hosted or self-hosted jobs, and then select **Save**. - - > [!IMPORTANT] - > Hosted XAML build controller isn't supported. If you have an organization where you need to run [XAML builds](/previous-versions/visualstudio/visual-studio-2013/ms181709(v=vs.120)), - > set up an [on-premises build server](/previous-versions/visualstudio/visual-studio-2013/ms252495(v=vs.120)) - > and switch to an [on-premises build controller](/previous-versions/visualstudio/visual-studio-2013/ee330987(v=vs.120)). For more information about the hosted XAML model, see [Get started with XAML](../create-first-pipeline.md). +1. Enter a lesser or greater quantity of Microsoft-hosted or self-hosted jobs, and then select **Save**. -5. It may take up to 30 minutes for the new number of parallel jobs to become active. +1. It might take up to 30 minutes for the new number of parallel jobs to become active. ::: moniker-end @@ -206,7 +198,7 @@ For pricing cost per parallel job, see the [Azure DevOps pricing page](https://a ## How is a parallel job consumed in DevOps Services? -Consider an organization that has only one Microsoft-hosted parallel job. This job allows users in that organization to collectively run only one job at a time. When additional jobs are triggered, they're queued and will wait for the previous job to finish. +Consider an organization that has only one Microsoft-hosted parallel job. This job allows users in that organization to collectively run only one job at a time. When more jobs are triggered, they're queued until previous jobs finish. If you use release or YAML pipelines, then a run consumes a parallel job only when it's being actively deployed to a stage. While the release is waiting for an approval or a manual intervention, it doesn't consume a parallel job. @@ -215,100 +207,14 @@ When you run a [server job](../process/phases.md#server-jobs) or deploy to a [de ![Simple example of parallel jobs](media/concurrent-pipelines-vsts/concurrent-pipelines-simple-example.png) 1. FabrikamFiber CI Build 102 (main branch) starts first. -2. Deployment of FabrikamFiber Release 11 gets triggered by completion of FabrikamFiber CI Build 102. -3. FabrikamFiber CI Build 101 (feature branch) is triggered. The build can't start yet because Release 11's deployment is active. So the build stays queued. -4. Release 11 waits for approvals. Fabrikam CI Build 101 starts because a release that's waiting for approvals doesn't consume a parallel job. -5. Release 11 is approved. It resumes only after Fabrikam CI Build 101 is completed. - - -::: moniker-end - - -::: moniker range="< azure-devops-2019" - -## How is a parallel job consumed? - -For example, a collection in a Team Foundation Server has one parallel job. This allows users in that collection to run only one release at a time. When additional releases are triggered, they're queued and will wait for the previous one to complete. - -A release requires a parallel job only when it's being actively deployed to a stage. Waiting for an approval doesn't consume a parallel job. However, waiting for a manual intervention in the middle of a deployment does consume a parallel job. - -![Parallel jobs simple example](media/concurrent-pipelines-tfs/concurrent-pipelines-simple-example.png) - -1. FabrikamFiber Release 10 is first to be deployed. -2. Deployment of FabrikamFiber Release 11 starts after Release 10's deployment is complete. -3. Release 12 is queued until Release 11's deployment is active. -4. Release 11 waits for an approval. Release 12's deployment starts because a release waiting for approvals doesn't consume a parallel job. -5. Even though Release 11 is approved, it resumes only after Release 12's deployment is completed. -6. Release 11 is waiting for manual intervention. Release 13 can't start because the manual intervention state consumes a parallel job. - -> Manual intervention does not consume a job in TFS 2017.1 and newer. - -## Parallel processing within a single release - -Parallel processing within a single release doesn't require additional parallel jobs. So long as you have enough agents, you can deploy to multiple stages in a release at the same time. - -For example, suppose your collection has three parallel jobs. You can have more than three agents running at the same time to perform parallel operations within releases. For instance, notice below that four or five agents are actively running jobs from three parallel jobs. - -![Parallel jobs with additional agents example](media/concurrent-pipelines-tfs/concurrent-pipelines-with-additional-agents-example.png) - -## Parallel jobs in an organization - -For example, here's an organization that has multiple Team Foundation Servers. Two of their users have Visual Studio Enterprise subscriptions that they can use at the same time across all their on-premises servers and in each collection so long as the customer adds them as users to both the servers as explained below. - -![Parallel jobs in an organization example](media/concurrent-pipelines-tfs/concurrent-pipelines-in-an-organization-example.png) - -## Determine the number of parallel jobs you need - -You can begin by seeing if your teams can get by with the parallel jobs you've got by default. As the number of queued releases exceeds the number of parallel jobs you have, your release queues will grow longer. When you find the queue delays are too long, you can purchase additional parallel jobs as needed. - -### Simple estimate - -A simple rule of thumb: Estimate that you'll need one parallel job for every 10 users in your server. - -### Detailed estimate - -In the following scenarios you might need multiple parallel jobs: - -* If you have multiple teams, if each of them require a CI build, and if each of the CI builds is configured to trigger a release, then you'll likely need a parallel job for each team. - -* If you develop multiple applications in one collection, then you'll likely need additional parallel jobs: one to deploy each application at the same time. - -## Use your Visual Studio Enterprise subscription benefit - -Users who have Visual Studio Enterprise subscriptions are assigned to **VS Enterprise** access level in the Users hub of TFS instance. Each of these users contributes one additional parallel job to each collection. You can use this benefit on all Team Foundation Servers in your organization. - -1. Browse to **Server settings**, **Access levels**. - - ![control panel server versus enterprise access levels](media/concurrent-pipelines-tfs/control-panel-server-vs-enterprise-access-levels.png) - - URL example: `http://{your_server}:8080/tfs/_admin/_licenses` - -2. On the left side of the page, click **VS Enterprise**. - -3. Add your users who have Visual Studio Enterprise subscriptions. - -After you've added these users, additional licenses will appear on the resource limits page described below. - - - -## Purchase additional parallel jobs - -If you need to run more parallel releases, you can [buy additional private jobs from the Visual Studio marketplace](https://marketplace.visualstudio.com/items?itemName=ms.build-release-private-pipelines). Since there's no way to directly purchase parallel jobs from Marketplace for a TFS instance at present, you must first buy parallel jobs for an Azure DevOps organization. After you buy the private jobs for an Azure DevOps organization, you enter the number of purchased parallel jobs manually on the resource limits page described below. - -## View and manage parallel jobs - -1. Browse to **Collection settings**, **Pipelines**, **Resource limits**. - - ![Set resource limits](media/concurrent-pipelines-tfs/control-panel-account-build-and-release-resource-limits.png) - - URL example: `http://{your_server}:8080/tfs/DefaultCollection/_admin/_buildQueue?_a=resourceLimits` - -2. View or edit the number of purchased parallel jobs. - +1. Deployment of FabrikamFiber Release 11 gets triggered by completion of FabrikamFiber CI Build 102. +1. FabrikamFiber CI Build 101 (feature branch) is triggered. The build can't start yet because Release 11's deployment is active. So the build stays queued. +1. Release 11 waits for approvals. Fabrikam CI Build 101 starts because a release that's waiting for approvals doesn't consume a parallel job. +1. Release 11 is approved. It resumes only after Fabrikam CI Build 101 is completed. ::: moniker-end -::: moniker range="< azure-devops-2019 || azure-devops" +::: moniker range="=azure-devops" ## FAQ @@ -331,62 +237,34 @@ Currently, there isn't a way to partition or dedicate parallel job capacity to a * You purchase two parallel jobs in your organization. * You start two runs in the first project, and both the parallel jobs are consumed. -* You start a run in the second project. That run won't start until one of the runs in your first project is completed. - +* You start a run in the second project. That run doesn't start until one of the runs in your first project is completed. ### Are there limits on who can use Azure Pipelines? -You can have as many users as you want when you're using Azure Pipelines. There's no per-user charge for using Azure Pipelines. Users with both [basic and stakeholder access](https://visualstudio.microsoft.com/products/visual-studio-team-services-feature-matrix-vs) can author as many builds and releases as they want. +You can have as many users as you want when you're using Azure Pipelines. There's no per-user charge for using Azure Pipelines. Users with both [basic and stakeholder access](../../organizations/security/access-levels.md) can author as many builds and releases as they want. ### Are there any limits on the number of builds and release pipelines that I can create? No. You can create hundreds or even thousands of pipelines for no charge. You can register any number of self-hosted agents for no charge. -### As a Visual Studio Enterprise subscriber, do I get additional parallel jobs for TFS and Azure Pipelines? - -Yes. Visual Studio Enterprise subscribers get [one parallel job in Team Foundation Server 2017 or later](concurrent-pipelines-tfs.md) and one self-hosted parallel job in each Azure DevOps Services organization where they are a member. - ### What about the option to pay for hosted agents by the minute? Some of our earlier customers are still on a per-minute plan for the hosted agents. In this plan, you pay $0.05/minute for the first 20 hours after the free tier, and $0.01/minute after 20 hours. Because of the following limitations in this plan, you might want to consider moving to the parallel jobs model: - When you're using the per-minute plan, you can run only one job at a time. -- If you run builds for more than 14 paid hours in a month, the per-minute plan might be less cost-effective than the parallel jobs model. +- When you run builds for more than 14 paid hours in a month, the per-minute plan might be less cost-effective than the parallel jobs model. -### I use XAML build controllers with my organization. How am I charged for those? +### I use XAML build controllers with my organization. How am I charged for them? You can register one XAML build controller for each self-hosted parallel job in your organization. -Your organization gets at least one free self-hosted parallel job, so you can register one XAML build controller for no additional charge. -For each additional XAML build controller, you'll need an additional self-hosted parallel job. +Your organization gets at least one free self-hosted parallel job, so you can register one XAML build controller for no extra charge. +For each additional XAML build controller, you need an additional self-hosted parallel job. ::: moniker-end -::: moniker range="< azure-devops-2019" - -### Who can use the system? - -TFS users with a [TFS CAL](https://visualstudio.microsoft.com/team-services/tfs-pricing) can author as many releases as they want. - -To approve releases, a TFS CAL isn't necessary; any user with [stakeholder access](../..//organizations/security/access-levels.md) can approve or reject releases. - -### Do I need parallel jobs to run builds on TFS? - -No, on TFS you don't need parallel jobs to run builds. You can run as many builds as you want at the same time for no additional charge. - -       - -### Do I need parallel jobs to manage releases in versions before TFS 2017? - -No. - -In TFS 2015, so long as your users have a TFS CAL, they can manage releases for no additional charge in trial mode. We called it "trial mode" to indicate that we would eventually charge for managing releases. Despite this label, we fully support managing releases in TFS 2015. - -::: moniker-end - - ## Related articles -- [Set up billing](../../organizations/billing/set-up-billing-for-your-organization-vs.md) +- [Set up billing](../../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing) - [Manage paid access](../../organizations/billing/buy-basic-access-add-users.md) - [Buy access to test hub](../../organizations/billing/buy-access-tfs-test-hub.md) -- [Add user for billing management](../../organizations/billing/add-backup-billing-managers.md) +- [Add user for billing management](../../organizations/billing/set-up-billing-for-your-organization-vs.md#give-a-user-access-to-manage-billing) - [Azure DevOps billing overview](../../organizations/billing/overview.md) diff --git a/docs/pipelines/licensing/media/concurrent-pipelines-vsts/control-panel-account-build-and-release-resource-limits.png b/docs/pipelines/licensing/media/concurrent-pipelines-vsts/control-panel-account-build-and-release-resource-limits.png index 540ddd38246..ccdf57cb75d 100644 Binary files a/docs/pipelines/licensing/media/concurrent-pipelines-vsts/control-panel-account-build-and-release-resource-limits.png and b/docs/pipelines/licensing/media/concurrent-pipelines-vsts/control-panel-account-build-and-release-resource-limits.png differ diff --git a/docs/pipelines/media/azure-service-connection-settings-devops-server.png b/docs/pipelines/media/azure-service-connection-settings-devops-server.png new file mode 100644 index 00000000000..3a3bff62771 Binary files /dev/null and b/docs/pipelines/media/azure-service-connection-settings-devops-server.png differ diff --git a/docs/pipelines/media/azure-service-connection-settings-devops-services.png b/docs/pipelines/media/azure-service-connection-settings-devops-services.png new file mode 100644 index 00000000000..b4744228936 Binary files /dev/null and b/docs/pipelines/media/azure-service-connection-settings-devops-services.png differ diff --git a/docs/pipelines/media/python/azure-cloud-shell-interface.png b/docs/pipelines/media/python/azure-cloud-shell-interface.png index acb0a374486..00c0140e6a5 100644 Binary files a/docs/pipelines/media/python/azure-cloud-shell-interface.png and b/docs/pipelines/media/python/azure-cloud-shell-interface.png differ diff --git a/docs/pipelines/media/python/pipeline-stages.png b/docs/pipelines/media/python/pipeline-stages.png new file mode 100644 index 00000000000..39fc64537fe Binary files /dev/null and b/docs/pipelines/media/python/pipeline-stages.png differ diff --git a/docs/pipelines/media/python/pipeline-summary-stages-section.png b/docs/pipelines/media/python/pipeline-summary-stages-section.png new file mode 100644 index 00000000000..7ab2e4a42c7 Binary files /dev/null and b/docs/pipelines/media/python/pipeline-summary-stages-section.png differ diff --git a/docs/pipelines/media/python/service-connection-01.png b/docs/pipelines/media/python/service-connection-01.png deleted file mode 100644 index af0c6bc24f1..00000000000 Binary files a/docs/pipelines/media/python/service-connection-01.png and /dev/null differ diff --git a/docs/pipelines/media/python/service-connection-02.png b/docs/pipelines/media/python/service-connection-02.png deleted file mode 100644 index cbd35b6305b..00000000000 Binary files a/docs/pipelines/media/python/service-connection-02.png and /dev/null differ diff --git a/docs/pipelines/media/python/service-connection-type-devops-services.png b/docs/pipelines/media/python/service-connection-type-devops-services.png new file mode 100644 index 00000000000..aeb1aa77bea Binary files /dev/null and b/docs/pipelines/media/python/service-connection-type-devops-services.png differ diff --git a/docs/pipelines/media/python/where-is-your-code-devops-server.png b/docs/pipelines/media/python/where-is-your-code-devops-server.png new file mode 100644 index 00000000000..62b2f70f0f9 Binary files /dev/null and b/docs/pipelines/media/python/where-is-your-code-devops-server.png differ diff --git a/docs/pipelines/media/python/where-is-your-code.png b/docs/pipelines/media/python/where-is-your-code.png index f708eb465c1..89b1966c24f 100644 Binary files a/docs/pipelines/media/python/where-is-your-code.png and b/docs/pipelines/media/python/where-is-your-code.png differ diff --git a/docs/pipelines/migrate/from-travis.md b/docs/pipelines/migrate/from-travis.md index b34853c27da..db1cd45a5f1 100644 --- a/docs/pipelines/migrate/from-travis.md +++ b/docs/pipelines/migrate/from-travis.md @@ -31,7 +31,7 @@ There are many differences between Travis and Azure Pipelines, including: * A GitHub account where you can create a repository. [Create one for free](https://github.com). * An Azure DevOps organization. [Create one for free](../get-started/pipelines-sign-up.md). If your team already has one, then make sure you're an administrator of the Azure DevOps project that you want to use. -* An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can [request a free tier](../troubleshooting/troubleshooting.md#check-for-available-parallel-jobs). +* An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can [request a free tier](../troubleshooting/troubleshoot-start.md#check-for-available-parallel-jobs). * Basic knowledge of Azure Pipelines. If you're new to Azure Pipelines, see the following to learn more about Azure Pipelines and how it works prior to starting your migration: * [Create your first pipeline](../create-first-pipeline.md) * [Key concepts for new Azure Pipelines users](../get-started/key-pipelines-concepts.md) @@ -57,9 +57,9 @@ For example, to select Node.JS 16.x: **azure-pipelines.yml** ``` yaml steps: -- task: NodeTool@0 +- task: UseNode@1 inputs: - versionSpec: '16.x' + version: '16.x' ``` ### Language mappings @@ -101,7 +101,7 @@ dependency installation step or execution inside a docker container: | `nix` | `docker run -v $(pwd):/src -w /src nixos/nix nix-build` | `perl6` | `sudo apt-get install rakudo`
      `PERL6LIB=lib prove -v -r --exec=perl6 t/` | `rust` | `curl -sSf https://sh.rustup.rs | sh -s -- -y`
      `cargo build --verbose`
      `cargo test --verbose` | -| `scala` | echo "deb `https://repo.scala-sbt.org/scalasbt/debian` /" | /etc/apt/sources.list.d/sbt.list
      `sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 2EE0EA64E40A89B84B2DF73499E82A75642AC823`
      `sudo apt-get update`
      `sudo apt-get install sbt`
      `sbt ++2.11.6 test` | +| `scala` | `echo "deb `https://repo.scala-sbt.org/scalasbt/debian` /" | /etc/apt/sources.list.d/sbt.list`
      `sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 2EE0EA64E40A89B84B2DF73499E82A75642AC823`
      `sudo apt-get update`
      `sudo apt-get install sbt`
      `sbt ++2.11.6 test` | | `smalltalk` | `docker run -v $(pwd):/src -w /src hpiswa/smalltalkci smalltalkci` | ### Multiple language selections @@ -113,9 +113,9 @@ build environment targets both Node.JS 16.x and Ruby 3.2 or better: **azure-pipelines.yml** ``` yaml steps: -- task: NodeTool@0 +- task: UseNode@1 inputs: - versionSpec: '8.x' + version: '8.x' - task: UseRubyVersion@0 inputs: versionSpec: '>= 3.2' @@ -489,7 +489,7 @@ The `TRAVIS_OS_NAME` variable contains values that map to values provided by the | `osx` | `Darwin` | The build is running on macOS. | | `windows` | `Windows_NT` | The build is running on Windows. | -To learn more, see [Predefined environment variables](../build/variables.md). +For more information, see [Predefined environment variables](../build/variables.md). If there isn't a variable for the data you need, then you can use a shell command to get it. For example, a good substitute of an environment diff --git a/docs/pipelines/overview-azure.md b/docs/pipelines/overview-azure.md index e3951f258e7..2a8ea0e683c 100644 --- a/docs/pipelines/overview-azure.md +++ b/docs/pipelines/overview-azure.md @@ -1,338 +1,67 @@ --- -title: Deploy to Azure index to content -ms.custom: seodec18, contperf-fy21q4 -description: Learn how to deploy to Azure using Azure Pipelines. Tutorials, references, and other documentation. -ms.assetid: BC7FACEF-6E79-4BBA-BF53-07BD27EEB235 +title: Deploy to Azure services +description: See articles that describe how different Azure services support continuous integration (CI) and continuous delivery (CD) with Azure Pipelines. +ms.assetid: BC7FACEF-6E79-4BBA-BF53-07BD27EEB235 ms.author: jukullam author: juliakm -ms.date: 01/24/2023 +ms.date: 07/15/2024 ms.topic: overview monikerRange: '<= azure-devops' --- -# Deploy to Azure +# Deploy to Azure services [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - Azure Pipelines combines continuous integration (CI) and continuous delivery (CD) to test and build your code and ship it to any target. While you don't have to use Azure services with Pipelines, Pipelines can help you take advantage of Azure. You can use Pipelines to integrate your CI/CD process with most Azure services. +Azure Pipelines combines continuous integration (CI) and continuous delivery (CD) to test and build your code and ship it to any target. While you don't have to use Azure services with Azure Pipelines, you can use Azure Pipelines to integrate your CI/CD process with most Azure services. Azure Pipelines CI/CD helps you take the best advantage of your Azure services. -To learn more about selecting an Azure service for hosting your application code, see [Choose an Azure compute service for your application](/azure/architecture/guide/technology-choices/compute-decision-tree). +The following articles describe how different Azure services support CI and CD with Azure Pipelines. -If you're just getting started, we recommend you review and get started with the following resources. +**Azure App Configuration** +- [Push settings to App Configuration with Azure Pipelines](/azure/azure-app-configuration/push-kv-devops-pipeline) +- [Pull settings from App Configuration with Azure Pipelines](/azure/azure-app-configuration/pull-key-value-devops-pipeline) -:::row::: - :::column span="1"::: - **Azure service** - :::column-end::: - :::column span="3"::: - **Integration points** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure DevOps Projects/Azure DevOps Starter](https://azure.microsoft.com/features/devops-projects/) - :::column-end::: - :::column span="3"::: - Start using Azure Pipelines to automate the setup of a CI/CD of your application to Azure. Choose where to deploy your application such as Virtual Machines, Azure App Service, Azure Kubernetes Services (AKS), Azure SQL Database, or Azure Service Fabric. - To learn more, see [Overview of DevOps Starter](/azure/devops-project/overview). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure portal](/azure/azure-portal/azure-portal-overview) - :::column-end::: - :::column span="3"::: - The Azure portal is a web-based, unified console from which you can build, manage, and monitor everything from simple web apps to complex cloud deployments. Also, you can create custom dashboards for an organized view of resources and configure accessibility options. If you have an Azure DevOps Services organization, you have access to the Azure portal. - [Sign in to your Azure portal](https://portal.azure.com/). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [DevOps solutions on Azure](https://azure.microsoft.com/solutions/devops/#products) - :::column-end::: - :::column span="3"::: - Use end-to-end solutions on Azure to implement DevOps practices throughout application planning, development, delivery, and operations. Apply the right combination of DevOps technologies, culture, and processes to enable continual software delivery and better value for customers. Get started with the following Learn modules: - - [Deploy applications with Azure DevOps](/training/paths/deploy-applications-with-azure-devops/) - - [Build applications with Azure DevOps](/training/paths/build-applications-with-azure-devops/) - - [Deploy and maintain cloud-native apps with GitHub actions and Azure Pipelines](/training/modules/cna-deploy-maintain/) - - [Load test Azure web apps by using Azure DevOps](/training/modules/load-test-web-app-azure-devops/) - :::column-end::: -:::row-end::: ---- +**Azure App Service** +- [Deploy to App Service using Azure Pipelines](/azure/app-service/deploy-azure-pipelines) +- [Deploy a custom container to Azure App Service with Azure Pipelines](apps/cd/deploy-docker-webapp.md) +- [Use Azure Pipelines to build and deploy a Python web app to Azure App Service](ecosystems/python-webapp.md) -Follow the links provided in the following table to learn more about the Azure services that support continuous integration (CI) and continuous delivery (CD) using Azure Pipelines. For a complete list of Azure Pipelines tasks, see [Build and release tasks](tasks/index.md). +**Azure Container Registry** +- [Build and push Docker images to Azure Container Registry](ecosystems/containers/acr-template.md) +**Azure Cosmos DB** +- [Set up a CI/CD pipeline with the Azure Cosmos DB Emulator build task in Azure DevOps](/azure/cosmos-db/tutorial-setup-ci-cd) -:::row::: - :::column span="1"::: - **Azure service** - :::column-end::: - :::column span="3"::: - **Integration points** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure App Service](https://azure.microsoft.com/services/app-service/#overview) - :::column-end::: - :::column span="3"::: - An HTTP-based service for hosting web applications, REST APIs, and mobile back ends; the Azure App Service employs Azure Pipelines to deliver CI/CD. To learn more, see: - - [App Service overview](/azure/app-service/overview) - - [Deploy an Azure Web App](/azure/app-service/deploy-azure-pipelines) - - [Use CI/CD to deploy a Python web app to Azure App Service on Linux](ecosystems/python-webapp.md) - - [Continuously deploy from a Jenkins build](release/integrate-jenkins-pipelines-cicd.md) - - [Azure App Service Deploy task](/azure/devops/pipelines/tasks/reference/azure-rm-web-app-deployment-v4) - - [Azure App Service Manage task](/azure/devops/pipelines/tasks/reference/azure-app-service-manage-v0) - - [Azure App Service Settings task](/azure/devops/pipelines/tasks/reference/azure-app-service-settings-v1) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure App Configuration](https://azure.microsoft.com/services/app-configuration/) - :::column-end::: - :::column span="3"::: - Service to centrally manage application settings and feature flags. To learn more, see the following articles: - - [Push settings to App Configuration with Azure Pipelines](/azure/azure-app-configuration/push-kv-devops-pipeline) - - [Pull settings to App Configuration with Azure Pipelines](/azure/azure-app-configuration/pull-key-value-devops-pipeline). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Blob Storage](https://azure.microsoft.com/services/storage/blobs/) - [Azure Storage](https://azure.microsoft.com/services/#storage) - :::column-end::: - :::column span="3"::: - Store and access unstructured data at scale using Azure Pipelines and Azure Blob Storage. - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Static Web Apps](https://azure.microsoft.com/services/app-service/static/) - :::column-end::: - :::column span="3"::: - Use Azure Static Web Apps to automatically build and deploy a full stack web app to Azure from a code repository. - - [Tutorial: Publish Azure Static Web Apps with Azure DevOps](/azure/static-web-apps/publish-devops) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Container Registry](https://azure.microsoft.com/services/container-registry/) - :::column-end::: - :::column span="3"::: - Build, store, secure, scan, replicate, and manage container images and artifacts. For example, build and publish a private Docker registry service. To learn more, see [Build and push Docker images to Azure Container Registry](ecosystems/containers/acr-template.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - **Azure Databases** - [Azure SQL Database](https://azure.microsoft.com/products/azure-sql/database/) - [Azure Database for MySQL](https://azure.microsoft.com/services/mysql/) - [Azure Cosmos DB](https://azure.microsoft.com/services/cosmos-db/) - :::column-end::: - :::column span="3"::: - Use Azure Pipelines to deploy to Azure SQL Database, Azure Database for MySQL, or Azure Cosmos DB. To learn more, see the following articles: - - [Deploy to Azure SQL Database](targets/azure-sqldb.md) - - [Azure SQL Database Deployment task](/azure/devops/pipelines/tasks/reference/sql-azure-dacpac-deployment-v1) - - [Azure Database for MySQL Deployment task](/azure/devops/pipelines/tasks/reference/azure-mysql-deployment-v1) - - [Quickstart: Deploy to Azure MySQL](/azure/mysql/single-server/azure-pipelines-mysql-deploy) - - [Set up a CI/CD pipeline with the Azure Cosmos DB Emulator build task in Azure DevOps](/azure/cosmos-db/tutorial-setup-ci-cd) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Databricks](https://azure.microsoft.com/services/databricks) - [Azure Data Factory](https://azure.microsoft.com/services/data-factory/) - [Azure Machine Learning](https://azure.microsoft.com/services/machine-learning/) - :::column-end::: - :::column span="3"::: - Configure a pipeline to integrate with a fully managed, serverless data integration service and unlock insights from all your data. Create an Azure Pipeline that builds and deploys a machine learning model as a web service and to automate the machine learning lifecycle. To learn more, see the following resources: - - [Build a data pipeline by using Azure Data Factory, DevOps, and machine learning; Configure Azure Databricks and Azure Data Factory](apps/cd/azure/build-data-pipeline.md#configure-azure-databricks-and-azure-data-factory) - - [DevOps for Azure Databricks](https://marketplace.visualstudio.com/items?itemName=riserrad.azdo-databricks) - - [Prepare data, train, deploy, and monitor machine learning models with Azure Pipelines](/azure/machine-learning/how-to-devops-machine-learning). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure DevTest Labs](https://azure.microsoft.com/services/devtest-lab/) - :::column-end::: - :::column span="3"::: - Quickly provision development and test stages using reusable templates. To learn more, see [Manage a virtual machine in Azure DevTest Labs](apps/cd/azure/deploy-provision-devtest-lab.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Functions](https://azure.microsoft.com/services/functions/) - :::column-end::: - :::column span="3"::: - Provides a fully managed Platform as a service (PaaS) to implement serverless architecture. To learn more, see: - - [Deploy an Azure Function](/azure/azure-functions/functions-how-to-azure-devops) - - [Azure Function App task](/azure/devops/pipelines/tasks/reference/azure-function-app-v1) - - [Azure Function App for Containers task](/azure/devops/pipelines/tasks/reference/azure-function-app-container-v1) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Government](https://azure.microsoft.com/global-infrastructure/government/get-started/) - :::column-end::: - :::column span="3"::: - Use Azure Pipelines to set up CI/CD of your web app running in Azure Government.To learn more, see [Deploy an app in Azure Government with Azure Pipelines](/azure/azure-government/connect-with-azure-pipelines). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure IoT Edge](https://azure.microsoft.com/services/iot-edge/) - :::column-end::: - :::column span="3"::: - Use Azure Pipelines to managed services built on Azure IoT Hub. To learn more, see [Continuous integration and continuous deployment to Azure IoT Edge devices](/azure/iot-edge/how-to-continuous-integration-continuous-deployment) and [Create a CI/CD pipeline for IoT Edge with Azure DevOps Starter](/azure/iot-edge/how-to-devops-starter). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Key Vault](https://azure.microsoft.com/services/key-vault/) - :::column-end::: - :::column span="3"::: - Use Azure Pipelines to managed services for storing secret data. To learn more, see [Use Azure Key Vault secrets in Azure Pipelines](release/azure-key-vault.md) and [Azure Key Vault task](/azure/devops/pipelines/tasks/reference/azure-key-vault-v2). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Kubernetes Services (AKS)](https://azure.microsoft.com/services/kubernetes-service/) - :::column-end::: - :::column span="3"::: - Deploy and manage containerized applications with a fully managed Kubernetes service. To learn more, see [Build and deploy to Azure Kubernetes Service](ecosystems/kubernetes/aks-template.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Monitor](https://azure.microsoft.com/services/monitor/) - :::column-end::: - :::column span="3"::: - Configure alerts on available metrics for an Azure resource. Observe the configured Azure monitor rules for active alerts in a release pipeline. Define pre or post-deployment gates based on Query Azure Monitor Alerts. For details, see the following articles: - - [Define approvals and checks, Query Azure Monitor Alerts](process/approvals.md#query-azure-monitor-alerts) - - [Release deployment control using gates]() - - [Azure Monitor Alerts task](/azure/devops/pipelines/tasks/reference/azure-monitor-alerts-v0) - - [Query Azure Monitor Alerts task](/azure/devops/pipelines/tasks/reference/azure-monitor-v1). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Policy](https://azure.microsoft.com/services/azure-policy/) - :::column-end::: - :::column span="3"::: - Manage and prevent IT issues by using policy definitions that enforce rules and effects for your resources. To learn how, see [Check policy compliance with gates](policies/azure-policy.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Resource Manager (ARM)](https://azure.microsoft.com/features/resource-manager/) - [ARM Templates](https://azure.microsoft.com//services/arm-templates/) - :::column-end::: - :::column span="3"::: - Use ARM templates to define the infrastructure and dependencies and streamline authentication to deploy your app using Azure Pipelines. Specifically, you can: - - Create an Azure Resource Manager service connection using automated security - - Create an Azure Resource Manager service connection with an existing service principal - - Create an Azure Resource Manager service connection to a VM with a managed service identity - - Connect to an Azure Government Cloud - - Connect to Azure Stack
      - To learn more, see [Connect to Microsoft Azure](library/connect-to-azure.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Service Bus](https://azure.microsoft.com/services/service-bus/) - :::column-end::: - :::column span="3"::: - In a release pipeline, send a message to an Azure Service Bus using a service connection. To learn more, see [Publish To Azure Service Bus task](/azure/devops/pipelines/tasks/reference/publish-to-azure-service-bus-v1) and [Manage service connections, Azure Service Bus service connection](library/service-endpoints.md#azure-service-bus-service-connection). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Service Fabric](https://azure.microsoft.com/services/service-fabric) - :::column-end::: - :::column span="3"::: - Distributed systems platform that can run in many environments, including Azure or on-premises. To learn more, see the following articles: [Tutorial: Deploy an application with CI/CD to a Service Fabric cluster](/azure/service-fabric/service-fabric-tutorial-deploy-app-with-cicd-vsts) and [Service Fabric Application Deployment task](/azure/devops/pipelines/tasks/reference/service-fabric-deploy-v1). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Stack](https://azure.microsoft.com/overview/azure-stack/) - :::column-end::: - :::column span="3"::: - Build, deploy, and run hybrid and edge computing apps consistently across your ecosystems. To learn more, see [Deploy to Azure Stack Hub App Service using Azure Pipelines](targets/azure-stack.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure Virtual Machines](https://azure.microsoft.com/services/virtual-machines/) - [Azure Virtual Machine Scale Sets](https://azure.microsoft.com/services/virtual-machine-scale-sets/) - :::column-end::: - :::column span="3"::: - Simplify continuous delivery to Azure VMs using Azure Pipelines. To learn more, see these articles: - - [Build an Azure virtual machine using an Azure RM template](./apps/cd/azure/deploy-arm-template.md) - - [Deploy to Azure VMs using deployment groups in Azure Pipelines](release/deployment-groups/deploying-azure-vms-deployment-groups.md) - - [Tutorial: Deploy a Java app to a Virtual Machine Scale Set](apps/cd/azure/deploy-virtual-scale-set-java.md) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Azure WebApps](https://azure.microsoft.com/services/app-service/web/) - :::column-end::: - :::column span="3"::: - Use publish profile to deploy Azure WebApps for Windows from the Deployment Center. To learn more, see the following articles: - - [Deploy an Azure Web App](/azure/app-service/deploy-azure-pipelines) - - [Deploy an Azure Web App Container](apps/cd/deploy-docker-webapp.md) - - [Azure App Service Deploy task](/azure/devops/pipelines/tasks/reference/azure-rm-web-app-deployment-v4) - - [Azure App Service Manage task](/azure/devops/pipelines/tasks/reference/azure-app-service-manage-v0) - - [Azure App Service Settings task](/azure/devops/pipelines/tasks/reference/azure-app-service-settings-v1) - :::column-end::: -:::row-end::: ---- +**Azure Data Factory** +- [Configure Azure Databricks and Azure Data Factory](apps/cd/azure/build-data-pipeline.md#configure-azure-databricks-and-azure-data-factory) + +**Azure Government** +- [Deploy an app in Azure Government with Azure Pipelines](/azure/azure-government/connect-with-azure-pipelines) + +**Azure IoT Edge** +- [Continuous integration and continuous deployment to Azure IoT Edge devices](/azure/iot-edge/how-to-continuous-integration-continuous-deployment) + +**Azure Kubernetes Service** +- [Build and deploy to Azure Kubernetes Service with Azure Pipelines](ecosystems/kubernetes/aks-template.md) +**Azure Monitor** +- [Query Azure Monitor Alerts](process/approvals.md#query-azure-monitor-alerts) +**Azure Database for MySQL - Flexible Server** +- [Azure Pipelines for Azure Database for MySQL - Flexible Server](/azure/mysql/flexible-server/azure-pipelines-deploy-database-task) - +For a complete list of Azure Pipelines tasks, see [Build and release tasks](tasks/index.md) and the [Azure Pipelines task reference](/azure/devops/pipelines/tasks/reference). diff --git a/docs/pipelines/packages/jenkins.md b/docs/pipelines/packages/jenkins.md deleted file mode 100644 index a32edb11305..00000000000 --- a/docs/pipelines/packages/jenkins.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Publish Artifacts with Jenkins -ms.custom: seodec18, devx-track-jenkins -description: How to publish Artifacts with Jenkins and Azure Pipelines -ms.assetid: FC3EC349-1F9B-42A7-B523-495F21BC73F6 -ms.date: 12/08/2021 -monikerRange: '<= azure-devops' ---- - -# Publish NuGet packages with Jenkins - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -With Azure Artifacts, you can leverage a variety of build and deployment automation tools such as Maven, Gradle, and Jenkins. This article will walk you through creating and publishing NuGet packages using Jenkins. - -## Prerequisites - -- [Install NuGet CLI](/nuget/tools/nuget-exe-cli-reference). -- [A personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) to authenticate your feed. -- [Azure DevOps Services account](https://azure.microsoft.com/services/devops/). -- [Azure Artifacts feed](../../artifacts/get-started-nuget.md). - -## Jenkins Setup - -This walkthrough uses the latest Jenkins running on Windows 10. Ensure the following Jenkins plugins are enabled: - -- [MSBuild](https://plugins.jenkins.io/msbuild/) -- [Git](https://plugins.jenkins.io/git/) -- [Git Client](https://plugins.jenkins.io/git-client/) -- [Credentials Binding plugin](https://plugins.jenkins.io/credentials-binding/) - -Some of these plugins are enabled by default, others you will need to install by using the Jenkins's "Manage Plugins" feature. - -### The sample project - -We will be using a C# class library sample project for this article. - -1. In Visual Studio, create a new project, and then select the C# **Class Library** template. - -1. Name your solution *FabrikamLibrary*. - -1. Open your solution and then right click on the project and select **Properties**. - -1. Select **Package** and then fill out the *description*, *product*, and *company* fields. - -1. Select **Save** when you are done. - -1. Check the new solution into a Git repository where your Jenkins server can access it later. - -:::image type="content" source="media/jenkins-package.png" alt-text="Screenshot showing how to configure the package properties for a class library project."::: - -## Create a NuGet package - -1. Open a new command prompt window navigate to your project directory. - -1. Run the `nuget spec` command to create a nuspec file. - -1. Open the newly created *FabrikamLibrary.nuspec* and remove the boilerplate tags *projectUrl* and *iconUrl*. Add an author inside the *authors* tag, and then change the tags from *Tag1 Tag2* to *fabrikam*. - -1. **Save** your file when you are done. - -1. Run the following command to create a NuGet package: `nuget pack FabrikamLibrary.csproj`. - -1. A NuGet package *FabrikamLibrary.1.0.0.nupkg* will be generated in the same directory as your *.csproj* file. - -## Connect to feed - -1. From within your project, select **Artifacts**, and then select your feed. You can [create a new feed](../../artifacts/get-started-nuget.md#create-a-feed) if you don't have one already. - -1. Select **Connect to feed**. - - :::image type="content" source="../../artifacts/media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot showing how to connect to your feed"::: - -1. Select **NuGet.exe** under the **NuGet** header. - - :::image type="content" source="../../artifacts/media/nuget-connect-feed.png" alt-text="Screenshot showing the NuGet.exe feed connection"::: - -1. If this is the first time using Azure Artifacts with Nuget.exe, select **Get the tools** button and follow the instructions to install the prerequisites. - - 1. Download the [latest NuGet version](https://www.nuget.org/downloads). - 1. Download and install the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider). - -1. Follow the instructions in the **Project setup** to connect to your feed. - - :::image type="content" source="../../artifacts/media/project-setup.png" alt-text="Screenshot showing the project setup section"::: - -## Create a build pipeline in Jenkins - -1. From your Jenkins dashboard, select **Create a job**. - -1. Enter an item name, and then select **Freestyle project**. Select **OK** when you are done. - - :::image type="content" source="./media/jenkins-freestyle.png" alt-text="Screenshot showing how to create a freestyle project in Jenkins"::: - -1. Select **Source Code Management**, and then select **Git**. Enter your Git repository and select the branches to build. - -1. Select **Build Environment**, and then select **Use secret text(s) or file(s)**. - -1. Select **Add**, and then select **Username and password (separated)**. - -1. Set the **Username Variable** to "FEEDUSER" and the **Password Variable** to "FEEDPASS". Select **Add** when you are done. - - :::image type="content" source="./media/jenkins-build-environment.png" alt-text="Screenshot showing how to set up build environment in jenkins."::: - -1. Set the *Username* to "token" and the *Password* to the personal access token PAT you generated earlier. Select **Add** to save your credentials. - - :::image type="content" source="./media/jenkins-add-credentials.png" alt-text="Screenshot showing how to add your credentials."::: - -1. Select **Build** > **Add build step**., and then select **Execute Windows batch command**. Enter your batch command in the command box. - -1. Select **Save** and then queue your build. - -## Publish a package using Jenkins - -1. Select your build pipeline, and then select **Configure** to edit your build definition. - -1. Select **Build**, and then select **Add build step** to add a new task. - -1. Select **Execute a Windows batch command** and enter the following commands in the command box: - - ```Command - .tools\VSS.NuGet\nuget sources update -Name -UserName "%FEEDUSER%" -Password "%FEEDPASS%" - .tools\VSS.NuGet\nuget push *.nupkg -Name -ApiKey key - ``` - -1. Select **Save**, and then queue your build. Your NuGet package should be published to your Azure Artifacts feed. - -## Related articles - -- [Publish and download pipeline Artifacts](../artifacts/pipeline-artifacts.md) -- [Release artifacts and artifact sources](../release/artifacts.md) -- [Restore NuGet packages in Azure Pipelines](./nuget-restore.md) diff --git a/docs/pipelines/packages/maven-restore.md b/docs/pipelines/packages/maven-restore.md new file mode 100644 index 00000000000..c45b1e36834 --- /dev/null +++ b/docs/pipelines/packages/maven-restore.md @@ -0,0 +1,165 @@ +--- +title: Restore Maven packages (YAML/Classic) +description: Learn how to restore Maven packages from internal and external feed using Azure Pipelines. +ms.topic: how-to +ms.date: 02/04/2025 +monikerRange: '<= azure-devops' +--- + +# Restore Maven packages with Azure Pipelines (YAML/Classic) + +This article guides you through setting up your YAML and Classic pipelines to restore your Maven packages from internal and external feeds. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|---------------------| +| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).
      - An [Azure Artifacts feed](../../artifacts/get-started-maven.md#create-a-feed).
      - **Permissions:**
          - To grant access to all pipelines in the project, you must be a member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md).
          - To create service connections, you must have the *Administrator* or *Creator* role for [service connections](../library/add-resource-protection.md). | + +## Restore packages from a feed in the same organization + +### [YAML](#tab/yaml/) + +::: moniker range="azure-devops" +1. Sign in to your Azure DevOps organization, and then navigate to your project. +::: moniker-end + +::: moniker range="< azure-devops" +1. Sign in to your Azure DevOps collection, and then navigate to your project. +::: moniker-end + +::: moniker range="<=azure-devops" +2. Select **Pipelines**, and then select your pipeline definition. +::: moniker-end + +3. Select **Edit**, and then add the following snippet to your YAML pipeline. + +```yml +steps: +- task: MavenAuthenticate@0 + displayName: 'Maven Authenticate' + inputs: + artifactsFeeds: 'YOUR_FEED_NAME' +- script: | + mvn install +``` + +### [Classic](#tab/classic/) + +::: moniker range="azure-devops" +1. Sign in to your Azure DevOps organization, and then navigate to your project. +::: moniker-end + +::: moniker range="< azure-devops" +1. Sign in to your Azure DevOps collection, and then navigate to your project. +::: moniker-end + +::: moniker range="<=azure-devops" +2. Select **Pipelines**, and then select your pipeline definition. +::: moniker-end + +3. Select **Edit**, and then select the `+` sign to add a new task. Add the *Maven Authenticate* and *Command line* tasks to your pipeline definition and configure them as follows: + + 1. **Maven Authenticate**: Select one or multiple feeds from the **Feeds** dropdown menu. + + 1. **Command line task**: + - **Display name**: Restore. + - **Script**: + ``` + mvn install + ``` + +4. Select **Save & queue** when you're done. + +--- + +## Restore packages from a feed in another organization + +To restore your packages from a feed in another Azure DevOps organization, you must first create a personal access token in the target organization, and then create a service connection to authenticate with the target feed. + +#### Create a Personal Access Token + +1. Navigate to the target organization where the feed is hosted + +1. [Create a personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **Packaging** > **Read & write** scope. + +1. Copy your personal access token as you'll need it in the next step. + +#### Create a Maven service connection + +1. Sign in to the Azure DevOps organization where your pipeline will run, and then navigate to your project. + +1. Navigate to **Project settings** > **Service connections**. + +1. Select **New service connection**, select **Maven**, and then select **Next**. + +1. Select **Username and Password** as the **Authentication method**, and then enter your **Repository URL** and your **Repository Id**. + +1. Enter your **Username** (a placeholder, as Azure Pipelines will use your `pom.xml` and the personal access token you created earlier to authenticate). For **Password**, paste your personal access token. + +1. Provide a **Name** for your service connection, and select **Grant access permission to all pipelines**. + +1. Select **Save** when you're done. + +#### Restore packages + +#### [YAML](#tab/yaml/) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select your pipeline definition. + +1. Select **Edit**, and then add the following snippet to your YAML pipeline. + +```yaml +steps: +- task: MavenAuthenticate@0 + displayName: 'Maven Authenticate' + inputs: + MavenServiceConnections: + +- script: | + mvn install + displayName: 'Restore' +``` + +#### [Classic](#tab/classic/) + +::: moniker range="azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +::: moniker-end + +::: moniker range="< azure-devops" + +1. Sign in to your Azure DevOps collection, and then navigate to your project. + +::: moniker-end + +::: moniker range="<=azure-devops" + +2. Select **Pipelines**, and then select your pipeline definition. + +::: moniker-end + +3. Select **Edit**, and then select the `+` sign to add a new task. Add the *Maven Authenticate* and *Command line* tasks to your pipeline definition and configure them as follows: + + 1. **Maven Authenticate**: Select your service connection from the **Credentials for repositories outside this organization/collection** dropdown menu. + + 1. **Command line task**: + - **Display name**: Restore. + - **Script**: + ``` + mvn install + ``` + +4. Select **Save & queue** when you're done. + +--- + +## Related content + +- [Publish Maven packages with Azure Pipelines](../artifacts/publish-maven-artifacts.md) +- [Use the .artifactignore file](../../artifacts/reference/artifactignore.md) +- [Publish and download pipeline artifacts](../artifacts/pipeline-artifacts.md) \ No newline at end of file diff --git a/docs/pipelines/packages/media/create-new-pat-updated.png b/docs/pipelines/packages/media/create-new-pat-updated.png new file mode 100644 index 00000000000..96a5af631d4 Binary files /dev/null and b/docs/pipelines/packages/media/create-new-pat-updated.png differ diff --git a/docs/pipelines/packages/media/jenkins-add-credentials.png b/docs/pipelines/packages/media/jenkins-add-credentials.png index fa75da5a24e..ddc0c42d3bd 100644 Binary files a/docs/pipelines/packages/media/jenkins-add-credentials.png and b/docs/pipelines/packages/media/jenkins-add-credentials.png differ diff --git a/docs/pipelines/packages/media/jenkins_build_environment.png b/docs/pipelines/packages/media/jenkins_build_environment.png index 3dc03a36f11..99d61bdac71 100644 Binary files a/docs/pipelines/packages/media/jenkins_build_environment.png and b/docs/pipelines/packages/media/jenkins_build_environment.png differ diff --git a/docs/pipelines/packages/media/new-service-connection-nuget-restore.png b/docs/pipelines/packages/media/new-service-connection-nuget-restore.png new file mode 100644 index 00000000000..266abe087b1 Binary files /dev/null and b/docs/pipelines/packages/media/new-service-connection-nuget-restore.png differ diff --git a/docs/pipelines/packages/nuget-restore.md b/docs/pipelines/packages/nuget-restore.md index 9dd9294e967..3b62c8a684d 100644 --- a/docs/pipelines/packages/nuget-restore.md +++ b/docs/pipelines/packages/nuget-restore.md @@ -1,94 +1,79 @@ --- -title: Restore NuGet packages in Azure Pipelines -description: How to restore your NuGet packages +title: Restore NuGet packages with Azure Pipelines +description: Learn how to restore your NuGet packages with Classic and YAML Pipelines. ms.assetid: C3D7008E-7C23-49A4-9642-E5906DAE3BAD ms.author: rabououn ms.reviewer: rabououn author: ramiMSFT -ms.custom: "seodec18, contperf-fy21q1" -ms.topic: conceptual -ms.date: 10/10/2022 +ms.topic: how-to +ms.date: 11/12/2024 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Restore NuGet packages with Azure Pipelines +# Restore NuGet packages with Azure Pipelines (YAML/Classic) [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -With NuGet Package Restore you can install all your project's dependency without having to store them in source control. This allows for a cleaner development environment and a smaller repository size. You can restore your NuGet packages using the NuGet restore task, the NuGet CLI, or the .NET Core CLI. This article will show you how to restore your NuGet packages using both Classic and YAML Pipelines. +With NuGet Package Restore you can install all your project's dependency without needing to store them in source control. This allows for a cleaner development environment and a smaller repository size. You can restore your NuGet packages using the NuGet restore task, the NuGet CLI, or the .NET Core CLI. This article will guide you through restoring your NuGet packages using both Classic and YAML Pipelines. -### Prerequisites +## Prerequisites -- An Azure DevOps organization. [Create an organization](../../organizations/accounts/create-organization.md), if you don't have one already. -- An Azure DevOps project. If you don't have one yet, you can [create a new project](../../organizations/projects/create-project.md). -- An Azure Artifacts feed. [Create a new feed](../../artifacts/get-started-nuget.md#create-a-feed) if you don't have one already. -- Connect to Azure Artifacts feed: [NuGet.exe](../../artifacts/nuget/nuget-exe.md), [dotnet](../../artifacts/nuget/dotnet-setup.md). -- [Set up your pipeline permissions](../../artifacts/feeds/feed-permissions.md#pipelines-permissions). +- Create an Azure DevOps [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. -## Restore NuGet packages from a feed +- Create a [new feed](../../artifacts/get-started-nuget.md#create-feed) if you don't have one already. -### [Classic](#tab/classic/) +- If you're using a self-hosted agent, make sure that it has the [.NET Core SDK (2.1.400+)](https://dotnet.microsoft.com/en-us/download) and [NuGet (4.8.0.5385+)](https://www.nuget.org/downloads) installed. -1. Navigate to your classic pipeline definition, and then select **Edit**. +> [!NOTE] +> If you're using Ubuntu 24.04 or higher, you must use the `NuGetAuthenticate` task with the .NET CLI instead of the *nuget.exe*. See [Support for newer Ubuntu hosted images](/azure/devops/pipelines/tasks/reference/nuget-command-v2#support-for-newer-ubuntu-hosted-images) for more details. -1. Select **+** to add a new task. Search for **NuGet**, and then select **Add** to add the task to your pipeline. +## Restore NuGet packages from a feed in the same organization -1. Name your task and select **Restore** from the **Command**. +### [YAML](#tab/yaml/) -1. Select **Feed(s) I select here**, and select your feed from the dropdown menu. If you want to use your own config file, select **Feeds in my NuGet.config** and enter the path to your NuGet.config file and the service connection if you want to authenticate with feeds outside your organization. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. If you want to include packages from NuGet.org, check the **Use packages from NuGet.org** checkbox. +1. Select **Pipelines**, and then select your pipeline definition. -1. Select **Save & queue** when you're done. +1. Select **Edit**, and then add the following snippet to your YAML pipeline. - :::image type="content" source="media/nuget-restore-classic.png" alt-text="Screenshot that shows how to configure the NuGet restore task."::: + ```yaml + steps: + - task: NuGetAuthenticate@1 + + - task: NuGetToolInstaller@1 + inputs: + versionSpec: '*' + checkLatest: true + + - script: nuget restore + ``` -> [!NOTE] -> Classic NuGet restore uses the [NuGetCommand@2](/azure/devops/pipelines/tasks/reference/nuget-command-v2) task. By default, this version uses NuGet 4.1.0. Use the [NuGet Tool Installer task](/azure/devops/pipelines/tasks/reference/nuget-tool-installer-v1) if you want to use a different NuGet version. - -### [YAML](#tab/yaml/) +### [Classic](#tab/classic/) -```YAML -- task: NuGetCommand@2 - displayName: NuGet v2 Restore - inputs: - command: restore - restoreSolution: '**/*.sln' ## Required when command = restore. Path to solution, packages.config, or project.json. Default: **/*.sln. - feedsToUse: 'select' ## Required. Feeds to use. 'select' | 'config'. Alias: selectOrConfig. Default: select. - vstsFeed: '/' ## Required when feedsToUse == Select. Use packages from this Azure Artifacts feed. - includeNuGetOrg: true ## Use packages from upstream (NuGet.org) -``` +1. Sign in to your Azure DevOps organization, and then navigate to your project. -* * * +1. Select **Pipelines**, select your pipeline definition, and then select **Edit**. -## Restore NuGet packages locally +1. Select **+** to add a new task. Add the *NuGet tool installer*, *NuGet Authenticate*, and *Command line* tasks to your pipeline. Leave the *NuGet tool installer* and *NuGet Authenticate* tasks with their default settings and configure the *Command line* task as follows: -Place your `nuget.config` in the same folder as your `.csproj` or `.sln`file. Your config file should look similar to the following example: + - **Display name**: Restore. + - **Script**: + ``` + nuget.exe restore + ``` -```xml - - - - - - - - - - - -``` +1. Select **Save & queue** when you're done. -To restore your NuGet packages, run the following command in your project directory: +* * * -```Command -nuget.exe restore -``` +> [!NOTE] +> Make sure that The NuGet Gallery upstream is enabled in your feed. See [Enable upstream sources in an existing feed](../../artifacts/how-to/set-up-upstream-sources.md#enable-upstream-sources-in-an-existing-feed) for details. -## Restore NuGet packages from a feed in a different organization +## Restore NuGet packages from a feed in another organization -To restore NuGet packages from a feed in a different Azure DevOps organization, you must use a personal access token to authenticate. +To restore NuGet packages from a feed in a different Azure DevOps organization, you must first create a personal access token then use it to set up a NuGet service connection. #### Create a personal access token @@ -96,64 +81,75 @@ To restore NuGet packages from a feed in a different Azure DevOps organization, :::image type="content" source="media/pat.png" alt-text="Screenshot showing how to create a personal access token."::: -1. Create a personal access token with **Packaging (read)** scope and copy your PAT to the clipboard. +1. Create a new personal access token with **Packaging*** > **Read** scope. Copy your PAT as you'll need it in the following section. - :::image type="content" source="media/create-read-feed-pat.png" alt-text="A screenshot showing how to create a personal access token with packaging read permissions."::: +1. Select **Create** when you're done. -#### Restore NuGet packages + :::image type="content" source="media/create-new-pat-updated.png" alt-text="A screenshot showing how to create a personal access token with packaging read permissions."::: -### [Classic](#tab/classic/) +#### Create a service connection -1. Navigate to your pipeline definition and select the **NuGet restore** task. Make sure you're using version 2 of the task. +1. Sign in to the Azure DevOps organization where your pipeline will run, and then navigate to your project. - :::image type="content" source="media/nuget-v-2.png" alt-text="Screenshot showing the NuGet restore task version."::: +1. Navigate to your **Project settings** > **Service connections**. -1. Select **Feeds and authentication**, and then select **Feeds in my NuGet.config**. -1. Select the path of your *NuGet.config* file. -1. Select **New** to add **Credentials for feeds outside this organization/collection**. +1. Select **New service connection**, select **NuGet**, and then select **Next**. - :::image type="content" source="media/feeds-and-authentication.png" alt-text="Screenshot showing how to configure the NuGet restore task."::: +1. Select **External Azure DevOps Server** as the **Authentication method**, and then enter your target **Feed URL**. Paste the **Personal Access Token** you created earlier, provide a name for your service connection, and check **Grant access permission to all pipelines** if applicable to your scenario. -1. Select **External Azure DevOps Server**, and then enter your feed URL (make sure it matches what's in your NuGet.config), your service connection name, and the personal access token you created earlier. Select **Save** when you're done. +1. Select **Save** when you're done. - :::image type="content" source="media/external-server-service-connection.png" alt-text="Screenshot showing how to add a new service connection."::: + :::image type="content" source="media/new-service-connection-nuget-restore.png" alt-text="A screenshot showing how to create a new NuGet service connection."::: -1. Select **Save & queue** when you're done. +#### Restore packages ### [YAML](#tab/yaml/) -```yml -- task: NuGetCommand@2 - displayName: NuGet Restore - inputs: - restoreSolution: '**/*.sln' ## Required when command = restore. Path to your project's solution, packages.config, or project.json. - feedsToUse: 'config' ## Required. 'select' | 'config'. Default: select. - nugetConfigPath: 'Deployment/NuGet.config' ## Required when selectOrConfig = config. Path to your nuget.config file. - externalFeedCredentials: 'MyServiceConnection' ## Use when selectOrConfig = config. The name of your service connection. Credentials for feeds outside your organization/collection. -``` +1. Sign in to your Azure DevOps organization, and then navigate to your project. -* * * +1. Select **Pipelines**, and then select your pipeline definition. -## FAQ +1. Select **Edit**, and then add the following snippet to your YAML pipeline. -### Q: My pipeline is failing to restore my NuGet packages? + ```yaml + - task: NuGetToolInstaller@1 + inputs: + versionSpec: '*' + checkLatest: true + + - task: NuGetAuthenticate@1 + inputs: + nuGetServiceConnections: + + - script: | + nuget.exe restore + displayName: Restore + ``` -A: The NuGet restore task can fail for several reasons. The most common scenario is when you add a new project that requires a [target framework](/nuget/schema/target-frameworks) that is not supported by the NuGet version your pipeline is using. This failure doesn't occur generally in the local development environment because Visual Studio takes care of updating your solution accordingly. Make sure you upgrade your NuGet task to the latest version. +### [Classic](#tab/classic/) -::: moniker range="tfs-2018" +1. Sign in to your Azure DevOps organization, and then navigate to your project. -### Q: How do I use the latest version of NuGet? +1. Select **Pipelines**, select your pipeline definition, and then select **Edit**. -A: For new pipelines, the **NuGet Tool Installer** will be added automatically to any pipeline that uses a NuGet task. We periodically update the NuGet default version around the same time we install Visual Studio updates on the Hosted build agents. +1. Select **+** to add a new task. Add the *NuGet tool installer*, *NuGet Authenticate*, and *Command line* tasks to your pipeline. Leave the *NuGet tool installer* with its default settings and configure the other tasks as follows: -For existing pipelines, add the **NuGet Tool Installer** to your pipeline and select the NuGet version for all the subsequent tasks. Check out the [dist.nuget](https://dist.nuget.org/tools.json) to see all the available versions. + 1. NuGet Authenticate task: + Select your service connection from the **Service connection credentials for feeds outside this organization** dropdown menu. + + 1. Command line task: + - **Display name**: Restore. + - **Script**: + ``` + nuget.exe restore + ``` -:::image type="content" source="media/nuget-tool-installer.png" alt-text="Screenshot showing the NuGet tool installer task."::: +1. Select **Save & queue** when you're done. -::: moniker-end +* * * -## Related articles +## Related content -- [Publish to NuGet feeds (YAML/Classic)](../artifacts/nuget.md) -- [Publish and consume build artifacts](../artifacts/build-artifacts.md) -- [How to mitigate risk when using private package feeds](https://azure.microsoft.com/resources/3-ways-to-mitigate-risk-using-private-package-feeds/) +- [Publish packages to internal and external feeds](../artifacts/pipeline-artifacts.md) +- [Publish and download pipeline artifacts](../artifacts/build-artifacts.md) +- [Use the .artifactignore file](../../artifacts/reference/artifactignore.md) diff --git a/docs/pipelines/policies/media/agent-pool-add-pipeline.png b/docs/pipelines/policies/media/agent-pool-add-pipeline.png new file mode 100644 index 00000000000..1ec447b6bc4 Binary files /dev/null and b/docs/pipelines/policies/media/agent-pool-add-pipeline.png differ diff --git a/docs/pipelines/policies/media/agent-pool-add-user.png b/docs/pipelines/policies/media/agent-pool-add-user.png new file mode 100644 index 00000000000..78a8facec92 Binary files /dev/null and b/docs/pipelines/policies/media/agent-pool-add-user.png differ diff --git a/docs/pipelines/policies/media/agent-pool-individual-pool-user-permissions.png b/docs/pipelines/policies/media/agent-pool-individual-pool-user-permissions.png new file mode 100644 index 00000000000..da8c32f85f6 Binary files /dev/null and b/docs/pipelines/policies/media/agent-pool-individual-pool-user-permissions.png differ diff --git a/docs/pipelines/policies/media/agent-pool-open-access.png b/docs/pipelines/policies/media/agent-pool-open-access.png new file mode 100644 index 00000000000..34fb9ab2386 Binary files /dev/null and b/docs/pipelines/policies/media/agent-pool-open-access.png differ diff --git a/docs/pipelines/policies/media/agent-pool-organization-security-dialog.png b/docs/pipelines/policies/media/agent-pool-organization-security-dialog.png new file mode 100644 index 00000000000..b852362e041 Binary files /dev/null and b/docs/pipelines/policies/media/agent-pool-organization-security-dialog.png differ diff --git a/docs/pipelines/policies/media/agent-pool-project-level-permissions.png b/docs/pipelines/policies/media/agent-pool-project-level-permissions.png new file mode 100644 index 00000000000..3c35a8a1ea4 Binary files /dev/null and b/docs/pipelines/policies/media/agent-pool-project-level-permissions.png differ diff --git a/docs/pipelines/policies/media/agent-pool-restrict-permissions.png b/docs/pipelines/policies/media/agent-pool-restrict-permissions.png new file mode 100644 index 00000000000..afc817cd39a Binary files /dev/null and b/docs/pipelines/policies/media/agent-pool-restrict-permissions.png differ diff --git a/docs/pipelines/policies/media/agent-pools-collection-level-security-dialog.png b/docs/pipelines/policies/media/agent-pools-collection-level-security-dialog.png new file mode 100644 index 00000000000..2cbcdfd9ffb Binary files /dev/null and b/docs/pipelines/policies/media/agent-pools-collection-level-security-dialog.png differ diff --git a/docs/pipelines/policies/media/agent-pools-individual-pool-security.png b/docs/pipelines/policies/media/agent-pools-individual-pool-security.png new file mode 100644 index 00000000000..4d15f48e85b Binary files /dev/null and b/docs/pipelines/policies/media/agent-pools-individual-pool-security.png differ diff --git a/docs/pipelines/policies/media/agent-pools-organization-level-security-for-individual-pool.png b/docs/pipelines/policies/media/agent-pools-organization-level-security-for-individual-pool.png new file mode 100644 index 00000000000..9e88caa5e37 Binary files /dev/null and b/docs/pipelines/policies/media/agent-pools-organization-level-security-for-individual-pool.png differ diff --git a/docs/pipelines/policies/media/agent-pools-organization-security-selection.png b/docs/pipelines/policies/media/agent-pools-organization-security-selection.png new file mode 100644 index 00000000000..a402e1d98bc Binary files /dev/null and b/docs/pipelines/policies/media/agent-pools-organization-security-selection.png differ diff --git a/docs/pipelines/policies/media/all-pipelines-security-selection-2019.png b/docs/pipelines/policies/media/all-pipelines-security-selection-2019.png new file mode 100644 index 00000000000..0e581749862 Binary files /dev/null and b/docs/pipelines/policies/media/all-pipelines-security-selection-2019.png differ diff --git a/docs/pipelines/policies/media/builds-permissions-dialog-box-server.png b/docs/pipelines/policies/media/builds-permissions-dialog-box-server.png new file mode 100644 index 00000000000..6295551e6af Binary files /dev/null and b/docs/pipelines/policies/media/builds-permissions-dialog-box-server.png differ diff --git a/docs/pipelines/policies/media/builds-permissions-dialog-box.png b/docs/pipelines/policies/media/builds-permissions-dialog-box.png index 55797ec0ce6..d6514fedf7a 100644 Binary files a/docs/pipelines/policies/media/builds-permissions-dialog-box.png and b/docs/pipelines/policies/media/builds-permissions-dialog-box.png differ diff --git a/docs/pipelines/policies/media/delete-user-in-security-dialog.png b/docs/pipelines/policies/media/delete-user-in-security-dialog.png new file mode 100644 index 00000000000..bb42d6726ab Binary files /dev/null and b/docs/pipelines/policies/media/delete-user-in-security-dialog.png differ diff --git a/docs/pipelines/policies/media/deployment-group-project-level-security-dialog.png b/docs/pipelines/policies/media/deployment-group-project-level-security-dialog.png new file mode 100644 index 00000000000..21482847422 Binary files /dev/null and b/docs/pipelines/policies/media/deployment-group-project-level-security-dialog.png differ diff --git a/docs/pipelines/policies/media/deployment-group-security-selection.png b/docs/pipelines/policies/media/deployment-group-security-selection.png new file mode 100644 index 00000000000..9bf5af2c834 Binary files /dev/null and b/docs/pipelines/policies/media/deployment-group-security-selection.png differ diff --git a/docs/pipelines/policies/media/deployment-group-single-group-security-selection.png b/docs/pipelines/policies/media/deployment-group-single-group-security-selection.png new file mode 100644 index 00000000000..f54801d35b2 Binary files /dev/null and b/docs/pipelines/policies/media/deployment-group-single-group-security-selection.png differ diff --git a/docs/pipelines/policies/media/deployment-groups-single-group-security-dialog.png b/docs/pipelines/policies/media/deployment-groups-single-group-security-dialog.png new file mode 100644 index 00000000000..c64497ea58e Binary files /dev/null and b/docs/pipelines/policies/media/deployment-groups-single-group-security-dialog.png differ diff --git a/docs/pipelines/policies/media/environments-open-access-selection.png b/docs/pipelines/policies/media/environments-open-access-selection.png new file mode 100644 index 00000000000..3d506d52cf9 Binary files /dev/null and b/docs/pipelines/policies/media/environments-open-access-selection.png differ diff --git a/docs/pipelines/policies/media/environments-project-security-dialog.png b/docs/pipelines/policies/media/environments-project-security-dialog.png new file mode 100644 index 00000000000..38db7d6635e Binary files /dev/null and b/docs/pipelines/policies/media/environments-project-security-dialog.png differ diff --git a/docs/pipelines/policies/media/environments-project-security-selection.png b/docs/pipelines/policies/media/environments-project-security-selection.png new file mode 100644 index 00000000000..61fe90d6140 Binary files /dev/null and b/docs/pipelines/policies/media/environments-project-security-selection.png differ diff --git a/docs/pipelines/policies/media/environments-revoke-pipeline-permission.png b/docs/pipelines/policies/media/environments-revoke-pipeline-permission.png new file mode 100644 index 00000000000..628e95e5a22 Binary files /dev/null and b/docs/pipelines/policies/media/environments-revoke-pipeline-permission.png differ diff --git a/docs/pipelines/policies/media/environments-single-environment-security-selection.png b/docs/pipelines/policies/media/environments-single-environment-security-selection.png new file mode 100644 index 00000000000..036f225ea0c Binary files /dev/null and b/docs/pipelines/policies/media/environments-single-environment-security-selection.png differ diff --git a/docs/pipelines/policies/media/environments-single-environment-user-permissions.png b/docs/pipelines/policies/media/environments-single-environment-user-permissions.png new file mode 100644 index 00000000000..e2c1c97402a Binary files /dev/null and b/docs/pipelines/policies/media/environments-single-environment-user-permissions.png differ diff --git a/docs/pipelines/policies/media/folder-icon.png b/docs/pipelines/policies/media/folder-icon.png new file mode 100644 index 00000000000..550e719fd31 Binary files /dev/null and b/docs/pipelines/policies/media/folder-icon.png differ diff --git a/docs/pipelines/policies/media/individual-pipeline-permissions-dialog-2019.png b/docs/pipelines/policies/media/individual-pipeline-permissions-dialog-2019.png new file mode 100644 index 00000000000..88beee20130 Binary files /dev/null and b/docs/pipelines/policies/media/individual-pipeline-permissions-dialog-2019.png differ diff --git a/docs/pipelines/policies/media/individual-pipeline-permissions-dialog-2020.png b/docs/pipelines/policies/media/individual-pipeline-permissions-dialog-2020.png new file mode 100644 index 00000000000..f51747e7a49 Binary files /dev/null and b/docs/pipelines/policies/media/individual-pipeline-permissions-dialog-2020.png differ diff --git a/docs/pipelines/policies/media/individual-pipeline-security-dialog.png b/docs/pipelines/policies/media/individual-pipeline-security-dialog.png new file mode 100644 index 00000000000..0887654ca3b Binary files /dev/null and b/docs/pipelines/policies/media/individual-pipeline-security-dialog.png differ diff --git a/docs/pipelines/policies/media/individual-pipeline-security-navigation-2019.png b/docs/pipelines/policies/media/individual-pipeline-security-navigation-2019.png new file mode 100644 index 00000000000..376e9e102a1 Binary files /dev/null and b/docs/pipelines/policies/media/individual-pipeline-security-navigation-2019.png differ diff --git a/docs/pipelines/policies/media/individual-service-connection-permission-user-dialog.png b/docs/pipelines/policies/media/individual-service-connection-permission-user-dialog.png new file mode 100644 index 00000000000..b84bb5dbf26 Binary files /dev/null and b/docs/pipelines/policies/media/individual-service-connection-permission-user-dialog.png differ diff --git a/docs/pipelines/policies/media/library-file-permissions-dialog.png b/docs/pipelines/policies/media/library-file-permissions-dialog.png new file mode 100644 index 00000000000..18486aaa61e Binary files /dev/null and b/docs/pipelines/policies/media/library-file-permissions-dialog.png differ diff --git a/docs/pipelines/policies/media/library-project-level-permissions-dialog.png b/docs/pipelines/policies/media/library-project-level-permissions-dialog.png new file mode 100644 index 00000000000..faa40b8efec Binary files /dev/null and b/docs/pipelines/policies/media/library-project-level-permissions-dialog.png differ diff --git a/docs/pipelines/policies/media/library-variable-group-permissions.png b/docs/pipelines/policies/media/library-variable-group-permissions.png new file mode 100644 index 00000000000..16e73616483 Binary files /dev/null and b/docs/pipelines/policies/media/library-variable-group-permissions.png differ diff --git a/docs/pipelines/policies/media/manage-security-all-pipelines.png b/docs/pipelines/policies/media/manage-security-all-pipelines.png index 9d54716c108..a81aebccc69 100644 Binary files a/docs/pipelines/policies/media/manage-security-all-pipelines.png and b/docs/pipelines/policies/media/manage-security-all-pipelines.png differ diff --git a/docs/pipelines/policies/media/pipeline-security-add-user-2019.png b/docs/pipelines/policies/media/pipeline-security-add-user-2019.png new file mode 100644 index 00000000000..afcb985b2ad Binary files /dev/null and b/docs/pipelines/policies/media/pipeline-security-add-user-2019.png differ diff --git a/docs/pipelines/policies/media/pipeline-security-add-user-2020.png b/docs/pipelines/policies/media/pipeline-security-add-user-2020.png new file mode 100644 index 00000000000..4285fe5f652 Binary files /dev/null and b/docs/pipelines/policies/media/pipeline-security-add-user-2020.png differ diff --git a/docs/pipelines/policies/media/pipelines-navigation-from-project.png b/docs/pipelines/policies/media/pipelines-navigation-from-project.png index 4625e30a002..f1310370a26 100644 Binary files a/docs/pipelines/policies/media/pipelines-navigation-from-project.png and b/docs/pipelines/policies/media/pipelines-navigation-from-project.png differ diff --git a/docs/pipelines/policies/media/pipelines-project-level-permissions-2020.png b/docs/pipelines/policies/media/pipelines-project-level-permissions-2020.png new file mode 100644 index 00000000000..357c7275d6b Binary files /dev/null and b/docs/pipelines/policies/media/pipelines-project-level-permissions-2020.png differ diff --git a/docs/pipelines/policies/media/pipelines-project-level-security-dialog-2022.png b/docs/pipelines/policies/media/pipelines-project-level-security-dialog-2022.png new file mode 100644 index 00000000000..b1e8a2d983b Binary files /dev/null and b/docs/pipelines/policies/media/pipelines-project-level-security-dialog-2022.png differ diff --git a/docs/pipelines/policies/media/pipelines-project-level-security-dialog.png b/docs/pipelines/policies/media/pipelines-project-level-security-dialog.png new file mode 100644 index 00000000000..ac47be33e4b Binary files /dev/null and b/docs/pipelines/policies/media/pipelines-project-level-security-dialog.png differ diff --git a/docs/pipelines/policies/media/release-select-pipeline-for-stage-permissions.png b/docs/pipelines/policies/media/release-select-pipeline-for-stage-permissions.png new file mode 100644 index 00000000000..3db00c60cef Binary files /dev/null and b/docs/pipelines/policies/media/release-select-pipeline-for-stage-permissions.png differ diff --git a/docs/pipelines/policies/media/releases-all-pipelines-permissions-2019.png b/docs/pipelines/policies/media/releases-all-pipelines-permissions-2019.png new file mode 100644 index 00000000000..e0db7ecea68 Binary files /dev/null and b/docs/pipelines/policies/media/releases-all-pipelines-permissions-2019.png differ diff --git a/docs/pipelines/policies/media/releases-all-pipelines-permissions.png b/docs/pipelines/policies/media/releases-all-pipelines-permissions.png new file mode 100644 index 00000000000..77ba5f1db80 Binary files /dev/null and b/docs/pipelines/policies/media/releases-all-pipelines-permissions.png differ diff --git a/docs/pipelines/policies/media/releases-individual-pipeline-permissions-2019.png b/docs/pipelines/policies/media/releases-individual-pipeline-permissions-2019.png new file mode 100644 index 00000000000..838137f043e Binary files /dev/null and b/docs/pipelines/policies/media/releases-individual-pipeline-permissions-2019.png differ diff --git a/docs/pipelines/policies/media/releases-individual-pipeline-permissions.png b/docs/pipelines/policies/media/releases-individual-pipeline-permissions.png new file mode 100644 index 00000000000..3414a525d25 Binary files /dev/null and b/docs/pipelines/policies/media/releases-individual-pipeline-permissions.png differ diff --git a/docs/pipelines/policies/media/releases-select-all-pipelines-security.png b/docs/pipelines/policies/media/releases-select-all-pipelines-security.png new file mode 100644 index 00000000000..94b1cabcd93 Binary files /dev/null and b/docs/pipelines/policies/media/releases-select-all-pipelines-security.png differ diff --git a/docs/pipelines/policies/media/releases-select-pipeline-security.png b/docs/pipelines/policies/media/releases-select-pipeline-security.png new file mode 100644 index 00000000000..93b7eeba6f4 Binary files /dev/null and b/docs/pipelines/policies/media/releases-select-pipeline-security.png differ diff --git a/docs/pipelines/policies/media/releases-select-stage-security.png b/docs/pipelines/policies/media/releases-select-stage-security.png new file mode 100644 index 00000000000..ac628e3cb0c Binary files /dev/null and b/docs/pipelines/policies/media/releases-select-stage-security.png differ diff --git a/docs/pipelines/policies/media/releases-stage-permissions.png b/docs/pipelines/policies/media/releases-stage-permissions.png new file mode 100644 index 00000000000..c9ed8b47a0c Binary files /dev/null and b/docs/pipelines/policies/media/releases-stage-permissions.png differ diff --git a/docs/pipelines/policies/media/reset-icon.png b/docs/pipelines/policies/media/reset-icon.png new file mode 100644 index 00000000000..32a68ad634e Binary files /dev/null and b/docs/pipelines/policies/media/reset-icon.png differ diff --git a/docs/pipelines/policies/media/save-icon.png b/docs/pipelines/policies/media/save-icon.png new file mode 100644 index 00000000000..51852e895ae Binary files /dev/null and b/docs/pipelines/policies/media/save-icon.png differ diff --git a/docs/pipelines/policies/media/service-connection-open-access.png b/docs/pipelines/policies/media/service-connection-open-access.png new file mode 100644 index 00000000000..ab9e6ddfe1a Binary files /dev/null and b/docs/pipelines/policies/media/service-connection-open-access.png differ diff --git a/docs/pipelines/policies/media/service-connection-project-level-permissions-dialog.png b/docs/pipelines/policies/media/service-connection-project-level-permissions-dialog.png new file mode 100644 index 00000000000..be1498c8f0b Binary files /dev/null and b/docs/pipelines/policies/media/service-connection-project-level-permissions-dialog.png differ diff --git a/docs/pipelines/policies/media/service-connection-project-permissions.png b/docs/pipelines/policies/media/service-connection-project-permissions.png new file mode 100644 index 00000000000..9e2c1583e65 Binary files /dev/null and b/docs/pipelines/policies/media/service-connection-project-permissions.png differ diff --git a/docs/pipelines/policies/media/service-connection-restrict-access.png b/docs/pipelines/policies/media/service-connection-restrict-access.png new file mode 100644 index 00000000000..4590675f4d0 Binary files /dev/null and b/docs/pipelines/policies/media/service-connection-restrict-access.png differ diff --git a/docs/pipelines/policies/media/service-connection-roles-dialog-2019.png b/docs/pipelines/policies/media/service-connection-roles-dialog-2019.png new file mode 100644 index 00000000000..7de6cd15492 Binary files /dev/null and b/docs/pipelines/policies/media/service-connection-roles-dialog-2019.png differ diff --git a/docs/pipelines/policies/media/service-connections-security-selection.png b/docs/pipelines/policies/media/service-connections-security-selection.png new file mode 100644 index 00000000000..684bb50879e Binary files /dev/null and b/docs/pipelines/policies/media/service-connections-security-selection.png differ diff --git a/docs/pipelines/policies/media/task-group-individual-permission.png b/docs/pipelines/policies/media/task-group-individual-permission.png new file mode 100644 index 00000000000..1f3c6c3f32e Binary files /dev/null and b/docs/pipelines/policies/media/task-group-individual-permission.png differ diff --git a/docs/pipelines/policies/media/task-group-individual-permissions-2019.png b/docs/pipelines/policies/media/task-group-individual-permissions-2019.png new file mode 100644 index 00000000000..c34880365b1 Binary files /dev/null and b/docs/pipelines/policies/media/task-group-individual-permissions-2019.png differ diff --git a/docs/pipelines/policies/media/task-group-menu-item-2019.png b/docs/pipelines/policies/media/task-group-menu-item-2019.png new file mode 100644 index 00000000000..54ea24af87e Binary files /dev/null and b/docs/pipelines/policies/media/task-group-menu-item-2019.png differ diff --git a/docs/pipelines/policies/media/task-group-project-level-permissions-2019.png b/docs/pipelines/policies/media/task-group-project-level-permissions-2019.png new file mode 100644 index 00000000000..80205e8badb Binary files /dev/null and b/docs/pipelines/policies/media/task-group-project-level-permissions-2019.png differ diff --git a/docs/pipelines/policies/media/task-groups-project-level-permissions.png b/docs/pipelines/policies/media/task-groups-project-level-permissions.png new file mode 100644 index 00000000000..8807436c30c Binary files /dev/null and b/docs/pipelines/policies/media/task-groups-project-level-permissions.png differ diff --git a/docs/pipelines/policies/permissions.md b/docs/pipelines/policies/permissions.md index 4331099454b..7259fe1b7d0 100644 --- a/docs/pipelines/policies/permissions.md +++ b/docs/pipelines/policies/permissions.md @@ -1,436 +1,1284 @@ --- -title: Set pipeline permissions -ms.topic: conceptual -ms.custom: seodec18, contperf-fy21q3 -description: Understand how you can set permissions at varying levels to securely manage Azure Pipelines. +title: Manage security in Azure Pipelines +ms.topic: how-to +description: Manage security in Azure Pipelines. ms.assetid: A7C38A15-C9FE-4353-8680-21BAC0F6C873 -ms.author: jukullam -author: juliakm -ms.date: 01/04/2023 +ms.author: chcomley +author: chcomley +ms.date: 11/12/2024 monikerRange: '<= azure-devops' --- -# Set pipeline permissions +# Manage security in Azure Pipelines [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -[!INCLUDE [temp](../includes/concept-rename-note.md)] +Azure Pipelines security controls access to pipelines and their resources through a hierarchy of security groups and users. This system governs resources like release pipelines, task groups, agent pools, and service connections, though external to pipelines. Upon creation, pipelines and resources inherit project-level permissions from predefined security groups and users, affecting all project pipelines. + +Administrators typically have unrestricted access, contributors oversee resources, and readers have view-only permissions, with user roles determining group assignments. For more information, see [About pipeline security roles](../../organizations/security/about-security-roles.md). + +## Prerequisites + +|Security area|Prerequisites | +|---------|---------| +|[Pipelines security](#set-pipeline-permissions-in-azure-pipelines) | - To manage project collection groups, be a member of the **Project Collection Administrators** group.
      - To manage project level users and groups, be a member of an administrator group or have *Administer build permissions*. | +| [Agent pool security](#set-agent-pool-security-in-azure-pipelines) | - To manage agent pool security at the organization, collection, or project level, be a member of the **Project Collection Administrators** group or have the **Administrator** role for agent pools.
      - To manage agent pool security at the object level, have the **Administrator** role for the agent pool. | +|[Deployment group security](#set-deployment-group-security-in-azure-pipelines) | - To manage project-level deployment group security, be a member of an administrator group or be assigned an administrator role.
      - To manage security for individual deployment groups, have an administrator role. | +|[Environment security](#set-security-for-environments-in-azure-pipelines) | - To manage project-level environment security, be a member of an administrator group or assigned an administrator role.
      - To manage object-level security for individual environments, have an administrator role. | +|[Library security](#set-library-security-in-azure-pipelines) | - To manage library security, be a member of an administrator group or assigned an administrator role.
      - To manage security for individual library assets, e an administrator or have the appropriate role. | +|[Release pipeline security](#set-release-pipeline-permissions-in-azure-pipelines) | - To manage release pipeline security, be a member of an administrator group or have *Administer release permissions*.
      - Have a release pipeline. | +|[Service connection security](#set-service-connection-security-in-azure-pipelines) | - To manage service connection security, be a member of the **Project Administrators** group or have an administrator role. - To manage security at the project level, be a member of the **Project Administrators** group or have the **Administrator** role for service connections.
      - To manage security at the object level, have the **Administrator** role for the service connection. | +|[Task group security](#set-task-group-permissions-in-azure-pipelines) | To manage task group security, be a member of an administrator group or have *Administer task group permissions*.
      - Have a task group. | + +       + +## Set pipeline permissions in Azure Pipelines + +Pipeline security follows a hierarchical model of user and group permissions. Project-level permissions are inherited at the object level by all pipelines in the project. You can change inherited and default user and group permissions for all pipelines at the project- and object-levels. You can't change the permissions set by the system. + +The following table shows the default security groups for pipelines: + +| Group | Description | +|-------|-------------| +| Build Administrators | Administer build permissions and manage pipelines and builds. | +| Contributors | Manage pipelines and builds, but not build queues. This group includes all team members.| +| **Project Administrators** | Administer build permissions and manage pipelines and builds. | +| Readers | View pipeline and builds. | +| Project Collection Administrators | Administer build permissions and manage pipelines and builds. | +| Project Collection Build Administrators | Administer build permissions and manage pipelines and builds. | +| Project Collection Build Service Accounts | Manage builds. | +| Project Collection Test Service Accounts | View pipelines and builds. | + +The system automatically creates the *\ Build Service (collection name)* user, a member of the *Project Collection Build Service Accounts* group. This user executes build services within the project. + +Depending on the resources you use in your pipelines, your pipeline could include other built-in users. For instance, if you're using a GitHub repository for your source code, a GitHub user is included. + +The following table shows default permissions for security groups: +[!INCLUDE [temp](../../organizations/security/includes/pipelines-build.md)] + +For a description of pipeline permissions, see [Pipeline or Build permissions](../../organizations/security/permissions.md#pipeline-or-build-object-level). + +### Set project-level pipeline permissions + +::: moniker range="azure-devops-2022" + +To manage project-level permissions for users and groups across all build pipelines in your project, do the following steps: + +1. From your project, select **Pipelines**. + + :::image type="content" source="media/pipelines-navigation-from-project.png" alt-text="Screenshot showing Pipelines menu selection."::: + +1. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Manage security**. + +1. Select users or groups and set permissions to **Allow**, **Deny**, or **Not set**. + + :::image type="content" source="media/pipelines-project-level-security-dialog-2022.png" alt-text="Screenshot of project-level pipelines security dialog."::: + +1. Repeat the previous step to change the permissions for more groups and users. +1. Close permissions dialog to save the changes. -::: moniker range="azure-devops" -Pipeline permissions and roles help you securely manage your pipelines. You can set hierarchical permissions at the organization, project, and object levels for all pipelines in a project or for an individual pipeline. You can update pipeline permissions with security groups or by [adding individual users](set-permissions.md). ::: moniker-end -::: moniker range="< azure-devops" -Pipeline permissions and roles help you securely manage your pipelines. You can set hierarchical permissions at the organization, server, project, and object levels for all pipelines in a project or for an individual pipeline. You can update pipeline permissions with security groups or by [adding individual users](set-permissions.md). +::: moniker range="azure-devops" + +To manage project-level permissions for users and groups across all build pipelines in your project, do the following steps: + +1. From your project, select **Pipelines**. + + :::image type="content" source="media/pipelines-navigation-from-project.png" alt-text="Screenshot showing Pipelines menu selection."::: + +1. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Manage security**. + +1. Select users or groups and set permissions to **Allow**, **Deny**, or **Not set**. + + :::image type="content" source="media/pipelines-project-level-security-dialog.png" alt-text="Screenshot of project-level pipelines security dialog."::: + +1. Repeat the previous step to change the permissions for more groups and users. +1. Close permissions dialog to save the changes. + ::: moniker-end -Object-level permissions are more granular than organization-level permissions, so you can increase the security of your pipeline. For example, a user could have access to your Azure Repos repository thanks to their organization-level permissions. However, that same user could be prevented from running a pipeline manually because of that object/pipeline's permissions. +::: moniker range=">= azure-devops-2022" -In this article, we break down the permissions to the following levels of permissions: -- [Project-level permissions](#set-project-level-pipeline-permissions) -- Object-level permissions: - - [Release](#set-release-permissions) - - [Task group](#set-task-group-permissions) - - [Agent pool](#set-agent-pool-permissions) - - [Library](#set-library-permissions) - - [Service connection](#set-service-connection-permissions) - - [Deployment pool](#set-deployment-pool-permissions) - - [Environment](#set-environment-permissions) +#### Add users or groups to the permissions dialog + +To add users and groups that aren't listed in the permissions dialog, do the following steps: -For more information, see [Get started with permissions, access, and security groups](../../organizations/security/about-permissions.md), [Securing Azure Pipelines](../security/overview.md), and [Verify permissions for contributors](set-permissions.md#verify-permissions-for-contributors). +1. Enter the user or group in the search bar, then select the user or group from the search result. +1. Set the permissions. +1. Close the dialog. -## Prerequisites +When you open the security dialog again, the user or group is listed. -* To manage permissions and [add users to Azure Pipelines](set-permissions.md) for project-level groups, you must be a **Project Administrator**. For more information, see [Project-level group permissions](../../organizations/security/permissions.md#project-level-groups). -* To manage permissions for collection groups, you must be a **Project Collection Administrator**. For more information, see [collection-level group permissions](../../organizations/security/permissions.md#collection-level-groups). -* Keep the following information in mind when you're setting pipeline permissions. - * In many cases, you might want to set **Delete build pipeline** to _Allow_. Otherwise, these team members can't delete their own build pipelines. - * Without the **Delete builds** permission, users can't delete their own completed builds. However, they can automatically delete old unneeded builds with [retention policies](retention.md). - * We recommend that you don't grant permissions directly to a user. A better practice is to add the user to the build administrator group or another group, and manage permissions for that group. +#### Remove users or groups from the permissions dialog -For more information and best practices, see [Securing Azure Pipelines](../security/overview.md). +To delete a user from the permissions list, do the following steps: -::: moniker range="azure-devops-2019" -## Default permissions assigned to built-in security groups -### Build -[!INCLUDE [temp](../../organizations/security/includes/pipelines-build.md)] -### Release -[!INCLUDE [temp](../../organizations/security/includes/pipelines-release.md)] -### Task groups -[!INCLUDE [temp](../../organizations/security/includes/task-groups.md)] -::: moniker-end -::: moniker range="tfs-2018" -## Default permissions assigned to built-in security groups -### Build -[!INCLUDE [temp](../../organizations/security/includes/build.md)] -### Release -[!INCLUDE [temp](../../organizations/security/includes/release.md)] -::: moniker-end +1. Select the user or group. +1. Select **Remove and clear explicit permissions**. -## Set project-level pipeline permissions + :::image type="content" source="media\delete-user-in-security-dialog.png" alt-text="Screenshot of remove user or group selection."::: -::: moniker range=">=azure-devops-2020" +1. When you're done, close the dialog to save your changes. -Do the following steps to set project-level permissions for all pipelines. +::: moniker-end + +::: moniker range="azure-devops-2020" -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -2. From within your project, select **Pipelines** > **Pipelines**. +To manage project-level permissions for users and groups across all build pipelines in your project, do the following steps: + +1. From your project, select **Pipelines**. - :::image type="content" source="media/pipelines-navigation-from-project.png" alt-text="Screenshot showing ordered Pipelines menu selections."::: + :::image type="content" source="media/pipelines-navigation-from-project.png" alt-text="Screenshot showing Pipelines menu selections."::: -3. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: > **Manage security**. +1. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Manage security**. +1. To add users or groups that aren't listed in the permissions dialog, select **Add**, enter the user or group, and select **Save changes**. +1. Select a user or group and set the permissions. - :::image type="content" source="media/manage-security-all-pipelines.png" alt-text="Screenshot showing ordered selections to Manage security for all pipelines in a project. "::: + :::image type="content" source="media/pipelines-project-level-permissions-2020.png" alt-text="Screenshot showing project-level pipeline security dialog."::: -4. Modify the permissions associated with an [Azure DevOps group](../../organizations/security/permissions.md), for example, Build Administrators, or for an [individual user](set-permissions.md). +1. Repeat the previous step to change the permissions for more groups and users. +1. Select **Save changes** or you can select **Undo changes** to undo the changes. -5. Select **Allow** or **Deny** for the permission for a security group or an individual user, and then exit the screen. +1. To remove a user or group from the list, select the user or group and select **Remove**. +1. Select **Close**. Your project-level pipelines permissions are set. ::: moniker-end -::: moniker range="< azure-devops-2020" -Build and YAML pipeline permissions follow a hierarchical model. You can set defaults for all permissions at the project-level and override permissions for an individual build pipeline. +### Set object-level pipeline permissions -To set the permissions at project-level for all pipelines in a project, choose **Security** from the action bar on the main page of **Builds** hub. +::: moniker range=">= azure-devops-2022" -::: moniker-end -### Set individual pipeline permissions +By default, object-level permissions for individual pipelines are inherited from the project-level permissions. You can override the inherited project-level permissions. -::: moniker range=">=azure-devops-2020" +You can set the permissions to **Allow**, **Deny**, or to **Not set** if the permission isn't inherited. If inheritance is enabled, you can change an explicitly set permission back to the inherited value. + +To manage permissions for a pipeline, do the following steps: + +1. From your project, select **Pipelines** . + + :::image type="content" source="media/pipelines-navigation-from-project.png" alt-text="Screenshot showing Pipelines menu selection."::: -Do the following steps to set permissions for an individual pipeline. +2. Select a pipeline, then select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Manage security**. + + :::image type="content" source="media/individual-pipeline-more-actions-menu.png" alt-text="Screenshot showing selected security option from a pipeline's more actions menu."::: -1. From within your project, select **Pipelines** > **Pipelines**. +3. Select a user or group and set the permissions. + :::image type="content" source="media/individual-pipeline-security-dialog.png" alt-text="Screenshot of object-level pipeline security dialog."::: + +4. Repeat the previous step to change the permissions for more groups and users. +5. When you're finished, close the dialog to save your changes. + +#### Add users or groups to the permissions dialog + +To add users and groups that aren't listed in the permissions dialog, do the following steps: + +1. Enter the user or group in the search bar, then select the user or group from the search result. +1. Set the permissions. +1. Close the dialog. + +When you open the security dialog again, the user or group is listed. + +#### Remove users or groups from the permissions dialog + +Inherited users and groups can't be removed unless inheritance is disabled. To remove users or groups from a pipeline's permissions, do the following steps: + +1. Select the user or group. +2. Select **Remove and clear explicit permissions**. + + :::image type="content" source="media\delete-user-in-security-dialog.png" alt-text="Screenshot of remove user or group selection."::: + +3. When you're done, close the dialog to save your changes. + +::: moniker-end + +::: moniker range="azure-devops-2020" + +By default, object-level permissions for individual pipelines inherit the project-level permissions. You can override the inherited permissions. + +You can set the permissions to **Allow**, **Deny**, or to **Not set** if the permission isn't inherited. If inheritance is enabled, you can change an explicitly set permission back to the inherited value. + +To set permissions for an individual pipeline, do the following steps: + +1. From your project, select **Pipelines** . + :::image type="content" source="media/pipelines-navigation-from-project.png" alt-text="Screenshot showing Pipelines ordered menu selections."::: -2. Select an individual pipeline, and then select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: > **Manage security**. +2. Select a pipeline, then select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Manage security**. + + :::image type="content" source="media/individual-pipeline-more-actions-menu.png" alt-text="Screenshot showing selected Manage security option from a pipeline's more actions menu."::: + +3. To add users or groups that aren't listed in the permissions dialog, select **Add**, enter the user or group, and select **Save changes**. +4. Select users and groups and set the permissions. +5. Select **Save changes** or **Undo changes*, if necessary. + + :::image type="content" source="media/individual-pipeline-permissions-dialog-2020.png" alt-text="Screenshot of pipeline security add user or group selection."::: + +6. To remove a user or group, select the user or group and select **Remove**. You can't remove inherited users or groups unless inheritance is disabled. +7. Select **Close** when you're finished. + +When you explicitly set an inherited user or group permission, inheritance is disabled for that specific permission. To restore inheritance, set the permission to **Not set**. Select **Clear explicit permissions** to reset all explicitly set permissions to their inherited settings. To disable inheritance for all user and group permissions, turn off the **Inheritance** setting. Upon re-enabling inheritance, the permissions for all users and groups revert to their project-level settings. - :::image type="content" source="media/individual-pipeline-more-actions-menu.png" alt-text="Screenshot showing selected Manage security option from an individual pipeline's more actions menu."::: -3. Set permissions, and then **Save** your changes. ::: moniker-end -::: moniker range="< azure-devops-2020" + + +## Set deployment group security in Azure Pipelines + +A deployment group is a pool of physical or virtual target machines that have agents installed. Deployment groups are only available with classic release pipelines. You can create deployment groups in the following circumstances: + +- When dependent deployment groups are provisioned for projects from organization deployment pools +- When a deployment group is created at the project level +- When a project shares a deployment group, dependent deployment groups are created in the recipient projects + +Individual deployment groups inherit the security roles from the project-level assignments. You can override the project-level assignments for a user or group. To remove an inherited user or group, or lower the privilege level of an inherited role, you must [disable inheritance](../../organizations/security/about-permissions.md). + +When a deployment group gets shared with another project, a separate deployment group, which inherits its security roles, is created in the other project. If sharing is disabled, the deployment group is removed from the other project. + +The following table shows security roles for deployment groups: + +| Role | Description | +|------|---------| +| **Reader** | Can only view deployment groups. | +| **Creator** | Can create deployment groups. This role is a project-level role only. | +| **User** | Can view and use deployment groups. | +| **Service Account** | Can view agents, create sessions, and listen for jobs. This role is a collection- or organization-level role only. | +| **Administrator** | Can administer, manage, view, and use deployment groups. | + +The following table shows default user and group role assignments: + +| Group | Role | +|-|-| +| [*project name*]\Contributors | Creator (project-level), Reader (object-level) | +| [*project name*]\Deployment Group Administrators | Administrator | +| [*project name*]\Project Administrators | Administrator | +| [*project name*]\Release Administrators | Administrator | + +### Set project-level deployment group security roles + +Do the following steps to set project-level security roles for all deployment groups: + +1. From your project, select **Deployment groups** under **Pipelines**. +1. Select **Security**. + + :::image type="content" source="media/deployment-group-security-selection.png" alt-text="Screenshot of security selection for all deployment groups."::: + +1. Set roles for users and groups. + + :::image type="content" source="media/deployment-group-project-level-security-dialog.png" alt-text="Screenshot of security dialog for all deployment groups."::: + +1. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. +1. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. + +Do the following steps to add project users or groups that aren't listed in the security dialog: + +1. Select **Add**. +2. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +3. Select the **Role**. +4. Select **Add** to save the changes. + +### Set object-level deployment group security roles + +Do the following steps to set security roles for an individual deployment group: + +1. From your project, select **Deployment groups** under **Pipelines**. +2. Select a deployment group under **Groups**. +3. Select **Security**. + + :::image type="content" source="media/deployment-group-single-group-security-selection.png" alt-text="Screenshot of security selection for an individual deployment group."::: + +4. Set roles for users and groups. To lower the privilege level of an inherited role, disable inheritance. + + :::image type="content" source="media/deployment-groups-single-group-security-dialog.png" alt-text="Screenshot of object-level deployment group security dialog."::: + +5. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. Inherited users and groups can't be removed unless inheritance is disabled. +6. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. + +When you explicitly set a role, the inheritance for that user or group is turned off. To disable inheritance for all users and groups, turn off the **Inheritance** setting. When you re-enable inheritance, the roles for all users and groups revert to their project-level assignments. + +Do the following steps to add project users or groups that aren't listed in the security dialog: + +1. Select **Add**. +1. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +1. Select the **Role**. +1. Select **Add** to save the changes. + + + +## Set security for environments in Azure Pipelines + +Environments bundle deployment targets for YAML pipelines but aren't compatible with classic pipelines. All environments inherit, security roles, assigned at the project level to default users and groups. You can customize these settings for individual environments, including removing inherited users or groups and adjusting privilege levels, by disabling inheritance. Additionally, you can manage pipeline access for each environment. + +The following table shows security roles for environments: + +> [!div class="mx-tdCol2BreakAll"] +> | Role | Description | +> |------------------------------------|---------| +> | **Creator** | Can create environments in the project. It only applies to project-level security. Contributors are automatically assigned this role. | +> | **Reader** | Can view the environment. | +> | **User** | Can use the environment when creating or editing YAML pipelines. | +> | **Administrator** | Can administer permissions, create, manage, view and use environments. The creator of an environment is granted the administrator role for that environment. Administrators can also open access to an environment for all pipelines in the project. | + +The following table shows default user and group role assignments: -To set or override the permissions for an individual pipeline, choose **Security** from the context menu of the individual pipeline. +| Group | Role | +|-|-| +| [*project name*]\Contributors | Creator (project-level) Reader (object-level) | +| [*project name*]\Project Administrators | Creator | +| [*project name*]\Project Valid Users | Reader | + +The individual who creates an environment is automatically given the **Administrator** role for that specific environment. This role assignment is permanent and can't be changed. + +### Set project-level environment security roles + +To set project-level security roles for all environments, do the following steps: + +1. From your project, **Environments** under **Pipelines**. +1. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Security**. + + :::image type="content" source="media/environments-project-security-selection.png" alt-text="Screenshot of security selection for all environments."::: + +1. Set roles for user and groups to **Administrator**, **Creator**, **User**, or **Reader**. + + :::image type="content" source="media/environments-project-security-dialog.png" alt-text="Screenshot of project-level environments security dialog."::: + +1. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. +1. Select **Save** to save your changes or **Undo** to revert unsaved changes. + +To add project users or groups that aren't listed in the security dialog, do the following steps: + +1. Select **Add**. +1. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +1. Select the **Role**. +1. Select **Add** to save the changes. + +### Set object-level environment security + +By default, object-level security roles inherit from project-level settings. But, you can customize these settings for individual environments, including removing inherited users or groups and adjusting privilege levels, by disabling inheritance. Additionally, you can manage pipeline access for each environment. + +#### Set object-level environment user and group security roles + +To set user and group security roles for an environment, do the following steps: + +1. From your project, select **Environments** under **Pipelines**. +1. Select an environment. +1. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Security**. + + :::image type="content" source="media/environments-single-environment-security-selection.png" alt-text="Screenshot of security selection for a single environment."::: + +1. Set roles for user and groups to **Administrator**, **User**, or **Reader**. + + :::image type="content" source="media\environments-single-environment-user-permissions.png" alt-text="Screenshot of object-level security dialog for environments."::: + +1. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. Inherited users and groups can't be removed unless inheritance is disabled. +1. Select **Save** to save your changes or **Undo** to revert unsaved changes. + +Setting a role explicitly for a user or group disables their inheritance. To halt inheritance for everyone, deactivate the **Inheritance** option. Reactivating inheritance resets all users and groups to their original project-level role assignments. + +To add project users or groups that aren't listed in the security dialog, do the following steps: + +1. Select **Add**. +2. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +3. Select the **Role**. +4. Select **Add** to save the changes. + +#### Set pipeline access for an environment + +Pipeline permissions can be set to **Open access** to allow access to all pipelines in a project or restricted access to specific pipelines. Only **Project administrators** can set pipeline permissions to **Open access**. + +To set open access to all pipeline in a project, do the following steps: + +1. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Open access**. + + :::image type="content" source="media/environments-open-access-selection.png" alt-text="Screenshot of open access for pipelines in an environment."::: +1. Select **Open access** on the confirmation dialog. + +To restrict access and manage pipeline access, do the following steps: + +1. Select **Restrict access**. +1. Select **Add pipeline** :::image type="icon" source="../../media/icons/add-dark-icon.png" border="false"::: and select a pipeline from the dropdown menu. +1. To remove a pipeline, select the pipeline and select the **Revoke access** icon. + + :::image type="content" source="media/environments-revoke-pipeline-permission.png" alt-text="Screenshot of revoke pipeline option."::: + + + +## Set library security in Azure Pipelines + +The library facilitates asset sharing, like variable groups and secure files, across build and release pipelines. It employs a unified security model, allowing role assignments for asset management, creation, and usage. These roles, once set at the library level, automatically apply to all contained assets but can be individually adjusted. + +[!INCLUDE [temp](../../organizations/security/includes/library-roles.md)] + +The following table shows default roles: + +| Group | Role | +|-|-| +| [*project name*]\Project Administrators | Administrator | +| [*project name*]\Build Administrators | Administrator | +| [*project name*]\Project Valid Users | Reader | +| [*project name*]\Contributors | Creator (project-level) Reader (object-level) | +| [*project name*]\Release Administrators | Administrator | +| *project name* Build Service (*collection or organization name*) | Reader | + +For individual library assets, the creator is automatically assigned the *Administrator* role. + +### Set project-level library security roles + +::: moniker range=">= azure-devops-2020" + +To manage access for all library assets, such as [variable groups](../library/variable-groups.md) and [secure files](../library/secure-files.md), do the following steps: + +1. From your project, select **Pipelines** > **Library**. + + :::image type="content" source="media/pipeline-library-permissions.png" alt-text="Screenshot of the Library menu item."::: + +2. Select **Security**. + + :::image type="content" source="media/pipelines-security-library.png" alt-text="Screenshot of the library Security button."::: + +3. Select a user or group and change the role to **Reader**, **User**, **Creator**, or **Administrator**. + + :::image type="content" source="media/library-project-level-permissions-dialog.png" alt-text="Screenshot of the library security dialog."::: + +4. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. +5. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. + +To add project users or groups that aren't listed in the security dialog, do the following steps: + +1. Select **Add**. +1. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +1. Select the **Role**. +1. Select **Add** to save the changes. ::: moniker-end -### Pipeline permissions reference - -You can set the following permissions for all pipelines in a project or for an individual pipeline. -Default values are set for project collections and project groups. For example, Project Collection Administrators, Project Administrators, and Build Administrators have all these permissions by default. - -> [!div class="mx-tdCol2BreakAll"] -> | Permission | Description | -> |------------|-------------| -> | **Administer build permissions** | Can change any of the other permissions listed here. | -> | **Delete build pipeline** | Can delete build pipeline(s). | -> | **Delete builds** | Can delete builds for a pipeline. Deleted builds are [retained](retention.md) in the **Deleted** tab for a period before they're destroyed. | -> | **Destroy builds** | Can delete builds from the **Deleted** tab. | -> | **Edit build pipeline** | Can create pipelines and save any changes to a build pipeline, including configuration variables, triggers, repositories, and retention policy. | -> | **Edit build quality** | Can add tags to a build. | -> | **Manage build qualities** | _Only applies to XAML builds_ | -> | **Manage build queue** | _Only applies to XAML builds_ | -> | **Override check-in validation by build** | Applies to [TFVC gated check-in builds](../repos/tfvc.md#gated). Doesn't apply to pull request builds. | -> | **Queue builds** | Can queue new builds. | -> | **Retain indefinitely** | Can toggle the retain indefinitely flag on a build. | -> | **Stop builds** | Can stop builds queued by other team members or by the system. | -> | **Update build information** | It is recommended to leave this alone. It's intended to enable service accounts, not team members. | -> | **View build pipeline** | Can view build pipeline(s). | -> | **View builds** | Can view builds belonging to build pipeline(s). | - -All team members are members of the **Contributors** group. This group permission allows you to define and manage builds and releases. The most common built-in groups include Readers, Contributors, and Project Administrators. - -For more information, see the following articles: -- [Default permissions and access quick reference](../../organizations/security/permissions-access.md) -- [About permissions and inheritance](../../organizations/security/about-permissions.md) -- [About security roles](../../organizations/security/about-security-roles.md). -## Set release permissions - -Permissions for release pipelines follow a hierarchical model. You can set default permissions at the project-level, and you can override these permissions on an individual release pipeline. +### Set secure file security roles + +Security roles for **Secure files** are inherited from the project-level library role assignments by default. You can override these assignments for an individual file. To remove an inherited user or group, or lower the privilege level of an inherited role, you must disable inheritance. + +The creator of the secure file is automatically assigned the **Administrator** role for that file, which can't be changed. + +To set permissions for a secure file, do the following steps: + +1. From your project, select **Pipelines** > **Library**. +2. Select **Secure files**. +3. Select a file. +4. Select **Security**. + :::image type="content" source="media/library-file-permissions-dialog.png" alt-text="Screenshot of secure file permission dialog."::: +5. Set the desired role for users and groups. +6. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. Inherited users and groups can't be removed unless inheritance is disabled. +7. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. + +When you explicitly set a role, the inheritance for that user or group is turned off. To disable inheritance for all users and groups, turn off the **Inheritance** setting. When you re-enable inheritance, the roles for all users and groups revert to their project-level assignments. + +To add project users or groups that aren't listed in the security dialog, do the following steps: + +1. Select **Add**. +1. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +1. Select the **Role**. +1. Select **Add** to save the changes. + +### Set variable group security roles + +Security roles for variable groups are inherited from the project-level library role assignments by default. You can override these assignments for an individual variable group. To remove an inherited user or group, or lower the privilege level of an inherited role, you must disable inheritance. + +The creator of the variable group is automatically assigned the **Administrator** role for that group, which can't be changed. + +To set access for a variable group, do the following steps: + +1. From your project, select **Pipelines** > **Library**. +2. Select a variable group. +3. Select **Security**. + :::image type="content" source="media/library-variable-group-permissions.png" alt-text="Screenshot of variable group permission dialog."::: +4. Set the desired role for users and groups. +5. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. Inherited users and groups can't be removed unless inheritance is disabled. +6. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. + +When you explicitly set a role, the inheritance for that user or group is turned off. To disable inheritance for all users and groups, turn off the **Inheritance** setting. When you re-enable inheritance, the roles for all users and groups revert to their project-level assignments. + +To add project users or groups that aren't listed in the security dialog, do the following steps: + +1. Select **Add**. +1. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +1. Select the **Role**. +1. Select **Add** to save the changes. + + + +## Set release pipeline permissions in Azure Pipelines + +Once you create a release pipeline, you can set project-level permissions for all release pipelines and object-level permissions for individual release pipelines and stages. You can also set permissions for release stages, which are a subset of permissions inherited from the object-level release pipeline permissions. + +The following table shows the permission hierarchy for release pipelines: + +- Project-level release pipelines permissions +- Object-level release pipeline permissions +- Object-level stage permissions + +The following table shows default user and group roles: + +| Group | Role | +|-|-| +| **Contributors** | All permissions except *Administer release permissions*. | +| **Project Administrators** | All permissions. | +| **Readers** | Can view pipelines and releases. | +| **Release Administrators** | All permissions.| +| **Project Collection Administrators** | All permissions.| +| **\ Build Service(\)** | Can view pipelines and releases.| +| **Project Collection Build Server (\)** | Can view pipelines and releases.| + +For permission descriptions, see [Permissions and groups](../../organizations/security/permissions.md#release-object-level). + +### Set project-level release pipeline permissions ::: moniker range=">=azure-devops-2020" -### Set all release permissions +To update permissions for all releases, do the following steps: -Do the following steps to update permissions for all releases. +1.From your project, select **Pipelines** > **Releases**. -1. Select the file view. +2. Select the file view icon. :::image type="content" source="media/releases-select-file-view.png" alt-text="Screenshot showing selection of the all files view."::: -2. Select the **All pipelines** folder. +3. Select the **All pipelines** folder. - :::image type="content" source="media/releases-select-all-pipelines.png" alt-text="Screenshot showing selection of all pipelines folder."::: + :::image type="content" source="media/releases-select-all-pipelines.png" alt-text="Screenshot showing selection of all release pipelines folder."::: -3. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Security**. -4. Set permissions, and then **Save** your changes. +4. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Security**. -### Set individual release permissions + :::image type="content" source="media/releases-select-all-pipelines-security.png" alt-text="Screenshot of all release pipelines security dialog."::: -Do the following steps to update permissions for an individual release. +5. Select users and groups to and change their permissions. -1. Select the release you want to modify. + :::image type="content" source="media/releases-all-pipelines-permissions.png" alt-text="Screenshot of all release pipelines security add user or group selection."::: -2. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: > **Security**. -3. Set permissions, and then **Save** your changes. +6. When you're done, close the dialog to save your changes. -::: moniker-end +#### Add users or groups to the permissions dialog + +To add users and groups that aren't listed in the permissions dialog, do the following steps: -::: moniker range="< azure-devops-2020" +1. Enter the user or group in the search bar, then select the user or group from the search result. +1. Set the permissions. +1. Close the dialog. -To set permissions at project-level for all release definitions in a project, open the shortcut menu from the ![drop-down list](media/drop-down-list-icon.png) +When you open the security dialog again, the user or group is listed. -To set or override the permissions for a specific release pipeline, open the shortcut menu from the ![drop-down list](media/drop-down-list-icon.png) icon next to that pipeline name. Then choose **Security** to open the **Permissions** dialog. +#### Remove users or groups from the permissions dialog -To specify security settings for individual stages in a release pipeline, open the **Permissions** dialog by choosing **Security** on the shortcut menu that opens from **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: on a stage in the release pipeline editor. +To delete a user from the permissions list, do the following steps: -::: moniker-end +1. From your project permissions page, select the user or group. +1. Select **Remove and clear explicit permissions**. + + :::image type="content" source="media\delete-user-in-security-dialog.png" alt-text="Screenshot of remove user or group selection."::: + +1. When you're done, close the dialog to save your changes. + +::: moniker-end + +### Set object-level release pipeline permissions + +By default, the object-level permissions for individual release pipelines are inherited from the project-level release pipeline permissions. You can override these inherited permissions for a specific release pipeline. + +To override permissions for a release, do the following steps: + +::: moniker range=">= azure-devops-2020" + +1. From your project, select **Pipelines** > **Releases**. +1. Select the file view icon:::image type="icon" source="media/folder-icon.png":::. + +1. Select the release pipeline you want to modify, and then select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: > **Security**. + + :::image type="content" source="media/releases-select-pipeline-security.png" alt-text="Screenshot of object-level release pipeline security dialog."::: + +1. Select users or groups to set their permissions to **Allow**, **Deny** or **Not set**. + + :::image type="content" source="media/releases-individual-pipeline-permissions.png" alt-text="Screenshot of release pipeline security add user or group selection."::: + +1. When you're finished, close the dialog to save your changes. + +When you explicitly set an inherited user or group permission, inheritance is disabled for that specific permission. To restore inheritance, set the permission to **Not set**. To disable inheritance for all user and group permissions, turn off the **Inheritance** setting. Upon re-enabling inheritance, the permissions for all users and groups revert to their project-level settings. + +#### Add users or groups to the permissions dialog + +To add users and groups that aren't listed in the permissions dialog, do the following steps: + +1. Enter the user or group in the search bar, then select the user or group from the search result. +1. Set the permissions. +1. Close the dialog. + +When you open the security dialog again, the user or group is listed. + +#### Remove users or groups from the permissions dialog + +Users and groups can be removed from a release pipeline. Inherited users and groups can't be removed unless inheritance is disabled. To remove release pipeline permissions for users or groups, do the following steps: + +1. Select the user or group. +2. Select **Remove and clear explicit permissions**. + + :::image type="content" source="media\delete-user-in-security-dialog.png" alt-text="Screenshot of remove user or group selection."::: -### Release permissions reference +3. When you're done, close the dialog to save your changes. -The following table defines permissions for releases. The scope column explains whether the permission can be set at the project, release pipeline, or stage level. +::: moniker-end + +### Set release stage permissions + +Stage permissions are a subset of permissions that are inherited from the object-level release pipeline permissions. + +To set permissions for a stage, do the following steps: + +1. From your project, select **Pipelines** > **Releases**. +1. Select the file view icon :::image type="icon" source="media/folder-icon.png"::: and select **All pipelines**. +1. Select the release pipeline you want to modify from **All pipelines** + + :::image type="content" source="media\release-select-pipeline-for-stage-permissions.png" alt-text="Screenshot of the release pipeline stage security dialog."::: + +1. Select the stage you want to modify. +1. Select the **More options icon** :::image type="icon" source="../../media/icons/actions-icon.png"::: and select **Security**. + + :::image type="content" source="media/releases-select-stage-security.png" alt-text="Screenshot showing release stage security navigation selections."::: + +1. To add users or groups that aren't listed in the permissions dialog, select **Add**, enter the user or group, and select **Save changes**. + +1. Select users and groups to set their permissions to **Allow**, **Deny** or **Not set**. + + :::image type="content" source="media/releases-stage-permissions.png" alt-text="Screenshot of release pipeline stage security dialog."::: + +1. Select **Save changes** or you can select **Undo changes** to undo the changes. You must save the changes to apply the permissions before selecting another user or group. +1. You can select more users and groups to change their permissions. +1. To remove a user or group, select the user or group and select **Remove**. Inherited users and groups can't be removed unless inheritance is disabled. +1. Select **OK** when you're finished. + +When you explicitly set an inherited user or group permission, inheritance is disabled for that specific permission. To restore inheritance, set the permission to **Not set**. Select **Clear explicit permissions** to reset all explicitly set permissions to their inherited settings. To disable inheritance for all user and group permissions, turn off the **Inheritance** setting. Upon re-enabling inheritance, the permissions for all users and groups revert to their project-level settings. + + + +## Set service connection security in Azure Pipelines + +Service connections are used to connect to external and remote services. You can set service connection security for: + +::: moniker range=">= azure-devops-2020" + +* Projects: Permissions are set at the object level. +* Pipelines: Permissions are set at the object level. +* Users and Groups: Security roles are set at the project and object levels. + +The following table show service connection roles: + +| Role | Purpose | +|------------------------------------|---------| +| **Reader** | Can view service connections. | +| **User** | Can use service connections in classic and YAML build and release pipelines. | +| **Creator** | Can create a service connection in the project. This role is a project-level role only.| +| **Administrator** | Can use the service connection and manage roles for other users and groups. | + +The following table shows default security roles for service connections: + +| Group | Role | +|-|-| +| [*project name*]\Endpoint Administrators | Administrator | +| [*project name*]\Endpoint Creators | Creator | + +The user who creates the service connection is automatically assigned the Administrator role for that service connection. + +::: moniker-end + +::: moniker range=">= azure-devops-2020" -> [!div class="mx-tdCol2BreakAll"] -> | Permission | Description | -> |------------------------------------| -----------------------------------| -> | **Administer release permissions** | Can change any of the other permissions listed here.
      *Scopes*: Project, Release pipeline, Stage | -> | **Create releases** | Can create new releases.
      *Scopes*: Project, Release pipeline | -> | **Delete release pipeline** | Can delete release pipeline(s).
      *Scopes*: Project, Release pipeline | -> | **Delete release stage** | Can delete stage(s) in release pipeline(s).
      *Scopes*: Project, Release pipeline, Stage | -> | **Delete releases** | Can delete releases for a pipeline.
      *Scopes*: Project, Release pipeline | -> | **Edit release pipeline** | Can save any changes to a release pipeline, including configuration variables, triggers, artifacts, and retention policy as well as configuration within a stage of the release pipeline. To update a specific stage in a release pipeline, the user also needs **Edit release stage** permission.
      *Scopes*: Project, Release pipeline | -> | **Edit release stage** | Can edit stage(s) in release pipeline(s). To save the changes to the release pipeline, the user also needs **Edit release pipeline** permission. This permission also controls whether a user can edit the configuration inside the stage of a specific release instance. The user also needs **Manage releases** permission to save the modified release.
      *Scopes*: Project, Release pipeline, Stage| -> | **Manage deployments** | Can initiate a deployment of a release to a stage. This permission is only for deployments that are manually initiated by selecting the **Deploy** or **Redeploy** actions in a release. If the condition on a stage is set to any type of automatic deployment, the system automatically initiates deployment without checking the permission of the user that created the release. If the condition is set to start after some stage, manually initiated deployments do not wait for those stages to be successful.
      *Scopes*: Project, Release pipeline, Stage | -> | **Manage release approvers** | Can add or edit approvers for stage(s) in release pipeline(s). This permission also controls whether a user can edit the approvers inside the stage of a specific release instance.
      *Scopes*: Project, Release pipeline, Stage | -> | **Manage releases** | Can edit the configuration in releases. To edit the configuration of a specific stage in a release instance (including variables marked as `settable at release time`), the user also needs **Edit release stage** permission.
      *Scopes*: Project, Release pipeline | -> | **View release pipeline** | Can view release pipeline(s).
      *Scopes*: Project, Release pipeline| -> | **View releases** | Can view releases belonging to release pipeline(s).
      *Scopes*: Project, Release pipeline | +For more information, see [Service connections](../library/service-endpoints.md). -Default values for all permissions are set for team project collections and project groups. For example, Project Collection Administrators, Project Administrators, and Release Administrators are given all the previously listed permissions by default. Contributors are given all permissions except *Administer release permissions*. By default, Readers -are denied all permissions except *View release pipeline* and *View releases*. +### Set project-level service connection security roles -## Set task group permissions +To manage security roles for all service connections, do the following steps: -Use [task groups](../library/task-groups.md) to combine a sequence of tasks already defined in a pipeline into a single, reusable task. +1. From your project, select **Project settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false":::. +1. Select **Service connections** under **Pipelines**. +1. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Security**. -Task group permissions follow a hierarchical model. You can set default permissions at the project-level, and you can override these permissions on an individual task group pipeline. + :::image type="content" source="media/service-connections-security-selection.png" alt-text="Screenshot of select service connection security option."::: + +1. To change a role, select a user or group, and select a role from the dropdown menu. + + :::image type="content" source="media/service-connection-project-level-permissions-dialog.png" alt-text="Screenshot of project-level service connections security dialog."::: + +1. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. +1. Select **Save** to save your changes or **Undo** to revert unsaved changes. + +To add project users or groups that aren't listed in the security dialog, do the following steps: + +1. Select **Add**. +1. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +1. Select the **Role**. +1. Select **Add** to save the changes. + +::: moniker-end ::: moniker range=">=azure-devops-2020" -### Set project-level task group permissions -Do the following steps to update permissions for project-level task groups. +### Set object-level service connection security + +You can set security roles for users and groups, as well as pipeline and project access, to the service connection. Individual service connections inherit the project-level role assignments for users and groups by default. + +To open the security dialog for an individual service connection, do the following steps: + +1. From your project, select **Project settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false":::. +1. Select **Service connections** under **Pipelines**. +1. Select a service connection. +1. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and select **Security**. + +### Set service connection security roles for users and groups + +You can override the inherited roles for users and groups. Inheritance must be disabled to remove an inherited user or group or to lower the privilege level of an inherited role. + +To manage security roles for an individual service connection, do the following steps: + +1. In the **User permissions** section of the **Security** dialog, select **Project** to manage project-level users and groups, or **Organization** to manage organization- or collection-level users and groups. + + :::image type="content" source="media/individual-service-connection-permission-user-dialog.png" alt-text="Screenshot of user permissions dialog for individual service connections."::: + +1. Select users and groups and change their roles. To lower the privilege level of an inherited role, inheritance must be disabled. +1. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. Inherited users and groups can't be removed unless inheritance is disabled. +1. Select **Save** to save your changes or **Undo** to revert unsaved changes. + +When you explicitly set a role, the inheritance for that user or group is turned off. To disable inheritance for all users and groups, turn off the **Inheritance** setting. When you re-enable inheritance, the roles for all users and groups revert to their project-level assignments. + +To add project users or groups that aren't listed in the security dialog: + +1. Select **Add**. +1. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +1. Select the **Role**. +1. Select **Add** to save the changes. + +### Set service connection pipeline permissions + +You can set the pipeline permissions to **Open access**, allowing all pipelines to use the service connection, or you can restrict access to specific pipelines. + +When the pipeline permissions are set to **Open access**, you can limit access by selecting the **Restrict access** option. + + :::image type="content" source="media/service-connection-restrict-access.png" alt-text="Screenshot of restrict access option for an individual service connection."::: + +To add pipelines to the restricted service connection, select **Add pipeline** :::image type="icon" source="../../media/icons/add-dark-icon.png" border="false"::: and select a pipeline from the dropdown menu. + +To change a service connection from restricted to open access, select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: and then **Open access**. + + :::image type="content" source="media/service-connection-open-access.png" alt-text="Screenshot of open access option for an individual service connection."::: + +### Set service connection project permissions + +You can share a service connection across multiple projects. Project permissions control which projects can use the service connection. By default, service connections aren't shared with any other projects. + +* Only the organization-level administrators from user permissions can share the service connection with other projects. +* The user who's sharing the service connection with a project must have at least Create service connection permission in the target project. +* The user who shares the service connection with a project becomes the project-level Administrator for that service connection. The project-level inheritance is set to on in the target project. +* The service connection name is appended with the project name and it can be renamed in the target project scope. +* Organization-level administrator can unshare a service connection from any shared project. + +Access is restricted to the current project by default. To grant access to other projects in the organization or collection, select **Add projects**. + + :::image type="content" source="media/service-connection-project-permissions.png" alt-text="Screenshot of project permissions selection for individual service connections."::: + +::: moniker-end + +If you're having trouble with permissions and service connections, see [Troubleshoot Azure Resource Manager service connections](../release/azure-rm-endpoint.md). + + + +## Set task group permissions in Azure Pipelines + +The permissions for task groups follow a hierarchical model. By default, all task groups inherit the project-level permissions. Once a task group is created, you can modify the project-level permissions and the object-level permissions for individual task groups. + +The following table show permissions for task groups: + +| Permission | Description | +|------------|-------------| +| Administer task group permissions | Can add and remove users or groups to task group security. | +| Delete task group | Can delete a task group. | +| Edit task group | Can create, modify, or delete a task group. | + +The following table shows default permissions for security groups: + +[!INCLUDE [temp](../../organizations/security/includes/task-groups.md)] + +The creator of a task group has all permissions to the task group. > [!NOTE] > Task groups aren't supported in YAML pipelines, but templates are. For more information, see [YAML schema reference](/azure/devops/pipelines/yaml-schema/steps-template). +### Set project-level task group permissions + +::: moniker range="> azure-devops-2020" + +To set permissions for project-level task groups, do the following steps: + 1. From your project, select **Pipelines** > **Task groups**. - :::image type="content" source="media/task-group-permissions.png" alt-text="Find task group menu item."::: + :::image type="content" source="media/task-group-permissions.png" alt-text="Screenshot of task group menu item."::: -1. Select **Security**. +2. Select **Security**. - :::image type="content" source="media/task-group-security-project.png" alt-text="Select the Security option for a task group."::: + :::image type="content" source="media/task-group-security-project.png" alt-text="Screenshot of task groups security selection."::: -1. Select **Allow** or **Deny** for the permission for a security group or an individual user. +3. Select users and groups to set their permissions to **Allow**, **Deny**, or **Not set**. -### Set pipeline-level task group permissions + :::image type="content" source="media/task-groups-project-level-permissions.png" alt-text="Screenshot of task group security dialog."::: -Do the following steps to update permissions for pipeline-level task groups. +4. When you're done, close the dialog to save your changes. + +#### Add users or groups to the permissions dialog + +To add users and groups that aren't listed in the permissions dialog, do the following steps: + +1. Enter the user or group in the search bar, then select the user or group from the search result. +1. Set the permissions. +1. Close the dialog. + +When you open the security dialog again, the user or group is listed. + +#### Remove users or groups from the permissions dialog + +To remove a user from the permissions list, do the following steps: + +1. Select the user or group. +1. Select **Remove and clear explicit permissions**. + + :::image type="content" source="media\delete-user-in-security-dialog.png" alt-text="Screenshot of remove user or group selection."::: + +1. When you're done, close the dialog to save your changes. + +::: moniker-end + +::: moniker range="=azure-devops-2020" + +To set permissions for project-level task groups, do the following steps: 1. From your project, select **Pipelines** > **Task groups**. - :::image type="content" source="media/task-group-permissions.png" alt-text="Find task group menu item."::: + :::image type="content" source="media/task-group-permissions.png" alt-text="Screenshot of task group selection."::: -2. Select a task group. +2. Select **Security**. + + :::image type="content" source="media/task-group-security-project.png" alt-text="Screenshot of task groups security selection."::: + +3. To add users or groups that aren't listed in the permissions dialog, select **Add**, enter the user or group, and select **Save changes**. -3. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: > **Security**. +4. Select a user or group to set the permissions to **Allow**, **Deny** or **Not set**. + + :::image type="content" source="media/task-group-project-level-permissions-2019.png" alt-text="Screenshot of pipeline task groups security dialog."::: + +5. Select **Save changes** or you can select **Undo changes** to undo the changes. You must save the changes to apply the permissions before selecting another user or group. +6. You can select more users and groups to change their permissions. +7. Select **Close** when you're finished. -4. Select **Allow** or **Deny** for the permission for a security group or an individual user. ::: moniker-end -### Task group permissions reference -> [!div class="mx-tdCol2BreakAll"] -> | Permission | Description | -> |------------|-------------| -> | **Administer task group permissions** | Can add and remove users or groups to task group security. | -> | **Delete task group** | Can delete a task group. | -> | **Edit task group** | Can create, modify, or delete a task group. | +### Set object-level task group permissions -## Set agent pool permissions +::: moniker range=">=azure-devops-2022" -You can use predefined roles to configure [security on agent pools](../agents/pools-queues.md#security) in a hierarchical manner for all pools, or for an individual pool. Do the following steps to set agent pool permissions for all pools. +To set permissions for individual task groups, do the following steps: -::: moniker range=">=azure-devops-2020" -### Set all agent pool permissions +1. From your project, select **Pipelines** > **Task groups**. -Do the following steps to update permissions for all agent pools. + :::image type="content" source="media/task-group-permissions.png" alt-text="Screenshot of Task group selection."::: -1. From your project, select **Project settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: > **Agent pools**. -2. Select **Security**. +2. Select a task group. - :::image type="content" source="media/agent-pool-security.png" alt-text="Configure agent pool security."::: +3. Select **More commands** :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: and select **Security**. -3. Set permissions, and then **Save** your changes. +4. Select users and groups to set their permissions to **Allow**, **Deny**, or **Not set**. -### Set individual agent pool permissions + :::image type="content" source="media\task-group-individual-permission.png" alt-text="Screenshot of object-level task group security dialog."::: -Do the following steps to set permissions for an individual agent pool. +5. When you're done, close the dialog to save your changes. -1. From the agent pool, select the agent. -2. Select **Security**. +When a permission for an inherited user or group is explicitly set, inheritance is disabled for that specific permission. Change the permission to **Not set** to restore inheritance. To disable inheritance for all user and group permissions, turn off the **Inheritance** setting. Upon re-enabling inheritance, the settings for all permissions revert to the project level. + +#### Add users or groups to the permissions dialog + +To add users and groups that aren't listed in the permissions dialog, do the following steps: + +1. Enter the user or group in the search bar, then select the user or group from the search result. +1. Set the permissions. +1. Close the dialog. + +When you open the security dialog again, the user or group is listed. + +#### Remove users or groups from the permissions dialog + +Users and groups can be removed from the task group. Inherited users and groups can't be removed unless inheritance is disabled. + +1. Select the user or group. +1. Select **Remove and clear explicit permissions**. + + :::image type="content" source="media\delete-user-in-security-dialog.png" alt-text="Screenshot of remove user or group selection."::: + +1. When you're done, close the dialog to save your changes. - :::image type="content" source="media/single-agent-pool-security.png" alt-text="Set security for one agent pool."::: -3. Set permissions, and then **Save** your changes. ::: moniker-end -## Set library permissions +::: moniker range="azure-devops-2020" -Use a variable group to store values that you want to make available across multiple build and release pipelines. Define roles to help you configure security on shared [library entities](../library/index.md). You can also configure the inheritance of roles. +You can set the permissions to **Allow**, **Deny**, or to **Not set** if the permission isn't inherited. If inheritance is enabled, you can change an explicitly set permission back to the inherited value. -::: moniker range=">=azure-devops-2020" +To set permissions for individual task groups, do the following steps: -Do the following steps to manage permissions for library artifacts, such as [variable groups](../library/variable-groups.md) and [secure files](../library/secure-files.md). +1. From your project, select **Pipelines** > **Task groups**. -1. From your project, select **Pipelines** > **Library**. + :::image type="content" source="media/task-group-permissions.png" alt-text="Screenshot of Task group selection."::: + +2. Select a task group. - :::image type="content" source="media/pipeline-library-permissions.png" alt-text="Open the Library menu option."::: +3. Select **More commands** :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: and select **Security**. -2. Select **Security**. +4. Select users and groups to set their permissions to **Allow**, **Deny**, or **Not set**. + + :::image type="content" source="media\task-group-individual-permission.png" alt-text="Screenshot of object-level task group security dialog."::: - :::image type="content" source="media/pipelines-security-library.png" alt-text="Security option in Library."::: +5. When you're done, close the dialog to save your changes. -3. Set permissions for everything in your library or for an individual variable group or secure file, and then **Save** your changes. +When a permission for an inherited user or group is explicitly set, inheritance is disabled for that specific permission. Change the permission to **Not set** to restore inheritance. To disable inheritance for all user and group permissions, turn off the **Inheritance** setting. Upon re-enabling inheritance, the settings for all permissions revert to the project level. + +#### Add users or groups to the permissions dialog + +To add users and groups that aren't listed in the permissions dialog, do the following steps: + +1. Enter the user or group in the search bar, then select the user or group from the search result. +1. Set the permissions. +1. Close the dialog. + +When you open the security dialog again, the user or group is listed. + +#### Remove users or groups from the permissions dialog + +Users and groups can be removed from the task group. Inherited users and groups can't be removed unless inheritance is disabled. + +1. Select the user or group. +1. Select **Remove and clear explicit permissions**. + + :::image type="content" source="media\delete-user-in-security-dialog.png" alt-text="Screenshot of remove user or group selection."::: + +1. When you're done, close the dialog to save your changes. ::: moniker-end -### Library permissions reference + -[!INCLUDE [temp](../../organizations/security/includes/library-roles.md)] +## Set agent pool security in Azure Pipelines -## Set service connection permissions +Agent pools are a collection of agents that you use to run build and release jobs. -Configure permissions for all [service connections](../library/service-endpoints.md) or for an individual connection. +::: moniker range="azure-devops" -::: moniker range=">=azure-devops-2020" +You can create agent pools with either organization scope or project scope. Organization-scoped agent pools are accessible to all existing or new projects in the organization, and by default, each organization has two agent pools: **Azure Pipelines** and **Default**. These default pools are accessible by all projects in the organization. -### Set all service connection permissions +Project-scoped agent pools are created at the project level and are accessible only to that project. -Do the following steps to configure permissions for all service connections. +From the organization settings, you can manage the organization-level security settings for all agent pools in the organization, and for individual agent pools. Both organization- and project-level security roles can be managed from the project settings. -1. From within your project, select **Project settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false":::. -2. Select **Service connections** under Pipelines. -3. Set permissions, and then **Save** your changes. +::: moniker-end -### Set individual service connection permissions +::: moniker range="<= azure-devops-2022" -Do the following steps to configure permissions for an individual service connection. +You can create agent pools with either collection scope or project scope. Collection scoped agent pools are accessible to all existing or new projects in the collection, and by default, each collection has two agent pools: **Azure Pipelines** and **Default**. These default pools are accessible by all projects in the collection. -1. From within your project, open a service connection. -2. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: > **Security**. -3. Set permissions, and then **Save** your changes. +Project-scoped agent pools are created at the project level and are accessible only to that project. - :::image type="content" source="media/security-option-service-connection.png" alt-text="Select security service connection option."::: +From the collection settings, you can manage the collection-level security settings for all agent pools in the collection, and for individual agent pools. Both collection- and project-level security roles can be managed at the object level from the project settings. ::: moniker-end -::: moniker range="< azure-devops-2020" -[Add users to the following roles](set-permissions.md) from the project-level admin context, **Services** page. For more information about how to create and manage these resources, see [Service connections for build and release](../library/service-endpoints.md). +Use predefined security roles to manage [security for agent pools](../agents/pools-queues.md#security). + +The following table shows security roles for agent pools: + +| Role | Purpose | +|------------------------------------|---------| +| Reader | Can view agent pools. | +| User | Can use agent pools in classic and YAML build and release pipelines. | +| Creator | Can create agent pools in the project. This role is a project-level role only.| +| Service Account | Can view agents, create sessions, and listen for jobs from the agent pool. This role is set at the organization/collection level only. | +| Administrator | Can manage and use agent pools and manage roles for other users and groups. | + +The following table shows default project and object security roles for agent pools: + +| Group | Role | +|-|-| +| [*project name*]\Project Administrators | Administrator | +| [*project name*]\Build Administrators | Administrator | +| [*project name*]\Project Valid Users | Reader | +| [*project name*]\Release Administrators | Administrator | +| The user who created the agent pool | Administrator | + +::: moniker range="azure-devops" + +### Add the principal as a user + +Before you can add a user or service principal in the **Security** settings of an agent pool, you must add it as a user in your organization. + +1. Go to **Organization settings**. +2. Select **Users**. +3. Add the user or service principal with at least Basic access. + +### Set organization security for agent pools + +You can manage collection-level users and groups for all agent pools in the organization or for individual project-scoped agent pools. The security roles for agent pools are **Reader**, **Service Account**, and **Administrator**. The **User** and **Creator** roles aren't available at the organization level. + +#### Set organization security for all agent pools + +By default, no users or groups have explicit roles for all pools at the organization level. You can add organization-level users and groups and manage security roles for all agent pools in the organization. + +To manage security roles for all agent pools in the organization, do the following steps: + +1. [Add the user or group as a user in the organization](#add-the-principal-as-a-user). +2. Go to **Organization settings** ::::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: and select **Agent pools**. +3. Select **Security**. + + :::image type="content" source="media/agent-pools-organization-security-selection.png" alt-text="Screenshot of organization-level security selection for all agent pools."::: + +4. To add users and groups: + 1. Select **Add** + 2. Enter a user or group and select it from the search results. + 1. Select a role and choose **Add**. + 1. Repeat the previous step to add more users and groups. + 1. Choose **Save** to save your changes. + 1. Verify that your new users are saved in the list. If they did not save, verify that the users are members of your organization with at least Basic access and try again. + 1. Choose **Close** to close the **User permissions** window. + +1: To create a new pipeline, you need **Create build pipeline** permissions. To add permission, open the security settings for all pipelines and verify that **Create build pipeline** is set to **Allow** for your security group. + +5. To remove a user or group from the list, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. + +6. To change a security role, select the user or group and select the role from the dropdown list. + +7. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. + + :::image type="content" source="media\agent-pool-organization-security-dialog.png" alt-text="Screenshot of organization-level security dialog for all agent pools."::: + +8. Close the dialog. + +#### Set organization security for individual agent pools + +Individual agent pools inherit the organization-level security assignments. The **Default** and **Azure Pipelines** agent pools include the **Project Valid Users** group for each project in the organization. + +Agent pools created at the project-level are automatically assigned the **[\]\Project Valid Users** group and the creator of the agent pool. The creator can't be deleted or modified. Any organization-level users and groups that are added from the project settings are listed here. + +You can add and remove organization-level users and groups and set security roles for an individual agent pool. The security roles at this level are **Reader**, **Service Account**, and **Administrator**. + +To manage security roles for all agent pools in the collection, do the following steps: + +1. Go to **Organization settings** ::::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: and select **Agent pools**. +2. Select an agent pool. +3. Select **Security**. +4. To add users and groups: + 1. Select **Add** + 2. Enter a user or group and select it from the search results. + 3. Repeat the previous step to add more users and groups. + 4. Select a role and select **Add**. + :::image type="content" source="media/agent-pool-add-user.png" alt-text="Screenshot of organization-level add user for an agent pool."::: +5. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. +6. To change a security role, select the user or group and select the role from the dropdown list. +7. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. + :::image type="content" source="media\agent-pools-organization-level-security-for-individual-pool.png" alt-text="Screenshot of organization-level security dialog for an individual agent pool."::: +8. Close the dialog. ::: moniker-end -If you're having trouble with permissions and service connections, see [Troubleshoot Azure Resource Manager service connections](../release/azure-rm-endpoint.md). -### Service connection permissions reference -[!INCLUDE [temp](../../organizations/security/includes/service-endpoint-roles.md)] +::: moniker range="]\Project Valid Users** group and the creator of the agent pool. The creator can't be deleted or modified. Any collection-level users and groups that are added from the project settings are listed here. + +You can add and remove collection-level users and groups and set security roles for an individual agent pool. The security roles at this level are **Reader**, **Service Account**, and **Administrator**. To lower the privilege level of an inherited role, inheritance must be disabled. + +To manage security roles for all agent pools in the collection, do the following steps: -### Set individual deployment group permissions +1. Go to **Collection settings** ::::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: and select **Agent pools**. +2. Select an agent pool. +3. Select **Security**. +4. To add users and groups: + 1. Select **Add** + 2. Enter a user or group and select it from the search results. + 3. Repeat the previous step to add more users and groups. + 4. Select a role and select **Add**. + + + :::image type="content" source="media/agent-pool-add-user.png" alt-text="Screenshot of collection-level add user dialog."::: -1. From within your project, open a deployment pool. -2. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: > **Security**. -3. Set permissions, and then **Save** your changes. +5. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. +6. To change a security role, select the user or group and select the role from the dropdown list. +7. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. + + :::image type="content" source="media\agent-pools-organization-level-security-for-individual-pool.png" alt-text="Screenshot of collection-level security dialog for an individual agent pool."::: + +8. Close the dialog. ::: moniker-end -### Deployment pool permissions reference +### Set project-level agent pool security -[!INCLUDE [temp](../../organizations/security/includes/deployment-pool-roles.md)] +To set project-level security roles for all agent pools, do the following steps: -::: moniker range=">=azure-devops-2020" +1. From your project, select **Project settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: and select **Agent pools**. +1. Select **Security**. -## Set environment permissions + :::image type="content" source="media/agent-pool-security.png" alt-text="Screenshot of security selection for all agent pools."::: -You can use roles and user permissions to control who [can create, view, and manage environments](../process/environments.md#security). Apply a hierarchy of roles to all environments or one environment. +1. Select a user or group and set the role to **Reader**, **User**, **Creator**, or **Administrator**. -### Set all environment permissions + :::image type="content" source="media/agent-pool-project-level-permissions.png" alt-text="Screenshot of security dialog for all agent pools."::: -1. From within your project, select **Project settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false":::. -2. Select **Environments** under Pipelines. -3. Set permissions, and then **Save** your changes. +1. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. - :::image type="content" source="media/environments-permissions.png" alt-text="Select Environments."::: +2. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. -### Set individual environment permissions +To add project users or groups that aren't listed in the security dialog: -Select **Security** from **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: to change permissions for all environment. +1. Select **Add**. +1. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +1. Select the **Role**. +1. Select **Add** to save the changes. + + :::image type="content" source="media/agent-pool-add-user.png" alt-text="Screenshot of add user dialog."::: + +### Set object-level agent pool security -1. From within your project, open an environment. -2. Select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: > **Security**. -3. Set permissions, and then **Save** your changes. +You can override project-level user and group role assignments and set pipeline permissions for an individual agent pool. To remove an inherited user or group, or lower the privilege level of an inherited role, you must disable inheritance. -### Environment permissions reference +::: moniker range=">= azure-devops-2022" -> [!IMPORTANT] -> When you create an environment in a YAML, contributors and project administrators have the administrator role. When you create an environment through the UI, only the creator has the administrator role. +To open the security dialog: -[!INCLUDE [temp](../../organizations/security/includes/environment-roles.md)] +1. From your project, select **Project settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: and select **Agent pools**. + +1. Select an agent pool. +1. Select **Security**. + +#### Set pipeline permissions for an individual agent pool + +To set pipeline permissions for an individual agent pool: + +1. Select **Restrict permission**. This option is only available if the pool isn't restricted to specific pipelines. + + :::image type="content" source="media/agent-pool-restrict-permissions.png" alt-text="Screenshot of pipeline permissions dialog for an individual agent pool."::: + +2. Select **Add pipeline** :::image type="icon" source="../../media/icons/add-dark-icon.png" border="false":::. + + :::image type="content" source="media/agent-pool-add-pipeline.png" alt-text="Screenshot of the button to add a pipeline."::: + +3. Select the pipeline you want to add to the agent pool from the dropdown menu. + +To open access to all pipelines, select **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false":::, then select **Open access**. + + :::image type="content" source="media/agent-pool-open-access.png" alt-text="Screenshot of agent pool open access for all pipelines selection."::: + +#### Set object-level agent pool user permissions + +From the **User permissions** section of the security dialog: + +1. Select a user or group and set the role to **Reader**, **User**, or **Administrator**. + + :::image type="content" source="media/agent-pool-individual-pool-user-permissions.png" alt-text="Screenshot of user permissions dialog for an individual agent pool."::: + +1. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. Inherited users and groups can't be removed unless inheritance is disabled. + +2. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. + +When you explicitly set a role, the inheritance for that user or group is turned off. To disable inheritance for all users and groups, turn off the **Inheritance** setting. When you re-enable inheritance, the roles for all users and groups revert to their project-level assignments. + +To add project users or groups that aren't listed in the security dialog, do the following steps: + +1. Select **Add**. + +1. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +1. Select the **Role**. +1. Select **Add** to save the changes. + + :::image type="content" source="media/agent-pool-add-user.png" alt-text="Screenshot of add user dialog."::: ::: moniker-end -## FAQs +::: moniker range="=azure-devops-2020" -See the following frequently asked questions (FAQs) about pipeline permissions. -### Q: Why can't I create a new pipeline? +To set pipeline and user security roles and pipeline permissions for an individual agent pool, do the following steps. -A: You need **Edit build pipeline** permissions to create a new pipeline. To add permission, open the security settings for all pipelines and verify that **Edit build pipeline** is set to _Allow_ for your security group. +1. Go to your agent pool and select **Security**. -If you still can't create a pipeline, check to see if your [access level](../../organizations/security/access-levels.md) is set to **Stakeholder**. If you have stakeholder access, change your access to **Basic**. +1. Use the **Grant access permissions to all pipelines** switch to enable or disable permissions to all pipelines in the project: -::: moniker range=">=azure-devops-2020" -### Q: Why do I see the message that I need to authorize a resource before the run can continue? + :::image type="content" source="media/agent-pool-grant-permissions.png" alt-text="Screenshot of agent Grant access permissions to all pipelines switch."::: + +To set object-level user and group roles for an agent pool: + +1. From the **User permissions** section of the security dialog: + +1. Select a user or group and set the role to **Reader**, **User**, or **Administrator**. + + :::image type="content" source="media/agent-pool-individual-pool-user-permissions.png" alt-text="Screenshot of object-level user permissions dialog for an agent pool."::: -A: You need to authorize resources before you can use them. The exception to this rule is when you create a pipeline for the first time and all the resources referenced in the YAML file are automatically authorized. The resources are authorized for the pipeline as long as the user running the pipeline has access to the resource. +1. To remove a user or group, select the user or group and select **Delete** :::image type="icon" source="../../media/icons/delete-icon.png" border="false":::. Inherited users and groups can't be removed unless inheritance is disabled. +2. Select **Save changes** :::image type="icon" source="media/save-icon.png" border="false"::: to save your changes or **Reset changes** :::image type="icon" source="media/reset-icon.png" border="false"::: to revert unsaved changes. -To authorize **All pipelines** to access a resource like an agent pool, do the following steps. +When you explicitly set a role, the inheritance for that user or group is turned off. To disable inheritance for all users and groups, turn off the **Inheritance** setting. When you re-enable inheritance, the roles for all users and groups revert to their project-level assignments. -1. From your project, select **Settings** :::image type="icon" source="../../media/icons/team-settings-gear-icon.png" border="false"::: > **Pipelines** > **Agent Pools**. +To add project users or groups that aren't listed in the security dialog, do the following steps: -2. Select **Security** for a specific agent pool, and then update permissions to grant access to all pipelines. +1. Select **Add**. +2. Enter the user or group in the search bar, then select the user or group from the search result. You can add multiple users and groups. +3. Select the **Role**. +4. Select **Add** to save the changes. - :::image type="content" source="media/agent-pool-grant-permissions.png" alt-text="Grant permissions to all pipelines."::: + :::image type="content" source="media/agent-pool-add-user.png" alt-text="Screenshot of add user dialog."::: - For more information, see [Resources in YAML](../process/resources.md). ::: moniker-end ## Related articles -- [Set build and release permissions](set-permissions.md) +- [Get started with permissions, access, and security groups](../../organizations/security/about-permissions.md) - [Default permissions and access](../../organizations/security/permissions-access.md) - [Permissions and groups reference](../../organizations/security/permissions.md) - [Troubleshoot Azure Resource Manager service connections](../release/azure-rm-endpoint.md) +- [Securing Azure Pipelines](../security/overview.md) +- [Azure DevOps CLI reference](/cli/azure/devops) diff --git a/docs/pipelines/policies/retention.md b/docs/pipelines/policies/retention.md index dcb1c96f4c9..a783f4f6e85 100644 --- a/docs/pipelines/policies/retention.md +++ b/docs/pipelines/policies/retention.md @@ -6,7 +6,7 @@ ms.assetid: A9AC68EB-E013-4F86-8604-E69BB330817B ms.author: rabououn author: juliakm ms.date: 05/03/2023 -ms.custom: contperf-fy21q1, contperf-fy21q2, cross-service +ms.custom: cross-service monikerRange: '<= azure-devops' --- @@ -14,12 +14,6 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - Retention policies let you set how long to keep runs, releases, and tests stored in the system. To save storage space, you want to delete older runs, tests, and releases. The following retention policies are available in Azure DevOps in your **Project settings**: @@ -45,23 +39,7 @@ To manage retention policies, you must have one of the following subscriptions: You can also buy monthly access to Azure Test Plans and assign the [Basic + Test Plans](https://marketplace.visualstudio.com/items?itemName=ms.vss-testmanager-web) access level. See [Testing access by user role](../../test/manual-test-permissions.md#access-by-user-role). -::: moniker range="azure-devops-2019" - -## Configure retention policies - -1. Sign in to your project. - -2. Go to the ![gear icon](../../media/icons/gear-icon.png) **Settings** tab of your project's settings. - -3. Select **Release retention** under **Pipelines** or **Retention** under **Test**. - * Select **Release retention** to set up your release retention policies and configure when to delete or permanently destroy releases. - * Select **Retention** to set up how long to keep manual and automated test runs. - - :::image type="content" source="media/devops-2019-retention-menu.png" alt-text="Screenshot of retention settings in Project settings for DevOps 2019."::: - -::: moniker-end - -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" ## Configure retention policies @@ -89,12 +67,6 @@ You can also buy monthly access to Azure Test Plans and assign the [Basic + Test In most cases, you don't need to retain completed runs longer than a certain number of days. Using retention policies, you can control **how many days** you want to keep each run before deleting it. -::: moniker range="tfs-2018" - -Along with defining how many days to retain runs, you can also decide the minimum number of runs that should be kept for each pipeline. - -::: moniker-end - ::: moniker range=">= azure-devops-2020" 1. Go to the ![gear icon](../../media/icons/gear-icon.png) **Settings** tab of your project's settings. @@ -115,7 +87,7 @@ Along with defining how many days to retain runs, you can also decide the minimu > ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" The setting for number of recent runs to keep for each pipeline requires a little more explanation. The interpretation of this setting varies based on the type of repository you build in your pipeline. @@ -146,23 +118,7 @@ The setting for number of recent runs to keep for each pipeline requires a littl ### What parts of the run get deleted -::: moniker range="tfs-2018" - -When the retention policies mark a build for deletion, you can control which information related to the build is deleted: - -* Build record: You can choose to delete the entire build record or keep basic information about the build even after the build is deleted. -* Source label: If you label sources as part of the build, then you can choose to delete the tag (for Git) or the label (for TFVC) created by a build. -* Automated test results: You can choose to delete the automated test results associated with the build (for example, results published by the Publish Test Results build task). - -The following information is deleted when a build is deleted: - -* Logs -* Published artifacts -* Published symbols - -::: moniker-end - -::: moniker range="> tfs-2018" +::: moniker range="<=azure-devops" The following information is deleted when a run is deleted: @@ -180,7 +136,7 @@ Universal packages, NuGet, npm, and other packages are not tied to pipelines ret ### When are runs deleted -::: moniker range="> tfs-2018" +::: moniker range="<=azure-devops" Your retention policies are processed once a day. The time that the policies get processed variables because we spread the work throughout the day for load-balancing purposes. There is no option to change this process. @@ -193,12 +149,6 @@ A run is deleted if all of the following conditions are true: ::: moniker-end -::: moniker range="tfs-2018" - -Your retention policies run every day at 3:00 A.M. UTC. There is no option to change the time the policies run. - -::: moniker-end - ::: moniker range="azure-devops" ### Automatically set retention lease on pipeline runs @@ -224,6 +174,8 @@ You can delete runs using the [More actions menu](../create-first-pipeline.md#pi > [!NOTE] > If any retention policies currently apply to the run, they must be removed before the run can be deleted. For instructions, see [Pipeline run details - delete a run](../create-first-pipeline.md#pipeline-run-more-actions-menu). +> The product team is actively working on improving data deletion times. You might see a processing delay of multiple days when deleting data if there are multiple test points associated with your host. + > [!div class="mx-imgBorder"] > ![delete a run](media/delete-a-run.png) @@ -245,11 +197,6 @@ The retention policy for YAML and build pipelines is the same. You can see your ::: moniker-end -::: moniker range="tfs-2018" -You can also learn how to customize these policies on a [stage-by-stage basis](#stage-specific-retention-policies) later in this article. - -::: moniker-end - ### Global release retention policy If you are using an on-premises Team Foundation Server or Azure DevOps Server, you can specify release retention policy defaults and maximums for a project. You can also specify when releases are permanently destroyed (removed from the **Deleted** tab in the build explorer). @@ -270,112 +217,18 @@ The **default retention policy** sets the default retention values for all the r The **destruction policy** helps you keep the releases for a certain period of time after they are deleted. This policy cannot be overridden in individual release pipelines. +::: moniker range="=azure-devops-2020" -::: moniker range=">= tfs-2018" ## Set collection-level retention policies For on-premises servers, you can also set the collection-level retention policies with custom retention rules. These retention policies apply to Classic build pipelines. The page at `https://{your_server}/{collection_name}/_settings/buildqueue` governs your maximum values and default values. -:::image type="content" source="media/retention-settings-server.png" alt-text="Configure server collection settings"::: - -::: moniker-end - - -::: moniker range="<=tfs-2018" - -> [!NOTE] -> In TFS, release retention management is restricted to specifying the number of days, and this is available only in TFS 2015.3 and newer. - -## Stage-specific retention policies - -You may want to retain more releases that have been deployed to specific stages. For example, your team may want to keep: - -* Releases deployed to Production stage for 60 days, with a minimum of three last deployed releases. -* Releases deployed to Pre-production stage for 15 days, with a minimum of one last deployed release. -* Releases deployed to QA stage for 30 days, with a minimum of two last deployed releases. -* Releases deployed to Dev stage for 10 days, with a minimum of one last deployed release. - -The following example retention policy for a release pipeline meets the above requirements: - - > [!div class="mx-imgBorder"] - > ![Configuring the release retention setting for a release pipeline](media/retention-policy-01.png) - -In this example, if a release that is deployed to Dev is not promoted to QA for 10 days, it is a potential candidate for deletion. However, if that same release is deployed to QA eight days after being deployed to Dev, its retention timer is reset, and it is retained in the system for another 30 days. - -When specifying custom policies per pipeline, you cannot exceed the maximum limits set by administrator. - -::: moniker-end - -::: moniker range="tfs-2018" - -### Interaction between build and release retention policies - -The build linked to a release has its own retention policy, which may be shorter than that of the release. If you want to retain the build for the same period as the release, set the **Retain associated artifacts** checkbox for the appropriate stages. This overrides the retention policy for the build, and ensures that the -artifacts are available if you need to redeploy that release. - -When you delete a release pipeline, delete a release, or when the retention policy deletes a release automatically, the retention policy for the associated build will determine when that build is deleted. - -> [!NOTE] -> In TFS, interaction between build and release retention is available in TFS 2017 and newer. - -## Set test retention policies - -You can set manual and automated test run policies. - -### Manual test-runs retention policies - -To delete manual test results after a specific number of days, set the retention limit at the project level. Azure DevOps keeps manual test results related to builds, even after you delete those builds. That way, build policies don't delete your test results before you can analyze the data. - -1. Sign into your Azure DevOps. You'll need at least project administrator permissions. - -2. Go to your project and then select ![gear icon](../../media/icons/gear-icon.png) project settings at the bottom of the page. - - > [!div class="mx-imgBorder"] - > ![configure project settings](media/project-settings.png) - -3. In the Retention page under the Test section, select a limit for how long you want to keep manual test data. - - > [!div class="mx-imgBorder"] - > ![manual tests retention policies](media/manual-tests-retention-policies.png) - -### Automated test-runs retention policies - -By default, Azure DevOps keeps automated test results related to builds only as long as you keep those builds. To keep test results after you delete your builds, edit the build retention policy. If you use Git for version control, you can specify how long to keep automated test results based on the branch. - -1. Sign into Azure DevOps. You'll need at least build level permissions to edit build pipelines. - -2. Go to your project and then select ![gear icon](../../media/icons/gear-icon.png) project settings at the bottom of the page. - - > [!div class="mx-imgBorder"] - > ![manage project settings](media/project-settings.png) - -3. Select ![gear icon](../../media/icons/gear-icon.png) Settings under Pipelines and modify your retention policies. - - > [!div class="mx-imgBorder"] - > ![edit project settings](media/build-pipelines-retention-policies.png) - -### Other automated test results - -To clean up automated test results that are left over from deleted builds or test results that aren't related to builds, for example, results published from external test systems, set the retention limits at the project level as shown in the [Manual test-runs retention policies](#manual-test-runs-retention-policies) - -## Set artifact retention policies - -You can set artifact retention policies for pipeline runs in the Pipeline settings. - -1. Sign in to your project, For Azure DevOps Services, the URL path is `https://dev.azure.com/{yourorganization}/{yourproject}`. - -2. Go to on the ![gear icon](../../media/icons/gear-icon.png) **Settings** tab of your project's settings. - -3. Select **Settings** in **Pipelines**. - -4. Edit **Days to keep artifacts, symbols, and attachments**. +:::image type="content" source="media/retention-settings-server.png" alt-text="A screenshot showing how to configure collection level retention policies."::: ::: moniker-end - ::: moniker range=">=azure-devops-2020" - ## Use the Copy Files task to save data longer You can use the [Copy Files task](/azure/devops/pipelines/tasks/reference/copy-files-v2) to save your build and artifact data for longer than what is set in the retention policies. The **Copy Files task** is preferable to the [Publish Build Artifacts task](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) because data saved with the **Publish Build Artifacts task** will get periodically cleaned up and deleted. @@ -407,77 +260,6 @@ You can use the [Copy Files task](/azure/devops/pipelines/tasks/reference/copy-f ::: moniker-end -::: moniker range="tfs-2018" - -You can also customize these policies on a branch-by-branch basis if you are building from [Git repositories](#git-repositories). - -## Global build retention policy - -You can specify build retention policy defaults and maximums for a project collection. You can also specify when builds are permanently destroyed (removed from the **Deleted** tab in the build explorer). - -::: moniker-end - -::: moniker range="tfs-2018" - -* TFS 2018: `https://{your_server}/tfs/DefaultCollection/_admin/_buildQueue` - -The **maximum retention policy** sets the upper limit for how long runs can be retained for all build pipelines. -Authors of build pipelines cannot configure settings for their definitions beyond the values specified here. - -The **default retention policy** sets the default retention values for all the build pipelines. Authors of build pipelines can override these values. - -The **Permanently destroy releases** helps you keep the runs for a certain period of time after they are deleted. This policy cannot be overridden in individual build pipelines. - -## Git repositories - -If your [repository type](../repos/index.md) is one of the following, you can define multiple retention policies with branch filters: - -* Azure Repos Git or TFS Git. -* GitHub. -* Other/external Git. - -For example, your team may want to keep: - -* User branch builds for five days, with a minimum of a single successful or partially successful build for each branch. -* Main and feature branch builds for 10 days, with a minimum of three successful or partially successful builds for each of these branches. You exclude a special feature branch that you want to keep for a longer period of time. -* Builds from the special feature branch and all other branches for 15 days, with a minimum of a single successful or partially successful build for each branch. - -The following example retention policy for a build pipeline meets the above requirements: - - > [!div class="mx-imgBorder"] - > ![define git retention policies](media/define-git-retention-policies.png) - -When specifying custom policies for each pipeline, you cannot exceed the maximum limits set by administrator. - - - -### Clean up pull request builds - -If you [protect your Git branches with pull request builds](../../repos/git/branch-policies.md#build-validation), then you can use retention policies to automatically delete the completed builds. To do it, add a policy that keeps a minimum of `0` builds with the following branch filter: - -``` - refs/pull/* -``` - - > [!div class="mx-imgBorder"] - > ![retention policies for PR builds](media/retention-policy-for-pull-request-builds.png) - -### TFVC and Subversion repositories - -For TFVC and Subversion [repository types](../repos/index.md) you can modify a single policy with the same options shown above. - -### Policy order - -When the system is purging old builds, it evaluates each build against the policies in the order you have specified. You can drag and drop a policy lower or higher in the list to change this order. - -The "All" branches policy is automatically added as the last policy in the evaluation order to enforce the maximum limits for all other branches. - - > [!div class="mx-imgBorder"] - > ![define git retention policy max shown in pipeline](media/define-git-retention-policy-max-shown-in-definition.png) - -::: moniker-end - - ## FAQ ### If I mark a run or a release to be retained indefinitely, does the retention policy still apply? @@ -521,7 +303,6 @@ You can also explore the possibility of using the REST APIs in order to download If you believe that you have lost runs due to a bug in the service, create a support ticket immediately to recover the lost information. If a build definition was manually deleted more than a week earlier, it will not be possible to recover it. If the runs were deleted as expected due to a retention policy, it will not be possible to recover the lost runs. - ### How do I use the `Build.Cleanup` capability of agents? Setting a `Build.Cleanup` capability on agents will cause the pool's cleanup jobs to be directed to just those agents, leaving the rest free to do regular work. When a pipeline run is deleted, artifacts stored outside of Azure DevOps are cleaned up through a job run on the agents. When the agent pool gets saturated with cleanup jobs, this can cause a problem. The solution to that is to designate a subset of agents in the pool that are the cleanup agents. If any agents have `Build.Cleanup` set, only those agents will run the cleanup jobs, leaving the rest of the agents free to continue running pipeline jobs. The Cleanup functionality can be enabled by navigating to **Agent** > **Capabilities** and setting `Build.Cleanup` equal to `1`. @@ -543,7 +324,7 @@ Test results published within a stage of a release are retained as specified by No. Manual test results are not deleted. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### How do I preserve my version control labels or tags? @@ -575,3 +356,4 @@ Classic releases retain pipelines that they consume automatically. If you are us - [Control how long to keep test results](../../test/how-long-to-keep-test-results.md) - [Delete test artifacts](../../boards/backlogs/delete-test-artifacts.md) +- [Using Tasks to Retain Runs in Azure Pipelines](../../pipelines/build/run-retention.md) diff --git a/docs/pipelines/policies/set-permissions.md b/docs/pipelines/policies/set-permissions.md index 8b574597df8..c01ffc0cec6 100644 --- a/docs/pipelines/policies/set-permissions.md +++ b/docs/pipelines/policies/set-permissions.md @@ -1,6 +1,5 @@ --- title: Add users to Azure Pipelines -ms.custom: seodec18 description: Add users to Azure Pipelines and set permissions. ms.assetid: DCEDB5E6-B6FB-4814-B3B9-F688094EA88B ms.topic: conceptual @@ -14,15 +13,15 @@ monikerRange: '<= azure-devops' Permissions for build and release pipelines are primarily set at the object-level for a specific build or release, or for select tasks, at the collection level. -You can manage security for different types of resources such as variable groups, secure files, and deployment groups by adding users or groups to that role. Project administrator can grant or restrict access to project resources. If you want to allow a team member to edit pipelines, you must be a project administrator in order to do so. +You can manage security for different types of resources such as variable groups, secure files, and deployment groups by granting permissions to that resource to users or groups. Project administrators can manage access to project resources. If you want to allow a team member to edit pipelines, you must be a project administrator in order to do so. + -::: moniker range="> tfs-2018" ## Add users to your project 1. Navigate to your project's summary page: `https://dev.azure.com/{your-organization}/{your-project}` -1. Select the **Invite** button to add a user to your project, and then fill out the required fields. Select **Add** when you are done. +1. Select the **Invite** button to add a user to your project, and then fill out the required fields. Select **Add** when you're done. :::image type="content" source="media/project-invite-button.png" alt-text="Invite button"::: @@ -35,167 +34,25 @@ You can manage security for different types of resources such as variable groups > [!NOTE] > A security best practice is to only grant permissions to required users or groups. The **Contributors** group may be too broad in a given project. -To verify the permissions for your project's contributors, make sure you are a member of the **Build Administrators** group or the **Project Administrators** group. See [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) for more details. +To verify the permissions for your project's contributors, make sure you're a member of the **Build Administrators** group or the **Project Administrators** group. For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). -1. From within your project, select **Pipelines** > **Pipelines**. Select the **All** tab, and then select the more actions menu then **Manage security**. +1. From within your project, select **Pipelines** > **Pipelines**. Select the **All** tab, and then select the more actions menu than **Manage security**. :::image type="content" source="media/security-menu-item.png" alt-text="Manage pipeline security"::: 1. On the permissions dialog box, make sure the following **Contributors** permissions are set to Allow. - :::image type="content" source="media/builds-permissions-dialog-box.png" alt-text="Set up the contributors permissions"::: - -::: moniker-end - -::: moniker range="tfs-2018" - -## Set permissions for build pipelines - -1. From within your project, select **Build and Release**, and then select **Builds** to access your build pipelines. - - :::image type="content" source="media/build-release-tfs.png" alt-text="Access builds in TFS"::: - -1. Select **Security** to set the permissions for all build pipelines. - - :::image type="content" source="media/set-build-release-permissions/open-all-build-definitions-security.png" alt-text="Access all builds security permissions"::: - - To set permissions for a specific build pipeline, select the context menu for that build and select **Security**. - - :::image type="content" source="media/set-build-release-permissions/set-build-permission-open-dialog.png" alt-text="Configure build permissions"::: - -1. Choose the group you want to set permissions for, and then change the permission setting to grant or restrict access. In the following example, we change the contributors permission to allow editing build definitions. - - :::image type="content" source="media/set-build-release-permissions/set-build-permission-dialog.png" alt-text="Contributors permissions - allow editing build definitions"::: - -1. Select **Save changes** when you are done. - -## Set permissions for release pipelines - -1. From within your project, select **Build and Release**, and then select **Releases** to access your release pipelines. - - :::image type="content" source="media/set-build-release-permissions/release-pipelines-tfs.png" alt-text="Access release pipelines TFS"::: - -1. Select the context menu for **All release definitions**, and then select **Security**. - - :::image type="content" source="media/set-build-release-permissions/all-releases-security.png" alt-text="All security releases"::: - -1. Choose the group you want to set permissions for, and then change the permission setting to grant or restrict access. In the following example, we change the contributors permission to prohibit the deletion of release definitions. - - :::image type="content" source="media/set-build-release-permissions/set-release-permission-dialog.png" alt-text="Configure permissions for release pipelines"::: - -1. Select **Save changes** when you are done. - - - - - -::: moniker-end - -::: moniker range="tfs-2018" - -## Manage Library roles for variable groups, secure files, and deployment groups - -Permissions for variable groups, secure files, and deployment groups are managed by roles. Setting up permissions is similar for all the three different types. **Variable groups** and **Secure files** permissions are configured from **Build and Release** > **Library** while **Deployment groups** permissions are set from **Build and Release** > **Deployment groups**. - -In the following example, we will configure permissions for variable groups. - -1. From within your project, select **Build and Release**, and then select **Library** then **Variable groups**. - - :::image type="content" source="media/set-build-release-permissions/open-variable-group-all-security.png" alt-text="Library - variable groups"::: - - If you want to manage the permissions for a specific variable group, select the ellipsis for that variable group and then select **Security**. - - :::image type="content" source="media/set-build-release-permissions/open-variable-group-specific-security.png" alt-text="Configure permission for one variable group"::: - -1. Add the user or group and choose the role you want them to have. - - :::image type="content" source="media/set-build-release-permissions/library-security-role-dialog-add-user.png" alt-text="add user or group and set roles"::: - -1. Select **Add** when you are done. - -::: moniker-end + ::: moniker range="azure-devops" -::: moniker range="tfs-2018" - - - -## Manage task group permissions - -Permissions for task groups are subject to a hierarchical model. You use task groups to encapsulate a sequence of tasks already defined in a build or a release pipeline into a single reusable task. - -1. From within your project, select **Build and Release**, and then select **Task groups**. - - :::image type="content" source="media/set-build-release-permissions/open-task-group-all-security.png" alt-text="access task groups permissions"::: - - If you want to manage the permissions for a specific task group, select the ellipsis for that task group and then select **Security**. - -1. Add the user or group and then set the permissions you want them to have. - - :::image type="content" source="media/set-build-release-permissions/task-group-security-dialog.png" alt-text="Set up task groups permissions"::: - -1. Select **Save changes** when you are done. - -::: moniker-end - -::: moniker range="tfs-2018" - - - -## Manage permissions for build administrators group - -1. From within your project, select the gear icon button ![gear icon](../../media/icons/gear_icon.png), and then select **Collection settings**. - -1. Select **Security**, and then select **Project Collection Build Administrators**. In this example, we want to allow the usage of build resources. - - :::image type="content" source="media/set-build-release-permissions/set-build-collection-level-permission-dialog.png" alt-text="Configure the build administrators group permissions"::: - -1. Select **Save changes** when you are done. - -::: moniker-end - -::: moniker range="tfs-2018" - -## Manage permissions for service connections - -You can set up permissions for service connections or agent pools by adding users or groups to a specific role. You will need to be a member of the Project Administrator group to manage the permissions for these resources. - -In the following example, we will add an Administrator to a service connection. - -1. From within your project, select the gear icon button ![gear icon](../../media/icons/gear_icon.png), and then select **Project settings**. - -1. Select **Services**, and then select the service connection that you want to manage. Select **Roles** to add a new role. - - :::image type="content" source="media/manage-roles/open-services-roles.png" alt-text="Select service roles"::: - -1. Add the user or group and choose the role you want them to have. - - :::image type="content" source="media/manage-roles/add-user-role-endpoint-service.png" alt-text="Add a new role"::: - -1. Select **Add** when you are done. - -::: moniker-end - -::: moniker range=">= tfs-2018 <= tfs-2018" - -## Manage permissions for deployment pools - -You can set up permissions for deployment pools by adding users or groups to a specific role. You will need to be a member of the Project Collection Administrator group to manage the pool's permissions. - -In the following example, we will add an Administrator role to all deployment pools. - -1. From within your project, select the gear icon button ![gear icon](../../media/icons/gear_icon.png), and then select **Project settings**. - -1. Select **Deployment Pools**, and then select **Security** to manage permissions for all deployment pools. - - :::image type="content" source="media/manage-roles/open-security-deployment-pools.png" alt-text="Manage permissions for all deployment pools"::: + :::image type="content" source="media/builds-permissions-dialog-box.png" alt-text="Set up the contributors permissions"::: -1. Add the user or group and choose the role you want them to have. + ::: moniker-end - :::image type="content" source="media/manage-roles/add-user-role-deployment-pool.png" alt-text="Add an administrator to all deployment pools"::: + ::: moniker range="< azure-devops" -1. Select **Add** when you are done. + :::image type="content" source="media/builds-permissions-dialog-box-server.png" alt-text="Set up the contributors permissions"::: -::: moniker-end + ::: moniker-end ## Related articles diff --git a/docs/pipelines/process/about-resources.md b/docs/pipelines/process/about-resources.md index 7f246d88a91..3131aec5a20 100644 --- a/docs/pipelines/process/about-resources.md +++ b/docs/pipelines/process/about-resources.md @@ -1,10 +1,10 @@ --- title: About pipeline resources -ms.custom: seodec18, contperf-fy21q4, pipelinesresourcesrefresh +ms.custom: pipelinesresourcesrefresh description: What are resources? ms.topic: conceptual -ms.date: 07/27/2022 -monikerRange: '>= azure-devops-2019' +ms.date: 11/06/2023 +monikerRange: "<=azure-devops" --- # About resources for Azure Pipelines @@ -34,7 +34,7 @@ How a resource gets used in a pipeline depends on the type of pipeline and type For YAML pipelines: -* Service connections and secure files are directly used as inputs to tasks and don't need to be pre-declared. +* Service connections and secure files are directly used as inputs to tasks and don't need to be predeclared. * Variable groups use the `group` syntax. * Pipelines and repositories use the `resources` syntax. diff --git a/docs/pipelines/process/access-tokens.md b/docs/pipelines/process/access-tokens.md index c8d13f1048e..11653d8581f 100644 --- a/docs/pipelines/process/access-tokens.md +++ b/docs/pipelines/process/access-tokens.md @@ -2,7 +2,6 @@ title: Understand job access tokens description: Access repositories, artifacts and other resources from pipelines ms.topic: reference -ms.custom: seodec18 ms.author: vijayma author: vijayma ms.date: 06/30/2022 @@ -13,10 +12,6 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - At run-time, each job in a pipeline may access other resources in Azure DevOps. For example, a job may: - Check out source code from a Git repository - Add a tag to the repository @@ -81,14 +76,6 @@ Enable one or more of the following settings. Enabling these settings are recomm ::: moniker-end -::: moniker range="<= azure-devops-2019" - -If you use Azure DevOps Server 2019, then all YAML jobs run with the job authorization scope set to **collection**. In other words, these jobs have access to all repositories in your project collection. You cannot change this in Azure DevOps Server 2019. - -YAML pipelines are not available in TFS. - -::: moniker-end - # [Classic](#tab/classic/) ::: moniker range=">=azure-devops-2020" @@ -148,17 +135,6 @@ To set job authorization scope for a specific pipeline: ::: moniker-end -::: moniker range="<= azure-devops-2019" - -Job authorization scope can be set for each pipeline. To set this scope: - -- Navigate to the pipeline in the **Pipelines** page. -- Select **Edit** to edit the pipeline. -- In the **Options** tab, select **Project collection** or **Current project** for **Build job authorization scope**. -- Save the build pipeline. - -::: moniker-end - --- >[!NOTE] @@ -244,7 +220,7 @@ To update the permissions of the job access token: - Make any changes to the non-pipelines-related permissions for this account. - Since **Your-project-name Build Service (your-collection-name)** is a user in your organization or collection, you can add this account explicitly to any resource - for e.g., to a feed in Azure Artifacts. -:::moniker range=">=azure-devops-2019" +:::moniker range="<=azure-devops" @@ -281,7 +257,7 @@ In this example, the `fabrikam-tailspin/SpaceGameWeb` project-scoped build ident :::moniker-end -:::moniker range=">=azure-devops-2019 <= azure-devops-2020" +:::moniker range="=azure-devops-2020" 3. Choose the **+** icon, start to type in the name **SpaceGameWeb**, and select the **SpaceGameWeb Build Service** account. ![Add user for repository access.](media/access-tokens/add-build-service-user.png) @@ -293,7 +269,7 @@ In this example, the `fabrikam-tailspin/SpaceGameWeb` project-scoped build ident ![Screenshot of how to add a user for repository access.](media/access-tokens/search-for-user.png) :::moniker-end -:::moniker range=">=azure-devops-2019" +:::moniker range="<=azure-devops" 4. Grant *Read* permissions for that user. @@ -314,25 +290,18 @@ In this example, the `fabrikam-tailspin/SpaceGameWeb` project-scoped build ident ## FAQ -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" ### How do I determine the job authorization scope of my YAML pipeline? :::moniker-end - :::moniker range="azure-devops" - If your project is a public project, the job authorization scope is always **project** regardless of any other settings. :::moniker-end -:::moniker range="azure-devops-2019" - -All YAML pipelines in Azure DevOps Server 2019 run under **collection** job authorization scope. - -:::moniker-end - :::moniker range="azure-devops-2020" * Check the Pipeline settings under your Azure DevOps **Organization settings**: @@ -361,14 +330,6 @@ All YAML pipelines in Azure DevOps Server 2019 run under **collection** job auth :::moniker-end -:::moniker range="= azure-devops-2020" --- @@ -16,12 +15,28 @@ monikerRange: ">= azure-devops-2020" A pipeline is made up of stages. A pipeline author can control whether a stage should run by defining [conditions](conditions.md) on the stage. Another way to control if and when a stage should run is through **approvals and checks**. - Pipelines rely on resources such as environments, service connections, agent pools, variable groups, and secure files. Checks enable the _resource owner_ to control if and when a stage in any pipeline can consume a resource. As an owner of a resource, you can define checks that must be satisfied before a stage consuming that resource can start. For example, a _manual approval check_ on an [environment](environments.md) would ensure that deployment to that environment only happens after the designated user(s) has reviewed the changes being deployed. +Approvals and other checks aren't defined in the yaml file. Users modifying the pipeline yaml file can't modify the checks performed before start of a stage. Administrators of resources manage checks using the web interface of Azure Pipelines. -A stage can consist of many jobs, and each job can consume several resources. Before the execution of a stage can begin, all checks on all the resources used in that stage must be satisfied. Azure Pipelines pauses the execution of a pipeline prior to each stage, and waits for all pending checks to be completed. Checks are reevaluated based on the retry interval specified in each check. If all checks aren't successful until the **timeout** specified, then that stage is not executed. -If any of the checks terminally fails (for example, if you reject an approval on one of the resources), then that stage is not executed. +Pipelines rely on resources such as environments, service connections, agent pools, variable groups, and secure files. Checks enable the _resource owner_ to control if and when a stage in any pipeline can consume a resource. As an owner of a resource, you can define checks that must be satisfied before a stage consuming that resource can start. For example, a _manual approval check_ on an [environment](environments.md) ensures that deployment to that environment only happens after the designated user reviews the changes being deployed. -Approvals and other checks aren't defined in the yaml file. Users modifying the pipeline yaml file can't modify the checks performed before start of a stage. Administrators of resources manage checks using the web interface of Azure Pipelines. +A stage can consist of many jobs, and each job can consume several resources. Before the execution of a stage can begin, all checks on all the resources used in that stage must be satisfied. Azure Pipelines pauses the execution of a pipeline before each stage, and waits for all pending checks to be completed. + +There are five categories of approvals and checks and they run in the order they were created within each category. Checks are reevaluated based on the retry interval specified in each check. If all checks aren't successful until the **timeout** specified, then that stage isn't executed. +If any of the checks terminally fails (for example, if you reject an approval on one of the resources), then that stage isn't executed. + +::: moniker range=">=azure-devops-2022" +You can retry a stage when approvals and checks time out. +:::moniker-end + +Static checks run first and then pre-check approvals run. The categories in order are: + +1. Static checks: Branch control, Required template, and Evaluate artifact +2. Pre-check approvals +3. Dynamic checks: Approval, Invoke Azure Function, Invoke REST API, Business Hours, Query Azure Monitor alerts +4. Post-check approvals +5. Exclusive lock + +You can also see the execution order on the **Approvals and checks** tab. > [!IMPORTANT] > Checks can be configured on environments, service connections, repositories, variable groups, secure files, and agent pools. @@ -30,23 +45,52 @@ Approvals and other checks aren't defined in the yaml file. Users modifying the ## Approvals -You can manually control when a stage should run using approval checks. This check is commonly used to control deployments to production environments. +You can manually control when a stage should run using approval and checks. This check is commonly used to control deployments to production environments. -1. In your Azure DevOps project, go to the resource (for example, environment) that needs to be protected. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -2. Navigate to **Approvals and Checks** for the resource. +1. Select **Pipelines** > **Environments**, and then select your environment. -:::image type="content" source="media/checks/approvals-and-checks.png" alt-text="Approvals and Checks on environment."::: - -3. Select **Create**, provide the approvers and an optional message, and select **Create** again to complete the addition of the manual approval check. +1. Select the **Approvals and checks** tab, and then select the **+** sign to add a new check. + + :::image type="content" source="media/add-approvals-and-checks.png" alt-text="A screenshot showing how to add approvals and checks in Azure Pipelines."::: + +1. Select **Approvals**, and then select **Next**. + +1. Add users or groups as your designated **Approvers**, and, if desired, provide **instructions for the approvers**. Specify if you want to permit or restrict approvers from approving their own runs, and specify your desired **Timeout**. If approvals aren't completed within the specified Timeout, the stage is marked as skipped. + +1. Select **Create** when you're done. + + :::image type="content" source="media/create-new-approval.png" alt-text="A screenshot showing how to create a new approval."::: + +1. Once the approval check is triggered, a prompt window, as shown in the following example, is presented in the user interface. This window provides the option for approvers to either reject or approve the run, along with any accompanying instructions. + + :::image type="content" source="media/approval-prompt.png" alt-text="A screenshot showing the approval prompt window."::: + +The list of users who can review an Approval is fixed at the time approvals & checks start running. That is, changes to the list of users and groups of an approval check done after checks start executing aren't picked up. + +> [!NOTE] +> If a group is designated as an approver, only one user within the group needs to approve for the run to proceed. + +::: moniker range=">azure-devops-2022" + +### Deferred approvals -You can add multiple approvers to an environment. These approvers can be individual users or groups of users. When a group is specified as an approver, only one of the users in that group needs to approve for the run to move forward. +There are situations when the time when an approval is given and the time the deployment should start don't match. For example, you might want to wait to deploy a new release until a low-traffic time in the evening. -Using the advanced options, you can configure minimum number of approvers to complete the approval. A group is considered as one approver. +To address this scenario, you can defer an approval and set the time the approval becomes effective. -You can also restrict the user who requested (initiated or created) the run from completing the approval. This option is commonly used for segregation of roles amongst the users. +1. Select **Defer approval**. -When you run a pipeline, the execution of that run pauses before entering a stage that uses the environment. Users configured as approvers must review and approve or reject the deployment. If you have multiple runs executing simultaneously, you must approve or reject each of them independently. If all required approvals aren't completed within the **Timeout** specified for the approval and all other checks succeed, the stage is marked as skipped. + :::image type="content" source="media/defer-approval.png" alt-text="Screenshot of defer approval option when you respond to an approval request. "::: + +1. Set the approval time. + + :::image type="content" source="media/defer-approval-set-time.png" alt-text="Screenshot of setting the time for an approval. "::: + +You'll see the approval in the **Checks** panel as a pre-approval. The approval is effective at the set time. + +::: moniker-end ## Branch control @@ -58,9 +102,9 @@ To define the branch control check: 2. Navigate to **Approvals and Checks** for the resource. -3. Choose the **Branch control** check and provide a comma-separated list of allowed branches. You can mandate that the branch should have protection enabled. You can also define the behavior of the check in case protection status for one of the branches isn't known. +3. Choose the **Branch control** check and provide a comma-separated list of allowed branches. You can mandate that the branch should have protection enabled. You can also define the behavior of the check if the protection status for one of the branches isn't known. A branch is considered protected if at least one policy has been applied (including policies applied at the repository level). -:::image type="content" source="media/checks/branch-control-check.png" alt-text="Configuring branch control check."::: + :::image type="content" source="media/checks/branch-control-check.png" alt-text="Configuring branch control check."::: At run time, the check would validate branches for all linked resources in the run against the allowed list. If any of the branches doesn't match the criteria, the check fails and the stage is marked failed. @@ -79,27 +123,27 @@ The check fails if execution of the stage doesn't start within the **Timeout** p ## Invoke Azure function Azure functions are the serverless computation platform offered by Azure. With Azure functions, you can run small pieces of code (called "functions") without worrying about application infrastructure. -Given the high flexibility, Azure functions provide a great way to author your own checks. You include the logic of the check-in Azure function such that each execution is triggered on http request, has a short execution time and returns a response. While defining the check, you can parse the response body to infer if the check is successful. The evaluation can be repeated periodically using the Time between evaluations setting in control options. [Learn More](/azure/devops/pipelines/tasks/reference/azure-function-v1) +Given the high flexibility, Azure functions provide a great way to author your own checks. You include the logic of the check-in Azure function such that each execution is triggered on http request, has a short execution time, and returns a response. While defining the check, you can parse the response body to infer if the check is successful. The evaluation can be repeated periodically using the Time between evaluations setting in control options. [Learn More](/azure/devops/pipelines/tasks/reference/azure-function-v1) :::image type="content" source="media/checks/azure-function-check.png" alt-text="Configuring Azure function check."::: -The checks fail if the stage has not started execution within the specified **Timeout** period. See [Azure Function App task](/azure/devops/pipelines/tasks/reference/azure-function-app-v1) for more details. +If your check doesn't succeed within the configured **Timeout**, the associated stage is skipped. Stages depending on it are skipped as well. For more information, see the [Azure Function App task](/azure/devops/pipelines/tasks/reference/azure-function-app-v1). > [!NOTE] -> User defined pipeline variables are not accessible to the check. You can only access the predefined variables and variables from the linked variable group in the request body. +> User defined pipeline variables are accessible to the check starting with [Sprint 215](/azure/devops/release-notes/2023/sprint-215-update#variables-as-inputs-in-checks). -[Read more about the recommended way to use Invoke Azure Function checks](invoke-checks.md). +[Read more about the recommended way to use invoke Azure function checks](invoke-checks.md). Checks [need to follow specific rules](invoke-checks.md#check-compliance) depending on their mode and the number of retries to be compliant. ## Invoke REST API Invoke REST API check enables you to integrate with any of your existing services. Periodically, make a call to a REST API and continue if it returns a successful response. [Learn More](/azure/devops/pipelines/tasks/reference/invoke-rest-api-v1) -The evaluation can be repeated periodically using the **Time between evaluations** setting in control options. The checks fail if the stage has not started execution within the specified **Timeout** period. See [Invoke REST API task](/azure/devops/pipelines/tasks/reference/invoke-rest-api-v1) for more details. +The evaluation can be repeated periodically using the **Time between evaluations** setting in control options. If your check doesn't succeed within the configured **Timeout**, the associated stage is skipped. Stages depending on it are skipped as well. For more information, see [Invoke REST API task](/azure/devops/pipelines/tasks/reference/invoke-rest-api-v1). > [!NOTE] -> User defined pipeline variables are not accessible to the check. You can only access the predefined variables and variables from the linked variable group in the request body. +> User defined pipeline variables are accessible to the check starting with [Sprint 215](/azure/devops/release-notes/2023/sprint-215-update#variables-as-inputs-in-checks). -[Read more about the recommended way to use Invoke REST API checks](invoke-checks.md). +[Read more about the recommended way to use invoke REST API checks](invoke-checks.md). ## Query Azure Monitor Alerts Azure Monitor offers visualization, query, routing, alerting, autoscale, and automation on data from the Azure infrastructure and each individual Azure resource. Alerts are a standard means to detect issues with the health of infrastructure or application, and take corrective actions. @@ -111,7 +155,7 @@ The evaluation is repeated after **Time between evaluations** setting in control ## Required template -With the required template check, you can enforce pipelines to use a specific YAML template. When this check is in place, a pipeline will fail if it doesn't extend from the referenced template. +With the required template check, you can enforce pipelines to use a specific YAML template. When this check is in place, a pipeline fails if it doesn't extend from the referenced template. To define a required template approval: @@ -128,35 +172,65 @@ To define a required template approval: * **Path to required template**: The name of your template. -You can have multiple required templates for the same service connection. In this example, the required template is `required.yml`. +You can have multiple required templates for the same service connection. In this example, the required template is `production_template.yaml`. :::image type="content" source="media/checks/required-template.png" alt-text="Configuring required template check."::: +::: moniker range=">=azure-devops-2022" + + +## Disable a check + +When debugging a check, you might want to temporarily disable and then enable it again. To disable or enable a check: + +1. In your Azure DevOps project, go to the resource with a check. + +2. Open the **Approvals and Checks** tab. + +3. In the contextual menu, select **Disable** or **Enable**. + + :::image type="content" source="media/checks/disable-check-approvals.png" alt-text="Screenshot of disable a check option."::: + + +## Bypass a check + +In some circumstances such as a hotfix deployment, you may need to bypass a check. You can only bypass a check only if you have the administrator permission for the resource where the check is defined. + +To bypass an approval, business hours, invoke Azure function, or invoke REST API check, select **Bypass check** when the resource is waiting for review. Here's an example of bypassing the business hours check. + +:::image type="content" source="media/bypass-business-hours-check.png" alt-text="Screenshot of bypass business hours check option. "::: + +When you bypass a check, you'll see who bypassed the check in the checks panel. + +:::image type="content" source="media/check-bypass-example.png" alt-text="Screenshot of log of bypassed check. "::: + +::: moniker-end + ## Evaluate artifact -You can evaluate artifact(s) to be deployed to an environment against custom policies. +You can evaluate artifacts to be deployed to an environment against custom policies. > [!NOTE] > Currently, this works with container image artifacts only -To define a custom policy evaluation over the artifact(s), follow the below steps. +To define a custom policy evaluation over the artifacts, follow the below steps. 1. In your Azure DevOps Services project, navigate to the environment that needs to be protected. Learn more about [creating an environment](environments.md). -:::image type="content" source="media/checks/environments.png" alt-text="View environment."::: + :::image type="content" source="media/checks/environments.png" alt-text="View environment."::: 2. Navigate to **Approvals and checks** for the environment. -:::image type="content" source="media/checks/approvals-and-checks.png" alt-text="Add checks to environment."::: + :::image type="content" source="media/checks/approvals-and-checks.png" alt-text="Add checks to environment."::: 3. Select **Evaluate artifact**. -:::image type="content" source="media/checks/evaluate-artifact.png" alt-text="Add evaluate artifact check."::: + :::image type="content" source="media/checks/evaluate-artifact.png" alt-text="Add evaluate artifact check."::: -4. Paste the policy definition and click **Save**. [See more](artifact-policy.md) about writing policy definitions. +4. Paste the policy definition and select **Save**. [See more](artifact-policy.md) about writing policy definitions. -:::image type="content" source="media/checks/policy-definition.png" alt-text="Add policy definition."::: + :::image type="content" source="media/checks/policy-definition.png" alt-text="Add policy definition."::: When you run a pipeline, the execution of that run pauses before entering a stage that uses the environment. The specified policy is evaluated against the available image metadata. The check passes when the policy is successful and fails otherwise. The stage is marked failed if the check fails. @@ -182,17 +256,20 @@ You can also see the complete logs of the policy checks from the pipeline view. :::moniker range="> azure-devops-2020" -The **exclusive lock** check allows only a single run from the pipeline to proceed. All stages in all runs of that pipeline that use the resource are paused. When the stage using the lock completes, then another stage can proceed to use the resource. Also, only one stage will be allowed to continue. +The **exclusive lock** check allows only a single run from the pipeline to proceed and can be set at the stage or pipeline level. All stages in all runs of that pipeline that use the resource are paused. When the stage using the lock completes, then another stage can proceed to use the resource. Also, only one stage is allowed to continue. -The behavior of any other stages that attempt to take a lock is configured by the `lockBehavior` value that is configured in the YAML file for the pipeline. +The `lockBehavior` property determines how other stages handle locks. When you specify the `lockBehavior` property for a stage, a lock is automatically created for that stage. There are two possible `lockBehavior` values: * `runLatest` - Only the latest run acquires the lock to the resource. `runLatest` is the default if no `lockBehavior` is specified. -* `sequential` - All runs acquire the lock sequentially to the protected resource. +* `sequential` - All runs acquire the lock to the protected resource sequentially. -To use exclusive lock check with `sequential` deployments or `runLatest`, follow these steps: +To use an exclusive lock check with `sequential` deployments or `runLatest`, follow these steps: + + 1. Enable the exclusive lock check on the environment (or another protected resource). The exclusive lock option is an available check. + + :::image type="content" source="media/exclusive-lock-option.png" alt-text="Screenshot of exclusive lock option Approvals tab. "::: - 1. Enable the exclusive lock check on the environment (or another protected resource). - 2. In the YAML file for the pipeline, specify a property called `lockBehavior`. This can be specified for the whole [pipeline](/azure/devops/pipelines/yaml-schema/pipeline) or for a given [stage](/azure/devops/pipelines/yaml-schema/stages-stage): + 1. In the YAML file for the pipeline, specify a property called `lockBehavior`. This can be specified for the whole [pipeline](/azure/devops/pipelines/yaml-schema/pipeline) or for a given [stage](/azure/devops/pipelines/yaml-schema/stages-stage): Set on a stage: @@ -217,7 +294,7 @@ stages: - script: Hey! ``` -If you don't specify a `lockBehavior`, the default value of `runLatest` is used. +If you don't specify a `lockBehavior` and a lock is set on a resource, the default value of `runLatest` is used. :::moniker-end @@ -226,7 +303,7 @@ If you don't specify a `lockBehavior`, the default value of `runLatest` is used. The **exclusive lock** check allows only a single run from the pipeline to proceed. All stages in all runs of that pipeline that use the resource are paused. When the stage using the lock completes, then another stage can proceed to use the resource. -Also, only one stage will be allowed to continue. +Also, only one stage is allowed to continue. Any other stages that tried to take the lock will be canceled. :::moniker-end @@ -244,25 +321,25 @@ More details are available [here](../release/approvals/servicenow.md). A stage can consist of many jobs, and each job can consume several resources. Before the execution of a stage can begin, all checks on all the resources used in that stage must be satisfied. Azure Pipelines pauses the execution of a pipeline prior to each stage, and waits for all pending checks to be completed. -A single final negative decision causes the pipeline to be denied access and the stage to fail. The decisions of all Approvals and Checks except for Invoke Azure Function / REST API and [Exclusive lock](#exclusive-lock) are final. +A single final negative decision causes the pipeline to be denied access and the stage to fail. The decisions of all approvals and checks except for invoke Azure function / REST API and [Exclusive lock](#exclusive-lock) are final. You can rerun successful invoke Azure function / REST API checks. -When using Invoke Azure Function / REST API checks in the [recommended way](invoke-checks.md), their access decisions are also final. +When using invoke Azure function / REST API checks in the [recommended way](invoke-checks.md), their access decisions are also final. -When you specify _Time between evaluations_ for an Invoke Azure Function / REST API check to be non-zero, the check's decision is non-final. This scenario is worth exploring. +When you specify _Time between evaluations_ for an invoke Azure function / REST API check to be non-zero, the check's decision is non-final. This scenario is worth exploring. -Let us look at an example. Imagine your YAML pipeline has a stage that uses a Service Connection. This Service Connection has two checks configured for it: +Let us look at an example. Imagine your YAML pipeline has a stage that uses a service connection. This service connection has two checks configured for it: 1. An asynchronous check, named _External Approval Granted_, that verifies that [an external approval is given](invoke-checks.md#external-approval-must-be-granted) and is configured in the recommended way. 1. A synchronous check, named _Deployment Reason Valid_, that verifies that [the deployment reason is valid](invoke-checks.md#deployment-reason-must-be-valid) and for which you set the _Time between evaluations_ to 7 minutes. A possible checks execution is shown in the following diagram. -:::image type="content" source="media/checks/checks-timeline.png" alt-text="Diagram that shows the timeline of an asynchronous and a synchronous checks' executions."::: +:::image type="content" source="media/checks/checks-timeline.png" alt-text="Diagram that shows the timeline of an asynchronous and a synchronous check's executions."::: In this execution: -- Both checks, _External Approval Granted_ and _Deployment Reason Valid_, are invoked at the same time. _Deployment Reason Valid_ fails immediately, but because _External Approval Granted_ is pending, it will be retried. +- Both checks, _External Approval Granted_ and _Deployment Reason Valid_, are invoked at the same time. _Deployment Reason Valid_ fails immediately, but because _External Approval Granted_ is pending, it is retried. - At minute 7, _Deployment Reason Valid_ is retried and this time it passes. - At minute 15, _External Approval Granted_ calls back into Azure Pipelines with a successful decision. Now, both checks pass, so the pipeline is allowed to continue to deploy the stage. -Let us look at another example, involving two synchronous checks. Assume your YAML pipeline has a stage that uses a Service Connection. This Service Connection has two checks configured for it: +Let us look at another example, involving two synchronous checks. Assume your YAML pipeline has a stage that uses a service connection. This service connection has two checks configured for it: 1. A synchronous check, named _Sync Check 1_, for which you set the _Time between evaluations_ to 5 minutes. 1. A synchronous check, named _Sync Check 2_, for which you set the _Time between evaluations_ to 7 minutes. @@ -270,25 +347,25 @@ A possible checks execution is shown in the following diagram. :::image type="content" source="media/checks/checks-timeline-sync.png" alt-text="Diagram that shows the timeline of two synchronous checks' executions."::: In this execution: -- Both checks, _Sync Check 1_ and _Sync Check 2_, are invoked at the same time. _Sync Check 1_ passes, but it will be retried, because _Sync Check 2_ fails. -- At minute 5, _Sync Check 1_ is retried but fails, so it will be retried. -- At minute 7, _Sync Check 2_ is retried and succeeds. The pass decision is valid for 7 minutes. If _Sync Check 1_ doesn't pass in this time interval, _Sync Check 2_ will be retried. -- At minute 10, _Sync Check 1_ is retried but fails, so it will be retried. -- At minute 14, _Sync Check 2_ is retried and succeeds. The pass decision is valid for 7 minutes. If _Sync Check 1_ doesn't pass in this time interval, _Sync Check 2_ will be retried. +- Both checks, _Sync Check 1_ and _Sync Check 2_, are invoked at the same time. _Sync Check 1_ passes, but it is retried, because _Sync Check 2_ fails. +- At minute 5, _Sync Check 1_ is retried but fails, so it is retried. +- At minute 7, _Sync Check 2_ is retried and succeeds. The pass decision is valid for 7 minutes. If _Sync Check 1_ doesn't pass in this time interval, _Sync Check 2_ is retried. +- At minute 10, _Sync Check 1_ is retried but fails, so it is retried. +- At minute 14, _Sync Check 2_ is retried and succeeds. The pass decision is valid for 7 minutes. If _Sync Check 1_ doesn't pass in this time interval, _Sync Check 2_ is retried. - At minute 15, _Sync Check 1_ is retried and succeeds. Now, both checks pass, so the pipeline is allowed to continue to deploy the stage. -Let us look at an example that involves an Approval and a synchronous check. Imagine you configured a synchronous check and an Approval for a Service Connection with a _Time between evaluations_ of 5 minutes. Until the approval is given, your check will run every 5 minutes, regardless of decision. +Let us look at an example that involves an approval and a synchronous check. Imagine you configured a synchronous check and an approval for a service connection with a _Time between evaluations_ of 5 minutes. Until the approval is given, your check runs every 5 minutes, regardless of decision. ## FAQ -### The checks defined did not start. What happened? +### The checks defined didn't start. What happened? The evaluation of checks starts once the stage conditions are satisfied. You should confirm run of the stage started after the checks were added on the resource and that the resource is consumed in the stage. ### How can I use checks for scheduling a stage? -Using the business hours check, you can control the time for start of stage execution. You can achieve the same behavior as [predefined schedule on a stage](../release/triggers.md?#stage-scheduled-triggers) in designer releases. +Using the business hours check, you can control the time for start of stage execution. You can achieve the same behavior as [predefined schedule on a stage](../release/triggers.md#scheduled-release-triggers) in designer releases. ### How can I take advance approvals for a stage scheduled to run in future? -This scenario can be enabled +This scenario can be enabled. 1. The business hours check enables all stages deploying to a resource to be scheduled for execution between the time window 2. When approvals are configured on the same resource, the stage would wait for approvals before starting. 3. You can configure both the checks on a resource. The stage would wait on approvals and business hours. It would start in the next scheduled window after approvals are complete. @@ -301,3 +378,7 @@ Using the Invoke REST API check, you can add a check to wait on the API in the s By default, only predefined variables are available to checks. You can use a linked variable group to access other variables. The output variable from the previous stage can be written to the variable group and accessed in the check. +## Learn more +- [Invoke Azure Function / REST API checks](invoke-checks.md) +- [Approvals and Checks REST API](/rest/api/azure/devops/approvalsandchecks/) +- [Approvals Query REST API](/rest/api/azure/devops/approvalsandchecks/approvals/query) diff --git a/docs/pipelines/process/artifact-policy.md b/docs/pipelines/process/artifact-policy.md index 1d09b1c5740..1c1a0cd766a 100644 --- a/docs/pipelines/process/artifact-policy.md +++ b/docs/pipelines/process/artifact-policy.md @@ -4,8 +4,8 @@ description: Ensure artifacts adhere to custom policies ms.topic: conceptual ms.assetid: C7E2BE58-2B01-414D-9A3A-67FA68637B51 ms.manager: shashban -ms.author: shashban -author: shashankbansal +ms.author: sandrica +author: silviuandrica ms.date: 11/05/2019 monikerRange: 'azure-devops' --- diff --git a/docs/pipelines/process/conditions.md b/docs/pipelines/process/conditions.md index 9a4b89e77cd..9a021c314d8 100644 --- a/docs/pipelines/process/conditions.md +++ b/docs/pipelines/process/conditions.md @@ -1,50 +1,54 @@ --- -title: Conditions -ms.custom: seodec18 -description: Learn about how you can write custom conditions in Azure Pipelines. +title: Pipeline conditions +description: Learn about how to specify the conditions under which each Azure Pipelines stage, job, or step runs. ms.topic: conceptual ms.assetid: C79149CC-6E0D-4A39-B8D1-EB36C8D3AB89 -ms.date: 02/17/2023 +ms.date: 06/27/2024 monikerRange: '<= azure-devops' --- -# Specify conditions +# Pipeline conditions [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can specify the conditions under which each stage, job, or step runs. -By default, a job or stage runs if it doesn't depend on any other job or stage, or if _all_ of the jobs or stages it depends on have completed and succeeded. This includes not only direct dependencies, but their dependencies as well, computed recursively. -By default, a step runs if nothing in its job has failed yet and the step immediately preceding it has finished. -You can customize this behavior by forcing a stage, job, or step to run even if a previous dependency fails or by specifying a custom condition. +This article describes the conditions under which an Azure Pipelines stage, job, or step runs, and how to specify different conditions. For more context on stages, jobs, and steps, see [Key concepts for Azure Pipelines](../get-started/key-pipelines-concepts.md). -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end +- By default, a job or stage runs if it doesn't depend on any other job or stage, or if all its dependencies completed and succeeded. This requirement applies not only to direct dependencies, but to their indirect dependencies, computed recursively. -#### [YAML](#tab/yaml/) -::: moniker range=">=azure-devops-2020" +- By default, a step runs if nothing in its job failed yet and the step immediately preceding it completed. -You can specify conditions under which a step, job, or stage will run. +You can override or customize this behavior by forcing a stage, job, or step to run even if a previous dependency fails, or by specifying a custom condition. + +> [!NOTE] +> This article discusses YAML pipeline capabilities. For Classic pipelines, you can specify some conditions under which tasks or jobs run in the **Control Options** of each task, and in the **Additional options** for a job in a release pipeline. + +## Conditions under which a stage, job, or step runs + +In the pipeline definition YAML, you can specify the following conditions under which a stage, job, or step runs: [!INCLUDE [include](includes/task-run-built-in-conditions.md)] -* Custom conditions +- Custom conditions. + +By default, stages, jobs, and steps run if all direct and indirect dependencies succeed. This status is the same as specifying `condition: succeeded()`. For more information, see [succeeded status function](expressions.md#succeeded). + +When you specify a `condition` property for a stage, job, or step, you overwrite the default `condition: succeeded()`. Specifying your own conditions can cause your stage, job, or step to run even if the build is canceled. Make sure the conditions you write take into account the state of the parent stage or job. -By default, steps, jobs, and stages run if all previous steps/jobs have succeeded. -It's as if you specified "condition: succeeded()" (see [Job status functions](expressions.md#job-status-functions)). +The following YAML example shows the `always()` and `failed()` conditions. The step in the first job runs even if dependencies fail or the build is canceled. In the second script task, `exit 1` forces the `Foo` job to fail. The second job runs only if the first job fails. ```yaml jobs: - job: Foo - steps: - script: echo Hello! - condition: always() # this step will always run, even if the pipeline is canceled - + condition: always() # this step runs, even if the build is canceled + - script: | + echo "This task will fail." + exit 1 - job: Bar dependsOn: Foo - condition: failed() # this job will only run if Foo fails + condition: failed() # this job runs only if Foo fails ``` -You can also use variables in conditions. +You can also set and use variables in conditions. The following example sets and uses an `isMain` variable to designate `main` as the `Build.SourceBranch`. ```yaml variables: @@ -66,50 +70,32 @@ stages: - script: echo $(isMain) ``` -Conditions are evaluated to decide whether to start a stage, job, or step. -This means that nothing computed at runtime inside that unit of work will be available. -For example, if you have a job that sets a variable using a runtime expression using `$[ ]` syntax, you can't use that variable in your custom condition. - -::: moniker-end +> [!IMPORTANT] +> Conditions are evaluated to determine whether to start a stage, job, or step. Therefore, nothing computed at runtime inside that unit of work is available. For example, if you have a job that sets a variable using a runtime expression with `$[ ]` syntax, you can't use that variable in a custom condition in that job. -::: moniker range="< azure-devops" -YAML isn't supported in TFS. -::: moniker-end +## Custom conditions -#### [Classic](#tab/classic/) +If the built-in conditions don't meet your needs, you can specify *custom conditions*. You write conditions as expressions in YAML pipeline definitions. -Inside the **Control Options** of each task, and in the **Additional options** for a job in a release pipeline, -you can specify the conditions under which the task or job will run. +The agent evaluates the expression beginning with the innermost function and proceeding outward. The final result is a boolean value that determines whether or not the task, job, or stage should run. For a full guide to the syntax, see [Expressions](expressions.md). -* * * - -> [!NOTE] -> When you specify your own `condition` property for a stage / job / step, you overwrite its default `condition: succeeded()`. This can lead to your stage / job / step running even if the build is cancelled. Make sure you take into account the state of the parent stage / job when writing your own conditions. +If any of your conditions make it possible for the task to run even after the build is canceled, specify a reasonable value for [cancel timeout](phases.md#timeouts) so that these tasks have enough time to complete after the user cancels a run. -## Enable a custom condition +## Condition outcomes when a build is canceled -If the built-in conditions don't meet your needs, then you can specify **custom conditions**. +Canceling a build doesn't mean that all its stages, jobs, or steps stop running. Which stages, jobs, or steps stop running depend on the conditions you specified, and at what point of the pipeline's execution you canceled the build. If a stage, job, or step's parent is skipped, the task doesn't run, regardless of its conditions. -Conditions are written as expressions in YAML pipelines. -The agent evaluates the expression beginning with the innermost function and works out its way. -The final result is a boolean value that determines if the task, job, or stage should run or not. -See the [expressions](expressions.md) article for a full guide to the syntax. +A stage, job, or step runs whenever its conditions evaluate to `true`. If your condition doesn't take into account the state of the task's parent, the task might run even if its parent is canceled. To control whether stages, jobs, or steps with conditions run when a build is canceled, make sure to include a [job status check function](expressions.md?view=azure-devops&preserve-view=true#job-status-functions) in your conditions. -Do any of your conditions make it possible for the task to run even after the build is canceled by a user? If so, then specify a reasonable value for [cancel timeout](phases.md#timeouts) so that these kinds of tasks have enough time to complete after the user cancels a run. +The following examples show the outcomes of various conditions set on stages, jobs, or steps when the build is canceled. -## Pipeline behavior when build is canceled +### Stage example 1 -When a build is canceled, it doesn't mean all its stages, jobs, or steps stop running. The decision depends on the stage, job, or step `conditions` you specified and at what point of the pipeline's execution you canceled the build. +In the following pipeline, by default `stage2` would depend on `stage1`, but `stage2` has a `condition` set to run whenever the source branch is `main`, regardless of `stage1` status. -If your condition doesn't take into account the state of the parent of your stage / job / step, then if the condition evaluates to `true`, your stage, job, or step will run, *even if* its parent is canceled. If its parent is skipped, then your stage, job, or step won't run. +If you queue a build on the `main` branch and cancel it while `stage1` is running, `stage2` still runs, because `eq(variables['Build.SourceBranch'], 'refs/heads/main')` evaluates to `true`. -Let's look at some examples. - -#### [Stages](#tab/stages/) - -In this pipeline, by default, `stage2` depends on `stage1` and `stage2` has a `condition` set. `stage2` only runs when the source branch is `main`. - -```yml +```yaml stages: - stage: stage1 jobs: @@ -124,11 +110,11 @@ stages: - script: echo 2 ``` -If you queue a build on the `main` branch, and you cancel it while `stage1` is running, `stage2` will still run, because `eq(variables['Build.SourceBranch'], 'refs/heads/main')` evaluates to `true`. +### Stage example 2 -In this pipeline, `stage2` depends on `stage1`. Job `B` has a `condition` set for it. +In the following pipeline, `stage2` depends on `stage1` by default. Job `B` in `stage2` has a `condition` set. If you queue a build on the `main` branch and cancel it while `stage1` is running, `stage2` doesn't run, even though it contains a job whose condition evaluates to `true`. -```yml +```yaml stages: - stage: stage1 jobs: @@ -143,9 +129,12 @@ stages: - script: echo 2 ``` -If you queue a build on the `main` branch, and you cancel it while `stage1` is running, `stage2` *won't* run, even though it contains a job `B` whose condition evaluates to `true`. The reason is because `stage2` has the default `condition: succeeded()`, which evaluates to `false` when `stage1` is canceled. Therefore, `stage2` is skipped, and none of its jobs run. +### Stage example 3 + +In the following pipeline, by default `stage2` depends on `stage1`, and the step inside job `B` has a `condition` set. + +If you queue a build on the `main` branch and cancel it while `stage1` is running, `stage2` doesn't run, even though it contains a step in job `B` whose condition evaluates to `true`. The reason is because `stage2` is skipped in response to `stage1` being canceled. -Say you have the following YAML pipeline. Notice that, by default, `stage2` depends on `stage1` and that `script: echo 2` has a `condition` set for it. ```yaml stages: - stage: stage1 @@ -161,11 +150,11 @@ stages: condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') ``` -If you queue a build on the `main` branch, and you cancel it while `stage1` is running, `stage2` *won't* run, even though it contains a step in job `B` whose condition evaluates to `true`. The reason is because `stage2` is skipped in response to `stage1` being canceled. +### Job example 1 + +In the following YAML pipeline, job `B` depends on job `A` by default, but job `B` has a `condition` set to run whenever the source branch is `main`. If you queue a build on the `main` branch and cancel it while job `A` is running, job `B` still runs, because `eq(variables['Build.SourceBranch'], 'refs/heads/main')` evaluates to `true`. -#### [Jobs](#tab/jobs/) -Say you have the following YAML pipeline. Notice that job `B` depends on job `A` and that job `B` has a `condition` set for it. -```yml +```yaml jobs: - job: A steps: @@ -177,12 +166,15 @@ jobs: - script: echo step 2.1 ``` -If you queue a build on the `main` branch, and you cancel it while job `A` is running, job `B` will still run, because `eq(variables['Build.SourceBranch'], 'refs/heads/main')` evaluates to `true`. +If you want job `B` to run only when job `A` succeeds and the build source is the `main` branch, your `condition` should be `and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))`. + +### Job example 2 -If you want job `B` to only run when job `A` succeeds *and* you queue the build on the `main` branch, then your `condition` should read `and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))`. +In the following pipeline, job `B` depends on job `A` by default. If you queue a build on the `main` branch and cancel it while job `A` is running, job `B` doesn't run, even though its step has a `condition` that evaluates to `true`. -In the following pipeline, `B` depends on `A`. -```yml +The reason is because job `B` evaluates to `false` when job `A` is canceled. Therefore, job `B` is skipped, and none of its steps run. + +```yaml jobs: - job: A steps: @@ -191,17 +183,16 @@ jobs: dependsOn: A steps: - script: echo step 2.1 - condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') - + condition: and(eq(variables['Build.SourceBranch'], 'refs/heads/main'), succeeded()) ``` -If you queue a build on the `main` branch, and you cancel the build when job `A` is executing, job `B` *won't* execute, even though `step 2.1` has a `condition` that evaluates to `true`. The reason is because job `B` has the default `condition: succeeded()`, which evaluates to `false` when job `A` is canceled. Therefore, job `B` is skipped, and none of its steps run. +### Step example -#### [Steps](#tab/steps/) +You can also have conditions on steps. -You can also have conditions on steps. In this pipeline, notice that step 2.3 has a `condition` set on it. +In the following pipeline, step 2.3 has a `condition` set to run whenever the source branch is `main`. If you queue a build on the `main` branch and cancel it while steps 2.1 or 2.2 are running, step 2.3 still runs, because `eq(variables['Build.SourceBranch'], 'refs/heads/main')` evaluates to `true`. -```yml +```yaml steps: - script: echo step 2.1 - script: echo step 2.2; sleep 30 @@ -209,91 +200,42 @@ steps: condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') ``` -If you queue a build on the `main` branch, and you cancel the build when steps 2.1 or 2.2 are executing, step 2.3 will still execute, because `eq(variables['Build.SourceBranch'], 'refs/heads/main')` evaluates to `true`. - -* * * - -To prevent stages, jobs, or steps with `conditions` from running when a build is canceled, make sure you consider their parent's state when writing the `conditions`. For more information, see [Job status functions](expressions.md#job-status-functions). - -## Examples - -### Run for the main branch, even if canceled, even if failing - -``` -eq(variables['Build.SourceBranch'], 'refs/heads/main') -``` - - -### Run for the main branch, if succeeding - -``` -and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')) -``` - -### Run if the branch is not main, if succeeding - -``` -and(succeeded(), ne(variables['Build.SourceBranch'], 'refs/heads/main')) -``` - -### Run for user topic branches, if succeeding - -``` -and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/heads/users/')) -``` - -### Run for continuous integration (CI) builds if succeeding - -``` -and(succeeded(), in(variables['Build.Reason'], 'IndividualCI', 'BatchedCI')) -``` - -### Run if the build is run by a branch policy for a pull request, if failing - -``` -and(failed(), eq(variables['Build.Reason'], 'PullRequest')) -``` - -### Run if the build is scheduled, even if failing, even if canceled - -``` -eq(variables['Build.Reason'], 'Schedule') -``` - -> **Release.Artifacts.{artifact-alias}.SourceBranch** is equivalent to **Build.SourceBranch**. - -### Always run if a variable is set to true, even if canceled, even if failing - -``` -eq(variables['System.debug'], true) -``` - -### Run if a variable is null (empty string) - -Since all variables are treated as strings in Azure Pipelines, an empty string is equivalent to `null` in this pipeline. - -```yaml -variables: -- name: testEmpty - value: '' - -jobs: - - job: A - steps: - - script: echo testEmpty is blank - condition: eq(variables.testEmpty, '') -``` - -### Use a template parameter as part of a condition - -When you declare a parameter in the same pipeline that you have a condition, parameter expansion happens before conditions are considered. In this case, you can embed parameters inside conditions. The script in this YAML file will run because `parameters.doThing` is true. - -The `condition` in the pipeline combines two functions: `succeeded()` and `eq('${{ parameters.doThing }}', true)`. The `succeeded()` function checks if the previous step succeeded. The `succeeded()` function returns true because there was no previous step. +## Condition settings -The `eq('${{ parameters.doThing }}', true)` function checks whether the doThing parameter is equal to `true`. Since the default value for doThing is true, the condition will return true by default unless a different value gets set in the pipeline. +The following table shows example `condition` settings to produce various outcomes. -For more template parameter examples, see [Template types & usage](templates.md). +> [!NOTE] +> `Release.Artifacts.{artifact-alias}.SourceBranch` is equivalent to `Build.SourceBranch`. + +| Desired outcome | Example condition setting | +| --------------- | ----------------- | +| Run if the source branch is main, even if the parent or preceding stage, job, or step failed or was canceled. | `eq(variables['Build.SourceBranch'], 'refs/heads/main')` | +| Run if the source branch is main and the parent or preceding stage, job, or step succeeded. | `and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))` | +| Run if the source branch isn't main, and the parent or preceding stage, job, or step succeeded. | `and(succeeded(), ne(variables['Build.SourceBranch'], 'refs/heads/main'))` | +| Run for user topic branches, if the parent or preceding stage, job, or step succeeded. | `and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/heads/users/'))` | +| Run for continuous integration (CI) builds, if the parent or preceding stage, job, or step succeeded. | `and(succeeded(), in(variables['Build.Reason'], 'IndividualCI', 'BatchedCI'))` | +| Run if the build was triggered by a branch policy for a pull request, and the parent or preceding stage, job, or step failed. | `and(failed(), eq(variables['Build.Reason'], 'PullRequest'))` | +| Run for a scheduled build, even if the parent or preceding stage, job, or step failed or was canceled. | `eq(variables['Build.Reason'], 'Schedule')` | +| Run if a variable is set to true, even if the parent or preceding stage, job, or step failed or was canceled. | `eq(variables['System.debug'], true)` | +> [!NOTE] +> You can set a condition to run if a variable is null (empty string). Since all variables are treated as strings in Azure Pipelines, an empty string is equivalent to `null` in the following pipeline: +> +> ```yaml +> variables: +> - name: testEmpty +> value: '' +> +> jobs: +> - job: A +> steps: +> - script: echo testEmpty is blank +> condition: eq(variables.testEmpty, '') +> ``` + +### Parameters in conditions + +Parameter expansion happens before conditions are considered. Therefore, when you declare a parameter in the same pipeline as a condition, you can embed the parameter inside the condition. The script in the following YAML runs because `parameters.doThing` is true. ```yaml parameters: @@ -303,11 +245,18 @@ parameters: steps: - script: echo I did a thing - condition: and(succeeded(), eq('${{ parameters.doThing }}', true)) + condition: and(succeeded(), ${{ eq(parameters.doThing, true) }}) ``` +The `condition` in the preceding pipeline combines two functions: `succeeded()` and `${{ eq(parameters.doThing, true) }}`. The `succeeded()` function checks if the previous step succeeded. The `succeeded()` function returns `true` because there was no previous step. + +The `${{ eq(parameters.doThing, true) }}` function checks whether the `doThing` parameter is equal to `true`. Since the default value for `doThing` is `true`, the condition returns `true` by default unless the pipeline sets a different value. + +### Template parameters in conditions + +When you pass a parameter to a template, you need to either set the parameter's value in your template or [use templateContext to pass the parameter to the template](template-parameters.md?view=azure-devops&preserve-view=true#use-templatecontext-to-pass-properties-to-templates). -When you pass a parameter to a template, you need to set the parameter's value in your template or [use templateContext to pass properties to templates](template-parameters.md#use-templatecontext-to-pass-properties-to-templates). +For example, the following *parameters.yml* file declares the `doThing` parameter and default value: ```yaml # parameters.yml @@ -323,6 +272,8 @@ jobs: condition: ${{ eq(parameters.doThing, true) }} ``` +The pipeline code references the *parameters.yml* template. The output of the pipeline is `I did a thing` because the parameter `doThing` is true. + ```yaml # azure-pipeline.yml parameters: @@ -337,13 +288,11 @@ extends: template: parameters.yml ``` -The output of this pipeline is `I did a thing` because the parameter `doThing` is true. - - +For more template parameter examples, see the [Template usage reference](templates.md). -### Use the output variable from a job in a condition in a subsequent job +### Job output variables used in subsequent job conditions -You can make a variable available to future jobs and specify it in a condition. Variables available to future jobs must be marked as [multi-job output variables](./variables.md#set-a-multi-job-output-variable) using `isOutput=true`. +You can make a variable available to future jobs and specify it in a condition. Variables available to future jobs must be marked as [multi-job output variables](./variables.md#set-a-multi-job-output-variable) by using `isOutput=true`, as in the following code: ```yaml jobs: @@ -360,29 +309,29 @@ jobs: - script: echo "Job Foo ran and doThing is Yes." ``` -### Use the pipeline variable created from a step in a condition in a subsequent step +### Variables created in a step used in subsequent step conditions -You can make a variable available to future steps and specify it in a condition. By default, variables created from a step are available to future steps and don't need to be marked as [multi-job output variables](./variables.md#set-a-multi-job-output-variable) using `isOutput=true`. +You can create a variable that's available for future steps to specify in a condition. Variables created from steps are available to future steps by default and don't need to be marked as [multi-job output variables](./variables.md#set-a-multi-job-output-variable). -There are some important things to note regarding the above approach and [scoping](./variables.md#set-a-job-scoped-variable-from-a-script): +There are some important things to note about [scoping](./variables.md#set-a-job-scoped-variable-from-a-script) variables that are created from steps. -- Variables created in a step in a job will be scoped to the steps in the same job. -- Variables created in a step will only be available in subsequent steps as environment variables. +- Variables created in a step in a job are scoped to the steps in the same job. +- Variables created in a step are available in subsequent steps only as environment variables. - Variables created in a step can't be used in the step that defines them. -Below is an example of creating a pipeline variable in a step and using the variable in a subsequent step's condition and script. +The following example shows creating a pipeline variable in a step and using the variable in a subsequent step's condition and script. ```yaml steps: -# This step creates a new pipeline variable: doThing. This variable will be available to subsquent steps. +# This step creates a new pipeline variable: doThing. This variable is available to subsequent steps. - bash: | echo "##vso[task.setvariable variable=doThing]Yes" displayName: Step 1 -# This step is able to use doThing, so it uses it in its condition +# This step is able to use doThing, so it uses doThing in its condition - script: | - # You can access the variable from Step 1 as an environment variable. + # Access the variable from Step 1 as an environment variable. echo "Value of doThing (as DOTHING env var): $DOTHING." displayName: Step 2 condition: and(succeeded(), eq(variables['doThing'], 'Yes')) # or and(succeeded(), eq(variables.doThing, 'Yes')) @@ -392,10 +341,9 @@ steps: - ### How can I trigger a job if a previous job succeeded with issues? -You can use the result of the previous job. For example, in this YAML file, the condition `eq(dependencies.A.result,'SucceededWithIssues')` allows the job to run because Job A succeeded with issues. +You can use the result of the previous job in a condition. For example, in the following YAML, the condition `eq(dependencies.A.result,'SucceededWithIssues')` allows job `B` to run after job `A` succeeds with issues. ```yaml jobs: @@ -414,16 +362,15 @@ jobs: - script: echo Job B ran ``` -### I canceled my build, but it's still running. What's happening? +### I canceled my build, but it's still running. Why? -You'll experience this issue if the condition that's configured in the stage doesn't include a job status check function. To resolve the issue, add a job status check function to the condition. If you cancel a job while it's in the queue, but not running, the entire job is canceled, including all the other stages. +You can experience this issue if a condition configured in a stage doesn't include a [job status check function](expressions.md?view=azure-devops&preserve-view=true#job-status-functions). To resolve the issue, add a job status check function to the condition. -Learn more about a [pipeline's behavior when a build is canceled](#pipeline-behavior-when-build-is-canceled). +If you cancel a job while it's in the queue stage but not running, the entire job is canceled, including all the other stages. For more information, see [Condition outcomes when a build is canceled](#condition-outcomes-when-a-build-is-canceled) earlier in this article. - -## Related articles +## Related content - [Specify jobs in your pipeline](../process/phases.md) -- [Add stages, dependencies, & conditions](../process/stages.md) +- [Add stages, dependencies, and conditions](../process/stages.md) diff --git a/docs/pipelines/process/container-phases.md b/docs/pipelines/process/container-phases.md index ff77f4f4767..9daed199c65 100644 --- a/docs/pipelines/process/container-phases.md +++ b/docs/pipelines/process/container-phases.md @@ -1,79 +1,73 @@ --- -title: Container Jobs in Azure Pipelines and TFS -ms.custom: seodec18 -description: Run pipeline jobs inside of a container +title: Container jobs in YAML +description: Learn about configuring and running pipeline jobs inside containers. ms.assetid: 8d35f78a-f386-4699-9280-7bd933de9e7b ms.topic: conceptual -ms.date: 05/01/2023 -monikerRange: '>= azure-devops-2019' +ms.date: 07/08/2024 +monikerRange: "<=azure-devops" --- -# Define container jobs (YAML) +# Container jobs in YAML pipelines [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -By default, [jobs](phases.md) run on the host machine where the [agent](../agents/agents.md) -is installed. -This is convenient and typically well-suited for projects that are just beginning to adopt Azure Pipelines. -Over time, you may find that you want more control over the context where your tasks run. -YAML pipelines offer container jobs for this level of control. +This article explains container jobs in Azure Pipelines. -[!INCLUDE [container-vs-host](./includes/container-vs-host.md)] +By default, Azure Pipelines [jobs](phases.md) run directly on the host machines where the agent is installed. Hosted agent jobs are convenient, require little initial setup and infrastructure to maintain, and are well-suited for basic projects. -Containers offer a lightweight abstraction over the host operating system. -You can select the exact versions of operating systems, tools, and dependencies that your build requires. -When you specify a container in your pipeline, the agent will first -fetch and start the container. -Then, each step of the job will run inside the container. -You can't have nested containers. Containers aren't supported when an agent is already running inside a container. +If you want more control over task context, you can define and run jobs in containers. Containers are a lightweight abstraction over the host operating system that provides isolation from the host. When you run jobs in containers, you can select the exact versions of operating systems, tools, and dependencies that your build requires. -::: moniker range="> azure-devops-2019" -If you need fine-grained control at the individual step level, [step targets](tasks.md#step-target) allow you to choose container or host for each step. +Linux and Windows [agents](../agents/agents.md) can run pipeline jobs directly on the host or in containers. Container jobs aren't available on macOS. + +For a container job, the agent first fetches and starts the container. Then each step of the job runs inside the container. + +::: moniker range="<=azure-devops" +If you need fine-grained control at the individual build step level, [step targets](tasks.md#step-target) let you choose a container or host for each step. ::: moniker-end -## Requirements +## Prerequisites -### Linux-based containers +- Use a YAML pipeline. Classic pipelines do not support container jobs. +- Use a hosted Windows or Ubuntu agent. Only `windows-*` and `ubuntu-*` agents support running containers. The `macos-*` agents don't support running containers. +- Your agent is set up for container jobs. + - Windows and Linux agents must have Docker installed, and need permission to access the Docker daemon. + - Containers aren't supported when the agent is already running inside a container. You can't have nested containers. -The Azure Pipelines system requires a few things in Linux-based containers: -- Bash -- glibc-based -- Can run Node.js (which the agent provides) -- Doesn't define an `ENTRYPOINT` -- `USER` has access to `groupadd` and other privileges commands without `sudo` +### Additional container requirements -And on your agent host: -- Ensure Docker is installed -- The agent must have permission to access the Docker daemon +### [Linux](#tab/linux) -Be sure your container has each of these tools available. Some of the stripped-down -containers available on Docker Hub, especially those based on Alpine Linux, don't satisfy these -minimum requirements. Containers with a `ENTRYPOINT` might not work, since Azure Pipelines -will `docker create` an awaiting container and `docker exec` a series of commands, which expect -the container is always up and running. +Linux-based containers have the following requirements. For workarounds, see [Nonglibc-based containers](#nonglibc-based-containers). +- Bash installed +- GNU C Library (glibc)-based +- No `ENTRYPOINT` +- Provide `USER` with access to `groupadd` and other privileged commands without using `sudo` +- Can run Node.js, which the agent provides + > [!NOTE] + > Node.js must be pre-installed for Linux containers on Windows hosts. -> [!NOTE] -> For Windows-based Linux containers, Node.js must be pre-installed. +Some stripped-down containers available on Docker Hub, especially containers based on Alpine Linux, don't satisfy these requirements. Containers with an `ENTRYPOINT` might not work because Azure Pipelines `docker create` and `docker exec` expect that the container is always up and running. -### Windows Containers +### [Windows](#tab/windows) -Azure Pipelines can also run [Windows Containers](/virtualization/windowscontainers/about/). -[Windows Server version 1803](/windows-server/get-started/whats-new-in-windows-server-1803) or higher is required. -Docker must be installed. Be sure your pipelines agent has permission to access the Docker daemon. +[Windows containers](/virtualization/windowscontainers/about/) must meet the following requirements: -The Windows container must support running Node.js. -A base Windows Nano Server container is missing dependencies required to run Node. +- Windows Server version 1803 or higher +- Matching host and container kernel versions +- Can run Node.js + > [!NOTE] + > A base Windows Nano Server container doesn't have the required dependencies to run Node.js. +--- -### Hosted agents +## Single job examples -Only `windows-2019` and `ubuntu-*` images support running containers. -The macOS image doesn't support running containers. +The following examples define a Windows or Linux container for a single job. -## Single job +### [Linux](#tab/linux) -A simple example: +The following simple example defines a Linux container: ```yaml pool: @@ -85,11 +79,11 @@ steps: - script: printenv ``` -This tells the system to fetch the `ubuntu` image tagged `18.04` from -[Docker Hub](https://hub.docker.com) and then start the container. When the -`printenv` command runs, it will happen inside the `ubuntu:18.04` container. +The preceding example tells the system to fetch the `ubuntu` image tagged `18.04` from [Docker Hub](https://hub.docker.com) and then start the container. The `printenv` command runs inside the `ubuntu:18.04` container. + +### [Windows](#tab/windows) -A Windows example: +The following example defines a Windows container: ```yaml pool: @@ -101,15 +95,13 @@ steps: - script: set ``` -> [!Note] -> Windows requires that the kernel version of the host and container match. -> Since this example uses the Windows 2019 image, we will use the `2019` tag for the container. +For Windows, the kernel version of the host and container must match. Since the preceding example uses a Windows 2019 host image, it uses the `2019` tag for the container. + +--- ## Multiple jobs -Containers are also useful for running the same steps in multiple [jobs](phases.md). -In the following example, the same steps run in multiple versions of Ubuntu Linux. -(And we don't have to mention the `jobs` keyword, since there's only a single job defined.) +You can use containers to run the same step in multiple jobs. The following example runs the same step in multiple versions of Ubuntu Linux. You don't have to mention the `jobs` keyword because only a single job is defined. ```yaml pool: @@ -130,44 +122,20 @@ steps: - script: printenv ``` -## Endpoints - -Containers can be hosted on registries other than public Docker Hub registries. -To host an image on [Azure Container Registry](/azure/container-registry/) or -another private container registry (including a private Docker Hub registry), -add a [service connection](../library/service-endpoints.md) to the -private registry. Then you can reference it in a container spec: - -```yaml -container: - image: registry:ubuntu1804 - endpoint: private_dockerhub_connection - -steps: -- script: echo hello -``` +### Multiple jobs with agent pools on a single agent host -or +A container job uses the underlying host agent's Docker configuration file for image registry authorization. This file signs out at the end of the Docker registry container initialization. Registry image pulls for subsequent container jobs might be denied for `unauthorized authentication` because another job running in parallel already signed out the Docker configuration file. -```yaml -container: - image: myprivate.azurecr.io/windowsservercore:1803 - endpoint: my_acr_connection +The solution is to set a Docker environment variable `DOCKER_CONFIG` that's specific to each agent pool running on the hosted agent. Export the `DOCKER_CONFIG` in each agent pool's *runsvc.sh* script as follows: -steps: -- script: echo hello +```bash +export DOCKER_CONFIG=./.docker ``` -Other container registries may also work. -Amazon ECR doesn't currently work, as there are other client tools required to convert AWS credentials into something Docker can use to authenticate. + +## Startup options - -> [!NOTE] -> The Red Hat Enterprise Linux 6 build of the agent won't run container job. Choose another Linux flavor, such as Red Hat Enterprise Linux 7 or above. - -## Options - -If you need to control container startup, you can specify `options`. +You can specify `options` to control container startup, as in the following example: ```yaml container: @@ -178,13 +146,13 @@ steps: - script: echo hello ``` -Running `docker create --help` will give you the list of supported options. You can use any option available with the [`docker create` command](https://docs.docker.com/engine/reference/commandline/create/). +Running `docker create --help` gives you the list of options that you can pass to Docker invocation. Not all of these options are guaranteed to work with Azure DevOps. Check first to see if you can use a `container` property to accomplish the same goal. + +For more information, see the [docker create](https://docs.docker.com/engine/reference/commandline/create) command reference and the [resources.containers.container definition](/azure/devops/pipelines/yaml-schema/resources-containers-container) in the Azure DevOps YAML schema reference. ## Reusable container definition -In the following example, the containers are defined in the resources section. -Each container is then referenced later, by referring to its assigned alias. -(Here, we explicitly list the `jobs` keyword for clarity.) +The following example defines the containers in the `resources` section, and then references them by their assigned aliases. The `jobs` keyword is explicitly listed for clarity. ```yaml resources: @@ -218,46 +186,69 @@ jobs: - script: printenv ``` -## Non glibc-based containers +## Service endpoints + +You can host containers on other registries than public Docker Hub. To host an image on [Azure Container Registry](/azure/container-registry/) or another private container registry, including a private Docker Hub registry, add a [service connection](../library/service-endpoints.md) to access the registry. Then you can reference the endpoint in the container definition. + +Private Docker Hub connection: + +```yaml +container: + image: registry:ubuntu1804 + endpoint: private_dockerhub_connection +``` + +Azure Container Registry connection: + +```yaml +container: + image: myprivate.azurecr.io/windowsservercore:1803 + endpoint: my_acr_connection +``` + +>[!NOTE] +>Azure Pipelines can't set up a service connection for Amazon Elastic Container Registry (ECR), because Amazon ECR requires other client tools to convert AWS credentials into something Docker can use to authenticate. + +## Nonglibc-based containers + +The Azure Pipelines agent supplies a copy of Node.js, which is required to run tasks and scripts. To find out the version of Node.js for a hosted agent, see [Microsoft-hosted agents](../agents/hosted.md#software). -The Azure Pipelines agent supplies a copy of Node.js, which is required to run tasks and scripts. To find out the version of Node.js for an hosted agent, see [Microsoft-hosted agents](../agents/hosted.md#software). -The version of Node.js is compiled against the C runtime we use in our hosted cloud, typically glibc. -Some variants of Linux use other C runtimes. -For instance, Alpine Linux uses musl. +The version of Node.js compiles against the C runtime used in the hosted cloud, typically glibc. Some Linux variants use other C runtimes. For instance, Alpine Linux uses musl. -If you want to use a non-glibc-based container as a job container, you will need to arrange a few things on your own. -First, you must supply your own copy of Node.js. -Second, you must add a label to your image telling the agent where to find the Node.js binary. -Finally, stock Alpine doesn't come with other dependencies that Azure Pipelines depends on: -bash, sudo, which, and groupadd. +If you want to use a nonglibc-based container, you need to: -### Bring your own Node.js -You're responsible for adding a Node binary to your container. -Node 14 is a safe choice. -You can start from the `node:14-alpine` image. +- Supply your own copy of Node.js. +- Add a label to your image telling the agent where to find the Node.js binary. +- Provide other dependencies that Azure Pipelines depends on: `bash`, `sudo`, `which`, and `groupadd`. + +### Supply your own Node.js + +If you use a nonglibc-based container, you're responsible for adding a Node binary to your container. Node.js 18 is a safe choice. Start from the `node:18-alpine` image. ### Tell the agent about Node.js -The agent will read a container label "com.azure.dev.pipelines.handler.node.path". -If this label exists, it must be the path to the Node.js binary. -For example, in an image based on `node:10-alpine`, add this line to your Dockerfile: -``` + +The agent reads the container label `"com.azure.dev.pipelines.handler.node.path"`. If this label exists, it must be the path to the Node.js binary. + +For example, in an image based on `node:18-alpine`, add the following line to your Dockerfile: + +```dockerfile LABEL "com.azure.dev.pipelines.agent.handler.node.path"="/usr/local/bin/node" ``` -### Add requirements -Azure Pipelines assumes a Bash-based system with common administration packages installed. -Alpine Linux in particular doesn't come with several of the packages needed. -Installing `bash`, `sudo`, and `shadow` will cover the basic needs. -``` +### Add required packages + +Azure Pipelines assumes a Bash-based system with common administrative packages installed. Alpine Linux in particular doesn't come with several of the packages needed. Install `bash`, `sudo`, and `shadow` to cover the basic needs. + +```dockerfile RUN apk add bash sudo shadow ``` -If you depend on any in-box or Marketplace tasks, you'll also need to supply the binaries they require. +If you depend on any in-box or Marketplace tasks, also supply the binaries they require. -### Full example of a Dockerfile +### Full Dockerfile example -``` -FROM node:10-alpine +```dockerfile +FROM node:18-alpine RUN apk add --no-cache --virtual .pipeline-deps readline linux-pam \ && apk add bash sudo shadow \ @@ -268,13 +259,8 @@ LABEL "com.azure.dev.pipelines.agent.handler.node.path"="/usr/local/bin/node" CMD [ "node" ] ``` -### Multiple jobs with agent pools on a single hosted agent - -The container job uses the underlying host agent Docker config.json for image registry authorization, which logs out at the end of the Docker registry container initialization. Subsequent registry image pulls authorization might be denied for “unauthorized authentication” because the Docker config.json file registered in the system for authentication has already been logged out by one of the other container jobs that are running in parallel. - -The solution is to set the Docker environment variable `DOCKER_CONFIG` that is specific to each agent pool service running on the hosted agent. Export the `DOCKER_CONFIG` in each agent pool’s runsvc.sh script: +## Related content -``` -#insert anything to set up env when running as a service -export DOCKER_CONFIG=./.docker -``` +- [Azure Pipelines jobs](phases.md) +- [Azure Pipelines agents](../agents/agents.md) +- [YAML schema resources.containers.container definition](/azure/devops/pipelines/yaml-schema/resources-containers-container) diff --git a/docs/pipelines/process/create-multistage-pipeline.md b/docs/pipelines/process/create-multistage-pipeline.md index d6494ea549f..6a91a194a35 100644 --- a/docs/pipelines/process/create-multistage-pipeline.md +++ b/docs/pipelines/process/create-multistage-pipeline.md @@ -1,22 +1,23 @@ --- -title: Create a multistage pipeline with Azure DevOps +title: 'Tutorial: Create a multistage pipeline with Azure DevOps' description: Build an app pipeline for development and staging. -ms.topic: how-to -ms.date: 07/05/2023 +ms.topic: tutorial +ms.date: 07/12/2023 ms.custom: template-how-to-pattern --- -# Create a multistage pipeline with Azure DevOps +# Tutorial: Create a multistage pipeline with Azure DevOps [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] You can use an Azure DevOps multistage pipeline to divide your CI/CD process into stages that represent different parts of your development cycle. Using a multistage pipeline gives you more visibility into your deployment process and makes it easier to integrate [approvals and checks](approvals.md). -In this article, you'll build a YAML pipeline with three stages: +In this article, you'll create two App Service instances and build a YAML pipeline with three stages: -1. Build: build the source code and produce a package -2. Dev: deploy your package to a development site for testing -3. Staging: deploy to a staging Azure App Service instance a [manual approval check](approvals.md) +> [!div class="checklist"] +> * [Build: build the source code and produce a package](#add-the-build-stage) +> * [Dev: deploy your package to a development site for testing](#add-the-dev-stage) +> * [Staging: deploy to a staging Azure App Service instance with a manual approval check](#add-the-staging-stage) In a real-world scenario, you may have another stage for deploying to production depending on your DevOps process. @@ -27,11 +28,11 @@ The example code in this exercise is for a .NET web application for a pretend sp * A GitHub account where you can create a repository. [Create one for free](https://github.com). * An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/dotnet). - * An Azure DevOps organization and project. [Create one for free](../get-started/pipelines-sign-up.md). +* An Azure DevOps organization and project. [Create one for free](../get-started/pipelines-sign-up.md). * An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can request a free tier. -## 1 - Fork the project +## Fork the project Fork the following sample repository at GitHub. @@ -39,27 +40,27 @@ Fork the following sample repository at GitHub. https://github.com/MicrosoftDocs/mslearn-tailspin-spacegame-web-deploy ``` -## 2 - Create the App Service environments +## Create the App Service instances -Before you can deploy your pipeline, you need to first create an App Service environment to deploy to. You'll use Azure CLI to create the environment. +Before you can deploy your pipeline, you need to first create an App Service instance to deploy to. You'll use Azure CLI to create the instance. -1. Go to [Azure portal](https://portal.azure.com) and sign in. +1. Sign in to the [Azure portal](https://portal.azure.com). 1. From the menu, select **Cloud Shell** and the **Bash** experience. -1. Generate a random number that makes your web app's domain name unique. +1. Generate a random number that makes your web app's domain name unique. The advantage of having a unique value is that your App Service instance won't have a name conflict with other learners completing this tutorial. ```code webappsuffix=$RANDOM ``` -1. Use a `az group create` command to create a resource group named *tailspin-space-game-rg* that contains all of your App Service instances. Update the `location` value to use your closest region. +1. Open a command prompt and use a `az group create` command to create a resource group named *tailspin-space-game-rg* that contains all of your App Service instances. Update the `location` value to use your closest region. ```azurecli az group create --location eastus --name tailspin-space-game-rg ``` -1. Create an App Service plan. +1. Use the command prompt to create an App Service plan. ```azurecli az appservice plan create \ @@ -69,7 +70,7 @@ Before you can deploy your pipeline, you need to first create an App Service env --is-linux ``` -1. Create two App Service instances, one for each environment (Dev and Staging) with the `az webapp create` command. +1. In the command prompt, create two App Service instances, one for each instance (Dev and Staging) with the `az webapp create` command. ```azurecli az webapp create \ @@ -85,7 +86,7 @@ Before you can deploy your pipeline, you need to first create an App Service env --runtime "DOTNET|6.0" ``` -1. List both App Service instances to verify that they're running with the `az webapp list` command. +1. With the command prompt, list both App Service instances to verify that they're running with the `az webapp list` command. ```azurecli az webapp list \ @@ -96,9 +97,9 @@ Before you can deploy your pipeline, you need to first create an App Service env 1. Copy the names of the App Service instances to use as variables in the next section. -## 3 - Create your Azure DevOps project and variables +## Create your Azure DevOps project and variables -Set up your Azure DevOps project and a build pipeline. You'll also add variables for your development and staging environments. +Set up your Azure DevOps project and a build pipeline. You'll also add variables for your development and staging instances. Your build pipeline: @@ -107,7 +108,7 @@ Your build pipeline: * Includes a stage named Build that builds the web application * Publishes an artifact you'll use in a later stage -### Add a build pipeline +#### Add the Build stage [!INCLUDE [include](../ecosystems/includes/create-pipeline-before-template-selected.md)] @@ -115,11 +116,80 @@ Your build pipeline: 8. Replace the contents of *azure-pipelines.yml* with this code. - :::code language="yml" source="~/../snippets/pipelines/multistage/multistage-example.yml" range="1-67"::: + ```yml + trigger: + - '*' + + variables: + buildConfiguration: 'Release' + releaseBranchName: 'release' + + stages: + - stage: 'Build' + displayName: 'Build the web application' + jobs: + - job: 'Build' + displayName: 'Build job' + pool: + vmImage: 'ubuntu-20.04' + demands: + - npm + + variables: + wwwrootDir: 'Tailspin.SpaceGame.Web/wwwroot' + dotnetSdkVersion: '6.x' + + steps: + - task: UseDotNet@2 + displayName: 'Use .NET SDK $(dotnetSdkVersion)' + inputs: + version: '$(dotnetSdkVersion)' + + - task: Npm@1 + displayName: 'Run npm install' + inputs: + verbose: false + + - script: './node_modules/.bin/node-sass $(wwwrootDir) --output $(wwwrootDir)' + displayName: 'Compile Sass assets' + + - task: gulp@1 + displayName: 'Run gulp tasks' + + - script: 'echo "$(Build.DefinitionName), $(Build.BuildId), $(Build.BuildNumber)" > buildinfo.txt' + displayName: 'Write build info' + workingDirectory: $(wwwrootDir) + + - task: DotNetCoreCLI@2 + displayName: 'Restore project dependencies' + inputs: + command: 'restore' + projects: '**/*.csproj' + + - task: DotNetCoreCLI@2 + displayName: 'Build the project - $(buildConfiguration)' + inputs: + command: 'build' + arguments: '--no-restore --configuration $(buildConfiguration)' + projects: '**/*.csproj' + + - task: DotNetCoreCLI@2 + displayName: 'Publish the project - $(buildConfiguration)' + inputs: + command: 'publish' + projects: '**/*.csproj' + publishWebProjects: false + arguments: '--no-build --configuration $(buildConfiguration) --output $(Build.ArtifactStagingDirectory)/$(buildConfiguration)' + zipAfterPublish: true + + - publish: '$(Build.ArtifactStagingDirectory)' + artifact: drop + ``` + 9. When you're ready, select **Save and run**. -### Add environment variables +#### Add instance variables 1. In Azure DevOps, go to **Pipelines** > **Library**. @@ -127,7 +197,7 @@ Your build pipeline: 1. Under **Properties**, add *Release* for the variable group name. -1. Create a two variables to refer to your development and staging host names. Replace the value `1234` with the correct value for your environment. +1. Create a two variables to refer to your development and staging host names. Replace the value `1234` with the correct value for your instance. |Variable name |Example value | @@ -138,7 +208,7 @@ Your build pipeline: 1. Select **Save** to save your variables. -## 4 - Add the Dev stage +## Add the Dev stage Next, you'll update your pipeline to promote your build to the *Dev* stage. @@ -154,8 +224,101 @@ Next, you'll update your pipeline to promote your build to the *Dev* stage. * Download an artifact from `drop` * Deploy to Azure App Service with an [Azure Resource Manager service connection](../library/service-endpoints.md) - :::code language="yml" source="~/../snippets/pipelines/multistage/multistage-example.yml" range="1-92" highlight="69-92"::: - + ```yml + trigger: + - '*' + + variables: + buildConfiguration: 'Release' + releaseBranchName: 'release' + + stages: + - stage: 'Build' + displayName: 'Build the web application' + jobs: + - job: 'Build' + displayName: 'Build job' + pool: + vmImage: 'ubuntu-20.04' + demands: + - npm + + variables: + wwwrootDir: 'Tailspin.SpaceGame.Web/wwwroot' + dotnetSdkVersion: '6.x' + + steps: + - task: UseDotNet@2 + displayName: 'Use .NET SDK $(dotnetSdkVersion)' + inputs: + version: '$(dotnetSdkVersion)' + + - task: Npm@1 + displayName: 'Run npm install' + inputs: + verbose: false + + - script: './node_modules/.bin/node-sass $(wwwrootDir) --output $(wwwrootDir)' + displayName: 'Compile Sass assets' + + - task: gulp@1 + displayName: 'Run gulp tasks' + + - script: 'echo "$(Build.DefinitionName), $(Build.BuildId), $(Build.BuildNumber)" > buildinfo.txt' + displayName: 'Write build info' + workingDirectory: $(wwwrootDir) + + - task: DotNetCoreCLI@2 + displayName: 'Restore project dependencies' + inputs: + command: 'restore' + projects: '**/*.csproj' + + - task: DotNetCoreCLI@2 + displayName: 'Build the project - $(buildConfiguration)' + inputs: + command: 'build' + arguments: '--no-restore --configuration $(buildConfiguration)' + projects: '**/*.csproj' + + - task: DotNetCoreCLI@2 + displayName: 'Publish the project - $(buildConfiguration)' + inputs: + command: 'publish' + projects: '**/*.csproj' + publishWebProjects: false + arguments: '--no-build --configuration $(buildConfiguration) --output $(Build.ArtifactStagingDirectory)/$(buildConfiguration)' + zipAfterPublish: true + + - publish: '$(Build.ArtifactStagingDirectory)' + artifact: drop + + - stage: 'Dev' + displayName: 'Deploy to the dev environment' + dependsOn: Build + condition: succeeded() + jobs: + - deployment: Deploy + pool: + vmImage: 'ubuntu-20.04' + environment: dev + variables: + - group: Release + strategy: + runOnce: + deploy: + steps: + - download: current + artifact: drop + - task: AzureWebApp@1 + displayName: 'Azure App Service Deploy: dev website' + inputs: + azureSubscription: 'your-subscription' + appType: 'webAppLinux' + appName: '$(WebAppNameDev)' + package: '$(Pipeline.Workspace)/drop/$(buildConfiguration)/*.zip' + ``` + 1. Change the `AzureWebApp@1` task to use your subscription. 1. Select **Settings** for the task. @@ -172,14 +335,12 @@ Next, you'll update your pipeline to promote your build to the *Dev* stage. 1. Save and run your pipeline. -1. Verify that your app deployed by going to https://tailspin-space-game-web-dev-1234.azurewebsites.net in your browser. Substitute `1234` with the unique value for your site. - -## 5 - Add the Staging stage +## Add the Staging stage Last, you'll promote the Dev stage to Staging. Unlike the Dev environment, you want to have more control in the staging environment you'll add a manual approval. -### Create staging environment +#### Create staging environment 1. From Azure Pipelines, select **Environments**. @@ -199,13 +360,130 @@ Last, you'll promote the Dev stage to Staging. Unlike the Dev environment, you w 1. Select **Save**. -### Add new stage to pipeline +#### Add new stage to pipeline You'll add new stage, `Staging` to the pipeline that includes a manual approval. 1. Edit your pipeline file and add the `Staging` section. - :::code language="yml" source="~/../snippets/pipelines/multistage/multistage-example.yml" range="1-116" highlight="94-116"::: + ```yml + trigger: + - '*' + + variables: + buildConfiguration: 'Release' + releaseBranchName: 'release' + + stages: + - stage: 'Build' + displayName: 'Build the web application' + jobs: + - job: 'Build' + displayName: 'Build job' + pool: + vmImage: 'ubuntu-20.04' + demands: + - npm + + variables: + wwwrootDir: 'Tailspin.SpaceGame.Web/wwwroot' + dotnetSdkVersion: '6.x' + + steps: + - task: UseDotNet@2 + displayName: 'Use .NET SDK $(dotnetSdkVersion)' + inputs: + version: '$(dotnetSdkVersion)' + + - task: Npm@1 + displayName: 'Run npm install' + inputs: + verbose: false + + - script: './node_modules/.bin/node-sass $(wwwrootDir) --output $(wwwrootDir)' + displayName: 'Compile Sass assets' + + - task: gulp@1 + displayName: 'Run gulp tasks' + + - script: 'echo "$(Build.DefinitionName), $(Build.BuildId), $(Build.BuildNumber)" > buildinfo.txt' + displayName: 'Write build info' + workingDirectory: $(wwwrootDir) + + - task: DotNetCoreCLI@2 + displayName: 'Restore project dependencies' + inputs: + command: 'restore' + projects: '**/*.csproj' + + - task: DotNetCoreCLI@2 + displayName: 'Build the project - $(buildConfiguration)' + inputs: + command: 'build' + arguments: '--no-restore --configuration $(buildConfiguration)' + projects: '**/*.csproj' + + - task: DotNetCoreCLI@2 + displayName: 'Publish the project - $(buildConfiguration)' + inputs: + command: 'publish' + projects: '**/*.csproj' + publishWebProjects: false + arguments: '--no-build --configuration $(buildConfiguration) --output $(Build.ArtifactStagingDirectory)/$(buildConfiguration)' + zipAfterPublish: true + + - publish: '$(Build.ArtifactStagingDirectory)' + artifact: drop + + - stage: 'Dev' + displayName: 'Deploy to the dev environment' + dependsOn: Build + condition: succeeded() + jobs: + - deployment: Deploy + pool: + vmImage: 'ubuntu-20.04' + environment: dev + variables: + - group: Release + strategy: + runOnce: + deploy: + steps: + - download: current + artifact: drop + - task: AzureWebApp@1 + displayName: 'Azure App Service Deploy: dev website' + inputs: + azureSubscription: 'your-subscription' + appType: 'webAppLinux' + appName: '$(WebAppNameDev)' + package: '$(Pipeline.Workspace)/drop/$(buildConfiguration)/*.zip' + + - stage: 'Staging' + displayName: 'Deploy to the staging environment' + dependsOn: Dev + jobs: + - deployment: Deploy + pool: + vmImage: 'ubuntu-20.04' + environment: staging + variables: + - group: 'Release' + strategy: + runOnce: + deploy: + steps: + - download: current + artifact: drop + - task: AzureWebApp@1 + displayName: 'Azure App Service Deploy: staging website' + inputs: + azureSubscription: 'your-subscription' + appType: 'webAppLinux' + appName: '$(WebAppNameStaging)' + package: '$(Pipeline.Workspace)/drop/$(buildConfiguration)/*.zip' + ``` 1. Change the `AzureWebApp@1` task in the Staging stage to use your subscription. @@ -228,13 +506,27 @@ You'll add new stage, `Staging` to the pipeline that includes a manual approval. 1. Review the approval and allow the pipeline to run. :::image type="content" source="media/mutistage-pipeline/pipeline-check-manual-validation.png" alt-text="Screenshot of manual validation check."::: - -1. Verify that your app deployed by going to https://tailspin-space-game-web-staging-1234.azurewebsites.net in your browser. Substitute `1234` with the unique value for your site. -## Clean up +## Clean up resources -Delete the resource group that you used, *tailspin-space-game-rg*, with the `az group delete` command. + If you're not going to continue to use this application, delete the resource group in Azure portal and the project in Azure DevOps with the following steps: -```azurecli -az group delete --name tailspin-space-game-rg -``` +To clean up your resource group: + +1. Go to the [Azure portal](https://portal.azure.com?azure-portal=true) and sign in. +1. From the menu bar, select Cloud Shell. When prompted, select the **Bash** experience. + + :::image type="content" source="../apps/cd/azure/media/azure-portal-menu-cloud-shell.png" alt-text="A screenshot of the Azure portal showing selecting the Cloud Shell menu item. "::: + +1. Run the following [az group delete](/cli/azure/group#az-group-delete) command to delete the resource group that you used, `tailspin-space-game-rg`. + + ```azurecli + az group delete --name tailspin-space-game-rg + ``` + +To delete your Azure DevOps project, including the build pipeline, see [Delete project](../../organizations/projects/delete-project.md). + +## Related content + +- [Key concepts for new Azure Pipelines users](../get-started/key-pipelines-concepts.md) +- [Deploy to App Service using Azure Pipelines](/azure/app-service/deploy-azure-pipelines) diff --git a/docs/pipelines/process/demands.md b/docs/pipelines/process/demands.md deleted file mode 100644 index 661f95d1169..00000000000 --- a/docs/pipelines/process/demands.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Demands -ms.custom: seodec18 -description: Configure custom demands for your pipeline in Azure Pipelines, Azure DevOps Server, or Team Foundation Server. -ms.topic: conceptual -ms.assetid: 7C469647-117D-4867-B094-8BC811C0003E -ms.author: sdanie -author: steved0x -ms.date: 01/18/2023 -monikerRange: '<= azure-devops' ---- - -# Specify demands - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - -Use demands to make sure that the [capabilities](../agents/agents.md#capabilities) your pipeline needs are present on the agents that run it. Demands are asserted automatically by tasks or manually by you. - -> [!NOTE] -> -> Demands and capabilities are designed for use with self-hosted agents so that jobs can be matched with an agent that -> meets the requirements of the job. When using Microsoft-hosted agents, you select an image for the agent that -> matches the requirements of the job, so although it is possible to add capabilities to a Microsoft-hosted agent, you don't need -> to use capabilities with Microsoft-hosted agents. - -## Task demands - -Some tasks won't run unless one or more demands are met by the agent. For example, the [Visual Studio Build](/azure/devops/pipelines/tasks/reference/vsbuild-v1) task demands that ```msbuild``` and ```visualstudio``` are installed on the agent. - -## Manually entered agent demands - -You might need to use self-hosted agents with special capabilities. For example, your pipeline may require **SpecialSoftware** on agents in the `Default` pool. Or, if you have multiple agents with different operating systems in the same pool, you may have a pipeline that requires a Linux agent. - -# [YAML](#tab/yaml) - -:::moniker range=">=azure-devops-2019" - -To add a single demand to your YAML build pipeline, add the `demands:` line to the `pool` section. -```yaml -pool: - name: Default - demands: SpecialSoftware # exists check for SpecialSoftware -``` - -Or if you need to add multiple demands, add one per line. - -```yaml -pool: - name: MyPool - demands: - - myCustomCapability # exists check for myCustomCapability - - Agent.Version -equals 2.144.0 # equals check for Agent.Version 2.144.0 -``` - -> [!NOTE] -> Checking for the existence of a capability (exists) and checking for a specific string in a capability (equals) are the only two supported operations for demands. - -For more information and examples, see [YAML schema - Demands](/azure/devops/pipelines/yaml-schema/pool). - -:::moniker-end - -:::moniker range=" [!TIP] -> For classic non-YAML build definitions, when you manually queue a build you can change the demands on that run. - -* * * diff --git a/docs/pipelines/process/deployment-jobs.md b/docs/pipelines/process/deployment-jobs.md index 1dedb77c11a..342d1bdc54d 100644 --- a/docs/pipelines/process/deployment-jobs.md +++ b/docs/pipelines/process/deployment-jobs.md @@ -3,7 +3,7 @@ title: Deployment jobs description: Deploy to resources within an environment ms.topic: conceptual ms.assetid: fc825338-7012-4687-8369-5bf8f63b9c10 -ms.date: 05/18/2023 +ms.date: 01/24/2025 monikerRange: '>= azure-devops-2020' --- @@ -12,7 +12,7 @@ monikerRange: '>= azure-devops-2020' [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] > [!IMPORTANT] -> - Job and stage names cannot contain keywords (example: `deployment`). +> - Job and stage names can't contain keywords (example: `deployment`). > - Each job in a stage must have a unique name. In YAML pipelines, we recommend that you put your deployment steps in a special type of [job](phases.md) called a deployment job. A deployment job is a collection of steps that are run sequentially against the environment. A deployment job and a [traditional job](phases.md) can exist in the same stage. Azure DevOps supports the *runOnce*, *rolling*, and the *canary* strategies. @@ -22,51 +22,17 @@ Deployment jobs provide the following benefits: - **Deployment history**: You get the deployment history across pipelines, down to a specific resource and status of the deployments for auditing. - **Apply deployment strategy**: You define how your application is rolled out. -A deployment job doesn't automatically clone the source repo. You can checkout the source repo within your job with `checkout: self`. +A deployment job doesn't automatically clone the source repo. You can check out the source repo within your job with `checkout: self`. > [!NOTE] > This article focuses on deployment with deployment jobs. To learn how to deploy to Azure with pipelines, see [Deploy to Azure overview](../overview-azure.md). ## Schema -Here's the full syntax to specify a deployment job: +Go to the YAML Schema to see the [jobs.deployment](/azure/devops/pipelines/yaml-schema/jobs-deployment) and [jobs.deployment.environment](/azure/devops/pipelines/yaml-schema/jobs-deployment-environment) definitions. -```YAML -jobs: -- deployment: string # name of the deployment job, A-Z, a-z, 0-9, and underscore. The word "deploy" is a keyword and is unsupported as the deployment name. - displayName: string # friendly name to display in the UI - pool: # not required for virtual machine resources - name: string # Use only global level variables for defining a pool name. Stage/job level variables are not supported to define pool name. - demands: string | [ string ] - workspace: - clean: outputs | resources | all # what to clean up before the job runs - dependsOn: string - condition: string - continueOnError: boolean # 'true' if future jobs should run even if this job fails; defaults to 'false' - container: containerReference # container to run this job inside - services: { string: string | container } # container resources to run as a service container - timeoutInMinutes: nonEmptyString # how long to run the job before automatically cancelling - cancelTimeoutInMinutes: nonEmptyString # how much time to give 'run always even if cancelled tasks' before killing them - variables: # several syntaxes, see specific section - environment: string # target environment name and optionally a resource name to record the deployment history; format: . - strategy: - runOnce: #rolling, canary are the other strategies that are supported - deploy: - steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ] -``` - -There is a more detailed, alternative syntax you can also use for the `environment` property. - -```yaml -environment: - name: string # Name of environment. - resourceName: string # Name of resource. - resourceId: string # Id of resource. - resourceType: string # Type of environment resource. - tags: string # List of tag filters. -``` +For virtual machines, you don't need to define a pool. Any steps that you define in a deployment job with a virtual machine resource runs against that virtual machine and not against the agent in the pool. For other resource types such as Kubernetes, you do need to define a pool so that tasks can run on that machine. -For virtual machines, you don't need to define a pool. Any steps that you define in a deployment job with a virtual machine resource will run against that virtual machine and not against the agent in the pool. For other resource types such as Kubernetes, you do need to define a pool so that tasks can run on that machine. ## Deployment strategies When you're deploying application updates, it's important that the technique you use to deliver the update will: @@ -77,7 +43,7 @@ When you're deploying application updates, it's important that the technique you * Test the updated version after routing traffic. * In case of failure, run steps to restore to the last known good version. -We achieve this by using lifecycle hooks that can run steps during deployment. Each of the lifecycle hooks resolves into an agent job or a [server job](phases.md#server-jobs) (or a container or validation job in the future), depending on the `pool` attribute. By default, the lifecycle hooks will inherit the `pool` specified by the `deployment` job. +We achieve this by using lifecycle hooks that can run steps during deployment. Each of the lifecycle hooks resolves into an agent job or a [server job](phases.md#server-jobs) (or a container or validation job in the future), depending on the `pool` attribute. By default, the lifecycle hooks inherit the `pool` specified by the `deployment` job. Deployment jobs use the `$(Pipeline.Workspace)` system variable. @@ -85,7 +51,7 @@ Deployment jobs use the `$(Pipeline.Workspace)` system variable. `preDeploy`: Used to run steps that initialize resources before application deployment starts. -`deploy`: Used to run steps that deploy your application. Download artifact task will be auto injected only in the `deploy` hook for deployment jobs. To stop downloading artifacts, use `- download: none` or choose specific artifacts to download by specifying [Download Pipeline Artifact task](/azure/devops/pipelines/yaml-schema/steps-download). +`deploy`: Used to run steps that deploy your application. Download artifact task is auto injected only in the `deploy` hook for deployment jobs. To stop downloading artifacts, use `- download: none` or choose specific artifacts to download by specifying [Download Pipeline Artifact task](/azure/devops/pipelines/yaml-schema/steps-download). `routeTraffic`: Used to run steps that serve the traffic to the updated version. @@ -95,7 +61,7 @@ Deployment jobs use the `$(Pipeline.Workspace)` system variable. ### RunOnce deployment strategy -`runOnce` is the simplest deployment strategy wherein all the lifecycle hooks, namely `preDeploy` `deploy`, `routeTraffic`, and `postRouteTraffic`, are executed once. Then, either `on:` `success` or `on:` `failure` is executed. +[runOnce](/azure/devops/pipelines/yaml-schema/jobs-deployment-strategy-run-once) is the simplest deployment strategy wherein all the lifecycle hooks, namely `preDeploy` `deploy`, `routeTraffic`, and `postRouteTraffic`, are executed once. Then, either `on:` `success` or `on:` `failure` is executed. ```YAML strategy: @@ -141,7 +107,7 @@ If you're using self-hosted agents, you can use the workspace clean options to c ### Rolling deployment strategy -A rolling deployment replaces instances of the previous version of an application with instances of the new version of the application on a fixed set of virtual machines (rolling set) in each iteration. +A [rolling deployment](/azure/devops/pipelines/yaml-schema/jobs-deployment-strategy-rolling) replaces instances of the previous version of an application with instances of the new version of the application on a fixed set of virtual machines (rolling set) in each iteration. We currently only support the rolling strategy to VM resources. @@ -182,11 +148,11 @@ Then, either `on: success` or `on: failure` is executed. With `maxParallel: <# or % of VMs>`, you can control the number/percentage of virtual machine targets to deploy to in parallel. This ensures that the app is running on these machines and is capable of handling requests while the deployment is taking place on the rest of the machines, which reduces overall downtime. > [!NOTE] - > There are a few known gaps in this feature. For example, when you retry a stage, it will re-run the deployment on all VMs not just failed targets. + > There are a few known gaps in this feature. For example, when you retry a stage, it re-runs the deployment on all VMs not just failed targets. ### Canary deployment strategy -Canary deployment strategy is an advanced deployment strategy that helps mitigate the risk involved in rolling out new versions of applications. By using this strategy, you can roll out the changes to a small subset of servers first. As you gain more confidence in the new version, you can release it to more servers in your infrastructure and route more traffic to it. +The [Canary deployment strategy](/azure/devops/pipelines/yaml-schema/jobs-deployment-strategy-canary) is an advanced deployment strategy that helps mitigate the risk involved in rolling out new versions of applications. By using this strategy, you can roll out the changes to a small subset of servers first. As you gain more confidence in the new version, you can release it to more servers in your infrastructure and route more traffic to it. ```YAML strategy: @@ -292,10 +258,14 @@ This approach has the following benefits: - Steps in the deployment job **automatically inherit** the connection details of the resource (in this case, a Kubernetes namespace, `smarthotel-dev.bookings`), because the deployment job is linked to the environment. This is useful in the cases where the same connection detail is set for multiple steps of the job. +> [!NOTE] +> If you're using a private AKS cluster, make sure you're connected to the cluster's virtual network as the API server endpoint isn't exposed through a public IP address. +> +> Azure Pipelines recommends setting up a self-hosted agent within a VNET that has access to the cluster's virtual network. See [Options for connecting to the private cluster](/azure/aks/private-clusters#options-for-connecting-to-the-private-cluster) for details. ### Rolling deployment strategy -The rolling strategy for VMs updates up to five targets in each iteration. `maxParallel` will determine the number of targets that can be deployed to, in parallel. The selection accounts for absolute number or percentage of targets that must remain available at any time excluding the targets that are being deployed to. It is also used to determine the success and failure conditions during deployment. +The rolling strategy for VMs updates up to five targets in each iteration. `maxParallel` determines the number of targets that can be deployed to, in parallel. The selection accounts for absolute number or percentage of targets that must remain available at any time excluding the targets that are being deployed to. It's also used to determine the success and failure conditions during deployment. ```YAML jobs: @@ -374,7 +344,7 @@ jobs: ``` ## Use pipeline decorators to inject steps automatically -[Pipeline decorators](../../extend/develop/add-pipeline-decorator.md) can be used in deployment jobs to auto-inject any custom step (for example, vulnerability scanner) to every [lifecycle hook](#descriptions-of-lifecycle-hooks) execution of every deployment job. Since pipeline decorators can be applied to all pipelines in an organization, this can be applied as part of enforcing safe deployment practices. +[Pipeline decorators](../../extend/develop/add-pipeline-decorator.md) can be used in deployment jobs to autoinject any custom step (for example, vulnerability scanner) to every [lifecycle hook](#descriptions-of-lifecycle-hooks) execution of every deployment job. Since pipeline decorators can be applied to all pipelines in an organization, this can be applied as part of enforcing safe deployment practices. In addition, deployment jobs can be run as a [container job](container-phases.md) along with [services side-car](service-containers.md) if defined. @@ -387,8 +357,8 @@ To share variables between stages, output an [artifact](../artifacts/pipeline-ar While executing deployment strategies, you can access output variables across jobs using the following syntax. -- For **runOnce** strategy: `$[dependencies..outputs['..']]` (for example, `$[dependencies.JobA.outputs['Deploy.StepA.VariableA']]`) -- For **runOnce** strategy plus a resourceType: `$[dependencies..outputs['_..']]`. (for example, `$[dependencies.JobA.outputs['Deploy_VM1.StepA.VariableA']]`) +- For **runOnce** strategy: `$[dependencies..outputs['..']]` (for example, `$[dependencies.JobA.outputs['JobA.StepA.VariableA']]`) +- For **runOnce** strategy plus a resourceType: `$[dependencies..outputs['Deploy_..']]`. (for example, `$[dependencies.JobA.outputs['Deploy_VM1.StepA.VariableA']]`) - For **canary** strategy: `$[dependencies..outputs['_..']]` - For **rolling** strategy: `$[dependencies..outputs['_..']]` @@ -471,6 +441,7 @@ stages: vmImage: 'ubuntu-latest' environment: name: env2 + resourceName: vmsfortesting resourceType: virtualmachine strategy: runOnce: @@ -495,7 +466,7 @@ stages: pool: vmImage: 'ubuntu-latest' variables: - myVarFromDeploymentJob: $[ dependencies.A2.outputs['A2.setvarStepTwo.myOutputVar'] ] + myVarFromDeploymentJob: $[ dependencies.A2.outputs['A2.setvarStepTwo.myOutputVarTwo'] ] myOutputVarTwo: $[ dependencies.A2.outputs['Deploy_vmsfortesting.setvarStepTwo.myOutputVarTwo'] ] steps: @@ -503,7 +474,7 @@ stages: name: echovartwo ``` -When you output a variable from a deployment job, referencing it from the next job uses different syntax depending on if you want to set a variable or use it as a condition for the stage. +When you output a variable from a job in stage one, referencing it from a deployment job in next stage uses different syntax depending on if you want to set a variable or use it as a condition for the stage. ```yaml stages: @@ -536,6 +507,44 @@ stages: steps: - bash: echo $(myOutputVar) ``` +When you output a variable from a deployment job, use stageDependencies syntax to reference it from next stage +(for example, `$[stageDependencies...outputs[Deploy_..]]`). + +```yaml +stages: +- stage: StageA + jobs: + - deployment: A1 + environment: + name: env1 + resourceName: DevEnvironmentV + resourceType: virtualMachine + strategy: + runOnce: + deploy: + steps: + - script: echo "##vso[task.setvariable variable=myVar;isOutput=true]true" + name: setvarStep + - script: | + echo "Value of myVar in the same Job : $(setVarStep.myVar)" + displayName: 'Verify variable in StageA' +- stage: StageB + dependsOn: StageA + + # Full Variables syntax for inter-stage jobs + variables: + myOutputVar: $[stageDependencies.StageA.A1.outputs['Deploy_DevEnvironmentV.setvarStep.myVar']] + jobs: + - deployment: B1 + pool: + vmImage: 'ubuntu-latest' + environment: envB + strategy: + runOnce: + deploy: + steps: + - bash: echo $(myOutputVar) + ``` Learn more about how to [set a multi-job output variable](variables.md#set-a-multi-job-output-variable) diff --git a/docs/pipelines/process/environments-kubernetes.md b/docs/pipelines/process/environments-kubernetes.md index 0312235dd7b..4400014ec17 100644 --- a/docs/pipelines/process/environments-kubernetes.md +++ b/docs/pipelines/process/environments-kubernetes.md @@ -4,7 +4,7 @@ description: Target Kubernetes clusters with the Kubernetes resource. Use Kubern ms.custom: pipelinesresourcesrefresh ms.topic: conceptual ms.assetid: b318851c-4240-4dc2-8688-e70aba1cec55 -ms.date: 03/23/2022 +ms.date: 11/06/2023 monikerRange: '>= azure-devops-2020' --- @@ -12,11 +12,16 @@ monikerRange: '>= azure-devops-2020' [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -The Kubernetes resource view provides a glimpse into the status of objects within the namespace that's mapped to the resource. This view also overlays pipeline traceability so you can trace back from a Kubernetes object to the pipeline, and then back to the commit. +The Kubernetes resource view shows the status of objects within the namespace that are mapped to the resource. The resource view also overlays pipeline traceability so you can trace back from a Kubernetes object to the pipeline, and then back to the commit. Use Kubernetes resources to target Kubernetes clusters in an [environment](environments.md) for deployment. Use pipelines to deploy to Azure Kubernetes Service (AKS) and clusters from any other cloud provider. -You can use Kubernetes resources with public or private clusters. To learn more about how resources work, see [resources in YAML](resources.md) and [security with resources](../security/resources.md). +You can use Kubernetes resources with public or private clusters. For more information about how resources work, see [resources in YAML](resources.md) and [security with resources](../security/resources.md). + +> [!NOTE] +> If you're using a private AKS cluster, make sure you're connected to the cluster's virtual network as the the API server endpoint is not exposed through a public IP address. +> +> Azure Pipelines recommends setting up a self-hosted agent within a VNET that has access to the cluster's virtual network. See [Options for connecting to the private cluster](/azure/aks/private-clusters#options-for-connecting-to-the-private-cluster) for details. ## Overview @@ -27,7 +32,7 @@ See the following advantages of using Kubernetes resource views within environme > [!div class="mx-imgBorder"] > ![Pipeline traceability](media/k8s-pipeline-traceability.png) -- **Diagnose resource health** - Workload status can be useful for quickly debugging mistakes or regressions that might have been introduced by a new deployment. For example, for unconfigured *imagePullSecrets* resulting in ImagePullBackOff errors, pod status information can help you identify the root cause for the issue. +- **Diagnose resource health** - Workload status can be useful for quickly debugging mistakes or regressions that were introduced by a new deployment. For example, for unconfigured *imagePullSecrets* resulting in ImagePullBackOff errors, pod status information can help you identify the root cause for the issue. > [!div class="mx-imgBorder"] > ![ImagePullBackOff](media/k8s-imagepullbackoff.png) @@ -42,7 +47,7 @@ A [ServiceAccount](https://kubernetes.io/docs/tasks/configure-pod-container/conf 2. Select **Azure Kubernetes Service** in the Provider dropdown. 3. Choose the Azure subscription, cluster, and namespace (new/existing). 4. Select **Validate and create** to create the Kubernetes resource. -5. Verify that you see a cluster for your environment. You'll see the text "Never deployed" if you have not yet deployed code to your cluster. +5. Verify that you see a cluster for your environment. You'll see the text "Never deployed" if you haven't yet deployed code to your cluster. :::image type="content" source="media/kubernetes-environment-cluster.png" alt-text="Add a Kubernetes cluster."::: @@ -71,7 +76,7 @@ For more information about setting up a Kubernetes service connection outside of #### Kubernetes 1.22+ Replace `service-account-name` with your account name. ``` - kubectl get secret -n -o jsonpath='{.items[?(@.metadata.annotations.kubernetes\.io/service-account\.name=="service-account-name")]}' + kubectl get secret -n -o jsonpath='{.items[?(@.metadata.annotations.kubernetes\.io/service-account\.name==\"service-account-name\")]}' ``` If you get nothing, see [Manually create a long-lived API token for a ServiceAccount](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#manually-create-a-long-lived-api-token-for-a-serviceaccount). @@ -168,7 +173,9 @@ stages: displayName: Production pool: vmImage: $(vmImageName) - environment: $(envName).$(resourceName) + environment: + name: $(envName).$(resourceName) + resourceType: Kubernetes strategy: runOnce: deploy: @@ -198,7 +205,9 @@ stages: pool: vmImage: $(vmImageName) - environment: $(envName).$(resourceName) + environment: + name: $(envName).$(resourceName) + resourceType: Kubernetes strategy: runOnce: deploy: diff --git a/docs/pipelines/process/environments-virtual-machines.md b/docs/pipelines/process/environments-virtual-machines.md index 8a9f0bae509..468501d40ca 100644 --- a/docs/pipelines/process/environments-virtual-machines.md +++ b/docs/pipelines/process/environments-virtual-machines.md @@ -1,80 +1,100 @@ --- -title: Environment - Virtual machine resource -description: Virtual machine resource support within Environment -ms.topic: conceptual +title: Manage VM resources in environments +description: Learn how to create and use virtual machine (VM) resources in Azure Pipelines environments. +ms.topic: how-to ms.custom: pipelinesresourcesrefresh ms.assetid: b318851c-4240-4dc2-8688-e70aba1cec55 ms.manager: mijacobs -ms.date: 01/12/2023 +ms.date: 07/12/2024 monikerRange: '>= azure-devops-2020' --- -# Environment - virtual machine resource +# Manage VM resources in environments [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -Use virtual machine (VM) resources to manage deployments across multiple machines with YAML pipelines. VM resources let you install agents on your own servers for rolling deployments. +This article describes how to use virtual machine (VM) resources in environments to manage Azure Pipelines deployments across multiple machines. You can also install agents on your own servers for rolling deployments. -VM resources connect to [environments](environments.md). After you define an environment, you can add VMs to target with deployments. The deployment history view in an environment provides traceability from your VM to your pipeline. +VM resources can exist in [environments](environments.md), such as Development, Test, or Production. After you define an environment, you can add VMs to target with deployments. The environment's deployment history provides traceability from each VM to your pipeline. ## Prerequisites -You must have at least a Basic license and access to the following areas: +### [Linux](#tab/linux) -- the repository connected to your pipeline -- the VM you want to connect to the environment +- Access to a source repository that's connected to your pipeline. +- Access and permission to download and run executable scripts on the VMs you want to connect to the environment. +- Project Administrator or Build Administrator [permissions](../policies/permissions.md) in the Azure DevOps project that contains the environment. For more information, see [Pipeline security resources](../security/resources.md). +- [Administrator role](../agents/pools-queues.md#security) for the *deployment pool*, or set of target servers available to the organization. For more information, see [deployment pool and environment permissions](../policies/permissions.md#deployment-group-permissions). -For more information about security for Azure Pipelines, see [Pipeline security resources](../security/resources.md). +### [Windows](#tab/windows) -To add a VM to an environment, you must have the [Administrator role](../agents/pools-queues.md#security) for the corresponding deployment pool. A deployment pool is a set of target servers available to the organization. Learn more about [deployment pool and environment permissions](../policies/permissions.md#set-deployment-pool-permissions). +- Access to a source repository that's connected to your pipeline. +- Access to and PowerShell administrator permissions on VMs you want to connect to the environment. +- Project Administrator or Build Administrator [permissions](../policies/permissions.md) in the Azure DevOps project that contains the environment. For more information, see [Pipeline security resources](../security/resources.md). +- [Administrator role](../agents/pools-queues.md#security) for the *deployment pool*, or set of target servers available to the organization. For more information, see [deployment pool and environment permissions](../policies/permissions.md#deployment-group-permissions). + +--- > [!NOTE] -> If you are configuring a deployment group agent, or if you see an error when registering a VM environment resource, you must set the PAT scope to **All accessible organizations**. +> To configure a deployment group agent, or if you see an error when registering a VM environment resource, make sure you set your personal access token (PAT) scope to **All accessible organizations**. -## Create a VM resource +## Create the environment -> [!NOTE] -> You can use this same process to set up physical machines with a registration script. +Use the following procedure to add a VM resource to an environment. You can use the same process to set up physical machines. + +### Add a VM resource + +1. In your Azure DevOps project, go to **Pipelines** > **Environments** and then select **Create environment** or **New environment**. +1. On the first **New environment** screen, add a **Name** and an optional **Description**. +1. Under **Resource**, select **Virtual machines**, and then select **Next**. + + :::image type="content" source="media/create-environment.png" alt-text="Screenshot that shows adding an environment."::: + +### Copy the registration script -The first step in adding a VM resource is to define an environment. +The agent scripts for VM resources are like the scripts for self-hosted agents, and use the same commands. The scripts include an Azure DevOps Personal Access Token (PAT) for the signed-in user, which expires three hours after the script is generated. -### Define an environment +### [Linux](#tab/linux) -1. Select **Create environment** or **New environment**, depending on whether it's your first environment. -1. Add a **Name** (required) for the environment and a **Description**. -1. Save the new environment. +1. On the next **New environment** screen, choose Linux under **Operating system**. +1. Copy the Linux registration script. -### Add a resource + :::image type="content" source="media/vm-creation-linux.png" alt-text="Screenshot that shows adding a virtual machine."::: -1. Select your environment and choose **Add resource**. -1. Select **Virtual machines** for your **Resource** type. Then select **Next**. +The script is the same for all the Linux VMs added to the environment. For more information about installing the agent script, see [Self-hosted Linux agents](../agents/linux-agent.md). - :::image type="content" source="media/create-environment.png" alt-text="Add an environment."::: +### [Windows](#tab/windows) -1. Choose Windows or Linux for the **Operating System**. -1. Copy the registration script. Your script will be a [PowerShell script](/powershell/scripting/overview) if you've selected Windows and a Linux script if you've selected Linux. +1. On the next **New environment** screen, choose Windows under **Operating system**. +1. Copy the [PowerShell](/powershell/scripting/overview) registration script. :::image type="content" source="media/vm-creation.png" alt-text="Add a virtual machine."::: -1. Run the copied script on each of the target virtual machines that you want to register with this environment. - - If you're installing on Windows, you'll need to run the script an PowerShell administrator. - - If you're installing on Linux, you'll need to have permission to download and run executable scripts. +The script is the same for all the Windows VMs added to the environment. For more information about installing the agent script, see [Self-hosted Windows agents](../agents/windows-agent.md). + +--- + +### Run the copied script + +1. Select **Close**, and note that the new environment is created. To copy the script again, for example if your PAT expires, select **Add resource**. + + :::image type="content" source="media/environment-new.png" alt-text="Screenshot of the new environment created message."::: + +1. Run the copied script on each target VM that you want to register with the environment. > [!NOTE] - > - > - The Personal Access Token (PAT) for the signed-in user gets included in the script. The PAT expires on the day you generate the script. - > - If your VM already has any other agent running on it, provide a unique name for **agent** to register with the environment. - > - To learn more about installing the agent script, see [Self-hosted Linux agents](../agents/linux-agent.md) and [Self-hosted Windows agents](../agents/windows-agent.md). The agent scripts for VM resources are like the scripts for self-hosted agents and you can use the same commands. + > If the VM already has another agent running on it, provide a unique name for **agent** to register with the environment. -1. Once your VM is registered, it appears as an environment resource under the **Resources** tab of the environment. -1. To add more VMs, copy the script again. Select **Add resource** > **Virtual machines**. The Windows and Linux scripts are the same for all the VMs added to the environment. -1. When the VM script is successfully installed, your VM appears in the list of resources for the environment. +Once the VM is registered, it appears as a resource under the **Resources** tab of the environment. - :::image type="content" source="media/vm-resourceview.png" alt-text="View resources."::: +:::image type="content" source="media/vm-resourceview.png" alt-text="Screenshot of the Resources tab."::: -## Use VM in pipelines +## Use VMs in pipelines -Target VMs in your pipeline by referencing the environment. By default, the pipeline job runs for all of the VMs defined for an environment with a `resourceName`. +In your YAML pipeline, you can target VMs by referencing their environment. By default, the job targets all the VMs registered for that environment's `resourceName`. + +>[!NOTE] +>When you retry a stage, the deployment reruns on all VMs, not just failed targets. ```yaml trigger: @@ -98,9 +118,9 @@ jobs: ``` > [!NOTE] -> The `resourceType` values are case sensitive. Specifying the incorrect casing will result in no matching resources found in the environment. See the [YAML schema](/azure/devops/pipelines/yaml-schema/jobs-deployment-environment) for more information. +> The `resourceType` values like `virtualMachine` are case sensitive. Incorrect casing results in no matching resources found. -You can select a specific virtual machine from the environment to only receive the deployment by specifying it by its `resourceName`. For example, to target deploying only to the Virtual Machine resource named `USHAN-PC` in the `VMenv` environment, add the `resourceName` parameter and give it the value of `USHAN-PC`. +You can deploy to specific VMs in the environment by specifying them in `resourceName`. The following example deploys only to the VM resource named `RESOURCE-PC` in the `VMenv` environment. ```yaml trigger: @@ -115,7 +135,7 @@ jobs: environment: name: VMenv resourceType: virtualMachine - resourceName: USHAN-PC # only deploy to the VM resource named USHAN-PC + resourceName: RESOURCE-PC # only deploy to the VM resource named RESOURCE-PC strategy: runOnce: deploy: @@ -123,17 +143,17 @@ jobs: - script: echo "Hello world" ``` -To learn more about deployment jobs, see the [YAML schema](/azure/devops/pipelines/yaml-schema/jobs-deployment). +For more information about YAML pipeline deployment jobs, see the [YAML pipelines schema](/azure/devops/pipelines/yaml-schema/jobs-deployment). ## Add and manage tags -Tags give you a way to target a set of specific VMs in an environment for deployment. You can add tags to the VM as part of the interactive registration script or through the UI. Tags are each limited to 256 characters. There's no limit to the number of tags that you can use. +Tags are a way to target a specific set of VMs in an environment for deployment. Tags are limited to 256 characters each. There's no limit to the number of tags that you can use. -Add or remove tags in the UI from the resource view by selecting **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: for a VM resource. +You can add tags or remove tags for VMs in the interactive registration script or through the UI by selecting **More actions** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: for a VM resource. -:::image type="content" source="media/vm-tags.png" alt-text="Set VM tags."::: +:::image type="content" source="media/vm-tags.png" alt-text="Screenshot that shows setting VM tags."::: -When you select multiple tags, VMs that include all the tags get used in your pipeline. For example, this pipeline targets VMs with both the `windows` and `prod` tags. If a VM only has one of these tags, it's not targeted. +If you specify multiple tags, the pipeline uses only VMs that include all the tags. The following example targets only VMs that have both the `windows` and `prod` tags. VMs that have only one or none of the tags aren't targeted. ```yaml trigger: @@ -148,7 +168,7 @@ jobs: environment: name: VMenv resourceType: virtualMachine - tags: windows,prod # only deploy to virtual machines with both windows and prod tags + tags: windows,prod # only deploy to VMs with both windows and prod tags strategy: runOnce: deploy: @@ -158,44 +178,40 @@ jobs: ## Apply deployment strategy -Apply a deployment strategy to define how your application gets rolled out. The `runOnce` strategy and the `rolling` strategy for VMs are both supported. -For more information about deployment strategies and life-cycle hooks, see [Deployment jobs/Deployment strategies](./deployment-jobs.md#deployment-strategies). +You can apply a deployment `strategy` to define how to roll out your application. VMs support both the `runOnce` and the `rolling` strategies. For more information about deployment strategies and lifecycle hooks, see [Deployment strategies](./deployment-jobs.md#deployment-strategies). ## View deployment history Select the **Deployments** tab for complete traceability of commits and work items, and a cross-pipeline deployment history per environment and resource. -> [!div class="mx-imgBorder"] -> ![VMDeployments_view](media/vm-deployments.png) - -## Remove a VM from an environment -### Windows environment +:::image type="content" source="media/vm-deployments.png" alt-text="Screenshot that shows VM Deployments view."::: -To remove VMs from a Windows environment, run the following command. -Ensure you do the following tasks: +## Remove a VM from an environment -- Run the command from an administrator PowerShell command prompt -- Run the command on each machine -- Run the command in the same folder path as the environment registration command was run +### [Linux](#tab/linux) + +To remove a VM from a Linux environment, run the following command on each machine. ``` -./config.cmd remove +./config.sh remove ``` -### Linux environment +### [Windows](#tab/windows) -To remove a VM from a Linux environment, run the following command on each machine. +To remove VMs from a Windows environment, run the following command. Make sure you run the command: + +- On each machine. +- From an administrator PowerShell command prompt. +- In the same folder path as the environment registration command. ``` -./config.sh remove +./config.cmd remove ``` -## Known limitations - -When you retry a stage, it reruns the deployment on all VMs and not just failed targets. +--- -## Related articles +## Related content -- [About environments](environments.md) -- [Learn about deployment jobs](deployment-jobs.md) -- [YAML schema reference](/azure/devops/pipelines/yaml-schema) +- [Create and target environments](environments.md) +- [Deployment jobs](deployment-jobs.md) +- [YAML pipelines schema reference](/azure/devops/pipelines/yaml-schema) diff --git a/docs/pipelines/process/environments.md b/docs/pipelines/process/environments.md index 7177073de3e..bb4fc9cabc5 100644 --- a/docs/pipelines/process/environments.md +++ b/docs/pipelines/process/environments.md @@ -1,63 +1,74 @@ --- -title: Create target environment -description: Collection of deployment targets useful for traceability and recording deployment history. +title: Create and target Azure DevOps environments for pipelines +description: Learn how to create, target, secure, and view deployment history for Azure DevOps environments. Manage Kubernetes and virtual machine resources for CI/CD pipelines. ms.topic: how-to ms.assetid: 4abec444-5d74-4959-832d-20fd0acee81d -ms.date: 04/10/2023 +ms.date: 04/09/2025 monikerRange: '>= azure-devops-2020' +keywords: Azure DevOps environments, CI/CD pipelines, Kubernetes, virtual machines, deployment history, secure environments --- -# Create and target an environment +# Create and target Azure DevOps environments [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -An environment is a collection of [resources](about-resources.md) that you can target with deployments from a pipeline. Typical examples of environment names are Dev, Test, QA, Staging, and Production. An Azure DevOps environment represents a logical target where your pipeline deploys software. +This article explains how to create and target Azure Pipelines environments. An environment is a group of [resources](about-resources.md) that you can target with deployments from a pipeline. -Azure DevOps environments aren't available in classic pipelines. For classic pipelines, [deployment groups](../release/deployment-groups/index.md) offer similar functionality. +An environment represents a logical target where your pipeline deploys software. Common environment names include Dev, Test, QA, Staging, and Production. +>[!NOTE] +> Azure DevOps environments aren't available in Classic pipelines. For Classic pipelines, [deployment groups](../release/deployment-groups/index.md) provide similar functionality. -Environments provide the following benefits. +Environments provide the following benefits: -| Benefit | Description | -|--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Deployment history** | Pipeline name and run details get recorded for deployments to an environment and its resources. In the context of multiple pipelines targeting the same environment or resource, [deployment history](#deployment-history) of an environment is useful to identify the source of changes. | -| **Traceability of commits and work items** | View jobs within the pipeline run that target an environment. You can also view the [commits and work items](#deployment-history) that were newly deployed to the environment. Traceability also allows one to track whether a code change (commit) or feature/bug-fix (work items) reached an environment. | -| **Diagnostic resource health** | Validate whether the application is functioning at its wanted state. | -| **Security** | Secure environments by specifying which users and pipelines are allowed to target an environment. | +- **Deployment history**. Pipeline name and run details are recorded for deployments to an environment and its resources. In the context of multiple pipelines targeting the same environment or resource, you can use [deployment history](#view-deployment-history) of an environment to identify the source of changes. -While an environment is a grouping of resources, the resources themselves represent actual deployment targets. The [Kubernetes resource](environments-kubernetes.md) and [virtual machine resource](environments-virtual-machines.md) types are currently supported. +- **Traceability of commits and work items**. You can view jobs within the pipeline run that target an environment. You can also view the [commits and work items](#view-deployment-history) that were newly deployed to the environment. Traceability also lets you track whether a code change commit or feature/bug-fix work item reached an environment. -When you author a YAML pipeline and refer to an environment that doesn't exist, Azure Pipelines automatically creates the environment when the user performing the operation is known and permissions can be assigned. When Azure Pipelines doesn't have information about the user creating the environment (example: a YAML update from an external code editor), your pipeline fails if the environment doesn't already exist. +- **Diagnostic resource health**. You can validate whether the application is functioning at its desired state. + +- **Security**. You can secure environments by specifying which users and pipelines are allowed to target an environment. + +An environment is a grouping of resources where the resources themselves represent actual deployment targets. Azure Pipelines environments currently support the [Kubernetes](environments-kubernetes.md) and [virtual machine](environments-virtual-machines.md) resource types. + +If a YAML pipeline refers to an environment that doesn't exist: + +- When the user performing the operation is known and permissions can be assigned, Azure Pipelines automatically creates the environment. + +- When Azure Pipelines doesn't have information about the user performing the operation, for example in a YAML update from an external code editor, the pipeline fails. ## Prerequisites -* You need to have the [**Creator** role for Environments](../library/add-resource-protection.md) to add an Environment. - +| Category | Requirements | +|--------------|-------------| +| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).
      - An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can request a free tier.
      - Basic knowledge of YAML and Azure Pipelines. For more information, see [Create your first pipeline](../create-first-pipeline.md).
      - **Permissions:**
           To add environments, the [Creator role for environments](../library/add-resource-protection.md#environments) in your project. By default, members of the **Build Administrators**, **Release Administrators**, and **Project Administrators** groups can also create environments. | +| **Azure** | An [Azure subscription](https://azure.microsoft.com/free/). | ## Create an environment -1. Sign in to your organization: ```https://dev.azure.com/{yourorganization}``` and select your project. +To create your first environment: -2. Select **Pipelines** > **Environments** > **Create environment**. +1. Sign in to your Azure DevOps organization at `https://dev.azure.com/{yourorganization}` and open your project. - > [!div class="mx-imgBorder"] - > ![Environments](media/environments-nav.png) +1. Select **Pipelines** > **Environments** > **Create environment**. -3. Enter information for the environment, and then select **Create**. Resources can be added to an existing environment later. + :::image type="content" source="media/environments-nav.png" alt-text="Screenshot that shows Environments."::: - :::image type="content" source="media/create-new-environment.png" alt-text="Screenshot of creating a new environment."::: +1. Enter information for the environment, and then select **Create**. You can add resources to an existing environment later. -Use a Pipeline to create and deploy to environments, too. For more information, see the [how-to guide](../ecosystems/kubernetes/aks-template.md). + :::image type="content" source="media/create-new-environment.png" alt-text="Screenshot of creating a new environment."::: > [!TIP] -> You can create an empty environment and reference it from deployment jobs. This lets you record the deployment history against the environment. +> Create an empty environment and reference it from deployment jobs to record deployment history against the environment. - +To programmatically create and manage environments, use the [Azure DevOps Environments REST API](/rest/api/azure/devops/environments/environments). + +You can use Azure Pipelines to deploy to environments. For more information, see [Build and deploy to Azure Kubernetes Service with Azure Pipelines](../ecosystems/kubernetes/aks-template.md). ## Target an environment from a deployment job -A [deployment job](deployment-jobs.md) is a collection of steps to be run sequentially. A deployment job can be used to target an entire environment (group of resources) as shown in the following YAML snippet. The pipeline will run on the myVM machine because the resource name is specified. +A [deployment job](deployment-jobs.md) contains steps that run sequentially. You can use a deployment job to target an entire environment group of resources, as shown in the following example YAML snippet. The pipeline runs on the `myVM` machine because that resource name is specified. ```YAML - stage: deploy @@ -67,7 +78,8 @@ A [deployment job](deployment-jobs.md) is a collection of steps to be run sequen pool: vmImage: 'Ubuntu-latest' # creates an environment if it doesn't exist - environment: 'smarthotel-dev' + environment: + name: 'smarthotel-dev' resourceName: myVM resourceType: virtualMachine strategy: @@ -77,15 +89,15 @@ A [deployment job](deployment-jobs.md) is a collection of steps to be run sequen - script: echo Hello world ``` +## Target a specific environment resource from a deployment job - - -## Target a specific resource within an environment from deployment job +You can scope the deployment target to a particular resource within the environment, so you can record deployment history on the specific resource. The steps of the deployment job automatically inherit the service connection details from the resource the deployment job targets. -You can scope the target of deployment to a particular resource within the environment. Then, you can record deployment history on a specific resource within the environment. The steps of the deployment job *automatically inherit* the service connection details from the resource targeted by the deployment job. +In the following example, the value for the `kubernetesServiceConnection` automatically passes down to the task from the `environment.resource` input. ```YAML -environment: 'smarthotel-dev.bookings' +environment: + name: 'smarthotel-dev.bookings' strategy: runOnce: deploy: @@ -98,94 +110,98 @@ strategy: manifests: $(System.ArtifactsDirectory)/manifests/* imagePullSecrets: $(imagePullSecret) containers: $(containerRegistry)/$(imageRepository):$(tag) - # value for kubernetesServiceConnection input automatically passed down to task by environment.resource input ``` - +> [!NOTE] +> If you're using a private AKS cluster, make sure you're connected to the cluster's virtual network as the API server endpoint isn't exposed through a public IP address. +> +> Azure Pipelines recommends setting up a self-hosted agent within a VNET that has access to the cluster's virtual network. See [Options for connecting to the private cluster](/azure/aks/private-clusters#options-for-connecting-to-the-private-cluster) for details. -## Environment in run details +## Use manual approval checks -All environments that get targeted by deployment jobs of a specific run of a pipeline can be found under the *Environments* tab of pipeline run details. +To control deployments to production environments, Azure Pipelines supports manual approval checks. These checks allow resource owners to control when a stage in a pipeline consumes the resource. Resource owners can define approvals and checks that must be satisfied before a stage consuming that resource can begin. - > [!div class="mx-imgBorder"] - > ![Environments in run details](media/environments-run.png) - -If you're using an AKS private cluster, the **Environments** tab isn't available. +The environment **Creator**, **Administrator**, and **User** roles, but not the **Reader** role, can manage approvals and checks. As an environment owner, you can manually control when a stage should run by using approval checks. For more information, see [Define approvals and checks](approvals.md). -## Approvals +## See environments in run details -Manually control when a stage should run using approval checks. Use approval checks to control deployments to production environments. Checks are available to the resource Owner to control when a stage in a pipeline consumes a resource. As the owner of a resource, such as an environment, you can [define approvals and checks](approvals.md) that must be satisfied before a stage consuming that resource starts. +Under the **Environments** tab of the pipeline run details, you can see all environments that were targeted by deployment jobs of a pipeline run. -We support manual approval checks on environments. For more information, see [Approvals](approvals.md). +:::image type="content" source="media/environments-run.png" alt-text="Screenshot that shows Environments in run details."::: -The Creator, Administrator, and user roles can manage approvals and checks. The Reader role can't manage approvals and checks. +>[!NOTE] +>If you're using an Azure Kubernetes Service (AKS) private cluster, the **Environments** tab isn't available. - +## View deployment history -## Deployment history +You can select the **Deployments** tab in the Azure Pipelines **Environments** section to view deployment history. -The deployment history view within environments provides the following advantages. +- View jobs from all pipelines that target a specific environment. For example, two microservices that each have their own pipeline can deploy to the same environment. The deployment history helps identify all pipelines that affect the environment, and also helps visualize the sequence of deployments by each pipeline. -- View jobs from all pipelines that target a specific environment. For example, two micro-services, each having its own pipeline, are deploying to the same environment. The deployment history listing helps identify all pipelines that affect this environment and also helps visualize the sequence of deployments by each pipeline. + :::image type="content" source="media/environments-deployment-history.png" alt-text="Screenshot that shows deployment history listing."::: - > [!div class="mx-imgBorder"] - > ![Screenshot of deployment history listing.](media/environments-deployment-history.png) +- To drill down into the job details, select the **Changes** and **Work items** tabs on a deployment page. The tabs show lists of commits and work items that deployed to the environment. Each list item represents new items in that deployment. -- Drill down into the job details to see the list of commits and work items that were deployed to the environment. The list of commits and work items are the new items between deployments. Your first listing includes all of the commits and the following listings will just include changes. If multiple commits are tied to the same pull request, you'll see multiple results on the work items and changes tabs. + On the **Changes** tab, the first listing includes all the commits to that point, and the following listings include just the changes for that job. If multiple commits are tied to the same job, there are multiple results on the **Changes** tab. - > [!div class="mx-imgBorder"] - > ![Screenshot of commits under deployment history.](media/environment-deployment-history-changes.png) + :::image type="content" source="media/environment-deployment-history-changes.png" alt-text="Screenshot of commits under deployment history."::: -- If multiple work items are tied to the same pull request, you'll see multiple results on the work items tab. - - > [!div class="mx-imgBorder"] - > ![Screenshot of work items under deployment history.](media/environment-deployment-history-workitems.png) +- If multiple work items are tied to the same job, there are multiple results on the **Work items** tab. + :::image type="content" source="media/environment-deployment-history-workitems.png" alt-text="Screenshot of work items under deployment history."::: ## Security +You can secure your environments by setting user permissions and pipeline permissions. + ### User permissions -Control who can create, view, use, and manage the environments with user permissions. There are four roles - Creator (scope: all environments), Reader, User, and Administrator. In the specific environment's **user permissions** panel, you can set the permissions that are inherited and you can override the roles for each environment. +You can control who can create, view, use, and manage environments with user permissions. There are four roles: **Creator** with a scope of all environments, **Reader**, **User**, and **Administrator**. + +To add a user by using an environment's **User permissions** panel, go to the specific **Environment** you want to authorize, select the **More actions** icon, and select **Security**. -1. Go to the specific **Environment** that you want to authorize. -1. Select :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: > **Security** to view the settings. -1. Select **User permissions** > **+Add** > **User or group**, and then select a suitable role. +In the **User permissions** panel of the **Security** page, select **Add** and then select a **User or group** and suitable **Role**. + +In the **User permissions** panel, you can also set the permissions that are inherited, and override the roles for your environment. [!INCLUDE [temp](../../organizations/security/includes/environment-roles.md)] ### Pipeline permissions -Use pipeline permissions to authorize all or selected pipelines for deployment to the environment. - -- To remove **Open access** on the environment or resource, select **Restrict permission** in **Pipeline permissions**. -- To allow specific pipelines to deploy to an environment or specific resource, select **+** and choose from the list of pipelines. +Use the **Pipeline permissions** panel of the **Security** page to authorize all or selected pipelines for deployment to the environment. -## Next steps +- To remove open access on the environment or resource, select **Restrict permission** in **Pipeline permissions**. -[Define approvals and checks](approvals.md) +- When permissions are restricted, you can allow specific pipelines to deploy to the environment or to a specific resource. Select **+** and choose from the list of pipelines to allow. ## FAQ -### Q: Why do I get an error message when I try to create an environment? +### Why do I get an error message when I try to create an environment? + +If you see the message **Access denied: {User} needs Create permissions to do the action**, go to **Organization Settings** > **Users** to check if you have the **Stakeholder** role. The **Stakeholder** role can't create environments because stakeholders don't have access to the repository. + +Change your access level and then check to see if you can create environments. For more information, see [User and permissions management FAQ](../../organizations/accounts/faq-user-and-permissions-management.yml). + +### Why do I get an error that an environment can't be found? + +If you see the message **Job XXXX: Environment XXXX could not be found. The environment does not exist or has not been authorized for use.**, there are several possible reasons for the failure. -A: If you see the message "Access denied: {User} needs Create permissions to do the action", check your organization-level permissions. Go to **Organization Settings** > **Users** and check if you have the stakeholder role. The stakeholder role can't create environments. Change your access level and then check to see if you can create environments. For more information, see [User and permissions management FAQ](../../organizations/accounts/faq-user-and-permissions-management.yml). +- [Runtime parameters](runtime-parameters.md) don't work when creating environments, because the parameters are expanded only at run time. You can use [variables](./variables.md?tabs=yaml%2cbatch&view=azure-devops&preserve-view=true) to create an environment or use [templateContext to pass properties to templates](template-parameters.md#use-templatecontext-to-pass-properties-to-templates). -### Q: Why am I getting error "Job XXXX: Environment XXXX could not be found. The environment does not exist or has not been authorized for use"? + When you refer to an environment that doesn't exist in a YAML pipeline file, Azure Pipelines automatically creates the environment in the following cases: -A: These are some of the possible reasons of the failure: + - You use the YAML pipeline creation wizard in the Azure Pipelines web experience and refer to an environment that isn't created yet. + - You update the YAML file by using the Azure Pipelines web editor and save the pipeline after adding the reference to the environment. - * When you author a YAML pipeline and refer to an environment that doesn't exist in the YAML file, Azure Pipelines automatically creates the environment in some cases: - * You use the YAML pipeline creation wizard in the Azure Pipelines web experience and refer to an environment that hasn't been created yet. - * You update the YAML file using the Azure Pipelines web editor and save the pipeline after adding a reference to an environment that does not exist. + In the following cases, Azure Pipelines doesn't have information about the user creating the environment, so the pipeline fails: - * In the following flows, Azure Pipelines doesn't have information about the user creating the environment: you update the YAML file using another external code editor, add a reference to an environment that doesn't exist, and then cause a manual or continuous integration pipeline to be triggered. In this case, Azure Pipelines doesn't know about the user. Previously, we handled this case by adding all the project contributors to the administrator role of the environment. Any member of the project could then change these permissions and prevent others from accessing the environment. + - You update the YAML file by using another external code editor. + - You add a reference to an environment that doesn't exist, and then cause a manual or continuous integration pipeline to be triggered. - * You can use [variables](./variables.md?tabs=yaml%2cbatch&view=azure-devops&preserve-view=true) to create the environment or use [templateContext to pass properties to templates](template-parameters.md#use-templatecontext-to-pass-properties-to-templates). [Runtime parameters](runtime-parameters.md) won't work when creating the environment because they are expanded at run time. + Previously, Azure Pipelines handled these cases by adding all the project contributors to the administrator role of the environment. Any member of the project could then change these permissions and prevent others from accessing the environment. To prevent this outcome, Azure Pipelines now fails these jobs. - * A user with stakeholder access level can't create the environment as stakeholders don't have access to the repository. - ## Related articles +- [Define approvals and checks](approvals.md) - [Define variables](variables.md) -- [Define resources in YAML](resources.md) \ No newline at end of file +- [Define resources in YAML](resources.md) diff --git a/docs/pipelines/process/expressions.md b/docs/pipelines/process/expressions.md index 0f79f90acd5..55ca61fc6cc 100644 --- a/docs/pipelines/process/expressions.md +++ b/docs/pipelines/process/expressions.md @@ -1,11 +1,10 @@ --- title: Expressions -ms.custom: seodec18 -description: Learn about how you can use expressions in Azure Pipelines or Team Foundation Server (TFS). +description: Learn about how you can use expressions in Azure Pipelines. ms.topic: conceptual ms.assetid: 4df37b09-67a8-418e-a0e8-c17d001f0ab3 -ms.date: 05/23/2023 -monikerRange: '>= azure-devops-2019' +ms.date: 11/18/2024 +monikerRange: "<=azure-devops" --- # Expressions @@ -14,10 +13,11 @@ monikerRange: '>= azure-devops-2019' [!INCLUDE [version-selector](../../includes/version-selector.md)] -Expressions can be used in many places where you need to specify a string, boolean, or number value when authoring a pipeline. -The most common use of expressions is in [conditions](conditions.md) to determine whether a job or step should run. +Expressions can be used in many places where you need to specify a string, boolean, or number value when authoring a pipeline. When an expression returns an array, normal indexing rules apply and the index starts with `0`. -::: moniker range=">= azure-devops-2019" +The most common use of expressions is in [conditions](conditions.md) to determine whether a job or step should run. + +::: moniker range="<=azure-devops" ```yaml # Expressions are used to define conditions for a step, job, or stage steps: @@ -79,7 +79,7 @@ variables: `True` and `False` are boolean literal expressions. ### Null -Null is a special literal expression that's returned from a dictionary miss, e.g. (`variables['noSuch']`). Null can be the output of an expression but cannot be called directly within an expression. +Null is a special literal expression that's returned from a dictionary miss, for example (`variables['noSuch']`). Null can be the output of an expression but can't be called directly within an expression. ### Number Starts with '-', '.', or '0' through '9'. @@ -138,10 +138,11 @@ The following built-in functions can be used in expressions. * Short-circuits after first `False` * Example: `and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))` -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### coalesce -* Evaluates the parameters in order, and returns the value that does not equal null or empty-string. +* Evaluates the parameters in order (left to right), and returns the first value that doesn't equal null or empty-string. +* No value is returned if the parameter values all are null or empty strings. * Min parameters: 2. Max parameters: N * Example: `coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')` @@ -166,7 +167,7 @@ The following built-in functions can be used in expressions. > This function is of limited use in general pipelines. > It's intended for use in the [pipeline decorator context](../../extend/develop/pipeline-decorator-context.md) with system-provided arrays such as the list of steps. -You can use the `containsValue` expression to find a matching value in an object. Here is an example that demonstrates looking in list of source branches for a match for `Build.SourceBranch`. +You can use the `containsValue` expression to find a matching value in an object. Here's an example that demonstrates looking in list of source branches for a match for `Build.SourceBranch`. ```yaml parameters: @@ -189,7 +190,7 @@ jobs: - script: echo "Matching branch found" ``` -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### convertToJson * Take a complex object and outputs it as JSON. @@ -228,13 +229,13 @@ Script output: ``` ### counter -* This function can only be used in an expression that defines a variable. It cannot be used as part of a condition for a step, job, or stage. +* This function can only be used in an expression that defines a variable. It can't be used as part of a condition for a step, job, or stage. * Evaluates a number that is incremented with each run of a pipeline. * Parameters: 2. `prefix` and `seed`. * Prefix is a string expression. A separate value of counter is tracked for each unique value of prefix. The `prefix` should use UTF-16 characters. * Seed is the starting value of the counter -You can create a counter that is automatically incremented by one in each execution of your pipeline. When you define a counter, you provide a `prefix` and a `seed`. Here is an example that demonstrates this. +You can create a counter that is automatically incremented by one in each execution of your pipeline. When you define a counter, you provide a `prefix` and a `seed`. Here's an example that demonstrates this. ```yaml variables: @@ -246,20 +247,19 @@ steps: - bash: echo $(minor) ``` -The value of `minor` in the above example in the first run of the pipeline will be 100. In the second run it will be 101, provided the value of `major` is still 1. +The value of `minor` in the above example in the first run of the pipeline is 100. In the second run it is 101, provided the value of `major` is still 1. -If you edit the YAML file, and update the value of the variable `major` to be 2, then in the next run of the pipeline, the value of `minor` will be 100. Subsequent runs will increment the counter to 101, 102, 103, ... +If you edit the YAML file, and update the value of the variable `major` to be 2, then in the next run of the pipeline, the value of `minor` will be 100. Subsequent runs increment the counter to 101, 102, 103, ... Later, if you edit the YAML file, and set the value of `major` back to 1, then the value of the counter resumes where it left off for that prefix. In this example, it resumes at 102. -Here is another example of setting a variable to act as a counter that starts at 100, gets incremented by 1 for every run, and gets reset to 100 every day. +Here's another example of setting a variable to act as a counter that starts at 100, gets incremented by 1 for every run, and gets reset to 100 every day. > [!NOTE] > `pipeline.startTime` is not available outside of expressions. `pipeline.startTime` > formats `system.pipelineStartTime` into a date and time object so that it is available to work with expressions. > The default time zone for `pipeline.startTime` is UTC. You can [change the time zone](../../organizations/accounts/change-time-zone.md) for your organization. - ```yaml jobs: - job: @@ -269,7 +269,7 @@ jobs: - bash: echo $(a) ``` -Here is an example of having a counter that maintains a separate value for PRs and CI runs. +Here's an example of having a counter that maintains a separate value for PRs and CI runs. ```yaml variables: @@ -294,7 +294,7 @@ Counters are scoped to a pipeline. In other words, its value is incremented for * Ordinal ignore-case comparison for Strings * Example: `eq(variables.letters, 'ABC')` -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### format * Evaluates the trailing parameters and inserts them into the leading parameter string @@ -328,13 +328,21 @@ Counters are scoped to a pipeline. In other words, its value is incremented for * Short-circuits after first match * Example: `in('B', 'A', 'B', 'C')` (returns True) -::: moniker range="> azure-devops-2019" +::: moniker range=">= azure-devops" +### iif +* Returns the second parameter if the first parameter evaluates to `True`, and the third parameter otherwise +* Min parameters: 1. Max parameters: 3 +* The first parameter must be a condition +* Example: `iif(eq(variables['Build.Reason'], 'PullRequest'), 'ManagedDevOpsPool', 'Azure Pipelines')` returns 'ManagedDevOpsPool' when the pipeline runs in response to a PR. +::: moniker-end + +::: moniker range="<=azure-devops" ### join * Concatenates all elements in the right parameter array, separated by the left parameter string. * Min parameters: 2. Max parameters: 2 * Each element in the array is converted to a string. Complex objects are converted to empty string. -* If the right parameter is not an array, the result is the right parameter converted to a string. +* If the right parameter isn't an array, the result is the right parameter converted to a string. In this example, a semicolon gets added between each item in the array. The parameter type is an object. @@ -368,7 +376,7 @@ steps: * Min parameters: 1. Max parameters 1 * Example: `length('fabrikam')` returns 8 -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" ### lower * Converts a string or variable value to all lowercase characters * Min parameters: 1. Max parameters 1 @@ -397,7 +405,7 @@ steps: * Example: `not(eq(1, 2))` (returns True) ### notIn -* Evaluates `True` if left parameter is not equal to any right parameter +* Evaluates `True` if left parameter isn't equal to any right parameter * Min parameters: 1. Max parameters: N * Converts right parameters to match type of left parameter. Equality comparison evaluates `False` if conversion fails. * Ordinal ignore-case comparison for Strings @@ -411,7 +419,7 @@ steps: * Short-circuits after first `True` * Example: `or(eq(1, 1), eq(2, 3))` (returns True, short-circuits) -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" ### replace * Returns a new string in which all instances of a string in the current instance are replaced with another string * Min parameters: 3. Max parameters: 3 @@ -419,7 +427,7 @@ steps: * Example: `replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server')` (returns `http://server/saml/consume`) ::: moniker-end -::: moniker range=">= azure-devops" +::: moniker range=">= azure-devops-2022" ### split * Splits a string into substrings based on the specified delimiting characters @@ -427,12 +435,12 @@ steps: * The first parameter is the string to split * The second parameter is the delimiting characters * Returns an array of substrings. The array includes empty strings when the delimiting characters appear consecutively or at the end of the string -* Example: +* Example: ```yml variables: - name: environments - value: prod1,prod2 - steps: + value: prod1,prod2 + steps: - ${{ each env in split(variables.environments, ',')}}: - script: ./deploy.sh --environment ${{ env }} ``` @@ -446,13 +454,13 @@ steps: - /subscriptions/mysubscription02/resourceGroups/myResourceGroup02/providers/Microsoft.Network/loadBalancers/kubernetes - name: environments type: object - default: + default: - prod1 - prod2 trigger: - main - + steps: - ${{ each env in parameters.environments }}: - ${{ each resourceId in parameters.resourceIds }}: @@ -468,7 +476,14 @@ steps: * Performs ordinal ignore-case comparison * Example: `startsWith('ABCDE', 'AB')` (returns True) -::: moniker range="> azure-devops-2019" +::: moniker range=">= azure-devops" +### trim +* Returns the parameter without leading and trailing white spaces +* Min parameters: 1. Max parameters: 1 +* Example: `trim(' variable ') ` returns 'variable' +::: moniker-end + +::: moniker range="<=azure-devops" ### upper * Converts a string or variable value to all uppercase characters * Min parameters: 1. Max parameters 1 @@ -476,21 +491,19 @@ steps: * Example: `upper('bah')` returns `BAH` ::: moniker-end - ### xor * Evaluates `True` if exactly one parameter is `True` * Min parameters: 2. Max parameters: 2 * Casts parameters to Boolean for evaluation * Example: `xor(True, False)` (returns True) -

      Job status check functions

      You can use the following status check functions as expressions in conditions, but not in variable definitions.

      always

      -* Always evaluates to True (even when canceled). Note: A critical failure may still prevent a task from running. For example, if getting sources failed. +* Always evaluates to `True` (even when canceled). Note: A critical failure may still prevent a task from running. For example, if getting sources failed. ### canceled * Evaluates to `True` if the pipeline was canceled. @@ -503,7 +516,7 @@ You can use the following status check functions as expressions in conditions, b ### succeeded * For a step, equivalent to `in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')` -* Use with `dependsOn` when working with jobs and you want to evaluate whether a previous job was successful. Jobs are designed to run in parallel while stages run sequentially. +* Use with `dependsOn` when working with jobs and you want to evaluate whether a previous job was successful. Jobs are designed to run in parallel while stages run sequentially. * For a job: * With no arguments, evaluates to `True` only if all previous jobs in the dependency graph succeeded or partially succeeded. * With job names as arguments, evaluates to `True` if all of those jobs succeeded or partially succeeded. @@ -521,17 +534,17 @@ You can use the following status check functions as expressions in conditions, b ## Conditional insertion ::: moniker range=">=azure-devops-2022" -You can use `if`, `elseif`, and `else` clauses to conditionally assign variable values or set inputs for tasks. You can also conditionally run a step when a condition is met. +You can use `if`, `elseif`, and `else` clauses to conditionally assign variable values or set inputs for tasks. You can also conditionally run a step when a condition is met. ::: moniker-end ::: moniker range="< azure-devops-2022" -You can use `if` to conditionally assign variable values or set inputs for tasks. You can also conditionally run a step when a condition is met. +You can use `if` to conditionally assign variable values or set inputs for tasks. You can also conditionally run a step when a condition is met. -The `elseif` and `else` clauses are are available starting with Azure DevOps 2022 and are not available for Azure DevOps Server 2020 and earlier versions of Azure DevOps. +The `elseif` and `else` clauses are available starting with Azure DevOps 2022 and aren't available for Azure DevOps Server 2020 and earlier versions of Azure DevOps. ::: moniker-end -Conditionals only work when using template syntax. Learn more about [variable syntax](variables.md#understand-variable-syntax). +Conditionals only work when using template syntax. Learn more about [variable syntax](variables.md#understand-variable-syntax). For templates, you can use conditional insertion when adding a sequence or mapping. Learn more about [conditional insertion in templates](templates.md). @@ -568,7 +581,7 @@ steps: ### Conditionally run a step -If there is no variable set, or the value of `foo` does not match the `if` conditions, the `else` statement will run. Here the value of `foo` returns true in the `elseif` condition. +If there's no variable set, or the value of `foo` doesn't match the `if` conditions, the `else` statement runs. Here the value of `foo` returns true in the `elseif` condition. ```yaml variables: @@ -583,7 +596,7 @@ steps: - ${{ if eq(variables.foo, 'adaptum') }}: - script: echo "this is adaptum" - ${{ elseif eq(variables.foo, 'contoso') }}: # true - - script: echo "this is contoso" + - script: echo "this is contoso" - ${{ else }}: - script: echo "the value is not adaptum or contoso" ``` @@ -593,7 +606,7 @@ steps: ## Each keyword -You can use the `each` keyword to loop through parameters with the object type. +You can use the `each` keyword to loop through parameters with the object type. ```yaml parameters: @@ -623,7 +636,7 @@ steps: - ${{ each fruit in parameters.listOfFruits }} : - ${{ each fruitColor in fruit.colors}} : - script: echo ${{ fruit.fruitName}} ${{ fruitColor }} -``` +``` ## Dependencies @@ -642,7 +655,7 @@ If you experience issues with output variables having quote characters (`'` or ` ### Dependency syntax overview -The syntax of referencing output variables with dependencies varies depending on the circumstances. Here's an overview of the most common scenarios. Note that there may be times when alternate syntax also works. +The syntax of referencing output variables with dependencies varies depending on the circumstances. Here's an overview of the most common scenarios. There might be times when alternate syntax also works. :::row::: :::column span="1"::: @@ -657,28 +670,28 @@ The syntax of referencing output variables with dependencies varies depending on [stage to stage dependency](#stage-to-stage-dependencies) (different stages) :::column-end::: :::column span="2"::: - Reference an output variable from a previous stage in a job in a different stage in a condition in `stages`. - - Syntax: `and(succeeded(), eq(stageDependencies..outputs['..'], 'true'))` + Reference an output variable from a previous stage in a job in a different stage in a condition in `stages`. + - Syntax: `and(succeeded(), eq(stageDependencies..outputs['..'], 'true'))` - Example: `and(succeeded(), eq(stageDependencies.A.outputs['A1.printvar.shouldrun'], 'true'))` :::column-end::: :::row-end::: :::row::: :::column span=""::: - [job to job dependency](#job-to-job-dependencies-within-one-stage) (same stage) + [job to job dependency](#job-to-job-dependencies-within-one-stage) (same stage) :::column-end::: :::column span="2"::: - Reference an output variable in a different job in the same stage in `stages`. - - Syntax: `and(succeeded(), eq(dependencies..outputs['.'], 'true'))` - - Example: `and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))` + Reference an output variable in a different job in the same stage in `stages`. + - Syntax: `and(succeeded(), eq(dependencies..outputs['.'], 'true'))` + - Example: `and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))` :::column-end::: :::row-end::: :::row::: :::column span=""::: - [Job to stage dependency](#job-to-job-dependencies-across-stages) (different stages) + [Job to stage dependency](#job-to-job-dependencies-across-stages) (different stages) :::column-end::: :::column span="2"::: Reference an output variable in a different stage in a `job`. - - Syntax: `eq(stageDependencies...outputs['.'], 'true')` + - Syntax: `eq(stageDependencies...outputs['.'], 'true')` - Example: `eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')` :::column-end::: :::row-end::: @@ -697,14 +710,13 @@ The syntax of referencing output variables with dependencies varies depending on [Stage to stage dependency](#deployment-job-output-variables) (deployment job with resource) :::column-end::: :::column span="2"::: - Reference an output variable in a deployment job that includes a resource in different stage in `stages`. + Reference an output variable in a deployment job that includes a resource in different stage in `stages`. - Syntax: `eq(dependencies..outputs['...'], 'true')` - - Example: `eq(dependencies.build.outputs['build_job.Deploy_winVM.setRunTests.runTests'], 'true')` + - Example: `eq(dependencies.build.outputs['build_job.Deploy_winVM.setRunTests.runTests'], 'true')` :::column-end::: :::row-end::: -There are also different syntaxes for output variables in deployment jobs depending on the deployment strategy. For more information, see [Deployment jobs](deployment-jobs.md#support-for-output-variables). - +There are also different syntaxes for output variables in deployment jobs depending on the deployment strategy. For more information, see [Deployment jobs](deployment-jobs.md#support-for-output-variables). ### Stage to stage dependencies Structurally, the `dependencies` object is a map of job and stage names to `results` and `outputs`. @@ -729,7 +741,7 @@ Expressed as JSON, it would look like: Use this form of `dependencies` to map in variables or check conditions at a stage level. -In this example, there are two stages, A and B. Stage A has the condition `false` and won't ever run as a result. Stage B runs if the result of Stage A is `Succeeded`, `SucceededWithIssues`, or `Skipped`. Stage B will run because Stage A was skipped. +In this example, there are two stages, A and B. Stage A has the condition `false` and won't ever run as a result. Stage B runs if the result of Stage A is `Succeeded`, `SucceededWithIssues`, or `Skipped`. Stage B runs because Stage A was skipped. ```yaml stages: @@ -748,8 +760,7 @@ stages: ``` Stages can also use output variables from another stage. -In this example, there are also two stages. Stage A includes a job, A1, that sets an output variable `shouldrun` to `true`. Stage B runs when `shouldrun` is `true`. Because `shouldrun` is `true`, Stage B runs. Note that `stageDependencies` is used in the condition because you are referring to an output variable in a different stage. - +In this example, there are also two stages. Stage A includes a job, A1, that sets an output variable `shouldrun` to `true`. Stage B runs when `shouldrun` is `true`. Because `shouldrun` is `true`, Stage B runs. ```yaml stages: @@ -763,7 +774,7 @@ stages: name: printvar - stage: B - condition: and(succeeded(), eq(stageDependencies.A.outputs['A1.printvar.shouldrun'], 'true')) + condition: and(succeeded(), eq(dependencies.A.outputs['A1.printvar.shouldrun'], 'true')) dependsOn: A jobs: - job: B1 @@ -793,8 +804,8 @@ At the job level within a single stage, the `dependencies` data doesn't contain } ``` -In this example, there are three jobs (a, b, and c). Job a will always be skipped because of `condition: false`. -Job b runs because there are no associated conditions. +In this example, there are three jobs (a, b, and c). Job a will always be skipped because of `condition: false`. +Job b runs because there are no associated conditions. Job c runs because all of its dependencies either succeed (job b) or are skipped (job a). ```yaml @@ -865,8 +876,8 @@ This requires using the `stageDependencies` context. } ``` -In this example, job B1 will run if job A1 is skipped. -Job B2 will check the value of the output variable from job A1 to determine whether it should run. +In this example, job B1 runs if job A1 is skipped. +Job B2 checks the value of the output variable from job A1 to determine whether it should run. ```yaml stages: @@ -921,7 +932,7 @@ stages: - stage: test dependsOn: - 'build' - jobs: + jobs: - job: run_tests condition: eq(stageDependencies.build.build_job.outputs['build_job.setRunTests.runTests'], 'true') steps: @@ -967,7 +978,7 @@ stages: - script: echo Hello from job A ``` -In the example above, the condition references an environment and not an environment resource. To reference an environment resource, you'll need to add the environment resource name to the dependencies condition. In the following example, condition references an environment virtual machine resource named `vmtest`. +In the example above, the condition references an environment and not an environment resource. To reference an environment resource, you'll need to add the environment resource name to the dependencies condition. In the following example, condition references an environment virtual machine resource named `vmtest`. ```yml stages: @@ -1048,10 +1059,20 @@ steps: - script: echo $(secondEval) ``` +When you use the `eq()` expression for evaluating equivalence, values are implicitly converted to numbers (`false` to `0` and `true` to `1`). + +```yaml +variables: + trueAsNumber: $[eq('true', true)] # 1 vs. 1, True + falseAsNumber: $[eq('false', true)] # 0 vs. 1, False -In this example, the values `variables.emptyString` and the empty string both evaluate as empty strings. -The function `coalesce()` evaluates the parameters in order, and returns the first value that does not equal null or empty-string. +steps: +- script: echo $(trueAsNumber) +- script: echo $(falseAsNumber) +``` +In this next example, the values `variables.emptyString` and the empty string both evaluate as empty strings. +The function `coalesce()` evaluates the parameters in order, and returns the first value that doesn't equal null or empty-string. ```yaml variables: @@ -1090,7 +1111,7 @@ To string: ### Number * To Boolean: `0` → `False`, any other number → `True` -* To version: Must be greater than zero and must contain a non-zero decimal. Must be less than [Int32.MaxValue](/dotnet/api/system.int32.maxvalue) (decimal component also). +* To version: Must be greater than zero and must contain a nonzero decimal. Must be less than [Int32.MaxValue](/dotnet/api/system.int32.maxvalue) (decimal component also). * To string: Converts the number to a string with no thousands separator and no decimal separator. @@ -1111,7 +1132,7 @@ runs C#'s `Version.TryParse`. Must contain Major and Minor component at minimum. -### I want to do something that is not supported by expressions. What options do I have for extending Pipelines functionality? +### I want to do something that isn't supported by expressions. What options do I have for extending Pipelines functionality? You can customize your Pipeline with a script that includes an expression. For example, this snippet takes the `BUILD_BUILDNUMBER` variable and splits it with Bash. This script outputs two new variables, `$MAJOR_RUN` and `$MINOR_RUN`, for the major and minor run numbers. The two variables are then used to create two pipeline variables, `$major` and `$minor` with [task.setvariable](../scripts/logging-commands.md#task-commands). These variables are available to downstream steps. To share variables across pipelines see [Variable groups](../../pipelines/library/variable-groups.md). diff --git a/docs/pipelines/process/includes/masked-secrets.md b/docs/pipelines/process/includes/masked-secrets.md new file mode 100644 index 00000000000..8c5a7e29111 --- /dev/null +++ b/docs/pipelines/process/includes/masked-secrets.md @@ -0,0 +1,11 @@ +--- +ms.topic: include +ms.service: azure-devops-pipelines +ms.manager: mijacobs +ms.author: sdanie +author: steved0x +ms.date: 10/20/2023 +--- + +> [!NOTE] +> Azure Pipelines makes an effort to mask secrets when emitting data to pipeline logs, so you may see additional variables and data masked in output and logs that are not set as secrets. diff --git a/docs/pipelines/process/includes/parameter-data-types.md b/docs/pipelines/process/includes/parameter-data-types.md index 7d78b066161..c32a31b0b86 100644 --- a/docs/pipelines/process/includes/parameter-data-types.md +++ b/docs/pipelines/process/includes/parameter-data-types.md @@ -4,7 +4,8 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 02/22/2023 +ms.date: 08/30/2024 +ai-usage: ai-assisted --- | Data type | Notes | @@ -26,56 +27,63 @@ The step, stepList, job, jobList, deployment, deploymentList, stage, and stageLi ```yaml parameters: -- name: myString - type: string - default: a string -- name: myMultiString - type: string - default: default - values: - - default - - ubuntu -- name: myNumber - type: number - default: 2 - values: - - 1 - - 2 - - 4 - - 8 - - 16 -- name: myBoolean - type: boolean - default: true -- name: myObject - type: object - default: - foo: FOO - bar: BAR - things: - - one - - two - - three - nested: - one: apple - two: pear - count: 3 -- name: myStep - type: step - default: - script: echo my step -- name: mySteplist - type: stepList - default: - - script: echo step one - - script: echo step two +- name: myString # Define a parameter named 'myString' + type: string # The parameter type is string + default: a string # Default value is 'a string' -trigger: none +- name: myMultiString # Define a parameter named 'myMultiString' + type: string # The parameter type is string + default: default # Default value is 'default' + values: # Allowed values for 'myMultiString' + - default + - ubuntu + +- name: myNumber # Define a parameter named 'myNumber' + type: number # The parameter type is number + default: 2 # Default value is 2 + values: # Allowed values for 'myNumber' + - 1 + - 2 + - 4 + - 8 + - 16 + +- name: myBoolean # Define a parameter named 'myBoolean' + type: boolean # The parameter type is boolean + default: true # Default value is true + +- name: myObject # Define a parameter named 'myObject' + type: object # The parameter type is object + default: # Default value is an object with nested properties + foo: FOO # Property 'foo' with value 'FOO' + bar: BAR # Property 'bar' with value 'BAR' + things: # Property 'things' is a list + - one + - two + - three + nested: # Property 'nested' is an object + one: apple # Property 'one' with value 'apple' + two: pear # Property 'two' with value 'pear' + count: 3 # Property 'count' with value 3 + +- name: myStep # Define a parameter named 'myStep' + type: step # The parameter type is step + default: # Default value is a step + script: echo my step + +- name: mySteplist # Define a parameter named 'mySteplist' + type: stepList # The parameter type is stepList + default: # Default value is a list of steps + - script: echo step one + - script: echo step two + +trigger: none jobs: -- job: stepList - steps: ${{ parameters.mySteplist }} -- job: myStep +- job: stepList # Define a job named 'stepList' + steps: ${{ parameters.mySteplist }} # Use the steps from the 'mySteplist' parameter + +- job: myStep # Define a job named 'myStep' steps: - - ${{ parameters.myStep }} + - ${{ parameters.myStep }} # Use the step from the 'myStep' parameter ``` \ No newline at end of file diff --git a/docs/pipelines/process/includes/secret-variables-logging.md b/docs/pipelines/process/includes/secret-variables-logging.md index 96f41948678..2343b154b01 100644 --- a/docs/pipelines/process/includes/secret-variables-logging.md +++ b/docs/pipelines/process/includes/secret-variables-logging.md @@ -7,7 +7,9 @@ author: juliakm ms.date: 05/31/2022 --- -When `issecret` is set to true, the value of the variable will be saved as secret and masked out from log. +When `issecret` is set to true, the value of the variable will be saved as secret and masked out from logs. + +[!INCLUDE [secrets masked](./masked-secrets.md)] # [Bash](#tab/bash) diff --git a/docs/pipelines/process/includes/set-secrets.md b/docs/pipelines/process/includes/set-secrets.md index 487a318c87e..ab4bfae06fe 100644 --- a/docs/pipelines/process/includes/set-secrets.md +++ b/docs/pipelines/process/includes/set-secrets.md @@ -4,7 +4,7 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 04/29/2022 +ms.date: 02/28/2024 --- To set secrets in the web interface, follow these steps: @@ -12,7 +12,7 @@ To set secrets in the web interface, follow these steps: 1. Go to the **Pipelines** page, select the appropriate pipeline, and then select **Edit**. 1. Locate the **Variables** for this pipeline. 1. Add or update the variable. -1. Select the ![Secret](../media/variables/secret-variable-icon.png) lock icon to store the variable in an encrypted manner. +1. Select the option to **Keep this value secret** to store the variable in an encrypted manner. 1. Save the pipeline. Secret variables are encrypted at rest with a 2048-bit RSA key. diff --git a/docs/pipelines/process/includes/task-run-built-in-conditions.md b/docs/pipelines/process/includes/task-run-built-in-conditions.md index 3f4dfe060e1..cec69241527 100644 --- a/docs/pipelines/process/includes/task-run-built-in-conditions.md +++ b/docs/pipelines/process/includes/task-run-built-in-conditions.md @@ -4,13 +4,13 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 08/23/2021 +ms.date: 06/19/2024 --- -* Only when all previous direct and indirect dependencies with the same agent pool have succeeded. If you have different agent pools, those stages or jobs will run concurrently. This is the default if there is not a condition set in the YAML. +- Only when all previous direct and indirect dependencies with the same agent pool succeed. If you have different agent pools, those stages or jobs run concurrently. This condition is the default if no condition is set in the YAML. -* Even if a previous dependency has failed, unless the run was canceled. Use `succeededOrFailed()` in the YAML for this condition. +- Even if a previous dependency fails, unless the run is canceled. Use `succeededOrFailed()` in the YAML for this condition. -* Even if a previous dependency has failed, even if the run was canceled. Use `always()` in the YAML for this condition. +- Even if a previous dependency fails, and even if the run is canceled. Use `always()` in the YAML for this condition. -* Only when a previous dependency has failed. Use `failed()` in the YAML for this condition. +- Only when a previous dependency fails. Use `failed()` in the YAML for this condition. diff --git a/docs/pipelines/process/includes/variable-groups-link-secrets.md b/docs/pipelines/process/includes/variable-groups-link-secrets.md index 85ed4af8a4f..af225505806 100644 --- a/docs/pipelines/process/includes/variable-groups-link-secrets.md +++ b/docs/pipelines/process/includes/variable-groups-link-secrets.md @@ -4,38 +4,60 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: jukullam author: juliakm -ms.date: 04/29/2022 +ms.date: 01/27/2025 +ms.custom: arm2024 --- -Link an existing Azure key vault to a variable group and map selective vault secrets to the variable group. +You can create a variable group that links to existing Azure key vaults and maps selected key vault secrets to the variable group. Only the secret names are mapped to the variable group, not the secret values. When pipelines run, they link to the variable group to fetch the latest secret values from the vault at runtime. -1. In the **Variable groups** page, enable **Link secrets from an Azure key vault as variables**. - You'll need an existing key vault containing your secrets. Create a key vault using the [Azure portal](https://portal.azure.com). +Any changes made to existing secrets in the key vault are automatically available to all the pipelines that use the variable group. However, if secrets are added to or deleted from the vault, the associated variable groups don't automatically update. You must explicitly update the secrets to include in the variable group. - ![Screenshot of variable group with Azure key vault integration.](../../library/media/link-azure-key-vault-variable-group.png) +Although Key Vault supports storing and managing cryptographic keys and certificates in Azure, Azure Pipelines variable group integration only supports mapping key vault secrets. Cryptographic keys and certificates aren't supported. -1. Specify your Azure subscription end point and the name of the vault containing your secrets. +> [!NOTE] +> Key vaults that use Azure role-based access control (Azure RBAC) aren't supported. - Ensure the Azure service connection has at least **Get** and **List** management permissions on the vault for secrets. - Enable Azure Pipelines to set these permissions by choosing **Authorize** next to the vault name. - Or, set the permissions manually in the [Azure portal](https://portal.azure.com): +### Prerequisites - 1. Open **Settings** for the vault, and then choose **Access policies** > **Add new**. - 1. Select **Select principal** and then choose the service principal for your client account. - 1. Select **Secret permissions** and ensure that **Get** and **List** have check marks. - 1. Select **OK** to save the changes. +| Product | Requirements| +|---------|-------------| +| Azure DevOps | - An [Azure DevOps project](../../../organizations/projects/create-project.md).
      - An [Azure Resource Manager service connection](../../library/connect-to-azure.md) for your project.
      - **Permissions:**
          - To use service connections: Have at least the *User* role for the [service connection](../../policies/permissions.md#set-service-connection-security-in-azure-pipelines).
          - To create a variable group: Have at least *Creator* [library permission](../../policies/permissions.md#set-library-security-in-azure-pipelines). | +| Azure | - An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/).
      - **Permissions:**
          To create a key vault: Have at least the *Owner* role for the subscription.| -1. On the **Variable groups** page, select **+ Add** to select specific secrets from your vault for mapping to this variable group. -### Manage key vault secrets +### Create a key vault -See the following list of helpful tips for managing secrets. +Create an Azure key vault. -- Only the secret *names* get mapped to the variable group, not the secret values. The latest secret value, fetched from the vault, is used in the pipeline run that's linked to the variable group. +1. In the Azure portal, select **Create a resource**. +1. Search for and select **Key Vault**, then select **Create**. +1. Select your subscription. +1. Select an existing resource group or create a new one. +1. Enter a name for the key vault. +1. Select a region. +1. Select the **Access and configuration** tab. +1. Select **Vault access policy**. +1. Select your account as the principal. +1. Select **Review + create** and then **Create**. -- Any change made to *existing* secrets in the key vault is automatically available to all the pipelines the variable group's used in. -- When new secrets get added to or deleted from the vault, the associated variable groups aren't automatically updated. The secrets included in the variable group must be explicitly updated so the pipelines that are using the variable group get executed correctly. +### Create the variable group linked to the key vault -- Azure Key Vault supports storing and managing cryptographic keys and secrets in Azure. - Currently, Azure Pipelines variable group integration supports mapping only secrets from the Azure key vault. Cryptographic keys and certificates aren't supported. \ No newline at end of file +1. In your Azure DevOps project, select **Pipelines** > **Library** > **+ Variable group**. +1. On the **Variable groups** page, enter a name and optional description for the variable group. +1. Enable the **Link secrets from an Azure key vault as variables** toggle. +1. Select your service connection and select **Authorize**. +1. Select your key vault name and enable Azure DevOps to access the key vault by selecting **Authorize** next to the vault name. +1. Select **+ Add** and on the **Choose secrets** screen, select the secrets from your vault for mapping to this variable group, then select **OK**. +1. Select **Save** to save the secret variable group. + +:::image type="content" source="../../library/media/link-azure-key-vault-variable-group.png" alt-text="Screenshot of variable group with Azure key vault integration."::: + +>[!NOTE] +>Your service connection must have at least **Get** and **List** permissions on the key vault, which you can authorize in the preceding steps. You can also provide these permissions from the Azure portal by following these steps: +> +>1. Open **Settings** for the key vault, and then choose **Access configuration** > **Go to access policies**. +>1. On the **Access policies** page, if your Azure Pipelines project isn't listed under **Applications** with at least **Get** and **List** permissions, select **Create**. +>1. Under **Secret permissions**, select **Get** and **List**, and then select **Next**. +>1. Select your principal, and then select **Next**. +>1. Select **Next** again, review the settings, and then select **Create**. diff --git a/docs/pipelines/process/invoke-checks.md b/docs/pipelines/process/invoke-checks.md index 9ea98a4f551..7543d3efae2 100644 --- a/docs/pipelines/process/invoke-checks.md +++ b/docs/pipelines/process/invoke-checks.md @@ -4,7 +4,7 @@ description: Use Invoke Azure Function / REST API checks to determine when a dep ms.topic: conceptual ms.author: sandrica author: silviuandrica -ms.date: 07/13/2022 +ms.date: 07/18/2023 monikerRange: ">= azure-devops-2020" --- @@ -45,13 +45,21 @@ The steps in the diagram are: - 2.4 If it can't reach a final decision, reschedule a reevaluation of the conditions for a later point, then go to step 2.3 1. Decision Communication. The Azure function calls back into Azure Pipelines with the access decision. Stage deployment can proceed +::: moniker range="azure-devops" + +When you use the recommended implementation, the pipeline run details page shows the latest check log. + +:::image type="content" source="media/checks-pipeline-run-details.png" alt-text="Screenshot of pipeline run details with check information."::: + +::: moniker-end + ### Recommended configuration for asynchronous checks In the Azure Function / REST API check configuration panel, make sure you: - Selected _Callback_ for the _Completion event_ - Set _Time between evaluations (minutes)_ to _0_ -Setting the _Time between evaluations_ to a non-zero value means the check decision (pass / fail) isn't final. The check is reevaluated until all other Approvals & Checks reach a final state. +Setting the _Time between evaluations_ to a nonzero value means the check decision (pass / fail) isn't final. The check is reevaluated until all other Approvals & Checks reach a final state. @@ -77,7 +85,7 @@ To reach a decision, your check may need information about the current pipeline To call into Azure DevOps, we recommend you use the [job access token](/azure/devops/pipelines/process/access-tokens) issued for the check execution, instead of a [personal access token (PAT)](/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate). The token is already provided to your checks by default, in the `AuthToken` header. -Compared to PATs, the job access token is less prone to getting throttled, doesn't need manual refresh, and is not tied to a personal account. The token is valid for 48 hours. +Compared to PATs, the job access token is less prone to getting throttled, doesn't need manual refresh, and isn't tied to a personal account. The token is valid for 48 hours. Using the job access token all but removes Azure DevOps REST API throttling issues. When you use a PAT, you're using the same PAT for all runs of your pipeline. If you run a large number of pipelines, then the PAT gets throttled. This is less of an issue with the job access token since a new token is generated for each check execution. @@ -88,7 +96,7 @@ If your check needs to access non-Pipelines related resources, for example, Boar ### Send a decision back to Azure DevOps Your check implementation must use the [Post Event](/rest/api/azure/devops/distributedtask/events/post-event) REST API call to communicate a decision back to Azure Pipelines. Make sure you specify the following properties: -- `Headers`: `Basic: {AuthToken}` +- `Headers`: `Bearer {AuthToken}` - `Body`: ```json { @@ -223,7 +231,7 @@ When configuring the check, you can specify the pipeline run information you wis - `"TaskInstanceId": "$(system.TaskInstanceId)"` - `"AuthToken": "$(system.AccessToken)"` -We don't recommend making calls into Azure DevOps in synchronous mode, because it will most likely cause your check to take more than 3 seconds to reply, so the check will fail. +We don't recommend making calls into Azure DevOps in synchronous mode, because it will most likely cause your check to take more than 3 seconds to reply, so the check fails. ### Error handling @@ -288,6 +296,20 @@ Say you have a Service Connection to a production environment resource, and you - Azure Pipelines calls your check function - If the reason is other than `Manual`, the check fails, and the pipeline run fails +::: moniker range="azure-devops" + +## Check compliance + +Invoke Azure Function and REST API checks now include rules to match recommended usage. Checks need to follow these rules depending on mode and the number of retries: + +- **Asynchronous checks (Callback mode)**: Azure Pipelines doesn't retry asynchronous checks. You should provide a result asynchronously when an evaluation is final. For asynchronous checks to be considered compliant, the time interval between evaluations needs to be 0. + +- **Synchronous checks (ApiResponse mode)**: The maximum number of retries for your check is 10. You can do set in a number of ways. For example, you can configure timeout to 20 and time interval between evaluations to 2. Or, you can configure timeout to 100 and time interval between evaluations to 10. But, if you configure timeout to 100 and set the time interval between evaluations to 2, your check won't be compliant because your asking for 50 retries. The ratio of timeout to time interval between evaluations should be less than or equal to 10. + +Learn more about the [rollout of check compliance](https://devblogs.microsoft.com/devops/updates-to-approvals-and-checks/#scalability-improvements). + +::: moniker-end + ## Multiple checks Before Azure Pipelines deploys a stage in a pipeline run, multiple checks may need to pass. A protected resource may have one or more Checks associated to it. A stage may use multiple protected resources. Azure Pipelines collects all the checks associated to each protected resource used in a stage and evaluates them concurrently. diff --git a/docs/pipelines/process/media/access-tokens/create-new-security-group.png b/docs/pipelines/process/media/access-tokens/create-new-security-group.png index 76d5945cc32..8f85d2db5d2 100644 Binary files a/docs/pipelines/process/media/access-tokens/create-new-security-group.png and b/docs/pipelines/process/media/access-tokens/create-new-security-group.png differ diff --git a/docs/pipelines/process/media/add-approvals-and-checks.png b/docs/pipelines/process/media/add-approvals-and-checks.png new file mode 100644 index 00000000000..29775e70ebe Binary files /dev/null and b/docs/pipelines/process/media/add-approvals-and-checks.png differ diff --git a/docs/pipelines/process/media/approval-prompt.png b/docs/pipelines/process/media/approval-prompt.png new file mode 100644 index 00000000000..aeb7a6c8b0d Binary files /dev/null and b/docs/pipelines/process/media/approval-prompt.png differ diff --git a/docs/pipelines/process/media/bypass-business-hours-check.png b/docs/pipelines/process/media/bypass-business-hours-check.png new file mode 100644 index 00000000000..01530177f1d Binary files /dev/null and b/docs/pipelines/process/media/bypass-business-hours-check.png differ diff --git a/docs/pipelines/process/media/check-bypass-example.png b/docs/pipelines/process/media/check-bypass-example.png new file mode 100644 index 00000000000..528f01b19e7 Binary files /dev/null and b/docs/pipelines/process/media/check-bypass-example.png differ diff --git a/docs/pipelines/process/media/checks-pipeline-run-details.png b/docs/pipelines/process/media/checks-pipeline-run-details.png new file mode 100644 index 00000000000..1bcfe441687 Binary files /dev/null and b/docs/pipelines/process/media/checks-pipeline-run-details.png differ diff --git a/docs/pipelines/process/media/checks/disable-check-approvals.png b/docs/pipelines/process/media/checks/disable-check-approvals.png new file mode 100644 index 00000000000..1dec7f61a0a Binary files /dev/null and b/docs/pipelines/process/media/checks/disable-check-approvals.png differ diff --git a/docs/pipelines/process/media/checks/policy-check-failed-logs.png b/docs/pipelines/process/media/checks/policy-check-failed-logs.png index 60d794891b3..ab96c3a954e 100644 Binary files a/docs/pipelines/process/media/checks/policy-check-failed-logs.png and b/docs/pipelines/process/media/checks/policy-check-failed-logs.png differ diff --git a/docs/pipelines/process/media/checks/policy-check-pass-logs.png b/docs/pipelines/process/media/checks/policy-check-pass-logs.png index ba3b288183b..490d1b79b07 100644 Binary files a/docs/pipelines/process/media/checks/policy-check-pass-logs.png and b/docs/pipelines/process/media/checks/policy-check-pass-logs.png differ diff --git a/docs/pipelines/process/media/checks/required-template.png b/docs/pipelines/process/media/checks/required-template.png index ad8a8015042..48121598b22 100644 Binary files a/docs/pipelines/process/media/checks/required-template.png and b/docs/pipelines/process/media/checks/required-template.png differ diff --git a/docs/pipelines/process/media/create-environment.png b/docs/pipelines/process/media/create-environment.png index ef646fe9dac..ddb02f4c1fe 100644 Binary files a/docs/pipelines/process/media/create-environment.png and b/docs/pipelines/process/media/create-environment.png differ diff --git a/docs/pipelines/process/media/create-new-approval.png b/docs/pipelines/process/media/create-new-approval.png new file mode 100644 index 00000000000..72ea959a571 Binary files /dev/null and b/docs/pipelines/process/media/create-new-approval.png differ diff --git a/docs/pipelines/process/media/create-new-environment.png b/docs/pipelines/process/media/create-new-environment.png index 6052933bfe1..664e81a491a 100644 Binary files a/docs/pipelines/process/media/create-new-environment.png and b/docs/pipelines/process/media/create-new-environment.png differ diff --git a/docs/pipelines/process/media/defer-approval-set-time.png b/docs/pipelines/process/media/defer-approval-set-time.png new file mode 100644 index 00000000000..167f1d2f14e Binary files /dev/null and b/docs/pipelines/process/media/defer-approval-set-time.png differ diff --git a/docs/pipelines/process/media/defer-approval.png b/docs/pipelines/process/media/defer-approval.png new file mode 100644 index 00000000000..d7316e45161 Binary files /dev/null and b/docs/pipelines/process/media/defer-approval.png differ diff --git a/docs/pipelines/process/media/environment-new.png b/docs/pipelines/process/media/environment-new.png new file mode 100644 index 00000000000..9057b018156 Binary files /dev/null and b/docs/pipelines/process/media/environment-new.png differ diff --git a/docs/pipelines/process/media/environments-add-resource.png b/docs/pipelines/process/media/environments-add-resource.png new file mode 100644 index 00000000000..78df0bfceb6 Binary files /dev/null and b/docs/pipelines/process/media/environments-add-resource.png differ diff --git a/docs/pipelines/process/media/environments-deployment-history.png b/docs/pipelines/process/media/environments-deployment-history.png index d8bcb878c19..7fccaa22395 100644 Binary files a/docs/pipelines/process/media/environments-deployment-history.png and b/docs/pipelines/process/media/environments-deployment-history.png differ diff --git a/docs/pipelines/process/media/environments-nav.png b/docs/pipelines/process/media/environments-nav.png index 0fad9aff99d..a9e31fc921f 100644 Binary files a/docs/pipelines/process/media/environments-nav.png and b/docs/pipelines/process/media/environments-nav.png differ diff --git a/docs/pipelines/process/media/exclusive-lock-option.png b/docs/pipelines/process/media/exclusive-lock-option.png new file mode 100644 index 00000000000..04abd7ee1f5 Binary files /dev/null and b/docs/pipelines/process/media/exclusive-lock-option.png differ diff --git a/docs/pipelines/process/media/incoming-webhook.png b/docs/pipelines/process/media/incoming-webhook.png index 61f18e62a84..d34bcd33028 100644 Binary files a/docs/pipelines/process/media/incoming-webhook.png and b/docs/pipelines/process/media/incoming-webhook.png differ diff --git a/docs/pipelines/process/media/pipeline-triggers/default-branch-setting.png b/docs/pipelines/process/media/pipeline-triggers/default-branch-setting.png index 30c6cb858d0..c53e4a65a73 100644 Binary files a/docs/pipelines/process/media/pipeline-triggers/default-branch-setting.png and b/docs/pipelines/process/media/pipeline-triggers/default-branch-setting.png differ diff --git a/docs/pipelines/process/media/pipeline-triggers/edit-triggers.png b/docs/pipelines/process/media/pipeline-triggers/edit-triggers.png index 6f9cf0ecc7f..a7688e6a3d4 100644 Binary files a/docs/pipelines/process/media/pipeline-triggers/edit-triggers.png and b/docs/pipelines/process/media/pipeline-triggers/edit-triggers.png differ diff --git a/docs/pipelines/process/media/pipeline-triggers/pipeline-edit.png b/docs/pipelines/process/media/pipeline-triggers/pipeline-edit.png index fea02e8542b..f6bee2cc6c9 100644 Binary files a/docs/pipelines/process/media/pipeline-triggers/pipeline-edit.png and b/docs/pipelines/process/media/pipeline-triggers/pipeline-edit.png differ diff --git a/docs/pipelines/process/media/repository-version-picker.png b/docs/pipelines/process/media/repository-version-picker.png new file mode 100644 index 00000000000..da6cc2fae42 Binary files /dev/null and b/docs/pipelines/process/media/repository-version-picker.png differ diff --git a/docs/pipelines/process/media/run-expansion.png b/docs/pipelines/process/media/run-expansion.png new file mode 100644 index 00000000000..5f73ecd97d3 Binary files /dev/null and b/docs/pipelines/process/media/run-expansion.png differ diff --git a/docs/pipelines/process/media/run-logging.png b/docs/pipelines/process/media/run-logging.png new file mode 100644 index 00000000000..66d70422549 Binary files /dev/null and b/docs/pipelines/process/media/run-logging.png differ diff --git a/docs/pipelines/process/media/run-overview.png b/docs/pipelines/process/media/run-overview.png new file mode 100644 index 00000000000..e4311478885 Binary files /dev/null and b/docs/pipelines/process/media/run-overview.png differ diff --git a/docs/pipelines/process/media/run-select-pool.png b/docs/pipelines/process/media/run-select-pool.png new file mode 100644 index 00000000000..7ba56215c62 Binary files /dev/null and b/docs/pipelines/process/media/run-select-pool.png differ diff --git a/docs/pipelines/process/media/run-tasks.png b/docs/pipelines/process/media/run-tasks.png new file mode 100644 index 00000000000..0353aa4ce2f Binary files /dev/null and b/docs/pipelines/process/media/run-tasks.png differ diff --git a/docs/pipelines/process/media/stages/is-skippable-stage-false.png b/docs/pipelines/process/media/stages/is-skippable-stage-false.png new file mode 100644 index 00000000000..6d0ae52998e Binary files /dev/null and b/docs/pipelines/process/media/stages/is-skippable-stage-false.png differ diff --git a/docs/pipelines/process/media/stages/stages-run-skip-stage.png b/docs/pipelines/process/media/stages/stages-run-skip-stage.png new file mode 100644 index 00000000000..887e1a89ffc Binary files /dev/null and b/docs/pipelines/process/media/stages/stages-run-skip-stage.png differ diff --git a/docs/pipelines/process/media/trigger-menu.png b/docs/pipelines/process/media/trigger-menu.png index 0cfcd836115..e6f0c78e57a 100644 Binary files a/docs/pipelines/process/media/trigger-menu.png and b/docs/pipelines/process/media/trigger-menu.png differ diff --git a/docs/pipelines/process/media/vm-creation-linux.png b/docs/pipelines/process/media/vm-creation-linux.png new file mode 100644 index 00000000000..7eee23306b2 Binary files /dev/null and b/docs/pipelines/process/media/vm-creation-linux.png differ diff --git a/docs/pipelines/process/media/vm-creation.png b/docs/pipelines/process/media/vm-creation.png index 1c397d52b28..5168a706aad 100644 Binary files a/docs/pipelines/process/media/vm-creation.png and b/docs/pipelines/process/media/vm-creation.png differ diff --git a/docs/pipelines/process/media/vm-resourceview.png b/docs/pipelines/process/media/vm-resourceview.png index 7ed5945e211..d9fc8280eab 100644 Binary files a/docs/pipelines/process/media/vm-resourceview.png and b/docs/pipelines/process/media/vm-resourceview.png differ diff --git a/docs/pipelines/process/media/vm-tags.png b/docs/pipelines/process/media/vm-tags.png index fb0d99f9c3b..7abb5aeebf8 100644 Binary files a/docs/pipelines/process/media/vm-tags.png and b/docs/pipelines/process/media/vm-tags.png differ diff --git a/docs/pipelines/process/parameters.md b/docs/pipelines/process/parameters.md deleted file mode 100644 index 5f65f688349..00000000000 --- a/docs/pipelines/process/parameters.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Process parameters -ms.custom: seodec18 -description: You can link all important fields for tasks used across the build definition as process parameters -ms.topic: conceptual -ms.assetid: 27AD0094-FDF1-4B36-A82E-B845980984AF -ms.date: 06/30/2023 -monikerRange: '<= azure-devops' ---- - -# Process parameters - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -> [!NOTE] -> This guidances does not apply to YAML pipelines. For parameters in YAML pipelines, see [runtime parameters](runtime-parameters.md). -> - -Process parameters are used in classic pipelines and differ from variables in the kind of input supported by them. Variables only take in string inputs while process parameters in addition to string inputs support more data types like check boxes and drop-down list boxes. - -You can link all important arguments for tasks used across the build definition as process parameters, which are then shown at one place - the Pipeline view. -This means you can quickly edit these arguments without needing to click through all the tasks. - -[Templates](../release/env-templates.md) come with a set of predefined process parameters. - -> [!NOTE] -> -> The **Link** and **Unlink** functionality applies to build pipelines only. It does not apply to release pipelines. - -::: moniker range="> tfs-2018" -To link more arguments across all tasks to new or existing process parameters, select **Link** from the task argument. -::: moniker-end - -To set a process parameter, edit your pipeline and go to **Tasks** > **Pipeline**. - -:::image type="content" source="media/process-parameter-task.png" alt-text="Screenshot of adding a parameter to a classic task. "::: - -::: moniker range="<=tfs-2018" - -## Set a process parameter from a template in a build pipeline - -You can create a process parameter from a task input in a build pipeline. Process parameters are useful if you will have the same input values in multiple tasks. -You can link more arguments across all tasks to new or existing process parameters. - -![Schematic showing tasks](media/2017-user-experience/tasks-linking.png) - -To link a process parameter: - -1. Select the **i** icon that is part of a task input field. - -1. In the window that opens, select **Link**. - - :::image type="content" source="media/select-link.png" alt-text="Select the link option in the pop-up."::: - -1. Configure the **Link settings**. You can set a new **Display name** so that you can identify the process parameter later on. - - :::image type="content" source="media/configure-display-name.png" alt-text="Update the display name so that you can reference the parameter later. "::: - -1. You'll now have the option to link your process parameter when you reuse the same task. To link a process parameter, select the **i** icon and click **Link**. - -1. Set the **Process parameter to link to this setting** to reference your existing process parameter and select **Link**. - - :::image type="content" source="media/reference-process-param.png" alt-text="Reference an existing process parameter. "::: - -::: moniker-end - -::: moniker range="> tfs-2018" -Select **Unlink** if you need to disconnect an argument from a process parameter. -::: moniker-end - -::: moniker range="tfs-2018" -You can also unlink arguments from process parameters. - -1. Select the link icon. - -1. Choose the **Unlink** option. In this example, the `Parameter.solution` process parameter is unlinked. - -![Unlink arguments.](media/2017-user-experience/tasks-unlinking.png) - -## Define a new process parameter - -You can define a new process parameter using the `json` definition for your pipeline. - -1. Export the existing template from the **Build Definitions** page. - - :::image type="content" source="media/export-build-template.png" alt-text="Export the build template."::: - -1. Open the JSON in a text editor. Add a new input in the process parameter section of your file. If you have existing process parameters, you can duplicate one of them. For example, this is a new parameter definition based on the msBuildArgs parameter. - - ```json - { - "aliases":[ - - ], - "options":{ - - }, - "properties":{ - - }, - "name":"myNewParam", - "label":"MyProcessParam", - "defaultValue":"/p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:PackageLocation=\"$(build.artifactstagingdirectory)\\\\\"", - "type":"string", - "helpMarkDown":"Additional arguments for process parameters.", - "visibleRule":"", - "groupName":"" - } - ``` - -1. Add the new parameter as an input value for any tasks where you want to use it. For example, here the new value of `msbuildArgs` is `myNewParam`. - - ```json - "inputs":{ - "solution":"$(Parameters.solution)", - "vsVersion":"latest", - "msbuildArgs":"$(Parameters.myNewParam)", - "platform":"$(BuildPlatform)", - "configuration":"$(BuildConfiguration)", - "clean":"false", - "maximumCpuCount":"false", - "restoreNugetPackages":"false", - "msbuildArchitecture":"x86", - "logProjectEvents":"true", - "createLogFile":"false" - } - ``` - - -1. Return to the **Build Definitions** page and select **Import**. - - :::image type="content" source="media/select-import-option.png" alt-text="Select the import option to add your json file."::: - -1. Add your `json` file and import the pipeline. - -1. Within your imported pipeline, you now have the option to link to your new process parameter. You may need to unlink and then link again for the process parameter to appear. - -::: moniker-end - - - diff --git a/docs/pipelines/process/phases.md b/docs/pipelines/process/phases.md index bf70cd8a566..c7aa2709b5c 100644 --- a/docs/pipelines/process/phases.md +++ b/docs/pipelines/process/phases.md @@ -1,10 +1,9 @@ --- -title: Jobs in Azure Pipelines and TFS -ms.custom: seodec18, contperf-fy20q4 -description: Understand jobs in Azure Pipelines, Azure DevOps Server, and Team Foundation Server (TFS) +title: Jobs in Azure Pipelines +description: Understand jobs in Azure Pipelines and Azure DevOps Server ms.assetid: B05BCE88-73BA-463E-B35E-B54787631B3F ms.topic: conceptual -ms.date: 10/13/2022 +ms.date: 01/08/2025 monikerRange: '<= azure-devops' --- @@ -12,35 +11,17 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - - - -::: moniker range=">= azure-devops-2019" - -You can organize your pipeline into jobs. Every pipeline has at least one job. A job is a series of steps that run sequentially as a unit. -In other words, a job is the smallest unit of work that can be scheduled to run. - -::: moniker-end +You can organize your pipeline into jobs. Every pipeline has at least one job. A job is a series of steps that run sequentially as a unit. In other words, a job is the smallest unit of work that can be scheduled to run. -::: moniker range="tfs-2018" +To learn about the key concepts and components that make up a pipeline, see [Key concepts for new Azure Pipelines users](../get-started/key-pipelines-concepts.md). -You can organize your build or release pipeline into jobs. Every pipeline has at least one job. A job is a series of steps that run sequentially as a unit. -In other words, a job is the smallest unit of work that can be scheduled to run. - -> [!NOTE] -> You must install TFS 2018.2 to use jobs in build processes. In TFS 2018 RTM you can use jobs in release deployment processes. - -::: moniker-end +Azure Pipelines doesn't support job priority for YAML pipelines. To control when jobs run, you can specify [conditions](#conditions) and [dependencies](#dependencies). ## Define a single job #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" -In the simplest case, a pipeline has a single job. In that case, you do not have to explicitly use the `job` keyword unless you are using a [template](templates.md). You can directly specify the steps in your YAML file. +In the simplest case, a pipeline has a single job. In that case, you don't have to explicitly use the `job` keyword unless you're using a [template](templates.md). You can directly specify the steps in your YAML file. This YAML file has a job that runs on a [Microsoft-hosted agent](../agents/hosted.md) and outputs `Hello world`. @@ -51,7 +32,7 @@ steps: - bash: echo "Hello world" ``` -You may want to specify additional properties on that job. In that case, you can use the `job` keyword. +You might want to specify more properties on that job. In that case, you can use the `job` keyword. ```yaml jobs: @@ -63,7 +44,7 @@ jobs: - bash: echo "Hello world" ``` -Your pipeline may have multiple jobs. In that case, use the `jobs` keyword. +Your pipeline could have multiple jobs. In that case, use the `jobs` keyword. ```yaml jobs: @@ -76,11 +57,9 @@ jobs: - bash: echo "B" ``` -::: moniker-end - ::: moniker range=">=azure-devops-2020" -Your pipeline may have multiple stages, each with multiple jobs. In that case, use the `stages` keyword. +Your pipeline can have multiple stages, each with multiple jobs. In that case, use the `stages` keyword. ```yaml stages: @@ -97,7 +76,7 @@ stages: ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="< azure-devops" The full syntax to specify a job is: @@ -181,16 +160,12 @@ The syntax for a deployment job is: ::: moniker-end -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" -Although you can add steps for deployment tasks in a `job`, we recommend that you instead use a [deployment job](deployment-jobs.md). A deployment job has a few benefits. For example, you can deploy to an environment, which includes benefits such as being able to see the history of what you've deployed. +Although you can add steps for deployment tasks in a `job`, we recommend that you instead use a [deployment job](deployment-jobs.md). A deployment job has a few benefits. For example, you can deploy to an environment, which includes benefits such as being able to see the history of what you deployed. ::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) To add jobs to your build pipeline, edit the pipeline on the Pipelines page. Select **...** to add a job. @@ -221,46 +196,17 @@ Jobs can be of different types, depending on where they run. ::: moniker-end -::: moniker range="azure-devops-2019" - -# [YAML](#tab/yaml) - -* **Agent pool jobs** run on an agent in an agent pool. -* **Server jobs** run on the Azure DevOps Server. - -# [Classic](#tab/classic) - -* **Agent pool jobs** run on an agent in an agent pool. -* **Server jobs** run on the Azure DevOps Server. -* **Deployment group jobs** run on machines in a deployment group. These jobs are only available in a release pipeline. - ---- - -::: moniker-end - -::: moniker range="tfs-2018" - -* **Agent pool jobs** run on an agent in the agent pool. These jobs are available in build and release pipelines. -* **Server jobs** run on TFS. These jobs are available in build and release pipelines. -* **Deployment group jobs** run on machines in a deployment group. These jobs are available only in release pipelines. - -::: moniker-end - ### Agent pool jobs -These are the most common type of jobs and they run on an agent in an agent pool. +Agent pool jobs are the most common jobs. These jobs run on an agent in an agent pool. You can specify the pool to run the job on, and you can also specify demands to specify what capabilities an agent must have to run your job. Agents can be Microsoft-hosted or self-hosted. For more information, see [Azure Pipelines agents](../agents/agents.md). -* When using Microsoft-hosted agents, each job in a pipeline gets a fresh agent. -* Use [demands](demands.md) with self-hosted agents to specify what capabilities an agent must have to run your job. You may get the same agent for consecutive jobs, depending on whether there is more than one agent in your agent pool that matches your pipeline's demands. If there is only one agent in your pool that matches the pipeline's demands, the pipeline will wait until this agent is available. +* When you're using Microsoft-hosted agents, each job in a pipeline gets a fresh agent. +* When you're using self-hosted agents, you can use [demands](/azure/devops/pipelines/yaml-schema/pool-demands) to specify what capabilities an agent must have to run your job. You can get the same agent for consecutive jobs, depending on whether there's more than one agent in your agent pool that matches your pipeline's demands. If there's only one agent in your pool that matches the pipeline's demands, the pipeline waits until this agent is available. > [!NOTE] -> Demands and capabilities are designed for use with self-hosted agents so that jobs can be matched with an agent that -> meets the requirements of the job. When using Microsoft-hosted agents, you select an image for the agent that -> matches the requirements of the job, so although it is possible to add capabilities to a Microsoft-hosted agent, you don't need -> to use capabilities with Microsoft-hosted agents. +> Demands and capabilities are designed for use with self-hosted agents so that jobs can be matched with an agent that meets the requirements of the job. When using Microsoft-hosted agents, you select an image for the agent that matches the requirements of the job. Although it's possible to add capabilities to a Microsoft-hosted agent, you don't need to use capabilities with Microsoft-hosted agents. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" ```yaml pool: @@ -282,38 +228,33 @@ steps: - script: echo hello world ``` -::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) -You have the option to specify demands in the pipeline, in the jobs, or both. -If you specify demands in both the pipeline and in a job, the union of the two sets of demands is required for the system to select an agent. + +You can specify demands in the pipeline, in the jobs, or both. If you specify demands in both the pipeline and in a job, the union of the two sets of demands is required for the system to select an agent. * * * + Learn more about [agent capabilities](../agents/agents.md#capabilities). -

      Server jobs

      +### Server jobs -Tasks in a server job are orchestrated by and executed on the server (Azure Pipelines or TFS). A server job does not require an agent or any target computers. Only a few tasks are supported in a server job at present. The maximum time for a server job is 30 days. +The server orchestrates and executes tasks in a server job. A server job doesn't require an agent or any target computers. Only a few tasks are supported in a server job now. The maximum time for a server job is 30 days. -

      Agentless jobs supported tasks

      +### Agentless jobs supported tasks Currently, only the following tasks are supported out of the box for agentless jobs: * [Delay task](/azure/devops/pipelines/tasks/reference/delay-v1) * [Invoke Azure Function task](/azure/devops/pipelines/tasks/reference/azure-function-v1) * [Invoke REST API task](/azure/devops/pipelines/tasks/reference/invoke-rest-api-v1) -* [Manual Validation task](/azure/devops/pipelines/tasks/reference/manual-validation-v0) -* [Publish To Azure Service Bus task](/azure/devops/pipelines/tasks/reference/publish-to-azure-service-bus-v1) +* [Manual Validation task](/azure/devops/pipelines/tasks/reference/manual-validation-v1) +* [Publish To Azure Service Bus task](/azure/devops/pipelines/tasks/reference/publish-to-azure-service-bus-v2) * [Query Azure Monitor Alerts task](/azure/devops/pipelines/tasks/reference/azure-monitor-v1) * [Query Work Items task](/azure/devops/pipelines/tasks/reference/query-work-items-v0) Because tasks are extensible, you can add more agentless tasks by using extensions. The default timeout for agentless jobs is 60 minutes. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" The full syntax to specify a server job is: @@ -337,25 +278,19 @@ jobs: pool: server # note: the value 'server' is a reserved keyword which indicates this is an agentless job ``` -::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) You add a server job in the editor by selecting '...' on the **Pipeline** channel in the **Tasks** tab of a pipeline. The properties for the server job are displayed when you select the job in the editor. ---- +* * * -

      Dependencies

      +## Dependencies -When you define multiple jobs in a single stage, you can specify dependencies between them. Pipelines must contain at least one job with no dependencies. By default Azure DevOps YAML pipeline jobs will run in parallel unless the `dependsOn` value is set. +When you define multiple jobs in a single stage, you can specify dependencies between them. Pipelines must contain at least one job with no dependencies. By default Azure DevOps YAML pipeline jobs run in parallel unless the `dependsOn` value is set. > [!NOTE] -> Each agent can run only one job at a time. To run multiple jobs in parallel you must configure multiple agents. You also need sufficient [parallel jobs](../licensing/concurrent-jobs.md). +> Each agent can run only one job at a time. To run multiple jobs in parallel, you must configure multiple agents. You also need sufficient [parallel jobs](../licensing/concurrent-jobs.md). #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" The syntax for defining multiple jobs and their dependencies is: @@ -435,71 +370,34 @@ jobs: - script: echo hello from subsequent ``` -::: moniker-end - -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) To add a new job, select '...' on the pipeline channel in the **Tasks** tab of the pipeline. The conditions and order of execution for a job are displayed when you select the job in the editor. -::: moniker range="> tfs-2018" -When you specify multiple jobs in a build pipeline, they run in parallel by default. You can specify the order in which jobs must execute by configuring dependencies between jobs. Job dependencies are not supported in release pipelines. Multiple jobs in a release pipeline run in sequence. -::: moniker-end +When you specify multiple jobs in a build pipeline, they run in parallel by default. You can specify the order in which jobs must execute by configuring dependencies between jobs. Job dependencies aren't supported in release pipelines. Multiple jobs in a release pipeline run in sequence. -::: moniker range="tfs-2018" -Multiple jobs you add to a build or a release pipeline run in sequence. You cannot configure the order of dependencies between jobs in this version of TFS. -::: moniker-end - -::: moniker range="tfs-2018" -Multiple jobs you add to a release pipeline run in sequence. You cannot configure the order of dependencies between jobs in this version of TFS. You cannot also use jobs with build pipelines. -::: moniker-end - -For example, the pipeline shown below divides the overall release -execution into separate execution jobs by using two agent jobs -and a [server job](#server-jobs). +For example, the pipeline divides the overall release execution into separate execution jobs by using two agent jobs and a [server job](#server-jobs). ![Configuring a manual intervention step](media/phases-02.png) -In the example above: - -1. The tasks in the first job of the release run on an agent - and, after this job is complete, the agent is released. +1. The tasks in the first job of the release run on an agent. The agent is released after the job is complete. -1. The server job contains a Manual Intervention task - that runs on the Azure Pipelines or TFS. - The job does not execute on, or require, an agent or any target servers. - The Manual Intervention task displays its message and waits for a - "resume" or "reject" response from the user. In this example, if - the configured timeout is reached, the task will - automatically reject the deployment (set the timeout in the control options section to zero if - you do not want an automated response to be generated). +1. The server job contains a Manual Intervention task that runs on the Azure Pipelines or DevOps Server. The job doesn't execute on, or require, an agent or any target servers. The Manual Intervention task displays its message and waits for a "resume" or "reject" response from the user. In this example, if the task reaches the configured timeout, the task automatically rejects the deployment. Set the timeout in the control options section to zero if you don't want an automated response to be generated. -1. If the release is resumed, tasks in the third job run - - possibly on a different agent. If the release is rejected, - this job does not run and the release is marked as failed. +1. The tasks in the third jobs are run if the release is resumed, possibly on a different agent. If the release is rejected, this job doesn't run and the release is marked as failed. -It's important to understand some of the consequences of -phased execution: +It's important to understand some of the consequences of phased execution: -* Each job may use different - agents. Do not assume that the state from an earlier - job is available during subsequent jobs. +* Each job might use different agents. Don't assume that the state from an earlier job is available during subsequent jobs. -* The **Continue on Error** and **Always run** options for - tasks in each job do not have any effect on tasks in - subsequent jobs. For example, setting - **Always run** on a task at the end of the first job will - not guarantee that tasks in subsequent jobs will run. +* The **Continue on Error** and **Always run** options for tasks in each job don't have any effect on tasks in subsequent jobs. For example, setting **Always run** on a task at the end of the first job doesn't guarantee that tasks in subsequent jobs run. * * * -

      Conditions

      -You can specify the conditions under which each job runs. By default, a job runs if it does not depend on any other job, or if all of the jobs that it depends on have completed and succeeded. You can customize this behavior by forcing a job to run even if a previous job fails or by specifying a custom condition. +## Conditions + +You can specify the conditions under which each job runs. By default, a job runs if it doesn't depend on any other job, or if all of the jobs that it depends on completed successfully. You can customize this behavior by forcing a job to run even if a previous job fails or by specifying a custom condition. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" Example to run a job based upon the status of running a previous job: @@ -555,44 +453,28 @@ jobs: - script: echo hello from B ``` -::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - - #### [Classic](#tab/classic/) -::: moniker range=">= tfs-2018" - -Use the **Run this job** option on an agent or server job to run the tasks - only when specific [conditions](conditions.md) are met. Select a predefined - condition, or select "custom" and enter an [expression](conditions.md) that evaluates - to **true** or **false**. Nested expressions can be used, and the - expressions can access variables available in the release pipeline. -::: moniker-end -::: moniker range="tfs-2018" -Conditions are not supported in this version of TFS. -::: moniker-end +Use the **Run this job** option on an agent or server job to run the tasks only when specific [conditions](conditions.md) are met. Select a predefined condition, or select "custom" and enter an [expression](expressions.md) that evaluates to **true** or **false**. Nested expressions can be used, and the expressions can access variables available in the release pipeline. * * * -

      Timeouts

      -To avoid taking up resources when your job is unresponsive or waiting too long, it's a good idea to set a limit on how long your job is allowed to run. Use the job timeout setting to specify the limit in minutes for running the job. Setting the value to **zero** means that the job can run: +## Timeouts + +To avoid taking up resources when your job is unresponsive or waiting too long, you can set a limit on how long your job can run. Use the job timeout setting to specify the limit in minutes for running the job. Setting the value to **zero** means that the job can run: * Forever on self-hosted agents * For 360 minutes (6 hours) on Microsoft-hosted agents with a public project and public repository -* For 60 minutes on Microsoft-hosted agents with a private project or private repository (unless [additional capacity](../agents/hosted.md#capabilities-and-limitations) is paid for) +* For 60 minutes on Microsoft-hosted agents with a private project or private repository (unless [extra capacity](../agents/hosted.md#capabilities-and-limitations) is paid for) -The timeout period begins when the job starts running. It does not include the +The timeout period begins when the job starts running. It doesn't include the time the job is queued or is waiting for an agent. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" -The `timeoutInMinutes` allows a limit to be set for the job execution time. When not specified, the default is 60 minutes. When `0` is specified, the maximum limit is used (described above). +The `timeoutInMinutes` allows a limit to be set for the job execution time. When not specified, the default is 60 minutes. When `0` is specified, the maximum limit is used. -The `cancelTimeoutInMinutes` allows a limit to be set for the job cancel time when the deployment task is set to keep running if a previous task has failed. When not specified, the default is 5 minutes. The value should be in range from **1** to **35790** minutes. +The `cancelTimeoutInMinutes` allows a limit to be set for the job cancel time when the deployment task is set to keep running if a previous task failed. When not specified, the default is 5 minutes. The value should be in range from **1** to **35790** minutes. ```yaml jobs: @@ -601,44 +483,36 @@ jobs: cancelTimeoutInMinutes: 2 # how much time to give 'run always even if cancelled tasks' before stopping them ``` -::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) Select the job and then specify the timeout value. -On the Options tab, you can specify default values for all jobs in the pipeline. If you specify a non-zero value for the job timeout, then it overrides any value that is specified in the pipeline options. If you specify a zero value, then the timeout value from the pipeline options is used. If the pipeline value is also set to zero, then there is no timeout. +On the Options tab, you can specify default values for all jobs in the pipeline. If you specify a nonzero value for the job timeout, then it overrides any value that is specified in the pipeline options. If you specify a zero value, then the timeout value from the pipeline options is used. If the pipeline value is also set to zero, then there's no timeout. * * * Timeouts have the following level of precedence. -1. On Microsoft-hosted agents, jobs are [limited in how long they can run based on project type and whether they are run using a paid parallel job](../agents/hosted.md#capabilities-and-limitations). When the Microsoft-hosted job timeout interval elapses, the job is terminated. On Microsoft-hosted agents, jobs cannot run longer than this interval, regardless of any job level timeouts specified in the job. -2. The timeout configured at the job level specifies the maximum duration for the job to run. When the job level timeout interval elapses, the job is terminated. If the job is run on a Microsoft-hosted agent, setting the job level timeout to an interval greater than the [built-in Microsoft-hosted job level timeout](../agents/hosted.md#capabilities-and-limitations) has no effect and the Microsoft-hosted job timeout is used. +1. On Microsoft-hosted agents, jobs are [limited in how long they can run based on project type and whether they're run using a paid parallel job](../agents/hosted.md#capabilities-and-limitations). When the Microsoft-hosted job timeout interval elapses, the job is terminated. On Microsoft-hosted agents, jobs can't run longer than this interval, regardless of any job level timeouts specified in the job. +1. The timeout configured at the job level specifies the maximum duration for the job to run. When the job level timeout interval elapses, the job is terminated. When the job is run on a Microsoft-hosted agent, setting the job level timeout greater than the [built-in Microsoft-hosted job level timeout](../agents/hosted.md#capabilities-and-limitations) has no effect. 1. You can also set the timeout for each task individually - see [task control options](tasks.md#controloptions). If the job level timeout interval elapses before the task completes, the running job is terminated, even if the task is configured with a longer timeout interval. - - ## Multi-job configuration From a single job you author, you can run multiple jobs on multiple agents in parallel. Some examples include: * **Multi-configuration builds:** You can build multiple configurations in parallel. For - example, you could build a Visual C++ app for both `debug` and `release` configurations on both `x86` and `x64` platforms. To learn more, see [Visual Studio Build - multiple configurations for multiple platforms](../tasks/build/visual-studio-build.md#multiconfiguration). + example, you could build a Visual C++ app for both `debug` and `release` configurations on both `x86` and `x64` platforms. For more information, see [Visual Studio Build - multiple configurations for multiple platforms](../tasks/build/visual-studio-build.md#multiconfiguration). * **Multi-configuration deployments:** You can run multiple deployments in parallel, for example, to different geographic regions. * **Multi-configuration testing:** You can run test multiple configurations in parallel. -* Multi-configuration will always generate at least one job, even if a multi-configuration variable is empty. +* Multi-configuration always generates at least one job, even if a multi-configuration variable is empty. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" -The `matrix` strategy enables a job to be dispatched multiple times, with different variable sets. The `maxParallel` tag restricts the amount of parallelism. The following job will be dispatched three times with the values of Location and Browser set as specified. However, only two jobs will run at the same time. +The `matrix` strategy enables a job to be dispatched multiple times, with different variable sets. The `maxParallel` tag restricts the amount of parallelism. The following job is dispatched three times with the values of Location and Browser set as specified. However, only two jobs run at the same time. ```yaml jobs: @@ -658,16 +532,16 @@ jobs: ``` > [!NOTE] -> Matrix configuration names (like `US_IE` above) must contain only basic Latin alphabet letters (A-Z, a-z), numbers, and underscores (`_`). +> Matrix configuration names (like `US_IE` in the example) must contain only basic Latin alphabet letters (A - Z, a - z), numbers, and underscores (`_`). > They must start with a letter. > Also, they must be 100 characters or less. It's also possible to use [output variables](variables.md#set-a-multi-job-output-variable) to generate a matrix. -This can be handy if you need to generate the matrix using a script. +This method can be handy if you need to generate the matrix using a script. -`matrix` will accept a runtime expression containing a stringified JSON object. +`matrix` accepts a runtime expression containing a stringified JSON object. That JSON object, when expanded, must match the matrixing syntax. -In the example below, we've hard-coded the JSON string, but it could be generated by a scripting language or command-line program. +In the following example, we hard-coded the JSON string, but you can be generate it with a scripting language or command-line program. ```yaml jobs: @@ -688,11 +562,6 @@ jobs: - script: echo $(myvar) # echos A or B depending on which leg is running ``` -::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) To run multiple jobs using multi-configuration option, you identify a variable named a **multiplier**, and specify a list @@ -706,14 +575,14 @@ To run multiple jobs using multi-configuration option, to pass individually to the agents. * Enter the name of the multiplier variable, without the **$** and parentheses, as the - value of the **Multipliers** parameter. Using a secret variable as a multiplier variable is not supported. + value of the **Multipliers** parameter. Using a secret variable as a multiplier variable isn't supported. * If you want to execute the job for more than one multiplier variable, enter the variable names as a comma-delimited list - omitting the **$** and parentheses for each one. * If you want to limit the number of agents used during the deployment to a - number less than you have configured for your subscription, enter that value as the + number less than you configured for your subscription, enter that value as the **Maximum number of agents** parameter. For example, you might define two variables named **Location** and **Browser** as follows: @@ -721,32 +590,31 @@ For example, you might define two variables named **Location** and **Browser** a * **Location** = `US,Europe` * **Browser** = `IE,Chrome,Edge,Firefox` -The following configuration will execute the deployment eight times using +The following configuration executes the deployment eight times using a maximum of four agents at any one time: * **Multipliers** = `Location,Browser` * **Maximum number of agents** = `4` -With multi-configuration you can run multiple jobs, each with a different value for one, or more variables (multipliers). If you want to run the same job on multiple agents, then you can use **multi-agent** option of parallelism. The test slicing example above can be accomplished through multi-agent option. +With multi-configuration you can run multiple jobs, each with a different value for one, or more variables (multipliers). If you want to run the same job on multiple agents, then you can use **multi-agent** option of parallelism. The previous test slicing example can be accomplished through multi-agent option. * * * ## Slicing -An agent job can be used to run a suite of tests in parallel. For example, you can run a large suite of 1000 tests on a single agent. Or, you can use two agents and run 500 tests on each one in parallel. +An agent job can be used to run a suite of tests in parallel. For example, you can run a large suite of 1,000 tests on a single agent. Or, you can use two agents and run 500 tests on each one in parallel. -To leverage slicing, the tasks in the job should be smart enough to understand the slice they belong to. +To apply slicing, the tasks in the job should be smart enough to understand the slice they belong to. -The Visual Studio Test task is one such task that supports test slicing. If you have installed multiple agents, you can specify how the Visual Studio Test task will run in parallel on these agents. +The Visual Studio Test task is one such task that supports test slicing. If you installed multiple agents, you can specify how the Visual Studio Test task runs in parallel on these agents. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" The `parallel` strategy enables a job to be duplicated many times. Variables `System.JobPositionInPhase` and `System.TotalJobsInPhase` are added to each job. The variables can then be used within your scripts to divide work among the jobs. -See [Parallel and multiple execution using agent jobs](#parallelexec). +See [Parallel and multiple execution using agent jobs](#multi-job-configuration). -The following job will be dispatched five times with the values of `System.JobPositionInPhase` and `System.TotalJobsInPhase` set appropriately. +The following job is dispatched five times with the values of `System.JobPositionInPhase` and `System.TotalJobsInPhase` set appropriately. ```yaml jobs: @@ -755,23 +623,17 @@ jobs: parallel: 5 ``` -::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) -Specify the **multi-agent** option on an agent job to leverage slicing. +Specify the **multi-agent** option on an agent job to apply slicing. The job is dispatched as many times as the number of agents you specify, and the variables `System.JobPositionInPhase` and `System.TotalJobsInPhase` are automatically set in each job. * * * ## Job variables -If you are using YAML, variables can be specified on the job. The variables can be passed to task inputs using the macro syntax $(variableName), or accessed within a script using the stage variable. +If you're using YAML, variables can be specified on the job. The variables can be passed to task inputs using the macro syntax $(variableName), or accessed within a script using the stage variable. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" Here's an example of defining variables in a job and using them within tasks. @@ -790,42 +652,26 @@ steps: - powershell: Write-Host "Input macro = $(my var with spaces). Env var = $env:MY_VAR_WITH_SPACES" ``` -::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) -Job variables are not yet supported in the web editor. +Job variables aren't yet supported in the web editor. * * * For information about using a **condition**, see [Specify conditions](conditions.md). ## Workspace -::: moniker range=">= azure-devops-2019" - When you run an agent pool job, it creates a workspace on the agent. The workspace is a directory in which it downloads the source, runs steps, and produces outputs. The workspace directory can be referenced in your job using `Pipeline.Workspace` variable. Under this, various subdirectories are created: -::: moniker-end - -::: moniker range="< azure-devops-2019" - -When you run an agent pool job, it creates a workspace on the agent. The workspace is a directory in which it downloads the source, runs steps, and produces outputs. The workspace directory can be referenced in your job using `Agent.BuildDirectory` variable. Under this, various subdirectories are created: - -::: moniker-end - -- `Build.SourcesDirectory` is where tasks download the application's source code. -- `Build.ArtifactStagingDirectory` is where tasks download artifacts needed for the pipeline or upload artifacts before they are published. -- `Build.BinariesDirectory` is where tasks write their outputs. -- `Common.TestResultsDirectory` is where tasks upload their test results. +* `Build.SourcesDirectory` is where tasks download the application's source code. +* `Build.ArtifactStagingDirectory` is where tasks download artifacts needed for the pipeline or upload artifacts before they're published. +* `Build.BinariesDirectory` is where tasks write their outputs. +* `Common.TestResultsDirectory` is where tasks upload their test results. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" -The `$(Build.ArtifactStagingDirectory)` and `$(Common.TestResultsDirectory)` are always deleted and recreated prior to every build. +The `$(Build.ArtifactStagingDirectory)` and `$(Common.TestResultsDirectory)` are always deleted and recreated before every build. -When you run a pipeline on a **self-hosted agent**, by default, none of the subdirectories other than `$(Build.ArtifactStagingDirectory)` and `$(Common.TestResultsDirectory)` are cleaned in between two consecutive runs. As a result, you can do incremental builds and deployments, provided that tasks are implemented to make use of that. You can override this behavior using the `workspace` setting on the job. +When you run a pipeline on a **self-hosted agent**, by default, none of the subdirectories other than `$(Build.ArtifactStagingDirectory)` and `$(Common.TestResultsDirectory)` are cleaned in between two consecutive runs. As a result, you can do incremental builds and deployments, if tasks are implemented to make use of them. You can override this behavior using the `workspace` setting on the job. > [!IMPORTANT] > The workspace clean options are applicable only for self-hosted agents. Jobs are always run on a new agent with Microsoft-hosted agents. @@ -836,11 +682,11 @@ When you run a pipeline on a **self-hosted agent**, by default, none of the subd clean: outputs | resources | all # what to clean up before the job runs ``` -When you specify one of the `clean` options, they are interpreted as follows: +When you specify one of the `clean` options, they're interpreted as follows: -- `outputs`: Delete `Build.BinariesDirectory` before running a new job. -- `resources`: Delete `Build.SourcesDirectory` before running a new job. -- `all`: Delete the entire `Pipeline.Workspace` directory before running a new job. +* `outputs`: Delete `Build.BinariesDirectory` before running a new job. +* `resources`: Delete `Build.SourcesDirectory` before running a new job. +* `all`: Delete the entire `Pipeline.Workspace` directory before running a new job. ```yaml jobs: @@ -853,39 +699,33 @@ When you specify one of the `clean` options, they are interpreted as follows: ``` > [!NOTE] -> Depending on your agent capabilities and pipeline demands, each job may be routed to a different agent in your self-hosted pool. As a result, you may get a new agent for subsequent pipeline runs (or stages or jobs in the same pipeline), so **not** cleaning is not a guarantee that subsequent runs, jobs, or stages will be able to access outputs from previous runs, jobs, or stages. You can configure agent capabilities and pipeline demands to specify which agents are used to run a pipeline job, but unless there is only a single agent in the pool that meets the demands, there is no guarantee that subsequent jobs will use the same agent as previous jobs. For more information, see [Specify demands](demands.md). +> Depending on your agent capabilities and pipeline demands, each job could be routed to a different agent in your self-hosted pool. As a result, you can get a new agent for subsequent pipeline runs (or stages or jobs in the same pipeline), so **not** cleaning isn't a guarantee that subsequent runs, jobs, or stages are able to access outputs from previous runs, jobs, or stages. You can configure agent capabilities and pipeline demands to specify which agents are used to run a pipeline job. But unless there's only a single agent in the pool that meets the demands, there's no guarantee that subsequent jobs use the same agent as previous jobs. For more information, see [Specify demands](demands.md). -In addition to workspace clean, you can also configure cleaning by configuring the **Clean** setting in the pipeline settings UI. When the **Clean** setting is **true**, which is also its default value, it is equivalent to specifying `clean: true` for every [checkout](/azure/devops/pipelines/yaml-schema/steps-checkout) step in your pipeline. When you specify `clean: true`, you'll run `git clean -ffdx` followed by `git reset --hard HEAD` before git fetching. To configure the **Clean** setting: +In addition to workspace clean, you can also configure cleaning by configuring the **Clean** setting in the pipeline settings UI. When the **Clean** setting is **true**, which is also its default value, it's equivalent to specifying `clean: true` for every [checkout](/azure/devops/pipelines/yaml-schema/steps-checkout) step in your pipeline. When you specify `clean: true`, you run `git clean -ffdx` followed by `git reset --hard HEAD` before git fetching. To configure the **Clean** setting: 1. Edit your pipeline, choose **...**, and select **Triggers**. :::image type="content" source="media/pipeline-triggers/edit-triggers.png" alt-text="Edit triggers."::: -2. Select **YAML**, **Get sources**, and configure your desired **Clean** setting. The default is **true**. +1. Select **YAML**, **Get sources**, and configure your desired **Clean** setting. The default is **true**. :::image type="content" source="media/clean-setting.png" alt-text="Clean setting."::: -::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) -When you run a pipeline on a self-hosted agent, by default, none of the subdirectories are cleaned in between two consecutive runs. As a result, you can run incremental builds and deployments, provided that tasks are implemented to do that. However, you can override this behavior using the `Clean build` option under `Get sources` task. The options vary depending on the type of repository that you use. + +When you run a pipeline on a self-hosted agent, by default, none of the subdirectories are cleaned in between two consecutive runs. As a result, you can run incremental builds and deployments, if tasks are implemented to do that. However, you can override this behavior using the `Clean build` option under `Get sources` task. The options vary depending on the type of repository that you use. - [GitHub](../repos/github.md#checkout) - [Azure Repos Git](../repos/azure-repos-git.md) - [TFVC](../repos/tfvc.md) * * * - ## Artifact download This example YAML file publishes the artifact `WebSite` and then downloads the artifact to `$(Pipeline.Workspace)`. The Deploy job only runs if the Build job is successful. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" ```yaml # test and upload my code as an artifact named WebSite @@ -910,39 +750,27 @@ jobs: displayName: 'Download Build Artifacts' inputs: artifactName: WebSite - downloadPath: $(System.DefaultWorkingDirectory) + downloadPath: $(Pipeline.Workspace) dependsOn: Build condition: succeeded() ``` -::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) -In a release pipeline, you may choose to skip the - [download of artifacts](../release/artifacts.md#download) - during the job execution. Use this option if you want to implement - your own custom logic for downloading artifacts by using tasks, or if the tasks in a particular job do not rely on the artifacts. -::: moniker range=">=tfs-2018" +In a release pipeline, you can choose to skip the [download of artifacts](../release/artifacts.md) during the job execution. Use this option if you want to implement your own custom logic for downloading artifacts by using tasks, or if the tasks in a particular job don't rely on the artifacts. -Alternatively, you can choose to download specific [artifacts](../release/artifacts.md#download) during the job execution in a release. Use this option if the tasks in a particular job rely on only specific artifacts. - -::: moniker-end +Alternatively, you can choose to download specific [artifacts](../release/artifacts.md) during the job execution in a release. Use this option if the tasks in a particular job rely on only specific artifacts. * * * + For information about using **dependsOn** and **condition**, see [Specify conditions](conditions.md). ## Access to OAuth token - You can allow scripts running in a job to access the current Azure Pipelines or TFS OAuth security token. - The token can be used to authenticate to the Azure Pipelines REST API. + You can allow scripts running in a job to access the current Azure Pipelines OAuth security token. The token can be used to authenticate to the Azure Pipelines REST API. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" The OAuth token is always available to YAML pipelines. It must be explicitly mapped into the task or step using `env`. @@ -961,13 +789,8 @@ steps: SYSTEM_ACCESSTOKEN: $(system.accesstoken) ``` -::: moniker-end -::: moniker range="tfs-2018" -YAML is not supported in TFS. -::: moniker-end - #### [Classic](#tab/classic/) -Select the **Allow scripts to access OAuth token** option in the control options for the job. The token will be available as the environment variable `SYSTEM_ACCESSTOKEN`. +Select the **Allow scripts to access OAuth token** option in the control options for the job. The token is available as the environment variable `SYSTEM_ACCESSTOKEN`. * * * ## What's next diff --git a/docs/pipelines/process/pipeline-default-branch.md b/docs/pipelines/process/pipeline-default-branch.md index 78ec85ebd50..b886a49360e 100644 --- a/docs/pipelines/process/pipeline-default-branch.md +++ b/docs/pipelines/process/pipeline-default-branch.md @@ -1,31 +1,43 @@ --- title: Pipeline default branch -description: Configure a pipeline's default branch +description: See how to configure a pipeline's default branch in Azure Pipelines. ms.topic: conceptual ms.author: sandrica author: silviuandrica -ms.date: 02/01/2022 +ms.date: 08/06/2024 monikerRange: 'azure-devops || >= azure-devops-2020' --- -# The pipeline default branch +# Pipeline default branch [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -A pipeline's default branch defines the pipeline version used for manual builds, [scheduled builds](scheduled-triggers.md), [retention policies](../policies/retention.md), and in [pipeline resource triggers](pipeline-triggers.md). +This article describes how to view and edit a pipeline's default branch. A pipeline's default branch defines the pipeline version used for manual builds, scheduled builds, retention policies, and in pipeline resource triggers. By default, a pipeline's default branch is the default branch of the repository. -By default, a pipeline's default branch is the default branch of the repository. +## View and update the default branch To view and update the **Default branch for manual and scheduled builds** setting: -1. [Go to the pipeline details](../create-first-pipeline.md#view-and-manage-your-pipelines) for your pipeline, and choose **Edit**. +1. In your Azure DevOps project, select your pipeline from the **Pipelines** list. +1. On the pipeline page, select **Edit**. - :::image type="content" source="media/pipeline-triggers/pipeline-edit.png" alt-text="Edit pipeline."::: + :::image type="content" source="media/pipeline-triggers/pipeline-edit.png" alt-text="Screenshot that shows selecting Edit for a pipeline."::: -2. Choose **...** and select **Triggers**. +1. In the **More actions** menu, select **Triggers**. - :::image type="content" source="media/pipeline-triggers/edit-triggers.png" alt-text="Edit triggers."::: + :::image type="content" source="media/pipeline-triggers/edit-triggers.png" alt-text="Screenshot that shows selecting Triggers for edit."::: -3. Select **YAML**, **Get sources**, and view the **Default branch for manual and scheduled builds** setting. If you change it, choose **Save** or **Save & queue** to save the change. +1. Select **YAML** > **Get sources**, and view the **Default branch for manual and scheduled builds** setting. - :::image type="content" source="media/pipeline-triggers/default-branch-setting.png" alt-text="Default branch for manual and scheduled builds setting."::: +1. To change the branch, select the **Browse** icon next to the branch name, select a different branch name, and select **Select**. Then select **Save** or **Save & queue** on the pipeline page. + + :::image type="content" source="media/pipeline-triggers/default-branch-setting.png" alt-text="Screenshot that shows the Default branch for manual and scheduled builds setting."::: + +> [!IMPORTANT] +> Azure Pipelines loads a maximum of 2,000 branches from a repository into the **Default branch for manual and scheduled builds** selector. If you don't see your desired branch in the list, enter the desired branch name manually. + +## Related content +- [View and manage your pipelines](../create-first-pipeline.md#view-and-manage-your-pipelines) +- [Configure schedules for pipelines](scheduled-triggers.md) +- [Trigger pipelines](pipeline-triggers.md) +- [Set retention policies for builds, releases, and tests](../policies/retention.md) diff --git a/docs/pipelines/process/pipeline-triggers-classic.md b/docs/pipelines/process/pipeline-triggers-classic.md deleted file mode 100644 index 477859b5fd4..00000000000 --- a/docs/pipelines/process/pipeline-triggers-classic.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Configure build completion triggers (classic) -description: Configure build completion triggers (classic) -ms.topic: conceptual -ms.author: sdanie -author: steved0x -ms.date: 01/25/2023 -monikerRange: ">=azure-devops-2019" ---- - -# Trigger one pipeline after another (classic) - -[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] - -> [!div class="op_single_selector"] -> - [YAML pipelines](pipeline-triggers.md) -> - [Classic pipelines](pipeline-triggers-classic.md) - -Large products have several components that are dependent on each other. -These components are often independently built. When an upstream component (a library, for example) changes, the downstream dependencies have to be rebuilt and revalidated. - -In situations like these, add a pipeline trigger to run your pipeline upon the successful completion of the **triggering pipeline**. - -## Add a build completion trigger - -In the classic editor, pipeline triggers are called **build completion triggers**. You can select any other build in the same project to be the triggering pipeline. - -After you add a **build completion** trigger, select the **triggering build**. If the triggering build is sourced from a Git repo, you can also specify **branch filters**. If you want to use wildcard characters, then type the branch specification (for example, `features/modules/*`) and then press Enter. - -> [!NOTE] -> Keep in mind that in some cases, a single [multi-job build](phases.md) could meet your needs. -> However, a build completion trigger is useful if your requirements include different configuration settings, options, or a different team to own the dependent pipeline. - -## Download artifacts from the triggering build - -In many cases, you'll want to download artifacts from the triggering build. To do this: - -1. Edit your build pipeline. - -1. Add the **Download Build Artifacts** task to one of your jobs under **Tasks**. - -1. For **Download artifacts produced by**, select **Specific build**. - -1. Select the team **Project** that contains the triggering build pipeline. - -1. Select the triggering **Build pipeline**. - -1. Select **When appropriate, download artifacts from the triggering build**. - -1. Even though you specified that you want to download artifacts from the triggering build, you must still select a value for **Build**. The option you choose here determines which build will be the source of the artifacts whenever your triggered build is run because of any other reason than `BuildCompletion` (e.g. `Manual`, `IndividualCI`, `Schedule`, and so on). - -1. Specify the **Artifact name** and make sure it matches the name of the artifact published by the triggering build. - -1. Specify the **Destination directory** to which you want to download the artifacts. For example: `$(Build.BinariesDirectory)` - diff --git a/docs/pipelines/process/pipeline-triggers.md b/docs/pipelines/process/pipeline-triggers.md index 5436c616c3f..c6507a83a5e 100644 --- a/docs/pipelines/process/pipeline-triggers.md +++ b/docs/pipelines/process/pipeline-triggers.md @@ -4,8 +4,7 @@ description: Configure pipeline triggers ms.topic: conceptual ms.author: sdanie author: steved0x -ms.date: 06/06/2023 -ms.custom: contperf-fy21q3 +ms.date: 04/05/2024 monikerRange: ">=azure-devops-2020" --- @@ -24,10 +23,14 @@ In situations like these, add a pipeline trigger to run your pipeline upon the s > [!NOTE] > Previously, you may have navigated to the classic editor for your YAML pipeline and configured **build completion triggers** in the UI. While that model still works, it is no longer recommended. The recommended approach is to specify **pipeline triggers** directly within the YAML file. Build completion triggers as defined in the classic editor have various drawbacks, which have now been addressed in pipeline triggers. For instance, there is no way to trigger a pipeline on the same branch as that of the triggering pipeline using build completion triggers. +> +> Triggers defined using the pipeline settings UI take precedence over YAML triggers. To delete UI scheduled triggers from a YAML pipeline, see [UI settings override YAML scheduled triggers](../troubleshooting/troubleshoot-triggers.md#ui-settings-override-yaml-scheduled-triggers). + + ## Configure pipeline resource triggers -To trigger a pipeline upon the completion of another pipeline, configure a [pipeline resource](resources.md#define-a-pipelines-resource) trigger. +To trigger a pipeline upon the completion of another pipeline, configure a [pipeline resource](resources.md#define-a-pipelines-resource) trigger. The following example configures a pipeline resource trigger so that a pipeline named `app-ci` runs after any run of the `security-lib-ci` pipeline completes. @@ -60,7 +63,7 @@ This example has the following two pipelines. ``` * `- pipeline: securitylib` specifies the name of the pipeline resource. Use the label defined here when referring to the pipeline resource from other parts of the pipeline, such as when using pipeline resource variables or downloading artifacts. -* `source: security-lib-ci` specifies the name of the pipeline referenced by this pipeline resource. You can retrieve a pipeline's name from the Azure DevOps portal in several places, such as the [Pipelines landing page](../create-first-pipeline.md#pipelines-landing-page). By default, pipelines are named after the repository that contains the pipeline. To update a pipeline's name, see [Pipeline settings](../customize-pipeline.md#pipeline-settings). +* `source: security-lib-ci` specifies the name of the pipeline referenced by this pipeline resource. You can retrieve a pipeline's name from the Azure DevOps portal in several places, such as the [Pipelines landing page](../create-first-pipeline.md#view-and-manage-your-pipelines). By default, pipelines are named after the repository that contains the pipeline. To update a pipeline's name, see [Pipeline settings](../customize-pipeline.md#pipeline-settings). If the pipeline is contained in a folder, include the folder name, including the leading `\`, for example `\security pipelines\security-lib-ci`. * `project: FabrikamProject` - If the triggering pipeline is in another Azure DevOps project, you must specify the project name. This property is optional if both the source pipeline and the triggered pipeline are in the same project. If you specify this value and your pipeline doesn't trigger, see the note at the end of this section. * `trigger: true` - Use this syntax to trigger the pipeline when any version of the source pipeline completes. See the following sections in this article to learn how to filter which versions of the source pipeline completing will trigger a run. When filters are specified, the source pipeline run must match all of the filters to trigger a run. @@ -69,6 +72,8 @@ If the triggering pipeline and the triggered pipeline use the same repository, b > [!NOTE] > In some scenarios, the default branch for manual builds and scheduled builds doesn't include a `refs/heads` prefix. For example, the default branch might be set to `main` instead of to `refs/heads/main`. In this scenario, *a trigger from a different project doesn't work*. If you encounter issues when you set `project` to a value other than the target pipeline's, you can update the default branch to include `refs/heads` by changing its value to a different branch, and then by changing it back to the default branch you want to use. +Configuring pipeline completion triggers is not supported in YAML templates. You can still define pipeline resources in templates. + ## Branch filters You can optionally specify the branches to include or exclude when configuring the trigger. If you specify branch filters, a new pipeline is triggered whenever a source pipeline run is successfully completed that matches the branch filters. In the following example, the `app-ci` pipeline runs if the `security-lib-ci` completes on any `releases/*` branch, except for `releases/old*`. @@ -87,6 +92,22 @@ resources: - releases/old* ``` +To trigger the child pipeline for different branches for which the parent is triggered, include all the branch filters for which the parent is triggered. In the following example, the `app-ci` pipeline runs if the `security-lib-ci` completes on any `releases/*` branch or main branch, except for `releases/old*`. + +```yaml +# app-ci YAML pipeline +resources: + pipelines: + - pipeline: securitylib + source: security-lib-ci + trigger: + branches: + include: + - releases/* + - main + exclude: + - releases/old* +``` > [!NOTE] > If your branch filters aren't working, try using the prefix `refs/heads/`. For example, use `refs/heads/releases/old*`instead of `releases/old*`. @@ -124,7 +145,7 @@ resources: :::moniker-end -You can trigger your pipeline when one or more stages of the triggering pipeline complete by using the `stages` filter. If you provide multiple stages, the triggered pipeline runs when all of the listed stages complete. +By default your target pipeline is triggered only when the source pipeline completes. If your source pipeline has stages, you can use stage filters to trigger your pipeline to run when one or more stages of the source pipeline complete (instead of the entire pipeline) by configuring a `stages` filter with one or more stages. If you provide multiple stages, the triggered pipeline runs when all of the listed stages complete. ```yml resources: @@ -156,7 +177,7 @@ A typical scenario in which the pipeline completion trigger doesn't fire is when ## Combining trigger types -When you specify both CI triggers and pipeline triggers in your pipeline, you can expect new runs to be started every time a push is made that matches the filters the CI trigger, and a run of the source pipeline is completed that matches the filters of the pipeline completion trigger. +When you specify both CI triggers and pipeline triggers in your pipeline, you can expect new runs to be started every time a push is made that matches the filters of the CI trigger, and a run of the source pipeline is completed that matches the filters of the pipeline completion trigger. For example, consider two pipelines named `A` and `B` that are in the same repository, both have CI triggers, and `B` has a pipeline completion trigger configured for the completion of pipeline `A`. If you make a push to the repository: @@ -164,6 +185,4 @@ For example, consider two pipelines named `A` and `B` that are in the same repos - At the same time, a new run of `B` is started, based on its CI trigger. This run consumes the artifacts from a previous run of pipeline `A`. - When `A` completes, it triggers another run of `B`, based on the pipeline completion trigger in `B`. -To prevent triggering two runs of `B` in this example, you must remove its CI trigger or pipeline trigger. - - +To prevent triggering two runs of `B` in this example, you must disable its CI trigger (`trigger: none`) or pipeline trigger (`pr: none`). diff --git a/docs/pipelines/process/repository-resource.md b/docs/pipelines/process/repository-resource.md index fcc0a182d61..b1bfd4fb29b 100644 --- a/docs/pipelines/process/repository-resource.md +++ b/docs/pipelines/process/repository-resource.md @@ -5,7 +5,7 @@ ms.custom: pipelinesresourcesrefresh ms.reviewer: vijayma ms.date: 09/15/2022 ms.topic: how-to -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" --- # Protect a repository resource diff --git a/docs/pipelines/process/resources.md b/docs/pipelines/process/resources.md index 033f0ef71a8..8e1adb453b4 100644 --- a/docs/pipelines/process/resources.md +++ b/docs/pipelines/process/resources.md @@ -1,34 +1,23 @@ --- -title: Define YAML resources for Azure Pipelines -ms.custom: seodec18 -description: Learn how to define YAML resources that can be consumed anywhere in your pipelines. -ms.topic: how-to +title: Resources in YAML pipelines +description: Learn about defining and consuming YAML resources that you can use anywhere in your pipelines jobs, or to trigger jobs and automation. +ms.topic: conceptual ms.assetid: b3ca305c-b587-4cb2-8ac5-52f6bd46c25e -ms.date: 04/14/2023 -monikerRange: '>= azure-devops-2019' +ms.date: 07/01/2024 +monikerRange: "<=azure-devops" --- -# Define resources in YAML +# Resources in YAML pipelines [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Resources in YAML represent sources of pipelines, builds, repositories, containers, packages, and webhooks. -Resources also provide you the full traceability of the services used in your pipeline including the version, artifacts, associated commits, and work items. When you define a resource, it can be consumed anywhere in your pipeline. And, you can fully automate your DevOps workflow by subscribing to trigger events on your resources. +This article discusses resources for YAML pipelines. A resource is anything used by a pipeline that exists outside the pipeline. After you define a resource, you can consume it anywhere in your pipeline. -For more information, see [About resources](about-resources.md). -### Schema +Resources provide full traceability for the services your pipeline uses, including the version, artifacts, associated commits, and work items. You can fully automate your DevOps workflows by subscribing to trigger events on your resources. -```yaml -resources: - pipelines: [ pipeline ] - builds: [ build ] - repositories: [ repository ] - containers: [ container ] - packages: [ package ] - webhooks: [ webhook ] -``` +## Resources schema -### Variables +Resources in YAML represent sources of pipelines, builds, repositories, containers, packages, and webhooks. For complete schema information, see the [resources definition](/azure/devops/pipelines/yaml-schema/resources) in the [YAML schema reference for Azure Pipelines](/azure/devops/pipelines/yaml-schema). When a resource triggers a pipeline, the following variables get set: @@ -37,47 +26,34 @@ resources.triggeringAlias resources.triggeringCategory ``` -These values are empty if a resource doesn't trigger a pipeline run. The variable `Build.Reason` must be `ResourceTrigger` for these values to get set. +The variable `Build.Reason` must be `ResourceTrigger` for these values to get set. The values are empty if a resource didn't trigger the pipeline run. -## Define a `pipelines` resource + +## Pipelines resource definition -If you have a pipeline that produces artifacts, you can consume the artifacts by defining a `pipelines` resource. `pipelines` is a dedicated resource only for Azure Pipelines. You can also set triggers on a pipeline resource for your CD workflows. +If you have a pipeline that produces artifacts, you can consume the artifacts by defining a `pipelines` resource. Only Azure Pipelines can use the `pipelines` resource. You can set triggers for your continuous deployment (CD) workflows on a pipeline resource. -In your resource definition, `pipeline` is a unique value that you can use to reference the pipeline resource later on. `source` is the name of the pipeline that produces an artifact. Use the label defined by `pipeline` to reference the pipeline resource from other parts of the pipeline, such as when using pipeline resource variables or downloading artifacts. +In your resource definition, `pipeline` is a unique value that you can use to reference the pipeline resource later in your pipeline. The `source` is the name of the pipeline that produced the pipeline artifact. For complete schema information, see the [resources.pipelines.pipeline definition](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline). -For an alternative way to download pipelines, see the tasks in [Pipeline Artifacts](../artifacts/pipeline-artifacts.md). +You use the label defined by `pipeline` to reference the pipeline resource from other parts of your pipeline, such as when using pipeline resource variables or downloading artifacts. For an alternative way to download pipeline artifacts, see [Download artifacts](../artifacts/pipeline-artifacts.md#download-artifacts). -## [Schema](#tab/schema) - -```yaml -resources: # types: pipelines | builds | repositories | containers | packages - pipelines: - - pipeline: string # identifier for the resource used in pipeline resource variables - project: string # project for the source; optional for current project - source: string # name of the pipeline that produces an artifact - version: string # the pipeline run number to pick the artifact, defaults to latest pipeline successful across all stages; Used only for manual or scheduled triggers - branch: string # branch to pick the artifact, optional; defaults to all branches; Used only for manual or scheduled triggers - tags: [ string ] # list of tags required on the pipeline to pickup default artifacts, optional; Used only for manual or scheduled triggers - trigger: # triggers aren't enabled by default unless you add trigger section to the resource - branches: # branch conditions to filter the events, optional; Defaults to all branches. - include: [ string ] # branches to consider the trigger events, optional; Defaults to all branches. - exclude: [ string ] # branches to discard the trigger events, optional; Defaults to none. - tags: [ string ] # list of tags to evaluate for trigger event, optional - stages: [ string ] # list of stages to evaluate for trigger event, optional -``` +> [!IMPORTANT] +> When you define a pipeline resource trigger: +> - If the `pipeline` resource is from the same repository as the current pipeline, or `self`, triggering follows the same branch and commit on which the event is raised. +> - If the pipeline resource is from a different repository, the current pipeline triggers on the default branch of the `pipeline` resource repository. -## [Example](#tab/example) +### Example pipeline resource definitions -To consume artifacts from a pipeline within the same project, use the following schema. +The following example consumes artifacts from a pipeline within the same project. ```yaml resources: pipelines: - - pipeline: SmartHotel-resource # identifier for the resource (used in pipeline resource variables) - source: SmartHotel-CI # name of the pipeline that produces an artifact + - pipeline: SmartHotel-resource # identifier to use in pipeline resource variables + source: SmartHotel-CI # name of the pipeline that produces the artifacts ``` -To consume a pipeline from another project, include the project name and source name. +To consume a pipeline from another project, you include the project name and source name. The following example uses `branch` to resolve the default version when the pipeline is triggered manually or scheduled. The branch input can't have wildcards. ```yaml resources: @@ -85,10 +61,10 @@ resources: - pipeline: SmartHotel project: DevOpsProject source: SmartHotel-CI - branch: releases/M142 # This branch is used for resolving default version when the pipeline is triggered manually or scheduled. The branch input should not have wild cards + branch: releases/M142 ``` -Pipeline resource with simple trigger. +The following example shows a pipeline resource with a simple trigger. ```yaml resources: @@ -99,7 +75,7 @@ resources: trigger: true ``` -Pipeline resource trigger with branch conditions. +The following example shows a pipeline resource `trigger` with branch conditions. ```yaml resources: @@ -113,7 +89,7 @@ resources: - resources.triggeringAlias ``` -Stages filters for triggers. +The following example uses `stages` filters for evaluating trigger conditions for CD pipelines. Stages use the `AND` operator. On successful completion of all the provided stages, the CD pipeline triggers. ```yml resources: @@ -122,12 +98,14 @@ resources: project: Fabrikam source: Farbrikam-CI trigger: - stages: ### This stage filter is used when evaluating conditions for triggering your CD pipeline - - PreProduction ### stages are AND'ed. On successful completion of all the stages provided, your CD pipeline gets triggered. + stages: + - PreProduction - Production ``` -Tag filters for default version evaluation and for triggers. +The following example uses `tags` filters for default version evaluation and for triggers. Tags use the `AND` operator. + +The `tags` are set on the continuous integration (CI) or CD pipeline. These tags differ from the tags set on branches in the Git repository. ```yml resources: @@ -135,64 +113,64 @@ resources: - pipeline: MyCIAlias project: Fabrikam source: Farbrikam-CI - tags: ### tags are used for resolving default version when the pipeline is triggered manually or scheduled - - Production ### Tags are AND'ed + tags: + - Production trigger: - tags: ### This filter is used for triggering the pipeline run - - Production ### Tags are AND'ed + tags: + - Production - Signed ``` -These examples are tags set on the continuous integration (CI) pipeline. These tags are different from the tags set on the branches in the git repository. - ---- - -> [!IMPORTANT] -> When you define a resource trigger, if its pipeline resource is from the same repository (say self) as the current pipeline, triggering follows the same branch and commit on which the event is raised. -> But, if the pipeline resource is from a different repository, the current pipeline triggers on the default branch of the self repository. + +### Pipelines artifact version evaluation +The resource pipeline's artifact version depends on how the pipeline triggers. +#### Manual or scheduled trigger -### Evaluation of artifact version - -The version of the resource pipeline's artifacts depends on how your pipeline is triggered. - -If your pipeline runs because you manually triggered it or due to a scheduled run, the version of artifacts's version is defined by the values of the `version`, `branch`, and `tags` properties. +If the pipeline run is manually triggered or scheduled, the values of the `version`, `branch`, and `tags` properties define the artifact version. The `branch` input can't have wildcards. The `tags` properties use the `AND` operator. |Specified properties | Artifact version | |---------|---------| -| `version` | The artifacts from the build having the specified run number | -| `branch` | The artifacts from the latest build performed on the specified branch | +| `version` | The artifacts from the build that have the specified run number | +| `branch` | The artifacts from the latest build done on the specified branch | | `tags` list | The artifacts from the latest build that has all the specified tags | -| `branch` and `tags` list | The artifacts from the latest build performed on the specified branch _and_ that has all the specified tags | +| `branch` and `tags` list | The artifacts from the latest build done on the specified branch that has all the specified tags | +| `version` and `branch` | The artifacts from the build with the specified run number and the specified branch. | | None | The artifacts from the latest build across all the branches | -Let's look at an example. Say your pipeline contains the following resource definition. -```yml +The following `pipeline` resource definition uses the `branch` and `tags` properties to evaluate the default version when the pipeline is triggered manually or scheduled. When you manually trigger the pipeline to run, the `MyCIAlias` pipeline artifacts version is the latest build done on the `main` branch that has the `Production` and `PrepProduction` tags. + +```yaml resources: pipelines: - pipeline: MyCIAlias project: Fabrikam source: Farbrikam-CI - branch: main ### This branch input cannot have wild cards. It is used for evaluating default version when pipeline is triggered manually or scheduled. - tags: ### These tags are used for resolving default version when the pipeline is triggered manually or scheduled - - Production ### Tags are AND'ed + branch: main + tags: + - Production - PreProduction ``` -When you manually trigger your pipeline to run, the version of the artifacts of the `MyCIAlias` pipeline is the one of the latest build done on the `main` branch and that has the `Production` and `PrepProduction` tags. -When your pipeline gets triggered because one of its resource pipelines completes, the version of the artifacts is the one of the triggering pipeline. The values of the `version`, `branch`, and `tags` properties are ignored. +#### Resource pipeline completion trigger + +When a pipeline triggers because one of its resource pipelines completes, the artifacts version is the version of the triggering pipeline. The values of the `version`, `branch`, and `tags` properties are ignored. |Specified triggers | Outcome | |---------|---------| -|`branches` | A new run of the current pipeline is triggered whenever the resource pipeline successfully completes a run on the `include` branches | -|`tags` | A new run of the current pipeline is triggered whenever the resource pipeline successfully completes a run that is tagged with _all_ the specified tags | -| `stages` | A new run of the current pipeline is triggered whenever the resource pipeline successfully executed the specified `stages` | -| `branches`, `tags`, and `stages` | A new run of the current pipeline is triggered whenever the resource pipeline run satisfies _all_ branch, tags, and stages conditions | -| `trigger: true` | A new run of the current pipeline is triggered whenever the resource pipeline successfully completes a run | -|Nothing | No new run of the current pipeline is triggered when the resource pipeline successfully completes a run| +| `branches` | A new pipeline run triggers whenever the resource pipeline successfully completes a run on one of the `include` branches. | +| `tags` | A new pipeline run triggers whenever the resource pipeline successfully completes a run tagged with all of the specified tags. | +| `stages` | A new pipeline run triggers whenever the resource pipeline successfully executes the specified `stages`. | +| `branches`, `tags`, and `stages` | A new pipeline run triggers whenever the resource pipeline run satisfies all branch, tags, and stages conditions. | +| `trigger: true` | A new pipeline run triggers whenever the resource pipeline successfully completes a run. | +| Nothing | No new pipeline run triggers when the resource pipeline successfully completes a run. | -Let's look at an example. Say your pipeline contains the following resource definition. +The following pipeline runs whenever the `SmartHotel-CI` resource pipeline: + +- Runs on one of the `releases` branches or on the `main` branch +- Is tagged with both `Verified` and `Signed` +- Completes both the `Production` and `PreProduction` stages ```yaml resources: @@ -216,67 +194,41 @@ resources: ``` -Your pipeline will run whenever the `SmartHotel-CI` pipelines runs on one of the `releases` branches or on the `main` branch, is tagged with both `Verified` and `Signed`, and it completed both the `Production` and `PreProduction` stages. +### Pipeline artifact download -### `download` for pipelines +The `download` step downloads artifacts associated with the current run or with another pipeline resource. -All artifacts from the current pipeline and from all `pipeline` resources are automatically downloaded and made available at the beginning of each `deployment` job. You can override this behavior. For more information, see [Pipeline Artifacts](../artifacts/pipeline-artifacts.md). Regular 'job' artifacts aren't automatically downloaded. Use `download` explicitly when needed. +All artifacts from the current pipeline and all its `pipeline` resources are automatically downloaded and made available at the beginning of each deployment job. You can override this behavior by setting `download` to `none`, or by specifying another pipeline resource identifier. -## [Schema](#tab/schema) +Regular job artifacts aren't automatically downloaded. Use `download` explicitly when needed. -```yaml -steps: -- download: [ current | pipeline resource identifier | none ] # disable automatic download if "none" - artifact: string ## artifact name, optional; downloads all the available artifacts if not specified - patterns: string # patterns representing files to include; optional -``` +Artifacts from the `pipeline` resource are downloaded to the *$(PIPELINE.WORKSPACE)/\/\* folder. For more information, see [Publish and download pipeline artifacts](../artifacts/pipeline-artifacts.md). -## [Example](#tab/example) +The optional `artifact` property specifies artifact names. If not specified, all available artifacts are downloaded. The optional `patterns` property defines patterns that represent files to include. For full schema information, see the [steps.download definition](/azure/devops/pipelines/yaml-schema/steps-download). ```yaml - job: deploy_windows_x86_agent steps: - - download: SmartHotel # pipeline resource identifier. - artifact: WebTier1 # artifact to download, optional; defaults to all the artifacts from the resource. - patterns: '**/*.zip' # mini match pattern to download specific files, optional; defaults to all files. -``` - -Or, to avoid downloading any of the artifacts: - -```yaml -- download: none + - download: SmartHotel + artifact: WebTier1 + patterns: '**/*.zip' ``` ---- -Artifacts from the `pipeline` resource get downloaded to `$(PIPELINE.WORKSPACE)//` folder. +:::moniker range=">=azure-devops-2020" ### Pipeline resource variables -In each run, the metadata for a pipeline resource is available to all jobs in the form of [predefined variables](../build/variables.md). The `` is the identifier that you gave for your pipeline resource. Pipeline resources variables are only available at runtime. - -## [Schema](#tab/schema) +In each run, the metadata for a pipeline resource is available to all jobs as [predefined variables](../build/variables.md). These variables are available to your pipeline only at runtime, and therefore can't be used in template expressions, which are evaluated at pipeline compile time. -```yaml -resources.pipeline..projectID -resources.pipeline..pipelineName -resources.pipeline..pipelineID -resources.pipeline..runName -resources.pipeline..runID -resources.pipeline..runURI -resources.pipeline..sourceBranch -resources.pipeline..sourceCommit -resources.pipeline..sourceProvider -resources.pipeline..requestedFor -resources.pipeline..requestedForID -``` +For more information, see [Pipeline resource metadata as predefined variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#pipeline-resource-metadata-as-predefined-variables). To learn more about variable syntax, see [Define variables](variables.md). -## [Example](#tab/example) +The following example returns the predefined variable values for the `myresourcevars` pipeline resource. ```yaml resources: pipelines: - - pipeline: myresourcevars # identifier for the pipeline resource - source: mypipeline # source pipeline definition name + - pipeline: myresourcevars + source: mypipeline trigger: true steps: @@ -292,30 +244,18 @@ steps: echo $(resources.pipeline.myresourcevars.requestedForID) ``` ---- +:::moniker-end -For more information, see [Pipeline resource metadata as predefined variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#pipeline-resource-metadata-as-predefined-variables). + +## Builds resource definition -## Define a `builds` resource +If you have an external CI build system that produces artifacts, you can consume artifacts with `builds` resources. A `build` resource can be from any external CI system like Jenkins, TeamCity, or CircleCI. -If you have an external CI build system that produces artifacts, you can consume artifacts with a `builds` resource. A `builds` resource can be any external CI systems like Jenkins, TeamCity, CircleCI, and so on. +The `builds` category is extensible. You can write an extension to consume artifacts from your build service, and introduce a new type of service as part of `builds`. -## [Schema](#tab/schema) +In the `build` definition, `version` defaults to the latest successful build. The `trigger` isn't enabled by default and must be explicitly set. For complete schema information, see the [resources.builds.build definition](/azure/devops/pipelines/yaml-schema/resources-builds-build). -```yaml -resources: # types: pipelines | builds | repositories | containers | packages - builds: - - build: string # identifier for the build resource - type: string # the type of your build service like Jenkins, circleCI etc. - connection: string # service connection for your build service. - source: string # source definition of the build - version: string # the build number to pick the artifact, defaults to Latest successful build - trigger: boolean # Triggers aren't enabled by default and should be explicitly set -``` - -`builds` is an extensible category. You can write an extension to consume artifacts from your builds service and introduce a new type of service as part of `builds`. Jenkins is a type of resource in `builds`. - -## [Example](#tab/example) +In the following example, Jenkins is the resource `type`. ```yaml resources: @@ -323,66 +263,40 @@ resources: - build: Spaceworkz type: Jenkins connection: MyJenkinsServer - source: SpaceworkzProj # name of the jenkins source project + source: SpaceworkzProj # name of the Jenkins source project trigger: true ``` ---- - > [!IMPORTANT] -> Triggers are only supported for hosted Jenkins where Azure DevOps has line of sight with Jenkins server. - -### `downloadBuild` task for builds +> Triggers are supported for hosted Jenkins only where Azure DevOps has line of sight with the Jenkins server. -You can consume artifacts from the `build` resource as part of your jobs using the `downloadBuild` task. Based on the type of `build` resource defined, this task automatically resolves to the corresponding download task for the service during the run time. +### The downloadBuild task -Artifacts from the `build` resource get downloaded to `$(PIPELINE.WORKSPACE)//` folder. - -> [!IMPORTANT] -> `build` resource artifacts aren't automatically downloaded in your jobs/deploy-jobs. You need to explicitly add the `downloadBuild` task for consuming the artifacts. +The `build` resource artifacts aren't automatically downloaded in your *jobs/deploy-jobs*. To consume artifacts from the `build` resource as part of your jobs, you need to explicitly add the `downloadBuild` task. You can customize the download behavior for each deployment or job. -## [Schema](#tab/schema) +This task automatically resolves to the corresponding download task for the type of `build` resource the runtime defines. Artifacts from the `build` resource are downloaded to the *$(PIPELINE.WORKSPACE)/\/* folder. -```yaml -- downloadBuild: string # identifier for the resource from which to download artifacts - artifact: string # artifact to download; if left blank, downloads all artifacts associated with the resource provided - patterns: string | [ string ] # a minimatch path or list of [minimatch paths](tasks/file-matching-patterns.md) to download; if blank, the entire artifact is downloaded -``` +In the `downloadBuild` definition, you specify the resource to download artifacts from. The optional `artifact` property specifies artifacts to download. If not specified, all artifacts associated with the resource are downloaded. -## [Example](#tab/example) -You can customize the download behavior for each deployment or job. +The optional `patterns` property defines a minimatch path or list of [minimatch paths](../tasks/file-matching-patterns.md) to download. If blank, the entire artifact is downloaded. For example, the following snippet downloads only the *\*.zip* files. ```yaml - job: deploy_windows_x86_agent steps: - - downloadBuild: Spaceworkz # build resource identifier. - patterns: '**/*.zip' # mini match pattern to download specific files, optional; defaults to all files. + - downloadBuild: Spaceworkz + patterns: '**/*.zip' ``` ---- +For complete schema information, see the [steps.downloadBuild definition](/azure/devops/pipelines/yaml-schema/steps-download-build). -## Define a `repositories` resource + +## Repository resource definition -If your pipeline has [templates in another repository](../process/templates.md#use-other-repositories), or if you want to use [multi-repo checkout](../repos/multi-repo-checkout.md) with a repository that requires a service connection, you must let the system know about that repository. -The `repository` keyword lets you specify an external repository. +The `repository` keyword lets you specify an external repository. You can use this resource if your pipeline has [templates in another repository](templates.md#store-templates-in-other-repositories) or you want to use [multi-repo checkout](../repos/multi-repo-checkout.md) with a repository that requires a service connection. You must let the system know about these repositories. -## [Schema](#tab/schema) +For example: ```yaml -resources: - repositories: - - repository: string # Required as first property. Alias for the repository. - endpoint: string # ID of the service endpoint connecting to this repository. - trigger: none | trigger | [ string ] # CI trigger for this repository, no CI trigger if skipped (only works for Azure Repos). - name: string # repository name (format depends on 'type'; does not accept variables). - ref: string # ref name to checkout; defaults to 'refs/heads/main'. The branch checked out by default whenever the resource trigger fires. - type: string # Type of repository: git, github, githubenterprise, and bitbucket. -``` - -## [Example](#tab/example) - -```yaml - resources: repositories: - repository: common @@ -391,85 +305,120 @@ resources: endpoint: MyContosoServiceConnection ``` ---- +For complete schema information, see the [resources.repositories.repository definition](/azure/devops/pipelines/yaml-schema/resources-repositories-repository). -### Type +### Repository resource types -Pipelines support the following values for the repository type: `git`, `github`, `githubenterprise`, and `bitbucket`. -The `git` type refers to Azure Repos Git repos. +Azure Pipelines supports the following values for the repository type: `git`, `github`, `githubenterprise`, and `bitbucket`. -|Type specified |Outcome |Example | -|---------|---------|---------| -|`type: git` | The `name` value refers to another repository in the same project. | `name: otherRepo` To refer to a repository in another project within the same organization, prefix the name with that project's name. An example is `name: OtherProject/otherRepo`. | -|`type: github` | The `name` value is the full name of the GitHub repository and includes the user or organization. | `name: Microsoft/vscode` | -|`type: githubenterprise` | the `name` value is the full name of the GitHub Enterprise repository and includes the user or organization. | `name: Microsoft/vscode` | -|`type: bitbucket` | The `name` value is the full name of the Bitbucket Cloud repository and includes the user or organization. | `name: MyBitbucket/vscode` | +- The `git` type refers to Azure Repos Git repos. +- GitHub Enterprise repos require a [GitHub Enterprise service connection](../library/service-endpoints.md#github-enterprise-server-service-connection) for authorization. +- Bitbucket Cloud repos require a [Bitbucket Cloud service connection](../library/service-endpoints.md#bitbucket-cloud-service-connection) for authorization. -GitHub Enterprise repos require a [GitHub Enterprise service connection](../library/service-endpoints.md#github-enterprise-server-service-connection) for authorization. +|Type |Name value |Example | +|---------|---------|---------| +|`type: git` | Another repository in the same project or same organization. | Same project: `name: otherRepo`
      Another project in the same organization: `name: otherProject/otherRepo`. | +|`type: github` | Full name of the GitHub repository including the user or organization. | `name: Microsoft/vscode` | +|`type: githubenterprise` | Full name of the GitHub Enterprise repository including the user or organization. | `name: Microsoft/vscode` | +|`type: bitbucket` | Full name of the Bitbucket Cloud repository including the user or organization. | `name: MyBitbucket/vscode` | -Bitbucket Cloud repos require a [Bitbucket Cloud service connection](../library/service-endpoints.md#bitbucket-cloud-service-connection) for authorization. +### Repository resource variables -### Use `checkout` to consume repository +:::moniker range=">=azure-devops-2020 ` is the identifier that you give your repository resource. -Use `checkout` keyword to consume your repos defined as part of `repository` resource. +```yaml +resources.repositories..name +resources.repositories..ref +resources.repositories..type +resources.repositories..id +resources.repositories..url +``` -### Schema +The following example has a repository resource with an alias of `common`, so the repository resource variables are accessed using `resources.repositories.common.*`. ```yaml +resources: + repositories: + - repository: common + type: git + ref: main + name: Repo + +variables: + ref: $[ resources.repositories.common.ref ] + name: $[ resources.repositories.common.name ] + id: $[ resources.repositories.common.id ] + type: $[ resources.repositories.common.type ] + url: $[ resources.repositories.common.url ] + steps: -- checkout: string # Required as first property. Configures checkout for the specified repository. - clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. - fetchDepth: string # Depth of Git graph to fetch. - fetchTags: string # Set to 'true' to sync tags when fetching the repo, or 'false' to not sync tags. See remarks for the default behavior. - lfs: string # Set to 'true' to download Git-LFS files. Default is not to download them. - persistCredentials: string # Set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it. - submodules: string # Set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules. - path: string # Where to put the repository. The root directory is $(Pipeline.Workspace). - condition: string # Evaluate this condition expression to determine whether to run this task. - continueOnError: boolean # Continue running even on failure? - displayName: string # Human-readable name for the task. - target: string | target # Environment in which to run this task. - enabled: boolean # Run this task when the job runs? - env: # Variables to map into the process's environment. - string: string # Name/value pairs - name: string # ID of the step. - timeoutInMinutes: string # Time to wait for this task to complete before the server kills it. - retryCountOnTaskFailure: string # Number of retries if the task fails. +- bash: | + echo "name = $(name)" + echo "ref = $(ref)" + echo "id = $(id)" + echo "type = $(type)" + echo "url = $(url)" ``` -Repos from the `repository` resource aren't automatically synced in your jobs. Use `checkout` to fetch your repos as part of your jobs. - -For more information, see [Check out multiple repositories in your pipeline](../repos/multi-repo-checkout.md). - -## Define a `containers` resource +::: moniker-end -If you need to consume a container image as part of your continuous integration/continuous delivery (CI/CD) pipeline, you can achieve it using `containers`. A container resource can be a public or private Docker Registry, or Azure Container Registry. +:::moniker range=">=azure-devops" +In each run, the following metadata for a repository resource is available to all jobs in the form of runtime variables. The `` is the identifier that you give your repository resource. -If you need to consume images from Docker registry as part of your pipeline, you can define a generic container resource (not `type` keyword required). +```yaml +resources.repositories..name +resources.repositories..ref +resources.repositories..type +resources.repositories..id +resources.repositories..url +resources.repositories..version +``` -## [Schema](#tab/schema) +The following example has a repository resource with an alias of `common`, so the repository resource variables are accessed using `resources.repositories.common.*`. ```yaml resources: - containers: - - container: string # identifier (A-Z, a-z, 0-9, and underscore) - image: string # container image name - options: string # arguments to pass to container at startup - endpoint: string # reference to a service connection for the private registry - env: { string: string } # list of environment variables to add - ports: [ string ] # ports to expose on the container - volumes: [ string ] # volumes to mount on the container - mapDockerSocket: bool # whether to map in the Docker daemon socket; defaults to true - mountReadOnly: # volumes to mount read-only - all default to false - externals: boolean # components required to talk to the agent - tasks: boolean # tasks required by the job - tools: boolean # installable tools like Python and Ruby - work: boolean # the work directory + repositories: + - repository: common + type: git + ref: main + name: Repo + +variables: + ref: $[ resources.repositories.common.ref ] + name: $[ resources.repositories.common.name ] + id: $[ resources.repositories.common.id ] + type: $[ resources.repositories.common.type ] + url: $[ resources.repositories.common.url ] + version: $[ resources.repositories.common.version ] + +steps: +- bash: | + echo "name = $(name)" + echo "ref = $(ref)" + echo "id = $(id)" + echo "type = $(type)" + echo "url = $(url)" + echo "version = $(version)" ``` -You can use a generic container resource as an image consumed as part of your job, or it can also be used for [Container jobs](../process/container-phases.md). If your pipeline requires the support of one or more services, you'll want to create and connect to [service containers](service-containers.md). You can use volumes to share data between services. +::: moniker-end + +### Checkout keyword for repositories -## [Example](#tab/example) +Repos from the `repository` resource aren't automatically synced in your jobs. Use the `checkout` keyword to fetch a repository defined as part of the `repository` resource. For complete schema information, see the [steps.checkout definition](/azure/devops/pipelines/yaml-schema/steps-checkout). + +For more information, see [Check out multiple repositories in your pipeline](../repos/multi-repo-checkout.md). + + +## Containers resource definition + +If you need to consume container images as part of your CI/CD pipelines, you can use `containers` resources. A `container` resource can be a public or private Docker registry or an Azure Container Registry instance. + +You can consume a generic container resource image as part of your job, or use the resource for [container jobs](../process/container-phases.md). If your pipeline requires the support of one or more services, you need to create and connect to [service containers](service-containers.md). You can use volumes to share data between services. + +If you need to consume images from a Docker registry as part of your pipeline, you can define a generic container resource. No `type` keyword is required. For example: ```yaml resources: @@ -479,39 +428,25 @@ resources: image: smartHotelApp ``` ---- +For complete schema information, see the [resources.containers.container definition](/azure/devops/pipelines/yaml-schema/resources-containers-container). -You can use a first class container resource type for Azure Container Registry (ACR) to consume your ACR images. This resources type can be used as part of your jobs and also to enable automatic pipeline triggers. You need to have **Contributor** or **Owner** permissions for ACR to use automatic pipeline triggers. For more information, see [Azure Container Registry roles and permissions](/azure/container-registry/container-registry-roles). +> [!NOTE] +> The `enabled: 'true'` syntax to enable container triggers for all image tags is different from the syntax for other resource triggers. Be sure to use the correct syntax for specific resources. -## [Schema](#tab/schema) +### Azure Container Registry resource type -```yaml -resources: # types: pipelines | repositories | containers | builds | packages - containers: - - container: string # identifier for the container resource - type: string # type of the registry like ACR, GCR etc. - azureSubscription: string # Azure subscription (ARM service connection) for container registry; - resourceGroup: string # resource group for your ACR - registry: string # registry for container images - repository: string # name of the container image repository in ACR - trigger: # Triggers aren't enabled by default and need to be set explicitly - enabled: boolean # set to 'true' to trigger on all image tags if 'tags' is unset. - tags: - include: [ string ] # image tags to consider the trigger events, optional; defaults to any new tag - exclude: [ string ] # image tags on discard the trigger events, optional; defaults to none -``` +To consume your Azure Container Registry images, you can use the first-class container resource type `acr`. You can use this resource type as part of your jobs and to enable automatic pipeline triggers. -> [!NOTE] -> The syntax that's used to enable container triggers for all image tags (`enabled: 'true'`) is different from the syntax that's used for other resource triggers. Pay close attention to use the correct syntax for a specific resource. +You need **Contributor** or **Owner** permissions for Azure Container Registry to use automatic pipeline triggers. For more information, see [Azure Container Registry roles and permissions](/azure/container-registry/container-registry-roles). -## [Example](#tab/example) +To use the `acr` resource type, you must specify the `azureSubscription`, `resourceGroup`, and `repository` values for your Azure container registry. For example: ```yaml resources: containers: - container: petStore - type: ACR - azureSubscription: ContosoARMConnection + type: acr + azureSubscription: ContosoConnection resourceGroup: ContosoGroup registry: petStoreRegistry repository: myPets @@ -521,41 +456,29 @@ resources: - production* ``` ---- -#### Container resource variables - -Once you define a container as a resource, container image metadata gets passed to the pipeline in the form of variables. Information like image, registry, and connection details are accessible across all the jobs to be used in your container deploy tasks. - -## [Schema](#tab/schema) +> [!NOTE] +> Trigger evaluation only occurs on the default branch. Make sure to set the correct default branch or merge the YAML file into the current default branch. For more information on how to change the pipeline default branch, visit [The pipeline default branch](/azure/devops/pipelines/process/pipeline-default-branch). -```yaml -resources.container..type -resources.container..registry -resources.container..repository -resources.container..tag -resources.container..digest -resources.container..URI -resources.container..location -``` +### Container resource variables -Location variable is only applicable for `ACR` type of container resources. +Once you define a container as a resource, container image metadata passes to the pipeline as variables. Information like image, registry, and connection details are accessible across all the jobs used in your container deployment tasks. -## [Example](#tab/example) +Container resource variables work with Docker and Azure Container Registry. You can't use container resource variables for local image containers. The `location` variable applies only to the `acr` type of container resources. -In this example, there's an [Azure Resource Manager service connection](../library/service-endpoints.md#common-service-connection-types) named `arm-connection`. For more information, see [Azure container registries, repositories, and images](/azure/container-registry/container-registry-concepts). +The following example has an [Azure Resource Manager service connection](../library/service-endpoints.md#common-service-connection-types) named `arm-connection`. For more information, see [Azure container registries, repositories, and images](/azure/container-registry/container-registry-concepts). ```yaml resources: containers: - - container: mycontainer # name of the container (Alias) - type: ACR # type of registry - azureSubscription: arm-connection # name of the ARM service connection - resourceGroup: rg-storage-eastus # Azure resource group with the container - registry: mycontainerregistry # Azure container registry name - repository: hello-world # name of the of container image collection + - container: mycontainer + type: ACR + azureSubscription: arm-connection + resourceGroup: rg-storage-eastus + registry: mycontainerregistry + repository: hello-world trigger: tags: - - latest # tag for the container image to use + - latest steps: - script: echo | @@ -569,37 +492,20 @@ steps: ``` ---- - ::: moniker range=">= azure-devops-2020" + +## Packages resource definition -## Define a `packages` resource - -You can consume NuGet and npm GitHub packages as a resource in YAML pipelines. - -When you're specifying `package` resources, set the package as NuGet or npm. You can also enable automated pipeline triggers when a new package version gets released. - -To use GitHub packages, use personal access token (PAT)-based authentication and create a GitHub service connection that uses PATs. +You can consume NuGet and npm GitHub packages as resources in YAML pipelines. To enable automated pipeline triggers when a new package version gets released, set the `trigger` property to `true`. -By default, packages aren't automatically downloaded into jobs. To download, use `getPackage`. +When you define `package` resources, specify the package \/\ in the `name` property, and set the package `type` as `NuGet` or `npm`. To use GitHub packages, use personal access token (PAT)-based authentication and create a GitHub service connection that uses the PAT. -## [Schema](#tab/schema) +For complete schema information, see the [resources.packages.package definition](/azure/devops/pipelines/yaml-schema/resources-packages-package). -```yaml -resources: - packages: - - package: myPackageAlias # alias for the package resource - type: Npm # type of the package NuGet/npm - connection: GitHubConnectionName # GitHub service connection with the PAT type - name: nugetTest/nodeapp # / - version: 1.0.1 # Version of the package to consume; Optional; Defaults to latest - trigger: true # To enable automated triggers (true/false); Optional; Defaults to no triggers -``` - -## [Example](#tab/example) +By default, packages aren't automatically downloaded into jobs. To download, use [getPackage](/azure/devops/pipelines/yaml-schema/steps-get-package). -In this example, there's a [GitHub service connection](../library/service-endpoints.md#common-service-connection-types) named `pat-contoso` to a GitHub npm package named `contoso`. For more information, see [GitHub packages](https://github.com/features/packages). +The following example has a [GitHub service connection](../library/service-endpoints.md#common-service-connection-types) named `pat-contoso` to a GitHub npm package named `contoso`. For more information, see [GitHub packages](https://github.com/features/packages). ```yaml resources: @@ -607,7 +513,7 @@ resources: - package: contoso type: npm connection: pat-contoso - name: yourname/contoso + name: myname/contoso version: 7.130.88 trigger: true @@ -615,56 +521,71 @@ pool: vmImage: 'ubuntu-latest' steps: -- getPackage: contoso +- getPackage: contoso ``` ---- - - -## Define a `webhooks` resource + +## Webhooks resource definition > [!NOTE] > Webhooks were released in Azure DevOps Server 2020.1. -With other resources (such as pipelines, containers, build, and packages) you can consume artifacts and enable automated triggers. However, you can't automate your deployment process based on other external events or services. The `webhooks` resource enables you to integrate your pipeline with any external service and automate the workflow. You can subscribe to any external events through its webhooks (GitHub, GitHub Enterprise, Nexus, Artifactory, and so on) and trigger your pipelines. +You can consume artifacts and enable automated triggers with pipeline, container, build, and package resources. However, you can't use these resources to automate your deployments based on external events or services. -Do the following steps to configure the webhook triggers. +The `webhooks` resource in YAML pipelines lets you integrate your pipelines with external services like GitHub, GitHub Enterprise, Nexus, and Artifactory to automate workflows. You can subscribe to any external events through webhooks and use the events to trigger your pipelines. -1. Set up a webhook on your external service. When you're creating your webhook, you need to provide the following info: +Webhooks automate your workflow based on any external webhook event that isn't supported by first-class resources like pipelines, builds, containers, or packages. Also, for on-premises services where Azure DevOps doesn't have visibility into the process, you can configure webhooks on the service and trigger your pipelines automatically. - - Request Url - - ``` - https://dev.azure.com//_apis/public/distributedtask/webhooks/?api-version=6.0-preview - ``` - - - Secret - Optional. If you need to secure your JSON payload, provide the **Secret** value. -2. Create a new "Incoming Webhook" service connection. This connection is a newly introduced Service Connection Type that allows you to define the following important information: - - **Webhook Name**: The name of the webhook should match webhook created in your external service. - - **HTTP Header** - The name of the HTTP header in the request that contains the payload's HMAC-SHA1 hash value for request verification. For example, for GitHub, the request header is "**X-Hub-Signature**". - - **Secret** - The secret is used to verify the payload's HMAC-SHA1 hash used for verification of the incoming request (optional). If you used a secret when creating your webhook, you must provide the same secret key. - - ![Incoming Webhook Service connection](media/incoming-webhook.png) +To subscribe to a webhook event, you define a webhook resource in your pipeline and point it to an incoming webhook service connection. You can also define more filters on the webhook resource, based on the JSON payload data, to customize the triggers for each pipeline. -3. A new resource type called `webhooks` is introduced in YAML pipelines. To subscribe to a webhook event, define a webhook resource in your pipeline and point it to the Incoming webhook service connection. You can also define more filters on the webhook resource, based on the JSON payload data, to customize the triggers for each pipeline. Consume the payload data in the form of variables in your jobs. +Whenever the incoming webhook service connection receives a webhook event, a new run triggers for all the pipelines subscribed to the webhook event. You can consume the JSON payload data in your jobs as variables by using the format `${{ parameters..}}`. -4. Whenever the Incoming Webhook service connection receives a webhook event, a new run gets triggered for all the pipelines subscribed to the webhook event. You can consume the JSON payload data in your jobs using the format `${{ parameters..}}` +For complete schema information, see the [resources.webhooks.webhook definition](/azure/devops/pipelines/yaml-schema/resources-webhooks-webhook). -## [Schema](#tab/schema) +The following example defines a webhook resource: -```yml +```yaml resources: webhooks: - - webhook: MyWebhookTriggerAlias ### Webhook alias - connection: IncomingWebhookConnection ### Incoming webhook service connection - filters: ### List of JSON parameters to filter; Parameters are AND'ed - - path: JSONParameterPath ### JSON path in the payload - value: JSONParameterExpectedValue ### Expected value in the path provided + - webhook: WebHook + connection: IncomingWH + +steps: +- script: echo ${{ parameters.WebHook.resource.message.title }} ``` -Webhooks automate your workflow based on any external webhook event that isn't supported by first class resources. Resources like pipelines, builds, containers, and packages. Also, for on-premise services where Azure DevOps doesn't have visibility into the process, you can configure webhooks on the service and to trigger your pipelines automatically. +### Webhook triggers + +To configure webhook triggers, you first set up a webhook on your external service, providing the following information: + +- **Request Url**: `https://dev.azure.com//_apis/public/distributedtask/webhooks/?api-version=6.0-preview` +- **Secret** (Optional): If you need to secure your JSON payload, provide a secret value. -## [Example](#tab/example) +Next, you create a new incoming webhook service connection. For this service connection type, you define the following information: + +- **WebHook Name**: Same as the webhook created in your external service. +- **Secret** (Optional): Used to verify the payload's HMAC-SHA1 hash for verification of the incoming request. If you used a secret when creating your webhook, you must provide the same secret. +- **Http Header**: The HTTP header in the request that contains the payload's HMAC-SHA1 hash value for request verification. For example, the GitHub request header is `X-Hub-Signature`. + +![Screenshot that shows the incoming webhook service connection.](media/incoming-webhook.png) + +To trigger your pipeline using a webhook, you make a `POST` request to `https://dev.azure.com//_apis/public/distributedtask/webhooks/?api-version=6.0-preview`. This endpoint is publicly available, and needs no authorization. The request should have a body like the following example: + +```json +{ + "resource": { + "message": { + "title": "Hello, world!", + "subtitle": "I'm using WebHooks!" + } + } +} +``` + +>[!NOTE] +>Accessing data from the webhook's request body can lead to incorrect YAML. For example, the pipeline step `- script: echo ${{ parameters.WebHook.resource.message }}` pulls in the entire JSON message, which generates invalid YAML. Any pipeline triggered via this webhook doesn't run, because the generated YAML became invalid. + +The following snippet shows another example that uses webhook filters. ```yml resources: @@ -681,127 +602,109 @@ steps: inputs: targetType: 'inline' script: | - Write-Host ${{ parameters.MyWebhookTrigger.repositoryName}} ### JSON payload data is available in the form of ${{ parameters..}} + Write-Host ${{ parameters.MyWebhookTrigger.repositoryName}} Write-Host ${{ parameters.MyWebhookTrigger.component.group}} ``` ---- - ::: moniker-end -## Manual version picker for resources in the create run dialogue - -When you manually trigger a CD YAML pipeline, we automatically evaluate the default version for the resources defined in the pipeline, based on the inputs provided. However, you can choose to pick a different version from resource version picker when you create a run. - -1. In the **Create run** pane, select **Resources**. You see a list of resources consumed in this pipeline. -1. Select a resource and pick a specific version from the list of versions available. Resource version picker is supported for pipeline, build, repository, container, and package resources. - - ![Pipeline Version Picker](media/pipeline-version-picker.png) +## Manual version picker for resources -For pipeline resources, you can see all the available runs across all branches. Search them based on the pipeline number or branch. And, pick a run that's successful, failed, or in-progress. This flexibility ensures that you can run your CD pipeline if you're sure it produced all the artifacts that you need. You don't need to wait for the CI run to complete or rerun because of an unrelated stage failure in the CI run. However, we only consider successfully completed CI runs when we evaluate the default version for scheduled triggers, or if you don't use manual version picker. +When you manually trigger a CD YAML pipeline, Azure Pipelines automatically evaluates the default versions for the resources defined in the pipeline, based on the inputs provided. However, Azure Pipelines considers only successfully completed CI runs when evaluating the default version for scheduled triggers, or if you don't manually choose a version. -For resources where you can't fetch available versions, like GitHub packages, we show a text box as part of version picker so you can provide the version for the run to pick. +You can use the resource version picker to manually choose a different version when you create a run. The resource version picker is supported for pipeline, build, repository, container, and package resources. -## Authorize a YAML pipeline +For pipeline resources, you can see all the available runs across all branches, search them based on the pipeline number or branch, and pick a run that's successful, failed, or in progress. This flexibility ensures that you can run your CD pipeline if you're sure a run produced all the artifacts you need. You don't need to wait for a CI run to complete, or rerun it because of an unrelated stage failure. -Resources must be authorized before they can be used. A resource owner controls the users and pipelines that can access that resource. The pipeline must be authorized to use the resource. See the following ways you can authorize a YAML pipeline. +To use the resource version picker, in the **Run pipeline** pane, select **Resources**, then select a resource and pick a specific version from the list of available versions. -* Go to the administration experience of the resource. For example, variable groups and secure files are managed in the **Library** page under **Pipelines**. Agent pools and service connections are managed in **Project settings**. Here you can authorize **all pipelines** to access that resource. This authorization is convenient if you don't have a need to restrict access to a resource - for example, test resources. +![Screenshot that shows the repository resource version picker.](media/repository-version-picker.png) -* When you create a pipeline for the first time, all the resources that are referenced in the YAML file get automatically authorized for use by the pipeline, if you're a member of the **User** role for that resource. So, resources that are referenced in the YAML file when you create a pipeline get automatically authorized. +For resources where you can't fetch available versions, like GitHub packages, the version picker provides a text field so you can enter the version for the run to pick. -* When you make changes to the YAML file and add resources, then the build fails with an error similar to the following error: `Could not find a with name . The does not exist or has not been authorized for use.` + +## Resource authorization in YAML pipelines - In this case, you see an option to authorize the resources on the failed build. If you're a member of the **User** role for the resource, you can select this option. Once the resources are authorized, you can start a new build. +Resources must be authorized before they can be used in pipelines. Resource owners control the users and pipelines that can access their resources. There are several ways to authorize a YAML pipeline to use resources. -* Verify that the [agent pool security roles](../../organizations/security/about-security-roles.md) for your project are correct. +- Use the resource administration experience to authorize **all pipelines** to access the resource. For example, variable groups and secure files are managed in the **Library** page under **Pipelines**, and agent pools and service connections are managed in **Project settings**. This authorization is convenient if you don't need to restrict access to resources, such as for test resources. -## Set approval checks for resources +- When you create a pipeline, all the resources referenced in the YAML file are automatically authorized for use by the pipeline if you have the **User** role for those resources. -You can manually control when a resource runs with approval checks and templates. With the [required template approval check](approvals.md#required-template), you can require any pipeline using a resource or environment also extends from a specific YAML template. -Setting a required template approval enhances security. Make sure your resource only gets used under specific conditions with a template. Learn more about how to [enhance pipeline security](../security/templates.md#set-required-templates) with templates and resources. +- If you add a resource to a YAML file and the build fails with an error like `Could not find a with name . The does not exist or has not been authorized for use.`, you see an option to authorize the resources on the failed build. -## Traceability - -We provide full traceability for any resource consumed at a pipeline- or deployment job-level. + If you're a member of the **User** role for the resource, you can select this option and authorize the resource on the failed build. Once the resource is authorized, you can start a new build. -### Pipeline traceability +- Verify that the [agent pool security roles](../../organizations/security/about-security-roles.md) for your project are correct. -For every pipeline run, we show the following information. +## Approval checks for resources -* The resource that has triggered the pipeline, if it's triggered by a resource. +You can use approval checks and templates to manually control when a resource runs. With the [required template approval check](approvals.md#required-template), you can require that any pipeline using a resource or environment extends from a specific YAML template. - ![Resource trigger in a pipeline](media/runs-resource-trigger.png) +Setting a required template approval ensures that your resource is used only under specific conditions, and enhances security. To learn more about how to [enhance pipeline security](../security/templates.md#set-required-templates) with templates, see [Use templates for security](../security/templates.md). -* Version of the resource and the artifacts consumed. +## Traceability - ![Consumed artifacts in pipeline run](media/runs-consumed-artifacts.png) +Azure Pipelines provides full traceability for any resource consumed at a pipeline or deployment job level. -* Commits associated with each resource. +### Pipeline traceability - ![Commits in pipeline run](media/runs-commits.png) +Azure Pipelines shows the following information for every pipeline run: -* Work items associated with each resource. +- If a resource triggered the pipeline, the resource that triggered the pipeline. +- The resource version and the artifacts consumed. +- Commits associated with each resource. +- Work items associated with each resource. ### Environment traceability -Whenever a pipeline deploys to an environment, you can see a list of resources that are consumed. The following view includes resources consumed as part of the deployment jobs and their associated commits and work items. +Whenever a pipeline deploys to an environment, you can see a list of resources that are consumed. The view includes resources consumed as part of the deployment jobs and their associated commits and work items. -![Commits in environment](media/environments-commits.png) +![Screenshot that shows commits in an environment.](media/environments-commits.png) -### Show associated CD pipelines information in CI pipelines +### Associated CD pipelines information in CI pipelines -To provide end-to-end traceability, you can track which CD pipelines are consuming a giving CI pipeline. You can see the list of CD YAML pipelines runs where a CI pipeline run is consumed through the `pipeline` resource. If other pipelines consume your CI pipeline, you see an "Associated pipelines" tab in the run view. Here you can find all the pipeline runs that consume your pipeline and artifacts from it. +To provide end-to-end traceability, you can track which CD pipelines consume a specific CI pipeline through the `pipelines` resource. If other pipelines consume your CI pipeline, you see an **Associated pipelines** tab in the **Run** view. The view shows all the CD YAML pipeline runs that consumed your CI pipeline and the artifacts from it. -![CD pipelines information in CI pipeline](media/cdinfo-in-ci-pipelines.png) +![Screenshot that shows CD pipelines information in a CI pipeline.](media/cdinfo-in-ci-pipelines.png) -### YAML resource trigger issues support and traceability +### Resource trigger issues -It can be confusing when pipeline triggers fail to execute. We've added a new menu item in the pipeline definition page called **Trigger Issues**, where you can learn why triggers aren't executing. To access this page, open your pipeline history. **Trigger Issues** is only available for non-repository resources. +Resource triggers can fail to execute because: -:::image type="content" source="media/trigger-menu.png" alt-text="Select Trigger Issues from the navigation."::: +- The source of the provided service connection is invalid, there are syntax errors in the trigger, or the trigger isn't configured. +- Trigger conditions aren't matched. -Resource triggers can fail to execute for the following reasons. +To see why pipeline triggers failed to execute, select the **Trigger issues** menu item on the pipeline definition page. **Trigger issues** is available only for nonrepository resources. -* If the source of the service connection that's provided is invalid, or if there are any syntax errors in the trigger, the trigger isn't configured, resulting in an error. -* If trigger conditions aren't matched, the trigger won't execute. A warning is surfaced so you can understand why the conditions weren't matched. +![Screenshot that shows Trigger issues on the main pipeline page.](media/trigger-menu.png) - ![Trigger issues supportability](media/trigger-supportability.png) - -## Next steps +On the **Trigger issues** page, the error and warning messages describe why the trigger failed. -> [!div class="nextstepaction"] -> [Add and use variable groups](../library/variable-groups.md) +![Screenshot that shows Trigger issues supportability.](media/trigger-supportability.png) ## FAQ -### Why should I use pipelines `resources` instead of the `download` shortcut? - -Using a `pipelines` resource is a way to consume artifacts from a CI pipeline and also configure automated triggers. A resource gives you full visibility into the process by displaying the version consumed, artifacts, commits, and work items. When you define a pipeline resource, the associated artifacts get automatically downloaded in deployment jobs. +### When should I use pipelines resources, the download shortcut, or the Download Pipeline Artifacts task? -You can choose to download the artifacts in build jobs or to override the download behavior in deployment jobs with `download`. The `download` task internally uses the [Download Pipeline Artifacts task](/azure/devops/pipelines/tasks/reference/download-pipeline-artifact-v2). +Using a `pipelines` resource is a way to consume artifacts from a CI pipeline and also configure automated triggers. A resource gives you full visibility into the process by displaying the version consumed, artifacts, commits, and work items. When you define a pipeline resource, the associated artifacts are automatically downloaded in deployment jobs. -### Why should I use `resources` instead of the Download Pipeline Artifacts task? +You can use the `download` shortcut to download the artifacts in build jobs or to override the download behavior in deployment jobs. For more information, see the [steps.download definition](/azure/devops/pipelines/yaml-schema/steps-download). -When you use the [Download Pipeline Artifacts task](/azure/devops/pipelines/tasks/reference/download-pipeline-artifact-v2) directly, you miss traceability and triggers. Sometimes it makes sense to use the Download Pipeline Artifacts task directly. For example, you might have a script task stored in a different template and the script task requires artifacts from a build to be downloaded. Or, you may not know if someone using a template wants to add a pipeline resource. To avoid dependencies, you can use the Download Pipeline Artifacts task to pass all the build information to a task. +The [Download Pipeline Artifacts task](/azure/devops/pipelines/tasks/reference/download-pipeline-artifact-v2) doesn't provide traceability or triggers, but sometimes it makes sense to use this task directly. For example, you might have a script task stored in a different template that requires artifacts from a build to be downloaded. Or, you might not want to add a pipeline resource to a template. To avoid dependencies, you can use the Download Pipeline Artifacts task to pass all the build information to a task. ### How can I trigger a pipeline run when my Docker Hub image gets updated? -You'll need to set up a [classic release pipeline](../release/index.md) because the containers resource trigger is not available for Docker Hub for YAML pipelines. +The container resource trigger isn't available for Docker Hub for YAML pipelines, so you need to set up a [classic release pipeline](../release/index.md). 1. Create a new Docker Hub [service connection](../library/service-endpoints.md). -1. Create a classic release pipeline and add a Docker Hub artifact. Set your service connection. Select the namespace, repository, version, and source alias. - - :::image type="content" source="media/docker-artifact-release-pipeline.png" alt-text="Add a Docker Hub artifact. "::: - -1. Select the trigger and toggle the continuous deployment trigger to **Enable**. You'll create a release every time a Docker push occurs to the selected repository. -1. Create a new stage and job. Add two tasks, Docker login and Bash: - * The Docker task has the `login` action and logs you into Docker Hub. - * The Bash task runs `docker pull /[:]`. Replace `hub-user`, `repo-name`, and `tag` with your values. - - :::image type="content" source="media/docker-hub-tasks-classic-pipeline.png" alt-text="Add Docker login and Bash tasks. "::: +1. Create a classic release pipeline and add a Docker Hub artifact. Set your service connection and select the namespace, repository, version, and source alias. +1. Select the trigger and toggle the continuous deployment trigger to **Enable**. Every Docker push that occurs to the selected repository creates a release. +1. Create a new stage and job. Add two tasks, Docker login and Bash. + - The Docker task has the `login` action and signs you in to Docker Hub. + - The Bash task runs `docker pull /[:]`. -### How can I validate and troubleshoot webhooks? +### How can I validate and troubleshoot my webhook? 1. Create a service connection. @@ -814,24 +717,25 @@ You'll need to set up a [classic release pipeline](../release/index.md) because connection: MyServiceConnection ``` -1. Run your pipeline. When you run your pipeline, the webhook will be created in Azure as a distributed task for your organization. +1. Run your pipeline. The webhook is created in Azure as a distributed task for your organization. +1. Perform a `POST` API call with valid JSON in the body to `https://dev.azure.com//_apis/public/distributedtask/webhooks/?api-version=`. If you receive a 200 status code response, your webhook is ready for consumption by your pipeline. -1. Perform a `POST` API call with valid JSON in the body to -`https://dev.azure.com/{organization}/_apis/public/distributedtask/webhooks/{webhook-name}?api-version={apiversion}`. If you receive a 200 status code response, your webhook is ready for consumption by your pipeline. If you receive a 500 status code response with the error `Cannot find webhook for the given webHookId ...`, your code may be in a branch that is not your default branch. +If you receive a 500 status code response with the error `Cannot find webhook for the given webHookId ...`, your code might be in a branch that's not your default branch. To address this issue: - 1. Open your pipeline. - 1. Select **Edit**. - 1. Select the more actions menu :::image type="content" source="../../media/icons/more-actions.png" alt-text="Select more actions menu":::. - 1. Select **Triggers** > **YAML** > **Get Sources**. - 1. Go to **Default branch for manual and scheduled builds** to update your feature branch. - 1. Select **Save & queue**. - 1. After this pipeline runs successfully, perform a `POST` API call with valid JSON in the body to -`https://dev.azure.com/{organization}/_apis/public/distributedtask/webhooks/{webhook-name}?api-version={apiversion}`. You should now receive a 200 status code response. +1. Select **Edit** on your pipeline page. +1. From the **More actions** menu, select **Triggers**. +1. Select the **YAML** tab and then select **Get sources**. +1. Under **Default branch for manual and scheduled builds**, update your feature branch. +1. Select **Save & queue**. +1. After this pipeline runs successfully, perform a `POST` API call with valid JSON in the body to +`https://dev.azure.com//_apis/public/distributedtask/webhooks/?api-version=`. You should now receive a 200 status code response. -## Related articles +## Related content -* [Define variables](variables.md) -* [Create and target an environment](environments.md) -* [Use YAML pipeline editor](../get-started/yaml-pipeline-editor.md) -* [YAML schema reference](/azure/devops/pipelines/yaml-schema) +- [About resources for Azure Pipelines](about-resources.md) +- [Define variables](variables.md) +- [Add and use variable groups](../library/variable-groups.md) +- [Create and target an environment](environments.md) +- [Use YAML pipeline editor](../get-started/yaml-pipeline-editor.md) +- [YAML schema reference](/azure/devops/pipelines/yaml-schema) diff --git a/docs/pipelines/process/run-number.md b/docs/pipelines/process/run-number.md index b834ec1ffd5..d75e7dfed43 100644 --- a/docs/pipelines/process/run-number.md +++ b/docs/pipelines/process/run-number.md @@ -1,129 +1,117 @@ --- -title: Run (build) number -ms.custom: seodec18 -description: Customize pipeline run number in Azure Pipelines or Azure DevOps Server. +title: Run and build numbers +description: Learn about Azure Pipelines run numbers and build numbers and how you can configure them in your pipelines. ms.topic: conceptual ms.assetid: 7C469647-117D-4867-B094-8BC811C0003E -ms.date: 03/21/2023 -monikerRange: '>= tfs-2018' +ms.date: 07/01/2024 +monikerRange: "<=azure-devops" --- -# Configure run or build numbers +# Run and build numbers [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -[!INCLUDE [temp](../includes/concept-rename-note.md)] +This article explains how Azure Pipelines build numbers and run numbers are constructed, and how you can customize them in your pipelines. -You can customize how your pipeline runs are numbered. The default value for run number is `$(Date:yyyyMMdd).$(Rev:r)`. +The run number is used to identify a specific execution of a pipeline or build. The build number is synonymous with the run number. -In Azure DevOps `$(Rev:r)` is a special variable format that only works in the build number field. When a build is completed, if nothing else in the build number has changed, the `Rev` integer value increases by one. +If you don't specify a build name in YAML pipelines, or you leave the **Name** field blank in Classic pipelines, your run gets a unique integer as its name. You can give runs more useful names that are meaningful to your team. You can use a combination of tokens, variables, and underscore characters in build names. -`$(Rev:r)` resets when you change part of the build number. For example, if you've configured your build number format as `$(BuildDefinitionName)_$(Date:yyyyMMdd)$(Rev:r)`, then the build number will reset when the date changes the next day. If your build number is `MyBuild_20230621.1`, the next build number that day is `MyBuild_20230621.2`. The next day, the build number is `MyBuild_20230622.1`. - -If your build number format is `1.0.$(Rev:r)`, then the build number resets to `1.0.1` when you change part of the number. For example, if your last build number was `1.0.3`, and you change the build number to `1.1.$(Rev:r)` to indicate a version change, the next build number is `1.1.1`. +::: moniker range=">=azure-devops-2020" +In YAML pipelines, the build name property is called `name` and must be at the root level of a pipeline. Items specified at the root level of a YAML file are [pipeline](/azure/devops/pipelines/yaml-schema/pipeline) properties. +>[!NOTE] +>The `name` property doesn't work in template files. -#### [YAML](#tab/yaml/) -::: moniker range=">=azure-devops-2020" - -In YAML, this property is called `name` and must be at the root level of a pipeline. -If not specified, your run is given a unique integer as its name. -You can give runs much more useful names that are meaningful to your team. -You can use a combination of tokens, variables, and underscore characters. -The `name` property doesn't work in template files. +The following example code outputs a customized build number like **project_def_master_202408281**. ```yaml name: $(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd)$(Rev:r) steps: - - script: echo '$(Build.BuildNumber)' # outputs customized build number like project_def_master_20200828.1 + - script: echo '$(Build.BuildNumber)' ``` ::: moniker-end -::: moniker range="< azure-devops" -YAML builds aren't yet available on TFS. -::: moniker-end - -#### [Classic](#tab/classic/) -If you leave this field blank, your completed build is given a unique integer as its name. But you can give completed builds much more useful names that are meaningful to your team. You can use a combination of tokens, variables, and underscore characters. - -* * * - -## Example - -At the time, a run is started: +## Run number -* Project name: Fabrikam +The default value for a run number in Azure Pipelines is `$(Date:yyyyMMdd).$(Rev:r)`. `$(Rev:r)` is a special variable format that only works in the build number field. When a build completes, if nothing else in the build number changed, the `Rev` integer value increases by one. -* Pipeline name: CIBuild +`$(Rev:r)` resets to `1` when any other part of the build number changes. For example, if you configure your build number format as `$(Build.DefinitionName)_$(Date:yyyyMMdd).$(Rev:r)`, the build number resets when the date changes. -* Branch: main +If the previous build number was `MyBuild_20230621.1`, the next build number that day is `MyBuild_20230621.2`. The first build number the next day is `MyBuild_20230622.1`. -* Build ID/Run ID: 752 +`$(Rev:r)` also resets to `1` if you change the build number to indicate a version change. For example, if your build format is `1.0.$(Rev:r)` and your last build number was `1.0.3`, if you change the build number to `1.1.$(Rev:r)`, the next build number is `1.1.1`. -* Date: May 5, 2019. +## Example -* Time: 9:07:03 PM. +Consider the following data for a build run: -* One run completed earlier today. +- Project name: Fabrikam +- Pipeline name: CIBuild +- Branch: main +- Build ID/Run ID: 752 +- Date: May 6, 2024 +- Time: 9:07:03 PM +- One run completed earlier today. -If you specify this build number format: +If you specify the following build number format, the second run on May 6, 2024 is named **Fabrikam_CIBuild_main_20240506.2**. +```yaml +$(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd).$(Rev:r) ``` -$(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd)$(Rev:.r) -``` - -Then the second run on this day would be named: **Fabrikam\_CIBuild_master\_20190505.2** - ## Tokens -The following table shows how each token is resolved based on the previous example. You can use these tokens only to define a run number; they don't work anywhere else in your pipeline. - -| Token | Example replacement value | -| ----- | ------------------------- | -| `$(Build.DefinitionName)` | CIBuild

      Note: The pipeline name must not contain invalid or whitespace characters.| -| `$(Build.BuildId)` | 752

      $(Build.BuildId) is an internal immutable ID that is also referred to as the Run ID. It's unique across the organization.| -| `$(DayOfMonth)` | 5 | -| `$(DayOfYear)` | 217 | -| `$(Hours)` | 21 | -| `$(Minutes)` | 7 | -| `$(Month)` | 8 | -| `$(Rev:r)` | 2 (The third run is 3, and so on.)

      Use **$(Rev:r)** to ensure that every completed build has a unique name. When a build starts, if nothing else in the build number has changed, the Rev integer value is incremented by one.

      If you want to show prefix zeros in the number, you can add more **'r'** characters. For example, specify **$(Rev:rr)** if you want the Rev number to begin with 01, 02, and so on. If you use a zero-padded Rev as part of a version numbering scheme, note that some pipeline tasks or popular tools, like NuGet packages, remove the leading zeros, which cause a version number mismatch in the artifacts that are produced. | -| `$(Date:yyyyMMdd)` | 20090824

      You can specify other date formats such as **$(Date:MMddyy)** | -| `$(Seconds)` | 3 | -| `$(SourceBranchName)` | main | -| `$(TeamProject)` | Fabrikam | -| `$(Year:yy)` | 09 | -| `$(Year:yyyy)` | 2009 | +The following table shows how each token resolves, based on the previous example. You can use these tokens only to define run numbers. They don't work anywhere else in a pipeline. + +| Token | Example value | Notes | +| ----- | -------------- | ----------- | +| `$(Build.DefinitionName)` | CIBuild | The pipeline name can't contain invalid or whitespace characters.| +| `$(Build.BuildId)` | 752 | `$(Build.BuildId)` is an internal, immutable ID, also called the Run ID, that is unique across the Azure DevOps organization.| +| `$(DayOfMonth)` | 6 || +| `$(DayOfYear)` | 126 || +| `$(Hours)` | 21 || +| `$(Minutes)` | 7 || +| `$(Month)` | 5 || +| `$(Rev:r)` | 2 | The third daily run is `3`, and so on. Use `$(Rev:r)` to ensure that every completed build has a unique name. | +| `$(Date:yyyyMMdd)` | 20240506 | You can specify other date formats such as `$(Date:MMddyy)`. | +| `$(Seconds)` | 3 || +| `$(SourceBranchName)` | main || +| `$(TeamProject)` | Fabrikam || +| `$(Year:yy)` | 24 || +| `$(Year:yyyy)` | 2024 || + +>[!IMPORTANT] +>If you want to show prefix zeros in the run number, you can add more `r` characters to the `Rev` token. For example, specify `$(Rev:rr)` if you want the `Rev` number to begin with `01`, `02`, and so on. +> +>If you use a zero-padded `Rev` as part of a version numbering scheme, be aware that some pipeline tasks or popular tools, like NuGet packages, remove the leading zeros. This behavior causes a version number mismatch in the artifacts that are produced. +## Expressions +If you use an expression to set the build number, you can't use some tokens, because their values aren't set at the time expressions are evaluated. These tokens include `$(Build.BuildId)`, `$(Build.BuildURL)`, and `$(Build.BuildNumber)`. ## Variables -You can also use user-defined and predefined variables that have a scope of "All" in your number. For example, if you've defined `My.Variable`, you could specify the following number format: +You can use user-defined and predefined variables in your build number. For example, if you define `My.Variable`, you can specify the following number format: -``` +```yaml $(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.RequestedFor)_$(Build.BuildId)_$(My.Variable) ``` -The first four variables are predefined. `My.Variable` is defined by you on the [variables tab](variables.md). - -## Expressions - -If you use an expression to set the build number, you can't use some tokens because their values aren't set at the time expressions are evaluated. These tokens include `$(Build.BuildId)`, `$(Build.BuildURL)`, and `$(Build.BuildNumber)`. +In the preceding example, the first four variables are predefined. For information on how to define user variables, see [Set variables in pipelines](variables.md#set-variables-in-pipeline). ## FAQ -### How large can a run number be and what characters can I use? +### How large can a run number be, and what characters can I use? -Runs may be up to 255 characters. Characters that aren't allowed include `"`, `/`, `:`, `<`, `>`, `'`, `|`, `?`, `@`, and `*`. You can't end with a `.`. +Run numbers can be up to 255 characters. You can't use the characters `"`, `/`, `\`, `:`, `<`, `>`, `'`, `|`, `?`, `@`, or `*`, and you can't end the number with `.`. -### In what time zone are the build number time values expressed? +### What time zone are the build number time values expressed in? ::: moniker range="azure-devops" @@ -131,55 +119,56 @@ The time zone is UTC. ::: moniker-end -::: moniker range=">= tfs-2018 < azure-devops" +::: moniker range=" +## Related content - +[Define variables](variables.md) diff --git a/docs/pipelines/process/run-stages.md b/docs/pipelines/process/run-stages.md new file mode 100644 index 00000000000..db6e9672d94 --- /dev/null +++ b/docs/pipelines/process/run-stages.md @@ -0,0 +1,327 @@ +--- +title: Build a YAML pipeline with stages +description: Create and run a complex YAML pipeline with multiple stages, conditions, validations, triggers, and rollback options. +ms.custom: peer-review-program +ms.topic: how-to +ms.date: 02/21/2025 +monikerRange: 'azure-devops' +ai-usage: ai-assisted + +#customer intent: As a developer, I want to design a sample pipeline with stages so that I can see how to use conditions, validation, triggers, etc.. + +--- + +# Build a YAML pipeline with stages + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +With multiple stages, you can isolate different parts of your pipeline, improve quality control and security, have better visibility into the pipeline's progress, and mitigate risk. + +In this article, learn how to create and run a more complex YAML pipeline with multiple stages and conditions. The example pipeline includes build, test, and deploy stages and also has optional stages for alternate deployments and rollbacks. The rollback stage lets you quickly revert to a stable version if something goes wrong, enhancing reliability and stability. + +This code works for most scenarios but doesn't include language or platform-specific requirements. As a next step, customize the pipeline for your specific implementation needs. + +To learn how to build a Classic pipeline with stages, see [Deploy to different stages from multiple branches using Classic release pipelines](../release/deploy-multiple-branches.md). + +## Prerequisites + +| **Product** | **Requirements** | +|---|---| +| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).
      - An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can request a free tier.
      - Basic knowledge of YAML and Azure Pipelines. For more information, see [Create your first pipeline](../create-first-pipeline.md).
      - **Permissions:**
           To create a pipeline, users need to be in the **Contributors** group and the group needs to have *Create build pipeline* permission set to Allow. Members of the [Build Administrators and Project Administrators groups](../../organizations/security/permissions.md) can also manage pipelines. +| **GitHub** | - A [GitHub](https://github.com) account.
      - A [GitHub service connection](../library/service-endpoints.md) to authorize Azure Pipelines.| +| **Azure** | An [Azure subscription](https://azure.microsoft.com/free/). | + + +## 1. Create a starter pipeline + +1. In your Azure DevOps project, select **Pipelines** > **Create Pipeline**, and then select **GitHub** as the location of your source code. +1. On the **Select a repository** screen, select your repository. +1. On the **Configure your pipeline** screen, select **Starter pipeline**. +1. Save your pipeline. + +## 2. Add the build stage + +The starter pipeline you added in the previous stage was a placeholder. Remove the starter pipeline code and add in a new YAML pipeline with a Build stage. + +1. Remove all of the code in your pipeline. +1. Replace the code with the following YAML that includes a `Build` stage. + + ```yaml + trigger: + - main + + pool: + vmImage: 'ubuntu-latest' + + stages: + - stage: Build + displayName: 'Build Stage' + jobs: + - job: BuildJob + displayName: 'Build Job' + steps: + - script: | + echo "Restoring project dependencies..." + displayName: 'Restore dependencies' + - script: | + echo "Running unit tests..." + displayName: 'Run unit tests' + ``` + +In this `Build` stage and throughout the sample pipeline, there are placeholder script tasks. When you build a working pipeline, replace the placeholder commands like `Restoring project dependencies...` with actual code. + +In this sample, you're restoring dependencies and running unit tests to make sure the code is ready for testing and deployment. If your application needs to compile source code, that will also happen in the `Build` stage. + +## 3. Add the test stage + +The `Test` stage runs tests on the project and publishes the test results to Azure DevOps. To learn more about publishing test results, see the [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2). + +The `Test` stage only runs if the `Build` stage completes successfully and the stage can't be skipped. + +Add the `Test` stage after the `Build` stage in your pipeline. + +```yaml +- stage: Test + displayName: 'Test Stage' + dependsOn: Build + isSkippable: false + jobs: + - job: TestJob + displayName: 'Test Job' + steps: + - script: | + echo "Running unit tests..." + displayName: 'Run unit tests' +``` + +The Test stage includes an attribute that sets `isSkippable` to `false`. When you set `isSkippable` to `false`, a stage can't be skipped. The option to skip the stage is also disabled in the Azure DevOps UI. + +:::image type="content" source="media/stages/is-skippable-stage-false.png" alt-text="Screenshot of stage that can't be skipped."::: + +## 4. Deploy to staging + +Add the `DeployToStaging` stage after the `Test` stage in your pipeline. + +The `DeployToStaging` stage depends on the `Test` stage to run. There are two different jobs in the `DeployToStaging` stage - `DeployStagingJob` and `DeployStagingJobWithValidation`. The `DeployStagingJob` should contain the code to deploy your staging job to staging resources like a staging server. + +The `DeployStagingJobWithValidation` job contains all of the validation that goes with your staging deployment. The `DeployStagingJobWithValidation` job requires manual approval. The [manual validation task](/azure/devops/pipelines/tasks/reference/manual-validation-v1) pauses the pipeline run and waits for a manual interaction. A user needs to validate the stage before the run proceeds. Having a manual approval in your pipeline adds another level of security, helps mitigate risks, and makes sure that all changes get reviewed by the appropriate stakeholders. + +The pool for the manual approval is `server`. Manual validations only run on a server pool. + +```yaml +- stage: DeployToStaging + displayName: 'Deploy to Staging' + dependsOn: Test + jobs: + - job: DeployStagingJob + displayName: 'Deploy to Staging Job' + pool: + vmImage: 'ubuntu-latest' + steps: + - script: | + echo "Build staging job..." + displayName: 'Build and deploy to staging' + + - job: DeployStagingJobWithValidation + pool: server + timeoutInMinutes: 4320 # job times out in 3 days + displayName: 'Deploy to Staging Job' + steps: + - task: ManualValidation@1 + timeoutInMinutes: 1440 # task times out in 1 day + inputs: + notifyUsers: user@example.com + instructions: 'Please validate the stage configuration and resume' + onTimeout: 'resume' +``` + +## 5. Deploy to production + +Add the `DeployToProduction` stage after the `DeployToStaging` stage in your pipeline. + +In the `DeployToProduction` stage, the application deploys to production, but only if the `DeployToStaging` stage succeeds and the source branch is either `main` or `release`. + +There are two different jobs in the `DeployToProduction` stage - `DeployProductionJob` and `waitForValidation`. + +The [manual validation task](/azure/devops/pipelines/tasks/reference/manual-validation-v1) in `waitForValidation` adds a second human validation step for security and quality control. We also used a manual validation task in the `DeployToStaging` stage. + +```yaml +- stage: DeployToProduction + displayName: 'Deploy to Production' + dependsOn: DeployToStaging + lockBehavior: sequential + condition: and(succeeded(), in(variables['Build.SourceBranch'], 'refs/heads/main', 'refs/heads/release')) + jobs: + - job: DeployProductionJob + displayName: 'Deploy to Production Job' + steps: + - script: | + echo "Deploying to production..." + # Add your deployment commands here + displayName: 'Run deployment commands' + - job: waitForValidation + displayName: Wait for external validation + pool: server + timeoutInMinutes: 4320 # job times out in 3 days + steps: + - task: ManualValidation@1 + timeoutInMinutes: 1440 # task times out in 1 day + inputs: + notifyUsers: user@example.com + instructions: 'Please validate the build configuration and resume' + onTimeout: 'resume' +``` + +## 6. Add optional alternate production and rollback stages + +You can optionally add two stages `DeployToAlternateProduction` and `Rollback` after the `DeployToProduction` stage. + + `DeployToAlternateProduction` and `Rollback` are manually queued. The `DeployToAlternateProduction` stage lets you have a backup production environment ready in case your primary environment fails. An environment can be an [Azure DevOps Environment](environments.md) or another location like a different cloud provider. This enhances the overall reliability and availability of your application. You might also want to have an alternate deployment environment for disaster recovery or testing and validation. For more complicated deployment strategies, see [Deployment jobs](deployment-jobs.md) and [Add stages, dependencies, and conditions](stages.md). + +The `Rollback` stage provides a safety net to revert your application to a previously stable state if something goes wrong during or after a deployment. This could be because of a deployment failure, bug, compliance requirement, disaster recovery, or other issue. A rollback stage is essential for maintaining the stability and reliability of your application. + +```yaml +- stage: DeployToAlternateProduction + displayName: 'Deploy to Alternate Production' + condition: succeeded() + trigger: manual + jobs: + - job: DeployAlternateProductionJob + displayName: 'Deploy to Alternate Production Job' + steps: + - script: | + echo "Deploying to alternate production..." + # Add your deployment commands here + displayName: 'Run deployment commands' + +- stage: Rollback + displayName: 'Rollback Stage' + trigger: manual + jobs: + - job: RollbackJob + displayName: 'Rollback Job' + steps: + - script: | + echo "Rolling back the deployment..." + # Add your rollback commands here + displayName: 'Run rollback commands' +``` + +## View the entire YAML pipeline + +Here's the entire pipeline with all of the referenced stages. + +```yaml +trigger: +- main + +pool: + vmImage: 'ubuntu-latest' + +stages: +- stage: Build + displayName: 'Build Stage' + jobs: + - job: BuildJob + displayName: 'Build Job' + steps: + - script: | + echo "Restoring project dependencies..." + displayName: 'Restore dependencies' + - script: | + echo "Running unit tests..." + displayName: 'Run unit tests' + +- stage: Test + displayName: 'Test Stage' + dependsOn: Build + isSkippable: false + jobs: + - job: TestJob + displayName: 'Test Job' + steps: + - script: | + echo "Running unit tests..." + displayName: 'Run unit tests' + + +- stage: DeployToStaging + displayName: 'Deploy to Staging' + dependsOn: Test + jobs: + - job: DeployStagingJob + displayName: 'Deploy to Staging Job' + pool: + vmImage: 'ubuntu-latest' + steps: + - script: | + echo "Build staging job..." + displayName: 'Build and deploy to staging' + + - job: DeployStagingJobWithValidation + pool: server + timeoutInMinutes: 4320 # job times out in 3 days + displayName: 'Deploy to Staging Job' + steps: + - task: ManualValidation@1 + timeoutInMinutes: 1440 # task times out in 1 day + inputs: + notifyUsers: user@example.com + instructions: 'Please validate the stage configuration and resume' + onTimeout: 'resume' + +- stage: DeployToProduction + displayName: 'Deploy to Production' + dependsOn: DeployToStaging + lockBehavior: sequential + condition: and(succeeded(), in(variables['Build.SourceBranch'], 'refs/heads/main', 'refs/heads/release')) + jobs: + - job: DeployProductionJob + displayName: 'Deploy to Production Job' + steps: + - script: | + echo "Deploying to production..." + # Add your deployment commands here + displayName: 'Run deployment commands' + - job: waitForValidation + displayName: Wait for external validation + pool: server + timeoutInMinutes: 4320 # job times out in 3 days + steps: + - task: ManualValidation@1 + timeoutInMinutes: 1440 # task times out in 1 day + inputs: + notifyUsers: user@example.com + instructions: 'Please validate the build configuration and resume' + onTimeout: 'resume' + +- stage: DeployToAlternateProduction + displayName: 'Deploy to Alternate Production' + condition: succeeded() + trigger: manual + jobs: + - job: DeployAlternateProductionJob + displayName: 'Deploy to Alternate Production Job' + steps: + - script: | + echo "Deploying to alternate production..." + # Add your deployment commands here + displayName: 'Run deployment commands' + +- stage: Rollback + displayName: 'Rollback Stage' + trigger: manual + jobs: + - job: RollbackJob + displayName: 'Rollback Job' + steps: + - script: | + echo "Rolling back the deployment..." + # Add your rollback commands here + displayName: 'Run rollback commands' +``` + +## Next steps + +> [!div class="nextstepaction"] +> [Add stages, dependencies, & conditions](stages.md) diff --git a/docs/pipelines/process/runs.md b/docs/pipelines/process/runs.md index 1e54a145fce..aaffc10ef7b 100644 --- a/docs/pipelines/process/runs.md +++ b/docs/pipelines/process/runs.md @@ -1,131 +1,114 @@ --- -title: Pipeline run sequence -description: Learn how Azure Pipelines runs your jobs, tasks, and scripts +title: Pipeline runs +description: Learn how Azure Pipelines runs jobs, tasks, and scripts. ms.topic: conceptual ms.custom: devx-track-azurecli ms.assetid: 0d207cb2-fcef-49f8-b2bf-ddb4fcf5c47a -ms.date: 01/04/2023 -monikerRange: '>= azure-devops-2019' +ms.date: 07/12/2024 +monikerRange: "<=azure-devops" --- -# Pipeline run sequence +# Pipeline runs [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Runs represent one execution of a pipeline. During a run, the pipeline is processed, and agents process one or more jobs. A pipeline run includes [jobs, steps, and tasks](../get-started/key-pipelines-concepts.md). Runs power both continuous integration (CI) and continuous delivery (CD) pipelines. +This article explains the sequence of activities in Azure Pipelines pipeline runs. A run represents one execution of a pipeline. Both continuous integration (CI) and continuous delivery (CD) pipelines consist of runs. During a run, Azure Pipelines processes the pipeline, and [agents](../agents/agents.md) process one or more [jobs, steps, and tasks](../get-started/key-pipelines-concepts.md). -![Pipeline overview](media/run-overview.svg) +![Diagram showing a pipeline overview.](media/run-overview.png) -When you run a pipeline, many things happen under the covers. -While you often won't need to know about them, occasionally it's useful to have the big picture. -At a high level, Azure Pipelines will: -- [Process the pipeline](#process-the-pipeline) -- [Request one or more agents to run jobs](#request-an-agent) -- Hand off jobs to agents and collect the results +For each run, Azure Pipelines: +- Processes the pipeline. +- Requests one or more agents to run jobs. +- Hands off jobs to agents and collects the results. -On the agent side, for each job, an agent will: -- [Get ready for the job](#prepare-to-run-a-job) -- [Run each step in the job](#run-each-step) -- [Report results to Azure Pipelines](#report-and-collect-results) +For each job, an agent: +- Prepares for the job. +- Runs each step in the job. +- Reports results. -Jobs may [succeed, fail, or be canceled](#state-and-conditions). -There are also situations where a job [may not complete](#timeouts-and-disconnects). -Understanding how this happens can help you troubleshoot issues. +Jobs might succeed, fail, be canceled, or not complete. Understanding these outcomes can help you troubleshoot issues. -Let's break down each action one by one. +The following sections describe the pipeline run process in detail. -## Process the pipeline + +## Pipeline processing -![Expand YAML templates](media/run-expansion.svg) +![Diagram that shows expanding YAML templates.](media/run-expansion.png) -To turn a pipeline into a run, Azure Pipelines goes through several steps in this order: -1. First, expand [templates](templates.md) and evaluate [template expressions](template-expressions.md). -2. Next, evaluate dependencies at the [stage](stages.md) level to pick the first stage(s) to run. -3. For each stage selected to run, two things happen: - * All resources used in all jobs are gathered up and validated for [authorization](approvals.md) to run. - * Evaluate [dependencies at the job level](phases.md#dependencies) to pick the first job(s) to run. -4. For each job selected to run, expand [multi-configs](phases.md#parallelexec) (`strategy: matrix` or `strategy: parallel` in YAML) into multiple runtime jobs. -5. For each runtime job, evaluate [conditions](conditions.md) to decide whether that job is eligible to run. -6. [Request an agent](#request-an-agent) for each eligible runtime job. +To process a pipeline for a run, Azure Pipelines first: -As runtime jobs complete, Azure Pipelines will see if there are new jobs eligible to run. -If so, steps 4 - 6 repeat with the new jobs. -Similarly, as stages complete, steps 2 - 6 will be repeated for any new stages. +1. Expands [templates](templates.md) and evaluates [template expressions](template-expressions.md). +2. Evaluates dependencies at the [stage](stages.md) level to pick the first stage to run. -This ordering helps answer a common question: why can't I use certain variables in my [template parameters](template-parameters.md)? -Step 1, template expansion, operates solely on the text of the YAML document. -Runtime variables don't exist during that step. -After step 1, template parameters have been resolved and no longer exist. +For each stage it selects to run, Azure Pipelines: -It also answers another common issue: why can't I use [variables](variables.md) to resolve service connection / environment names? -Resources are authorized before a stage can start running, so stage- and job-level variables aren't available. -Pipeline-level variables can be used, but only those variables explicitly included in the pipeline. -Variable groups are themselves a resource subject to authorization, so their data is likewise not available when checking resource authorization. +1. Gathers and validates all job resources for [authorization](approvals.md) to run. +2. Evaluates [dependencies at the job level](phases.md#dependencies) to pick the first job to run. -## Request an agent +Azure Pipelines does the following activities for each job it selects to run: -Whenever Azure Pipelines needs to run a job, it will ask the [pool](../agents/pools-queues.md) for an [agent](../agents/agents.md). -([Server jobs](phases.md#server-jobs) are an exception, since they run on the Azure Pipelines server itself.) -[Microsoft-hosted](../agents/hosted.md) and [self-hosted](../agents/pools-queues.md) agent pools work slightly differently. +1. Expands YAML `strategy: matrix` or `strategy: parallel` [multi-configurations](phases.md#multi-job-configuration) into multiple runtime jobs. +5. Evaluates [conditions](conditions.md) to decide whether the job is eligible to run. +6. Requests an agent for each eligible job. -### Microsoft-hosted agent pool requests +As runtime jobs complete, Azure Pipelines checks whether there are new jobs eligible to run. Similarly, as stages complete, Azure Pipelines checks if there are any more stages. -First, the service checks on your organization's parallel jobs. -It adds up all running jobs on all Microsoft-hosted agents and compares that with the number of parallel jobs purchased. -If there are no available parallel slots, the job has to wait on a slot to free up. +### Variables -Once a parallel slot is available, the job is routed to the requested agent type. -Conceptually, the Microsoft-hosted pool is one giant, global pool of machines. -(In reality, it's many different physical pools split by geography and operating system type.) -Based on the `vmImage` (in YAML) or pool name (in the classic editor) requested, an agent is selected. +Understanding the processing order clarifies why you can't use certain variables in [template parameters](template-parameters.md). The first template expansion step operates only on the text of the YAML file. Runtime variables don't yet exist during that step. After that step, template parameters are already resolved. -![Pool selection](media/run-select-pool.svg) +You also can't use [variables](variables.md) to resolve service connection or environment names, because the pipeline authorizes resources before a stage can start running. Stage- and job-level variables aren't available yet. Variable groups are themselves a resource subject to authorization, so their data isn't available when checking resource authorization. -All agents in the Microsoft pool are fresh, new virtual machines that haven't run any pipelines before. -When the job completes, the agent VM will be discarded. +You can use pipeline-level variables that are explicitly included in the [pipeline resource definition](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline). For more information, see [Pipeline resource metadata as predefined variables](/azure/devops/pipelines/yaml-schema/resources-pipelines-pipeline#pipeline-resource-metadata-as-predefined-variables). -### Self-hosted agent pool requests +## Agents -Similar to the [Microsoft-hosted pool](#microsoft-hosted-agent-pool-requests), the service first checks on your organization's parallel jobs. -It adds up all running jobs on all self-hosted agents and compares that with the number of parallel jobs purchased. -If there are no available parallel slots, the job has to wait on a slot to free up. +When Azure Pipelines needs to run a job, it requests an [agent](../agents/agents.md) from the [pool](../agents/pools-queues.md). The process works differently for [Microsoft-hosted](../agents/hosted.md) and [self-hosted](../agents/pools-queues.md) agent pools. -Once a parallel slot is available, the self-hosted pool is examined for a compatible agent. -Self-hosted agents offer [capabilities](../agents/agents.md#capabilities), which are strings indicating that particular software is installed or settings are configured. -The pipeline has [demands](demands.md), which are the capabilities required to run the job. -If a free agent whose capabilities match the pipeline's demands can't be found, the job will continue waiting. -If there are no agents in the pool whose capabilities match the demands, the job will fail. +>[!NOTE] +>[Server jobs](phases.md#server-jobs) don't use a pool because they run on the Azure Pipelines server itself. -Self-hosted agents are typically reused from run to run. -For self-hosted agents, a pipeline job can have side effects such as warming up caches or having most commits already available in the local repo. +![Diagram that shows pool selection.](media/run-select-pool.png) -## Prepare to run a job +### Parallel jobs -Once an agent has accepted a job, it has some preparation work to do. -The agent downloads (and caches for next time) all the [tasks](tasks.md) needed to run the job. -It creates working space on disk to hold the source code, artifacts, and outputs used in the run. -Then it begins [running steps](#run-each-step). +First, Azure Pipelines checks on your organization's [parallel jobs](../licensing/concurrent-jobs.md). The service adds up all running jobs on all agents and compares that with the number of parallel jobs granted or purchased. -## Run each step +If there are no available parallel slots, the job has to wait on a slot to free up. Once a parallel slot is available, the job routes to the appropriate agent type. -Steps are run sequentially, one after another. -Before a step can start, all the previous steps must be finished (or skipped). +### Microsoft-hosted agents -![Run each task](media/run-tasks.svg) +Conceptually, the Microsoft-hosted pool is one global pool of machines, although it's physically many different pools split by geography and operating system type. Based on the YAML `vmImage` or Classic editor pool name requested, Azure Pipelines selects an agent. -Steps are implemented by [tasks](tasks.md). -Tasks themselves are implemented as Node.js or PowerShell scripts. -The task system routes inputs and outputs to the backing scripts. -It also provides some common services such as altering the system path and creating new [pipeline variables](variables.md). +All agents in the Microsoft pool are fresh, new virtual machines (VMs) that have never run any pipelines. When the job completes, the agent VM is discarded. -Each step runs in its own process, isolating it from the environment left by previous steps. -Because of this process-per-step model, environment variables aren't preserved between steps. -However, tasks and scripts have a mechanism to communicate back to the agent: [logging commands](../scripts/logging-commands.md). -When a task or script writes a logging command to standard out, the agent will take whatever action is requested. +### Self-hosted agents -There's an agent command to create new pipeline variables. -Pipeline variables will be automatically converted into environment variables in the next step. -In order to set a new variable `myVar` with a value of `myValue`, a script can do this: +Once a parallel slot is available, Azure Pipelines examines the self-hosted pool for a compatible agent. Self-hosted agents offer [capabilities](../agents/agents.md#capabilities), which indicate that particular software is installed or settings configured. The pipeline has [demands](/azure/devops/pipelines/yaml-schema/pool-demands), which are the capabilities required to run the job. + +If Azure Pipelines can't find a free agent whose capabilities match the pipeline's demands, the job continues waiting. If there are no agents in the pool whose capabilities match the demands, the job fails. + +Self-hosted agents are typically reused from run to run. For self-hosted agents, a pipeline job can have side effects, such as warming up caches or having most commits already available in the local repo. + +## Job preparation + +Once an agent accepts a job, it does the following preparation work: + +1. Downloads all the [tasks](tasks.md) needed to run the job and caches them for future use. +2. Creates working space on disk to hold the source code, artifacts, and outputs used in the run. + + +## Step execution + +The agent runs steps sequentially in order. Before a step can start, all previous steps must be finished or skipped. + +![Diagram that shows running each task.](media/run-tasks.png) + +Steps are implemented by [tasks](tasks.md), which can be Node.js, PowerShell, or other scripts. The task system routes inputs and outputs to the backing scripts. Tasks also provide common services such as altering the system path and creating new [pipeline variables](variables.md). + +Each step runs in its own process, isolating its environment from previous steps. Because of this process-per-step model, environment variables aren't preserved between steps. However, tasks and scripts can use a mechanism called [logging commands](../scripts/logging-commands.md) to communicate back to the agent. When a task or script writes a logging command to standard output, the agent takes whatever action the command requests. + +You can use a logging command to create new pipeline variables. Pipeline variables are automatically converted into environment variables in the next step. A script can set a new variable `myVar` with a value of `myValue` as follows: ```bash echo '##vso[task.setVariable variable=myVar]myValue' @@ -135,96 +118,51 @@ echo '##vso[task.setVariable variable=myVar]myValue' Write-Host "##vso[task.setVariable variable=myVar]myValue" ``` -## Report and collect results +## Result reporting and collection -Each step can report warnings, errors, and failures. -Errors and warnings are reported to the pipeline summary page, marking the task as "succeeded with issues". -Failures are also reported to the summary page, but they mark the task as "failed". -A step is a failure if it either explicitly reports failure (using a `##vso` command) or ends the script with a non-zero exit code. +Each step can report warnings, errors, and failures. The step reports errors and warnings on the pipeline summary page by marking the tasks as succeeded with issues, or reports failures by marking the task as failed. A step fails if it either explicitly reports failure by using a `##vso` command or ends the script with a nonzero exit code. -![Logs and results flow from agent to service](media/run-logging.svg) +As steps run, the agent constantly sends output lines to Azure Pipelines, so you can see a live feed of the console. At the end of each step, the entire output from the step is uploaded as a log file. You can download the log once the pipeline finishes. -As steps run, the agent is constantly sending output lines to the service. -That's why you can see a live feed of the console. -At the end of each step, the entire output from the step is also uploaded as a log file. -Logs can be downloaded once the pipeline has finished. -Other items that the agent can upload include [artifacts](../artifacts/pipeline-artifacts.md) and [test results](../test/review-continuous-test-results-after-build.md). -These are also available after the pipeline completes. +![Diagram showing how logs and results flow from agent to service.](media/run-logging.png) -## State and conditions +The agent can also upload [artifacts](../artifacts/pipeline-artifacts.md) and [test results](../test/review-continuous-test-results-after-build.md), which are also available after the pipeline completes. -The agent keeps track of each step's success or failure. -As steps succeed with issues or fail, the job's status will be updated. -The job always reflects the "worst" outcome from each of its steps: if a step fails, the job also fails. +## State and conditions -Before running a step, the agent will check that step's [condition](conditions.md) to determine whether it should run. -By default, a step will only run when the job's status is succeeded or succeeded with issues. -Many jobs have cleanup steps that need to run no matter what else happened, so they can specify a condition of "always()". -Cleanup steps might also be set to run only on [cancellation](#timeouts-and-disconnects). -A succeeding cleanup step can't save the job from failing; jobs can never go back to success after entering failure. +The agent keeps track of each step's success or failure. As steps succeed with issues or fail, the job's status is updated. The job always reflects the worst outcome from each of its steps. If a step fails, the job also fails. -## Timeouts and disconnects +Before the agent runs a step, it checks that step's [condition](conditions.md) to determine whether the step should run. By default, a step only runs when the job's status is succeeded or succeeded with issues, but you can set other conditions. -Each job has a timeout. -If the job hasn't completed in the specified time, the server will cancel the job. -It will attempt to signal the agent to stop, and it will mark the job as canceled. -On the agent side, this means canceling all remaining steps and uploading any remaining [results](#report-and-collect-results). +Many jobs have cleanup steps that need to run no matter what else happens, so they can specify a condition of `always()`. Cleanup or other steps can also be set to run only on cancellation. -Jobs have a grace period known as the cancel timeout in which to complete any cancellation work. -(Remember, steps can be marked to run [even on cancellation](#state-and-conditions).) -After the timeout plus the cancel timeout, if the agent hasn't reported that work has stopped, the server will mark the job as a failure. +A successful cleanup step can't save the job from failing. Jobs can never go back to success after entering failure. -Because Azure Pipelines distributes work to agent machines, from time to time, agents may stop responding to the server. -This can happen if the agent's host machine goes away (power loss, VM turned off) or if there's a network failure. -To help detect these conditions, the agent sends a heartbeat message once per minute to let the server know it's still operating. -If the server doesn't receive a heartbeat for five consecutive minutes, it assumes the agent won't come back. -The job is marked as a failure, letting the user know they should retry the pipeline. +## Timeouts and disconnects -::: moniker range=">=azure-devops-2020" +Each job has a timeout. If the job doesn't complete in the specified time, the server cancels the job. The server attempts to signal the agent to stop, and marks the job as canceled. On the agent side, cancellation means to cancel all remaining steps and upload any remaining results. -## Manage runs through the CLI +Jobs have a grace period called the cancel timeout in which to complete any cancellation work. You can also mark steps to run even on cancellation. After a job timeout plus a cancel timeout, if the agent doesn't report that work is stopped, the server marks the job as a failure. -Using the Azure DevOps CLI, you can list the pipeline runs in your project and view details about a specific run. You can also add and delete tags in your pipeline run. +Agent machines can stop responding to the server if the agent's host machine loses power or is turned off, or if there's a network failure. To help detect these conditions, the agent sends a heartbeat message once per minute to let the server know it's still operating. -### Prerequisites +If the server doesn't receive a heartbeat for five consecutive minutes, it assumes the agent is not coming back. The job is marked as a failure, letting the user know they should retry the pipeline. -- You must have installed the Azure DevOps CLI extension as described in [Get started with Azure DevOps CLI](../../cli/index.md). -- Sign into Azure DevOps using `az login`. -- For the examples in this article, set the default organization using `az devops configure --defaults organization=YourOrganizationURL`. +::: moniker range=">=azure-devops" +## Manage runs through the Azure DevOps CLI -### List pipeline runs +You can manage pipeline runs by using [az pipelines runs](/cli/azure/pipelines/runs) in the Azure DevOps CLI. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). For a complete command reference, see [Azure DevOps CLI command reference](/cli/azure/service-page/devops). -List the pipeline runs in your project with the [az pipelines runs list](/cli/azure/pipelines/runs#az-pipelines-runs-list) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). +The following examples show how to use the Azure DevOps CLI to list the pipeline runs in your project, view details about a specific run, and manage tags for pipeline runs. -```azurecli -az pipelines runs list [--branch] - [--org] - [--pipeline-ids] - [--project] - [--query-order {FinishTimeAsc, FinishTimeDesc, QueueTimeAsc, QueueTimeDesc, StartTimeAsc, StartTimeDesc}] - [--reason {all, batchedCI, buildCompletion, checkInShelveset, individualCI, manual, pullRequest, schedule, triggered, userCreated, validateShelveset}] - [--requested-for] - [--result {canceled, failed, none, partiallySucceeded, succeeded}] - [--status {all, cancelling, completed, inProgress, none, notStarted, postponed}] - [--tags] - [--top] -``` +### Prerequisites -#### Optional parameters +- Azure CLI with the Azure DevOps CLI extension installed as described in [Get started with Azure DevOps CLI](../../cli/index.md). Sign into Azure using `az login`. +- The default organization set by using `az devops configure --defaults organization=`. -- **branch**: Filter by builds for this branch. -- **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **pipeline-ids**: Space-separated IDs of definitions for which to list builds. -- **project**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. -- **query-order**: Define the order in which pipeline runs are listed. Accepted values are *FinishTimeAsc*, *FinishTimeDesc*, *QueueTimeAsc*, *QueueTimeDesc*, *StartTimeAsc*, and *StartTimeDesc*. -- **reason**: Only list builds for this specified reason. Accepted values are *batchedCI*, *buildCompletion*, *checkInShelveset*, *individualCI*, *manual*, *pullRequest*, *schedule*, *triggered*, *userCreated*, and *validateShelveset*. -- **requested-for**: Limit to the builds requested for a specified user or group. -- **result**: Limit to the builds with a specified result. Accepted values are *canceled*, *failed*, *none*, *partiallySucceeded*, and *succeeded*. -- **status**: Limit to the builds with a specified status. Accepted values are *all*, *cancelling*, *completed*, *inProgress*, *none*, *notStarted*, and *postponed*. -- **tags**: Limit to the builds with each of the specified tags. Space separated. -- **top**: Maximum number of builds to list. +### List pipeline runs -#### Example +List the pipeline runs in your project with the [az pipelines runs list](/cli/azure/pipelines/runs#az-pipelines-runs-list) command. The following command lists the first three pipeline runs that have a status of **completed** and a result of **succeeded**, and returns the result in table format. @@ -238,28 +176,11 @@ Run ID Number Status Result Pipeline ID Pipeline Name 122 20200123.1 completed succeeded 12 Githubname.pipelines-java master 2020-01-23 11:48:05.574742 manual ``` - ### Show pipeline run details -Show the details for a pipeline run in your project with the [az pipelines runs show](/cli/azure/pipelines/runs#az-pipelines-runs-show) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). - -```azurecli -az pipelines runs show --id - [--open] - [--org] - [--project] -``` - -#### Parameters +Show the details for a pipeline run in your project with the [az pipelines runs show](/cli/azure/pipelines/runs#az-pipelines-runs-show) command. -- **id**: Required. ID of the pipeline run. -- **open**: Optional. Opens the build results page in your web browser. -- **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. - -#### Example - -The following command shows details for the pipeline run with the ID **123** and returns the results in table format. It also opens your web browser to the build results page. +The following command shows details for the pipeline run with the ID **123**, returns the results in table format, and opens your web browser to the Azure Pipelines build results page. ```azurecli az pipelines runs show --id 122 --open --output table @@ -271,25 +192,9 @@ Run ID Number Status Result Pipeline ID Pipeline Name ### Add tag to pipeline run -Add a tag to a pipeline run in your project with the [az pipelines runs tag add](/cli/azure/pipelines/runs/tag#az-pipelines-runs-tag-add) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). - -```azurecli -az pipelines runs tag add --run-id - --tags - [--org] - [--project] -``` - -#### Parameters - -- **run-id**: Required. ID of the pipeline run. -- **tags**: Required. Tags to be added to the pipeline run (comma-separated values). -- **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. +Add a tag to a pipeline run in your project with the [az pipelines runs tag add](/cli/azure/pipelines/runs/tag#az-pipelines-runs-tag-add) command. -#### Example - -The following command adds the tag **YAML** to the pipeline run with the ID **123** and returns the result in JSON format. +The following command adds the tag **YAML** to the pipeline run with the ID **123** and returns the result in JSON format. ```azurecli az pipelines runs tag add --run-id 123 --tags YAML --output json @@ -301,23 +206,7 @@ az pipelines runs tag add --run-id 123 --tags YAML --output json ### List pipeline run tags -List the tags for a pipeline run in your project with the [az pipelines runs tag list](/cli/azure/pipelines/runs/tag#az-pipelines-runs-tag-list) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). - -```azurecli -az pipelines runs tag list --run-id - [--org] - [--project] -``` - -#### Parameters - -- **run-id**: Required. ID of the pipeline run. -- **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. - -#### Example - -The following command lists the tags for the pipeline run with the ID **123** and returns the result in table format. +List the tags for a pipeline run in your project with the [az pipelines runs tag list](/cli/azure/pipelines/runs/tag#az-pipelines-runs-tag-list) command. The following command lists the tags for the pipeline run with the ID **123** and returns the result in table format. ```azurecli az pipelines runs tag list --run-id 123 --output table @@ -329,27 +218,17 @@ YAML ### Delete tag from pipeline run -Delete a tag from a pipeline run in your project with the [az pipelines runs tag delete](/cli/azure/pipelines/runs/tag#az-pipelines-runs-tag-delete) command. To get started, see [Get started with Azure DevOps CLI](../../cli/index.md). - -```azurecli -az pipelines runs tag delete --run-id - --tag - [--org] - [--project] -``` - -#### Parameters - -- **run-id**: Required. ID of the pipeline run. -- **tag**: Required. Tag to be deleted from the pipeline run. -- **org**: Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up using `git config`. Example: `--org https://dev.azure.com/MyOrganizationName/`. -- **project**: Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up using `git config`. - -#### Example - -The following command deletes the **YAML** tag from the pipeline run with ID **123**. +Delete a tag from a pipeline run in your project with the [az pipelines runs tag delete](/cli/azure/pipelines/runs/tag#az-pipelines-runs-tag-delete) command. The following command deletes the **YAML** tag from the pipeline run with ID **123**. ```azurecli az pipelines runs tag delete --run-id 123 --tag YAML ``` + ::: moniker-end + +## Related content + +- [Key Azure Pipelines concepts](../get-started/key-pipelines-concepts.md) +- [Stages, dependencies, and conditions](stages.md) +- [Jobs in pipelines](phases.md) +- [Azure Pipelines agents](../agents/agents.md) diff --git a/docs/pipelines/process/runtime-parameters.md b/docs/pipelines/process/runtime-parameters.md index b2da83eafb3..8138dc38f57 100644 --- a/docs/pipelines/process/runtime-parameters.md +++ b/docs/pipelines/process/runtime-parameters.md @@ -1,10 +1,10 @@ --- title: Use runtime and type-safe parameters -ms.custom: seodec18 -description: You can use runtime parameters in pipelines or as part of a template +description: You can use runtime parameters in pipelines or as part of a template ms.topic: conceptual -ms.date: 07/03/2023 +ms.date: 11/19/2024 monikerRange: '>=azure-devops-2020' +ai-usage: ai-assisted --- # Runtime parameters @@ -56,7 +56,7 @@ jobs: - script: echo building $(Build.BuildNumber) with ${{ parameters.image }} ``` -When the pipeline runs, you select the Pool Image. If you don't make a selection, the default option, `ubuntu-latest` gets used. +From the pipeline runs page, select **Run pipeline** to run the pipeline. You'll see the option to select the Pool Image. If you don't make a selection, the default option, `ubuntu-latest` gets used. You won't have the option to select a Pool Image if you run your pipeline from the YAML editor. > [!div class="mx-imgBorder"] > ![runtime parameters](media/runtime-param-ui.png) @@ -294,8 +294,95 @@ steps: displayName: Foo is empty ``` +### Dynamically include a list of steps with the stepList parameter + +In this example, the `stepList` parameter type is used to dynamically include a list of steps in the build process. + +- The main pipeline (`azure-pipelines.yml`) defines two jobs: build and deploy. +- The build job uses a template (`build.yml`) and passes a list of build tasks using the `stepList` parameter. +- The `build.yml` template dynamically includes the steps defined in the `build_tasks` parameter. + +```yaml +#azure-pipelines.yml + +trigger: +- main + +jobs: + - job: build + displayName: 'Build .NET Core Application' + pool: + vmImage: 'ubuntu-latest' + + steps: + - checkout: self + + - template: build.yml + parameters: + build_tasks: + - task: DotNetCoreCLI@2 + displayName: 'Restore' + inputs: + command: 'restore' + projects: '**/*.csproj' + + - task: DotNetCoreCLI@2 + displayName: 'Build' + inputs: + command: 'build' + arguments: '--no-restore' + projects: '**/*.csproj' + + - job: deploy + displayName: 'Pack for Azure App Service deployment' + dependsOn: build + pool: + vmImage: 'ubuntu-latest' + steps: + - download: current + artifact: drop +``` + +The `build.yml` template: + +- Defines the parameter `build_tasks` with the stepList type and a default empty list. +- Sets the .NET Core SDK to 6.x. +- Iterates over each step in the `build_tasks` parameter. +- Executes each step defined in the `build_tasks` list. + +```yaml +#build.yml + +parameters: + - name: build_tasks + type: stepList + default: [] + +steps: + - task: UseDotNet@2 + displayName: 'Use .NET Core SDK' + inputs: + packageType: 'sdk' + version: '6.x' + + - ${{ each step in parameters.build_tasks }}: + - ${{ step }} + + - task: DotNetCoreCLI@2 + displayName: 'Publish' + inputs: + command: 'publish' + arguments: '--configuration Release --output $(Build.ArtifactStagingDirectory)' + projects: '**/*.csproj' + + - task: PublishBuildArtifacts@1 + displayName: 'Publish Artifact' + inputs: + PathtoPublish: '$(Build.ArtifactStagingDirectory)' + ArtifactName: 'drop' +``` + ## Parameter data types [!INCLUDE [parameter-data-types](includes/parameter-data-types.md)] - diff --git a/docs/pipelines/process/scheduled-triggers.md b/docs/pipelines/process/scheduled-triggers.md index d6de2948441..afc4519a715 100644 --- a/docs/pipelines/process/scheduled-triggers.md +++ b/docs/pipelines/process/scheduled-triggers.md @@ -2,10 +2,11 @@ title: Configure schedules to run pipelines description: Configure schedules to run pipelines ms.topic: conceptual +ms.colelction: ce-skilling-ai-copilot +ms.custom: copilot-scenario-highlight ms.author: sdanie author: steved0x -ms.date: 01/17/2023 -ms.custom: contperf-fy21q3 +ms.date: 02/27/2025 monikerRange: '<= azure-devops' --- @@ -13,10 +14,6 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - Azure Pipelines provides several types of triggers to configure how your pipeline starts. * Scheduled triggers start your pipeline based on a schedule, such as a nightly build. This article provides guidance on using scheduled triggers to run your pipelines based on a schedule. @@ -28,7 +25,7 @@ You can combine scheduled and event-based triggers in your pipelines, for exampl #### [YAML](#tab/yaml/) -::: moniker range=">azure-devops-2019" +::: moniker range="<=azure-devops" > [!IMPORTANT] > Scheduled triggers defined using the pipeline settings UI take precedence over YAML scheduled triggers. @@ -40,10 +37,28 @@ You can combine scheduled and event-based triggers in your pipelines, for exampl > Once all UI scheduled triggers are removed, a push must be made in order for the YAML > scheduled triggers to start being evaluated. > -> To delete UI scheduled triggers from a YAML pipeline, see [UI settings override YAML scheduled triggers](../troubleshooting/troubleshooting.md#ui-settings-override-yaml-scheduled-triggers). +> To delete UI scheduled triggers from a YAML pipeline, see [UI settings override YAML scheduled triggers](../troubleshooting/troubleshoot-triggers.md#ui-settings-override-yaml-scheduled-triggers). Scheduled triggers configure a pipeline to run on a schedule defined using [cron syntax](#cron-syntax). +::: moniker-end + +::: moniker range=" [!NOTE] +> The `batch` property is available on Azure DevOps Server 2022.1 and higher. ::: moniker-end -#### [Classic](#tab/classic/) +::: moniker range=">=azure-devops-2022" -Select the days and times when you want to run the build using the classic editor. +The `batch` property configures whether to run the pipeline if the previously scheduled run is in-progress. When `batch` is `true`, a new pipeline run won't start due to the schedule if a previous pipeline run is still in-progress. The default is `false`. -If your repository is Azure Repos Git, GitHub, or Other Git, then you can also specify branches to include and exclude. If you want to use wildcard characters, then type the branch specification (for example, `features/modules/*`) and then press Enter. +The `batch` property is affected by the setting of the `always` property. When `always` is `true`, the pipeline runs according to the cron schedule, even when `batch` is `true` and there is an in-progress run. +| Always | Batch | Behavior | +|--------|-------|----------| +| `false` | `false` | Pipeline runs only if there's a change with respect to the last successful scheduled pipeline run, even if there's an in-progress run from the last scheduled trigger. | +| `false` | `true` | Pipeline runs only if there's a change with respect to the last successful scheduled pipeline run, and there's no in-progress scheduled pipeline run. | +| `true` | `false` | Pipeline runs according to the cron schedule. | +| `true` | `true` | Pipeline runs according to the cron schedule even if there is an in-progress run. | -::: moniker range=">= azure-devops-2019" +### Build.CronSchedule.DisplayName variable -![Scheduled trigger UTC + 5:30 time zone](media/triggers/scheduled-trigger-git-india.png) +::: moniker-end + +::: moniker range="=azure-devops-2022" + +> [!NOTE] +> The `Build.CronSchedule.DisplayName` variable is available on Azure DevOps Server 2022.1 and higher. ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range=">=azure-devops-2022" + +When a pipeline is running due to a cron scheduled trigger, the pre-defined `Build.CronSchedule.DisplayName` variable contains the `displayName` of the cron schedule that triggered the pipeline run. + +Your YAML pipeline may contain multiple cron schedules, and you may want your pipeline to run different stages or jobs based on which cron schedule runs. For example, you have a nightly build and a weekly build, and you want to run a certain stage only during the nightly build. You can use the `Build.CronSchedule.DisplayName` variable in a job or stage condition to determine whether to run that job or stage. + +```yml +- stage: stage1 + # Run this stage only when the pipeline is triggered by the + # "Daily midnight build" cron schedule + condition: eq(variables['Build.CronSchedule.DisplayName'], 'Daily midnight build') +``` -![scheduled trigger multiple time zones.](media/triggers/scheduled-trigger-git-multiple-time-zones-neweditor.png) +For more examples, see [schedules.cron examples](/azure/devops/pipelines/yaml-schema/schedules-cron#examples). + +::: moniker-end + +#### [Classic](#tab/classic/) + +Select the days and times when you want to run the build using the classic editor. + +If your repository is Azure Repos Git, GitHub, or Other Git, then you can also specify branches to include and exclude. If you want to use wildcard characters, then type the branch specification (for example, `features/modules/*`) and then press Enter. + +::: moniker range="<=azure-devops" + +![Scheduled trigger UTC + 5:30 time zone](media/triggers/scheduled-trigger-git-india.png) ::: moniker-end @@ -166,7 +221,7 @@ If your repository is Azure Repos Git, GitHub, or Other Git, then you can also s #### [YAML](#tab/yaml/) -::: moniker range=">azure-devops-2019" +::: moniker range="<=azure-devops" The following example defines two schedules: @@ -199,24 +254,11 @@ For more examples, see [Migrating from the classic editor](#migrating-from-the-c ::: moniker-end -::: moniker range="azure-devops-2019" - -Scheduled builds aren't supported in YAML syntax in Azure DevOps Server 2019. -After you create your YAML build pipeline, you can use pipeline settings to specify a scheduled trigger. - -::: moniker-end - -::: moniker range="tfs-2018" - -YAML isn't supported in TFS. - -::: moniker-end - #### [Classic](#tab/classic/) #### Example: Nightly build of Git repo in multiple time zones -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" In this example, the classic editor scheduled trigger has two entries, which produce the following builds. @@ -230,16 +272,9 @@ In this example, the classic editor scheduled trigger has two entries, which pro ::: moniker-end -::: moniker range="tfs-2018" - -![scheduled trigger multiple time zones.](media/triggers/scheduled-trigger-git-multiple-time-zones-neweditor.png) - -::: moniker-end - - #### Example: Nightly build with different frequencies -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" **Azure Pipelines and Azure DevOps 2019 Server** @@ -255,21 +290,13 @@ In this example, the classic editor scheduled trigger has two entries, producing ::: moniker-end -::: moniker range="tfs-2018" - - -![Scheduled trigger different frequencies, TFS 2017.3 through TFS 2018.](media/triggers/scheduled-trigger-git-different-frequencies-neweditor.png) - -::: moniker-end - - * * * ## Cron syntax #### [YAML](#tab/yaml/) -::: moniker range=">azure-devops-2019" +::: moniker range="<=azure-devops" Each Azure Pipelines scheduled trigger cron expression is a space-delimited expression with five entries in the following order. The expression is enclosed in single quotes `'`. @@ -308,19 +335,39 @@ Build every 6 hours starting at 9:00 AM | `0 9,15,21 * * *` or `0 9-21/6 * * *` For more information on supported formats, see [Crontab Expression](https://github.com/atifaziz/NCrontab/wiki/Crontab-Expression). +### Use GitHub Copilot to create a cron expression -::: moniker-end +You can get AI assistance from GitHub Copilot to build cron expressions, or convert existing cron expressions from your local time zone to UTC. -::: moniker range="azure-devops-2019" +Azure Pipelines cron schedules are defined in UTC, so schedules like **Build every Monday, Wednesday, and Friday at 6:00 PM** must be created using cron syntax, and converted from your local time zone to UTC. -Scheduled builds aren't supported in YAML syntax in Azure DevOps Server 2019. -After you create your YAML build pipeline, you can use pipeline settings to specify a scheduled trigger. +Customize the following prompts to create cron expressions, or convert cron expressions to UTC from the time zone you used to create the expressions. -::: moniker-end +In the following example, Copilot is prompted to create a UTC cron schedule to build every Monday, Wednesday, and Friday at 6:00 PM Eastern Standard Time. -::: moniker range="tfs-2018" +```copilot-prompt +Build a UTC cron expression for Monday, Wednesday, and Friday at 6:00 PM Eastern Standard Time +``` + +If you already have a cron expression in your local time zone, you can ask Copilot to convert it to UTC. In this example, a cron schedule to build every Monday, Wednesday, and Friday at 6:00 PM (`0 18 * * Mon,Wed,Fri`) Eastern Standard Time is converted to UTC. + +```copilot-prompt +Convert the following cron expression from Eastern Standard Time to UTC: 0 18 * * Mon,Wed,Fri +``` + +Converting a cron expression to UTC might require changing the days of the week in your expression. In the following example, Copilot is prompted to create a UTC cron schedule to build Monday through Friday at 12:30 AM Central European Standard Time. Central European Standard Time is ahead of UTC, so the resulting expression starts late Sunday night instead of early Monday morning, and ends on Thursday. + +```copilot-prompt +Build a UTC cron expression for Monday through Friday at 12:30 AM Central European Standard Time +``` + +To get additional details about the cron expression generated by Copilot, you can ask Copilot to provide an explanation of the generated cron expression in your prompt. -YAML isn't supported in TFS. +```copilot-prompt +Build a UTC cron expression for Monday through Friday at 12:30 AM Central European Standard Time and explain the different parts of the cron expression +``` + +*Copilot is powered by AI, so surprises and mistakes are possible. For more information, see [Copilot general use FAQs](https://aka.ms/copilot-general-use-faqs).* ::: moniker-end @@ -334,13 +381,16 @@ Classic schedules are defined using a graphical editor instead of cron syntax. F #### [YAML](#tab/yaml/) -::: moniker range=">azure-devops-2019" +::: moniker range="<=azure-devops" -You can view a preview of upcoming scheduled builds by choosing **Scheduled runs** from the context menu on the [pipeline details page](../create-first-pipeline.md#view-pipeline-details) for your pipeline. +You can view a preview of upcoming scheduled builds by choosing **Scheduled runs** from the context menu on the [pipeline details page](../create-first-pipeline.md#view-pipeline-details) for your pipeline. + +> [!IMPORTANT] +> The scheduled runs view only shows pipelines scheduled to run within seven days from the current date. If your cron schedule has an interval longer than 7 days and the next run is scheduled to start after seven days from the current date, it won't be displayed in the **Scheduled runs** view. ![Scheduled runs menu](media/triggers/scheduled-runs-menu.png) -After you create or update your scheduled triggers, you can verify them using this view. +After you create or update your scheduled triggers, you can verify them using **Scheduled runs** view. ![Scheduled runs](media/triggers/scheduled-runs.png) @@ -357,18 +407,8 @@ schedules: The **Scheduled runs** windows displays the times converted to the local time zone set on the computer used to browse to the Azure DevOps portal. This example displays a screenshot taken in the EST time zone. -::: moniker-end - -::: moniker range="azure-devops-2019" - -Scheduled builds aren't supported in YAML syntax in Azure DevOps Server 2019. -After you create your YAML build pipeline, you can use pipeline settings to specify a scheduled trigger. - -::: moniker-end - -::: moniker range="tfs-2018" - -YAML isn't supported in TFS. +> [!NOTE] +> If you update the schedule for a running pipeline, the **Scheduled runs** view isn't updated with the new schedule until the currently running pipeline completes. ::: moniker-end @@ -385,38 +425,12 @@ After you create or update your scheduled triggers, you can verify them using th ::: moniker-end -::: moniker range="< azure-devops-2020" - -Classic scheduled pipelines don't have a **Scheduled runs** view, but you can view the schedule for a pipeline in the classic schedule editor for your pipeline. - -::: moniker-end - -::: moniker range="= azure-devops-2019" - -![Scheduled trigger UTC + 5:30 time zone](media/triggers/scheduled-trigger-git-india.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -![scheduled trigger multiple time zones.](media/triggers/scheduled-trigger-git-multiple-time-zones-neweditor.png) - -::: moniker-end - - * * * ## Running even when there are no code changes -::: moniker range="<=tfs-2018" - -> [!NOTE] -> Scheduled builds always run on schedule regardless of code changes on TFS 2018.1 and lower. - -::: moniker-end - -::: moniker range=">=tfs-2018" +::: moniker range="<=azure-devops" By default, your pipeline doesn't run as scheduled if there have been no code changes since the last successful scheduled run. For instance, consider that you've scheduled a pipeline to run every night at 9:00pm. During the weekdays, you push various changes to your code. The pipeline runs as per schedule. During the weekends, you don't make any changes to your code. If there have been no code changes since the scheduled run on Friday, then the pipeline doesn't run as scheduled during the weekend. @@ -424,7 +438,7 @@ By default, your pipeline doesn't run as scheduled if there have been no code ch #### [YAML](#tab/yaml/) -::: moniker range=">azure-devops-2019" +::: moniker range="<=azure-devops" To force a pipeline to run even when there are no code changes, you can use the `always` keyword. @@ -437,36 +451,9 @@ schedules: ::: moniker-end -::: moniker range="azure-devops-2019" - -Scheduled builds aren't supported in YAML syntax in this version of Azure DevOps Server. -After you create your YAML build pipeline, you can use pipeline settings to specify a scheduled trigger. - -::: moniker-end - -::: moniker range="tfs-2018" - -YAML isn't supported in TFS. - -::: moniker-end - #### [Classic](#tab/classic/) -::: moniker range="<=tfs-2018" - -> [!NOTE] -> Scheduled builds always run on schedule regardless of code changes on TFS 2018.1 and lower. - -::: moniker-end - -::: moniker range="tfs-2018" - -> [!NOTE] -> The [Skip scheduled builds if nothing has changed in the repo](/previous-versions/azure/devops/2017/dec-11-vsts#skip-scheduled-builds-if-nothing-has-changed-in-the-repo) support described in this section is supported in TFS 2018.2 and higher. - -::: moniker-end - -::: moniker range=">=tfs-2018" +::: moniker range="<=azure-devops" To configure the scheduled pipeline to build only if there has been a change since the last build, check **Only schedule builds if the source or pipeline has changed**. @@ -483,7 +470,7 @@ There are certain limits on how often you can schedule a pipeline to run. These - around 1000 runs per pipeline per week - 10 runs per pipeline per 15 minutes -::: moniker range=">azure-devops-2019" +::: moniker range="<=azure-devops" ## Migrating from the classic editor The following examples show you how to migrate your schedules from the classic editor to YAML. @@ -521,13 +508,13 @@ schedules: In the first schedule, **M-F 3:00 AM (UTC + 5:30) India daily build**, the cron syntax (`mm HH DD MM DW`) is `30 21 * * Sun-Thu`. -* Minutes and Hours - `30 21` - This maps to `21:30 UTC` (`9:30 PM UTC`). Since the specified time zone in the classic editor is **UTC + 5:30**, we need to subtract 5 hours and 30 minutes from the desired build time of 3:00 AM to arrive at the desired UTC time to specify for the YAML trigger. +* Minutes and Hours - `30 21` - This maps to `21:30 UTC` (`9:30 PM UTC`). Since the specified time zone in the classic editor is **UTC + 5:30**, we need to subtract 5 hours and 30 minutes from the desired build time of 3:00 AM to arrive at the desired UTC time to specify for the YAML trigger. [You can get AI assistance from GitHub Copilot to create your cron expression](#use-github-copilot-to-create-a-cron-expression). * Days and Months are specified as wildcards since this schedule doesn't specify to run only on certain days of the month or on a specific month. * Days of the week - `Sun-Thu` - because of the timezone conversion, for our builds to run at 3:00 AM in the UTC + 5:30 India time zone, we need to specify starting them the previous day in UTC time. We could also specify the days of the week as `0-4` or `0,1,2,3,4`. In the second schedule, **M-F 3:00 AM (UTC - 5) NC daily build**, the cron syntax is `0 8 * * Mon-Fri`. -* Minutes and Hours - `0 8` - This maps to `8:00 AM UTC`. Since the specified time zone in the classic editor is **UTC - 5:00**, we need to add 5 hours from the desired build time of 3:00 AM to arrive at the desired UTC time to specify for the YAML trigger. +* Minutes and Hours - `0 8` - This maps to `8:00 AM UTC`. Since the specified time zone in the classic editor is **UTC - 5:00**, we need to add 5 hours from the desired build time of 3:00 AM to arrive at the desired UTC time to specify for the YAML trigger. [You can get AI assistance from GitHub Copilot to create your cron expression](#use-github-copilot-to-create-a-cron-expression). * Days and Months are specified as wildcards since this schedule doesn't specify to run only on certain days of the month or on a specific month. * Days of the week - `Mon-Fri` - Because our timezone conversions don't span multiple days of the week for our desired schedule, we don't need to do any conversion here. We could also specify the days of the week as `1-5` or `1,2,3,4,5`. @@ -586,12 +573,26 @@ In the second schedule, **Sunday 3:00 AM (UTC) weekly latest version build**, th ## FAQ +* [I want my pipeline to run only on the schedule and not when someone pushes a change to a branch](#i-want-my-pipeline-to-run-only-on-the-schedule-and-not-when-someone-pushes-a-change-to-a-branch) * [I defined a schedule in the YAML file. But it didn't run. What happened?](#i-defined-a-schedule-in-the-yaml-file-but-it-didnt-run-what-happened) * [My YAML schedules were working fine. But, they stopped working now. How do I debug this?](#my-yaml-schedules-were-working-fine-but-they-stopped-working-now-how-do-i-debug-this) * [My code hasn't changed, yet a scheduled build is triggered. Why?](#my-code-hasnt-changed-yet-a-scheduled-build-is-triggered-why) * [I see the planned run in the Scheduled runs panel. However, it doesn't run at that time. Why?](#i-see-the-planned-run-in-the-scheduled-runs-panel-however-it-doesnt-run-at-that-time-why) * [Schedules defined in YAML pipeline work for one branch but not the other. How do I fix this?](#schedules-defined-in-yaml-pipeline-work-for-one-branch-but-not-the-other-how-do-i-fix-this) +### I want my pipeline to run only on the schedule and not when someone pushes a change to a branch + +If you want your pipeline to run only on the schedule, and not when someone pushes a change to a branch or merges a change to the main branch, you must explicitly disable the default CI and PR triggers on the pipeline. + +To disable the default CI and PR triggers, add the following statements to your YAML pipeline, and [verify that you haven't overridden the YAML pipeline triggers with UI triggers](../troubleshooting/troubleshoot-triggers.md#ui-settings-override-yaml-trigger-setting). + +```yaml +trigger: none +pr: none +``` + +For more information, see [pr definition](/azure/devops/pipelines/yaml-schema/pr) and [trigger definition](/azure/devops/pipelines/yaml-schema/trigger). + ### I defined a schedule in the YAML file. But it didn't run. What happened? * Check the next few runs that Azure Pipelines has scheduled for your pipeline. You can find these runs by selecting the **Scheduled runs** action in your pipeline. The list is filtered down to only show you the upcoming few runs over the next few days. If this doesn't meet your expectation, it's probably the case that you've mistyped your cron schedule, or you don't have the schedule defined in the correct branch. Read the topic above to understand how to configure schedules. Reevaluate your cron syntax. All the times for cron schedules are in UTC. diff --git a/docs/pipelines/process/service-containers.md b/docs/pipelines/process/service-containers.md index 9848439fa73..9f1272682ab 100644 --- a/docs/pipelines/process/service-containers.md +++ b/docs/pipelines/process/service-containers.md @@ -1,10 +1,9 @@ --- -title: Service Containers -titleSuffix: Azure Pipelines -description: Run containerized services alongside pipeline jobs +title: Service containers +description: Learn about running containerized services in Azure Pipelines single or multiple container jobs or noncontainer jobs. ms.assetid: a6af47c5-2358-487a-ba3c-d213930fceb8 ms.topic: conceptual -ms.date: 01/24/2023 +ms.date: 07/15/2024 monikerRange: azure-devops --- @@ -12,29 +11,22 @@ monikerRange: azure-devops [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -If your pipeline requires the support of one or more services, in many cases you'll want to create, connect to, and clean up each -service on a per-job basis. For instance, a pipeline may run integration tests that require access to -a database and a memory cache. The database and memory cache need to be freshly created for each job in the pipeline. +If your pipeline requires the support of one or more services, you might need to create, connect to, and clean up the services per job. For example, your pipeline might run integration tests that require access to a newly created database and memory cache for each job in the pipeline. -A container provides a simple and portable way to run a service that your pipeline depends on. -A _service container_ enables you to automatically create, network, and manage the lifecycle of your containerized service. -Each service container is accessible by only the job that requires it. -Service containers work with any kind of [job](phases.md), but they're most commonly used with [container jobs](container-phases.md). +A *container* provides a simple and portable way to run a service that your pipeline depends on. A *service container* lets you automatically create, network, and manage the lifecycle of a containerized service. Each service container is accessible only to the [job](phases.md) that requires it. Service containers work with any kind of job, but are most commonly used with [container jobs](container-phases.md). ## Requirements -Service containers must define a `CMD` or `ENTRYPOINT`. -The pipeline will run `docker run` for the provided container without additional arguments. +- Service containers must define a `CMD` or `ENTRYPOINT`. The pipeline runs `docker run` for the provided container without any arguments. -Azure Pipelines can run Linux or [Windows Containers](/virtualization/windowscontainers/about/). Use either -hosted Ubuntu for Linux containers, or the Hosted Windows Container pool for Windows containers. -(The Hosted macOS pool doesn't support running containers.) +- Azure Pipelines can run Linux or [Windows containers](/virtualization/windowscontainers/about/). You can use either the hosted Ubuntu container pool for Linux containers or the hosted Windows pool for Windows containers. The hosted macOS pool doesn't support running containers. -# [YAML](#tab/yaml) +>[!NOTE] +>Service containers aren't supported in Classic pipelines. ## Single container job -A simple example of using [container jobs](container-phases.md): +The following example YAML pipeline definition shows a single container job. ```yaml resources: @@ -44,7 +36,6 @@ resources: - container: nginx image: nginx - pool: vmImage: 'ubuntu-latest' @@ -58,15 +49,13 @@ steps: displayName: Show that nginx is running ``` -This pipeline fetches the `nginx` and `buildpack-deps` containers from [Docker Hub](https://hub.docker.com) -and then starts the containers. The containers are networked together so that they can reach each other -by their `services` name. +The preceding pipeline fetches the `nginx` and `buildpack-deps` containers from [Docker Hub](https://hub.docker.com) and then starts the containers. The containers are networked together so that they can reach each other by their `services` name. + +From inside this job container, the `nginx` host name resolves to the correct services by using Docker networking. All containers on the network automatically expose all ports to each other. -From inside this job container, the `nginx` host name resolves to the correct services using Docker networking. -All containers on the network automatically expose all ports to each other. -## Single job +## Single noncontainer job -You can also use service containers without a job container. A simple example: +You can also use service containers without a job container, as in the following example. ```yaml resources: @@ -95,20 +84,15 @@ steps: echo $AGENT_SERVICES_REDIS_PORTS_6379 ``` -This pipeline starts the latest `nginx` containers. Since the job isn't running in a container, there's no automatic name resolution. -This example shows how you can instead reach services by using `localhost`. -In the above example, we provide the port explicitly (for example, `8080:80`). +The preceding pipeline starts the latest `nginx` containers. Since the job isn't running in a container, there's no automatic name resolution. Instead, you can reach services by using `localhost`. The example explicitly provides the `8080:80` port. + +An alternative approach is to let a random port get assigned dynamically at runtime. You can then access these dynamic ports by using [variables](variables.md). These variables take the form: `agent.services..ports.`. In a Bash script, you can access variables by using the process environment. -An alternative approach is to let a random -port get assigned dynamically at runtime. You can then access these dynamic ports by using [variables](variables.md). -In a Bash script, you can access a variable by using the process environment. These variables take the form: `agent.services..ports.`. -In the above example, `redis` is assigned a random available port on the host. -The `agent.services.redis.ports.6379` variable contains the port number. +In the preceding example, `redis` is assigned a random available port on the host. The `agent.services.redis.ports.6379` variable contains the port number. ## Multiple jobs -Service containers are also useful for running the same steps against multiple versions of the same service. -In the following example, the same steps run against multiple versions of PostgreSQL. +Service containers are also useful for running the same steps against multiple versions of the same service. In the following example, the same steps run against multiple versions of PostgreSQL. ```yaml resources: @@ -140,7 +124,7 @@ steps: ## Ports -When specifying a container resource or an inline container, you can specify an array of `ports` to expose on the container. +When you invoke a container resource or an inline container, you can specify an array of `ports` to expose on the container, as in the following example. ```yaml resources: @@ -158,20 +142,15 @@ services: - 6379/tcp ``` -Specifying `ports` is not required if your job is running in a container because containers on the same Docker network automatically expose all ports -to each other by default. +Specifying `ports` isn't required if your job is running in a container, because containers on the same Docker network automatically expose all ports to each other by default. -If your job is running on the host, then `ports` are required to access the service. A port takes the form `:` or just ``, -with an optional `/` at the end, for example `6379/tcp` to expose `tcp` over port `6379`, bound to a random port on the host machine. +If your job is running on the host, `ports` are required to access the service. A port takes the form `:` or just `` with an optional `/` at the end. For example, `6379/tcp` exposes `tcp` over port `6379`, bound to a random port on the host machine. -For ports bound to a random port on the host machine, the pipeline creates a variable of the form `agent.services..ports.` so that it can be accessed -by the job. For example, `agent.services.redis.ports.6379` resolves to the randomly assigned port on the host machine. +For ports bound to a random port on the host machine, the pipeline creates a variable of the form `agent.services..ports.` so that the job can access the port. For example, `agent.services.redis.ports.6379` resolves to the randomly assigned port on the host machine. ## Volumes -Volumes are useful for sharing data between services, or for persisting data between multiple runs of a job. - -You can specify volume mounts as an array of `volumes`. Volumes can either be named Docker volumes, anonymous Docker volumes, or bind mounts on the host. +Volumes are useful for sharing data between services or for persisting data between multiple runs of a job. You specify volume mounts as an array of `volumes` of the form `:`, where `` can be a named volume or an absolute path on the host machine, and `` is an absolute path in the container. Volumes can be named Docker volumes, anonymous Docker volumes, or bind mounts on the host. ```yaml services: @@ -183,32 +162,29 @@ services: - /src/dir:/dst/dir ``` -Volumes take the form `:`, where `` can be a named volume or an absolute path on the host machine, and `` is -an absolute path in the container. - -> [!NOTE] -> If you use our hosted pools, then your volumes will not be persisted between jobs because the host machine is cleaned up after the job is completed. +>[!NOTE] +>If you use Microsoft-hosted pools, your volumes aren't persisted between jobs, because the host machine is cleaned up after each job is completed. -## Other options +## Startup options -Service containers share the same container resources as container jobs. This means that you can use the same -[additional options](container-phases.md?tabs=yaml#options). +Service containers share the same container resources as container jobs. This means that you can use the same [startup options](container-phases.md?tabs=yaml#options). -# [Classic](#tab/classic) +## Health check -Service containers aren't yet supported in classic pipelines. +If any service container specifies a [HEALTHCHECK](https://docs.docker.com/engine/reference/builder/#healthcheck), the agent can optionally wait until the container is healthy before running the job. ---- - -## Healthcheck +## Multiple containers with services example -Optionally, if any service container specifies a [HEALTHCHECK](https://docs.docker.com/engine/reference/builder/#healthcheck), the -agent waits until the container is healthy before running the job. +The following example has a Django Python web container connected to PostgreSQL and MySQL database containers. -## Multiple containers with services example +- The PostgreSQL database is the primary database, and its container is named `db`. +- The `db` container uses volume `/data/db:/var/lib/postgresql/data`, and there are three database variables passed to the container via `env`. +- The `mysql` container uses port `3306:3306`, and there are also database variables passed via `env`. +- The `web` container is open with port `8000`. -In this example, there's a Django Python web container connected to two database containers - PostgreSQL and MySQL. The PostgreSQL database is the primary database and its container has the name `db`. The `db` container uses volume `/data/db:/var/lib/postgresql/data` and there are three database variables passed to the container via `env`. The `mysql` container uses port `3306:3306` and there are also database variables passed via `env`. The `web` container is open with port `8000`. In the steps, `pip` installs dependencies and then Django test are run. If you'd like to get a working example set up, you'll need a [Django site set up with two databases](https://docs.djangoproject.com/en/3.2/topics/db/multi-db/). This example assumes your `manage.py` file is in the root directory and your Django project is within that directory. You may need to update the `/__w/1/s/` path in `/__w/1/s/manage.py test`. +In the steps, `pip` installs dependencies and then Django tests run. +To set up a working example, you need a [Django site set up with two databases](https://docs.djangoproject.com/en/3.2/topics/db/multi-db/). The example assumes your *manage.py* file is in the root directory and your Django project is also within that directory. If not, you might need to update the `/__w/1/s/` path in `/__w/1/s/manage.py test`. ```yaml resources: @@ -254,3 +230,8 @@ steps: - script: | python /__w/1/s/manage.py test ``` + +## Related content + +- [Specify jobs in your pipeline](phases.md) +- [Use container jobs in YAML pipelines](container-phases.md) diff --git a/docs/pipelines/process/set-secret-variables.md b/docs/pipelines/process/set-secret-variables.md index 6727cd62bb9..93b27d3bc1d 100644 --- a/docs/pipelines/process/set-secret-variables.md +++ b/docs/pipelines/process/set-secret-variables.md @@ -2,23 +2,23 @@ title: Set secret variables description: Learn how to set secret variables. ms.topic: conceptual -ms.date: 06/03/2022 -monikerRange: 'azure-devops || >= azure-devops-2019' +ms.date: 11/19/2024 +monikerRange: "<=azure-devops" --- # Set secret variables [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2019.md)] -Secret variables are encrypted variables that you can use in pipelines without exposing their value. Secret variables can be used for private information like passwords, IDs, and other identifying data that you wouldn't want to have exposed in a pipeline. Secret variables are encrypted at rest with a 2048-bit RSA key and are available on the agent for tasks and scripts to use. +Secret variables are encrypted variables that you can use in pipelines without exposing their value. Secret variables can be used for private information like passwords, IDs, and other identifying data that you wouldn't want exposed in a pipeline. Secret variables are encrypted at rest with a 2048-bit RSA key and are available on the agent for tasks and scripts to use. -The recommended ways to [set secret variables are in the UI](#secret-variable-in-the-ui), [in a variable group](#set-a-secret-variable-in-a-variable-group), and [in a variable group from Azure Key Vault](#link-secrets-from-an-azure-key-vault). You can also [set secret variables in a script with a logging command](#set-secret-variable-in-a-script-with-logging-commands) but this is not recommended since anyone who can access your pipeline will be able to also see the secret. +The recommended ways to [set secret variables are in the UI](#secret-variable-in-the-ui), [in a variable group](#set-a-secret-variable-in-a-variable-group), and [in a variable group from Azure Key Vault](#link-secrets-from-an-azure-key-vault). You can also [set secret variables in a script with a logging command](#set-secret-variable-in-a-script-with-logging-commands) but this method isn't recommended since anyone who can access your pipeline can also see the secret. -Secret variables set in the pipeline settings UI for a pipeline are scoped to the pipeline where they are set. You can use variable groups to share secret variables across pipelines. +Secret variables set in the pipeline settings UI for a pipeline are scoped to the pipeline where they're set. You can use variable groups to share secret variables across pipelines. ## Secret variable in the UI -You can set secret variables in the pipeline editor when you are editing an individual pipeline. You'll encrypt and make a pipeline variable secret by selecting the lock icon. +You can set secret variables in the pipeline editor when you're editing an individual pipeline. You encrypt and make a pipeline variable secret by selecting the lock icon. You set secret variables the same way for YAML and Classic. @@ -28,7 +28,7 @@ You set secret variables the same way for YAML and Classic. #### [YAML](#tab/yaml/) -You'll need to map secret variable as environment variables to reference them in YAML pipelines. In this example, there are two secret variables defined in the UI, `SecretOne` and `SecretTwo`. The value of `SecretOne` is `foo` and the value of `SecretTwo` is `bar`. +You need to map secret variable as environment variables to reference them in YAML pipelines. In this example, there are two secret variables defined in the UI, `SecretOne` and `SecretTwo`. The value of `SecretOne` is `foo` and the value of `SecretTwo` is `bar`. ```yml steps: @@ -56,13 +56,14 @@ True My second secret variable: *** Strings are equal. ``` -For a more detailed example, see [Define variables](variables.md#secret-variables). +[!INCLUDE [secrets masked](./includes/masked-secrets.md)] -#### [Classic](#tab/classic/) +For a more detailed example, see [Define variables](variables.md#secret-variables). +#### [Classic](#tab/classic/) -Unlike a normal variable, secret are not automatically decrypted into environment variables for scripts. You need to explicitly map secret variables. +Unlike a normal variable, secret aren't automatically decrypted into environment variables for scripts. You need to explicitly map secret variables. In this example, the variable `mySecret` is set on the Variables tab. The value of `mySecret` is `foo`. @@ -101,9 +102,8 @@ You can add secrets to a variable group or link secrets from an existing [Azure Variable groups follow the [library security model](../library/index.md#library-security). ### Link secrets from an Azure key vault - -[!INCLUDE [set secret variable in UI](includes/variable-groups-link-secrets.md)] - + +You can create variable groups and link them to an existing Azure key vault, allowing you to map to secrets stored in the key vault. Only the secret names are mapped to the variable group, not the secret values. Pipeline runs that link to the variable group fetch the latest secret values from the vault. For more information, see [Link a variable group to secrets in Azure Key Vault](../library/link-variable-groups-to-key-vaults.md). ## Use the Azure Key Vault task @@ -115,16 +115,16 @@ You can use the Azure Key Vault task to include secrets in your pipeline. This t :::image type="content" source="../release/media/azure-key-vault/configure-azure-key-vault-task.png" alt-text="Add the Azure Key Vault task."::: -The **Make secrets available to whole job** option is not currently supported in Azure DevOps Server 2019 and 2020. +The **Make secrets available to whole job** option isn't currently supported in Azure DevOps Server 2019 and 2020. To learn more about the Azure Key Vault task, see [Use Azure Key Vault secrets in Azure Pipelines](../release/azure-key-vault.md). ## Set secret variable in a script with logging commands -You can use the `task.setvariable` logging command to set variables in PowerShell and Bash scripts. This is the least secure way to work with secret variables but can be useful for debugging. The recommended ways to set secret variables are in the UI, in a variable group, and in a variable group from Azure Key Vault. +You can use the `task.setvariable` logging command to set variables in PowerShell and Bash scripts. This method is the least secure way to work with secret variables but can be useful for debugging. The recommended ways to set secret variables are in the UI, in a variable group, and in a variable group from Azure Key Vault. -To set a variable as a script with a logging command, you'll need to pass the `issecret` flag. +To set a variable as a script with a logging command, you need to pass the `issecret` flag. [!INCLUDE [set secret variable in UI](includes/secret-variables-logging.md)] diff --git a/docs/pipelines/process/set-variables-scripts.md b/docs/pipelines/process/set-variables-scripts.md index 11db09fbe9b..ba95b2a88b4 100644 --- a/docs/pipelines/process/set-variables-scripts.md +++ b/docs/pipelines/process/set-variables-scripts.md @@ -3,7 +3,7 @@ title: Set variables in scripts description: Learn how to define variables in Bash and PowerShell scripts and use them in your pipeline. ms.topic: conceptual -ms.date: 05/10/2023 +ms.date: 01/08/2025 monikerRange: '<= azure-devops' --- @@ -13,9 +13,9 @@ monikerRange: '<= azure-devops' When you use PowerShell and Bash scripts in your pipelines, it's often useful to be able to set variables that you can then use in future tasks. Newly set variables aren't available in the same task. -Scripts are great for when you want to do something that isn't supported by a task like calling a custom REST API and parsing the response. +Scripts are great for when you want to do something not supported by a task. For example, you can use a script to call a custom REST API and parse the response. -You'll use the `task.setvariable` logging command to set variables in [PowerShell](../scripts/powershell.md) and [Bash](/azure/devops/pipelines/tasks/reference/bash-v3) scripts. +You use the `task.setvariable` logging command to set variables in [PowerShell](../scripts/powershell.md) and [Bash](/azure/devops/pipelines/tasks/reference/bash-v3) scripts. > [!NOTE] > Deployment jobs use a different syntax for output variables. To learn more about support for output variables in deployment jobs, see [Deployment jobs](./deployment-jobs.md#support-for-output-variables). @@ -24,7 +24,7 @@ To use a variable with a condition in a pipeline, see [Specify conditions](condi ## About `task.setvariable` -When you add a variable with `task.setvariable`, the following tasks can use the variable using macro syntax `$(myVar)`. The variable will only be available to tasks in the same job by default. If you add the parameter `isoutput`, the syntax to call your variable changes. See [Set an output variable for use in the same job](#set-an-output-variable-for-use-in-the-same-job). +When you add a variable with `task.setvariable`, the following tasks can use the variable using macro syntax `$(myVar)`. The variable is only available to tasks in the same job by default. If you add the parameter `isOutput`, the syntax to call your variable changes. For more information, see [Set an output variable for use in the same job](#set-an-output-variable-for-use-in-the-same-job). # [Bash](#tab/bash) @@ -64,13 +64,13 @@ Read the variable `myVar`: The `task.setvariable` command includes properties for setting a variable as secret, as an output variable, and as read only. The available properties include: * `variable` = variable name (Required) -* `issecret` = boolean (Optional, defaults to false) -* `isoutput` = boolean (Optional, defaults to false) -* `isreadonly` = boolean (Optional, defaults to false) +* `isSecret` = boolean (Optional, defaults to false) +* `isOutput` = boolean (Optional, defaults to false) +* `isReadOnly` = boolean (Optional, defaults to false) -To use the variable in the next stage, set the `isoutput` property to `true`. To reference a variable with the `isoutput` set to true, you'll include the task name. For example, `$(TaskName.myVar)`. +To use the variable in the next stage, set the `isOutput` property to `true`. To reference a variable with the `isOutput` set to true, you include the task name. For example, `$(TaskName.myVar)`. -When you set a variable as read only, it can't be overwritten by downstream tasks. Set `isreadonly` to `true`. Setting a variable as read only enhances security by making that variable immutable. +When you set a variable as read only, downstream tasks can't overwrite it. Set `isreadonly` to `true`. Setting a variable as read only enhances security by making that variable immutable. ## Set a variable as secret @@ -82,18 +82,28 @@ When you set a variable as read only, it can't be overwritten by downstream task There are four different types of output variables with distinct syntaxes: -* [Output variables set in the same job without the `isoutput` parameter](#set-an-output-variable-for-use-in-the-same-job). To reference these variables, you'll use macro syntax. Example: `$(myVar)`. -* [Output variables set in the same job with the `isoutput` parameter](#set-an-output-variable-for-use-in-the-same-job). To reference these variables, you'll include the task name. Example: `$(myTask.myVar)`. -* [Output variables set in a future job](#set-an-output-variable-for-use-in-future-jobs). To reference these variables, you'll reference the variable in the `variables` section with `dependency` syntax. -* [Output variables set in future stages](#set-an-output-variable-for-use-in-future-stages). To reference these variables, you'll reference the variable in the `variables` section with `stageDependencies` syntax. +* [Output variables set in the same job without the `isOutput` parameter](#set-an-output-variable-for-use-in-the-same-job). To reference these variables, you use macro syntax. Example: `$(myVar)`. +* [Output variables set in the same job with the `isOutput` parameter](#set-an-output-variable-for-use-in-the-same-job). To reference these variables, you include the task name. Example: `$(myTask.myVar)`. +* [Output variables set in a future job](#set-an-output-variable-for-use-in-future-jobs). To reference these variables, you reference the variable in the `variables` section with `dependency` syntax. +* [Output variables set in future stages](#set-an-output-variable-for-use-in-future-stages). To reference these variables, you reference the variable in the `variables` section with `stageDependencies` syntax. + +> [!NOTE] +> Future stages or jobs can only access output variables if they depend on the stage or job where the variable was set. To make an output variable accessible, make sure that the next stage or job depends on the stage or job where you created the variable. If multiple stages or jobs need to use the same output variable, use the `dependsOn` condition to establish this dependency. + +The name of an output variable may change if your pipeline uses an [execution strategy like a matrix job](/azure/devops/pipelines/yaml-schema/jobs-job-strategy). For those cases, output your variable for testing first to verify its name. You can also print out all available variables in a pipeline with the script `env`. + +```yaml +- script: env + displayName: 'Print all variables' +``` ## Set an output variable for use in the same job -When you use an output variable in the same job, you don't have to use the `isoutput` property. By default, the variable will be available to downstream steps within the same job. However, if you do add the `isoutput` property, you'll need to reference the variable with the task name. +When you use an output variable in the same job, you don't have to use the `isOutput` property. By default, the variable is available to downstream steps within the same job. However, if you do add the `isOutput` property, you need to reference the variable with the task name. # [Bash](#tab/bash) -The script here sets the same-job output variable `myJobVar` without specifying `isoutput` and sets `myOutputJobVar` with `isoutput=true`. +The script here sets the same-job output variable `myJobVar` without specifying `isOutput` and sets `myOutputJobVar` with `isOutput=true`. ```yaml jobs: @@ -102,11 +112,11 @@ jobs: - bash: | echo "##vso[task.setvariable variable=myJobVar]this is the same job" - bash: | - echo "##vso[task.setvariable variable=myOutputJobVar;isoutput=true]this is the same job too" + echo "##vso[task.setvariable variable=myOutputJobVar;isOutput=true]this is the same job too" name: setOutput ``` -This script gets the same-job variables `myJobVar` and `myOutputJobVar`. Notice that the syntax changes for referencing an output variable once `isoutput=true` is added. +This script gets the same-job variables `myJobVar` and `myOutputJobVar`. Notice that the syntax changes for referencing an output variable once `isOutput=true` is added. ```yaml jobs: @@ -115,7 +125,7 @@ jobs: - bash: | echo "##vso[task.setvariable variable=myJobVar]this is the same job" - bash: | - echo "##vso[task.setvariable variable=myOutputJobVar;isoutput=true]this is the same job too" + echo "##vso[task.setvariable variable=myOutputJobVar;isOutput=true]this is the same job too" name: setOutput - bash: | echo $(myJobVar) @@ -125,7 +135,7 @@ jobs: # [PowerShell](#tab/powershell) -This script sets the same-job output variable `myJobVar` without specifying `isoutput` and sets `myOutputJobVar` with `isoutput=true`. +This script sets the same-job output variable `myJobVar` without specifying `isOutput` and sets `myOutputJobVar` with `isOutput=true`. ```yaml jobs: @@ -134,11 +144,11 @@ jobs: - powershell: | Write-Host "##vso[task.setvariable variable=myJobVar]this is the same job" - powershell: | - Write-Host "##vso[task.setvariable variable=myOutputJobVar;isoutput=true]this is the same job too" + Write-Host "##vso[task.setvariable variable=myOutputJobVar;isOutput=true]this is the same job too" name: setOutput ``` -This script gets the same-job variables `myJobVar` and `myOutputJobVar`. Notice that the syntax changes for referencing an output variable once `isoutput=true` is added. +This script gets the same-job variables `myJobVar` and `myOutputJobVar`. Notice that the syntax changes for referencing an output variable once `isOutput=true` is added. ```yaml jobs: @@ -147,7 +157,7 @@ jobs: - powershell: | Write-Host "##vso[task.setvariable variable=myJobVar]this is the same job" - powershell: | - Write-Host "##vso[task.setvariable variable=myOutputJobVar;isoutput=true]this is the same job too" + Write-Host "##vso[task.setvariable variable=myOutputJobVar;isOutput=true]this is the same job too" name: setOutput - powershell: | Write-Host $(myJobVar) @@ -158,7 +168,7 @@ jobs: --- ## Set an output variable for use in future jobs -When you use output variables across jobs, you'll reference them with `dependencies`. The syntax for accessing an output variable in a future job or stage varies based on the relationship between the setter and consumer of the variable. Learn about each case in [dependencies](expressions.md#dependencies). +When you use output variables across jobs, you reference them with `dependencies`. The syntax for accessing an output variable in a future job or stage varies based on the relationship between the setter and consumer of the variable. Learn about each case in [dependencies](expressions.md#dependencies). # [Bash](#tab/bash) @@ -169,7 +179,7 @@ jobs: - job: A steps: - bash: | - echo "##vso[task.setvariable variable=myOutputVar;isoutput=true]this is from job A" + echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is from job A" name: passOutput ``` @@ -181,7 +191,7 @@ jobs: - job: A steps: - bash: | - echo "##vso[task.setvariable variable=myOutputVar;isoutput=true]this is from job A" + echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is from job A" name: passOutput - job: B dependsOn: A @@ -201,7 +211,7 @@ jobs: - job: A steps: - powershell: | - Write-Host "##vso[task.setvariable variable=myOutputVar;isoutput=true]this is from job A" + Write-Host "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is from job A" name: passOutput ``` @@ -212,7 +222,7 @@ jobs: - job: A steps: - powershell: | - Write-Host "##vso[task.setvariable variable=myOutputVar;isoutput=true]this is from job A" + Write-Host "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is from job A" name: passOutput - job: B dependsOn: A @@ -228,8 +238,9 @@ jobs: Output variables can be used across stages in pipelines. You can use output variables to pass useful information, such as the ID of a generated output, from one stage to the next. -When you set a variable with the `isoutput` property, you can reference that variable in later stages with the task name and the `stageDependencies` syntax. Learn more about [dependencies](expressions.md#stage-depending-on-job-output). +When you set a variable with the `isOutput` property, you can reference that variable in later stages with the task name and the `stageDependencies` syntax. Learn more about [dependencies](expressions.md#dependencies). +Output variables are only available in the next downstream stage. If multiple stages consume the same output variable, use the `dependsOn` condition. # [Bash](#tab/bash) @@ -293,7 +304,7 @@ stages: --- -In case your value contains newlines, you can escape them and the agent will automatically unescape it: +In case your value contains newlines, you can escape them and the agent automatically unescapes it: ```yaml steps: @@ -313,8 +324,34 @@ steps: ### My output variable isn't rendering. What is going wrong? -There are a few reasons why your output variable may not appear. +There are a few reasons why your output variable might not appear. + +* Output variables set with `isOutput` aren't available in the same job and instead are only available in downstream jobs. +* Depending on what variable syntax you use, a variable that sets an output variable's value might not be available at runtime. For example, variables with macro syntax (`$(var)`) get processed before a task runs. In contrast, variables with template syntax are processed at runtime (`$[variables.var]`). You usually want to use runtime syntax when setting output variables. For more information on variable syntax, see [Define variables](variables.md#understand-variable-syntax). +* There might be extra spaces within your expression. If your variable isn't rendering, check for extra spaces surrounding `isOutput=true`. + +You can troubleshoot the `dependencies` output for a pipeline job or stage by adding a variable for the dependencies and then printing that variable. For example, in this pipeline job `A` sets the output variable `MyTask`. The second job (`B`) depends on job `A`. A new variable, `deps` holds the JSON representation of the job dependencies. The second step in Job `B` uses PowerShell to print `deps` so that you can see the job dependencies. + +```yml +trigger: +- '*' + +pool: + vmImage: 'ubuntu-latest' + +jobs: +- job: A + steps: + - script: | + echo "##vso[task.setvariable variable=MyTask;isOutput=true]theoutputval" + name: ProduceVar +- job: B + dependsOn: A + variables: + varFromA: $[ dependencies.A.outputs['ProduceVar.MyTask'] ] + deps: $[convertToJson(dependencies)] # create a variable with the job dependencies + steps: + - script: echo $(varFromA) # + - powershell: Write-Host "$(deps)" + ``` -* Output variables set with `isoutput` aren't available in the same job and instead are only available in downstream jobs. -* Depending on what variable syntax you use, a variable that sets an output variable's value may not be available at runtime. For example, variables with macro syntax (`$(var)`) get processed before a task runs. In contrast, variables with template syntax are processed at runtime (`$[variables.var]`). You'll usually want to use runtime syntax when setting output variables. For more information on variable syntax, see [Define variables](variables.md#understand-variable-syntax). -* There may be extra spaces within your expression. If your variable isn't rendering, check for extra spaces surrounding `isOutput=true`. \ No newline at end of file diff --git a/docs/pipelines/process/stages.md b/docs/pipelines/process/stages.md index 96ec9e45c71..937a6f7e2c4 100644 --- a/docs/pipelines/process/stages.md +++ b/docs/pipelines/process/stages.md @@ -1,10 +1,9 @@ --- title: Stages in Azure Pipelines -ms.custom: seodec18 -description: Understand stages in Azure Pipelines +description: Learn how to organize your jobs into stages, define dependencies, and set conditions. Understand how to implement deployment strategies and use YAML or a Classic pipeline to define stages. ms.assetid: FAAD6503-F8CE-4F5D-8C1E-83AF6E903568 ms.topic: conceptual -ms.date: 12/22/2022 +ms.date: 02/16/2024 monikerRange: '<= azure-devops' --- @@ -12,13 +11,9 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - -A stage is a logical boundary in the pipeline. It can be used to mark separation of concerns (for example, Build, QA, and production). Each stage contains one or more jobs. When you define multiple stages in a pipeline, by default, they run one after the other. +A stage is a logical boundary in an Azure DevOps pipeline. Stages can be used to group actions in your software development process (for example, build the app, run tests, deploy to preproduction). Each stage contains one or more jobs. -For Classic pipelines, You can organize the deployment jobs in your release pipeline into stages. +When you define multiple stages in a pipeline, by default, they run one after the other. Stages can also depend on each other. You can use the `dependsOn` keyword to define [dependencies](#specify-dependencies). Stages also can run based on the result of a previous stage with [conditions](#conditions). To learn how stages work with parallel jobs and licensing, see [Configure and pay for parallel jobs](../licensing/concurrent-jobs.md). @@ -27,36 +22,22 @@ To find out how stages relate to other parts of a pipeline such as jobs, see [Ke You can also learn more about how stages relate to parts of a pipeline in the [YAML schema stages article](/azure/devops/pipelines/yaml-schema/stages). #### [YAML](#tab/yaml/) -::: moniker range=">=azure-devops-2019" - -You can organize pipeline jobs into stages. Stages are the major divisions in a pipeline: "build this app", "run these tests", and "deploy to pre-production" are good examples of stages. They're logical boundaries in your pipeline where you can pause the pipeline and perform various checks. - -Every pipeline has at least one stage even if you don't explicitly define it. You can also arrange stages into a dependency graph so that one stage runs before another one. There is a limit of 256 jobs for a stage. - -::: moniker-end - -::: moniker range="azure-devops-2019" - -> [!NOTE] -> Support for stages was added in Azure DevOps Server 2019.1. - -::: moniker-end +::: moniker range="<=azure-devops" -::: moniker range="< azure-devops-2019" +You can organize pipeline jobs into stages. Stages are the major divisions in a pipeline: build this app, run these tests, and deploy to preproduction are good examples of stages. They're logical boundaries in your pipeline where you can pause the pipeline and perform various checks. -This version of TFS doesn't support YAML. +Every pipeline has at least one stage even if you don't explicitly define it. You can also arrange stages into a dependency graph so that one stage runs before another one. There's a limit of 256 jobs for a stage. ::: moniker-end #### [Classic](#tab/classic/) -You can organize the deployment jobs in your release pipeline into stages. -Stages are the major divisions in your release pipeline: "run functional tests", "deploy to pre-production", -and "deploy to production" are good examples of release stages. +Organize the deployment jobs in your release pipeline into stages. +Stages are the major divisions in your release pipeline: run functional tests, deploy to preproduction, and deploy to production are good examples of release stages. A stage in a release pipeline consists of [jobs](../process/phases.md) and [tasks](../process/tasks.md). -[Approvals and gates](../release/approvals/index.md), [deployment conditions and triggers](../release/triggers.md#env-triggers), +[Approvals and gates](../release/approvals/index.md), [deployment conditions and triggers](../release/triggers.md#stage-triggers), and [queuing policies](#queuing-policies) control when a release gets deployed to a stage. ![stage](../release/media/definition-02.png) @@ -67,14 +48,7 @@ and [queuing policies](#queuing-policies) control when a release gets deployed t #### [YAML](#tab/yaml/) -::: moniker range="azure-devops-2019" - -> [!NOTE] -> Support for stages was added in Azure DevOps Server 2019.1. - -::: moniker-end - -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" In the simplest case, you don't need any logical boundaries in your pipeline. In that case, you don't have to explicitly use the `stage` keyword. You can directly specify the jobs in your YAML file. @@ -113,18 +87,11 @@ stages: - job: B2 ``` -If you choose to specify a `pool` at the stage level, then all jobs defined in that stage will use that pool unless otherwise specified at the job-level. - -::: moniker-end - -::: moniker range="azure-devops-2019" - -> [!NOTE] -> In Azure DevOps Server 2019, pools can only be specified at job level. +If you choose to specify a `pool` at the stage level, then all jobs defined in that stage use that pool unless specified at the job-level. ::: moniker-end -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" ```yaml stages: @@ -151,12 +118,6 @@ stages: ::: moniker-end -::: moniker range="< azure-devops-2019" - -This version of TFS doesn't support YAML pipelines. - -::: moniker-end - #### [Classic](#tab/classic/) To add a stage to your release pipeline, select the release pipeline in **Releases** page, select the action to **Edit** it, and then select the **Pipeline** tab. @@ -182,20 +143,12 @@ for a stage in a release pipeline. You can: #### [YAML](#tab/yaml/) -::: moniker range="azure-devops-2019" - -> [!NOTE] -> Support for stages was added in Azure DevOps Server 2019.1. - -::: moniker-end - -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" When you define multiple stages in a pipeline, by default, they run sequentially in the order in which you define them in the YAML file. The exception to this is when you add dependencies. With dependencies, stages run in the order of the `dependsOn` requirements. Pipelines must contain at least one stage with no dependencies. - The syntax for defining multiple stages and their dependencies is: ```yaml @@ -257,21 +210,16 @@ stages: ::: moniker-end -::: moniker range="< azure-devops-2019" - -This version of TFS doesn't support YAML pipelines. - -::: moniker-end - #### [Classic](#tab/classic/) You control the dependencies by setting the triggers on each stage of the release pipeline: * Stages run with a trigger or by being manually started. -* With an **After release** trigger, a stage will start as soon as the release starts, in parallel with other stages that have **After release** trigger. +* With an **After release** trigger, a stage starts as soon as the release starts, in parallel with other stages that have **After release** trigger. * With an **After stage** trigger, a stage will start after all the dependent stages complete. Using this, you can model fan-out and fan-in behavior for stages. * * * -

      Conditions

      + +## Define conditions You can specify the conditions under which each stage runs with [expressions](expressions.md). By default, a stage runs if it doesn't depend on any other stage, or if all of the stages that it depends on have completed and succeeded. You can customize this behavior by forcing a stage to run even if a previous stage fails or by specifying a custom condition. @@ -281,17 +229,9 @@ If you customize the default condition of the preceding steps for a stage, you r > > Conditions for failed ('JOBNAME/STAGENAME') and succeeded ('JOBNAME/STAGENAME') as shown in the following example work only for [YAML pipelines](?tabs=yaml). - #### [YAML](#tab/yaml/) -::: moniker range="azure-devops-2019" - -> [!NOTE] -> Support for stages was added in Azure DevOps Server 2019.1. - -::: moniker-end - -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" Example to run a stage based upon the status of running a previous stage: @@ -323,14 +263,6 @@ stages: ::: moniker-end -::: moniker range="< azure-devops-2019" - -This version of TFS doesn't support YAML pipelines. - - -::: moniker-end - - #### [Classic](#tab/classic/) When you specify **After release** or **After stage** triggers, you can also specify the branch filters for the artifacts consumed in the release. Releases will only deploy to a stage when the branch filters are satisfied. @@ -342,16 +274,10 @@ When you specify **After release** or **After stage** triggers, you can also spe ## Specify queuing policies #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" YAML pipelines don't support queuing policies. Each run of a pipeline is independent from and unaware of other runs. In other words, your two successive commits may trigger two pipelines, and both of them will execute the same sequence of stages without waiting for each other. While we work to bring queuing policies to YAML pipelines, we recommend that you use [manual approvals](approvals.md) in order to manually sequence and control the order the execution if this is of importance. ::: moniker-end -::: moniker range="< azure-devops-2019" - -This version of TFS doesn't support YAML pipelines. - -::: moniker-end - #### [Classic](#tab/classic/) In some cases, you may be able to generate builds faster than they can be deployed. Alternatively, you may configure multiple @@ -365,57 +291,47 @@ stage. **Queuing policies** give you that control. The options you can choose for a queuing policy are: * **Number of parallel deployments**: - Use this option if you dynamically provision new resources - in your stage and it's physically capable of handling - the deployment of multiple releases in parallel, but you want - to limit the number of parallel deployments. + Use this option if you dynamically provision new resources in your stage and it's physically capable of handling the deployment of multiple releases in parallel, but you want to limit the number of parallel deployments. * If you specify a maximum number of deployments, two more options appear: - **Deploy all in sequence**: - Use this option if you want to deploy all the releases - sequentially into the same shared physical resources. - By deploying the builds in turn, one after the other, you - ensure that two deployment jobs don't target the same - physical resources concurrently, even if there are - multiple build and release agents available. You - also ensure that pre-deployment approval requests for the - stage are sent out in sequence. + Use this option if you want to deploy all the releases sequentially into the same shared physical resources. + By deploying the builds in turn, one after the other, you ensure that two deployment jobs don't target the same physical resources concurrently, even if there are multiple build and release agents available. You also ensure that predeployment approval requests for the stage are sent out in sequence. - **Deploy latest and cancel the others**: - Use this option if you're producing releases faster - than builds, and you only want to deploy the latest build. + Use this option if you're producing builds faster than releases, and you only want to deploy the latest build. To understand how these options work, consider a scenario where releases **R1**, **R2**, **...**, **R5** of a single release pipeline get created in quick succession. Assume that the first stage in this pipeline is named **QA** -and has both pre-deployment and post-deployment approvers +and has both predeployment and post-deployment approvers defined. * If you don't specify a limit for the number of parallel deployments, - all five approval requests will be sent out as soon as + all five approval requests are sent out as soon as the releases are created. If the approvers approve all of the releases, they'll all be deployed to the **QA** stage in parallel. - (if the **QA** stage didn't have any pre-deployment + (if the **QA** stage didn't have any predeployment approvers defined, all the five releases will automatically be deployed in parallel to this stage). * If you specify a limit and **Deploy all in sequence**, - and the limit has already been reached, the pre-deployment approval for + and the limit has already been reached, the predeployment approval for release **R1** will be sent out first. After this approval is completed, the deployment of release **R1** to the **QA** stage begins. Next, a request for post-deployment approval is sent out for release **R1**. It's only after this post-deployment approval is completed that - execution of release **R2** begins and its pre-deployment + execution of release **R2** begins and its predeployment approval is sent out. The process continues like this for all of the releases in turn. * If you specify a limit and **Deploy latest and cancel the others**, and the limit has already been reached, releases **R2**, **R3**, and **R4** will be - skipped, and the pre-deployment approval for **R5** in + skipped, and the predeployment approval for **R5** in the **QA** stage will be sent out immediately after the post-deployment approval for release **R1** is completed. @@ -425,30 +341,70 @@ defined. #### [YAML](#tab/yaml/) -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" You can manually control when a stage should run using approval checks. This is commonly used to control deployments to production environments. Checks are a mechanism available to the *resource owner* to control if and when a stage in a pipeline can consume a resource. As an owner of a resource, such as an environment, you can define checks that must be satisfied before a stage consuming that resource can start. -Currently, manual approval checks are supported on environments. -For more information, see [Approvals](approvals.md). +Currently, manual approval checks are supported on environments. For more information, see [Approvals](approvals.md). ::: moniker-end -::: moniker range="= azure-devops-2019" +#### [Classic](#tab/classic/) -Approvals aren't yet supported in YAML pipelines in this version of Azure DevOps Server. +You can add manual approvals at the start or end of each stage in the pipeline. For more information, see [Release approvals and gates overview](../release/approvals/index.md). -::: moniker-end +* * * -::: moniker range="< azure-devops-2019" +::: moniker range="azure-devops" -This version of TFS doesn't support YAML pipelines. -::: moniker-end +## Add a manual trigger -#### [Classic](#tab/classic/) +Manually triggered YAML pipeline stages enable you to have a unified pipeline without always running it to completion. -You can add manual approvals at the start or end of each stage in the pipeline. For more information, see [Release approvals and gates overview](../release/approvals/index.md). +For instance, your pipeline might include stages for building, testing, deploying to a staging environment, and deploying to production. You might want all stages to run automatically except for the production deployment, which you prefer to trigger manually when ready. +To use this feature, add the `trigger: manual` property to a stage. + +In the following example, the development stage runs automatically, while the production stage requires manual triggering. Both stages run a hello world output script. + +```yaml +stages: +- stage: development + displayName: Deploy to development + jobs: + - job: DeployJob + steps: + - script: echo 'hello, world' + displayName: 'Run script' +- stage: production + displayName: Deploy to production + trigger: manual + jobs: + - job: DeployJob + steps: + - script: echo 'hello, world' + displayName: 'Run script' +``` + +## Mark a stage as unskippable + +Mark a stage as `isSkippable: false` to prevent pipeline users from skipping stages. For example, you may have a YAML template that injects a stage that performs malware detection in all pipelines. If you set `isSkippable: false` for this stage, Pipeline won't be able to skip malware detection. + +In the following example, the Malware detection stage is marked as non-skippable, meaning it must be executed as part of the pipeline run. + +```yaml +- stage: malware_detection + displayName: Malware detection + isSkippable: false + jobs: + - job: check_job + ... +``` + +When a stage is non-skippable, it will show with a disabled checkbox in the **Stages to run** configuration panel. + +:::image type="content" source="media/stages/stages-run-skip-stage.png" alt-text="Screenshot of stages to run with disabled stage. "::: + +::: moniker-end -* * * diff --git a/docs/pipelines/process/tasks.md b/docs/pipelines/process/tasks.md index 8b4109925da..862a96151de 100644 --- a/docs/pipelines/process/tasks.md +++ b/docs/pipelines/process/tasks.md @@ -1,60 +1,49 @@ --- -title: Build and Release Tasks -ms.custom: seodec18 -description: Understand Build and Release tasks in Azure Pipelines +title: Task types & usage +description: Learn how to define tasks in your pipeline, set inputs, and control task conditions with Azure DevOps. ms.topic: conceptual ms.assetid: 3293E200-6B8C-479D-9EA0-B3E82CE1450F -ms.date: 12/21/2022 +ms.date: 02/21/2024 monikerRange: '<= azure-devops' +ai-usage: ai-assisted --- # Task types & usage [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -[!INCLUDE [temp](../includes/concept-rename-note.md)] +A **task** performs an action in a pipeline and is a packaged script or procedure that's +abstracted with a set of inputs. Tasks are the building blocks for defining automation in a pipeline. -A **task** is the building block for defining automation in a -pipeline. -A task is simply a packaged script or procedure that has been -abstracted with a set of inputs. - -When you add a task to your pipeline, it may also add a set of **demands** to the pipeline. The demands define the prerequisites that must be installed on the [agent](../agents/agents.md) for the task to run. When you run the build or deployment, an agent that meets these demands will be chosen. - -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" When you run a [job](phases.md), all the tasks are run in sequence, one after the other. To run the same set of tasks in parallel on multiple agents, or to run some tasks without using an agent, see [jobs](phases.md). By default, all tasks run in the same context, whether that's on the [host](phases.md) or in a [job container](container-phases.md). -You may optionally use [step targets](#step-target) to control context for an individual task. -Learn more about how to specify properties for a task with the [built-in tasks](../tasks/index.md). +You might optionally use [step targets](#step-target) to control context for an individual task. +Learn more about how to specify properties for a task with the [built-in tasks](../tasks/index.md). ::: moniker-end -::: moniker range="<= azure-devops-2019" - -When you run a [job](phases.md), all the tasks are run in sequence, one after the other, on an agent. To run the same set of tasks in parallel on multiple agents, or to run some tasks without using an agent, see [jobs](phases.md). - -::: moniker-end +To learn more about the general attributes supported by tasks, see the [YAML Reference for *steps.task*](/azure/devops/pipelines/yaml-schema/steps-task). ## Custom tasks -We provide some [built-in tasks](../tasks/index.md) -to enable fundamental build and deployment scenarios. We have also -provided guidance for [creating your own custom task](../../extend/develop/add-build-task.md). +Azure DevOps includes [built-in tasks](../tasks/index.md) +to enable fundamental build and deployment scenarios. You also can [create your own custom task](../../extend/develop/add-build-task.md). In addition, [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops) offers many extensions; each of which, when installed to your subscription or collection, extends the task catalog with one or more tasks. -Furthermore, you can write your own [custom extensions](../../integrate/index.md) -to add tasks to Azure Pipelines or TFS. +You can also write your own [custom extensions](../../integrate/index.md) +to add tasks to Azure Pipelines. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" In YAML pipelines, you refer to tasks by name. If a name matches both an in-box task -and a custom task, the in-box task will take precedence. You can use the task GUID or a fully qualified +and a custom task, the in-box task takes precedence. You can use the task GUID or a fully qualified name for the custom task to avoid this risk: ```yaml @@ -75,17 +64,16 @@ pipeline. This can help to prevent issues when new versions of a task are releas Tasks are typically backwards compatible, but in some scenarios you may encounter unpredictable errors when a task is automatically updated. -When a new minor version is released (for example, 1.2 to 1.3), your build or release -will automatically use the new version. However, if a new major version is released -(for example 2.0), your build or release will continue to use the major version you specified +When a new minor version is released (for example, 1.2 to 1.3), your pipeline +automatically uses the new version. However, if a new major version is released +(for example 2.0), your pipeline continues to use the major version you specified until you edit the pipeline and manually change to the new major version. -The build or release log will include an alert that a new major version is available. +The log will include an alert that a new major version is available. You can set which minor version gets used by specifying the full version number of a task after the `@` sign (example: `GoTool@0.3.1`). You can only use task versions that exist for your [organization](../../organizations/accounts/organization-management.md). - #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" In YAML, you specify the major version using `@` in the task name. For example, to pin to version 2 of the `PublishTestResults` task: @@ -97,17 +85,11 @@ steps: ::: moniker-end -::: moniker range="<= azure-devops-2019" - -YAML pipelines aren't available in TFS. - -::: moniker-end - #### [Classic](#tab/classic/) Each task in a pipeline has a **Version** selector to let you choose the version you want. -If you select a preview version (such as **1.\* Preview**), be aware that this -version is still under development and might have known issues. +If you select a preview version (such as **1.\* Preview**), the +version is still under development and might have issues. If you change the version and have problems with your builds, you can revert the pipeline change from the **History** tab. The ability to restore to an older version of a release pipeline isn't currently available. You must manually revert the changes to the release pipeline, then save the pipeline. @@ -124,52 +106,50 @@ Each task offers you some **Control Options**. #### [YAML](#tab/yaml/) -::: moniker range="azure-devops-2019" - -Control options are available as keys on the `task` section. - -```yaml -- task: string # reference to a task and version, e.g. "VSBuild@1" - condition: expression # see below - continueOnError: boolean # 'true' if future steps should run even if this step fails; defaults to 'false' - enabled: boolean # whether or not to run this step; defaults to 'true' - timeoutInMinutes: string # how long to wait before timing out the task -``` - -::: moniker-end - -::: moniker range=">azure-devops-2019 [!NOTE] > A given task or job can't unilaterally decide whether the job/stage continues. What it can do is offer a status of **succeeded** or **failed**, and downstream tasks/jobs each have a condition computation that lets them decide whether to run or not. The default condition which is effectively "run if we're in a successful state". @@ -182,7 +162,7 @@ time the task is queued or is waiting for an agent. > [!NOTE] > Pipelines may have a job level timeout specified in addition to a task level timeout. If the job level timeout interval elapses before your step completes, the running job is terminated, even if the step is configured with a longer timeout interval. For more information, see [Timeouts](phases.md#timeouts). -In this YAML, `PublishTestResults@2` will run even if the previous step fails because of the [succeededOrFailed() condition](expressions.md#succeededorfailed). +In this YAML, `PublishTestResults@2` runs even if the previous step fails because of the [succeededOrFailed() condition](expressions.md#succeededorfailed). ```yaml steps: @@ -196,7 +176,6 @@ steps: condition: succeededOrFailed() ``` - ### Conditions [!INCLUDE [include](includes/task-run-built-in-conditions.md)] @@ -204,12 +183,12 @@ steps: ::: moniker-end -:::moniker range="> azure-devops-2019" +:::moniker range="> azure-devops-2020" ### Step target Tasks run in an execution context, which is either the agent host or a container. -An individual step may override its context by specifying a `target`. +An individual step might override its context by specifying a `target`. Available options are the word `host` to target the agent host plus any containers defined in the pipeline. For example: @@ -230,21 +209,22 @@ Here, the `SampleTask` runs on the host and `AnotherTask` runs in a container. ::: moniker-end -::: moniker range="azure-devops" +::: moniker range=">= azure-devops-2020" ### Number of retries if task failed -Use `retryCountOnTaskFailure` to specify the number of retries if the task fails. The default is zero. +Use `retryCountOnTaskFailure` to specify the number of retries if the task fails. The default is zero retries. For more information on task properties, see [steps.task in the YAML Schema](/azure/devops/pipelines/yaml-schema/steps-task). ```yml - task: - retryCountOnTaskFailure: + retryCountOnTaskFailure: ... ``` > [!NOTE] -> * Requires agent version 2.194.0 or later. Not supported for [agentless tasks](./phases.md#agentless-tasks). -> * The failing task retries in seconds. The wait time between each retry increases after each failed attempt. +> * Requires agent version 2.194.0 or later. On Azure DevOps Server 2022, retries are not supported for [agentless tasks](./phases.md#agentless-jobs-supported-tasks). For more information, see [Azure DevOps service update November 16, 2021 - Automatic retries for a task](/azure/devops/release-notes/2021/sprint-195-update#automatic-retries-for-a-task), and [Azure DevOps service update June 14, 2025 - Retries for server tasks](/azure/devops/release-notes/2024/sprint-240-update#retries-for-server-tasks). +> * The maximum number of retries allowed is 10. +> * The wait time between each retry increases after each failed attempt, following an exponential backoff strategy. The 1st retry happens after 1 second, the 2nd retry after 4 seconds, and the 10th retry after 100 seconds. > * There is no assumption about the idempotency of the task. If the task has side-effects (for instance, if it created an external resource partially), then it may fail the second time it is run. > * There is no information about the retry count made available to the task. > * A warning is added to the task logs indicating that it has failed before it is retried. @@ -252,12 +232,6 @@ Use `retryCountOnTaskFailure` to specify the number of retries if the task fails ::: moniker-end -::: moniker range="<= azure-devops-2019" - -YAML pipelines aren't available in TFS. - -::: moniker-end - #### [Classic](#tab/classic/) ### Enabled @@ -297,13 +271,11 @@ Specify the number of retries if this task fails. The default is zero. Select the condition for running this task: [!INCLUDE [include](includes/task-run-built-in-conditions.md)] -* [Custom conditions](conditions.md) which are composed of [expressions](expressions.md) +* [Custom conditions](conditions.md), which are composed of [expressions](expressions.md) > [!NOTE] > If you're running tasks in cases when the build is canceled, then make sure you specify sufficient time for these tasks to run the [pipeline options](../process/phases.md#timeouts). -### TFS 2018 and newer options - #### Continue on error (partially successful) Select this option if you want subsequent tasks in the same job to run even if this task fails. The build or deployment will be no better than partially successful. @@ -314,29 +286,21 @@ Select this check box if you want the task to run even if the build or deploymen * * * - - ## Environment variables #### [YAML](#tab/yaml/) -:::moniker range="< azure-devops-2019" - -YAML pipelines are supported in Azure DevOps Server 2019 and higher. - -:::moniker-end - -:::moniker range=">= azure-devops-2019" - Each task has an `env` property that is a list of string pairs that represent environment variables mapped into the task process. +:::moniker range="azure-devops" + ```yml -task: AzureCLI@2 -displayName: Azure CLI -inputs: # Specific to each task -env: - ENV_VARIABLE_NAME: value - ENV_VARIABLE_NAME2: value +- task: AzureCLI@2 + displayName: Azure CLI + inputs: # Specific to each task + env: + ENV_VARIABLE_NAME: value + ENV_VARIABLE_NAME2: value ... ``` @@ -361,6 +325,37 @@ The following example runs the `script` step, which is a shortcut for the [Comma :::moniker-end +::: moniker range="< azure-devops" + +```yml +- task: Bash@3 + inputs: + targetType: # specific to each task + env: + ENV_VARIABLE_NAME: value + ENV_VARIABLE_NAME2: value + ... +``` + +The following example runs the `script` step, which is a shortcut for the [Bash@3](/azure/devops/pipelines/tasks/reference/bash-v3), followed by the equivalent task syntax. This example assigns a value to the `ENV_VARIABLE_NAME` environment variable and echoes the value. + +```yml +# Using the script shortcut syntax +- script: echo "This is " $ENV_VARIABLE_NAME + env: + ENV_VARIABLE_NAME: "my value" + displayName: 'echo environment variable' + +# Using the task syntax +- task: Bash@2 + inputs: + script: echo "This is " $ENV_VARIABLE_NAME + env: + ENV_VARIABLE_NAME: "my value" + displayName: 'echo environment variable' +``` + +::: moniker-end #### [Classic](#tab/classic/) @@ -368,10 +363,8 @@ You can work with environment variables using the **Environment Variables** sect :::image type="content" source="media/tasks/task-environment-variables.png" alt-text="Task environment variables."::: - * * * -

      Build tool installers (Azure Pipelines)

      Tool installers enable your build pipeline to install and control your dependencies. Specifically, you can: @@ -385,7 +378,7 @@ For example, you can set up your build pipeline to run and validate your app for ### Example: Test and validate your app on multiple versions of Node.js #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Create an azure-pipelines.yml file in your project's base directory with the following contents. @@ -395,10 +388,10 @@ pool: steps: # Node install -- task: NodeTool@0 +- task: UseNode@1 displayName: Node install inputs: - versionSpec: '12.x' # The version we're installing + version: '16.x' # The version we're installing # Write the installed version to the command line - script: which node ``` @@ -408,12 +401,6 @@ The [Node.js Tool Installer](/azure/devops/pipelines/tasks/reference/node-tool-v ::: moniker-end -::: moniker range="<= azure-devops-2019" - -YAML pipelines aren't available in TFS. - -::: moniker-end - #### [Classic](#tab/classic/) #### Tasks tab @@ -456,7 +443,7 @@ Add these tasks: #### Variables tab -On the [Variables tab](../build/variables.md) define this variable: +On the [Variables tab](../build/variables.md), define this variable: |Name|Value|Settable at queue time| |-|-|-| @@ -478,7 +465,7 @@ For a list of our tool installer tasks, see [Tool installer tasks](../tasks/inde On the organization settings page, you can disable Marketplace tasks, in-box tasks, or both. Disabling Marketplace tasks can help [increase security](../security/misc.md) of your pipelines. -If you disable both in-box and Marketplace tasks, only tasks you install using [`tfx`](https://www.npmjs.com/package/tfx-cli) will be available. +If you disable both in-box and Marketplace tasks, only tasks you install using [`tfx`](https://www.npmjs.com/package/tfx-cli) is available. ::: moniker-end diff --git a/docs/pipelines/process/template-expressions.md b/docs/pipelines/process/template-expressions.md index 2c0dcec967d..a0579088658 100644 --- a/docs/pipelines/process/template-expressions.md +++ b/docs/pipelines/process/template-expressions.md @@ -1,9 +1,8 @@ --- title: Template expressions -ms.custom: seodec18 description: How to use expressions in templates ms.topic: conceptual -ms.date: 06/30/2023 +ms.date: 10/25/2024 monikerRange: '>=azure-devops-2020' --- @@ -246,6 +245,37 @@ steps: - script: echo "this is a test" # runs when foo=test ``` +You can also set variables based on the values of other variables. In the following pipeline, `myVar` is used to set the value of `conditionalVar`. + + +```yaml +trigger: +- main + +pool: + vmImage: 'ubuntu-latest' + +variables: + - name: myVar + value: 'baz' + + - name: conditionalVar + ${{ if eq(variables['myVar'], 'foo') }}: + value: 'bar' + ${{ elseif eq(variables['myVar'], 'baz') }}: + value: 'qux' + ${{ else }}: + value: 'default' + +steps: +- script: echo "start" # always runs +- ${{ if eq(variables.conditionalVar, 'bar') }}: + - script: echo "the value of myVar is set in the if condition" # runs when myVar=foo +- ${{ if eq(variables.conditionalVar, 'qux') }}: + - script: echo "the value of myVar is set in the elseif condition" # runs when myVar=baz +``` + + ### Iterative insertion The `each` directive allows iterative insertion based on a YAML sequence (array) or mapping (key-value pairs). @@ -327,12 +357,4 @@ jobs: ### Escape a value -If you need to escape a value that literally contains `${{`, then wrap the value in an expression string. For example, `${{ 'my${{value' }}` or `${{ 'my${{value with a '' single quote too' }}` - -## Imposed limits - -Templates and template expressions can cause explosive growth to the size and complexity of a pipeline. -To help prevent runaway growth, Azure Pipelines imposes the following limits: -- No more than 100 separate YAML files may be included (directly or indirectly) -- No more than 20 levels of template nesting (templates including other templates) -- No more than 10 megabytes of memory consumed while parsing the YAML (in practice, this is typically between 600 KB - 2 MB of on-disk YAML, depending on the specific features used) +If you need to escape a value that literally contains `${{`, then wrap the value in an expression string. For example, `${{ 'my${{value' }}` or `${{ 'my${{value with a '' single quote too' }}` \ No newline at end of file diff --git a/docs/pipelines/process/template-parameters.md b/docs/pipelines/process/template-parameters.md index a4fc702d3c5..f61ad3f6673 100644 --- a/docs/pipelines/process/template-parameters.md +++ b/docs/pipelines/process/template-parameters.md @@ -1,10 +1,10 @@ --- title: Parameters and templateContext -ms.custom: seodec18 description: How to use parameters in templates ms.topic: conceptual -ms.date: 06/30/2023 -monikerRange: '>=azure-devops-2019' +ms.date: 10/25/2024 +monikerRange: "<=azure-devops" +ai-usage: ai-assisted --- # Template parameters @@ -13,8 +13,7 @@ monikerRange: '>=azure-devops-2019' You can specify parameters and their data types in a template and reference those parameters in a pipeline. With [templateContext](#use-templatecontext-to-pass-properties-to-templates), you can also pass properties to stages, steps, and jobs that are used as parameters in a template. -You can also [use parameters outside of templates](runtime-parameters.md). You can only use literals for parameter default values. - +You can also [use parameters outside of templates](runtime-parameters.md). You can only use literals for parameter default values. Learn more about [parameters in the YAML schema](/azure/devops/pipelines/yaml-schema/parameters-parameter). ### Passing parameters @@ -47,7 +46,7 @@ extends: ## Use templateContext to pass properties to templates -You can use `templateContext` to pass more properties to stages, steps, and jobs that are used as parameters in a template. Specifically, you can specify `templateContext` within the `jobList`, `deploymentList`, or `stageList` parameter data type. +You can use `templateContext` to pass more properties to [stages](/azure/devops/pipelines/yaml-schema/stages-stage), steps, and [jobs](/azure/devops/pipelines/yaml-schema/jobs-job) that are used as parameters in a template. Specifically, you can specify `templateContext` within the `jobList`, `deploymentList`, or `stageList` parameter data type. You can use `templateContext` to make it easier to set up environments when processing each job. By bundling a job and its environment properties object together, `templateContext` can help you have more maintainable and easier to understand YAML. @@ -65,17 +64,17 @@ parameters: type: jobList jobs: -- ${{ each testJob in parameters.testSet }}: - - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 200) }}: +- ${{ each testJob in parameters.testSet }}: # Iterate over each job in the 'testSet' parameter + - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 200) }}: # Check if the HTTP response is 200 - job: steps: - powershell: 'Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ | Format-Table -Property Title, pubDate' - ${{ testJob.steps }} - - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 500) }}: + - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 500) }}: # Check if the HTTP response is 500 - job: steps: - - powershell: 'Get-ChildItem -Path Env:\' - - ${{ testJob.steps }} + - powershell: 'Get-ChildItem -Path Env:\' # Run a PowerShell script to list environment variables + - ${{ testJob.steps }} # Include additional steps from the 'testJob' object ``` ```yaml @@ -87,17 +86,17 @@ pool: vmImage: ubuntu-latest extends: - template: testing-template.yml + template: testing-template.yml parameters: - testSet: - - job: positive_test + testSet: # Define the 'testSet' parameter to pass to the template + - job: positive_test # Define a job named 'positive_test' templateContext: - expectedHTTPResponseCode: 200 + expectedHTTPResponseCode: 200 # Set the expected HTTP response code to 200 for this job steps: - script: echo "Run positive test" - - job: negative_test + - job: negative_test # Define a job named 'negative_test' templateContext: - expectedHTTPResponseCode: 500 + expectedHTTPResponseCode: 500 # Set the expected HTTP response code to 500 for this job steps: - script: echo "Run negative test" ``` @@ -112,15 +111,15 @@ You can call different templates from a pipeline YAML depending on a condition. ```yml #azure-pipeline.yml parameters: -- name: experimentalTemplate +- name: experimentalTemplate displayName: 'Use experimental build process?' type: boolean default: false steps: -- ${{ if eq(parameters.experimentalTemplate, true) }}: +- ${{ if eq(parameters.experimentalTemplate, true) }}: # Check if 'experimentalTemplate' is true - template: experimental.yml -- ${{ if not(eq(parameters.experimentalTemplate, true)) }}: +- ${{ if not(eq(parameters.experimentalTemplate, true)) }}: # Check if 'experimentalTemplate' is not true - template: stable.yml ``` @@ -132,15 +131,15 @@ You can iterate through an object and print each string in the object. ```yaml parameters: -- name: listOfStrings +- name: listOfStrings type: object - default: + default: - one - two steps: -- ${{ each value in parameters.listOfStrings }}: - - script: echo ${{ value }} +- ${{ each value in parameters.listOfStrings }}: # Iterate over each value in the 'listOfStrings' parameter + - script: echo ${{ value }} # Output the current value in the iteration ``` Additionally, you can iterate through nested elements within an object. @@ -153,20 +152,44 @@ parameters: - fruitName: 'apple' colors: ['red','green'] - fruitName: 'lemon' - colors: ['yellow'] + colors: ['yellow'] steps: -- ${{ each fruit in parameters.listOfFruits }} : - - ${{ each fruitColor in fruit.colors}} : - - script: echo ${{ fruit.fruitName}} ${{ fruitColor }} +- ${{ each fruit in parameters.listOfFruits }} : # Iterate over each fruit in the 'listOfFruits' + - ${{ each fruitColor in fruit.colors}} : # Iterate over each color in the current fruit's colors + - script: echo ${{ fruit.fruitName}} ${{ fruitColor }} # Echo the current fruit's name and color ``` +You can also directly reference an object's keys and corresponding values. + +```yaml +parameters: + - name: myObject + type: object + default: + key1: 'value1' + key2: 'value2' + key3: 'value3' + +jobs: +- job: ExampleJob + displayName: 'Example object parameter job' + pool: + vmImage: 'ubuntu-latest' + steps: + - script: | + echo "Keys in myObject:" + echo "Key1: ${{ parameters.myObject.key1 }}" + echo "Key2: ${{ parameters.myObject.key2 }}" + echo "Key3: ${{ parameters.myObject.key3 }}" + displayName: 'Display object keys and values' +``` ### Required parameters -You can add a validation step at the beginning of your template to check for the parameters you require. +Pipelines automatically reports an error if a parameter is missing. You can add a validation step at the beginning of your template to check for the parameters you require and take appropriate action. -Here's an example that checks for the `solution` parameter using Bash (which enables it to work on any platform): +Here's an example that checks for the `solution` parameter using Bash: ```yaml # File: steps/msbuild.yml @@ -207,111 +230,3 @@ steps: ::: moniker-end -::: moniker range="azure-devops-2019" - -You can pass parameters to templates. -The `parameters` section defines what parameters are available in the template and their default values. -Templates are expanded just before the pipeline runs so that values surrounded by `${{ }}` are replaced by the parameters it receives from the enclosing pipeline. As a result, only [predefined variables](../build/variables.md) can be used in parameters. - -To use parameters across multiple pipelines, see how to create a [variable group](../library/variable-groups.md). - -### Job, stage, and step templates with parameters - -```yaml -# File: templates/npm-with-params.yml - -parameters: - name: '' # defaults for any parameters that aren't specified - vmImage: '' - -jobs: -- job: ${{ parameters.name }} - pool: - vmImage: ${{ parameters.vmImage }} - steps: - - script: npm install - - script: npm test -``` - -When you consume the template in your pipeline, specify values for -the template parameters. - -```yaml -# File: azure-pipelines.yml - -jobs: -- template: templates/npm-with-params.yml # Template reference - parameters: - name: Linux - vmImage: 'ubuntu-latest' - -- template: templates/npm-with-params.yml # Template reference - parameters: - name: macOS - vmImage: 'macOS-10.13' - -- template: templates/npm-with-params.yml # Template reference - parameters: - name: Windows - vmImage: 'windows-latest' -``` - -You can also use parameters with step or stage templates. -For example, steps with parameters: - -```yaml -# File: templates/steps-with-params.yml - -parameters: - runExtendedTests: 'false' # defaults for any parameters that aren't specified - -steps: -- script: npm test -- ${{ if eq(parameters.runExtendedTests, 'true') }}: - - script: npm test --extended -``` - -When you consume the template in your pipeline, specify values for -the template parameters. - -```yaml -# File: azure-pipelines.yml - -steps: -- script: npm install - -- template: templates/steps-with-params.yml # Template reference - parameters: - runExtendedTests: 'true' -``` - -> [!Note] -> Scalar parameters are always treated as strings. -> For example, `eq(parameters['myparam'], true)` will almost always return `true`, even if the `myparam` parameter is the word `false`. -> Non-empty strings are cast to `true` in a Boolean context. -> That [expression](expressions.md) could be rewritten to explicitly compare strings: `eq(parameters['myparam'], 'true')`. - -Parameters aren't limited to scalar strings. -As long as the place where the parameter expands expects a mapping, the parameter can be a mapping. -Likewise, sequences can be passed where sequences are expected. -For example: - -```yaml -# azure-pipelines.yml -jobs: -- template: process.yml - parameters: - pool: # this parameter is called `pool` - vmImage: ubuntu-latest # and it's a mapping rather than a string - - -# process.yml -parameters: - pool: {} - -jobs: -- job: build - pool: ${{ parameters.pool }} -``` - -::: moniker-end diff --git a/docs/pipelines/process/templates.md b/docs/pipelines/process/templates.md index 9a1391229d7..5de413d7ad5 100644 --- a/docs/pipelines/process/templates.md +++ b/docs/pipelines/process/templates.md @@ -1,49 +1,52 @@ --- -title: Templates -ms.custom: seodec18 -description: How to reuse pipelines through templates +title: How to use YAML templates for reusable and secure pipelines +description: Learn how to create reusable YAML pipeline templates to streamline and secure your CI/CD processes. ms.assetid: 6f26464b-1ab8-4e5b-aad8-3f593da556cf ms.topic: conceptual -ms.date: 06/30/2023 -monikerRange: ">=azure-devops-2019" +ms.date: 02/26/2025 +monikerRange: "<=azure-devops" zone_pivot_groups: template-type +ai-usage: ai-assisted --- -# Template usage reference +# Use YAML templates in pipelines for reusable and secure processes [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] ::: moniker range=">=azure-devops-2020" -Templates let you define reusable content, logic, and parameters in YAML pipelines. To work with templates effectively, you'll need to have a basic understanding of [Azure Pipelines key concepts](../get-started/key-pipelines-concepts.md) such as stages, steps, and jobs. +Templates let you define reusable content, logic, and parameters in YAML pipelines. To work with templates effectively, you need to have a basic understanding of [Azure Pipelines key concepts](../get-started/key-pipelines-concepts.md) such as stages, steps, and jobs. Templates can help you speed up development. For example, you can have a series of the same tasks in a template and then include the template multiple times in different stages of your YAML pipeline. -Templates can also help you secure your pipeline. When a template controls what is allowed in a pipeline, the template defines logic that another file must follow. For example, you may want to restrict what tasks are allowed to run. For that scenario, you can use template to prevent someone from successfully running a task that violates your organization's security policies. +Templates can also help you secure your pipeline. When a template controls what is allowed in a pipeline, the template defines logic that another file must follow. For example, you might want to restrict what tasks are allowed to run. For that scenario, you can use template to prevent someone from successfully running a task that violates your organization's security policies. There are two types of templates: includes and extends. -- **Includes templates** let you insert reusable content with a template. If a template is used to include content, it functions like an include directive in many programming languages. Content from one file is inserted into another file. -- **Extends template** control what is allowed in a pipeline. When an extends template controls what is allowed in a pipeline, the template defines logic that another file must follow. +- **Includes templates** let you insert reusable content with a template. If a template is used to include content, it functions like an include directive in many programming languages. Content from template is inserted into the pipeline or template that includes it. +- **Extends templates** let you control what is allowed in a pipeline. When an extends template controls what is allowed in a pipeline, the template defines logic that a pipeline must follow. For example, an extends template can be used in the context of extending a pipeline to perform stages or jobs. To take full advantage of templates, you should also use [template expressions](template-expressions.md) and [template parameters](template-parameters.md). -::: moniker-end +### Imposed limits on template updates -::: moniker range="azure-devops-2019" +Templates and template expressions can cause explosive growth to the size and complexity of a pipeline. +To help prevent runaway growth, Azure Pipelines imposes the following limits: -Use templates to define your logic once and then reuse it several times. Templates combine the content of multiple YAML files into a single pipeline. You can pass parameters into a template from your parent pipeline. +- No more than 100 separate YAML files may be included (directly or indirectly) +- No more than 100 levels of template nesting (templates including other templates) +- No more than 20 megabytes of memory consumed while parsing the YAML (in practice, this is typically between 600 KB - 2 MB of on-disk YAML, depending on the specific features used) ::: moniker-end ::: zone pivot="templates-extends" -::: moniker range=">=azure-devops-2020" - ## Extend from a template +::: moniker range=">=azure-devops-2020" + To increase security, you can enforce that a pipeline extends from a particular template. The file `start.yml` defines the parameter `buildSteps`, which is then used in the pipeline `azure-pipelines.yml`. -In `start.yml`, if a `buildStep` gets passed with a script step, then it is rejected and the pipeline build fails. +In `start.yml`, if a `buildStep` gets passed with a script step, then it's rejected and the pipeline build fails. When extending from a template, you can increase security by adding a [required template approval](../security/templates.md#set-required-templates). ```yaml @@ -97,7 +100,7 @@ extends: - script: echo "Script Test" ``` -### Extend from a template with resources +## Extend from a template with resources You can also use `extends` to extend from a template in your Azure pipeline that contains resources. @@ -136,8 +139,6 @@ You can copy content from one YAML and reuse it in a different YAML. Copying con > [!NOTE] > Template files need to exist on your filesystem at the start of a pipeline run. You can't reference templates in an artifact. - - ```yaml # File: templates/include-npm-steps.yml @@ -163,8 +164,7 @@ jobs: - template: templates/include-npm-steps.yml # Template reference ``` - -#### Step reuse +#### Reuse steps across multiple jobs You can insert a template to reuse one or more steps across several jobs. In addition to the steps from the template, each job can define more steps. @@ -201,7 +201,7 @@ jobs: - script: echo This step runs after the template's steps. ``` -#### Job reuse +#### Reuse jobs across multiple templates Much like steps, jobs can be reused with templates. @@ -255,7 +255,7 @@ jobs: - template: templates/jobs.yml # Template reference ``` -#### Stage reuse +#### Reuse stages across multiple templates Stages can also be reused with templates. @@ -295,12 +295,17 @@ stages: - task: Npm@1 inputs: command: 'install' -- template: templates/stages1.yml -- template: templates/stages2.yml +- template: templates/stages1.yml # Template reference +- template: templates/stages2.yml # Template reference ``` +#### Add parameters to job, stage, and step templates + +In the following templates: -#### Job, stage, and step templates with parameters +- `templates/npm-with-params.yml` defines two parameters: `name` and `vmImage` and creates a job with the name parameter for the job name and the vmImage parameter for the VM image. +- The pipeline (`azure-pipelines.yml`) references the template three times, each with different parameter values referring to the operating system and VM image names. +- The built pipeline runs on a different VM image and named according to the specified OS. Each job performs npm install and npm test steps. ```yaml # File: templates/npm-with-params.yml @@ -342,9 +347,57 @@ jobs: name: Windows vmImage: 'windows-latest' ``` +**Stage templates with multiple parameters** + +In the following templates: +- The `stage-template.yml` template defines four parameters: `stageName`, `jobName`, `vmImage`, and `scriptPath`, all of type string. The template creates a stage using the `stageName` parameter to set the stage name, defines a job with `jobName`, and includes a step to run a script. +- The pipeline, `azure-pipeline.yml`, then dynamically define stages and jobs using parameters and runs a job that executes a script, `build-script.sh`. + +```yaml +# stage-template.yml + +parameters: + - name: stageName + type: string + - name: jobName + type: string + - name: vmImage + type: string + - name: scriptPath + type: string + +stages: + - stage: ${{ parameters.stageName }} + jobs: + - job: ${{ parameters.jobName }} + pool: + vmImage: ${{ parameters.vmImage }} + steps: + - script: ./${{ parameters.scriptPath }} +``` + +```yaml +# azure-pipelines.yml +trigger: +- main + +stages: +- template: stage-template.yml + parameters: + stageName: 'BuildStage' + jobName: 'BuildJob' + scriptPath: 'build-script.sh' # replace with script in your repository + vmImage: 'ubuntu-latest' +``` + +**Templates with steps and parameters** You can also use parameters with step or stage templates. -For example, steps with parameters: + +In the following templates: + +- The template (`templates/steps-with-params.yml`) defines a parameter named `runExtendedTests` with a default value of false. +- The pipeline (`azure-pipelines.yml`) runs `npm test` and `npm test --extended` because the `runExtendedTests` parameter is true. ```yaml # File: templates/steps-with-params.yml @@ -392,7 +445,6 @@ jobs: pool: # this parameter is called `pool` vmImage: ubuntu-latest # and it's a mapping rather than a string - # process.yml parameters: - name: 'pool' @@ -404,7 +456,6 @@ jobs: pool: ${{ parameters.pool }} ``` - ## Variable reuse Variables can be defined in one YAML and included in another template. This could be useful if you want to store all of your variables in one file. If you're using a template to include variables in a pipeline, the included template can only be used to define variables. You can use steps and more complex logic when you're [extending from a template](#extend-from-a-template). @@ -427,7 +478,7 @@ variables: steps: - script: echo My favorite vegetable is ${{ variables.favoriteVeggie }}. ``` -### Variable templates with parameter +### Variable templates with parameters You can pass parameters to variables with templates. In this example, you're passing the `DIRECTORY` parameter to a `RELEASE_COMMAND` variable. @@ -475,9 +526,87 @@ stages: :::zone-end +## Extend from a template and use an include template with variables + +One common scenario is to have a pipeline with stages for development, testing, and production that uses both an includes template for variables and an extends template for stages and jobs. + +In the following example, `variables-template.yml` defines a set of virtual machine variables that are then used in `azure-pipeline.yml`. + +```yaml +# variables-template.yml + +variables: +- name: devVmImage + value: 'ubuntu-latest' +- name: testVmImage + value: 'ubuntu-latest' +- name: prodVmImage + value: 'ubuntu-latest' +``` +The following file, `stage-template.yml` defines a reusable stage configuration with three parameters (`name`, `vmImage`, `steps`) and a job named `Build`. + +```yaml +# stage-template.yml +parameters: +- name: name + type: string + default: '' +- name: vmImage + type: string + default: '' +- name: steps + type: stepList + default: [] + +stages: +- stage: ${{ parameters.name }} + jobs: + - job: Build + pool: + vmImage: ${{ parameters.vmImage }} + steps: ${{ parameters.steps }} +``` + +The following pipeline, `azure-pipelines.yml`, imports variables from `variables-template.yml`, and then uses the `stage-template.yml` template for each stage. Each stage (Dev, Test, Prod) is defined with the same template but with different parameters, leading to consistency across stages while allowing for customization. The 'Prod' stage includes an environment variable as an example of something you might use for authentication. To learn more about defining parameters, see [Template parameters](template-parameters.md). + +```yaml +# azure-pipelines.yml +trigger: +- main + +variables: +- template: variables-template.yml + +stages: +- template: stage-template.yml + parameters: + name: Dev + vmImage: ${{ variables.devVmImage }} + steps: + - script: echo "Building in Dev" +- template: stage-template.yml + parameters: + name: Test + vmImage: ${{ variables.testVmImage }} + steps: + - script: echo "Testing in Test" +- template: stage-template.yml + parameters: + name: Prod + vmImage: ${{ variables.prodVmImage }} + steps: + - script: echo "Deploying to Prod" + env: + SYSTEM_ACCESSTOKEN: $(System.AccessToken) +``` + ## Reference template paths -Template paths should be relative to the file that does the including. Here's an example nested hierarchy. +Template paths can be an absolute path within the repository or relative to the file that does the including. + +To use an absolute path, the template path must start with a `/`. All other paths are considered relative. + +Here's an example nested hierarchy. ``` | @@ -515,7 +644,15 @@ steps: - template: dir2/fileC.yml ``` -### Use other repositories +Alternatively, `fileB.yml` could refer to `fileA.yml` and `fileC.yml` using absolute paths like this. + +```yaml +steps: +- template: /fileA.yml +- template: /dir1/dir2/fileC.yml +``` + +### Store templates in other repositories You can keep your templates in other repositories. For example, suppose you have a core pipeline that you want all of your app pipelines to use. @@ -526,7 +663,7 @@ You can put the template in a core repo and then refer to it from each of your a # File: common.yml parameters: - name: 'vmImage' - default: 'ubuntu 16.04' + default: 'ubuntu-22.04' type: string jobs: @@ -571,9 +708,9 @@ jobs: vmImage: 'windows-latest' ``` -For `type: github`, `name` is `/` as in the examples above. +For `type: github`, `name` is `/` as in the preceding example. For `type: git` (Azure Repos), `name` is `/`. -If that project is in a separate Azure DevOps organization, you'll need to configure a [service connection](../library/service-endpoints.md#azure-repos) of type `Azure Repos/Team Foundation Server` with access to the project and include that in YAML: +If that project is in a separate Azure DevOps organization, you need to configure a [service connection](../library/service-endpoints.md#azure-repos) of type `Azure Repos/Team Foundation Server` with access to the project and include that in YAML: ```yaml resources: @@ -586,7 +723,7 @@ jobs: ``` Repositories are resolved only once, when the pipeline starts up. -After that, the same resource is used for the duration of the pipeline. +After that, the same resource is used during the pipeline run. Only the template files are used. Once the templates are fully expanded, the final pipeline runs as if it were defined entirely in the source repo. This means that you can't use scripts from the template repo in your pipeline. @@ -596,9 +733,20 @@ The `refs` are either branches (`refs/heads/`) or tags (`refs/tags/` If you want to pin a specific commit, first create a tag pointing to that commit, then pin to that tag. > [!NOTE] -> If no `ref` is specified, the pipeline will default to using `refs/heads/main`. +> If no `ref` is specified, the pipeline defaults to using `refs/heads/main`. + +You can also pin to a specific commit in Git with the SHA value for a repository resource. The SHA value is a 40-character checksum hash that uniquely identifies the commit. + +```yaml +resources: + repositories: + - repository: templates + type: git + name: Contoso/BuildTemplates + ref: 1234567890abcdef1234567890abcdef12345678 +``` -You may also use `@self` to refer to the repository where the original pipeline was found. +You can also use `@self` to refer to the repository where the original pipeline was found. This is convenient for use in `extends` templates if you want to refer back to contents in the extending pipeline's repository. For example: @@ -639,16 +787,14 @@ jobs: steps: [] ``` - ## FAQ ### How can I use variables inside of templates? -There are times when it may be useful to set parameters to values based on variables. Parameters are expanded early in processing a [pipeline run](runs.md) so not all variables are available. To see what predefined variables are available in templates, see [Use predefined variables](../build/variables.md). +There are times when it's useful to set parameters to values based on variables. Parameters are expanded early in processing a [pipeline run](runs.md) so not all variables are available. To see what predefined variables are available in templates, see [Use predefined variables](../build/variables.md). In this example, the predefined variables `Build.SourceBranch` and `Build.Reason` are used in conditions in template.yml. - ```yaml # File: azure-pipelines.yml trigger: @@ -669,6 +815,3 @@ steps: - script: echo I run only if Build.Reason = IndividualCI - script: echo I run after the conditions ``` - - - diff --git a/docs/pipelines/process/variables.md b/docs/pipelines/process/variables.md index cf5d4d05f92..4aa8f947021 100644 --- a/docs/pipelines/process/variables.md +++ b/docs/pipelines/process/variables.md @@ -1,10 +1,11 @@ --- title: Define variables -ms.custom: seodec18, contperf-fy20q4, devx-track-azurecli +ms.custom: devx-track-azurecli description: Variables are name-value pairs defined by you for use in a pipeline. You can use variables as inputs to tasks and in your scripts. ms.topic: conceptual ms.assetid: 4751564b-aa99-41a0-97e9-3ef0c0fce32a -ms.date: 02/16/2023 +ms.date: 10/03/2024 +ai-usage: ai-assisted monikerRange: '<= azure-devops' --- @@ -13,11 +14,10 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -[!INCLUDE [temp](../includes/concept-rename-note.md)] - Variables give you a convenient way to get key bits of data into various parts of the pipeline. The most common use of variables is to define a value that you can then use in your pipeline. All variables are strings and are mutable. The value of a variable can change from run to run or job to job of your pipeline. -When you define the same variable in multiple places with the same name, the most locally scoped variable wins. So, a variable defined at the job level can override a variable set at the stage level. A variable defined at the stage level overrides a variable set at the pipeline root level. A variable set in the pipeline root level overrides a variable set in the Pipeline settings UI. +When you define the same variable in multiple places with the same name, the most locally scoped variable takes precedence. So, a variable defined at the job level can override a variable set at the stage level. A variable defined at the stage level overrides a variable set at the pipeline root level. A variable set in the pipeline root level overrides a variable set in the Pipeline settings UI. +To learn more how to work with variables defined at the job, stage, and root level, see [Variable scope](#variable-scopes). You can use variables with [expressions](expressions.md) to conditionally assign values and further customize pipelines. @@ -37,12 +37,11 @@ You can [use a variable group](../library/variable-groups.md) to make variables Use [templates](templates.md) to define variables in one file that are used in multiple pipelines. - ### User-defined multi-line variables Azure DevOps supports multi-line variables but there are a few limitations. -Downstream components such as pipeline tasks may not handle the variable values correctly. +Downstream components such as pipeline tasks might not handle the variable values correctly. Azure DevOps won't alter user-defined variable values. Variable values need to be formatted correctly before being passed as multi-line variables. When formatting your variable, avoid special characters, don't use restricted names, and make sure you use a line ending format that works for the operating system of your agent. @@ -52,7 +51,10 @@ Azure DevOps never alters variable values, even if you provide unsupported forma ## System variables -In addition to user-defined variables, Azure Pipelines has system variables with predefined values. If you're using YAML or classic build pipelines, see [predefined variables](../build/variables.md) for a comprehensive list of system variables. +In addition to user-defined variables, Azure Pipelines has system variables with predefined values. For example, the predefined variable [Build.BuildId](../build/variables.md#build-variables-devops-services) gives the ID of each build and can be used to identify different pipeline runs. You can use the `Build.BuildId` variable in scripts or tasks when you need to a unique value. + +If you're using YAML or classic build pipelines, see [predefined variables](../build/variables.md) for a comprehensive list of system variables. + If you're using classic release pipelines, see [release variables](../release/variables.md). System variables get set with their current value when you run the pipeline. Some variables are set automatically. As a pipeline author or end user, you change the value of a system variable before the pipeline runs. @@ -65,7 +67,7 @@ Environment variables are specific to the operating system you're using. They're On UNIX systems (macOS and Linux), environment variables have the format `$NAME`. On Windows, the format is `%NAME%` for batch and `$env:NAME` in PowerShell. -System and user-defined variables also get injected as environment variables for your platform. When variables convert into environment variables, variable names become uppercase, and periods turn into underscores. For example, the variable name `any.variable` becomes the variable name `$ANY_VARIABLE`. +System and user-defined variables (except secret variables) also get injected as environment variables for your platform. When variables convert into environment variables, variable names become uppercase, and periods turn into underscores. For example, the variable name `any.variable` becomes the variable name `$ANY_VARIABLE`. There are [variable naming restrictions](#variable-naming-restrictions) for environment variables (example: you can't use `secret` at the start of a variable name). @@ -102,7 +104,7 @@ steps: ### Macro syntax variables Most documentation examples use macro syntax (`$(var)`). Macro syntax is designed to interpolate variable values into task inputs and into other variables. -Variables with macro syntax get processed before a task executes during runtime. Runtime happens [after template expansion](runs.md#process-the-pipeline). When the system encounters a macro expression, it replaces the expression with the contents of the variable. If there's no variable by that name, then the macro expression does not change. For example, if `$(var)` can't be replaced, `$(var)` won't be replaced by anything. +Variables with macro syntax get processed before a task executes during runtime. Runtime happens [after template expansion](runs.md#process-the-pipeline). When the system encounters a macro expression, it replaces the expression with the contents of the variable. If there's no variable by that name, then the macro expression doesn't change. For example, if `$(var)` can't be replaced, `$(var)` won't be replaced by anything. Macro syntax variables remain unchanged with no value because an empty value like `$()` might mean something to the task you're running and the agent shouldn't assume you want that value replaced. For example, if you use `$(foo)` to reference variable `foo` in a Bash task, replacing all `$()` expressions in the input to the task could break your Bash scripts. @@ -143,16 +145,16 @@ Runtime expression variables are only expanded when they're used for a value, no ### What syntax should I use? -Use macro syntax if you're providing input for a task. +Use macro syntax if you're providing a secure string or a [predefined variable](/azure/devops/pipelines/build/variables) input for a task. Choose a runtime expression if you're working with [conditions](conditions.md) and [expressions](expressions.md). However, don't use a runtime expression if you don't want your empty variable to print (example: `$[variables.var]`). For example, if you have conditional logic that relies on a variable having a specific value or no value. In that case, you should use a macro expression. -If you're defining a variable in a template, use a template expression. +Typically a template variable is the standard to use. By leveraging template variables, your pipeline will fully inject the variable value into your pipeline at pipeline compilation. This is helpful when attempting to debug pipelines. You can download the log files and evaluate the fully expanded value that is being substituted in. Since the variable is substituted in, you shouldn't leverage template syntax for sensitive values. ## Set variables in pipeline #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" In the most common case, you set the variables and use them within the YAML file. This allows you to track changes to the variable in your version control system. You can also define variables in the pipeline settings UI (see the Classic tab) and reference them in your YAML. @@ -233,14 +235,18 @@ value2 value ``` - ### Specify variables In the preceding examples, the `variables` keyword is followed by a list of key-value pairs. The keys are the variable names and the values are the variable values. -There's another syntax, useful when you want to use [variable templates](templates.md) or [variable groups](../library/variable-groups.md). Use this syntax at the root level of a pipeline. +There's another syntax, useful when you want to use [templates](templates.md) for variables or [variable groups](../library/variable-groups.md). + +With [templates](templates.md#variable-reuse), variables can be defined in one YAML and included in another YAML file. +Variable groups are a set of variables that you can use across multiple pipelines. They allow you to manage and organize variables that are common to various stages in one place. + +Use this syntax for variable templates and variable groups at the root level of a pipeline. In this alternate syntax, the `variables` keyword takes a list of variable specifiers. The variable specifiers are `name` for a regular variable, `group` for a variable group, and `template` to include a variable template. @@ -256,16 +262,12 @@ variables: # a reference to a variable template - template: myvariabletemplate.yml ``` - Learn more about [variable reuse with templates](templates.md). ### Access variables through the environment [!INCLUDE [temp](includes/access-variables-through-env.md)] -::: moniker-end -::: moniker range="< azure-devops-2019" -YAML isn't supported in TFS. ::: moniker-end #### [Classic](#tab/classic/) @@ -292,11 +294,11 @@ Using the Azure DevOps CLI, you can create and update variables for the pipeline ### Prerequisites -- You must have installed the Azure DevOps CLI extension as described in [Get started with Azure DevOps CLI](../../cli/index.md). +- You've installed the Azure DevOps CLI extension as described in [Get started with Azure DevOps CLI](../../cli/index.md). - Sign into Azure DevOps using `az login`. - For the examples in this article, set the default organization using `az devops configure --defaults organization=YourOrganizationURL`. - + ### Create a variable @@ -336,7 +338,7 @@ Name Allow Override Is Secret Value Configuration False False platform ``` - + ### Update a variable @@ -380,7 +382,7 @@ Name Allow Override Is Secret Value Configuration False False config.debug ``` - + ### Delete a variable @@ -420,17 +422,29 @@ Deleted variable 'Configuration' successfully. * * *

      Set secret variables

      +> [!TIP] +> Secret variables aren't automatically exported as environment variables. To use secret variables in your scripts, explicitly map them to environment variables. For more information, see [Set secret variables](set-secret-variables.md). + #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Don't set secret variables in your YAML file. Operating systems often log commands for the processes that they run, and you wouldn't want the log to include a secret that you passed in as an input. Use the script's environment or map the variable within the `variables` block to pass secrets to your pipeline. -You need to set secret variables in the pipeline settings UI for your pipeline. These variables are scoped to the pipeline where they are set. You can also set [secret variables in variable groups](#reference-secret-variables-in-variable-groups). +[!INCLUDE [secrets masked](./includes/masked-secrets.md)] + +You need to set secret variables in the pipeline settings UI for your pipeline. These variables are scoped to the pipeline where they're set. You can also set [secret variables in variable groups](#reference-secret-variables-in-variable-groups). [!INCLUDE [temp](includes/set-secrets.md)] -The following example shows how to use a secret variable called `mySecret` in PowerShell and Bash scripts. -Unlike a normal pipeline variable, there's no environment variable called `MYSECRET`. +The following example shows how to map and use a secret variable called `mySecret` in PowerShell and Bash scripts. Two global variables are defined. `GLOBAL_MYSECRET` is assigned the value of a secret variable `mySecret`, and `GLOBAL_MY_MAPPED_ENV_VAR` is assigned the value of a non-secret variable `nonSecretVariable`. Unlike a normal pipeline variable, there's no environment variable called `MYSECRET`. + +The PowerShell task runs a script to print the variables. + +- `$(mySecret)`: This is a direct reference to the secret variable and works. +- `$env:MYSECRET`: This attempts to access the secret variable as an environment variable, which does not work because secret variables are not automatically mapped to environment variables. +- `$env:GLOBAL_MYSECRET`: This attempts to access the secret variable through a global variable, which also does not work because secret variables cannot be mapped this way. +- `$env:GLOBAL_MY_MAPPED_ENV_VAR`: This accesses the non-secret variable through a global variable, which works. +- `$env:MY_MAPPED_ENV_VAR`: This accesses the secret variable through a task-specific environment variable, which is the recommended way to map secret variables to environment variables. ```yaml variables: @@ -457,7 +471,6 @@ steps: env: MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable - ``` The output from both tasks in the preceding script would look like this: @@ -491,10 +504,9 @@ steps: vmsAdminPassword: $(VMS_PASS) ``` - ### Reference secret variables in variable groups -This example shows how to reference a variable group in your YAML file, and also add variables within the YAML. There are two variables used from the variable group: `user` and `token`. The `token` variable is secret, and is mapped to the environment variable `$env:MY_MAPPED_TOKEN` so that it can be referenced in the YAML. +This example shows how to reference a variable group in your YAML file, and also how to add variables within the YAML. There are two variables used from the variable group: `user` and `token`. The `token` variable is secret, and is mapped to the environment variable `$env:MY_MAPPED_TOKEN` so that it can be referenced in the YAML. This YAML makes a REST call to retrieve a list of releases, and outputs the result. @@ -532,9 +544,6 @@ steps: > [!IMPORTANT] > By default with GitHub repositories, secret variables associated with your pipeline aren't made available to pull request builds of forks. For more information, see [Contributions from forks](../repos/github.md#contributions-from-forks). -::: moniker-end -::: moniker range="< azure-devops-2019" -YAML isn't supported in TFS. ::: moniker-end #### [Classic](#tab/classic/) @@ -542,7 +551,6 @@ YAML isn't supported in TFS. Each task that needs to use the secret as an environment variable does remapping. If you want to use a secret variable called `mySecret` from a script, use the `Environment` section of the scripting task's input variables. Set the environment variable name to `MYSECRET`, and set the value to `$(mySecret)`. - > [!IMPORTANT] > By default with GitHub repositories, secret variables associated with your pipeline aren't made available to pull request builds of forks. For more information, see [Contributions from forks](../repos/github.md#contributions-from-forks). @@ -565,17 +573,8 @@ To share variables across multiple pipelines in your project, use the web interf Some tasks define output variables, which you can consume in downstream steps, jobs, and stages. In YAML, you can access variables across jobs and stages by using [dependencies](expressions.md#dependencies). -When referencing matrix jobs in downstream tasks, you'll need to use a different syntax. See [Set a multi-job output variable](#set-a-multi-job-output-variable). +When referencing matrix jobs in downstream tasks, you'll need to use a different syntax. See [Set a multi-job output variable](#set-a-multi-job-output-variable). You also need to use a different syntax for variables in deployment jobs. See [Support for output variables in deployment jobs](deployment-jobs.md#support-for-output-variables). -::: moniker-end - -::: moniker range="azure-devops-2019" -Some tasks define output variables, which you can consume in downstream steps and jobs within the same stage. -In YAML, you can access variables across jobs by using [dependencies](expressions.md#dependencies). -::: moniker-end - -::: moniker range="= azure-devops-2020' ---- - -# Publish Pipeline Artifacts - -[!INCLUDE [version-gt-eq-2020](../includes/version-gt-eq-2020.md)] - -Azure Artifacts enable developers to store and manage their packages and control who they want to share it with. Pipeline Artifacts are generated after you build your application. The output can then be deployed or consumed by another job in your pipeline. - -## Publish Artifacts - -> [!NOTE] -> Publish pipeline artifacts is not supported in release pipelines. It is only supported in build pipelines, multi-stage pipelines, and yaml pipelines. - -You can publish your Artifacts at any stage of your pipeline using YAML or the classic editor. You won't be billed for storing your Pipeline Artifacts or using Pipeline caching. - -# [YAML](#tab/yaml) - -```yaml -steps: -- task: PublishPipelineArtifact@1 - inputs: - targetPath: '$(Pipeline.Workspace)' - artifactType: 'pipeline' - artifactName: 'drop' -``` - -- **targetPath**: Path to the folder or file you want to publish. (Required) -- **artifactType**: Artifacts publish location. (Required). Options: pipeline, filepath. Default value: pipeline. -- **artifactName**: Name of your Artifact. (Optional). - -# [Classic](#tab/classic) - -1. From your pipeline definition, select + to add a new task. - -1. Search for the **Publish Pipeline Artifacts** task :::image type="icon" source="tasks/utility/media/publish-pipeline-artifact.png" border="false"::: and then select **Add** to add it to your pipeline. - -1. Fill out the following fields: - - **Display name**: the task display name. - - **File or directory path**: the path of the file or directory to publish. - - **Artifact name**: name of the Artifact to publish. - - **Artifact publish location**: choose whether to store the Artifact in Azure Pipelines, or to copy it to a file share. - - :::image type="content" source="./media/publish-pipeline-artifacts.png" alt-text="Publish Pipeline Artifacts task"::: - ---- - -::: moniker range=" azure-devops" - -## Publish Artifacts from the command line - -If you want to manually publish your Artifact, run the following command in an elevated command prompt: - -```azurecli -az pipelines runs artifact upload --artifact-name your_artifact_name --path your_path_to_publish --run-id '' -``` - -::: moniker-end - -## View published Artifacts - -When your pipeline run is completed, you can view or download your published Artifact as follows - -1. Select your pipeline run, and then select the **Summary** tab. - -1. Select the published Artifact in the related section. - - :::image type="content" source="./media/published-artifact.png" alt-text="View published Artifact"::: - -1. Expand the drop folder and find your Artifact. - - :::image type="content" source="./media/drop-artifacts.png" alt-text="View the drop content"::: - -1. Download your pipeline Artifact and explore its content. - -## Related articles - -- [Releases in Azure Pipelines](/rest/api/azure/devops/release/releases) -- [Multi-stage release pipeline](./release/define-multistage-release-process.md) -- [Deploy from multiple branches](./release/deploy-multiple-branches.md) diff --git a/docs/pipelines/release/_img/azure-rm-endpoint/azure-rm-approvals-checks.png b/docs/pipelines/release/_img/azure-rm-endpoint/azure-rm-approvals-checks.png new file mode 100644 index 00000000000..25873e7c98d Binary files /dev/null and b/docs/pipelines/release/_img/azure-rm-endpoint/azure-rm-approvals-checks.png differ diff --git a/docs/pipelines/release/approvals/approvals.md b/docs/pipelines/release/approvals/approvals.md index 1ee4ee4f546..6f27d876403 100644 --- a/docs/pipelines/release/approvals/approvals.md +++ b/docs/pipelines/release/approvals/approvals.md @@ -1,11 +1,11 @@ --- title: Control deployments with release approvals -ms.custom: seodec18, engagement-fy23 -description: Understand release approvals in Azure Pipelines +ms.custom: engagement-fy23 +description: Understand release approvals in Azure Pipelines. ms.assetid: 3725541F-FC36-42E2-8153-21D2F9CA755B ms.topic: conceptual -ms.author: shashban -author: azooinmyluggage +ms.author: sandrica +author: silviuandrica ms.date: 12/20/2022 monikerRange: '<= azure-devops' --- @@ -14,42 +14,45 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -With Azure release pipelines, You can enable manual deployment approvals for each stage in a release pipeline to control your deployment workflow. When using approvals in your pipeline, the deployment is paused at each point where approval is required until the specified approver grants approval, rejects the release, or reassigns the approval to another user. +With Azure release pipelines, you can enable manual deployment approvals for each stage in a release pipeline to control your deployment workflow. When you use manual approvals, the deployment is paused at each point where approval is required until the specified approver grants approval, rejects the release, or reassigns the approval to another user. ## Deployment approvals -You can set up approvals at the start of a stage (pre-deployment approvals), at the end of a stage (post-deployment approvals), or for both. +You can set up approvals at the start of a stage (predeployment approvals), at the end of a stage (post-deployment approvals), or for both. -### Pre-deployment approvals +### Predeployment approvals -1. Select your classic release pipeline, and then select the **Pre-deployment conditions** icon and then click the toggle button to enable **Pre-deployment approvals**. +1. Select your classic release pipeline, and then select the **Pre-deployment conditions** icon and then select the toggle button to enable **Pre-deployment approvals**. 1. Add your **Approvers** and then choose the **Timeout** period. You can add multiple users or groups to the list of approvers. You can also select your **Approval policies** depending on your deployment workflow. - :::image type="content" source="media/pre-deployment-approvals.png" alt-text="A screenshot showing how to set up pre-deployment approvals."::: + :::image type="content" source="media/pre-deployment-approvals.png" alt-text="A screenshot showing how to set up predeployment approvals."::: + +> [!NOTE] +> Azure DevOps doesn’t expand Azure Active Directory groups when delivering Notifications. If you must use Azure AD groups, we suggest that you add an email alias as an explicit recipient to your subscription and associate that alias with your AD group, if applicable to your scenario. ### Post-deployment approvals -1. Select your classic release pipeline, and then select the **Post-deployment conditions** icon and then click the toggle button to enable **Post-deployment approvals**. +1. Select your classic release pipeline, and then select the **Post-deployment conditions** icon and then select the toggle button to enable **Post-deployment approvals**. 1. Add your **Approvers** and then choose the **Timeout** period. You can add multiple users or groups to the list of approvers. You can also select your **Approval policies** depending on your deployment workflow. :::image type="content" source="media/post-deployment-approvals.png" alt-text="A screenshot showing how to set up post-deployment approvals."::: > [!NOTE] -> Deployment approvers must have **View releases** [permissions](../../policies/permissions.md#set-release-permissions). +> Deployment approvers must have **View releases** [permissions](../../policies/permissions.md#release-pipeline-permissions). - **Approvers**: When a group is specified as approvers, only one user from that group is needed to approve, resume, or reject deployment. - **Timeout**: -If no approval is granted within the **Timeout** period, the deployment will be rejected. +If no approval is granted within the **Timeout** period, the deployment is rejected. - **Approval policies**: - For added security, you can add this approval policy to prevent the user who requested the release from approving it. If you're experimenting with approvals, uncheck this option so that you can approve or reject your own deployments. See [How are the identity variables set?](../../build/variables.md#how-are-the-identity-variables-set) to learn more about identity variables. - - This policy lets you enforce multi-factor authentication in the release approval flow. If this policy is checked it will prompt approvers to re-sign in before approving releases. This feature is only available in Azure DevOps Services for Azure Active Directory backed accounts only. - - Reduce user workload by automatically approving subsequent prompts if the specified user has already approved the deployment to a previous stage in the pipeline (applies to pre-deployment approvals only). + - This policy lets you enforce multifactor authentication in the release approval flow. If this policy is checked, it prompts approvers to re-sign in before approving releases. This feature is only available in Azure DevOps Services for Microsoft Entra backed accounts only. + - Reduce user workload by automatically approving subsequent prompts if the specified user has already approved the deployment to a previous stage in the pipeline (applies to predeployment approvals only). ## Approval notifications @@ -67,4 +70,3 @@ You can enable notifications from your project settings to subscribe to release - [Use gates and approvals to control your deployment](../deploy-using-approvals.md) - [Add stages, dependencies, & conditions](../../process/stages.md) - [Release triggers](../triggers.md) - diff --git a/docs/pipelines/release/approvals/gates.md b/docs/pipelines/release/approvals/gates.md index 2ef3b18e62f..e04c7c3f2d1 100644 --- a/docs/pipelines/release/approvals/gates.md +++ b/docs/pipelines/release/approvals/gates.md @@ -1,40 +1,41 @@ --- -title: Control releases with deployment gates -ms.custom: seodec18 +title: Deployment gates concepts description: Understand deployment gates in Azure Pipelines ms.assetid: 0824A7C4-9353-4BDA-B652-5B826E0EF2A5 -ms.topic: conceptual -ms.author: shashban -author: azooinmyluggage -ms.date: 08/01/2022 +ms.topic: concept-article +ms.author: sandrica +author: silviuandrica +ms.date: 11/14/2024 monikerRange: '<= azure-devops' --- -# Deployment gates +# Deployment gates concepts [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -Gates allow automatic collection of health signals from external services and then promote the release when all the signals are successful or stop the deployment on timeout. Typically, gates are used in connection with incident management, problem management, change management, monitoring, and external approval systems. +Deployment gates in Azure Pipelines are added to release pipelines to ensure that deployments meet specific criteria before proceeding. Gates are essential for ensuring that deployments are reliable and secure by enforcing rigorous checks leading to more stable and secure software releases. + +Gates are defined in the pre-deployment and post-deployment conditions of a release stage. They provide a mechanism to automatically collect health signals from external services, such as Azure Function or REST APIs, to control the promotion of releases based on these signals. Gates work with approvals to ensure that the right stakeholders approve the release and the release meets the necessary quality and compliance criteria. ## Use cases Some common use cases for deployment gates are: - **Incident management**: Ensure certain criteria are met before proceeding with deployment. For example, ensure deployment occurs only if no priority zero bugs exist. -- **Seek approvals**: Notify external users such as legal departments, auditors, or IT managers about a deployment by integrating with other services such as Microsoft Teams or Slack and wait for their approvals. +- **Seek approvals**: Integrate with Microsoft Teams or Slack to notify external users such as auditors, or IT managers about a deployment and wait for their approvals. - **Quality validation**: Query pipeline metrics such as pass rate or code coverage and deploy only if they are within a predefined threshold. - **Security scan**: Perform security checks such as artifacts scanning, code signing, and policy checking. A deployment gate might initiate the scan and wait for it to complete, or just check for completion. -- **User experience relative to baseline**: Using product telemetry, ensure the user experience hasn't regressed from the baseline state. The user experience metrics before the deployment could be used as baseline. +- **User experience relative to baseline**: Use product data collection to ensure the user experience regressions from the baseline state. The user experience metrics before the deployment could be used as baseline. - **Change management**: Wait for change management procedures in a system such as ServiceNow to complete before proceeding with deployment. - **Infrastructure health**: Execute monitoring and validate the infrastructure against compliance rules after deployment, or wait for healthy resource utilization and a positive security report. -Most of the health parameters vary over time, regularly changing their status from healthy to unhealthy and back to healthy. To account for such variations, all the gates are periodically reevaluated until all of them are successful at the same time. The release execution and deployment does not proceed if all gates do not succeed in the same interval and before the configured timeout. +Most of the health parameters vary over time, regularly changing their status from healthy to unhealthy and back to healthy. To account for such variations, all the gates are periodically reevaluated until all of them are successful at the same time. The release execution and deployment doesn't proceed if all gates don't succeed in the same interval and before the configured timeout. ## Define a gate for a stage -You can enable gates at the start of a stage (Pre-deployment conditions) or at the end of a stage (Post-deployment conditions) or for both. See [Set up gates](../deploy-using-approvals.md#set-up-gates) for more details. +You can enable gates at the start of a stage (**Pre-deployment conditions**) or at the end of a stage (**Post-deployment conditions**) or for both. For more information, see [Set up gates](../deploy-using-approvals.md#set-up-gates). -The **Delay before evaluation** is a time delay at the beginning of the gate evaluation process that allows the gates to initialize, stabilize, and begin providing accurate results for the current deployment. see [Gate evaluation flows](#gate-evaluation-flow-examples) for more details. +The **Delay before evaluation** is a time delay at the beginning of the gate evaluation process that allows the gates to initialize, stabilize, and begin providing accurate results for the current deployment. For more information, see [Gate evaluation flows](#gate-evaluation-flow-examples). :::image type="content" source="../media/deploy-using-approvals/set-delay-time-gates.png" alt-text="A screenshot showing the delay before evaluation feature in gates."::: @@ -43,11 +44,11 @@ The **Delay before evaluation** is a time delay at the beginning of the gate eva The following gates are available by default: -- **Invoke Azure function**: Trigger execution of an Azure function and ensure a successful completion. See [Azure function task](/azure/devops/pipelines/tasks/reference/azure-function-v1) for more details. -- **Query Azure monitor alerts**: Observe the configured Azure monitor alert rules for active alerts. See [Azure monitor task](/azure/devops/pipelines/tasks/reference/azure-monitor-v1) for more details. -- **Invoke REST API**: Make a call to a REST API and continue if it returns a successful response. See [Invoke REST API task](/azure/devops/pipelines/tasks/reference/invoke-rest-api-v1) for more details. -- **Query Work items**: Ensure the number of matching work items returned from a query is within a threshold. See [Query Work Items task](/azure/devops/pipelines/tasks/reference/query-work-items-v0) for more details. -- **Security and compliance assessment**: Assess Azure Policy compliance on resources within the scope of a given subscription and resource group, and optionally at a specific resource level. See [Check Azure Policy compliance task](/azure/devops/pipelines/tasks/reference/azure-policy-check-gate-v0) for more details. +- **Invoke Azure Function**: Trigger execution of an Azure function and ensure a successful completion. For more information, see [Azure function task](/azure/devops/pipelines/tasks/reference/azure-function-v1). +- **Query Azure mMnitor alerts**: Observe the configured Azure monitor alert rules for active alerts. For more information, see [Azure monitor task](/azure/devops/pipelines/tasks/reference/azure-monitor-v1). +- **Invoke REST API**: Make a call to a REST API and continue if it returns a successful response. For more information, see [Invoke REST API task](/azure/devops/pipelines/tasks/reference/invoke-rest-api-v1). +- **Query work items**: Ensure the number of matching work items returned from a query is within a threshold. For more information, see [Query Work Items task](/azure/devops/pipelines/tasks/reference/query-work-items-v0). +- **Check Azure Policy compliance**: Assess Azure Policy compliance on resources within the scope of a given subscription and resource group, and optionally at a specific resource level. For more information, see [Check Azure Policy compliance task](/azure/devops/pipelines/tasks/reference/azure-policy-check-gate-v0). :::image type="content" source="../media/default-gates.png" alt-text="A screenshot showing the default gates."::: @@ -55,11 +56,11 @@ You can also [create your own gates](https://github.com/Microsoft/azure-pipeline The evaluation options that apply to all the gates are: -- **Time between re-evaluation of gates**. The time interval between successive evaluations of the gates. At each sampling interval, new requests are sent concurrently to each gate and the new results are evaluated. It is recommended that the sampling interval is greater than the longest typical response time of the configured gates to allow time for all responses to be received for evaluation. -- **Timeout after which gates fail**. The maximum evaluation period for all gates. The deployment will be rejected if the timeout is reached before all gates succeed during the same sampling interval. -- **Gates and approvals**. Select the required order of execution for gates and approvals if you have configured both. For pre-deployment conditions, the default is to prompt for manual (user) approvals first, then evaluate gates afterwards. This saves the system from evaluating the gate functions if the release is rejected by the user. For post-deployment conditions, the default is to evaluate gates and prompt for manual approvals only when all gates are successful. This ensures the approvers have all the information required to approve. +- **Time between re-evaluation of gates**. The time interval between successive evaluations of the gates. At each sampling interval, new requests are sent concurrently to each gate and the new results are evaluated. The recommendation is that the sampling interval is greater than the longest typical response time of the configured gates to allow time for all responses to be received for evaluation. +- **Timeout after which gates fail**. The maximum evaluation period for all gates. The deployment is rejected if the timeout is reached before all gates succeed during the same sampling interval. +- **Gates and approvals**. Select the required order of execution for gates and approvals if you configured both. For pre-deployment conditions, the default is to prompt for manual (user) approvals first, then evaluate gates afterwards saving the system from evaluating the gate functions if the user rejects the release. For post-deployment conditions, the default is to evaluate gates and prompt for manual approvals only when all gates are successful ensuring the approvers have all the information required to approve the release. -See [View approvals logs](../deploy-using-approvals.md#set-up-manual-validation) and [Monitor and track deployments](../define-multistage-release-process.md#monitor-track) for more information on gates analytics. +For more information about gates analytics, see [View approvals logs](../deploy-using-approvals.md#view-deployment-logs) and [Monitor and track deployments](../define-multistage-release-process.md#monitor-and-track-deployments). ### Gate evaluation flow examples @@ -67,19 +68,13 @@ The following diagram illustrates the flow of gate evaluation where, after the i :::image type="content" source="media/gate-results-pass.png" alt-text="A screenshot showing the gates evaluation flow diagram."::: -The following diagram illustrates the flow of gate evaluation where, after the initial stabilization delay period, not all gates have succeeded at each sampling interval. In this case, after the timeout period expires, the deployment is rejected. +The following diagram illustrates the flow of gate evaluation where, after the initial stabilization delay period, not all gates succeeded at each sampling interval. In this case, after the timeout period expires, the deployment is rejected. :::image type="content" source="media/gate-results-fail.png" alt-text="A screenshot showing examples of gates approvals and failures."::: -## Resources - -- [Create custom gates](https://github.com/Microsoft/azure-pipelines-tasks/blob/master/docs/authoring/gates.md) -- [Twitter sentiment as a release gate](https://blogs.msdn.microsoft.com/bharry/2017/12/15/twitter-sentiment-as-a-release-gate/) -- [GitHub issues as a release gate](https://www.visualstudiogeeks.com/DevOps/github-issues-as-deployment-gate-in-vsts-rm) ## Related articles - [Release gates and approvals overview](index.md) - [Use gates and approvals to control your deployment](../deploy-using-approvals.md) -- [Add stages, dependencies, & conditions](../../process/stages.md) -- [Release triggers](../triggers.md) +- [Classic Release triggers](../triggers.md) diff --git a/docs/pipelines/release/approvals/index.md b/docs/pipelines/release/approvals/index.md index a6f21b1b9a3..8e3f8e0f8d9 100644 --- a/docs/pipelines/release/approvals/index.md +++ b/docs/pipelines/release/approvals/index.md @@ -1,11 +1,10 @@ --- title: Understand release gates, checks, and approvals -ms.custom: seodec18 description: Understand deployment gates and approvals in Azure Pipelines ms.assetid: D5989F1C-04D8-43EF-9212-AE70151C461C ms.topic: conceptual -ms.author: shashban -author: azooinmyluggage +ms.author: sandrica +author: silviuandrica ms.date: 02/18/2021 monikerRange: '<= azure-devops' --- @@ -14,9 +13,7 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../includes/concept-rename-note.md)] -::: moniker-end + Release pipelines enable teams to continuously deploy their application across different stages with lower risk and with faster pace. Deployments to each stage can be fully automated by using jobs and tasks. diff --git a/docs/pipelines/release/approvals/media/access-control-resource-group.png b/docs/pipelines/release/approvals/media/access-control-resource-group.png new file mode 100644 index 00000000000..e7e2537ff28 Binary files /dev/null and b/docs/pipelines/release/approvals/media/access-control-resource-group.png differ diff --git a/docs/pipelines/release/approvals/media/app-registration-client-tenant.png b/docs/pipelines/release/approvals/media/app-registration-client-tenant.png new file mode 100644 index 00000000000..55afd2134a0 Binary files /dev/null and b/docs/pipelines/release/approvals/media/app-registration-client-tenant.png differ diff --git a/docs/pipelines/release/approvals/media/copy-federated-credential.png b/docs/pipelines/release/approvals/media/copy-federated-credential.png new file mode 100644 index 00000000000..5a2ba7f79d9 Binary files /dev/null and b/docs/pipelines/release/approvals/media/copy-federated-credential.png differ diff --git a/docs/pipelines/release/approvals/media/federated-credential-scenario.png b/docs/pipelines/release/approvals/media/federated-credential-scenario.png new file mode 100644 index 00000000000..31c568e5aa1 Binary files /dev/null and b/docs/pipelines/release/approvals/media/federated-credential-scenario.png differ diff --git a/docs/pipelines/release/approvals/media/federated-credentials-choice.png b/docs/pipelines/release/approvals/media/federated-credentials-choice.png new file mode 100644 index 00000000000..4587d5d10ce Binary files /dev/null and b/docs/pipelines/release/approvals/media/federated-credentials-choice.png differ diff --git a/docs/pipelines/release/approvals/media/federated-credentials-devops.png b/docs/pipelines/release/approvals/media/federated-credentials-devops.png new file mode 100644 index 00000000000..ee521f8bdb2 Binary files /dev/null and b/docs/pipelines/release/approvals/media/federated-credentials-devops.png differ diff --git a/docs/pipelines/release/approvals/media/federated-managed-values.png b/docs/pipelines/release/approvals/media/federated-managed-values.png new file mode 100644 index 00000000000..63e0dbdae64 Binary files /dev/null and b/docs/pipelines/release/approvals/media/federated-managed-values.png differ diff --git a/docs/pipelines/release/approvals/media/federated-set-subscription.png b/docs/pipelines/release/approvals/media/federated-set-subscription.png new file mode 100644 index 00000000000..188f712065f Binary files /dev/null and b/docs/pipelines/release/approvals/media/federated-set-subscription.png differ diff --git a/docs/pipelines/release/approvals/media/new-app-registration.png b/docs/pipelines/release/approvals/media/new-app-registration.png new file mode 100644 index 00000000000..3a48d7e0065 Binary files /dev/null and b/docs/pipelines/release/approvals/media/new-app-registration.png differ diff --git a/docs/pipelines/release/approvals/media/servicenow-04.png b/docs/pipelines/release/approvals/media/servicenow-04.png index 32065e1e1c4..ccfb06fde95 100644 Binary files a/docs/pipelines/release/approvals/media/servicenow-04.png and b/docs/pipelines/release/approvals/media/servicenow-04.png differ diff --git a/docs/pipelines/release/approvals/media/servicenow-05.png b/docs/pipelines/release/approvals/media/servicenow-05.png index cf7d1c7bd6d..34f039d03d9 100644 Binary files a/docs/pipelines/release/approvals/media/servicenow-05.png and b/docs/pipelines/release/approvals/media/servicenow-05.png differ diff --git a/docs/pipelines/release/approvals/media/servicenow-06.png b/docs/pipelines/release/approvals/media/servicenow-06.png index f516d5a2a3a..347eb462cb7 100644 Binary files a/docs/pipelines/release/approvals/media/servicenow-06.png and b/docs/pipelines/release/approvals/media/servicenow-06.png differ diff --git a/docs/pipelines/release/approvals/media/servicenow-08.png b/docs/pipelines/release/approvals/media/servicenow-08.png index 355125c2ffe..6eda72ee0ab 100644 Binary files a/docs/pipelines/release/approvals/media/servicenow-08.png and b/docs/pipelines/release/approvals/media/servicenow-08.png differ diff --git a/docs/pipelines/release/approvals/media/servicenow-14.png b/docs/pipelines/release/approvals/media/servicenow-14.png index a97bc12bf68..344d0b4f0b7 100644 Binary files a/docs/pipelines/release/approvals/media/servicenow-14.png and b/docs/pipelines/release/approvals/media/servicenow-14.png differ diff --git a/docs/pipelines/release/approvals/media/workload-identity-service-connection-manual.png b/docs/pipelines/release/approvals/media/workload-identity-service-connection-manual.png new file mode 100644 index 00000000000..bc7debd687a Binary files /dev/null and b/docs/pipelines/release/approvals/media/workload-identity-service-connection-manual.png differ diff --git a/docs/pipelines/release/approvals/servicenow.md b/docs/pipelines/release/approvals/servicenow.md index fdbb24c9364..2adf8d5defc 100644 --- a/docs/pipelines/release/approvals/servicenow.md +++ b/docs/pipelines/release/approvals/servicenow.md @@ -1,191 +1,234 @@ --- -title: Control deployments by using ServiceNow -ms.custom: seodec18 -description: Understand ServiceNow gated releases in Azure Pipelines +title: Integrate with ServiceNow change management +description: Learn how to integrate ServiceNow change management by using gated releases with the Azure Pipelines ServiceNow extension. ms.assetid: 0824A7C4-9353-4BDA-B652-5B826E0EF2A5 -ms.topic: conceptual -ms.author: shashban -author: shashban -ms.date: 08/29/2022 +ms.topic: tutorial +ms.author: ericvan +author: geekzter +ms.date: 08/19/2024 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Integrate with ServiceNow change management +# Integrate Azure Pipelines with ServiceNow change management [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -Azure Pipelines support integration with ServiceNow to improve collaboration between development and IT teams. By including change management in release pipelines, teams can reduce the risks associated with changes and follow service management methodologies such as ITIL while taking full advantage of Azure Pipelines. +To improve collaboration between development and IT teams, Azure Pipelines supports integration with ServiceNow. Teams can reduce the risks associated with changes and follow service management methodologies such as Information Technology Infrastructure Library (ITIL) by including change management gates in release pipelines. -In this article, you'll learn how to: +In this tutorial, you learn how to: > [!div class="checklist"] > > - Configure ServiceNow instances. -> - Include ServiceNow change management process as a release gate. -> - Monitor change management process from release pipelines. +> - Include the ServiceNow change management process as a release gate. +> - Monitor the change management process from release pipelines. > - Keep ServiceNow change requests updated with deployment results. ## Prerequisites -- This tutorial expands on [Use approvals and gates](../deploy-using-approvals.md) and [Define approvals & checks](../../process/approvals.md). +- Have a HI account in a nondeveloper instance of [ServiceNow](https://www.servicenow.com/). +- Have an Azure DevOps [organization](../../../organizations/accounts/create-organization.md) and [project](../../../organizations/projects/create-project.md) with organization-level permissions to install extensions. +- Have either a [Classic release pipeline](../define-multistage-release-process.md), or a [YAML pipeline](../../create-first-pipeline.md) that deploys to an environment, in your Azure DevOps project. +- Make sure you understand and can follow the procedures in [Use gates and approvals to control your deployment](../deploy-using-approvals.md) and [Define approvals and checks](../../process/approvals.md). -- An Azure DevOps organization. [Create an organization](../../../organizations/accounts/create-organization.md), if you don't have one already. +## Configure the ServiceNow instance -- A non-developer instance of [ServiceNow](https://www.servicenow.com/). +1. Install the [Azure Pipelines extension](https://store.servicenow.com/sn_appstore_store.do#!/store/application/fa788cb5dbb5630040669c27db961940) on your ServiceNow instance. See [Buying Overview](https://store.servicenow.com/sn_appstore_store.do#!/store/help?article=KB0010019) for more details on installing apps from the ServiceNow store. You need **HI** credentials to complete the installation. -## Configure the ServiceNow instance +1. In ServiceNow, create a new user for the Azure Pipelines Service Account and grant it the **x_mioms_azpipeline.pipelinesExecution** role. -1. Install the [Azure Pipelines](https://store.servicenow.com/sn_appstore_store.do#!/store/application/fa788cb5dbb5630040669c27db961940) extension on your ServiceNow instance. You'll need **Hi** credentials to complete the installation. See [Buying Overview](https://store.servicenow.com/sn_appstore_store.do#!/store/help?article=KB0010019) for more details on installing apps from the ServiceNow store. + :::image type="content" source="media/servicenow-01.png" alt-text="A screenshot showing how to set up a new user in ServiceNow."::: -1. Create a new user in ServiceNow and grant it the following role: `x_mioms_azpipeline.pipelinesExecution`. +## Set up the Azure DevOps organization and project - :::image type="content" source="media/servicenow-01.png" alt-text="A screenshot showing how to set up a new user in ServiceNow."::: +1. In your Azure DevOps organization, install the [ServiceNow Change Management extension](https://marketplace.visualstudio.com/items?itemName=ms-vscs-rm.vss-services-servicenowchangerequestmanagement). -## Set up the Azure DevOps organization + :::image type="content" source="media/servicenow-02.png" alt-text="A screenshot showing the ServiceNow Change Management extension."::: -1. Install the [ServiceNow Change Management extension](https://marketplace.visualstudio.com/items?itemName=ms-vscs-rm.vss-services-servicenowchangerequestmanagement) on your Azure DevOps organization. +1. In your Azure DevOps project, create a new ServiceNow service connection by using either **Basic authentication** or [OAuth2 authentication](https://github.com/microsoft/azure-pipelines-extensions/blob/master/Extensions/ServiceNow/Src/readme.md#create-service-connection-for-servicenow-in-azure-pipelines). For more information, see [Create a service connection](../../library/service-endpoints.md#create-a-service-connection). - :::image type="content" source="media/servicenow-02.png" alt-text="A screenshot showing the ServiceNow Change Management extension."::: + :::image type="content" source="media/servicenow-03.png" alt-text="A screenshot showing how to configure ServiceNow service connection."::: -1. Create a new ServiceNow [service connection](../../library/service-endpoints.md) in your Azure DevOps project as follows. Alternatively, you can also use [OAuth2 authentication](https://github.com/microsoft/azure-pipelines-extensions/blob/master/Extensions/ServiceNow/Src/readme.md#create-service-connection-for-servicenow-in-azure-pipelines). - - :::image type="content" source="media/servicenow-03.png" alt-text="A screenshot showing how to configure ServiceNow service connection."::: +## Configure the pipeline -## Configure the release pipeline +You can add ServiceNow integration to a Classic release pipeline or to a YAML pipeline that deploys to an environment. -1. Navigate to your release pipeline, and then select the **Pre-deployment conditions** icon. Select **Gates** and the **ServiceNow Change Management** pre-deployment gate. - - :::image type="content" source="media/servicenow-04.png" alt-text="A screenshot showing how to add a pre-deployment gate."::: +#### [Classic](#tab/classic/) -1. Select the service connection you created earlier and fill out the required fields as follows: +### Add the ServiceNow Change Management pre-deployment gate - :::image type="content" source="media/servicenow-05.png" alt-text="A screenshot showing how to configure the ServiceNow Change Management gate."::: +1. In your Azure Pipelines release pipeline, select the **Pre-deployment conditions** icon. - - **ServiceNow connection**: Connection to the ServiceNow instance used for change management. - - **Short description**: A summary of the change. - - **Description**: A detailed description of the change. - - **Category**: The category of the change. Example: Hardware, Network, Software. - - **Priority**: Priority of the change. - - **Risk**: The risk level for the change. - - **Impact**: The effect that the change has on business. - - **Configuration Item**: Configuration item (CI) that the change applies to. - - **Assignment group**: The group that the change is assigned to. - - **Schedule of change request**: Schedule of the change as honored by the ServiceNow workflow. Date and time should be in UTC and format should be *yyyy-MM-ddTHH:mm:ssZ*. Example: 2018-01-31T07:56:59Z. - - **Additional change request parameters**: Name must be field name (not label) prefixed with 'u_'. Example: *u_backout_plan*. Value must be a valid value in ServiceNow. Invalid entries are ignored. - - **Desired state of change request**: The gate would succeed and the pipeline continues when the change request status is the same as the provided value. - - **Advanced**: Specifies an expression that controls when this gate should succeed. The change request is defined as *root['result']* in the response from ServiceNow. Example - "and(eq(root['result'].state, 'New'),eq(root['result'].risk, 'Low'))". See [Expressions](../../process/expressions.md) for more details. - - **Output Variables** : You must specify a reference name to be able to use output variables in your deployment workflow. Gate variables can be accessed by using "PREDEPLOYGATE" as a "prefix" in **an agentless job**. For example when the reference name is set to 'gate1', the change number can be obtained as follows: *$(PREDEPLOYGATE.gate1.CHANGE_REQUEST_NUMBER)*. - - **CHANGE_REQUEST_NUMBER** : Number of the change request. - - **CHANGE_SYSTEM_ID** : System Id of the change request. +1. On the **Pre-deployment conditions** screen, expand and enable **Gates**, select **Add** next to **Deployment gates**, and select the **ServiceNow Change Management** pre-deployment gate. -1. At the end of your release pipeline, add an **Agentless job** with a task **Update ServiceNow Change Request**. + :::image type="content" source="media/servicenow-04.png" alt-text="A screenshot showing how to add a pre-deployment gate."::: - :::image type="content" source="media/servicenow-06.png" alt-text="A screenshot showing how to configure the Update ServiceNow Change Request task."::: +#### [YAML](#tab/yaml/) -- **ServiceNow connection**: Connection to the ServiceNow instance used for change management. -- **Change request number**: Number of the change request to update. -- **Updated status of change request** : Status to set for the change request. This input is available if *Update status* is selected. -- **Close code and Close notes**: Return status. +### Add the ServiceNow Change Management check -> [!NOTE] -> The Update ServiceNow Change Request task will fail if none of the change request fields are updated during execution. ServiceNow ignores invalid fields and values passed to the task. +1. In your Azure DevOps project, select **Pipelines** > **Environments** in the left menu, and select the environment that your YAML pipeline deploys to. -## Create a release pipeline +1. On the **Approvals and checks** tab, select **+** to add a new check, and then select and add the **ServiceNow Change Management** check to your environment. -1. Select **Create release** to start a new release pipeline. + :::image type="content" source="media/servicenow-12.png" alt-text="A screenshot showing how to add a ServiceNow Change Management check."::: -1. Your pipeline should create a new change request in ServiceNow as part of the pre-deployment conditions you created earlier. +--- - :::image type="content" source="media/servicenow-07.png" alt-text="A screenshot showing the execution of the pre-deployment gate."::: +### Configure ServiceNow Change Management settings -1. The pipeline will wait for all the gates to succeed within the same sample interval. To check the change number, select the status icon to view your pipeline logs. +1. On the **ServiceNow Change Management** settings screen, under **ServiceNow connection**, select the ServiceNow service connection you created earlier. - :::image type="content" source="media/servicenow-08.png" alt-text="A screenshot showing the pipeline logs."::: + :::image type="content" source="media/servicenow-05.png" alt-text="A screenshot showing how to configure the ServiceNow Change Management gate."::: -1. The change request will be queued in ServiceNow and can be viewed by the change owner. +1. Complete the rest of the form as follows: - :::image type="content" source="media/servicenow-09.png" alt-text="A screenshot showing a new change request in ServiceNow."::: - -1. The release pipeline that triggered the new change request can be found under the **Azure DevOps Pipeline metadata** section. + |Setting|Description| + |-------|-----------| + | **Action** | Select **Create new change request** or **Use existing change request**. + | **Change type** | Select **Normal**, **Standard**, or **Emergency**. + | **Short description** | Enter a summary of the change.| + | **Schedule of change request** | Optionally, enter the schedule of the change as honored by the ServiceNow workflow. Under **Planned start date** and **Planned end date**, enter UTC date and time in format *yyyy-MM-ddTHH:mm:ssZ*.| + | **Description** | Optionally, enter a detailed description of the change.| + | **Category** | Optionally select the category of the change, such as **Hardware**, **Network**, or **Software**.| + | **Priority** | Optionally select the priority of the change.| + | **Risk** | Optionally select the risk level for the change.| + | **Impact** | Optionally select the effect that the change has on business.| + | **Configuration item** | Optionally select the configuration item that the change applies to.| + | **Assignment group** | Optionally select the group that the change is assigned to.| + | **Advanced** > **Additional change request parameters** | Select the ellipsis next to the field and then select **Add** to add more parameters. Names must be field names, not labels, prefixed with `u_`, such as `u_backout_plan`. Values must be valid in ServiceNow. Invalid entries are ignored.| + | **Success criteria** | Select either **Desired state of change request** or **Advanced success criteria**. + | **Desired state of change request** | Select the change request status value necessary for the gate to succeed and the pipeline to continue. + | **Advanced success criteria** | Enter an expression that controls when the gate should succeed. The change request is defined as `root['result']` in the response from ServiceNow. For example, `and(eq(root['result'].state, 'New'),eq(root['result'].risk, 'Low'))`. For more information, see [Expressions](../../process/expressions.md). + | **Output Variables** > **Reference name** | To be able to use output variables in your deployment workflow, specify a reference name. You can access gate variables by using `PREDEPLOYGATE` as a prefix in an agentless job. For example, when the reference name is set to *gate1*, you can get the change request number by using the variable `$(PREDEPLOYGATE.gate1.CHANGE_REQUEST_NUMBER)`. + | **Variables list** | **CHANGE_REQUEST_NUMBER** is the number of the change request.
      **CHANGE_SYSTEM_ID** is the System ID of the change request.| - :::image type="content" source="media/servicenow-10.png" alt-text="A screenshot showing the release pipeline metadata."::: +#### [Classic](#tab/classic/) -1. When the change is ready for implementation (moved to **Implement** state), the pipeline will resume execution and the gate status should return *succeeded*. +### Update the pipeline - :::image type="content" source="media/servicenow-11.png" alt-text="A screenshot showing the deployment gate status."::: +1. At the end of your release pipeline, add an **Agentless job** with the task **Update ServiceNow Change Request**. +1. In the task settings form, under **ServiceNow connection**, select your ServiceNow service connection. +1. Under **Change request number**, enter the ServiceNow change request number to update. +1. Select **Update status**, and then under **Updated status of change request**, choose or enter the status to set for the change request. +1. In **Work Notes** under **Advanced**, optionally enter any work notes to be added for the change request update. -1. The change request will be closed automatically after deployment. + :::image type="content" source="media/servicenow-06.png" alt-text="A screenshot showing how to configure the Update ServiceNow Change Request task."::: + +> [!NOTE] +> The Update ServiceNow Change Request task fails if none of the change request fields are updated during execution. ServiceNow ignores invalid fields and values passed to the task. -## Yaml pipelines +## Create a release -This tutorial assumes you have a yaml pipeline with a single stage that deploys to a "latest" environment. +Select **Create release** to start a new release. -### Add a check +Your pipeline should create a new change request in ServiceNow as part of the pre-deployment conditions you created earlier. -1. Navigate to your environment "latest", select the ellipsis button and then select **Approvals and checks**. +:::image type="content" source="media/servicenow-07.png" alt-text="A screenshot showing the execution of the pre-deployment gate."::: -1. Select the plus sign to add a new check, and then add the **ServiceNow Change Management** check to your environment. Use the same configuration you used for your pre-deployment gate. +The pipeline waits for all the gates to succeed within the same sample interval. To check the change number, select the status icon to view your pipeline logs. - :::image type="content" source="media/servicenow-12.png" alt-text="A screenshot showing how to add a ServiceNow Change Management check."::: +:::image type="content" source="media/servicenow-08.png" alt-text="A screenshot showing the pipeline logs."::: + +The change request is queued in ServiceNow, and the change owner can view it. + +:::image type="content" source="media/servicenow-09.png" alt-text="A screenshot showing a new change request in ServiceNow."::: + +You can find the release pipeline that triggered the new change request under the **Azure DevOps Pipeline metadata** section. -### Add the yaml task +:::image type="content" source="media/servicenow-10.png" alt-text="A screenshot showing the release pipeline metadata."::: -1. Add a [server job](../../process/phases.md#server-jobs) to your stage to update the change request. +When the change is ready for implementation and moved to **Implement** state, the pipeline resumes execution and the gate status should return **succeeded**. - :::image type="content" source="media/servicenow-13.png" alt-text="A screenshot showing the agentless task."::: +:::image type="content" source="media/servicenow-11.png" alt-text="A screenshot showing the deployment gate status."::: -1. Save and run your pipeline. A new change request will be automatically created and the pipeline will pause and wait for the checks to complete. +The change request closes automatically after deployment. -1. Once the checks are completed, the pipeline should resume execution. The change request will be closed automatically after deployment. +#### [YAML](#tab/yaml/) + +### Add the YAML task + +To update the change request, add the following [server job](../../process/phases.md#server-jobs) and `UpdateServiceNowChangeRequest@2` task to your YAML pipeline. + +```yaml +stages: +- stage: Stage1 + jobs: + - deployment: DeployLatest + environment: + ... + - job: UpdateChangeRequest + steps: + - task: UpdateServiceNowChangeRequest@2 + displayName: 'Update ServiceNow Change Request' + inputs: + ServiceNowConnection: '' + NewStatus: '' + WorkNotes: '' + otherParameters: '{"u_": ""}' +pool: server +``` + +For example: + +:::image type="content" source="media/servicenow-13.png" alt-text="A screenshot showing the agentless task."::: + +## Run the pipeline + +Save and run your pipeline. A new change request is automatically created, and the pipeline pauses and waits for the checks to complete. When the checks complete, the pipeline resumes execution. :::image type="content" source="media/servicenow-14.png" alt-text="A screenshot showing the pipeline execution."::: -## FAQs +The change request closes automatically after deployment. -### Q: What versions of ServiceNow are supported? +--- -::: moniker range="azure-devops" +## FAQs -**A**: We support the following versions: Kingston, London, New York, Paris, Quebec, Rome, San Diego, and Tokyo. +### What versions of ServiceNow are supported? +::: moniker range="azure-devops" +The Azure Pipelines ServiceNow extension supports the Kingston, London, New York, Paris, Quebec, Rome, San Diego, Tokyo, and Utah releases. ::: moniker-end -::: moniker range="<= azure-devops-2022" - -**A**: We support the following versions: Kingston, London, New York, Paris, and Quebec. +::: moniker range="azure-devops-2022" +The Azure Pipelines ServiceNow extension supports the Kingston, London, New York, Paris, Quebec, San Diego, Tokyo, and Utah releases. +::: moniker-end +::: moniker range="< azure-devops-2022" +The Azure Pipelines ServiceNow extension supports the Kingston, London, New York, Paris, and Quebec releases. ::: moniker-end -### Q: What types of change request are supported? +### What types of change request are supported? -**A**: Normal, standard and emergency change requests are supported with this integration. +Azure Pipelines ServiceNow integration supports normal, standard, and emergency change requests. -### Q: How do I set additional change properties? +### How do I set other change properties? -**A**: You can specify additional change properties from the **Additional change request parameters** field. Use a key-value pairs JSON format, with the name being the field name (not the label) prefixed with `u_`. +You can specify more change properties from the **Additional change request parameters** field or in `otherParameters`. Use a key-value pairs JSON format, with the name being the field name, not the label, prefixed with `u_`. -### Q: Can I update custom fields in the change request with additional change request parameters? +### Can I update custom fields in the change request with more change request parameters? -**A**: If custom fields are defined in the change request, you must [add mapping for custom fields in Import set transform map](https://github.com/Microsoft/azure-pipelines-extensions/tree/master/Extensions/ServiceNow/Src#steps-to-add-mapping-for-custom-fields-in-import-set-transform-map-). +If you define custom fields in the change request, you must [add mapping for custom fields in Import set transform map](https://github.com/Microsoft/azure-pipelines-extensions/tree/master/Extensions/ServiceNow/Src#steps-to-add-mapping-for-custom-fields-in-import-set-transform-map-). -### Q: I don't see drop-down values populated for Category, Status, and other fields. What should I do? +### How can I see dropdown values populated for Category, Status, and other fields? -**A**: Change Management Core and Change Management - State Model plugins must be active on your ServiceNow instance for the drop-downs to work. See [Upgrade change management](https://docs.servicenow.com/bundle/quebec-it-service-management/page/product/change-management/task/migrate-change-mgmt-pre-geneva.html) and [Update change request states](https://docs.servicenow.com/bundle/quebec-it-service-management/page/product/change-management/task/state-model-activate-tasks.html) for more details. +Change Management Core and Change Management - State Model plugins must be active on your ServiceNow instance for the dropdowns to work. For more information, see [Upgrade change management](https://docs.servicenow.com/bundle/quebec-it-service-management/page/product/change-management/task/migrate-change-mgmt-pre-geneva.html) and [Update change request states](https://docs.servicenow.com/bundle/quebec-it-service-management/page/product/change-management/task/state-model-activate-tasks.html). ## Resources - [Configure your release pipelines for safe deployments](https://devblogs.microsoft.com/devops/configuring-your-release-pipelines-for-safe-deployments/) -- [Twitter sentiment as a release gate](https://blogs.msdn.microsoft.com/bharry/2017/12/15/twitter-sentiment-as-a-release-gate/) +- [X sentiment as a release gate](https://blogs.msdn.microsoft.com/bharry/2017/12/15/twitter-sentiment-as-a-release-gate/) - [GitHub issues as a release gate](https://www.visualstudiogeeks.com/DevOps/github-issues-as-deployment-gate-in-vsts-rm) - [Author custom gates](https://github.com/Microsoft/azure-pipelines-tasks/blob/master/docs/authoring/gates.md). - [ServerTaskHelper Library example](https://github.com/Microsoft/vsts-rm-extensions/tree/master/ServerTaskHelper/DistributedTask.ServerTask.Remote.Common) -## Related articles +## Related content - [Release gates and approvals](index.md) - [Define approvals and checks](../../process/approvals.md) - [Set up manual intervention](../deploy-using-approvals.md#set-up-manual-intervention) - [Use gates and approvals to control your deployment](../../release/deploy-using-approvals.md) -- [Add stages, dependencies, & conditions](../../process/stages.md) +- [Add stages, dependencies, and conditions](../../process/stages.md) - [Release triggers](../triggers.md) diff --git a/docs/pipelines/release/artifacts.md b/docs/pipelines/release/artifacts.md index 82a6d93fc88..08cd351f712 100644 --- a/docs/pipelines/release/artifacts.md +++ b/docs/pipelines/release/artifacts.md @@ -1,254 +1,240 @@ --- -title: Release pipelines and artifact sources -description: Understand release pipelines and the different artifact sources. +title: Artifact sources in Classic release pipelines +description: Learn about the list of artifact sources that can be used in a Classic release pipeline. ms.assetid: 6820FA1F-4B20-4845-89E0-E6AB4BD5888D ms.topic: conceptual -ms.author: shashban -author: shashban -ms.date: 01/12/2023 -ms.custom: contperf-fy20q4, seodec18, engagement-fy23, devx-track-jenkins +ms.author: sandrica +author: silviuandrica +ms.date: 07/31/2024 +ms.custom: engagement-fy23, devx-track-jenkins monikerRange: '<= azure-devops' --- -# Release pipelines and Artifact sources +# Artifact sources in Classic release pipelines [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -With Azure Pipelines, you can deploy your artifacts from a wide range of artifact sources and integrate your workflow with different types of artifact repositories. Releases can be linked to multiple artifact sources, where one is designated as the primary source. +With Classic release pipelines, you can deploy your artifacts from a wide range of sources. Using the graphical interface, you can set up your pipeline to integrate and consume artifacts from various services. Additionally, you can link multiple artifacts from different sources and designate one as the primary source based on your needs. ## Artifact sources -Azure Pipelines supports a wide range of repositories, source control tools, and continuous integration systems. +Azure Pipelines supports a wide range of repositories, services, and CI/CD platforms. When creating a release, you can specify the version of your artifact source. By default, releases use the latest version of the source artifact. You can also choose to use the latest build from a specific branch by specifying the tags, a specific version, or allow the user to specify the version at the time of release creation. -When creating a release, you can specify the version of your artifact source. By default, releases use the latest version of the source artifact. You can also choose to use the latest build from a specific branch by specifying the tags, a specific version, or allow the user to specify the version at the time of release creation. +:::image type="content" source="media/classic-release-pipeline-add-artifact-souce.png" alt-text="A screenshot that shows how to add an artifact to a classic release pipeline."::: -:::image type="content" source="media/artifacts-02.png" alt-text="Screenshot showing how to add an artifact to a classic release pipeline."::: +If you link multiple artifacts, you can specify which one is the primary source (default). The primary artifact source is used to set several predefined [variables](variables.md#release-artifacts-variables) and can also be used for [naming releases](index.md#q-how-do-i-manage-the-naming-of-new-releases). -If you link more than one artifact, you can specify which one is the primary source (default). The primary artifact source is used to set a number of predefined [variables](variables.md#artifact-variables). It can also be used in [naming releases](index.md#numbering). +:::image type="content" source="media/classic-release-pipeline-set-primary-souce.png" alt-text="A screenshot that shows how to set a primary source artifact."::: +The **Default version** dropdown options depend on the source type of the linked build definition. The options `Specify at the time of release creation`, `Specific version`, and `Latest` are supported by all repository types. However, the `Latest from the build pipeline default branch with tags` is not supported by *XAML* build definitions. -:::image type="content" source="media/artifacts-02a.png" alt-text="Screenshot showing how to set a primary source artifact."::: +The following sections describe how to work with the different types of artifact sources: -> [!NOTE] -> The `Default version` dropdown items depend on the source type of the linked build definition. - -- The following options are supported by all the repository types: `Specify at the time of release creation`, `Specific version`, and `Latest`. - -- `Latest from a specific branch with tags` and `Latest from the build pipeline default branch with tags` options are supported by the following repository types: `TfsGit`, `GitHub`, `Bitbucket`, and `GitHubEnterprise`. - -- `Latest from the build pipeline default branch with tags` is not supported by `XAML` build definitions. - -The following sections describe how to work with the different types of artifact sources. - -- [Azure Pipelines](#artifact-sources---azure-pipelines) -- [Version control](#artifact-sources---version-control) -- [Jenkins](#artifact-sources---jenkins) -- [Azure Container Registry, Docker, and Kubernetes](#artifact-sources---containers) -- [Azure Artifacts](#artifact-sources---azure-artifacts) -- [TFS server](#artifact-sources---tfs-server) -- [TeamCity](#artifact-sources---teamcity) +>[!div class="checklist"] +> - [Azure Pipelines](#azure-pipelines) +> - [Azure Repos, GitHub, and TFVC](#azure-repos-github-and-tfvc) +> - [Azure Artifacts](#azure-artifacts) +> - [Azure Container Repository and Docker Hub](#azure-container-repository-and-docker-hub) +> - [Jenkins](#jenkins) -## Artifact sources - Azure Pipelines +> [!NOTE] +> When using multiple artifact sources, mapping an artifact source to trigger a particular stage is not supported. If you need this functionality, Azure Pipelines recommends splitting your release pipeline into multiple releases. -You can link a release pipeline to any Azure Pipelines build. You can also link multiple build pipelines and specify their default values and set up deployment triggers on multiple build sources. When any of the builds completes, it will trigger the creation of a release. +## Azure Pipelines -The following features are available when using Azure Pipelines as an artifact source: +You can link your Classic release pipeline to any pipeline artifact. Additionally, you can link multiple artifacts and set up deployment triggers on multiple build sources. This setup will create a release each time a new build becomes available. The following features are available when using Azure Pipelines as an artifact source: | Feature | Description | |---------|----------------------------------| -| Auto-trigger releases | New releases can be created automatically when a new build artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| -| Artifact variables | A number of [artifact variables](variables.md#artifact-variables) are supported fo Azure Pipelines sources. | -| Work items and commits | You can link Azure Pipelines work items and it will be displayed in the releases details. Commits are displayed when you use Git or TFVC source controls.| -| Artifact download | By default, build artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](../process/phases.md#agent-phase) your artifact. | -| Deployment stages | The build summary list all the deployment stages where the artifact was deployed to. | +| Auto-trigger releases | New releases can be created automatically when a new artifact is available (including XAML builds). See [Classic release triggers](triggers.md) for more details.| +| Artifact variables | A number of [artifact variables](variables.md#release-artifacts-variables) are supported for artifacts referenced in a Classic release. | +| Work items and commits | Link work items to see them displayed in the release details. Commits will be shown when using Git or TFVC.| +| [Artifact download](#artifact-download) | By default, pipeline artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](/azure/devops/pipelines/yaml-schema/steps-download) the artifact if needed. | +| Deployment stages | The pipeline summary lists all the deployment stages where the artifact has been deployed. | > [!NOTE] -> You must include a **Publish Artifacts** task in your build pipeline. For YAML build pipelines, an artifact with the name **drop** is published implicitly. +> To publish your pipeline artifact in a Classic pipeline, you must add a [PublishPipelineArtifact](/azure/devops/pipelines/tasks/reference/publish-pipeline-artifact-v1) task to your pipeline. In YAML pipelines, a **drop** artifact is published implicitly. -::: moniker range="> azure-devops-2022" +::: moniker range="azure-devops" -By default, releases run with a collection level job authorization scope. This means that releases can access resources in all projects in the organization (or collection for Azure DevOps Server). This is useful when linking build artifacts from other projects. You can enable **Limit job authorization scope to current project for release pipelines** in project settings to restrict access to a project's artifact. +### Limit job authorization scope -**To set job authorization scope for the organization**: +By default, releases run with an organization-level job authorization scope, allowing them to access resources across all projects in the organization. This is useful when linking pipeline artifacts from other projects. To restrict access to a project's artifacts, you can enable **Limit job authorization scope to current project for release pipelines** in the project settings -- Navigate to your **Organization settings**. -- Select **Settings** under Pipelines. -- Turn on the toggle **Limit job authorization scope to current project for release pipelines** to limit the scope to current project. This is the recommended setting for a good security measures. +**To set the job authorization scope for the organization**: -**To set job authorization scope for a specific project**: +1. Sign in to your Azure DevOps organization. -- Navigate to your **Project settings**. -- Select **Settings** under Pipelines. -- Turn on the toggle **Limit job authorization scope to current project for release pipelines** to limit the scope to the current project. This is the recommended setting, as it enhances security for your pipelines. +1. Select **Organization settings** at the bottom left. -> [!NOTE] -> If the scope is set to project at the organization level, you cannot change the scope in each project. +1. Select **Pipelines** > ***Settings**. -::: moniker-end +1. Turn on the toggle **Limit job authorization scope to current project for release pipelines** to restrict the scope to the current project. This is recommended to enhance security. -::: moniker range="< azure-devops" + :::image type="content" source="media/authorization-scope-organization-level.png" alt-text="A screenshot that shows how to set the job authorization scope for the organization."::: -All jobs in a release run with the job authorization scope set to collection. In other words, these jobs have access to resources in all projects in your project collection. +**To set the job authorization scope for a specific project**: -::: moniker-end +1. Sign in to your Azure DevOps organization, and then navigate to your project. -## Artifact sources - version control +1. Select **Project settings** at the bottom left. -There are some scenarios in which you may want to consume artifacts from different source controls directly without passing them through a build pipeline. For example: +1. Select **Pipelines** > ***Settings**. -- Developing a PHP or a JavaScript application that doesn't require an explicit build pipeline. +1. Turn on the toggle **Limit job authorization scope to current project for release pipelines** to restrict the scope to the current project. This setting is recommended for enhancing the security of your pipelines. -- You manage configurations for various stages in different version control repositories, and you want to consume these configuration files directly from version control as part of the deployment pipeline. + :::image type="content" source="media/authorization-scope-project-level.png" alt-text="A screenshot that shows how to set the job authorization scope for a project."::: -- You manage your infrastructure and configuration as code and you want to manage these files in a version control repository. +> [!NOTE] +> If the scope is set at the organization level, it cannot be changed individually in each project. -Because you can configure multiple artifact sources in a single release pipeline, you can link both a build pipeline that produces the binaries of your application as well as a version control repository that stores the configuration files into the same pipeline, and use the two sets of artifacts together while deploying. +::: moniker-end -Azure Pipelines supports Team Foundation Version Control (TFVC) repositories, Git repositories, and GitHub repositories. +::: moniker range="< azure-devops" + +> [!NOTE] +> By default, releases run with a collection-level job authorization scope, allowing them to access resources across all projects in the collection. -You can link a release pipeline to any of the Git or TFVC repositories in any project in your collection (you'll need read access to these repositories). No additional setup is required when deploying version control artifacts within the same collection. +::: moniker-end -When you link a GitHub repository and select a branch, you can edit the default properties of the artifact types after the artifact has been saved. This is particularly useful in scenarios where the branch for the stable version of the artifact changes, and continuous delivery releases should use this branch to obtain newer versions of the artifact. You can also specify details of the checkout, such as whether checkout submodules and LFS-tracked files, and the shallow fetch depth. +## Azure Repos, GitHub, and TFVC -When you link a TFVC branch, you can specify the changeset to be deployed when creating a release. +There are scenarios where you might want to consume artifacts directly from different source controls without passing them through a build pipeline. For example: -The following features are available when using TFVC, Git, and GitHub as an artifact source: +- Developing a PHP or JavaScript application that doesn't require an explicit build pipeline. -| Feature | Description | -|---------|----------------------------------| -| Auto-trigger releases | New releases can be created automatically when a new build artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| -| Artifact variables | A number of [artifact variables](variables.md#artifact-variables) are supported fo Azure Pipelines sources. | -| Work items and commits | You can link Azure Pipelines work items are it will be displayed in the releases details. Commits are displayed when you use Git or TFVC source controls.| -| Artifact download | By default, build artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](../process/phases.md#agent-phase) your artifact. | +- Managing configurations for various stages in different version control repositories, and consuming these configuration files directly as part of the deployment pipeline. -::: moniker range="> azure-devops-2022" +- Managing infrastructure and configuration as code in a version control repository. -By default, releases run with a collection level job authorization scope. This means that releases can access resources in all projects in the organization (or collection for Azure DevOps Server). This is useful when linking build artifacts from other projects. You can enable **Limit job authorization scope to current project for release pipelines** in project settings to restrict access to a project's artifact. +With Azure Pipelines, you can configure multiple artifact sources in a single release pipeline. This allows you to link a build pipeline that produces application binaries and a version control repository that stores configuration files, using both sets of artifacts together during deployment. -::: moniker-end +Azure Pipelines supports Azure Repos, Team Foundation Version Control (TFVC), and GitHub repositories. You can link a release pipeline to any Git or TFVC repository within your project collection, provided you have read access. No additional setup is required when deploying version control artifacts within the same collection. -## Artifact sources - Jenkins +When linking a GitHub repository and selecting a branch, you can edit the default properties of the artifact types after saving the artifact. This is useful if the stable version branch changes, ensuring continuous delivery releases use the correct branch for newer artifact versions. You can also specify checkout details, such as **submodules**, **Git-LFS tracked files** inclusion, and **shallow fetch depth**. -To consume Jenkins artifacts, you must create a service connection to authenticate with your Jenkins server. See [manage service connections](../library/service-endpoints.md) and [Jenkins service connection](../library/service-endpoints.md#jenkins-service-connection) for more information. The Jenkins project must be configured with a post build action to publish your artifacts. +When linking a TFVC branch, you can specify the changeset to be deployed during release creation. -The following features are available when using Jenkins as an artifact source: +The following features are available when using Azure Repos, Git, and TFVC as an artifact source: | Feature | Description | |---------|----------------------------------| -| Auto-trigger releases | New releases can be created automatically when a new build artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| -| Artifact variables | A number of [artifact variables](variables.md#artifact-variables) are supported fo Azure Pipelines sources. | -| Work items and commits | You can link Azure Pipelines work items and it will be displayed in the releases details. Commits are displayed when you use Git or TFVC source controls.| -| Artifact download | By default, build artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](../process/phases.md#agent-phase) your artifact. | +| Auto-trigger releases | New releases can be created automatically when a new artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| +| Artifact variables | A number of [artifact variables](variables.md#release-artifacts-variables) are supported for artifacts referenced in a Classic release. | +| Work items and commits | Link work items to see them displayed in the release details. Commits will be shown when using Git or TFVC.| +| [Artifact download](#artifact-download) | By default, pipeline artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](/azure/devops/pipelines/yaml-schema/steps-download) the artifact if needed. | -Artifacts generated by Jenkins builds are typically propagated to storage repositories for archiving and sharing. Azure blob storage is one of the supported repositories, allowing you to consume Jenkins projects that publish to Azure storage as artifact sources in a release pipeline. Azure Pipelines download the artifacts automatically from Azure to the agent running the pipeline. In this scenario, connectivity between the agent and the Jenkins server is not required. Microsoft-hosted agents can be used without exposing the server to internet. +::: moniker range="azure-devops" > [!NOTE] -> Azure Pipelines may not be able to contact your Jenkins server if, for example, it is within your enterprise network. If this is the case, you can integrate Azure Pipelines with Jenkins by setting up an on-premises agent that can access the Jenkins server. You will not be able to see the name of your Jenkins projects when linking to a build, but you can enter the name in the URL text field. +> By default, releases run with organization-level job authorization scope, allowing them to access resources across all projects in the organization. This is useful when linking pipeline artifacts from other projects. To restrict access to a project's artifacts, enable **Limit job authorization scope to current project for release pipelines** in the project settings. -## Artifact sources - containers - -When deploying containerized apps, the container image is first pushed to a container registry. You can then deploy your container image to Azure Web App for Containers or a Docker/Kubernetes cluster. You must create a service connection to authenticate with Azure. See [manage service connections](../library/service-endpoints.md) for more details. - -The following features are available when using Azure Container as an artifact source: +::: moniker-end -| Feature | Description | -|---------|----------------------------------| -| Auto-trigger releases | New releases can be created automatically when a new build artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| -| Artifact variables | A number of [artifact variables](variables.md#artifact-variables) are supported fo Azure Pipelines sources. | -| Work items and commits | You can link Azure Pipelines work items and it will be displayed in the releases details. Commits are displayed when you use Git or TFVC source controls.| -| Artifact download | By default, build artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](../process/phases.md#agent-phase) your artifact. | +::: moniker range="< azure-devops" > [!NOTE] -> When using multiple artifact sources, mapping an artifact source to trigger a particular stage is not supported. A release will be created anytime there is a push to any of the artifact sources. If you wish to do so, Azure Pipelines recommend splitting your release pipeline into multiple releases. +> By default, releases run with collection-level job authorization scope, allowing them to access resources across all projects in the collection. This is useful when linking pipeline artifacts from other projects. To restrict access to a project's artifacts, enable **Limit job authorization scope to current project for release pipelines** in the project settings. + +::: moniker-end -## Artifact sources - Azure Artifacts +## Azure Artifacts Below are some of the scenarios where you can use Azure Artifacts as an artifact source: -1. Your application binary is published to Azure Artifacts and you want to consume the package in a release pipeline. -1. You need additional packages stored in Azure Artifacts as part of your deployment workflow. +- Your application binary is published to Azure Artifacts, and you want to consume the package in a release pipeline. -Using Azure Artifacts in your release pipeline, you must select the *Feed*, *Package*, and the *Default version* for your package. You can choose to pick up the *latest version of the package*, use a *specific version*, or *select the version at the time of release creation*. During deployment, the package gets downloaded/extracted to the agent running your pipeline. +- You need additional packages stored in Azure Artifacts as part of your deployment workflow. + +When using Azure Artifacts in your release pipeline, you must select the **Feed**, **Package**, and the **Default version** for your package. You can choose to pick up the **latest** version of the package, use a **specific version**, or **specify at the time of release creation**. During deployment, the package is downloaded to the agent running your pipeline. The following features are available when using Azure Artifacts as an artifact source: | Feature | Description | |---------|----------------------------------| -| Auto-trigger releases | New releases can be created automatically when a new build artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| -| Artifact variables | A number of [artifact variables](variables.md#artifact-variables) are supported fo Azure Pipelines sources. | -| Work items and commits | You can link Azure Pipelines work items and it will be displayed in the releases details. Commits are displayed when you use Git or TFVC source controls.| -| Artifact download | By default, build artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](../process/phases.md#agent-phase) your artifact. | +| Auto-trigger releases | New releases can be created automatically when a new artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| +| Artifact variables | A number of [artifact variables](variables.md#release-artifacts-variables) are supported for artifacts referenced in a Classic release. | +| Work items and commits | Link work items to see them displayed in the release details. Commits will be shown when using Git or TFVC.| +| [Artifact download](#artifact-download) | By default, pipeline artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](/azure/devops/pipelines/yaml-schema/steps-download) the artifact if needed. | #### Handling Maven snapshots -When using Maven snapshots, multiple versions can be downloaded at once (example `myApplication-2.1.0.BUILD-20190920.220048-3.jar`, `myApplication-2.1.0.BUILD-20190820.221046-2.jar`, `myApplication-2.1.0.BUILD-20190820.220331-1.jar`). You might need to remove the old version and only keep the latest Artifact before deployment. Run the following PowerShell command in an elevated command prompt to remove all copies except the one with the highest lexicographical value: +When using Maven snapshots, multiple versions can be downloaded at once (example `myApplication-2.1.0.BUILD-20190920.220048-3.jar`, `myApplication-2.1.0.BUILD-20190820.221046-2.jar`, `myApplication-2.1.0.BUILD-20190820.220331-1.jar`). You might need to remove the old versions and only keep the latest artifact before deployment. + +Run the following command in a PowerShell prompt to remove all copies except the one with the highest lexicographical value: ```PowerShell Get-Item "myApplication*.jar" | Sort-Object -Descending Name | Select-Object -SkipIndex 0 | Remove-Item ``` > [!NOTE] -> You can store up to 30 Maven snapshots in your feed. Once you reach the maximum limit, Azure Artifacts will automatically delete snapshots down to 25. This process will be triggered automatically every time 30+ snapshots are published to your feed. +> You can store up to 30 Maven snapshots in your feed. Once this limit is reached, Azure Artifacts will automatically delete older snapshots to keep only the most recent 25. -## Artifact sources - TFS server +## Azure Container Repository and Docker Hub -You can use Azure Pipelines to deploy artifacts from TFS servers without having to make your server discoverable on the Internet by setting up an on-premises automation agent. Artifacts are downloaded to the on-premises agent and then deployed to the specified target servers without leaving your enterprise network. This is ideal for customers to leverage their investments of their on-premises infrastructure while taking advantage of Azure Pipelines releases. +When deploying containerized apps, the container image is first pushed to a container registry. You can then deploy your container image to Azure Web App for Containers or a Docker/Kubernetes cluster. To do this, you must first create a service connection to authenticate with Azure or Docker Hub. See [Docker Registry service connection](../library/service-endpoints.md#docker-registry-service-connection) for more details. -To use TFS servers as an artifact source, you must install the [TFS artifacts for Azure Pipelines](https://marketplace.visualstudio.com/items?itemName=ms-vscs-rm.vss-services-externaltfs) extension from the Visual Studio Marketplace, and then create a [service connection](../library/service-endpoints.md) to authenticate with Azure Pipelines. Once authenticated, you can then link a TFS build pipeline to your release pipeline and choose **External TFS Build** from the *Type* dropdown menu. - -The following features are available when using TFS servers as an artifact source: +The following features are available when using Azure Container Repository or Docker Hub as an artifact source: | Feature | Description | |---------|----------------------------------| -| Auto-trigger releases | New releases can be created automatically when a new build artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| -| Artifact variables | A number of [artifact variables](variables.md#artifact-variables) are supported fo Azure Pipelines sources. | -| Work items and commits | You can link Azure Pipelines work items and it will be displayed in the releases details. Commits are displayed when you use Git or TFVC source controls.| -| Artifact download | By default, build artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](../process/phases.md#agent-phase) your artifact. | - -Azure Pipelines may not be able to contact an on-premises TFS server in case it's within your enterprise network. In that case you can integrate Azure Pipelines with TFS by setting up an on-premises agent that can access the TFS server. You will not be able to see the name of your TFS projects or build pipelines when linking to a build, but you can include those variables in the URL text fields. In addition, when you create a release, Azure Pipelines may not be able to query the TFS server for the build numbers. Instead, enter the *Build ID* (not the build number) of the desired build in the appropriate field, or select the *Latest* build. +| Auto-trigger releases | New releases can be created automatically when a new artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| +| Artifact variables | A number of [artifact variables](variables.md#release-artifacts-variables) are supported for artifacts referenced in a Classic release. | +| Work items and commits | Link work items to see them displayed in the release details. Commits will be shown when using Git or TFVC.| +| [Artifact download](#artifact-download) | By default, pipeline artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](/azure/devops/pipelines/yaml-schema/steps-download) the artifact if needed. | -## Artifact sources - TeamCity +## Jenkins -To use TeamCity as an Artifact source, you must first install the [TeamCity artifacts for Azure Pipelines](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.vss-services-teamcity) extension from Visual Studio Marketplace. +To consume Jenkins artifacts, you must create a service connection to authenticate with your Jenkins server. See [Jenkins service connection](../library/service-endpoints.md#jenkins-service-connection) for more details. Additionally, your Jenkins project must be configured with a post-build action to publish your artifacts. -Once completed, create a [service connection](../library/service-endpoints.md) to authenticate with your TeamCity server. You can then link your build artifact to a release pipeline. The TeamCity build configuration must be set up with an action to publish artifacts. +Artifacts generated by Jenkins builds are typically propagated to storage repositories for archiving and sharing. Azure Blob Storage is one such repository, allowing you to use Jenkins projects that publish to Azure Storage as artifact sources in a release pipeline. Azure Pipelines will automatically download these artifacts from Azure to the agent running the pipeline. In this scenario, connectivity between the agent and the Jenkins server is not required, and Microsoft-hosted agents can be used without exposing the Jenkins server to the internet. -The following features are available when using TeamCity as an artifact source: +The following features are available when using Jenkins as an artifact source: | Feature | Description | |---------|----------------------------------| -| Auto-trigger releases | New releases can be created automatically when a new build artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| -| Artifact variables | A number of [artifact variables](variables.md#artifact-variables) are supported fo Azure Pipelines sources. | -| Work items and commits | You can link Azure Pipelines work items and it will be displayed in the releases details. Commits are displayed when you use Git or TFVC source controls.| -| Artifact download | By default, build artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](../process/phases.md#agent-phase) your artifact. | +| Auto-trigger releases | New releases can be created automatically when a new artifact is available (including XAML builds). See [Release triggers](triggers.md) for more details.| +| Artifact variables | A number of [artifact variables](variables.md#release-artifacts-variables) are supported for artifacts referenced in a Classic release. | +| Work items and commits | Link work items to see them displayed in the release details. Commits will be shown when using Git or TFVC.| +| [Artifact download](#artifact-download) | By default, pipeline artifacts are downloaded to the agent running the pipeline. You can also configure a step in your stage to [skip downloading](/azure/devops/pipelines/yaml-schema/steps-download) the artifact if needed. | -Azure Pipelines may not be able to contact your TeamCity server if, for example, it is within your enterprise network. In this case you can integrate Azure Pipelines with TeamCity by setting up an on-premises agent that can access the TeamCity server. You will not be able to see the name of your TeamCity projects when linking to a build, but you can type this into the URL text field. +> [!NOTE] +> Azure Pipelines may not be able to ping your Jenkins server if it is within a private enterprise network. In such cases, you can integrate Azure Pipelines with Jenkins by setting up an on-premises agent that has access to the Jenkins server. While you may not see the names of your Jenkins projects when linking to a pipeline, you can manually enter the project name in the URL text field. ## Artifact source alias -To ensure the uniqueness of every artifact download, each artifact source linked to a release pipeline is automatically provided with a specific download location known as the *source alias*. This location can be accessed by using the variable: `$(System.DefaultWorkingDirectory)\[source alias]` +To ensure the uniqueness of each artifact download, every artifact source linked to a release pipeline is automatically assigned a specific download location known as the *source alias*. This location can be accessed using the variable: `$(System.DefaultWorkingDirectory)\[source alias]`. -Using a source aliases ensures that renaming a linked artifact source doesn't require editing the task properties because the download location defined in the agent does not change. +Using source aliases ensures that renaming a linked artifact source does not require editing the task properties, as the download location defined in the agent remains unchanged. -By default, the source alias is the name of the artifact source prefixed with an underscore. Depending on the type of the artifact source, this will be the name of the build pipeline, job name, project name, or the repository name. You can edit the source alias from the artifacts tab of your release pipeline. +By default, the source alias is the name of the artifact source prefixed with an underscore (e.g., _mslearn-tailspin-spacegame-web). The source alias can correspond to the name of the build pipeline, job name, project name, or repository name, depending on the artifact source type. You can edit the source alias from the artifacts tab in your release pipeline.m the artifacts tab of your release pipeline. ## Artifact download -When a deployment is completed to a stage, the versioned artifacts from each of the sources are downloaded to the pipeline agent so that tasks running within that stage can access those artifacts. The downloaded artifacts do not get deleted when a release is completed. However, when you initiate the next release, the downloaded artifacts are deleted and replaced with the new set of artifacts. +When a deployment to a stage is completed, versioned artifacts from each source are downloaded to the pipeline agent so that tasks within that stage can access them. These downloaded artifacts are not deleted when a release completes. However, when a new release is initiated, the previous artifacts are deleted and replaced with the new ones. + +A unique folder is created on the agent for each release pipeline when a release is initiated, and artifacts are downloaded to this folder:`$(System.DefaultWorkingDirectory)`. -A new unique folder in the agent is created for every release pipeline when a release is initiated, and the artifacts are downloaded to the following folder:`$(System.DefaultWorkingDirectory)`. +Azure Pipelines does not perform any optimization to avoid re-downloading the unchanged artifacts if the same release is deployed again. Additionally, since previously downloaded contents are deleted when a new release is started, Azure Pipelines cannot perform incremental downloads to the agent. -Azure Pipelines does not perform any optimization to avoid downloading the unchanged artifacts if the same release is deployed again. In addition, because the previously downloaded contents are always deleted when you initiate a new release, Azure Pipelines cannot perform incremental downloads to the agent. +::: moniker range="azure-devops" + +To skip automatic artifact downloads, navigate to your **Release pipeline** > **Tasks** > **Agent job** > **Artifact download** and uncheck all artifacts or specify particular artifacts to be skipped. + +:::image type="content" source="media/skip-automatic-download-devops-services.png" alt-text="A screenshot that shows how to skip automatic artifact download in a Classic release pipeline on Azure DevOps Services."::: + +::: moniker-end ::: moniker range="< azure-devops" -You can however, set up your pipeline to [skip automatic download](../process/phases.md#artifact-download) for a specific job or stage if you wish to do so. +To skip automatic artifact downloads, navigate to your **Release pipeline** > **Tasks** > **Agent job** > **Additional options**, and check the **Skip download of artifacts** checkbox. + +:::image type="content" source="media/skip-automatic-download-server.png" alt-text="A screenshot that shows how to skip automatic artifact download in a Classic release pipeline on Azure DevOps Server."::: ::: moniker-end ## Related articles -- [Classic release and artifacts variables](variables.md#artifact-variables) -- [Classic release pipelines](index.md) +- [Deploy from multiple branches](deploy-multiple-branches.md) - [Publish and download pipeline Artifacts](../artifacts/pipeline-artifacts.md) -- [Add stages, dependencies, & conditions](../process/stages.md) +- [Artifacts variables](variables.md) diff --git a/docs/pipelines/release/azure-key-vault.md b/docs/pipelines/release/azure-key-vault.md index f7db0f5a668..4984378db7d 100644 --- a/docs/pipelines/release/azure-key-vault.md +++ b/docs/pipelines/release/azure-key-vault.md @@ -1,10 +1,10 @@ --- title: Use Azure Key Vault secrets in Azure Pipelines -description: How to create Azure Key vaults, store secrets, and use those secrets in your Azure Pipelines +description: How to create Azure Key vaults, store secrets, and use them in your Azure Pipelines. ms.topic: tutorial -ms.date: 05/16/2022 -ms.custom: contperf-fy21q3, devx-track-azurecli -monikerRange: '>= azure-devops-2019' +ms.date: 04/23/2024 +ms.custom: devx-track-azurecli, arm2024 +monikerRange: '>= azure-devops' "recommendations": "true" --- @@ -12,7 +12,8 @@ monikerRange: '>= azure-devops-2019' [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Azure Key Vault enables developers to securely store and manage secrets such as API keys, credentials or certificates. Azure Key Vault service supports two types of containers: vaults and managed HSM (hardware security module) pools. Vaults support storing software and HSM-backed keys, secrets, and certificates, while managed HSM pools only support HSM-backed keys. +Azure Key Vault allows developers to securely store and manage sensitive information like API keys, credentials, or certificates. +Azure Key Vault service supports two types of containers: vaults and managed HSM (Hardware Security Module) pools. Vaults can store both software and HSM-backed keys, secrets, and certificates, while managed HSM pools exclusively support HSM-backed keys. In this tutorial, you will learn how to: @@ -24,112 +25,250 @@ In this tutorial, you will learn how to: ## Prerequisites -* An Azure DevOps organization. If you don't have one, you can [create one for free](../get-started/pipelines-sign-up.md). -* An Azure subscription. [Create an Azure account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) if you don't have one already. +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. -## Create an Azure Key Vault +- An Azure subscription. [Create an Azure account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) if you don't have one already. -[!INCLUDE [include](../ecosystems/includes/sign-in-azure-cli.md)] +## Get the sample code -1. If you have more than one Azure subscription associated with your account, use the command below to specify a default subscription. You can use `az account list` to generate a list of your subscriptions. +If you already have your own repository, proceed to the next step. Otherwise, import the following sample repository into your Azure Repo. - ```azurecli - az account set --subscription +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Repos**, and then select **Import**. Enter the following repository URL, and then select **Import**. + + ``` + https://github.com/MicrosoftDocs/pipelines-dotnet-core ``` -1. Set your default Azure region. You can use `az account list-locations` to generate a list of available regions. +## Create an Azure Key Vault + +1. Sign in to the [Azure portal](https://portal.azure.com/), and then select the [Cloud Shell](/azure/cloud-shell/overview) button in the upper-right corner. + +1. If you have more than one Azure subscription associated with your account, use the command below to specify a default subscription. You can use `az account list` to generate a list of your subscriptions. ```azurecli - az config set defaults.location= + az account set --subscription ``` - For example, this command will select the westus2 region: +1. Set your default Azure region. You can use `az account list-locations` to generate a list of available regions. ```azurecli - az config set defaults.location=westus2 + az config set defaults.location= ``` -1. Create a new resource group. A resource group is a container that holds related resources for an Azure solution. +1. Create a new resource group. ```azurecli - az group create --name + az group create --name ``` -1. Create a new key vault. +1. Create a new Azure Key Vault. ```azurecli az keyvault create \ - --name \ - --resource-group + --name \ + --resource-group ``` 1. Create a new secret in your Azure key vault. ```azurecli az keyvault secret set \ - --name "Password" \ - --value "mysecretpassword" \ - --vault-name + --name \ + --value \ + --vault-name ``` -## Create a project +## Set up authentication -1. Sign in to your [Azure DevOps organization](https://dev.azure.com/). +# [Managed Identity](#tab/managedidentity) -1. If you don't have any projects in your organization yet, select **Create a project to get started**. Otherwise, select **New project** in the upper-right corner. +## Create a user-assigned managed identity -## Create a repo +1. Sign in to the [Azure portal](https://portal.azure.com/), then search for the **Managed Identities** service in the search bar. -We will use YAML to create our pipeline but first we need to create a new repo. +1. Select Create, and fill out the required fields as follows: -1. Sign in to your Azure DevOps organization and navigate to your project. + - **Subscription**: Select your subscription from the dropdown menu. + - **Resource group**: Select an existing resource group or create a new one. + - **Region**: Select a region from the dropdown menu. + - **Name**: Enter a name for your user-assigned managed identity. -1. Select **Repos**, and then select **Initialize** to initialize a new repo with a README. +1. Select **Review + create** when you're done. - :::image type="content" border="false" source="media/azure-key-vault/initialize-repo.png" alt-text="A screenshot showing how to initialize a repository."::: +1. Once the deployment is complete, select **Go to resource**, then copy the **Subscription** and **Client ID** values to use in upcoming steps. -## Create a new pipeline +1. Navigate to **Settings** > **Properties**, and copy your managed identity's **Tenant ID** value for later use. -#### [YAML](#tab/yaml) +## Set up key vault access policies -1. Select **Pipelines**, and then select **New Pipeline**. +1. Navigate to [Azure portal](https://portal.azure.com/), and use the search bar to find the key vault you created earlier. -1. Select **Azure Repos Git** (YAML). +1. Select **Access policies**, then select **Create** to add a new policy. - :::image type="content" border="false" source="media/azure-key-vault/create-pipeline.png" alt-text="A screenshot showing how to select Azure Repos source control."::: +1. Under **Secret permissions**, select **Get** and **List** checkboxes. -1. Select the repository you created in the previous step. +1. Select **Next**, then paste the **Client ID** of the managed identity you created earlier into the search bar. Select your managed identity. -1. Select the **Starter pipeline** template. +1. Select **Next**, then **Next** once more. -1. The default pipeline will include a few scripts that run echo commands. Those are not needed so we can delete them. Your new YAML file should look like this: +1. Review your new policies, and then select **Create** when you're done. - ```YAML - trigger: - - main +## Create a service connection + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Project settings** > **Service connections**, and then select **New service connection** to create a new service connection. + +1. Select **Azure Resource Manager**, then select **Next**. + +1. For **Identity Type**, select **Managed identity** from the dropdown menu. + +1. For **Step 1: Managed identity details**, fill out the fields as follows: + + - **Subscription for managed identity**: Select the subscription containing your managed identity. - pool: - vmImage: 'ubuntu-latest' + - **Resource group for managed identity**: Select the resource group hosting your managed identity. - steps: - ``` + - **Managed Identity**: Select your managed identity from the dropdown menu. + +1. For **Step 2: Azure Scope**, fill out the fields as follows: + + - **Scope level for service connection**: Select Subscription. + + - **Subscription for service connection**: Select the subscription your managed identity will access. + + - **Resource group for Service connection**: (Optional) Specify to limit managed identity access to one resource group. + +1. For **Step 3: Service connection details**: + + - **Service connection name**: Provide a name for your service connection. + + - **Service Management Reference**: (Optional) Context information from an ITSM database. + + - **Description**: (Optional) Add a description. + +1. In **Security**, select the **Grant access permission to all pipelines** checkbox to allow all pipelines to use this service connection. If you don't select this option, you must manually grant access to each pipeline that uses this service connection. + +1. Select **Save** to validate and create the service connection. + + :::image type="content" border="false" source="media/managed-identity-service-connection.png" alt-text="A screenshot displaying how to create a managed identity ARM service connection." lightbox="media/managed-identity-service-connection.png"::: + +# [Service Principal](#tab/serviceprincipal) + +## Set up key vault access policies + +To access your Azure Key Vault, you must first set up a service principal to grant access to Azure Pipelines: + +1. [Create a service principal](/cli/azure/azure-cli-sp-tutorial-1#create-a-service-principal) + +1. Navigate to [Azure portal](https://portal.azure.com/), and then use the search bar to find the key vault you created earlier. + +1. Select **Access policies**, and then select **Create**. + +1. Under **Secret permissions**, add the **Get** and **List** permissions, and then select **Next**. + +1. For **Principal**, paste your service principal's *Object ID*, select it, and then select **Next**. + +1. Select **Next** once more, review your policies, and then select **Save** when you're done. + +## Add role assignment + +In the next step, you’ll create an ARM service connection for your service principal. Before verifying the connection, you need to: (1) grant the service principal *Read* access at the subscription level, and (2) create a federated credential for your service principal. + +The following steps outline how to grant *Read* access at the subscription level: + +1. Navigate to [Azure portal](https://portal.azure.com/), select **Subscriptions**, and then find and select your subscription. + +1. Select **Access control**, and then select **Add** > **Add role assignment**. + +1. Select **Reader** under the **Role** tab, and then select **Next**. + +1. Select **User, group, or service principal**, and then select **Select members**. + +1. Paste your service principal's Object ID in the search bar, select it, and then **Select**. + +1. Select **Review + assign**, review your settings, and then select **Review + assign** once more to confirm your choices and add the role assignment. + +## Create a service connection + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Project settings**, and then select **Service connections**. + +1. Select **New service connection**, select **Azure Resource Manager**, and then select **Next**. + +1. Select **Service principal (manual)**, and then select **Next**. + +1. For **Identity Type**, select **App registration or managed identity (manual)** from the dropdown menu. + +1. For **Credential**, select **Workload identity federation**. -1. Select **Show assistant** to expand the assistant panel. This panel provides convenient and searchable list of pipeline tasks. +1. Provide a name for your service connection, and then select **Next**. - :::image type="content" border="false" source="media/azure-key-vault/show-assistant.png" alt-text="A screenshot showing how to access the task assistant panel."::: +1. Select **Azure Cloud** for **Environment**, and **Subscription** for the **Subscription scope**. -1. Search for **vault** and select the **Azure Key Vault** task. +1. Enter your Azure **Subscription ID** and **Subscription name**. - :::image type="content" border="false" source="media/azure-key-vault/azure-key-vault-task.png" alt-text="A screenshot showing how to search for the Azure Key Vault task."::: +1. For **Authentication**, paste your service principal's **Application (client) ID** and **Directory (tenant) ID** -1. Select your **Azure subscription** and then select **Authorize**. Select your **Key vault** from the dropdown menu, and then select **Add** to add the task to your YAML pipeline. +1. Under **Security**, select the **Grant access permission to all pipelines** checkbox to allow all pipelines to use this service connection. If you don't select this option, you must manually grant access to each pipeline that uses this service connection. - :::image type="content" border="false" source="media/azure-key-vault/configure-azure-key-vault-task.png" alt-text="A screenshot showing how to configure the Azure Key Vault task."::: +1. Leave this window open, you'll return to verify and save your service connection once you've created the federated credential in Azure. - > [!NOTE] - > The **Make secrets available to whole job** feature is not supported in Azure DevOps Server 2019 and 2020. +## Create a service principal federated credential -1. Your YAML file should look like the following: +1. Navigate to [Azure portal](https://portal.azure.com/), then enter your service principal's *ClientID* in the search bar, and then select your *Application*. + +1. Under **Manage**, select **Certificates & secrets** > **Federated credentials**. + +1. Select **Add credential**, and then for **Federated credential scenario**, select **Other issuer**. + +1. For **Issuer**, paste the *Issuer* you copied from your service connection earlier. + +1. For **Subject identifier**, paste the *Subject identifier* you copied from your service connection earlier. + +1. Provide a **Name** for your federated credential, and then select **Add** when you're done. + +1. Return to your service connection window, select **Verify and Save** to save your service connection. + +--- + +## Access key vault secrets from your pipeline + +#### [YAML](#tab/yaml) + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, and then select **New Pipeline**. + +1. Select **Azure Repos Git** (YAML), and then select your repository. + +1. Select the **Starter pipeline** template. + +1. The default pipeline will include a script that runs echo commands. Those are not needed so we can delete them. + +1. Add the AzureKeyVault task, replacing the placeholders with the name of the service connection you created earlier and your key vault name. Your YAML file should resemble the following snippet: + + ```yml + trigger: + - main + + pool: + vmImage: ubuntu-latest + + steps: + - task: AzureKeyVault@2 + displayName: Azure Key Vault + inputs: + azureSubscription: 'SERVICE_CONNECTION_NAME' + KeyVaultName: 'KEY_VAULT_NAME' + SecretsFilter: '*' + RunAsPreJob: false + ``` + +1. Let's add the following tasks to copy and publish our secret. This example is for demonstration purposes only and should not be implemented in a production environment. ```YAML trigger: @@ -140,109 +279,109 @@ We will use YAML to create our pipeline but first we need to create a new repo. steps: - task: AzureKeyVault@2 + displayName: Azure Key Vault inputs: - azureSubscription: 'Your-Azure-Subscription' - KeyVaultName: 'Your-Key-Vault-Name' + azureSubscription: 'SERVICE_CONNECTION_NAME' + KeyVaultName: 'KEY_VAULT_NAME' SecretsFilter: '*' RunAsPreJob: false - task: CmdLine@2 + displayName: Create file inputs: - script: 'echo $(Your-Secret-Name) > secret.txt' + script: 'echo $(SECRET_NAME) > secret.txt' - task: CopyFiles@2 + displayName: Copy file inputs: Contents: secret.txt targetFolder: '$(Build.ArtifactStagingDirectory)' - task: PublishBuildArtifacts@1 + displayName: Publish Artifact inputs: PathtoPublish: '$(Build.ArtifactStagingDirectory)' ArtifactName: 'drop' publishLocation: 'Container' ``` -#### [Classic](#tab/classic) - -1. Select **Pipelines**, and then select **New Pipeline**. - -1. Select **Use the classic editor** to create a pipeline without YAML. +1. Select **Save and run**, and then select it once more to commit your changes and trigger the pipeline. You may be asked to allow the pipeline access to Azure resources, if prompted select **Allow**. You will only have to approve your pipeline once. -1. Select **Azure Repos Git**, and then select your repository and default branch. Select **Continue** when you are done. - -1. Select the **.Net Desktop** pipeline template. - -1. For this example, we will only need the last two tasks from the template. Press CTRL and then select the first five tasks, right-click and choose **Remove selected tasks(s)** to delete them. - - :::image type="content" border="false" source="media/delete-tasks.png" alt-text="A screenshot showing how to delete pipeline tasks."::: - -1. Select **+** to add a new task. Add the **Command line** task and configure it as follows: - - Display name: Command Line Script. - Script: ```echo $(Your-Secret-Name) > secret.txt``` +1. Select the **CmdLine** task to view the logs. - :::image type="content" border="false" source="media/cmd-task.png" alt-text="A screenshot showing how to configure the command line task."::: + :::image type="content" border="false" source="media/azure-key-vault/command-line-task.png" alt-text="A screenshot showing the command-line task logs."::: -1. Select **+** to add a new task. Add the **Azure Key Vault** task and configure it as follows: +1. Once the pipeline run is complete, return to the pipeline summary and select the published artifact. - Display Name: Azure Key Vault - Azure subscription: Select your Azure subscription from the list, and then select **Authorize**. - Key vault: Select your key vault - Secret filter: A comma separated list of secret names or leave * to download all secrets from the selected key vault. - - :::image type="content" border="false" source="media/key-vault-classic.png" alt-text="A screenshot showing how to configure the Azure Key Vault task."::: + :::image type="content" border="false" source="media/azure-key-vault/pipeline-summary.png" alt-text="A screenshot showing the published artifact in the summary tab."::: -1. Select the **Copy files** task and fill out the required fields. +1. Select **drop** > **secret.txt** to download it. - :::image type="content" border="false" source="media/copy-task.png" alt-text="A screenshot showing how to set up the copy files task."::: + :::image type="content" border="false" source="media/azure-key-vault/view-artifact.png" alt-text="A screenshot showing how to download the published artifact."::: -1. Select the **Publish Artifacts** and keep the default settings. +1. Open the text file you just downloaded, the text file should contain the secret from your Azure key vault. - :::image type="content" border="false" source="media/publish-artifacts.png" alt-text="A screenshot showing how to set up the publish artifacts task."::: +#### [Classic](#tab/classic) -*** +1. Sign in to your Azure DevOps organization, and then navigate to your project. -Don't save or queue your pipeline just yet. We must first give our pipeline the right permissions to access Azure Key Vault. Keep your browser tab open, we will resume the remaining steps once we set up the key vault permissions. +1. Select **Pipelines**, and then select **New Pipeline**. -## Set up Azure Key Vault access policies +1. Select **Use the classic editor** to create a classic pipeline. -In order to access our Azure Key Vault, we must first set up a service principal to give access to Azure Pipelines. Follow [this guide](/azure/active-directory/develop/howto-create-service-principal-portal#register-an-application-with-azure-ad-and-create-a-service-principal) to create your service principal and then proceed with the next steps in this section. +1. Select **Azure Repos Git**, select your repository and default branch, and then select **Continue**. -1. Navigate to [Azure portal](https://azure.microsoft.com/). +1. Select the **.Net Desktop** pipeline template. -1. Use the search bar to search for the key vault you created earlier. +1. For this example, we will only need the last two tasks. Press CTRL and then select the first five tasks, right-click and choose **Remove selected tasks(s)** to delete them. - :::image type="content" border="false" source="media/azure-key-vault/search-azure-key-vault.png" alt-text="A screenshot showing how to search for your Azure Key Vault."::: + :::image type="content" border="false" source="media/delete-tasks.png" alt-text="A screenshot showing how to delete multiple pipeline tasks."::: -1. Under **Settings** Select **Access policies**. +1. Select **+** to add a new task. Search for the **Command line** task, select it, and then select **Add** to add it to your pipeline. Once added, configure it as follows: + + - **Display name**: Create file + - **Script**: `echo $(SECRET_NAME) > secret.txt` -1. Select **Add Access Policy** to add a new policy. + :::image type="content" border="false" source="media/create-secret-file.png" alt-text="A screenshot showing how to configure the command line task."::: -1. For **Secret permissions**, select **Get** and **List**. +1. Select **+** to add a new task. Search for the **Azure Key Vault** task, select it, and then select *Add** to add it to your pipeline. Once added, configure it as follows: -1. Select the option to select a service principal and search for the one you created in the beginning of this section. A security principal is an object that represents a user, group, service, or application that's requesting access to Azure resources. + - **Display name**: Azure Key Vault + - **Azure subscription**: select the service connection you created earlier + - **Key vault**: select your key vault + - **Secret filter**: A comma separated list of secret names or leave * to download all secrets from the selected key vault + + :::image type="content" border="false" source="media/azure-key-vault-classic-task-setup.png" alt-text="A screenshot showing how to set up the Azure Key Vault task in classic pipelines."::: -1. Select **Add** to create the access policy, then select **Save** when you are done. +1. Select the **Copy files** task and fill out the required fields as follows: + + - **Display name**: Copy File + - **Contents**: secret.txt + - **Target Folder**: $(build.artifactstagingdirectory) -## Run and review the pipeline + :::image type="content" border="false" source="media/copy-files-task-classic-pipeline.png" alt-text="A screenshot showing how to set up the copy files task in classic pipelines."::: -1. Return to the previous tab where we left off. +1. Select the **Publish Artifacts** task and fill out the required fields as follows: -1. Select **Save**, and then select **Save** again to commit your changes and trigger the pipeline. You may be asked to allow the pipeline access to Azure resources, if prompted select **Allow**. You will only have to approve your pipeline once. + - **Display name**: Publish Artifact + - **Path to publish**: $(build.artifactstagingdirectory) + - **Artifact name**: drop + - **Artifact publish location**: Azure Pipelines + + :::image type="content" border="false" source="media/publish-artifacts-classic-pipeline.png" alt-text="A screenshot showing how to set up the publish artifacts task in classic pipelines."::: -1. Select the **CmdLine** task to view the logs. +1. Select **Save and queue**, and then select **Run** to run your pipeline. - :::image type="content" border="false" source="media/azure-key-vault/command-line-task.png" alt-text="A screenshot showing the command-line task logs."::: +1. Once the pipeline run is complete, return to the pipeline summary and select the published artifact. -1. Return to pipeline summary and select the published artifact. +1. Select **drop** > **secret.txt** to download the published artifact. - :::image type="content" border="false" source="media/azure-key-vault/pipeline-summary.png" alt-text="A screenshot showing the pipeline summary and the published artifact."::: + :::image type="content" border="false" source="media/azure-key-vault/view-artifact.png" alt-text="A screenshot showing how to download the published artifact."::: -1. Select the **secret.txt** artifact to open it. +1. Open the text file you just downloaded, the text file should contain the secret from your Azure key vault. - :::image type="content" border="false" source="media/azure-key-vault/view-artifact.png" alt-text="A screenshot showing how to open the published artifact."::: -1. The text file should contain our secret: *mysecretpassword*. +*** > [!WARNING] > This tutorial is for educational purposes only. For security best practices and how to safely work with secrets, see [Manage secrets in your server apps with Azure Key Vault](/training/modules/manage-secrets-with-azure-key-vault/). @@ -251,12 +390,12 @@ In order to access our Azure Key Vault, we must first set up a service principal Follow the steps below to delete the resources you created: -1. If you created a new organization to host your project, see [how to delete your organization](../../organizations/accounts/delete-your-organization.md), otherwise [delete your project](../../organizations/projects/delete-project.md). +1. If you've created a new organization to host your project, see [how to delete your organization](../../organizations/accounts/delete-your-organization.md), otherwise [delete your project](../../organizations/projects/delete-project.md). -1. All Azure resources created during this tutorial are hosted under a single resource group *PipelinesKeyVaultResourceGroup*. Run the following command to delete the resource group and all of its resources. +1. All Azure resources created during this tutorial are hosted under a single resource group. Run the following command to delete your resource group and all of its resources. ```azurecli - az group delete --name PipelinesKeyVaultResourceGroup + az group delete --name ``` ## FAQ @@ -265,19 +404,18 @@ Follow the steps below to delete the resources you created: A: If you encounter an error indicating that the user or group does not have secrets list permission on key vault, run the following commands to authorize your application to access the key or secret in the Azure Key Vault: -```PowerShell -$ErrorActionPreference="Stop"; -$Credential = Get-Credential; -Connect-AzAccount -SubscriptionId -Credential $Credential; -$spn=(Get-AzureRmADServicePrincipal -SPN ); -$spnObjectId=$spn.Id; -Set-AzureRmKeyVaultAccessPolicy -VaultName key-vault-tutorial -ObjectId $spnObjectId -PermissionsToSecrets get,list; +```azurecli +az account set --subscription + +az login + +$spnObjectId = az ad sp show --id + +az keyvault set-policy --name --object-id $spnObjectId --secret-permissions get list ``` -## Next steps +## Related articles -> [!div class="nextstepaction"] -> -> [Artifacts in Azure Pipelines](../artifacts/artifacts-overview.md) -> [Publish and download artifacts in Azure Pipelines](../artifacts/pipeline-artifacts.md) -> [Release artifacts and artifact sources](artifacts.md) +- [Publish and download pipeline artifacts](../artifacts/pipeline-artifacts.md) +- [Release artifacts and artifact sources](artifacts.md) +- [Use gates and approvals to control deployment](deploy-using-approvals.md) diff --git a/docs/pipelines/release/azure-rm-endpoint.md b/docs/pipelines/release/azure-rm-endpoint.md index 8323ec52e1d..b110e74216b 100644 --- a/docs/pipelines/release/azure-rm-endpoint.md +++ b/docs/pipelines/release/azure-rm-endpoint.md @@ -1,25 +1,25 @@ --- title: Troubleshoot Azure Resource Manager service connections -ms.custom: seodec18, devx-track-arm-template +ms.custom: devx-track-arm-template, arm2024 description: How to troubleshoot Azure Resource Manager service connections in Azure Pipelines ms.assetid: B43E78DE-5D73-4303-981F-FB86D46F0CAE -ms.topic: conceptual -ms.author: ronai -author: RoopeshNair -ms.date: 03/22/2022 +ms.topic: troubleshooting +ms.author: jukullam +author: juliakm +ms.date: 11/05/2024 +ai-usage: ai-assisted monikerRange: '<= azure-devops' "recommendations": "true" --- -# Troubleshoot ARM service connections +# Troubleshoot Azure Resource Manager service connections [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -This article presents the common troubleshooting scenarios to help you resolve issues you may encounter when creating an Azure Resource Manager service connection. See [Manage service connections](../library/service-endpoints.md) to learn how to create, edit, and secure service connections. +This article presents the common troubleshooting scenarios to help you resolve issues you might encounter when creating an Azure Resource Manager service connection. See [Manage service connections](../library/service-endpoints.md) to learn how to create, edit, and secure service connections. - -## What happens when you create an ARM service connection? +## What happens when you create an Azure Resource Manager service connection If you don't have a service connection, you can create one as follows: @@ -27,64 +27,46 @@ If you don't have a service connection, you can create one as follows: :::image type="content" source="media/service-connections.png" alt-text="Screenshot showing how to access service connections from project settings"::: -1. Select **New service connection** to add a new service connection, and then select **Azure Resource Manager**. Select **Next** when you are done. +1. Select **New service connection** to add a new service connection, and then select **Azure Resource Manager**. Select **Next** when you're done. :::image type="content" source="media/arm-service-connection.png" alt-text="Screenshot showing the service connections types."::: -1. Select **Service principal (automatic)**, and then select **Next. +1. Select **App registration (automatic)** as the Identity type and **Workload identity federation** as the credential. -1. Select **Subscription**, and then select your subscription from the drop-down list. Fill out the form and then select **Save** when you are done. +1. Select **Subscription**, and then select your subscription from the drop-down list. Fill out the rest of the form and then select **Save** when you're done. - :::image type="content" source="media/new-arm-service-connection.png" alt-text="Screenshot showing the new ARM service connection form."::: +When you save your new Azure Resource Manager service connection, Azure DevOps does the following actions: -When you save your new ARM service connection, Azure DevOps then: - -1. Connects to the Azure Active Directory (Azure AD) tenant for to the selected subscription. -1. Creates an application in Azure AD on behalf of the user. -1. After the application has been successfully created, assign the application as a contributor to the selected subscription. +1. Connects to the Microsoft Entra tenant for to the selected subscription. +1. Creates an application in Microsoft Entra ID on behalf of the user. +1. Assigns the application as a contributor to the selected subscription. 1. Creates an Azure Resource Manager service connection using this application's details. > [!NOTE] -> To create service connections you must be added to the Endpoint Creator group in your project settings: **Project settings** > **Service connections** > **Security**. Contributors are added to this group by default. - - +> To create service connections, you need to be assigned the Creator or Administrator role for the Endpoint Creator group in your project settings: **Project settings** > **Service connections** > **More Actions** > **Security**. Project Contributors are added to this group by default. ## Troubleshooting scenarios -Below are some of the issues that may occur when creating service connections: - -- [Insufficient privileges to complete the operation](#privileges) -- [Failed to obtain an access token](#sessionexpired) -- [A valid refresh token was not found](#sessionexpired) -- [Failed to assign contributor role](#contributorrole) -- [Subscription isn't listed when creating a service connection](#subscription-isnt-listed-service-connection) -- [Some subscriptions are missing from the subscription drop down menu](#missingSubscriptions) -- [Automatically created service principal secret has expired](#autoCreatedSecretExpiration) -- [Failed to obtain the JSON Web Token (JWT)](#failedToObtainJWT) -- [Azure subscription is not passed from the previous task output](#azure-subscription-is-not-passed-from-the-previous-task-output) - - - -### Insufficient privileges to complete the operation - -This typically occurs when the system attempts to create an application in Azure AD on your behalf. - -This is a permission issue that may be due to the following causes: - -* [The user has only guest permission in the directory](#guestonly) -* [The user is not authorized to add applications in the directory](#notauthtoadd) - - +The following issues might occur when you create service connections: -#### The user has only guest permission in the directory +- [The user has only guest permission in the directory](#the-user-has-only-guest-permission-in-the-directory) +- [The user isn't authorized to add applications in the directory](#the-user-isnt-authorized-to-add-applications-in-the-directory) +- [Failed to obtain an access token or a valid refresh token wasn't found](#failed-to-obtain-an-access-token-or-a-valid-refresh-token-wasnt-found) +- [Failed to assign Contributor role](#failed-to-assign-contributor-role) +- [Subscription isn't listed when creating a service connection](#subscription-isnt-listed-when-creating-a-service-connection) +- [Some subscriptions are missing from the list of subscriptions](#some-subscriptions-are-missing-from-the-list-of-subscriptions) +- [Service principal's token expired](#service-principals-token-expired) +- [Failed to obtain the JSON web token (JWT) by using the service principal client ID](#failed-to-obtain-the-jwt-by-using-the-service-principal-client-id) +- [Azure subscription isn't passed from the previous task output](#azure-subscription-isnt-passed-from-the-previous-task-output) +- [What authentication mechanisms are supported? How do managed identities work?](#what-authentication-mechanisms-are-supported-how-do-managed-identities-work) -The best approach to resolve this issue, while granting only the minimum additional permissions to the user, is to increase the Guest user permissions as follows. +### The user has only guest permission in the directory -1. Sign in to the Azure portal using an administrator account. The account should be an [owner](/azure/role-based-access-control/built-in-roles#owner), [global administrator](/azure/active-directory/active-directory-assign-admin-roles-azure-portal#global-administrator--company-administrator), or [user account administrator](/azure/active-directory/active-directory-assign-admin-roles-azure-portal#user-administrator-permissions). +1. Sign in to the Azure portal using an administrator account. The account should be an [owner](/azure/role-based-access-control/built-in-roles#owner) or [user account administrator](/azure/role-based-access-control/built-in-roles#user-access-administrator) -1. Select **Azure Active Directory** in the left navigation bar. +1. Select **Microsoft Entra ID** in the left navigation bar. -1. Ensure you are editing the appropriate directory corresponding to the user subscription. If not, select **Switch directory** and log in using the appropriate credentials if required. +1. Ensure you're editing the appropriate directory corresponding to the user subscription. If not, select **Switch directory** and sign in using the appropriate credentials if necessary. 1. Select **Users** from the **Manage** section. @@ -94,46 +76,47 @@ The best approach to resolve this issue, while granting only the minimum additio 1. Change the **Guest user permissions are limited** option to **No**. -Alternatively, if you are prepared to give the user additional permissions (administrator-level), you can make the user a member of the **Global administrator** role. To do so follow the steps below: +Alternatively, if you're prepared to give the user administrator-level permissions, you can make the user a member of an Administrator role. Do the following steps: > [!WARNING] -> Users who are assigned to the Global administrator role can read and modify every administrative setting in your Azure AD organization. As a best practice, we recommend that you assign this role to fewer than five people in your organization. +> Assigning users to the Global Administrator role allows them to read and modify every administrative setting in your Microsoft Entra organization. As a best practice, assign this role to fewer than five people in your organization. -1. Sign in to the Azure portal using an administrator account. The account should be an [owner](/azure/role-based-access-control/built-in-roles#owner), [global administrator](/azure/active-directory/active-directory-assign-admin-roles-azure-portal#global-administrator--company-administrator), or [user account administrator](/azure/active-directory/active-directory-assign-admin-roles-azure-portal#user-administrator-permissions). +1. Sign in to the Azure portal using an administrator account. The account should be an [owner](/azure/role-based-access-control/built-in-roles#owner) or [user account administrator](/azure/role-based-access-control/built-in-roles#user-access-administrator). -1. Select **Azure Active Directory** from the left navigation pane. +1. Select **Microsoft Entra ID** from the left navigation pane. -1. Ensure you are editing the appropriate directory corresponding to the user subscription. If not, select **Switch directory** and log in using the appropriate credentials if required. +1. Ensure you're editing the appropriate directory corresponding to the user subscription. If not, select **Switch directory** and sign in using the appropriate credentials if necessary. 1. Select **Users** from the **Manage** section. 1. Use the search box to search for the user you want to manage. -1. Select **Directory role** from the **Manage** section, and then change the role to **Global administrator**. Select **Save** when you are done. +1. Select **Directory role** from the **Manage** section, and then change the role. Select **Save** when you're done. It typically takes 15 to 20 minutes to apply the changes globally. The user then can try recreating the service connection. - -#### The user is not authorized to add applications in the directory +### The user isn't authorized to add applications in the directory You must have permissions to add integrated applications in the directory. The directory administrator has permissions to change this setting. -1. Select **Azure Active Directory** in the left navigation pane. +1. Select **Microsoft Entra ID** in the left navigation pane. -1. Ensure you are editing the appropriate directory corresponding to the user subscription. If not, select **Switch directory** and log in using the appropriate credentials if required. +1. Ensure you're editing the appropriate directory corresponding to the user subscription. If not, select **Switch directory** and sign in using the appropriate credentials if necessary. 1. Select **Users**, and then select **User settings**. 1. Under **App registrations**, and then change the **Users can register applications** option to **Yes**. -You can also create the service principal with an existing user who already has the required permissions in Azure Active Directory. See [Create an Azure Resource Manager service connection with an existing service principal](../library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-with-an-existing-service-principal) for more information. +::: moniker range="<= azure-devops-2022" - +You can also create the service principal with an existing user who already has the required permissions in Microsoft Entra ID. For more information, see [Create an Azure Resource Manager service connection with an existing service principal](../library/connect-to-azure.md#create-a-service-connection-that-uses-an-existing-service-principal). -### Failed to obtain an access token or a valid refresh token was not found +::: moniker-end -These errors typically occur when your session has expired. To resolve these issues: +### Failed to obtain an access token or a valid refresh token wasn't found + +These errors typically occur when your session is expired. To resolve these issues: 1. Sign out of Azure DevOps. 1. Open an InPrivate or incognito browser window and navigate to [Azure DevOps](https://azure.microsoft.com/services/devops/). @@ -141,75 +124,94 @@ These errors typically occur when your session has expired. To resolve these iss 1. Select your organization and your project. 1. [Create your service connection](../library/service-endpoints.md). - +### Error: You don't appear to have an active Azure subscription when attempting to edit or create a new service connection -### Failed to assign Contributor role +This error typically occurs when you are part of multiple Entra ID tenants. +Follow the below steps to resolve to verify and resolve the issue. -This error typically occurs when you do not have **Write** permission for the selected Azure subscription. +1. Navigate to [VS profile](https://app.vsaex.visualstudio.com/). -To resolve this issue, ask the subscription administrator to [assign you the appropriate role](/azure/active-directory/fundamentals/active-directory-users-assign-role-azure-portal) in Azure Active Directory. +2. Check whether you have multiple tenants. - +3. Select each tenant, and then reauthenticate. -### Subscription isn't listed when creating a service connection +4. Try to create a service connection, and then check whether the subscription loads. -A maximum of 50 Azure subscriptions are listed in the various Azure subscription drop-down menus (billing, service connection, etc.). If you're setting up a service connection and you have more than 50 Azure subscriptions, some of your subscriptions won't be listed. In this scenario, complete the following steps: + -1. Create a new, native Azure AD user in the Azure AD instance of your Azure subscription. +### Failed to assign Contributor role -1. Set up the Azure AD user so that it has the proper permissions to set up billing or create service connections. For more information, see [Add a user who can set up billing for Azure DevOps](../../organizations/billing/add-backup-billing-managers.md). - -1. Add the Azure AD user to the Azure DevOps org with a **Stakeholder** access level, and then add it to the **Project Collection Administrators** group (for billing), or ensure that the user has sufficient permissions in the Team Project to create service connections. +This error typically occurs when you don't have **Write** permission for the selected Azure subscription. -1. Log in to Azure DevOps with the new user credentials, and set up a billing. You'll only see one Azure subscription in the list. +To resolve this issue, ask the subscription administrator to [assign you the appropriate role](/azure/active-directory/fundamentals/active-directory-users-assign-role-azure-portal) in Microsoft Entra ID. - +### Subscription isn't listed when creating a service connection -### Some subscriptions are missing from the list of subscriptions +- **Maximum of 50 Azure subscriptions listed in the various Azure subscription drop-down menus** (billing, service connection, and so on): If you're setting up a service connection and you have more than 50 Azure subscriptions, some of your subscriptions aren't listed. In this scenario, complete the following steps: -This issue can be fixed by changing the **supported account types** settings and defining who can use your application. To do so, follow the steps below: + 1. Create a new, native Microsoft Entra user in the Microsoft Entra instance of your Azure subscription. + 1. Set up the Microsoft Entra user so that it has the proper permissions to set up billing or create service connections. For more information, see [Add a user who can set up billing for Azure DevOps](../../organizations/billing/set-up-billing-for-your-organization-vs.md#give-a-user-access-to-manage-billing). + 1. Add the Microsoft Entra user to the Azure DevOps org with a **Stakeholder** access level, and then add it to the **Project Collection Administrators** group (for billing), or ensure that the user has sufficient permissions in the Team Project to create service connections. + 1. Sign in to Azure DevOps with the new user credentials, and set up billing. You only see one Azure subscription in the list. -1. Sign in to the Azure portal. +- **Old user token cached in Azure DevOps Services:** If your Azure subscription isn't listed when you create an Azure Resource Manager (ARM) service connection, it might be due to an old user token cached in Azure DevOps Services. This scenario isn't immediately obvious as the list screen of Azure subscriptions doesn't display any errors or warning messages indicating that the user token is outdated. To resolve this issue, manually update the cached user token in Azure DevOps Services by doing the following steps: -1. If you have access to multiple tenants, use the **Directory + subscription** filter in the top menu to select the tenant in which you want to register an application. + 1. Sign out of Azure DevOps Services and sign back in. This action can refresh the user token. + 1. Clear your browser cache and cookies to ensure that any old tokens are removed. + 1. From the Azure DevOps portal, go to the service connections, and reauthorize the connection to Azure. This step prompts Azure DevOps to use a new token. - :::image type="content" source="media/directory-and-subscriptions.png" alt-text="Screenshot showing the directory and subscriptions icon in Azure Portal."::: +### Some subscriptions are missing from the list of subscriptions -1. Select **Azure Active Directory** from the left pane. +- **Change support account types settings:** This issue can be fixed by changing the **supported account types** settings and defining who can use your application. Do the following steps: -1. Select **App registrations**. + 1. Sign in to the Azure portal. + 1. If you have access to multiple tenants, use the **Directory + subscription** filter in the top menu to select the tenant in which you want to register an application. -1. Select you application from the list of registered applications. + :::image type="content" source="media/directory-and-subscriptions.png" alt-text="Screenshot showing the directory and subscriptions icon in Azure portal."::: -1. Under **Authentication**, select **Supported account types**. + 1. Select **Microsoft Entra ID** from the left pane. + 1. Select **App registrations**. + 1. Select your application from the list of registered applications. + 1. Under **Authentication**, select **Supported account types**. + 1. Under **Supported account types**, _Who can use this application or access this API?_ select **Accounts in any organizational directory**. -1. Under **Supported account types**, _Who can use this application or access this API?_ select **Accounts in any organizational directory**. + :::image type="content" source="media/supported-account-types.png" alt-text="Screenshot showing the supported account types."::: - :::image type="content" source="media/supported-account-types.png" alt-text="Screenshot showing the supported account types."::: + 1. Select **Save** when you're done. -1. Select **Save** when you are done. +- **Old user token cached in Azure DevOps Services:** If your Azure subscription isn't listed when you create an Azure Resource Manager (ARM) service connection, it might be due to an old user token cached in Azure DevOps Services. This scenario isn't immediately obvious as the list screen of Azure subscriptions doesn't display any errors or warning messages indicating that the user token is outdated. To resolve this issue, manually update the cached user token in Azure DevOps Services by doing the following steps: - + 1. Sign out of Azure DevOps Services and sign back in. This action can refresh the user token. + 1. Clear your browser cache and cookies to ensure that any old tokens are removed. + 1. From the Azure DevOps portal, go to the service connections, and reauthorize the connection to Azure. This step prompts Azure DevOps to use a new token. ### Service principal's token expired -An issue that often arises with service principals that are automatically created is that the service principal's token expires and needs to be renewed. However, if you have an issue with refreshing the token, see [valid refresh token was not found](#troubleshoot). +An issue that often arises with service principals or secrets that are automatically created is that the token expires and needs to be renewed. If you have an issue with refreshing the token, see [Failed to obtain an access token or a valid refresh token wasn't found](#failed-to-obtain-an-access-token-or-a-valid-refresh-token-wasnt-found). + +If your token expired, you could see one of the error messages: -To renew the access token for an automatically created service principal: +* `AADSTS7000215: Invalid client secret is provided` +* `AADSTS7000222: The provided client secret keys for app '***' are expired` +* `Invalid client id or client secret` + +To renew the access token for an automatically created service principal or secret: 1. Go to **Project settings** > **Service connections**, and then select the service connection you want to modify. -1. Select **Edit** in the upper-right corner, and the select **Verify**. +1. Select **Edit** in the upper-right corner. 1. Select **Save**. -Your service principal's token has now been renewed for two more years. +The token for your service principal or secret is now renewed for three more months. - + > [!NOTE] + > This operation is available even if the service principal's token has not expired. + > Make sure that the user performing the operation has proper permissions on the subscription and Microsoft Entra ID, because it will update the secret for the app registered for the service principal. For more information, see [Create an Azure Resource Manager service connection using automated security](/azure/devops/pipelines/library/connect-to-azure#create-an-azure-resource-manager-service-connection-using-automated-security) and [What happens when you create a Resource Manager service connection?](/azure/devops/pipelines/release/azure-rm-endpoint#what-happens-when-you-create-an-azure-resource-manager-service-connection) ### Failed to obtain the JWT by using the service principal client ID -This issue occurs when you try to verify a service connection that has an expired secret. +This issue occurs when you try to save a service connection that has an expired secret or there are some other issues at the Entra ID level. To resolve this issue: @@ -219,35 +221,42 @@ To resolve this issue: 1. Select **Save** to save the service connection. - > [!NOTE] - > Select **Save**. Don't try to verify the service connection at this step. +> [!NOTE] +> If you get an error like `Failed to obtain the Json Web Token(JWT) using service principal client ID. Exception message: AADSTS7000112: Application is disabled.`, you need to work with your Entra ID team to confirm that the option [Enabled for users to sign-in](/troubleshoot/entra/entra-id/app-integration/error-code-aadsts7000112-application-is-disabled) in the enterprise application linked with your service principal is not disabled. + +### Azure subscription isn't passed from the previous task output + +When you set your Azure subscription dynamically for your release pipeline and want to consume the output variable from a preceding task, you might encounter this issue. -1. Exit the service connection edit window, and then refresh the service connections page. +To resolve the issue, ensure that the values are defined within the variables section of your pipeline. You can then pass this variable between your pipeline's tasks. -1. Select **Edit** in the upper-right corner, and now select **Verify**. +### What authentication mechanisms are supported? How do managed identities work? -1. Select **Save** to save your service connection. +::: moniker range="<= azure-devops-2022" -### Azure subscription is not passed from the previous task output +An Azure Resource Manager service connection can connect to an Azure subscription by using a Service Principal Authentication (SPA) or managed identity authentication. -When you set your Azure subscription dynamically for your release pipeline and want to consume the output variable from a preceding task, you might encounter this issue. +::: moniker-end -To resolve the issue, ensure that the values are defined within the variables section of your pipeline. You can then pass this variable between your pipeline's tasks. +::: moniker range="azure-devops" - +The Azure Resource Manager service connection can connect to an Azure subscription, management group, or machine learning workspace using: -### What authentication mechanisms are supported? How do managed identities work? +- App registration (recommended): You can authenticate the connection using a Workload identity federation or a secret. +- Managed identity: Managed identities for Azure resources provide Azure services with an automatically managed identity in Microsoft Entra ID. You can also use an agent-assigned managed identity. + +> When setting up the service connection with a managed identity as the authentication method, the process doesn’t create a new managed identity; it simply establishes the service connection. For this to function correctly, certain conditions must be met. Specifically, because managed identity is the chosen authentication method, there should be a system-assigned identity on the virtual machine you're using. Additionally, this virtual machine needs to act as a self-hosted agent within the pipelines for the workflow to fully execute, allowing the pipeline to deploy changes through the service connection. The system-assigned identity on the VM identifies that the same VM is serving as the agent in the pipeline, enabling authentication. This allows you to leverage the existing managed identity setup. -An Azure Resource Manager service connection can connect to an Azure subscription by using a Service Principal Authentication (SPA) or managed identity authentication. Managed identities for Azure resources provide Azure services with an automatically managed identity in Azure Active Directory (Azure AD). You can use this identity to authenticate to any service that supports Azure AD authentication without persisting credentials in code or in the service connection. To learn about managed identities for virtual machines, see [Assigning roles](/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm). > [!NOTE] > Managed identities aren't supported in Microsoft-hosted agents. In this scenario, you must [set up a self-hosted agent](../agents/agents.md#install) on an Azure VM and configure a managed identity for that VM. +::: moniker-end + ## Related articles - [Troubleshoot pipeline runs](../troubleshooting/troubleshooting.md) - [Review pipeline logs](../troubleshooting/review-logs.md) - [Define variables](../process/variables.md) -- [Classic release and artifacts variables](./variables.md) diff --git a/docs/pipelines/release/caching.md b/docs/pipelines/release/caching.md index 4ed2ed6f057..176374ba0d0 100644 --- a/docs/pipelines/release/caching.md +++ b/docs/pipelines/release/caching.md @@ -17,7 +17,8 @@ Pipeline caching can help reduce build time by allowing the outputs or downloade Caching can be effective at improving build time provided the time to restore and save the cache is less than the time to produce the output again from scratch. Because of this, caching may not be effective in all scenarios and may actually have a negative impact on build time. -Caching is currently supported in CI and deployment jobs, but not classic release jobs. +> [!NOTE] +> Pipeline caching is not supported in Classic release pipelines. ### When to use artifacts versus caching @@ -28,7 +29,7 @@ Pipeline caching and [pipeline artifacts](../artifacts/pipeline-artifacts.md) pe * **Use pipeline caching** when you want to improve build time by reusing files from previous runs (and not having these files won't impact the job's ability to run). > [!NOTE] -> Pipeline caching and pipeline artifacts are free for all tiers (free and paid). see [Artifacts storage consumption](../../artifacts/artifact-storage.md) for more details. +> Pipeline caching and pipeline artifacts are free for all tiers (free and paid). See [Artifacts storage consumption](../../artifacts/artifact-storage.md) for more details. ## Cache task: how it works @@ -39,7 +40,7 @@ When a cache step is encountered during a run, the task restores the cache based After all steps in the job have run and assuming a **successful** job status, a special **"Post-job: Cache"** step is automatically added and triggered for each **"restore cache"** step that wasn't skipped. This step is responsible for **saving the cache**. > [!NOTE] -> Caches are immutable, meaning that once a cache is created, its contents cannot be changed. +> Caches are immutable, meaning once a cache is created, its content is unchangeable. ### Configure the Cache task @@ -65,7 +66,7 @@ Comma-separated list of glob-style wildcard pattern that must match at least one * `**/yarn.lock`: all yarn.lock files under the sources directory * `*/asset.json, !bin/**`: all asset.json files located in a directory under the sources directory, except under the bin directory -The contents of any file identified by a file path or file pattern is hashed to produce a dynamic cache key. This is useful when your project has file(s) that uniquely identify what is being cached. For example, files like `package-lock.json`, `yarn.lock`, `Gemfile.lock`, or `Pipfile.lock` are commonly referenced in a cache key since they all represent a unique set of dependencies. +The contents of any file identified by a file path or file pattern is hashed to produce a dynamic cache key. This is useful when your project has files that uniquely identify what is being cached. For example, files like `package-lock.json`, `yarn.lock`, `Gemfile.lock`, or `Pipfile.lock` are commonly referenced in a cache key since they all represent a unique set of dependencies. Relative file paths or file patterns are resolved against `$(System.DefaultWorkingDirectory)`. @@ -75,7 +76,7 @@ Here's an example showing how to cache dependencies installed by Yarn: ```yaml variables: - YARN_CACHE_FOLDER: $(Pipeline.Workspace)/.yarn + YARN_CACHE_FOLDER: $(Pipeline.Workspace)/s/.yarn steps: - task: Cache@2 @@ -92,14 +93,18 @@ steps: In this example, the cache key contains three parts: a static string ("yarn"), the OS the job is running on since this cache is unique per operating system, and the hash of the `yarn.lock` file that uniquely identifies the set of dependencies in the cache. -On the first run after the task is added, the cache step will report a "cache miss" since the cache identified by this key doesn't exist. After the last step, a cache will be created from the files in `$(Pipeline.Workspace)/.yarn` and uploaded. On the next run, the cache step will report a "cache hit" and the contents of the cache will be downloaded and restored. +On the first run after the task is added, the cache step will report a "cache miss" since the cache identified by this key doesn't exist. After the last step, a cache will be created from the files in `$(Pipeline.Workspace)/s/.yarn` and uploaded. On the next run, the cache step will report a "cache hit" and the contents of the cache will be downloaded and restored. + +When using `checkout: self`, the repository is checked out to `$(Pipeline.Workspace)/s`, and your `.yarn` folder usually resides in the repository itself. > [!NOTE] > `Pipeline.Workspace` is the local path on the agent running your pipeline where all directories are created. This variable has the same value as `Agent.BuildDirectory`. +> +> Ensure you update the variable `YARN_CACHE_FOLDER` if using anything other than `checkout: self` as this should point to the repository where `.yarn` resides. #### Restore keys -`restoreKeys` can be used if one wants to query against multiple exact keys or key prefixes. This is used to fall back to another key in the case that a `key` doesn't yield a hit. A restore key will search for a key by prefix and yield the latest created cache entry as a result. This is useful if the pipeline is unable to find an exact match but wants to use a partial cache hit instead. To insert multiple restore keys, simply delimit them by using a new line to indicate the restore key (see the example for more details). The order of which restore keys will be tried against will be from top to bottom. +`restoreKeys` can be used if one wants to query against multiple exact keys or key prefixes. This is used to fall back to another key in the case that a `key` doesn't yield a hit. A restore key searches for a key by prefix and yield the latest created cache entry as a result. This is useful if the pipeline is unable to find an exact match but wants to use a partial cache hit instead. To insert multiple restore keys, delimit them by using a new line to indicate the restore key (see the example for more details). The order of which restore keys will be tried against will be from top to bottom. #### Required software on self-hosted agent @@ -133,16 +138,18 @@ steps: ``` In this example, the cache task attempts to find if the key exists in the cache. If the key doesn't exist in the cache, it tries to use the first restore key `yarn | $(Agent.OS)`. -This will attempt to search for all keys that either exactly match that key or has that key as a prefix. A prefix hit can happen if there was a different `yarn.lock` hash segment. -For example, if the following key `yarn | $(Agent.OS) | old-yarn.lock` was in the cache where the old `yarn.lock` yielded a different hash than `yarn.lock`, the restore key will yield a partial hit. -If there's a miss on the first restore key, it will then use the next restore key `yarn` which will try to find any key that starts with `yarn`. For prefix hits, the result will yield the most recently created cache key as the result. +This attempts to search for all keys that either exactly match that key or has that key as a prefix. A prefix hit can happen if there was a different `yarn.lock` hash segment. +For example, if the following key `yarn | $(Agent.OS) | old-yarn.lock` was in the cache where the `old-yarn.lock` yielded a different hash than `yarn.lock`, the restore key would yield a partial hit. +If there's a miss on the first restore key, it will then use the next restore key `yarn` which will try to find any key that starts with `yarn`. For prefix hits, the result yields the most recently created cache key as the result. > [!NOTE] -> A pipeline can have one or more caching task(s). There is no limit on the caching storage capacity, and jobs and tasks from the same pipeline can access and share the same cache. +> A pipeline can have one or more caching tasks. There's no limit on the caching storage capacity, and jobs and tasks from the same pipeline can access and share the same cache. ## Cache isolation and security -To ensure isolation between caches from different pipelines and different branches, every cache belongs to a logical container called a scope. Scopes provide a security boundary that ensures a job from one pipeline cannot access the caches from a different pipeline, and a job building a PR has read access to the caches for the PR's target branch (for the same pipeline), but cannot write (create) caches in the target branch's scope. +To ensure isolation between caches from different pipelines and different branches, every cache belongs to a logical container called a scope. Scopes provide a security boundary that ensures: +1. A job from one pipeline can't access the caches from a different pipeline, and +1. A job building a PR has read access to the caches for the PR's target branch (for the same pipeline), but can't write (create) caches in the target branch's scope. When a cache step is encountered during a run, the cache identified by the key is requested from the server. The server then looks for a cache with this key from the scopes visible to the job, and returns the cache (if available). On cache save (at the end of the job), a cache is written to the scope representing the pipeline and branch. See below for more details. @@ -151,7 +158,8 @@ When a cache step is encountered during a run, the cache identified by the key i | Scope | Read | Write | |---------------------------------------------------|------|-------| | Source branch | Yes | Yes | -| main branch (default branch) | Yes | No | +| `main` branch | Yes | No | +| `master` branch | Yes | No | ### Pull request runs @@ -160,7 +168,8 @@ When a cache step is encountered during a run, the cache identified by the key i | Source branch | Yes | No | | Target branch | Yes | No | | Intermediate branch (such as `refs/pull/1/merge`) | Yes | Yes | -| main branch (default branch) | Yes | No | +| `main` branch | Yes | No | +| `master` branch | Yes | No | ### Pull request fork runs @@ -168,14 +177,15 @@ When a cache step is encountered during a run, the cache identified by the key i |---------------------------------------------------|------|-------| | Target branch | Yes | No | | Intermediate branch (such as `refs/pull/1/merge`) | Yes | Yes | -| main branch (default branch) | Yes | No | +| `main` branch | Yes | No | +| `master` branch | Yes | No | > [!TIP] -> Because caches are already scoped to a project, pipeline, and branch, there is no need to include any project, pipeline, or branch identifiers in the cache key. +> Because caches are already scoped to a project, pipeline, and branch, there's no need to include any project, pipeline, or branch identifiers in the cache key. ## Conditioning on cache restoration -In some scenarios, the successful restoration of the cache should cause a different set of steps to be run. For example, a step that installs dependencies can be skipped if the cache was restored. This is possible using the `cacheHitVar` task input. Setting this input to the name of an environment variable will cause the variable to be set to `true` when there's a cache hit, `inexact` on a restore key cache hit, otherwise it will be set to `false`. This variable can then be referenced in a [step condition](../process/conditions.md) or from within a script. +In some scenarios, the successful restoration of the cache should cause a different set of steps to be run. For example, a step that installs dependencies can be skipped if the cache was restored. This is possible using the `cacheHitVar` task input. Setting this input to the name of an environment variable causes the variable to be set to `true` when there's a cache hit, `inexact` on a restore key cache hit, otherwise it's set to `false`. This variable can then be referenced in a [step condition](../process/conditions.md) or from within a script. In the following example, the `install-deps.sh` step is skipped when the cache is restored: @@ -196,7 +206,7 @@ steps: ## Bundler -For Ruby projects using Bundler, override the `BUNDLE_PATH` environment variable used by Bundler to set the [path Bundler](https://bundler.io/v2.3/man/bundle-config.1.html) will look for Gems in. +For Ruby projects using Bundler, override the `BUNDLE_PATH` environment variable used by Bundler to set the [path Bundler](https://bundler.io/v2.3/man/bundle-config.1.html) looks for Gems in. **Example**: @@ -209,10 +219,10 @@ steps: displayName: Bundler caching inputs: key: 'gems | "$(Agent.OS)" | Gemfile.lock' + path: $(BUNDLE_PATH) restoreKeys: | gems | "$(Agent.OS)" - gems - path: $(BUNDLE_PATH) + gems ``` ## Ccache (C/C++) @@ -232,12 +242,12 @@ steps: displayName: Install ccache and update PATH to use linked versions of gcc, cc, etc - task: Cache@2 + displayName: Ccache caching inputs: - key: 'ccache | "$(Agent.OS)"' + key: 'ccache | "$(Agent.OS)" | $(Build.SourceVersion)' path: $(CCACHE_DIR) restoreKeys: | ccache | "$(Agent.OS)" - displayName: ccache ``` See [Ccache configuration settings](https://ccache.dev/manual/latest.html#_configuration_settings) for more details. @@ -258,9 +268,9 @@ steps: - task: Cache@2 displayName: Cache task inputs: - key: 'docker | "$(Agent.OS)" | cache' - path: $(Pipeline.Workspace)/docker - cacheHitVar: CACHE_RESTORED #Variable to set to 'true' when the cache is restored + key: 'docker | "$(Agent.OS)" | cache' ## A unique identifier for the cache + path: $(Pipeline.Workspace)/docker ## Path of the folder or file that you want to cache + cacheHitVar: CACHE_RESTORED ## Variable to set to 'true' when the cache is restored - script: | docker load -i $(Pipeline.Workspace)/docker/cache.tar @@ -283,8 +293,30 @@ steps: condition: and(not(canceled()), not(failed()), ne(variables.CACHE_RESTORED, 'true')) ``` -- **key**: (required) - a unique identifier for the cache. -- **path**: (required) - path of the folder or file that you want to cache. +- **Example using docker buildx**: + + ```yaml + steps: + - task: Cache@2 + displayName: Cache Docker + inputs: + key: 'docker | "$(Agent.OS)" | mydockerimage | ./Dockerfile' + path: $(Pipeline.Workspace)/docker_image_cache + restoreKeys: | + docker | "$(Agent.OS)" | mydockerimage + + - script: | + docker buildx create --name builder --driver docker-container --use + docker buildx build \ + --cache-from=type=local,src=$(Pipeline.Workspace)/docker_image_cache \ + --cache-to=type=local,dest=$(Pipeline.Workspace)/docker_image_cache,mode=max \ + --file ./Dockerfile \ + --output=type=docker,name=mydockerimage \ + . + displayName: docker buildx + env: + DOCKER_BUILDKIT: 1 + ``` ## Golang @@ -343,7 +375,7 @@ steps: - **restoreKeys**: The fallback keys if the primary key fails (Optional) > [!NOTE] -> Caches are immutable, once a cache with a particular key is created for a specific scope (branch), the cache cannot be updated. This means that if the key is a fixed value, all subsequent builds for the same branch will not be able to update the cache even if the cache's contents have changed. If you want to use a fixed key value, you must use the `restoreKeys` argument as a fallback option. +> Caches are immutable, once a cache with a particular key is created for a specific scope (branch), the cache can't be updated. This means that if the key is a fixed value, all subsequent builds for the same branch won't be able to update the cache even if the cache's contents have changed. If you want to use a fixed key value, you must use the `restoreKeys` argument as a fallback option. ## Maven @@ -381,7 +413,7 @@ If you're using a [Maven task](/azure/devops/pipelines/tasks/reference/maven-v3) ## .NET/NuGet If you use `PackageReferences` to manage NuGet dependencies directly within your project file and have a `packages.lock.json` file, you can enable caching by setting the `NUGET_PACKAGES` environment variable to a path under `$(UserProfile)` and caching this directory. See [Package reference in project files](/nuget/consume-packages/package-references-in-project-files) for more details on how to lock dependencies. -If you want to use multiple packages.lock.json, you can still use the following example without making any changes. The content of all the packages.lock.json files will be hashed and if one of the files is changed, a new cache key will be generated. +If you want to use multiple packages.lock.json, you can still use the following example without making any changes. The content of all the packages.lock.json files will be hashed and if one of the files is changed, a new cache key is generated. **Example**: @@ -400,11 +432,13 @@ steps: displayName: Cache NuGet packages ``` +This approach is also valid for .NET Core projects if your project uses *packages.lock.json* to lock package versions. You can enable this by setting `RestorePackagesWithLockFile` to `True` in your *Csproj* file, or by using the following command: `dotnet restore --use-lock-file`. + ## Node.js/npm There are different ways to enable caching in a Node.js project, but the recommended way is to cache npm's [shared cache directory](https://docs.npmjs.com/misc/config#cache). This directory is managed by npm and contains a cached version of all downloaded modules. During install, npm checks this directory first (by default) for modules that can reduce or eliminate network calls to the public npm registry or to a private registry. -Because the default path to npm's shared cache directory is [not the same across all platforms](https://docs.npmjs.com/misc/config#cache), it's recommended to override the `npm_config_cache` environment variable to a path under `$(Pipeline.Workspace)`. This also ensures the cache is accessible from container and non-container jobs. +Because the default path to npm's shared cache directory is [not the same across all platforms](https://docs.npmjs.com/misc/config#cache), it's recommended to override the `npm_config_cache` environment variable to a path under `$(Pipeline.Workspace)`. This also ensures the cache is accessible from container and noncontainer jobs. **Example**: @@ -541,7 +575,7 @@ A: Clearing a cache is currently not supported. However you can add a string lit key: 'yarn | "$(Agent.OS)" | yarn.lock' ``` -to this: +To this: ```yaml key: 'version2 | yarn | "$(Agent.OS)" | yarn.lock' @@ -553,7 +587,7 @@ A: Caches expire after seven days of no activity. ### Q: When does the cache get uploaded? -A: After the last step fo your pipeline a cache will be created from your cache `path` and uploaded. See the [example](#configure-the-cache-task) for more details. +A: After the last step of your pipeline a cache will be created from your cache `path` and uploaded. See the [example](#configure-the-cache-task) for more details. ### Q: Is there a limit on the size of a cache? diff --git a/docs/pipelines/release/configure-workload-identity.md b/docs/pipelines/release/configure-workload-identity.md new file mode 100644 index 00000000000..d419febfbda --- /dev/null +++ b/docs/pipelines/release/configure-workload-identity.md @@ -0,0 +1,322 @@ +--- +title: Set a Resource Manager workload identity service connection +ms.custom: devx-track-arm-template, arm2024 +description: Learn how to manually set an Azure Resource Manager workload identity service connection in Azure Pipelines, one of the services in Azure DevOps. +ms.topic: conceptual +ms.author: jukullam +author: juliakm +ms.date: 10/16/2024 +monikerRange: '>= azure-devops' +"recommendations": "true" +--- + +# Manually set an Azure Resource Manager workload identity service connection + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +> [!NOTE] +>We are rolling out the new Azure service connection creation experience. Receiving it in your organization depends on various factors, and you may still see the older user experience. + +When you [troubleshoot an Azure Resource Manager workload identity service connection](troubleshoot-workload-identity.md#i-dont-have-permissions-to-create-a-service-principal-in-the-microsoft-entra-tenant), you might need to manually configure the connection instead of using the automated tool that's available in Azure DevOps. + +We recommend that you [try the automated approach](../library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-that-uses-workload-identity-federation) before you begin a manual configuration. + +There are two options for authentication: use a managed identity or use an app registration. The advantage of the managed identity option is that you can use it if you don't have permissions to create service principals or if you're using a different Microsoft Entra tenant than your Azure DevOps user. + +## Set a workload identity service connection + +#### [Managed identity](#tab/managed-identity) + + + +To manually set up managed identity authentication for your Azure Pipelines, follow these steps to create a managed identity in the Azure portal, establish a service connection in Azure DevOps, add federated credentials, and grant the necessary permissions. You'll need to follow these steps in this order: + +1. Create the managed identity in Azure portal. +1. Create the service connection in Azure DevOps and save as a draft. +1. Add a federated credential to your managed identity in Azure portal. +1. Grant permissions to the managed identity in Azure portal. +1. Save your service connection in Azure DevOps. + +You can also use the REST API for this process. + +### Prerequisites for managed identity authentication + +- To create a user-assigned managed identity, your Azure account needs the [Managed Identity Contributor](/azure/role-based-access-control/built-in-roles/identity#managed-identity-contributor) or higher role assignment. +- To use a managed identity to access Azure resources in your pipeline, [assign the managed identity access to the resource](/entra/identity/managed-identities-azure-resources/how-to-assign-access-azure-resource). + + +### Create a managed identity in Azure portal + +1. Sign in to the [Azure portal](https://portal.azure.com). + +1. In the search box, enter **Managed Identities**. + +1. Select **Create**. + +1. In the **Create User Assigned Managed Identity** pane, enter or select values for the following items: + + - **Subscription**: Select the subscription in which to create the user-assigned managed identity. + - **Resource group**: Select a resource group to create the user-assigned managed identity in, or select **Create new** to create a new resource group. + - **Region**: Select a region to deploy the user-assigned managed identity (example: **East US**). + - **Name**: Enter the name for your user-assigned managed identity (example: **UADEVOPS**). + +1. Select **Review + create** to create a new managed identity. When your deployment is complete, select **Go to resource**. + +1. Copy the **Subscription**, **Subscription ID**, and **Client ID** values for your managed identity to use later. + +1. Within your managed identity in Azure portal, go to **Settings** > **Properties**. + +1. Copy the **Tenant Id** value to use later. + +### Create a service connection for managed identity authentication in Azure DevOps + +1. In Azure DevOps, open your project and go to :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: > **Pipelines** > **Service connections**. + +1. Select **New service connection**. + +1. Select **Azure Resource Manager**. + +1. Select identity type **App registration or Managed identity (manual)** the **Workload identity federation** credential. + + :::image type="content" source="media/workload-identity-manual-app-workload.png" alt-text="Screenshot that shows selecting the Workload Identity service connection for managed identity."::: + +1. For **Service connection name**, enter a value such as `uamanagedidentity`. You'll use this value in your federated credential subject identifier. + +1. Select **Next**. + +1. In **Step 2: App registration details**: + + **Step 2: App registration details** contains the following parameters. You can enter or select the following parameters: + + | Parameter | Description | + | --------- | ----------- | + | **Issuer** | Required. DevOps automatically creates the issuer URL. | + | **Subject identifier** | Required. DevOps automatically creates the subject identifier. | + | **Environment** | Required. Choose a cloud environment to connect to. If you select **Azure Stack**, enter the environment URL, which is something like `https://management.local.azurestack.external`. | + + + 1. Select the **Scope Level**. Select **Subscription**, **Management Group**, or **Machine Learning Workspace**. [Management groups](/azure/azure-resource-manager/management-groups-overview) are containers that help you manage access, policy, and compliance across multiple subscriptions. A [Machine Learning Workspace](/azure/machine-learning/concept-workspace) is place to create machine learning artifacts. + + * For the **Subscription** scope, enter the following parameters: + + | Parameter | Description | + | --------- | ----------- | + | **Subscription Id** | Required. Enter the Azure subscription ID. | + | **Subscription Name** | Required. Enter the Azure subscription name. | + + * For the **Management Group** scope, enter the following parameters: + + | Parameter | Description | + | --------- | ----------- | + | **Management Group Id** | Required. Enter the Azure management group ID. | + | **Management Group Name** | Required. Enter the Azure management group name. | + + * For the **Machine Learning Workspace** scope, enter the following parameters: + + | Parameter | Description | + | --------- | ----------- | + | **Subscription Id** | Required. Enter the Azure subscription ID. | + | **Subscription Name** | Required. Enter the Azure subscription name. | + | **Resource Group** | Required. Select the resource group containing the workspace. | + | **ML Workspace Name** | Required. Enter the name of the existing Azure Machine Learning workspace. | + | **ML Workspace Location** | Required. Enter the location of the existing Azure Machine Learning workspace. | + + 1. In the **Authentication** section, enter or select the following parameters: + + | Parameter | Description | + | --------- | ----------- | + | **Application (client) ID** | Required. Enter the Client ID for your managed identity. | + | **Directory (tenant) ID** | Required. Enter the Tenant ID from your managed identity. | + + + 1. In the **Security** section, select **Grant access permission to all pipelines** to allow all pipelines to use this service connection. If you don't select this option, you must manually grant access to each pipeline that uses this service connection. + +1. In Azure DevOps, copy the generated values for **Issuer** and **Subject identifier**. + +1. Select **Keep as draft** to save a draft credential. You can't complete setup until your managed identity has a federated credential in Azure portal. + + +### Add a federated credential in Azure portal + +1. In a new browser window, within your managed identity in Azure portal, go to **Settings** > **Federated credentials**. + +1. Select **Add credentials**. + +1. Select the **Other issuer** scenario. + +1. Paste the values for **Issuer** and **Subject identifier** that you copied from your Azure DevOps project into your federated credentials in the Azure portal. For **Type**, select *Explicit subject identifier*. + + :::image type="content" source="media/copy-federated-credentials-new-ui.png" alt-text="Screenshot comparison of federated credentials in Azure DevOps and the Azure portal." lightbox="media/copy-federated-credentials-new-ui.png" ::: + +1. Enter the **Name** of your federated credential. + +1. Select **Add**. + +### Grant permissions to the managed identity in Azure portal + +1. In Azure portal, go to the Azure resource that you want to grant permissions for (for example, a resource group). + +1. Select **Access control (IAM)**. + + :::image type="content" source="approvals/media/access-control-resource-group.png" alt-text="Screenshot that shows selecting Access control in the resource menu."::: + +1. Select **Add role assignment**. Assign the required role to your managed identity (for example, Contributor). + +1. Select **Review and assign**. + +### Save your Azure DevOps service connection + +1. In Azure DevOps, return to your draft service connection. + +1. Select **Finish setup**. + +1. Select **Verify and save**. Once this step successfully completes, your managed identity is fully configured. + +#### [App registration](#tab/app-registration) + + + +This section guides you through setting up an app registration and federated credentials in the Azure portal, creating a service connection for service principal authentication in Azure DevOps, adding federated credentials to your app registration, and granting the necessary permissions. The app registration uses service principal authentication. You'll need to complete these steps in the following order: + +1. Create the app registration with service principal authentication in Azure portal. +1. Create the service connection in Azure DevOps and save as a draft. +1. Add a federated credential to your app registration in Azure portal. +1. Grant permissions to the app registration in Azure portal. +1. Save your service connection in Azure DevOps. + +You can also use the REST API for this process. + + +### Prerequisites for app registration authentication + +- To create a service connection, your Azure account needs to be able to create app registrations. + - If [creating app registrations is disabled in your tenant](/entra/identity/role-based-access-control/delegate-app-roles#to-disable-the-default-ability-to-create-application-registrations-or-consent-to-applications), then you need to have the [Application Developer role](/entra/identity/role-based-access-control/permissions-reference#application-developer) to create application registrations. + + +### Create an app registration and federated credentials in Azure portal + +1. In the Azure portal, search for [app registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps). + +1. Select **New registration**. + + :::image type="content" source="approvals/media/new-app-registration.png" alt-text="Screenshot that shows a new app registration."::: + +1. For **Name**, enter a name for your app registration, and then select **Who can use this application or access this API**. + +1. Select **Register**. + +1. When your new app registration loads, copy the values for **Application (client) ID** and **Directory (tenant) ID** to use later. + + :::image type="content" source="approvals/media/app-registration-client-tenant.png" alt-text="Screenshot that shows the app registration client ID and tenant ID."::: + + +### Create a service connection for app registration authentication in Azure DevOps + +1. In Azure DevOps, open your project and go to :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: > **Pipelines** > **Service connections**. + +1. Select **New service connection**. + +1. Select **Azure Resource Manager**. + +1. Select identity type **App registration or Managed identity (manual)** the **Workload identity federation** credential. + + :::image type="content" source="media/workload-identity-manual-app-workload.png" alt-text="Screenshot that shows selecting the Workload Identity service connection."::: + +1. For **Service connection name**, enter a value such as `uaappregistration`. You'll use this value in your federated credential subject identifier. + +1. Select **Next**. + +1. In **Step 2: App registration details**: + + **Step 2: App registration details** contains the following parameters. You can enter or select the following parameters: + + | Parameter | Description | + | --------- | ----------- | + | **Issuer** | Required. DevOps automatically creates the issuer URL. | + | **Subject identifier** | Required. DevOps automatically creates the subject identifier. | + | **Environment** | Required. Choose a cloud environment to connect to. If you select **Azure Stack**, enter the environment URL, which is something like `https://management.local.azurestack.external`. | + + + 1. Select the **Scope Level**. Select **Subscription**, **Management Group**, or **Machine Learning Workspace**. [Management groups](/azure/azure-resource-manager/management-groups-overview) are containers that help you manage access, policy, and compliance across multiple subscriptions. A [Machine Learning Workspace](/azure/machine-learning/concept-workspace) is place to create machine learning artifacts. + + * For the **Subscription** scope, enter the following parameters: + + | Parameter | Description | + | --------- | ----------- | + | **Subscription Id** | Required. Enter the Azure subscription ID. | + | **Subscription Name** | Required. Enter the Azure subscription name. | + + * For the **Management Group** scope, enter the following parameters: + + | Parameter | Description | + | --------- | ----------- | + | **Management Group Id** | Required. Enter the Azure management group ID. | + | **Management Group Name** | Required. Enter the Azure management group name. | + + * For the **Machine Learning Workspace** scope, enter the following parameters: + + | Parameter | Description | + | --------- | ----------- | + | **Subscription Id** | Required. Enter the Azure subscription ID. | + | **Subscription Name** | Required. Enter the Azure subscription name. | + | **Resource Group** | Required. Select the resource group containing the workspace. | + | **ML Workspace Name** | Required. Enter the name of the existing Azure Machine Learning workspace. | + | **ML Workspace Location** | Required. Enter the location of the existing Azure Machine Learning workspace. | + + 1. In the **Authentication** section, enter or select the following parameters: + + | Parameter | Description | + | --------- | ----------- | + | **Application (client) ID** | Required. Enter the Application (client) ID for your app registration. | + | **Directory (tenant) ID** | Required. Enter the Directory (tenant) ID for your app registration. | + + + 1. In the **Security** section, select **Grant access permission to all pipelines** to allow all pipelines to use this service connection. If you don't select this option, you must manually grant access to each pipeline that uses this service connection. + +1. In Azure DevOps, copy the generated values for **Issuer** and **Subject identifier**. + +1. Select **Keep as draft** to save a draft credential. You can't complete setup until your managed identity has a federated credential in Azure portal. + + +### Add a federated credential to your app registration in Azure portal + +1. In Azure portal, open your app registration and go to **Manage** > **Certificates & secrets**. + +1. Select **Federated credentials**. + + :::image type="content" source="approvals/media/federated-credentials-choice.png" alt-text="Screenshot that shows the federated credentials tab."::: + +1. Select **Add credentials**. + +1. Select the **Other issuer** scenario. + + :::image type="content" source="approvals/media/federated-credential-scenario.png" alt-text="Screenshot that shows selecting a federated credentials scenario."::: + +1. Paste the values for **Issuer** and **Subject identifier** that you copied from your Azure DevOps project into your federated credentials in the Azure portal. For **Type**, select *Explicit subject identifier*. + + :::image type="content" source="media/copy-federated-credentials-new-ui.png" alt-text="Screenshot comparison of federated credentials in Azure DevOps and the Azure portal." lightbox="media/copy-federated-credentials-new-ui.png" ::: + +1. Select **Save**. + +### Grant permissions to the app registration in Azure portal + +1. In the Azure portal, go to the Azure resource that you want to grant permissions for (for example, a resource group). + +1. Select **Access control (IAM)**. + + :::image type="content" source="approvals/media/access-control-resource-group.png" alt-text="Screenshot that shows selecting Access control in the resource menu."::: + +1. Select **Add role assignment**. Assign the required role to the app registration (for example, Contributor). + +1. Select **Review and assign**. + +### Save your app registration Azure DevOps service connection + +1. In Azure DevOps, return to your draft service connection. + +1. Select **Finish setup**. + +1. Select **Verify and save**. When this step successfully finishes, your Azure Resource Manager service connection is fully configured. + +--- + diff --git a/docs/pipelines/release/define-multistage-release-process.md b/docs/pipelines/release/define-multistage-release-process.md index 331a0eff583..ec693bdba00 100644 --- a/docs/pipelines/release/define-multistage-release-process.md +++ b/docs/pipelines/release/define-multistage-release-process.md @@ -1,179 +1,113 @@ --- -title: Define a Classic release pipeline -ms.custom: seodec18 -description: DevOps CI CD - Define a multi-stage continuous deployment (CD) pipeline for your ASP.NET Core app using Azure Pipelines +title: Create a multi-stage release pipeline +description: Learn how to create a multi-stage Classic release pipeline for your ASP.NET Core app using Azure Pipelines. ms.assetid: 12F57ADB-49B9-4E21-A346-5EDB1D1EC2F7 ms.topic: tutorial -ms.author: ronai -author: RoopeshNair -ms.date: 09/02/2021 +ms.date: 12/10/2024 monikerRange: '<= azure-devops' --- -# Define your Classic pipeline +# Create a multi-stage release pipeline (Classic) [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" +Azure Pipelines enables developers to deploy their applications across multiple environments using both YAML and Classic pipelines. This article walks you through creating a multi-stage Classic release pipeline to deploy your ASP.NET Core web app to multiple stages. -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - -Azure Pipelines provide a highly configurable and manageable pipeline for releases to multiple stages such as development, staging, QA, and production. it also offers the opportunity to implement gates and approvals at each specific stage. - -In this tutorial, you will learn about: +In this tutorial, you'll learn how to: > [!div class="checklist"] -> * Continuous deployment triggers -> * Adding stages -> * Adding pre-deployment approvals -> * Creating releases and monitoring deployments +> * Set up continuous deployment triggers +> * Add stages +> * Add pre-deployment approvals +> * Create releases and monitor deployments ## Prerequisites -You'll need: - -* A release pipeline that contains at least one stage. If you don't already have one, you can create it by working through any of the following quickstarts and tutorials: +- An Azure DevOps organization. [Create one for free](../../organizations/accounts/create-organization.md). - - [Deploy to an Azure Web App](../apps/cd/deploy-webdeploy-webapps.md) - - [Azure DevOps Project](/azure/devops-project/overview) - - [Deploy to IIS web server on Windows](../apps/cd/deploy-webdeploy-iis-deploygroups.md) +- An Azure DevOps project. Create a new [project](../../organizations/projects/create-project.md#create-a-project) if you don't have one already. -* Two separate targets where you will deploy the app. These could be virtual machines, web servers, on-premises physical deployment groups, or other types of deployment target. - In this example, we are using Azure App Service website instances. If you decide to do the same, you will have to choose names that are unique, but it's a good idea to include - "QA" in the name of one, and "Production" in the name of the other so that you can easily identify them. Use the Azure portal to create a new web app. +- A Classic release pipeline that contains at least one stage. If you don't already have one, [Create a Classic release](releases.md). -## Continuous deployment (CD) triggers +## Set up continuous deployment triggers -Enabling continuous deployment trigger will instruct the pipeline to automatically create a new release every time a new build is available. +Enabling the continuous deployment trigger will configure the pipeline to automatically create a new release whenever a new pipeline artifact becomes available. -1. In **Azure Pipelines**, open the **Releases** tab. Select your release pipeline select **Edit**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. - ![edit the release pipelin](media/define-multistage-release-process/open-for-edit.png) +1. Select **Azure Pipelines** > **Releases**, select your release pipeline, and then select **Edit**. -1. Select the **Continuous deployment trigger** icon in the **Artifacts** section to open the trigger panel. Make sure this is enabled so that a new release is created after every new successful build is completed. +1. In the **Artifacts** section, select the **Continuous deployment trigger** icon to open the trigger panel, then toggle it to enable. - ![continuous deployment trigger](media/define-multistage-release-process/ci-trigger.png) - -1. Select the **Pre-deployment conditions** icon in the **Stages** section to open the conditions panel. - Make sure that the trigger for deployment to this stage is set to **After release**. This means that a deployment will be initiated automatically when a new release is created from this release pipeline. - - ![pre-deployment conditions](media/define-multistage-release-process/environment-trigger.png) - - You can also set up [Release triggers](triggers.md), [Stage triggers](triggers.md#stage-triggers) or [schedule deployments](triggers.md#scheduled-release-triggers). +1. Under the first stage, select the **Pre-deployment conditions** icon and ensure the deployment trigger is set to **After release**. This triggers deployments to this stage automatically when a new release is created. ## Add stages -In this section, we will add two new stages to our release pipeline: QA and production (Two Azure App Services websites in this example). This is a typical scenario where you would deploy initially to a test or staging server, and then to a live or production server. Each [stage](../process/stages.md) represents one deployment target. - -1. Select the **Pipeline** tab in your release pipeline and select the existing stage. Change the name of your stage to **Production**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. - ![Choosing an existing stage from the Pipelines tab and changing the name to Production in the Stage panel](media/define-multistage-release-process/rename-environment-prod.png) +1. Select **Azure Pipelines** > **Releases**, select your release pipeline, and then select **Edit**. -1. Select the **+ Add** drop-down list and choose **Clone stage** (the clone option is available only when an existing stage is selected). +1. Select **+ Add** > **New stage** to create a new stage. - ![selecting Clone stage](media/define-multistage-release-process/clone-environment.png) - - Typically, you want to use the same deployment methods with a test and a production stage so that you can be sure your deployed apps will behave the same way. Cloning an existing stage is a good way to ensure you have the same settings for both. You then just need to change the deployment targets. - -1. Your cloned stage will have the name **Copy of Production**. Select it and change the name to **QA**. +1. In your newly added stage, select the **Pre-deployment conditions** icon. Set the trigger to **After stage**, and then select your original stage from the drop-down menu. - ![changing stage name to QA](media/define-multistage-release-process/rename-copy-environment.png) - -1. To reorganize the stages in the pipeline, select the **Pre-deployment conditions** icon in your **QA** stage and set the trigger to **After release**. The pipeline diagram will then show the two stages in parallel. - - ![reorganizing stages](media/define-multistage-release-process/change-trigger-qa.png) - -1. Select the **Pre-deployment conditions** icon in your **Production** stage and set the trigger to **After stage**, then select **QA** in the **Stages** drop-down list. - The pipeline diagram will now indicate that the two stages will execute in the correct order. - - ![Selecting QA triggers and stages](media/define-multistage-release-process/change-trigger-prod.png) - - > [!NOTE] - > You can set up your deployment to start when a deployment to the previous stage is _partially_ successful. This means that the deployment will continue even if a specific non-critical task have failed. This is usually used in a fork and join deployments that deploy to different stages in parallel. + :::image type="content" source="media/define-multistage-release-process/change-trigger-prod.png" alt-text="A screenshot displaying how to set up pre-deployment conditions in a Classic release pipeline."::: -1. Select the **Tasks** drop-down list and select the **QA** stage. +1. Select the **Tasks** drop-down menu and select your desired stage. Depending on the tasks that you're using, change the settings so that this stage deploys to your desired target. In this example, we're using **Deploy Azure App Service** task to deploy to an Azure App Service as shown below. - ![Tasks drop down and selecting QA stage](media/define-multistage-release-process/open-qa-tasks.png) - -1. Depending on the tasks that you are using, change the settings so that this stage deploys to your "QA" target. In our example, we will be using **Deploy Azure App Service** task as shown below. - - ![Using the deploy azure app service task](media/define-multistage-release-process/change-target-environment.png) - - + :::image type="content" source="media/define-multistage-release-process/change-target-environment.png" alt-text="A screenshot displaying how to set up stage tasks in a Classic release pipeline."::: ## Add Pre-deployment approvals -The release pipeline we previously modified deploys to QA and production. If the deployment to QA fails, then deployment to production won't trigger. -It is recommended to always verify if your app is working properly in QA or test stage before deploying to production. Adding approvals will ensure all the criteria are met before deploying to the next stage. To add approvals to your pipeline follow the steps below: - -1. Select the **Pipeline** tab, **Pre-deployment conditions** icon then **Pre-deployment approvers**. +Adding approvals ensures that all criteria are met before deploying to the next stage. - ![pre-deployment approvers panel](media/define-multistage-release-process/open-approvers.png) +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. In the **Approvers** text box, enter the user(s) that will be responsible for approving the deployment. It is also recommended to uncheck the **The user requesting a release or deployment should not approve it** check box. +1. Select **Azure Pipelines** > **Releases**, select your release pipeline, and then select **Edit**. - ![Adding pre-deployment approvers](media/define-multistage-release-process/select-approvers.png) +1. From **Stages**, select the **Pre-deployment conditions** icon in the desired stage, and then select the **Pre-deployment approvals** toggle button to enable it. - You can add as many approvers as you need, both individual users and organization groups. It's also possible to set up post-deployment approvals by selecting the "user" icon at the right side of the stage in the pipeline diagram. For more information, see [Releases gates and approvals](approvals/index.md). +1. In the **Approvers** text box, enter the user(s) responsible for approving the deployment. It's also recommended to uncheck the **The user requesting a release or deployment should not approve it** checkbox. -1. Select **Save**. +1. Select **Save** when you're done. - ![Saving the release pipeline](media/define-multistage-release-process/save-definition.png) - - + :::image type="content" source="media/define-multistage-release-process/select-approvers.png" alt-text="A screenshot displaying how to add pre-deployment approvers in a Classic release pipeline."::: ## Create a release -Now that the release pipeline setup is complete, it's time to start the deployment. To do this, we will manually create a new release. Usually a release is created automatically when a new build artifact is available. However, in this scenario we will create it manually. - -1. Select the **Release** drop-down list and choose **Create release**. - - ![create a new release](media/define-multistage-release-process/create-release.png) - -1. Enter a description for your release, check that the correct artifacts are selected, and then select **Create**. +In this example we'll manually create a new release. Usually a release is created automatically when a new build artifact is available. However, in this scenario we'll create it manually. - ![create a new release panel](media/define-multistage-release-process/queue-release.png) +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. A banner will appear indicating that a new release has been create. Select the release link to see more details. +1. Select **Azure Pipelines** > **Releases**, select your release pipeline, and then select **Edit**. - ![release created successfully](media/define-multistage-release-process/release-link.png) +1. Select the **Release** drop-down menu and choose **Create release**. -1. The release summary page will show the status of the deployment to each stage. +1. Enter a description for the release, verify that the correct artifacts are selected, and then select **Create**. - ![deployment status](media/define-multistage-release-process/approval-waiting.png) +1. A banner will appear indicating that a new release has been created. Select the release link to see more details. The release summary page will display the deployment status for each stage. - Other views, such as the list of releases, also display an icon that indicates approval is pending. The icon shows a pop-up containing the stage name and more details when you point to it. This makes it easy for an administrator to see which releases are awaiting approval, as well as the overall progress of all releases. +1. The user(s) you added as approvers will receive an approval request. To approve, they can add a brief comment and select **Approve**. - ![releases list view](media/define-multistage-release-process/list-approval-waiting.png) - -1. Select the _pending_approval_ icon to open the approval window panel. Enter a brief comment, and select **Approve**. - - ![approving deployment](media/define-multistage-release-process/approve-dialog.png) + :::image type="content" source="media/define-multistage-release-process/approve-dialog.png" alt-text="A screenshot displaying how to approve deployment requests in a Classic release pipeline."::: > [!NOTE] -> You can schedule deployment at a later date, for example during non-peak hours. You can also reassign approval to a different user. Release administrators can access and override all approval decisions. - - +> Release administrators can access and override all approval decisions. ## Monitor and track deployments -Deployment logs help you monitor and debug the release of your application. To check the logs of our deployment follow the steps below: - -1. In the release summary, hover over a stage and select **Logs**. +Deployment logs allow you to monitor and troubleshoot the release of your application. Follow the steps below to check the logs for your deployment: - ![deployment logs](media/define-multistage-release-process/open-logs-page.png) - - During deployment, you can still access the logs page to see the live logs of every task. +1. In the release summary, hover over a stage and select **Logs**. You can also access the logs page during deployment to see the live logs of each task. -1. Select any task to see the logs for that specific task. This makes it easier to trace and debug deployment issues. You can also download individual task logs, or a zip of all the log files. - - ![downloading logs](media/define-multistage-release-process/download-logs.png) +1. Select any task to view its specific logs. You can also download individual task logs or a zip of all the log files. -1. If you need additional information to debug your deployment, you can [run the release in debug mode](../../pipelines/release/variables.md#debug-mode). +1. If you need additional information to debug your deployment, you can [run the release in debug mode](../../pipelines/release/variables.md#run-a-release-in-debug-mode). -## Next step + :::image type="content" source="media/define-multistage-release-process/download-logs.png" alt-text="A screenshot displaying deployment logs in a Classic release pipeline."::: + +## Related content -> [!div class="nextstepaction"] -> [Use approvals and gates to control your deployment](deploy-using-approvals.md) +- [Use approvals and gates to control your deployment](deploy-using-approvals.md) +- [Deploy pull request Artifacts](deploy-pull-request-builds.md) +- [Deploy from multiple branches](deploy-multiple-branches.md) diff --git a/docs/pipelines/release/deploy-multiple-branches.md b/docs/pipelines/release/deploy-multiple-branches.md index d64f0c27f0d..860f7bcb5f9 100644 --- a/docs/pipelines/release/deploy-multiple-branches.md +++ b/docs/pipelines/release/deploy-multiple-branches.md @@ -1,65 +1,85 @@ --- -title: Deploy from multiple branches -description: DevOps CI CD - Use release pipelines to deploy from multiple branches to multiple stages. +title: Deploy to different stages from multiple branches +description: Learn how to use Classic release pipelines to deploy to different stages from multiple branches. ms.topic: tutorial -ms.author: ninallam -author: ninallam -ms.date: 03/22/2021 -monikerRange: '>= azure-devops-2019' +ms.date: 08/06/2024 +monikerRange: "<=azure-devops" "recommendations": "true" --- -# Deploy from multiple branches using Azure Pipelines +# Deploy to different stages from multiple branches using Classic release pipelines [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Artifact filters can be used with release triggers to deploy from multiple branches. Applying the artifact filter to a specific branch enables deployment to a specific stage when all the conditions are met. +Classic release pipelines provide a convenient graphical user interface for setting up a continuous delivery solution for your application. Classic releases can be configured to trigger deployments automatically whenever a new artifact is available. Artifact filters can be used with release triggers to deploy from multiple branches. By applying artifact filters to specific branches, you can control deployment to particular stages based on your needs. + +In this article, you'll learn how to: + +> [!div class="checklist"] +> * Enable continuous deployment triggers. +> * Release from multiple branches. +> * Deploy to multiple stages. ## Prerequisites -- A Git repository to create the pipeline. If you don't have one, use the [pipelines-dotnet-core](https://github.com/MicrosoftDocs/pipelines-dotnet-core) sample app. +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- A working pipeline set up for your repository to build your project and generate a pipeline artifact. [Create your first pipeline](../create-first-pipeline.md) if you don't have one already. + +## Create a release pipeline + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines** > **Releases**. If this is your first release pipeline, select **New Pipeline**, otherwise select **New** > **New release pipeline**. + +1. When prompted to select a template, select **Start with an empty job**. + +1. Under **Stages**, select the stage and rename it to **Dev**. The following steps show how to configure this stage to be triggered when an artifact is published from the *Dev* branch. + + :::image type="content" source="media/dev-stage.png" alt-text="A screenshot displaying how to rename a stage in a Classic release pipeline."::: -- A working build for your repository. +1. Under **Artifacts**, select **Add** to add an artifact. Specify your **Source type** and fill out the required fields (these vary based on the selected source type). Select **Add** when you're done. -## Set up a release pipeline + :::image type="content" source="media/add-artifact.png" alt-text="A screenshot that shows how to add an artifact to a Classic release pipeline."::: -1. Select **Releases** under **Pipelines**. If this is your first release pipeline, select **New Pipeline**, otherwise select **Create a release**. +1. Select the **Continuous deployment trigger** icon, and then enable the **Continuous deployment trigger** to create a release whenever a new artifact is available. -1. Select **Start with an empty job** when prompted to select a template. + :::image type="content" source="media/enable-continuous-deployment-trigger.png" alt-text="A screenshot displaying how to enable the continuous deployment trigger."::: -1. Select **Add an artifact** and specify the project, the build pipeline, and the default version. Select **Add** when you are done. +1. In the Dev stage, select the **Pre-deployment conditions** icon and set the deployment trigger to **After release**. This will trigger a deployment to this stage whenever a new release is created. - :::image type="content" source="media/add-artifact.png" alt-text="Add build artifact to release pipeline"::: + :::image type="content" source="media/predeployment-trigger.png" alt-text="A screenshot that shows how to configure the pre-deployment conditions."::: -1. Select the **Continuous deployment trigger** icon and enable the **Continuous deployment trigger** to create a release every time a new build is available. +1. while still in **Pre-deployment conditions**, enable **Artifact filters**, select **Add**, and then specify the artifact you selected earlier and set the **Build branch** to *Dev*. - :::image type="content" source="media/deploy-multiple-branches/ci-trigger.png" alt-text="Enable continuous deployment trigger"::: + :::image type="content" source="media/predeployment-conditions-artifact-filters.png" alt-text="A screenshot displaying how to set up the Artifact filters in Pre-deployment conditions."::: -1. Under **Stages**, select the stage and rename it to **Dev**. This stage will be triggered when a build artifact is published from the dev branch. +## Add a new stage - :::image type="content" source="media/dev-stage.png" alt-text="Configure Dev stage"::: +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select the **Pre-deployment conditions** icon in the _Dev_ stage and set the deployment trigger to **After release** to trigger a deployment to this stage every time a new release is created. +1. Select **Pipelines** > **Releases**, select your release pipeline, and then select **Edit**. - :::image type="content" source="media/predeployment-trigger.png" alt-text="Set pre-deployment trigger to after release"::: +1. Under **Stages**, select **Add** > **New stage** to add a new stage. + +1. Select **Start with an empty job** when prompted to select a template. -1. Enable the **Artifact filters**. Select Add and specify your artifact and build branch. +1. Select your new stage and rename it to **Prod**. The following steps show how to configure this stage to trigger when an artifact is published from the *main* branch. - :::image type="content" source="media/deploy-multiple-branches/artifact-filter1.png" alt-text="Enable Artifact filters"::: +1. Select your *Prod* stage, select the **Pre-deployment conditions** icon, and set the deployment trigger to **After release**. This ensures deployment to this stage whenever a new release is created. -1. Under **Stage**, select **Add** then **New stage** to add a new stage. Select **Start with an empty job** when prompted to select a template, and rename the stage to **Prod**. This stage will be triggered when a build artifact is published from the main branch. Repeat the steps 6-8 and replace the **Build branch** for this stage to main. +1. Select the toggle button to enable **Artifact filters**. Select **Add**, and then specify the artifact you selected earlier and set the **Build branch** to *main*. - :::image type="content" source="media/deploy-multiple-branches/artifact-filter2.png" alt-text="Set up Prod with the main branch"::: + :::image type="content" source="media/predeployment-conditions-prod.png" alt-text="A screenshot displaying how to configure predeployment conditions for the Prod stage."::: -1. Add to each stage all the relevant deployment tasks to your environment. +## Deploy to a specific stage -Now the next time you have a successful build, the pipeline will detect which branch triggered that build and trigger deployment to the appropriate stage only. +Now that you've set up your stages, every time a new artifact is available, the release pipeline will detect which branch triggered the build and deploy only to the appropriate stage. -:::image type="content" source="media/deploy-multiple-branches/after-release.png" alt-text="Deployment status"::: +:::image type="content" source="media/deploy-to-specific-stage.png" alt-text="A screenshot displaying deployment to a specific stage."::: ## Related articles +- [Artifact sources](artifacts.md) - [Release triggers](triggers.md) -- [Build Artifacts](../artifacts/build-artifacts.md) -- [Release artifacts and artifact sources](../release/artifacts.md) -- [Publish and download artifacts](../artifacts/pipeline-artifacts.md) +- [Deploy pull request Artifacts](deploy-pull-request-builds.md) diff --git a/docs/pipelines/release/deploy-pull-request-builds.md b/docs/pipelines/release/deploy-pull-request-builds.md index a52dc467063..0aee46e2268 100644 --- a/docs/pipelines/release/deploy-pull-request-builds.md +++ b/docs/pipelines/release/deploy-pull-request-builds.md @@ -1,103 +1,124 @@ --- -title: Deploy pull request Artifacts -description: Deploy pull request Artifacts from Azure Repos or GitHub repositories +title: Deploy pull request Artifacts with Classic release pipelines +description: Learn how to deploy pull request Artifacts from Azure Repos or GitHub repositories using Classic release pipelines. ms.topic: tutorial ms.author: moala -ms.custom: contperf-fy21q4, engagement-fy23 +ms.custom: engagement-fy23 author: raiyanalam -ms.date: 02/14/2023 -monikerRange: '>= azure-devops-2019' +ms.date: 02/28/2025 +monikerRange: "<=azure-devops" --- # Deploy pull request Artifacts with classic release pipelines [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Pull requests provide an effective way to review code changes before it is merged into the codebase. However, these changes can introduce issues that can be tricky to find without building and deploying your application to a specific environment. Pull request triggers enable you to set up a set of criteria that must be met before deploying your code. In this article, you will learn how to set up pull request triggers with Azure Repos and GitHub to deploy your build artifact. +Pull requests provide an effective way to review code changes before merging them into the codebase. However, these changes can introduce issues that can be tricky to find without building and deploying the application to a specific environment. Pull request triggers enable you to define a set of criteria that must be met before deployment. This article explains how to set up pull request triggers with Azure Repos and GitHub repositories to deploy pipeline artifacts using Classic release pipelines. ## Prerequisites -- Source code hosted on Azure Repos or GitHub. Use the [pipelines-dotnet-core](https://github.com/MicrosoftDocs/pipelines-dotnet-core) sample app and create your repository if you don't have one already. -- A working [build pipeline](../create-first-pipeline.md) for your repository. -- A classic release pipeline. [Set up a release pipeline](./deploy-multiple-branches.md#set-up-a-release-pipeline) if you don't have one already. +| **Product** | **Requirements** | +|--------------------|---------------------| +| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).
      - Source code hosted on Azure Repos or GitHub. If you don’t have a repository, you can use the [pipelines-dotnet-core](https://github.com/MicrosoftDocs/pipelines-dotnet-core) sample app to create one.
      - A working [pipeline](../create-first-pipeline.md) for your repository.
      - A Classic release pipeline. If you don't have one, [set up a Classic release pipeline](./deploy-multiple-branches.md#create-a-release-pipeline). | -## Pull request deployment +## Pull request deployments -With pull request triggers, anytime you raise a new pull request for the designated branch, a release is triggered automatically to start the deployment to the designated environments. The deployment status will then be displayed on the pull request page. Pull request triggers can help you maintain better code quality, release with higher confidence, and discover any issues early on in the development cycle. +Pull request triggers can help you maintain better code quality, release with higher confidence, and discover any issues early on in the development cycle. Setting up pull request deployments is a two step process, first we must set up a pull request trigger and then set up branch policies (Azure Repos) or status checks (GitHub) for our release pipelines. -### Create a pull request trigger +## 1. Enable pull request triggers -A pull request trigger creates a release every time a new build Artifact is available. +When pull request triggers are enabled, a new release is created whenever a new artifact becomes available in a pull request workflow: -1. Navigate to your Azure DevOps project, select **Pipelines** > **Releases** and then select your release pipeline. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select the **Continuous deployment trigger** icon in the **Artifacts** section. +1. Select **Pipelines** > **Releases** and then select your release pipeline definition. - :::image type="content" source="media/deploy-pull-request-builds/artifact-pr-trigger.png" alt-text="A screenshot showing how to access the continuous deployment trigger settings."::: +1. In the **Artifacts** section, select the **Continuous deployment trigger** icon. -1. Select the toggle button to enable the **Pull request trigger**. + :::image type="content" source="media/deploy-pull-request-builds/artifact-pr-trigger.png" alt-text="A screenshot displaying how to access the continuous deployment trigger settings in Classic release pipelines."::: - :::image type="content" source="media/deploy-pull-request-builds/pull-request-trigger-enabled.png" alt-text="A screenshot showing how to enable pull request triggers."::: +1. Toggle the **Pull request trigger** setting to enable it. + + :::image type="content" source="media/deploy-pull-request-builds/pull-request-trigger-enabled.png" alt-text="A screenshot displaying how to enable pull request triggers in Classic release pipelines."::: 1. Select your **Target Branch** from the dropdown menu. - :::image type="content" source="media/deploy-pull-request-builds/pull-request-trigger-target-branch.png" alt-text="A screenshot showing how to select the target branch."::: + :::image type="content" source="media/deploy-pull-request-builds/pull-request-trigger-target-branch.png" alt-text="A screenshot displaying how to select your target branch."::: -1. To deploy your application to a specific stage you need to explicitly opt in that stage. The **Stages** section shows the stages that are enabled for pull request deployments. +1. To deploy your application to a specific stage, explicitly opt in for that stage. The **Stages** section lists the stages enabled for pull request deployments. - :::image type="content" source="media/deploy-pull-request-builds/pull-request-trigger-stage.png" alt-text="A screenshot showing the list of stages that are enabled for pull request deployments."::: + :::image type="content" source="media/deploy-pull-request-builds/pull-request-trigger-stage.png" alt-text="A screenshot displaying the list of stages that are enabled for pull request deployments."::: - To opt-in a stage for pull request deployment, select the **Pre-deployment conditions** icon for your specific stage, and then select **Triggers** > **After release**. Finally select the **Pull request deployment** toggle button to enable it. + To enable pull request deployment for a stage: + - Select the **Pre-deployment conditions** icon for the stage. + - Navigate to **Triggers** > **After release**. + - Toggle the **Pull request deployment** setting to enable it. - :::image type="content" source="media/deploy-pull-request-builds/deploy-to-dev-stage.png" alt-text="A screenshot showing how to enable pull request deployment for a specific stage."::: + :::image type="content" source="media/deploy-pull-request-builds/deploy-to-dev-stage.png" alt-text="A screenshot displaying how to enable pull request deployment for a specific stage."::: > [!IMPORTANT] > Enabling automatic pull request deployments for production stages is not recommended. -### Set up branch policies for Azure Repos +## 2. Set up branch policies + +### [Azure Repos](#tab/repos) + +You can use branch policies to implement a list of criteria that must be met before a pull request can be merged. -You can use branch policies to implement a list of criteria that must be met for a pull request to be merged. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Navigate to your project, and then select **Repos** > **Branches** to access the list of branches for your repository. +1. Select **Repos** > **Branches** to access the list of branches for your repository. - :::image type="content" source="../../repos/git/media/branches/branches_nav-new-nav.png" alt-text="A screenshot showing how to navigate to branches in Azure Repos."::: + :::image type="content" source="../../repos/git/media/branches/branches_nav-new-nav.png" alt-text="A screenshot displaying how to navigate to branches in Azure Repos."::: 1. Select the context menu for your appropriate branch `...`, then select **Branch policies**. - :::image type="content" source="media/deploy-pull-request-builds/branch-policies-menu.png" alt-text="A screenshot showing how to access branch policies for a specific branch."::: + :::image type="content" source="media/deploy-pull-request-builds/branch-policies-menu.png" alt-text="A screenshot displaying how to access branch policies for a specific branch."::: 1. Select **Add status policy**, then select a **Status to check** from the dropdown menu. Select the status corresponding to your release definition and then select **Save**. - :::image type="content" source="media/deploy-pull-request-builds/add-status-policy.png" alt-text="A screenshot showing how to add a status policy."::: + :::image type="content" source="media/deploy-pull-request-builds/add-status-policy.png" alt-text="A screenshot displaying how to add a status policy."::: - > [!NOTE] - > The release definition should have run at least once with the pull request trigger enabled in order to get the list of statuses. See [Configure a branch policy for an external service](../../repos/git/pr-status-policy.md) for more details. + > [!Important] + > The release definition must have run at least once with the pull request trigger enabled to see the list of statuses. See [Configure a branch policy for an external service](../../repos/git/pr-status-policy.md) for more details. -1. With the new status policy added, users won't be able to merge any changes to the target branch without a "succeeded" status is posted to the pull request. +1. Once the status policy is added, users won't be able to merge changes to the target branch unless the pull request has a `succeeded` status. - :::image type="content" source="media/deploy-pull-request-builds/status-policies.png" alt-text="A screenshot showing a list of status policies and the pull request deployment policy enabled."::: + :::image type="content" source="media/deploy-pull-request-builds/status-policies.png" alt-text="A screenshot displaying a list of status policies and the pull request deployment policy enabled."::: -1. You can view the status of your policies from the pull request Overview page. Depending on your policy settings, you can view the posted release status under the **Required**, **Optional**, or **Status** sections. The release status gets updated every time the pipeline is triggered. +1. You can check the status of your policies on the pull request Overview page. Depending on your settings, the release status will be displayed under **Required**, **Optional**, or **Status** sections. The status updates each time the pipeline is triggered. - :::image type="content" source="media/deploy-pull-request-builds/pull-request-policy-status.png" alt-text="A screenshot showing the pull request policies status."::: + :::image type="content" source="media/deploy-pull-request-builds/pull-request-policy-status.png" alt-text="A screenshot displaying the pull request policies status."::: + +### [GitHub](#tab/github) + +Enabling status checks for a GitHub repository allows administrators to specify the criteria that must be met before a pull request can be merged into the target branch. + +1. Navigate to the main page of your repository on GitHub. -### Set up status checks for GitHub repositories +1. Under your repository name, select **Settings**. -Enabling status checks for a GitHub repository allow an administrator to choose which criteria must be met before a pull request is merged into the target branch. +1. Select **Branches**, and then select **Add classic branch protection rule**. -> [!NOTE] -> The status checks will be posted on your pull request only after your release pipeline has run at least once with the pull request deployment condition Enabled. See [Branch protection rules](https://docs.github.com/free-pro-team@latest/github/administering-a-repository/enabling-required-status-checks) for more details. +1. Check the box for **Require status checks to pass before merging**, then select the status corresponding to your release definition. -:::image type="content" source="media/deploy-pull-request-builds/github-branch-protection-rule.png" alt-text="A screenshot showing how to enable status checks."::: + :::image type="content" source="media/deploy-pull-request-builds/github-branch-protection-rule.png" alt-text="A screenshot displaying how to enable status checks."::: -You can view your status checks in your pull request under the **Conversation** tab. + > [!IMPORTANT] + > Status checks will only appear on your pull request after the release pipeline has run at least once with the pull request deployment condition enabled. . See [Branch protection rules](https://docs.github.com/free-pro-team@latest/github/administering-a-repository/enabling-required-status-checks) for more details. + +1. You can view your status checks on the pull request overview page under the **Conversation** tab. -:::image type="content" source="media/deploy-pull-request-builds/github-pr-status-check.png" alt-text="A screenshot showing the pull request status checks."::: + :::image type="content" source="media/deploy-pull-request-builds/github-pr-status-check.png" alt-text="A screenshot displaying the pull request status checks."::: + +--- -## Related articles +## Related content + +- [Release triggers (Classic)](triggers.md) -- [Release triggers](triggers.md) - [Deploy from multiple branches](deploy-multiple-branches.md) -- [Supported source repositories](../repos/index.md) + +- [Create a multi-stage release pipeline (Classic)](define-multistage-release-process.md) diff --git a/docs/pipelines/release/deploy-using-approvals.md b/docs/pipelines/release/deploy-using-approvals.md index 931b44ca30b..bc7f53acfe2 100644 --- a/docs/pipelines/release/deploy-using-approvals.md +++ b/docs/pipelines/release/deploy-using-approvals.md @@ -3,9 +3,9 @@ title: Control deployments with gates and approvals description: Use deployment approvals, gates, and manual intervention to control your deployment ms.assetid: 3D22D4B3-DE1F-482C-BBD4-475C829452C1 ms.topic: tutorial -ms.custom: seodec18, engagement-fy23 -ms.author: shashban -author: azooinmyluggage +ms.custom: engagement-fy23 +ms.author: sandrica +author: silviuandrica ms.date: 10/12/2022 monikerRange: '<= azure-devops' --- diff --git a/docs/pipelines/release/deploy-webdeploy-iis-deploygroups.md b/docs/pipelines/release/deploy-webdeploy-iis-deploygroups.md new file mode 100644 index 00000000000..753e1da8206 --- /dev/null +++ b/docs/pipelines/release/deploy-webdeploy-iis-deploygroups.md @@ -0,0 +1,93 @@ +--- +title: Deploy web apps to an IIS server on a Windows VM +description: Use a Classic pipeline to deploy web apps to an IIS web server on a Windows virtual machine in a deployment group. +ms.assetid: 979E4504-C88A-4D0A-A912-6E5998D87445 +ms.topic: quickstart +ms.author: ronai +author: RoopeshNair +ms.date: 08/27/2024 +monikerRange: '<= azure-devops' +--- + +# Deploy web apps to an IIS server on a Windows VM + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +Learn how to use a Classic pipeline to deploy an ASP.NET Core or Node.js web app to an IIS web server virtual machine (VM) in a Windows deployment group. + +## Prerequisites + +- An Azure DevOps organization and project. To create an organization and project, see [Create a new organization](../../organizations/accounts/create-organization.md) or [Create a project in Azure DevOps](../../organizations/projects/create-project.md). + +#### [.NET Core](#tab/netcore/) + +- A Classic pipeline to build your project. For instructions, see [Build .NET Core apps](../ecosystems/dotnet-core.md). +- A configured IIS web server. For instructions, see [Host ASP.NET Core on Windows with IIS](/aspnet/core/host-and-deploy/iis/). + +#### [Node](#tab/node/) + +- A Classic pipeline to build your project. For instructions, see [Build Node.js apps](../ecosystems/javascript.md). +- A configured IIS web server. For instructions, see [Hosting node.js applications in IIS on Windows](https://github.com/Azure/iisnode). + +--- + +## Create a deployment group + +A deployment group is a logical set of target machines that each have an Azure Pipelines deployment agent installed. Deployment groups make it easier to organize the servers that you want to use to host your app. Each machine interacts with Azure Pipelines to coordinate the deployment of your app. + +To create the deployment group: + +1. From your Azure DevOps project, select **Pipelines** > **Deployment groups** from the left menu. +1. On the **Deployment groups** screen, select **New**, or select **Add a deployment group** if this deployment group is the first one in the project. +1. Enter a **Deployment group name** and optional **Description**, and then select **Create**. +1. On the next screen, in the machine registration section, select **Windows** for the **Type of target to register**. A registration script is generated. +1. Select **Use a personal access token in the script for authentication**. For more information, see [Use personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). +1. Select **Copy script to the clipboard**. + + :::image type="content" source="media/generated-script.png" alt-text="A screenshot showing the generated registration script and other settings."::: + +On each of your target VMs: + +1. Use an account with administrative permissions to sign in to the VM. +1. To register the machine and install the agent, open an Administrator PowerShell command prompt and run the script you copied. + + When you're prompted to configure optional tags for the agent, press Enter to skip. When you're prompted for the user account, press Enter to accept the defaults. + + > [!NOTE] + > The agent running the pipeline must have access to the *C:\\Windows\\system32\\inetsrv\\* directory. For more information, see [Security groups, service accounts, and permissions](../../organizations/security/permissions-access.md). + +After you set up a target server, the script should return the message `Service vstsagent.{computer-name} started successfully`. + +On the **Targets** tab of the Azure Pipelines **Deployment groups** page, you can verify that the VMs are listed and the agents are running. Refresh the page if necessary. + +## Create a release pipeline + +Deploy the artifacts from your build pipeline to your IIS server by using a release pipeline. + +1. From your Azure DevOps project, select **Pipelines** > **Releases**, and then select **New** > **New release pipeline**. +1. On the **Select a template** screen, search for and select **IIS website deployment**, and then select **Apply**. + + :::image type="content" source="media/iis-web-template.png" alt-text="A screenshot showing how to add the IIS website deployment template."::: + +1. In your release pipeline, select **Add an artifact**. +1. On the **Add an artifact** screen, select **Build**, select your **Project** and your **Source (build pipeline)**, and then select **Add**. +1. On the release pipeline screen, select the **Continuous deployment trigger** icon in the **Artifacts** section. +1. On the **Continuous deployment** screen, enable the **Continuous deployment trigger**, +1. Under **Build branch filters**, add the **main** build branch as a filter. +1. On the release pipeline screen, select **Tasks**, and then select **IIS Deployment**. +1. On the settings screen, under **Deployment group**, select the deployment group you created earlier. +1. Select **Save**. + + :::image type="content" source="media/iis-deployment-group.png" alt-text="A screenshot showing how to set up the IIS deployment group."::: + +## Deploy your app + +1. From **Pipelines** > **Releases**, select the release pipeline you just created, and then select **Create release**. +1. Check that the artifact version you want to use is selected, and then select **Create**. +1. Select the release name link in the information bar message **Release \ has been queued**. +1. Select **View logs** to see the logs and agent output. + +## Related articles + +- [Deploy from multiple branches](deploy-multiple-branches.md) +- [Deploy pull request artifacts](deploy-pull-request-builds.md) diff --git a/docs/pipelines/process/deployment-group-phases.md b/docs/pipelines/release/deployment-group-phases.md similarity index 78% rename from docs/pipelines/process/deployment-group-phases.md rename to docs/pipelines/release/deployment-group-phases.md index fe3527fbb9c..f8607d86f75 100644 --- a/docs/pipelines/process/deployment-group-phases.md +++ b/docs/pipelines/release/deployment-group-phases.md @@ -1,6 +1,5 @@ --- title: (Classic) Deployment group jobs in release pipelines -ms.custom: seodec18 description: Understand deployment group jobs in Azure Pipelines ms.assetid: 05956924-242A-43D6-AA29-C93149C0265B ms.topic: conceptual @@ -12,23 +11,21 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end + [Deployment groups](../release/deployment-groups/index.md) in Classic pipelines make it easy to define groups of target servers for deployment. Tasks that you define in a deployment group job run on some or all of the target servers, depending on the arguments you specify for the tasks and the job itself. You can select specific sets of servers from a deployment group to receive the deployment by specifying the machine tags that you've defined for each server in the deployment group. You can also specify the proportion of the target servers that the pipeline should deploy to at the same time. This ensures that the app running on these servers is capable of handling requests while the deployment is taking place. -If you're using a YAML pipeline, you should use [Environments](environments.md) with [virtual machines](environments-virtual-machines.md) instead. +If you're using a YAML pipeline, you should use [Environments](../process/environments.md) with [virtual machines](../process/environments-virtual-machines.md) instead. #### [YAML](#tab/yaml/) ::: moniker range=">=azure-devops-2020" > [!NOTE] -> Deployment group jobs are not supported in YAML. You can use [Virtual machine resources in Environments](environments-virtual-machines.md) to do a rolling deployment to VMs in YAML pipelines. +> Deployment group jobs are not supported in YAML. You can use [Virtual machine resources in Environments](../process/environments-virtual-machines.md) to do a rolling deployment to VMs in YAML pipelines. -Rolling deployments can be configured by specifying the keyword `rolling:` under `strategy:` node of a [deployment job](deployment-jobs.md). +Rolling deployments can be configured by specifying the keyword `rolling:` under `strategy:` node of a [deployment job](../process/deployment-jobs.md). ```YAML strategy: @@ -72,9 +69,9 @@ You add a deployment group job in the editor by selecting '...' on **Process** c Use the job timeout to specify the timeout in minutes for jobs in this job. A zero value for this option means that the timeout is effectively infinite and so, by default, jobs run until they complete or fail. - You can also set the timeout for each task individually - see [task control options](tasks.md#controloptions). Jobs targeting Microsoft-hosted agents have [additional restrictions](../agents/hosted.md) on how long they may run. + You can also set the timeout for each task individually - see [task control options](../process/tasks.md#controloptions). Jobs targeting Microsoft-hosted agents have [additional restrictions](../agents/hosted.md) on how long they may run. ## Related articles -* [Jobs](phases.md) -* [Conditions](conditions.md) +* [Jobs](../process/phases.md) +* [Conditions](../process/conditions.md) diff --git a/docs/pipelines/release/deployment-groups/deploying-azure-vms-deployment-groups.md b/docs/pipelines/release/deployment-groups/deploying-azure-vms-deployment-groups.md index f3198c2fa3d..d1827b01154 100644 --- a/docs/pipelines/release/deployment-groups/deploying-azure-vms-deployment-groups.md +++ b/docs/pipelines/release/deployment-groups/deploying-azure-vms-deployment-groups.md @@ -10,9 +10,7 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../includes/concept-rename-note.md)] -::: moniker-end + In earlier versions of Azure Pipelines, applications that needed to be deployed to multiple servers required a significant amount of planning and maintenance. Windows PowerShell remoting had to be enabled manually, required ports opened, and deployment agents installed on each of the servers. The pipelines then had to be managed manually if a roll-out deployment was required. @@ -45,11 +43,11 @@ The following resources are provisioned on the Azure using an ARM template: - SQL server VM (DB server) - Azure Network Load Balancer -1. Click the **Deploy to Azure** button below to initiate resource provisioning. Provide all the necessary information and select **Purchase**. You may use any combination of allowed administrative usernames and passwords as they are not used again in this tutorial. The **Env Prefix Name** is prefixed to all of the resource names in order to ensure that those resources are generated with globally unique names. Try to use something personal or random, but if you see a naming conflict error during validation or creation, try changing this parameter and running again. +1. Click the **Deploy to Azure** link below to initiate resource provisioning. Provide all the necessary information and select **Purchase**. You may use any combination of allowed administrative usernames and passwords as they are not used again in this tutorial. The **Env Prefix Name** is prefixed to all of the resource names in order to ensure that those resources are generated with globally unique names. Try to use something personal or random, but if you see a naming conflict error during validation or creation, try changing this parameter and running again. - [![Deploy to Azure button.](http://azuredeploy.net/deploybutton.png)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FMicrosoft%2Falmvm%2Fmaster%2Flabs%2Fvstsextend%2Fdeploymentgroups%2Farmtemplate%2Fazurewebsqldeploy.json) + [Deploy to Azure](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FMicrosoft%2Falmvm%2Fmaster%2Flabs%2Fvstsextend%2Fdeploymentgroups%2Farmtemplate%2Fazurewebsqldeploy.json) - ![Deploy to Azure](media/deploying-azure-vms-deployment-groups/deploy-azure.png) + :::image type="content" source="media/deploying-azure-vms-deployment-groups/deploy-azure.png" alt-text="Screenshot showing how to set up your Azure deployment environment."::: > [!NOTE] > It takes approximately 10-15 minutes to complete the deployment. If you receive any naming conflict errors, try changing the parameter you provide for **Env Prefix Name**. @@ -109,7 +107,7 @@ Since there is no configuration change required for the build pipeline, the buil ![Creating an Azure Pipelines service connection](media/deploying-azure-vms-deployment-groups/create-azure-pipelines-connection.png) > [!NOTE] - > To register an agent, you must be a member of the Administrator role in the agent pool. The identity of the agent pool administrator is needed only at the time of registration. The administrator identity isn't persisted on the agent, and it's not used in any subsequent communication between the agent and Azure Pipelines or TFS. After the agent is registered, there's no need to renew the personal access token because it's required only at the time of registration. + > To register an agent, you must be a member of the Administrator role in the agent pool. The identity of the agent pool administrator is needed only at the time of registration. The administrator identity isn't persisted on the agent, and it's not used in any subsequent communication between the agent and Azure Pipelines. After the agent is registered, there's no need to renew the personal access token because it's required only at the time of registration. 1. Select the current **Team project** and the **Deployment group** created earlier. @@ -129,22 +127,22 @@ Since there is no configuration change required for the build pipeline, the buil 1. Select the **Connect Azure Network Load Balancer** task. Configure the task to use the Azure connection, resource group, and load balancer (there should only be one). -1. Select the **Variables** tab and enter the variable values as below. +1. Select the **Variables** tab, create your variables, and provide their respective values as shown in the example below: | Variable Name | Variable Value | |--|--| | DatabaseName | PartsUnlimited-Dev | - | DBPassword | P2ssw0rd@123 | - | DBUserName |sqladmin | - | DefaultConnectionString | Data Source=[YOUR_DNS_NAME];Initial Catalog=PartsUnlimited-Dev;User ID=sqladmin;Password=P2ssw0rd@123;MultipleActiveResultSets=False;Connection Timeout=30; | + | DBPassword | xxxxxxxx | + | DBUserName | xxxxxxxx | + | DefaultConnectionString | Data Source=[YOUR_DNS_NAME];Initial Catalog=PartsUnlimited-Dev;User ID=xxxxxxxx;Password=xxxxxxxx;MultipleActiveResultSets=False;Connection Timeout=30; | | ServerName | localhost | > [!IMPORTANT] > Make sure to replace your SQL server DNS name (which you noted from Azure portal earlier) in **DefaultConnectionString** variable. - Your DefaultConnectionString should be similar to this string after replacing the SQL DNS: + Your DefaultConnectionString should look similar to the following after replacing the SQL DNS: - `Data Source=cust1sqljo5zndv53idtw.westus2.cloudapp.azure.com;Initial Catalog=PartsUnlimited-Dev;User ID=sqladmin;Password=P2ssw0rd@123;MultipleActiveResultSets=False;Connection Timeout=30;` + `Data Source=cust1sqljo5zndv53idtw.westus2.cloudapp.azure.com;Initial Catalog=PartsUnlimited-Dev;User ID=xxxxxxxx;Password=xxxxxxxx;MultipleActiveResultSets=False;Connection Timeout=30;` The final variable list should look something like this: diff --git a/docs/pipelines/release/deployment-groups/howto-provision-deployment-group-agents.md b/docs/pipelines/release/deployment-groups/howto-provision-deployment-group-agents.md index f69e37fb37e..55fbcc003f4 100644 --- a/docs/pipelines/release/deployment-groups/howto-provision-deployment-group-agents.md +++ b/docs/pipelines/release/deployment-groups/howto-provision-deployment-group-agents.md @@ -1,12 +1,12 @@ --- title: Provision agents for deployment groups -ms.custom: seodec18, devx-track-arm-template -description: How to provision agents for deployment groups in Azure Pipelines and Team Foundation Server (TFS) +ms.custom: devx-track-arm-template +description: Learn how to install and provision deployment agents on machines in an Azure Pipelines deployment group. ms.assetid: DF79C2A3-DE70-4184-B7A3-F01A8E86C87C -ms.topic: conceptual +ms.topic: how-to ms.author: ronai author: RoopeshNair -ms.date: 02/04/2021 +ms.date: 08/18/2024 monikerRange: '<= azure-devops' --- @@ -14,112 +14,104 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../../includes/concept-rename-note.md)] -::: moniker-end +A [deployment group](index.md) is a logical group of deployment target machines for Classic release pipelines in Azure Pipelines. Every target server in a deployment group requires a deployment agent installed. This article explains how to install and provision the deployment agent on each physical or virtual machine (VM) in a deployment group. -[Deployment groups](index.md) make it easy to define logical groups of target machines for deployment, -and install the required agent on each machine. This topic explains how to create a deployment group, -and how to install and provision the agent on each virtual or physical machine in your deployment group. +You can install the agent on a target machine in any one of the following ways: -You can install the agent in any one of these ways: +- Run the script that generates when you create the deployment group. +- Install the **Azure Pipelines Agent** Azure VM extension on the VM. +- Use the **AzureResourceGroupDeploymentV2 task** in your release pipeline to create a deployment group and provision agents dynamically. -* [Run the script](#runscript) that is generated automatically when you create a deployment group. -* [Install the **Azure Pipelines Agent** Azure VM extension](#azureext) on each of the VMs. -* [Use the **ARM Template deployment** task](#deploytask) in your release pipeline. +The following sections provide steps to implement each method. -For information about agents and pipelines, see: +## Prerequisites -* [Parallel jobs in Team Foundation Server](../../licensing/concurrent-pipelines-tfs.md). -* [Parallel jobs in Azure Pipelines](../../licensing/concurrent-jobs.md). -* [Pricing for Azure Pipelines features](https://visualstudio.microsoft.com/team-services/pricing/) - - +- An Azure DevOps organization and project. To create an organization or project, see [Create a new organization](../../../organizations/accounts/create-organization.md) or [Create a project in Azure DevOps](../../../organizations/projects/create-project.md). +- Access to at least one Windows or Linux deployment target machine with the [appropriate permissions](../../agents/windows-agent.md#permissions). +- For the Azure Pipelines Agent installation methods, an Azure account and subscription with permissions to create and manage Azure VMs. If you don't have an Azure account, [sign up for a free account](https://azure.microsoft.com/free/). ## Run the installation script on the target servers -1. In the **Deployment groups** tab of **Azure Pipelines**, choose **+New** to create a new group. - -1. Enter a name for the group, and optionally a description, then choose **Create**. +When you create a deployment group, a script is generated that you can run on each target machine to register the server and install the agent. To install the agent by using the generated registration script: -1. In the **Register machines using command line** section of the next page, select the target machine operating system. +1. From your Azure DevOps project, select **Pipelines** > **Deployment groups**. +1. On the **Deployment groups** screen, select **New**, or select **Add a deployment group** if this deployment group is the first one in the project. +1. Enter a **Deployment group name** and optional **Description**, and then select **Create**. +1. On the next screen, select **Windows** or **Linux** for the **Type of target to register**. A registration script is generated. +1. Select **Use a personal access token in the script for authentication**. For more information, see [Use personal access tokens](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). +1. Select **Copy script to the clipboard**. +1. On each target machine, sign in using an account with administrative permissions. +1. Run the copied script to register the machine and install the agent. For Windows machines, use an elevated PowerShell command prompt. -1. Choose **Use a personal access token in the script for authentication**. [Learn more](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). + As the script runs: -1. Choose **Copy the script to clipboard**. + - To assign tags that let you limit deployments to certain servers in a [deployment group job](../../process/deployment-group-phases.md), enter *Y* when prompted to enter tags, and then enter a tag or tags for this VM. -1. Log onto each target machine in turn using the account with the [appropriate permissions](../../agents/windows-agent.md#permissions) and: + Tags are limited to 256 characters each, are case insensitive, and there's no limit to the number of tags you can use. - - Open an Administrator PowerShell command prompt, paste in the script you copied, then execute it to register the machine with this group. - - - If you get an error when running the script that a secure channel could not be created, execute this command at the Administrator PowerShell prompt: + - When prompted for a user account, accept the defaults. - `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` - - - When prompted to configure tags for the agent, press `Y` and enter any tags you will use to identify subsets of the machines in the group for partial deployments. + >[!NOTE] + >If you get an error when running the script that a secure channel couldn't be created, run the following command at the Administrator PowerShell prompt: + > + >`[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` - > Tags you assign allow you to limit deployment to specific servers when - the deployment group is used in a [**Run on machine group** job](../../process/deployment-group-phases.md). +After you set up each target server, the script should return the message `Service vstsagent.{organization-name}.{computer-name} started successfully`. - - When prompted for the user account, press *Return* to accept the defaults. +On the **Targets** tab of the Azure Pipelines **Deployment groups** page, you can verify that the agent is running. Refresh the page if necessary. - - Wait for the script to finish with the message `Service vstsagent.{organization-name}.{computer-name} started successfully`.

      +## Install the Azure Pipelines Agent Azure VM extension -1. In the **Deployment groups** page of **Azure Pipelines**, open the **Machines** tab and verify that the agents are running. If the tags you configured are not visible, refresh the page. - - +If you use Azure VMs as your deployment machines, you can install the Azure Pipelines Agent extension on each VM. The extension automatically registers the agent with the specified deployment group in your Azure DevOps project. -## Install the Azure Pipelines Agent Azure VM extension +To install the agent by using the extension, first create the deployment group: -1. In the **Deployment groups** tab of **Azure Pipelines**, choose **+New** to create a new group. +1. From your Azure DevOps project, select **Pipelines** > **Deployment groups**. +1. On the **Deployment groups** screen, select **New**, or select **Add a deployment group** if this deployment group is the first one in the project. +1. Enter a **Deployment group name** and optional **Description**, and then select **Create**. -1. Enter a name for the group, and optionally a description, then choose **Create**. +In the [Azure portal](https://portal.azure.com), install the Azure Pipelines Agent extension on each target VM: -1. In the Azure portal, for each VM that will be included in the deployment group - open the **Extension** blade, choose **+ Add** to open the **New resource** list, and select **Azure Pipelines Agent**. +1. On the VM page, select **Settings** > **Extensions + Applications** in the left navigation. +1. On the **Extension** tab, select **Add**. +1. On the **Install an Extension** page, search for and select **Azure Pipelines Agent**, and then select **Next**. - ![Installing the Azure Pipelines Agent extension](media/howto-provision-azure-vm-agents/azure-vm-create.png) + :::image type="content" source="media/howto-provision-azure-vm-agents/azure-vm-create.png" alt-text="Screenshot that shows selecting the Azure Pipelines Agent extension."::: -1. In the **Install extension** blade, specify the name of the Azure Pipelines subscription to use. For example, if the URL is `https://dev.azure.com/contoso`, just specify **contoso**. +1. On the **Configure Azure Pipelines Agent Extension** screen, specify the following information: -1. Specify the project name and the deployment group name. - -1. Optionally, specify a name for the agent. If not specified, it uses the VM name appended with `-DG`. + - **Azure DevOps Organization Url**: Enter the URL of your Azure DevOps organization, such as `https://dev.azure.com/contoso`. + - **Team Project**: Enter your project name, such as *myProject*. + - **Deployment Group**: Enter the name of the deployment group you created. + - **Agent Name**: Optionally, enter a name for the agent. If you don't enter anything, the agent is named the VM name appended with `-DG`. + - **Personal Access Token**: Enter the [Personal Access Token (PAT)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) to use for authenticating to Azure Pipelines. + - **Tags**: Optionally, specify a comma-separated list of tags to configure on the agent. Tags are limited to 256 characters each, are case insensitive, and there's no limit to the number of tags you can use. -1. Enter the [Personal Access Token (PAT)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) to use for authentication against Azure Pipelines. +1. Select **Review + create**, and when validation passes, select **Create**. -1. Optionally, specify a comma-separated list of tags that will be configured on the agent. - Tags are not case-sensitive, and each must be no more than 256 characters. - -1. Choose **OK** to begin installation of the agent on this VM. +## Use the AzureResourceGroupDeploymentV2 task -1. Add the extension to any other VMs you want to include in this deployment group. +You can use the [AzureResourceGroupDeploymentV2 task](https://aka.ms/argtaskreadme) to deploy an Azure Resource Manager (ARM) template. The template can install the Azure Pipelines Agent extension while creating an Azure VM, or can update the resource group to apply the extension after a VM is created. - +Alternatively, you can use the advanced deployment options of the AzureResourceGroupDeployment task to deploy the agent. -## Use the ARM Template deployment task +### Create a deployment group -> [!IMPORTANT] -> These instructions refer to version 2 of the task. Switch your **Task version** from 3 to 2. +First create the deployment group: +1. From your Azure DevOps project, select **Pipelines** > **Deployment groups**. +1. On the **Deployment groups** screen, select **New**, or select **Add a deployment group** if this deployment group is the first one in the project. +1. Enter a **Deployment group name** and optional **Description**, and then select **Create**. -You can use the [ARM Template deployment task](https://aka.ms/argtaskreadme) -to deploy an Azure Resource Manager (ARM) template that installs the Azure Pipelines Agent -Azure VM extension as you create a virtual machine, or to update the resource group -to apply the extension after the virtual machine has been created. -Alternatively, you can use the advanced deployment options of the -ARM Template deployment task to deploy the agent to deployment groups. +### Use an ARM template to install the agent -### Install the "Azure Pipelines Agent" Azure VM extension using an ARM template +An ARM template is a JSON file that declaratively defines a set of Azure resources. Azure automatically reads the template and provisions the resources. You can deploy multiple services and their dependencies in a single template. -An ARM template is a JSON file that declaratively defines a set of Azure resources. -The template can be automatically read and the resources provisioned by Azure. -In a single template, you can deploy multiple services along with their dependencies. +To register and install the deployment agent by using an ARM template, add a resources element under the `Microsoft.Compute/virtualMachine` resource, as shown in the following code. -For a Windows VM, create an ARM template and add a resources element under the -`Microsoft.Compute/virtualMachine` resource as shown here: +:::moniker range=">= azure-devops-2022" -```ARMTemplate +```json "resources": [ { "name": "[concat(parameters('vmNamePrefix'),copyIndex(),'/TeamServicesAgent')]", @@ -140,7 +132,7 @@ For a Windows VM, create an ARM template and add a resources element under the "TeamProject": "[parameters('TeamProject')]", "DeploymentGroup": "[parameters('DeploymentGroup')]", "AgentName": "[parameters('AgentName')]", - "AgentMajorVersion": "auto|N", + "AgentMajorVersion": "auto|2|3", "Tags": "[parameters('Tags')]" }, "protectedSettings": { @@ -151,81 +143,124 @@ For a Windows VM, create an ARM template and add a resources element under the ] ``` -where: +> [!NOTE] +> For a Linux VM, the `type` parameter under `properties` in the code should be `TeamServicesAgentLinux`. + +:::moniker-end -* **VSTSAccountName** is required. The Azure Pipelines subscription to use. Example: If your URL is `https://dev.azure.com/contoso`, just specify `contoso` -* **TeamProject** is required. The project that has the deployment group defined within it -* **DeploymentGroup** is required. The deployment group against which deployment agent will be registered -* **AgentName** is optional. If not specified, the VM name with `-DG` appended will be used -* **Tags** is optional. A comma-separated list of tags that will be set on the agent. Tags are not case sensitive and each must be no more than 256 characters -* **PATToken** is required. The Personal Access Token that will be used to authenticate against Azure Pipelines to download and configure the agent +:::moniker range="= azure-devops-2022" > [!NOTE] -> If you are deploying to a Linux VM, ensure that the `type` parameter in the code is `TeamServicesAgentLinux`. +> In Azure DevOps Server 2022.1 and higher, the allowable values for `AgentMajorVersion` are `auto|2|3`. In Azure DevOps Server 2022.0 and earlier, the allowable values for `AgentMajorVersion` are `auto|N`. -### Troubleshoot the extension +:::moniker-end -These are some known issues with the extension: +:::moniker range="< azure-devops-2022" -* **Status file getting too big**: This issue occurs on Windows VMs; it has not been observed on Linux VMs. The status file contains a JSON object that describes the current status of the extension. The object is a placeholder to list the operations performed so far. Azure reads this status file and passes the status object as response to API requests. The file has a maximum allowed size; if the size exceeds the threshold, Azure cannot read it completely and gives an error for the status. On each machine reboot, some operations are performed by the extension (even though it might be installed successfully earlier), which append the status file. If the machine is rebooted a large number of times, the status file size exceeds the threshold, which causes this error. The error message reads: `Handler Microsoft.VisualStudio.Services.TeamServicesAgent:1.27.0.2 status file 0.status size xxxxxx bytes is too big. Max Limit allowed: 131072 bytes`. Note that extension installation might have succeeded, but this error hides the actual state of the extension. +```json +"resources": [ + { + "name": "[concat(parameters('vmNamePrefix'),copyIndex(),'/TeamServicesAgent')]", + "type": "Microsoft.Compute/virtualMachines/extensions", + "location": "[parameters('location')]", + "apiVersion": "2015-06-15", + "dependsOn": [ + "[resourceId('Microsoft.Compute/virtualMachines/', + concat(parameters('vmNamePrefix'),copyindex()))]" + ], + "properties": { + "publisher": "Microsoft.VisualStudio.Services", + "type": "TeamServicesAgent", + "typeHandlerVersion": "1.0", + "autoUpgradeMinorVersion": true, + "settings": { + "VSTSAccountName": "[parameters('VSTSAccountName')]", + "TeamProject": "[parameters('TeamProject')]", + "DeploymentGroup": "[parameters('DeploymentGroup')]", + "AgentName": "[parameters('AgentName')]", + "AgentMajorVersion": "auto|N", + "Tags": "[parameters('Tags')]" + }, + "protectedSettings": { + "PATToken": "[parameters('PATToken')]" + } + } + } +] +``` +:::moniker-end - We have fixed this issue for machine reboots (version `1.27.0.2` for Windows extension and `1.21.0.1` for Linux extension onward), so on a reboot, nothing will be added to the status file. If you had this issue with your extension before the fix was made (that is, you were having this issue with earlier versions of the extension) and your extension was auto-upadted to the versions with the fix, the issue will still persist. This is because on extension update, the newer version of the extension still works with the earlier status file. Currently, you could still be facing this issue if you are using an earlier version of the extension with the flag to turn off minor version auto-updates, or if a large status file was carried from an earlier extension version to the newer versions that contains the fix, or for any other reason. If that is the case, you can get past this issue by uninstalling and re-installing the extension. Uninstalling the extension cleans up the entire extension directory, so a new status file will be created for fresh install. You need to install latest version of the extension. This solution is a permanent fix, and after following this, you should not face the issue again. +In the preceding code: -* **Issue with custom data**: This issue is not with the extension, but some customers have reported confusion regarding the custom data location on the VM on switching OS versions. We suggest the following workaround. Python 2 has been deprecated, so we have made the extension to work with Python 3. If you are still using earlier OS versions that don't have Python 3 installed by default, to run the extension, you should either install Python 3 on the VM or switch to OS versions that have Python 3 installed by default. On linux VMs, [custom data](/azure/virtual-machines/custom-data#linux) is copied to the file `/var/lib/waagent/ovf-env.xml` for earlier Microsoft Azure Linux Agent versions, and to `/var/lib/waagent/CustomData` for newer Microsoft Azure Linux Agent versions. It appears that customers who have hardcoded only one of these two paths face issues while switching OS versions because the file does not exist on the new OS version, but the other file is present. So, to avoid breaking the VM provisioning, you should consider both the files in the template so that if one fails, the other should succeed. +- `VSTSAccountName` is the required Azure Pipelines organization to use. For example, if your Azure DevOps URL is `https://dev.azure.com/contoso`, just specify `contoso` +- `TeamProject` is the required project that has the deployment group defined in it. +- `DeploymentGroup` is the required deployment group to register the agent to. +- `AgentName` is an optional agent name. If not specified, the agent is given the VM name with `-DG` appended. +- `Tags` is an optional, comma-separated list of tags to be set on the agent. Tags are limited to 256 characters each, are case insensitive, and there's no limit to the number of tags you can use. +- `PATToken` is the required PAT to authenticate to Azure Pipelines for downloading and configuring the agent. For more information about ARM templates, see [Define resources in Azure Resource Manager templates](/azure/templates/). -To use the template: +### Use the template in a release pipeline -1. In the **Deployment groups** tab of **Azure Pipelines**, choose **+New** to create a new group. +Create a release pipeline: -1. Enter a name for the group, and optionally a description, then choose **Create**. +1. Select **Pipelines** > **Releases** from the left menu, and then select **New** > **New release pipeline**. +1. In the **Releases** tab of **Azure Pipelines**, create a release pipeline with a stage that contains the **ARM template deployment** task. +1. This template uses version 2 of the task, so on the **Azure resource group deployment** settings screen, change the **Task version** from **3.\*** to **2.\***. +1. Provide the parameters required for the task, such as the Azure subscription, resource group name, location, template information, and action to take. +1. Save the release pipeline, and create a release from the pipeline to install the agents. -1. In the **Releases** tab of **Azure Pipelines**, create a release pipeline with a stage that contains the **ARM Template deployment** task. +### Install agents using the advanced deployment options -1. Provide the parameters required for the task such as the Azure subscription, resource group name, - location, and template information, then save the release pipeline. +Alternatively, you can install the agent by using advanced deployment options. Follow the preceding steps, but on the **Azure resource group deployment** settings screen, expand the **Advanced deployment options for virtual machines** section. -1. Create a release from the release pipeline to install the agents. +1. Under **Enable prerequisites**, select **Configure with Deployment Group agent**. +1. Provide the following required parameters and settings: -### Install agents using the advanced deployment options + - **Azure Pipelines service connection**: Select an existing service connection that points to your target. + + If you don't have an existing service connection, select **New** and create one. For more information, see [Create a service connection](../../library/service-endpoints.md#create-a-service-connection). Configure the service connection to use a [PAT](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with scope restricted to **Deployment Group**. -1. In the **Deployment groups** tab of **Azure Pipelines**, choose **+New** to create a new group. + - **Team project**: Select the project that contains the deployment group. -1. Enter a name for the group, and optionally a description, then choose **Create**. + - **Deployment Group**: Select the deployment group to register the agents to. -1. In the **Releases** tab of **Azure Pipelines**, create a release pipeline with a stage that contains the **ARM Template deployment** task. + - Select **Copy Azure VM tags to agents** to copy any tags already configured on the Azure VM to the corresponding deployment group agent. -1. Select the task and expand the **Advanced deployment options for virtual machines** section. - Configure the parameters in this section as follows: + By default, all [Azure tags](/azure/azure-resource-manager/resource-group-using-tags) are copied using the `Key: Value` format, for example `Role: Web`. - * **Enable Prerequisites**: select **Configure with Deployment Group Agent**. +1. Save the pipeline, and create a release to install the agents. - * **Azure Pipelines/TFS endpoint**: Select an existing Team Foundation Server/TFS service connection that points - to your target. Agent registration for deployment groups requires access to your Visual - Studio project. If you do not have an existing service connection, choose **Add** and create one now. - Configure it to use a [Personal Access Token (PAT)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) - with scope restricted to **Deployment Group**. +## Troubleshoot the extension - * **Project**: Specify the project containing the deployment group. +There are some known issues with the Azure Pipelines Agent extension. - * **Deployment Group**: Specify the name of the deployment group against which the agents will be registered. +#### Status file is too large - * **Copy Azure VM tags to agents**: When set (ticked), any tags already configured on the Azure VM will - be copied to the corresponding deployment group agent. By default, all - [Azure tags](/azure/azure-resource-manager/resource-group-using-tags) - are copied using the format `Key: Value`. For example, `Role: Web`. +This issue can occur on Windows VMs. The status file contains a JSON object that describes the current status of the extension. The object is a placeholder to list the operations performed so far. -1. Provide the other parameters required for the task such as the Azure subscription, resource group name, - and location, then save the release pipeline. +Azure reads this status file and passes the status object as response to API requests. The file has a maximum allowed size. If the size exceeds the maximum, Azure can't read it completely and gives an error for the status. -1. Create a release from the release pipeline to install the agents. +Even though the extension might install initially, every time the machine reboots the extension performs some operations that append to the status file. If the machine reboots many times, the status file size can exceed the threshold, causing the error `Handler Microsoft.VisualStudio.Services.TeamServicesAgent:1.27.0.2 status file 0.status size xxxxxx bytes is too big. Max Limit allowed: 131072 bytes`. Although extension installation might succeed, this error hides the actual state of the extension. -## Related topics +This machine reboot issue is fixed starting with version `1.27.0.2` for the Windows extension and `1.21.0.1` for the Linux extension. A reboot now adds nothing to the status file. However, if you had this issue with an earlier version of the extension and your extension was autoupdated to the fixed version, the issue can persist. Newer versions of the extension can still work with an earlier status file. -* [Run on machine group job](../../process/deployment-group-phases.md) -* [Deploy an agent on Windows](../../agents/windows-agent.md) -* [Deploy an agent on macOS](../../agents/osx-agent.md) -* [Deploy an agent on Linux](../../agents/linux-agent.md) +You could face this issue if you're using an earlier version of the extension with the flag to turn off minor version autoupdates, or if a large status file was carried from an earlier version to a fixed version. If so, you can solve the issue by uninstalling and reinstalling the extension. Uninstalling the extension cleans up the entire extension directory and creates a new status file for a fresh install of the latest version. + +#### Custom data issue + +Python 2 is deprecated, and the Azure Pipelines Agent extension works with Python 3. If you still use OS versions that don't have Python 3 installed by default, to run the extension you should either install Python 3 on the VM or switch to an OS version that has Python 3 installed by default. Otherwise, there can be confusion regarding the [custom data](/azure/virtual-machines/custom-data#linux) location on the VM when you switch OS versions. + +On Linux VMs, custom data copies to */var/lib/waagent/ovf-env.xml* for earlier agent versions, and to */var/lib/waagent/CustomData* for newer versions. If you hardcode only one of these two paths, you might face issues when switching OS versions because one of the paths doesn't exist on the new OS version, although the other path is present. To avoid breaking the VM provisioning, consider using both paths in the template so that if one fails, the other should succeed. [!INCLUDE [rm-help-support-shared](../../includes/rm-help-support-shared.md)] + +## Related content + +* [Deployment group jobs](../../process/deployment-group-phases.md) +* [Self-hosted Windows agents](../../agents/windows-agent.md) +* [Self-hosted macOS agents](../../agents/osx-agent.md) +* [Self-hosted Linux agents](../../agents/linux-agent.md) +* [Configure and pay for parallel jobs](../../licensing/concurrent-jobs.md) +* [Pricing for Azure DevOps](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) diff --git a/docs/pipelines/release/deployment-groups/index.md b/docs/pipelines/release/deployment-groups/index.md index e1e5f12a292..80026642da5 100644 --- a/docs/pipelines/release/deployment-groups/index.md +++ b/docs/pipelines/release/deployment-groups/index.md @@ -1,114 +1,131 @@ --- -title: Use deployment groups in a release pipeline -ms.custom: seodec18, contperf-fy21q4 -description: Work with deployment Groups in Azure Pipelines +title: Use deployment groups in Classic release pipelines +description: Learn how to create and use deployment groups, which are logical groups of target machines for Classic release pipelines in Azure Pipelines. ms.assetid: 21416B0A-F60F-436F-AB46-D6C2A54D5707 -ms.topic: conceptual +ms.topic: how-to ms.author: ronai author: RoopeshNair -ms.date: 06/15/2021 +ms.date: 08/27/2024 monikerRange: '<= azure-devops' "recommendations": "true" --- -# Provision deployment groups +# Use deployment groups in Classic release pipelines [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -A deployment group is a logical set of deployment target machines that have agents installed on each one. Deployment groups represent the physical environments; for example, "Dev", "Test", or "Production" environment. In effect, a deployment group is just another grouping of agents, much like an agent pool. +Similar to an [agent pool](../../agents/pools-queues.md), a deployment group is a logical set of target machines that each have a deployment agent installed. Deployment groups can represent environments such as "Development," "Test," or "Production." Every physical or virtual machine (VM) in the deployment group interacts with Azure Pipelines to coordinate the deployment tasks. Deployment groups are different from [deployment jobs](../../process/deployment-jobs.md), which are collections of task-related steps defined in YAML pipelines. -Deployment groups are only available with Classic release pipelines and are different from deployment jobs. A deployment job is a collection of deployment-related steps defined in a YAML file to accomplish a specific task. +>[!NOTE] +>Deployment groups are available only for Classic release pipelines. -With deployment groups you can: +By using deployment groups, you can: -* Specify the security context and runtime targets for the agents. As you create a deployment group, you add users and give them appropriate permissions to administer, manage, view, and use the group. +- Specify the security context and runtime targets for agents. +- Add users and give them appropriate permissions to administer, manage, view, and use the group. +- View live logs for each server while a deployment happens, and download logs to track deployments for individual servers. +- Use tags to limit deployments to specific sets of target servers. -* Let you view live logs for each server as a deployment takes place, and download logs for all servers to track your deployments down to individual machines. +## Prerequisites -* Enable you to use machine tags to limit deployment to specific sets of target servers. +- An Azure DevOps organization and project. To create an organization and project, see [Create a new organization](../../../organizations/accounts/create-organization.md) or [Create a project in Azure DevOps](../../../organizations/projects/create-project.md). +- Administrative access to at least one Windows or Linux physical or virtual machine to use as a deployment target. ## Create a deployment group -A deployment group is a set of virtual machines with deployment agents. Every VM of the deployment group interacts with Azure Pipelines to coordinate the deployment tasks. +1. From your Azure DevOps project, select **Pipelines** > **Deployment groups**. -1. From within your project, select **Pipelines** > **Deployment groups**. + :::image type="content" source="media/pipelines-deployment-groups.png" alt-text="A screenshot showing Deployment groups in the Pipelines menu."::: - :::image type="content" source="media/pipelines-deployment-groups.png" alt-text="Access deployment groups"::: +1. On the **Deployment groups** screen, select **New**, or select **Add a deployment group** if this deployment group is the first one in the project. -1. Select **Add a deployment group**. - - :::image type="content" source="media/add-deployment-groups.png" alt-text="Add new deployment groups"::: + :::image type="content" source="media/add-deployment-groups.png" alt-text="A screenshot showing Add a deployment group."::: -1. Enter a **Deployment group name** and then select **Create**. A registration script will be generated. Select the **Type of target to register** and then select **Use a personal access token in the script for authentication**. Finally, select **Copy script to the clipboard**. +1. Enter a **Deployment group name** and then select **Create**. - :::image type="content" source="media/generated-script.png" alt-text="Create a deployment group - generated script"::: +1. On the next screen, select **Windows** or **Linux** for the **Type of target to register**. A registration script is generated. -1. Log onto each of your target machines and run the script from an elevated PowerShell command prompt to register it as a target server. When prompted to enter tags for your agent, press *Y* and enter the tag(s) you will use to filter subsets of the servers. - - :::image type="content" source="media/register-servers.png" alt-text="Register deployment groups servers"::: +1. Select **Use a personal access token in the script for authentication**, and then select **Copy script to the clipboard**. -After setting up your target servers, the script should return the following message: `Service vstsagent.{organization-name}.{computer-name} started successfully`. +1. Save the copied script to run on all the target machines in your deployment group. -The tags you assign to your target servers allow you to limit deployment to specific servers in a [Deployment group job](../../process/deployment-group-phases.md). -A tag is limited to 256 characters, but there is no limit to the number of tags you can use. + :::image type="content" source="media/generated-script.png" alt-text="A screenshot showing the generated registration script and other settings."::: -> [!NOTE] -> A deployment pool is a set of target servers available to the organization (org-scoped). When you create a new deployment pool for projects in your organization, a corresponding deployment group is automatically provisioned for each project. The deployment groups will have the same target servers as the deployment pool. You can manually trigger an agent version upgrade for your target servers by hovering over the ellipsis (...) in **Deployment Pools** and selecting **Update targets**. See [Agent versions and upgrades](../../agents/agents.md) for more details. +## Register target servers -:::image type="content" source="media/update-targets-pools.png" alt-text="A screenshot showing how to update targets in deployment pools."::: +To register each target server in the deployment group: + +1. Sign in to the machine with an administrative account and run the copied script. For Windows machines, use an elevated PowerShell command prompt. + + :::image type="content" source="media/register-servers.png" alt-text="A screenshot that shows registering deployment groups servers."::: + +1. To assign tags that let you limit deployments to certain servers in a [deployment group job](../../process/deployment-group-phases.md), enter *Y* when prompted to enter tags, and then enter a tag or tags. + + Tags are limited to 256 characters each, are case insensitive, and there's no limit to the number of tags you can use. +After you set up a target server, the script should return the message `Service vstsagent.{organization-name}.{computer-name} started successfully`. -## Set up agents on deployment groups +## Install and upgrade agents -Every target server in the deployment group requires a deployment agent. You can install an agent on your target servers in three different ways: +Every target server in the deployment group requires a deployment agent. The generated registration script for target servers installs an agent. Alternatively, you can use the following methods to install agents: -- By running the [generated script](#create-a-deployment-group) from the **Deployment Groups** tab. +- If the target servers are Azure VMs, you can easily set up your servers by [installing the Azure Pipelines agent extension](./howto-provision-deployment-group-agents.md#install-the-azure-pipelines-agent-azure-vm-extension) on each VM. -- If the target servers are Azure VMs, you can easily set up your servers by [installing the Azure Pipelines Agent](./howto-provision-deployment-group-agents.md#install-the-azure-pipelines-agent-azure-vm-extension) extension on each of the VMs. +- You can use the [AzureResourceGroupDeploymentV2 task](./howto-provision-deployment-group-agents.md#use-the-azureresourcegroupdeploymentv2-task) in your release pipeline to create and register a deployment group dynamically. -- By using the [ARM template deployment task](./howto-provision-deployment-group-agents.md#use-the-arm-template-deployment-task) in your release pipeline to create a deployment group dynamically. +For more information about these methods, see [Provision agents for deployment groups](howto-provision-deployment-group-agents.md). -You can force the agents on the target servers to be upgraded to the latest version without needing to redeploy them by selecting **Update targets** from your deployment groups page. +To upgrade the agents on target servers to the latest version without having to redeploy them, select the **More actions** ellipsis next to the deployment group on the **Deployment groups** page and select **Update targets**. For more information, see [Azure Pipelines agents](../../agents/agents.md). :::image type="content" source="media/update-targets-deployment-groups.png" alt-text="A screenshot showing how to update targets in deployment groups."::: -## Monitor release status for deployment groups +## Deployment pools + +A deployment pool is a set of target servers that are available to the entire Azure DevOps organization. To create and update deployment pools, you need Project Collection Administrator permissions in the Azure DevOps organization. + +When you create a new deployment pool for an organization, you can automatically provision corresponding deployment groups for selected projects or all projects in the organization. These deployment groups have the same target servers as the deployment pool. + +You can manually trigger an agent version upgrade for all servers in the pool by selecting the **More actions** ellipsis next to the deployment pool in **Deployment pools** and selecting **Update targets**. + +:::image type="content" source="media/update-targets-pools.png" alt-text="A screenshot showing how to update targets in deployment pools."::: + +## Monitor release status -When a release pipeline is executing, you can view the live logs for each target server in your deployment group. When the deployment is completed, you can download the log files for every server to examine the deployments and debug any issues. +While a release pipeline is running, you can view the live logs for each target server in your deployment group. When the deployment finishes, you can download the log files for each server to examine the deployments and debug any issues. -:::image type="content" source="media/deployment-groups-release-summary.png" alt-text="Deployment groups release logs"::: +:::image type="content" source="media/deployment-groups-release-summary.png" alt-text="A screenshot showing deployment groups release logs."::: -## Share a deployment group with other projects +## Share a deployment group -Deployment groups can be shared with other projects in the same organization. Follow the steps below to provision your deployment group for other projects: +You can share deployment groups with other projects in the organization. To provision your deployment group for other projects: -1. From within your project, select **Pipelines** > **Deployment groups**. +1. From your Azure DevOps project, select **Pipelines** > **Deployment groups**. 1. Select your deployment group and then select **Manage**. - :::image type="content" source="media/manage-deployment-group.png" alt-text="Manage deployment groups"::: + :::image type="content" source="media/manage-deployment-group.png" alt-text="A screenshot showing Manage in the deployment group."::: -1. Select a project from the list and then select **Save**. +1. Select projects from the list to share to, and then select **Save**. - :::image type="content" source="media/deployment-group-share-with-project.png" alt-text="Share a deployment group with a project"::: + :::image type="content" source="media/deployment-group-share-with-project.png" alt-text="A screenshot showing sharing a deployment group with a project."::: -1. You will now notice that there is a new Deployment Group in the project you just included. +The included projects now have the shared deployment group listed in **Deployment groups**. - :::image type="content" source="media/shared-deployment-group.png" alt-text="Shared new deployment group"::: +:::image type="content" source="media/shared-deployment-group.png" alt-text="A screenshot showing a shared new deployment group."::: ## Automatically deploy to new target servers -When new target servers get added to a deployment group, you can configure the environment to automatically deploy the last successful release to the new targets. +When new target servers are added to a deployment group, you can configure the environment to automatically deploy the last successful release to the new targets. -From your release pipeline definition, select the post deployment icon, and then enable the **Auto redeploy trigger**. Select the events and action as shown below. +1. From your release pipeline definition, select the post deployment icon. +1. On the **Post-deployment conditions** screen, enable the **Auto redeploy trigger**. +1. Under **Select events**, select **New target with required tags becomes available**. +1. Under **Select action**, select **Redeploy the last successful deployment on this environment**. -:::image type="content" source="../media/deployment-group-add-targets.png" alt-text="Automatically deploy to new target servers"::: + :::image type="content" source="../media/deployment-group-add-targets.png" alt-text="A screenshot showing the Auto redeploy trigger settings."::: ## Related articles - [Deployment group jobs](../../process/deployment-group-phases.md) - [Deploy to Azure VMs using deployment groups](./deploying-azure-vms-deployment-groups.md) - [Provision agents for deployment groups](./howto-provision-deployment-group-agents.md) -- [Self-hosted Windows agents](../../agents/windows-agent.md) -- [Self-hosted macOS agents](../../agents/osx-agent.md) -- [Self-hosted Linux agents](../../agents/linux-agent.md) diff --git a/docs/pipelines/release/deployment-groups/media/add-deployment-groups.png b/docs/pipelines/release/deployment-groups/media/add-deployment-groups.png index 68b1bd4114a..b051315a28a 100644 Binary files a/docs/pipelines/release/deployment-groups/media/add-deployment-groups.png and b/docs/pipelines/release/deployment-groups/media/add-deployment-groups.png differ diff --git a/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/sql-dns.png b/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/sql-dns.png index 8f551b39364..ac323a007c8 100644 Binary files a/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/sql-dns.png and b/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/sql-dns.png differ diff --git a/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/variables.png b/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/variables.png index 708b73f1c35..ccc6f881ada 100644 Binary files a/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/variables.png and b/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/variables.png differ diff --git a/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/web-app-domain.png b/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/web-app-domain.png index 43fc72bca7f..1330a795d4c 100644 Binary files a/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/web-app-domain.png and b/docs/pipelines/release/deployment-groups/media/deploying-azure-vms-deployment-groups/web-app-domain.png differ diff --git a/docs/pipelines/release/deployment-groups/media/deployment-group-share-with-project.png b/docs/pipelines/release/deployment-groups/media/deployment-group-share-with-project.png index eba3442d16f..1b7e645dde3 100644 Binary files a/docs/pipelines/release/deployment-groups/media/deployment-group-share-with-project.png and b/docs/pipelines/release/deployment-groups/media/deployment-group-share-with-project.png differ diff --git a/docs/pipelines/release/deployment-groups/media/generated-script.png b/docs/pipelines/release/deployment-groups/media/generated-script.png index 7e8704eca3a..06ef6d425be 100644 Binary files a/docs/pipelines/release/deployment-groups/media/generated-script.png and b/docs/pipelines/release/deployment-groups/media/generated-script.png differ diff --git a/docs/pipelines/release/deployment-groups/media/howto-provision-azure-vm-agents/azure-vm-create.png b/docs/pipelines/release/deployment-groups/media/howto-provision-azure-vm-agents/azure-vm-create.png index 755ab958555..db22d119dd7 100644 Binary files a/docs/pipelines/release/deployment-groups/media/howto-provision-azure-vm-agents/azure-vm-create.png and b/docs/pipelines/release/deployment-groups/media/howto-provision-azure-vm-agents/azure-vm-create.png differ diff --git a/docs/pipelines/release/deployment-groups/media/manage-deployment-group.png b/docs/pipelines/release/deployment-groups/media/manage-deployment-group.png index 1f6978dcdde..3416b148341 100644 Binary files a/docs/pipelines/release/deployment-groups/media/manage-deployment-group.png and b/docs/pipelines/release/deployment-groups/media/manage-deployment-group.png differ diff --git a/docs/pipelines/release/deployment-groups/media/pipelines-deployment-groups.png b/docs/pipelines/release/deployment-groups/media/pipelines-deployment-groups.png index 6f2c71c1f08..506878a77ca 100644 Binary files a/docs/pipelines/release/deployment-groups/media/pipelines-deployment-groups.png and b/docs/pipelines/release/deployment-groups/media/pipelines-deployment-groups.png differ diff --git a/docs/pipelines/release/deployment-groups/media/shared-deployment-group.png b/docs/pipelines/release/deployment-groups/media/shared-deployment-group.png index fe5fc7ef435..918e698d126 100644 Binary files a/docs/pipelines/release/deployment-groups/media/shared-deployment-group.png and b/docs/pipelines/release/deployment-groups/media/shared-deployment-group.png differ diff --git a/docs/pipelines/release/deployment-groups/media/update-targets-deployment-groups.png b/docs/pipelines/release/deployment-groups/media/update-targets-deployment-groups.png index 2209fc90163..371613ba4c9 100644 Binary files a/docs/pipelines/release/deployment-groups/media/update-targets-deployment-groups.png and b/docs/pipelines/release/deployment-groups/media/update-targets-deployment-groups.png differ diff --git a/docs/pipelines/release/deployment-groups/media/update-targets-pools.png b/docs/pipelines/release/deployment-groups/media/update-targets-pools.png index 0e74f0585ce..45f5402e8d5 100644 Binary files a/docs/pipelines/release/deployment-groups/media/update-targets-pools.png and b/docs/pipelines/release/deployment-groups/media/update-targets-pools.png differ diff --git a/docs/pipelines/release/dsc-cicd.md b/docs/pipelines/release/dsc-cicd.md deleted file mode 100644 index 67d000fe076..00000000000 --- a/docs/pipelines/release/dsc-cicd.md +++ /dev/null @@ -1,521 +0,0 @@ ---- -title: Building a pipeline with DSC -ms.custom: seodec18 -description: How to build a Continuous Integration and Continuous Deployment pipeline with DSC -ms.topic: conceptual -ms.date: 07/10/2020 -monikerRange: '<= azure-devops' ---- - -# Building a Continuous Integration and Continuous Deployment pipeline with DSC - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - -This example demonstrates how to build a Continuous Integration/Continuous Deployment (CI/CD) -pipeline by using PowerShell, DSC, and Pester. - -After the pipeline is built and configured, you can use it to fully deploy, configure and test a DNS -server and associated host records. This process simulates the first part of a pipeline that would -be used in a development environment. - -An automated CI/CD pipeline helps you update software faster and more reliably, ensuring that all -code is tested, and that a current build of your code is available at all times. - -## Prerequisites - -To use this example, you should be familiar with the following: - -- CI-CD concepts. A good reference can be found at [The Release Pipeline Model](../get-started/key-pipelines-concepts.md). -- [Git](https://git-scm.com/) source control -- The [Pester](https://github.com/pester/Pester) testing framework -- [Desired State Configuration](/powershell/dsc/overview)(DSC) - -## What you will need - -To build and run this example, you will need an environment with several computers and/or virtual -machines. - -### Client - -This is the computer where you'll do all of the work setting up and running the example. -The client computer must be a Windows computer with the following installed: - -- [Git](https://git-scm.com/) -- a local git repo cloned from https://github.com/PowerShell/Demo_CI -- a text editor, such as [Visual Studio Code](https://code.visualstudio.com/) - -:::moniker range=">= azure-devops-2019" - -### Azure DevOps Subscription - -An Azure DevOps organization. If you don't have one, you can [create one for free](../get-started/pipelines-sign-up.md). -(An Azure DevOps organization is different from your GitHub organization. Give them the same name if -you want alignment between them.) - -:::moniker-end - -:::moniker range="< azure-devops-2019" - -### TFSSrv - -The computer that hosts the TFS server where you will define your build and release. This computer -must have [Team Foundation Server 2017](https://visualstudio.microsoft.com/tfs/) installed. - -:::moniker-end - -### BuildAgent - -The computer that runs the Windows build agent that builds the project. This computer must have a -Windows build agent installed and running. See [Deploy an agent on Windows](../agents/windows-agent.md) -for instructions on how to install and run a Windows build agent. - -You also need to install both the `xDnsServer` and `xNetworking` DSC modules on this computer. - -### TestAgent1 - -This is the computer that is configured as a DNS server by the DSC configuration in this example. -The computer must be running [Windows Server 2016](https://www.microsoft.com/evalcenter/evaluate-windows-server-2016). - -### TestAgent2 - -This is the computer that hosts the website this example configures. The computer must be running [Windows Server 2016](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2016). - -## Add the code to a repository - -We'll start out by creating a Git repository, and importing the code from your local -repository on the client computer. If you have not already cloned the Demo_CI repository to your -client computer, do so now by running the following git command: - -```CLI -git clone https://github.com/PowerShell/Demo_CI -``` - -:::moniker range="tfs-2018" - -1. On your client computer, navigate to your TFS server in a web browser. - -1. [Create a new team project](../../organizations/projects/create-project.md) named Demo_CI. - - Make sure that **Version control** is set to **Git**. -1. On your client computer, add a remote to the repository you just created in TFS with the following command: - - `git remote add tfs ` - - Where `` is the clone URL to the TFS repository you created in the previous step. - - If you don't know where to find this URL, see [Clone an existing Git repo](../../repos/git/clone.md). -1. Push the code from your local repository to your TFS repository with the following command: - - `git push tfs --all` -1. The TFS repository will be populated with the Demo_CI code. - -:::moniker-end - -:::moniker range=">= azure-devops-2019" - -1. Navigate to your Azure DevOps subscription in a web browser. - -1. [Create a new team project](../../organizations/projects/create-project.md) named Demo_CI. - Make sure that **Version control** is set to **Git**. - -1. On your client computer, add a remote to the repository you just created with the following - command: - - `git remote add devops ` - - Where `` is the clone URL to the Azure DevOps repository you created in the - previous step. - - If you don't know where to find this URL, see [Clone an existing Git repo](../../repos/git/clone.md). - -1. Push the code from your local repository to your TFS repository with the following command: - - `git push devops --all` - -1. The Azure DevOps repository will be populated with the Demo_CI code. - -:::moniker-end - -> [!NOTE] -> This example uses the code in the `ci-cd-example` branch of the Git repo. Be sure to specify this -> branch as the default branch in your project, and for the CI/CD triggers you create. - -## Understanding the code - -Before we create the build and deployment pipelines, let's look at some of the code to understand -what is going on. On your client computer, open your favorite text editor and navigate to the root -of your Demo_CI Git repository. - -### The DSC configuration - -Open the file `DNSServer.ps1` (from the root of the local Demo_CI repository, `./InfraDNS/Configs/DNSServer.ps1`). - -This file contains the DSC configuration that sets up the DNS server. Here it is in its entirety: - -```powershell -configuration DNSServer -{ - Import-DscResource -module 'xDnsServer','xNetworking', 'PSDesiredStateConfiguration' - - Node $AllNodes.Where{$_.Role -eq 'DNSServer'}.NodeName - { - WindowsFeature DNS - { - Ensure = 'Present' - Name = 'DNS' - } - - xDnsServerPrimaryZone $Node.zone - { - Ensure = 'Present' - Name = $Node.Zone - DependsOn = '[WindowsFeature]DNS' - } - - foreach ($ARec in $Node.ARecords.keys) { - xDnsRecord $ARec - { - Ensure = 'Present' - Name = $ARec - Zone = $Node.Zone - Type = 'ARecord' - Target = $Node.ARecords[$ARec] - DependsOn = '[WindowsFeature]DNS' - } - } - - foreach ($CName in $Node.CNameRecords.keys) { - xDnsRecord $CName - { - Ensure = 'Present' - Name = $CName - Zone = $Node.Zone - Type = 'CName' - Target = $Node.CNameRecords[$CName] - DependsOn = '[WindowsFeature]DNS' - } - } - } -} -``` - -Notice the `Node` statement: - -```powershell -Node $AllNodes.Where{$_.Role -eq 'DNSServer'}.NodeName -``` - -This finds any nodes that were defined as having a role of `DNSServer` in the [configuration data](/powershell/scripting/dsc/configurations/configData), -which is created by the `DevEnv.ps1` script. - -You can read more about the `Where` method in [about_arrays](/powershell/module/microsoft.powershell.core/about/about_arrays) - -Using configuration data to define nodes is important when doing CI because node information will -likely change between environments, and using configuration data allows you to easily make changes -to node information without changing the configuration code. - -In the first resource block, the configuration calls the **WindowsFeature** to ensure that the DNS -feature is enabled. The resource blocks that follow call resources from the [xDnsServer](https://github.com/PowerShell/xDnsServer) -module to configure the primary zone and DNS records. - -Notice that the two `xDnsRecord` blocks are wrapped in `foreach` loops that iterate through arrays -in the configuration data. Again, the configuration data is created by the `DevEnv.ps1` script, -which we'll look at next. - -### Configuration data - -The `DevEnv.ps1` file (from the root of the local Demo_CI repository, `./InfraDNS/DevEnv.ps1`) -specifies the environment-specific configuration data in a hashtable, and then passes that hashtable -to a call to the `New-DscConfigurationDataDocument` function, which is defined in -`DscPipelineTools.psm` (`./Assets/DscPipelineTools/DscPipelineTools.psm1`). - -The `DevEnv.ps1` file: - -```powershell -param( - [parameter(Mandatory=$true)] - [string] - $OutputPath -) - -Import-Module $PSScriptRoot\..\Assets\DscPipelineTools\DscPipelineTools.psd1 -Force - -# Define Unit Test Environment -$DevEnvironment = @{ - Name = 'DevEnv'; - Roles = @( - @{ Role = 'DNSServer'; - VMName = 'TestAgent1'; - Zone = 'Contoso.com'; - ARecords = @{'TFSSrv1'= '10.0.0.10';'Client'='10.0.0.15';'BuildAgent'='10.0.0.30';'TestAgent1'='10.0.0.40';'TestAgent2'='10.0.0.50'}; - CNameRecords = @{'DNS' = 'TestAgent1.contoso.com'}; - } - ) -} - -return New-DscConfigurationDataDocument -RawEnvData $DevEnvironment -OutputPath $OutputPath -``` - -The `New-DscConfigurationDataDocument` function (defined in -`\Assets\DscPipelineTools\DscPipelineTools.psm1`) programmatically creates a configuration data -document from the hashtable (node data) and array (non-node data) that are passed as the -`RawEnvData` and `OtherEnvData` parameters. - -In our case, only the `RawEnvData` parameter is used. - -### The psake build script - -The [psake](https://github.com/psake/psake) build script defined in `Build.ps1` (from the root of -the Demo_CI repository, `./InfraDNS/Build.ps1`) defines tasks that are part of the build. It also -defines which other tasks each task depends on. When invoked, the psake script ensures that the -specified task (or the task named `Default` if none is specified) runs, and that all dependencies -also run (this is recursive, so that dependencies of dependencies run, and so on). - -In this example, the `Default` task is defined as: - -```powershell -Task Default -depends UnitTests -``` - -The `Default` task has no implementation itself, but has a dependency on the `CompileConfigs` task. -The resulting chain of task dependencies ensures that all tasks in the build script are run. - -In this example, the psake script is invoked by a call to `Invoke-PSake` in the `Initiate.ps1` file -(located at the root of the Demo_CI repository): - -```powershell -param( - [parameter()] - [ValidateSet('Build','Deploy')] - [string] - $fileName -) - -#$Error.Clear() - -Invoke-PSake $PSScriptRoot\InfraDNS\$fileName.ps1 - -<#if($Error.count) -{ - Throw "$fileName script failed. Check logs for failure details." -} -#> -``` - -When we create the build definition for our example, we will supply our psake script file as -the `fileName` parameter for this script. - -The build script defines the following tasks: - -#### GenerateEnvironmentFiles - -Runs `DevEnv.ps1`, which generates the configuration data file. - -#### InstallModules - -Installs the modules required by the configuration `DNSServer.ps1`. - -#### ScriptAnalysis - -Calls the [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer). - -#### UnitTests - -Runs the [Pester](https://github.com/pester/Pester/wiki) unit tests. - -#### CompileConfigs - -Compiles the configuration (`DNSServer.ps1`) into a MOF file, using the configuration data generated -by the `GenerateEnvironmentFiles` task. - -#### Clean - -Creates the folders used for the example, and removes any test results, configuration data files, -and modules from previous runs. - -### The psake deploy script - -The [psake](https://github.com/psake/psake) deployment script defined in `Deploy.ps1` (from the root -of the Demo_CI repository, `./InfraDNS/Deploy.ps1`) defines tasks that deploy and run the -configuration. - -`Deploy.ps1` defines the following tasks: - -#### DeployModules - -Starts a PowerShell session on `TestAgent1` and installs the modules containing the DSC resources -required for the configuration. - -#### DeployConfigs - -Calls the [Start-DscConfiguration](/powershell/module/psdesiredstateconfiguration/start-dscconfiguration) -cmdlet to run the configuration on `TestAgent1`. - -#### IntegrationTests - -Runs the [Pester](https://github.com/pester/Pester/wiki) integration tests. - -#### AcceptanceTests - -Runs the [Pester](https://github.com/pester/Pester/wiki) acceptance tests. - -#### Clean - -Removes any modules installed in previous runs, and ensures that the test result folder exists. - -### Test scripts - -Acceptance, Integration, and Unit tests are defined in scripts in the `Tests` folder (from the root -of the Demo_CI repository, `./InfraDNS/Tests`), each in files named `DNSServer.tests.ps1` in their -respective folders. - -The test scripts use [Pester](https://github.com/pester/Pester/wiki) and [PoshSpec](https://github.com/Ticketmaster/poshspec/wiki/Introduction) -syntax. - -#### Unit tests - -The unit tests test the DSC configurations themselves to ensure that the configurations will do what -is expected when they run. The unit test script uses [Pester](https://github.com/pester/Pester/wiki). - -#### Integration tests - -The integration tests test the configuration of the system to ensure that when integrated with other -components, the system is configured as expected. These tests run on the target node after it has -been configured with DSC. The integration test script uses a mixture of [Pester](https://github.com/pester/Pester/wiki) -and [PoshSpec](https://github.com/Ticketmaster/poshspec/wiki/Introduction) syntax. - -#### Acceptance tests - -Acceptance tests test the system to ensure that it behaves as expected. For example, it tests to -ensure a web page returns the right information when queried. These tests run remotely from the -target node in order to test real world scenarios. The integration test script uses a mixture of [Pester](https://github.com/pester/Pester/wiki) -and [PoshSpec](https://github.com/Ticketmaster/poshspec/wiki/Introduction) syntax. - -## Define the build - -Now that we've uploaded our code to a repo and looked at what it does, let's define our build. - -Here, we'll cover only the build steps that you'll add to the build. For instructions on how to -create a build definition in Azure DevOps, see [Create and queue a build definition](../create-first-pipeline.md). - -Create a new build definition (select the **Starter Pipeline** template) named "InfraDNS". Add the following -steps to you build definition: - -- PowerShell -- Publish Test Results -- Copy Files -- Publish Artifact - -After adding these build steps, edit the properties of each step as follows: - -### PowerShell - -1. Set the **targetType** property to `File Path`. -1. Set the **filePath** property to `initiate.ps1`. -1. Add `-fileName build` to the **Arguments** property. - -This build step runs the `initiate.ps1` file, which calls the psake build script. - -### Publish Test Results - -1. Set **TestResultsFormat** to `NUnit` -1. Set **TestResultsFiles** to `InfraDNS/Tests/Results/*.xml` -1. Set **TestRunTitle** to `Unit`. -1. Make sure **Control Options** **Enabled** and **Always run** are both selected. - -This build step runs the unit tests in the Pester script we looked at earlier, and stores the -results in the `InfraDNS/Tests/Results/*.xml` folder. - -### Copy Files - -1. Add each of the following lines to **Contents**: - - ``` - initiate.ps1 - **\deploy.ps1 - **\Acceptance\** - **\Integration\** - ``` - -1. Set **TargetFolder** to `$(Build.ArtifactStagingDirectory)\` - -This step copies the build and test scripts to the staging directory so that the can be published as -build artifacts by the next step. - -### Publish Artifact - -1. Set **TargetPath** to `$(Build.ArtifactStagingDirectory)\` -1. Set **ArtifactName** to `Deploy` -1. Set **Enabled** to `true`. - -## Enable continuous integration - -Now we'll set up a trigger that causes the project to build any time a change is checked in to the -`ci-cd-example` branch of the git repository. - -1. In TFS, click the **Build & Release** tab -1. Select the `DNS Infra` build definition, and click **Edit** -1. Click the **Triggers** tab -1. Select **Continuous integration (CI)**, and select `refs/heads/ci-cd-example` in the branch - drop-down list -1. Click **Save** and then **OK** - -Now any change in the git repository triggers an automated build. - -## Create the release definition - -Let's create a release definition so that the project is deployed to the development environment -with every code check-in. - -To do this, add a new release definition associated with the `InfraDNS` build definition you created -previously. Be sure to select **Continuous deployment** so that a new release will be triggered any -time a new build is completed. ([What are release pipelines?](../release/index.md)) and -configure it as follows: - -Add the following steps to the release definition: - -- PowerShell -- Publish Test Results -- Publish Test Results - -Edit the steps as follows: - -### PowerShell - -1. Set the **TargetPath** field to `$(Build.DefinitionName)\Deploy\initiate.ps1"` -1. Set the **Arguments** field to `-fileName Deploy` - -### First Publish Test Results - -1. Select `NUnit` for the **TestResultsFormat** field -1. Set the **TestResultsFiles** field to `$(Build.DefinitionName)\Deploy\InfraDNS\Tests\Results\Integration*.xml` -1. Set the **TestRunTitle** to `Integration` -1. Set **Condition** to `succeededOrFailed()` - -### Second Publish Test Results - -1. Select `NUnit` for the **TestResultsFormat** field -1. Set the **TestResultsFiles** field to `$(Build.DefinitionName)\Deploy\InfraDNS\Tests\Results\Acceptance*.xml` -1. Set the **TestRunTitle** to `Acceptance` -1. Set **Condition** to `succeededOrFailed()` - -## Verify your results - -Now, any time you push changes in the `ci-cd-example` branch, a new build will start. If the -build completes successfully, a new deployment is triggered. - -You can check the result of the deployment by opening a browser on the client machine and navigating -to `www.contoso.com`. - -## Next steps - -This example configures the DNS server `TestAgent1` so that the URL `www.contoso.com` resolves to -`TestAgent2`, but it does not actually deploy a website. The skeleton for doing so is provided in -the repo under the `WebApp` folder. You can use the stubs provided to create psake scripts, Pester -tests, and DSC configurations to deploy your own website. diff --git a/docs/pipelines/release/env-templates.md b/docs/pipelines/release/env-templates.md index 1b7d3740d5f..f890d676731 100644 --- a/docs/pipelines/release/env-templates.md +++ b/docs/pipelines/release/env-templates.md @@ -1,6 +1,5 @@ --- title: Use stage templates in release pipelines -ms.custom: seodec18 description: How to use stage templates in Azure Pipelines ms.assetid: BE9E2883-5CEB-4A91-A038-CB45B728A0C4 ms.topic: conceptual @@ -73,4 +72,3 @@ To update a stage template, delete the existing one from the list of templates, - [Deploy pull request Artifacts ](deploy-pull-request-builds.md). - [Deploy from multiple branches](deploy-multiple-branches.md). -- [View release progress and test summary](visualize-release-test-progress.md). diff --git a/docs/pipelines/migrate/from-classic-pipelines.md b/docs/pipelines/release/from-classic-pipelines.md similarity index 80% rename from docs/pipelines/migrate/from-classic-pipelines.md rename to docs/pipelines/release/from-classic-pipelines.md index 87b5b29c9c0..7f28ecae5d7 100644 --- a/docs/pipelines/migrate/from-classic-pipelines.md +++ b/docs/pipelines/release/from-classic-pipelines.md @@ -4,7 +4,7 @@ titleSuffix: Azure Pipelines description: How to migrate from Classic pipelines to YAML. ms.subservice: azure-devops-pipelines-migrate ms.topic: quickstart -ms.date: 07/03/2023 +ms.date: 07/01/2024 monikerRange: azure-devops --- @@ -14,7 +14,10 @@ monikerRange: azure-devops Get started with Azure Pipelines by converting your existing Classic pipeline to use YAML. With a YAML-based pipeline, you can implement your CI/CD strategy as code and see its history, compare versions, blame, annotate, and so on. -When you convert your Classic pipeline, the end product is two pipelines. You'll have one new YAML pipeline and a Classic pipeline that can be retired. Your Classic pipeline's run history will remain in the Classic pipeline. +When you convert your Classic pipeline, the end product is two pipelines. You'll have one new YAML pipeline and a Classic pipeline that can be retired. Your Classic pipeline's run history remains in the Classic pipeline. + +> [!NOTE] +> You can only export a YAML file from an existing Classic pipeline created with the classic build designer. If you don't see the option to export to JSON or YAML, then your pipeline doesn't support exporting. Classic release pipelines don't have the export to YAML option. You can export a classic release pipeline by exporting each individual task. ## Prerequisites @@ -57,25 +60,25 @@ Do the following steps to create a sample YAML pipeline, which you'll update lat ## Export your Classic pipeline -Do the following steps to export your Classic pipeline to a YAML file that you can use in the editor. - -1. Open your Classic pipeline. +1. Sign in to your Azure DevOps organization, and then go to your project. -2. Select the ellipses (...), and then select **Export to YAML**. +1. Select **Pipelines** > **Pipelines**. + +1. Select your Classic pipeline definition, select the ellipses icon, and then select **Export to YAML**. Make sure you're in the pipeline definition view, not a specific run, to see the **Export to YAML** option. :::image type="content" source="media/export-yaml.png" alt-text="Screenshot of context menu, to export your pipeline to YAML."::: -3. Open the downloaded YAML file in your code editor. +1. Open the downloaded YAML file in your code editor. -4. If your YAML pipeline includes variables defined in the Classic UI, define the variables again in your pipeline settings UI or in your YAML file. For more information, see [Define variables](../process/variables.md). +1. If your YAML pipeline includes variables defined in the Classic UI, define the variables again in your pipeline settings UI or in your YAML file. For more information, see [Define variables](../process/variables.md). -5. Review any `cron` schedules in your YAML file. By default, `cron` schedules in YAML are in UTC. In Classic pipelines, they are in the organization's timezone. For more information, see [Configure schedules for pipelines](../process/scheduled-triggers.md). +1. Review any `cron` schedules in your YAML file. By default, `cron` schedules in YAML are in UTC. In Classic pipelines, they are in the organization's timezone. For more information, see [Configure schedules for pipelines](../process/scheduled-triggers.md). -6. Use the Task Assistant to make any other changes to the YAML file. The Task Assistant is a pane on the right side of the screen, which helps you correctly create and modify YAML steps. +1. Use the Task Assistant to make any other changes to the YAML file. The Task Assistant is a pane on the right side of the screen, which helps you correctly create and modify YAML steps. :::image type="content" source="media/task-assistant-yaml.png" alt-text="Configure your pipeline task with Task Assistant."::: -7. **Save and run** your pipeline. +1. **Save and run** your pipeline. ## Clean up resources @@ -103,6 +106,5 @@ Learn about the feature differences between YAML and Classic pipelines. ## Related articles - [Customize your pipeline](../customize-pipeline.md) -- [YAML pipeline editor basics](../get-started/yaml-pipeline-editor.md) -- [Library of assets](../library/index.md) +- [Learn YAML pipeline editor basics](../get-started/yaml-pipeline-editor.md) - [Define approvals and checks](../release/approvals/approvals.md) diff --git a/docs/pipelines/release/history.md b/docs/pipelines/release/history.md new file mode 100644 index 00000000000..58a80607b80 --- /dev/null +++ b/docs/pipelines/release/history.md @@ -0,0 +1,62 @@ +--- +title: View Classic pipeline history +description: Learn how to determine what changed, when it happened, and who made the changes using the build history in your classic pipelines. +ms.topic: how-to +ms.assetid: AB81E23E-DD84-4BDB-ACD9-AE03D783A303 +ms.date: 09/06/2024 +monikerRange: '<= azure-devops' +--- + +# View Classic pipeline history + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +With Azure Pipelines, you can set up a classic pipeline to build your project. This article will guide you through checking the history of your classic pipeline to see what changed, when it happened, and who made the changes. + +## Prerequisites + +- Create an Azure DevOps [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- A working Classic pipeline. + +## View pipeline history + +::: moniker range=" azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines**, select your Classic pipeline, and then select **Edit**. + +1. Select the **History** tab to view a list of changes, including who made the changes and when they occurred. + + :::image type="content" source="media/classic-pipeline-history-devops.png" alt-text="A screenshot displaying how to view Classic pipeline history in Azure DevOps Services."::: + +::: moniker-end + +::: moniker range="< azure-devops" + +1. Sign in to your Azure DevOps collection, and then navigate to your project. + +1. Select **Pipelines**, select your Classic pipeline, and then select **Edit**. + +1. Select the **History** tab to view a list of changes, including who made the changes and when they occurred. + + :::image type="content" source="media/classic-pipeline-history.png" alt-text="A screenshot displaying how to view Classic pipeline history."::: + +::: moniker-end + +4. To take action on a change, select it, select the ellipsis button **...**, and then choose either **Compare Difference** or **Revert Pipeline**. + + :::image type="content" source="media/pipeline-history-compare-difference.png" alt-text="A screenshot displaying the Classic pipeline history difference."::: + +> [!NOTE] +> When viewing the compare difference in Classic pipeline history, the JSON files are read-only and cannot be edited directly. + +## Related content + +- [Build multiple branches in Azure Pipelines](../build/ci-build-git.md) + +- [Configure build run numbers](../process/run-number.md) + +- [Pipeline caching](../release/caching.md) + diff --git a/docs/pipelines/release/index.md b/docs/pipelines/release/index.md index 8253e3d49a3..a9f6a086a9d 100644 --- a/docs/pipelines/release/index.md +++ b/docs/pipelines/release/index.md @@ -3,7 +3,7 @@ title: Classic release pipelines description: Overview of classic release pipelines ms.assetid: 126C3E1C-9DB3-4E46-918D-FF5600BF8FC9 ms.topic: conceptual -ms.custom: seodec18, engagement-fy23 +ms.custom: engagement-fy23 ms.author: ronai author: RoopeshNair ms.date: 06/02/2023 @@ -52,14 +52,35 @@ As part of every deployment, Azure Pipelines executes the following steps: ## Deployment model -Azure release pipelines support a wide range of [artifact sources](artifacts.md#sources) including Jenkins, Azure Artifacts, and Team City. The following example illustrates a deployment model using Azure release pipelines: +Azure release pipelines support a wide range of [artifact sources](artifacts.md#artifact-sources) including Jenkins, Azure Artifacts, and Team City. The following example illustrates a deployment model using Azure release pipelines: In the following example, the pipeline consists of two build artifacts originating from separate build pipelines. The application is initially deployed to the *Dev* stage and then to two separate *QA* stages. If the deployment is successful in both QA stages, the application will be deployed to *Prod ring 1* and then to *Prod ring 2*. Each production ring represents multiple instances of the same web app, deployed to different locations across the world. :::image type="content" source="media/definition-01.png" alt-text="A screenshot showing a release pipeline deployment steps."::: +## Releases vs deployments + +A **release** is a construct that holds a versioned set of artifacts specified in a CI/CD pipeline. It includes a snapshot of all the information required to carry out all the tasks and actions in the release pipeline, such as stages, tasks, policies such as triggers and approvers, and deployment options. There can be multiple releases from one release pipeline, and information about each one is stored and displayed in Azure Pipelines for the specified [retention period](../policies/retention.md#release). + +A **deployment** is the action of running the tasks for one stage, which can include running automated tests, deploying build artifacts, and whatever other actions are specified for that stage. +Initiating a release starts each deployment based on the settings and policies defined in the original release pipeline. There can be multiple deployments of each release even for one stage. When a deployment of a release fails for a stage, you can redeploy the same release to that stage. To redeploy a release, simply navigate to the release you want to deploy and select deploy. + +The following diagram shows the relationship between release, release pipelines, and deployments. + +:::image type="content" source="media/release-deploy.png" alt-text="A diagram illustrating the difference between releases and deployments."::: + ## FAQ +#### Q: Why wasn't my deployment triggered? + +A: Creating a release pipeline doesn't automatically start a deployment. Here are a few reasons why this might happen: + +- [Deployment Triggers](triggers.md): defined deployment triggers may cause the deployment to pause. This can occur with scheduled triggers or when there's a delay until deployment to another stage is complete. + +- [Queuing Policies](../process/stages.md#queuing-policies): these policies dictate the order of execution and when releases are queued for deployment. + +- [Pre-Deployment Approvals or Gates](approvals/index.md): specific stages may require pre-deployment approvals or gates, preventing deployment until all defined conditions are met. + #### Q: How can I edit variables at release time? A: In the **Variables** tab of your release pipeline, Select the **Settable at release time** checkbox for the variables that you wish to modify when a release is queued. @@ -93,10 +114,10 @@ When specifying the format mask, you can use the following predefined variables. | **System.TeamProject** | The name of the project to which this build belongs. | | **Release.ReleaseId** | The ID of the release, which is unique across all releases in the project. | | **Release.DefinitionName** | The name of the release pipeline to which the current release belongs. | -| **Build.BuildNumber** | The number of the build contained in the release. If a release has multiple builds, it's the number of the [primary build](artifacts.md#primary-source). | -| **Build.DefinitionName** | The pipeline name of the build contained in the release. If a release has multiple builds, it's the pipeline name of the [primary build](artifacts.md#primary-source). | +| **Build.BuildNumber** | The number of the build contained in the release. If a release has multiple builds, it's the number of the [primary build](artifacts.md). | +| **Build.DefinitionName** | The pipeline name of the build contained in the release. If a release has multiple builds, it's the pipeline name of the [primary build](artifacts.md). | | **Artifact.ArtifactType** | The type of the artifact source linked with the release. For example, this can be **Azure Pipelines** or **Jenkins**. | -| **Build.SourceBranch** | The branch of the [primary artifact source](artifacts.md#primary-source). For Git, this is of the form **main** if the branch is **refs/heads/main**. For Team Foundation Version Control, this is of the form **branch** if the root server path for the workspace is **$/teamproject/branch**. This variable is not set for Jenkins or other artifact sources. | +| **Build.SourceBranch** | The branch of the [primary artifact source](artifacts.md). For Git, this is of the form **main** if the branch is **refs/heads/main**. For Team Foundation Version Control, this is of the form **branch** if the root server path for the workspace is **$/teamproject/branch**. This variable is not set for Jenkins or other artifact sources. | | **Custom variable** | The value of a global configuration property defined in the release pipeline. You can update the release name with custom variables using the [Release logging commands](https://github.com/microsoft/azure-pipelines-tasks/blob/master/docs/authoring/commands.md#release-logging-commands) | #### Q: How can I define the retention period for my releases? diff --git a/docs/pipelines/release/integrate-jenkins-pipelines-cicd.md b/docs/pipelines/release/integrate-jenkins-pipelines-cicd.md deleted file mode 100644 index 6507e151a45..00000000000 --- a/docs/pipelines/release/integrate-jenkins-pipelines-cicd.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: Deploy Jenkins CI builds -description: Set up continuous integration (CI) and continuous deployment (CD) for your apps using Jenkins and Azure Pipelines -ms.topic: tutorial -ms.author: ronai -ms.reviewer: vijayma -ms.assetid: CE485C57-C26A-4B9D-9D75-2FDDFB3361D6 -ms.custom: mvc, seodec18, devx-track-jenkins -ms.date: 01/15/2019 -monikerRange: '<= azure-devops' ---- - -# Continuously deploy from a Jenkins build - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - -Azure Pipelines supports integration with Jenkins so that you can use -Jenkins for Continuous Integration (CI) while gaining several DevOps benefits -from an Azure Pipelines release pipeline that deploys to Azure: - -* Reuse your existing investments in Jenkins build jobs -* Track work items and related code changes -* Get end-to-end traceability for your CI/CD workflow -* Consistently deploy to a range of cloud services -* Enforce quality of builds by gating deployments -* Define work flows such as manual approval processes and CI triggers -* Integrate Jenkins with JIRA and Azure Pipelines to show associated issues for each Jenkins job -* Integrate with other service management tools such as [ServiceNow](approvals/servicenow.md) - -A typical approach is to use Jenkins to build an app from source -code hosted in a Git repository such as GitHub and then deploy it to -Azure using Azure Pipelines. - -![Schematic of deployment from GitHub and Jenkins to Azure](media/integrate-jenkins-vsts-cicd/schematic1.png) - -## Before you begin - -* You'll need the source code for your app hosted in a repository such as GitHub, Azure Repos, GitHub Enterprise Server, - Bitbucket Cloud, or any another source control provider that Jenkins can interact with. -* You'll need a Jenkins server where you run your CI builds. You can quickly - [set up a Jenkins server on Azure](/azure/developer/jenkins/configure-on-linux-vm). -* You'll need a Jenkins project that builds you app. For example, - you can [build a Java app with Maven](https://jenkins.io/doc/tutorials/build-a-java-app-with-maven/) on Jenkins. - -## Link Jenkins with Azure Pipelines - -Create a Jenkins service connection from the **Service connections** section of the project settings page. - -::: moniker range="< azure-devops" -In TFS, open the **Services** page from the "settings" icon in the top menu bar. -::: moniker-end - -For more information, see [Jenkins service connection](../library/service-endpoints.md#jenkins-service-connection). -If you are not familiar with the general concepts in this section, see -[Accessing your project settings](../../project/navigation/go-to-service-page.md#open-project-settings) -and [Creating and using a service connection](../library/service-endpoints.md). - - -## Add a Jenkins artifact - -Create a new release pipeline and add a Jenkins artifact to it. -After you select the Jenkins service connection, you can select an existing Jenkins job to deploy. - -It's possible to [store the output from a Jenkins build in Azure blob storage](/azure/developer/jenkins/azure-storage-blobs-as-build-artifact-repository). -If you have configured this in your Jenkins project, choose **Download artifacts from Azure storage** -and select the default version and source alias. - -For more information, see [Jenkins artifacts](artifacts.md#jenkins). -If you are not familiar with the general concepts in this section, see -[Creating a release pipeline](../create-first-pipeline.md) -and [Release artifacts and artifact sources](artifacts.md). - -## Define the deployment steps - -Add the tasks you require to deploy your app to your chosen target in the **Agent job** section in the **Tasks** page -of your release pipeline. For example, add the **Azure App Service Deploy** task to deploy a web app. - -#### [YAML](#tab/yaml/) -::: moniker range="azure-devops" - -Add the **Azure App Service Deploy** task YAML code to a job in the `.yml` file at the root of the repository. - -```YAML - -... -jobs: -- job: DeployMyApp - pool: - name: Default - steps: - - task: AzureRmWebAppDeployment@4 - inputs: - connectionType: 'AzureRM' - azureSubscription: your-subscription-name - appType: webAppLinux - webAppName: 'MyApp' - deployToSlotOrASE: false - packageForLinux: '$(System.DefaultWorkingDirectory)/**/*.zip' - takeAppOfflineFlag: true -... -``` - -::: moniker-end - -::: moniker range="< azure-devops" - -YAML builds aren't yet available on TFS. - -::: moniker-end - -#### [Classic](#tab/classic/) -1. In the **Tasks** page of your release pipeline, choose the **+** - (plus sign) in the **Agent job** section. - -1. In the list of tasks, select **Azure App Service Deploy** and choose **Add**. - You can use the Search box to quickly find the required task. - -1. Save the pipeline. - -For an example of using the classic editor, see [Deploy an Azure Web App](../targets/webapp.md?tabs=classic). - -* * * -Whenever you trigger your Azure release pipeline, the artifacts published by the Jenkins CI job -are downloaded and made available for your deployment. You get full traceability of your workflow, -including the commits associated with each job. - -[See more details of the Azure App Service Deploy task](/azure/devops/pipelines/tasks/reference/azure-rm-web-app-deployment-v4) -If you are not familiar with the general concepts in this section, see -[Build and release jobs](../process/phases.md?tabs=yaml) -and [Using tasks in builds and releases](../tasks/index.md). - -## Enable continuous deployment - -If your Jenkins server is **hosted in Azure**, or your Azure DevOps organization -has **direct visibility** to your Jenkins server, you can easily enable a continuous -deployment (CD) trigger within your release pipeline that causes a release to be -created and a deployment started every time the source artifact is updated. - -To enable continuous deployment for an Azure hosted or directly visible Jenkins server: - -1. Open the [continuous deployment trigger](triggers.md#release-triggers) pane from the **Pipelines** page of your release pipeline. - -1. Change the setting to **Enabled**. - -1. Choose **Add** and select the branch you want to create the trigger for. Or select the default branch. - -However, if you have an **on-premises** Jenkins server, or your Azure DevOps organization **does not** have direct visibility -to your Jenkins Server, you can trigger a release for an Azure pipeline from a Jenkins project using the following steps: - -1. Create a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) (PAT) in your Azure DevOps or TFS organization. Jenkins requires this information to access your organization. - Ensure you keep a copy of the token information for upcoming steps in this section. - -1. Install the [Team Foundation Server plugin](https://www.jenkins.io/doc/pipeline/steps/tfs/) on your Jenkins server. - -1. Within your Jenkins project, you will find a new post build action named **Trigger release in TFS/Team Services**. - Add this action to your project. - -1. Enter the collection URL for your Azure DevOps organization or TFS server as `https://.visualstudio.com/DefaultCollection/` - -1. Leave **username** empty and enter your PAT as the password. - -1. Select the Azure DevOps project and the release definition to trigger. - -Now a new CD release will be triggered every time your Jenkins CI job is completed. - -## See also - -:::moniker range=">=azure-devops-2019" - -* [Artifacts](artifacts.md) -* [Stages](../process/stages.md) -* [Triggers](triggers.md) -* [YAML schema reference](/azure/devops/pipelines/yaml-schema) - -:::moniker-end - -:::moniker range=" [!div class="checklist"] +> +> - Create a service principal +> - Create a service connection +> - Configure your inbound access points +> - Query a private Azure key vault from your pipeline + +## Prerequisites + +- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. + +- An Azure subscription. [Create a free Azure account](https://azure.microsoft.com/free) if you don't have one already. + +- An Azure Key Vault. [Create a new Azure Key Vault](/azure/key-vault/general/quick-create-portal) if you haven't already. + +## Access a private key vault + +Azure Pipelines enables developers to link an Azure Key Vault to a variable group and map selective vault secrets to it. A key vault that is used as a variable group can be accessed: + +1. From Azure DevOps, during the variable group configuration time. + +2. From a Self-hosted agent, during the pipeline job runtime. + +:::image type="content" source="media/access-private-key-vault.png" alt-text="A diagram showing the two different paths to access a private key vault."::: + +## Create a service principal + +Start by creating a new service principal, this will enable you to access Azure resources. Next, you will need to create a new ARM service connection in Azure DevOps, then set up a federated credential for your service principal in Azure before verifying and saving your service connection in Azure DevOps. + +1. Navigate to [Azure portal](https://ms.portal.azure.com/). + +1. Open the **Cloud Shell** from the menu bar, and then select **Bash**. + +1. Run the following command to create a new service principal: + + ```Azure CLI + az ad sp create-for-rbac --name YOUR_SERVICE_PRINCIPAL_NAME + ``` + +1. Make sure to copy the output, as we'll use it to create the service connection in the next step. + +::: moniker range="azure-devops" + +## Create a service connection + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Project settings** > **Service connections** > **New service connection**. + +1. Select **Azure Resource Manager**, and then select **Next**. + +1. For **Identity Type**, select **App registration (automatic)** from the dropdown menu. + +1. For **Credential**, leave the default recommended value: **Workload identity federation**. + +1. For **Scope level**, select **Subscription, and then select your subscription from the dropdown menu. + +1. Select a **Resource group** if you want to limit access to the specified resource group only. + +1. Provide a name for your service connection, and then select the **Grant access permission to all pipelines** checkbox to allow all pipelines to use this service connection. + +1. Select **Save** when you're done. + + :::image type="content" source="media/automatic-service-connection-service-principal.png" alt-text="A screenshot displaying how to configure an ARM service connection for a service principal."::: + +## Create a federated credential + +1. Navigate to [Azure portal](https://portal.azure.com/), enter your service principal's *ClientID* in the search bar, and then select your *Application*. + +1. Under **Manage**, select **Certificates & secrets** > **Federated credentials**. + +1. Select **Add credential**, and then for **Federated credential scenario**, select **Other issuer**. + +1. For **Issuer**, paste the following URL replacing the placeholder with your organization GUID. You can find your organization ID by navigating to **Organization settings** > **Microsoft Entra** > Download the list of Azure DevOps organizations connected to your directory. + + ``` + https://login.microsoftonline.com//v2.0 + ``` + +1. For **Subject identifier**, paste the following URL replacing the placeholder with your organization name, project name, and service connection name. + + ``` + ENTRA_PREFIX/sc/ORGANIZATION_NAME/PROJECT_NAME/SERVICE_CONNECTION_NAME + ``` + +1. Provide a **Name** for your federated credential, and then select **Add** when you're done. + +::: moniker-end + +::: moniker range="azure-devops-2020 || azure-devops-2022" + +## Create a service connection + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Project settings** > **Service connections** > **New service connection**. + +1. Select **Azure Resource Manager**, > **Next**, and then select **Service principal (manual)** > **Next**. + +1. Select **Azure Cloud** for **Environment** and **Subscription** for the **Scope Level**, then enter your **Subscription Id** and your **Subscription Name**. + +1. Enter your service principal information, and then select **Verify**. + +1. After successful verification, name your service connection, add a description, and then check the **Grant access permission to all pipelines** checkbox. Select **Verify and save** when you're done. + +> [!TIP] +> If you're unable to verify your service principal connection, grant the service principal **Reader** access to your subscription. + +::: moniker-end + +::: zone pivot="access-from-azure-devops" + +## Access a private key vault from Azure Devops + +In this section, we'll explore two methods for accessing a private key vault from Azure DevOps. First, we'll use Variable Groups to link and map secrets from our key vault, followed by setting up inbound access by allowing static IP ranges. We establish inbound access because Azure Pipelines uses the posted Azure DevOps Public IP when querying the Azure Key Vault from a Variable Group. Therefore, by adding inbound connections to the Azure Key Vault firewall, we can successfully connect to our Azure Key Vault. + +For our second approach, we'll demonstrate dynamically adding the Microsoft-hosted agent IP address to our key vault's firewall allowlist, querying the key vault, and subsequently removing the IP after completion. This second approach is for demonstration purposes and is not the recommended approach by Azure Pipelines. + +## 1 - Map key vault secrets with a variable group + +::: moniker range="azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines** > **Library**, and then select **+ Variable group**. + +1. Name your variable group, and then select the toggle button to enable the **Link secrets from an Azure Key Vault as variable** button. + +1. Select the service connection you created earlier, select your key vault, and then select **Authorize**. + +1. Under **Variables**, select **Add** to add your secret, then select **Save** when you're done. + +> [!NOTE] +> Make sure that your **service connection** has the *Get* and *list* permissions, and your **service principal** is assigned the *Key Vault Secrets User* role in your private key vault. + +#### 1.1 Set up the service connection permissions + +1. Navigate to your Azure key vault, and then select **Access policies**. + +1. Select **Create**, and under **Secret permissions**, add the **Get** and **List** permissions, and then select **Next**. + +1. Add your service connection in the search bar, select it, and then select **Next**. + +1. Select **Next** once more, review your settings, and then select **Review + create** when you're done. + +#### 1.2 Set up the service principal permissions + +1. Navigate to your Azure key vault, and then select **Access control (IAM)**. + +1. Select **Add** > **Add role assignment** > then select the **Role** tab. + +1. Select the **Key Vault Secrets User** role, and then select **Next**. + +1. Select **Select members** > add your service principal > **Select**. + +1. Select **Review + assign** when you're done. + +::: moniker-end + +::: moniker range="< azure-devops" + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines** > **Library**, and then select **+ Variable group**. + +1. Name your variable group, and then select the toggle button to enable the **Link secrets from an Azure Key Vault as variable** button. + +1. Select your Azure service connection you created earlier from the dropdown menu, and then select your key vault. + + :::image type="content" source="media/new-variable-group-get-list-error.png" alt-text="A screenshot showing how to link a variable group to an Azure Key Vault with an error indicating missing get and list permissions."::: + +1. If you encounter the error message: *Specified Azure service connection needs to have "Get, List" secret management permissions on the selected key vault.* as shown above. Navigate to your key vault in Azure portal, select **Access control (IAM)** > **Add role assignment** > **key vault secrets user** > **Next**, then add your service principal, then select **Review + assign** when you're done. + + :::image type="content" source="media/add-role-assignment-secret-user-service-principal.png" alt-text="A screenshot showing how to add a service principal as a secret user for an Azure Key Vault."::: + +1. Add your secrets and then select **Save** when you're done. + +::: moniker-end + +## 2 - Configure inbound access from Azure DevOps + +To enable access to your key vault from Azure DevOps, you must grant access from specific static IP ranges. These ranges are determined by the geographical location of your Azure DevOps organization. + +1. Sign in to your Azure DevOps organization. + +1. Select **Organization settings**. + +1. Navigate to **Overview**, where you'll find the geographical location listed towards the bottom of the page. + + :::image type="content" source="media/organization-geographical-location.png" alt-text="A screenshot showing how to find the geographical location of your Azure DevOps organization."::: + +1. [Find your geography IP V4 ranges](../../organizations/security/allow-list-ip-url.md#inbound-connections). + +1. [Configure your key vault](/azure/key-vault/general/network-security#key-vault-firewall-enabled-ipv4-addresses-and-ranges---static-ips) to allow access from static IP ranges. + +## 3 - Query a private key vault with a variable group + +In this example, we use the variable group, set up earlier and authorized with a service principal, to query and copy our secret from our private Azure Key Vault simply by using the linked variable group. Azure Pipelines uses the posted public IP when querying the Azure Key Vault from a Variable Group, so make sure you have [configured inbound access](#2---configure-inbound-access-from-azure-devops) for this to work properly: + +```yml +variables: +- group: mySecret-VG + +steps: +- task: CmdLine@2 + inputs: + script: 'echo $(mySecret) > secret.txt' + +- task: CopyFiles@2 + inputs: + Contents: secret.txt + targetFolder: '$(Build.ArtifactStagingDirectory)' + +- task: PublishBuildArtifacts@1 + inputs: + PathtoPublish: '$(Build.ArtifactStagingDirectory)' + ArtifactName: 'drop' + publishLocation: 'Container' +``` + +## Alternative method - Dynamically allow Microsoft-hosted agent IP + +In this second approach, we'll start by querying the IP of the Microsoft-hosted agent at the beginning of our pipeline. Then, we'll add it to the key vault allowlist, proceed with the remaining tasks, and finally, remove the IP from the key vault's firewall allowlist. + +> [!NOTE] +> This approach is for demonstration purposes only and is not the recommended approach by Azure Pipelines. + +```yml +- task: AzurePowerShell@5 + displayName: 'Allow agent IP' + inputs: + azureSubscription: 'YOUR_SERVICE_CONNECTION_NAME' + azurePowerShellVersion: LatestVersion + ScriptType: InlineScript + Inline: | + $ip = (Invoke-WebRequest -uri "http://ifconfig.me/ip").Content + Add-AzKeyVaultNetworkRule -VaultName "YOUR_KEY_VAULT_NAME" -ResourceGroupName "YOUR_RESOURCE_GROUP_NAME" -IpAddressRange $ip + echo "##vso[task.setvariable variable=agentIP]ip" + +- task: AzureKeyVault@2 + inputs: + azureSubscription: 'YOUR_SERVICE_CONNECTION_NAME' + KeyVaultName: 'YOUR_KEY_VAULT_NAME' + SecretsFilter: '*' + RunAsPreJob: false + +- task: AzurePowerShell@5 + displayName: 'Remove agent IP' + inputs: + azureSubscription: 'YOUR_SERVICE_CONNECTION_NAME' + azurePowerShellVersion: LatestVersion + ScriptType: InlineScript + Inline: | + $ipRange = $env:agentIP + "/32" + Remove-AzKeyVaultNetworkRule -VaultName "YOUR_KEY_VAULT_NAME" -IpAddressRange $ipRange + condition: succeededOrFailed() +``` + +> [!IMPORTANT] +> Ensure that the service principal you're using to access your key vault from your pipeline holds the **Key vault contributor** role within your key vault's Access control (IAM). + +::: zone-end + +::: zone pivot="access-from-self-hosted-agent" + +## Access a private key vault from a self-hosted agent + +To have the ability to access a private key vault from an Azure Pipelines agent, you'll need to use either a Self-hosted agent ([Windows](../agents/windows-agent.md), [Linux](../agents/linux-agent.md), [Mac](../agents/osx-agent.md)) or [Scale Set agents](../agents/scale-set-agents.md). This is because Microsoft Hosted agents, like other generic compute services, are not included in the key vault's list of [trusted services](/azure/key-vault/general/overview-vnet-service-endpoints#trusted-services). + +To establish connectivity with your private key vault, you must provide a [line of sight](../agents/agents.md#communication-to-deploy-to-target-servers) connectivity by configuring a private endpoint for your key vault. This endpoint must be routable and have its private DNS name resolvable from the Self-hosted Pipeline agent. + +## 1 - Configure inbound access from a self-hosted Agent + +1. Follow the provided instruction to [Create a virtual network](/azure/virtual-network/quick-create-portal). + +1. In [Azure portal](https://portal.azure.com/), use the search bar at the top of the page to find your Azure Key Vault. + +1. Once you've located your key vault in the search results, select it, and then navigate to **Settings** > **Networking**. + +1. Select **Private endpoint connections**, and then select **Create** to create a new private endpoint. + + :::image type="content" source="media/key-vault-private-endpoint.png" alt-text="A screenshot showing how to create a new private endpoint connection for an Azure Key Vault."::: + +1. Select the **Resource Group** that hosts the virtual network that you created earlier. Provide a **Name** and a **Network Interface Name** for your instance, and make sure that you select the same **Region** as the virtual network you created earlier. Select **Next** when you're done. + + :::image type="content" source="media/key-vault-new-private-endpoint.png" alt-text="A screenshot showing how to configure the basics tab when creating a new private endpoint instance for your Azure Key Vault."::: + +1. Select **Connect to an Azure resource in my directory** for the **Connection method**, and then choose **Microsoft.KeyVault/vaults** from the dropdown menu for the **Resource type**. Select your **Resource** from the dropdown menu. The **Target sub-resource** will be auto-populated with the value: *vault*. Select **Next** when you're done. + + :::image type="content" source="media/key-vault-private-endpoint-resource.png" alt-text="A screenshot showing how to configure the resource tab when creating a new private endpoint instance for your Azure Key Vault."::: + +1. Under the **Virtual Network** tab, select the **Virtual network** and **Subnet** that you created earlier and leave the rest of the fields as default. Select **Next** when you're done. + +1. Continue through the **DNS** and **Tags** tabs, accepting the default settings. Under the **Review + Create** tab, select **Create** when you're done. + +1. Once your resource is deployed, navigate to your key vault > **Settings** > **Networking** > **Private endpoint connections**, your private endpoint should be listed with a **Connection state** *approved*. If you're linking to an Azure resource in a different directory, you'll need to wait for the resource owner to approve your connection request. + + :::image type="content" source="media/key-vault-approved-private-endpoint-connection.png" alt-text="A screenshot showing an approved private endpoint connection"::: + +## 2 - Allow your virtual network + +1. Navigate to [Azure portal](https://portal.azure.com/), and then find your Azure Key Vault. + +1. Select **Settings** > **Networking**, and make sure you're under the **Firewalls and virtual networks** tab. + +1. Select **Add a virtual network** > **Add existing virtual networks**. + +1. Select your **Subscription** from the dropdown menu, and then select the virtual network you created earlier, and then select your **Subnets**. + +1. Select **Add** when you're done, and then scroll to the bottom of the page and select **Apply** to save your changes. + + :::image type="content" source="media/add-new-virtual-network-key-vault-firewall.png" alt-text="A screenshot showing how to add an existing virtual network to Azure Key Vault firewall."::: + +## 3 - Query a private key vault from a self-hosted Agent + +The following example uses an agent set up on the virtual network's VM to query the private key vault through the variable group: + +```yml +pool: Self-hosted-pool + +variables: + group: mySecret-VG + +steps: +- task: CmdLine@2 + inputs: + script: 'echo $(mySecret) > secret.txt' + +- task: CopyFiles@2 + inputs: + Contents: secret.txt + targetFolder: '$(Build.ArtifactStagingDirectory)' + +- task: PublishBuildArtifacts@1 + inputs: + PathtoPublish: '$(Build.ArtifactStagingDirectory)' + ArtifactName: 'drop' + publishLocation: 'Container' +``` + +If you prefer not to grant Azure DevOps inbound access to your private key vault, you can use the [AzureKeyVault](/azure/devops/pipelines/tasks/reference/azure-key-vault-v2) task to query your key vault. However, you must ensure that you allow the virtual network hosting your agent in your key vault firewall settings. + +```yml +pool: Self-hosted-pool + +steps: +- task: AzureKeyVault@2 + inputs: + azureSubscription: '$(SERVICE_CONNECTION_NAME)' + keyVaultName: $(KEY_VAULT_NAME) + SecretsFilter: '*' + +- task: CmdLine@2 + inputs: + script: 'echo $(mySecret) > secret.txt' + +- task: CopyFiles@2 + inputs: + Contents: secret.txt + targetFolder: '$(Build.ArtifactStagingDirectory)' + +- task: PublishBuildArtifacts@1 + inputs: + PathtoPublish: '$(Build.ArtifactStagingDirectory)' + ArtifactName: 'drop' + publishLocation: 'Container' +``` + +::: zone-end + +## Troubleshoot + +If you're experiencing the following errors, follow the steps in this section to troubleshoot and resolve the issue: + +- ```Public network access is disabled and request is not from a trusted service nor via an approved private link.``` + +This indicates that public access has been disabled, and neither a private endpoint connection nor firewall exceptions have been set up. Follow the steps under [#configure-inbound-access-from-a-self--hosted-agent] and [Configure inbound access from Azure DevOps](#2---configure-inbound-access-from-azure-devops) to set up access to your private key vault. + +- ```Request was not allowed by NSP rules and the client address is not authorized and caller was ignored because bypass is set to None Client address: ``` + +This error message indicates that the key vault's public access has been disabled and the **Allow trusted Microsoft services to bypass this firewall** option is unchecked, but the client IP address hasn't been added to the key vault firewall. Navigate to your key vault in the Azure portal, then **Settings** > **Networking** and add your client IP to the firewall's allowlist. + +- ```Error: Client address is not authorized and caller is not a trusted service.``` + +Make sure you add your geography's IPV4 ranges to your key vault allowlist. See [Configure inbound access from Azure DevOps](#2---configure-inbound-access-from-azure-devops) for details. +Alternatively, you can jump to [Dynamically allow Microsoft-hosted agent IP](#alternative-method---dynamically-allow-microsoft-hosted-agent-ip) to learn how to add your client IP to the key vault's firewall during runtime. + +## Related content + +- [Manage service connections](../library/service-endpoints.md) +- [Library & shared resources](../library/index.md) +- [Manage agents and agent pools](../agents/agents.md) + diff --git a/docs/pipelines/release/key-vault-in-own-project.md b/docs/pipelines/release/key-vault-in-own-project.md index f800b14d7b8..340e980b022 100644 --- a/docs/pipelines/release/key-vault-in-own-project.md +++ b/docs/pipelines/release/key-vault-in-own-project.md @@ -1,9 +1,10 @@ --- -title: Query and use Azure Key Vault secrets in your Pipeline -description: How to set up Azure Key vaults in your project and use it in your Azure Pipelines +title: Query and use Azure Key Vault secrets in your pipeline +description: Lean how to set up Azure Key vaults with your own project and use it in your Azure Pipelines. ms.topic: tutorial -ms.date: 08/26/2021 -monikerRange: '>= azure-devops-2019' +ms.date: 04/14/2025 +monikerRange: "<=azure-devops" +ms.custom: arm2024 "recommendations": "true" --- @@ -11,45 +12,31 @@ monikerRange: '>= azure-devops-2019' [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -With Azure Key Vault, you can securely store and manage your sensitive information such as passwords, API keys, certificates, etc. using Azure Key Vault, you can easily create and manage encryption keys to encrypt your data. Azure Key Vault can also be used to manage certificates for all your resources. +Azure Key Vaults enable developers to securely store and manage sensitive information such as passwords, API keys, and certificates. This article walks you through how to query and use secrets from an Azure Key Vault in your pipeline. ## Prerequisites -- An Azure DevOps organization. [Create one for free](../../organizations/accounts/create-organization.md#create-an-organization) if you don't already have one. -- Your own project. [Create a project](../../organizations/projects/create-project.md#create-a-project) if you don't already have one. -- Your own repository. [Create a new Git repo](../../repos/git/create-new-repo.md) if you don't already have one. -- An Azure subscription. [Create a free Azure account](https://azure.microsoft.com/free) if you don't already have one. - -## Create an Azure Key Vault +| **Product** | **Requirements** | +|-------------|--------------------| +| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).
      - **Permissions:**
          - To grant access to all pipelines in the project: You must be a member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md).
          - To create service connections: You must have the *Administrator* or *Creator* role for [service connections](../library/add-resource-protection.md). | +| **GitHub** | - A [GitHub](https://github.com) account and a [GitHub repository](../../repos/git/create-new-repo.md).
      - A [GitHub service connection](../library/service-endpoints.md#github-service-connection) to authorize Azure Pipelines.| +| **Azure** | - An [Azure subscription](https://azure.microsoft.com/free/). | +## Create a Key Vault ### [Azure portal](#tab/portal/) -1. Navigate to [Azure portal](https://portal.azure.com/). - -1. Select **Create a resource** in the left navigation pane. - - :::image type="content" source="media/create-resource-pane.png" alt-text="Create a new resource from the left nav pane"::: - -1. Search for **Key Vault** and then click Enter. - - :::image type="content" source="media/search-resources.png" alt-text="Search for Azure Key Vault"::: - -1. Select **Create** to create a new Azure Key Vault. +1. Sign in to the [Azure portal](https://portal.azure.com/), and then select **Create a resource**. - :::image type="content" source="media/create-key-vault.png" alt-text="Create a new Azure Key Vault"::: +1. Under **Key Vault**, select **Create** to create a new Azure Key Vault. -1. Select your **Subscription** and then add a new **Resource group**. Enter a **Key vault name** and select a **Region** and a **Pricing tier**. Select **Review + create** when you are done. +1. Select your **Subscription** from the dropdown menu, and then select an existing **Resource group** or create a new one. Enter a **Key vault name**, select a **Region**, choose a **Pricing tier**, and select **Next** if you want to configure additional properties. Otherwise, select **Review + create** to keep the default settings. - :::image type="content" source="media/create-key-vault-window.png" alt-text="Create a new key vault window"::: - -1. Select **Go to resource** when the deployment of your new resource is completed. - - :::image type="content" source="media/go-to-resources.png" alt-text="Go to resource"::: +1. Once the deployment is complete, select **Go to resource**. ### [Azure CLI](#tab/cli/) -1. First we need to set our default region and Azure subscription. +1. First, set your default region and Azure subscription: - Set default subscription: @@ -63,13 +50,13 @@ With Azure Key Vault, you can securely store and manage your sensitive informati az config set defaults.location= ``` -1. Create a new resource group to host your Azure Key Vault. A resource group is a container that holds related resources for an Azure solution. +1. Create a new resource group to host your Azure Key Vault. A resource group is a container that holds related resources for an Azure solution: ```azurecli az group create --name ``` -1. Create a new Azure Key Vault. +1. Create a new Azure Key Vault: ```azurecli az keyvault create \ @@ -78,31 +65,189 @@ With Azure Key Vault, you can securely store and manage your sensitive informati ``` --- -## Configure Key Vault access permissions +## Set up authentication + +# [Managed Identity](#tab/managedidentity) + +## Create a user-assigned managed identity + +1. Sign in to the [Azure portal](https://portal.azure.com/), then search for the **Managed Identities** service in the search bar. + +1. Select Create, and fill out the required fields as follows: + + - **Subscription**: Select your subscription from the dropdown menu. + - **Resource group**: Select an existing resource group or create a new one. + - **Region**: Select a region from the dropdown menu. + - **Name**: Enter a name for your user-assigned managed identity. + +1. Select **Review + create** when you're done. + +1. Once the deployment is complete, select **Go to resource**, then copy the **Subscription** and **Client ID**, you'll need them in the next steps. + +1. Navigate to **Settings** > **Properties**, and copy your managed identity's **Tenant ID** to use later. + +## Set up key vault access policies + +1. Navigate to [Azure portal](https://portal.azure.com/), and use the search bar to find the key vault you created earlier. + +1. Select **Access policies**, then select **Create** to add a new policy. + +1. Under **Secret permissions**, select the **Get** and **List** checkboxes. + +1. Select **Next**, then paste the **Client ID** of the managed identity you created earlier into the search bar. + +1. Select your managed identity, select **Next**, then **Next** once more. + +1. Review your new policy, and then select **Create** when you're done. + +## Create a service connection + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Project settings** > **Service connections**, and then select **New service connection**. + +1. Select **Azure Resource Manager**, then select **Next**. + +1. Under **Identity Type**, select **Managed identity** from the dropdown menu. + +1. For **Step 1: Managed identity details**, fill out the fields as follows: + + - **Subscription for managed identity**: Select the subscription that contains your managed identity. + + - **Resource group for managed identity**: Select the resource group where your managed identity is hosted. + + - **Managed Identity**: Select your managed identity from the dropdown menu. + +1. For **Step 2: Azure Scope**, fill out the fields as follows: + + - **Scope level for service connection**: Select **Subscription**. + + - **Subscription for service connection**: Select the subscription your managed identity will access. + + - **Resource group for Service connection**: (Optional) Specify this if you want to restrict access to a specific resource group. + +1. For **Step 3: Service connection details**: + + - **Service connection name**: Provide a name for your service connection. + + - **Service Management Reference**: (Optional) Include context information from an ITSM database. + + - **Description**: (Optional) Add a description. + +1. Under **Security**, check the **Grant access permission to all pipelines** box to allow all pipelines to use this service connection. If you leave this unchecked, you’ll need to manually grant access for each pipeline. + +1. Select **Save** to validate and create the service connection. + + :::image type="content" border="false" source="media/managed-identity-service-connection.png" alt-text="A screenshot displaying how to create a managed identity ARM service connection." lightbox="media/managed-identity-service-connection.png"::: + +# [Service Principal](#tab/serviceprincipal) + +## Create a service principal -Before proceeding with the next steps, we must first create a service principal to be able to query our Azure Key Vault from Azure Pipelines. Complete the steps in [Create a service principal](/azure/active-directory/develop/howto-create-service-principal-portal#register-an-application-with-azure-ad-and-create-a-service-principal), and then continue with the next steps. +In this step, you'll create a new [service principal](/cli/azure/azure-cli-sp-tutorial-1) in Azure so that your Azure Pipelines can access Azure Key Vault. -1. Navigate to [Azure portal](https://portal.azure.com/). +1. Navigate to [Azure portal](https://portal.azure.com/), then select the **>_** icon from the top menu to open the **Cloud Shell**. -2. Select the key vault you created in the previous step. +1. Select either **PowerShell** or **Bash** depending on your preference. -3. Select **Access policies**. +1. Run the following command to create a new service principal: - :::image type="content" source="media/access-policies.png" alt-text="configure access policies"::: + ```Azure CLI + az ad sp create-for-rbac --name YOUR_SERVICE_PRINCIPAL_NAME + ``` + +1. After the command runs, you’ll get an output similar to the following. Copy and save the output, you’ll need it to create a service connection in the next step. + + ```json + { + "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", + "displayName": "MyServicePrincipal", + "password": "***********************************", + "tenant": "aaaabbbb-0000-cccc-1111-dddd2222eeee" + } + ``` + +## Create a service connection + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Project settings**, and then select **Service connections**. + +1. Select **New service connection**, select **Azure Resource Manager**, and then select **Next**. + +1. Select **Service principal (manual)**, and then select **Next**. + +1. Under **Identity Type**, select **App registration or managed identity (manual)**. + +1. Under **Credential**, select **Workload identity federation**. + +1. Provide a name for your service connection, and then select **Next**. + +1. Copy the **Issuer** and the **Subject identifier** values. You'll need them in the next step. + +1. For **Environment**, Select **Azure Cloud** and for **Subscription scope** select **Subscription**. + +1. Enter your Azure **Subscription ID** and **Subscription name**. + +1. Under **Authentication**, paste your service principal's **Application (client) ID** and **Directory (tenant) ID** + +1. In the **Security** section, check the **Grant access permission to all pipelines** box to allow all pipelines to use this service connection. If you skip this, you’ll need to manually grant access per pipeline. + +1. Leave this page open, you’ll come back to complete it after you've (1) created the federated credential in Azure and (2) granted your service principal *Read* access at the subscription level. + + :::image type="content" border="false" source="media/service-principal-federated-credential-service-connection.png" alt-text="A screenshot displaying how to create an ARM service connection using App registration." lightbox="media/service-principal-federated-credential-service-connection.png"::: + +## Create a federated credential in Azure + +1. Navigate to [Azure portal](https://portal.azure.com/), then use the search bar to find your service principal by entering its **ClientID**. Select the matching *Application* from the results. + +1. Under **Manage**, select **Certificates & secrets** > **Federated credentials**. + +1. Select **Add credential**, then for **Federated credential scenario**, select **Other issuer**. -4. Select **Add Access Policy** to add a new policy. +1. In the **Issuer** field, paste the *Issuer* value you copied from your service connection earlier. -5. Add a **Get** and **List** to **Secret permissions**. +1. In the **Subject identifier** field, paste the *Subject identifier* you copied earlier. - :::image type="content" source="media/get-list-permissions.png" alt-text="Add get and list permissions"::: +1. Enter a **Name** for your federated credential, and then select **Add** when you're done. -6. Under **Select principal**, select to add a service principal and choose the one you created earlier. + :::image type="content" border="false" source="media/service-principal-federated-credential-in-azure.png" alt-text="A screenshot displaying how to create a federated credential for a service principal in Azure." lightbox="media/service-principal-federated-credential-in-azure.png"::: -7. Select **Save** when you are done. +## Add role assignment to your subscription + +Before you can verify the connection, you need to grant the service principal **Read** access at the subscription level: + +1. Navigate to [Azure portal](https://portal.azure.com/) + +1. Under **Azure services**, select **Subscriptions**, and then find and select your subscription. + +1. Select **Access control (IAM)**, and then select **Add** > **Add role assignment**. + +1. Under the **Role** tab, select **Reader**, and then select **Next**. + +1. Select **User, group, or service principal**, and then select **Select members**. + +1. In the search bar, paste your service principal's *Object ID*, select it, then click **Select**. + +1. Select **Review + assign**, review your settings, and then select **Review + assign** again to confirm. + +1. Once the role assignment is added. go back to your service connection in Azure DevOps and select **Verify and Save** to save your service connection. + +## Configure Key Vault access policies + +1. Navigate to the [Azure portal](https://portal.azure.com/), find the key vault you created earlier, and then select **Access policies**. + +1. Select **Create**, then under **Secret permissions** add both the **Get** and **List** permissions, and then select **Next**. + +1. Under **Principal**, paste your service principal's *Object ID*, select it, and then select **Next**. + +1. Select **Next** again, review your settings, and then select **Save** to apply the new policy. + +--- ## Query and use secrets in your pipeline -Using the [Azure Key Vault task](/azure/devops/pipelines/tasks/reference/azure-key-vault-v2) we can fetch the value of our secret and use it in subsequent tasks in our pipeline. One thing to keep in mind is that secrets must be explicitly mapped to env variable as shown in the example below. +Using the [Azure Key Vault task](/azure/devops/pipelines/tasks/reference/azure-key-vault-v2), you can now query and fetch secrets from Azure Key Vault and use them in subsequent tasks in your pipeline. Note that secrets must be explicitly mapped to environment variables, as shown in the following example: ```YAML pool: @@ -111,40 +256,29 @@ pool: steps: - task: AzureKeyVault@1 inputs: - azureSubscription: 'repo-kv-demo' ## YOUR_SERVICE_CONNECTION_NAME - KeyVaultName: 'kv-demo-repo' ## YOUR_KEY_VAULT_NAME - SecretsFilter: 'secretDemo' ## YOUR_SECRET_NAME. Default value: * - RunAsPreJob: false ## Make the secret(s) available to the whole job - -- task: DotNetCoreCLI@2 - inputs: - command: 'build' - projects: '**/*.csproj' - -- task: DotNetCoreCLI@2 - inputs: - command: 'run' - projects: '**/*.csproj' - env: - mySecret: $(secretDemo) + azureSubscription: 'SERVICE_CONNECTION_NAME' + KeyVaultName: 'KEY_VAULT_NAME' + SecretsFilter: '*' - bash: | echo "Secret Found! $MY_MAPPED_ENV_VAR" env: - MY_MAPPED_ENV_VAR: $(mySecret) + MY_MAPPED_ENV_VAR: $(SECRET_NAME) ``` -The output from the last bash command should look like this: +The output from the last bash step should look like this: ``` Secret Found! *** ``` > [!NOTE] -> If you want to query for multiple secrets from your Azure Key Vault, use the `SecretsFilter` argument to pass a comma-separated list of secret names: *'secret1, secret2'*. +> To query multiple secrets from your Azure Key Vault, use the `SecretsFilter` input and provide a comma-separated list of secret names, like: *'secret1, secret2'*. + +## Related content + +- [Protect secrets in Azure Pipelines](../security/secrets.md) -## Related articles +- [Access a private key vault from your pipeline](key-vault-access.md) -- [Manage service connections](../library/service-endpoints.md) -- [Define variables](../process/variables.md) -- [Publish Pipeline Artifacts](../publish-pipeline-artifact.md) \ No newline at end of file +- [Manage security in Azure Pipelines](../policies/permissions.md) diff --git a/docs/pipelines/release/media/access-private-key-vault.png b/docs/pipelines/release/media/access-private-key-vault.png new file mode 100644 index 00000000000..7389b7f8b15 Binary files /dev/null and b/docs/pipelines/release/media/access-private-key-vault.png differ diff --git a/docs/pipelines/release/media/add-new-virtual-network-key-vault-firewall.png b/docs/pipelines/release/media/add-new-virtual-network-key-vault-firewall.png new file mode 100644 index 00000000000..7d66236fc4e Binary files /dev/null and b/docs/pipelines/release/media/add-new-virtual-network-key-vault-firewall.png differ diff --git a/docs/pipelines/release/media/add-role-assignment-secret-user-service-principal.png b/docs/pipelines/release/media/add-role-assignment-secret-user-service-principal.png new file mode 100644 index 00000000000..9b92e21b510 Binary files /dev/null and b/docs/pipelines/release/media/add-role-assignment-secret-user-service-principal.png differ diff --git a/docs/pipelines/release/media/add-service-principal-role-assignment.png b/docs/pipelines/release/media/add-service-principal-role-assignment.png new file mode 100644 index 00000000000..0b16cb3884c Binary files /dev/null and b/docs/pipelines/release/media/add-service-principal-role-assignment.png differ diff --git a/docs/pipelines/release/media/authorization-scope-organization-level.png b/docs/pipelines/release/media/authorization-scope-organization-level.png new file mode 100644 index 00000000000..e4541ae9665 Binary files /dev/null and b/docs/pipelines/release/media/authorization-scope-organization-level.png differ diff --git a/docs/pipelines/release/media/authorization-scope-project-level.png b/docs/pipelines/release/media/authorization-scope-project-level.png new file mode 100644 index 00000000000..05c68a30c7b Binary files /dev/null and b/docs/pipelines/release/media/authorization-scope-project-level.png differ diff --git a/docs/pipelines/release/media/automatic-service-connection-service-principal.png b/docs/pipelines/release/media/automatic-service-connection-service-principal.png new file mode 100644 index 00000000000..b842d6355cf Binary files /dev/null and b/docs/pipelines/release/media/automatic-service-connection-service-principal.png differ diff --git a/docs/pipelines/release/media/azure-add-members-to-role-assignment.png b/docs/pipelines/release/media/azure-add-members-to-role-assignment.png new file mode 100644 index 00000000000..d65338d4c87 Binary files /dev/null and b/docs/pipelines/release/media/azure-add-members-to-role-assignment.png differ diff --git a/docs/pipelines/release/media/azure-key-vault-classic-task-setup-server-2019.png b/docs/pipelines/release/media/azure-key-vault-classic-task-setup-server-2019.png new file mode 100644 index 00000000000..b0a6f80f3a7 Binary files /dev/null and b/docs/pipelines/release/media/azure-key-vault-classic-task-setup-server-2019.png differ diff --git a/docs/pipelines/release/media/azure-key-vault-classic-task-setup.png b/docs/pipelines/release/media/azure-key-vault-classic-task-setup.png new file mode 100644 index 00000000000..033efe82b91 Binary files /dev/null and b/docs/pipelines/release/media/azure-key-vault-classic-task-setup.png differ diff --git a/docs/pipelines/release/media/azure-rm-endpoint/endpoint-01.png b/docs/pipelines/release/media/azure-rm-endpoint/endpoint-01.png deleted file mode 100644 index 11249dcafd0..00000000000 Binary files a/docs/pipelines/release/media/azure-rm-endpoint/endpoint-01.png and /dev/null differ diff --git a/docs/pipelines/release/media/build-trigger-download-artifact.png b/docs/pipelines/release/media/build-trigger-download-artifact.png new file mode 100644 index 00000000000..150db0e0f0c Binary files /dev/null and b/docs/pipelines/release/media/build-trigger-download-artifact.png differ diff --git a/docs/pipelines/release/media/classic-build-properties.png b/docs/pipelines/release/media/classic-build-properties.png new file mode 100644 index 00000000000..ec640933ec4 Binary files /dev/null and b/docs/pipelines/release/media/classic-build-properties.png differ diff --git a/docs/pipelines/release/media/classic-pipeline-agent-job-configuration.png b/docs/pipelines/release/media/classic-pipeline-agent-job-configuration.png new file mode 100644 index 00000000000..21109bb7deb Binary files /dev/null and b/docs/pipelines/release/media/classic-pipeline-agent-job-configuration.png differ diff --git a/docs/pipelines/release/media/classic-pipeline-history-devops.png b/docs/pipelines/release/media/classic-pipeline-history-devops.png new file mode 100644 index 00000000000..7de6da274ae Binary files /dev/null and b/docs/pipelines/release/media/classic-pipeline-history-devops.png differ diff --git a/docs/pipelines/release/media/classic-pipeline-history.png b/docs/pipelines/release/media/classic-pipeline-history.png new file mode 100644 index 00000000000..e243bbae4c8 Binary files /dev/null and b/docs/pipelines/release/media/classic-pipeline-history.png differ diff --git a/docs/pipelines/release/media/classic-release-pipeline-add-artifact-souce.png b/docs/pipelines/release/media/classic-release-pipeline-add-artifact-souce.png new file mode 100644 index 00000000000..5b90c996cca Binary files /dev/null and b/docs/pipelines/release/media/classic-release-pipeline-add-artifact-souce.png differ diff --git a/docs/pipelines/release/media/classic-release-pipeline-set-primary-souce.png b/docs/pipelines/release/media/classic-release-pipeline-set-primary-souce.png new file mode 100644 index 00000000000..b6af0afabda Binary files /dev/null and b/docs/pipelines/release/media/classic-release-pipeline-set-primary-souce.png differ diff --git a/docs/pipelines/migrate/media/commit-save-run.png b/docs/pipelines/release/media/commit-save-run.png similarity index 100% rename from docs/pipelines/migrate/media/commit-save-run.png rename to docs/pipelines/release/media/commit-save-run.png diff --git a/docs/pipelines/release/media/copy-federated-credentials-new-ui.png b/docs/pipelines/release/media/copy-federated-credentials-new-ui.png new file mode 100644 index 00000000000..a8b97ef80fd Binary files /dev/null and b/docs/pipelines/release/media/copy-federated-credentials-new-ui.png differ diff --git a/docs/pipelines/release/media/copy-files-task-classic-pipeline.png b/docs/pipelines/release/media/copy-files-task-classic-pipeline.png new file mode 100644 index 00000000000..db61a172c06 Binary files /dev/null and b/docs/pipelines/release/media/copy-files-task-classic-pipeline.png differ diff --git a/docs/pipelines/release/media/create-key-vault-window.png b/docs/pipelines/release/media/create-key-vault-window.png index b7cef107739..d3780a00908 100644 Binary files a/docs/pipelines/release/media/create-key-vault-window.png and b/docs/pipelines/release/media/create-key-vault-window.png differ diff --git a/docs/pipelines/release/media/create-release-definition-manually.png b/docs/pipelines/release/media/create-release-definition-manually.png new file mode 100644 index 00000000000..8aa47980047 Binary files /dev/null and b/docs/pipelines/release/media/create-release-definition-manually.png differ diff --git a/docs/pipelines/release/media/create-secret-file.png b/docs/pipelines/release/media/create-secret-file.png new file mode 100644 index 00000000000..46d404fd12a Binary files /dev/null and b/docs/pipelines/release/media/create-secret-file.png differ diff --git a/docs/pipelines/release/media/create-task-group.png b/docs/pipelines/release/media/create-task-group.png new file mode 100644 index 00000000000..e895bb5468c Binary files /dev/null and b/docs/pipelines/release/media/create-task-group.png differ diff --git a/docs/pipelines/release/media/deploy-queue.png b/docs/pipelines/release/media/deploy-queue.png index 0902cb36239..ecbcacb4ddd 100644 Binary files a/docs/pipelines/release/media/deploy-queue.png and b/docs/pipelines/release/media/deploy-queue.png differ diff --git a/docs/pipelines/release/media/deploy-to-specific-stage.png b/docs/pipelines/release/media/deploy-to-specific-stage.png new file mode 100644 index 00000000000..6a734042e67 Binary files /dev/null and b/docs/pipelines/release/media/deploy-to-specific-stage.png differ diff --git a/docs/pipelines/release/media/deployment-group-add-targets.png b/docs/pipelines/release/media/deployment-group-add-targets.png index 1241b66e9ec..1224b1d2ef2 100644 Binary files a/docs/pipelines/release/media/deployment-group-add-targets.png and b/docs/pipelines/release/media/deployment-group-add-targets.png differ diff --git a/docs/pipelines/release/media/enable-continuous-deployment-trigger.png b/docs/pipelines/release/media/enable-continuous-deployment-trigger.png new file mode 100644 index 00000000000..b5070791510 Binary files /dev/null and b/docs/pipelines/release/media/enable-continuous-deployment-trigger.png differ diff --git a/docs/pipelines/migrate/media/export-yaml.png b/docs/pipelines/release/media/export-yaml.png similarity index 100% rename from docs/pipelines/migrate/media/export-yaml.png rename to docs/pipelines/release/media/export-yaml.png diff --git a/docs/pipelines/release/media/generated-script.png b/docs/pipelines/release/media/generated-script.png new file mode 100644 index 00000000000..06ef6d425be Binary files /dev/null and b/docs/pipelines/release/media/generated-script.png differ diff --git a/docs/pipelines/release/media/iis-deployment-group.png b/docs/pipelines/release/media/iis-deployment-group.png new file mode 100644 index 00000000000..a78bb77a548 Binary files /dev/null and b/docs/pipelines/release/media/iis-deployment-group.png differ diff --git a/docs/pipelines/release/media/iis-web-template.png b/docs/pipelines/release/media/iis-web-template.png new file mode 100644 index 00000000000..9c4c65094d0 Binary files /dev/null and b/docs/pipelines/release/media/iis-web-template.png differ diff --git a/docs/pipelines/release/media/integrate-jenkins-vsts-cicd/schematic1.png b/docs/pipelines/release/media/integrate-jenkins-vsts-cicd/schematic1.png deleted file mode 100644 index 277861fdc7a..00000000000 Binary files a/docs/pipelines/release/media/integrate-jenkins-vsts-cicd/schematic1.png and /dev/null differ diff --git a/docs/pipelines/release/media/key-vault-approved-private-endpoint-connection.png b/docs/pipelines/release/media/key-vault-approved-private-endpoint-connection.png new file mode 100644 index 00000000000..728db016f35 Binary files /dev/null and b/docs/pipelines/release/media/key-vault-approved-private-endpoint-connection.png differ diff --git a/docs/pipelines/release/media/key-vault-new-private-endpoint.png b/docs/pipelines/release/media/key-vault-new-private-endpoint.png new file mode 100644 index 00000000000..c91a69e8154 Binary files /dev/null and b/docs/pipelines/release/media/key-vault-new-private-endpoint.png differ diff --git a/docs/pipelines/release/media/key-vault-private-endpoint-resource.png b/docs/pipelines/release/media/key-vault-private-endpoint-resource.png new file mode 100644 index 00000000000..16865cf13eb Binary files /dev/null and b/docs/pipelines/release/media/key-vault-private-endpoint-resource.png differ diff --git a/docs/pipelines/release/media/key-vault-private-endpoint.png b/docs/pipelines/release/media/key-vault-private-endpoint.png new file mode 100644 index 00000000000..647f3c782fe Binary files /dev/null and b/docs/pipelines/release/media/key-vault-private-endpoint.png differ diff --git a/docs/pipelines/release/media/list-task-group.png b/docs/pipelines/release/media/list-task-group.png new file mode 100644 index 00000000000..f5d64fdc7f3 Binary files /dev/null and b/docs/pipelines/release/media/list-task-group.png differ diff --git a/docs/pipelines/library/media/manage-task-group.png b/docs/pipelines/release/media/manage-task-group.png similarity index 100% rename from docs/pipelines/library/media/manage-task-group.png rename to docs/pipelines/release/media/manage-task-group.png diff --git a/docs/pipelines/release/media/managed-identity-service-connection.png b/docs/pipelines/release/media/managed-identity-service-connection.png new file mode 100644 index 00000000000..2b83d817607 Binary files /dev/null and b/docs/pipelines/release/media/managed-identity-service-connection.png differ diff --git a/docs/pipelines/release/media/manual-service-principal-service-connection.png b/docs/pipelines/release/media/manual-service-principal-service-connection.png new file mode 100644 index 00000000000..5b72204828b Binary files /dev/null and b/docs/pipelines/release/media/manual-service-principal-service-connection.png differ diff --git a/docs/pipelines/release/media/new-service-principal-arm-service-connection-server-2019.png b/docs/pipelines/release/media/new-service-principal-arm-service-connection-server-2019.png new file mode 100644 index 00000000000..a7e793af5f6 Binary files /dev/null and b/docs/pipelines/release/media/new-service-principal-arm-service-connection-server-2019.png differ diff --git a/docs/pipelines/release/media/new-variable-group-get-list-error.png b/docs/pipelines/release/media/new-variable-group-get-list-error.png new file mode 100644 index 00000000000..93f6b284b94 Binary files /dev/null and b/docs/pipelines/release/media/new-variable-group-get-list-error.png differ diff --git a/docs/pipelines/release/media/organization-geographical-location.png b/docs/pipelines/release/media/organization-geographical-location.png new file mode 100644 index 00000000000..934a66485d1 Binary files /dev/null and b/docs/pipelines/release/media/organization-geographical-location.png differ diff --git a/docs/pipelines/release/media/pipeline-history-compare-difference.png b/docs/pipelines/release/media/pipeline-history-compare-difference.png new file mode 100644 index 00000000000..45dd8c9cb7d Binary files /dev/null and b/docs/pipelines/release/media/pipeline-history-compare-difference.png differ diff --git a/docs/pipelines/migrate/media/pipelines-new-pipeline.png b/docs/pipelines/release/media/pipelines-new-pipeline.png similarity index 100% rename from docs/pipelines/migrate/media/pipelines-new-pipeline.png rename to docs/pipelines/release/media/pipelines-new-pipeline.png diff --git a/docs/pipelines/release/media/predeployment-conditions-artifact-filters.png b/docs/pipelines/release/media/predeployment-conditions-artifact-filters.png new file mode 100644 index 00000000000..0d1d119104b Binary files /dev/null and b/docs/pipelines/release/media/predeployment-conditions-artifact-filters.png differ diff --git a/docs/pipelines/release/media/predeployment-conditions-prod.png b/docs/pipelines/release/media/predeployment-conditions-prod.png new file mode 100644 index 00000000000..7f5ef03a86b Binary files /dev/null and b/docs/pipelines/release/media/predeployment-conditions-prod.png differ diff --git a/docs/pipelines/release/media/publish-artifacts-classic-pipeline.png b/docs/pipelines/release/media/publish-artifacts-classic-pipeline.png new file mode 100644 index 00000000000..3a554847da6 Binary files /dev/null and b/docs/pipelines/release/media/publish-artifacts-classic-pipeline.png differ diff --git a/docs/pipelines/library/media/publish-preview-task-group.png b/docs/pipelines/release/media/publish-preview-task-group.png similarity index 100% rename from docs/pipelines/library/media/publish-preview-task-group.png rename to docs/pipelines/release/media/publish-preview-task-group.png diff --git a/docs/pipelines/library/media/publish-version-task-group.png b/docs/pipelines/release/media/publish-version-task-group.png similarity index 100% rename from docs/pipelines/library/media/publish-version-task-group.png rename to docs/pipelines/release/media/publish-version-task-group.png diff --git a/docs/pipelines/release/media/release-triggers-to-stages.png b/docs/pipelines/release/media/release-triggers-to-stages.png new file mode 100644 index 00000000000..52a371965dd Binary files /dev/null and b/docs/pipelines/release/media/release-triggers-to-stages.png differ diff --git a/docs/pipelines/library/media/save-draft-task-group.png b/docs/pipelines/release/media/save-draft-task-group.png similarity index 100% rename from docs/pipelines/library/media/save-draft-task-group.png rename to docs/pipelines/release/media/save-draft-task-group.png diff --git a/docs/pipelines/migrate/media/save-run-new-yaml-pipeline.png b/docs/pipelines/release/media/save-run-new-yaml-pipeline.png similarity index 100% rename from docs/pipelines/migrate/media/save-run-new-yaml-pipeline.png rename to docs/pipelines/release/media/save-run-new-yaml-pipeline.png diff --git a/docs/pipelines/migrate/media/select-pipeline-template.png b/docs/pipelines/release/media/select-pipeline-template.png similarity index 100% rename from docs/pipelines/migrate/media/select-pipeline-template.png rename to docs/pipelines/release/media/select-pipeline-template.png diff --git a/docs/pipelines/migrate/media/select-repository.png b/docs/pipelines/release/media/select-repository.png similarity index 100% rename from docs/pipelines/migrate/media/select-repository.png rename to docs/pipelines/release/media/select-repository.png diff --git a/docs/pipelines/release/media/service-principal-federated-credential-in-azure.png b/docs/pipelines/release/media/service-principal-federated-credential-in-azure.png new file mode 100644 index 00000000000..b4da505df8f Binary files /dev/null and b/docs/pipelines/release/media/service-principal-federated-credential-in-azure.png differ diff --git a/docs/pipelines/release/media/service-principal-federated-credential-service-connection.png b/docs/pipelines/release/media/service-principal-federated-credential-service-connection.png new file mode 100644 index 00000000000..48f7ebc0bd1 Binary files /dev/null and b/docs/pipelines/release/media/service-principal-federated-credential-service-connection.png differ diff --git a/docs/pipelines/release/media/skip-automatic-download-devops-services.png b/docs/pipelines/release/media/skip-automatic-download-devops-services.png new file mode 100644 index 00000000000..2fa2d4209fd Binary files /dev/null and b/docs/pipelines/release/media/skip-automatic-download-devops-services.png differ diff --git a/docs/pipelines/release/media/skip-automatic-download-server.png b/docs/pipelines/release/media/skip-automatic-download-server.png new file mode 100644 index 00000000000..96d84c51689 Binary files /dev/null and b/docs/pipelines/release/media/skip-automatic-download-server.png differ diff --git a/docs/pipelines/migrate/media/source-code-location.png b/docs/pipelines/release/media/source-code-location.png similarity index 100% rename from docs/pipelines/migrate/media/source-code-location.png rename to docs/pipelines/release/media/source-code-location.png diff --git a/docs/pipelines/release/media/supported-account-types.png b/docs/pipelines/release/media/supported-account-types.png index 70676d62b10..8b3d1403e8b 100644 Binary files a/docs/pipelines/release/media/supported-account-types.png and b/docs/pipelines/release/media/supported-account-types.png differ diff --git a/docs/pipelines/migrate/media/task-assistant-yaml.png b/docs/pipelines/release/media/task-assistant-yaml.png similarity index 100% rename from docs/pipelines/migrate/media/task-assistant-yaml.png rename to docs/pipelines/release/media/task-assistant-yaml.png diff --git a/docs/pipelines/release/media/trigger-01a.png b/docs/pipelines/release/media/trigger-01a.png index 97bcb5cd45a..4a38f6b596e 100644 Binary files a/docs/pipelines/release/media/trigger-01a.png and b/docs/pipelines/release/media/trigger-01a.png differ diff --git a/docs/pipelines/release/media/unlink-task-group.png b/docs/pipelines/release/media/unlink-task-group.png new file mode 100644 index 00000000000..e9f26c6a396 Binary files /dev/null and b/docs/pipelines/release/media/unlink-task-group.png differ diff --git a/docs/pipelines/library/media/use-preview-task-group.png b/docs/pipelines/release/media/use-preview-task-group.png similarity index 100% rename from docs/pipelines/library/media/use-preview-task-group.png rename to docs/pipelines/release/media/use-preview-task-group.png diff --git a/docs/pipelines/library/media/use-version-task-group.png b/docs/pipelines/release/media/use-version-task-group.png similarity index 100% rename from docs/pipelines/library/media/use-version-task-group.png rename to docs/pipelines/release/media/use-version-task-group.png diff --git a/docs/pipelines/release/media/what-is-release-management/email-release-summary.png b/docs/pipelines/release/media/what-is-release-management/email-release-summary.png index 80904f6acb7..42f7b047268 100644 Binary files a/docs/pipelines/release/media/what-is-release-management/email-release-summary.png and b/docs/pipelines/release/media/what-is-release-management/email-release-summary.png differ diff --git a/docs/pipelines/release/media/workload-identity-manual-app-workload.png b/docs/pipelines/release/media/workload-identity-manual-app-workload.png new file mode 100644 index 00000000000..936dd27aeaa Binary files /dev/null and b/docs/pipelines/release/media/workload-identity-manual-app-workload.png differ diff --git a/docs/pipelines/release/media/workload-identity-service-connection-manual.png b/docs/pipelines/release/media/workload-identity-service-connection-manual.png new file mode 100644 index 00000000000..942617e8720 Binary files /dev/null and b/docs/pipelines/release/media/workload-identity-service-connection-manual.png differ diff --git a/docs/pipelines/release/options.md b/docs/pipelines/release/options.md new file mode 100644 index 00000000000..54f88ac044c --- /dev/null +++ b/docs/pipelines/release/options.md @@ -0,0 +1,95 @@ +--- +title: Classic pipelines configuration +description: Learn about the options available to configure your agent and the different build properties for your Classic pipeline. +ms.topic: reference +ms.assetid: 7C469647-117D-4867-B094-8BC811C0003E +ms.date: 10/07/2024 +monikerRange: '<= azure-devops' +--- + +# Classic pipelines configuration + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +Classic pipelines make it easier for developers to design their pipeline workflows using the user interface to add tasks and conditions tailored to their scenario. This article explains the available options to configure your agent job and explores the different build properties for your Classic pipeline. + +## Agent job + +1. Sign in to your Azure DevOps organization, and then go to your project. + +1. Select **Pipelines**, select your pipeline definition, and then select **Edit**. + +1. Select **Tasks**, and then select **Agent job**. + +#### Default agent pool: + +When you queue a build, it runs on an agent from your selected pool. You can choose a Microsoft-hosted pool or a self-hosted pool that you manage. Select the [pool](../agents/pools-queues.md) associated with the agents you want to run this pipeline on. + +#### Parallelism + +Defines how the job's tasks are executed in parallel: + +- None: tasks are executed on a single agent. + +- Multi-configuration: tasks are executed on multiple configurations, as specified in the multipliers. Configurations run in parallel, each using a single agent. The total number of agents depends on the number of configurations and can be limited by setting a maximum number of agents. + +- Multi-agent: tasks are executed on multiple agents using the specified number of agents. + +#### Timeout + +Specifies the maximum time, in minutes, that a deployment is allowed to run on an agent before being canceled by the server. The duration is measured after preapproval is completed and before post-approval is requested. A value of zero will cause the timeout of the parent pipeline to be used. + +#### Job cancel timeout + +Specifies the maximum wait time for a deployment job to respond to a cancellation request before being terminated by the server. A value of zero will cause the timeout of the parent pipeline to be used. + +#### Allow scripts to access the OAuth token + +Enables scripts and other processes to access the OAuth token through the `System.AccessToken` variable. See the [example script for accessing the REST API](../scripts/powershell.md) for more details. + +:::image type="content" source="media/classic-pipeline-agent-job-configuration.png" alt-text="A screenshot displaying how to configure the agent job in a Classic pipeline." lightbox="media/classic-pipeline-agent-job-configuration.png"::: + +## Build properties + +1. Sign in to your Azure DevOps organization, and then go to your project. + +1. Select **Pipelines**, select your pipeline definition, select **Edit**, and then select the **Options** tab. + +#### Build number format + +Define the format to give meaningful names to completed builds. Leave it blank to give builds a unique integer as name. See [Configure build run numbers](../process/run-number.md) for more details. + +#### Create work items on failure + +When enabled, if the pipeline fails, a work item is automatically created to track the issue. You can specify the type of work item and choose whether to assign it to the requestor. + +- Additional Fields: set additional fields when creating the work item. + +For example, "System.Title" = "Build $(build.buildNumber) failed" formats the Work Item title, and "System.Reason" = "Build failure" sets the reason. See [Work item field index](../../boards/work-items/guidance/work-item-field.md) for other available fields. + +#### Build job + +Define build job authorization and timeout settings. + +- Build job authorization scope: specify the authorization scope for a build job. Select: + + - Project Collection: if the pipeline needs access to multiple projects. + - Current Project: if you want to restrict this pipeline to only access the resources in the current project. + +See [Understand job access tokens](../process/access-tokens.md) for more details. + +- Build job timeout in minutes: specifies the maximum time a build job is allowed to execute on an agent before being canceled by the server. An empty or zero value indicates no timeout limit. + +- Build job cancel timeout in minutes: specifies the maximum wait time for a build job to respond to a cancellation request before being terminated by the server. + +#### Demands + +Specify the capabilities that the agent must have to run this pipeline. See [Agent capabilities and demands](../agents/agents.md#capabilities) for more details. + +:::image type="content" source="media/classic-build-properties.png" alt-text="A screenshot displaying how to configure the different build properties in a Classic pipeline." lightbox="media/classic-build-properties.png"::: + +## Related content + +- [Build multiple branches ](../build/ci-build-git.md) +- [View Classic pipeline history](history.md) +- [Publish and download pipeline artifacts](../artifacts/pipeline-artifacts.md) \ No newline at end of file diff --git a/docs/pipelines/release/parameters.md b/docs/pipelines/release/parameters.md new file mode 100644 index 00000000000..b4e7177bcb5 --- /dev/null +++ b/docs/pipelines/release/parameters.md @@ -0,0 +1,69 @@ +--- +title: Classic process parameters +description: Learn how to link essential task settings as process parameters across your pipeline. +ms.topic: conceptual +ms.assetid: 27AD0094-FDF1-4B36-A82E-B845980984AF +ms.date: 07/25/2024 +monikerRange: '<= azure-devops' +--- + +# Classic process parameters + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +> [!NOTE] +> Process parameters are only available in Classic pipelines. For parameters in YAML pipelines, see [runtime parameters](../process/runtime-parameters.md). + +Process parameters are used in Classic pipelines and differ from variables in the types of input they support. Variables only accept string inputs, whereas process parameters support additional data types such as checkboxes and drop-down lists. + +Process parameters are a list of essential settings that can be shared across all tasks in your pipeline definition. Having these parameters in one location allows you to quickly edit these arguments without having to click through each task individually. [Templates](../release/env-templates.md) come with a set of predefined process parameters. + +> [!NOTE] +> Process parameters are not available in release pipelines. + +## Configure process parameters + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select your classic pipeline, and then select **Edit**. + +1. Select **Pipeline** under **Tasks**, scroll down to **Parameters**, and configure them as needed. + + :::image type="content" source="../artifacts/media/classic-pipeline-process-parameters.png" alt-text="A screenshot displaying the process parameters in a classic pipeline."::: + +## Add new process parameters + +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select your classic pipeline, and then select **Edit**. + +1. Select the task you want to add to the process parameters, and then select **Link settings**. Configure your settings, and then select **Link**. + + :::image type="content" source="../artifacts/media/classic-pipeline-link-process-parameters.png" alt-text="A screenshot showing how to link new task settings to process parameters in a classic pipeline."::: + +1. Once linked, you can find your linked task settings under your **Pipeline** > **Parameters**. + + :::image type="content" source="../artifacts/media/classic-pipeline-new-process-parameters.png" alt-text="A screenshot displaying the newly added process parameter in a classic pipeline."::: + +## Unlink process parameters + +- **Unlink all process parameters**: + 1. Navigate to **Tasks** > **Pipeline** > **Parameters** in your pipeline definition. + 1. Select **Unlink all**. + + :::image type="content" source="../artifacts/media/classic-pipeline-process-parameters-unlink-all.png" alt-text="A screenshot showing how to unlink all parameters in a classic pipeline."::: + +- **Unlink a single parameter**: + 1. In your pipeline definition, select the task you want to unlink. + 1. Select **Link settings** from the right panel, and then select **Unlink**. + + :::image type="content" source="../artifacts/media/classic-pipeline-process-parameters-unlink.png" alt-text="A screenshot showing how to unlink a single parameter in a classic pipeline."::: + +## Related articles + +- [Build multiple branches](../build/ci-build-git.md) +- [Pipeline completion triggers (Classic)](../process/pipeline-triggers-classic.md) +- [Pipeline caching](../release/caching.md) + + + diff --git a/docs/pipelines/release/pipeline-triggers-classic.md b/docs/pipelines/release/pipeline-triggers-classic.md new file mode 100644 index 00000000000..3aa35ac3820 --- /dev/null +++ b/docs/pipelines/release/pipeline-triggers-classic.md @@ -0,0 +1,65 @@ +--- +title: Configure build completion triggers (classic) +description: Configure build completion triggers (classic) +ms.topic: conceptual +ms.author: sdanie +author: steved0x +ms.date: 01/25/2023 +monikerRange: "<=azure-devops" +--- + +# Trigger one pipeline after another (classic) + +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] + +> [!div class="op_single_selector"] +> - [YAML pipelines](../process/pipeline-triggers.md) +> - [Classic pipelines](pipeline-triggers-classic.md) + +Large products have several components that are dependent on each other. +These components are often independently built. When an upstream component (a library, for example) changes, the downstream dependencies have to be rebuilt and revalidated. + +In situations like these, add a pipeline trigger to run your pipeline upon the successful completion of the **triggering pipeline**. + +## Add a build completion trigger + +In the classic editor, pipeline triggers are called **build completion triggers**. You can select any other build in the same project to be the triggering pipeline. + +After you add a **build completion** trigger, select the **triggering build**. If the triggering build is sourced from a Git repo, you can also specify **branch filters**. If you want to use wildcard characters, then type the branch specification (for example, `features/modules/*`) and then press Enter. + +> [!NOTE] +> Keep in mind that in some cases, a single [multi-job build](../process/phases.md) could meet your needs. +> However, a build completion trigger is useful if your requirements include different configuration settings, options, or a different team to own the dependent pipeline. + +## Download artifacts from the triggering build + +In many cases, you'll want to download artifacts from the triggering build. To do this: + +1. Edit your build pipeline. + +1. Add the **Download Build Artifacts** task to one of your jobs under **Tasks**. + +1. For **Download artifacts produced by**, select **Specific build**. + +1. Select the team **Project** that contains the triggering build pipeline. + +1. Select the triggering **Build pipeline**. + +1. Select **When appropriate, download artifacts from the triggering build**. + +1. Even though you specified that you want to download artifacts from the triggering build, you must still select a value for **Build**. The option you choose here determines which build will be the source of the artifacts whenever your triggered build is run because of any other reason than `BuildCompletion` (e.g. `Manual`, `IndividualCI`, `Schedule`, and so on). + +1. Specify the **Artifact name** and make sure it matches the name of the artifact published by the triggering build. + +1. Specify the **Destination directory** to which you want to download the artifacts. For example: `$(Build.BinariesDirectory)` + + :::image type="content" source="media/build-trigger-download-artifact.png" alt-text="A screenshot displaying how to download artifacts from a triggering build in a Classic pipeline."::: + +- **Download artifacts produced by**: *Specific build*. +- **Project**: select your project from the dropdown menu. +- **Build pipeline**: select your pipeline from the dropdown menu. +- Check **When appropriate, download artifacts from the triggering build**. +- **Build version to download**: select a build version. +- **Download type**: *Specific artifact*. +- **Artifact name**: select your artifact from the dropdown menu. +- **Destination directory**: path on the agent machine where the artifacts will be downloaded. \ No newline at end of file diff --git a/docs/pipelines/release/releases.md b/docs/pipelines/release/releases.md index c599fda329c..d807849c94e 100644 --- a/docs/pipelines/release/releases.md +++ b/docs/pipelines/release/releases.md @@ -1,72 +1,49 @@ --- -title: Understand releases and deployments in Azure Pipelines -ms.custom: seodec18 -description: DevOps CI/CD - Understand releases pipelines +title: Create Classic releases +description: Learn how to create Classic release definition in Azure pipelines. ms.assetid: 2FF35C3B-FBF9-407F-8467-2D336973E63C -ms.topic: conceptual +ms.topic: tutorial ms.author: ronai author: RoopeshNair -ms.date: 03/01/2021 +ms.date: 10/31/2024 monikerRange: '<= azure-devops' --- -# Releases in Azure Pipelines +# Create Classic releases [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end +Azure Pipelines offers developers a structured framework for deploying applications across multiple environments efficiently and securely using classic release pipelines. In this article you learn how to create release definitions in Azure Pipelines. -::: moniker range="azure-devops" +## Prerequisites -> [!NOTE] -> This topic covers classic release pipelines. If you want to create your pipelines using YAML, see [Customize your pipeline](../customize-pipeline.md). +- An Azure DevOps organization. [Create one for free](../../organizations/accounts/create-organization.md). -::: moniker-end +- An Azure DevOps project. Create a new [project](../../organizations/projects/create-project.md#create-a-project) if you don't have one already. -A **release** is a construct that holds a versioned set of artifacts specified in a CI/CD pipeline. It includes a snapshot of all the information required to carry out all the tasks and actions in the release pipeline, such as stages, tasks, policies such as triggers and approvers, and deployment options. There can be multiple releases from one release pipeline, and information about each one is stored and displayed in Azure Pipelines for the specified [retention period](../policies/retention.md#release). +## Create a release definition -A **deployment** is the action of running the tasks for one stage, which can include running automated tests, deploying build artifacts, and whatever other actions are specified for that stage. -Initiating a release starts each deployment based on the settings and policies defined in the original release pipeline. There can be multiple deployments of each release even for one stage. When a deployment of a release fails for a stage, you can redeploy the same release to that stage. To redeploy a release, simply navigate to the release you want to deploy and select deploy. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -The following diagram shows the relationship between release, release pipelines, and deployments. +1. Select **Pipelines** > **Releases**. -:::image type="content" source="media/release-deploy.png" alt-text="Relationship between releases, release pipelines, and deployments"::: +1. If this your first release pipeline, select **New pipeline**, otherwise select **New** > **New release pipeline**. -## Create release pipelines +1. Select a template, or start with an **Empty job**. -Releases can be created in several ways: +1. Under **Artifacts**, select **Add an artifact**, select your **Source type**, and then fill out the required fields. Select **Add** when you're done. -1. By using a [deployment trigger](triggers.md) to create a release every time a new build artifact is available. +1. Under **Stages**, select the job/task link, and add the tasks you need for your scenario to the **Agent job**. - :::image type="content" source="media/trigger-01.png" alt-text="Continuous deployment triggers"::: +1. Select **Save** when you're done, add a comment (optional), and then select **Ok**. -1. By using the **Create release** button from within your **Pipelines** > **Releases** to manually create a release pipeline. - - :::image type="content" source="media/create-release-ui.png" alt-text="Create a release pipeline from the UI"::: - -1. By using the [REST API](/rest/api/azure/devops/release) to create a release definition. + :::image type="content" source="media/create-release-definition-manually.png" alt-text="A screenshot displaying how to manually create a release definition."::: > [!NOTE] -> If your organization is using a firewall or a proxy server, make sure you allow [Azure Artifacts Domain URLs and IP addresses](../../organizations/security/allow-list-ip-url.md#azure-artifacts). - -## Q&A - -Q: Why my deployment did not get triggered? - -A: Creating a release pipeline does not necessarily mean that it will automatically/immediately start a deployment. Below are few reasons why this might happen: - -- Defined [deployment triggers](triggers.md) forcing the deployment to pause.This can happen with scheduled triggers or when a delay is imposed until deployment to another stage is complete. - -- Defined [queuing policies](../process/stages.md#queuing-policies) dictating the order of execution and when releases are queued for deployment. - -- [Pre-deployment approvals or gates](approvals/index.md) for a specific stage preventing deployment until all the defined conditions are met. +> Release definitions can also be created using the [REST API](/rest/api/azure/devops/release). -## Related articles +## Related content -- [Release deployment control using approvals](approvals/approvals.md). -- [Release deployment control using gates](approvals/gates.md). -- [Release triggers](triggers.md). -- [Release artifacts and artifact sources](artifacts.md). -- [Add stages, dependencies, & conditions](../process/stages.md). +- [Classic release triggers](triggers.md). +- [Artifact sources](artifacts.md). +- [Deploy pull request Artifacts](deploy-pull-request-builds.md). diff --git a/docs/pipelines/release/task-groups.md b/docs/pipelines/release/task-groups.md new file mode 100644 index 00000000000..67fdb6f2af8 --- /dev/null +++ b/docs/pipelines/release/task-groups.md @@ -0,0 +1,154 @@ +--- +title: Task groups in Classic pipelines +description: Understand, create, and manage task groups in Classic pipelines for Azure Pipelines. +ms.assetid: 0FEAE814-2AF8-441B-A099-E77B1008D2F0 +ms.topic: how-to +ms.author: ronai +author: RoopeshNair +ms.date: 08/01/2024 +monikerRange: '<= azure-devops' +--- + +# Task groups in Classic pipelines + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +In Classic pipelines, a task group encapsulates a sequence of tasks that are already defined in a pipeline into a single reusable task. The new task group is automatically added to the task catalog, and can be added to pipelines in the project just like other tasks. Task groups are stored at the project level, and aren't accessible outside the project scope. + +Task groups are a way to standardize and centrally manage deployment steps for all your applications. When you make a change centrally to a task group, the change is automatically reflected in all the pipeline definitions that use the task group. You don't need to change each definition individually. + +> [!NOTE] +> Task groups are not supported in YAML pipelines. Instead, you can use [Templates](../process/templates.md). + +## Prerequisites + +- An Azure DevOps organization and project where you have permission to create pipelines. +- A Classic pipeline created in the project. + +## Extract task parameters as variables + +When you create a task group, you can choose to extract the parameters from the encapsulated tasks as configuration variables, and abstract the rest of the task information. Variables used in the tasks are automatically extracted and converted into parameters for the task group, and values of these configuration variables are converted into default values for the task group. + +You can also change the default values for the parameters when you save the new task group. When you queue a pipeline run or release, the encapsulated tasks are extracted and the values you entered for the task group parameters are applied to the tasks. + +Before you create a task group, make sure to define any parameters that you want to be able to configure in pipeline runs as variables, such as **$(MyVariable)**. Any task parameters that have no values or have specified values instead of variables become fixed parameters and aren't exposed to the task group as configurable parameters. + +You can also configure task conditions in a task group, such as **Run this task only when a previous task has failed** for a **PowerShell Script** task, and these conditions are persisted with the task group. + +> [!NOTE] +> Task groups are supported in Classic pipelines and Classic release pipelines. + +## Create a task group + +When you save a new task group, you provide a name and description and select a category for the task group in the task catalog. + +1. Open the pipeline where you want to create a new task group. + +1. To ensure that none of the tasks you intend to include contain any linked parameters, select **Unlink all** in the pipeline settings panel, and then select **Confirm**. + + :::image type="content" source="media/unlink-task-group.png" alt-text="Screenshot that shows unlinking parameters for all tasks."::: + +1. Select a sequence of pipeline tasks that you want to turn into a task group, right-click to open the context menu, and then choose **Create task group**. + + :::image type="content" source="media/create-task-group.png" alt-text="Screenshot that shows creating a task group from a release pipeline list of tasks."::: + +1. Specify a name and description for the new task group, and the category in the **Add tasks** pane you want to add it to. + +1. Select **Create**. The new task group is created and replaces the selected tasks in your pipeline. + +1. All the `'$(vars)'` from the underlying tasks, except [predefined variables](../build/variables.md), surface as the mandatory parameters for the newly created task group, and you can edit the values if necessary. + + For example, if you had a task input `foobar` that you didn't intend to parameterize, the task input is converted into the task group parameter `'foobar'`. You can provide the default value for the task group parameter `'foobar'` as `$(foobar)` to ensure that at runtime, the expanded task gets the input you intend. + +1. Save your updated pipeline. + +## Manage task groups + +All the task groups in the current project are listed under **Pipelines** on the **Task groups** page. + +:::image type="content" source="media/list-task-group.png" alt-text="Screenshot that shows listing task groups."::: + +At the top of the **Task groups** page, you can select **Import** to import previously saved task group definitions. You can use this feature to transfer task groups between projects and enterprises, or replicate and save copies of your task groups. + +You can also select **Security** at the top of the page to define who can use, edit, delete, or set permissions for all task groups in the project. + +To manage a task group, right-click or select the **More actions** icon for the group, and select one of the following options from the context menu: + +- Select **Delete** to delete the task group, and then select **Delete** again on the confirmation screen. +- Select **Export** to save a copy of the task group as a JSON pipeline. +- Select **Security** to define who can use, edit, delete, or set permissions for the task group. + +To open the task group details page for editing, select the task group name on the **Task groups** page. + +:::image type="content" source="media/manage-task-group.png" alt-text="Screenshot that shows managing a task group."::: + +- On the **Tasks** tab, you can edit the tasks that make up the task group. For each encapsulated task you can change the parameter values for the nonvariable parameters, edit the existing parameter variables, or convert parameter values to and from variables. When you save the changes, all definitions that use the task group pick up the changes. + + All the variable parameters of the task group appear as mandatory parameters in the pipeline definition. You can also set the default values for the task group parameters. + +- On the **History** tab, you can see the history of changes to the group. + +- On the **References** tab, you can see lists of all the pipelines and other task groups that reference this task group. This listing helps you ensure that changes don't have unexpected effects on other processes. + +## Create preview and updated versions of task groups + +All built-in Azure Pipelines tasks are [versioned](../process/tasks.md#task-versions). Versioning allows pipelines to continue using the existing version of a task while new versions are developed, tested, and released. You can version your custom task groups the same way to provide the same advantages. + +1. To version a task group, after you finish editing it, select **Save as draft** instead of **Save**. + + :::image type="content" source="media/save-draft-task-group.png" alt-text="Screenshot that shows saving a draft update to a task group."::: + +1. The string **-test** is appended to the task group version number. When you're happy with the changes, choose **Publish draft**. On the **Publish draft task group** screen, select **Publish as preview** if you want to publish the new version as a preview, and then select **Publish**. + + :::image type="content" source="media/publish-preview-task-group.png" alt-text="Screenshot that shows publishing a draft version of a task group."::: + +1. You can now use the updated task group in your release processes. You can either change the version number in pipelines that already use the task group, or choose the versioned task group from the **Add tasks** pane. As with built-in tasks, the default when you add a task group is the highest non-preview version. + + :::image type="content" source="media/use-preview-task-group.png" alt-text="Screenshot that shows using a draft version of a task group."::: + +1. After you finish testing the updated task group, choose **Publish preview**, and then select **Publish**. The **Preview** string is removed from the version number, and the version now appears in definitions as a production-ready version. + + :::image type="content" source="media/publish-version-task-group.png" alt-text="Screenshot that shows publishing a preview version of a task group."::: + +1. You can now select the new production-ready version in a pipeline that already contains the task group. When you add the task group from the **Add tasks** panel, it automatically selects the new production-ready version. You can edit the pipeline to use an earlier version. + + :::image type="content" source="media/use-version-task-group.png" alt-text="Screenshot that shows using an updated version of a task group."::: + +## Work with task group versions + +Task group updates can be minor or major version updates. + +### Create a minor version update + +To create a minor version update, you directly save the task group after editing it instead of saving it as a draft. + +The version number doesn't change, and the latest changes show up in the pipeline definition automatically. For example, if your task group is version `1`, you can have any number of minor version updates such as `1.1`, `1.2`, and `1.3`. In your pipeline, the task group version shows as `1.*`. + +Use minor version updates for small changes in the task group, when you expect pipelines to use the new change without changing the version number in the pipeline definition. + +### Create a major version update + +To create a new major version, you save the task group updates as draft and create a preview, validate the changes, and then publish the preview. + +This process bumps up the task group to a new version. If you had a task group with version `1.*`, new versions are published as `2.*`, `3.*`, `4.*`, and so on. + +A notification about new version availability appears in all the pipeline definitions that use the task group. Users must explicitly update to the new task group version if they want to use it in their pipelines. + +When you make substantial changes that might break existing pipelines, you can test and roll out the changes as a new major version. Users can choose to upgrade to new version or stay on the current version. This functionality is the same as a regular task version update. + +### Test a minor version update + +If your task group update isn't a breaking change, but you want to test first and then force all pipelines to use the latest changes, follow these steps: + +1. Save the task group changes as a draft. A new draft task group named **\ (Draft)** is created with your changes. +1. Add this draft task group directly to your test pipeline. +1. Validate the changes in your test pipeline. Once you're confident in the changes, go back to your main task group, do the same changes, and save them directly. The changes are saved as a minor version update. +1. The new changes now show up in all the pipelines that use this task group. Now you can delete your draft task group. + +[!INCLUDE [rm-help-support-shared](../includes/rm-help-support-shared.md)] + +## Related content + +* [Tasks](../process/tasks.md) +* [Task jobs](../process/phases.md) + diff --git a/docs/pipelines/release/triggers.md b/docs/pipelines/release/triggers.md index ee9eb476d04..fc768fad295 100644 --- a/docs/pipelines/release/triggers.md +++ b/docs/pipelines/release/triggers.md @@ -1,109 +1,103 @@ --- -title: Classic release triggers for stages, branches, and pipelines -description: DevOps CI CD - Understand triggers in Azure Pipelines +title: Classic release triggers +description: Learn the different types of release triggers and how to use them in your release pipelines. ms.assetid: FDB5DA41-1ADA-485E-86BD-8BF147788568 ms.topic: tutorial ms.author: ronai author: RoopeshNair -ms.custom: seodec18, contperf-fy21q1 -ms.date: 10/20/2021 +ms.date: 10/28/2024 monikerRange: '<= azure-devops' --- -# Release triggers +# Classic release triggers [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end +Release triggers are an automation tool that can be used in your deployment workflow to initiate actions when specific conditions are met. after certain conditions are met. Classic release pipelines support several types of triggers, which we'll cover in this article: -::: moniker range="azure-devops" -> [!NOTE] -> This topic covers classic release pipelines. To understand triggers in YAML pipelines, see [pipeline triggers](../build/triggers.md). -::: moniker-end +- [Continuous deployment triggers](#continuous-deployment-triggers) -Release triggers are an automation tool to deploy your application. When the trigger conditions are met, the pipeline will deploy your artifacts to the environment/stages you already specified. +- [Scheduled release triggers](#scheduled-release-triggers) - +- [Pull request release triggers](#pull-request-triggers) + +- [Stage triggers](#stage-triggers) ## Continuous deployment triggers -Continuous deployment triggers allow you to create a release every time a new build artifact is available. Using the build branch filters you can trigger deployment for a specific target branch. A release will be triggered only if the Git push contains a commit on the specified branch. For example, selecting `main` will trigger a release for a Git push which contains one or more commits to the main branch. To trigger a release for any commit to branches under `features/`, enter `features/*`. To trigger a release for commits to all branches, enter `*`. Note that all specified filters will be OR'ed. +Continuous deployment triggers enable you to automatically create a release whenever a new artifact becomes available. By Using the build branch filters you can trigger deployment for a specific target branch. A release is triggered only for pipeline artifacts originating from one of the selected branches. + +For example, selecting *main* will trigger a release every time a new artifact becomes available from the main branch. To trigger a release for any build under 'features/', enter 'features/*'. To trigger a release for all builds, use '*'. Note that all specified filters will be OR'ed meaning any artifact matching at least one filter condition will trigger a release. + +1. Sign in to your Azure DevOps organization, and then navigate to your project. -:::image type="content" source="media/trigger-01.png" alt-text="Configure continuous deployment triggers"::: +1. Select **Pipelines** > **Releases**. -> [!NOTE] -> Automatically creating a release does not mean it will be automatically deployed to a stage. You must set up triggers to deploy your app to the various stages. +1. Select your release definition, and then select **Edit**. - +1. Select the **Continuous deployment triggers** icon, and then select the toggle button to enable the **Continuous deployment trigger**, then add your **Build branch filters**. + + :::image type="content" source="media/trigger-01.png" alt-text="A screenshot displaying how to configure the continuous deployment trigger in a release pipeline."::: ## Scheduled release triggers Scheduled release triggers allow you to create new releases at specific times. -Select the schedule icon under the **Artifacts** section. Toggle the Enabled/Disabled button and specify your release schedule. You can set up multiple schedules to trigger a release. +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines** > **Releases**. -> [!div class="mx-imgBorder"] -> ![Defining schedules to trigger releases](media/trigger-04.png) +1. Select your release definition, and then select **Edit**. -::: moniker range="> tfs-2018" +1. Under the **Artifacts** section, select the **Schedule set** icon, select the toggle button to enable the **Scheduled release trigger**, and then specify your release schedule. You can set up multiple schedules to trigger releases. - + :::image type="content" source="media/trigger-04.png" alt-text="A screenshot displaying how to configure the Scheduled release triggers in a release pipeline."::: ## Pull request triggers -If you chose to enable the pull-request triggers, a release will be created every time a selected artifact is available as part of a pull request workflow. +If you chose to enable the pull-request triggers, a release will be triggered whenever a new version of the selected artifact is created by the pull request pipeline workflow. To use a pull request trigger, you must also enable it for specific stages (covered in the next section). You may also want to set up [branch policies](../../repos/git/pr-status-policy.md) for your branches. -> [!div class="mx-imgBorder"] -> ![Configure a pull request trigger.](media/trigger-01a.png) +1. Sign in to your Azure DevOps organization, and then navigate to your project. -To use a pull request trigger, you must also enable it for specific stages. We will go through stage triggers in the next section. You may also want to set up a [branch policies](../../repos/git/pr-status-policy.md) for your branches. +1. Select **Pipelines** > **Releases**. -You can also use **Build tags** to organize your workflow and tag specific runs. The following pull request trigger will create a release every time a new artifact version is available as part of a pull request to the *main* branch with the tags *Migration* and *Deployment*. +1. Select your release definition, and then select **Edit**. -:::image type="content" source="media/build-tags-example.png" alt-text="Screenshot showing an example of how to set up a pull request trigger with build tags"::: +1. Select the **Continuous deployment triggers** icon, and then select the toggle button to enable the **Pull request trigger**, then add your **Target Branch Filters**. In the example below, a release is triggered every time a new artifact version is created as part of a pull request to the *main* branch with the tags *Migration* and *Deployment*. -::: moniker-end + :::image type="content" source="media/trigger-01a.png" alt-text="A screenshot displaying how to configure pull request triggers in a release pipeline."::: ## Stage triggers Stage triggers allow you set up specific conditions to trigger deployment to a specific stage. -- **Select trigger**: - Set the trigger that will start the deployment to your stage automatically. Use the **Stages** dropdown to trigger a release after a successful deployment to the selected stage. Select **Manual only** to only allow manual trigger. +1. Sign in to your Azure DevOps organization, and then navigate to your project. + +1. Select **Pipelines** > **Releases**. - :::image type="content" source="media/trigger-02a.png" alt-text="A screenshot showing pre-deployment triggers."::: +1. Select your release definition, and then select **Edit**. -- **Artifacts filter**: - Enable the toggle button to trigger a new deployment based on specific artifacts. In this example, a release will be deployed when a new artifact is available from the specified branch. +1. Under the **Stages** section, select the **Pre-deployment conditions** icon, and set up your triggers. - :::image type="content" source="media/trigger-02b.png" alt-text="A screenshot showing pre-deployment artifact filters."::: + :::image type="content" source="media/release-triggers-to-stages.png" alt-text="A screenshot showing stage triggers in a release pipeline." lightbox="media/release-triggers-to-stages.png"::: -- **Schedule**: - Trigger a new deployment to your specified stage at a specific time. +- **Select trigger**: Choose the trigger to start deployment to this stage automatically. Select "After release" to deploy to this stage each time a new release is created. Select "After stage" to deploy after successful deployments to selected stages. Select "Manual only" to allow only manual deployments. - :::image type="content" source="media/trigger-02.png" alt-text="A screenshot showing pre-deployment schedule settings."::: +- **Artifacts filter**: Specify artifact condition(s) that must be met to trigger a deployment. A release will be deployed to this stage only if all artifact conditions match. -- **Pull-request deployment**: - Enable the toggle button to trigger a new release every time a new pull request is created. It's recommended to disable this feature for production environment. +- **Schedule**: Set a specified time to trigger a deployment to this stage. - :::image type="content" source="media/trigger-02c.png" alt-text="A screenshot showing pull request deployment trigger."::: +- **Pull-request deployment**: Allow pull request-triggered releases to deploy to this stage. We recommend keeping this option disabled for critical or production stages. -- **Pre-deployment approvals**: -Select the users who can approve or reject deployments to your selected stage. By default, when this feature is enabled, all project users must approve the deployment. If a group is added to the approvers list, at least one user in the group must approve the deployment. You can also specify the *Approval policies* and *Timeout* (the maximum time for an approval to remain in pending state before it is automatically rejected). +## Related content - :::image type="content" source="media/pre-deployment-approval.png" alt-text="A screenshot showing pre-deployment approvals."::: +- [Deploy pull request Artifacts](deploy-pull-request-builds.md) -- **Gates**: -Enable the toggle button to set up specific gates to evaluate before trigger deployment. +- [Deploy to different stages from multiple branches](deploy-multiple-branches.md) - :::image type="content" source="media/gates.png" alt-text="A screenshot showing pre-deployment gates."::: +- [Publish and download pipeline artifacts](../artifacts/pipeline-artifacts.md) -- **Deployment queue settings**: -Configure specific actions when multiple releases are queued for deployment. - :::image type="content" source="media/deploy-queue.png" alt-text="A screenshot showing deployment queue settings."::: diff --git a/docs/pipelines/release/troubleshoot-workload-identity.md b/docs/pipelines/release/troubleshoot-workload-identity.md new file mode 100644 index 00000000000..cccf96f8674 --- /dev/null +++ b/docs/pipelines/release/troubleshoot-workload-identity.md @@ -0,0 +1,155 @@ +--- +title: Troubleshoot workload identity service connections +ms.custom: devx-track-arm-template, arm2024 +description: Learn how to troubleshoot an Azure Resource Manager workload identity service connection in Azure Pipelines, one of the services in Azure DevOps. +ms.topic: troubleshooting-general +ms.author: jukullam +author: juliakm +ms.date: 03/12/2025 +monikerRange: '>= azure-devops' +"recommendations": "true" +--- + + +# Troubleshoot an Azure Resource Manager workload identity service connection + +Get help debugging common issues with workload identity service connections. You also learn how to manually create a service connection if you need to. + +## Troubleshooting checklist + +Use the following checklist to troubleshoot issues with workload identity service connections: + +- Review pipeline tasks to ensure that they support workload identity. +- Verify that workload identity federation is active for the tenant. +- Check the issuer URL and federation subject identifier for accuracy. + +The following sections describe the issues and how to resolve them. + +### Review pipeline tasks + +Not all pipelines tasks support workload identity. Specifically, only Azure Resource Manager service connection properties on tasks use workload identity federation. The table below lists workload identity federation support for [tasks included with Azure DevOps](/azure/devops/pipelines/tasks/reference/?view=azure-pipelines&preserve-view=true). For tasks installed from the [Marketplace](https://marketplace.visualstudio.com/search?target=AzureDevOps&category=Azure%20Pipelines&visibilityQuery=all&sortBy=Installs), contact the extension publisher for support. + +| Task | Workload identity federation support | +|------------------------------------------|---------------------------------------------------------------------------------------------------------------| +| AutomatedAnalysis@0 | Y | +| AzureAppServiceManage@0 | Y | +| AzureAppServiceSettings@1 | Y | +| AzureCLI@1 | Y | +| AzureCLI@2 | Y | +| AzureCloudPowerShellDeployment@1 | Use AzureCloudPowerShellDeployment@2 | +| AzureCloudPowerShellDeployment@2 | Y | +| AzureContainerApps@0 | Y | +| AzureContainerApps@1 | Y | +| AzureFileCopy@1 | Use AzureFileCopy@6 | +| AzureFileCopy@2 | Use AzureFileCopy@6 | +| AzureFileCopy@3 | Use AzureFileCopy@6 | +| AzureFileCopy@4 | Use AzureFileCopy@6 | +| AzureFileCopy@5 | Use AzureFileCopy@6 | +| AzureFileCopy@6 | Y | +| AzureFunctionApp@1 | Y | +| AzureFunctionApp@2 | Y | +| AzureFunctionAppContainer@1 | Y | +| AzureFunctionOnKubernetes@0 | Use AzureFunctionOnKubernetes@1 | +| AzureFunctionOnKubernetes@1 | Y | +| AzureIoTEdge@2 | Y | +| AzureKeyVault@1 | Y | +| AzureKeyVault@2 | Y | +| AzureMonitor@0 | Use AzureMonitor@1 | +| AzureMonitor@1 | Y | +| AzureMysqlDeployment@1 | Y | +| AzureNLBManagement@1 | N | +| AzurePolicyCheckGate@0 | Y | +| AzurePowerShell@2 | Y | +| AzurePowerShell@3 | Y | +| AzurePowerShell@4 | Y | +| AzurePowerShell@5 | Y | +| AzureResourceGroupDeployment@2 | Y | +| AzureResourceManagerTemplateDeployment@3 | Y | +| AzureRmWebAppDeployment@3 | Y | +| AzureRmWebAppDeployment@4 | Y | +| AzureSpringCloud@0 | Y | +| AzureVmssDeployment@0 | Y | +| AzureWebApp@1 | Y | +| AzureWebAppContainer@1 | Y | +| ContainerBuild@0 | Y | +| ContainerStructureTest@0 | Y | +| Docker@0 | Y | +| Docker@1 | Azure service connection: Y
      Docker Registry service connection: N | +| Docker@2 | Y | +| DockerCompose@0 | Y | +| DockerCompose@1 | Y | +| DotNetCoreCLI@2 | Y | +| HelmDeploy@0 | Azure service connection: Y | +| HelmDeploy@1 | Azure service connection: Y | +| InvokeRESTAPI@1 | Y | +| JavaToolInstaller@0 | Y | +| JenkinsDownloadArtifacts@1 | Y | +| Kubernetes@0 | Use Kubernetes@1 | +| Kubernetes@1 | Y | +| KubernetesManifest@0 | Use KubernetesManifest@1 | +| KubernetesManifest@1 | Y | +| Maven@4 | Y | +| Notation@0 | Y | +| PackerBuild@0 | Use PackerBuild@1 | +| PackerBuild@1 | Y | +| PublishToAzureServiceBus@1 | Use PublishToAzureServiceBus@2 with Azure service connection | +| PublishToAzureServiceBus@2 | Y | +| ServiceFabricComposeDeploy@0 | N | +| ServiceFabricDeploy@1 | N | +| SqlAzureDacpacDeployment@1 | Y | +| VSTest@3 | Y | + +### Verify that workload identity federation is active + +If you see error messages **AADSTS700223** or **AADSTS700238**, workload identity federation was disabled in your Microsoft Entra tenant. + +Verify that there are no Microsoft Entra policies in place that block federated credentials. + +### Check the issuer URL for accuracy + +If you see a message that indicates **no matching federated identity record found**, either the issuer URL or the federation subject doesn't match. The correct issuer URL starts with `https://login.microsoftonline.com`. + +You can fix the issuer URL by editing and saving the service connection to update the issuer URL. If Azure DevOps didn't create the identity, the issuer URL must be updated manually. For Azure identities, the issuer URL automatically updates. + +## Common issues + +The next sections identify common issues and describe causes and resolutions. + + + +### I don't have permissions to create a service principal in the Microsoft Entra tenant + +You can't use the Azure DevOps service connection configuration tool if you don't have the correct permissions. Your permissions level is insufficient to use the tool if you either don't have permissions to create service principals or if you're using a different Microsoft Entra tenant than your Azure DevOps user. + +You must either have permissions in Microsoft Entra ID to create app registrations or have an appropriate role (for example, Application Developer). + +You have two options to resolve the issue: + +- [Solution 1: Manually configure workload identity by using managed identity authentication](configure-workload-identity.md#set-a-workload-identity-service-connection-to-use-managed-identity-authentication) +- [Solution 2: Manually configure workload identity by using app registration authentication](configure-workload-identity.md#app-registration-workload-identity) + +## Error messages + +The following table identifies common error messages and issues that might generate them: + +| Message | Possible issue | +|---------|-----------------| +| **cannot request token: Get `?audience=api://AzureADTokenExchange: unsupported protocol scheme`** | The task doesn't support workload identity federation. | +| **Identity not found** | The task doesn't support workload identity federation. | +| **Could not fetch access token for Azure** | The task doesn't support workload identity federation. | +| **AADSTS700016: Application with identifier '****' wasn't found** | The identity that is used for the service connection no longer exists, might have been removed from the service connection, or is incorrectly configured. If you configure the service connection manually with a pre-created identity, make sure the `appID`/`clientId` is correctly configured. | +| **AADSTS7000215: Invalid client secret provided.** | You're using a service connection that has an expired secret. [Convert the service connection to workload identity federation](https://aka.ms/azdo-rm-workload-identity-conversion) and replace the expired secret with federated credentials. | +| **AADSTS700024: Client assertion is not within its valid time range** | If the error happens after approximately 1 hour, use a service connection with [Workload identity federation and a Managed Identity](configure-workload-identity.md#set-a-workload-identity-service-connection-to-use-managed-identity-authentication) instead. Managed Identity tokens have a [lifetime of around 24 hours](/entra/identity/managed-identities-azure-resources/managed-identities-faq#are-managed-identities-tokens-cached).
      If the error happens before 1 hour but after 10 minutes, move commands that (implicitly) request an access token to e.g. access Azure storage to the beginning of your script. The access token will be cached for subsequent commands. | +| **AADSTS70021: No matching federated identity record found for presented assertion. Assertion Issuer: `https://app.vstoken.visualstudio.com`.** | No federated credential was created or the issuer URL isn't correct. The correct issuer URL has the format `https://login.microsoftonline.com/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`. You can fix the issuer URL by editing and then saving a service connection. If Azure DevOps didn't create your identity, you must manually update the issuer. You can find the correct issuer in the edit dialog of the service connection or in the response if you use the REST API. | +| **AADSTS70021: No matching federated identity record found for presented assertion. Assertion Issuer: `https://login.microsoftonline.com/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`. Assertion Subject: `sc:////.`** | Either the issuer URL or the federation subject doesn't match. The Azure DevOps organization or project was renamed or a manually created service connection was renamed without updating the federation subject on the identity. | +| **AADSTS700211: No matching federated identity record found for presented assertion issuer** | No federated credential was created or the issuer URL is not correct. | +| **AADSTS700213: No matching federated identity record found for presented assertion subject** | No federated credential was created or the subject is not correct. | +| **AADSTS700223** | Workload identity federation is constrained or disabled on the Microsoft Entra tenant. In this scenario, it may be possible to use a managed identity for the federation instead. For more information, see [Workload identity with managed identity](https://aka.ms/azdo-rm-workload-identity-manual). | +| **AADSTS70025: Client application has no configured federated identity credentials** | Make sure federated credentials are configured on the App registration or Managed Identity. | +| **Microsoft Entra rejected the token issued by Azure DevOps with error code AADSTS700238** | Workload identity federation has been constrained on the Microsoft Entra tenant. The issuer for your organization (`https://login.microsoftonline.com/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`) isn't allowed to use workload identity federation. Ask your Microsoft Entra tenant administrator or administration team to allow workload identity federation for your Azure DevOps organization. | +| **AADSTS900382: Confidential Client is not supported in Cross Cloud** | Some sovereign clouds block Workload identity federation. | +| **Failed to obtain the JSON Web Token (JWT) using service principal client ID** | Your federation identity credentials are misconfigured or the Microsoft Entra tenant blocks OpenID Connect (OIDC). | +| **Script failed with error: UnrecognizedArgumentError: unrecognized arguments: --federated-token** | You're using an AzureCLI task on an agent that has an earlier version of the Azure CLI installed. Workload identity federation requires Azure CLI 2.30 or later. | +| **Failed to create an app in Microsoft Entra ID. Error: Insufficient privileges to complete the operation in Microsoft Graph. Ensure that the user has permissions to create a Microsoft Entra Application.** | The ability to create app registrations was [disabled](/azure/active-directory/roles/delegate-app-roles#restrict-who-can-create-applications) in the Microsoft Entra tenant. Assign the user who is creating the service connection the [Application Developer](/azure/active-directory/roles/permissions-reference#application-developer) Microsoft Entra role. Alternatively, create the service connection manually by using a managed identity. For more information, see [Workload identity with managed identity](https://aka.ms/azdo-rm-workload-identity-manual). | + +Is the AADSTS error you see not listed above? Check [Microsoft Entra authentication and authorization error codes](/entra/identity-platform/reference-error-codes#aadsts-error-codes). diff --git a/docs/pipelines/release/variables.md b/docs/pipelines/release/variables.md index 19db179d831..ac78843d5be 100644 --- a/docs/pipelines/release/variables.md +++ b/docs/pipelines/release/variables.md @@ -1,281 +1,225 @@ --- -title: Classic release and artifacts variables -description: Understand the different Azure DevOps variables within the classic release Pipelines. This reference article covers both custom and default variables. -author: shashban -ms.author: shashban +title: Use variables in Classic release pipelines +description: Learn how to use the different types of variables in a Classic release pipeline. +author: geekzter +ms.author: ericvan ms.assetid: 864FEB87-FE29-446D-804E-AD6ABDEA82C3 ms.topic: conceptual -ms.custom: seodec18, contperf-fy20q4 -ms.date: 10/18/2021 +ms.date: 08/15/2024 monikerRange: '<= azure-devops' --- -# Classic release and artifacts variables +# Use variables in Classic release pipelines [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end +Using variables in Classic release pipelines is a convenient way to exchange and transport data throughout your pipeline. Each variable is stored as a string and its value can change between pipeline runs. ::: moniker range="azure-devops" -Classic release and artifacts variables are a convenient way to exchange and transport data throughout your pipeline. Each variable is stored as a string and its value can change between runs of your pipeline. - -Variables are different from [Runtime parameters](../process/runtime-parameters.md) which are only available at template parsing time. +Unlike [Runtime parameters](../process/runtime-parameters.md), which are only available at template parsing time, variables in Classic release pipelines are accessible throughout the entire deployment process ::: moniker-end -As you compose the tasks for deploying your application into each stage in your DevOps CI/CD processes, variables will help you to: +When setting up tasks to deploy your application in each stage of your Classic release pipeline, variables can help you: -* Define a more generic deployment pipeline once, and then -customize it easily for each stage. For example, a variable -can be used to represent the connection string for web deployment, -and the value of this variable can be changed from one stage -to another. These are **custom variables**. +- **Simplify customization**: Define a generic deployment pipeline once and easily adapt it for different stages. For instance, use a variable to represent a web deployment's connection string, adjusting its value as needed for each stage. These are known as *custom variables*. -* Use information about the context of the particular release, -[stage](../process/stages.md), [artifacts](artifacts.md), or -[agent](../agents/agents.md) in which the deployment pipeline is -being run. For example, your script may need access to the location -of the build to download it, or to the working directory on the -agent to create temporary files. These are **default variables**. +- **Leverage contextual information**: Access details about the release context, such as a [stage](../process/stages.md), an [artifact](artifacts.md), or the [agent](../agents/agents.md) running the deployment. For example, your scripts might require the build location for download, or the agent's working directory to create temporary files. These are referred to as *default variables*. > [!NOTE] > For YAML pipelines, see [user-defined variables](../process/variables.md) and [predefined variables](../build/variables.md) for more details. ## Default variables -Information about the execution context is made available to running tasks through default variables. Your tasks and scripts can use these variables to find information about the system, release, stage, or agent they are running in. -With the exception of **System.Debug**, these variables are read-only and their values are automatically set by the system. -Some of the most significant variables are described in the following tables. -To view the full list, see [View the current values of all variables](#view-vars). - -> [!TIP] -> You can view the [current values of all variables](#view-vars) for a release, and use a default variable to [run a release in debug mode](#debug-mode). - -## System +Default variables provide essential information about the execution context to your running tasks and scripts. These variables allow you to access details about the *system*, *release*, *stage*, or *agent* in which they are running. + +With the exception of *System.Debug*, default variables are read-only, with their values automatically set by the system. + +Some of the most significant variables are described in the following tables. To view the full list, see [View the current values of all variables](#view-the-current-values-of-all-variables). + +### System variables + +| Variable name | Description | +|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **System.TeamFoundationServerUri** | The URL of the service connection in Azure Pipelines. Use this from your scripts or tasks to call Azure Pipelines REST APIs.

      Example: `https://fabrikam.vsrm.visualstudio.com/` | +| **System.TeamFoundationCollectionUri** | The URL of the Team Foundation collection or Azure Pipelines. Use this from your scripts or tasks to call REST APIs on other services such as Build and Version control.

      Example: `https://dev.azure.com/fabrikam/` | +| **System.CollectionId** | The ID of the collection to which this build or release belongs.

      Example: `6c6f3423-1c84-4625-995a-f7f143a1e43d` | +| **System.DefinitionId** | The ID of the release pipeline to which the current release belongs.

      Example: `1` | +| **System.TeamProject** | The name of the project to which this build or release belongs.

      Example: `Fabrikam` | +| **System.TeamProjectId** | The ID of the project to which this build or release belongs.

      Example: `79f5c12e-3337-4151-be41-a268d2c73344` | +| **System.ArtifactsDirectory** | The directory to which artifacts are downloaded during deployment of a release. The directory is cleared before every deployment if it requires artifacts to be downloaded to the agent. Same as Agent.ReleaseDirectory and System.DefaultWorkingDirectory.

      Example: `C:\agent\_work\r1\a` | +| **System.DefaultWorkingDirectory** | The directory to which artifacts are downloaded during deployment of a release. The directory is cleared before every deployment if it requires artifacts to be downloaded to the agent. Same as Agent.ReleaseDirectory and System.ArtifactsDirectory.

      Example: `C:\agent\_work\r1\a` | +| **System.WorkFolder** | The working directory for this agent, where subfolders are created for every build or release. Same as Agent.RootDirectory and Agent.WorkFolder.

      Example: `C:\agent\_work` | +| **System.Debug** | This is the only system variable that can be _set_ by the users. Set this to true to [run the release in debug mode](#run-a-release-in-debug-mode) to assist in fault-finding.

      Example: `true` | + +### Release variables + +| Variable name | Description | +|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Release.AttemptNumber** | The number of times this release is deployed in this stage.

      Example: `1` | +| **Release.DefinitionEnvironmentId** | The ID of the stage in the corresponding release pipeline.

      Example: `1` | +| **Release.DefinitionId** | The ID of the release pipeline to which the current release belongs.

      Example: `1` | +| **Release.DefinitionName** | The name of the release pipeline to which the current release belongs.

      Example: `fabrikam-cd` | +| **Release.Deployment.RequestedFor** | The display name of the identity that triggered (started) the deployment currently in progress.

      Example: `Mateo Escobedo` | +| **Release.Deployment.RequestedForEmail** | The email address of the identity that triggered (started) the deployment currently in progress.

      Example: `mateo@fabrikam.com` | +| **Release.Deployment.RequestedForId** | The ID of the identity that triggered (started) the deployment currently in progress.

      Example: `2f435d07-769f-4e46-849d-10d1ab9ba6ab` | +| **Release.DeploymentID** | The ID of the deployment. Unique per job.

      Example: `254` | +| **Release.DeployPhaseID** | The ID of the phase where deployment is running.

      Example: `127` | +| **Release.EnvironmentId** | The ID of the stage instance in a release to which the deployment is currently in progress.

      Example: `276` | +| **Release.EnvironmentName** | The name of stage to which deployment is currently in progress.

      Example: `Dev` | +| **Release.EnvironmentUri** | The URI of the stage instance in a release to which deployment is currently in progress.

      Example: `vstfs://ReleaseManagement/Environment/276` | +| **Release.Environments.{stage-name}.status** | The deployment status of the stage.

      Example: `InProgress` | +| **Release.PrimaryArtifactSourceAlias** | The alias of the primary artifact source.

      Example: `fabrikam\_web` | +| **Release.Reason** | The reason for the deployment. Supported values are:
      `ContinuousIntegration` - the release started in Continuous Deployment after a build completed.
      `Manual` - the release started manually.
      `None` - the deployment reason has not been specified.
      `Schedule` - the release started from a schedule. | +| **Release.ReleaseDescription** | The text description provided at the time of the release.

      Example: `Critical security patch` | +| **Release.ReleaseId** | The identifier of the current release record.

      Example: `118` | +| **Release.ReleaseName** | The name of the current release.

      Example: `Release-47` | +| **Release.ReleaseUri** | The URI of the current release.

      Example: `vstfs://ReleaseManagement/Release/118` | +| **Release.ReleaseWebURL** | The URL for this release.

      Example: `https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary` | +| **Release.RequestedFor** | The display name of the identity that triggered the release.

      Example: `Mateo Escobedo` | +| **Release.RequestedForEmail** | The email address of the identity that triggered the release.

      Example: `mateo@fabrikam.com` | +| **Release.RequestedForId** | The ID of the identity that triggered the release.

      Example: `2f435d07-769f-4e46-849d-10d1ab9ba6ab` | +| **Release.SkipArtifactsDownload** | Boolean value that specifies whether or not to skip downloading of artifacts to the agent.

      Example: `FALSE` | +| **Release.TriggeringArtifact.Alias** | The alias of the artifact which triggered the release. This is empty when the release was scheduled or triggered manually.

      Example: `fabrikam\_app`| + + +### Release-stage variables + +| Variable name | Description | +|----------------------------------------------|----------------------------------------------------------------------------------------------------| +| **Release.Environments.{stage name}.Status** | The status of deployment of this release within a specified stage.

      Example: `NotStarted` | + +### Agent variables + +| Variable name | Description | +|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Agent.Name** | The name of the agent as registered with the [agent pool](../agents/pools-queues.md). This is likely to be different from the computer name.

      Example: `fabrikam-agent` | +| **Agent.MachineName** | The name of the computer on which the agent is configured.

      Example: `fabrikam-agent` | +| **Agent.Version** | The version of the agent software.

      Example: `2.109.1` | +| **Agent.JobName** | The name of the job that is running, such as Release or Build.

      Example: `Release` | +| **Agent.HomeDirectory** | The folder where the agent is installed. This folder contains the code and resources for the agent.

      Example: `C:\agent` | +| **Agent.ReleaseDirectory** | The directory to which artifacts are downloaded during deployment of a release. The directory is cleared before every deployment if it requires artifacts to be downloaded to the agent. Same as System.ArtifactsDirectory and System.DefaultWorkingDirectory.

      Example: `C:\agent\_work\r1\a` | +| **Agent.RootDirectory** | The working directory for this agent, where subfolders are created for every build or release. Same as Agent.WorkFolder and System.WorkFolder.

      Example: `C:\agent\_work` | +| **Agent.WorkFolder** | The working directory for this agent, where subfolders are created for every build or release. Same as Agent.RootDirectory and System.WorkFolder.

      Example: `C:\agent\_work` | +| **Agent.DeploymentGroupId** | The ID of the deployment group the agent is registered with. This is available only in deployment group jobs.

      Example: `1` | + +## Release Artifacts variables + +For each artifact that is referenced in a release, you can use the following artifact variables. Note that not all variables apply to every artifact type. The table below lists default artifact variables and provides examples of their values based on the artifact type. If an example is empty, it indicates that the variable is not applicable for that artifact type. + +Replace the `{alias}` placeholder with the value you specified for the [artifact source alias](artifacts.md#artifact-source-alias) or with the default value generated for the release pipeline. | Variable name | Description | |---------------|-------------| -| System.TeamFoundationServerUri | The URL of the service connection in TFS or Azure Pipelines. Use this from your scripts or tasks to call Azure Pipelines REST APIs.

      Example: `https://fabrikam.vsrm.visualstudio.com/` | -| System.TeamFoundationCollectionUri | The URL of the Team Foundation collection or Azure Pipelines. Use this from your scripts or tasks to call REST APIs on other services such as Build and Version control.

      Example: `https://dev.azure.com/fabrikam/` | -| System.CollectionId | The ID of the collection to which this build or release belongs. Not available in TFS 2015.

      Example: `6c6f3423-1c84-4625-995a-f7f143a1e43d` | -| System.DefinitionId | The ID of the release pipeline to which the current release belongs. Not available in TFS 2015.

      Example: `1` | -| System.TeamProject | The name of the project to which this build or release belongs.

      Example: `Fabrikam` | -| System.TeamProjectId | The ID of the project to which this build or release belongs. Not available in TFS 2015.

      Example: `79f5c12e-3337-4151-be41-a268d2c73344` | -| System.ArtifactsDirectory | The directory to which artifacts are downloaded during deployment of a release. The directory is cleared before every deployment if it requires artifacts to be downloaded to the agent. Same as Agent.ReleaseDirectory and System.DefaultWorkingDirectory.

      Example: `C:\agent\_work\r1\a` | -| System.DefaultWorkingDirectory | The directory to which artifacts are downloaded during deployment of a release. The directory is cleared before every deployment if it requires artifacts to be downloaded to the agent. Same as Agent.ReleaseDirectory and System.ArtifactsDirectory.

      Example: `C:\agent\_work\r1\a` | -| System.WorkFolder | The working directory for this agent, where subfolders are created for every build or release. Same as Agent.RootDirectory and Agent.WorkFolder.

      Example: `C:\agent\_work` | -| System.Debug | This is the only system variable that can be _set_ by the users. Set this to true to [run the release in debug mode](#debug-mode) to assist in fault-finding.

      Example: `true` | - -## Release +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.DefinitionId | The identifier of the build pipeline or repository.Examples:

      Azure Pipelines: `1`
      GitHub: `fabrikam/asp` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.DefinitionName | The name of the build pipeline or repository.Examples:

      Azure Pipelines: `fabrikam-ci`
      TFVC: `$/fabrikam`
      Git: `fabrikam`
      GitHub: `fabrikam/asp (main)` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.BuildNumber | The build number or the commit identifier.Examples:

      Azure Pipelines: `20170112.1`
      Jenkins: `20170112.1`
      TFVC: `Changeset 3`
      Git: `38629c964`
      GitHub: `38629c964` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.BuildId | The build identifier.Examples:

      Azure Pipelines: `130`
      Jenkins: `130`
      GitHub: `38629c964d21fe405ef830b7d0220966b82c9e11` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.BuildURI | The URL for the build.Examples:

      Azure Pipelines: `vstfs://build-release/Build/130`
      GitHub: `https://github.com/fabrikam/asp` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.SourceBranch | The full path and name of the branch from which the source was built.Examples:

      Azure Pipelines: `refs/heads/main` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.SourceBranchName | The name only of the branch from which the source was built.Examples:

      Azure Pipelines: `main` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.SourceVersion | The commit that was built.Examples:

      Azure Pipelines: `bc0044458ba1d9298cdc649cb5dcf013180706f7` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.Repository.Provider | The type of repository from which the source was built.Examples:

      Azure Pipelines: `Git` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.RequestedForID | The identifier of the account that triggered the build.Examples:

      Azure Pipelines: `2f435d07-769f-4e46-849d-10d1ab9ba6ab` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.RequestedFor | The name of the account that requested the build.Examples:

      Azure Pipelines: `Mateo Escobedo` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.Type | The type of artifact source, such as Build.Examples

      Azure Pipelines: `Build`
      Jenkins: `Jenkins`
      TFVC: `TFVC`
      Git: `Git`
      GitHub: `GitHub` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.PullRequest.TargetBranch | The full path and name of the branch that is the target of a pull request. This variable is initialized only if the release is triggered by a pull request flow.Examples:

      Azure Pipelines: `refs/heads/main` | +| Release.Artifacts.{[alias](artifacts.md#artifact-source-alias)}.PullRequest.TargetBranchName | The name only of the branch that is the target of a pull request. This variable is initialized only if the release is triggered by a pull request flow.Examples:

      Azure Pipelines: `main` | + +## Primary Artifact variables + +In Classic release pipelines, if you are using multiple artifacts, you can designate one as the primary artifact. Azure Pipelines will then populate the following variables for the designated primary artifact. + +| Variable name | Same as | +|----------------------------------|------------------------------------------------------| +| **Build.DefinitionId** | Release.Artifacts.{Primary artifact alias}.DefinitionId | +| **Build.DefinitionName** | Release.Artifacts.{Primary artifact alias}.DefinitionName | +| **Build.BuildNumber** | Release.Artifacts.{Primary artifact alias}.BuildNumber | +| **Build.BuildId** | Release.Artifacts.{Primary artifact alias}.BuildId | +| **Build.BuildURI** | Release.Artifacts.{Primary artifact alias}.BuildURI | +| **Build.SourceBranch** | Release.Artifacts.{Primary artifact alias}.SourceBranch | +| **Build.SourceBranchName** | Release.Artifacts.{Primary artifact alias}.SourceBranchName | +| **Build.SourceVersion** | Release.Artifacts.{Primary artifact alias}.SourceVersion | +| **Build.Repository.Provider** | Release.Artifacts.{Primary artifact alias}.Repository.Provider | +| **Build.RequestedForID** | Release.Artifacts.{Primary artifact alias}.RequestedForID | +| **Build.RequestedFor** | Release.Artifacts.{Primary artifact alias}.RequestedFor | +| **Build.Type** | Release.Artifacts.{Primary artifact alias}.Type | +| **Build.PullRequest.TargetBranch** | Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranch | +| **Build.PullRequest.TargetBranchName** | Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranchName | -| Variable name | Description | -|---------------|-------------| -| Release.AttemptNumber | The number of times this release is deployed in this stage. Not available in TFS 2015.

      Example: `1` | -| Release.DefinitionEnvironmentId | The ID of the stage in the corresponding release pipeline. Not available in TFS 2015.

      Example: `1` | -| Release.DefinitionId | The ID of the release pipeline to which the current release belongs. Not available in TFS 2015.

      Example: `1` | -| Release.DefinitionName | The name of the release pipeline to which the current release belongs.

      Example: `fabrikam-cd` | -| Release.Deployment.RequestedFor | The display name of the identity that triggered (started) the deployment currently in progress. Not available in TFS 2015.

      Example: `Mateo Escobedo` | -| Release.Deployment.RequestedForEmail | The email address of the identity that triggered (started) the deployment currently in progress. Not available in TFS 2015.

      Example: `mateo@fabrikam.com` | -| Release.Deployment.RequestedForId | The ID of the identity that triggered (started) the deployment currently in progress. Not available in TFS 2015.

      Example: `2f435d07-769f-4e46-849d-10d1ab9ba6ab` | -| Release.DeploymentID | The ID of the deployment. Unique per job.

      Example: `254` | -| Release.DeployPhaseID | The ID of the phase where deployment is running.

      Example: `127` | -| Release.EnvironmentId | The ID of the stage instance in a release to which the deployment is currently in progress.

      Example: `276` | -| Release.EnvironmentName | The name of stage to which deployment is currently in progress.

      Example: `Dev` | -| Release.EnvironmentUri | The URI of the stage instance in a release to which deployment is currently in progress.

      Example: `vstfs://ReleaseManagement/Environment/276` | -| Release.Environments.{stage-name}.status | The deployment status of the stage.

      Example: `InProgress` | -| Release.PrimaryArtifactSourceAlias | The alias of the primary artifact source

      Example: `fabrikam\_web` | -| Release.Reason | The reason for the deployment. Supported values are:
      `ContinuousIntegration` - the release started in Continuous Deployment after a build completed.
      `Manual` - the release started manually.
      `None` - the deployment reason has not been specified.
      `Schedule` - the release started from a schedule. | -| Release.ReleaseDescription | The text description provided at the time of the release.

      Example: `Critical security patch` | -| Release.ReleaseId | The identifier of the current release record.

      Example: `118` | -| Release.ReleaseName | The name of the current release.

      Example: `Release-47` | -| Release.ReleaseUri | The URI of current release.

      Example: `vstfs://ReleaseManagement/Release/118` | -| Release.ReleaseWebURL | The URL for this release.

      Example: `https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary` | -| Release.RequestedFor | The display name of identity that triggered the release.

      Example: `Mateo Escobedo` | -| Release.RequestedForEmail | The email address of identity that triggered the release.

      Example: `mateo@fabrikam.com` | -| Release.RequestedForId | The ID of identity that triggered the release.

      Example: `2f435d07-769f-4e46-849d-10d1ab9ba6ab` | -| Release.SkipArtifactsDownload | Boolean value that specifies whether or not to skip downloading of artifacts to the agent.

      Example: `FALSE` | -| Release.TriggeringArtifact.Alias | The alias of the artifact which triggered the release. This is empty when the release was scheduled or triggered manually.

      Example: `fabrikam\_app` | - -## Release-stage - -| Variable name | Description | -|---------------|-------------| -| Release.Environments.{stage name}.Status | The status of deployment of this release within a specified stage. Not available in TFS 2015.

      Example: `NotStarted` | - -## Agent - -| Variable name | Description | -| ------------- | ----------- | -| Agent.Name | The name of the agent as registered with the [agent pool](../agents/pools-queues.md). This is likely to be different from the computer name.

      Example: `fabrikam-agent` | -| Agent.MachineName | The name of the computer on which the agent is configured.

      Example: `fabrikam-agent` | -| Agent.Version | The version of the agent software.

      Example: `2.109.1` | -| Agent.JobName | The name of the job that is running, such as Release or Build.

      Example: `Release` | -| Agent.HomeDirectory | The folder where the agent is installed. This folder contains the code and resources for the agent.

      Example: `C:\agent` | -| Agent.ReleaseDirectory | The directory to which artifacts are downloaded during deployment of a release. The directory is cleared before every deployment if it requires artifacts to be downloaded to the agent. Same as System.ArtifactsDirectory and System.DefaultWorkingDirectory.

      Example: `C:\agent\_work\r1\a` | -| Agent.RootDirectory | The working directory for this agent, where subfolders are created for every build or release. Same as Agent.WorkFolder and System.WorkFolder.

      Example: `C:\agent\_work` | -| Agent.WorkFolder | The working directory for this agent, where subfolders are created for every build or release. Same as Agent.RootDirectory and System.WorkFolder.

      Example: `C:\agent\_work` | -| Agent.DeploymentGroupId | The ID of the deployment group the agent is registered with. This is available only in deployment group jobs. Not available in TFS 2018 Update 1.

      Example: `1` | - - - -## General Artifact +## Use default variables -For each artifact that is referenced in a release, you can use the following artifact variables. -Not all variables are meaningful for each artifact type. The table below lists the default artifact -variables and provides examples of the values that they have depending on the artifact type. If an example is empty, -it implies that the variable is not populated for that artifact type. +You can use the default variables in two ways: as parameters to tasks in a release pipeline or within your scripts. -Replace the `{alias}` placeholder with the value you specified for the [artifact alias](artifacts.md#source-alias) or with the default value generated for the release pipeline. +You can use a default variable directly as an input to a task. For example, to pass `Release.Artifacts.{Artifact alias}.DefinitionName` as an argument to a PowerShell task for an artifact with *ASPNET4.CI* as its alias, you would use `$(Release.Artifacts.ASPNET4.CI.DefinitionName)`. -| Variable name | Description | -|---------------|-------------| -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.DefinitionId | The identifier of the build pipeline or repository.

      Azure Pipelines example: `1`
      GitHub example: `fabrikam/asp` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.DefinitionName | The name of the build pipeline or repository.

      Azure Pipelines example: `fabrikam-ci`
      TFVC example: `$/fabrikam`
      Git example: `fabrikam`
      GitHub example: `fabrikam/asp (main)` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.BuildNumber | The build number or the commit identifier.

      Azure Pipelines example: `20170112.1`
      Jenkins/TeamCity example: `20170112.1`
      TFVC example: `Changeset 3`
      Git example: `38629c964`
      GitHub example: `38629c964` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.BuildId | The build identifier.

      Azure Pipelines example: `130`
      Jenkins/TeamCity example: `130`
      GitHub example: `38629c964d21fe405ef830b7d0220966b82c9e11` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.BuildURI | The URL for the build.

      Azure Pipelines example: `vstfs://build-release/Build/130`
      GitHub example: `https://github.com/fabrikam/asp` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.SourceBranch | The full path and name of the branch from which the source was built.

      Azure Pipelines example: `refs/heads/main` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.SourceBranchName | The name only of the branch from which the source was built.

      Azure Pipelines example: `main` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.SourceVersion | The commit that was built.

      Azure Pipelines example: `bc0044458ba1d9298cdc649cb5dcf013180706f7` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.Repository.Provider | The type of repository from which the source was built.

      Azure Pipelines example: `Git` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.RequestedForID | The identifier of the account that triggered the build.

      Azure Pipelines example: `2f435d07-769f-4e46-849d-10d1ab9ba6ab` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.RequestedFor | The name of the account that requested the build.

      Azure Pipelines example: `Mateo Escobedo` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.Type | The type of artifact source, such as Build.

      Azure Pipelines example: `Build`
      Jenkins example: `Jenkins`
      TeamCity example: `TeamCity`
      TFVC example: `TFVC`
      Git example: `Git`
      GitHub example: `GitHub` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.PullRequest.TargetBranch | The full path and name of the branch that is the target of a pull request. This variable is initialized only if the release is triggered by a pull request flow.

      Azure Pipelines example: `refs/heads/main` | -| Release.Artifacts.{[alias](artifacts.md#source-alias)}.PullRequest.TargetBranchName | The name only of the branch that is the target of a pull request. This variable is initialized only if the release is triggered by a pull request flow.

      Azure Pipelines example: `main` | - -See also [Artifact source alias](artifacts.md#source-alias) - -## Primary Artifact - -You designate one of the artifacts as a primary artifact in a release pipeline. For the designated primary artifact, Azure Pipelines populates the following variables. - -| Variable name | Same as | -|---------------|---------| -| Build.DefinitionId | Release.Artifacts.{Primary artifact alias}.DefinitionId | -| Build.DefinitionName | Release.Artifacts.{Primary artifact alias}.DefinitionName | -| Build.BuildNumber | Release.Artifacts.{Primary artifact alias}.BuildNumber | -| Build.BuildId | Release.Artifacts.{Primary artifact alias}.BuildId | -| Build.BuildURI | Release.Artifacts.{Primary artifact alias}.BuildURI | -| Build.SourceBranch | Release.Artifacts.{Primary artifact alias}.SourceBranch | -| Build.SourceBranchName | Release.Artifacts.{Primary artifact alias}.SourceBranchName | -| Build.SourceVersion | Release.Artifacts.{Primary artifact alias}.SourceVersion | -| Build.Repository.Provider | Release.Artifacts.{Primary artifact alias}.Repository.Provider | -| Build.RequestedForID | Release.Artifacts.{Primary artifact alias}.RequestedForID | -| Build.RequestedFor | Release.Artifacts.{Primary artifact alias}.RequestedFor | -| Build.Type | Release.Artifacts.{Primary artifact alias}.Type | -| Build.PullRequest.TargetBranch | Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranch | -| Build.PullRequest.TargetBranchName | Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranchName | +:::image type="content" source="media/variables-01.png" alt-text="A screenshot displaying how to use a default variable as an argument."::: -## Use default variables +To use a default variable in your script, you must first replace the `.` in the default variable names with `_`. For example, to print the value of `Release.Artifacts.{Artifact alias}.DefinitionName` for an artifact with *ASPNET4.CI* as its alias in a PowerShell script, use `$env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME`. Note that the original alias, *ASPNET4.CI*, is replaced with *ASPNET4_CI*. -You can use the default variables in two ways - as parameters to tasks in a release pipeline or in your scripts. +:::image type="content" source="media/variables-02.png" alt-text="A screenshot displaying how to use a default variable in an inline PowerShell script."::: -You can directly use a default variable as an input to a task. -For example, to pass `Release.Artifacts.{Artifact alias}.DefinitionName` for the artifact source whose alias is **ASPNET4.CI** to a task, -you would use `$(Release.Artifacts.ASPNET4.CI.DefinitionName)`. +## Custom variables -![Using artifact variables in arguments to a PowerShell Script task](media/variables-01.png) +Custom variables can be defined at various scopes. -To use a default variable in your script, you must first replace the `.` in the default variable names with `_`. -For example, to print the value of artifact variable `Release.Artifacts.{Artifact alias}.DefinitionName` for the artifact source whose alias is **ASPNET4.CI** in a PowerShell script, -you would use `$env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME`. +- **Variable Groups**: Use variable groups to share values across all definitions in a project. This is useful when you want to use the same values throughout definitions, stages, and tasks within a project, and manage them from a single location. Define and manage variable groups in the **Pipelines** > **Library**. -![Using artifact variables in an inline PowerShell script](media/variables-02.png) +- **Release Pipeline Variables**: Use release pipeline variables to share values across all stages within a release pipeline. This is ideal for scenarios where you need a consistent value across stages and tasks, with the ability to update it from a single location. Define and manage these variables in the **Variables** tab of the release pipeline. In the Pipeline Variables page, set the **Scope** drop-down list to *Release* when adding a variable. -Note that the original name of the artifact source alias, `ASPNET4.CI`, is replaced by `ASPNET4_CI`. +- **Stage Variables**: Use stage variables to share values within a specific stage of a release pipeline. This is useful for values that differ from stage to stage but are consistent across all tasks within a stage. Define and manage these variables in the **Variables** tab of the release pipeline. In the Pipeline Variables page, set the **Scope** drop-down list to appropriate environment when adding a variable. + +Using custom variables at the project, release pipeline, and stage levels helps you to: - +- Avoid duplicating values, making it easier to update all occurrences with a single change. -### View the current values of all variables +- Secure sensitive values by preventing them from being viewed or modified by users. To mark a variable as secure (secret), select the ![padlock](media/padlock-icon.png) icon next to the variable. -1. Open the pipelines view of the summary for the release, and choose the stage you are interested in. - In the list of steps, choose **Initialize job**. + > [!IMPORTANT] + > The values of the hidden variables (secret) are securely stored on the server and cannot be viewed by users after they are saved. During deployment, Azure Pipelines decrypts these values when referenced by tasks and passes them to the agent over a secure HTTPS channel. - ![Opening the log for a release](media/view-variable-values-link.png) +> [!NOTE] +> Creating custom variables can overwrite standard variables. For example, if you define a custom **Path** variable on a Windows agent, it will overwrite the *$env:Path* variable, which may prevent PowerShell from running properly. -1. This opens the log for this step. Scroll down to see the values used by the agent for this job. +## Use custom variables - ![Viewing the values of the variables in a release](media/view-variable-values.png) +To use custom variables in your tasks, enclose the variable name in parentheses and precede it with a **$** character. For example, if you have a variable named *adminUserName*, you can insert its current value into a task as `$(adminUserName)`. - +> [!NOTE] +> Variables from different groups linked to a pipeline at the same scope (e.g., job or stage) may conflict, leading to unpredictable results. To avoid this, ensure that variables across all your variable groups have unique names. + +[!INCLUDE [set-variables-in-scripts](../includes/set-variables-in-scripts.md)] -### Run a release in debug mode +## View the current values of all variables -Show additional information as a release executes and in the log files -by running the entire release, or just the tasks in an individual -release stage, in debug mode. This can help you resolve issues and failures. +1. Select **Pipelines** > **Releases**, and then select your release pipeline. -* To initiate debug mode for an entire release, add a variable - named `System.Debug` with the value `true` to the **Variables** - tab of a release pipeline. +1. Open the summary view for your release, and select the stage you're interested in. In the list of steps, choose **Initialize job**. -* To initiate debug mode for a single stage, open the - **Configure stage** dialog from the shortcut menu - of the stage and add a variable named `System.Debug` - with the value `true` to the **Variables** tab. + :::image type="content" source="media/view-variable-values-link.png" alt-text="A screenshot displaying the initialize job step."::: -* Alternatively, create a [variable group](../library/variable-groups.md) - containing a variable named `System.Debug` with the value `true` - and link this variable group to a release pipeline. +1. This opens the logs for this step. Scroll down to see the values used by the agent for this job. -> [!TIP] -> If you get an error related to an Azure RM service connection, -see [How to: Troubleshoot Azure Resource Manager service connections](azure-rm-endpoint.md). + :::image type="content" source="media/view-variable-values.png" alt-text="A screenshot displaying the variables used by the agent."::: -## Custom variables +## Run a release in debug mode -Custom variables can be defined at various scopes. +Running a release in debug mode can help you diagnose and resolve issues or failures by displaying additional information during the release execution. You can enable debug mode for the entire release or just for the tasks within a specific release stage. -* Share values across all of the definitions - in a project by using [variable groups](../library/variable-groups.md). Choose a variable - group when you need to use the same values across all - the definitions, stages, and tasks in a project, and you want to be able to change - the values in a single place. You define and manage variable groups in the **Library** tab. - -* Share values across all of the stages by using - **release pipeline variables**. Choose a release pipeline - variable when you need to use the same value across all - the stages and tasks in the release pipeline, and you - want to be able to change the value in a single place. - You define and manage these variables in the **Variables** tab in a release pipeline. - In the Pipeline Variables page, open the Scope drop-down list and select "Release". - By default, when you add a variable, it is set to Release scope. - -* Share values across all of the tasks within one specific stage by using **stage variables**. - Use a stage-level variable for values that vary from stage to stage (and are the same for - all the tasks in an stage). You define and manage these variables in the **Variables** tab of a release pipeline. - In the Pipeline Variables page, open the Scope drop-down list and select the required stage. - When you add a variable, set the Scope to the appropriate environment. - -Using custom variables at project, release pipeline, and stage scope helps you to: +- To enable debug mode for an entire release, add a variable named `System.Debug` with the value `true` to the **Variables** tab of the release pipeline. -* Avoid duplication of values, making it easier to update - all occurrences as one operation. +- To enable debug mode for a specific stage, open the **Configure stage** dialog from the shortcut menu of the stage, and add a variable named `System.Debug` with the value `true` to the **Variables** tab. -* Store sensitive values in a way that they cannot be seen - or changed by users of the release pipelines. Designate a configuration property to be a secure (secret) variable by selecting the ![padlock](media/padlock-icon.png) (padlock) icon next to the variable. +- Alternatively, create a [variable group](../library/variable-groups.md) containing a variable named `System.Debug` with the value `true`, and link this variable group to the release pipeline. - > [!IMPORTANT] - > The values of the hidden (secret) variables are securely stored on - the server and cannot be viewed by users after they are saved. - During a deployment, the Azure Pipelines release service - decrypts these values when referenced by the tasks and passes them - to the agent over a secure HTTPS channel. +> [!TIP] +> If you encounter an error related to Azure ARM service connections, see [How to: Troubleshoot Azure Resource Manager service connections](azure-rm-endpoint.md) for more details. -> [!NOTE] -> Creating custom variables can overwrite standard variables. For example, the PowerShell **Path** environment variable. If you create a custom `Path` variable on a Windows agent, it will overwrite the `$env:Path` variable and PowerShell won't be able to run. +## Related content -## Use custom variables +- [Artifact sources in Classic release pipelines](artifacts.md) -To use custom variables in your build and release tasks, simply enclose the -variable name in parentheses and precede it with a **$** character. For example, -if you have a variable named **adminUserName**, you can insert the current -value of that variable into a parameter of a task as `$(adminUserName)`. +- [Deploy pull request Artifacts](deploy-pull-request-builds.md) -[!INCLUDE [variable-collision](../includes/variable-collision.md)] - -[!INCLUDE [set-variables-in-scripts](../includes/set-variables-in-scripts.md)] +- [Use variables in a variable group](../scripts/cli/pipeline-variable-group-secret-nonsecret-variables.md) diff --git a/docs/pipelines/release/visualize-release-test-progress.md b/docs/pipelines/release/visualize-release-test-progress.md deleted file mode 100644 index 740030c06ec..00000000000 --- a/docs/pipelines/release/visualize-release-test-progress.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Visualize release pipelines progress and test summary -description: View summary and progress of release pipelines and test results -ms.topic: conceptual -ms.author: rabououn -author: ramiMSFT -ms.date: 06/15/2021 -monikerRange: '<= azure-devops' ---- - -# View release progress and test summary - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Azure Pipelines provides a quick and easy way to check the status of your deployment and test results right from your pipeline definition page. The user interface provides a live update of deployment progress and easy access to logs for more details. - -::: moniker range=">= azure-devops-2019" - -## Visualize release progress - -The user interface provides a visual representation of the current status of the release pipeline, making it easier to understand what’s happening and surfaces appropriate details and actions at different stages of the deployment. - -:::image type="content" source="media/release-progress-devops.png" alt-text="View release progress status Azure DevOps Services"::: - -::: moniker-end - -::: moniker range="tfs-2018" - -## Visualize release progress - -The release progress view provides live updates of deployment progress and one-click access to further details. The user interface provides a visual representation of the current status of the release pipeline, making it easier to understand what’s happening and surfaces appropriate details and actions at different stages of the deployment. - -:::image type="content" source="media/release-progress-view.png" alt-text="User interface to view the release progress status"::: - -### Pre-deployment and post-deployment - -If pre-deployment or post-deployment conditions have been set for an environment, it is indicated on the environment with the presence of the approvals and gates. The progress of approvals and gates show up in the status of the environment as well. You can take action or view further details by clicking on the environment’s condition icon displayed on the right or left side of the environment. - -:::image type="content" source="media/pre-deployment-status.png" alt-text="Pre-deployment conditions - view status"::: - -You can also view the deployment gates status and a quick action buttons to view logs and debug issues if needed. - -:::image type="content" source="media/gates-status.png" alt-text="Deployment gates - view status"::: - -### Commits and work items - -With each new release, you can see the list of associated commits and work items for each environment separately by clicking on the environment. If the list is long, use filters to find a commit or work item you’re interested in. - -:::image type="content" source="media/commits-view.png" alt-text="View the list of commits for your release pipeline"::: - -### Deployment progress and logs - -The environments show live updates for in-progress deployments, including how many phases and tasks are complete and the running time. Clicking the environment status opens a view containing the logs, with focus on the what’s currently active. - -:::image type="content" source="media/release-progress-tfs.png" alt-text="Release progress - tasks view"::: - -You can also click into the logs to enter a focused view for each of the tasks. - -:::image type="content" source="media/release-focused-view.png" alt-text="View logs for a specific task"::: - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -## Review test summary - -During test execution, a test might spawn multiple instances of tests that contribute to the overall outcome. A few examples include: tests that rerun due to failures, tests composed of an ordered combination of other tests (for example, ordered test), or tests having different instances based on provided input parameter (data-driven tests). Since these tests are related, they need to be reported together with the overall outcome derived based on the individual test outcomes. The summary page provides insights on the result of the test runs related to your pipeline. - -:::image type="content" source="media/test-results.png" alt-text="Test results summary"::: - -> [!NOTE] -> Metrics in the test summary section (e.g. Total tests, Passed, etc.), are computed using the root level of the hierarchy rather than each individual iteration of the tests. - -::: moniker-end - -## Related articles - -- [Release pipelines overview](./index.md) -- [Classic release pipelines](./define-multistage-release-process.md) -- [Stage templates in Azure Pipelines](./env-templates.md) diff --git a/docs/pipelines/reports/media/pipelines-reports/duration-trend.png b/docs/pipelines/reports/media/pipelines-reports/duration-trend.png index aef95e4fb8f..0622342d9e8 100644 Binary files a/docs/pipelines/reports/media/pipelines-reports/duration-trend.png and b/docs/pipelines/reports/media/pipelines-reports/duration-trend.png differ diff --git a/docs/pipelines/reports/pipeline-widgets.md b/docs/pipelines/reports/pipeline-widgets.md new file mode 100644 index 00000000000..978ea68d581 --- /dev/null +++ b/docs/pipelines/reports/pipeline-widgets.md @@ -0,0 +1,38 @@ +--- +title: Monitor your pipelines with dashboard widgets +titleSuffix: Azure DevOps +description: Monitor your pipeline with widgets on your team dashboard in Azure DevOps. +ms.custom: pipelines +ms.author: chcomley +ms.topic: conceptual +monikerRange: '<= azure-devops' +ms.date: 08/11/2024 +--- + + +# Monitor your pipelines with dashboard widgets + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +You can monitor your pipelines by adding widgets to team dashboards in Azure DevOps. Widgets give you visibility to the status of your build and release pipelines and monitor test results trends. For information about team dashboards, see [About dashboards, charts, reports, and widgets](../../report/dashboards/overview.md). + +## Pipeline widgets + +The pipeline widgets include: + +- [Build history](../../report/dashboards/widget-catalog.md#build-history-widget): View the histogram of all the builds run for a build pipeline. +- [Deployment status](../../report/dashboards/widget-catalog.md#deployment-status-widget): View the status of the deployment status and test pass rate for a recent set of builds. +- [Release pipeline overview](../../report/dashboards/widget-catalog.md#release-definition-widget): View and track the status of a release pipeline. +- [Requirements quality](../../report/dashboards/widget-catalog.md#requirements-quality-widget): Track quality continuously from a build or release pipeline. +- [Test results trend](../../report/dashboards/widget-catalog.md#test-trend-results): View trends of test results for a build or release pipeline. +- [Test results trend (Advanced)](../../report/dashboards/analytics-widgets.md#test-results-trend-advanced): View trends of test results for multiple builds and releases in near real-time with Analytics. For more information about Analytics widgets, see [Analytics widgets](../../report/dashboards/analytics-widgets.md). + +## Manage your dashboard widgets + +To manage your dashboard widgets, see [Add a widget to a dashboard](../../report/dashboards/add-widget-to-dashboard.md). + +## Related articles + +- [Widget catalog](../../report/dashboards/widget-catalog.md) +- [Dashboards, charts, and quick reference](../../report/dashboards/quick-ref.md) +- [Add, rename, and delete dashboards in Azure DevOps](../../report/dashboards/dashboards.md) \ No newline at end of file diff --git a/docs/pipelines/reports/pipelinereport.md b/docs/pipelines/reports/pipelinereport.md index 1ebfe9a40f9..52dc001b3af 100644 --- a/docs/pipelines/reports/pipelinereport.md +++ b/docs/pipelines/reports/pipelinereport.md @@ -3,9 +3,9 @@ title: Pipeline reports description: Get meaningful insights with pipeline reports in the pipeline ms.assetid: 678DF283-CE38-4CAF-BA74-D331B357F510 ms.topic: conceptual -ms.custom: continuous-test, seodec18 +ms.custom: continuous-test ms.date: 08/21/2019 -monikerRange: '>=azure-devops-2019' +monikerRange: "<=azure-devops" --- # Pipeline reports @@ -14,26 +14,12 @@ monikerRange: '>=azure-devops-2019' Teams track their pipeline health and efficiency to ensure continuous delivery to their customers. You can gain visibility into your team's pipeline(s) using Pipeline analytics. The source of information for pipeline analytics is the set of runs for your pipeline. These analytics are accrued over a period of time, and form the basis of the rich insights offered. Pipelines reports show you metrics, trends, and can help you identify insights to improve the efficiency of your pipeline. -::: moniker range="azure-devops-2019" - -## Prerequisites - -Ensure that you have installed the [Analytics Marketplace extension](../../report/dashboards/analytics-extension.md) for Azure DevOps Server. - -::: moniker-end - -::: moniker range="azure-devops-2019 || azure-devops" +::: moniker range="=azure-devops" ## View pipeline reports ::: moniker-end -::: moniker range="azure-devops-2019" - -A summary of the pass rate can be viewed in the **Analytics** tab of a pipeline. To drill into the trend and insights, click on the card to view the full report. - -::: moniker-end - ::: moniker range="azure-devops" @@ -45,13 +31,6 @@ A summary of the pass rate and duration can be viewed in the **Analytics** tab o ::: moniker-end -::: moniker range="azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![View pipeline reports](media/pipelines-reports/analyticstab-server-2019.png) - -::: moniker-end - ::: moniker range="azure-devops" ## Pipeline pass rate report @@ -107,5 +86,4 @@ Pipelines reports can be further filtered by date range or branch. > [!div class="mx-imgBorder"] > ![View branch filter](media/pipelines-reports/branch-filter.png) - [!INCLUDE [help-and-support-footer](../test/includes/help-and-support-footer.md)] diff --git a/docs/pipelines/repos/azure-repos-git.md b/docs/pipelines/repos/azure-repos-git.md index 35ab1d9f793..81532076549 100644 --- a/docs/pipelines/repos/azure-repos-git.md +++ b/docs/pipelines/repos/azure-repos-git.md @@ -3,7 +3,6 @@ title: Build Azure Repos Git repositories description: Using an Azure Repos Git repository with Azure Pipelines ms.topic: reference ms.assetid: aa910a2f-b668-4a08-9ac0-adc5f9ae417a -ms.custom: seodec18 ms.date: 01/24/2023 monikerRange: '<= azure-devops' --- @@ -12,17 +11,13 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - Azure Pipelines can automatically build and validate every pull request and commit to your Azure Repos Git repository. ## Choose a repository to build # [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" You create a new pipeline by first selecting a repository and then a YAML file in that repository. The repository in which the YAML file is present is called `self` repository. By default, this is the repository that your pipeline builds. @@ -34,12 +29,6 @@ You can later configure your pipeline to check out a different repository or mul ::: moniker-end -::: moniker range="< azure-devops-2019" - -YAML pipelines aren't available in TFS. - -::: moniker-end - # [Classic](#tab/classic/) While creating a pipeline, to choose the repository to build, first select the project to which the repository belongs. Then, select the repository. @@ -75,10 +64,6 @@ Continuous integration (CI) triggers cause a pipeline to run whenever you push a [!INCLUDE [ci-triggers](includes/ci-triggers3.md)] -::: moniker range="< azure-devops-2019" -YAML pipelines aren't available in TFS. -::: moniker-end - # [Classic](#tab/classic/) [!INCLUDE [ci-triggers](includes/ci-triggers4.md)] @@ -89,13 +74,7 @@ YAML pipelines aren't available in TFS. ### Skipping CI for individual pushes -::: moniker range="<= azure-devops-2019" - -You can also tell Azure Pipelines to skip running a pipeline that a push would normally trigger. Just include `***NO_CI***` in the message of any of the commits that are part of a push, and Azure Pipelines will skip running CI for this push. - -::: moniker-end - -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" You can also tell Azure Pipelines to skip running a pipeline that a push would normally trigger. Just include `[skip ci]` in the message or description of any of the commits that are part of a push, and Azure Pipelines will skip running CI for this push. You can also use any of the following variations. @@ -126,7 +105,7 @@ If you have an open PR and you push changes to its source branch, multiple pipel > [!NOTE] > [Draft pull requests](../../repos/git/pull-requests.md#draft-pull-requests) do not trigger a pipeline even if you configure a branch policy. -::: moniker range=">tfs-2018" +::: moniker range="<=azure-devops" ### Validate contributions from forks @@ -172,7 +151,7 @@ If your Azure Repos Git repository is in a different project than your pipeline, ::: moniker-end -:::moniker range=">azure-devops-2019" +:::moniker range="<=azure-devops" For more information on **Limit job authorization scope**, see [Understand job access tokens](../process/access-tokens.md). @@ -255,7 +234,7 @@ steps: > For many scenarios, multi-repo checkout can be leveraged, removing the need to use scripts to check out additional repositories in your pipeline. For more information, see [Check out multiple repositories in your pipeline](multi-repo-checkout.md). ::: moniker-end -::: moniker range=">tfs-2018" +::: moniker range="<=azure-devops" [!INCLUDE [ci-triggers](includes/source-options.md)] diff --git a/docs/pipelines/repos/bitbucket.md b/docs/pipelines/repos/bitbucket.md index b51ca580d97..e7b1e53aba2 100644 --- a/docs/pipelines/repos/bitbucket.md +++ b/docs/pipelines/repos/bitbucket.md @@ -4,7 +4,7 @@ description: Using a Bitbucket Cloud repository with Azure Pipelines ms.topic: reference ms.author: vijayma author: vijayma -ms.date: 01/25/2023 +ms.date: 10/27/2023 monikerRange: azure-devops --- @@ -202,7 +202,7 @@ pr: none For more information, see [PR trigger](/azure/devops/pipelines/yaml-schema/pr) in the [YAML schema](/azure/devops/pipelines/yaml-schema). > [!NOTE] -> If your `pr` trigger isn't firing, ensure that you have not [overridden YAML PR triggers in the UI](../troubleshooting/troubleshooting.md#overridden-yaml-trigger-setting). +> If your `pr` trigger isn't firing, ensure that you have not [overridden YAML PR triggers in the UI](../troubleshooting/troubleshoot-triggers.md#overridden-yaml-trigger-setting). # [Classic](#tab/classic/) @@ -219,6 +219,10 @@ For included branches, a build will be triggered on each push to a pull request Learn more about [informational runs](../process/information-run.md). +## Limitations + +[!INCLUDE [bb-limitations](./includes/bb-limitations.md)] + ## FAQ Problems related to Bitbucket integration fall into the following categories: diff --git a/docs/pipelines/repos/github-enterprise.md b/docs/pipelines/repos/github-enterprise.md index 7d53efb7885..59f834d5422 100644 --- a/docs/pipelines/repos/github-enterprise.md +++ b/docs/pipelines/repos/github-enterprise.md @@ -86,6 +86,10 @@ If you want to set up YAML pipelines or if you want to enhance the experience wi To allow traffic from Azure DevOps to reach your GitHub Enterprise Server, add the IP addresses or service tags specified in [Inbound connections](../../organizations/security/allow-list-ip-url.md#inbound-connections) to your firewall's allowlist. If you use ExpressRoute, make sure to also include [ExpressRoute IP ranges](../../organizations/security/allow-list-ip-url.md#azure-devops-expressroute-connections) to your firewall's allowlist. +## Limitations + +[!INCLUDE [limitations](includes/limitations-gh.md)] + ## FAQ Problems related to GitHub Enterprise integration fall into the following categories: @@ -106,7 +110,7 @@ Problems related to GitHub Enterprise integration fall into the following catego [!INCLUDE [qa](includes/qa2-1.md)] -[!INCLUDE [qa](includes/qa3.md)] +[!INCLUDE [qa](includes/qa3-ghes.md)] ### Failing checkout diff --git a/docs/pipelines/repos/github.md b/docs/pipelines/repos/github.md index 9f3a3b15656..f4fb0b15176 100644 --- a/docs/pipelines/repos/github.md +++ b/docs/pipelines/repos/github.md @@ -5,7 +5,7 @@ ms.topic: reference ms.assetid: 96a52d0d-5e01-4b30-818d-1893387522cd ms.author: vijayma author: vijayma -ms.date: 01/25/2023 +ms.date: 12/11/2024 monikerRange: azure-devops --- @@ -137,7 +137,7 @@ To use the GitHub App, install it in your GitHub organization or user account fo After installation, the GitHub App will become Azure Pipelines' default method of authentication to GitHub (instead of OAuth) when pipelines are created for the repositories. -If you install the GitHub App for all repositories in a GitHub organization, you don't need to worry about Azure Pipelines sending mass emails or automatically setting up pipelines on your behalf. As an alternative to installing the app for all repositories, repository admins can install it one at a time for individual repositories. This requires more work for admins, but has no advantage nor disadvantage. +If you install the GitHub App for all repositories in a GitHub organization, you don't need to worry about Azure Pipelines sending mass emails or automatically setting up pipelines on your behalf. However, if the app is installed for all repositories, the token used by the application will have access to all repositories, including private ones. For security reasons, it is recommended to separate private and public repositories at the organization level. This means having a dedicated organization only for public projects without private repositories. If, for some reason, there is a need to have public and private repositories in the same organization, instead of using access for all repositories, explicitly select the repositories to which the application should have access. This requires more work for admins but ensures better security management. #### Permissions needed in GitHub @@ -393,9 +393,6 @@ For more information, see [PR trigger](/azure/devops/pipelines/yaml-schema/pr) i > [!NOTE] > If your `pr` trigger isn't firing, follow the troubleshooting steps in the [FAQ](#failing-triggers). ->[!NOTE] ->[Draft pull requests](https://docs.github.com/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests) do not trigger a pipeline. - # [Classic](#tab/classic/) Select the **Pull request validation** trigger and check the **Enable pull request validation** check box to enable builds on pull requests. @@ -477,7 +474,22 @@ To bypass this precaution on GitHub pipelines, enable the **Make secrets availab > It has more limited access to open resources than a normal access token. > To give fork builds the same permissions as regular builds, enable the **Make fork builds have the same permissions as regular builds** setting. -For more information, see [Repository protection - Forks](../security/repos.md#forks). +For more information, see [Repository protection - Forks](../security/misc.md#forks). + +You can define centrally how pipelines build PRs from forked GitHub repositories using the **Limit building pull requests from forked GitHub repositories** control. It's available at organization and project level. You can choose to: +- Disable building pull requests from forked repositories +- Securely build pull requests from forked repositories +- Customize rules for building pull requests from forked repositories + +:::image type="content" source="media/centralized-pipeline-control.png" alt-text="Screenshot of centralized control settings for how pipelines build PRs from forked GitHub repositories."::: + +Starting with [Sprint 229](/azure/devops/release-notes/2023/sprint-229-update), to improve the security of your pipelines, [Azure Pipelines no longer automatically builds pull requests from forked GitHub repositories](/azure/devops/release-notes/2023/sprint-229-update#building-prs-from-forked-github-repositories). For new projects and organizations, the default value of the **Limit building pull requests from forked GitHub repositories** setting is **Disable building pull requests from forked repositories**. + +When you choose the **Securely build pull requests from forked repositories** option, all pipelines, organization or project-wide, *cannot* make secrets available to builds of PRs from forked repositories, *cannot* make these builds have the same permissions as normal builds, and *must* be triggered by a PR comment. Projects can still decide to *not* allow pipelines to build such PRs. + +When you choose the **Customize** option, you can define how to restrict pipeline settings. For example, you can ensure that all pipelines require a comment in order to build a PR from a forked GitHub repo, when the PR belongs to non-team members and non-contributors. But, you can choose to allow them to make secrets available to such builds. Projects can decide to *not* allow pipelines to build such PRs, or to build them securely, or have even more restrictive settings than what is specified at the organization level. + +The control is off for existing organizations. [Starting September 2023, new organizations have **Securely build pull requests from forked repositories** turned on by default](/azure/devops/release-notes/2023/pipelines/sprint-227-update#build-github-repositories-securely-by-default). #### Important security considerations @@ -569,6 +581,10 @@ GitHub allows three options when one or more Check Runs fail for a PR/commit. Yo Clicking on the "Rerun" link next to the Check Run name will result in Azure Pipelines retrying the run that generated the Check Run. The resultant run will have the same run number and will use the same version of the source code, configuration, and YAML file as the initial build. Only those jobs that failed in the initial run and any dependent downstream jobs will be run again. Clicking on the "Rerun all failing checks" link will have the same effect. This is the same behavior as clicking "Retry run" in the Azure Pipelines UI. Clicking on "Rerun all checks" will result in a new run, with a new run number and will pick up changes in the configuration or YAML file. +## Limitations + +[!INCLUDE [limitations](includes/limitations-gh.md)] + ## FAQ Problems related to GitHub integration fall into the following categories: @@ -646,7 +662,7 @@ This means that your repository is already associated with a pipeline in a diffe [!INCLUDE [qa](includes/qa2-1.md)] -[!INCLUDE [qa](includes/qa3.md)] +[!INCLUDE [qa](includes/qa3-gh.md)] [!INCLUDE [qa](includes/qa4.md)] diff --git a/docs/pipelines/repos/includes/bb-limitations.md b/docs/pipelines/repos/includes/bb-limitations.md new file mode 100644 index 00000000000..6deb12081e4 --- /dev/null +++ b/docs/pipelines/repos/includes/bb-limitations.md @@ -0,0 +1,6 @@ +--- +ms.topic: include +ms.date: 10/27/2023 +--- + +Azure Pipelines loads a maximum of 2000 branches from a repository into dropdown lists in the Azure Devops Portal, for example into the **Default branch for manual and scheduled builds** setting, or when choosing a branch when running a pipeline manually. If you don't see your desired branch in the list, type the desired branch name manually. diff --git a/docs/pipelines/repos/includes/ci-triggers1.md b/docs/pipelines/repos/includes/ci-triggers1.md index a5b32b0403c..54951004e4f 100644 --- a/docs/pipelines/repos/includes/ci-triggers1.md +++ b/docs/pipelines/repos/includes/ci-triggers1.md @@ -4,12 +4,12 @@ ms.service: azure-devops-pipelines ms.manager: mijacobs ms.author: vijayma author: vijayma -ms.date: 09/02/2022 +ms.date: 12/18/2023 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -YAML pipelines are configured by default with a CI trigger on all branches. +YAML pipelines are configured by default with a CI trigger on all branches, unless the [Disable implied YAML CI trigger](/azure/devops/release-notes/2023/sprint-227-update#prevent-unintended-pipeline-runs) setting, introduced in [Azure DevOps sprint 227](/azure/devops/release-notes/2023/sprint-227-update), is enabled. The **Disable implied YAML CI trigger** setting can be configured at the organization level or at the project level. When the **Disable implied YAML CI trigger** setting is enabled, CI triggers for YAML pipelines are not enabled if the YAML pipeline doesn't have a `trigger` section. By default, **Disable implied YAML CI trigger** is not enabled. ### Branches @@ -58,7 +58,7 @@ trigger: - refs/tags/{othertagname} ``` -If you don't specify any triggers, the default is as if you wrote: +If you didn't specify any triggers, and the [Disable implied YAML CI trigger](/azure/devops/release-notes/2023/sprint-227-update#prevent-unintended-pipeline-runs) setting is not enabled, the default is as if you wrote: ```yaml trigger: @@ -116,11 +116,10 @@ When you specify paths, you must explicitly specify branches to trigger on if yo ::: moniker range="> azure-devops-2020" -Wilds cards are supported for path filters. For instance, you can include all paths that match `src/app/**/myapp*`. You can use wild card characters (`**`, `*`, or `?)` when specifying path filters. +Wildcards are supported for path filters. For instance, you can include all paths that match `src/app/**/myapp*`. You can use wildcard characters (`**`, `*`, or `?)` when specifying path filters. ::: moniker-end - * Paths are always specified relative to the root of the repository. * If you don't set path filters, then the root folder of the repo is implicitly included by default. * If you exclude a path, you cannot also include it unless you qualify it to a deeper folder. For example if you exclude _/tools_ then you could include _/tools/trigger-runs-on-these_ diff --git a/docs/pipelines/repos/includes/ci-triggers2.md b/docs/pipelines/repos/includes/ci-triggers2.md index 8ee2e8d14ec..bcbf586d59b 100644 --- a/docs/pipelines/repos/includes/ci-triggers2.md +++ b/docs/pipelines/repos/includes/ci-triggers2.md @@ -7,7 +7,7 @@ author: vijayma ms.date: 07/07/2022 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### Tags diff --git a/docs/pipelines/repos/includes/ci-triggers3.md b/docs/pipelines/repos/includes/ci-triggers3.md index 231ff6b777c..73847d6f8a3 100644 --- a/docs/pipelines/repos/includes/ci-triggers3.md +++ b/docs/pipelines/repos/includes/ci-triggers3.md @@ -7,7 +7,7 @@ author: vijayma ms.date: 07/07/2022 --- -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### Opting out of CI diff --git a/docs/pipelines/repos/includes/ci-triggers5.md b/docs/pipelines/repos/includes/ci-triggers5.md index 1905ca59055..7162dbf1c97 100644 --- a/docs/pipelines/repos/includes/ci-triggers5.md +++ b/docs/pipelines/repos/includes/ci-triggers5.md @@ -13,7 +13,7 @@ It is a common scenario to run different steps, jobs, or stages in your pipeline `condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))` -### Behavior of triggers when new branches are created +### Behavior of triggers when new branches are pushed It is common to configure multiple pipelines for the same repository. For instance, you may have one pipeline to build the docs for your app and another to build the source code. You may configure CI triggers with appropriate branch filters and path filters in each of these pipelines. For instance, you may want one pipeline to trigger when you push an update to the `docs` folder, and another one to trigger when you push an update to your application code. In these cases, you need to understand how the pipelines are triggered when a new branch is created. diff --git a/docs/pipelines/repos/includes/limitations-gh.md b/docs/pipelines/repos/includes/limitations-gh.md new file mode 100644 index 00000000000..0aee305701b --- /dev/null +++ b/docs/pipelines/repos/includes/limitations-gh.md @@ -0,0 +1,10 @@ +* For best performance, we recommend a maximum of 50 pipelines in a single repository. For acceptable performance, we recommend a maximum of 100 pipelines in a single repository. The time required to process a push to a repository increases with the number of pipelines in that repository. Whenever there's push to a repository, Azure Pipelines needs to load all YAML pipelines in that repository to figure out if any of them need to run, and loading each pipeline incurs a performance penalty. In addition to performance issues, having too many pipelines in a single repository can lead to throttling on GitHub's side, as Azure Pipelines may make too many requests in a short amount of time. +* The use of _extends_ and _include_ templates in a pipeline impacts the rate at which Azure Pipelines makes GitHub API requests and can lead to throttling on GitHub's side. Before running a pipeline, Azure Pipelines needs to generate the complete YAML code, so it needs to fetch all template files. +* Azure Pipelines loads a maximum of 2000 branches from a repository into dropdown lists in the Azure DevOps Portal, for example in the **Select a branch** window for the **Default branch for manual and scheduled builds** setting, or when choosing a branch when running a pipeline manually. + + If you don't see your desired branch in the list, type the desired branch name manually in the **Default branch for manual and scheduled builds** field. + + If you click the ellipsis and open the **Select a branch** dialogue and close it without choosing a valid branch from the drop-down list, you may see a **Some settings need attention** + message and a **This setting is required** message below **Default Branch for manual and scheduled builds**. To work around this message, reopen the pipeline and enter the name + directly in the **Default branch for manual and scheduled builds** field. + diff --git a/docs/pipelines/repos/includes/qa2.md b/docs/pipelines/repos/includes/qa2.md index 48a6710bdbd..54d10c136f1 100644 --- a/docs/pipelines/repos/includes/qa2.md +++ b/docs/pipelines/repos/includes/qa2.md @@ -7,11 +7,11 @@ author: vijayma ms.date: 07/07/2020 --- -#### I just created a new YAML pipeline with CI/PR triggers, but the pipeline is not being triggered. +#### I just created a new YAML pipeline with CI/PR triggers, but the pipeline isn't being triggered. Follow each of these steps to troubleshoot your failing triggers: -* Are your YAML CI or PR triggers being [overridden by pipeline settings in the UI](../../troubleshooting/troubleshooting.md#overridden-yaml-trigger-setting)? While editing your pipeline, choose **...** and then **Triggers**. +* Are your YAML CI or PR triggers [overridden by pipeline settings in the UI](../../troubleshooting/troubleshoot-triggers.md#overridden-yaml-trigger-setting)? While editing your pipeline, choose **...** and then **Triggers**. ![Pipeline settings UI.](../media/pipelines-options-for-git/yaml-pipeline-git-options-menu.png) diff --git a/docs/pipelines/repos/includes/qa3-gh.md b/docs/pipelines/repos/includes/qa3-gh.md new file mode 100644 index 00000000000..6b399348f76 --- /dev/null +++ b/docs/pipelines/repos/includes/qa3-gh.md @@ -0,0 +1,18 @@ +--- +ms.topic: include +ms.service: azure-devops-pipelines +ms.manager: mijacobs +ms.author: sandrica +author: silviu.andrica +ms.date: 07/07/2020 +--- + +#### My CI or PR triggers have been working fine. But, they stopped working now. + +First, go through the troubleshooting steps in the previous question, then follow these additional steps: + +* Do you have merge conflicts in your PR? For a PR that didn't trigger a pipeline, open it and check whether it has a merge conflict. Resolve the merge conflict. + +* Are you experiencing a delay in the processing of push or PR events? You can usually verify a delay by seeing if the issue is specific to a single pipeline or is common to all pipelines or repos in your project. If a push or a PR update to any of the repos exhibits this symptom, we might be experiencing delays in processing the update events. Here are some reasons why a delay may be happening: + * We are experiencing a service outage on our [status page](https://status.dev.azure.com/). If the status page shows an issue, then our team must have already started working on it. Check the page frequently for updates on the issue. + * Your repository contains too many YAML pipelines. For best performance, we recommend a maximum of 50 pipelines in a single repository. For acceptable performance, we recommend a maximum of 100 pipelines in a single repository. The more pipelines there are, the slower the processing of a push to that repository. Whenever there is push to a repository, Azure Pipelines needs to load all YAML pipelines in that repository, to figure out if any of them need to run, and each new pipeline incurs a performance penalty. diff --git a/docs/pipelines/repos/includes/qa3-ghes.md b/docs/pipelines/repos/includes/qa3-ghes.md new file mode 100644 index 00000000000..3742a5373d6 --- /dev/null +++ b/docs/pipelines/repos/includes/qa3-ghes.md @@ -0,0 +1,19 @@ +--- +ms.topic: include +ms.service: azure-devops-pipelines +ms.manager: mijacobs +ms.author: sandrica +author: silviu.andrica +ms.date: 07/07/2020 +--- + +#### My CI or PR triggers have been working fine. But, they stopped working now. + +First, go through the troubleshooting steps in the previous question, then follow these additional steps: + +* Do you have merge conflicts in your PR? For a PR that did not trigger a pipeline, open it and check whether it has a merge conflict. Resolve the merge conflict. + +* Are you experiencing a delay in the processing of push or PR events? You can usually verify a delay by seeing if the issue is specific to a single pipeline or is common to all pipelines or repos in your project. If a push or a PR update to any of the repos exhibits this symptom, we might be experiencing delays in processing the update events. Here are some reasons why a delay may be happening: + * We are experiencing a service outage on our [status page](https://status.dev.azure.com/). If the status page shows an issue, then our team must have already started working on it. Check the page frequently for updates on the issue. + * Your repository contains too many YAML pipelines. For best performance, we recommend a maximum of 50 pipelines in a single repository. For acceptable performance, we recommend a maximum of 100 pipelines in a single repository. The more pipelines there are, the slower the processing of a push to that repository. Whenever there is push to a repository, Azure Pipelines needs to load all YAML pipelines in that repository, to figure out if any of them need to run, and each new pipeline incurs a performance penalty. + * Your GitHub Enterprise Server instance may be underprovisioned, slowing down processing requests from Azure Pipelines. Read more about [hardware considerations](https://docs.github.com/en/enterprise-server@3.8/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-azure#hardware-considerations) for GitHub Enterprise Server. diff --git a/docs/pipelines/repos/includes/source-options.md b/docs/pipelines/repos/includes/source-options.md index c6d3b2b9a63..220f6e69139 100644 --- a/docs/pipelines/repos/includes/source-options.md +++ b/docs/pipelines/repos/includes/source-options.md @@ -9,26 +9,27 @@ ms.date: 06/04/2020 ## Checkout -When a pipeline is triggered, Azure Pipelines pulls your source code from the Azure Repos Git repository. You can control various aspects of how this happens. +When a pipeline is triggered, Azure Pipelines pulls your source code from the Azure Repos Git repository. You can control various aspects of how your code is checked out. > [!NOTE] > When you include a checkout step in your pipeline, we run the following command: `git -c fetch --force --tags --prune --prune-tags --progress --no-recurse-submodules origin --depth=1`. -If this does not meet your needs, you can choose to exclude built-in checkout by `checkout: none` and then use a script task to perform your own checkout. +If this default doesn't meet your needs, you can choose to exclude built-in checkout by `checkout: none` and then use a script task to perform your own checkout. + ### Preferred version of Git The Windows agent comes with its own copy of Git. If you prefer to supply your own Git rather than use the included copy, set `System.PreferGitFromPath` to `true`. -This setting is always true on non-Windows agents. +The `System.PreferGitFromPath` setting is always true on non-Windows agents. ### Checkout path # [YAML](#tab/yaml/) -If you are checking out a single repository, by default, your source code will be checked out into a directory called `s`. For YAML pipelines, you can change this by specifying `checkout` with a `path`. The specified path is relative to `$(Agent.BuildDirectory)`. For example: if the checkout path value is `mycustompath` and `$(Agent.BuildDirectory)` is `C:\agent\_work\1`, then the source code will be checked out into `C:\agent\_work\1\mycustompath`. +If you're checking out a single repository, by default, your source code is checked out into a directory called `s`. For YAML pipelines, you can change this by specifying `checkout` with a `path`. The specified path is relative to `$(Agent.BuildDirectory)`. For example: if the checkout path value is `mycustompath` and `$(Agent.BuildDirectory)` is `C:\agent\_work\1`, then the source code is checked out into `C:\agent\_work\1\mycustompath`. -If you are using multiple `checkout` steps and checking out multiple repositories, and not explicitly specifying the folder using `path`, each repository is placed in a subfolder of `s` named after the repository. For example if you check out two repositories named `tools` and `code`, the source code will be checked out into `C:\agent\_work\1\s\tools` and `C:\agent\_work\1\s\code`. +If you're using multiple `checkout` steps and checking out multiple repositories, and not explicitly specifying the folder using `path`, each repository is placed in a subfolder of `s` named after the repository. For example if you check out two repositories named `tools` and `code`, the source code is checked out into `C:\agent\_work\1\s\tools` and `C:\agent\_work\1\s\code`. -Please note that the checkout path value cannot be set to go up any directory levels above `$(Agent.BuildDirectory)`, so `path\..\anotherpath` will result in a valid checkout path (i.e. `C:\agent\_work\1\anotherpath`), but a value like `..\invalidpath` will not (i.e. `C:\agent\_work\invalidpath`). +Please note that the checkout path value can't be set to go up any directory levels above `$(Agent.BuildDirectory)`, so `path\..\anotherpath` will result in a valid checkout path (i.e. `C:\agent\_work\1\anotherpath`), but a value like `..\invalidpath` will not (i.e. `C:\agent\_work\invalidpath`). You can configure the `path` setting in the [Checkout](/azure/devops/pipelines/yaml-schema/steps-checkout) step of your pipeline. @@ -45,7 +46,7 @@ steps: # [Classic](#tab/classic/) -This setting is not configurable in the classic editor. Your source code will be checked out into a directory called `s`, which is relative to `$(Agent.BuildDirectory)`. For example: if `$(Agent.BuildDirectory)` is `C:\agent\_work\1`, then the source code will be checked out into `C:\agent\_work\1\mycustompath`. +The path setting isn't configurable in the classic editor. Your source code is checked out into a directory called `s`, which is relative to `$(Agent.BuildDirectory)`. For example: if `$(Agent.BuildDirectory)` is `C:\agent\_work\1`, then the source code is checked out into `C:\agent\_work\1\mycustompath`. --- @@ -68,7 +69,7 @@ steps: # [Classic](#tab/classic/) -You can configure the **Submodules** setting from the properties of the **Get sources** task in your pipeline if you want to download files from [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules). +You can configure the **Submodules** setting from the properties of the `Get sources` task in your pipeline if you want to download files from [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules). ![Configure Submodules setting.](../media/github/github-options.png) @@ -95,7 +96,7 @@ The build pipeline will check out your Git submodules as long as they are: In some cases you can't use the **Checkout submodules** option. You might have a scenario where a different set of credentials are needed to access the submodules. -This can happen, for example, if your main repository and submodule repositories aren't stored in the same Azure DevOps organization, or if your job access token does not have access to the repository in a different project. +This can happen, for example, if your main repository and submodule repositories aren't stored in the same Azure DevOps organization, or if your job access token doesn't have access to the repository in a different project. If you can't use the **Checkout submodules** option, then you can instead use a custom script step to fetch submodules. First, get a personal access token (PAT) and prefix it with `pat:`. @@ -115,11 +116,12 @@ Use that variable to populate the secret in the above Git command. > **Q: Why can't I use a Git credential manager on the agent?** **A:** Storing the submodule credentials in a Git credential manager installed on your private build agent is usually not effective as the credential manager may prompt you to re-enter the credentials whenever the submodule is updated. This isn't desirable during automated builds when user interaction isn't possible. -:::moniker range="azure-devops" - ### Sync tags -The checkout step uses the `--tags` option when fetching the contents of a Git repository. This causes the server to fetch all tags as well as all objects that are pointed to by those tags. This increases the time to run the task in a pipeline, particularly if you have a large repository with a number of tags. Furthermore, the checkout step syncs tags even when you enable the shallow fetch option, thereby possibly defeating its purpose. To reduce the amount of data fetched or pulled from a Git repository, Microsoft has added a new option to checkout to control the behavior of syncing tags. This option is available both in classic and YAML pipelines. +> [!IMPORTANT] +> The sync tags feature is supported in Azure Repos Git with Azure DevOps Server 2022.1 and higher. + +The checkout step uses the `--tags` option when fetching the contents of a Git repository. This causes the server to fetch all tags as well as all objects that are pointed to by those tags. This increases the time to run the task in a pipeline, particularly if you have a large repository with a number of tags. Furthermore, the checkout step syncs tags even when you enable the shallow fetch option, thereby possibly defeating its purpose. To reduce the amount of data fetched or pulled from a Git repository, Microsoft has added a new option to check out to control the behavior of syncing tags. This option is available both in classic and YAML pipelines. Whether to synchronize tags when checking out a repository can be configured in YAML by setting the `fetchTags` property, and in the UI by configuring the **Sync tags** setting. @@ -141,7 +143,7 @@ You can also configure this setting by using the **Sync tags** option in the pip :::image type="content" source="../media/more-actions-triggers.png" alt-text="Screenshot of more triggers menu."::: -2. Choose **YAML**, **Get sources**. +2. Choose **YAML**, `Get sources`. :::image type="content" source="../media/yaml-get-sources.png" alt-text="Screenshot of Get sources."::: @@ -154,7 +156,7 @@ You can also configure this setting by using the **Sync tags** option in the pip # [Classic](#tab/classic/) -You can configure the **Sync tags** setting from the properties of the **Get sources** task in your pipeline. +You can configure the **Sync tags** setting from the properties of the `Get sources` task in your pipeline. :::image type="content" source="../media/github/github-options.png" alt-text="Screenshot of Git sources options."::: @@ -168,14 +170,14 @@ You can configure the **Sync tags** setting from the properties of the **Get sou > [!NOTE] > If you explicitly set `fetchTags` in your `checkout` step, that setting takes priority over the setting configured in the pipeline settings UI. -:::moniker-end - ### Shallow fetch You may want to limit how far back in history to download. Effectively this results in `git fetch --depth=n`. If your repository is large, this option might make your build pipeline more efficient. Your repository might be large if it has been in use for a long time and has sizeable history. It also might be large if you added and later deleted large files. -> [!IMPORTANT] -> New pipelines created after the [September 2022 Azure DevOps sprint 209 update](/azure/devops/release-notes/2022/sprint-209-update) have **Shallow fetch** enabled by default and configured with a depth of 1. Previously the default was not to shallow fetch. To check your pipeline, view the **Shallow fetch** setting in the pipeline settings UI as described in the following section. +> [!NOTE] +> In some organizations, new pipelines created after the [September 2022 Azure DevOps sprint 209 update](/azure/devops/release-notes/2022/sprint-209-update) have **Shallow fetch** enabled by default and configured with a depth of 1. Previously the default wasn't to shallow fetch. +> +> To check your pipeline, view the **Shallow fetch** setting in the pipeline settings UI as described in the following section. # [YAML](#tab/yaml/) @@ -198,7 +200,7 @@ You can also configure fetch depth by setting the **Shallow depth** option in th :::image type="content" source="../media/more-actions-triggers.png" alt-text="Screenshot of more triggers menu."::: -2. Choose **YAML**, **Get sources**. +2. Choose **YAML**, `Get sources`. :::image type="content" source="../media/yaml-get-sources.png" alt-text="Screenshot of Get sources."::: @@ -211,7 +213,7 @@ You can also configure fetch depth by setting the **Shallow depth** option in th # [Classic](#tab/classic/) -You can configure the **Shallow fetch** setting from the properties of the **Get sources** task in your pipeline. +You can configure the **Shallow fetch** setting from the properties of the `Get sources` task in your pipeline. :::image type="content" source="../media/github/github-options.png" alt-text="Screenshot of Git sources options."::: @@ -245,7 +247,7 @@ steps: # [Classic](#tab/classic/) -Select the **Don't sync sources** setting from the properties of the **Get sources** task in your pipeline. +Select the **Don't sync sources** setting from the properties of the `Get sources` task in your pipeline. ![Select the Don't sync sources setting.](../media/github/github-options.png) @@ -259,7 +261,7 @@ Select the **Don't sync sources** setting from the properties of the **Get sourc [!INCLUDE [include](build-clean-intro.md)] > [!NOTE] -> Cleaning is not effective if you're using a [Microsoft-hosted agent](../../agents/hosted.md) because you'll get a new agent every time. +> Cleaning isn't effective if you're using a [Microsoft-hosted agent](../../agents/hosted.md) because you'll get a new agent every time. # [YAML](#tab/yaml/) @@ -303,7 +305,7 @@ This gives the following clean options. # [Classic](#tab/classic/) -Select the **Clean** setting from the properties of the **Get sources** task in your pipeline and select one of the following options. +Select the **Clean** setting from the properties of the `Get sources` task in your pipeline and select one of the following options. ![Select the Clean setting.](../media/github/github-clean-sources.png) @@ -331,13 +333,13 @@ You can't currently configure this setting in YAML but you can in the classic ed ![Configure Git options, YAML.](../media/pipelines-options-for-git/yaml-pipeline-git-options-menu.png) -From the classic editor, choose **YAML**, choose the **Get sources** task, and then configure the desired properties there. +From the classic editor, choose **YAML**, choose the `Get sources` task, and then configure the desired properties there. ![From the Classic editor, choose YAML > Get sources.](../media/pipelines-options-for-git/yaml-pipeline-git-options.png) # [Classic](#tab/classic) -You can configure the **Tag sources** setting from the properties of the **Get sources** task in your pipeline. +You can configure the **Tag sources** setting from the properties of the `Get sources` task in your pipeline. ![Configure Git options, Classic.](../media/github/github-options.png) @@ -351,8 +353,8 @@ $(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.BuildId)_$(Build.Buil The first four variables are predefined. `My.Variable` can be defined by you on the [variables tab](../../build/variables.md). -The build pipeline labels your sources with a [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). +The pipeline labels your sources with a [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). -Some build variables might yield a value that is not a valid label. For example, variables such as `$(Build.RequestedFor)` and `$(Build.DefinitionName)` can contain white space. If the value contains white space, the tag is not created. +Some build variables might yield a value that isn't a valid label. For example, variables such as `$(Build.RequestedFor)` and `$(Build.DefinitionName)` can contain white space. If the value contains white space, the tag isn't created. After the sources are tagged by your build pipeline, an artifact with the Git ref `refs/tags/{tag}` is automatically added to the completed build. This gives your team additional traceability and a more user-friendly way to navigate from the build to the code that was built. The tag is considered a build artifact since it is produced by the build. When the build is deleted either manually or through a retention policy, the tag is also deleted. diff --git a/docs/pipelines/repos/index.md b/docs/pipelines/repos/index.md index b6dbde01603..61b9679ddf6 100644 --- a/docs/pipelines/repos/index.md +++ b/docs/pipelines/repos/index.md @@ -11,20 +11,16 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end +Azure Pipelines and Azure DevOps Server integrate with a number of version control systems. When you use any of these version control systems, you can configure a pipeline to build, test, and deploy your application. -Azure Pipelines, Azure DevOps Server, and TFS integrate with a number of version control systems. When you use any of these version control systems, you can configure a pipeline to build, test, and deploy your application. +YAML pipelines only work with certain version control systems. The following table shows all the supported version control systems and the ones that support YAML pipelines. -YAML pipelines are a new form of pipelines that have been introduced in Azure DevOps Server 2019 and in Azure Pipelines. YAML pipelines only work with certain version control systems. The following table shows all the supported version control systems and the ones that support YAML pipelines. - -| Repository type | Azure Pipelines (YAML) | Azure Pipelines (classic editor) | Azure DevOps Server 2022, 2020, 2019, TFS 2018 | +| Repository type | Azure Pipelines (YAML) | Azure Pipelines (classic editor) | Azure DevOps Server 2022, 2020, 2019 | |---|---|---|---| | [Azure Repos Git](azure-repos-git.md) | Yes | Yes | Yes | | [Azure Repos TFVC](tfvc.md) | No | Yes | Yes | | [GitHub](github.md) | Yes | Yes | No | -| [GitHub Enterprise Server](github-enterprise.md) | Yes | Yes | TFS 2018.2 and higher | +| [GitHub Enterprise Server](github-enterprise.md) | Yes | Yes | Yes | | [Bitbucket Cloud](bitbucket.md) | Yes | Yes | No | | [Bitbucket Server](on-premises-bitbucket.md) | No | Yes | Yes | | Subversion | No | Yes | Yes | diff --git a/docs/pipelines/repos/media/centralized-pipeline-control.png b/docs/pipelines/repos/media/centralized-pipeline-control.png new file mode 100644 index 00000000000..1fcc4d3a72b Binary files /dev/null and b/docs/pipelines/repos/media/centralized-pipeline-control.png differ diff --git a/docs/pipelines/repos/multi-repo-checkout.md b/docs/pipelines/repos/multi-repo-checkout.md index c218009e792..9c3704ad9f8 100644 --- a/docs/pipelines/repos/multi-repo-checkout.md +++ b/docs/pipelines/repos/multi-repo-checkout.md @@ -3,7 +3,7 @@ title: Check out multiple repositories in your pipeline description: Learn how to check out multiple repositories in your pipeline ms.topic: reference ms.date: 01/25/2023 -monikerRange: "> azure-devops-2019" +monikerRange: "<=azure-devops" --- # Check out multiple repositories in your pipeline @@ -164,7 +164,6 @@ steps: If the `self` repository is named `CurrentRepo`, the `script` command produces the following output: `CurrentRepo MyAzureReposGitRepo MyBitbucketRepo MyGitHubRepo`. In this example, the names of the repositories (as specified by the `name` property in the repository resource) are used for the folders, because no `path` is specified in the checkout step. For more information on repository folder names and locations, see the following [Checkout path](#checkout-path) section. - ## Inline syntax checkout If your repository doesn't require a service connection, you can declare it inline with your `checkout` step. @@ -174,11 +173,14 @@ If your repository doesn't require a service connection, you can declare it inli ```yaml steps: +- checkout: self - checkout: git://MyProject/MyRepo # Azure Repos Git repository in the same organization ``` > [!NOTE] -> In the previous example, the `self` repository is not checked out. If you specify any `checkout` steps, you must include `checkout: self` in order for `self` to be checked out. +> In the previous example, the `self` checkout repository is specified in order to checkout the source of the repository associated with the pipeline. +> +> If you are using the default Azure Repos Git repository (that has the same name as the project), use the format `- checkout: git://MyProject/MyRepo`. ## Checkout path @@ -196,6 +198,22 @@ If a `path` is specified for a `checkout` step, that path is used, relative to ` > [!NOTE] > If you are using default paths, adding a second repository `checkout` step changes the default path of the code for the first repository. For example, the code for a repository named `tools` would be checked out to `C:\agent\_work\1\s` when `tools` is the only repository, but if a second repository is added, `tools` would then be checked out to `C:\agent\_work\1\s\tools`. If you have any steps that depend on the source code being in the original location, those steps must be updated. +## Workspace repository + +When multiple `checkout` steps (and different paths for each) are used in your pipeline, you may want to use the root directory of one the repositories as the default working directory. If so, you can set the `workspaceRepo` input to `true` for the related `checkout` step. + +```yaml +- checkout: git://project/first + path: repo/first-repo + +- checkout: git://project/second + path: repo/second-repo + workspaceRepo: true + +- pwsh: pwd +# Expected output: $(Pipeline.Workspace)/repo/second-repo +``` + ## Checking out a specific ref The default branch is checked out unless you designate a specific ref. @@ -248,7 +266,7 @@ You can trigger a pipeline when an update is pushed to the `self` repository or - You keep your YAML file in a separate repository from the application code. You want to trigger the pipeline every time an update is pushed to the application repository. > [!IMPORTANT] -> Repository resource triggers only work for Azure Repos Git repositories in the same organization at present. They do not work for GitHub or Bitbucket repository resources. +> Repository resource triggers only work for Azure Repos Git repositories in the same organization and when the `self` repository type is Azure Repos Git. They do not work for GitHub or Bitbucket repository resources. > > `batch` is not supported in repository resource triggers. diff --git a/docs/pipelines/repos/on-premises-bitbucket.md b/docs/pipelines/repos/on-premises-bitbucket.md index 22d55dd9e2a..d15c2927379 100644 --- a/docs/pipelines/repos/on-premises-bitbucket.md +++ b/docs/pipelines/repos/on-premises-bitbucket.md @@ -2,7 +2,7 @@ title: Build code from on-premises Bitbucket server description: Using on-premises Bitbucket with Azure Pipelines ms.topic: reference -ms.date: 01/25/2023 +ms.date: 10/27/2023 monikerRange: 'azure-devops' --- @@ -13,14 +13,14 @@ monikerRange: 'azure-devops' > [!NOTE] > To integrate Bitbucket Cloud with Azure Pipelines, see [Bitbucket Cloud](bitbucket.md). -You can integrate your on-premises Bitbucket server or another Git server with Azure Pipelines. Your on-premises server may be exposed to the Internet or it may not be. +You can integrate your on-premises Bitbucket server or another Git server with Azure Pipelines. Your on-premises server might be exposed to the Internet or it might not be. If your on-premises server is reachable from the servers that run Azure Pipelines service, then: - you can set up classic build and configure CI triggers -If your on-premises server is not reachable from the servers that run Azure Pipelines service, then: +If your on-premises server isn't reachable from the servers that run Azure Pipelines service, then: - you can set up classic build pipelines and start manual builds -- you cannot configure CI triggers +- you can't configure CI triggers > [!NOTE] > YAML pipelines do not work with on-premises Bitbucket repositories. @@ -34,23 +34,23 @@ If your on-premises server is reachable from the hosted agents, then you can use If your on-premises Bitbucket server is reachable from Azure Pipelines service, create a **[Other Git](../library/service-endpoints.md#other-git-service-connection)** service connection and use that to create a pipeline. Check the option to **Attempt accessing this Git server from Azure Pipelines**. -CI triggers work through polling and not through webhooks. In other words, Azure Pipelines periodically checks the Bitbucket server if there are any updates to code. If there are, then Azure Pipelines will start a new run. +CI triggers work through polling and not through webhooks. In other words, Azure Pipelines periodically checks the Bitbucket server if there are any updates to code. If there are, then Azure Pipelines starts a new run. ### Not reachable from Azure Pipelines -If the Bitbucket server cannot be reached from Azure Pipelines, you have two options: +If the Bitbucket server can't be reached from Azure Pipelines, you have two options: * Work with your IT department to open a network path between Azure Pipelines and on-premises Git server. For example, you can add exceptions to your firewall rules to allow traffic from Azure Pipelines to flow through. See the section on [Azure DevOps IPs](#azure-devops-ip-addresses) to see which IP addresses you need to allow. Furthermore, you need to have a public DNS entry for the Bitbucket server so that Azure Pipelines can resolve the FQDN of your server to an IP address. -* You can use a **[Other Git](../library/service-endpoints.md#other-git-service-connection)** connection but tell Azure Pipelines not to **attempt accessing this Git server from Azure Pipelines**. CI and PR triggers will not work in this configuration. You can only start manual or scheduled pipeline runs. +* You can use a **[Other Git](../library/service-endpoints.md#other-git-service-connection)** connection but tell Azure Pipelines not to **attempt accessing this Git server from Azure Pipelines**. CI and PR triggers aren't available with **Other Git** repositories. You can only start manual or scheduled pipeline runs. ### Reachable from Microsoft-hosted agents -Another decision you possibly have to make is whether to use Microsoft-hosted agents or self-hosted agents to run your pipelines. This often comes down to whether Microsoft-hosted agents can reach your server. To check whether they can, create a pipeline to use Microsoft-hosted agents and make sure to add a step to check out source code from your server. If this passes, then you can continue using Microsoft-hosted agents. +Another decision you possibly have to make is whether to use Microsoft-hosted agents or self-hosted agents to run your pipelines. This choice often depends on to whether Microsoft-hosted agents can reach your server. To check whether they can, create a pipeline to use Microsoft-hosted agents and make sure to add a step to check out source code from your server. If this passes, then you can continue using Microsoft-hosted agents. ### Not reachable from Microsoft-hosted agents -If the simple test pipeline mentioned in the above section fails with the error `TF401019: The Git repository with name or identifier does not exist or you do not have permissions for the operation you are attempting`, then the Bitbucket server is not reachable from Microsoft-hosted agents. This is again probably caused by a firewall blocking traffic from these servers. You have two options in this case: +If the simple test pipeline mentioned in the above section fails with the error `TF401019: The Git repository with name or identifier does not exist or you do not have permissions for the operation you are attempting`, then the Bitbucket server isn't reachable from Microsoft-hosted agents. This is again probably caused by a firewall blocking traffic from these servers. You have two options in this case: * Work with your IT department to open a network path between Microsoft-hosted agents and Bitbucket server. See the section on [networking](../agents/hosted.md#agent-ip-ranges) in Microsoft-hosted agents. @@ -58,12 +58,12 @@ If the simple test pipeline mentioned in the above section fails with the error ## Azure DevOps IP addresses -When you use **Other Git** connection to set up a classic pipeline, disable communication between Azure Pipelines service and Bitbucket server, and use self-hosted agents to build code, you will get a degraded experience: +When you use **Other Git** connection to set up a classic pipeline, disable communication between Azure Pipelines service and Bitbucket server, and use self-hosted agents to build code, you get a degraded experience: -* You will have to type in the name of the repository manually during pipeline creation -* You cannot use CI triggers as Azure Pipelines won't be able to poll for changes to the code -* You cannot use scheduled triggers with the option to build only when there are changes -* You cannot view information about the latest commit in the user interface +* You have to type in the name of the repository manually during pipeline creation +* You can't use CI triggers as Azure Pipelines won't be able to poll for changes to the code +* You can't use scheduled triggers with the option to build only when there are changes +* You can't view information about the latest commit in the user interface If you want to enhance this experience, it is important that you enable communication from Azure Pipelines to Bitbucket Server. @@ -76,20 +76,24 @@ Allow Azure Pipelines to attempt accessing the Git server in the **Other Git** s Learn more about [informational runs](../process/information-run.md). +## Limitations + +[!INCLUDE [bb-limitations](./includes/bb-limitations.md)] + ## FAQ Problems related to Bitbucket Server integration fall into the following categories: -* **[Failing triggers](#failing-triggers):** My pipeline is not being triggered when I push an update to the repo. +* **[Failing triggers](#failing-triggers):** My pipeline isn't being triggered when I push an update to the repo. * **[Failing checkout](#failing-checkout):** My pipeline is being triggered, but it fails in the checkout step. ### Failing triggers -#### I pushed a change to my server, but the pipeline is not being triggered. +#### I pushed a change to my server, but the pipeline isn't being triggered. Follow each of these steps to troubleshoot your failing triggers: -* Is your Bitbucket server accessible from Azure Pipelines? Azure Pipelines periodically polls Bitbucket server for changes. If the Bitbucket server is behind a firewall, this traffic may not reach your server. See [Azure DevOps IP Addresses](#azure-devops-ip-addresses) and verify that you have granted exceptions to all the required IP addresses. These IP addresses may have changed since you have originally set up the exception rules. You can only start manual runs if you used an external Git connection and if your server is not accessible from Azure Pipelines. +* Is your Bitbucket server accessible from Azure Pipelines? Azure Pipelines periodically polls Bitbucket server for changes. If the Bitbucket server is behind a firewall, this traffic might not reach your server. For more information, see [Azure DevOps IP Addresses](#azure-devops-ip-addresses) and verify that you have granted exceptions to all the required IP addresses. These IP addresses might have changed since you have originally set up the exception rules. You can only start manual runs if you used an external Git connection and if your server isn't accessible from Azure Pipelines. * Is your pipeline paused or disabled? Open the editor for the pipeline, and then select **Settings** to check. If your pipeline is paused or disabled, then triggers do not work. @@ -97,14 +101,14 @@ Follow each of these steps to troubleshoot your failing triggers: #### I did not push any updates to my code, however the pipeline is still being triggered. -* The continuous integration trigger for Bitbucket works through polling. After each polling interval, Azure Pipelines attempts to contact the Bitbucket server to check if there have been any updates to the code. If Azure Pipelines is unable to reach the Bitbucket server (possibly due to a network issue), then we start a new run anyway assuming that there might have been code changes. When Azure Pipelines cannot retrieve a YAML pipeline's code, it will create an [informational run](../process/information-run.md). +* The continuous integration trigger for Bitbucket works through polling. After each polling interval, Azure Pipelines attempts to contact the Bitbucket server to check if there have been any updates to the code. If Azure Pipelines is unable to reach the Bitbucket server (possibly due to a network issue), then we start a new run anyway assuming that there might have been code changes. When Azure Pipelines can't retrieve a YAML pipeline's code, it will create an [informational run](../process/information-run.md). ### Failing checkout #### When I attempt to start a new run manually, there is a delay of 4-8 minutes before it starts. -* Your Bitbucket server is not reachable from Azure Pipelines. Make sure that you have not selected the option to **attempt accessing this Git server from Azure Pipelines** in the Bitbucket service connection. If that option is selected, Azure Pipelines will attempt to contact to your server and since your server is unreachable, it eventually times out and starts the run anyway. Unchecking that option speeds up your manual runs. +* Your Bitbucket server isn't reachable from Azure Pipelines. Make sure that you have not selected the option to **attempt accessing this Git server from Azure Pipelines** in the Bitbucket service connection. If that option is selected, Azure Pipelines will attempt to contact to your server and since your server is unreachable, it eventually times out and starts the run anyway. Unchecking that option speeds up your manual runs. -#### The checkout step fails with the error that the server cannot be resolved. +#### The checkout step fails with the error that the server can't be resolved. -Do you use Microsoft-hosted agents? If so, these agents may not be able to reach your Bitbucket server. See [Not reachable from Microsoft-hosted agents](#not-reachable-from-microsoft-hosted-agents) for more information. +Do you use Microsoft-hosted agents? If so, these agents might not be able to reach your Bitbucket server. See [Not reachable from Microsoft-hosted agents](#not-reachable-from-microsoft-hosted-agents) for more information. diff --git a/docs/pipelines/repos/pipeline-options-for-git.md b/docs/pipelines/repos/pipeline-options-for-git.md index 796bbbfb166..50d072e5202 100644 --- a/docs/pipelines/repos/pipeline-options-for-git.md +++ b/docs/pipelines/repos/pipeline-options-for-git.md @@ -3,7 +3,6 @@ title: Options for Git repositories description: Options available when using a Git repository with Azure Pipelines ms.topic: reference ms.assetid: a74b3efe-d7bd-438a-be32-47d036556f74 -ms.custom: seodec18 ms.date: 01/25/2023 monikerRange: '<= azure-devops' --- @@ -12,10 +11,6 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - While editing a pipeline that uses a Git repo—in an Azure DevOps project, GitHub, GitHub Enterprise Server, Bitbucket Cloud, or another Git repo—you have the following options. | Feature | Azure Pipelines | Azure DevOps Server 2019 and higher | TFS 2018 | @@ -30,11 +25,9 @@ While editing a pipeline that uses a Git repo—in an Azure DevOps project, | Don't sync sources | Yes | Yes | Yes | | Shallow fetch | Yes | Yes | Yes | - > [!NOTE] > Click **Advanced settings** in the **Get Sources** task to see some of the above options. - ## Branch This is the branch that you want to be the default when you manually queue this build. If you set a scheduled trigger for the build, this is the branch from which your build will get the latest sources. The default branch has no bearing when the build is triggered through continuous integration (CI). Usually you'll set this to be the same as the default branch of the repository (for example, "master"). @@ -58,7 +51,7 @@ This is the branch that you want to be the default when you manually queue this #### [YAML](#tab/yaml/) -:::moniker range=">=azure-devops-2019" +:::moniker range="<=azure-devops" ### Azure Pipelines, Azure DevOps Server 2019 and newer @@ -102,12 +95,6 @@ By default, `clean` is set to `true` but can be overridden when manually running :::moniker-end -:::moniker range=" [!NOTE] > For more information about the YAML syntax for checking out submodules, see [Checkout in the YAML schema](/azure/devops/pipelines/yaml-schema/steps-checkout). @@ -207,7 +193,6 @@ The build pipeline will check out your Git submodules as long as they are: - Added by using a URL relative to the main repository. For example, this one would be checked out: ```git submodule add /../../submodule.git mymodule``` This one would not be checked out: ```git submodule add https://dev.azure.com/fabrikamfiber/_git/ConsoleApp mymodule``` - ### Authenticated submodules > [!NOTE] @@ -269,7 +254,7 @@ If a submodule contains LFS files, Git LFS must be configured prior to checking The Microsoft-hosted macOS and Linux agents come preconfigured this way. Windows agents and self-hosted macOS / Linux agents may not. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" As a workaround, if you're using YAML, you can add the following step before your `checkout`: @@ -277,9 +262,9 @@ As a workaround, if you're using YAML, you can add the following step before you steps: - script: | git config --global --add filter.lfs.required true - git config --global --add filter.lfs.smudge "git-lfs smudge -- %f" + git config --global --add filter.lfs.smudge "git-lfs smudge -- %%f" git config --global --add filter.lfs.process "git-lfs filter-process" - git config --global --add filter.lfs.clean "git-lfs clean -- %f" + git config --global --add filter.lfs.clean "git-lfs clean -- %%f" displayName: Configure LFS for use with submodules - checkout: self lfs: true @@ -305,18 +290,7 @@ If the repo is not public, you will need to pass authentication to the Git comma ### Azure Repos -:::moniker range="<= azure-devops-2019" - -Your pipeline will already have access to other repos in its project, and you can clone them in your pipeline using a script command, as shown in the following example. - -``` -- script: | - git clone -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" https://organization@dev.azure.com/project/FabrikamFiber/_git/reponame -``` - -:::moniker-end - -:::moniker range="> azure-devops-2019" +:::moniker range="<=azure-devops" You can clone multiple repositories in the same project as your pipeline by using [multi-repo checkout](multi-repo-checkout.md). @@ -352,7 +326,6 @@ If you want to disable downloading sources: * **Azure Pipelines, TFS 2018, and newer:** Click **Advanced settings**, and then select **Don't sync sources**. - > [!NOTE] > When you use this option, the agent also skips running Git commands that clean the repo. @@ -369,7 +342,6 @@ In these cases this option can help you conserve network and storage resources. > and you set a very small value for shallow fetch, the commit may not exist when the agent attempts > to check it out. If that happens, increase the shallow fetch depth setting. - After you select the check box to enable this option, in the **Depth** box specify the number of commits. > [!TIP] diff --git a/docs/pipelines/repos/tfvc.md b/docs/pipelines/repos/tfvc.md index 0031b9de2cd..15ff973ee00 100644 --- a/docs/pipelines/repos/tfvc.md +++ b/docs/pipelines/repos/tfvc.md @@ -3,7 +3,7 @@ title: Build TFVC repositories description: Using a TFVC repository with Azure Pipelines ms.topic: reference ms.assetid: d88333c9-e964-4f91-9532-5d014edb8277 -ms.date: 01/25/2023 +ms.date: 08/18/2023 monikerRange: '<= azure-devops' --- @@ -11,26 +11,22 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end +> [!IMPORTANT] +> TFVC is supported by classic pipelines only, and does not support YAML. + + ## Choose the repository to build While editing a pipeline that uses a TFVC repo, you have the following options. -| Feature | Azure Pipelines, TFS 2018, TFS 2017, TFS 2015.4 | TFS 2015 RTM | -|---------|-------------------------------------------------|--------------| -| Clean |Yes|Yes| -| Specify local path |Yes|No| -| Label sources |Yes|No| - -> [!NOTE] -> **Azure Pipelines, TFS 2017.2 and newer:** Click **Advanced settings** to see some of the following options. +* Clean +* Specify local path +* Label sources ### Repository name -Ignore this text box (**TFS 2017 RTM** or older). +Name of the TFVC repository. ### Mappings (workspace) diff --git a/docs/pipelines/scripts/cli/pipeline-variable-group-secret-nonsecret-variables.md b/docs/pipelines/scripts/cli/pipeline-variable-group-secret-nonsecret-variables.md index 061e46ba84b..0283f9da946 100644 --- a/docs/pipelines/scripts/cli/pipeline-variable-group-secret-nonsecret-variables.md +++ b/docs/pipelines/scripts/cli/pipeline-variable-group-secret-nonsecret-variables.md @@ -1,40 +1,43 @@ --- -title: 'Azure CLI sample for Azure Pipelines and variable groups' -description: Azure CLI sample for accessing secret and nonsecret variables from a variable group in an Azure Pipeline. This sample uses the azure-devops extension. +title: Manage variables in variable groups with the Azure DevOps CLI +description: Use this Azure DevOps CLI sample to create and manage secret and nonsecret variables in an Azure Pipelines variable group. author: juliakm ms.author: jukullam manager: mijacobs -ms.date: 01/12/2023 +ms.date: 08/15/2024 ms.topic: sample ms.devlang: azurecli -monikerRange: '>=azure-devops-2020' +monikerRange: 'azure-devops' ms.custom: devx-track-azurecli --- -# Use a variable group's secret and nonsecret variables in an Azure Pipeline +# Manage variables in variable groups with the Azure DevOps CLI -[!INCLUDE [version-gt-eq-2020](../../../includes/version-gt-eq-2020.md)] +[!INCLUDE [version-gt-2022](../../../includes/version-gt-2022.md)] -In this sample, use the Microsoft Azure DevOps CLI (azure-devops extension) to create an Azure Pipeline that accesses a variable group containing both secret and nonsecret variables. +Managing variables in Azure Pipelines is crucial for maintaining flexibility and security in your CI/CD workflows. This guide demonstrates how to use the Azure DevOps CLI to create and manage both secret and nonsecret variables within an Azure Pipelines variable group. By using variable groups, you can centralize the management of variables and ensure that sensitive information is securely handled. -This script demonstrates three operations: +With the sample in this guide, you learn how to: -* Defining a [Azure Pipeline](../../index.yml) using [YAML](/azure/devops/pipelines/yaml-schema/) files -* Creating a [variable group](../../library/variable-groups.md) with nonsecret and secret variables for use in a pipeline -* Running the pipeline using [Azure DevOps CLI](../../../cli/index.md), which also opens a web page for monitoring the pipeline run's processing and output +- Define an Azure Pipelines pipeline using a YAML file stored in GitHub. +- Create a variable group containing both secret and nonsecret variables. +- Execute the pipeline using the Azure DevOps CLI and monitor the run processing and output. + +> [!NOTE] +> This sample demonstrates the functionality of Azure DevOps CLI with variable groups. For increased security, [define variables in variables groups in the Pipelines UI](../../library/variable-groups.md) or [link a variable group to secrets in Azure Key Vault](../../library/link-variable-groups-to-key-vaults.md). [!INCLUDE [include](~/../docs/reusable-content/azure-cli/azure-cli-prepare-your-environment.md)] -* [Sign up for Azure Pipelines](../../get-started/pipelines-sign-up.md) to get an Azure DevOps organization. -* [Create an Azure DevOps personal access token](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) (PAT) for authentication. -* Use or create a [GitHub](https://www.github.com) repository to place the Azure Pipeline in. -* In the GitHub Marketplace, [install the Azure Pipelines application](https://github.com/marketplace/azure-pipelines/) so that Azure Pipelines can access your GitHub repository. +- A [GitHub repository with Azure Pipelines installed](../../get-started/pipelines-sign-up.md) +- A [GitHub personal access token (PAT)](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for access +- An [Azure DevOps organization](../../get-started/pipelines-sign-up.md) with a [personal access token (PAT)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) for authentication +- [Project Collection Administrator permissions in the Azure DevOps organization](../../../organizations/security/change-organization-collection-level-permissions.md) -## Sample script +## Save Pipeline YAML file -First, save the following YAML file, which defines the Azure Pipeline, to *azure-pipelines.yml* in the root directory of your local repository. Then add and commit the file in GitHub, and push the file to the remote GitHub repository. +Save the following YAML pipeline definition as a file called *azure-pipelines.yml* in the root directory and `main` branch of your GitHub repository. -```yml +```yaml parameters: - name: image displayName: 'Pool image' @@ -98,55 +101,71 @@ steps: SYSTEM_ACCESSTOKEN: $(System.AccessToken) ``` -After you've published the YAML file in GitHub, replace the placeholders in the following Bash script, and then run the script. +## The sample script + +This sample does the following tasks: + +* Create the DevOps resources +* Run the pipeline +* Modify the variable values three times +* Run the pipeline again each time the variable values are changed + +The script creates the following resources in Azure DevOps: + +* A project in your DevOps organization +* A GitHub service connection +* A pipeline +* A variable group with two nonsecret variables and one secret variable + +Before you run the script, replace the following placeholders as follows: + +- `` Your Azure DevOps organization name +- `` Your GitHub organization or user name +- `` Your GitHub repository name +- `` A name for the pipeline that is between 3-19 characters and contains only numerals and lowercase letters. The script adds a five-digit unique identifier. + +Save your GitHub PAT in your local environment. + +```bash +AZURE_DEVOPS_EXT_GITHUB_PAT= +``` + + +After you store the YAML file in GitHub, run the following Azure DevOps CLI script in a Bash shell in Cloud Shell or locally. ```azurecli #!/bin/bash -# Provide variable definitions. -devopsToken="" -devopsOrg="https://dev.azure.com/" -resourceGroupLocation="" -storageAccountLocation="" -pipelineName="" -githubOrg="" -githubRepo="" +# Provide placeholder variables. +devopsOrg="https://dev.azure.com/" +githubOrg="" +githubRepo="" +pipelineName="" repoName="$githubOrg/$githubRepo" repoType="github" branch="main" # Declare other variables. uniqueId=$RANDOM -resourceGroupName="contoso-storage-rg$uniqueId" -storageAccountName="contosostoracct$uniqueId" # needs to be lowercase devopsProject="Contoso DevOps Project $uniqueId" serviceConnectionName="Contoso Service Connection $uniqueId" -variableGroupName="Contoso Variable Group" -# Sign in to Azure CLI and follow the directions. May be unnecessary in some environments. -echo "Sign in. (For Cloud Shell, provide the device login code.)" +# Sign in to Azure CLI and follow the sign-in instructions, if necessary. +echo "Sign in." az login -# Sign in using an Azure DevOps personal access token (PAT). May be unnecessary in some environments. +# Sign in to Azure DevOps with your Azure DevOps PAT, if necessary. echo "Sign in to Azure DevOps." az devops login -# Create a resource group and a storage account. -az group create --name "$resourceGroupName" --location "$resourceGroupLocation" -az storage account create --name "$storageAccountName" \ - --resource-group "$resourceGroupName" --location "$storageAccountLocation" - -# Set the environment variable used for Azure DevOps token authentication. -export AZURE_DEVOPS_EXT_GITHUB_PAT=$devopsToken - -# Create the Azure DevOps project. Set the default organization and project. +# Create the Azure DevOps project and set defaults. projectId=$(az devops project create \ - --name "$devopsProject" --organization "$devopsOrg" --visibility public --query id) + --name "$devopsProject" --organization "$devopsOrg" --visibility private --query id) projectId=${projectId:1:-1} # Just set to GUID; drop enclosing quotes. az devops configure --defaults organization="$devopsOrg" project="$devopsProject" pipelineRunUrlPrefix="$devopsOrg/$projectId/_build/results?buildId=" -# Create GitHub service connection (requires AZURE_DEVOPS_EXT_GITHUB_PAT to be set). +# Create GitHub service connection. githubServiceEndpointId=$(az devops service-endpoint github create \ --name "$serviceConnectionName" --github-url "https://www.github.com/$repoName" --query id) githubServiceEndpointId=${githubServiceEndpointId:1:-1} # Just set to GUID; drop enclosing quotes. @@ -169,7 +188,7 @@ variableGroupId=$(az pipelines variable-group create \ az pipelines variable-group variable create \ --group-id $variableGroupId --name contososecret --secret true --value 17 pipelineRunId1=$(az pipelines run --id $pipelineId --open --query id) -echo "Go to the pipeline run's web page to view the output results for the 1st run." +echo "Go to the pipeline run's web page to view the output results of the 'Test variable group variables' job for the 1st run." echo "If the web page doesn't automatically appear, go to:" echo " ${pipelineRunUrlPrefix}${pipelineRunId1}" read -p "Press Enter to change the value of one of the variable group's nonsecret variables, then run again:" @@ -178,7 +197,7 @@ read -p "Press Enter to change the value of one of the variable group's nonsecre az pipelines variable-group variable update \ --group-id $variableGroupId --name a --value 22 pipelineRunId2=$(az pipelines run --id $pipelineId --open --query id) -echo "Go to the pipeline run's web page to view the output results for the 2nd run." +echo "Go to the pipeline run's web page to view the output results of the 'Test variable group variables' job for the 2nd run." echo "If the web page doesn't automatically appear, go to:" echo " ${pipelineRunUrlPrefix}${pipelineRunId2}" read -p "Press Enter to change the value of the variable group's secret variable, then run once more:" @@ -187,7 +206,7 @@ read -p "Press Enter to change the value of the variable group's secret variable az pipelines variable-group variable update \ --group-id $variableGroupId --name contososecret --value 35 pipelineRunId3=$(az pipelines run --id $pipelineId --open --query id) -echo "Go to the pipeline run's web page to view the output results for the 3rd run." +echo "Go to the pipeline run's web page to view the output results of the 'Test variable group variables' job for the 3rd run." echo "If the web page doesn't automatically appear, go to:" echo " ${pipelineRunUrlPrefix}${pipelineRunId3}" read -p "Press Enter to continue:" @@ -195,27 +214,36 @@ read -p "Press Enter to continue:" ## Clean up resources -After the script sample has been run, the following commands can be used to remove the resource group and all resources associated with it. +To avoid incurring charges for the Azure project, you can delete the sample project, which also deletes its resource. + +Copy the `id` of the sample project from the output of the following command: + +```azurecli +az devops project list --org +``` + +Delete the project by running the following command: + +```azurecli +az devops project delete --id --org --yes +``` + +Clean up your local environment by running the following commands: ```azurecli -az pipelines variable-group delete --group-id $variableGroupId --yes -az pipelines delete --id $pipelineId --yes -az devops service-endpoint delete --id $githubServiceEndpointId --yes -az devops project delete --id $projectId --yes export AZURE_DEVOPS_EXT_GITHUB_PAT="" -az storage account delete --name $storageAccountName --resource-group $resourceGroupName --yes -az group delete --name $resourceGroupName --yes az devops configure --defaults organization="" project="" ``` -## Azure CLI references used in this article +## Azure CLI references + +The sample in this article uses the following Azure CLI commands: - [az devops configure](/cli/azure/devops#az-devops-configure) - [az devops project create](/cli/azure/devops/project#az-devops-project-create) - [az devops project delete](/cli/azure/devops/project#az-devops-project-delete) +- [az devops project delete](/cli/azure/devops/project#az-devops-project-list) - [az devops service-endpoint github create](/cli/azure/devops/service-endpoint/github#az-devops-service-endpoint-github-create) -- [az group create](/cli/azure/group#az-group-create) -- [az group delete](/cli/azure/group#az-group-delete) - [az login](/cli/azure/reference-index#az-login) - [az pipelines create](/cli/azure/pipelines#az-pipelines-create) - [az pipelines delete](/cli/azure/pipelines#az-pipelines-delete) @@ -224,5 +252,4 @@ az devops configure --defaults organization="" project="" - [az pipelines variable-group delete](/cli/azure/pipelines/variable-group#az-pipelines-variable-group-delete) - [az pipelines variable-group variable create](/cli/azure/pipelines/variable-group/variable#az-pipelines-variable-group-variable-create) - [az pipelines variable-group variable update](/cli/azure/pipelines/variable-group/variable#az-pipelines-variable-group-variable-update) -- [az storage account create](/cli/azure/storage/account#az-storage-account-create) -- [az storage account delete](/cli/azure/storage/account#az-storage-account-delete) + diff --git a/docs/pipelines/scripts/cross-platform-scripting.md b/docs/pipelines/scripts/cross-platform-scripting.md index 3d252a5abb6..aa1568760f0 100644 --- a/docs/pipelines/scripts/cross-platform-scripting.md +++ b/docs/pipelines/scripts/cross-platform-scripting.md @@ -1,10 +1,9 @@ --- title: Cross-platform scripting -ms.custom: seodec18 description: Patterns for safe cross-platform scripting ms.topic: conceptual ms.assetid: 96b7da24-617e-4a58-b65f-040c374e60e2 -ms.date: 02/28/2022 +ms.date: 11/02/2023 monikerRange: '<= azure-devops' --- @@ -15,8 +14,7 @@ monikerRange: '<= azure-devops' With Azure Pipelines, you can run your builds on macOS, Linux, and Windows machines. If you develop on cross-platform technologies such as .NET Core, Node.js and Python, these capabilities bring both benefits and challenges. For example, most pipelines include one or more scripts that you want to run during the build process. -But scripts often don't run the same way on different platforms. -Below are some tips on how to handle this kind of challenge. +But scripts often don't run the same way on different platforms. You can use the `script` keyword shortcut to make writing scripts easier and also can use conditions to target specific platforms with your scripts. ## Run cross-platform tools with a script step @@ -51,7 +49,7 @@ Command line, PowerShell, and Bash each have different ways of reading environme If you need to access an operating system-provided value like PATH, you'll need different techniques per platform. However, Azure Pipelines offers a cross-platform way to refer to variables that -it knows about called [macro syntax](../process/variables.md#understand-variable-syntax). By surrounding a variable name in `$( )`, it will be expanded +it knows about called [macro syntax](../process/variables.md#understand-variable-syntax). By surrounding a variable name in `$( )`, it's expanded before the platform's shell ever sees it. For instance, if you want to echo out the ID of the pipeline, the following script is cross-platform friendly: @@ -220,4 +218,4 @@ Finally, add a task that uses the value, no matter how we got it. echo The IP address is $(IP_ADDR) ``` -* * * \ No newline at end of file +* * * diff --git a/docs/pipelines/scripts/git-commands.md b/docs/pipelines/scripts/git-commands.md index b4cd95a78ab..769ec9bb9e9 100644 --- a/docs/pipelines/scripts/git-commands.md +++ b/docs/pipelines/scripts/git-commands.md @@ -1,6 +1,5 @@ --- title: Run Git commands in a script -ms.custom: seodec18 description: Learn how you can run a Git command in a build script for your workflow with Azure Pipelines ms.topic: conceptual ms.assetid: B5481254-F39C-4F1C-BE98-44DC0A95F2AD @@ -12,15 +11,10 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - For some workflows, you need your build pipeline to run Git commands. For example, after a CI build on a feature branch is done, the team might want to merge the branch to main. Git is available on [Microsoft-hosted agents](../agents/hosted.md) and on [on-premises agents](../agents/agents.md). - ## Enable scripts to run Git commands @@ -60,55 +54,8 @@ Git is available on [Microsoft-hosted agents](../agents/hosted.md) and on [on-pr * **Read:** Allow * **Create tag:** Allow - ::: moniker-end -::: moniker range="<= azure-devops-2019" - -Go to the Version Control control panel tab - -

        -
      • Azure Repos: https://dev.azure.com/{your-organization}/{your-project}/_admin/_versioncontrol
        • - -
      • On-premises: https://{your-server}:8080/tfs/DefaultCollection/{your-project}/_admin/_versioncontrol
        • -
      - -

      - -![manage project](media/manage-project.png) - -

      - -

      If you see this page, select the repo, and then select the link:

      - -

      - -![control panel top to project](media/control-panel-top-to-team-project.png) - -

      - -

      - -![control panel project version control tab](media/control-panel-team-project-version-control-tab.png) - -

      - -On the **Version Control** tab, select the repository in which you want to run Git commands, and then select **Project Collection Build Service**. By default, this identity can read from the repo but can’t push any changes back to it. - -![permissions](media/control-panel-version-control-project-collection-build-service.png) - -Grant permissions needed for the Git commands you want to run. Typically you'll want to grant: - -* **Create branch:** Allow -* **Contribute:** Allow -* **Read:** Allow -* **Create tag:** Allow - -When you're done granting the permissions, make sure to select **Save changes**. - -::: moniker-end - - ### Allow scripts to access the system token ::: moniker range=">=azure-devops-2020" @@ -133,12 +80,6 @@ On the [options tab](../build/options.md), select **Allow scripts to access OAut ::: moniker-end -::: moniker range="< azure-devops-2020" - -On the [options tab](../build/options.md), select **Allow scripts to access OAuth token**. - -::: moniker-end - ## Make sure to clean up the local repo Certain kinds of changes to the local repository aren't automatically cleaned up by the build pipeline. So make sure to: @@ -178,7 +119,6 @@ steps: ## Examples - ### List the files in your repo On the [build tab](../tasks/index.md), add this task: @@ -241,18 +181,9 @@ Yes [Shell Script](/azure/devops/pipelines/tasks/reference/shell-script-v2) - ### How do I avoid triggering a CI build when the script pushes? -::: moniker range="<= azure-devops-2019" - -Add ```***NO_CI***``` to your commit message. Here are examples: -* ```git commit -m "This is a commit message ***NO_CI***"``` -* ```git merge origin/features/hello-world -m "Merge to main ***NO_CI***"``` - -::: moniker-end - -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" Add `[skip ci]` to your commit message or description. Here are examples: * ```git commit -m "This is a commit message [skip ci]"``` diff --git a/docs/pipelines/scripts/logging-commands.md b/docs/pipelines/scripts/logging-commands.md index bb491523b53..55d01e2e154 100644 --- a/docs/pipelines/scripts/logging-commands.md +++ b/docs/pipelines/scripts/logging-commands.md @@ -3,9 +3,9 @@ title: Logging commands description: How scripts can request work from the agent ms.topic: reference ms.assetid: 3ec13da9-e7cf-4895-b5b8-735c1883cc7b -ms.date: 04/21/2023 -ms.custom: contperf-fy21q3 +ms.date: 11/19/2024 monikerRange: '<= azure-devops' +ai-usage: ai-assisted --- # Logging commands @@ -15,16 +15,23 @@ monikerRange: '<= azure-devops' Logging commands are how [tasks](../process/tasks.md) and scripts communicate with the agent. They cover actions like creating new [variables](../process/variables.md), marking a step as failed, and uploading [artifacts](../artifacts/pipeline-artifacts.md). Logging commands are useful when you're troubleshooting a pipeline. - +> [!IMPORTANT] +> We make an effort to mask secrets from appearing in Azure Pipelines output, but you still need to take precautions. Never echo secrets as output. +> Some operating systems log command line arguments. Never pass secrets on the command line. +> Instead, we suggest that you map your secrets into environment variables. +> +> We never mask substrings of secrets. If, for example, "abc123" is set as a secret, "abc" isn't masked from the logs. +> This is to avoid masking secrets at too granular of a level, making the logs unreadable. +> For this reason, secrets shouldn't contain structured data. If, for example, "{ "foo": "bar" }" is set as a secret, +> "bar" isn't masked from the logs. |Type |Commands | |---------|---------| -|Task commands | [AddAttachment](#addattachment-attach-a-file-to-the-build), [Complete](#complete-finish-timeline), [LogDetail](#logdetail-create-or-update-a-timeline-record-for-a-task), [LogIssue](#logissue-log-an-error-or-warning), [PrependPath](#prependpath-prepend-a-path-to-the--path-environment-variable), [SetEndpoint](#setendpoint-modify-a-service-connection-field), [SetProgress](#setprogress-show-percentage-completed), [SetVariable](#setvariable-initialize-or-modify-the-value-of-a-variable), [UploadFile](#uploadfile-upload-a-file-that-can-be-downloaded-with-task-logs), [UploadSummary](#uploadsummary-add-some-markdown-content-to-the-build-summary) | +|Task commands | [AddAttachment](#addattachment-attach-a-file-to-the-build), [Complete](#complete-finish-timeline), [LogDetail](#logdetail-create-or-update-a-timeline-record-for-a-task), [LogIssue](#logissue-log-an-error-or-warning), [PrependPath](#prependpath-prepend-a-path-to-the--path-environment-variable), [SetEndpoint](#setendpoint-modify-a-service-connection-field), [SetProgress](#setprogress-show-percentage-completed), [SetVariable](#setvariable-initialize-or-modify-the-value-of-a-variable), [SetSecret](#setsecret-register-a-value-as-a-secret), [UploadFile](#uploadfile-upload-a-file-that-can-be-downloaded-with-task-logs), [UploadSummary](#uploadsummary-add-some-markdown-content-to-the-build-summary) | |Artifact commands | [Associate](#associate-initialize-an-artifact), [Upload](#upload-upload-an-artifact) | |Build commands | [AddBuildTag](#addbuildtag-add-a-tag-to-the-build), [UpdateBuildNumber](#updatebuildnumber-override-the-automatically-generated-build-number), [UploadLog](#uploadlog-upload-a-log) | |Release commands | [UpdateReleaseName](#updatereleasename-rename-current-release) | - ## Logging command format The general format for a logging command is: @@ -59,7 +66,7 @@ Write-Host "##vso[task.setvariable variable=testvar;]testvalue" File paths should be given as absolute paths: rooted to a drive on Windows, or beginning with `/` on Linux and macOS. > [!NOTE] -> Please note that you can't use the `set -x` command before a logging command when you are using Linux or macOS. See [troubleshooting](../troubleshooting/troubleshooting.md#variables-having--single-quote-appended), to learn how to disable `set -x` temporarily for Bash. +> Note that you can't use the `set -x` command before a logging command when you're using Linux or macOS. See [troubleshooting](../troubleshooting/troubleshooting.md#variables-having--single-quote-appended), to learn how to disable `set -x` temporarily for Bash. ## Formatting commands @@ -111,7 +118,7 @@ steps: ``` --- -Those commands will render in the logs like this: +Those commands render in the logs like this: ![Screenshot of logs with custom formatting options](media/log-formatting.png) @@ -253,7 +260,6 @@ Set a task as failed. As an alternative, you can also use `exit 1`. fi ``` - ### LogDetail: Create or update a timeline record for a task `##vso[task.logdetail]current operation` @@ -267,7 +273,7 @@ While customers can add entries to the timeline, they won't typically be shown i The first time we see `##vso[task.detail]` during a step, we create a "detail timeline" record for the step. We can create and update nested timeline records base on `id` and `parentid`. Task authors must remember which GUID they used for each timeline record. -The logging system will keep track of the GUID for each timeline record, so any new GUID will result a new timeline record. +The logging system keeps track of the GUID for each timeline record, so any new GUID results a new timeline record. #### Properties @@ -310,25 +316,21 @@ Update exist timeline record: Sets a variable in the variable service of taskcontext. The first task can set a variable, and following tasks are able to use the variable. The variable is exposed to the following tasks as an environment variable. -When `issecret` is set to `true`, the value of the variable will be saved as secret and masked out from log. Secret variables aren't passed into tasks as environment variables and must instead be passed as inputs. +When `isSecret` is set to `true`, the value of the variable will be saved as secret and masked out from log. Secret variables aren't passed into tasks as environment variables and must instead be passed as inputs. -When `isoutput` is set to `true` the syntax to reference the set variable varies based on whether you are accessing that variable in the same job, a future job, or a future stage. Additionally, if `isoutput` is set to `false` the syntax for using that variable within the same job is distinct. See [levels of output variables](../process/set-variables-scripts.md#levels-of-output-variables) to determine the appropriate syntax for each use case. +When `isOutput` is set to `true` the syntax to reference the set variable varies based on whether you're accessing that variable in the same job, a future job, or a future stage. Additionally, if `isOutput` is set to `false` the syntax for using that variable within the same job is distinct. See [levels of output variables](../process/set-variables-scripts.md#levels-of-output-variables) to determine the appropriate syntax for each use case. -See [set variables in scripts](../process/set-variables-scripts.md) and [define variables](../process/variables.md#set-variables-in-scripts) for more details. +For more information about output variables, see [set variables in scripts](../process/set-variables-scripts.md) and [define variables](../process/variables.md#set-variables-in-scripts). #### Properties -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" * `variable` = variable name (Required) -* `issecret` = boolean (Optional, defaults to false) -* `isoutput` = boolean (Optional, defaults to false) -* `isreadonly` = boolean (Optional, defaults to false) +* `isSecret` = boolean (Optional, defaults to false) +* `isOutput` = boolean (Optional, defaults to false) +* `isReadOnly` = boolean (Optional, defaults to false) ::: moniker-end -::: moniker range="< azure-devops-2019" -* `variable` = variable name (Required) -* `issecret` = boolean (Optional, defaults to false) -* `isreadonly` = boolean (Optional, defaults to false) -::: moniker-end + #### Examples @@ -336,34 +338,19 @@ See [set variables in scripts](../process/set-variables-scripts.md) and [define Set the variables: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ```yaml - bash: | echo "##vso[task.setvariable variable=sauce;]crushed tomatoes" - echo "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic" - echo "##vso[task.setvariable variable=outputSauce;isoutput=true]canned goods" - name: SetVars -``` -::: moniker-end -::: moniker range="< azure-devops-2019" -```yaml -- bash: | - echo "##vso[task.setvariable variable=sauce;]crushed tomatoes" - echo "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic" + echo "##vso[task.setvariable variable=secretSauce;isSecret=true]crushed tomatoes with garlic" + echo "##vso[task.setvariable variable=outputSauce;isOutput=true]canned goods" name: SetVars ``` ::: moniker-end + Read the variables: -::: moniker range=">= azure-devops-2019" -```yaml -- bash: | - echo "Non-secrets automatically mapped in, sauce is $SAUCE" - echo "Secrets are not automatically mapped in, secretSauce is $SECRETSAUCE" - echo "You can use macro replacement to get secrets, and they'll be masked in the log: $(secretSauce)" -``` -::: moniker-end -::: moniker range="< azure-devops-2019" +::: moniker range="<=azure-devops" ```yaml - bash: | echo "Non-secrets automatically mapped in, sauce is $SAUCE" @@ -376,27 +363,19 @@ Read the variables: Set the variables: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ```yaml - pwsh: | Write-Host "##vso[task.setvariable variable=sauce;]crushed tomatoes" - Write-Host "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic" - Write-Host "##vso[task.setvariable variable=outputSauce;isoutput=true]canned goods" - name: SetVars -``` -::: moniker-end -::: moniker range="< azure-devops-2019" -```yaml -- pwsh: | - Write-Host "##vso[task.setvariable variable=sauce;]crushed tomatoes" - Write-Host "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic" + Write-Host "##vso[task.setvariable variable=secretSauce;isSecret=true]crushed tomatoes with garlic" + Write-Host "##vso[task.setvariable variable=outputSauce;isOutput=true]canned goods" name: SetVars ``` ::: moniker-end Read the variables: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ```yaml - pwsh: | Write-Host "Non-secrets automatically mapped in, sauce is $env:SAUCE" @@ -406,20 +385,12 @@ Read the variables: write-Host "Future jobs can also see $(SetVars.outputSauce)" ``` ::: moniker-end -::: moniker range="< azure-devops-2019" -```yaml -- pwsh: | - Write-Host "Non-secrets automatically mapped in, sauce is $env:SAUCE" - Write-Host "Secrets are not automatically mapped in, secretSauce is $env:SECRETSAUCE" - Write-Host "You can use macro replacement to get secrets, and they'll be masked in the log: $(secretSauce)" -``` -::: moniker-end --- Console output: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ``` Non-secrets automatically mapped in, sauce is crushed tomatoes Secrets are not automatically mapped in, secretSauce is @@ -428,13 +399,70 @@ Future jobs can also see canned goods Future jobs can also see canned goods ``` ::: moniker-end -::: moniker range="< azure-devops-2019" + +### SetSecret: Register a value as a secret + +`##vso[task.setsecret]value` + +#### Usage + +The value is registered as a secret for the duration of the job. The value will be masked out from the logs from this point forward. This command is useful when a secret is transformed (for example, base64 encoded) or derived. + +Note: Previous occurrences of the secret value won't be masked. + +#### Examples + +# [Bash](#tab/bash) + +Set the variables: + +```yaml +- bash: | + NEWSECRET=$(echo $OLDSECRET|base64) + echo "##vso[task.setsecret]$NEWSECRET" + name: SetSecret + env: + OLDSECRET: "SeCrEtVaLuE" ``` -Non-secrets automatically mapped in, sauce is crushed tomatoes -Secrets are not automatically mapped in, secretSauce is -You can use macro replacement to get secrets, and they'll be masked in the log: *** + +Read the variables: + +```yaml +- bash: | + echo "Transformed and derived secrets will be masked: $(echo $OLDSECRET|base64)" + env: + OLDSECRET: "SeCrEtVaLuE" +``` + +# [PowerShell](#tab/powershell) + +Set the variables: + +```yaml +- pwsh: | + $NewSecret = [convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($env:OLDSECRET)) + Write-Host "##vso[task.setsecret]$NewSecret" + name: SetSecret + env: + OLDSECRET: "SeCrEtVaLuE" +``` + +Read the variables: + +```yaml +- pwsh: | + Write-Host "Transformed and derived secrets will be masked: $([convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($env:OLDSECRET)))" + env: + OLDSECRET: "SeCrEtVaLuE" +``` + +--- + +Console output: + +``` +Transformed and derived secrets will be masked: *** ``` -::: moniker-end ### SetEndpoint: Modify a service connection field @@ -484,12 +512,12 @@ Upload and attach attachment to current timeline record. These files aren't avai #### Usage -Upload and attach summary Markdown to current timeline record. This summary shall be added to the build/release summary and not available for download with logs. The summary should be in UTF-8 or ASCII format. The summary will appear on an Extensions tab. +Upload and attach summary Markdown from an .md file in the repository to current timeline record. This summary shall be added to the build/release summary and not available for download with logs. The summary should be in UTF-8 or ASCII format. The summary appears on the **Extensions** tab of your pipeline run. Markdown rendering on the Extensions tab is different from Azure DevOps wiki rendering. For more information on Markdown syntax, see the [Markdown Guide](https://www.markdownguide.org/basic-syntax/). #### Examples ``` -##vso[task.uploadsummary]c:\testsummary.md +##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/testsummary.md ``` It's a short hand form for the command @@ -529,6 +557,8 @@ The updated environment variable will be reflected in subsequent tasks. ## Artifact commands +Artifact publishing is not supported in Classic release pipelines. + ### Associate: Initialize an artifact `##vso[artifact.associate]artifact location` @@ -630,12 +660,10 @@ You can automatically generate a build number from tokens you specify in the [pi `##vso[build.addbuildtag]build tag` - #### Usage Add a tag for current build. You can expand the tag with a predefined or user-defined variable. For example, here a new tag gets added in a Bash task with the value `last_scanned-$(currentDate)`. You can't use a colon with AddBuildTag. - #### Example ```yaml @@ -648,7 +676,6 @@ Add a tag for current build. You can expand the tag with a predefined or user-de displayName: 'Apply last scanned tag' ``` - ## Release commands ### UpdateReleaseName: Rename current release diff --git a/docs/pipelines/scripts/media/BldScriptPSAdd.png b/docs/pipelines/scripts/media/BldScriptPSAdd.png deleted file mode 100644 index 30f4b068d3f..00000000000 Binary files a/docs/pipelines/scripts/media/BldScriptPSAdd.png and /dev/null differ diff --git a/docs/pipelines/scripts/media/BldScriptPSExmpVerAssembliesBuildNumFormat.png b/docs/pipelines/scripts/media/BldScriptPSExmpVerAssembliesBuildNumFormat.png deleted file mode 100644 index cb99af109b9..00000000000 Binary files a/docs/pipelines/scripts/media/BldScriptPSExmpVerAssembliesBuildNumFormat.png and /dev/null differ diff --git a/docs/pipelines/scripts/media/BldScriptPSExmpVerAssembliesBuildStep.png b/docs/pipelines/scripts/media/BldScriptPSExmpVerAssembliesBuildStep.png deleted file mode 100644 index 09f11f1ab90..00000000000 Binary files a/docs/pipelines/scripts/media/BldScriptPSExmpVerAssembliesBuildStep.png and /dev/null differ diff --git a/docs/pipelines/scripts/media/BldStepAddBegin.png b/docs/pipelines/scripts/media/BldStepAddBegin.png deleted file mode 100644 index a4a02176cf7..00000000000 Binary files a/docs/pipelines/scripts/media/BldStepAddBegin.png and /dev/null differ diff --git a/docs/pipelines/scripts/media/allow-script-to-access-oauth-token.png b/docs/pipelines/scripts/media/allow-script-to-access-oauth-token.png new file mode 100644 index 00000000000..4ee000af8ca Binary files /dev/null and b/docs/pipelines/scripts/media/allow-script-to-access-oauth-token.png differ diff --git a/docs/pipelines/scripts/media/build-number-format-2019.png b/docs/pipelines/scripts/media/build-number-format-2019.png new file mode 100644 index 00000000000..53255ef0d0d Binary files /dev/null and b/docs/pipelines/scripts/media/build-number-format-2019.png differ diff --git a/docs/pipelines/scripts/media/build-number-format.png b/docs/pipelines/scripts/media/build-number-format.png new file mode 100644 index 00000000000..e5da9a85972 Binary files /dev/null and b/docs/pipelines/scripts/media/build-number-format.png differ diff --git a/docs/pipelines/scripts/media/powershell-script-task-2020.png b/docs/pipelines/scripts/media/powershell-script-task-2020.png new file mode 100644 index 00000000000..b32a4b6e94f Binary files /dev/null and b/docs/pipelines/scripts/media/powershell-script-task-2020.png differ diff --git a/docs/pipelines/scripts/media/powershell-script-task.png b/docs/pipelines/scripts/media/powershell-script-task.png new file mode 100644 index 00000000000..02095d9cbc9 Binary files /dev/null and b/docs/pipelines/scripts/media/powershell-script-task.png differ diff --git a/docs/pipelines/scripts/media/powershell-update-script-path.png b/docs/pipelines/scripts/media/powershell-update-script-path.png index 312764896d4..7ab8aae4983 100644 Binary files a/docs/pipelines/scripts/media/powershell-update-script-path.png and b/docs/pipelines/scripts/media/powershell-update-script-path.png differ diff --git a/docs/pipelines/scripts/powershell.md b/docs/pipelines/scripts/powershell.md index f1d1954b585..893e6d17b21 100644 --- a/docs/pipelines/scripts/powershell.md +++ b/docs/pipelines/scripts/powershell.md @@ -1,202 +1,170 @@ --- -title: Use PowerShell scripts to customize pipelines -ms.custom: seodec18 -description: Learn how you can use a script to customize your pipeline +title: PowerShell scripts to customize pipelines +description: Learn about using PowerShell scripts to customize your pipelines by adding business logic. ms.topic: conceptual ms.assetid: 7D184F55-18BC-40E5-8BE7-283A0DB8E823 -ms.date: 01/06/2023 +ms.date: 07/03/2024 monikerRange: '<= azure-devops' --- -# Use a PowerShell script to customize your pipeline +# PowerShell scripts to customize pipelines [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end +This article explains how you can move beyond compiling and testing code and use PowerShell scripts to add business logic to pipelines. The Azure Pipelines [PowerShell task](/azure/devops/pipelines/tasks/reference/powershell-v2) runs PowerShell scripts in your pipelines. You can use PowerShell to access the Azure DevOps REST API, work with Azure DevOps work items and test management, or call other services as needed. -When you're ready to move beyond the basics of compiling and testing your code, use a PowerShell script to add your team's business logic to your build pipeline. You can run Windows PowerShell on a [Windows build agent](../agents/windows-agent.md). PowerShell Core runs on any platform. +You can use variables in your PowerShell scripts, including [user-defined variables](../process/variables.md#user-defined-variables) that you set yourself. You can also use [predefined variables](../build/variables.md) that are available in all Azure Pipelines, and set [multi-job output variables](../process/variables.md#set-a-multi-job-output-variable) to make variables available to future jobs. For more information, see [Define variables](../process/variables.md). + +You can use named parameters in your PowerShell scripts. Other kinds of parameters, such as switch parameters, aren't supported and cause errors if you try to use them. For more information, see [How to declare cmdlet parameters](/powershell/scripting/developer/cmdlet/how-to-declare-cmdlet-parameters). + +## Add a PowerShell script to a pipeline + +The build uses the active branch of your code. If your pipeline run uses the `main` branch, your script also uses the `main` branch. -::: moniker range=">= azure-devops-2019" -## Add a PowerShell script ### [YAML](#tab/yaml) -The syntax for including PowerShell Core is slightly different from the syntax for Windows PowerShell. +You can run Windows PowerShell on a [Windows build agent](../agents/windows-agent.md), or run PowerShell Core on any platform. The syntax for including PowerShell Core is slightly different than for Windows PowerShell. -1. Push your PowerShell script to your repo. +After you push your PowerShell script to your repo, add a `pwsh` or `powershell` step to your pipeline. The `pwsh` keyword and `powershell` keywords are both shortcuts to run the [PowerShell task](/azure/devops/pipelines/tasks/reference/powershell-v2). -2. Add a `pwsh` or `powershell` step. The `pwsh` keyword is a shortcut for the [PowerShell task](/azure/devops/pipelines/tasks/reference/powershell-v2) for PowerShell Core. The `powershell` keyword is another shortcut for the [PowerShell task](/azure/devops/pipelines/tasks/reference/powershell-v2). +Example for PowerShell Core: ```yaml -# for PowerShell Core steps: - pwsh: ./my-script.ps1 +``` + +Example for Windows PowerShell: -# for Windows PowerShell +```yaml steps: - powershell: .\my-script.ps1 ``` ### [Classic](#tab/classic) -1. Add the PowerShell Script task to your pipeline. The same [PowerShell task](/azure/devops/pipelines/tasks/reference/powershell-v2) works for PowerShell Core and Windows PowerShell. +Add the PowerShell Script task to your pipeline, and add your script file to the **Script Path**. The same [PowerShell task](/azure/devops/pipelines/tasks/reference/powershell-v2) works for both PowerShell Core and Windows PowerShell. - :::image type="content" source="media/powershell-script.png" alt-text="Add the PowerShell task."::: - -2. Add your file to the **Script Path**. - - :::image type="content" source="media/powershell-update-script-path.png" alt-text="Add the script path."::: +:::image type="content" source="media/powershell-update-script-path.png" alt-text="Screenshot of PowerShell task script path setting."::: --- -::: moniker-end - -::: moniker range="< azure-devops-2019" - -You can run Windows PowerShell Script on a [Windows build agent](../agents/windows-agent.md). - -1. Push your script into your repo. - -2. Add a PowerShell build task. - ![Add task](media/BldStepAddBegin.png) +## Example script to apply version to assemblies - ![Add PowerShell task](media/BldScriptPSAdd.png) +The example script in this section applies a version to assembly property files. For the script to run successfully, the defined build number format must have four periods, for example `$(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)`. -3. Drag the build task where you want it to run. - -4. Specify the name of the script. - -::: moniker-end - -## Example PowerShell script: version assemblies - -Here's an example script to version your assemblies. For the script to run successfully, you'll need to update your build number to use a format with four periods (example: `$(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)`). Build number can also be referred to as run number. +> [!NOTE] +> Build number is also called run number. ### [YAML](#tab/yaml) -You can [customize your build number](../process/run-number.md) within a YAML pipeline with the `name` property. +Customize your build number in the YAML pipeline by using the `name` property. The `name` property must be at the root level of the pipeline. For more information, see [Configure run or build numbers](../process/run-number.md). ```yaml name: $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r) - -pool: - vmImage: windows-latest - -steps: -- pwsh: echo $(Build.BuildNumber) //output updated build number ``` -#### [Classic](#tab/classic) - -1. To customize your build number in a classic pipeline, first add the build task to your pipeline. - ![Apply version to assemblies build task](media/BldScriptPSExmpVerAssembliesBuildStep.png) +#### [Classic](#tab/classic) -2. Next, specify your build number. +To customize your build number in a Classic pipeline, when you add the build task to your pipeline, specify your build number format in the **Options** tab. - ![Build number format](media/BldScriptPSExmpVerAssembliesBuildNumFormat.png) +:::image type="content" source="media\build-number-format.png" alt-text="Screenshot of build number format setting."::: --- -```ps -# If found use it to version the assemblies. -# -# For example, if the 'Build number format' build pipeline parameter -# $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r) -# then your build numbers come out like this: -# "Build HelloWorld_2013.07.19.1" -# This script would then apply version 2013.07.19.1 to your assemblies. - +The following PowerShell example script applies a version to assemblies. For example, if your defined build number format `$(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)` produces build number `Build HelloWorld_2024.07.19.1`, the script applies version `2024.07.19.1` to your assemblies. + +```powershell # Enable -Verbose option [CmdletBinding()] - -# Regular expression pattern to find the version in the build number -# and then apply it to the assemblies + +# Regular expression pattern to find the version in the build number $VersionRegex = "\d+\.\d+\.\d+\.\d+" - -# If this script is not running on a build server, remind user to -# set environment variables so that this script can be debugged + +# If not running on a build server, remind user to set environment variables for debugging if(-not ($Env:BUILD_SOURCESDIRECTORY -and $Env:BUILD_BUILDNUMBER)) { - Write-Error "You must set the following environment variables" - Write-Error "to test this script interactively." - Write-Host '$Env:BUILD_SOURCESDIRECTORY - For example, enter something like:' - Write-Host '$Env:BUILD_SOURCESDIRECTORY = "C:\code\FabrikamTFVC\HelloWorld"' - Write-Host '$Env:BUILD_BUILDNUMBER - For example, enter something like:' - Write-Host '$Env:BUILD_BUILDNUMBER = "Build HelloWorld_0000.00.00.0"' - exit 1 + Write-Error "You must set the following environment variables" + Write-Error "to test this script interactively." + Write-Host '$Env:BUILD_SOURCESDIRECTORY - For example, enter something like:' + Write-Host '$Env:BUILD_SOURCESDIRECTORY = "C:\code\Fabrikam\HelloWorld"' + Write-Host '$Env:BUILD_BUILDNUMBER - For example, enter something like:' + Write-Host '$Env:BUILD_BUILDNUMBER = "Build HelloWorld_0000.00.00.0"' + exit 1 } - + # Make sure path to source code directory is available if (-not $Env:BUILD_SOURCESDIRECTORY) { - Write-Error ("BUILD_SOURCESDIRECTORY environment variable is missing.") - exit 1 + Write-Error ("BUILD_SOURCESDIRECTORY environment variable is missing.") + exit 1 } elseif (-not (Test-Path $Env:BUILD_SOURCESDIRECTORY)) { - Write-Error "BUILD_SOURCESDIRECTORY does not exist: $Env:BUILD_SOURCESDIRECTORY" - exit 1 + Write-Error "BUILD_SOURCESDIRECTORY does not exist: $Env:BUILD_SOURCESDIRECTORY" + exit 1 } Write-Verbose "BUILD_SOURCESDIRECTORY: $Env:BUILD_SOURCESDIRECTORY" - -# Make sure there is a build number + +# Make sure there's a build number if (-not $Env:BUILD_BUILDNUMBER) { - Write-Error ("BUILD_BUILDNUMBER environment variable is missing.") - exit 1 + Write-Error ("BUILD_BUILDNUMBER environment variable is missing.") + exit 1 } Write-Verbose "BUILD_BUILDNUMBER: $Env:BUILD_BUILDNUMBER" - + # Get and validate the version data $VersionData = [regex]::matches($Env:BUILD_BUILDNUMBER,$VersionRegex) switch($VersionData.Count) { - 0 + 0 { - Write-Error "Could not find version number data in BUILD_BUILDNUMBER." + Write-Error "Couldn't find version number data in BUILD_BUILDNUMBER." exit 1 } 1 {} default { - Write-Warning "Found more than instance of version data in BUILD_BUILDNUMBER." - Write-Warning "Will assume first instance is version." + Write-Warning "Found more than one instance of version data in BUILD_BUILDNUMBER." + Write-Warning "Assuming first instance is version." } } $NewVersion = $VersionData[0] Write-Verbose "Version: $NewVersion" - + # Apply the version to the assembly property files $files = gci $Env:BUILD_SOURCESDIRECTORY -recurse -include "*Properties*","My Project" | - ?{ $_.PSIsContainer } | - foreach { gci -Path $_.FullName -Recurse -include AssemblyInfo.* } + ?{ $_.PSIsContainer } | + foreach { gci -Path $_.FullName -Recurse -include AssemblyInfo.* } if($files) { - Write-Verbose "Will apply $NewVersion to $($files.count) files." - - foreach ($file in $files) { - $filecontent = Get-Content($file) - attrib $file -r - $filecontent -replace $VersionRegex, $NewVersion | Out-File $file - Write-Verbose "$file.FullName - version applied" - } + Write-Verbose "Applying $NewVersion to $($files.count) files." + + foreach ($file in $files) { + $filecontent = Get-Content($file) + attrib $file -r + $filecontent -replace $VersionRegex, $NewVersion | Out-File $file + Write-Verbose "$file.FullName - version applied" + } } else { - Write-Warning "Found no files." + Write-Warning "Found no files." } ``` + +## Example script to access the REST API -## Example PowerShell script: access REST API - -In this example, you'll use the `SYSTEM_ACCESSTOKEN` variable to access the [Azure Pipelines REST API](../../integrate/index.md). +This example uses the `SYSTEM_ACCESSTOKEN` variable to access the [Azure Pipelines REST API](../../integrate/index.md). #### [YAML](#tab/yaml) -You can use `$env:SYSTEM_ACCESSTOKEN` in your script in a YAML pipeline to access the OAuth token. +You can use `$env:SYSTEM_ACCESSTOKEN` in an inline script in your YAML pipeline to access the OAuth token. + +The following inline PowerShell script in a YAML pipeline uses the OAuth token to access the Azure Pipelines REST API that retrieves the pipeline definition. ```yaml - task: PowerShell@2 @@ -213,14 +181,17 @@ You can use `$env:SYSTEM_ACCESSTOKEN` in your script in a YAML pipeline to acces SYSTEM_ACCESSTOKEN: $(System.AccessToken) ``` - #### [Classic](#tab/classic) -To enable your script to use the build process OAuth token, go to the **Tasks** tab of the build definition and within your build phase, select **Allow Scripts to Access OAuth Token**, which is located in the **Additional options** section. +To enable your script to use the build process OAuth token, select the **Agent job** for the PowerShell script task, and then select **Allow scripts to access the OAuth token** under **Additional options**. + +:::image type="content" source="media\allow-script-to-access-oauth-token.png" alt-text="Screenshot of enabling OAuth token access for scripts."::: + +Your script can now use the `SYSTEM_ACCESSTOKEN` environment variable to access the [Azure Pipelines REST API](../../integrate/index.md). -After you've done that, your script can use to SYSTEM_ACCESSTOKEN environment variable to access the [Azure Pipelines REST API](../../integrate/index.md). For example: +The following inline script in a **PowerShell Script** task uses the Azure Pipelines REST API to retrieve the pipeline definition. -```ps +```powershell $url = "$($env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)$env:SYSTEM_TEAMPROJECTID/_apis/build/definitions/$($env:SYSTEM_DEFINITIONID)?api-version=5.0" Write-Host "URL: $url" $pipeline = Invoke-RestMethod -Uri $url -Headers @{ @@ -229,29 +200,10 @@ $pipeline = Invoke-RestMethod -Uri $url -Headers @{ Write-Host "Pipeline = $($pipeline | ConvertTo-Json -Depth 100)" ``` +--- ---- - - -## FAQ - - - -### What variables are available for me to use in my scripts? - -You can use [predefined variables](../build/variables.md) in your scripts. For more information on available variables and how to use them, see [Use predefined variables](../build/variables.md). - -[!INCLUDE [include](../includes/variable-set-in-script-qa.md)] - -### Which branch of the script does the build run? - -The build will use the active branch of your code. If your pipeline run uses the `main` branch, your script will also use the `main` branch. -### What kinds of parameters can I use? - -You can use named parameters. Other kinds of parameters, such as switch parameters, aren't supported. You'll see errors if you try to use switch parameters. - -::: moniker range="< azure-devops" -[!INCLUDE [temp](../includes/qa-versions.md)] -::: moniker-end +## Related content - \ No newline at end of file +- [Configure run or build numbers](../process/run-number.md) +- [Azure Pipelines PowerShell task](/azure/devops/pipelines/tasks/reference/powershell-v2) +- [Azure Pipelines REST API](../../integrate/index.md) diff --git a/docs/pipelines/security/approach.md b/docs/pipelines/security/approach.md index 2e4e5df17ee..64b4aa13bdc 100644 --- a/docs/pipelines/security/approach.md +++ b/docs/pipelines/security/approach.md @@ -1,48 +1,63 @@ --- -title: Plan an approach to secure your YAML pipelines -description: Apply security recommendations incrementally in your YAML pipelines. Incremental improvements add up. +title: Determine your approach for securing YAML pipelines +description: Apply security recommendations incrementally in your YAML pipelines because incremental improvements add up. ms.assetid: a506a55a-2379-4d14-a52c-f4c28abae0ec ms.reviewer: vijayma -ms.date: 01/26/2023 -monikerRange: '> azure-devops-2019' +ms.date: 06/10/2024 +monikerRange: '>= azure-devops-2020' --- -# Plan how to secure your YAML pipelines +# Determine your approach for securing YAML pipelines [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -We recommend that you use an incremental approach to secure your pipelines. -Ideally, you would implement all of the guidance that we offer. -But don't be daunted by the number of recommendations. -And don't hold off making *some* improvements just because you can't make all the changes right now. +Consider adopting an incremental approach to enhance the security of your pipelines. While it’s ideal to implement all the guidance we provide, don’t get overwhelmed by the number of recommendations. Start by making some improvements, even if you can’t address everything immediately. -## Security recommendations depend on each other +[!INCLUDE [security-prerequisites](includes/security-prerequisites.md)] -Security recommendations have complex interdependencies. -Your security posture depends heavily on which recommendations you choose to implement. -The recommendations that you choose, in turn, depend on the concerns of your DevOps and security teams. -They also depend on the policies and practices of your organization. +## Security interdependence -You might choose to tighten security in one critical area and accept less security but more convenience in another area. -For example, if you use [`extends` templates](templates.md#step-targets) to require all builds to run in containers, then you might not need a [separate agent pool for each project](infrastructure.md#separate-agents-for-each-project). +Security recommendations are interdependent. Your posture relies on the specific recommendations you implement, which, in turn, align with your DevOps and security teams’ concerns and organizational policies. + +Consider prioritizing security in critical areas while accepting some trade-offs for convenience in other aspects. For example, if you use [`extends` templates](templates.md#step-targets) to require all builds to run in containers, then you might not need a [separate agent pool for each project](misc.md#separate-agents-for-each-project). ## Begin with a nearly empty template -A good place to start is by enforcing extension from a nearly empty template. -This way, as you start to apply security practices, you have a centralized place that already catches every pipeline. +Begin with a minimal template and gradually enforce extensions. This approach ensures that as you implement security practices, you have a centralized starting point that covers all pipelines. For more information, see [Templates](templates.md). +:::moniker range=">= azure-devops-2022" + ## Disable creation of classic pipelines -If you develop *only* YAML pipelines, disable creation of classic build and release pipelines. Doing so prevents a security concern that stems from YAML and classic pipelines sharing the same resources, for example the same service connections. +:::moniker-end + +:::moniker range="=azure-devops-2022" + +[!INCLUDE [feature-added-2022-1](../../includes/feature-added-2022-1.md)] + +:::moniker-end + +:::moniker range=">= azure-devops-2022" + +Disable the creation of classic build and release pipelines if you exclusively use YAML pipelines. This precaution prevents a security concern arising from YAML and classic pipelines sharing the same resources, such as service connections. + +Independently disable the creation of classic build pipelines and classic release pipelines. When both are disabled, no classic build pipeline, classic release pipeline, task groups, or deployment groups can be created via the user interface or the REST API. + +To disable the creation of classic pipelines, go to your **Organization settings** or **Project settings**, then under the *Pipelines* section select **Settings**. In the *General* section, toggle on **Disable creation of classic build pipelines** and **Disable creation of classic release pipelines**. + +If you enable this feature at the organization level, it applies to all projects within that organization. However, if you leave it disabled, you can selectively enable it for specific projects. + +:::moniker-end -When the feature is enabled, no classic build pipeline, classic release pipeline, task groups, and deployment groups can be created using either the user interface or the REST API. +:::moniker range="> azure-devops-2022" -You can disable creation of classic pipelines by turning on a toggle at either organization level or project level. To turn it on, navigate to your *Organization / Project settings*, then under the *Pipelines* section choose *Settings*. In the *General* section, toggle on *Disable creation of classic build and classic release pipelines*. +To improve the security of newly created organizations, starting with [Sprint 226](/azure/devops/release-notes/2023/sprint-225-update#disable-creation-of-classic-pipelines-for-new-organizations-pre-announcement), by default we disable creating classic build and release pipelines for new organizations. -When you turn it on at organization level, it is on for all projects in that organization. If you leave it off, you can choose for which projects you wish to turn it on. +:::moniker-end ## Next steps -After you plan your security approach, consider how your [repositories](repos.md) provide protection. +>[!div class="nextstepaction"] +> [Protect repositories](misc.md#protect-repositories) diff --git a/docs/pipelines/security/includes/security-prerequisites.md b/docs/pipelines/security/includes/security-prerequisites.md new file mode 100644 index 00000000000..1f962290f59 --- /dev/null +++ b/docs/pipelines/security/includes/security-prerequisites.md @@ -0,0 +1,17 @@ +--- +ms.topic: include +ms.service: azure-devops-pipelines +ms.manager: mijacobs +ms.author: jukullam +author: juliakm +ms.date: 03/04/2025 +--- + +This article is part of a series that helps you implement security measures for Azure Pipelines. For more information, see [Secure Azure Pipelines](../overview.md). + +## Prerequisites + +| **Category** | **Requirements** | +|---|---| +| **Azure DevOps** | - Implement recommendations in [Make your Azure DevOps secure](../../../organizations/security/security-overview.md) and [Secure Azure Pipelines](../overview.md).
      - Basic knowledge of YAML and Azure Pipelines. For more information, see [Create your first pipeline](../../create-first-pipeline.md). | +| **Permissions** | - To modify pipelines permissions: [Member of the Project Administrators group](../../../organizations/security/change-project-level-permissions.md).
      - To modify organization permissions: Member of the [Project Collection Administrators group](../../../organizations/security/change-project-level-permissions.md). | \ No newline at end of file diff --git a/docs/pipelines/security/infrastructure.md b/docs/pipelines/security/infrastructure.md deleted file mode 100644 index c5108163b20..00000000000 --- a/docs/pipelines/security/infrastructure.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Recommendations to protect shared infrastructure -description: Learn why you should separate agents, user accounts, and other infrastructure components. -ms.assetid: 1bda2617-a03b-47e1-b987-3849517a1e81 -ms.reviewer: vijayma -ms.date: 01/27/2023 -monikerRange: '> azure-devops-2019' ---- - -# Recommendations to secure shared infrastructure in Azure Pipelines - -[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] - -Protected resources in Azure Pipelines are an abstraction of real infrastructure. -Follow these recommendations to protect the underlying infrastructure. - -## Use Microsoft-hosted pools - -Microsoft-hosted pools offer isolation and a clean virtual machine for each run of a pipeline. -If possible, use Microsoft-hosted pools rather than self-hosted pools. - -## Separate agents for each project - -An agent can be bound to only one pool. -You might want to share agents across projects by sharing the pool with multiple projects. -In other words, multiple projects might run jobs on the same agent, one after another. -Although this practice saves infrastructure costs, it can allow lateral movement. - -To eliminate that form of lateral movement and to prevent one project from "poisoning" an agent for another project, keep separate agent pools with separate agents for each project. - -## Use low-privileged accounts to run agents - -It's tempting but dangerous to run the agent under an identity that can directly access Azure DevOps resources. -This problematic setup is common in organizations that use Azure Active Directory (Azure AD). -If you run the agent under an identity that's backed by Azure AD, then it can directly access Azure DevOps APIs without using the job's access token. -You should instead run the agent as a non-privileged local account such as *Network Service*. - -Azure DevOps has a group that's misleadingly named *Project Collection Service Accounts*. -By inheritance, members of Project Collection Service Accounts are also members of Project Collection Administrators. -Customers sometimes run their build agents by using an identity that's backed by Azure AD and that's a member of Project Collection Service Accounts. -If adversaries run a pipeline on one of these build agents, then they can take over the entire Azure DevOps organization. - -We've also seen self-hosted agents run under highly privileged accounts. -Often, these agents use privileged accounts to access secrets or production environments. -But if adversaries run a compromised pipeline on one of these build agents, then they can access those secrets. -Then the adversaries can move laterally through other systems that are accessible through those accounts. - -To keep your systems secure, use the lowest-privileged account to run self-hosted agents. -For example, use your machine account or a managed service identity. -Let Azure Pipelines manage access to secrets and environments. - -## Minimize the scope of service connections - -Service connections must be able to access only the resources that they require. -For instance, an [Azure service connection](../library/service-endpoints.md) should use Azure Resource Manager and service principals that are scoped to the resources that they need to access. -They shouldn't have broad contributor rights for the entire Azure subscription. - -When you create a new [Azure Resource Manager service connection](../library/connect-to-azure.md), always select a resource group. -Ensure that your resource group contains only the VMs or resources that the build requires. -Similarly, when you configure the GitHub app, grant access only to the repositories that you want to build by using Azure Pipelines. - -## Next steps - -Consider a few [general recommendations](misc.md) for security. diff --git a/docs/pipelines/security/inputs.md b/docs/pipelines/security/inputs.md index 74a1e785360..d6e0b115d02 100644 --- a/docs/pipelines/security/inputs.md +++ b/docs/pipelines/security/inputs.md @@ -1,45 +1,39 @@ --- -title: Recommendations to secure variables and parameters in a pipeline -description: Find out how to safely accept input from pipeline users. +title: Securely use variables and parameters in a pipeline +description: Find out how to safely accept input from pipeline users in Azure Pipelines. ms.assetid: ada3e166-c606-48b3-8e5e-7d83b1c1c962 ms.reviewer: vijayma -ms.date: 01/09/2023 -monikerRange: '> azure-devops-2019' +ms.date: 06/10/2024 +monikerRange: '>= azure-devops-2020' --- -# How to securely use variables and parameters in your pipeline +# Securely use variables and parameters in your pipeline [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -This article discusses how to securely use variables and parameters to gather input from pipeline users. If you'd like to learn more about using variables and parameters, see: +In Azure Pipelines, you can use variables and parameters to collect input from users. This capability is useful when you want to allow users to customize the pipeline execution. However, accepting user input can also introduce security risks if not handled properly. In this article, you learn how to securely use variables and parameters in your pipeline. -* [Define variables](../process/variables.md) -* [Use predefined variables](../build/variables.md) -* [Use runtime parameters](../process/runtime-parameters.md) -* [Template types & usage](../process/templates.md) -## Variables +[!INCLUDE [security-prerequisites](includes/security-prerequisites.md)] -Variables can be a convenient way to collect information from the user up front. -You can also use variables to pass data from step to step within a pipeline. +## Variables -But use variables with caution. Newly created variables, whether they're defined in YAML or written by a script, are read-write by default. A downstream step can change the value of a variable in a way that you don't expect. +Variables serve as a convenient method to gather user input upfront and facilitate data transfer between pipeline steps. However, exercise caution when working with variables. By default, newly created variables, whether defined in YAML or scripted, are read-write. Downstream steps can modify variable values unexpectedly. -For instance, your script reads: +For example, consider the following script snippet: ```batch msbuild.exe myproj.proj -property:Configuration=$(MyConfig) ``` -A preceding step could set `MyConfig` to `Debug & deltree /y c:`. -Although this example would only delete the contents of your build agent, you can imagine how this setting could easily become far more dangerous. +If a preceding step sets `MyConfig` to `Debug & deltree /y c:`, it could lead to unintended consequences. While this example merely deletes the contents of your build agent, it highlights the potential danger of such settings. You can make variables read-only. System variables like `Build.SourcesDirectory`, task output variables, and queue-time variables are always read-only. Variables that are created in YAML or created at run time by a script can be designated as read-only. When a script or task creates a new variable, it can pass the `isReadonly=true` flag in its logging command to make the variable read-only. -In YAML, you can specify read-only variables by using a specific key: +In YAML, you can specify read-only variables by using the following specific key: ```yaml variables: - name: myReadOnlyVar @@ -47,9 +41,12 @@ variables: readonly: true ``` +Use caution with secret variables. The recommended methods for setting secret variables include using UI, creating a variable group, or utilizing a variable group sourced from Azure Key Vault. For more information, see [set secret variables](../process/set-secret-variables.md). + + ### Queue-time variables -When defining a variable in the Pipelines UI editor, you can choose to let users override its value when running the pipeline. We call such a variable a queue-time variable. Queue-time variables are always defined in the Pipelines UI editor. +When defining a variable in the Pipelines UI editor, you can allow users to override its value during pipeline execution. These variables are referred to as queue-time variables and are always defined within the Pipelines UI editor. :::image type="content" source="media/define-variables-yaml-pipeline.png" alt-text="Screenshot of defining a queue-time variable."::: @@ -58,32 +55,41 @@ Queue-time variables are exposed to the end user when they manually run a pipeli ::: moniker range="azure-devops" +Users need [Edit queue build configuration](/azure/devops/pipelines/policies/permissions#pipeline-permissions-reference) permission on the pipeline to specify variables set at queue time. + ### Limit variables that can be set at queue time The UI and REST API used to run a pipeline provide means for users to define new variables at queue time. :::image type="content" source="media/add-variables-at-queue-time.png" alt-text="Screenshot of adding a queue-time variable just before running the pipeline."::: -In the early days of Azure Pipelines, this functionality had some issues: -- It allowed users to define new variables that aren't explicitly defined by the pipeline author in the definition. +In the early days of Azure Pipelines, this functionality had the following issues: +- It allowed users to define new variables not already defined by the pipeline author in the definition. - It allowed users to override system variables. -To correct these issues, we defined a setting to limit variables that can be set at queue time. With this setting enabled, only those variables that are explicitly marked as "Settable at queue time" can be set. In other words, you can set any variables at queue time unless this setting is enabled. +To address these issues, we defined a setting to *limit variables that can be set at queue time.* With this setting turned on, only those variables explicitly marked as "Settable at queue time" can be set. In other words, you can set any variables at queue time unless this setting is turned on. -The setting is designed to work at organization level and at project level. -1. Organization level. When the setting is on, it enforces that, for all pipelines in all projects in the organization, only those variables that are explicitly marked as "Settable at queue time" can be set. When the setting is off, each project can choose whether to restrict variables set at queue time or not. The setting is a toggle under Organization Settings -> Pipelines -> Settings. Only Project Collection Administrators can enable or disable it. +The setting is designed to work at organization and project levels. +- **Organization level:** + - When the setting is on, it enforces that only variables explicitly marked as "Settable at queue time" can be modified for all pipelines across all projects within the organization. + - Project Collection Administrators can enable or disable this setting. + - Access this setting under **Organization settings** > **Pipelines** > **Settings**. :::image type="content" source="media/org-level-settings.png" alt-text="Screenshot of limiting variables that can be set at queue time at organization level."::: -1. Project level. When the setting is on, it enforces that, for all pipelines in the project, only those variables that are explicitly marked as "Settable at queue time" can be set. If the setting is on at the organization level, then it is on for all projects and can't be turned off. The setting is a toggle under Project Settings -> Pipelines -> Settings. Only Project Administrators can enable or disable it. +- **Project level:** + - Similar to the organization level, enabling this setting ensures that only variables marked as "Settable at queue time" can be modified for all pipelines within the specific project. + - If the organization-level setting is enabled, it applies to all projects and can't be turned off. + - Project Administrators can enable or disable this setting. + - Access this setting under **Project settings** > **Pipelines** > **Settings**. :::image type="content" source="media/project-level-settings.png" alt-text="Screenshot of limiting variables that can be set at queue time at project level."::: -Lets look at an example. Say the setting is on and your pipeline defines a variable named `my_variable` that isn't settable at queue time. +The following example shows the setting is on and your pipeline defines a variable named `my_variable` that isn't settable at queue time. :::image type="content" source="media/define-variables-classic-pipeline.png" alt-text="Screenshot of defining a variable in a classic pipeline."::: Next, assume you wish to run the pipeline. The _Variables_ panel doesn't show any variables, and the _Add variable_ button is missing. :::image type="content" source="media/add-variables-at-queue-time-setting-on.png" alt-text="Screenshot of variables panel with setting on."::: -Using the [Builds - Queue](/rest/api/azure/devops/build/builds/queue) and the [Runs - Run Pipeline](/rest/api/azure/devops/pipelines/runs/run-pipeline) REST API calls to queue a pipeline run and set the value of `my_variable` or of a new variable will fail with an error similar to the following. +Using the [Builds - Queue](/rest/api/azure/devops/build/builds/queue) and the [Runs - Run Pipeline](/rest/api/azure/devops/pipelines/runs/run-pipeline) REST API calls to queue a pipeline run and set the value of `my_variable` or of a new variable fails with an error similar to the following. ```json { @@ -101,10 +107,35 @@ Using the [Builds - Queue](/rest/api/azure/devops/build/builds/queue) and the [R ## Parameters -Unlike variables, pipeline parameters can't be changed by a pipeline while it's running. -Parameters have data types such as `number` and `string`, and they can be restricted to a subset of values. -Restricting the parameters is useful when a user-configurable part of the pipeline should take a value only from a constrained list. The setup ensures that the pipeline won't take arbitrary data. +Unlike variables, a running pipeline can't modify pipeline parameters. +Parameters have data types such as `number` and `string`, and they can be restricted to specific value subsets. This restriction is valuable when a user-configurable aspect of the pipeline should only accept values from a predefined list, ensuring that the pipeline doesn't accept arbitrary data. + + + +### Enable shell tasks arguments parameter validation -## Next steps +Pipelines can reference tasks executed within the pipeline. Some tasks include an `arguments` parameter that allows you to specify more options for the task. -After you secure your inputs, you also need to secure your [shared infrastructure](infrastructure.md). +When the setting *Enable shell tasks arguments parameter validation* is enabled, the arguments parameter undergoes review to ensure that the shell correctly executes characters like semi-colons, quotes, and parentheses. +Similar to the *Limit variables that can be set at queue time* option, you can configure *Enable shell tasks arguments parameter validation* at the organization or project level under **Settings** > **Pipelines** > **Settings**. + +When this feature is turned on, any validation issues related to the `arguments` parameter trigger an error message like the following one: + +``Detected characters in arguments that may not be executed correctly by the shell. Please escape special characters using backtick (`).`` + +To resolve this issue, adjust the arguments by escaping special characters as indicated in the error message. This validation applies to the `arguments` parameter in the following specific tasks: + +- PowerShell +- BatchScript +- Bash +- Ssh +- AzureFileCopy +- WindowsMachineFileCopy + +## Related articles + +* [Define variables](../process/variables.md) +* [Set secret variables](../process/set-secret-variables.md) +* [Use predefined variables](../build/variables.md) +* [Use runtime parameters](../process/runtime-parameters.md) +* [Use template types](../process/templates.md) diff --git a/docs/pipelines/security/media/configure-checks.png b/docs/pipelines/security/media/configure-checks.png index 19dec7aa0c3..1af7dc4e13d 100644 Binary files a/docs/pipelines/security/media/configure-checks.png and b/docs/pipelines/security/media/configure-checks.png differ diff --git a/docs/pipelines/security/media/job-auth-scope.png b/docs/pipelines/security/media/job-auth-scope.png index 2ecb63a2715..7c90a824d8e 100644 Binary files a/docs/pipelines/security/media/job-auth-scope.png and b/docs/pipelines/security/media/job-auth-scope.png differ diff --git a/docs/pipelines/security/media/pipeline-permissions.png b/docs/pipelines/security/media/pipeline-permissions.png index 03ebcfcd2d6..eb0631de425 100644 Binary files a/docs/pipelines/security/media/pipeline-permissions.png and b/docs/pipelines/security/media/pipeline-permissions.png differ diff --git a/docs/pipelines/security/media/user-permissions.png b/docs/pipelines/security/media/user-permissions.png deleted file mode 100644 index 89a0849c70a..00000000000 Binary files a/docs/pipelines/security/media/user-permissions.png and /dev/null differ diff --git a/docs/pipelines/security/misc.md b/docs/pipelines/security/misc.md index a6fc147c64e..593a08a6c9d 100644 --- a/docs/pipelines/security/misc.md +++ b/docs/pipelines/security/misc.md @@ -1,31 +1,149 @@ --- -title: Other security considerations -description: Additional tips for securing your pipelines. +title: Secure agents, projects, and containers +description: Other tips for securing your pipelines, including protecting shared infrastructure, repositories, and projects. ms.assetid: 95fe319a-60bd-4b1b-9111-5fd8852f7839 ms.reviewer: vijayma -ms.date: 01/27/2023 -monikerRange: '> azure-devops-2019' +ms.date: 06/11/2024 +monikerRange: '>= azure-devops-2020' --- -# Other security considerations +# Secure agents, projects, and containers [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -There are a handful of other things you should consider when securing pipelines. +When it comes to securing Azure Pipelines, there are several other considerations to keep in mind, like protecting [shared infrastructure](#protect-shared-infrastructure), [repositories](#protect-repositories), [projects](#protect-projects), and [more](#other-security-considerations). -## Relying on PATH +[!INCLUDE [security-prerequisites](includes/security-prerequisites.md)] -Relying on the agent's `PATH` setting is dangerous. -It may not point where you think it does, since a previous script or tool could have altered it. -For security-critical scripts and binaries, always use a fully qualified path to the program. +## Protect shared infrastructure -## Logging of secrets +Protected resources in Azure Pipelines are an abstraction of real infrastructure. +Follow these recommendations to protect the underlying infrastructure. -Azure Pipelines attempts to scrub secrets from logs wherever possible. -This filtering is on a best-effort basis and can't catch every way that secrets can be leaked. -Avoid echoing secrets to the console, using them in command line parameters, or logging them to files. +### Use Microsoft-hosted pools -## Lock down containers +Microsoft-hosted pools offer isolation and a clean virtual machine for each run of a pipeline. +If possible, use Microsoft-hosted pools rather than self-hosted pools. + +### Separate agents for each project + +An agent can be associated only with a single pool. You can share agents across projects by associating the pool with multiple projects. In practice, multiple projects might utilize the same agent consecutively. While cost-effective, this approach can introduce lateral movement risks. + +To mitigate lateral movement and prevent cross-contamination between projects, maintain separate agent pools, each dedicated to a specific project. + +### Use low-privileged accounts to run agents + +While you might be tempted, running the agent under an identity with direct access to Azure DevOps resources can be risky. This setup is prevalent in organizations using Microsoft Entra ID but poses risks. If you run the agent under an identity backed by Microsoft Entra ID, it can directly access Azure DevOps APIs without relying on the job’s access token. For better security, consider running the agent using a nonprivileged local account, such as Network Service. + +> [!IMPORTANT] +> In Azure DevOps, there's a group called *Project Collection Service Accounts*, which can be misleading. By inheritance, members of Project Collection Service Accounts are also considered members of *Project Collection Administrators*. Some customers run their build agents using an identity backed by Microsoft Entra ID, and these identities may be part of Project Collection Service Accounts. But, if adversaries run a pipeline on one of these build agents, they could potentially gain control over the entire Azure DevOps organization. + +There are instances where self-hosted agents operate under highly privileged accounts. These agents often utilize these privileged accounts to access secrets or production environments. But, if adversaries execute a compromised pipeline on one of these build agents, they gain access to those secrets. Then, the adversaries can move laterally through other systems accessible via these accounts. + +To enhance system security, we recommend using the lowest-privileged account for running self-hosted agents. For instance, consider using your machine account or a managed service identity. Also, entrust Azure Pipelines with managing access to secrets and environments. + +### Minimize the scope of service connections + +Ensure that service connections have access only to the necessary resources. Whenever feasible, consider using [workload identity federation](../library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-using-workload-identity-federation) in place of a service principal for your [Azure service connection](../library/service-endpoints.md). Workload identity federation uses Open ID Connect (OIDC), an industry-standard technology, to facilitate authentication between Azure and Azure DevOps without relying on secrets. + +Ensure that your [Azure service connection](../library/service-endpoints.md) is scoped to access only the necessary resources. Avoid granting broad contributor rights for the entire Azure subscription to users. + +When you create a new [Azure Resource Manager service connection](../library/connect-to-azure.md), always choose a specific resource group. Ensure that the resource group contains only the necessary VMs or resources required for the build. Similarly, when you configure the GitHub app, grant access only to the repositories that you intend to build using Azure Pipelines. + +## Protect projects + +Beyond individual resources, it’s crucial to consider resource groups in Azure DevOps. Resources get organized by team projects, and understanding what your pipeline can access based on project settings and containment is essential. + +Each job in your pipeline receives an access token with permissions to read open resources. In some cases, pipelines might also update these resources. This means that while your user account might not have direct access to a specific resource, scripts, and tasks running in your pipeline could still access it. Additionally, Azure DevOps’ security model allows access to these resources from other projects within the organization. If you decide to restrict pipeline access to certain resources, this decision applies to all pipelines within a project—specific pipelines can't be selectively granted access to open resources. + +### Separate projects + +Given the nature of open resources, consider managing each product and team in separate projects. +By doing so, you prevent pipelines from one product inadvertently accessing open resources from another product, thus minimizing lateral exposure. But, when multiple teams or products share a project, granular isolation of their resources becomes challenging. + +If your Azure DevOps organization was created before August 2019, runs might still have access to open resources across all your organization's projects. Your organization administrator should review a critical security setting in Azure Pipelines that enables project isolation for pipelines. + +You can find this setting at **Organization settings** > **Pipelines** > **Settings**, or directly: *https:\//dev.azure.com/Organization_Name/_settings/pipelinessettings*. + +![Screenshot of job authorization scope UI](media/job-auth-scope.png) + +## Protect repositories + +In version control repositories, you can store source code, the pipeline’s YAML file, and necessary scripts and tools. To ensure safe changes to the code and pipeline, it’s crucial to apply permissions and branch policies. Additionally, consider [adding pipeline permissions and checks to repositories](../process/repository-resource.md). + +Furthermore, review the [default access control settings](../../organizations/security/default-git-permissions.md) for your repositories. + +Keep in mind that Git’s design means that branch-level protection has limitations. Users with push access to a repository can typically create new branches. If you’re working with GitHub open-source projects, anyone with a GitHub account can fork your repository and propose contributions. Since pipelines are associated with a repository (not specific branches), it’s essential to treat code and YAML files as potentially untrusted. + +### Forks + +When you're working with public repositories from GitHub, it’s essential to carefully consider your approach to fork builds. Forks, originating from outside your organization, pose particular risks. To safeguard your products from potentially untrusted contributed code, take the following recommendations into account + +> [!NOTE] +> These recommendations primarily apply to building public repositories from GitHub. + +#### Don't provide secrets to fork builds + +By default, your pipelines are configured to build forks, but secrets and protected resources aren't automatically exposed to the jobs in those pipelines. It's essential not to disable this protection to maintain security. + +:::moniker range="> azure-devops-2020" + +:::image type="content" source="media/fork-build-protection.png" alt-text="Screenshot of fork build protection UI."::: + +> [!NOTE] +> When you enable fork builds to access secrets, Azure Pipelines restricts the access token used by default. This token has limited access to open resources compared to a regular access token. +> To grant fork builds the same permissions as regular builds, enable the **Make fork builds have the same permissions as regular builds** setting. + +:::moniker-end + +:::moniker range="=azure-devops-2020" + +:::image type="content" source="media/fork-build-protection-2020.png" alt-text="Screenshot of fork build protection UI in Azure DevOps Server 2020 and lower."::: + +> [!NOTE] +> When you enable fork builds to access secrets, Azure Pipelines restricts the access token used by default. It has more limited access to open resources than a normal access token. You can't disable this protection. + +:::moniker-end + +#### Consider manually triggering fork builds + +[You can turn off automatic fork builds](../repos/github.md#contributions-from-forks) and instead use pull request comments as a way to manually building these contributions. +This setting gives you an opportunity to review the code before triggering a build. + +#### Use Microsoft-hosted agents for fork builds + +Avoid running builds from forks on self-hosted agents. Doing so could allow external organizations to execute external code on machines within your corporate network. Whenever possible, use Microsoft-hosted agents. For self-hosted agents, implement network isolation and ensure that agents don't persist their state between jobs. + +#### Review code changes + +Before you run your pipeline on a forked pull-request, carefully review the proposed changes, and make sure you're comfortable running it. + +The version of the YAML pipeline you run is the one from the pull request. Thus, pay special attention to changes to the YAML code and to the code that runs when the pipeline runs, such as command line scripts or unit tests. + +#### GitHub token scope limitation + +When you build a GitHub forked pull request, Azure Pipelines ensures the pipeline can't change any GitHub repository content. This restriction applies _only_ if you use the [Azure Pipelines GitHub app](https://github.com/marketplace/azure-pipelines) to integrate with GitHub. If you use other forms of GitHub integration, for example, the OAuth app, the restriction isn't enforced. + +### User branches + +Users in your organization with the right permissions can create new branches containing new or updated code. This code can run through the same pipeline as your protected branches. If the YAML file in the new branch is changed, then the updated YAML gets used to run the pipeline. While this design allows for great flexibility and self-service, not all changes are safe (whether made maliciously or not). + +If your pipeline consumes source code or is defined in Azure Repos, you must fully understand the [Azure Repos permissions model](../../organizations/security/permissions.md#git-repository-object-level). +In particular, a user with **Create Branch** permission at the repository level can introduce code to the repo even if that user lacks **Contribute** permission. + +## Other security considerations + +There's the following handful of other things you should consider when securing pipelines. + +### Rely on PATH + +Relying on the agent's `PATH` setting is dangerous. It might not point where you think it does, since it was potentially altered by a previous script or tool. For security-critical scripts and binaries, always use a fully qualified path to the program. + +### Log secrets + +Azure Pipelines attempts to scrub secrets from logs wherever possible. This filtering is on a best-effort basis and can't catch every way that secrets can be leaked. Avoid echoing secrets to the console, using them in command line parameters, or logging them to files. + +### Lock down containers Containers have a few system-provided volume mounts mapping in the tasks, the workspace, and external components required to communicate with the host agent. You can mark any or all of these volumes read-only. @@ -42,17 +160,15 @@ resources: work: false # the default; shown here for completeness ``` -Most people should mark the first three read-only and leave `work` as read-write. -If you know you won't write to the work directory in a given job or step, go ahead and make `work` read-only as well. -If you have tasks in your pipeline, which self-modify, you may need to leave `tasks` read-write. +Typically, most people should set the first three directories as read-only and leave `work` as read-write. +If you don't write to the `work` directory in a specific job or step, feel free to make `work` read-only as well. But, if your pipeline tasks involve self-modification, you might need to keep `tasks` as read-write. ::: moniker range=">= azure-devops-2020" -## Control available tasks +### Control available tasks -You can disable the ability to install and run tasks from the Marketplace. -This will allow you greater control over the code that executes in a pipeline. -You may also disable all the in-the-box tasks (except Checkout, which is a special action on the agent). +You can disable the ability to install and run tasks from the Marketplace, which allows you greater control over the code that executes in a pipeline. +You might also disable all the in-the-box tasks (except Checkout, which is a special action on the agent). We recommend that you don't disable in-the-box tasks under most circumstances. Tasks directly installed with [`tfx`](https://www.npmjs.com/package/tfx-cli) are always available. @@ -60,12 +176,13 @@ With both of these features enabled, **only** those tasks are available. ::: moniker-end -## Use the Auditing service +### Use the Auditing service Many pipeline events are recorded in the Auditing service. -Review the audit log periodically to ensure no malicious changes have slipped past. +Review the audit log periodically to ensure no malicious changes slipped past. Visit `https://dev.azure.com/ORG-NAME/_settings/audit` to get started. ## Next steps -Return to the [overview](overview.md) and make sure you've covered every article. +>[!div class="nextstepaction"] +>[Review the security overview](overview.md) diff --git a/docs/pipelines/security/overview.md b/docs/pipelines/security/overview.md index f2754fe2094..ae93dea05e5 100644 --- a/docs/pipelines/security/overview.md +++ b/docs/pipelines/security/overview.md @@ -1,55 +1,129 @@ --- -title: Securing Azure Pipelines +title: Secure your Azure Pipelines description: Guidelines and recommendations for securing pipelines. ms.assetid: 1ef377e9-e684-4e72-8486-a42d754761ac +ms.custom: peer-review-program ms.reviewer: vijayma -ms.date: 01/24/2023 -monikerRange: '> azure-devops-2019' +ms.date: 03/04/2025 +monikerRange: "<=azure-devops" --- -# Securing Azure Pipelines +# Secure your Azure Pipelines [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -Azure Pipelines poses unique security challenges. -You can use a pipeline to run scripts or deploy code to production environments. -But you want to ensure your CI/CD pipelines don't become avenues to run malicious code. -You also want to ensure only code you intend to deploy is deployed. -Security must be balanced with giving teams the flexibility and power they need to run their own pipelines. - -> [!NOTE] -> Azure Pipelines is one among a collection of Azure DevOps Services, all built on the same secure infrastructure in Azure. -> To understand the main concepts around security for all of Azure DevOps Services, see [Azure DevOps Data Protection Overview](../../organizations/security/data-protection.md) and [Azure DevOps Security and Identity](../../organizations/security/about-security-identity.md). - -Traditionally, organizations implemented security through draconian lock-downs. -Code, pipelines, and production environments had severe restrictions on access and use. -In small organizations with a few users and projects, this stance was relatively easy to manage. -However, that's not the case in larger organizations. -Where many users have contributor access to code, one must "assume breach". -Assuming breach means behaving as if an adversary has contributor access to some (if not all) of the repositories. - -The goal in this case is to prevent that adversary from running malicious code in the pipeline. -Malicious code may steal secrets or corrupt production environments. -Another goal is to prevent lateral exposure to other projects, pipelines, and repositories from the compromised pipeline. - -YAML pipelines offer the best security for your Azure Pipelines. In contrast to classic build and release pipelines, YAML pipelines: - -* _Can be code reviewed_. YAML pipelines are no different from any other piece of code. You can prevent malicious actors from introducing malicious steps in your pipelines by enforcing the use of Pull Requests to merge changes. [Branch policies](../../repos/git/branch-policies-overview.md) make it easy for you to set this up. -* _Provide resource access management_. Resource owners decide if a YAML pipeline can access a resource or not. This security feature control attacks like [stealing another repository](https://devblogs.microsoft.com/devops/pipeline-stealing-another-repo/). [Approvals and checks](../process/approvals.md) provide access control for _each_ pipeline run. -* _Support runtime parameters_. [Runtime parameters](../process/runtime-parameters.md) help you avoid a host of security issues related to variables, such as [Argument Injection](https://devblogs.microsoft.com/devops/pipeline-argument-injection/). - -This series of articles outlines recommendations to help you put together a secure YAML-based CI/CD pipeline. -It also covers the places where you can make trade-offs between security and flexibility. -The series also assumes familiarity with [Azure Pipelines](../get-started/what-is-azure-pipelines.md), the core [Azure DevOps security constructs](../../organizations/security/about-security-identity.md), and [Git](https://git-scm.com). - - -Topics covered: -- [Incremental approach to improving security](approach.md) -- [Repository protection](repos.md) -- [Secure access to repositories](secure-access-to-repos.md) -- [Pipeline resources](resources.md) -- [Project structure](projects.md) -- [Security through templates](templates.md) -- [Variables and parameters](inputs.md) -- [Shared infrastructure](infrastructure.md) -- [Other security considerations](misc.md) +Pipelines offer powerful capabilities for executing scripts and deploying code to production environments, but it's crucial to balance this power with security. You never want a pipeline to become a conduit for malicious code. Balancing security with the flexibility and power needed by development teams is essential. + +This article provides an overview of necessary security-related configurations to protect your pipelines against threats and vulnerabilities. + +## Prerequisites + +| **Category** | **Requirements** | +|---|---| +| **Azure DevOps** | - Implement recommendations in [Make your Azure DevOps secure](../../organizations/security/security-overview.md).
      - Basic knowledge of YAML and Azure Pipelines. For more information, see [Create your first pipeline](../create-first-pipeline.md). | +| **Permissions** | - To modify pipelines permissions: Member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md).
      - To modify organization permissions: Member of the [Project Collection Administrators group](../../organizations/security/change-project-level-permissions.md). | + +## Restrict project, repository, and service connection access + +To enhance security, consider separating your projects, using branch policies, and adding more security measures for forks. Minimize the scope of service connections and use the most secure authentication methods. + +- **Separate projects**: Manage each product and team in separate projects. This prevents pipelines from one product from inadvertently accessing open resources from another product, minimizing lateral exposure. +- **Use project-level identities**: Use a project-based build identity for pipelines instead of a collection-level identity. Project-level identities can only access resources within their associated project, minimizing the risk of unauthorized access by malicious actors. For more information, see [scoped build identities](../process/access-tokens.md#scoped-build-identities) and [job authorization scope](../process/access-tokens.md#job-authorization-scope). +- **Use branch policies**: To ensure safe changes to code and pipeline, apply permissions and branch policies. Additionally, consider [adding pipeline permissions and checks to repositories](../process/repository-resource.md). +- **Add additional security for forks**: When you work with public repositories from GitHub, carefully consider your approach to fork builds. Forks originating from outside your organization pose particular risks. + - **Don't provide secrets to fork builds**: By default, pipelines are configured to build forks, but secrets and protected resources aren't automatically exposed to the jobs in those pipelines. It's essential not to disable this protection to maintain security. + - **Consider manually triggering fork builds**: Turn off automatic fork builds and use pull request comments to manually build these contributions. This setting gives you an opportunity to review the code before triggering a build. For more information, see [Turn off automatic fork builds](../repos/github.md#contributions-from-forks). + - **Don't provide secrets to fork builds**: By default, secrets associated with your pipeline aren’t made available to pull request validations of forks. Do not enable the option to **Make secrets available to builds of forks**. For instructions on how to find and verify this setting, see [Contributions from forks](../repos/github.md#contributions-from-forks). + - **Consider manually triggering fork builds**: Turn off automatic fork builds and use pull request comments to manually build these contributions. This setting gives you an opportunity to review the code before triggering a build. For instructions on how to do this, see [Turn off automatic fork builds](../repos/github.md#contributions-from-forks). + - **Use Microsoft-hosted agents for fork builds**: Avoid running builds from forks on self-hosted agents. Doing so could allow external organizations to execute external code on machines within your corporate network. Whenever possible, use Microsoft-hosted agents. + - **Use the Azure Pipelines GitHub app for token scope limitation**: When you build a GitHub forked pull request, Azure Pipelines ensures the pipeline can't change any GitHub repository content. This restriction applies _only_ if you use the [Azure Pipelines GitHub app](https://github.com/marketplace/azure-pipelines) to integrate with GitHub. + +### Secure service connections + +- **Minimize the scope of service connections**: Service connections should only have access to necessary resources. When you create a new Azure Resource Manager service connection, always choose a specific resource group. Make sure that the resource group contains only the necessary VMs or resources required for the build. For instructions on how to set up service connections, see [Use an Azure Resource Manager service connection](../library/connect-to-azure.md). +- **Use workload identity federation for authentication**: Whenever possible, use workload identity federation instead of a service principal for your Azure service connection. Workload identity federation uses Open ID Connect (OIDC), an industry-standard technology, to facilitate authentication between Azure and Azure DevOps without relying on secrets. For instructions on how to do this, see [Create a service connection with workload identity federation (automatic)](../library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-using-workload-identity-federation). +- **Minimize GitHub App access**: When you configure the GitHub app to Azure DevOps, grant access only to the repositories you intend to build using pipelines. + +## Use YAML pipelines instead of Classic pipelines + +For added security and to reduce the risk of accidental misconfigurations, use YAML pipelines instead of Classic pipelines. This precaution prevents a security concern arising from YAML and classic pipelines sharing the same resources, such as service connections. If your organization is using Classic pipelines, [migrate the pipelines to YAML](../release/from-classic-pipelines.md). + +- **YAML offers the benefits of infrastructure as code**: Treat YAML pipelines like any other code because steps and dependencies are defined in code. There's also clear visibility into pipeline configurations and a reduced risk of accidental misconfigurations. +- **YAML pipelines can be combined with enhanced security measures**: Through code reviews and pull requests, use [branch policies](../../repos/git/branch-policies-overview.md) to set up a review process for pull requests to prevent bad merges. +- **Resource access management**: Resource owners control whether a YAML pipeline can access specific resources. This security feature prevents attacks like stealing another repository. Use [Approvals and checks](../process/approvals.md) to provide access control for each pipeline run. + - **Protected branch check**: If you have manual code review processes for specific branches, you can extend this protection to pipelines. A protected branch check for a resource prevents pipelines from automatically running on unauthorized branches. + - **Manual approval check**: Use a manual approval check to block pipeline requests from using a protected resource until manually approved by specified users or groups. + - **Business hours check**: Use this check to ensure that a pipeline deployment starts within a specified day and time window. +- **Disable creating Classic pipelines**: Independently disable the creation of classic build pipelines and classic release pipelines. When both are disabled, no classic build pipeline, classic release pipeline, task groups, or deployment groups can be created via the user interface or the REST API. For more information, see [Disable creation of Classic pipelines](approach.md#disable-creation-of-classic-pipelines). + +## Secure agents + +To secure containers, mark volumes as read-only, set resource limits, use trusted images, scan for vulnerabilities, and enforce security policies. + +- **Use Microsoft-hosted instead of self-hosted agents**: Microsoft-hosted agents offer isolation and a clean virtual machine for each run of a pipeline. Use Microsoft-hosted agents instead of self-hosted agents. For more information, see [Microsoft-hosted agents](../agents/hosted.md). +- **Separate agents for each project**: To mitigate lateral movement and prevent cross-contamination between projects, maintain separate agent pools, each dedicated to a specific project. +- **Use low-privileged accounts to run agents**: To enhance system security, use the lowest-privileged account for running self-hosted agents. For example, consider using your machine account or a managed service identity. Don't run an agent under an identity with direct access to Azure DevOps resources. +- **Isolate production artifacts and sensitive agent pools**: Use different agent pools to prevent security issues. + - **Use a separate agent pool for production artifacts**: Isolate production artifacts by using a distinct agent pool, preventing accidental deployments from nonproduction branches. + - **Segment sensitive pools:** Create separate pools for sensitive and nonsensitive workloads. Only allow credentials in build definitions associated with the appropriate pool. +- **Configure restrictive firewalls for self-hosted agents**: Set up firewalls to be as restrictive as possible while still allowing agents to function, balancing security and usability. +- **Regularly update self-hosted agent pools**: Keep your self-hosted agents up to date with regular updates to ensure vulnerable code isn't running, reducing the risk of exploitation. + +## Securely use variables and parameters + +Securely use variables and parameters in your pipelines by following best practices for setting secrets. Best practices include restricting secret use, using queue-time variables, and enabling shell task argument validation to protect your pipeline from threats and vulnerabilities. + +- **Restrict access to secrets**: Remove any secrets or keys from appearing in pipelines. Move to secretless authentication methods like workload identity federation or set secrets in the UI, a variable group, or a variable group sourced from Azure Key Vault. +- **Enable shell parameter validation**: When the setting *Enable shell tasks arguments parameter validation* is enabled, there's an added check for characters like semi-colons, quotes, and parentheses. Turn on *Enable shell tasks arguments parameter validation* at the organization or project level under **Settings** > **Pipelines** > **Settings**. +- **Limit variables that can be set at queue time**: Prevent users from defining new variables at queue time by enabling the setting *limit variables that can be set at queue time* at **Organization settings** > **Pipelines** > **Settings**. +- **Use parameters instead of variables**: Unlike variables, a running pipeline can't modify pipeline parameters. Parameters have data types such as `number` and `string`, and they can be restricted to specific value subsets. This restriction is valuable when a user-configurable aspect of the pipeline should only accept values from a predefined list, ensuring that the pipeline doesn't accept arbitrary data. +- **Reference secrets from templates**: Instead of including inline scripts with secret parameters directly in your pipeline YAML, use templates to abstract sensitive information away from the main pipeline. To implement this approach, create a separate YAML file for your script and then store that script in a separate, secure repository. You can then reference the template and pass a secret variable in your YAML as a parameter. The secure variable should come from Azure Key Vault, a variable group, or the pipeline UI. For more see, [Use templates](templates.md). +- **Limit secrets with branch policies and variable group permissions**: You can use a combination of variable group permissions, conditional job insertion, and branch policies to make sure that secrets are tied to the `main` branch. For more information, see [Protect secrets](secrets.md#limit-secrets-with-branch-policies-and-variable-group-permissions). +- **Use setvariable to limit setting variables**: Use the `settableVariables` attribute to configure what variables pipeline authors are allowed to set in a pipeline. Without this setting, pipeline authors can declare unlimited new variables with the `setvariable` logging command. When you specify an empty list `with settableVariables`, all variable setting is disallowed. For more information, see the [`settableVariables` attribute](/azure/devops/pipelines/yaml-schema/target-settable-variables) in the YAML Schema. + +The best method to protect a secret is to not have a secret in the first place. Avoid using secrets when possible, never store them in YAML files, and ensure they are not logged or printed to maintain security. + +- **Avoid using secrets when possible**: Check to see if your pipeline can use a different method than using a secret to perform a task such as a service connection with workload identity federation or a managed identity. Managed identities allow your applications and services to authenticate with Azure without requiring explicit credentials. For more information, see [Use service principals & managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md). +**Don't put secrets in YAML**: Never store sensitive values as plaintext in an Azure Pipelines **.yml** file. +- **Don't log or print secrets**: Avoid echoing secrets to the console, using them in command line parameters, or logging them to files. Azure Pipelines attempts to scrub secrets from logs wherever possible but can't catch every way that secrets can be leaked. +- **Don't use structured data like JSON as secrets**: Create individual secrets for each sensitive value. This approach ensures better redaction accuracy and minimizes the risk of exposing sensitive data inadvertently. + +### Audit and rotate secrets + +To secure your pipelines, regularly audit secret handling in tasks and logs, review and remove unnecessary secrets, and rotate secrets to minimize security risks. + +- **Audit secret handling in tasks and logs**: Checks tasks to make sure secrets aren't sent to hosts or printed to logs. Verify that there are no secrets in any log files, including the error logs. +- **Review registered secrets**: Confirm that secrets in your pipeline are still necessary, and remove any that are no longer needed to reduce clutter and potential security risks. +- **Rotate secrets**: Regularly rotate secrets to minimize the window of time during which a compromised secret could be exploited. + +### Prevent malicious code execution + +To ensure that only tested and sanitized code runs through your pipeline, regularly review your pipelines for common issues. + +- **Code scanning**: Escape special characters in arguments to avoid shell command injection. You can use [GitHub Advanced Security for Azure DevOps](../../repos/security/github-advanced-security-security-overview.md) to automate code scanning. +- **Validate inputs and use parameters**: Validate input parameters and arguments to prevent unintended behavior. Use parameterized queries in scripts to prevent SQL injection. [Runtime parameters](../process/runtime-parameters.md) help avoid security issues related to variables, such as [Argument Injection](https://devblogs.microsoft.com/devops/pipeline-argument-injection/). +- **Don't use PATH in scripts**: Relying on the agent's `PATH` setting is dangerous because it can be altered by a previous script or tool. Always use a fully qualified path instead. +- **Control available tasks**: Disable the ability to install and run tasks from the Marketplace, which gives you greater control over the code that executes in a pipeline. +- +## Secure containers + +Learn how to secure containers through configuration changes, scanning, and policies. + +- **Mark volumes as read only**: Containers include system-provided volume mounts for tasks, tools, and external components required to work with the host agent. Set `externals`, `tasks`, and `tools` to read only for added security. +- **Set container-specific resource limits**: Set limits on CPU and memory to prevent containers from consuming excessive resources, which can lead to denial of service or security vulnerabilities. +- **Use trusted images**: Use official and verified images from reputable sources such as Azure Container Registry or Docker Hub. Always specify a specific version or tag to maintain consistency and reliability, rather than relying on the `latest` tag. Regularly update base images to include the latest security patches and bug fixes. +- **Scan containers for vulnerabilities and enforce runtime threat protection**: Use tools such as [Microsoft Defender for Cloud](/azure/defender-for-cloud/defender-for-containers-introduction) to monitor and detect security risks. Additionally, Azure Container Registry offers integrated [vulnerability scanning](/azure/container-registry/scan-images-defender) to help ensure container images are secure before deployment. You can also integrate third-party scanning tools through Azure DevOps extensions for added security checks. +- **Implement security policies to prevent privilege escalation and ensure containers run with the least amount of privileges necessary**: For example, Azure [Kubernetes Service (AKS)](/azure/aks/operator-best-practices-cluster-security), [role-based access control](/azure/aks/manage-azure-rbac), and [Pod Security Admission](/azure/aks/use-psa) let you enforce policies that restrict container privileges, ensure non-root execution, and limit access to critical resources. +- **Utilize Network Policies**: [Network Policies](/azure/virtual-network/kubernetes-network-policies) can be used to restrict communication between containers, ensuring that only authorized containers can access sensitive resources within your network. In addition, [Azure Policy for AKS](/azure/governance/policy/concepts/policy-for-kubernetes) can be applied to enforce container security best practices, such as ensuring only trusted container images are deployed. + +## Use templates to enforce best practices + +Begin with a minimal template and gradually enforce extensions. This approach ensures that as you implement security practices, you have a centralized starting point that covers all pipelines. + +- **Use extends templates**: Extends templates define the outer structure and offer specific points for targeted customizations. [Using extends templates](../process/templates.md#extend-from-a-template) can prevent malicious code from infiltrating a pipeline. +- **Restrict access with steps**: Limit network access by having steps such as downloading packages run on a container rather than on the host. When steps run in a container, you prevent a bad actor from modifying agent configuration or leaving malicious code for later execution. + +## Related Articles + +- [Microsoft Security Development Lifecycle](https://www.microsoft.com/sdl/) +- [Azure Trust Center](https://azure.microsoft.com/support/trust-center/) \ No newline at end of file diff --git a/docs/pipelines/security/projects.md b/docs/pipelines/security/projects.md deleted file mode 100644 index 83575797f7f..00000000000 --- a/docs/pipelines/security/projects.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Recommendations to structure projects in your pipeline -description: Learn how to use project structure to improve pipeline security. -ms.assetid: 90fb461a-2315-4b60-a662-f022c9c770e2 -ms.reviewer: vijayma -ms.date: 01/27/2023 -monikerRange: '> azure-devops-2019' ---- - -# Recommendations to securely structure projects in your pipeline - -[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] - -Beyond the scale of individual resources, you should also consider groups of resources. -In Azure DevOps, resources are grouped by team projects. -It's important to understand what resources your pipeline can access based on project settings and containment. - -Every job in your pipeline receives an access token. This token has permissions to read open resources. -In some cases, pipelines might also update those resources. -In other words, your user account might not have access to a certain resource, but scripts and tasks that run in your pipeline might have access to that resource. -The security model in Azure DevOps also allows access to these resources from other projects in the organization. -If you choose to shut off pipeline access to some of these resources, then your decision applies to all pipelines in a project. -A specific pipeline can't be granted access to an open resource. - -## Separate projects - -Given the nature of open resources, you should consider managing each product and team in a separate project. -This practice ensures that a pipeline from one product can't access open resources from another product. -In this way, you prevent lateral exposure. -When multiple teams or products share a project, you can't granularly isolate their resources from one another. - -If your Azure DevOps organization was created before August 2019, then runs might be able to access open resources in all of your organization's projects. -Your organization administrator must review a key security setting in Azure Pipelines that enables project isolation for pipelines. -You can find this setting at **Azure DevOps** > **Organization settings** > **Pipelines** > **Settings**. Or go directly to this Azure DevOps location: *https:\//dev.azure.com/ORG-NAME/_settings/pipelinessettings*. - -![Screenshot of job authorization scope UI](media/job-auth-scope.png) - -## Next steps - -After you've set up the right project structure, enhance runtime security by using [templates](templates.md). diff --git a/docs/pipelines/security/repos.md b/docs/pipelines/security/repos.md deleted file mode 100644 index e75760eef33..00000000000 --- a/docs/pipelines/security/repos.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Secure repositories -description: Securing repos and forks -ms.assetid: c1cfe88b-96aa-4804-998c-027a287e5696 -ms.reviewer: vijayma -ms.date: 07/13/2022 -monikerRange: '> azure-devops-2019' ---- - -# Repository protection - -[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] - -Source code, the pipeline's YAML file, and necessary scripts & tools are all stored in a version control repository. -Permissions and branch policies must be employed to ensure changes to the code and pipeline are safe. You can also [add pipeline permissions and checks to repositories](../process/repository-resource.md). - -Also, you should review [default access control](../../organizations/security/default-git-permissions.md) for repositories. - -Because of Git's design, protection at a branch level will only carry you so far. -Users with push access to a repo can usually create new branches. -If you use GitHub open-source projects, anyone with a GitHub account can fork your repository and propose contributions back. -Since pipelines are associated with a repository and not with specific branches, you must assume the code and YAML files are untrusted. - -## Forks - -If you build public repositories from GitHub, you must consider your stance on fork builds. -Forks are especially dangerous since they come from outside your organization. -To protect your products from contributed code, consider the following recommendations. - -> [!NOTE] -> The following recommendations apply primarily to building public repos from GitHub. - -### Don't provide secrets to fork builds - -By default, your pipelines are configured to build forks, but secrets and protected resources aren't made available to the jobs in those pipelines by default. -Don't turn off this latter protection. - -:::moniker range="> azure-devops-2020" - -:::image type="content" source="media/fork-build-protection.png" alt-text="Screenshot of fork build protection UI."::: - -> [!NOTE] -> When you enable fork builds to access secrets, Azure Pipelines by default restricts the access token used for fork builds. -> It has more limited access to open resources than a normal access token. -> To give fork builds the same permissions as regular builds, enable the **Make fork builds have the same permissions as regular builds** setting. - -:::moniker-end - -:::moniker range="<= azure-devops-2020" - -:::image type="content" source="media/fork-build-protection-2020.png" alt-text="Screenshot of fork build protection UI in Azure DevOps Server 2020 and lower."::: - -> [!NOTE] -> Even if you enable fork builds to access secrets, Azure Pipelines restricts the access token used for fork builds. -> It has more limited access to open resources than a normal access token. -> You cannot disable this protection. - -:::moniker-end - - -### Consider manually triggering fork builds - -You can turn off automatic fork builds and instead use pull request comments as a way to manually building these contributions. -This setting will give you an opportunity to review the code before triggering a build. - -### Use Microsoft-hosted agents for fork builds - -Don't run builds from forks on self-hosted agents. -By doing so, you're effectively providing a path to external organizations to run outside code on machines inside your corporate network. -Use Microsoft-hosted agents whenever possible. For your self-hosted agent, use some form of network isolation and ensure agents don't persist their state between jobs. - -### Review code changes - -Before you run your pipeline on a forked pull-request, carefully review the proposed changes, and make sure you're comfortable running it. - -The version of the YAML pipeline you'll run is the one from the pull request. Thus, pay special attention to changes to the YAML code and to the code that runs when the pipeline runs, such as command line scripts or unit tests. - -### GitHub token scope limitation - -When you build a GitHub forked pull request, Azure Pipelines ensures the pipeline can't change any GitHub repository content. This restriction applies _only_ if you use the [Azure Pipelines GitHub app](https://github.com/marketplace/azure-pipelines) to integrate with GitHub. If you use other forms of GitHub integration, for example, the OAuth app, the restriction isn't enforced. - -## User branches - -Users in your organization with the right permissions can create new branches containing new or updated code. -That code can run through the same pipeline as your protected branches. -Further, if the YAML file in the new branch is changed, then the updated YAML will be used to run the pipeline. -While this design allows for great flexibility and self-service, not all changes are safe (whether made maliciously or not). - -If your pipeline consumes source code or is defined in Azure Repos, you must fully understand the [Azure Repos permissions model](../../organizations/security/permissions.md#git-repository-object-level). -In particular, a user with **Create Branch** permission at the repository level can introduce code to the repo even if that user lacks **Contribute** permission. - - - -## Next steps - -Next, learn about the more protection offered by checks on [protected resources](resources.md). - diff --git a/docs/pipelines/security/resources.md b/docs/pipelines/security/resources.md index b8edec840c7..00bbfad016d 100644 --- a/docs/pipelines/security/resources.md +++ b/docs/pipelines/security/resources.md @@ -1,28 +1,29 @@ --- -title: Pipeline resource protection -description: Permissions and approvals on important resources. +title: Secure pipeline resources +description: Learn about permissions, checks, and approvals for Azure Pipeline resources. ms.assetid: 9e635504-f56a-4d59-8629-ced0cbb03c77 ms.reviewer: vijayma -ms.date: 01/26/2023 -monikerRange: '> azure-devops-2019' +ms.date: 07/15/2024 +ms.topic: conceptual +monikerRange: '>= azure-devops-2020' --- -# Pipeline resources +# Resource security [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -Azure Pipelines offers security beyond just protecting the YAML file and source code. -When YAML pipelines run, access to resources goes through a system called [checks](../process/approvals.md). -Checks can suspend or even fail a pipeline run in order to keep resources safe. -A pipeline can access two types of resources, protected and open. +This article describes Azure Pipelines security features that protect your pipelines and resources. Pipelines can access two types of resources, open or protected. + +Artifacts, pipelines, test plans, and work items are considered *open resources* that don't have the same restrictions as protected resources. You can fully automate workflows by subscribing to trigger events on open resources. For more information about protecting open resources, see [Protect projects](misc.md#protect-projects). + +Permissions and approval checks allow pipelines to access *protected resources* during pipeline runs. To keep protected resources safe, checks can suspend or fail a pipeline run. + +[!INCLUDE [security-prerequisites](includes/security-prerequisites.md)] ## Protected resources -Your pipelines often have access to secrets. -For instance, to sign your build, you need a signing certificate. -To deploy to a production environment, you need a credential to that environment. -Azure Pipelines requires the **Administrator** role when opening up access to a resource to all pipelines for all protected resources except for Environments. For Environments, you'll need the **Creator** role. Learn more about [resource protection](../library/add-resource-protection.md). -In Azure Pipelines, all of the following are considered *protected* resources in YAML pipelines: +Protected means that only specific users and pipelines within the project can access the resource. Examples of protected resources include: + - [Agent pools](../agents/agents.md) - [Secret variables in variable groups](../library/variable-groups.md) - [Secure files](../library/secure-files.md) @@ -30,77 +31,47 @@ In Azure Pipelines, all of the following are considered *protected* resources in - [Environments](../process/environments.md) - [Repositories](../process/repository-resource.md) -"Protected" means: -- They can be made accessible to specific users and specific pipelines within the project. They can't be accessed by users and pipelines outside of a project. -- You can run other manual or automated checks every time a YAML pipeline uses one of these resources. To learn more about protected resources, see [About pipeline resources](../process/about-resources.md). +You can define checks that must be satisfied before a stage that consumes a protected resource can start. For example, you can require manual approval before the stage can use the protected resource. +### Repository protection -## Protecting repository resources -Repositories can optionally be protected. -At the organization or project level, you may choose to limit the scope of the Azure Pipelines access token to mentioned repositories. -When you do this, Azure Pipelines will add two more protections: +You can optionally protect repositories by limiting the scope of the Azure Pipelines access token. You provide agents with the access token only for repositories explicitly mentioned in the pipeline's `resources` section. -* The access token given to the agent for running jobs will only have access to repositories explicitly mentioned in the `resources` section of the pipeline. -* Repositories added to the pipeline will have to be authorized by someone with contribute access to the repository the first time that pipeline uses the repository. +Adding a repository to a pipeline requires authorization from a user with **Contribute** access to the repository. For more information, see [Protect a repository resource](../process/repository-resource.md). -This setting is on by default for all organizations created after May 2020. -Organizations created before that should enable it in **Organization settings**. +## Permissions -## Open resources +There are two types of permissions to protected resources, *user permissions* and *pipeline permissions*. -All the other resources in a project are considered *open* resources. -Open resources include: -- Artifacts -- Pipelines -- Test plans -- Work items +User permissions are the frontline of defense for protected resources. You should grant permissions only to users who require them. Members of the **User** role for a resource can manage approvals and checks. -You'll learn more about which pipelines can access what resources in the section on [projects](projects.md). +Pipeline permissions protect against copying protected resources to other pipelines. You must have the **Administrator** role to enable access to a protected resource across all pipelines in a project. -## User permissions +![Screenshot of user and pipeline permissions.](media/pipeline-permissions.png) -The first line of defense for protected resources is user permissions. -In general, ensure that you only give permissions to users who require them. -All protected resources have a similar security model. -A member of user role for a resource can: -- Remove approvers and checks configured on that resource -- Grant access to other users or pipelines to use that resource +To manage pipeline permissions, explicitly grant access to specific pipelines you trust. Make sure not to enable **Open access**, which allows all pipelines in the project to use the resource. For more information, see [About pipeline resources](../process/about-resources.md) and [Add resource protection](../library/add-resource-protection.md). -![Screenshot of user permissions on pipelines](media/user-permissions.png) -## Pipeline permissions +## Checks -When you use YAML pipelines, user permissions aren't enough to secure your protected resources. -You can easily copy the name of a protected resource (for example, a service connection for your production environment) and include that in a different pipeline. -Pipeline permissions protect against such copying. -For each of the protected resources, ensure that you've disabled the option to grant access to "all pipelines". -Instead, explicitly granted access to specific pipelines that you trust. +User and pipeline permissions don't completely secure protected resources in pipelines. You can also add *checks* that specify conditions to be satisfied before a stage in any pipeline can consume the resource. You can require specific approvals or other criteria before pipelines can use the protected resource. For more information, see [Define approvals and checks](../process/approvals.md). -![Screenshot of pipeline permissions](media/pipeline-permissions.png) +![Screenshot of configuring checks.](media/configure-checks.png) -## Checks +### Manual approval check + +You can block pipeline requests to use a protected resource until manually approved by specified users or groups. This check gives you the chance to review the code and provides an extra layer of security before proceeding with a pipeline run. + +### Protected branch check + +If you have manual code review processes for specific branches, you can extend this protection to pipelines. Branch control ensures that only authorized branches can access protected resources. A protected branch check for a resource prevents pipelines from automatically running on unauthorized branches. + +### Business Hours check + +Use this check to ensure that a pipeline deployment starts within a specified day and time window. + +## Next step + +> [!div class="nextstepaction"] +> [Group resources into a project structure](projects.md) -In YAML, a combination of user and pipeline permissions isn't enough to fully secure your protected resources. -Pipeline permissions to resources are granted to the whole pipeline. -Nothing prevents an adversary from creating another branch in your repository, injecting malicious code, and using the same pipeline to access that resource. -Even without malicious intent, most pipelines need a second set of eyes look over changes (especially to the pipeline itself) before deploying to production. -**Checks** allow you to pause the pipeline run until certain conditions are met: -- **Manual approval check**. -Every run that uses a project protected resource is blocked for your manual approval before proceeding. -Manual protection gives you the opportunity to review the code and ensure that it's coming from the right branch. -- **Protected branch check**. -If you have manual code review processes in place for some of your branches, you can extend this protection to pipelines. -Configure a protected branch check on each of your resources. -This will automatically stop your pipeline from running on top of any user branches. -- **Protected resource check** -You can add checks to environments, service connections, repositories, variable groups, agent pools, variable groups, and secure files to specify conditions that must be satisfied before a stage in any pipeline can consume a resource. Learn more about [checks and approvals](../process/approvals.md). - - - -![Screenshot of configuring checks](media/configure-checks.png) - -## Next steps - -Next, consider how you group resources into a [project structure](projects.md). diff --git a/docs/pipelines/security/secrets.md b/docs/pipelines/security/secrets.md new file mode 100644 index 00000000000..5f2dad010fb --- /dev/null +++ b/docs/pipelines/security/secrets.md @@ -0,0 +1,116 @@ +--- +title: Protect secrets in Azure Pipelines +description: Learn best practices for protecting secrets in Azure Pipelines. +ms.date: 07/05/2024 +monikerRange: '>= azure-devops-2020' +--- + +# Protect secrets in Azure Pipelines + +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] + +This article provides best practices on protecting secrets in Azure Pipelines. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, or cryptographic keys. + +Azure Pipelines doesn't generate secret values. However, you might need to add a secret to a pipeline to store sensitive data like an API key. To learn more about setting secret variables, see [Set secret variables](../process/set-secret-variables.md). + +[!INCLUDE [security-prerequisites](includes/security-prerequisites.md)] + +## Don't use secrets if another method is available + +The best method to protect a secret isn't to have a secret in the first place. Check to see if your pipeline can use a different method than using a secret to perform a task. + +* **Use service connections:** + - When you're targeting Azure or other services, use service connections instead of managing secrets in variables. + - Service connections allow you to securely connect to external services without exposing sensitive information directly in your pipeline configuration. + - For more information, see [Manage service connections](../library/service-endpoints.md) and [Connect to Microsoft Azure with an Azure Resource Manager service connection](../library/connect-to-azure.md). + +- **Use managed identities:** + - Consider using managed identities instead of handling secrets directly. + - Managed identities allow your applications and services to authenticate with Azure services without requiring explicit credentials. + - You can [use managed identities to access other Azure services](/entra/identity/managed-identities-azure-resources/managed-identities-status). + +- **Azure CLI task:** + - If you're using the [Azure CLI task](/azure/devops/pipelines/tasks/reference/azure-cli-v2), in your pipeline, consider using the `addSpnToEnvironment` setting to access service principal details in script without explicitly passing secrets. + +For more information, see [Use service principals & managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) + +## Use secret variables + +Never store sensitive values as plaintext in an Azure Pipelines **.yml** file. + +Secret variables can be used for private information like passwords, IDs, and other identifying data that you wouldn't want exposed in a pipeline. We recommend that you [set secret variables](../process/set-secret-variables.md) with Azure Key Vault. You can also set secret variables in the UI or in a variable group. We don't recommend using a logging command to set a secret variable. When you set a secret with a logging command, anyone who can access your pipeline can also see the secret. + +Secret variables are encrypted and can be used in pipelines without exposing their values. Although their values aren't exposed, never echo secrets as output and don't pass secrets on the command line. Instead, we suggest that you map your secrets into environment variables. + +When you create a secret, follow [variable naming guidelines](../process/variables.md#variable-naming-restrictions) and make sure that your secret name doesn't disclose sensitive information. + +### Limit access to secret variables + +To limit access to secrets in Azure DevOps, follow these best practices: + + - Store your secrets in [Azure Key Vault](/azure/key-vault/). With Azure Key Vault, you can then use Azure's role-based access control model to limit access to a secret or group of secrets. + - Set secret variables in the UI for a pipeline. Secret variables set in the pipeline settings UI for a pipeline are scoped to the pipeline where they're set. So, you can have secrets that are only visible to users with access to that pipeline. + - Set secrets in a variable group. Variable groups follow the [library security model](../library/index.md#library-security). You can control who can define new items in a library, and who can use an existing item. + +## Don't write secrets to logs + +Azure Pipelines attempts to scrub secrets from logs wherever possible, but it's not foolproof. Avoid echoing secrets to the console, using them in command line parameters, or logging them to files. Be cautious when you use Azure CLI commands that output sensitive information. Use the [`None output format`](https://aka.ms/clisecrets), and if you need to retrieve a secret from an Azure CLI call, [`Use none output format and retrieve security information to a secret variable`](/cli/azure/format-output-azure-cli#use-none-and-retrieve-security-information-at-a-later-time). + +## Don't use structured data as secrets + +Avoid using structured data formats like JSON, XML, or YAML, to encapsulate secret values, including control characters such as carriage return, `\r`, and line feed,`\n`. Instead, create individual secrets for each sensitive value. This approach ensures better redaction accuracy and minimizes the risk of exposing sensitive data inadvertently. + +## Audit how secrets are handled + +To audit how secrets are used in Azure Pipelines, follow these best practices: + +- **Review source code:** Examine the source code of the repository hosting the pipeline. To ensure secrets get handled correctly, check any tasks used in the pipeline. For instance, verify that secrets aren't inadvertently sent to unintended hosts or explicitly printed to log output. +- **Inspect run logs:** After testing valid and invalid inputs, view the run logs for your pipeline. Ensure that secrets are properly redacted and not exposed. Sometimes, errors in commands or tools might inadvertently leak secrets into error logs. While Azure Pipelines attempts to scrub secrets from logs, manual review is still essential. + +## Audit and rotate secrets + +To audit and rotate secrets, follow these best practices: + +- **Review registered secrets:** Periodically assess the secrets registered in your pipelines. Confirm that they're still necessary, and remove any that are no longer needed, which helps reduce clutter and potential security risks. +- **Rotate secrets:** Regularly rotate secrets to minimize the window of time during which a compromised secret could be exploited. By changing secrets periodically, you enhance security. +- [**Choose the right authentication method**](../../organizations/security/security-overview.md#choose-the-right-authentication-method) + - **Types of secrets used:** + - **[Personal access tokens (PATs)](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md):** These tokens are used for authentication. Follow security best practices when choosing the right authentication method. You can [manage PATs using the REST API](../../organizations/accounts/manage-personal-access-tokens-via-api.md). + - **[Secret variables](../process/set-secret-variables.md):** Use secret variables to securely store sensitive information like API keys, passwords, or other credentials within your pipeline. + - **[Azure Key Vault secrets](/azure/key-vault/general/overview):** Use Azure Key Vault to store and manage secrets securely. + - **[Service connections](../library/service-endpoints.md):** These service connections allow your pipeline to connect to external services (for example, Azure, GitHub, Docker Hub). Ensure proper configuration and secure handling of service connection secrets. + +## Use YAML templates + +Instead of including inline scripts with secret parameters directly in your pipeline YAML, use [templates](templates.md). This approach enhances security by abstracting sensitive information away from the main pipeline. + +To implement this approach, create a separate YAML file for your script and then store that script in a separate, secure repository. You can then reference the template and pass a secret variable in your YAML as a parameter. The secure variable should come from Azure Key Vault, a variable group, or the pipeline UI. For more information on using templates, see the [Template usage reference](../process/templates.md). + +## Limit secrets with branch policies and variable group permissions + +To make sure that secrets are tied to the `main` branch and not accessible to random branches, you can use a combination of variable group permissions, conditional job insertion, and branch policies. + +With branch policies, you can enforce [build validation policies](../../repos/git/branch-policies.md#build-validation) that only allow builds from the main branch. Then, you can use [variable group permissions](../library/variable-groups.md) to make sure that only authorized pipelines have access the secrets stored in your variable group. Last, you can use a condition in your pipeline to make sure that the variable group can only be referenced by a push to the `main` branch. + +```yaml +jobs: +- job: ExampleJob + condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')) + pool: + vmImage: 'ubuntu-latest' + steps: + - script: echo "This runs only for the main branch" + displayName: 'Conditional Step' + variables: + - group: your-variable-group-name +``` + +## Next steps + +> [!div class="nextstepaction"] +> [Best practices for protecting Azure secrets](/azure/security/fundamentals/secrets-best-practices) + +## Related articles + +- [Key and secret management considerations in Azure](/azure/well-architected/security/design-storage-keys) +- [Azure DevOps security overview](../../organizations/security/security-overview.md) diff --git a/docs/pipelines/security/secure-access-to-repos.md b/docs/pipelines/security/secure-access-to-repos.md index e91a33329e9..062e04569db 100644 --- a/docs/pipelines/security/secure-access-to-repos.md +++ b/docs/pipelines/security/secure-access-to-repos.md @@ -2,82 +2,73 @@ title: Secure access to Azure repositories from pipelines description: Secure access to Azure repositories from pipelines ms.author: sandrica -ms.date: 07/25/2022 +ms.date: 06/10/2024 monikerRange: '>= azure-devops-2020' --- # Secure access to Azure Repos from pipelines -Your repositories are a critical resource to your business success, because they contain the code that powers your business. Access to repositories shouldn't be granted easily. +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -This article shows you how to improve the security of your pipelines accessing Azure Repos, to limit the risk of your source code getting into the wrong hands. +Your repositories are vital for your business success as they house the code powering your operations. Access to repositories should be carefully controlled. This article guides you on enhancing [Build pipeline](#build-pipelines) and [Classic release pipeline](#classic-release-pipelines) security when accessing Azure Repos to mitigate the risk of unauthorized access. -The setup for pipelines to securely access Azure repositories is one in which the toggles _Limit job authorization scope to current project for non-release pipelines_, _Limit job authorization scope to current project for release pipelines_, and _Protect access to repositories in YAML pipelines_, are enabled. +To ensure secure access to Azure repositories, enable the following toggles: +- **Limit job authorization scope to current project for non-release pipelines** +- **Limit job authorization scope to current project for release pipelines** +- **Protect access to repositories in YAML pipelines** -We'll cover both build pipelines and classic release pipelines: - -- [Build pipelines](#build-pipelines) -- [Classic release pipelines](#classic-release-pipelines) +[!INCLUDE [security-prerequisites](includes/security-prerequisites.md)] ## Basic process -The steps are similar across all pipelines: - -1. Determine the list of Azure Repos repositories your pipeline needs access to that are part of the same organization, but are in different projects. - - You can compile the list of repositories by inspecting your pipeline. Or, you can turn on the _Limit job authorization scope to current project for (non-)release pipelines_ toggle and note which repositories your pipeline fails to check out. Submodule repositories may not show up in the first failed run. - -2. For each Azure DevOps project that contains a repository your pipeline needs to access, follow the steps to [grant the pipeline's build identity access to that project](../process/access-tokens.md#configure-permissions-for-a-project-to-access-another-project-in-the-same-project-collection). +The following steps to secure your pipelines are similar across all pipelines: -3. For each Azure Repos repository your pipeline checks out, follow the steps to [grant the pipeline's build identity _Read_ access to that repository](../process/access-tokens.md#example---configure-permissions-to-access-another-repo-in-the-same-project-collection). - -4. For each repository that is used as a submodule by a repository your pipeline checks out and is in the same project, follow the steps to [grant the pipeline's build identity _Read_ access to that repository](../process/access-tokens.md#example---configure-permissions-to-access-another-repo-in-the-same-project-collection). - -5. Turn on the _Limit job authorization scope to current project for non-release pipelines_, _Limit job authorization scope to current project for release pipelines_, and _Protect access to repositories in YAML pipelines_ toggles. +1. Identify the Azure Repos repositories that your pipeline requires access to within the same organization but across different projects.
      + Do so by inspecting your pipeline or enable **Limit job authorization scope to current project for (non-)release pipelines** and note which repositories your pipeline fails to check out. Submodule repositories might not show up in the first failed run. +2. [Grant the pipeline's build identity access to that project](../process/access-tokens.md#configure-permissions-for-a-project-to-access-another-project-in-the-same-project-collection) for each project that contains a repository your pipeline needs to access. +3. [Grant the pipeline's build identity **Read** access to that repository](../process/access-tokens.md#example---configure-permissions-to-access-another-repo-in-the-same-project-collection) for each repository your pipeline checks out. +4. [Grant the pipeline's build identity **Read** access to that repository](../process/access-tokens.md#example---configure-permissions-to-access-another-repo-in-the-same-project-collection) for each repository that is used as a submodule by a repository your pipeline checks out and is in the same project. +5. Enable **Limit job authorization scope to current project for non-release pipelines**, **Limit job authorization scope to current project for release pipelines**, and **Protect access to repositories in YAML pipelines**. ## Build pipelines -To illustrate the steps to take to improve the security of your pipelines when they access Azure Repos, we'll use a running example. - -Assume you're working on the `SpaceGameWeb` pipeline hosted in the `fabrikam-tailspin/SpaceGameWeb` project, in the `SpaceGameWeb` Azure Repos repository. Furthermore, let's say your `SpaceGameWeb` pipeline checks out the `SpaceGameWebReact` repository in the same project, and the `FabrikamFiber` and `FabrikamChat` repositories in the `fabrikam-tailspin/FabrikamFiber` project. - -Finally, assume the `FabrikamFiber` repository uses the `FabrikamFiberLib` repository as a submodule, hosted in the same project. Read more about [how to check out submodules](../repos/pipeline-options-for-git.md#checkout-submodules). +To illustrate the steps to take to improve the security of your pipelines when they access Azure Repos, we use the following example. -The `SpaceGameWeb` project's repository structures look like in the following screenshot. +- Assume you're working on the `SpaceGameWeb` pipeline hosted in the `fabrikam-tailspin/SpaceGameWeb` project, in the `SpaceGameWeb` Azure Repos repository. +- Your `SpaceGameWeb` pipeline checks out the `SpaceGameWebReact` repository in the same project, and the `FabrikamFiber` and `FabrikamChat` repositories in the `fabrikam-tailspin/FabrikamFiber` project. +- The `FabrikamFiber` repository uses the `FabrikamFiberLib` repository as a submodule, hosted in the same project. +- The `SpaceGameWeb` project's repository structures look like in the following screenshot. + :::image type="content" source="media/spacegame-repository-structure.png" alt-text="Screenshot of the SpaceGameWeb repository structure."::: +- The `FabrikamFiber` project's repository structures look like in the following screenshot. + :::image type="content" source="media/fabrikam-repository-structure.png" alt-text="Screenshot of the FabrikamFiber repository structure."::: +- Imagine your project isn't set up to use a project-based build identity or to protect access to repositories in YAML pipelines. Also, assume you already successfully ran your pipeline. -:::image type="content" source="media/spacegame-repository-structure.png" alt-text="Screenshot of the SpaceGameWeb repository structure."::: +### Use a project-based build identity for build pipelines -The `FabrikamFiber` project's repository structures look like in the following screenshot. +During pipeline execution, an identity gets used to access resources, such as repositories, service connections, and variable groups. Pipelines can utilize two types of identities: project-level and collection-level. The former prioritizes security, while the latter emphasizes ease of use. For more information, see [scoped build identities](../process/access-tokens.md#scoped-build-identities) and [job authorization scope](../process/access-tokens.md#job-authorization-scope). -:::image type="content" source="media/fabrikam-repository-structure.png" alt-text="Screenshot of the FabrikamFiber repository structure."::: +For enhanced security, use project-level identities when you run your pipelines. These identities can only access resources within their associated project, minimizing the risk of unauthorized access by malicious actors. -Image your project isn't set up to use a project-based build identity or to protect access to repositories in YAML pipelines. Also, assume you've already successfully ran your pipeline. - -### Use a Project-based build identity for build pipelines - -When a pipeline executes, it uses an identity to access various resources, such as repositories, service connections, variable groups. There are two types of identities a pipeline can use: a project-level one and a collection-level one. The former provides better security, the latter provides ease of use. Read more about [scoped build identities](../process/access-tokens.md#scoped-build-identities) and [job authorization scope](../process/access-tokens.md#job-authorization-scope). - -We recommend you use project-level identities for running your pipelines. By default, project-level identities can only access resources in the project of which they're a member. Using this identity improves security, because it reduces the access gained by a malicious person when hijacking your pipeline. - -To make your pipeline use a project-level identity, turn on the _Limit job authorization scope to current project for non-release pipelines_ setting. +To configure your pipeline to use a project-level identity, enable the **Limit job authorization scope to current project for non-release pipelines** setting. In our running example, when this toggle is off, the `SpaceGameWeb` pipeline can access all repositories in all projects. When the toggle is on, `SpaceGameWeb` can only access resources in the `fabrikam-tailspin/SpaceGameWeb` project, so only the `SpaceGameWeb` and `SpaceGameWebReact` repositories. -If you run our example pipeline, when you turn on the toggle, the pipeline will fail, and the error logs will tell you `remote: TF401019: The Git repository with name or identifier FabrikamChat does not exist or you do not have permissions for the operation you are attempting.` and `remote: TF401019: The Git repository with name or identifier FabrikamFiber does not exist or you do not have permissions for the operation you are attempting.` +If you run our example pipeline, when you turn on the toggle, the pipeline fails, and the error logs tell you `remote: TF401019: The Git repository with name or identifier FabrikamChat does not exist or you do not have permissions for the operation you are attempting.` and `remote: TF401019: The Git repository with name or identifier FabrikamFiber does not exist or you do not have permissions for the operation you are attempting.` -To fix the checkout issues, follow the steps described in [Basic process](#basic-process). +To fix the checkout issues, follow the steps described in the [Basic process](#basic-process) section of this article. -Additionally, you need to explicitly check out the submodule repositories, _before_ the repositories that use them. In our example, it means the `FabrikamFiberLib` repository. +Additionally, explicitly check out the submodule repositories, _before_ the repositories that use them. In our example, it means the `FabrikamFiberLib` repository. -If you now run our example pipeline, it will succeed. +If you run our example pipeline, it succeeds. ### Further configuration -To further improve security when accessing Azure Repos, consider turning on the _Protect access to repositories in YAML pipelines_ setting. +To further improve security when you access Azure Repos, consider enabling **Protect access to repositories in YAML pipelines**. ## [YAML pipelines](#tab/yaml) Assume the `SpaceGameWeb` pipeline is a YAML pipeline, and its YAML source code looks similar to the following code. + ```yml trigger: - main @@ -114,19 +105,21 @@ steps: ### Protect access to repositories in YAML pipelines -Azure DevOps provides a fine-grained permissions mechanism for Azure Repos repositories, in the form of the _Protect access to repositories in YAML pipelines_ setting. This setting makes a YAML pipeline explicitly ask for permission to access _all_ Azure Repos repositories, regardless of which project they belong to. Read more about [this setting](../process/access-tokens.md#protect-access-to-repositories-in-yaml-pipelines). Checking out other types of repositories, for example, GitHub-hosted ones, isn't affected by this setting. +Azure DevOps provides a fine-grained permissions mechanism for Azure Repos repositories, in the form of the **Protect access to repositories in YAML pipelines** setting. This setting makes a YAML pipeline explicitly ask for permission to access _all_ Azure Repos repositories, regardless of which project they belong to. For more information, see [access repos](../process/access-tokens.md#protect-access-to-repositories-in-yaml-pipelines). This setting doesn't affect checking out other types of repositories, such as GitHub-hosted ones. -In our running example, when this toggle is on, the `SpaceGameWeb` pipeline will ask permission to access the `SpaceGameWebReact` repository in the `fabrikam-tailspin/SpaceGameWeb` project, and the `FabrikamFiber` and `FabrikamChat` repositories in the `fabrikam-tailspin/FabrikamFiber` project. +In our running example, when this setting is turned on, the `SpaceGameWeb` pipeline asks permission to access the `SpaceGameWebReact` repository in the `fabrikam-tailspin/SpaceGameWeb` project, and the `FabrikamFiber` and `FabrikamChat` repositories in the `fabrikam-tailspin/FabrikamFiber` project. + +When you run the example pipeline, it builds similar to the following example. -When you run the example pipeline, you'll see a build similar to the following screenshot. :::image type="content" source="media/running-the-pipeline-first-time.png" alt-text="Screenshot of running the SpaceGameWeb pipeline the first time after turning on the Protect access to repositories in YAML pipelines toggle."::: -You'll be asked to grant permission to the repositories your pipeline checks out or has defined as resources. - :::image type="content" source="media/asked-to-grant-permission.png" alt-text="Screenshot of being asked to grant permission to the SpaceGameWeb pipeline to access three repositories."::: +Grant permission to your pipeline repositories or resources. + +:::image type="content" source="media/asked-to-grant-permission.png" alt-text="Screenshot of being asked to grant permission to the SpaceGameWeb pipeline to access three repositories."::: -Once you do, your pipeline will run, but it will fail because it will not be able to check out the `FabrikamFiberLib` repository as a submodule of `FabrikamFiber`. To solve this issue, explicitly check out the `FabrikamFiberLib`, for example, add a `- checkout: git://FabrikamFiber/FabrikamFiberLib` step, before the `-checkout: FabrikamFiber` step. +Your pipeline runs, but fails because it can't check out the `FabrikamFiberLib` repository as a submodule of `FabrikamFiber`. To solve this issue, explicitly check out the `FabrikamFiberLib`, by adding a `- checkout: git://FabrikamFiber/FabrikamFiberLib` step, before the `-checkout: FabrikamFiber` step. -If you now run the example pipeline, it will succeed. +The example pipeline succeeds. Our final YAML pipeline source code looks like the following code snippet. ```yml @@ -165,39 +158,39 @@ steps: ### Troubleshooting -Here are a couple of problematic situations and how to handle them. +Use the following solutions for any issues that arise. #### You use git in command line to check out repositories in the same organization -For example, you're using `- script: git clone https://$(System.AccessToken)@dev.azure.com/fabrikam-tailspin/FabrikamFiber/_git/OtherRepo/`. The command will fail when the _Protect access to repositories in YAML pipelines_ toggle is on. +For example, you're using `- script: git clone https://$(System.AccessToken)@dev.azure.com/fabrikam-tailspin/FabrikamFiber/_git/OtherRepo/`. The command fails when the **Protect access to repositories in YAML pipelines** setting is turned on. -To solve the issue, check out the `OtherRepo` repository using the `checkout` command, for example, `- checkout: git://FabrikamFiber/OtherRepo`. +To solve the issue, check out the `OtherRepo` repository using the `checkout` command, such as `- checkout: git://FabrikamFiber/OtherRepo`. #### A repository is using another repository as submodule Say one of the repositories your pipeline checks out uses another repository (in the same project) as submodule, as is the case in our example for the `FabrikamFiber` and `FabrikamFiberLib` repositories. Read more about [how to check out submodules](../repos/pipeline-options-for-git.md#checkout-submodules). -Furthermore, assume you gave the `SpaceGame` build identity _Read_ access to this repo, but the checkout of the `FabrikamFiber` repository still fails when checking out the `FabrikamFiberLib` submodule. +Furthermore, assume you gave the `SpaceGame` build identity **Read** access to this repo, but the checkout of the `FabrikamFiber` repository still fails when checking out the `FabrikamFiberLib` submodule. -To solve this issue, explicitly check out the `FabrikamFiberLib`, for example, add a `- checkout: git://FabrikamFiber/FabrikamFiberLib` step before the `-checkout: FabrikamFiber` one. +To solve this issue, explicitly check out the `FabrikamFiberLib`, by adding a `- checkout: git://FabrikamFiber/FabrikamFiberLib` step before the `-checkout: FabrikamFiber` one. ## [Classic build pipelines](#tab/classic) -In classic build pipelines, you can't explicitly declare other repositories as resources. The way you check out more Azure Repos repositories is by adding command-line tasks with `git clone` commands, similar to the following command to check out the `FabrikamFiber` repository: `git -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" clone --recurse-submodules https://dev.azure.com/silviuandrica/FabrikamFiber/_git/FabrikamFiber`. +In classic build pipelines, you can't explicitly declare other repositories as resources. Check out more Azure Repos repositories by adding command-line tasks with `git clone` commands, similar to the following command to check out the `FabrikamFiber` repository: `git -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" clone --recurse-submodules https://dev.azure.com/silviuandrica/FabrikamFiber/_git/FabrikamFiber`. -### The _Protect access to repositories in YAML pipelines_ setting +### The **Protect access to repositories in YAML pipelines** setting -The _Protect access to repositories in YAML pipelines_ setting makes a YAML pipeline explicitly ask for permission to access _all_ Azure Repos repositories, regardless of which project they belong to. Read more about [this setting](../process/access-tokens.md#protect-access-to-repositories-in-yaml-pipelines). +The **Protect access to repositories in YAML pipelines** setting makes a YAML pipeline explicitly ask for permission to access _all_ Azure Repos repositories, regardless of which project they belong to. For more information, see [Access tokens, Protect access to repositories in YAML pipelines](../process/access-tokens.md#protect-access-to-repositories-in-yaml-pipelines). -Be careful when turning on the _Protect access to repositories in YAML pipelines_ setting. If you do, your classic build pipelines won't be able to access any other Azure DevOps repository, except for the one specified in its Settings. In our example pipeline, you'll get an error and the log message `TF401019: The Git repository with name or identifier FabrikamFiber does not exist or you do not have permissions for the operation you are attempting.` +Be careful when turning on the **Protect access to repositories in YAML pipelines** setting. If you do, your classic build pipelines can't access any other Azure DevOps repository, except for the one specified in its Settings. In our example pipeline, you get an error and the log message `TF401019: The Git repository with name or identifier FabrikamFiber does not exist or you do not have permissions for the operation you are attempting.` -If your project has both YAML and classic build pipelines _and_ your classic build pipelines check out other Azure DevOps repositories in addition to the ones specified in their settings, then you want to create two projects, one for the YAML pipelines and one for the classic build pipelines. Then, in the YAML pipelines project, you can turn on the setting. +If your project uses both YAML and classic build pipelines, and your classic build pipelines check out more Azure DevOps repositories beyond the ones specified in their settings, create two projects, one for the YAML pipelines and one for classic build pipelines. Then, in the YAML pipelines project, enable the desired setting. -The _Protect access to repositories in YAML pipelines_ setting doesn't apply to repositories hosted on other services, such as GitHub. +The **Protect access to repositories in YAML pipelines** setting doesn't apply to repositories hosted on other services, such as GitHub. -#### The _Build job authorization scope_ setting +#### The **Build job authorization scope** setting -The _Limit job authorization scope to current project for non-release pipelines_ setting overrides the _Build job authorization scope_ setting. If you turn the former on, your pipeline will run with project-based identity, even if your _Build job authorization scope_ specifies _Project collection_. +The **Limit job authorization scope to current project for non-release pipelines** setting overrides the **Build job authorization scope** setting. If you turn the former on, your pipeline runs with project-based identity, even if your **Build job authorization scope** specifies **Project collection**. :::image type="content" source="media/build-job-authorization-scope.png" alt-text="Screenshot of the successful run of the Build job authorization scope setting."::: @@ -207,28 +200,28 @@ The _Limit job authorization scope to current project for non-release pipelines_ The process for securing access to repositories for release pipelines is similar to the one for [build pipelines](#build-pipelines). -To illustrate the steps you need to take, we'll use a running example. In our example, there's a release pipeline named `FabrikamFiberDocRelease` in the `fabrikam-tailspin/FabrikamFiberDocRelease` project. Assume the pipeline checks out the `FabrikamFiber` repository in the `fabrikam-tailspin/FabrikamFiber` project, runs a command to generate public documentation, and then publishes it to a website. Additionally, imagine the `FabrikamFiber` repository uses the `FabrikamFiberLib` repository (in the same project) as a submodule +To illustrate the steps you need to take, we use a running example. In our example, there's a release pipeline named `FabrikamFiberDocRelease` in the `fabrikam-tailspin/FabrikamFiberDocRelease` project. Assume the pipeline checks out the `FabrikamFiber` repository in the `fabrikam-tailspin/FabrikamFiber` project, runs a command to generate public documentation, and then publishes it to a website. Additionally, imagine the `FabrikamFiber` repository uses the `FabrikamFiberLib` repository (in the same project) as a submodule. ### Use a Project-based build identity for classic release pipelines -When a pipeline executes, it uses an identity to access various resources, such as repositories, service connections, variable groups. There are two types of identities a pipeline can use: a project-level one and a collection-level one. The former provides better security, the latter provides ease of use. Read more about [scoped build identities](../process/access-tokens.md#scoped-build-identities) and [job authorization scope](../process/access-tokens.md#job-authorization-scope). +When a pipeline executes, it uses an identity to access various resources, such as repositories, service connections, variable groups. There are two types of identities a pipeline can use: a project-level one and a collection-level one. The former provides better security. The latter provides ease of use. Read more about [scoped build identities](../process/access-tokens.md#scoped-build-identities) and [job authorization scope](../process/access-tokens.md#job-authorization-scope). We recommend you use project-level identities for running your pipelines. By default, project-level identities can only access resources in the project of which they're a member. Using this identity improves security, because it reduces the access gained by a malicious person when hijacking your pipeline. -To make your pipeline use a project-level identity, turn on the _Limit job authorization scope to current project for release pipelines_ setting. +To make your pipeline use a project-level identity, turn on the **Limit job authorization scope to current project for release pipelines** setting. In our running example, when this toggle is off, the `FabrikamFiberDocRelease` release pipeline can access all repositories in all projects, including the `FabrikamFiber` repository. When the toggle is on, `FabrikamFiberDocRelease` can only access resources in the `fabrikam-tailspin/FabrikamFiberDocRelease` project, so the `FabrikamFiber` repository becomes inaccessible. -If you run our example pipeline, when you turn on the toggle, the pipeline will fail, and the logs will tell you `remote: TF401019: The Git repository with name or identifier FabrikamFiber does not exist or you do not have permissions for the operation you are attempting.` +If you run our example pipeline, when you turn on the toggle, the pipeline fails, and the logs tell you `remote: TF401019: The Git repository with name or identifier FabrikamFiber does not exist or you do not have permissions for the operation you are attempting.` -To fix these issues, follow the steps in [Basic process](#basic-process). +To fix these issues, follow the steps in the [Basic process](#basic-process) section of this article. -If you now run our example pipeline, it will succeed. +Our example pipeline succeeds. -## See also +## Related articles - [Scoped build identities](../process/access-tokens.md#scoped-build-identities) - [Job authorization scope](../process/access-tokens.md#job-authorization-scope) - [Grant a pipeline's build identity access to a project](../process/access-tokens.md#configure-permissions-for-a-project-to-access-another-project-in-the-same-project-collection) - [Grant a pipeline's build identity _Read_ access to a repository](../process/access-tokens.md#example---configure-permissions-to-access-another-repo-in-the-same-project-collection) -- [How to check out submodules](../repos/pipeline-options-for-git.md#checkout-submodules) \ No newline at end of file +- [How to check out submodules](../repos/pipeline-options-for-git.md#checkout-submodules) diff --git a/docs/pipelines/security/templates.md b/docs/pipelines/security/templates.md index 036e42cdec8..4552b0f621c 100644 --- a/docs/pipelines/security/templates.md +++ b/docs/pipelines/security/templates.md @@ -1,39 +1,46 @@ --- -title: Security through templates -description: Using template features to improve pipeline security. +title: Use templates for security +description: Learn about using template features to improve pipeline security. ms.assetid: 73d26125-e3ab-4e18-9bcd-387fb21d3568 ms.reviewer: vijayma -ms.date: 01/24/2023 +ms.date: 07/18/2024 +ms.topic: conceptual monikerRange: '>= azure-devops-2020' --- -# Security through templates +# Use templates for security [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -[Checks on protected resources](resources.md) are the basic building block of security for Azure Pipelines. -Checks work no matter the structure - the stages and jobs - of your pipeline. -If several pipelines in your team or organization have the same structure, you can further simplify security using [templates](../process/templates.md). +This article describes how templates can streamline security for Azure Pipelines. Templates can define the outer structure of your pipeline and help prevent malicious code infiltration. Templates can also automatically include steps to do tasks such as credential scanning. If multiple pipelines within your team or organization share the same structure, consider using templates. -Azure Pipelines offers two kinds of templates: **includes** and **extends**. -Included templates behave like `#include` in C++: it's as if you paste the template's code right into the outer file, which references it. For example, here an includes template (`include-npm-steps.yml`) is inserted into `steps`. +[Checks on protected resources](resources.md) form the fundamental security framework for Azure Pipelines. These checks apply regardless of pipeline structure, stages, and jobs. You can use templates to help enforce these checks. -```yaml - steps: - - template: templates/include-npm-steps.yml -``` +[!INCLUDE [security-prerequisites](includes/security-prerequisites.md)] + +## Includes and extends templates + +Azure Pipelines provides *includes* and *extends* templates. + +- Includes templates include the template's code directly in the outer file that references it, similar to `#include` in C++. The following example pipeline inserts the *include-npm-steps.yml* template into the `steps` section. + + ```yaml + steps: + - template: templates/include-npm-steps.yml + ``` -To continue the C++ metaphor, `extends` templates are more like inheritance: the template provides the outer structure of the pipeline and a set of places where the template consumer can make targeted alterations. +- Extends templates define the outer structure of the pipeline and offer specific points for targeted customizations. In the context of C++, `extends` templates resemble inheritance. -## Use extends templates +When you use `extends` templates, you can also use `includes` in both the template and the final pipeline to do common configuration pieces. For a complete reference, see the [Template usage reference](../process/templates.md). -For the most secure pipelines, we recommend starting with `extends` templates. -By providing the outer structure, a template can prevent malicious code from getting into your pipeline. -You can still use `includes`, both in the template and in the final pipeline, to factor out common pieces of configuration. -To use an extends template, your pipeline might look like the below example. + +## Extends templates + +For the most secure pipelines, start by using extends templates. These templates define the outer structure of the pipeline and prevent malicious code from infiltrating the pipeline. + +For example, the following template file is named *template.yml*. ```yaml -# template.yml parameters: - name: usersteps type: stepList @@ -43,6 +50,8 @@ steps: - ${{ step }} ``` +The following pipeline extends the *template.yml* template. + ```yaml # azure-pipelines.yml resources: @@ -60,20 +69,20 @@ extends: - script: echo This is my second step ``` -When you set up `extends` templates, consider anchoring them to a particular Git branch or tag. -That way, if breaking changes need to be made, existing pipelines won't be affected. -The examples above use this feature. +>[!TIP] +>When you set up `extends` templates, consider anchoring them to a particular Git branch or tag so if there are breaking changes, existing pipelines aren't affected. The preceding example uses this feature. -## Security features enforced through YAML +## YAML pipeline security features -There are several protections built into the YAML syntax, and an extends template can enforce the usage of any or all of them. +The YAML pipeline syntax includes several built-in protections. Extends template can enforce their use. To enhance pipeline security, you can implement any of the following restrictions. ### Step targets -Restrict some steps to run in a container instead of the host. -Without access to the agent's host, user steps can't modify agent configuration or leave malicious code for later execution. -Run code on the host first to make the container more secure. -For instance, we recommend limiting access to network. -Without open access to the network, user steps will be unable to access packages from unauthorized sources, or upload code and secrets to a network location. + +You can restrict certain steps to run in a container rather than on the host. Steps in containers don't have access to the agent's host, preventing these steps from modifying agent configuration or leaving malicious code for later execution. + +For example, consider limiting network access. Without open network access, user steps can't retrieve packages from unauthorized sources or upload code and secrets to external network locations. + +The following example pipeline runs steps on the agent host before running steps inside a container. ```yaml resources: @@ -81,7 +90,7 @@ resources: - container: builder image: mysecurebuildcontainer:latest steps: -- script: echo This step runs on the agent host, and it could use docker commands to tear down or limit the container's network +- script: echo This step runs on the agent host, and it could use Docker commands to tear down or limit the container's network - script: echo This step runs inside the builder container target: builder ``` @@ -90,12 +99,11 @@ steps: ### Agent logging command restrictions -Restrict what services the Azure Pipelines agent will provide to user steps. -Steps request services using "logging commands" (specially formatted strings printed to stdout). -In restricted mode, most of the agent's services such as uploading artifacts and attaching test results are unavailable. +You can restrict the services the Azure Pipelines agent provides to user steps. User steps request services by using *logging commands*, which are specially formatted strings printed to standard output. In restricted mode, most of the agent's services, such as uploading artifacts and attaching test results, are unavailable. + +The following example task fails because its `target` property instructs the agent not to allow publishing artifacts. ```yaml -# this task will fail because its `target` property instructs the agent not to allow publishing artifacts - task: PublishBuildArtifacts@1 inputs: artifactName: myartifacts @@ -103,10 +111,13 @@ In restricted mode, most of the agent's services such as uploading artifacts and commands: restricted ``` -One of the commands still allowed in restricted mode is the `setvariable` command. Because pipeline variables are exported as environment variables to subsequent tasks, tasks that output user-provided data (for example, the contents of open issues retrieved from a REST API) can be vulnerable to injection attacks. Such user content can set environment variables that can in turn be used to exploit the agent host. To disallow this, pipeline authors can explicitly declare which variables are settable via the `setvariable` logging command. Specifying an empty list disallows setting all variables. +In `restricted` mode, the `setvariable` command remains permissible, so caution is necessary because pipeline variables are exported as environment variables to subsequent tasks. If tasks output user-provided data, such as open issues retrieved via a REST API, they might be vulnerable to injection attacks. Malicious user content could set environment variables that might be exploited to compromise the agent host. + +To mitigate this risk, pipeline authors can explicitly declare which variables are settable by using the `setvariable` logging command. When you specify an empty list, all variable setting is disallowed. + +The following example task fails because the task is only allowed to set the `expectedVar` variable or a variable prefixed with `ok`. ```yaml -# this task will fail because the task is only allowed to set the 'expectedVar' variable, or a variable prefixed with "ok" - task: PowerShell@2 target: commands: restricted @@ -119,10 +130,9 @@ One of the commands still allowed in restricted mode is the `setvariable` comman Write-Host "##vso[task.setvariable variable=BadVar]myValue" ``` -### Conditional insertion of stages or jobs +### Conditional stage or job execution -Restrict stages and jobs to run under specific conditions. -Conditions can help, for example, to ensure that you are only building certain branches. +You can restrict stages and jobs to run only under specific conditions. In the following example, the condition ensures that restricted code builds only for the main branch. ```yaml jobs: @@ -135,17 +145,13 @@ jobs: - script: echo Building the restricted part that only builds for main branch ``` -### Require certain syntax with extends templates +### Syntax modification -Templates can iterate over and alter/disallow any YAML syntax. -Iteration can force the use of particular YAML syntax including the above features. +Azure Pipelines templates have the flexibility to iterate over and modify YAML syntax. By using iteration, you can enforce specific YAML security features. -A template can rewrite user steps and only allow certain approved tasks to run. -You can, for example, prevent inline script execution. +A template can also rewrite user steps, allowing only approved tasks to run. For example, you can prevent inline script execution. -> [!WARNING] -> In the example below, the steps type "bash", "powershell", "pwsh" and "script" are prevented from executing. -> For full lockdown of ad-hoc scripts, you would also need to block "BatchScript" and "ShellScript". +The following example template prevents the step types `bash`, `powershell`, `pwsh`, and `script` from running. For complete lockdown of ad-hoc scripts, you could also block `BatchScript` and `ShellScript`. ```yaml # template.yml @@ -157,7 +163,7 @@ steps: - ${{ each step in parameters.usersteps }}: - ${{ if not(or(startsWith(step.task, 'Bash'),startsWith(step.task, 'CmdLine'),startsWith(step.task, 'PowerShell'))) }}: - ${{ step }} - # The lines below will replace tasks like Bash@3, CmdLine@2, PowerShell@2 + # The following lines replace tasks like Bash@3, CmdLine@2, PowerShell@2 - ${{ else }}: - ${{ each pair in step }}: ${{ if eq(pair.key, 'inputs') }}: @@ -173,6 +179,8 @@ steps: displayName: 'Disabled by template: ${{ step.displayName }}' ``` +In the following pipeline that extends this template, the script steps are stripped out and not run. + ```yaml # azure-pipelines.yml extends: @@ -196,9 +204,9 @@ extends: ### Type-safe parameters -Templates and their parameters are turned into constants before the pipeline runs. -[Template parameters](../process/template-parameters.md) provide type safety to input parameters. -For instance, it can restrict which pools can be used in a pipeline by offering an enumeration of possible options rather than a freeform string. +Before a pipeline runs, templates and their parameters are transformed into constants. [Template parameters](../process/template-parameters.md) can enhance type safety for input parameters. + +In the following example template, the parameters restrict the available pipeline pool options by providing an enumeration of specific choices instead of allowing freeform strings. ```yaml # template.yml @@ -216,6 +224,8 @@ steps: - script: # ... removed for clarity ``` +When the pipeline extends the template, it has to specify one of the available pool choices. + ```yaml # azure-pipelines.yml extends: @@ -224,22 +234,47 @@ extends: userpool: private-pool-1 ``` -### Set required templates +::: moniker range=">=azure-devops" + +### Template steps + +A template can automatically include steps in a pipeline. These steps can do tasks such as credential scanning or static code checks. The following template inserts steps before and after the user steps in every job. + +```yaml +parameters: + jobs: [] + +jobs: +- ${{ each job in parameters.jobs }}: + - ${{ each pair in job }}: + ${{ if ne(pair.key, 'steps') }}: + ${{ pair.key }}: ${{ pair.value }} + steps: + - task: CredScan@1 + - ${{ job.steps }} + - task: PublishMyTelemetry@1 + condition: always() +``` +::: moniker-end + +## Template enforcement -To require that a specific template gets used, you can set the [required template check](../process/approvals.md#required-template) for a resource or environment. The required template check can be used when extending from a template. +Templates are a valuable security mechanism, but their effectiveness relies on enforcement. The key control points for enforcing template usage are [protected resources](resources.md). You can configure approvals and checks for your agent pool or other protected resources such as repositories. For an example, see [Add a repository resource check](../process/repository-resource.md#add-a-repository-resource-check). -You can check on the status of a check when viewing a pipeline job. When a pipeline doesn't extend from the require template, the check will fail and the run will stop. You will see that your check failed. + +### Required templates - > [!div class="mx-imgBorder"] - > ![approval check fails](../process/media/approval-fail.png) +To enforce the use of a specific template, configure the [required template check](../process/approvals.md#required-template) for a resource. This check applies only when the pipeline extends from a template. -When the required template is used, you'll see that your check passed. +When you view the pipeline job, you can monitor the check's status. If the pipeline doesn't extend from the required template, the check fails. The run stops and notifies you of the failed check. - > [!div class="mx-imgBorder"] - > ![approval check passes](../process/media/approval-pass.png) +:::image type="content" source="../process/media/approval-fail.png" alt-text="Screenshot showing a failed approval check."::: +When you use the required template, the check passes. -Here the template `params.yml` is required with an approval on the resource. To trigger the pipeline to fail, comment out the reference to `params.yml`. +:::image type="content" source="../process/media/approval-pass.png" alt-text="Screenshot showing a passed approval check."::: + +The following *params.yml* template must be referenced in any pipeline that extends it. ```yaml # params.yml @@ -261,6 +296,8 @@ steps: - script: echo ${{ parameters.image }} ``` +The following example pipeline extends the *params.yml* template and requires it for approval. To demonstrate a pipeline failure, comment out the reference to *params.yml*. + ```yaml # azure-pipeline.yml @@ -275,40 +312,11 @@ extends: parameters: yesNo: true image: 'windows-latest' - ``` -::: moniker range=">=azure-devops" - -### Additional steps - -A template can add steps without the pipeline author having to include them. -These steps can be used to run credential scanning or static code checks. - -```yaml -# template to insert a step before and after user steps in every job -parameters: - jobs: [] - -jobs: -- ${{ each job in parameters.jobs }}: # Each job - - ${{ each pair in job }}: # Insert all properties other than "steps" - ${{ if ne(pair.key, 'steps') }}: - ${{ pair.key }}: ${{ pair.value }} - steps: # Wrap the steps - - task: CredScan@1 # Pre steps - - ${{ job.steps }} # Users steps - - task: PublishMyTelemetry@1 # Post steps - condition: always() -``` -::: moniker-end - - -## Template enforcement - -A template is only a security mechanism if you can enforce it. -The control point to enforce use of templates is a [protected resource](resources.md). -You can configure approvals and checks on your agent pool or other protected resources like repositories. For an example, see [Add a repository resource check](../process/repository-resource.md#add-a-repository-resource-check). -## Next steps +## Related content -Next, learn about taking inputs safely through [variables and parameters](inputs.md). +- [Template usage reference](../process/templates.md) +- [Secure variables and parameters in pipelines](inputs.md) +- [Resource security](resources.md) +- [Approvals and checks](../process/approvals.md) diff --git a/docs/pipelines/targets/azure-sqldb.md b/docs/pipelines/targets/azure-sqldb.md index d8175007114..9681d39edd4 100644 --- a/docs/pipelines/targets/azure-sqldb.md +++ b/docs/pipelines/targets/azure-sqldb.md @@ -1,10 +1,9 @@ --- title: Deploy to Azure SQL Database -description: Deploy to an Azure SQL database from Azure Pipelines or TFS +description: Learn how to deploy an Azure SQL database with Azure Pipelines. ms.assetid: B4255EC0-1A25-48FB-B57D-EC7FDB7124D9 -ms.topic: conceptual -ms.custom: seodec18 -ms.date: 04/20/2022 +ms.topic: how-to +ms.date: 04/02/2025 monikerRange: '<= azure-devops' --- @@ -12,18 +11,37 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -[!INCLUDE [temp](../includes/concept-rename-note.md)] - You can automatically deploy your database updates to Azure SQL database after every successful build. +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|--------------------------------| +| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).
      - **Permissions:**
          - To create service connections, you must have the *Administrator* or *Creator* role for [service connections](../library/add-resource-protection.md). | + ## DACPAC -The simplest way to deploy a database is to create [data-tier package or DACPAC](/sql/relational-databases/data-tier-applications/data-tier-applications). DACPACs can be used to package and deploy schema changes and data. You can create a DACPAC using the **SQL database project** in Visual Studio. +The simplest way to deploy a database is by using a [data-tier package or DACPAC](/sql/relational-databases/data-tier-applications/data-tier-applications). DACPACs allow you to package and deploy schema changes and data. You can create a DACPAC using the **SQL Database Project** in Visual Studio. + +The [Azure SQL Database deployment](/azure/devops/pipelines/tasks/reference/sql-azure-dacpac-deployment-v1) task is the primary mechanism to deploy a database to Azure. This task, as with other built-in Azure tasks, requires an Azure service connection as an input. The Azure service connection stores the credentials to connect from Azure Pipelines to Azure. + +::: moniker range="azure-devops" + +The easiest way to get started with this task is to be signed in as a user that owns both the Azure DevOps organization and the Azure subscription. +In this case, you won't have to manually create the service connection. Otherwise, to learn how to create an Azure service connection, see [Create an Azure service connection](../library/connect-to-azure.md). + +::: moniker-end + +::: moniker range="< azure-devops" + +To learn how to create an Azure service connection, see [Create an Azure service connection](../library/connect-to-azure.md). + +::: moniker-end #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -To deploy a DACPAC to an Azure SQL database, add the following snippet to your azure-pipelines.yml file. +To deploy a DACPAC to an Azure SQL database, use the [Azure SQL Database deployment task](/azure/devops/pipelines/tasks/reference/sql-azure-dacpac-deployment-v1). Add the following snippet to your YAML file: ```yaml - task: SqlAzureDacpacDeployment@1 @@ -39,23 +57,21 @@ To deploy a DACPAC to an Azure SQL database, add the following snippet to your a ::: moniker-end -::: moniker range="tfs-2018" +#### [Classic](#tab/classic/) -YAML is not supported in TFS. +When setting up a build pipeline, use the **.NET desktop** template. This template automatically adds the tasks to build the project and publish artifacts, including the DACPAC. -::: moniker-end +:::image type="content" source="media/classic-pipeline-templates.png" alt-text="A screenshot displaying Classic pipeline templates."::: -#### [Classic](#tab/classic/) -When setting up a build pipeline for your Visual Studio database project, use the **.NET desktop** template. This template automatically adds the tasks to build the project and publish artifacts, including the DACPAC. +For Classic release pipelines, select **Start with an empty pipeline**, link the artifacts from your build pipeline, and then add the [Azure SQL Database Deployment](/azure/devops/pipelines/tasks/reference/sql-azure-dacpac-deployment-v1) task. -When setting up a release pipeline, choose **Start with an empty pipeline**, link the artifacts from build, and then add an [Azure SQL Database Deployment](/azure/devops/pipelines/tasks/reference/sql-azure-dacpac-deployment-v1) task. +:::image type="content" source="media/release-pipeline-sql-database-task.png" alt-text="A screenshot displaying how to set up a Classic release pipeline for database deployment."::: * * * -See also [authentication information when using the Azure SQL Database Deployment task](/azure/devops/pipelines/tasks/reference/sql-azure-dacpac-deployment-v1). ## SQL scripts -Instead of using a DACPAC, you can also use SQL scripts to deploy your database. Here’s a simple example of a SQL script that creates an empty database. +Alternatively, you can use SQL scripts instead of DACPAC to deploy your database. Below is a simple SQL script that creates an empty database: ```sql USE [main] @@ -65,11 +81,13 @@ Instead of using a DACPAC, you can also use SQL scripts to deploy your database. GO ``` -To run SQL scripts as part of a pipeline, you’ll need Azure PowerShell scripts to create and remove firewall rules in Azure. Without the firewall rules, the Azure Pipelines agent can’t communicate with Azure SQL Database. +To run SQL scripts from your pipeline, you'll need to add and remove firewall rules in Azure. Without these rules, the Azure Pipelines agent cannot communicate with Azure SQL Database. -The following PowerShell script creates firewall rules. You can check in this script as `SetAzureFirewallRule.ps1` into your repository. +#### Set Azure firewall rules -### ARM +The following PowerShell script creates firewall rules. Save it as `SetAzureFirewallRule.ps1` and add it to your repository: + +#### [ARM](#tab/arm/) ```powershell [CmdletBinding(DefaultParameterSetName = 'None')] @@ -80,10 +98,10 @@ param [String] $FirewallRuleName = "AzureWebAppFirewall" ) $agentIP = (New-Object net.webclient).downloadstring("https://api.ipify.org") -New-AzSqlServerFirewallRule -ResourceGroupName $ResourceGroupName -ServerName $ServerName -FirewallRuleName $FirewallRuleName -StartIPAddress $agentIp -EndIPAddress $agentIP +New-AzSqlServerFirewallRule -ResourceGroupName $ResourceGroupName -ServerName $ServerName -FirewallRuleName $FirewallRuleName -StartIPAddress $agentIP -EndIPAddress $agentIP ``` -### Classic +#### [ASM (Classic)](#tab/asm/) ```powershell [CmdletBinding(DefaultParameterSetName = 'None')] @@ -98,12 +116,12 @@ $ErrorActionPreference = 'Stop' function New-AzureSQLServerFirewallRule { $agentIP = (New-Object net.webclient).downloadstring("https://api.ipify.org") - New-AzureSqlDatabaseServerFirewallRule -StartIPAddress $agentIp -EndIPAddress $agentIp -RuleName $FirewallRuleName -ServerName $ServerName + New-AzureSqlDatabaseServerFirewallRule -StartIPAddress $agentIP -EndIPAddress $agentIP -RuleName $FirewallRuleName -ServerName $ServerName } function Update-AzureSQLServerFirewallRule{ $agentIP= (New-Object net.webclient).downloadstring("https://api.ipify.org") - Set-AzureSqlDatabaseServerFirewallRule -StartIPAddress $agentIp -EndIPAddress $agentIp -RuleName $FirewallRuleName -ServerName $ServerName + Set-AzureSqlDatabaseServerFirewallRule -StartIPAddress $agentIP -EndIPAddress $agentIP -RuleName $FirewallRuleName -ServerName $ServerName } if ((Get-AzureSqlDatabaseServerFirewallRule -ServerName $ServerName -RuleName $FirewallRuleName -ErrorAction SilentlyContinue) -eq $null) @@ -115,10 +133,13 @@ else Update-AzureSQLServerFirewallRule } ``` +* * * + +#### Remove Azure firewall rules -The following PowerShell script removes firewall rules. You can check in this script as `RemoveAzureFirewallRule.ps1` into your repository. +The following PowerShell script removes firewall rules. Save it as `RemoveAzureFirewallRule.ps1` and add it to your repository: -### ARM +#### [ARM](#tab/arm/) ```powershell [CmdletBinding(DefaultParameterSetName = 'None')] @@ -131,7 +152,7 @@ param Remove-AzSqlServerFirewallRule -ServerName $ServerName -FirewallRuleName $FirewallRuleName -ResourceGroupName $ResourceGroupName ``` -### Classic +#### [ASM (Classic)](#tab/asm/) ```powershell [CmdletBinding(DefaultParameterSetName = 'None')] @@ -149,12 +170,15 @@ if ((Get-AzureSqlDatabaseServerFirewallRule -ServerName $ServerName -RuleName $F Remove-AzureSqlDatabaseServerFirewallRule -RuleName $FirewallRuleName -ServerName $ServerName } ``` +* * * -#### [YAML](#tab/yaml/) +#### Deploy database with SQL scripts -::: moniker range=">= azure-devops-2019" +The following example outlines the steps to add firewall rules, deploy your database using SQL scripts, and then remove the firewall rules: + +#### [YAML](#tab/yaml/) -Add the following to your azure-pipelines.yml file to run a SQL script. +::: moniker range="<=azure-devops" ```yaml variables: @@ -169,7 +193,7 @@ variables: steps: - task: AzurePowerShell@5 - displayName: 'Azure PowerShell script' + displayName: 'Set Azure firewall rules' inputs: azureSubscription: '$(AzureSubscription)' ScriptType: filePath @@ -177,14 +201,24 @@ steps: ScriptArguments: '-ServerName $(ServerName) -ResourceGroupName $(ResourceGroupName)' azurePowerShellVersion: LatestVersion -- task: CmdLine@2 - displayName: Run Sqlcmd +- task: PowerShell@2 inputs: - filename: Sqlcmd - arguments: '-S $(ServerFqdn) -U $(AdminUser) -P $(AdminPassword) -d $(DatabaseName) -i $(SQLFile)' + displayName: 'Install SqlServer module if not present' + targetType: 'inline' + script: | + if (-not (Get-Module -ListAvailable -Name SqlServer)) { + Install-Module -Name SqlServer -Force -AllowClobber + } + +- task: PowerShell@2 + displayName: 'Deploy database' + inputs: + targetType: 'inline' + script: | + Invoke-Sqlcmd -InputFile $(SQLFile) -ServerInstance $(ServerFqdn) -Database $(DatabaseName) -Username $(AdminUser) -Password $(AdminPassword) - task: AzurePowerShell@5 - displayName: 'Azure PowerShell script' + displayName: 'Remove Azure firewall rules' inputs: azureSubscription: '$(AzureSubscription)' ScriptType: filePath @@ -195,57 +229,44 @@ steps: ::: moniker-end -::: moniker range="tfs-2018" - -YAML is not supported in TFS. - -::: moniker-end - #### [Classic](#tab/classic/) -When you set up a build pipeline, make sure that the SQL script to deploy the database and the Azure PowerShell scripts to configure firewall rules are part of the build artifact. - -When you set up a release pipeline, choose **Start with an Empty process**, link the artifacts from build, and then use the following tasks: - -- First, use an [Azure PowerShell](/azure/devops/pipelines/tasks/reference/azure-powershell-v5) task to add a firewall rule in Azure to allow the Azure Pipelines agent to connect to Azure SQL Database. The script requires one argument - the name of the SQL server you created. -- Second, use a [Command line](/azure/devops/pipelines/tasks/reference/cmd-line-v2) task to run the SQL script using the **SQLCMD** tool. The arguments to this tool are `-S {database-server-name}.database.windows.net -U {username}@{database-server-name} -P {password} -d {database-name} -i {SQL file}` For example, when the SQL script is coming from an artifact source, **{SQL file}** will be of the form: `$(System.DefaultWorkingDirectory)/contoso-repo/DatabaseExample.sql`. -- Third, use another [Azure PowerShell](/azure/devops/pipelines/tasks/reference/azure-powershell-v5) task to remove the firewall rule in Azure. +For Classic pipelines, ensure that both the SQL script for deploying the database and the Azure PowerShell scripts for configuring firewall rules are included as part of the build artifact. -:::image type="content" source="media/classic-sql.png" alt-text="A screenshot showing a classic pipeline to run SQL script."::: +For Classic release pipelines, select **Start with an empty pipeline**, link the artifacts from your build pipeline, and then add the following tasks: -* * * +1. Use the [Azure PowerShell](/azure/devops/pipelines/tasks/reference/azure-powershell-v5) task to add a firewall rule in Azure, allowing the Azure Pipelines agent to connect to the Azure SQL Database. The script requires one argument - the name of the SQL server you created. -## Azure service connection +1. Use the [PowerShell](/azure/devops/pipelines/tasks/reference/powershell-v2) task to invoke SQLCMD and execute your scripts. Use the following inline script: -The **Azure SQL Database Deployment** task is the primary mechanism to deploy a database to Azure. This task, as with other built-in Azure tasks, requires an Azure service connection as an input. The Azure service connection stores the credentials to connect from Azure Pipelines or TFS to Azure. + ```PowerShell + if (-not (Get-Module -ListAvailable -Name SqlServer)) { + Install-Module -Name SqlServer -Force -AllowClobber + } -::: moniker range="azure-devops" + Invoke-Sqlcmd -InputFile $(SQLFile) -ServerInstance $(ServerFqdn) -Database $(DatabaseName) -Username $(AdminUser) -Password $(AdminPassword) + ``` -The easiest way to get started with this task is to be signed in as a user that owns both the Azure DevOps organization and the Azure subscription. -In this case, you won't have to manually create the service connection. -Otherwise, to learn how to create an Azure service connection, see [Create an Azure service connection](../library/connect-to-azure.md). +1. Use another [Azure PowerShell](/azure/devops/pipelines/tasks/reference/azure-powershell-v5) task to remove the firewall rule in Azure. -::: moniker-end + :::image type="content" source="media/sql-add-firewall-rules.png" alt-text="A screenshot displaying a classic pipeline to add firewall rules and run SQL scripts."::: -::: moniker range="< azure-devops" - -To learn how to create an Azure service connection, see [Create an Azure service connection](../library/connect-to-azure.md). - -::: moniker-end +* * * -## Deploying conditionally +## Deploy database conditionally -You may choose to deploy only certain builds to your Azure database. +You can choose to deploy only specific builds to your Azure database, giving you more control over which changes are applied based on criteria like the source branch or build status. #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" To do this in YAML, you can use one of these techniques: -* Isolate the deployment steps into a separate job, and add a condition to that job. -* Add a condition to the step. +* Isolate the deployment steps into a separate job and apply a condition to that job. + +* Add a condition directly to the step. -The following example shows how to use step conditions to deploy only those builds that originate from main branch. +The example below shows how to deploy only builds from the main branch using [conditions](../process/conditions.md): ```yaml - task: SqlAzureDacpacDeployment@1 @@ -259,38 +280,28 @@ The following example shows how to use step conditions to deploy only those buil DacpacFile: '' ``` -To learn more about conditions, see [Specify conditions](../process/conditions.md). - -::: moniker-end - -::: moniker range="tfs-2018" - -YAML is not supported in TFS. - ::: moniker-end #### [Classic](#tab/classic/) -In your release pipeline, you can implement various checks and conditions to control the deployment. +With Classic release pipelines, you can implement various checks and conditions to control when and which deployments are triggered. Here are some strategies you can use: -> [!NOTE] -> In some setups, you might need to allowlist the range of IP addresses for the specific region that is updated in the [weekly JSON file](https://www.microsoft.com/download/details.aspx?id=56519). Learn about [networking Microsoft-hosted agents](../agents/hosted.md#networking). +* Use branch filters to set up your [continuous deployment triggers](../release/triggers.md#continuous-deployment-triggers) to trigger a release whenever a new build from a specific branch becomes available. +* Use [pre-deployment approvals](../release/approvals/approvals.md#predeployment-approvals) to designate approvers who can either approve or reject deployment to a specific stage. -* Set **branch filters** to configure the **continuous deployment trigger** on the artifact of the release pipeline. -* Set **pre-deployment approvals** as a pre-condition for deployment to a stage. -* Configure **gates** as a pre-condition for deployment to a stage. -* Specify conditions for a task to run. +* Define a set of [gates](../release/deploy-using-approvals.md#set-up-gates) to ensure that the release pipeline meets specific criteria before deployment without requiring user intervention. -To learn more, see [Release, branch, and stage triggers](../release/triggers.md), [Release deployment control using approvals](../release/approvals/approvals.md), [Release deployment control using gates](../release/approvals/gates.md), and [Specify conditions for running a task](../process/conditions.md). +> [!NOTE] +> In some scenarios, you might need to allowlist IP address ranges for a specific region. These ranges are updated weekly and can be downloaded as a [JSON file](https://www.microsoft.com/download/details.aspx?id=56519). See [networking Microsoft-hosted agents](../agents/hosted.md#networking) for more details. * * * + ## More SQL actions -**SQL Azure Dacpac Deployment** may not support all SQL server actions -that you want to perform. In these cases, you can simply use PowerShell or command-line scripts to run the commands you need. -This section shows some of the common use cases for invoking the [SqlPackage.exe tool](/sql/tools/sqlpackage-download). -As a prerequisite to running this tool, you must use a self-hosted agent and have the tool installed on your agent. +The SQL Azure Dacpac Deployment task might not cover all the SQL server actions you need to perform. In such cases, you can use PowerShell or command-line scripts to execute the required commands. + +This section covers common use cases for invoking the [SqlPackage.exe tool](/sql/tools/sqlpackage-download). Before running this tool, make sure you're using a self-hosted agent with the tool installed. > [!NOTE] > If you execute **SQLPackage** from the folder where it is installed, you must prefix the path with `&` and wrap it in double-quotes. @@ -299,9 +310,9 @@ As a prerequisite to running this tool, you must use a self-hosted agent and hav ` ` -You can use any of the following SQL scripts depending on the action that you want to perform +You can use any of the following SQL scripts based on the action you wish to perform: -### Extract +#### [Extract](#tab/extract/) Creates a database snapshot (.dacpac) file from a live SQL server or Microsoft Azure SQL Database. @@ -323,7 +334,7 @@ SqlPackage.exe /action:Extract /tf:"" **Example:** ```command -SqlPackage.exe /TargetFile:"C:\temp\test.dacpac" /Action:Extract /SourceServerName:"DemoSqlServer.database.windows.net" +SqlPackage.exe /TargetFile:"C:\temp\test.dacpac" /Action:Extract /SourceServerName:"DemoSqlServer.database.windows.net.placeholder" /SourceDatabaseName:"Testdb" /SourceUser:"ajay" /SourcePassword:"SQLPassword" ``` @@ -333,7 +344,7 @@ SqlPackage.exe /TargetFile:"C:\temp\test.dacpac" /Action:Extract /SourceServerNa sqlpackage.exe /Action:Extract /? ``` -### Publish +#### [Publish](#tab/publish/) Incrementally updates a database schema to match the schema of a source .dacpac file. If the database doesn’t exist on the server, the publish operation will create it. Otherwise, an existing database will be updated. @@ -347,7 +358,7 @@ SqlPackage.exe /SourceFile:"" /Action:Publish /TargetServe **Example:** ```command -SqlPackage.exe /SourceFile:"E:\dacpac\ajyadb.dacpac" /Action:Publish /TargetServerName:"DemoSqlServer.database.windows.net" +SqlPackage.exe /SourceFile:"E:\dacpac\ajyadb.dacpac" /Action:Publish /TargetServerName:"DemoSqlServer.database.windows.net.placeholder" /TargetDatabaseName:"Testdb4" /TargetUser:"ajay" /TargetPassword:"SQLPassword" ``` @@ -357,7 +368,7 @@ SqlPackage.exe /SourceFile:"E:\dacpac\ajyadb.dacpac" /Action:Publish /TargetServ sqlpackage.exe /Action:Publish /? ``` -### Export +#### [Export](#tab/export/) Exports a live database, including database schema and user data, from SQL Server or Microsoft Azure SQL Database to a BACPAC package (.bacpac file). @@ -371,7 +382,7 @@ SqlPackage.exe /TargetFile:"" /Action:Export /S **Example:** ```command -SqlPackage.exe /TargetFile:"C:\temp\test.bacpac" /Action:Export /SourceServerName:"DemoSqlServer.database.windows.net" +SqlPackage.exe /TargetFile:"C:\temp\test.bacpac" /Action:Export /SourceServerName:"DemoSqlServer.database.windows.net.placeholder" /SourceDatabaseName:"Testdb" /SourceUser:"ajay" /SourcePassword:"SQLPassword" ``` @@ -381,7 +392,7 @@ SqlPackage.exe /TargetFile:"C:\temp\test.bacpac" /Action:Export /SourceServerNam sqlpackage.exe /Action:Export /? ``` -### Import +#### [Import](#tab/import/) Imports the schema and table data from a BACPAC package into a new user database in an instance of SQL Server or Microsoft Azure SQL Database. @@ -395,7 +406,7 @@ SqlPackage.exe /SourceFile:"" /Action:Import /TargetServer **Example:** ```command -SqlPackage.exe /SourceFile:"C:\temp\test.bacpac" /Action:Import /TargetServerName:"DemoSqlServer.database.windows.net" +SqlPackage.exe /SourceFile:"C:\temp\test.bacpac" /Action:Import /TargetServerName:"DemoSqlServer.database.windows.net.placeholder" /TargetDatabaseName:"Testdb" /TargetUser:"ajay" /TargetPassword:"SQLPassword" ``` @@ -405,7 +416,7 @@ SqlPackage.exe /SourceFile:"C:\temp\test.bacpac" /Action:Import /TargetServerNam sqlpackage.exe /Action:Import /? ``` -### DeployReport +#### [DeployReport](#tab/deployreport/) Creates an XML report of the changes that would be made by a publish action. @@ -419,7 +430,7 @@ SqlPackage.exe /SourceFile:"" /Action:DeployReport /Target **Example:** ```command -SqlPackage.exe /SourceFile:"E: \dacpac\ajyadb.dacpac" /Action:DeployReport /TargetServerName:"DemoSqlServer.database.windows.net" +SqlPackage.exe /SourceFile:"E: \dacpac\ajyadb.dacpac" /Action:DeployReport /TargetServerName:"DemoSqlServer.database.windows.net.placeholder" /TargetDatabaseName:"Testdb" /TargetUser:"ajay" /TargetPassword:"SQLPassword" /OutputPath:"C:\temp\deployReport.xml" ``` @@ -429,7 +440,7 @@ SqlPackage.exe /SourceFile:"E: \dacpac\ajyadb.dacpac" /Action:DeployReport /Targ sqlpackage.exe /Action:DeployReport /? ``` -### DriftReport +#### [DriftReport](#tab/driftreport/) Creates an XML report of the changes that have been made to a registered database since it was last registered. @@ -443,7 +454,7 @@ SqlPackage.exe /Action:DriftReport /TargetServerName:".database.wind **Example:** ```command -SqlPackage.exe /Action:DriftReport /TargetServerName:"DemoSqlServer.database.windows.net" /TargetDatabaseName:"Testdb" +SqlPackage.exe /Action:DriftReport /TargetServerName:"DemoSqlServer.database.windows.net.placeholder" /TargetDatabaseName:"Testdb" /TargetUser:"ajay" /TargetPassword:"SQLPassword" /OutputPath:"C:\temp\driftReport.xml" ``` @@ -453,7 +464,7 @@ SqlPackage.exe /Action:DriftReport /TargetServerName:"DemoSqlServer.database.win sqlpackage.exe /Action:DriftReport /? ``` -### Script +#### [Script](#tab/script/) Creates a Transact-SQL incremental update script that updates the schema of a target to match the schema of a source. @@ -467,7 +478,7 @@ SqlPackage.exe /SourceFile:"" /Action:Script /TargetServer **Example:** ```command -SqlPackage.exe /Action:Script /SourceFile:"E:\dacpac\ajyadb.dacpac" /TargetServerName:"DemoSqlServer.database.windows.net" +SqlPackage.exe /Action:Script /SourceFile:"E:\dacpac\ajyadb.dacpac" /TargetServerName:"DemoSqlServer.database.windows.net.placeholder" /TargetDatabaseName:"Testdb" /TargetUser:"ajay" /TargetPassword:"SQLPassword" /OutputPath:"C:\temp\test.sql" /Variables:StagingDatabase="Staging DB Variable value" ``` @@ -477,3 +488,13 @@ SqlPackage.exe /Action:Script /SourceFile:"E:\dacpac\ajyadb.dacpac" /TargetServe ```command sqlpackage.exe /Action:Script /? ``` + +*** + +## Related content + +- [Azure Resource Manager service connections](../library/connect-to-azure.md) + +- [Troubleshoot pipeline runs](../troubleshooting/troubleshooting.md) + +- [Troubleshoot ARM service connections](../release/azure-rm-endpoint.md) \ No newline at end of file diff --git a/docs/pipelines/targets/azure-stack.md b/docs/pipelines/targets/azure-stack.md index 68a57bdb89f..6fc0f20d855 100644 --- a/docs/pipelines/targets/azure-stack.md +++ b/docs/pipelines/targets/azure-stack.md @@ -3,11 +3,10 @@ title: Deploy to Azure Stack Hub App Service using Azure Pipelines description: Understand how to deploy to Azure Stack Hub App Service using Azure Pipelines ms.assetid: 76C2080A-C1D9-44AF-AA76-1953BA4C2837 ms.topic: how-to -ms.custom: seodec18 ms.author: ronai author: RoopeshNair ms.date: 02/01/2022 -monikerRange: '> tfs-2018' +monikerRange: "<=azure-devops" --- # Deploy to Azure Stack Hub App Service using Azure Pipelines diff --git a/docs/pipelines/targets/create-virtual-network.md b/docs/pipelines/targets/create-virtual-network.md index 8a77b37a5e6..65f125494df 100644 --- a/docs/pipelines/targets/create-virtual-network.md +++ b/docs/pipelines/targets/create-virtual-network.md @@ -1,9 +1,8 @@ --- -title: Create a virtual network for build-deploy-test +title: Create a virtual network for build-deploy-test description: Provision and manage VMs in SCVMM - Create a virtual network for build-deploy-test scenarios using Network Virtualization ms.assetid: 64620E9B-D2D1-4516-921A-40A159019513 ms.topic: conceptual -ms.custom: seodec18 ms.author: ronai author: RoopeshNair ms.date: 02/01/2022 @@ -14,9 +13,7 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end + Network Virtualization provides ability to create multiple virtual networks on a shared physical network. Isolated virtual networks can @@ -45,8 +42,6 @@ See also: [Hyper-V Network Virtualization Overview](/windows-server/networking/s virtual network. The options and steps are described in [this section](#select-topology). * Enable your build-deploy-test scenario as shown in [these steps](#enable-scenario). - -* You can perform a range of operations to manage VMs using SCVMM. For examples, see [SCVMM deployment](scvmm.md). @@ -205,7 +200,7 @@ port profiles, logical switches, and adding the switches to the Hyper-V hosts. 1. Do the same for all the Hyper-V hosts in the host group. This is a one-time configuration for a specific host group of machines. After completing this setup, you can dynamically -provision your isolated network of virtual machines using the **SCVMM extension** in TFS and Azure Pipelines builds and releases. +provision your isolated network of virtual machines using the **SCVMM extension** in Azure Pipelines builds and releases. [Back to list of tasks](#task-list) @@ -243,8 +238,7 @@ Isolated virtual networks can be broadly classified into three topologies. You can create any of the above topologies using the SCVMM extension, as shown in the following steps. -1. Open your TFS or Azure Pipelines instance and install the **SCVMM extension** if not already installed. - For more information, see [SCVMM deployment](scvmm.md). +1. Open your Azure Pipelines instance and install the **SCVMM extension** if not already installed. >The **SCVMM task** provides a more efficient way capability to perform lab management operations using build and release pipelines. You can manage SCVMM environments, provision isolated virtual networks, and implement build-deploy-test scenarios. @@ -341,16 +335,13 @@ environments. You can create as many environments as you need with just a select ## See also -* [SCVMM deployment](scvmm.md) * [Hyper-V Network Virtualization Overview](/windows-server/networking/sdn/technologies/hyper-v-network-virtualization/hyperv-network-virtualization-overview-windows-server) ## FAQ -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/qa-versions.md)] -::: moniker-end + diff --git a/docs/pipelines/targets/media/classic-pipeline-templates.png b/docs/pipelines/targets/media/classic-pipeline-templates.png new file mode 100644 index 00000000000..622999388a0 Binary files /dev/null and b/docs/pipelines/targets/media/classic-pipeline-templates.png differ diff --git a/docs/pipelines/targets/media/functionapp-container/container-settings.png b/docs/pipelines/targets/media/functionapp-container/container-settings.png deleted file mode 100644 index b26eac90e05..00000000000 Binary files a/docs/pipelines/targets/media/functionapp-container/container-settings.png and /dev/null differ diff --git a/docs/pipelines/targets/media/release-pipeline-sql-database-task.png b/docs/pipelines/targets/media/release-pipeline-sql-database-task.png new file mode 100644 index 00000000000..5d9175bb5cb Binary files /dev/null and b/docs/pipelines/targets/media/release-pipeline-sql-database-task.png differ diff --git a/docs/pipelines/targets/media/sql-add-firewall-rules.png b/docs/pipelines/targets/media/sql-add-firewall-rules.png new file mode 100644 index 00000000000..90eb0102707 Binary files /dev/null and b/docs/pipelines/targets/media/sql-add-firewall-rules.png differ diff --git a/docs/pipelines/targets/media/webapp-linux/container-settings.png b/docs/pipelines/targets/media/webapp-linux/container-settings.png deleted file mode 100644 index 31fda262c54..00000000000 Binary files a/docs/pipelines/targets/media/webapp-linux/container-settings.png and /dev/null differ diff --git a/docs/pipelines/targets/scvmm.md b/docs/pipelines/targets/scvmm.md deleted file mode 100644 index 3bb0c726c02..00000000000 --- a/docs/pipelines/targets/scvmm.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Deploy with SCVMM -description: Provision and manage your virtual machines in System Center Virtual Machine Manager (SCVMM) -ms.assetid: A14C4E98-EF76-400C-A728-292E1D75ECFD -ms.topic: conceptual -ms.custom: seodec18 -ms.author: ronai -author: RoopeshNair -ms.date: 02/01/2022 -monikerRange: '<= azure-devops' ---- - -# Deploy with System Center Virtual Machine Manager - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -You can automatically provision new virtual machines in System Center Virtual Machine Manager (SCVMM) and deploy to those virtual machines after every successful build. - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -## SCVMM connection - -::: moniker range="azure-devops" - -You need to first configure how Azure Pipelines connects to SCVMM. You can’t use Microsoft-hosted agents to run SCVMM tasks since the VMM Console isn’t installed on hosted agents. You must set up a self-hosted build and release agent on the same network as your SCVMM server. - -::: moniker-end - -::: moniker range="< azure-devops" - -You need to first configure how TFS connects to SCVMM. You must have a build and release agent that can communicate with the SCVMM server. - -::: moniker-end - -1. Install the **Virtual Machine Manager** (VMM) console on the agent machine by - following [these instructions](/system-center/vmm/install-console). - Supported version: [System Center 2012 R2 Virtual Machine Manager](/previous-versions/system-center/system-center-2012-R2/hh546785(v=sc.12)). - -2. Install the **System Center Virtual Machine Manager (SCVMM)** extension - from Visual Studio Marketplace into TFS or Azure Pipelines: - - * If you’re using **Azure Pipelines**, - install the extension from [this location](https://marketplace.visualstudio.com/items?itemName=ms-vscs-rm.scvmmapp) - in Visual Studio Marketplace. - * If you’re using **Team Foundation Server**, download - the extension from [this location](https://marketplace.visualstudio.com/items?itemName=ms-vscs-rm.scvmmapp) - in Visual Studio Marketplace, upload it to your - Team Foundation Server, and install it.

      - -3. Create an SCVMM service connection in your project: - - * In your Azure Pipelines or TFS project in your web browser, navigate to the project settings and select **Service connections**. - - * In the **Service connections** tab, choose **New service connection**, and select **SCVMM**. - - * In the **Add new SCVMM Connection** - dialog, enter the values required to connect to the - SCVMM Server: - - - **Connection Name**: Enter a user-friendly name - for the service connection such as **MySCVMMServer**. - - **SCVMM Server Name**: Enter the fully qualified domain - name and port number of the SCVMM server, in the form **machine.domain.com:port**. - - **Username** and **Password**: Enter the credentials - required to connect to the vCenter Server. Username formats such as **username**, **domain\username**, - **machine-name\\username**, and **.\\username** are supported. - UPN formats such as username@domain.com and built-in system - accounts such as **NT Authority\\System** aren’t supported.

      - - -## Create new virtual machines from a template, VHD, or stored VM - -One of the common actions that you can perform with every build is to create a new virtual machine to deploy the build to. You use the SCMVMM task from the extension to do this and configure the properties of the task as follows: - -* **Display name**: The name for the task as it appears in the task list. -* **SCVMM Service Connection**: Select a SCVMM service connection you already defined, or create a new one. -* **Action**: Select **New Virtual Machine using Template/Stored VM/VHD**. -* **Create virtual machines from VM Templates**: Set this option if you want to use a template. - - **Virtual machine names**: Enter the name of the virtual machine, or a list of the virtual machine names on separate lines. Example `FabrikamDevVM` - - **VM template names**: Enter the name of the template, or a list of the template names on separate lines. - - **Set computer name as defined in the VM template**: If not set, the computer name will be the same as the VM name. -* **Create virtual machines from stored VMs**: Set this option if you want to use a stored VM. - - **Virtual machine names**: Enter the name of the virtual machine, or a list of the virtual machine names on separate lines. Example `FabrikamDevVM` - - **Stored VMs**: Enter the name of the stored VM, or a list of the VMs on separate lines in the same order as the virtual machine names. -* **Create virtual machines from VHD**: Set this option if you want to use a stored VM. - - **Virtual machine names**: Enter the name of the virtual machine, or a list of the virtual machine names on separate lines. Example `FabrikamDevVM` - - **VHDs**: Enter the name of the VHD or VHDX, or a list of names on separate lines in the same order as the virtual machine names. - - **CPU count**: Specify the number of processor cores required for the virtual machines. - - **Memory**: Specify the memory in MB required for the virtual machines. -* **Clear existing network adapters**: Set this option if you want to remove the network adapters and specify new ones in the **Network Virtualization** options. -* **Deploy the VMs to**: Choose either **Cloud** or **Host** to select the set of virtual machines to which the action will be applied. -* **Host Name** or **Cloud Name**: Depending on the previous selection, enter either a cloud name or a host machine name. -* **Placement path for VM**: If you selected **Host** as the deployment target, enter the path to be used during virtual machine placement. Example `C:\ProgramData\Microsoft\Windows\Hyper-V` -* **Additional Arguments**: Enter any arguments to pass to the virtual machine creation template. Example `-StartVM -StartAction NeverAutoTurnOnVM -StopAction SaveVM` -* **Wait Time**: The time to wait for the virtual machine to reach ready state. -* **Network Virtualization**: Set this option to enable network virtualization for your virtual machines. For more information, see [Create a virtual network isolated environment](create-virtual-network.md). -* **Show minimal logs**: Set this option if you don't want to create detailed live logs about the VM provisioning process. - - -## Delete virtual machines - -After validating your build, you would want to delete the virtual machines that you created. You use the SCMVMM task from the extension to do this and configure the properties of the task as follows: - -* **Display name**: The name for the task as it appears in the task list. -* **SCVMM Service Connection**: Select a SCVMM service connection you already defined, or create a new one. -* **Action**: Select **New Virtual Machine using Template/Stored VM/VHD**. -* **VM Names**: Enter the name of the virtual machine, or a comma-separated list of the virtual machine names. Example `FabrikamDevVM,FabrikamTestVM` -* **Select VMs From**: Choose either **Cloud** or **Host** to select the set of virtual machines to which the action will be applied. -* **Host Name** or **Cloud Name**: Depending on the previous selection, enter either a cloud name or a host machine name. - - -## Start and stop virtual machines - -You can start a virtual machine prior to deploying a build, and then stop the virtual machine after running tests. Use the SCVMM task as follows in order to achieve this: - -* **Display name**: The name for the task as it appears in the task list. -* **SCVMM Service Connection**: Select a SCVMM service connection you already defined, or create a new one. -* **Action**: Select **Start Virtual Machine** or **Stop Virtual Machine**. -* **VM Names**: Enter the name of the virtual machine, or a comma-separated list of the virtual machine names. Example `FabrikamDevVM,FabrikamTestVM` -* **Select VMs From**: Choose either **Cloud** or **Host** to select the set of virtual machines to which the action will be applied. -* **Host Name** or **Cloud Name**: Depending on the previous selection, enter either a cloud name or a host machine name. -* **Wait Time**: The time to wait for the virtual machine to reach ready state. - - -## Create, restore, and delete checkpoints - -A quick alternative to bringing up a virtual machine in desired state prior to running tests is to restore it to a known checkpoint. Use the SCVMM task as follows in order to do this: - -* **Display name**: The name for the task as it appears in the task list. -* **SCVMM Service Connection**: Select a SCVMM service connection you already defined, or create a new one. -* **Action**: Select one of the checkpoint actions **Create Checkpoint**, **Restore Checkpoint**, or **Delete Checkpoint**. -* **VM Names**: Enter the name of the virtual machine, or a comma-separated list of the virtual machine names. Example `FabrikamDevVM,FabrikamTestVM` -* **Checkpoint Name**: For the **Create Checkpoint** action, enter the name of the checkpoint that will be applied to the virtual machines. For the **Delete Checkpoint** or **Restore Checkpoint** action, enter the name of an existing checkpoint. -* **Description for Checkpoint**: Enter a description for the new checkpoint when creating it. -* **Select VMs From**: Choose either **Cloud** or **Host** to select the set of virtual machines to which the action will be applied. -* **Host Name** or **Cloud Name**: Depending on the previous selection, enter either a cloud name or a host machine name. - - -## Run custom PowerShell scripts for SCVMM - -For functionality that isn’t available through the in-built actions, you can run custom SCVMM PowerShell scripts using the task. The task helps you with setting up the connection with SCVMM using the credentials configured in the service connection, and then runs the script. - -* **Display name**: The name for the task as it appears in the task list. -* **SCVMM Service Connection**: Select a SCVMM service connection you already defined, or create a new one. -* **Action**: Select **Run PowerShell Script for SCVMM**. -* **Script Type**: Select either **Script File Path** or **Inline Script**. -* **Script Path**: If you selected **Script File Path**, enter the path of the PowerShell script to execute. It must be a fully qualified path, or a path relative to the default working directory. -* **Inline Script**: If you selected **Inline Script**, enter the PowerShell script lines to execute. -* **Script Arguments**: Enter any arguments to be passed to the PowerShell script. You can use either ordinal parameters or named parameters. -* **Working folder**: Specify the current working directory for the script when it runs. The default if not provided is the folder containing the script. - -## Deploying build to virtual machines - -Once you have the virtual machines set up, deploying a build to those virtual machines is no different than deploying to any other machine. For instance, you can: - -* Use the [PowerShell on Target Machines](/azure/devops/pipelines/tasks/reference/powershell-on-target-machines-v3) task to run remote scripts on those machines using Windows Remote Management. -* Use [Deployment groups](../release/deployment-groups/index.md) to run scripts and other tasks on those machines using build and release agent. - -## See also - -* [Create a virtual network isolated environment for build-deploy-test scenarios](create-virtual-network.md) \ No newline at end of file diff --git a/docs/pipelines/targets/vmware.md b/docs/pipelines/targets/vmware.md deleted file mode 100644 index 104ace51232..00000000000 --- a/docs/pipelines/targets/vmware.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: Deploy to VMware -description: Provision and manage virtual machines (VMs) in VMware vCenter Server -ms.assetid: 1A6903E4-B0B3-426E-9E07-67492ADB1F42 -ms.topic: conceptual -ms.custom: seodec18 -ms.author: ronai -author: RoopeshNair -ms.date: 02/01/2022 -monikerRange: '<= azure-devops' ---- - -# Deploy to VMware vCenter Server - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -You can automatically provision virtual machines in a VMware environment and deploy to those virtual machines after every successful build. - -## VMware connection - -::: moniker range="azure-devops" - -You need to first configure how Azure Pipelines connects to vCenter. You can’t use Microsoft-hosted agents to run VMware tasks since the vSphere SDK isn’t installed on these machines. You have to a setup a self-hosted agent that can communicate with the vCenter server. - -::: moniker-end - -::: moniker range="azure-devops-2019" - -You need to first configure how Azure DevOps Server connects to vCenter. You have to a setup a self-hosted agent that can communicate with the vCenter server. - -::: moniker-end - -::: moniker range="tfs-2018" - -You need to first configure how TFS connects to vCenter. You have to a setup a self-hosted agent that can communicate with the vCenter server. - -::: moniker-end - -1. Install the VMware vSphere Management - SDK to call VMware API functions that access vSphere - web services. To install and configure the SDK on - the agent machine: - - * Download and install the latest - version of the Java Runtime Environment from - [this location](https://aka.ms/downloadjre). - - * Go to [this location](https://aka.ms/vspheresdk) - and sign in with your existing credentials or register - with the website. Then download the **vSphere 6.0 - Management SDK**. - - * Create a directory for the vSphere Management SDK - such as **C:\vSphereSDK**. Don’t include spaces in - the directory names to avoid issues with some of the - batch and script files included in the SDK. - - * Unpack the vSphere Management SDK into the - new folder you created. - - * Add the full path and name of the precompiled - VMware Java SDK file **vim25.jar** to the machine's - CLASSPATH environment variable. If you used the path and name - **C:\vSphereSDK** for the SDK files, as shown above, the full - path will be: - `C:\vSphereSDK\SDK\vsphere-ws\java\JAXWS\lib\vim25.jar`

      - -2. Install the [VMware extension](https://marketplace.visualstudio.com/items?itemName=ms-vscs-rm.vmwareapp) - from Visual Studio Marketplace into TFS or Azure Pipelines. - -3. Follow these steps to create a vCenter Server service connection in your project: - - * Open your Azure Pipelines or TFS project in - your web browser. Choose the **Settings** icon in the menu bar and select **Service connections**. - - * In the **Services** tab, choose **New service connection**, and select **VMware vCenter Server**. - - * In the **Add new VMware vCenter Server Connection** - dialog, enter the values required to connect to the - vCenter Server: - - - **Connection Name**: Enter a user-friendly name - for the service connection such as **Fabrikam vCenter**. - - **vCenter Server URL**: Enter the URL of the - vCenter server, in the form `https://machine.domain.com/`. - Only **HTTPS** connections are supported. - - **Username** and **Password**: Enter the credentials - required to connect to the vCenter Server. - Username formats such as **username**, **domain\\username**, - **machine-name\\username**, and **.\\username** are supported. - UPN formats such as username@domain.com and built-in system - accounts such as **NT Authority\\System** aren’t supported.

      - -## Managing VM snapshots - -Use the **VMware Resource Deployment** task from the VMware extension and configure the properties as follows to take snapshot of virtual machines, or to revert or delete them: - -- **VMware Service Connection**: Select the VMware vCenter Server connection you created earlier. - -- **Action**: Select one of the actions: **Take Snapshot of Virtual Machines**, **Revert Snapshot of Virtual Machines**, or **Delete Snapshot of Virtual Machines**. - -- **Virtual Machine Names**: Enter the names of one or more virtual machines. Separate multiple names with a comma; for example, `VM1,VM2,VM3` - -- **Datacenter**: Enter the name of the datacenter where the virtual machines will be created. - -- **Snapshot Name**: Enter the name of the snapshot. This snapshot must exist if you use the revert or delete action. - -- **Host Name**: Depending on the option you selected for the compute resource type, enter the name of the host, cluster, or resource pool. - -- **Datastore**: Enter the name of the datastore that will hold the virtual machines' configuration and disk files. - -- **Description**: Optional. Enter a description for the **Take Snapshot of Virtual Machines** action, such as `$(Build.DefinitionName).$(Build.BuildNumber)`. This can be used to track the execution of the build or release that created the snapshot. - -- **Skip Certificate Authority Check**: If the vCenter Server's certificate is self-signed, select this option to skip the validation of the certificate by a trusted certificate authority.

      - - >To verify if a self-signed certificate is installed - on the vCenter Server, open the VMware vSphere Web - Client in your browser and check for a certificate - error page. The vSphere Web Client URL will be - of the form `https://machine.domain/vsphere-client/`. - Good practice guidance for vCenter Server certificates - can be found in the [VMware Knowledge Base](https://aka.ms/vcentercertificate) - (article 2057223). - -## Provisioning virtual machines - -To configure the **VMware Resource Deployment** task to provision a new virtual machine from a template, use these settings: - - - **VMware Service Connection**: Select the VMware vCenter Server connection you created earlier. - - - **Action**: `Deploy Virtual Machines using Template` - - - **Template**: The name of the template that will be used to create the virtual machines. The template must exist in the location you enter for the **Datacenter** parameter. - - - **Virtual Machine Names**: Enter the names of one or more virtual machines. Separate multiple names with a comma; for example, `VM1,VM2,VM3` - - - **Datacenter**: Enter the name of the datacenter where the virtual machines will be created. - - - **Compute Resource Type**: Select the type of hosting for the virtual machines: `VMware ESXi Host`, `Cluster`, or `Resource Pool` - - - **Host Name**: Depending on the option you selected for the compute resource type, enter the name of the host, cluster, or resource pool. - - - **Datastore**: Enter the name of the datastore that will hold the virtual machines' configuration and disk files. - - - **Description**: Optional. Enter a description to identify the deployment. - - - **Skip Certificate Authority Check**: If the vCenter Server's certificate is self-signed, select this option to skip the validation of the certificate by a trusted certificate authority. See the note for the previous step to check for the presence of a self-signed certificate.

      - -## Deploying build to virtual machines - -Once you have the virtual machines set up, deploying a build to those virtual machines is no different than deploying to any other machine. For instance, you can: - -* Use the [PowerShell on Target Machines](/azure/devops/pipelines/tasks/reference/powershell-on-target-machines-v3) task to run remote scripts on those machines using Windows Remote Management. -* Use [Deployment groups](../release/deployment-groups/index.md) to run scripts and other tasks on those machines using build and release agent. diff --git a/docs/pipelines/tasks/deploy/includes/rm-app-service-faqs-shared.md b/docs/pipelines/tasks/deploy/includes/rm-app-service-faqs-shared.md deleted file mode 100644 index bbe273d148c..00000000000 --- a/docs/pipelines/tasks/deploy/includes/rm-app-service-faqs-shared.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -author: ninallam -ms.subservice: azure-devops-pipelines-tasks -ms.topic: include -ms.date: 12/10/2019 -ms.manager: mijacobs -ms.author: ninallam ---- - -### How should I configure my service connection? - -This task requires an [Azure Resource Manager service connection](../../../release/azure-rm-endpoint.md). - -### How should I configure web job deployment with Application Insights? - -When you're deploying to an App Service, if you have [Application Insights](/azure/azure-monitor/app/app-insights-overview) configured and you've enabled `Remove additional files at destination`, you also need to enable `Exclude files from the App_Data folder`. Enabling this option keeps the Application Insights extension in a safe state. This step is required because the Application Insights continuous WebJob is installed into the App_Data folder. - -### How should I configure my agent if it's behind a proxy while I'm deploying to App Service? - -If your self-hosted agent requires a web proxy, you can inform the agent about the proxy during configuration. Doing so allows your agent to connect to Azure Pipelines or Azure DevOps Server through the proxy. [Learn more about running a self-hosted agent behind a web proxy](../../../agents/proxy.md?tabs=windows). \ No newline at end of file diff --git a/docs/pipelines/tasks/deploy/includes/rm-app-service-troubleshoot-shared.md b/docs/pipelines/tasks/deploy/includes/rm-app-service-troubleshoot-shared.md deleted file mode 100644 index 6a2ef2b37ca..00000000000 --- a/docs/pipelines/tasks/deploy/includes/rm-app-service-troubleshoot-shared.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -author: ninallam -ms.subservice: azure-devops-pipelines-tasks -ms.topic: include -ms.date: 12/10/2019 -ms.manager: mijacobs -ms.author: ninallam ---- - -### Error: Could not fetch access token for Azure. Verify if the Service Principal used is valid and not expired. - -The task uses the service principal in the service connection to authenticate with Azure. If the service principal has expired or doesn't have permissions to the App Service, the task fails with this error. Verify the validity of the service principal used and that it's present in the app registration. For more information, see - [Use role-based access control to manage access to your Azure subscription resources](/azure/role-based-access-control/role-assignments-portal). - [This blog post](https://devblogs.microsoft.com/devops/automating-azure-resource-group-deployment-using-a-service-principal-in-visual-studio-online-buildrelease-management/) - also contains more information about using service principal authentication. - -### SSL error - -If you want to use a certificate in App Service, the certificate must be signed by a trusted certificate authority. If your web app gives you certificate validation errors, you're probably using a self-signed certificate. Set a variable named `VSTS_ARM_REST_IGNORE_SSL_ERRORS` to the value `true` in the build or release pipeline to resolve the error. - -### A release hangs for long time and then fails - -This problem could be the result of insufficient capacity in your App Service plan. To resolve this problem, you can scale up the App Service instance to increase available CPU, RAM, and disk space or try with a different App Service plan. - -### 5*xx* error codes - -If you're seeing a 5*xx* error, [check the status of your Azure service](https://status.azure.com/status). - - diff --git a/docs/pipelines/tasks/deploy/includes/rm-webapp-functionapp-troubleshoot-shared.md b/docs/pipelines/tasks/deploy/includes/rm-webapp-functionapp-troubleshoot-shared.md deleted file mode 100644 index a9e932f24a4..00000000000 --- a/docs/pipelines/tasks/deploy/includes/rm-webapp-functionapp-troubleshoot-shared.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -author: ninallam -ms.subservice: azure-devops-pipelines-tasks -ms.topic: include -ms.date: 12/10/2019 -ms.manager: mijacobs -ms.author: ninallam ---- - -### Error: No package found with specified pattern - -Check if the package mentioned in the task is published as an artifact in the build or a previous stage and downloaded in the current job. - -### Error: Publish using zip deploy option is not supported for msBuild package type - -Web packages created via the MSBuild task (with default arguments) have a nested folder structure that can be deployed correctly only by Web Deploy. The publish-to-zip deployment option can't be used to deploy those packages. To convert the packaging structure, take these steps: - -1. In the Build solution task, change the **MSBuild Arguments** to -`/p:DeployOnBuild=true /p:DeployDefaultTarget=WebPublish /p:WebPublishMethod=FileSystem /p:DeleteExistingFiles=True /p:publishUrl="$(System.DefaultWorkingDirectory)\\WebAppContent"`: - - :::image type="content" source="../media/azure-rm-web-app-deployment-03.png" alt-text="Screenshot that shows the Build solution values."::: - -1. Add an Archive task and change the values as follows: - 1. Change **Root folder or file to archive** to - `$(System.DefaultWorkingDirectory)\\WebAppContent`. - - 1. Clear the **Prepend root folder name to archive paths** check box: - - :::image type="content" source="../media/azure-rm-web-app-deployment-04.png" alt-text="Screenshot that shows the Archive values."::: - diff --git a/docs/pipelines/tasks/file-matching-patterns.md b/docs/pipelines/tasks/file-matching-patterns.md index 624453e7b42..736a6f9d556 100644 --- a/docs/pipelines/tasks/file-matching-patterns.md +++ b/docs/pipelines/tasks/file-matching-patterns.md @@ -1,6 +1,5 @@ --- title: File matching patterns reference -ms.custom: seodec18 description: A reference guide that can help you to understand the file matching patterns for Azure Pipelines and Team Foundation Server (TFS). ms.topic: reference ms.assetid: 8A92C09C-3EE2-48EF-A2C0-3B2005AACFD7 diff --git a/docs/pipelines/tasks/includes/build-step-common-qa.md b/docs/pipelines/tasks/includes/build-step-common-qa.md deleted file mode 100644 index 672f7957586..00000000000 --- a/docs/pipelines/tasks/includes/build-step-common-qa.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 08/28/2021 -ms.subservice: azure-devops-pipelines-tasks ---- - -#### Q: I'm having issues with publishing my artifacts. How can I view the detailed logs? - -To enable detailed logs for your pipeline: - -1. Edit your pipeline and select **Variables** -1. Add a new variable with the name `System.Debug` and value `true` -1. **Save** - -#### Q: Which variables are available to me? - -A: `$(Build.SourcesDirectory)` and `$(Agent.BuildDirectory)` are just few of the variables you can use in your pipeline. Variables are available as [expressions](../../process/expressions.md) or scripts. - -See [Define variables](../../process/variables.md), [predefined variables](../../build/variables.md), and [Classic release and artifacts variables](../../release/variables.md) to learn about the different types of variables. - -#### Q: Task allows me to publish artifacts in deployment job in yaml pipeline, but I am not able to use it in downstream pipeline? - -A: Deployment jobs do not have the context of source branches and are hence not appropriate for publishing artifacts. They have been primarily designed to consume artifacts. A workaround would be to isolate that logic into a separate job (with dependencies on your deployment jobs). \ No newline at end of file diff --git a/docs/pipelines/tasks/includes/control-options-arguments-md.md b/docs/pipelines/tasks/includes/control-options-arguments-md.md deleted file mode 100644 index 4c7f6818ca3..00000000000 --- a/docs/pipelines/tasks/includes/control-options-arguments-md.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 05/04/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -[Control options](../../process/tasks.md#controloptions) \ No newline at end of file diff --git a/docs/pipelines/tasks/includes/control-options-arguments.md b/docs/pipelines/tasks/includes/control-options-arguments.md deleted file mode 100644 index 35c992aff25..00000000000 --- a/docs/pipelines/tasks/includes/control-options-arguments.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -ms.topic: include -ms.date: 02/26/2020 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -### [Task control options](../../process/tasks.md#controloptions) \ No newline at end of file diff --git a/docs/pipelines/tasks/includes/copyfiles-publishbuildartifacts-usage.md b/docs/pipelines/tasks/includes/copyfiles-publishbuildartifacts-usage.md deleted file mode 100644 index 08dc20bba01..00000000000 --- a/docs/pipelines/tasks/includes/copyfiles-publishbuildartifacts-usage.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -ms.topic: include -ms.date: 02/11/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -## Example - -```yaml -steps: -- task: CopyFiles@2 - inputs: - contents: '_buildOutput/**' - targetFolder: $(Build.ArtifactStagingDirectory) -- task: PublishBuildArtifacts@1 - inputs: - pathToPublish: $(Build.ArtifactStagingDirectory) - artifactName: MyBuildOutputs -``` \ No newline at end of file diff --git a/docs/pipelines/tasks/includes/deploy-winrm-setup.md b/docs/pipelines/tasks/includes/deploy-winrm-setup.md deleted file mode 100644 index 30a3329cb6e..00000000000 --- a/docs/pipelines/tasks/includes/deploy-winrm-setup.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - - - -This task uses [Windows Remote Management](/windows/win32/winrm/portal) -(WinRM) to access -on-premises physical computers or virtual computers that are -domain-joined or workgroup-joined. - -**To set up WinRM for on-premises physical computers or virtual machines** - -Follow the steps described in [domain-joined](../../apps/cd/deploy-webdeploy-iis-winrm.md) - -**To set up WinRM for Microsoft Azure Virtual Machines** - -Azure Virtual Machines require WinRM to use the HTTPS protocol. -You can use a self-signed Test Certificate. In this case, the -automation agent will not validate the authenticity of the -certificate as being issued by a trusted certification authority. - -* **Azure Classic Virtual Machines**. When you create a -[classic virtual machine](/azure/) -from the Azure portal, the virtual machine is already set up for -WinRM over HTTPS, with the default port 5986 already opened in the firewall -and a self-signed certificate installed on the machine. These virtual -machines can be accessed with no further configuration required. -Existing Classic virtual machines can be also selected by using the -[Azure Resource Group Deployment](https://github.com/Microsoft/azure-pipelines-tasks/tree/master/Tasks/AzureResourceGroupDeploymentV2) -task. - -* **Azure Resource Group**. If you have an -[Azure Resource Group](/azure/virtual-machines/windows/tutorial-manage-vm) - -already defined in the Azure portal, you must configure it to use the WinRM HTTPS -protocol. You need to open port 5986 in the firewall, and install a -self-signed certificate. - -To dynamically deploy Azure Resource Groups that contain virtual machines, use the -[Azure Resource Group Deployment](https://github.com/Microsoft/azure-pipelines-tasks/tree/master/Tasks/AzureResourceGroupDeploymentV2) -task. This task has a checkbox named **Enable Deployment Prerequisites**. Select -this to automatically set up the WinRM HTTPS protocol on the virtual machines, -open port 5986 in the firewall, and install a test certificate. The virtual machines -are then ready for use in the deployment task. \ No newline at end of file diff --git a/docs/pipelines/tasks/includes/msbuild_qa.md b/docs/pipelines/tasks/includes/msbuild_qa.md deleted file mode 100644 index 502747704df..00000000000 --- a/docs/pipelines/tasks/includes/msbuild_qa.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/23/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -### Should I use the Visual Studio Build task or the MSBuild task? - -If you are building a solution, in most cases you should use the [Visual Studio Build task](/azure/devops/pipelines/tasks/reference/vsbuild-v1). This task automatically: - -* Sets the `/p:VisualStudioVersion` property for you. This forces MSBuild to use a particular set of targets that increase the likelihood of a successful build. - -* Specifies the MSBuild version argument. - -In some cases you might need to use the [MSBuild task](/azure/devops/pipelines/tasks/reference/msbuild-v1). For example, you should use it if you are building code projects apart from a solution. - -### Where can I learn more about MSBuild? - -[MSBuild task](/azure/devops/pipelines/tasks/reference/msbuild-v1) - -[MSBuild reference](/visualstudio/msbuild/msbuild) - -[MSBuild command-line reference](/visualstudio/msbuild/msbuild-command-line-reference) - - -### How do I build multiple configurations for multiple platforms? - -

        -

      1. -On the Variables tab, make sure you've got variables defined for your configurations and platforms. To specify multiple values, separate them with commas. -

        -

        For example, for a .NET app you could specify:

        - - - - - - - - - - - - - - - -
        NameValue
        BuildConfigurationdebug, release
        BuildPlatformany cpu
        - -

        For example, for a C++ app you could specify:

        - - - - - - - - - - - - - - - -
        NameValue
        BuildConfigurationdebug, release
        BuildPlatformx86, x64
        -
        2. -

      2. On the Options tab select Parallel if you want to distribute the jobs (one for each combination of values) to multiple agents in parallel if they are available.

        -
        3. -

      3. On the Build tab, select this step and specify the Platform and Configuration arguments. For example:

        -
          -
        • Platform: $(BuildPlatform)
          • -
        • Configuration: $(BuildConfiguration)
          • -
        -
        4. -

      4. Under the agent job of the assigned task, on the Parallelism tab, select Multi-configuration and specify the Multipliers separated by commas. For example: BuildConfiguration, BuildPlatform

        -
        5. -
      - -### Can I build TFSBuild.proj files? - -You cannot build TFSBuild.proj files. These kinds of files are generated by TFS 2005 and 2008. These files contain tasks and targets are supported only using [XAML builds](/previous-versions/visualstudio/visual-studio-2013/ms181709(v=vs.120)). - -### Can I build SSIS, SSRS, and SSAS projects? - -No. MSBuild doesn't support building SQL Server Integration Services (SSIS), SQL Server Reporting Services (SSRS), or SQL Server Analysis Services (SSAS) projects out of the box. However, devenv.exe performs the same function as the **Build Solution** menu option in the integrated development environment. You can use the `devenv` command to build your SSIS solution. diff --git a/docs/pipelines/tasks/includes/nuget-create-step-examples.md b/docs/pipelines/tasks/includes/nuget-create-step-examples.md deleted file mode 100644 index 7b3b97acf13..00000000000 --- a/docs/pipelines/tasks/includes/nuget-create-step-examples.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -ms.topic: include -ms.date: 08/10/2016 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -You want to package and publish some projects in a C# class library to your Azure Artifacts feed. - -``` -`-- Message - |-- Message.sln - `-- ShortGreeting - |-- ShortGreeting.csproj - |-- Class1.cs - `-- Properties - |-- AssemblyInfo.cs - `-- LongGreeting - |-- LongGreeting.csproj - |-- Class1.cs - `-- Properties - |-- AssemblyInfo.cs -``` - - - -### Prepare - - -#### AssemblyInfo.cs - -Make sure your AssemblyInfo.cs files contain the information you want shown in your packages. For example, ```AssemblyCompanyAttribute``` will be shown as the author, and ```AssemblyDescriptionAttribute``` will be shown as the description. - - -#### [Variables](../../build/variables.md) tab - -| Name | Value | -|---|---| -|```$(BuildConfiguration)``` | ```release```| -|```$(BuildPlatform)``` | ```any cpu```| - - -#### [Options](../../build/options.md) - -| Setting | Value | -|---|---| -| Build number format | ```$(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)```| - - -### Publish to Azure Artifacts - -Make sure you've prepared the build as described [above](#prepare). - - -#### Create the feed - -See [Create a feed](../../../artifacts/index.yml). - - -#### [Build](../../index.yml) tasks - - - - - - - - - - - - - - -
      - -Build: Visual Studio Build - -
      Build: Visual Studio Build      		 -

      Build your solution.

      -
        -
      • Solution: *.sln
        • -
      • Platform: $(BuildPlatform)
        • -
      • Configuration: $(BuildConfiguration)
        • - -
      -
      - -Package: NuGet Packager - -
      Package: NuGet Packager      		 -

      Package your projects.

      -
        -
      • Path/Pattern to nuspec files: *.csproj
        • -
      • Use Build number to version package: Selected
        • -
      • Advanced, Configuration to Package: Release
        • -
      -
      - -Package: NuGet Publisher - -
      Package: NuGet Publisher      		 -

      Publish your packages to Azure Artifacts.

      - -
      - -### Publish to NuGet.org - -Make sure you've prepared the build as described [above](#prepare). - -#### Register with NuGet.org - -If you haven't already, [register with NuGet.org](https://www.nuget.org/). - - -#### [Build](../../tasks/index.md) tasks - - - - - - - - - - - - - - - -
      - -Build: Visual Studio Build - -
      Build: Visual Studio Build      		 -

      Build your solution.

      -
        -
      • Solution: *.sln
        • -
      • Platform: $(BuildPlatform)
        • -
      • Configuration: $(BuildConfiguration)
        • - -
      -
      - -Package: NuGet Packager - -
      Package: NuGet Packager      		 -

      Package your projects.

      -
        -
      • Path/Pattern to nuspec files: *.csproj
        • -
      • Use Build number to version package: Selected
        • -
      • Advanced, Configuration to Package: Release
        • -
      -
      - -Package: NuGet Publisher - -
      Package: NuGet Publisher      		 -

      Publish your packages to NuGet.org.

      -
        -
      • Path/Pattern to nupkg: ***.nupkg
        • -
      • Feed type: External NuGet Feed
        • -
      • -

        NuGet Server Endpoint:

        -
          -
        1. Click "New service connection", and then click Generic.
          2. -

        2. On the Add New Generic Connection dialog box:

          - -
          3. -
        -
        • -
      - -
      \ No newline at end of file diff --git a/docs/pipelines/tasks/includes/nuget-step-arguments.md b/docs/pipelines/tasks/includes/nuget-step-arguments.md deleted file mode 100644 index fc9269a0eef..00000000000 --- a/docs/pipelines/tasks/includes/nuget-step-arguments.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -ms.topic: include -ms.date: 08/10/2016 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - - -Path to NuGet.exe -(Optional) Path to your own instance of NuGet.exe. If you specify this argument, you must have your own strategy to handle authentication. - diff --git a/docs/pipelines/tasks/includes/nuget-step-qa.md b/docs/pipelines/tasks/includes/nuget-step-qa.md deleted file mode 100644 index ccb794ec938..00000000000 --- a/docs/pipelines/tasks/includes/nuget-step-qa.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -ms.topic: include -ms.date: 09/10/2019 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -### Why should I check in a NuGet.Config? - -Checking a NuGet.Config into source control ensures that a key piece of information needed to build your project, the location of its packages, is available to every developer that checks out your code. - -However, for situations where a team of developers works on a large range of projects, it's also possible to add an Azure Artifacts feed to the global NuGet.Config on each developer's machine. In these situations, using the "Feeds I select here" option in the NuGet task replicates this configuration. - -### Where can I learn about Azure Artifacts? - -[Azure Artifacts Documentation](../../../artifacts/index.yml) - -### Where can I learn more about NuGet? - -[NuGet Docs](https://docs.nuget.org/) Overview - -[NuGet Create](https://docs.nuget.org/create) Packaging and publishing - -[NuGet Consume](https://docs.nuget.org/consume) Setting up a solution to get dependencies - diff --git a/docs/pipelines/tasks/includes/qa-minimatch.md b/docs/pipelines/tasks/includes/qa-minimatch.md deleted file mode 100644 index 647f9ca2397..00000000000 --- a/docs/pipelines/tasks/includes/qa-minimatch.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -### Where can I learn more about file matching patterns? - -[File matching patterns reference](../file-matching-patterns.md) diff --git a/docs/pipelines/tasks/includes/qa-ssh-supported-keys.md b/docs/pipelines/tasks/includes/qa-ssh-supported-keys.md deleted file mode 100644 index 17abff26d20..00000000000 --- a/docs/pipelines/tasks/includes/qa-ssh-supported-keys.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.service: azure-devops-pipelines ---- - -### What key formats are supported for the SSH tasks? - -The Azure Pipelines SSH tasks use the Node.js `ssh2` package for SSH connections. Ensure that you are using the latest version of the SSH tasks. Older versions may not support the OpenSSH key format. - -If you run into an "Unsupported key format" error, then you may need to add the `-m PEM` flag to your `ssh-keygen` command so that the key is in a supported format. \ No newline at end of file diff --git a/docs/pipelines/tasks/includes/qa-test-azurerg-machine-group.md b/docs/pipelines/tasks/includes/qa-test-azurerg-machine-group.md deleted file mode 100644 index 4395ac7d8dc..00000000000 --- a/docs/pipelines/tasks/includes/qa-test-azurerg-machine-group.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - - -#### How do I create an Azure Resource Group for testing? - -See [Using the Azure Portal to manage your Azure resources](/azure/azure-resource-manager/management/manage-resources-portal) -and [Azure Resource Manager - Creating a Resource Group and a VNET](https://www.cicoria.com/azure-resource-manager-creating-a-resource-group-and-a-vnet/). \ No newline at end of file diff --git a/docs/pipelines/tasks/includes/qa-test-customize-code-coverage.md b/docs/pipelines/tasks/includes/qa-test-customize-code-coverage.md deleted file mode 100644 index 28a44687c9a..00000000000 --- a/docs/pipelines/tasks/includes/qa-test-customize-code-coverage.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -#### How can I customize code coverage analysis and manage inclusions and exclusions - -See [Customize Code Coverage Analysis](/visualstudio/test/customizing-code-coverage-analysis) diff --git a/docs/pipelines/tasks/includes/qa-test-run-settings-file.md b/docs/pipelines/tasks/includes/qa-test-run-settings-file.md deleted file mode 100644 index 127e5b423d7..00000000000 --- a/docs/pipelines/tasks/includes/qa-test-run-settings-file.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -#### Where can I get more information about the Run Settings file? - -See [Configure unit tests by using a .runsettings file](/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file) - -#### Where can I get more information about overriding settings in the Run Settings file? - -See [Supplying Run Time Parameters to Tests](https://devblogs.microsoft.com/devops/supplying-run-time-parameters-to-tests/) diff --git a/docs/pipelines/tasks/includes/yaml/ANTV1.md b/docs/pipelines/tasks/includes/yaml/ANTV1.md deleted file mode 100644 index c622eae171b..00000000000 --- a/docs/pipelines/tasks/includes/yaml/ANTV1.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/17/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Ant -# Build with Apache Ant -- task: Ant@1 - inputs: - #buildFile: 'build.xml' - #options: # Optional - #targets: # Optional - #publishJUnitResults: true - #testResultsFiles: '**/TEST-*.xml' # Required when publishJUnitResults == True - #testRunTitle: # Optional - #codeCoverageToolOptions: 'None' # Optional. Options: none, cobertura, jaCoCo - #codeCoverageClassFilesDirectories: '.' # Required when codeCoverageToolOptions != None - #codeCoverageClassFilter: # Optional. Comma-separated list of filters to include or exclude classes from collecting code coverage. For example: +:com.*,+:org.*,-:my.app*.* - #codeCoverageSourceDirectories: # Optional - #codeCoverageFailIfEmpty: false # Optional - #antHomeDirectory: # Optional - #javaHomeOption: 'JDKVersion' # Options: jDKVersion, path - #jdkVersionOption: 'default' # Optional. Options: default, 1.11, 1.10, 1.9, 1.8, 1.7, 1.6 - #jdkUserInputDirectory: # Required when javaHomeOption == Path - #jdkArchitectureOption: 'x64' # Optional. Options: x86, x64 -``` diff --git a/docs/pipelines/tasks/includes/yaml/AndroidSigningV3.md b/docs/pipelines/tasks/includes/yaml/AndroidSigningV3.md deleted file mode 100644 index 2a13874d55d..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AndroidSigningV3.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/17/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Android signing -# Sign and align Android APK files -- task: AndroidSigning@3 - inputs: - #apkFiles: '**/*.apk' - #apksign: true # Optional - #apksignerKeystoreFile: # Required when apksign == True - #apksignerKeystorePassword: # Optional - #apksignerKeystoreAlias: # Optional - #apksignerKeyPassword: # Optional - #apksignerArguments: '--verbose' # Optional - #apksignerFile: # Optional - #zipalign: true # Optional - #zipalignFile: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/AppCenterDistributeV1.md b/docs/pipelines/tasks/includes/yaml/AppCenterDistributeV1.md deleted file mode 100644 index f470c3fa6c2..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AppCenterDistributeV1.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 10/07/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# App Center distribute -# Distribute app builds to testers and users via Visual Studio App Center -- task: AppCenterDistribute@1 - inputs: - serverEndpoint: - appSlug: - appFile: - #symbolsOption: 'Apple' # Optional. Options: apple - #symbolsPath: # Optional - #symbolsPdbFiles: '**/*.pdb' # Optional - #symbolsDsymFiles: # Optional - #symbolsMappingTxtFile: # Optional - #symbolsIncludeParentDirectory: # Optional - #releaseNotesOption: 'input' # Options: input, file - #releaseNotesInput: # Required when releaseNotesOption == Input - #releaseNotesFile: # Required when releaseNotesOption == File - #isMandatory: false # Optional - #distributionGroupId: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/AppCenterDistributeV3.md b/docs/pipelines/tasks/includes/yaml/AppCenterDistributeV3.md deleted file mode 100644 index 7215ea1769e..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AppCenterDistributeV3.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# App Center distribute -# Distribute app builds to testers and users via Visual Studio App Center -- task: AppCenterDistribute@3 - inputs: - serverEndpoint: - appSlug: - appFile: - #symbolsOption: 'Apple' # Optional. Options: apple, android - #symbolsPath: # Optional - #symbolsPdbFiles: '**/*.pdb' # Optional - #symbolsDsymFiles: # Optional - #symbolsIncludeParentDirectory: # Optional - #releaseNotesOption: 'input' # Options: input, file - #releaseNotesInput: # Required when releaseNotesOption == Input - #releaseNotesFile: # Required when releaseNotesOption == File - #isMandatory: false # Optional - #destinationType: 'groups' # Options: groups, store - #distributionGroupId: # Optional - #destinationStoreId: # Required when destinationType == store - #isSilent: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/AppCenterTestV1.md b/docs/pipelines/tasks/includes/yaml/AppCenterTestV1.md deleted file mode 100644 index 4284599ffa1..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AppCenterTestV1.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 07/10/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# App Center test -# Test app packages with Visual Studio App Center -- task: AppCenterTest@1 - inputs: - appFile: - #artifactsDirectory: '$(Build.ArtifactStagingDirectory)/AppCenterTest' - #prepareTests: true # Optional - #frameworkOption: 'appium' # Required when prepareTests == True# Options: appium, espresso, calabash, uitest, xcuitest - #appiumBuildDirectory: # Required when prepareTests == True && Framework == Appium - #espressoBuildDirectory: # Optional - #espressoTestApkFile: # Optional - #calabashProjectDirectory: # Required when prepareTests == True && Framework == Calabash - #calabashConfigFile: # Optional - #calabashProfile: # Optional - #calabashSkipConfigCheck: # Optional - #uiTestBuildDirectory: # Required when prepareTests == True && Framework == Uitest - #uitestStorePath: # Optional - #uiTestStorePassword: # Optional - #uitestKeyAlias: # Optional - #uiTestKeyPassword: # Optional - #uiTestToolsDirectory: # Optional - #signInfo: # Optional - #xcUITestBuildDirectory: # Optional - #xcUITestIpaFile: # Optional - #prepareOptions: # Optional - #runTests: true # Optional - #credentialsOption: 'serviceEndpoint' # Required when runTests == True# Options: serviceEndpoint, inputs - #serverEndpoint: # Required when runTests == True && CredsType == ServiceEndpoint - #username: # Required when runTests == True && CredsType == Inputs - #password: # Required when runTests == True && CredsType == Inputs - #appSlug: # Required when runTests == True - #devices: # Required when runTests == True - #series: 'master' # Optional - #dsymDirectory: # Optional - #localeOption: 'en_US' # Required when runTests == True# Options: da_DK, nl_NL, en_GB, en_US, fr_FR, de_DE, ja_JP, ru_RU, es_MX, es_ES, user - #userDefinedLocale: # Optional - #loginOptions: # Optional - #runOptions: # Optional - #skipWaitingForResults: # Optional - #cliFile: # Optional - #showDebugOutput: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/ArchiveFilesV2.md b/docs/pipelines/tasks/includes/yaml/ArchiveFilesV2.md deleted file mode 100644 index e20c03bb8a5..00000000000 --- a/docs/pipelines/tasks/includes/yaml/ArchiveFilesV2.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -ms.topic: include -ms.date: 02/10/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Archive files -# Compress files into .7z, .tar.gz, or .zip -- task: ArchiveFiles@2 - inputs: - #rootFolderOrFile: '$(Build.BinariesDirectory)' - #includeRootFolder: true - #archiveType: 'zip' # Options: zip, 7z, tar, wim - #tarCompression: 'gz' # Optional. Options: gz, bz2, xz, none - #archiveFile: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip' - #replaceExistingArchive: true - #verbose: # Optional - #quiet: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureAppServiceManageV0.md b/docs/pipelines/tasks/includes/yaml/AzureAppServiceManageV0.md deleted file mode 100644 index 1941e24fdec..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureAppServiceManageV0.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure App Service manage -# Start, stop, restart, slot swap, slot delete, install site extensions or enable continuous monitoring for an Azure App Service -- task: AzureAppServiceManage@0 - inputs: - azureSubscription: - #action: 'Swap Slots' # Optional. Options: Swap Slots, Start Swap With Preview, Complete Swap, Cancel Swap, Start Azure App Service, Stop Azure App Service, Restart Azure App Service, Delete Slot, Install Extensions, Enable Continuous Monitoring, Start all continuous webjobs, Stop all continuous webjobs - webAppName: - #specifySlotOrASE: false # Optional - #resourceGroupName: # Required when action == Swap Slots || Action == Delete Slot || SpecifySlot == True - #sourceSlot: # Required when action == Swap Slots - #swapWithProduction: true # Optional - #targetSlot: # Required when action == Swap Slots && SwapWithProduction == False - #preserveVnet: false # Optional - #slot: 'production' # Required when action == Delete Slot || SpecifySlot == True - #extensionsList: # Required when action == Install Extensions - #outputVariable: # Optional - #appInsightsResourceGroupName: # Required when action == Enable Continuous Monitoring - #applicationInsightsResourceName: # Required when action == Enable Continuous Monitoring - #applicationInsightsWebTestName: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureCloudPowerShellDeploymentV1.md b/docs/pipelines/tasks/includes/yaml/AzureCloudPowerShellDeploymentV1.md deleted file mode 100644 index 3c32f217026..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureCloudPowerShellDeploymentV1.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure Cloud Service deployment -# Deploy an Azure Cloud Service -- task: AzureCloudPowerShellDeployment@1 - inputs: - azureClassicSubscription: - #storageAccount: # Required when enableAdvancedStorageOptions == False - serviceName: - serviceLocation: - csPkg: - csCfg: - #slotName: 'Production' - #deploymentLabel: '$(Build.BuildNumber)' # Optional - #appendDateTimeToLabel: false # Optional - #allowUpgrade: true - #simultaneousUpgrade: false # Optional - #forceUpgrade: false # Optional - #verifyRoleInstanceStatus: false # Optional - #diagnosticStorageAccountKeys: # Optional - #newServiceCustomCertificates: # Optional - #newServiceAdditionalArguments: # Optional - #newServiceAffinityGroup: # Optional - #enableAdvancedStorageOptions: false - #aRMConnectedServiceName: # Required when enableAdvancedStorageOptions == True - #aRMStorageAccount: # Required when enableAdvancedStorageOptions == True -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureFileCopyV3.md b/docs/pipelines/tasks/includes/yaml/AzureFileCopyV3.md deleted file mode 100644 index c072fb12598..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureFileCopyV3.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.service: azure-devops-pipelines ---- - -```YAML -# Azure file copy -# Copy files to Azure Blob Storage or virtual machines -- task: AzureFileCopy@3 - inputs: - sourcePath: - azureSubscription: - destination: # Options: azureBlob, azureVMs - storage: - #containerName: # Required when destination == AzureBlob - #blobPrefix: # Optional - #resourceGroup: # Required when destination == AzureVMs - #resourceFilteringMethod: 'machineNames' # Optional. Options: machineNames, tags - #machineNames: # Optional - #vmsAdminUserName: # Required when destination == AzureVMs - #vmsAdminPassword: # Required when destination == AzureVMs - #targetPath: # Required when destination == AzureVMs - #additionalArgumentsForBlobCopy: # Optional - #additionalArgumentsForVMCopy: # Optional - #enableCopyPrerequisites: false # Optional - #copyFilesInParallel: true # Optional - #cleanTargetBeforeCopy: false # Optional - #skipCACheck: true # Optional - #outputStorageUri: # Optional - #outputStorageContainerSasToken: # Optional - #sasTokenTimeOutInMinutes: # Optional -``` - -```YAML -# Example: Upload files from Pipeline staging directory to blob storage. -- task: AzureFileCopy@2 - displayName: 'Example Step Name - inputs: - sourcePath: '$(Build.ArtifactStagingDirectory)/BlobsToUpload' - additionalArgumentsForBlobCopy: | - '/Y' # Supresses all AZCopy Confirmations. Used here to allow overwrites - '/Pattern:*' # Pattern of files to copy. - '/S' # Recursive Copy - azureSubscription: 'Subscription Name' - destination: AzureBlob - storage: storageaccountname - containerName: storagecontainername - blobPrefix: targetdirectoryincontainer -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureFunctionV1.md b/docs/pipelines/tasks/includes/yaml/AzureFunctionV1.md deleted file mode 100644 index c46d685d1b4..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureFunctionV1.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/14/2021 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Invoke Azure Function -# Invoke an Azure Function -- task: AzureFunction@1 - inputs: - function: # Required. Azure function URL. Example: "https://azurefunctionapp.azurewebsites.net/api/HttpTriggerJS1" - key: # Required. Function key - #method: # Required. 'POST' # Options: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, PATCH - #headers: # Optional. Default value: '{Content-Type:application/json, PlanUrl: $(system.CollectionUri), ProjectId: $(system.TeamProjectId), HubName: $(system.HostType), PlanId: $(system.PlanId), JobId: $(system.JobId), TimelineId: $(system.TimelineId), TaskInstanceId: $(system.TaskInstanceId), AuthToken: $(system.AccessToken)}' - #queryParameters: # Optional - #body: # Required when method != GET && Method != HEAD - #waitForCompletion: # Required Default value:'ApiResponse' # Options: Callback, ApiResponse - #successCriteria: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureKeyVaultV1.md b/docs/pipelines/tasks/includes/yaml/AzureKeyVaultV1.md deleted file mode 100644 index f4a53ef87f1..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureKeyVaultV1.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure Key Vault -# Download Azure Key Vault secrets -- task: AzureKeyVault@1 - inputs: - azureSubscription: - keyVaultName: - secretsFilter: '*' - runAsPreJob: false # Azure DevOps Services only -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureMonitorAlertsV0.md b/docs/pipelines/tasks/includes/yaml/AzureMonitorAlertsV0.md deleted file mode 100644 index 915a42f83b7..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureMonitorAlertsV0.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure Monitor alerts -# Configure alerts on available metrics for an Azure resource -- task: AzureMonitorAlerts@0 - inputs: - azureSubscription: - resourceGroupName: - #resourceType: 'Microsoft.Insights/components' # Options: microsoft.Insights/Components, microsoft.Web/Sites, microsoft.Storage/StorageAccounts, microsoft.Compute/VirtualMachines - resourceName: - alertRules: - #notifyServiceOwners: # Optional - #notifyEmails: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureMonitorV1.md b/docs/pipelines/tasks/includes/yaml/AzureMonitorV1.md deleted file mode 100644 index 75c49165f51..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureMonitorV1.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Query Azure Monitor alerts -# Observe the configured Azure Monitor rules for active alerts -- task: AzureMonitor@1 - inputs: - connectedServiceNameARM: - resourceGroupName: - #filterType: 'none' # Options: resource, alertrule, none - #resource: # Required when filterType == Resource - #alertRule: # Required when filterType == Alertrule - #severity: 'Sev0,Sev1,Sev2,Sev3,Sev4' # Optional. Options: sev0, sev1, sev2, sev3, sev4 - #timeRange: '1h' # Optional. Options: 1h, 1d, 7d, 30d - #alertState: 'Acknowledged,New' # Optional. Options: new, acknowledged, closed - #monitorCondition: 'Fired' # Optional. Options: fired , resolved -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureMysqlDeploymentV1.md b/docs/pipelines/tasks/includes/yaml/AzureMysqlDeploymentV1.md deleted file mode 100644 index f7ae0380a80..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureMysqlDeploymentV1.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure Database for MySQL deployment -# Run your scripts and make changes to your Azure Database for MySQL -- task: AzureMysqlDeployment@1 - inputs: - ConnectedServiceName: # Or alias azureSubscription - ServerName: - #DatabaseName: # Optional - SqlUsername: - SqlPassword: - #TaskNameSelector: 'SqlTaskFile' # Optional. Options: SqlTaskFile, InlineSqlTask - #SqlFile: # Required when taskNameSelector == SqlTaskFile - #SqlInline: # Required when taskNameSelector == InlineSqlTask - #SqlAdditionalArguments: # Optional - #IpDetectionMethod: 'AutoDetect' # Options: AutoDetect, IPAddressRange - #StartIpAddress: # Required when ipDetectionMethod == IPAddressRange - #EndIpAddress: # Required when ipDetectionMethod == IPAddressRange - #DeleteFirewallRule: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureNLBManagementV1.md b/docs/pipelines/tasks/includes/yaml/AzureNLBManagementV1.md deleted file mode 100644 index b527920d3de..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureNLBManagementV1.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 02/11/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure Network Load Balancer -# Connect or disconnect an Azure virtual machine's network interface to a Load Balancer's back end address pool -- task: AzureNLBManagement@1 - inputs: - azureSubscription: - resourceGroupName: - loadBalancer: - action: # Options: disconnect, connect -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzurePolicyV0.md b/docs/pipelines/tasks/includes/yaml/AzurePolicyV0.md deleted file mode 100644 index a9127a59243..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzurePolicyV0.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 03/12/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Check Azure Policy compliance -# Security and compliance assessment for Azure Policy -- task: AzurePolicyCheckGate@0 - inputs: - azureSubscription: - #resourceGroupName: # Optional - #resources: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzurePowerShellV5.md b/docs/pipelines/tasks/includes/yaml/AzurePowerShellV5.md deleted file mode 100644 index efabe967c8a..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzurePowerShellV5.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 06/01/2022 -ms.subservice: azure-devops-pipelines-tasks -ms.custom: devx-track-azurepowershell ---- - -```YAML -# Azure PowerShell -# Run a PowerShell script within an Azure environment -- task: AzurePowerShell@5 - inputs: - #ConnectedServiceNameARM: Required. Name of Azure Resource Manager service connection. You can also use azureSubscription. - #scriptType: 'FilePath' # Optional. Options: filePath, inlineScript - #scriptPath: # Optional - #inline: # Optional. You can write your Azure PowerShell scripts inline here. You can also pass predefined and custom variables to this script using arguments - #scriptArguments: # Optional - #errorActionPreference: 'stop' # Optional. Options: stop, continue, silentlyContinue - #failOnStandardError: false # Optional - #TargetAzurePs: 'OtherVersion' # Required. Options: latestVersion, otherVersion. You can also use azurePowerShellVersion. - #CustomTargetAzurePs: # Required when azurePowerShellVersion == OtherVersion. You can also use preferredAzurePowerShellVersion. - #pwsh: true # Optional. If this is true, PowerShell Core pwsh.exe will be used in Windows environments. - #workingDirectory: '' # Optional. The working directory where the script is run. -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzurePowerShellV5Sample.md b/docs/pipelines/tasks/includes/yaml/AzurePowerShellV5Sample.md deleted file mode 100644 index f347d21396f..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzurePowerShellV5Sample.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -- task: AzurePowerShell@5 - inputs: - azureSubscription: my-arm-service-connection - scriptType: filePath - scriptPath: $(Build.SourcesDirectory)\myscript.ps1 - scriptArguments: - -Arg1 val1 ` - -Arg2 val2 ` - -Arg3 val3 - azurePowerShellVersion: latestVersion - pwsh: true -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureResourceGroupDeploymentV2.md b/docs/pipelines/tasks/includes/yaml/AzureResourceGroupDeploymentV2.md deleted file mode 100644 index 66cd93617b7..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureResourceGroupDeploymentV2.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 02/10/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure resource group deployment -# Deploy an Azure Resource Manager (ARM) template to a resource group and manage virtual machines -- task: AzureResourceGroupDeployment@2 - inputs: - azureSubscription: - #action: 'Create Or Update Resource Group' # Options: create Or Update Resource Group, select Resource Group, start, stop, stopWithDeallocate, restart, delete, deleteRG - resourceGroupName: - #location: # Required when action == Create Or Update Resource Group - #templateLocation: 'Linked artifact' # Options: linked Artifact, uRL Of The File - #csmFileLink: # Required when templateLocation == URL Of The File - #csmParametersFileLink: # Optional - #csmFile: # Required when TemplateLocation == Linked Artifact - #csmParametersFile: # Optional - #overrideParameters: # Optional - #deploymentMode: 'Incremental' # Options: Incremental, Complete, Validation - #enableDeploymentPrerequisites: 'None' # Optional. Options: none, configureVMwithWinRM, configureVMWithDGAgent - #teamServicesConnection: # Required when enableDeploymentPrerequisites == ConfigureVMWithDGAgent - #teamProject: # Required when enableDeploymentPrerequisites == ConfigureVMWithDGAgent - #deploymentGroupName: # Required when enableDeploymentPrerequisites == ConfigureVMWithDGAgent - #copyAzureVMTags: true # Optional - #runAgentServiceAsUser: # Optional - #userName: # Required when enableDeploymentPrerequisites == ConfigureVMWithDGAgent && RunAgentServiceAsUser == True - #password: # Optional - #outputVariable: # Optional - #deploymentName: # Optional - #deploymentOutputs: # Optional - #addSpnToEnvironment: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/AzureStaticWebAppv0.md b/docs/pipelines/tasks/includes/yaml/AzureStaticWebAppv0.md deleted file mode 100644 index a5c1fe6d8e1..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureStaticWebAppv0.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -ms.topic: include -ms.date: 02/24/2022 -ms.subservice: azure-devops-pipelines-tasks ---- - -```yml -- task: AzureStaticWebApp@0 - inputs: - app_location: # (Optional) File path. Directory location of the application source code relative to working directory - app_build_command: # (Optional) String. Custom command for Oryx to run when building application source code. - output_location: # (Optional) String. Directory location of the compiled application code after building. - api_location: # (Optional) String. Directory location of the Azure Functions source code relative to working directory. - api_build_command: # (Optional) Custom command for Oryx to run when building Azure Functions source code. - routes_location: # (Optional) Directory location where the routes.json file can be found, relative to working directory. Use staticwebapp.config.json. - config_file_location: # (Optional) Directory location where the staticwebapp.config.json file can be found, relative to working directory. - skip_app_build: # (Optional) Skips Oryx build for app folder. - verbose: # (Optional) Enables verbose logging. - build_timeout_in_minutes: # (Optional) Time limit of Oryx app folder build in minutes. - azure_static_web_apps_api_token: # (Optional) Api token for deployment. Not required if passed as an environment variable. -``` \ No newline at end of file diff --git a/docs/pipelines/tasks/includes/yaml/AzureVmssDeploymentV0.md b/docs/pipelines/tasks/includes/yaml/AzureVmssDeploymentV0.md deleted file mode 100644 index 1591aacc2f6..00000000000 --- a/docs/pipelines/tasks/includes/yaml/AzureVmssDeploymentV0.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure VM scale set deployment -# Deploy a virtual machine scale set image -- task: AzureVmssDeployment@0 - inputs: - azureSubscription: - #action: 'Update image' # Options: update Image, configure Application Startup - vmssName: - vmssOsType: # Options: windows, linux - imageUrl: - #customScriptsDirectory: # Optional - #customScript: # Optional - #customScriptArguments: # Optional - #customScriptsStorageAccount: # Optional - #skipArchivingCustomScripts: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/BashV3.md b/docs/pipelines/tasks/includes/yaml/BashV3.md deleted file mode 100644 index 9cbce4b3f78..00000000000 --- a/docs/pipelines/tasks/includes/yaml/BashV3.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -ms.topic: include -ms.date: 02/11/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Bash -# Run a Bash script on macOS, Linux, or Windows -- task: Bash@3 - inputs: - #targetType: 'filePath' # Optional. Options: filePath, inline - #filePath: # Required when targetType == FilePath - #arguments: # Optional - #script: '# echo Hello world' # Required when targetType == inline - #workingDirectory: # Optional - #failOnStderr: false # Optional - #bashEnvValue: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/BatchScriptV1.md b/docs/pipelines/tasks/includes/yaml/BatchScriptV1.md deleted file mode 100644 index 26aa5b4a42c..00000000000 --- a/docs/pipelines/tasks/includes/yaml/BatchScriptV1.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -ms.date: 02/18/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Batch script -# Run a Windows command or batch script and optionally allow it to change the environment -- task: BatchScript@1 - inputs: - filename: - #arguments: # Optional - #modifyEnvironment: False # Optional - #workingFolder: # Optional - #failOnStandardError: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/CMakeV1.md b/docs/pipelines/tasks/includes/yaml/CMakeV1.md deleted file mode 100644 index 45f64f7a544..00000000000 --- a/docs/pipelines/tasks/includes/yaml/CMakeV1.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -ms.topic: include -author: wnjenkin -ms.author: whjenkin -ms.date: 12/17/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# CMake -# Build with the CMake cross-platform build system -- task: CMake@1 - inputs: - #workingDirectory: 'build' # Optional - #cmakeArgs: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/CUrlUploaderV2.md b/docs/pipelines/tasks/includes/yaml/CUrlUploaderV2.md deleted file mode 100644 index 5d14a5796d2..00000000000 --- a/docs/pipelines/tasks/includes/yaml/CUrlUploaderV2.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 02/12/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# cURL upload files -# Use cURL's supported protocols to upload files -- task: cURLUploader@2 - inputs: - files: - #authType: 'ServiceEndpoint' # Optional. Options: serviceEndpoint, userAndPass - #serviceEndpoint: # Required when authType == ServiceEndpoint - #username: # Optional - #password: # Optional - #url: # Required when authType == UserAndPass - #remotePath: 'upload/$(Build.BuildId)/' # Optional - #options: # Optional - #redirectStderr: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/ChefKnifeV1.md b/docs/pipelines/tasks/includes/yaml/ChefKnifeV1.md deleted file mode 100644 index 3799328425e..00000000000 --- a/docs/pipelines/tasks/includes/yaml/ChefKnifeV1.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Chef Knife -# Run scripts with Knife commands on your Chef workstation -- task: ChefKnife@1 - inputs: - connectedServiceName: - scriptPath: - #scriptArguments: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/ChefV1.md b/docs/pipelines/tasks/includes/yaml/ChefV1.md deleted file mode 100644 index ebe268696dd..00000000000 --- a/docs/pipelines/tasks/includes/yaml/ChefV1.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Chef -# Deploy to Chef environments by editing environment attributes -- task: Chef@1 - inputs: - connectedServiceName: - environment: - attributes: - #chefWaitTime: '30' -``` diff --git a/docs/pipelines/tasks/includes/yaml/CmdLineV2.md b/docs/pipelines/tasks/includes/yaml/CmdLineV2.md deleted file mode 100644 index b7d5e2d096c..00000000000 --- a/docs/pipelines/tasks/includes/yaml/CmdLineV2.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.topic: include -ms.date: 04/07/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Command line -# Run a command line script using Bash on Linux and macOS and cmd.exe on Windows -- task: CmdLine@2 - inputs: - script: 'echo Write your commands here.' - #workingDirectory: # Optional - #failOnStderr: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/CocoaPodsV0.md b/docs/pipelines/tasks/includes/yaml/CocoaPodsV0.md deleted file mode 100644 index a2fa16bd077..00000000000 --- a/docs/pipelines/tasks/includes/yaml/CocoaPodsV0.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 08/10/2016 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# CocoaPods -# Install CocoaPods dependencies for Swift and Objective-C Cocoa projects -- task: CocoaPods@0 - inputs: - #workingDirectory: # Optional - forceRepoUpdate: - #projectDirectory: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/CondaEnvironmentV1.md b/docs/pipelines/tasks/includes/yaml/CondaEnvironmentV1.md deleted file mode 100644 index 9c336bd9c39..00000000000 --- a/docs/pipelines/tasks/includes/yaml/CondaEnvironmentV1.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 11/16/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Conda environment -# This task is deprecated. Use `conda` directly in script to work with Anaconda environments. -- task: CondaEnvironment@1 - inputs: - #createCustomEnvironment: # Optional - #environmentName: # Required when createCustomEnvironment == True - #packageSpecs: 'python=3' # Optional - #updateConda: true # Optional - #installOptions: # Optional - #createOptions: # Optional - #cleanEnvironment: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/ContainerStructureTestV1.md b/docs/pipelines/tasks/includes/yaml/ContainerStructureTestV1.md deleted file mode 100644 index cc524ffc46a..00000000000 --- a/docs/pipelines/tasks/includes/yaml/ContainerStructureTestV1.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -author: Additi -ms.date: 10/01/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -steps: -- task: ContainerStructureTest@0 - displayName: 'Container Structure Test ' - inputs: - dockerRegistryServiceConnection: 'Container_dockerHub' - repository: adma/hellodocker - tag: v1 - configFile: /home/user/cstfiles/fileexisttest.yaml -``` diff --git a/docs/pipelines/tasks/includes/yaml/CopyFilesOverSSHV0.md b/docs/pipelines/tasks/includes/yaml/CopyFilesOverSSHV0.md deleted file mode 100644 index 5566fe4cdd4..00000000000 --- a/docs/pipelines/tasks/includes/yaml/CopyFilesOverSSHV0.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.service: azure-devops-pipelines ---- - -```YAML -# Copy files over SSH -# Copy files or build artifacts to a remote machine over SSH -- task: CopyFilesOverSSH@0 - inputs: - sshEndpoint: - #sourceFolder: # Optional - #contents: '**' - #targetFolder: # Optional - #cleanTargetFolder: false # Optional - #overwrite: true # Optional - #failOnEmptySource: false # Optional - #flattenFolders: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/CopyFilesV2.md b/docs/pipelines/tasks/includes/yaml/CopyFilesV2.md deleted file mode 100644 index 32eb96f1ae3..00000000000 --- a/docs/pipelines/tasks/includes/yaml/CopyFilesV2.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -ms.topic: include -ms.date: 02/11/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Copy files -# Copy files from a source folder to a target folder using patterns matching file paths (not folder paths) -- task: CopyFiles@2 - inputs: - #sourceFolder: # Optional - #contents: '**' - targetFolder: - #cleanTargetFolder: false # Optional - #overWrite: false # Optional - #flattenFolders: false # Optional - #preserveTimestamp: false # Optional - #retryCount: 0 # Optional - #ignoreMakeDirErrors: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/DecryptFileV1.md b/docs/pipelines/tasks/includes/yaml/DecryptFileV1.md deleted file mode 100644 index a7c7b8d4b67..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DecryptFileV1.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 02/12/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Decrypt file (OpenSSL) -# Decrypt a file using OpenSSL -- task: DecryptFile@1 - inputs: - #cipher: 'des3' - inFile: - passphrase: - #outFile: # Optional - #workingDirectory: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/DelayV1.md b/docs/pipelines/tasks/includes/yaml/DelayV1.md deleted file mode 100644 index fe7f7b002fc..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DelayV1.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 02/12/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Delay -# Delay further execution of a workflow by a fixed time -jobs: -- job: RunsOnServer - pool: Server - steps: - - task: Delay@1 - inputs: - #delayForMinutes: '0' -``` diff --git a/docs/pipelines/tasks/includes/yaml/DeleteFilesV1.md b/docs/pipelines/tasks/includes/yaml/DeleteFilesV1.md deleted file mode 100644 index 1a504ecacca..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DeleteFilesV1.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.topic: include -ms.date: 02/12/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Delete files -# Delete folders, or files matching a pattern -- task: DeleteFiles@1 - inputs: - #SourceFolder: # Optional - #Contents: 'myFileShare' - #RemoveSourceFolder: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/DeployVisualStudioTestAgentV2.md b/docs/pipelines/tasks/includes/yaml/DeployVisualStudioTestAgentV2.md deleted file mode 100644 index 9314ea30746..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DeployVisualStudioTestAgentV2.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Visual Studio test agent deployment -# Deprecated: Instead, use the 'Visual Studio Test' task to run unit and functional tests -- task: DeployVisualStudioTestAgent@2 - inputs: - testMachines: - adminUserName: - adminPassword: - #winRmProtocol: 'Http' # Options: http, https - #testCertificate: true # Optional - machineUserName: - machinePassword: - #runAsProcess: false # Optional - #isDataCollectionOnly: false # Optional - #testPlatform: '14.0' # Optional. Options: 15.0, 14.0 - #agentLocation: # Optional - #updateTestAgent: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/DotNetCoreCLIV2.md b/docs/pipelines/tasks/includes/yaml/DotNetCoreCLIV2.md deleted file mode 100644 index 59a34a38c9b..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DotNetCoreCLIV2.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -ms.topic: include -author: pulkitaggarwl -ms.author: puagarw -ms.date: 10/30/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# .NET Core -# Build, test, package, or publish a dotnet application, or run a custom dotnet command -- task: DotNetCoreCLI@2 - inputs: - #command: 'build' # Options: build, push, pack, publish, restore, run, test, custom - #publishWebProjects: true # Required when command == Publish - #projects: # Optional - #custom: # Required when command == Custom - #arguments: # Optional - #publishTestResults: true # Optional - #testRunTitle: # Optional - #zipAfterPublish: true # Optional - #modifyOutputPath: true # Optional - #feedsToUse: 'select' # Options: select, config - #vstsFeed: # Required when feedsToUse == Select - #feedRestore: # Required when command == restore. projectName/feedName for project-scoped feed. FeedName only for organization-scoped feed. - #includeNuGetOrg: true # Required when feedsToUse == Select - #nugetConfigPath: # Required when feedsToUse == Config - #externalFeedCredentials: # Optional - #noCache: false - restoreDirectory: - #restoreArguments: # Optional - #verbosityRestore: 'Detailed' # Options: -, quiet, minimal, normal, detailed, diagnostic - #packagesToPush: '$(Build.ArtifactStagingDirectory)/*.nupkg' # Required when command == Push - #nuGetFeedType: 'internal' # Required when command == Push# Options: internal, external - #publishVstsFeed: # Required when command == Push && NuGetFeedType == Internal - #publishPackageMetadata: true # Optional - #publishFeedCredentials: # Required when command == Push && NuGetFeedType == External - #packagesToPack: '**/*.csproj' # Required when command == Pack - #packDirectory: '$(Build.ArtifactStagingDirectory)' # Optional - #nobuild: false # Optional - #includesymbols: false # Optional - #includesource: false # Optional - #versioningScheme: 'off' # Options: off, byPrereleaseNumber, byEnvVar, byBuildNumber - #versionEnvVar: # Required when versioningScheme == byEnvVar - #majorVersion: '1' # Required when versioningScheme == ByPrereleaseNumber - #minorVersion: '0' # Required when versioningScheme == ByPrereleaseNumber - #patchVersion: '0' # Required when versioningScheme == ByPrereleaseNumber - #buildProperties: # Optional - #verbosityPack: 'Detailed' # Options: -, quiet, minimal, normal, detailed, diagnostic - workingDirectory: -``` diff --git a/docs/pipelines/tasks/includes/yaml/DownloadBuildArtifactsV0.md b/docs/pipelines/tasks/includes/yaml/DownloadBuildArtifactsV0.md deleted file mode 100644 index 24318d72c4c..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DownloadBuildArtifactsV0.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 02/12/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Download build artifacts -# Download files that were saved as artifacts of a completed build -- task: DownloadBuildArtifacts@0 - inputs: - #buildType: 'current' # Options: current, specific - #project: # Required when buildType == Specific - #pipeline: # Required when buildType == Specific - #specificBuildWithTriggering: false # Optional - #buildVersionToDownload: 'latest' # Required when buildType == Specific. Options: latest, latestFromBranch, specific - #allowPartiallySucceededBuilds: false # Optional - #branchName: 'refs/heads/main' # Required when buildType == Specific && BuildVersionToDownload == LatestFromBranch - #buildId: # Required when buildType == Specific && BuildVersionToDownload == Specific - #tags: # Optional - #downloadType: 'single' # Choose whether to download a single artifact or all artifacts of a specific build. Options: single, specific - #artifactName: # Required when downloadType == Single - #itemPattern: '**' # Optional - #downloadPath: '$(System.ArtifactsDirectory)' - #cleanDestinationFolder: false # Optional - #parallelizationLimit: '8' # Optional - #extractTars: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/DownloadFileshareArtifactsV0.md b/docs/pipelines/tasks/includes/yaml/DownloadFileshareArtifactsV0.md deleted file mode 100644 index 6faa6bba9ea..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DownloadFileshareArtifactsV0.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Download artifacts from file share -# Download artifacts from a file share, like \\share\drop -- task: DownloadFileshareArtifacts@1 - inputs: - filesharePath: - artifactName: - #itemPattern: '**' # Optional - #downloadPath: '$(System.ArtifactsDirectory)' - #parallelizationLimit: '8' # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/DownloadGitHubReleaseV0.md b/docs/pipelines/tasks/includes/yaml/DownloadGitHubReleaseV0.md deleted file mode 100644 index c6e01348ec6..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DownloadGitHubReleaseV0.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -ms.topic: include -author: ashokirla -ms.author: ashkir -ms.date: 02/03/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Download GitHub Release -# Downloads a GitHub Release from a repository -- task: DownloadGitHubRelease@0 - inputs: - connection: - userRepository: - #defaultVersionType: 'latest' # Options: latest, specificVersion, specificTag - #version: # Required when defaultVersionType != Latest - #itemPattern: '**' # Optional - #downloadPath: '$(System.ArtifactsDirectory)' -``` diff --git a/docs/pipelines/tasks/includes/yaml/DownloadPackageV1.md b/docs/pipelines/tasks/includes/yaml/DownloadPackageV1.md deleted file mode 100644 index 103ff04c0c6..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DownloadPackageV1.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -ms.topic: include -ms.date: 07/23/2020 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Download package -# Download a package from a package management feed in Azure Artifacts -- task: DownloadPackage@1 - inputs: - packageType: # 'nuget' Options: maven, npm, nuget, pypi, upack - feed: # for organization-scoped feeds, / for project-scoped feeds. - #view: ' ' # Optional - definition: # '$(packageName)' - version: # '1.0.0' or 'latest' - #files: '**' # Optional - #extract: true # Optional - downloadPath: # '$(System.ArtifactsDirectory)' -``` diff --git a/docs/pipelines/tasks/includes/yaml/DownloadPipelineArtifactV2.md b/docs/pipelines/tasks/includes/yaml/DownloadPipelineArtifactV2.md deleted file mode 100644 index 8c1dd4816f0..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DownloadPipelineArtifactV2.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 01/23/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Download pipeline artifacts -# Download build and pipeline artifacts -- task: DownloadPipelineArtifact@2 - inputs: - #source: 'current' # Options: current, specific - #project: # Required when source == Specific - #pipeline: # Required when source == Specific - #preferTriggeringPipeline: false # Optional - #runVersion: 'latest' # Required when source == Specific# Options: latest, latestFromBranch, specific - #runBranch: 'refs/heads/main' # Required when source == Specific && RunVersion == LatestFromBranch - #runId: # Required when source == Specific && RunVersion == Specific - #tags: # Optional - #artifact: # Optional - #patterns: '**' # Optional - #path: '$(Pipeline.Workspace)' -``` diff --git a/docs/pipelines/tasks/includes/yaml/DownloadSecureFileV1.md b/docs/pipelines/tasks/includes/yaml/DownloadSecureFileV1.md deleted file mode 100644 index 131f0e6bf4b..00000000000 --- a/docs/pipelines/tasks/includes/yaml/DownloadSecureFileV1.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Download secure file -# Download a secure file to the agent machine -- task: DownloadSecureFile@1 - name: mySecureFile # The name with which to reference the secure file's path on the agent, like $(mySecureFile.secureFilePath) - inputs: - secureFile: # The file name or GUID of the secure file - #retryCount: 5 # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/ExtractFilesV1.md b/docs/pipelines/tasks/includes/yaml/ExtractFilesV1.md deleted file mode 100644 index 8466a5258e1..00000000000 --- a/docs/pipelines/tasks/includes/yaml/ExtractFilesV1.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Extract files -# Extract a variety of archive and compression files such as .7z, .rar, .tar.gz, and .zip -- task: ExtractFiles@1 - inputs: - #archiveFilePatterns: '**/*.zip' - destinationFolder: - #cleanDestinationFolder: true - #overwriteExistingFiles: false - #pathToSevenZipTool: -``` diff --git a/docs/pipelines/tasks/includes/yaml/FileTransformV1.md b/docs/pipelines/tasks/includes/yaml/FileTransformV1.md deleted file mode 100644 index 87b351f9b86..00000000000 --- a/docs/pipelines/tasks/includes/yaml/FileTransformV1.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 02/21/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# File transform -# Replace tokens with variable values in XML or JSON configuration files -- task: FileTransform@1 - inputs: - #folderPath: '$(System.DefaultWorkingDirectory)/**/*.zip' - #enableXmlTransform: # Optional - #xmlTransformationRules: '-transform **\*.Release.config -xml **\*.config-transform **\*.$(Environment.Name).config -xml **\*.config' # Optional - #fileType: # Optional. Options: xml, json - #targetFiles: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/FtpUploadV2.md b/docs/pipelines/tasks/includes/yaml/FtpUploadV2.md deleted file mode 100644 index 4bfab64ba78..00000000000 --- a/docs/pipelines/tasks/includes/yaml/FtpUploadV2.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 01/01/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# FTP upload -# Upload files using FTP -- task: FtpUpload@2 - inputs: - #credentialsOption: 'serviceEndpoint' # Options: serviceEndpoint, inputs - #serverEndpoint: # Required when credentialsOption == ServiceEndpoint - #serverUrl: # Required when credentialsOption == Inputs - #username: # Required when credentialsOption == Inputs - #password: # Required when credentialsOption == Inputs - rootDirectory: - #filePatterns: '**' - #remoteDirectory: '/upload/$(Build.BuildId)/' - #clean: false - #cleanContents: false # Required when clean == False - #preservePaths: false - #trustSSL: false -``` diff --git a/docs/pipelines/tasks/includes/yaml/GitHubReleaseV0.md b/docs/pipelines/tasks/includes/yaml/GitHubReleaseV0.md deleted file mode 100644 index 69fdd9c87f1..00000000000 --- a/docs/pipelines/tasks/includes/yaml/GitHubReleaseV0.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -ms.topic: include -author: ashokirla -ms.author: ashkir -ms.date: 10/27/2021 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# GitHub Release -# Create, edit, or delete a GitHub release -- task: GitHubRelease@0 - inputs: - gitHubConnection: - #repositoryName: '$(Build.Repository.Name)' - #action: 'create' # Options: create, edit, delete - #target: '$(Build.SourceVersion)' # Required when action == Create || Action == Edit - #tagSource: 'auto' # Required when action == Create# Options: auto, manual - #tagPattern: # Optional - #tag: # Required when action == Edit || Action == Delete || TagSource == Manual - #title: # Optional - #releaseNotesSource: 'file' # Optional. Options: file, inline - #releaseNotesInline: Use this option to manually enter release notes. Use with releaseNotesSource = inline - #releaseNotesFilePath: # Optional. Use the contents of a file as release notes. - #releaseNotes: # Optional - #assets: '$(Build.ArtifactStagingDirectory)/*' # Optional - #assetUploadMode: 'delete' # Optional. Options: delete, replace - #isDraft: false # Optional - #isPreRelease: false # Optional - #addChangeLog: true # Optional - #compareWith: 'lastFullRelease' # Required when addChangeLog == True. Options: lastFullRelease, lastRelease, lastReleaseByTag - #releaseTag: # Required when compareWith == LastReleaseByTag -``` diff --git a/docs/pipelines/tasks/includes/yaml/GoToolV0.md b/docs/pipelines/tasks/includes/yaml/GoToolV0.md deleted file mode 100644 index 953d3cb1913..00000000000 --- a/docs/pipelines/tasks/includes/yaml/GoToolV0.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -author: azooinmyluggage -ms.author: atulmal -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Go tool installer -# Find in cache or download a specific version of Go and add it to the PATH -- task: GoTool@0 - inputs: - #version: '1.10' - #goPath: # Optional - #goBin: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/GoV0.md b/docs/pipelines/tasks/includes/yaml/GoV0.md deleted file mode 100644 index 2eb0eedc4da..00000000000 --- a/docs/pipelines/tasks/includes/yaml/GoV0.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -ms.topic: include -author: shashankbarsin -ms.author: shasb -ms.date: 12/17/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Go -# Get, build, or test a Go application, or run a custom Go command -- task: Go@0 - inputs: - #command: 'get' # Options: get, build, test, custom - #customCommand: # Required when command == Custom - #arguments: # Optional - workingDirectory: -``` diff --git a/docs/pipelines/tasks/includes/yaml/GradleV2.md b/docs/pipelines/tasks/includes/yaml/GradleV2.md deleted file mode 100644 index 82b9d34626d..00000000000 --- a/docs/pipelines/tasks/includes/yaml/GradleV2.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/17/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Gradle -# Build using a Gradle wrapper script -- task: Gradle@2 - inputs: - #gradleWrapperFile: 'gradlew' - #cwd: # Optional - #options: # Optional - #tasks: 'build' # A list of tasks separated by spaces, such as 'build test' - #publishJUnitResults: true - #testResultsFiles: '**/TEST-*.xml' # Required when publishJUnitResults == True - #testRunTitle: # Optional - #codeCoverageToolOption: 'None' # Optional. Options: none, cobertura, jaCoCo - #codeCoverageClassFilesDirectories: 'build/classes/main/' # Required when codeCoverageToolOption == False - #codeCoverageClassFilter: # Optional. Comma-separated list of filters to include or exclude classes from collecting code coverage. For example: +:com.*,+:org.*,-:my.app*.* - #codeCoverageFailIfEmpty: false # Optional - #javaHomeOption: 'JDKVersion' # Options: jDKVersion, path - #jdkVersionOption: 'default' # Optional. Options: default, 1.11, 1.10, 1.9, 1.8, 1.7, 1.6 - #jdkDirectory: # Required when javaHomeOption == Path - #jdkArchitectureOption: 'x64' # Optional. Options: x86, x64 - #gradleOptions: '-Xmx1024m' # Optional - #sonarQubeRunAnalysis: false - #sqGradlePluginVersionChoice: 'specify' # Required when sonarQubeRunAnalysis == True# Options: specify, build - #sonarQubeGradlePluginVersion: '2.6.1' # Required when sonarQubeRunAnalysis == True && SqGradlePluginVersionChoice == Specify - #checkStyleRunAnalysis: false # Optional - #findBugsRunAnalysis: false # Optional - #pmdRunAnalysis: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/GruntV0.md b/docs/pipelines/tasks/includes/yaml/GruntV0.md deleted file mode 100644 index 447e37c1460..00000000000 --- a/docs/pipelines/tasks/includes/yaml/GruntV0.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 08/10/2016 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Grunt -# Run the Grunt JavaScript task runner -- task: Grunt@0 - inputs: - #gruntFile: 'gruntfile.js' - #targets: # Optional - #arguments: # Optional - #workingDirectory: # Optional - #gruntCli: 'node_modules/grunt-cli/bin/grunt' - #publishJUnitResults: false # Optional - #testResultsFiles: '**/TEST-*.xml' # Required when publishJUnitResults == True - #testRunTitle: # Optional - #enableCodeCoverage: false # Optional - #testFramework: 'Mocha' # Optional. Options: mocha, jasmine - #srcFiles: # Optional - #testFiles: 'test/*.js' # Required when enableCodeCoverage == True -``` diff --git a/docs/pipelines/tasks/includes/yaml/GulpV1.md b/docs/pipelines/tasks/includes/yaml/GulpV1.md deleted file mode 100644 index 843331f34ab..00000000000 --- a/docs/pipelines/tasks/includes/yaml/GulpV1.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/17/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# gulp -# Run the gulp Node.js streaming task-based build system -- task: gulp@1 - inputs: - #gulpFile: 'gulpfile.js' - #targets: # Optional - #arguments: # Optional - #workingDirectory: # Optional - #gulpjs: # Optional - #publishJUnitResults: false # Optional - #testResultsFiles: '**/TEST-*.xml' # Required when publishJUnitResults == True - #testRunTitle: # Optional - #enableCodeCoverage: false - #testFramework: 'Mocha' # Optional. Options: mocha, jasmine - #srcFiles: # Optional - #testFiles: 'test/*.js' # Required when enableCodeCoverage == True -``` diff --git a/docs/pipelines/tasks/includes/yaml/HelmInstallerV1.md b/docs/pipelines/tasks/includes/yaml/HelmInstallerV1.md deleted file mode 100644 index aee3b0a7ea4..00000000000 --- a/docs/pipelines/tasks/includes/yaml/HelmInstallerV1.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.topic: include -author: azooinmyluggage -ms.author: atulmal -ms.date: 02/28/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Helm tool installer -# Install Helm on an agent machine -- task: HelmInstaller@1 - inputs: - #helmVersionToInstall: 'latest' # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/IISWebAppDeploymentOnMachineGroupV0.md b/docs/pipelines/tasks/includes/yaml/IISWebAppDeploymentOnMachineGroupV0.md deleted file mode 100644 index 9363c612404..00000000000 --- a/docs/pipelines/tasks/includes/yaml/IISWebAppDeploymentOnMachineGroupV0.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# IIS web app deploy -# Deploy a website or web application using Web Deploy -- task: IISWebAppDeploymentOnMachineGroup@0 - inputs: - webSiteName: - #virtualApplication: # Optional - #package: '$(System.DefaultWorkingDirectory)\**\*.zip' - #setParametersFile: # Optional - #removeAdditionalFilesFlag: false # Optional - #excludeFilesFromAppDataFlag: false # Optional - #takeAppOfflineFlag: false # Optional - #additionalArguments: # Optional - #xmlTransformation: # Optional - #xmlVariableSubstitution: # Optional - #jSONFiles: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/IISWebAppManagementOnMachineGroupV0.md b/docs/pipelines/tasks/includes/yaml/IISWebAppManagementOnMachineGroupV0.md deleted file mode 100644 index 5998ec90028..00000000000 --- a/docs/pipelines/tasks/includes/yaml/IISWebAppManagementOnMachineGroupV0.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# IIS web app manage -# Create or update websites, web apps, virtual directories, or application pools -- task: IISWebAppManagementOnMachineGroup@0 - inputs: - #enableIIS: false # Optional - #iISDeploymentType: 'IISWebsite' # Options: iISWebsite, iISWebApplication, iISVirtualDirectory, iISApplicationPool - #actionIISWebsite: 'CreateOrUpdateWebsite' # Required when iISDeploymentType == IISWebsite# Options: createOrUpdateWebsite, startWebsite, stopWebsite - #actionIISApplicationPool: 'CreateOrUpdateAppPool' # Required when iISDeploymentType == IISApplicationPool# Options: createOrUpdateAppPool, startAppPool, stopAppPool, recycleAppPool - #startStopWebsiteName: # Required when actionIISWebsite == StartWebsite || ActionIISWebsite == StopWebsite - websiteName: - #websitePhysicalPath: '%SystemDrive%\inetpub\wwwroot' - #websitePhysicalPathAuth: 'WebsiteUserPassThrough' # Options: websiteUserPassThrough, websiteWindowsAuth - #websiteAuthUserName: # Required when websitePhysicalPathAuth == WebsiteWindowsAuth - #websiteAuthUserPassword: # Optional - #addBinding: false # Optional - #protocol: 'http' # Required when iISDeploymentType == RandomDeployment# Options: https, http - #iPAddress: 'All Unassigned' # Required when iISDeploymentType == RandomDeployment - #port: '80' # Required when iISDeploymentType == RandomDeployment - #serverNameIndication: false # Optional - #hostNameWithOutSNI: # Optional - #hostNameWithHttp: # Optional - #hostNameWithSNI: # Required when iISDeploymentType == RandomDeployment - #sSLCertThumbPrint: # Required when iISDeploymentType == RandomDeployment - bindings: - #createOrUpdateAppPoolForWebsite: false # Optional - #configureAuthenticationForWebsite: false # Optional - appPoolNameForWebsite: - #dotNetVersionForWebsite: 'v4.0' # Options: v4.0, v2.0, no Managed Code - #pipeLineModeForWebsite: 'Integrated' # Options: integrated, classic - #appPoolIdentityForWebsite: 'ApplicationPoolIdentity' # Options: ApplicationPoolIdentity, LocalService, LocalSystem, NetworkService, SpecificUser - #appPoolUsernameForWebsite: # Required when appPoolIdentityForWebsite == SpecificUser - #appPoolPasswordForWebsite: # Optional - #anonymousAuthenticationForWebsite: false # Optional - #basicAuthenticationForWebsite: false # Optional - #windowsAuthenticationForWebsite: true # Optional - parentWebsiteNameForVD: - virtualPathForVD: - #physicalPathForVD: '%SystemDrive%\inetpub\wwwroot' - #vDPhysicalPathAuth: 'VDUserPassThrough' # Optional. Options: vDUserPassThrough, vDWindowsAuth - #vDAuthUserName: # Required when vDPhysicalPathAuth == VDWindowsAuth - #vDAuthUserPassword: # Optional - parentWebsiteNameForApplication: - virtualPathForApplication: - #physicalPathForApplication: '%SystemDrive%\inetpub\wwwroot' - #applicationPhysicalPathAuth: 'ApplicationUserPassThrough' # Optional. Options: applicationUserPassThrough, applicationWindowsAuth - #applicationAuthUserName: # Required when applicationPhysicalPathAuth == ApplicationWindowsAuth - #applicationAuthUserPassword: # Optional - #createOrUpdateAppPoolForApplication: false # Optional - appPoolNameForApplication: - #dotNetVersionForApplication: 'v4.0' # Options: v4.0, v2.0, no Managed Code - #pipeLineModeForApplication: 'Integrated' # Options: integrated, classic - #appPoolIdentityForApplication: 'ApplicationPoolIdentity' # Options: applicationPoolIdentity, localService, localSystem, networkService, specificUser - #appPoolUsernameForApplication: # Required when appPoolIdentityForApplication == SpecificUser - #appPoolPasswordForApplication: # Optional - appPoolName: - #dotNetVersion: 'v4.0' # Options: v4.0, v2.0, no Managed Code - #pipeLineMode: 'Integrated' # Options: integrated, classic - #appPoolIdentity: 'ApplicationPoolIdentity' # Options: applicationPoolIdentity, localService, localSystem, networkService, specificUser - #appPoolUsername: # Required when appPoolIdentity == SpecificUser - #appPoolPassword: # Optional - #startStopRecycleAppPoolName: # Required when actionIISApplicationPool == StartAppPool || ActionIISApplicationPool == StopAppPool || ActionIISApplicationPool == RecycleAppPool - #appCmdCommands: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/InstallAppleCertificateV2.md b/docs/pipelines/tasks/includes/yaml/InstallAppleCertificateV2.md deleted file mode 100644 index ec0f056d760..00000000000 --- a/docs/pipelines/tasks/includes/yaml/InstallAppleCertificateV2.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Install Apple certificate -# Install an Apple certificate required to build on a macOS agent machine -- task: InstallAppleCertificate@2 - inputs: - certSecureFile: - #certPwd: # Optional - #keychain: 'temp' # Options: default, temp, custom - #keychainPassword: # Required when keychain == Custom || Keychain == Default - #customKeychainPath: # Required when keychain == Custom - #deleteCert: # Optional - #deleteCustomKeychain: # Optional - #signingIdentity: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/InstallAppleProvisioningProfileV1.md b/docs/pipelines/tasks/includes/yaml/InstallAppleProvisioningProfileV1.md deleted file mode 100644 index f5dedcdfb54..00000000000 --- a/docs/pipelines/tasks/includes/yaml/InstallAppleProvisioningProfileV1.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Install Apple provisioning profile -# Install an Apple provisioning profile required to build on a macOS agent machine -- task: InstallAppleProvisioningProfile@1 - inputs: - #provisioningProfileLocation: 'secureFiles' # Options: secureFiles, sourceRepository - #provProfileSecureFile: # Required when provisioningProfileLocation == SecureFiles - #provProfileSourceRepository: # Required when provisioningProfileLocation == SourceRepository - #removeProfile: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/InstallSSHKeyV0.md b/docs/pipelines/tasks/includes/yaml/InstallSSHKeyV0.md deleted file mode 100644 index c0da0a41988..00000000000 --- a/docs/pipelines/tasks/includes/yaml/InstallSSHKeyV0.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 02/02/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Install SSH key -# Install an SSH key prior to a build or deployment -- task: InstallSSHKey@0 - inputs: - knownHostsEntry: - sshPublicKey: - #sshPassphrase: # Optional - sshKeySecureFile: - #addEntryToConfig: # Optional - #configHostAlias: # Optional - #configHostname: # Optional - #configUser: # Optional - #configPort: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/InvokeRestApiV1.md b/docs/pipelines/tasks/includes/yaml/InvokeRestApiV1.md deleted file mode 100644 index dcb30cadf5e..00000000000 --- a/docs/pipelines/tasks/includes/yaml/InvokeRestApiV1.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 01/10/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Invoke REST API -# Invoke a REST API as a part of your pipeline. -- task: InvokeRESTAPI@1 - inputs: - #connectionType: 'connectedServiceName' # Options: connectedServiceName, connectedServiceNameARM - #serviceConnection: # Required when connectionType == ConnectedServiceName - #azureServiceConnection: # Required when connectionType == ConnectedServiceNameARM - #method: 'POST' # Options: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, PATCH - #headers: '{Content-Type:application/json, PlanUrl: $(system.CollectionUri), ProjectId: $(system.TeamProjectId), HubName: $(system.HostType), PlanId: $(system.PlanId), JobId: $(system.JobId), TimelineId: $(system.TimelineId), TaskInstanceId: $(system.TaskInstanceId), AuthToken: $(system.AccessToken)}' - #body: # Required when method != GET && Method != HEAD - #urlSuffix: # Optional - #waitForCompletion: 'false' # Options: true, false - #successCriteria: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/JavaToolInstallerV0.md b/docs/pipelines/tasks/includes/yaml/JavaToolInstallerV0.md deleted file mode 100644 index ad6bd877084..00000000000 --- a/docs/pipelines/tasks/includes/yaml/JavaToolInstallerV0.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Java tool installer -# Acquire a specific version of Java from a user-supplied Azure blob or the tool cache and sets JAVA_HOME -- task: JavaToolInstaller@0 - inputs: - #versionSpec: '8' - jdkArchitectureOption: # Options: x64, x86 - jdkSourceOption: # Options: AzureStorage, LocalDirectory - #jdkFile: # Required when jdkSourceOption == LocalDirectory - #azureResourceManagerEndpoint: # Required when jdkSourceOption == AzureStorage - #azureStorageAccountName: # Required when jdkSourceOption == AzureStorage - #azureContainerName: # Required when jdkSourceOption == AzureStorage - #azureCommonVirtualFile: # Required when jdkSourceOption == AzureStorage - jdkDestinationDirectory: - #cleanDestinationDirectory: true -``` diff --git a/docs/pipelines/tasks/includes/yaml/JenkinsDownloadArtifactsV1.md b/docs/pipelines/tasks/includes/yaml/JenkinsDownloadArtifactsV1.md deleted file mode 100644 index 2e0a2a5a253..00000000000 --- a/docs/pipelines/tasks/includes/yaml/JenkinsDownloadArtifactsV1.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Jenkins download artifacts -# Download artifacts produced by a Jenkins job -- task: JenkinsDownloadArtifacts@1 - inputs: - jenkinsServerConnection: - jobName: - #jenkinsJobType: # Optional - #saveTo: 'jenkinsArtifacts' - #jenkinsBuild: 'LastSuccessfulBuild' # Options: lastSuccessfulBuild, buildNumber - #jenkinsBuildNumber: '1' # Required when jenkinsBuild == BuildNumber - #itemPattern: '**' # Optional - #downloadCommitsAndWorkItems: # Optional - #startJenkinsBuildNumber: # Optional - #artifactDetailsFileNameSuffix: # Optional - #propagatedArtifacts: false # Optional - #artifactProvider: 'azureStorage' # Required when propagatedArtifacts == NotValid# Options: azureStorage - #connectedServiceNameARM: # Required when propagatedArtifacts == True - #storageAccountName: # Required when propagatedArtifacts == True - #containerName: # Required when propagatedArtifacts == True - #commonVirtualPath: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/JenkinsQueueJobV2.md b/docs/pipelines/tasks/includes/yaml/JenkinsQueueJobV2.md deleted file mode 100644 index c2bfd37d590..00000000000 --- a/docs/pipelines/tasks/includes/yaml/JenkinsQueueJobV2.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/17/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Jenkins queue job -# Queue a job on a Jenkins server -- task: JenkinsQueueJob@2 - inputs: - serverEndpoint: - jobName: - #isMultibranchJob: # Optional - #multibranchPipelineBranch: # Required when isMultibranchJob == True - #captureConsole: true - #capturePipeline: true # Required when captureConsole == True - isParameterizedJob: - #jobParameters: # Optional - #retryCount: #Optional - #delayBetweenRetries: #Optional - #failOnUnstableResult: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/KubectlInstallerV0.md b/docs/pipelines/tasks/includes/yaml/KubectlInstallerV0.md deleted file mode 100644 index edebdafb0fb..00000000000 --- a/docs/pipelines/tasks/includes/yaml/KubectlInstallerV0.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.topic: include -author: azooinmyluggage -ms.author: atulmal -ms.date: 04/17/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Kubectl tool installer -# Install Kubectl on agent machine -- task: KubectlInstaller@0 - inputs: - #kubectlVersion: 'latest' # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/MSBuildV1.md b/docs/pipelines/tasks/includes/yaml/MSBuildV1.md deleted file mode 100644 index 0c164862ed4..00000000000 --- a/docs/pipelines/tasks/includes/yaml/MSBuildV1.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 02/24/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# MSBuild -# Build with MSBuild -- task: MSBuild@1 - inputs: - #solution: '**/*.sln' - #msbuildLocationMethod: 'version' # Optional. Options: version, location - #msbuildVersion: 'latest' # Optional. Options: latest, 16.0, 15.0, 14.0, 12.0, 4.0 - #msbuildArchitecture: 'x86' # Optional. Options: x86, x64 - #msbuildLocation: # Optional - #platform: # Optional - #configuration: # Optional - #msbuildArguments: # Optional - #clean: false # Optional - #maximumCpuCount: false # Optional - #restoreNugetPackages: false # Optional - #logProjectEvents: false # Optional - #createLogFile: false # Optional - #logFileVerbosity: 'normal' # Optional. Options: quiet, minimal, normal, detailed, diagnostic -``` diff --git a/docs/pipelines/tasks/includes/yaml/MavenAuthenticateV0.md b/docs/pipelines/tasks/includes/yaml/MavenAuthenticateV0.md deleted file mode 100644 index 1d4064a8fbc..00000000000 --- a/docs/pipelines/tasks/includes/yaml/MavenAuthenticateV0.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.topic: include -ms.date: 08/06/2019 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -```yaml -# Provides credentials for Azure Artifacts feeds and external Maven repositories. -- task: MavenAuthenticate@0 - #inputs: - #artifactsFeeds: MyFeedInOrg1, MyFeedInOrg2 # Optional - #mavenServiceConnections: serviceConnection1, serviceConnection2 # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/MavenV4.md b/docs/pipelines/tasks/includes/yaml/MavenV4.md deleted file mode 100644 index 2605f16e950..00000000000 --- a/docs/pipelines/tasks/includes/yaml/MavenV4.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 10/03/2022 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Maven -# Build, test, and deploy with Apache Maven -- task: Maven@4 - inputs: - #mavenPomFile: 'pom.xml' - #goals: 'package' # Optional - #options: # Optional - #publishJUnitResults: true - #testResultsFiles: '**/surefire-reports/TEST-*.xml' # Required when publishJUnitResults == True - #testRunTitle: # Optional - #allowBrokenSymlinks: false # Optional. Has effect only when publishJUnitResults == True - #codeCoverageToolOption: 'None' # Optional. Options: none, cobertura, jaCoCo. Enabling code coverage inserts the `clean` goal into the Maven goals list when Maven runs. - #codeCoverageClassFilter: # Optional. Comma-separated list of filters to include or exclude classes from collecting code coverage. For example: +:com.*,+:org.*,-:my.app*.* - #codeCoverageClassFilesDirectories: # Optional | Required for a multi-module project - #codeCoverageSourceDirectories: # Optional | Required for a multi-module project - #codeCoverageFailIfEmpty: false # Optional - #codeCoverageRestoreOriginalPomXml: false # Optional - #javaHomeOption: 'JDKVersion' # Options: jDKVersion, path - #jdkVersionOption: 'default' # Optional. Options: default, 1.14, 1.13, 1.12, 1.11, 1.10, 1.9, 1.8, 1.7, 1.6 - #jdkDirectory: # Required when javaHomeOption == Path - #jdkArchitectureOption: 'x64' # Optional. Options: x86, x64 - #mavenVersionOption: 'Default' # Options: default, path - #mavenDirectory: # Required when mavenVersionOption == Path - #mavenSetM2Home: false # Required when mavenVersionOption == Path - #mavenOptions: '-Xmx1024m' # Optional - #mavenAuthenticateFeed: false - #effectivePomSkip: false - #sonarQubeRunAnalysis: false - #isJacocoCoverageReportXML: false # Optional - #sqMavenPluginVersionChoice: 'latest' # Required when sonarQubeRunAnalysis == True# Options: latest, pom - #checkStyleRunAnalysis: false # Optional - #pmdRunAnalysis: false # Optional - #findBugsRunAnalysis: false # Optional - #spotBugsRunAnalysis: false # Optional - #spotBugsVersion: 4.5.3.0 # Optional - #spotBugsGoal: spotbugs # Optional - #sbFailWhenBugsFound: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/NodeToolV0.md b/docs/pipelines/tasks/includes/yaml/NodeToolV0.md deleted file mode 100644 index 65235dbd505..00000000000 --- a/docs/pipelines/tasks/includes/yaml/NodeToolV0.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Node.js tool installer -# Finds or downloads and caches the specified version spec of Node.js and adds it to the PATH -- task: NodeTool@0 - inputs: - #versionSpec: '6.x' - #force32bit: false # Optional - #checkLatest: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/NpmAuthenticateV0.md b/docs/pipelines/tasks/includes/yaml/NpmAuthenticateV0.md deleted file mode 100644 index 258939568b9..00000000000 --- a/docs/pipelines/tasks/includes/yaml/NpmAuthenticateV0.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 05/04/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# npm authenticate -# Don't use this task if you're also using the npm task. Provides npm credentials to an .npmrc file in your repository for the scope of the build. This enables npm and npm task runners like gulp and Grunt to authenticate with private registries. -- task: npmAuthenticate@0 - inputs: - #workingFile: - #customEndpoint: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/NpmV1.md b/docs/pipelines/tasks/includes/yaml/NpmV1.md deleted file mode 100644 index b47ae839b86..00000000000 --- a/docs/pipelines/tasks/includes/yaml/NpmV1.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 02/24/2022 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# npm v1 -# Install and publish npm packages, or run an npm command. Supports npmjs.com and authenticated registries like Azure Artifacts. -- task: Npm@1 - inputs: - command: ci | install | publish | custom # Required. Command. Default: install - workingDir: string # Working folder that contains package.json. - customCommand: string # Required when command = custom. Command and arguments. - # Advanced - verbose: boolean # Verbose logging. - publishPackageMetadata: boolean # Optional. Use when command = publish && publishRegistry = useFeed. Publish pipeline metadata. Default: True - # Custom registries and authentication - customRegistry: useNpmrc | useFeed # Registries to use. Default: useNpmrc - customFeed: string # Required when customRegistry = useFeed. Use packages from this Azure Artifacts/TFS registry. - customEndpoint: string # Optional. Use when customRegistry = useNpmrc. Credentials for registries outside this organization/collection. - # Destination registry and authentication - publishRegistry: useExternalRegistry | useFeed # Registry location. Default: useExternalRegistry - publishFeed: string # Required when publishRegistry = useFeed. Target registry. - publishEndpoint: string # Required when publishRegistry = useExternalRegistry. External Registry. -``` diff --git a/docs/pipelines/tasks/includes/yaml/NuGetAuthenticateV1.md b/docs/pipelines/tasks/includes/yaml/NuGetAuthenticateV1.md deleted file mode 100644 index 740128b516e..00000000000 --- a/docs/pipelines/tasks/includes/yaml/NuGetAuthenticateV1.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.topic: include -ms.date: 08/27/2019 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Authenticate nuget.exe, dotnet, and MSBuild with Azure Artifacts and optionally other repositories -- task: NuGetAuthenticate@1 - #inputs: - #nuGetServiceConnections: MyOtherOrganizationFeed, MyExternalPackageRepository # Optional - #forceReinstallCredentialProvider: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/NuGetCommandV2.md b/docs/pipelines/tasks/includes/yaml/NuGetCommandV2.md deleted file mode 100644 index d9dc06f6100..00000000000 --- a/docs/pipelines/tasks/includes/yaml/NuGetCommandV2.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -ms.topic: include -ms.date: 09/10/2019 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# NuGet -# Restore, pack, or push NuGet packages, or run a NuGet command. Supports NuGet.org and authenticated feeds like Azure Artifacts and MyGet. Uses NuGet.exe and works with .NET Framework apps. For .NET Core and .NET Standard apps, use the .NET Core task. -- task: NuGetCommand@2 - inputs: - #command: 'restore' # Options: restore, pack, push, custom - #restoreSolution: '**/*.sln' # Required when command == Restore - #feedsToUse: 'select' # Options: select, config - #vstsFeed: # Required when feedsToUse == Select - #includeNuGetOrg: true # Required when feedsToUse == Select - #nugetConfigPath: # Required when feedsToUse == Config - #externalFeedCredentials: # Optional - #noCache: false - #disableParallelProcessing: false - restoreDirectory: - #verbosityRestore: 'Detailed' # Options: quiet, normal, detailed - #packagesToPush: '$(Build.ArtifactStagingDirectory)/**/*.nupkg;!$(Build.ArtifactStagingDirectory)/**/*.symbols.nupkg' # Required when command == Push - #nuGetFeedType: 'internal' # Required when command == Push# Options: internal, external - #publishVstsFeed: # Required when command == Push && NuGetFeedType == Internal - #publishPackageMetadata: true # Optional - #allowPackageConflicts: # Optional - #publishFeedCredentials: # Required when command == Push && NuGetFeedType == External - #verbosityPush: 'Detailed' # Options: quiet, normal, detailed - #packagesToPack: '**/*.csproj' # Required when command == Pack - #configuration: '$(BuildConfiguration)' # Optional - #packDestination: '$(Build.ArtifactStagingDirectory)' # Optional - #versioningScheme: 'off' # Options: off, byPrereleaseNumber, byEnvVar, byBuildNumber - #includeReferencedProjects: false # Optional - #versionEnvVar: # Required when versioningScheme == ByEnvVar - #majorVersion: '1' # Required when versioningScheme == ByPrereleaseNumber - #minorVersion: '0' # Required when versioningScheme == ByPrereleaseNumber - #patchVersion: '0' # Required when versioningScheme == ByPrereleaseNumber - #packTimezone: 'utc' # Required when versioningScheme == ByPrereleaseNumber# Options: utc, local - #includeSymbols: false # Optional - #toolPackage: # Optional - #buildProperties: # Optional - #basePath: # Optional, specify path to nuspec files - #verbosityPack: 'Detailed' # Options: quiet, normal, detailed - #arguments: # Required when command == Custom -``` diff --git a/docs/pipelines/tasks/includes/yaml/NuGetPackagerV0.md b/docs/pipelines/tasks/includes/yaml/NuGetPackagerV0.md deleted file mode 100644 index 2f33c534b96..00000000000 --- a/docs/pipelines/tasks/includes/yaml/NuGetPackagerV0.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -ms.topic: include -ms.date: 08/10/2016 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# NuGet packager -# Deprecated: use the “NuGet” task instead. It works with the new Tool Installer framework so you can easily use new versions of NuGet without waiting for a task update, provides better support for authenticated feeds outside this organization/collection, and uses NuGet 4 by default. -- task: NuGetPackager@0 - inputs: - #searchPattern: '**\*.csproj' - #outputdir: # Optional - #includeReferencedProjects: false # Optional - #versionByBuild: 'false' # Options: false, byPrereleaseNumber, byEnvVar, true - #versionEnvVar: # Required when versionByBuild == ByEnvVar - #requestedMajorVersion: '1' # Required when versionByBuild == ByPrereleaseNumber - #requestedMinorVersion: '0' # Required when versionByBuild == ByPrereleaseNumber - #requestedPatchVersion: '0' # Required when versionByBuild == ByPrereleaseNumber - #configurationToPack: '$(BuildConfiguration)' # Optional - #buildProperties: # Optional - #nuGetAdditionalArgs: # Optional - #nuGetPath: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/NuGetPublisherV0.md b/docs/pipelines/tasks/includes/yaml/NuGetPublisherV0.md deleted file mode 100644 index 7d3315f92ab..00000000000 --- a/docs/pipelines/tasks/includes/yaml/NuGetPublisherV0.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -ms.topic: include -ms.date: 08/10/2016 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# NuGet publisher -# Deprecated: use the “NuGet” task instead. It works with the new Tool Installer framework so you can easily use new versions of NuGet without waiting for a task update, provides better support for authenticated feeds outside this organization/collection, and uses NuGet 4 by default. -- task: NuGetPublisher@0 - inputs: - #searchPattern: '**/*.nupkg;-:**/packages/**/*.nupkg;-:**/*.symbols.nupkg' - #nuGetFeedType: 'external' # Options: external, internal - #connectedServiceName: # Required when nuGetFeedType == External - #feedName: # Required when nuGetFeedType == Internal - #nuGetAdditionalArgs: # Optional - #verbosity: '-' # Options: -, quiet, normal, detailed - #nuGetVersion: '3.3.0' # Options: 3.3.0, 3.5.0.1829, 4.0.0.2283, custom - #nuGetPath: # Optional - #continueOnEmptyNupkgMatch: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/NuGetToolInstallerV1.md b/docs/pipelines/tasks/includes/yaml/NuGetToolInstallerV1.md deleted file mode 100644 index 2effcf9e796..00000000000 --- a/docs/pipelines/tasks/includes/yaml/NuGetToolInstallerV1.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -ms.topic: include -ms.date: 12/10/2019 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# NuGet tool installer -# Acquires a specific version of NuGet from the internet or the tools cache and adds it to the PATH. Use this task to change the version of NuGet used in the NuGet tasks. -- task: NuGetToolInstaller@1 - inputs: - #versionSpec: # Optional - #checkLatest: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PackerBuildV1.md b/docs/pipelines/tasks/includes/yaml/PackerBuildV1.md deleted file mode 100644 index 74580bbf9bd..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PackerBuildV1.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Build machine image -# Build a machine image using Packer, which may be used for Azure Virtual machine scale set deployment -- task: PackerBuild@1 - inputs: - #templateType: 'builtin' # Options: builtin, custom - #customTemplateLocation: # Required when templateType == Custom - #customTemplateParameters: '{}' # Optional - connectedServiceName: - #isManagedImage: true - #managedImageName: # Required when isManagedImage == True - location: - storageAccountName: - azureResourceGroup: - #baseImageSource: 'default' # Options: default, customVhd - #baseImage: 'MicrosoftWindowsServer:WindowsServer:2012-R2-Datacenter:windows' # Required when baseImageSource == Default# Options: microsoftWindowsServer:WindowsServer:2012-R2-Datacenter:Windows, microsoftWindowsServer:WindowsServer:2016-Datacenter:Windows, microsoftWindowsServer:WindowsServer:2012-Datacenter:Windows, microsoftWindowsServer:WindowsServer:2008-R2-SP1:Windows, canonical:UbuntuServer:14.04.4-LTS:Linux, canonical:UbuntuServer:16.04-LTS:Linux, redHat:RHEL:7.2:Linux, redHat:RHEL:6.8:Linux, openLogic:CentOS:7.2:Linux, openLogic:CentOS:6.8:Linux, credativ:Debian:8:Linux, credativ:Debian:7:Linux, sUSE:OpenSUSE-Leap:42.2:Linux, sUSE:SLES:12-SP2:Linux, sUSE:SLES:11-SP4:Linux - #customImageUrl: # Required when baseImageSource == CustomVhd - #customImageOSType: 'windows' # Required when baseImageSource == CustomVhd# Options: windows, linux - packagePath: - deployScriptPath: - #deployScriptArguments: # Optional - #additionalBuilderParameters: '{vm_size:Standard_D3_v2}' # Optional - #skipTempFileCleanupDuringVMDeprovision: true # Optional - #packerVersion: # Optional - #imageUri: # Optional - #imageId: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PipAuthenticateV0.md b/docs/pipelines/tasks/includes/yaml/PipAuthenticateV0.md deleted file mode 100644 index febc70241f5..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PipAuthenticateV0.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -ms.topic: include -author: davidstaheli -ms.author: dastahel -ms.date: 10/31/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Python pip authenticate -# Authentication task for the pip client used for installing Python distributions -- task: PipAuthenticate@0 - inputs: - artifactFeeds: - #externalFeeds: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PipAuthenticateV1.md b/docs/pipelines/tasks/includes/yaml/PipAuthenticateV1.md deleted file mode 100644 index 2f9a8c6a033..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PipAuthenticateV1.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -ms.date: 08/02/2019 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Python pip authenticate V1 -# Authentication task for the pip client used for installing Python distributions -- task: PipAuthenticate@1 - inputs: - #artifactFeeds: 'MyFeed, MyTestFeed' # Optional - #pythonDownloadServiceConnections: pypiOrgFeed, OtherOrganizationFeed # Optional - #onlyAddExtraIndex: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PowerShellOnTargetMachinesV3.md b/docs/pipelines/tasks/includes/yaml/PowerShellOnTargetMachinesV3.md deleted file mode 100644 index c10affa2ace..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PowerShellOnTargetMachinesV3.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# PowerShell on target machines -# Execute PowerShell scripts on remote machines using PSSession and Invoke-Command for remoting -- task: PowerShellOnTargetMachines@3 - inputs: - machines: - #userName: # Optional - #userPassword: # Optional - #scriptType: 'Inline' # Optional. Options: filePath, inline - #scriptPath: # Required when scriptType == FilePath - #inlineScript: '# Write your powershell commands here.Write-Output Hello World' # Required when scriptType == Inline - #scriptArguments: # Optional - #initializationScript: # Optional - #sessionVariables: # Optional - #communicationProtocol: 'Https' # Optional. Options: http, https - #authenticationMechanism: 'Default' # Optional. Options: default, credssp - #newPsSessionOptionArguments: '-SkipCACheck -IdleTimeout 7200000 -OperationTimeout 0 -OutputBufferingMode Block' # Optional - #errorActionPreference: 'stop' # Optional. Options: stop, continue, silentlyContinue - #failOnStderr: false # Optional - #ignoreLASTEXITCODE: false # Optional - #workingDirectory: # Optional - #runPowershellInParallel: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PowerShellV2.md b/docs/pipelines/tasks/includes/yaml/PowerShellV2.md deleted file mode 100644 index 7a6b2980869..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PowerShellV2.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -ms.topic: include -ms.date: 02/18/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# PowerShell -# Run a PowerShell script on Linux, macOS, or Windows -- task: PowerShell@2 - inputs: - #targetType: 'filePath' # Optional. Options: filePath, inline - #filePath: # Required when targetType == FilePath - #arguments: # Optional - #script: '# Write your PowerShell commands here.Write-Host Hello World' # Required when targetType == Inline - #errorActionPreference: 'stop' # Optional. Options: default, stop, continue, silentlyContinue - #warningPreference: 'default' # Optional. Options: default, stop, continue, silentlyContinue - #informationPreference: 'default' # Optional. Options: default, stop, continue, silentlyContinue - #verbosePreference: 'default' # Optional. Options: default, stop, continue, silentlyContinue - #debugPreference: 'default' # Optional. Options: default, stop, continue, silentlyContinue - #failOnStderr: false # Optional - #ignoreLASTEXITCODE: false # Optional - #pwsh: false # Optional - #workingDirectory: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PublishBuildArtifactsV1.md b/docs/pipelines/tasks/includes/yaml/PublishBuildArtifactsV1.md deleted file mode 100644 index b6fd6e8e7b5..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PublishBuildArtifactsV1.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Publish build artifacts -# Publish build artifacts to Azure Pipelines or a Windows file share -- task: PublishBuildArtifacts@1 - inputs: - #pathToPublish: '$(Build.ArtifactStagingDirectory)' - #artifactName: 'drop' - #publishLocation: 'Container' # Options: container, filePath - #targetPath: # Required when publishLocation == FilePath - #parallel: false # Optional - #parallelCount: # Optional - #fileCopyOptions: #Optional - #storeAsTar: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PublishCodeCoverageResultsV1.md b/docs/pipelines/tasks/includes/yaml/PublishCodeCoverageResultsV1.md deleted file mode 100644 index 9261c745f73..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PublishCodeCoverageResultsV1.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Publish code coverage results -# Publish Cobertura or JaCoCo code coverage results from a build -- task: PublishCodeCoverageResults@1 - inputs: - codeCoverageTool: 'JaCoCo' # Available options: 'JaCoCo', 'Cobertura' - summaryFileLocation: - #pathToSources: # Optional - #reportDirectory: # Optional - #additionalCodeCoverageFiles: # Optional - #failIfCoverageEmpty: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PublishPipelineArtifactV1.md b/docs/pipelines/tasks/includes/yaml/PublishPipelineArtifactV1.md deleted file mode 100644 index 7958edf6ef3..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PublishPipelineArtifactV1.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 08/12/2022 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Publish pipeline artifacts -# Publish (upload) a file or directory as a named artifact for the current run -- task: PublishPipelineArtifact@1 - inputs: - #path: '$(Pipeline.Workspace)' # Required. Default value: $(Pipeline.Workspace). Aliases: targetPath. - #artifactName: 'drop' # Optional. Aliases: artifact. - #artifactType: 'pipeline' # Required. Options: pipeline, filepath. Default value: pipeline. Aliases: publishLocation. - #fileSharePath: '\server\folderName' # Required when artifactType = filepath. - #parallel: false # Optional. Default value: false. - #parallelCount: 1 # Optional. Value must be at least 1 and not greater than 128. Default value: 8 - #properties: # Optional. Custom properties to associate with the published artifact. Must be a valid json string. -``` diff --git a/docs/pipelines/tasks/includes/yaml/PublishSymbolsV2.md b/docs/pipelines/tasks/includes/yaml/PublishSymbolsV2.md deleted file mode 100644 index 81534dacf03..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PublishSymbolsV2.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 06/17/2022 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Index sources and publish symbols -# Index your source code and publish symbols to a file share or Azure Artifacts symbol server -- task: PublishSymbols@2 - inputs: - #symbolsFolder: '$(Build.SourcesDirectory)' # Optional - #searchPattern: '**/bin/**/*.pdb' - #indexSources: true # Optional - #publishSymbols: true # Optional - #symbolServerType: ' ' # Required when publishSymbols == True # Options: , teamServices, fileShare - #symbolsPath: The file share that hosts your symbols. # Optional - #compressSymbols: false # Required when symbolServerType == FileShare - #SymbolExpirationInDays: The number of days that symbols should be retained. # Required when PublishSymbols = true && SymbolServerType = TeamServices. Default: 36530 - #IndexableFileFormats: Which debug formats to publish to the symbol server. # Options: Default, Pdb, SourceMap, All. # Required when PublishSymbols = true && SymbolServerType = TeamServices. Default: Default - #detailedLog: true # Optional - #treatNotIndexedAsWarning: false # Optional - #useNetCoreClientTool: false # Optional - #symbolsMaximumWaitTime: # Optional - #symbolsProduct: # Optional - #symbolsVersion: # Optional - #symbolsArtifactName: 'Symbols_$(BuildConfiguration)' # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PublishTestResultsV2.md b/docs/pipelines/tasks/includes/yaml/PublishTestResultsV2.md deleted file mode 100644 index e6bcd257f8d..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PublishTestResultsV2.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 06/27/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Publish Test Results -# Publish test results to Azure Pipelines -- task: PublishTestResults@2 - inputs: - #testResultsFormat: 'JUnit' # Options: JUnit, NUnit, VSTest, xUnit, cTest - #testResultsFiles: '**/TEST-*.xml' - #searchFolder: '$(System.DefaultWorkingDirectory)' # Optional - #mergeTestResults: false # Optional - #failTaskOnFailedTests: false # Optional - #testRunTitle: # Optional - #buildPlatform: # Optional - #buildConfiguration: # Optional - #publishRunAttachments: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PublishToAzureServiceBusV1.md b/docs/pipelines/tasks/includes/yaml/PublishToAzureServiceBusV1.md deleted file mode 100644 index dcba51c4ff0..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PublishToAzureServiceBusV1.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Publish To Azure Service Bus -# Sends a message to Azure Service Bus using a service connection (no agent is required) -- task: PublishToAzureServiceBus@1 - inputs: - azureSubscription: - #messageBody: # Optional - #sessionId: # Optional - #signPayload: false - #certificateString: # Required when signPayload == True - #signatureKey: 'signature' # Optional - #waitForCompletion: false -``` diff --git a/docs/pipelines/tasks/includes/yaml/PyPIPublisherV0.md b/docs/pipelines/tasks/includes/yaml/PyPIPublisherV0.md deleted file mode 100644 index fedeaa960c7..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PyPIPublisherV0.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.topic: include -ms.date: 5/7/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# PyPI publisher -# Create and upload an sdist or wheel to a PyPI-compatible index using Twine -- task: PyPIPublisher@0 - inputs: - pypiConnection: - packageDirectory: - #alsoPublishWheel: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/PythonScriptV0.md b/docs/pipelines/tasks/includes/yaml/PythonScriptV0.md deleted file mode 100644 index 68903295822..00000000000 --- a/docs/pipelines/tasks/includes/yaml/PythonScriptV0.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -ms.topic: include -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Python script -# Run a Python file or inline script -- task: PythonScript@0 - inputs: - #scriptSource: 'filePath' # Options: filePath, inline - #scriptPath: # Required when scriptSource == filePath - #script: # Required when scriptSource == inline - #arguments: # Optional - #pythonInterpreter: # Optional - #workingDirectory: # Optional - #failOnStderr: false # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/QueryWorkItemsV0.md b/docs/pipelines/tasks/includes/yaml/QueryWorkItemsV0.md deleted file mode 100644 index b87b61f5bd0..00000000000 --- a/docs/pipelines/tasks/includes/yaml/QueryWorkItemsV0.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Query work items -# Execute a work item query and check the number of items returned -- task: queryWorkItems@0 - inputs: - queryId: - #maxThreshold: '0' - #minThreshold: '0' -``` diff --git a/docs/pipelines/tasks/includes/yaml/QuickPerfTestV1.md b/docs/pipelines/tasks/includes/yaml/QuickPerfTestV1.md deleted file mode 100644 index 555973082ec..00000000000 --- a/docs/pipelines/tasks/includes/yaml/QuickPerfTestV1.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Cloud-based web performance test -# Run a quick web performance test in the cloud with Azure Pipelines -- task: QuickPerfTest@1 - inputs: - #connectedServiceName: # Optional - websiteUrl: - testName: - #vuLoad: '25' # Options: 25, 50, 100, 250 - #runDuration: '60' # Options: 60, 120, 180, 240, 300 - #geoLocation: 'Default' # Optional. Options: default, australia East, australia Southeast, brazil South, central India, central US, east Asia, east US 2, east US, japan East, japan West, north Central US, north Europe, south Central US, south India, southeast Asia, west Europe, west US - #machineType: '0' # Options: 0, 2 - #resourceGroupName: 'default' # Optional - #numOfSelfProvisionedAgents: # Optional - #avgResponseTimeThreshold: '0' # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/RunDistributedTestsV1.md b/docs/pipelines/tasks/includes/yaml/RunDistributedTestsV1.md deleted file mode 100644 index b30b75a93b7..00000000000 --- a/docs/pipelines/tasks/includes/yaml/RunDistributedTestsV1.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Run functional tests -# Deprecated: This task and its companion task (Visual Studio Test Agent Deployment) are deprecated. Use the 'Visual Studio Test' task instead. The VSTest task can run unit as well as functional tests. Run tests on one or more agents using the multi-agent job setting. Use the 'Visual Studio Test Platform' task to run tests without needing Visual Studio on the agent. VSTest task also brings new capabilities such as automatically rerunning failed tests. -- task: RunVisualStudioTestsusingTestAgent@1 - inputs: - testMachineGroup: - dropLocation: - #testSelection: 'testAssembly' # Options: testAssembly, testPlan - #testPlan: # Required when testSelection == TestPlan - #testSuite: # Required when testSelection == TestPlan - #testConfiguration: # Required when testSelection == TestPlan - #sourcefilters: '**\*test*.dll' # Required when testSelection == TestAssembly - #testFilterCriteria: # Optional - #runSettingsFile: # Optional - #overrideRunParams: # Optional - #codeCoverageEnabled: false # Optional - #customSlicingEnabled: false # Optional - #testRunTitle: # Optional - #platform: # Optional - #configuration: # Optional - #testConfigurations: # Optional - #autMachineGroup: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/RunJMeterLoadTestV1.md b/docs/pipelines/tasks/includes/yaml/RunJMeterLoadTestV1.md deleted file mode 100644 index 6deef3bdc4d..00000000000 --- a/docs/pipelines/tasks/includes/yaml/RunJMeterLoadTestV1.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Cloud-based Apache JMeter load test -# Run an Apache JMeter load test in the cloud -- task: ApacheJMeterLoadTest@1 - inputs: - #connectedServiceName: # Optional - testDrop: - #loadTest: 'jmeter.jmx' - #agentCount: '1' # Options: 1, 2, 3, 4, 5 - #runDuration: '60' # Options: 60, 120, 180, 240, 300 - #geoLocation: 'Default' # Optional. Options: default, australia East, australia Southeast, brazil South, central India, central US, east Asia, east US 2, east US, japan East, japan West, north Central US, north Europe, south Central US, south India, southeast Asia, west Europe, west US - #machineType: '0' # Optional. Options: 0, 2 -``` diff --git a/docs/pipelines/tasks/includes/yaml/RunLoadTestV1.md b/docs/pipelines/tasks/includes/yaml/RunLoadTestV1.md deleted file mode 100644 index b2f2c34e7ce..00000000000 --- a/docs/pipelines/tasks/includes/yaml/RunLoadTestV1.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Cloud-based load test -# Run a load test in the cloud with Azure Pipelines -- task: CloudLoadTest@1 - inputs: - #connectedServiceName: # Optional - #testDrop: '$(System.DefaultWorkingDirectory)' - loadTest: - #activeRunSettings: 'useFile' # Optional. Options: useFile, changeActive - #runSettingName: # Required when activeRunSettings == ChangeActive - #testContextParameters: # Optional - #testSettings: # Optional - #thresholdLimit: # Optional - #machineType: '0' # Options: 0, 2 - #resourceGroupName: 'default' # Optional - #numOfSelfProvisionedAgents: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/ServiceFabricComposeDeployV0.md b/docs/pipelines/tasks/includes/yaml/ServiceFabricComposeDeployV0.md deleted file mode 100644 index 7c1aa8a0dad..00000000000 --- a/docs/pipelines/tasks/includes/yaml/ServiceFabricComposeDeployV0.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Service Fabric Compose deploy -# Deploy a Docker Compose application to an Azure Service Fabric cluster -- task: ServiceFabricComposeDeploy@0 - inputs: - clusterConnection: - #composeFilePath: '**/docker-compose.yml' - #applicationName: 'fabric:/Application1' - #registryCredentials: 'AzureResourceManagerEndpoint' # Options: azureResourceManagerEndpoint, containerRegistryEndpoint, usernamePassword, none - #dockerRegistryConnection: # Optional - #azureSubscription: # Required when registryCredentials == AzureResourceManagerEndpoint - #registryUserName: # Optional - #registryPassword: # Optional - #passwordEncrypted: true # Optional - #upgrade: # Optional - #deployTimeoutSec: # Optional - #removeTimeoutSec: # Optional - #getStatusTimeoutSec: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/ServiceFabricDeployV1.md b/docs/pipelines/tasks/includes/yaml/ServiceFabricDeployV1.md deleted file mode 100644 index 810c30004aa..00000000000 --- a/docs/pipelines/tasks/includes/yaml/ServiceFabricDeployV1.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 7/25/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Service Fabric application deployment -# Deploy an Azure Service Fabric application to a cluster -- task: ServiceFabricDeploy@1 - inputs: - applicationPackagePath: - serviceConnectionName: - #publishProfilePath: # Optional - #applicationParameterPath: # Optional - #overrideApplicationParameter: false # Optional - #compressPackage: false # Optional - #copyPackageTimeoutSec: # Optional - #registerPackageTimeoutSec: # Optional - #overwriteBehavior: 'SameAppTypeAndVersion' # Options: always, never, sameAppTypeAndVersion - #skipUpgradeSameTypeAndVersion: false # Optional - #skipPackageValidation: false # Optional - #useDiffPackage: false # Optional - #overridePublishProfileSettings: false # Optional - #isUpgrade: true # Optional - #unregisterUnusedVersions: true # Optional - #upgradeMode: 'Monitored' # Required when overridePublishProfileSettings == True && IsUpgrade == True# Options: monitored, unmonitoredAuto, unmonitoredManual - #failureAction: 'Rollback' # Required when overridePublishProfileSettings == True && IsUpgrade == True && UpgradeMode == Monitored# Options: rollback, manual - #upgradeReplicaSetCheckTimeoutSec: # Optional - #timeoutSec: # Optional - #forceRestart: false # Optional - #healthCheckRetryTimeoutSec: # Optional - #healthCheckWaitDurationSec: # Optional - #healthCheckStableDurationSec: # Optional - #upgradeDomainTimeoutSec: # Optional - #considerWarningAsError: false # Optional - #defaultServiceTypeHealthPolicy: # Optional - #maxPercentUnhealthyDeployedApplications: # Optional - #upgradeTimeoutSec: # Optional - #serviceTypeHealthPolicyMap: # Optional - #configureDockerSettings: false # Optional - #registryCredentials: 'AzureResourceManagerEndpoint' # Required when configureDockerSettings == True# Options: azureResourceManagerEndpoint, containerRegistryEndpoint, usernamePassword - #dockerRegistryConnection: # Required when configureDockerSettings == True && RegistryCredentials == ContainerRegistryEndpoint - #azureSubscription: # Required when configureDockerSettings == True && RegistryCredentials == AzureResourceManagerEndpoint - #registryUserName: # Optional - #registryPassword: # Optional - #passwordEncrypted: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/ServiceFabricPowerShellV1.md b/docs/pipelines/tasks/includes/yaml/ServiceFabricPowerShellV1.md deleted file mode 100644 index 2f087b15ac0..00000000000 --- a/docs/pipelines/tasks/includes/yaml/ServiceFabricPowerShellV1.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Service Fabric PowerShell -# Run a PowerShell script in the context of an Azure Service Fabric cluster connection -- task: ServiceFabricPowerShell@1 - inputs: - clusterConnection: - #scriptType: 'FilePath' # Options: filePath, inlineScript - #scriptPath: # Optional - #inline: '# You can write your PowerShell scripts inline here. # You can also pass predefined and custom variables to this script using arguments' # Optional - #scriptArguments: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/ServiceFabricUpdateManifestsV2.md b/docs/pipelines/tasks/includes/yaml/ServiceFabricUpdateManifestsV2.md deleted file mode 100644 index bbc49bcf984..00000000000 --- a/docs/pipelines/tasks/includes/yaml/ServiceFabricUpdateManifestsV2.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 08/20/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Update Service Fabric manifests -# Automatically update portions of application and service manifests in a packaged Azure Service Fabric application -- task: ServiceFabricUpdateManifests@2 - inputs: - #updateType: 'Manifest versions' # Options: manifest Versions, docker Image Settings - applicationPackagePath: - #versionSuffix: '.$(Build.BuildNumber)' # Required when updateType == Manifest Versions - #versionBehavior: 'Append' # Optional. Options: append, replace - #updateOnlyChanged: false # Required when updateType == Manifest Versions - #pkgArtifactName: # Required when updateType == Manifest versions && updateOnlyChanged == true - #logAllChanges: true # Optional - #compareType: 'LastSuccessful' # Optional. Options: lastSuccessful, specific - #buildNumber: # Optional - #overwriteExistingPkgArtifact: true # Optional - #imageNamesPath: # Optional - #imageDigestsPath: # Required when updateType == Docker Image Settings -``` diff --git a/docs/pipelines/tasks/includes/yaml/SqlAzureDacpacDeploymentV1.md b/docs/pipelines/tasks/includes/yaml/SqlAzureDacpacDeploymentV1.md deleted file mode 100644 index d2e8026314b..00000000000 --- a/docs/pipelines/tasks/includes/yaml/SqlAzureDacpacDeploymentV1.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 07/05/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure SQL Database deployment -# Deploy an Azure SQL Database using DACPAC or run scripts using SQLCMD -- task: SqlAzureDacpacDeployment@1 - inputs: - #azureConnectionType: 'ConnectedServiceNameARM' # Optional. Options: connectedServiceName, connectedServiceNameARM - #azureClassicSubscription: # Required when azureConnectionType == ConnectedServiceName - #azureSubscription: # Required when azureConnectionType == ConnectedServiceNameARM - #authenticationType: 'server' # Options: server, aadAuthenticationPassword, aadAuthenticationIntegrated, connectionString, servicePrincipal - #serverName: # Required when authenticationType == Server || AuthenticationType == AadAuthenticationPassword || AuthenticationType == AadAuthenticationIntegrated || AuthenticationType == servicePrincipal - #databaseName: # Required when authenticationType == Server || AuthenticationType == AadAuthenticationPassword || AuthenticationType == AadAuthenticationIntegrated || AuthenticationType == servicePrincipal - #sqlUsername: # Required when authenticationType == Server - #sqlPassword: # Required when authenticationType == Server - #aadSqlUsername: # Required when authenticationType == AadAuthenticationPassword - #aadSqlPassword: # Required when authenticationType == AadAuthenticationPassword - #connectionString: # Required when authenticationType == ConnectionString - #deployType: 'DacpacTask' # Options: dacpacTask, sqlTask, inlineSqlTask - #deploymentAction: 'Publish' # Required when deployType == DacpacTask. Options: publish, extract, export, import, script, driftReport, deployReport - #dacpacFile: # Required when deploymentAction == Publish || DeploymentAction == Script || DeploymentAction == DeployReport - #bacpacFile: # Required when deploymentAction == Import - #sqlFile: # Required when deployType == SqlTask - #sqlInline: # Required when deployType == InlineSqlTask - #publishProfile: # Optional - #additionalArguments: # Optional - #sqlAdditionalArguments: # Optional - #inlineAdditionalArguments: # Optional - #ipDetectionMethod: 'AutoDetect' # Options: autoDetect, iPAddressRange - #startIpAddress: # Required when ipDetectionMethod == IPAddressRange - #endIpAddress: # Required when ipDetectionMethod == IPAddressRange - #deleteFirewallRule: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/SqlDacpacDeploymentOnMachineGroupV0.md b/docs/pipelines/tasks/includes/yaml/SqlDacpacDeploymentOnMachineGroupV0.md deleted file mode 100644 index 0fcbbfd8877..00000000000 --- a/docs/pipelines/tasks/includes/yaml/SqlDacpacDeploymentOnMachineGroupV0.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# SQL Server database deploy -# Deploy a SQL Server database using DACPAC or SQL scripts -- task: SqlDacpacDeploymentOnMachineGroup@0 - inputs: - #taskType: 'dacpac' # Options: dacpac, sqlQuery, sqlInline - #dacpacFile: # Required when taskType == Dacpac - #sqlFile: # Required when taskType == SqlQuery - #executeInTransaction: false # Optional - #exclusiveLock: false # Optional - #appLockName: # Required when exclusiveLock == True - #inlineSql: # Required when taskType == SqlInline - #targetMethod: 'server' # Required when taskType == Dacpac# Options: server, connectionString, publishProfile - #serverName: 'localhost' # Required when targetMethod == Server || TaskType == SqlQuery || TaskType == SqlInline - #databaseName: # Required when targetMethod == Server || TaskType == SqlQuery || TaskType == SqlInline - #authScheme: 'windowsAuthentication' # Required when targetMethod == Server || TaskType == SqlQuery || TaskType == SqlInline# Options: windowsAuthentication, sqlServerAuthentication - #sqlUsername: # Required when authScheme == SqlServerAuthentication - #sqlPassword: # Required when authScheme == SqlServerAuthentication - #connectionString: # Required when targetMethod == ConnectionString - #publishProfile: # Optional - #additionalArguments: # Optional - #additionalArgumentsSql: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/SshV0.md b/docs/pipelines/tasks/includes/yaml/SshV0.md deleted file mode 100644 index 1250551a5c3..00000000000 --- a/docs/pipelines/tasks/includes/yaml/SshV0.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.service: azure-devops-pipelines ---- - -```YAML -# SSH -# Run shell commands or a script on a remote machine using SSH -- task: SSH@0 - inputs: - sshEndpoint: - #runOptions: 'commands' # Options: commands, script, inline - #commands: # Required when runOptions == Commands - #scriptPath: # Required when runOptions == Script - #inline: # Required when runOptions == Inline - #interpreterCommand: # Used when runOptions == Inline - #args: # Optional - #failOnStdErr: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/TwineAuthenticateV0.md b/docs/pipelines/tasks/includes/yaml/TwineAuthenticateV0.md deleted file mode 100644 index c111535a5a2..00000000000 --- a/docs/pipelines/tasks/includes/yaml/TwineAuthenticateV0.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -author: davidstaheli -ms.author: dastahel -ms.date: 10/31/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Python twine upload authenticate -# Authenticate for uploading Python distributions using twine. Add '-r FeedName/EndpointName --config-file $(PYPIRC_PATH)' to your twine upload command. For feeds present in this organization, use the feed name as the repository (-r). Otherwise, use the endpoint name defined in the service connection. -- task: TwineAuthenticate@0 - inputs: - artifactFeeds: - #externalFeeds: # Optional - #publishPackageMetadata: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/TwineAuthenticateV1.md b/docs/pipelines/tasks/includes/yaml/TwineAuthenticateV1.md deleted file mode 100644 index 95ba473083c..00000000000 --- a/docs/pipelines/tasks/includes/yaml/TwineAuthenticateV1.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -ms.topic: include -ms.date: 08/02/2019 -author: steved0x -ms.author: sdanie -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Python twine upload authenticate V1 -# Authenticate for uploading Python distributions using twine. Add '-r FeedName/EndpointName --config-file $(PYPIRC_PATH)' to your twine upload command. For feed present in this organization, use the feed name as the repository (-r). Otherwise, use the endpoint name defined in the service connection. -- task: TwineAuthenticate@1 - inputs: - #artifactFeed: MyTestFeed # Optional - #pythonUploadServiceConnection: OtherOrganizationFeed # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/UniversalPackagesV0.md b/docs/pipelines/tasks/includes/yaml/UniversalPackagesV0.md deleted file mode 100644 index 50cde82335c..00000000000 --- a/docs/pipelines/tasks/includes/yaml/UniversalPackagesV0.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -ms.topic: include -author: arob98 -ms.author: angrobe -ms.date: 03/01/2020 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Universal packages -# Download or publish Universal Packages -- task: UniversalPackages@0 - inputs: - #command: 'download' # Options: download, publish - #downloadDirectory: '$(System.DefaultWorkingDirectory)' # Required when command == Download - #feedsToUse: 'internal' # Options: internal, external - #externalFeedCredentials: # Optional - #vstsFeed: # Required when feedsToUse == Internal - #vstsFeedPackage: # Required when feedsToUse == Internal - #vstsPackageVersion: # Required when feedsToUse == Internal - #feedDownloadExternal: # Required when feedsToUse == External - #packageDownloadExternal: # Required when feedsToUse == External - #versionDownloadExternal: # Required when feedsToUse == External - #publishDirectory: '$(Build.ArtifactStagingDirectory)' # Required when command == Publish - #feedsToUsePublish: 'internal' # Options: internal, external - #publishFeedCredentials: # Required when feedsToUsePublish == External - #vstsFeedPublish: # Required when feedsToUsePublish == Internal - #publishPackageMetadata: true # Optional - #vstsFeedPackagePublish: # Required when feedsToUsePublish == Internal - #feedPublishExternal: # Required when feedsToUsePublish == External - #packagePublishExternal: # Required when feedsToUsePublish == External - #versionOption: 'patch' # Options: major, minor, patch, custom - #versionPublish: # Required when versionOption == Custom - packagePublishDescription: - #verbosity: 'None' # Options: none, trace, debug, information, warning, error, critical - #publishedPackageVar: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/UsePythonVersionV0.md b/docs/pipelines/tasks/includes/yaml/UsePythonVersionV0.md deleted file mode 100644 index c6623df4796..00000000000 --- a/docs/pipelines/tasks/includes/yaml/UsePythonVersionV0.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -ms.topic: include -ms.date: 04/25/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Use Python version -# Use the specified version of Python from the tool cache, optionally adding it to the PATH -- task: UsePythonVersion@0 - inputs: - #versionSpec: '3.x' - #addToPath: true - #architecture: 'x64' # Options: x86, x64 (this argument applies only on Windows agents) -``` diff --git a/docs/pipelines/tasks/includes/yaml/UseRubyVersionV0.md b/docs/pipelines/tasks/includes/yaml/UseRubyVersionV0.md deleted file mode 100644 index 02de8c3360d..00000000000 --- a/docs/pipelines/tasks/includes/yaml/UseRubyVersionV0.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -ms.topic: include -author: davidstaheli -ms.author: dastahel -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Use Ruby version -# Use the specified version of Ruby from the tool cache, optionally adding it to the PATH -- task: UseRubyVersion@0 - inputs: - #versionSpec: '>= 2.4' - #addToPath: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/VSBuildV1.md b/docs/pipelines/tasks/includes/yaml/VSBuildV1.md deleted file mode 100644 index 0eaa68a6ee0..00000000000 --- a/docs/pipelines/tasks/includes/yaml/VSBuildV1.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/23/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Visual Studio Build -# Build with MSBuild and set the Visual Studio version property -- task: VSBuild@1 - inputs: - #solution: '**\*.sln' - #vsVersion: 'latest' # Optional. Options: latest, 16.0, 15.0, 14.0, 12.0, 11.0 - #msbuildArgs: # Optional - #platform: # Optional - #configuration: # Optional - #clean: false # Optional - #maximumCpuCount: false # Optional - #restoreNugetPackages: false # Optional - #msbuildArchitecture: 'x86' # Optional. Options: x86, x64 - #logProjectEvents: true # Optional - #createLogFile: false # Optional - #logFileVerbosity: 'normal' # Optional. Options: quiet, minimal, normal, detailed, diagnostic -``` diff --git a/docs/pipelines/tasks/includes/yaml/VsTestPlatformToolInstallerV1.md b/docs/pipelines/tasks/includes/yaml/VsTestPlatformToolInstallerV1.md deleted file mode 100644 index 646486dc1a4..00000000000 --- a/docs/pipelines/tasks/includes/yaml/VsTestPlatformToolInstallerV1.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Visual Studio test platform installer -# Acquire the test platform from nuget.org or the tool cache. Satisfies the ‘vstest’ demand and can be used for running tests and collecting diagnostic data using the Visual Studio Test task. -- task: VisualStudioTestPlatformInstaller@1 - inputs: - #packageFeedSelector: 'nugetOrg' # Options: nugetOrg, customFeed, netShare - #versionSelector: 'latestPreRelease' # Required when packageFeedSelector == NugetOrg || PackageFeedSelector == CustomFeed# Options: latestPreRelease, latestStable, specificVersion - #testPlatformVersion: # Required when versionSelector == SpecificVersion - #customFeed: # Required when packageFeedSelector == CustomFeed - #username: # Optional - #password: # Optional - #netShare: # Required when packageFeedSelector == NetShare -``` diff --git a/docs/pipelines/tasks/includes/yaml/VsTestV2.md b/docs/pipelines/tasks/includes/yaml/VsTestV2.md deleted file mode 100644 index de285c886f8..00000000000 --- a/docs/pipelines/tasks/includes/yaml/VsTestV2.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/02/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Visual Studio Test -# Run unit and functional tests (Selenium, Appium, Coded UI test, etc.) using the Visual Studio Test (VsTest) runner. Test frameworks that have a Visual Studio test adapter such as MsTest, xUnit, NUnit, Chutzpah (for JavaScript tests using QUnit, Mocha and Jasmine), etc. can be run. Tests can be distributed on multiple agents using this task (version 2). -- task: VSTest@2 - inputs: - #testSelector: 'testAssemblies' # Options: testAssemblies, testPlan, testRun - #testAssemblyVer2: | # Required when testSelector == TestAssemblies - # **\*test*.dll - # !**\*TestAdapter.dll - # !**\obj\** - #testPlan: # Required when testSelector == TestPlan - #testSuite: # Required when testSelector == TestPlan - #testConfiguration: # Required when testSelector == TestPlan - #tcmTestRun: '$(test.RunId)' # Optional - #searchFolder: '$(System.DefaultWorkingDirectory)' - #testFiltercriteria: # Optional - #runOnlyImpactedTests: False # Optional - #runAllTestsAfterXBuilds: '50' # Optional - #uiTests: false # Optional - #vstestLocationMethod: 'version' # Optional. Options: version, location - #vsTestVersion: 'latest' # Optional. Options: latest, 16.0, 15.0, 14.0, toolsInstaller - #vstestLocation: # Optional - #runSettingsFile: # Optional - #overrideTestrunParameters: # Optional - #pathtoCustomTestAdapters: # Optional - #runInParallel: False # Optional - #runTestsInIsolation: False # Optional - #codeCoverageEnabled: False # Optional - #otherConsoleOptions: # Optional - #distributionBatchType: 'basedOnTestCases' # Optional. Options: basedOnTestCases, basedOnExecutionTime, basedOnAssembly - #batchingBasedOnAgentsOption: 'autoBatchSize' # Optional. Options: autoBatchSize, customBatchSize - #customBatchSizeValue: '10' # Required when distributionBatchType == BasedOnTestCases && BatchingBasedOnAgentsOption == CustomBatchSize - #batchingBasedOnExecutionTimeOption: 'autoBatchSize' # Optional. Options: autoBatchSize, customTimeBatchSize - #customRunTimePerBatchValue: '60' # Required when distributionBatchType == BasedOnExecutionTime && BatchingBasedOnExecutionTimeOption == CustomTimeBatchSize - #dontDistribute: False # Optional - #testRunTitle: # Optional - #platform: # Optional - #configuration: # Optional - #publishRunAttachments: true # Optional - #failOnMinTestsNotRun: false # Optional - #minimumExpectedTests: '1' # Optional - #diagnosticsEnabled: false # Optional - #collectDumpOn: 'onAbortOnly' # Optional. Options: onAbortOnly, always, never - #rerunFailedTests: False # Optional - #rerunType: 'basedOnTestFailurePercentage' # Optional. Options: basedOnTestFailurePercentage, basedOnTestFailureCount - #rerunFailedThreshold: '30' # Optional - #rerunFailedTestCasesMaxLimit: '5' # Optional - #rerunMaxAttempts: '3' # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/WindowsMachineFileCopyV2.md b/docs/pipelines/tasks/includes/yaml/WindowsMachineFileCopyV2.md deleted file mode 100644 index 46805eafab5..00000000000 --- a/docs/pipelines/tasks/includes/yaml/WindowsMachineFileCopyV2.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Windows machine file copy -# Copy files to remote Windows machines -- task: WindowsMachineFileCopy@2 - inputs: - sourcePath: - #machineNames: # Required - #adminUserName: # Optional - #adminPassword: # Optional - targetPath: - #cleanTargetBeforeCopy: false # Optional - #copyFilesInParallel: true # Optional - #additionalArguments: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/XamarinAndroidV1.md b/docs/pipelines/tasks/includes/yaml/XamarinAndroidV1.md deleted file mode 100644 index a09ad845f5f..00000000000 --- a/docs/pipelines/tasks/includes/yaml/XamarinAndroidV1.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/23/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Xamarin.Android -# Build an Android app with Xamarin -- task: XamarinAndroid@1 - inputs: - #projectFile: '**/*.csproj' - #target: # Optional - #outputDirectory: # Optional - #configuration: # Optional - #createAppPackage: true # Optional - #clean: false # Optional - #msbuildLocationOption: 'version' # Optional. Options: version, location - #msbuildVersionOption: '15.0' # Optional. Options: latest, 16.0, 15.0, 14.0, 12.0, 4.0 - #msbuildFile: # Required when msbuildLocationOption == Location - #msbuildArchitectureOption: 'x86' # Optional. Options: x86, x64 - #msbuildArguments: # Optional - #jdkOption: 'JDKVersion' # Options: jDKVersion, path - #jdkVersionOption: 'default' # Optional. Options: default, 1.11, 1.10, 1.9, 1.8, 1.7, 1.6 - #jdkDirectory: # Required when jdkOption == Path - #jdkArchitectureOption: 'x64' # Optional. Options: x86, x64 -``` diff --git a/docs/pipelines/tasks/includes/yaml/XamarinTestCloudV1.md b/docs/pipelines/tasks/includes/yaml/XamarinTestCloudV1.md deleted file mode 100644 index 284942022c3..00000000000 --- a/docs/pipelines/tasks/includes/yaml/XamarinTestCloudV1.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -ms.topic: include -author: shashban -ms.author: shashban -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Xamarin Test Cloud -# [Deprecated] Test mobile apps with Xamarin Test Cloud using Xamarin.UITest. Instead, use the 'App Center test' task. -- task: XamarinTestCloud@1 - inputs: - appFile: - #dsymFile: # Optional - teamApiKey: - email: - devices: - #series: 'master' - testAssemblyDirectory: - #parallelizationOption: 'none' # Options: none, --Fixture-Chunk, --Test-Chunk - #localeOption: 'en_US' # Options: da_DK, nl_NL, en_GB, en_US, fr_FR, de_DE, ja_JP, ru_RU, es_MX, es_ES, user - #userDefinedLocale: # Optional - #testCloudFile: '**/packages/**/tools/test-cloud.exe' - #optionalArgs: # Optional - #publishNUnitResults: true # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/XamariniOSV2.md b/docs/pipelines/tasks/includes/yaml/XamariniOSV2.md deleted file mode 100644 index fcbdd71c0de..00000000000 --- a/docs/pipelines/tasks/includes/yaml/XamariniOSV2.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/23/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Xamarin.iOS -# Build an iOS app with Xamarin on macOS -- task: XamariniOS@2 - inputs: - #solutionFile: '**/*.sln' - #configuration: 'Release' - #clean: false # Optional - #packageApp: true - #buildForSimulator: false # Optional - #runNugetRestore: false - #args: # Optional - #workingDirectory: # Optional - #mdtoolFile: # Optional - #signingIdentity: # Optional - #signingProvisioningProfileID: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/XcodePackageiOSV0.md b/docs/pipelines/tasks/includes/yaml/XcodePackageiOSV0.md deleted file mode 100644 index 256634caf5a..00000000000 --- a/docs/pipelines/tasks/includes/yaml/XcodePackageiOSV0.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 11/13/2017 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Xcode Package iOS -# Generate an .ipa file from Xcode build output using xcrun (Xcode 7 or below) -- task: XcodePackageiOS@0 - inputs: - #appName: 'name.app' - #ipaName: 'name.ipa' - provisioningProfile: - #sdk: 'iphoneos' - #appPath: '$(SDK)/$(Configuration)/build.sym/$(Configuration)-$(SDK)' - #ipaPath: '$(SDK)/$(Configuration)/build.sym/$(Configuration)-$(SDK)/output' -``` diff --git a/docs/pipelines/tasks/includes/yaml/XcodeV5.md b/docs/pipelines/tasks/includes/yaml/XcodeV5.md deleted file mode 100644 index fff5baa1a01..00000000000 --- a/docs/pipelines/tasks/includes/yaml/XcodeV5.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -ms.topic: include -author: vijayma -ms.author: vijayma -ms.date: 12/23/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Xcode -# Build, test, or archive an Xcode workspace on macOS. Optionally package an app. -- task: Xcode@5 - inputs: - #actions: 'build' - #configuration: '$(Configuration)' # Optional - #sdk: '$(SDK)' # Optional - #xcWorkspacePath: '**/*.xcodeproj/project.xcworkspace' # Optional - #scheme: # Optional - #xcodeVersion: 'default' # Optional. Options: 8, 9, 10, default, specifyPath - #xcodeDeveloperDir: # Optional - packageApp: - #archivePath: # Optional - #exportPath: 'output/$(SDK)/$(Configuration)' # Optional - #exportOptions: 'auto' # Optional. Options: auto, plist, specify - #exportMethod: 'development' # Required when exportOptions == Specify - #exportTeamId: # Optional - #exportOptionsPlist: # Required when exportOptions == Plist - #exportArgs: # Optional - #signingOption: 'nosign' # Optional. Options: nosign, default, manual, auto - #signingIdentity: # Optional - #provisioningProfileUuid: # Optional - #provisioningProfileName: # Optional - #teamId: # Optional - #destinationPlatformOption: 'default' # Optional. Options: default, iOS, tvOS, macOS, custom - #destinationPlatform: # Optional - #destinationTypeOption: 'simulators' # Optional. Options: simulators, devices - #destinationSimulators: 'iPhone 8' # Optional. Default value: iPhone8 for Xcode 11 and iPhone 7 for other iOS projects; Apple TV for tvOS projects. - #destinationDevices: # Optional - #args: # Optional - #workingDirectory: # Optional - #useXcpretty: true # Optional - #publishJUnitResults: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/azure-file-copy-v4.md b/docs/pipelines/tasks/includes/yaml/azure-file-copy-v4.md deleted file mode 100644 index 2a22dc11d2f..00000000000 --- a/docs/pipelines/tasks/includes/yaml/azure-file-copy-v4.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -ms.topic: include -author: RoopeshNair -ms.author: ronai -ms.date: 12/07/2018 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure file copy -# Copy files to Azure Blob Storage or virtual machines -- task: AzureFileCopy@4 - inputs: - sourcePath: - azureSubscription: - destination: # Options: azureBlob, azureVMs - storage: - #containerName: # Required when destination == AzureBlob - #blobPrefix: # Optional - #resourceGroup: # Required when destination == AzureVMs - #resourceFilteringMethod: 'machineNames' # Optional. Options: machineNames, tags - #machineNames: # Optional - #vmsAdminUserName: # Required when destination == AzureVMs - #vmsAdminPassword: # Required when destination == AzureVMs - #targetPath: # Required when destination == AzureVMs - #additionalArgumentsForBlobCopy: # Optional - #additionalArgumentsForVMCopy: # Optional - #enableCopyPrerequisites: false # Optional | Required to be true when destination == AzureVMs - #copyFilesInParallel: true # Optional - #cleanTargetBeforeCopy: false # Optional - #skipCACheck: true # Optional - #sasTokenTimeOutInMinutes: # Optional -``` diff --git a/docs/pipelines/tasks/includes/yaml/azure-key-vault-v2.md b/docs/pipelines/tasks/includes/yaml/azure-key-vault-v2.md deleted file mode 100644 index f00e5e66676..00000000000 --- a/docs/pipelines/tasks/includes/yaml/azure-key-vault-v2.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -ms.topic: include -ms.date: 09/30/2021 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Azure Key Vault -# Download Azure Key Vault secrets -- task: AzureKeyVault@2 - inputs: - connectedServiceName: # Azure subscription - keyVaultName: # Name of existing key vault - secretsFilter: '*' # Downloads all secrets for the key vault - runAsPreJob: true # Runs before the job starts -``` \ No newline at end of file diff --git a/docs/pipelines/tasks/includes/yaml/azure-load-testing-v1.md b/docs/pipelines/tasks/includes/yaml/azure-load-testing-v1.md deleted file mode 100644 index b4229cf4bb3..00000000000 --- a/docs/pipelines/tasks/includes/yaml/azure-load-testing-v1.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -ms.topic: include -author: ntrogh -ms.author: nicktrog -ms.date: 01/21/2022 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Invoke Azure Load Testing -# Run an Apache JMeter test script in Azure Load Testing -- task: AzureLoadTest@1 - inputs: - azureSubscription: - resourceGroup: # Required. Name of resource group that contains an Azure Load Testing resource. - loadTestResource: # Required. Name of an existing Azure Load Testing resource. - loadTestConfigFile: # Required. Path to the load test YAML configuration file. Relative path from repo root where the load test files are available. - #secrets: # Optional. Array of JSON objects that consist of the name and value for each secret. The name should match the secret name used in the Apache JMeter test script. - #env: # Optional. Array of JSON objects that consist of the name and value for each environment variable. The name should match the variable name used in the Apache JMeter test script. -``` diff --git a/docs/pipelines/tasks/includes/yaml/cache-v2.md b/docs/pipelines/tasks/includes/yaml/cache-v2.md deleted file mode 100644 index 99ee20dbdfb..00000000000 --- a/docs/pipelines/tasks/includes/yaml/cache-v2.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.topic: include -author: damccorm -ms.date: 12/13/2019 -ms.subservice: azure-devops-pipelines-tasks ---- - -```YAML -# Cache -# Cache files between runs -- task: Cache@2 - inputs: - key: - path: - #cacheHitVar: # Optional - #restoreKeys: # Optional -``` diff --git a/docs/pipelines/tasks/transforms-variable-substitution.md b/docs/pipelines/tasks/transforms-variable-substitution.md deleted file mode 100644 index 895eaf4de8f..00000000000 --- a/docs/pipelines/tasks/transforms-variable-substitution.md +++ /dev/null @@ -1,458 +0,0 @@ ---- -title: File transforms and variable substitution -ms.custom: seodec18 -description: File transforms and variable substitution for tasks in Azure Pipelines and Team Foundation Server (TFS) -ms.assetid: C287712A-8979-444C-8B1F-A7B3016801D6 -ms.topic: reference -ms.author: ronai -author: RoopeshNair -ms.date: 02/18/2020 -monikerRange: '<= azure-devops' ---- - -# File transforms and variable substitution reference - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end - -Some tasks, such as the [Azure App Service Deploy](https://github.com/Microsoft/azure-pipelines-tasks/tree/master/Tasks/AzureRmWebAppDeploymentV3) task -version 3 and later and the [IIS Web App Deploy](/azure/devops/pipelines/tasks/reference/iisweb-app-deployment-on-machine-group-v0) task, allow users to configure the package based on the environment specified. -These tasks use **msdeploy.exe**, which supports the overriding of values in the **web.config** file with values from the **parameters.xml** file. -However, file transforms and variable substitution are **not confined to web app files**. You can use these techniques with any XML or JSON files. - -::: moniker range="> tfs-2018" -> [!NOTE] -> File transforms and variable substitution are also supported by the separate [File Transform task](/azure/devops/pipelines/tasks/reference/file-transform-v2) for use in Azure Pipelines. - You can use the File Transform task to apply file transformations and variable substitutions on any configuration and parameters files. -::: moniker-end - -Configuration substitution is specified in the **File Transform and Variable Substitution Options** -section of the settings for the tasks. The transformation and substitution options are: - -* [XML transformation](#xmltransform) -* [XML variable substitution](#xmlvarsubs) -* [JSON variable substitution](#jsonvarsubs) - -When the task runs, it first performs XML transformation, XML variable substitution, and JSON variable substitution -on configuration and parameters files. Next, it invokes **msdeploy.exe**, which uses -the **parameters.xml** file to substitute values in the **web.config** file. - - -## XML Transformation - -XML transformation supports transforming the configuration files (`*.config` files) -by following [Web.config Transformation Syntax](/previous-versions/aspnet/dd465326(v=vs.110)) -and is based on the environment to which the web package will be deployed. -This option is useful when you want to add, remove or modify configurations for different environments. -Transformation will be applied for other configuration files including Console or Windows service application -configuration files (for example, **FabrikamService.exe.config**). - -### Configuration transform file naming conventions - -XML transformation will be run on the `*.config` file for -transformation configuration files named `*.Release.config` or `*..config` -and will be executed in the following order: - -1. `*.Release.config` (for example, **fabrikam.Release.config**) -1. `*..config` (for example, **fabrikam.Production.config**) - -For example, if your package contains the following files: - -* Web.config -* Web.Debug.config -* Web.Release.config -* Web.Production.config - -and your stage name is **Production**, the transformation is applied -for `Web.config` with `Web.Release.config` followed by `Web.Production.config`. - -### XML transformation example - -1. Create a Web Application package with the necessary configuration and transform files. - For example, use the following configuration files: - - **Configuration file** - - ```xml - - - - - - - - - - - - - - - ``` -

      - - **Transform file** - - ```xml - - - - - - - - - - - - - ``` -

      - - This example transform configuration file does three things: - - * It adds a new database connection string inside the `ConnectionStrings` element. - * It modifies value of `Webpages:Enabled` inside the `appSettings` element. - * It removes the `debug` attribute from the `compilation` element inside the `System.Web` element. - - >For more information, see [Web.config Transformation Syntax for Web Project Deployment Using Visual Studio](/previous-versions/aspnet/dd465326(v=vs.110)) - -2. Create a release pipeline with a stage named **Release**. - -3. Add an **Azure App Service Deploy** task and set (tick) the **XML transformation** option. - - ![Release pipeline for XML transformation](media/release-definition2.png) - -4. Save the release pipeline and start a new release. - -5. Open the `Web.config` file to see the transformations from `Web.Release.config`. - - ```xml - - - - - - - - - - - - - - - - ``` - -### XML transformation notes - -* You can use this technique to create a default package and deploy it to multiple stages. - -* XML transformation takes effect only when the configuration file and transform file - are in the same folder within the specified package. - -* By default, MSBuild applies the transformation as it generates the web package if the `` element - is already present in the transform file in the `*.csproj` file. In such cases, the **Azure App Service Deploy** - task will fail because there is no further transformation applied on the `Web.config` file. Therefore, it is - recommended that the `` element is removed from all the transform files to disable any build-time - configuration when using XML transformation. - -* Set the **Build Action** property for each of the transformation files (`Web.config`) to **Content** so that the files are copied to the root folder. - - ```xml - ... - - Web.config - - - Web.config - - ... - ``` - - -## XML variable substitution - -This feature enables you to modify configuration settings in configuration files (`*.config` files) -inside web packages and XML parameters files (`parameters.xml`). -In this way, the same package can be configured based on the environment to which it will be deployed. - -Variable substitution takes effect only on the `applicationSettings`, `appSettings`, `connectionStrings`, -and `configSections` elements of configuration files. If you are looking to substitute values outside of these elements you can use a (`parameters.xml`) file, however you will need to use a 3rd party pipeline task to handle the variable substitution. - -### XML variable substitution example - -As an example, consider the task of changing the following values in `Web.config`: - -```xml - - - -

      - - - - - - - - - - - - - - - - - - - - - - - -``` -

      - -1. Create a release pipeline with a stage named **Release**. - -1. Add an **Azure App Service Deploy** task and set (tick) the **XML variable substitution** option. - - ![Release pipeline for XML variable substitution](media/release-definition.png) - -1. Define the required values in release pipeline variables: - - | Name | Value | Secure | Scope | - | ---- | ----- | ------ | ----- | - | DefaultConnection | Data Source=(ProdDB)\\MSSQLProdDB;AttachFileName=Local.mdf | No | Release | - | AdminUserName | ProdAdminName | No | Release | - | AdminPassword | [your-password] | Yes | Release | - | invariantName | System.Data.SqlClientExtension | No | Release | - -1. Save the release pipeline and start a new release. - -1. Open the `Web.config` file to see the variable substitutions. - - ```xml - - - -

      - - - - - - - - - - - - - - - - - - - - ``` - -### XML variable substitution notes - -* By default, ASP.NET applications have a default parameterized connection attribute. - These values are overridden only in the `parameters.xml` file inside the web package. - -* Because substitution occurs before deployment, the user can override the - values in `Web.config` using `parameters.xml` (inside the web package) or - a `setparameters` file. - - -## JSON variable substitution - -This feature substitutes values in the JSON configuration files. -It overrides the values in the specified JSON configuration files -(for example, `appsettings.json`) with the values matching names of release pipeline -and stage variables. - -To substitute variables in specific JSON files, provide newline-separated -list of JSON files. File names must be specified relative to the root folder. -For example, if your package has this structure: - -```Folders -/WebPackage(.zip) - /---- content - /----- website - /---- appsettings.json - /---- web.config - /---- [other folders] - /--- archive.xml - /--- systeminfo.xml -``` - -and you want to substitute values in **appsettings.json**, enter the relative -path from the root folder; for example `content/website/appsettings.json`. -Alternatively, use wildcard patterns to search for specific JSON files. -For example, `**/appsettings.json` returns the relative path and name of files -named **appsettings.json**. - -### JSON variable substitution example - -As an example, consider the task of overriding values in this JSON file: - -```json -{ - "Data": { - "DefaultConnection": { - "ConnectionString": "Data Source=(LocalDb)\\MSDB;AttachDbFilename=aspcore-local.mdf;" - }, - "DebugMode": "enabled", - "DBAccess": { - "Administrators": ["Admin-1", "Admin-2"], - "Users": ["Vendor-1", "vendor-3"] - }, - "FeatureFlags": { - "Preview": [ - { - "newUI": "AllAccounts" - }, - { - "NewWelcomeMessage": "Newusers" - } - ] - } - } -} -``` -

      - -The task is to override the values of **ConnectionString**, **DebugMode**, -the first of the **Users** values, and **NewWelcomeMessage** at the respective places within the JSON file hierarchy. - -# [Classic](#tab/Classic) - -1. Create a release pipeline with a stage named **Release**. - -2. Add an **Azure App Service Deploy** task and enter a newline-separated - list of JSON files to substitute the variable values in the **JSON variable substitution** textbox. - Files names must be relative to the root folder. - You can use wildcards to search for JSON files. For example: - `**/*.json` means substitute values in all the JSON files within the package. - - ![Release pipeline for JSON variable substitution](media/json-setting.png) - -3. Define the required substitution values in release pipeline or stage variables. - - - | Name | Value | Secure | Scope | - |-----------------------------------------------|-------------------------------------------------------|--------|---------| - | Data.DebugMode | disabled | No | Release | - | Data.DefaultConnection.ConnectionString | Data Source=(prodDB)\\MSDB;AttachDbFilename=prod.mdf; | No | Release | - | Data.DBAccess.Users.0 | Admin-3 | Yes | Release | - | Data.FeatureFlags.Preview.1.NewWelcomeMessage | AllAccounts | No | Release | - - -4. Save the release pipeline and start a new release. - -5. After the transformation, the JSON will contain the following: - - ```json - { - "Data": { - "DefaultConnection": { - "ConnectionString": "Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;" - }, - "DebugMode": "disabled", - "DBAccess": { - "Administrators": ["Admin-1", "Admin-2"], - "Users": ["Admin-3", "vendor-3"] - }, - "FeatureFlags": { - "Preview": [ - { - "newUI": "AllAccounts" - }, - { - "NewWelcomeMessage": "AllAccounts" - } - ] - } - } - } - ''' - -# [YAML](#tab/yaml) - -Following YAML snippet showcases JSON variable substitution. - -```YAML -variables: - Data.DebugMode: disabled - Data.DefaultConnection.ConnectionString: 'Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;' - Data.DBAccess.Users.0: Admin-3 - Data.FeatureFlags.Preview.1.NewWelcomeMessage: AllAccounts - -# Update appsettings.json via FileTransform task. -- task: FileTransform@1 - displayName: 'File transformation: appsettings.json' - inputs: - folderPath: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip' - targetFiles: '**/appsettings.json' - fileType: json - -# Deploy web app -- task: AzureWebApp@1 - inputs: - azureSubscription: - appName: - package: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip -``` - -* * * - -### JSON variable substitution notes - -* To substitute values in nested levels of the file, concatenate the names with - a period (`.`) in hierarchical order. - -* A JSON object may contain an array whose values can be referenced by their index. - For example, to substitute the first value in the **Users** array shown above, - use the variable name `DBAccess.Users.0`. To update the value in **NewWelcomeMessage**, - use the variable name `FeatureFlags.Preview.1.NewWelcomeMessage`. However, the [file transform task](/azure/devops/pipelines/tasks/reference/file-transform-v2) has the ability to transform entire arrays in JSON files. You can also use `DBAccess.Users = ["NewUser1","NewUser2","NewUser3"]`. - -* Only **String** substitution is supported for JSON variable substitution. - -* Substitution is supported for only UTF-8 and UTF-16 LE encoded files. - -* If the file specification you enter does not match any file, the task will fail. - -* Variable name matching is case-sensitive. - -* Variable substitution is applied for only the JSON keys predefined in the object hierarchy. It does not create new keys. - -* If a variable name includes periods ("."), the transformation will attempt to locate the item within the hierarchy. - For example, if the variable name is `first.second.third`, the transformation process will search for: - - ```json - "first" : { - "second": { - "third" : "value" - } - } - ``` - - as well as `"first.second.third" : "value"`. \ No newline at end of file diff --git a/docs/pipelines/test/codecoverage-for-pullrequests.md b/docs/pipelines/test/codecoverage-for-pullrequests.md index a4423dcb449..185d72f64ac 100644 --- a/docs/pipelines/test/codecoverage-for-pullrequests.md +++ b/docs/pipelines/test/codecoverage-for-pullrequests.md @@ -1,12 +1,12 @@ --- title: Code coverage for pull requests -description: Continuous testing. Measuring code coverage for changes in pull requests. +description: Continuous testing. Measuring code coverage for changes in pull requests. ms.assetid: 1B7C890E-FB67-4BEF-A48E-20C9453BD54A -ms.topic: conceptual -ms.custom: "continuous-test, seodec18, cross-service" -ms.author: shashban -author: shashban -ms.date: 10/04/2019 +ms.topic: conceptual +ms.custom: continuous-test, cross-service +ms.author: jeom +author: raviLiftr +ms.date: 09/14/2023 monikerRange: 'azure-devops' --- @@ -14,25 +14,24 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Code coverage is an important quality metric and helps you measure the percentage of your project's code that is being tested. To ensure that quality for your project improves over time (or at the least, does not regress), it is essential that new code being brought into the system is well tested. This means that when developers raise pull requests, knowing whether their changes are covered by tests would help plug any testing holes before the changes are merged into the target branch. Repo owners may also want to set policies to prevent merging large untested changes. +Code coverage is an important quality metric and helps you measure the percentage of your project's code that is being tested. To ensure that quality for your project improves over time (or at the least, doesn't regress), new code being brought into the system must be well tested. When developers raise pull requests, knowing whether their changes are covered by tests helps plug any testing holes before the changes are merged into the target branch. Repo owners might also want to set policies to prevent merging large untested changes. ### Full coverage, diff coverage -Typically, coverage gets measured for the entire codebase of a project. This is **full coverage**. -However, in the context of pull requests, developers are focused on the changes they are making and want to know whether the specific lines of code they have added or changed are covered. This is **diff coverage**. +**Full coverage** is when coverage gets measured for the entire codebase of a project. But, in the context of pull requests, developers focus on the changes they're making and want to know whether the specific lines of code they added or changed are covered. This type of coverage is **diff coverage**. ## Prerequisites -In order to get coverage metrics for a pull request, first configure a pipeline that validates pull requests. In this pipeline, configure the test tool you are using to collect code coverage metrics. Coverage results must then be published to the server for reporting. +In order to get coverage metrics for a pull request, first configure a pipeline that validates pull requests. In this pipeline, configure the test tool you're using to collect code coverage metrics. Coverage results must then be published to the server for reporting. To learn more about collecting and publishing code coverage results for the language of your choice, see the [Ecosystems](../ecosystems/ecosystems.md) section. For example, collect and publish code coverage for [.NET core apps](../ecosystems/dotnet-core.md#collect-code-coverage). > [!NOTE] > While you can collect and publish code coverage results for many different languages using Azure Pipelines, the **code coverage for pull requests** feature discussed in this document is currently available only for .NET and .NET core projects using the Visual Studio code coverage results format (file extension .coverage). Support for other languages and coverage formats will be added in future milestones. -## Coverage status, details and indicators +## Coverage status, details, and indicators -Once you have configured a pipeline that collects and publishes code coverage, it posts a code coverage status when a pull request is raised. By default, the server checks for atleast 70% of changed lines being covered by tests. The diff coverage threshold target can be changed to a value of your choice. See the settings configuration section below to learn more about this. +Once you configure a pipeline that collects and publishes code coverage, it posts a code coverage status when you create a pull request. By default, the server checks for at least 70% of changed lines being covered by tests. The diff coverage threshold target can be changed to a value of your choice. For more information, see the [settings configuration section](#configuring-coverage-settings) further in this article. > [!div class="mx-imgBorder"] > ![Screenshot showing coverage status check.](media/codecoverage-for-pullrequests/coveragestatuscheck.png) @@ -58,7 +57,7 @@ The settings that can be changed are: | Setting | Description | Default | Permissible values | |:---:|:---:|:---:|:---:| -| status | Indicates whether code coverage status check should be posted on pull requests.
      Turning this off will not post any coverage checks and coverage annotations will not appear in the changed files view. | on | on, off | +| status | Indicates whether code coverage status check should be posted on pull requests.
      Turning off doesn't post any coverage checks and coverage annotations don't appear in the changed files view. | on | on, off | | target | Target threshold value for diff coverage must be met for a successful coverage status to be posted. | 70% | Desired % number | | comments | Indicates whether a comment containing coverage details for each code file should be posted in the pull request | off | on, off | @@ -82,24 +81,26 @@ More examples with details can be found in the [code coverage YAML samples repo] ## Protect a branch using a code coverage policy -Code coverage status check for pull requests is only a suggestion for developers and it does not prevent pull requests with low code coverage from being merged into the target branch. If you maintain a repo where you would like to prevent developers from merging changes that do not meet a coverage threshold, you must configure a [branch policy using the coverage status check](../../repos/git/pr-status-policy.md). +Code coverage status check for pull requests is only a suggestion for developers and it doesn't prevent pull requests with low code coverage from being merged into the target branch. To prevent developers from merging changes that don't meet a coverage threshold, you must configure a [branch policy using the coverage status check](../../repos/git/pr-status-policy.md). > [!TIP] > Code coverage status posted from a pipeline follows the naming convention `{name-of-your-pipeline/codecoverage}`. > [!NOTE] > Branch policies in Azure Repos (even optional policies) prevent pull requests from completing automatically if they fail. This behavior is not specific to code coverage policy. +> +> [Starting September 2023, the code coverage policy won't be overridden to **Failed** if the build fails. This feature will be enabled for all customers](/azure/devops/release-notes/2023/pipelines/sprint-227-update#disabled-override-of-code-coverage-policy-status-to-failed-when-build-is-failing). ## FAQ ### Which coverage tools and result formats can be used for validating code coverage in pull requests? -Code coverage for pull requests capability is currently only available for Visual Studio code coverage (.coverage) formats. This can be used if you publish code coverage using the Visual Studio Test task, the test verb of dotnet core task and the TRX option of the publish test results task. +Code coverage for pull requests capability is currently only available for Visual Studio Code coverage, `.coverage`, formats. Use it if you publish code coverage using the Visual Studio Test task, the test verb of dotnet core task and the TRX option of the publish test results task. Support for other coverage tools and result formats will be added in future milestones. -### If multiple pipelines are triggered when a pull request is raised, will coverage be merged across the pipelines? +### If multiple pipelines are triggered when a pull request is raised, will coverage get merged across the pipelines? -If multiple pipelines are triggered when a pull request is raised, code coverage will not be merged. The capability is currently designed for a single pipeline that collects and publishes code coverage for pull requests. -If you need the ability to merge coverage data across pipelines, please file a feature request on [developer community](https://developercommunity.visualstudio.com/spaces/21/index.html). +If multiple pipelines get triggered when a pull request gets raised, code coverage doesn't merge. The capability is currently designed for a single pipeline that collects and publishes code coverage for pull requests. +If you need to merge coverage data across pipelines, submit a feature request on [Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). [!INCLUDE [help-and-support-footer](includes/help-and-support-footer.md)] diff --git a/docs/pipelines/test/continuous-test-selenium.md b/docs/pipelines/test/continuous-test-selenium.md index 5ad387b6fbb..cb316f6440e 100644 --- a/docs/pipelines/test/continuous-test-selenium.md +++ b/docs/pipelines/test/continuous-test-selenium.md @@ -1,11 +1,11 @@ --- title: Perform UI tests with Selenium -description: UI Testing with Selenium in a continuous deployment pipeline in Azure Pipelines and Team Foundation Server TFS +description: UI Testing with Selenium in a continuous deployment pipeline in Azure Pipelines and Team Foundation Server (TFS). ms.assetid: 1B90D2DF-4AB0-4B65-8039-2B14A25FB547 ms.topic: conceptual -ms.custom: continuous-test, seodec18 -ms.author: shashban -author: shashban +ms.custom: continuous-test +ms.author: jeom +author: raviLiftr ms.date: 03/15/2019 monikerRange: '<= azure-devops' --- @@ -14,16 +14,10 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - Performing user interface (UI) testing as part of the release pipeline is a great way of detecting unexpected changes, and need not be difficult. This -topic describes using Selenium to test your website +article describes using Selenium to test your website during a continuous deployment release and test automation. Special considerations that apply when running UI tests are discussed in [UI testing considerations](ui-testing-considerations.md). @@ -40,10 +34,10 @@ For more information about Selenium browser automation, see: ## Create your test project -As there is no template for Selenium testing, the +As there's no template for Selenium testing, the easiest way to get started is to use the Unit Test template. This automatically adds the test framework -references and enables you run and view the results +references and enables you to run and view the results from Visual Studio Test Explorer. 1. In Visual Studio, open the **File** menu and choose **New Project**, @@ -160,24 +154,24 @@ from Visual Studio Test Explorer. ## Define your build pipeline -You'll need a continuous integration (CI) build pipeline that builds your Selenium tests. -For more details, see [Build your .NET desktop app for Windows](../apps/aspnet/build-aspnet-4.md). +You need a continuous integration (CI) build pipeline that builds your Selenium tests. +For more information, see [Build your .NET desktop app for Windows](../apps/aspnet/build-aspnet-4.md). ## Create your web app -You'll need a web app to test. You can use an existing app, or deploy one in your continuous deployment (CD) release pipeline. -The example code above runs tests against Bing.com. For details of how to set up your own release pipeline +You need a web app to test. You can use an existing app, or deploy one in your continuous deployment (CD) release pipeline. +The previous code example runs tests against Bing.com. For details of how to set up your own release pipeline to deploy a web app, see [Deploy to Azure Web Apps](../targets/webapp.md). -## Decide how you will deploy and test your app +## Decide how to deploy and test your app You can deploy and test your app using either the Microsoft-hosted agent in Azure, or a self-hosted agent that you install on the target servers. * When using the **Microsoft-hosted agent**, you should use the Selenium web drivers that are - pre-installed on the Windows agents (agents named **Hosted VS 20xx**) because they are compatible with the browser versions installed on the Microsoft-hosted agent images. + preinstalled on the Windows agents (agents named **Hosted VS 20xx**) because they're compatible with the browser versions installed on the Microsoft-hosted agent images. The paths to the folders containing these drivers can be obtained from the environment variables named `IEWebDriver` (Internet Explorer), `ChromeWebDriver` (Google Chrome), and `GeckoWebDriver` (Firefox). - The drivers are **not** pre-installed on other agents such as Linux, Ubuntu, and macOS agents. + The drivers are **not** preinstalled on other agents such as Linux, Ubuntu, and macOS agents. Also see [UI testing considerations](ui-testing-considerations.md). -* When using a **self-hosted agent** that you deploy on your target servers, agents must be configured to run interactively with auto-logon enabled. +* When using a **self-hosted agent** that you deploy on your target servers, agents must be configured to run interactively with autologon enabled. See [Build and release agents](../agents/agents.md#interactive-or-service) and [UI testing considerations](ui-testing-considerations.md). @@ -218,7 +212,7 @@ You can deploy and test your app using either the Microsoft-hosted agent in Azur ![Configuring the variables](media/continuous-test-selenium/continuous-test-selenium-08a.png) -2. If you are deploying your app and tests to environments where the target machines that host the agents do not have Visual Studio installed: +2. If you're deploying your app and tests to environments where the target machines that host the agents don't have Visual Studio installed: * In the **Tasks** tab of the release pipeline, choose the **+** icon in the **Run on agent** section. Select the **Visual Studio Test Platform Installer** task and choose **Add**. Leave all the settings diff --git a/docs/pipelines/test/flaky-test-management.md b/docs/pipelines/test/flaky-test-management.md index 408aa22f7eb..3a49b1b660e 100644 --- a/docs/pipelines/test/flaky-test-management.md +++ b/docs/pipelines/test/flaky-test-management.md @@ -2,10 +2,10 @@ title: Manage flaky tests description: Improve productivity with flaky test management system ms.assetid: BBDD071F-4017-4AF0-AB59-71F8FEFF1E37 -ms.topic: conceptual -ms.custom: "continuous-test, seodec18" -ms.author: chcomley -author: chcomley +ms.topic: conceptual +ms.custom: continuous-test +ms.author: jeom +author: raviLiftr ms.date: 08/31/2020 monikerRange: 'azure-devops' --- diff --git a/docs/pipelines/test/includes/help-and-support-footer.md b/docs/pipelines/test/includes/help-and-support-footer.md index 4d370aab91f..1614c3b6981 100644 --- a/docs/pipelines/test/includes/help-and-support-footer.md +++ b/docs/pipelines/test/includes/help-and-support-footer.md @@ -2,8 +2,8 @@ ms.topic: include ms.service: azure-devops-pipelines ms.manager: mijacobs -ms.author: jukullam -author: juliakm +ms.author: jeom +author: raviLiftr ms.date: 02/19/2020 --- diff --git a/docs/pipelines/test/includes/navigation-include.md b/docs/pipelines/test/includes/navigation-include.md index 510af61312a..647d24cad66 100644 --- a/docs/pipelines/test/includes/navigation-include.md +++ b/docs/pipelines/test/includes/navigation-include.md @@ -1,9 +1,8 @@ --- ms.topic: include ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: jukullam -author: juliakm +ms.author: jeom +author: raviLiftr ms.date: 02/19/2020 --- diff --git a/docs/pipelines/test/includes/paralleltest-maxcpucount.md b/docs/pipelines/test/includes/paralleltest-maxcpucount.md index c473a559910..9dc2627b570 100644 --- a/docs/pipelines/test/includes/paralleltest-maxcpucount.md +++ b/docs/pipelines/test/includes/paralleltest-maxcpucount.md @@ -1,9 +1,8 @@ --- ms.topic: include ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: shashban -author: shashban +ms.author: jeom +author: raviLiftr ms.date: 02/19/2020 --- diff --git a/docs/pipelines/test/includes/paralleltest-runsettingsmerge.md b/docs/pipelines/test/includes/paralleltest-runsettingsmerge.md index 40c45d2be15..2735b8d639e 100644 --- a/docs/pipelines/test/includes/paralleltest-runsettingsmerge.md +++ b/docs/pipelines/test/includes/paralleltest-runsettingsmerge.md @@ -1,9 +1,8 @@ --- ms.topic: include ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: shashban -author: shashban +ms.author: jeom +author: raviLiftr ms.date: 02/19/2020 --- diff --git a/docs/pipelines/test/includes/pipelines-hub-include-nolink.md b/docs/pipelines/test/includes/pipelines-hub-include-nolink.md index 7fd00391f8c..eed246fe24f 100644 --- a/docs/pipelines/test/includes/pipelines-hub-include-nolink.md +++ b/docs/pipelines/test/includes/pipelines-hub-include-nolink.md @@ -1,9 +1,8 @@ --- ms.topic: include ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: shashban -author: shashban +ms.author: jeom +author: raviLiftr ms.date: 02/19/2020 --- diff --git a/docs/pipelines/test/includes/pipelines-hub-include.md b/docs/pipelines/test/includes/pipelines-hub-include.md index c6f7c5c026e..fb851e8ffe7 100644 --- a/docs/pipelines/test/includes/pipelines-hub-include.md +++ b/docs/pipelines/test/includes/pipelines-hub-include.md @@ -1,9 +1,8 @@ --- ms.topic: include ms.service: azure-devops-pipelines -ms.manager: mijacobs -ms.author: shashban -author: shashban +ms.author: jeom +author: raviLiftr ms.date: 02/19/2020 --- diff --git a/docs/pipelines/test/media/test-analytics/test-failures.png b/docs/pipelines/test/media/test-analytics/test-failures.png index 4aacb755a96..6a5efd2ea14 100644 Binary files a/docs/pipelines/test/media/test-analytics/test-failures.png and b/docs/pipelines/test/media/test-analytics/test-failures.png differ diff --git a/docs/pipelines/test/parallel-testing-any-test-runner.md b/docs/pipelines/test/parallel-testing-any-test-runner.md index 59168d379ae..6746a998c7c 100644 --- a/docs/pipelines/test/parallel-testing-any-test-runner.md +++ b/docs/pipelines/test/parallel-testing-any-test-runner.md @@ -2,12 +2,12 @@ title: Run any tests in parallel description: Speed up testing by running tests in parallel for any test runner ms.assetid: 21D3C181-5067-45C7-8A98-1F0ECB2CCB01 -ms.topic: conceptual -ms.custom: "continuous-test, seodec18, cross-service" -ms.author: shashban -author: shashban +ms.topic: conceptual +ms.custom: continuous-test, cross-service +ms.author: jeom +author: raviLiftr ms.date: 12/07/2018 -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" --- # Run tests in parallel for any test runner @@ -32,7 +32,6 @@ Familiarize yourself with the concepts of [agents](../agents/agents.md) and [job Each agent can run only one job at a time. To run multiple jobs in parallel, you must configure multiple agents. You also need sufficient [parallel jobs](../licensing/concurrent-jobs.md). - ## Setting up parallel jobs Specify 'parallel' strategy in the YAML and indicate how many jobs should be dispatched. diff --git a/docs/pipelines/test/parallel-testing-vstest.md b/docs/pipelines/test/parallel-testing-vstest.md index a2cfad3d4bb..cc9b0911adc 100644 --- a/docs/pipelines/test/parallel-testing-vstest.md +++ b/docs/pipelines/test/parallel-testing-vstest.md @@ -1,11 +1,11 @@ --- title: Run VSTest tests in parallel -description: Continuous testing. Speed up testing by running tests in parallel using Visual Studio Test task. +description: Continuous testing. Speed up testing by running tests in parallel using Visual Studio Test task. ms.assetid: 8AEECA6C-6CC8-418C-AF75-6527E365FD88 -ms.topic: conceptual -ms.custom: "continuous-test, seodec18" -ms.author: shashban -author: shashban +ms.topic: conceptual +ms.custom: continuous-test +ms.author: jeom +author: raviLiftr ms.date: 11/13/2019 monikerRange: '<= azure-devops' --- @@ -27,12 +27,6 @@ This can be done easily by employing the additional capacity offered by the clou This article discusses how you can configure the [Visual Studio Test task](/azure/devops/pipelines/tasks/reference/vstest-v2) to run tests in parallel by using multiple agents. -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - ## Pre-requisite Familiarize yourself with the concepts of [agents](../agents/agents.md) and [jobs](../process/phases.md). @@ -126,7 +120,7 @@ use the following steps. * Add the **Visual Studio Test** task and configure it to use the required [slicing strategy](#strategy). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Setting up jobs for parallel testing in YAML pipelines @@ -153,7 +147,7 @@ to validate the app functionality. > [!NOTE] > To use the multi-agent capability in release pipelines with on-premises TFS server, you must use TFS 2017 Update 1 or a later version. -1. **Deploy app using a single agent**. Use the tasks shown in the image below to deploy a web app to Azure App Services. +1. **Deploy app using a single agent**. Use the Azure Deployment: Create or Update Resource Group or the Azure App Service Deploy task to deploy a web app to Azure App services. This uses the default job settings (single agent, no parallel jobs). ![DeployApp1Agent](media/parallel-testing-vstest/deploy-app-1-agent.png) @@ -187,7 +181,6 @@ to validate the app functionality. > [Visual Studio Test Platform Installer task](/azure/devops/pipelines/tasks/reference/visual-studio-test-platform-installer-v1) to > acquire the required version of the test platform. - ## Massively parallel testing by combining parallel pipeline jobs with parallel test execution When parallel jobs are used in a pipeline, it employs multiple machines (agents) to run each job in parallel. diff --git a/docs/pipelines/test/requirements-traceability.md b/docs/pipelines/test/requirements-traceability.md index c40d98a24c9..d112721f91c 100644 --- a/docs/pipelines/test/requirements-traceability.md +++ b/docs/pipelines/test/requirements-traceability.md @@ -3,9 +3,9 @@ title: Requirements traceability description: Link requirements, tests, and bugs to enable requirements traceability ms.assetid: 41F15A66-D8C2-43AA-9E38-BCED9A8D3F55 ms.topic: conceptual -ms.custom: "continuous-test, seodec18, cross-service" -ms.author: vinojos -author: vinodjo +ms.custom: continuous-test, cross-service +ms.author: jeom +author: raviLiftr ms.date: 07/01/2020 monikerRange: '<= azure-devops' --- @@ -16,19 +16,14 @@ monikerRange: '<= azure-devops' **Requirements traceability** is the ability to relate and document two or more phases of a development process, which can then be traced both forward or backward from its origin. -Requirements traceability help teams to get insights into indicators such as +Requirements traceability helps teams to get insights into indicators such as **quality of requirements** or **readiness to ship the requirement**. -A fundamental aspect of requirements traceability is association of the requirements to test cases, bugs and code changes. +A fundamental aspect of requirements traceability is association of the requirements to test cases, bugs, and code changes. -> Read the [glossary](./test-glossary.md) to understand test report terminology. - -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end +Read the [glossary](./test-glossary.md) to understand test report terminology. + ## Agile teams running automated tests Agile teams have characteristics including, but not limited to the following @@ -38,74 +33,22 @@ Agile teams have characteristics including, but not limited to the following * Negligible manual testing footprint; limited to exploratory testing * High degree of automation -The following sections explore traceability from **Quality**, **Bug** and **Source** standpoints for Agile teams. +The following sections explore traceability from **Quality**, **Bug**, and **Source** standpoints for Agile teams. ### Quality traceability -:::moniker range="<=azure-devops-2019" - -To ensure user requirements meet the quality goals, the requirements -in a project can be linked to test results, which can then be viewed on the -team's dashboard. This enables end-to-end traceability with a simple way to monitor test results. -To link automated tests with requirements, visit [test report](review-continuous-test-results-after-build.md) in build or release. - -1. In the results section under **Tests** tab of a build or release summary, - select the test(s) to be linked to requirements and choose **Link**. - - ![Select tests to be linked to requirements](media/requirements-traceability/link-results-to-requirements.png) - -2. Choose a work item to be linked to the selected test(s) in one of the specified way: - - * Choose an applicable work item from the list of suggested work items. The list is based on the most recently viewed and updated work items. - * Specify a work item ID. - * Search for a work item based on the title text. - - ![Select requirements work item](media/requirements-traceability/select-workitem.png) - - > The list shows only work items belonging to the Requirements category. - -3. After the requirements have been linked to the test results you can view the test - results grouped by requirement. Requirement is one of the many "Group by" options provided - to make it easy to navigate the test results. - - ![Group results by requirements](media/requirements-traceability/groupby-requirements.png) - -4. Teams often want to pin the summarized view of requirements traceability to a dashboard. - Use the [Requirements quality](../../report/dashboards/widget-catalog.md) widget for this. - - ![Create team dashboard](media/requirements-traceability/team-dashboard.png) - -5. Configure the **Requirements quality** widget with the required options and save it. - - * **Requirements query**: Select a work item query that captures the requirements, such as the user stories in the current iteration. - * **Quality data**: Specify the stage of the pipeline for which the requirements quality should be traced. - - ![Configure widget](media/requirements-traceability/configure-widget.png) - -6. View the widget in the team's dashboard. It lists all the **Requirements** in scope, - along with the **Pass Rate** for the tests and count of Failed tests. Selecting a **Failed** test - count opens the **Tests** tab for the selected build or release. - The widget also helps to track the requirements without any associated test(s). - - ![Track requirements without tests](media/requirements-traceability/requirements-quality-widget.png) - -:::moniker-end - -:::moniker range=">azure-devops-2019" +:::moniker range="<=azure-devops" -To ensure user requirements meet the quality goals, the requirements -in a project can be linked to test results, which can then be viewed on the -team's dashboard. This enables end-to-end traceability with a simple way to monitor test results. -To link automated tests with requirements, visit [test report](review-continuous-test-results-after-build.md) in build or release. +Link project requirements to test results for end-to-end traceability with a simple way to monitor test results. To link automated tests with requirements, see [Test report](review-continuous-test-results-after-build.md). 1. In the results section under **Tests** tab of a build or release summary, - select the test(s) to be linked to requirements and choose **Link**. + select the test to be linked to requirements and choose **Link**. ![Select tests to be linked to requirements](media/requirements-traceability/link-results-to-requirements.png) -1. Choose a work item to be linked to the selected test(s) in one of the specified way: +2. Choose a work item to be linked to the selected test in one of the following ways: * Choose an applicable work item from the list of suggested work items. The list is based on the most recently viewed and updated work items. * Specify a work item ID. @@ -115,22 +58,22 @@ To link automated tests with requirements, visit [test report](review-continuous > The list shows only work items belonging to the Requirements category. -1. Teams often want to pin the summarized view of requirements traceability to a dashboard. - Use the [Requirements quality](../../report/dashboards/widget-catalog.md) widget for this. +3. Teams often want to pin the summarized view of requirements traceability to a dashboard. + Use the [Requirements quality](../../report/dashboards/widget-catalog.md) widget to do so. ![Create team dashboard](media/requirements-traceability/team-dashboard.png) -1. Configure the **Requirements quality** widget with the required options and save it. +4. Configure the **Requirements quality** widget with the required options and save it. * **Requirements query**: Select a work item query that captures the requirements, such as the user stories in the current iteration. * **Quality data**: Specify the stage of the pipeline for which the requirements quality should be traced. ![Configure widget](media/requirements-traceability/configure-widget.png) -1. View the widget in the team's dashboard. It lists all the **Requirements** in scope, +5. View the widget in the team's dashboard. It lists all the **Requirements** in scope, along with the **Pass Rate** for the tests and count of Failed tests. Selecting a **Failed** test count opens the **Tests** tab for the selected build or release. - The widget also helps to track the requirements without any associated test(s). + The widget also helps to track the requirements without any associated test. ![Track requirements without tests](media/requirements-traceability/requirements-quality-widget.png) @@ -140,21 +83,15 @@ To link automated tests with requirements, visit [test report](review-continuous ### Bug traceability -Testing gives a measure of the confidence to ship a change to users. A test failure signals an issues with the change. -Failures can happen for many reasons such as errors in the source under test, bad test code, environmental issues, -[flaky tests](test-glossary.md), and more. +Testing gives a measure of the confidence to ship a change to users. A test failure signals an issue with the change. Failures can occur due to errors in the source under test, bad test code, environmental issues, [flaky tests](test-glossary.md), and more. Bugs provide a robust way to track test failures and drive accountability in the team to take the required remedial actions. -To associate bugs with test results, visit [test report](review-continuous-test-results-after-build.md) in build or release. +To associate bugs with test results, see [Test report](review-continuous-test-results-after-build.md). -1. In the results section of the **Tests** tab select the tests against which the bug should be created - and choose **Bug**. Multiple test results can be mapped to a single bug. - This is typically done when the reason for the failures is attributable to a single cause such as - the unavailability of a dependent service, a database connection failure, or similar issues. +1. In the results section of the Tests tab, select the tests against which the bug should be created and choose **Bug**. Multiple test results can be mapped to a single bug, which is typically done when the reason for the failures attributes to a single cause, such as an unavailable dependent service, a database connection failure, or similar issues. ![Link bugs to tests](media/requirements-traceability/link-bugs-to-tests.png) -2. Open the work item to see the bug. It captures the complete context of the test results including key information - such as the error message, stack trace, comments, and more. +2. Open the work item. The bug captures the complete context of the test results including key information, such as the error message, stack trace, comments, and more. ![Capture bug details](media/requirements-traceability/capture-bug-details.png) @@ -171,7 +108,7 @@ To associate bugs with test results, visit [test report](review-continuous-test- 5. In the work item, select **Test case** or **Test result** to go directly to the **Tests** page for the selected build or release. You can troubleshoot the failure, update your analysis in the bug, and make the changes required to fix the issue as applicable. - While both the links take you to the **Tests tab**, the default section shown are **History** and **Debug** respectively. + While both the links take you to the **Tests tab**, the default sections include **History** and **Debug**. ![Tests Tab full page view](media/requirements-traceability/redirect-to-tests-tab.png) @@ -180,8 +117,8 @@ To associate bugs with test results, visit [test report](review-continuous-test- ### Source traceability When troubleshooting test failures that occur consistently over a period of time, -it is important to trace back to the initial set of changes - where the failure originated. -This can help significantly to narrow down the scope for identifying the problematic test or +it's important to trace back to the initial set of changes - where the failure originated. +This step can help significantly to narrow down the scope for identifying the problematic test or source under test. To discover the first instance of test failures and trace it back to the associated code changes, visit [Tests tab](review-continuous-test-results-after-build.md) in build or release. @@ -190,11 +127,11 @@ visit [Tests tab](review-continuous-test-results-after-build.md) in build or rel ![View Failing release](media/requirements-traceability/view-failing-release.png) -2. This opens another instance of the **Tests** tab in a new window, showing the first instance of consecutive failures for the test. + Another instance of the **Tests** tab opens in a new window, showing the first instance of consecutive failures for the test. ![originating test failure](media/requirements-traceability/view-originating-test.png) -3. Based on the build or release pipeline, you can choose the timeline or pipeline view to see what code changes were committed. +2. Based on the build or release pipeline, you can choose the timeline or pipeline view to see what code changes were committed. You can analyze the code changes to identify the potential root cause of the test failure. ![View code commits](media/requirements-traceability/view-code-commits.png) @@ -203,9 +140,8 @@ visit [Tests tab](review-continuous-test-results-after-build.md) in build or rel ## Traditional teams using planned testing -Teams that are moving from manual testing to continuous (automated) testing, and have a subset of tests already automated, -can execute them as part of the pipeline or on demand (see [test report](review-continuous-test-results-after-build.md)). -Referred to as **Planned testing**, automated tests can be [associated to the test cases](../../test/associate-automated-test-with-test-case.md) +Teams moving from manual testing to continuous, automated testing, and have a subset of tests that are already automated, can [execute them as part of the pipeline or on demand](review-continuous-test-results-after-build.md). +**Planned testing**, or "automated tests" can be [associated to the test cases](../../test/associate-automated-test-with-test-case.md) in a test plan and executed from **Azure Test Plans**. Once associated, these tests contribute towards the quality metrics of the corresponding requirements. diff --git a/docs/pipelines/test/review-code-coverage-results.md b/docs/pipelines/test/review-code-coverage-results.md index aa881b92bb4..fa8a458e292 100644 --- a/docs/pipelines/test/review-code-coverage-results.md +++ b/docs/pipelines/test/review-code-coverage-results.md @@ -3,9 +3,9 @@ title: Review code coverage description: Review code coverage results in Azure Pipelines or Team Foundation Server (TFS) ms.assetid: 86D94FB7-D730-4ECE-8300-5E76934090A5 ms.topic: conceptual -ms.custom: "continuous-test, seodec18, cross-service" -ms.author: vinojos -author: vinodjo +ms.custom: continuous-test, cross-service +ms.author: jeom +author: raviLiftr ms.date: 06/23/2020 monikerRange: '<= azure-devops' --- @@ -25,34 +25,15 @@ Reviewing the code coverage result helps to identify code path(s) that are not covered by the tests. This information is important to improve the test collateral over time by reducing the test debt. -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - ## Example To view an example of publishing code coverage results for your choice of language, see the **Ecosystems** section of the Pipelines topics. For example, collect and publish -code coverage for [JavaScript](../ecosystems/javascript.md) using Istanbul. +code coverage for [JavaScript](../ecosystems/customize-javascript.md) using Istanbul. ## View results -:::moniker range="< azure-devops-2019" - -The code coverage summary can be viewed in the build timeline view. -The summary shows the overall percentage of line coverage. - -![View code coverage results](media/review-code-coverage-results/view-code-coverage-summary-2018.png) - -> [!NOTE] -> Merging code coverage results from multiple [test runs](test-glossary.md) is -> limited to .NET and .NET Core at present. This will be supported for other formats in a future release. - -:::moniker-end - -:::moniker range=">= azure-devops-2019" +:::moniker range="<=azure-devops" The code coverage summary can be viewed on the **Summary** tab on the pipeline run summary. @@ -67,7 +48,6 @@ The results can be viewed and downloaded on the **Code coverage** tab. > This means that you may have to separate the build stage into a pipeline of its own if you want to review the > code coverage results prior to deploying to production. - > [!NOTE] > Merging code coverage results from multiple [test runs](test-glossary.md) is > limited to .NET and .NET Core at present. This will be supported for other formats in a future release. @@ -76,16 +56,7 @@ The results can be viewed and downloaded on the **Code coverage** tab. ## Artifacts -:::moniker range="< azure-devops-2019" - -The code coverage artifacts published during the build can be viewed under the -**Build artifacts published** milestone in the timeline view. - -![View code coverage artifact](media/review-code-coverage-results/view-code-coverage-artifact-2018.png) - -:::moniker-end - -:::moniker range=">= azure-devops-2019" +:::moniker range="<=azure-devops" The code coverage artifacts published during the build can be viewed under the **Summary** tab on the pipeline run summary. @@ -108,7 +79,7 @@ The code coverage artifacts published during the build can be viewed under the * ## Tasks -* [Publish Code Coverage Results](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v1) publishes code coverage results to Azure Pipelines or TFS, +* [Publish Code Coverage Results](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v2) publishes code coverage results to Azure Pipelines or TFS, which were produced by a build in [Cobertura](https://cobertura.github.io/cobertura/) or [JaCoCo](https://www.eclemma.org/jacoco/) format. * Built-in tasks such as [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2), [.NET Core](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2), [Ant](/azure/devops/pipelines/tasks/reference/ant-v1), [Maven](/azure/devops/pipelines/tasks/reference/maven-v3), diff --git a/docs/pipelines/test/review-continuous-test-results-after-build.md b/docs/pipelines/test/review-continuous-test-results-after-build.md index b3dc6ca9597..906625d031f 100644 --- a/docs/pipelines/test/review-continuous-test-results-after-build.md +++ b/docs/pipelines/test/review-continuous-test-results-after-build.md @@ -3,9 +3,9 @@ title: Review test results description: Review continuous test results with a build or release pipeline in Azure Pipelines or Team Foundation Server (TFS) ms.assetid: EA5D7524-3683-4660-B3B6-3F29AD3587AC ms.topic: conceptual -ms.custom: "continuous-test, seodec18, cross-service" -ms.author: vinojos -author: vinodjo +ms.custom: continuous-test, cross-service +ms.author: jeom +author: raviLiftr ms.date: 10/06/2021 monikerRange: '<= azure-devops' --- @@ -16,10 +16,10 @@ monikerRange: '<= azure-devops' Automated tests can be configured to run as part of a build or release for various [languages](../ecosystems/javascript.md). Test reports provide an effective and consistent way to view the tests results executed using different test frameworks, -in order to measure pipeline quality, review traceability, troubleshoot failures and drive failure ownership. +in order to measure pipeline quality, review traceability, troubleshoot failures, and drive failure ownership. In addition, it provides many advanced reporting capabilities explored in the following sections. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" You can also perform deeper analysis of test results by using the [Analytics Service](../../report/powerbi/what-is-analytics.md). @@ -29,41 +29,26 @@ For an example of using this with your build and deploy pipelines, see [Analyze Read the [glossary](./test-glossary.md) to understand test report terminology. -::: moniker range="< azure-devops-2019" - -> [!NOTE] -> Test report is available in TFS 2015 and above, however the new experience -> described in this topic is currently available only in Azure Pipelines. - -::: moniker-end - -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - Published test results can be viewed in the **Tests** tab in a build or release summary. ## Surface test results in the Tests tab Test results can be surfaced in the **Tests** tab using one of the following options: -* **Automatically inferred test results**. By default, your pipeline can automatically infer the test output for a few popular test runners. - This is done by parsing the error logs generated during the build operation and then checking for signatures of test failures. +* **Automatically inferred test results**. By default, your pipeline can automatically infer the test output for a few popular test runners. Parse the error logs generated during the build operation and then check for signatures of test failures. Currently, Azure DevOps supports the following languages and test runners for automatically inferring the test results: - - JavaScript - Mocha, Jest and Jasmine + - JavaScript - Mocha, Jest, and Jasmine - Python- Unittest > [!NOTE] > This inferred test report is a limited experience. Some features available in fully-formed test reports are not present here > [(more details)](#automatically_inferred_tests). We recommend that you publish a fully-formed test report to get the full Test and Insights experience in Pipelines. Also see: - - [Publishing fully-formed test reports for JavaScript test runners](../ecosystems/customize-javascript.md#run-unit-tests) - - [Publishing fully-formed test reports for Python test runners](../ecosystems/customize-python.md#test) + - [Publishing fully formed test reports for JavaScript test runners](../ecosystems/customize-javascript.md#run-unit-tests) + - [Publishing fully formed test reports for Python test runners](../ecosystems/customize-python.md#test) -* **Test execution tasks**. Built-in test execution tasks such as [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) +* **Test execution tasks**. Built-in test execution tasks, such as [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) that automatically publish test results to the pipeline, or others such as [Ant](/azure/devops/pipelines/tasks/reference/ant-v1), [Maven](/azure/devops/pipelines/tasks/reference/maven-v3), [Gulp](/azure/devops/pipelines/tasks/reference/gulp-v1), [Grunt](/azure/devops/pipelines/tasks/reference/grunt-v0), and [Xcode](/azure/devops/pipelines/tasks/reference/xcode-v5) that provide this capability as an option within the task. @@ -76,7 +61,7 @@ Test results can be surfaced in the **Tests** tab using one of the following opt ## Surface test information beyond the Tests tab The **Tests** tab provides a detailed summary of the test execution. -This is helpful in tracking the quality of the pipeline, as well as for troubleshooting failures. +This is helpful in tracking the quality of the pipeline, and for troubleshooting failures. Azure DevOps also provides other ways to surface the test information: * The [Dashboard](../../report/dashboards/dashboards.md) provides visibility of your team's progress. @@ -104,7 +89,7 @@ test results as a measure of **pass percentage** along with indicators for **fai ## View test results in release -In the pipeline view you can see all the stages and associated tests. +In the pipeline view, you can see all the stages and associated tests. The view provides a summary of the test results as a measure of **pass percentage** along with indicators for **failures** and **aborts** if these exist. These indicators are same as in the build timeline view, giving a consistent experience across build and release. @@ -144,7 +129,7 @@ The following capabilities of the **Tests** tab help to improve productivity and ### Filter large test results Over time, tests accrue and, for large applications, can easily grow to tens of thousands of tests. -For these applications with very many tests, it can be hard to navigate through the results to identify test failures, +For these applications with many tests, it can be hard to navigate through the results to identify test failures, associate root causes, or get ownership of issues. Filters make it easy to quickly navigate to the test results of your interest. You can filter on **Test Name**, **Outcome** (failed, passed, and more), **Test Files** (files holding tests) and **Owner** (for test files). All of the filter criteria are cumulative in nature. @@ -158,7 +143,7 @@ you can organize the **Results** view exactly as you require. ### Test debt management with bugs -To manage your test debt for failing or long running tests you can create a bug or add data to existing bug and all view all associated work items in the work item tab. +To manage your test debt for failing or long running tests, you can create a bug or add data to existing bug and all view all associated work items in the work item tab. ### Immersive troubleshooting experience @@ -183,10 +168,9 @@ You can create or add to an existing bug to manage test debt for failures or lon ### Test trends with historical data History of test execution can provide meaningful insights into reliability or performance of tests. -When troubleshooting a failure, it is valuable to know how a test has performed in the past. +When troubleshooting a failure, it's valuable to know how a test has performed in the past. The **Tests** tab provides test history in context with the test results. -The test history information is exposed in a progressive manner starting with the current build pipeline to other branches, -or the current stage to other stages, for build and release respectively. +The test history information is exposed in a progressive manner, starting with the current build pipeline to other branches, or the current stage to other stages, for build and release respectively. ![View historical trends](media/review-continuous-test-results-after-build/view-historical-trend.png) @@ -195,8 +179,8 @@ or the current stage to other stages, for build and release respectively. ### View execution of in-progress tests Tests, such as integration and functional tests, can run for a long time. -Therefore, it is important to see the current or near real-time status of test execution at any given time. -Even for cases where tests run quickly, it's useful to know the status of the relevant test result(s) as early as possible; +Therefore, it's important to see the current or near real-time status of test execution at any given time. +Even for cases where tests run quickly, it's useful to know the status of the relevant test results as early as possible; especially when failures occur. The **in-progress** view eliminates the need to wait for test execution to finish. Results are available in near real-time as execution progresses, helping you to take actions faster. You can debug a failure, file a bug, or abort the pipeline. @@ -208,8 +192,8 @@ You can debug a failure, file a bug, or abort the pipeline. > [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) task in a Multi Agent job. > It will be available for Single Agent jobs in a future release. -The view below shows the **in-progress** test summary in a release, reporting the total test count and the number of test failures -at a given point in time. The test failures are available for troubleshooting, creating bug(s), or to take any other appropriate action. +The following example shows the **in-progress** test summary in a release, reporting the total test count and the number of test failures +at a given point in time. The test failures are available for troubleshooting, creating bugs, or to take any other appropriate action. ![In progress summary view](media/review-continuous-test-results-after-build/inprogress-summary-view.png) @@ -227,15 +211,15 @@ As these tests are related, they must be reported together with the overall outc These test results are reported as a summarized test result in the **Tests** tab: * **Rerun failed tests**: The ability to rerun failed tests is available in the latest version of the [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) task. - During a rerun, multiple attempts can be made for a failed test, and each failure could have a different root cause due to the non-deterministic behavior of the test. + During a rerun, multiple attempts can be made for a failed test, and each failure could have a different root cause due to the nondeterministic behavior of the test. Test reports provide a combined view for all the attempts of a rerun, along with the overall test outcome as a summarized unit. - Additionally the [Test Management API(s)](/rest/api/azure/devops/test/results/list) + The [Test Management APIs](/rest/api/azure/devops/test/results/list) now support the ability to publish and query summarized test results. ![Rerun failed tests](media/review-continuous-test-results-after-build/rerun-failed-test.png) * **Data driven tests**: Similar to the rerun of failed tests, all iterations of data driven tests are reported under that test in a summarized view. - The summarized view is also available for ordered tests (**.orderedtest** in Visual Studio). + The summarized view is also available for ordered tests (**`.orderedtest`** in Visual Studio). ![Data driven test](media/review-continuous-test-results-after-build/data-driven-test.png) @@ -248,7 +232,7 @@ These test results are reported as a summarized test result in the **Tests** tab ### View aborted tests Test execution can abort due to several reasons such as bad test code, errors in the source under test, or environmental issues. -Irrespective of the reason for the abort, it is important to be able to diagnose the behavior and identify the root cause. +Irrespective of the reason for the abort, it's important to be able to diagnose the behavior and identify the root cause. The aborted tests and test runs can be viewed alongside the completed runs in the **Tests** tab. ![View stopped tests.](media/review-continuous-test-results-after-build/aborted-test-run.png) @@ -272,8 +256,8 @@ started using Test Reporting. See the [list of runners for which test results are automatically inferred](#inferred_runners_list). -As only limited test metadata is present in such inferred reports, they are limited in features and capabilities. -The following features are not available for inferred test reports: +As only limited test metadata is present in such inferred reports, they're limited in features and capabilities. +The following features aren't available for inferred test reports: * Group the test results by test file, owner, priority, and other fields * Search and filter the test results diff --git a/docs/pipelines/test/test-analytics.md b/docs/pipelines/test/test-analytics.md index ff2e2be4d4b..72ebcf246f9 100644 --- a/docs/pipelines/test/test-analytics.md +++ b/docs/pipelines/test/test-analytics.md @@ -3,11 +3,11 @@ title: Test Analytics description: Get meaningful insights with test analytics in the pipeline ms.assetid: 678DF283-CE38-4CAF-BA74-D331B357F510 ms.topic: conceptual -ms.custom: "continuous-test, seodec18, cross-service" -ms.author: vinojos -author: vinodjo +ms.custom: continuous-test, cross-service +ms.author: jeom +author: raviLiftr ms.date: 06/28/2019 -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" --- # Test Analytics @@ -23,7 +23,7 @@ It helps improve the efficiency of your pipeline by identifying repetitive, high Read the [glossary](./test-glossary.md) to understand test reports terminology. -## Install the Analytics extension if required +## Install the Analytics extension if necessary For more information, see [The Analytics Marketplace extension](../../report/dashboards/analytics-extension.md). @@ -47,7 +47,7 @@ As with build, the summary provides an aggregated view of the test pass rate and ![View trends in release](media/test-analytics/view-in-release.png) -## Test Failures +## Test failures Open a build or release summary to view the top failing tests report. This report provides a granular view of the top failing tests in the pipeline, along with the failure details. @@ -62,7 +62,7 @@ The detailed view contains two sections: ![View pass rate](media/test-analytics/pass-rate.png) - - Failing tests: Provides a distinct count of tests that failed during the specified period. In the example above, 986 test failures originated from 124 tests. + - Failing tests: Provides a distinct count of tests that failed during the specified period. In the previous example, 986 test failures originated from 124 tests. ![View failing tests](media/test-analytics/failing-tests.png) @@ -70,7 +70,7 @@ The detailed view contains two sections: ![View chart](media/test-analytics/chart-view.png) -* **Results**: List of top failed tests based on the total number of failures. Helps to identify problematic tests and lets you drill into a detailed summary of results. +* **Results**: List of top failed tests based on the total number of failures. Helps to identify problematic tests and lets you drill into a detailed summary of results. ![View results.](media/test-analytics/results-view.png) @@ -78,7 +78,7 @@ The detailed view contains two sections: The report view can be organized in several different ways using the **group by** option. Grouping test results can provide deep insights into various aspects of the top failing tests. -In the example below, the test results are grouped based on the [test files](test-glossary.md) they belong to. +In the following example, the test results are grouped based on the [test files](test-glossary.md) they belong to. It shows the test files and their respective contribution towards the total of test failures, during the specified period to help you easily identify and prioritize your next steps. Additionally, for each test file, it shows the tests that contribute to these failures. @@ -87,9 +87,7 @@ Additionally, for each test file, it shows the tests that contribute to these fa ### Drill down to individual tests -After you have identified one or more tests in the **Details** section, select the individual test you want to analyze. -This provides a drill-down view of the selected test with a stacked chart of various outcomes such as passed or -failed instances of the test, for each day in the specified period. +After you identify one or more tests in the **Details** section, select the individual test you want to analyze. This action provides a drill-down view of the selected test with a stacked chart of various outcomes such as passed or failed instances of the test, for each day in the specified period. This view helps you infer hidden patterns and take actions accordingly. ![Drill down for test](media/test-analytics/drill-down-test.png) @@ -107,19 +105,19 @@ to see failure details in context. ### Infer hidden patterns -When looking at the test failures for a single instance of execution, it is often difficult to infer any pattern. -In the example below, the test failures occurred during a specific period, and knowing this can help narrow down the scope of investigation. +When looking at the test failures for a single instance of execution, it's often difficult to infer any pattern. +In the following example, the test failures occurred during a specific period, which helps narrow down the scope of investigation. ![Example of test failure pattern.](media/test-analytics/infer-pattern.png) -Another example is tests that exhibit non-deterministic behavior (often referred to as [flaky tests](test-glossary.md)). -Looking at an individual instance of test execution may not provide any meaningful insights into the behavior. +Another example is tests that exhibit nondeterministic behavior (often referred to as [flaky tests](test-glossary.md)). +Looking at an individual instance of test execution might not provide any meaningful insights into the behavior. However, observing test execution trends for a period can help infer hidden patterns, and help you resolve the failures. ## Report information source The source of information for test analytics is the set of [published test results](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) for the build or release pipeline. -These result are accrued over a period of time, and form the basis of the rich insights that test analytics provides. +These results are accrued over a period of time, and form the basis of the rich insights that test analytics provides. [!INCLUDE [help-and-support-footer](includes/help-and-support-footer.md)] diff --git a/docs/pipelines/test/test-glossary.md b/docs/pipelines/test/test-glossary.md index 322aba19e21..8586df216d8 100644 --- a/docs/pipelines/test/test-glossary.md +++ b/docs/pipelines/test/test-glossary.md @@ -3,9 +3,9 @@ title: About pipeline tests description: Understand terms used in test report and test analytics ms.assetid: 7C6E8651-FD90-40EB-8E0F-1AE48360B5DB ms.topic: conceptual -ms.custom: "continuous-test, seodec18" -ms.author: vinojos -author: vinodjo +ms.custom: continuous-test +ms.author: jeom +author: raviLiftr ms.date: 12/07/2018 monikerRange: '<= azure-devops' --- @@ -14,13 +14,9 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -This article describes commonly used terms used in pipeline [test report](review-continuous-test-results-after-build.md) and [test analytics](test-analytics.md). +This article describes commonly used terms used in pipeline [test report](review-continuous-test-results-after-build.md) and [test analytics](test-analytics.md), and provides tips for better testing in Azure Pipelines. -::: moniker range="tfs-2018" -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end | Term | Definition | | ---- | ---------- | @@ -42,4 +38,10 @@ This article describes commonly used terms used in pipeline [test report](review | **Test run** | Logical grouping of test results based on:
      - **Test executed using built-in tasks**: All tests executed using a single task such as [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2), [Ant](/azure/devops/pipelines/tasks/reference/ant-v1), [Maven](/azure/devops/pipelines/tasks/reference/maven-v3), [Gulp](/azure/devops/pipelines/tasks/reference/gulp-v1), [Grunt](/azure/devops/pipelines/tasks/reference/grunt-v0) or [Xcode](/azure/devops/pipelines/tasks/reference/xcode-v5) will be reported under a single test run
      - **Results published using [Publish Test Results](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) task**: Provides an option to group all test results from one or more test results files into a single run, or individual runs per file
      - **Tests results published using API(s)**: [API(s)](/rest/api/azure/devops/test/runs) provide the flexibility to create test runs and organize test results for each run as required. | | **Traceability** | Ability to [trace](requirements-traceability.md) forward or backward to a requirement, bug, or source code from a test result. | -[!INCLUDE [help-and-support-footer](includes/help-and-support-footer.md)] \ No newline at end of file +## Best practices + +Ensuring application reliability requires [comprehensive testing](/devops/develop/shift-left-make-testing-fast-reliable) in Azure Pipelines, with unit tests and integration tests being essential. Testing integrations in cloud environments, particularly [serverless applications](https://azure.microsoft.com/solutions/serverless), poses challenges due to distributed architectures, misconfigured [IAM permissions](/entra/fundamentals/introduction-identity-access-management), and service-to-service integration issues. + +To address this, consider running your code locally while interacting with genuine Azure services, facilitating realistic tests and enabling debugger tools suitable for automated testing. Implementing this approach requires provisioning ephemeral Azure resources. Ideally, create [separate accounts for each environment](/azure/devops/user-guide/plan-your-azure-devops-org-structure); alternatively, dynamic provisioning within Azure pipelines is possible, although this increases execution time and necessitates careful resource decommissioning planning. To minimize naming conflicts, avoid explicit resource naming unless necessary and include environment names in resource names. + +[!INCLUDE [help-and-support-footer](includes/help-and-support-footer.md)] diff --git a/docs/pipelines/test/test-impact-analysis.md b/docs/pipelines/test/test-impact-analysis.md index 5ee5344ae7e..14c6da86c83 100644 --- a/docs/pipelines/test/test-impact-analysis.md +++ b/docs/pipelines/test/test-impact-analysis.md @@ -1,11 +1,11 @@ --- title: Use Test Impact Analysis -description: Speed up testing by using Test Impact Analysis (TIA) in Azure Pipelines or TFS with a build or release pipeline +description: Speed up testing by using Test Impact Analysis (TIA) in Azure Pipelines or TFS with a build or release pipeline. ms.assetid: BBDD071F-4017-4AF0-AB59-71F8FEFF1E37 ms.topic: conceptual -ms.custom: continuous-test, seodec18, cross-service -ms.author: shashban -author: shashban +ms.custom: continuous-test, cross-service +ms.author: jeom +author: raviLiftr ms.date: 12/07/2018 monikerRange: '<= azure-devops' --- @@ -14,48 +14,34 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range="tfs-2018" +Continuous Integration (CI) is a key practice in the industry. Integrations are frequent, and verified with an automated build that runs regression tests to detect integration errors as soon as possible. But, as the code base grows and matures, its regression test suite tends to grow as well - to the extent that running a full regression test might require hours. This testing slows down the frequency of integrations, and ultimately defeats the purpose of continuous integration. -> [!NOTE] -> Applies only to TFS 2017 Update 1 and later, and Visual Studio 2015 Update 3 and later. - -::: moniker-end - -Continuous Integration (CI) is a key practice in the industry. -Integrations are frequent, and verified with an automated build that runs regression tests to detect integration errors as soon as possible. -However, as the codebase grows and matures, its regression test suite tends to grow as well - to the extent that running a full regression test might require hours. -This slows down the frequency of integrations, and ultimately defeats the purpose of continuous integration. -In order to have a CI pipeline that completes quickly, some teams defer the execution of their longer running tests to a separate stage in the pipeline. -However, this only serves to further defeat continuous integration. +To have a CI pipeline that completes quickly, some teams defer the execution of their longer running tests to a separate stage in the pipeline. But, this action only serves to further defeat continuous integration. Instead, [enable Test Impact Analysis (TIA)](#enabletia) when using the [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) task in a build pipeline. TIA performs incremental validation by automatic test selection. -It will automatically select only the subset of tests required to validate the code being committed. -For a given code commit entering the CI/CD pipeline, TIA will select and run only the relevant tests required to validate that commit. -Therefore, that test run will complete more quickly, if there is a failure you will get to know about it sooner, and because it is all scoped by relevance, analysis will be faster as well. +It automatically selects only the subset of tests required to validate the code being committed. +For a given code commit entering the CI/CD pipeline, TIA selects and runs only the relevant tests required to validate that commit. +Therefore, that test run completes more quickly, if there is a failure you get alerted sooner, and because it's all scoped by relevance, analysis is faster, too. ![Comparison of test times when using TIA](media/test-impact-analysis/tia-chart.png) Test Impact Analysis has: * **A robust test selection mechanism**. It includes existing impacted tests, previously failing tests, and newly added tests. -* **Safe fallback**. For commits and scenarios that TIA cannot understand, it will fall back to running all tests. TIA is currently scoped to only managed code, and single machine topology. So, for example, if the code commit contains changes to HTML or CSS files, it cannot reason about them and will fall back to running all tests. +* **Safe fallback**. For commits and scenarios that TIA can't understand, it falls back to running all tests. TIA is currently scoped to only managed code, and single machine topology. So, for example, if the code commit contains changes to HTML or CSS files, it can't reason about them and falls back to running all tests. * **Configurable overrides**. You can run all tests at a configured periodicity. However, be aware of the following caveats when using TIA with Visual Studio 2015: -* **Running tests in parallel**. In this case, tests will run serially. -* **Running tests with code coverage enabled**. In this case, code coverage data will not get collected. - -::: moniker range="tfs-2018" +* **Running tests in parallel**. In this case, tests run serially. +* **Running tests with code coverage enabled**. In this case, code coverage data doesn't get collected. -[!INCLUDE [temp](../includes/concept-rename-note.md)] -::: moniker-end ## Test Impact Analysis supported scenarios -At present, TIA is supported for: + Test Impact Analysis (TIA) is supported for the following scenarios: * TFS 2017 Update 1 onwards, and Azure Pipelines * Version 2.* of the [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) task in the build pipeline @@ -69,7 +55,7 @@ At present, TIA is supported for: * Single machine topology. Tests and app (SUT) must be running on the same machine. * Managed code (any .NET Framework app, any .NET service) -At present, TIA is **not** supported for: +TIA is **not** supported for the following scenarios: * Multi-machine topology (where the test is exercising an app deployed to a different machine) * Data driven tests @@ -85,12 +71,12 @@ At present, TIA is **not** supported for: TIA is supported through Version 2.* of the [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) task. If your app is a single tier application, all you need to do is to check **Run only impacted tests** in the task UI. -The Test Impact data collector is automatically configured. No additional steps are required. +The Test Impact data collector is automatically configured. No further steps are required. ![Enable TIA in the VS Test task UI](media/test-impact-analysis/task-params.png) If your application interacts with a service in the context of IIS, you must also configure the Test Impact data collector to run in the context of IIS by using a **.runsettings** file. -Here is a sample that creates this configuration: +The following sample creates this configuration: ```xml @@ -132,12 +118,12 @@ TIA is integrated into existing test reporting at both the summary and details l You can influence the way that tests are either included or ignored during a test run: * **Through the VSTest task UI**. TIA can be conditioned to run all tests at a configured periodicity. Setting this option is recommended, and is the means to regulate test selection. -* **By setting a build variable**. Even after TIA has been enabled in the VSTest task, it can be disabled for a specific build by setting the variable **DisableTestImpactAnalysis** to **true**. This override will force TIA to run all tests for that build. In subsequent builds, TIA will go back to optimized test selection. +* **By setting a build variable**. Even after TIA is enabled in the VSTest task, you can disable it for a specific build by setting the variable **DisableTestImpactAnalysis** to **true**. This override forces TIA to run all tests for that build. In subsequent builds, TIA goes back to optimized test selection. -When TIA opens a commit and sees an unknown file type, it falls back to running all tests. While this is good from a safety perspective, tuning this behavior might be useful in some cases. For example: +When TIA opens a commit and sees an unknown file type, it falls back to running all tests. While this action is good from a safety perspective, tuning this behavior might be useful in some cases. For example: -* Set the **TI\_IncludePathFilters** variable to specific paths to include only these paths in a repository for which you want TIA to apply. This is useful when teams use a shared repository. Setting this variable disables TIA for all other paths not included in the setting. -* Set the **TIA\_IncludePathFilters** variable to specify file types that do not influence the outcome of tests and for which changes should be ignored. For example, to ignore changes to .csproj files set the variable to the value **!\*\*\\\*.csproj**. +* Set the **TI\_IncludePathFilters** variable to specific paths to include only these paths in a repository for which you want TIA to apply. This action is useful when teams use a shared repository. Setting this variable disables TIA for all other paths not included in the setting. +* Set the **TIA\_IncludePathFilters** variable to specify file types that don't influence the outcome of tests and for which changes should be ignored. For example, to ignore changes to.csproj files set the variable to the value: **`!\*\*\\\*.csproj`**. > Use the [minimatch pattern](../tasks/file-matching-patterns.md) when setting variables, and separate multiple items with a semicolon. @@ -161,8 +147,8 @@ TestMethod2 dependency3 ``` -TIA can generate such a dependencies map for managed code execution. -Where such dependencies reside in **.cs** and **.vb** files, TIA can automatically watch for commits into such files and then run tests that had these source files in their list of dependencies. +TIA can generate a dependency map for managed code execution. +Where such dependencies reside in **`.cs`** and **`.vb`** files, TIA can automatically watch for commits into such files and then run tests that had these source files in their list of dependencies. You can extend the scope of TIA by explicitly providing the dependencies map as an XML file. For example, you might want to support code in other languages such as JavaScript or C++, @@ -182,4 +168,4 @@ For an example of the XML file format, see [TIA custom dependency mapping](https * [TIA advanced configuration](https://blogs.msdn.microsoft.com/devops/2017/06/13/accelerated-continuous-testing-with-test-impact-analysis-part-3/) * [TIA custom dependency mapping](https://blogs.msdn.microsoft.com/devops/2017/08/04/accelerated-continuous-testing-with-test-impact-analysis-part-4/) -[!INCLUDE [help-and-support-footer](includes/help-and-support-footer.md)] \ No newline at end of file +[!INCLUDE [help-and-support-footer](includes/help-and-support-footer.md)] diff --git a/docs/pipelines/test/ui-testing-considerations.md b/docs/pipelines/test/ui-testing-considerations.md index 231beefa360..73f2354b16d 100644 --- a/docs/pipelines/test/ui-testing-considerations.md +++ b/docs/pipelines/test/ui-testing-considerations.md @@ -1,12 +1,10 @@ --- title: Configure for UI testing -description: Continuous testing. Things to consider when running UI tests and FAQ. +description: Continuous testing. Things to consider when running UI tests and FAQ. ms.assetid: 1B7C890E-FB67-4BEF-A48E-20C9453BD54A -ms.topic: conceptual -ms.custom: "continuous-test, seodec18" -ms.author: shashban -author: shashban -ms.date: 12/07/2018 +ms.topic: conceptual +ms.custom: continuous-test +ms.date: 04/25/2024 monikerRange: '<= azure-devops' --- @@ -15,17 +13,10 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] When running automated tests in the CI/CD pipeline, you may need a special configuration -in order to run UI tests such as Selenium, Appium or Coded UI tests. This topic describes +in order to run UI tests such as Selenium, Appium, or Coded UI tests. This article describes the typical considerations for running UI tests. -::: moniker range="tfs-2018" -> [!NOTE] -> Applies only to TFS 2017 Update 1 and later. - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end ## Prerequisites @@ -36,12 +27,12 @@ Familiarize yourself with [agents](../agents/agents.md) and [deploying an agent When running Selenium tests for a web app, you can launch the browser in two ways: 1. **Headless mode**. In this mode, the browser runs as normal but without any UI - components being visible. While this mode is obviously not useful for browsing the web, - it is useful for running automated tests in an unattended manner in a CI/CD pipeline. + components being visible. While this mode is not useful for browsing the web, + it's useful for running automated tests in an unattended manner in a CI/CD pipeline. [Chrome](https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md) and [Firefox](https://developer.mozilla.org/docs/Mozilla/Firefox) browsers can be run in headless mode. - This mode generally consumes less resources on the machine because the UI is not + This mode generally consumes less resources on the machine because the UI isn't rendered and tests run faster. As a result, potentially more tests can be run in parallel on the same machine to reduce the total test execution time. @@ -53,7 +44,7 @@ When running Selenium tests for a web app, you can launch the browser in two way 1. **Visible UI mode**. In this mode, the browser runs normally and the UI components are visible. When running tests in this mode on Windows, [special configuration of the agents](#visible-ui-mode) is required. -If you are running UI tests for a desktop application, such as +If you're running UI tests for a desktop application, such as [Appium tests using WinAppDriver](https://github.com/Microsoft/WinAppDriver) or Coded UI tests, a [special configuration of the agents](#visible-ui-mode) is required. @@ -75,36 +66,38 @@ A special configuration is required for agents to run UI tests in visible UI mod ### Visible UI testing using Microsoft-hosted agents -Microsoft-hosted agents are pre-configured for UI testing and UI tests for both -web apps and desktop apps. Microsoft-hosted agents are also -pre-configured with [popular browsers and matching web-driver versions](https://github.com/actions/runner-images/blob/main/images/win/Windows2022-Readme.md) +Visible UI testing in not supported in Microsoft-hosted agents. The test fails with error message "element not interactable". Microsoft-hosted agents support headless browser testing. + +### Headless mode UI testing using Microsoft-hosted agents +Microsoft-hosted agents are preconfigured for UI testing and UI tests for web apps. Microsoft-hosted agents are also +preconfigured with [popular browsers and matching web-driver versions](https://github.com/actions/runner-images/blob/main/images/windows/Windows2022-Readme.md) that can be used for running Selenium tests. The browsers and corresponding web-drivers are updated on a periodic basis. -To learn more about running Selenium tests, see [UI test with Selenium](continuous-test-selenium.md) +To learn more about running Selenium tests, see [UI test with Selenium](continuous-test-selenium.md). ### Visible UI testing using self-hosted Windows agents Agents that are configured to run as service can run Selenium tests only with headless browsers. -If you are not using a headless browser, or if you are running UI tests for desktop apps, -Windows agents _must_ be configured to run as an interactive process with auto-logon enabled. +If you aren't using a headless browser, or if you're running UI tests for desktop apps, +Windows agents _must_ be configured to run as an interactive process with autologon enabled. When configuring agents, select 'No' when prompted to run as a service. -Subsequent steps then allow you to configure the agent with auto-logon. +Subsequent steps then allow you to configure the agent with autologon. When your UI tests run, applications and browsers are launched in the -context of the user specified in the auto-logon settings. +context of the user specified in the autologon settings. If you use Remote Desktop to access the computer on which an agent is running -with auto-logon, simply disconnecting the Remote Desktop causes the computer -to be locked and any UI tests that run on this agent may fail. -To avoid this, use the [tscon](/windows-server/administration/windows-commands/tscon) +with autologon, simply disconnecting the Remote Desktop causes the computer +to be locked and any UI tests that run on this agent could fail. +To avoid failure, use the [tscon](/windows-server/administration/windows-commands/tscon) command on the remote computer to disconnect from Remote Desktop. For example: `%windir%\System32\tscon.exe 1 /dest:console` In this example, the number '1' is the ID of the remote desktop session. -This number may change between remote sessions, but can be viewed in Task Manager. +This number could change between remote sessions, but can be viewed in Task Manager. Alternatively, to automate finding the current session ID, create a batch file containing the following code: @@ -119,26 +112,26 @@ Running the batch file from this shortcut disconnects from the remote desktop bu ## Provisioning agents in Azure VMs for UI testing -If you are provisioning virtual machines (VMs) on Azure, agent configuration for UI testing is available +If you're provisioning virtual machines (VMs) on Azure, agent configuration for UI testing is available through the [Agent artifact for DevTest Labs](https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-vsts-build-agent). ![agentArtifactDTL](media/agentartifact-dtl.png) ## Setting screen resolution -Before running UI tests you may need to adjust the screen resolution so that apps render correctly. +Before running UI tests, you might need to adjust the screen resolution so that apps render correctly. For this, a [screen resolution utility task](https://marketplace.visualstudio.com/items?itemName=ms-autotest.screen-resolution-utility-task) is available from Marketplace. Use this task in your pipeline to set the screen resolution to a value that is supported by the agent machine. By default, this utility sets the resolution to the optimal value supported by the agent machine. If you encounter failures using the screen resolution task, ensure that the agent is configured -to run with auto-logon enabled and that all remote desktop sessions are safely disconnected using +to run with autologon enabled and that all remote desktop sessions are safely disconnected using the **tscon** command as described above. > [!NOTE] > The screen resolution utility task runs on the unified build/release/test agent, and cannot be used with -> the deprecated [Run Functional Tests task](/azure/devops/pipelines/tasks/reference/run-visual-studio-testsusing-test-agent-v1). +> the deprecated [Run Functional Tests task](/azure/devops/pipelines/tasks/reference/run-visual-studio-testsusing-test-agent-v1). The resolution util task also does not work for Azure virtual machines. ## Troubleshooting failures in UI tests @@ -173,15 +166,15 @@ Use the `TestContext.AddTestAttachment()` method available in NUnit 3.7 or highe --- If you use the [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) -to publish results, test result attachments can only be published if you are using +to publish results, test result attachments can only be published if you're using the VSTest (TRX) results format or the [NUnit 3.0 results](https://github.com/nunit/docs/wiki/Test-Result-XML-Format) format. -Result attachments cannot be published if you use JUnit or xUnit test results. This is because these test result formats do not have a formal definition for attachments in the results schema. You can use one of the below approaches to publish test attachments instead. +Result attachments can't be published if you use JUnit or xUnit test results. This is because these test result formats don't have a formal definition for attachments in the results schema. You can use one of the below approaches to publish test attachments instead. -* If you are running tests in the build (CI) pipeline, you can use the - [Copy and Publish Build Artifacts](/azure/devops/pipelines/tasks/reference/copy-publish-build-artifacts-v1) task to publish any additional files created in your tests. - These will appear in the **Artifacts** page of your build summary. +* If you're running tests in the build (CI) pipeline, you can use the + [Copy and Publish Build Artifacts](/azure/devops/pipelines/tasks/reference/copy-publish-build-artifacts-v1) task to publish any more files created in your tests. + These appear in the **Artifacts** page of your build summary. * Use the REST APIs to publish the necessary attachments. Code samples can be found in [this GitHub repository](https://github.com/ManojBableshwar/VstsTestRestApiSamples/blob/master/PublishResultsFromCsvWithAttachments/PublishResultsFromCsvWithAttachments.cs). diff --git a/docs/pipelines/toc.yml b/docs/pipelines/toc.yml index 61dc95da80f..ba591579c20 100644 --- a/docs/pipelines/toc.yml +++ b/docs/pipelines/toc.yml @@ -1,756 +1,743 @@ - name: Azure Pipelines href: index.yml -- name: What is Azure Pipelines? - href: get-started/what-is-azure-pipelines.md -- name: Use Azure Pipelines - href: get-started/pipelines-get-started.md - name: Get started items: - - name: Sign up for Azure Pipelines - href: get-started/pipelines-sign-up.md - - name: Create your first pipeline - href: create-first-pipeline.md - displayName: status badge, get started, first pipeline, import from github - - name: Customize your pipeline - href: customize-pipeline.md - displayName: azure-pipelines.yml, change build platform, add steps, multiple platforms, multiple versions, customize triggers + - name: What is Azure Pipelines? + href: get-started/what-is-azure-pipelines.md + - name: Sign up for Azure Pipelines + href: get-started/pipelines-sign-up.md + - name: Create your first pipeline + displayName: status badge, get started, first pipeline, import from github + href: create-first-pipeline.md + - name: Customize your pipeline + displayName: azure-pipelines.yml, change build platform, add steps, multiple platforms, multiple versions, customize triggers + href: customize-pipeline.md + - name: Build a pipeline with stages + displayName: multi-stage pipeline, stages, design pipeline, build, test, deploy + href: process/run-stages.md - name: Pipeline basics items: - - name: Key concepts - href: get-started/key-pipelines-concepts.md - - name: YAML pipeline editor - href: get-started/yaml-pipeline-editor.md - - name: Repositories - items: - - name: Supported repositories - href: repos/index.md - displayName: supported repository types, version control, azure repos git, tfvc, github, bitbucket, subversion, github enterprise, ghe - - name: Azure Repos Git - href: repos/azure-repos-git.md - displayName: ci, pr, pull request, triggers, self, batching, batched CI, branch policy, access token, public project, private project, skip ci, no_ci, build.reason, path filter, branch filter, tag trigger, forks, badge, prefergitfrompath, checkout, get sources, clean, label sources, tag sources, checkout path, submodules, shallow fetch, exit code 128 - - name: GitHub - href: repos/github.md - displayName: ci, pr, pull request, triggers, self, batching, batched CI, github app, oauth, pat, open source, public project, private project, skip ci, no_ci, build.reason, path filter, branch filter, tag trigger, forks, badge, prefergitfrompath, checkout, clone, fetch, get sources, checks, clean, label sources, tag sources, checkout path, submodules, shallow fetch - - name: GitHub Enterprise Server - href: repos/github-enterprise.md - displayName: github enterprise, ci, pr, pull request, triggers, oauth, pat, checkout, firewall, allow list, exception, rule, other git, external git, service connection, classic, yaml, ip address range - - name: Pipeline options for Git repositories - href: repos/pipeline-options-for-git.md - - name: Bitbucket Cloud - href: repos/bitbucket.md - displayName: ci, pr, pull request, triggers, self, batching, batched CI, oauth, public project, private project, skip ci, no_ci, build.reason, path filter, branch filter, badge, prefergitfrompath, checkout, clone, fetch, get sources, clean, label sources, tag sources, checkout path, submodules, shallow fetch - - name: Bitbucket Server - href: repos/on-premises-bitbucket.md - displayName: ci, triggers, checkout, firewall, allow list, exception, rule, other git, external git, service connection, ip address range - - name: TFVC - href: repos/tfvc.md - displayName: tfvc, version control, workspace, ci, gated, checkin, mappings, scroch, triggers, path filter, clean - - name: Subversion - href: repos/subversion.md - displayName: ci, triggers, checkout, firewall, allow list, exception, rule, service connection, ip address range - - name: Multiple repositories - href: repos/multi-repo-checkout.md - displayName: ci, pr, pull request, triggers, checkout, branch policy, path filter, branch filter, tag trigger, multiple repos, multi-repo, multi-checkout, multi-trigger, self - - name: Build history - href: build/history.md - - name: Triggers - items: - - name: Types of triggers - href: build/triggers.md - displayName: ci, pr, pull request, triggers, azure repos git, github, bitbucket, tfvc, release triggers, scheduled, pipeline triggers, build completion triggers, comment triggers, CD triggers, stage triggers, YAML triggers - - name: Scheduled triggers - href: process/scheduled-triggers.md - displayName: schedule, cron, daily, weekly, monthly, nightly, scheduled runs, crontab - - name: Pipeline completion triggers - href: process/pipeline-triggers.md - displayName: build completion, completion trigger - - name: Build completion triggers (classic) - href: process/pipeline-triggers-classic.md - displayName: build completion, completion trigger - - name: Release triggers (classic) - href: release/triggers.md - displayName: release trigger, CD trigger, stage trigger, environment trigger, deploy PR, scheduled trigger, schedule - - name: Tasks & templates - items: - - name: Templates, parameters, & expressions - items: - - name: Templates - href: process/templates.md - displayName: parameters, passing, job reuse, stage reuse, variable reuse, expressions, context, conditional insertion, iterative insertion, escape a value - - name: Template parameters - href: process/template-parameters.md - - name: Template expressions - href: process/template-expressions.md - - name: Task types & usage - href: process/tasks.md - displayName: custom tasks, task versions, task control options, conditions, task tool installers, build tool installers - - name: Task groups (classic) - href: library/task-groups.md - - name: Add a custom task extension - href: ../extend/develop/add-build-task.md?toc=/azure/devops/pipelines/toc.json - - name: Upload tasks to project collection - href: ../extend/develop/upload-tasks.md?toc=/azure/devops/pipelines/toc.json - - name: Jobs & stages - items: - - name: Specify jobs in your pipeline - href: process/phases.md - displayName: phases, stages, job type, dependencies, conditions, timeouts, multi-configuration, slicing, job variables, artifact download, oauth token - - name: Define container jobs - href: process/container-phases.md - - name: Add stages, dependencies & conditions - href: process/stages.md - displayName: stage, dependencies, conditions, queuing policies, approvals - - name: Deployment jobs - href: process/deployment-jobs.md - displayName: pipeline decorator, deployment strategy, lifecycle hooks, rolling, canary - - name: Author a custom pipeline decorator - href: ../extend/develop/add-pipeline-decorator.md?toc=/azure/devops/pipelines/toc.json - - name: Pipeline decorator context - href: ../extend/develop/pipeline-decorator-context.md?toc=/azure/devops/pipelines/toc.json - - name: Specify conditions - href: process/conditions.md - - name: Specify demands - href: process/demands.md - displayName: task demands, manually entered demands, capabilities - - name: Library, variables & secure files - items: - - name: Library & shared resources - href: library/index.md - displayName: security roles, variables, variable groups, secure files - - name: Define variables - href: process/variables.md - displayName: secrets, expressions, queue time, expansion,system, environment variables, macro syntax, template syntax - - name: Use variables in variable group - href: scripts/cli/pipeline-variable-group-secret-nonsecret-variables.md - displayName: create pipeline, manage pipeline, monitor pipeline, secret variable - - name: Use predefined variables - href: build/variables.md - displayName: build variables, agent variables, pipeline variables, system variables - - name: Set variables in scripts - href: process/set-variables-scripts.md - displayName: variables, task, setname, scripts - - name: Set secret variables - href: process/set-secret-variables.md - displayName: secret variables - - name: Use runtime parameters - href: process/runtime-parameters.md - displayName: parameters in pipelines, conditionals, loop, data types - - name: Use classic process parameters - href: process/parameters.md - - name: Use classic release and artifacts variables - href: release/variables.md - displayName: identity, system, build, agent, deployment job, System.AccessToken, System.Debug - - name: Use secrets from Azure Key Vault - href: release/azure-key-vault.md - displayName: secrets, access policies, key vault - - name: Use Azure Key Vault in your YAML Pipeline - href: release/key-vault-in-own-project.md - displayName: key vault, secrets, YAML pipeline - - name: Approvals, checks, & gates - items: - - name: Release approval and gates overview - href: release/approvals/index.md - - name: Define approvals & checks - href: process/approvals.md - displayName: approvals, checks - - name: Invoke Azure Function / REST API checks - href: process/invoke-checks.md - displayName: azure function, checks - - name: Define a gate - href: release/approvals/gates.md - - name: Use approvals and gates - href: release/deploy-using-approvals.md - - name: Deployment control using approvals - href: release/approvals/approvals.md - - name: Pipeline runs - items: - - name: Pipeline run sequence - href: process/runs.md - displayName: process the pipeline, process pipeline, request an agent, request agent, pool requests, step, timeouts, disconnects - - name: Job access tokens - href: process/access-tokens.md - displayName: job access token, identity, build service account, project build service account, collection build service account, access token, build service - - name: Information pipeline runs - href: process/information-run.md - displayName: information run - - name: Pipeline reports - items: - - name: View pipeline reports - href: reports/pipelinereport.md - - name: Add widgets to a dashboard - href: ../report/dashboards/add-widget-to-dashboard.md?toc=/azure/devops/pipelines/toc.json - - name: Test Results Trend (Advanced) - href: ../report/dashboards/analytics-widgets.md?toc=/azure/devops/pipelines/toc.json#test-results-trend-advanced - - name: Manage pipelines with Azure CLI - href: get-started/manage-pipelines-with-azure-cli.md - - name: Clone or import a pipeline - href: ./get-started/clone-import-pipeline.md - displayName: export, copy - - name: Configure pipelines to support work tracking - href: integrations/configure-pipelines-work-tracking.md - - name: Pipeline default branch - href: process/pipeline-default-branch.md - - name: DevOps Starter - href: /azure/devops-project/overview -- name: Ecosystems & integration - items: - - name: Ecosystem support - href: ecosystems/ecosystems.md - displayName: language, platform - - name: .NET Core - href: ecosystems/dotnet-core.md - displayName: dotnet, DotNetCoreInstaller, csproj, DotNetCoreCLI, msbuild, DotNetCore - - name: .NET Framework - href: apps/aspnet/build-aspnet-4.md - displayName: ASP, ASPNET, web - - name: JavaScript quickstart - href: ecosystems/javascript.md - displayName: node, node.js, nodetool, npm, yarn, react, babel, typescript, tsc, mocha, jasmine, jest, karma, ava, junit, cobertura, protractor, phantomjs, webpack, angular, react, vue, gulp, grunt - - name: Customize JavaScript - href: ecosystems/customize-javascript.md - displayName: configure javasript, node, configure node.js, nodetool, npm, yarn, react, babel, typescript, tsc, mocha, jasmine, jest, karma, ava, junit, cobertura, protractor, phantomjs, webpack, angular, react, vue, gulp, grunt - - name: Python quickstart - href: ecosystems/python.md - displayName: flake, python - - name: Customize Python - href: ecosystems/customize-python.md - displayName: anaconda, PyPI, pip , setuptools, wheel, conda, flake8, pytest, junit, cobertura, tox, twine - - name: Python to web app - href: ecosystems/python-webapp.md - displayName: django, webapp - - name: Anaconda - href: ecosystems/anaconda.md - displayName: data science, python, miniconda, conda - - name: C/C++ - href: apps/windows/cpp.md - - name: Java - items: - - name: Java apps - href: ecosystems/java.md - displayName: maven, goals, gradle, ant - - name: Java to web App - href: ecosystems/java-webapp.md - - name: Java to web app with MicroProfile - href: /azure/java/microprofile/cicd-microprofile?toc=/azure/devops/pipelines/toc.json - - name: Android - href: ecosystems/android.md - displayName: android sdk, xamarin, android sdk platform tools - - name: Go - href: ecosystems/go.md - displayName: workspace, gopath, goroot, go get, dep, dep ensure - - name: PHP - href: ecosystems/php.md - displayName: php, phpunit - - name: Ruby - href: ecosystems/ruby.md - displayName: rails, bundler, rake, simplecov, cobertura - - name: Xamarin - href: ecosystems/xamarin.md - displayName: xamarin.android, xamarin.ios, macOS, AppStore, Xamarin SDK - - name: Xcode - href: ecosystems/xcode.md - displayName: app certificate, test flight - - name: GitHub Actions - href: ecosystems/github-actions.md - displayName: github, pipelines action -- name: Build apps + - name: Key concepts + href: get-started/key-pipelines-concepts.md + - name: Pipeline run sequence + displayName: process the pipeline, process pipeline, request an agent, request agent, pool requests, step, timeouts, disconnects + href: process/runs.md + - name: YAML vs Classic Pipelines + href: get-started/pipelines-get-started.md + - name: YAML pipeline editor + href: get-started/yaml-pipeline-editor.md + - name: Pipeline default branch + href: process/pipeline-default-branch.md + - name: Clone or import a pipeline + displayName: export, copy + href: ./get-started/clone-import-pipeline.md + - name: Manage pipelines with Azure CLI + href: get-started/manage-pipelines-with-azure-cli.md + - name: Configure pipelines to support work tracking + href: integrations/configure-pipelines-work-tracking.md + - name: Informational runs + displayName: information run + href: process/information-run.md + - name: View pipeline history (Classic) + href: release/history.md +- name: Pipeline structure & logic items: - - name: Build multiple branches - href: build/ci-build-git.md - displayName: build, pipelines build, multiple branches - - name: Build on multiple platforms - href: get-started-multiplatform.md - displayName: platforms, multiplaform - - name: Publish Pipeline Artifacts - href: publish-pipeline-artifact.md - displayName: publish, artifacts + - name: Repositories + items: + - name: Supported repositories + displayName: supported repository types, version control, azure repos git, tfvc, github, bitbucket, subversion, github enterprise, ghe + href: repos/index.md + - name: Azure Repos Git + displayName: ci, pr, pull request, triggers, self, batching, batched CI, branch policy, access token, public project, private project, skip ci, no_ci, build.reason, path filter, branch filter, tag trigger, forks, badge, prefergitfrompath, checkout, get sources, clean, label sources, tag sources, checkout path, submodules, shallow fetch, exit code 128 + href: repos/azure-repos-git.md + - name: GitHub + displayName: ci, pr, pull request, triggers, self, batching, batched CI, github app, oauth, pat, open source, public project, private project, skip ci, no_ci, build.reason, path filter, branch filter, tag trigger, forks, badge, prefergitfrompath, checkout, clone, fetch, get sources, checks, clean, label sources, tag sources, checkout path, submodules, shallow fetch + href: repos/github.md + - name: GitHub Enterprise Server + displayName: github enterprise, ci, pr, pull request, triggers, oauth, pat, checkout, firewall, allow list, exception, rule, other git, external git, service connection, classic, yaml, ip address range + href: repos/github-enterprise.md + - name: Pipeline options for Git repositories + href: repos/pipeline-options-for-git.md + - name: Bitbucket Cloud + displayName: ci, pr, pull request, triggers, self, batching, batched CI, oauth, public project, private project, skip ci, no_ci, build.reason, path filter, branch filter, badge, prefergitfrompath, checkout, clone, fetch, get sources, clean, label sources, tag sources, checkout path, submodules, shallow fetch + href: repos/bitbucket.md + - name: Bitbucket Server + displayName: ci, triggers, checkout, firewall, allow list, exception, rule, other git, external git, service connection, ip address range + href: repos/on-premises-bitbucket.md + - name: TFVC + displayName: tfvc, version control, workspace, ci, gated, checkin, mappings, scroch, triggers, path filter, clean + href: repos/tfvc.md + - name: Subversion + displayName: ci, triggers, checkout, firewall, allow list, exception, rule, service connection, ip address range + href: repos/subversion.md + - name: Multiple repositories + displayName: ci, pr, pull request, triggers, checkout, branch policy, path filter, branch filter, tag trigger, multiple repos, multi-repo, multi-checkout, multi-trigger, self + href: repos/multi-repo-checkout.md + - name: Stages, jobs, & steps + items: + - name: Specify jobs in your pipeline + displayName: phases, stages, job type, dependencies, conditions, timeouts, multi-configuration, slicing, job variables, artifact download, oauth token + href: process/phases.md + - name: Define container jobs + href: process/container-phases.md - name: Use service containers - href: process/service-containers.md displayName: containers, service containers - - name: Cross-platform scripts - href: scripts/cross-platform-scripting.md - displayName: cross platform, scripts + href: process/service-containers.md + - name: Add stages, dependencies & conditions + displayName: stage, dependencies, conditions, queuing policies, approvals + href: process/stages.md + - name: Deployment jobs + displayName: pipeline decorator, deployment strategy, lifecycle hooks, rolling, canary + href: process/deployment-jobs.md + - name: Author a custom pipeline decorator + href: ../extend/develop/add-pipeline-decorator.md?toc=/azure/devops/pipelines/toc.json + - name: Pipeline decorator context + href: ../extend/develop/pipeline-decorator-context.md?toc=/azure/devops/pipelines/toc.json + - name: Specify conditions + href: process/conditions.md + - name: Specify demands + displayName: task demands, manually entered demands, capabilities + href: /azure/devops/pipelines/yaml-schema/pool-demands + - name: Expressions + href: process/expressions.md + - name: Tasks & scripts + items: + - name: Task index + href: /azure/devops/pipelines/tasks/reference/ + - name: Task types & usage + displayName: custom tasks, task versions, task control options, conditions, task tool installers, build tool installers + href: process/tasks.md + - name: Task groups (Classic) + href: release/task-groups.md + - name: Add a custom task extension + href: ../extend/develop/add-build-task.md?toc=/azure/devops/pipelines/toc.json + - name: Upload tasks to project collection + href: ../extend/develop/upload-tasks.md?toc=/azure/devops/pipelines/toc.json + - name: Use tasks to increase run retention + displayName: retention, pipelines, runs + href: build/run-retention.md - name: Run a PowerShell script - href: scripts/powershell.md displayName: powershell, scripts + href: scripts/powershell.md - name: Run Git commands - href: scripts/git-commands.md displayName: scripts, git, cmd, commands - - name: Reduce build time using caching - href: release/caching.md - displayName: caching, pipelines caching, cache + href: scripts/git-commands.md + - name: Cross-platform scripts + displayName: cross platform, scripts + href: scripts/cross-platform-scripting.md + - name: Logging commands + href: scripts/logging-commands.md + - name: File matching patterns + href: tasks/file-matching-patterns.md - name: Cache NuGet packages - href: artifacts/caching-nuget.md - displayName: caching, cache - - name: Configure build run numbers - href: process/run-number.md - displayName: build number, run number, tokens, variables, - - name: Classic Build options - href: build/options.md - displayName: classic build, build options - - name: Use tasks to increase run retention - href: build/run-retention.md - displayName: retention, pipelines, runs -- name: Run pipeline tests - items: - - name: About pipeline tests - href: test/test-glossary.md - - name: Set up parallel testing (VSTest) - href: test/parallel-testing-vstest.md - - name: Set up parallel testing (Test Runner) - href: test/parallel-testing-any-test-runner.md - - name: Enable Test Impact Analysis (TIA) - href: test/test-impact-analysis.md - - name: Enable flaky test management - href: test/flaky-test-management.md - - name: Run UI tests - href: test/ui-testing-considerations.md - - name: Run UI tests with Selenium - href: test/continuous-test-selenium.md - - name: Requirements traceability - href: test/requirements-traceability.md - - name: Review test results + href: artifacts/caching-nuget.md + - name: Templates, parameters, & expressions + items: + - name: Templates + displayName: parameters, passing, job reuse, stage reuse, variable reuse, expressions, context, conditional insertion, iterative insertion, escape a value + href: process/templates.md + - name: Template parameters + href: process/template-parameters.md + - name: Template expressions + href: process/template-expressions.md + - name: Use runtime parameters + displayName: parameters in pipelines, conditionals, loop, data types + href: process/runtime-parameters.md + - name: Process parameters (Classic) + href: release/parameters.md + - name: Variables + items: + - name: Define variables + displayName: secrets, expressions, queue time, expansion,system, environment variables, macro syntax, template syntax + href: process/variables.md + - name: Use predefined variables + displayName: build variables, agent variables, pipeline variables, system variables + href: build/variables.md + - name: Job access tokens + displayName: job access token, identity, build service account, project build service account, collection build service account, access token, build service + href: process/access-tokens.md + - name: Set secret variables + displayName: secret variables + href: process/set-secret-variables.md + - name: Set variables in scripts + displayName: variables, task, setname, scripts + href: process/set-variables-scripts.md + - name: Variable groups items: - - name: Review test results - href: test/review-continuous-test-results-after-build.md - - name: Review test Analytics - href: test/test-analytics.md - - name: Review code coverage - href: test/review-code-coverage-results.md - - name: Review pull request code coverage - href: test/codecoverage-for-pullrequests.md -- name: Deploy apps - items: - - name: Create a multistage pipeline - href: process/create-multistage-pipeline.md - displayName: multi stage, multi stage pipelines - - name: Deploy apps to environments - items: - - name: Define and target environments - href: process/environments.md - displayName: clusters, vms, resources - - name: Kubernetes resource - href: process/environments-kubernetes.md - displayName: clusters, aks, manifest, service account - - name: Virtual machine resource - href: process/environments-virtual-machines.md - - name: Deploy apps using VMs - items: - - name: Linux virtual machines - href: ecosystems/deploy-linux-vm.md - - name: Manage a VM in Azure DevTest Labs - href: apps/cd/azure/deploy-provision-devtest-lab.md - - name: Deploy mobile apps - items: - - name: Manage signing certificates - href: apps/mobile/app-signing.md - - name: Manage signing certificates (TFS-2017) - href: apps/mobile/secure-certs.md -- name: Deploy apps (Classic) + - name: Manage variable groups + displayName: Azure key vault, link secrets, expansion, expand variables + href: library/variable-groups.md + - name: Link a variable group to Azure Key Vault + displayName: Azure key vault, link secrets, expansion, expand variables + href: library/link-variable-groups-to-key-vaults.md + - name: Manage variables in variable groups (CLI) + displayName: create pipeline, manage pipeline, monitor pipeline, secret variable + href: scripts/cli/pipeline-variable-group-secret-nonsecret-variables.md + - name: Use classic release and artifacts variables + displayName: identity, system, build, agent, deployment job, System.AccessToken, System.Debug + href: release/variables.md + - name: Library, resources, & secure files + items: + - name: Pipeline resources + href: process/about-resources.md + - name: Library & shared resources + displayName: security roles, variables, variable groups, secure files + href: library/index.md + - name: Add resources to a pipeline + href: process/resources.md + - name: Define and target environments + displayName: clusters, vms, resources + href: process/environments.md + - name: Kubernetes resource + displayName: clusters, aks, manifest, service account + href: process/environments-kubernetes.md + - name: Virtual machine resource + href: process/environments-virtual-machines.md + - name: Use secure files + href: library/secure-files.md + - name: Triggers + items: + - name: Types of triggers + displayName: ci, pr, pull request, triggers, azure repos git, github, bitbucket, tfvc, release triggers, scheduled, pipeline triggers, build completion triggers, comment triggers, CD triggers, stage triggers, YAML triggers + href: build/triggers.md + - name: Scheduled triggers + displayName: schedule, cron, daily, weekly, monthly, nightly, scheduled runs, crontab + href: process/scheduled-triggers.md + - name: Pipeline completion triggers + displayName: build completion, completion trigger + href: process/pipeline-triggers.md + - name: Build completion triggers (Classic) + displayName: build completion, completion trigger + href: release/pipeline-triggers-classic.md + - name: Release triggers (Classic) + displayName: release trigger, stage trigger, deploy PR, scheduled trigger + href: release/triggers.md + - name: Approvals, checks, & gates + items: + - name: Release approval and gates overview + href: release/approvals/index.md + - name: Define approvals & checks + displayName: approvals, checks + href: process/approvals.md + - name: Invoke Azure Function / REST API checks + displayName: azure function, checks + href: process/invoke-checks.md + - name: Deployment gates concepts + displayName: gates, checks, approvals, pre-deployment, post-deployment + href: release/approvals/gates.md + - name: Use approvals and gates + href: release/deploy-using-approvals.md + - name: Deployment control using approvals + href: release/approvals/approvals.md + - name: Architectures + items: + - name: Baseline Azure Pipelines architecture + href: architectures/devops-pipelines-baseline-architecture.md + - name: Azure Web Apps architecture + href: architectures/devops-pipelines-azure-web-apps-architecture.md + - name: DevTest architecture + href: architectures/devops-pipelines-devtest-iaas-architecture.md + - name: IaaS architecture + href: architectures/devops-pipelines-iaas-vms-architecture.md +- name: Agents & pools items: - - name: Release pipelines overview - href: release/index.md - displayName: release, deploy, deployment - - name: Deploy from multiple branches - href: release/deploy-multiple-branches.md - displayName: multiple branches, deployment - - name: Deploy pull request Artifacts - href: release/deploy-pull-request-builds.md - displayName: pr release, deployment - - name: Classic release pipelines - href: release/define-multistage-release-process.md - displayName: classic release, classic deployment - - name: Pipelines with PowerShell DSC - href: release/dsc-cicd.md - displayName: powershell, dsc - - name: Stage templates in Azure Pipelines - href: release/env-templates.md - displayName: environment, templates, stages - - name: View release progress and test results - href: release/visualize-release-test-progress.md - displayName: release status, test summary - - name: Deploy apps to VMs (Classic) - items: - - name: Linux VMs (Classic) - href: apps/cd/deploy-linuxvm-deploygroups.md - displayName: linux, deployment vm - - name: Windows VMs (Classic) - href: apps/cd/deploy-webdeploy-iis-deploygroups.md - displayName: windows vm, deployment vm - - name: IIS servers (WinRM) (Classic) - href: apps/cd/deploy-webdeploy-iis-winrm.md - displayName: iis, server, winrm - - name: Extend IIS Server deployments (Classic) - href: apps/cd/howto-webdeploy-iis-deploygroups.md - displayName: iis, server - - name: SCVMM (Classic) - href: targets/scvmm.md - displayName: scvmm, targets - - name: VMware (Classic) - href: targets/vmware.md - displayName: vmware, targets -- name: Deploy to Azure + - name: About agents & agent pools + displayName: self-hosted, microsoft-hosted, parallel, capabilities, user capabilities, system capabilities, demands, pools, communication + href: agents/agents.md + - name: Managed DevOps pools + displayName: pools, agents + href: /azure/devops/managed-devops-pools/overview + - name: Agent version 4.x + href: agents/v4-agent.md + - name: Agent version 3.x + href: agents/v3-agent.md + - name: Create & manage agent pools + displayName: queue, default, hosted, maintenance + href: agents/pools-queues.md + - name: Historical graph for agent pools + href: agents/pool-consumption-report.md + - name: Microsoft-hosted agents + href: agents/hosted.md + - name: Self-hosted Linux agents + href: agents/linux-agent.md + - name: Self-hosted macOS agents + href: agents/osx-agent.md + - name: Self-hosted Windows agents + href: agents/windows-agent.md + - name: Scale set agents + displayName: byos, elastic agents, VMSS, autoscale + href: agents/scale-set-agents.md + - name: Run an agent behind a web proxy + href: agents/proxy.md + - name: Run an agent in Docker + href: agents/docker.md + - name: Use a self-signed certificate + href: agents/certificate.md + - name: Agent registration options + items: + - name: Self-hosted agent authentication options + href: agents/agent-authentication-options.md + - name: Personal access token (PAT) + href: agents/personal-access-token-agent-registration.md + - name: Service Principal + href: agents/service-principal-agent-registration.md + - name: Device code flow + href: agents/device-code-flow-agent-registration.md +- name: Build & Deploy items: - - name: Deploy to Azure overview - href: overview-azure.md - - name: Azure Resource Manager service connection - href: library/connect-to-azure.md - displayName: resource manager, service connection, service principal - - name: Azure App Service (Web Apps) + - name: Build + items: + - name: Build multiple branches + displayName: build, pipelines build, multiple branches + href: build/ci-build-git.md + - name: Configure build run numbers + displayName: build number, run number, tokens, variables, + href: process/run-number.md + - name: Use build tags + displayName: build tags, tags + href: build/build-tag.md + - name: Reduce build time using caching + displayName: caching, pipelines caching, cache + href: release/caching.md + - name: Cache NuGet packages + displayName: caching, cache + href: artifacts/caching-nuget.md + - name: View pipeline history (Classic) + displayName: history + href: release/history.md + - name: Classic pipelines configuration + displayName: classic, build options + href: release/options.md + - name: Publish & download pipeline artifacts + displayName: publish, download, artifacts + href: artifacts/pipeline-artifacts.md + - name: Publish & download build artifacts + displayName: build, download, publish, artifacts + href: artifacts/build-artifacts.md + - name: Deploy + items: + - name: Deploy to Azure items: - - name: App Service + - name: Overview + href: overview-azure.md + - name: Connect to Azure + items: + - name: Azure Resource Manager service connection + displayName: resource manager, service connection, service principal + href: library/connect-to-azure.md + - name: Azure Resource Manager special cases + displayName: agent-assigned identity, publish profile + href: library/azure-resource-manager-alternate-approaches.md + - name: Manually configure workload identity service connections + href: release/configure-workload-identity.md + - name: Troubleshoot workload identity service connections + href: release/troubleshoot-workload-identity.md + - name: Troubleshoot Azure Resource Manager service connections + displayName: service connection, service principal, Azure resource manager, azure + href: release/azure-rm-endpoint.md + - name: Azure App Service (Web Apps) + items: + - name: Deploy to App Service using Azure Pipelines href: /azure/app-service/deploy-azure-pipelines - name: Azure Web App for Containers - href: apps/cd/deploy-docker-webapp.md displayName: containers, docker, azure web app - - name: Azure Functions - items: - - name: Azure Functions - href: /azure/azure-functions/functions-how-to-azure-devops - - name: Azure Resource Manager (ARM) templates - items: + href: apps/cd/deploy-docker-webapp.md + - name: Create a multistage pipeline + displayName: multi stage, multi stage pipelines + href: process/create-multistage-pipeline.md + - name: Azure Resource Manager (ARM) templates + items: - name: Use a Resource Manager template to deploy - href: apps/cd/azure/deploy-arm-template.md displayName: Resource Manager, ARM, azure - - name: Azure VM using Azure Resource Manager (Classic) - href: apps/cd/azure/deploy-provision-azure-vm.md - - name: Azure Databricks - items: + href: apps/cd/azure/deploy-arm-template.md + - name: Azure Databricks + items: - name: Data pipeline overview - href: apps/cd/azure/cicd-data-overview.md displayName: data science, machine learning + href: apps/cd/azure/cicd-data-overview.md - name: Build a data pipeline href: apps/cd/azure/build-data-pipeline.md - - name: Azure Machine Learning - href: /azure/machine-learning/how-to-devops-machine-learning - - name: Azure Databases - items: - - name: Azure SQL database - href: targets/azure-sqldb.md - - name: Azure MySQL database - href: /azure/mysql/single-server/azure-pipelines-mysql-deploy - - name: Azure Virtual Machine Scale Set - items: - - name: Deploy a virtual machine scale set - href: apps/cd/azure/deploy-virtual-scale-set-java.md - displayName: vmss, custom image - - name: Deploy apps to a virtual machine scale set (Classic) - href: apps/cd/azure/deploy-azure-scaleset.md - - name: Azure Stack - href: targets/azure-stack.md - - name: Azure Container Registry - items: + - name: Azure Databases + items: + - name: Azure SQL database + href: targets/azure-sqldb.md + - name: Azure MySQL database + href: /azure/mysql/single-server/azure-pipelines-mysql-deploy + - name: Azure Virtual Machine Scale Set + items: + - name: Deploy a virtual machine scale set + displayName: vmss, custom image + href: apps/cd/azure/deploy-virtual-scale-set-java.md + - name: Deploy apps using VMs + items: + - name: Linux virtual machines + href: ecosystems/deploy-linux-vm.md + - name: Azure Container Registry + items: - name: Build and push to Azure Container Registry with a Docker template href: ecosystems/containers/acr-template.md - name: Build and push to Azure Container Registry - Managed Service Identity href: ecosystems/containers/publish-to-acr.md - - name: Azure Kubernetes Service - items: - - name: Build and deploy to Azure Kubernetes Service - href: /azure/aks/devops-pipeline - - name: Azure Policy Compliance (Classic) - href: /azure/governance/policy/tutorials/policy-devops-pipelines - displayName: policy, compliance -- name: Deploy apps using containers - items: - # - name: Orchestration overview (New) - - name: Build images - href: ecosystems/containers/build-image.md - displayName: docker, compose, docker-compose, arm, buildkit, image - - name: Push images - href: ecosystems/containers/push-image.md - displayName: container registry, acr, gcr, ecr, docker hub, azure container registry, google container registry - - name: Content trust - displayName: docker content trust, dct - href: ecosystems/containers/content-trust.md - - name: Kubernetes + - name: Azure Kubernetes Service + items: + - name: Build and deploy to Azure Kubernetes Service + href: /azure/aks/devops-pipeline + - name: Azure Functions + href: /azure/azure-functions/functions-how-to-azure-devops + - name: Azure Stack + href: targets/azure-stack.md + - name: Azure Machine Learning + href: /azure/machine-learning/how-to-devops-machine-learning + - name: Deploy apps using containers items: + - name: Build images + displayName: docker, compose, docker-compose, arm, buildkit, image + href: ecosystems/containers/build-image.md + - name: Build and push container images to registries + displayName: container registry, acr, docker hub, azure container registry + href: ecosystems/containers/push-image.md + - name: Content trust + displayName: docker content trust, dct + href: ecosystems/containers/content-trust.md + - name: Kubernetes + items: - name: Deploy to Kubernetes - href: ecosystems/kubernetes/deploy.md displayName: kubernetes, aks, gke, eks, canary + href: ecosystems/kubernetes/deploy.md - name: Use a canary deployment strategy href: ecosystems/kubernetes/canary-demo.md -- name: Consume & publish artifacts - items: + - name: Deploy apps (Classic) + items: + - name: Release pipelines overview + displayName: release, deploy, deployment + href: release/index.md + - name: Create a Classic release + displayName: release artifacts, deployment artifacts + href: release/releases.md + - name: Create a multi-stage release + displayName: classic release, classic deployment + href: release/define-multistage-release-process.md + - name: Artifact sources + displayName: artifacts, source, release artifacts + href: release/artifacts.md + - name: Release variables + displayName: release, deploy, variables + href: release/variables.md + - name: Release triggers (Classic) + displayName: release trigger, stage trigger, deploy PR, scheduled trigger + href: release/triggers.md + - name: Deploy pull request Artifacts + displayName: pr release, deployment + href: release/deploy-pull-request-builds.md + - name: Deploy from multiple branches + displayName: multiple branches, deployment + href: release/deploy-multiple-branches.md + - name: Deploy to a Windows VM + displayName: windows vm, deployment vm + href: release/deploy-webdeploy-iis-deploygroups.md + - name: Stage templates in Azure Pipelines + displayName: environment, templates, stages + href: release/env-templates.md + - name: Azure Policy Compliance (Classic) + displayName: policy, compliance + href: /azure/governance/policy/tutorials/policy-devops-pipelines + - name: Create & use deployment groups (Classic) + items: + - name: Provision deployment groups + href: release/deployment-groups/index.md + - name: Provision agents for deployment groups + href: release/deployment-groups/howto-provision-deployment-group-agents.md + - name: Add a deployment group job to a release pipeline + href: release/deployment-group-phases.md + - name: Deploying to Azure VMs using deployment groups in Azure Pipelines + href: release/deployment-groups/deploying-azure-vms-deployment-groups.md + - name: Artifacts + items: - name: Artifacts in Azure Pipelines - href: artifacts/artifacts-overview.md displayName: artifacts, artifacts overview + href: artifacts/artifacts-overview.md - name: Publish & download pipeline artifacts - href: artifacts/pipeline-artifacts.md displayName: download artifacts, publish artifacts, packages - - name: Build artifacts - href: artifacts/build-artifacts.md + href: artifacts/pipeline-artifacts.md + - name: Publish & download build artifacts displayName: build, artifacts - - name: Release pipelines - href: release/releases.md - displayName: release artifacts, deployment artifacts - - name: Release artifacts and artifact sources - href: release/artifacts.md + href: artifacts/build-artifacts.md + - name: Artifact sources displayName: artifacts, source, release artifacts + href: release/artifacts.md + - name: Use the .artifactignore file + displayName: artifactignore, gitignore + href: ../artifacts/reference/artifactignore.md?toc=/azure/devops/pipelines/toc.json - name: NuGet - href: artifacts/nuget.md - displayName: nuget, package + items: + - name: Publish packages to internal and external feeds + displayName: nuget, package + href: artifacts/nuget.md + - name: Restore NuGet packages + displayName: nuget, package, restore + href: packages/nuget-restore.md + - name: Publish NuGet packages to NuGet.org (Classic/YAML) + displayName: publish, nuget, package + href: artifacts/publish-public-registry.md - name: npm - href: artifacts/npm.md displayName: npm, package + href: artifacts/npm.md - name: Maven - href: artifacts/publish-maven-artifacts.md - displayName: Maven, package + items: + - name: Publish Maven packages to internal and external feeds + displayName: Maven, publish + href: artifacts/publish-maven-artifacts.md + - name: Restore packages + displayName: Maven, restore + href: packages/maven-restore.md - name: Gradle - href: artifacts/pull-package-gradle.md displayName: Gradle, package + href: artifacts/build-publish-artifacts-gradle.md - name: Python - href: artifacts/pypi.md displayName: python, package + href: artifacts/pypi.md + - name: Cargo + displayName: cargo, crate + href: artifacts/cargo-pipelines.md - name: Universal Packages - href: artifacts/universal-packages.md displayName: package, universal + href: artifacts/universal-packages.md - name: Symbols - href: artifacts/symbols.md displayName: symbols, debugging, debugger - - name: Restore NuGet packages - href: packages/nuget-restore.md - displayName: nuget, package, restore - - name: Publish NuGet packages with Jenkins - href: packages/jenkins.md - displayName: nuget, package, publish, jenkins - - name: Publish NuGet packages to NuGet.org (Classic/YAML) - href: artifacts/publish-public-registry.md - displayName: publish, nuget, package -- name: Create & use resources - items: - - name: About resources - href: process/about-resources.md - - name: Library & shared resources - href: library/index.md - displayName: resource, resources, pipeline resource, resources security, resources traceability - - name: Add an admin role to a resource - href: library/add-resource-protection.md - - name: Repository resource protection - href: process/repository-resource.md - displayName: protected resources, protection, checks - - name: Manage service connections - href: library/service-endpoints.md - displayName: service connection, project-level permissions, docker, GitHub, npm, Nuget, Azure Repos - - name: Add resources to a pipeline - href: process/resources.md - - name: Add & use variable groups - href: library/variable-groups.md - displayName: Azure key vault, link secrets, expansion, expand variables - - name: Use secure files - href: library/secure-files.md - - name: Provision deployment groups - href: release/deployment-groups/index.md - - name: Define and target environments - href: process/environments.md - - name: Kubernetes resource - href: process/environments-kubernetes.md - - name: Virtual machine resource - href: process/environments-virtual-machines.md -- name: Manage agents & agent pools - items: - - name: About agents & agent pools - href: agents/agents.md - displayName: self-hosted, microsoft-hosted, parallel, capabilities, user capabilities, system capabilities, demands, pools, communication - - name: Agent version 3.x - href: agents/v3-agent.md - - name: Create & manage agent pools - href: agents/pools-queues.md - displayName: queue, default, hosted, maintenance - - name: Historical graph for agent pools - href: agents/pool-consumption-report.md - - name: Microsoft-hosted agents - href: agents/hosted.md - - name: Self-hosted Linux agents - href: agents/linux-agent.md - - name: Self-hosted macOS agents - href: agents/osx-agent.md - - name: Self-hosted Windows agents - href: agents/windows-agent.md - - name: Self-hosted agents (previous version 2.x) + href: artifacts/symbols.md + - name: Artifact policy checks + href: process/artifact-policy.md + - name: Examples + items: + - name: Ecosystem support + displayName: language, platform + href: ecosystems/ecosystems.md + - name: .NET items: - - name: Self-hosted Linux agents (2.x) - href: agents/v2-linux-agent.md - - name: Self-hosted macOS agents (2.x) - href: agents/v2-osx-agent.md - - name: Self-hosted Windows agents (2.x) - href: agents/v2-windows-agent.md - - name: Scale set agents - href: agents/scale-set-agents.md - displayName: byos, elastic agents, VMSS, autoscale - - name: Run an agent behind a web proxy - href: agents/proxy.md - - name: Run an agent in Docker - href: agents/docker.md - - name: Use a self-signed certificate - href: agents/certificate.md - - name: Create & use deployment groups (Classic) + - name: .NET Core + displayName: dotnet, DotNetCoreInstaller, csproj, DotNetCoreCLI, msbuild, DotNetCore + href: ecosystems/dotnet-core.md + - name: .NET Framework + displayName: ASP, ASPNET, web + href: apps/aspnet/build-aspnet-4.md + - name: JavaScript items: - # - name: About deployment groups & deployment group jobs - # href: release/deployment-groups/index.md - - name: Provision deployment groups - href: release/deployment-groups/index.md - - name: Provision agents for deployment groups - href: release/deployment-groups/howto-provision-deployment-group-agents.md - - name: Add a deployment group job to a release pipeline - href: process/deployment-group-phases.md - - name: Deploying to Azure VMs using deployment groups in Azure Pipelines - href: release/deployment-groups/deploying-azure-vms-deployment-groups.md -- name: Configure security & settings - items: - # - name: About security options and requirements (New) - # href: policies/permissions.md - - name: Set retention policies - href: policies/retention.md - displayName: service endpoints, artifact retention, test retention, copy files - - name: Configure and pay for parallel jobs - href: licensing/concurrent-jobs.md - displayName: parallel jobs, microsoft-hosted, self-hosted - - name: Set pipeline permissions - href: policies/permissions.md - displayName: release permissions, task group permissions, service permissions, environment permissions - - name: Add users to contribute to pipelines - href: policies/set-permissions.md - displayName: add administrators, add users - - name: Grant version control permissions to the build service - href: scripts/git-commands.md#version-control - displayName: enable scripts, enable git scripts, git commands - - name: Pipelines security walkthrough + - name: JavaScript quickstart + displayName: node, node.js, nodetool, npm, yarn, react, babel, typescript, tsc, mocha, jasmine, jest, karma, ava, junit, cobertura, protractor, phantomjs, webpack, angular, react, vue, gulp, grunt + href: ecosystems/javascript.md + - name: Customize JavaScript + displayName: configure javascript, node, configure node.js, nodetool, npm, yarn, react, babel, typescript, tsc, mocha, jasmine, jest, karma, ava, junit, cobertura, protractor, phantomjs, webpack, angular, react, vue, gulp, grunt + href: ecosystems/customize-javascript.md + - name: Node.js tutorial + href: ecosystems/nodejs-tutorial.md + - name: Python items: - - name: Overview - href: security/overview.md - displayName: security, repo protection, malicious code, assume breach - - name: Approach to securing YAML pipelines - href: security/approach.md - displayName: template permissions, repositories - - name: Secure repositories - href: security/repos.md - - name: Secure access to Azure repositories from pipelines - href: security/secure-access-to-repos.md - displayName: forks, branches, access token - - name: Pipeline resources - href: security/resources.md - displayName: protected resources, repository resources - - name: Project structure - href: security/projects.md - displayName: separate projects - - name: Security through templates - href: security/templates.md - displayName: conditionals, extends, scripts, templates - - name: Variables and parameters - href: security/inputs.md - displayName: inputs, parameters, queue-time variables - - name: Shared infrastructure - href: security/infrastructure.md - displayName: low privileges, hosted, infrastructure - - name: Other security considerations - href: security/misc.md - displayName: PATH, containers, control tasks, auditing - - name: Download release permissions report - href: ../organizations/security/download-permissions-report-release.md -- name: Architectures + - name: Python quickstart + displayName: flake, python + href: ecosystems/python.md + - name: Customize Python + displayName: anaconda, PyPI, pip , setuptools, wheel, conda, flake8, pytest, junit, cobertura, tox, twine + href: ecosystems/customize-python.md + - name: Python to web app + displayName: django, webapp + href: ecosystems/python-webapp.md + - name: Anaconda + displayName: data science, python, miniconda, conda + href: ecosystems/anaconda.md + - name: Java + items: + - name: Java apps + displayName: maven, goals, gradle, ant + href: ecosystems/java.md + - name: Java to web App + href: ecosystems/java-webapp.md + - name: Java to web app with MicroProfile + href: /azure/java/microprofile/cicd-microprofile?toc=/azure/devops/pipelines/toc.json + - name: Android + displayName: android sdk,android sdk platform tools + href: ecosystems/android.md + - name: Go + displayName: workspace, gopath, goroot, go get, dep, dep ensure + href: ecosystems/go.md + - name: PHP + displayName: php, phpunit + href: ecosystems/php.md + - name: Ruby + displayName: rails, bundler, rake, simplecov, cobertura + href: ecosystems/ruby.md + - name: Xcode + displayName: app certificate, test flight + href: ecosystems/xcode.md + - name: Microsoft Learn courses + items: + - name: Create a build pipeline + href: /training/modules/create-a-build-pipeline/ + - name: Implement a code workflow in your build pipeline by using Git and GitHub + href: /training/modules/implement-code-workflow/index + - name: Run quality tests in your build pipeline + href: /training/modules/run-quality-tests-build-pipeline/index + - name: Manage build dependencies with Azure Artifacts + href: /training/modules/manage-build-dependencies/index +- name: Test items: - - name: Baseline Azure Pipelines architecture - href: architectures/devops-pipelines-baseline-architecture.md - - name: Azure Web Apps architecture - href: architectures/devops-pipelines-azure-web-apps-architecture.md - - name: DevTest architecture - href: architectures/devops-pipelines-devtest-iaas-architecture.md - - name: IaaS architecture - href: architectures/devops-pipelines-iaas-vms-architecture.md -- name: Integrate with 3rd party software + - name: About pipeline tests + href: test/test-glossary.md + - name: Set up parallel testing (VSTest) + href: test/parallel-testing-vstest.md + - name: Set up parallel testing (Test Runner) + href: test/parallel-testing-any-test-runner.md + - name: Enable Test Impact Analysis (TIA) + href: test/test-impact-analysis.md + - name: Enable flaky test management + href: test/flaky-test-management.md + - name: Run UI tests + href: test/ui-testing-considerations.md + - name: Run UI tests with Selenium + href: test/continuous-test-selenium.md + - name: Requirements traceability + href: test/requirements-traceability.md + - name: Use Azure DevTest Labs + href: /azure/devtest-labs/devtest-lab-overview + - name: Review test results + items: + - name: Review test results + href: test/review-continuous-test-results-after-build.md + - name: Review test Analytics + href: test/test-analytics.md + - name: Review code coverage + href: test/review-code-coverage-results.md + - name: Review pull request code coverage + href: test/codecoverage-for-pullrequests.md +- name: Monitor & Troubleshoot + items: + - name: Troubleshoot pipeline runs + href: troubleshooting/troubleshooting.md + - name: Troubleshoot pipeline triggers + href: troubleshooting/troubleshoot-triggers.md + - name: Pipeline queues but never starts + href: troubleshooting/troubleshoot-start.md + - name: Debug release issues + href: release/variables.md#run-a-release-in-debug-mode + - name: Troubleshoot ARM service connections + href: release/azure-rm-endpoint.md + - name: Review logs + href: troubleshooting/review-logs.md + - name: Pipeline reports + items: + - name: View pipeline reports + href: reports/pipelinereport.md + - name: Monitor your pipelines with dashboard widgets + href: reports/pipeline-widgets.md +- name: Security & permissions + items: + - name: Set retention policies + displayName: service endpoints, artifact retention, test retention, copy files + href: policies/retention.md + - name: Configure and pay for parallel jobs + displayName: parallel jobs, microsoft-hosted, self-hosted + href: licensing/concurrent-jobs.md + - name: Add users to contribute to pipelines + displayName: add administrators, add users + href: policies/set-permissions.md + - name: Grant version control permissions to the build service + displayName: enable scripts, enable git scripts, git commands + href: scripts/git-commands.md#version-control + - name: Download release permissions report + href: ../organizations/security/download-permissions-report-release.md + - name: Manage service connections + displayName: service connection, project-level permissions, docker, GitHub, npm, Nuget, Azure Repos + href: library/service-endpoints.md + - name: Add an admin role to a resource + href: library/add-resource-protection.md + - name: Repository resource protection + displayName: protected resources, protection, checks + href: process/repository-resource.md + - name: Manage signing certificates + href: apps/mobile/app-signing.md + - name: Use secrets from Azure Key Vault + displayName: secrets, access policies, key vault + href: release/azure-key-vault.md + - name: Use Azure Key Vault in your YAML Pipeline + displayName: key vault, secrets, YAML pipeline + href: release/key-vault-in-own-project.md + - name: Access private key vaults from your pipeline + displayName: secret, key vault + href: release/key-vault-access.md + - name: Permissions + items: + - name: Manage permissions + href: policies/permissions.md + - name: Pipeline permissions + href: policies/permissions.md#pipeline-permissions + - name: Agent pool permissions + href: policies/permissions.md#agent-pool-permissions + - name: Deployment group permissions + href: policies/permissions.md#deployment-group-permissions + - name: Environment permissions + href: policies/permissions.md#environment-permissions + - name: Library permissions + href: policies/permissions.md#library-permissions + - name: Release pipeline permissions + href: policies/permissions.md#release-pipeline-permissions + - name: Service connection permissions + href: policies/permissions.md#service-connection-permissions + - name: Task group permissions + href: policies/permissions.md#task-group-permissions + - name: Security + items: + - name: Secure Azure Pipelines + displayName: security, repo protection, malicious code, assume breach + href: security/overview.md + - name: Approach to securing YAML pipelines + displayName: template permissions, repositories + href: security/approach.md + - name: Secure agents, projects, and containers + href: security/misc.md + - name: Secure access to Azure repositories from pipelines + displayName: forks, branches, access token + href: security/secure-access-to-repos.md + - name: Protecting secrets + href: security/secrets.md + - name: Pipeline resources + displayName: protected resources, repository resources + href: security/resources.md + - name: Security through templates + displayName: conditionals, extends, scripts, templates + href: security/templates.md + - name: Variables and parameters + displayName: inputs, parameters, queue-time variables + href: security/inputs.md +- name: Integration items: - name: Microsoft Teams - href: integrations/microsoft-teams.md displayName: integrations, teams + href: integrations/microsoft-teams.md - name: Slack - href: integrations/slack.md displayName: integrations, slack - - name: Integrate with ServiceNow - href: release/approvals/servicenow.md + href: integrations/slack.md + - name: ServiceNow displayName: integrations, servicenow - - name: Integrate with Jenkins (Classic) - href: release/integrate-jenkins-pipelines-cicd.md - displayName: integrations, jenkins + href: release/approvals/servicenow.md - name: Migrate items: - - name: Migrate from Classic pipelines - href: migrate/from-classic-pipelines.md - - name: Migrate from Jenkins - href: migrate/from-jenkins.md - - name: Migrate from Travis - href: migrate/from-travis.md - - name: Migrate from XAML builds - href: build/migrate-from-xaml-builds.md - - name: Migrate from Lab Management - href: targets/create-virtual-network.md -- name: Pipeline tasks - items: - - name: Task index - href: /azure/devops/pipelines/tasks/reference/ -- name: Troubleshooting - items: - - name: Troubleshoot pipeline runs - href: troubleshooting/troubleshooting.md - - name: Review logs - href: troubleshooting/review-logs.md - - name: Debug deployment issues - href: release/variables.md#debug-mode - - name: Troubleshoot ARM service connections - href: release/azure-rm-endpoint.md + - name: Migrate from Classic pipelines + href: release/from-classic-pipelines.md + - name: Migrate from Jenkins + href: migrate/from-jenkins.md + - name: Migrate from Travis + href: migrate/from-travis.md + - name: Migrate from Lab Management + href: targets/create-virtual-network.md - name: Reference items: - - name: YAML schema - href: /azure/devops/pipelines/yaml-schema/ - displayName: pipeline structure, pipeline, stage, job, steps, variables, templates, resources, triggers, ci trigger, push trigger, pr trigger, comment trigger, pool, server, script, bash, pwsh, powershell, checkout, task - - name: Expressions - href: process/expressions.md - - name: File matching patterns - href: tasks/file-matching-patterns.md - - name: File and variable transform - href: tasks/transforms-variable-substitution.md - - name: Logging commands - href: scripts/logging-commands.md - - name: Artifact policy checks - href: process/artifact-policy.md - - name: Azure CLI - href: /cli/azure/pipelines -- name: Case studies & best practices - items: - - name: Use deployment rings - href: ../migrate/phase-rollout-with-rings.md?toc=/azure/devops/pipelines/toc.json - - name: Use feature flags - href: /devops/operate/progressive-experimentation-feature-flags?bc=%2fazure%2fdevops%2fpipelines%2fbreadcrumb/toc.json&toc=/azure%2fdevops%2fpipelines/toc.json - displayName: feature-flags - - name: Legacy content - items: - - name: NuGet Packager 0.* - href: /previous-versions/azure/devops/pipelines/tasks/package/prev-versions/nuget-packager-0?view=tfs-2017&preserve-view=true - - name: NuGet Publisher 0.* - href: /previous-versions/azure/devops/pipelines/tasks/package/prev-versions/nuget-publisher-0?view=tfs-2017&preserve-view=true - - name: NuGet Installer 0.* - href: /previous-versions/azure/devops/pipelines/tasks/package/prev-versions/nuget-installer-0?view=tfs-2017&preserve-view=true - - name: Deploy to AKS with Jenkins - href: /previous-versions/azure/devops/pipelines/release/integrate-jenkins-pipelines-aks?view=tfs-2017&preserve-view=true -- name: Developer resources - items: - - name: REST API reference - href: /rest/api/azure/devops/ - - name: Azure DevOps CLI - href: ../cli/index.md - - name: DevOps Starter to deploy to Azure - href: /azure/devops-project/ - - name: Azure Lab Services - href: /azure/lab-services/ - - name: Microsoft Learn - items: - - name: Create a build pipeline - href: /training/modules/create-a-build-pipeline/ - - name: Implement a code workflow in your build pipeline by using Git and GitHub - href: /training/modules/implement-code-workflow/index - - name: Run quality tests in your build pipeline - href: /training/modules/run-quality-tests-build-pipeline/index - - name: Manage build dependencies with Azure Artifacts - href: /training/modules/manage-build-dependencies/index - - name: Automated testing - href: /visualstudio/test/lab-management/use-build-or-rm-instead-of-lab-management + - name: YAML schema + displayName: pipeline structure, pipeline, stage, job, steps, variables, templates, resources, triggers, ci trigger, push trigger, pr trigger, comment trigger, pool, server, script, bash, pwsh, powershell, checkout, task + href: /azure/devops/pipelines/yaml-schema/ + - name: Task index + href: /azure/devops/pipelines/tasks/reference/ + - name: Azure DevOps CLI + href: ../cli/index.md + - name: Azure CLI + href: /cli/azure/pipelines + - name: REST API reference + href: /rest/api/azure/devops/ diff --git a/docs/pipelines/troubleshooting/media/error-analysis.png b/docs/pipelines/troubleshooting/media/error-analysis.png new file mode 100644 index 00000000000..d5149aa94f4 Binary files /dev/null and b/docs/pipelines/troubleshooting/media/error-analysis.png differ diff --git a/docs/pipelines/troubleshooting/media/error-message.png b/docs/pipelines/troubleshooting/media/error-message.png new file mode 100644 index 00000000000..3724a52ae6f Binary files /dev/null and b/docs/pipelines/troubleshooting/media/error-message.png differ diff --git a/docs/pipelines/troubleshooting/media/notification-settings.png b/docs/pipelines/troubleshooting/media/notification-settings.png new file mode 100644 index 00000000000..1dc14f80d29 Binary files /dev/null and b/docs/pipelines/troubleshooting/media/notification-settings.png differ diff --git a/docs/pipelines/troubleshooting/media/pipeline-error-analysis-icon-server.png b/docs/pipelines/troubleshooting/media/pipeline-error-analysis-icon-server.png new file mode 100644 index 00000000000..569d3f19f0e Binary files /dev/null and b/docs/pipelines/troubleshooting/media/pipeline-error-analysis-icon-server.png differ diff --git a/docs/pipelines/troubleshooting/media/pipeline-error-analysis-icon.png b/docs/pipelines/troubleshooting/media/pipeline-error-analysis-icon.png new file mode 100644 index 00000000000..ee784b8a07b Binary files /dev/null and b/docs/pipelines/troubleshooting/media/pipeline-error-analysis-icon.png differ diff --git a/docs/pipelines/troubleshooting/media/pipeline-run-summary-troubleshooting.png b/docs/pipelines/troubleshooting/media/pipeline-run-summary-troubleshooting.png new file mode 100644 index 00000000000..1241e1cb519 Binary files /dev/null and b/docs/pipelines/troubleshooting/media/pipeline-run-summary-troubleshooting.png differ diff --git a/docs/pipelines/troubleshooting/media/task-details.png b/docs/pipelines/troubleshooting/media/task-details.png new file mode 100644 index 00000000000..8137ffdefbe Binary files /dev/null and b/docs/pipelines/troubleshooting/media/task-details.png differ diff --git a/docs/pipelines/troubleshooting/media/task-error-log.png b/docs/pipelines/troubleshooting/media/task-error-log.png new file mode 100644 index 00000000000..dde03e5601f Binary files /dev/null and b/docs/pipelines/troubleshooting/media/task-error-log.png differ diff --git a/docs/pipelines/troubleshooting/media/view-raw-log.png b/docs/pipelines/troubleshooting/media/view-raw-log.png new file mode 100644 index 00000000000..2a74c2ca3a0 Binary files /dev/null and b/docs/pipelines/troubleshooting/media/view-raw-log.png differ diff --git a/docs/pipelines/troubleshooting/review-logs.md b/docs/pipelines/troubleshooting/review-logs.md index 62ea424ef05..b92896a4f4b 100644 --- a/docs/pipelines/troubleshooting/review-logs.md +++ b/docs/pipelines/troubleshooting/review-logs.md @@ -3,9 +3,8 @@ title: Review logs to diagnose pipeline issues description: Learn how to review pipeline diagnostic logs to troubleshoot ms.author: sdanie ms.reviewer: steved0x -ms.custom: seodec18, contperf-fy20q4 ms.topic: troubleshooting -ms.date: 01/30/2023 +ms.date: 04/02/2024 monikerRange: '<= azure-devops' author: steved0x --- @@ -14,17 +13,15 @@ author: steved0x [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Pipeline logs provide a powerful tool for determining the cause of pipeline failures. +Pipeline logs provide a powerful tool for determining the cause of pipeline failures, and verbose logs can be configured to provide more diagnostic information. -A typical starting point is to review the logs in your completed build or release. You can view logs by navigating to the pipeline run summary and selecting the job and task. If a certain task is failing, check the logs for that task. - -In addition to viewing logs in the pipeline build summary, you can download complete logs which include additional diagnostic information, and you can configure more verbose logs to assist with your troubleshooting. +A typical starting point is to review the logs in your completed build or release. You can view logs by navigating to the pipeline run summary and selecting the job and task. If a certain task is failing, check the logs for that task. [Configure verbose logs](#configure-verbose-logs) to include more diagnostic information. ## Configure verbose logs To assist with troubleshooting, you can configure your logs to be more verbose. -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" * To configure verbose logs for a single run, you can start a new build by choosing **Run pipeline** and selecting **Enable system diagnostics**, **Run**. @@ -34,19 +31,17 @@ In addition to viewing logs in the pipeline build summary, you can download comp ::: moniker-end -::: moniker range="<= azure-devops-2019" +::: moniker range="> azure-devops-2022" -* To configure verbose logs for a single run, you can start a new build by choosing **Queue build**, and setting the value for the `system.debug` variable to `true`. -* To configure verbose logs for all runs, edit the build, navigate to the **Variables** tab, and add a variable named `system.debug`, set its value to `true`, and select to **Allow at Queue Time**. -* To configure verbose logs for a YAML pipeline, add the `system.debug` variable in the `variables` section: +Azure pipeline logs can now capture resource utilization metrics such as memory, CPU usage and available disk space. The logs also include resources used by the pipeline agent and child processes including tasks run in a job. If you suspect your pipeline job may run into resource constraints, enable verbose logs to have resource utilization information injected into pipeline logs. Resource utilization metrics are available on any agent, independent from hosting model. - ```YAML - variables: - system.debug: true - ``` - -::: moniker-end +To view the captured resource utilization metrics, [search the logs](#view-and-download-logs) for `Agent environment resources` entries for each step. + +``` +2024-02-28T17:41:15.1315148Z ##[debug]Agent environment resources - Disk: D:\ Available 12342.00 MB out of 14333.00 MB, Memory: Used 1907.00 MB out of 7167.00 MB, CPU: Usage 17.23% +``` +::: moniker-end ## View and download logs @@ -62,12 +57,6 @@ To download all logs, navigate to the build results for the run, select **...**, ::: moniker-end -::: moniker range="<= azure-devops-2019" - -To download all logs, navigate to the build results for the run, choose **Download all logs as zip**. - -::: moniker-end - In addition to the pipeline diagnostic logs, the following specialized log types are available, and may contain information to help you troubleshoot. * [Worker diagnostic logs](#worker-diagnostic-logs) @@ -76,7 +65,7 @@ In addition to the pipeline diagnostic logs, the following specialized log types ## Worker diagnostic logs -You can get the diagnostic log of the completed build that was generated by the worker process on the build agent. Look for the `worker` log file that has the date and time stamp of your completed build. For example, `worker_20160623-192022-utc_6172.log`. +You can get the diagnostic log of the completed build generated by the worker process on the build agent. Look for the `worker` log file that has the date and time stamp of your completed build. For example, `worker_20160623-192022-utc_6172.log`. ## Agent diagnostic logs @@ -102,7 +91,7 @@ Both logs show how the agent capabilities were detected and set. ## Network diagnostics for self-hosted agents -Set the value of `Agent.Diagnostic` to `true` to collect the following additional logs that can be used for troubleshooting network issues for self-hosted agents. +Set the value of `Agent.Diagnostic` to `true` to collect additional logs that can be used for troubleshooting network issues for self-hosted agents. | File | Information | Applies to | |------|-------------|------------| @@ -121,7 +110,6 @@ For more information, see [agent troubleshooting](https://github.com/microsoft/a :::moniker-end - ## Other logs Inside the diagnostic logs you will find `environment.txt` and `capabilities.txt`. @@ -170,7 +158,6 @@ macOS/Linux: 6. Restart the agent. - ### Use full HTTP tracing - macOS and Linux Use Charles Proxy (similar to Fiddler on Windows) to capture the HTTP trace of the agent. @@ -185,6 +172,196 @@ Use Charles Proxy (similar to Fiddler on Windows) to capture the HTTP trace of t export VSTS_HTTP_PROXY=http://127.0.0.1:8888 ``` -4. Run the agent interactively. If it's running as a service, you can set in the .env file. See [nix service](https://github.com/Microsoft/azure-pipelines-agent/blob/master/docs/start/nixsvc.md) +4. Run the agent interactively. If it's running as a service, you can set in the .env file. See [:::no-loc text="nix"::: service](https://github.com/Microsoft/azure-pipelines-agent/blob/master/docs/start/nixsvc.md) 5. Restart the agent. + +## Capture custom logs + +In addition to the built-in logs, you can use tasks and scripts to capture custom logs in your pipeline. The following examples show how to capture resource utilization, network traces, memory dumps, and :::no-loc text="perfview"::: traces. If you are working with customer support, you may be asked to capture logs such as these. + +- [Capture resource utilization details](#capture-resource-utilization-details) +- [Capture a dotnet process memory dump using ProcDump](#capture-a-dotnet-process-memory-dump-using-procdump) +- [Capture ETW traces for a hosted agent](#capture-etw-traces-for-a-hosted-agent) +- [Capture :::no-loc text="perfview"::: traces for Visual Studio build](#capture--traces-for-visual-studio-build) + +### Retrieve custom logs + +After capturing a custom log in your pipeline, you must upload it so that it can be retrieved for review. You can upload the custom log as part of the standard pipeline logs, or you can upload it as an artifact. The examples in the following sections show both ways of uploading custom logs. + +#### Upload a log as part of the standard logs + +To upload the custom log as part of the standard pipeline logs, use `##vso[task.uploadfile]` to upload the desired file. To use this command, specify it as part of a script command as shown in the following example. The file can be [downloaded and viewed](#view-and-download-logs) as part of the standard pipeline logs. The `##vso[task.uploadfile]` method is good for uploading a single log file. If you have more than one log file, you must use a separate `##vso[task.uploadfile]` line for each file. + +```yml +- pwsh: Write-Host "##vso[task.uploadfile]$(Agent.TempDirectory)\resource-usage.txt" +``` + +For more information, see [Logging commands](../scripts/logging-commands.md) and [UploadFile: Upload a file that can be downloaded with task logs](../scripts/logging-commands.md#uploadfile-upload-a-file-that-can-be-downloaded-with-task-logs). + +#### Upload a log as a pipeline artifact + +To upload a custom log as a pipeline artifact, use the [PublishPipelineArtifact@1](/azure/devops/pipelines/tasks/reference/publish-pipeline-artifact-v1) task. `PublishPipelineArtifact@1` can upload a single file or the files in a directory path, and is useful if you have many custom log files to upload. + +```yml +- task: PublishPipelineArtifact@1 + inputs: + targetPath: '$(Pipeline.Workspace)/s/trace' + artifact: 'file_result.pcap' + publishLocation: 'pipeline' +``` + +For more information, see [Publish Pipeline Artifacts](../publish-pipeline-artifact.md). + +### Capture resource utilization details + +When using Azure DevOps Services, you can see resource utilization in the logs, including disk usage, memory usage, and CPU utilization, by enabling [verbose logs](#configure-verbose-logs). When the pipeline completes, [search the logs](#view-and-download-logs) for `Agent environment resources` entries for each step. + +``` +2024-02-28T17:41:15.1315148Z ##[debug]Agent environment resources - Disk: D:\ Available 12342.00 MB out of 14333.00 MB, Memory: Used 1907.00 MB out of 7167.00 MB, CPU: Usage 17.23% +``` + +If you are using Azure DevOps Server, or if you want to collect additional metrics, you can use PowerShell to capture resource utilization and upload it to the pipeline logs. When the pipeline run completes, you can [download the pipeline logs and view the captured data](#view-and-download-logs). If the `Upload resource usage from pipeline run` step is the sixth step in the job, the filename in the logs will be **6_resource-usage.txt**. + +```yml +# Place this task in your pipeline to log the current resource utilization +# of the pipeline. This task appends the specified resource usage to a logfile +# which is uploaded at the end of the current pipeline job. +- pwsh: | + $logFile = '$(Agent.TempDirectory)\resource-usage.txt' + if (!(Test-Path $logFile)) + { + New-Item $logFile + } + Get-Date | Out-File -FilePath $logFile -Append + Get-Volume | Out-File -FilePath $logFile -Append + Get-Counter '\Memory\Available MBytes' | Out-File -FilePath $logFile -Append + Get-Counter '\Processor(_Total)\% Processor Time' | Out-File -FilePath $logFile -Append + sleep 10 + displayName: 'Check resource utilization' + +# Other tasks here, and you can repeat the "Check resource utilization" +# step if desired, and the results will be appended to the resource-usage.txt file + +- pwsh: Write-Host "##vso[task.uploadfile]$(Agent.TempDirectory)\resource-usage.txt" + displayName: 'Upload resource usage from pipeline run' + condition: always() +``` + +### Capture a dotnet process memory dump using ProcDump + +If you have a test execution that crashes, customer support may ask you to capture a memory dump of the dotnet process after the failed test execution. Add the following task after your Visual Studio Test task with `condition: always()`. When the pipeline run completes, you can [download the pipeline logs, including the memory dump](./review-logs.md#view-and-download-logs). + +```yml +# Run this task after your test execution crashes +# with a condition of alway() so that it always runs +- pwsh: | + Invoke-WebRequest https://download.sysinternals.com/files/Procdump.zip -OutFile $(Agent.TempDirectory)\Procdump.zip + mkdir $(Agent.TempDirectory)\Procdump + unzip $(Agent.TempDirectory)\Procdump.zip -d Procdump + cd $(Agent.TempDirectory)\Procdump + Get-Process dotnet | % { $(Agent.TempDirectory)\procdump.exe -accepteula -ma $_.Id dotnet-$($_.Id).dmp } + Compress-Archive *.dmp -DestinationPath $(Agent.TempDirectory)\dump_files.zip + Write-Host "##vso[task.uploadfile]$(Agent.TempDirectory)\dump_files.zip" + condition: always() + displayName: 'Create and upload a dotnet process memory dump' +``` + +### Capture ETW traces for a hosted agent + +If you are troubleshooting network issues with Microsoft-hosted agents, customer support may ask you to collect ETW traces. When the pipeline run completes, you can [download the pipeline logs, including the ETW traces](./review-logs.md#view-and-download-logs). + +#### [Windows agent](#tab/windows-agent/) + +```yml +# Add this task to start the ETW trace +- script: netsh trace start scenario=InternetClient capture=yes tracefile=$(Agent.TempDirectory)\networktrace.etl + displayName: 'Start ETW trace' + +# Other tasks here + +# Add these 2 tasks to stop the trace and upload +# the trace to the pipeline logs +- script: netsh trace stop + displayName: 'Stop ETW trace' + +- pwsh: | + Write-Host "##vso[task.uploadfile]$(Agent.TempDirectory)\networktrace.etl" + Write-Host "##vso[task.uploadfile]$(Agent.TempDirectory)\networktrace.cab" + displayName: 'Upload ETW trace logs' +``` +#### [Linux agent](#tab/linux-agent/) + +```yml +- task: Bash@3 + inputs: + targetType: 'inline' + script: | + sudo rm -f nohup.out + sudo rm -R trace + sudo mkdir trace + sudo nohup tcpdump -i eth0 -s 65535 -w trace/file_result.pcap & + cd trace + ls + +# Add tasks that perform actions that you want to trace here + +# Upload the trace to a pipeline artifact +- task: PublishPipelineArtifact@1 + inputs: + targetPath: '$(Pipeline.Workspace)/s/trace' + artifact: 'file_result.pcap' + publishLocation: 'pipeline' +``` + +* * * + +### Capture :::no-loc text="perfview"::: traces for Visual Studio build + +If customer support asks you to create a :::no-loc text="perfview"::: trace of your Visual Studio build, add the following tasks to your pipeline before and after your Visual Studio build step. + +After running the pipeline, you can download the **PerfViewLog** artifact from the [pipeline run details](../create-first-pipeline.md#view-pipeline-run-details) and send that file customer support. + +```yml +steps: +- task: PowerShell@2 # download the perfview exe + inputs: + targetType: 'inline' + script: | + invoke-webrequest https://github.com/microsoft/perfview/releases/download/v3.1.7/PerfView.exe -OutFile PerfView.exe + +- task: PowerShell@2 + inputs: + targetType: 'inline' # start perfview to capture the traces before build build task + script: '$(System.DefaultWorkingDirectory)\PerfView.exe "/DataFile:PerfViewData.etl" /accepteula /BufferSizeMB:512 /StackCompression /CircularMB:5000 /Providers:"Microsoft-Windows-IIS" /logfile:"PerfView.log" /zip:true /norundown start' + +- task: VSBuild@1 + displayName: '$(solution)' # build of the solution, note the msbuildargs might be different for your scenario + inputs: + solution: '$(solution)' + clean: true + msbuildArgs: '/p:DeployOnBuild=true /p:PrecompileBeforePublish=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:PackageLocation="$(Build.ArtifactStagingDirectory)" /p:TransformWebConfigEnabled=false /p:AutoParameterizationWebConfigConnectionStrings=false /p:MarkWebConfigAssistFilesAsExclude=false /p:ProfileTransformWebConfigEnabled=false /p:IsTransformWebConfigDisabled=true' + platform: '$(buildPlatform)' + configuration: '$(buildConfiguration)' + +- task: PowerShell@2 # stop the perfview tracing + inputs: + targetType: 'inline' + script: | + $(System.DefaultWorkingDirectory)\perfview.exe /accepteula /logfile:"PerfView.log" stop + +- task: PowerShell@2 # abort perfview, it seems required. + inputs: + targetType: 'inline' + script: '$(System.DefaultWorkingDirectory)\perfview.exe /accepteula /logfile:"PerfView.log" abort' + +- task: PowerShell@2 # add a sleep of 5 mins, to give it time for required traces to be complete + inputs: + targetType: 'inline' + script: 'Start-Sleep -Seconds 300' + +- task: PublishPipelineArtifact@1 # upload the traces + displayName: 'Publish Pipeline Artifact' + inputs: + artifactName: webapp +``` diff --git a/docs/pipelines/troubleshooting/troubleshoot-start.md b/docs/pipelines/troubleshooting/troubleshoot-start.md new file mode 100644 index 00000000000..0fba1d25d32 --- /dev/null +++ b/docs/pipelines/troubleshooting/troubleshoot-start.md @@ -0,0 +1,205 @@ +--- +title: Troubleshoot pipeline failure to start +description: Learn how to troubleshoot pipeline starting issues in Azure Pipelines and Team Foundation Server. +ms.assetid: BFCB144F-9E9B-4FCB-9CD1-260D6873BC2E +ms.author: sdanie +ms.reviewer: steved0x +ms.topic: troubleshooting +ms.date: 04/02/2024 +monikerRange: '<= azure-devops' +author: steved0x +--- + +# Troubleshoot pipeline failure to start + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +If your pipeline queues but never starts, check the following items. + +::: moniker range="azure-devops" + +* [Parallel job limits - no available agents or you have hit your free limits](#parallel-job-limits---no-available-agents-or-you-have-hit-your-free-limits) +* [Can't access Azure Key Vault behind firewall from Azure DevOps](#cant-access-azure-key-vault-behind-firewall-from-azure-devops) +* [You don't have enough concurrency](#you-dont-have-enough-concurrency) +* [Your job might be waiting for approval](#your-job-might-be-waiting-for-approval) +* [All available agents are in use](#all-available-agents-are-in-use) +* [Demands that don't match the capabilities of an agent](#demands-that-dont-match-the-capabilities-of-an-agent) +* [Check Azure DevOps status for a service degradation](#check-azure-devops-status-for-a-service-degradation) + +> [!NOTE] +> The following scenarios won't consume a parallel job: +> * If you use release pipelines or multi-stage YAML pipelines, then a run consumes a parallel job only when it's being actively deployed to a stage. While the release is waiting for an approval or a manual intervention, it doesn't consume a parallel job. +> * When you run a server job or deploy to a deployment group using release pipelines, you don't consume any parallel jobs. +> +> Learn more: +> [How a parallel job is consumed by a pipeline](../licensing/concurrent-jobs.md), +> [Add Pre-deployment approvals](../release/define-multistage-release-process.md#add-pre-deployment-approvals), +> [Server jobs](../process/phases.md#server-jobs), +> [Deployment groups](../release/deployment-groups/index.md) + +::: moniker-end + +::: moniker range="< azure-devops" + +* [Parallel job limits - no available agents or you have hit your free limits](#parallel-job-limits---no-available-agents-or-you-have-hit-your-free-limits) +* [Demands that don't match the capabilities of an agent](#demands-that-dont-match-the-capabilities-of-an-agent) +* [TFS agent connection issues](#tfs-agent-connection-issues) + +::: moniker-end + + + +## Parallel job limits - no available agents or you have hit your free limits + +::: moniker range="azure-devops" + +If you're currently running other pipelines, you might not have any remaining parallel jobs, or you might have hit your [free limits](../licensing/concurrent-jobs.md). + +### Check for available parallel jobs + +> [!NOTE] +> Azure Pipelines has temporarily disabled the automatic free grant of Microsoft-hosted parallel jobs in new organizations for public projects and for certain private projects. If you don't have any parallel jobs, your pipelines will fail with the following error: `##[error]No hosted parallelism has been purchased or granted. To request a free parallelism grant, please fill out the following form https://aka.ms/azpipelines-parallelism-request`. Check your Microsoft-hosted parallel jobs as described in the following section, and if you have zero parallel jobs, you can request a free grant of parallel jobs. To request the free grant of parallel jobs for your organization, submit [a request](https://aka.ms/azpipelines-parallelism-request). Your request can take several business days to process. + +To check your limits, navigate to **Project settings**, **Parallel jobs**. + +![Pipelines concurrent jobs](../media/troubleshooting/concurrent-pipeline-limits.png) + +If you're using [Microsoft-hosted](../agents/hosted.md) agents, check the parallel job limits for **Microsoft-hosted** for **Private projects** or **Public projects**, depending on whether your Azure DevOps project is a [private project (default) or public project](../../organizations/projects/make-project-public.md). + +After reviewing the limits, check concurrency to see how many jobs are currently running and how many are available. + +::: moniker-end + +::: moniker range="< azure-devops" + +If you're currently running other pipelines, you might not have any remaining parallel jobs, or you might have hit your [free limits](../licensing/concurrent-pipelines-tfs.md). + +::: moniker-end + +::: moniker range="azure-devops" + +## Can't access Azure Key Vault behind firewall from Azure DevOps + +If you can't access Azure Key Vault from your pipeline, the firewall might be blocking the Azure DevOps Services agent IP address. The IP addresses published in the [weekly JSON file](https://www.microsoft.com/download/details.aspx?id=56519) must be allowlisted. For more information, see [Microsoft-hosted agents: Networking](../agents/hosted.md#networking). + +## You don't have enough concurrency + +To check how much concurrency you have: + +1. To check your limits, navigate to **Project settings**, **Parallel jobs**. + + ![Concurrent pipeline limits](../media/troubleshooting/in-progress-jobs-link.png) + + You can also reach this page by navigating to `https://dev.azure.com/{org}/_settings/buildqueue?_a=concurrentJobs`, or choosing **manage parallel jobs** from the logs. + + ![Manage parallel jobs](../media/troubleshooting/manage-parallel-jobs.png) + +2. Determine which pool you want to check concurrency on (Microsoft hosted or self hosted pools), and choose **View in-progress jobs**. + +3. You'll see text that says **Currently running X/X jobs**. If both numbers are the same, pending jobs will wait until currently running jobs complete. + + ![View in-progress jobs](../media/troubleshooting/view-in-progress-jobs.png) + + You can view all jobs, including queued jobs, by selecting **Agent pools** from the **Project settings**. + + ![View queued jobs](../media/troubleshooting/agent-pools-jobs.png) + + In this example, the concurrent job limit is one, with one job running and one queued up. When all agents are busy running jobs, as in this example, the following message is displayed when additional jobs are queued: `The agent request is not running because all potential agents are running other requests. Current position in queue: 1`. In this example the job is next in the queue so its position is one. + +## Your job might be waiting for approval + +Your pipeline might not move to the next stage because it's waiting on approval. For more information, see [Define approvals and checks](../process/approvals.md). + +## All available agents are in use + +Jobs might wait if all your agents are currently busy. To check your agents: +1. Navigate to `https://dev.azure.com/{org}/_settings/agentpools` +2. Select the agent pool to check, in this example **FabrikamPool**, and choose **Agents**. + + ![Agent status](../media/troubleshooting/agents-online.png) + + This page shows all the agents currently online/offline and in use. You can also add additional agents to the pool from this page. + +::: moniker-end + +## Demands that don't match the capabilities of an agent + +If your pipeline has demands that don't meet the capabilities of any of your agents, your pipeline won't start. If only some of your agents have the desired capabilities and they're currently running other pipelines, your pipeline will be stalled until one of those agents becomes available. + +To check the capabilities and demands specified for your agents and pipelines, see [Capabilities](../agents/agents.md#capabilities). + +::: moniker range="azure-devops" + +> [!NOTE] +> Capabilities and demands are typically used only with self-hosted agents. If your pipeline has demands that don't match the system capabilities of the agent, unless you have explicitly labeled the agents with matching capabilities, your pipelines won't get an agent. + +::: moniker-end + +::: moniker range="< azure-devops" + +## TFS agent connection issues + +* [Config fails while testing agent connection (on-premises TFS only)](#config-fails-while-testing-agent-connection-on-premises-tfs-only) +* [Agent lost communication](#agent-lost-communication) +* [TFS Job Agent not started](#tfs-job-agent-not-started) +* [Misconfigured notification URL (1.x agent version)](#misconfigured-notification-url-1x-agent-version) + +#### Config fails while testing agent connection (on-premises TFS only) + +``` +Testing agent connection. +VS30063: You are not authorized to access http://:8080/tfs +``` + +If the above error is received while configuring the agent, log on to your TFS machine. Start the Internet Information Services (IIS) manager. Make sure **Anonymous Authentication** is enabled. + +![is TFS anonymous authentication enabled](../media/troubleshooting/iis-tfs-anonymous-authentication-enabled.png) + + + + +### Agent lost communication + +This issue is characterized by the error message: +``` +The job has been abandoned because agent did not renew the lock. Ensure agent is running, not sleeping, and has not lost communication with the service. +``` + +This error might indicate the agent lost communication with the server for a span of several minutes. Check the following to rule out network or other interruptions on the agent machine: + +* Verify automatic updates are turned off. A machine reboot from an update will cause a build or release to fail with the above error. Apply updates in a controlled fashion to avoid this type of interruption. Before rebooting the agent machine, mark the agent as disabled in the pool administration page and let any running build finish. +* Verify the sleep settings are turned off. +* If the agent is running on a virtual machine, avoid any live migration or other VM maintenance operation that might severely impact the health of the machine for multiple minutes. +* If the agent is running on a virtual machine, the same operating-system-update recommendations and sleep-setting recommendations apply to the host machine. And also any other maintenance operations that several impact the host machine. +* Performance monitor logging or other health metric logging can help to correlate this type of error to constrained resource availability on the agent machine (disk, memory, page file, processor, network). +* Another way to correlate the error with network problems is to ping a server indefinitely and dump the output to a file, along with timestamps. Use a healthy interval, for example 20 or 30 seconds. If you're using Azure Pipelines, then you would want to ping an internet domain, for example bing.com. If you're using an on-premises TFS server, then you would want to ping a server on the same network. +* Verify the network throughput of the machine is adequate. You can perform an online speed test to check the throughput. +* If you use a proxy, verify the agent is configured to use your proxy. Refer to the agent deployment topic. + +### TFS Job Agent not started + +This might be characterized by a message in the web console "Waiting for an agent to be requested." Verify the TFSJobAgent (display name: *Visual Studio Team Foundation Background Job Agent*) Windows service is started. + +### Misconfigured notification URL (1.x agent version) + +This might be characterized by a message in the web console "Waiting for console output from an agent," and the process eventually times out. + +A mismatching notification URL might cause the worker to process to fail to connect to the server. See *Team Foundation Administration Console*, *Application Tier*. The 1.x agent listens to the message queue using the URL that it was configured with. However, when a job message is pulled from the queue, the worker process uses the notification URL to communicate back to the server. + +::: moniker-end + +::: moniker range="azure-devops" + +## Check Azure DevOps status for a service degradation + +Check the [Azure DevOps Service Status Portal](https://status.dev.azure.com/) for any issues that might cause a service degradation, such as increased queue time for agents. For more information, see [Azure DevOps Service Status](../../user-guide/service-status-info.md). + +::: moniker-end + +## I need more help. I found a bug. I've got a suggestion. Where do I go? + +[Get subscription, billing, and technical support](https://azure.microsoft.com/support/devops/) + +Report any problems or submit feedback at [Developer Community](https://developercommunity.visualstudio.com/). + +We welcome your suggestions: diff --git a/docs/pipelines/troubleshooting/troubleshoot-triggers.md b/docs/pipelines/troubleshooting/troubleshoot-triggers.md new file mode 100644 index 00000000000..3e4e775a552 --- /dev/null +++ b/docs/pipelines/troubleshooting/troubleshoot-triggers.md @@ -0,0 +1,126 @@ +--- +title: Troubleshoot pipeline triggers +description: Learn how to troubleshoot pipeline triggers in Azure Pipelines and Team Foundation Server. +ms.assetid: BFCB144F-9E9B-4FCB-9CD1-260D6873BC2E +ms.author: sdanie +ms.reviewer: steved0x +ms.topic: troubleshooting +ms.date: 04/02/2024 +monikerRange: '<= azure-devops' +author: steved0x +--- + +# Troubleshoot pipeline triggers + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +If a pipeline doesn't start at all, check the following common trigger related issues. + +::: moniker range=">=azure-devops-2022" + +* [UI settings override YAML trigger setting](#ui-settings-override-yaml-trigger-setting) +* [Disable implied YAML CI trigger setting is enabled](#disable-implied-yaml-ci-trigger-setting-is-enabled) +* [Pull request triggers not supported with Azure Repos](#pull-request-triggers-not-supported-with-azure-repos) +* [Branch filters misconfigured in CI and PR triggers](#branch-filters-misconfigured-in-ci-and-pr-triggers) +* [Scheduled trigger time zone conversions](#scheduled-trigger-time-zone-conversions) +* [UI settings override YAML scheduled triggers](#ui-settings-override-yaml-scheduled-triggers) + +::: moniker-end + +::: moniker range=" [!NOTE] +> An additional reason that runs may not start is that your organization goes dormant five minutes after the last user signs out of Azure DevOps. After that, each of your build pipelines will run one more time. For example, while your organization is dormant: +> * A nightly build of code in your organization will run only one night until someone signs in again. +> * CI builds of an Other Git repo will stop running until someone signs in again. + +::: moniker-end + + + +## UI settings override YAML trigger setting + +YAML pipelines can have their `trigger` and `pr` trigger settings overridden in the pipeline settings UI. If your `trigger` or `pr` triggers don't seem to be firing, check that setting. While editing your pipeline, choose **...** and then **Triggers**. + +![Pipeline settings UI](../repos/media/pipelines-options-for-git/yaml-pipeline-git-options-menu.png) + +Check the **Override the YAML trigger from here** setting for the types of trigger (**Continuous integration** or **Pull request validation**) available for your repo. + +![Override YAML trigger from here.](../repos/media/pipelines-options-for-git/yaml-pipeline-override-trigger.png) + + + +## Pull request triggers not supported with Azure Repos + +If your `pr` trigger isn't firing, and you are using Azure Repos, it is because `pr` triggers aren't supported for Azure Repos. In Azure Repos Git, branch policies are used to implement pull request build validation. For more information, see [Branch policy for pull request validation](../repos/azure-repos-git.md#pr-triggers). + +:::moniker range=">=azure-devops-2022" + +## Disable implied YAML CI trigger setting is enabled + +:::moniker-end + +:::moniker range="=azure-devops-2022" + +[!INCLUDE [feature-added-2022-2](../../includes/feature-added-2022-2.md)] + +:::moniker-end + +:::moniker range=">=azure-devops-2022" + +YAML pipelines are configured by default with a CI trigger on all branches, unless the [Disable implied YAML CI trigger](/azure/devops/release-notes/2023/sprint-227-update#prevent-unintended-pipeline-runs) setting, introduced in [Azure DevOps sprint 227](/azure/devops/release-notes/2023/sprint-227-update), is enabled. The **Disable implied YAML CI trigger** setting can be configured at the organization level or at the project level, and by default, the setting is not enabled. + +If your pipelines use the default implicit CI trigger, and they stop working, check this setting. When the **Disable implied YAML CI trigger** setting is enabled, CI triggers for YAML pipelines are not enabled if the YAML pipeline doesn't have a `trigger` section. + +:::moniker-end + + + +## Branch filters misconfigured in CI and PR triggers + +::: moniker range="<=azure-devops" + +When you define a YAML PR or CI trigger, you can specify both `include` and `exclude` clauses for branches, tags, and paths. Ensure that the `include` clause matches the details of your commit and that the `exclude` clause doesn't exclude them. For more information, see [pr](/azure/devops/pipelines/yaml-schema/pr) and [trigger](/azure/devops/pipelines/yaml-schema/trigger). + +> [!NOTE] +> If you specify an `exclude` clause without an `include` clause, it is equivalent to specifying `*` in the `include` clause. + +::: moniker-end + + + +## Scheduled trigger time zone conversions + +YAML scheduled triggers are set using UTC time zone. If your scheduled triggers don't seem to be firing at the right time, confirm the conversions between UTC and your local time zone, taking into account the day setting as well. For more information, see [Scheduled triggers](../process/scheduled-triggers.md). + +## UI settings override YAML scheduled triggers + +If your YAML pipeline has both YAML scheduled triggers and UI defined scheduled triggers, only the UI defined scheduled triggers are run. To run the YAML defined scheduled triggers in your YAML pipeline, you must remove the scheduled triggers defined in the pipeline settings UI. + +To access the pipeline settings UI from a YAML pipeline, edit your pipeline, choose **...** and then **Triggers**. + +![Pipeline settings UI](../repos/media/pipelines-options-for-git/yaml-pipeline-git-options-menu.png) + +Remove all scheduled triggers. + +:::image type="content" source="../process/media/triggers/delete-ui-scheduled-trigger.png" alt-text="Delete scheduled triggers in the Pipeline settings UI."::: + +Once all UI scheduled triggers are removed, a push must be made in order for the YAML scheduled triggers to start running. For more information, see [Scheduled triggers](../process/scheduled-triggers.md). + +## I need more help. I found a bug. I've got a suggestion. Where do I go? + +[Get subscription, billing, and technical support](https://azure.microsoft.com/support/devops/) + +Report any problems or submit feedback at [Developer Community](https://developercommunity.visualstudio.com/). + +We welcome your suggestions: diff --git a/docs/pipelines/troubleshooting/troubleshooting.md b/docs/pipelines/troubleshooting/troubleshooting.md index 99aef60ad3f..71dbede4213 100644 --- a/docs/pipelines/troubleshooting/troubleshooting.md +++ b/docs/pipelines/troubleshooting/troubleshooting.md @@ -1,12 +1,11 @@ --- title: Troubleshoot pipeline runs -description: Learn how to troubleshoot pipeline runs in Azure Pipelines and Team Foundation Server. +description: Learn how to troubleshoot pipeline runs in Azure Pipelines using logs, error analysis tools, and common techniques to resolve issues. ms.assetid: BFCB144F-9E9B-4FCB-9CD1-260D6873BC2E ms.author: sdanie ms.reviewer: steved0x -ms.custom: seodec18, contperf-fy20q4 -ms.topic: troubleshooting -ms.date: 06/06/2023 +ms.topic: how-to +ms.date: 03/25/2025 monikerRange: '<= azure-devops' author: steved0x --- @@ -15,299 +14,67 @@ author: steved0x [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -This topic provides guidance on the common reasons that pipelines fail to [trigger](#pipeline-wont-trigger), [get an agent and start](#pipeline-queues-but-never-starts), or [complete](#pipeline-fails-to-complete). For instructions on reviewing pipeline logs, see [Review logs to diagnose pipeline issues](review-logs.md). +If your pipeline run fails to complete, use the diagnostic information and logs on the pipeline run summary page to troubleshoot the issue. This guide provides instructions for diagnosing pipeline failures using logs, error analysis tools, and common troubleshooting techniques. Learn how to identify root causes and implement solutions to keep your pipelines running smoothly. -> [!NOTE] -> If your pipeline run failed and you were directed to this article from the **Troubleshooting failed runs** link in the Azure DevOps portal: -> 1. Review the common causes in [Pipeline fails to complete](#pipeline-fails-to-complete). -> 2. Follow the troubleshooting steps in [Review logs to diagnose pipeline issues](review-logs.md). - -::: moniker range="tfs-2018" - -[!INCLUDE [temp](../includes/concept-rename-note.md)] - -::: moniker-end - -You can use the following troubleshooting sections to help diagnose issues with your pipeline. Most pipeline failures fall into one of these categories. - -* [Pipeline won't trigger](#pipeline-wont-trigger) -* [Pipeline queues but never starts](#pipeline-queues-but-never-starts) -* [Pipeline fails to complete](#pipeline-fails-to-complete) - - -For specific troubleshooting about .NET Core, see [.NET Core troubleshooting](../ecosystems/dotnet-core.md#troubleshooting). - - -## Pipeline won't trigger - -If a pipeline doesn't start at all, check the following common trigger related issues. - -* [UI settings override YAML trigger setting](#ui-settings-override-yaml-trigger-setting) -* [Pull request triggers not supported with Azure Repos](#pull-request-triggers-not-supported-with-azure-repos) -* [Branch filters misconfigured in CI and PR triggers](#branch-filters-misconfigured-in-ci-and-pr-triggers) -* [Scheduled trigger time zone conversions](#scheduled-trigger-time-zone-conversions) -* [UI settings override YAML scheduled triggers](#ui-settings-override-yaml-scheduled-triggers) - -::: moniker range="azure-devops" - -> [!NOTE] -> An additional reason that runs may not start is that your organization goes dormant five minutes after the last user signs out of Azure DevOps. After that, each of your build pipelines will run one more time. For example, while your organization is dormant: -> * A nightly build of code in your organization will run only one night until someone signs in again. -> * CI builds of an Other Git repo will stop running until someone signs in again. - -::: moniker-end - - - -### UI settings override YAML trigger setting - -YAML pipelines can have their `trigger` and `pr` trigger settings overridden in the pipeline settings UI. If your `trigger` or `pr` triggers don't seem to be firing, check that setting. While editing your pipeline, choose **...** and then **Triggers**. - -![Pipeline settings UI](../repos/media/pipelines-options-for-git/yaml-pipeline-git-options-menu.png) - -Check the **Override the YAML trigger from here** setting for the types of trigger (**Continuous integration** or **Pull request validation**) available for your repo. - -![Override YAML trigger from here.](../repos/media/pipelines-options-for-git/yaml-pipeline-override-trigger.png) - - - -### Pull request triggers not supported with Azure Repos - -If your `pr` trigger isn't firing, and you are using Azure Repos, it is because `pr` triggers aren't supported for Azure Repos. In Azure Repos Git, branch policies are used to implement pull request build validation. For more information, see [Branch policy for pull request validation](../repos/azure-repos-git.md#pr-triggers). - - - -### Branch filters misconfigured in CI and PR triggers - -::: moniker range="azure-devops-2019" - -When you define a YAML PR or CI trigger, you can specify both `include` and `exclude` clauses for branches and paths. Ensure that the `include` clause matches the details of your commit and that the `exclude` clause doesn't exclude them. - -> [!IMPORTANT] -> When you define a YAML PR or CI trigger, only branches explicitly configured to be included will trigger a run. Includes are processed first, and then excludes are removed from the list. If you specify an exclude but don't specify any includes, nothing will trigger. For more information, see [pr](/azure/devops/pipelines/yaml-schema/pr) and [trigger](/azure/devops/pipelines/yaml-schema/trigger). - -::: moniker-end - -::: moniker range="> azure-devops-2019" - -When you define a YAML PR or CI trigger, you can specify both `include` and `exclude` clauses for branches, tags, and paths. Ensure that the `include` clause matches the details of your commit and that the `exclude` clause doesn't exclude them. For more information, see [pr](/azure/devops/pipelines/yaml-schema/pr) and [trigger](/azure/devops/pipelines/yaml-schema/trigger). - -> [!NOTE] -> If you specify an `exclude` clause without an `include` clause, it is equivalent to specifying `*` in the `include` clause. - -::: moniker-end - - - -### Scheduled trigger time zone conversions - -YAML scheduled triggers are set using UTC time zone. If your scheduled triggers don't seem to be firing at the right time, confirm the conversions between UTC and your local time zone, taking into account the day setting as well. For more information, see [Scheduled triggers](../process/scheduled-triggers.md). - -### UI settings override YAML scheduled triggers - -If your YAML pipeline has both YAML scheduled triggers and UI defined scheduled triggers, only the UI defined scheduled triggers are run. To run the YAML defined scheduled triggers in your YAML pipeline, you must remove the scheduled triggers defined in the pipeline settings UI. - -To access the pipeline settings UI from a YAML pipeline, edit your pipeline, choose **...** and then **Triggers**. - -![Pipeline settings UI](../repos/media/pipelines-options-for-git/yaml-pipeline-git-options-menu.png) - -Remove all scheduled triggers. - -:::image type="content" source="../process/media/triggers/delete-ui-scheduled-trigger.png" alt-text="Delete scheduled triggers in the Pipeline settings UI."::: - -Once all UI scheduled triggers are removed, a push must be made in order for the YAML scheduled triggers to start running. For more information, see [Scheduled triggers](../process/scheduled-triggers.md). - - - -## Pipeline queues but never starts - -If your pipeline queues but never starts, check the following items. - -::: moniker range="azure-devops" - -* [Parallel job limits - no available agents or you have hit your free limits](#parallel-job-limits---no-available-agents-or-you-have-hit-your-free-limits) -* [Can't access Azure Key Vault behind firewall from Azure DevOps](#cant-access-azure-key-vault-behind-firewall-from-azure-devops) -* [You don't have enough concurrency](#you-dont-have-enough-concurrency) -* [Your job may be waiting for approval](#your-job-may-be-waiting-for-approval) -* [All available agents are in use](#all-available-agents-are-in-use) -* [Demands that don't match the capabilities of an agent](#demands-that-dont-match-the-capabilities-of-an-agent) -* [Check Azure DevOps status for a service degradation](#check-azure-devops-status-for-a-service-degradation) - -> [!NOTE] -> The following scenarios won't consume a parallel job: -> * If you use release pipelines or multi-stage YAML pipelines, then a run consumes a parallel job only when it's being actively deployed to a stage. While the release is waiting for an approval or a manual intervention, it does not consume a parallel job. -> * When you run a server job or deploy to a deployment group using release pipelines, you don't consume any parallel jobs. -> -> Learn more: -> [How a parallel job is consumed by a pipeline](../licensing/concurrent-jobs.md), -> [Add Pre-deployment approvals](../release/define-multistage-release-process.md#add-approvals), -> [Server jobs](../process/phases.md#server-jobs), -> [Deployment groups](../release/deployment-groups/index.md) - -::: moniker-end - -::: moniker range="< azure-devops" - -* [Parallel job limits - no available agents or you have hit your free limits](#parallel-job-limits---no-available-agents-or-you-have-hit-your-free-limits) -* [Demands that don't match the capabilities of an agent](#demands-that-dont-match-the-capabilities-of-an-agent) -* [TFS agent connection issues](#tfs-agent-connection-issues) - -::: moniker-end +:::image type="content" source="./media/pipeline-run-summary-troubleshooting.png" lightbox="./media/pipeline-run-summary-troubleshooting.png" alt-text="Screenshot of pipeline run summary page with diagnostic information."::: + +## View logs -### Parallel job limits - no available agents or you have hit your free limits +Select the error message to view logs for the task that didn't complete. -::: moniker range="azure-devops" - -If you are currently running other pipelines, you may not have any remaining parallel jobs, or you may have hit your [free limits](../licensing/concurrent-jobs.md). - -#### Check for available parallel jobs - -> [!NOTE] -> Azure Pipelines has temporarily disabled the automatic free grant of Microsoft-hosted parallel jobs in new organizations for public projects and for certain private projects. If you don't have any parallel jobs, your pipelines will fail with the following error: `##[error]No hosted parallelism has been purchased or granted. To request a free parallelism grant, please fill out the following form https://aka.ms/azpipelines-parallelism-request`. Check your Microsoft-hosted parallel jobs as described in the following section, and if you have zero parallel jobs, you can request a free grant of parallel jobs. To request the free grant of parallel jobs for your organization, submit [a request](https://aka.ms/azpipelines-parallelism-request). Please allow 2-3 business days to respond to your grant request. - -To check your limits, navigate to **Project settings**, **Parallel jobs**. - -![Pipelines concurrent jobs](../media/troubleshooting/concurrent-pipeline-limits.png) - -If you are using [Microsoft-hosted](../agents/hosted.md) agents, check the parallel job limits for **Microsoft-hosted** for **Private projects** or **Public projects**, depending on whether your Azure DevOps project is a [private project (default) or public project](../../organizations/projects/make-project-public.md). - -After reviewing the limits, check concurrency to see how many jobs are currently running and how many are available. - -::: moniker-end - -::: moniker range="< azure-devops" - -If you are currently running other pipelines, you may not have any remaining parallel jobs, or you may have hit your [free limits](../licensing/concurrent-pipelines-tfs.md). - -::: moniker-end - -::: moniker range="azure-devops" - -### Can't access Azure Key Vault behind firewall from Azure DevOps - -If you can't access Azure Key Vault from your pipeline, the firewall might be blocking the Azure DevOps Services agent IP address. The IP addresses published in the [weekly JSON file](https://www.microsoft.com/download/details.aspx?id=56519) must be allowlisted. For more information, see [Microsoft-hosted agents: Networking](../agents/hosted.md#networking). - -### You don't have enough concurrency - -To check how much concurrency you have: - -1. To check your limits, navigate to **Project settings**, **Parallel jobs**. - - ![Concurrent pipeline limits](../media/troubleshooting/in-progress-jobs-link.png) - - You can also reach this page by navigating to `https://dev.azure.com/{org}/_settings/buildqueue?_a=concurrentJobs`, or choosing **manage parallel jobs** from the logs. - - ![Manage parallel jobs](../media/troubleshooting/manage-parallel-jobs.png) - -2. Determine which pool you want to check concurrency on (Microsoft hosted or self hosted pools), and choose **View in-progress jobs**. - -3. You'll see text that says **Currently running X/X jobs**. If both numbers are the same, pending jobs will wait until currently running jobs complete. - - ![View in-progress jobs](../media/troubleshooting/view-in-progress-jobs.png) - - You can view all jobs, including queued jobs, by selecting **Agent pools** from the **Project settings**. - - ![View queued jobs](../media/troubleshooting/agent-pools-jobs.png) - - In this example, the concurrent job limit is one, with one job running and one queued up. When all agents are busy running jobs, as in this example, the following message is displayed when additional jobs are queued: `The agent request is not running because all potential agents are running other requests. Current position in queue: 1`. In this example the job is next in the queue so its position is one. - -### Your job may be waiting for approval - -Your pipeline may not move to the next stage because it is waiting on approval. For more information, see [Define approvals and checks](../process/approvals.md). - -### All available agents are in use - -Jobs may wait if all your agents are currently busy. To check your agents: -1. Navigate to `https://dev.azure.com/{org}/_settings/agentpools` -2. Select the agent pool to check, in this example **FabrikamPool**, and choose **Agents**. - - ![Agent status](../media/troubleshooting/agents-online.png) - - This page shows all the agents currently online/offline and in use. You can also add additional agents to the pool from this page. - -::: moniker-end - -### Demands that don't match the capabilities of an agent - -If your pipeline has demands that don't meet the capabilities of any of your agents, your pipeline won't start. If only some of your agents have the desired capabilities and they are currently running other pipelines, your pipeline will be stalled until one of those agents becomes available. - -To check the capabilities and demands specified for your agents and pipelines, see [Capabilities](../agents/agents.md#capabilities). - -::: moniker range="azure-devops" - -> [!NOTE] -> Capabilities and demands are typically used only with self-hosted agents. If your pipeline has demands that don't match the system capabilities of the agent, unless you have explicitly labelled the agents with matching capabilities, your pipelines won't get an agent. +:::image type="content" source="./media/error-message.png" alt-text="Screenshot of a task error message on pipeline run summary page."::: -::: moniker-end - -::: moniker range="< azure-devops" +The logs page shows the selected error. In this example, there's an error in the `cmd-line` task, where the `echo` command is entered as `ech`. -### TFS agent connection issues +:::image type="content" source="./media/task-error-log.png" lightbox="./media/task-error-log.png" alt-text="Screenshot of diagnostics log for the pipeline run."::: -* [Config fails while testing agent connection (on-premises TFS only)](#config-fails-while-testing-agent-connection-on-premises-tfs-only) -* [Agent lost communication](#agent-lost-communication) -* [TFS Job Agent not started](#tfs-job-agent-not-started) -* [Misconfigured notification URL (1.x agent version)](#misconfigured-notification-url-1x-agent-version) +You can view the raw log for the task by choosing **View raw log**, and you can search the log using **Find**. -#### Config fails while testing agent connection (on-premises TFS only) +:::image type="content" source="./media/view-raw-log.png" alt-text="Screenshot of log view options in Azure DevOps."::: -``` -Testing agent connection. -VS30063: You are not authorized to access http://:8080/tfs -``` +Scan the logs of the failing task for error information and clues as to why the task is failing. By default, nonverbose logs are generated by a pipeline run. If the default logs don't indicate the cause of the issue, you can get more information by [configuring verbose logs](./review-logs.md#configure-verbose-logs). -If the above error is received while configuring the agent, log on to your TFS machine. Start the Internet Information Services (IIS) manager. Make sure **Anonymous Authentication** is enabled. +:::moniker range=">= azure-devops-2020" -![is TFS anonymous authentication enabled](../media/troubleshooting/iis-tfs-anonymous-authentication-enabled.png) +## Error analysis page - - +Troubleshooting assistance is available using the **Error analysis** page. Move the mouse over the error information line and choose the **View analysis** icon. -#### Agent lost communication +:::moniker-end -This issue is characterized by the error message: -``` -The job has been abandoned because agent did not renew the lock. Ensure agent is running, not sleeping, and has not lost communication with the service. -``` +:::moniker range="azure-devops" -This error may indicate the agent lost communication with the server for a span of several minutes. Check the following to rule out network or other interruptions on the agent machine: +:::image type="content" source="./media/pipeline-error-analysis-icon.png" alt-text="Screenshot of view analysis icon on pipeline run summary page."::: -* Verify automatic updates are turned off. A machine reboot from an update will cause a build or release to fail with the above error. Apply updates in a controlled fashion to avoid this type of interruption. Before rebooting the agent machine, mark the agent as disabled in the pool administration page and let any running build finish. -* Verify the sleep settings are turned off. -* If the agent is running on a virtual machine, avoid any live migration or other VM maintenance operation that may severely impact the health of the machine for multiple minutes. -* If the agent is running on a virtual machine, the same operating-system-update recommendations and sleep-setting recommendations apply to the host machine. And also any other maintenance operations that several impact the host machine. -* Performance monitor logging or other health metric logging can help to correlate this type of error to constrained resource availability on the agent machine (disk, memory, page file, processor, network). -* Another way to correlate the error with network problems is to ping a server indefinitely and dump the output to a file, along with timestamps. Use a healthy interval, for example 20 or 30 seconds. If you are using Azure Pipelines, then you would want to ping an internet domain, for example bing.com. If you are using an on-premises TFS server, then you would want to ping a server on the same network. -* Verify the network throughput of the machine is adequate. You can perform an online speed test to check the throughput. -* If you use a proxy, verify the agent is configured to use your proxy. Refer to the agent deployment topic. +:::moniker-end -#### TFS Job Agent not started +:::moniker range=">= azure-devops-2020 < azure-devops" -This may be characterized by a message in the web console "Waiting for an agent to be requested". Verify the TFSJobAgent (display name: *Visual Studio Team Foundation Background Job Agent*) Windows service is started. +:::image type="content" source="./media/pipeline-error-analysis-icon-server.png" alt-text="Screenshot of view analysis icon for Azure DevOps Server."::: -#### Misconfigured notification URL (1.x agent version) +:::moniker-end -This may be characterized by a message in the web console "Waiting for console output from an agent", and the process eventually times out. +:::moniker range=">= azure-devops-2020" -A mismatching notification URL may cause the worker to process to fail to connect to the server. See *Team Foundation Administration Console*, *Application Tier*. The 1.x agent listens to the message queue using the URL that it was configured with. However, when a job message is pulled from the queue, the worker process uses the notification URL to communicate back to the server. +Choose **View agent** for self-hosted agents (or **About hosted agent image** for Microsoft-hosted agents) to view more information about the agent used to run the pipeline, and **View log** to view the pipeline run logs. -::: moniker-end +:::image type="content" source="./media/error-analysis.png" alt-text="Screenshot of error analysis page in Azure DevOps portal."::: -::: moniker range="azure-devops" +Choose the name of the task below **Run-time details** to view information about the task. -### Check Azure DevOps status for a service degradation +:::image type="content" source="./media/task-details.png" alt-text="Screenshot of task details from error analysis."::: -Check the [Azure DevOps Service Status Portal](https://status.dev.azure.com/) for any issues that may cause a service degradation, such as increased queue time for agents. For more information, see [Azure DevOps Service Status](../../user-guide/service-status-info.md). +In this example, you can see that there's an error in the `Value` of the `Script`. Choose **About this task** to view the documentation for the task. -::: moniker-end +:::moniker-end - +If the issue isn't apparent from the pipeline run summary page or browsing the logs, check the following [Common issues](#common-issues) section, and see [Review logs to diagnose pipeline issues](./review-logs.md) for information on downloading complete logs which include more diagnostic information. -## Pipeline fails to complete + -If your pipeline starts, but fails to complete, check the following common issues. If your issue doesn't seem to match one of these, see [Get logs to diagnose problems](#get-logs-to-diagnose-problems). +## Common issues * [Job time-out](#job-time-out) * [Issues downloading code](#issues-downloading-code) @@ -318,6 +85,7 @@ If your pipeline starts, but fails to complete, check the following common issue * [Line endings for multiple platforms](#line-endings-for-multiple-platforms) * [Variables having ' (single quote) appended](#variables-having--single-quote-appended) * [Service Connection related issues](#service-connection-related-issues) +* [Pipeline stopped hearing from agent](#pipeline-stopped-hearing-from-agent) :::moniker range="azure-devops" @@ -331,20 +99,30 @@ To configure this setting, navigate to [Preview features](../../project/navigati :::image type="content" source="../get-started/media/task-insights-setting.png" alt-text="Screenshot of task insights for failed pipeline runs setting."::: +### Notifications for failed runs + +Azure DevOps includes build-in notifications for failed pipeline runs. To enable notifications: + +1. Go to **Project settings** > **Notifications** for your project. +1. Choose what type of notification you want to receive. To be notified each time a pipeline run fails, select **A build fails**. + +:::image type="content" source="media/notification-settings.png" alt-text="Screenshot of notifications in project settings."::: + :::moniker-end ### Job time-out -A pipeline may run for a long time and then fail due to job time-out. +A pipeline can run for a long time and then fail due to job time-out. Job timeout closely depends on the agent being used. Free Microsoft hosted agents have a max timeout of 60 minutes per job for a private repository and 360 minutes for a public repository. + To increase the max timeout for a job, you can opt for any of the following. -* Buy a Microsoft hosted agent which will give you 360 minutes for all jobs, irrespective of the repository used +* Buy a Microsoft hosted agent which gives you 360 minutes for all jobs, irrespective of the repository used * Use a self-hosted agent to rule out any timeout issues due to the agent Learn more about job [timeout](../process/phases.md#timeouts). > [!NOTE] -> If your Microsoft-hosted agent jobs are timing out, ensure that you haven't specified a pipeline timeout that is less than the max timeout for a job. To check, see [Timeouts](../process/phases.md#timeouts). +> If your Microsoft-hosted agent jobs are timing out, verify that your pipeline timeout is set to a larger value than the max timeout for a job. To check, see [Timeouts](../process/phases.md#timeouts). ### Issues downloading code @@ -353,9 +131,9 @@ Learn more about job [timeout](../process/phases.md#timeouts). #### My pipeline is failing on a checkout step -If you are using a `checkout` step on an Azure Repos Git repository in your organization that is in a different project than your pipeline, ensure that the **Limit job authorization scope to current project** setting is disabled, or follow the steps in [Scoped build identities](../build/options.md) to ensure that your pipeline has access to the repository. +If you're using a `checkout` step on an Azure Repos Git repository in your organization that is in a different project than your pipeline, ensure that the **Limit job authorization scope to current project** setting is disabled, or follow the steps in [Scoped build identities](../build/options.md) to ensure that your pipeline has access to the repository. -When your pipeline can't access the repository due to limited job authorization scope, you will receive the error `Git fetch failed with exit code 128` and your logs will contain an entry similar to `Remote: TF401019: The Git repository with name or identifier does not exist or you do not have permissions for the operation you are attempting.` +When your pipeline can't access the repository due to limited job authorization scope, you'll receive the error `Git fetch failed with exit code 128` and your logs contain an entry similar to `Remote: TF401019: The Git repository with name or identifier does not exist or you do not have permissions for the operation you are attempting.` If your pipeline is failing immediately with `Could not find a project that corresponds with the repository`, ensure that your project and repository name are correct in the `checkout` step or the repository resource declaration. @@ -366,7 +144,7 @@ If your pipeline is failing immediately with `Could not find a project that corr ##### Get sources not downloading some files -This may be characterized by a message in the log "All files up to date" from the `tf get` command. Verify the built-in service identity has permission to download the sources. Either the identity *Project Collection Build Service* or *Project Build Service* will need permission to download the sources, depending on the selected authorization scope on General tab of the build pipeline. In the version control web UI, you can browse the project files at any level of the folder hierarchy and check the security settings. +You might see a message in the log "All files up to date" from the `tf get` command. Verify the built-in service identity has permission to download the sources. Either the identity *Project Collection Build Service* or *Project Build Service* need permission to download the sources, depending on the selected authorization scope on General tab of the build pipeline. In the version control web UI, you can browse the project files at any level of the folder hierarchy and check the security settings. ##### Get sources through Team Foundation Proxy @@ -385,9 +163,9 @@ macOS/Linux: ### My pipeline is failing on a command-line step such as MSBUILD -It is helpful to narrow whether a build or release failure is the result of an Azure Pipelines/TFS product issue (agent or tasks). Build and release failures may also result from external commands. +It's helpful to narrow whether a build or release failure is the result of an Azure Pipelines product issue (agent or tasks). Build and release failures might also result from external commands. -Check the logs for the exact command-line executed by the failing task. Attempting to run the command locally from the command line may reproduce the issue. It can be helpful to run the command locally from your own machine, and/or log-in to the machine and run the command as the service account. +Check the logs for the exact command-line executed by the failing task. Attempting to run the command locally from the command line might reproduce the issue. It can be helpful to run the command locally from your own machine, and/or sign in to the machine and run the command as the service account. For example, is the problem happening during the MSBuild part of your build pipeline (for example, are you using either the [MSBuild](/azure/devops/pipelines/tasks/reference/msbuild-v1) or [Visual Studio Build](/azure/devops/pipelines/tasks/reference/vsbuild-v1) task)? If so, then try running the same [MSBuild command](/visualstudio/msbuild/msbuild-command-line-reference) on a local machine using the same arguments. If you can reproduce the problem on a local machine, then your next steps are to investigate the [MSBuild](/visualstudio/msbuild/msbuild) problem. @@ -396,13 +174,13 @@ For example, is the problem happening during the MSBuild part of your build pipe #### File layout -The location of tools, libraries, headers, and other things needed for a build may be different on the hosted agent than from your local machine. +The location of tools, libraries, headers, and other things needed for a build might be different on the hosted agent than from your local machine. If a build fails because it can't find one of these files, you can use the below scripts to inspect the layout on the agent. -This may help you track down the missing file. +This might help you track down the missing file. -Create a new YAML pipeline in a temporary location (e.g. a new repo created for the purpose of troubleshooting). +Create a new YAML pipeline in a temporary location (for example, a new repo created for the purpose of troubleshooting). As written, the script searches directories on your path. -You may optionally edit the `SEARCH_PATH=` line to search other places. +You can optionally edit the `SEARCH_PATH=` line to search other places. ```yaml # Script for Linux and macOS @@ -449,13 +227,13 @@ steps: #### Differences between local command prompt and agent -Keep in mind, some differences are in effect when executing a command on a local machine and when a build or release is running on an agent. If the agent is configured to run as a service on Linux, macOS, or Windows, then it is not running within an interactive logged-on session. Without an interactive logged-on session, UI interaction and other limitations exist. +Keep in mind, some differences are in effect when executing a command on a local machine and when a build or release is running on an agent. If the agent is configured to run as a service on Linux, macOS, or Windows, then it isn't running within an interactive logged-on session. Without an interactive logged-on session, UI interaction and other limitations exist. ### File or folder in use errors -`File or folder in use` errors are often indicated by error messages such as: +`File or folder in use` errors are indicated by error messages such as: * `Access to the path [...] is denied.` * `The process cannot access the file [...] because it is being used by another process.` @@ -475,13 +253,13 @@ On Windows, tools like [Process Monitor](/sysinternals/downloads/procmon) can be #### Anti-virus exclusion -Anti-virus software scanning your files can cause file or folder in use errors during a build or release. Adding an anti-virus exclusion for your agent directory and configured "work folder" may help to identify anti-virus software as the interfering process. +Anti-virus software scanning your files can cause file or folder in use errors during a build or release. Adding an anti-virus exclusion for your agent directory and configured "work folder" can help to identify anti-virus software as the interfering process. #### MSBuild and /nodeReuse:false -If you invoke MSBuild during your build, make sure to pass the argument `/nodeReuse:false` (short form `/nr:false`). Otherwise MSBuild process(es) will remain running after the build completes. The process(es) remain for some time in anticipation of a potential subsequent build. +If you invoke MSBuild during your build, make sure to pass the argument `/nodeReuse:false` (short form `/nr:false`). Otherwise MSBuild processes continue running after the build completes. The processes remain for some time in anticipation of a potential subsequent build. -This feature of MSBuild can interfere with attempts to delete or move a directory - due to a conflict with the working directory of the MSBuild process(es). +This feature of MSBuild can interfere with attempts to delete or move a directory - due to a conflict with the working directory of the MSBuild processes. The MSBuild and Visual Studio Build tasks already add `/nr:false` to the arguments passed to MSBuild. However, if you invoke MSBuild from your own script, then you would need to specify the argument. @@ -492,11 +270,11 @@ By default the build tasks such as [MSBuild](/azure/devops/pipelines/tasks/refer Try adding the `/m:1` argument to your build tasks to force MSBuild to run only one process at a time. -File-in-use issues may result when leveraging the concurrent-process feature of MSBuild. Not specifying the argument `/maxcpucount:[n]` (short form `/m:[n]`) instructs MSBuild to use a single process only. If you are using the MSBuild or Visual Studio Build tasks, you may need to specify "/m:1" to override the "/m" argument that is added by default. +File-in-use issues might result when leveraging the concurrent-process feature of MSBuild. Not specifying the argument `/maxcpucount:[n]` (short form `/m:[n]`) instructs MSBuild to use a single process only. If you're using the MSBuild or Visual Studio Build tasks, you might need to specify "/m:1" to override the "/m" argument that is added by default. ### Intermittent or inconsistent MSBuild failures -If you are experiencing intermittent or inconsistent MSBuild failures, try instructing MSBuild to use a single-process only. Intermittent or inconsistent errors may indicate that your target configuration is incompatible with the concurrent-process feature of MSBuild. See [MSBuild and /maxcpucount:[n]](#msbuild-and-maxcpucountn). +If you're experiencing intermittent or inconsistent MSBuild failures, try instructing MSBuild to use a single-process only. Intermittent or inconsistent errors might indicate that your target configuration is incompatible with the concurrent-process feature of MSBuild. See [MSBuild and /maxcpucount:[n]](#msbuild-and-maxcpucountn). ### Process stops responding @@ -508,11 +286,11 @@ Process stops responding causes and troubleshooting steps: #### Waiting for Input -A process that stops responding may indicate that a process is waiting for input. +A process that stops responding might indicate that a process is waiting for input. -Running the agent from the command line of an interactive logged on session may help to identify whether a process is prompting with a dialog for input. +Running the agent from the command line of an interactive logged on session might help to identify whether a process is prompting with a dialog for input. -Running the agent as a service may help to eliminate programs from prompting for input. For example in .NET, programs may rely on the System.Environment.UserInteractive Boolean to determine whether to prompt. When the agent is running as a Windows service, the value is false. +Running the agent as a service might help to eliminate programs from prompting for input. For example in .NET, programs might rely on the System.Environment.UserInteractive Boolean to determine whether to prompt. When the agent is running as a Windows service, the value is false. #### Process dump @@ -520,7 +298,7 @@ Analyzing a dump of the process can help to identify what a deadlocked process i #### WiX project -Building a WiX project when custom MSBuild loggers are enabled, can cause WiX to deadlock waiting on the output stream. Adding the additional MSBuild argument `/p:RunWixToolsOutOfProc=true` will work around the issue. +Building a WiX project when custom MSBuild loggers are enabled, can cause WiX to deadlock waiting on the output stream. Adding the additional MSBuild argument `/p:RunWixToolsOutOfProc=true` works around the issue. ### Line endings for multiple platforms @@ -539,7 +317,7 @@ In that file, add the following line: ### Variables having ' (single quote) appended -If your pipeline includes a Bash script that sets variables using the `##vso` command, you may see an additional `'` appended to the value of the variable you set. +If your pipeline includes a Bash script that sets variables using the `##vso` command, you might see another `'` appended to the value of the variable you set. This occurs because of an interaction with `set -x`. The solution is to disable `set -x` temporarily before setting a variable. The Bash syntax for doing that is `set +x`. @@ -553,8 +331,8 @@ set -x #### Why does this happen? Many Bash scripts include the `set -x` command to assist with debugging. -Bash will trace exactly what command was executed and echo it to stdout. -This will cause the agent to see the `##vso` command twice, and the second time, Bash will have added the `'` character to the end. +Bash traces exactly what command was executed and echo it to stdout. +This causes the agent to see the `##vso` command twice, and the second time, Bash will have added the `'` character to the end. For instance, consider this pipeline: @@ -565,15 +343,15 @@ steps: echo ##vso[task.setvariable variable=MY_VAR]my_value ``` -On stdout, the agent will see two lines: +On stdout, the agent sees two lines: ```bash ##vso[task.setvariable variable=MY_VAR]my_value + echo '##vso[task.setvariable variable=MY_VAR]my_value' ``` When the agent sees the first line, `MY_VAR` will be set to the correct value, "my_value". -However, when it sees the second line, the agent will process everything to the end of the line. -`MY_VAR` will be set to "my_value'". +However, when it sees the second line, the agent processes everything to the end of the line. +`MY_VAR` is set to "my_value'". ### Libraries aren't installed for Python application when script executes @@ -588,26 +366,25 @@ D:\home\python364x64\python.exe -m pip install -r requirements.txt ### Service Connection related issues -To troubleshoot issues related to service connections, see [Service connection troubleshooting](../release/azure-rm-endpoint.md). - -### Enable Storage Explorer to deploy static content like .css and .js to a static website from Azure DevOps via Azure Pipelines +To troubleshoot issues related to service connections, see [Service connection troubleshooting](../release/azure-rm-endpoint.md). To specifically troubleshoot service connections using workload identity for authentication, see [Troubleshoot workload identity service connections](../release/troubleshoot-workload-identity.md). -In this scenario, you can use the [Azure File Copy task](/azure/devops/pipelines/tasks/reference/azure-file-copy-v4) to upload content to the website. You can use any of the tools described in [Uploading content](/azure/storage/blobs/storage-blob-static-website#uploading-content) to upload content to the web container. +### Pipeline stopped hearing from agent -## Get logs to diagnose problems +If your pipeline fails with a message like `We stopped hearing from agent . Verify the agent machine is running and has a healthy network connection.`, check the resource utilization of the agent to see if the agent machine is running out of resources. Starting with [Sprint 228](/azure/devops/release-notes/2023/sprint-228-update), [Azure Pipelines logs contain resource utilization metrics](/azure/devops/release-notes/2023/sprint-228-update#pipeline-logs-now-contain-resource-utilization) for each step. -If none of the previous suggestions match your problem, you can use the information in the logs to diagnose your failing pipeline. +When using Azure DevOps Services, you can see resource utilization in the logs, including disk usage, memory usage, and CPU utilization, by enabling [verbose logs](review-logs.md#configure-verbose-logs). When the pipeline completes, [search the logs](review-logs.md#view-and-download-logs) for `Agent environment resources` entries for each step. -Start by looking at the logs in your completed build or release. You can view logs by navigating to the pipeline run summary and selecting the job and task. If a certain task is failing, check the logs for that task. +``` +2024-02-28T17:41:15.1315148Z ##[debug]Agent environment resources - Disk: D:\ Available 12342.00 MB out of 14333.00 MB, Memory: Used 1907.00 MB out of 7167.00 MB, CPU: Usage 17.23% +``` -In addition to viewing logs in the pipeline build summary, you can download complete logs which include additional diagnostic information, and you can configure more verbose logs to assist with your troubleshooting. +For information on capturing additional resource utilization logs, see [Capture resource utilization details](review-logs.md#capture-resource-utilization-details). -For detailed instructions for configuring and using logs, see [Review logs to diagnose pipeline issues](review-logs.md). -## I need more help. I found a bug. I've got a suggestion. Where do I go? +#### Enable Storage Explorer to deploy static content like .css and .js to a static website from Azure DevOps via Azure Pipelines -[Get subscription, billing, and technical support](https://azure.microsoft.com/support/devops/) +In this scenario, you can use the [Azure File Copy task](/azure/devops/pipelines/tasks/reference/azure-file-copy-v4) to upload content to the website. You can use any of the tools described in [Uploading content](/azure/storage/blobs/storage-blob-static-website#uploading-content) to upload content to the web container. -Report any problems or submit feedback at [Developer Community](https://developercommunity.visualstudio.com/). +## Next steps -We welcome your suggestions: +* [Review logs](./review-logs.md) to uncover additional diagnostic tools. \ No newline at end of file diff --git a/docs/project/configure-or-add-a-project-portal.md b/docs/project/configure-or-add-a-project-portal.md deleted file mode 100644 index 5720d5fde6a..00000000000 --- a/docs/project/configure-or-add-a-project-portal.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Configure or add a project portal -titleSuffix: TFS -description: How to configure a project portal for Azure DevOps -ms.subservice: azure-devops-projects -ms.assetid: 63eae10a-b4d6-4ef5-93fd-270d20a8a2cf -ms.author: chcomley -author: chcomley -ms.topic: tutorial -monikerRange: '<= azure-devops' -ms.date: 04/04/2022 ---- - -# Configure or add a project portal - -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - -The project portal is a site associated with a team project for the purposes of sharing information. - -> [!IMPORTANT] -> Configuring the project portal and process guidance features have been deprecated. You can only set them from Visual Studio 2017 or earlier versions and when connected to TFS 2017 or earlier versions. SharePoint integration with Azure DevOps (formerly named Team Foundation Server) was deprecated with the release of TFS 2018. For TFS 2018 and later versions, you can use the built-in wiki feature to share information, guidance, and documents. To learn more, see [About Wikis, READMEs, and Markdown](./wiki/about-readme-wiki.md). - -## Related articles - -- [About processes and process templates](../boards/work-items/guidance/choose-process.md) -- [About SharePoint integration](/previous-versions/azure/devops/report/sharepoint-dashboards/about-sharepoint-integration) -- [Discontinue SharePoint integration: TFS 2017 and earlier versions](/previous-versions/azure/devops/report/sharepoint-dashboards/deprecation/discontinue-pre-tfs-2017-sharepoint-integration) diff --git a/docs/project/feedback/index.md b/docs/project/feedback/index.md index 1586d6e5f7f..1cda6909565 100644 --- a/docs/project/feedback/index.md +++ b/docs/project/feedback/index.md @@ -8,62 +8,53 @@ ms.assetid: ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 03/03/2025 --- # About requesting and providing feedback [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can request feedback using one of two tools, through the Test & Feedback extension or through the Request feedback link you access from a dashboard. +In Azure DevOps, gathering feedback is essential for improving your software applications. You can request feedback using one of two tools: the Test & Feedback extension or the Request feedback link accessible from a dashboard. With these tools, you can capture valuable insights from stakeholders and team members, helping you identify issues and areas for improvement. > [!NOTE] -> This article is about using Azure DevOps feedback tools. To provide feedback about Azure DevOps, see [Provide product and content feedback](../../user-guide/provide-feedback.md?bc=%252fazure%252fdevops%252fproject%252ffeedback%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fproject%252ffeedback%252ftoc.json). +> This article is about using Azure DevOps feedback tools. For more information about providing feedback about Azure DevOps, see [Provide product and content feedback](../../user-guide/provide-feedback.md?bc=%252fazure%252fdevops%252fproject%252ffeedback%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fproject%252ffeedback%252ftoc.json). -## About the Test & Feedback extension +## Learn about the Test & Feedback extension -Using the Test & Feedback extension is a simple, three step process: +Using the Test & Feedback extension is a simple, three-step process: ![Schematic showing process steps Capture, Create, Collaborate](../../test/media/perform-exploratory-tests/getstarted-05.png) - -* **Capture your findings** quickly and easily using the tools in the extension. - Capture notes, screenshots with annotations, and screen recordings - to describe your findings and highlight issues. Additionally, in - the background the extension automatically captures rich data such - as user actions as an image action log, page load data, - and system information about the browser, operating system, memory, - and more that can serve as a starting point for debugging. - -* **Create work items** such as bugs, tasks, and test cases directly from - the extension. The captured findings automatically become a part of the work item. - Users can file a bug to report an issue with the product, or create a task that - indicates a new work requirement. The extension can also be used to - create test cases for scenarios discovered during exploration. - -* **Collaborate with your team** by sharing your findings. - Export your session report in Standalone mode, or connect to Azure DevOps or - Team Foundation Server (2015 or later) for a fully integrated experience - including exploring user stories and backlog items, simplified tracking and triaging of - bugs and tasks, and managing feedback requests in one place. - -As users perform exploratory testing, you can -[get insights from the sessions](../../test/insights-exploratory-testing.md). View completed exploratory sessions and derive meaningful -insights across all sessions. Get end-to-end traceability such as a breakdown -of the work items created, the work items explored and not explored, session owners, -and more. + +## 1. Capture your findings + +- Capture notes, screenshots with annotations, and screen recordings to quickly and easily describe your findings and highlight issues. +- Capture rich data automatically in the background, such as user actions as an image action log, page load data, and system information about the browser, operating system, memory, and more. This data can serve as a starting point for debugging. + +## 2. Create work items + +- Create work items such as bugs, tasks, and test cases directly from the extension. +- Include captured findings automatically in the work item. +- File a bug to report an issue with the product, create a task that indicates a new work requirement, or create test cases for scenarios discovered during exploration. + +## 3. Collaborate with your team + +- Share your findings by exporting your session report in Standalone mode. +- Connect to Azure DevOps for a fully integrated experience, including exploring user stories and backlog items, simplified tracking, and triaging of bugs and tasks, and managing feedback requests in one place. + +As users perform exploratory testing, you can [gain insights from the sessions](../../test/insights-exploratory-testing.md). View completed exploratory sessions and derive meaningful insights across all sessions. Achieve end-to-end traceability with a breakdown of the work items created, the work items explored and not explored, session owners, and more. -To learn more, see the following articles: +For more information, see the following articles: - [Install the Test & Feedback extension](../../test/request-stakeholder-feedback.md?toc=/azure/devops/project/toc.json) - [Request stakeholder feedback](../../test/request-stakeholder-feedback.md?toc=/azure/devops/project/toc.json) - [Provide stakeholder feedback](../../test/provide-stakeholder-feedback.md?toc=/azure/devops/project/toc.json) +## Use the Microsoft Feedback client -## Microsoft Feedback client - -The Visual Studio 2015 Microsoft Feedback client is a downloadable tool that you install on your desktop. It supports similar features for capturing findings to those provided by the Test & Feedback extension. It doesn't support creating work items. You can download the tool from [Feedback Client for Microsoft Visual Studio Team Foundation Server 2015](https://www.microsoft.com/download/details.aspx?id=48142). +Download and install the Visual Studio 2015 Microsoft Feedback client on your desktop. This tool supports similar features for capturing findings as the Test & Feedback extension but doesn't support creating work items. You can download the tool from [Feedback Client for Microsoft Visual Studio Team Foundation Server 2015](https://www.microsoft.com/download/details.aspx?id=48142). -To learn more, see the following articles: +For more information, see the following articles: - [Get feedback (Work tracking)](/previous-versions/azure/devops/project/feedback/get-feedback) - [Provide feedback with the Feedback client](/previous-versions/azure/devops/project/feedback/give-feedback) @@ -71,6 +62,6 @@ To learn more, see the following articles: ## Related articles -- [Give reviewers permissions to provide feedback](/previous-versions/azure/devops/project/feedback/give-permissions-feedback) -- [Default permissions and access set for collaboration tools](../wiki/wiki-readme-permissions.md) -- [Give us feedback, get support](../../user-guide/provide-feedback.md) +- [Grant reviewers permissions to provide feedback](/previous-versions/azure/devops/project/feedback/give-permissions-feedback) +- [Set default permissions and access for collaboration tools](../wiki/wiki-readme-permissions.md) +- [Provide feedback and get support](../../user-guide/provide-feedback.md) diff --git a/docs/project/feedback/toc.yml b/docs/project/feedback/toc.yml index 0052cfbdf2f..cde968630f0 100644 --- a/docs/project/feedback/toc.yml +++ b/docs/project/feedback/toc.yml @@ -35,12 +35,12 @@ - name: Microsoft Feedback client (Archived) items: - name: Request feedback - href: /previous-versions/azure/devops/project/feedback/get-feedback + href: /previous-versions/azure/devops/project/feedback/get-feedback - name: Provide feedback href: /previous-versions/azure/devops/project/feedback/give-feedback - - name: Set feedback permissions - href: /previous-versions/azure/devops/project/feedback/give-permissions-feedback + - name: Set feedback permissions displayName: security + href: /previous-versions/azure/devops/project/feedback/give-permissions-feedback - name: Enable remote audio capture href: /previous-versions/azure/devops/project/feedback/enable-remote-audio-capture - name: Change the audio device or annotation tool diff --git a/docs/project/index.yml b/docs/project/index.yml index 501c672858f..2a136de5d8e 100644 --- a/docs/project/index.yml +++ b/docs/project/index.yml @@ -11,7 +11,7 @@ metadata: ms.topic: landing-page author: chcomley ms.author: chcomley - ms.date: 02/18/2022 + ms.date: 03/11/2025 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -25,7 +25,7 @@ landingContent: links: - text: Navigate the web portal url: ./navigation/index.md - - text: Get started with Search + - text: Search Azure DevOps url: ./search/get-started-search.md - linkListType: how-to-guide links: @@ -37,7 +37,7 @@ landingContent: url: ../organizations/settings/set-your-preferences.md?toc=/azure/devops/project/toc.json - text: Connect to a project url: ../organizations/projects/connect-to-projects.md?toc=/azure/devops/project/toc.json - - title: Add and manage wikis + - title: Manage wikis linkLists: - linkListType: overview links: @@ -53,17 +53,19 @@ landingContent: url: ./wiki/add-edit-wiki.md - text: Publish a Git repository to a wiki url: ./wiki/publish-repo-to-wiki.md + - text: Restore a deleted wiki + url: ./wiki/restore-deleted-wiki.md - linkListType: reference links: - text: Syntax guidance for basic Markdown usage url: ./wiki/markdown-guidance.md - text: Syntax guidance for Markdown usage in Wiki - url: ./wiki/wiki-markdown-guidance.md + url: ./wiki/markdown-guidance.md - title: Search linkLists: - linkListType: overview links: - - text: Search across all your code, wiki, packages and work items + - text: Search across all your code, wiki, packages, and work items url: ./search/get-started-search.md - linkListType: how-to-guide links: diff --git a/docs/project/media/mobile-azure-devops-hubs.png b/docs/project/media/mobile-azure-devops-hubs.png new file mode 100644 index 00000000000..1b174d1ce37 Binary files /dev/null and b/docs/project/media/mobile-azure-devops-hubs.png differ diff --git a/docs/project/navigation/add-artifact-team.md b/docs/project/navigation/add-artifact-team.md index 68a5c9372ae..79f383356bd 100644 --- a/docs/project/navigation/add-artifact-team.md +++ b/docs/project/navigation/add-artifact-team.md @@ -15,34 +15,25 @@ ms.date: 04/04/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Select the service of interest to get started adding new artifacts or objects. For example, to add work items, choose **Boards** or **Work**. Some artifacts—such as a product backlog, Kanban board, portfolio backlogs—are added when you add a team. +Select the service of interest to get started adding new artifacts or objects. For example, to add work items, choose **Boards** or **Work**. Some artifacts—such as a product backlog, board, portfolio backlogs—are added when you add a team. Prior to adding an artifact, make sure that you've [selected the project and repository](go-to-project-repo.md) that you want to work in. +## Prerequisites + +[!INCLUDE [prerequisites](../../boards/includes/prerequisites.md)] + +There might be other prerequisites for managing specific items. For more information, see [Security groups, service accounts, and permissions reference](../../organizations/security/permissions.md). + ## Add work items, queries, or other work tracking artifacts You can quickly add a query or work item when working from a **Boards** or **Work** page. -::: moniker range=">= azure-devops-2019" - Choose a **Boards** page—such as **Work Items**, **Boards**, or **Backlogs**. Then choose the :::image type="icon" source="../../media/icons/blue-add.png" border="false"::: plus icon and select from the menu of options. > [!div class="mx-imgBorder"] > ![Work, add artifact](media/add-artifact/add-work-item-query-vert.png) -::: moniker-end - -::: moniker range="tfs-2018" - -From a **Work** page, you can add a work item from the menu of options as shown in the following image. - -> [!div class="mx-imgBorder"] -> ![Work, add a work item](../../boards/backlogs/media/add-work-items-choose-user-story.png) - - Or, you can open one of the pages—**Boards**, **Backlogs**, **Queries**, or **Plans**—to add an artifact specific to each of these functional pages. - -::: moniker-end - To add other work tracking artifacts, see one of the following articles: - To add a board, backlog, or sprint backlog, first [add a team](../../organizations/settings/add-teams.md) which will be associated with those artifacts @@ -50,13 +41,10 @@ To add other work tracking artifacts, see one of the following articles: - [Add a managed work item query](../../boards/queries/using-queries.md) - [Add work items](../../boards/work-items/view-add-work-items.md). - ## Add a pull request or Git repository You can quickly add a pull request, Git repository, or work item using the **Add** menu when working from **Code**. -::: moniker range=">= azure-devops-2019" - Expand the **Repos** service and choose **Files**, **Commits**, or **Pull Requests** (Git repos) or **Files**, **Changesets**, or **Shelvesets** (TFVC). Then, choose the :::image type="icon" source="../../media/icons/blue-add.png" border="false"::: plus icon and select from the menu of options. > [!div class="mx-imgBorder"] @@ -64,20 +52,6 @@ Expand the **Repos** service and choose **Files**, **Commits**, or **Pull Reques For details on adding a Git repository, see [Git repository](../../repos/git/creatingrepo.md). -::: moniker-end - -::: moniker range="tfs-2018" - -From **Code**, open the context menu for the current repository and choose ![plus icon](../../media/icons/blue-add-icon.png) **New repository**. For details on adding a Git repository, see [Git repository](../../repos/git/creatingrepo.md) - -> [!div class="mx-imgBorder"] -> ![Code, add artifact](media/add-artifact/add-repo-horz.png) - -From one of the other **Code** pages, you can add files or folders, a new branch, or a new pull request. - -::: moniker-end - - Note that you can only add one TFVC repository per project, but an unlimited number of Git repositories. To learn more about Git artifacts, see one of the following articles: - [Git repository](../../repos/git/creatingrepo.md) @@ -85,92 +59,47 @@ Note that you can only add one TFVC repository per project, but an unlimited num - [Git pull request](../../repos/git/pull-requests.md) - [Add work items](../../boards/work-items/view-add-work-items.md) - - ## Add build and release pipelines -::: moniker range=">= azure-devops-2019" - Expand **Pipelines** and choose **Builds** or **Releases**. Then choose the :::image type="icon" source="../../media/icons/blue-add.png" border="false"::: plus icon and select from the menu of options. > [!div class="mx-imgBorder"] > ![Add build and release pipelines.](media/add-artifact/add-pipeline-vert.png) -::: moniker-end - -::: moniker range="tfs-2018" - -From **Build and Release**, choose **Builds**, **Releases**, or other page to add an artifact associated with that page. - -> [!div class="mx-imgBorder"] -> ![Build and Release, add an artifact](media/add-artifact/build-release-hub.png) - -::: moniker-end - -To learn more about adding other pipeline related artifacts, see the following articles: +For more information about adding other pipeline related artifacts, see the following articles: - [Deployment groups](../../pipelines/release/deployment-groups/index.md) - [Task groups](../../pipelines/library/task-groups.md) - [Variable groups](../../pipelines/library/variable-groups.md) - [Secure files](../../pipelines/library/secure-files.md) - ## Add a team Agile tools and dashboards are typically associated with teams. You add teams to a project. To learn more about teams, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). To add a team, see [Add a team and team members](../../organizations/settings/add-teams.md). - + ## View teams already defined -::: moniker range=">= azure-devops-2019" - To view the set of defined teams, open **Project settings**, and choose **Overview**. > [!div class="mx-imgBorder"] > ![Web portal, Project Settings, Teams](media/add-artifact/view-teams-vert-brn.png) -::: moniker-end - -::: moniker range="tfs-2018" - -To view the set of defined teams, open the admin context for the project, and choose **Overview**. - -![Web portal, admin context, project, Overview page](../../boards/plans/media/multiple-teams-view-teams.png) - -::: moniker-end - ## Add a dashboard ::: moniker range=">= azure-devops-2020" Dashboards are associated with a team or a project. Each team can create and configure a number of dashboards. And, any team member can create one or more project dashboards. To learn how, see [Add a dashboard](../../report/dashboards/dashboards.md). ::: moniker-end -::: moniker range="<= azure-devops-2019" -Dashboards are associated with a team. Each team can create and configure a number of dashboards. To learn how, see [Add a dashboard](../../report/dashboards/dashboards.md). -::: moniker-end - - ## Add a wiki If you don't have a wiki yet, you can add one. Once added, you can add and update pages to that wiki. - -::: moniker range=">= azure-devops-2019" - - [Create a wiki](../wiki/wiki-create-repo.md) - [Add and edit wiki pages](../wiki/add-edit-wiki.md) - [Publish a Git repository to a wiki](../wiki/publish-repo-to-wiki.md) -::: moniker-end - -::: moniker range="tfs-2018" - -- [Create a wiki](../wiki/wiki-create-repo.md) -- [Add and edit wiki pages](../wiki/add-edit-wiki.md) - -::: moniker-end - ## Related articles - [Azure Artifacts](../../artifacts/index.yml) -- [Exploratory & Manual Testing](../../test/index.yml) \ No newline at end of file +- [Exploratory & Manual Testing](../../test/index.yml) diff --git a/docs/project/navigation/filter-basics.md b/docs/project/navigation/filter-basics.md index 18102e05f16..9e4abdec4f7 100644 --- a/docs/project/navigation/filter-basics.md +++ b/docs/project/navigation/filter-basics.md @@ -8,71 +8,60 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 03/11/2025 --- - # Filter lists, boards, and directories [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Several applications and pages support filtering, which is very useful when a large number of artifacts or items have been defined. Most directory views provide one or more filter functions. +Several applications and pages in Azure DevOps support filtering, which is useful when dealing with a large number of artifacts or items. Most directory views offer one or more filter functions to help you quickly find what you're looking for. -You can filter most items using keywords or a user name for an author of an item or where work is assigned to them. You can filter lists and boards in the following areas: - - -::: moniker range=">= azure-devops-2019" -- Git repositories: Branches, Commits, Commit history, Pull Requests, Pushes, and Repositories -- Work tracking: Work Items, Kanban boards, Backlogs, Sprint Backlogs, and Taskboards -- Directories: Dashboards, Boards, Backlogs, Sprints, Queries, Builds, Releases - -::: moniker-end - -::: moniker range="tfs-2018" -- Git repositories: Branches, Commits, Commit history, Pull Requests, Pushes, and Repositories -- Work tracking: Work Items, Kanban boards, Backlogs, Sprint Backlogs, and Taskboards - -::: moniker-end +You can filter most items using keywords or a user name, either for the author of an item or where work is assigned to them. Filtering can be applied to lists and boards in the following areas: +- **Git repositories:** Branches, Commits, Commit history, Pull Requests, Pushes, and Repositories +- **Work tracking:** Work Items, Boards, Backlogs, Sprint Backlogs, and Taskboards +- **Directories:** Dashboards, Boards, Backlogs, Sprints, Queries, Builds, Releases > [!NOTE] -> You may have fewer or additional filter options based on the [features you've enabled](preview-features.md) or the platform and version that you are working from. +> You might have fewer or other filter options based on the [enabled features](preview-features.md) or the platform and version that you're working from. +## Prerequisites - +| Category | Requirements | +|--------------|-------------| +|**Permissions**|Member of the **Contributors** group or similar permissions. | +|**Access**| - Member of the project where you want to apply filters. If you don't have access, request it from your project administrator.
      - At least **Basic** access to use filtering features. Users with Stakeholder access might experience limited filtering capabilities.| + ## Filter based on keywords, tags, or fields -To turn filtering on, choose the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: filter icon. +To turn on filtering, choose the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: filter icon. -You can filter work items by typing a keyword or using one or more of the fields provided, such as work item type, assigned to, state, and tags. Based on the keyword that you enter, the filter function will list work items based on any visible/displayed column or field, including tags. Also, you can enter a value for an ID, whether or not the ID field is visible. +You can filter work items by entering a keyword or using fields like work item type, assigned to, state, and tags. The filter lists work items based on any visible column or field, including tags. You can also enter an ID value, regardless of the visibility of the ID field. -![Backlogs, turn filtering on](../../boards/backlogs/media/filter-backlogs-options.png) +![Screenshot showing Backlogs and highlighted filter icon.](../../boards/backlogs/media/filter-backlogs-options.png) -The filtered set is always a flat list, even if you've selected to show parents. +The filtered set is always a flat list, even if you selected to show parents. ### Characters ignored by keyword filter criteria -The filter criteria ignores the following characters: `,` (comma), `.` (period), `/` (forward slash), and `\` (back slash). - -::: moniker range=">= azure-devops-2019" +The filter criteria ignore the following characters: `,` (comma), `.` (period), `/` (forward slash), and `\` (back slash). ## Filter directories Choose the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: filter icon to filter a directory list by keyword, team, or other supported field. Keywords apply to titles, descriptions, and team names. -For example, here we turn filtering on for the dashboard directory. +For example, here we turn on filtering for the dashboard directory. > [!div class="mx-imgBorder"] -> ![Filter the dashboard directory](../../report/dashboards/media/dashboards/filter-directory.png) - -::: moniker-end +> ![Screenshot shows highlighted Filter icon in the dashboard directory.](../../report/dashboards/media/dashboards/filter-directory.png) ## Related articles - [Commit history](../../repos/git/commit-history.md) - [Working with Git tags](../../repos/git/git-tags.md) - [Filter backlogs and queries](../../boards/backlogs/filter-backlogs-boards-plans.md) -- [Filter your Kanban board](../../boards/backlogs/filter-backlogs-boards-plans.md) +- [Filter your board](../../boards/backlogs/filter-backlogs-boards-plans.md) - [Add tags to work items](../../boards/queries/add-tags-to-work-items.md) \ No newline at end of file diff --git a/docs/project/navigation/glossary.md b/docs/project/navigation/glossary.md index 0220cb092b6..377ce1ea06f 100644 --- a/docs/project/navigation/glossary.md +++ b/docs/project/navigation/glossary.md @@ -1,43 +1,59 @@ --- title: Key concepts, objects, and terms titleSuffix: Azure DevOps -description: Understand the key concepts that support navigation and managing projects available with Azure DevOps +description: Understand the key concepts that support navigation and managing projects available with Azure DevOps. ms.custom: Navigation ms.subservice: azure-devops-projects ms.author: chcomley author: chcomley ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 02/08/2019 +ms.date: 04/22/2024 --- - # Project management and navigation glossary [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -This glossary describes terms used when navigating in the web portal for Azure DevOps. See also: -- [Agile glossary](../../boards/work-items/agile-glossary.md) -- [Security glossary](../../organizations/security/security-glossary.md) - +This glossary describes terms used when navigating in the web portal for Azure DevOps. See also the [Agile glossary](../../boards/work-items/agile-glossary.md). ## Backlogs -An interactive list of work items that corresponds to a team's project plan or roadmap for what the team plans to deliver. The product backlog supports prioritizing work, forecasting work by sprints, and quickly linking work to portfolio backlog items. You can define your backlog items and then manage their status using the Kanban board. +An interactive list of work items that corresponds to a team's project plan or roadmap for what the team plans to deliver. The product backlog supports prioritizing work, forecasting work by sprints, and quickly linking work to portfolio backlog items. You can define your backlog items and then manage their status using the board. -Each product backlog can be customized by a team. Learn more: [Create your backlog](../../boards/backlogs/create-your-backlog.md). +Teams can customize each backlog. For more information, see [Create your backlog](../../boards/backlogs/create-your-backlog.md). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Analytics views Analytics views provide a simplified way to specify the filter criteria for a Power BI report based on the Analytics service. The Analytics service is the reporting platform for Azure DevOps Services. ::: moniker-end [!INCLUDE [temp](../../includes/glossary-terms/area-paths.md)] -## Boards (Kanban) -An interactive, electronic sign board that supports visualization of the flow of work from concept to completion and lean methods. Learn more: [Kanban overview](../../boards/boards/kanban-overview.md). +::: moniker range="azure-devops" + +## Audit log + +Audit logs contain many changes that occur throughout an Azure DevOps organization. Changes occur when a user or service identity within the organization edits the state of an artifact, including changes to permissions. For more information, see [Access, export, and filter audit logs](../../organizations/audit/azure-devops-auditing.md). + +::: moniker-end + +## Authentication + +Authentication verifies a user's identify based on the credentials provided when they sign into an organization in Azure DevOps. These services/servers typically integrate with and rely upon the security features provided by services such as Active Directory or Microsoft Entra ID. For more information, see [About security, authentication, and authorization](../../organizations/security/about-security-identity.md). + +## Authorization + +Authorization is the operation that's performed to verify that the identity that's attempting to connect to a service or server instance has the necessary permissions to access a service, feature, function, object, or method. For more information, see [About security, authentication, and authorization](../../organizations/security/about-security-identity.md). + +## Boards +An interactive, electronic sign board that supports visualization of the flow of work from concept to completion and lean methods. Learn more: [Board overview](../../boards/boards/kanban-overview.md). [!INCLUDE [temp](../../includes/glossary-terms/collections.md)] +## Conditional access + +Conditional access provides support for securing Azure DevOps resources backed by a Microsoft Entra tenant. For example, you can enable multifactor authentication to help protect against the risk of compromised credentials. For more information, see [Manage conditional access to Azure DevOps](../../organizations/accounts/change-application-access-policies.md). + [!INCLUDE [temp](../../includes/glossary-terms/dashboards.md)] [!INCLUDE [temp](../../includes/glossary-terms/extensions.md)] @@ -53,12 +69,49 @@ A Git repository supports a distributed version control system for tracking chan > [!NOTE] > Git in Visual Studio and Azure DevOps Services is standard Git. You can use Visual Studio with third-party Git services, and you can also use third-party Git clients with Azure DevOps Services. +## Inheritance + +Permissions that aren't directly allowed or denied for a user, might be inherited. For more information, see [Get started with permissions, access, and security groups](../../organizations/security/about-permissions.md). + +## Microsoft Authentication Library + +The Microsoft Authentication Library (MSAL) enables application developers to acquire tokens from the Microsoft identity platform to authenticate users and access secured web APIs. It can be used to provide secure access to Microsoft Graph, other Microsoft APIs, third-party web APIs, or your own web API. MSAL supports many different application architectures and platforms including .NET, JavaScript, Java, Python, Android, and iOS. For more information, see the [Overview of Microsoft Authentication Library](/azure/active-directory/develop/msal-overview#languages-and-frameworks). + +## Namespace + +Each family of Azure DevOps resources (work items, Git repositories, etc.) is secured using a different namespace. Each security namespace contains zero or more ACLs. Each ACL contains a token, an inherit flag, and a set of zero or more ACEs. Each ACE contains an identity descriptor, an allowed permissions bitmask, and a denied permissions bitmask. + +For a list of Azure DevOps namespaces, see [Security namespace and permission reference](../../organizations/security/namespace-reference.md). + [!INCLUDE [temp](../../includes/glossary-terms/notifications.md)] +## OAuth + +OAuth 2.0 is an industry-standard protocol for authorization. OAuth 2.0 is supported for Azure DevOps Services to authenticate REST APIs. For more information, see [Authorize access to REST APIs with OAuth 2.0](../../integrate/get-started/authentication/oauth.md). + +::: moniker range="azure-devops" + +## Organization owner + +The person who created the organization or was later assigned as the organization owner. The organization owner has access to all Azure DevOps features and functions, and can grant access to others to features and functions. To look up or change organization owner, see [Change the organization owner](../../organizations/accounts/change-organization-ownership.md). + +::: moniker-end + +## Personal Access Token (PAT) + +Personal access tokens (PATs) are alternate passwords that you can use to authenticate into Azure DevOps. To learn how to create and revoke PATs, see [Authenticate access with personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). + +## Permission + +The assignment made to a user or group to use a feature or function. Permissions are assigned to default security groups. For more information, see [Get started with permissions, access, and security groups](../../organizations/security/about-permissions.md). + +## Permission state + +The state assigned to a feature or function to a user's or group's permission. Users have permission to access a feature if their permission is set to **Allow**, **Inherited Allow**, or **System Allow**. They don't have permission when the state is set to **Deny**, **Inherited deny**, **System deny**, or **Not set**. For more information, see [Get started with permissions, access, and security groups](../../organizations/security/about-permissions.md). ## Pipelines -Pipelines are artifacts that you define to run concurrent builds or deploy concurrent releases. Two types of pipelines are supported, private and hosted. To learn more, see [CI/CD concurrent jobs](../../pipelines/licensing/concurrent-jobs.md). +Pipelines are artifacts that you define to run concurrent builds or deploy concurrent releases. Two types of pipelines are supported, private, and hosted. For more information, see [CI/CD concurrent jobs](../../pipelines/licensing/concurrent-jobs.md). ![Pipeline concept end-to-end](/azure/devops/pipelines/media/pipeline-concept-end-to-end.png) @@ -70,25 +123,60 @@ Pipelines are artifacts that you define to run concurrent builds or deploy concu [!INCLUDE [temp](../../includes/glossary-terms/public-projects.md)] - [!INCLUDE [temp](../../includes/glossary-terms/queries.md)] ## Repositories A source control folder or container you configure to help you track file changes in. You can have any number of repositories on your computer, each stored in their own folder. Each repository is independent, so changes saved in one repository don't affect the contents of another. Learn more: [Create a new Git repo](../../repos/git/creatingrepo.md). +## Role-based permissions + +A security model that limits actions based on membership within a role and permissions assigned to that role. For more information, see [Role-based permissions](../../organizations/security/about-permissions.md#role-based-permissions). + +## Security group + +A method by which you can organize users and other domain objects to simplify administration of permissions and access. Azure DevOps supports many default security groups and the ability to create custom groups. For more information, see [Get started with permissions, access, and security groups](../../organizations/security/about-permissions.md). + +## Service account + +An account used to monitor or manage select services, such as build or test services. + +## Service principal + +A service principal is the local representation, or application instance, of a global application object in a single tenant or directory. When an application is given permission to access resources in a tenant (upon registration or consent), a service principal object is created. For more information, see [Application and service principal objects in Microsoft Entra ID](/azure/active-directory/develop/app-objects-and-service-principals) and [service principal and managed identity support in Azure DevOps](../../integrate/get-started/authentication/service-principal-managed-identity.md). + [!INCLUDE [temp](../../includes/glossary-terms/sprints.md)] ## Sprint backlog -An interactive list of work items that have been assigned to the same sprint or iteration path for a team. The sprint backlog supports teams that use Scrum methodologies. Learn more: [Sprint planning](../../boards/sprints/assign-work-sprint.md). +An interactive list of work items assigned to the same sprint or iteration path for a team. The sprint backlog supports teams that use Scrum methodologies. Learn more: [Sprint planning](../../boards/sprints/assign-work-sprint.md). + +## Stakeholder + +A user account granted membership to an organization in an Azure DevOps instance with Stakeholder access. With Stakeholder access, you can add and modify work items, check project status, manage pipelines, and view and manage dashboards. For more information, see [Get started as a Stakeholder](../../organizations/security/get-started-stakeholder.md). [!INCLUDE [temp](../../includes/glossary-terms/taskboard.md)] [!INCLUDE [temp](../../includes/glossary-terms/teams.md)] +## Team group + +A security group that is defined when a team is created and automatically populated with members as they're added to the team. + +::: moniker range="azure-devops" + +## Tenant + +A Microsoft Entra ID used to manage access or billing. For more information, see [Change Microsoft Entra tenant.](../../organizations/accounts/change-organization-location.md) + +::: moniker-end + [!INCLUDE [temp](../../includes/glossary-terms/tfvc-repo.md)] +## Valid users + +Valid users are users that Azure DevOps recognizes as being able to connect to the account or a project. When you add accounts of users directly to a built-in group or through a Windows, Active Directory, or Microsoft Entra group, they're automatically added to one of the valid user groups. For more information, see [Get started with permissions, access, and security groups](../../organizations/security/about-permissions.md). + [!INCLUDE [temp](../../includes/glossary-terms/widgets.md)] [!INCLUDE [temp](../../includes/glossary-terms/work-items.md)] diff --git a/docs/project/navigation/go-to-project-repo.md b/docs/project/navigation/go-to-project-repo.md index 056a13b03c8..e59a18b4c09 100644 --- a/docs/project/navigation/go-to-project-repo.md +++ b/docs/project/navigation/go-to-project-repo.md @@ -15,14 +15,13 @@ ms.date: 04/04/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - Several features depend on the project, repository, or team that you have selected. For example, dashboards, backlogs, and board views will change depending on the project and team you select. -Also, when you add a work item, the system references the default area and iteration paths defined for the team context. Work items you add from the team dashboard (new work item widget) and queries page are assigned the team default iteration. Work items you add from a team backlog or board, are assigned the team default backlog iteration. To learn more, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). +Also, when you add a work item, the system references the default area and iteration paths defined for the team context. Work items you add from the team dashboard (new work item widget) and queries page are assigned the team default iteration. Work items you add from a team backlog or board, are assigned the team default backlog iteration. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). ## Prerequisites -* You must be added to a project as a member of the **Contributors** or administrator security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). +[!INCLUDE [prerequisites-contributor-only](../../includes/prerequisites-contributor-only.md)] ::: moniker range="azure-devops" @@ -37,7 +36,7 @@ Also, when you add a work item, the system references the default area and itera From the **Projects** page you can quickly navigate to a project that you have permissions to view. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. @@ -56,48 +55,16 @@ From the **Projects** page you can quickly navigate to a project that you have p > [!div class="mx-imgBorder"] > ![Screenshot showing Projects page, filter on Fabrikam.](media/projects-page/filter-projects-vert.png) -1. Choose **Create Project** to add a project. You must be an account administrator or a member of the Project Collection Administrators group to [add a project](../../organizations/projects/create-project.md). +1. Choose **Create Project** to add a project. Be an account administrator or a member of the Project Collection Administrators group to [add a project](../../organizations/projects/create-project.md). > [!div class="mx-imgBorder"] > ![Screenshot showing selection of account home, Projects page, New project.](../../organizations/projects/media/create-project/projects-hub-vert-create-project.png) ::: moniker-end -::: moniker range="tfs-2018" - -From the **Projects** page you can quickly navigate to a project or a team that you've accessed or worked in previously. Projects and teams are listed in the order you've last accessed, with the most recent five projects accessed appearing first. All projects you've accessed are listed within the **All** section. - -1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing web portal, Azure DevOps logo, TFS.](../../media/settings/open-project-hub-horz.png) - - The projects you most recently viewed are displayed, followed by a list of all projects in alphabetic order. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing projects page, TFS-2018.](media/projects-page/account-home-projects.png) - -1. As you hover over a project or team, you can choose one of the links to go to **Home** or **Dashboards**, **Code**, **Work**, **Build and Release**, **Test**, or **Wiki** pages. Choose the ![favorites](../../media/icons/icon-favorite-star.png) star icon to mark the project as a favorite. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing account home, Projects page, hover over a project.](media/projects-page/account-home-projects-hover-links.png) - -2. You can filter the project and team list using the *Filter projects and teams* search box. Simply type a keyword contained within the name of a project or team. Here we type **Fabrikam** to find all projects or teams with *Fabrikam* in their name. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing Projects page, filter on Fabrikam.](media/projects-page/account-home-search-projects-fabrikam.png) - -3. Choose **New Project** to add a project. You must be an account administrator or a member of the Project Collection Administrators group to [add a project](../../organizations/projects/create-project.md). - - > [!div class="mx-imgBorder"] - > ![Screenshot showing selection of account home, Projects page, New project.](media/projects-page/account-home-projects-new-project.png) - -::: moniker-end - - ## View and open a repository -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Choose **Repos>Files**. @@ -110,27 +77,14 @@ From the **Projects** page you can quickly navigate to a project or a team that ::: moniker-end - -::: moniker range="tfs-2018" - -1. Choose **Code**. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing Open Code, previous nav.](../../organizations/projects/media/browse-code/select-code-hub.png) - -1. Select the repository from the selector. - - > [!div class="mx-imgBorder"] - > ![Screenshot showing selecting repository.](../../organizations/projects/media/browse-code/select-repository.png) - ::: moniker-end - + ## Switch to a different team -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" From a user page, one under—**Boards**, **Repos**, **Pipelines**, or **Test Plans**—you can't switch to a different team, you can [only select team artifacts](use-breadcrumbs-selectors.md). @@ -141,13 +95,6 @@ From a **Project Settings>Work>Team configuration** page, you select a team from ::: moniker-end - -::: moniker range="tfs-2018" -You can switch your team focus to one that you've recently viewed from the project/team selector. If you don't see the team or project you want, choose **Browse…** or choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to [access the **Projects** page](work-across-projects.md). - -![Screenshot showing selecting another team from the project menu.](../../media/work-web-portal-ts-switch-team-focus.png) -::: moniker-end - ## Related articles - [Work across projects](work-across-projects.md) - [Add teams](../../organizations/settings/add-teams.md?toc=/azure/devops/project/navigation/toc.json&bc=/azure/devops/project/navigation/breadcrumb/toc.json) \ No newline at end of file diff --git a/docs/project/navigation/go-to-service-page.md b/docs/project/navigation/go-to-service-page.md index a4bb64cec4f..3f717e0811c 100644 --- a/docs/project/navigation/go-to-service-page.md +++ b/docs/project/navigation/go-to-service-page.md @@ -8,7 +8,7 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 06/23/2024 --- @@ -22,132 +22,71 @@ The web portal for Azure DevOps provides support for software development teams This article shows you how to navigate to functional and administrative tasks available from the web portal. There are three levels of administrative tasks: team, project, and organization. -If you don't have a project yet, [create one](../../user-guide/sign-up-invite-teammates.md?toc=/azure/devops/project/navigation/toc.json&bc=/azure/devops/project/navigationbreadcrumb/toc.json). If you don't have access to the project, [get invited to the team](../../organizations/security/add-users-team-project.md). - ::: moniker-end ::: moniker range="< azure-devops" -This article shows you how to navigate to functional and administrative tasks available from the web portal. There are four levels of administrative tasks: team, project, collection, and server. - -If you don't have a project yet, [create one](../../organizations/projects/create-project.md). If you don't have access to the project, [get invited to the team](../../organizations/security/add-users-team-project.md). +This article shows you how to navigate to functional and administrative tasks available from the web portal. There are four levels of administrative tasks: team, project, collection, and server. ::: moniker-end +## Prerequisites + +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.md)] + ## Open a service or functional task page Services support getting work done—managing code, planning and tracking work, defining and managing pipelines, creating and running tests, and so on. -::: moniker range=">= azure-devops-2019" > [!NOTE] -> Only those services that are enabled will appear in the user interface. For example, if **Boards** is disabled, then **Boards** or **Work** and all pages associated with that service won't appear. To enable or disable a service, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -::: moniker-end +> Only those services that are enabled appear in the user interface. For example, if **Boards** is disabled, then **Boards** or **Work** and all pages associated with that service don't appear. To enable or disable a service, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -::: moniker range=">= azure-devops-2019" You open a service by choosing the service from the sidebar and then selecting from the available pages. -For example, here we select **Boards>Backlogs**. - -> [!div class="mx-imgBorder"] -> ![Open a service, vertical sidebar](media/go-to-app/work-backlogs-selection.gif) +For example, here we select **Boards** > **Backlogs**. -Within the page you may select a specific view or artifact, such as a team backlog or choose another page. - -::: moniker-end +:::image type="content" source="media/go-to-app/work-backlogs-selection.gif" alt-text="Screenshot of Boards -> Backlogs."::: +Within the page you might select a specific view or artifact, such as a team backlog or choose another page. -::: moniker range="tfs-2018" - -You open a service by choosing it from the horizontal blue bar. Then, select from the available pages. - -For example, here we select **Work>Work Items**. - -![Open a service, previous navigation gif](media/go-to-app/project-app-page-horizontal-selection.png) - -::: moniker-end - - + ## Open team settings Select configurations are made to teams through the team settings pages. For an overview of all team settings, see [About user, team, project, and organization-level settings](../../organizations/settings/about-settings.md#team). -::: moniker range=">= azure-devops-2019" -1. Choose **Project Settings**. +1. Choose **Project settings**. - > [!div class="mx-imgBorder"] - > ![Open project settings](../../media/settings/open-project-settings-vert-brn.png) + :::image type="content" source="../../media/settings/open-project-settings-vert-brn.png" alt-text="Screenshot of project settings selection."::: 1. Expand **Boards** and choose **Team configuration**. - > [!div class="mx-imgBorder"] - > ![Open Team configuration](media/go-to-app/team-configurations-new-nav.png) + :::image type="content" source="media/go-to-app/team-configurations-new-nav.png" alt-text="Screenshot of team configuration selection."::: -1. Choose one of the pages **General**, **Iterations**, **Areas**, or **Templates** to configure settings for the team. To learn more, see [Manage teams](../../organizations/settings/manage-teams.md). +1. Choose one of the pages **General**, **Iterations**, **Areas**, or **Templates** to configure settings for the team. For more information, see [Manage teams](../../organizations/settings/manage-teams.md). 1. If you need to switch to a different team, use the team selector within the breadcrumbs. - - > [!div class="mx-imgBorder"] - > ![Team Configuration, Team breadcrumb](../../organizations/settings/media/team-defaults/select-team-context.png) -1. To add a team administrator, add team members, or change the team profile, choose **Teams** from the vertical sidebar, and then choose the name of the team you want to configure. - -::: moniker-end - -::: moniker range="tfs-2018" + :::image type="content" source="../../organizations/settings/media/team-defaults/select-team-context.png" alt-text="Screenshot of team selector."::: -You open team settings from the top navigation bar. Select the team you want and then choose the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: gear icon. To learn more about switching your team focus, see [Switch project, repository, team](go-to-project-repo.md#switch-team-context). - -> [!div class="mx-imgBorder"] -> ![Open team settings](../../organizations/settings/media/team-defaults/open-team-settings-horz.png) - -1. Choose one of the pages **General**, **Iterations**, **Areas**, or **Templates** to configure settings for the team. To learn more, see [Manage teams](../../organizations/settings/manage-teams.md). - -1. To add a team administrator, add team members, or change the team profile, choose **Overview**. -2. - ::: moniker-end +1. To add a team administrator, add team members, or change the team profile, choose **Teams** from the vertical sidebar, and then choose the name of the team you want to configure. - + ## Open project settings Administrators configure resources for a project and manage project-level permissions from the **Project settings** pages. Tasks performed in this context can impact the project and team functions. For an overview of all project settings, see [Project administrator role and managing projects](../../organizations/settings/about-settings.md#project). -::: moniker range=">= azure-devops-2019" 1. Choose **Project Settings**. - > [!div class="mx-imgBorder"] - > ![Open project settings](../../media/settings/open-project-settings-vert-brn.png) - -1. From there, you can choose a page from the list. Settings are organized based on the service they support. Expand or collapse the major sections such as **Boards**, **Build and release**, **Code**, **Test**, and **Extensions** to select from the list. - - > [!div class="mx-imgBorder"] - > ![Open Project settings](media/go-to-app/project-setting-hubs.png) - -::: moniker-end - - -::: moniker range="tfs-2018" - -From a user context, open **Project settings** by choosing the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: gear icon. -::: moniker-end - -::: moniker range="tfs-2018" - - - - -Open any admin page by choosing it's name. Choose or hover over the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: gear icon to access other administrative options. Note that you can choose any of the user-context areas—**Dashboards**, **Code**, **Work**—to return to the user context. - -![Project Settings](../../media/settings/open-project-settings-horz.png) - -::: moniker-end + :::image type="content" source="../../media/settings/open-project-settings-vert-brn.png" alt-text="Screenshot of project settings selection."::: +1. From there, you can choose a page from the list. Settings are organized based on the service they support, such as **Boards**, **Pipelines**, **Repos**, and **Test**. - + ::: moniker range="azure-devops" @@ -155,65 +94,25 @@ Open any admin page by choosing it's name. Choose or hover over the :::image typ Organization owners and members of the Project Collection Administrators group configure resources for all projects or the entire organization, including adding users, from the Organization settings pages. This includes managing permissions at the organization-level. For an overview of all organization settings, see [Project collection administrator role and managing collections of projects](../../organizations/settings/about-settings.md#admin). +From there, you can choose a page from the list of settings. Settings are organized based on the service they support, such as **Boards**, **Repos**, **Pipelines**, and **Artifacts**. + ::: moniker-end - ::: moniker range="< azure-devops" ## Open Collection settings Members of the Project Collection Administrators group configure resources for all projects or the entire project collection from the Collection settings pages. This includes managing permissions at the collection-level. For an overview of all collection-level settings, see [Project collection administrator role and managing collections of projects](../../organizations/settings/about-settings.md#admin). -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - 1. Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. Then choose **Admin settings**. - > [!div class="mx-imgBorder"] - > ![Open Organization settings](../../media/settings/open-admin-settings-vert.png) - -1. From there, you can choose a page from the list of settings. Settings are organized based on the service they support. Expand or collapse the major sections such as **Boards** and **Build and release** to select a page from the list. - - > [!div class="mx-imgBorder"] - > ![Account settings, Projects](media/go-to-app/admin-account-settings.png) - -::: moniker-end - + :::image type="content" source="../../media/settings/open-admin-settings-vert.png" alt-text="Screenshot of organization settings selection."::: -::: moniker range="tfs-2018" - -1. Choose the :::image type="icon" source="../../media/icons/gear-icon.png" border="false"::: gear icon to open **Organization settings** or **Collection settings**. - - > [!div class="mx-imgBorder"] - > ![Organization settings, Policy page, Security policies](../../media/settings/open-organization-settings.png) - -1. From there, you can choose a page. Settings are organized based on the service they support. - - > [!div class="mx-imgBorder"] - > ![Account settings, Projects](media/go-to-app/open-admin-settings-horizontal.png) +1. From there, you can choose a page from the list of settings. Settings are organized based on the service they support, such as **Boards**, **Repos**, and **Pipelines**. ::: moniker-end - -::: moniker range="tfs-2018" - -## Open Server settings - -Members of the Team Foundation Server Administrators group configure resources for the server instance from the Server settings pages. - -1. From the web portal home page for a project, choose or hover over the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: gear icon and select **Server settings**. - - TFS 2017, Web portal, open the Server settings admin context - -1. Choose **Access levels**, to set access levels for a member or group. For details, see [Change access levels](../../organizations/security/change-access-levels.md). - - If you don't see **Access levels**, you aren't a TFS administrator and don't have permission. [Here's how to get permissions](/azure/devops/server/admin/add-administrator). - -::: moniker-end - - ## Related articles - [Manage projects](../../organizations/projects/about-projects.md) -- [About team, project, and admin settings](../../organizations/settings/about-settings.md) \ No newline at end of file +- [About team, project, and admin settings](../../organizations/settings/about-settings.md) diff --git a/docs/project/navigation/index.md b/docs/project/navigation/index.md index 563ac88c3e1..48af6f8a741 100644 --- a/docs/project/navigation/index.md +++ b/docs/project/navigation/index.md @@ -8,88 +8,44 @@ ms.author: chcomley author: chcomley ms.topic: overview monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 03/11/2025 --- -# Web portal navigation in Azure DevOps +# Navigate the Azure DevOps web portal [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] ::: moniker range="azure-devops" -The web portal for Azure DevOps is organized around a set of services as well as administrative pages and several task specific features such as the search box. The service labels differ depending on whether you work from Azure DevOps Services or Azure DevOps on premises and its version. +The Azure DevOps web portal is organized into various services, administrative pages, and task-specific features like the search box. Service labels vary depending on whether you’re using Azure DevOps Services or an on-premises version. -[!INCLUDE [temp](../../includes/version-selector-minimize.md)] +[!INCLUDE [temp](../../includes/version-selector.md)] -Each service provides you with one or more pages which support a number of features and functional tasks. Within a page, you may then have a choice of options to select a specific artifact or add an artifact. +Each service offers multiple pages with numerous features and functional tasks. Within each page, you can choose options to select or add specific artifacts. ::: moniker-end -::: moniker range="azure-devops-2019" +## Key features and navigation -The web portal for Azure DevOps Server is organized around a set of services—such as, **Overview**, **Boards**, **Repos**, **Pipelines**, **Test Plans**, and **Artifacts**— as well as administrative pages and several task-specific features such as the search box. Each service provides you with one or more pages which support a number of features and functional tasks. Within a page, you may then have a choice of options to select a specific artifact or add an artifact. +Here's what you need to know to start using the web portal effectively. -Each service provides you with one or more pages which support a number of features and functional tasks. Within a page, you may then have a choice of options to select a specific artifact or add an artifact. +- [**Open a service, page, or settings**](go-to-service-page.md): Use to switch to a different [service or functional area](../../user-guide/services.md) +- [**Add an artifact or team**](add-artifact-team.md): Use to quickly add a work item, Git repo, build or release pipelines, or a new team +- [**Open another project or repo**](work-across-projects.md): Use to switch to a different project or access work items and pull requests defined in different projects, or your favorite items +- [**Open team artifacts, use breadcrumbs, selectors and directories**](use-breadcrumbs-selectors.md): Use to navigate within a service, open other artifacts, or return to a root function +- [**Work with favorites**](set-favorites.md): Mark your favorite artifacts for quick navigation +- [**Search box**](../search/get-started-search.md): Use to find code, work items, or wiki content +- [**Your profile menu**](../../organizations/settings/set-your-preferences.md?toc=/azure/devops/project/navigation/toc.json&bc=/azure/devops/project/navigation/breadcrumb/toc.json): Use to set personal preferences, notifications, and enable preview features +- [**Settings**](../../organizations/settings/about-settings.md#project-administrator-role-and-managing-projects): Use to add teams, manage security, and configure other project and organization level resources. -::: moniker-end - - -::: moniker range="tfs-2018" - -The web portal for Team Foundation Server is organized around a set of applications—such as, **Dashboards**, **Code**, **Work**, **Build and Release**—as well as administrative pages and several task-specific features such as the search box. Each service provides you with one or more pages which support a number of features and functional tasks. Within a page, you may then have a choice of options to select a specific artifact or add an artifact. -::: moniker-end - -Here's what you need to know to get up and running using the web portal. - -::: moniker range=">= azure-devops-2019" -- [**Open a service, page, or settings**](go-to-service-page.md): use to switch to a different [service or functional area](../../user-guide/services.md) -- [**Add an artifact or team**](add-artifact-team.md): use to quickly add a work item, Git repo, build or release pipelines, or a new team -- [**Open another project or repo**](work-across-projects.md): use to switch to a different project or access work items and pull requests defined in different projects, or items you've favorited -- [**Open team artifacts, use breadcrumbs, selectors and directories**](use-breadcrumbs-selectors.md): use to navigate within a service, to open other artifacts, or return to a root function -- [**Work with favorites**](set-favorites.md): favorite artifacts to support quick navigation -- [**Search box**](../search/get-started-search.md): use to find code, work items, or wiki content -- [**Your profile menu**](../../organizations/settings/set-your-preferences.md?toc=/azure/devops/project/navigation/toc.json&bc=/azure/devops/project/navigation/breadcrumb/toc.json): use to set personal preferences, notifications, and enable preview features -- [**Settings**](../../organizations/settings/about-settings.md#project-administrator-role-and-managing-projects): use to add teams, manage security, and configure other project and organization level resources. - -::: moniker-end - - -::: moniker range="tfs-2018" -- [**Open a service, page, or settings**](go-to-service-page.md): use to switch to a different service or functional area -- [**Add an artifact or team**](add-artifact-team.md): use to quickly add a work item, Git repo, build or release pipelines, or a new team -- [**Open another project or repo, or switch to a different team**](work-across-projects.md): use to switch to a different project or browse teams -- [**Work across projects**](work-across-projects.md): use to quickly open work assigned to you, your active pull requests, or items you've favorited -- [**Open team artifacts, use breadcrumbs & selectors**](use-breadcrumbs-selectors.md): use to navigate within a service, to open other artifacts or return to a root function -- [**Work with favorites**](set-favorites.md): favorite artifacts to support quick navigation -- [**Search box**](../search/get-started-search.md): use to find code, work items, or wiki content -- [**Your profile menu**](../../organizations/settings/set-your-preferences.md?toc=/azure/devops/project/navigation/toc.json&bc=/azure/devops/project/navigation/breadcrumb/toc.json): use to set personal preferences, notifications, and enable preview features -- [**Settings**](../../organizations/settings/about-settings.md#project-administrator-role-and-managing-projects): use to add teams, manage security, and configure other project and organization-level resources. - -::: moniker-end - -::: moniker range=">= azure-devops-2019" > [!NOTE] -> Only those services that are enabled will appear in the user interface. For example, if **Boards** is disabled, then **Boards** or **Work** and all pages associated with that service won't appear. To enable or disable a service, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -::: moniker-end +> Only enabled services are visible in the user interface. For example, if **Boards** is disabled, then **Boards** or **Work** and all pages associated with that service don't appear. To enable or disable a service, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). +Select services—such as **Boards**, **Repos**, and **Pipelines**—from the sidebar and pages within those services. -::: moniker range=">= azure-devops-2019" -You select services —such as **Boards**, **Repos**, and **Pipelines**— from the sidebar and pages within those services. +![Screenshot shows vertical sidebar.](media/gif-images/vertical-nav.gif) -![Vertical sidebar](media/gif-images/vertical-nav.gif) - -::: moniker-end - - -::: moniker range="tfs-2018" -You select a service—such as **Code**, **Work**, and **Build and Release**—from the horizontal bar and pages within those services. - -![Horizontal navigation](media/gif-images/horizontal-nav.gif) - -::: moniker-end - - -Now that you have an understanding of how the user interface is structured, it's time to get started using it. As you can see, there are a lot of features and functionality. +Now that you understand the user interface structure, it’s time to start using it. You can find a wide range of features and functionalities to explore. If all you need is a code repository and bug tracking solution, then start with [Get started with Git](../../repos/git/gitquickstart.md) and [Manage bugs](../../boards/backlogs/manage-bugs.md). @@ -99,7 +55,7 @@ To start planning and tracking work, see [About Agile tools](../../boards/get-st ::: moniker range="azure-devops" -You connect to the web portal through a supported web browser —such as the latest versions of Edge, Chrome, Safari, or Firefox. Only users who have been [added to a project](../../organizations/accounts/add-organization-users.md) can connect. This is typically done by the organization owner. +You connect to the web portal through a supported web browser—such as the latest versions of Microsoft Edge, Chrome, Safari, or Firefox. Only users [added to a project](../../organizations/accounts/add-organization-users.md) can connect, which is typically done by the organization owner. Five account users are free as are Visual Studio subscribers and stakeholders. After that, you need to [pay for more users](../../organizations/billing/buy-basic-access-add-users.md). Find out more about licensing from [Azure DevOps pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). @@ -107,14 +63,6 @@ Limited access is available to an unlimited number of stakeholders for free. For ::: moniker-end -::: moniker range="<= azure-devops-2019" - -You connect to the web portal through a supported web browser—such as the latest versions of Edge, Chrome, Safari, or Firefox. Only users who have been [added to a project](../../organizations/security/add-users-team-project.md) can connect. This is typically done by a member of the Project Administrators group. - -Limited access is available to an unlimited number of stakeholders for free. For details, see [Work as a Stakeholder](../../organizations/security/get-started-stakeholder.md). Most regular contributors must have a TFS client access license (CAL). All Visual Studio subscriptions include a TFS CAL. Find out more about licensing from [TFS pricing](https://www.visualstudio.com/team-services/tfs-pricing). - -::: moniker-end - ## Refresh the web portal @@ -123,7 +71,6 @@ If data doesn't appear as expected, the first thing to try is to refresh your we [!INCLUDE [temp](../../includes/when-to-refresh-client.md)] - ## Differences between the web portal and Visual Studio Although you can access source code, work items, and builds from both clients, some task specific tools are only supported in the web browser or an IDE but not in both. Supported tasks differ depending on whether you connect to a Git or TFVC repository from Team Explorer. @@ -141,7 +88,7 @@ Although you can access source code, work items, and builds from both clients, s :::row::: :::column span="2"::: - [Product backlog](../../boards/backlogs/create-your-backlog.md), [Portfolio backlogs](../../boards/boards/kanban-epics-features-stories.md), [Sprint backlogs](../../boards/sprints/assign-work-sprint.md), [Taskboards](../../boards/sprints/task-board.md), [Capacity planning](../../boards/sprints/set-capacity.md) - - [Kanban boards](../../boards/boards/kanban-overview.md) + - [Boards](../../boards/boards/kanban-overview.md) - [Dashboards](../../report/dashboards/dashboards.md), [Widgets](../../report/dashboards/widget-catalog.md), [Charts](../../report/dashboards/charts.md) - [Request feedback](/previous-versions/azure/devops/project/feedback/get-feedback) - [Web-based Test Management](../../test/overview.md) @@ -149,17 +96,16 @@ Although you can access source code, work items, and builds from both clients, s :::column-end::: :::column span="2"::: - Git: [Changes](../../repos/git/commits.md#stage-your-changes-and-commit), [Branches](../../repos/git/create-branch.md), [Pull Requests](../../repos/git/pull-requests.md), [Sync](../../repos/git/pulling.md), [Work Items](../../boards/backlogs/add-work-items.md), [Builds](/previous-versions/ms181721(v=vs.140)) - - TFVC: [My Work](../../repos/tfvc/develop-code-manage-pending-changes.md#use-the-my-work-page-to-manage-your-work), [Pending Changes](../../repos/tfvc/develop-code-manage-pending-changes.md#use-the-pending-changes-page-to-manage-your-work) | [Source Control Explorer](../../repos/tfvc/develop-code-manage-pending-changes.md#use-solution-explorer-or-source-control-explorer-to-view-what-you-changed), [Work Items](../../boards/backlogs/add-work-items.md) | [Builds](/previous-versions/ms181721(v=vs.140)) + - TFVC: [My Work](../../repos/tfvc/develop-code-manage-pending-changes.md), [Pending Changes](../../repos/tfvc/develop-code-manage-pending-changes.md) | [Source Control Explorer](../../repos/tfvc/develop-code-manage-pending-changes.md#use-solution-explorer-or-source-control-explorer-to-view-what-you-changed), [Work Items](../../boards/backlogs/add-work-items.md) | [Builds](/previous-versions/ms181721(v=vs.140)) - Greater integration with work items and Office integration clients. You can open a work item or query result in an office supported client. :::column-end::: :::row-end::: --- - [!INCLUDE [temp](../../repos/git/includes/note-new-git-tool.md)] -## Resources +## Related articles - [Manage projects](../../organizations/projects/about-projects.md) -- [Project & Organizational Settings](../../organizations/settings/about-settings.md#project-administrator-role-and-managing-projects) +- [Manage settings for projects and organizations](../../organizations/settings/about-settings.md#project-administrator-role-and-managing-projects) diff --git a/docs/project/navigation/keyboard-shortcuts.md b/docs/project/navigation/keyboard-shortcuts.md index 8ae624201fc..f3476a608a0 100644 --- a/docs/project/navigation/keyboard-shortcuts.md +++ b/docs/project/navigation/keyboard-shortcuts.md @@ -1,14 +1,14 @@ --- title: Keyboard shortcuts for web portal and Team Explorer titleSuffix: Azure DevOps -description: Learn about keyboard shortcuts for the web portal for Azure DevOps and Team Explorer +description: Learn about keyboard shortcuts for the web portal for Azure DevOps and Team Explorer, including wikis. ms.custom: Navigation ms.subservice: azure-devops-projects ms.topic: conceptual ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 03/11/2025 --- # Keyboard shortcuts for Azure DevOps and Team Explorer @@ -25,7 +25,7 @@ You can use these keyboard shortcuts when you work in the web portal for Azure D ### Web portal global shortcuts -Select **?** to access global and page-specific shortcuts. +To access global and page-specific shortcuts, select **?**. Page-specific shortcuts work only when you're on a specific page. For example, select **g**, **c** to open the **Code** page, and then select **c**, **p** to create a pull request. These navigation shortcuts work as long as the focus isn't on an input control. @@ -44,7 +44,7 @@ You can use these keyboard shortcuts when you work in a list in the web portal f |Down arrow|Move focus down| |Ctrl+Home|Move focus to top of list| |Ctrl+End|Move focus to bottom of list| -|Ctrl+Up arrow|Move item up in the list| +|Ctrl+Up arrow|Move up item in the list| |Ctrl+Down arrow|Move item down in the list| |Shift+Up arrow|Highlight consecutive items above the current line or field| |Shift+Down arrow|Highlight consecutive items below the current line or field| @@ -52,21 +52,15 @@ You can use these keyboard shortcuts when you work in a list in the web portal f |Esc|Dismiss context menu| |Enter|Choose selected menu item| -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Repos ::: moniker-end -::: moniker range="tfs-2018" - -## Code - -::: moniker-end - [!INCLUDE [temp](../../includes/keyboard-shortcuts/code-shortcuts.md)] -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Work items @@ -74,7 +68,7 @@ You can use these keyboard shortcuts when you work in a list in the web portal f ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Work item forms @@ -106,16 +100,49 @@ You can use these keyboard shortcuts when you work in a list in the web portal f [!INCLUDE [temp](../../includes/keyboard-shortcuts/test-shortcuts.md)] -## Wiki + -::: moniker range="tfs-2018" +## Wiki -> [!NOTE] -> Keyboard shortcuts to manage Wiki pages are supported on TFS 2018.2 or later versions. To download TFS 2018.2, see [Team Foundation Server 2018 Update 2 Release Notes](/visualstudio/releasenotes/tfs2018-update2). +You can use the following keyboard shortcuts when you [manage or edit wiki pages](../../project/wiki/add-edit-wiki.md). To view valid shortcuts, from the wiki page, select **?**. -::: moniker-end +::: moniker range=">= azure-devops-2020" + +### Manage wiki page shortcuts + +|Shortcut|Action| +|---|---| +|n|Add new page| +|e|Edit page| +|c|Create new subpage| +|Ctrl+Down arrow|Move page down the order| +|Ctrl+Up arrow|Move page up the order| +|Ctrl+P|Print page| +|Ctrl+Shift+b|Create work item from selected text| + +The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: + +:::image type="content" source="../../media/keyboard-shortcuts/wiki-manage-cloud.png" alt-text="Screenshot that shows Azure DevOps 2020 manage Wiki page keyboard shortcuts."::: -[!INCLUDE [temp](../../includes/keyboard-shortcuts/wiki-shortcuts.md)] +### Edit wiki page shortcuts + +|Shortcut|Action| +|---|---| +|Ctrl+b|Bold text| +|Ctrl+i|Italicize text| +|Ctrl+k|Insert hyperlink| +|Ctrl+c|Copy text| +|Ctrl+v|Paste copied text| +|Ctrl+Shift+f|Format tables| +|Ctrl+s|Save changes| +|Ctrl+Enter|Save and close| +|Esc|Close| + +The following screenshot shows the list of keyboard shortcuts as it appears in Azure DevOps: + +:::image type="content" source="../../media/keyboard-shortcuts/wiki-edit-cloud.png" alt-text="Screenshot that shows Azure DevOps 2020 edit Wiki page keyboard shortcuts."::: + +::: moniker-end ## Team Explorer @@ -132,7 +159,7 @@ You can use these shortcuts when you work in Team Explorer. |Ctrl+0, e|Open [Branches (Git)](../../repos/git/gitquickstart.md)| |Ctrl+0, g|Open [Changes (Git)](../../repos/git/gitquickstart.md)| |Ctrl+0, h|Open Home| -|Ctrl+0, m|Open [My Work (TFVC)](../../repos/tfvc/share-your-code-in-tfvc-vs.md)| +|Ctrl+0, m|Open [My Work Team Foundation Version Control (TFVC)](../../repos/tfvc/share-your-code-in-tfvc-vs.md)| |Ctrl+0, p|Open [Pending changes (TFVC)](../../repos/tfvc/suspend-your-work-manage-your-shelvesets.md)| |Ctrl+0, r|Open [Reports](/previous-versions/azure/devops/report/sql-reports/reporting-services-reports)| |Ctrl+0, s|Open Settings| @@ -167,7 +194,7 @@ You can use these shortcuts when you work in Team Explorer. |Shift+Alt, l|Link to new work item| |Enter|Open selected work item| -You can use shortcuts for query results when you have a list of work items, such as the query results view or a list of linked work items within a work item form. +You can use shortcuts for query results when you're viewing a list of work items, whether in the query results view or within a list of linked work items in a work item form. [!INCLUDE [temp](../../includes/keyboard-shortcuts/queries-te-shortcuts.md)] @@ -175,14 +202,15 @@ You can use shortcuts for query results when you have a list of work items, such Team Explorer is a plug-in for Visual Studio. You gain access to Team Explorer when you install the free [Visual Studio Community](https://visualstudio.microsoft.com/products/free-developer-offers-vs.aspx) version, another version of Visual Studio, or Visual Studio Team Explorer 2017. -## Related articles +## Next steps -- [Keyboard shortcuts for Microsoft Test Manager](/previous-versions/visualstudio/visual-studio-2013/ff458183(v=vs.120)) -- [Customize Visual Studio keyboard shortcuts](/visualstudio/ide/identifying-and-customizing-keyboard-shortcuts-in-visual-studio) -- [Default keyboard shortcuts for Visual Studio](/visualstudio/ide/default-keyboard-shortcuts-in-visual-studio) -- [Accessibility features of Visual Studio](/visualstudio/ide/reference/accessibility-features-of-visual-studio) -- [Web portal navigation](../../project/navigation/index.md) +>[!div class="nextstepaction"] +>[Work in Team Explorer](../../user-guide/work-team-explorer.md) -## Next steps +## Related articles -Learn more about [working in Team Explorer](../../user-guide/work-team-explorer.md). +- [Learn keyboard shortcuts for Microsoft Test Manager](/previous-versions/visualstudio/visual-studio-2013/ff458183(v=vs.120)) +- [Customize Visual Studio keyboard shortcuts](/visualstudio/ide/identifying-and-customizing-keyboard-shortcuts-in-visual-studio) +- [Use default keyboard shortcuts for Visual Studio](/visualstudio/ide/default-keyboard-shortcuts-in-visual-studio) +- [Explore accessibility features of Visual Studio](/visualstudio/ide/reference/accessibility-features-of-visual-studio) +- [Navigate the web portal](../../project/navigation/index.md) diff --git a/docs/project/navigation/media/breadcrumbs/query-dropdown-new-boards-hubs.png b/docs/project/navigation/media/breadcrumbs/query-dropdown-new-boards-hubs.png new file mode 100644 index 00000000000..38940576869 Binary files /dev/null and b/docs/project/navigation/media/breadcrumbs/query-dropdown-new-boards-hubs.png differ diff --git a/docs/project/navigation/media/mobile-work-account-work-items-pages.png b/docs/project/navigation/media/mobile-work-account-work-items-pages.png index f27f16502a1..51266fcb915 100644 Binary files a/docs/project/navigation/media/mobile-work-account-work-items-pages.png and b/docs/project/navigation/media/mobile-work-account-work-items-pages.png differ diff --git a/docs/project/navigation/media/mobile-work-click-list.png b/docs/project/navigation/media/mobile-work-click-list.png index ba0d4cba079..47011946b16 100644 Binary files a/docs/project/navigation/media/mobile-work-click-list.png and b/docs/project/navigation/media/mobile-work-click-list.png differ diff --git a/docs/project/navigation/media/mobile-work-click-work-items.png b/docs/project/navigation/media/mobile-work-click-work-items.png index 2f16126f4ef..761e70e58e3 100644 Binary files a/docs/project/navigation/media/mobile-work-click-work-items.png and b/docs/project/navigation/media/mobile-work-click-work-items.png differ diff --git a/docs/project/navigation/media/mobile-work-email-notice.png b/docs/project/navigation/media/mobile-work-email-notice.png index ce2bb4e515c..75fe007ea10 100644 Binary files a/docs/project/navigation/media/mobile-work-email-notice.png and b/docs/project/navigation/media/mobile-work-email-notice.png differ diff --git a/docs/project/navigation/media/mobile-work-intro-1.png b/docs/project/navigation/media/mobile-work-intro-1.png index c5a4753a50f..dd76cc88496 100644 Binary files a/docs/project/navigation/media/mobile-work-intro-1.png and b/docs/project/navigation/media/mobile-work-intro-1.png differ diff --git a/docs/project/navigation/media/mobile-work-send-feedback.png b/docs/project/navigation/media/mobile-work-send-feedback.png index 048667ee974..67f2bbf9c33 100644 Binary files a/docs/project/navigation/media/mobile-work-send-feedback.png and b/docs/project/navigation/media/mobile-work-send-feedback.png differ diff --git a/docs/project/navigation/media/mobile-work-view-history.png b/docs/project/navigation/media/mobile-work-view-history.png index 5037017b9fb..2c3bbc752b2 100644 Binary files a/docs/project/navigation/media/mobile-work-view-history.png and b/docs/project/navigation/media/mobile-work-view-history.png differ diff --git a/docs/project/navigation/media/preview-features/manage-preview-features.png b/docs/project/navigation/media/preview-features/manage-preview-features.png new file mode 100644 index 00000000000..187aa3aacd3 Binary files /dev/null and b/docs/project/navigation/media/preview-features/manage-preview-features.png differ diff --git a/docs/project/navigation/media/projects-page/view-work-across-projects.png b/docs/project/navigation/media/projects-page/view-work-across-projects.png index 83c89cd43ce..cecd59f403b 100644 Binary files a/docs/project/navigation/media/projects-page/view-work-across-projects.png and b/docs/project/navigation/media/projects-page/view-work-across-projects.png differ diff --git a/docs/project/navigation/mobile-work.md b/docs/project/navigation/mobile-work.md index 5fdfaa0d3d8..aa6800000ca 100644 --- a/docs/project/navigation/mobile-work.md +++ b/docs/project/navigation/mobile-work.md @@ -1,131 +1,141 @@ --- -title: View and update work items via a mobile browser +title: View and update work items via mobile browser titleSuffix: Azure DevOps -description: View and update work items from your mobile client when using Azure DevOps +description: View and update work items from your mobile client using Azure DevOps. ms.custom: Navigation ms.subservice: azure-devops-projects ms.topic: how-to ms.assetid: 1B91BB7F-1205-4E51-B33C-1349D3117408 ms.author: chcomley author: chcomley +ai-usage: ai-assisted monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 01/27/2025 --- -# View and update work items via the mobile browser +# View and update work items via mobile browser -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -With the mobile browser and work item form, you gain on-the-go features to stay on top of the latest updates made to work tracking. When you click any work item link on your mobile device, it will open a mobile-friendly version of the work item. From there, you can update the work item or access all work items assigned to you or that you're following. - -Mobile work item form +Use the mobile browser to stay updated on work tracking in Azure DevOps. When you select any work item link on your mobile device, it opens a mobile-friendly version of the work item. From there, you can update the work item or access all work items assigned to you or that you're following. + +:::image type="content" source="media/mobile-work-intro-1.png" alt-text="Screenshot of work item on mobile device."::: ::: moniker range="azure-devops" > [!NOTE] -> The mobile browser supports Azure DevOps work tracking. To sign up for free, go to [Azure DevOps Services](https://www.visualstudio.com/team-services/). The mobile browser is not an app, but a mobile view into select features. There is nothing to download. You access the mobile browser by clicking a link from a work item you receive in your mobile email application. +> The mobile browser supports Azure DevOps work tracking. To sign up for free, go to [Azure DevOps Services](https://www.visualstudio.com/team-services/). The mobile browser isn't an app, but a mobile view into select features. There's nothing to download. You access the mobile browser by selecting a link from a work item you receive in your mobile email application. ::: moniker-end ::: moniker range="< azure-devops" -> [!NOTE] -> The mobile browser is available for TFS 2018 and Azure DevOps Server 2019 and later versions. For downloads, see [Downloads](https://visualstudio.microsoft.com/downloads/). The mobile browser is not an app, but a mobile view into select features. There is nothing to download. You access the mobile browser by clicking a link from a work item you receive in your mobile email application. +> [!NOTE] +> The mobile browser is available for Azure DevOps Server 2019 and later versions. For downloads, see [Downloads](https://visualstudio.microsoft.com/downloads/). The mobile browser isn't an app but a mobile view of select features. There's nothing to download. Access the mobile browser by selecting a link from a work item in your mobile email application. ::: moniker-end +## Prerequisites - +| Category | Requirements | +|--------------|-------------| +| **Azure DevOps Server** | The mobile browser is available for Azure DevOps Server 2019 and later versions. | +| **Email notifications** | [Enable email notifications](../../organizations/notifications/manage-your-personal-notifications.md) for work item changes, @mentions, or other alerts. | +| **Mobile device** | Access the mobile work item form from a mobile device with an email application that can open links. | ## Open the mobile work item form -The mobile work item form will open when you click **View work item** from an email you receive from your mobile device. You'll receive this type of email under these circumstances: +The mobile work item form opens when you select **View work item** from an email on your mobile device. You receive this type of email when the following actions occur: -- Changes were made to a work item you're following -- You were @mentioned in a discussion -- A notification is sent based on the work item alerts you've set using [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md). - -Email received in your mobile client +- Changes get made to a work item you're following. +- You're **@mentioned** in a discussion. +- A notification email gets sent based on your work item alerts set using [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md). +:::image type="content" source="media/mobile-work-email-notice.png" alt-text="Screenshot of Azure DevOps email notification of email received in mobile client."::: ## Update a work item -Within the mobile form, you can do almost everything you can do from the [web portal form](../../boards/backlogs/add-work-items.md). Here are the actions you can take in the order they appear in the mobile form: - -* Add and remove tags -* View and add to the discussion, click on the comment to add to the discussion -* View and update any field within the form (Assign to, State, Area, Iteration, Description, and more) -* View and open a link within the Development section -* View History -* View and open a link from the Links tab -* Open and add an attachment from the Attachments tab +Within the mobile form, you can perform almost all actions available in the [web portal form](../../boards/backlogs/add-work-items.md). Here are the actions you can take in the order they appear in the mobile form: -Actions not available to you within the mobile work item form: -* You can't create or add new work items -* You can't initiate a development operation -* You can't add a link +- Add and remove tags +- View and add to the discussion by selecting a comment +- View and update any field within the form (Assign to, State, Area, Iteration, Description, and more) +- View and open a link within the Development section +- View History +- View and open a link from the Links tab +- Open and add an attachment from the Attachments tab +Actions not available in the mobile work item form: +- You can't create or add new work items +- You can't initiate a development operation +- You can't add a link ### Interact with mobile form controls -Mobile form controls operate as follows: +Mobile form controls operate as follows: -- Click any field to edit it and the form changes to a full-screen experience. For example, some of the most common actions such as changing the state of an item, moving to a different area path, adding an attachment, and creating/removing tags are all supported. -- When done, click the ![return icon](media/mobile-work-return.png) return option. -- Remember to click the ![save icon](../../boards/media/icons/icon-save-wi.png) save icon to save your changes! +- Select any field to edit it, and the form changes to a full-screen experience. Common actions include: + - Change the state of an item: To update the work item status, select the desired state from the dropdown menu. + - Move to a different area path: Choose a new area path to reassign the work item within the project. + - Add an attachment: Upload files to the work item to provide more context or resources. + - Create or remove tags: Enter the text you want in the tag field and press **Enter** to add a tag. To remove a tag, select the "x" next to the tag name. +- Select the ![save icon](../../boards/media/icons/icon-save-wi.png) save icon to save your changes. This action ensures all updates are recorded and reflected in the work item. ### Update status (change State) -To update the state, click the state you want. - -Mobile work item form, Change State action +To update the state, select the desired state from the dropdown menu. This action changes the work item's status, helping to track its progress. After making your selection, ensure you save your changes by selecting the ![save icon](../../boards/media/icons/icon-save-wi.png) save icon. + +:::image type="content" source="media/mobile-work-change-state.png" alt-text="Screenshot of State change options via mobile browser."::: ### Add or remove tags -To add a tag, type the text you want. - -Mobile work item form, Add or remove tags +To add a tag, enter the desired text in the tag field and press **Enter**. The tag gets added to the work item. You can add multiple tags by repeating this process. Tags help categorize and filter work items for better organization and tracking. + +:::image type="content" source="media/mobile-work-add-tags.png" alt-text="Screenshot of mobile work item form, Add or remove tags."::: ### View history -Click the History tab to view history. +To view the work item's history, select the **History** tab. This action displays a chronological list of all changes made to the work item, including updates to fields, comments, and state transitions. -Mobile work item form, View history +:::image type="content" source="media/mobile-work-view-history.png" alt-text="Screenshot of mobile work item form, View history."::: ## View and open work items in your activity lists -From within the mobile work item form, you can access your work items. The mobile browser allows you to view and open work items which fall into these categories: -- **Assigned to me**: lists all work items assigned to you -- **Following**: lists all work items that you have elected to follow -- **My activity**: lists all work items that you have recently viewed or updated. +From within the mobile work item form, you can access your work items. The mobile browser allows you to view and open work items categorized as follows: +- **Assigned to me**: Lists all work items assigned to you. +- **Following**: Lists all work items that you're following. +- **My activity**: Lists all work items that you recently viewed or updated. -The lists available from each page span all team projects that you work in. +These lists span all team projects that you're involved in, providing a comprehensive view of your work items across projects. -To access a list, first click the list control from the work item form you've opened. +1. Select the list control from the work item form you opened. -![Click the list icon](media/mobile-work-click-list.png) + :::image type="content" source="media/mobile-work-click-list.png" alt-text="Screenshot of selected list icon."::: -Then, click **Work items**. +2. Select **Work items**. -![Click Work items](media/mobile-work-click-work-items.png) + :::image type="content" source="media/mobile-work-click-work-items.png" alt-text="Screenshot of selected work items."::: -The browser opens to the **Assigned to me** page. From there, you can choose **Following** or **My activity** to access the other pages. To learn more about the **Work Items** view, see [View and add work items](../../boards/work-items/view-add-work-items.md). +When you open the browser, it defaults to the **Assigned to me** page. From there, you can navigate to the **Following** or **My activity** pages to access other work items. For more information, see [View and add work items](../../boards/work-items/view-add-work-items.md). -![The browser opens to the Assigned to me page.](media/mobile-work-account-work-items-pages.png) +:::image type="content" source="media/mobile-work-account-work-items-pages.png" alt-text="Screenshot of the Assigned to me page in the browser."::: + +> [!TIP] +> From your mobile device, you can perform most functions in Azure Boards, Azure Repos, Azure Pipelines, Azure Test Plans, and Azure Artifacts, just as you would via the desktop browser. The following example shows mobile access to **Repos** > **Pull requests**. +> +>:::image type="content" source="../media/mobile-azure-devops-hubs.png" alt-text="Screenshot showing Azure DevOps hubs accessible via mobile browser."::: ## Related articles -Additional experiences are in the works to improve and expand on the mobile experience. For more information, see the blog post: [The mobile work item form (preview)](https://devblogs.microsoft.com/devops/the-mobile-work-item-form/). - +- [View blog post, The mobile work item form (preview)](https://devblogs.microsoft.com/devops/the-mobile-work-item-form/). - [Set personal notifications](../../organizations/notifications/manage-your-personal-notifications.md) - [Set team notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) - [Follow a work item](../../boards/work-items/follow-work-items.md) - ### Provide feedback for the mobile experience -Help us improve the mobile experience. +Help us improve the mobile experience. -To provide feedback, choose the list control from the work item form and then click **Send Feedback**. To complete the feedback, select either the smile or frown and optionally enter a comment. +To provide feedback, select the list control from the work item form and choose **Make a suggestion**. You can also select **Report a bug** or **Contact support** to provide other feedback or get assistance. -Mobile work item form, Send feedback \ No newline at end of file +:::image type="content" source="media/mobile-work-send-feedback.png" alt-text="Screenshot of the mobile work item form, Send feedback."::: diff --git a/docs/project/navigation/preview-features.md b/docs/project/navigation/preview-features.md index 989c48f345d..223daad9823 100644 --- a/docs/project/navigation/preview-features.md +++ b/docs/project/navigation/preview-features.md @@ -1,115 +1,72 @@ --- title: Manage preview features -titleSuffix: Azure DevOps Services -description: Enable/disable or activate/deactivate features in preview at the user or organization level +titleSuffix: Azure DevOps +description: Learn how to enable preview features in Azure DevOps and get early access to new functionalities and improvements. Preview features are easy to turn on or off. ms.custom: navigation, cross-project, cross-service, engagement-fy23 ms.subservice: azure-devops-projects ms.assetid: FB4E044D-B916-4901-A322-C87C3581A90A ms.author: chcomley author: chcomley +ai-usage: ai-assisted ms.topic: how-to -monikerRange: '>= azure-devops-2020' -ms.date: 06/22/2023 +monikerRange: '<= azure-devops' +ms.date: 01/27/2025 --- -# Manage or enable features +# Manage preview features -[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-lt-eq-azure-devops.md)] ::: moniker range="azure-devops" -As new features are introduced, you can turn them on or off. That way, you can try them out, provide feedback, and work with the ones that meet your requirements. - -Some preview features provide access to entire new functionality. Others, such as the New Wiki experience, reflect a change to the user interface, but little or no change in functionality. +As some new features get introduced, you can turn them on or off. You can try them out, provide feedback, and work with the ones that meet your requirements. Some preview features provide access to new functionality, while others reflect a change to the user interface, but little or no change in functionality. > [!NOTE] -> It may take up to three weeks after a release to Azure DevOps Services for the preview feature to appear in your organization. The [latest release notes](/azure/devops/release-notes/features-timeline) usually provide information on new preview features. You can turn on or off select features for Azure DevOps Services. Preview features become available first on Azure DevOps Services and then become standard features with an update to Azure DevOps Server. At some point, the preview feature moves out of preview status and becomes a regular feature of the web portal. +> It might take up to three weeks after a release to Azure DevOps for the preview feature to appear in your organization. The [latest release notes](/azure/devops/release-notes/features-timeline) usually provide information on new preview features. You can turn on or off select features for Azure DevOps. Preview features become available first on Azure DevOps Services and then become standard features with an update to Azure DevOps Server. At some point, the preview feature moves out of preview status and becomes a regular feature of the web portal. ::: moniker-end -::: moniker range="azure-devops-2020" +::: moniker range="< azure-devops" -There are a few features you or an administrator can enable or disable. Some features provide access to entire new functionality, while others provide a change to the user interface. -::: moniker-end - -::: moniker range="azure-devops" - -The following table indicates which preview features can be enabled per user or team member, and which can be enabled for the organization. You must be a member of the Project Collection Administrators group to change a preview feature at the organization-level. - - -|**Preview features**|**Per user**|**Per organization**| -|--------------------|--------------|-----------------| -|[Pull Request Summary - Load of large files](#pull-request-summary) | ✔️ | | -|[Analytics views](../../report/powerbi/what-are-analytics-views.md)| ✔️ | ✔️ | -|Dependency Tracker Preview Features (ignore this setting) | ✔️ | ✔️ | -|[Experimental themes](#experimental-themes) | ✔️ | ✔️ | -|[Limit user visibility and collaboration to specific projects](../../user-guide/manage-organization-collection.md#project-scoped-user-group) | | ✔️ | -|New Artifacts (Feeds) Experience (accessibility updates) | ✔️ | ✔️ | -|[New Boards Hubs](/azure/devops/release-notes/2022/sprint-202-update#new-boards-hubs-now-available-in-public-preview) | ✔️ | ✔️ | -|[New release progress views](/azure/devops/release-notes/2018/may-30-vsts#visualize-release-progress)| ✔️ | ✔️ | -|[New service connections experience](../../pipelines/library/service-endpoints.md)| ✔️ | ✔️ | -|[New Settings Search in the organization settings panel](../../organizations/settings/search-settings.md)| ✔️ | ✔️ | -|[New Teams page](../../organizations/settings/add-teams.md)| ✔️ | ✔️ | -|New Wiki experience| ✔️ | ✔️ | -|[Organization Permissions Settings Page v2](../../organizations/security/change-organization-collection-level-permissions.md)| ✔️ | ✔️ | -|[Project Permissions Settings page](../../organizations/security/change-project-level-permissions.md)| ✔️ | ✔️ | -|[Task Insights for Failed Pipeline Runs](../../pipelines/troubleshooting/troubleshooting.md#task-insights-for-failed-pipeline-runs)| ✔️ | ✔️ | -|[YAML templates editor](../../pipelines/get-started/yaml-pipeline-editor.md#view-and-edit-templates)| ✔️ | ✔️ | +As some new features get introduced, you can turn them on or off. You can try them out, provide feedback, and work with the ones that meet your requirements. Some preview features provide access to new functionality, while others reflect a change to the user interface, but little or no change in functionality. ::: moniker-end +## Prerequisites -::: moniker range="azure-devops-2020" -The following table indicates those features that you can enable as a user, project administrator, or project collection administrator. These preview features are only available to manage for Azure DevOps Server 2020 RTW. +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of the [project](../../organizations/projects/create-project.md) where you want to enable or disable preview features. | +| **Permissions** | To enable or disable preview features for your organization: Member of the **Project Administrators** group. | +| **Access levels** |At least **Basic** access. | -|**Feature**|**User**|**Project** | **Collection**| -|--------------------|--------------|-----------------||-----------------| -|[New service connections experience](../../pipelines/library/service-endpoints.md)| ✔️ | | ✔️ | -|[Selective artifacts download feature for collection/project](../../pipelines/process/phases.md#artifact-download)| | ✔️ | ✔️ | +## Turn on or off preview features -::: moniker-end - ::: moniker range="azure-devops" - - -## Enable features for your use - -From time to time, a new feature is introduced in Preview mode, which allows you to turn it on or off. - -To enable or disable a feature, slide the toggle to the **on** or **off** position. +Select either your organization or personal settings from the dropdown menu and slide the toggle to **on** or **off** to change the feature status. -:::image type="content" source="media/preview-features/preview-features-user.png" alt-text="Screenshot of Preview features options for yourself."::: +:::image type="content" source="media/preview-features/manage-preview-features.png" alt-text="Screenshot of Preview features options and dropdown menu for either personal or organizational settings."::: -For more information, see [Set user preferences](../../organizations/settings/set-your-preferences.md). - - - -## Enable features at the organization level - -When you enable a feature at the organization level, you essentially turn it on for all users of your account. Each user can then disable the feature if they so choose. If you disable a feature at the organization level, user settings aren't changed. Users can enable or disable the feature on their own. +Enabling a feature at the organization level activates it for all users. They can still turn it off individually. Disabling a feature at the organization level doesn’t affect user settings. Users can change feature status on their own. For more information, see [Set user preferences](../../organizations/settings/set-your-preferences.md). > [!TIP] > If you don't see the **for this account** menu option, then you aren't a member of the Project Collection Administrators group. To get added as one, see [Change project collection-level permissions](../../organizations/security/change-organization-collection-level-permissions.md). -:::image type="content" source="media/preview-features/organization-preview-features.png" alt-text="Screenshot of preview features at organization level."::: - ::: moniker-end -::: moniker range="azure-devops-2020" - -## Enable or disable a feature +::: moniker range="< azure-devops" 1. Open your profile menu by choosing your image icon and select **Manage features**. :::image type="content" source="media/manage-features/open-profile-2020.png" alt-text="Screenshot of Open profile menu, Azure DevOps Server 2020."::: -1. Select the level from the menu provided. +2. Select the level from the menu provided. > [!TIP] > If you don't see the **for this project** or **for this collection** menu options, then you aren't an administrator. To get added as one, see [Change project collection-level permissions](../../organizations/security/change-organization-collection-level-permissions.md). -1. To enable or disable a feature, choose the slider. +3. To turn on or off a feature, choose the slider. **User-level** :::image type="content" source="media/manage-features/manage-features-user-2020.png" alt-text="Screenshot of Manage features for the user."::: @@ -120,33 +77,76 @@ When you enable a feature at the organization level, you essentially turn it on **Collection-level** :::image type="content" source="media/manage-features/manage-features-collection-2020.png" alt-text="Screenshot of Manage features for the collection."::: -When you enable a feature at the project or collection-level, you essentially turn it on for all users. If you disable a feature at the project or collection-level, user settings aren't changed. Users can enable or disable the feature on their own. +When you turn on a feature at the project or collection-level, you turn it on for all users. If you turn off a feature at the project or collection-level, user settings aren't changed. Users can change feature status on their own. ::: moniker-end +## Preview features + ::: moniker range="azure-devops" - +The following table lists the preview features that you can turn on or off based on your role: user, team member, or organization. Only Project Collection Administrators can manage organization-level features. -## Pull Request Summary - Load of large files +|**Preview features**|**Per user**|**Per organization**| +|--------------------|--------------|-----------------| +|[Pull Request Summary - Load of large files](#pull-request-summary---load-of-large-files) | ✔️ | | +|Microsoft Entra profile information | ✔️ | | +|[Experimental themes](#experimental-themes) | ✔️ | ✔️ | +|[Limit user visibility and collaboration to specific projects](../../user-guide/manage-organization-collection.md#project-scoped-user-group)| | ✔️ | +|New Artifacts (Feeds) Experience (accessibility updates) | ✔️ | ✔️ | +|[New Boards Hubs](../../boards/work-items/quick-ref.md) | ✔️ | ✔️ | +|[New service connections experience](../../pipelines/library/service-endpoints.md)| ✔️ | ✔️ | +| New Settings Search in the organization settings panel| ✔️ |✔️ | +|[New workflow identity authentication option](../../pipelines/library/connect-to-azure.md)| ✔️ | ✔️ | +|[New Teams page](../../organizations/settings/add-teams.md)| ✔️ | ✔️ | +|New Wiki experience| ✔️ | ✔️ | +|[Organization Permissions Settings Page v2](../../organizations/security/change-organization-collection-level-permissions.md)| ✔️ | ✔️ | +|[Project Permissions Settings page](../../organizations/security/change-project-level-permissions.md)| ✔️ | ✔️ | +|[Task Insights for Failed Pipeline Runs](../../pipelines/troubleshooting/troubleshooting.md#task-insights-for-failed-pipeline-runs)| ✔️ | ✔️ | +|[YAML templates editor](../../pipelines/get-started/yaml-pipeline-editor.md#view-and-edit-templates)| ✔️ | ✔️ | -Enables a file content load experience for large files in the Pull request summary. +::: moniker-end - +::: moniker range="azure-devops-2020" + +The following table shows the features you can turn on or off based on your role: user, project administrator, or project collection administrator. + +|**Feature**|**User**|**Project** | **Collection**| +|--------------------|--------------|-----------------||-----------------| +|[New service connections experience](../../pipelines/library/service-endpoints.md)| ✔️ | | ✔️ | +|[Selective artifacts download feature for collection/project](../../pipelines/process/phases.md#artifact-download)| | ✔️ | ✔️ | + +::: moniker-end + +::: moniker range="azure-devops-2022" + +You can turn on or off the [Pull Request Summary - Load of large files](#pull-request-summary---load-of-large-files) feature on a per-user basis. + +::: moniker-end + +::: moniker range=">= azure-devops-2022" + +## Pull request summary - Load of large files + +Turns on a file content load experience for large files in the Pull request summary. + +::: moniker-end + +::: moniker range="azure-devops" ## Experimental themes -When you select Theme from the Profile menu, you can select between **Dark** and **Light** themes for the display of Azure DevOps web portal. +When you select **Theme** from the Profile menu, you can select between **Dark** and **Light** themes for the display of Azure DevOps web portal. :::image type="content" source="media/preview-features/menu-theme.png" alt-text="Screenshot of Profile menu, Theme selected."::: -With **Experimental themes** enabled, you can select from many other themes. +With **Experimental themes** on, you can select from many other themes. :::image type="content" source="media/preview-features/choose-your-theme.png" alt-text="Screenshot of Choose your theme dialog."::: -## Features now enabled for all Azure DevOps Services +## GA features for Azure DevOps -The following features are now enabled for all Azure DevOps Services. +The following features are generally available for Azure DevOps. ### General @@ -154,11 +154,11 @@ The following features are now enabled for all Azure DevOps Services. - [New PAT experience](/azure/devops/release-notes/2018/sprint-140-update#manage-your-personal-access-tokens-with-filtering-and-paging) - [New Navigation](https://devblogs.microsoft.com/devops/new-navigation/) - [Wiki](../wiki/add-edit-wiki.md) -- [Combine email recipients](../../organizations/notifications/manage-team-group-global-organization-notifications.md) +- [Combine email recipients](../../organizations/notifications/manage-team-group-global-organization-notifications.md) - [New experience in Code, Work Item, & Wiki search](/previous-versions/azure/devops/2017/oct-06-vsts#code) - [Out of the box notifications](../../organizations/notifications/manage-your-personal-notifications.md) - [Team expansion for notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) -- [Streamlined User Management](../../organizations/accounts/add-organization-users.md) +- [Streamlined user management](../../organizations/accounts/add-organization-users.md) ### Azure Artifacts @@ -169,11 +169,11 @@ The following features are now enabled for all Azure DevOps Services. - [Copy Dashboard Experience](../../report/dashboards/copy-dashboard.md) - [New Delivery Plans Experience](../../boards/plans/review-team-plans.md) - [Enable group by tags for work item chart widget on dashboard](../../boards/queries/add-tags-to-work-items.md#group-by-tags) -- [New Rich Text Editor](../../boards/queries/share-plans.md#rich-text) - [New Queries Experience](../../boards/queries/view-run-query.md) - [New Work Items](../../boards/work-items/view-add-work-items.md) - [New Dashboards Experience](../../report/dashboards/dashboards.md) -- [New boards reports](../../report/dashboards/overview.md#in-context-reports-work-tracking) +- [New boards reports](../../report/dashboards/overview.md#in-context-reports-work-tracking) +- [Analytics views](../../report/powerbi/what-are-analytics-views.md) ### Azure Repos @@ -184,7 +184,6 @@ The following features are now enabled for all Azure DevOps Services. - [New Repos landing pages](/azure/devops/release-notes/2019/sprint-159-update#new-web-ui-for-azure-repos-landing-pages-preview) - [Pull Request Status Policy](../../repos/git/pr-status-policy.md) - ### Azure Pipelines - [Historical graph for agent pools](../../pipelines/agents/pool-consumption-report.md) @@ -198,7 +197,7 @@ The following features are now enabled for all Azure DevOps Services. - [Approval gates in releases](../../pipelines/release/approvals/index.md) - [New Release Definition Editor](../../pipelines/release/define-multistage-release-process.md) - [Symbol server](../../pipelines/artifacts/symbols.md) - [Task tool installers](../../pipelines/process/tasks.md#tool-installers) - +- [Workload Identity federation for Azure Resource Manager service connections](../../pipelines/library/connect-to-azure.md) ### Azure Test Plans @@ -207,7 +206,13 @@ The following features are now enabled for all Azure DevOps Services. ::: moniker-end +## Transition of Preview Features to General Availability + +While there's no fixed timeline for when a preview feature moves to general availability (GA), there are several indicators and resources you can use to stay informed about the status of preview features: + +- **Azure DevOps roadmap and release notes:** The Azure DevOps roadmap provides insights into upcoming features and enhancements. It includes information about features currently in preview and their expected release timelines. Azure DevOps release notes provide detailed information about new features, improvements, and bug fixes. For more information, see the Relevant Links section at [Azure DevOps Blog](https://devblogs.microsoft.com/devops/). +- **Azure DevOps blog:** The Azure DevOps blog often features posts about new releases, including when preview features transition to GA. Subscribing to the blog or regularly checking it can help you stay updated. For more information, see [Azure DevOps Blog](https://devblogs.microsoft.com/devops/). + ## Related articles - [Set user preferences](../../organizations/settings/set-your-preferences.md) -- [Azure DevOps Feature Timeline](/azure/devops/release-notes/features-timeline) diff --git a/docs/project/navigation/set-favorites.md b/docs/project/navigation/set-favorites.md index bdf75acc8dc..c894855b8be 100644 --- a/docs/project/navigation/set-favorites.md +++ b/docs/project/navigation/set-favorites.md @@ -9,115 +9,53 @@ ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 03/21/2019 +ms.date: 01/27/2025 --- -# Tutorial: Set personal or team favorites +# Set personal or team favorites [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Favorite ![start icon](../../media/icons/icon-favorite-star.png) those views that you frequently access. You can favorite all sorts of Azure DevOps features and tools—such as a project, repository, build pipeline, dashboard, backlog, board, or query. You can set favorites for yourself or your team. +As your code base, work tracking, developer operations, and organization grow, quickly navigating to important views becomes essential, which setting favorites helps with. -As your code base, work tracking efforts, developer operations, and organization grows, you'll want to be able to quickly navigate to those view of interest to you and your team. Setting favorites allows you to do just that. +Favorite ![star icon](../../media/icons/icon-favorite-star.png) the views you frequently access. You can favorite various Azure DevOps features and tools, such as projects, repositories, build pipelines, dashboards, backlogs, boards, or queries. Favorites can be set for yourself or your team. -Team favorites are a quick way for members of your team to quickly access shared resources of interest. You favorite an item for yourself by choosing the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon. The favorited item will then show up easily from one or more directory lists. You set favorites for a team through the context menu for the definition, view, or artifact. - -In this tutorial you'll learn how to view your personal favorites and to favorite or unfavorite the following views:  - -::: moniker range=">= azure-devops-2019" - ->[!div class="checklist"] -> - Project or team -> - Dashboard -> - Team backlog, board, shared query, or other Azure Boards view -> - Repository -> - Build and release definition -> - Test plans - -::: moniker-end - -::: moniker range="tfs-2018" - ->[!div class="checklist"] -> - Project -> - Shared query -> - Repository -> - Build and release definition -> - Test plans - -::: moniker-end +Team favorites allow members to quickly access shared resources. Favorite an item for yourself by selecting the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon. The favorite item appears in one or more directory lists. Set team favorites through the context menu for the definition, view, or artifact. ## Prerequisites -::: moniker range="azure-devops" - -* You must connect to a project through the web portal. If you don't have a project yet, [create one](../../boards/get-started/sign-up-invite-teammates.md). To connect to the web portal, see [Connect to a project](../../organizations/projects/connect-to-projects.md). -* You must be a member of the **Contributors** or an administrators security group of the project. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To favorite projects, backlogs, boards, queries, dashboards, or pipeline views, you must have **Stakeholder** access or higher. -* To favorite repositories, or delivery plans, you must have **Basic** access or higher. -* To favorite test plans, you must have **Basic + Test Plans** access level or equivalent. - -::: moniker-end - -::: moniker range="<= azure-devops-2019" - -* You must connect to a project through the web portal. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). To connect to the web portal, see [Connect to a project](../../organizations/projects/connect-to-projects.md). -* You must be a member of the **Contributors** or an administrators security group of the project. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -* To favorite projects, backlogs, boards, queries, dashboards, or pipeline views, you must have **Stakeholder** access or higher. -* To favorite repositories, or delivery plans, you must have **Basic** access or higher. -* To favorite test plans, you must have **Basic + Test Plans** access level or equivalent. - -::: moniker-end - -For details about the different access levels, see [About access levels](../../organizations/security/access-levels.md). +| Category | Requirements | +|--------------|-------------| +| **Permissions** | Member of the **Contributors** group or an administrative security group for the project. | +| **Access levels** | - To favorite projects, backlogs, boards, queries, dashboards, or pipeline views: At least **Stakeholder** access.
      - To favorite repositories or delivery plans: At least **Basic** access.
      - To favorite test plans: **Basic + Test Plans** or equivalent. | +For more information, see [About access levels](../../organizations/security/access-levels.md). ## View personal favorites -::: moniker range=">= azure-devops-2019" - -Access views that you have favorited by choosing the :::image type="icon" source="../../media/icons/inbox.png" border="false"::: inbox icon, and then choosing **Favorites**. +Access your personal favorites by choosing the :::image type="icon" source="../../media/icons/inbox.png" border="false"::: inbox icon, and then choosing **Favorites**. > [!div class="mx-imgBorder"] -> ![View your favorited items](media/favorites/open-favorites-page-vnav.png) +> ![Screenshot show view of your favorite items.](media/favorites/open-favorites-page-vnav.png) > [!NOTE] > If a service is disabled, then you can't favorite an artifact or view of that service. For example, if **Boards** is disabled, then the favorite groups—Plans, Boards, Backlogs, Analytics views, Sprints, and Queries and all Analytics widgets—are disabled. To re-enable a service, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -::: moniker-end - -::: moniker range="tfs-2018" - -1. Access views that you have favorited by choosing the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. - - > [!div class="mx-imgBorder"] - > ![Open Projects page](../../media/settings/open-project-hub-horz.png) - -2. Choose **My Favorites** to quickly access any view or item that you've marked as a favorite. - - > [!div class="mx-imgBorder"] - > ![Projects page, Favorites page](media/favorites/project-page-favorites-horz.png) - -::: moniker-end - - -::: moniker range=">= azure-devops-2019" - - + ## Favorite a project or team 1. To favorite a project, open the project **Summary** page and choose the ![favorites](../../media/icons/icon-favorite-star.png) star icon. > [!div class="mx-imgBorder"] - > ![web portal, Azure DevOps logo](media/favorites/favorite-project-vert.png) + > ![Screenshot shows web portal, Azure DevOps logo.](media/favorites/favorite-project-vert.png) -2. To favorite a team artifact, open Boards>Boards or Boards>Backlogs. Select the team you want to favorite from the team selector and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon. +2. To favorite a team artifact, open **Boards** > **Boards** or **Boards**> **Backlogs**. Select the team you want to favorite from the team selector and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon. > [!div class="mx-imgBorder"] - > ![Work>Boards, set team favorite](media/favorites/set-team-favorite-vert.png) + > ![Screenshot shows Work>Boards, set team favorite option.](media/favorites/set-team-favorite-vert.png) 3. To favorite other team artifacts, choose the :::image type="icon" source="../../media/icons/team.png" border="false"::: team icon, and then choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to one of the listed artifacts. @@ -126,32 +64,17 @@ Access views that you have favorited by choosing the :::image type="icon" source ::: moniker-end -::: moniker range="tfs-2018" - -## Favorite a project - -To favorite a project, open the project **Summary** page and choose the ![favorites](../../media/icons/icon-favorite-star.png) star icon. - -> [!div class="mx-imgBorder"] -> ![web portal, Azure DevOps logo](media/favorites/favorite-project-horz-brn.png) - -Or, you can favorite a project from the **Projects** page by choosing the ![favorites](../../media/icons/icon-favorite-star.png) star icon next to the project. - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - ## Favorite a dashboard -1. From **Overview>Dashboards**, open the selector and choose the **Browse all dashboards** option. +1. From **Overview** > **Dashboards**, open the selector and choose the **Browse all dashboards** option. > [!div class="mx-imgBorder"] - > ![Dashboards, Browse all dashboards option](../../report/dashboards/media/dashboards/browse-all-dashboards.png) + > ![Screenshot shows Dashboards, Browse all dashboards option.](../../report/dashboards/media/dashboards/browse-all-dashboards.png) -2. The **Mine** page shows your favorited dashboards, and all dashboards of teams that you belong to. The **All** page (shown below) lists all dashboards defined for the project in alphabetical order. You can filter the list by team or by keyword. +2. The **Mine** page shows your favorite dashboards, and all dashboards of teams that you belong to. The **All** page lists all dashboards defined for the project in alphabetical order. You can filter the list by team or by keyword. > [!div class="mx-imgBorder"] - > ![The All page lists all dashboards.](../../report/dashboards/media/dashboards/all-dashboards-list.png) + > ![Screenshot shows the All page lists all dashboards.](../../report/dashboards/media/dashboards/all-dashboards-list.png) > [!TIP] > You can change the sort order of the list by choosing the column label. @@ -159,120 +82,64 @@ Or, you can favorite a project from the **Projects** page by choosing the ![favo 3. To favorite a dashboard, hover over the dashboard and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon. > [!div class="mx-imgBorder"] - > ![Favorite a dashboard.](../../report/dashboards/media/dashboards/favorite-dashboard.png) + > ![Screenshot shows favorite dashboard.](../../report/dashboards/media/dashboards/favorite-dashboard.png) - Favoriting a dashboard will cause it to appear on your **Favorites** page and towards the top in the **Dashboards** selection menu. - -::: moniker-end + Favoriting a dashboard causes it to appear on your **Favorites** page and towards the top in the **Dashboards** selection menu. +## Favorite a team's backlog, board, or other view -::: moniker range=">= azure-devops-2019" +You can favorite several Agile tools for a team from a **Boards** page. -## Favorite a team's backlog, Kanban board, or other view - -You can favorite several Agile tools for a team from a **Boards** page. 1. Choose **Boards**, and then choose the page of interest, such as **Boards**, **Backlogs**, or **Sprints**. For example, here we choose (1) **Work** and then (2) **Backlogs**. > [!div class="mx-imgBorder"] - > ![Open Work, Backlogs](media/favorites/open-work-backlogs-vert.png) + > ![Screenshot shows Open Work, Backlogs selections.](media/favorites/open-work-backlogs-vert.png) To choose a specific team backlog, open the selector and select a different team or choose the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all team backlogs** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. > [!div class="mx-imgBorder"] - > ![Choose another team](../../boards/sprints/media/assign-items-sprint/team-selector-backlogs-agile.png) - -2. Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to favorite a team backlog. Favorited artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorited icon) appear on your **Favorites** page and towards the top of the team backlog selector menu. - -::: moniker-end + > ![Screenshot shows Choose another team selection.](../../boards/sprints/media/assign-items-sprint/team-selector-backlogs-agile.png) +2. Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to favorite a team backlog. Favorite artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorite icon) appear on your **Favorites** page and towards the top of the team backlog selector menu. ## Favorite a shared query -::: moniker range=">= azure-devops-2019" - -Open **Boards>Queries** and choose the **All** page. Expand a folder as needed. Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to the query you want to favorite. +Open **Boards** > **Queries** and choose the **All** page. Expand a folder as needed. Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to the query you want to favorite. Or, open the context menu of the query, and then select **Add to Team Favorites**, and then select from the list of teams. > [!NOTE] -> You must be a member of at least one team for the **Add to Team Favorites** option to be visible. If not visible, ask your project administrator or team administrator to add you to a team. +> Be a member of at least one team for the **Add to Team Favorites** option to be visible. If not visible, ask your project administrator or team administrator to add you to a team. > [!div class="mx-imgBorder"] -> ![Work>Queries, Add to favorites](media/favorites/favorite-query.png) +> ![Screenshot shows Work>Queries, Add to favorites selection.](media/favorites/favorite-query.png) You can also set a query as a personal favorite by opening the query and choosing the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon. > [!div class="mx-imgBorder"] -> ![Work>Queries, set shared query as a personal favorite](media/favorites/set-query-favorite-personal.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -Open **Work>Queries**. Next, open the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon menu of the shared query you want to favorite, and then select **Add to my favorites** or **Add to team favorites**. - -![Web portal, Work, Queries, Add to my favorites](media/set-favorites-shared-query.png) - -::: moniker-end - +> ![Screenshot shows Work>Queries, set shared query as a personal favorite selection.](media/favorites/set-query-favorite-personal.png) ## Favorite a delivery plan To learn more about delivery plans, see [Review team Delivery Plans](../../boards/plans/review-team-plans.md). -::: moniker range=">= azure-devops-2019" - -To mark a delivery plan as a favorite, open the **Boards>Plans** page and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to the Delivery Plan. -::: moniker-end - -::: moniker range="tfs-2018" - -To mark a delivery plan as a favorite, open the **Work>Plans** page and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to the Delivery Plan. - -::: moniker-end - +To mark a delivery plan as a favorite, open the **Boards** > **Plans** page and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to the Delivery Plan. ## Favorite a repository -::: moniker range=">= azure-devops-2019" - From any **Repos** page, open the repository selector and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon for the repository you want to favorite. > [!div class="mx-imgBorder"] -> ![Code page, Repository selector, choose favorites icon](media/favorites/favorite-repo-vert.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -From any **Code** page, open the repository selector and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to the repository you want to favorite. - -> [!div class="mx-imgBorder"] -> ![Web portal, Code, Favorite a repo](media/set-favorites-repository.png) - -::: moniker-end - +> ![Screenshot shows Code page, Repository selector, choose favorites icon.](media/favorites/favorite-repo-vert.png) ## Favorite a build pipeline -::: moniker range=">= azure-devops-2019" - -Open **Pipelines>Builds** and choose either **Mine** or **Definitions** page. Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to the build definition you want to favorite. Or, open the context menu of the build definition, and then select **Add to my favorites** or **Add to team favorites**. +Open **Pipelines** > **Builds** and choose either **Mine** or **Definitions**. Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to the build definition you want to favorite. Or, open the context menu of the build definition, and then select **Add to my favorites** or **Add to team favorites**. > [!div class="mx-imgBorder"] -> ![Pipelines, Builds, Add to my favorites or team favorites](media/favorites/set-build-favorites-vert.png) - -::: moniker-end - - -::: moniker range="tfs-2018" - -Open **Build and Release>Builds** and choose either **Mine** or **Definitions** page. Choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to the build definition you want to favorite. Or, open the context menu of the build definition, and then select **Add to my favorites** or **Add to team favorites**. - -> [!div class="mx-imgBorder"] -> ![Build & Release, Builds, Add to my favorites or team favorites, previous navigation](media/favorites/set-favorites-build-definitions.png) +> ![Screenshot shows Pipelines, Builds, Add to my favorites or team favorites.](media/favorites/set-build-favorites-vert.png) ::: moniker-end @@ -280,92 +147,24 @@ Open **Build and Release>Builds** and choose either **Mine** or **Definitions** To learn more about test plans, see [Create a test plan and test suite](../../test/create-a-test-plan.md). -::: moniker range=">= azure-devops-2019" - -To mark a test plan as a favorite, open **Test Plans>Test Plans** and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to a test plan from the menu that shows All test plans. - -::: moniker-end - -::: moniker range="tfs-2018" - -To mark a test plan as a favorite, open the **Test>Test Plans** page and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to a test plan from the menu that shows All test plans. - -::: moniker-end - +To mark a test plan as a favorite, open **Test Plans** > **Test Plans** and choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to a test plan from the menu that shows All test plans. -## Unfavorite a view you've favorited -::: moniker range=">= azure-devops-2019" +## Unfavorite a view -You can unfavorite an artifact from your **Favorites** page. Choose the :::image type="icon" source="../../media/icons/inbox.png" border="false"::: inbox icon, and then choose **Favorites**. Choose the :::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorited icon of a currently favorited artifact. +You can unfavorite an artifact from your **Favorites** page. Choose the :::image type="icon" source="../../media/icons/inbox.png" border="false"::: inbox icon, and then choose **Favorites**. Choose the :::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorite icon of a favorite artifact. > [!div class="mx-imgBorder"] -> ![View your favorited items](media/favorites/open-favorites-page-vnav.png) - -Similarly, you can unfavorite an artifact from the same page where you favorited it. - -::: moniker-end - -::: moniker range="tfs-2018" - -You can unfavorite an artifact from the **Projects>Favorites** page and choose the :::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorited icon of a currently favorited artifact. - -Similarly, you can unfavorite an artifact from the same page where you favorited it. - -::: moniker-end +> ![Screenshot shows view of your favorite items.](media/favorites/open-favorites-page-vnav.png) +Similarly, you can unfavorite an artifact from the same page where you marked it as a favorite. - -## Try this next +## Next steps > [!div class="nextstepaction"] > [Follow a user story, bug, issue, or other work item or pull request](../../boards/work-items/follow-work-items.md) ## Related articles - [Manage personal notifications](../../organizations/notifications/manage-your-personal-notifications.md) -- [Set your preferences](../../organizations/settings/set-your-preferences.md) - - - - - - +- [Set your preferences](../../organizations/settings/set-your-preferences.md) diff --git a/docs/project/navigation/toc.yml b/docs/project/navigation/toc.yml index b7fda6c2728..32ab7eb3a48 100644 --- a/docs/project/navigation/toc.yml +++ b/docs/project/navigation/toc.yml @@ -4,8 +4,6 @@ href: go-to-service-page.md - name: Add an artifact or team artifacts href: add-artifact-team.md -- name: Use breadcrumbs, selectors, and directories - href: use-breadcrumbs-selectors.md - name: Open another project or repo href: go-to-project-repo.md - name: Work with favorites diff --git a/docs/project/navigation/use-breadcrumbs-selectors.md b/docs/project/navigation/use-breadcrumbs-selectors.md deleted file mode 100644 index d338280efa6..00000000000 --- a/docs/project/navigation/use-breadcrumbs-selectors.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: Use breadcrumbs and selectors -titleSuffix: Azure DevOps -description: Navigate to pages and artifacts using breadcrumbs or selectors in the web portal for Azure DevOps -ms.custom: "navigation, cross-project, cross-service" -ms.subservice: azure-devops-projects -ms.topic: how-to -ms.author: chcomley -author: chcomley -monikerRange: '<= azure-devops' -ms.date: 07/30/2020 ---- - - - -# Use breadcrumbs, selectors, and directories to navigate and open artifacts - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -To quickly navigate to a feature or artifact—such as a dashboard, repository, product backlog, Kanban board, build pipeline—you can use breadcrumbs, selectors, and directories. - -## Organization and project breadcrumbs - -::: moniker range=">= azure-devops-2019" - -To navigate to the project summary page, choose the project link within the breadcrumbs. To navigate to the organization page with all projects defined for the organization, choose the organization link. - -![Top level breadcrumbs](media/breadcrumbs/top-level-breadcrumbs.png) - -::: moniker-end - - -::: moniker range="tfs-2018" - -Horizontal navigation doesn't provide a breadcrumb structure for the organization and project levels. Instead, you can select a recent team or project from the project/team selector. - - ![Choose a different team or project from the project/team selector](../../media/work-web-portal-ts-switch-team-focus.png) - -Choosing **Browse all** [opens the **projects** page](work-across-projects.md). - -::: moniker-end - -## Selectors - -::: moniker range=">= azure-devops-2019" -Selectors are used to select an artifact within the current page. Most Agile tools are defined for a team and therefore require selection of the team artifact or tool. -::: moniker-end - -::: moniker range="tfs-2018" -Selectors are used to select an artifact within the current page. Most Agile tools are defined for a team and therefore require selection of the team as well as the specific page. -::: moniker-end - -> [!NOTE] -> When you navigate to a specific page or artifact, the system remembers your selection. You use selectors to choose a different artifact within the current page. - -### Example: Dashboard selector - -::: moniker range=">= azure-devops-2019" - -Within **Dashboards**, you open a specific dashboard from the selector. - -> [!div class="mx-imgBorder"] -> ![Dashboards, dashboard selector](media/breadcrumbs/dashboard-selector.png) - -This particular selector features these navigational elements: - -- Search box for filtering dashboards based on a team name or keyword -- Two pages you can choose from: - - **Mine** (dashboards you created) which are organized by team - - **All** (dashboards created by everyone) which are listed alphabetically -- Dashboards you've favorited will appear at the top of the selector -- **Add new dashboard** feature -- **Browse all dashboards** - opens **Dashboards>All** - -::: moniker-end - - -::: moniker range="tfs-2018" - -Within **Dashboards**, you select the team whose dashboards you want to view. - -![Choose a different team or project from the project/team selector](../../media/work-web-portal-ts-switch-team-focus.png) - -Then, choose the name of the dashboard to view it. - -For example, here we open the *Work in Progress* dashboard. - -> [!div class="mx-imgBorder"] -> ![Dashboards, Choose a team dashboard](../../report/dashboards/media/dashboards/choose-dashboard.png) - -::: moniker-end - - -### Example: Backlogs - - -::: moniker range=">= azure-devops-2019" - -From the **Boards>Backlogs** page, you use the selector to switch to another team's backlog. Again, favorited backlogs appear towards the top of the menu. You can also filter the list based on a team name or keyword. - -> [!div class="mx-imgBorder"] -> ![Work>Backlogs, backlogs selector](media/breadcrumbs/backlog-selector.png) - -Or, choose **Browse all team backlogs** to open the **Backlogs>All** page. - -::: moniker-end - - -::: moniker range="tfs-2018" - -(1) Select the team from the project/team selector, choose (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - -> [!div class="mx-imgBorder"] -> ![Open the Work>Backlogs page, standard pages](../../boards/sprints/media/assign-items-sprint/open-work-backlogs-standard.png) - -To choose another team, open the project/team selector and select a different team or choose the **Browse** option. - -> [!div class="mx-imgBorder"] -> ![Choose another team](../../boards/sprints/media/assign-items-sprint/team-selector-backlogs-standard.png) - -::: moniker-end - -## Artifact breadcrumbs and selectors - -Within select pages, breadcrumbs are provided to support navigating within the page or opening an artifact. - -::: moniker range=">= azure-devops-2019" - -### Example: Queries folders and breadcrumbs -For example, when working in the **Queries** pages, you can navigate to a subfolder, folder, or page. - -![Queries breadcrumbs](media/breadcrumbs/queries-breadcrumbs.png) - -Also, you can choose a query that you've favorited from the selector menu, Or, you can choose to browse all queries which returns you to the **All Queries** page. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Queries, Query selector.](media/breadcrumbs/query-bd-and-selector.png) - -::: moniker-end - -### Example: Pipeline folders and breadcrumbs - -Breadcrumb-and-selector navigation elements are used within most services that support defining and organizing artifacts within folders. This includes **Pipelines** or **Build and Release** applications pages. - -::: moniker range=">= azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Screenshot of Build Definitions, Query selector.](media/breadcrumbs/build-bc-selector.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -Choose the **Deployment** breadcrumb link to return to the *Deployment* folder. - -> [!div class="mx-imgBorder"] -> ![Build and Release, Build definition](media/breadcrumbs/build-bc-folder.png) - -::: moniker-end - - -::: moniker range=">= azure-devops-2019" - -## Directories - -Directories provide a filterable list of all artifacts defined for a service area. Often when you navigate to an application, it will open the application's directory. - -For example, here is the **Boards>Boards** directory. - -> [!div class="mx-imgBorder"] -> ![Boards directory](media/breadcrumbs/boards-directory.png) - -It lists boards in the following order: -- Your last visited board -- Your favorited boards -- All boards of teams that you belong to -- All boards defined for the project in alphabetical order. - -Choose the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: filter icon to filter the list as described in [Filter basics](filter-basics.md). - -From a specific page, you can open the directory from the breadcrumbs or a selector. For example, choose **Browse all boards** from the Boards selector. - -:::row::: - :::column span="2"::: - **Open from breadcrumb** - :::column-end::: - :::column span=""::: - **Open from selector** - :::column-end::: -:::row-end::: -:::row::: - :::column span="2"::: - :::image type="content" source="media/breadcrumbs/open-directory-boards.png" alt-text="Open Boards directory from selector"::: - :::column-end::: - :::column span=""::: - :::image type="content" source="media/breadcrumbs/open-directory-boards-from-breadcrumbs.png" alt-text="Open Boards directory from breadcrumb"::: - :::column-end::: -:::row-end::: - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -## Team profiles - -- Open a team profile to quickly access items defined for a team. The team profile is available from the **Overview>Dashboards**, **Boards>Boards**, **Boards>Backlogs**, and **Boards>Sprints** pages. - - > [!div class="mx-imgBorder"] - > ![Open team profile](media/breadcrumbs/open-team-profile.png) - - A panel opens that shows all items defined for the team. - - > [!div class="mx-imgBorder"] - > ![Team profile all items](media/breadcrumbs/team-profile-all-items.png) - -- You can filter the list to show only **Dashboards**, **Boards**, **Backlogs**, or **Sprints** by choosing from the menu. - - > [!div class="mx-imgBorder"] - > ![Filter team tools](media/breadcrumbs/filter-team-profile.png) - -- To view the team admins and members of the team, choose **Members**. - - > [!div class="mx-imgBorder"] - > ![Team members](media/breadcrumbs/team-profile-members.png) - -- To view or change the team configuration, choose **Team Settings**. - You can then add [team members](../../organizations/security/add-users-team-project.md#add-team-members), [team admins](../../organizations/settings/add-team-administrator.md), or navigate to [team notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md), or team [iterations](../../organizations/settings/set-iteration-paths-sprints.md#open-team-settings) and [area paths](../../organizations/settings/set-area-paths.md#open-team-settings). - -See also [Manage and configure team tools](../../organizations/settings/manage-teams.md). - -::: moniker-end - -## Related articles - -- [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md ) -- [Add an artifact or team](add-artifact-team.md) -- [Set favorites](set-favorites.md) -- [Open a service or page](go-to-service-page.md) -- [Filter basics](filter-basics.md) \ No newline at end of file diff --git a/docs/project/navigation/work-across-projects.md b/docs/project/navigation/work-across-projects.md index af90bb5c105..36dd0d58e3e 100644 --- a/docs/project/navigation/work-across-projects.md +++ b/docs/project/navigation/work-across-projects.md @@ -5,11 +5,11 @@ description: How to access work items, pull requests, team projects, and more us ms.custom: navigation, cross-project ms.subservice: azure-devops-projects ms.assetid: B4406575-4D4D-42E3-88FD-93830546B67F -ms.topic: quickstart +ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 01/27/2025 --- @@ -17,93 +17,46 @@ ms.date: 04/04/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -When you work on several projects, you can use select pages to support your cross-project work. These pages provide quick access and filter functions to support your work within a single project or work you're doing across several projects. +When you work on several projects, you can use specific pages to support your cross-project work. These pages provide quick access and filter functions to help you manage your tasks within a single project or across multiple projects. -For example, you can quickly access and navigate to the following artifacts defined across projects. +For more information, see [Switch project, repository, or team](go-to-project-repo.md) or [Work across projects FAQs](../work-across-projects-faqs.yml). -::: moniker range=">= azure-devops-2019" -- **Projects**: Projects defined for an organization in Azure DevOps -- **Work items**: Work items assigned to you -- **Pull requests**: Pull requests you've initiated or that are relevant to you across all team projects you work in -- **Favorites**: Artifacts—such as projects, teams, repositories, shared queries, and more —that you've favorited +For example, you can quickly access and navigate to the following artifacts defined across projects: -::: moniker-end - - -::: moniker range="tfs-2018" -- **Projects**: Team projects and teams within the projects that you work in -- **Favorites**: Items—such as build definitions, repositories, shared queries, and more —that you've favorited -- **Work items**: Work items assigned to you, that you're following, or that you've recently viewed or updated -- **Pull requests**: Pull requests you've initiated or that are relevant to you across all team projects you work in - -::: moniker-end - -> [!NOTE] -> This feature only retrieves artifacts defined in projects for a single collection or organization. Retrieval of artifacts in projects across organizations isn't supported. - -To switch to another project, see [Switch project, repository, or team](go-to-project-repo.md). - -For additional notes on working across projects, see [Work across projects FAQs](../work-across-projects-faqs.yml). +- **Projects**: View all projects defined for an organization in Azure DevOps. +- **Work items**: Access work items assigned to you. +- **Pull requests**: See pull requests you initiated or that are relevant to you across all team projects you work in. +- **Favorites**: Access artifacts—such as projects, teams, repositories, shared queries, and more—that you marked as favorite. ## Prerequisites -* You must be added to a project as a member of the **Contributors** or administrator security group. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). +[!INCLUDE [prerequisites-contributor-only](../../includes/prerequisites-contributor-only.md)] ::: moniker range="azure-devops" > [!NOTE] -> Users added to the **Project-Scoped Users** group can only access those projects they've been explicitly added to. To learn more, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). - ::: moniker-end +> Users added to the **Project-Scoped Users** group can only access those projects they're explicitly added to. For more information, see [Manage your organization, Limit user visibility for projects and more](../../user-guide/manage-organization-collection.md#project-scoped-user-group). +::: moniker-end ## View and open work items -::: moniker range=">= azure-devops-2019" - To view work items assigned to you across projects, choose the :::image type="icon" source="../../media/icons/inbox.png" border="false"::: inbox icon, and then choosing **Work Items**. > [!div class="mx-imgBorder"] -> ![View work assigned to you across projects](media/projects-page/view-work-across-projects.png) - -To view work items assigned to you for a specific project, [open **Work>Work Items>Assigned to Me**](../../boards/work-items/view-add-work-items.md). - - -::: moniker-end - -::: moniker range="tfs-2018" - -Choose the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Open Projects page, TFS-2018 and TFS-2017 versions.](../../media/settings/open-project-hub-horz.png) - -::: moniker-end - -::: moniker range="tfs-2018" -Choose **Work items** to access the set of work items assigned to you or followed by you. The lists available from each page span all team projects that you work in. +> ![Screenshot show View of work assigned to you across projects.](media/projects-page/view-work-across-projects.png) -The **Assigned to me** page lists all work items assigned to you in the order they were last updated. To open or update a work item, choose its title. - -![Screenshot of Projects> Work, Assigned to me page, TFS-2018 and TFS-2017 versions.](media/org-hub-tfs/account-home-work-assigned-to-me.png) - -::: moniker-end +To view work items assigned to you for a specific project, [open **Boards>Work items>Assigned to me**](../../boards/work-items/view-add-work-items.md). ### Work you're following -Choose **Following** to open the page that lists all the work items [you've marked to follow](../../boards/work-items/follow-work-items.md). To stop following an item and remove it from your list, choose the ![followed icon](../../media/icons/icon-followed.png) following icon. +Choose **Following** to open the page that lists all the work items [you marked to follow](../../boards/work-items/follow-work-items.md). To stop following an item and remove it from your list, choose the ![followed icon](../../media/icons/icon-followed.png) following icon. -::: moniker range=">= azure-devops-2019" > [!div class="mx-imgBorder"] > ![Screenshot of Inbox > Work items pane > Following.](media/projects-page/account-home-work-following.png) ::: moniker-end -::: moniker range="tfs-2018" -![Screenshot of Projects > My work items > Following page. ](media/org-hub-tfs/account-home-work-followed.png) -::: moniker-end - - -::: moniker range=">= azure-devops-2019" ### My activity -Choose **My activity** to open the page that lists all work items that you have recently viewed or updated. +Choose **My activity** to open the page that lists all work items that you recently viewed or updated. > [!div class="mx-imgBorder"] > ![Screenshot of Inbox > Work items pane > My activity.](media/projects-page/account-work-my-activity.png) @@ -112,71 +65,24 @@ Choose **My activity** to open the page that lists all work items that you have ### Filter the list of work items -Similar to the Favorites page, you can filter the work pages by typing a keyword in the *Filter your work items...* box. The list will filter based on keyword matches to the work item ID, title, state, or team project name. +Similar to the Favorites page, you can filter the work pages by typing a keyword in the *Filter your work items...* box. The list filters based on keyword matches to the work item ID, title, state, or team project name. ## View and open pull requests -::: moniker range=">= azure-devops-2019" - To view pull requests you created or that are assigned to you across projects, choose the :::image type="icon" source="../../media/icons/inbox.png" border="false"::: inbox icon, and then choosing **Pull requests**. > [!div class="mx-imgBorder"] -> ![Screenshot of pull requests assigned to you across projects.](media/projects-page/view-pull-requests-vert.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -Open the **Projects>Pull requests** page to access any pull request that's relevant to you across all projects you work in. Choose **Active** or **Completed** to pivot between the active or completed set of pull requests. To initiate a pull request, choose **New pull request**. - -![Screenshot of pull requests assigned to you across projects, TFS-2017 and TFS-2018 versions.](media/org-hub-tfs/account-home-pull-requests.png) - -From each page, you're one choice away from navigating to the branch or repository for a pull request. This mirrors capabilities on the project **Code>Pull Requests** page. - -### Filter the list of pull requests - -Similar to the Favorites page, you can filter the list by typing a keyword in the *Filter pull requests* box. - -::: moniker-end - +> ![Screenshot of pull requests assigned to you across projects.](media/projects-page/view-pull-requests-vert.png) ## View and open favorites -You can view favorites you've set across projects. To learn more about working with favorites, see [Set personal or team favorites](set-favorites.md). - -::: moniker range=">= azure-devops-2019" +You can view favorites you set across projects. For more information about working with favorites, see [Set personal or team favorites](set-favorites.md). Choose the :::image type="icon" source="../../media/icons/inbox.png" border="false"::: inbox icon, and then choosing **Favorites**. > [!div class="mx-imgBorder"] > ![Screenshot of items you've favorited across projects.](media/favorites/open-favorites-page-vnav.png) -::: moniker-end - - -::: moniker range="tfs-2018" -Open the **Favorites** page to quickly access any object or item that you've marked as a favorite. - -> [!div class="mx-imgBorder"] -> ![Screenshot of items you've favorited across projects, TFS-2017 and TFS-2018 versions.](media/projects-page/account-home-favorites.png) - -To learn more about working with favorites, see [Set personal and team favorites](set-favorites.md). - -### Favorite and unfavorite an item - -To mark any item as a favorite, choose the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon next to the object. - -To remove an item from your favorites list, choose the favorited icon. - -![Favorite and unfavorite an item.](media/projects-page/account-home-remove-from-favorites.png) - -### Filter the list of favorites - -To filter the list, type a keyword in the *Filter favorites* box. The list will filter based on keyword matches to the title or team project name associated with the favorited item. - -::: moniker-end - - ## Related articles - [Work across projects FAQs](../work-across-projects-faqs.yml) diff --git a/docs/project/search/faq-search.yml b/docs/project/search/faq-search.yml deleted file mode 100644 index 823f577ff54..00000000000 --- a/docs/project/search/faq-search.yml +++ /dev/null @@ -1,114 +0,0 @@ -### YamlMime:FAQ -metadata: - title: FAQs search - description: Get answers to common questions about searching in Azure DevOps. - titleSuffix: Azure Boards - ms.custom: cross-service, cross-project - ms.technology: devops-collab - ms.author: chcomley - author: chcomley - ms.topic: faq - monikerRange: '<= azure-devops' - ms.date: 04/14/2021 - -title: Search FAQs - -summary: | - [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - - Learn the answers to frequently asked questions (FAQs) about the search function for Azure DevOps. - -sections: - - name: General - - questions: - - - question: Why isn't the wildcard search working as expected? - answer: | - You may see different results while doing a wildcard search for the term ```ge*``` as compared to a wildcard search for the term ```get*```. For example, in the image below you see ```ge*``` shows **7509** results. - ![Wildcard search for ge*](media/shared/faq-wildcard1.png) - ![Wildcard search for get*](media/shared/faq-wildcard2.png) - Let's say, you're searching for ```app*```. In the backend, the wildcard `*` expands to match any character sequence after the term ```app```. For example, ```app*``` might expand to ```app, app0, app01, .., apple```. The expansion takes place for the first 100 expanded terms only. Post expansion, all the files associated with the 100 expanded terms display on the search results page. There's a possibility that ```application``` may not be within the first 100 expanded terms so, you may not find files with the search term ```application``` in the search results. You may see fewer search results for the term ```ge*``` as compared to ```get*```. - Ensuring that you can find the most meaningful and actionable results as fast as possible, **enter more criteria in the search bar**. - - question: Is Azure DevOps Search extensible? - answer: | - Currently, no, but you can submit a new feature request in the [Developer Community](https://developercommunity.visualstudio.com/spaces/8/index.html). - - - name: Code search - - questions: - - - question: When I search file:span, why does it return files with an extension? - answer: | - You need to format functional commands as code. For instance, File:span searches fetch all files named span with the extension included. This behavior occurs because the most common scenario for users is to fetch the filename along with the extension. In case you don't want to see the extension, use the following search string: file:{filename} NOT file:{filename}. - - question: Why do I only get partial results when I search code? - answer: | - I see a **Showing partial code results** banner in code search. - ![Showing partial code results](media/shared/faq-partialresult.png) - Your code base might have one or more large repositories. The larger the repository, the higher number of documents that get searched. When you search large repositories, the request could take more time to process, which can cause the search request to fail. In this case, you may see partial search results along with the **Showing partial code results** banner, per the previous image. - You could try the following alternatives, as applicable to your scenario: - * Scope your query by using filters to narrow down to a "repo" or a "path". - * See if you can narrow your query to avoid scenarios that require matching too many terms. - For example, while looking for methods like App_App1, App_App2, and so on, instead of searching for ```a*``` try searching for ```app*``` instead. (```a*``` will match many more terms than ```app*```). - - question: How do I search code comments? - answer: | - Specify the History field. For example: History:Keyword. - - - name: Work item search - - questions: - - - question: Why does Code search display when I'm in Work Item view? - answer: | - You can toggle between Work Item and Code Search entities by using the picker next to the search box. - - name: Package search - - questions: - - - question: How do I search internal NuGet packages published company-wide? - answer: | - 1. Go to [Discover in Azure DevOps](https://aka.ms/discover). - 2. Enter your query and search. - 3. Choose the **Packages** pivot. - You can also navigate from your organization's landing page. - At the top left of your screen, there's a link to the Microsoft enterprise search page below the Azure DevOps logo. - - question: How do I search package comments? - answer: | - Specify the History field. For example: History:Keyword. - - - name: On-premises, Azure DevOps Server - - questions: - - - question: How do I get the search box to display? - answer: | - 1. The search box is shown only in the context of a project page. Go to a project and check if the search box is displayed at the top right. - 2. If you don't see the search box, verify that the extension is installed for the collection. If not, see [Install and configure Search](install-configure-search.md). - - question: Why are no search results shown after installing or configuring Search? - answer: | - 1. Wait until you're sure sufficient time has elapsed after installing or configuring Search. It typically takes less than one hour for Search to index a collection. But, it may take up to 12 hours based on the size and number of code files, work items, or wiki pages. - 2. If no results are shown after this period, [check the indexing status](manage-search.md#check-indexing-status). - - question: Why doesn't Search show the expected results? - answer: | - 1. If the files were added in the last few minutes, wait for about 10 minutes while they're indexed. - 2. [Check indexing status](manage-search.md#check-indexing-status) for the collection. - 3. If the files are still not shown in the results, [reindex the repository or collection](manage-search.md#reindex-a-repository-or-collection) where the files are located. - - question: How do I determine the status of indexing for a collection? - answer: | - [Check indexing status](manage-search.md#check-indexing-status) separately for each collection. - - question: How do I address adverse performance issues? - answer: | - 1. [Pause all indexing](manage-search.md#pause-indexing) and see if performance recovers. - 2. If performance does recover, consider locating Search on a separate server if you haven't already done so. - - question: How do I get Search to work after an upgrade? - answer: | - If Search is on a separate remote server and the source version is TFS 2018 Update 2 or higher, verify that the user followed [these upgrade steps](install-configure-search.md#upgrade-search). Run [this script](https://github.com/microsoft/Code-Search/blob/master/Azure_DevOps_Server_2019/Troubleshooting/Repair-Search.ps1) to fix the issue, if the upgrade steps weren't followed. - -additionalContent: | - ## Related articles - - [Search artifacts and packages](functional-package-search.md) - - [Search work items](functional-work-item-search.md) - - [Export access levels audit log](../../organizations/security/export-users-audit-log.md) - - *Have a question that didn't get answered? Feel free to ask it through one of the feedback links provided below.* - diff --git a/docs/project/search/functional-code-search.md b/docs/project/search/functional-code-search.md index 286ff313cb6..e29c5fa9bf0 100644 --- a/docs/project/search/functional-code-search.md +++ b/docs/project/search/functional-code-search.md @@ -1,59 +1,67 @@ --- -title: Functional code search options +title: Functional code search titleSuffix: Azure Repos -description: Options for code searching across all your projects in Azure DevOps. +description: Options for searching code across all your projects in Azure DevOps. ms.subservice: azure-devops-search ms.custom: cross-service, cross-project ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 09/08/2021 +ms.date: 01/27/2025 --- # Functional code search [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Functional code search extends your ability to refine your search across repositories beyond what's documented in [Get started with search](get-started-search.md). To do code searches, the [Code Search](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search) Marketplace extension must be installed for your organization or collection. +Find the code you need faster with functional code search. This article explains how to refine your search across repositories using code types and other functions with the [Code Search](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search) Marketplace extension for Azure DevOps. ## Prerequisites -- Install [Code Search](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search) -::: moniker range="< azure-devops" - For more information, see [Install and configure search](install-configure-search.md). +::: moniker range=" azure-devops" + +| Category | Prerequisite | +|--------------|-------------| +| **Access levels** | - To use code search: At least **Basic** access.
      - To access code in a private project: At least **Basic** access. Stakeholder access doesn't include code.
      - To access code in a public project: At least **Stakeholder** access. | +| **Search results** | **Access-based results**: When you're searching across the organization or collection, only results for which a project member has access are listed. | + ::: moniker-end -- To use Code Search, you must have at least Basic access. -- Users with Stakeholder access don't have access to code, so they can't search for code. -::: moniker range="azure-devops" -- Users with Stakeholder access for a public project have [full access to code](../../organizations/security/access-levels.md), so they can search for code. To access code in a private project, you must have at least Basic access. + +::: moniker range="< azure-devops" + +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - To use code search: At least **Basic** access.
      - To access code in a private project: At least **Basic** access. Stakeholder access doesn't include code. | +| **Search results** | **Access-based results**: When you're searching across the organization or collection, only results for which a project member has access are listed. | +| **Tools** | [Code Search extension](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search) | + ::: moniker-end -- When you're searching across the organization or collection, only results for which a project member has access are listed. ## Code search best practices -- Get the results you want even faster by starting with a higher-level search. You can narrow your search by using project, repository, path, file name, and other filter operators. -- When you're not sure of the exact term you're looking for, [Use wildcards to widen your search](get-started-search.md#search-features-usage-and-examples) and [Boolean operators to fine-tune it](get-started-search.md#search-features-usage-and-examples). -- Find more information about an item of interest faster and with minimal efforts. When you find an item of interest, place the cursor on it and use the shortcut menu to quickly search for that text across all your projects and files. -- Easily trace how your code works by using the shortcut menu to search for related items such as definitions and references – directly from inside a file or from the search results. -- Go quickly to the implementation of, for example, an API your code might be taking dependency on by narrowing down your results to exact code type matches. Use code type filters to search for specific kinds of code such as: -- definitions -- references -- functions -- comments -- strings -- namespaces, and more. +- **Start broad:** Begin with a broad search and then use filter operators to narrow it down by project, repository, path, file name, and more. +- **Use [wildcards](get-started-search.md#search-features-usage-and-examples) and [boolean operators](get-started-search.md#search-features-usage-and-examples):** If you don’t know the exact term, use wildcards to expand your search and boolean operators to refine it. +- **Hover for more info:** To get more information about a code item, hover over it and use the shortcut menu to search for that text in all your projects and files. +- **Trace code functionality:** Use the shortcut menu to search for related items like definitions and references in a file or in the search results to trace how your code works. +- **Use code type filters:** To find the implementation of an API or other code element, use code type filters to search for specific kinds of code such as: + - Definitions + - References + - Functions + - Comments + - Strings + - Namespaces, and more > [!NOTE] -> You can't search code in forked repositories. +> Code search doesn't work for forked repositories. ## Functions to find specific types of code -As you enter your search, select functions and keywords from the drop-down list to quickly create your query. Use the **Show more** link to display all the available functions and keywords. Mix and match the functions as required. +To create your query faster, choose functions and keywords from the drop-down list as you enter text. Select **Show more** to see all the options. You can combine different functions as needed. -You can also select one or a combination of filters from the list in the left column. Again, the **Show more** link displays all the available functions and keywords. +You can also use filters from the left column to narrow your search. **Show more** shows you all the functions and keywords. -Instead, you can enter the functions and parameters directly into the search. The following table shows a list of functions for selecting specific types or members in your C#, C, C++, Java, and Visual Basic.NET code. +Or, you can type the functions and parameters in the search box. The following table lists the functions for finding specific types or members in your C#, C, C++, Java, and Visual Basic.NET code. | To find code where _findThis_ appears as a ... | ... search for argument **arg:**_findThis_ | | --- | --- | @@ -97,21 +105,17 @@ Instead, you can enter the functions and parameters directly into the search. Th | Typedef | **typedef:**_findThis_ ```Merged with type:```| | Union | **union:**_findThis_ ```Deprecated in July 2019```| - - - - ## Functions to select projects, repositories, paths, and files -Functions make it easy to narrow the search to specified locations, specific types of files within these locations, or specified filenames. Narrow the search to a specific location using the `proj`, `repo`, or `path` filters. Mix and match the functions as required. - - +Functions make it easy to narrow the search to specified locations, specific types of files within these locations, or specified filenames. Narrow the search to a specific location using the `proj`, `repo`, or `path` filters. Mix and match the following functions as required. |**Usage** |**Example** | |---------|---------| |Find all occurrences of the word *QueueJobsNow* in the Fabrikam project. | `QueueJobsNow proj:Fabrikam` | |Find all occurrences of the word *QueueJobsNow* in the Contoso repository. | `QueueJobsNow repo:Contoso` | |Find all occurrences of the word *QueueJobsNow* in the path *VisualStudio/Services/Framework* and its subpaths. | `QueueJobsNow path:VisualStudio/Services/Framework` | +|Find all occurrences of the word *QueueJobsNow* in the path *\*/Doc\*/Framework/\** and *\*/Doc\*/\*/\*/Framework/\** and its subpaths. Globbing Pattern (\*\*) matches zero or more characters across multiple segments. For example, path:\*\*/Doc\*\*/Framework also matches abc/*Doc*Test/gh/ijk/mnop/*Framework*/ | `QueueJobsNow path:**/Doc**/Framework` | +|Find all occurrences of the word *QueueJobsNow* in the path *\*/Doc\*/Framework/\** and its subpaths and file name Test*.txt (Use Globbing Pattern \*\*). For example, path:\*\*/Doc\*\*/Framework/\*\*/Test\*.txt also matches abc/def/*Doc*A/gh/*Framework*/*Test*Misc.*txt* | `QueueJobsNow path:**/Doc**/Framework/**/Test*.txt` | |Enclose the argument to the filter in double-quotes if it contains a space. | `QueueJobsNow path:"VisualStudio/Windows Phones and Devices/Services"` | |Find all occurrences of the word *QueueJobsNow* in all files where the filename starts with *queueRegister*. | `QueueJobsNow file:queueRegister*` | |Find all files with the name *QueueRegister* without an extension. Use quotes to find files without extensions. | `file:"queueRegister"` | @@ -119,45 +123,42 @@ Functions make it easy to narrow the search to specified locations, specific typ ## Find related items or other terms -One of the powerful features of Code Search is the capability to expand your search interactively, based on the results of previous searches. For example, you can easily broaden your search to related files when tracing or debugging code. +Code Search lets you interactively expand your search based on previous results. For example, you can widen your search to related files when you're tracing or debugging code. -Place the insertion point on a term in the file and open the shortcut menu (mouse: right-click) to start a new search for other files containing the selected term. You can search for it as text, for the definition if you select an object name, or for references to a selected object. +Right-click on a term in the file and start a new search for other files with the same term. You can search for it as text, or as a definition or reference if it's an object name. -For more information about the following search functions, see [Get started with search](get-started-search.md#search-features-usage-and-examples). - -- Keyword -- Exact match -- Wildcard -- Boolean operators -- Proximity +For more information, see [Get started with search](get-started-search.md#search-features-usage-and-examples). ## More code search operations -See the following examples of even more code search functions. You can use the code type search functions with files written in C#, C, C++, Java, and Visual Basic.NET. Open the search results in a new browser tab from the main search box, and select **Ctrl** + **Enter**. In Google Chrome, select **Ctrl** + **Shift** + **Enter** to switch the focus to the new browser tab. +Here are some more code search functions. You can search for code types in C#, C, C++, Java, and Visual Basic.NET files. To open the search results in a new tab, select **Ctrl** + **Enter** from the main search box. To switch to the new tab in Google Chrome, select **Ctrl** + **Shift** + **Enter**. |**Usage** |**Example** | |---------|---------| -|Find all instances of "ToDo" comments in your code |Select `comment:` and enter `todo` | +|Find all comments | History:Keyword | +|Find all instances of "ToDo" comments in your code |Select `comment:` and enter `todo` | |Search in specific locations, such as within a particular path |Use a search string such as `Driver path:MyShuttle/Server` | |Search for files by name or just by file extension | `Driver file:GreenCabs.cs`. The search string `error ext:resx` could be useful if you want to review all error strings in your code. Even if your plain text search string matches part of a filename, the file appears in the list of found files. This search works without matching specific file type functions. | - ## Search Git projects and repositories -In a Git project, you see a list of the repositories that it contains. Use the project and repository checkboxes to widen your search. You can search more or all projects, or narrow your search to fewer projects and repositories. If there are more than a few projects or repositories, use the **Show more** link to see them all. +A Git project has a list of repositories. To expand your search, check the project and repository boxes. You can search all or more projects, or fewer projects and repositories. If there are many projects or repositories, select **Show more** to see them all. -Code Search can index multiple branches in a Git repository. By default it indexes files in only the default branch of your Git repositories. Your default branch is usually the **main** branch. Specify the branches for each repository, indexing in the **Options** tab of the **Repositories** section, [project settings page](../navigation/go-to-service-page.md#open-project-settings). +Code Search can index different branches in a Git repository. It only indexes files in the default branch of your Git repositories by default. The default branch is main. To index other branches, go to the **Options** tab in the **Repositories** section of the [project settings page](../navigation/go-to-service-page.md#open-project-settings). + +> [!NOTE] +> By default, code search looks for the specified string in the main or default branch of a repository. But, you can narrow down the search by specifying a filter for a specific branch. -::: moniker range=">= azure-devops-2019" -![Configure Git branches to include in search](media/advanced-work-item-search-syntax/configure-branches.png) +::: moniker range="<=azure-devops" +![Screenshot showing Git branches for configuration.](media/advanced-work-item-search-syntax/configure-branches.png) ::: moniker-end ## Search TFVC projects -In a TFVC project, you see a list of folder paths in that project for which you have read access - you won't see any projects and folders for which you don't have read permission. Select paths in the folder tree to narrow your search if necessary. +Team Foundation Version Control (TFVC) projects display only the folders that you can read. You can't see any other projects or folders. To filter your search, choose folders from the tree. > [!TIP] -> Code Search remembers your last settings, such as the project and repository or path that you searched in. Clear the checkboxes to search across all projects easily with the **Clear all** links when you want to search in a different scope. In the results pane, Code Search highlights up to the first 100 hits or matches found in the target files. +> Code Search saves your last settings, such as the project and repository or path that you searched in. When you want to search in a different scope, select **Clear all links** to clear the checkboxes and search across all projects. The first 100 hits or matches in the target files get highlighted by Code Search in the results pane. ## Search code with REST API @@ -173,4 +174,3 @@ You can use APIs to extend or supplement the capabilities listed in this article * [Get started with Search](get-started-search.md) * [Search artifacts and packages](functional-package-search.md) * [Search work items](functional-work-item-search.md) -* [Search FAQs](faq-search.yml) diff --git a/docs/project/search/functional-package-search.md b/docs/project/search/functional-package-search.md index 6500423a411..8990fc52284 100644 --- a/docs/project/search/functional-package-search.md +++ b/docs/project/search/functional-package-search.md @@ -8,37 +8,39 @@ ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 11/28/2022 +ms.date: 08/08/2024 --- # Search packages across your feeds [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Package Search is available to all users of Azure DevOps. For information on main search functions, see [Get started with search](get-started-search.md). +Finding the right package for your project can be challenging, especially when there are many versions and dependencies involved. In this article, learn how to use Code Search to perform functional package search in Azure DevOps, which allows you to search for packages based on their functionality, metadata, and code snippets. ## Prerequisites -- An Azure DevOps organization and a project. Create an [organization](../../organizations/accounts/create-organization.md) or a [project](../../organizations/projects/create-project.md#create-a-project) if you haven't already. +| Category | Requirements | +|--------------|-------------| +| **Azure DevOps organization and project** | An [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md#create-a-project). | +| **Azure Artifacts feed** | An [Azure Artifacts feed](../../artifacts/get-started-nuget.md#create-feed). | -- An Azure Artifacts feed. [Create a feed](../../artifacts/get-started-nuget.md#create-a-feed), if you don't have one already. +## Search packages -## Apply supported functions to package search +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). +2. Enter `package` in the search box. +3. Select from the dropdown menus to search by feeds, views, or package types. -1. Select the filter icon to show the filter panel. + :::image type="content" source="media/shared/package-search-results-filters.png" alt-text="Screenshot showing the filter panel options."::: - :::image type="content" source="media/shared/pkgsrch-results-filtericon.png" alt-text="Screenshot Showing the filter lists"::: +You can search within all feeds of the organization by default, regardless of the project you’re in. -1. Select from the dropdown menus to search by feeds, views, or package types. +The **Views** filter shows up only when you select a single feed from the **Feeds** filter. This filter lets you display packages from a particular view. - :::image type="content" source="media/shared/pkgsrch-results-filters.png" alt-text="Screenshot showing the filter panel options"::: +You can use the **Type** filter to choose the package type you want to search for (for example, NuGet packages). -By default, you search within all feeds of the organization, no matter which project you're in. The **Views** filter only appears if a single feed gets selected from the **Feeds** filter. Use this filter to show packages from a specific view. -Using the **Type** filter, you can select the type of package you want to search for (such as NuGet packages). +## Search with the REST API -## Search using the REST API - -You can use the Azure DevOps REST API to search for packages in a specific organization. See [Fetch Package Search Results](/rest/api/azure/devops/search/package-search-results/fetch-package-search-results) for more details. +You can use the Azure DevOps REST API to search for packages in a specific organization. For more information, see [Fetch package search results](/rest/api/azure/devops/search/package-search-results/fetch-package-search-results). #### Example @@ -58,23 +60,19 @@ POST https://almsearch.dev.azure.com/ORGANIZATION_NAME/_apis/search/packagesearc } ``` -## Search in upstream sources +## Search upstream sources -Using upstream sources, you can consume packages from public registries and Azure Artifacts feeds. See [Search upstreams](../../artifacts/how-to/search-upstream.md) to lean how to search for packages in upstream sources and save them to your feed. +Using upstream sources, you can consume packages from public registries and other Azure Artifacts feeds. For more information, see [Search upstream](../../artifacts/how-to/search-upstream.md). > [!NOTE] -> Searching for packages in upstreams using the NuGet Package Explorer is not supported. See [Download NuGet packages](../../artifacts/get-started-nuget.md#download-nuget-packages) for more details. +> You can only search for packages in upstream sources from your feed in Azure DevOps Services. NuGet Package Explorer doesn't support searching for upstream packages. For more information, see [Download NuGet packages](../../artifacts/get-started-nuget.md#download-packages). ## Next steps > [!div class="nextstepaction"] -> [What are feeds?](../../artifacts/concepts/feeds.md) -> [What are feed views?](../../artifacts/concepts/views.md) > [Promote a package to a view](../../artifacts//feeds/views.md) ## Related articles -- [Get started with Search](get-started-search.md) - [Search code](functional-code-search.md) - [Search work items](functional-work-item-search.md) -- [Search FAQs](faq-search.yml) diff --git a/docs/project/search/functional-work-item-search.md b/docs/project/search/functional-work-item-search.md index d44532ae629..2d86a83526c 100644 --- a/docs/project/search/functional-work-item-search.md +++ b/docs/project/search/functional-work-item-search.md @@ -4,10 +4,11 @@ description: How to use Work Item Search - functional options for Work Item Sear ms.assetid: B64E70C5-E5B2-49E6-BD05-FF5932F9894C ms.subservice: azure-devops-search ms.custom: cross-service, cross-project +ai-usage: ai-assisted ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 04/15/2021 +ms.date: 10/17/2024 monikerRange: '<= azure-devops' --- @@ -15,68 +16,56 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Functional work item search command filters extend your ability to refine your search of work items based on assignment, work item type, specific fields, and more. This is in addition to the filter functions documented in [Get started with search](get-started-search.md). Work item search is a built-in feature available to all Azure DevOps users. - -::: moniker range=" azure-devops" - -You can use Work Item Search by default without any installation when the Boards service is installed and enabled in Azure DevOps Services. - -::: moniker-end - -By using Work Item Search, you can do the following tasks and more. +Functional work item search command filters let you search for work items more precisely by assignment, work item type, specific fields, and more. For more filter functions, see [Get started with search](get-started-search.md). +Work Item Search lets you do the following tasks and more. |**Search task** |**Description** | |---------|---------| -|[Search over all your projects](#full-text-search-across-all-fields) | Search in your own and your partner teams' backlog. Use cross-project searches over all the work items to search across your enterprise's entire work items. Narrow your search by using project and area path filters. | -|[Search across all work item fields](#full-text-search-across-all-fields) | Quickly and easily find relevant work items by searching across all work item fields, including custom fields. Use a full text search across all fields to efficiently locate relevant work items. The snippet view indicates where matches were found. | +|[Search over all your projects](#search-across-all-fields) | Search in your own and your partner teams' backlog. To search across your entire enterprise's work items, use cross-project searches. Narrow your search by using project and area path filters. | +|[Search across all work item fields](#search-across-all-fields) | Quickly and easily find relevant work items by searching across all work item fields, including custom fields. Use a full text search across all fields to efficiently locate relevant work items. The snippet view indicates where matches were found. | |[Search in specific fields](#quick-filters-for-matching-in-specific-fields) | Use the quick in-line search filters to narrow down to a list of work items in seconds. Use the filters on any work item field. The list of suggestions helps complete your search faster. For example, a search such as **AssignedTo:Chris WorkItemType:Bug State:Active** finds all active bugs assigned to a user named Chris. | |Search across test |Search across Test Plans, Test Suites, and other test work item types. | |[Take advantage of integration with work item tracking](#search-by-work-item-id) | The Work Item Search interface integrates with familiar controls for managing your work items; letting you view, edit, comment, share, and more. | -## Prerequisites - -- All users can use work item search. -### Search by work item ID - -Enter the work item ID in the Azure DevOps title bar to quickly go to it. Searching for a work item ID opens the work item in a -modal dialog, providing quick access to read and edit work items. - -::: moniker range=">= azure-devops-2019" -![Opening the work item in a modal dialogue](media/advanced-work-item-search-syntax/open-work-item-modal-new.png) +## Prerequisites +- **Access levels:** + - **All project members:** Every project member can use the search functions, including users with Stakeholder, Basic, and higher levels of access. +::: moniker range=" azure-devops" +- Work Item Search is available by default when the Boards service is installed and enabled. ::: moniker-end -::: moniker range="tfs-2018" +### Search by work item ID -![Opening the work item in a modal dialogue](media/advanced-work-item-search-syntax/open-work-item-modal.png) +Enter the work item ID in the Azure DevOps title bar. You can read and edit the work item in a modal dialog. -::: moniker-end +![Screenshot of opening the work item in a modal dialogue.](media/advanced-work-item-search-syntax/open-work-item-modal-new.png) -## Full text search across all fields +## Search across all fields -You can easily search across all work item fields, including custom fields, which enables more natural searches. The snippet view indicates where matches were found. +Search all work item fields, including custom ones, for natural searches. The following snippet view shows matches. -Search across all work item fields +Screenshot of Searching across all work item fields. -- Use simple search strings for words or phrases. Work item search matches derived forms of your search terms; for example, a search for "updating" also finds instances of the word "updated" and "update". Searches aren't case-sensitive. -- When you search from inside a project, the default is to search only within that project. -- While searching from inside a team, the default is to search only within the default area path of that team. - - When you have one project selected, you see a list of area paths in that project for which you have read access - you won't see any projects and area paths for which you don't have read permission +- Use simple search strings for words or phrases. Work item search matches derived forms of your search terms; for example, a search for "updating" also finds instances of the word "updated" and "update." Searches aren't case-sensitive. +- Search from a project to, by default, search only within that project. +- Search from inside a team to, by default, search only within the default area path of that team. + - Select a project to view a list of area paths in that project for which you have Read access. - Select area paths in the tree to narrow your search if necessary. -- The selected projects are always at the top of the list. Notice that hit counts are also shown for projects that aren't selected. +- View hit counts for all projects, even one that you don't select. - Open the search results in a new browser tab from either the main search function or by selecting **Ctrl** + **Shift** + **Enter**. -## Work item search best practices +## Best practices -- Use a text search across all fields to efficiently locate relevant work items. Text search is useful when you're trying to, for example, search for all work items that had similar exception trace. -- Use the quick in-line search filters on any work item field to narrow down to a list of work items in seconds. The list of suggestions helps complete your search faster. +- **Text search across all fields:** Use a text search across all fields to efficiently locate relevant work items. This search is useful for finding work items with similar exception traces. +- **Quick in-line search filters:** Use quick in-line search filters on any work item field to narrow down the list of work items in seconds. The list of suggestions helps you complete your search faster. -## Search vs. managed work item queries +## Compare search vs. managed work item queries -You have two ways to find and list work items: managed queries and the main search function. If you're looking for a single work item, use the main search. If you want to generate a list of work items to triage, update, chart, or share with others, use a managed query. +The main search function and managed queries are two ways to find and list work items. For a single work item, use the main search. For a list of work items that you want to triage, update, chart, or share, use a managed query. -With the main search function, you can search against a more fully indexed set of fields than that of managed queries. +You can search more fields with the main search function than with managed queries. --- :::row::: @@ -106,31 +95,28 @@ With the main search function, you can search against a more fully indexed set o - Perform full text search across all work item fields. - Review work items assigned to a specific team member. - Search against specific work item fields to quickly narrow down a list of work items. - - Determine what key words will support a managed search. + - Determine what key words support a managed search. - List work items for a single project, multiple projects, or across all projects. :::column-end::: :::row-end::: --- -To get started, see the following articles: +For more information, see the following articles: - [View and run a query](../../boards/queries/view-run-query.md) - [Use search](../../boards/queries/search-box-queries.md) -- [Define a query](../../boards/queries/using-queries.md) - -For specific managed query examples, see [Query quick reference, Example queries](../../boards/queries/query-index-quick-ref.md). +- [Define a query](../../boards/queries/using-queries.md) +- [Query quick reference, Example queries](../../boards/queries/query-index-quick-ref.md) -## Apply supported functions to work item search - -::: moniker range=">= azure-devops-2019" +## Fine-tune your search -1. Fine-tune your search by specifying the fields to search. Enter `a:` and a user name to search for all items assigned to that user. +1. To fine-tune your search, specify fields. Search all assigned items by entering `a:` and a user name. :::image type="content" source="media/get-started/search-work-vert.png" alt-text="Search from title bar"::: - See the following quick filters that you can use: + Quick filters: * `a:` for **Assigned to:** * `c:` for **Created by:** @@ -141,71 +127,34 @@ For specific managed query examples, see [Query quick reference, Example queries :::image type="content" source="media/work-item-search-get-started/dyna-dropdown.png" alt-text="Quick filters as you enter the name of a field"::: - The dropdown list shows work item field name suggestions that match user input. These suggestions help you complete the search faster. For example, a search such as `tags:Critical` finds all work items tagged 'Critical'. + The dropdown list shows work item field name suggestions that match user input. These suggestions help you complete the search faster. For example, a search such as `tags:Critical` finds all work items tagged 'Critical.' 3. Add more filters to further narrow your search, and use Boolean operators to combine terms if necessary. For example, **a: Chris t: Bug s: Active** finds all active bugs assigned to a user named Chris. 4. Narrow your search to specific types and states, by using the selector lists at the top of the results page. 5. Widen your search across all projects, or narrow it to specific types and states. Use the filter to show the selector lists. - ![Showing the filter lists](media/shared/show-filters.png) + ![Screenshot showing the filter lists.](media/shared/show-filters.png) 6. Select the criteria you want in the drop-down selector lists, or search across the entire organization. - ![Selector drop-down lists](media/work-item-search-get-started/area-selectors.png) - -7. Sort the results as you need using the drop-down list of field names, work item types, or by relevance. - - ![Sort drop-down list](media/work-item-search-get-started/sort-order.png) - -::: moniker-end - -::: moniker range="tfs-2018" + ![Screenshot of selector drop-down lists.](media/work-item-search-get-started/area-selectors.png) -1. Fine-tune your search by specifying the fields to search. Enter `a:` and a user name to search for all items assigned to that user. - - :::image type="content" source="media/get-started/work-item-search-filters.png" alt-text="Search from the title bar"::: +7. Sort the results with the drop-down list of field names, work item types, or by relevance. - See the following quick filters that you can use: - - * `a:` for **Assigned to:** - * `c:` for **Created by:** - * `s:` for **State** - * `t:` for **Work item type**

      - -2. Start entering the name of a field in your work items; for example, enter `ta`. - - :::image type="content" source="media/work-item-search-get-started/dyna-dropdown.png" alt-text="Quick filters as you enter a field name"::: - - The dropdown list shows work item field name suggestions that match user input. These suggestions help you complete the search faster. For example, a search such as **tags:Critical** finds all work items tagged 'Critical'. - -3. Add more filters to further narrow your search, and use Boolean operators to combine terms if necessary. For example, **a: Chris t: Bug s: Active** finds all active bugs assigned to a user named Chris. - -4. Narrow your search to specific types and states, by using the drop-down selector lists at the top of the results page. -5. Widen your search across all projects, or narrow it to specific types and states. Use the filter to show the selector lists. - - ![Showing the filter lists](media/shared/show-filters.png) - -6. Select the criteria you want in the drop-down selector lists, or search across the entire organization. - - ![Selector drop-down lists](media/work-item-search-get-started/area-selectors.png) - -7. Sort the results as you need using the drop-down list of field names, work item types, or by relevance. - - ![Sort drop-down list](media/work-item-search-get-started/sort-order.png) - -::: moniker-end + ![Screenshot showing sort drop-down list.](media/work-item-search-get-started/sort-order.png) ### Quick filters for matching in specific fields Quick inline search filters let you refine work items in seconds. The dropdown list of suggestions helps complete your search faster. Mix and match the functions to create quick powerful searches. + |**Usage** |**Example** | |---------|---------| -| Scope your search terms to match in any work item field including custom fields. Enter the field name followed by the search terms. |`tags:Critical` finds work items having a field 'tags' containing the term 'Critical'. | -|Use multiple inline search filters to scope your search by any work item field, including custom fields. | `t: Bug path:"project\search"` finds all bugs in the area path "project\search". | -|Use the operators `>`, `>=`, `<`, `<=`, `=`, and `!=` for date, integer, and float fields. | `t: Bug CreatedDate> @Today-7` finds all bugs created in the last week. | -|For the search query that contains multiple terms and users looking for exact match, embed the search term inside `" "` | `BuildPath: "tools.demoproject.com"` finds all work items that necessarily contain the path "tools.demoproject.com". | +| Scope your search terms to match in any work item field, including custom fields. Enter the field name followed by the search terms. |`tags:Critical` finds work items with a 'tags' field containing the term 'Critical.' | +| Use multiple inline search filters to scope your search by any work item field, including custom fields. | `t: Bug path:"project\search"` finds all bugs in the area path "project\search." | +| Use the operators `>`, `>=`, `<`, `<=`, `=`, and `!=` for date, integer, and float fields. | `t: Bug CreatedDate> @Today-7` finds all bugs created in the last week. | +| For search queries containing multiple terms, use quotes to group the terms. However, quotes don't yield exact matches as you might expect; results match any work items containing the grouped terms in any order. | `BuildPath: "tools.demoproject.com"` finds work items that contain the path "tools.demoproject.com." | Quick inline search filters let you refine work items in seconds @@ -236,7 +185,7 @@ If you're using a portrait orientation screen, use the **Preview pane: Right** l > [!TIP] > Search remembers the state of the filter pane, configuration of the work item view pane, and its position between sessions as part of your user preferences. -## Search Work Items with REST API +## Search work items with REST API You can use APIs to extend or supplement the capabilities listed in this article. For information about Work Item Search with REST API, see [Fetch Work Item Search Results](/rest/api/azure/devops/search/work-item-search-results/fetch-work-item-search-results). @@ -250,4 +199,3 @@ You can use APIs to extend or supplement the capabilities listed in this article - [Get started with Search](get-started-search.md) - [Search code](functional-code-search.md) - [Search artifacts and packages](functional-package-search.md) -- [Search FAQs](faq-search.yml) diff --git a/docs/project/search/get-started-search.md b/docs/project/search/get-started-search.md index a79e1357e54..c78b2ec3e10 100644 --- a/docs/project/search/get-started-search.md +++ b/docs/project/search/get-started-search.md @@ -8,7 +8,7 @@ ms.custom: cross-service, cross-project ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 08/23/2021 +ms.date: 08/08/2024 monikerRange: '<= azure-devops' --- @@ -18,54 +18,45 @@ monikerRange: '<= azure-devops' You can quickly find work items, code files, wiki pages, or packages based on a keyword, wildcards, and other supported search filters with the search function. -Take an at-a-glance look at all of the [search features](#search-features-usage-and-examples) further in this article. +For more information, see the following links: + +- [Functional code search](functional-code-search.md) +- [Code Search extension](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search) +- [Functional work item search](functional-work-item-search.md) +- [Functional package search](functional-package-search.md) ## Prerequisites -- Every project member can use the search functions, including project members granted Stakeholder, Basic, and higher levels of access. -- When searching across the organization or collection, only results for which a project member has access are listed. -- Stakeholder wiki search results are limited to provisioned wikis. Because published wikis require access to regular repositories, which Stakeholders don't have access to, results for published wikis don't appear in the search results. Similarly, Code search results don't appear for Stakeholders. +- **Access levels:** + - **All project members:** Every project member can use the search functions, including users with Stakeholder, Basic, and higher levels of access. +- **Search results:** + - **Access-based results:** When you're searching across the organization or collection, only results for which a project member has access are listed. + - **Stakeholder limitations:** + - **Wiki search:** Stakeholder wiki search results are limited to provisioned wikis. Published wiki results don’t appear because they require access to regular repositories, which Stakeholders don’t have. + - **Code search:** Code search results don’t appear for Stakeholders. ::: moniker range="< azure-devops" - > [!IMPORTANT] -> For Code search, a Collection Administrator must [Install and configure search](install-configure-search.md). - -::: moniker-end - -## Start your search with a keyword - -Start your search using a keyword. You can then apply other options, as needed, to broaden or narrow your search results. - -::: moniker range=">= azure-devops-2019" - -:::image type="content" source="media/shared/title-bar-search-box-select-type-tfs.png" alt-text="Search boxes in Azure DevOps"::: - +> A Collection Administrator must [install and configure search](install-configure-search.md). ::: moniker-end -::: moniker range="tfs-2018" - -:::image type="content" source="media/shared/title-bar-search-box-select-type.png" alt-text="Search boxes in TFS 2018 and earlier"::: +## Search tips -::: moniker-end - -- If you get no results matching the input, try removing filters and retry the search. Broadening the search and after you view the search results, you can apply appropriate filters again and search again for relevant results. -- Check for the spelling of your search terms. Currently Work item search doesn't support ignoring of users' spelling mistakes. -- If there are lots of hits when you're using a wildcard search, such as when you're using a simple wildcard search string, you may see a message that no matching files are found. In this case, narrow your search to reduce the number of matches. Specify more characters of the word or words that you want to find, or add a condition or filter to limit the number of possible matches. -- Searches aren't case-sensitive. +- **Use keywords:** Start your search using a keyword. You can then apply other options, as needed, to broaden or narrow your search results. + :::image type="content" source="media/shared/title-bar-search-box-select-type-tfs.png" alt-text="Screenshot of search boxes in Azure DevOps"::: +- **Adjust filters:** If your initial search doesn’t yield the desired results, try removing filters and searching again. Once you see the search results, you can narrow them down by applying appropriate filters and searching again. +- **Check spelling:** Ensure your search terms are spelled correctly, as work item search doesn't ignore spelling errors. +- **Refine wildcard searches:** If you receive a message that no matching files are found due to a wildcard search with too many hits, make your search more specific. Add more characters of the word or words you want to find, or use a condition or filter to restrict the number of possible matches. +- **Case insensitivity:** Searches aren't case-sensitive. ## Search features, usage, and examples ::: moniker range="azure-devops" - The following features apply to all searches, including work items, code, wikis, and packages. - ::: moniker-end ::: moniker range="< azure-devops" - The following features apply to all searches, including work items, code, and packages. - ::: moniker-end --- @@ -101,7 +92,7 @@ The following features apply to all searches, including work items, code, and pa Search based on an exact match, enclosed in double-quotes. :::column-end::: :::column span="2"::: - `"Client not found"` finds instances that contain the exact phrase match *Client not found*. + `"Client not found"` finds instances that contain the exact phrase match *Client not found*. Search might not handle special characters as expected. Try escaping special characters or simplifying the search phrase. :::column-end::: :::row-end::: --- @@ -135,8 +126,8 @@ The following features apply to all searches, including work items, code, and pa :::column span="2"::: - `Validate AND revisit` finds files that contain both the words *validate* and *revisit*. - `Validate OR revisit` finds files that contain either of the words *validate* or *revisit*. - - `Validate NOT revisit` finds files that contain the word *validate* but not the word *revisit*. - - `(Validate NOT revisit) OR "release delayed"` finds files that contain the word *validate* but not the word *revisit* or files that contain the phrase *release delayed*. + - `Validate NOT revisit` finds files that contain the word *validate* but not the word, *revisit*. + - `(Validate NOT revisit) OR "release delayed"` finds files that contain the word *validate* but not the word, *revisit, or files that contain the phrase *release delayed*. :::column-end::: :::row-end::: --- @@ -170,7 +161,7 @@ The following features apply to all searches, including work items, code, and pa :::column-end::: :::column span="2"::: - `"flatten()"` finds the literal string *flatten()*. Search for a literal occurrence of the double-quote character *"* by preceding it with the escape character `\` and enclosing the search string in double-quotes. - - `"\"react-redux\""` finds the literal string "react-redux". + - `"\"react-redux\""` finds the literal string "react-redux." :::column-end::: :::row-end::: --- @@ -179,27 +170,23 @@ The following features apply to all searches, including work items, code, and pa You can search from any of the following pages: -- The Projects page for the organization: starts a search across all projects. -- The Project overview page: automatically applies a filter to search within the selected project. -- The Boards page for a project: automatically displays recent work items and backlogs accessed by the user. -- Azure Repos, Pipelines, Test Plans, or an Artifacts page for a project: automatically displays functional filters for code searches. -- The wiki page for a project: automatically go to a wiki page you recently opened. - -> [!TIP] -> Use the content type filter to access a page that you recently accessed. -> :::image type="content" source="media/get-started/search-page-filter.png" alt-text="Search page filter"::: +- Organization project page: Starts a search across all projects. +- Project overview page: Automatically applies a filter to search within the selected project. +- Boards page for a project: Automatically displays recent work items and backlogs accessed by the user. +- Azure Repos, Pipelines, Test Plans, or an Artifacts page for a project: Automatically displays functional filters for code searches. +- Wiki page: Automatically go to a wiki page you recently opened. -For more information about searching and filtering in Azure Boards, see [Filter backlogs, boards, and plans](../../boards/backlogs/filter-backlogs-boards-plans.md). - -For more information about searching wikis, see [Provisioned vs. published wiki](../wiki/provisioned-vs-published-wiki.md). +For more information, see the following articles: +- [Filter backlogs, boards, and plans](../../boards/backlogs/filter-backlogs-boards-plans.md) +- [Provisioned vs. published wiki](../wiki/provisioned-vs-published-wiki.md) > [!TIP] > **No results found for ...** -> If there's a large number of hits when using a wildcard search, such as when using a very simple wildcard search string, you may see a message that no matching files were found. In this case, narrow your search to reduce the number of matches. For example, specify more characters of the word(s) you want to find, or add a condition or filter to limit the number of possible matches. +> Too many hits from a simple wildcard search can result in no matching files. You can narrow your search by adding more characters or using a condition or filter. -## Additional search functions +## More search functions -To search for various settings, users, projects, and more, see the following table for other types of search tasks and corresponding actions. +See the following table for more search tasks and actions. --- :::row::: @@ -214,7 +201,7 @@ To search for various settings, users, projects, and more, see the following tab ::: moniker range="azure-devops" :::row::: :::column span="1"::: - [Find an organization setting](../../organizations/settings/search-settings.md) + Find an organization setting :::column-end::: :::column span="2"::: Go to your organization and select **Organization settings**. @@ -224,7 +211,7 @@ To search for various settings, users, projects, and more, see the following tab --- :::row::: :::column span="1"::: - [Find a project setting](../../organizations/settings/search-settings.md) + Find a project setting :::column-end::: :::column span="2"::: Go to your project and select **Project settings**. @@ -233,7 +220,7 @@ To search for various settings, users, projects, and more, see the following tab --- :::row::: :::column span="1"::: - [Find a user setting](../../organizations/settings/search-settings.md) + Find a user setting :::column-end::: :::column span="2"::: Go to your **User settings page**. @@ -284,30 +271,28 @@ To search for various settings, users, projects, and more, see the following tab ::: moniker range="< azure-devops" -## Search re-index requirements - -Search for Azure DevOps Server has the following limitation: +## Search reindex requirements -- If you do a disaster recovery (DR) operation and move your server back to an earlier snapshot of your SQL database, [re-index all your collections](manage-search.md#reindex-a-repository-or-collection). +Search has the following limitation: If you do a disaster recovery (DR) operation and move your server back to an earlier snapshot of your SQL database, [reindex all your collections](manage-search.md#reindex-a-repository-or-collection). ::: moniker-end ## Marketplace extensions -- [Code search](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search) - Extends search with fast, flexible, and precise search results across all your code. Required for searching repositories. +- [Code Search](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search) - Extends search with fast, flexible, and precise search results across all your code. Required for searching repositories. - [Azure Paths Search](https://marketplace.visualstudio.com/items?itemName=wavemotionio.ado-areapaths) - Adds a special search hub to Boards for searching within iterations and area paths without having to create and maintain custom queries. > [!NOTE] -> Some extensions aren't supported features of Azure DevOps and therefore aren't supported by the product team. For questions, suggestions, or issues you have when using these extensions, visit their corresponding extension page on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search). +> Azure DevOps doesn't support some extensions. For more information or assistance, go to the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search). ## Next steps > [!div class="nextstepaction"] -> [Functional work item search](functional-work-item-search.md) or -> [Functional code search](functional-code-search.md) or -> [Functional artifact or package search](functional-package-search.md) +> [Functional code search](functional-code-search.md) ## Related articles +- [Functional work item search](functional-work-item-search.md) +- [Functional artifact or package search](functional-package-search.md) - [Code search blog posts](https://devblogs.microsoft.com/search?query=Code+search&blog=%2Fdevops%2F) - [Work item search blog posts](https://devblogs.microsoft.com/search?query=Work+item+search) diff --git a/docs/project/search/install-configure-search.md b/docs/project/search/install-configure-search.md index eae34dd8fb0..c95132e8457 100644 --- a/docs/project/search/install-configure-search.md +++ b/docs/project/search/install-configure-search.md @@ -8,33 +8,29 @@ ms.subservice: azure-devops-search ms.topic: how-to ms.author: chcomley author: chcomley -monikerRange: '<= azure-devops' -ms.date: 02/14/2023 +monikerRange: '< azure-devops' +ms.date: 01/22/2025 --- # Install and configure Search -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-lt-azure-devops](../../includes/version-lt-azure-devops.md)] -Learn how to do the following actions for the Search extension for Code, Wiki, and Work item searches in Azure DevOps Server. -- [Configure Search](#configure-search) -- [Secure Search](#secure-search) -- [Upgrade Search](#upgrade-search) -- [Uninstall Search](#uninstall-search) - -For information about managing Search indexing, see [Manage Search and indexing](manage-search.md). +In this article, learn how to install, [configure](#configure-search), and [uninstall](#uninstall-search) a secure search engine for Azure DevOps Server that runs on your own hardware. For more information, see the following articles: +- [Manage Search and indexing](manage-search.md) +- [Software dependencies](#software-dependencies), further in this article ## Prerequisites -- To install the Search extension, you must be a Project Collection Administrator (PCA) for the organization. Non-administrative users can also request to have the extension added to their PCA. -- See [Install and configure Azure DevOps Server](/azure/devops/server/install/get-started) and [Requirements and compatibility](/azure/devops/server/requirements). +**Permissions:** Member of the **Project Collection Administrators** group for the organization. Non-administrative users can also request to have the extension added to their PCA. +For more information, see [Install and configure Azure DevOps Server](/azure/devops/server/install/get-started) and [Requirements and compatibility](/azure/devops/server/requirements). ### Hardware recommendations -You can use Search on any size physical server or virtual machine that runs Azure DevOps Server. You can configure it on the same server, or on a separate server dedicated to Search. When you're configuring Search on the same server, consider the existing CPU utilization factor because of Azure DevOps Server itself. +Search works on any physical server or virtual machine that runs Azure DevOps Server. You can set it up on the same server or a different one for Search. If you use the same server, consider the CPU usage. > [!TIP] -> For production environments, we recommend you configure Search on a separate server. +> We recommend that you configure Search on a separate server for production environments. For acceptable performance in multi-user scenarios, consider the following recommendations: @@ -51,109 +47,94 @@ For acceptable performance in multi-user scenarios, consider the following recom * More than 1,000 users with Search located on a [separate server](#install-or-update-search-on-a-separate-server): - Quad core processor, 16 GB (minimum) RAM - Fast hard drive backed by Solid State Drive (SSD) or Storage Area Network (SAN) storage -* Azure DevOps Server with Multiple ATs: +* Azure DevOps Server with Multiple application tiers (ATs): - Install Search on a [separate server](#install-or-update-search-on-a-separate-server) * Azure DevOps Server CPU utilization greater than 50% before Search installation: - Install Search on a [separate server](#install-or-update-search-on-a-separate-server) **Disk space requirement**: -The amount of disk space used by Search depends mainly on the type and size of files indexed. For Code search, since many times repositories can be large and have different code files in version control, disk space requirement could be significant. **Allocate up to 150% of the size of all the repositories to be indexed.** From TFS 2018 Update 3 and onward, users can exclude folders from their repositories for index to optimize the disk space that's consumed by search. +The amount of disk space used by Search depends mainly on the type and size of files indexed. For Code search, since many times repositories can be large and have different code files in version control, disk space requirement could be significant. **Allocate up to 150% of the size of all the repositories to be indexed.** From TFS 2018 Update 3 and onward, users can exclude folders from their repositories for index to optimize the disk space consumed by search. ### Software dependencies -Search has the following dependencies, which are installed automatically as part of the configuration: +Search has the following dependencies, which get installed automatically as part of the configuration: -* [Elasticsearch](https://www.elastic.co/products/elasticsearch) by Elasticsearch BV (see Notes 1 and 2) -* [Elasticsearch NEST client](https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/index.html) -* [Azul Zulu OpenJDK](https://www.azul.com/products/zulu-community/) (see [Java installation notes](#java-installation-notes)) -* [Markdowndeep](https://www.toptensoftware.com/markdowndeep/) by Topten Software -* [Roslyn](https://github.com/dotnet/roslyn) compiler platform -* [ANTLR](https://www.antlr.org/) language recognition parser +* [Elasticsearch](https://www.elastic.co/products/elasticsearch) by Elastic. + * Search uses a modified version of Elasticsearch. It works only with this modified version. + * A newer version of Elasticsearch ships with TFS 2018 Update 2 and onward, and Azure DevOps Server. All content is reindexed after installation when you upgrade from an older version of Search results. Depending on the volume of content (code files, work items, and wiki pages), reindexing can take some time to complete. +* [Elasticsearch NEST client](https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/index.html). +* [Microsoft Build of OpenJDK](/java/openjdk/download) Version 11. + * The Microsoft Build of OpenJDK doesn't automatically install updates. +* [Markdowndeep](https://www.toptensoftware.com/markdowndeep/) by Topten Software. +* [Roslyn](https://github.com/dotnet/roslyn) compiler platform. +* [ANTLR](https://www.antlr.org/) language recognition parser. > [!NOTE] -> - Search uses a modified version of Elasticsearch. It works only with this modified version -> - A newer version of Elasticsearch ships with TFS 2018 Update 2 and onward, and Azure DevOps Server. All content is reindexed after installation when you upgrade from an older version of Search results. Depending on the volume of content (code files, work items, and wiki pages), re-indexing can take some time to complete -> - The system or server administrator must ensure that Server JRE is maintained and updated in line with the software provider's recommendations. Also see the [Java installation notes](#java-installation-notes) that follow -> - The Azul Zulu OpenJDK doesn't automatically install updates -> - Ensure that you regularly [check for updates](https://www.azul.com/downloads/zulu-community/?&version=java-8-lts&os=windows&os-details=Windows&architecture=x86-64-bit&package=jdk) +> - The system or server administrator must ensure that Server JRE is maintained and updated in line with the software provider's recommendations. Also see the [Java installation notes](#java-installation-notes) that follow. +> - Regularly [check for updates](/java/openjdk/download). #### Java installation notes - If the Search configuration wizard doesn't detect a working installation of a Java Runtime Environment (JRE), it provides an option to download and install the latest supported version. Internet connectivity is required to download. If the target server doesn't have Internet connectivity, you must download and install a JRE manually before attempting to install Search. -- Versions of Search before Azure DevOps Server used the [Oracle Server Java Runtime Environment](https://www.oracle.com/technetwork/java/javase/downloads/server-jre8-downloads-2133154.html). In Azure DevOps Server, the default JRE is [Azul Zulu OpenJDK](https://www.azul.com/products/zulu-community/). +- Versions of Search before Azure DevOps Server used the [Oracle Server Java Runtime Environment](https://www.oracle.com/technetwork/java/javase/downloads/server-jre8-downloads-2133154.html). Azure DevOps Server uses Elasticsearch version 7.17.0, which has a bundled version of OpenJDK. - During installation, the wizard sets the **JAVA\_HOME** environment variable to point to the JRE installation folder. The configuration wizard might not detect an existing JRE installation if it wasn't correctly configured, or if the **JAVA\_HOME** setting points to an earlier version than required by Search. -> [!NOTE] -> We don't advise installing Elasticsearch on a machine where resources are shared, especially on a large enterprise environment with multiple application tiers. Instead, we recommend that you set up Elasticsearch in a separate dedicated machine. In that way, the JAVA environment isn't shared across machines for other purposes. - -- If there's a version of a JRE **earlier** than the minimum required by Search, and the **JAVA\_HOME** variable was set to that version, we recommend that you install Search on a [separate server](#install-or-update-search-on-a-separate-server). If you change the value of the **JAVA\_HOME** variable, it may cause other installed software to fail. - -- If there's a version of Server JRE **equal to or later** than the minimum required by Search and it's not recognized by the configuration wizard, set the value of the **JAVA\_HOME** variable to that version. This action's described in the JRE installation guide. Then, rerun the configuration wizard. - - [Zulu OpenJDK installation guide](https://docs.azul.com/zulu/zuludocs/index.htm) - - [Oracle JRE troubleshooting guide](https://docs.oracle.com/javase/7/docs/webnotes/tsg/) + > [!NOTE] + > We don't advise installing Elasticsearch on a machine where resources are shared, especially on a large enterprise environment with multiple application tiers. We recommend that you set up Elasticsearch in a separate dedicated machine. In that way, the JAVA environment isn't shared across machines for other purposes. +- If there's a version of a JRE **earlier** than the minimum required by Search, and the **JAVA\_HOME** variable was set to that version, we recommend that you install Search on a [separate server](#install-or-update-search-on-a-separate-server). +- If there's a version of Server JRE **equal to or later** than the minimum required by Search and not recognized by the configuration wizard, ensure **JAVA\_HOME** variable is NOT set. Then, rerun the configuration wizard (`& "C:\Program Files\Azure DevOps Server XXX\Search\ES\vX.XX\bin\elasticsearch-service.bat" manager`) and select the version by setting the path for the *Java Virtual Machine*. - If you can't install the version of Java required by Search because of other dependencies, you can do the following tasks: - - Install Azure DevOps Server with the Search extension on a server that doesn't have Java installed. We don't recommend this action for more than 250 users or CPU utilization greater than 50% or multiple ATs) - - Install Search and the JRE on a [separate server](#install-or-update-search-on-a-separate-server) from Azure DevOps Server - -> [!NOTE] -> If you're using Oracle Server JRE 8, which was the default for Search in TFS (Azure DevOps Server doesn't use Oracle Server JRE 8), be aware of the following information: -> * Search doesn't use or support any of the commercial features of Server JRE 8. Therefore, during Search configuration,the commercial features of the Server JRE are neither activated nor unlocked -> * If you choose to continue with Oracle JRE, contact Oracle for a [Java SE Subscription](https://www.oracle.com/java/java-se-subscription.html), so that you can continue to receive JRE updates - -#### Migrate to Zulu OpenJDK from Oracle Server JRE + - Install Azure DevOps Server with the Search extension on a server that doesn't have Java installed. We don't recommend this action for more than 250 users or CPU utilization greater than 50% or multiple ATs. + - Install Search and the JRE on a [separate server](#install-or-update-search-on-a-separate-server) from Azure DevOps Server. -Search in Azure DevOps Server supports both Azul Zulu OpenJDK and Oracle JRE, allowing you to choose between them based on your needs. -When you select a JRE during installation, Azure DevOps Server defaults to Azul Zulu OpenJDK 8. + > [!NOTE] + > If you're using Oracle Server JRE 8, which was the default for Search in TFS (Azure DevOps Server doesn't use Oracle Server JRE 8), be aware of the following information: + > * Search doesn't use or support any of the commercial features of Server JRE 8. Therefore, during Search configuration, the commercial features of the Server JRE are neither activated nor unlocked. + > * If you choose to continue with Oracle JRE, contact Oracle for a [Java SE Subscription](https://www.oracle.com/java/java-se-subscription.html), so that you can continue to receive JRE updates. -To change to the Azul Zulu OpenJDK, follow these steps: +#### Migrate to Microsoft Build of OpenJDK from Oracle Server JRE -![Java Migration flow](media/administration/java-migration-flow.png) +Search in Azure DevOps Server supports both, the Microsoft Build of OpenJDK, and Oracle JRE, which let you choose between them based on your needs. -For more information, see [GitHub Code-Search Java Migration](https://github.com/microsoft/Code-Search/tree/master/Java%20Migration). - -> [!NOTE] -> * If you choose to use Azul Zulu OpenJDK, ensure that you [download version 8](https://www.azul.com/downloads/zulu-community/?&version=java-8-lts&os=windows&os-details=Windows&architecture=x86-64-bit&package=jdk). +To change to the Microsoft Build of OpenJDK, ensure **JAVA\_HOME** variable is NOT set. Then, rerun the configuration wizard (`& "C:\Program Files\Azure DevOps Server XXX\Search\ES\vX.XX\bin\elasticsearch-service.bat" manager`) and select the version by setting the path for the *Java Virtual Machine*. ## Feature availability -* Work Item Search is available in TFS 2018 and later versions. +* Work Item Search is available in Team Foundation Server (TFS) 2018 and later versions. * Wiki Search is available in TFS 2018 Update 2 and later versions. * Work Item and Wiki search are built-in extensions that are installed by default during Search configuration. -* Code Search is available in TFS 2018 and later versions, and is an opt-in feature. You can install Code Search later from the Local Gallery. Go to **Local Gallery** (```http://{server}/_gallery```) as an administrator. Non-administrative users can also request the extension for Azure DevOps Server. For more information, see [Install an extension](../../marketplace/get-tfs-extensions.md) in the Local gallery documentation. +* Code Search is available in TFS 2018 and later versions, and is an opt-in feature. You can install Code Search later from the Local Gallery. Go to **Local Gallery** (```http://{server}/_gallery```) as an administrator. Non-administrative users can also request the extension for Azure DevOps Server. For more information, see [Install an extension](../../marketplace/get-tfs-extensions.md). ## Configure Search Configure the Search service using the dedicated pages in the Server Configuration Wizard as you install Azure DevOps Server. You can also [unconfigure Search](#uninstall-search) -afterwards by running the Server Configuration Wizard again or by launching the Search Configuration Wizard. For configuring Search, be aware of the [configuration considerations](#configuration-considerations). -### Configuration considerations +afterwards by running the Server Configuration Wizard again or by launching the Search Configuration Wizard. -Consider the following information when you're configuring Search: +### Configuration considerations -* Both Work Item and Wiki search get enabled by default when Search is configured. These extensions can be later removed if necessary from the **Manage Extensions** page of Azure DevOps Server +Consider the following information when you configure Search: -* The Code Search extension must be installed for each Azure DevOps Server collection where you want to use it. When initially configuring Search, you can set a checkbox to **Automatically install Code Search extension for existing and new Project Collections** to automate this process - * If you don't set the checkbox to install the Code Search extension for all your project collections, your PCA can install it from the Local Gallery. Ensure you go to the Local Gallery (`http://{Server}/_gallery`) from your Azure DevOps Server portal page. For more information, see [Install an extension](../../marketplace/get-tfs-extensions.md) in the Local gallery documentation +* Both Work Item and Wiki search get enabled by default when Search is configured. These extensions can be later removed if necessary from the **Manage Extensions** page of Azure DevOps Server. +* The Code Search extension must be installed for each Azure DevOps Server collection where you want to use it. When you initially configure Search, you can set a checkbox to **Automatically install Code Search extension for existing and new Project Collections** to automate this process. +* If you don't set the checkbox to install the Code Search extension for all your project collections, your PCA can install it from the Local Gallery. Ensure you go to the Local Gallery (`http://{Server}/_gallery`) from your Azure DevOps Server portal page. For more information, see [Install an extension](../../marketplace/get-tfs-extensions.md). +* It typically takes less than one hour for Search to index a collection. But, it may take up to 12 hours based on the size and number of code files, work items, or wiki pages. If you get no results after this period, [check the indexing status](manage-search.md#check-indexing-status). #### Use a second hard drive and remote server -* For maximum performance, the search index folder should be on a separate fast hard drive and backed by fast storage, such as a solid-state drive (SSD) or Storage Area Network (SAN). **Allocate up to 150%** of the size of all the repositories to be indexed, which is the worst-case scenario. The actual space that's consumed depends on the amount and type of code files, and the number of work items and wiki pages in that collection - * Unless specified, the indexing service and Elasticsearch engine use the network service account during installation to create and access the index files. If you choose a different account, it must have **Log on as a service** permission - * Restrict the permissions for the index disk and folder to protect the index from accidental or malicious modification or deletion. Configure appropriate [security settings](#secure-search) for the service - -* When you're configuring Search for a server with **multiple application tiers (ATs)**, make sure it's installed on a [separate server](#install-or-update-search-on-a-separate-server). After you've installed Search on the remote server, use the Configuration Wizard on any one of the AT servers to link the remote Search instance with your Azure DevOps Server instance. When unconfiguring Search in the future you must use the Configuration Wizard on the same AT server where configuration was originally carried out +* For maximum performance, the search index folder should be on a separate fast hard drive and backed by fast storage, such as a solid-state drive (SSD) or Storage Area Network (SAN). **Allocate up to 150%** of the size of all the repositories to be indexed, which is the worst-case scenario. The actual consumed space depends on the amount and type of code files, and the number of work items and wiki pages in that collection. + * Unless specified, the indexing service and Elasticsearch engine use the network service account during installation to create and access the index files. If you choose a different account, it must have **Log on as a service** permission. + * Restrict the permissions for the index disk and folder to protect the index from accidental or malicious modification or deletion. Configure appropriate [security settings](#secure-search) for the service. +* When you configure Search for a server with **multiple ATs**, install on a [separate server](#install-or-update-search-on-a-separate-server). After you install Search on the remote server, use the Configuration Wizard on any one of the AT servers to link the remote Search instance with your Azure DevOps Server instance. When you unconfigure Search, you must use the Configuration Wizard on the same AT server where configuration was originally carried out. #### Upgrade your server -* If you're doing a **pre-production upgrade** on a server where Search was already configured, you must fully reconfigure Search again to avoid corrupting your production instance. There isn't an option to configure Search as part of a pre-production upgrade. Instead, configure it after the pre-production upgrade is complete. You can uncheck **Automatically install and configure Code Search for all existing and new collections** during configuration. Instead, install the Search extension for just one or two of your collections after configuration is complete - -* If you're doing a **production upgrade** on a server where Search is configured and you want to keep it, check the box next to **Install and Configure Search**. The wizard detects your existing Search instance and automatically selects **Use existing Search instance** , and pre-populates your current Search service URL. Use the **Install a new Search instance** option only if you want to set up a new instance of Search on the same server. Setting up a new instance causes all your code, work items, and wiki to be indexed again, which - depending on the size of the collections - can take some time. During indexing, users may see partial search results - +* If you're doing a **pre-production upgrade** on a server where Search was already configured, you must fully reconfigure Search again to avoid corrupting your production instance. There isn't an option to configure Search as part of a preproduction upgrade. Instead, configure it after the preproduction upgrade is complete. You can uncheck **Automatically install and configure Code Search for all existing and new collections** during configuration. Instead, install the Search extension for just one or two of your collections after configuration is complete +* If you're doing a **production upgrade** on a server where Search is configured and you want to keep it, check the box next to **Install and Configure Search**. The wizard detects your existing Search instance and automatically selects **Use existing Search instance** , and prepopulates your current Search service URL. Use the **Install a new Search instance** option only if you want to set up a new instance of Search on the same server. Setting up a new instance causes all your code, work items, and wiki to be indexed again, which - depending on the size of the collections - can take some time. During indexing, users might see partial search results * If you're **upgrading your server to new hardware**, you have the following two options. Select from these options, depending on how Search was previously configured: - If Search is on a separate server from Azure DevOps Server, you must select **Install and Configure Search** in the Server Configuration Wizard, and then select **Use an existing Search instance** and provide the URL of your existing Search instance to complete the Search configuration - If Search is configured alongside your Azure DevOps Server instance on the old server, you must select **Install and Configure Search** in the Server Configuration Wizard. Then, select **Install a new Search instance** again on the new server if you want to continue to cohost Search and Azure DevOps Server. All Search indexes for all collections are re-created which, depending on the size of each collection, might take some time - * If you're **detaching a collection** from one Azure DevOps Server instance to attach it to another instance, do the following steps: 1. Detach the collection from source Azure DevOps Server instance 2. Configure Search on the target Azure DevOps Server instance (if not yet done already) @@ -165,28 +146,25 @@ Consider the following information when you're configuring Search: To install or update Search on a separate or remote server, typically when there are more than 250 users, do the following steps: -1. As you install Azure DevOps Server on the primary server, set the **Install and configure Search** checkbox +1. As you install Azure DevOps Server on the primary server, set the **Install and configure Search** checkbox. in the **Search** page of the Server Configuration Wizard. 2. Select the option to **Use an existing Search service**. -3. Use the **Search service package** link that's provided in the wizard to access a set of Search installer files - on the local machine. Then, copy these files to the remote server. - +3. Use the **Search service package** link provided in the wizard to access a set of Search installer files on the local machine. Then, copy these files to the remote server. 4. Follow the instructions in the **Readme.txt** file, located in the set of installer files, to install or update the Search service on the remote server. 5. After installation completes, copy the resulting Search server URL into the **Search URL** field of the configuration wizard that runs on the Azure DevOps Server instance. -6. When both installations are complete, configure appropriate - [security settings](#secure-search) for both servers. +6. When both installations are complete, configure appropriate [security settings](#secure-search) for both servers. ## Secure search -The Search service uses a modified version of [Elasticsearch](https://www.elastic.co/products/elasticsearch) (the terms "Search" and "Elasticsearch" are used interchangeably for the rest of this section). Administrators must provide credentials whether the Search service is on the same machine as Azure DevOps Server, or on a separate machine. This action is part of configuring the Search feature through the server or the Search configuration wizard. These credentials are new and aren't related to any pre-existing account or server credentials. They're used to set up and connect to Search service. These new sets of credentials enable basic authentication in the search service. +The Search service uses a modified version of [Elasticsearch](https://www.elastic.co/products/elasticsearch). The terms "Search" and "Elasticsearch" are used interchangeably for the rest of this section. Administrators must provide credentials whether the Search service is on the same machine as Azure DevOps Server, or on a separate machine. This action is part of configuring the Search feature through the server or the Search configuration wizard. These credentials are new and aren't related to any preexisting account or server credentials. They're used to set up and connect to Search service. These new sets of credentials enable basic authentication in the search service. -![Search credentials](media/administration/tfsU3_search_cred1.png) +![Screenshot showing search credentials.](media/administration/tfsU3_search_cred1.png) -For an upgrade from TFS 2018 Update 1.1 to TFS 2018 Update 3 or for search reconfiguration, only the user information automatically populates and administrators must provide password credentials. Administrators can provide a different username and password if they wish. If the Search service is on the same machine as Azure DevOps Server, administrators can provide a new set of credentials in the Configuration Wizard to set up the Search service, if wanted. However, if the Search service is on a remote machine, administrators must first provide the new credentials to the Search service setup script. +For an upgrade from TFS 2018 Update 1.1 to TFS 2018 Update 3 or for search reconfiguration, only the user information automatically populates and administrators must provide credentials. Administrators can provide different credentials if they wish. If the Search service is on the same machine as Azure DevOps Server, administrators can provide a new set of credentials in the Configuration Wizard to set up the Search service, if wanted. However, if the Search service is on a remote machine, administrators must first provide the new credentials to the Search service setup script. > [!NOTE] -> * Username and password values should both be between 8 and 64 characters in length. While the password can be assigned any value, the username can contain only alphanumeric and underscore characters. +> * Credential values should both be between 8 and 64 characters in length. > * Search credentials only authenticate the users and make sure that unauthenticated users can't access the Elasticsearch endpoint. However, Elasticsearch doesn't support HTTPS and so these credentials get sent over the network as Base64 encoded strings. If there's a possibility of intermediate access to request, configure appropriate security settings based on your corporate security and compliance requirements. > * Aim to limit access to both searching and indexing to specific users or user groups using encryption through IPSec, described as follows. @@ -205,15 +183,15 @@ Consider the following techniques for using IPSec to secure Elasticsearch on a W ## Upgrade search -- **TFS 2018 Update 2** includes updated Search components and Wiki Search. +- **TFS 2018 Update 2**: Includes updated Search components and Wiki Search. - If the Search service was set up during the 2018 RTM upgrade and configured in the TFS system you're upgrading, its components update automatically. - - If Search was configured on a remote server, follow [these instructions](#install-or-update-search-on-a-separate-server) to update it. + - If Search was configured on a remote server, see [Install or update search on a separate server](#install-or-update-search-on-a-separate-server) to update it. In both cases, all existing content (code files and work items) gets automatically reindexed to support the updated components after configuration. Depending on the volume of content, this upgrade might take some time to complete. -- **TFS 2018 Update 1.1 and TFS 2018 Update 3** include basic authentication for the communication between the TFS and Search service to make it more secure. Any installation or upgrade to TFS 2018 Update 1.1 or TFS 2018 Update 3, must provide credentials as part of configuring Search feature, through Server or the Search configuration wizard. +- **TFS 2018 Update 1.1 and TFS 2018 Update 3**: Includes basic authentication for the communication between the TFS and Search service to make it more secure. Any installation or upgrade to TFS 2018 Update 1.1 or TFS 2018 Update 3, must provide credentials as part of configuring Search feature, through Server or the Search configuration wizard. -- **TFS 2018 Update 2 (or higher) to version Azure DevOps Server 2019 Update 1**, when search is configured on a separate server, requires a reinstallation of search. While following [the instructions for an upgrade](#install-or-update-search-on-a-separate-server), in step 4 instead of updating `Configure-TFSSearch.ps1 – Operation update`, run the following command to reinstall search: +- **TFS 2018 Update 2 (or higher) to version Azure DevOps Server 2019 Update 1**: When search is configured on a separate server, require a reinstallation of search. While following [the instructions for an upgrade](#install-or-update-search-on-a-separate-server), in step 4 instead of updating `Configure-TFSSearch.ps1 – Operation update`, run the following command to reinstall search. ``` Configure-TFSSearch.ps1 -Operation remove @@ -222,81 +200,77 @@ Configure-TFSSearch.ps1 -Operation install -TFSSearchInstallPath ### Unconfigure Search on the machine configured as your Azure DevOps Server -1. Uninstall the Search extension for each collection where it's installed. +1. Uninstall the Search extension for each collection. Go to the **Manage Extensions** page of each collection in your Azure DevOps Server instance: - ::: moniker range=">= azure-devops-2019" - ![Screenshot of checking that the extension is installed](media/shared/goto-marketplace-new.png) + ::: moniker range="<=azure-devops" + ![Screenshot of checking that the extension is installed.](media/shared/goto-marketplace-new.png) ::: moniker-end - ::: moniker range="tfs-2018" - ![Screenshot of Checking the extension is installed](media/shared/goto-marketplace.png) - ::: moniker-end + 2. Remove the Search feature: - - Open the Azure DevOps Server Administration Console - - In the left pane, select the name of the server - - In the right pane, choose **Remove Feature** - - In the Remove Feature dialog, select **Search service**, and then choose **Remove** + + 1. Open the Azure DevOps Server Administration Console. + 2. Select the name of the server. + 3. Choose **Remove Feature**. + 4. Select **Search service**, and then choose **Remove**. + 3. Remove the Elasticsearch service: - - Open **Command Prompt** as an administrator - - Change the directory: - * For TFS 2018 Update 2 and onward, and Azure DevOps Server, `cd "C:\Program Files\Microsoft Team Foundation Server 15.0\Search\ES\elasticsearch-5.4.1\bin"` - - Remove the service: - * For TFS 2018 and Azure DevOps Server, `"elasticsearch-service.bat remove"` + + 1. Open **Command Prompt** as an administrator. + 2. Change the directory, `cd "C:\Program Files\Microsoft Team Foundation Server 15.0\Search\ES\elasticsearch-5.4.1\bin"`. + 3. Remove the service, `"elasticsearch-service.bat remove"`. + 4. Remove Search data: - - Delete the contents of the location described by the environment variable `SEARCH_ES_INDEX_PATH` -5. Remove environment variables: - - Delete the environment variable `"SEARCH_ES_INDEX_PATH"` - - Delete the environment variable `"ES_HEAP_SIZE"` (this environment variable is obsolete for TFS 2018 Update 2 and later, and Azure DevOps Server) - + - Delete the contents of the location described by the environment variable, `SEARCH_ES_INDEX_PATH`. +5. Delete the environment variable, `"SEARCH_ES_INDEX_PATH"`. + -### Unconfigure Search when it's configured on a separate server +### Unconfigure Search on a separate server -1. Uninstall the Search extension, like for Code, Work item, or Wiki, for each collection where it's installed. Go to the **Manage Extensions** page of each collection in your Azure DevOps Server instance. +Do the following steps to unconfigure Search, like for Code, Work item, or Wiki, for each collection. - ::: moniker range=">= azure-devops-2019" - ![Screenshot Checking that the extension is installed](media/shared/goto-marketplace-new.png) - ::: moniker-end +1. Go to the **Manage Extensions** page for each collection in your Azure DevOps Server instance. - ::: moniker range="tfs-2018" - ![Screenshot of Checking that the extension's installed](media/shared/goto-marketplace.png) + ::: moniker range="<=azure-devops" + ![Screenshot Checking that the extension is installed.](media/shared/goto-marketplace-new.png) ::: moniker-end -::: moniker range="<= azure-devops-2019" + + 2. Remove the Search feature: - - Open the Remove Feature dialog, Administration Console - - In the left pane, select the name of the Azure DevOps Server - - In the right pane, choose **Remove Feature** - - In the Remove Feature dialog, select **Search service**, and then choose **Remove** + 1. Open the *Remove Feature* dialog, Administration Console. + 1. In the left pane, select the name of the Azure DevOps Server. + 1. In the right pane, choose **Remove Feature**. + 1. In the *Remove Feature* dialog, select **Search service**, and then choose **Remove**. -3. Remove the Elasticsearch service and data: +3. Remove the Elasticsearch service and data. - - Open **PowerShell** as an administrator - - Open the **Configure Search.ps1** folder, along with the rest of the files that are required for a remote install of Search - - Run the script again with the remove option: `"ConfigureTFSSearch.ps1 -remove"` -::: moniker-end + 1. Open **PowerShell** as an administrator. + 1. Open the **Configure Search.ps1** folder, along with the rest of the files that are required for a remote install of Search. + 1. Run the script again with the remove option: `"ConfigureTFSSearch.ps1 -remove".` -## Search limitations +## Limitations of Search Search for Azure DevOps Server has the following limitation: -* If you do a disaster recovery (DR) operation and move your server back to an earlier snapshot of your SQL database, [reindex all your collections](manage-search.md#reindex-a-repository-or-collection). +* [Reindex all your collections](manage-search.md#reindex-a-repository-or-collection) if you do a disaster recovery (DR) operation and move your server back to an earlier snapshot of your SQL database. +* Search isn't extensible, but you can submit a new feature request on the [Developer Community](https://developercommunity.visualstudio.com/home). ## Related articles - [Manage indexing for Search](manage-search.md) - [Get started with Search](get-started-search.md) -- [Search FAQs](faq-search.yml) \ No newline at end of file diff --git a/docs/project/search/manage-search.md b/docs/project/search/manage-search.md index e1139f41984..09fe9d3aeca 100644 --- a/docs/project/search/manage-search.md +++ b/docs/project/search/manage-search.md @@ -7,7 +7,7 @@ ms.subservice: azure-devops-search ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 02/14/2023 +ms.date: 03/04/2024 monikerRange: '< azure-devops' --- @@ -16,16 +16,17 @@ monikerRange: '< azure-devops' [!INCLUDE [version-lt-azure-devops](../../includes/version-lt-azure-devops.md)] You can manage your search extension and indexing status, which include the following actions: -[Check indexing status](#check-indexing-status) -[Pause indexing](#pause-indexing) -[Resume indexing](#resume-indexing) -[Reindex a repository or collection](#reindex-a-repository-or-collection) - -For information about how to install or configure Search, see [Install and configure Search](install-configure-search.md). +- [Check indexing status](#check-indexing-status) +- [Pause indexing](#pause-indexing) +- [Resume indexing](#resume-indexing) +- [Reindex a repository or collection](#reindex-a-repository-or-collection) ## Prerequisites -To manage Search and indexing, you must be a [Project Collection Administrator (PCA)](../../user-guide/project-admin-tutorial.md) for the organization. +| Category | Requirements | +|--------------|-------------| +| **Permissions** | Member of the [Project Collection Administrators](../../user-guide/project-admin-tutorial.md) group. | +| **Tasks** | Complete [Install and configure Search](install-configure-search.md). | ## Manage indexing @@ -33,10 +34,10 @@ Search gets managed by running PowerShell and SQL scripts. All of these scripts The PowerShell scripts require the SQL script files, so ensure the **SqlScripts** folder and its contents are present, along with the PowerShell scripts. -![Download script files for administration](media/administration/script-filesv2.png) +![Screenshot showing download script files for administration.](media/administration/script-filesv2.png) > [!NOTE] -> When you're executing scripts, ensure that you run the appropriate script for your Azure DevOps Server or TFS version: +> When you execute scripts, ensure that you run the appropriate script for your version: > > * [TFS 2018 RTM](https://github.com/Microsoft/Code-Search/tree/master/TFS_2018RTW) > * [TFS 2018 Update 1](https://github.com/Microsoft/Code-Search/tree/master/TFS_2018Update1) @@ -45,126 +46,95 @@ The PowerShell scripts require the SQL script files, so ensure the **SqlScripts* ### Check indexing status -(For TFS 2018 and Azure DevOps Server, see the [next section](#check-indexing-status-for-tfs-2018-and-later).) - -To check the indexing status after Search is configured, or after the extension is installed for a collection, do the following steps: - -1. Execute the `CheckIndexingStatus.ps1` script with administrative privileges. - You're prompted to enter the following information: - - - The SQL server instance name where the TFS configuration database is. - - The name of the TFS collection database. - - The name of the TFS configuration database. - - The name of the collection. - - The number of previous days to check indexing status.

      - -2. Check the following outputs: - - - **Collection indexing was triggered successfully**: Indicates that indexing is in progress. If it's displayed, check the following outputs. If it isn't displayed, go ahead to step 3. - - **Repositories Indexing Completed**: The repositories whose indexing has been completed and are now searchable. - - **Repositories in File Discovery Phase**: The repositories where files are yet to be discovered. The files are indexed after this stage. Repositories in this state aren't yet searchable. The number of files that are already discovered for indexing in each repository shows. This number increases as more files get discovered. - - **Repositories Indexing In Progress**: These repositories are partially indexed and should be searchable, even if the results are only partial. - -3. It takes some time for indexing to complete. Execute the `CheckIndexingStatus.ps1` script at intervals to check indexing progress. - -4. If indexing isn't working, or is in progress, but the number of files pending haven't changed for some time, or if you get no results for a search, execute the `TriggerCollectionIndexing.ps1` script in a PowerShell window with administrative permission. - -5. If the problem persists, contact [customer support ](https://developercommunity.visualstudio.com/spaces/21/index.html). - -### Check indexing status for TFS 2018 and later +To check the indexing status after Search is configured, or after the extension is installed for a collection, do the following steps. -To check the indexing status after Search is configured, or after the extension was installed for a collection, complete the following steps: +::: moniker range=" azure-devops-2022" -1. Execute the `ExtensionInstallIndexingStatus.ps1` script with administrative privileges. - You're prompted to enter: +1. Execute the `ExtensionInstallIndexingStatus.ps1` script with **administrative privileges** and enter the following information: - - The SQL server instance name where the Azure DevOps Server configuration database is. + - The SQL server instance name where the Azure DevOps Server configuration database is located. - The name of the Azure DevOps Server collection database. - The name of the Azure DevOps Server configuration database. - The name of the collection. - - The number of previous days to check indexing status.

      + - The number of previous days to check indexing status. -2. Check the following outputs: +2. Review the following outputs: - - **Collection indexing was triggered successfully**: Indicates that - indexing is in progress. If it's displayed, check the following outputs. - If it isn't displayed, go to step 3. - - - **Repositories completed indexing**: The number of repositories for which indexing has completed and are searchable. - - - **Status of repositories currently indexing**: A list of the names of all the repositories that are still being indexed and are partially searchable.

      + - **Collection indexing was triggered successfully:** Indicates that indexing is in progress. + - **Repositories Indexing Completed:** Lists repositories whose indexing completed and is searchable. + - **Status of repositories currently indexing:** Lists the names of all the repositories that are still being indexed and are partially searchable. It takes some time for indexing to complete. -3. It takes some time for indexing to complete. Execute the `RecentIndexingActivity.ps1` script at intervals to check indexing progress. This script takes the same parameters as the `ExtensionInstallIndexingStatus.ps1` script. +3. Execute the `RecentIndexingActivity.ps1` script at intervals for indexing progress. This script takes the same parameters as the `ExtensionInstallIndexingStatus.ps1` script: - - **Repositories completed fresh indexing**: The number of repositories for which indexing has completed within the specified time interval. + - **Repositories completed fresh indexing:** Shows number of repositories for which indexing completed within the specified time interval. + - **Count of repositories with fresh indexing in progress:** Shows the number of repositories for which indexing isn't complete. These repositories are still being indexed and are partially searchable. + - **Repositories completed continuous indexing:** Shows the number of commits processed in the specified time interval. The number might not exactly match the total number of pushes to the repository because merges are committed as they're indexed. + - **Count of repositories with continuous indexing in progress:** Shows the number of repositories for which the commits are still being processed. These repositories show incomplete results until indexing is completed. + - **Count of indexing job failures:** Shows the number of indexing jobs that failed. Repositories associated with these indexing jobs could potentially show incomplete results until later indexing jobs for the same repositories patched the failed indexing. - - **Count of repositories with fresh indexing in progress**: The number of repositories for which indexing hasn't yet completed. These repositories are still being indexed and are partially searchable. +::: moniker-end - - **Repositories completed continuous indexing**: The number of commits processed in the specified time interval. The number may not exactly match the total number of pushes to the repository because merges are committed as they're indexed. +::: moniker range="< azure-devops-2022" - - **Count of repositories with continuous indexing in progress**: The number of repositories for which the commits are still being processed. These repositories show incomplete results until indexing is completed.

      - - - **Count of indexing job failures**: The number of indexing jobs that failed. Repositories associated with these indexing jobs could potentially show incomplete results until later indexing jobs for the same repositories have patched the failed indexing.

      +1. Execute the `CheckIndexingStatus.ps1` script with **administrative privileges** and enter the following information: - + - The **SQL server instance name** where the **TFS configuration database** is located. + - The name of the **TFS collection database**. + - The name of the **TFS configuration database**. + - The name of the **collection**. + - The number of previous days to check indexing status. -### Pause indexing +2. Review the following outputs: + - **Collection indexing was triggered successfully:** Indicates that indexing is in progress. + - **Repositories Indexing Completed:** Lists repositories whose indexing completed and is searchable. + - **Repositories in File Discovery Phase:** Repositories where files are yet to be discovered. These files are indexed after this stage. + - **Repositories Indexing In Progress:** Repositories that are partially indexed and should be searchable, even if the results are only partial. It might take some time for indexing to complete. + +3. Monitor progress: + 1. Execute the `CheckIndexingStatus.ps1` script at intervals for indexing progress. + 2. If indexing isn’t working or if the number of pending files doesn't change for some time, execute the `TriggerCollectionIndexing.ps1` script with administrative permission. -To pause all indexing, execute `PauseSearchIndexing.ps1`, which is useful if you see spikes in CPU utilization after configuring Search. +::: moniker-end -You're prompted to enter the following information: + If you encounter any issues, get support on the [Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). +### Pause indexing + +To pause all indexing, execute: `PauseSearchIndexing.ps1`, which is useful if you see spikes in CPU utilization after configuring Search. You're prompted to enter the following information. * The SQL server instance name where the Azure DevOps Server configuration database is * The name of the Azure DevOps Server configuration database - - ### Resume indexing -If indexing was paused, execute `ResumeIndexing.ps1` to start indexing again. -You're prompted to enter the following information: - +If you paused indexing, execute: `ResumeIndexing.ps1` to start again. You're prompted to enter the following information. * The SQL server instance name where the Azure DevOps Server configuration database is * The name of the Azure DevOps Server configuration database - - ### Reindex a repository or collection To reindex a Git or TFVC repository, execute the appropriate -version of the script `Re-IndexingRepository.ps1` for your Azure DevOps Server version. -You're prompted to enter the following information: +version of the script, `Re-IndexingRepository.ps1`, for your Azure DevOps Server version. +You're prompted to enter the following information. * The SQL server instance name where the Azure DevOps Server configuration database is * The name of the Azure DevOps Server collection database * The name of the Azure DevOps Server configuration database -* The type of reindexing to execute. The type can be one of the following values: - - **Git\_Repository** - - **TFVC\_Repository** +* The type of reindexing to execute, either `Git\_Repository` or `TFVC\_Repository` * The name of the collection * The name of the repository to reindex -To reindex a **collection**, execute the script `TriggerCollectionIndexing.ps1`. -You're prompted to enter the following information: - +To reindex a **collection**, execute the script: `TriggerCollectionIndexing.ps1`. +You're prompted to enter the following information. * The SQL server instance name where the Azure DevOps Server configuration database is * The name of the Azure DevOps Server collection database * The name of the Azure DevOps Server configuration database * The name of the collection -* The entities to reindex. The entities can be one of the following values: - - **All** - - **Code** - - **WorkItem** - - **Wiki** +* The entities to reindex, either `All`, `Code`, `WorkItem`, or `Wiki` ## Search limitations -Search for Azure DevOps Server has the following limitation: - -* If you do a disaster recovery (DR) operation and move your server back to an earlier snapshot of your SQL database, [reindex all your collections](manage-search.md#reindex-a-repository-or-collection). +If you do a disaster recovery (DR) operation and move your server back to an earlier snapshot of your SQL database, [reindex all your collections](manage-search.md#reindex-a-repository-or-collection). ## Related articles - [Install and configure Search](install-configure-search.md) -- [Search FAQs](faq-search.yml) - diff --git a/docs/project/search/media/advanced-work-item-search-syntax/configure-branches.png b/docs/project/search/media/advanced-work-item-search-syntax/configure-branches.png index 5bab1bb5fd1..96c43ff4e38 100644 Binary files a/docs/project/search/media/advanced-work-item-search-syntax/configure-branches.png and b/docs/project/search/media/advanced-work-item-search-syntax/configure-branches.png differ diff --git a/docs/project/search/media/shared/package-search-results-filters.png b/docs/project/search/media/shared/package-search-results-filters.png new file mode 100644 index 00000000000..bc75424f861 Binary files /dev/null and b/docs/project/search/media/shared/package-search-results-filters.png differ diff --git a/docs/project/search/media/shared/pkgsrch-results-filters.png b/docs/project/search/media/shared/pkgsrch-results-filters.png deleted file mode 100644 index ce58db372ad..00000000000 Binary files a/docs/project/search/media/shared/pkgsrch-results-filters.png and /dev/null differ diff --git a/docs/project/search/toc.yml b/docs/project/search/toc.yml index 06063eacdbc..822a0607127 100644 --- a/docs/project/search/toc.yml +++ b/docs/project/search/toc.yml @@ -6,11 +6,7 @@ href: functional-work-item-search.md - name: Functional package search href: functional-package-search.md -- name: Search organization settings - href: ../../organizations/settings/search-settings.md - name: Install and configure search href: install-configure-search.md - name: Manage search indexing href: manage-search.md -- name: FAQs - href: faq-search.yml diff --git a/docs/project/toc.yml b/docs/project/toc.yml index 4bb26a01922..30343053b03 100644 --- a/docs/project/toc.yml +++ b/docs/project/toc.yml @@ -1,22 +1,22 @@ - name: Wikis, Search, & Navigation href: index.yml - name: Get started - expanded: true items: - name: Set your preferences - href: ../organizations/settings/set-your-preferences.md?toc=/azure/devops/project/toc.json + href: ../organizations/settings/set-your-preferences.md?toc=/azure/devops/project/toc.json - name: Set personal or team favorites - href: ../organizations/settings/set-your-preferences.md?toc=/azure/devops/project/toc.json + href: ../organizations/settings/set-your-preferences.md?toc=/azure/devops/project/toc.json - name: Understand your default permissions - href: ../organizations/security/permissions-access.md?toc=/azure/devops/project/toc.json + href: ../organizations/security/permissions-access.md?toc=/azure/devops/project/toc.json - name: Connect to a project - href: ../organizations/projects/connect-to-projects.md?toc=/azure/devops/project/toc.json + href: ../organizations/projects/connect-to-projects.md?toc=/azure/devops/project/toc.json - name: Navigate the web portal href: ./navigation/index.md - name: Get started with Search href: ./search/get-started-search.md - name: Create a wiki for your project href: ./wiki/wiki-create-repo.md + expanded: true - name: Wiki href: wiki/toc.yml - name: Search @@ -38,7 +38,7 @@ - name: Get Started href: ../get-started/index.yml - name: Notifications - href: ../organizations/notifications/about-notifications.md?toc=/azure/devops/organizations/toc.json + href: ../organizations/notifications/about-notifications.md?toc=/azure/devops/organizations/toc.json - name: Manage projects href: ../organizations/projects/about-projects.md - name: Settings & Usage diff --git a/docs/project/wiki/about-readme-wiki.md b/docs/project/wiki/about-readme-wiki.md index d2c07106ef7..a22271a12d0 100644 --- a/docs/project/wiki/about-readme-wiki.md +++ b/docs/project/wiki/about-readme-wiki.md @@ -1,7 +1,7 @@ --- -title: Share information with a project, repo, README, or Wiki +title: Share information with a project, repo, README, or wiki titleSuffix: Azure DevOps -description: Share information using a project, repo, README, or Wiki in Azure DevOps. +description: Share information using a project, repo, README, or wiki in Azure DevOps. ms.subservice: azure-devops-wiki ms.custom: wiki, devdivchpfy22 ms.assetid: @@ -13,22 +13,17 @@ ms.date: 07/06/2022 monikerRange: '<= azure-devops' --- -# About Wikis, READMEs, and Markdown +# About wikis, READMEs, and Markdown [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -To support your team or contributors to your project, use [Markdown](https://en.wikipedia.org/wiki/Markdown) to add rich formatting, tables, and images to your team project. You can use Markdown format within a team project Wiki, content you add to a dashboard, your team project README file, or other repository README file. +To support your team or contributors to your project, use [Markdown](https://en.wikipedia.org/wiki/Markdown) to add rich formatting, tables, and images to your team project. You can use Markdown format within a team project wiki, content you add to a dashboard, your team project README file, or other repository README file. ## Wiki Use your team project wiki to share information with other team members. When you provision a wiki from scratch, a new Git repository stores your Markdown files, images, attachments, and sequence of pages. This wiki supports collaborative editing of its content and structure. -::: moniker range="tfs-2018" -> [!NOTE] -> The built-in wiki is available with TFS 2018 and later versions. To download Azure DevOps Server, see [Visual Studio Downloads](https://visualstudio.microsoft.com/downloads/). -::: moniker-end - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" The following features are supported for the team project wiki. @@ -41,47 +36,26 @@ The following features are supported for the team project wiki. - [Add and edit wiki pages](add-edit-wiki.md) - [View wiki page history and revert](wiki-view-history.md) -- [Version, select, or unpublish a published wiki](wiki-select-unpublish-versions.md) - [Clone and update wiki content offline](wiki-update-offline.md) -- [Use Wiki keyboard shortcuts](wiki-keyboard-shortcuts.md) -- [Filter or print Wiki content](filter-print-wiki.md) 1 +- [Use wiki keyboard shortcuts](../navigation/keyboard-shortcuts.md#wiki-keyboard-shortcuts) +- [Filter or print wiki content](filter-print-wiki.md) 1 > [!NOTE] -> The print feature may not be available from the Firefox web browser. +> The print feature might not be available from the Firefox web browser. ### Format wiki content - [Markdown format](markdown-guidance.md) -- [HTML tags](wiki-markdown-guidance.md#html) +- [HTML tags](markdown-guidance.md#html) - [Insert and resize images](markdown-guidance.md#images) -- [Link to work items using #](wiki-markdown-guidance.md#link-work-items) +- [Link to work items using #](markdown-guidance.md#link-work-items) - [Attach files](markdown-guidance.md#attach) - [Mathematical notation and characters](markdown-guidance.md#math-notation) -- [Table of contents (TOC) for Wiki pages](wiki-markdown-guidance.md#toc-wiki) - -::: moniker-end - -::: moniker range="tfs-2018" - -The following features are supported for the team project wiki you create in the indicated TFS version or later versions. To learn more, see [Create a wiki for your team project](wiki-create-repo.md) and [Add and edit wiki pages](add-edit-wiki.md). - -> [!div class="mx-tdBreakAll"] -> |Feature | TFS version | -> |--------|--------------| -> |[Markdown format](markdown-guidance.md) | TFS 2018 | -> |[HTML tags](wiki-markdown-guidance.md#html) | TFS 2018 | -> |[Insert and resize images](markdown-guidance.md#images) | TFS 2018 | -> |[Link to work items using #](wiki-markdown-guidance.md#link-work-items) | TFS 2018 | -> |[Attach files](markdown-guidance.md#attach) | TFS 2018 | -> |[Filter Wiki TOC](filter-print-wiki.md) | TFS 2018 | -> |[Mathematical notation and characters](markdown-guidance.md#math-notation) |TFS 2018.2 | -> |[Preview a Wiki page while editing](add-edit-wiki.md) | TFS 2018.2 | -> |[Print a Wiki page](filter-print-wiki.md) 1 | TFS 2018.2 | -> |[Wiki keyboard shortcuts](wiki-keyboard-shortcuts.md) | TFS 2018.2 | +- [Table of contents (TOC) for wiki pages](markdown-guidance.md#toc-wiki) ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Publish existing Git repositories to a wiki @@ -100,32 +74,19 @@ There are significant differences between how you manage the content for a wiki ## Markdown -Markdown makes it easy to format text and include images. You can also link to documents within your project pages, README files, dashboards, and pull request comments. +Markdown makes it easy to format text and include images. You can also link to documents within your project pages, README files, dashboards, and pull requests. You can provide guidance to your team in the following places using Markdown: -You can provide guidance to your team in the following places using Markdown: - -::: moniker range=">= azure-devops-2019" - +::: moniker range="<=azure-devops" - [Team project wiki](add-edit-wiki.md) - [Publish code as wiki](publish-repo-to-wiki.md) - [Add Markdown to a dashboard](../../report/dashboards/add-markdown-to-dashboard.md) - [Project page or Welcome pages](../../organizations/projects/project-vision-status.md) - [Repository README files](../../repos/git/create-a-readme.md) -- [Pull request comments](../../repos/git/pull-requests.md) - -::: moniker-end - -::: moniker range="tfs-2018" - -- [Add and edit wiki pages](add-edit-wiki.md) -- [Add Markdown to a dashboard](../../report/dashboards/add-markdown-to-dashboard.md) -- [Project page or Welcome pages](../../organizations/projects/project-vision-status.md) -- [Repository README files](../../repos/git/create-a-readme.md) -- [Pull request comments](../../repos/git/pull-requests.md) +- [Pull requests](../../repos/git/pull-requests.md) ::: moniker-end -For supported syntax, see [Syntax guidance for Markdown files, widgets, wikis, and pull request comments](markdown-guidance.md). +For supported syntax, see [Use Markdown in Azure DevOps](markdown-guidance.md). ## READMEs diff --git a/docs/project/wiki/add-comments-wiki.md b/docs/project/wiki/add-comments-wiki.md index 2a929ca8362..0201f1eef36 100644 --- a/docs/project/wiki/add-comments-wiki.md +++ b/docs/project/wiki/add-comments-wiki.md @@ -4,45 +4,47 @@ titleSuffix: Azure DevOps description: Learn how to add comments to wiki pages in Azure DevOps. ms.subservice: azure-devops-wiki ms.custom: wiki, devdivchpfy22 -ms.topic: conceptual +ms.topic: how-to ms.assetid: ms.author: chcomley author: chcomley ms.reviewer: gopinach monikerRange: '>= azure-devops-2020' -ms.date: 06/21/2022 +ms.date: 08/05/2024 --- # Add comments to wiki pages [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -Learn how to add comments to wiki pages for better collaboration. +Learn how to add comments to wiki pages to enhance collaboration among team members. + +## Prerequisites + +[!INCLUDE [wiki-prerequisites](includes/wiki-prerequisites.md)] ## Add a comment -Add a comment at the bottom of any wiki page. Comments are posted on a per-branch basis. For example, if you make a comment on a wiki page on the main branch, it doesn't appear in another published branch of a file of the same name. Comments are stored on the internal database. For more information, see [Data locations for Azure DevOps](../../organizations/security/data-location.md). +You can add a comment at the bottom of any wiki page. Comments get posted on a per-branch basis. For example, if you make a comment on a wiki page on the main branch, it doesn't appear in another published branch of a file of the same name. Comments get stored on the internal database. For more information, see [Data locations for Azure DevOps](../../organizations/security/data-location.md). -![Create comment on wiki page](media/wiki/add-wiki-comment.png) +![Screenshot of Created comment on wiki page.](media/wiki/add-wiki-comment.png) -### View Markdown and preview tabs +When a user reacts to a comment on a wiki, an email notification gets sent to the commenter and optionally the followers. When a user adds a comment on a wiki, an email notification gets sent to all followers of the wiki regardless of who is tagged in the comment. -When you add a Markdown-based comment, there's a Markdown editor and preview tab. Use these tabs to view and change how the comment is rendered before you add it. You can also @mention users and groups. This @mention sends an email notification to each user or group, with a link to the wiki page. +## View Markdown and preview tabs -![Wiki comments in Markdown and preview tabs](media/wiki/wiki-comments-markdown-preview-tabs.png) +When you add a Markdown-based comment, there's a Markdown editor and preview tab. Use these tabs to view and change how the comment is rendered before you add it. You can also [@mention users and groups](../../organizations/notifications/at-mentions.md). This @mention sends an email notification to each user or group, with a link to the wiki page. -## Edit or delete comment +![Screenshot of wiki comments in Markdown and preview tabs.](media/wiki/wiki-comments-markdown-preview-tabs.png) -Edit or delete any comments that you've added to a wiki. +## Edit or delete a comment -![Edit or delete wiki comment](media/wiki/wiki-comment.png) +Edit or delete any comments that you added to a wiki. You can't edit or delete comments made by other users. -## Related articles +![Screenshot of Edit or delete wiki comment.](media/wiki/wiki-comment.png) +## Related articles - [Follow wiki pages, get notifications](follow-notifications-wiki-pages.md) - [Create and embed a work item from wiki content](create-embed-wit-from-wiki.md) -- [Version, select, or unpublish a wiki](wiki-select-unpublish-versions.md) -- [Markdown guidance](markdown-guidance.md) -- [Wiki Markdown guidance](wiki-markdown-guidance.md) - +- [Get Markdown guidance](markdown-guidance.md) diff --git a/docs/project/wiki/add-edit-wiki.md b/docs/project/wiki/add-edit-wiki.md index a04b1271563..66114eaed1a 100644 --- a/docs/project/wiki/add-edit-wiki.md +++ b/docs/project/wiki/add-edit-wiki.md @@ -10,7 +10,7 @@ author: chcomley ms.reviewer: gopinach ms.topic: quickstart monikerRange: '<= azure-devops' -ms.date: 07/06/2022 +ms.date: 10/18/2024 --- # Add and edit wiki pages @@ -19,22 +19,12 @@ ms.date: 07/06/2022 You can add a title and content to a page, after the [wiki Git repository is provisioned](./wiki-create-repo.md) for your team project. There's a side-by-side edit and preview experience where you can edit the page and preview the content as you go. -Learn how to do the following tasks: - -> [!div class="checklist"] -> * Open wiki -> * Add a wiki page -> * View revisions for a page -> * Edit and delete wiki pages -> * Reorder wiki pages -> * Make a page the wiki home page - -While authoring pages using [Markdown format](./markdown-guidance.md), you can also use the format pane for rich-text formatting and inserting images, attachments, and links. +While you author pages using [Markdown format](./markdown-guidance.md), you can also use the format pane for rich-text formatting and inserting images, attachments, and links. > [!div class="mx-imgBorder"] > ![Wiki home page](media/wiki/wiki-edit.png) -As you edit the page, save it by entering **Ctrl+S**. To save with a custom revision message, select :::image type="icon" source="../../media/icons/context-menu.png" border="false":::next to **Save**. For more shortcuts, see [Keyboard shortcuts to manage wiki pages](wiki-keyboard-shortcuts.md). +As you edit the page, save it by entering **Ctrl+S**. To save with a custom revision message, select :::image type="icon" source="../../media/icons/context-menu.png" border="false":::next to **Save**. For more shortcuts, see [Keyboard shortcuts to manage wiki pages](../navigation/keyboard-shortcuts.md). > [!div class="mx-imgBorder"] > ![Save page with a custom message](media/wiki/wiki-save-with-message.png) @@ -46,34 +36,36 @@ As you edit the page, save it by entering **Ctrl+S**. To save with a custom revi | Commands | Description | |---------|---------| | [az devops wiki show](#open-wiki) | Open a wiki | -| [az devops wiki page show](#view-a-wiki-page) | Get the content of a page or open a page | +| [az devops wiki page show](/cli/azure/devops/wiki/page#az-devops-wiki-page-show)| Get the content of a page or open a page | | [az devops wiki page create](#add-a-wiki-page) | Add a new page | | [az devops wiki page update](#edit-wiki-page) | Edit a page | | [az devops wiki page delete](#delete-wiki-page) | Delete a page | ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!NOTE] > To add or edit pages to a wiki that you've published from a Git repository, see [Publish a Git repository to a wiki](publish-repo-to-wiki.md). This article addresses how to add and edit pages of a wiki that you've provisioned for a team project. ::: moniker-end - ## Prerequisites -* You must have a provisioned wiki. If your wiki hasn't yet been created, [create it now](wiki-create-repo.md). -* You must be a member of the team project as a contributor to add or update wiki pages. -* You must have Basic access level to edit the project wiki. +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of the project where the wiki's located. If you don't have access, request it from your project administrator. | +| **Permissions** | Member of the **Contributors** group. | +| **Access levels** | At least **Basic** access. | +| **Tasks** | Complete [provisioned wiki](wiki-create-repo.md).| [!INCLUDE [temp](includes/open-wiki-hub.md)] - + ## Add a wiki page @@ -84,9 +76,9 @@ To add another page, choose **New page**. Or, to add a subpage, open the context Specify a unique title of 235 characters or less. Page titles are case-sensitive. For other title restrictions, see [Wiki Git repository files and file structure, File naming conventions](wiki-file-structure.md#file-naming-conventions). > [!div class="mx-imgBorder"] -> ![Create wiki and first page](media/wiki/add-new-page.png) +> ![Screenshot of first wiki page.](media/wiki/add-new-page.png) -You can also use keyboard shortcuts to add a new page by pressing **n** or add a subpage by pressing **c**. For a complete list of keyboard shortcuts, see [Keyboard shortcuts to manage wiki pages](wiki-keyboard-shortcuts.md). +You can also use keyboard shortcuts to add a new page by pressing **n** or add a subpage by pressing **c**. For a complete list of keyboard shortcuts, see [Keyboard shortcuts to manage wiki pages](../navigation/keyboard-shortcuts.md#wiki-keyboard-shortcuts). #### [Azure DevOps CLI](#tab/azure-devops-cli) @@ -111,15 +103,11 @@ az devops wiki page create --path - **--path**: Required. Path of the wiki page. - **--wiki**: Required. Name or ID of the wiki. - **--comment**: Optional. Comment in the commit message of the file add operation. Default value: Added a new page using Azure DevOps CLI. -- **--content**: Optional. Content of the wiki page. Ignored if --file-path is specified. -- **--encoding**: Optional. Encoding of the file. Used with --file-path parameter. -accepted values: ascii, utf-16be, utf-16le, utf-8 +- **--content**: Optional. Content of the wiki page. Ignored if `--file-path` is specified. +- **--encoding**: Optional. Encoding of the file. Used with `--file-path` parameter. +accepted values: `ascii`, `utf-16be`, `utf-16le`, `utf-8` - **--file-path**: Optional. Path of the file input if the content is specified in the file. -- **--project -p**: Required if not configured as default or picked up via git config. Name or ID of the project. You can configure the default project using the az devops configure -d project=NAME_OR_ID. - -::: moniker-end -[!INCLUDE [temp](../../includes/note-cli-supported-server.md)] -::: moniker range="azure-devops" +- **--project -p**: Required if not configured as default or picked up via git config. Name or ID of the project. You can configure the default project using the az devops configure `-d project=NAME_OR_ID`. ### Examples @@ -141,7 +129,6 @@ az devops wiki page update --path 'my page' --wiki myprojectwiki --file-path a.t [!INCLUDE [note-cli-not-supported](../../includes/note-cli-not-supported.md)] - * * * @@ -154,24 +141,23 @@ az devops wiki page update --path 'my page' --wiki myprojectwiki --file-path a.t #### [Browser](#tab/browser) -To edit an existing wiki page, open the page and select **Edit**, or open the context menu and select **Edit**. You can also use keyboard shortcut **e** to go to the edit of the current page quickly. +To edit an existing wiki page, open the page and select **Edit**, or open the context menu and select **Edit**. You can also use keyboard shortcut **e** to go to the edit of the current page quickly. For more information about specific editing functions, see [Use Markdown guidance](markdown-guidance.md). ::: moniker range="> azure-devops-2020" For code wikis, you can edit a page in the side-by-side editor, using the markdown toolbar to create your content. This experience is identical to the process in a project wiki. You can also edit wiki pages in the Repos hub also by using the option, **Edit in Repos**. > [!div class="mx-imgBorder"] -> ![Edit wiki page.](media/wiki/edit-in-repos.png) +> ![Screenshot of Edit wiki page.](media/wiki/edit-in-repos.png) -> [!NOTE] -> If you have branch policies in your code wiki, use **Edit in Repos** to create a branch and continue editing. +Select **Edit in Repos** to create a branch and continue editing. The **Edit in Repos** button is available only for code wikis that have branch policies enabled. If you don't see the button, it might be because your wiki isn't a code wiki or branch policies aren't enabled. For more information on branch policies, see [Branch policies and settings](../../repos/git/branch-policies.md). ::: moniker-end To delete a page, open the context menu from the tree or the one inside the page and select **Delete**. Confirm the delete in the dialog that opens. > [!NOTE] -> Deleting a page deletes the page along with all the metadata and all its subpages (if any) in the hierarchy. +> When you delete a wiki page, you also delete all its metadata and any subpages within its hierarchy. #### [Azure DevOps CLI](#tab/azure-devops-cli) @@ -203,11 +189,6 @@ az devops wiki page update --path - **--project -p**: Optional. Name or ID of the project. - **--subscription**: Optional. Name or ID of subscription. You can configure the default subscription using `az account set -s NAME_OR_ID`. -::: moniker-end -[!INCLUDE [temp](../../includes/note-cli-supported-server.md)] -::: moniker range="azure-devops" - - ### Examples Update content of the page with path 'my page' in a wiki named 'myprojectwiki' with inline content. @@ -248,11 +229,9 @@ az devops wiki page delete --path - **--subscription**: Optional. Name or ID of subscription. You can configure the default subscription using `az account set -s NAME_OR_ID`. - **--yes -y**: Optional. Don't prompt for confirmation. -[!INCLUDE [note-cli-not-supported](../../includes/note-cli-not-supported.md)] - ### Example -Delete a wiki page with the path 'my wiki' in a wiki named 'myprojectwiki'. +Delete a wiki page with the path 'my wiki' in a wiki named 'myprojectwiki.' > [!div class="tabbedCodeSnippets"] ```azurecli @@ -263,7 +242,6 @@ az devops wiki page delete --path 'my wiki' --wiki 'myprojectwiki' [!INCLUDE [note-cli-not-supported](../../includes/note-cli-not-supported.md)] - * * * ## Reorder a wiki page @@ -274,15 +252,39 @@ You can reorder pages within the wiki tree view to have pages appear in the orde * Change the order of the page within the hierarchy. > [!NOTE] -> Moving a page in the hierarchy may break links to it from other pages. You can always fix the links manually after you move. Reordering a page within a hierarchy has no impact on page links. +> Moving a page in the hierarchy might break links from other pages. You can manually fix these links after moving the page. Reordering a page within the hierarchy does not affect page links. + +### Manually fix a broken link after moving a page + +To manually fix a broken link after moving a page in the hierarchy, follow these steps: + +1. **Identify broken links:** + - Go to the pages that originally linked to the moved page. + - Look for broken links, which might appear as errors or missing content. +2. **Edit the linking page:** Open the page with the broken link in edit mode. +3. **Update the link:** + - Locate the broken link in the content. + - Update the link to point to the new location of the moved page, which typically involves changing the URL or path in the link. +4. **Save changes:** Save the changes to the page to apply the updated link. +5. **Verify the fix:** Go to the updated link to ensure it correctly points to the moved page. + +### Example + +If you moved a page from `/docs/old-path/page.md` to `/docs/new-path/page.md`, you'd do the following steps: + +1. Find the broken link in the content, such as `Link to Page`. +2. Edit the link to the new path: `Link to Page`. +3. Save the changes and verify that the link now correctly points to the new location. + +### Use keyboard shortcuts to reorder pages You can also use keyboard shortcuts to reorder pages. Select a page and press **CTRL + UP ARROW** or **CTRL + DOWN ARROW** to change page orders. To change the parent-child relationship of a page, open its context menu and select **Move**. The **Move page** dialog opens. Select a parent page under which you can move the current page. > [!div class="mx-imgBorder"] -> ![Move wiki page in the hierarchy](media/wiki/wiki-move-page.png) +> ![Screenshot showing moving a wiki page in the hierarchy.](media/wiki/wiki-move-page.png) -For a complete list of keyboard shortcuts, see [Keyboard shortcuts to manage wiki pages](wiki-keyboard-shortcuts.md). +For a complete list of keyboard shortcuts, see [Keyboard shortcuts to manage wiki pages](../navigation/keyboard-shortcuts.md#wiki-keyboard-shortcuts). ## Make a page the wiki home page @@ -292,3 +294,10 @@ By default, the first page you add when you create a wiki is set as the wiki hom > [!div class="nextstepaction"] > [View wiki page history and revert](wiki-view-history.md) + +## Related articles + +- [Follow a wiki page and receive notifications](follow-notifications-wiki-pages.md) +- [Compare provisioned vs. published wiki](provisioned-vs-published-wiki.md) +- [Update a wiki offline](wiki-update-offline.md) +- [Use wiki Markdown guidance](markdown-guidance.md) diff --git a/docs/project/wiki/create-embed-wit-from-wiki.md b/docs/project/wiki/create-embed-wit-from-wiki.md index a134583822d..6ab618e63ce 100644 --- a/docs/project/wiki/create-embed-wit-from-wiki.md +++ b/docs/project/wiki/create-embed-wit-from-wiki.md @@ -8,9 +8,9 @@ ms.assetid: ms.author: chcomley author: chcomley ms.reviewer: anian -ms.topic: conceptual +ms.topic: how-to monikerRange: '>= azure-devops-2020' -ms.date: 06/29/2022 +ms.date: 01/05/2024 --- # Create and embed a work item from wiki @@ -19,26 +19,38 @@ ms.date: 06/29/2022 Create and embed work items in your wiki page content. This feature gives you an easy way to promote text to a link to a feature, task, or user story. +## Prerequisites + +[!INCLUDE [wiki-prerequisites](includes/wiki-prerequisites.md)] + ## Create and embed work item -1. Sign in to your organization (`https://dev.azure.com/{yourorganization}`), and then select your **project**. +1. Sign in to your project (`https://dev.azure.com/{Your_Organization/Your_Project}`). - ![Screenshot of sign-in to Azure DevOps, and then select Project.](media/wiki/sign-in-to-azure-devops-select-project.png) + ![Screenshot of sign-in to Azure DevOps, and selected project.](media/wiki/sign-in-to-azure-devops-select-project.png) -2. Select your **wiki**. -3. Highlight the text, and then select the type of work item you want to create from the **New work item** dropdown menu. The work item form opens with the selected text added as the title and description of the work item. -4. Add information to the work item, such as entering an assignee in the Assign To box, and then select **Save & Close**. +2. Open your **wiki**. +3. Highlight the text, and then choose the type of work item you want to create from the **New work item** dropdown menu. The work item form opens with the selected text added as the title and description of the work item. +4. Add information to the work item, such as entering an assignee in the `Assign To` box, and then select **Save & Close**. ![Screenshot of create and embed work items from Wiki content.](media/wiki/create-embed-wit-from-wiki.gif) The selected content in the wiki page is replaced with the embedded work item. > [!NOTE] -> Only Markdown plain text (including bold and italics) are replaced in the wiki page. For the rest of the content like images, code blocks, and videos the work item is created, but the embed must be done manually. This is to prevent the page from breaking due to the replaced work item. For more information, see [how to link to work items from a Wiki page](wiki-markdown-guidance.md#link-to-work-items-from-a-wiki-page). +> Only Markdown plain text, including bold and italics, get replaced in the wiki page. For the rest of the content like images, code blocks, and videos, the work item gets created, but the embed must be done manually. This process is to prevent the page from breaking due to the replaced work item. For more information, see [Link to work items from a Wiki page](markdown-guidance.md#link-to-work-items-from-a-wiki-page). ## Show work item status The status, ID, and title of an embedded work item is shown in the wiki page. Work item references in pull request comments and Boards discussions also show the status. -![Work item status shown on wiki page](media/wiki/show-work-item-status-wiki.png) +![Screenshot of Work item status shown on wiki page.](media/wiki/show-work-item-status-wiki.png) + +## Related articles +- [Add and edit wiki pages](add-edit-wiki.md) +- [View wiki page history and revert](wiki-view-history.md) +- [Clone and update wiki content offline](wiki-update-offline.md) +- [Use wiki keyboard shortcuts](../navigation/keyboard-shortcuts.md#wiki-keyboard-shortcuts) +- [Filter or print wiki content](filter-print-wiki.md) 1 +- [Use Markdown syntax](markdown-guidance.md) diff --git a/docs/project/wiki/filter-print-wiki.md b/docs/project/wiki/filter-print-wiki.md index 374e19b4ece..78df4be2803 100644 --- a/docs/project/wiki/filter-print-wiki.md +++ b/docs/project/wiki/filter-print-wiki.md @@ -1,46 +1,49 @@ --- title: Filter a wiki TOC or print a wiki page titleSuffix: Azure DevOps -description: Filter the contents of a wiki TOC or print a wiki page in Azure DevOps +description: Filter the contents of a wiki table of content or print a wiki page. ms.subservice: azure-devops-wiki ms.custom: wiki, devdivchpfy22 ms.topic: conceptual -ms.assetid: ms.author: chcomley author: chcomley ms.reviewer: gopinach monikerRange: '<= azure-devops' -ms.date: 06/13/2022 +ms.date: 01/05/2024 --- -# Filter the contents of a wiki or print a page +# Filter a wiki or print a page [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -To focus on a single page or several pages, use the *Filter pages* feature in the table of contents (TOC). Or, to find pages containing a phrase or keyword, you can use the [search function](../search/get-started-search.md). +Use the *Filter pages* feature in the table of contents (TOC) to focus on a single page or several pages. Or, [search](../search/get-started-search.md) to find pages containing a phrase or keyword. -To print a wiki page, you can select a page and then print it. +## Prerequisites + +[!INCLUDE [wiki-prerequisites](includes/wiki-prerequisites.md)] ## Filter wiki pages Enter a title, keyword, or character string into the **Filter pages by title** box to quickly find pages whose title contains the keyword. > [!div class="mx-imgBorder"] -> ![Filter page by title](media/wiki/filter-box.png) +> ![Screenshot of Filter page by title.](media/wiki/filter-box.png) ## Print a wiki page -The **Print page** menu option allows you to use your browser print function to send a page to a printer or save as a PDF. Currently, you can only print a single page at a time. +The **Print page** menu option allows you to use your browser print function to send a page to a printer or save as a PDF. You can only print a single page at a time. > [!div class="mx-imgBorder"] -> ![Print page](media/wiki/print-page.png) +> ![Screenshot of Printing a page action.](media/wiki/print-page.png) + +The print feature might not be available from the Firefox web browser. -::: moniker range="tfs-2018" -> [!NOTE] -> The **Print page** feature is supported on TFS 2018.2 or later versions.. -::: moniker-end +## Related articles -> [!NOTE] -> The print feature may not be available from the Firefox web browser. +- [Follow a wiki page and get notifications](follow-notifications-wiki-pages.md) +- [Provisioned vs. published wiki](provisioned-vs-published-wiki.md) +- [Update wiki offline](wiki-update-offline.md) +- [Wiki Markdown guidance](markdown-guidance.md) +- [Add or edit a wiki](add-edit-wiki.md) diff --git a/docs/project/wiki/follow-notifications-wiki-pages.md b/docs/project/wiki/follow-notifications-wiki-pages.md index 5096b873752..8221450c608 100644 --- a/docs/project/wiki/follow-notifications-wiki-pages.md +++ b/docs/project/wiki/follow-notifications-wiki-pages.md @@ -1,48 +1,59 @@ --- title: Follow wiki page, get notifications titleSuffix: Azure DevOps -description: Learn how to follow wiki pages and get notifications in Azure DevOps +description: Learn how to follow wiki pages and get notifications in Azure DevOps. ms.subservice: azure-devops-wiki ms.custom: wiki, devdivchpfy22 -ms.topic: conceptual +ms.topic: how-to ms.assetid: ms.author: chcomley author: chcomley ms.reviewer: gopinach +ai-usage: ai-assisted monikerRange: 'azure-devops' -ms.date: 06/13/2022 +ms.date: 10/03/2024 --- # Follow a wiki page, get notifications [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Follow a Wiki page and get notified by email whenever the page is edited, deleted, or renamed. +Follow a Wiki page to receive email notifications whenever the page is edited, deleted, or renamed. -Get immediate notifications for rename and delete. For edit notifications, you get a 30-minute digest email with all edits that occurred within that period. This digest prevents the emails from spamming your inbox. +You receive immediate notifications for renames and deletions. For edits, you receive a 30-minute digest email that includes all edits made within that period. This digest helps prevent your inbox from being spammed with individual edit notifications. - ![Screenshot showing how to follow a page.](media/wiki/follow-wiki-page.png) +## Prerequisites -When you create a page, you become a default follower of the page. You can unfollow the page in the following two ways: +[!INCLUDE [wiki-prerequisites](includes/wiki-prerequisites.md)] -* From within the UI +## Follow a wiki page - ![Select unfollow](media/wiki/unfollow-button.png) +To follow a Wiki page, select the **Follow** button on the page you want to track. You can manage your notification settings in your user profile to ensure you receive updates as needed. -* From within the footer of your email notification + ![Screenshot showing the follow button.](media/wiki/follow-wiki-page.png) - ![Unfollow wiki page from your email notification](media/wiki/unfollow-wiki-page.png) +When you create a page, you become a default follower of the page. -To reduce noise, you don’t get notified for pages that you follow when the action is performed by you. +## Unfollow a wiki page + +You can unfollow a wiki page in the following ways: + +- **UI:** Select the **Unfollow** button on the page. + + ![Screenshot showing selected unfollow button.](media/wiki/unfollow-button.png) + +- **Footer of your email notification:** Select the **Unfollow** link in your email notification. + + ![Screenshot showing Unfollow wiki page from your email notification.](media/wiki/unfollow-wiki-page.png) > [!NOTE] -> When a page is deleted, all followers are removed. +> When a user deletes a page, all followers get removed. ## Related articles - [Create a wiki for your team project](wiki-create-repo.md) -- [Wiki Git repository files and file structure](wiki-file-structure.md) -- [Clone an existing Git repo](../../repos/git/clone.md) -- [Share code with push](../../repos/git/pushing.md) +- [Learn about wiki Git repository files and file structure](wiki-file-structure.md) +- [Make a clone of an existing Git repo](../../repos/git/clone.md) +- [Learn how to share code with push](../../repos/git/pushing.md) - [Manage README and Wiki permissions](manage-readme-wiki-permissions.md) -- [Syntax guidance for Markdown files, widgets, wikis, and pull request comments](./markdown-guidance.md) \ No newline at end of file +- [Follow syntax guidance for Markdown files, widgets, wikis, and pull request comments](./markdown-guidance.md) diff --git a/docs/project/wiki/includes/open-wiki-hub.md b/docs/project/wiki/includes/open-wiki-hub.md index 6d20e9924f2..4a08972b449 100644 --- a/docs/project/wiki/includes/open-wiki-hub.md +++ b/docs/project/wiki/includes/open-wiki-hub.md @@ -4,6 +4,8 @@ ms.topic: include ## Open the Wiki +You can open and view a wiki page for your project. + #### [Browser](#tab/browser) Connect to your project using a [supported web browser](/azure/devops/server/compatibility#supported-browsers) and choose **Wiki**. @@ -33,10 +35,6 @@ az devops wiki show --wiki - **--project -p**: Optional. Name or ID of the project. - **--subscription**: Optional. Name or ID of subscription. You can configure the default subscription using `az account set -s NAME_OR_ID`. -::: moniker-end - -::: moniker range="azure-devops" - ### Example Open a wiki named 'myprojectwiki'. @@ -81,6 +79,6 @@ az devops wiki page show --path 'my wiki' --wiki 'myprojectwiki' --content "Hell ::: moniker-end - +[!INCLUDE [temp](../../../includes/note-cli-not-supported.md)] * * * diff --git a/docs/project/wiki/includes/wiki-naming-conventions.md b/docs/project/wiki/includes/wiki-naming-conventions.md index 5063b8ba6e7..19f0a8c6358 100644 --- a/docs/project/wiki/includes/wiki-naming-conventions.md +++ b/docs/project/wiki/includes/wiki-naming-conventions.md @@ -4,7 +4,7 @@ ms.topic: include Each wiki page corresponds to a file within the wiki Git repo. Names you assign to a wiki page title must conform to the following restrictions. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" |Restriction type| Restriction| |---------------|-----------| @@ -32,15 +32,3 @@ You can specify page titles which contain one or more of these special character ::: moniker-end -::: moniker range="tfs-2018" - -> [!div class="mx-tdCol2BreakAll"] -> |Restriction type| Restriction| -> |---------------|-----------| -> | File name | The fully qualified page path shouldn't exceed 235 characters. | -> | Uniqueness | Page titles are case sensitive and must be unique within the wiki hierarchy.| -> |Special characters| - Must not contain any Unicode control characters or surrogate characters.
      - Must not contain the following printable characters: `/ \ : < > * ? | - #`.
      - Must not start or end with a period `.`.
      - Titles of pages added offline must not contain a blank space.| -> | File size | Must not exceed the maximum of 18 MB. | -> | Attachment file size | Must not exceed the maximum of 19 MB. | - -::: moniker-end diff --git a/docs/project/wiki/includes/wiki-prereqs-create-repository.md b/docs/project/wiki/includes/wiki-prereqs-create-repository.md new file mode 100644 index 00000000000..48cab3f77d3 --- /dev/null +++ b/docs/project/wiki/includes/wiki-prereqs-create-repository.md @@ -0,0 +1,10 @@ +--- +ms.topic: include +--- + + +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of the project where the wiki is located. If you don't have access, request it from your project administrator. Anyone with access to the team project, including [Stakeholders](../../../organizations/security/get-started-stakeholder.md), can view the wiki. | +| **Permissions** | - To add or edit wiki pages: Member of the **Contributors** group.
      - To publish code as wiki: **Create Repository** permission. By default, this permission is set for members of the [Project Administrators group](../../../repos/git/set-git-repository-permissions.md).| +| **Access levels** | At least **Basic** access. | diff --git a/docs/project/wiki/includes/wiki-prerequisites.md b/docs/project/wiki/includes/wiki-prerequisites.md new file mode 100644 index 00000000000..14bac186388 --- /dev/null +++ b/docs/project/wiki/includes/wiki-prerequisites.md @@ -0,0 +1,9 @@ +--- +ms.topic: include +--- + +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of the project where the wiki's located. If you don't have access, request it from your project administrator. | +| **Permissions** | Member of the **Contributors** group. | +| **Access levels** | At least **Basic** access. | diff --git a/docs/project/wiki/manage-readme-wiki-permissions.md b/docs/project/wiki/manage-readme-wiki-permissions.md index 5458f109f86..60c58aa1976 100644 --- a/docs/project/wiki/manage-readme-wiki-permissions.md +++ b/docs/project/wiki/manage-readme-wiki-permissions.md @@ -5,65 +5,76 @@ description: Learn how to set permissions to grant or secure access to README fi ms.subservice: azure-devops-wiki ms.custom: wiki, devdivchpfy22 ms.topic: conceptual -ms.assetid: ms.author: chcomley author: chcomley ms.reviewer: gopinach -ms.date: 06/21/2022 -monikerRange: '>= tfs-2018' +ai-usage: ai-assisted +ms.date: 09/06/2024 +monikerRange: "<=azure-devops" --- -# Manage Wiki permissions +# Manage wiki permissions [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Learn about managing permissions for your wiki. By default, all members of the Contributors group can edit Wiki pages. +In this article, learn about managing permissions for your wiki. By default, all members of the Contributors group can edit wiki pages. - +## Manage permissions for wikis -## Manage wiki permissions +By default, all project contributors have "read" and "edit" access to the wiki repository. You can manage these permissions to control who can read and edit wiki pages. For more information, see [Get started with permissions, access, and security groups](../../organizations/security/about-permissions.md). -By default, all project contributors have read and edit access of the wiki repository. You can grant or restrict access to who can read and edit wiki pages by managing the wiki repository permissions. For more information about permissions in Azure DevOps, see [Get started with permissions, access, and security groups](../../organizations/security/about-permissions.md). +1. Sign in to your project (```https://dev.azure.com/{Your_Organization/Your_Project}```). +2. Select **Wiki** > :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More actions** > **Wiki security**. -::: moniker range="tfs-2018" -> [!NOTE] -> **Feature availability**: The built-in wiki is available with TFS 2018 and later versions. -::: moniker-end +> [!div class="mx-imgBorder"] +> ![Screenshot of Wiki, Choose More, select security.](media/wiki/wiki-open-security.png) -To open the Security dialog, choose **More actions** > **Wiki security**. +For definitions of each repository permission, see [Git repository permissions](../../organizations/security/permissions.md). -> [!div class="mx-imgBorder"] -> ![Wiki, Choose More, select security](media/wiki/wiki-open-security.png) +:::image type="content" source="media/wiki/security-dialog.png" alt-text="Screenshot of Wiki security dialog."::: + +If you don't have access to create a wiki page, contact an Administrator, who can grant you adequate permission on the underlying Git repository of the wiki. + +## Grant Edit permissions to an individual or group -For definitions of each repository permission, see [Git repository permissions](../../organizations/security/permissions.md#git-repository). +To grant *Edit* permissions to an individual or group, do the following steps. -:::image type="content" source="media/wiki/security-dialog.png" alt-text="Wiki security dialog/"::: +1. Sign in to your project (```https://dev.azure.com/{Your_Organization/Your_Project}```). +2. Select **Wiki** > :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More actions** > **Wiki security**. -## Don't have access to create a page? + > [!div class="mx-imgBorder"] + > ![Screenshot of Wiki, Choose More, select security.](media/wiki/wiki-open-security.png) -If you don't have access to create a wiki page, you need to contact an administrator to grant you adequate permission on the underlying Git repository of the wiki. +1. Select **Add**. If this button isn't available, check your [permissions](../../organizations/security/about-permissions.md). +2. Enter the name of the user or group you want to grant permissions to and select the user or group from the search results. + After you add the user or group, they're listed in the Wiki security pane. +3. To grant *Edit* permissions, set the **Contribute permission** to **Allow**. +4. **Save** the changes. + +### Other considerations + +- Ensure that the user or group has the necessary access level to the Azure DevOps project. +- Review and adjust other permissions as needed to maintain security and proper access control, such as *Read*, *Delete*, and *Manage*. ## Stakeholder wiki access -### Private projects +**Private projects** -Users with [Stakeholder access](../../organizations/security/get-started-stakeholder.md) in a private project can read [**provisioned**](provisioned-vs-published-wiki.md) wiki pages and view revisions, however they can't do any edit operations. For example, Stakeholders can't create, edit, reorder, or revert changes to project wiki pages. These permissions can't be changed. +Users with [Stakeholder access](../../organizations/security/get-started-stakeholder.md) in a private project can read [**provisioned**](provisioned-vs-published-wiki.md) wiki pages and view revisions, but they can't edit them. For example, Stakeholders can't create, edit, reorder, or revert changes to project wiki pages. These permissions can't be changed. -Stakeholders have zero access to read or edit [**published code**](provisioned-vs-published-wiki.md) wiki pages in private projects. For more information, see the [Stakeholder access quick reference for project and code wikis](../../organizations/security/stakeholder-access.md#public-versus-private-feature-access). +Stakeholders have no access to read or edit [**published code**](provisioned-vs-published-wiki.md) wiki pages in private projects. For more information, see the [Stakeholder access quick reference for project and code wikis](../../organizations/security/stakeholder-access.md#public-versus-private-feature-access). -### Public projects +**Public projects** Stakeholders have full access to wikis in public projects. For more information about Stakeholder access, see [About access levels, Stakeholder access, Public versus private feature access](../../organizations/security/stakeholder-access.md#public-versus-private-feature-access). -## FAQ - -### Q: Is it possible to grant permissions on a per-page basis? - -**A:** No, permissions to access the wiki are made for all pages and not individual pages. +> [!NOTE] +> You can set permissions for the entire wiki, but not for individual pages. ## Related articles -- [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) +- [Learn default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) - [Get Started with Git](../../repos/git/gitquickstart.md) +- [Learn about Azure DevOps security](../../organizations/security/about-security-identity.md) diff --git a/docs/project/wiki/manage-wikis.md b/docs/project/wiki/manage-wikis.md index 6c4199c0f92..21b5bc23d3b 100644 --- a/docs/project/wiki/manage-wikis.md +++ b/docs/project/wiki/manage-wikis.md @@ -9,7 +9,7 @@ ms.assetid: ms.author: chcomley author: chcomley ms.reviewer: sancha -ms.date: 06/07/2021 +ms.date: 01/05/2024 monikerRange: 'azure-devops' --- @@ -22,6 +22,10 @@ Learn the following CLI commands for managing wikis. > [!NOTE] > You can't delete project wikis with the CLI. +## Prerequisites + +[!INCLUDE [wiki-prerequisites](includes/wiki-prerequisites.md)] + ## Commands |Commands |description | @@ -52,12 +56,12 @@ az devops wiki create [--mapped-path] ### Optional parameters -- **--mapped-path**: [Required for codewiki type] Mapped path of the new wiki, for example, '/' to publish from root of repository. ---name: Name of the new wiki. -- **--project -p**: Optional. Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up via git config. -- **--repository -r**: [Required for codewiki type] Name or ID of the repository to publish the wiki from. -- **--subscription**: Optional. Name or ID of subscription. You can configure the default subscription using `az account set -s NAME_OR_ID`. -- **--type --wiki-type**: Type of wiki to create. Accepted values: codewiki, projectwiki. Default value: projectwiki. +- **--mapped-path**: [Required for `codewiki` type] Mapped path of the new wiki, for example, `/` to publish from root of repository. +- **--name**: Name of the new wiki. +- **--project -p**: Optional. Name or ID of the project. Configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up via git config. +- **--repository -r**: [Required for `codewiki` type] Name or ID of the repository to publish the wiki from. +- **--subscription**: Optional. Name or ID of subscription. Configure the default subscription using `az account set -s NAME_OR_ID`. +- **--type --wiki-type**: Type of wiki to create. Accepted values: `codewiki`, `projectwiki`. Default value: `projectwiki`. ### Examples @@ -81,7 +85,7 @@ az devops wiki create --name WIKI_NAME --type codewiki To delete a wiki, enter the `az devops wiki delete` command. > [!NOTE] -> You can use this command only to delete a code wiki. You can't use the command to delete a project wiki. +> You can only use this command only to delete a code wiki, not to delete a project wiki. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -95,7 +99,7 @@ az devops wiki delete ### Parameters - **--wiki**: Required. Name or ID of the wiki to delete. -- **--project -p**: Optional. Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up via git config. +- **--project -p**: Optional. Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up via git config. - **--subscription**: Optional. Name or ID of subscription. You can configure the default subscription using `az account set -s NAME_OR_ID`. - **--yes -y**: Optional. Don't prompt for confirmation. @@ -123,7 +127,7 @@ az devops wiki list ### Optional parameters - **--project -p**: Optional. Name or ID of the project. -- **--scope**: Optional. List the wikis at project or organization level. Accepted values: organization, project. Default value: project. +- **--scope**: Optional. List the wikis at project or organization level. Accepted values: `organization`, `project`. Default value: `project`. - **--subscription**: Optional. Name or ID of subscription. You can configure the default subscription using `az account set -s NAME_OR_ID`. ### Examples @@ -159,11 +163,11 @@ az devops wiki show --wiki - **--wiki**: Required. Name or ID of the wiki. - **--open**: Optional. Open the wiki page in your web browser. - **--project -p**: Optional. Name or ID of the project. -- **--subscription**: Optional. Name or ID of subscription. You can configure the default subscription using `az account set -s NAME_OR_ID`. +- **--subscription**: Optional. Name or ID of subscription. Configure the default subscription using `az account set -s NAME_OR_ID`. ### Example -Show the wiki named 'myprojectwiki' and open the wiki page in your web browser. +Show the wiki named `myprojectwiki` and open the wiki page in your web browser. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -190,16 +194,16 @@ az devops wiki page create --path - **--path**: Required. Path of the wiki page. - **--wiki**: Required. Name or ID of the wiki. -- **--comment**: Optional. Comment in the commit message of file add operation. Default value: Added a new page using Azure DevOps CLI. -- **--content**: Optional. Content of the wiki page. Ignored if --file-path is specified. -- **--encoding**: Optional. Encoding of the file. Used with --file-path parameter. +- **--comment**: Optional. Comment in the commit message of file add operation. Default value: `added a new page using Azure DevOps CLI`. +- **--content**: Optional. Content of the wiki page. Ignored if `--file-path` is specified. +- **--encoding**: Optional. Encoding of the file. Used with `--file-path` parameter. - **--file-path**: Optional. Path of the file input if content is specified in the file. - **--project -p**: Optional. Name or ID of the project. -- **--subscription**: Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID. +- **--subscription**: Name or ID of subscription. You can configure the default subscription using `az account set -s NAME_OR_ID`. ### Examples -Create a new page with path 'my page' in a wiki named 'myprojectwiki' with inline content. +Create a new page with path `my page` in a wiki named `myprojectwiki` with inline content. > [!div class="tabbedCodeSnippets"] ```azurecli @@ -212,8 +216,3 @@ Create a new page with path 'my page' in a wiki named 'myprojectwiki' with conte ```azurecli az devops wiki page create --path 'my page' --wiki myprojectwiki --file-path a.txt --encoding utf-8 ``` - - - - - diff --git a/docs/project/wiki/markdown-guidance.md b/docs/project/wiki/markdown-guidance.md index 056af991990..e72915b9d81 100644 --- a/docs/project/wiki/markdown-guidance.md +++ b/docs/project/wiki/markdown-guidance.md @@ -1,8 +1,8 @@ --- -title: Markdown syntax for files, widgets, and wikis +title: Markdown syntax for files, widgets, wikis titleSuffix: Azure DevOps ms.custom: wiki, devdivchpfy22 -description: Discover how to utilize Markdown to incorporate tables, mathematical symbols, and share information effectively in pull requests, README files, dashboards, and wikis. +description: Discover how to utilize Markdown to incorporate tables, mathematical symbols, and share information effectively in pull requests, README files, dashboards, and wikis in Azure DevOps. ms.subservice: azure-devops-wiki ms.assetid: 43D2156E-2E20-42B8-B816-43E95CB479C5 ms.author: chcomley @@ -10,59 +10,47 @@ author: chcomley ms.reviewer: gopinach ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 02/17/2023 +ms.date: 09/06/2024 --- -# Syntax guidance for basic Markdown usage +# Use Markdown in Azure DevOps [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-selector](../../includes/version-selector.md)] -Here you can find some basic Markdown syntax guidance and specific guidance for using Markdown in Azure DevOps features. You can use both common [Markdown conventions](https://daringfireball.net/projects/markdown/syntax) and [GitHub-flavored extensions](https://help.github.com/articles/github-flavored-markdown/). - -Having the right guidance at the right time is critical to success. Use [Markdown](https://en.wikipedia.org/wiki/Markdown) to add rich formatting, tables, and images to your project pages, README files, dashboards, and pull request comments. - -For more supported syntax for wiki pages, see [Wiki Markdown guidance](wiki-markdown-guidance.md). - -You can provide guidance in the following areas using Markdown: - -::: moniker range=">= azure-devops-2019" - -- [Project wiki](add-edit-wiki.md) -- [Publish code as wiki](publish-repo-to-wiki.md) -- [Markdown widget added to a dashboard](../../report/dashboards/add-markdown-to-dashboard.md) -- [Project page or Welcome pages](../../organizations/projects/project-vision-status.md) -- [Repository README files](../../repos/git/create-a-readme.md) -- [Pull request (PR) comments](../../repos/git/pull-requests.md) -- [Definition of Done (Kanban board)](../../boards/boards/add-columns.md#definition-of-done) - -::: moniker-end - -::: moniker range="tfs-2018" - -- [Project Wiki](add-edit-wiki.md) -- [Markdown widget added to a dashboard](../../report/dashboards/add-markdown-to-dashboard.md) -- [Project page or Welcome pages](../../organizations/projects/project-vision-status.md) -- [Repository README files](../../repos/git/create-a-readme.md) -- [Pull request (PR) comments](../../repos/git/pull-requests.md) -- [Definition of Done (Kanban board)](../../boards/boards/add-columns.md#definition-of-done) - -> [!NOTE] -> Rich Markdown rendering in code repositories is supported for TFS 2018.2 and later versions. You can create rich README.md files in the code repositories. The Markdown rendering of the MD files in code repositories supports HTML tags, block quotes, emojis, image resizing, and mathematical formulas. There is parity in Markdown rendering in Wiki and MD files in code. - -::: moniker-end - -> [!IMPORTANT] -> Not all Markdown syntax is supported across all features. Each section in this article identifies the features and the syntax supported with the **Supported in** line. +In this article, find basic syntax guidance for using Markdown in Azure DevOps features and [wiki Markdown](#use-markdown-in-wikis). You can use both common [Markdown conventions](https://daringfireball.net/projects/markdown/syntax) and [GitHub-flavored extensions](https://help.github.com/articles/github-flavored-markdown/). + +Use Markdown to add formatting, tables, images, and more to your project pages, README files, dashboards, pull requests, [wikis](#use-markdown-in-wikis), and so on. + +Not all Markdown syntax is supported across all features in Azure DevOps. The following table links to each basic syntax section in this article and highlights which features support it. + +|Markdown type |Supported features | +|---------|---------| +|[Headers](#headers) | Definition of Done (board), Markdown widget, pull request, README, wiki | +|[Paragraphs and line breaks](#paragraphs-and-line-breaks)| Definition of Done (board), Markdown widget, pull request, README files, wiki| +|[Blockquotes](#blockquotes) | [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), [pull request](../../repos/git/pull-requests.md), [README files](../../repos/git/create-a-readme.md), [wiki](add-edit-wiki.md) | +|[Horizontal rules](#horizontal-rules) |[Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), [pull request](../../repos/git/pull-requests.md), [README files](../../repos/git/create-a-readme.md), [wiki](add-edit-wiki.md) | +|[Emphasis](#emphasis-bold-italics-strikethrough) | [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), [pull request](../../repos/git/pull-requests.md), [README files](../../repos/git/create-a-readme.md), [wiki](add-edit-wiki.md) | +|[Code highlighting](#code-highlighting) | [pull request](../../repos/git/pull-requests.md), [README files](../../repos/git/create-a-readme.md), [wiki](add-edit-wiki.md) | +|[Suggest change](#suggest-change) | [pull request](../../repos/git/pull-requests.md) | +|[Tables](#tables) | [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), [pull request](../../repos/git/pull-requests.md), [README files](../../repos/git/create-a-readme.md), [wiki](add-edit-wiki.md) | +|[Lists](#lists) |[Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), [pull request](../../repos/git/pull-requests.md), [README files](../../repos/git/create-a-readme.md), [wiki](add-edit-wiki.md) | +|[Links](#links) |[Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), [pull request](../../repos/git/pull-requests.md), [README files](../../repos/git/create-a-readme.md), [wiki](add-edit-wiki.md) | +|[Images](#images) | [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), [pull request](../../repos/git/pull-requests.md), [README files](../../repos/git/create-a-readme.md), [wiki](add-edit-wiki.md) | +|[Checklist or task list](#checklist-or-task-list) | [pull request](../../repos/git/pull-requests.md), [wiki](add-edit-wiki.md) | +|[Emoji](#emoji) | [pull request](../../repos/git/pull-requests.md), [wiki](add-edit-wiki.md) | +|[Ignore or escape Markdown syntax](#ignore-or-escape-markdown-syntax-to-enter-specific-or-literal-characters) | [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), [pull request](../../repos/git/pull-requests.md), [README files](../../repos/git/create-a-readme.md), [wiki](add-edit-wiki.md) | +| [Attachments](#attachments) | [pull request](../../repos/git/pull-requests.md), [wiki](add-edit-wiki.md) | +| [Mathematical notation and characters](#mathematical-notation-and-characters)| [pull request](../../repos/git/pull-requests.md), [wiki](add-edit-wiki.md) | + +For more information, see [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), [pull request](../../repos/git/pull-requests.md), [README files](../../repos/git/create-a-readme.md), and [wiki](add-edit-wiki.md). ## Headers -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis - -Structure your comments using headers. Headers segment longer comments, making them easier to read. +Structure your content using headers. Headers segment longer content, making it easier to read. -Start a line with a hash character `#` to set a heading. Organize your remarks with subheadings by starting a line with more hash characters, for example, `####`. You can use up to six levels of headings. +To set a heading, start a line with a hash character `#`. Organize your remarks with subheadings by starting a line with more hash characters, for example, `####`. You can use up to six levels of headings. **Example:** ```markdown @@ -85,7 +73,7 @@ Make your text easier to read by breaking it into paragraphs or line breaks. ### Pull requests -In pull request comments, select **Enter** to insert a line break and begin text on a new line. +In pull request comments, select **Enter** to insert a line break, and begin text on a new line. **Example - pull request comment:** @@ -119,12 +107,7 @@ A space gets added in between paragraphs. ## Blockquotes -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis - -Quote previous comments or text to set the context for your comment or text. - -Quote single lines of text with `>` before the text. Use many `>` characters to nest quoted text. -Quote blocks of lines of text by using the same level of `>` across many lines. +Quote previous comments or text to set the context for your comment or text. Quote single lines of text with `>` before the text. Use many `>` characters to nest quoted text. Quote blocks of lines of text by using the same level of `>` across many lines. **Example:** @@ -137,12 +120,10 @@ Quote blocks of lines of text by using the same level of `>` across many lines. **Result:** -![Quoting in Markdown](media/markdown-guidance/markdown_quote2.jpg) +![Screenshot of Quoting in Markdown.](media/markdown-guidance/markdown_quote2.jpg) ## Horizontal rules -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis - To add a horizontal rule, add a line that's a series of dashes `---`. The line above the line containing the `---` must be blank. **Example:** @@ -176,20 +157,13 @@ You can emphasize text by applying bold, italics, or strikethrough to characters Combine these elements to apply emphasis to the text. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!NOTE] > There is no Markdown syntax that supports underlining text. Within a wiki page, you can use the HTML `` tag to generate underlined text. For example, `underlined text` yields underlined text. ::: moniker-end -::: moniker range="tfs-2018" - -> [!NOTE] -> There is no Markdown syntax that supports underlining text. Within a wiki page in TFS 2018.2 and later versions, you can use the HTML `` tag to generate underlined text. For example, `underlined text` yields underlined text. - -::: moniker-end - **Example:** 

      @@ -198,8 +172,6 @@ Use _emphasis_ in comments to express **strong** opinions and point out ~~correc
 **~~Bold, strike-through text~~**
      -
      - **Result:** Use _emphasis_ in comments to express **strong** opinions and point out corrections @@ -208,15 +180,11 @@ Use _emphasis_ in comments to express **strong** opinions and point out corre ## Code highlighting - -#### Supported in: Pull Requests | README files | Wikis - Highlight suggested code segments using code highlight blocks. -To indicate a span of code, wrap it with three backtick quotes (```) on a new line at both the start and end of the block. To indicate code inline, wrap it with one backtick quote (`). - -> [!NOTE] -> Code highlighting entered within the Markdown widget renders code as plain preformatted text. +To indicate a span of code, wrap it with three backtick quotes (```) on a new line at both the start and end of the +block. To indicate code inline, wrap it with one backtick quote (`). +Code highlighting entered within the Markdown widget renders code as plain preformatted text. **Example:** @@ -238,20 +206,20 @@ sudo npm install vsoagent-installer -g **Example:** 
      -To install the Microsoft Cross Platform Build & Release Agent, run the following: `$ sudo npm install vsoagent-installer -g`.
+```To install the Microsoft Cross Platform Build & Release Agent, run the following: `$ sudo npm install vsoagent-installer -g`.```

      **Result:** -To install the Microsoft Cross Platform Build & Release Agent, run the following command: `$ sudo npm install vsoagent-installer -g`. +```To install the Microsoft Cross Platform Build & Release Agent, run the following command: `$ sudo npm install vsoagent-installer -g`.```
      Within a Markdown file, text with four spaces at the beginning of the line automatically converts to a code block. -Set a language identifier for the code block to enable syntax highlighting for any of the supported languages in [highlightjs](https://github.com/highlightjs/highlight.js/tree/9.10.0/src/languages), version v9.10.0. +Set a language identifier for the code block to enable syntax highlighting for any of the supported languages in [highlightjs](https://github.com/highlightjs/highlight.js/tree/stable-11/src/languages). 
       ``` language
@@ -285,20 +253,37 @@ Console.WriteLine("Hello, World!");
 Console.WriteLine("Hello, World!");
 ```
 
-## Tables
+## Suggest change
+
+In pull requests, you can use comments to suggest replacement text for one or more lines in a file. 
+Users can easily apply the suggested change by selecting **Apply Change**. This action results in committing the change to the pull request.
+
+Code highlighting entered within the Markdown widget renders code in diff format with line prefixed by '-' and '+'.
+
+**Example:**
+
+
      +```suggestion
+  for i in range(A, B+100, C):
+```
+
      
 
-#### Supported in: Markdown widget | Pull Requests | README files | Wikis 
+:::image type="content" source="media/markdown-guidance/suggestion-snapshot.png" alt-text="Screenshot showing example of suggested changed in a pull request."::: 
+
+For more information, see [Suggest changes in comments](../../repos/git/review-pull-requests.md?tabs=browser#suggest-changes-in-comments).
+
+## Tables
 
 Organize structured data with tables. Tables are especially useful for describing function parameters, object methods, and other data with a
-clear name to description mapping. You can format tables in pull requests, wiki, and Markdown files such as README files and Markdown widgets.  
+clear name to description mapping.
 
 - Place each table row on its own line.
 - Separate table cells using the pipe character `|`.
-- To use a pipe character within a table you must escape with a backslash `\|`.
+- To use a pipe character within a table, you must escape with a backslash `\|`.
 - The first two lines of a table set the column headers and the alignment of elements in the table.
 - Use colons (`:`) when dividing the header and body of tables to specify column alignment (left, center, right).
 - To start a new line, use the HTML break tag (`
      `) (works within a Wiki but not elsewhere).  
-- Make sure to end each row with a CR or LF.
+- Make sure to end each row with a carriage return (CR) or line feed (LF).
 - You must enter a blank space before and after work item or pull request (PR) mentioned inside a table cell.
 
 **Example:**
@@ -310,7 +295,6 @@ clear name to description mapping. You can format tables in pull requests, wiki,
 | Cell B1 | Cell B2 | Cell B3
      second line of text |  
 ```
 
-
 **Result:**  
 
 | Heading 1 | Heading 2 | Heading 3 |  
@@ -320,12 +304,9 @@ clear name to description mapping. You can format tables in pull requests, wiki,
 
 ## Lists
 
-#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis  
-
-
-Organize related items with lists. You can add ordered lists with numbers or unordered lists with just bullets.
+Use lists to organize related items. You can add ordered lists with numbers or unordered lists with just bullets. Ordered lists start with a number followed by a period for each list item. Unordered lists start with a `-`. 
 
-Ordered lists start with a number followed by a period for each list item. Unordered lists start with a `-`. Begin each list item on a new line. In a Markdown file or widget, enter two spaces before the line break to begin a new paragraph or enter two line breaks consecutively to begin a new paragraph.
+Begin each list item on a new line. In a Markdown file or widget, enter two spaces before the line break to begin a new paragraph or enter two line breaks consecutively to begin a new paragraph.
 
 ### Ordered or numbered lists
 
@@ -388,16 +369,13 @@ Ordered lists start with a number followed by a period for each list item. Unord
     - Nested item 2
     - Nested item 3
 
-
-
+
 
 ## Links
 
-#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis  
-
-In pull request comments and wikis, HTTP and HTTPS URLs automatically format as links. You can link to work items by entering the *#* key and a work item ID and then choosing the work item from the list.
+In pull request comments and wikis, HTTP and HTTPS URLs automatically format as links. You can link to work items by entering the `#` key and a work item ID and then choosing the work item from the list.
 
-Avoid auto suggestions for work items by prefixing *#* with a backslash (`\`). This action can be useful if you want to use *#* for color hex codes.
+Avoid auto suggestions for work items by prefixing `#` with a backslash (`\`). This action can be useful if you want to use `#` for color hex codes.
 
 In Markdown files and widgets, you can set text hyperlinks for your URL using the standard Markdown link syntax:
 
@@ -405,7 +383,7 @@ In Markdown files and widgets, you can set text hyperlinks for your URL using th
 [Link Text](Link URL)
 ```
 
-When you're linking to another Markdown page in the same Git or TFVC repository, the link target can be a relative path or an absolute path in the repository.  
+When you link to another Markdown page in the same Git or Team Foundation Version Control (TFVC) repository, the link target can be a relative path or an absolute path in the repository.  
 
 **Supported links for Welcome pages:**
 
@@ -416,20 +394,16 @@ When you're linking to another Markdown page in the same Git or TFVC repository,
 
 **Supported links for Markdown widget:**
 
-
        
-
      • URL: [text to display](http://address.com)  
        • 
-
      
+- URL: `[text to display](http://address.com)`
 
 **Supported links for Wiki:**  
-
        
-
      • Absolute path of Wiki pages: [text to display](/parent-page/child-page) 
        • 
-
      • URL: [text to display](http://address.com)  
        • 
-
      
+
+- Absolute path of Wiki pages: `[text to display](/parent-page/child-page)`
+- URL: `[text to display](http://address.com)`
 
 > [!NOTE]  
-> Links to documents on file shares using `file://` aren't supported on 2017.1 and later versions. This restriction has been implemented for security purposes.
->
-> For information on how to specify relative links from a Welcome page or Markdown widget, see [Source control relative links](#source-control-relative-links).
+> - Links to documents on file shares using `file://` aren't supported for security purposes.
+> - For information on how to specify relative links from a Welcome page or Markdown widget, see [Source control relative links](#source-control-relative-links).
 
 **Example:**  
 
@@ -447,8 +421,8 @@ When you're linking to another Markdown page in the same Git or TFVC repository,
 
 Links to source control files get interpreted differently depending on whether you specify them in a Welcome page or a Markdown widget. The system interprets relative links as follows:
 
-- **Welcome page:** relative to the root of the source control repository in which the welcome page exists
-- **Markdown widget:**  relative to the team project collection URL base
+- **Welcome page:** Relative to the root of the source control repository in which the welcome page exists
+- **Markdown widget:** Relative to the team project collection URL base
 
 For example:
 
@@ -459,10 +433,10 @@ For example:
 
 ### Anchor links
 
-Within Markdown files, anchor IDs are assigned to all headings when rendered as HTML. The ID is the heading text, with the spaces replaced by dashes (-) and all lower case. In general, the following conventions apply:
+Within Markdown files, anchor IDs get assigned to all headings when rendered as HTML. Anchor links also support special characters. The ID is the heading text, with the spaces replaced by dashes (-) and all lower case. The following conventions apply to anchor links:
 
 - Punctuation marks and leading white spaces within a file name are ignored
-- Upper case letters convert to lower case letter
+- Upper case letters convert to lower case letters
 - Spaces between letters convert to dashes (-)
 
 **Example:**
@@ -473,7 +447,6 @@ Within Markdown files, anchor IDs are assigned to all headings when rendered as
 
 
      
 
-
 **Result:**
 
 The syntax for an anchor link to a section...
@@ -482,7 +455,7 @@ The syntax for an anchor link to a section...
 [Link to a heading in the page](#link-to-a-heading-in-the-page)

      -The ID is all lower case, and the link is case-sensitive, so be sure to use lower case, even though the heading itself uses upper case. +The ID is all lower case, and the link is case-sensitive, so be sure to use lower case, even though the heading uses upper case. You can also reference headings within another Markdown file: @@ -501,9 +474,7 @@ In wiki, you can also reference heading in another page: ## Images -#### Supported in: Markdown widget | Pull Requests | README files | Wikis - -To highlight issues or make things more interesting, you can add images and animated GIFs to the following aspects of your pull requests: +To highlight issues or make things more interesting, you can add images and animated GIFs to the following aspects of your pull requests. - Comments - Markdown files @@ -536,21 +507,19 @@ The path to the image file can be a relative path or the absolute path in Git or ## Checklist or task list -#### Supported in: Pull Requests | Wikis - Lightweight task lists are great ways to track progress on your to-dos as a pull request creator or reviewer in the PR description or in a wiki page. Select the Markdown toolbar to get started or apply the format to the selected text. -You can Use `[ ]` or `[x]` to support checklists. Precede the checklist with either `-` or `1.` (any numeral). +Use `[ ]` or `[x]` to support checklists. Precede the checklist with either `-` or `1.` (any numeral). **Example - Apply the task list Markdown to a highlighted list** > [!div class="mx-imgBorder"] -> ![Apply Markdown task list format to a highlighted list in a PR](media/markdown-guidance/checklist-pr-apply.png) +> ![Screenshot of Markdown task list format in a highlighted list in a PR.](media/markdown-guidance/checklist-pr-apply.png) To mark items as completed by checking the boxes, you need to manually edit the markdown and modify the syntax after adding a task list. > [!div class="mx-imgBorder"] -> ![Check the boxes to mark items as completed.](media/markdown-guidance/checklist-pr-applied-check.png) +> ![Screenshot of checked boxes to mark items as completed.](media/markdown-guidance/checklist-pr-applied-check.png) **Example - Format a list as a task list** @@ -575,9 +544,7 @@ To mark items as completed by checking the boxes, you need to manually edit the ## Emoji -#### Supported in: Pull Requests | Wikis - -In pull request comments and wiki pages, you can use emojis to add character and react to comments in the request. Enter what you're feeling surrounded by `:` characters to get a matching emoji in your text. We support the [full set of emojis](https://www.webpagefx.com/tools/emoji-cheat-sheet/). +In pull request comments and wiki pages, you can use emojis to add character and react to comments in the request. Enter what you're feeling surrounded by `:` characters to get a matching emoji in your text. We support [*most* emojis](https://www.webpagefx.com/tools/emoji-cheat-sheet/). **Example:** @@ -604,8 +571,6 @@ To escape emojis, enclose them using the \` character. ## Ignore or escape Markdown syntax to enter specific or literal characters -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis - :::row::: :::column span="1"::: **Syntax** @@ -616,7 +581,7 @@ To escape emojis, enclose them using the \` character. :::row-end::: :::row::: :::column span="1"::: - To insert one of the following characters, prefix with a \(backslash). + To insert one of the following characters, prefix with a `\`(backslash). `\`, backslash ```, backtick `_`, underscore @@ -635,7 +600,7 @@ To escape emojis, enclose them using the \` character. Enter `\\` to get \ Enter `\_` to get _ Enter `\#` to get # - Enter `\(` to get ( + Enter `\(` to get ( Enter `\.` to get . Enter `\!` to get ! Enter `\*` to get * @@ -646,15 +611,13 @@ To escape emojis, enclose them using the \` character. ## Attachments -#### Supported in: Pull Requests | Wikis - In pull request comments and wiki pages, you can attach files to illustrate your point or to give more detailed reasoning behind your suggestions. To attach a file, drag and drop it into the comment field, or wiki page edit experience. You can also select the **paperclip** in the upper right of the comment box or from the format pane in your wiki page. -Web portal, Pull Request, Attach files via drag and drop i +:::image type="content" source="media/markdown-guidance/attach_files.png" alt-text="Screenshot of Web portal, Pull Request, Attach files via drag and drop."::: -If you have an image in your clipboard, you can paste it from the clipboard into the comment box or wiki page, and it renders directly into your comment or wiki page. +If you have an image on your clipboard, you can paste it into the comment box or wiki page, and it renders directly into your comment or wiki page. -Attaching non-image files creates a link to the file in your comment. Update the description text between the brackets to change the text displayed in the link. +Attaching nonimage files creates a link to the file in your comment. To change the text displayed in the link, update the description text between the brackets. The attached image files render directly into your comment or wiki pages. Save or update your comment or wiki page with an attachment. Then, you can see the attached image and select links to download the attached files. Attachments support the following file formats: @@ -677,8 +640,6 @@ Attachments support the following file formats: ## Mathematical notation and characters -#### Supported in: Pull Requests | Wikis - We support both inline and block [KaTeX](https://khan.github.io/KaTeX/function-support.html) notation in wiki pages and pull requests. See the following supported elements: - Symbols @@ -690,13 +651,6 @@ We support both inline and block [KaTeX](https://khan.github.io/KaTeX/function-s To include mathematical notation surround the mathematical notation with a `$` sign for inline and `$$` for block, as shown in the following examples: -::: moniker range="tfs-2018" - -> [!NOTE] -> This feature is supported within Wiki pages and pull requests for TFS 2018.2 or later versions. - -::: moniker-end - ### Example: Greek characters ```KaTeX @@ -704,7 +658,6 @@ $ \alpha, \beta, \gamma, \delta, \epsilon, \zeta, \eta, \theta, \kappa, \lambda, \mu, \nu, \omicron, \pi, \rho, \sigma, \tau, \upsilon, \phi, ... $ - $\Gamma, \Delta, \Theta, \Lambda, \Xi, \Pi, \Sigma, \Upsilon, \Phi, \Psi, \Omega$ ``` @@ -735,7 +688,6 @@ $$ \sum_{i=1}^{10} t_i $$ - $$ \int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x $$ @@ -745,6 +697,412 @@ $$ > [!div class="mx-imgBorder"] > ![Sums and Integrals.](media/markdown-guidance/mathematical-notation-sums-integrals.png) +## Use Markdown in wikis + +The following guidance shows Markdown syntax for use in Azure DevOps wikis. + +::: moniker range=">= azure-devops-2022" + +## Add Mermaid diagrams to a wiki page + +Mermaid lets you create diagrams and visualizations using text and code. + +> [!NOTE] +> - Not all syntax in the following linked content for diagram types works in Azure DevOps. For example, we don't support most HTML tags, Font Awesome, `flowchart` syntax (`graph` used instead), or LongArrow `---->`. +> - Mermaid isn't supported in the Internet Explorer browser. +> - If you experience an "Unsupported diagram type," the functionality may not be yet available in your organization due to usual deployment scheme. + +Wiki supports the following Mermaid diagram types: + +- [Sequence diagrams](https://mermaid.js.org/syntax/sequenceDiagram.html) +- [Gantt charts](https://mermaid.js.org/syntax/gantt.html) +- [Flowcharts](https://mermaid.js.org/syntax/flowchart.html) +- [Class diagram](https://mermaid.js.org/syntax/classDiagram.html) +- [State diagram](https://mermaid.js.org/syntax/stateDiagram.html) +- [User Journey](https://mermaid.js.org/syntax/userJourney.html) +- [Pie chart](https://mermaid.js.org/syntax/pie.html) +- [Requirements diagram](https://mermaid.js.org/syntax/requirementDiagram.html) + +For more information, see the [Mermaid release notes](https://github.com/mermaid-js/mermaid/releases) and [active requests in the Developer Community](https://developercommunity.visualstudio.com/search?space=21&q=mermaid&stateGroup=active). + +To add a Mermaid diagram to a wiki page, use the following syntax: + +``` wiki-mermaid +::: mermaid + +::: +``` +### Sequence diagram example + +A sequence diagram is an interaction diagram that shows how processes operate with one another and in which order. + +```markdown +::: mermaid +sequenceDiagram + Christie->>Josh: Hello Josh, how are you? + Josh-->>Christie: Great! + Christie->>Josh: See you later! +::: +``` + +:::image type="content" source="media/wiki/wiki-mermaid-sequence-diagram.png" alt-text="Screenshot of mermaid sequence."::: + +### Gantt chart example + +A Gantt chart records each scheduled task as one continuous bar that extends from the left to the right. The `x` axis represents time and the `y` records the different tasks and the order in which they're to be completed. + +When you exclude a date, day, or collection of dates specific to a task, the Gantt chart accommodates those changes by extending an equal number of days toward the right, not by creating a gap inside the task. + +```markdown +::: mermaid +gantt + title A Gantt chart + dateFormat YYYY-MM-DD + excludes 2022-03-16,2022-03-18,2022-03-19 + section Section + + A task :a1, 2022-03-07, 7d + Another task :after a1 , 5d +::: +``` + +:::image type="content" source="media/wiki/wiki-mermaid-gantt-chart.png" alt-text="Screenshot showing the Mermaid Live Editor with code and preview for Gantt chart."::: + +### Flowchart example + +A flowchart is composed of nodes, geometric shapes and edges, and arrows or lines. +The following example shows a flowchart using `graph` rather than `flowchart`. + +> [!NOTE] +> We don't support `---->` or `flowchart` syntax, nor links to and from `subgraph`. + +``` +:::mermaid +graph LR; + A[Hard edge] -->|Link text| B(Round edge) --> C{Decision} + C -->|One| D[Result one] + C -->|Two| E[Result two] +::: +``` + +:::image type="content" source="media/wiki/wiki-mermaid-flowchart.png" alt-text="Screenshot showing the Mermaid Live Editor with code and preview for flowchart."::: + +### Class diagram example + +The class diagram is main part of object-oriented modeling. The diagram describes objects, their attributes, methods, and inheritance between them. + +``` +:::mermaid +classDiagram + Creature <|-- Superman + Creature <|-- Vampire + Creature <|-- Diavolo + Creature: +int size + Creature: +int weight + Creature: +isBenign() + Creature: +power() + class Superman{ + +String currentName + +fly() + +heal() + } + class Vampire{ + -int age + -canBite() + } + class Diavolo{ + +bool is_serving + +heat() + } +::: +``` + +:::image type="content" source="media/wiki/wiki-mermaid-class-diagram.png" alt-text="Screenshot showing the Mermaid Live Editor with code and preview for Class diagram."::: + +### State diagram example + +The state diagram is used to describe how the system states can change from one to another. + +``` +:::mermaid +stateDiagram-v2 + [*] --> Active + state Active { + [*] --> NumLockOff + NumLockOff --> NumLockOn : EvNumLockPressed + NumLockOn --> NumLockOff : EvNumLockPressed + -- + [*] --> CapsLockOff + CapsLockOff --> CapsLockOn : EvCapsLockPressed + CapsLockOn --> CapsLockOff : EvCapsLockPressed + -- + [*] --> ScrollLockOff + ScrollLockOff --> ScrollLockOn : EvScrollLockPressed + ScrollLockOn --> ScrollLockOff : EvScrollLockPressed + } +::: +``` + +:::image type="content" source="media/wiki/wiki-mermaid-state-diagram.png" alt-text="Screenshot showing the Mermaid Live Editor with code and preview for State diagram." lightbox="media/wiki/wiki-mermaid-state-diagram.png"::: + +### User journey example + +The user journey diagram describes what steps are required to complete certain higher level action or task. + +``` +:::mermaid +journey + title Home office day + section Go to work + Wake up: 1: Me, Dog + Take shower: 2: Me + Go downstairs: 3: Me, Dog + Make coffee: 4: Me + Have a breakfast: 5: Me, Dog + Go upstairs: 3: Me, Dog + Do work: 1: Me, Dog + section Go home + Go downstairs: 3: Me, Dog + Sit down: 5: Me +::: +``` + +:::image type="content" source="media/wiki/wiki-mermaid-user-journey.png" alt-text="Screenshot of rendering of User Journey mermaid diagram."::: + +### Pie chart example + +The pie chart diagram is used to visualize the percentages in a circled graph. + +``` +:::mermaid +pie title Fishermans in countries + "Norway" : 684 + "Sweeden" : 234 + "Switzerland" : 10 +::: +``` + +:::image type="content" source="media/wiki/wiki-mermaid-pie-chart.png" alt-text="Screenshot showing the Mermaid Live Editor with code and preview for Pie chart." lightbox="media/wiki/wiki-mermaid-pie-chart.png"::: + +### Requirements diagram example + +The requirements diagram visualizes the requirements and their connections. + +``` +:::mermaid +requirementDiagram + requirement development_req { + id: 1 + text: requirements spec. + risk: medium + verifymethod: test + } + element test_suite { + type: manual test + } + test_suite - verifies -> development_req +::: +``` + +:::image type="content" source="media/wiki/wiki-mermaid-requirements-diagram.png" alt-text="Screenshot showing the Mermaid Live Editor with code and preview for Requirements diagram." lightbox="media/wiki/wiki-mermaid-requirements-diagram.png"::: + +::: moniker-end + +::: moniker range="<=azure-devops" + + + +## Create a table of contents (TOC) for wiki pages + +To create a table of contents, add a \[[\_TOC\_]]. The TOC is generated when the tag gets added and there's at least one heading on the page. + +> [!div class="mx-imgBorder"] +> ![Table of contents](media/toc_sample.png) + +The \[[\_TOC\_]] can be placed anywhere in the page to render the table of contents. +Only Markdown headings are considered for TOC (HTML heading tags aren't considered). + +All HTML and Markdown tags get stripped from the headings while adding it inside the TOC block. +See the following example of how the TOC renders when you add bold and italics to a heading. + +> [!div class="mx-imgBorder"] +> ![Tags for TOC](media/toc_tags.png) + +Consistency is maintained in the formatting of the TOC. + +> [!NOTE] +> The tag \[[\_TOC\_]] is case-sensitive. For example, \[[\_toc\_]] may not render the TOC. Also, only the first instance of [[\_TOC\_]] is rendered and the rest are ignored. + +::: moniker-end + +::: moniker range="azure-devops" + +## Add a subpages table + +Add a table of content for subpages (TOSP) to your wiki pages. This table has links to all subpages located under the page where the table of subpages is shown. + +You can add the table of subpages either by inserting the special tag `[[_TOSP_]]` manually or by selecting from the **More options** menu. Only the first `[[_TOSP_]]` tag is used to create the table of subpages. + +:::image type="content" source="media/wiki/wiki-table-content-subpages.png" alt-text="Screenshot showing markdown for child pages of Page 1."::: + +::: moniker-end + +::: moniker range="<=azure-devops" + +## Add a collapsible section + +To add a collapsible section in a wiki page, use the following syntax: + +```html +# A collapsible section with markdown +
      + Click to expand! + + ## Heading + 1. A numbered + 2. list + * With some + * Sub bullets +
      +``` + +:::image type="content" source="media/wiki/add-collapsible-section-wiki.png" alt-text="Screenshot showing markdown on one side and how the collapsible section renders on the other."::: + +Make sure to add an empty line in the following areas: + +- After the closing `` tag, otherwise the markdown/code blocks don't show correctly +- After the closing `` tag if you have multiple collapsible sections + +## Embed videos in a wiki page + +To embed videos from YouTube and Microsoft Streams in a wiki page, use the following syntax: + +```markdown +::: video + -::: -``` -The IFrame is the embed IFrame block of the YouTube or Microsoft Streams video. - -The ending ":::" is required to prevent a break in the page. - -## Embed Azure Boards query results in wiki - -To embed Azure Boards query results in a wiki page as a table, use the following syntax: - -> [!div class="tabbedCodeSnippets"] -```Query syntax -::: query-table -::: -``` - -For example: - -::: -query-table 6ff7777e-8ca5-4f04-a7f6-9e63737dddf7 -::: - -You can also use the **toolbar** and the **query selector** to embed the query results in a wiki page. - -![Query Results Icon](media/query_selector_icon.png) - -![Query Selector Pane](media/query_selector_pane.png) - -For more information about how to copy the query URL, which provides a GUID for the query, see [Email query items or share query URL](../../boards/queries/view-run-query.md#email-query-items-or-share-a-query-url). - -## @mention users and groups - -To @mention users or groups in wiki, key in "@" in the wiki editor. This @mention opens autosuggest from which you can mention users or groups to get notified by email. - -> ![Mention Autosuggest](media/mention-autosuggest.png) - -You can also select **@mention** from the edit toolbar. - -> ![Mention from edit toolbar](media/mention-toolbar.png) - -When you're editing pages directly in code, use the following pattern, `@<{identity-guid}>`. - -::: moniker-end - -::: moniker range=">= azure-devops-2020" - -## Page visits for wiki pages - -Automatically, you see an aggregated page visits count for the last 30 days on every page. - -Use the batch API `pagesBatch` to see the daily quantity of visits to all pages in a paginated way. They aren't sorted by number of visits, however. For data over 30 days old, you can get all page visits using the rest API. Sort these pages based on the number of visits to get the top 100. You can store these visits in a dashboard or database. - -![Wiki page visits](media/wiki/wiki-page-visits.png) - -> [!NOTE] -> A page visit is defined as a page view by a given user in a 15-minute interval. - -::: moniker-end - - - -## Link to work items from a wiki page - -Enter the pound sign (`#`), and then enter a work item ID. - -::: moniker range="tfs-2018" -> [!NOTE] -> This feature is available with TFS 2018.2 and later versions. -::: moniker-end - - - -## HTML tag support in wiki pages - -In wiki pages, you can also create rich content using HTML tags. - -> [!TIP] -> You can nest Markdown within your HTML, but you must include a blank line between the HTML element and the markdown. - - - ```HTML -

      - - [A Markdown link](https://microsoft.com) -

      -``` - -> [!NOTE] -> Pasting rich content as HTML is supported in Azure DevOps Server 2019.1 and later versions. - -**Example - Embedded video** - -```HTML - -``` - -```HTML - -``` - -
      -Result: -
      - - -**Example - Rich text format** - -```HTML -

      This text needs to strikethrough since it is redundant!

      -

      This text is teletype text.

      -Colored text -
      This text is center-aligned.
      -

      This text contains superscript text.

      -

      This text contains subscript text.

      -

      The project status is GREEN even though the bug count / developer may be in red. - Capability of span -

      Disclaimer: Wiki also supports showing small text

      -

      Bigger text

      -``` - -**Result:** - -![Light theme view](media/wiki/green-red-light-theme.png) - -![Dark theme view](media/wiki/green-red-dark-theme.png) - - - -## Related articles - -- [Project wiki](add-edit-wiki.md) -- [Wiki file structure](wiki-file-structure.md) -- [Wiki view history](wiki-view-history.md) diff --git a/docs/project/wiki/wiki-readme-permissions.md b/docs/project/wiki/wiki-readme-permissions.md index 8d77599bf50..1df594e7864 100644 --- a/docs/project/wiki/wiki-readme-permissions.md +++ b/docs/project/wiki/wiki-readme-permissions.md @@ -18,9 +18,9 @@ monikerRange: '<= azure-devops' Collaboration tools encompass READMEs, team project wikis, notifications, feedback, and search. -Most of these tools are available to you if you're added as a team member or a member of the Contributors group for a team project. The most common built-in groups include Readers, Contributors, and Project Administrators. For a simplified view of all default permissions assigned to built-in groups, see [Default permissions and access](../../organizations/security/permissions-access.md). +Most of the collaboration tools are available to you if you're a team member or a member of the Contributors group for a team project. The most common built-in groups include Readers, Contributors, and Project Administrators. For a simplified view of all default permissions assigned to built-in groups, see [Default permissions and access](../../organizations/security/permissions-access.md). -Stakeholders have limited access to view the charts and dashboards. To learn more, see [About access levels](../../organizations/security/access-levels.md). +Stakeholders are allowed limited access to view the charts and dashboards. For more information, see [About access levels](../../organizations/security/access-levels.md). [!INCLUDE [temp](../../organizations/security/includes/wiki.md)] diff --git a/docs/project/wiki/wiki-select-unpublish-versions.md b/docs/project/wiki/wiki-select-unpublish-versions.md deleted file mode 100644 index 8e5f2f5a9b4..00000000000 --- a/docs/project/wiki/wiki-select-unpublish-versions.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Publish, select, or unpublish a wiki version -titleSuffix: Azure DevOps -description: Publish or unpublish files in a Git code repository to a wiki in Azure DevOps -ms.subservice: azure-devops-wiki -ms.custom: wiki, devdivchpfy22 -ms.topic: conceptual -ms.assetid: -ms.author: chcomley -ms.reviewer: gopinach -author: chcomley -monikerRange: '>= azure-devops-2019' -ms.date: 06/21/2022 ---- - -# Publish, unpublish, and select version of a wiki - -[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] - -When you publish a Git repository to a wiki, you can publish new branch of the repo as versions, select a version to view, or unpublish the repo. - -## Publish a new wiki branch - -If your published wiki corresponds to a product version, you can publish new branches as you release new versions of your product. To create a new version, create a new branch of your repo, and then make updates to that new branch. - -1. To create a new branch from the web portal, select **Repos** > **Branches**, select :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **Actions** for the branch you previously published, and then select **New branch**. - - :::image type="content" source="../wiki/media/wiki/add-new-branch.png" alt-text="Screenshot of creating a new branch."::: - -1. To publish the new branch to a wiki, open the **Wiki** page for the currently published branch, open the branch picker, and then choose **Publish new branch**. - - > [!div class="mx-imgBorder"] - > ![Publish new version menu option](media/wiki/publish-new-version-option.png) - -1. Complete the form, choosing the branch that you previously created. - - :::image type="content" source="../wiki/media/wiki/publish-new-version-of-wiki.png" alt-text="Screenshot showing the publish new version dialog."::: - -1. Select **Publish**. - - -## Select a wiki version - -To select a wiki version, choose the version from the branch options from the **Wiki** page. - -> [!div class="mx-imgBorder"] -> ![Select wiki version](media/wiki/publish-wiki-select-version.png) - -## Unpublish a published wiki - -If you no longer want a repository to be published as a wiki, you can choose to unpublish it from **Wiki**. - -> [!NOTE] -> Unpublishing a wiki unpublishes the entire code wiki, which includes all versions of the repository that you have published previously. - -1. Select the wiki you want to unpublish, open the context menu, and select **Unpublish wiki**. - - > [!div class="mx-imgBorder"] - > ![Unpublish a wiki confirm dialog](media/wiki/unpublish-wiki-code-option.png) - -1. Confirm that you want to unpublish the wiki by choosing **Unpublish**. - - > [!div class="mx-imgBorder"] - > ![Select your wiki version](media/wiki/unpublish-wiki.png) - -## Related articles - -- [Provisioned wiki vs. publish code as wiki](provisioned-vs-published-wiki.md) -- [Update wiki pages offline](wiki-update-offline.md) -- [Manage README and Wiki permissions](manage-readme-wiki-permissions.md) diff --git a/docs/project/wiki/wiki-update-offline.md b/docs/project/wiki/wiki-update-offline.md index 4c601a0f61f..ec67ee0f562 100644 --- a/docs/project/wiki/wiki-update-offline.md +++ b/docs/project/wiki/wiki-update-offline.md @@ -9,8 +9,8 @@ ms.assetid: ms.author: chcomley author: chcomley ms.reviewer: gopinach -monikerRange: '>= tfs-2018' -ms.date: 06/21/2022 +monikerRange: "<=azure-devops" +ms.date: 01/05/2024 --- # Clone and update wiki content offline @@ -19,38 +19,23 @@ ms.date: 06/21/2022 You can update your wiki pages offline the same way you develop code in a Git repo. -::: moniker range="tfs-2018" -> [!NOTE] -> GIT workflows, like branch policies, are applicable only for publish code as wiki workflows. -::: moniker-end - You can use any client you want or git command-line tools to update your wiki offline. For details on working with Git repositories and supported tools, see [Git Repositories](../../repos/git/index.yml). The basic steps to update wiki content offline are as follows: -1. Clone your wiki Git repo to your local IDE or workspace. -2. Add files or folders to your local git branch. -3. Update the *.order* files to reflect the pages and sub-pages that you've added. -4. Commit and push the updates you made to your local git branch. +1. [Clone your wiki Git repo to your local IDE or workspace.](#clone-your-wiki) +2. [Add files or folders to your local git branch.](#add-pages) +3. Update the *.order* files to reflect your pages and subpages. +4. [Commit and push the updates you made to your local git branch.](#push-your-changes) ## Prerequisites -::: moniker range=">= azure-devops-2019" - -Do the following steps to migrate Markdown pages from another wiki to your team project wiki or to content that you publish as code to a wiki. - -- [Understand the underlying structure of your wiki Git repo](wiki-file-structure.md) -- Understand the [differences between provisioned wiki and publish code as wiki](provisioned-vs-published-wiki.md) - -::: moniker-end - -::: moniker range="tfs-2018" - -Do the following steps to migrate Markdown pages from another wiki to your team project wiki. - -- [Understand the underlying structure of your wiki Git repo](wiki-file-structure.md). - -::: moniker-end +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of the project where the wiki's located. If you don't have access, request it from your project administrator. | +| **Permissions** | - Member of the **Contributors** group.
      - To publish code as wiki: **Create Repository** permission. By default, this permission is set for members of the [Project Administrators group](../../repos/git/set-git-repository-permissions.md). | +| **Access levels** | At least **Basic** access. | +|**Tasks** |- [Understand the underlying structure of your wiki Git repo](wiki-file-structure.md)
      - Understand the [differences between provisioned wiki and publish code as wiki](provisioned-vs-published-wiki.md) | @@ -58,7 +43,7 @@ Do the following steps to migrate Markdown pages from another wiki to your team Your wiki repository stores pages, images, attachments, and the sequence of pages and subpages. Clone your wiki to begin. -1. Sign in to your organization (`https://dev.azure.com/{yourorganization}`), select your project, and then select your wiki. +1. Sign in to your project (`https://dev.azure.com/{Your_Organization/Your_Project}`) and then select your wiki. 2. Open the **More actions** context menu and select **Clone wiki**. @@ -72,7 +57,10 @@ Your wiki repository stores pages, images, attachments, and the sequence of page :::image type="content" source="media/wiki/work-offline-wikiMaster-files.png" alt-text="Wiki main files"::: -4. Use the URL that you copied to clone the repo in the IDE that you use. To learn more, see one of the following articles: + > [!IMPORTANT] + > The "Generate Git Credentials" button will be removed in January 2025, to reduce creation of unnecessary and underutilized personal access tokens. Review the Git Authentication docs for all authentication methods available to you for git clone operations. + +4. Use the URL that you copied to clone the repo in the IDE that you use. For more information, see one of the following articles: - [Clone an existing Git repo](../../repos/git/clone.md) - [Using Version Control in VS Code](https://code.visualstudio.com/docs/editor/versioncontrol) - [Get Started with Git and Azure DevOps](../../repos/git/gitquickstart.md?tabs=visual-studio) @@ -95,7 +83,7 @@ To add pages at the root of the wiki tree, add a Markdown file at the root of th :::image type="content" source="media/wiki/add-pages.png" alt-text="Local branch wiki Git repo"::: -3. After you've added all the pages you want to add at the root, update the **.order** file at the root. It should have one entry for each Markdown file that is defined at the root. Each entry should match the file title with spaces replaced with a dash. +3. After you added all the pages you want to add at the root, update the **.order** file at the root. It should have one entry for each Markdown file that is defined at the root. Each entry should match the file title with spaces replaced with a dash. For example: @@ -115,9 +103,9 @@ To add pages at the root of the wiki tree, add a Markdown file at the root of th :::image type="content" source="media/wiki/add-sub-pages.png" alt-text="Screenshot of the subpages."::: -2. Add a **.order** file in the folder with the order of the sub-pages as they should appear in the wiki. To understand the use of the **.order** file to sequence pages, see [Wiki Git repository files and file structure](wiki-file-structure.md). +2. Add a **.order** file in the folder with the order of the subpages as they should appear in the wiki. To understand the use of the **.order** file to sequence pages, see [Wiki Git repository files and file structure](wiki-file-structure.md). - For example, the file has the following sub-pages: + For example, the file has the following subpages: ``` Request-extensions @@ -126,7 +114,7 @@ To add pages at the root of the wiki tree, add a Markdown file at the root of th Coding-guidelines ``` -### Push your changes +## Push your changes When you're done with all your updates, [push the files to the Git repository](../../repos/git/pushing.md). @@ -136,7 +124,7 @@ The added pages and subpages appear immediately in your wiki. If there are any errors in the process, the pages appear in your wiki with a warning sign. -:::image type="content" source="media/wiki/wiki-offline-order-warning.png" alt-text="Warning when .order file is not updated properly."::: +:::image type="content" source="media/wiki/wiki-offline-order-warning.png" alt-text="Warning when .order file isn't updated properly."::: ## Related articles @@ -146,33 +134,3 @@ If there are any errors in the process, the pages appear in your wiki with a war - [Share code with push](../../repos/git/pushing.md) - [Manage README and Wiki permissions](manage-readme-wiki-permissions.md) - [Syntax guidance for Markdown files, widgets, wikis, and pull request comments](./markdown-guidance.md). - - diff --git a/docs/project/wiki/wiki-view-history.md b/docs/project/wiki/wiki-view-history.md index cc7418cc5b4..d17359cbf57 100644 --- a/docs/project/wiki/wiki-view-history.md +++ b/docs/project/wiki/wiki-view-history.md @@ -1,7 +1,7 @@ --- title: Revert changes and find wiki page history titleSuffix: Azure DevOps -description: Add and update pages offline for your built-in team project wiki +description: Add and update pages offline for your built-in team project wiki. ms.subservice: azure-devops-wiki ms.custom: wiki, devdivchpfy22 ms.topic: how-to @@ -9,53 +9,47 @@ ms.author: chcomley author: chcomley ms.reviewer: gopinach monikerRange: '<= azure-devops' -ms.date: 06/13/2022 +ms.date: 11/21/2023 --- # View wiki page history and revert changes [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can see details of the changes made to a wiki page and revert to an earlier version, if needed. +This article shows you how to view the revision history of a wiki page in Azure DevOps. It also provides information on how to revert changes made to a wiki page. - - -## View wiki page revision history +## Prerequisites -1. To view the revision history of a page, select the **Revisions** link provided on each page. You can also select **View revisions** in the context menu of a page. +[!INCLUDE [wiki-prereqs-create-repository](includes/wiki-prereqs-create-repository.md)] - :::image type="content" source="media/wiki/click-revision.png" alt-text="Screenshot of the context menu showing Print, Link work items, View revisions, and Delete options. View revisions is highlighted."::: + -2. Revision pages show who made the change along with the revision message, date, and version or commit ID. To view details of a revision, select the message or version link. +## View wiki page revision history - ::: moniker range=">= azure-devops-2019" +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and go to your wiki page. +2. Select :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More actions** > **View revisions**. - > [!div class="mx-imgBorder"] - > ![Page for a provisioned wiki page](media/wiki/revision-history-vsts.png) + :::image type="content" source="media/wiki/wiki-page-revisions.png" alt-text="Screenshot of the context menu showing Print, Link work items, View revisions, and Delete options. The View revisions button is highlighted."::: - ::: moniker-end +3. Revision pages show who made the change along with the revision message, date, and version or commit ID. To view details of a revision, select the message or version link. - ::: moniker range="tfs-2018" + ::: moniker range="<=azure-devops" - ![Home | Revisions lists revisions. The columns are Author, Message, Last Updated, and Version.](media/wiki/revision-history.png) + :::image type="content" source="media/wiki/revision-history-vsts.png" alt-text="Screenshot of Page for a provisioned wiki page."::: ::: moniker-end -3. Similar to any git file revision, the revision details page provides a **Show diff side-by-side** view or the **Show diff inline** view. Choose **Preview** to see the content of the page of the specific revision. +4. Similar to any git file revision, the revision details page provides a **Show diff side-by-side** view or the **Show diff inline** view. Choose **Preview** to see the content of the page of the specific revision. - ![Two revisions of an article are compared side-by-side. The article is in Markdown, and is titled Welcome to the Fabrikam Fiber wiki.](media/wiki/wiki-revision-details-2.png) + :::image type="content" source="media/wiki/wiki-revision-details-2.png" alt-text="Screenshot of article revisions compared side-by-side. The article is in Markdown."::: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - For a *publish as code wiki* page, you see similar information, but **Revert** isn't active. - - > [!div class="mx-imgBorder"] - > ![Revision page for a publish as code wiki page](media/wiki/view-history-publish-as-code.png) + For a *publish as code wiki* page, similar information displays, but the **Revert** button isn't active. ::: moniker-end -4. [Use the breadcrumbs](../navigation/use-breadcrumbs-selectors.md) to return to the page or revisions of the page. - +5. [Use the breadcrumbs](../navigation/use-breadcrumbs-selectors.md) to return to the page or revisions of the page. @@ -63,93 +57,65 @@ You can see details of the changes made to a wiki page and revert to an earlier Select **Revert** on the revision details page to revert a change on a wiki page. -::: moniker range="tfs-2018" -> [!NOTE] -> The **Revert** option is available with TFS 2018.2 and later versions. -::: moniker-end - -![Dialog box Revert revision 701b5a9f has the Revert and Cancel options. Revert is selected.](media/wiki/wiki-revert.png) +:::image type="content" source="media/wiki/wiki-revert.png" alt-text="Screenshot fo the Dialog box revert revision. Revert option is selected."::: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Revert a commit to a *publish as code wiki* page -If you need to revert to an earlier revision for a page that you've published as code, do one of the following actions: +To revert to an earlier revision for a page that you published as code, do one of the following actions: - If the commit is the most recent revision to a page, you can revert from the web portal. -- If the commit is an earlier revision, with additional commits having occurred in between, create a separate branch and revert the changes in that branch. +- If the commit is an earlier revision, with more commits having occurred in between, create a separate branch and revert the changes in that branch. ### Revert from a recent revision from the web portal 1. Preview any version by choosing the commit ID from the **Revisions** page for the selected file. -2. Copy the full ID of the commit by selecting :::image type="icon" source="../../media/icons/copy-clone-icon.png" border="false"::: **Copy-clone**. Here we copy the commit ID, `ca6d475a22eb1db930cf238f3b80862a78a689e4`, with the abbreviated ID of `ca6d475a`. +2. Copy the full ID of the commit by selecting :::image type="icon" source="../../media/icons/copy-clone-icon.png" border="false"::: **Copy-clone**. - > [!div class="mx-imgBorder"] - > ![Copy the full commit id for an earlier commit](media/wiki/revert-publish-as-code-copy-commit-id.png) + :::image type="content" source="media/wiki/revert-publish-as-code-copy-commit-id.png" alt-text="Screenshot of Copy the full commit ID."::: -3. Open the **Repos > Commits** page and paste the ID that you copied into the Commit ID box and choose :::image type="icon" source="../../media/icons/search-icon.png" border="false"::: Search. +3. Go to **Repos** > **Commits**, paste the ID that you copied into the Commit ID box, and select :::image type="icon" source="../../media/icons/search-icon.png" border="false"::: Search. - > [!div class="mx-imgBorder"] - > ![Paste the commit id for an earlier commit.](media/wiki/revert-publish-as-code-paste-commit-id.png) + :::image type="content" source="media/wiki/revert-publish-as-code-paste-commit-id.png" alt-text="Screenshot of Paste the commit ID for an earlier commit."::: 4. From the commit page, select :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: **More actions**, and then choose **Revert**. - > [!div class="mx-imgBorder"] - > ![Choose revert menu option of an earlier commit](media/wiki/revert-publish-as-code-option.png) - -5. Confirm that you want to revert. Choose **Revert** in the dialog. + :::image type="content" source="media/wiki/revert-publish-as-code-option.png" alt-text="Screenshot of Choose revert menu option of an earlier commit."::: - > [!div class="mx-imgBorder"] - > ![Revert commit dialog](media/wiki/revert-publish-as-code-commit-dialog.png) +5. Confirm that you want to revert. Select **Revert**. - A branch is created with the reverted changes. + :::image type="content" source="media/wiki/revert-publish-as-code-commit-dialog.png" alt-text="Screenshot of Revert commit dialog."::: -6. Select **Create Pull Request**. + A branch gets created with the reverted changes. - > [!div class="mx-imgBorder"] - > ![Select Create Pull Request.](media/wiki/revert-publish-as-code-commit-confirm.png) +6. Select **Create Pull Request**. - If instead, you receive an error message as shown, it indicates that you must create a local branch and make your changes manually as described in the next section. - - > [!div class="mx-imgBorder"] - > ![Revert publish code as wiki error message](media/wiki/revert-publish-as-code-error-message.png) + If you receive an error message, you might need to create a local branch and make your changes manually as described in the next section. 7. Select **Create** in the New Pull Request form. -8. Select **Complete** to merge the changes into the main wiki branch. Optionally, check the **Delete** checkbox to delete the intermediate branch. +8. Select **Complete merge** to merge the changes into the main wiki branch. Optionally, add a check to the checkboxes to select post-completion options. - > [!div class="mx-imgBorder"] - > ![Revert publish code as wiki, complete pull request](media/wiki/revert-complete-pull-request-dialog.png) + :::image type="content" source="media/wiki/revert-complete-pull-request-dialog.png" alt-text="Screenshot of Revert publish code as wiki, complete pull request."::: -Return to the wiki, refresh the browser, and you should see the reverted content. +To view the reverted content, return to the wiki and refresh the browser. ### Revert from earlier revisions using a different branch -To revert to an earlier committed version of a publish as code wiki page (one that isn't the immediate last revision), you must update a branch other than the main branch for the wiki, and then create a pull request to the main branch. +To revert to an earlier committed version of a publish as code wiki page, one that isn't the immediate last revision, update a branch other than the main branch for the wiki, and then create a pull request to the main branch. 1. Create a local branch of the main wiki branch. -1. View the commit history and locate the commit that contains the changes you want to undo. -2. Use the revert command to revert the desired commit. -3. When a conflict arises, use the conflict resolution tools to resolve the issues. -4. Commit the changes locally to your local branch. -5. Push the local branch to the remote server. -6. Create a pull request for your local branch into main. -7. Complete the pull request. - -You can use the following steps to identify the commit that contains the content you want to revert to. Then, use standard Git operations to revert the content. - -For more information, see the following articles: - -- [Clone an existing Git repo](../../repos/git/clone.md) -- [Create work in branches](../../repos/git/create-branch.md) -- [Review history](../../repos/git/review-history.md) -- [Undo (revert) changes](../../repos/git/undo.md) -- [Resolve merge conflicts](../../repos/git/merging.md) -- [Copy changes with cherry-pick](../../repos/git/cherry-pick.md) -- [Commit details](../../repos/git/commit-details.md) +2. View the commit history and locate the commit that contains the changes you want to undo. +3. Use the revert command to revert the desired commit. +4. When a conflict arises, use the conflict resolution tool to resolve the issues. +5. Commit the changes to your local branch. +6. Push the local branch to the remote server. +7. Create a pull request for your local branch into main. +8. Complete the pull request. ::: moniker-end @@ -157,5 +123,8 @@ For more information, see the following articles: - [Wiki Git repository files and file structure](wiki-file-structure.md) - [Differences between provisioned wiki and publish code as wiki](provisioned-vs-published-wiki.md) -- [Update wiki pages offline](wiki-update-offline.md) -- [Manage README and Wiki permissions](manage-readme-wiki-permissions.md) \ No newline at end of file +- [Undo (revert) repo changes](../../repos/git/undo.md) +- [Manage README and Wiki permissions](manage-readme-wiki-permissions.md) +- [Review Git history](../../repos/git/review-history.md) +- [Clone an existing Git repo](../../repos/git/clone.md) + \ No newline at end of file diff --git a/docs/project/work-across-projects-faqs.yml b/docs/project/work-across-projects-faqs.yml index 07aa012f426..6f60004885e 100644 --- a/docs/project/work-across-projects-faqs.yml +++ b/docs/project/work-across-projects-faqs.yml @@ -1,7 +1,7 @@ ### YamlMime:FAQ metadata: title: Work across projects FAQs - description: Get answers to common questions about working across projects in Azure DevOps. + description: Get answers to frequently asked questions about working across projects in Azure DevOps. titleSuffix: Azure DevOps ms.subservice: azure-devops-projects ms.custom: cross-project @@ -9,143 +9,135 @@ metadata: author: chcomley ms.topic: faq monikerRange: '<= azure-devops' - ms.date: 05/20/2022 + ms.date: 03/11/2025 -title: Work across projects FAQs +title: FAQs about working across projects summary: | - Many enterprise organizations add multiple projects to support their business needs. While we recommend that you maintain a single project to keep things simple, there are instances where multiple projects are needed. In that event, several questions arise as to what tasks are supported when working with two or more projects. + Many enterprise organizations create multiple projects to meet their business needs. Although we recommend maintaining a single project for simplicity, there are situations where multiple projects are necessary. Working with two or more projects raises several questions about the tasks that are supported. - This article addresses these questions. To learn about specific cross-project features, see [Work across projects](navigation/work-across-projects.md). + This article answers those questions. For more information about specific cross-project features, see [Work across projects](navigation/work-across-projects.md). - ::: moniker range="azure-devops" - > [!NOTE] - > Users added to the **Project-Scoped Users** group can only access those projects they've been explicitly added to. To learn more, see [About projects and scaling your organization, Project-scoped User group ](../organizations/projects/about-projects.md#project-scoped-user-group). - ::: moniker-end + ::: moniker range="azure-devops" + > [!NOTE] + > Users added to the **Project-Scoped Users** group can only access projects they're added to. For more information, see [About projects and scaling your organization, Project-scoped User group](../organizations/projects/about-projects.md#project-scoped-user-group). + ::: moniker-end sections: - name: Projects questions: - question: How many projects should I create? answer: | - In general, we recommend that you create a single project. However, certain business needs, such as supporting a public project or applying security policies, may require creating more than one project. To learn more, see one of the following articles. + In general, we recommend that you create a single project. However, certain business needs, such as supporting a public project or applying security policies, might require creating more than one project. For more information, see one of the following articles. - [About projects and scaling your organization](../organizations/projects/about-projects.md) - [Plan your organizational structure](../user-guide/plan-your-azure-devops-org-structure.md) - [What is a public project?](../organizations/projects/about-projects.md) - - question: Can I connect to more than one project at a time? + - question: Can I connect to more than one project at a time? answer: | When you connect from a web browser, you can connect to different projects from different browser tabs. When you connect from a client or IDE, you can only connect to a single project at a time. For more information, see [Connect to team projects](../organizations/projects/connect-to-projects.md). - - question: How do I view all projects available to me? + - question: How do I view all projects available to me? answer: See [Switch project, repository, team](navigation/go-to-project-repo.md). - question: How do I turn off cross-project collaboration? answer: | - If you want to limit users to view or modify select work items, you can by [setting permissions on Area Paths](../organizations/security/set-permissions-access-work-tracking.md#set-permissions-area-path). However, there's no method for limiting users to linking work items that reside in different projects. + If you want to limit users to view or modify select work items, [set permissions on Area Paths](../organizations/security/set-permissions-access-work-tracking.md#set-permissions-area-path). However, there's no method for limiting users to linking work items that reside in different projects. - name: Dashboards and reports questions: - question: Can I create a dashboard with information that spans two or more projects? answer: | ::: moniker range=">= azure-devops-2020" - There is limited support for widgets that you add to a dashboard from different projects. Specifically, you can add [Burndown and Burnup charts](../report/dashboards/configure-burndown-burnup-widgets.md) from different projects to a dashboard. Query-based widgets reference queries that you define, which can [reference projects](../boards/queries/using-queries.md#query-across-projects) other than the project where the query is defined. You can also use an [Embedded Webpage widget](../report/dashboards/widget-catalog.md#embedded-webpage-widget) to display data from a URL, such as a backlog, board, or an **Analytics** chart from for a team. However, the backlog, board, or chart displays using the display preferences set by the currently logged in user viewing the dashboard. - ::: moniker-end - ::: moniker range="< azure-devops-2020" - The only way to view data from different projects is to use [Query-based widgets](../report/dashboards/widget-catalog.md#work-widgets) or [Embedded Webpage widgets](../report/dashboards/widget-catalog.md#embedded-webpage-widget). Query-based widgets reference queries that you define, which can [reference projects](../boards/queries/using-queries.md#query-across-projects) other than the project where the query is defined. Embedded Webpage widgets display data from a URL, such as a backlog, board, or chart for a team in different projects. However, the backlog, board, or chart displays using the display preferences set by the currently logged in user viewing the dashboard. + There's limited support for widgets that you add to a dashboard from different projects. Specifically, you can add [Burndown and Burnup charts](../report/dashboards/configure-burndown-burnup-widgets.md) from different projects to a dashboard. Query-based widgets reference queries that you define, which can [reference other projects](../boards/queries/using-queries.md). You can also use an [Embedded Webpage widget](../report/dashboards/widget-catalog.md#embedded-webpage-widget) to display data from a URL, such as a backlog, board, or an **Analytics** chart from for a team. However, the backlog, board, or chart displays using the display preferences set by the currently logged in user viewing the dashboard. ::: moniker-end + > [!NOTE] - > There is a [suggested feature, Single Dashboard for Multiple Projects](https://developercommunity.visualstudio.com/t/single-dashboard-for-multiple-projects/365500) that you can review and up vote. + > There's a [suggested feature, Single Dashboard for Multiple Projects](https://developercommunity.visualstudio.com/t/single-dashboard-for-multiple-projects/365500) that you can review and up vote. - question: Can I create a report that spans two or more projects? answer: | - ::: moniker range=">= azure-devops-2019" - **Yes**. The Analytics service and Power BI reports support creation of reports that span two or more projects. To learn more, see [Create a Power BI report with an OData Query](../report/powerbi/create-quick-report-odataq.md). - ::: moniker-end - ::: moniker range="< azure-devops-2019" - **Yes**. The SQL Server Reporting services support creation of reports that span two or more projects. + ::: moniker range="<=azure-devops" + **Yes**. The Analytics service and Power BI reports support the creation of reports that span two or more projects. For more information, see [Create a Power BI report with an OData Query](../report/powerbi/create-quick-report-odataq.md). ::: moniker-end + - name: Azure Boards and work tracking questions: - question: Can I query across projects? answer: | - **Yes**. You can create work item queries that span all projects within an organization or filter for specific projects. Also, you can use the search tool to perform work item searches across all projects in an organization. To learn more, see one of the following articles: - - [Define a query, Query across projects](../boards/queries/using-queries.md#across-projects) + **Yes**. You can create work item queries that span all projects within an organization or filter for specific projects. Also, you can use the search tool to perform work item searches across all projects in an organization. For more information, see one of the following articles. + - [Define a query, Query across projects](../boards/queries/using-queries.md) - [Search for work items](search/functional-work-item-search.md) - - question: Can I view a Kanban board of work items defined in different projects? + - question: Can I view a board of work items defined in different projects? answer: | - **Yes**. This feature is supported through the [Query Based Boards](https://marketplace.visualstudio.com/items?itemName=realdolmen.EdTro-AzureDevOps-Extensions-QueryBasedBoards-Public) Marketplace extension. You can view a Kanban board view of a flat-list query of work items. + **Yes**. The [Query Based Boards](https://marketplace.visualstudio.com/items?itemName=realdolmen.EdTro-AzureDevOps-Extensions-QueryBasedBoards-Public) Marketplace extension supports this feature. You can view a board view of a flat-list query of work items. - question: Can I link work items across projects? answer: | - **Yes**. You can use any link type you want to link work items that are defined in different projects. The projects must be defined within the same organization or project collection. To learn more, see [Link user stories, issues, bugs, and other work items](../boards/backlogs/add-link.md). + **Yes**. You can use any link type you want to link work items defined in different projects. You must define the projects within the same organization or project collection. For more information, see [Link user stories, issues, bugs, and other work items](../boards/backlogs/add-link.md). - question: Can I query for work items linked across projects? answer: | - **No**. There is a prohibitive performance cost for trying to execute such a query, so it isn't supported. + **No**. There's a prohibitive performance cost for trying to execute such a query, so it isn't supported. - question: Can I export a cross-project query to Excel? answer: | - ::: moniker range=">= azure-devops-2019" - **No**. Cross-project queries won't open in Excel. However, you can export a cross-project query to a .csv file, open it in Excel, and import it to Azure Boards. To learn more, see [Bulk import or update work items using CSV files](../boards/queries/import-work-items-from-csv.md). - ::: moniker-end - ::: moniker range="tfs-2018" - **No**. Cross-project queries won't open in Excel. + ::: moniker range="<=azure-devops" + **No**. Cross-project queries don't open in Excel. However, you can export a cross-project query to a .csv file, open it in Excel, and import it to Azure Boards. For more information, see [Bulk import or update work items using CSV files](../boards/queries/import-work-items-from-csv.md). ::: moniker-end - + - question: Can I link work items across organizations or collections? answer: | ::: moniker range="azure-devops" - **Yes** across organizations. See [Link user stories, issues, bugs, and other work items; Link to a remote work item](../boards/backlogs/add-link.md#link-to-a-remote-work-item). + **Yes** across organizations. See [Link user stories, issues, bugs, and other work items; Link to a remote work item](../boards/backlogs/add-link.md). ::: moniker-end ::: moniker range="< azure-devops" - **No** across collections. This isn't a supported feature. + **No** across collections, as it isn't a supported feature. ::: moniker-end - question: Can I perform capacity planning across projects? answer: | - **No**. Capacity planning data isn't stored in the work tracking data store or Analytics service. This isn't a supported feature. + **No**. Azure Devops doesn't store capacity planning data in the work tracking data store or Analytics service, as it isn't a supported feature. - - question: How do I manage dependencies across projects? + - question: How do I manage dependencies across projects? answer: | To manage dependencies in Azure Boards, you can link work items using the Predecessor/Successor link type. To learn how, see [Link user stories, issues, bugs, and other work items](../boards/backlogs/add-link.md). - - question: Can I query for work items linked across projects? + - question: Can I query for work items linked across projects? answer: | - **No**. There is a prohibitive performance cost for trying to execute such a query, so it isn't supported. - + **No**. There's a prohibitive performance cost for trying to execute such a query, so it isn't supported. - name: Azure Boards customization questions: - question: Can I apply an Inherited process defined in one organization to another organization? answer: | - **Yes**. To perform this operation, you need to export the process and import it to the other organization. While there is no import/export user interface, you can use the [Process Migrator for Node.js](https://github.com/Microsoft/process-migrator) application. + **Yes**. To perform this operation, you need to export the process and import it to the other organization. While there's no import/export user interface, you can use the [Process Migrator for Node.js](https://github.com/Microsoft/process-migrator) application. - question: Can I apply an Inherited process defined in one collection to another collection? answer: | - **Yes**. To perform this operation, you need to export the process and import it to the other collection. While there is no import/export user interface, you can use the [Process Migrator for Node.js](https://github.com/Microsoft/process-migrator) application. + **Yes**. To perform this operation, you need to export the process and import it to the other collection. While there's no import/export user interface, you can use the [Process Migrator for Node.js](https://github.com/Microsoft/process-migrator) application. - name: Azure Repos questions: - question: Can I set branch policies across repositories within a project? answer: | ::: moniker range="azure-devops" - **Yes**. Cross-repository policies apply to all or a selection of the repositories in the projects. You do this from **Project Settings>Repositories>Policies**. Add a custom policy and specify if it is for all repositories or choose which repositories it should apply to. To learn more about branch policies, see [Improve code quality with branch policies](../repos/git/branch-policies.md). + **Yes**. Cross-repository policies apply to all or a selection of the repositories in the projects. Do so from **Project settings** > **Repositories** > **Policies**. Add a custom policy and specify if it's for all repositories or choose to which repositories it should apply. For more information about branch policies, see [Improve code quality with branch policies](../repos/git/branch-policies.md). ::: moniker-end ::: moniker range="azure-devops-2020" - **Yes**. Cross-repository policies apply to all or a selection of the repositories in the projects. You do this from **Project Settings>Cross-repo policies**. Add branch protection and specify if it is for all repositories or choose which repositories it should apply to. To learn more, see [Cross-repo branch policy administration](/azure/devops/release-notes/2019/sprint-160-update#cross-repo-branch-policy-administration) and [Improve code quality with branch policies](../repos/git/branch-policies.md). + **Yes**. Cross-repository policies apply to all or a selection of the repositories in the projects. Do so from **Project settings** > **Cross-repo policies**. Add branch protection and specify if it's for all repositories or choose to which repositories it should apply. For more information, see [Cross-repo branch policy administration](/azure/devops/release-notes/2019/sprint-160-update#cross-repo-branch-policy-administration) and [Improve code quality with branch policies](../repos/git/branch-policies.md). ::: moniker-end - question: How can I find all completed pull requests across projects? answer: | - There is no user interface feature to extract this information. You can use the REST API to get this information as follows: + There's no user interface feature to extract this information. You can use the REST API to get this information as follows: 1. Get all projects using [Projects-List](/rest/api/azure/devops/core/projects/list). 1. Get all repositories of each project using [Repositories - List](/rest/api/azure/devops/git/repositories/list). 1. Get all pull requests of each repository using [Pull Requests - Get Pull Requests](/rest/api/azure/devops/git/pull-requests/get-pull-request#pullrequeststatus). additionalContent: | ## Related articles - - [Work across projects](navigation/work-across-projects.md). + - [Work across projects](navigation/work-across-projects.md) - [Connect to team projects](../organizations/projects/connect-to-projects.md) diff --git a/docs/reference/add-modify-field.md b/docs/reference/add-modify-field.md index 6f3ec8ed24a..e25bc495839 100644 --- a/docs/reference/add-modify-field.md +++ b/docs/reference/add-modify-field.md @@ -34,9 +34,9 @@ Not all pick lists are defined in the same way. Some lists are defined through t ## Prerequisites -- To list fields, you must have your **View project-level information** permission for the project in the collection set to **Allow**. -- To add or customize a field, you must be a member of the Project Administrators group or have your **Edit project-level information** permission set to Allow. -- To delete or rename fields or change an attribute of a field, you must be a member of the **Team Foundation Administrators** security group or the **Project Collection Administrators** security group. +- To list fields, have your **View project-level information** permission for the project in the collection set to **Allow**. +- To add or customize a field, be a member of the Project Administrators group or have your **Edit project-level information** permission set to Allow. +- To delete or rename fields or change an attribute of a field, be a member of the **Team Foundation Administrators** security group or the **Project Collection Administrators** security group. To get added as an administrator, [Change project collection-level permissions](../organizations/security/change-organization-collection-level-permissions.md). @@ -75,7 +75,7 @@ To add rules or add a custom field, export, edit, and then import the WIT defini [!INCLUDE [temp](../includes/process-editor.md)] -Any field that you want to use to track data must be added to the WIT definition file. This is true for all but system fields (fields whose reference name start with **System.**). All System fields are defined for all WITs, whether or not you include them in WIT definition. To learn more about each field, see [Work item field index](../boards/work-items/guidance/work-item-field.md). +Any field that you want to use to track data must be added to the WIT definition file. This is true for all but system fields (fields whose reference name start with **System.**). All System fields are defined for all WITs, whether or not you include them in WIT definition. For more information about each field, see [Work item field index](../boards/work-items/guidance/work-item-field.md). @@ -364,7 +364,7 @@ For more information, see [Query based on build and test integration fields](../ ## Field names and reporting -You can add fields or change the attributes of existing fields to support reporting. When you add or change fields, you should name them systematically so that you can find the field in the Analysis Services cube because the fields are logically grouped into folders. To learn more, see [Add or modify work item fields to support reporting](/previous-versions/azure/devops/reference/xml/add-or-modify-work-item-fields-to-support-reporting). +You can add fields or change the attributes of existing fields to support reporting. When you add or change fields, you should name them systematically so that you can find the field in the Analysis Services cube because the fields are logically grouped into folders. For more information, see [Add or modify work item fields to support reporting](/previous-versions/azure/devops/reference/xml/add-or-modify-work-item-fields-to-support-reporting). ::: moniker-end diff --git a/docs/reference/add-modify-wit.md b/docs/reference/add-modify-wit.md index 2f52a996a62..c5182c21d76 100644 --- a/docs/reference/add-modify-wit.md +++ b/docs/reference/add-modify-wit.md @@ -51,24 +51,16 @@ Most work item type customizations are made to the work item type XML definition - [Rename a work item type](#rename-wit) - [Delete a work item type](#delete-wit) - ## Prerequisites -::: moniker range=">= azure-devops-2019" - -- To list work item types, you must have your **View project-level information** permission for the project in the collection set to **Allow**. -- To add or customize a work item type by customizing a process template, you must be a member of the Project Collection Administrators group or have your **Edit process** permission set to **Allow**. -::: moniker-end +::: moniker range="<=azure-devops" -::: moniker range="< azure-devops-2019" -- To list work item types, you must have your **View project-level information** permission for the project in the collection set to **Allow**. -- To add or customize a work item type, you must be a member of the Project Administrators group or have your **Edit project-level information** permission set to **Allow**. +- To list work item types, have your **View project-level information** permission for the project in the collection set to **Allow**. +- To add or customize a work item type by customizing a process template, be a member of the Project Collection Administrators group or have your **Edit process** permission set to **Allow**. ::: moniker-end To get added as an administrator, see [Change project collection-level permissions](../organizations/security/change-organization-collection-level-permissions.md). - - ## How do modifications to work item types affect existing work items? The following table summarizes the effect on existing work items when you modify fields or work item type definitions. @@ -122,7 +114,6 @@ To add a custom work item type or modify an existing work item type, you define The easiest way to add a new work item type is to copy an existing work item type and then modify the definition file. - ## Add or modify a field, field rule, label, or empty text @@ -198,7 +189,6 @@ The following illustrations highlight the most common elements on work item form ![Screenshot of header element within work item web form.](xml/media/weblayout-system-controls-details-page.png) - You can customize the form to accomplish the following objectives: - [Add or modify a field](/previous-versions/azure/devops/reference/xml/weblayout-xml-elements) @@ -211,7 +201,6 @@ You can customize the form to accomplish the following objectives: - [Embed HTML text or display dynamic reports](xml/provide-help-text-hyperlinks-web-content-form.md) - [Add a links-control page](/previous-versions/azure/devops/reference/xml/linkscontroloptions-xml-elements) - ## Add or remove a work item type from the backlog or task board @@ -222,7 +211,6 @@ For example, you can add bugs from the product backlog page. To learn how to add or remove work item types from the backlog or task board, see [Add a work item type to a backlog and board](add-wits-to-backlogs-and-boards.md). To add a new work item type to support a portfolio backlog, see [Add a portfolio backlog level](add-portfolio-backlogs.md). - ## Change the color, icon, or workflow state color of a work item type @@ -232,7 +220,6 @@ In the web portal, work items appear in query results and on the backlog and boa Screenshot of Query results showing work item type color, icon, and state color. - ## Change the type of an existing work item See [Bulk move work items and change the work item type](../boards/backlogs/move-change-type.md) for the features available to you based on your platform. @@ -246,7 +233,6 @@ If you want to restrict creation of a specific work item type to a group of user > [!NOTE] > You can't add field rules to restrict the workflow as you can't apply rules to system fields. - ## Delete a work item type @@ -259,7 +245,7 @@ witadmin destroywitd /collection:"http://FabrikamPrime:8080/tfs/DefaultCollectio When you delete a work item type that belongs to a category, you must update the categories definition for the project to reflect the new name. For more information, see [Import, export, and manage work item types](witadmin/witadmin-import-export-manage-wits.md) and [Import and export categories](/previous-versions/azure/devops/reference/witadmin/witadmin-import-export-categories). - + ## Rename a work item type @@ -273,19 +259,6 @@ When you rename a work item type that belongs to a category, you have to update For more information, see [Import, export, and manage work item types](witadmin/witadmin-import-export-manage-wits.md) and [Import and export categories](/previous-versions/azure/devops/reference/witadmin/witadmin-import-export-categories). - -::: moniker range="tfs-2018" - -## Enable features after upgrade - -What customizations can you make and still use the Configure Features Wizard to update my project after an on-premises upgrade? - -You can add custom work item types and change the form layout. The [Configure Features Wizard](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade?view=tfs-2017&preserve-view=true) will update your projects and you'll get access to the latest features. - -Changing the workflow or renaming a work item type might require you to perform some manual operations when updating your project. To learn about other customizations that you can safely make and which you should avoid, see [Customize the work tracking experience: Before you customize, understand the maintenance and upgrade implications](on-premises-xml-process-model.md#before-you-customize). - -::: moniker-end - ## Related articles This article addressed how to add and customize work item types for Hosted XML and On-premises XML process models. For information on adding and customizing work item types for the Inherited process model, see [Customize a process](../organizations/settings/work/customize-process.md). diff --git a/docs/reference/add-portfolio-backlogs.md b/docs/reference/add-portfolio-backlogs.md index 0aecf6ab95c..f17bd9fe12e 100644 --- a/docs/reference/add-portfolio-backlogs.md +++ b/docs/reference/add-portfolio-backlogs.md @@ -57,7 +57,7 @@ This article walks you through adding a portfolio backlog to a project based on You can apply the same steps if you work with a project based on the [Scrum](../boards/work-items/guidance/scrum-process.md) or [CMMI](../boards/work-items/guidance/cmmi-process.md) process. When you're done, you'll get to manage your portfolio of projects by grouping work within these four levels: User Stories (or Product backlog items or Requirements), Features, Epics, and Initiatives. -For more informaiton, see [About processes and process templates](../boards/work-items/guidance/choose-process.md). For an overview of the three process models, see [Customize your work tracking experience](customize-work.md). +For more information, see [About processes and process templates](../boards/work-items/guidance/choose-process.md). For an overview of the three process models, see [Customize your work tracking experience](customize-work.md). @@ -76,43 +76,43 @@ For more informaiton, see [About processes and process templates](../boards/work The easiest way to create a work item type (WIT) is to copy an existing one, rename it, and edit it to support your requirements. In this example, we copy the Epic WIT and label it Initiative.
        -
      1. Copy the Epic WIT definition to an XML file labeled Initiative. (The Epic.xml file is located in the WorkItem Tracking folder of the ProcessTemplate folder.)
        2. +- Copy the `Epic` WIT definition to an XML file labeled `Initiative`. (The Epic.xml file is located in the WorkItem Tracking folder of the ProcessTemplate folder.)
        -
      2. Edit the file named Initiative.
        +- Edit the file named `Initiative`.
          -
        1. Rename the WIT. Replace WORKITEMTYPE name="Epic" with WORKITEMTYPE name="Initiative", and update the description.
          -<WORKITEMTYPE name="Initiative" >
          -   <DESCRIPTION>Initiatives help program managers to effectively manage and organize work across several teams >
          -   </DESCRIPTION>
          -. . .
          -</WORKITEMTYPE>
          -
          2. -
        2. Add any custom fields that you want to track using this WIT.
          3. -
        3. Rename the Tab section named Features to Epics and replace Filter WorkItemType="Feature" with Filter WorkItemType="Epic".
          -<Tab Label="Epics">
          -<Control Type="LinksControl" Name="Hierarchy">
          -   <LinksControlOptions>
          -   <WorkItemLinkFilters FilterType="include">
          -   <Filter LinkType="System.LinkTypes.Hierarchy" />
          -   </WorkItemLinkFilters>
          -   <WorkItemTypeFilters FilterType="include">
          -      <Filter WorkItemType="Epic" />
          -   </WorkItemTypeFilters>
          -      <ExternalLinkFilters FilterType="excludeAll" />
          -      <LinkColumns>
          -          <LinkColumn RefName="System.ID" />
          -          <LinkColumn RefName="System.Title" />
          -          <LinkColumn RefName="System.AssignedTo" />
          -          <LinkColumn RefName="System.State" />
          -          <LinkColumn LinkAttribute="System.Links.Comment" />
          -          </LinkColumns>
          -   </LinksControlOptions>
          -</Control>
          -</Tab>
          +- Rename the WIT. Replace `WORKITEMTYPE name="Epic"` with `WORKITEMTYPE name="Initiative"`, and update the description.
          +`<WORKITEMTYPE name="Initiative" >`
          +   `<DESCRIPTION>Initiatives help program managers to effectively manage and organize work across several teams >`
          +   `</DESCRIPTION>`
          +`. . .`
          +`</WORKITEMTYPE>`
          +
          +- Add any custom fields that you want to track using this WIT.
          +- Rename the `Tab` section named `Features` to `Epics` and replace `Filter WorkItemType="Feature"` with `Filter WorkItemType="Epic"`.
          +`<Tab Label="Epics">`
          +`<Control Type="LinksControl" Name="Hierarchy">`
          +   `<LinksControlOptions>`
          +   `<WorkItemLinkFilters FilterType="include">`
          +   `<Filter LinkType="System.LinkTypes.Hierarchy" />`
          +   `</WorkItemLinkFilters>`
          +   `<WorkItemTypeFilters FilterType="include">`
          +      `<Filter WorkItemType="Epic" />`
          +   `</WorkItemTypeFilters>`
          +      `<ExternalLinkFilters FilterType="excludeAll" />`
          +      `<LinkColumns>`
          +          `<LinkColumn RefName="System.ID" />`
          +          `<LinkColumn RefName="System.Title" />`
          +          `<LinkColumn RefName="System.AssignedTo" />`
          +          `<LinkColumn RefName="System.State" />`
          +          `<LinkColumn LinkAttribute="System.Links.Comment" />`
          +          `</LinkColumns>`
          +   `</LinksControlOptions>`
          +`</Control>`
          +`</Tab>`

          With this change, you cause the tab control to exclusively show or link to epics as child work items of the initiative.

          -
          4. +
        -
        3. +
      @@ -259,7 +259,7 @@ We've just shown how to add another portfolio backlog level. You can add up to f If you want to add another WIT to your backlogs or boards, see [work item types to backlogs and boards](add-wits-to-backlogs-and-boards.md). -To learn more about the syntax for a definition file or command line tool, see these topics: +For more information about the syntax for a definition file or command line tool, see these topics: - [All WITD XML elements reference](/previous-versions/azure/devops/reference/xml/all-witd-xml-elements-reference) - [Categories XML element reference](/previous-versions/azure/devops/reference/xml/categories-xml-element-reference) diff --git a/docs/reference/add-wits-to-backlogs-and-boards.md b/docs/reference/add-wits-to-backlogs-and-boards.md index c51b17d9e4a..06979f143e5 100644 --- a/docs/reference/add-wits-to-backlogs-and-boards.md +++ b/docs/reference/add-wits-to-backlogs-and-boards.md @@ -20,7 +20,7 @@ ms.date: 08/03/2021 > [!IMPORTANT] > This article applies to project customization for Hosted XML and On-premises XML process models. For the Inheritance process model, see [Customize your backlogs or boards for a process](../organizations/settings/work/customize-process.md). For an overview of process models, see [Customize your work tracking experience](customize-work.md). -To satisfy select business processes, your team may want to track additional work item types (WITs) as requirements or as tasks. This way, you can add them and track them within the product and sprint backlogs or Kanban and task boards. +To satisfy select business processes, your team may want to track additional work item types (WITs) as requirements or as tasks. This way, you can add them and track them within the product and sprint backlogs or board and Taskboards. For example, you may want to track different types of requirements based on their target customer, or different types of bugs based on their source. Here the Fabrikam Fiber team has added the Service App WIT to track work that supports their customer service team. @@ -72,7 +72,7 @@ You'll first export your work tracking definition files, update them, and then i ## Add a WIT to track it like a requirement -WITs that you add to the Requirement Category show up on the product backlog and Kanban board. You must make sure that the WIT definition contains required fields to support the Agile planning tools. +WITs that you add to the Requirement Category show up on the product backlog and board. You must make sure that the WIT definition contains required fields to support the Agile planning tools. 1. Export your process (Hosted XML) or your definition files (On-premises XML) as indicated in [First steps](#first-steps). 2. Edit the WIT definition to support planning tools. @@ -107,7 +107,7 @@ WITs that you add to the Requirement Category show up on the product backlog and **Value Area** field > [!div class="tabbedCodeSnippets"] ```XML - @@ -191,7 +191,7 @@ WITs that you add to the Requirement Category show up on the product backlog and 4. Update or verify ProcessConfiguration definition: `RequirementBacklog` section for the WIT you're adding. Specifically, make sure that the following conditions are met: - Map the start of each workflow state to `type="Proposed"` - - Map each intermediate workflow state you want to have show up on the Kanban board to `type="InProgress"` + - Map each intermediate workflow state you want to have show up on the board to `type="InProgress"` - Map the end of each workflow state to `type="Complete"` - Make sure that you have only one State mapped to `type="Complete"` For example, add the Pending workflow state: @@ -432,7 +432,7 @@ WITs that you add to the Bug Category will be treated based on the [team setting Specifically, make sure that the following conditions are met: - Map the start of each workflow state to `type="Proposed"` - - Map each intermediate workflow state you want to have show up on the Kanban or task board to `type="InProgress"` + - Map each intermediate workflow state you want to have show up on the board or Taskboard to `type="InProgress"` - Map the end of each workflow state to `type="Complete"` - Make sure that you have only one State mapped to `type="Complete"` diff --git a/docs/reference/customize-work.md b/docs/reference/customize-work.md index 48b06fef1b1..a08dce51158 100644 --- a/docs/reference/customize-work.md +++ b/docs/reference/customize-work.md @@ -1,7 +1,7 @@ --- title: Customize your work tracking experience titleSuffix: Azure DevOps -description: Guide to configuring and customizing work tracking features in Azure DevOps +description: Guide to configuring and customizing work tracking features. ms.service: azure-devops-boards ms.custom: process ms.assetid: D1B44480-F88B-4F35-927A-11ADFBCBAA23 @@ -9,76 +9,65 @@ ms.author: chcomley author: chcomley ms.topic: overview monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 06/05/2024 --- # Customize your work tracking experience [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -As you plan and track your project, you'll find you may want to configure a feature or customize your experience to meet your team's tracking needs. You configure teams and team Agile tools through the web portal administration context for Azure Boards. The method you use to customize projects, which impacts all teams, depends on the process model you use. +As you plan and track your project, consider configuring a feature or customizing your experience to align with your team's tracking requirements. The approach for customizing projects, which affects all teams, depends on the process model you’re using. -If you're new to Azure Boards and work item tracking, see [What is Azure Boards?](../boards/get-started/what-is-azure-boards.md) and [Track work with user stories, issues, bugs, features, and epics](../boards/work-items/about-work-items.md). - -This article provides a high-level overview of the customizations you can make and how they differ for the three process models. For guidance on customizations to make to support business decisions, see [Configure and customize Azure Boards](../boards/configure-customize.md). - -Customizations you make occur at one of these four levels: +This article gives you an overview of the customizations available and how they vary across the three process models. For specific guidance on customizations to support business decisions, [Configure and customize Azure Boards](../boards/configure-customize.md). For more information, see [What is Azure Boards?](../boards/get-started/what-is-azure-boards.md) and [About work items](../boards/work-items/about-work-items.md). +You can customize at the following levels of work tracking: ::: moniker range="azure-devops" -- **Project-level shared resources**: Define area and iteration paths which teams select to configure their backlogs and boards. Shared queries and work item tags are additional objects that once defined can be shared across the project. -- **Team assets or tools**: Each team can configure their specific tools, such as backlogs, boards, and dashboards. For details, see [About teams and Agile tools](../organizations/settings/about-teams-and-settings.md). -- **Project and object-level permissions**: Grant or restrict access to work tracking tools, which includes setting permissions for objects and the project and assigning users or groups to specific access levels. +- **[Project-level shared resources](#project-level-shared-resources)**: Define area and iteration paths which teams select to configure their backlogs and boards. Shared queries and work item tags are more objects that once defined can be shared across the project. +- **Team assets or tools**: Each team can configure their specific tools, such as backlogs, boards, and dashboards. For more information, see [About teams and Agile tools](../organizations/settings/about-teams-and-settings.md). +- **Project and object-level permissions**: Manage access to work tracking tools, which include setting permissions for objects and the project and assigning users or groups to specific access levels. - **Organization-level process customization**: Customize the fields, work item types, and backlogs and boards available to all teams. ::: moniker-end - - ::: moniker range="< azure-devops" -- **Project-level shared resources**: Define area and iteration paths which teams select to configure their backlogs and boards. Shared queries and work item tags are additional objects that once defined can be shared across the project. -- **Team assets or tools**: Each team can configure their specific tools, such as backlogs, boards, and dashboards. For details, see [About teams and Agile tools](../organizations/settings/about-teams-and-settings.md). -- **Project and object-level permissions**: Grant or restrict access to work tracking tools, which includes setting permissions for objects and the project and assigning users or groups to specific access levels. +- **Project-level shared resources**: Define area and iteration paths which teams select to configure their backlogs and boards. Shared queries and work item tags are more objects that once defined can be shared across the project. +- **Team assets or tools**: Each team can configure their specific tools, such as backlogs, boards, and dashboards. For more information, see [About teams and Agile tools](../organizations/settings/about-teams-and-settings.md). +- **Project and object-level permissions**: Manage access to work tracking tools, which include setting permissions for objects and the project and assigning users or groups to specific access levels. - **Collection-level process customization**: Customize the fields, work item types, and backlogs and boards available to all teams. ::: moniker-end - ## Project-level shared resources -Each project provides a number of shared resources that support all teams added to the project. You configure these features through the user interface or the admin context of the web portal. To understand how the system uses area and iteration paths, see [About area and iteration paths](../organizations/settings/about-areas-iterations.md). - -> [!div class="mx-tdCol2BreakAll"] -> | Area path pick lists | Sprint/iteration pick lists | -> |-------------|----------| -> |Change the [pick list of area paths](../organizations/settings/set-area-paths.md) to support grouping work items by team, product, or feature area.
      ![Hierarchical area paths](../user-guide/media/features/alm-feature-area-paths.png)|Change the [pick list of iteration paths](../boards/sprints//define-sprints.md) to support grouping work into sprints, milestones, or other event-specific or time-related period. Activate sprints for each team.
      ![Iterations or sprints](../user-guide/media/features/alm-feature-define-sprints.png) | - - -> [!div class="mx-tdCol2BreakAll"] -> |Shared queries | Tags | -> |-------------|----------| -> |Open shared queries or create your own
      query using the [query editor](../boards/queries/using-queries.md) to list work items
      or show hierarchical or dependent items.
      ![Add tags to filter backlogs, boards, and queries](media/alm-feature-tags.png) | - +Each project provides many shared resources that support all teams within the project. You configure these features through the user interface or the admin context of the web portal. For more information, see the following articles: +- [About area and iteration paths](../organizations/settings/about-areas-iterations.md) +- [Set area paths](../organizations/settings/set-area-paths.md) +- [Change the pick list for an iteration path](../boards/sprints/define-sprints.md) +- [Create and edit queries](../boards/queries/using-queries.md) +- [Add tags to work items](../boards/queries/add-tags-to-work-items.md) -### Identity fields, people-picker fields +### People picker and identity fields -The **Assigned To** and other Identity fields are supported by the people picker feature. For example, when you choose the **Assigned To** field from within a work item form, the people picker is activated. As shown in the following image, you simply start typing the name of the user you want to select, and search until you find a match. Users that you've previously selected appear in the list automatically. To select users that you haven't selected previously, simply enter their entire name or search against the full directory. +- The **Assigned To** and other **Identity** fields are supported by the people picker feature. +- When you choose the **Assigned To** field within a work item form, the people picker is activated. +- To select a user, start entering their name and search until you find a match. +- Previously selected users appear automatically in the list. +- For organizations using Microsoft Entra ID or Active Directory, people pickers allow searching all users and groups added to the AD (not just ones added to a specific project). +- To limit the scope of identities available for selection to project-specific users, use the **Project-Scoped Users** group. +- Custom rules can further restrict the values available for Identity fields within a work item. > [!div class="mx-imgBorder"] > ![Screenshot of people picker Assigned To field.](../organizations/notifications/media/at-mention/identity-selector.png) -For organizations that manage their users and groups using Azure Active Directory (Azure AD) or Active Directory, people pickers provide support for searching all users and groups added to the AD, not just those added to the project. To learn more, see [Add AD/Azure AD users or groups to a built-in security group](../organizations/security/add-ad-aad-built-in-security-groups.md). - +For more information, see the following articles: +- [Add Active Directory / Microsoft Entra users or groups to a built-in security group](../organizations/security/add-ad-aad-built-in-security-groups.md). ::: moniker range="azure-devops" - -To limit the scope of identities available for selection to just those users added to the project, you can do so using the **Project-Scoped Users** group. To learn how, see [Manage your organization, Limit identity search and selection](../user-guide/manage-organization-collection.md#limit-identity-selection). - +- [Limit identity search](../user-guide/manage-organization-collection.md#limit-user-visibility-for-projects-and-more). ::: moniker-end -You can limit the values available to Identity fields within a work item by adding a custom rule. - @@ -96,7 +85,7 @@ You can limit the values available to Identity fields within a work item by addi ::: moniker-end -Your project determines the objects available to track work and the configuration of Agile tools. Specifically, the project determines the work item types (WITs)—user stories, tasks, bugs— and the data fields used to capture information. Customized objects are shared across teams added to the project. +Your project defines the work item types (WITs) available for tracking work and configures Agile tools. It specifies user stories, tasks, bugs, and the data fields used to capture information. Customized objects are shared across teams within the project. > [!NOTE] >The method you use to customize work tracking depends on the process model you subscribe to: @@ -104,7 +93,7 @@ Your project determines the objects available to track work and the configuratio >- **Hosted XML**: Supports customization through import/export of process templates, available for a select number of customers of Azure DevOps Services who have opted into this model. >- **On-premises XML**: Supports customization through import/export of XML definition files for work tracking objects and is available for all on-premises deployments. -The following table summarizes the differences between the three supported process models. For definitions of the main work tracking objects, see [Agile glossary](../boards/work-items/agile-glossary.md). For links to all customization articles, see [Quick reference index for Azure Boards settings](quick-reference-index-boards-settings.md). +The following table summarizes the differences between the three supported process models. For definitions of the main work tracking objects, see [Agile glossary](../boards/work-items/agile-glossary.md). For links to customization articles, see [Quick reference index for Azure Boards settings](quick-reference-index-boards-settings.md). --- :::row::: @@ -242,27 +231,11 @@ The following table summarizes the differences between the three supported proce :::column-end::: :::row-end::: --- -::: moniker range="< azure-devops-2020" -:::row::: - :::column span="3"::: - Update Microsoft field mappings using the [**TFSFieldMapping**](/previous-versions/azure/devops/reference/xml/upload-or-download-the-microsoft-project-mapping-file) command-line tool (see note 4) - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: ---- -::: moniker-end + ::: moniker range="azure-devops" :::row::: :::column span="3"::: - Use [**az boards** command-line tools](../cli/quick-reference.md#azure-boards) to edit projects and teams and list information + Use [**`az boards`** command-line tools](../cli/quick-reference.md#azure-boards) to edit projects and teams and list information :::column-end::: :::column span="1"::: ✔️ @@ -278,7 +251,7 @@ The following table summarizes the differences between the three supported proce ::: moniker-end :::row::: :::column span="3"::: - Use the [**witadmin** command-line tools](witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) to list and export process information + Use the [**`witadmin`** command-line tools](witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) to list and export process information :::column-end::: :::column span="1"::: ✔️ @@ -294,7 +267,7 @@ The following table summarizes the differences between the three supported proce ::: moniker range="< azure-devops" :::row::: :::column span="3"::: - Use the [**witadmin** command-line tools](witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) to edit process information + Use the [**`witadmin`** command-line tools](witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) to edit process information :::column-end::: :::column span="1"::: @@ -311,7 +284,7 @@ The following table summarizes the differences between the three supported proce ::: moniker range="< azure-devops" :::row::: :::column span="3"::: - Use the [**tcm fieldmapping** command-line tool](witadmin/tcm-customize-manage-test-experience.md) to list and export test case management mapping for resolution types, bug filing, and failure types. + Use the [**`tcm fieldmapping`** command-line tool](witadmin/tcm-customize-manage-test-experience.md) to list and export test case management mapping for resolution types, bug filing, and failure types. :::column-end::: :::column span="1"::: @@ -356,13 +329,12 @@ The following table summarizes the differences between the three supported proce :::row-end::: --- - **Notes:** 1. A process determines the building blocks used to track work. A process template specifies an interdependent-related set of XML definition files that provide the building blocks and initial configuration for tracking work and other functional areas. -2. Hosted XML customization supports adding and updating global lists with a process update (subject to limits on maximum size of each list). To learn more, see [Work tracking object limits](../organizations/settings/work/object-limits.md). +2. Hosted XML customization supports adding and updating global lists with a process update (subject to limits on maximum size of each list). For more information, see [Work tracking object limits](../organizations/settings/work/object-limits.md). 3. The Inherited process model doesn't support customization of the following features available with customization of process templates. Instead, you customize these areas within the web portal on a project-by-project basis. - - Configure Area Paths and Iteration Paths + - Area and iteration paths - Work item queries - Security groups and permissions - Permissions and access to functional areas such as version control and build @@ -372,52 +344,50 @@ The following table summarizes the differences between the three supported proce ::: moniker range="azure-devops" Or, you can use [REST APIs](/rest/api/azure/devops/wit/classification-nodes/create-or-update) or the [Azure DevOps CLI command tool](../cli/quick-reference.md). ::: moniker-end -4. Support for Office Project integration with Azure DevOps is deprecated starting with Azure DevOps Server 2019. The TFSFieldMapping command is not supported for Azure DevOps Server 2019 and later versions, including Azure DevOps Services. Starting with Visual Studio 2019, the Azure DevOps plug-in for Office no longer supports Office Project. -5. You can use the REST API to [import and export process templates](/rest/api/azure/devops/processadmin/processes/import%20process%20template). +4. Support for Office Project integration with Azure DevOps is deprecated and the `TFSFieldMapping` command isn't supported. +5. Use the REST API to [import and export process templates](/rest/api/azure/devops/processadmin/processes/import%20process%20template). - + -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="< azure-devops" ## Choose the process model for your project collection -For Azure DevOps Server 2019 and Azure DevOps Server 2020, you have a choice of process models. When you create a project collection, you'll need to choose between **XML** (On-premises XML process model) and **Inheritance** (Inheritance process model), as shown in the following dialog. +For Azure DevOps Server 2019 and Azure DevOps Server 2020, you can choose between **XML** (On-premises XML process model) and **Inheritance** (Inheritance process model), as shown in the following dialog. > [!div class="mx-imgBorder"] -> ![Create Team Project Collection wizard, Collection Name dialog](media/azd-2019/configure-new-collection-inheritance.png) +> ![Screenshot showing Create Team Project Collection wizard, Collection Name dialog.](media/azd-2019/configure-new-collection-inheritance.png) > [!IMPORTANT] -> The choice you make is not reversible. Once the collection is created, you'll only be able to customize work tracking objects using the model selected. Also, there is no way to migrate existing project collections that use the On-premises XML process model to the Inheritance process model. +> The process choice you make is irreversible. Once it's set up, you can only customize work tracking objects based on the selected model. Also, existing project collections using the On-premises XML process model can't get migrated to the Inheritance process model. -To learn more about project collections, see [Manage project collections](/azure/devops/server/admin/manage-project-collections). +For more information, see [Manage project collections](/azure/devops/server/admin/manage-project-collections). ::: moniker-end - - - ## Customize the test experience -::: moniker range=">= azure-devops-2019" -Several work item types support the test experience within the web portal **Test** pages and Test Manager client. For an Inherited process, you can customize Test Plan, Test Suite, and Test Case, work item types as you would any other work item type. For an On-premises XML process, you can customize all test-related work item types—Test Plan, Test Suite, Test Case, Shared Steps, and Shared Parameters—as you would any other work item type. -::: moniker-end - -::: moniker range="tfs-2018" -Several work item types support the test experience within the web portal **Test** pages and Test Manager client. You can customize these work item types—Test Plan, Test Suite, Test Case, Shared Steps, and Shared Parameters—as you would any other work item type. -::: moniker-end - -The following image illustrates the supported link relationships. +Several work item types support the test experience within the web portal **Test** pages and Test Manager client. +- For an **Inherited process**, you can customize the following work item types as you would any other work item type: + - Test Plan + - Test Suite + - Test Case +- For an **On-premises XML process**, you can customize all test-related work item types, including: + - Test Plan + - Test Suite + - Test Case + - Shared Steps + - Shared Parameters - ![Test management work item types](../boards/work-items/guidance/media/ALM_PT_WITS_TestExperience.png) +The following example shows the supported link relationships. + ![Screenshot showing Test management work item types.](../boards/work-items/guidance/media/ALM_PT_WITS_TestExperience.png) ::: moniker range="< azure-devops" -See the following resources for additional usage and customization information: - -- [Test configurations and test variables](../test/test-different-configurations.md) -- [Test resolution states](witadmin/tcm-customize-manage-test-experience.md) (TFS) +For more information, see the following articles: +- [Test configurations and test variables](../test/test-different-configurations.md) - [Failure types](witadmin/tcm-customize-manage-test-experience.md) - [Define the initial test management configuration (process template)](process-templates/define-initial-configuration-test-manager.md) - [Query based on build and test integration fields](../boards/queries/build-test-integration.md) @@ -425,13 +395,13 @@ See the following resources for additional usage and customization information: ## Less common customizations -You can only perform the following customizations when working with the Hosted XML or On-premises XML process models. Customizations made to process configuration apply to all teams added to a project. +You can only perform the following customizations when working with the Hosted XML or On-premises XML process models. Customizations made to process configuration apply to all teams within a project. ### Backlog and board limits (Hosted XML, On-premises XML) -To limit the display load time to acceptable parameters, the task board is restricted to a maximum of 1000 work items. For details, see [Process configuration XML element reference](xml/process-configuration-xml-element.md). +To limit the display load time to acceptable parameters, the task board is restricted to a maximum of 1,000 work items. For details, see [Process configuration XML element reference](xml/process-configuration-xml-element.md). You can increase this value up to a maximum of 1500 by specifying a value for the `workItemCountLimit` attribute of the **TaskBacklog** element. For details, see [Process configuration XML element reference](xml/process-configuration-xml-element.md#backlog_page). @@ -448,7 +418,7 @@ You can increase this value up to a maximum of 1500 by specifying a value for th You can change the work item fields that are used in calculating capacity, burndown charts, forecasting, and velocity. Any change you make to one of the default assignments should correspond to a change made to the WIT used to define and capture information for that value. -For example, if you change the `refname` assigned to `type="Activity"` then you should include the same field in the WIT definition assigned to the Task Category which captures the activity information. For details, see [Process configuration XML element reference](xml/process-configuration-xml-element.md#fields). +For example, if you change the `refname` assigned to `type="Activity"` then you should include the same field in the WIT definition assigned to the Task Category that captures the activity information. For details, see [Process configuration XML element reference](xml/process-configuration-xml-element.md#fields). The fields you assign are used by the following tools: @@ -460,17 +430,23 @@ The fields you assign are used by the following tools: | Task board, capacity tools | Remaining work | | Capacity tools | Activity (Task Activity or Discipline) | - -## Grant or restrict access to work tracking tools +## Manage access to work tracking tools -You can grant or restrict access to select features through permission settings. When you add user accounts to your team, they're automatically added to the Contributor group. They then have access to most of the features they'll need to contribute to code, work tracking, builds, and test. However, the Contributor group doesn't allow users to create shared queries or to add area or iteration paths. You have to grant these permissions separately. +Manage access to specific features through permission settings. When you add user accounts to your team, they're automatically added to the Contributor group. They then have access to most of the features they'll need to contribute to code, work tracking, builds, and test. However, the Contributor group doesn't allow users to create shared queries or to add area or iteration paths. You have to grant these permissions separately. -For a simplified view of the most common, default permissions and access assignments, see [Permissions and access](../organizations/security/permissions-access.md). If you're new to managing permissions, see [Get started with permissions, access, and security groups, Permission inheritance and security groups](../organizations/security/about-permissions.md#inheritance). +You can manage access with the following permission settings: +- When you add user accounts to your team, they’re automatically added to the **Contributor** group. +- The **Contributor** group provides access to most features needed for contributing to code, work tracking, builds, and testing. +- But, the **Contributor** group doesn’t allow users to: + - Create shared queries + - Add area or iteration paths + - To grant these permissions separately, follow the appropriate steps. +- For a simplified overview of common default permissions and access assignments, see [Permissions and access](../organizations/security/permissions-access.md). +If you’re new to managing permissions, explore [Get started with permissions, access, and security groups, Permission inheritance and security groups](../organizations/security/about-permissions.md#permission-inheritance). -Otherwise, to grant or restrict access to select features, review one of these topics: - +To manage access to specific features, see the following articles: --- :::row::: @@ -479,7 +455,7 @@ Otherwise, to grant or restrict access to select features, review one of these t - [About access levels](../organizations/security/access-levels.md) - [Add team members (Azure DevOps Services)](../organizations/security/add-users-team-project.md) - [Change access levels (on-premises deployments)](../organizations/security/change-access-levels.md) - - [Add team members (on-premises deployments)](../organizations/settings/add-teams.md#add-team-members) + - [Add team members (on-premises deployments)](../organizations/settings/add-teams.md) :::column-end::: :::column span="1"::: **Permissions** @@ -488,7 +464,7 @@ Otherwise, to grant or restrict access to select features, review one of these t - [Work item query and folder permissions](../boards/queries/set-query-permissions.md) - [Dashboard permissions](../report/dashboards/dashboard-permissions.md#set-permissions) - [Delivery Plan permissions](../organizations/security/set-permissions-access-work-tracking.md) - - [Tagging permissions](../organizations/security/permissions.md#tags) + - [Tagging permissions](../organizations/security/permissions.md) - [Test permissions](../organizations/security/permissions.md#project_test) :::column-end::: :::column span="1"::: @@ -501,32 +477,25 @@ Otherwise, to grant or restrict access to select features, review one of these t :::column-end::: :::row-end::: --- - - -## Additional customization options +## More customization options -Do you want to customize your tools in a way that's not supported? - -Here are a few options available to you: +Choose from the following other customization options: - Check out [Marketplace extensions](https://marketplace.visualstudio.com/vsts) to see if there's a tool available for your purposes - [Develop your own extension](../extend/get-started/node.md) -- Determine if a [Service hook](../service-hooks/overview.md) will satisfy your needs +- Determine if a [Service hook](../service-hooks/overview.md) satisfies your needs - Create your own tool using [REST APIs](../integrate/index.md) - Add a feature request to our [Developer Community page](https://developercommunity.visualstudio.com/content/idea/post.html?space=21). -## Try this next +## Next steps > [!div class="nextstepaction"] > [Configure and customize Azure Boards](../boards/configure-customize.md?toc=/azure/devops/reference/toc.json&bc=/azure/devops/reference/breadcrumb/toc.json) ## Related articles - [Work item field index](../boards/work-items/guidance/work-item-field.md) -- [witadmin command-line tool](witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) +- [witAdmin command-line tool](witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) - [Manage process templates](../boards/work-items/guidance/manage-process-templates.md) - [Process templates overview](process-templates/overview-process-template-files.md) -- [Naming restrictions and conventions](../organizations/settings/naming-restrictions.md?toc=/azure/devops/reference/toc.json&bc=/azure/devops/reference/breadcrumb/toc.json) - [Work tracking, process, and project limits](../organizations/settings/work/object-limits.md?toc=/azure/devops/reference/toc.json&bc=/azure/devops/reference/breadcrumb/toc.json) - - \ No newline at end of file diff --git a/docs/reference/media/area-picklist.png b/docs/reference/media/area-picklist.png new file mode 100644 index 00000000000..b6cd35ee65e Binary files /dev/null and b/docs/reference/media/area-picklist.png differ diff --git a/docs/reference/media/iteration-picklist.png b/docs/reference/media/iteration-picklist.png new file mode 100644 index 00000000000..c11ba578bbf Binary files /dev/null and b/docs/reference/media/iteration-picklist.png differ diff --git a/docs/reference/on-premises-xml-process-model.md b/docs/reference/on-premises-xml-process-model.md index 4b3d31475f7..9ea56ccfbc9 100644 --- a/docs/reference/on-premises-xml-process-model.md +++ b/docs/reference/on-premises-xml-process-model.md @@ -11,7 +11,6 @@ monikerRange: '< azure-devops' ms.date: 01/17/2023 --- - # On-premises XML process customization [!INCLUDE [version-lt-azure-devops](../includes/version-lt-azure-devops.md)] @@ -22,19 +21,16 @@ You customize your work tracking experience to support your business and reporti [!INCLUDE [temp](../boards/includes/note-configure-customize.md)] -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -For Azure DevOps Server 2019 and later versions, you have a choice of process models. When you create a project collection, you'll need to choose between On-premises XML process model and Inheritance process model. To learn more, see [Customize work tracking, Choose the process model for your project collection](./customize-work.md?view=azure-devops-2019&preserve-view=true#choose-process-model). +For Azure DevOps Server 2019 and later versions, you have a choice of process models. When you create a project collection, you'll need to choose between On-premises XML process model and Inheritance process model. For more information, see [Customize work tracking, Choose the process model for your project collection](./customize-work.md?view=azure-devops-2019&preserve-view=true#choose-process-model). ::: moniker-end -::: moniker range="tfs-2018" - -Team Foundation Server uses the On-premises XML process model to support customizations. This model relies on updating and importing XML files using the **witadmin** command line tool. -::: moniker-end + > [!IMPORTANT] -> Migration of projects or collections from Hosted XML to the inherited model is not support for Azure DevOps Server. It is only available on the Azure DevOps Sevice. +> Migration of projects or collections from Hosted XML to the inherited model is not support for Azure DevOps Server. It is only available on the Azure DevOps Services. > > To customize an Azure DevOps Services project, see [About process customization and inherited processes](../organizations/settings/work/inheritance-process-model.md). This article applies to on-premises deployments only. @@ -44,7 +40,6 @@ You can perform the following tasks when you work with the On-premises XML proce - :::row::: :::column span="1"::: **Area** @@ -153,7 +148,6 @@ In addition, you can use the **witadmin** tool to list objects, rename WITs, per [!INCLUDE [temp](../includes/process-editor.md)] - ## Maintenance and upgrade implications @@ -164,7 +158,6 @@ Upgrades to an on-premises deployment can introduce new features that require up To minimize the amount of manual work you'll need to do after an upgrade, understand which customizations support an easy update path and which do not. - ### Compatible for quick updating With the following customizations, you can use the Configure Features Wizard to automatically apply any changes to your project required for new features. @@ -172,12 +165,11 @@ With the following customizations, you can use the Configure Features Wizard to - Fields: Add custom fields, customize a pick list, add or modify area and iteration paths, add rules to a field - WITs: Add custom WITs, change the form layout - Categories: Add custom categories -- Agile tools: Customize the columns on the Kanban board, customize the quick add panel +- Agile tools: Customize the columns on the board, customize the quick add panel - Office integration: Add or change how Project fields map to TFS fields To learn more about the Configure Features Wizard, see [Configure features after an upgrade](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade). - ### Compatible, but may require manual updates The Configure Features Wizard requires that specific work item types, workflow states, and fields exist in the project. When you make the following customizations, you might need to modify your custom process for the wizard to run, or you might have to update your project manually. @@ -208,7 +200,6 @@ To learn more about reporting attributes, see [Add or modify work item fields to * Test your customized objects just as you would test your software. * Minimize the number of custom fields that you introduce. Minimize the number of fields that you make reportable. - ## Replace team area path with a team field The default configuration for projects associates each team with an area path. If your organization has several teams that work from a common backlog and across many product areas, this configuration might not fit how you want to organize your work. By adding a custom field to represent teams in your organization, you can reconfigure the agile planning tools and pages to support your teams and decouple assignment to teams and area paths. diff --git a/docs/reference/process-templates/customize-process.md b/docs/reference/process-templates/customize-process.md index 2f644d41521..44f2c06ef9d 100644 --- a/docs/reference/process-templates/customize-process.md +++ b/docs/reference/process-templates/customize-process.md @@ -1,15 +1,16 @@ --- title: Customize a process template titleSuffix: Azure DevOps -description: Define the objects and processes available to you when you create a project in Azure DevOps +description: Define the objects and processes available to you when you create a project in Azure DevOps. ms.custom: engagement-fy23 ms.service: azure-devops-boards ms.assetid: 3122f0e7-2ad9-46a1-a65f-32af37c0f444 ms.author: chcomley author: chcomley +ai-usage: ai-assisted ms.topic: reference monikerRange: '<= azure-devops' -ms.date: 01/13/2023 +ms.date: 10/08/2024 --- @@ -26,7 +27,6 @@ Process templates define the objects and processes available to you when you cre - Add or remove a work item type - Change the process configuration or defaults associated with Azure Boards hubs - > [!NOTE] > This article describes process templates used to create projects defined on Azure DevOps Services. If you're looking for **project templates** for software development, see [Creating Visual Studio templates](/visualstudio/ide/creating-project-and-item-templates). @@ -36,9 +36,9 @@ Default process templates define default configurations and work item types used Many of these artifacts depend on work item types that are used to track work. For example, data fields defined in the definition of Feature, Bug, User Story, or Task are also used to define work item queries. In addition to these artifacts, you can also define the initial project areas and iterations, security configuration, and other default settings that support test plans. - After you create a project, you can change configurations and customize artifacts. However, by customizing the process template before you create your projects, all resulting projects that you create from it will match a standard set of team processes. The main reasons you might want to customize a process template include: + After you create a project, you can change configurations and customize artifacts. However, by customizing the process template before you create your projects, all resulting projects that you create from it matches a standard set of team processes. The main reasons you might want to customize a process template include: -- You plan to create several projects and you want to minimize repetitive tasks that you'll have to implement later in each project that you create +- You plan to create several projects and you want to minimize repetitive tasks that you have to implement later in each project that you create - You want to make sure all teams adhere to certain standards by providing the templates and structures within the toolset your software development teams use - You need to update a custom process template to support using the Configure Features wizard after an upgrade @@ -46,7 +46,7 @@ If you work with only a single project, then you might consider simply creating ## How are process templates used? -The primary use of process templates is to create a project. For the Hosted XML process model, it is also used to update a project. A project provides the set of objects, artifacts, and configurations defined in the interdependent set of template files. You use your project to organize source code, track work and information, build software, and support test activities. +The primary use of process templates is to create a project. For the Hosted XML process model, it's also used to update a project. A project provides the set of objects, artifacts, and configurations defined in the interdependent set of template files. You use your project to organize source code, track work and information, build software, and support test activities. **Hosted XML process model** - [Create a project](../../organizations/projects/create-project.md) @@ -57,19 +57,19 @@ The primary use of process templates is to create a project. For the Hosted XML ## Where should I start? - Before you start customizing a process template, you'll want to become familiar with what you can configure and customize and then plan your changes accordingly. + Before you start customizing a process template, get familiar with what you can configure and customize and then plan your changes accordingly. - If you're new to process templates, first [review the default process templates](../../boards/work-items/guidance/choose-process.md). -- If you want to become familiar with the file structure of a process template, [review a description for each file](/previous-versions/azure/devops/reference/process-templates/overview-process-template-files) or [download a process template](../../boards/work-items/guidance/manage-process-templates.md). +- To get familiar with the file structure of a process template, [review a description for each file](/previous-versions/azure/devops/reference/process-templates/overview-process-template-files) or [download a process template](../../boards/work-items/guidance/manage-process-templates.md). - You can modify the processes for your project after it is created. As you work with a project, the initial settings that the process template defined may no longer meet your needs. + You can modify the processes for your project after it's created. As you work with a project, the initial settings that the process template defined might no longer meet your needs. - If you're most interested in customizing objects used to track work, which includes test plans, test suites, and test cases, review [Customize your work tracking experience](../customize-work.md). The customizations you make by modifying an XML definition file for a project are the same types of customizations you make in a process template file. - If you want to [add or modify types of work items](../add-modify-wit.md), you can achieve this without changing the whole process template. You can make and test changes by using an existing project. For the On-premises XML process model, you can use the **witadmin exportwitd** and **importwitd** command-line tools to download and upload the XML definition files for work item types. + To [add or modify types of work items](../add-modify-wit.md), you can do so without changing the whole process template. You can make and test changes by using an existing project. For the On-premises XML process model, you can use the **witadmin exportwitd** and **importwitd** command-line tools to download and upload the XML definition files for work item types. -- If you're considering making extensive customizations, [review how the changes you make will impact maintenance and upgrade of your projects](../on-premises-xml-process-model.md#before-you-customize). +- If you're considering making extensive customizations, [review how the changes you make impacts maintenance and upgrade of your projects](../on-premises-xml-process-model.md#before-you-customize). @@ -82,22 +82,18 @@ Process templates consist of nine plug-ins. Each plug-in defines a set of tasks ::: moniker range="< azure-devops-2022" > [!IMPORTANT] ->When you create a project from the web portal, several process template files are ignored. Specifically, the files that would create a Report Manager site aren't supported. To support reporting for a project collection, see [Add reports to a team project](/previous-versions/azure/devops/report/admin/add-reports-to-a-team-project). +> When you create a project from the web portal, several process template files are ignored. Specifically, the files that would create a Report Manager site aren't supported. To support reporting for a project collection, see [Add reports to a team project](/previous-versions/azure/devops/report/admin/add-reports-to-a-team-project). ::: moniker-end -To customize a process template, you customize one or more files associated with a functional area. While customizing any one object is fairly simple, you'll want to make sure that you don't break any inter-dependencies when you customize. The [ProcessTemplate.xml plug-in file](/previous-versions/azure/devops/reference/process-templates/define-root-tasks-process-template-plug-in) defines which plug-ins to include in the template. This file contains all the task groups that you want to run to create a project. Each task group references a subordinate XML plug-in file where the specific tasks for that plug-in are defined. +To customize a process template, you customize one or more files associated with a functional area. While customizing any one object is fairly simple, make sure that you don't break any inter-dependencies when you customize. The [ProcessTemplate.xml plug-in file](/previous-versions/azure/devops/reference/process-templates/define-root-tasks-process-template-plug-in) defines which plug-ins to include in the template. This file contains all the task groups that you want to run to create a project. Each task group references a subordinate XML plug-in file where the specific tasks for that plug-in are defined. - **Teams, groups, permissions, & area and iteration paths** - ::: moniker range="> tfs-2018" - - [Area and iteration paths](/previous-versions/azure/devops/reference/process-templates/define-classification-plug-in) - - [Groups, teams, members, and permissions](/previous-versions/azure/devops/reference/process-templates/configure-initial-groups-teams-members-permissions) - ::: moniker-end - ::: moniker range="tfs-2018" + ::: moniker range="<=azure-devops" - [Area and iteration paths](/previous-versions/azure/devops/reference/process-templates/define-classification-plug-in) - [Groups, teams, members, and permissions](/previous-versions/azure/devops/reference/process-templates/configure-initial-groups-teams-members-permissions) - - [Microsoft Project mapping file](/previous-versions/azure/devops/reference/xml/map-microsoft-project-fields-to-tf-fields) ::: moniker-end + - **Work item tracking** - [WIT definitions](/previous-versions/azure/devops/reference/process-templates/add-wit-definitions-process-template) @@ -118,14 +114,14 @@ When you add objects to a process template, make sure that you label them correc - Restrictions are put on the names or labels of most Team Foundation objects. For an overview of naming restrictions that apply to process templates, security groups, area and iteration nodes, work item types, and work item fields, see [Naming restrictions](../../organizations/settings/naming-restrictions.md). -- Most process template components that you customize will affect only the project that you create by using the process template. The exceptions to this rule are global lists, link types, and work item fields. These objects are defined for a project collection. +- Most process template components that you customize affect only the project that you create by using the process template. The exceptions to this rule are global lists, link types, and work item fields. These objects are defined for a project collection. -- Each work item field has an associated field reference name that uniquely identifies each field. The reference name cannot be changed after it is assigned. +- Each work item field has an associated field reference name that uniquely identifies each field. The reference name can't be changed after it's assigned. ::: moniker range="< azure-devops-2022" - In addition,if you are using SQL Server Reporting Services for your project collection, the reporting name assigned to a work item field must match across all work item types that are defined for the project collection. If they do not, validation errors might occur when you upload the process template, or conflicts might occur in the data warehouse databases. + In addition, if you're using SQL Server Reporting Services for your project collection, the reporting name assigned to a work item field must match across all work item types that are defined for the project collection. If they don't, validation errors might occur when you upload the process template, or conflicts might occur in the data warehouse databases. ::: moniker-end - Work item field names, link type names, and global lists are scoped to a project collection. If you customize any of these objects, the change will be reflected in all projects that are defined in the collection and in the work item types that contain that work item field. + Work item field names, link type names, and global lists are scoped to a project collection. If you customize any of these objects, the change is reflected in all projects that are defined in the collection and in the work item types that contain that work item field. - The maximum size of a process template is two gigabytes. When you customize a process template, make sure that your changes don't increase its size beyond that value. @@ -133,7 +129,7 @@ When you add objects to a process template, make sure that you label them correc ## Steps to customize a process template -Customizing a process template is an iterative process. You will need a project collection that is defined on a server that is running Azure DevOps Server where you can test your process template to make sure that it was customized correctly. +Customizing a process template is an iterative process. You need a project collection that is defined on a server that is running Azure DevOps Server where you can test your process template to make sure that it was customized correctly. To customize a process template, you first download an existing process template, modify or add files, upload the process template files, and then verify your changes. @@ -142,21 +138,11 @@ Customizing a process template is an iterative process. You will need a project |Step|Task| |----------|----------| |![Step 1](media/procguid_1.png "ProcGuid_1")|[Download a process template](../../boards/work-items/guidance/manage-process-templates.md). Before you can customize a process template, you must download it to your local computer.

      To minimize the modifications that you must make, [select a template](../../boards/work-items/guidance/choose-process.md) that most closely matches your team processes. In general, you choose a process template based on types of work items and workflow.| -|![Step 2](media/procguid_2.png "ProcGuid_2")|**Modify or add files**. You customize a process template by modifying, deleting, or adding files that are defined for a process template. You customize a plug-in or definition file by modifying its XML content. Each plug-in file and type definition file must conform to its XML schema definition.

      The first time that you customize a process template, make a small change. If you make many changes without a good understanding of how the changes may affect your template, you risk encountering multiple mistakes that will be difficult to debug.

      Make sure that the name of your process template is unique. If you download a process template, make changes, and upload it, you must change its name or it will over-write the existing process template from the project collection.| -|![Step 3](media/procguid_3.png "ProcGuid_3")|[Upload a process template](../../boards/work-items/guidance/manage-process-templates.md). After you have customized your template, upload it to the project collection where you will create the project.

      Ideally, you should use a project collection that is not used by other projects. By working in a test-bed project collection, you avoid introducing a change that might collide with existing team processes that are still under development. Also, you will want the project collection to support the same resources that you want to access, such as a project portal and a reporting site.

      Make sure that the name of your process template is unique. If you downloaded a process template from a project collection, made a change, and are now uploading the template, you must change its name or delete the existing process template from the project collection.

      The upload process performs a verification check to make sure that the XML is valid. If you receive any errors when you try to upload the process template, the changes that you made will have caused the error. Review your changes, and correct any XML syntax errors that you find.| +|![Step 2](media/procguid_2.png "ProcGuid_2")|**Modify or add files**. You customize a process template by modifying, deleting, or adding files that are defined for a process template. You customize a plug-in or definition file by modifying its XML content. Each plug-in file and type definition file must conform to its XML schema definition.

      The first time that you customize a process template, make a small change. If you make many changes without a good understanding of how the changes might affect your template, you risk encountering multiple mistakes difficult to debug.

      Make sure that the name of your process template is unique. If you download a process template, make changes, and upload it, you must change its name or it over-writes the existing process template from the project collection.| +|![Step 3](media/procguid_3.png "ProcGuid_3")|[Upload a process template](../../boards/work-items/guidance/manage-process-templates.md). After you customize your template, upload it to the project collection where you create the project.

      Ideally, you should use a project collection that isn't used by other projects. By working in a test-bed project collection, you avoid introducing a change that might collide with existing team processes that are still under development. Also, the project collection should support the same resources that you want to access, such as a project portal and a reporting site.

      Make sure that the name of your process template is unique. If you downloaded a process template from a project collection, made a change, and are now uploading the template, you must change its name or delete the existing process template from the project collection.

      The upload process performs a verification check to make sure that the XML is valid. If you receive any errors when you try to upload the process template, the changes that you made caused the error. Review your changes, and correct any XML syntax errors that you find.| |![Step 4](media/procguid_4.png "ProcGuid_4")|[Create a project](../../organizations/projects/create-project.md). To test new process templates, you must create a project. If any errors occur, view the log for project creation. It contains a list of the tasks that it tried to run and shows which tasks failed. You can map failed tasks back to the XML to determine the cause of the errors.

      You can clean up unnecessary projects by using the [TFSDeleteProject command-line tool](../../organizations/projects/delete-project.md).| -|![Step 5](media/procguid_6.png "ProcGuid_6")|**Verify changes to process templates**. Before you put your process template in production mode and use it as the basis for several projects, you should verify that it is well-defined. You perform this task by systematically verifying that each object and artifact works as expected. | - - - -## Related articles +|![Step 5](media/procguid_6.png "ProcGuid_6")|**Verify changes to process templates**. Before you put your process template in production mode and use it as the basis for several projects, you should verify that it's well-defined. You perform this task by systematically verifying that each object and artifact works as expected. | -- [Process templates overview](index.md) -- [Process template and plug-in files](/previous-versions/azure/devops/reference/process-templates/overview-process-template-files) -- [Configure features after an upgrade](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) -- [Process template plug-ins: Index to XML elements](/previous-versions/azure/devops/reference/process-templates/process-template-plug-ins-xml-elements-index) -- [XML element reference](../xml/xml-element-reference.md) - ### Tools that support customizing a process template You can customize a process template using one of the following tools: @@ -166,3 +152,14 @@ You can customize a process template using one of the following tools: Based on the version of Visual Studio you have installed, get the Process Editor Tool from one of the following extensions. [!INCLUDE [temp](../../includes/process-editor-tool.md)] + + + +## Related articles + +- [Learn about process templates](index.md) +- [Explore process template and plug-in files](/previous-versions/azure/devops/reference/process-templates/overview-process-template-files) +- [Configure features after upgrading](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) +- [Review process template plug-ins and XML elements](/previous-versions/azure/devops/reference/process-templates/process-template-plug-ins-xml-elements-index) +- [Reference XML elements](../xml/xml-element-reference.md) + diff --git a/docs/reference/process-templates/toc.yml b/docs/reference/process-templates/toc.yml index c7867098828..5989e1efbc5 100644 --- a/docs/reference/process-templates/toc.yml +++ b/docs/reference/process-templates/toc.yml @@ -37,24 +37,24 @@ - name: XML element reference items: - name: XML element index - href: /previous-versions/azure/devops/reference/process-templates/process-template-plug-ins-xml-elements-index + href: /previous-versions/azure/devops/reference/process-templates/process-template-plug-ins-xml-elements-index - name: Process template files - href: /previous-versions/azure/devops/reference/process-templates/overview-process-template-files + href: /previous-versions/azure/devops/reference/process-templates/overview-process-template-files - name: Define root tasks href: /previous-versions/azure/devops/reference/process-templates/define-root-tasks-process-template-plug-in - name: Process template XML elements - href: /previous-versions/azure/devops/reference/process-templates/process-template-xml-elements-reference + href: /previous-versions/azure/devops/reference/process-templates/process-template-xml-elements-reference - name: Define tasks and task group dependencies - href: /previous-versions/azure/devops/reference/process-templates/define-dependencies-plug-ins-groups-tasks + href: /previous-versions/azure/devops/reference/process-templates/define-dependencies-plug-ins-groups-tasks - name: Define tasks to process - href: /previous-versions/azure/devops/reference/process-templates/define-tasks-to-process-a-plug-in + href: /previous-versions/azure/devops/reference/process-templates/define-tasks-to-process-a-plug-in - name: Define the Classification plug-in - href: /previous-versions/azure/devops/reference/process-templates/define-classification-plug-in + href: /previous-versions/azure/devops/reference/process-templates/define-classification-plug-in - name: Define the Portal plug-in - href: /previous-versions/azure/devops/reference/process-templates/define-project-portal-plug-in + href: /previous-versions/azure/devops/reference/process-templates/define-project-portal-plug-in - name: Define the Reporting plug-in - href: /previous-versions/azure/devops/reference/process-templates/add-reports-to-the-process-template + href: /previous-versions/azure/devops/reference/process-templates/add-reports-to-the-process-template - name: Configure initial groups, teams, members, & permissions - href: /previous-versions/azure/devops/reference/process-templates/configure-initial-groups-teams-members-permissions + href: /previous-versions/azure/devops/reference/process-templates/configure-initial-groups-teams-members-permissions - name: Define the Groups and Permissions plug-in - href: /previous-versions/azure/devops/reference/process-templates/define-groups-teams-permissions-plug-in \ No newline at end of file + href: /previous-versions/azure/devops/reference/process-templates/define-groups-teams-permissions-plug-in diff --git a/docs/reference/quick-reference-index-boards-settings.md b/docs/reference/quick-reference-index-boards-settings.md index 73ea6a16a33..1b1b4683aeb 100644 --- a/docs/reference/quick-reference-index-boards-settings.md +++ b/docs/reference/quick-reference-index-boards-settings.md @@ -17,11 +17,11 @@ ms.date: 01/17/2023 Use this index to quickly access concepts and tasks related to configuring and customizing Azure Boards. If you're new to the Azure Boards, see [What is Azure Boards?](../boards/get-started/what-is-azure-boards.md). - + ## Get started -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" You can start using Azure Boards without configuring or customizing anything. However, as your organization grows, you'll find it beneficial to add teams, define area paths and iteration paths. If you use GitHub for your source code repository, you may want to connect Azure Boards to GitHub. If you are tasked with administrating a project for several teams, we recommend you review the following articles. @@ -34,18 +34,7 @@ You can start using Azure Boards without configuring or customizing anything. Ho - [Set process permissions](../organizations/security/set-permissions-access-work-tracking.md#process-permissions) ::: moniker-end -::: moniker range="< azure-devops-2019" - -You can start using Azure Boards without configuring or customizing anything. However, as your organization grows, you'll find it beneficial to add teams, define area paths and iteration paths. If you are tasked with administrating a project for several teams, we recommend you review the following articles. - - -- [Customize work tracking overview](customize-work.md) -- [Add a team](../organizations/settings/add-teams.md) -- [Define Area Paths](../organizations/settings/set-area-paths.md?toc=/azure/devops/reference/toc.json&bc=/azure/devops/reference/breadcrumb/toc.json) -- [Define Iteration Paths](../organizations/settings/set-iteration-paths-sprints.md?toc=/azure/devops/reference/toc.json&bc=/azure/devops/reference/breadcrumb/toc.json) -- [Configure and customize Azure Boards](../boards/configure-customize.md?toc=/azure/devops/reference/toc.json&bc=/azure/devops/reference/breadcrumb/toc.json) -- [Set process permissions](../organizations/security/set-permissions-access-work-tracking.md#process-permissions) -::: moniker-end + ## Configure team tools @@ -58,12 +47,11 @@ Each team administrator can configure the following elements for their team, bac - [Define Area Paths for a team](../organizations/settings/set-area-paths.md) - [Define Iteration Paths for a team](../organizations/settings/set-iteration-paths-sprints.md) - [Define work item templates](../boards/backlogs/work-item-template.md) - - [Backlogs](../organizations/settings/select-backlog-navigation-levels.md) - - [Working days](../organizations/settings/set-working-days.md) + - [Backlogs](../organizations/settings/select-backlog-navigation-levels.md) - [Working with bugs](../organizations/settings/show-bugs-on-backlog.md) :::column-end::: :::column span="1"::: - **Kanban boards** + **Boards** - [Columns](../boards/boards/add-columns.md) - [WIP limits](../boards/boards/wip-limits.md) - [Definition of Done](../boards/boards/add-columns.md#definition-of-done) @@ -79,27 +67,19 @@ Each team administrator can configure the following elements for their team, bac You customize your work tracking experience to support your business and reporting needs. The most common customizations include adding a custom field, modifying a work item form, or adding a custom work item type. Process customization tasks must be performed by an administrator who has the necessary organization-level permissions, as they affect all users and teams within a project. - ::: moniker range="azure-devops" You customize Azure Boards work tracking using the Inheritance process model which uses a WYSIWYG user interface to customize work tracking objects and tools. For select organizations who migrated to Azure DevOps Services using the data migration tool for Azure DevOps, the Hosted XML process model is used. This model relies on modifying and importing process templates to customize work tracking objects and tools. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!IMPORTANT] - > When you upgrade Team Foundation Server from an earlier version to the current version, the type assignment for the **Description** (System.Description) field is automatically converted from `PlainText` to `HTML`. With the `changefield` command, you can restore the content of this field to display plain text. - - - **Friendly name** that displays in the work item query. This name may differ from that displayed on the work item form. - - **Reporting attributes** which includes the name of the field as it appears in a report, the reference report name, and the reporting type. - - **Synchronization** with Active Directory - you can enable/disable synchronization of person name fields. -- `deletefield`: Deletes the specified field. -- `indexfield`: Turns indexing on or off for the specified field. When you enable indexing for a field, you may increase the performance of finding work items whose queries specify that field. If you add a custom field that you use in many of your work item queries, you may want to enable indexing for that field. -- `listfields`: Lists the attributes for all fields or a specified field. - -::: moniker-end - [!INCLUDE [temp](../../includes/witadmin-run-tool.md)] @@ -59,11 +43,10 @@ For an overview of the fields defined within a default process template, see [Wo [!INCLUDE [temp](../../includes/process-editor.md)] - ## Prerequisites -- To list fields, you must have your **View project-level information** permission for the project in the collection set to **Allow**. -- To delete or rename fields or change an attribute of a field, you must be a member of the **Team Foundation Administrators** security group or the **Project Collection Administrators** security group. +- To list fields, have your **View project-level information** permission for the project in the collection set to **Allow**. +- To delete or rename fields or change an attribute of a field, be a member of the **Team Foundation Administrators** security group or the **Project Collection Administrators** security group. For more information, see [Change project collection-level permissions](../../organizations/security/change-organization-collection-level-permissions.md). @@ -72,8 +55,7 @@ For more information, see [Change project collection-level permissions](../../or ## Syntax - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ``` witadmin changefield /collection:CollectionURL /n:RefName [/name:NewName] [/syncnamechanges:true | false] [/reportingname:ReportingName] [/reportingrefname:ReportingRefName] [/reportingtype:Type] [/reportingformula:Formula] [/type:PlainText | HTML] [/noprompt] @@ -85,19 +67,6 @@ witadmin listfields /collection:CollectionURL /n:RefName [/unused] ::: moniker-end -::: moniker range="< azure-devops-2019" - -``` -witadmin changefield /collection:CollectionURL /n:RefName [/name:NewName] [/syncnamechanges:true | false] [/reportingname:ReportingName] [/reportingrefname:ReportingRefName] [/reportingtype:Type] [/reportingformula:Formula] [/type:PlainText | HTML] [/noprompt] - -witadmin deletefield /collection:CollectionURL /n:RefName [/noprompt] - -witadmin indexfield /collection:CollectionURL /n:Name /index:on|off - -witadmin listfields /collection:CollectionURL /n:RefName [/unused] -``` - -::: moniker-end ### Parameters @@ -117,16 +86,6 @@ witadmin listfields /collection:CollectionURL /n:RefName [/unused] |`/noprompt`|Disables prompt for confirmation.| |`/?` or `help`|Displays help about the command in the Command Prompt window.| - - -::: moniker range="< azure-devops-2019" -### Indexed fields - -A query index is created based on those fields that have indexing enabled. This index improves the response time when running queries that include indexed fields. - -By default, the following fields are indexed: Assigned To, Created Date, Changed By, State, Reason, Area ID, Iteration ID, and Work Item Type. If there are other fields that your team frequently uses in their queries, you can add them to the query index. - -::: moniker-end ### Synchronizing person names with Active Directory @@ -377,18 +336,6 @@ witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCol Enter **y** at the confirmation prompt to complete this step. - -::: moniker range="< azure-devops-2019" - -## Q & A - -### Q: What customizations can I make and still use the Configure Features Wizard to update my project after an upgrade? - -**A:** You can add custom fields, customize a pick list, and add rules to a field. The [Configure Features Wizard](/previous-versions/azure/devops/reference/upgrade/configure-features-after-upgrade) will update your projects and you'll get access to the latest features. - -Changing field attributes is not recommended. To learn about which customizations you can safely make and which you should avoid, see [On-premises XML process model, Maintenance and upgrade implications](../on-premises-xml-process-model.md#before-you-customize). - -::: moniker-end ## Related articles diff --git a/docs/reference/witadmin/toc.yml b/docs/reference/witadmin/toc.yml index be4c3fbc9cf..335ba7ff7af 100644 --- a/docs/reference/witadmin/toc.yml +++ b/docs/reference/witadmin/toc.yml @@ -13,7 +13,7 @@ - name: Archived articles items: - name: Import & export categories - href: /previous-versions/azure/devops/reference/witadmin/witadmin-import-export-categories + href: /previous-versions/azure/devops/reference/witadmin/witadmin-import-export-categories displayname: exportcategories, importcategories - name: Manage link types href: /previous-versions/azure/devops/reference/witadmin/manage-link-types @@ -32,4 +32,4 @@ displayname: destroywi - name: Customize & manage the test experience href: /previous-versions/azure/devops/reference/witadmin/tcm-customize-manage-test-experience - displayname: tcm fieldmapping, map test fields \ No newline at end of file + displayname: tcm fieldmapping, map test fields diff --git a/docs/reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md b/docs/reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md index 3701bf82b97..531587d72be 100644 --- a/docs/reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md +++ b/docs/reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md @@ -9,11 +9,9 @@ ms.topic: reference ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 01/13/2023 +ms.date: 11/13/2023 --- - - # witAdmin: Customize and manage objects for tracking work [!INCLUDE [version-lt-eq-azure-devops-plus-witadmin](../../includes/version-lt-eq-azure-devops-plus-witadmin.md)] @@ -26,11 +24,9 @@ In addition, for on-premises Azure DevOps Servers, you can manage the resolution As the following illustration shows, you manage categories and types of and work items for each project. You manage global lists, types of links, and fields in work item for each project collection. You can customize global workflow for a project or a collection. -![Conceptual image of Work Item Tracking Objects.](media/pnt_wit_objects.png) - -[!INCLUDE [temp](../../includes/process-editor.md)] +![Conceptual image of Work Item Tracking Objects.](media/pnt_wit_objects.png) -For most commands, you must be a member of the Project Administrators or Project Collection Administrators groups. For more information, see [Change project collection-level permissions](../../organizations/security/change-organization-collection-level-permissions.md). +For most commands, be a member of the Project Administrators or Project Collection Administrators groups. For more information, see [Change project collection-level permissions](../../organizations/security/change-organization-collection-level-permissions.md). [!INCLUDE [temp](../../includes/witadmin-run-tool.md)] @@ -51,13 +47,13 @@ For most commands, you must be a member of the Project Administrators or Project You customize all work tracking objects—such as, work item types, process configuration, global lists—by updating their XML definitions. If you're new to work tracking customization, see [Customize your work tracking experience](../customize-work.md). -You run **witadmin** commands against Azure DevOps Services or an on-premises Azure DevOps Server. As shown in the command lists below, only **witadmin** commands that list or export files are supported for the Azure DevOps Services. +You run **witadmin** commands against Azure DevOps Services or an on-premises Azure DevOps Server. As shown in the following command lists, only **witadmin** commands that list or export files are supported for the Azure DevOps Services. ## [Work item types](witadmin-import-export-manage-wits.md) -Work items are used to track anything you need to track. Each work item is based on a work item type. Each work item types defines the fields available in which to store information. The available work item types depend on the process you used when your project was created (Agile, Scrum, Basic, or CMMI). To learn more, see [Track your work items in Azure Boards user stories, issues, bugs, features, and epics](../../boards/work-items/about-work-items.md). +Work items are used to track anything you need to track. Each work item is based on a work item type. Each work item type defines the fields available in which to store information. The available work item types depend on the process you used when your project was created (Agile, Scrum, Basic, or CMMI). For more information, see [Track your work items in Azure Boards user stories, issues, bugs, features, and epics](../../boards/work-items/about-work-items.md). -For the Inherited process model, you can add and delete work item types from the web portal. To learn how, see [Add and manage work item types(Inheritance process)](../../organizations/settings/work/customize-process-work-item-type.md). +For the Inherited process model, you can add and delete work item types from the web portal. For more information, see [Add and manage work item types (Inheritance process)](../../organizations/settings/work/customize-process-work-item-type.md). --- :::row::: @@ -133,9 +129,9 @@ For the Inherited process model, you can add and delete work item types from the ## [Fields](manage-work-item-fields.md) Fields are used to track the status and information associated with work items. Fields are defined for an organization or collection. -To learn more about fields, see [Work item fields and attributes](../../boards/work-items/work-item-fields.md). To look up the description of a specific field, see [Field descriptions for default and work item fields used in process templates](../../boards/work-items/guidance/work-item-field.md). +For more information, see [Work item fields and attributes](../../boards/work-items/work-item-fields.md). To look up the description of a specific field, see [Field descriptions for default and work item fields used in process templates](../../boards/work-items/guidance/work-item-field.md). -For the Inherited process model, you can view and delete fields from the web portal. To learn how, see [Add and manage fields (Inheritance process)](../../organizations/settings/work/customize-process-field.md). +For the Inherited process model, you can view and delete fields from the web portal. For more information, see [Add and manage fields (Inheritance process)](../../organizations/settings/work/customize-process-field.md). --- :::row::: @@ -172,19 +168,7 @@ For the Inherited process model, you can view and delete fields from the web por ✔️ :::column-end::: :::row-end::: -::: moniker range="< azure-devops-2019" -:::row::: - :::column span="2"::: - `indexfield`: Turn field indexing on/off - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: -::: moniker-end + :::row::: :::column span="2"::: `changefield`: Change a field attribute @@ -210,10 +194,9 @@ For the Inherited process model, you can view and delete fields from the web por --- - ## [Categories](/previous-versions/azure/devops/reference/witadmin/witadmin-import-export-categories) -Categories associate one or more work item types as belonging to the same category. Azure Boards relies on default category definitions, many of which specify a single work item type per category. To learn about categories and how they're used, see [Use categories to group work item types](../xml/use-categories-to-group-work-item-types.md). +Categories associate one or more work item types as belonging to the same category. Azure Boards relies on default category definitions, many of which specify a single work item type per category. For more information, see [Use categories to group work item types](../xml/use-categories-to-group-work-item-types.md). --- @@ -253,10 +236,9 @@ Categories associate one or more work item types as belonging to the same catego :::row-end::: --- - ## [Link types](/previous-versions/azure/devops/reference/witadmin/manage-link-types) -You use different link types to manage the various relationships between work items. For On-premises XML and Hosted XML process models, you can define custom link types. To learn more about default link types, see [Manage dependencies, link work items](../../boards/queries/link-work-items-support-traceability.md) and [Reference guide for link types](../../boards/queries/link-type-reference.md). +Use different link types to manage the various relationships between work items. For On-premises XML and Hosted XML process models, you can define custom link types. For more information, see [Link work items to other objects](../../boards/backlogs/add-link.md) and [Reference guide for link types](../../boards/queries/link-type-reference.md). --- :::row::: @@ -293,19 +275,7 @@ You use different link types to manage the various relationships between work it ✔️ :::column-end::: :::row-end::: -::: moniker range="< azure-devops-2019" -:::row::: - :::column span="2"::: - `importlinktype`: Import a link type file - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - ✔️ - :::column-end::: -:::row-end::: -::: moniker-end + :::row::: :::column span="2"::: `listlinktypes`: List the defined link types @@ -333,7 +303,7 @@ You use different link types to manage the various relationships between work it ## [Global lists](/previous-versions/azure/devops/reference/witadmin/manage-global-lists-for-work-item-types) -Global lists are pick lists that you can include within one or more fields and work item type definitions. You can share list items among several work item types for a collection of projects by including the list items in one or more **GLOBALLIST** elements. To learn more, see [GLOBALLIST XML element reference](../xml/define-global-lists.md). +Global lists are pick lists that you can include within one or more fields and work item type definitions. You can share list items among several work item types for a collection of projects by including the list items in one or more **GLOBALLIST** elements. For more information, see [GLOBALLIST XML element reference](../xml/define-global-lists.md). --- :::row::: @@ -350,7 +320,7 @@ Global lists are pick lists that you can include within one or more fields and w --- :::row::: :::column span="2"::: - `destroygloballist`*: Delete a global list + `destroygloballist`: Delete a global list :::column-end::: :::column span="1"::: @@ -399,7 +369,7 @@ Global lists are pick lists that you can include within one or more fields and w ## [Global workflow](/previous-versions/azure/devops/reference/witadmin/witadmin-import-export-global-workflow) -With global workflow, you can define and update fields and global lists that apply to all work item types in a project or collection. To learn more, see [Global workflow XML element reference](../xml/global-workflow-xml-element-reference.md). +With global workflow, you can define and update fields and global lists that apply to all work item types in a project or collection. For more information, see [Global workflow XML element reference](../xml/global-workflow-xml-element-reference.md). --- :::row::: @@ -441,10 +411,10 @@ With global workflow, you can define and update fields and global lists that app ## [Process configuration](witadmin-import-export-process-configuration.md) -Process configuration defines the default configuration and functional capabilities that your teams can access using Azure Boards. The configuration determines the work item types that appear on the product backlog, sprint backlogs, Kanban board, and task board. To learn about process configuration and what you can customize, see [ProcessConfiguration](../xml/process-configuration-xml-element.md). +Process configuration defines the default configuration and functional capabilities that your teams can access using Azure Boards. The configuration determines the work item types that appear on the product backlog, sprint backlogs, boards, and Taskboards. For more information about process configuration and what you can customize, see [Process Configuration](../xml/process-configuration-xml-element.md). -For the Inherited process model, you can customize backlogs from the web portal. To learn how, see [Customize your backlogs or boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md). +For the Inherited process model, you can customize backlogs from the web portal. For more information, see [Customize your backlogs or boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md). --- :::row::: @@ -483,15 +453,6 @@ For the Inherited process model, you can customize backlogs from the web portal. :::row-end::: --- -::: moniker range="< azure-devops-2019" - -## [Work items](/previous-versions/azure/devops/reference/witadmin/remove-work-items-permanently) - -The following **witadmin** command is only available for TFS 2018.1 and earlier versions. It has been deprecated for TFS 2018.2 and later versions. To learn more about how to permanently delete work items for later versions, see [Remove, delete, or restore work items](../../boards/backlogs/remove-delete-work-items.md). - -- `destroywi`: Permanently delete work items -::: moniker-end - ::: moniker range="< azure-devops" ## [Client cache](/previous-versions/azure/devops/reference/witadmin/rebuild-client-cache) @@ -503,7 +464,7 @@ The following `witadmin` command is only available for Azure DevOps Server on-pr - `rebuildcache`: Rebuild the client cache ::: moniker-end - + ::: moniker range="< azure-devops" @@ -515,31 +476,20 @@ To customize the resolution types, bug work item type, and failure types used wh ::: moniker-end - ## Related articles ::: moniker range="azure-devops" - [Customize your work tracking experience](../customize-work.md) -- [**az boards** command-line tools](../../cli/quick-reference.md#azure-boards) - [On-premises XML process model](../on-premises-xml-process-model.md) -- [Inheritance process model](../../organizations/settings/work/inheritance-process-model.md) - [Hosted XML process model](../../organizations/settings/work/hosted-xml-process-model.md) -- [What is Azure Test Plans?](../../test/overview.md) ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="
      To contain an entry to define the color codes associated with the WIT. For example: @@ -386,7 +380,7 @@ Other changes might require you to perform some manual operations when updating You can have only one State mapped to `type="Complete"` - To learn more, see [Support bug update status using My Work](../xml/support-bug-update-status-using-my-work.md). + For more information, see [Support bug update status using My Work](../xml/support-bug-update-status-using-my-work.md). :::column-end::: :::row-end::: :::row::: diff --git a/docs/reference/xml/change-workflow-wit.md b/docs/reference/xml/change-workflow-wit.md index b16af39b1e9..3d19c25fef2 100644 --- a/docs/reference/xml/change-workflow-wit.md +++ b/docs/reference/xml/change-workflow-wit.md @@ -26,7 +26,7 @@ The workflow determines the logical progression and regression of work that team > [!NOTE] -> This article describes how to customize a workflow state. If instead, you want to change the *State* assigned to a specific work item, see one of the following topics: [Add work items, Update work status](../../boards/work-items/work-item-form-controls.md#update-work-status), [Kanban board, Track work in progress](../../boards/boards/kanban-quickstart.md#track-work-in-progress), or [Task board, Update task status](../../boards/sprints//task-board.md#update-task-status). You can also perform a [bulk update of the *State* for many work items](../../boards/backlogs/bulk-modify-work-items.md). +> This article describes how to customize a workflow state. If instead, you want to change the *State* assigned to a specific work item, see one of the following articles: [Board, Track work in progress](../../boards/boards/kanban-quickstart.md#track-work-in-progress), or [Task board, Update task status](../../boards/sprints//task-board.md#update-task-status). You can also perform a [bulk update of the *State* for many work items](../../boards/backlogs/bulk-modify-work-items.md). > > For information about build pipeline workflows, see [Get started with CI/CD](../../pipelines/create-first-pipeline.md). @@ -49,7 +49,7 @@ To customize the workflow, follow these two steps: 2. [Modify the process configuration to map new workflow states to metastates](process-configuration-xml-element.md). - This second step is required when you change the workflow for a WIT that appears on an Agile tool page. These WITs belong to either the Requirement or Task categories. To learn more about state categories, see [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md). + This second step is required when you change the workflow for a WIT that appears on an Agile tool page. These WITs belong to either the Requirement or Task categories. For more information about state categories, see [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md). @@ -66,7 +66,7 @@ As you design or modify a workflow, consider the following guidelines: - Use the `STATE` element to define a unique state for each team member role that will take a specific action on a work item. The more states you define, the more transitions you must define. Regardless of the sequence in which you define the states, they are listed in alphanumeric order in the drop-down menu for the **State** field. - If you add a state to a work item type that appears on the backlog or board pages in the web portal, you must also map the state to a state category. To learn more, review [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md). + If you add a state to a work item type that appears on the backlog or board pages in the web portal, you must also map the state to a state category. For more information, review [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md). - Use the `TRANSITION` element to define a transition for each valid progression and regression from one state to another. @@ -249,7 +249,7 @@ You can define rules that update fields whenever the following events occur: - Assign a field rule under `DEFAULTREASON` or `REASON` when you want the rules to apply only for that specific reason. - If a field should always contain the same value, you define the rule under the `FIELD` element that defines that field. To learn more about rule usage, see [Rules and rule evaluation](../../organizations/settings/work/rule-reference.md). + If a field should always contain the same value, you define the rule under the `FIELD` element that defines that field. For more information about rule usage, see [Rules and rule evaluation](../../organizations/settings/work/rule-reference.md). You should try to minimize the number of conditions that you define for any one type of work item. With each conditional rule that you add, you increase the complexity of the validation process that occurs every time that a team member saves a work item. Complex rule sets might increase the time that is required to save the work item. @@ -316,7 +316,7 @@ When the value of the **State** field for a work item is set to Active and the w - [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md) - [Customize your work tracking experience](../customize-work.md) -- [Query by assignment, workflow or Kanban board changes](../../boards/queries/query-by-workflow-changes.md) +- [Query by assignment, workflow or board changes](../../boards/queries/query-by-workflow-changes.md) - [Design the work item form](/previous-versions/azure/devops/reference/xml/design-work-item-form?view=tfs-2017&preserve-view=true) - [Import, export, and manage work item types](../witadmin/witadmin-import-export-manage-wits.md) diff --git a/docs/reference/xml/process-configuration-xml-element.md b/docs/reference/xml/process-configuration-xml-element.md index 8e02b956fd2..43e7bd57a41 100644 --- a/docs/reference/xml/process-configuration-xml-element.md +++ b/docs/reference/xml/process-configuration-xml-element.md @@ -16,7 +16,7 @@ ms.date: 12/15/2017 [!INCLUDE [version-lt-azure-devops](../../includes/version-lt-azure-devops.md)] -Process configuration defines the default configuration and functional capabilities that your teams can access using the web portal Agile tools. These tools, include the product backlog, sprint backlogs, Kanban board, and task board and are customizable for each team you add to project. +Process configuration defines the default configuration and functional capabilities that your teams can access using the web portal Agile tools. These tools, include the product backlog, sprint backlogs, board, and task board and are customizable for each team you add to project. Configuration elements specify the work item types (WITs), default columns, fields used by the tools, and other elements. The main configurations made determine which items will display for the portfolio, product, and sprint backlogs by defining the **PortfolioBacklog**, **RequirementBacklog**, and **TaskBacklog** sections of the process configuration XML definition file. In addition, process configuration defines the workflow mapping of state-to-state category for all WITs that require mapping. @@ -59,7 +59,7 @@ To update the process configuration for a project, you export the XML definition You can customize the following elements for the product backlog, sprint backlogs, and portfolio backlogs: -- **State category mappings**:  Map workflow states to state categories (previously referred to as a metastate). These mappings support the display of all Agile planning tools, including the Kanban and task boards. +- **State category mappings**:  Map workflow states to state categories (previously referred to as a metastate). These mappings support the display of all Agile planning tools, including the board and Taskboards. - **Quick add panel**:  Specify the WITs and work item fields that appear for quickly adding items to the backlog. @@ -201,7 +201,7 @@ You configure backlogs within the XML sections that appear in the following samp Several WITs require their workflow states to be mapped to a state category. Workflow states define how a work item progresses from first activation or creation to closed or complete. For example, the states defined for the Scrum product backlog item define a progression of four states, from **New**, **Approved**, **Committed**, to **Done**, and also includes a fifth state, **Removed**, to account for a state removed from the backlog without being implemented. Workflow states are associated with the `value` attribute. -State categories, on the other hand, determine how the Agile planning tools treat each workflow state. The primary state categories used by the backlog and task board are **Proposed**, **InProgress**, and **Complete**. State categories are associated with the `type` attribute. To learn more, see [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md). +State categories, on the other hand, determine how the Agile planning tools treat each workflow state. The primary state categories used by the backlog and task board are **Proposed**, **InProgress**, and **Complete**. State categories are associated with the `type` attribute. For more information, see [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md). By associating each workflow state to a state category, the background operations performed to display the backlog and task boards know how to correctly interpret the status of each work item. For example, the following mappings are defined for the Scrum product backlog. @@ -249,8 +249,8 @@ There are three groups of state categories: Agile, Bug, and Feedback. The follow - Agile: Use for all work item types. - **Proposed**: Indicates work items that are new, not yet committed, or not yet being worked on. - **InProgress**: Indicates work items that have been committed or are actively being worked on. - - **Complete**: Indicates work items that have been implemented. For the [Kanban board](../../boards/boards/kanban-overview.md) to be valid, exactly one workflow state must be mapped to the **Complete** state category. If additional workflow states need to be represented, they can be mapped to the **Resolved** state category. - Once a workflow state transitions to a state that is associated with the **Complete** metastate, the associated work item will fall off the product backlog. However, it will continue to be listed in the last column on the Kanban board.

      + - **Complete**: Indicates work items that have been implemented. For the [board](../../boards/boards/kanban-overview.md) to be valid, exactly one workflow state must be mapped to the **Complete** state category. If additional workflow states need to be represented, they can be mapped to the **Resolved** state category. + Once a workflow state transitions to a state that is associated with the **Complete** metastate, the associated work item will fall off the product backlog. However, it will continue to be listed in the last column on the board.

      Work items in a workflow state that aren't mapped to one of the state categories don't appear on the backlog or board. - Bug: Use only for work item types grouped within the Bug Category. In addition to the Agile state categories, includes the **Resolved** state category which indicates bugs that have been resolved.

      > [!NOTE] @@ -463,7 +463,7 @@ The following table describes the additional elements used to define the state c :::column-end::: :::column span="2"::: - Optional. Container element that defines the state category mappings for work item types assigned to the Bug Category. In addition to how these mappings are used in the display of Agile tools, they also control how the **My Work** feature in Team Explorer updates the bug state as developers move bugs using **My Work**. To learn more, see [Get your code reviewed (TFVC)](../../repos/tfvc/get-code-reviewed-vs.md). + Optional. Container element that defines the state category mappings for work item types assigned to the Bug Category. In addition to how these mappings are used in the display of Agile tools, they also control how the **My Work** feature in Team Explorer updates the bug state as developers move bugs using **My Work**. For more information, see [Get your code reviewed (TFVC)](../../repos/tfvc/get-code-reviewed-vs.md). ``` [!NOTE] ->Feature availability: To map state categories for `TestPlanWorkItems` or `TestSuiteWorkItems`, you must upgrade your application-tier server to TFS 2013.3 or later version. Afterwards, you can customize the workflow state of test plans and test suites. To learn more, see [Test Plan and Test Suite features](/previous-versions/azure/devops/reference/upgrade/new-features-added#test-management). +>Feature availability: To map state categories for `TestPlanWorkItems` or `TestSuiteWorkItems`, you must upgrade your application-tier server to TFS 2013.3 or later version. Afterwards, you can customize the workflow state of test plans and test suites. For more information, see [Test Plan and Test Suite features](/previous-versions/azure/devops/reference/upgrade/new-features-added#test-management). @@ -700,7 +700,7 @@ For example, if you change the `refname` assigned to `type="Activity"` then you ## Set non-working days -Non-working days are removed from calculations made by the [capacity planning tool](../../boards/sprints//set-capacity.md) and [burndown charts](../../report/dashboards/configure-sprint-burndown.md). Default processes—[Agile](../../boards/work-items/guidance/agile-process.md), [Scrum](../../boards/work-items/guidance/scrum-process.md), or [CMMI](../../boards/work-items/guidance/cmmi-process.md)—specify Saturday and Sunday as non-working days. After you create a project, [each team can set their specific non-working days](../../organizations/settings/set-working-days.md). +Non-working days get removed from calculations made by the [capacity planning tool](../../boards/sprints/set-capacity.md) and [burndown charts](../../report/dashboards/configure-sprint-burndown.md). Default processes—[Agile](../../boards/work-items/guidance/agile-process.md), [Scrum](../../boards/work-items/guidance/scrum-process.md), or [CMMI](../../boards/work-items/guidance/cmmi-process.md)—specify Saturday and Sunday as non-working days. > [!div class="tabbedCodeSnippets"] > ```XML @@ -877,9 +877,9 @@ The `HiddenBacklogs` property determines which backlogs/portfolio backlogs appea - **Off** — Bugs don't appear on backlogs or boards
      - **HiddenBacklogs** specifies the [backlog that's inactive by default](../../organizations/settings/select-backlog-navigation-levels.md). - **StateColors** sets the color values for workflow states. (Requires TFS 2017 or later version) - The value for the property is a comma-separated list of state names and hex colors. Prefix the six-digit Hex color code with FF which denotes that the color should be fully visible. - ``

      + The value for the property is a comma-separated list of state names and hex colors. Prefix the six-digit Hex color code (include the #) with FF which denotes that the color should be fully visible. + ``

      > [!NOTE] > **Feature availability:** You can specify workflow state colors if you use Hosted XML or, for On-premises XML, you have upgraded to TFS 2015.2 or later version. For additional details, see the next section, [Specify workflow state colors](#workflow-colors). @@ -908,7 +908,7 @@ The color you associate with your work item states will appear across the produc - Work item form (web portal, see [New work item experience](../process/new-work-item-experience.md)) - Work item form links control (web portal, see [LinksControlOptions XML elements reference](linkscontroloptions-xml-elements.md)) -- Cards displayed on the [Kanban board](../../boards/boards/kanban-overview.md) and [task boards](../../boards/sprints//task-board.md) (For settings, see [Customize cards](../../boards/boards/customize-cards.md)) +- Cards displayed on the [board](../../boards/boards/kanban-overview.md) and [task boards](../../boards/sprints//task-board.md) (For settings, see [Customize cards](../../boards/boards/customize-cards.md)) - All backlogs (add State via column options) - Query results (add State via column options) diff --git a/docs/reference/xml/support-rollup-of-work-and-other-fields.md b/docs/reference/xml/support-rollup-of-work-and-other-fields.md index c04865aa4ee..31fdf52351d 100644 --- a/docs/reference/xml/support-rollup-of-work-and-other-fields.md +++ b/docs/reference/xml/support-rollup-of-work-and-other-fields.md @@ -1,6 +1,6 @@ --- title: Support rollup of work and other fields -titleSuffix: Azure DevOps & TFS +titleSuffix: Azure DevOps description: Provides summed values of select fields for all child work items of a parent. ms.service: azure-devops-boards ms.custom: process, archive-candidate @@ -9,15 +9,14 @@ ms.author: chcomley author: chcomley ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 09/16/2024 --- - # Rollup of work and other fields [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Rollup provides summed values of select fields for all child work items of a parent. Because Azure DevOps Services and Team Foundation Server (TFS) support multiple levels of nesting, when you perform rollup, you want to make sure you don't double-count values. Most project managers are interested in getting rollup of estimated or completed work, effort, size, or story points. +Rollup provides summed values of selected fields for all child work items of a parent. Since Azure DevOps supports multiple levels of nesting, ensure you don't double-count values during rollup. Project managers typically seek rollup for estimated or completed work, effort, size, or story points. > [!NOTE] > The system doesn't support rollup of the Effort, Story Points, or Size fields across product backlogs and portfolio backlogs. @@ -34,7 +33,7 @@ From any product or portfolio backlog, you can add rollup progress bars, counts [!INCLUDE [temp](../../boards/includes/display-progress-bars.md)] -To learn more, see [Display rollup progress or totals](../../boards/backlogs/display-rollup.md). +For more information, see [Display rollup progress or totals](../../boards/backlogs/display-rollup.md). ### View rollup within sprint Planning pane @@ -43,7 +42,7 @@ As you assign backlog items to a sprint using the Planning pane, the sprint wind > [!div class="mx-imgBorder"] > ![Product backlog page, drag work items to sprint or assign to sprint through the context menu](../../boards/sprints/media/assign-items-sprint/sprint-window-effort.png) -*Planned Effort* provides a sum of all *Story Points* or *Effort* defined for backlog items assigned to the sprint. To learn more, see [Assign backlog items to a sprint](../../boards/sprints/assign-work-sprint.md). +*Planned Effort* provides a sum of all *Story Points* or *Effort* defined for backlog items assigned to the sprint. For more information, see [Assign backlog items to a sprint](../../boards/sprints/assign-work-sprint.md). ### View rollup of sprint backlogs and taskboards @@ -51,11 +50,7 @@ In addition, you can view rollup of Remaining Work from a sprint backlog or task ::: moniker-end -::: moniker range="< azure-devops-2020" - -You can view rollup of Remaining Work from a sprint backlog or task board. - -::: moniker-end + From the sprint backlog, the sum of all **Remaining Work** defined for all tasks is displayed for the parent work item. This value also displays on the parent work item card when you view the task board. @@ -66,18 +61,6 @@ From the sprint backlog, the sum of all **Remaining Work** defined for all tasks ::: moniker-end -::: moniker range="azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Sprint backlog displays rollup of Remaining Work.](media/rollup/remaining-work-rollup-2019.png ) - -::: moniker-end - -::: moniker range="tfs-2018" - -![Sprint backlog displays rollup of Remaining Work](media/alm_rup_remworkiteration.png "ALM_RUP_RemWorkIteration") - -::: moniker-end From a sprint task board, there are three types of rollup: - The rollup of Remaining Work displays on the card for the parent work item @@ -91,26 +74,13 @@ From a sprint task board, there are three types of rollup: ::: moniker-end -::: moniker range="azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Sprint backlog displays rollup of Remaining Work](media/rollup/taskboard-remaining-work-2019.png ) - -::: moniker-end - -::: moniker range="tfs-2018" - -![Task board, collapsed backlog items](../../boards/sprints/media/ALM_TB_Intro.png) - -::: moniker-end - -When you update the status of a task as Completed, the system automatically zeros out the Remaining Work for that task. To learn more, see [Task board](../../boards/sprints//task-board.md). +When you update the status of a task as Completed, the system automatically zeros out the Remaining Work for that task. For more information, see [Task board](../../boards/sprints//task-board.md). ## Other tools that support rollup You can obtain rollup of additional data fields in Azure DevOps work tracking data by using one of the following methods: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" |Method|Azure DevOps Services|On-premises Azure DevOps| |------------|----------|----------------------| @@ -122,22 +92,11 @@ You can obtain rollup of additional data fields in Azure DevOps work tracking da ::: moniker-end -::: moniker range="tfs-2018" - -- Work item query charts -- Microsoft Excel -- Microsoft Project -- Marketplace extensions -- SQL Server Reporting Services report -::: moniker-end - - - ## Work item query charts and rollup -You can create a flat list query that sums the values of a field you specify. To learn more, see [Track progress by creating status and trend query-based charts](../../report/dashboards/charts.md). Charts support a count of work items or a sum of a field. +You can create a flat list query that sums the values of a field you specify. For more information, see [Track progress by creating status and trend query-based charts](../../report/dashboards/charts.md). Charts support a count of work items or a sum of a field. For example, here we show a pivot table that sums the story points for user stories by area path and work item state. @@ -146,25 +105,13 @@ For example, here we show a pivot table that sums the story points for user stor ## Microsoft Excel and rollup of work tracking data -You can export a query to Excel that contains the work items you want to provide rollup. You can then write an Excel macro to get the sums and publish data back to TFS. To learn more about Excel integration, see [Bulk add or modify work items with Excel](../../boards/backlogs/office/bulk-add-modify-work-items-excel.md). +You can export a query to Excel that contains the work items you want to provide rollup. You can then write an Excel macro to get the sums and publish data back to TFS. For more information about Excel integration, see [Bulk add or modify work items with Excel](../../boards/backlogs/office/bulk-add-modify-work-items-excel.md). -To learn more about Excel macros, see [Automate tasks with the Macro Recorder](https://support.office.com/article/Automate-tasks-with-the-Macro-Recorder-974ef220-f716-4e01-b015-3ea70e64937b). +For more information about Excel macros, see [Automate tasks with the Macro Recorder](https://support.office.com/article/Automate-tasks-with-the-Macro-Recorder-974ef220-f716-4e01-b015-3ea70e64937b). > [!TIP] > To provide support for opening work items and query results in Excel from the web portal, add the [VSTS Open in Excel](https://marketplace.visualstudio.com/items?itemName=blueprint.vsts-open-work-items-in-excel) Marketplace extension to your organization or collection. -::: moniker range="tfs-2018" - -## Microsoft Project and rollup of work tracking data - - Project natively supports rollup of summary tasks. With Project, you can round trip work tracking data to obtain rollup values. - - ![Task board displays round-trip rollup from Project](media/alm_rup_roundtriprollup.png "ALM_RUP_RoundTripRollup") - - To learn how, see [Rollup estimated and actual work](/previous-versions/azure/devops/boards/backlogs/office/rollup-estimated-and-actual-work-using-project). -::: moniker-end - - ## Marketplace extensions and custom controls @@ -176,7 +123,7 @@ There are several extensions available from the [Marketplace](https://marketplac Or, you can write an extension using the [REST API for work tracking](/rest/api/azure/devops/wit/work%20items) to get rollup. A code sample available on github that can get you started is [TFS Aggregator](https://tfsaggregator.github.io/). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Analytics service @@ -217,7 +164,7 @@ If you need to add reports to your on-premises TFS deployment, see [Add reports If your project was created using the Visual Studio Scrum process template, only Remaining Work is defined in the task. - To learn more about adding fields, see [Modify a field or add a custom field](../add-modify-field.md). + For more information about adding fields, see [Modify a field or add a custom field](../add-modify-field.md). - Determine the unit of time used to track work and make sure it is used consistently across your team or organization. For example, you can track tasks using hours or days. - Determine if you want to make rollup values read-only on the work item form. By making them read-only you prevent users from entering inaccurate data. You make fields read-only using the `Control` field `Readonly` attribute. diff --git a/docs/reference/xml/toc.yml b/docs/reference/xml/toc.yml index ad756ff008c..a5763068140 100644 --- a/docs/reference/xml/toc.yml +++ b/docs/reference/xml/toc.yml @@ -25,7 +25,7 @@ - name: Archived articles items: - name: Change the maximum attachment size for work items - href: /previous-versions/azure/devops/reference/xml/change-maximum-attachment-size-work-items + href: /previous-versions/azure/devops/reference/xml/change-maximum-attachment-size-work-items - name: XML element reference items: - name: XML element reference @@ -81,9 +81,9 @@ - name: Customize the work item form href: /previous-versions/azure/devops/reference/customize-wit-form - name: Specify work item form controls - href: /previous-versions/azure/devops/reference/xml/specify-work-item-form-controls + href: /previous-versions/azure/devops/reference/xml/specify-work-item-form-controls - name: Define link controls - href: /previous-versions/azure/devops/reference/xml/define-link-controls + href: /previous-versions/azure/devops/reference/xml/define-link-controls - name: Web and client form layout (Legacy) items: - name: Manage roll out of the new web form @@ -107,11 +107,11 @@ - name: Link and Param href: link-param-xml-elements-reference.md - name: CATEGORIES XML reference - href: /previous-versions/azure/devops/reference/xml/categories-xml-element-reference + href: /previous-versions/azure/devops/reference/xml/categories-xml-element-reference - name: Use categories to group work item types - href: /previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types + href: /previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types - name: LinkTypes elements reference - href: /previous-versions/azure/devops/reference/xml/link-type-element-reference + href: /previous-versions/azure/devops/reference/xml/link-type-element-reference - name: Define a custom link type href: /previous-versions/azure/devops/reference/xml/define-custom-link-type - name: Reporting reference @@ -133,4 +133,4 @@ - name: Resolve errors received when configuring features href: /previous-versions/azure/devops/reference/xml/resolve-errors-received-when-configuring-features - name: Resolve process configuration issues - href: /previous-versions/azure/devops/reference/troubleshoot-process-configuration \ No newline at end of file + href: /previous-versions/azure/devops/reference/troubleshoot-process-configuration diff --git a/docs/report/analytics/analytics-best-practices.md b/docs/report/analytics/analytics-best-practices.md index 62fbf2ba285..605c3698e00 100644 --- a/docs/report/analytics/analytics-best-practices.md +++ b/docs/report/analytics/analytics-best-practices.md @@ -1,51 +1,28 @@ --- title: Analytics best practices titleSuffix: Azure DevOps -description: Learn about the best practices to use when querying Analytics for Azure DevOps. +description: Learn about the best practices to use when you query Analytics for Azure DevOps. ms.custom: analytics ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: overview -monikerRange: '>= azure-devops-2019' -ms.date: 08/12/2022 +monikerRange: "<=azure-devops" +ms.date: 11/02/2023 --- -# Best practices to use when querying Analytics +# Analytics best practices [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -There are several reasons to follow best practices when querying Analytics, such as those practices listed below. - -::: moniker range="azure-devops" - -- Ensure high performance queries -- Return just the data you need -- Minimize receipt of warning or error messages -- Minimize consumption of resources that could lead to throttling - -::: moniker-end - -::: moniker range="< azure-devops" - -- Ensure high performance queries -- Return just the data you need -- Minimize receipt of warning or error messages -::: moniker-end - -Follow the guidance provided below as you get started. If you're an extension developer, you'll also want to review [OData Analytics query guidelines](../extend-analytics/odata-query-guidelines.md). - +Analytics is the reporting platform for Azure DevOps, which allows you to gain insights from your data and make data-driven decisions. Analytics is optimized for fast read-access and server-based aggregations, and it provides various tools to visualize and analyze your data. In this article, we share some best practices for using Analytics in Azure DevOps. [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] +- If you're an extension developer, make sure to review [OData Analytics query guidelines](../extend-analytics/odata-query-guidelines.md). ## Get familiar with the Analytics metadata -Query the Analytics metadata to gain familiarity with the entity types, entity sets, properties, and enumerated lists. To learn how, see [Query the Analytics service](analytics-query-parts.md). - -In addition, you can review select information from these resources: -- [Analytics OData metadata](../extend-analytics/analytics-metadata.md) -- [Entities and properties reference for Azure Boards](entity-reference-boards.md) - +Query the Analytics metadata to gain familiarity with the entity types, entity sets, properties, and enumerated lists. For more information, see [Query the Analytics service](analytics-query-parts.md), [Analytics OData metadata](../extend-analytics/analytics-metadata.md), and [Entities and properties reference for Azure Boards](entity-reference-boards.md). ## Structure your query to return the data you need @@ -57,9 +34,7 @@ To query the minimum data set you need to create your report, follow these pract - [Create preview queries](#preview) - [Limit queries to projects you have access to](#limit-projects) - - - + ### Choose the entity set to support your report @@ -78,9 +53,7 @@ Here's a quick reference for the EntityTypes to specify to support reports. For |Azure Pipelines and Tests | `TestResultsDaily` | `TestRuns` | |Azure Test Plans | `Tests`
      `TestConfiguration`
      `TestPoints`
      `WorkItems` | `TestResultsDaily`
      `TestPointHistorySnapshot` | | - - - + ### Specify query parts in the order they're executed @@ -94,10 +67,9 @@ The recommended order for the various query parts is to specify them in the foll 1. `$skip` 1. `$top` -All queries must contain an `$apply` or `$select` clause, otherwise you may receive a warning message. - +All queries must contain an `$apply` or `$select` clause, otherwise you might receive a warning message. - + ### Limit the columns you request in your query @@ -111,8 +83,7 @@ To look up the list of properties and their corresponding field names, see [Enti Analytics is built on top of a Columnstore Index technology. That means that data is both storage and query processing is column-based. So, the more properties that a query references, the more expensive it's to process. --> - - + ### Create preview queries @@ -140,19 +111,17 @@ The response returns a total of 1415 work items. } ``` - - - + ### Limit queries to projects you have access to Project-scope queries return information about a single project, whereas organization-scope queries are designed to return information that cross project boundaries. Organization scoped queries require broader user permissions or careful scoping restrictions to ensure that your query isn't blocked due to a lack of project permissions. -If you have access to one or more projects, but not all projects, and you submit an organization-scoped query, you'll receive an error message. +If you have access to one or more projects, but not all projects, and you submit an organization-scoped query, you receive an error message. `"VS403496: The query results include data in one or more projects for which you do not have access. Add one or more projects filters to specify the project(s) you have access to in 'WorkItems' entity. If you're using $expand or navigation properties, project filter is required for those entities. More information can be found here: https://go.microsoft.com/fwlink/?LinkId=786441."` -To learn more, see [Project and organization-scoped queries](../extend-analytics/account-scoped-queries.md). +For more information, see [Project and organization-scoped queries](../extend-analytics/account-scoped-queries.md). ## Review warning and error messages @@ -160,10 +129,9 @@ Analytics reviews each query it receives for violations to its rules. It returns ::: moniker range="azure-devops" - ## Rate limits and throttling -Queries made to Analytics for Azure DevOps Services are subject to rate limits. If too many queries are sent that request the return of large amounts of data within a short time frame, the service may be subject to throttling. Rate limits are discussed in [Service and rate limits for Azure DevOps Services](../../user-guide/service-limits.md). +Queries made to Analytics for Azure DevOps Services are subject to rate limits. If too many queries are sent that request the return of large amounts of data within a short time frame, the service might be subject to throttling. For more information, see [Rate and usage limits](../../integrate/concepts/rate-limits.md). You can review usage for the service and for individuals by going to **Organization Settings>Usage** and exercising the filters. For example, the following image shows the usage by *Jamal Hartnett* to the Analytics service. @@ -171,39 +139,9 @@ You can review usage for the service and for individuals by going to **Organizat ::: moniker-end - - ## Related articles - [What is the Analytics service?](../powerbi/what-is-analytics.md) - [Construct OData queries for Analytics](analytics-query-parts.md) - [Analytics OData metadata](../extend-analytics/analytics-metadata.md) - [OData Analytics query guidelines](../extend-analytics/odata-query-guidelines.md) - - - - \ No newline at end of file diff --git a/docs/report/analytics/analytics-permissions-prerequisites.md b/docs/report/analytics/analytics-permissions-prerequisites.md index d735df38e6e..2283a582ae5 100644 --- a/docs/report/analytics/analytics-permissions-prerequisites.md +++ b/docs/report/analytics/analytics-permissions-prerequisites.md @@ -6,7 +6,7 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 09/30/2022 --- @@ -34,41 +34,32 @@ For Azure DevOps Services, Analytics is always on. You can't disable it or pause For Azure DevOps Server 2020 and later on-premises versions, Analytics is automatically installed with each project collection you create. ::: moniker-end - -::: moniker range="azure-devops-2019" -For Azure DevOps Server 2019, you must first install Analytics on each project collection you create. -::: moniker-end - ::: moniker range="< azure-devops" You can pause and restart the service. When paused, no new data is added to Analytics. -To learn more, see [Install or enable the Analytics service](../dashboards/analytics-extension.md). +For more information, see [Install or enable the Analytics service](../dashboards/analytics-extension.md). ::: moniker-end - ### Azure DevOps services To exercise any Azure DevOps service, it must be enabled. No data can be captured for a service that has been disabled. Services can be enabled or disabled on a project by project basis. To verify that all services are enabled, see [Turn a service on or off](../../organizations/settings/set-services.md). - ### Analytics views -**Analytics views**, a hub in your web portal, provides a simplified way to specify the filter criteria for a Power BI report based on the Analytics data. To learn more, see [What is the Analytics Service?](../powerbi/what-are-analytics-views.md) +**Analytics views**, a hub in your web portal, provides a simplified way to specify the filter criteria for a Power BI report based on the Analytics data. For more information, see [What is the Analytics Service?](../powerbi/what-are-analytics-views.md) -To access **Analytics views**, you must have it enabled. The organization owner or member of the Project Collection Administrators group can enable it for everyone in the organization. Or, each project member can enable it for themselves. +To access **Analytics views**, have it enabled. The organization owner or member of the Project Collection Administrators group can enable it for everyone in the organization. Or, each project member can enable it for themselves. To learn how, see [Manage or enable features](../../project/navigation/preview-features.md). - ## Permissions You set [permissions](../../report/powerbi/analytics-security.md) for the service at the project level, and for shared **Analytics views** at the object level. The following table summarizes the permissions available to be set and the default assignments made to the project security groups. - |Permission| Readers | Contributors |Project Administrators| |----------|----------|------------------|-------------------| |**View Analytics** |✔️|✔️|✔️| @@ -96,7 +87,7 @@ For a review of available entity sets that you can query, see [Metadata referenc To report on work tracking, teams need to perform several tasks to ensure meaningful data is available. Review the following tasks prior to defining your Analytics queries and reports. - To report on active bugs or bug trends, define bugs and update the bug **State** as it is fixed, verified, and then closed. - To report on backlog work or other work item types, make sure you define those work items, and update their **State** as it moves from new to closed. Consider whatever fields or tags you'll use to filter or group data in a report and make sure that is well defined and consistent. -- To support rollup reports, ensure parent-child links exist between product backlog items and tasks/bugs, or parent-child links exist between features or portfolio backlog work items and their child items. To learn more, see [Organize your backlog and map child work items to parents](../../boards/backlogs/organize-backlog.md). +- To support rollup reports, ensure parent-child links exist between product backlog items and tasks/bugs, or parent-child links exist between features or portfolio backlog work items and their child items. For more information, see [Organize your backlog and map child work items to parents](../../boards/backlogs/organize-backlog.md). - To create burndown or burnup reports, such as [Sprint burndown](../powerbi/sample-boards-sprintburndown.md) or [Release burndown](../powerbi/sample-boards-releaseburndown.md), ensure you have thought through how you want to filter and group data in your report. Burndown/burnup reports reference the `WorkItemsSnapshot` entity set. Snapshot entity sets are modeled as daily snapshots. Data is aggregated based on assignments made as of the date they are assigned. What this means is that to filter a burndown/burnup report based on field or tag assignments, you must assign the fields or tags prior to the period you want to report on. Otherwise, the fields/tags aren't registered by the report until the date on which they are applied. - To support [Requirements tracking](../powerbi/sample-stories-overview.md), define test cases, and create a **Tested By** link from each test case to a user story, product backlog item, or requirement. Define test cases and link test cases to their parent PBIs using the Tested By link. See Create your tests. @@ -110,7 +101,7 @@ Define test cases and link test cases to their parent PBIs using the Tested By l ### Test plans To review test plan progress and test case readiness, teams need to perform the following activities. -- Define test cases, test plans, and test suites, and specify their current state. To learn more, see [Create test plans and test suites](../../test/create-a-test-plan.md) and [Create test cases](../../test/create-test-cases.md). +- Define test cases, test plans, and test suites, and specify their current state. For more information, see [Create test plans and test suites](../../test/create-a-test-plan.md) and [Create test cases](../../test/create-test-cases.md). - Update the **State** of test objects as they progress from *Design* to *Ready* to *Closed*. - For manual tests, mark the results of each validation step in the test case as passed or failed. > [!TIP] @@ -121,7 +112,7 @@ To review test plan progress and test case readiness, teams need to perform the ### Pipelines -To report on pipelines, teams need to Define pipelines using YAML and run pipelines regularly. To learn more, see [Key concepts for new Azure Pipelines users](../../pipelines/get-started/key-pipelines-concepts.md). +To report on pipelines, teams need to Define pipelines using YAML and run pipelines regularly. For more information, see [Key concepts for new Azure Pipelines users](../../pipelines/get-started/key-pipelines-concepts.md). In addition, consider the following actions: - Consider what data you want to report on and choose the correct entity set. For a review of available entity sets to query, see [Metadata reference for Azure Pipelines Analytics](entity-reference-pipelines.md). @@ -129,20 +120,17 @@ In addition, consider the following actions: ### Pipelines and test -To report on pipelines and tests results, make sure you add test tasks to the pipeline definition. To learn more, see [Build and release tasks-Test](../../pipelines/tasks/index.md#test). +To report on pipelines and tests results, make sure you add test tasks to the pipeline definition. For more information, see [Build and release tasks-Test](../../pipelines/tasks/index.md#test). If you're just getting started, consider reviewing this Learn module, [Run quality tests in your build pipeline by using Azure Pipelines](/training/modules/run-quality-tests-build-pipeline). ::: moniker-end - ## Related articles - [What is the Analytics service?](../powerbi/what-is-analytics.md) - [Default permissions quick reference for Azure DevOps](../../organizations/security/permissions-access.md) - [Best practices to use when querying the Analytics service](analytics-best-practices.md) - - diff --git a/docs/report/analytics/analytics-query-parts.md b/docs/report/analytics/analytics-query-parts.md index a9d982f2804..cc4cf4188d1 100644 --- a/docs/report/analytics/analytics-query-parts.md +++ b/docs/report/analytics/analytics-query-parts.md @@ -7,7 +7,7 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: tutorial -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 11/04/2022 --- @@ -31,9 +31,11 @@ You can query Analytics from any [supported web browser](/azure/devops/server/co > [!NOTE] > OData, an application-level protocol for interacting with data via RESTful (where REST=Representational State Transfer) interfaces), supports the description of data models as well as editing and querying of data according to those models. The Entity Data Model (EDM) or metadata describes the information available from Analytics, including the entities, entity types, properties, relationships, and enumerations you use to query the data to build reports. For an overview of OData, see [Welcome to OData](/odata/overview). +## Prerequisites + [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] - + ## URL components to query the metadata @@ -64,7 +66,6 @@ https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/ Analytics service root URL Organization/Project OData version return metadata ``` - > [!NOTE] > The latest Analytics OData version is **v4.0-preview**. You can use this version for all queries against the hosted service. For more information on Analytics versions and available data, see [Data model for Analytics](../extend-analytics/data-model-analytics-service.md). @@ -90,7 +91,6 @@ https://{ServerName}/{CollectionName}/{ProjectName}/_odata/version/$metadata > [!NOTE] > The latest Analytics OData version is **v4.0-preview**. You can use this version for all queries against the hosted service. For more information on Analytics versions and available data, see [Data model for Analytics](../extend-analytics/data-model-analytics-service.md). - Here's an example for the server named `fabrikam-devops` and the `DefaultCollection` hosted on Azure DevOps Server 2022: > [!div class="tabbedCodeSnippets"] @@ -100,13 +100,12 @@ https://fabrikam-devops/DefaultCollection/_odata/v4.0-preview/$metadata *** - + ### Interpret the metadata response Analytics returns an XML file of the data model. Use your browser search function to find information specific to the entity of interest. - > [!TIP] > Depending on the browser you're using, this file may or may not be formatted in a readable manner. If it isn't formatted, you can find a free online XML formatter through a web browser search. @@ -127,7 +126,7 @@ The two main schemas defined in the Analytics metadata are `Microsoft.VisualStud > > ``` - + ### Related entities and navigation properties @@ -184,7 +183,7 @@ The following code snippet provides a partial view of the metadata for the `Work > ... > ``` - + ## URL components to query entities @@ -261,8 +260,7 @@ For entity metadata property and relationship information, see the following art - [Metadata reference for Azure Pipelines](entity-reference-pipelines.md) - [Metadata reference for Test Plans](entity-reference-test-plans.md) - - + ### Example: Query a specific entity set @@ -333,8 +331,6 @@ The example return three project names. > ``` *** - - ## Query options A query option is a set of query string parameters applied to a resource that can help control the amount of data being returned for the resource in the URL. @@ -355,14 +351,12 @@ Query options should be specified in the order listed in the following table. > [!TIP] > Avoid mixing `$apply` and `$filter` clauses in a single query. To filter your query, you have two options: (1) use a `$filter` clause or (2) use a `$apply=filter()` combination clause. Each one of these options works great on its own, but combining them together might lead to some unexpected results. - ## Enforce server-side paging Analytics forces paging when query results exceed 10000 records. In that case, you'll get first page of data and link to follow to get next page. Link (`@odata.nextLink`) can be found at the end of the JSON output. It will look like an original query followed by `$skip` or `$skiptoken`. For example: - > [!div class="tabbedCodeSnippets"] > ```JSON > { @@ -402,13 +396,11 @@ Mention WIQL to Odata extension Query work item data - Record count query https://analytics.dev.azure.com/content-learn/Content/_odata/v4.0-preview/WorkItems? $count=true&$select=WorkItemId,Title,WorkItemType,State,CreatedDate - Construct a basic query Query parts (Apply, filter, select, …) Compute @@ -424,5 +416,4 @@ Count Return data from related entities Enforce server-side paging - --> diff --git a/docs/report/analytics/analytics-query-tools.md b/docs/report/analytics/analytics-query-tools.md index 6fa4116b23e..cea1d69a916 100644 --- a/docs/report/analytics/analytics-query-tools.md +++ b/docs/report/analytics/analytics-query-tools.md @@ -7,7 +7,7 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 08/12/2022 --- @@ -22,22 +22,18 @@ To help you get started, use the guidance provided in the following table to det | Task | Tool | Notes | |------|---------|---------------------------| | Query the metadata | [Any supported web browser](/azure/devops/server/compatibility#supported-browsers) | Review the Analytics data model consisting of EntityTypes, properties, enumerated member names, supported functions, and more. To get started, see [Query the Analytics service](analytics-query-parts.md). | -| Create a status or trend report for work tracking data | [Analytics views](../powerbi/what-are-analytics-views.md)
      Power BI | Use a default view or create a custom view to filter work tracking data. To learn more, see [Create a Power BI report with a default Analytics view](../powerbi/create-quick-report.md). | +| Create a status or trend report for work tracking data | [Analytics views](../powerbi/what-are-analytics-views.md)
      Power BI | Use a default view or create a custom view to filter work tracking data. For more information, see [Create a Power BI report with a default Analytics view](../powerbi/create-quick-report.md). | | Create a report from a work item query | [WIQL to OData extension](https://marketplace.visualstudio.com/items?itemName=ms-eswm.wiql-to-odata)
      Power BI | Install the extension to get an OData query based on the filtered set of work items. Then use [Create a Power BI report with an OData Query](../powerbi/create-quick-report-odataq.md). | -|Create reports or dashboards based on Analytics data | Power BI | You can specify a Power BI query or OData query within Power BI to filter the data. To learn more, see [Overview of sample reports using OData queries](../powerbi/sample-odata-overview.md). | +|Create reports or dashboards based on Analytics data | Power BI | You can specify a Power BI query or OData query within Power BI to filter the data. For more information, see [Overview of sample reports using OData queries](../powerbi/sample-odata-overview.md). | | Write and test OData | [Visual Studio Code](https://code.visualstudio.com/download)
      [OData for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=stansw.vscode-odata) | Visual Studio Code is a free code editor available on Windows, Mac, and Linux. The OData extension provides syntax highlighting and other functions that are useful for writing and testing queries. | ## Related articles - - [What is the Analytics service?](../powerbi/what-is-analytics.md) - [Construct OData queries for Analytics](analytics-query-parts.md) - [Analytics OData metadata](../extend-analytics/analytics-metadata.md) - ### Related resources - [Ecosystem · OData - the Best Way to REST](https://www.odata.org/ecosystem/) - - diff --git a/docs/report/analytics/entity-reference-boards.md b/docs/report/analytics/entity-reference-boards.md index b2e2405e42f..ac8dbb61d1d 100644 --- a/docs/report/analytics/entity-reference-boards.md +++ b/docs/report/analytics/entity-reference-boards.md @@ -6,22 +6,20 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 11/07/2022 --- - # Metadata reference for Azure Boards Analytics [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] The Analytics service collects all work tracking activity defined and updated through Azure Boards. Analytics stores as properties all work tracking fields, except for HTML/rich-text and History fields. Custom properties for custom fields are automatically added to Analytics. -This article describes the majority of properties that you can use to generate an Analytics report for work tracking. You use a combination of properties to filter a query, aggregate data, or build a report. You can run these queries directly in your browser. To learn more, see [Define basic queries using OData Analytics](../extend-analytics/wit-analytics.md). If you're new to work tracking and Azure Boards, we recommend you review the following articles: +This article describes the majority of properties that you can use to generate an Analytics report for work tracking. You use a combination of properties to filter a query, aggregate data, or build a report. You can run these queries directly in your browser. For more information, see [Define basic queries using OData Analytics](../extend-analytics/wit-analytics.md). If you're new to work tracking and Azure Boards, we recommend you review the following articles: - [What is Azure Boards?](../../boards/get-started/what-is-azure-boards.md) - [Track user stories, issues, bugs, and other work items in Azure Boards](../../boards/work-items/about-work-items.md) - [!INCLUDE [note-analytics-early-draft](../includes/note-analytics-data-model.md)] ## Overview of entity sets @@ -33,20 +31,20 @@ When querying Analytics for work tracking data, use one of the following entity Use other entity types, such as `Area`, `Iteration`, `Project`, `Team`, or other entities to filter data or select properties to report on. For a summary of example reports, see [Sample reports and quick reference index](../extend-analytics/quick-ref.md). > [!NOTE] -> To generate status and trend reports on test-specific work item types, query the `WorkItems` and `WorkItemSnapshot` entity types and filter based on the work item type. For information on test runs, test results, or other test data, query the `TestRuns`, `TestPoints`, `TestResultsDaily`, `TestSuite` or `TestPointHistorySnapshot` entity types. To learn more, see [Test metadata reference for Azure DevOps](entity-reference-test-plans.md). +> To generate status and trend reports on test-specific work item types, query the `WorkItems` and `WorkItemSnapshot` entity types and filter based on the work item type. For information on test runs, test results, or other test data, query the `TestRuns`, `TestPoints`, `TestResultsDaily`, `TestSuite` or `TestPointHistorySnapshot` entity types. For more information, see [Test metadata reference for Azure DevOps](entity-reference-test-plans.md). |`EntitySet` | `EntityType` | Description | |------------|-------------|-------------| |[**Areas**](#areas) | **Area** |The work item **Area Paths**, with properties for grouping and filtering by area hierarchy. | |[**Dates**](entity-reference-general.md#dates)|**CalendarDate**|The dates used to filter and group other entities using relationships.| |[**Iterations**](#iterations) | **Iteration** |The work item **Iteration Paths**, with properties for grouping and filtering by iteration hierarchy. | -|[**BoardLocations**](#kanban-board-properties-fields) |**BoardLocation**| The Kanban board cell locations, as identified by board column, swimlane, and split, includes historic board settings. For a description of each Kanban board field, see [Workflow and Kanban board fields](../../boards/queries/query-by-workflow-changes.md#workflow-and-kanban-board-fields).| +|[**BoardLocations**](#kanban-board-properties-fields) |**BoardLocation**| The board cell locations, as identified by board column, swimlane, and split, includes historic board settings. For a description of each board field, see [Workflow and board fields](../../boards/queries/query-by-workflow-changes.md#workflow-and-board-fields).| |[**Processes**](#processes) |**Process** | Backlog information used to expand or filter work items and work item types. For an example that uses **Processes** to filter a report, see [Requirements tracking sample report](../powerbi/sample-stories-overview.md). Supported for Analytics v2.0 version and later. | |[**Projects**](entity-reference-general.md#projects)|**Project** |All projects defined for an organization (cloud) or project collection (on-premises). | |[**Tags**](#tags) | **Tag** |All work item tags for each project. For an example that uses **Tags** to filter a report, see [Release burndown sample report](../powerbi/sample-boards-releaseburndown.md). | |[**Teams**](#teams) | **Team** |All teams defined for the project. For an example that uses **Teams** to filter a report, see [Add a Team slicer to a Power BI report](../powerbi/sample-boards-teamslicer.md). | |[**Users**](entity-reference-general.md#users)|**User** |User information that is used to expand or filter various work item properties, for example **Assigned To**, **Created By**. | -|[**WorkItemBoardSnapshot**](#kanban-board-properties-fields) |**WorkItemBoardSnapshot** |(Composite) The state of each work item on each calendar date, including Kanban board location, used to generate trend reports. For a sample report, see [Cumulative Flow Diagram (CFD) sample report](../powerbi/sample-boards-cfd.md). | +|[**WorkItemBoardSnapshot**](#kanban-board-properties-fields) |**WorkItemBoardSnapshot** |(Composite) The state of each work item on each calendar date, including board location, used to generate trend reports. For a sample report, see [Cumulative Flow Diagram (CFD) sample report](../powerbi/sample-boards-cfd.md). | |[**WorkItemLinks**](#workitemlinks)| **WorkItemLink** |The links between work items, for example, *Child*, *Parent*, and *Related*. Includes only the latest revision of links, no history. Hyperlinks aren't included. | |[**WorkItemRevisions**](#property-names-fields) |**WorkItemRevision** |All historic work item revisions, including the current revision. Doesn't include deleted work items. | |[**WorkItemSnapshot**](#property-names-fields) |**WorkItemSnapshot** |(Composite) The state of each work item on each calendar date, used to support trend reporting. For a sample report, see [Bug trends sample report](../powerbi/sample-boards-bugtrend.md). | @@ -59,8 +57,7 @@ There are two work tracking snapshot entity sets: `WorkItemSnapshot` and `WorkIt A snapshot provides a record of the values defined for a work item each day. The record is written to Analytics once a day at the same time each day. You use snapshots when you want to generate a trend report. By default, all the snapshot tables are modeled as daily snapshot fact tables. If you query for a time range it will get a value for each day. Long time ranges result in a large number of records. If you don't need such high precision, you can use weekly or even monthly snapshots. -To learn more, see [OData query guidelines, Do use weekly or monthly snapshots for trend queries that span a long time period](../extend-analytics/odata-query-guidelines.md#-do-use-weekly-or-monthly-snapshots-for-trend-queries-that-span-a-long-time-period). - +For more information, see [OData query guidelines, Do use weekly or monthly snapshots for trend queries that span a long time period](../extend-analytics/odata-query-guidelines.md#-do-use-weekly-or-monthly-snapshots-for-trend-queries-that-span-a-long-time-period). ### About work item revisions @@ -72,7 +69,7 @@ If you want all the dates since the `{startDate}` inclusive, add the following f You use the `WorkItemRevisions` entity set to load all the revisions for a given work item. The query returns all historic work item revisions, including the current revision, for the work items you filter on. It doesn't include deleted work items. - + ## Shared properties across several entity types @@ -123,7 +120,7 @@ Many properties are date-based or user-based. These properties are associated wi |**Created Date**
      `CreatedDate`
      `CreatedDateSK`| DateTime | The date the work item was created, expressed in the [time zone defined for the organization](../../organizations/accounts/change-organization-location.md). Commonly used for filtering and for display.
      `Microsoft.VSTS.Common.CreatedDate` | |`CreatedDateSK`| Int32 | The date the work item was created, expressed as `YYYYMMDD` in the time zone defined for the organization. Used by external tools to join related entities. | |`CreatedOn` | Navigation | Navigation property to the `Date` entity for the date the work item was created, in the time zone defined for the organization. Commonly used to reference properties from the `Date` entity in ```groupby``` statements. | -|**Cycle Time Days**
      `CycleTimeDays` | Double | Cycle time is calculated from first entering an *In Progress* or *Resolved* state category to entering a *Completed* state category. To learn more, see [Lead Time and Cycle Time widgets](../dashboards/cycle-time-and-lead-time.md). | +|**Cycle Time Days**
      `CycleTimeDays` | Double | Cycle time is calculated from first entering an *In Progress* or *Resolved* state category to entering a *Completed* state category. For more information, see [Lead Time and Cycle Time widgets](../dashboards/cycle-time-and-lead-time.md). | |**Discipline**
      `Discipline` | String | The type of activity or discipline that is assigned to a task. Allowed values are: *Analysis**, **Development**, **Test**, **User Education**, and **User Experience**. (CMMI process)
      `Microsoft.VSTS.Common.Activity` | |**Due Date**
      `DueDate` | DateTime | The forecasted due date by which an issue or work item will be resolved. (Agile process)
      `Microsoft.VSTS.Scheduling.DueDate` | | **Effort**
      `Effort` | Double | An estimate for the amount of work that a product backlog item (Scrum process) or issue (Basic process) will require to implement.
      `Microsoft.VSTS.Scheduling.Effort` | @@ -136,7 +133,7 @@ Many properties are date-based or user-based. These properties are associated wi |**Is Last Revision of Day**
      `IsLastRevisionOfDay` | Boolean | Indicates that the snapshot represents the last revision of the day when set to `True`.| |**Is Last Revision of Period**
      `IsLastRevisionOfPeriod` | Boolean | Indicates that the snapshot represents the last revision of the period when set to `True`. | |**Issue**
      `Issue` | String | Indicates that the shared step is associated with an expected result. Allowed values are **Yes** and **No**.
      `Microsoft.VSTS.Common.Issue` | -| **Lead Time Days**
      `LeadTimeDays` | Double | Lead time is calculated from work item creation or entering a *Proposed* state category to entering a *Completed* state category. To learn more, see [Lead Time and Cycle Time widgets](../dashboards/cycle-time-and-lead-time.md). | +| **Lead Time Days**
      `LeadTimeDays` | Double | Lead time is calculated from work item creation or entering a *Proposed* state category to entering a *Completed* state category. For more information, see [Lead Time and Cycle Time widgets](../dashboards/cycle-time-and-lead-time.md). | |**Original Estimate**
      `OriginalEstimate` | Double | A measure of the amount of work that is required to complete a task.
      `Microsoft.VSTS.Scheduling.OriginalEstimate` | |**Parent Work Item Id**
      `ParentWorkItemId` | Int32 | The unique ID that identifies the work item linked to as a parent. Useful for generating rollup reports. The **Parent** field is available from Azure DevOps Server 2020 and later versions. Valid for these entity types: `WorkItemRevision` and `WorkItem`.
      `System.Parent` | |**Priority**
      `Priority` | Int32 | A subjective rating of the bug, issue, task, or test case as it relates to the business. Values include: - **1**, **2**, or **3**.
      `Microsoft.VSTS.Common.Priority` | @@ -160,7 +157,7 @@ Many properties are date-based or user-based. These properties are associated wi |**Stack Rank**
      `StackRank` | Double | A number assigned by a system background process used to stack rank or track the sequence of items on a backlog or board. (Agile, Scrum, and Basic processes)
      `Microsoft.VSTS.Common.StackRank` | | **Start Date**
      `StartDate` | DateTime | Date and time assigned to a work item for work to start.
      `Microsoft.VSTS.Scheduling.StartDate` | | **State**
      `State` | String | The current state of the work item. The valid values for state are specific to each type of work item and customizations made to it.
      `System.State` | -|**State Category**
      `StateCategory` | String | State categories determine how Azure Boards and select dashboard widgets treat each workflow state. The state categories in use include: *Proposed*, *In Progress*, *Resolved*, *Removed*, and *Completed*. To learn more, see [How to use workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md). Valid only for the `WorkItemRevision` entity type. | +|**State Category**
      `StateCategory` | String | State categories determine how Azure Boards and select dashboard widgets treat each workflow state. The state categories in use include: *Proposed*, *In Progress*, *Resolved*, *Removed*, and *Completed*. For more information, see [How to use workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md). Valid only for the `WorkItemRevision` entity type. | |**State Change Date**
      `StateChangeDate` | DateTime | The date and time when the value of the **State** field changed.
      `Microsoft.VSTS.Common.StateChangeDate` | |`StateChangeSK`| Int32 | The date the State for a work item was changed, expressed as `YYYYMMDD` in the time zone defined for the organization. Used by external tools to join related entities. | |`StateChangeOn` | Navigation | Navigation property to the `Date` entity for the date the State for a work item was changed, in the time zone defined for the organization. Commonly used to reference properties from the `Date` entity in ```groupby``` statements. | @@ -213,7 +210,6 @@ Navigation properties in OData are the reference attributes of an entity that po | **Descendants** | | `WorkItem` | | **WorkItem** | `WorkItemId` | `WorkItemRevision` | - ### Predict functions The following two functions are supported for the **WorkItem** entity. These functions are used in supporting predictive trends on select Analytics built-in reports and widgets. @@ -221,12 +217,11 @@ The following two functions are supported for the **WorkItem** entity. These fun - `Predict` - - + ## BoardLocation and WorkItemBoardSnapshot -Properties listed and described in the following table are defined for the following entity types, unless specifically noted. With these fields, you can filter work item data based on the status of a work item within a team's Kanban board column, swimlane, or backlog level. +Properties listed and described in the following table are defined for the following entity types, unless specifically noted. With these fields, you can filter work item data based on the status of a work item within a team's board column, swimlane, or backlog level. - `BoardLocation` - `WorkItemBoardSnapshot` @@ -235,23 +230,23 @@ For an example that queries the `WorkItemBoardSnapshot` entity set, see [Cumulat |**Display name**
      `Property name` | **Data type** | **Description**
      `Reference name` | |-------------------------------------|---------------|--------------------------------------| -|**Board Id**
      `BoardId` | Guid | The unique GUID assigned to a Kanban board. Each team is associated with one or more Kanban boards. | -|**Board Category Reference Name**
      `BoardCategoryReferenceName` | String | The name assigned to the category of work item types used to populate a Kanban board. For example, the product backlog board is associated with the Requirements category. To learn more, see [Customize your backlogs or boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md). | -| **Board Name**
      `BoardName` | String | The name assigned to the Kanban board. For example, *Stories*, *Backlog Items*, *Features*, and *Epics*. | -|**Board Level**
      `BoardLevel` | Int32 | The number assigned to the Kanban board based on where it sits within the hierarchy of Kanban boards. | +|**Board Id**
      `BoardId` | Guid | The unique GUID assigned to a board. Each team is associated with one or more boards. | +|**Board Category Reference Name**
      `BoardCategoryReferenceName` | String | The name assigned to the category of work item types used to populate a board. For example, the product backlog board is associated with the Requirements category. For more information, see [Customize your backlogs or boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md). | +| **Board Name**
      `BoardName` | String | The name assigned to the board. For example, *Stories*, *Backlog Items*, *Features*, and *Epics*. | +|**Board Level**
      `BoardLevel` | Int32 | The number assigned to the board based on where it sits within the hierarchy of boards. | |**Backlog Type**
      `BacklogType` | String | The name of the type of backlog. For example, Iteration, Requirement, or Portfolio. | -|**Column Name**
      `ColumnName` | String | The name of the Kanban board column that a work item is currently assigned, such as *Active*, **Closed**, **Committed**, **Done**, or other custom column label.
      `System.BoardColumn` | -|**Column Order**
      `ColumnOrder` | Int32 | The number assigned to the Kanban board column in terms of its sequence within the Kanban board. | +|**Column Name**
      `ColumnName` | String | The name of the board column that a work item is currently assigned, such as *Active*, **Closed**, **Committed**, **Done**, or other custom column label.
      `System.BoardColumn` | +|**Column Order**
      `ColumnOrder` | Int32 | The number assigned to the board column in terms of its sequence within the board. | |**Done**
      `Done` | Enumerated | Indicates the split-column location. Valid values are listed below for [BoardColumnSplit](#boardcolumnsplit-enumerated-members). | -|**Column Item Limit**
      `ColumnItemLimit` | Int32 | The number assigned to the Kanban board column in terms of its sequence. | +|**Column Item Limit**
      `ColumnItemLimit` | Int32 | The number assigned to the board column in terms of its sequence. | |**Is Board Visible**
      `IsBoardVisible` | Boolean | Indicates if the team has elected to make a board visible or not. | -|**Is Column Split**
      `IsColumnSplit` | Boolean | Indicates if a column has been split into **Doing** and **Done** columns as described in [Split columns on your Kanban board to show work in progress](../../boards/boards/split-columns.md). | +|**Is Column Split**
      `IsColumnSplit` | Boolean | Indicates if a column has been split into **Doing** and **Done** columns as described in [Split columns on your board to show work in progress](../../boards/boards/split-columns.md). | |**Is Current**
      `IsCurrent` | Boolean | Property that supports filtering the data to view the most recent snapshot of the filtered set of work items by setting the value to `True`. | |**Is Default Lane**
      `IsDefaultLane` | Boolean | Property that indicates the work item is assigned to the default swimlane (True) or not (False). | -|**Is Done**
      `IsDone` | Boolean | The current assignment of the work item to **Doing** (False) or **Done** (True) within a Kanban column. Only assigned when [split-columns](../../boards/boards/split-columns.md) is enabled for a Kanban board column.
      `System.BoardColumnDone` | -|**Lane Id**
      `LaneId` | Guid | The unique GUID assigned to a Kanban board swim lane. Each team can add one or more swim lanes to a Kanban board. To learn more about swimlanes, see [Speed up your team's work by using swimlanes in your Kanban board](../../boards/boards/expedite-work.md). | -|**Lane Name**
      `LaneName` | String | The name assigned to the Kanban board swimlane.
      `System.BoardLane` | -|**Lane Order**
      `LaneOrder` | Int32 | The number assigned to the Kanban board swimlane in terms of its sequence. | +|**Is Done**
      `IsDone` | Boolean | The current assignment of the work item to **Doing** (False) or **Done** (True) within a column. Only assigned when [split-columns](../../boards/boards/split-columns.md) is enabled for a board column.
      `System.BoardColumnDone` | +|**Lane Id**
      `LaneId` | Guid | The unique GUID assigned to a board swim lane. Each team can add one or more swim lanes to a board. For more information about swimlanes, see [Speed up your team's work by using swimlanes in your board](../../boards/boards/expedite-work.md). | +|**Lane Name**
      `LaneName` | String | The name assigned to the board swimlane.
      `System.BoardLane` | +|**Lane Order**
      `LaneOrder` | Int32 | The number assigned to the board swimlane in terms of its sequence. | ### BoardColumnSplit enumerated members @@ -263,10 +258,9 @@ The following table lists the member names for the `BoardColumnSplit` enumerated |`Done` | 1 | Done | |`Unknown` | 2 | Unknown (not split) | - -To learn more about board columns for a team, see the following articles: -- [Add columns to your Kanban board to manage your workflow](../../boards/boards/add-columns.md) -- [Split columns on your Kanban board to show work in progress](../../boards/boards/split-columns.md) +For more information about board columns for a team, see the following articles: +- [Add columns to your board to manage your workflow](../../boards/boards/add-columns.md) +- [Split columns on your board to show work in progress](../../boards/boards/split-columns.md) ## Areas @@ -286,7 +280,7 @@ The following properties are valid for the **Areas** entity set, which is associ Navigation properties for the **Area** entity type and **Areas** entity set include `Project` and `Teams`. -To learn more about **Area Paths**, see the following articles: +For more information about **Area Paths**, see the following articles: - [About area and iteration (sprint) paths](../../organizations/settings/about-areas-iterations.md) - [Define area paths and assign to a team](../../organizations/settings/set-area-paths.md) @@ -311,7 +305,7 @@ The following properties are valid for the **Iterations** entity set, which is a Navigation properties for the **Iteration** entity type and **Iterations** entity set include `Project` and `Teams`. -To learn more about **Iteration Paths**, see the following articles: +For more information about **Iteration Paths**, see the following articles: - [About area and iteration (sprint) paths](../../organizations/settings/about-areas-iterations.md) - [Define iteration paths (sprints) and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md) @@ -339,7 +333,7 @@ You can use these properties to filter on work tracking data based on a backlog |**Is Bug Type** | `IsBugType` | Boolean | Indicates if the work item type belongs to the Bug category. | |**Is Deleted** | `IsDeleted` | Boolean | Indicates if the work item type has been deleted. | -To learn more about process backlogs and work item types, see the following articles: +For more information about process backlogs and work item types, see the following articles: - [Create and manage inherited processes](../../organizations/settings/work/manage-process.md) - [Add and manage work item types](../../organizations/settings/work/customize-process-work-item-type.md) - [Customize your backlogs or boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md) @@ -350,10 +344,9 @@ Data for custom work item types are automatically added to the Analytics service A custom category is created when a custom work item type and backlog level are defined. `Custom_` is prepended to the category GUID. For example, for the **Portfolio** custom work item type with a Portfolios backlog, a GUID is assigned to the custom category, such as `Custom.49b81c4e-9c4f-4c04-94fd-d660cbf3a000`. - ## Tags -The following properties are valid for the **Tags** entity set. Surrogate keys associated with **Tag** include `TagSK` and `ProjectSK`. Navigational properties include [`Project`](entity-reference-general.md#projects) and its referential constraint `ProjectSK`. To learn more about using tags, see [Add work item tags to categorize and filter lists and boards](../../boards/queries/add-tags-to-work-items.md). +The following properties are valid for the **Tags** entity set. Surrogate keys associated with **Tag** include `TagSK` and `ProjectSK`. Navigational properties include [`Project`](entity-reference-general.md#projects) and its referential constraint `ProjectSK`. For more information about using tags, see [Add work item tags to categorize and filter lists and boards](../../boards/queries/add-tags-to-work-items.md). You can use these properties to filter or report on work tracking data. @@ -362,7 +355,6 @@ You can use these properties to filter or report on work tracking data. |**Tag Id** | `TagId` | GUID | The unique ID assigned to the tag when it's created. | |**Tag Name** | `TagName` | String | The tag name. | - ## Teams The following properties are valid for the **Team** entity type and **Teams** entity set. Surrogate keys associated with **Team** include `TeamSK` and `ProjectSK`. You can use these properties to filter or report on work tracking data based on team assignments. For information on using and adding teams, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md) and [Create or add a team](../../organizations/settings/add-teams.md). @@ -373,7 +365,6 @@ The following properties are valid for the **Team** entity type and **Teams** en |**Team Id** | `TeamId` | GUID | The unique ID assigned to the team when it's created. | |**Team Name** | `TeamName` | String | The team name. | - Navigation properties for the **Teams** entity set include `Projects`, `Areas`, and `Iterations`. ## WorkItemLinks @@ -396,16 +387,13 @@ Query **WorkItemLinks** to report on parent/child, related, predecessor/successo |**Source Work Item Id** | `SourceWorkItemId` | Int32 | The ID assigned to the source work item linked to. | |**Target Work Item Id** | `TargetWorkItemId` | Int32 | The ID assigned to the target work item linked to. | - Navigation properties for the **WorkItemLink** entity type include `Projects`, `SourceWorkItem`, and `TargetWorkItem`. -To learn more about links and link types, see the following articles: -- [Use links to view dependencies and track related work](../../boards/queries/link-work-items-support-traceability.md) -- [Link user stories, issues, bugs, and other work items in Azure Boards](../../boards/backlogs/add-link.md) +For more information about links and link types, see the following articles: +- [Use links to view dependencies and track related work](../../boards/backlogs/add-link.md) - [Reference guide for link types used in Azure DevOps](../../boards/queries/link-type-reference.md) - - + ## WorkItemTypeFields @@ -418,7 +406,6 @@ The following properties are valid for the **WorkItemTypeFields** entity set. Th |**Field Type** | `FieldType` | String | Data type assigned to a field. | |**Work Item Type** | `WorkItemType` | String | Name of work item types that a field is defined for. | - Navigation properties include `Project`. For an index of all fields defined for a project, see [Field descriptions for work item fields](../../boards/work-items/guidance/work-item-field.md). For additional information, see the following articles: diff --git a/docs/report/analytics/entity-reference-general.md b/docs/report/analytics/entity-reference-general.md index bf19c5f802b..a9598d965a5 100644 --- a/docs/report/analytics/entity-reference-general.md +++ b/docs/report/analytics/entity-reference-general.md @@ -6,33 +6,28 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 11/07/2022 --- - # Calendar date, Project, and User metadata reference for Azure DevOps Analytics [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] The entity types and entity sets listed in the following table can be used to filter and build reports based on Analytics data. - |EntitySet| EntityType | Description | |----------------------|-------------|-------------| | [**Dates**](#dates) |**CalendarDate** | The dates used to filter and group other entities using relationships. | |[**Projects**](#projects)| **Project** |Projects defined for an organization (cloud) or project collection (on-premises). | |[**Users**](#users)| **User** |User information that is used to expand or filter various work item properties, for example **Assigned To**, **Created By**. | - [!INCLUDE [note-analytics-early-draft](../includes/note-analytics-data-model.md)] - ## Dates The following properties are valid for the **CalendarDate** entity type. The surrogate key associated with **CalendarDate** is `DateSK`. You can specify calendar date properties to filter and structure reports. - |**Display name** | **Name** | **Data type** | **Description** | |-----------------|--------------------|---------------|--------------------------------------| | | `IsLastDayOfPeriod` | Enumerated | Use to filter data to determine if a day finishes in different periods such as days, weeks, months, or years. Valid values are listed below for [Period](#period-enumerated-type-members).| @@ -67,7 +62,6 @@ When you aggregate data for a snapshot entity, you should include the `DateSK` o The following members are defined for the `Period` enumerated type that you can use with other filter expressions to remove days that don't finish a given week or month. Reference one of these members to specify a weekly or monthly period for trend queries that span a long time period. The `Period` enumerated type has a single attribute, `IsFlags`, which is set to `True`. - | Member name | Value | Display name | |------------------------|--------------|-----------------------| |`None` | 0 | None | @@ -84,10 +78,9 @@ The following members are defined for the `Period` enumerated type that you can |`Year` | 1024 | Year | |`All` | 2047 | All | - ## Projects -The following properties are valid for the **Projects** entity set and its surrogate key `ProjectSK`. When generating an organization scoped query, you can focus on one or more projects by specifying one or more **Project Names**. To learn more, see [Project and organization-scoped queries](../extend-analytics/account-scoped-queries.md). +The following properties are valid for the **Projects** entity set and its surrogate key `ProjectSK`. When generating an organization scoped query, you can focus on one or more projects by specifying one or more **Project Names**. For more information, see [Project and organization-scoped queries](../extend-analytics/account-scoped-queries.md). |**Display name** | **Name** | **Data type** | **Description** | |-----------------|--------------------|---------------|--------------------------------------| @@ -114,7 +107,6 @@ The following members are defined for the `ProjectVisibility` enumerated type. |`Organization` | 1 | Organization | |`Public` | 2 | Public | - ## Users The following properties are valid for the **Users** entity set and **User** entity type with surrogate key `UserSK`. @@ -128,7 +120,6 @@ The following properties are valid for the **Users** entity set and **User** ent |**GitHub User Id** | `GitHubUserId` | String | GitHub user ID associated with the user account. | |**User Type** | `UserType` | Custom | The type of user. Valid values are listed below for [UserType](#usertype-enumerated-type-members). | - ### UserType enumerated type members The following members are defined for the `UserType` enumerated type. @@ -141,13 +132,10 @@ The following members are defined for the `UserType` enumerated type. |`Organization` | 3 | Organization | |`Bot` | 4 | Bot | - ## Related articles - [Data model for Analytics](../extend-analytics/data-model-analytics-service.md) - [Entities and properties reference for Azure Boards](entity-reference-boards.md) - [OData Analytics query guidelines](../extend-analytics/odata-query-guidelines.md) -- [Project and team quick reference](../../organizations/projects/project-team-quick-reference.md) - - +- [About projects](../../organizations/projects/about-projects.md) \ No newline at end of file diff --git a/docs/report/analytics/entity-reference-pipelines.md b/docs/report/analytics/entity-reference-pipelines.md index 06b8297a1b3..a65a2d1ffb7 100644 --- a/docs/report/analytics/entity-reference-pipelines.md +++ b/docs/report/analytics/entity-reference-pipelines.md @@ -27,7 +27,7 @@ The following table summarizes the entity types and entity sets that support Azu |EntitySet | EntityType | Description | |-----------|-------------|-------------| |[**Branches**](#branches)|**Branch** | Basic information about branches used in tests or pipelines. For a sample report, see [Progress status sample report](../powerbi/sample-test-plans-progress-status.md).| -|[**ParallelPipelineJobsSnapshot**](#parallelpipelinejobssnapshot)|**ParallelPipelineJobsSnapshot** | (Composite) Supports understanding of parallel pipeline consumption. To learn more about parallel pipeline tests, see [Run tests in parallel using the Visual Studio Test task](../../pipelines/test/parallel-testing-vstest.md). | +|[**ParallelPipelineJobsSnapshot**](#parallelpipelinejobssnapshot)|**ParallelPipelineJobsSnapshot** | (Composite) Supports understanding of parallel pipeline consumption. For more information about parallel pipeline tests, see [Run tests in parallel using the Visual Studio Test task](../../pipelines/test/parallel-testing-vstest.md). | |[**Pipelines**](#pipelines) | **Pipeline**| Properties for a pipeline. | |[**PipelineJobs**](#pipelinejobs)|**PipelineJob** |Individual execution results for a specific Test associated with a TestRun | |[**PipelineRuns**](#pipelineruns)|**PipelineRun** | Execution information for pipelines. For a sample report, see [Pipeline pass rate trend sample report](../powerbi/sample-pipelines-pass-rate-trend.md). | @@ -62,7 +62,7 @@ The following properties are valid for the **ParallelPipelineJobsSnapshot** enti |**Display name** | **Name** | **Data type** | **Description** | |-----------------|--------------------|---------------|--------------------------------------| -|**Hosted Or Self-hosted** | `IsHosted` | Boolean | Indicates if the parallel pipeline is run on a Microsoft-hosted agent (True) or is self-hosted (False). To learn more, see [Azure Pipelines agents](../../pipelines/agents/agents.md). | +|**Hosted Or Self-hosted** | `IsHosted` | Boolean | Indicates if the parallel pipeline is run on a Microsoft-hosted agent (True) or is self-hosted (False). For more information, see [Azure Pipelines agents](../../pipelines/agents/agents.md). | |**Failed To Reach All Providers** | `FailedToReachAllProviders` | Boolean | Indicates if the job run reached all providers (True) or not (False). | |**Number Of Parallel Pipelines Jobs** | `TotalCount` | Int32 | The number of jobs run as part of the snapshot. | |**Number Of Parallel Pipelines Minutes** | `TotalMinutes` | Int32 | The number of minutes taken to run the snapshot. | @@ -99,7 +99,7 @@ The following members are defined for the `PipelineProcessType` enumerated type ## PipelineJobs -A pipeline job is a series of steps that run sequentially as a unit. A job is the smallest unit of work that you can schedule to run. Pipelines are organized around jobs, and each pipeline has at least one job. To learn more, see [Specify jobs in your pipeline](../../pipelines/process/phases.md). +A pipeline job is a series of steps that run sequentially as a unit. A job is the smallest unit of work that you can schedule to run. Pipelines are organized around jobs, and each pipeline has at least one job. For more information, see [Specify jobs in your pipeline](../../pipelines/process/phases.md). The following properties are valid for **PipelineJobs** and its `PipelineJobSK` surrogate key. @@ -119,7 +119,7 @@ For a sample report that queries the **PipelineJob** entity type, see [Pipeline ## PipelineRuns -A pipeline run represents a single execution of a pipeline. During a run, the pipeline is processed, and agents process one or more jobs. A pipeline run includes jobs, steps, and tasks. To learn more, see [Pipeline run sequence](../../pipelines/process/runs.md). +A pipeline run represents a single execution of a pipeline. During a run, the pipeline is processed, and agents process one or more jobs. A pipeline run includes jobs, steps, and tasks. For more information, see [Pipeline run sequence](../../pipelines/process/runs.md). The following properties are valid for the **PipelineRun** entity type and its `PipelineRunSK` surrogate key. diff --git a/docs/report/analytics/entity-reference-test-plans.md b/docs/report/analytics/entity-reference-test-plans.md index 300a42eb7f8..f9903eb7f3b 100644 --- a/docs/report/analytics/entity-reference-test-plans.md +++ b/docs/report/analytics/entity-reference-test-plans.md @@ -17,17 +17,16 @@ ms.date: 11/07/2022 The Analytics service collects all data for all Azure DevOps test activities. Azure Test Plans supports the definition and execution of planned and exploratory tests. And with Azure Pipelines, you can also execute automated tests with Continuous Integration/Continuous Deployment (CI/CD) workflows. -If you're new to Azure DevOps testing, we recommend you review the following articles: +If you're new to Azure DevOps testing, we recommend viewing the following articles: - [What is Azure Test Plans?](../../test/overview.md) - [Test objects and terms](../../test/test-objects-overview.md) - [About pipeline tests](../../pipelines/test/test-glossary.md) - [Visual Studio Test](../../pipelines/tasks/test/vstest.md) - The metadata information provided in this article describes the entities, properties, and enumerated types supported for all Azure DevOps test activities. - [!INCLUDE [note-analytics-early-draft](../includes/note-analytics-data-model.md)] + ## Entity sets and entity types To query Analytics for Test Plan data, use one or more of the entity types and entity sets described in the following table. @@ -47,7 +46,6 @@ To query Analytics for Test Plan data, use one or more of the entity types and e |[**TestRuns**](#testruns) | **TestRun** | Execution information with aggregated test results for tests that are run under a pipeline. | |[**TestSuites**](#testsuites) | **TestSuite**| Test suites information. For details on defining test suites, see [Create test plans and test suites](../../test/create-a-test-plan.md). | - ## Tests The following properties are valid for the **Test** entity type and **Tests** entity set. Surrogate key is `TestSK`. @@ -58,7 +56,7 @@ Navigational properties include [`Project`](entity-reference-general.md#projects |-----------------|--------------------|---------------|--------------------------------------| | |`AnalyticsUpdatedDate` | DateTime | Watermark that indicates the last time the Analytics data was updated. | |**Container Name** | `ContainerName` | String | Name of the job container containing the test task within a pipeline. | -|**Fully Qualified Test Name** | `FullyQualifiedTestName` | String | The name created for the test. The fully qualified name format corresponds to `Namespace.Testclass.Methodname` with a character limit of 512. If the test is data driven and has parameters, the character limit will include the parameters. | +|**Fully Qualified Test Name** | `FullyQualifiedTestName` | String | The name created for the test. The fully qualified name format corresponds to `Namespace.Testclass.Methodname` with a character limit of 512. If the test is data driven and has parameters, the character limit includes the parameters. | |**Priority** | `Priority` | Int32 | Specifies the degree of importance or criticality of a test. Priority is typically specified as an attribute in the test code. | |**Test Case Reference Id** | `TestCaseReferenceId` | Int32 | The number (not the ID) assigned to a test case. | |**Test Name** | `TestName` | String | The name of the test. | @@ -66,7 +64,7 @@ Navigational properties include [`Project`](entity-reference-general.md#projects ## TestConfigurations -Test configurations specify different environments in which you'll run tests as described in [Test different configurations](../../test/test-different-configurations.md). +Test configurations specify different environments in which you run tests as described in [Test different configurations](../../test/test-different-configurations.md). The following properties are valid for the **TestConfiguration** entity type and **TestConfigurations** entity set and their surrogate key `TestConfigurationSK`. @@ -76,9 +74,7 @@ The following properties are valid for the **TestConfiguration** entity type and |**Test Configuration Name** | `Name` | String | Name assigned to the test configuration. | |**Test Configuration State** | `State` | String | The state of the test configuration, either Active or Inactive. | - Navigational properties include [`Project`](entity-reference-general.md#projects) and its referential constraint `ProjectSK`. - ## TestPoints @@ -90,12 +86,12 @@ Navigational properties include [`Project`](entity-reference-general.md#projects | |`TesterUserSK` | GUID | The GUID assigned to the tester associated with the test point. | |**Automation Status** | `AutomationStatus` | Enumerated | The status of a test case, such as Automated, Not Automated, or Planned. Corresponds to the [Microsoft.VSTS.TCM.AutomationStatus](../../boards/queries/build-test-integration.md) work item field. | |**Changed Date** | `ChangedDate` | DateTime | The date-time when the test point last changed. | -|**Last Result State** | `LastResultState` | Enumerated | The state of the test point, such as pending, queued, or in progress. Valid values are listed below for [TestResultState](#testresultstate-enumerated-type-members). | +|**Last Result State** | `LastResultState` | Enumerated | The state of the test point, such as pending, queued, or in progress. Valid values are listed as follows for [TestResultState](#testresultstate-enumerated-type-members). | |**Priority** | `Priority` | Int32 | The priority assigned to the associated test case. | |**Test Case Id** | `TestCaseId` | Int32 | The work item ID assigned to the associated test case. | |**Test Configuration Id** | `TestConfigurationId` | Int32 | The number assigned to the associated test configuration. | |**Test Plan Id** | `TestPlanId` | Int32 | The work item ID assigned to the associated test plan. | -|**Test Result Outcome** | `LastResultOutcome` | Enumerated | Specifies the last test result outcome. Valid values are listed below for [TestOutcome](#testoutcome-enumerated-type-members). | +|**Test Result Outcome** | `LastResultOutcome` | Enumerated | Specifies the last test result outcome. Valid values are listed as follows for [TestOutcome](#testoutcome-enumerated-type-members). | |**Test Suite Id** | `TestSuiteId` | Int32 | The work item ID assigned to the associated test suite. | To review test points via the user interface, see [Run manual tests, Save results, close the session, and review results](../../test/run-manual-tests.md#save-results-close-the-session-and-review-results). @@ -114,7 +110,6 @@ The following table lists those navigation properties for the **TestPoint** enti |Test Suite | `TestSuite` | `TestSuiteSK` | `TestSuiteSK` | |Tester User Name | `Tester` | `TesterUserSK` | `UserSK` | - ### TestResultState enumerated type members A test result can be in one of the six states summarized in the following table for the `TestResultState` enumerated type. @@ -150,17 +145,15 @@ The 15 outcomes for a test are listed in the following table and are the members |`InProgress` | 13 | In Progress | | |`NotImpacted` | 14 | Not Impacted | Test not impacted by the code change that triggered the pipeline. | - ## TestPointHistorySnapshot - The following properties are valid for the **TestPointHistorySnapshot** entity set. Surrogate keys include `TestPointSK` and `DateSK`. |**Display name** | **Name** | **Data type** | **Description** | |-----------------|--------------------|---------------|--------------------------------------| | |`AnalyticsUpdatedDate` | DateTime | Watermark that indicates the last time the Analytics data was updated. | | |`AssignedToUserSK` | GUID | The GUID assigned to the test work item. | -| |`IsLastDayOfPeriod` | Enumerated | Use to filter data to determine if a day finishes in different periods such as days, weeks, months, or years. Valid values are listed here: [Period enumerated type members](entity-reference-general.md#period-enumerated-type-members).| +| |`IsLastDayOfPeriod` | Enumerated | Use to filter data to determine if a day finishes in different periods such as days, weeks, months, or years. Valid values are listed here: [Period enumerated type members](entity-reference-general.md#period-enumerated-type-members).| | |`TesterUserSK` | GUID | The GUID assigned to the tester associated with the test point. | | |`TestConfigurationSK` | Int32 | The key assigned to the associated test configuration. | |**Automation Status** | `AutomationStatus` | Enumerated | The status of a test case, such as Automated, Not Automated, or Planned. Corresponds to the [Microsoft.VSTS.TCM.AutomationStatus](../../boards/queries/build-test-integration.md) work item field. | @@ -170,8 +163,7 @@ The following properties are valid for the **TestPointHistorySnapshot** entity s |**Test Plan Id** | `TestPlanId` | Int32 | The work item ID assigned to the associated test plan. | |**Test Result Outcome** | `ResultOutcome` | Enumerated | Specifies the last test result outcome. Valid values are listed in [TestOutcome](#testoutcome-enumerated-type-members). | |**Test Suite Id** | `TestSuiteId` | Int32 | The work item ID assigned to the associated test suite. | - - + ### Navigation properties The following table lists those navigation properties for the **TestPointHistorySnapshot** entity type and **TestPointHistorySnapshot** entity set. @@ -186,14 +178,11 @@ The following table lists those navigation properties for the **TestPointHistory |Test Suite | `TestSuite` | `TestSuiteSK` | `TestSuiteSK` | |Tester User Name | `Tester` | `TesterUserSK` | `UserSK` | - - ## TestResults A test result corresponds to a single instance of execution of a test case with a specific outcome and details. - -Test runs occur when you manually run a test or include test tasks within a pipeline definition as described in [Build, test, and deploy .NET Core apps, Run your tests](../../pipelines/ecosystems/dotnet-core.md#run-your-tests). +Test runs occur when you manually run a test or include test tasks within a pipeline definition. For more information, see [Build, test, and deploy .NET Core apps, Run your tests](../../pipelines/ecosystems/dotnet-core.md#run-your-tests). The following properties are valid for the **TestResults** entity set. Surrogate key is `TestResultSK`. @@ -210,10 +199,10 @@ The following properties are valid for the **TestResults** entity set. Surrogate |**Started Date** | `StartedDate` | DateTime |The date-time when the test result started execution. | |**Test Result Id** | `TestResultId` | Int32 | The number assigned to a test result. | |**Test Run Id** | `TestRunId` | Int32 | The number assigned to a test run. | -|**Test Run Type** | `TestRunType` | Enumerated | Indicates if it's a manual or automated test type. Valid values are listed below for [TestRunType](#testruntype-enumerated-type-members). | -|**Test Outcome** | `Outcome` | Enumerated | The test run outcome. There are 15 possible outcomes for a test result: Aborted, Blocked, Error, Failed, Inconclusive, In progress, None, Not applicable, Not executed, Not impacted, Passed, Paused, Timeout, Unspecified, and Warning. Valid values are listed below for [TestOutcome](#testoutcome-enumerated-type-members). | -|**Workflow** | `Workflow` | Enumerated | The pipeline workflow type. Valid values are listed below for [SourceWorkflow](#sourceworkflow-enumerated-type-members). | - +|**Test Run Type** | `TestRunType` | Enumerated | Indicates if it's a manual or automated test type. Valid values are listed as follows for [TestRunType](#testruntype-enumerated-type-members). | +|**Test Outcome** | `Outcome` | Enumerated | The test run outcome. There are 15 possible outcomes for a test result: Aborted, Blocked, Error, Failed, Inconclusive, In progress, None, Not applicable, Not executed, Not impacted, Passed, Paused, Timeout, Unspecified, and Warning. Valid values are listed as follows for [TestOutcome](#testoutcome-enumerated-type-members). | +|**Workflow** | `Workflow` | Enumerated | The pipeline workflow type. Valid values are listed as follows for [SourceWorkflow](#sourceworkflow-enumerated-type-members). | + ### Navigation properties The following table lists the navigation properties valid for a **TestResult** entity type. @@ -229,19 +218,16 @@ The following table lists the navigation properties valid for a **TestResult** e |`Test` | `TestSK` | `TestSK` | | `TestRun` | `TestRunSK` |`TestRunSK` | - ### SourceWorkflow enumerated type members The following table lists the members defined for the `SourceWorkflow` enumerated type. - | Display name | Member name | Value | |--------------|--------------|--------------| |Build |`Build` | 1 | |Release |`Release` | 2 | |Manual |`Manual` | 3 | - ### TestRunType enumerated type members The following table lists the members defined for the `SourceWorkflow` enumerated type. @@ -251,11 +237,8 @@ The following table lists the members defined for the `SourceWorkflow` enumerate |`Automated` | 1 | Automated | |`Manual` | 2 | Manual | - - ## TestResultsDaily - The following properties are valid for the **TestResultsDaily** entity set. Surrogate key is`TestResultsDailySK`. |**Display name** | **Name** | **Data type** | **Description** | @@ -269,7 +252,7 @@ The following properties are valid for the **TestResultsDaily** entity set. Surr |**Result Duration Seconds** | `ResultDurationSeconds` | Decimal | The number of seconds that the test result required to execute. | |**Result Error Count** | `ResultErrorCount` | Int32 | The number of test outcomes reported as *Error* for the test result daily. | |**Result Fail Count** | `ResultFailCount` | Int32 | The number of test outcomes reported as *Failed* for the test result daily. | -|**Result Flaky Count** | `ResultFlakyCount` | Int32 | The number of flaky results. A flaky Test is a test that intermittently fails for no apparent reason, such as a change to the code or test. For more information, see [Manage flaky tests](../../pipelines/test/flaky-test-management.md). | +|**Result Flaky Count** | `ResultFlakyCount` | Int32 | The number of flaky results. A flaky Test is a test that intermittently fails for no apparent reason, such as a change to the code or test. For more information, see [Manage flaky tests](../../pipelines/test/flaky-test-management.md). | |**Result Inconclusive Count** | `ResultInconclusiveCount` | Int32 | The number of test outcomes reported as *Inconclusive* for the test result daily. | |**Result Pass Count** | `ResultPassCount` | Int32 | The number of test outcomes reported as *Passed* for the test result daily. | |**Result None Count** | `ResultNoneCount` | Int32 | The number of test outcomes reported as *None* for the test result daily. | @@ -283,7 +266,6 @@ The following properties are valid for the **TestResultsDaily** entity set. Surr |**Test Run Type** | `TestRunType` | Enumerated | Indicates if it's a manual or automated test type. Valid values are listed under [TestRunType](#testruntype-enumerated-type-members). | |**Workflow** | `Workflow` | Enumerated | The pipeline workflow type. Valid values are listed under [SourceWorkflow](#sourceworkflow-enumerated-type-members). | - ### Navigation properties The following table lists the navigation properties that are valid for a **TestResultDaily** entity type. @@ -298,7 +280,7 @@ The following table lists the navigation properties that are valid for a **TestR ## TestRuns -Test runs occur when you manually run a test or include test tasks within a pipeline definition. To learn more, see [Build, test, and deploy .NET Core apps, Run your tests](../../pipelines/ecosystems/dotnet-core.md#run-your-tests). +Test runs occur when you manually run a test or include test tasks within a pipeline definition. For more information, see [Build, test, and deploy .NET Core apps, Run your tests](../../pipelines/ecosystems/dotnet-core.md#run-your-tests). The following properties are valid for **TestRuns** and its surrogate key `TestRunSK`. @@ -319,7 +301,7 @@ The following properties are valid for **TestRuns** and its surrogate key `TestR |**Result Duration Seconds** | `ResultDurationSeconds` | Decimal | The number of seconds that the test run required to execute. | |**Result Error Count** | `ResultErrorCount` | Int32 | The number of test outcomes reported as *Error* for the test run or test result daily. | |**Result Fail Count** | `ResultFailCount` | Int32 | The number of test outcomes reported as *Failed* for the test run or test result daily. | -|**Result Flaky Count** | `ResultFlakyCount` | Int32 | The number of test outcomes marked as flaky. A flaky test is a test that intermittently fails for no apparent reason, such as a change to the code or test. For more information, see [Manage flaky tests](../../pipelines/test/flaky-test-management.md). | +|**Result Flaky Count** | `ResultFlakyCount` | Int32 | The number of test outcomes marked as flaky. A flaky test is a test that intermittently fails for no apparent reason, such as a change to the code or test. For more information, see [Manage flaky tests](../../pipelines/test/flaky-test-management.md). | |**Result Inconclusive Count** | `ResultInconclusiveCount` | String | The number of test outcomes reported as *Inconclusive* for the test run or test result daily. | |**Result Pass Count** | `ResultPassCount` | Int32 | The number of test outcomes reported as *Passed* for the test run or test result daily. | |**Result Timeout Count** | `ResultTimeoutCount` | Int32 | The number of test outcomes reported as *Timeout* for the test run or test result daily. | @@ -334,7 +316,6 @@ The following properties are valid for **TestRuns** and its surrogate key `TestR |**Title** | `Title` | String | The GUID assigned to a pipeline task. | |**Workflow** | `Workflow` | Enumerated | The pipeline workflow type. Valid values are listed under [SourceWorkflow](#sourceworkflow-enumerated-type-members). | - ### Navigation properties The following table lists the navigation properties that are valid for a **TestRun** entity type. @@ -347,10 +328,10 @@ The following table lists the navigation properties that are valid for a **TestR | `PipelineRun` | `PipelineRunSK` | `PipelineRunSK` | |`Project` | `ProjectSK` | `ProjectSK` | | `StartedOn` | `StartedDateSK` | `DateSK` | - + ## TestSuites -Test suites are defined for test plans and specify the tests to run. To learn more, see [Create test plans and test suites](../../test/create-a-test-plan.md). +Test suites are defined for test plans and specify the tests to run. For more information, see [Create test plans and test suites](../../test/create-a-test-plan.md). The following properties are valid for **TestSuites** and its surrogate key `TestSuiteSK`. @@ -359,7 +340,7 @@ The following properties are valid for **TestSuites** and its surrogate key `Te | |`AnalyticsUpdatedDate` | DateTime | Watermark that indicates the last time the Analytics data was updated. | |**Test Plan Id** | `TestPlanId` | Int32 | The number (not the ID) assigned to a test case. | |**Test Suite Id** | `TestSuiteId` | Int32 | Name assigned to the test configuration. | -|**Test Plan Title** | `TestPlanTitle` | String | The state of the test configuration, either Active or Inactive. | +|**Test Plan Title** | `TestPlanTitle` | String | The title of the test plan. | |**Test Suite Title** | `Title` | Int32 | The number (not the ID) assigned to a test case. | |**OrderId** | `OrderId` | Int32 | Name assigned to the test configuration. | |**Test Suite Level 1 Id** through **Test Suite Level 14 Id** | `IdLevel1` through`IdLevel14` | Int32 | The level of a nested test suite. | diff --git a/docs/report/dashboards/add-charts-to-dashboard.md b/docs/report/dashboards/add-charts-to-dashboard.md index c1272b46b72..83163163a98 100644 --- a/docs/report/dashboards/add-charts-to-dashboard.md +++ b/docs/report/dashboards/add-charts-to-dashboard.md @@ -1,243 +1,153 @@ --- title: Add built-in charts to a team dashboard titleSuffix: Azure DevOps -description: Learn how to add system-generated charts or query-based charts to a team dashboard in Azure DevOps. +description: Learn how to add system-generated charts or query-based charts to a team dashboard. ms.custom: dashboards, engagement-fy23 ms.subservice: azure-devops-analytics ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 02/02/2022 +ms.date: 10/28/2024 --- # Add charts to a dashboard [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - - ::: moniker range=">= azure-devops-2020" -This article describes how to add query-based charts and in-context reports to a dashboard from their functional page. For example, you can add the Team Velocity in-context Analytics report to a dashboard. Once you've added the report, go ahead and modify the corresponding widget configuration parameters. -::: moniker-end - -::: moniker range="< azure-devops-2020" -You can add the charts described in this article to a dashboard from their corresponding functional page, like: -- Builds -- Releases -- Queries +This article explains how to add query-based charts and in-context reports to a dashboard from their respective functional pages. For example, you can add the Team Velocity in-context Analytics report to a dashboard. After adding the report, you can modify the corresponding widget configuration parameters to suit your needs. ::: moniker-end - - - ## Prerequisites ::: moniker range="azure-devops" -- You must be a member of a project. If you don't have a project yet, [create one](../../organizations/accounts/set-up-vs.md). -- You must have [created the team dashboard](dashboards.md) to which you want to add a chart. -- If you haven't been added as a project member, [get added now](../../organizations/accounts/add-organization-users.md). -- Anyone with access to a project, including [stakeholders](../../organizations/security/get-started-stakeholder.md), can view dashboards. -- To add, edit, or manage a team dashboard, you must have **Basic** access or greater and be a [team admin](../../organizations/settings/add-team-administrator.md), a project admin, or have [dashboard permissions](./dashboard-permissions.md). In general, you need to be a member of the team to edit a team dashboard. +|Category | Requirements | +|-------------|-------------| +| **Dashboard creation** |[Creator of the team dashboard](dashboards.md) to which you want to add a chart. | +|**Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Basic** access. | +| **Permissions** | [Team administrator](../../organizations/settings/add-team-administrator.md), project administrator, or specific [dashboard permissions](./dashboard-permissions.md) granted to you. For more information about other prerequisites regarding service and feature enablement and general data tracking activities, see [Permissions and prerequisites to access Analytics](../analytics/analytics-permissions-prerequisites.md). | +|**Services**| **Azure Boards** enabled. If it's disabled, **Analytics views** doesn't display. [Reenable it](../../organizations/settings/set-services.md) either for individual users or for the entire organization.| ::: moniker-end ::: moniker range="< azure-devops" -- You must be a member of a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -- You must have [created the team dashboard](dashboards.md) to which you want to add a chart. -- If you haven't been added as a project member, [get added now](../../organizations/security/add-users-team-project.md). -- To add, edit, or manage a team dashboard, you must have **Basic** access or greater and be a team admin, a project admin, or have [dashboard permissions](./dashboard-permissions.md). In general, you need to be a member of the team to edit a team dashboard. - Request your current team or project admin to add you as a [team admin](../../organizations/settings/add-team-administrator.md). -::: moniker-end +|Category | Requirements | +|-------------|-------------| +| **Dashboard creation** |[Creator of the team dashboard](dashboards.md) to which you want to add a chart. | +|**Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Basic** access. | +| **Permissions** | [Team administrator](../../organizations/settings/add-team-administrator.md), project administrator, or specific [dashboard permissions](./dashboard-permissions.md) granted to you. For more information about other prerequisites regarding service and feature enablement and general data tracking activities, see [Permissions and prerequisites to access Analytics](../analytics/analytics-permissions-prerequisites.md). | +|**Services**| **Azure Boards** enabled. If it's disabled, **Analytics views** doesn't display. [Reenable it](../../organizations/settings/set-services.md) either for individual users or for the entire organization.| -To learn more, see [Default permissions and access for charts and dashboards](charts-dashboard-permissions-access.md). +::: moniker-end ## Add a work item query or chart -You add work item queries and charts to a dashboard from the Queries page. Queries and charts must be associated with queries under the Shared queries folder. +You can add work item queries and charts to a dashboard from the Queries page. -> [!NOTE] +> [!TIP] > You can also add a [work item query chart widget](widget-catalog.md#build-history-widget) to a team dashboard. -1. First, make sure you've selected your team context. Only those dashboards created for a team appear in the context menu for each query or chart. [Switch team context](../../project/navigation/go-to-project-repo.md?toc=/azure/devops/report/toc.json&bc=/azure/devops/report/breadcrumb/toc.json) as needed. +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and go to your project. +2. Select **Boards** > **Queries** > **Charts**. Queries and charts must be associated with queries under the `Shared queries` folder. -2. If you aren't a team administrator, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can add and customize team dashboards. + :::image type="content" source="media/add-charts/boards-queries-charts-sequence.png" alt-text="Screenshot showing sequence, Boards, Queries, and Charts."::: -3. If you haven't yet created the dashboard, [do that now](dashboards.md). +3. From the charts :::image type="icon" source="media/icons/actions-icon.png" border="false"::: Actions menu, select **Add to dashboard**. -4. From the charts Actions menu, select the team dashboard. - - ![Screenshot of Query Chart context menu, add to a dashboard.](media/pin-chart-to-a-dashboard.png) - - You can only add charts associated with shared queries. Charts associated with queries under My Queries folder won't display the **Add to dashboard** option. + :::image type="content" source="media/add-charts/pin-chart-to-a-dashboard.png" alt-text="Screenshot of Query Chart context menu, add to a dashboard."::: +4. Select a **dashboard** from the dropdown menu, and then select **OK**. + + :::image type="content" source="media/add-charts/select-dashboard.png" alt-text="Screenshot of pin to dashboard sequence, select dashboard, and then OK."::: + + You can only add charts associated with shared queries. Charts associated with queries under My Queries folder don't display the **Add to dashboard** option. ## Add an in-context work tracking report - ::: moniker range=">= azure-devops-2020" You can add each of the in-context **Analytics** reports to a dashboard. 1. Open the report, select the :::image type="icon" source="media/icons/actions-icon.png" border="false"::: actions icon, and select **Copy to Dashboard**. - > [!div class="mx-imgBorder"] - > ![Screenshot of Analytics in-context report, Copy to dashboard.](media/add-charts/add-analytics-chart.png) - - To open a report, see [Cumulate Flow Diagram](cumulative-flow.md#view-the-cfd-in-context-report), [Velocity](team-velocity.md#view-the-velocity-in-context-report), or [Sprint burndown](configure-sprint-burndown.md#view-context-report). + :::image type="content" source="media/add-charts/add-analytics-chart.png" alt-text="Screenshot of Analytics in-context report, Copy to dashboard."::: -1. Select the dashboard and select **OK**. +2. Select a **dashboard** from the dropdown menu, and then select **OK**. - > [!div class="mx-imgBorder"] - > ![Select the dashboard dialog.](media/add-charts/select-a-dashboard-dialogue.png) + :::image type="content" source="media/add-charts/select-in-context-work-tracking-dashboard.png" alt-text="Screenshot of select the dashboard dialog."::: -1. (Optional) Open the dashboard and select :::image type="icon" source="media/icons/actions-icon.png" border="false"::: **More actions** for the widget to configure the size or change other chart properties. +3. (Optional) Open the dashboard and select :::image type="icon" source="media/icons/actions-icon.png" border="false"::: **More actions** for the widget to configure the size or change other chart properties. ::: moniker-end -::: moniker range="< azure-devops-2020" - -There are many in-context reports that you can access from the web portal, but can't add to a dashboard. However, you may find a comparable widget listed in the [widget catalog](widget-catalog.md) that tracks the same or similar data. If you find a widget that works, add it to the dashboard: - -- [Add Markdown to a dashboard](add-markdown-to-dashboard.md) -- [Team velocity](./team-velocity.md) -- [View/configure sprint burndown](configure-sprint-burndown.md), see [Sprint burndown widget](widget-catalog.md#sprint-burndown-widget) -- [Cumulative flow](./cumulative-flow.md), see [CFD widget](widget-catalog.md) - -::: moniker-end - - - - ## Add a build history chart Each time you run a build, it logs information about the build, including: -- The run time. -- Errors and warnings. -- Whether it successfully completed or failed. +- Run time +- Errors and warnings +- Status: Completed or Failed -> [!NOTE] +> [!TIP] > You can also add this chart to a team dashboard from the [widget catalog](widget-catalog.md#build-history-widget). -1. Select your [team context](../../project/navigation/go-to-project-repo.md) and then open **Pipelines>Builds** to add a build history chart to a team dashboard. - - ![Screenshot of Add a build summary chart to a dashboard.](media/add-chart-build-summary.png) - - If you aren't a team administrator, [get added as one](../../organizations/settings/add-team-administrator.md). The **Add to dashboard** menu selection is disabled when you don't have permissions to add it to the dashboards of the selected team context. - -2. Build summary charts look like this: +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and go to your project. +2. Select **Pipelines** > **Pipelines** to add a build history chart to a team dashboard. The **Add to dashboard** menu selection is disabled when you don't have permissions to add it to the dashboards of the selected team context. - ![Screenshot of Build summary chart.](media/add-a-dashboard-build-summary.png) + The Build summary charts look similar to the following image. - Hover over a bar to view build information and run time. Select a bar to go to the build summary page. + :::image type="content" source="media/add-a-dashboard-build-summary.png" alt-text="Screenshot of Build summary chart."::: - +3. Hover over a bar to view build information and run time and select a bar to go to the build summary page. ## Add a release summary chart -Each time a release is deployed, it logs information about the release to each of its environments. You can add a release tile to your team dashboard to monitor release progress and gain quick access to each release. +Each time a release gets deployed, it logs information about the release to each of its environments. You can add a release tile to your team dashboard to monitor release progress and gain quick access to each release. - -::: moniker range=">= azure-devops-2019" - -> [!NOTE] +> [!TIP] > You can also add this chart to a team dashboard from the [widget catalog](widget-catalog.md#release-definition-widget). -1. Open **Pipelines>Releases** to add a release definition chart to a team dashboard. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Add a Release pipeline chart to a dashboard.](media/add-charts/add-release-pipeline-to-dashboard-new-nav.png) - -2. Release pipeline charts show the success (green), in progress (blue), cancellation (red), or non-deployment (grey) to an environment for the current and last four releases: - - ![Screenshot of Release pipeline tile.](media/add-cd-release-definition-tile.png) - -::: moniker-end - - -::: moniker range="tfs-2018" - -> [!NOTE] -> You can also add this chart to a team dashboard from the [widget catalog](widget-catalog.md). - -1. Open **Pipelines>Releases** to add a release definition chart to a team dashboard. - - ![Screenshot of Add a Release pipeline chart to a dashboard, TFS 2018.](media/add-cd-release-definition.png) - -2. Release pipeline charts show the success (green), in progress (blue), cancellation (red), or non-deployment (grey) to an environment for the current and last four releases: +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and go to your project. +2. Select **Pipelines** > **Releases** to add a release definition chart to a team dashboard. - ![Screenshot of Release pipeline tile, TFS 2018.](media/add-cd-release-definition-tile.png) + :::image type="content" source="media/add-charts/add-release-pipeline-to-dashboard-new-nav.png" alt-text="Screenshot of Add a Release pipeline chart to a dashboard."::: -::: moniker-end - -::: moniker range="tfs-2018" - - -## Add a manual test status or result chart - -As you create and run tests, you can track your status by defining [lightweight charts of test plans and test results](../../test/track-test-status.md). +3. Release pipeline charts show the success (green), in progress (blue), cancellation (red), or nondeployment (grey) to an environment for the current and last four releases: -> [!NOTE] -> You can also add a [Chart for test plans widget](widget-catalog.md) to a dashboard. - -1. Select your [team context](../../project/navigation/go-to-project-repo.md?toc=/azure/devops/report/toc.json&bc=/azure/devops/report/breadcrumb/toc.json), make sure you're a [team admin](../../organizations/settings/add-team-administrator.md). - -1. Open **Test>Test Plans** and then **Charts** and select the dashboard to add the test chart to. - - ![Screenshot of Select the dashboard to add the test chart to.](media/add-a-chart-test-plan.png) -::: moniker-end - - - + :::image type="content" source="media/add-cd-release-definition-tile.png" alt-text="Screenshot of Release pipeline tile."::: ## Add a test quality trend chart You can add trends to the dashboard of the failures and duration of those [tests that were run as part of a build](../../pipelines/ecosystems/dotnet-core.md#run-your-tests). -> [!NOTE] +> [!TIP] > You can also add a [test result trend chart widget](widget-catalog.md#test-results-widget) to a dashboard. -1. Select your [team context](../../project/navigation/go-to-project-repo.md?toc=/azure/devops/report/toc.json&bc=/azure/devops/report/breadcrumb/toc.json), make sure you're a [team admin](../../organizations/settings/add-team-administrator.md). - -2. Open a build summary for a build pipeline to which you've added tests. +1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and go to your project. -1. Open the **Tests** page +2. Open a build summary for a build pipeline to which you added tests. -1. Select the bar chart for either Test failures or Test duration. +3. Open the **Tests** page. - ![Screenshot of Add a test plan chart to a dashboard.](media/add-chart-test-quality.png) +4. Select the bar chart for either Test failures or Test duration. -3. Open the :::image type="icon" source="media/icons/actions-icon.png" border="false"::: **Actions** menu and select the dashboard to add the chart to. + :::image type="content" source="media/add-chart-test-quality.png" alt-text="Screenshot of Add a test plan chart to a dashboard."::: - ![Screenshot of Open Actions menu and select dashboard.](media/add-chart-test-failures.png) +5. Open the :::image type="icon" source="media/icons/actions-icon.png" border="false"::: **Actions** menu, select **Add to dashboard**, select the **dashboard** to add the chart to from the dropdown menu, and then **OK**. - Learn more about [reviewing automated test results after a build](../../pipelines/test/review-continuous-test-results-after-build.md). - - +For more information, see [Review automated test results after a build](../../pipelines/test/review-continuous-test-results-after-build.md). ## Add a markdown repository file to a dashboard -Open the Markdown file defined in your repository and make sure you are in your team context. - -Select **Add to dashboard**, and then select the team dashboard to add the Markdown file to. As you update the Markdown file, changes will automatically appear on the dashboard upon refresh. See [Dashboards](dashboards.md) for more info. - -Screenshot of Web portal, Code, README file, Add Markdown page to a dashboard. +To add a markdown file to a dashboard, you must complete the steps in [Add Markdown to a dashboard, Add the Markdown widget](add-markdown-to-dashboard.md#add-the-markdown-widget). + +As you update the Markdown file, changes automatically appear on the dashboard upon refresh. - - ## Related articles -::: moniker range=">= azure-devops-2019" - -- [Burndown guidance](burndown-guidance.md) -- [Cumulative flow & lead/cycle time guidance](cumulative-flow-cycle-lead-time-guidance.md) -- [Analyze test results](../../pipelines/test/test-analytics.md) -::: moniker-end - -::: moniker range="tfs-2018" -- [Burndown guidance](burndown-guidance.md) -- [Cumulative flow & lead/cycle time guidance](cumulative-flow-cycle-lead-time-guidance.md) -::: moniker-end +- [Learn how to use burndown charts](burndown-guidance.md) +- [Understand cumulative flow and lead/cycle time](cumulative-flow-cycle-lead-time-guidance.md) +- [Analyze your test results](../../pipelines/test/test-analytics.md) diff --git a/docs/report/dashboards/add-markdown-to-dashboard.md b/docs/report/dashboards/add-markdown-to-dashboard.md index 9ad3b136625..eb31a48d38b 100644 --- a/docs/report/dashboards/add-markdown-to-dashboard.md +++ b/docs/report/dashboards/add-markdown-to-dashboard.md @@ -8,26 +8,28 @@ ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 02/02/2022 +ms.date: 01/03/2025 --- # Add Markdown to a dashboard [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Use the Markdown widget to support your team and stakeholders by adding information such as: -- Team goals. -- Links to: - - Team backlogs or boards. - - Metrics. - - Other items located in a network share such as a OneNote, SharePoint site, or wiki pages. -- Important dates or target deadlines. +The Markdown widget is a versatile tool that allows you to support your team and stakeholders by adding valuable information directly to your dashboard. You can use it to display the following items: + +- Team goals +- Links to team backlogs or boards +- Links to metrics +- Links to other items located in a network share, such as a OneNote, SharePoint site, or wiki pages +- Important dates or target deadlines + +By using the Markdown widget, you can ensure that essential information is easily accessible and visible to your team and stakeholders. +The following example shows team information and links: +:::image type="content" source="../../project/wiki/media/markdown-guidance/markdown-widget-configured.png" alt-text="Screenshot of sample Markdown widget."::: -Here's an example: -Screenshot of a Sample Markdown widget. +## Prerequisites [!INCLUDE [temp](../includes/dashboard-prerequisites.md)] @@ -43,144 +45,51 @@ The Markdown widget supports CommonMark standard features, such as: - Lists, both ordered and unordered - Links - Images -- Escaping characters +- Character escaping -For details on usage, see [Syntax guidance for basic Markdown usage](../../project/wiki/markdown-guidance.md). +For more information, see [Syntax guidance for basic Markdown usage](../../project/wiki/markdown-guidance.md). For performance reasons, the Markdown widget doesn't add support for many extended features, many of which are supported in the wiki. Extended capabilities would impede widget load time. For example, the following extended Markdown features aren't supported in the Markdown widget: -- Embedded HTML syntax +- HTML syntax embedded - Code highlighting (wiki/others support language-syntax aware color coding, CommonMark just renders code as plain preformatted text) - Checklists - Emoji characters - Attachments - Math formulas - -## Connect to your project - -To add the Markdown widget to a dashboard, you connect to your project using a [supported web browser](/azure/devops/server/compatibility#supported-browsers). - -::: moniker range=">= azure-devops-2019" -Open a web browser, connect to your project, and select **Overview>Dashboards**. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Web portal, open Dashboards.](media/dashboards/open-dashboards-vert.png) - -If you need to switch to a different project, select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to [browse all projects](../../project/navigation/go-to-project-repo.md). - -::: moniker-end - -::: moniker range="tfs-2018" - -Open a web browser, connect to your project, and select **Dashboards**. - -![Screenshot of Web portal, Open Dashboards, TFS 2018.](media/dashboards-go-to.png) - -If you need to switch to a different project, select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to [browse all projects and teams](../../project/navigation/go-to-project-repo.md). - -::: moniker-end - - ## Add the Markdown widget -If you need to add a dashboard, see [Add, rename, and delete dashboards](dashboards.md). - -::: moniker range=">= azure-devops-2019" -To add the Markdown widget to the dashboard, select :::image type="icon" source="media/icons/edit-icon.png" border="false"::: **Edit**. The widget catalog will automatically open. - -1. Add or drag the Markdown widget onto the dashboard where you want it located. - - Screenshot of Markdown widget. - -1. Select **Done Editing** to exit dashboard editing. This will dismiss the widget catalog. You can then configure the Markdown widget as needed. - -2. Select the ![gear icon](../../media/icons/gear-icon.png) gear icon to open the configuration dialog for the widget. - - To edit a Markdown widget, you may need to be a team admin, a member of the Project Administrators group, or be granted permissions. To learn more, see [Set dashboard permissions](dashboard-permissions.md). - -3. Adjust the widget size as needed to fit the contents of the Markdown you'll enter. The largest size is 10 tiles wide by 10 tiles tall. You can always adjust this later. - - Screenshot of Markdown widget configuration dialog, change size. - -4. Enter the text and Markdown syntax into the configuration the configuration dialog. For supported syntax, see [Syntax guidance for Markdown files, widgets, wikis, and pull request comments](../../project/wiki/markdown-guidance.md). - - Here we show some simple text with a bulleted list of four links - - Screenshot for Configure markdown, text entry. - - > [!TIP] - > To link to a wiki page,use the following syntax:
      - > `/ProjectName/_wiki/wikis/WikiRepositoryName?pagePath=/FileName` - > - > To link to a repository file, page, or image within the project, rich-click the file and use the full URL. - - This renders the following widget: - - Screenshot of Web portal, Sample Markdown widget. - - > [!NOTE] - > Links to documents on file shares using `file://` are not supported. This restriction has been implemented for security purposes. - -5. Optionally, you can select to point to a file in your repository. - - Screenshot of Configure Markdown widget with a repo file. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Select :::image type="icon" source="media/edit-dashboard-icon.png" border="false"::: **Edit** to modify a dashboard. - -1. Select :::image type="icon" source="media/add-widget-icon.png" border="false"::: to open the widget catalog. - -2. Drag the Markdown widget onto the dashboard where you want it located. - - Markdown widget - -3. Select the ![gear icon](../../media/icons/gear-icon.png) gear icon to open the configuration dialog for the widget. - - To edit a Markdown widget, you may need to be a team admin, a member of the Project Administrators group, or be granted permissions. To learn more, see [Set dashboard permissions](dashboard-permissions.md). - -4. Adjust the widget size as needed to fit the contents of the Markdown you'll enter. The largest size is 10 tiles wide by 10 tiles tall. You can always adjust this later. - - Change Markdown widget size - -5. Enter the text and Markdown syntax into the configuration the configuration dialog. For supported syntax, see [Syntax guidance for Markdown files, widgets, wikis, and pull request comments](../../project/wiki/markdown-guidance.md). - - Here we show some simple text with a bulleted list of four links - - Configure Markdown - - To link to a wiki page, repository file, or page within the project, use this format: - - `/DefaultCollection/Fabrikam%20Fiber/Voice/_wiki?pagePath=%2FHome` - `/DefaultCollection/Fabrikam%20Fiber/Voice/_git/Fabrikam%20Fiber?path=%2FREADME.md` - `/DefaultCollection/Fabrikam%20Fiber/Voice/_backlogs?level=Backlog%20items&showParents=false&_a=backlog` - - This renders the following widget: +Do the following steps to add the Markdown widget. To add a dashboard, see [Add, rename, and delete dashboards](dashboards.md). - Web portal, Sample Markdown widget +1. Sign in to your project (```https://dev.azure.com/{Your_Organization/Your_Project}```). +2. Select **Dashboards**. +3. Select :::image type="icon" source="media/icons/edit-icon.png" border="false"::: **Edit**. The widget catalog automatically opens. +4. Add or drag the Markdown widget onto the dashboard where you want it located. - > [!NOTE] - > Links to documents on file shares using `file://` are not supported. This restriction has been implemented for security purposes. - -6. Optionally, you can select to point to a file in your repository. + ![Screenshot shows Markdown widget.](media/widget-markdown-tile.png) - Screenshot of Configuration dialog for Markdown widget with a repo file selected. +5. Select **Done Editing** to exit dashboard editing. This action dismisses the widget catalog. You can then configure the Markdown widget as needed. +6. Select :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: more actions > ![gear icon](../../media/icons/gear-icon.png) **Configure**. -7. If you haven't closed the widget catalog yet, do that now. + :::image type="content" source="media/widget-more-actions-configure.png" alt-text="Screenshot shows three dots for more actions, and the highlighted Configure button."::: -8. If you want to reposition the Markdown widget or other widgets on the dashboard, do that now while you're still in dashboard edit mode. +7. (Optional) Adjust the widget size as needed to fit the contents of the Markdown. The largest size is 10 tiles wide by 10 tiles tall. You can always adjust the size later. +8. Enter text and Markdown syntax into the configuration dialog. For supported syntax, see [Syntax guidance for Markdown files, widgets, wikis, and pull request comments](../../project/wiki/markdown-guidance.md). -9. When you're finished with your changes, select ![Exit edit-dashboard-mode icon](media/exit-edit-dashboard-mode-icon.png) to exit dashboard editing. + ![Screenshot shows Markdown widget configuration dialog.](media/add-markdown-size.png) -::: moniker-end + > [!NOTE] + > - Links to documents on file shares using `file://` aren't supported. This restriction is implemented for security purposes. + > - To link to a wiki page, use the following syntax:
      + > `/ProjectName/_wiki/wikis/WikiRepositoryName?pagePath=/FileName` + > - To link to a repository file, page, or image within the project, choose **Select a markdown file**, choose your **Repository**, **Branch**, and **Path** from the dropdown menus. +9. **Save** your changes. ## Related articles - [Add and manage dashboards](dashboards.md) - [Add a widget to a dashboard](add-widget-to-dashboard.md) -- [Syntax guidance for Markdown files, widgets, wikis, and pull request comments](../../project/wiki/markdown-guidance.md) -- [Marketplace widgets](https://marketplace.visualstudio.com/search?term=widget&target=VSTS&category=All%20categories&sortBy=Relevance) +- [Get syntax guidance for Markdown files, widgets, wikis, and pull request comments](../../project/wiki/markdown-guidance.md) +- [Browse marketplace widgets](https://marketplace.visualstudio.com/search?term=widget&target=VSTS&category=All%20categories&sortBy=Relevance) diff --git a/docs/report/dashboards/add-widget-to-dashboard.md b/docs/report/dashboards/add-widget-to-dashboard.md index 0221495efa8..3e2a43fd665 100644 --- a/docs/report/dashboards/add-widget-to-dashboard.md +++ b/docs/report/dashboards/add-widget-to-dashboard.md @@ -9,10 +9,9 @@ ms.author: chcomley author: chcomley ms.topic: quickstart monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 10/25/2024 --- - # Add widgets to a dashboard [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -22,124 +21,75 @@ Widgets smartly format data to provide access to easily consumable data. You add Each widget provides access to a chart, user-configurable information, or a set of links that open a feature or function. You can add one or more charts or widgets to your dashboard. Up to 200 widgets total. You add several widgets at a time simply by selecting each one. See [Manage dashboards](dashboards.md#manage) to determine the permissions you need to add and remove widgets from a dashboard. -[!INCLUDE [temp](../includes/dashboard-prerequisites.md)] - -::: moniker range=">= azure-devops-2019" - -> [!NOTE] -> Widgets specific to a service are disabled if the service they depend on has been disabled. For example, if **Boards** is disabled, New Work item and all work tracking Analytics widgets are disabled and won't appear in the widget catalog. If Analytics is disabled or not installed, then all Analytics widgets are disabled. -> -> To re-enable a service, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). For Analytics, see [enable or install Analytics](analytics-extension.md)]. - -::: moniker-end +## Prerequisites +[!INCLUDE [temp](../includes/dashboard-prerequisites.md)] ## Open a dashboard -All dashboards are associated with a team. You need to be a team administrator, project administrator, or a team member with permissions to modify a dashboard. +All dashboards are associated with a team. Be a team administrator, project administrator, or a team member with permissions to modify a dashboard. -::: moniker range=">= azure-devops-2019" +> [!NOTE] +> Widgets specific to a service are disabled if the service they depend on has been disabled. For example, if **Boards** is disabled, New Work item and all work tracking Analytics widgets are disabled and don't appear in the [widget catalog](widget-catalog.md). If Analytics is disabled or not installed, then all Analytics widgets are disabled. +> +> To re-enable a service, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). For Analytics, see [enable or install Analytics](analytics-extension.md). -1. Open a web browser, connect to your project, and select **Overview>Dashboards**. The dashboard directory page opens. +1. Open a web browser, connect to your project, and select **Overview** > **Dashboards**. The dashboard directory page opens. - > [!div class="mx-imgBorder"] - > ![Web portal, open Dashboards](media/dashboards/open-dashboards-vert.png) + :::image type="content" source="media/dashboards/open-dashboards-vert.png" alt-text="Screenshot of web portal, open Dashboards."::: If you need to switch to a different project, select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to [browse all projects](../../project/navigation/go-to-project-repo.md). -1. Select the dashboard you want to modify. - -::: moniker-end - -::: moniker range="tfs-2018" -Open a web browser, connect to your project, and select **Dashboards**. - -![Dashboards directory, previous navigation](media/dashboards-go-to.png) - -Select the team whose dashboards you want to view. To switch your team focus, see [Switch project or team focus](../../project/navigation/go-to-project-repo.md). - -Select the name of the dashboard to modify it. - -For example, here we select to view the Work in Progress dashboard. +2. Select the dashboard you want to modify. -> [!div class="mx-imgBorder"] -> ![Dashboards, Select a team dashboard](media/dashboards/choose-dashboard.png) - -If you need to switch to a different project, select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to [browse all projects](../../project/navigation/go-to-project-repo.md). -::: moniker-end - - -## Add a widget - -::: moniker range=">= azure-devops-2019" +## Add a widget To add widgets to the dashboard, select :::image type="icon" source="media/icons/edit-icon.png" border="false"::: **Edit**. -The widget catalog will automatically open. Add all the widgets that you want and drag their tiles into the sequence you want. +The [widget catalog](widget-catalog.md) automatically opens. Add all the widgets that you want and drag their tiles into the sequence you want. -When you're finished with your additions, select **Done Editing** to exit dashboard editing. The widget catalog will close. You can then [configure the widgets](#configure) as needed. +When you finish your additions, select **Done editing** to exit dashboard editing. The widget catalog closes. You can then [configure the widgets](#configure) as needed. > [!TIP] > When you're in dashboard edit mode, you can remove, rearrange, and configure widgets, as well as add new widgets. Once you leave edit mode, the widget tiles remain locked, reducing the chances of accidentally moving a widget. To remove a widget, select ![actions icon](../../media/icons/actions-icon.png) **More actions** and select **Delete** from the menu. -> [!div class="mx-imgBorder"] -> ![Delete a widget from a dashboard](media/dashboards/delete-widget.png) - -::: moniker-end - -::: moniker range="tfs-2018" -Select ![Edit dashboard icon](media/edit-dashboard-icon.png) to modify a dashboard. Select ![add a widget icon](media/add-widget-icon.png) to add a widget to the dashboard. - -The [widget catalog](widget-catalog.md) describes all available widgets, many of which are scoped to the selected team context. - -::: moniker-end +:::image type="content" source="media/dashboards/delete-widget.png" alt-text="Screenshot of delete widget from a dashboard."::: Or, you can drag and drop a widget from the catalog onto the dashboard. - - -::: moniker range=">= azure-devops-2019" + ## Add an Analytics widget -This example shows how to add the Velocity widget available from Analytics to a dashboard. +Analytics widget data gets calculated from the Analytics service. The Analytics service must be installed and enabled in Azure DevOps. -1. Select ![edit icon](media/icons/edit-icon.png) **Edit** to modify a dashboard. The widget catalog opens. +The following steps show how to add the Velocity widget available from Analytics to a dashboard: -4. In the right pane search box, type **Velocity** to quickly locate the Velocity widget within the widget catalog. +1. Select ![edit icon](media/icons/edit-icon.png) **Edit** to modify a dashboard. The [widget catalog](widget-catalog.md) opens. - > [!div class="mx-imgBorder"] - > ![Velocity widget in widget catalog](media/add-widgets/velocity-in-widget-catalog.png) +2. In the right pane search box, enter **Velocity** to quickly locate the Velocity widget within the widget catalog. -5. Select the widget, then **Add** to add it to the dashboard. Or, you can drag-and-drop it onto the dashboard. + :::image type="content" source="media/add-widgets/velocity-in-widget-catalog.png" alt-text="Screenshot of Velocity widget in widget catalog."::: -6. Next, configure the widget. For details, see the following articles: - - [Configure burndown or burnup](configure-burndown-burnup-widgets.md) - - [Configure cumulative flow](cumulative-flow.md) - - [Configure lead/cycle time](cycle-time-and-lead-time.md) - - [Configure velocity](team-velocity.md) - - [Configure test trend results](configure-test-results-trend.md) - -::: moniker-end +3. Select the widget, then **Add** to add it to the dashboard. Or, you can drag-and-drop it onto the dashboard. +4. [Configure the widget](#configure-a-widget). - + ## Configure a widget -Most widgets support configuration, which may include specifying the title, setting the widget size, and other widget-specific variables. +Most widgets support configuration, which might include specifying the title, setting the widget size, and other widget-specific variables. To configure a widget, add the widget to a dashboard, select open the ![actions icon](../../media/icons/actions-icon.png) menu, and select **Configure**. -> [!div class="mx-imgBorder"] -> ![Open the create a dashboard dialog](media/add-widgets/configure-widget.png) - +:::image type="content" source="media/add-widgets/configure-widget.png" alt-text="Screenshot of opened dashboard dialog."::: ::: moniker range=">= azure-devops-2020" -Additional information is provided to configure the following widgets: +For more information about configuring widgets, see the following articles: - [Burndown/burnup](configure-burndown-burnup-widgets.md) - [Cumulative flow](cumulative-flow.md) - [Lead time or cycle time](cycle-time-and-lead-time.md) @@ -148,86 +98,37 @@ Additional information is provided to configure the following widgets: ::: moniker-end -::: moniker range="azure-devops-2019" - -Additional information is provided to configure the following widgets: -- [Burndown/burnup](configure-burndown-burnup-widgets.md) -- [Cumulative flow](cumulative-flow.md) -- [Lead time or cycle time](cycle-time-and-lead-time.md) -- [Velocity widget](team-velocity.md) - -::: moniker-end - - - + ## Move or delete a widget To move a widget, you need to enable the dashboard edit mode. To delete a widget, select the delete option provided from the widget's **More actions** menu. - -::: moniker range=">= azure-devops-2019" Select :::image type="icon" source="media/icons/edit-icon.png" border="false"::: **Edit** to modify your dashboard. You can then add widgets or drag tiles to reorder their sequence on the dashboard. -To remove a widget, select the ![actions icon](../../media/icons/actions-icon.png) actions icon and select the **Delete** option from the menu. - -> [!div class="mx-imgBorder"] -> ![Delete a widget from a dashboard](media/dashboards/delete-widget.png) - -When you're finished with your changes, select **Done Editing** to exit dashboard editing. - -::: moniker-end - - -::: moniker range="tfs-2018" -Select ![Edit dashboard icon](media/edit-dashboard-icon.png) to modify your dashboard. You can then drag tiles to reorder their sequence on the dashboard. - -To remove a widget, select the ![actions icon](../../media/icons/actions-icon.png) actions icon and select the **Delete** option from the menu. - -> [!div class="mx-imgBorder"] -> ![Delete a widget from a dashboard](media/dashboards/delete-widget.png) - -::: moniker-end - +To remove a widget, select the ![actions icon](../../media/icons/actions-icon.png) actions icon and then **Delete** it. -::: moniker range="tfs-2018" +:::image type="content" source="media/dashboards/delete-widget.png" alt-text="Screenshot of delete widget from a dashboard."::: -When you're finished with your changes, select ![Exit edit-dashboard-mode icon](media/exit-edit-dashboard-mode-icon.png) to exit dashboard editing. +When you finish your changes, select **Done Editing** to exit dashboard editing. -::: moniker-end - - + ## Copy a widget -You can copy a widget to the same dashboard or to another team dashboard. If you want to move widgets you've configured to another dashboard, here's how you do it. Before you begin, add the dashboard you want to copy or move the widget to. Once you've copied the widget, you can delete it from the current dashboard. - +You can copy a widget to the same dashboard or to another team dashboard. If you want to move widgets you configured to another dashboard, here's how you do it. Before you begin, add the dashboard that you want to copy or move the widget to. Once you copy the widget, you can delete it from the current dashboard. -::: moniker range=">= azure-devops-2019" To copy a configured widget to another team dashboard, select the ![Actions icon](../../media/icons/actions-icon.png) actions icon and select **Copy to dashboard** and then the dashboard to copy it to. -> [!div class="mx-imgBorder"] -> ![Copy a widget to another dashboard](media/add-widgets/copy-to-dashboard.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -To copy a configured widget to another team dashboard, select -the ![Actions icon](../../media/icons/actions-icon.png) actions icon and select **Add to dashboard** and then the dashboard to copy it to. - -Copy a widget to another team dashboard - -::: moniker-end - +:::image type="content" source="media/add-widgets/copy-to-dashboard.png" alt-text="Screenshot of Copying a widget to another dashboard."::: ## Widget size -Some widgets are pre-sized and can't be changed. Others are configurable through their configuration dialog. +Some widgets are presized and can't be changed. Others are configurable through their configuration dialog. For example, the Chart for work items widget allows you to select an area size ranging from 2 x 2 to 4 x 4 (tiles). -Change widget size +:::image type="content" source="media/add-widget-size.png" alt-text="Screenshot of change widget size function."::: ## Extensibility and Marketplace widgets @@ -237,12 +138,11 @@ In addition to the widgets described in the Widget catalog, you can: ## Disabled Marketplace widgets -If your organization owner or project collection administrator disables a marketplace widget, you'll see the following image: +If your organization owner or project collection administrator disables a marketplace widget, the following notification displays: -Disabled widget extension notification - -To regain access to it, request your admin to reinstate or reinstall the widget. +:::image type="content" source="media/widget-catalog-disabled-widget.png" alt-text="Screenshot of Disabled widget extension notification."::: +To regain access, request your administrator to reinstate or reinstall the widget. ## Next steps @@ -253,18 +153,8 @@ To regain access to it, request your admin to reinstate or reinstall the widget. ## Related articles -::: moniker range=">= azure-devops-2019" -- [FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml) -- [Analytics-based widgets](../dashboards/analytics-widgets.md) -- [What is Analytics?](../powerbi/what-is-analytics.md) -- [Burndown guidance](burndown-guidance.md) -- [Cumulative flow & lead/cycle time guidance](cumulative-flow-cycle-lead-time-guidance.md) -::: moniker-end - -::: moniker range="tfs-2018" -- [FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml) -- [Burndown guidance](burndown-guidance.md) -- [Cumulative flow & lead/cycle time guidance](cumulative-flow-cycle-lead-time-guidance.md) -::: moniker-end - - +- [Find answers to FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml) +- [Explore analytics-based widgets](../dashboards/analytics-widgets.md) +- [Learn about Analytics](../powerbi/what-is-analytics.md) +- [Get burndown guidance](burndown-guidance.md) +- [Understand cumulative flow and lead/cycle time](cumulative-flow-cycle-lead-time-guidance.md) diff --git a/docs/report/dashboards/analytics-extension.md b/docs/report/dashboards/analytics-extension.md index 6cb32f8f561..330fc93b5d3 100644 --- a/docs/report/dashboards/analytics-extension.md +++ b/docs/report/dashboards/analytics-extension.md @@ -6,8 +6,8 @@ ms.topic: how-to ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019 < azure-devops' -ms.date: 07/26/2022 +monikerRange: " [!NOTE] > The Analytics Marketplace extension and Analytics are **not supported** for TFS 2018 or earlier versions. -Analytics supports access to Analytics widgets for all projects defined in the project collection. To learn more, see [What is Analytics?](../powerbi/what-is-analytics.md) and [Widgets based on Analytics](analytics-widgets.md). Data available in Analytics is summarized in [Data available from Analytics](../powerbi/data-available-in-analytics.md). +Analytics supports access to Analytics widgets for all projects defined in the project collection. For more information, see [What is Analytics?](../powerbi/what-is-analytics.md) and [Widgets based on Analytics](analytics-widgets.md). Data available in Analytics is summarized in [Data available from Analytics](../powerbi/data-available-in-analytics.md). ## Prerequisites -::: moniker range="azure-devops-2019" -**For Azure DevOps Server 2019.1:** -::: moniker-end +**For Azure DevOps Server 2019.1 and greater:** -- You must have installed and configured your Azure DevOps Server. For details, see [Install and configure Azure DevOps on-premises](/azure/devops/server/install/get-started). -- You must have added at least one project collection. To add project collections, see [Manage project collections](/azure/devops/server/admin/manage-project-collections). -- To enable, pause, disable, or resume Analytics, you must be a member of the **[Project Collection Administrators](../../organizations/security/change-organization-collection-level-permissions.md)**[ group](../../organizations/security/change-organization-collection-level-permissions.md) group with **[Edit collection-level information](../../organizations/security/permissions.md#collection)**[ permissions](../../organizations/security/permissions.md#collection). - -::: moniker range="azure-devops-2019" -**For Azure DevOps Server 2019:** - -- You must have installed and configured your Azure DevOps Server. For details, see [Install and configure Azure DevOps on-premises](/azure/devops/server/install/get-started). -- You must have added at least one project collection. To add project collections, see [Manage project collections](/azure/devops/server/admin/manage-project-collections). -- To install an extension, you must be a member of the **[Project Collection Administrators](../../organizations/security/change-organization-collection-level-permissions.md)**[ group](../../organizations/security/change-organization-collection-level-permissions.md) group with **[Edit collection-level information](../../organizations/security/permissions.md#collection)**[ permissions](../../organizations/security/permissions.md#collection) If you don't have permissions, you can [request extensions](../../marketplace/request-extensions.md) instead. -- To upload an extension, you must be a member of the [Azure DevOps Server Administrators](/azure/devops/server/admin/add-administrator) group with **[Edit instance-level information](../../organizations/security/permissions.md#server)**[ permissions](../../organizations/security/permissions.md#server). - ::: moniker-end +|Category | Requirements | +|-------------|-------------| +| **Project collection** |[Project collection](/azure/devops/server/admin/manage-project-collections). | +| **Permissions** | To enable, pause, disable, or resume Analytics: Member of the [Project Collection Administrators group](../../organizations/security/change-organization-collection-level-permissions.md) with [Edit collection-level information permissions](../../organizations/security/permissions.md#collection). For more information about other prerequisites regarding service and feature enablement and general data tracking activities, see [Permissions and prerequisites to access Analytics](../analytics/analytics-permissions-prerequisites.md). | +| **Tools** |Azure DevOps Server [installed and configured](/azure/devops/server/install/get-started). | ## Enable Analytics -::: moniker range="azure-devops-2019" - -If you've upgraded to Azure DevOps Server 2019.1, you can enable Analytics for a project collection with the following steps. Otherwise, for Azure DevOps Server 2019, see [Install Analytics](#install-analytics). - -::: moniker-end - > [!NOTE] > Analytics is automatically enabled for all newly created project collections. @@ -72,21 +51,17 @@ If you've upgraded to Azure DevOps Server 2019.1, you can enable Analytics for a > [!div class="mx-imgBorder"] > ![Enable Analytics](media/enable-analytics/enable-analytics.png) - Once enabled, Analytics staging jobs begin to populate the Analytics data tables. This process could take some time depending on the size of your collection. To learn more about the data tables, see [Analytics data model](../extend-analytics/data-model-analytics-service.md). + Once enabled, Analytics staging jobs begin to populate the Analytics data tables. This process could take some time depending on the size of your collection. For more information about the data tables, see [Analytics data model](../extend-analytics/data-model-analytics-service.md). ## Pause or disable Analytics -::: moniker range="azure-devops-2019" -If you've upgraded to Azure DevOps Server 2019.1, you can pause or disable Analytics for a project collection with the following steps. Otherwise, for Azure DevOps Server 2019, the equivalent actions are to [Disable or uninstall the Analytics extension](#disable-analytics-extension). -::: moniker-end - -You can only pause or disable Analytics that has been previously enabled. +You can only pause or disable previously enabled Analytics. 1. From the **Analytics** settings page, select **Pause Analytics** or **Disable Analytics**. > [!div class="mx-imgBorder"] > ![Pause or Disable Analytics](media/enable-analytics/pause-analytics.png) -1. Confirm that you want to pause or disable the service. +2. Confirm that you want to pause or disable the service. > [!div class="mx-imgBorder"] > ![Confirm Pause dialog.](media/enable-analytics/confirm-pause.png) ![Confirm Disable](media/enable-analytics/confirm-disable.png) @@ -95,15 +70,11 @@ You can only pause or disable Analytics that has been previously enabled. ## Resume Analytics -::: moniker range="azure-devops-2019" -For Azure DevOps Server 2019.1, you can resume Analytics after you've paused it for a project collection. Resuming the service will re-enable staging jobs, which will update the data tables and make them current, updating since the time it was paused. -::: moniker-end - 1. From the **Analytics** settings page, select **Resume Analytics**. > [!div class="mx-imgBorder"] > ![Enable Analytics](media/enable-analytics/enable-analytics.png) -1. Confirm that you want to resume the service. +2. Confirm that you want to resume the service. > [!div class="mx-imgBorder"] > ![Confirm Resume dialog.](media/enable-analytics/confirm-resume.png) @@ -112,135 +83,29 @@ For Azure DevOps Server 2019.1, you can resume Analytics after you've paused it ## What happens if I pause or disable Analytics? -Pausing Analytics or disabling the Analytics extension (2019), disables the following features: +When you pause or disable the Analytics extension (2019), the following features get disabled: - [Analytics widgets](analytics-widgets.md) - [Analytics in-context reports, such as pipeline and test reports](overview.md) - [Power BI integration using Analytics views](../powerbi/what-are-analytics-views.md) - [OData endpoint queries](../extend-analytics/quick-ref.md) -Pausing Analytics preserves your data but stops staging jobs from updating your data. You can resume the service later and your data will then be updated. +Pausing Analytics preserves your data but stops staging jobs from updating your data. You can resume the service later and then your data updates. -Disabling Analytics or removing the Analytics extension (2019), turns off all Analytics staging jobs and deletes the Analytics data stored in the Analytics tables. All Analytics data that captures historical trends is lost. It doesn't delete any other data stored in your collection. You can't undo this action. Once historical data and trending data is deleted, you can't restore it. Re-enabling Analytics won't restore the historical data. +When you disable or remove the Analytics extension (2019), it turns off all Analytics staging jobs and deletes the Analytics data that is stored in the Analytics tables. All Analytics data that captures historical trends is lost. It doesn't delete any other data stored in your collection. You can't undo this action. Once historical data and trending data is deleted, you can't restore it. Re-enabling Analytics doesn't restore the historical data. With Analytics disabled or removed, the following actions occur: -- No staging jobs are run, and the Analytics tables won't have updated information. -- Table data is deleted, and if Analytics is re-enabled, all data will have to be repopulated from scratch. - -::: moniker range="azure-devops-2019" - -> [!NOTE] -> Disabling Analytics in Azure DevOps Server 2019.1 is the same as uninstalling the Analytics extension for Azure DevOps Server 2019. - -::: moniker-end - -To learn more about the data tables, see [Analytics data model](../extend-analytics/data-model-analytics-service.md). - -::: moniker range="azure-devops-2019" - - - -## Install the Analytics extension - -If you haven't upgraded to Azure DevOps Server 2019.1, you can install the Analytics extension to gain access to Analytics widgets and reports for your project collection. The Analytics extension is shipped within the on-premises installer. Installing the extension simply enables the functionality. There isn't any need to download extension files manually to install. - -> [!TIP] -> The Analytics extension appears in the local gallery for Azure DevOps Server so that there isn't any need to download it from the Azure DevOps Marketplace. - -1. From a web browser, select (1) the project collection, (2) **Admin settings**, and then (3) **Extensions**. - - ![Open Collection>Admin settings>Extensions](media/install-analytics/open-collection-admin-extensions.png) -1. Select **Browse local extensions**. - - > [!div class="mx-imgBorder"] - > ![Browse local marketplace](media/install-analytics/browse-marketplace.png) - - > [!NOTE] - > Installing the extension from the local marketplace is identical to installing from the hosted marketplace. The only difference is the hosted marketplace shows extension ratings and user comments. -1. The local Marketplace opens in a new browser tab. Select the Analytics extension card. - - > [!div class="mx-imgBorder"] - > ![Analytics extension card](media/install-analytics/local-marketplace.png) - -1. Select **Get it free**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Analytics Marketplace extension, Select Get it free.](media/install-analytics/choose-get-it-free.png) - -1. Select the project collection and then select **Install**. - - > [!div class="mx-imgBorder"] - > ![Select the project collection](media/install-analytics/select-collection.png) - -1. Upon completion of install, you'll see an image similar to the following. Select **Proceed to collection** to return to the web portal for your collection. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Analytics Marketplace extension installed, Proceed to collection.](media/install-analytics/success-install.png) - - Optionally, if you want to install the Analytics extension on other project collections, select the browser back button. - - +- No staging jobs run, and the Analytics tables information doesn't get updated. +- Table data is deleted, and if Analytics is re-enabled, all data must get repopulated from scratch. -## Disable or uninstall the Analytics extension - -If you choose to disable the Analytics extension, it will stop any jobs from running. Analytics data will be out of sync and associated features won't be available. However, no data is deleted. Uninstalling the Analytics extension deletes the data from the Analytics database tables. Upon reinstall of the extension, the data is repopulated from scratch. - -1. Open the extensions menu and select **Manage Extensions**. - - ![Screenshot of Manage extensions tab.](media/install-analytics/install-devops-extension-13.png) -1. In the **Manage** tab, open the shortcut menu for the extension. -1. Select **Disable** or **Uninstall** as required. - -## Restore the Analytics extension if removed from the deployment - -If you remove the Analytics extension from your deployment, you can install the extension from the online marketplace to restore it. You may be unable to use the online marketplace because of your server setup. For example, your firewall might block some outgoing connections. Even if that's the case, you can restore it to the local marketplace using the following steps. - -1. Open **Collection settings** following the instructions provided in the section [Install the Analytics extension](#install-the-analytics-extension). - - Select **Extensions**, and then **Browse local extensions**. -1. Scroll to the bottom of the page, and select **Manage Extensions**. - - > [!div class="mx-imgBorder"] - > ![Manage extensions](media/install-analytics/manage-extensions.png) - -1. Select **Upload extension** and then select **click to upload**. Browse to the folder containing the Microsoft.TeamFoundation.Extension.Analytics.vsix file. - - > [!div class="mx-imgBorder"] - > ![Upload extension](media/install-analytics/upload-extension.png) - - The .vsix file can be found in your application-tier folder installation in the following path. - - `C:\Program Files\Azure DevOps Server 2019\Tools\Deploy\TfsServicingFiles\Extensions\Microsoft.TeamFoundation.Extension.Analytics.vsix` - - Uploading the extension restores it to the local marketplace. From there, you can install it to a collection. - - - -## How to determine if your server is disconnected? - -If your server is disconnected from the Internet, you must install Analytics from the local marketplace. - -You can determine if your Azure DevOps Server is in a disconnected state. Check to see if the connected icon and server name appear at the top when browsing the hosted marketplace. - -> [!div class="mx-imgBorder"] -> ![Determining if your server is connected or not](media/install-analytics/browse-marketplace-connected.png) - -When you navigate to the Marketplace from your on-premises server, an error doesn't display if you're not connected. It simply switches to the cloud service context. - -## Known issue - -If you use a public URL to install the extension, for example `https://OnPrem.MyCompany.com`, you may get a callback error, such as a TLS/SSL error. - -To resolve this issue, you can install the extension from a machine that hosts the application tier and point to the local machine URL, for example `https://myMachineName`. - -::: moniker-end +For more information about the data tables, see [Analytics data model](../extend-analytics/data-model-analytics-service.md). ## Related articles - [What is Analytics](../powerbi/what-is-analytics.md) - [Data available from Analytics](../powerbi/data-available-in-analytics.md) -- [Grant permissions to access Analytics](../powerbi/analytics-security.md) +- [Grant permissions for accessing Analytics](../powerbi/analytics-security.md) - [The Reporting Roadmap](../powerbi/reporting-roadmap.md) - [Extension FAQs](../../marketplace/faq-extensions.yml) diff --git a/docs/report/dashboards/analytics-widgets.md b/docs/report/dashboards/analytics-widgets.md index bc2e8220679..07f482fa6ef 100644 --- a/docs/report/dashboards/analytics-widgets.md +++ b/docs/report/dashboards/analytics-widgets.md @@ -6,11 +6,10 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 09/27/2021 --- - # Widgets based on Analytics data [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] @@ -19,24 +18,28 @@ ms.date: 09/27/2021 Analytics supports several dashboard widgets that take advantage of the power of the service. Using these widgets, you and your team can gain valuable insights into the health and status of your work. ::: moniker-end -::: moniker range="azure-devops-2019" -Analytics supports several dashboard widgets that take advantage of the power of the service. Once you [enable or install Analytics](../dashboards/analytics-extension.md) on a project collection, you can add these widgets to your dashboard. To add extensions or enable the service, you must be an organization owner or a member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md). Using these widgets, you and your team can gain valuable insights into the health and status of your work. -::: moniker-end - You add an Analytics widget to a dashboard the same way you add any other type of widget. For details, see [Add a widget to your dashboard](add-widget-to-dashboard.md). - - ## Prerequisites ::: moniker range="azure-devops" -- Analytics widget data is calculated from the Analytics service. The Analytics service is enabled for all Azure DevOps organizations. -- To view Analytics data, you must have the **View analytics** project-level permission set to **Allow**. By default, this permission is set for all project members in all security groups. Users granted **Stakeholder** access or greater can view Analytics widgets. + +The Analytics service is enabled for all Azure DevOps organizations. + +|Category | Requirements | +|-------------|-------------| +| **Permissions** |- To view Analytics data: **View analytics** project-level permission set to **Allow**. By default, all project members in all security groups have this permission. | +|**Access levels** | At least **Stakeholder** access. | + ::: moniker-end ::: moniker range="< azure-devops" -- Analytics widget data is calculated from the Analytics service. -- For Analytics widgets to display correctly, the Analytics service must be enabled on your on-premises Azure DevOps Server. To learn more, see [Install/uninstall or enable/disable the Analytics service](../../report/dashboards/analytics-extension.md). -- To view Analytics data, you must have the **View analytics** project-level permission set to **Allow**. By default, this permission is set for all project members in all security groups. Users granted **Stakeholder** access or greater can view Analytics widgets. + +|Category | Requirements | +|-------------|-------------| +| **Permissions** |- To view Analytics data: **View analytics** project-level permission set to **Allow**. By default, all project members in all security groups have this permission. | +|**Access levels** | At least **Stakeholder** access. | +|**Services** | [Analytics service enabled](../../report/dashboards/analytics-extension.md). | + ::: moniker-end [!INCLUDE [temp](../includes/boards-disabled.md)] @@ -53,7 +56,7 @@ The Burndown widget lets you display a trend of remaining work across multiple t ![Burndown Widget - Release Burndown Example](./media/burndown-ax-catalog.png) -To learn more, see [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). +For more information, see [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). ## Burnup widget @@ -63,8 +66,7 @@ The Burnup widget lets you display a trend of completed work across multiple tea ![Burnup Widget - Release Burnup Example](./media/burnup-ax-catalog.png) -To learn more, see [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). - +For more information, see [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). ## Sprint Burndown widget @@ -75,12 +77,11 @@ The Analytics-based Sprint Burndown widget adds a team's burndown chart for a sp > [!div class="mx-imgBorder"] > ![Sprint Burndown Widget - Sprint Burndown Example](media/sprint-burndown/sprint-burndown-widget.png) -To learn more, see [Configure and monitor sprint burndown](configure-sprint-burndown.md). - +For more information, see [Configure and monitor sprint burndown](configure-sprint-burndown.md). ## Cumulative Flow Diagram (CFD) widget -The CFD widget shows the count of work items (over time) for each column of a Kanban board. It allows you to see patterns in your team's development cycle over time. It will help you answer questions like: +The CFD widget shows the count of work items (over time) for each column of a board. It allows you to see patterns in your team's development cycle over time. It will help you answer questions like: * Is there a bottleneck in my process? * Am I consistently delivering value to my users? @@ -88,7 +89,7 @@ The CFD widget shows the count of work items (over time) for each column of a Ka ![Cumulative flow diagram widget](./media/cdf-big-widget.png) -To learn more, see [Cumulative flow diagram widget](cumulative-flow.md). +For more information, see [Cumulative flow diagram widget](cumulative-flow.md). ## Cycle Time widget @@ -100,7 +101,7 @@ The Cycle Time widget will help you analyze the time it takes for your team to c ![Cycle Time widget](media/cycle-time-planning.png) -To learn more, see [Cycle Time and lead time control charts](cycle-time-and-lead-time.md). +For more information, see [Cycle Time and lead time control charts](cycle-time-and-lead-time.md). ## Lead Time widget @@ -108,12 +109,11 @@ The Lead Time widget will help you analyze the time it takes to deliver work fro * How long does it take for work requested by a customer to be delivered? * Did work items take longer than usual to complete? - **Lead Time widget showing 60 days of data** ![Lead Time widget](media/lead-time-control-chart.png) -To learn more, see [Cycle Time and lead time control charts](cycle-time-and-lead-time.md). +For more information, see [Cycle Time and lead time control charts](cycle-time-and-lead-time.md). ## Velocity widget @@ -122,13 +122,12 @@ The Velocity widget will help you learn how much work your team can complete dur * Is my team consistently delivering what we planned? * How much work can we commit to deliver in upcoming sprints? - **Velocity widget showing 8 sprints of data based on Story Points** ![Velocity widget](./media/Velocity-ax-catalog.png) -To learn more, see [Configure and view Velocity widgets](team-velocity.md). +For more information, see [Configure and view Velocity widgets](team-velocity.md). ## Test Results Trend (Advanced) @@ -144,4 +143,4 @@ You can find outliers in your test results and answer questions like: ![test trend widget by priority](media/test-results-trend-widget/passed-bypriority-pass.png) -To learn more, see [Configure a test results widget](configure-test-results-trend.md). +For more information, see [Configure a test results widget](configure-test-results-trend.md). diff --git a/docs/report/dashboards/burndown-guidance.md b/docs/report/dashboards/burndown-guidance.md index cd73f84b327..9151f70a88f 100644 --- a/docs/report/dashboards/burndown-guidance.md +++ b/docs/report/dashboards/burndown-guidance.md @@ -7,51 +7,30 @@ ms.subservice: azure-devops-analytics ms.topic: conceptual ms.author: chcomley author: chcomley -monikerRange: '<= azure-devops' -ms.date: 08/25/2022 +monikerRange: "<=azure-devops" +ms.date: 01/02/2024 --- # Burndown and burnup guidance -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -::: moniker range=">= azure-devops-2019" - -Burndown and burnup charts support project management to visually track work completed over time. The main differences between the two chart types are: +Burndown and burnup charts support project management to visually track work completed over time. - Burndown charts begin with the total amount of planned work and then as work is completed graphs the remaining work. With the progression of time, the amount of to-do work decreases. -- Burnup charts track work as it is completed over time. They are useful to show the rate at which work is getting completed. -- Sprint burndown charts track planned work for a team and a selected sprint. Sprint charts can help teams review how efficient they are in planning and executing sprint over sprint. +- Burnup charts track work as it is completed over time. They're useful to show the rate at which work is getting completed. + +Sprint burndown charts track planned work for a team and a selected sprint, so teams can review how efficiently they plan and execute sprint over sprint. -In general, burndown charts should show a downward trend. However, if teams add work through a sprint or release period, then the chart will show upward trends. These charts help teams monitor what they planned to do versus what they actually do. +Burndown charts generally show a downward trend. But, if teams add work through a sprint or release period, then the chart shows upward trends. These charts help teams monitor what they planned to do versus what they actually do. Burnup charts, on the other hand, should always show an upward trend as work is completed over time. -Burnup charts, on the other hand, should always show an upward trend as work is completed over time. The following configurable charts and widgets are available for tracking burndown or burnup. - Burndown/burnup widget (Analytics) - Sprint burndown built-in report (Analytics) - Sprint burndown widget (Analytics) - Sprint burndown widget (Legacy) (Work item store) -::: moniker-end - -::: moniker range="tfs-2018" - -Review your sprint burndown chart throughout your sprint cycle to check for these indicators: - -> [!div class="checklist"] -> * Is remaining work getting updated regularly? Flat spaces within the blue area indicate a lack of updates. -> * Is remaining work increasing instead of decreasing? Increases can indicate work that wasn't estimated or planned. Both signal a need for the team to discuss how they'll complete the sprint tasks on time. -> * Based on the actual burn rate, does the team feel confident that they'll complete the work by the end of the sprint? - -You can view sprint burndown from your team's sprint backlog built-in report or by adding the Sprint burndown widget to a team dashboard. - -To configure or view sprint burndown charts, see [Sprint burndown](configure-sprint-burndown.md). - -::: moniker-end - [!INCLUDE [note-delete-area-paths](../../boards/includes/note-delete-area-paths.md)] -::: moniker range=">= azure-devops-2019" - ## Supported configuration options The following table summarizes the configuration options supported by the various burndown chart options. Sprint burndown charts are always focused on a single team, whereas a Burndown/Burnup widget can track work for several teams. All charts support tracking by work item count or a sum of **Story Points**, **Effort**, **Remaining Work** or other custom (integer or decimal) field. @@ -66,11 +45,6 @@ The following table summarizes the configuration options supported by the variou For details on viewing and configuring charts, see [Configure and monitor sprint burndown](configure-sprint-burndown.md) or [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). -::: moniker-end - - -::: moniker range=">= azure-devops-2019" - ## General guidance Depending on the teams, work item types, and time period you want to monitor, choose the chart option according to the following guidance. @@ -84,64 +58,30 @@ Depending on the teams, work item types, and time period you want to monitor, ch | Burnup or burndown for any type of work item and time period | Burndown/Burnup widget | | Project and target completion date | Burndown/Burnup widget | - -::: moniker-end - - ## Scope management -By estimating remaining work of tasks for each backlog item, teams better understand what they can accomplish within a sprint. Because the sprint tasks define the overall sprint scope, defining the remaining work leads to a well-defined sprint scope. Anything that isn't represented by a task in the sprint should be considered out of scope for the sprint. - - -::: moniker range=">= azure-devops-2019" +When you estimate remaining work of tasks for each backlog item, teams better understand what they can accomplish within a sprint. Because the sprint tasks define the overall sprint scope, defining the remaining work leads to a well-defined sprint scope. Any nontasks in the sprint should be considered out of scope for the sprint. As the team makes progress, divergences from the ideal trend line help the team monitor divergences from scope. > [!div class="mx-imgBorder"] > ![Screenshot of Sprint burndown report, with Burndown on Count of Work Items selected.](media/burndown/analytics-burndown-stories-count-past-s159.png) -[!INCLUDE [temp](../../includes/note-working-days-off.md)] - -Increases instead of decreases within the blue graph may indicate: +The **Show non-working days** shades those days set through the team's [**Working days** and **Team days off** settings](../../boards/sprints/set-capacity.md). +Increases instead of decreases within the blue graph might indicate: - Poor estimates made to tasks - Discovery of new work not accounted for in sprint planning - Scope creep, other work not agreed to by the team. -Whatever the cause, teams should come together quickly to determine how to remedy the increased workload. - -Solutions may include reassigning tasks or recruiting more resources. The team should move all non-essential sprint work to the backlog and consider it during the next sprint planning meeting. - -::: moniker-end - -::: moniker range="tfs-2018" - -As the team makes progress, divergences from the ideal trend line help the team monitor divergences from scope. - -Increases instead of decreases within the blue graph may indicate: - -- Poor estimates made to tasks -- Discovery of new work not accounted for in sprint planning -- Scope creep, other work not agreed to by the team. - - -![Screenshot of Sprint burndown report that illustrates increasing remaining work indicating scope creep.](media/burndown/ALM_SB_ScopeCreep_75.png) - -Whatever the cause, teams should come together quickly to determine how to remedy the increased workload. - -Solutions may include reassigning tasks or recruiting more resources. The team should move all non-essential sprint work to the backlog and consider it during the next sprint planning meeting. - -::: moniker-end - +Whatever the cause, teams should come together quickly to determine how to remedy the increased workload. Solutions might include reassigning tasks or recruiting more resources. The team should move all nonessential sprint work to the backlog and consider it during the next sprint planning meeting. ## Mitigate risk through daily inspection -::: moniker range=">= azure-devops-2019" - Your burn-down chart shows you if your project is on schedule. A daily check can mitigate risks and provide early warning of potential schedule or cost overruns, two metrics associated with traditional project management. For example, when the actual remaining work (blue area) goes flat for a while, or remains high above the ideal trend line, the team is at risk of not meeting their sprint commitments. @@ -149,29 +89,12 @@ For example, when the actual remaining work (blue area) goes flat for a while, o > [!div class="mx-imgBorder"] > ![Screenshot of Burndown trend based on Sum of Remaining Work illustrating a flat line indicating risk to sprint.](media/burndown/analytics-burndown-remaining-work-s159.png) - Teams should meet immediately to course correct and either reassign work, recruit more resources, or reset expectations. - -::: moniker-end - - -::: moniker range="tfs-2018" - -Your burn-down chart shows you if your project is on schedule. A daily check can mitigate risks and provide early warning of potential schedule or cost overruns, two metrics associated with traditional project management. - -For example, when the actual remaining work (blue area) goes flat over time, or remains high above the ideal trend line, the team is at risk of not meeting their sprint commitments. - -Teams should meet immediately to course correct and either reassign work, recruit more resources, or reset expectations. - -![Screenshot of Sprint burndown report that illustrates actual remaining work higher above ideal trend line.](media/burndown/ALM_SB_RiskMitigation.png) - -::: moniker-end ## Next steps > [!div class="nextstepaction"] > [Configure and monitor sprint burndown](configure-sprint-burndown.md) or [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md) - ## Related articles - [View and configure velocity](team-velocity.md) @@ -179,8 +102,4 @@ Teams should meet immediately to course correct and either reassign work, recrui - [Query by date or current iteration, List work items moved out of a sprint](../../boards/queries/query-by-date-or-current-iteration.md#list-work-items-moved-out-of-a-sprint) - [Query by date or current iteration, List work items added to a sprint after the start date](../../boards/queries/query-by-date-or-current-iteration.md#list-work-items-added-to-a-sprint-after-the-start-date) - [Manage priorities and gain visibility across teams](../../boards/plans/visibility-across-teams.md) - -## Industry resources - -- [Understanding the Scrum Burndown Chart](https://www.methodsandtools.com/archive/scrumburndown.php) - +- [Understand the Scrum Burndown Chart](https://www.methodsandtools.com/archive/scrumburndown.php) diff --git a/docs/report/dashboards/charts-dashboard-permissions-access.md b/docs/report/dashboards/charts-dashboard-permissions-access.md index 9c71d815918..4d9bbdb241f 100644 --- a/docs/report/dashboards/charts-dashboard-permissions-access.md +++ b/docs/report/dashboards/charts-dashboard-permissions-access.md @@ -17,11 +17,10 @@ ms.date: 04/04/2022 Team members and members of the Contributors group for a project can view charts and dashboards. The most common built-in groups include Readers, Contributors, and Project Administrators. For a simplified view of all default permissions assigned to built-in groups, see [Default permissions and access](../../organizations/security/permissions-access.md). -Stakeholders have limited access to view charts and dashboards. To learn more, see [About access levels](../../organizations/security/access-levels.md). +Stakeholders get limited access to view charts and dashboards. For more information, see [About access levels](../../organizations/security/access-levels.md). For an overview of dashboard and chart features, see [Dashboards, charts, & widgets](overview.md). - ## Dashboards, charts, reports, and widgets You can define and manage dashboards from the web portal, **Dashboard**. For an overview of dashboard and chart features, see [About dashboards, charts, reports, and widgets](overview.md). You set [dashboard permissions at the team level](dashboard-permissions.md) from the team dashboard page. @@ -30,38 +29,18 @@ You can define and manage dashboards from the web portal, **Dashboard**. For an Users granted Stakeholder access to private projects can't view or create query charts. Stakeholder access to public projects can view and create query charts. ::: moniker-end - - [!INCLUDE [temp](../../organizations/security/includes/report.md)] - -::: moniker range=">= azure-devops-2019" - ## Power BI Integration and Analytics views -From the web portal **Analytics views**, you can create and manage Analytics views. An Analytics view provides a simplified way to specify the filter criteria for a Power BI report based on Analytics data. Analytics is the reporting platform for Azure DevOps. To learn more, see [What is Analytics?](../../report/powerbi/what-is-analytics.md). +From the web portal **Analytics views**, you can create and manage Analytics views. An Analytics view provides a simplified way to specify the filter criteria for a Power BI report based on Analytics data. Analytics is the reporting platform for Azure DevOps. For more information, see [What is Analytics?](../../report/powerbi/what-is-analytics.md). You set [permissions](../../report/powerbi/analytics-security.md) for the service at the project level, and for shared Analytics views at the object level. Users with **Stakeholder** access have no access to view or edit Analytics views. [!INCLUDE [temp](../../organizations/security/includes/analytics.md)] -::: moniker-end - - ## Related articles -::: moniker range=">= azure-devops-2019" - - [Work across projects](../../project/navigation/work-across-projects.md) - [Add a team administrator](../../organizations/settings/add-team-administrator.md) - [Set permissions to access Analytics data and Analytics views](../powerbi/analytics-security.md) - -::: moniker-end - -::: moniker range="tfs-2018" - -- [Work across projects](../../project/navigation/work-across-projects.md) -- [Add a team administrator](../../organizations/settings/add-team-administrator.md) - -::: moniker-end - diff --git a/docs/report/dashboards/charts.md b/docs/report/dashboards/charts.md index e509d86ecce..6a4a6601a5b 100644 --- a/docs/report/dashboards/charts.md +++ b/docs/report/dashboards/charts.md @@ -1,339 +1,247 @@ --- title: Status and trend work item, query-based charts -titleSuffix: Azure DevOps +titleSuffix: Azure DevOps description: Learn how to add status, progress, and trend charts to dashboards from flat-based queries in Azure DevOps. -ms.custom: dashboards, contperf-fy20q4 +ms.custom: dashboards ms.subservice: azure-devops-analytics -ms.assetid: EFAD32DB-8B19-4ACC-8F72-87CC5A513798 +ms.assetid: EFAD32DB-8B19-4ACC-8F72-87CC5A513798 ms.author: chcomley author: chcomley -ms.topic: tutorial +ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 02/14/2023 +ms.date: 03/12/2025 +#customer intent: As an Azure Boards user, I want to create charts to track the status of work in progress. --- -# Track progress with status and trend query-based charts +# Track progress with status and trend query-based charts [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can quickly view the status of work in progress by charting the results of a [flat-list query](../../boards/queries/using-queries.md). Different chart views such as pie, column, pivot, or trend are supported. Charts support viewing a count of work items or a sum of values for select numeric fields, such as Story Points, Effort, or Remaining Work. Group work by State, Assigned To, or other system defined or custom field. +You can quickly view the status of work in progress by charting the results of a [flat-list query](../../boards/queries/using-queries.md#define-a-flat-list-query). Queries support different chart views, such as pie, column, pivot, or trend. Charts support viewing a count of work items or a sum of values for select numeric fields, such as Story Points, Effort, or Remaining Work. Group work by State, Assigned To, or other custom or system defined field. -In this article you'll learn how to perform the following tasks: +In this article, learn how to do the following tasks: -> [!div class="checklist"] -> * Construct a flat-list query to support your chart -> * Create and share your query-based chart -> * Create a status pie, column, bar, or pivot chart -> * Create a trend chart -> * Add a chart to a dashboard +> [!div class="checklist"] +> - Construct a flat-list query to support your chart +> - Create and share your query-based chart +> - Create a status pie, column, bar, or pivot chart +> - Create a trend chart +> - Add a chart to a dashboard -> [!NOTE] -> This article describes how to configure work tracking query charts. To add existing query charts to dashboards, see [Add charts to a dashboard](add-charts-to-dashboard.md). For information on configuring a **Chart for Work Items** widget, see [Configure a chart for work items widget](configure-chart-work-items-widget.md). -> -> For an overview of all work tracking charts and in-context reports, see [About dashboards, charts, reports, & widgets](overview.md). +This article describes how to configure work tracking query charts. For more information, see the following articles: +- [Add charts to a dashboard](add-charts-to-dashboard.md) +- [Configure a chart for work items widget](configure-chart-work-items-widget.md). +- [About dashboards, charts, reports, & widgets](overview.md). +The following image shows two charts created from the same flat-list query. -::: moniker range=">= azure-devops-2019" - -For example, the following image illustrates two different charts created from the same flat-list query. The pie chart groups the 19 bugs by state, and the bar chart groups the bugs by assignment and their current status. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Active bug charts added to dashboards.](media/overview/active-bug-charts-on-dashboards-2019.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -For example, the following image illustrates four different charts created from the same flat-list query. The pie chart groups the 146 active bugs by priority, and the bar chart groups the bugs by team and their triage status. The last two chart show two different trend views of the active bugs over the last two weeks. - -![Screenshot of 4 charts for a flat-list query.](media/charts-active-bugs.png) - -::: moniker-end +:::image type="content" source="media/overview/active-bug-charts-on-dashboards-2019.png" alt-text="Screenshot of Active bug charts added to dashboards."::: ## Prerequisites -Prerequisites to meet include having **Basic** access or higher and to have created a flat-list query. Only flat-list queries support charts. - -If you want to add the chart to a dashboard, then you need to save the query under the **Shared Queries** folder, and create the dashboard where you want to add the chart. - ::: moniker range=">= azure-devops-2020" -- To create a query chart, you must have **Basic** access or higher. Users with **Stakeholder** access can't view or create charts from the **Queries** page, however, they can view charts added to a team dashboard. For details, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -- To add a chart to a dashboard, you must save the query to a **Shared Queries** folder. To do that, you must be granted permissions to save queries under a folder. To get permissions granted, see [Set permissions on queries and query folders](../../boards/queries/set-query-permissions.md). -- To add a query chart to a team dashboard, you must be a member of the team or be a member of the **Project Administrators** security group. -- To add a query chart to a project dashboard, you must have created the dashboard or be granted permissions to edit the dashboard, or be a member of the **Project Administrators** security group. -- To view a query chart added to a dashboard, you must have **Read** permissions to the underlying query. If that permission has been denied, then the widget will display with a *Widget failed to load* message. +| Category | Requirements | +|-------------|-------------| +| **Access** | [Project member](../../organizations/accounts/add-organization-users.md) with at least **Basic** access. Users with **Stakeholder** access can't view or create charts from the **Queries** page. They can view charts added to a team dashboard. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). | +| **Permissions** |- To add a query chart to a team dashboard: Member of the team or member of the **Project Administrators** security group.
      - To add a query chart to a project dashboard: Dashboard creator or permissions to **Edit** the dashboard or member of the **Project Administrators** security group.
      - To view a query chart added to a dashboard: **Read** permissions to the underlying query. If that permission is denied, the widget displays a *Widget failed to load* message.
      For more information about other prerequisites regarding service and feature enablement and general data tracking activities, see [Permissions and prerequisites to access Analytics](../analytics/analytics-permissions-prerequisites.md). | +| **Queries** | - Only [flat-list queries](#create-a-flat-list-query) support charts.
      - To add a chart to a dashboard: Save the query to a **Shared Queries** folder. To do so, [get permissions to save queries under a folder](../../boards/queries/set-query-permissions.md). | + ::: moniker-end ::: moniker range="azure-devops" > [!NOTE] -> Users with **Stakeholder** access for a public project have full access to query chart features just like users with **Basic** access. For details, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). +> Users with **Stakeholder** access for a public project have full access to query chart features just like users with **Basic** access. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). ::: moniker-end -::: moniker range="< azure-devops-2020" - -- To create a query chart, you must have **Basic** access or higher. Users with **Stakeholder** access can't view or create charts from the **Queries** page, however, they can view charts added to a team dashboard. For details, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). -- To add a chart to a dashboard, you must save the query to a **Shared Queries** folder. To do that, you must be granted permissions to save queries under a folder. To get permissions granted, see [Set permissions on queries and query folders](../../boards/queries/set-query-permissions.md). -- To add a query chart to a team dashboard, you must be a member of the team or be a member of the **Project Administrators** security group. -- To view a query chart added to a dashboard, you must have **Read** permissions to the underlying query. If that permission has been denied, then the widget will display with a *Widget failed to load* message. -::: moniker-end - -To learn more about dashboard permissions, see [Set dashboard permissions](dashboard-permissions.md). - ### Create a flat-list query -When creating a query to support your chart, follow these guidelines. +When creating a query to support your chart, follow these guidelines. + +- Always select the **Flat list of work items** query type. Other query types aren't supported for charting. For more information, see [Define a flat-list query](../../boards/queries/using-queries.md#flat-list). +- Add those fields to either a query clause or the column options that you want to use within your chart. You can group charts by any field except date-time, free-form text, and tag fields. For example: -- Always select the **Flat list of work items** query type. Other query types aren't supported for charting. For more information, see [Define a query, Define a flat-list query](../../boards/queries/using-queries.md#flat-list). -- Add those fields to either a query clause or the column options that you want to use within your chart. You can group charts by any field except date-time, free-form text, and tag fields. For example: - - To group by Status, include the **State** field - - To group by work assignments, include the **Assigned To** field - - To group by sprints or iterations, include the **Iteration Path** - - To group by team, include the **Node Name** field that displays the leaf node of the Area Path - - To group by a custom field, include it. -- To sum a numeric column, include the corresponding field in your query clause or column options. For more examples of charts created from numeric fields, see [Query by a numeric field](../../boards/queries/query-numeric.md). -- If you plan to add your query to a dashboard, [save your query as a **Shared query**](../../boards/queries/organize-queries.md). + - To group by status, include the **State** field. + - To group by work assignments, include the **Assigned To** field. + - To group by sprints or iterations, include the **Iteration Path**. + - To group by team, include the **Node Name** field that displays the leaf node of the Area Path. + - To group by a custom field, include it. +- To sum a numeric column, include the corresponding field in your query clause or column options. For more examples of charts created from numeric fields, see [Query by numeric fields](../../boards/queries/query-numeric.md). +- If you plan to add your query to a dashboard, [save your query as a Shared query](../../boards/queries/organize-queries.md). ::: moniker range=">= azure-devops-2022" +- You can't group charts by the following field data types: -- You can't group charts by the following field data types: - - ID - - Date-time, such as Created Date, Changed Date - - Plain text, such as Title - - Rich-text, such as Description, Repro Steps - - Tags (You can filter a query using tags, however you can't use tags to configure your chart). + - ID + - Date-time, such as Created Date, Changed Date + - Plain text, such as Title + - Rich-text, such as Description, Repro Steps + - Tags -> [!NOTE] +> [!NOTE] > You can't group a query-based chart by tags, however, you can group a **Chart for Work Items** widget by tags that you add to a dashboard as described in [Configure a chart for work items widget](configure-chart-work-items-widget.md). ::: moniker-end - ::: moniker range="< azure-devops-2022" +- You can't group charts by the following field data types: -- You can't group charts by the following field data types: - - ID - - Date-time, such as Created Date, Changed Date - - Plain text, such as Title - - Rich-text, such as Description, Repro Steps - - Tags (You can filter a query using tags, however you can't use tags to configure your chart). + - ID + - Date-time, such as **Created Date**, **Changed Date** + - Plain text, such as **Title** + - Rich-text, such as **Description**, **Repro Steps** + - Tags (You can filter a query using tags, but you can't use tags to configure your chart) ::: moniker-end #### Display of areas and iterations -When you select **Area Path** or **Iteration Path**, only the leaf node appears in the chart. The leaf node is the last node of the full path. For example, ```Phone``` is the leaf node of ```FabrikamFiber/Fabrikam Website/Phone```. If your query contains a mixed level of leaf nodes, your chart might not reflect expected results. +When you select **Area Path** or **Iteration Path**, only the leaf node appears in the chart. The leaf node is the last node of the full path. For example, `Phone` is the leaf node of `FabrikamFiber/Fabrikam Website/Phone`. If your query contains a mixed level of leaf nodes, your chart might not reflect expected results. -Select the **Node Name** field, the area path leaf node, to see if that improves your results. +Select the **Node Name** field, the area path leaf node, to see if that improves your results. Charts display in browsers that support Scalable Vector Graphics (SVG). Supported browsers include Microsoft Edge, Internet Explorer 9 and later versions, Chrome, Firefox and Safari on Mac. Charts aren't optimized for mobile or touch displays. - ::: moniker range=">= azure-devops-2020" -> [!NOTE] -> Internet Explorer is no longer supported for Azure DevOps Services, nor for Azure DevOps Server 2020.1. +> [!NOTE] +> Internet Explorer is no longer supported for Azure DevOps Services or for Azure DevOps Server 2020.1. ::: moniker-end +#### Sort by Value or Label -#### Sort by Value or Label - -Most charts allow you to choose how you want to sort the data. You can sort by **Value** or **Label** and select **Ascending** or **Descending**. - -- **Value**: Sorts data by the numeric value -- **Label**: Sorts by the label selected for grouping the data. - -#### Limited display of series - -::: moniker range=">= azure-devops-2019" -When a chart contains more than eight or 12 items within the data series, values in the 9 or 13-plus items are consolidated into a set labeled "other"? However, if you increase the chart size through the configurable widget on a dashboard you may increase the series limit. - -![Screenshot of Other category groups data beyond 12 set series.](media/charts/other-12-series.png) - -::: moniker-end - +Most charts allow you to choose how you want to sort the data. You can sort by **Value** or **Label** and select **Ascending** or **Descending**. -::: moniker range="tfs-2018" +- **Value**: Sorts data by the numeric value +- **Label**: Sorts by the label selected for grouping the data -When a chart contains more than seven items within the data series, values in the eight-plus items are consolidated into a set labeled "other"? +#### Limited display of series -![Screenshot of Other category groups data beyond 7 set series.](media/tfs-vso-remaining-category-consolidation-chart.png) +When a chart contains more than 8 or 12 items within the data series, values in the nine or 13-plus items are consolidated into a set labeled *(other)*. However, if you increase the chart size through the configurable widget on a dashboard you can increase the series limit. -::: moniker-end +:::image type="content" source="media/charts/other-12-series.png" alt-text="Screenshot of Other category groups data beyond 12 set series."::: ## Chart availability -- Charts saved under **Shared Queries** are viewable by all team members, except members with **Stakeholder** access, and can be added to dashboards. -- Charts that you create for queries under your **My Queries** folder are visible only to you. -- You can copy and email the URL of any chart page to share it with a project member. +- All team members can view charts saved under **Shared Queries**, except members with **Stakeholder** access. You can add those charts to dashboards. +- Only you can view queries under your **My Queries** folder. +- You can copy and email the URL of any chart page to share it with a project member. - To create similar charts for tests, see [Track test status](../../test/track-test-status.md). ## Create a query-based chart -1. From **Queries**, open the chart editor for a flat list query. You must belong to the Contributors group to create charts. +1. From **Queries**, open the chart editor for a flat-list query. To create charts, belong to the Contributors group. - ::: moniker range=">= azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Screenshot of New chart button.](media/charts/new-chart-new-qe.png) - ::: moniker-end + :::image type="content" source="media/charts/new-chart-new-qe.png" alt-text="Screenshot of the Charts tab with the New chart button."::: - ::: moniker range="tfs-2018" - :::image type="content" source="media/charts-new-chart.png" alt-text="Screenshot of Web portal, Queries page, Chart tab, New chart link."::: - ::: moniker-end - - If you have **Stakeholder** access, the **Charts** and **New Chart** links won't appear. + If you have **Stakeholder** access, the **Charts** and **New Chart** links don't appear. 2. Select the chart type and field for grouping values. When you use pie, bar, and column charts, select a single field to view a count of work items. - ::: moniker range=">= azure-devops-2019" - > [!div class="mx-imgBorder"] - > ![Screenshot of pie chart configure dialog.](media/charts/config-pie-chart-priority-qe.png) - ::: moniker-end - ::: moniker range="tfs-2018" - :::image type="content" source="media/charts-pie-chart-active-bugs-by-priority.png" alt-text="Screenshot of web portal, Queries page, Chart tab, Configure Chart dialog, Configure a Pie chart."::: - ::: moniker-end + :::image type="content" source="media/charts/config-pie-chart-priority-qe.png" alt-text="Screenshot of pie chart configure dialog."::: - If you don't see the field you want in the **Group by** drop-down list, [add the field as a column to the query and save the query](../../boards/backlogs/set-column-options.md). Also, the **Aggregation** options depend on the fields used in the query or those selected from the **Column Options**. + If you don't see the field you want in the **Group by** dropdown list, [add the field as a column to the query and save the query](../../boards/backlogs/set-column-options.md). Also, the **Aggregation** options depend on the fields used in the query or the fields selected from the **Column Options**. - If you receive an error message when you close the chart editor, you need to request [Basic access](../../organizations/security/change-access-levels.md). + If you receive an error message when you close the chart editor, you need to request Basic access. For more information, see [Change access levels](../../organizations/security/change-access-levels.md). 3. To sort the results, select **Value** or **Label** as the sort option and then **Ascending** or **Descending**. - ::: moniker range=">= azure-devops-2019" - To change a color, select a color from the Series set of color pickers. - > [!div class="mx-imgBorder"] - > ![Screenshot of Charts dialog, color series picker.](media/charts/color-series-picker.png) - ::: moniker-end + To change a color, select a color from the Series set of color pickers. - ::: moniker range="tfs-2018" - To change a color, select a color on the chart and pick a new color from the color picker. - ::: moniker-end + :::image type="content" source="media/charts/color-series-picker.png" alt-text="Screenshot of Charts dialog, color series picker."::: Charts automatically update when you edit the query or refresh the query results. - + ## Add a Pie chart -Use a pie chart to show group percentages with six or fewer categories. Good examples of pie charts are: +Use a pie chart to show group percentages with six or fewer categories. Good examples of pie charts are: - Active Bugs Status, group by State -- User Story Status, group by State -- User Story Progress, group by Completed, In Progress, or Cut - -For example, the following query filters User Stories based on the State for Cut, In Progress, and Completed since the start of the year. +- User Story Status, group by State +- User Story Progress, group by Completed, In Progress, or Cut -> [!div class="mx-imgBorder"] -> ![Screenshot of Query Editor, filter User Stories by State.](media/charts/pie-chart-query.png) +For example, the following query filters User Stories based on the State for Cut, In Progress, and Completed since the start of the year. -The pie chart configuration is as shown in the following image. +:::image type="content" source="media/charts/pie-chart-query.png" alt-text="Screenshot of Query Editor, filter User Stories by State."::: -> [!div class="mx-imgBorder"] -> ![Screenshot of Configure chart dialog, Pie chart.](media/charts/pie-chart-configured.png) +The pie chart configuration is as shown in the following image. -The combined query and chart configuration yield the following pie chart. +:::image type="content" source="media/charts/pie-chart-configured.png" alt-text="Screenshot of Configure chart dialog, Pie chart."::: -![Screenshot of Charts, pie chart example.](media/charts/pie-chart-user-stories-progress.png) +The combined query and chart configuration yield the following pie chart. -## Add a Stacked bar chart +:::image type="content" source="media/charts/pie-chart-user-stories-progress.png" alt-text="Screenshot of Charts, pie chart example."::: -A stacked bar chart lets you track progress against two field values. Node Name will display the last leaf within an area path. Use this when you want to show data across teams, and each node corresponds to a team. +## Add a Stacked bar chart -::: moniker range=">= azure-devops-2019" -> [!div class="mx-imgBorder"] -> ![Screenshot of Configure chart dialog, Stacked bar chart.](media/charts/config-stacked-bar-chart-team-qe.png) -::: moniker-end +A stacked bar chart lets you track progress against two field values. Node Name displays the last leaf within an area path. Use this approach when you want to show data across teams and each node corresponds to a team. -::: moniker range="tfs-2018" -:::image type="content" source="media/charts-add-stacked-bar.png" alt-text="Screenshot of web portal, Queries page, Chart tab, Configure Chart dialog, Stacked bar chart."::: -::: moniker-end +:::image type="content" source="media/charts/config-stacked-bar-chart-team-qe.png" alt-text="Screenshot of Configure chart dialog, Stacked bar chart."::: ## Add a Pivot table -The Pivot table displays a table of configurable rows and columns, with columns showing a count of work items or sum of a numeric field. Choose a Pivot table when you want to compare across areas the work being performed. - -The following image shows an example of active bugs assigned to developers and their current state. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Configure Chart dialog, Pivot table.](../../boards/queries/media/numeric/config-pivot-items-developer.png) - -## Add a Trend chart - -Trend charts let you view progress over time. You can select a rolling period ranging from the last week to the last year. - -::: moniker range=">= azure-devops-2019" -> [!div class="mx-imgBorder"] -> ![Screenshot of Configure chart dialog, two week trend chart.](media/charts/config-2-week-trend-chart-bugs.png) -::: moniker-end +The Pivot table displays a table of configurable rows and columns, with columns showing a count of work items or sum of a numeric field. Choose a Pivot table when you want to compare across areas the work being performed. -::: moniker range="tfs-2018" -:::image type="content" source="media/charts-active-bugs-area-trend-2-weeks.png" alt-text="Screenshot of Web portal, Queries page, Chart tab, Configure Chart dialog, two week trend chart."::: -::: moniker-end +The following image shows an example of work item types and their current state. -Trend data is extracted from the work tracking data store. Like most data stores, the schema of the relational database is designed and optimized for the online transactional processing of data. As the tool or plug-in performs an activity, it writes the latest information to the operational store. Therefore, data in the operational store is constantly changing and being updated, and all data is current. +:::image type="content" source="media/charts/configure-pivot-item-state.png" alt-text="Screenshot of Configure Chart dialog, Pivot table."::: +## Add a Trend chart -## Add a Burndown chart +Trend charts display progress over time. You can select a rolling period ranging from the last week to the last year. -Burndown charts are useful for determining how quickly work is progressing based on a numeric field value, such as Story Points, Effort, or Remaining Work, or on a count of work items. +:::image type="content" source="media/charts/config-2-week-trend-chart-bugs.png" alt-text="Screenshot of Configure chart dialog, two week trend chart."::: -To create a burndown chart, make sure to add the numeric field you want to your query. To view a burndown chart of tasks, select the **Sum** operator for **Remaining Work**. +Trend data comes from the work tracking data store. The schema of the relational database is designed and optimized for online transactional processing of data. As the tool or plug-in performs an activity, it writes the latest information to the operational store. Data in the operational store constantly changes and updates. All data is current. -::: moniker range=">= azure-devops-2019" -> [!div class="mx-imgBorder"] -> ![Screenshot of Configure chart dialog, Remaining work for past four weeks.](media/charts/config-remaining-work-trend-chart.png) +## Add a Burndown chart -In addition to query-based burndown charts, you can [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). +Burndown charts help determine how quickly work is progressing based on a numeric field value, such as Story Points, Effort, or Remaining Work, or on a count of work items. -::: moniker-end +To create a burndown chart, add the numeric field you want to your query. To view a burndown chart of tasks, select the **Sum** operator for **Remaining Work**. -::: moniker range="tfs-2018" -:::image type="content" source="media/create-burndown-trend-sum-chart.png" alt-text="Screenshot of Web portal, Queries page, Chart tab, Configure Chart dialog, Trend chart for the past four weeks."::: -::: moniker-end +:::image type="content" source="media/charts/config-remaining-work-trend-chart.png" alt-text="Screenshot of Configure chart dialog, Remaining work for past four weeks."::: +In addition to query-based burndown charts, you can [configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). -## Add chart to a dashboard +## Add a chart to a dashboard -A chart added to a dashboard is added through the addition of a **Chart for Work Items** widget. You can add the chart to a dashboard as shown in the following procedure, or by adding the **Chart for Work Items** widget directly. To learn more, see [Configure a chart for work items widget](configure-chart-work-items-widget.md). +To add a chart to a dashboard, do the following steps: -> [!TIP] -> All query charts are limited in size. However, charts added to a dashboard can be re-sized and re-configured by opening the **Chart for Work Items** widget used to display them. +1. Add a **Chart for Work Items** widget. You can add the chart to a dashboard as shown in the following procedure, or by adding the **Chart for Work Items** widget directly. For more information, see [Configure a chart for work items widget](configure-chart-work-items-widget.md). -- Select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the chart you want to add, and select **Add to dashboard**. + > [!TIP] + > All query charts are limited in size. You can resize and configure charts that you add to a dashboard by opening the **Chart for Work Items** widget used to display them. -::: moniker range=">= azure-devops-2019" -> [!div class="mx-imgBorder"] -> ![Chart context menu, Add to dashboard option](media/charts/add-chart-to-dashboard-qe.png) +2. Select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the chart you want to add, and select **Add to dashboard**. -The **Add to dashboard** menu option is only available for queries that have been saved to a **Shared Queries** folder. + :::image type="content" source="media/charts/add-chart-to-dashboard-qe.png" alt-text="Screenshot shows the Chart context menu, Add to dashboard option."::: -In the dialog that opens, select the dashboard to add the chart to. + Only queries that are saved to a **Shared Queries** folder have the **Add to dashboard** menu option. -> [!div class="mx-imgBorder"] -> ![Select a dashboard dialog](media/charts/select-dashboard-dialog.png) -::: moniker-end +3. In the dialog that opens, select the dashboard to add the chart to. -::: moniker range="tfs-2018" -![Chart context menu, add to a team dashboard](media/pin-chart-to-a-dashboard.png) -::: moniker-end + :::image type="content" source="media/charts/select-dashboard-dialog.png" alt-text="Screenshot shows the Select a dashboard dialog."::: -To add other types of charts, such as test results and build summary charts, see [Add widgets and chart to a dashboard](add-widget-to-dashboard.md). +To add other types of charts, such as test results and build summary charts, see [Add widgets and chart to a dashboard](add-widget-to-dashboard.md). ::: moniker range="< azure-devops-2022" -## Query-based charts versus Excel-generated PivotCharts +## Query-based charts versus Excel-generated PivotCharts -Query-based charts generate data from the work item tracking data store and therefore display the most recent data. [Excel PivotCharts](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports) access data published to the Analysis Services cube, which is refreshed every two hours by default. Excel charts require your project's project collection is configured with SQL Server Reporting Services and Analysis Services. +Query-based charts generate data from the work item tracking data store. The charts display the most recent data. [Excel PivotCharts](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports) access data published to the Analysis Services cube, which is refreshed every two hours by default. Excel charts require that your project's project collection is configured with SQL Server Reporting Services and Analysis Services. ::: moniker-end ## Related articles -- [Example query charts](../../boards/queries/example-query-charts.md) +- [Review example query charts](../../boards/queries/example-query-charts.md) - [Configure a chart for work items widget](configure-chart-work-items-widget.md) -- [FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml) -- [Cumulative flow diagram](cumulative-flow.md) -- [Team velocity](team-velocity.md) -- [View/configure sprint burndown](configure-sprint-burndown.md) -- [Track test status](../../test/track-test-status.md) -- [Add widgets and chart to a dashboard](add-widget-to-dashboard.md) -- [Widget catalog](widget-catalog.md) +- [Read FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml) +- [View and configure a Cumulative Flow Diagram](cumulative-flow.md) +- [View and configure team velocity](team-velocity.md) +- [Configure and monitor sprint burndown](configure-sprint-burndown.md) +- [Track test status](../../test/track-test-status.md) +- [Add widgets to a dashboard](add-widget-to-dashboard.md) +- [View the Widget catalog](widget-catalog.md) diff --git a/docs/report/dashboards/configure-burndown-burnup-widgets.md b/docs/report/dashboards/configure-burndown-burnup-widgets.md index 53f902fcb16..3868b9fb432 100644 --- a/docs/report/dashboards/configure-burndown-burnup-widgets.md +++ b/docs/report/dashboards/configure-burndown-burnup-widgets.md @@ -1,48 +1,46 @@ --- title: Configure burndown or burnup widget -titleSuffix: Azure DevOps +titleSuffix: Azure DevOps description: Learn how to configure a burndown or burnup widget to create charts that you add to a dashboard to track progress across one or more teams in Azure DevOps. ms.custom: dashboards ms.subservice: azure-devops-analytics -ms.topic: tutorial +ms.topic: how-to ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' -ms.date: 06/09/2023 +monikerRange: "<=azure-devops" +ms.date: 09/25/2024 +#customer intent: As a team member, I want to create burndown and burnup charts that show team progress and add them as widgets to a dashboard. --- -# Configure a burndown or burnup widget +# Configure a burndown or burnup widget [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -The burndown and burnup widgets give you flexibility to create charts for any type of scope or number of teams within specified time periods. Burndown charts focus on remaining work, while burnup charts focus on completed work. Both chart types help your team determine whether you're on track to complete the set of work by the end date. For an overview of all burndown/burnup charts available to you, see [Burndown and burnup guidance](burndown-guidance.md). +The burndown and burnup widgets give you flexibility to create charts for any type of scope or number of teams in specified time periods. *Burndown charts* focus on remaining work. *Burnup charts* focus on completed work. Both chart types help your team determine whether you're on track to complete your work by the end date. For an overview of all burndown and burnup charts available to you, see [Burndown and burnup guidance](burndown-guidance.md). -**Burndown widget configured to display a release burndown** -:::image type="content" source="media/burndown-widget/burndownup-release-burndown.png" alt-text="Screenshot of release burndown widget."::: +This diagram shows a Burndown widget configured to display a release burndown. -## Prerequisites +:::image type="content" source="media/burndown-widget/burndownup-release-burndown.png" alt-text="Screenshot of a release burndown widget."::: -[!INCLUDE [temp](../includes/analytics-widgets-prerequisites.md)] +## Prerequisites + +[!INCLUDE [analytics-widgets-prerequisites](../includes/analytics-widgets-prerequisites.md)] + +## Add the widget to your dashboard + +Use the following procedure to add a burndown or burnup widget to your dashboard. -## Add the widget to your dashboard - ::: moniker range=">= azure-devops-2020" -1. Sign in to your organization (``https://dev.azure.com/{yourorganization}``). -2. Go to your project, and then select **Dashboards**, and then :::image type="icon" source="../../boards/backlogs/office/media/icons/edit.png" border="false"::: **Edit**. - - :::image type="content" source="media/burndown-widget/select-dashboards-edit.png" alt-text="Screenshot showing sequence of selection for Dashboards, Edit function."::: +1. Sign in to your organization (`https://dev.azure.com/{yourorganization}`). +1. Go to your project. Select **Dashboards**, and then :::image type="icon" source="../../boards/backlogs/office/media/icons/edit.png" border="false"::: **Edit**. -3. Select a widget, and then **Add**. - - :::image type="content" source="media/burndown-widget/add-widget.png" alt-text="Screenshot showing widget selection pane and blue Add button."::: -::: moniker-end + :::image type="content" source="media/burndown-widget/select-dashboards-edit.png" alt-text="Screenshot showing sequence of selection for Dashboards, Edit function." lightbox="media/burndown-widget/select-dashboards-edit.png"::: + +1. Select a widget, and then **Add**. -::: moniker range="azure-devops-2019" + :::image type="content" source="media/burndown-widget/add-widget.png" alt-text="Screenshot showing widget selection pane and blue Add button."::: -1. [Enable or install Analytics](analytics-extension.md). -2. [Add the widget to your dashboard](./add-widget-to-dashboard.md). -3. Select :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: **More actions** and **Configure**. ::: moniker-end ## Configure burndown or burnup widget @@ -50,70 +48,74 @@ The burndown and burnup widgets give you flexibility to create charts for any ty Do the following steps to configure both widget types. The only difference between the burndown and burnup widgets is that the burnup widget plots *work completed* and the burndown widget plots *work remaining*. For more information, see how to [interpret a burndown or burnup chart](#interpret-a-burndown-or-burnup-chart), later in this article. 1. On the widget, select :::image type="icon" source="../../boards/media/icons/gear_icon.png" border="false"::: **Configure**. -2. Complete configuration information, described in the following table, and then select **Save**. +1. Complete configuration information, described in the following table, and then select **Save**. -::: moniker range="= azure-devops" +:::moniker range="=azure-devops-2022" -|Configuration category |Guidance| -|-----------|-----------| -|Teams | To track progress across teams, add more teams. You can select teams from other projects, but the lists of selectable backlogs, work item types, and fields are based on your current project. Tracking across multiple projects only works if the [process](../..//boards/work-items/guidance/choose-process.md) for those projects is the same, or at least similar.| -| Work items| **Backlog** includes all the work item types configured for that backlog. If your project is customized using a [Hosted XML process](../../organizations/settings/work/hosted-xml-process-model.md) and has a customized bug work item category name, then the burndown/burnup widgets can't query for work items within that category. To query for bugs, the customized bug work item type must belong to the default **Bug category**, reference name `Microsoft.BugCategory`.| -|Field criteria| Select field criteria to limit the work items that appear in the chart. Filtering is based on values assigned to fields as defined for each work item on the date within the tracking period. For more information, see [Filters that apply to historical data](../powerbi/analytics-historical-filtering.md).
      Analytics-based charts are built based on the `WorkItemsSnapshot` EntitySet. Snapshot entity types are modeled as daily snapshots. Data aggregates based on assignments made as of the date they're assigned. So, if you want to filter a burndown/burnup widget based on field or tag assignments, assign them prior to the period you want to monitor. Otherwise, the widget doesn't recognize them until the date on which they're applied. You can filter on a null value for the **Field criteria**, which is consistent with a query using the same field criteria. | -|Burndown on |Choose how you want to calculate burndown by **Count** of work items or by **Sum** based on a selected field. You can select from standard or custom fields of integer or decimal data type, such as **Story Points**, **Effort**, or **Remaining Work**. Burndown works best when you aggregate size fields like Story Points. If you choose to burndown on fields that change during the sprint, like Remaining Work for Tasks, the calculation of "Items not Estimated" grows as items get closed. | -|Time period |- **Start Date**: Determines the original scope baseline. The chart burns down from the original scope.
      - **% Complete** and **Total Scope Increase**: Calculated based on your original scope.
      - **End Date**: Specifies the target date of completion. Your goal is to burndown the original scope of work by the End Date. -|Plot interval |Select the intervals to plot between the **Start Date** and **End Date**. Average burndown is based on the selected interval. After you select the Start Date, set Plot burndown by to Iteration. The Average Burndown assumes that every interval is the same length and that the interval between the Start Date and the first month is a full month, even if the length of time between Start Date and the first month's end date doesn't match your typical length of a month. For best results, enter a Start Date that is the same as the first month's start date, which is also true when plotting by weekly intervals. | -|Advanced features |- **Show burndown**: Displays both the historical and projected future burndown.
      - **Show total scope**: Displays both the historical and projected scope increase.
      - **Show completed work**: It displays remaining work and completed work as stack bar.
      - **Plot remaining using work item type color**: Displays remaining work based on the work item type color, rather than the default blue color. If multiple work items are included, then it stacks colors by work item type. | +[!INCLUDE [feature-added-2022-1](../../includes/feature-added-2022-1.md)] ::: moniker-end -::: moniker range="< azure-devops" +::: moniker range=">= azure-devops-2022" + +| Configuration category | Guidance | +|:-----------|:-----------| +| Teams | To track progress across teams, add more teams. You can select teams from other projects, but the lists of selectable backlogs, work item types, and fields are based on your current project. Tracking across multiple projects only works if the [process](../..//boards/work-items/guidance/choose-process.md) for those projects is the same, or at least similar. | +| Work items | **Backlog** includes all the work item types configured for that backlog. If your project is customized using a [Hosted XML process](../../organizations/settings/work/hosted-xml-process-model.md) and has a customized bug work item category name, the burndown and burnup widgets can't query for work items in that category. To query for bugs, the customized bug work item type must belong to the default **Bug category**, reference name `Microsoft.BugCategory`. | +| Field criteria | Select field criteria to limit the work items that appear in the chart. Filtering is based on values assigned to fields as defined for each work item on the date within the tracking period. For more information, see [Filters that apply to historical data](../powerbi/analytics-historical-filtering.md).
      Analytics-based charts are built based on the `WorkItemsSnapshot` entity set. Snapshot entity types are modeled as daily snapshots. Data aggregates based on assignments made as of the date they're assigned. So, if you want to filter a burndown or burnup widget based on field or tag assignments, assign them previous to the period you want to monitor. Otherwise, the widget doesn't recognize them until the date on which they're applied. You can filter on a null value for the **Field criteria**, which is consistent with a query using the same field criteria. | +| Burndown on | Choose how you want to calculate burndown by **Count** of work items or by **Sum** based on a selected field. You can select from standard or custom fields of integer or decimal data type, such as **Story Points**, **Effort**, or **Remaining Work**. Burndown works best when you aggregate size fields like Story Points. If you choose to burndown on fields that change during the sprint, like **Remaining Work for Tasks**, the calculation of *Items not Estimated* grows as items get closed. | +| Time period |- **Start Date**: Determines the original scope baseline. The chart burns down from the original scope.
      - **% Complete** and **Total Scope Increase**: Calculated based on your original scope.
      - **End Date**: Specifies the target date of completion. Your goal is to burndown the original scope of work by the End Date. | +| Plot interval | Select the intervals to plot between the **Start Date** and **End Date**. Average burndown is based on the selected interval. After you select the start date, set **Plot burndown by** to **Iteration**. The Average Burndown assumes that every interval is the same length and that the interval between the start date and the first month is a full month. Even if the length of time between start date and the first month's end date doesn't match your typical length of a month, the length is the same. For best results, enter a **Start Date** that is the same as the first month's start date, which is also true when plotting by weekly intervals. | +| Advanced features |- **Show burndown**: Displays both the historical and projected future burndown.
      - **Show total scope**: Displays both the historical and projected scope increase.
      - **Show completed work**: It displays remaining work and completed work as stack bar.
      - **Plot remaining using work item type color**: Displays remaining work based on the work item type color, rather than the default blue color. If multiple work items are included, then it stacks colors by work item type.| + +::: moniker-end +::: moniker range="< azure-devops-2022" -|Configuration category |Guidance| -|:----------------------|:-------| -|Teams | You can select teams from other projects, but the lists of selectable backlogs, work item types, and fields are based on your current project. You can only track across multiple projects if the [process](../..//boards/work-items/guidance/choose-process.md) for those projects is the same.| -|Work items | **Backlog** includes all the work item types configured for that backlog. If you select the **Stories** backlog, you have another option: **Include bugs on the Stories backlog**. Enter a checkmark in the box to include bugs along with user stories in your burndown. This option's available for the PBI Backlog for Scrum projects and the Requirements backlog for CMMI projects. If your project is customized using a [Hosted XML process](../../organizations/settings/work/hosted-xml-process-model.md) and has a customized bug work item category name, then the burndown/burnup widgets can't query for work items within that category. To query for bugs, the customized bug work item type must belong to the default **Bug category**, reference name `Microsoft.BugCategory`.| -|Field criteria| Select field criteria to limit the work items that appear in the chart. Filtering is based on values assigned to fields as defined for each work item on the date within the tracking period. For more information, see [Filters that apply to historical data](../powerbi/analytics-historical-filtering.md).
      Analytics-based charts are built based on the `WorkItemsSnapshot` EntitySet. Snapshot entity types are modeled as daily snapshots. Data aggregates based on assignments made as of the date they're assigned. So, if you want to filter a burndown/burnup widget based on field or tag assignments, assign them prior to the period you want to monitor. Otherwise, the widget doesn't recognize them until the date on which they're applied. You can filter on a null value for the **Field criteria**, which is consistent with a query using the same field criteria. | -|Burndown on |Choose how you want to calculate burndown by **Count** of work items or by **Sum** based on a selected field. You can select from standard or custom fields of integer or decimal data type, such as **Story Points**, **Effort**, or **Remaining Work**. Burndown works best when you aggregate size fields like Story Points. If you choose to burndown on fields that change during the sprint, like Remaining Work for Tasks, the calculation of "Items not Estimated" grows as items get closed. | -|Time period |- **Start Date**: Determines the original scope baseline. The chart burns down from the original scope.
      - **% Complete** and **Total Scope Increase**: Calculated based on your original scope.
      - **End Date**: Specifies the target date of completion. Your goal is to burndown the original scope of work by the End Date. | -|Plot interval |Average burndown gets based on the selected interval, which can be daily, weekly, monthly, or based on an iteration schedule. The Average Burndown assumes that every interval is the same length. For example, the interval between the Start Date and the first month is a full month, even if the length of time between Start Date and the first month's end date doesn't match your typical length of a month. For best results, enter a Start Date that is the same as the first month's start date, which is also true for weekly intervals. | -|Advanced features |- **Show burndown**: Displays both the historical and projected future. burndown.
      - **Show total scope**: Displays both the historical and projected scope increase.
      - **Show completed work**: Displays remaining work and completed work as stack bar.
      - **Plot remaining using work item type color**: Displays remaining work based on the work item type color, rather than the default blue color. If multiple work items are included, then it stacks colors by work item type. | +| Configuration category | Guidance | +|:----------------------|:-------| +| Teams | You can select teams from other projects, but the lists of selectable backlogs, work item types, and fields are based on your current project. You can only track across multiple projects if the [process](../..//boards/work-items/guidance/choose-process.md) for those projects is the same. | +| Work items | **Backlog** includes all the work item types configured for that backlog. If you select the **Stories** backlog, you have another option: **Include bugs on the Stories backlog**. Enter a checkmark in the box to include bugs along with user stories in your burndown. This option's available for the PBI Backlog for Scrum projects and the Requirements backlog for CMMI projects. If your project is customized using a [Hosted XML process](../../organizations/settings/work/hosted-xml-process-model.md) and has a customized bug work item category name, then the burndown and burnup widgets can't query for work items in that category. To query for bugs, the customized bug work item type must belong to the default **Bug category**, reference name `Microsoft.BugCategory`. | +| Field criteria | Select field criteria to limit the work items that appear in the chart. Filtering is based on values assigned to fields as defined for each work item on the date within the tracking period. For more information, see [Filters that apply to historical data](../powerbi/analytics-historical-filtering.md).
      Analytics-based charts are built based on the `WorkItemsSnapshot` entity set. Snapshot entity types are modeled as daily snapshots. Data aggregates based on assignments made as of the date they're assigned. So, if you want to filter a burndown or burnup widget based on field or tag assignments, assign them previous to the period you want to monitor. Otherwise, the widget doesn't recognize them until the date on which they're applied. You can filter on a null value for the **Field criteria**, which is consistent with a query using the same field criteria. | +| Burndown on | Choose how you want to calculate burndown by **Count** of work items or by **Sum** based on a selected field. You can select from standard or custom fields of integer or decimal data type, such as **Story Points**, **Effort**, or **Remaining Work**. Burndown works best when you aggregate size fields like Story Points. If you choose to burndown on fields that change during the sprint, like **Remaining Work for Tasks**, the calculation of "Items not Estimated" grows as items get closed. | +| Time period |- **Start Date**: Determines the original scope baseline. The chart burns down from the original scope.
      - **% Complete** and **Total Scope Increase**: Calculated based on your original scope.
      - **End Date**: Specifies the target date of completion. Your goal is to burndown the original scope of work by the End Date. | +| Plot interval | Average burndown gets based on the selected interval, which can be daily, weekly, monthly, or based on an iteration schedule. The Average Burndown assumes that every interval is the same length. For example, the interval between the start date and the first month is a full month, even if the length of time between Start Date and the first month's end date doesn't match your typical length of a month. For best results, enter a Start Date that is the same as the first month's start date, which is also true for weekly intervals. | +| Advanced features |- **Show burndown**: Displays both the historical and projected future. burndown.
      - **Show total scope**: Displays both the historical and projected scope increase.
      - **Show completed work**: Displays remaining work and completed work as stack bar.
      - **Plot remaining using work item type color**: Displays remaining work based on the work item type color, rather than the default blue color. If multiple work items are included, then it stacks colors by work item type. | ::: moniker-end ## Interpret a burndown or burnup chart -Your team can get immediate insight as to their progress and learn about their rhythm and behavior. Most burndown lines aren't straight lines. The team never moves at exactly one fixed velocity. Scope increases occur over time. For example, if your projected completion date moves, you may want to ask one of these questions: -* *Are we adding too much scope?* -* *Is the average burn rate changing, and if so, why?* +Your team can get immediate insight as to their progress and learn about their rhythm and behavior. Most burndown lines aren't straight lines. The team never moves at exactly one fixed velocity. Scope increases occur over time. For example, if your projected completion date moves, you might want to ask one of these questions: + +- *Are we adding too much scope?* +- *Is the average burn rate changing, and if so, why?* -Burndown charts also help teams understand risks to their release. If the projected end date exceeds the release target date, teams may need to reduce scope or lengthen the project. Burndown can also indicate that progress is greater than expected, providing the uncommon, but wonderful option of adding scope. +Burndown charts also help teams understand risks to their release. If the projected end date exceeds the release target date, teams might need to reduce scope or lengthen the project. Burndown can also indicate that progress is greater than expected, providing the uncommon, but wonderful option of adding scope. -As the following diagram shows, charts based on the burndown/burnup widgets provide many calculated elements. +As the following diagram shows, charts based on the burndown or burnup widgets provide many calculated elements. -:::image type="content" source="media/burndown-widget/burndownup-release-burndown-with-markup.png" alt-text="Conceptual image showing burndown/burnup widget elements."::: +:::image type="content" source="media/burndown-widget/burndownup-release-burndown-with-markup.png" alt-text="Screenshot annotated with labels about burndown or burnup widget elements."::: -| Element | Description| -|---------|------------| -|**Date range**|The start and end date of the burndown. When burndown gets plotted by iterations, the end date is the end of the last iteration. | -|**Main metric**|Current remaining work based on the selected burndown method.| -|**% Completed**|The percentage of work completed based on original scope. Select **% Completed** to see the full list of completed work items.| -|**Average burndown**|Average work completed per interval or iteration.| -|**Items not estimated**|Shows only when burning down on the Sum of a field. It represents the current number of items that don't have a value in the selected **Burndown on** field. Select the number to see a full list of work items without estimates.| -|**Total Scope Increase** |Shows how much work was added to the original scope since the burndown started.| -|**Projected completion** |Calculates the projected completion date based on the remaining work and historical burndown and scope increase rates. If the projected completion date is before the specified **End Date**, it draws a vertical line on the interval when the work should complete. If the projected completion date is after the specified **End Date**, it displays the number of other intervals/iterations needed to complete the work.| -|**Original Scope** |Original scope is all remaining work since the specified **Start Date**. The chart burns down from the original scope. **% Complete** and **Total Scope Increase** are calculated based on your original scope.| -|**Total Scope** |Represents to the total scope of the burndown. The plotted points include both completed and remaining work. The total scope line indicates the scope change of your project. For past data points, the plotted total scope represents actual total scope as of the end of each interval/iteration. For future data points, the plotted total scope represents a projected scope change, based on past scope changes.| -|**Burndown**|Represents the burndown. The burndown line tells you how fast you're burning down the work. For past data points, the plotted burndown represents actual burndown as of the end of each interval/iteration. For future data points, the plotted burndown represents a projected burndown, based on past burndown. +| Element | Description | +|:--------|:------------| +| **Date range** | The start and end date of the burndown. When burndown gets plotted by iterations, the end date is the end of the last iteration. | +| **Main metric** | Current remaining work based on the selected burndown method. | +| **% Completed** | The percentage of work completed based on original scope. Select **% Completed** to see the full list of completed work items. | +| **Average burndown** | Average work completed per interval or iteration. | +| **Items not estimated** | Shows only when burning down on the Sum of a field. It represents the current number of items that don't have a value in the selected **Burndown on** field. Select the number to see a full list of work items without estimates. | +| **Total Scope Increase** | Shows how much work was added to the original scope since the burndown started.| +| **Projected completion** | Calculates the projected completion date based on the remaining work and historical burndown and scope increase rates. If the projected completion date is before the specified **End Date**, it draws a vertical line on the interval when the work should complete. If the projected completion date is after the specified **End Date**, it displays the number of other intervals or iterations needed to complete the work. | +| **Original Scope** | Original scope is all remaining work since the specified **Start Date**. The chart burns down from the original scope. **% Complete** and **Total Scope Increase** are calculated based on your original scope. | +| **Total Scope** | Represents to the total scope of the burndown. The plotted points include both completed and remaining work. The total scope line indicates the scope change of your project. For past data points, the plotted total scope represents actual total scope as of the end of each interval or iteration. For future data points, the plotted total scope represents a projected scope change, based on past scope changes. | +| **Burndown** | Represents the burndown. The burndown line tells you how fast you're burning down the work. For past data points, the plotted burndown represents actual burndown as of the end of each interval or iteration. For future data points, the plotted burndown represents a projected burndown, based on past burndown. | [!INCLUDE [note-delete-area-paths](../../boards/includes/note-delete-area-paths.md)] -## Next steps +## Related articles > [!div class="nextstepaction"] -> [Burndown and burnup guidance](burndown-guidance.md) - -## Related articles +> [Burndown and burnup guidance](burndown-guidance.md) - [Configure and monitor sprint burndown](configure-sprint-burndown.md) - [Define iteration paths or sprints) and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md) diff --git a/docs/report/dashboards/configure-chart-work-items-widget.md b/docs/report/dashboards/configure-chart-work-items-widget.md index 9bc8caaddc0..d8491d34c22 100644 --- a/docs/report/dashboards/configure-chart-work-items-widget.md +++ b/docs/report/dashboards/configure-chart-work-items-widget.md @@ -22,37 +22,27 @@ To view a chart on a dashboard, you can start from **Queries>Charts** page and c The only task you can accomplish from the **Chart for Work Items** widget that you can't from the **Queries>Charts** page is grouping work items by Tags. This feature is supported for Azure DevOps server 2022 and later versions. ::: moniker-end - ## Prerequisites -Prerequisites to meet include having the necessary permissions, defining and saving a flat-list query under the **Shared Queries** folder, and creating the dashboard where you want to add the widget. - -### Permissions - -By default, users with **Basic** access or higher can create charts. Users with **Stakeholder** access can't view or create charts from the **Queries** page, however, they can view charts added to a team dashboard. For details, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). - -::: moniker range=">= azure-devops-2020" - -- To save a query to a **Shared Queries** folder, you must be granted permissions to save queries under a folder. To get permissions granted, see [Set permissions on queries and query folders](../../boards/queries/set-query-permissions.md). -- To add a widget to a team dashboard, you must be a member of the team or be a member of the **Project Administrators** security group. -- To add a widget to a project dashboard, you must have created the dashboard or be granted permissions to edit the dashboard, or be a member of the **Project Administrators** security group. -- To view a query-based widget added to a dashboard, you must have **Read** permissions to the underlying query. If that permission has been denied, then the widget will display with a *Widget failed to load* message. -::: moniker-end - ::: moniker range="azure-devops" + > [!NOTE] -> Users with **Stakeholder** access for a public project have full access to query chart features just like users with **Basic** access. For details, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). +> Users with **Stakeholder** access for a public project have full access to query chart features just like users with **Basic** access. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). ::: moniker-end -::: moniker range="< azure-devops-2020" +::: moniker range=">= azure-devops-2020" + +| Category | Requirements | +|-------------|-------------| +| **Access** | [Project member](../../organizations/accounts/add-organization-users.md) with at least **Basic** access. Users with **Stakeholder** access can't view or create charts from the **Queries** page. They can view charts added to a team dashboard. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). | +| **Permissions** |- By default, users with at least **Basic** access can create charts. Users with **Stakeholder** access can't view or create charts from the **Queries** page, however, they can view charts added to a team dashboard. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md).
      - To save a query to a **Shared Queries** folder: Permissions to save queries under a folder. For more information, see [Set permissions on queries and query folders](../../boards/queries/set-query-permissions.md).
      - To add a widget to a team dashboard: Member of the team or member of the **Project Administrators** security group.
      - To add a widget to a project dashboard: Dashboard creator or **Edit** permissions for the dashboard, or member of the **Project Administrators** security group.
      - To view a query-based widget added to a dashboard: **Read** permissions to the underlying query. If that permission is denied, the widget displays a *Widget failed to load* message. | +| **Queries** | - Only [flat-list queries](charts.md#create-a-flat-list-query) support charts.
      - To add a chart to a dashboard: Save the query to a **Shared Queries** folder. To do so, [get permissions to save queries under a folder](../../boards/queries/set-query-permissions.md). | -- To save a query to a **Shared Queries** folder, you must be granted permissions to save queries under a folder. To get permissions granted, see [Set permissions on queries and query folders](../../boards/queries/set-query-permissions.md). -- To add a widget to a team dashboard, you must be a member of the team or be a member of the **Project Administrators** security group. -- To view a query-based widget added to a dashboard, you must have **Read** permissions to the underlying query. If that permission has been denied, then the widget will display with a *Widget failed to load* message. ::: moniker-end + -To learn more about dashboard permissions, see [Set dashboard permissions](dashboard-permissions.md). +For more information about dashboard permissions, see [Set dashboard permissions](dashboard-permissions.md). ### Define and save a flat-list query @@ -68,7 +58,7 @@ Prior to adding a widget to a dashboard, you must first add the dashboard to the ## Add the Chart for Work Items widget to a dashboard -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" 1. From the web portal, open the dashboard you want to add the chart to. @@ -106,83 +96,6 @@ Prior to adding a widget to a dashboard, you must first add the dashboard to the 8. When you're finished with your changes, select **Done Editing** to exit dashboard edit mode. ::: moniker-end -::: moniker range="azure-devops-2019" - -1. From the web portal, open the dashboard you want to add the chart to. - -2. To add widgets to the dashboard, select :::image type="icon" source="media/icons/edit-icon.png" border="false"::: **Edit** to open the widget catalog. - - > [!NOTE] - > If you don't see the :::image type="icon" source="media/icons/edit-icon.png" border="false"::: **Edit** option, then you need to [get permissions to edit the dashboard](dashboard-permissions.md). - -3. Select the **Chart for Work Items** widget and then select **Add** or drag it onto the dashboard. - - ![Web portal, Dashboards page, Widget catalog, Chart for work items widget](media/widget-chart-work-query.png) - -4. To configure the widget, select the widget's :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: **More actions** and choose the :::image type="icon" source="../../media/icons/gear_icon.png" border="false"::: **Configure** option. - - :::image type="content" source="media/chart-work-items/widget-more-actions-menu.png" alt-text="Screenshot of dashboard widget More actions menu options."::: - - The Configuration dialog opens. - -5. Enter a **Title**, select the **Size**, and then select the flat-list **Query** on which the chart is based. Next, choose the **Chart type**. - - :::image type="content" source="media/chart-work-items/configure-chart-widget.png" alt-text="Configuration dialog for chart work items widget, Azure DevOps Server 2019."::: - - Based on your chart type, specify values for the remaining fields. Change a chart color simply by choosing another color from those shown. For additional guidance on choosing and configuring specific chart types, see [Track progress with status and trend query-based charts](charts.md). - -6. After you save your changes, you'll see the new chart has been added to the dashboard. - - ![Chart of work items widget, configure dialog](media/charts/pivot-chart-from-query.png) - - > [!TIP] - > If the chart doesn't display all the rows or columns you want, try changing the chart **Size**. Pivot tables and other chart types will display more data based on the area provided on the dashboard. - -7. Drag the tile anywhere on the dashboard to put it where you want it. - -8. When you're finished with your changes, select **Done Editing** to exit dashboard edit mode. -::: moniker-end - - - -::: moniker range="tfs-2018" - -1. From the web portal, open the [team dashboard](dashboards.md) you want to add the chart to. - -2. To add widgets to the dashboard, select :::image type="icon" source="media/icons/edit-icon.png" border="false"::: **Edit**. The widget catalog will automatically open. Add all the widgets that you want and drag their tiles into the sequence you want. - - If you don't see these icons, then you need to be added as a [team administrator](../../organizations/settings/add-team-administrator.md) or a member of the Project Administrators group. - -3. Select the **Chart for work items** widget and then select **Add**. - - Web portal, Dashboards page, Widget catalog, Chart for work items widget - -4. Select the widget's :::image type="icon" source="media/icons/gear-icon.png" border="false"::: gear icon to open the configuration dialog. - - Web portal, Dashboards page, Widget catalog, Chart for work items widget, Configuration dialog - -5. Give the chart a title, select the flat list query on which the chart is based, and choose the chart type. For guidance on choosing the chart type, see [Track progress with status and trend query-based charts ](charts.md). - - Based on your chart type, specify values for the remaining fields. Change a chart color simply by choosing another color from those shown. - - > [!NOTE] - > All rules for configuring charts described previously in this article apply to configuring the chart for work items widget. - -6. After you save your changes, you'll see the new chart has been added to the dashboard. - - ![Chart of work items widget, configure dialog](media/charts-chart-wit-widget-configured.png) - - > [!TIP] - > If the chart doesn't display all the rows or columns you want, try changing the chart **Size**. Pivot tables and other chart types will display more data based on the area provided on the dashboard. - -7. Drag the tile anywhere on the dashboard to put it where you want it. - -8. When you're finished with your changes, select ![Exit edit-dashboard-mode icon](media/exit-edit-dashboard-mode-icon.png) to exit dashboard editing. - -::: moniker-end - - - ::: moniker range=">= azure-devops-2022" @@ -196,7 +109,7 @@ To group a chart by tags, perform the same steps provided in the previous sectio :::image type="content" source="media/charts/configure-chart-widget-tags.png" alt-text="Screenshot of Chart by Work Items, Configure, Group by Tags."::: -To learn more about using tags, see [Add tags to work items](../../boards/queries/add-tags-to-work-items.md). +For more information about using tags, see [Add tags to work items](../../boards/queries/add-tags-to-work-items.md). ::: moniker-end diff --git a/docs/report/dashboards/configure-sprint-burndown.md b/docs/report/dashboards/configure-sprint-burndown.md index 045a317a311..57b0c2d3a13 100644 --- a/docs/report/dashboards/configure-sprint-burndown.md +++ b/docs/report/dashboards/configure-sprint-burndown.md @@ -7,186 +7,103 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: tutorial -monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +monikerRange: "<=azure-devops" +ms.date: 03/12/2025 +#customer intent: As a team member or leader, I want to monitor sprint burndown information to see whether my team is on track to complete our sprint plan. --- -# Configure and monitor sprint burndown - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +# Configure and monitor sprint burndown +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] ::: moniker range=">= azure-devops-2020" -Throughout your sprint, you can monitor the sprint burndown report to determine if your team is on track to complete its [sprint plan](../../boards/sprints/assign-work-sprint.md). There are two sprint accessible burndown charts: the in-context Burndown Trend report viewable from a team sprint backlog and the Sprint Burndown widget you can add to a dashboard. - -Both the report and the widget derive data from [Analytics](../powerbi/what-is-analytics.md). They support monitoring burndown based on a count of work items or a sum of Story Points/Size/Effort, Remaining Work, or other numeric field. - -You can add either the report or widget to a dashboard. Also, you can monitor progress using the [Analytics-based burndown or burnup widgets](configure-burndown-burnup-widgets.md). They provide more configuration options. - -::: moniker-end - -::: moniker range="azure-devops-2019" - -Throughout your sprint, you can monitor the sprint burndown report to determine if your team is on track to complete its [sprint plan](../../boards/sprints/assign-work-sprint.md). The in-context sprint burndown report supports tracking burndown based on Remaining Work assigned to sprint tasks. If you don't track tasks or Remaining Work, then you can use the [Analytics-based burndown and burnup widgets](configure-burndown-burnup-widgets.md). They provide more configuration options. +Throughout your sprint, you can monitor the sprint burndown report to determine if your team is on track to complete its [sprint plan](../../boards/sprints/assign-work-sprint.md). There are two accessible burndown charts: the in-context Burndown Trend report viewable from a team sprint backlog and the Sprint Burndown widget that you can add to a dashboard. -::: moniker-end +Both the report and the widget derive data from [Analytics](../powerbi/what-is-analytics.md). They support monitoring burndown based on a count of work items or a sum of Story Points, Size, Effort, Remaining Work, or other numeric fields. -::: moniker range="< azure-devops-2019" - -Throughout your sprint, you can monitor the sprint burndown chart to determine if your team is on track to complete its [sprint plan](../../boards/sprints/assign-work-sprint.md). Both the in-context sprint burndown report and the Sprint Burndown widget support tracking burndown based on Remaining Work assigned to sprint tasks. - -::: moniker-end - - -::: moniker range="azure-devops-2019" - -> [!NOTE] -> You can't add an in-context report to a dashboard. However, you can add the Sprint burndown widget or the [Analytics-based burndown or burnup widgets](configure-burndown-burnup-widgets.md) to a dashboard. - -::: moniker-end - -::: moniker range="tfs-2018" - -> [!NOTE] -> You can't add an in-context report to a dashboard. However, you can add the Sprint burndown widget to a dashboard. +You can add either the report or widget to a dashboard. Additionally, you can monitor progress using the [Analytics-based burndown or burnup widgets](configure-burndown-burnup-widgets.md), which provide more configuration options. ::: moniker-end [!INCLUDE [note-delete-area-paths](../../boards/includes/note-delete-area-paths.md)] -Use this article to learn about: - -::: moniker range=">= azure-devops-2020" -> [!div class="checklist"] -> * Metrics tracked in the sprint burndown report and widget -> * Team activities required to track tasks and Remaining Work -> * How to set interactive controls to personalize your view of the sprint burndown report -> * How to add the in-context Burndown Trend report to a dashboard -> * How to configure the Sprint Burndown widgets -> * How to view current and past sprint burndowns - -For an overview of all burndown/burnup charts available to you, see [Burndown and burnup guidance](burndown-guidance.md). - -::: moniker-end - -::: moniker range="<= azure-devops-2019" - - -> [!div class="checklist"] -> * Metrics tracked in the sprint burndown report and widget -> * Team activities required to track tasks and Remaining Work -> * How to configure the Sprint Burndown widget -> * How to view current and past sprint burndowns - -::: moniker-end - - -> [!NOTE] -> Sprint burndown reports are derived from data tracked by a team during a sprint or iteration. To learn more, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). - +For an overview of all burndown and burnup charts available to you, see [Burndown and burnup guidance](burndown-guidance.md). +> [!NOTE] +> Sprint burndown reports are derived from data tracked by a team during a sprint or iteration. For more information, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). ## The in-context Burndown Trend report ::: moniker range=">= azure-devops-2020" -The Burndown Trend report is based on either a count of tasks or remaining work estimates, or other numeric fields that you define and update throughout the sprint cycle. For details, see [Sprint planning](../../boards/sprints/assign-work-sprint.md). To open this report, jump to the section [Open a Sprint backlog](#open-chart). - -A healthy sprint burndown report looks something like the image shown below. Typically, there will be a stair-case burndown as individual team members may only update their work items once a week or every few days. -The **Total Scope** line indicates the number of work items added after the sprint starts. The **Ideal Trend** line is calculated based on the number of work items, days in the sprint, and number of working days. - -The blue area indicates the number of work items active or in progress each day of the sprint. As shown in this example, one work item is still active at the end of the sprint. - -[!INCLUDE [temp](../../includes/note-working-days-off.md)] +The Burndown Trend report is based on either a count of tasks or remaining work estimates, or other numeric fields that you define and update throughout the sprint cycle. For details, see [Sprint planning](../../boards/sprints/assign-work-sprint.md). To open this report, see [Open a Sprint backlog](#open-chart). -> [!div class="mx-imgBorder"] -> ![Select another team](media/burndown/analytics-burndown-stories-count-past-s159.png) +A healthy sprint burndown report appears similar to the following example. The blue area indicates the number of work items active or in progress each day of the sprint. As shown in this example, one work item is still active at the end of the sprint. -> [!NOTE] -> The **Total Scope** line reflects the number of work items added to the sprint. If the team's default iteration is the **\@CurrentIteration**, then new work items are added to the current iteration. The scope decreases as the Iteration Path is modified to another sprint, or work items are completed. - -::: moniker-end - - -::: moniker range="< azure-devops-2020" - -The in-context sprint burndown report is based on the tasks and Remaining Work estimates you define and update throughout the sprint cycle. For details, see [Sprint planning](../../boards/sprints/assign-work-sprint.md) and [taskboard](../../boards/sprints/task-board.md). To open the sprint burndown chart, jump to the section [Open sprint burndown chart](#open-chart). +:::image type="content" source="media/burndown/analytics-burndown-stories-count-past-s159.png" alt-text="Screenshot shows the burndown trend for specified start and end dates." lightbox="media/burndown/analytics-burndown-stories-count-past-s159.png"::: -:::row::: - :::column span="1"::: - - A healthy sprint burndown chart will look something like this. The Ideal Trend line connects the two points: +| Element | Description | +|:--------|:------------| +| **Date range** | The start and end date of the sprint. | +| **Stories Remaining** | The number of stories remaining in the sprint. If you choose a different work item type, the remaining number of those work items is shown. | +| **Completed** | The percentage of work completed based on original scope. Select **Completed** to see the full list of completed work items. | +| **Average burndown** | Average work completed. | +| **Total Scope Increase** | Shows the change in how much work from the original scope since the burndown started. The example shows that six work items were removed. | +| **Remaining** | The number of work items active or in progress. The example shows one active item is remaining in the sprint. | +| **Total Scope** | The total number of work items in the sprint including closed work items. If the team's default iteration is the **\@CurrentIteration**, then new work items are added to the current iteration. The scope decreases as the Iteration Path is modified to another sprint, or work items are completed.| +| **Ideal Trend** | The ideal burndown rate for the sprint calculated from the number of work items, days in the sprint, and number of working days. | - - **(1)** Team's total capacity at the start of the sprint. - - **(2)** 0 Remaining Work at the end of the sprint. - - The slope represents the rate at which the team needs to burn down work to finish the sprint on time. - - The actual graph, the blue area, represents the total amount of planned sprint work and how it changes throughout the course of the sprint. The blue area corresponds to the sum of all Remaining Work set for all sprint tasks, and possibly bugs, that have the current sprint as their iteration path. - - :::column-end::: - :::column span="2"::: - - ![Healthy sprint burndown chart](media/burndown/ALM_SB_IntroHealthyChart.png) - :::column-end::: -:::row-end::: +Because individual team members might only update their work items once a week or every few days, there's usually a stair-case burndown pattern. +> ::: moniker-end - ## The Sprint Burndown widget ::: moniker range=">= azure-devops-2020" -In the widget catalog, you'll find two versions of the Sprint Burndown widget: the Analytics-based **Sprint Burndown** and **Sprint Burndown (Legacy)** which is built from the work tracking data store. +In the widget catalog, you find two versions of the Sprint Burndown widget: the Analytics-based **Sprint Burndown** and **Sprint Burndown (Legacy)**, which is built from the work tracking data store. ### Sprint Burndown widget -The Analytics-based Sprint Burndown widget provides an easy way to monitor progress for a team by showing work remaining for a given sprint. Work remaining is the vertical axis and time is the horizontal axis. You can define remaining work based on Stories or Tasks, and by counting the work items or summing a field. +The Analytics-based Sprint Burndown widget provides an easy way to monitor progress for a team by showing work remaining for a given sprint. Work remaining is the vertical axis and time is the horizontal axis. You can define remaining work based on Stories or Tasks, and by counting the work items or summing a field. -> [!div class="mx-imgBorder"] -> ![Sprint Burndown Widget - Sprint Burndown Example](media/sprint-burndown/sprint-burndown-widget.png) +:::image type="content" source="media/sprint-burndown/sprint-burndown-widget.png" alt-text="Screenshot shows the Sprint Burndown widget, which displays a graph of the burndown."::: + +| Element | Description | +|:--------|:------------| +| **Date range** | The start and end date of the sprint. | +| **Tasks Remaining** | The number of tasks remaining in the sprint. If you choose a different work item type, the remaining number of those work items is shown. | +| **Completed** | The percentage of work completed based on original scope. Select **Completed** to see the full list of completed work items. | +| **Average burndown** | Average work completed. | +| **Total Scope Increase** | Shows the change in how much work from the original scope since the burndown started. The example shows that four work items were added to the sprint. | +| **Remaining** | The number of work items active or in progress. The example shows 15 active items are remaining in the sprint. | +| **Total Scope** | The total number of work items in the sprint including closed work items. If the team's default iteration is the **\@CurrentIteration**, then new work items are added to the current iteration. The scope decreases as the Iteration Path is modified to another sprint, or work items are completed.| +| **Ideal Trend** | The ideal burndown rate for the sprint calculated from the number of work items, days in the sprint, and number of working days. | The charts provide useful metrics to help you answer the question: *Are we on track to complete this set of work by the end a sprint?* -* Percentage work complete -* Number of work items not estimated (if using a field other than Remaining Work) -* Average burndown -* Total scope increase + +- Percentage work complete +- Number of work items not estimated, if using a field other than Remaining Work +- Average burndown +- Total scope increase ### Sprint Burndown (Legacy) widget -The **Sprint Burndown (Legacy)** widget adds a chart based on Remaining Work defined for tasks in a team's current sprint. Select this version when you don't have access to Analytics. Configuration options include team selection, and widget size. +The **Sprint Burndown (Legacy)** widget adds a chart based on Remaining Work defined for tasks in a team's current sprint. Select this version when you don't have access to Analytics. Configuration options include team selection, and widget size. -> [!div class="mx-imgBorder"] -> ![Sprint Burndown Legacy Widget - Sprint Burndown Example](media/burndown/sprint-burndown-legacy-devops.png) +:::image type="content" source="media/burndown/sprint-burndown-legacy-devops.png" alt-text="Screenshot shows the Sprint Burndown Legacy widget, which shows a burndown chart."::: If your dashboard already has a legacy version available, you can easily upgrade the widget by editing the widget's configuration, and checking **Try the new version now**. You can always go back to the legacy version by unchecking the box. ::: moniker-end -::: moniker range="< azure-devops-2020" +## Prerequisites -The **Sprint Burndown** widget adds a chart based on Remaining Work defined for tasks in the team's current sprint. There are no configuration options for this widget. - -> [!div class="mx-imgBorder"] -> ![Sprint Burndown Widget - Configuration, legacy](media/burndown/sprint-burndown-widget-no-config.png) - -::: moniker-end - -## Prerequisites - -[!INCLUDE [temp](../includes/analytics-widgets-prerequisites.md)] - -::: moniker range="< azure-devops-2019" - -- You must be a member of a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -- If you haven't been added as a project member, [get added now](../../organizations/security/add-users-team-project.md). -- To add a widget to a team dashboard, you need to be a member of the team. You must have **Basic** access or greater, have [dashboard permissions](./dashboard-permissions.md), or be a [team admin](../../organizations/settings/add-team-administrator.md) or project admin. - -::: moniker-end +[!INCLUDE [prerequisites](../includes/analytics-widgets-prerequisites.md)] -## Team activities to track tasks and Remaining Work +## Team activities to track tasks and Remaining Work ::: moniker range=">= azure-devops-2020" @@ -195,185 +112,105 @@ To monitor sprint burndown, your team must [schedule sprints](../../boards/sprin If you want to monitor sprint burndown based on tasks and Remaining Work, your team must carry out these extra actions. ::: moniker-end -::: moniker range="<= azure-devops-2019" -To monitor sprint burndown, your team must [schedule sprints](../../boards/sprints/define-sprints.md) and [assign work to those sprints](../../boards/sprints/assign-work-sprint.md). For sprint burndown charts to show meaningful data, your team must carry out these extra actions. -::: moniker-end - -### Required activities: - -* [Define and estimate tasks](../../boards/sprints/add-tasks.md#define-tasks) for each product backlog item you're working on in the sprint. If you work from your team's backlog and taskboard, the items you create will automatically be assigned to the current sprint (Iteration) and to your team's default Area Path. -* [Update Remaining Work for each sprint task](../../boards/sprints/task-board.md#update-tasks) as work progresses. +### Required activities -### Recommended activities: +- Define and estimate tasks for each product backlog item that you're working on in the sprint. If you work from your team's backlog and taskboard, the items you create are automatically assigned to the current sprint (Iteration) and to your team's default Area Path. For more information, see [Add tasks to backlog items to support sprint planning](../../boards/sprints/add-tasks.md). +- Update Remaining Work for each sprint task as work progresses. For more information, see [Update tasks during the sprint cycle](../../boards/sprints/task-board.md#update-tasks). -* Define tasks that take a day or less to complete to lessen the effect of poor estimates. -* Don't divide tasks into subtasks. If you divide a task into subtasks, specify hours only for the subtasks. These hours are rolled up as summary values for the parent task. -* Update Remaining Work daily or several times within a week to support monitoring and achieve a smoother burndown chart. -* At the end of the sprint, update the task status of completed tasks and determine how to handle incomplete tasks. +### Recommended activities +- To decrease the effect of poor estimates, define tasks that take a day or less to complete. +- Don't divide tasks into subtasks. If you divide a task into subtasks, specify hours only for the subtasks. These hours are rolled up as summary values for the parent task. +- To support monitoring and achieve a smoother burndown chart, update Remaining Work daily or several times within a week. +- At the end of the sprint, update the task status of completed tasks and determine how to handle incomplete tasks. -### Empty sprint burndown chart +### Empty sprint burndown chart If your sprint burndown chart appears empty, check these points: -- Have you assigned tasks to the sprint associated with the chart? -- Have you assigned Remaining Work to the tasks assigned to the sprint? -- Are the parent work items of the tasks assigned to the same sprint? If not, the tasks may appear in another sprint associated with the parent item. + +- Did you assign tasks to the sprint associated with the chart? +- Did you assign Remaining Work to the tasks assigned to the sprint? +- Are the parent work items of the tasks assigned to the same sprint? If not, the tasks might appear in another sprint associated with the parent item. ## Open a Sprint backlog -You view the in-context sprint burndown report from a team's Sprint backlog. +You view the in-context sprint burndown report from a team's Sprint backlog. ::: moniker range=">= azure-devops-2020" -1. From your web portal, open your team's sprint backlog. (1) Check that you've selected the right project, (2) select **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), select **Backlog**. - - > [!div class="mx-imgBorder"] - > ![Open Work, Sprints, for a team](../../boards/sprints/media/add-tasks/open-sprint-backlog-s155-co.png) - - To select another team, open the selector and select a different team or select the **View Sprint directory** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Select another team, team selector](../../boards/sprints/media/add-tasks/team-selector-sprints-agile.png) - -2. To select a different sprint than the one shown, open the sprint selector and select the sprint you want. - - > [!div class="mx-imgBorder"] - > ![Select another sprint](../../boards/sprints/media/add-tasks/select-specific-sprint-agile.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then select **New Sprint** from the menu, and then select **Select existing iteration**. For details, see [Define iteration paths](../../organizations/settings/set-iteration-paths-sprints.md). - - -::: moniker-end - -::: moniker range="azure-devops-2019" - -1. From your web browser, open your team's sprint backlog. (1) Check that you've selected the right project, (2) select **Boards>Sprints**, (3) select the correct team from the team selector menu, and lastly (4), select **Backlog**. - - ![Open Work, Sprints, for a team, 2019](../../boards/sprints/media/add-tasks/open-sprints-backlog-agile.png) - - To select another team, open the selector and select a different team or select the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all sprints** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. +1. From your web portal, open your team's sprint backlog. - > [!div class="mx-imgBorder"] - > ![Select another team, team selector 2019](../../boards/sprints/media/add-tasks/team-selector-sprints-agile.png) + 1. Check that you selected the right project. + 1. Select **Boards>Sprints** and select the correct team from the team selector menu. + 1. Select **Backlog**. -2. To select a different sprint than the one shown, open the sprint selector and select the sprint you want. + :::image type="content" source="../../boards/sprints/media/add-tasks/open-sprint-backlog-s155-co.png" alt-text="Screenshot shows where you can select Backlog in Azure Boards." lightbox="../../boards/sprints/media/add-tasks/open-sprint-backlog-s155-co.png"::: - > [!div class="mx-imgBorder"] - > ![Select another sprint, 2019](../../boards/sprints/media/add-tasks/select-specific-sprint-agile.png) - - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then select **New Sprint** from the menu, and then select **Select existing iteration**. For details, see [Define iteration paths](../../organizations/settings/set-iteration-paths-sprints.md). - - -::: moniker-end - - -::: moniker range="tfs-2018" - -1. From your web browser, open your team's sprint backlog. (1) Select the team from the project/team selector, select (2) **Work**, (3) **Backlogs**, and then (4) the product backlog, which is **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI). - - > [!div class="mx-imgBorder"] - > ![Open the Boards>Backlogs page](../../boards/sprints/media/assign-items-sprint/open-work-backlogs-standard.png) - - To select another team, open the project/team selector and select a different team or select the **Browse** option. - - > [!div class="mx-imgBorder"] - > ![Select another team, on-premises](../../boards/sprints/media/assign-items-sprint/team-selector-backlogs-standard.png) + To select another team, open the selector and select a different team or select the **View Sprint directory** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - The set of sprints selected for your team appears in the left pane. If you don't see any sprints listed, you can add sprints or select existing sprints for your team's use. To learn how, see [Define sprints](../../boards/sprints/define-sprints.md). + :::image type="content" source="../../boards/sprints/media/add-tasks/team-selector-sprints-agile.png" alt-text="Screenshot shows the option to select another team in Azure Boards."::: -1. Select the sprint whose burndown chart you want to view. +1. To select a different sprint than the one shown, open the sprint selector and select the sprint you want. - > [!div class="mx-imgBorder"] - > ![Select another sprint, on-premises](../../boards/sprints/media/add-tasks/choose-sprint-standard.png) + :::image type="content" source="../../boards/sprints/media/add-tasks/select-specific-sprint-agile.png" alt-text="Screenshot shows the option to select another sprint in Azure Boards."::: - The system lists only those sprints that have been selected for the current team focus. If you don't see the sprints you want listed, then see [Define iteration paths](../../organizations/settings/set-iteration-paths-sprints.md). + The system lists only those sprints that are selected for the current team focus. If you don't see the sprints you want listed, select **New Sprint** from the menu, and then select **Select existing iteration**. For details, see [Define iteration paths](../../organizations/settings/set-iteration-paths-sprints.md). ::: moniker-end - + -## View the in-context Burndown Trend report +## View the in-context Burndown Trend report ::: moniker range=">= azure-devops-2020" -1. To open the Sprint burndown report, select **Analytics**. +1. To open the Sprint burndown report, select **Analytics**. - > [!div class="mx-imgBorder"] - > ![Open Analytics](media/burndown/open-analytics.png) + :::image type="content" source="media/burndown/open-analytics.png" alt-text="Screenshot shows the Azure DevOps Analytics tab for sprints."::: 1. Use the interactive controls to select from the following options: - 1. The **Start Date** and **End Date** of the sprint. These dates will default to the team's current iteration sprint dates. - - 1. The **Backlogs/Work Items** to burn down on, either the product backlog—Stories, Issues, Product Backlog Items, or Requirements—or Tasks backlog to use. Your selection impacts the options available for the **Burndown on** menu. - + 1. The **Start Date** and **End Date** of the sprint. These dates default to the team's current iteration sprint dates. + 1. The **Backlogs/Work Items** to burn down on, either the product backlog (Stories, Issues, Product Backlog Items, or Requirements) or Tasks backlog to use. Your selection impacts the options available for the **Burndown on** menu. 1. The **Burndown on** field to use to calculate burndown, either a Count of Work Items or a sum of a field, such as Story Points, Effort, or Size. + 1. Check or uncheck **Show non-working days**. Nonworking days appear as gray bars in the background when enabled. Default nonworking days are set for a team and for a team's sprint through the capacity page. For more information, see [Set sprint capacity](../../boards/sprints/set-capacity.md). - 1. Check or uncheck **Show non-working days**. Non-working days appear as gray bars in the background when enabled. Default non-working days are set for a team and for a team's sprint through the capacity page. See [Set working days](../../organizations/settings/set-working-days.md) and [Set sprint capacity](../../boards/sprints/set-capacity.md). + Select **Reset** to reset the controls to the default options. By default, the dates are set to the selected sprint. Changes to the start and end dates don't change any sprint date definitions. - Select **Reset** to reset the controls to the default options. By default, the dates are set to the selected sprint. Changes to the start and end dates don't change any sprint date definitions. - -1. If you don't track Remaining Work in tasks, you can view burndown based on a count of work items/tasks. Hover over any point on the chart to show a summary of the data for a specific day. +1. If you don't track Remaining Work in tasks, you can view burndown based on a count of work items or tasks. To show a summary of the data for a specific day, hover over any point on the chart. ### [Sum of Remaining Work](#tab/remaining-work) -When you choose to view the **Tasks backlog** and **Sum of Remaining Work**, the blue area shows the sum of Remaining Work per day for those tasks that are still active or in progress. As the Remaining Work is updated, the chart indicates the rate of burndown. The **Scope** trend line indicates the addition of Remaining Work after the start of the sprint. The **Ideal** trend line indicates the ideal burndown rate for the sprint. **Capacity** lines are only shown when the team has configured capacity. +When you choose to view the **Tasks backlog** and **Sum of Remaining Work**, the blue area shows the sum of Remaining Work per day for those tasks that are still active or in progress. As the Remaining Work is updated, the chart indicates the rate of burndown. The **Scope** trend line indicates the addition of Remaining Work after the start of the sprint. The **Ideal** trend line indicates the ideal burndown rate for the sprint. **Capacity** lines are only shown when the team configured capacity. -> [!div class="mx-imgBorder"] -> ![Burndown trend based on Remaining Work](media/burndown/analytics-burndown-remaining-work-s159.png) +:::image type="content" source="media/burndown/analytics-burndown-remaining-work-s159.png" alt-text="Screenshot shows Burndown trend based on Remaining Work." lightbox="media/burndown/analytics-burndown-remaining-work-s159.png"::: ### [Count of Work Items](#tab/work-items) -When you choose to view the **Count of Work Items**, the blue area shows the count of work items—could be stories/backlog items/requirements or tasks depending on the backlog selected—which are still active or in progress. The **Scope** trend line indicates when new work items are added after the start of the sprint. The **Ideal** trend line indicates the ideal burndown rate for the sprint. - -> [!div class="mx-imgBorder"] -> ![Burndown trend based on Count of Work Items](media/burndown/analytics-burndown-count-of-work-items-s159.png) +When you choose to view the **Count of Work Items**, the blue area shows the count of work items which are still active or in progress. Work items could be stories, backlog items, requirements, or tasks depending on the backlog selected. The **Scope** trend line indicates when new work items are added after the start of the sprint. The **Ideal** trend line indicates the ideal burndown rate for the sprint. +:::image type="content" source="media/burndown/analytics-burndown-count-of-work-items-s159.png" alt-text="Screenshot shows Burndown trend based on Count of Work Items." lightbox="media/burndown/analytics-burndown-count-of-work-items-s159.png"::: ### [Sum of Story Points](#tab/story-points) -When you choose to view the **Stories backlog** and **Sum of Story Points**, the blue area shows the sum of Story Points for all User Stories that are still active or in progress. The **Scope** trend line indicates when Story Points are added after the start of the sprint. The **Ideal** trend line indicates the ideal burndown rate for the sprint. +When you choose to view the **Stories backlog** and **Sum of Story Points**, the blue area shows the sum of Story Points for all User Stories that are still active or in progress. The **Scope** trend line indicates when Story Points are added after the start of the sprint. The **Ideal** trend line indicates the ideal burndown rate for the sprint. -> [!div class="mx-imgBorder"] -> ![Burndown trend based on Story Points](media/burndown/analytics-burndown-story-points.png) +:::image type="content" source="media/burndown/analytics-burndown-story-points.png" alt-text="Screenshot shows Burndown trend based on Story Points." lightbox="media/burndown/analytics-burndown-story-points.png"::: * * * > [!NOTE] -> The options for the sum fields depend on the numeric fields defined for task and requirement category work item types. The most common fields used to show the burndown trend are: +> The options for the sum fields depend on the numeric fields defined for task and requirement category work item types. The most common fields used to show the burndown trend are: +> > - Count of work items -> - Sum of [Story Points, Effort, or Size](../../boards/queries/query-numeric.md#fields) -> - Sum of [Remaining Work](../../boards/queries/query-numeric.md#fields). - -The selections you make are only set for you, and persist across sessions until you change them. - -::: moniker-end - -::: moniker range="<= azure-devops-2019" +> - Sum of [Story Points, Effort, or Size](../../boards/queries/query-numeric.md#fields) +> - Sum of [Remaining Work](../../boards/queries/query-numeric.md#fields) -Select the chart to display it in a larger view. - -::: moniker-end - -::: moniker range="azure-devops-2019" -> [!div class="mx-imgBorder"] -> ![Open sprint burndown chart, 2019](media/burndown/open-burndown-chart-agile.png) - -::: moniker-end - -::: moniker range="tfs-2018" -> [!div class="mx-imgBorder"] -> ![Open sprint burndown chart, 2018](media/burndown/sprint-burndown-open-chart.png) -::: moniker-end - -::: moniker range="<= azure-devops-2019" - -> [!div class="mx-imgBorder"] -> ![Opened Sprint burndown chart](media/burndown/ALM_DS_SprntBD_Chrt_S.png) +The selections you make are only set for you, and persist across sessions until you change them. ::: moniker-end @@ -383,135 +220,76 @@ Select the chart to display it in a larger view. 1. To add the report to a dashboard, select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select **Copy to Dashboard**. - > [!div class="mx-imgBorder"] - > ![Analytics in-context report, Copy to dashboard](media/add-charts/add-analytics-chart-abbreviated.png) + :::image type="content" source="media/add-charts/add-analytics-chart-abbreviated.png" alt-text="Screenshot shows the Analytics in-context report, Copy to dashboard option."::: 1. Select the dashboard and select **OK**. ::: moniker-end - -## Add the Sprint Burndown widget to a dashboard - +## Add the Sprint Burndown widget to a dashboard ::: moniker range=">= azure-devops-2020" -You can add the Sprint Burndown widget to a dashboard and select the team whose progress you want to monitor. You configure these widgets for one or more teams. - -1. If you haven't yet [added the Sprint Burndown widget to your dashboard](add-widget-to-dashboard.md), do that now. - - You can filter the **Add** widget dialog with "sprint burndown" to quickly locate the two widgets available to you. - - > [!div class="mx-imgBorder"] - > ![Add widget dialog, filter by sprint burndown](media/burndown/add-sprint-burndown-widget-devops.png) - -1. To configure the widget, select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select the **Configure** option. - - > [!div class="mx-imgBorder"] - > ![Open the Configure dialog](media/add-widgets/configure-widget.png) -::: moniker-end - -::: moniker range="azure-devops-2019" - -1. Select :::image type="icon" source="media/icons/edit-icon.png" border="false"::: **Edit** to add the Sprint burndown widget to your team dashboard. +You can add the Sprint Burndown widget to a dashboard and select the team whose progress you want to monitor. You configure these widgets for one or more teams. - The widget catalog automatically opens. Drag the Sprint Burndown widget onto the dashboard. +1. If you need to [add the Sprint Burndown widget to your dashboard](add-widget-to-dashboard.md), do that now. -1. When you're finished with your additions, select **Done Editing**. + You can filter the **Add Widget** dialog with *sprint burndown* to quickly locate the two widgets available to you. - The sprint burndown chart for the team's current sprint is added to the dashboard. There's no configuration option associated with this widget. + :::image type="content" source="media/burndown/add-sprint-burndown-widget-devops.png" alt-text="Screenshot shows the Add Widget dialog, filter by sprint burndown."::: - > [!div class="mx-imgBorder"] - > ![Sprint burndown legacy](media/burndown/sprint-burndown-widget-no-config.png) +1. To configure the widget, select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and then select **Configure**. + :::image type="content" source="media/add-widgets/configure-widget.png" alt-text="Screenshot shows the Configure menu item."::: ::: moniker-end -::: moniker range="tfs-2018" - -1. Select ![Edit dashboard icon](media/edit-dashboard-icon.png) to modify a dashboard. Select ![add a widget icon](media/add-widget-icon.png) to add a widget to the dashboard. - - The widget catalog automatically opens. Add all the widgets that you want and drag their tiles into the sequence you want. - -1. When you're finished with your additions, select **Done Editing**. - - The sprint burndown chart for the team's current sprint is added to the dashboard. There's no configuration option associated with this widget. - - > [!div class="mx-imgBorder"] - > ![Sprint burndown legacy](media/burndown/sprint-burndown-widget-no-config.png) - -::: moniker-end - - - ::: moniker range=">= azure-devops-2020" -## Configure the Analytics-based Sprint Burndown widget - -1. To configure the widget, select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select the **Configure** option. - - > [!div class="mx-imgBorder"] - > ![Sprint Burndown Widget - Configuration](media/sprint-burndown/sprint-burndown-config.png) - -1. Modify the **Title** of the widget and select your preferred **Size**. The Sprint Burndown widget can scale up to 10x10. - +## Configure the Analytics-based Sprint Burndown widget -2. Make the following selections: - - **Team** - Select the **Team** you want to track. +1. To configure the widget, select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select the **Configure** option. - - **Backlogs and work items** - Select the work items to include in your burndown. You can select to any backlog or a specific work item type. + :::image type="content" source="media/sprint-burndown/sprint-burndown-config.png" alt-text="Screenshot shows the Sprint Burndown widget Configuration dialog."::: - - **Burndown on** - Choose how you want to burndown. You may burndown by count of work items or a sum based on a selected field. +1. Modify the **Title** of the widget and select your preferred **Size**. The Sprint Burndown widget can scale up to 10x10. - - **Select iteration** - You may select **\@CurrentIteration**, or a specific iteration. +1. Make the following selections: - - **Time period** - If you selected **\@CurrentIteration**, these dates aren't editable, as they'll be automatically to the start/end date of the current iteration. If you selected a specific iteration, you may customize the start/end date for the burndown chart. + - **Team**: Select the **Team** you want to track. + - **Backlogs and work items**: Select the work items to include in your burndown. You can select to any backlog or a specific work item type. + - **Burndown on**: Choose how you want to burndown. You might burndown by count of work items or a sum based on a selected field. + - **Select iteration**: You can select **\@CurrentIteration**, or a specific iteration. + - **Time period**: If you selected **\@CurrentIteration**, these dates aren't editable. They're automatically the start and end date of the current iteration. If you selected a specific iteration, you can customize the start/end date for the burndown chart. -2. **Advanced features**: Check the boxes of the following options that you want to add to your chart. - - **Show total scope**: Displays both the historical and projected scope increase. - - **Show non working days**: Displays non working days on the burndown. When displayed, non working days are shaded. - - **Plot remaining using work item type color**: Displays remaining work based on the work item type color, rather than the default blue color. If multiple work items are included, then it stacks colors by work item type. +1. **Advanced features**: Select the following options that you want to add to your chart. -[!INCLUDE [temp](../../includes/note-working-days-off.md)] + - **Show total scope**: Displays both the historical and projected scope increase. + - **Show non working days**: Displays nonworking days on the burndown. When displayed, nonworking days are shaded. + - **Plot remaining using work item type color**: Displays remaining work based on the work item type color, rather than the default blue color. If multiple work items are included, then it stacks colors by work item type. ::: moniker-end ::: moniker range=">= azure-devops-2020" -## Configure the Sprint Burndown (Legacy) widget +## Configure the Sprint Burndown (Legacy) widget -1. To configure the widget, select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select the **Configure** option. +To configure the widget, select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon and select the **Configure** option. - > [!div class="mx-imgBorder"] - > ![Sprint Burndown Legacy Widget - Configuration - Legacy Version](media/sprint-burndown/sprint-burndown-legacy-config.png) +:::image type="content" source="media/sprint-burndown/sprint-burndown-legacy-config.png" alt-text="Screenshot shows the Sprint Burndown Legacy widget configuration dialog."::: - If your dashboard already has a legacy version available, you can easily upgrade the widget by editing the widget's configuration, and checking **Try the new version now**. You can always go back to the legacy version by unchecking the box. +If your dashboard already has a legacy version available, you can easily upgrade the widget by editing the widget's configuration. Select **Try the new version now**. You can always go back to the legacy version by unselecting the option. ::: moniker-end - ## Current and past sprint burndown charts -As you complete each sprint, the system maintains a history of your activity. - -::: moniker range=">= azure-devops-2019" +As you complete each sprint, the system maintains a history of your activity. To view a past sprint and its burndown chart, select the sprint from the Sprint selector. -> [!div class="mx-imgBorder"] -> ![Select a past sprint from the sprint selector](media/burndown/select-past-sprint.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -To view a past sprint and its burndown chart, select the sprint listed under the **Past** section of the sidebar. - -> [!div class="mx-imgBorder"] -> ![Past sprints provide historical record, 2017-2018](media/burndown/past-sprints.png) - -::: moniker-end +:::image type="content" source="media/burndown/select-past-sprint.png" alt-text="Screenshot shows here you can select a past sprint from the sprint selector."::: You can review sprint burndown in-context reports to show the team patterns in execution. The burndown charts maintain a record of the team's ability to plan and estimate. @@ -519,59 +297,34 @@ You can review sprint burndown in-context reports to show the team patterns in e #### [May](#tab/may) -> [!div class="mx-imgBorder"] -> ![May burndown](media/burndown/may.png) +:::image type="content" source="media/burndown/may.png" alt-text="Screenshot shows the May burndown chart." lightbox="media/burndown/may.png"::: #### [June](#tab/june) - -> [!div class="mx-imgBorder"] -> ![June burndown](media/burndown/june.png) +:::image type="content" source="media/burndown/june.png" alt-text="Screenshot shows the June burndown chart." lightbox="media/burndown/june.png"::: #### [July](#tab/july) -> [!div class="mx-imgBorder"] -> ![July burndown](media/burndown/july.png) - -::: moniker-end - -::: moniker range="< azure-devops-2020" - -| Sprint 1 | Sprint 2 | Sprint 3 | -|------------|------------|----------| -|![Sprint 1](media/burndown/ALM_SB_Chart_S1_225.png) |![Sprint 2](media/burndown/ALM_SB_Chart_S2_225.png) |![Sprint 3](media/burndown/ALM_SB_Chart_S3_225.png) | +:::image type="content" source="media/burndown/july.png" alt-text="Screenshot shows the July burndown chart." lightbox="media/burndown/july.png"::: ::: moniker-end -Teams may find it useful to review these reports periodically during their sprint retrospectives. It may spark useful discussions and lead to setting one or more sprint goals, such as: -* How does our projected velocity match up to our actual velocity? -* How can we more accurately determine how much we can accomplish in a sprint? -* How can we complete work at a more regular pace throughout the sprint? +Teams can find it useful to review these reports periodically during their sprint retrospectives. It can spark useful discussions and lead to setting one or more sprint goals, such as: +- How does your projected velocity match up to your actual velocity? +- How can you more accurately determine how much your team can accomplish in a sprint? +- How can you complete work at a more regular pace throughout the sprint? ## Next steps > [!div class="nextstepaction"] -> [Burndown and burnup guidance](burndown-guidance.md) - -In addition to the sprint burndown chart, teams can review the [velocity](team-velocity.md) at which they work sprint over sprint. The velocity chart tracks how many backlog items your team works on in a sprint. You can use your team velocity as input into the [forecast](../../boards/sprints/forecast.md) tool to help plan your sprints. - +> [Burndown and burnup guidance](burndown-guidance.md) ## Related articles -You can learn more about defining, planning, and executing your sprints from these articles: - - [Define iteration paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md) -- [Sprint planning](../../boards/sprints/assign-work-sprint.md) +- [Assign backlog items to a sprint in Azure Boards](../../boards/sprints/assign-work-sprint.md) - [Add tasks to backlog items](../../boards/sprints/add-tasks.md) -- [Update and monitor your Taskboard](../../boards/sprints/task-board.md) -- [Scrum and best practices](../../boards/sprints/best-practices-scrum.md) - -And, from these industry resources: -- [Understanding the Scrum Burndown Chart](https://www.methodsandtools.com/archive/scrumburndown.php) - -::: moniker range="< azure-devops" - -For projects that use the On-premises XML process model, you can [specify the format that appears—**h** for hours or **d** for days—for the remaining work field](../../reference/xml/process-configuration-xml-element.md#fields). - -::: moniker-end +- [Update and monitor your Taskboard](../../boards/sprints/task-board.md) +- [Understand scrum and best practices](../../boards/sprints/best-practices-scrum.md) +- [Understand the Scrum Burndown Chart](https://www.methodsandtools.com/archive/scrumburndown.php) diff --git a/docs/report/dashboards/configure-test-results-trend.md b/docs/report/dashboards/configure-test-results-trend.md index ee30a3b1b13..9743d4f1506 100644 --- a/docs/report/dashboards/configure-test-results-trend.md +++ b/docs/report/dashboards/configure-test-results-trend.md @@ -8,7 +8,7 @@ ms.assetid: ms.topic: tutorial ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 02/02/2022 --- @@ -46,33 +46,20 @@ With the Test Results Trend charts, you can gain the following insights: - Obtain insights into specific areas of interest to you based on test file, branch, or stage you own by configuring specific filters. - Obtain insights into a specific area you test by configuring the widget to focus on a test file, branch, or stage. -Test Results Trend charts require that you set up continuous testing in your build pipeline. To get deeper insights and data you can view the Test Failure report in the pipeline. To learn more, see details [Analyze test results](../../pipelines/test/test-analytics.md#view-test-analytics-for-builds). +Test Results Trend charts require that you set up continuous testing in your build pipeline. To get deeper insights and data you can view the Test Failure report in the pipeline. For more information, see details [Analyze test results](../../pipelines/test/test-analytics.md#view-test-analytics-for-builds). ## Prerequisites -To configure the Test Results Trend widget: - ::: moniker range="azure-devops" -- You must be a member of a project. If you haven't been added as a project member, [get added now](../../organizations/accounts/add-organization-users.md). -- Set up continuous testing for your build pipeline. For details, see [Run unit tests with your builds](../../pipelines/ecosystems/dotnet-core.md#run-your-tests). -- To add a widget to a team dashboard, you need to be a member of the team. You must have **Basic** access or greater, have [dashboard permissions](./dashboard-permissions.md), or be a [team admin](../../organizations/settings/add-team-administrator.md) or project admin. Default settings provide all team members with permissions. -- Enable **Pipelines**. If disabled, none of the Analytics widgets for pipelines will display. To re-enable it, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -- Enable **Test Plans**. If disabled, the Test Results Trend widget displays an "Access not supported" error message. To enable test plans, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). - -::: moniker-end - -::: moniker range="azure-devops-2019" - -- You must be a member of a project. If you haven't been added as a project member, [get added now](../../organizations/security/add-users-team-project.md). -- Set up continuous testing for your build pipeline. For details, see [Run unit tests with your builds](../../pipelines/ecosystems/dotnet-core.md#run-your-tests). -- Have installed the [Analytics Marketplace extension](../dashboards/analytics-extension.md). You must be a member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) to add extensions. -- To add a widget to a team dashboard, you need to be a member of the team. You must have **Basic** access or greater, have [dashboard permissions](./dashboard-permissions.md), or be a [team admin](../../organizations/settings/add-team-administrator.md) or project admin. -- Enable **Pipelines**. If disabled, none of the Analytics widgets for pipelines will display. To re-enable it, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). +| Category | Requirements | +|-------------|-------------| +| **Access** | [Project member](../../organizations/accounts/add-organization-users.md) with at least **Basic** access. Users with **Stakeholder** access can't view or create charts from the **Queries** page. They can view charts added to a team dashboard. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). | +| **Permissions** |- By default, users with at least **Basic** access can create charts. Users with **Stakeholder** access can't view or create charts from the **Queries** page, however, they can view charts added to a team dashboard. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md).
      - To add a widget to a team dashboard, you need to be a member of the team. Have at least **Basic** access, [dashboard permissions](./dashboard-permissions.md), or be a [team admin](../../organizations/settings/add-team-administrator.md) or project admin. Default settings provide all team members with permissions.| +|**Services** |- **Azure Pipelines** enabled. If disabled, none of the Analytics widgets for pipelines will display. To re-enable it, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md).
      - **Test Plans** enabled. If disabled, the Test Results Trend widget displays an "Access not supported" error message. To enable test plans, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md).
      - **Continuous testing** set up for your build pipeline. For more information, see [Run unit tests with your builds](../../pipelines/ecosystems/dotnet-core.md#run-your-tests). | ::: moniker-end - ## Configure the Test Results Trend (Advanced) widget @@ -96,8 +83,6 @@ You can configure your Test Results Trend (Advanced) widget to show results for ![Screenshot of Test Results Trend Advanced widget.](media/test-results-trend-widget/passed-bypriority-pass.png) - - ## Next steps > [!div class="nextstepaction"] diff --git a/docs/report/dashboards/copy-dashboard.md b/docs/report/dashboards/copy-dashboard.md index 02e70778e3c..d5155fc9155 100644 --- a/docs/report/dashboards/copy-dashboard.md +++ b/docs/report/dashboards/copy-dashboard.md @@ -8,40 +8,38 @@ ms.author: chcomley author: chcomley ms.topic: quickstart monikerRange: '>= azure-devops-2022' -ms.date: 10/18/2022 +ms.date: 11/22/2023 --- # Copy a dashboard [!INCLUDE [version-gt-eq-2022](../../includes/version-gt-eq-2022.md)] -Use **Copy Dashboard** to create a copy of a team or project dashboard. You can copy a dashboard to a different team, the same team, or a different project. The copy operation copies the widgets defined on one dashboard to a new dashboard, and reconfigures them based on a selected team. This feature minimizes the work required to build similar dashboards from scratch. - -> [!NOTE] -> The **Copy Dashboard** feature is currently in preview and enabled by default. To access the feature, the **Copy Dashboard Experience** must be enabled. To learn how, see [Manage or enable features](../../project/navigation/preview-features.md). +You can create a new dashboard by copying the widgets from an existing one and adjusting them for a different team or project. This way, you don’t have to start from scratch when you want to make a similar dashboard. To copy a dashboard, you begin with the source dashboard and then select the destination team and the destination project. The copied dashboard has the same widgets as the source dashboard, but you can configure them according to the team you chose. + +To create a dashboard for a team or project, see [Add, rename, and delete dashboards](dashboards.md). To add a team or project, see [Add a team](../../organizations/settings/add-teams.md) or [Create a project](../../organizations/projects/create-project.md). -To create a dashboard for a team or project, see [Add, rename, and delete dashboards](dashboards.md). To add a team or project, see [Add a team](../../organizations/settings/add-teams.md) or [Create a project](../../organizations/projects/create-project.md) +[!INCLUDE [feature-added-2022-1](../../includes/feature-added-2022-1.md)] ## Prerequisites -- You must be a member of a project. If you don't have a project yet, [create one](../../organizations/accounts/set-up-vs.md). If you haven't been added as a project member, [get added now](../../organizations/accounts/add-organization-users.md). -- Anyone with access to a project, including [stakeholders](../../organizations/security/get-started-stakeholder.md), can view dashboards. However, to view queries or work items displayed in a dashboard widget, you must have permissions to view the query and work items. To learn more, see [Set permissions on queries and query folders](../../boards/queries/set-query-permissions.md) and [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md). -- To add, edit, or manage a team dashboard, you must have **Basic** access or greater and be a [team admin](../../organizations/settings/add-team-administrator.md), a project admin, or have [dashboard permissions](../dashboards/dashboard-permissions.md). In general, you need to be a team member for the currently selected team to edit dashboards. -- When copying a dashboard as a team dashboard, you should be a member of the team. Otherwise, you may be able to copy it, but later won't be able to edit it. Also, when copying a dashboard, you should choose a Shared Queries folder to copy queries to that you have permissions to edit and contribute queries to. - +|Category | Requirements | +|-------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Basic** access. | +| **Permissions** | - Anyone with access to a project, including [Stakeholders](../../organizations/security/get-started-stakeholder.md), can view dashboards. However, to view queries or work items displayed in a dashboard widget, have permissions to view the query and work items. For more information, see [Set permissions on queries and query folders](../../boards/queries/set-query-permissions.md) and [Set work tracking permissions](../../organizations/security/set-permissions-access-work-tracking.md).
      - Member of the team, a [team administrator](../../organizations/settings/add-team-administrator.md), a project administrator, or [**Edit**](../dashboards/dashboard-permissions.md) dashboard permission.- **Edit** permissions for a shared queries folder to copy queries into.| ## Open the dashboard you want to copy -All dashboards are associated with either a team or a project. From the **Overview>Dashboards** page, you can browse all dashboards and see which team they belong to, or if they're a project dashboard. +Do the following steps to open the source dashboard. -1. Open a web browser, connect to your project, and select **Overview>Dashboards**. The dashboard directory page opens. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). +2. Select **Overview** > **Dashboards**. The dashboard directory page opens. - > [!div class="mx-imgBorder"] - > ![Screenshot of Dashboards Directory.](media/dashboards/open-dashboards-vert.png) + :::image type="content" source="media/dashboards/open-dashboards-vert.png" alt-text="Screenshot of Dashboards Directory."::: - It lists dashboards in the following order: + Dashboards get listed in the following order: - Your last visited dashboard - Your favorited dashboards - All dashboards of teams that you belong to @@ -49,47 +47,40 @@ All dashboards are associated with either a team or a project. From the **Overvi Select the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: filter icon to filter the list by keyword or team. Keywords apply to dashboard titles, descriptions, and team names. - > [!div class="mx-imgBorder"] - > ![Screenshot of Filter the dashboard directory.](media/dashboards/filter-directory.png) + :::image type="content" source="media/dashboards/filter-directory.png" alt-text="Screenshot of Filter the dashboard directory."::: -1. If you need to switch to a different project, select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to [browse all projects](../../project/navigation/go-to-project-repo.md). +3. (Optional) To switch to a different project, select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to [browse all projects](../../project/navigation/go-to-project-repo.md). -1. If you open a dashboard, you can select a different dashboard from the directory list, or from the selector. To return to the dashboard directory, select the **Browse all dashboards** option. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Dashboard selector, Browse all dashboards option.](media/dashboards/browse-all-dashboards.png) +4. (Optional) If you open a dashboard, you can select a different dashboard from the directory list, or from the selector. To return to the dashboard directory, select **Browse all dashboards**. + + :::image type="content" source="media/dashboards/browse-all-dashboards.png" alt-text="Screenshot of Dashboard selector, Browse all dashboards option."::: ## Copy the dashboard -1. From the dashboard page, select :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: **More actions** and then select **Copy Dashboard**. +Do the following steps to copy the source dashboards and create your new dashboard with it. - > [!div class="mx-imgBorder"] - > ![Open the create a dashboard dialog](media/copy-dashboard/dashboard-copy-dashboard-selected.png) +1. From the Dashboards page, select :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: **More actions** and then select **+ Copy Dashboard**. - If you don't see the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: **More actions** icon, make sure that you've enabled the **Copy Dashboard Experience** preview feature. See [Manage or enable features](../../project/navigation/preview-features.md). + :::image type="content" source="media/copy-dashboard/dashboard-copy-dashboard-selected.png" alt-text="Screenshot of Create a dashboard dialog."::: -1. Enter a **Name** and **Description** for the new dashboard. To copy the dashboard as a team dashboard, select **Team Dashboard** and then select the **Project** and the **Team**. To copy the dashboard as a project dashboard, select **Project Dashboard** and then the **Project**. +2. Enter a **Name** and **Description** for the new dashboard. Make sure you specify a unique name for the dashboard. To copy the dashboard as a team dashboard, select **Team Dashboard** and then select the **Project** and the **Team**. To copy the dashboard as a project dashboard, select **Project Dashboard** and then the **Project**. Here we choose to copy the Fabrikam Fiber project - Fabrikam Team Bug Activity dashboard to the Design Agile project, Design Agile team dashboard. - > [!div class="mx-imgBorder"] - > ![New dashboard dialog, copy dashboard for a different team.](media/copy-dashboard/new-dashboard-dialog.png) - Check the **Select folder to copy dashboard queries** checkbox to choose the folder into which dashboard queries will be copied. Make sure to select a folder where you have permissions to contribute queries. When copying dashboards to a different project, this checkbox is automatically selected and requires you to select a folder in the project. + :::image type="content" source="media/copy-dashboard/new-dashboard-dialog.png" alt-text="New dashboard dialog, copy dashboard for a different team."::: + + Check the **Select folder to copy dashboard queries** checkbox to choose the folder into which dashboard queries get copied. Make sure to select a folder where you have permissions to contribute queries. When you copy dashboards to a different project, this checkbox is automatically selected and requires you to select a folder in the project. -1. Select **Create**. Make sure you specify a unique name for the dashboard. +3. Select **Create**. - The page updates to reflect the new dashboard. The widgets and layout appear the same as the dashboard selected for copy. + The page updates to reflect the new dashboard. The widgets and layout appear the same as the copied dashboard. - In the background, a folder with the name of the new dashboard is created in **Shared Queries**. All the queries for the new dashboard are copied to that folder. Query names remain the same. Widgets with a team configuration are updated with the new team. Widgets with a team configuration that are copied from a team dashboard to a project dashboard retain the original configuration. + In the background, a folder with the name of the new dashboard gets created in **Shared Queries**. All the queries for the new dashboard get copied to that folder. Query names remain the same. Widgets with a team configuration get updated with the new team. Widgets with a team configuration that are copied from a team dashboard to a project dashboard retain the original configuration. :::image type="content" source="media/copy-dashboard/shared-query-folder-created.png" alt-text="Screenshot of Shared Queries folder created with copy dashboard experience."::: - Open each query that was copied to adjust it if needed. You can rename the queries and the dashboard widgets will automatically update to reflect the new name. - -1. Open each widget copied to the new dashboard as needed to verify or modify the configuration. - - +4. (Optional) Open each query and widget in the new dashboard, as needed, to verify or modify the name and configuration. Dashboard widget changes automatically update. ## Next steps @@ -101,5 +92,4 @@ All dashboards are associated with either a team or a project. From the **Overvi - [Add a team](../../organizations/settings/add-teams.md) - [Widget catalog](widget-catalog.md) - [Marketplace widgets](https://marketplace.visualstudio.com/search?term=widget&target=VSTS&category=All%20categories&sortBy=Relevance) - \ No newline at end of file diff --git a/docs/report/dashboards/cumulative-flow-cycle-lead-time-guidance.md b/docs/report/dashboards/cumulative-flow-cycle-lead-time-guidance.md index 83fa0e4dc4e..c361d4978b1 100644 --- a/docs/report/dashboards/cumulative-flow-cycle-lead-time-guidance.md +++ b/docs/report/dashboards/cumulative-flow-cycle-lead-time-guidance.md @@ -17,7 +17,7 @@ ms.date: 04/04/2022 You use cumulative flow diagrams (CFD) to monitor the flow of work through a system. The two primary metrics to track, cycle time and lead time, can be extracted from the chart. To configure or view CFD charts, see [Configure a cumulative flow chart](cumulative-flow.md). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Or, you can add the [Lead time and cycle time control charts](cycle-time-and-lead-time.md) to your dashboards. @@ -53,7 +53,7 @@ Or, you can add the [Lead time and cycle time control charts](cycle-time-and-lea ## Chart metrics -CFD charts display the count of work items grouped by state/Kanban column over time. The two primary metrics to track, cycle time and lead time, can be extracted from the chart. +CFD charts display the count of work items grouped by state/column over time. The two primary metrics to track, cycle time and lead time, can be extracted from the chart. --- :::row::: @@ -102,11 +102,11 @@ CFD charts display the count of work items grouped by state/Kanban column over t --- 1 The CFD widget (Analytics) and built-in CFD chart (work tracking data store) don't provide discrete numbers on Lead Time and Cycle Time. However, the [Lead Time and Cycle Time widgets](cycle-time-and-lead-time.md) do provide these numbers. -There's a well-defined correlation between Lead Time/Cycle Time and Work in Progress (WIP). The more WIP, the longer the cycle time, which also leads to longer lead times. The opposite is also true—the less WIP, the shorter the cycle and lead time. When the development team focuses on fewer items, they reduce the cycle and lead times. This correlation is a key reason why you can and should set [Work In Progress limits on the Kanban board](../../boards/boards/wip-limits.md). +There's a well-defined correlation between Lead Time/Cycle Time and Work in Progress (WIP). The more WIP, the longer the cycle time, which also leads to longer lead times. The opposite is also true—the less WIP, the shorter the cycle and lead time. When the development team focuses on fewer items, they reduce the cycle and lead times. This correlation is a key reason why you can and should set [Work In Progress limits on the board](../../boards/boards/wip-limits.md). The count of work items indicates the total amount of work on a given day. In a fixed period CFD, a change in this count indicates scope change for a given period. In a continuous flow CFD, it indicates the total amount of work in the queue and completed for a given day. -Decomposing work into specific Kanban board columns provides a view where work is in process. This view provides insights on where work is moving smoothly, where there are blockages and where no work is being done at all. It's difficult to decipher a tabular view of the data, however, the visual CFD chart provides evidence that something is happening in a given way. +Decomposing work into specific board columns provides a view where work is in process. This view provides insights on where work is moving smoothly, where there are blockages and where no work is being done at all. It's difficult to decipher a tabular view of the data, however, the visual CFD chart provides evidence that something is happening in a given way. ## Identify issues, take appropriate actions @@ -114,7 +114,7 @@ The CFD answers several specific questions and based on the answer, actions can ### Will the team complete work on time? -This question applies to fixed period CFDs only. You gain an understanding by looking at the curve (or progression) of work in the last column of the Kanban board. +This question applies to fixed period CFDs only. You gain an understanding by looking at the curve (or progression) of work in the last column of the board. ![Sample CFD with a half completed chart, dotted lines show the work won't be completed](media/cfd-incomplete.png) @@ -134,7 +134,7 @@ Two problems show up visually as flat lines and as bulges. :::row::: :::column span="2"::: - Flat lines appear when the team doesn't update their work with a regular cadence. The [Kanban board](../../boards/boards/kanban-overview.md) provides the quickest way to transition work from one column to another. + Flat lines appear when the team doesn't update their work with a regular cadence. The [board](../../boards/boards/kanban-overview.md) provides the quickest way to transition work from one column to another. Flat lines can also appear when the work across one or more processes takes longer than planned. Flat lines appear across many parts of the system because if only one part of the system or two parts of a system have problems then you'll see a bulge. :::column-end::: :::column span="3"::: @@ -180,10 +180,9 @@ Scope changes apply to fixed period CFDs only. The top line of the chart indicat The one scenario where you can't track scope changes with a CFD occurs when the same number of work items are added as removed on the same day. The line would continue to be flat. Compare several charts with one another. Monitor the specific issues. Use [View/configure sprint burndown](configure-sprint-burndown.md) to monitor scope changes. - ### Too much WIP? -You can easily monitor [whether WIP limits have been exceed from the Kanban board](../../boards/boards/wip-limits.md). You can also monitor it from the CFD. +You can easily monitor [whether WIP limits have been exceed from the board](../../boards/boards/wip-limits.md). You can also monitor it from the CFD. A large amount of WIP usually shows up as a vertical bulge. The longer that there's a large amount of WIP, the more the bulge will expand to become an oval. It's an indication that the WIP is negatively affecting the cycle and lead time. @@ -191,8 +190,7 @@ Here's a good rule of thumb for works in progress. There should be no more than Sometimes it takes time to get information from a stakeholder, or it takes more time to acquire necessary software. There are any number of reasons why work might be halted. Having a second work item to pivot to provides some leeway. If both items are blocked, it's time to raise a red flag to get something unblocked—not just switch to yet another item. As soon as there are a large number of items in progress, the person working on those items will have difficulty context switching. It's more likely they'll forget what they were doing, and mistakes may occur. - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Lead time versus cycle time @@ -204,9 +202,9 @@ The diagram below illustrates how lead time differs from cycle time. Lead time i If a work item enters a Completed state and then is reactivated, any extra time it spends in a Proposed, In Progress, or Resolved state will contribute to its lead/cycle time when it enters a Completed state category for the second time. -If your team uses the Kanban board, you'll want to understand how your Kanban columns map to workflow states. For more information on configuring your Kanban board, see [Add columns](../../boards/boards/add-columns.md). +If your team uses the board, you'll want to understand how your columns map to workflow states. For more information on configuring your board, see [Add columns](../../boards/boards/add-columns.md). -To learn more about how the system uses the state categories—Proposed, In Progress, Resolved, and Completed—see [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md). +For more information about how the system uses the state categories—Proposed, In Progress, Resolved, and Completed—see [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md). ## Plan using estimate delivery times based on lead/cycle times @@ -220,7 +218,6 @@ In the following chart, the average cycle time is eight days. The standard devia Cycle Time widget - ## Identify process issues Review your team's control chart for outliers. Outliers often represent an underlying process issue. For example, waiting too long to complete PR reviews or not resolving an external dependency quickly. @@ -237,14 +234,9 @@ You can also see how process changes affect your lead and cycle time. For exampl ## Next steps -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!div class="nextstepaction"] > [Configure your cumulative flow charts](cumulative-flow.md) or > [Configure a lead time or cycle time chart](cycle-time-and-lead-time.md) ::: moniker-end -::: moniker range="tfs-2018" -> [!div class="nextstepaction"] -> [Configure your cumulative flow chart](cumulative-flow.md) -::: moniker-end - diff --git a/docs/report/dashboards/cumulative-flow.md b/docs/report/dashboards/cumulative-flow.md index 08fc9f70f3f..b740a2c2a23 100644 --- a/docs/report/dashboards/cumulative-flow.md +++ b/docs/report/dashboards/cumulative-flow.md @@ -16,13 +16,12 @@ ms.date: 04/04/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -You use cumulative flow diagrams (CFD) to monitor the flow of work through a system. There are two CFD charts: the in-context report you can view from a team backlog or Kanban board and the CFD widget you can add to a dashboard. +You use cumulative flow diagrams (CFD) to monitor the flow of work through a system. There are two CFD charts: the in-context report you can view from a team backlog or board and the CFD widget you can add to a dashboard. ::: moniker-end - ::: moniker range=">= azure-devops-2020" CFDs help teams monitor the count of work items as they progressively move through various workflow states. These diagrams can show the flow of epics, features, user stories, issues, product backlog items, or requirements, depending on the process selected for your project: @@ -33,15 +32,6 @@ CFDs help teams monitor the count of work items as they progressively move throu ::: moniker-end -::: moniker range="azure-devops-2019" - -CFDs help teams monitor the count of work items as they progressively move through various workflow states. These diagrams can show the flow of epics, features, user stories, product backlog items, or requirements, depending on the process selected for your project: -- [Agile](../../boards/work-items/guidance/agile-process.md) -- [Scrum](../../boards/work-items/guidance/scrum-process.md) -- [Capability Maturity Model Integration (CMMI)](../../boards/work-items/guidance/cmmi-process.md) - -::: moniker-end - ::: moniker range=">= azure-devops-2020" Use this article to learn how to: @@ -52,33 +42,7 @@ Use this article to learn how to: ::: moniker-end -::: moniker range="azure-devops-2019" - -Use this article to learn how to: - -> [!div class="checklist"] -> * Configure the Cumulative Flow Diagram widget (Analytics) -> * View and configure the CFD in-context report (work tracking data store) - -::: moniker-end - -::: moniker range="tfs-2018" - -You use cumulative flow diagrams (CFD) to monitor the flow of work through a system. CFDs help teams monitor the count of work items as they progressively move through various workflow states. These diagrams can show the flow of epics, features, user stories, product backlog items, or requirements, depending on the process selected for your project: -- [Agile](../../boards/work-items/guidance/agile-process.md) -- [Basic](../../boards/get-started/plan-track-work.md) -- [Scrum](../../boards/work-items/guidance/scrum-process.md) -- [Capability Maturity Model Integration (CMMI)](../../boards/work-items/guidance/cmmi-process.md) - -Use this article to learn how to: - -> [!div class="checklist"] -> * View and configure the CFD in-context report (work tracking data store) - -::: moniker-end - -The CFD shows the count of items in each Kanban column for the selected time period. From this chart, you can gain an idea of the amount of work in progress and lead time. Work in progress counts unfinished requirements. Lead time indicates the amount of time it takes to complete a requirement once work has started. - +The CFD shows the count of items in each column for the selected time period. From this chart, you can gain an idea of the amount of work in progress and lead time. Work in progress counts unfinished requirements. Lead time indicates the amount of time it takes to complete a requirement once work has started. ::: moniker range=">= azure-devops-2020" @@ -87,36 +51,22 @@ The CFD shows the count of items in each Kanban column for the selected time per ::: moniker-end - -::: moniker range="< azure-devops-2020" - -![Cumulative Flow Diagram](../../boards/boards/media/ALM_KB_CumulativeFlow.png) - -::: moniker-end - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!NOTE] > The in-context report always uses the blue-green color theme. However, the [Analytics-based Cumulative flow diagram widget](#cfd-widget) provides support for choosing different color themes. ::: moniker-end -For the CFD to provide useful information, you'll want to update the status of work items to reflect progress as it occurs. You can quickly make these updates through your [Kanban board](../../boards/boards/kanban-quickstart.md). +For the CFD to provide useful information, you'll want to update the status of work items to reflect progress as it occurs. You can quickly make these updates through your [board](../../boards/boards/kanban-quickstart.md). For usage guidance, see [Cumulative flow, lead time, and cycle time guidance](cumulative-flow-cycle-lead-time-guidance.md). - -::: moniker range=">= azure-devops-2019" - -## Prerequisites - -::: moniker-end +## Prerequisites [!INCLUDE [temp](../includes/analytics-widgets-prerequisites.md)] - ## Open your backlog from the web portal - ::: moniker range=">= azure-devops-2020" 1. Check that you selected the right project, and select **Boards** > **Backlogs**. Then select the correct team from the team selector menu. @@ -136,39 +86,6 @@ For usage guidance, see [Cumulative flow, lead time, and cycle time guidance](cu ::: moniker-end -::: moniker range="azure-devops-2019" - -1. Check that you selected the right project, and select **Boards** > **Backlogs**. Then select the correct team from the team selector menu. - - ![Open Boards > Backlogs, for a team](/azure/devops/boards/sprints/media/assign-items-sprint/open-work-backlogs-agile.png) - - To select another backlog, open the selector and then select a different team or select the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all backlogs** option. Or, enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Select another team](/azure/devops/boards/sprints/media/assign-items-sprint/team-selector-backlogs-agile.png) - -1. To view the in-context reports for the product backlog, check that you selected **Stories** for Agile, **Issues** for Basic, **Backlog items** for Scrum, or **Requirements** for CMMI as the backlog level. Or - - > [!div class="mx-imgBorder"] - > ![Select product backlog level, Backlog items, Stories, or Requirements](/azure/devops/boards/sprints/media/assign-items-sprint/select-product-backlog-agile.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -On your web browser, open your team's product backlog and select the team from the project and team selector. Then select **Work** > **Backlogs**. Select the product backlog, which is **Backlog items** for Scrum, **Stories** for Agile, or **Requirements** for CMMI. - -> [!div class="mx-imgBorder"] -> ![Open the Boards > Backlogs page](/azure/devops/boards/sprints/media/assign-items-sprint/open-work-backlogs-standard.png) - -To select another team, open the project and team selector. Select a different team, or select the **Browse** option. - -> [!div class="mx-imgBorder"] -> ![Select another team](/azure/devops/boards/sprints/media/assign-items-sprint/team-selector-backlogs-standard.png) - -::: moniker-end - - ## View the CFD in-context report ::: moniker range=">= azure-devops-2020" @@ -189,7 +106,7 @@ CFD reports are available for each backlog level, both product and portfolio bac 1. Next, select **View full report** for the Cumulative Flow Diagram. -1. Use the interactive controls to select the time frame, swimlanes, and workflow states or Kanban board columns. You can select a rolling period of 14 days or up to 180 days. +1. Use the interactive controls to select the time frame, swimlanes, and workflow states or board columns. You can select a rolling period of 14 days or up to 180 days. Hover over a point in time to show how many work items are in a particular state. The default setting for the Cumulative Flow Diagram-Average work in progress includes completed work items since the team started tracking work. @@ -211,73 +128,15 @@ CFD reports are available for each backlog level, both product and portfolio bac ::: moniker-end -::: moniker range="azure-devops-2019" - -To open the CFD in-context report for your product or portfolio backlog, select the image in the upper-right corner of your **Boards>Boards** page. - -> [!div class="mx-imgBorder"] -> ![Open CFD, new nav](media/open-cfd-new-nav.png) - -The image opens to display a larger view of the CFD. - -> [!div class="mx-imgBorder"] -> ![Opened CFD chart](media/cfd/data-store-cumulative-flow-opened.png) - -::: moniker-end - - -::: moniker range="tfs-2018" - -To open the CFD in-context report for your product or portfolio backlog, select the image in the upper-right corner of your **Work>Backlogs** page. - -![Open CFD, prev nav](/azure/devops/boards/boards/media/kanban-basics-open-cfd.png) - -::: moniker-end - - + -::: moniker range="<= azure-devops-2019" - -## Configure the CFD in-context report - -Each team can set their preferences for the in-context cumulative flow charts. - -::: moniker-end - -::: moniker range="azure-devops-2019" - -1. Open the [backlog level for which you want to configure](../../boards/boards/kanban-quickstart.md) and then open the common configuration dialog. Select the :::image type="icon" source="../../boards/media/icons/team-settings-gear-icon.png" border="false"::: gear icon. - - > [!div class="mx-imgBorder"] - > ![Open Board settings](media/cfd/open-cfd-settings-new-nav.png) - - If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the Kanban boards and CFD charts. - -2. Select **Cumulative flow** and specify the team's preferences. - - > [!div class="mx-imgBorder"] - > ![Kanban board, Common configuration dialog, Cumulative flow](media/cfd/settings-cumulative-flow-dialog.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Open the backlog level for which you want to configure and then open the common configuration dialog. Select the :::image type="icon" source="../../boards/media/icons/team-settings-gear-icon.png" border="false"::: gear icon. + - :::image type="content" source="../../boards/boards/media/kanban-card-customize-open-settings.png" alt-text="Kanban board, open common configuration settings"::: +::: moniker range="<=azure-devops" - If you're not a team admin, [get added as one](../../organizations/settings/add-team-administrator.md). Only team and project admins can customize the team Kanban boards and CFD charts. - -2. Select **Cumulative flow** and specify the team's preferences. - - :::image type="content" source="media/cfd-configure-common-settings.png" alt-text="Kanban board, Common configuration dialog, Cumulative flow"::: -::: moniker-end - -::: moniker range=">= azure-devops-2019" - - + ## Add the Cumulative Flow Diagram widget to your dashboard @@ -285,7 +144,7 @@ Each team can set their preferences for the in-context cumulative flow charts. ::: moniker range=">= azure-devops-2020" -1. If you haven't yet configured your Kanban board, do that now. Define the [columns](../../boards/boards/add-columns.md) and [swimlanes](../../boards/boards/expedite-work.md) that support your workflow processes. +1. If you haven't yet configured your board, do that now. Define the [columns](../../boards/boards/add-columns.md) and [swimlanes](../../boards/boards/expedite-work.md) that support your workflow processes. 1. If you want fixed scope CFD charts, make sure that you've [defined the sprint iterations](../../boards/sprints/define-sprints.md) for those sprints of interest. 1. To add a CFD chart to your team dashboard, see [Add a widget to a dashboard](./add-widget-to-dashboard.md). Add the Cumulative Flow Diagram widget. @@ -300,27 +159,10 @@ Each team can set their preferences for the in-context cumulative flow charts. :::image type="content" source="media/cfd-configure.png" alt-text="Configure CFD chart"::: ::: moniker-end -::: moniker range="azure-devops-2019" -1. If you haven't yet [enabled or installed Analytics](analytics-extension.md), do that now. -1. If you haven't yet configured your Kanban board, do that now. Define the [columns](../../boards/boards/add-columns.md) and [swimlanes](../../boards/boards/expedite-work.md) that support your workflow processes. -1. If you want fixed scope CFD charts, make sure that you've [defined the sprint iterations](../../boards/sprints/define-sprints.md) for those sprints of interest. -1. To add a CFD chart to your team dashboard, see [Add a widget to a dashboard](./add-widget-to-dashboard.md). Add the Cumulative Flow Diagram widget. + + - ![Cumulative flow diagram widget](media/cfd-choose-widget.png) - -1. Select the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon and select the **Configure** option to open the configuration dialog. Modify the title, and then select the values you want to monitor: - - Team - - Backlog level - - Swimlanes - - Time period - - :::image type="content" source="media/cfd-configure.png" alt-text="Configure CFD chart"::: -::: moniker-end - - - - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Configure the CFD widget @@ -337,7 +179,6 @@ Each team can set their preferences for the in-context cumulative flow charts. :::image type="content" source="media/cfd-exampe-rolling-30-days.png" alt-text="Example CFD chart, rolling 30 days"::: ::: moniker-end - ## Next steps > [!div class="nextstepaction"] diff --git a/docs/report/dashboards/cycle-time-and-lead-time.md b/docs/report/dashboards/cycle-time-and-lead-time.md index c320b9a1cc6..64b6215e222 100644 --- a/docs/report/dashboards/cycle-time-and-lead-time.md +++ b/docs/report/dashboards/cycle-time-and-lead-time.md @@ -5,166 +5,133 @@ description: Learn how to configure and use the cycle time and lead time control ms.custom: dashboards ms.subservice: azure-devops-analytics ms.assetid: C444622C-A2CA-4FCF-9E68-90D8D4896E6B -ms.topic: tutorial +ms.topic: how-to ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' -ms.date: 09/28/2021 +monikerRange: "<=azure-devops" +ms.date: 03/12/2025 +#customer intent: As a team member, I want to create Lead Time or Cycle Time widgets to show team progress on the dashboard. --- - # Lead Time and Cycle Time widgets [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] +The Lead Time and Cycle Time widgets indicate how long it takes for work to flow through your development pipeline. Lead time measures the total time elapsed from the creation of work items to their completion. Cycle time measures the time it takes for your team to complete work items once they begin actively working on them. -Both lead time and cycle time widgets are useful to teams. They both indicate how long it takes for work to flow through their development pipeline. Lead time measures the total time elapsed from the creation of work items to their completion. Cycle time measures the time it takes for your team to complete work items once they begin actively working on them. - -The following diagram illustrates how lead time differs from cycle time. Lead time is calculated from work item creation to entering a completed state. Cycle time is calculated from first entering an In Progress or Resolved state category to entering a Completed state category. To understand how workflow states map to state categories, see [How workflow states and state categories are used in Backlogs and Boards](../../boards/work-items/workflow-and-state-categories.md). - -:::image type="content" source="media/cycle-lead-time-concept-intro.png" alt-text="Conceptual image of how cycle time and lead time are measured"::: +The following diagram illustrates how lead time differs from cycle time. Lead time is calculated from *Work Item Creation* to entering a *Completed* state. Cycle time is calculated from first entering an *In Progress or Resolved* state category to entering a *Completed* state category. For more information, see [About workflow states in backlogs and boards](../../boards/work-items/workflow-and-state-categories.md). -These measures help teams plan, spot variations in efficiency, and identify potential process issues. The lower the lead and cycle times, the faster the throughput your team has. - -In this article you'll learn: +:::image type="content" source="media/cycle-lead-time-concept-intro.png" alt-text="Conceptual image of how cycle time and lead time are measured."::: -> [!div class="checklist"] -> * How to install and configure the Lead Time and Cycle Time widgets (Analytics) -> * How to interpret the scatter-plot control charts -> * How moving average and standard deviation are calculated in the charts +These measures help teams plan, identify variations in efficiency, and spot potential process issues. Lower lead and cycle times indicate faster team throughput. We recommend checking the lead time and cycle time charts before or during each retrospective. Use lead time to estimate delivery times and track service level agreements (SLAs). Use cycle time to identify process issues, spot variations in trends, and assist with planning. -To learn more, see [Cumulative flow, lead time, and cycle time guidance](cumulative-flow-cycle-lead-time-guidance.md). +For more information, see [Cumulative flow, lead time, and cycle time guidance](cumulative-flow-cycle-lead-time-guidance.md). +## Prerequisites -## Prerequisites +[!INCLUDE [analytics-widgets-prerequisites](../includes/analytics-widgets-prerequisites.md)] -[!INCLUDE [temp](../includes/analytics-widgets-prerequisites.md)] +## Add the widget to your dashboard -## Add the widget to your dashboard - -1. (Optional) If you haven't yet configured your team's Kanban board, do that now. Define the [columns](../../boards/boards/add-columns.md) and [swimlanes](../../boards/boards/expedite-work.md) that support your workflow processes. -2. If you haven't yet [added the widget to your dashboard](./add-widget-to-dashboard.md), do that now. There are two widgets: [Cycle Time](widget-catalog.md#cycle-time-widget) and [Lead Time](widget-catalog.md#lead-time-widget). Select the one you want to display and configure. +1. Ensure your team's board is configured with defined [columns](../../boards/boards/add-columns.md) and [swimlanes](../../boards/boards/expedite-work.md) that support your workflow processes. +2. [Add the widget to your dashboard](./add-widget-to-dashboard.md). There are two widgets: [Cycle Time](widget-catalog.md#cycle-time-widget) and [Lead Time](widget-catalog.md#lead-time-widget). Select the one you want to display and configure. -## Configure the Cycle Time and Lead Time widgets +## Configure the Cycle Time and Lead Time widgets -The Configuration dialog is the same for the Cycle Time and Lead Time widgets. You configure these widgets for a team. To learn more about teams, see [Add teams](../../organizations/settings/add-teams.md). +The Configuration dialog is the same for the Cycle Time and Lead Time widgets. Configure these widgets for a team. For more information, see [Create or add a team](../../organizations/settings/add-teams.md). ::: moniker range=">= azure-devops-2020" -1. Select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: context menu icon and select **Configure** to open the configuration dialog. Modify the title, and then select the values you want to monitor: +1. Select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: context menu icon and select **Configure** to open the configuration dialog. +1. Modify the title, and then select the values you want to monitor: + - Team - - Backlog level + - Work items - Swimlane - Field criteria - Time period - > [!div class="mx-imgBorder"] - > ![Screenshot of Configure dialog, Lead Time widget, latest version.](media/lead-cycle/cycle-lead-time-configure-dialog-s156.png) - - To select a **Swimlane**, you must select a **Backlog**. - - > [!NOTE] - > You can only select work item types that have been added to a backlog. To add work item types to a backlog, see [Customize your backlogs or boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md). For On-premises XML process, see [Process configuration XML element reference](../../reference/xml/process-configuration-xml-element.md). - -1. To further filter the work items used to calculate the lead or cycle time, specify the **Field Criteria**. For example, all the work items whose Release field is set to Milestone 1. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Configure dialog, Lead Time widget, filter criteria.](media/lead-cycle/field-criteria-release.png) - - - > [!NOTE] - > Supplying no values to the filter may lead to selection of all workitems, or may be an invalid filter argument depending on type of filter criteria. - -1. For a continuous flow, select **Rolling period** and specify the number of days you want to view on the chart. + :::image type="content" source="media/lead-cycle/cycle-lead-time-configure-dialog-s156.png" alt-text="Screenshot of Configure dialog, Lead Time widget, latest version."::: - Or, for a fixed scope view, select and specify the Start date. Select this view if your team employs a Scrumban process or follows a standard sprint process. + To select a **Swimlane**, select **Backlog**. - The main difference between these two types of charts is that the fixed scope chart will provide information (in most cases) of scope change. + > [!NOTE] + > You can only select work item types that are added to a backlog. To add work item types to a backlog, see [Customize your backlogs or boards (Inheritance process)](../../organizations/settings/work/customize-process-backlogs-boards.md). For On-premises XML process, see [Process configuration XML element reference](../../reference/xml/process-configuration-xml-element.md). -2. Select **Save** when done. The following image shows an example Lead Time chart showing 60 days of data. - - :::image type="content" source="media/cycle-lead-time-lt-sample-chart.png" alt-text="Screenshot ofExample CFD chart, rolling 30 days."::: - For your lead/cycle time charts to provide useful data, your team must quickly [update the status](../../boards/boards/kanban-quickstart.md#track-work-in-progress) of those work items that the widgets track. +2. To further filter the work items used to calculate the lead or cycle time, specify the **Field Criteria**. For example, all the work items whose Release field is set to Milestone 1. -::: moniker-end - -::: moniker range="azure-devops-2019" - -1. Select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: context menu icon and select **Configure** to open the configuration dialog. Modify the title and then select the values you want to monitor: - - Team - - Backlog level - - Swimlane - - Time period + :::image type="content" source="media/lead-cycle/field-criteria-release.png" alt-text="Screenshot of Configure dialog, Lead Time widget, filter criteria."::: - ![Screenshot of Configure dialog, Configure dialog, Lead Time widget, 2019 version.](media/cycle-lead-time-configure-dialog.png) + > [!NOTE] + > Supplying no values to the filter might lead to selection of all work items, or might be an invalid filter argument depending on type of filter criteria. - To select a **Swimlane**, you must select a **Backlog**. +3. For a continuous flow, select **Rolling period** and specify the number of days you want to view on the chart. -1. For a continuous flow, select **Rolling period** and specify the number of days you want to view on the chart. + Or, for a fixed scope view, select and specify the **Start date**. Select this view if your team employs a Scrumban process or follows a standard sprint process. The main difference between these two types of charts is that the fixed scope chart provides information of scope change in most cases. - Or, for a fixed scope view, select and specify the Start date. Select this view if your team employs a Scrumban process or follows a standard sprint process. +4. Select **Save** when you're done. The following image shows an example Lead Time chart showing 60 days of data. - The main difference between these two types of charts is that the fixed scope chart will provide information (in most cases) of scope change. + :::image type="content" source="media/cycle-lead-time-lt-sample-chart.png" alt-text="Screenshot of Example CFD chart, rolling 30 days."::: -2. Select **Save** when done. The following image shows an example Lead Time chart showing 60 days of data. - - :::image type="content" source="media/cycle-lead-time-lt-sample-chart.png" alt-text="Screenshot Example CFD chart, rolling 30 days, 2019 version."::: - For your lead/cycle time charts to provide useful data, your team must quickly [update the status](../../boards/boards/kanban-quickstart.md#track-work-in-progress) of those work items that the widgets track. + For your lead time and cycle time charts to provide useful data, your team must quickly [update the status](../../boards/boards/kanban-quickstart.md#track-work-in-progress) of those work items that the widgets track. ::: moniker-end - - -## Interpret the scatter-plot control charts +## Interpret the scatter-plot control charts -Both Lead Time and Cycle Time widgets display as scatter-plot control charts. They display summary information and provide several interactive elements. +Both Lead Time and Cycle Time widgets display as scatter-plot control charts. They display summary information and provide several interactive elements. **Example Lead Time widget** -:::image type="content" source="media/lead-time-control-chart.png" alt-text="Screenshot of Cycle Time widget."::: -The chart dots represent completed work items where their position on the horizontal axis represents the date the team completed them. Their position on the vertical axis represents the calculated lead time or cycle time. -- Larger dots represent multiple work items with the same lead/cycle time +:::image type="content" source="media/lead-time-control-chart.png" alt-text="Screenshot of the Lead Time widget displaying Compliance Tooling Lead Time."::: + +The chart dots represent completed work items, and their position on the horizontal axis represents the date the team completed them. Their position on the vertical axis represents the calculated lead time or cycle time. + +- Larger dots represent multiple work items with the same lead time or cycle time - Dot color corresponds to the work item type displayed in the legend -- Dark gray dots correspond to a mix of work item types. +- Dark gray dots correspond to a mix of work item types -### Summary elements +### Summary elements -- Days on average (average lead time or cycle time) for the main work item types configured for the chart. This number may not be equal to the average cycle/lead time of all work items. It depends on configurations used for widgets. The average number is calculated based on each day the team takes time for work item. -- The number of backlog work items used in the chart calculations; if there are more than three types of work items, you'll see a summary for **Other** -- The black trend line indicates the moving average +- Days on average (average lead time or cycle time) for the main work item types configured for the chart. This number might not be equal to the average cycle time or lead time of all work items. It depends on configurations you use for the widgets. The average number is calculated based on each day the team takes time for work item. +- The number of backlog work items used in the chart calculations. If there are more than three types of work items, you see a summary for **Other**. +- The black trend line indicates the moving average. - The band around the trend line shows the standard deviation. ### Interactive elements -- Hover over any dot to see which work items contributed to the data point and the lead/cycle time for those items -- Select a dot to open the work item or query that lists the work items -- To filter the chart, select a work item type in the legend (:::image type="icon" source="../../media/icons/user-story-icon.png" border="false":::, :::image type="icon" source="../../media/icons/bug-icon.png" border="false":::, or other icon) to filter on that type; to return to the original chart, refresh the dashboard. +- Hover over any dot to see which work items contributed to the data point and the lead time or cycle time for those items. +- Select a dot to open the work item or query that lists the work items. +- Filter the chart by selecting a work item type in the legend (:::image type="icon" source="../../media/icons/user-story-icon.png" border="false":::, :::image type="icon" source="../../media/icons/bug-icon.png" border="false":::, or other icon) to filter on that type. To return to the original chart, refresh the dashboard. +## Moving average and standard deviation calculations -## Moving average and standard deviation calculations +- **Daily moving average**: The average of data points within the moving average window, calculated based on the current day and previous *N* days. *N* is 20% of the number of days the chart displays, rounded down to the nearest odd number. + - Example: If the chart displays the last 30 days, then *N* = 5 days (20% of 30 days is 6, rounded down to 5). -The daily moving average value corresponds to the average of data points that fall within the moving average window. -The time-based moving average window is calculated based on the current day and previous *N* days. *N* corresponds to 20% of the number of days the chart displays, rounded down to the nearest odd number. +- **Moving average window**: For April 10, the window corresponds to the previous five days. The April 10 moving average is the average of all data points from April 5 to April 10. + - If there are no data points within the moving average window, the chart doesn't show a moving average line. This behavior can occur if there aren't enough days to calculate a moving average. -Here's an example. If the chart displays the last 30 days, then *N* = 5 days: -> 20% of 30 days is 6 days rounded down to the nearest odd number which is 5. +- **Standard deviation**: Appears as a band around the moving average and gets calculated based on all data points within the same moving average window. + - If no data points fall within the moving average window, the chart doesn't plot standard deviation. -The moving average window for April 10 corresponds to the previous 5 days. So, the April 10 moving average is the average of all data points that fall on April 5 through April 10. +## Use a REST API to add a widget -If you don't have data points that fall within the moving average window, the chart doesn't show a moving average line. This scenario can occur if you're starting out and there aren't enough days to calculate a moving average. +To programmatically add a widget, use the following API endpoint: -The standard deviation appears as a band that encompasses the moving average. Standard deviation is calculated based on all data points falling within the same moving average window. Like moving average, if no data points fall within the moving average window, the chart doesn't plot standard deviation. +```HTTP + POST https://dev.azure.com/{organization}/{project}/{team}/_apis/dashboard/dashboards/{dashboardId}/widgets?api-version=7.1-preview.2 +``` +For more information, see [REST API - Get widget](/rest/api/azure/devops/dashboard/widgets/get-widget). ## Related articles -We recommend your team review the lead/cycle time charts before or during each retrospective. Use lead time to help estimate delivery times and track service level agreements (SLAs). Use cycle time to identify potential process issues, spot variations in trends, and help with planning. - -- [Cumulative flow, lead time, and cycle time guidance](cumulative-flow-cycle-lead-time-guidance.md) -- [About Kanban](../../boards/boards/kanban-overview.md) -- [Cumulative flow diagram](cumulative-flow.md) -- [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md) -- [Agile](../../boards/work-items/guidance/agile-process.md), [Scrum](../../boards/work-items/guidance/scrum-process.md), and [CMMI](../../boards/work-items/guidance/cmmi-process.md) processes +- [Get guidance on cumulative flow, lead time, and cycle time](cumulative-flow-cycle-lead-time-guidance.md) +- [Learn about Kanban boards](../../boards/boards/kanban-overview.md) +- [View and configure a Cumulative Flow Diagram](cumulative-flow.md) +- [Understand workflow states in backlogs and boards](../../boards/work-items/workflow-and-state-categories.md) +- [Explore Agile, Scrum, and CMMI processes](../../boards/work-items/guidance/agile-process.md) diff --git a/docs/report/dashboards/dashboard-focus.md b/docs/report/dashboards/dashboard-focus.md index f98591250ce..aa6e42e8024 100644 --- a/docs/report/dashboards/dashboard-focus.md +++ b/docs/report/dashboards/dashboard-focus.md @@ -1,252 +1,220 @@ --- -title: Five steps to develop actionable dashboards +title: Design effective dashboards titleSuffix: Azure DevOps -description: Learn about useful dashboards to create when working in Azure DevOps. +description: Learn about useful and actionable dashboards that you can create when working in Azure DevOps. ms.service: azure-devops-boards ms.custom: dashboards, engagement-fy23 ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 02/23/2023 +ai-usage: ai-assisted +ms.date: 08/19/2024 --- - -# Five steps to develop actionable dashboards in Azure DevOps +# Design effective dashboards in Azure DevOps [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You want to provide your team and stakeholders the information they need to meet business objectives and keep projects moving forward. Well-crafted dashboards can help you achieve these goals. This article provides some examples of dashboards you can adapt to create your own. - -To create a well-crafted dashboard, perform the following tasks: - -::: moniker range=">= azure-devops-2020" - -> [!div class="checklist"] -> - Choose a dashboard focus -> - Choose the dashboard type and create your dashboard -> - Add and configure your dashboard widgets -> - Share the dashboard with your team and stakeholders -> - Review and fine tune - -::: moniker-end -::: moniker range="< azure-devops-2020" - -> [!div class="checklist"] -> - Choose a dashboard focus -> - Create your dashboard -> - Add and configure the widgets -> - Share the dashboard with your team and stakeholders -> - Review and fine tune - -::: moniker-end +To keep your team and stakeholders informed and projects on track, actionable dashboards in Azure DevOps are essential. This article explores how to design effective dashboards that align with your business objectives. ## Choose a dashboard focus -When determining the focus of a dashboard, identify the information needs of its intended audience. You want your dashboards to provide insights and identity actions to take. +When you determine the focus of a dashboard, it's crucial to identify the information needs of its intended audience. Your goal is to create dashboards that provide insights and help identify actions to take. + ::: moniker range=">= azure-devops-2020" -Your dashboard focus determines the type of dashboard you create, team or project, as indicated in the following table. +The focus of your dashboard determines whether you create a team or project dashboard, as shown in the following table. | **Focus** | **Description** | **Dashboard type** | |-----------|-----------------|--------------------| -|[**Stakeholder**](#stakeholder-dashboard)|Use to share team and organizational goals, information, links to work item templates to create bugs or new feature requests, and more. |Team or Project | -|[**Personal**](#personal-dashboard)|Helps each team member to focus on their backlog and current work.| Project or Team | -|[**Team**](#team-dashboard)|Provides information for a team to monitor status, track progress, identify bottlenecks, and ensure backlog items are well defined. |Team | -|[**Sprint**](#sprint-dashboard)|Useful for each team to review in daily stand-ups to ensure the team is on track to meet sprint goals and address any issues that impact those goals.|Team | -|[**Release**](#release-dashboard)|Use to monitor status and track progress toward a major release that may involve contributions from several teams. |Project | -|[**Test and deploy**](#test-and-deploy-dashboard)| Use to monitor continuous integration, builds, deployments, and releases. | Project or Team| -::: moniker-end +|[**Stakeholder**](#stakeholder-dashboard)|Share team and organizational goals, information, links to work item templates to create bugs or new feature requests, and more. |Team or Project | +|[**Personal**](#personal-dashboard)|Help each team member to focus on their backlog and current work.| Project or Team | +|[**Team**](#team-dashboard)|Provide information for a team to monitor status, track progress, identify bottlenecks, and ensure backlog items are well defined. |Team | +|[**Sprint**](#sprint-dashboard)|Review in daily stand-ups to ensure the team is on track to meet sprint goals and address any issues that affect those goals.|Team | +|[**Release**](#release-dashboard)|Monitor status and track progress toward a major release that might involve contributions from several teams. |Project | +|[**Test and deploy**](#test-deploy-dashboard)| Monitor continuous integration, builds, deployments, and releases. | Project or Team| -::: moniker range="< azure-devops-2020" +::: moniker-end -The following table lists several types of dashboards you may want to create. + -| **Focus** | **Description** | -|-----------|-----------------| -|[**Stakeholder**](#stakeholder-dashboard)|Used to share team and organizational goals, information, links to work item templates to create bugs or new feature requests, and more. | -|[**Personal**](#personal-dashboard)|Helps each team member to focus on their backlog and current work.| -|[**Team**](#team-dashboard)|Provides information for a team to monitor status, track progress, identify bottlenecks, and ensure backlog items are well defined. | -|[**Sprint**](#sprint-dashboard)|Useful for each team to review in daily standups to ensure the team is on track to meet sprint goals and address any issues that impact those goals.| -|[**Release**](#release-dashboard)|Used to monitor status and track progress toward a major release which may involve contributions from several teams. | -|[**Test and deploy**](#test-and-deploy-dashboard)| Use to monitor continuous integration, builds, deployments, and releases. | -::: moniker-end +## Prerequisites +[!INCLUDE [analytics-prerequisites](../includes/analytics-prerequisites.md)] ::: moniker range=">= azure-devops-2020" -## Choose the dashboard type and create your dashboard +## Choose a dashboard type and create it + +When a team gets created, a default dashboard named *Overview* also gets created without any widgets. This default dashboard is always a **Team** dashboard that you can edit and rename. When you add a dashboard, choose the type based on the following guidance: -When a team is created, a default dashboard named *Overview* is created which doesn't contain any widgets. This default dashboard is always a **Team** dashboard that you can edit and rename. When you add a dashboard, choose the type based on the following guidance. -- **Project**: Choose this type when you want to include information for more than one team or if the content isn't team-focused. -- **Team**: Choose this type when you plan to include team-specific widgets. +- **Project**: Select this type to include information for more than one team or if the content isn't team-focused. +- **Team**: Select this type to include team-specific widgets. + +Review the [Out Of Box widget catalog](widget-catalog.md) to determine which widgets are configurable for a single team or multiple teams. -Review the [Out Of Box widget catalog](widget-catalog.md) to determine which widgets are configurable for a single team or multiple teams. ::: moniker-end ::: moniker range=">= azure-devops-2022" -To create the dashboard, see [Add, rename, and delete dashboards](dashboards.md). Streamline your process by copying another team's dashboard and updating it for your team. For details, see [Copy a dashboard](copy-dashboard.md). +Once you choose your dashboard type, [create a dashboard](dashboards.md). You can also streamline your process by [copying another team's dashboard](copy-dashboard.md) and updating it for your team. ::: moniker-end ::: moniker range="azure-devops-2020" -To create the dashboard, see [Add, rename, and delete dashboards](dashboards.md). +Once you choose your dashboard type, [create a dashboard](dashboards.md). ::: moniker-end -::: moniker range="< azure-devops-2020" - -## Create your dashboard - -When a team is created, a default dashboard named *Overview* is created which doesn't contain any widgets. This default dashboard is always a **Team** dashboard which you can edit and rename. Review the [Out Of Box widget catalog](widget-catalog.md) to determine which widgets are configurable for a single team or multiple teams. - -To create the dashboard, see [Add, rename, and delete dashboards](dashboards.md). - -::: moniker-end + ## Share the dashboard with your team and stakeholders -Once you've created your dashboard, share the URL with your team and stakeholders. Let them know what kind of actions you want them to take. Request their feedback to support your efforts to make it as actionable and insightful as you can. +After creating your dashboard, share the URL with your team and stakeholders. Specify the actions you want them to take and request feedback to make it more actionable and insightful. -To view or edit dashboards, the following conditions must be met. -- All project members have access to view all dashboards, unless specific restrictions have been placed on dashboards using a security command line tool. See [Security namespace and permission reference, Object-level namespaces and permissions, Dashboards](../../organizations/security/namespace-reference.md#dashboard-previleges-namespace). -- All project members with **Basic** access can create a dashboard. -- All team members with **Basic** access can create a team dashboard unless permissions have been revoked for the team. For details, see [Set dashboard permissions, Set default team dashboard permissions](dashboard-permissions.md#set-default-team-dashboard permissions). -- All team members have permissions to edit all team dashboards, unless the **Edit dashboard** permission has been revoked for a specific dashboard or all team dashboards. For details, see [Set dashboard permissions](dashboard-permissions.md). -- Select dashboard charts and widgets contain data that is subject to their own permissions and access levels. To learn more, see [FAQs on Azure DevOps dashboards, charts, and reports, Are their restrictions on what charts or data project members can view in a dashboard?](faqs.yml#are-there-restrictions-on-what-charts-or-data-project-members-can-view-in-a-dashboard) +To view or edit dashboards, the following conditions must be met: +- All project members can view all dashboards unless specific restrictions are applied using a security command line tool. For more information, see [Security namespace and permission reference](../../organizations/security/namespace-reference.md#dashboard-previleges-namespace). +- All project members with **Basic** access can create a dashboard. +- All team members with **Basic** access can create a team dashboard unless permissions were revoked. For details, see [Set dashboard permissions, Set default team dashboard permissions](dashboard-permissions.md#set-default-team-dashboard-permissions). +- All team members can edit all team dashboards unless the **Edit dashboard** permission was revoked for a specific dashboard or all team dashboards. For details, see [Set dashboard permissions](dashboard-permissions.md). +- Some dashboard charts and widgets contain data subject to their own permissions and access levels. For more information, see [FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml#are-there-restrictions-on-what-charts-or-data-project-members-can-view-in-a-dashboard). ## Review and fine tune -After you create your dashboard, you'll want to fine-tune it based on feedback you receive. Often, you find you need to update one or more queries used in your dashboard to refine the query results. Periodically review your dashboards to make sure it delivers the information you, your team, and stakeholders need. - - -## Stakeholder dashboard - -Stakeholders are any project members that have an interest in the work you're doing. You can use a combination of markdown widgets and other team-focused widgets to address the following information: -- Team goals -- Team information -- Team members and key contacts -- Links to work item templates -- Team guidance that you can link to wiki content - -## Personal dashboard - -You can set up a personal focus dashboard for all team members to use using the **Assigned to me** widget and other query tile or query charts that reference an `Assigned To = @Me` query clause. - -The following image shows a personal dashboard titled *My Work Focus*. Each team member can review this dashboard for work assigned to them, work they're following, or work where they're mentioned. - -:::image type="content" source="media/dashboard-focus/my-work-focus.png" alt-text="Screenshot of Dashboard, My Work query tiles and query charts. "::: - -The following table provides more information for each widget shown in the dashboard. For details on constructing queries for each of these examples, see [Example query charts](../../boards/queries/example-query-charts.md). - -| **Title** | **Description** | **Widget type** | -|-----------|-----------------|--------------------| -| Current Sprint | Work assigned to `@Me` for the current sprint. | Query tile | -| Next Sprint |Work assigned to `@Me` for the current sprint. | Query tile | -| Completed Last Sprint |Work completed last sprint assigned to `@Me`. | Query tile | -| My Backlog | Work assigned to `@Me` new, proposed, or active. | Query tile | -| I Created last 30 days |Active work with the following clauses: `Created By = @Me` and `Created Date >= @Today-30`.| Query tile | -| I Recently Updated|Active work whose `ID In @MyRecentActivity`. | Query tile | -| Work I'm Following|Active work whose `ID In @MyFollows`. | Query tile | -| My Backlog by State|Stacked area chart showing work assigned to `@Me` by for the past four weeks. | Query chart | -| My Work - Current Sprint by Work Item Type |Active work by type assigned to `@Me` for the current sprint. | Query chart | -| My Backlog by Work Item Type |Work assigned to `@Me` by type. | Query chart| -| New Work < 7 Days |Active work assigned to `@Me` and `Created Date >= @Today-7`. | Query chart | - -> [!TIP] -> Remember that you can quickly navigate to the query and view a complete list of work items behind each query tile or widget by clicking the tile or widget. +After creating your dashboard, fine-tune it based on feedback. Update queries as needed to refine results. Periodically review your dashboards to ensure they deliver the information you, your team, and stakeholders need. -Also, consider adding the following widgets to the personal focus dashboard: -- **New Work Item**: Supports creating new work items -- **Work Links**: Provides links to a team's Backlog, Board, current sprint Taskboard, and the queries page -- **Assigned to Me**: Provides a list of work items assigned to the currently signed in user, as shown in the following image. +The following table describes the dashboard types: -:::image type="content" source="media/dashboard-focus/work-assigned-to-me.png" alt-text="Screenshot of Dashboard, Assigned to me widget. "::: - - -## Team dashboard - -*What information is most important for your team?* *What goals, objectives, or guidance do you want all team members to follow?* - -Create your team dashboard to support your team members to meet team goals, monitor status, track progress, identify bottlenecks, and ensure backlog items are well defined. Consider including one or more of the following team-scoped widgets to a team dashboard. Velocity can help teams learn how well they're planning and executing on their sprint plans. Lead and cycle time can help teams learn the average time it takes for work to move from inception to completion. - -- [CFD chart](cumulative-flow.md) -- [Velocity](team-velocity.md) -- [Cycle time](cycle-time-and-lead-time.md) -- [Lead time](cycle-time-and-lead-time.md) - -Consider adding a [Chart for work item widget, Pivot table](charts.md#add-a-pivot-table) to quickly see the number of work items and their assignments as illustrated in the following images. Use these charts to determine if the team needs of better load balance the work. - -:::image type="content" source="media/dashboard-focus/load-balance-work.png" alt-text="Screenshot of Dashboard, Assigned work pivot and stacked bar chart widgets."::: - -If your team manages their code, tests, builds, and releases using Azure DevOps, then consider adding the following widgets to your team dashboard. -- [Code tile](widget-catalog.md#code-tile-widget) -- [Test results trend (Advanced)](widget-catalog.md#test-results-trend-advanced) -- [Pull request (Team)](widget-catalog.md#pull-request-widget) -- [Build history](widget-catalog.md#build-history-widget) -- [Deployment status (Build pipeline)](widget-catalog.md#deployment-status-widget) - -## Sprint dashboard - -Azure DevOps provides several sprint and team-specific widgets to help track sprint progress. These widgets include Sprint overview, Sprint capacity, and Sprint burndown. Sprint capacity is only useful if your team tracks work using tasks and sets the Sprint capacity for the team as described in [Determine and set sprint capacity](../../boards/sprints/set-capacity.md). - -The following image shows a sample of a sprint focus dashboard. - -:::image type="content" source="media/dashboard-focus/sprint-focus.png" alt-text="Screenshot of Dashboard, Sprint focus query tiles, Team Velocity, and Sprint Burndown widgets."::: - -This sprint dashboard includes several query tiles and the following widgets: - -- [Sprint overview chart](widget-catalog.md#sprint-overview-widget) -- [New work items](widget-catalog.md#new-work-item-widget) -- [Velocity](team-velocity.md) (team-configurable) -- [Sprint burndown chart](configure-sprint-burndown.md) (team-configurable) - -## Release dashboard - -Major software releases often have contributions from one or more teams. Release burndown and burnup charts can help product managers keep track of how work is progressing across a number of teams. Burndown charts are highly configurable. You can choose one or more teams, backlog work items or work item types, field criteria, countdown metrics, and time interval. To learn more, see [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). - -### Burndown chart -The following burndown chart shows the completion of planned work from July 1 through September 30, 2022. - -:::image type="content" source="media/dashboard-focus/release-burndown-chart.png" alt-text="Screenshot of Sprint burndown chart."::: - -### Burnup chart -The following burnup chart shows the completion of work from May 1 through December 31, 2022. - -:::image type="content" source="media/dashboard-focus/feature-burnup-widget.png" alt-text="Screenshot of Sprint burnup chart."::: - -> [!NOTE] -> Analytics-based charts are built based on the `WorkItemsSnapshot` EntitySet. Snapshot entity types are modeled as daily snapshots. Data is aggregated based on assignments made as of the date they're assigned. What this means is that if you want to filter a Burndown/Burnup widget based on field or tag assignments, you must assign those prior to the period you want to monitor. Otherwise, they aren't registered by the widget until the date on which they're applied. - - -## Test and deploy dashboard - -Create a dedicated dashboard to review how tests, builds, and deployments are progressing by adding one or more of the following widgets. - - -- [Build history](widget-catalog.md#build-history-widget) -- [Deployment status (Build pipeline)](widget-catalog.md#deployment-status-widget) -- [Release Pipeline overview](widget-catalog.md#release-definition-widget) -- [Requirements quality](widget-catalog.md#requirements-quality-widget) - -### Build History -:::image type="content" source="media/dashboard-focus/release-pipeline-widget.png" alt-text="Screenshot of Release pipeline overview chart."::: - -### Release pipeline overview -:::image type="content" source="media/dashboard-focus/release-pipeline-widget.png" alt-text="Screenshot of Release pipeline overview chart."::: - -### Deployment status -:::image type="content" source="media/dashboard-focus/deployment-status-widget.png" alt-text="Screenshot of Deployment status widget."::: +:::row::: + :::column span="1"::: + **Dashboard type** + :::column-end::: + :::column span="2"::: + **Description** + :::column-end::: +:::row-end::: +--- +:::row::: + :::column span="1"::: + + + **Stakeholder dashboard** + :::column-end::: + :::column span="2"::: + Stakeholders include any project members interested in your work. Use a combination of markdown widgets and team-focused widgets to address: + - Team goals + - Team information + - Team members and key contacts + - Links to work item templates + - Team guidance linked to wiki content + :::column-end::: +:::row-end::: +:::row::: + :::column span="1"::: + + **Personal dashboard** + :::column-end::: + :::column span="2"::: + Set up a personal focus dashboard for all team members using the **Assigned to me** widget and other query tiles or charts that reference an `Assigned To = @Me` query clause.
      + The following image shows a personal dashboard titled *My Work Focus*. Each team member can review this dashboard for work assigned to them, work they're following, or work where they're mentioned.
      + :::image type="content" source="media/dashboard-focus/my-work-focus.png" alt-text="Screenshot of Dashboard work query tiles and query charts.":::
      + The following list provides more information for each widget shown in the dashboard. For more information on constructing queries for these examples, see [Example query charts](../../boards/queries/example-query-charts.md).
      + - **Current sprint:** Work assigned to `@Me` for the current sprint. + - **Next sprint:** Work assigned to `@Me` for the next sprint. + - **Completed last sprint:** Work completed last sprint assigned to `@Me`. + - **My backlog:** Work assigned to `@Me` new, proposed, or active. + - **I created last 30 days:** Active work with the following clauses: `Created By = @Me` and `Created Date >= @Today-30`. + - **I recently updated:** Active work whose `ID In @MyRecentActivity`. + - **Work I'm following:** Active work whose `ID In @MyFollows`. + - **My backlog state:** Stacked area chart showing work assigned to `@Me` for the past four weeks (query chart). + - **My work - Current sprint by work item type:** Active work by type assigned to `@Me` for the current sprint (query chart). + - **My backlog by work item type:** Work assigned to `@Me` by type (query chart). + - **New work < 7 days:** Active work assigned to `@Me` and `Created Date >= @Today-7` (query chart).
      + Select any query tile or widget to quickly navigate to the query and view a complete list of work items. Consider adding the following widgets to the personal focus dashboard: + - **New work item**: Create new work items. + - **Work links**: Access links to a team's Backlog, Board, current sprint Taskboard, and the queries page. + - **Assigned to me**: View a list of work items assigned to the currently signed-in user, as shown in the following image.
      + :::image type="content" source="media/dashboard-focus/work-assigned-to-me.png" alt-text="Screenshot of Dashboard, Assigned to me widget."::: + :::column-end::: +:::row-end::: +:::row::: + :::column span="1"::: + + + **Team dashboard** + :::column-end::: + :::column span="2"::: + Create your team dashboard to help members meet goals, monitor status, track progress, identify bottlenecks, and ensure backlog items are well defined. Include one or more of the following team-scoped widgets:
      + - [CFD chart](cumulative-flow.md)
      + - [Velocity](team-velocity.md)
      + - [Cycle time](cycle-time-and-lead-time.md)
      + - [Lead time](cycle-time-and-lead-time.md)
      + Velocity helps teams understand how well they're planning and executing sprints. Lead and cycle time show the average time for work to move from inception to completion. Consider adding a [pivot table](charts.md#add-a-pivot-table) to quickly see the number of work items and their assignments. Use these charts to determine if the team needs to better balance the workload.
      + :::image type="content" source="media/dashboard-focus/load-balance-work.png" alt-text="Screenshot of Dashboard, Assigned work pivot and stacked bar chart widgets.":::
      + If your team manages code, tests, builds, and releases using Azure DevOps, add these widgets to your team dashboard:
      + - [Code tile](widget-catalog.md#code-tile-widget)
      + - [Test results trend (Advanced)](widget-catalog.md#test-results-trend-advanced)
      + - [Pull request (Team)](widget-catalog.md#pull-request-widget)
      + - [Build history](widget-catalog.md#build-history-widget)
      + - [Deployment status (Build pipeline)](widget-catalog.md#deployment-status-widget) + :::column-end::: +:::row-end::: +:::row::: + :::column span="1"::: + + + **Sprint dashboard** + :::column-end::: + :::column span="2"::: + Azure DevOps offers several sprint and team-specific widgets to track sprint progress, including Sprint overview, Sprint capacity, and Sprint burndown. Sprint capacity is useful only if your team tracks work using tasks and sets the Sprint capacity as described in [Determine and set sprint capacity](../../boards/sprints/set-capacity.md).
      + The following image shows a sample sprint focus dashboard.
      + :::image type="content" source="media/dashboard-focus/sprint-focus.png" alt-text="Screenshot of Dashboard, Sprint focus query tiles, Team Velocity, and Sprint Burndown widgets.":::
      + This sprint dashboard includes several query tiles and the following widgets: + - [Sprint overview chart](widget-catalog.md#sprint-overview-widget) + - [New work items](widget-catalog.md#new-work-item-widget) + - [Velocity](team-velocity.md) (team-configurable) + - [Sprint burndown chart](configure-sprint-burndown.md) (team-configurable) + :::column-end::: +:::row-end::: +:::row::: + :::column span="1"::: + + + **Release dashboard** + :::column-end::: + :::column span="2"::: + Major software releases often involve contributions from multiple teams. Release burndown and burnup charts help product managers track progress across teams. These charts are highly configurable, allowing you to choose teams, backlog work items or work item types, field criteria, countdown metrics, and time intervals. For more information, see [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md).
      + > [!NOTE] + > Analytics-based charts use the `WorkItemsSnapshot` EntitySet, which models data as daily snapshots. Data aggregates based on assignments made on the date they're assigned. To filter a Burndown/Burnup widget by field or tag assignments, assign them before the period you want to monitor. Otherwise, the widget doesn't register them until the date they're applied. + :::column-end::: +:::row-end::: +:::row::: + :::column span="1"::: + + + **Test & deploy dashboard** + :::column-end::: + :::column span="2"::: + Create a dedicated dashboard to track the progress of tests, builds, and deployments by adding the following widgets: + - [Build history](widget-catalog.md#build-history-widget) + - [Deployment status (Build pipeline)](widget-catalog.md#deployment-status-widget) + - [Release Pipeline overview](widget-catalog.md#release-definition-widget) + - [Requirements quality](widget-catalog.md#requirements-quality-widget)
      + **Build History** + :::image type="content" source="media/dashboard-focus/release-pipeline-widget.png" alt-text="Screenshot of Release pipeline overview chart.":::
      + **Release pipeline overview** + :::image type="content" source="media/dashboard-focus/release-pipeline-widget.png" alt-text="Screenshot of Release pipeline overview chart.":::
      + **Deployment status** + :::image type="content" source="media/dashboard-focus/deployment-status-widget.png" alt-text="Screenshot of Deployment status widget."::: + :::column-end::: +:::row-end::: ## Extend your dashboard visibility -You can add Kanban boards and dashboards as tabs to your Teams channel. -[Configure Azure DevOps Services tabs in Microsoft Teams](../../boards/integrations/boards-teams.md#configure-azure-devops-services-tabs-in-microsoft-teams) +Add boards and dashboards as tabs to your Teams channel. For more information, see [Configure Azure DevOps tabs in Microsoft Teams](../../boards/integrations/boards-teams.md#configure-azure-devops-services-tabs-in-microsoft-teams). ## Related articles -- [Example query charts](../../boards/queries/example-query-charts.md) -- [FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml) -- [Test progress report](../../test/progress-report.md) -- [Pipeline reports](../../pipelines/reports/pipelinereport.md) -- [Test Analytics](../../pipelines/test/test-analytics.md) -- [Widget catalog](widget-catalog.md) -- [Marketplace widgets](https://marketplace.visualstudio.com/search?term=widget&target=VSTS&category=All%20categories&sortBy=Relevance) - - +- [Explore example query charts](../../boards/queries/example-query-charts.md) +- [Read FAQs about dashboards, charts, and reports](faqs.yml) +- [Review the test progress report](../../test/progress-report.md) +- [Check pipeline reports](../../pipelines/reports/pipelinereport.md) +- [Analyze test analytics](../../pipelines/test/test-analytics.md) +- [Browse the widget catalog](widget-catalog.md) +- [Find marketplace widgets](https://marketplace.visualstudio.com/search?term=widget&target=VSTS&category=All%20categories&sortBy=Relevance) diff --git a/docs/report/dashboards/dashboard-permissions.md b/docs/report/dashboards/dashboard-permissions.md index 1a776d5a050..c534882e410 100644 --- a/docs/report/dashboards/dashboard-permissions.md +++ b/docs/report/dashboards/dashboard-permissions.md @@ -8,7 +8,7 @@ ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 02/02/2022 +ms.date: 10/25/2024 --- # Set dashboard permissions @@ -19,89 +19,49 @@ ms.date: 02/02/2022 ::: moniker range=">= azure-devops-2020" -Dashboards are viewable by all members of the Project Valid Users group. Permissions to edit or delete dashboards or manage permissions can be set for both team or project dashboards. - -As a member of the Project Administrators group, you can set the default dashboard permissions for all teams. As a team or project administrator, you can set individual dashboard permissions for team members. The permissions only impact the team members and their team dashboards. - -::: moniker-end - -::: moniker range="azure-devops-2019" +Dashboards are viewable by all members of the Project Valid Users group. Permissions to edit, delete, or manage dashboards can be configured for both team and project dashboards. -As a member of the Project Administrators group, you can set the default dashboard permissions for all teams. As a team or project administrator, you can set individual dashboard permissions for team members. The permissions only impact the team members and their team dashboards. +As a member of the Project Administrators group, you can set the default dashboard permissions for all teams. As a team or project administrator, you have the flexibility to set individual dashboard permissions for team members. This enables you to tailor permissions based on the specific needs and roles of each team member. These permissions only impact the team members and their respective team dashboards, allowing for granular control over who can edit, delete, or manage dashboards. -::: moniker-end - -::: moniker range="tfs-2018" -As a team or project administrator, you can set individual dashboard permissions for team members. The permissions only impact the team members and their team dashboards. +By configuring these permissions, you ensure that only authorized users can make changes to dashboards, maintaining the integrity and organization of your project data. ::: moniker-end +For more information about adding and viewing dashboards, see [Add, rename, and delete dashboards](dashboards.md). -To learn more about adding and viewing dashboards, see [Add, rename, and delete dashboards](dashboards.md). - -> [!TIP] -> If a user reports that they can't create or edit a team dashboard, and you've set the permissions to allow them to do so, check that they have been added as a member of the team. This includes adding them as a team member to the default project team. For details, see [Add users to a project or specific team](../../organizations/security/add-users-team-project.md). - -::: moniker range=">= azure-devops-2019" +> [!TIP] +> If a user reports that they can't create or edit a team dashboard despite having the necessary permissions, ensure they are added as a member of the team. This includes adding them as a member of the default project team. For more information, see [Add users to a project or specific team](../../organizations/security/add-users-team-project.md). -## Prerequisites - -::: moniker-end +## Prerequisites ::: moniker range=">= azure-devops-2020" -- If you haven't been added as a team member, [get added now](../../organizations/security/add-users-team-project.md). -- All members of the Project Valid Users group can view dashboards. -- To add, edit, or manage a team dashboard, you must have **Basic** access or greater and be a [team admin](../../organizations/settings/add-team-administrator.md), a project admin, or have dashboard permissions. In general, you need to be a team member for the currently selected team to edit dashboards. -- To add, edit, or manage project dashboards, you must have **Basic** access or greater, a project admin, or have dashboard permissions. In general, you need to be a team member for the currently selected team to edit dashboards. - -::: moniker-end - - -::: moniker range="azure-devops-2019" - -- If you haven't been added as a team member, [get added now](../../organizations/security/add-users-team-project.md). -- All members of the Project Valid Users group can view dashboards. -- To add, edit, or manage a team dashboard, you must have **Basic** access or greater and be a [team admin](../../organizations/settings/add-team-administrator.md), a project admin, or have dashboard permissions. In general, you need to be a team member for the currently selected team to edit dashboards. +| Category | Requirements | +|-------------|-------------| +|**Access levels** |- All members of the Project Valid Users group can view dashboards.
      - To add, edit, or manage a team or project dashboard: [Team member](../../organizations/security/add-users-team-project.md)
      - At least **Basic** access. | +|**Permissions** |- **Team dashboards**: To add, edit, or manage a team dashboard: [Team administrator](../../organizations/settings/add-team-administrator.md), project administrator, or **Edit dashboard** permissions set to **Allow**.
      - **Project dashboards**: To add, edit, or manage project dashboards: Project administrator, or [Edit dashboard](./dashboard-permissions.md) permissions set to **Allow**.| ::: moniker-end -::: moniker range=">= azure-devops-2019" - ## Set default team dashboard permissions -By default, all team members have permissions to create and edit dashboards for their teams. All members of the Project Administrators or Project Collection Administrators group and team administrators can set the default dashboard permissions for a team. - -::: moniker-end - -::: moniker range=">= azure-devops-2020" +By default, all team members have permissions to create and edit dashboards for their teams. All members of the Project Administrators or Project Collection Administrators group and team administrators can set the default dashboard permissions for a team. -1. Select **Project Settings** and then **Dashboards**. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Web portal, Project Settings, open Dashboards.](media/set-permissions/project-setting-permissions-s167.png) - -1. Slide to enable or disable those permissions you want to grant or restrict. Your changes are automatically saved by the system. - -::: moniker-end - -::: moniker range="azure-devops-2019" - -1. Select **Project Settings** and then **Dashboards**. +1. Select **Project settings** > **Dashboards**. > [!div class="mx-imgBorder"] > ![Screenshot of Web portal, Project Settings, open Dashboards, Azure DevOps Server 2019.](media/set-permissions/project-setting-permissions.png) -1. Check or uncheck those permissions you want to grant or restrict. Your changes are automatically saved by the system. - -::: moniker-end +2. Move the toggle to enable or disable those permissions you want to grant or restrict. + + The system automatically saves your changes. ## Set individual team dashboard permissions -> [!NOTE] -> The dashboard permissions dialog doesn't support granting permissions to other users or groups at this time. You can only change the default settings made for the team. +> [!NOTE] +> The dashboard permissions dialog currently doesn't support granting permissions to other users or groups. You can only modify the default settings for the team. ::: moniker range=">= azure-devops-2020" @@ -121,49 +81,6 @@ By default, all team members have permissions to create and edit dashboards for ::: moniker-end - -::: moniker range="azure-devops-2019" - -1. Open the [Dashboards directory](dashboards.md), select the :::image type="icon" source="../../media/icons/actions-icon.png" border="false"::: actions icon for the dashboard, and then select the **Security** menu option. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Dashboards directory, open Security for a dashboard, Azure DevOps Server 2019.](media/set-permissions/open-dashboard-security.png) - -1. Change **Allow** or **Deny** to grant or restrict a permission. - - Here we restrict team members from editing the Analytics dashboard. Only Fabrikam team administrators can edit the Analytics dashboard. - - > [!div class="mx-imgBorder"] - > ![Permissions for Analytics dashboard dialog, Azure DevOps Server 2019.](media/set-permissions/dashboard-permission-dialog.png) - -2. Select **Save changes** and then **Close**. - -::: moniker-end - -::: moniker range="tfs-2018" - -By default, all team members have permissions to edit dashboards defined for the team. Other valid users of the project have view only permissions, except for administrators. You can change the view, edit, and manage permissions for every team dashboard for members of your team. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. To change the permissions for a specific dashboard, open the dashboard and then select the ![configure icon](media/icons/configure-icon.png) wrench icon for the dashboard. - - For example, here we open the Manage Dashboards dialog for the Fabrikam Fiber Web team's Test dashboard. - - ![Screenshot of Open Manage dashboards dialog for TFS 2018.](media/dashboards-configure-ts.png) - -2. Select the **Permissions** tab and check those checkboxes to grant or restrict permissions to your team members to edit and manage team dashboards. The default settings, as shown in the illustration, provide all team members permissions to edit and manage dashboards. - - > [!div class="mx-imgBorder"] - > ![Screenshot of Manage dashboards permissions dialog for TFS 2018.](media/dashboards-permissions.png) - -3. Select **Save** to save your changes and dismiss the Settings dialog. - -::: moniker-end - - ::: moniker range=">= azure-devops-2020" ## Set permissions for a project dashboard @@ -180,16 +97,15 @@ By default, all team members have permissions to edit dashboards defined for the > [!div class="mx-imgBorder"] > ![Dialog for a Project dashboard, add user and set permissions.](media/set-permissions/add-user-project-permissions.png) -1. Close the dialog when finished. +2. Close the dialog. -1. Reopen the security dialog to verify the changes were made. +3. Reopen the security dialog to verify the changes were made. > [!div class="mx-imgBorder"] > ![Project dashboard permissions dialog.](media/set-permissions/project-dashboard-permissions-added.png) ::: moniker-end - ## Related articles - [Add, rename, and delete dashboards](dashboards.md) diff --git a/docs/report/dashboards/dashboards.md b/docs/report/dashboards/dashboards.md index 9b2f5c48dc4..6faab994746 100644 --- a/docs/report/dashboards/dashboards.md +++ b/docs/report/dashboards/dashboards.md @@ -20,12 +20,8 @@ ms.date: 07/07/2022 Share progress and status with your team using configurable team or project dashboards. Dashboards provide easy-to-read, easy access, real-time information. At a glance, you can make informed decisions without having to drill down into other parts of your project. ::: moniker-end -::: moniker range="<= azure-devops-2019" -Share progress and status with your team using configurable team dashboards. Dashboards provide easy-to-read, easy access, real-time information. At a glance, you can make informed decisions without having to drill down into other parts of your project. -::: moniker-end - -When a project is first created, a default team and default team dashboard is created labeled *Overview*. You can customize this dashboard by adding widgets. Each widget provides access to one or more features or functions. To learn more about each widget, see [Widget catalog](widget-catalog.md). +When a project is first created, a default team and default team dashboard is created labeled *Overview*. You can customize this dashboard by adding widgets. Each widget provides access to one or more features or functions. For more information about each widget, see [Widget catalog](widget-catalog.md). ::: moniker range=">= azure-devops-2020" @@ -37,23 +33,19 @@ When you add a dashboard, you can choose to make it a project dashboard or one s > Project dashboards are owned by the person that created the dashboard. The owner can set permissions as to who can edit the dashboard. Team dashboards are owned by team administrators and can be edited by any member of the team. All dashboards can be viewed by members of the project. All widgets available to team dashboards are available for project dashboards. For team-specific widgets, if you aren't able to select a team through the widget, then the team defaults to the default project team. ::: moniker-end - -[!INCLUDE [temp](../includes/dashboard-prerequisites.md)] +## Prerequisites + +[!INCLUDE [temp](../includes/dashboard-prerequisites.md)] ## Open Dashboards ::: moniker range=">= azure-devops-2020" All dashboards are associated with either a team or a project. From the **Overview>Dashboards** page, you can browse all dashboards and see which team they belong to, or if they are project dashboard. -::: moniker-end -::: moniker range="<= azure-devops-2019" - -All dashboards are associated with a team. From the **Overview>Dashboards** page, you can browse all dashboards and see which team they belong to. - ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Open a web browser, connect to your project, and select **Overview>Dashboards**. The dashboard directory page opens. @@ -75,23 +67,11 @@ If you need to switch to a different project, select the :::image type="icon" so ::: moniker-end - -::: moniker range="tfs-2018" -Open a web browser, connect to your project, and select **Dashboards**. - -![Dashboards directory, previous navigation](media/dashboards-go-to.png) - -If you need to switch to a different project, select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to [browse all projects](../../project/navigation/go-to-project-repo.md). - -::: moniker-end - - - - + ## Select a dashboard -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Select a dashboard from the directory list, or from the selector. To return to the dashboard directory, select the **Browse all dashboards** option. @@ -107,26 +87,12 @@ If you need to switch to a different project, select the :::image type="icon" so ::: moniker-end - -::: moniker range="tfs-2018" - -1. Select the team whose dashboards you want to view. To switch your team focus, see [Switch project or team](../../project/navigation/go-to-project-repo.md#switch-team-context). - -2. From **Dashboards**, select the name of the dashboard to view it. - - For example, here we choose to view the Work in Progress dashboard. - - > [!div class="mx-imgBorder"] - > ![Dashboards, Select a team dashboard](media/dashboards/choose-dashboard.png) - -::: moniker-end - + ## Add a dashboard Add a new dashboard as needed to support your team's needs. You can also edit and rename any existing dashboards associated with your team. - > [!NOTE] > There is a limit of 500 dashboards per project. You'll receive an error message if you try to create a dashboard beyond that limit. Delete unused dashboards to resolve the error. @@ -145,7 +111,7 @@ Add a new dashboard as needed to support your team's needs. You can also edit an > [!div class="mx-imgBorder"] > ![Create a Project dashboard.](media/dashboards/create-dashboard-project-dialog.png) -1. Select **Save**. +1. Select **Create**. 3. The widget catalog opens. You can add one or more widgets to the dashboard. You can then configure and resize each widget as needed. @@ -155,41 +121,6 @@ Add a new dashboard as needed to support your team's needs. You can also edit an ::: moniker-end -::: moniker range="azure-devops-2019" - -1. From the Dashboards directory, select **New Dashboard**. Or, when viewing a dashboard, open the selector and select the :::image type="icon" source="media/icons/blue-plus-icon.png" border="false"::: **New Dashboard** option. - - > [!div class="mx-imgBorder"] - > ![Open the create a dashboard dialog](media/dashboards/open-new-dashboard-dialog.png) - - If you don't see the :::image type="icon" source="media/icons/blue-plus-icon.png" border="false"::: **New Dashboard** option, then you're not a team admin for the currently selected team, or you don't have permissions to add and edit dashboards. Either [switch the context to your team](../../project/navigation/go-to-project-repo.md?toc=/azure/devops/report/toc.json&bc=/azure/devops/report/breadcrumb/toc.json), or request you be added as a [team admin](../../organizations/settings/add-team-administrator.md?toc=/azure/devops/report/toc.json&bc=/azure/devops/report/breadcrumb/toc.json). - -2. Enter the name of the dashboard and other information you want to capture. - - > [!div class="mx-imgBorder"] - > ![Create a dashboard dialog](media/dashboards/create-dashboard-bug-status.png) - -1. Select **Save**. - -3. The widget catalog opens. You can add one or more widgets to the dashboard. You can then configure and resize each widget as needed. - -4. You can move the widgets around the dashboard to place them where you want them. - -5. When you're done making changes, select **Done Editing**. - -::: moniker-end - -::: moniker range="tfs-2018" - -From **Dashboards**, select :::image type="icon" source="../../boards/media/icons/green_plus_icon.png" border="false"::: **New Dashboard** and enter a dashboard name. - -![Add and name a dashboard](media/dashboards-new-ts.png) - -If you don't see :::image type="icon" source="../../boards/media/icons/green_plus_icon.png" border="false"::: **Edit** icon, then you're not a team admin for the currently selected team, or you don't have permissions to add and edit dashboards. Either [switch the context to your team](../../project/navigation/go-to-project-repo.md?toc=/azure/devops/report/dashboards/toc.json&bc=/azure/devops/report/breadcrumb/dashboards/toc.json), or request you be added as a [team admin](../../organizations/settings/add-team-administrator.md?toc=/azure/devops/report/dashboards/toc.json&bc=/azure/devops/report/breadcrumb/dashboards/toc.json). - -With the dashboard selected, you can add [widgets and charts to the dashboard](add-widget-to-dashboard.md). Or, you can [add charts to a team dashboard from the Work, Build, or Test pages](add-charts-to-dashboard.md). -::: moniker-end - ## Rename, delete, and enable auto-refresh @@ -198,11 +129,10 @@ You can rename or delete a dashboard. When you enable auto-refresh, the dashboar ::: moniker range=">= azure-devops-2020" > [!NOTE] -> To delete a project dashboard, you must be a member of the[**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md). +> To delete a project dashboard, be a member of the[**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md). ::: moniker-end - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" - To rename a dashboard, modify its description, or change its automatic refresh setting, open the dashboard, select the ![gear icon](media/icons/gear-icon.png) gear icon, and change the field options shown. Save your changes. @@ -214,33 +144,12 @@ You can rename or delete a dashboard. When you enable auto-refresh, the dashboar - To set permissions for a dashboard, select the **Security** option. For details, see [Set dashboard permissions](dashboard-permissions.md). ::: moniker-end -::: moniker range="tfs-2018" -1. To manage dashboards, select the ![configure icon](media/icons/configure-icon.png) wrench icon. - - ![Open Manage dashboards dialog](media/dashboards-configure-ts.png) - -2. Drag and drop the dashboards into the sequence you want them to appear. - - ![Manage dashboards dialog](media/manage-dashboards-ts.png) - -3. (Optional) Select the Auto-refresh checkbox when you want the dashboard to refresh every five minutes. - -4. To delete a dashboard, select the :::image type="icon" source="media/icons/delete_icon.png" border="false"::: delete icon. - -5. Select **Save** to save your changes. - -You can also [manage dashboard permissions](dashboard-permissions.md). -::: moniker-end - - -## Move or delete a widget - -Just as you have to be a team admin, a project admin, or have the necessary permissions to add items to a dashboard, you must have the [necessary permissions](#permissions) to remove items. +## Move or delete a widget > [!TIP] > When you're in dashboard edit mode, you can remove, rearrange, and configure widgets, as well as add new widgets. Once you leave edit mode, the widget tiles remain locked, reducing the chances of accidentally moving a widget. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Select :::image type="icon" source="media/icons/edit-icon.png" border="false"::: **Edit** to modify your dashboard. You can now add widgets or drag tiles to reorder their sequence on the dashboard. @@ -253,21 +162,9 @@ To remove a widget, select ![actions icon](../../media/icons/actions-icon.png) * When you're finished with your changes, select **Done Editing** to exit dashboard edit mode. ::: moniker-end -::: moniker range="tfs-2018" -Select ![Edit dashboard icon](media/edit-dashboard-icon.png) to modify your dashboard. You can then drag tiles to reorder their sequence on the dashboard. - -You can now add widgets or drag tiles to reorder their sequence on the dashboard. - -To remove a widget, select the widget's ![Trash icon](media/dashboard-trash-icon.png) or ![Delete icon](media/dashboard-delete-icon.png) delete icons. - -When you're finished with your changes, select ![Exit edit-dashboard-mode icon](media/exit-edit-dashboard-mode-icon.png) to exit dashboard editing. - -::: moniker-end - ## Extensibility -Using the REST API service, you can [create a dashboard widget](../../extend/develop/add-dashboard-widget.md). To learn more about the REST APIs for dashboards and widgets, see [Dashboards (API)](/rest/api/azure/devops/dashboard/dashboards). - +Using the REST API service, you can [create a dashboard widget](../../extend/develop/add-dashboard-widget.md). For more information about the REST APIs for dashboards and widgets, see [Dashboards (API)](/rest/api/azure/devops/dashboard/dashboards). ## Try this next @@ -283,4 +180,3 @@ As you can see, you can use team dashboards to provide guidance and keep your te - [Widget catalog](widget-catalog.md) - [Marketplace widgets](https://marketplace.visualstudio.com/search?term=widget&target=VSTS&category=All%20categories&sortBy=Relevance) - diff --git a/docs/report/dashboards/faqs.yml b/docs/report/dashboards/faqs.yml index 2774ab55a57..902b4a0e011 100644 --- a/docs/report/dashboards/faqs.yml +++ b/docs/report/dashboards/faqs.yml @@ -26,23 +26,22 @@ sections: - question: Who can create and view dashboards? answer: | - All members of an Azure DevOps project can view dashboards. Only members with **Basic** access or greater can create and edit dashboards. For details on managing dashboard permissions, see [Set dashboard permissions](dashboard-permissions.md). + All members of an Azure DevOps project can view dashboards. Only members with at least **Basic** access can create and edit dashboards. For details on managing dashboard permissions, see [Set dashboard permissions](dashboard-permissions.md). - question: Can I restrict who can view my dashboards? answer: | - **Yes**. From the user interface, you can't set read permissions on a dashboard. However, using permission management command-line tools, you can set more granular permissions, such as `Read`, `Create`, and `MaterializeDashboard` permissions. To learn more, see [Security namespace and permission reference](../../organizations/security/namespace-reference.md). + **Yes**. From the user interface, you can't set read permissions on a dashboard. However, using permission management command-line tools, you can set more granular permissions, such as `Read`, `Create`, and `MaterializeDashboard` permissions. For more information, see [Security namespace and permission reference](../../organizations/security/namespace-reference.md). - question: Can I share a dashboard with a non-project member? answer: | **No**. Only users who are valid project members can view dashboards. They must sign in to the web portal for a project to view a dashboard. - - question: Are there restrictions on what charts or data project members can view in a dashboard? answer: | - Dashboard charts and widgets contain data that is subject to their own permissions and access levels. Project members with **Basic** access or greater can view dashboard charts and reports if they have the necessary permissions, most of which are granted by default. Members granted **Stakeholder** access can't view any code-related charts or reports. + Dashboard charts and widgets contain data that is subject to their own permissions and access levels. Project members with at least **Basic** access can view dashboard charts and reports if they have the necessary permissions, most of which are granted by default. Members granted **Stakeholder** access can't view any code-related charts or reports. In general, if users aren't granted the following permissions, they won't be able to view the data for the corresponding chart or widget: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - **View work items in this node** (Area Path permission): Required to view queries and work items displayed in a query or dashboard chart - **Read** (query permission): Required to view query-based charts and widgets - **View analytics** (project-level permission): Required to view Analytics data in chart widgets and built-in reports @@ -52,15 +51,7 @@ sections: - **View release pipeline, View releases** (release object-level permission): Required to view release pipeline data - **View test runs** (project-level permission): Required to view rest run data ::: moniker-end - ::: moniker range="< azure-devops-2019" - - **View work items in this node** (Area Path permission): Required to view queries and work items displayed in a query or dashboard chart - - **View work items in this node** (Area Path permission): Required to view queries and work items displayed in a query or dashboard chart - - **Read** (query permission): Required to view query-based charts - - **Read** (Git or TFVC repository permission): Required to view code tile charts - - **View build pipeline, View builds** (build object-level permissions): Required to view build pipeline data - - **View release pipeline, View releases** (release object-level permission): Required to view release pipeline data - - **View test runs** (project-level permission): Required to view rest run data - ::: moniker-end + > [!NOTE] > The ability for a project member to view query results from a query or dashboard can be impacted by membership within another group. For example, if a project member belongs to two or more groups—and one of the groups has lesser permissions than the other—then the lesser permissions apply. For example, if the group is a member of a **Readers** group, which may have **View** permissions denied, then they wouldn’t be able to view queries with work items where they didn’t have view permissions. @@ -72,7 +63,7 @@ sections: - question: Can I create a private dashboard? answer: | - **No**. You can only create a dashboard and set permissions on the dashboard. To limit who can view the dashboard, you can use a permission management command-line tool. To learn more, see [Security namespace and permission reference](../../organizations/security/namespace-reference.md). + **No**. You can only create a dashboard and set permissions on the dashboard. To limit who can view the dashboard, you can use a permission management command-line tool. For more information, see [Security namespace and permission reference](../../organizations/security/namespace-reference.md). - question: I added a widget but it isn't displaying any data, what's going on? answer: | @@ -81,7 +72,7 @@ sections: - question: Can I copy a dashboard? answer: | ::: moniker range=">= azure-devops-2022" - **Yes**. You can copy a project or team dashboard to another dashboard, project or team. To learn how, see [Copy a dashboard](copy-dashboard.md). If you copy a dashboard to a team dashboard, you must be a member of the team to edit it. Also, when you copy a dashboard with widgets that reference queries, you must choose a **Shared Queries** folder where you have permissions to contribute. + **Yes**. You can copy a project or team dashboard to another dashboard, project or team. To learn how, see [Copy a dashboard](copy-dashboard.md). If you copy a dashboard to a team dashboard, be a member of the team to edit it. Also, when you copy a dashboard with widgets that reference queries, you must choose a **Shared Queries** folder where you have permissions to contribute. ::: moniker-end ::: moniker range="< azure-devops-2022" **No**. This feature is currently available for Azure DevOps Services only at this time. It should be available in later versions of Azure DevOps Server in the future. @@ -103,7 +94,7 @@ sections: - question: Can I copy a query chart? answer: | ::: moniker range="azure-devops" - **Yes**. You can copy a query-based widget from one dashboard to another. To learn how, see [Add widgets to a dashboard](add-widget-to-dashboard.md#copy-a-widget). Also, when you copy a dashboard, it copies any query charts added to the dashboard and configures them for the team you select. This essentially adds new queries and configures the charts. To learn more, see [Copy a dashboard](copy-dashboard.md). + **Yes**. You can copy a query-based widget from one dashboard to another. To learn how, see [Add widgets to a dashboard](add-widget-to-dashboard.md#copy-a-widget). Also, when you copy a dashboard, it copies any query charts added to the dashboard and configures them for the team you select. This essentially adds new queries and configures the charts. For more information, see [Copy a dashboard](copy-dashboard.md). ::: moniker-end ::: moniker range="< azure-devops" **Yes**. You can copy a query-based widget from one dashboard to another. To learn how, see [Add widgets to a dashboard](add-widget-to-dashboard.md#copy-a-widget). @@ -124,13 +115,13 @@ sections: - question: Can I create a query chart from a direct links or tree query? answer: | - **No**. All query-based charts require configuration of flat-list queries. To learn more, see [Track progress with status and trend query-based charts](charts.md). + **No**. All query-based charts require configuration of flat-list queries. For more information, see [Track progress with status and trend query-based charts](charts.md). - question: How do I view project dependencies? answer: | The best way to view work item dependencies are to use **Delivery Plans** as described in [Track dependencies](../../boards/plans/track-dependencies.md). To view dependencies in a dashboard, you can add a query results widget that lists a direct links query. - - question: What charts or widgets support PERT or Gannt charts? + - question: What charts or widgets support PERT or Gantt charts? answer: | Two project management tools in wide use are Program Evaluation Review Technique (PERT) charts and Gantt charts. PERT charts provide support for calculating the amount of time it will take to realistically finish a project. Horizontal bar charts developed by Henry Gantt provide support for visualizing project schedules. Azure DevOps doesn't provide native support for either PERT or Gantt charts. However, it does provide the following tools and extensions that support visualizing schedules and dependencies: ::: moniker range=">= azure-devops-2022" @@ -139,7 +130,7 @@ sections: - [**Gantt-chart extensions**](https://marketplace.visualstudio.com/search?term=Gantt&target=AzureDevOps&category=All%20categories&sortBy=Relevance): Marketplace extensions that provide support for visualizing portfolio roadmaps. ::: moniker-end ::: moniker range="< azure-devops" - - [**Delivery Plans**](../../boards/extensions/delivery-plans.md): A marketplace extension that displays scheduled work items by sprint of selected teams against a calendar view. + - [**Delivery Plans**](../../boards/plans/review-team-plans.md): A marketplace extension that displays scheduled work items by sprint of selected teams against a calendar view. - [**Dependency Tracker**](../../boards/extensions/dependency-tracker.md)): A marketplace extension that supports planning and managing dependencies across teams, projects, and organizations. It provides filterable views to show all dependencies a team is consuming and producing. - [**Gantt-chart extensions**](https://marketplace.visualstudio.com/search?term=Gantt&target=AzureDevOps&category=All%20categories&sortBy=Relevance): Marketplace extensions that provide support for visualizing portfolio roadmaps. ::: moniker-end @@ -154,14 +145,14 @@ sections: - question: Do sprint burndown or burnup charts reference team capacity settings? answer: | - **Yes**. Team days off and team member capacity are referenced in sprint burndown charts and reports. To learn more about setting team capacity, see [Determine and set sprint capacity](../../boards/sprints/set-capacity.md). + **Yes**. Team days off and team member capacity are referenced in sprint burndown charts and reports. For more information about setting team capacity, see [Determine and set sprint capacity](../../boards/sprints/set-capacity.md). - name: Cross-project data views questions: - question: How do I view data from several projects in one dashboard? answer: | There are a few ways to view data from several projects in a single dashboard. - - **Query-based widgets**: Queries can be defined in any project that target all or select projects. Charts based on these queries can be added to any dashboard. To learn more, see [Define a work item query, Query across or within projects](../../boards/queries/using-queries.md#query-across-projects). + - **Query-based widgets**: Queries can be defined in any project that target all or select projects. Charts based on these queries can be added to any dashboard. For more information, see [Define a work item query, Query across or within projects](../../boards/queries/using-queries.md). - **Burndown and Burnup charts**: The [Burndown and Burnup charts](configure-burndown-burnup-widgets.md) can be configured for any project and team. Therefore, you can add several of these charts to a single chart and configure them to gain a view of progress across several teams and projects. diff --git a/docs/report/dashboards/media/add-charts/add-analytics-chart.png b/docs/report/dashboards/media/add-charts/add-analytics-chart.png index a9b4e42675d..a587061694a 100644 Binary files a/docs/report/dashboards/media/add-charts/add-analytics-chart.png and b/docs/report/dashboards/media/add-charts/add-analytics-chart.png differ diff --git a/docs/report/dashboards/media/add-charts/add-release-pipeline-to-dashboard-new-nav.png b/docs/report/dashboards/media/add-charts/add-release-pipeline-to-dashboard-new-nav.png index b28256b3e7d..fe6a73f54e5 100644 Binary files a/docs/report/dashboards/media/add-charts/add-release-pipeline-to-dashboard-new-nav.png and b/docs/report/dashboards/media/add-charts/add-release-pipeline-to-dashboard-new-nav.png differ diff --git a/docs/report/dashboards/media/add-charts/boards-queries-charts-sequence.png b/docs/report/dashboards/media/add-charts/boards-queries-charts-sequence.png new file mode 100644 index 00000000000..ca93f99b729 Binary files /dev/null and b/docs/report/dashboards/media/add-charts/boards-queries-charts-sequence.png differ diff --git a/docs/report/dashboards/media/add-charts/pin-chart-to-a-dashboard.png b/docs/report/dashboards/media/add-charts/pin-chart-to-a-dashboard.png new file mode 100644 index 00000000000..8ed22504279 Binary files /dev/null and b/docs/report/dashboards/media/add-charts/pin-chart-to-a-dashboard.png differ diff --git a/docs/report/dashboards/media/add-charts/select-dashboard.png b/docs/report/dashboards/media/add-charts/select-dashboard.png new file mode 100644 index 00000000000..9dbcbb0656e Binary files /dev/null and b/docs/report/dashboards/media/add-charts/select-dashboard.png differ diff --git a/docs/report/dashboards/media/add-charts/select-in-context-work-tracking-dashboard.png b/docs/report/dashboards/media/add-charts/select-in-context-work-tracking-dashboard.png new file mode 100644 index 00000000000..a00f8fa5e3f Binary files /dev/null and b/docs/report/dashboards/media/add-charts/select-in-context-work-tracking-dashboard.png differ diff --git a/docs/report/dashboards/media/add-markdown-size.png b/docs/report/dashboards/media/add-markdown-size.png index 11d2bb6056e..6582312235e 100644 Binary files a/docs/report/dashboards/media/add-markdown-size.png and b/docs/report/dashboards/media/add-markdown-size.png differ diff --git a/docs/report/dashboards/media/add-widgets/configure-widget.png b/docs/report/dashboards/media/add-widgets/configure-widget.png index e0732e43950..4155b049773 100644 Binary files a/docs/report/dashboards/media/add-widgets/configure-widget.png and b/docs/report/dashboards/media/add-widgets/configure-widget.png differ diff --git a/docs/report/dashboards/media/burndown-widget/add-widget.png b/docs/report/dashboards/media/burndown-widget/add-widget.png index 687359faae0..18e89d11570 100644 Binary files a/docs/report/dashboards/media/burndown-widget/add-widget.png and b/docs/report/dashboards/media/burndown-widget/add-widget.png differ diff --git a/docs/report/dashboards/media/burndown-widget/burndownup-release-burndown-with-markup.png b/docs/report/dashboards/media/burndown-widget/burndownup-release-burndown-with-markup.png index bb4e202e95f..910d769d3fe 100644 Binary files a/docs/report/dashboards/media/burndown-widget/burndownup-release-burndown-with-markup.png and b/docs/report/dashboards/media/burndown-widget/burndownup-release-burndown-with-markup.png differ diff --git a/docs/report/dashboards/media/burndown-widget/burndownup-release-burndown.png b/docs/report/dashboards/media/burndown-widget/burndownup-release-burndown.png index db90db062a6..3792695d7b8 100644 Binary files a/docs/report/dashboards/media/burndown-widget/burndownup-release-burndown.png and b/docs/report/dashboards/media/burndown-widget/burndownup-release-burndown.png differ diff --git a/docs/report/dashboards/media/burndown-widget/select-dashboards-edit.png b/docs/report/dashboards/media/burndown-widget/select-dashboards-edit.png index ddc5ae252f0..a47985935e2 100644 Binary files a/docs/report/dashboards/media/burndown-widget/select-dashboards-edit.png and b/docs/report/dashboards/media/burndown-widget/select-dashboards-edit.png differ diff --git a/docs/report/dashboards/media/burndown/add-sprint-burndown-widget-devops.png b/docs/report/dashboards/media/burndown/add-sprint-burndown-widget-devops.png index c2fc74eabbf..91e75c63b39 100644 Binary files a/docs/report/dashboards/media/burndown/add-sprint-burndown-widget-devops.png and b/docs/report/dashboards/media/burndown/add-sprint-burndown-widget-devops.png differ diff --git a/docs/report/dashboards/media/burndown/analytics-burndown-count-of-work-items-s159.png b/docs/report/dashboards/media/burndown/analytics-burndown-count-of-work-items-s159.png index 52d709503bd..a92f40244ba 100644 Binary files a/docs/report/dashboards/media/burndown/analytics-burndown-count-of-work-items-s159.png and b/docs/report/dashboards/media/burndown/analytics-burndown-count-of-work-items-s159.png differ diff --git a/docs/report/dashboards/media/burndown/analytics-burndown-remaining-work-s159.png b/docs/report/dashboards/media/burndown/analytics-burndown-remaining-work-s159.png index 4d90314024d..4398164fb5a 100644 Binary files a/docs/report/dashboards/media/burndown/analytics-burndown-remaining-work-s159.png and b/docs/report/dashboards/media/burndown/analytics-burndown-remaining-work-s159.png differ diff --git a/docs/report/dashboards/media/burndown/analytics-burndown-story-points.png b/docs/report/dashboards/media/burndown/analytics-burndown-story-points.png index 6fb8e8698b5..ff5e774bda7 100644 Binary files a/docs/report/dashboards/media/burndown/analytics-burndown-story-points.png and b/docs/report/dashboards/media/burndown/analytics-burndown-story-points.png differ diff --git a/docs/report/dashboards/media/burndown/open-analytics.png b/docs/report/dashboards/media/burndown/open-analytics.png index 309c124fa06..6aabd72e003 100644 Binary files a/docs/report/dashboards/media/burndown/open-analytics.png and b/docs/report/dashboards/media/burndown/open-analytics.png differ diff --git a/docs/report/dashboards/media/cfd/analytics-cfd-azure-devops.png b/docs/report/dashboards/media/cfd/analytics-cfd-azure-devops.png index ca0a61f45d4..fcc41739420 100644 Binary files a/docs/report/dashboards/media/cfd/analytics-cfd-azure-devops.png and b/docs/report/dashboards/media/cfd/analytics-cfd-azure-devops.png differ diff --git a/docs/report/dashboards/media/charts/configure-pivot-item-state.png b/docs/report/dashboards/media/charts/configure-pivot-item-state.png new file mode 100644 index 00000000000..9aa1b6bdd74 Binary files /dev/null and b/docs/report/dashboards/media/charts/configure-pivot-item-state.png differ diff --git a/docs/report/dashboards/media/cycle-lead-time-concept-intro.png b/docs/report/dashboards/media/cycle-lead-time-concept-intro.png index 09b7dc10608..45b7ee4debd 100644 Binary files a/docs/report/dashboards/media/cycle-lead-time-concept-intro.png and b/docs/report/dashboards/media/cycle-lead-time-concept-intro.png differ diff --git a/docs/report/dashboards/media/dashboard-view-with-widgets.png b/docs/report/dashboards/media/dashboard-view-with-widgets.png index a052592baf9..3cac4d7ca43 100644 Binary files a/docs/report/dashboards/media/dashboard-view-with-widgets.png and b/docs/report/dashboards/media/dashboard-view-with-widgets.png differ diff --git a/docs/report/dashboards/media/dashboards/filter-directory.png b/docs/report/dashboards/media/dashboards/filter-directory.png index 87b2002391c..d19cba26cb6 100644 Binary files a/docs/report/dashboards/media/dashboards/filter-directory.png and b/docs/report/dashboards/media/dashboards/filter-directory.png differ diff --git a/docs/report/dashboards/media/dashboards/open-dashboards-vert.png b/docs/report/dashboards/media/dashboards/open-dashboards-vert.png index e774bc3931b..43b28f9f56f 100644 Binary files a/docs/report/dashboards/media/dashboards/open-dashboards-vert.png and b/docs/report/dashboards/media/dashboards/open-dashboards-vert.png differ diff --git a/docs/report/dashboards/media/embedded-web-page-widget.png b/docs/report/dashboards/media/embedded-web-page-widget.png index ee885346163..b99076277f8 100644 Binary files a/docs/report/dashboards/media/embedded-web-page-widget.png and b/docs/report/dashboards/media/embedded-web-page-widget.png differ diff --git a/docs/report/dashboards/media/gs-add-dashboard.png b/docs/report/dashboards/media/gs-add-dashboard.png index 8af543129f5..30724b61059 100644 Binary files a/docs/report/dashboards/media/gs-add-dashboard.png and b/docs/report/dashboards/media/gs-add-dashboard.png differ diff --git a/docs/report/dashboards/media/gs-add-widget.png b/docs/report/dashboards/media/gs-add-widget.png index 77db85e08d7..397d841de11 100644 Binary files a/docs/report/dashboards/media/gs-add-widget.png and b/docs/report/dashboards/media/gs-add-widget.png differ diff --git a/docs/report/dashboards/media/gs-chart-create.png b/docs/report/dashboards/media/gs-chart-create.png index fd15cfe8561..8ddb9dad8e9 100644 Binary files a/docs/report/dashboards/media/gs-chart-create.png and b/docs/report/dashboards/media/gs-chart-create.png differ diff --git a/docs/report/dashboards/media/gs-chart-query.png b/docs/report/dashboards/media/gs-chart-query.png index a5135ff9962..e9948a912c4 100644 Binary files a/docs/report/dashboards/media/gs-chart-query.png and b/docs/report/dashboards/media/gs-chart-query.png differ diff --git a/docs/report/dashboards/media/lead-cycle/cycle-lead-time-configure-dialog-s156.png b/docs/report/dashboards/media/lead-cycle/cycle-lead-time-configure-dialog-s156.png index ab355d291c0..8b93aabe4ef 100644 Binary files a/docs/report/dashboards/media/lead-cycle/cycle-lead-time-configure-dialog-s156.png and b/docs/report/dashboards/media/lead-cycle/cycle-lead-time-configure-dialog-s156.png differ diff --git a/docs/report/dashboards/media/lead-cycle/field-criteria-release.png b/docs/report/dashboards/media/lead-cycle/field-criteria-release.png index abecebbf61d..f0d9a47e42e 100644 Binary files a/docs/report/dashboards/media/lead-cycle/field-criteria-release.png and b/docs/report/dashboards/media/lead-cycle/field-criteria-release.png differ diff --git a/docs/report/dashboards/media/pin-chart-to-a-dashboard.png b/docs/report/dashboards/media/pin-chart-to-a-dashboard.png deleted file mode 100644 index 5847b223efb..00000000000 Binary files a/docs/report/dashboards/media/pin-chart-to-a-dashboard.png and /dev/null differ diff --git a/docs/report/dashboards/media/set-permissions/project-setting-permissions-s167.png b/docs/report/dashboards/media/set-permissions/project-setting-permissions-s167.png deleted file mode 100644 index b0e0f2e54a4..00000000000 Binary files a/docs/report/dashboards/media/set-permissions/project-setting-permissions-s167.png and /dev/null differ diff --git a/docs/report/dashboards/media/set-permissions/project-setting-permissions.png b/docs/report/dashboards/media/set-permissions/project-setting-permissions.png index 41afad63267..7127d1060aa 100644 Binary files a/docs/report/dashboards/media/set-permissions/project-setting-permissions.png and b/docs/report/dashboards/media/set-permissions/project-setting-permissions.png differ diff --git a/docs/report/dashboards/media/widget-assigned-to-me.png b/docs/report/dashboards/media/widget-assigned-to-me.png index 7ff144650f8..4748779edf5 100644 Binary files a/docs/report/dashboards/media/widget-assigned-to-me.png and b/docs/report/dashboards/media/widget-assigned-to-me.png differ diff --git a/docs/report/dashboards/media/widget-build-history-chart.png b/docs/report/dashboards/media/widget-build-history-chart.png index 76e12dc4c35..7e4e9827d06 100644 Binary files a/docs/report/dashboards/media/widget-build-history-chart.png and b/docs/report/dashboards/media/widget-build-history-chart.png differ diff --git a/docs/report/dashboards/media/widget-burndown-chart.png b/docs/report/dashboards/media/widget-burndown-chart.png index 8fa1634543c..82b94dceeb4 100644 Binary files a/docs/report/dashboards/media/widget-burndown-chart.png and b/docs/report/dashboards/media/widget-burndown-chart.png differ diff --git a/docs/report/dashboards/media/widget-burnup-chart.png b/docs/report/dashboards/media/widget-burnup-chart.png index b3a5bab2b0f..1ed7233cc16 100644 Binary files a/docs/report/dashboards/media/widget-burnup-chart.png and b/docs/report/dashboards/media/widget-burnup-chart.png differ diff --git a/docs/report/dashboards/media/widget-catalog-pull-request-multi.png b/docs/report/dashboards/media/widget-catalog-pull-request-multi.png index b3d1b3d4722..6255e207069 100644 Binary files a/docs/report/dashboards/media/widget-catalog-pull-request-multi.png and b/docs/report/dashboards/media/widget-catalog-pull-request-multi.png differ diff --git a/docs/report/dashboards/media/widget-catalog-pull-request.png b/docs/report/dashboards/media/widget-catalog-pull-request.png index 3e67c3fdef8..6b17ae7e4de 100644 Binary files a/docs/report/dashboards/media/widget-catalog-pull-request.png and b/docs/report/dashboards/media/widget-catalog-pull-request.png differ diff --git a/docs/report/dashboards/media/widget-cfd-chart.png b/docs/report/dashboards/media/widget-cfd-chart.png index 162853be047..f4c239c2ae4 100644 Binary files a/docs/report/dashboards/media/widget-cfd-chart.png and b/docs/report/dashboards/media/widget-cfd-chart.png differ diff --git a/docs/report/dashboards/media/widget-chart-test-plans.png b/docs/report/dashboards/media/widget-chart-test-plans.png index 87b706c4a94..c7c78e54924 100644 Binary files a/docs/report/dashboards/media/widget-chart-test-plans.png and b/docs/report/dashboards/media/widget-chart-test-plans.png differ diff --git a/docs/report/dashboards/media/widget-chart-work-query.png b/docs/report/dashboards/media/widget-chart-work-query.png index 0f05ce68275..adb4661caa9 100644 Binary files a/docs/report/dashboards/media/widget-chart-work-query.png and b/docs/report/dashboards/media/widget-chart-work-query.png differ diff --git a/docs/report/dashboards/media/widget-code-tile.png b/docs/report/dashboards/media/widget-code-tile.png index a05cede6407..d293716457b 100644 Binary files a/docs/report/dashboards/media/widget-code-tile.png and b/docs/report/dashboards/media/widget-code-tile.png differ diff --git a/docs/report/dashboards/media/widget-cycle-time.png b/docs/report/dashboards/media/widget-cycle-time.png index d2957c55726..84463e75c6e 100644 Binary files a/docs/report/dashboards/media/widget-cycle-time.png and b/docs/report/dashboards/media/widget-cycle-time.png differ diff --git a/docs/report/dashboards/media/widget-deployment-status.png b/docs/report/dashboards/media/widget-deployment-status.png index d4a8eb6e454..aceb03b8a5b 100644 Binary files a/docs/report/dashboards/media/widget-deployment-status.png and b/docs/report/dashboards/media/widget-deployment-status.png differ diff --git a/docs/report/dashboards/media/widget-how-to-links.png b/docs/report/dashboards/media/widget-how-to-links.png index e81340bffd4..68f060eeacf 100644 Binary files a/docs/report/dashboards/media/widget-how-to-links.png and b/docs/report/dashboards/media/widget-how-to-links.png differ diff --git a/docs/report/dashboards/media/widget-lead-time.png b/docs/report/dashboards/media/widget-lead-time.png index 108da7945c6..f800febf7ff 100644 Binary files a/docs/report/dashboards/media/widget-lead-time.png and b/docs/report/dashboards/media/widget-lead-time.png differ diff --git a/docs/report/dashboards/media/widget-markdown-tile.png b/docs/report/dashboards/media/widget-markdown-tile.png index 8fbf24fa155..cefff1d7678 100644 Binary files a/docs/report/dashboards/media/widget-markdown-tile.png and b/docs/report/dashboards/media/widget-markdown-tile.png differ diff --git a/docs/report/dashboards/media/widget-more-actions-configure.png b/docs/report/dashboards/media/widget-more-actions-configure.png new file mode 100644 index 00000000000..469f13d8b41 Binary files /dev/null and b/docs/report/dashboards/media/widget-more-actions-configure.png differ diff --git a/docs/report/dashboards/media/widget-new-work-items.png b/docs/report/dashboards/media/widget-new-work-items.png index 5ac436511b9..754cd0dd591 100644 Binary files a/docs/report/dashboards/media/widget-new-work-items.png and b/docs/report/dashboards/media/widget-new-work-items.png differ diff --git a/docs/report/dashboards/media/widget-other-links.png b/docs/report/dashboards/media/widget-other-links.png index 44987880fa2..9bbc89b79a8 100644 Binary files a/docs/report/dashboards/media/widget-other-links.png and b/docs/report/dashboards/media/widget-other-links.png differ diff --git a/docs/report/dashboards/media/widget-query-results.png b/docs/report/dashboards/media/widget-query-results.png index a794ebf9dff..0b4f612e663 100644 Binary files a/docs/report/dashboards/media/widget-query-results.png and b/docs/report/dashboards/media/widget-query-results.png differ diff --git a/docs/report/dashboards/media/widget-query-tile.png b/docs/report/dashboards/media/widget-query-tile.png index e4590c4b4d4..d9bf87c29fb 100644 Binary files a/docs/report/dashboards/media/widget-query-tile.png and b/docs/report/dashboards/media/widget-query-tile.png differ diff --git a/docs/report/dashboards/media/widget-release-definitions.png b/docs/report/dashboards/media/widget-release-definitions.png index 402675f7be8..e3a6afbd8b0 100644 Binary files a/docs/report/dashboards/media/widget-release-definitions.png and b/docs/report/dashboards/media/widget-release-definitions.png differ diff --git a/docs/report/dashboards/media/widget-requirements-quality.png b/docs/report/dashboards/media/widget-requirements-quality.png index 799e4a6b993..1ae313789aa 100644 Binary files a/docs/report/dashboards/media/widget-requirements-quality.png and b/docs/report/dashboards/media/widget-requirements-quality.png differ diff --git a/docs/report/dashboards/media/widget-sprint-burndown-analytics.png b/docs/report/dashboards/media/widget-sprint-burndown-analytics.png index a129b6774c7..a12d3aacc9f 100644 Binary files a/docs/report/dashboards/media/widget-sprint-burndown-analytics.png and b/docs/report/dashboards/media/widget-sprint-burndown-analytics.png differ diff --git a/docs/report/dashboards/media/widget-sprint-burndown-legacy.png b/docs/report/dashboards/media/widget-sprint-burndown-legacy.png index e2c0b014dca..6804a53de28 100644 Binary files a/docs/report/dashboards/media/widget-sprint-burndown-legacy.png and b/docs/report/dashboards/media/widget-sprint-burndown-legacy.png differ diff --git a/docs/report/dashboards/media/widget-sprint-burndown.png b/docs/report/dashboards/media/widget-sprint-burndown.png index 9aed7d69153..18a06594ce2 100644 Binary files a/docs/report/dashboards/media/widget-sprint-burndown.png and b/docs/report/dashboards/media/widget-sprint-burndown.png differ diff --git a/docs/report/dashboards/media/widget-sprint-capacity.png b/docs/report/dashboards/media/widget-sprint-capacity.png index 9a91b3fc737..4163075d88e 100644 Binary files a/docs/report/dashboards/media/widget-sprint-capacity.png and b/docs/report/dashboards/media/widget-sprint-capacity.png differ diff --git a/docs/report/dashboards/media/widget-sprint-overview.png b/docs/report/dashboards/media/widget-sprint-overview.png index 7191fa45eda..0b49134540e 100644 Binary files a/docs/report/dashboards/media/widget-sprint-overview.png and b/docs/report/dashboards/media/widget-sprint-overview.png differ diff --git a/docs/report/dashboards/media/widget-team-members.png b/docs/report/dashboards/media/widget-team-members.png index d2950c1c161..cf9b8de7ba9 100644 Binary files a/docs/report/dashboards/media/widget-team-members.png and b/docs/report/dashboards/media/widget-team-members.png differ diff --git a/docs/report/dashboards/media/widget-test-results-trend-advanced.png b/docs/report/dashboards/media/widget-test-results-trend-advanced.png index 0a4cb6d24b6..263e977ceea 100644 Binary files a/docs/report/dashboards/media/widget-test-results-trend-advanced.png and b/docs/report/dashboards/media/widget-test-results-trend-advanced.png differ diff --git a/docs/report/dashboards/media/widget-test-results-trend.png b/docs/report/dashboards/media/widget-test-results-trend.png index 7a4a8dff5b8..c55614a2a16 100644 Binary files a/docs/report/dashboards/media/widget-test-results-trend.png and b/docs/report/dashboards/media/widget-test-results-trend.png differ diff --git a/docs/report/dashboards/media/widget-velocity.png b/docs/report/dashboards/media/widget-velocity.png index b3c99cd439e..a0fc7d4b6a8 100644 Binary files a/docs/report/dashboards/media/widget-velocity.png and b/docs/report/dashboards/media/widget-velocity.png differ diff --git a/docs/report/dashboards/media/widget-visual-studio.png b/docs/report/dashboards/media/widget-visual-studio.png index d6ccb2ed3e5..fa06da159a0 100644 Binary files a/docs/report/dashboards/media/widget-visual-studio.png and b/docs/report/dashboards/media/widget-visual-studio.png differ diff --git a/docs/report/dashboards/media/widget-work-links.png b/docs/report/dashboards/media/widget-work-links.png index f84ed7aa44c..570e6f0c274 100644 Binary files a/docs/report/dashboards/media/widget-work-links.png and b/docs/report/dashboards/media/widget-work-links.png differ diff --git a/docs/report/dashboards/overview.md b/docs/report/dashboards/overview.md index d65b0409bec..6dbdbaa0069 100644 --- a/docs/report/dashboards/overview.md +++ b/docs/report/dashboards/overview.md @@ -1,79 +1,73 @@ --- -title: Understand dashboards, charts, reports & widgets +title: Understand dashboards, charts, reports, and widgets titleSuffix: Azure DevOps -description: Learn about OOB charts, widgets, dashboards, & reports available to monitor status and trends in Azure DevOps. +description: Learn about charts, widgets, dashboards, and reports available to monitor status and trends in Azure DevOps. ms.custom: dashboards ms.assetid: 7BAD53A1-080E-40E8-8866-24EC00395D39 ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: overview +ai-usage: ai-assisted monikerRange: '<= azure-devops' -ms.date: 08/03/2022 +ms.date: 03/12/2025 +#customer intent: As an administrator or team member, I want to understand how using a dashboard can provide visibility into projects for my team. --- -# About dashboards, charts, reports, & widgets +# About dashboards, charts, reports, and widgets [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Gain visibility into your team's progress by adding one or more widgets or charts to your dashboard. Customizable, highly configurable dashboards provide you and your teams with the flexibility to share information, monitor progress and trends, and improve your workflow processes. Each team can tailor their dashboards to share information and monitor their progress. +Gain visibility into your team's progress by adding one or more widgets or charts to your dashboard. Customizable, highly configurable dashboards provide you and your teams with the flexibility to share information, monitor progress and trends, and improve your workflow processes. Each team can tailor their dashboards to share information and monitor their progress. -If you're just starting out, read [Add, rename, and delete dashboards](dashboards.md). Looking for instructions on a specific task, in context chart, widget, or report? See [Dashboards and widgets quick reference](quick-ref.md). To learn about our reporting solutions, read [Reporting Roadmap](../powerbi/reporting-roadmap.md). - -[!INCLUDE [temp](../../includes/version-selector-minimize.md)] +If you're just starting out, read [Add, rename, and delete dashboards](dashboards.md). Looking for instructions on a specific task, in-context chart, widget, or report? See [Dashboards, charts, and quick reference](quick-ref.md). For more information, see the [Reporting roadmap](../powerbi/reporting-roadmap.md). +[!INCLUDE [version selector](../../includes/version-selector.md)] ## Supported capabilities, permissions, and access -Access to Azure DevOps web portal features are managed through access levels assigned to users. +Access to Azure DevOps web portal features are managed through access levels assigned to users. ### Web portal data views and reports The following features provide support for viewing Azure DevOps data through the web portal: -- **Dashboards** are customizable interactive signboards that provide real-time information. Dashboards are associated with a team or a project and display configurable charts and widgets. -- **Charts** are query-based status or trend charts derived from a work item query or test results. -- **Widgets** display configurable information and charts on dashboards. The widget catalog provides brief descriptions of those widgets available to you. Also, you can add widgets provided through the [Azure DevOps Marketplace](https://marketplace.visualstudio.com/azuredevops). -- **In-context reports** are system-generated charts that support specific services. Examples are team velocity, sprint burndown, and the Cumulative Flow Diagram (CFD), and the Test Failures Report. These reports are displayed on the **Analytics** tab for a specific service and derive data from Analytics. - -::: moniker range=">= azure-devops-2019" - -### Power BI reports +- **Dashboards**: Customizable interactive signboards that provide real-time information. Dashboards are associated with a team or a project and display configurable charts and widgets. +- **Charts**: Query-based status or trend charts derived from a work item query or test results. +- **Widgets**: Items that display configurable information and charts on dashboards. The widget catalog provides brief descriptions of those widgets available to you. Also, you can add widgets provided through [Azure DevOps Marketplace](https://marketplace.visualstudio.com/azuredevops). +- **In-context reports**: System-generated charts that support specific services. Examples are team velocity, sprint burndown, the Cumulative Flow Diagram (CFD), and the **Test failures** report. These reports are displayed on the **Analytics** tab for a specific service and derive data from Analytics. -The following features provide support for viewing Azure DevOps data using Power BI: +### Power BI reports -- **Analytics views** provide a simplified way to specify the filter criteria for a Power BI report based on Analytics data for Azure Boards data. To learn more, see [What are Analytics views?](../powerbi/what-are-analytics-views.md). -- **Power BI reports** allow users to create rich, customized Power BI reports or other reports using OData queries of Analytics data and the returned JSON data. For on-premises Azure DevOps environments, project collections must be configured to support the Inherited process. +The following features provide support for viewing Azure DevOps data by using Power BI: - > [!NOTE] - > OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming REST APIs. To learn more, see [OData documentation](/odata/). -::: moniker-end +- **Analytics views**: Provide a simplified way to specify the filter criteria for a Power BI report based on Analytics data for Azure Boards data. For more information, see [About Analytics views](../powerbi/what-are-analytics-views.md). +- **Power BI reports**: Allow users to create rich, customized Power BI reports or other reports using OData queries of Analytics data and the returned JSON data. For on-premises Azure DevOps environments, project collections must be configured to support the Inherited process. +> [!NOTE] +> Open Data Protocol (OData) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming REST APIs. For more information, see [OData documentation](/odata/). ::: moniker range="< azure-devops-2022" -### SQL Server reports +### SQL Server reports -SQL Server Reporting is the legacy reporting solution available with Azure DevOps Server 2020 and earlier versions. The following features provide support for viewing Azure DevOps data using SQL Server Reports and SQL Server Analysis Services. +SQL Server Reporting Services is the legacy reporting solution available with Azure DevOps Server 2020 and earlier versions. The following features provide support for viewing Azure DevOps data by using SQL Server Reports Services and SQL Server Analysis Services. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops-2022" -- **Excel status and trend reports** supports generating custom work tracking reports using Excel starting with a flat-list query. To learn more, see [Create status and trend reports from a work item query](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports). -- **SQL Server reports**: For project collections that support the On-premises XML process model, allow users access to out-of-the-box SQL Server reports and support to create customized SQL Reports or Excel reports. Doing so requires that the project is [configured to support SQL Server reporting](/previous-versions/azure/devops/report/admin/add-a-report-server). +::: moniker range="< azure-devops-2022" + +- **Excel status and trend reports**: Support generating custom work tracking reports by using Excel starting with a flat-list query. For more information, see [Create status and trend reports from a work item query](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports). +- **SQL Server reports**: For project collections that support the On-premises XML process model, allow users access to out-of-the-box SQL Server reports and support to create customized SQL reports or Excel reports. Doing so requires that the project is [configured to support SQL Server reporting](/previous-versions/azure/devops/report/admin/add-a-report-server). + ::: moniker-end - -::: moniker range="tfs-2018" -- **Excel status and trend reports** supports generating custom work tracking reports using Excel starting with a flat-list query. To learn more, see [Create status and trend reports from a work item query](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports). -- **SQL Server reports**: Allow users access to out-of-the-box SQL Server reports and support to create customized SQL Reports or Excel reports. Doing so requires that the project is [configured to support SQL Server reporting](/previous-versions/azure/devops/report/admin/add-a-report-server). -::: moniker-end -### Supported features and access level +### Supported features for access levels -Users granted **Stakeholder** access have limited access to select features as indicated in the following table. To learn more, see [About access levels](../../organizations/security/access-levels.md). In addition to access levels, select features require permissions to execute. +Users with **Stakeholder** access get restricted privileges, granting them access to only those features outlined in the following table. For more information, see [About access levels](../../organizations/security/access-levels.md). In addition to access levels, certain features require permissions to execute. > [!NOTE] -> Data displayed within a chart or widget is subject to permissions granted to the signed in user. To learn more, see [FAQs on Azure DevOps dashboards, charts, and reports, Access and permissions](faqs.yml). +> Data displayed within a chart or widget is subject to permissions granted to the signed-in user. For more information, see [FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml). :::row::: :::column span="3"::: @@ -89,7 +83,7 @@ Users granted **Stakeholder** access have limited access to select features as i --- :::row::: :::column span="3"::: - **Dashboards** (View) + Dashboards (View) :::column-end::: :::column span="1"::: ✔️ @@ -100,7 +94,7 @@ Users granted **Stakeholder** access have limited access to select features as i :::row-end::: :::row::: :::column span="3"::: - **Dashboards** (Create and edit) + Dashboards (Create and edit) :::column-end::: :::column span="1"::: @@ -111,7 +105,7 @@ Users granted **Stakeholder** access have limited access to select features as i :::row-end::: :::row::: :::column span="3"::: - **Charts**, **Widgets** (View) + Charts, Widgets (View) :::column-end::: :::column span="1"::: ✔️ @@ -122,7 +116,7 @@ Users granted **Stakeholder** access have limited access to select features as i :::row-end::: :::row::: :::column span="3"::: - **Charts**, **Widgets** (Add and configure) + Charts, Widgets (Add and configure) :::column-end::: :::column span="1"::: @@ -133,7 +127,7 @@ Users granted **Stakeholder** access have limited access to select features as i :::row-end::: :::row::: :::column span="3"::: - **In-context reports** + In-context reports :::column-end::: :::column span="1"::: ✔️ @@ -142,10 +136,9 @@ Users granted **Stakeholder** access have limited access to select features as i ✔️ :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" :::row::: :::column span="3"::: - **Analytic views** + Analytics views :::column-end::: :::column span="1"::: @@ -156,7 +149,7 @@ Users granted **Stakeholder** access have limited access to select features as i :::row-end::: :::row::: :::column span="3"::: - **Power BI reports** + Power BI reports :::column-end::: :::column span="1"::: ✔️ @@ -165,11 +158,10 @@ Users granted **Stakeholder** access have limited access to select features as i ✔️ :::column-end::: :::row-end::: -::: moniker-end ::: moniker range="< azure-devops" :::row::: :::column span="3"::: - **SQL Server reports** + SQL Server reports :::column-end::: :::column span="1"::: ✔️ @@ -180,298 +172,182 @@ Users granted **Stakeholder** access have limited access to select features as i :::row-end::: ::: moniker-end -### Default permissions +--- -**Dashboards** +### Default permissions ::: moniker range="azure-devops" -You can set [individual dashboard permissions](dashboard-permissions.md) to grant or restrict the ability to edit or delete dashboards. +For Dashboards, set [individual dashboard permissions](dashboard-permissions.md) to grant or restrict the ability to edit or delete dashboards. ::: moniker-end ::: moniker range="< azure-devops" -You set [dashboard permissions at the team level](dashboard-permissions.md) for team dashboards. +For Dashboards, set [dashboard permissions](dashboard-permissions.md) at the team level for team dashboards. ::: moniker-end -[!INCLUDE [temp](../../organizations/security/includes/report.md)] - +[!INCLUDE [report dashboard permissions](../../organizations/security/includes/report.md)] -::: moniker range=">= azure-devops-2019" - -**Power BI Integration and Analytics views** - -You set [permissions](../powerbi/analytics-security.md) for the service at the project level, and for shared **Analytics views** at the object level. - -[!INCLUDE [temp](../../organizations/security/includes/analytics.md)] - -::: moniker-end +For Power BI Integration and Analytics views, you set [permissions](../powerbi/analytics-security.md) for the service at the project level, and for shared Analytics views at the object level. +[!INCLUDE [analytics dashboard permissions](../../organizations/security/includes/analytics.md)] ## Configurable dashboards -With dashboards, you can configure an array of charts and widgets. +With dashboards, you can configure an array of charts and widgets. Each team can [add and configure multiple dashboards](dashboards.md) to: + - Share information. -- View status, progress, and trends +- View status, progress, and trends. - Access quick links and other functions. -Easily add and rearrange widgets on the dashboard to show recent changes made to view build status, bug trends, and more. +Easily add and rearrange widgets on the dashboard to show recent changes made to view build status, bug trends, and more. -![Example dashboard](media/dashboard-view-with-widgets.png) +:::image type="content" source="media/dashboard-view-with-widgets.png" alt-text="Screenshot that shows an example dashboard."::: #### Sequence for adding and customizing a dashboard -Select a box below to open the corresponding article. +Select one of the following boxes to open the corresponding article. -[![Add dashboard](media/gs-add-dashboard.png)](dashboards.md)[![Add widget](media/gs-add-widget.png)](add-widget-to-dashboard.md) +[:::image type="content" source="media/gs-add-dashboard.png" alt-text="Diagram is a link to Add dashboard article.":::](dashboards.md) [:::image type="content" source="media/gs-add-widget.png" alt-text="Diagram is a link to Add widget article.":::](add-widget-to-dashboard.md) -## Charts: Work tracking status and trends - -With flat-list queries, you can create various charts to monitor status, progress, and trends. Before you monitor work progress and trends, you'll need to have [planned your project and made progress on work you're tracking](../../boards/backlogs/create-your-backlog.md). - -You can open a shared query, create a chart, and add it to the dashboard. Once it's been added to the dashboard, you can change the **Chart for work items** widget configuration to resize or change the chart parameters. Or, from the dashboard, you can add a **Chart for work items** widget and choose a shared query and set the chart parameters. Chart types include status—pie, bar, column, stacked bar, and pivot—and trend—stacked area, line, and area—charts. - -For details, see: -- [Define a query](../../boards/queries/using-queries.md) -- [Track progress with status and trend query-based charts](charts.md) - -**Sample Agile tool light-weight charts** - -::: moniker range=">= azure-devops-2019" +## Charts: Work tracking status and trends -> [!div class="mx-imgBorder"] -> ![Active bug charts added to dashboards](media/overview/active-bug-charts-on-dashboards-2019.png) +With flat-list queries, you can create various charts to monitor status, progress, and trends. Before you monitor work progress and trends, [plan your project and make progress on work you're tracking](../../boards/backlogs/create-your-backlog.md). -::: moniker-end - -::: moniker range="tfs-2018" +You can open a shared query, create a chart, and add it to the dashboard. After the chart is added to the dashboard, you can change the **Chart for work items** widget configuration to resize or change the chart parameters. Or, from the dashboard, you can add a **Chart for work items** widget and choose a shared query and set the chart parameters. You have multiple chart types from which to choose. Status charts include pie, bar, column, stacked bar, and pivot. Trend charts include stacked area, line, and area. -![Active bugs](media/gs-monitor-charts-active-bugs.png) +For more information, see [Define a query](../../boards/queries/using-queries.md) and [Track progress with status and trend query-based charts](charts.md). -::: moniker-end +#### Sample Agile tool lightweight charts +:::image type="content" source="media/overview/active-bug-charts-on-dashboards-2019.png" alt-text="Screenshot that shows Active bug charts added to dashboards."::: -**Sequence for adding query-based charts to a dashboard** +#### Sequence for adding query-based charts to a dashboard -Select a box below to open the corresponding article. +Select one of the following boxes to open the corresponding article. -[![Edit query](media/gs-chart-query.png)](../../boards/queries/using-queries.md)[![Create chart](media/gs-chart-create.png)](charts.md)[![Add chart to dashboard](media/gs-chart-add-dashboard.png)](add-charts-to-dashboard.md#add-charts) +[:::image type="content" source="media/gs-chart-query.png" alt-text="Diagram that is a link to Edit query article.":::](../../boards/queries/using-queries.md) [:::image type="content" source="media/gs-chart-create.png" alt-text="Diagram is a link to create a chart article.":::](add-charts-to-dashboard.md) [:::image type="content" source="media/gs-chart-add-dashboard.png" alt-text="Diagram is a link to Add chart to dashboard article.":::](add-charts-to-dashboard.md) +## Charts: Manual testing progress, results, and trends +The steps to creating charts that track manual testing progress and results are similar to the ones for tracking work. The starting point is the test plan rather than a query. For example, you can find out how many test cases are ready to run, or how many tests are passing and failing in each test suite. And, just like work item query-based charts, you can add these charts to a dashboard. -## Charts: Manual testing progress, results, and trends +For more information, see: -The steps to creating charts that track manual testing progress and results are similar to the ones for tracking work. The starting point, however, begins with the test plan rather than a query. For example, you can find out how many test cases are ready to run, or how many tests are passing and failing in each test suite. And, just like work item query-based charts, you can add these charts to a dashboard. - -For details, see: - [Create test plans and test suites](../../test/create-a-test-plan.md) - [Create manual test cases](../../test/create-test-cases.md) -- [Track test status charts](../../test/track-test-status.md#charts) +- [Track testing progress](../../test/track-test-status.md#charts) -**Sample light-weight test charts** +#### Sample lightweight test charts -![Web Team test plan is a chart that shows counts of test in various stages. Tests by Suite breaks down the same tests by test suite.](media/gs-monitor-test-charts.png) +:::image type="content" source="media/gs-monitor-test-charts.png" alt-text="Screenshot that shows the Web Team test plan is a chart showing counts of tests in various stages, with tests broken down by suite."::: -## Widgets +## Widgets -You add widgets to a dashboard to display a chart, information, or set of links. Most widgets are configurable. For a description of each supported widget for your platform and version, see the [Widget catalog](widget-catalog.md). Here are the widgets that support the indicated service. +You add widgets to a dashboard to display a chart, information, or set of links. Most widgets are configurable. For a description of each supported widget for your platform and version, see the [Widget catalog](widget-catalog.md). Here are the widgets that support the indicated service. -[!INCLUDE [temp](../includes/widgets-oob.md)] - ---- -:::row::: - :::column span="1"::: - **Work** - - [Chart for work items](widget-catalog.md#chart-wit-widget) - - [New Work item](widget-catalog.md#new-work-item-widget) - - [Query results](widget-catalog.md#query-results-widget) - - [Query tile](widget-catalog.md#query-tile-widget) - - [Sprint burndown](widget-catalog.md#sprint-burndown-widget) - - [Sprint capacity](widget-catalog.md#sprint-capacity-widget) - - [Sprint overview](widget-catalog.md#sprint-overview-widget) - - [Work links](widget-catalog.md#work-links-widget) - --- - **Code** - - [Code tile](widget-catalog.md#code-tile-widget) - - [Pull request](widget-catalog.md#pull-request-widget) - :::column-end::: - :::column span="1"::: - **Build** - - [Chart for build history](widget-catalog.md#build-history-widget) - --- - **Information and links** - - [Markdown](widget-catalog.md#markdown-widget) - - [Other links](widget-catalog.md#other-links-widget-2018) - - [Team members](widget-catalog.md#team-members-widget) - - [Team room](widget-catalog.md#team-room-widget) - - [Visual Studio Shortcuts](widget-catalog.md#visual-studio-widget) - - [Welcome](widget-catalog.md#how-to-widget) - :::column-end::: -:::row-end::: ---- +[!INCLUDE [widget catalog links](../includes/widgets-oob.md)] -### Sprint chart widgets +### Sprint chart widgets -![Sprint capacity widget](media/widget-sprint-capacity.png) ![Sprint burndown widget](media/widget-sprint-burndown.png) - - -::: moniker range=">= azure-devops-2019" +[:::image type="icon" source="media/widget-sprint-capacity.png":::](widget-catalog.md#sprint-capacity-widget) [:::image type="icon" source="media/widget-sprint-burndown.png":::](widget-catalog.md#sprint-burndown-analytics-widget) ### Sprint scope change -There's no chart or widget that tracks changes to sprint scope. However, you can determine work items added to a sprint or moved out of a sprint using the Query Editor. To learn how, see [About Sprints, Scrum and project management, Sprint scope change](../../boards/sprints/scrum-overview.md#sprint-scope-change). - -::: moniker-end +There's no chart or widget that tracks changes to sprint scope. However, you can determine work items added to a sprint or moved out of a sprint by using the Query Editor. For more information, see [Query sprint scope changes](../../boards/sprints/scrum-overview.md#sprint-scope-change). -::: moniker range=">= azure-devops-2019" +### Sample Cumulative Flow Diagram widget -### Sample Cumulative Flow Diagram widget +:::image type="content" source="media/cfd-exampe-rolling-30-days.png" alt-text="Screenshot that shows a Cumulative Flow Diagram widget."::: -![Cumulative flow diagram widget](media/cfd-exampe-rolling-30-days.png) +### Monitor code activity, build progress, and deployment status -::: moniker-end +With the code tile widgets, you can monitor the activity occurring within a repository or branch folder. Build history displays a histogram of all builds run for a specific build pipeline. Bar colors use green for completed, red for failed, and yellow for completed without tests. -### Monitor code activity, build progress and deployment status +#### Code, build, and release chart widgets -With the code tile widgets, you can monitor the activity occurring within a repository or branch folder. Build history displays a histogram of all builds run for a specific build pipeline. Bar color indicates: green-completed, red-failed, and yellow-completed without tests. +:::image type="content" source="media/widget-code-tile.png" alt-text="Screenshot that shows a Code tile widget."::: -**Code, build, and release chart widgets** +:::image type="content" source="media/widget-catalog-pull-request.png" alt-text="Screenshot that shows a Pull request widget."::: -![Code tile widget](media/widget-code-tile.png)   ![Pull request widget](media/widget-catalog-pull-request.png) -![Build history widget](media/widget-build-history-chart.png)    ![Deployment status widget](media/widget-deployment-status.png) +:::image type="content" source="media/widget-deployment-status.png" alt-text="Screenshot that shows a Build history widget."::: -::: moniker range=">= azure-devops-2019" +:::image type="content" source="media/widget-build-history-chart.png" alt-text="Screenshot that shows a Deployment status widget."::: -### Analytics widgets and reports - -::: moniker-end +### Analytics widgets and reports ::: moniker range=">= azure-devops-2020" -The Analytics service is the reporting platform for Azure DevOps. As described in [What is the Analytics service?](../powerbi/what-is-analytics.md), it replaces the previous platform based on SQL Server Reporting Services. The Analytics service supports Analytics widgets, [in-context Analytics reports](#work-tracking-analytics), and [Analytics views for Power BI reporting](../powerbi/what-are-analytics-views.md). +The Analytics service is the reporting platform for Azure DevOps. As described in [What is Analytics?](../powerbi/what-is-analytics.md), it replaces the previous platform based on SQL Server Reporting Services. The Analytics service supports Analytics widgets, [in-context Analytics reports](#work-tracking-analytics), and Analytics views for Power BI reporting. For more information, see [About Analytics views](../powerbi/what-are-analytics-views.md). ::: moniker-end -::: moniker range="azure-devops-2019" - -The Analytics service is the reporting platform for Azure DevOps. As described in [What is the Analytics service?](../powerbi/what-is-analytics.md), it replaces the previous platform based on SQL Server Reporting Services. The Analytics service supports Analytics widgets and [Analytics views for Power BI reporting](../powerbi/what-are-analytics-views.md). - -> [!NOTE] -> Analytics is in preview for Azure DevOps Server 2019 and generally available for Azure DevOps Server 2020 and later versions. - -::: moniker-end +#### Sample Lead time widget -::: moniker range=">= azure-devops-2019" +:::image type="content" source="media/lead-time-control-chart.png" alt-text="Screenshot that shows a Lead time widget."::: -**Sample Lead time widget** +For more information, see [Widgets based on Analytics data](../dashboards/analytics-widgets.md) and [Add an Analytics widget to a dashboard](../dashboards/add-widget-to-dashboard.md#add-analytics-widget). -![Lead time widget](media/lead-time-control-chart.png) + -To learn more, see the following articles: -- [Widgets based on Analytics](../dashboards/analytics-widgets.md) -- [Add an Analytics widget to a dashboard](../dashboards/add-widget-to-dashboard.md#add-analytics-widget) - -::: moniker-end - - - -## In-context reports: Work tracking +## In-context reports: Work tracking ::: moniker range=">= azure-devops-2020" -Azure Boards provides several in-context reports that derive from Analytics data. From your backlog or board, you can view the Cumulative Flow Diagram and team Velocity reports by selecting the **Analytics** tab. Each report provides interactive controls to provide each user the view of interest to them. From a Sprint backlog, you can view the sprint burndown trend. +Azure Boards provides several in-context reports that derive from Analytics data. From your backlog or board, you can view the Cumulative Flow Diagram and team Velocity reports by selecting the **Analytics** tab. Each report provides interactive controls to provide each user the view of interest to them. From a Sprint backlog, you can view the Sprint Burndown Trend. -### Cumulative Flow Diagram +### Cumulative Flow Diagram -Use the interactive controls to choose the time frame, swimlanes, and workflow states or Kanban board columns. +Use the interactive controls to choose the time frame, swimlanes, and workflow states or board columns. -> [!div class="mx-imgBorder"] -> ![Open CFD Analytics](media/cfd/analytics-cfd-azure-devops.png) +:::image type="content" source="media/cfd/analytics-cfd-azure-devops.png" alt-text="Screenshot that shows open CFD analytics." lightbox="media/cfd/analytics-cfd-azure-devops.png"::: -### Velocity -Use the interactive controls to choose the count or sum field and number of iterations. +### Velocity -> [!div class="mx-imgBorder"] -> ![Open Velocity Analytics](media/velocity/analytics-velocity-azure-devops.png) +Use the interactive controls to choose the count or sum field and number of iterations. -### Sprint Burndown Trend +:::image type="content" source="media/velocity/analytics-velocity-azure-devops.png" alt-text="Screenshot that shows open Velocity analytics."::: -Use the interactive controls to choose the start and end of the sprint and count or sum field to use in the burndown. If you don't track Remaining Work in tasks, you can view burndown based on a count of work items/tasks. +### Sprint Burndown Trend -> [!div class="mx-imgBorder"] -> ![Burndown trend based on Remaining Work](../../boards/sprints/media/burndown/analytics-burndown-remaining-work.png) +Use the interactive controls to choose the start and end of the sprint and count or sum field to use in the burndown. If you don't track Remaining Work in tasks, you can view burndown based on a count of work items or tasks. +:::image type="content" source="../../boards/sprints/media/burndown/analytics-burndown-remaining-work.png" alt-text="Screenshot that shows Burndown Trend based on Remaining Work." lightbox="../../boards/sprints/media/burndown/analytics-burndown-remaining-work.png"::: ::: moniker-end -::: moniker range="<= azure-devops-2019" - -Azure Boards provides several in-context reports that derive from the work tracking data store. From your backlog or board, you can view the Cumulative Flow Diagram and team Velocity reports by choosing the miniature charts that appear on each page. From a Sprint backlog, you can view the sprint burndown. - -### Cumulative Flow Diagram - -The CFD report shows the count of work items in the backlog based on their state over time. - -> [!div class="mx-imgBorder"] -> ![Opened CFD chart](media/cfd/data-store-cumulative-flow-opened.png) - -### Velocity - -Velocity is based on the values entered for Effort, Story Points, or Size fields for work items that belong to the Requirement Category. - -![Web portal, Velocity chart showing seven sprints of in progress and completed work](media/team-velocity-chart-web-7-iterations.png) - - -### Sprint burndown +::: moniker range=">= azure-devops-2020" -Each sprint provides access to two charts. The first [tracks capacity](../../boards/sprints/define-sprints.md) for the team, team activities—such as Development, Test, Design—and individual team members. The second tracks the [sprint burndown](configure-sprint-burndown.md) for remaining work. +You can add the in-context reports to a dashboard by using the copy to dashboard option from the report's context menu. -| Capacity bars | Burndown | -|-------| ----- | -|![Capacity bars](../../boards/sprints/media/ALM_DS_CapacityBars_S.png) | ![Burndown chart](../../boards/sprints/media/ALM_DS_SprntBD_Chrt_S.png) | +:::image type="content" source="media/add-charts/add-analytics-chart-abbreviated.png" alt-text="Screenshot that shows an Analytics in-context report with the Copy to dashboard action."::: ::: moniker-end -::: moniker range=">= azure-devops-2020" - -> [!NOTE] -> You can add the in-context reports to a dashboard using the copy to dashboard option from the report's context menu. -> -> ![Analytics in-context report, Copy to dashboard](media/add-charts/add-analytics-chart-abbreviated.png) -::: moniker-end - -::: moniker range="<= azure-devops-2019" +For more information about these reports, see: -> [!NOTE] -> You can't add the in-context reports to a dashboard. However, you may find a comparable widget listed in the [widget catalog](widget-catalog.md) that tracks the same or similar data which you can add to the dashboard. -::: moniker-end - -To learn more about these reports, see one of the following articles: - [Cumulative flow](cumulative-flow.md) - [Team velocity](team-velocity.md) -- [View/configure sprint burndown](configure-sprint-burndown.md) - +- [Sprint burndown](configure-sprint-burndown.md) - - + ::: moniker range=">= azure-devops-2020" -## In-context reports: Pipelines and Test - -Several in-context reports are provided for Azure Pipelines. These reports derive from Analytics data. Open a pipeline (or release summary for Test failure) to view the reports and select the **Analytics** tab. Select **View full report** on a summary card for a detailed report. +## In-context reports: Pipelines and Test -> [!div class="mx-imgBorder"] -> ![Analytics Tab](../../pipelines/reports/media/pipelines-reports/analyticstab.png) +Several in-context reports are provided for Azure Pipelines. These reports derive from Analytics data. Open a pipeline or release summary for **Test failures** to view the reports and select the **Analytics** tab. Select **View full report** on a summary card for a detailed report. +:::image type="content" source="../../pipelines/reports/media/pipelines-reports/analyticstab.png" alt-text="Screenshot that shows the Analytics tab."::: -For more information on each in-context Analytics report for pipeline runs, see the following articles: +For more information on each in-context Analytics report for pipeline runs, see: ::: moniker-end ::: moniker range="azure-devops" -- [Historical graph for agent pools (Preview)](../../pipelines/agents/pool-consumption-report.md) + +- [Historical graph for agent pools (preview)](../../pipelines/agents/pool-consumption-report.md) - [Pipeline pass rate report](../../pipelines/reports/pipelinereport.md#pipeline-pass-rate-report) - [Test pass rate report](../../pipelines/reports/pipelinereport.md#test-failures-report) - [Pipeline duration report](../../pipelines/reports/pipelinereport.md#pipeline-duration-report) @@ -479,7 +355,7 @@ For more information on each in-context Analytics report for pipeline runs, see - [Test analytics for releases](../../pipelines/test/test-analytics.md) ::: moniker-end - + ::: moniker range="azure-devops-2020" - [Pipeline pass rate report](../../pipelines/reports/pipelinereport.md#pipeline-pass-rate-report) - [Test pass rate report](../../pipelines/reports/pipelinereport.md#test-failures-report) @@ -488,97 +364,88 @@ For more information on each in-context Analytics report for pipeline runs, see - [Test analytics for releases](../../pipelines/test/test-analytics.md) ::: moniker-end - ::: moniker range=">= azure-devops-2020" -You can also use Power BI and OData to create reports based on pipeline and test data. See [Overview of sample reports using OData queries](../powerbi/sample-odata-overview.md) +You can also use Power BI and OData to create reports based on pipeline and test data. For more information, see the [Overview of sample reports using OData queries](../powerbi/sample-odata-overview.md). ::: moniker-end ::: moniker range=">= azure-devops-2020" ### Pipeline pass rate report -The **Pipeline pass rate** report provides a trend of pipeline failure and task failure of the pipeline. You can view the pass rate of the pipeline over a configurable period of time (7/14/30 days). You can view more details in **Task failure details**, which not only highlights the trend, but also list the top failing tasks. +The **Pipeline pass rate** report provides a trend of pipeline failure and task failure of the pipeline. You can view the pass rate of the pipeline over a configurable period of time, for example, 7, 14, or 30 days. Find more details in **Task failure details**, which not only highlights the trend but also lists the top failing tasks. -> [!div class="mx-imgBorder"] -> ![Pipeline failures report](../../pipelines/reports/media/pipelines-reports/pipelinefailurereport.png) - -Learn more about the [Pipeline pass rate report](../../pipelines/reports/pipelinereport.md#pipeline-pass-rate-report). +:::image type="content" source="../../pipelines/reports/media/pipelines-reports/top-failing.png" alt-text="Screenshot that shows a summary of the pipeline pass rate report."::: +For more information, see [Pipeline pass rate report](../../pipelines/reports/pipelinereport.md#pipeline-pass-rate-report). ### Test failures report -The **Test failures** report provides a granular view of the top failing tests in the pipeline, along with the failure details. Summary charts are also provided for builds that indicate code coverage and test failures or success. +The **Test failures** report provides a granular view of the top failing tests in the pipeline, along with the failure details. Summary charts are also provided for builds that indicate code coverage and test failures or success. -> [!div class="mx-imgBorder"] -> ![Test analytics detail view](../../pipelines/test/media/test-analytics/test-failures.png) +:::image type="content" source="../../pipelines/test/media/test-analytics/test-failures.png" alt-text="Screenshot that shows a Test analytics detail view." lightbox="../../pipelines/test/media/test-analytics/test-failures.png"::: -Learn more about the [Test failures report](../../pipelines/test/test-analytics.md#test-failures). +For more information, see [Test failures report](../../pipelines/test/test-analytics.md#test-failures). ### Pipeline duration report -The **Pipeline duration** report provides the duration trend of a pipeline. It also highlights the average run time of the total successful runs over a period of time (7/14/30 days) and provides insights on the tasks that have affected the duration of the pipeline. +The **Pipeline duration** report provides the duration trend of a pipeline. It also highlights the average run time of the total successful runs over a period of time, for example, for 7, 14, or 30 days. The report also provides insights on the tasks that affected the duration of the pipeline. -> [!div class="mx-imgBorder"] -> ![Pipeline duration report](../../pipelines/reports/media/pipelines-reports/pipelinedurationreport.png) +:::image type="content" source="../../pipelines/reports/media/pipelines-reports/duration-summary.png" alt-text="Screenshot that shows pipeline duration summary."::: -Learn more about the [Pipeline duration report](../../pipelines/reports/pipelinereport.md#pipeline-duration-report). +:::image type="content" source="../../pipelines/reports/media/pipelines-reports/duration-trend.png" alt-text="Screenshot that shows a pipeline duration trend."::: -::: moniker-end +For more information, see [Pipeline duration report](../../pipelines/reports/pipelinereport.md#pipeline-duration-report). +::: moniker-end -::: moniker range="azure-devops-2019" +## Add custom work tracking fields -## In-context reports: Pipeline Test Failures +::: moniker range="azure-devops" -Azure Pipelines provides an in-context Test failures report, derived from Analytics data. Open a release summary to view the report and select the **Analytics** tab. Select the summarized card for a detailed report. To learn more, see [Test failures report](../../pipelines/reports/pipelinereport.md#test-failures-report). +[Add a custom field](../../organizations/settings/work/customize-process-field.md) to add data to support reporting requirements. +::: moniker-end -> [!div class="mx-imgBorder"] -> ![Analytics Tab, Azure DevOps Server 2019](../../pipelines/reports/media/pipelines-reports/analyticstab-server-2019.png) +::: moniker range=" < azure-devops" +Add data to support reporting requirements by adding a custom field: [Inheritance process](../../organizations/settings/work/customize-process-field.md) or [On-premises XML process](../../reference/add-modify-field.md). ::: moniker-end -## Add custom work tracking fields +## Marketplace widgets and extensibility -::: moniker range="azure-devops" +In addition to the widgets available in the widget catalog, you might find interesting widgets in the [Marketplace](https://marketplace.visualstudio.com/search?term=webpage%20widget&target=VSTS&sortBy=Relevance). -You can add data to support reporting requirements by [adding a custom field](../../organizations/settings/work/customize-process-field.md). -::: moniker-end +Or, you can create your own widget by using the REST API. For more information, see [Add a dashboard widget](../../extend/develop/add-dashboard-widget.md). -::: moniker range=">= azure-devops-2019 < azure-devops" +## Azure reporting -You can add data to support reporting requirements by adding a custom field [Inheritance process](../../organizations/settings/work/customize-process-field.md) or [On-premises XML process](../../reference/add-modify-field.md). -::: moniker-end +Azure provides various reporting tools and services to help you monitor and analyze the usage and performance of your resources, such as Virtual Machines (VMs), services, and overall usage. -::: moniker range="tfs-2018" +### Azure Monitor -You can add data to support reporting requirements by [adding a custom field](../../reference/add-modify-field.md). -::: moniker-end +Azure Monitor is a comprehensive solution for collecting, analyzing, and acting on telemetry from your cloud and on-premises environments. It helps you understand how your applications are performing and proactively identifies issues affecting them and the resources they depend on. +For more information, see [Azure Monitor overview](/azure/azure-monitor/overview). -## Marketplace widgets and extensibility +### Azure Resource Graph + +Azure Resource Graph lets you explore and query your Azure resources at scale. It lets you query across subscriptions and management groups, which makes it easier to manage large environments. -In addition to the widgets available in the widget catalog, you may find interesting widgets in the [Marketplace](https://marketplace.visualstudio.com/search?term=webpage%20widget&target=VSTS&sortBy=Relevance). +For more information, see [What is Azure Resource Graph](/azure/governance/resource-graph/overview). -Or, you can [create your own widget using the REST API](../../extend/develop/add-dashboard-widget.md). +### Azure Advisor + +Azure Advisor is a personalized cloud consultant that helps you follow best practices to optimize your Azure deployments. It analyzes your resource configuration and usage, and then recommends solutions to help improve the cost-effectiveness, performance, high availability, and security of your Azure resources. + +For more information, see [Introduction to Azure Advisor](/azure/advisor/advisor-overview). ## Next steps > [!div class="nextstepaction"] -> [Add a widget to a dashboard](add-widget-to-dashboard.md) -> or -> [Review available widgets](widget-catalog.md) - +> [Add a widget to a dashboard](add-widget-to-dashboard.md) ## Related articles - [FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml) -- [Best practices for "light-weight" Agile project management using Azure Boards](../../boards/best-practices-agile-project-management.md) -- [Cross-service integration and collaboration overview](../../cross-service/cross-service-overview.md) - -[excel-adhoc-query-report]: ../admin/create-status-and-trend-excel-reports.md -[add-a-team]: ../../organizations/settings/add-teams.md -[team-assets]: ../../organizations/settings/manage-teams.md -[add-team-members]: ../../organizations/settings/add-teams.md#add-team-members -[add-team-admin]: ../../organizations/settings/add-team-administrator.md - - +- [Widget catalog](widget-catalog.md) +- [Best practices for Agile project management](../../boards/best-practices-agile-project-management.md) +- [Cross-service overview](../../cross-service/cross-service-overview.md) diff --git a/docs/report/dashboards/quick-ref.md b/docs/report/dashboards/quick-ref.md index f1171835aed..2eccf8bd239 100644 --- a/docs/report/dashboards/quick-ref.md +++ b/docs/report/dashboards/quick-ref.md @@ -12,7 +12,6 @@ monikerRange: '<= azure-devops' ms.date: 09/28/2022 --- - # Dashboards, charts, and quick reference [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -49,7 +48,7 @@ Use this index to quickly access information on tasks for configuring or accessi - [Set dashboard permissions](dashboard-permissions.md) - [View a dashboard](dashboards.md) ::: moniker-end - ::: moniker range=">= azure-devops-2019 < azure-devops-2022" + ::: moniker range=" - - [Edit a dashboard](dashboards.md) - - [Enable auto-refresh](dashboards.md) - - [Favorite a dashboard](dashboards.md) - - [Filter dashboard directory](dashboards.md) - - [Move widgets on a dashboard](add-widget-to-dashboard.md#move-delete) - - [Open a dashboard](dashboards.md) - - [Rename a dashboard](dashboards.md) -
      - - [Refresh a dashboard](dashboards.md) - - [Set dashboard permissions](dashboard-permissions.md) - - [View a dashboard](dashboards.md) - ::: moniker-end + :::column-end::: :::column span="2"::: **Charts** - [Work-tracking query chart](charts.md) - [Test status or progress chart](../../test/track-test-status.md) - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" **Analytics** - [Analytics views](../powerbi/what-are-analytics-views.md) - [Analytics widgets](analytics-widgets.md) @@ -107,13 +86,9 @@ Use this index to quickly access information on tasks for configuring or accessi - [Power BI reports](../powerbi/overview.md#sample-reports) - [OData](../extend-analytics/quick-ref.md) ::: moniker-end - ::: moniker range="<= azure-devops-2019" - **SQL Reports** - - [SQL Server reports](/previous-versions/azure/devops/report/sql-reports/reporting-services-reports) - - [Excel work tracking reports](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports) - ::: moniker-end + **Widgets** - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" - [Configure a widget](add-widget-to-dashboard.md#configure) - [Configure the Burndown/Burnup widget](configure-burndown-burnup-widgets.md) - [Configure Sprint Burndown widget](configure-sprint-burndown.md) @@ -123,10 +98,7 @@ Use this index to quickly access information on tasks for configuring or accessi - [Configure the Test Results widget](configure-test-results-trend.md) - [Resize a widget](add-widget-to-dashboard.md) ::: moniker-end - ::: moniker range="< azure-devops-2019" - - [Configure a widget](add-widget-to-dashboard.md#configure) - - [Resize a widget](add-widget-to-dashboard.md) - ::: moniker-end + **Troubleshoot** - [FAQs: Dashboards, charts, and reports](faqs.yml) :::column-end::: @@ -140,17 +112,6 @@ Use this index to quickly access information on tasks for configuring or accessi In context reports appear on the **Analytics** tab of these specific service pages: **Boards>Boards**, **Boards>Backlogs**, **Boards>Sprints**, and **Pipelines>Builds**. ::: moniker-end -::: moniker range="azure-devops-2019" - -In-context reports appear on specific service pages, such as **Boards>Boards**, **Boards>Backlogs**, **Boards>Sprints**,and **Pipelines>Builds>Analytics**. These reports derive data from the Analytics service. -::: moniker-end - -::: moniker range="tfs-2018" - -In-context reports appear on specific service pages, such as **Work>Backlog**, **Work>Backlogs** and **Build and Release>Builds**. -::: moniker-end - - --- :::row::: :::column span="2"::: @@ -160,7 +121,7 @@ In-context reports appear on specific service pages, such as **Work>Backlog**, * - [Velocity chart](team-velocity.md) :::column-end::: :::column span="2"::: - ::: moniker range=">= azure-devops-2019" + ::: moniker range="<=azure-devops" **Pipelines** - [Build test results](../../pipelines/test/review-continuous-test-results-after-build.md) - [Code coverage](../../pipelines/test/review-code-coverage-results.md) @@ -170,15 +131,7 @@ In-context reports appear on specific service pages, such as **Work>Backlog**, * - [Test failures](../../pipelines/test/test-analytics.md) - [Test impact analysis](../../pipelines/test/test-impact-analysis.md) ::: moniker-end - ::: moniker range="< azure-devops-2019" - **Build & Release** - - [Build test results](../../pipelines/test/review-continuous-test-results-after-build.md) - - [Code coverage](../../pipelines/test/review-code-coverage-results.md) - - [Release test results](../../pipelines/test/review-continuous-test-results-after-build.md) - - [Trace test requirements](../../pipelines/test/requirements-traceability.md) - - [Test failures](../../pipelines/test/test-analytics.md) - - [Test impact analysis](../../pipelines/test/test-impact-analysis.md) - ::: moniker-end + :::column-end::: :::row-end::: --- diff --git a/docs/report/dashboards/team-velocity.md b/docs/report/dashboards/team-velocity.md index 5038b151004..6c6ab98768e 100644 --- a/docs/report/dashboards/team-velocity.md +++ b/docs/report/dashboards/team-velocity.md @@ -8,188 +8,80 @@ ms.assetid: 31CBF001-CFF2-49CF-97A1-FDFFEFDDF3AB ms.topic: tutorial ms.author: chcomley author: chcomley -monikerRange: '<= azure-devops' -ms.date: 05/18/2023 +monikerRange: "<=azure-devops" +ms.date: 03/12/2025 --- # View and configure team velocity -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Velocity metrics provide useful information, so teams can plan and [forecast](../../boards/sprints/forecast.md) sprints and determine how well they estimate and meet planned commitments. You can get an indication of how much work a team can complete during a sprint based on either **a count of work items completed** or **the sum of estimates made** for effort (product backlog items), story points (user stories), or size (requirements). Use velocity as an aid to determine team capacity and don't confuse it with key performance indicators. - -In this article, learn how to do the following tasks: - -::: moniker range=">= azure-devops-2019" - -> [!div class="checklist"] -> * Open your backlog from the web portal -> * View the velocity chart types -> * View the Velocity in-context report -> * Configure the Velocity widget -> * Support velocity tracking with required and recommended team activities - -::: moniker-end - -::: moniker range="tfs-2018" - -> [!div class="checklist"] -> * Open your backlog from the web portal -> * View the velocity chart types -> * View the Velocity in-context report (work tracking data store) -> * Support velocity tracking with required and recommended team activities - -::: moniker-end - -::: moniker range=">= azure-devops-2019" +Velocity metrics provide valuable insights that help teams plan and [forecast](../../boards/sprints/forecast.md) sprints, and evaluate how accurately they estimate and meet planned commitments. These metrics indicate how much work a team can complete during a sprint, based on either **the count of work items completed** or **the sum of estimates** for effort (product backlog items), story points (user stories), or size (requirements). Use velocity to aid in determining team capacity, but don't confuse it with key performance indicators. ## Prerequisites -::: moniker-end - [!INCLUDE [temp](../includes/analytics-widgets-prerequisites.md)] -- Be aware of the [required and recommended tasks](#required-and-recommended-tasks), listed later in this article. > [!TIP] -> The images you see from your web portal may differ from the images you see in this article. These differences result from updates made to your web app, options that you or your admin have enabled, and which process was chosen when creating your project—Agile, Basic, Scrum, or CMMI. The Basic process is available with Azure DevOps Server 2019 Update 1 and later versions. - -::: moniker range=">= azure-devops-2019" +> The images in this article might differ from what you see in your web portal. These differences can be due to updates to your web app, options enabled by you or your admin, and the process chosen when creating your project (Agile, Basic, Scrum, or CMMI). The Basic process is available starting from Azure DevOps Server 2019 Update 1. ## Velocity chart types -::: moniker-end - ::: moniker range=">= azure-devops-2020" -You have a choice of Velocity charts: the in-context Velocity chart you access from a Backlogs page and the Velocity widget you add to a dashboard. With both these charts, you can quickly determine the information in the following table, which describes the available workflow state categories and their descriptions. +You can choose between two Velocity charts: the in-context Velocity chart from the Backlogs page and the Velocity widget for dashboards. Both charts help you quickly understand the workflow state categories described in the following table. - +Items in the *Proposed* or *Resolved* states are excluded from the **Completed**, **Completed Late**, and **Incomplete** calculations. For more information, see [How workflow category states are used in Azure Boards](../../boards/work-items/workflow-and-state-categories.md). Your selections are personal and persist across sessions until changed. -Items assigned to a *Proposed* or *Resolved* aren't included in any of the calculations for **Completed**, **Completed Late**, or **Incomplete**. For more information, see [How workflow category states are used in Azure Boards](../../boards/work-items/workflow-and-state-categories.md). The selections you make are only set for you, and persist across sessions until you change them. + -|Workflow State |Description | +|Workflow state |Description | |---------|---------| -|Planned | Calculated based on the number of work items assigned to the sprint before the start of the sprint. If a work item is assigned to the sprint before the start of the sprint, and then assigned to another sprint after the start of the original sprint, it shows as Planned in the original sprint, and then Completed/Completed, Late/Incomplete in the new sprint it's assigned to. | -|Completed | Calculated based on the number of work items assigned to the sprint before or after the start of the sprint and completed before the end of the sprint. | -|Completed Late |Calculated based on the number of work items assigned to the sprint before or after the start of the sprint but completed after the end of the sprint. | -|Incomplete | Calculated based on the number of work items assigned to the sprint before or after the start of the sprint and not yet completed. | +|Planned | Work items assigned to a sprint before it starts. If reassigned after the sprint begins, they remain Planned in the original sprint and appear as Late or Incomplete in the new sprint. | +|Completed | Work items assigned to the sprint and completed before the end of the sprint. | +|Completed Late |Work items assigned to the sprint but completed after the sprint ends. | +|Incomplete | Work items assigned to the sprint but not yet completed. | +| Resolved | Bugs assigned to the sprint, indicating a solution was implemented but not yet verified.| Later in this article, learn how to [open the Velocity in-context report](#velocity-chart) or [configure the Velocity widget](#configure-the-velocity-widget). #### [In-context Velocity chart](#tab/in-context) -![Screenshot of the web portal, in-context Velocity chart showing six sprints of in progress and completed work.](media/velocity/analytics-velocity-azure-devops.png) +:::image type="content" source="media/velocity/analytics-velocity-azure-devops.png" alt-text="Screenshot of the web portal, in-context Velocity chart showing six sprints of in progress and completed work."::: #### [Velocity widget](#tab/widget) -![Screenshot of an example Velocity widget with eight iterations.](media/commerce-team-velocity-eight-iterations.png) +:::image type="content" source="media/commerce-team-velocity-eight-iterations.png" alt-text="Screenshot of an example Velocity widget with eight iterations."::: *** You can configure each chart in the following ways: -- Sum of [Effort, Story Points, or Size fields](../../boards/queries/query-numeric.md) or other supported numeric field assigned to backlog items. -- Count of work items that appear on the backlog -- Number of iterations. +- Sum of [Effort, Story Points, size fields](../../boards/queries/query-numeric.md), or other supported numeric fields assigned to backlog items. +- Count of work items on the backlog. +- Number of iterations. -The widget supports some more configuration options. To configure or view Velocity charts, see [Configure and view Velocity charts](team-velocity.md). +The widget offers more configuration options. For more information, see [Configure and view Velocity charts](team-velocity.md). ::: moniker-end -::: moniker range="azure-devops-2019" - -You have a choice of Velocity charts: the in-context Velocity chart you access from a Backlogs page and the Velocity widget you add to a dashboard. With the Velocity widget, you can quickly determine the following information: -- Planned velocity -- Actual (completed) velocity -- Work completed later than planned -- Amount of work not completed - -#### [In-context Velocity chart](#tab/in-context) - -![Screenshot of the web portal, Velocity chart showing seven sprints of in progress and completed work.](media/team-velocity-chart-web-7-iterations.png) - -#### [Velocity widget](#tab/widget) - -![Screenshot of an example Velocity widget with eight iterations.](media/commerce-team-velocity-eight-iterations.png) - -*** - -Both of these charts support visualizing team velocity for several sprints. The Velocity widget, however, supports the following configuration options: -- Sum of [Effort, Story Points, or Size fields](../../boards/queries/query-numeric.md) or other supported numeric field assigned to backlog items. -- Count of work items that appear on the backlog -- Number of iterations -- Advanced features. - -::: moniker-end - -::: moniker range="tfs-2018" - -The in-context Velocity charts are based on the sum of [Effort, Story Points, or Size fields](../../boards/queries/query-numeric.md) assigned to backlog items. These charts are similar to the one shown in the following image. - -::: moniker-end - -## Open your backlog from the web portal - -::: moniker range=">= azure-devops-2020" - -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and go to your project. -2. Select **Boards** > **Backlogs**, and then select your **team** from the dropdown menu. - - :::image type="content" source="../../boards/boards/media/open-boards-backlog.png" alt-text="Screenshot that shows Open Boards, Backlogs, and select a team."::: - -3. To view the in-context reports for the product backlog, check that you selected **Stories** for Agile, **Issues** for Basic, **Backlog items** for Scrum, or **Requirements** for CMMI as the backlog level. - - :::image type="content" source="../../boards/sprints/media/assign-items-sprint/select-product-backlog-agile-s155.png" alt-text="Screenshot that shows how to select product backlog level, Backlog items, Stories, or Requirements."::: - -::: moniker-end - -::: moniker range="azure-devops-2019" - -1. Check that you selected the right project, and select **Boards** > **Backlogs**. Then select the correct team from the team selector menu. - - ![Screenshot that shows how to Open Boards, Backlogs, for a team for Azure DevOps Server 2019.](/azure/devops/boards/sprints/media/assign-items-sprint/open-work-backlogs-agile.png) - - To select another backlog, open the selector and then select a different team or select the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all backlogs** option. Or, enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Screenshot of the My Team Backlogs drop-down list.](/azure/devops/boards/sprints/media/assign-items-sprint/team-selector-backlogs-agile.png) - -2. To view the in-context reports for the product backlog, check that you selected **Stories** for Agile, **Issues** for Basic, **Backlog items** for Scrum, or **Requirements** for CMMI as the backlog level. - - > [!div class="mx-imgBorder"] - > ![Screenshot of the Backlog items drop-down option.](/azure/devops/boards/sprints/media/assign-items-sprint/select-product-backlog-agile.png) - -::: moniker-end - -::: moniker range="tfs-2018" -From your web portal, open your team's product backlog and select the team from the project and team selector. Then select **Work** > **Backlogs**. Select the product backlog, which is **Backlog items** for Scrum, **Stories** for Agile, or **Requirements** for CMMI. - -> [!div class="mx-imgBorder"] -> ![Screenshot of Open Backlogs page, TFS 2018.](/azure/devops/boards/sprints/media/assign-items-sprint/open-work-backlogs-standard.png) - -To select another team, open the project and team selector. Select a different team, or select the **Browse** option. - -> [!div class="mx-imgBorder"] -> ![Screenshot of select another team, TFS 2018.](/azure/devops/boards/sprints/media/assign-items-sprint/team-selector-backlogs-standard.png) - -::: moniker-end - ## View the Velocity in-context report ::: moniker range=">= azure-devops-2020" -Velocity reports are available for each backlog level, both product and portfolio backlogs. Each report provides interactive controls to provide each user the view of interest to them. +Velocity reports are available for both product and portfolio backlogs. Each report includes interactive controls, allowing users to customize the view to their specific interests. -1. From the **Boards** > **Backlogs** screen, select **Analytics** to open the Velocity report for your product or portfolio backlog. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization/Your_Project}```). +2. Select **Boards** > **Backlogs** > **Analytics** to open the Velocity report for your product or portfolio backlog. :::image type="content" source="media/cfd/analytics-summary-cfd-velocity.png" alt-text="Screenshot showing Backlogs, open Analytics."::: -2. To change to a different backlog, choose from the backlog selector, and then select **View full report** for Velocity. +3. To change to a different backlog, choose from the backlog selector, and then select **View full report** for Velocity. -3. Use the interactive controls to select the count or sum field and number of iterations. Select **Custom iterations** to specify any number of iterations between 1 and 15. +4. Use the interactive controls to select the count or sum field and number of iterations. Select **Custom iterations** to specify any number of iterations between 1 and 15. - If your team hasn't completed a sprint or if you're working on items before a sprint start date, there's no data to analyze and forecast. You might see this message: *Set iteration dates to use this widget*. To resolve this situation, set an iteration date range to include present date or wait for the sprint to start. + If your team doesn't complete a sprint or if you're working on items before a sprint start date, there's no data to analyze and forecast. The following message might display: *Set iteration dates to use this widget*. To resolve this situation, set an iteration date range to include present date or wait for the sprint to start. Hover over a column area to show a summary of planned and completed work items. For example, for the 07_2019 sprint, 131 items are planned. @@ -197,81 +89,16 @@ Velocity reports are available for each backlog level, both product and portfoli For more information, see the [workflow state descriptions](#state-descriptions-table) mentioned earlier in this article. -4. To add the report to a dashboard, select the :::image type="icon" source="media/icons/actions-icon.png" border="false"::: actions icon and select **Copy to Dashboard**. +5. To add the report to a dashboard, select the :::image type="icon" source="media/icons/actions-icon.png" border="false"::: actions icon and select **Copy to Dashboard**. :::image type="content" source="media/add-charts/add-analytics-chart-abbreviated.png" alt-text="Screenshot of Analytics in-context report, Copy to dashboard option."::: -5. Select the dashboard and select **OK**. - -6. To return to the Analytics summary, select the :::image type="icon" source="../../media/icons/back-arrow.png" border="false"::: back arrow. - -::: moniker-end - -::: moniker range="azure-devops-2019" - -1. From the web portal, open your product backlog. - -1. (1) Check that you've selected the right project, (2) select **Boards** > **Backlogs**, and then (3) select the correct team from the team selector menu. - - ![Screenshot to Open Boards, Backlogs, for a team, Azure DevOps Server 2019. ](../../boards/sprints/media/assign-items-sprint/open-work-backlogs-agile.png) - - To select another team, open the selector and select a different team or select the :::image type="icon" source="../../media/icons/home-icon.png" border="false"::: **Browse all backlogs** option. Or, you can enter a keyword in the search box to filter the list of team backlogs for the project. - - > [!div class="mx-imgBorder"] - > ![Screenshot to Select another team, Azure DevOps Server 2019.](../../boards/sprints/media/assign-items-sprint/team-selector-backlogs-agile.png) - - > [!TIP] - > Select the :::image type="icon" source="../../media/icons/icon-favorite-star.png" border="false"::: star icon to favorite a team backlog. Favorited artifacts (:::image type="icon" source="../../media/icons/icon-favorited.png" border="false"::: favorited icon) appear at the top of the team selector list. - -1. Check that you have selected **Backlog items** (for Scrum), **Stories** (for Agile), or **Requirements** (for CMMI) as the backlog level. +6. Select the dashboard and select **OK**. - > [!div class="mx-imgBorder"] - > ![Screenshot to select product backlog level, Backlog items, Stories, or Requirements in Azure DevOps Server 2019.](../../boards/sprints/media/assign-items-sprint/select-product-backlog-agile.png) +7. To return to the Analytics summary, select the :::image type="icon" source="../../media/icons/back-arrow.png" border="false"::: back arrow. -2. Open the Velocity chart. - - > [!div class="mx-imgBorder"] - > ![Screenshot to select product backlog level, Backlog items, Stories, or Requirements, Azure DevOps Server 2019.](media/velocity/velocity-forecast-open-chart-vert.png) - - For charts to appear, your team must carry out these activities: - - Select sprints for your team. - - Assign backlog items to sprints. - - Estimate backlog items by defining the Effort, Story Points, or Size. - -3. The chart tracks your estimated backlog work (sum of Effort, Story Points, or Size) that's completed (green) in the previous sprints or is in progress (blue). - - As the following chart shows, velocity tends to fluctuate from sprint-to-sprint for different kinds of reasons. However, you can quickly determine the average velocity by averaging the values shown in green for each sprint. You can then plug the average into the Forecast tool. - - ![Web portal, Velocity chart showing seven sprints of in progress and completed work](media/team-velocity-chart-web-7-iterations.png) - - > [!NOTE] - > Work items based on the [Scrum process](../../boards/work-items/guidance/scrum-process.md) get counted in the chart once their State is set to Committed, whereas items based on the [Agile](../../boards/work-items/guidance/agile-process.md) and [CMMI](../../boards/work-items/guidance/cmmi-process.md) processes get counted once their State is set to Active. This behavior is set through the [workflow states to category state mappings](../../boards/work-items/workflow-and-state-categories.md). - ::: moniker-end - -::: moniker range="tfs-2018" - -1. From the web portal, open the product backlog and then select the Velocity chart. - - ![Screenshot to select the Velocity chart in the upper right area of the page.](media/velocity/velocity-forecast-open-chart.png) - - For charts to appear, your team must carry out these activities: - - Select sprints for your team. - - Assign backlog items to sprints. - - Estimate backlog items by defining the Effort, Story Points, or Size. - -2. The report tracks your estimated backlog work (sum of Effort, Story Points, or Size) that's completed (green) in the previous sprints or is in progress (blue). - - As this chart shows, velocity fluctuates from sprint-to-sprint for different kinds of reasons. However, you can quickly determine the average velocity by averaging the values shown in green for each sprint. You can then plug the average into the Forecast tool. - - ![Screenshot of Velocity chart showing seven sprints of in progress and completed work.](media/team-velocity-chart-web-7-iterations.png) - - > [!NOTE] - > Work items based on the [Scrum process](../../boards/work-items/guidance/scrum-process.md) get counted in the chart once their State is set to Committed, whereas items based on the [Agile](../../boards/work-items/guidance/agile-process.md) and [CMMI](../../boards/work-items/guidance/cmmi-process.md) processes get counted once their State is set to Active. This behavior is set through the [workflow states to category state mappings](../../boards/work-items/workflow-and-state-categories.md). - ::: moniker-end -::: moniker range=">= azure-devops-2019" - ## Configure the Velocity widget You can only configure your Velocity widget for a single team. If you want to view the velocity for several teams, then you must configure a portfolio management team that rolls up from several teams. For more information, see [Add teams](../../organizations/settings/add-teams.md). @@ -293,47 +120,40 @@ Complete the following steps to configure the Velocity widget. 3. (Optional) Select the check boxes to show additional information for work completed later than planned for each sprint. - **Display planned work for iterations:** Check this box to display the amount of work planned for an iteration at the start of the iteration, which is useful for comparing your planned work to actual deliverables. By default, the count of planned work begins on the start date of the iteration. - - **Days past start date of iteration when planned work is final**: Specify the number of days past the start date to count planned work. For example, if the first two days of an iteration are for planning, then you can enter "3", and planned work gets counted on the third day. For example, if the iteration starts on `01/01/2018`, and three backlog items are assigned to the iteration on `01/01/2018` end-of-day, then those three backlog items are considered as Planned. If your team doesn't complete planning until a few days into the iteration, then you can update the Days past start date of iteration when planned work is final. - - > [!NOTE] - > Work is considered Planned if it's assigned to the iteration as of the Iteration Start Date. - - - **Highlight work completed late:** Check this box to display Work items marked complete after the iteration end date, which are considered to be completed late and show as light green. This is useful for spotting a trend where work items are marked complete after the iteration is complete - - **Days past end date of iteration after which work is late**: Specify the number of days past which you consider a work item late if its status is still new or is in progress. For example, entering three days gives the team 3 days after the end of an iteration to mark work items complete or done, before they're considered late. + - **Days past start date of iteration when planned work is final**: Specify the number of days past the start date for counting planned work. For example, if the first two days of an iteration are for planning, then you can enter `3`, and planned work gets counted on the third day. For example, if the iteration starts on `01/01/2024`, and three backlog items are assigned to the iteration on `01/01/2024` end-of-day, then those three backlog items are considered as Planned. If your team doesn't complete planning until a few days into the iteration, then you can update the Days past start date of iteration when planned work is final. + - **Highlight work completed late:** Check this box to display work items marked complete after the iteration end date, which is considered to be completed late and show as light green. Highlighting work completed late is useful for spotting a trend where work items are marked complete after the iteration is complete. + - **Days past end date of iteration after which work is late**: Specify the number of days past which you consider a work item late if its status is still new or is in progress. For example, entering three days gives the team 3 days after the end of an iteration to mark work items complete or done, before considered late. - > [!NOTE] - > A work item is considered late when the work item's Completed Date is later than End Date of the Iteration the work item is *currently* assigned to. It takes into account the value you enter for *Days past end date of iteration after which work is late*. - -4. Select **Save** when you're done. The following image shows Velocity based on Story Points and eight sprints of data. +4. Select **Save**. The following image shows Velocity based on Story Points and eight sprints of data. - ![Screenshot of example Velocity widget, 8 iterations.](media/commerce-team-velocity-eight-iterations.png) + :::image type="content" source="media/commerce-team-velocity-eight-iterations.png" alt-text="Screenshot of example Velocity widget, eight iterations."::: For more information about **Planned**, **Completed**, **Completed Late**, and **Incomplete** states, see the [State descriptions](#state-descriptions-table) mentioned earlier in this article. -::: moniker-end - -## Required and recommended tasks +## Required and recommended tasks for using Velocity charts For your team to gain the greatest utility from the Velocity charts, follow these required and recommended tasks. -**Required:** -- [Define iteration paths (sprints) and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). Sprints should be of the same duration. -- [Define and estimate backlog items](../../boards/backlogs/create-your-backlog.md#estimates). If you work from your team's backlog, the items you create automatically get assigned to the current sprint (Iteration) and to your team's default Area Path. -- Update the status of backlog items once work starts and when it's completed. Only backlog items with State of *In Progress* or *Done* show up on the Velocity chart or widget. +### Required tasks + +- [**Define iteration paths (sprints) and configure team iterations**](../../organizations/settings/set-iteration-paths-sprints.md). Ensure sprints are of the same duration. +- [**Define and estimate backlog items**](../../boards/backlogs/create-your-backlog.md#estimates). Items created from the team's backlog are automatically assigned to the current sprint and the team's default Area Path. +- **Update the status of backlog items when work starts and completes**. Only items with a State of *In Progress* or *Done* appear on the Velocity chart or widget. + +### Recommended tasks -**Recommended:** -* Define and size backlog items to [minimize variability](../dashboards/team-velocity.md). -* Determine how your team wants to [treat bugs](../../organizations/settings/show-bugs-on-backlog.md). If your team chooses to treat bugs like requirements, bugs show up on the backlog and be counted within the Velocity chart and forecasting. -* [Set your team's area path](../../organizations/settings/set-area-paths.md). The forecast tool forecasts those items based on your team's default settings. These settings can specify to include items in area paths under the team's default or exclude them. -* Don't create a hierarchy of backlog items and bugs. The Kanban board, sprint backlog, and task board only show the last node in a hierarchy, called the leaf node. For example, if you link items within a hierarchy that is four levels deep, only the items at the fourth level appear on the Kanban board, sprint backlog, and task board.
      Instead of nesting requirements, bugs, and tasks, we recommend that you maintain a flat list-only creating parent-child links one level deep between items. Use [Features to group requirements or user stories](../../boards/backlogs/organize-backlog.md). You can quickly map stories to features, which creates parent-child links in the background. -* At the end of the sprint, update the status of those backlog items that the team has fully completed. Incomplete items should be moved back to the product backlog and considered in a future sprint planning meeting. -* Minimize the size variability of your backlog items to help strengthen the team's ability to create truer estimates. Variability increases uncertainty, but minimizing the variability of your estimates, increases the likelihood of more reliable velocity metrics and forecast results. Estimates, by their nature, don't reflect reality. They represent a best guess by the team as to the effort required to complete an item, as it relates to the effort to complete other items on the backlog. +- **[Define and size backlog items](../dashboards/team-velocity.md)** for minimized variability. +- **Decide how your team [treats bugs](../../organizations/settings/show-bugs-on-backlog.md)**. If treated like requirements, bugs appear on the backlog and are included in the Velocity chart and forecasting. +- **[Set your team's area path](../../organizations/settings/set-area-paths.md)**. The forecast tool uses these settings to include or exclude items in area paths under the team's default. +- **Avoid creating a hierarchy of backlog items and bugs**. The board, Taskboards, and sprint backlog only show the last node in a hierarchy. Instead, maintain a flat list with parent-child links one level deep. Use **[Features to group requirements or user stories](../../boards/backlogs/organize-backlog.md)**. +- **Update the status of completed backlog items at the end of the sprint**. Move incomplete items back to the product backlog for future sprint planning. +- **Minimize the size variability of backlog items for improved estimation accuracy**. Reducing variability increases the reliability of velocity metrics and forecast results. Estimates are best guesses by the team regarding the effort required to complete an item relative to others on the backlog. [!INCLUDE [note-delete-area-paths](../../boards/includes/note-delete-area-paths.md)] ## Add other teams -If you work with several teams, and each team wants to work with their own backlog view, Velocity chart, and forecast tool, you can [add teams](../../organizations/settings/add-teams.md). Each team then gets access to their own set of Agile tools. Each Agile tool filters work items to only include those whose assigned area paths and iteration paths meet those [set for the team](../../organizations/settings/about-teams-and-settings.md). +If each team wants their own backlog view, Velocity chart, and forecast tool, you can [add a new team](../../organizations/settings/add-teams.md). Each team has access to its own set of Agile tools, which filter work items to include only the assigned area paths and iteration paths [specific to that team](../../organizations/settings/about-teams-and-settings.md). ## Next steps diff --git a/docs/report/dashboards/toc.yml b/docs/report/dashboards/toc.yml index 39d63aa594a..c722a89fa0f 100644 --- a/docs/report/dashboards/toc.yml +++ b/docs/report/dashboards/toc.yml @@ -1,22 +1,21 @@ -- name: Code coverage +- name: Code coverage href: ../../pipelines/test/review-code-coverage-results.md?toc=/azure/devops/report/toc.json -- name: Pipeline Analytics +- name: Pipeline Analytics href: ../../pipelines/reports/pipelinereport.md?toc=/azure/devops/report/toc.json displayname: pipeline pass rate, pipeline duration, test pass rate, failed runs, failure trend, tests in the pipeline, unique failing tests, top 10 steps by duration -- name: Test Analytics +- name: Test Analytics href: ../../pipelines/test/test-analytics.md?toc=/azure/devops/report/toc.json - displayname: test failures, trends, pass rate, failing tests, group tests, individual tests, failure analysis -- name: Build and release test results + displayname: test failures, trends, pass rate, failing tests, group tests, individual tests, failure analysis +- name: Build and release test results href: ../../pipelines/test/review-continuous-test-results-after-build.md?toc=/azure/devops/report/toc.json - name: Tests and Requirements traceability href: ../../pipelines/test/requirements-traceability.md?toc=/azure/devops/report/toc.json - name: Pool consumption report href: ../../pipelines/agents/pool-consumption-report.md?toc=/azure/devops/report/toc.json - displayname: agent usage, private self-hosted, public hosted, concurrency, historical graph, preview + displayname: agent usage, private self-hosted, public hosted, concurrency, historical graph, preview - name: Configure a Test Results Trend widget href: configure-test-results-trend.md - name: Test Impact Analysis (TIA) href: ../../pipelines/test/test-impact-analysis.md?toc=/azure/devops/report/toc.json - name: Flaky test management and reporting href: ../../pipelines/test/flaky-test-management.md?toc=/azure/devops/report/toc.json - \ No newline at end of file diff --git a/docs/report/dashboards/widget-catalog.md b/docs/report/dashboards/widget-catalog.md index 67ce0af20e4..f1fed52a59e 100644 --- a/docs/report/dashboards/widget-catalog.md +++ b/docs/report/dashboards/widget-catalog.md @@ -1,350 +1,223 @@ --- title: Catalog of Out Of Box widgets you can add to a dashboard titleSuffix: Azure DevOps -description: An index of widgets you might want to add to your dashboards when working in Azure DevOps. -ms.custom: dashboards, contperf-fy22q1, engagement-fy23 +description: Learn about the widgets that you might want to add to your dashboards when you work in Azure DevOps. +ms.custom: dashboards, engagement-fy23 ms.subservice: azure-devops-analytics ms.assetid: C9FD12C0-033E-4A4D-AF63-6EF67E7B4828 ms.topic: conceptual ms.author: chcomley author: chcomley -monikerRange: '<= azure-devops' -ms.date: 02/14/2023 +monikerRange: '<= azure-devops' +ms.date: 03/12/2025 +#customer intent: As an administrator or team member, I want to understand the widgets I can use on a team or project dashboard in Azure DevOps. --- -# Out Of Box widget catalog +# Out Of Box widget catalog -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] +Widgets display information and charts on dashboards. Many widgets are configurable or scoped to a team or the logged-in user account. They display information from one or more data stores or charts maintained within the system. You can add a widget to a dashboard or copy a widget from one dashboard to another. For more information, see [Add a widget to a dashboard](add-widget-to-dashboard.md). -Widgets display information and charts on dashboards. Many widgets are configurable or are scoped to a team or to the logged in user account. Many display information available from one or more data stores or charts maintained within the system. You add a widget to a dashboard or copy a widget from one dashboard to another. To learn how, see [Add a widget to a dashboard](add-widget-to-dashboard.md). +For example, you can add the **Build History** widget from the dashboard's **Add Widget** dialog. -For example, you can add the **Build History** widget from the dashboard's **Add widget** dialog. +:::image type="content" source="media/widget-build-history-chart.png" alt-text="Screenshot shows the Build History Widget which includes an icon and description."::: -![Screenshot of Build history widget, example.](media/widget-build-history-chart.png) - -This article provides a quick reference of all out of box (OOB) widgets that you can add to your dashboard. In addition to these widgets, you may find more widgets in the [Marketplace](#marketplace) or create your own. +This article provides a quick reference of all out-of-box (OOB) widgets that you can add to your dashboard. In addition to these widgets, you might find more widgets in the [Marketplace](#marketplace) or create your own. ## Supported OOB widgets -Widgets listed in the following table are provided out-of-box. They're organized under the service they support. Widgets are annotated as follows: +Widgets listed in the following table are provided out-of-box. They're organized under the service they support: -::: moniker range=">= azure-devops-2019" - **Analytics**: Widget derives data from [Analytics data](../powerbi/what-is-analytics.md) - **Build**: Widget derives data for a selected build pipeline -- **Project**: indicates you can select the project and team when configuring the widget +- **Project**: Widget where you can select the project and team when configuring the widget - **Release**: Widget derives data for a selected release pipeline - **Team**: Widget is scoped to a single team - **Teams**: Widget is scoped to one or more teams - **User**: Widget is scoped to the logged in user account -::: moniker-end -::: moniker range="tfs-2018" -- **Build**: Widget derives data for a selected build pipeline -- **Release**: Widget derives data for a selected release pipeline -- **Team**: Widget is scoped to a single team -- **User**: Widget is scoped to the logged in user account -::: moniker-end - ---- -:::row::: - :::column span="1"::: - ::: moniker range=">= azure-devops-2020" - **Boards** - - [Assigned to me](#assigned-to-me-widget) (User) - - [Burndown chart](#burndown-analytics-widget) (Analytics, Project, Teams) - - [Burnup chart](#burnup-analytics-widget) (Analytics, Project, Teams) - - [Chart for work items](#chart-wit-widget) - - [Cumulative flow diagram](#cfd-widget) (Team) - - [Cycle time (Analytics)](#cycle-time-widget) (Analytics, Team) - - [Lead time (Analytics)](#lead-time-widget) (Analytics, Team) - - [New Work item](#new-work-item-widget) - - [Query results](#query-results-widget) - - [Query tile](#query-tile-widget) - - [Sprint burndown](#sprint-burndown-analytics-widget) (Analytics, Team) - - [Sprint burndown - Legacy](#sprint-burndown-widget) (Team) - - [Sprint capacity](#sprint-capacity-widget) (Team) - - [Sprint overview](#sprint-overview-widget) (Team) - - [Velocity](#velocity-widget) (Analytics, Team) - - [Work links](#work-links-widget) - ::: moniker-end - ::: moniker range="azure-devops-2019" - **Boards** - - [Assigned to me](#assigned-to-me-widget) (User) - - [Burndown chart](#burndown-analytics-widget) (Analytics, Teams) - - [Burnup chart](#burnup-analytics-widget) (Analytics, Teams) - - [Chart for work items](#chart-wit-widget) - - [Cumulative flow diagram](#cfd-widget) (Team) - - [Cycle time (Analytics)](#cycle-time-widget) (Analytics, Team) - - [Lead time (Analytics)](#lead-time-widget) (Analytics, Team) - - [New Work item](#new-work-item-widget) - - [Query results](#query-results-widget) - - [Query tile](#query-tile-widget) - - [Sprint burndown](#sprint-burndown-widget) (Team) - - [Sprint capacity](#sprint-capacity-widget) (Team) - - [Sprint overview](#sprint-overview-widget) (Team) - - [Velocity](#velocity-widget) (Analytics) (Team) - - [Work links](#work-links-widget) - ::: moniker-end - ::: moniker range="tfs-2018" - **Work** - - [Assigned to me](#assigned-to-me-widget) (User) - - [Chart for work items](#chart-wit-widget) - - [New Work item](#new-work-item-widget) - - [Query results](#query-results-widget) - - [Query tile](#query-tile-widget) - - [Sprint burndown](#sprint-burndown-widget) (Team) - - [Sprint capacity](#sprint-capacity-widget) (Team) - - [Sprint overview](#sprint-overview-widget) (Team) - - [Work links](#work-links-widget) - ::: moniker-end - --- - ::: moniker range=">= azure-devops-2019" - **Code** - - [Code tile](#code-tile-widget) (Repository, Branch, Folder) - - [Pull request](#pull-request-widget) (Team) - ::: moniker-end - ::: moniker range="tfs-2018" - **Repos** - - [Code tile](#code-tile-widget) (Repository, Branch, Folder) - - [Pull request](#pull-request-widget) (Team, User) - ::: moniker-end - :::column-end::: - :::column span="1"::: - ::: moniker range=">= azure-devops-2019" - **Pipelines** - - [Build history](#build-history-widget) (Build pipeline) - - [Deployment status](#deployment-status-widget) (Build pipeline) - - [Release pipeline overview](#release-definition-widget) (Release pipeline) - - [Requirements quality](#requirements-quality-widget) (Query, Build or Release pipeline) - --- - **Test Plans** - - [Chart for test plans](#chart-test-plan-widget) - - [Test results trend (Advanced)](#test-trend-results-advanced) (Analytics, Build or Release pipeline) - - [Test results trend](#test-trend-results) (Build or Release pipeline) - --- - **Information and links** - - [Embedded Webpage](#embedded-webpage-widget) - - [Markdown](#markdown-widget) - - [Other links](#other-links-widget) (Team) - - [Team members](#team-members-widget) (Team) - - [Visual Studio Shortcuts](#visual-studio-widget) - - [Welcome](#how-to-widget) - ::: moniker-end - ::: moniker range="tfs-2018" - **Build & Release** - - [Build history](#build-history-widget) (Build pipeline) - - [Deployment status](#deployment-status-widget) (Build pipeline) - - [Release pipeline overview](#release-definition-widget) (Release pipeline) - - [Requirements quality](#requirements-quality-widget) (Query, Build or Release pipeline) - --- - **Test** - - [Chart for test plans](#chart-test-plan-widget) - - [Test results trend](#test-trend-results) (Build or Release pipeline) - ::: moniker-end - ::: moniker range="tfs-2018" - **Information and links** - - [Embedded Webpage](#embedded-webpage-widget) - - [Markdown](#markdown-widget) - - [Other links](#other-links-widget-2018) (Team) - - [Team members](#team-members-widget) (Team) - - [Visual Studio Shortcuts](#visual-studio-widget) - - [Welcome](#how-to-widget) - ::: moniker-end - :::column-end::: -:::row-end::: ---- +| **Category** | **Widgets** | +|--------------|-------------| +| **Boards** (Azure DevOps 2020 and later) | - [Assigned to Me](#assigned-to-me-widget) (User)
      - [Burndown](#burndown-analytics-widget) (Analytics, Project, Teams)
      - [Burnup](#burnup-analytics-widget) (Analytics, Project, Teams)
      - [Chart for Work Items](#chart-wit-widget)
      - [Cumulative Flow Diagram](#cfd-widget) (Team)
      - [Cycle Time (Analytics)](#cycle-time-widget) (Analytics, Team)
      - [Lead Time (Analytics)](#lead-time-widget) (Analytics, Team)
      - [New Work Item](#new-work-item-widget)
      - [Query Results](#query-results-widget)
      - [Query Tile](#query-tile-widget)
      - [Sprint Burndown](#sprint-burndown-analytics-widget) (Analytics, Team)
      - [Sprint Burndown (Legacy)](#burndown-widget) (Team)
      - [Sprint Capacity](#sprint-capacity-widget) (Team)
      - [Sprint Overview](#sprint-overview-widget) (Team)
      - [Velocity](#velocity-widget) (Analytics, Team)
      - [Work Links](#work-links-widget) | +| **Boards** (Azure DevOps 2019) | - [Assigned to Me](#assigned-to-me-widget) (User)
      - [Burndown](#burndown-analytics-widget) (Analytics, Teams)
      - [Burnup](#burnup-analytics-widget) (Analytics, Teams)
      - [Chart for Work Items](#chart-wit-widget)
      - [Cumulative Flow Diagram](#cfd-widget) (Team)
      - [Cycle Time (Analytics)](#cycle-time-widget) (Analytics, Team)
      - [Lead Time (Analytics)](#lead-time-widget) (Analytics, Team)
      - [New Work Item](#new-work-item-widget)
      - [Query Results](#query-results-widget)
      - [Query Tile](#query-tile-widget)
      - [Sprint Burndown](#burndown-widget) (Team)
      - [Sprint Capacity](#sprint-capacity-widget) (Team)
      - [Sprint Overview](#sprint-overview-widget) (Team)
      - [Velocity](#velocity-widget) (Analytics, Team)
      - [Work Links](#work-links-widget) | +| **Repos** | - [Code Tile](#code-tile-widget) (Repository, Branch, Folder)
      - [Pull Request](#pull-request-widget) (Team) | +| **Pipelines** | - [Build History](#build-history-widget) (Build)
      - [Deployment status](#deployment-status-widget) (Build)
      - [Release Pipeline Overview](#release-definition-widget) (Release)
      - [Requirements quality](#requirements-quality-widget) (Query, Build, Release) | +| **Test Plans** | - [Chart for Test Plans](#chart-test-plan-widget)
      - [Test Results Trend](#test-trend-results) (Build, Release)
      - [Test Results Trend (Advanced)](#test-trend-results-advanced) (Analytics, Build, Release) | +| **Information and links** | - [Embedded Webpage](#embedded-webpage-widget)
      - [Markdown](#markdown-widget)
      - [Other Links](#other-links-widget) (Team)
      - [Team Members](#team-members-widget) (Team)
      - [Visual Studio Shortcuts](#visual-studio-widget)
      - [Welcome](#how-to-widget) | ## Prerequisites ::: moniker range="azure-devops" -- To add widgets to a dashboard, you must be a member of a project. If you haven't been added as a project member, [get added now](../../organizations/accounts/add-organization-users.md). -- To add widgets from the marketplace, you must be a member of the [**Project Collection Administrators** group](../../organizations/security/look-up-project-collection-administrators.md). -- To add, edit, or manage a dashboard, you must have **Basic** access or greater. -::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - -- To add widgets to a dashboard, you must be a member of a project. If you haven't been added as a project member, [get added now](../../organizations/accounts/add-organization-users.md). -- To add widgets from the marketplace, you must be a member of the [**Project Collection Administrators** group](../../organizations/security/look-up-project-collection-administrators.md). -- To add, edit, or manage a dashboard, you must have **Basic** access or greater. +|Category | Requirements | +|-------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Basic** access. | +| **Permissions** |To add widgets from the marketplace: Member of the [**Project Collection Administrators** group](../../organizations/security/look-up-project-collection-administrators.md). | + ::: moniker-end -::: moniker range="tfs-2018" +::: moniker range="< azure-devops" -- To add widgets to a dashboard, you must be a member of a project. If you haven't been added as a project member, [get added now](../../organizations/accounts/add-organization-users.md). -- To add widgets from the marketplace, you must be a member of the [**Project Collection Administrators** group](../../organizations/security/look-up-project-collection-administrators.md). -- To add, edit, or manage a team dashboard, you must have **Basic** access or greater and be a team admin, a project admin, or have [dashboard permissions](../dashboards/dashboard-permissions.md). In general, you need to be a team admin for the currently selected team to edit dashboards. Request your current team or project admin to add you as a [team admin](../../organizations/settings/add-team-administrator.md). -::: moniker-end +|Category | Requirements | +|-------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Stakeholder** access. | +| **Permissions** |To add widgets from the marketplace: Member of the [**Project Collection Administrators** group](../../organizations/security/look-up-project-collection-administrators.md). | -> [!NOTE] -> Data displayed within a chart or widget is subject to permissions granted to the signed in user. To learn more, see [FAQs on Azure DevOps dashboards, charts, and reports, Access and permissions](faqs.yml). - -::: moniker range=">= azure-devops-2019" -## Azure Boards widgets ::: moniker-end -::: moniker range="tfs-2018" -## Work widgets -::: moniker-end +> [!NOTE] +> Data displayed within a chart or widget is subject to permissions granted to the signed in user. For more information, see [Access and permissions](faqs.yml#access-and-permissions). -Add work tracking widgets to your dashboards to show status, progress, or trends. You [use work items to plan and track work](../../boards/backlogs/add-work-items.md). +## Azure Boards widgets -In addition to the widgets listed here, you can add a work item query chart to your dashboard. To learn more, see [Track progress with status and trend query-based charts](charts.md). +Add work tracking widgets to your dashboards that show status, progress, or trends. You use work items to plan and track work. For more information, see [Add and update a work item](../../boards/backlogs/add-work-items.md). +In addition to the widgets listed here, you can add a work item query chart to your dashboard. For more information, see [Track progress with status and trend query-based charts](charts.md). :::row::: :::column span="1"::: - ### Assigned to me - ![Screenshot of Assigned to me widget.](media/widget-assigned-to-me.png) + ### Assigned to Me + :::image type="icon" source="media/widget-assigned-to-me.png"::: :::column-end::: :::column span="1":::
      - Displays the list of active work items assigned to the currently logged in user. The list ignores closed, removed, cut, or deleted work items and other work item types which are not aligned to any backlogs. + Displays the active work items assigned to the current user. The list ignores closed, removed, cut, or deleted work items and other work item types, which aren't aligned to any backlogs. :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" :::row::: :::column span="1"::: - ### Burndown chart - ![Screenshot of Burndown chart widget.](media/widget-burndown-chart.png) + ### Burndown + :::image type="icon" source="media/widget-burndown-chart.png"::: :::column-end::: :::column span="1":::
      - Adds a tile that displays a burndown chart that you can configure to span one or more teams, work item types, and time period. With it, you can create a release burndown, sprint burndown, or any burndown that spans teams and sprints. - - To learn more, see [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). + Displays a burndown chart that you can configure to span one or more teams, work item types, and time period. With it, you can create a release burndown, sprint burndown, or any burndown that spans teams and sprints. + + For more information, see [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). :::column-end::: :::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019" :::row::: :::column span="1"::: - ### Burnup chart - ![Screenshot of Burnup chart widget.](media/widget-burnup-chart.png) + ### Burnup + :::image type="icon" source="media/widget-burnup-chart.png"::: :::column-end::: :::column span="1":::
      - - Adds a tile that displays a burnup chart that you can configure to span one or more teams, work item types, and time period. With it, you can create a release burnup, sprint burnup, or any burnup that spans teams and sprints. - - To learn more, see [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). + + Displays a burnup chart that you can configure to span one or more teams, work item types, and time period. With it, you can create a release burnup, sprint burnup, or any burnup that spans teams and sprints. + + For more information, see [Configure a burndown or burnup widget](configure-burndown-burnup-widgets.md). :::column-end::: -:::row-end::: -::: moniker-end +:::row-end::: :::row::: :::column span="1"::: - ### Chart for work items - ![Screenshot of Chart work item query widget.](media/widget-chart-work-query.png) + ### Chart for Work Items + :::image type="icon" source="media/widget-chart-work-query.png"::: :::column-end::: :::column span="1":::
      - - Adds a tile to display a progress or trend chart that builds off a shared work item query. - - From the configuration dialog, select a shared query and [specify the chart type and values](charts.md#add-chart-widget). + + Displays a progress or trend chart that builds off a shared work item query. + + From the configuration dialog, select a shared query and [specify the chart type and values](charts.md). :::column-end::: -:::row-end::: -::: moniker range=">= azure-devops-2019" +:::row-end::: :::row::: :::column span="1"::: - ### Cumulative flow diagram - ![Screenshot of Cumulative flow diagram widget.](media/widget-cfd-chart.png) + ### Cumulative Flow Diagram + :::image type="icon" source="media/widget-cfd-chart.png"::: :::column-end::: :::column span="1":::
      - - Displays the cumulative flow of backlog items based on the time frame, team, backlog level, and swimlane you select. Hover over each color within the chart to see the count of items for a particular Kanban column. - + + Displays the cumulative flow of backlog items based on the time frame, team, backlog level, and swimlane that you select. To display the count of items for a particular board column, hover over each color in the chart. + From the configuration dialog, [specify the team, backlog level, and other parameters you want](cumulative-flow.md#configure-widget). :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019" +:::row-end::: :::row::: :::column span="1"::: - ### Cycle time - ![Screenshot of Cycle time widget.](media/widget-cycle-time.png) + ### Cycle Time + :::image type="icon" source="media/widget-cycle-time.png"::: :::column-end::: :::column span="1":::
      - - Displays the cycle time of work items closed in a specified timeframe for a single team and backlog level. The cycle time of a work item is defined as the time taken to close a work item after work on it has started. Each marker on the chart corresponds to one or more work items with a particular cycle time. The lower the cycle time, the faster work is progressing through your development pipeline. - - To learn more, see [Lead time and cycle time control charts](cycle-time-and-lead-time.md). + + Displays the cycle time of work items closed in a specified timeframe for a single team and backlog level. The cycle time of a work item is defined as the time taken to close a work item after work on it begins. Each marker on the chart corresponds to one or more work items with a particular cycle time. The lower the cycle time, the faster work is progressing through your development pipeline. + + For more information, see [Lead time and cycle time control charts](cycle-time-and-lead-time.md). :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019" +:::row-end::: :::row::: :::column span="1"::: - ### Lead time - ![Screenshot of Lead time widget.](media/widget-lead-time.png) + ### Lead Time + :::image type="icon" source="media/widget-lead-time.png"::: :::column-end::: :::column span="1":::
      - + Displays the lead time of work items closed in a specified timeframe for a single team and backlog level. The lead time of a work item is defined as the time taken to close a work item after it was created. - Each marker on the chart corresponds to one or more work items with a particular lead time. The lower the lead time, the faster work is being delivered to the customer. - - To learn more, see [Lead time and cycle time control charts](cycle-time-and-lead-time.md). + Each marker on the chart corresponds to one or more work items with a particular lead time. The lower the lead time, the faster work is being delivered to the customer. + + For more information, see [Lead time and cycle time control charts](cycle-time-and-lead-time.md). :::column-end::: :::row-end::: -::: moniker-end :::row::: :::column span="1"::: - ### New Work item - ![Screenshot of New work item widget.](media/widget-new-work-items.png) + ### New Work Item + :::image type="icon" source="media/widget-new-work-items.png"::: :::column-end::: :::column span="1":::
      + Enables you to add work items from the dashboard. Work items that you add using this widget are automatically scoped to the team's default **Area Path**. The **Iteration Path** assigned matches the last **Iteration Path** assigned to a work item by the currently signed in user. - + To change team defaults, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). :::column-end::: :::row-end::: :::row::: :::column span="1"::: - ### Query results - ![Screenshot of Query results widget.](media/widget-query-results.png) + ### Query Results + :::image type="icon" source="media/widget-query-results.png"::: :::column-end::: :::column span="1":::
      - Adds a configurable tile that lists the results of a shared query. + A configurable tile that lists the results of a shared query. From the configuration dialog, select either a team favorite or shared query. - + To create a shared query, see [Use the query editor to list and manage queries](../../boards/queries/using-queries.md). :::column-end::: :::row-end::: :::row::: :::column span="1"::: - ### Query tile - ![Screenshot of Query tile widget.](media/widget-query-tile.png) + ### Query Tile + :::image type="icon" source="media/widget-query-tile.png"::: :::column-end::: :::column span="1":::
      - Adds a configurable tile to display the summary of shared query results. - From the configuration dialog, select either a team favorite or shared query. You can optionally specify rules to change the query tile color based on the number of work items returned by the query. - + A configurable tile to display the summary of shared query results. + From the configuration dialog, select either a team favorite or shared query. You can optionally specify rules to change the query tile color based on the number of work items returned by the query. + To create a shared query, see [Use the query editor to list and manage queries](../../boards/queries/using-queries.md). :::column-end::: :::row-end::: ::: moniker range=">= azure-devops-2020" :::row::: :::column span="1"::: - ### Sprint burndown (Analytics) - ![Screenshot of Sprint burndown widget.](media/widget-sprint-burndown-analytics.png) + ### Sprint Burndown (Analytics) + :::image type="icon" source="media/widget-sprint-burndown-analytics.png"::: :::column-end::: :::column span="1":::
      - Adds a team's burndown chart for a sprint to the dashboard. This widget is based on Analytics data. You have several configuration options for this widget, including selecting a team, iteration, and time period. - + A team's burndown chart for a sprint to the dashboard. This widget is based on Analytics data. You have several configuration options for this widget, including selecting a team, iteration, and time period. + Teams [use the burndown chart to mitigate risk and check for scope creep](configure-sprint-burndown.md) throughout the sprint cycle. :::column-end::: :::row-end::: @@ -352,412 +225,346 @@ In addition to the widgets listed here, you can add a work item query chart to y ::: moniker range=">= azure-devops-2020" :::row::: :::column span="1"::: - ### Sprint burndown (Legacy) - ![Screenshot of Sprint burndown widget, legacy version.](media/widget-sprint-burndown-legacy.png) + ### Sprint Burndown (Legacy) + :::image type="icon" source="media/widget-sprint-burndown-legacy.png"::: :::column-end::: :::column span="1":::
      - Adds the team's burndown chart for the current sprint to the dashboard. This chart always displays data for the current sprint. - + The team's burndown chart for the current sprint to the dashboard. This chart always displays data for the current sprint. + Teams [use the burndown chart to mitigate risk and check for scope creep](configure-sprint-burndown.md) throughout the sprint cycle. :::column-end::: :::row-end::: ::: moniker-end -::: moniker range="< azure-devops-2020" -:::row::: - :::column span="1"::: - ### Sprint burndown - ![Screenshot of Sprint burndown widget, Azure DevOps Server 2019 and earlier versions.](media/widget-sprint-burndown.png) - :::column-end::: - :::column span="1"::: -
      - - Adds the team's burndown chart for the current sprint to the dashboard. This chart always displays data for the current sprint. - - Teams [use the burndown chart to mitigate risk and check for scope creep](configure-sprint-burndown.md) throughout the sprint cycle. - :::column-end::: -:::row-end::: -::: moniker-end + :::row::: :::column span="1"::: - ### Sprint capacity - ![Screenshot of Sprint capacity widget.](media/widget-sprint-capacity.png) + ### Sprint Capacity + :::image type="icon" source="media/widget-sprint-capacity.png"::: :::column-end::: :::column span="1":::
      - Inserts the team's capacity bar chart for the current sprint. - To plan and monitor their sprint resources, team set capacity and update Remaining Work throughout the sprint. - - See [Set capacity](../../boards/sprints/set-capacity.md). + The team's capacity bar chart for the current sprint. + To plan and monitor their sprint resources, team set capacity and update Remaining Work throughout the sprint. + + For more information, see [Set capacity](../../boards/sprints/set-capacity.md). :::column-end::: :::row-end::: :::row::: :::column span="1"::: - ### Sprint overview - ![Screenshot of Sprint overview widget.](media/widget-sprint-overview.png) + ### Sprint Overview + :::image type="icon" source="media/widget-sprint-overview.png"::: :::column-end::: :::column span="1":::
      - - - Inserts a configurable overview of sprint progress. You can choose between a count of story points or number of work items. Also, selecting the **Show non-working days** checkbox indicates to count all remaining days in the sprint, regardless of the days the team has selected as days off. + + + A configurable overview of sprint progress. You can choose between a count of story points or number of work items. Selecting the **Show non-working days** checkbox indicates to count all remaining days in the sprint, regardless of the days the team has selected as days off. Teams [plan their sprints by defining sprints](../../organizations/settings/set-iteration-paths-sprints.md) and [assigning backlog items to an iteration](../../boards/sprints/assign-work-sprint.md). :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" :::row::: :::column span="1"::: - ### Velocity - ![Screenshot of Team velocity widget.](media/widget-velocity.png) + ### Velocity + :::image type="icon" source="media/widget-velocity.png"::: :::column-end::: :::column span="1"::: - The Velocity widget tracks a team's capacity to deliver work sprint after sprint. You configure the widget by selecting a team, a work item type, an aggregation field, and the number of sprints. The widget takes advantage of Analytics data. You can track the velocity for a single team, not multiple teams. - + The Velocity widget tracks a team's capacity to deliver work sprint after sprint. You configure the widget by selecting a team, a work item type, an aggregation field, and the number of sprints. The widget takes advantage of Analytics data. You can track the velocity for a single team, not multiple teams. + For additional guidance, see [Velocity](team-velocity.md). :::column-end::: :::row-end::: -::: moniker-end :::row::: :::column span="1"::: - ### Work links - ![Screenshot of Work links widget.](media/widget-work-links.png) + ### Work Links + :::image type="icon" source="media/widget-work-links.png"::: :::column-end::: :::column span="1":::
      - Provides quick access to open these Agile tools and team resources: + Provides quick access to open these Agile tools and team resources: - [Backlog](../../boards/backlogs/create-your-backlog.md) - - [Kanban board](../../boards/boards/kanban-overview.md) - - [Task board](../../boards/sprints/task-board.md) + - [Board](../../boards/boards/kanban-overview.md) + - [Taskboard](../../boards/sprints/task-board.md) - [Queries](../../boards/queries/using-queries.md) :::column-end::: :::row-end::: - - -::: moniker range=">= azure-devops-2019" -## Azure Repos widgets -::: moniker-end - -::: moniker range="tfs-2018" -## Code widgets -::: moniker-end +## Azure Repos widgets Add code tracking widgets to track changes made within a repository or get quick access to Git pull requests for your team. :::row::: :::column span="1"::: - ### Code tile - ![Screenshot of Code tile widget.](media/widget-code-tile.png) + ### Code Tile + :::image type="icon" source="media/widget-code-tile.png"::: :::column-end::: :::column span="1":::
      - Adds a configurable tile to display the summary of a code folder or Git repository. To configure, select the added tile, select a repository, select a branch (Git only) and select a path. The code tile supports both TFVC and Git repositories. + A configurable tile that displays the summary of a code folder or Git repository. To configure, select the added tile, select a repository, select a branch (Git only), and select a path. The code tile supports both Team Foundation Version Control (TFVC) and Git repositories. :::column-end::: :::row-end::: :::row::: :::column span="1"::: - ### Pull request - ![Screenshot of Pull request widget.](media/widget-catalog-pull-request.png) + ### Pull Request + :::image type="icon" source="media/widget-catalog-pull-request.png"::: :::column-end::: :::column span="1":::
      - Adds a configurable widget to display active PRs requested by the team, or assigned to or requested by the person logged in. Select the team and Git repository for the pull requests of interest. - - To learn more about pull requests, see [Review code with pull requests](../../repos/git/pull-requests.md). + A configurable widget that displays active PRs requested by the team, or assigned to or requested by the person logged in. Select the team and Git repository for the pull requests of interest. + + For more information, see [Review code with pull requests](../../repos/git/pull-requests.md). :::column-end::: :::row-end::: ::: moniker range="= azure-devops" :::row::: :::column span="1"::: - ### Pull request (multiple repos) - ![Screenshot of Pull request widget for multiple repos.](media/widget-catalog-pull-request-multi.png) + ### Pull Request (multiple repos) + :::image type="icon" source="media/widget-catalog-pull-request-multi.png"::: :::column-end::: :::column span="1":::
      - - Adds a configurable widget to display active PRs requested by the team, or assigned to or requested by the person logged in. Select the team and up to 10 repositories for the pull requests of interest. - - To learn more about pull requests, see [Review code with pull requests](../../repos/git/pull-requests.md). + + A configurable widget to that displays active PRs requested by the team, or assigned to or requested by the person logged in. Select the team and up to 10 repositories for the pull requests of interest. + + For more information, see [Review code with pull requests](../../repos/git/pull-requests.md). *This widget is currently in private preview* :::column-end::: :::row-end::: ::: moniker-end - -::: moniker range=">= azure-devops-2019" -## Azure Pipelines widgets - -Add build and release pipeline widgets to track the health of your builds and releases. -::: moniker-end - -::: moniker range="tfs-2018" -## Build and Release widgets +## Azure Pipelines widgets Add build and release pipeline widgets to track the health of your builds and releases. -::: moniker-end :::row::: :::column span="1"::: - ### Build history - ![Screenshot of Build history widget.](media/widget-build-history-chart.png) + ### Build History + :::image type="icon" source="media/widget-build-history-chart.png"::: :::column-end::: :::column span="1":::
      - Adds a tile to display a histogram of all builds run for the configured build pipeline. - From the configuration dialog, select the build you want to monitor. - Hover over a bar to learn how long the build took to complete. Select the bar to open the summary for that specific build. Bar color indicates: green-completed, red-failed, and yellow-completed without tests. + Displays a histogram of all builds run for the configured build pipeline. + From the configuration dialog, select the build you want to monitor. + Hover over a bar to learn how long the build took to complete. Select the bar to open the summary for that specific build. Bar color indicates: green-completed, red-failed, and yellow-completed without tests. :::column-end::: :::row-end::: :::row::: :::column span="1"::: - ### Deployment status - ![Screenshot of Deployment status widget.](media/widget-deployment-status.png) + ### Deployment status + :::image type="icon" source="media/widget-deployment-status.png"::: :::column-end::: :::column span="1":::
      - Configurable widget that shows a combined view of the deployment status and test pass rate across multiple environments for a recent set of builds. You configure the widget by specifying a build pipeline, branch, and linked release pipelines. - To view the test summary across multiple environments in a release, the widget provides a matrix view of each environment and corresponding test pass rate. - - You can choose any cell to see a more [detailed view](../../pipelines/test/review-continuous-test-results-after-build.md) for the selected environment. + Configurable widget that shows a combined view of the deployment status and test pass rate across multiple environments for a recent set of builds. Configure the widget by specifying a build pipeline, branch, and linked release pipelines. + To view the test summary across multiple environments in a release, the widget provides a matrix view of each environment and corresponding test pass rate. + + You can choose any cell to get a more [detailed view](../../pipelines/test/review-continuous-test-results-after-build.md) for the selected environment. :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" :::row::: :::column span="1"::: - ### Release pipeline overview - ![Screenshot of Release pipeline overview widget.](media/widget-release-definitions.png) + ### Release Pipeline Overview + :::image type="icon" source="media/widget-release-definitions.png"::: :::column-end::: :::column span="1":::
      - Configurable widget that you can use to view and track the status of a release pipeline. This widget shows the release as a series of environments, with the name of the release and the date or time it was started. - + Configurable widget that you can use to view and track the status of a release pipeline. This widget shows the release as a series of environments, with the name of the release and the date or time it was started. + The color of the heading and the icon in each environment indicate the current status of the release, which are the same as are used on the **Releases** page. Select a release pipeline in the left column to filter the list to just releases for that pipeline. :::column-end::: :::row-end::: -::: moniker-end :::row::: :::column span="1"::: - ### Requirements quality - ![Screenshot of Requirements quality widget.](media/widget-requirements-quality.png) + ### Requirements quality + :::image type="icon" source="media/widget-requirements-quality.png"::: :::column-end::: :::column span="1":::
      - Configurable widget that you can use to track quality continuously from a build or release pipeline. The widget shows the mapping between a requirement and latest test results executed against that requirement. It provides insights into requirements traceability. For example, requirements not meeting the quality, requirements not tested, and so on. + Configurable widget that you can use to track quality continuously from a build or release pipeline. The widget shows the mapping between a requirement and latest test results executed against that requirement. It provides insights into requirements traceability. For example, requirements not meeting the quality, requirements not tested, and so on. - To learn more about setting up traceability see [Requirements traceability](../../pipelines/test/requirements-traceability.md) + For more information, see [Requirements traceability](../../pipelines/test/requirements-traceability.md) :::column-end::: :::row-end::: +## Azure Test Plans widgets -::: moniker range=">= azure-devops-2019" -## Azure Test Plans widgets -::: moniker-end - -::: moniker range="tfs-2018" -## Test widgets -::: moniker-end - - -Add test tracking widgets to your dashboards to show status, progress, or trends of your testing efforts. In addition to the widgets listed here, you can add test tracking charts to your dashboard. To learn more, see [Track test status](../../test/track-test-status.md). +Add test tracking widgets to your dashboards to show status, progress, or trends of your testing efforts. In addition to the widgets listed here, you can add test tracking charts to your dashboard. For more information, see [Track test status](../../test/track-test-status.md). :::row::: :::column span="1"::: - ### Chart for test plans - ![Screenshot of Chart for test plans widget.](media/widget-chart-test-plans.png) + ### Chart for Test Plans + :::image type="icon" source="media/widget-chart-test-plans.png"::: :::column-end::: :::column span="1":::
      - Adds a configurable widget that lets you track the progress of test case authoring or status of test execution for tests in a test plan. Get started by selecting a test plan and a test suite. Then select test case chart for test authoring progress or test results for test execution progress. Finally, select the chart type and the pivots. - - To learn more, see [Track your test results](../../test/track-test-status.md). + A configurable widget that lets you track the progress of test case authoring or status of test execution for tests in a test plan. Get started by selecting a test plan and a test suite. Then select test case chart for test authoring progress or test results for test execution progress. Finally, select the chart type and the pivots. + + For more information, see [Track your test results](../../test/track-test-status.md). :::column-end::: :::row-end::: :::row::: :::column span="1"::: - ### Test results trend - ![Screenshot of Test results trend widget.](media/widget-test-results-trend.png) + ### Test Results Trend + :::image type="icon" source="media/widget-test-results-trend.png"::: :::column-end::: :::column span="1":::
      - Adds a configurable tile that displays the trend of test results for the selected build or release pipeline. The widget helps you visualize the test trends over a period of time, thereby surfacing patterns about test failures, test duration etc. - - From the configuration dialog, select the build or release whose test results you'd like to monitor. There are multiple chart options to choose from (Line, Column & Stacked Column) based on your preference. Optionally you can map the trend of test duration on the existing chart by adding a secondary line chart. + A configurable tile that displays the trend of test results for the selected build or release pipeline. The widget helps you visualize the test trends over a period of time. The widget surfaces patterns about test failures, test duration, and others. + + From the configuration dialog, select the build or release whose test results to monitor. There are multiple chart options to choose from, such as Line, Column, and Stacked Column, based on your preference. Optionally, map the trend of test duration on the existing chart by adding a secondary line chart. - To get deeper insights and higher configurability view [Test Analytics](../../pipelines/test/test-analytics.md) + To get deeper insights and higher configurability, see [Test Analytics](../../pipelines/test/test-analytics.md). :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" :::row::: :::column span="1"::: - + ### Test Results Trend (Advanced) :::column span="1"::: > [!div class="mx-imgBorder"] - > ![Screenshot of Test results trend widget, Advanced version based on Analytics service.](media/widget-test-results-trend-advanced.png) + > :::image type="icon" source="media/widget-test-results-trend-advanced.png"::: :::column-end::: :::column span="1":::
      The Test Results Trend (Advanced) widget provides near real-time visibility into test data for multiple builds and releases. The widget shows a trend of your test results for selected pipelines. You can use it to track the daily count of test, pass rate, and test duration. Tracking test quality over time and improving test collateral is key to maintaining a healthy DevOps pipeline. - The widget supports tracking advanced metrics for one or more build pipelines or release pipelines. The widget also allows filtering of test results by outcome, stacking metrics, and more. - - To learn more, see [Configure the Test Results Trend (Advanced) widget](./configure-test-results-trend.md). + The widget supports tracking advanced metrics for one or more build pipelines or release pipelines. The widget also allows filtering of test results by outcome, stacking metrics, and more. + + For more information, see [Configure the Test Results Trend (Advanced) widget](./configure-test-results-trend.md). :::column-end::: :::row-end::: -::: moniker-end +## Informational content and other links -## Informational content and other links +To support adding, add one or more of the following widgets: -Add one or more of the following widgets to support adding: - Configurable content - Links to features - Functions your team accesses often :::row::: :::column span="1"::: - ### Embedded web page - ![Screenshot of Embedded web page widget.](media/embedded-web-page-widget.png) + ### Embedded Webpage + :::image type="icon" source="media/embedded-web-page-widget.png"::: :::column-end::: :::column span="1":::
      - Adds a configurable tile to display the contents of a web page. The page displayed is interactive. - - Only webpages that allow [iframe embedding](https://go.microsoft.com/fwlink/?LinkId=808035) are supported. + A configurable tile to display the contents of a web page. The page displayed is interactive. + + The widget supports webpages that allow [iframe embedding](https://go.microsoft.com/fwlink/?LinkId=808035). :::column-end::: :::row-end::: :::row::: :::column span="1"::: - ### Markdown - ![Screenshot of Markdown widget.](media/widget-markdown-tile.png) + ### Markdown + :::image type="icon" source="media/widget-markdown-tile.png"::: :::column-end::: :::column span="1":::
      + + A configurable tile to display any type of information, guidance, or links that you want. You can also configure the widget to point to a file stored in your repository. From the configuration dialog, add the information you want to share with your team. - Adds a configurable tile to display any type of information, guidance, or links that you want. You can also configure the widget to point to a file stored in your repository. From the configuration dialog, add the information you want to share with your team. - - To learn more, see [Add Markdown to a dashboard](add-markdown-to-dashboard.md). + For more information, see [Add Markdown to a dashboard](add-markdown-to-dashboard.md). :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" :::row::: :::column span="1"::: - ### Other links - ![Screenshot of Other links widget.](media/widget-other-links.png) + ### Other Links + :::image type="icon" source="media/widget-other-links.png"::: :::column-end::: :::column span="1":::
      - Provides links to the following features: - + Provides links to the following features: + - [Opens a form to initiate a request to provide feedback](/previous-versions/azure/devops/project/feedback/get-feedback) - [Opens the team's quick dialog to add or modify the active sprints or iteration paths for your team](../../boards/sprints/define-sprints.md) - - [Opens the team's quick dialog to modify your team's area path](../../organizations/settings/set-area-paths.md). - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range="< azure-devops-2019" -:::row::: - :::column span="1"::: - ### Other links - ![Screenshot of Other links widget.](media/widget-other-links.png) - :::column-end::: - :::column span="1"::: -
      - - The following links are displayed when the corresponding resource is configured for the project: - - ![Other links widget, TFS-2018 and earlier versions.](media/widget-other-links-tfs.png) - - [View project portal](/previous-versions/azure/devops/report/sharepoint-dashboards/share-information-using-the-project-portal) - - [View process guidance](/previous-versions/azure/devops/project/configure-or-redirect-process-guidance?view=tfs-2017&preserve-view=true) - - [View reports](../sql-reports/reporting-services-reports.md) - - To add or update reports for a project, see [Add reports to a project](/previous-versions/azure/devops/report/admin/add-reports-to-a-team-project). + - [Opens the team's quick dialog to modify your team's area path](../../organizations/settings/set-area-paths.md) :::column-end::: :::row-end::: -::: moniker-end :::row::: :::column span="1"::: - ### Team members - ![Screenshot of Team members widget.](media/widget-team-members.png) + ### Team Members + :::image type="icon" source="media/widget-team-members.png"::: :::column-end::: :::column span="1":::
      - Shows team member profiles and, on-hover, their user alias. - + Shows team member profiles and, on-hover, their user alias. + For team admins, supports access to the quick dialog to [add or remove team members](../../organizations/settings/add-teams.md). > [!NOTE] - > This widget is a convenient way to add team members to specific teams within projects. If you remove it, you can still [add members to your team from the team administration page](../../organizations/settings/add-teams.md#add-team-members). + > This widget is a convenient way to add team members to specific teams within projects. If you remove it, you can still add users to your team from the team administration page. :::column-end::: :::row-end::: :::row::: :::column span="1"::: - ### Visual Studio Shortcuts - ![Screenshot of Visual Studio widget.](media/widget-visual-studio.png) + ### Visual Studio Shortcuts + :::image type="icon" source="media/widget-visual-studio.png"::: :::column-end::: :::column span="1":::
      - Provides links to open or download Visual Studio. - - The Visual Studio IDE client comes with the [Team Explorer plug-in](../../user-guide/work-team-explorer.md) which provides quick access to several features (some of which aren't available through the web portal). + Provides links to open or download Visual Studio. + + The Visual Studio IDE client comes with the [Team Explorer plug-in](../../user-guide/work-team-explorer.md) which provides quick access to several features, some of which aren't available through the web portal. :::column-end::: :::row-end::: :::row::: :::column span="1"::: - ### Welcome - ![Screenshot of How to links widget.](media/widget-how-to-links.png) + ### Welcome + :::image type="icon" source="media/widget-how-to-links.png"::: :::column-end::: :::column span="1":::
      - Provides links to the major Azure DevOps Services—work tracking boards, code, and builds—and reference documentation on how to add charts. - - :::image type="content" source="media/catalog/welcome-tile.png" alt-text="Screenshot of Welcome widget tile."::: + Provides links to the major services, including work tracking boards, code, and builds, and reference documentation on how to add charts. + + :::image type="content" source="media/catalog/welcome-tile.png" alt-text="Screenshot shows the Welcome widget tile."::: :::column-end::: :::row-end::: - + ## Marketplace widgets -You may find more widgets of interest in the [Marketplace](https://marketplace.visualstudio.com/search?term=webpage%20widget&target=VSTS&sortBy=Relevance). +You might find more widgets of interest in the [Marketplace](https://marketplace.visualstudio.com/search?term=webpage%20widget&target=VSTS&sortBy=Relevance). + +If your organization owner or project collection administrator disables a marketplace widget, an image similar to the following image displays: -If your organization owner or project collection administrator disables a marketplace widget, you'll see the following image: :::image type="content" source="media/widget-catalog-disabled-widget.png" alt-text="Screenshot of Disabled widget extension notification."::: -To regain access to it, request your admin to reinstate or reinstall the widget. +To regain access to it, request your admin to reinstate or reinstall the widget. -## Extensibility +## Extensibility -Using the REST API service, you can [create a dashboard widget](../../extend/develop/add-dashboard-widget.md). To learn more about the REST APIs for dashboards and widgets, see [Dashboards (API)](/rest/api/azure/devops/dashboard/dashboards). +Using the REST API service, you can [create a dashboard widget](../../extend/develop/add-dashboard-widget.md). For more information about the REST APIs for dashboards and widgets, see [Dashboards (API)](/rest/api/azure/devops/dashboard/dashboards). ## Related articles -- [FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml) +- [View FAQs on Azure DevOps dashboards, charts, and reports](faqs.yml) - [Track progress with status and trend query-based charts](charts.md) - [Add, rename, and delete dashboards](dashboards.md) -- [Add charts and widgets to a dashboard](add-widget-to-dashboard.md) +- [Add widgets to a dashboard](add-widget-to-dashboard.md) - [Add Markdown to a dashboard](add-markdown-to-dashboard.md) diff --git a/docs/report/extend-analytics/account-scoped-queries.md b/docs/report/extend-analytics/account-scoped-queries.md index 929838eac06..ae5c2a8311d 100644 --- a/docs/report/extend-analytics/account-scoped-queries.md +++ b/docs/report/extend-analytics/account-scoped-queries.md @@ -6,27 +6,28 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: quickstart -monikerRange: '>= azure-devops-2019' -ms.date: 12/13/2022 +monikerRange: "<=azure-devops" +ms.date: 02/12/2025 --- # Project and organization-scoped queries [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Using Analytics for Azure DevOps, you can construct queries that are scoped to a project or an organization or collection. You can run these queries directly in your browser or within Power BI. +Using Analytics for Azure DevOps, you can construct queries that are scoped to a project or an organization or collection. You can run these queries directly in your browser or within Power BI. Project-scope queries help answer questions about a single project whereas organization and collection scoped queries allow you to answer questions that cross project boundaries. Organization and collection scoped queries require broader user permissions or careful scoping restrictions to ensure that your query isn't blocked due to a lack of permissions. [!INCLUDE [temp](../includes/analytics-preview.md)] +## Prerequisites + [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] > [!IMPORTANT] -> If you don't have access to all projects in an organization, it is recommended that you apply a project filter to all of your queries. When pulling data into client tools such as Power BI or Excel, using the project path syntax is the best way to ensure that all your data is constrained by the given project. We recommend you use organization-scoped or collection-scoped queries only when you need to report on two or more projects. - +> If you don't have access to all projects in an organization, apply a project filter to all of your queries. When pulling data into client tools such as Power BI or Excel, use the project path syntax to ensure that all your data is constrained by the given project. Use organization-scoped or collection-scoped queries only when you need to report on two or more projects. - + ## Project-scoped queries @@ -34,7 +35,6 @@ You construct a query by entering the OData URL into a [supported web browser](/ The base URL for a project-level OData query is as shown in the following syntax. - # [**Cloud** (Azure DevOps Services](#tab/cloud) ```OData @@ -55,12 +55,10 @@ In the examples provided, make the following replacements: *** - > [!NOTE] -> The remaining examples provided in this article are based on a Azure DevOps Services URL. You will need to substitute in your Azure DevOps Server URL to exercise the examples. - +> The remaining examples in this article are based on an Azure DevOps Services URL. Substitute your Azure DevOps Server URL to use the examples. - + ### Return a count of work items @@ -70,7 +68,7 @@ For example, the following project-scoped query returns the count of work items https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems/$count ``` -For example, a query of the Fabrikam Fiber project returns a count of 7126 work items. Deleted work items aren't included in the count. +For example, a query of the Fabrikam Fiber project returns a count of 7,126 work items. Deleted work items aren't included in the count. ```OData https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/WorkItems/$count @@ -80,7 +78,7 @@ https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/WorkItems/$c ### Return project Area Paths -Likewise, the following query string will return the areas for a specific project: +Likewise, the following query string returns the areas for a specific project: ```OData https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/Areas @@ -93,7 +91,6 @@ https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/Areas? $filter=Project/ProjectName eq '{ProjectName}' ``` - For example, a query of the Fabrikam Fiber project returns all properties defined for an Area Path as no `$select` operator is applied in the query. ```OData https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/Areas @@ -125,7 +122,7 @@ AreaLevel14 null Depth 1 ``` - + ### Use of the $expand option @@ -138,7 +135,7 @@ https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/Wor $expand=Parent ``` -is filtered automatically to enforce security: +Is filtered automatically to enforce security: ```OData https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems? @@ -146,7 +143,7 @@ https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems? &$expand=Parent($filter=ProjectName eq '{ProjectName}') ``` - + ## Organization-scoped queries @@ -184,7 +181,7 @@ https://analytics.dev.azure.com/msft-skilling/_odata/v1.0/WorkItems? --> - + ### Return the parent of all work items @@ -204,15 +201,15 @@ https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems? &$expand=Parent($filter=Project/ProjectName eq '{ProjectName}') ``` -Without the other filter, the request will fail if the parent of any work item references work items in a project that you don't have read access to. +Without the additional filter, the request fails if the parent of any work item references work items in a project to which you don't have **Read** access. - + ## Project-level security restrictions Analytics has a few more restrictions on query syntax related to project level security. -The `any` or `all` filters apply to the base entity on an `$expand`. For filters based on a project, we explicitly ignore the filter when using an `$expand`: +The `any` or `all` filters apply to the base entity on an `$expand`. For filters based on a project, we explicitly ignore the filter when using an `$expand`: For example, the following query: @@ -230,7 +227,7 @@ https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems? &$expand=Children ``` -and will fail if you don't have access to all projects. +And fails if you don't have access to all projects. To work around the restriction, you need to add an extra expression in the `$filter`: diff --git a/docs/report/extend-analytics/aggregated-data-analytics.md b/docs/report/extend-analytics/aggregated-data-analytics.md index 2991e9fb276..666ad4ed303 100644 --- a/docs/report/extend-analytics/aggregated-data-analytics.md +++ b/docs/report/extend-analytics/aggregated-data-analytics.md @@ -6,7 +6,7 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: tutorial -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 11/04/2022 --- @@ -16,7 +16,6 @@ ms.date: 11/04/2022 You can get a sum of your work tracking data in one of two ways using Analytics with OData. The first method returns a simple count of work items based on your OData query. The second method returns a JSON formatted result based on your OData query that exercises the OData Aggregation Extension. - This article builds off information provided in [Construct OData queries for Analytics](../analytics/analytics-query-parts.md) and [Define basic queries using OData Analytics](wit-analytics.md). Also, the queries is this article are focused on retrieving work item data, however, the principles apply for querying other entity sets. In this article you'll learn: @@ -29,16 +28,17 @@ In this article you'll learn: To learn how to generate simple counts, see [Return a count of items (no other data)](wit-analytics.md#return-a-count-of-items-no-other-data) and [Return a count of items and data](wit-analytics.md#return-a-count-of-items-and-data). - [!INCLUDE [temp](../includes/analytics-preview.md)] +## Prerequisites + +[!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] ## What is the Aggregation Extension for OData? Analytics relies on OData to author queries over your work tracking data. Aggregations in OData are achieved using an extension that introduces the `$apply` keyword. We have some examples of how to use this keyword below. Learn more about the extension at [OData Extension for Data Aggregation](https://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/cs01/odata-data-aggregation-ext-v4.0-cs01.html). - - + ## Aggregate data using the OData aggregation extension @@ -52,13 +52,12 @@ Where: - {aggregationType} will specify the type of aggregation used - {newColumnName} specifies the name of the column having values after aggregation. - + ## Aggregated data using the apply extension Using the `$apply` extension, you can obtain counts, sums, and additional information when you query your work tracking data. - **Return the sum of all remaining work** > [!div class="tabbedCodeSnippets"] @@ -75,13 +74,13 @@ Using the `$apply` extension, you can obtain counts, sums, and additional inform > $apply=aggregate(WorkItemId with max as MaxWorkItemId) > ``` - + ## Group results using the groupby clause The OData aggregation extension also supports a `groupby` clause that is identical to the SQL `GROUP BY` clause. You can use this clause to quickly break down numbers in more detail. -For example, thie following clause returns a count of work items: +For example, the following clause returns a count of work items: > [!div class="tabbedCodeSnippets"] > ```OData @@ -168,7 +167,7 @@ https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/Areas? - + ## Filter aggregated results @@ -188,7 +187,7 @@ Filters look like this example: > [!NOTE] > You don't have to provide the `groupby` clause. You can simply use the `aggregate` clause to return a single value. - + ## Generate multiple aggregations within a single call @@ -209,8 +208,7 @@ It will return a result that looks like this example: > } > ``` - - + ## Generate calculated properties for use within a single call @@ -229,7 +227,7 @@ You might need to use a mathematical expression to calculate properties for use > } > ``` - + ## Generate a Cumulative Flow Diagram from aggregate data @@ -275,7 +273,6 @@ When refreshing Power BI or Excel, the fewer rows required, the faster the refre > [!div class="nextstepaction"] > [Query trend data](querying-for-trend-data.md) - ## Related articles - [Define basic queries using OData Analytics](wit-analytics.md) @@ -283,7 +280,6 @@ When refreshing Power BI or Excel, the fewer rows required, the faster the refre +If a query tries to access the data in a project for which you don't have access, you get the following error message.--> To work around this problem, you can either explicitly add a project filter, or use the [project-scoped endpoint](#project-scoped-endpoint) as explained later in this article. @@ -128,9 +123,9 @@ For example, the following query fetches work items that belong to projects name ### ✔️ DO specify project filter inside the `$expand` clause if your expansion could include data in other, potentially inaccessible projects -When you expand navigation properties, there's a chance that you'll end up referencing data from other, inaccessible projects. If you reference inaccessible data, you'll receive the same error message listed previously, "*"The query results include data in one or more projects...*". Similarly, you can resolve this problem by adding explicit project filters to control the expanded data. +When you expand navigation properties, there's a chance that you end up referencing data from other, inaccessible projects. If you reference inaccessible data, you receive the same error message listed previously, *"The query results include data in one or more projects...*". Similarly, you can resolve this problem by adding explicit project filters to control the expanded data. -You can do so in the regular `$filter` clause for simple navigation properties. For example, the query below explicitly asks for `WorkItemLinks` where both the link and its target exist in the same project. +You can do so in the regular `$filter` clause for simple navigation properties. For example, the following query explicitly asks for `WorkItemLinks` where both the link and its target exist in the same project. > [!div class="tabbedCodeSnippets"] > ```OData @@ -150,7 +145,7 @@ Instead, you can move the filter to `$filter` expand option in the `$expand` cla > &$expand=TargetWorkItem($filter=ProjectSK eq {projectSK}; $select=WorkItemId, Title) > ``` -You'll find that the `$filter` expand option is useful when you use the expand collection property such as `Children` in `WorkItems` entity set. For example, the following query returns all work items from a given project together with all their children that belong in the same project. +The `$filter` expand option is useful when you use the expand collection property such as `Children` in `WorkItems` entity set. For example, the following query returns all work items from a given project together with all their children that belong in the same project. > [!div class="tabbedCodeSnippets"] > ```OData @@ -160,7 +155,7 @@ You'll find that the `$filter` expand option is useful when you use the expand c > &$expand=Children($filter=ProjectSK eq {projectSK}; $select=WorkItemId, Title) > ``` -You'll need to specify the filter if you expand one of the following properties: +Specify the filter if you expand one of the following properties: * `WorkItems` entity set: `Parent`, `Children` * `WorkItemLinks` entity set: `TargetWorkItem`. @@ -194,7 +189,7 @@ You can apply this solution only when your focus is data from a single project. ### ✔️ DO wait or stop the operation if your query exceeds usage limits -If you execute many queries, or the queries require many resources to run, you might exceed service limits and get temporarily blocked. If you exceed the service limits, stop your operation as chances are that the next query you send will fail with the same error message. +If you execute many queries, or the queries require many resources to run, you might exceed service limits and get temporarily blocked. If you exceed the service limits, stop your operation as chances are that the next query you send fails with the same error message. >*Request was blocked due to exceeding usage of resource '{resource}' in namespace '{namespace}'.* @@ -205,7 +200,7 @@ To learn how to design efficient OData queries, refer to [Performance Guidelines ### ✔️ DO wait or stop the operation if your query fails with a timeout -Similar to exceeding usage limits, you should wait or stop the operation if your query comes across a timeout. It could signal a transient problem, so you may retry once to see if the problem resolves. However, persistent timeouts indicate that the query is probably too expensive to run. Further retries will only result in exceeding usage limits and you'll get blocked. +Similar to exceeding usage limits, you should wait or stop the operation if your query comes across a timeout. It could signal a transient problem, so you may retry once to see if the problem resolves. However, persistent timeouts indicate that the query is probably too expensive to run. Further retries only result in exceeding usage limits and you get blocked. >*TF400733: The request has been canceled: The request has exceeded request timeout, please try again.* @@ -217,7 +212,7 @@ Timeouts indicate that a query requires optimization. To learn how to design eff Snapshot entity sets with the `Snapshot` suffix are special because they're modeled as *daily snapshots*. You can use them to get a state of entities as they were at the end of each day in the past. For example, if you queried `WorkItemSnapshot` and filter to a single `WorkItemId`, you would get one record for each day since the work item was created. Loading directly all of this data would be expensive and most likely would exceed usage limits and be blocked. However, aggregations on these entities are both allowed and recommended. In fact, the snapshot entity sets were designed with aggregation scenarios in mind. -For example, the query below gets the number of work items as by date to observe how it grew in January 2020. +For example, the following query gets the number of work items as by date to observe how it grew in January 2020. > [!div class="tabbedCodeSnippets"] > ```OData @@ -227,7 +222,7 @@ For example, the query below gets the number of work items as by date to observe > groupby((DateSK), aggregate($count as Count)) > ``` -To learn more about aggregations, see [Aggregate data](aggregated-data-analytics.md). +For more information about aggregations, see [Aggregate data](aggregated-data-analytics.md). @@ -251,7 +246,7 @@ As the error messages hints, certain client tools can abuse direct entity addres ### ✔️ DO explicitly address entities with filter clauses -If you want to fetch data for a single entity, you should use the same approach as for a collection of entities and explicitly define filters in the `$filter` clause. +If you want to fetch data for a single entity, you should use the same approach as for a collection of entities, and explicitly define filters in the `$filter` clause. For example, the following query gets a single work item by its identifier. @@ -279,7 +274,7 @@ If you're not sure which properties you should include in such a filter, you can ### ❌ [BLOCKED] DON'T expand `Revisions` on `WorkItem` entity -The Analytics data model disallows certain types of expansions. One of them, which might be surprising to some, is the `Revisions` collection property on the `WorkItem` entity. If you try to expand this property, you'll receive the following error message. +The Analytics data model disallows certain types of expansions. One of them, which might be surprising to some, is the `Revisions` collection property on the `WorkItem` entity. If you try to expand this property, you receive the following error message. >*The query specified in the URI is not valid. The property 'Revisions' cannot be used in the $expand query option.* @@ -309,12 +304,11 @@ If you care about the full history for all the work items that match certain cri > &$select=WorkItemId, Title > ``` - ### ❌ [BLOCKED] DON'T group on distinct columns -You use a grouping operation to reduce the number of records. Using distinct columns in the `groupby` clause indicates a problem, and the query will fail immediately. Should you accidentally run into this situation, you'll receive the following error message. +You use a grouping operation to reduce the number of records. Using distinct columns in the `groupby` clause indicates a problem, and the query fails immediately. Should you accidentally run into this situation, you receive the following error message. > *One or more of the columns specified in the groupby clause of this query are not recommended.* @@ -324,7 +318,7 @@ To resolve this problem, remove the distinct column from the `groupby` clause. ### ❌ [BLOCKED] DON'T use `countdistinct` aggregation -Analytics doesn't support the `countdistinct` function, even though OData does. While we plan to add support in the future, it currently isn't available. A query that contains this function will return the following error message. +Analytics doesn't support the `countdistinct` function, even though OData does. While we plan to add support in the future, it currently isn't available. A query that contains this function returns the following error message. > *Queries which apply a count distinct with an aggregation are not supported.* @@ -342,23 +336,22 @@ You can incur problems with long queries. Particularly, problems might occur whe - You query a project with many custom fields. - Your query is constructed programmatically. -The current limit of OData queries sent with `HTTP GET` is 3,000 characters. If you exceed it, you'll get back a "*404 Not Found*" response. +The current limit of OData queries sent with `HTTP GET` is 3,000 characters. If you exceed it, you get back a "*404 Not Found*" response. ```http HTTP/1.1 404 Not Found Content-Length: 0 ``` -To resolve this problem, use the OData batch endpoint as explained in the specification, [OData Version 4.0. Part 1: Protocol - 11.7 Batch Requests](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part1-protocol/odata-v4.0-errata03-os-part1-protocol-complete.html#_Toc453752313). Batch capability was primarily designed to group multiple operations into a single `HTTP` request payload, but you can also use it as a workaround for the query length limitation. By sending an `HTTP POST` request, you can pass a query of an arbitrary length and it will be correctly interpreted by the service. - +To resolve this problem, use the OData batch endpoint as explained in the specification, [OData Version 4.0. Part 1: Protocol - 11.7 Batch Requests](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part1-protocol/odata-v4.0-errata03-os-part1-protocol-complete.html#_Toc453752313). Batch capability was primarily designed to group multiple operations into a single `HTTP` request payload, but you can also use it as a workaround for the query length limitation. By sending an `HTTP POST` request, you can pass a query of an arbitrary length and the service correctly interprets it. ### ❌ [BLOCKED] DON'T use batch endpoint for sending multiple queries -We restrict use of the batch endpoint from handling a batch of multiple requests. A single request can still have only one query. If you try to send a batch of several queries, the operation will fail with the following error message. The only solution is to split queries into multiple requests. +We restrict use of the batch endpoint from handling a batch of multiple requests. A single request can still have only one query. If you try to send a batch of several queries, the operation fails with the following error message. The only solution is to split queries into multiple requests. -> *Analytics doesn't support processing of multiple operations which the current batch message contains. Analytics uses OData batch in order to support POST requests, but requires you limit the operation to a single request.* +*Analytics doesn't support processing of multiple operations that the current batch message contains. Analytics uses OData batch in order to support POST requests, but requires that you limit the operation to a single request.* @@ -376,7 +369,7 @@ Add a $select clause to your query, and to $expand operations in your query, to We recommend that you evaluate your approach whenever you construct a long query. While there are many scenarios that need a long query (for example, complex filters or a long list of properties), typically they provide an early indicator of a suboptimal design. -When your query contains many entity keys in the query (for example, `WorkItemId eq {id 1} or WorkItemId eq {id 2} or ...`), you can probably rewrite it. Instead of passing the identifiers, try to define some other criteria that will select the same set of entities. Sometimes may need to modify your process (for example, add a new field or tag), but it's typically worth it. Queries that use more abstract filters are easier to maintain and have a greater potential to work better. +When your query contains many entity keys in the query (for example, `WorkItemId eq {id 1} or WorkItemId eq {id 2} or ...`), you can probably rewrite it. Instead of passing the identifiers, try to define some other criteria that select the same set of entities. Sometimes may need to modify your process (for example, add a new field or tag), but it's typically worth it. Queries that use more abstract filters are easier to maintain and have a greater potential to work better. Another scenario that tends to generate long queries occurs when you include many individual dates (for example, `DateSK eq {dateSK 1} or DateSK eq {dateSK 2} or ...`). Look for another pattern that you can use to create a more abstract filter. For example, the following query returns all work items that were created on Monday. @@ -387,12 +380,11 @@ Another scenario that tends to generate long queries occurs when you include man > &$select=WorkItemId, Title, State > ``` - ### ✔️ DO specify time zone when filtering on date columns -The time zone (`Edm.DateTimeOffset`) exposes all date and time information with an offset that matches the [organization's time zone settings](../../organizations/accounts/change-time-zone.md). This data is precise and simple to interpret at the same time. Another non-obvious consequence is that all the filters have to pass the time zone information as well. If you skip it, you'll get the following error message. +The time zone (`Edm.DateTimeOffset`) exposes all date and time information with an offset that matches the [organization's time zone settings](../../organizations/accounts/change-time-zone.md). This data is precise and simple to interpret at the same time. Another nonobvious consequence is that all the filters have to pass the time zone information as well. If you skip it, you get the following error message. > *The query specified in the URI is not valid. No datetime offset was specified. Please use either of these formats YYYY-MM-ddZ to specify everything since midnight or yyyy-MM-ddThh:mm-hh:mm (ISO 8601 standard representation of dates and times) to specify the offset.* @@ -405,7 +397,7 @@ To solve this problem, add the time zone information. For example, assuming that > &$select=WorkItemId, Title, State > ``` -The same solution works for time zones with positive offsets, however, the plus character (`+`) has a special meaning in the URI and you must handle it correctly. If you specify `2020-01-01T00:00:00+08:00` (with a `+` character) as your starting point, you'll get the following error. +The same solution works for time zones with positive offsets, however, the plus character (`+`) has a special meaning in the URI and you must handle it correctly. If you specify `2020-01-01T00:00:00+08:00` (with a `+` character) as your starting point, you get the following error. > *The query specified in the URI is not valid. Syntax error at position 31 in 'CreatedDate ge 2020-01-01T0000 08:00'.* @@ -427,7 +419,7 @@ An alternative approach is to use date surrogate key properties as they don't ke > &$select=WorkItemId, Title, State > ``` - + ## Performance guidelines @@ -444,7 +436,6 @@ An alternative approach is to use date surrogate key properties as they don't ke - [✔️ DO use server-driven paging](#perf-paging) - [✔️ DO use `$top` query option to limit the number of records](#perf-top) - ### Don't's - [❌ DON'T use `tolower` and `toupper` functions to do case-insensitive comparison](#perf-case-sensitive) @@ -453,21 +444,16 @@ An alternative approach is to use date surrogate key properties as they don't ke ### Consider -- [✔️ CONSIDER writing query to return small number of records](#perf-small-number) +- [✔️ CONSIDER writing queries to return small numbers of records](#perf-small-number) - [✔️ CONSIDER limiting the number of selected properties to minimum](#perf-limit-number) - [✔️ CONSIDER filtering on date surrogate key properties (`DateSK` suffix)](#perf-filter-date) - [✔️ CONSIDER filtering on surrogate key columns](#perf-filter-surrogate) - [✔️ CONSIDER passing `vsts.analytics.maxsize` preference in the header](#perf-max-size) - ### Avoid - [❌ AVOID using `Parent`, `Children`, or `Revisions` properties in the `$filter` or `$expand` clauses](#perf-avoid-parent-child) - - - - ### ✔️ DO measure the effect of implementing a performance guideline @@ -476,15 +462,15 @@ As with any performance recommendations, you shouldn't blindly implement them. I There are many options to measure performance. The simplest one is to run two versions of the same query directly in the browser. Observe the time it takes in the developer tools. For example, you can use [Network panel](/microsoft-edge/devtools-guide/network#network-request-list) in [Microsoft Edge F12 Developer Tools](/microsoft-edge/devtools-guide)). Another option is to capture this information using [Fiddler Web Debugger Tool](/windows/win32/win7appqual/fiddler-web-debugger-tool). -Whatever your approach is, run both queries multiple times. For example, run the queries 30 times each to have a sufficiently large sample set. Then figure out the performance characteristics. Analytics follows multi-tenant architecture. So, duration of your queries might be affected by other operations that occur at the same time. +Whatever your approach is, run both queries multiple times. For example, run the queries 30 times each to have a sufficiently large sample set. Then figure out the performance characteristics. Analytics follows multi-tenant architecture. So, other operations occurring at the same time can affect the duration of your queries. ### ✔️ DO use aggregation extensions -By far the best thing you can do to improve performance of your queries is to use aggregation extension - [OData Extension for Data Aggregation](https://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/cs01/odata-data-aggregation-ext-v4.0-cs01.html). With the aggregation extension, ask the service to summarize data server-side and return a much smaller response than what you can fetch by applying the same function client-side. Finally, Analytics is optimized for this type of queries, so make use of it. +By far the best thing you can do to improve performance of your queries is to use aggregation extension - [OData Extension for Data Aggregation](https://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/cs01/odata-data-aggregation-ext-v4.0-cs01.html). With the aggregation extension, ask the service to summarize data server-side and return a smaller response than what you can fetch by applying the same function client-side. Finally, Analytics is optimized for this type of queries, so make use of it. -To learn more, see [Aggregate data](aggregated-data-analytics.md). +For more information, see [Aggregate data](aggregated-data-analytics.md). @@ -501,15 +487,15 @@ For example, the following query specifies the columns for work items. > ``` > > [!NOTE] -> Azure DevOps supports process customization. Some administrators use this feature and create hundreds of custom fields. If you omit the `$select` clause, your query will return all fields, including custom fields. +> Azure DevOps supports process customization. Some administrators use this feature and create hundreds of custom fields. If you omit the `$select` clause, your query returns all fields, including custom fields. ### ✔️ DO specify columns in the `$select` expand option inside the `$expand` clause -Similarly to the `$select` clause guidelines, specify the properties in the `$select` expand option within the `$expand` clause. It's easy to forget, but if you omit it, your response will contain all the properties from the expanded object. +Similarly to the `$select` clause guidelines, specify the properties in the `$select` expand option within the `$expand` clause. It's easy to forget, but if you omit it, your response contains all the properties from the expanded object. -For example, the query below specifies the columns for both the work item and its parent. +For example, the following query specifies the columns for both the work item and its parent. > [!div class="tabbedCodeSnippets"] > ```OData @@ -524,7 +510,7 @@ For example, the query below specifies the columns for both the work item and it When you query for historical data, the chances are that you're interested in the most recent period (for example, 30 days, 90 days). Because of how work items entities are implemented, there's a convenient way for you to write such queries to get great performance. Each time you update a work item it creates a new revision and records this action in the `System.RevisedDate` field, which makes it perfect for history filters. -In Analytics, the revised date is represented by `RevisedDate` (`Edm.DateTimeOffset`) and `RevisedDateSK` (`Edm.Int32`) properties. For best performance, use the latter. It's the date *surrogate key* and it represents the date when a revision was created or it has `null` for active, incompleted revisions. If you want all the dates since the `{startDate}` inclusive, add the following filter to your query. +In Analytics, the revised date is shown in the `RevisedDate` (`Edm.DateTimeOffset`) and `RevisedDateSK` (`Edm.Int32`) properties. For best performance, use the latter. It's the date *surrogate key* and it represents the date when a revision was created or it has `null` for active, incompleted revisions. If you want all the dates since the `{startDate}` inclusive, add the following filter to your query. `RevisedDateSK eq null or RevisedDateSK gt {startDateSK}` @@ -550,7 +536,7 @@ For example, the following query returns the number of work items for each day s ### ✔️ DO use weekly or monthly snapshots for trend queries that span a long time period -By default, all the snapshot tables are modeled as *daily snapshot fact* tables. If you query for a time range it will get a value for each day. Long time ranges result in a large number of records. If you don't need such high precision, you can use weekly or even monthly snapshots. +By default, all the snapshot tables are modeled as *daily snapshot fact* tables. If you query for a time range it gets a value for each day. Long time ranges result in a large number of records. If you don't need such high precision, you can use weekly or even monthly snapshots. You can do so with other filter expressions to remove days that don't finish a given week or month. Use the `IsLastDayOfPeriod` property, which was added to Analytics with this scenario in mind. This property is of type `Microsoft.VisualStudio.Services.Analytics.Model.Period` and can determine if a day finishes in different periods (for example, weeks, months, and so on). @@ -593,7 +579,6 @@ For example, the following query returns a count of work items that were defined > ) > ``` - @@ -644,16 +629,15 @@ For example, the following query gets all the work items that were tagged with a > ``` > > [!IMPORTANT] -> Property `TagNames` has a length limit of 1024 characters. It contains a set of tags that fit within that limit. If a work item has many tags or the tags are very long, then `TagNames` will not contain the full set and `Tag` navigation property should be used instead. - +> Property `TagNames` has a length limit of 1024 characters. It contains a set of tags that fit within that limit. If a work item has many tags or the tags are very long, then `TagNames` don't contain the full set and `Tag` navigation property should be used instead. ### ❌ DON'T use `tolower` and `toupper` functions to do case-insensitive comparison -If you've worked with other systems, you might expect you need to use `tolower` or `toupper` functions for the case-insensitive comparison. With Analytics all the string comparisons are case-insensitive by default, so you don't need to apply any functions to explicitly handle it. +If you've worked with other systems, you might expect to use the `tolower` or `toupper` functions for the case-insensitive comparison. With Analytics, all the string comparisons are case-insensitive by default, so you don't need to apply any functions to explicitly handle it. -For example, the following query gets all the work items tagged with "QUALITY", "quality" or any other case combination of this word. +For example, the following query gets all the work items tagged with "QUALITY," "quality," or any other case combination of this word. > [!div class="tabbedCodeSnippets"] > ```OData @@ -668,13 +652,13 @@ For example, the following query gets all the work items tagged with "QUALITY", OData has the capability to expand all the levels of a hierarchical structure. For example, work item tracking has some entities where an unbounded expansion could be applied. This operation works only for organizations with a small amount of data. It doesn't scale well for larger datasets. Don't use it at all if: - You're working with large datasets. -- You're developing a widget and you have no control over where the widget will be installed. +- You're developing a widget and you have no control over where the widget gets installed. ### ✔️ DO use server-driven paging -If you ask for a set that is too large to be sent in a single response, Analytics will apply paging. The response will include only a partial set and a link that allows retrieving the next partial set of items. This strategy is described in the OData specification - [OData Version 4.0. Part 1: Protocol - Server-Driven Paging](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part1-protocol/odata-v4.0-errata03-os-part1-protocol-complete.html#_Server-Driven_Paging). By letting the service control the paging, you get the best performance as the `skiptoken` has been carefully design for each entity to be as efficient as possible. +If you ask for a set that is too large to be sent in a single response, Analytics applies paging. The response includes only a partial set and a link that allows retrieving the next partial set of items. This strategy is described in the OData specification - [OData Version 4.0. Part 1: Protocol - Server-Driven Paging](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part1-protocol/odata-v4.0-errata03-os-part1-protocol-complete.html#_Server-Driven_Paging). By letting the service control the paging, you get the best performance as the `skiptoken` has been carefully design for each entity to be as efficient as possible. The link to the next page is included in the `@odata.nextLink` property. @@ -697,14 +681,12 @@ The link to the next page is included in the `@odata.nextLink` property. With other REST APIs, you might have implemented client-driven paging with `$top` and `$skip` query options. Don't use them with Analytics. There are several problems with this approach and performance is one of them. Instead, adopt the server-driven paging strategy described in the previous section. - ### ✔️ DO use `$top` query option to limit the number of records Query option `$top` is only discouraged when used together with `$skip`. If in your reporting scenario you need only a subset of records (for example, sample), it's fine to use `$top` query option. Additionally, if you need to rank records according to some criteria, you should always use `$top` in combination with `$orderby` to get stable result with top ranked records. - ### ✔️ CONSIDER writing a query to return small number of records @@ -757,14 +739,13 @@ Work items are the most expensive entities in the whole data model. They have se For example, instead of expanding `Parent`, you can fetch more work items and use `ParentWorkItemId` property to reconstruct the full hierarchy client-side. Carry out such optimization on a case-by-case basis. - ### ✔️ CONSIDER passing `VSTS.Analytics.MaxSize` preference in the header -When you execute a query, you don't know the number of records that the query will return. You have to either send another query with aggregations or follow all the next links and fetch the entire dataset. Analytics respects `VSTS.Analytics.MaxSize` preference, which lets you fail fast in those instances that the dataset is bigger than what your client can accept. +When you execute a query, you don't know the number of records that the query returns. Either send another query with aggregations or follow all the next links and fetch the entire dataset. Analytics respects `VSTS.Analytics.MaxSize` preference, which lets you fail fast in those instances that the dataset is bigger than what your client can accept. -This option is helpful in data export scenarios. To use it, you have to add `Prefer` header to your HTTP request and set `VSTS.Analytics.MaxSize` to a non-negative value. The `VSTS.Analytics.MaxSize` value represents the maximum number of records you can accept. If you set it to zero, then a default value of 200K will be used. +This option is helpful in data export scenarios. To use it, you have to add `Prefer` header to your HTTP request and set `VSTS.Analytics.MaxSize` to a non-negative value. The `VSTS.Analytics.MaxSize` value represents the maximum number of records you can accept. If you set it to zero, then a default value of 200 K gets used. For example, the following query returns work items if the dataset is smaller or equal to 1000 records. @@ -776,10 +757,11 @@ OData-MaxVersion: 4.0 Accept: application/json;odata.metadata=minimal Host: analytics.dev.azure.com/{OrganizationName} ``` -If the dataset exceeds the limit of 1000 records, the query will immediately fail with the following error. +If the dataset exceeds the limit of 1000 records, the query immediately fails with the following error. > *Query result contains 1,296 rows and it exceeds maximum allowed size of 1000. Please reduce the number of records by applying additional filters* +For information about setting the max page size, see [ODataPreferenceHeader.MaxPageSize property](/dotnet/api/microsoft.odata.odatapreferenceheader.maxpagesize?view=odata-core-7.0&preserve-view=true). @@ -792,7 +774,6 @@ If the dataset exceeds the limit of 1000 records, the query will immediately fai - [✔️ CONSIDER structuring your query to match the OData evaluation order](#style-match-order) - [✔️ CONSIDER reviewing OData capabilities described in the metadata annotations](#style-metadata) - ### ✔️ DO use `$count` virtual property in the aggregation methods @@ -850,7 +831,7 @@ If you want to add `filter` to your query, you have two options. You can either Despite the expectation one might have, OData clearly defines an order of the evaluation. Also, the `$apply` clause has priority over `$filter`. For this reason, you should choose one or another but avoid these two filter options in a single query. It's important if the queries are generated automatically. -For example, the following query first filters work items by `StoryPoint gt 5`, aggregates results by are path and finally filters the result by `StoryPoints gt 2`. With this evaluation order, the query will always return an empty set. +For example, the following query first filters work items by `StoryPoint gt 5`, aggregates results by are path and finally filters the result by `StoryPoints gt 2`. With this evaluation order, the query always returns an empty set. > [!div class="tabbedCodeSnippets"] > ```OData @@ -878,7 +859,6 @@ Because mixing `$apply` and `filter` clauses in a single query can lead to poten 6. `$skip` 7. `$top` - ### ✔️ CONSIDER reviewing OData capabilities described in the metadata annotations @@ -917,8 +897,6 @@ Another useful annotation is `Org.OData.Capabilities.V1.ExpandRestrictions`, whi > > ``` - - ## Related articles - [Construct OData queries for Analytics](../analytics/analytics-query-parts.md) diff --git a/docs/report/extend-analytics/odata-supported-features.md b/docs/report/extend-analytics/odata-supported-features.md index 558073a882e..707b2e78113 100644 --- a/docs/report/extend-analytics/odata-supported-features.md +++ b/docs/report/extend-analytics/odata-supported-features.md @@ -8,20 +8,19 @@ ms.reviewer: desalg ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 09/30/2020 --- - # Supported OData functions and clauses [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -This article covers how Analytics supports several OData functions. Unsupported functions are also listed. OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines best practices for building and consuming REST APIs. To learn more, see [OData documentation](/odata/). +This article covers how Analytics supports several OData functions. Unsupported functions are also listed. OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines best practices for building and consuming REST APIs. For more information, see [OData documentation](/odata/). [!INCLUDE [temp](../includes/analytics-preview.md)] - + ## Supported clauses @@ -35,7 +34,6 @@ This article covers how Analytics supports several OData functions. Unsupported - ```$skip``` - ```$top``` - When multiple clauses are used in a query, they're applied in the order specified above. The order of clauses in the query string is ignored. For example, in the following query, work items are first grouped and aggregated. Next, the groups are filtered. After that, the filtered groups are sorted. Finally, the first five records are returned. The query returns the top five work item types used at least 100 times. ``` @@ -43,8 +41,7 @@ WorkItems?$filter=Count ge 100&$apply=groupby((WorkItemType), aggregate($count a ``` - - + ### Aggregation extensions support @@ -95,7 +92,6 @@ For more information, see [Aggregate work tracking data](aggregated-data-analyti | [```maxdatetime```](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc444868709) | Returns the latest possible point in time as a DateTimeOffset value. | | [```mindatetime```](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc371341795) | Returns the earliest possible point in time as a DateTimeOffset value. | - OData functions are used in a ```$filter``` clause, but not in a ```$select``` clause the way they would be uses in a SQL statement. For example, you can specify: @@ -108,7 +104,7 @@ However, you can't enter the following string: /WorkItems?$select=WorkItemId,State,toupper(Title) ``` - + ## Unsupported features @@ -126,7 +122,6 @@ However, you can't enter the following string: - ```topsum``` - ```toppercent``` - ## Related articles - [Query your work tracking data](wit-analytics.md) diff --git a/docs/report/extend-analytics/querying-for-trend-data.md b/docs/report/extend-analytics/querying-for-trend-data.md index 6cf81d704a6..a17ed4a4851 100644 --- a/docs/report/extend-analytics/querying-for-trend-data.md +++ b/docs/report/extend-analytics/querying-for-trend-data.md @@ -7,8 +7,8 @@ ms.assetid: FEF88D72-32D7-4DE8-B11E-BCB1A491C3FC ms.author: chcomley author: chcomley ms.topic: tutorial -monikerRange: '>= azure-devops-2019' -ms.date: 09/30/2020 +monikerRange: "<=azure-devops" +ms.date: 02/12/2025 --- # Query trend data @@ -21,20 +21,14 @@ Examining trends in data and making period-over-period comparisons are important Trend data is exposed in the WorkItemSnapshot and WorkItemBoardSnapshot entity sets. They're constructed so every work item, from the day it was created until today, exists for each day. For an organization with only one work item that was created a year ago, there are 365 rows in this entity. For large projects, these entities would be impractical to use with client tools. -What is the solution? Use the [Aggregation Extensions](aggregated-data-analytics.md). - -In this article you'll learn: - -> [!div class="checklist"] -> * How to construct a basic query for trend data +What is the solution? Use the [Aggregation extensions](aggregated-data-analytics.md). Using the OData Aggregation Extensions, you can return aggregated data from Azure DevOps that is conducive to reporting. For example, you could show bug trend for the month of March. Bug trends are a common and critical part of managing any project so you can put it to good use immediately. -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" > [!NOTE] -> The examples shown in this document are based on a Azure DevOps Services URL, you will need to substitute in your Azure DevOps Server URL. - +> The examples shown in this document are based on an Azure DevOps Services URL. Substitute your Azure DevOps Server URL as needed. > [!div class="tabbedCodeSnippets"] > ```OData @@ -43,15 +37,17 @@ Using the OData Aggregation Extensions, you can return aggregated data from Azur ::: moniker-end +## Prerequisites +[!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] - + ## Construct a basic query for trend data -There are some basic requirements you need to effectively query the WorkItemSnapshot table: +To effectively query the WorkItemSnapshot table, follow these basic requirements: * Filter the data by date. -* The aggregation should group by, at the least, date. If not, response will have warning. +* Group the aggregation by at least the date. If not, the response includes a warning. The query to create a bug trend report looks like the following example: @@ -66,7 +62,6 @@ The query to create a bug trend report looks like the following example: It returns a result similar to the following example: - > [!div class="tabbedCodeSnippets"] > ```JSON > { @@ -88,12 +83,12 @@ It returns a result similar to the following example: > } > ``` -This query will produce at most `31 * (number of bug states)`. The default bug has three states: +This query produces at most `31 * (number of bug states)`. The default bug has three states: - Active - Resolved - Closed - At most, this query will return 93 rows no matter how many thousands of records actually exist. It provides a much more compact form of returning data. + At most, this query returns 93 rows no matter how many thousands of records actually exist. It provides a much more compact form of returning data. Let's look at a variation on this example. You want to see the bug trend for an iteration or a release that starts with one iteration and ends with another. @@ -135,8 +130,8 @@ It returns a result similar to the following example: In this query, there are two key differences. We added a filter clause to filter the data to a specific iteration and the dates are now being compared to the iteration start and end dates versus a hard-coded date. -> [!NOTE] -> If aggregation is not used in your query on snapshot tables, you will see the warning "The specified query does not include a $select or $apply clause which is recommended for all queries." in the response. +> [!NOTE] +> If your query on snapshot tables doesn't use aggregation, the response displays the warning: "The specified query doesn't include a `$select` or `$apply` clause which is recommended for all queries." ## Related articles diff --git a/docs/report/extend-analytics/quick-ref.md b/docs/report/extend-analytics/quick-ref.md index 7563c4e0c5c..83551745a61 100644 --- a/docs/report/extend-analytics/quick-ref.md +++ b/docs/report/extend-analytics/quick-ref.md @@ -7,7 +7,7 @@ ms.reviewer: desalg ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 08/12/2022 --- @@ -28,8 +28,7 @@ If you're new to Analytics, we recommend that you review the following articles. - [Summary of best practices to use when querying Analytics](../analytics/analytics-best-practices.md) - [Permissions and prerequisites for working with Analytics](../analytics/analytics-permissions-prerequisites.md) - -[!INCLUDE [temp](../../includes/version-selector-minimize.md)] +[!INCLUDE [temp](../../includes/version-selector.md)] Analytics supports several widgets and built-in reports. In addition, we've created several sample reports to showcase how to query the data and build the reports of interest using Power BI. @@ -80,7 +79,6 @@ Analytics supports several widgets and built-in reports. In addition, we've crea - [Test duration trend](../powerbi/sample-test-analyics-test-duration-trend.md) - [Pass rate trend of a test](../powerbi/sample-test-analytics-pass-rate-trend-test.md) - ## Azure Test Plans sample widgets and reports - **Widgets and built-in reports** @@ -160,7 +158,6 @@ Analytics supports several widgets and built-in reports. In addition, we've crea :::column-end::: :::row-end::: - ## Tasks :::row::: @@ -214,7 +211,6 @@ Analytics supports several widgets and built-in reports. In addition, we've crea :::column-end::: :::row-end::: - ## Metadata reference ::: moniker range=">= azure-devops-2020" @@ -225,14 +221,6 @@ Analytics supports several widgets and built-in reports. In addition, we've crea - [Test Plans](../analytics/entity-reference-test-plans.md) ::: moniker-end - -::: moniker range="azure-devops-2019" - -- [Calendar date, Project, and User](../analytics/entity-reference-general.md) -- [Azure Boards](../analytics/entity-reference-boards.md) - -::: moniker-end - ## Data model reference and troubleshooting - [Analytics views dataset design](../powerbi/data-connector-dataset.md) - [Supported OData functions and clauses](odata-supported-features.md) @@ -246,11 +234,9 @@ Analytics supports several widgets and built-in reports. In addition, we've crea - [WIQL to OData](https://marketplace.visualstudio.com/items?itemName=ms-eswm.wiql-to-odata) - [OData for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=stansw.vscode-odata) - ## Related articles - [Power BI](../powerbi/overview.md) - [Dashboards, charts, reports, & widgets](../dashboards/overview.md) - [OData Extension for Data Aggregation Version 4.0](https://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/cs01/odata-data-aggregation-ext-v4.0-cs01.html) - diff --git a/docs/report/extend-analytics/view-odata-query-analytics-report.md b/docs/report/extend-analytics/view-odata-query-analytics-report.md index b6703af5082..122651d2e9d 100644 --- a/docs/report/extend-analytics/view-odata-query-analytics-report.md +++ b/docs/report/extend-analytics/view-odata-query-analytics-report.md @@ -6,7 +6,7 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: how-to -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 06/15/2022 --- @@ -14,13 +14,15 @@ ms.date: 06/15/2022 [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] - Several built-in Analytics reports and widgets are supported. You can view the OData query used to generate these reports by following the steps outlined in this article. You can then adapt that OData query as needed to generate other reports using Power BI. [!INCLUDE [temp](../includes/analytics-preview.md)] For a list of built-in Analytics reports and widgets, see [About dashboards, charts, reports, & widgets](../dashboards/overview.md) and [Widgets based on Analytics data](../dashboards/analytics-widgets.md). +## Prerequisites + +[!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] ## Open the Analytics report @@ -31,7 +33,6 @@ Open the report of interest. For details, choose one of the links provided below |- [Cumulative Flow Diagram (CFD)](../dashboards/cumulative-flow.md#configure-built-in-cfd)
      - [Sprint burndown](../dashboards/configure-sprint-burndown.md)
      - [Velocity chart](../dashboards/team-velocity.md) |- [Build test results](../../pipelines/test/review-continuous-test-results-after-build.md)
      - [Code coverage](../../pipelines/test/review-code-coverage-results.md)
      - [Release test results](../../pipelines/test/review-continuous-test-results-after-build.md)
      - [Trace test requirements](../../pipelines/test/requirements-traceability.md)
      - [Test analytics](../../pipelines/test/test-analytics.md)
      - [Test failures](../../pipelines/test/test-analytics.md)
      - [Test impact analysis](../../pipelines/test/test-impact-analysis.md)| - ## Open Developer Tools for your browser Press the **F12** key to open the Developer Tools for your browser. Open the **Network** tab and scroll down to find the entry with the OData query. The following table lists the beginning text of entries for select reports. Double-click the entry to open the OData query. @@ -45,8 +46,6 @@ Press the **F12** key to open the Developer Tools for your browser. Open the **N | Sprint Burndown | `BoardLocations?%24apply=filter` | | Velocity | `Iterations?%24filter=Teams` | - - ## Sample OData query, Velocity chart The following syntax represents the OData query for a velocity chart set to show six iterations. diff --git a/docs/report/extend-analytics/wit-analytics.md b/docs/report/extend-analytics/wit-analytics.md index 7c69335f50c..fb99a480148 100644 --- a/docs/report/extend-analytics/wit-analytics.md +++ b/docs/report/extend-analytics/wit-analytics.md @@ -8,7 +8,7 @@ ms.assetid: 0ABC2F7B-AFA5-465F-8DFE-4779D90452CD ms.author: chcomley author: chcomley ms.topic: tutorial -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 01/19/2023 --- @@ -16,7 +16,6 @@ ms.date: 01/19/2023 [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] - Using Analytics for Azure DevOps, you can construct basic and filtered queries to return data of interest. You can run these queries directly in your browser or within Power BI. This article builds off information provided in [Construct OData queries for Analytics](../analytics/analytics-query-parts.md) and [Metadata reference for Azure Boards Analytics](../analytics/entity-reference-boards.md). Also, the queries in this article are focused on retrieving work tracking entity sets, however, the principles apply for querying other entity sets. @@ -38,14 +37,14 @@ In this article you'll learn how to define queries that return the following dat [!INCLUDE [temp](../includes/analytics-preview.md)] +## Prerequisites [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] > [!NOTE] > In this article, the OData query URL is defined for Azure DevOps Services. To construct a similar query for an on-premises server, see the guidance provided in [Construct OData queries for Analytics](../analytics/analytics-query-parts.md). We encourage you to adjust the queries provided for your organization and project to get familiar with querying OData using your browser. - - + ## Return a count of items (no other data) @@ -93,7 +92,6 @@ To learn about the number of items or entities defined in an organization or pro > Count 70 > ``` - ### User count > [!div class="tabbedCodeSnippets"] @@ -105,8 +103,7 @@ To learn about the number of items or entities defined in an organization or pro > Count 16 > ``` - - + ## Return a count of items and data @@ -127,7 +124,7 @@ To return a count of items along with select data for the items, specify the `$c To look up the `AreaSK` or `IterationSK`, or other property of an **Area Path** or **Iteration Path**, use the following queries. - + ### Return the AreaSK for a specific Area Path @@ -152,7 +149,7 @@ The query returns the following data. > } > ``` - + ### Return the IterationSK for a specific Iteration Path @@ -177,7 +174,7 @@ The query returns the following data. > } > ``` - + ## Return specific properties or fields @@ -219,11 +216,10 @@ Analytics returns the following data. > ``` . - + ## Filter your data - To filter an entity set to return select items, specify a `$filter` clause that specifies the criteria the items must meet. Building on the last query, here we add a filter clause to only return *Feature* work item types that are in the *In Progress* state. `/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'` @@ -235,7 +231,6 @@ To filter an entity set to return select items, specify a `$filter` clause that Analytics returns the following data. - > [!div class="tabbedCodeSnippets"] > ```OData > @@ -263,7 +258,6 @@ Analytics returns the following data. > State "In Progress" > ``` - ## Specify several filter clauses You can use `AND` and `OR` to specify several filter clauses. @@ -272,8 +266,7 @@ For example, the following query specifies to return work items of type *User St Additionally, you can apply various functions such as `contains`, `startswith`, `endswith` and more. See the [Supported OData features and clauses, Supported functions](odata-supported-features.md#supported-functions). - - + ## Return data for Identity, Area Path, and Iteration Path fields @@ -285,18 +278,16 @@ The following table provides examples of how to expand several of these properti |-------------|-------------------|-------------------| | DateTime | `DateSK` | `$expand=CreatedDate($select=Date)` or
      `$expand=CreatedDate($select=WeekStartingDate)` | | Identity | `UserSK` | `$expand=AssignedTo($select=UserName)` or
      `$expand=AssignedTo($select=UserEmail)` | -| Area | `AreaSK` | `$expand=AssignedTo($select=AreaName)` or
      `$expand=AssignedTo($select=AreaPath)` | +| Area | `AreaSK` | `$expand=Area($select=AreaName)` or
      `$expand=Area($select=AreaPath)` | | Iteration | `IterationSK` | `$expand=Iteration($select=IterationName)` or
      `$expand=Iteration($select=IterationPath)` or
      `$expand=Iteration($select=StartDate)`| | Project | `ProjectSK` | `$expand=Project($select=ProjectName)` | | Team | `TeamSK` | `$expand=Teams($select=TeamName)` | -To specify several properties that need to be expanded, you specify them in a single expand clause within a comman-delimited list. +To specify several properties that need to be expanded, you specify them in a single expand clause within a comma-delimited list. `$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)` - - - + ## Filter by a navigation property @@ -350,8 +341,7 @@ Here's another example that requests the top five work items under the *Fabrikam > State "To Do" >``` - - + > [!TIP] > You can't use the navigation property directly in a `$select` statement. Instead, you need to use `$expand`. @@ -428,9 +418,7 @@ It then returns the following data. > } > ``` - - - + ## Query a date range @@ -441,7 +429,6 @@ The following example returns work items whose **Changed Date** is greater than > https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z > ``` - The following example returns work items whose **Changed Date** occurs during the week of April 26 through April 30, 2021. > [!div class="tabbedCodeSnippets"] @@ -539,7 +526,7 @@ It returns the following JSON: Notice that the result here shows only the IterationId and IterationPath and that the Project is a nested object within the JSON result. Another key item to note is the URL itself. When using a `$select` statement and an `$expand` clause, you must use a semi-colon (;) before the `$expand`. Anything else will result in an error. - + ## Sort results, `orderby` option @@ -567,12 +554,8 @@ Specify the `$orderby` option to sort your results or specify the sequence in wh - [OData v4.0 specification](https://www.odata.org/documentation/) - [OData v4.0 Part 2: URL Conventions Plus Errata 02](https://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part2-url-conventions/odata-v4.0-errata02-os-part2-url-conventions-complete.html) - - - - \ No newline at end of file +--> diff --git a/docs/report/powerbi/create-quick-report-odataq.md b/docs/report/powerbi/create-quick-report-odataq.md index c3a6c5b043a..9c19b220b7b 100644 --- a/docs/report/powerbi/create-quick-report-odataq.md +++ b/docs/report/powerbi/create-quick-report-odataq.md @@ -5,9 +5,9 @@ description: Learn how to create a trend report using an OData Query. ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.topic: quickstart -ms date: 10/17/2022 +ms date: 09/06/2024 --- # Create a Power BI report with an OData Query @@ -16,85 +16,78 @@ ms date: 10/17/2022 With Power BI Desktop, you can easily start creating reports for your project in Azure DevOps. -If you don't have Power BI Desktop, you can [download](/power-bi/desktop-what-is-desktop) and install it for free. - -Follow the steps to create a report in Power BI desktop that shows a **daily trend of bugs**. - -> [!div class="checklist"] -> * Create a Power BI query -> * Create Power BI transforms -> * Create an Open Bugs trend report - - +If you don't have Power BI Desktop, [download](/power-bi/desktop-what-is-desktop) and install it for free. ## Prerequisites -To create a Power BI report, you must meet the following criteria: - ::: moniker range="azure-devops" -- You must be a member of a project. If you don't have a project yet, create one. See [Sign up for free](../../user-guide/sign-up-invite-teammates.md). -- If you haven't been added as a project member, [get added now](../../organizations/accounts/add-organization-users.md). Anyone with access to the project, except Stakeholders, can view Analytics views. -- Have the **View Analytics** permission set to **Allow**. See [Grant permissions to access Analytics](./analytics-security.md). -- **Boards** must be enabled. To re-enable it, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -- Have installed *Power BI Desktop* *October 2018 Update* or later version. You can download this client application from the official [Power BI Desktop download page](/power-bi/desktop-what-is-desktop). -- Have tracked work items for some period of time on which to generate a trend report. +|Category | Requirements | +|-------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Basic** access. | +| **Permissions** | **View Analytics** permission set to **Allow**. For more information, see [Grant permissions for Analytics access](./analytics-security.md) | +|**Tools** | - [Azure Boards enabled](../../organizations/settings/set-services.md)
      - [Power BI Desktop](https://powerbi.microsoft.com/desktop) | +|**Tasks**| Monitor work items over a specified period to generate a trend report. | ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" -- You must be a member of a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -- If you haven't been added as a project member, [get added now](../../organizations/security/add-users-team-project.md). Anyone with access to the project, except Stakeholders, can view Analytics views. -- Have [enabled or installed Analytics](../dashboards/analytics-extension.md). You must be an account owner or a member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) to add extensions or enable the service. -- **Boards** must be enabled. To re-enable it, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -- Have the **View Analytics** permission set to **Allow**. See [Grant permissions to access Analytics](./analytics-security.md). -- Have installed *Power BI Desktop* *October 2018 Update* or later version. You can download this client application from the official [Power BI Desktop download page](/power-bi/desktop-what-is-desktop). -- Have tracked work items for some period of time on which to generate a trend report. +|Category | Requirements | +|-------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Basic** access. | +| **Permissions** | **View Analytics** permission set to **Allow**. For more information, see [Grant permissions for Analytics access](./analytics-security.md) | +|**Tools** | - [Analytics extension](../dashboards/analytics-extension.md). [**Project Collection Administrators**](../../organizations/security/change-organization-collection-level-permissions.md) can add and enable the service.
      - [Power BI Desktop](https://powerbi.microsoft.com/desktop).
      - [Azure Boards turned on](../../organizations/settings/set-services.md) | +|**Tasks**| Monitor work items over a specified period to generate a trend report. | ::: moniker-end - -## Create a Power BI Query +## Create a Power BI query -Create a Power BI Query to pull the data into Power BI as follows: +Create a Power BI query to pull the data into Power BI as follows: 1. Choose **Get Data**, and then **Blank Query**. > [!div class="mx-imgBorder"] - > ![Power BI - Blank Query](media/BlankQuery.png) + > ![Screenshot shows Power BI - Blank Query.](media/BlankQuery.png) 2. From the Power BI Query editor, choose **Advanced Editor**. > [!div class="mx-imgBorder"] - > ![Power BI - Select Advanced Editor](media/AdvancedEditor.png) + > ![Screenshot shows Power BI - Select Advanced Editor.](media/AdvancedEditor.png) 3. The Advanced Editor window opens. > [!div class="mx-imgBorder"] - > ![Power BI - Advanced Editor](media/odatapowerbi-advancededitor.png) + > ![Screenshot shows Power BI - Advanced Editor.](media/odatapowerbi-advancededitor.png) -4. Replace the contents with the following query. +4. Replace the contents with the following query: ``` let - Source = OData.Feed ("https://analytics.dev.azure.com/{organization}/{project}/_odata/v4.0-preview/WorkItemSnapshot? " - $apply=filter( - WorkItemType eq 'Bug' - AND StateCategory ne 'Completed' - AND startswith(Area/AreaPath,'{areapath}') - AND DateValue ge {startdate} )/ - groupby((DateValue,State,WorkItemType,Area/AreaPath), aggregate($count as Count)) - &$orderby=DateValue" - ,null, [Implementation="2.0",OmitValues = ODataOmitValues.Nulls,ODataVersion = 4]) - in - Source - ``` - - > [!div class="mx-imgBorder"] - > ![Screenshot of Power BI, Advanced Editor, Pasted Query.](media/odatapowerbi-advancededitor-pasted.png) - -5. Substitute your values within the sample query. + The query you provided has a syntax issue due to the placement of double quotes. Specifically, the `$apply` and `$orderby` parameters should be part of the URL string, but they are not correctly concatenated. Here is the corrected version: + +```markdown +let + Source = OData.Feed ( + "https://analytics.dev.azure.com/{organization}/{project}/_odata/v4.0-preview/WorkItemSnapshot?" + &"$apply=filter(" + &"WorkItemType eq 'Bug' " + &"AND StateCategory ne 'Completed' " + &"AND startswith(Area/AreaPath,'{areapath}') " + &"AND DateValue ge {startdate} )/" + &"groupby((DateValue,State,WorkItemType,Area/AreaPath), aggregate($count as Count))" + &"&$orderby=DateValue", + null, [Implementation="2.0", OmitValues = ODataOmitValues.Nulls, ODataVersion = 4] + ) +in + Source +``` + + > [!div class="mx-imgBorder"] + > ![Screenshot of Power BI, Advanced Editor, Pasted Query.](media/odatapowerbi-advancededitor-pasted.png) + +1. Substitute your values within the sample query. The sample query has strings that you must replace with your values: @@ -106,10 +99,9 @@ Create a Power BI Query to pull the data into Power BI as follows: > [!div class="mx-imgBorder"] > ![Screenshot of Power BI, Advanced Editor, Replaced Strings in Query.](media/odatapowerbi-advancededitor-replaced.png) -6. Choose **Done** to execute the query. - - If you've never connected to your account, Power BI may require you to authenticate. For more information, see [Client authentication options](client-authentication-options.md). +2. Choose **Done** to execute the query. + Power BI might require you to authenticate. For more information, see [Client authentication options](client-authentication-options.md). ## Expand Area, Iteration, AssignedTo columns @@ -123,26 +115,25 @@ After closing the **Advanced Editor** and while remaining in the **Power Query E > ![Screenshot of Power BI transform data, Expand AreaPath column.](media/transform-data/expand-area-path-property.png) > [!NOTE] - > The available properties to select depends on the properties requested to return in the query. If you don't specify any properties, then all properties are available. To learn more about these properties, see the following metadata references: [Areas](../analytics/entity-reference-boards.md#areas), [Iterations](../analytics/entity-reference-boards.md#iterations), and [Users](../analytics/entity-reference-general.md#users). + > The available properties to select depends on the properties requested to return in the query. If you don't specify any properties, then all properties are available. For more information about these properties, see the following metadata references: [Areas](../analytics/entity-reference-boards.md#areas), [Iterations](../analytics/entity-reference-boards.md#iterations), and [Users](../analytics/entity-reference-general.md#users). -1. The table now contains entity field(s). +1. The table now contains entity fields. > [!div class="mx-imgBorder"] > ![Screenshot of expanded Area columns.](media/transform-data/expanded-area-columns.png) -1. Repeat steps 1 through 3 for all fields representing entities that need expanding. These appear with *Record* listed in the table column when unexpanded. - +1. Repeat steps 1 through 3 for all fields representing entities that need to expand. These fields appear with *Record* listed in the table column when unexpanded. ## Rename fields and query, then Close & Apply -When finished, you may choose to rename columns. +When finished, you might choose to rename columns. 1. Right-click a column header and select **Rename...** > [!div class="mx-imgBorder"] > ![Screenshot of Power BI transform data, Rename Columns.](media/transform-data/powerbi-rename-columns.png) -1. You also may want to rename the query from the default **Query1**, to something more meaningful. +1. You also might want to rename the query from the default **Query1**, to something more meaningful. > [!div class="mx-imgBorder"] > ![Screenshot of Power BI transform data, Rename Query.](media/transform-data/powerbi-rename-query.png) @@ -152,27 +143,24 @@ When finished, you may choose to rename columns. > [!div class="mx-imgBorder"] > ![Screenshot of Power BI Power Query Editor, Close & Apply.](media/transform-data/powerbi-close-apply.png) - ## Create the report Power BI shows you the fields you can report on. > [!NOTE] -> The example below assumes that no one renamed any columns. - -:::image type="content" source="media/reports-boards/bug-trends-selections.png" alt-text="Screenshot of Power BI Visualizations and Fields selections for Bug trends report. "::: +> The following example assumes that no one renamed any columns. +> :::image type="content" source="media/reports-boards/bug-trends-selections.png" alt-text="Screenshot of Power BI Visualizations and Fields selections for Bug trends report. "::: For a simple report, do the following steps: 1. Select Power BI Visualization **Line chart**. 1. Add the field "DateValue" to **Axis** - - Right-click "DateValue" and select "DateValue", rather than Date Hierarchy + - Right-click "DateValue" and select "DateValue," rather than Date Hierarchy 1. Add the field "State" to **Legend** 1. Add the field "Count" to **Values** - Right-click WorkItemId field and ensure **Sum** is selected -The example report: - +Example report: :::image type="content" source="media/odatapowerbi-bugtrend-report.png" alt-text="Screenshot of Sample Bug trends line chart report."::: @@ -181,7 +169,6 @@ The example report: > [!div class="nextstepaction"] > [Create an Open bugs report](sample-boards-openbugs.md) - ## Related articles -[!INCLUDE [temp](includes/sample-relatedarticles.md)] \ No newline at end of file +[!INCLUDE [temp](includes/sample-relatedarticles.md)] diff --git a/docs/report/powerbi/create-quick-report.md b/docs/report/powerbi/create-quick-report.md index 54bc2df6069..9ab5886525a 100644 --- a/docs/report/powerbi/create-quick-report.md +++ b/docs/report/powerbi/create-quick-report.md @@ -5,7 +5,7 @@ description: Learn how to create a trend report using an Analytics view. ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.topic: quickstart ms.date: 11/08/2022 --- @@ -33,21 +33,32 @@ Follow these steps to create two reports in Power BI desktop that shows a **dail c. Apply filters to your trend report d. Create a card and apply the **Is Current=True** filter to show current count. +## Prerequisites -[!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] +::: moniker range="azure-devops" +|Category | Requirements | +|-------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Basic** access. | +| **Permissions** | **View Analytics** permission set to **Allow**. For more information, see [Grant permissions for Analytics access](./analytics-security.md) | +|**Tools** | - [Azure Boards enabled](../../organizations/settings/set-services.md)
      - [Power BI Desktop](https://powerbi.microsoft.com/desktop) | +|**Tasks**| Monitor work items over a specified period to generate a trend report. | -### Power BI prerequisites +::: moniker-end -To create a Power BI report that references an Analytics view, you must meet the following criteria: +::: moniker range=" < azure-devops" -- Have installed *Power BI Desktop* *October 2018 Update* or later version. You can download this client application from the official [Power BI Desktop download page](/power-bi/desktop-what-is-desktop). -- Have tracked work items for some period of time on which to generate a trend report. +|Category | Requirements | +|-------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Basic** access. | +| **Permissions** | **View Analytics** permission set to **Allow**. For more information, see [Grant permissions for Analytics access](./analytics-security.md) | +|**Tools** | - [Analytics extension](../dashboards/analytics-extension.md). [**Project Collection Administrators**](../../organizations/security/change-organization-collection-level-permissions.md) can add and enable the service.
      - [Power BI Desktop](https://powerbi.microsoft.com/desktop).
      - [Azure Boards turned on](../../organizations/settings/set-services.md) | +|**Tasks**| Monitor work items over a specified period to generate a trend report. | +::: moniker-end [!INCLUDE [temp](../includes/analytics-open.md)] - ## Verify the default Analytics view for your data By verifying the view you'll use in Power BI, your view is more likely to load correctly in Power BI. If verification takes too long, you can quickly adjust the view. Add filters or narrow your history and verify your view again. @@ -69,7 +80,7 @@ By verifying the view you'll use in Power BI, your view is more likely to load c 2. If your view successfully verifies, then go to the next step. If it's unsuccessful, select the **Work Items** tab and adjust the selections to select fewer teams or specify fewer work items in the dataset. - To learn more about defining views, see [Create an Analytics view](analytics-views-create.md). + For more information about defining views, see [Create an Analytics view](analytics-views-create.md). [!INCLUDE [temp](../includes/connect-analytics-view.md)] @@ -95,7 +106,6 @@ By verifying the view you'll use in Power BI, your view is more likely to load c > [!NOTE] > To view trends over time, you want to use the **Date** format and not **Date Hierarchy**. The **Date Hierarchy** in Power BI rolls ups everything into a simple number for the period. The day level in the hierarchy rolls all days to a number between 1-31. For example, April 3 and May 3 both roll up into number 3. This is not the same as counting items per actual date. - ## Group and filter the trend by State - To group your user stories by State, drag the **State** field into the Legend area. Optionally, filter the set of States to show in the chart. @@ -144,7 +154,6 @@ The reports shown in this quickstart illustrate how easy it is to generate repor > [!div class="nextstepaction"] > [Create an Active bugs report](active-bugs-sample-report.md) - ## Related articles - [Get started with Power BI Desktop](/power-bi/fundamentals/desktop-getting-started) diff --git a/docs/report/powerbi/create-team-filter.md b/docs/report/powerbi/create-team-filter.md index d4dd1771ff5..3d6613293f3 100644 --- a/docs/report/powerbi/create-team-filter.md +++ b/docs/report/powerbi/create-team-filter.md @@ -7,7 +7,7 @@ ms.custom: analytics-views ms.author: chcomley author: chcomley ms.topic: sample -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms date: 10/04/2021 --- @@ -22,6 +22,8 @@ However, you can still filter on a team using the steps provided in this article > [!NOTE] > In a similar manner, limitations exist in determining the board-specific column of a work item within an Analytics view. However, the guidance provided in this article won't work for board locations due to the dependency on the selected historical data in the view. +## Prerequisites + [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] ## Add the AreaSK field to your Analytics view @@ -54,7 +56,7 @@ The next step is to add the *Teams* entity to the Power BI data model and genera ```Query let - #"Get table" = VSTS.Feed("https://analytics.dev.azure.com/{OrganizationName}/_odata/v2.0/Teams?$select=TeamName,TeamSK&$filter=TeamName eq '{TeamName1}' or TeamName eq '{TeamName2}"), + #"Get table" = VSTS.Feed("https://analytics.dev.azure.com/{OrganizationName}/_odata/v2.0/Teams?$select=TeamName,TeamSK&$filter=TeamName eq '{TeamName1}' or TeamName eq '{TeamName2}'"), #"Select columns" = Table.SelectColumns(#"Get table", {"TeamName", "TeamSK"}) in #"Select columns" @@ -100,7 +102,6 @@ The next step is to add the *Teams* entity to the Power BI data model and genera 16. Next, choose **Refresh** to add *AreaSK* to the view. - ## Create the Power BI relationship mappings The last step is to create the necessary relationships in Power BI. @@ -117,7 +118,7 @@ The last step is to create the necessary relationships in Power BI. 3. In the Manage Relationships dialog: a. Delete any relationships that might have been automatically detected. - b. Choose **New** to create a bidirectional *Many to One* relationship between your *View* and *Area*. To learn more, see [Bidirectional cross-filtering using DirectQuery in Power BI Desktop](/power-bi/desktop-bidirectional-filtering). + b. Choose **New** to create a bidirectional *Many to One* relationship between your *View* and *Area*. For more information, see [Bidirectional cross-filtering using DirectQuery in Power BI Desktop](/power-bi/desktop-bidirectional-filtering). > [!div class="mx-imgBorder"] > ![Power BI Desktop, Manage Relationships dialog, View To Area](media/ViewToArea.png) diff --git a/docs/report/powerbi/create-timeinstate-report.md b/docs/report/powerbi/create-timeinstate-report.md index 47648cb2845..c9fcc69b9b1 100644 --- a/docs/report/powerbi/create-timeinstate-report.md +++ b/docs/report/powerbi/create-timeinstate-report.md @@ -7,17 +7,17 @@ ms.custom: analytics-views, engagement-fy23 ms.author: chcomley author: chcomley ms.topic: how-to -monikerRange: '>= azure-devops-2019' -ms date: 02/08/2023 +monikerRange: "<=azure-devops" +ms date: 09/16/2024 --- # Add a time-in-state measure to your Power BI report [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -The time a work item spends in a specific workflow state or series of states is an important aspect for understanding efficiency. The [Cycle Time and Lead Time](../dashboards/cycle-time-and-lead-time.md) Analytics widgets provide some measures of time-in-state. However, these widgets may not have the level of detail that you want. +The time a work item spends in a specific workflow state or series of states is an important aspect for understanding efficiency. The [Cycle Time and Lead Time](../dashboards/cycle-time-and-lead-time.md) Analytics widgets provide some measures of time-in-state. However, these widgets might not have the level of detail that you want. -This article provides recipes using DAX calculations to evaluate time spent by work items in a combination of states. Specifically, you learn how to add the following measure and calculated columns to your Power BI reports and use them to generate various trend charts. All fields are calculated columns except the first one listed. +This article provides recipes using Data Analysis Expressions (DAX) to evaluate time spent by work items in a combination of states. Specifically, you learn how to add the following measure and calculated columns to your Power BI reports and use them to generate various trend charts. All fields are calculated columns except the first one listed. |Count| Description | |-----|-------------| @@ -31,6 +31,7 @@ This article provides recipes using DAX calculations to evaluate time spent by w | *State Changed* | Adds a column that determines the date when a work item transitioned from one **State** to another | | *State Flow* | Adds a column that illustrates the state flow as a work item transitions from one **State** to another | | *State Change Count* | Adds a column that calculates the number of times a work item transitioned from one **State** to another | +| *State Change Count - First Completed* | Adds a column that determines the number of times a work item transitions to the Completed state for the first time. In other words, when it moves from any other state to the Completed state. | | *State Change Count - Last Proposed* | Adds a column that determines if a work item was in a Proposed state previously after it transitioned to a later **State** | | *State Restart Time in Days* | Adds a column that calculates the days a work item spent in a restart state | | *State Rework Time in Days* | Adds a column that calculates the days a work item spends in a state other than *Completed* | @@ -42,7 +43,10 @@ This article provides recipes using DAX calculations to evaluate time spent by w > * All intra-day or intra-period (weekly/monthly) revisions are ignored by the calculations. This can result in unexpected results for specific scenarios like a work item showing no time "In Progress" when a work item is "In Progress" for less than a day. > * Power BI default aggregations are used whenever possible instead of building measures. > * Some calculations include **+0** to ensure that a numeric value is included for every row instead of BLANK. -> You may need to revise some of the calculated column definitions based on the workflow states used by your project. For example, if your project uses *New*, *Active*, and *Closed* in place of *Proposed*, *In Progress*, and *Completed*. +> * You might need to revise some of the calculated column definitions based on the workflow states used by your project. For example, if your project uses *New*, *Active*, and *Closed* in place of *Proposed*, *In Progress*, and *Completed*. +> * The **Date** column referred to in this article isn't a native column in Azure DevOps; It's a derived column created within PowerBI to facilitate the **Time in State** report. You can build this column using the existing date-related columns, such as "Changed Date" or "State Changed Date." + +## Prerequisites [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] @@ -82,13 +86,13 @@ Compare the *Work Items Count* measure with the default count aggregation based :::image type="content" source="media/measure/work-item-count-measure-vs-id.png" alt-text="Screenshot of Power BI report page, two cards showing Work Item Count measure and Work Item ID property."::: -To get the correct count using a default aggregation, you apply the filter *Is Current* equals 'True'. This pattern of applying filters to a default aggregation is the basis for many of the examples provided in this article. +To get the correct count using a default aggregation, you apply the filter *Is Current* equals 'True.' This pattern of applying filters to a default aggregation is the basis for many of the examples provided in this article. -:::image type="content" source="media/measure/work-item-id-count-is-current.png" alt-text="Screenshot of Power BI report page, Work Item ID*count filtered with Is Current=True."::: +:::image type="content" source="media/measure/work-item-id-count-is-current.png" alt-text="Screenshot of Power BI report page, work item ID count filtered."::: ## Add State Sort Order -By default, Power BI shows states sorted alphabetically in a visualization. It can be misleading when you want to visualize time in state and *Proposed* shows up after *In Progress*. The following steps help to resolve this issue. +By default, Power BI shows states sorted alphabetically in a visualization. It can be misleading when you want to visualize time in state and *Proposed* shows up after *In Progress*. The following steps help to resolve this issue. 1. Verify that the *State Category* field is included in the Analytics view. This field is included in all default shared views. @@ -122,7 +126,7 @@ By default, Power BI shows states sorted alphabetically in a visualization. It c :::image type="content" source="media/measure/column-sort-order-select.png" alt-text="Screenshot of Power BI Column tools tab, Sort by column selection."::: - + ## Add Date Previous @@ -151,14 +155,14 @@ CALCULATE ( ) ``` -The **Date Previous** calculated column uses three DAX functions, [`MAX`](/dax/max-function-dax), [`ALLEXCEPT`](/dax/allexcept-function-dax), and [`EARLIER`](/dax/earlier-function-dax), described in more detail [later in this article](#dax-functions). Because the column is calculated, it's run for every row in the table, and each time it's run it has the context of that specific row. +The **Date Previous** calculated column uses three DAX functions, [`MAX`](/dax/max-function-dax), [`ALLEXCEPT`](/dax/allexcept-function-dax), and [`EARLIER`](/dax/earlier-function-dax), described in more detail [later in this article](#dax-functions). Because the column is calculated, it runs for every row in the table, and each time it runs, it has the context of that specific row. :::image type="content" source="media/measure/table-report-state-date-date-previous.png" alt-text="Screenshot of Power BI table chart and Visualization tab for Date and Date Previous."::: > [!TIP] > From the context menu for the *Date* and *Previous Date* fields, choose **Date** (instead of **Date Hierarchy**) to see a single date for these fields. - + ## Add Date Diff in Days @@ -206,7 +210,7 @@ From the **Modeling** tab, choose **New Column** and then replace the default te ## Add State Time in Days -The time that a work item spent in a specific state can now be calculated by summing the *Date Diff in Days* for each work item. This calculation includes all of the time spent in a specific state even if it has switched between states multiple times. It's possible to evaluate each row as a trend using *Date* or the latest information by using *Is Last Day In State*. +The time that a work item spent in a specific state can now be calculated by summing the *Date Diff in Days* for each work item. This calculation includes all of the time spent in a specific state even if it switched between states multiple times. It's possible to evaluate each row as a trend using *Date* or the latest information by using *Is Last Day In State*. > [!IMPORTANT] > Requires that you have added the *Date Diff in Days* and *Is Last Day in State* calculated columns to the table. @@ -234,21 +238,20 @@ The second chart illustrates the trend of average days the active work items are :::image type="content" source="media/measure/stacked-column-chart-average-time-in-days.png" alt-text="Screenshot of Power BI stacked column chart and Visualization tab that illustrates the average days in state for work items by date."::: - ### Add State Time in Days - Latest (Is Last Day In State) -When evaluating time-in-state for each work item in a table or when filtered by a field like *Area Path*, don't use the *State Time in Days* column in an aggregation. The aggregation uses the value for every day the work item was in the state. For example, if a work item was *In Progress* on Monday and moved to *Completed* on Thursday, the time-in-state is three days, but the sum of *State Time in Days* column is six days (1+2+3) which is clearly incorrect. +When evaluating time-in-state for each work item in a table or when filtered by a field like *Area Path*, don't use the *State Time in Days* column in an aggregation. The aggregation uses the value for every day the work item was in the state. For example, if a work item was *In Progress* on Monday and moved to *Completed* on Thursday, the time-in-state is three days, but the sum of *State Time in Days* column is six days, `1+2+3`, which is incorrect. > [!div class="mx-imgBorder"] > ![Add State Time in Days - Latest.](media/StateTimeInDaysTable.png) -To resolve this issue, use *State Time in Days* and apply the filter *Is Last Day In State* equals 'True'. It eliminates all the historical data necessary for a trend and focuses instead on just the latest value for each state. +To resolve this issue, use *State Time in Days* and apply the filter *Is Last Day In State* equals 'True.' It eliminates all the historical data necessary for a trend and focuses instead on just the latest value for each state. :::image type="content" source="media/StateTimeInDaysTableIsLast.png" alt-text="Use State Time in Days and apply the filter Is Last Day In State equals 'True'."::: ### Add State Time in Days - In Progress -In the examples above, *State Time in Days* for a given work item is only counted when the work item was in that specific state. If your goal is to have the time-in-state for a given work item count towards an average continuously, you must change the calculation. For example, if we want to track the "In Progress" state, we add the *State Time in Days - In Progress* calculated column. +In the previous examples, *State Time in Days* for a given work item is only counted when the work item was in that specific state. If your goal is to have the time-in-state for a given work item count towards an average continuously, you must change the calculation. For example, if we want to track the "In Progress" state, we add the *State Time in Days - In Progress* calculated column. From the **Modeling** tab, choose **New Column** and then replace the default text with the following code and select the :::image type="icon" source="media/checkmark.png" border="false"::: checkmark. @@ -270,7 +273,6 @@ The following image shows the effect of considering all time-in-state for every :::image type="content" source="media/TimeInStateActive.png" alt-text="Trend Comparison of the Average Time in State"::: - ### State Time in Days trend of multiple states Analyzing performance across multiple states is also possible using the "Continuous" pattern. However, this approach only works with a trend chart. @@ -291,7 +293,6 @@ From the **Modeling** tab, choose **New Column** and then replace the default te > [!NOTE] > You may need to revise the definition based on the workflow states used by your project. For example, if your project uses 'Active' in place of 'Committed' or 'Proposed'. - The chart of the left shows combined average while the right-hand side shows each individual state. > [!div class="mx-imgBorder"] @@ -299,7 +300,7 @@ The chart of the left shows combined average while the right-hand side shows eac ## Get the State Time in Days- Latest for multiple states -You use the *State Time in Days- Latest* calculated column when creating a trend. Using a filter on the states, the *State Time in Days* column and *Is Last Day in State* provides a simple way to get the total time any work item or group of work items spent in a set of states. +You use the *State Time in Days- Latest* calculated column when creating a trend. With a filter on the states, the *State Time in Days* column and *Is Last Day in State* provides a simple way to get the total time any work item or group of work items spent in a set of states. > [!div class="mx-imgBorder"] > ![Latest Time in States](media/CombinedTimeInState.png) @@ -331,13 +332,13 @@ The next parameter, `'View Name'[Work Item Id], 'View Name'[Work Item Id]`, spec And, the last parameter, `'View Name'[Date], 'View Name'[Date Previous]`, specifies that the date of the row being returned must have a [Date] that matches the [Previous Date] of the current row. In a snapshot, only one row can meet this criteria. - - + + ## Add State Changed Using the *State Previous* column, we can flag the rows for each work item where a state transition occurred. The *Stage Changed* calculated column has two special considerations: -* Blank values of *State Previous* which we set to the *Created Date* of the work item +* Blank values of *State Previous, which we set to the *Created Date* of the work item * Creation of a work item is considered a state transition > [!IMPORTANT] @@ -357,8 +358,7 @@ From the **Modeling** tab, choose **New Column** and then replace the default te The calculated column is a boolean value that identifies whether the row is a state transition. By using the `Not Equal To` operator, you correctly catch rows where the previous state doesn't match the current state, which means the comparison returns True as expected. - - + ## Add State Flow @@ -397,13 +397,12 @@ From the **Modeling** tab, choose **New Column** and then replace the default te ## Add State Change Count - Last Proposed and State Restart Time in Days -Calculating restarts, *State Restart Time in Days*, is a fairly complex calculation. The first step is to find the last time a work item was in a proposed state. Add the *State Change Count - Last Proposed* calculated column. - +*State Restart Time in Days* is a fairly complex calculation. The first step is to find the last time a work item was in a proposed state. Add the *State Change Count - Last Proposed* calculated column. > [!NOTE] -> You may need to revise the following definitions based on the workflow states used by your project. For example, if your project uses 'New' in place of 'Proposed'. +> You might need to revise the following definitions based on the workflow states used by your project. For example, if your project uses 'New' in place of 'Proposed'. -From the **Modeling** tab, choose **New Column** and then replace the default text with the following code and select the :::image type="icon" source="media/checkmark.png" border="false"::: checkmark. +From the **Modeling** tab, choose **New column** and then replace the default text with the following code and select the :::image type="icon" source="media/checkmark.png" border="false"::: checkmark. > [!div class="tabbedCodeSnippets"] > ```DAX @@ -434,34 +433,48 @@ From the **Modeling** tab, choose **New Column** and then replace the default te Since the **State Restart Time in Days** is updated for each row of data, you can either create a trend to evaluate rework across specific sprints or examine rework for individual work items by using **Is Current**. - ## Add State Rework Time in Days -Similar to *State Restart Time in Days*, the *State Rework Time in Days* looks for the first time a work item was in the **Completed** state category. After that time, each day a work item spends in a state other than Completed, counts as rework. - -From the **Modeling** tab, choose **New Column** and then replace the default text with the following code and select the :::image type="icon" source="media/checkmark.png" border="false"::: checkmark. - -> [!div class="tabbedCodeSnippets"] -> ```DAX -> State Rework Time in Days = -> IF ( -> ISBLANK ( 'View Name'[State Change Count - First Completed] ), -> 0, -> CALCULATE ( -> SUM ( 'View Name'[Date Diff in Days] ), -> ALLEXCEPT ( 'View Name', 'View Name'[Work Item Id] ), -> 'View Name'[Date] <= EARLIER ( 'View Name'[Date] ), -> 'View Name'[State Change Count] EARLIER ( 'View Name'[State Change Count - First Completed] ), -> 'View Name'[State] IN {"Completed", "Closed", "Cut" } = FALSE() -> ) + 0 -> ) -> ``` -> -> [!NOTE] -> You may need to revise the above definition based on the workflow states used by your project. For example, if your project uses *Done* in place of *Closed*. - - - +Similar to *State Restart Time in Days*, the *State Rework Time in Days* looks for the first time a work item was in the Completed state category. After that time, each day a work item spends in a state other than Completed, counts as rework. + +1. Create the "State Change Count - First Completed" column. This column tracks the number of times a work item transitions to the Completed state from any other state. + + > [!div class="tabbedCodeSnippets"] + > ```DAX + > State Change Count - First Completed = + > VAR CompletedState = "Completed" + > RETURN + > CALCULATE( + > COUNTROWS('YourTable'), + > FILTER( + > 'YourTable', + > 'YourTable'[State] = CompletedState + > && 'YourTable'[State Change Date] = MIN('YourTable'[State Change Date]) + > ) + > ) + +2. From the **Modeling** tab, choose **New Column** and then replace the default text with the following code and select the :::image type="icon" source="media/checkmark.png" border="false"::: checkmark. + + > [!div class="tabbedCodeSnippets"] + > ```DAX + > State Rework Time in Days = + > IF ( + > ISBLANK ( 'View Name'[State Change Count - First Completed] ), + > 0, + > CALCULATE ( + > SUM ( 'View Name'[Date Diff in Days] ), + > ALLEXCEPT ( 'View Name', 'View Name'[Work Item Id] ), + > 'View Name'[Date] <= EARLIER ( 'View Name'[Date] ), + > 'View Name'[State Change Count] <= EARLIER ( 'View Name'[State Change Count - First Completed] ), + > 'View Name'[State] IN {"Completed", "Closed", "Cut" } = FALSE() + > ) + 0 + > ) + > ``` + > + > [!NOTE] + > You might need to revise the previous definition based on the workflow states used by your project. For example, if your project uses *Done* in place of *Closed*, and so on. + + ## DAX functions @@ -469,22 +482,21 @@ Additional information is provided in this section for the DAX functions used to |Function| Description | |-----|-------------| -| [`ALLEXCEPT`](/dax/allexcept-function-dax) | Removes all context filters in the table except filters that have been applied to the specified columns. Essentially, `ALLEXCEPT ('View Name'', 'View Name'[Work Item Id])` reduces the rows in the table down to only the ones that share the same work item ID as the current row. | +| [`ALLEXCEPT`](/dax/allexcept-function-dax) | Removes all context filters in the table except filters applied to the specified columns. Essentially, `ALLEXCEPT ('View Name'', 'View Name'[Work Item Id])` reduces the rows in the table down to only the ones that share the same work item ID as the current row. | | [`CALCULATE`](/dax/calculate-function-dax) | This function is the basis for nearly all examples. The basic structure is an expression followed by a series of filters that are applied to the expression. | | [`COUNTROWS`](/dax/countrows-function-dax) | This function, `COUNTROWS ( 'View Name' )`, simply counts the number of rows that remain after the filters are applied. | | [`DATEDIFF`](/dax/datediff-function-dax) | Returns the count of interval boundaries crossed between two dates. `DATEDIFF` subtracts *Date Previous* from *Date* to determine the number of days between them.| -| [`EARLIER`](/dax/earlier-function-dax) | Returns the current value of the specified column in an outer evaluation pass of the mentioned column. For example, `'View Name'[Date] < EARLIER ( 'View Name'[Date] )`, further reduces the data set to only those rows that occurred before the date for the current row that is referenced by using the `EARLIER` function. `EARLIER` doesn't refer to previous dates, it specifically defines the row context of the calculated column. | +| [`EARLIER`](/dax/earlier-function-dax) | Returns the current value of the specified column in an outer evaluation pass of the mentioned column. For example, `'View Name'[Date] < EARLIER ( 'View Name'[Date] )` further reduces the data set to only those rows that occurred before the date for the current row that is referenced by using the `EARLIER` function. `EARLIER` doesn't refer to previous dates; it specifically defines the row context of the calculated column. | | [`ISBLANK`](/dax/isblank-function-dax) | Checks whether a value is blank, and returns TRUE or FALSE. `ISBLANK` evaluates the current row to determine if *Date Previous* has a value. If it doesn't, the If statement sets *Date Diff in Days* to 1.| | [`LASTDATE`](/dax/lastdate-function-dax) | We apply the `LASTDATE` filter to an expression, for example `LASTDATE ( 'View Name'[Date] )`, to find the newest date across all rows in the table and eliminate the rows that don't share the same date. With the snapshot table generated by an Analytics view, this filter effectively picks the last day of the selected period. | | [`LOOKUPVALUE`](/dax/lookupvalue-function-dax) | Returns the value in *result_columnName* for the row that meets all criteria specified by *search_columnName* and *search_value*. | -| [`MAX`](/dax/max-function-dax) | Returns the largest numeric value in a column, or between two scalar expressions. We apply `MAX ( 'View Name'[Date] )`, to determine the most recent date after all filters have been applied. | - +| [`MAX`](/dax/max-function-dax) | Returns the largest numeric value in a column, or between two scalar expressions. We apply `MAX ( 'View Name'[Date] )`, to determine the most recent date after all filters are applied. | ## Related articles -- [Power BI integration overview](overview.md) +- [Learn about Power BI integration](overview.md) - [Create Analytics views](analytics-views-create.md) - [Get started with Power BI Desktop](/power-bi/fundamentals/desktop-getting-started) -- [Dataset design for the Power BI Connector](data-connector-dataset.md) -- [Workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md) -- [Data model for Analytics](../extend-analytics/data-model-analytics-service.md) \ No newline at end of file +- [Design datasets for the Power BI Connector](data-connector-dataset.md) +- [Understand workflow states and state categories](../../boards/work-items/workflow-and-state-categories.md) +- [Explore the data model for Analytics](../extend-analytics/data-model-analytics-service.md) diff --git a/docs/report/powerbi/data-available-in-analytics.md b/docs/report/powerbi/data-available-in-analytics.md index cf61e0f0b87..da2e455e30c 100644 --- a/docs/report/powerbi/data-available-in-analytics.md +++ b/docs/report/powerbi/data-available-in-analytics.md @@ -6,7 +6,7 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 08/12/2022 --- @@ -16,21 +16,20 @@ ms.date: 08/12/2022 The data available to you from Analytics depends on the Azure DevOps platform and version you're using and the Analytics version you query. -::: moniker range=">= azure-devops-2019 < azure-devops-2022" +::: moniker range=" [!NOTE] -> For Azure DevOps Server, you can use Analytics in place of SQL Server Reporting Services or along side it. However, if you plan to use the Inheritance process model to customize work tracking, you can only use Analytics for reporting, the project collection must not be configured to support reporting. To learn more about the Inheritance process model, see [About process customization and inherited processes](../../organizations/settings/work/inheritance-process-model.md). +> For Azure DevOps Server, you can use Analytics in place of SQL Server Reporting Services or along side it. However, if you plan to use the Inheritance process model to customize work tracking, you can only use Analytics for reporting, the project collection must not be configured to support reporting. For more information about the Inheritance process model, see [About process customization and inherited processes](../../organizations/settings/work/inheritance-process-model.md). ::: moniker-end ## Data available by platform version -Refer to the following table to determine the data you have access to. To determine the platform and version you're using, see [Get support and provide feedback, What platform am I using?](../../user-guide/provide-feedback.md#what-platformversion-am-i-using) +Refer to the following table to determine the data you have access to. To determine the platform and version you're using, see [Get support and provide feedback, What platform am I using?](../../user-guide/provide-feedback.md) > [!NOTE] > The following table was last updated on August 2022. - |**Service**|**Azure DevOps Services**
      **Azure DevOps Server 2020**
      **Azure DevOps Server 2022** |**Azure DevOps Server 2019**|**Future availability**| |------------------|----------------|---------------------------|----------------| |[Boards](https://azure.microsoft.com/services/devops/boards/) | [In-context reports](../dashboards/overview.md#in-context-reports-work-tracking)
      [Widgets](../dashboards/analytics-widgets.md)
      [OData](../extend-analytics/quick-ref.md)
      [Power BI](overview.md) | [Widgets](../dashboards/analytics-widgets.md)
      [OData](../extend-analytics/quick-ref.md)
      [Power BI](overview.md) | | diff --git a/docs/report/powerbi/data-connector-connect.md b/docs/report/powerbi/data-connector-connect.md index 675ed1bc6f6..30d17d4dab4 100644 --- a/docs/report/powerbi/data-connector-connect.md +++ b/docs/report/powerbi/data-connector-connect.md @@ -1,152 +1,124 @@ --- title: Connect to Power BI Data Connector titleSuffix: Azure DevOps -description: Learn how to connect to Power BI Data Connector and Analytics to access Azure DevOps data. +description: Learn how to connect to Power BI Data Connector and Analytics to access Azure DevOps data. You can extract valuable insights and create compelling reports. ms.assetid: 509ECCF2-E18E-4F14-B7EE-8802AB8938A2 ms.subservice: azure-devops-analytics +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: how-to -monikerRange: '>= azure-devops-2019' -ms date: 10/04/2021 +monikerRange: "<=azure-devops" +ms date: 03/12/2025 +#customer intent: As a team member or administrator, I want to connect to Azure DevOps Analytics with Power BI to create reports. --- -# Connect to Analytics with Power BI Data Connector +# Connect Analytics with Power BI Data Connector [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] +In this article, learn how to establish a seamless connection between Power BI and Azure DevOps by using Data Connector. This integration allows you to extract valuable insights from your Azure DevOps data and create compelling reports within Power BI. Power BI Data Connector uses [Analytics views](what-are-analytics-views.md). - -The Power BI Data Connector uses [Analytics views](what-are-analytics-views.md). - -[!INCLUDE [temp](includes/analytics-views-warning.md)] +[!INCLUDE [analytics note](includes/analytics-views-warning.md)] ## Prerequisites -Follow the steps below to get started using the Azure DevOps Power BI Data Connector: - ::: moniker range="azure-devops" -- If you aren't familiar with Analytics, read "[what is Analytics](what-is-analytics.md)" before continuing. -- Install the *Power BI Desktop* *October 2018 Update* or a newer version. You can download it from the official [Power BI Desktop download page](/power-bi/desktop-what-is-desktop). -- If you haven't been added as a project member, [get added now](../../organizations/security/add-users-team-project.md). Anyone with access to the project, except stakeholders, can view Analytics views. -- **Boards** must be enabled. If it's disabled, **Analytics views** won't be displayed. To re-enable **Boards**, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -- Make sure you have [permissions required to access Analytics](analytics-security.md). If you're a member of the project Contributors group, you have permission. -- [Create an Analytics view](analytics-views-create.md) that you want to create a Power BI report. -- Review the [knowledge base of Power BI articles](/power-bi). +|Category | Requirements | +|-------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Basic** access. | +| **Permissions** | [Analytics permissions](analytics-security.md). If you're a member of the **Contributors** group for the project, you have permission. | +|**Tools** | - [Azure Boards enabled](../../organizations/settings/set-services.md)
      - [Power BI Desktop](https://aka.ms/pbidesktopstore) | +|**Tasks**| - Familiarity with [What is Analytics](what-is-analytics.md) and the [knowledge base of Power BI articles](/power-bi/).
      - [Create an Analytics view](analytics-views-create.md) that you want to create a Power BI report. | ::: moniker-end - ::: moniker range="< azure-devops" -- If you aren't familiar with Analytics, read [what is Analytics?](what-is-analytics.md) before continuing. -- Install the *Power BI Desktop* *October 2018 Update* or a newer version. You can download it from the official [Power BI Desktop download page](/power-bi/desktop-what-is-desktop). -- You must be a member of a project with Basic access or higher. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -- If you haven't been added as a project member, [get added now](../../organizations/security/add-users-team-project.md). Anyone with access to the project, except stakeholders, can view Analytics views. -- [Verify that Analytics](../dashboards/analytics-extension.md?view=azure-devops-2019&preserve-view=true)] is installed, and if not, then enable it. You must be an account owner or a member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) to add extensions or enable the service. -- **Boards** must be enabled. If it's disabled, **Analytics views** won't be displayed. To re-enable **Boards**, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -- Make sure you have [permissions required to access Analytics](analytics-security.md). If you're a member of the project Contributors group, you have permission. -- [Create an Analytics view](analytics-views-create.md) that you want to create a Power BI report. -- Review the [knowledge base of Power BI articles](/power-bi). +|Category | Requirements | +|-------------|-------------| +| **Access levels** | - [Project member](../../organizations/security/add-users-team-project.md).
      - At least **Basic** access. | +| **Permissions** | [Analytics permissions](analytics-security.md). If you're a member of the **Contributors** group for the project, you have permission. | +|**Tools** | - [Analytics installed and enabled](../dashboards/analytics-extension.md?view=azure-devops-2019&preserve-view=true). Account owners or members of the [Project Collection Administrators group](../../organizations/security/change-organization-collection-level-permissions.md) can add extensions or enable the service.
      - [Azure Boards enabled](../../organizations/settings/set-services.md)
      - [Power BI Desktop](https://aka.ms/pbidesktopstore) | +|**Tasks**| - Familiarity with [What is Analytics](what-is-analytics.md) and the [knowledge base of Power BI articles](/power-bi/).
      - [Create an Analytics view](analytics-views-create.md) that you want to create a Power BI report. | ::: moniker-end [!INCLUDE [alt-creds-deprecation-notice](../../includes/alt-creds-deprecation-notice.md)] -[!INCLUDE [temp](../includes/connect-analytics-view.md)] +[!INCLUDE [connect to an analytics view](../includes/connect-analytics-view.md)] -## Create your report +## Create a report -**Create reports based on the loaded data**. After the load operation finishes, you can explore the data by creating custom reports. For examples of common reports, see [Example Reports - using the Data Connector](data-connector-examples.md). +Create a report based on the loaded data. After the load operation finishes, you can explore the data by creating custom reports. For examples of common reports, see [Data Connector - Example reports](data-connector-examples.md). -![Power BI desktop report view](./media/data-connector-visual.png) +:::image type="content" source="media/data-connector-visual.png" alt-text="Screenshot that shows the Power BI Desktop report view." lightbox="media/data-connector-visual.png"::: -## Q & A +## FAQs + +Find answers to common questions about Power BI Data Connector and Analytics error messages. ### Q: How should I read error messages coming from the connector? -**A:** You may feel challenged reading error messages coming from the connector because they typically contain extra contextual information. -If the load operation fails, then the message starts with *Failed to save modifications to the server...*. -When you see it, then search for **[DataSource.Error] Azure DevOps...:**. -The following text is the real error message returned from the connector. - -In the example below, the most important part of the error message is: +**A:** You might feel challenged reading error messages coming from the connector because they typically contain extra contextual information. If the load operation fails, then the message starts with "Failed to save modifications to the server...". When you see it, search for **[DataSource.Error] Azure DevOps...:**. +The following example shows the error message returned from the connector. The most important part of the error message is "Query result exceeds maximum size. Reduce the number of records by applying more filters." -> Query result exceeds maximum size. Please reduce the number of records by applying additional filters. -> -> ![Screenshot showing the QueryExceedsPreferredMaxSize exception.](./media/QueryExceedsPreferredMaxSizeException.png) +:::image type="content" source="media/QueryExceedsPreferredMaxSizeException.png" alt-text="Screenshot that shows the Query result exceeds maximum size error message."::: -### Q: How do I resolve the *Query result exceeds maximum size. Please reduce the number of records by applying additional filters* error? +### Q: How do I resolve the "Query result exceeds maximum size. Reduce the number of records by applying additional filters" error? -**A:** You'll get the following error if the number of records retrieved from Analytics exceeds 250,000. -> Failed to save modifications to the server. Error returned: 'OLE DB or ODBC error: -> [DataSource.Error] VSTS: Request failed: The remote server returned an error: (400) Bad Request. -> (**Query result exceeds maximum size. Please reduce the number of records by applying additional filters**).'. +**A:** You get the following error if the number of records retrieved from Analytics exceeds 250,000: +"Failed to save modifications to the server. Error returned: 'OLE DB or ODBC error: +[DataSource.Error] VSTS: Request failed: The remote server returned an error: (400) Bad Request. +(Query result exceeds maximum size. Reduce the number of records by applying additional filters).'" -This error typically occurs when your project has a large number of work items. The size of the dataset must be reduced by [customizing the view](analytics-views-create.md). Do so before using it in Power BI. +This error typically occurs when your project has a large number of work items. Reduce the size of the dataset by [customizing the view](analytics-views-create.md). Do this step before you use it in Power BI. -![Query result exceeds maximum size. Please reduce the number of records by applying additional filters](media/QueryExceedsPreferredMaxSizeException.png) +:::image type="content" source="media/QueryExceedsPreferredMaxSizeException.png" alt-text="Screenshot that shows the Query result exceeds maximum size error."::: -### Q: How do I resolve the *The user wasn't authorized* error? - -> The user was not authorized. +### Q: How do I resolve the "user wasn't authorized" error? -**A:** You can come across this error if you try to access a project that you don't have permissions to. You'll also see it if your credentials aren't recognized by Power BI. To check your permissions, see [Set permissions to access Analytics and Analytics views](analytics-security.md). If it's a credential problem, you should work with your administrator to see if they can help resolve the problem. To learn more, see [Power BI Security, User Authentication](/power-bi/admin/service-admin-power-bi-security#user-authentication) and [Troubleshooting sign-in issues for Power BI](/power-bi/admin/power-bi-cannot-sign-in). - -> [!div class="mx-imgBorder"] -> ![The user was not authorized.](media/AccessDeniedError.png) - -> [!NOTE] -> Power BI uses Azure Active Directory ([AAD](https://azure.microsoft.com/services/active-directory/)) to authenticate users who sign in to the Power BI service, and in turn, uses the Power BI login credentials whenever a user attempts to access resources that require authentication. Users sign in to the Power BI service using the email address used to establish their Power BI account; Power BI uses that login email as the *effective username*, which is passed to resources whenever a user attempts to connect to data. The *effective username* is then mapped to a [*User Principal Name* (UPN)](/windows/win32/secauthn/user-name-formats) and resolved to the associated Windows domain account, against which authentication is applied. +**A:** You might get this error if you try to access a project that you don't have permissions to. You might also see it if Power BI doesn't recognize your credentials. To check your permissions, see [Set permissions to access Analytics and Analytics views](analytics-security.md). If it's a credential issue, work with your administrator to see if they can help resolve the problem. For more information, see [Power BI security, user authentication](/power-bi/admin/service-admin-power-bi-security#user-authentication), and [Troubleshooting sign-in issues for Power BI](/power-bi/admin/power-bi-cannot-sign-in). +:::image type="content" source="media/AccessDeniedError.png" alt-text="Screenshot that shows the access-denied error."::: +> [!NOTE] +> Power BI uses [Microsoft Entra ID](https://azure.microsoft.com/services/active-directory/) to authenticate users who sign in to the Power BI service, and in turn, uses the Power BI sign-in credentials whenever a user attempts to access resources that require authentication. Users sign in to the Power BI service by using the email address used to establish their Power BI account. Power BI uses that sign-in email as the *effective username*, which is passed to resources whenever a user attempts to connect to data. The effective username is then mapped to a [user principal name](/windows/win32/secauthn/user-name-formats) and resolved to the associated Windows domain account, against which authentication is applied. -### Q: How do I resolve the *Access to the resource is forbidden* error? +### Q: How do I resolve the "Access to the resource is forbidden" error? -> Access to the resource is forbidden. +**A:** You might get this error if you have access to a specific project but you don't have the **View analytics** permissions. Work with your project administrator to get these permissions. For more information about the security model, see [Analytics security](analytics-security.md). -**A:** You can come across this error if you have access to a given project but you don't have the *View analytics* permissions. Work with your project administrator to get these permissions. -For more information about the security model, see [Analytics security](analytics-security.md). - -> [!div class="mx-imgBorder"] -> ![Access to the resource is forbidden.](media/AnalyticsAccessCheckException.png) +:::image type="content" source="media/AnalyticsAccessCheckException.png" alt-text="Screenshot that shows the error message Access to the resource is forbidden."::: -### Q: How do I resolve the *Project "X" does not exist or you do not have permissions to access it* error? - -> We encountered an error while trying to connect.
      -> Details: Invalid "Project" parameter. **Project "X" doesn't exist or you do not have permissions to access it.**. - -**A:** This error indicates that the value you entered for *Project name* doesn't correspond to any project. A common mistake users can make is to confuse the project name with a team name. - -If the URL you use every day is "`https://dev.azure.com/fabrikam-fiber-inc/Fabrikam-Fiber-Git/Device`", then `Fabrikam-Fiber-Git` is the project name and it should be used in the parameter. `Device` is the team name. - -![ProjectNotFoundError](media/ProjecNotFoundError.png) +### Q: How do I resolve the "Project 'X' doesn't exist or you don't have permissions to access it" error? +**A:** This error indicates that the value you entered for **Project name** doesn't correspond to any project. A common mistake that users make is to confuse the project name with a team name. - +For example, if the URL you use is `https://dev.azure.com/fabrikam-fiber-inc/Fabrikam-Fiber-Git/Device`, then *Fabrikam-Fiber-Git* is the project name and it should be used in the parameter. *Device* is the team name. +:::image type="content" source="media/ProjecNotFoundError.png" alt-text="Screenshot that shows the Project not found error."::: ## Related articles -- [Permissions required to access Analytics](analytics-security.md) -- [Power BI integration overview](overview.md) -- [Analytics security](analytics-security.md) -- [Authenticate your identity with personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) -- [Dataset design for the Power BI Data Connector](data-connector-dataset.md) -- [Data Connector - Example reports](data-connector-examples.md) \ No newline at end of file +- [Set permissions to access Analytics and Analytics views](analytics-security.md) +- [Learn about Power BI integration](overview.md) +- [Set permissions to access Analytics and Analytics views](analytics-security.md) +- [Design Analytics views dataset](data-connector-dataset.md) +- [Explore example reports based on Analytics views](data-connector-examples.md) diff --git a/docs/report/powerbi/data-connector-dataset.md b/docs/report/powerbi/data-connector-dataset.md index 0a0481c0c6f..3a74dd042ff 100644 --- a/docs/report/powerbi/data-connector-dataset.md +++ b/docs/report/powerbi/data-connector-dataset.md @@ -7,7 +7,7 @@ ms.custom: analytics-views ms.author: chcomley author: chcomley ms.topic: reference -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 05/12/2022 --- @@ -20,7 +20,7 @@ Each Analytics view defines a dataset in Power BI. Datasets are the tables and p * The entities and associated fields available from Analytics are flattened (denormalized) into a single table. For example, the user name in "Created By" is modeled as a string (User Name), rather than the user ID. It eliminates the need to create relationships between tables to create reports. * Historical data is modeled as snapshots for each time period, so trending reporting is simple. -To learn more about Power BI and datasets, see [Power BI - basic concepts for Power BI service](/power-bi/service-basic-concepts). +For more information about Power BI and datasets, see [Power BI - basic concepts for Power BI service](/power-bi/service-basic-concepts). ## Flattening the Analytics OData endpoint @@ -51,7 +51,6 @@ You can select all work tracking fields in an Analytics view, except for the fol For a description of each work item tracking fields, see [Entities and properties reference for Azure Boards](../analytics/entity-reference-boards.md). - ### Analytics data store fields You can select the following Analytics-based fields in an Analytics view: @@ -81,8 +80,6 @@ To access any other fields available through [Analytics](../extend-analytics/ana * Process (AreaSK - generate mapping Table based on *Process* Navigational Property) * WorkItemLinks (Work Item ID) - - ### Data relationships Understanding the [Analytics data model](../extend-analytics/data-model-analytics-service.md) is critical to building good relationships between entities. @@ -123,7 +120,6 @@ not allowed. To handle this scenario, you could expand the Project column in the Now you can list Areas by Project and get a count of Areas in each project. - ## Related articles - [Historical data representation in Analytics](analytics-historical-filtering.md) diff --git a/docs/report/powerbi/data-connector-examples.md b/docs/report/powerbi/data-connector-examples.md index 9ad44a6a582..351bc160ca3 100644 --- a/docs/report/powerbi/data-connector-examples.md +++ b/docs/report/powerbi/data-connector-examples.md @@ -8,7 +8,7 @@ ms.subservice: azure-devops-analytics ms.topic: sample ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms date: 12/13/2022 --- @@ -26,9 +26,11 @@ Before generating these reports, you must first [connect to Analytics using the > [!TIP] > Use the search box if you are working with tables that contain many columns. +## Prerequisites + [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] - + ## Show card with total count of work items diff --git a/docs/report/powerbi/data-connector-functions.md b/docs/report/powerbi/data-connector-functions.md index 7603ba1b9d6..dff64d5205c 100644 --- a/docs/report/powerbi/data-connector-functions.md +++ b/docs/report/powerbi/data-connector-functions.md @@ -7,7 +7,7 @@ ms.subservice: azure-devops-analytics ms.topic: conceptual ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms date: 10/04/2021 --- @@ -23,7 +23,6 @@ The VSTS.AccountContents function is a replacement for Power Query M function [W > - Use VSTS.AccountContents only to access data that isn't [available in Analytics](data-available-in-analytics.md). It pulls data directly from Azure DevOps and, to protect other Azure DevOps users, it's susceptible to throttling. See the [Supported Subdomains for VSTS.AccountContents section](#) later in this article. For information about other approaches, see the [Power BI integration overview](overview.md). > - VSTS.AccountContents supports only Azure Boards data (work items). The data connector doesn't support other data types, such as pipelines. Currently, we have no plans to update the connector to support other data types. - ## VSTS.AccountContents Advanced function that returns the contents downloaded from the URL for Analytics as a binary value. @@ -55,7 +54,7 @@ If you're already using `Web.Contents` to access work tracking data from Analyti > |`Timeout`|Specify this value as a duration will change the timeout for an HTTP request. The default value is 600 seconds.| > |`Version`|Version of the data model. This option is primary for diagnostics.| - + ## Supported Subdomains for VSTS.AccountContents @@ -65,7 +64,6 @@ Currently, the `VSTS.AccountContents()` method only works for the subdomains lis - `https://analytics.dev.azure.com/` - `https://vsrm.dev.azure.com/` - ## Related articles * [Power Query M language specification](/powerquery-m/power-query-m-language-specification) diff --git a/docs/report/powerbi/includes/analytics-views-warning.md b/docs/report/powerbi/includes/analytics-views-warning.md index a5d1d3df8bc..a71a467e635 100644 --- a/docs/report/powerbi/includes/analytics-views-warning.md +++ b/docs/report/powerbi/includes/analytics-views-warning.md @@ -3,8 +3,8 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: include -ms.date: 07/14/2020 +ms.date: 09/10/2024 --- > [!IMPORTANT] -> **Analytics views only support Azure Boards data (work items)**. Analytics views doesn't support other data types, such as Pipelines. Views provide a flat-list of work items, and don't support work item hierarchies. At this point, we have no plans to update the connector to support other types of data. For information on other approaches, read [Power BI Integration Overview](../overview.md). +> **Analytics views only support Azure Boards data (work items)**. Analytics views don't support other data types, such as pipelines. Views provide a flat-list of work items and don't support work item hierarchies. At this point, we have no plans to update the connector to support other types of data. For information on other approaches, see [About Power BI integration](../overview.md). diff --git a/docs/report/powerbi/includes/manage-shared-view-permissions.md b/docs/report/powerbi/includes/manage-shared-view-permissions.md index 446cfc0d4be..e4a748f37fb 100644 --- a/docs/report/powerbi/includes/manage-shared-view-permissions.md +++ b/docs/report/powerbi/includes/manage-shared-view-permissions.md @@ -6,7 +6,6 @@ ms.topic: include ms.date: 06/18/2021 --- - ## Manage permissions for a shared view All members of the Contributors group for your project can use **Shared** views in Power BI. For shared views that you create, you can manage the permissions of users and groups to create, delete, or view a specific shared view. @@ -24,7 +23,7 @@ All members of the Contributors group for your project can use **Shared** views Close the dialog when done. Your changes are automatically saved. ::: moniker-end - ::: moniker range=">= azure-devops-2019 < azure-devops" + ::: moniker range=" [!NOTE] -> The `TestSuite/RequirementWorkItem/...` entry indicates that the work item must be linked to the test suite via a *requirement-based test suites* as discussed in the [prerequisites](#prerequisites). +> The `TestSuite/RequirementWorkItem/...` entry indicates that the work item must be linked to the test suite via a *requirement-based test suites* as discussed in the prerequisites section. diff --git a/docs/report/powerbi/includes/pipeline-test-task-resources.md b/docs/report/powerbi/includes/pipeline-test-task-resources.md index ce624355514..a3fe6511533 100644 --- a/docs/report/powerbi/includes/pipeline-test-task-resources.md +++ b/docs/report/powerbi/includes/pipeline-test-task-resources.md @@ -6,7 +6,7 @@ ms.topic: include ms.date: 01/24/2023 --- - + ## Test task resources diff --git a/docs/report/powerbi/includes/prerequisites-power-bi-2020.md b/docs/report/powerbi/includes/prerequisites-power-bi-2020.md index 03125d9f157..934370b159d 100644 --- a/docs/report/powerbi/includes/prerequisites-power-bi-2020.md +++ b/docs/report/powerbi/includes/prerequisites-power-bi-2020.md @@ -2,7 +2,7 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley -ms.date: 12/18/2020 +ms.date: 01/13/2025 ms.topic: include --- @@ -12,23 +12,22 @@ ms.topic: include ::: moniker range="azure-devops" -- You must be a member of a project with Basic access or higher. If you haven't been added as a project member, [get added now](../../../organizations/accounts/add-organization-users.md). Anyone with access to the project, except stakeholders, can view Analytics views. -- For Analytics data to be available, the corresponding service must be enabled. For example, to query work tracking data, **Boards** must be enabled. If it is disabled, **Analytics views** won't be displayed. To re-enable a service, see [Turn an Azure DevOps service on or off](../../../organizations/settings/set-services.md) -- To use **Analytics views**, [enable the Analytics views preview feature](../../../project/navigation/preview-features.md) either for individual users or for the organization. -- Also, you must have your ***View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). -- To use Power BI for Azure DevOps or to exercise an OData query for Analytics, you must have your **View Analytics** permission set to *Allow*. By default, all Contributors with Basic access are granted access. To edit shared **Analytics views**, you must have your **Edit shared Analytics views** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/accounts/add-organization-users.md) with at least Basic access. If you aren't a project member, [get added now](../../../organizations/accounts/add-organization-users.md). Anyone with access to the project, except stakeholders, can view Analytics views. | +| **Service availability** | For Analytics data availability, enable the corresponding service. For example, to query work tracking data, enable **Boards**. If it's disabled, **Analytics views** don't display. To re-enable a service, see [Turn an Azure DevOps service on or off](../../../organizations/settings/set-services.md). | +| **Feature enablement** | To use **Analytics views**, [enable the Analytics views preview feature](../../../project/navigation/preview-features.md) either for individual users or for the organization. | +| **Permissions** | - **View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md).
      - To use Power BI for Azure DevOps or to exercise an OData query for Analytics: **View Analytics** permission set to *Allow*. By default, all Contributors with Basic access are granted access.
      - To edit shared **Analytics views**: **Edit shared Analytics views** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). | ::: moniker-end - - ::: moniker range=">= azure-devops-2020 < azure-devops" -- You must be a member of a project with Basic access or higher. If you haven't been added as a project member, [get added now](../../../organizations/security/add-users-team-project.md). Anyone with access to the project, except stakeholders, can view Analytics views. -- [Verify that Analytics](../../dashboards/analytics-extension.md) is installed, and if not, then enable it. You must be an account owner or a member of the [**Project Collection Administrators** group](../../../organizations/security/change-organization-collection-level-permissions.md) to add extensions or enable the service. -- For Analytics data to be available, the corresponding service must be enabled. For example, to query work tracking data, **Boards** must be enabled. If it is disabled, **Analytics views** won't be displayed. To re-enable a service, see [Turn an Azure DevOps service on or off](../../../organizations/settings/set-services.md) -- To use **Analytics views**, [enable the Analytics views preview feature](../../../project/navigation/preview-features.md) either for individual users or for the organization. -- Also, you must have your ***View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). -- To use Power BI for Azure DevOps or to exercise an OData query for Analytics, you must must have your***View Analytics** permission set to *Allow*. By default, all Contributors with Basic access are granted access. To edit shared **Analytics views**, you must have your **Edit shared Analytics views** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/accounts/add-organization-users.md) with at least **Basic** access. If you aren't a project member, [get added now](../../../organizations/security/add-users-team-project.md). Anyone with access to the project, except stakeholders, can view Analytics views. | +| **Permissions** | - **View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md).
      - To use Power BI for Azure DevOps or to exercise an OData query for Analytics: **View Analytics** permission set to *Allow*. By default, all Contributors with Basic access are granted access.
      - To edit shared **Analytics views**: **Edit shared Analytics views** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). | +| **Service availability** | [Analytics](../../dashboards/analytics-extension.md) installed and enabled. Be an account owner or a member of the [**Project Collection Administrators** group](../../../organizations/security/change-organization-collection-level-permissions.md) to add extensions or enable the service. For Analytics data availability, enable the corresponding service. For example, to query work tracking data, enable **Boards**. If it's disabled, **Analytics views** don't display. To re-enable a service, see [Turn an Azure DevOps service on or off](../../../organizations/settings/set-services.md). | +| **Feature enablement** | To use **Analytics views**, [enable the Analytics views preview feature](../../../project/navigation/preview-features.md) either for individual users or for the organization. | ::: moniker-end diff --git a/docs/report/powerbi/includes/prerequisites-power-bi-cloud-only.md b/docs/report/powerbi/includes/prerequisites-power-bi-cloud-only.md index 3e4c7133196..3db48303bed 100644 --- a/docs/report/powerbi/includes/prerequisites-power-bi-cloud-only.md +++ b/docs/report/powerbi/includes/prerequisites-power-bi-cloud-only.md @@ -2,7 +2,7 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley -ms.date: 12/18/2020 +ms.date: 01/13/2025 ms.topic: include --- @@ -10,8 +10,9 @@ ms.topic: include ## Prerequisites -- You must be a member of a project with Basic access or higher. If you haven't been added as a project member, [get added now](../../../organizations/accounts/add-organization-users.md). Anyone with access to the project, except stakeholders, can view Analytics views. -- For Analytics data to be available, the corresponding service must be enabled. For example, to query work tracking data, **Boards** must be enabled. If it is disabled, **Analytics views** won't be displayed. To re-enable a service, see [Turn an Azure DevOps service on or off](../../../organizations/settings/set-services.md) -- To use **Analytics views**, [enable the Analytics views preview feature](../../../project/navigation/preview-features.md) either for individual users or for the organization. -- Also, you must have your ***View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). -- To use Power BI for Azure DevOps or to exercise an OData query for Analytics, you must have your **View Analytics** permission set to *Allow*. By default, all Contributors with Basic access are granted access. To edit shared **Analytics views**, you must have your **Edit shared Analytics views** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/accounts/add-organization-users.md) with at least **Basic** access. If you aren't project member, [get added now](../../../organizations/accounts/add-organization-users.md). Anyone with access to the project, except stakeholders, can view Analytics views. | +| **Permissions** | - **View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md).
      - To use Power BI for Azure DevOps or to exercise an OData query for Analytics: **View Analytics** permission set to *Allow*. By default, all Contributors with Basic access are granted access.
      - To edit shared **Analytics views**: **Edit shared Analytics views** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). | +| **Service availability** | For Analytics data availability, enable the corresponding service. For example, to query work tracking data, enable **Boards**. If it's disabled, **Analytics views** don't display. To re-enable a service, see [Turn an Azure DevOps service on or off](../../../organizations/settings/set-services.md). | +| **Feature enablement** | To use **Analytics views**, [enable the Analytics views preview feature](../../../project/navigation/preview-features.md) either for individual users or for the organization. | diff --git a/docs/report/powerbi/includes/prerequisites-power-bi.md b/docs/report/powerbi/includes/prerequisites-power-bi.md index c7ef9315b22..c85a49cb862 100644 --- a/docs/report/powerbi/includes/prerequisites-power-bi.md +++ b/docs/report/powerbi/includes/prerequisites-power-bi.md @@ -2,33 +2,29 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley -ms.date: 12/18/2020 +ms.date: 01/13/2025 ms.topic: include --- - ## Prerequisites - ::: moniker range="azure-devops" -- You must be a member of a project with Basic access or higher. If you haven't been added as a project member, [get added now](../../../organizations/accounts/add-organization-users.md). Anyone with access to the project, except stakeholders, can view Analytics views. -- For Analytics data to be available, the corresponding service must be enabled. For example, to query work tracking data, **Boards** must be enabled. If it is disabled, **Analytics views** won't be displayed. To re-enable a service, see [Turn an Azure DevOps service on or off](../../../organizations/settings/set-services.md) -- To use **Analytics views**, [enable the Analytics views preview feature](../../../project/navigation/preview-features.md) either for individual users or for the organization. -- Also, you must have your ***View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). -- To use Power BI for Azure DevOps or to exercise an OData query for Analytics, you must have your **View Analytics** permission set to *Allow*. By default, all Contributors with Basic access are granted access. To edit shared **Analytics views**, you must have your ***Edit shared Analytics views** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). +| Category | Requirement | +|--------------|-------------| +| **Access levels** | [Project member](../../organizations/accounts/add-organization-users.md) with at least **Basic** access. Anyone with access to the project, except those granted **Stakeholder** access, can view Analytics views. | +| **Services** | Enable **Boards**. If it's disabled, **Analytics views** doesn't display. [Reenable it](../../organizations/settings/set-services.md) either for individual users or for the entire organization. | +| **Permissions** | - **View Analytics** permission set to **Allow**. For more information, see [Grant permissions to access the Analytics service](../powerbi/analytics-security.md). By default, all Contributors with Basic access are granted access.
      - To edit shared **Analytics views**: **Edit shared Analytics views** permission set to **Allow**. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). | ::: moniker-end +::: moniker range="- For Analytics data availability, enable the corresponding service. For example, to query work tracking data, enable **Boards**. If it's disabled, **Analytics views** doesn't display. To re-enable a service, see [Turn an Azure DevOps service on or off](../../../organizations/settings/set-services.md). | +| **Feature enablement** | To use **Analytics views**, [enable the Analytics views preview feature](../../../project/navigation/preview-features.md) either for individual users or for the organization. | +| **Permissions** | - **View Analytics** permission set to **Allow**. For more information, see [Grant permissions to access the Analytics service](../powerbi/analytics-security.md). By default, all Contributors with Basic access are granted access.
      - To edit shared **Analytics views**: **Edit shared Analytics views** permission set to **Allow**. For more information, see [Grant permissions to access the Analytics service](../analytics-security.md). | ::: moniker-end diff --git a/docs/report/powerbi/includes/query-filters-pipelines.md b/docs/report/powerbi/includes/query-filters-pipelines.md index 69d08269279..57049e41ba8 100644 --- a/docs/report/powerbi/includes/query-filters-pipelines.md +++ b/docs/report/powerbi/includes/query-filters-pipelines.md @@ -8,6 +8,6 @@ ms.date: 12/13/2022 > [!NOTE] -> To determine available properties for filter or report purposes, see [Metadata reference for Azure Pipelines](../../analytics/entity-reference-pipelines.md). You can filter your queries or return properties using any of the `Property` values under an `EntityType` or `NavigationPropertyBinding Path` values available with an `EntitySet`. Each `EntitySet` corresponds to an `EntityType`. To learn more about the data type of each value, review the metadata provided for the corresponding `EntityType`. +> To determine available properties for filter or report purposes, see [Metadata reference for Azure Pipelines](../../analytics/entity-reference-pipelines.md). You can filter your queries or return properties using any of the `Property` values under an `EntityType` or `NavigationPropertyBinding Path` values available with an `EntitySet`. Each `EntitySet` corresponds to an `EntityType`. For more information about the data type of each value, review the metadata provided for the corresponding `EntityType`. diff --git a/docs/report/powerbi/includes/query-filters-test-pipelines.md b/docs/report/powerbi/includes/query-filters-test-pipelines.md index f198d894568..3cea7f19364 100644 --- a/docs/report/powerbi/includes/query-filters-test-pipelines.md +++ b/docs/report/powerbi/includes/query-filters-test-pipelines.md @@ -8,5 +8,5 @@ ms.date: 01/19/2023 > [!NOTE] -> To determine available properties for filter or report purposes, see [Metadata reference for Test Plans Analytics](../../analytics/entity-reference-test-plans.md) and [Metadata reference for Azure Pipelines](../../analytics/entity-reference-pipelines.md). You can filter your queries or return properties using any of the `Property` values under an `EntityType` or `NavigationPropertyBinding Path` values available with an `EntitySet`. Each `EntitySet` corresponds to an `EntityType`. To learn more about the data type of each value, review the metadata provided for the corresponding `EntityType`. +> To determine available properties for filter or report purposes, see [Metadata reference for Test Plans Analytics](../../analytics/entity-reference-test-plans.md) and [Metadata reference for Azure Pipelines](../../analytics/entity-reference-pipelines.md). You can filter your queries or return properties using any of the `Property` values under an `EntityType` or `NavigationPropertyBinding Path` values available with an `EntitySet`. Each `EntitySet` corresponds to an `EntityType`. For more information about the data type of each value, review the metadata provided for the corresponding `EntityType`. \ No newline at end of file diff --git a/docs/report/powerbi/includes/query-filters-test.md b/docs/report/powerbi/includes/query-filters-test.md index 970323c586d..20201094057 100644 --- a/docs/report/powerbi/includes/query-filters-test.md +++ b/docs/report/powerbi/includes/query-filters-test.md @@ -8,5 +8,5 @@ ms.date: 01/19/2023 > [!NOTE] -> To determine available properties for filter or report purposes, see [Metadata reference for Test Plans Analytics](../../analytics/entity-reference-test-plans.md). You can filter your queries or return properties using any of the `Property` values under an `EntityType` or `NavigationPropertyBinding Path` values available with an `EntitySet`. Each `EntitySet` corresponds to an `EntityType`. To learn more about the data type of each value, review the metadata provided for the corresponding `EntityType`. +> To determine available properties for filter or report purposes, see [Metadata reference for Test Plans Analytics](../../analytics/entity-reference-test-plans.md). You can filter your queries or return properties using any of the `Property` values under an `EntityType` or `NavigationPropertyBinding Path` values available with an `EntitySet`. Each `EntitySet` corresponds to an `EntityType`. For more information about the data type of each value, review the metadata provided for the corresponding `EntityType`. \ No newline at end of file diff --git a/docs/report/powerbi/includes/query-filters-work-items.md b/docs/report/powerbi/includes/query-filters-work-items.md index 428d32eca54..756966a7e56 100644 --- a/docs/report/powerbi/includes/query-filters-work-items.md +++ b/docs/report/powerbi/includes/query-filters-work-items.md @@ -7,6 +7,6 @@ ms.date: 12/05/2022 --- > [!NOTE] -> To determine available properties for filter or report purposes, see [Metadata reference for Azure Boards](../../analytics/entity-reference-boards.md). You can filter your queries or return properties using any of the `Property` values under an `EntityType` or `NavigationPropertyBinding Path` values available with an `EntitySet`. Each `EntitySet` corresponds to an `EntityType`. To learn more about the data type of each value, review the metadata provided for the corresponding `EntityType`. +> To determine available properties for filter or report purposes, see [Metadata reference for Azure Boards](../../analytics/entity-reference-boards.md). You can filter your queries or return properties using any of the `Property` values under an `EntityType` or `NavigationPropertyBinding Path` values available with an `EntitySet`. Each `EntitySet` corresponds to an `EntityType`. For more information about the data type of each value, review the metadata provided for the corresponding `EntityType`. diff --git a/docs/report/powerbi/includes/sample-powerbi-query.md b/docs/report/powerbi/includes/sample-powerbi-query.md index 68e5029a3a5..2da3672c210 100644 --- a/docs/report/powerbi/includes/sample-powerbi-query.md +++ b/docs/report/powerbi/includes/sample-powerbi-query.md @@ -2,4 +2,4 @@ ms.topic: include --- -You can paste the Power BI query listed below directly into the **Get Data->Blank Query** window. For more information, review [Overview of sample reports using OData queries](../sample-odata-overview.md). \ No newline at end of file +Copy and paste the following Power BI query directly into the **Get Data** > **Blank Query** window. For more information, see [Overview of sample reports using OData queries](../sample-odata-overview.md). diff --git a/docs/report/powerbi/includes/sample-related-articles-pipelines.md b/docs/report/powerbi/includes/sample-related-articles-pipelines.md index d99ae01d5c5..0568aad5dce 100644 --- a/docs/report/powerbi/includes/sample-related-articles-pipelines.md +++ b/docs/report/powerbi/includes/sample-related-articles-pipelines.md @@ -7,7 +7,5 @@ ms.date: 01/24/2023 --- - [Construct OData queries for Analytics](../../analytics/analytics-query-parts.md) -- [Connect using Power BI and OData queries](../odataquery-connect.md) - [Metadata reference for Azure Pipelines](../../analytics/entity-reference-pipelines.md) - [Sample reports and quick reference index](../../extend-analytics/quick-ref.md) -- [Slicers in Power BI](/power-bi/visuals/power-bi-visualization-slicers) \ No newline at end of file diff --git a/docs/report/powerbi/includes/sample-relatedarticles.md b/docs/report/powerbi/includes/sample-relatedarticles.md index b62a7c85715..abf55744367 100644 --- a/docs/report/powerbi/includes/sample-relatedarticles.md +++ b/docs/report/powerbi/includes/sample-relatedarticles.md @@ -6,9 +6,9 @@ ms.topic: include ms.date: 12/05/2022 --- -* [Overview of sample reports using OData queries](../sample-odata-overview.md) +* [Explore sample reports using OData queries](../sample-odata-overview.md) * [Construct OData queries for Analytics](../../analytics/analytics-query-parts.md) -* [Connect using Power BI and OData queries](../odataquery-connect.md) -* [Metadata reference for Azure Boards Analytics](../../analytics/entity-reference-boards.md) -* [Sample reports and quick reference index](../../extend-analytics/quick-ref.md) -* [Add a Team slicer to an existing report](../sample-boards-teamslicer.md) \ No newline at end of file +* [Connect to Power BI using OData queries](../odataquery-connect.md) +* [Refer to metadata for Azure Boards Analytics](../../analytics/entity-reference-boards.md) +* [Access sample reports and quick reference index](../../extend-analytics/quick-ref.md) +* [Add a Team slicer to an existing report](../sample-boards-teamslicer.md) diff --git a/docs/report/powerbi/includes/sample-required-reading.md b/docs/report/powerbi/includes/sample-required-reading.md index 4b0fa594e31..520bfd79888 100644 --- a/docs/report/powerbi/includes/sample-required-reading.md +++ b/docs/report/powerbi/includes/sample-required-reading.md @@ -3,4 +3,4 @@ ms.topic: include --- > [!NOTE] -> This article assumes you've read [Overview of Sample Reports using OData Queries](../sample-odata-overview.md) and have a basic understanding of Power BI. \ No newline at end of file +> This article assumes you read [Overview of Sample Reports using OData Queries](../sample-odata-overview.md) and have a basic understanding of Power BI. diff --git a/docs/report/powerbi/includes/sample-stories-overview-prereqs.md b/docs/report/powerbi/includes/sample-stories-overview-prereqs.md index ac4c4cf7936..6ed4d1537c3 100644 --- a/docs/report/powerbi/includes/sample-stories-overview-prereqs.md +++ b/docs/report/powerbi/includes/sample-stories-overview-prereqs.md @@ -12,5 +12,5 @@ For the report to generate useful data, you need to have performed the following - You've define requirement work items and assigned them to the area and iteration paths of interest. For information about how to define area and iteration paths, see [Define area paths](../../../organizations/settings/set-area-paths.md) and [Define iteration paths](../../../organizations/settings/set-iteration-paths-sprints.md). - To get the percentage of hours completion, you need to fill in the [Complete Work](../../../boards/queries/query-numeric.md#completed-work) and [Remaining Work](../../../boards/queries/query-numeric.md#remaining-work) fields of tasks or bugs linked to requirements with the **Child** link type. -- To get the execution status of test cases, you will have created *requirement-based test suites* in Test Plans corresponding to those requirements. Inline tests you add through the Kanban board satisfy this prerequisite, however requirements that you link to tests don't. To learn more, see [Create test plans and test suites](../../../test/create-a-test-plan.md). +- To get the execution status of test cases, you will have created *requirement-based test suites* in Test Plans corresponding to those requirements. Inline tests you add through the board satisfy this prerequisite, however requirements that you link to tests don't. For more information, see [Create test plans and test suites](../../../test/create-a-test-plan.md). - To get the status of bugs, you will have created and linked bugs to requirements with the **Child** link type. diff --git a/docs/report/powerbi/media/AccessDeniedError.png b/docs/report/powerbi/media/AccessDeniedError.png index 2f2e2b1b989..78a2eaca541 100644 Binary files a/docs/report/powerbi/media/AccessDeniedError.png and b/docs/report/powerbi/media/AccessDeniedError.png differ diff --git a/docs/report/powerbi/media/AnalyticsAccessCheckException.png b/docs/report/powerbi/media/AnalyticsAccessCheckException.png index 26477144fc9..8e3b4024537 100644 Binary files a/docs/report/powerbi/media/AnalyticsAccessCheckException.png and b/docs/report/powerbi/media/AnalyticsAccessCheckException.png differ diff --git a/docs/report/powerbi/media/ODataQuery.png b/docs/report/powerbi/media/ODataQuery.png index c8a8ff3d483..680ed732195 100644 Binary files a/docs/report/powerbi/media/ODataQuery.png and b/docs/report/powerbi/media/ODataQuery.png differ diff --git a/docs/report/powerbi/media/ProjecNotFoundError.png b/docs/report/powerbi/media/ProjecNotFoundError.png index f1ecfeb3181..7d223e08651 100644 Binary files a/docs/report/powerbi/media/ProjecNotFoundError.png and b/docs/report/powerbi/media/ProjecNotFoundError.png differ diff --git a/docs/report/powerbi/media/QueryExceedsPreferredMaxSizeException.png b/docs/report/powerbi/media/QueryExceedsPreferredMaxSizeException.png index 22334b5edfe..956dd451b6a 100644 Binary files a/docs/report/powerbi/media/QueryExceedsPreferredMaxSizeException.png and b/docs/report/powerbi/media/QueryExceedsPreferredMaxSizeException.png differ diff --git a/docs/report/powerbi/media/advanced-editor.png b/docs/report/powerbi/media/advanced-editor.png new file mode 100644 index 00000000000..546fd6d17a8 Binary files /dev/null and b/docs/report/powerbi/media/advanced-editor.png differ diff --git a/docs/report/powerbi/media/analytics-views/fields-customize-no-common.png b/docs/report/powerbi/media/analytics-views/fields-customize-no-common.png index 5020c66fbfa..d2f8154e15e 100644 Binary files a/docs/report/powerbi/media/analytics-views/fields-customize-no-common.png and b/docs/report/powerbi/media/analytics-views/fields-customize-no-common.png differ diff --git a/docs/report/powerbi/media/analytics-views/open-analytics-2020.png b/docs/report/powerbi/media/analytics-views/open-analytics-2020.png index 696da7318c9..db14408655b 100644 Binary files a/docs/report/powerbi/media/analytics-views/open-analytics-2020.png and b/docs/report/powerbi/media/analytics-views/open-analytics-2020.png differ diff --git a/docs/report/powerbi/media/create-report/choose-view.png b/docs/report/powerbi/media/create-report/choose-view.png index 8e63294784d..81f6970bb3b 100644 Binary files a/docs/report/powerbi/media/create-report/choose-view.png and b/docs/report/powerbi/media/create-report/choose-view.png differ diff --git a/docs/report/powerbi/media/create-report/specify-account.png b/docs/report/powerbi/media/create-report/specify-account.png index 9b89b8bd08b..037cd10242b 100644 Binary files a/docs/report/powerbi/media/create-report/specify-account.png and b/docs/report/powerbi/media/create-report/specify-account.png differ diff --git a/docs/report/powerbi/media/data-connector-visual.png b/docs/report/powerbi/media/data-connector-visual.png index 20a11d13d84..85f8aff48af 100644 Binary files a/docs/report/powerbi/media/data-connector-visual.png and b/docs/report/powerbi/media/data-connector-visual.png differ diff --git a/docs/report/powerbi/media/data-connector/get-data-azure-devops.png b/docs/report/powerbi/media/data-connector/get-data-azure-devops.png index 811b7449355..6e3de1155d0 100644 Binary files a/docs/report/powerbi/media/data-connector/get-data-azure-devops.png and b/docs/report/powerbi/media/data-connector/get-data-azure-devops.png differ diff --git a/docs/report/powerbi/media/default-views/default-views.png b/docs/report/powerbi/media/default-views/default-views.png index 18afe62ed23..a8022e6dc0d 100644 Binary files a/docs/report/powerbi/media/default-views/default-views.png and b/docs/report/powerbi/media/default-views/default-views.png differ diff --git a/docs/report/powerbi/media/default-views/navigator-dialog-default-views.png b/docs/report/powerbi/media/default-views/navigator-dialog-default-views.png index a06e4ac5284..b9d3b6b5980 100644 Binary files a/docs/report/powerbi/media/default-views/navigator-dialog-default-views.png and b/docs/report/powerbi/media/default-views/navigator-dialog-default-views.png differ diff --git a/docs/report/powerbi/media/edit-queries.png b/docs/report/powerbi/media/edit-queries.png index 56c5e1ed929..8558c029c5c 100644 Binary files a/docs/report/powerbi/media/edit-queries.png and b/docs/report/powerbi/media/edit-queries.png differ diff --git a/docs/report/powerbi/media/editable-views/area-path.png b/docs/report/powerbi/media/editable-views/area-path.png index 0d7d0162977..eaa54e8b8dc 100644 Binary files a/docs/report/powerbi/media/editable-views/area-path.png and b/docs/report/powerbi/media/editable-views/area-path.png differ diff --git a/docs/report/powerbi/media/editable-views/directory-actions.png b/docs/report/powerbi/media/editable-views/directory-actions.png index 9740baa5966..a338c068098 100644 Binary files a/docs/report/powerbi/media/editable-views/directory-actions.png and b/docs/report/powerbi/media/editable-views/directory-actions.png differ diff --git a/docs/report/powerbi/media/editable-views/field-criteria.png b/docs/report/powerbi/media/editable-views/field-criteria.png index ea7b72715ae..06e10e4e7c7 100644 Binary files a/docs/report/powerbi/media/editable-views/field-criteria.png and b/docs/report/powerbi/media/editable-views/field-criteria.png differ diff --git a/docs/report/powerbi/media/editable-views/general.png b/docs/report/powerbi/media/editable-views/general.png index 1c7c4e4a2fc..ba154d09430 100644 Binary files a/docs/report/powerbi/media/editable-views/general.png and b/docs/report/powerbi/media/editable-views/general.png differ diff --git a/docs/report/powerbi/media/editable-views/history-example.png b/docs/report/powerbi/media/editable-views/history-example.png index 30d73c0d4fc..8c1126ed2b9 100644 Binary files a/docs/report/powerbi/media/editable-views/history-example.png and b/docs/report/powerbi/media/editable-views/history-example.png differ diff --git a/docs/report/powerbi/media/editable-views/history-exclude.png b/docs/report/powerbi/media/editable-views/history-exclude.png index 6c9cf41ab75..d3777066cb9 100644 Binary files a/docs/report/powerbi/media/editable-views/history-exclude.png and b/docs/report/powerbi/media/editable-views/history-exclude.png differ diff --git a/docs/report/powerbi/media/editable-views/summary-panel.png b/docs/report/powerbi/media/editable-views/summary-panel.png index c3b9703d99a..991eb40db53 100644 Binary files a/docs/report/powerbi/media/editable-views/summary-panel.png and b/docs/report/powerbi/media/editable-views/summary-panel.png differ diff --git a/docs/report/powerbi/media/editable-views/verify-success.png b/docs/report/powerbi/media/editable-views/verify-success.png index 14c8728272c..8b84a300f27 100644 Binary files a/docs/report/powerbi/media/editable-views/verify-success.png and b/docs/report/powerbi/media/editable-views/verify-success.png differ diff --git a/docs/report/powerbi/media/editable-views/wi-type-picker.png b/docs/report/powerbi/media/editable-views/wi-type-picker.png index e8c13ea6adb..bf59197d3ac 100644 Binary files a/docs/report/powerbi/media/editable-views/wi-type-picker.png and b/docs/report/powerbi/media/editable-views/wi-type-picker.png differ diff --git a/docs/report/powerbi/media/editable-views/work-items-default.png b/docs/report/powerbi/media/editable-views/work-items-default.png index c4e6557fd8e..6caeb9f1038 100644 Binary files a/docs/report/powerbi/media/editable-views/work-items-default.png and b/docs/report/powerbi/media/editable-views/work-items-default.png differ diff --git a/docs/report/powerbi/media/enter-account.png b/docs/report/powerbi/media/enter-account.png new file mode 100644 index 00000000000..a46cb696fed Binary files /dev/null and b/docs/report/powerbi/media/enter-account.png differ diff --git a/docs/report/powerbi/media/enter-server.png b/docs/report/powerbi/media/enter-server.png new file mode 100644 index 00000000000..e51a344c179 Binary files /dev/null and b/docs/report/powerbi/media/enter-server.png differ diff --git a/docs/report/powerbi/media/get-data-connector.png b/docs/report/powerbi/media/get-data-connector.png new file mode 100644 index 00000000000..64ba7f91e20 Binary files /dev/null and b/docs/report/powerbi/media/get-data-connector.png differ diff --git a/docs/report/powerbi/media/get-data-server-connector.png b/docs/report/powerbi/media/get-data-server-connector.png new file mode 100644 index 00000000000..3211462944b Binary files /dev/null and b/docs/report/powerbi/media/get-data-server-connector.png differ diff --git a/docs/report/powerbi/media/last-refresh/change-data-type-date-time.png b/docs/report/powerbi/media/last-refresh/change-data-type-date-time.png index 6c12ebf145f..26856b062ef 100644 Binary files a/docs/report/powerbi/media/last-refresh/change-data-type-date-time.png and b/docs/report/powerbi/media/last-refresh/change-data-type-date-time.png differ diff --git a/docs/report/powerbi/media/last-refresh/get-data-blank-query.png b/docs/report/powerbi/media/last-refresh/get-data-blank-query.png new file mode 100644 index 00000000000..0d20f639756 Binary files /dev/null and b/docs/report/powerbi/media/last-refresh/get-data-blank-query.png differ diff --git a/docs/report/powerbi/media/navigator-select-data.png b/docs/report/powerbi/media/navigator-select-data.png new file mode 100644 index 00000000000..a48200f04ba Binary files /dev/null and b/docs/report/powerbi/media/navigator-select-data.png differ diff --git a/docs/report/powerbi/media/odatapowerbi-testerbyoutcome.png b/docs/report/powerbi/media/odatapowerbi-testerbyoutcome.png index 3640b8f7783..bbc9ac300bc 100644 Binary files a/docs/report/powerbi/media/odatapowerbi-testerbyoutcome.png and b/docs/report/powerbi/media/odatapowerbi-testerbyoutcome.png differ diff --git a/docs/report/powerbi/media/odatapowerbi-timeslicer-report.png b/docs/report/powerbi/media/odatapowerbi-timeslicer-report.png deleted file mode 100644 index 2c1ee798e9c..00000000000 Binary files a/docs/report/powerbi/media/odatapowerbi-timeslicer-report.png and /dev/null differ diff --git a/docs/report/powerbi/media/odataquery-powerbi-advancededitor1.png b/docs/report/powerbi/media/odataquery-powerbi-advancededitor1.png index a8e575c3d05..bab68261a50 100644 Binary files a/docs/report/powerbi/media/odataquery-powerbi-advancededitor1.png and b/docs/report/powerbi/media/odataquery-powerbi-advancededitor1.png differ diff --git a/docs/report/powerbi/media/odataquery-powerbi-advancededitor2.png b/docs/report/powerbi/media/odataquery-powerbi-advancededitor2.png index 6406065fe9b..476c25309d4 100644 Binary files a/docs/report/powerbi/media/odataquery-powerbi-advancededitor2.png and b/docs/report/powerbi/media/odataquery-powerbi-advancededitor2.png differ diff --git a/docs/report/powerbi/media/odataquery-powerbi-odatafeed.png b/docs/report/powerbi/media/odataquery-powerbi-odatafeed.png index 32e0859ad06..88924e6caaf 100644 Binary files a/docs/report/powerbi/media/odataquery-powerbi-odatafeed.png and b/docs/report/powerbi/media/odataquery-powerbi-odatafeed.png differ diff --git a/docs/report/powerbi/media/odataquery-powerbi-queryeditor.png b/docs/report/powerbi/media/odataquery-powerbi-queryeditor.png index a57c4075ca7..c01f885dfc3 100644 Binary files a/docs/report/powerbi/media/odataquery-powerbi-queryeditor.png and b/docs/report/powerbi/media/odataquery-powerbi-queryeditor.png differ diff --git a/docs/report/powerbi/media/onprem-cardentials.png b/docs/report/powerbi/media/onprem-cardentials.png deleted file mode 100644 index f49cf8bb980..00000000000 Binary files a/docs/report/powerbi/media/onprem-cardentials.png and /dev/null differ diff --git a/docs/report/powerbi/media/onprem-credentials.png b/docs/report/powerbi/media/onprem-credentials.png new file mode 100644 index 00000000000..4fdf2bcb636 Binary files /dev/null and b/docs/report/powerbi/media/onprem-credentials.png differ diff --git a/docs/report/powerbi/media/pbi2.png b/docs/report/powerbi/media/pbi2.png index 92094f6a3b6..08d5bc33094 100644 Binary files a/docs/report/powerbi/media/pbi2.png and b/docs/report/powerbi/media/pbi2.png differ diff --git a/docs/report/powerbi/media/pbi3.png b/docs/report/powerbi/media/pbi3.png index c8945d51979..04c0bd41200 100644 Binary files a/docs/report/powerbi/media/pbi3.png and b/docs/report/powerbi/media/pbi3.png differ diff --git a/docs/report/powerbi/media/powerbi-successful-organizational-signin.png b/docs/report/powerbi/media/powerbi-successful-organizational-signin.png index 0a408d1e7da..7045cacdf6b 100644 Binary files a/docs/report/powerbi/media/powerbi-successful-organizational-signin.png and b/docs/report/powerbi/media/powerbi-successful-organizational-signin.png differ diff --git a/docs/report/powerbi/media/powerbi-windows-login-onprem.png b/docs/report/powerbi/media/powerbi-windows-login-onprem.png deleted file mode 100644 index c20688991a0..00000000000 Binary files a/docs/report/powerbi/media/powerbi-windows-login-onprem.png and /dev/null differ diff --git a/docs/report/powerbi/odataquery-connect.md b/docs/report/powerbi/odataquery-connect.md index c4f1feff127..981f8aa80cd 100644 --- a/docs/report/powerbi/odataquery-connect.md +++ b/docs/report/powerbi/odataquery-connect.md @@ -1,171 +1,171 @@ --- title: Connect with data by using OData queries titleSuffix: Azure DevOps -description: Learn how to write and test OData queries for use in Power BI integration. +description: Learn how to write and test OData queries in Visual Studio Code for use in Power BI integration with Azure DevOps. ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: tutorial -monikerRange: '>= azure-devops-2019' -ms.date: 12/09/2022 +monikerRange: "<=azure-devops" +ms.date: 09/19/2024 +#customer intent: As a team member, I want to learn how to use OData queries to get data into Power BI in a way that does as much work as possible server-side. --- # Connect with data by using Power BI and OData queries [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Using OData queries is the recommended approach for pulling data into Power BI. OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines best practices for building and consuming REST APIs. To learn more, see [OData documentation](/odata/). +To pull data into Power BI, we recommend that you use Open Data Protocol (OData) queries. OData is an ISO/IEC-approved OASIS standard that defines best practices for building and consuming REST APIs. For more information, see the [OData documentation](/odata/). -To get started quickly, check out the [Overview of sample reports that use OData queries](sample-odata-overview.md). For information about other approaches, see [Power BI integration overview](overview.md). +To get started quickly, see [Overview of sample reports that use OData queries](sample-odata-overview.md). For information about other approaches, see [About Power BI integration](overview.md). -Power BI can run OData queries, which can return a filtered or aggregated set of data to Power BI. OData queries have two advantages: -* All filtering is done server-side. Only the data you need is returned, which leads to shorter refresh times. -* You can pre-aggregate data server-side. An OData query can carry out aggregations such as work item rollup and build failure rates. The aggregations are accomplished server-side, and only the aggregate values are returned to Power BI. With pre-aggregation, you can carry out aggregations across large data sets, without needing to pull all the detail data into Power BI. +Power BI can run OData queries, which can return a filtered or aggregated set of data to Power BI. OData queries have two advantages: + +- All filtering is done server-side. Only the data you need is returned, which leads to shorter refresh times. +- You can preaggregate data server-side. An OData query can carry out aggregations such as work item rollup and build failure rates. The aggregations are accomplished server-side, and only the aggregate values are returned to Power BI. With preaggregation, you can carry out aggregations across large datasets, without needing to pull all the detail data into Power BI. In this article, you learn how to: > [!div class="checklist"] -> * Write and test OData queries. -> * Run an OData query from Power BI. +> - Write and test OData queries. +> - Run an OData query from Power BI. + +## Prerequisites [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] ## Use Visual Studio Code to write and test OData queries -The easiest way to write and test OData is to use [Visual Studio Code](https://aka.ms/vscode) with the [OData extension](https://marketplace.visualstudio.com/items?itemName=stansw.vscode-odata). Visual Studio Code is a free code editor available on Windows, Mac, and Linux. The OData extension provides syntax highlighting and other functions that are useful for writing and testing queries. +The easiest way to write and test OData is to use [Visual Studio Code](https://aka.ms/vscode) with the [OData extension](https://marketplace.visualstudio.com/items?itemName=stansw.vscode-odata). Visual Studio Code is a free code editor available on Windows, Mac, and Linux. The OData extension provides syntax highlighting and other functions that are useful for writing and testing queries. -### Install Visual Studio Code - -To download and install Visual Studio Code, go to the [Visual Studio Code download page](https://aka.ms/vscode). +### Install Visual Studio Code and the OData extension -### Install the OData extension +1. Install [Visual Studio Code](https://aka.ms/vscode). -Open Visual Studio Code, select **Extensions**, and then search for *odata*. In the results list, select **vscode-odata**, and then install it. +1. Open Visual Studio Code, select **Extensions**, and then search for *odata*. In the results list, select **vscode-odata**, and then install it. -### Create an OData file - -In Visual Studio Code, create and save a file called `filename.odata`. You may name it whatever you want, but it must have a `.odata` extension to enable the OData extension functionality. +1. Create and save an OData file in Visual Studio Code, for example, *filename.odata*. Name it whatever you want, but it must have a *.odata* extension to enable the OData extension functionality. ### Write the OData query -Write the OData query. For example queries, review the [Overview of sample reports using OData queries](sample-odata-overview.md). +1. Write the OData query. For example queries, see the [Overview of sample reports that use OData queries](sample-odata-overview.md). + + The following query returns the top 10 work items under a specific area path. -The following query returns the top 10 work items under a specific area path. Replace {organization}, {project}, and {area path} with your values. +1. Replace `{organization}`, `{project}`, and `{area path}` with your values. -``` -https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/WorkItems? - $select=WorkItemId,Title,WorkItemType,State,CreatedDate - &$filter=startswith(Area/AreaPath,'{area path}') - &$orderby=CreatedDate desc - &$top=10 -``` -To query across projects, omit `/{project}` entirely. + ```odata + https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/WorkItems? + $select=WorkItemId,Title,WorkItemType,State,CreatedDate + &$filter=startswith(Area/AreaPath,'{area path}') + &$orderby=CreatedDate desc + &$top=10 + ``` -For more information about how to write OData queries against Analytics, see [OData query quick reference](../extend-analytics/quick-ref.md). + To query across projects, omit `/{project}` entirely. -After you've written the query in Visual Studio Code, you should see syntax highlighting: +For more information, see [Sample reports and quick reference index](../extend-analytics/quick-ref.md). -![Visual Studio Code OData extension - syntax highlighting](media/odataquery-syntaxhighlighting.png) +After you write the query in Visual Studio Code, you should see syntax highlighting. + +:::image type="content" source="media/odataquery-syntaxhighlighting.png" alt-text="Screenshot that shows the Visual Studio Code OData extension with syntax highlighting."::: ### Test the OData query -To test the OData query, place your cursor anywhere in the query text and select **View** > **Command Palette**. In the search box, type **odata** to bring up all the OData commands: +1. To test the OData query, place your cursor anywhere in the query text and select **View** > **Command Palette**. +1. In the search box, enter *odata* to bring up all the OData commands. -![Visual Studio Code OData extension - Command Palette](media/odataquery-commandpallette.png) + :::image type="content" source="media/odataquery-commandpallette.png" alt-text="Screenshot that shows the command palette for the Visual Studio Code OData extension."::: -Select **OData: Open**. This action combines the multiline query into a one-line URL and opens it in your default browser. +1. Select **OData: Open**. This action combines the multiline query into a one-line URL and opens it in your default browser. -The OData query result set is in JSON format. To view the results, install the JSON Formatter extension for your browser. Several options are available for both Chrome and Microsoft Edge. + - The OData query result set is in JSON format. To view the results, install the JSON Formatter extension for your browser. Several options are available for both Chrome and Microsoft Edge. -![Visual Studio Code OData extension - JSON output](media/odataquery-jsonoutput.png) + :::image type="content" source="media/odataquery-jsonoutput.png" alt-text="Screenshot that shows the JSON output for the Visual Studio Code OData extension."::: -If the query has an error, the Analytics service returns an error in JSON format. For example, this error states that the query has selected a field that doesn't exist: + - If the query has an error, the Analytics service returns an error in JSON format. For example, this error states that the query selected a field that doesn't exist. -> ![Visual Studio Code OData extension - JSON error](media/odataquery-jsonerror.png) + :::image type="content" source="media/odataquery-jsonerror.png" alt-text="Screenshot that shows the JSON error for the Visual Studio Code OData extension."::: -After you've verified that the query works correctly, you can run it from Power BI. +After you verify that the query works correctly, you can run it from Power BI. ## Run the OData query from Power BI +To run the OData query from Power BI, follow the steps in the next section. + ### Combine the multiline OData query into a single-line query Before you use the query in Power BI, you must convert the multiline OData query into a single-line query. The simplest way to do so is to use [Visual Studio Code](https://aka.ms/vscode) with the [OData extension](https://marketplace.visualstudio.com/items?itemName=stansw.vscode-odata) and use the **OData: Combine** command. > [!NOTE] -> In your *filename.odata* file, you might want to first create a copy of the multiline query text and then run **OData: Combine** on the copy. You do this because there's no way to convert the single-line query back to a readable multiline query. +> In your *filename.odata* file, you might want to first create a copy of the multiline query text and then run **OData: Combine** on the copy. Do this step first because there's no way to convert the single-line query back to a readable multiline query. -In Visual Studio Code, place your query anywhere in the query text, and then select **View** > **Command Palette**. In the search box, type **odata** and then, in the results list, select **OData: Combine**. +1. In Visual Studio Code, place your cursor anywhere in the query text, and then select **View** > **Command Palette**. In the search box, enter *odata*. Then in the results list, select **OData: Combine**. -The multiline query is converted into a single-line query. + The multiline query gets converted into a single-line query. -![Visual Studio Code OData extension - Combine to single-line query](media/odataquery-combineto1line.png) + :::image type="content" source="media/odataquery-combineto1line.png" alt-text="Screenshot that shows the Visual Studio Code OData extension combined to a single-line query."::: -Copy the entire line for use in the next section. +1. Copy the entire line for use in the next section. ### Run the query from Power BI -Open Power BI, select **Get Data**, and then select the **OData feed** connector. For more information, see [Create a Power BI report with an OData query](create-quick-report-odataq.md). - -![Power BI - "OData feed" command](media/ODataQuery.png) +1. Select **Get Data** > **OData feed**. For more information, see [Create a Power BI report with an OData query](create-quick-report-odataq.md). -In the **OData feed** window, in the **URL** box, paste the OData query that you copied in the preceding section, and then select **OK**. + :::image type="content" source="media/ODataQuery.png" alt-text="Screenshot that shows the Power BI OData feed command."::: -![Power BI - OData Feed - Paste in query](media/odataquery-powerbi-odatafeed.png) +1. In the **OData feed** window, in the **URL** box, paste the OData query that you copied in the preceding section, and then select **OK**. -Power BI displays a preview page: + :::image type="content" source="media/odataquery-powerbi-odatafeed.png" alt-text="Screenshot that shows the OData feed dialog where you paste the OData query."::: -![Power BI - OData Feed - Power BI Data Preview](media/odataquery-powerbi-preview.png) + Power BI displays a preview page. + :::image type="content" source="media/odataquery-powerbi-preview.png" alt-text="Screenshot that shows the preview page for the Power BI OData feed."::: ### Specify query options -On the preview page, select **Edit** to open the Power Query Editor. +1. Select **Edit** on the preview page to open Power Query Editor. -![Power BI - OData Feed - Power Query Editor](media/odataquery-powerbi-queryeditor.png) + :::image type="content" source="media/odataquery-powerbi-queryeditor.png" alt-text="Screenshot that shows Power Query Editor open for the Power BI OData feed." lightbox="media/odataquery-powerbi-queryeditor.png"::: -In the ribbon, select **Advanced Editor**. +1. Select **Advanced Editor** on the ribbon. -![Power BI - OData Feed - Select Advanced Editor](media/AdvancedEditor.png) + :::image type="content" source="media/AdvancedEditor.png" alt-text="Screenshot that shows Advanced Editor selected for the Power BI OData feed."::: -In the **Query** pane, scroll horizontally to view the `[Implementation="2.0"]` parameter. +1. Scroll horizontally to view the `[Implementation="2.0"]` parameter in the **Query** pane. -![Power BI - OData Feed - Advanced Editor - Scroll Right](media/odataquery-powerbi-advancededitor1.png) + :::image type="content" source="media/odataquery-powerbi-advancededitor1.png" alt-text="Screenshot that shows the Power BI OData feed with the Advanced Editor scrolled to the end."::: -Replace `[Implementation="2.0"]` with the following string: +1. Replace `[Implementation="2.0"]` with the following string: -`[Implementation="2.0",OmitValues = ODataOmitValues.Nulls,ODataVersion = 4]` + `[Implementation="2.0",OmitValues = ODataOmitValues.Nulls,ODataVersion = 4]` -![Replace the string.](media/odataquery-powerbi-advancededitor2.png) + :::image type="content" source="media/odataquery-powerbi-advancededitor2.png" alt-text="Screenshot that shows the replacement string."::: -> [!NOTE] -> The following actions help accomplish this preventative measure: -> -> **Prevent throttling errors**. Power Query attempts to resolve null values as errors by generating an additional query for every null value it encounters. This can result in thousands of queries, which will quickly exceed your usage threshold, beyond which your user account will be throttled. -> -> To prevent this issue: -> - Instruct Power BI to reference OData v4. -> - Instruct the Analytics service to omit any values that are null, which improves query performance. + This change helps prevent throttling errors. The new values do the following actions: -> [!NOTE] -> The following action is required for Power BI to successfully run an OData query against the Azure DevOps Analytics Service. -> -> Select **OK** to close the Advanced Editor and return to the Power BI Power Query Editor. You can use Power Query Editor to perform these optional actions: -> - Rename the "Query1" query as something more specific. -> - Transform columns to a specific type. Power BI auto-detects the type, but you might want to convert column to a specific data type. -> - Add computed columns. -> - Remove columns. -> - Expand columns into specific fields. + - Instruct Power BI to reference OData v4. + - Instruct the Analytics service to omit any values that are null, which improves query performance. + + Power Query attempts to resolve null values as errors by generating another query for every null value it encounters. This action can result in thousands of queries. These queries can quickly exceed your usage threshold, beyond which your user account gets throttled. + +1. Select **Done** to close the Advanced Editor and return to Power BI Power Query Editor. You can use Power Query Editor to perform the following optional actions: + + - Rename the `Query1` query as something more specific. + - Transform columns to a specific type. Power BI autodetects the type, but you might want to convert columns to a specific data type. + - Add computed columns. + - Remove columns. + - Expand columns into specific fields. ### Create a report by using the data -Select **Close & Apply** to save your settings and pull the data into Power BI. After the data is refreshed, you can create a report as you would normally in Power BI. +Select **Close & Apply** to save your settings and pull the data into Power BI. After the data refreshes, you can create a report as you would normally in Power BI. -![Power BI "Close & Apply" button](media/transform-data/powerbi-close-apply.png) +:::image type="content" source="media/transform-data/powerbi-close-apply.png" alt-text="Screenshot that shows the Power BI Close and Apply button."::: ## Related articles -- [Sample Power BI Reports by using OData queries](sample-odata-overview.md) +- [Overview of sample reports using OData queries](sample-odata-overview.md) - [Data available from Analytics](data-available-in-analytics.md) -- [Grant permissions to access Analytics](./analytics-security.md) -- [Power BI integration overview](overview.md) - +- [Permissions to access Analytics and Analytics views](./analytics-security.md) +- [Power BI integration](overview.md) diff --git a/docs/report/powerbi/overview.md b/docs/report/powerbi/overview.md index d5fa431aeb5..9deefa0f885 100644 --- a/docs/report/powerbi/overview.md +++ b/docs/report/powerbi/overview.md @@ -1,192 +1,121 @@ --- title: Power BI integration and supported connections methods titleSuffix: Azure DevOps -description: Learn about the different integration options you can use to connect to Power BI to access Analytics for Azure DevOps. +description: Learn about how to access Analytics for Azure DevOps and the different integration options you can use to connect to Power BI. ms.assetid: 8026A5ED-CD58-417A-913F-72A20272E7DC ms.subservice: azure-devops-analytics ms.topic: overview ms.author: chcomley author: chcomley -monikerRange: '>=azure-devops-2019' -ms.date: 12/13/2022 +monikerRange: "<=azure-devops" +ms.date: 03/12/2025 +#customer intent: As a team leader or member, I want to understand how to pull data from analytics to use in Power BI reports. --- # About Power BI integration [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] +Power BI is a suite of business analytics tools. With Power BI, you can pull data from [Analytics](what-is-analytics.md), generate reports, and customize them to meet your needs. Use Power BI to do impromptu analysis, produce beautiful reports, and publish for enterprise consumption. -With Power BI, a suite of business analytics tools, you can pull data from [Analytics](what-is-analytics.md), generate reports, and customize them to meet your needs. Use Power BI to do impromptu analysis, produce beautiful reports, and publish for enterprise consumption. - -The integration of Power BI with Analytics enables you to go beyond the built-in Analytics reports and dashboard widgets to generate fully custom reports. +The integration of Power BI with Analytics enables you to go beyond the built-in Analytics reports and dashboard widgets to generate fully custom reports. ## Data connection methods -You can pull data from Analytics into Power BI in one of the three ways described in the following table. +You can pull data from Analytics into Power BI in three ways, described in the following table. > [!NOTE] -> OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming REST APIs. To learn more, see [OData documentation](/odata/). - -:::row::: - :::column span="1"::: - **Connection Option** - :::column-end::: - :::column span="1"::: - **Description** - :::column-end::: - :::column span="2"::: - **Considerations** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Connect using the OData queries](odataquery-connect.md) - :::column-end::: - :::column span="1"::: - Power BI can execute OData queries. OData queries are powerful and can filter and aggregate data before returning it to Power BI. - :::column-end::: - :::column span="2"::: - **This is the recommended method**, except for simpler reports on Boards data. It requires you to write OData queries, which is similar to writing SQL queries. Fortunately, we provide several [sample reports](sample-odata-overview.md) to help you get started. - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Connect using the Azure DevOps Data Connector](data-connector-connect.md) - :::column-end::: - :::column span="1"::: - The Azure DevOps Data connector works with [Analytics views](what-are-analytics-views.md). To access **Analytics views**, you must enable the feature as described in [Enable preview features](../../project/navigation/preview-features.md) - :::column-end::: - :::column span="2"::: - **This connector only works with Boards data (work items)** and doesn't support other data types, such as Pipelines. It provides a flat-list of work items, and doesn't support work item hierarchies. At this point, we have no plans to update the connector to support other types of data. We recommend using OData queries unless you have a simpler report on Boards data. - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - [Connect using the Power BI's OData Feed connector](access-analytics-power-bi.md) - :::column-end::: - :::column span="1"::: - Power BI provides an OData Feed connector that allows you to connect to and browse the Analytic's OData endpoint. It's the typical way Power BI interacts with OData feeds. You can browse and select the entities and use its Query Editor to filter the dataset. - :::column-end::: - :::column span="2"::: - **Only use this method if you have a small account.** This method doesn't support server-side query folding. All filters are applied client-side. All the data is pulled into Power BI before applying the filters. If you have a small account, it may work fine for you. However, if you have a large account, then you'll likely experience long refresh times and timeouts. - :::column-end::: -:::row-end::: +> Open Data Protocol (OData) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming REST APIs. For more information, see [OData documentation](/odata/). +| **Connection Option** | **Description** | **Considerations** | +|-----------------------|-----------------|--------------------| +| [Connect using the OData queries](odataquery-connect.md) | Power BI can execute OData queries. OData queries are powerful and can filter and aggregate data before returning it to Power BI. | **We recommend this method**, except for simpler reports on Boards data. It requires you to write OData queries, which is similar to writing SQL queries. You can review several [sample reports](sample-odata-overview.md) to help you get started. | +| [Connect using the Azure DevOps Data Connector](data-connector-connect.md) | The Azure DevOps Data connector works with [Analytics views](what-are-analytics-views.md). To access **Analytics views**, you must enable the feature as described in [Enable preview features](../../project/navigation/preview-features.md). | **This connector only works with Boards data (work items)**. It doesn't support other data types, such as Pipelines. It provides a flat-list of work items, and doesn't support work item hierarchies. There are no plans to update the connector to support other types of data. We recommend using OData queries unless you have a simpler report on Boards data. | +| [Connect using the Power BI's OData Feed connector](access-analytics-power-bi.md) | Power BI provides an OData Feed connector that allows you to connect to and browse the Analytic's OData endpoint. It's the typical way Power BI interacts with OData feeds. You can browse and select the entities and use its Query Editor to filter the dataset. | **Only use this method if you have a small account.** This method doesn't support server-side query folding. All filters are applied client-side. All the data is pulled into Power BI before applying the filters. If you have a small account, it might work well for you. If you have a large account, you might have long refresh times and time-outs. | ## Query Editor -Once you've connected data from Analytics in Power BI, you can always modify the underlying data using Power BI's **Power Query Editor** and **Advanced Editor**. Note the following operational constraints: - -- When you connect using OData queries or an OData feed, you can specify query filters, data to return, data to aggregate, and more. -- When you connect using an Analytics view, you must edit the Analytics view to modify the query filter and fields that you want to have returned. +After you connect data from Analytics in Power BI, you can modify the underlying data using Power BI's **Power Query Editor** and **Advanced Editor**. Note the following operational constraints: -For examples of reports, see [sample reports](#sample-reports) provided later in this article. +- When you connect using OData queries or an OData feed, you can specify query filters, data to return, data to aggregate, and more. +- When you connect using an Analytics view, you must edit the Analytics view to modify the query filter and fields that you want returned. +For examples of reports, see [sample reports](#sample-reports) provided later in this article. ## Transform data in Power BI -Once you've imported data into Power BI, you can use the Power Query Editor **Transform**, **Add Column**, and other menu options and tools to change the data as needed. Many of the [sample reports](#sample-reports) provided later in this article provide instructions on data transformations that you'll need to make. These instructions include some of the following operations: +After you import data into Power BI, you can use the Power Query Editor **Transform**, **Add Column**, and other menu options and tools to change the data as needed. Many of the [sample reports](#sample-reports) provided in this article give instructions on data transformations that you need to make. These instructions include some of the following operations: -- Expand data columns -- Pivot columns -- Transform a column data type -- Replace null values in column data -- Create a custom field and a calculated column +- Expand data columns +- Pivot columns +- Transform a column data type +- Replace null values in column data +- Create a custom field and a calculated column -To get familiar with these operations, see [Transform Analytics data to generate Power BI reports](transform-analytics-data-report-generation.md). +For more information, see [Transform Analytics data to generate Power BI reports](transform-analytics-data-report-generation.md). +## Data Analysis Expressions -## Data Analysis Expressions (DAX) +Power BI supports creating new information from data already in your data model using Data Analysis Expressions (DAX). DAX provides a collection of functions, operators, and constants that you can use in a formula to calculate and return one or more values. -Power BI supports creating new information from data already in your data model using DAX. DAX provides a collection of functions, operators, and constants that you can use in a formula to calculate and return one or more values. +For an Analytics sample report that uses DAX, see [Add a time-in-state measure to your Power BI report](create-timeinstate-report.md). -For an Analytics sample report that uses DAX, see [Calculate time-in-state for an existing Analytics view](create-timeinstate-report.md). +For more information, see [Learn DAX basics in Power BI Desktop](/power-bi/transform-model/desktop-quickstart-learn-dax-basics). -To learn more about DAX, see [Learn DAX basics in Power BI Desktop](/power-bi/transform-model/desktop-quickstart-learn-dax-basics). +## Report visualizations, filters, sort operations +After you make any data transformations required for your report, use the **Visualizations** pane to craft changes in your report. You can drag column fields onto the **Visualizations** pane. You can then use the **Filters** pane to filter all or select data based on one or more fields. -## Report visualizations, filters, sort operations - -After you've made any data transformations required for your particular report, you craft your report using the **Visualizations** pane, dragging column fields onto the **Visualizations** pane. You can then use the **Filters** pane to filter all or select data based on one or more fields. - -To quickly get familiar with these Power BI basic features, see the following Power BI articles: -- [Visualization types in Power BI](/power-bi/visuals/power-bi-visualization-types-for-reports-and-q-and-a) -- [Visualizations in Power BI reports](/power-bi/visuals/power-bi-report-visualizations) -- [Take a tour of the report Filters pane](/power-bi/consumer/end-user-report-filter) - +To quickly get familiar with these Power BI basic features, see the following Power BI articles: +- [Learn about Visualization types in Power BI](/power-bi/visuals/power-bi-visualization-types-for-reports-and-q-and-a) +- [Customize the Visualization pane](/power-bi/visuals/power-bi-report-visualizations) +- [Take a tour of the report Filters pane](/power-bi/consumer/end-user-report-filter) ## Sample reports -Several sample reports are provided to show how to generate reports from either an Analytics view or OData query. +Several sample reports show how to generate reports from either an Analytics view or OData query. ### Sample reports using Analytics view -- [Active bugs report](active-bugs-sample-report.md) +- [Get active bugs report](active-bugs-sample-report.md) - [Get a count of work items](data-connector-examples.md) -- [Add a last refresh date](add-last-refresh-time.md) -- [Filter on teams](create-team-filter.md) -- [Calculate time-in-state for an existing Analytics view](create-timeinstate-report.md) +- [Add a last refresh date](add-last-refresh-time.md) +- [Filter on teams](create-team-filter.md) +- [Add a time-in-state measure to your Power BI report](create-timeinstate-report.md) ### Sample reports using OData queries -To get started using OData queries in Power BI reports, see [Overview of sample reports using OData queries](sample-odata-overview.md). For specific examples, see one of the following articles: - +To get started using OData queries in Power BI reports, see [Overview of sample reports using OData queries](sample-odata-overview.md). For specific examples, see the following articles: ::: moniker range=">= azure-devops-2020" ---- -:::row::: - :::column span="1"::: - **Azure Boards** - :::column-end::: - :::column span="1"::: - **Azure Test Plans** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [!INCLUDE [temp](includes/sample-fulllist.md)] - :::column-end::: - :::column span="1"::: - [!INCLUDE [temp](includes/sample-full-list-test-plans.md)] - :::column-end::: -:::row-end::: ---- - -[!INCLUDE [temp](includes/sample-full-list-pipelines.md)] - ---- -::: moniker-end - -::: moniker range="azure-devops-2019" -[!INCLUDE [temp](includes/sample-fulllist.md)] +|Service |Sample reports | +|------------------|---------------------| +|**Azure Boards**|[!INCLUDE [boards samples](includes/sample-fulllist.md)]| +|**Azure Test Plans** | [!INCLUDE [test plans samples](includes/sample-full-list-test-plans.md)] | +|**Azure Pipelines** |[!INCLUDE [pipeline samples](includes/sample-full-list-pipelines.md)]| ::: moniker-end -All sample report articles provide the following sections and information: +All sample report articles provide the following sections and information: -* **Sample queries** - The Power BI Query and raw OData query used to pull data into Power BI along with other sample queries. -* **Transform data in Power BI** - Steps to transform the data into a reportable format -* **Create the report** - Steps to create a report from the data. +- **Sample queries**: The Power BI Query and raw OData query used to pull data into Power BI along with other sample queries. +- **Transform data in Power BI**: Steps to transform the data into a reportable format. +- **Create the report**: Steps to create a report from the data. -## Power BI extensions +## Power BI extensions The following Marketplace extensions are available to support Power BI integration with Analytics. -- [WIQL to OData](https://marketplace.visualstudio.com/items?itemName=ms-eswm.wiql-to-odata) translates an Azure DevOps work item query into an OData query for use with Azure DevOps Analytics OData endpoints. This can be useful for beginners to initiate a simple OData query. -- [vscode-odata](https://marketplace.visualstudio.com/items?itemName=stansw.vscode-odata) extension adds rich language support to Visual Studio Code for the OData query language. - - +- [(WIQL to OData)](https://marketplace.visualstudio.com/items?itemName=ms-eswm.wiql-to-odata) translates an Azure DevOps work item query into an OData query for use with Azure DevOps Analytics OData endpoints, which can be useful to as a simple OData query. +- [vscode-odata](https://marketplace.visualstudio.com/items?itemName=stansw.vscode-odata) extension adds rich language support to Visual Studio Code for the OData query language. ## Related articles - [Dashboards](../dashboards/dashboards.md) -- [Extend Analytics with OData](../extend-analytics/quick-ref.md) -- [Dashboards, charts, reports & widgets](../dashboards/overview.md) -- [Power BI Desktop](/power-bi/fundamentals/desktop-get-the-desktop) +- [Sample reports and quick reference index](../extend-analytics/quick-ref.md) +- [Dashboards, charts, reports & widgets](../dashboards/overview.md) +- [Power BI Desktop](/power-bi/fundamentals/desktop-get-the-desktop) - [Power BI documentation](/power-bi) - [OData documentation](/odata/) - \ No newline at end of file diff --git a/docs/report/powerbi/performance-latency.md b/docs/report/powerbi/performance-latency.md index 326042b2dc8..04720b95e1c 100644 --- a/docs/report/powerbi/performance-latency.md +++ b/docs/report/powerbi/performance-latency.md @@ -6,11 +6,10 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 10/05/2021 --- - # Performance and latency of Analytics [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] @@ -19,14 +18,6 @@ ms.date: 10/05/2021 [!INCLUDE [temp](../includes/analytics-preview.md)] -::: moniker range="azure-devops-2019" - -## Install or enable Analytics - -When you [enable or install Analytics](../dashboards/analytics-extension.md) for a project collection, expect the initial setup to take between 5 and 30 minutes. After 24 hours, if you aren't able to access your data, contact [Microsoft Support](../../user-guide/provide-feedback.md?bc=%252fazure%252fdevops%252fuser-guide%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fuser-guide%252ftoc.json). - -::: moniker-end - ## Data latency When you use Analytics, you query a curated copy of the data stored in Azure DevOps. The data copy helps optimize read and aggregation performance, and greatly reduces the effect reporting scenarios have on Azure DevOps. diff --git a/docs/report/powerbi/publish-power-bi-desktop-to-power-bi.md b/docs/report/powerbi/publish-power-bi-desktop-to-power-bi.md index 9a3c9e8e03e..7ebb27c1d40 100644 --- a/docs/report/powerbi/publish-power-bi-desktop-to-power-bi.md +++ b/docs/report/powerbi/publish-power-bi-desktop-to-power-bi.md @@ -6,7 +6,7 @@ ms.subservice: azure-devops-analytics ms.topic: how-to ms.assetid: C03A04EC-F011-4043-A38E-5C5394F777CE ms.author: chcomley -monikerRange: '>=azure-devops-2019' +monikerRange: "<=azure-devops" author: chcomley ms.date: 10/05/2021 --- @@ -17,6 +17,10 @@ ms.date: 10/05/2021 Once you've [created a Power BI Desktop file](access-analytics-power-bi.md) and the associated datasets, measures, and charts, you can share them with others by creating a dashboard on Power BI. This article shows you how. +## Prerequisites + +[!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] + ## Publish to Power BI 1. If using an [Analytics view](what-are-analytics-views.md), verify that the view is Shared and not Private. @@ -51,7 +55,7 @@ Once you've [created a Power BI Desktop file](access-analytics-power-bi.md) and 1. Select the appropriate authentication option. - * Use **oAuth2** for Azure Active Directory (Azure AD) or Windows credentials. + * Use **oAuth2** for Microsoft Entra ID or Windows credentials. This is the recommended approach. ![Configure Areas dialog](media/aad-auth-power-bi.png) @@ -69,12 +73,8 @@ At this point, the data will update on your scheduled basis using the credential > [!IMPORTANT] > Any data included in the Analytics view and published Power BI will be accessible to all users with access to the report, regardless of the project permissions configured in Azure DevOps. - ## Related articles - [About Power BI integration](overview.md) -- [Authenticate your identity with personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) - [Access data through Excel](access-analytics-excel.md) - [Access data through Power BI desktop](access-analytics-power-bi.md) - - diff --git a/docs/report/powerbi/reporting-roadmap.md b/docs/report/powerbi/reporting-roadmap.md index 66c6e502ed9..e2ec42d6038 100644 --- a/docs/report/powerbi/reporting-roadmap.md +++ b/docs/report/powerbi/reporting-roadmap.md @@ -35,20 +35,11 @@ Analytics is generally available for Azure DevOps Services and Azure DevOps Serv ::: moniker-end - -::: moniker range="<= azure-devops-2019" - -Analytics is in Public Preview for Azure DevOps Server 2019 and later versions. You gain access to it by [enabling or installing Analytics](../dashboards/analytics-extension.md). Analytics provides several [advanced widgets](../dashboards/analytics-widgets.md), [Power BI integration](overview.md), and access to the [OData feed](../extend-analytics/quick-ref.md). - -Team Foundation Server (TFS) 2018 and earlier versions don't support Analytics. - -::: moniker-end - -To learn more, see [What is Analytics](what-is-analytics.md). It currently contains partial data. We're working to add all reportable data to Analytics. For more information, see [Data Available in Analytics](data-available-in-analytics.md). +For more information, see [What is Analytics](what-is-analytics.md). It currently contains partial data. We're working to add all reportable data to Analytics. For more information, see [Data Available in Analytics](data-available-in-analytics.md). ## Azure DevOps Server, TFS, and SQL Server Reporting -Since [Team Foundation Server (TFS)](https://visualstudio.microsoft.com/tfs/) was released in 2005, we've offered a reporting solution [based on a data warehouse and OLAP cube](/previous-versions/azure/devops/report/sql-reports/reporting-services-reports), coupled with [a SQL Server Reposrting Services server](/previous-versions/azure/devops/report/sql-reports/create-and-manage-reporting-services-reports) to host reports. +Since [Team Foundation Server (TFS)](https://visualstudio.microsoft.com/tfs/) was released in 2005, we've offered a reporting solution [based on a data warehouse and OLAP cube](/previous-versions/azure/devops/report/sql-reports/reporting-services-reports), coupled with [a SQL Server Reporting Services server](/previous-versions/azure/devops/report/sql-reports/create-and-manage-reporting-services-reports) to host reports. ![TFS Data warehouse architecture conceptual diagram](../sql-reports/media/datawarehouse-architecture.png) diff --git a/docs/report/powerbi/sample-boards-bugtrend.md b/docs/report/powerbi/sample-boards-bugtrend.md index f582bdca77c..315e3f4ee19 100644 --- a/docs/report/powerbi/sample-boards-bugtrend.md +++ b/docs/report/powerbi/sample-boards-bugtrend.md @@ -7,7 +7,7 @@ ms.author: chcomley ms.custom: powerbisample, engagement-fy23, engagement-fy23 author: chcomley ms.topic: sample -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 12/08/2022 --- @@ -24,7 +24,6 @@ Bug trend reports are useful to see how well a team is closing active bugs. This [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] - ## Sample queries The following queries return data from the `WorkItemSnapshot` entity set to support generating trend reports. @@ -88,7 +87,6 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor - ### Query breakdown The following table describes each part of the query. @@ -183,12 +181,10 @@ The following table describes each part of the query. :::row-end::: - ### Bug trend filtered by Teams You can query for bug trends by team name rather than Area Path. - #### [Power BI query](#tab/powerbi/) [!INCLUDE [temp](includes/sample-powerbi-query.md)] @@ -279,7 +275,7 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor *** - + ### Bug trend with a snapshot on the first of every month @@ -335,15 +331,12 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor Expand the `Area/AreaPath` and `Iteration/IterationPath` columns. Expanding the columns flattens the record into specific fields. To learn how, see [Transform Analytics data to generate Power BI reports](transform-analytics-data-report-generation.md). - ## (Optional) Rename fields Once you've expanded the columns, you may want to rename one or more fields. For example, you can rename the column `AreaPath` to `Area Path`. To learn how, see [Rename column fields](transform-analytics-data-report-generation.md#rename-column-fields). - [!INCLUDE [temp](includes/close-apply.md)] - ## Create the Line chart report 1. In Power BI, choose the **Line chart** report under **Visualizations**. @@ -366,8 +359,7 @@ The example report displays. :::image type="content" source="media/reports-boards/bug-trends-change-color.png" alt-text="Screenshot of Power BI Format visual selections for Bug trends report. "::: -To learn more, see [Get started with the formatting pane](/power-bi/visuals/service-getting-started-with-color-formatting-and-axis-properties). - +For more information, see [Get started with the formatting pane](/power-bi/visuals/service-getting-started-with-color-formatting-and-axis-properties). ## Related articles diff --git a/docs/report/powerbi/sample-boards-cfd.md b/docs/report/powerbi/sample-boards-cfd.md index 0f8ff07e25c..5aee544b449 100644 --- a/docs/report/powerbi/sample-boards-cfd.md +++ b/docs/report/powerbi/sample-boards-cfd.md @@ -7,7 +7,7 @@ ms.author: chcomley ms.custom: powerbisample, engagement-fy23 author: chcomley ms.topic: sample -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 12/08/2022 --- @@ -15,13 +15,13 @@ ms.date: 12/08/2022 [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -This article shows you how to display the Stories CFD for a specified team. This data is also available through the built-in chart and dashboard widget. To learn more about these options, see [View and configure a Cumulative Flow Diagram](../dashboards/cumulative-flow.md). +This article shows you how to display the Stories CFD for a specified team. This data is also available through the built-in chart and dashboard widget. For more information about these options, see [View and configure a Cumulative Flow Diagram](../dashboards/cumulative-flow.md). An example is shown in the following image that shows a count of user stories over time in the *Researching*, *Committed*, *In Progress*, and *In Review* states. Hovering over a date provides information on data for that date. -:::image type="content" source="media/reports-boards/cfd-stacked-area-chart-sorted.png" alt-text="Screenshot of Power BI Cumulative Flow stacked area chart report, columns sorted in Kanban board column order."::: +:::image type="content" source="media/reports-boards/cfd-stacked-area-chart-sorted.png" alt-text="Screenshot of Power BI Cumulative Flow stacked area chart report, columns sorted in board column order."::: -To learn more about cumulative flow, see [Cumulative flow, lead time, and cycle time guidance](../dashboards/cumulative-flow-cycle-lead-time-guidance.md) and [Cumulative flow, lead time, and cycle time guidance](../dashboards/cumulative-flow-cycle-lead-time-guidance.md). +For more information about cumulative flow, see [Cumulative flow, lead time, and cycle time guidance](../dashboards/cumulative-flow-cycle-lead-time-guidance.md) and [Cumulative flow, lead time, and cycle time guidance](../dashboards/cumulative-flow-cycle-lead-time-guidance.md). [!INCLUDE [temp](includes/sample-required-reading.md)] @@ -29,12 +29,10 @@ To learn more about cumulative flow, see [Cumulative flow, lead time, and cycle ## Sample queries -Queries in this section support returning cumulative flow data for User Stories. These queries specify the `WorkItemBoardSnapshot` entity set as they return data calculated for the Kanban board over time. - +Queries in this section support returning cumulative flow data for User Stories. These queries specify the `WorkItemBoardSnapshot` entity set as they return data calculated for the board over time. [!INCLUDE [temp](includes/query-filters-work-items.md)] - #### [Power BI query](#tab/powerbi/) [!INCLUDE [temp](includes/sample-powerbi-query.md)] @@ -83,7 +81,6 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/V3.0-preview/Wor * `{teamname}` - The name of the team to display CFD data - `{startdate}` - Start your report for items completed on or after a given date with the format: `YYYY-MM-DDZ`. For example: `2022-04-01Z` represents 2022-April-01. Don't enclose in quotes. - ### Query breakdown The following table describes each part of the query. @@ -170,26 +167,19 @@ The following table describes each part of the query. :::column-end::: :::row-end::: - - [!INCLUDE [temp](includes/rename-query.md)] - ## Expand columns in Power Query Editor From the Power Query Editor, choose the query with the data you want to transform. For a CFD chart, you'll need to expand the `Area`, `Iteration`, and `AssignedTo` columns. To learn how, see the following sections in [Transform Analytics data to generate Power BI reports, Expand columns](transform-analytics-data-report-generation.md#expand-columns). - ## (Optional) Rename fields Once you've expanded the columns, you may want to rename one or more fields. For example, you can rename the column `AreaPath` to `Area Path`. To learn how, see [Rename column fields](transform-analytics-data-report-generation.md#rename-column-fields). - [!INCLUDE [temp](includes/close-apply.md)] - - ## Create the stacked area chart In the following example, the query was renamed to *CFD*, but no columns were renamed. @@ -208,14 +198,13 @@ In the following example, the query was renamed to *CFD*, but no columns were re :::image type="content" source="media/reports-boards/cfd-columnname-filters.png" alt-text="Screenshot of Power BI Filters for ColumnName. "::: - -The example report displays the columns in alphabetic order. However, the preferred order is to sort the data according to the Kanban column order, or progressive order. +The example report displays the columns in alphabetic order. However, the preferred order is to sort the data according to the column order, or progressive order. :::image type="content" source="media/reports-boards/cfd-stacked-area-chart.png" alt-text="Screenshot of Sample Power BI Cumulative Flow stacked area chart report, columns sorted in alphabetic order."::: ### Sort columns in progressive order -To sort the chart columns in the order specific on the Kanban board, do the following steps: +To sort the chart columns in the order specific on the board, do the following steps: 1. Create a new query in Power BI per the following queries. When done, rename the query to *ColumnOrder*. @@ -265,15 +254,13 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/V3.0-preview/Boa 1. In the report created above, in the **Legend**, replace `CFD.ColumnName` with `ColumnOrder.ColumnName` to **Legend**. - The report refreshes with columns sorted in the same order used by the Kanban board. - - :::image type="content" source="media/reports-boards/cfd-stacked-area-chart-sorted.png" alt-text="Screenshot of Sample Power BI Cumulative Flow stacked area chart report, columns sorted in Kanban board column order."::: + The report refreshes with columns sorted in the same order used by the board. + :::image type="content" source="media/reports-boards/cfd-stacked-area-chart-sorted.png" alt-text="Screenshot of Sample Power BI Cumulative Flow stacked area chart report, columns sorted in board column order."::: > [!NOTE] > If any work items were in a column that has since been deleted, they will appear as "Blank" in the above report. - ## Related articles [!INCLUDE [temp](includes/sample-relatedarticles.md)] diff --git a/docs/report/powerbi/sample-boards-directlinks.md b/docs/report/powerbi/sample-boards-directlinks.md index ab6ec26ca8d..7d9de4a7ea6 100644 --- a/docs/report/powerbi/sample-boards-directlinks.md +++ b/docs/report/powerbi/sample-boards-directlinks.md @@ -7,7 +7,7 @@ ms.author: chcomley ms.custom: powerbisample, engagement-fy23 author: chcomley ms.topic: sample -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 10/08/2021 --- @@ -19,8 +19,7 @@ This article shows you how to create a report that lists work items linked to ot :::image type="content" source="media/reports-boards/parent-child-links-table-report.png" alt-text="Screenshot of Parent-child links of Features and User Stories table report."::: -To learn more about link types and linking work items, see [Link user stories, issues, bugs, and other work items](../../boards/backlogs/add-link.md). - +For more information about link types and linking work items, see [Link user stories, issues, bugs, and other work items](../../boards/backlogs/add-link.md). Other sample queries include listing bugs with a Duplicate link to another bug, and listing bugs that don't contain a Duplicate link to another bug. @@ -34,7 +33,6 @@ Several queries are provided which show how to filter linked work items. All of [!INCLUDE [temp](includes/query-filters-work-items.md)] - ### Return Features and their child User Stories [!INCLUDE [temp](includes/sample-powerbi-query.md)] @@ -61,7 +59,6 @@ in Source ``` - #### [OData query](#tab/odata/) [!INCLUDE [temp](includes/sample-odata-query.md)] @@ -91,7 +88,6 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor - `{project}` - Your team project name, or omit "/{project}" entirely, for a cross-project query - `{areapath}` - Your Area Path. Example format: `Project\Level1\Level2`. - ### Query breakdown The following table describes each part of the query. @@ -197,7 +193,6 @@ The following table describes each part of the query. [!INCLUDE [temp](includes/sample-powerbi-query.md)] - #### [Power BI query](#tab/powerbi/) ``` @@ -372,11 +367,8 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor *** - - [!INCLUDE [temp](includes/rename-query.md)] - ## Transform data in Power Query Editor Prior to creating the report, you'll need to expand columns that return records containing several fields. In this instance, you'll want to expand the following records: @@ -401,7 +393,6 @@ In this example, the following fields have been renamed: | Links.TargetWorkItem.State | Target State | | Links.TargetWorkItem.Title | Target Title | - [!INCLUDE [temp](includes/close-apply.md)] ## Create a table report to list linked work items diff --git a/docs/report/powerbi/sample-boards-featureprogress.md b/docs/report/powerbi/sample-boards-featureprogress.md index f6846f87612..e20113d5ce5 100644 --- a/docs/report/powerbi/sample-boards-featureprogress.md +++ b/docs/report/powerbi/sample-boards-featureprogress.md @@ -7,7 +7,7 @@ ms.author: chcomley ms.custom: powerbisample, engagement-fy23 author: chcomley ms.topic: sample -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 12/08/2022 --- @@ -25,7 +25,6 @@ You can view similar progress bar charts from your backlog by adding a rollup co [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] - ## Sample queries Feature progress queries the `WorkItems` entity to get the current state of progress. @@ -83,13 +82,10 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor - `{project}` - Your team project name, or omit `/{project}` entirely, for a cross-project query - `{areapath}` - Your Area Path. Example format: `Project/Level1/Level2`. - ### Query breakdown - The following table describes each part of the query. - :::row::: :::column span="1"::: **Query part** @@ -262,7 +258,6 @@ To learn how, see the following sections in [Transform Analytics data to generat > [!NOTE] > In this example, the **State** values for **User Story** include **Proposed**, **In Progress**, and **Completed**. - [!INCLUDE [temp](includes/close-apply.md)] ## Create the stacked bar chart report diff --git a/docs/report/powerbi/sample-boards-leadcycletime.md b/docs/report/powerbi/sample-boards-leadcycletime.md index 95623069f2a..06078b94652 100644 --- a/docs/report/powerbi/sample-boards-leadcycletime.md +++ b/docs/report/powerbi/sample-boards-leadcycletime.md @@ -7,7 +7,7 @@ ms.author: chcomley ms.custom: powerbisample, engagement-fy23 author: chcomley ms.topic: sample -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 12/08/2022 --- @@ -21,8 +21,7 @@ The following image shows an example for average lead time broken down by priori :::image type="content" source="media/reports-boards/lead-time-trend-chart.png" alt-text="Screenshot of Power BI Lead Cycle Time trend chart report."::: -To learn more about lead and cycle time, see [Lead Time and Cycle Time widgets](../dashboards/cycle-time-and-lead-time.md) and [Cumulative flow, lead time, and cycle time guidance](../dashboards/cumulative-flow-cycle-lead-time-guidance.md). - +For more information about lead and cycle time, see [Lead Time and Cycle Time widgets](../dashboards/cycle-time-and-lead-time.md) and [Cumulative flow, lead time, and cycle time guidance](../dashboards/cumulative-flow-cycle-lead-time-guidance.md). [!INCLUDE [temp](includes/sample-required-reading.md)] @@ -32,7 +31,6 @@ To learn more about lead and cycle time, see [Lead Time and Cycle Time widgets]( Queries in this section support returning lead and cycle time data for completed User Stories. You can query by area path or team name(s). All of these queries specify the `WorkItems` entity set as they return data calculated for each work item by the Analytics service. - [!INCLUDE [temp](includes/query-filters-work-items.md)] ### Return Lead Time and Cycle Time for User Stories and Area Path @@ -82,7 +80,6 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor - `{areapath}` - Your Area Path. Example format: `Project\Level1\Level2` - `{startdate}` - Start your report for items completed on or after a given date with the format: `YYYY-MM-DDZ`. For example: `2022-04-01Z` represents 2022-April-01. Don't enclose in quotes. - ### Query breakdown The following table describes each part of the query. @@ -155,7 +152,6 @@ The following table describes each part of the query. :::column-end::: :::row-end::: - ### Return Lead Time and Cycle Time for User Stories and teams This query is the same as the one provided in the previous section, except it filters by several team names rather than area paths. @@ -237,8 +233,6 @@ The example report displays. Note that as you hover over any area in the report, [!INCLUDE [temp](includes/sample-relatedarticles.md)] - - - diff --git a/docs/report/powerbi/sample-boards-openbugs.md b/docs/report/powerbi/sample-boards-openbugs.md index 9e451c0d9f5..56ef0553c77 100644 --- a/docs/report/powerbi/sample-boards-openbugs.md +++ b/docs/report/powerbi/sample-boards-openbugs.md @@ -7,7 +7,7 @@ ms.custom: powerbisample, engagement-fy23 ms.author: chcomley author: chcomley ms.topic: sample -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 12/05/2022 --- @@ -23,7 +23,6 @@ To generate a report that lists open bugs or user stories, select the Matrix rep [!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] - ## Sample queries Several queries are provided which filter bugs or user stories by area path, iteration path, or team. All of these queries specify the `WorkItems` entity set as they return current and not historical data. @@ -72,7 +71,6 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor - `{project}` - Your team project name, or omit "/{project}" entirely, for a cross-project query - `{areapath}` - Your Area Path. Example format: `Project\Level1\Level2` - ### Query breakdown The following table describes each part of the query. @@ -126,7 +124,6 @@ The following table describes each part of the query. :::column-end::: :::row-end::: - ### User stories filtered by teams You can query for open bugs by one or more teams rather than Area Path. @@ -140,7 +137,7 @@ let Source = OData.Feed ("https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/WorkItems?" &"$filter=WorkItemType eq 'Bug' " &"and StateCategory ne 'Completed'' " - &"and (Teams/any(x:x/TeamName eq '{teamname}') or Teams/any(x:x/TeamName eq '{teamname}') or Teams/any(x:x/TeamName eq '{teamname}') " + &"and (Teams/any(x:x/TeamName eq '{teamname}') or Teams/any(x:x/TeamName eq '{teamname}') or Teams/any(x:x/TeamName eq '{teamname}')) " &"&$select=WorkItemId,Title,WorkItemType,State,Priority,Severity,TagNames,AreaSK " &"&$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath) " ,null, [Implementation="2.0",OmitValues = ODataOmitValues.Nulls,ODataVersion = 4]) @@ -156,7 +153,7 @@ in https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/WorkItems? $filter=WorkItemType eq 'Bug' and StateCategory ne 'Completed' - and (Teams/any(x:x/TeamName eq '{teamname}') or Teams/any(x:x/TeamName eq '{teamname}') or Teams/any(x:x/TeamName eq '{teamname}') + and (Teams/any(x:x/TeamName eq '{teamname}') or Teams/any(x:x/TeamName eq '{teamname}') or Teams/any(x:x/TeamName eq '{teamname}')) &$select=WorkItemId,Title,WorkItemType,State,Priority,Severity,TagNames,AreaSK &$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath) ``` @@ -199,10 +196,8 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor *** - [!INCLUDE [temp](includes/rename-query.md)] - ## Expand columns in Power Query Editor The `&$expand=AssignedTo($select=UserName), Iteration($select=IterationPath), Area($select=AreaPath)` clause returns records that contain several fields. Prior to creating the report, you need to expand the record to flatten it into specific fields. In this instance, you'll want to expand the following records: @@ -219,7 +214,6 @@ Once you've expanded the columns, you may want to rename one or more fields. For [!INCLUDE [temp](includes/close-apply.md)] - ## Create the Matrix report 1. In Power BI, choose the **Matrix** report under **Visualizations**. @@ -234,7 +228,6 @@ The example report displays. :::image type="content" source="media/reports-boards/open-bugs-report.png" alt-text="Screenshot of Sample Open Bugs matrix report."::: - ## Related articles [!INCLUDE [temp](includes/sample-relatedarticles.md)] diff --git a/docs/report/powerbi/sample-boards-releaseburndown.md b/docs/report/powerbi/sample-boards-releaseburndown.md index 8e95e939c28..c7f89f6519d 100644 --- a/docs/report/powerbi/sample-boards-releaseburndown.md +++ b/docs/report/powerbi/sample-boards-releaseburndown.md @@ -7,7 +7,7 @@ ms.custom: powerbisample, engagement-fy23 ms.author: chcomley author: chcomley ms.topic: sample -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 12/08/2022 --- @@ -23,8 +23,7 @@ Burndown charts only make sense if you plan your work for the time period of the [!INCLUDE [note-delete-area-paths](../../boards/includes/note-delete-area-paths.md)] -To learn more about burndown and burnup, see [Configure a burndown or burnup widget](../dashboards/configure-burndown-burnup-widgets.md) and [Burndown and burnup guidance](../dashboards/burndown-guidance.md). - +For more information about burndown and burnup, see [Configure a burndown or burnup widget](../dashboards/configure-burndown-burnup-widgets.md) and [Burndown and burnup guidance](../dashboards/burndown-guidance.md). [!INCLUDE [temp](includes/sample-required-reading.md)] @@ -98,12 +97,10 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor - `{startdate}` - The date to start the burndown report with the format: `YYYY-MM-DDZ`. For example: `2022-04-01Z` represents 2022-April-01. Don't enclose in quotes. - `{enddate}` - The date to end the burndown report. - ### Query breakdown The following table describes each part of the query. - :::row::: :::column span="1"::: **Query part** @@ -201,7 +198,6 @@ The following table describes each part of the query. :::column-end::: :::row-end::: - ### Burndown of User Stories for a team The following query returns burndown data filtered by team name rather than **Area Path**. @@ -300,7 +296,6 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor *** - ### Burndown User Stories based on an area and iteration path Some organizations use **Iteration Paths** to mark Stories for a release. For example, they may have an **Iteration Path** of *MyProject\Release1*. The following query shows how to select User Stories by Iteration Path. @@ -399,11 +394,8 @@ https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/Wor * * * - - [!INCLUDE [temp](includes/rename-query.md)] - ## Expand columns in Power Query Editor Prior to creating the report, you'll need to expand columns that return records containing several fields. In this instance, you'll want to expand the following records: @@ -417,7 +409,6 @@ To learn how to expand work items, see [Transform Analytics data to generate Pow [!INCLUDE [temp](includes/close-apply.md)] - ## Create the clustered column chart 1. In Power BI, choose **Clustered column chart** under **Visualizations**. @@ -440,7 +431,6 @@ The example report displays burndown on both the count of Stories and sum or **S [!INCLUDE [temp](includes/sample-relatedarticles.md)] - -An Analytics view provides a simplified way to specify the filter criteria for a Power BI report based on Analytics data. **Analytics views** only support Azure Boards data (work items). Analytics views don't support other data types, such as pipelines and tests. Each view corresponds to a flat-list of work items. Work item hierarchies aren't supported. - +An *Analytics view* provides a simplified way to specify the filter criteria for a Power BI report based on Analytics data. Analytics views support Azure Boards data. Each view corresponds to a flat-list of work items. Work item hierarchies aren't supported. -[!INCLUDE [temp](includes/analytics-views-warning.md)] +[!INCLUDE [analytics views warning](includes/analytics-views-warning.md)] -You can use a default Analytics view or [create a custom view](analytics-views-create.md). You create custom views in the web portal for Azure DevOps. Once you've defined a view that supports the data of interest, you can then open the view using [Power BI Data Connector](data-connector-connect.md) to create a report. +You can use a default Analytics view or [create a custom view](analytics-views-create.md). Create custom views in the web portal for Azure DevOps. After you define a view that supports the data of interest, you can then open the view using [Power BI Data Connector](data-connector-connect.md) to create a report. -[!INCLUDE [prerequisites-simple](../includes/analytics-prerequisites-simple.md)] +## Prerequisites -Users with Stakeholder access have no access to view or edit Analytics views. +[!INCLUDE [prerequisites simple](../includes/analytics-prerequisites-simple.md)] -[!INCLUDE [temp](../includes/boards-disabled.md)] +Users with Stakeholder access don't have access to view or edit Analytics views. +[!INCLUDE [boards disabled note](../includes/boards-disabled.md)] ## Default Analytics views -A set of default Analytics views are provided. The default views and are immediately accessible from Power BI. The view you select determines the set of records, fields, and history that is pulled into Power BI. - -::: moniker range="azure-devops" -> [!NOTE] -> To access **Analytics views**, you must enable the **Analytics views** preview feature as described in [Manage or enable features](../../project/navigation/preview-features.md). -::: moniker-end - +Azure DevOps provides default Analytics views. The default views are immediately accessible from Power BI. The view you select determines the set of records, fields, and history to pull into Power BI. -Here we show the default views created for a project based on the Agile process. To learn how to open this view in your web portal, see [Manage Analytics views](analytics-views-manage.md). +The following screenshot shows the default views created for a project based on the Agile process. For more information, see [Manage Analytics views](analytics-views-manage.md). -> [!div class="mx-imgBorder"] -> ![Screenshot of default Analytics views](./media/default-views/default-views.png) +:::image type="content" source="./media/default-views/default-views.png" alt-text="Screenshot shows the default Analytics views available in Azure Boards."::: -[!INCLUDE [temp](../includes/analytics-image-differences.md)] +[!INCLUDE [labels for default analytics differences](../includes/analytics-image-differences.md)] When you use the Power BI Data Connector, these same default views appear in the Navigator dialog. The view you select determines the set of records, fields, and history that is loaded into Power BI. ::: moniker range="azure-devops" -![Screenshot of Power BI Azure DevOps Connector.](media/pbi-getstarted-123.png) +1. Select **Azure DevOps** as your data connector. -::: moniker-end + :::image type="content" source="./media/get-data-connector.png" alt-text="Screenshot shows the Get Data dialog box where you can select Azure DevOps."::: + +1. Enter your account information. + + :::image type="content" source="./media/enter-account.png" alt-text="Screenshot shows the Azure DevOps dialog box where you can enter your organization and project."::: -::: moniker range=">= azure-devops-2019 < azure-devops" +1. Select the data that you want to use. -![Screenshot of Power BI Azure DevOps Server Connector.](media/pbi-getstarted-123-onprem.png) + :::image type="content" source="./media/navigator-select-data.png" alt-text="Screenshot shows the Navigator dialog box where you can select the data to pull into Power BI Desktop."::: ::: moniker-end -### Options for work item types and historical data +::: moniker range=" [!div class="mx-tdCol2BreakAll"] -> |Work item type option | Description | -> |------|---------| -> | Bugs | Load current or historical state of Bugs only | -> | Requirement Backlog | Load current or historical state of Stories, Backlog Items or Requirements | -> | Tasks | Load current or historical state of Tasks -> | Work Items | Load current or historical state of all work items | + :::image type="content" source="./media/enter-server.png" alt-text="Screenshot shows the Azure DevOps Server dialog box where you can enter your URL and project."::: +1. Select the data that you want to use. -> [!div class="mx-tdCol2BreakAll"] -> |Historical option | Description | -> |------|---------| -> | Today | Loads only the most recent revision for each work item | -> | Last 30 days | Loads work item history for the last 30 days, on a daily interval | -> | Last 26 weeks | Loads work item history for the last 26 weeks, on a weekly interval | -> | All history by month | Loads all work item history, on a monthly interval | + :::image type="content" source="./media/navigator-select-data.png" alt-text="Screenshot shows the Navigator dialog box where you can select the data to pull into Power BI Desktop."::: +::: moniker-end + +### Options for work item types and historical data + +Default Analytics views work well for customers with small datasets. Each default Analytics view provides a combination of options for work item types and historical data. The following tables describe each set of options. + +| Work item type option | Description | +|:------|:---------| +| Bugs | Load current or historical state of Bugs only | +| Requirement Backlog | Load current or historical state of Stories, Backlog Items, or Requirements | +| Tasks | Load current or historical state of Tasks | +| Work Items | Load current or historical state of all work items | + +| Historical option | Description | +|:------|:---------| +| Today | Loads only the most recent revision for each work item | +| Last 30 days | Loads work item history for the last 30 days, on a daily interval | +| Last 26 weeks | Loads work item history for the last 26 weeks, on a weekly interval | +| All history by month | Loads all work item history, on a monthly interval | -### When a default view doesn't meet your needs +### When a default view doesn't meet your needs -The default Analytics views return all the specified data in a project. They work well for customers with smaller datasets. For larger datasets, the amount of data generated by a default view may be too large for Power BI to load. +The default Analytics views return all the specified data in a project. They work well for customers with smaller datasets. For larger datasets, the amount of data generated by a default view might be too large for Power BI to load. In these cases, you can [create a custom Analytics view](analytics-views-create.md) to fine-tune the records, fields, and history loaded into Power BI. ## Custom Analytics views If the default Analytics views don't meet your needs, you can create custom views to fine-tune the records, fields, and history returned to Power BI. With a custom view, you can define the following options: + - Sharing options -- Work item filters +- Work item filters - Team and area path filters -- Backlog and work item type filters -- Field-specific filters -- Fields to display -- View history and trend options - -To learn more, see [Create an Analytics view](./analytics-views-create.md). +- Backlog and work item type filters +- Field-specific filters +- Fields to display +- View history and trend options -## Common reportable fields +For more information, see [Create an Analytics view](./analytics-views-create.md). -Default views automatically include the most common fields for the included work item types used for reporting. All custom fields are included. +## Common reportable fields -For example, the following fields are included when filtered for bugs and user stories. You can look up the description of most of these fields from the [Entities and properties reference for Azure Boards](../analytics/entity-reference-boards.md) or [Work item field index](../../boards/work-items/guidance/work-item-field.md). +Default views automatically include the most common fields for the included work item types used for reporting. All custom fields are included. -> [!div class="mx-imgBorder"] -> ![Analytics views common fields](media/editable-views/common-fields.png) +For example, the following fields are included when filtered for bugs and work items. You can look up the description of most of these fields from the [Entities and properties reference for Azure Boards](../analytics/entity-reference-boards.md) or [Work item field index](../../boards/work-items/guidance/work-item-field.md). -Two fields that are reported on are only available from Analytics data, Cycle Time Days and Lead Time Days. To learn more about how these days are calculated, see [Cumulative flow, lead time, and cycle time guidance, Lead time versus cycle time](../dashboards/cumulative-flow-cycle-lead-time-guidance.md#lead-time-versus-cycle-time). +- Area Path +- Assigned To +- Date +- Is Current +- Iteration Path +- State +- Title +- Work Item ID +- Work Item Type -For more information on how the dataset is modeled when using the Power BI Data Connector, see [Analytics views dataset design](data-connector-dataset.md). +Two fields that are reported on are only available from Analytics data: *Cycle Time Days* and *Lead Time Days*. For more information about how these days are calculated, see [Lead time versus cycle time](../dashboards/cumulative-flow-cycle-lead-time-guidance.md#lead-time-versus-cycle-time). +For more information on how the dataset is modeled when you use the Power BI Data Connector, see [Analytics views dataset design](data-connector-dataset.md). -## Next steps +## Related content > [!div class="nextstepaction"] > [Create an Analytics view](analytics-views-create.md) -## Related articles - +These articles provide more information: -- [Manage Analytics views](analytics-views-manage.md) -- [Create a Power BI report with a default Analytics view](create-quick-report.md) +- [Manage Analytics views](analytics-views-manage.md) +- [Create a Power BI report with a default Analytics view](create-quick-report.md) - [Connect to Analytics with Power BI Data Connector](data-connector-connect.md) -- [Data available from Analytics](data-available-in-analytics.md) -- [Entities and properties reference for Azure Boards](../analytics/entity-reference-boards.md) - - -### Related resources - -- [Wiql to OData Marketplace extension](https://marketplace.visualstudio.com/items?itemName=ms-eswm.wiql-to-odata) -- [What is Power BI Desktop?](/power-bi/fundamentals/desktop-what-is-desktop) +- [Expedite work using swimlanes](../../boards/boards/expedite-work.md) +- [Manage columns on your board](../../boards/boards/add-columns.md) +- [Query by assignment or workflow changes](../../boards/queries/query-by-workflow-changes.md) diff --git a/docs/report/powerbi/what-is-analytics.md b/docs/report/powerbi/what-is-analytics.md index 46a480c3d91..071db588a6d 100644 --- a/docs/report/powerbi/what-is-analytics.md +++ b/docs/report/powerbi/what-is-analytics.md @@ -6,7 +6,7 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: overview -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 11/07/2022 --- @@ -34,17 +34,6 @@ Specifically, Analytics provides you with insights about your Azure DevOps proje ::: moniker-end - -::: moniker range="azure-devops-2019" - - -> [!div class="checklist"] -> - Analytics widgets that you can add to your dashboards -> - Custom reports you can create using Power BI -> - Custom reports you can create using OData queries -> - Support to develop and add your custom Analytics widgets you can add to dashboards - -::: moniker-end [!INCLUDE [temp](../includes/analytics-preview.md)] @@ -54,7 +43,6 @@ Analytics is generally available for Azure DevOps Service and Azure DevOps Serve Data available via the Analytics service depends on your version and platform. For specifics, read [Data available in Analytics](./data-available-in-analytics.md) and [Data model for Analytics](../extend-analytics/data-model-analytics-service.md). - ::: moniker range="azure-devops" Analytics is enabled for all Azure DevOps Services projects and automatically populates itself with all available Azure DevOps data. Once populated, it updates itself as data changes occur. For more information, read [Data available in Analytics](./data-available-in-analytics.md) and [Performance and latency](performance-latency.md). @@ -67,12 +55,6 @@ Analytics is enabled for all projects on new project collections and automatical ::: moniker-end -::: moniker range="azure-devops-2019" - -Once you've [enabled or installed Analytics](../dashboards/analytics-extension.md), the service populates itself with all available Azure DevOps data. Once populated, it updates itself as data changes occur. For more information, read [Data available in Analytics](./data-available-in-analytics.md) and [Performance and latency](performance-latency.md). - -::: moniker-end - ## Dashboard widgets You can create [dashboards](../dashboards/dashboards.md) and [add widgets to them](../dashboards/add-widget-to-dashboard.md). We provide several [widgets based on Analytics](../dashboards/analytics-widgets.md). These widgets take advantage of the power of Analytics. Widgets provide the easiest way to get insights from your data. @@ -83,7 +65,7 @@ For example, the Velocity widget shown in the following image provides insights Here, the Velocity widget shows that this team has a history of closing stories late. It also shows a discrepancy between planned and completed work across all the sprints displayed. The team can drill into the data to determine the root causes. After implementing new practices, the team can use the Velocity widget to track their effectiveness. -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="nextstepaction"] > [Data available in Analytics](./data-available-in-analytics.md) - ## Related articles ::: moniker range="azure-devops" diff --git a/docs/report/sql-reports/analytics-insights-comparable-sql-reports.md b/docs/report/sql-reports/analytics-insights-comparable-sql-reports.md deleted file mode 100644 index 96a1ce1cfb9..00000000000 --- a/docs/report/sql-reports/analytics-insights-comparable-sql-reports.md +++ /dev/null @@ -1,312 +0,0 @@ ---- -title: Get Analytics insights comparable to those provided by SQL Reporting Services reports -titleSuffix: Azure DevOps -description: Learn how to get insights using Analytics comparable to those provided by the legacy SQL Reporting Services reports. -ms.subservice: azure-devops-analytics -ms.author: chcomley -author: chcomley -ms.topic: conceptual -monikerRange: '>= azure-devops-2019 <= azure-devops-2020' -ms.date: 05/26/2022 ---- - - - -# Get Analytics insights comparable to those provided by SQL Reporting Services reports - - -[!INCLUDE [version-gt-eq-2019-lt-azure-devops](../../includes/version-gt-eq-2019-lt-azure-devops.md)] - - -You can get similar insights into your Azure DevOps processes made available through the legacy SQL Server Reporting Services reports using the Analytics service. This article provides guidance for migrating from each [SQL Server Reporting Services reports](/previous-versions/azure/devops/report/sql-reports/reporting-services-reports) to using the Analytics service. - - ## Prerequisites - -To access data available from the Analytics service, you must meet the following criteria: - -- You must be a member of the projects from which you want to view data. If you haven't been added as a project member, [get added now](../../organizations/security/add-users-team-project.md). -- Have the **View Analytics** permission set to **Allow**. See [Grant permissions to access Analytics](../powerbi/analytics-security.md). Anyone with this permission, except those granted **Stakeholder** access, can view Analytics data. -- Have [enabled or installed Analytics](../dashboards/analytics-extension.md). You must be an account owner or a member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) to enable the service. -- The service for which data is collected must be enabled. For example, **Boards** must be enabled to view work tracking data. To re-enable it, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -- To use Power BI, have installed a recent version of Power BI Desktop. You can download this client application from the official [Power BI Desktop download page](/power-bi/desktop-what-is-desktop). - -## Work tracking and project management reports - -The following table summarizes Analytics reports, widgets, and other tools that you can use to gain comparable insights to the work tracking reports defined using the SQL Server Reporting services. - - -:::row::: - :::column span="1"::: - **SQL Reporting Services reports** - :::column-end::: - :::column span="1"::: - **Migration guidance** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Backlog Overview (Scrum)](/previous-versions/azure/devops/report/sql-reports/backlog-overview-scrum)1 - [Requirements Overview (CMMI)](/previous-versions/azure/devops/report/sql-reports/requirements-overview-report-cmmi)1 - [Stories Overview (Agile)](/previous-versions/azure/devops/report/sql-reports/stories-overview-report-agile)1 - Display an overall progress (work breakdown) and test results for selected backlog items. - :::column-end::: - :::column span="1"::: - - To view rollup progress, [add rollup columns to a backlog to view progress bars and remaining work counts](../../boards/backlogs/display-rollup.md). - - Use Power BI to generate a [Requirements tracking report](../powerbi/sample-stories-overview.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Release Burndown (Scrum)](/previous-versions/azure/devops/report/sql-reports/release-burndown) - Displays a column chart showing how much work remained at the start of each sprint in a release. - :::column-end::: - :::column span="1"::: - - Configure a [Burndown widget](../dashboards/configure-burndown-burnup-widgets.md). - - Create a Power BI [Release burndown report](../powerbi/sample-boards-releaseburndown.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Burndown and Burn Rate (Agile and CMMI)](/previous-versions/azure/devops/report/sql-reports/burndown-and-burn-rate-report) - [Sprint Burndown (Scrum)](/previous-versions/azure/devops/report/sql-reports/sprint-burndown-scrum) - Displays an area trend chart for a team sprint showing the completed and remaining hours. - :::column-end::: - :::column span="1"::: - - [Built-in sprint report](../dashboards/configure-sprint-burndown.md#the-in-context-burndown-trend-report) - - [Power BI Sprint burndown sample report](../powerbi/sample-boards-sprintburndown.md) - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Remaining Work (Agile and CMMI)](/previous-versions/azure/devops/report/sql-reports/remaining-work-report) - Displays an area chart showing remaining and completed hours of work for a team sprint. - :::column-end::: - :::column span="1"::: - - Configure the [Sprint burndown widget](../dashboards/team-velocity.md#add-the-velocity-widget-to-your-dashboard) on a team dashboard, choosing the **Task backlog** and **Remaining Work**. - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Status on All Iterations (Agile and CMMI)](/previous-versions/azure/devops/report/sql-reports/status-on-all-iterations-report) - Displays a rollup by sprint of stories that were closed, completed hours, and bugs active, closed, or resolved. - :::column-end::: - :::column span="1"::: - - [Configure a query](../../boards/queries/using-queries.md) that spans several sprints and define a chart for the information of interest. - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Requirements Progress (CMMI)](/previous-versions/azure/devops/report/sql-reports/requirements-overview-report-cmmi)1 - [Stories Progress (Agile)](/previous-versions/azure/devops/report/sql-reports/stories-overview-report-agile)1 - Displays overall progress bars for requirements or user stories, along with remaining hours. - :::column-end::: - :::column span="1"::: - - To view rollup progress, [add rollup columns to a backlog to view progress bars and remaining work counts](../../boards/backlogs/display-rollup.md). - - Use Power BI to generate a [Requirements tracking report](../powerbi/sample-stories-overview.md). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Unplanned Work (Agile and CMMI)](/previous-versions/azure/devops/report/sql-reports/unplanned-work) - Displays an area trend chart for planned work and work added after the start of the sprint. - :::column-end::: - :::column span="1"::: - - Configure the [Sprint burndown widget](../dashboards/team-velocity.md#add-the-velocity-widget-to-your-dashboard) on a team dashboard, the widget will show total scope increase. - - Configure a query at the start of a sprint to track work moved in or moved out of a sprint. To learn how, see [Scrum overview, List work items added after the start of the sprint](../../boards/sprints/scrum-overview.md#list-work-items-added-after-the-start-of-the-sprint) and [List work items moved out of the sprint](../../boards/sprints/scrum-overview.md#ist-work-items-moved-out-of-the-sprint). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Velocity (scrum)](/previous-versions/azure/devops/report/sql-reports/velocity) - Displays a column chart showing the level of Effort completed by the team for each sprint within the selected time period. - :::column-end::: - :::column span="1"::: - - Configure the [Velocity widget](../dashboards/team-velocity.md#add-the-velocity-widget-to-your-dashboard) on a team dashboard. - - View the [Built-in velocity report](../dashboards/team-velocity.md#view-the-velocity-in-context-report). - :::column-end::: -:::row-end::: ---- - -**Notes:** -1. The overview and progress reports depend on linking tasks, test cases, and bugs to backlog items. Link these items using the parent-child link for tasks and bugs and the Tested By link for test cases. - -## Bug status and trends - -The following table summarizes Analytics reports, widgets, and query charts that you can use to gain comparable insights to the bug reports defined using the SQL Server Reporting services. - - -:::row::: - :::column span="1"::: - **SQL Reporting Services report** - :::column-end::: - :::column span="1"::: - **Migration guidance** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Bug Status](/previous-versions/azure/devops/report/sql-reports/bug-status-report) - Presents a stacked area chart of bug status, pie chart for bug priority, and assignment of bugs. - :::column-end::: - :::column span="1"::: - - Define a team dashboard and use three [Chart work items](../dashboards/charts.md#add-chart-widget) widgets to recreate similar information. - - Use Power BI to generate a [Bug trends report](../powerbi/sample-boards-bugtrend.md) and define three different charts based on the data. - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Bug Trends](/previous-versions/azure/devops/report/sql-reports/bug-trends-report) - Displays a calculated rolling average of the number of bugs that a team has opened, resolved, and closed. - :::column-end::: - :::column span="1"::: - (INVESTIGATING) The Analytics service doesn't store a calculated rolling average but it's possible to calculate one using Power BI. - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Reactivations](/previous-versions/azure/devops/report/sql-reports/reactivations-report) - Displays a stacked area chart of resolved and reactivated bugs over time to gain insight into effectiveness of team on closing bugs. - :::column-end::: - :::column span="1"::: - Create a work item query and area chart adapting the following WIQL syntax as needed. - > [!div class="tabbedCodeSnippets"] - ```XML - SELECT - [System.Id], - [System.CreatedDate], - [System.State], - [System.AssignedTo], - [System.Title], - [System.IterationPath] - FROM workitems - WHERE - [System.TeamProject] = @project - AND [System.WorkItemType] = 'Bug' - AND EVER [System.State] = 'Closed' - AND NOT [System.State] IN ('Closed', 'Cut') - AND [System.ChangedDate] >= @today - 60 - :::column-end::: -:::row-end::: ---- - - -## Pipelines, build, and release reports - -The following table summarizes Analytics reports and widgets that you can use to gain comparable insights to the build reports defined using the SQL Server Reporting services. - -> [!NOTE] -> Build operations have significantly changed with the release of TFS 2018 and later versions. For example, manually assigning the build quality is no longer supported. YAML defined build pipelines support additional of tasks to automate testing, code coverage, and other operations. TO learn more, see [Pipelines documentation](../../pipelines/index.yml). - -:::row::: - :::column span="1"::: - **SQL Reporting Services report** - :::column-end::: - :::column span="1"::: - **Migration guidance** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Build Quality Indicators (Agile and CMMI)](/previous-versions/azure/devops/report/sql-reports/build-quality-indicators-report) - Presents code coverage, code churn and active bugs associated with select build definitions. - :::column-end::: - :::column span="1"::: - - See [Build history widget](../dashboards/widget-catalog.md#azure-pipelines-widgets) to view the success/failure trend of a selected build pipeline. - - See [Review code coverage results](../../pipelines/test/review-code-coverage-results.md) to determine the proportion of your project's code that is actually being tested by tests such as unit tests. - - See the built-in [Pipeline pass rate report](../../pipelines/reports/pipelinereport.md) for key metrics of pass rate of the pipeline over a specified period, failure trends, and top failing tasks and their failed runs. - - Use Power BI to generate a [Pipeline stage wise failures sample report](../powerbi/sample-pipelines-stagewise-failures.md)to view a pipeline's daily stage failures. - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Build Success Over Time](/previous-versions/azure/devops/report/sql-reports/build-success-over-time-report) - Presents code coverage, code churn and active bugs associated with select build definitions. - :::column-end::: - :::column span="1"::: - - See [Build history widget](../dashboards/widget-catalog.md#azure-pipelines-widgets) to view the success/failure trend of a selected build pipeline. - - See the built-in [Pipeline pass rate report](../../pipelines/reports/pipelinereport.md) for key metrics of pass rate of the pipeline over a specified period, failure trends, and top failing tasks and their failed runs. - - Use Power BI to generate a [Pipeline stage wise failures sample report](../powerbi/sample-pipelines-stagewise-failures.md)to view a pipeline's daily stage failures. - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Build Summary](/previous-versions/azure/devops/report/sql-reports/build-summary-report) - Presents code coverage, code churn and active bugs associated with select build definitions. - :::column-end::: - :::column span="1"::: - - See [Build history widget](../dashboards/widget-catalog.md#azure-pipelines-widgets) to view the success/failure trend of a selected build pipeline. - - See the built-in [Pipeline pass rate report](../../pipelines/reports/pipelinereport.md) for key metrics of pass rate of the pipeline over a specified period, failure trends, and top failing tasks and their failed runs. - - Use Power BI to generate a [Pipeline stage wise failures sample report](../powerbi/sample-pipelines-stagewise-failures.md)to view a pipeline's daily stage failures. - :::column-end::: -:::row-end::: ---- - - -## Test Plans and pipeline and test reports - -The following table summarizes Analytics reports, widgets, and other tools that you can use to gain comparable insights to the test plan and progress reports defined using the SQL Server Reporting services. - - -:::row::: - :::column span="1"::: - **SQL Reporting Services report** - :::column-end::: - :::column span="1"::: - **Migration guidance** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Test Case Readiness](/previous-versions/azure/devops/report/sql-reports/test-case-readiness-report) - Displays an area trend chart that shows the number of test cases Design and Ready state - :::column-end::: - :::column span="1"::: - - See [Chart for test plans widget](../../test/track-test-status.md) to create a similar chart using the Test Plans chart tool. Optionally add to a dashboard. - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - [Test Plan Progress](/previous-versions/azure/devops/report/sql-reports/test-plan-progress-report) - Displays an area trend chart that shows the number of test points run and their status. - :::column-end::: - :::column span="1"::: - - To track a team's progress with respect to planned testing of a product or service, see the built-in [Progress report](../../test/progress-report.md). - - Use Power BI to generate Test Plans reports: - - [Requirements tracking sample report](../powerbi/sample-stories-overview.md) - - [Requirements tracking rollup sample report](../powerbi/sample-stories-overview-rollup.md) - - [Manual test suites aggregated view sample report](../powerbi//sample-test-plans-aggregate-data-level.md) - - [Tester by outcome matrix sample report](../powerbi/sample-test-plans-tester-by-outcome.md) - - [Configuration by outcome matrix sample report](../powerbi/sample-test-plans-configuration-by-outcome.md) - :::column-end::: -:::row-end::: ---- - - -## Next steps -> [!div class="nextstepaction"] -> [Entities and properties reference for Azure Boards](../analytics/entity-reference-boards.md) - - -## Related articles - -- [Overview of sample reports using OData queries](../powerbi/sample-odata-overview.md) -- [Extend Analytics with OData (Preview) quick reference](../extend-analytics/quick-ref.md) -- [Use quick measures for common calculations](/power-bi/transform-model/desktop-quick-measures) - - \ No newline at end of file diff --git a/docs/report/sql-reports/migration-guide.md b/docs/report/sql-reports/migration-guide.md index 6db7feacf58..8fcaf31eafd 100644 --- a/docs/report/sql-reports/migration-guide.md +++ b/docs/report/sql-reports/migration-guide.md @@ -6,14 +6,12 @@ ms.subservice: azure-devops-analytics ms.author: chcomley author: chcomley ms.topic: conceptual -monikerRange: '>= azure-devops-2019 <= azure-devops-2020' +monikerRange: "=azure-devops-2020" ms.date: 05/26/2022 --- - # Migrate to Analytics from SQL Reporting Services for Azure DevOps - [!INCLUDE [version-gt-eq-2019-lt-azure-devops](../../includes/version-gt-eq-2019-lt-azure-devops.md)] With the release of Azure DevOps Server 2022, the only option for gaining Azure DevOps data insights is the Analytics service. Integration with SQL Server Reporting Services is no longer supported. This article provides guidance for migrating from using SQL Reporting Services to Analytics. @@ -23,15 +21,12 @@ For an overview of Analytics, see [What is Analytics](../powerbi/what-is-analyti > [!NOTE] > If you are looking for information about the Azure Analysis Services, see [Azure Analysis Services](https://azure.microsoft.com/services/analysis-services/). - -For information on replacement of a specific SQL Server Reporting Services report, see [Get Analytics insights comparable to those provided by SQL Reporting Services reports](analytics-insights-comparable-sql-reports.md). - ## General guidance As you migrate from using SQL Server Reporting Services to Analytics, note the following information. -- Analytics is an object-relational mapper, whereas SQL Server Reporting Services data is based on a relational databased and online analytical processing (OLAP) cube. +- Analytics is an object-relational mapper, whereas SQL Server Reporting Services data is based on a relational database and online analytical processing (OLAP) cube. - Analytics doesn't require any maintenance. - Analytics stores all work tracking fields, except for HTML/rich-text fields. Custom fields are automatically added to the Analytics data store. - Always limit your query to the project(s) you have access to. You can generate cross-project reports using Power BI, however, queries only return data when you have permissions to view Analytics data for all projects you query. @@ -39,20 +34,18 @@ As you migrate from using SQL Server Reporting Services to Analytics, note the f - Analytics views provide a quick and easy way to generate status and trend reports for work items and test cases. - Identify the insights you need to make data-driven decisions. Then, use a combination of queries, dashboards, built-in reports, or Power BI and OData queries to generate the needed reports. - ## New feature support Several new features have been introduced to support data insights that weren't available with SQL Server Reporting services. - **Dashboard widgets**: Many widgets have been added to support status and trend views, including ones based on Analytics data. For an overview, see the [widget catalog](../dashboards/widget-catalog.md). -- **Built-in Analytics reports**: Severa in-context reports have been added to support Azure Boards, Pipelines, and Test Plans. These reports display Analytics data as described in [About dashboards, charts, reports, & widgets](../dashboards/overview.md). -- **Rollup**: Rollup columns allow you to view progress bars or totals of numeric fields for descendant items within a work item hierarchy. You can add them to any backlog view. To learn more, see [Display rollup progress or totals](../../boards/backlogs/display-rollup.md). +- **Built-in Analytics reports**: Several in-context reports have been added to support Azure Boards, Pipelines, and Test Plans. These reports display Analytics data as described in [About dashboards, charts, reports, & widgets](../dashboards/overview.md). +- **Rollup**: Rollup columns allow you to view progress bars or totals of numeric fields for descendant items within a work item hierarchy. You can add them to any backlog view. For more information, see [Display rollup progress or totals](../../boards/backlogs/display-rollup.md). - **Query-based charts grouped by tags**: You can now generate query charts and add them to dashboards based on grouping by tags. -- **Traceability**: Increased support for tracking work from requirements to deployment. End-to-end traceability is supported by linking various objects such as work items, branches, commits, pull requests, builds, and releases. Built-in reports based on the Analytics service support the ability to monitor traceability in real time. To learn more, see [End-to-end traceability](../../cross-service/end-to-end-traceability.md). +- **Traceability**: Increased support for tracking work from requirements to deployment. End-to-end traceability is supported by linking various objects such as work items, branches, commits, pull requests, builds, and releases. Built-in reports based on the Analytics service support the ability to monitor traceability in real time. For more information, see [End-to-end traceability](../../cross-service/end-to-end-traceability.md). - **Release pipelines**: Release pipelines were introduced with TFS 2018. Dashboard widgets that provide insights into release pipelines include [Release pipeline overview](../dashboards/widget-catalog.md#release-definition-widget) and [Requirements quality](../dashboards/widget-catalog.md#requirements-quality-widget). - ## Key concepts about the Analytics service For on-premises servers, the Analytics service is automatically enabled for all new project collections added to your server. You can pause, disable, or re-enable Analytics as described in [Install or enable the Analytics service](../dashboards/analytics-extension.md). @@ -61,15 +54,14 @@ The Analytics data model consists of entity sets, whose members (entities) conta The following tools support interaction with the Analytics service: - **Analytics views**: Provide a quick way to generate reports based on work tracking and test cases. You can define an Analytics view and share with others. Using Power BI, you can build any type of report Power BI supports. TO learn more, see [What are Analytics views?](../powerbi/what-are-analytics-views.md). -- **Power BI**: Connect to Analytics from Power BI through an ANalytics view, OData query, or OData feed. See [About Power BI integration](../powerbi/overview.md). +- **Power BI**: Connect to Analytics from Power BI through an Analytics view, OData query, or OData feed. See [About Power BI integration](../powerbi/overview.md). - **OData query**: Use Odata to directly query Analytics from a supported browser and use the returned JSON data as needed. - Programmatic query of the Analytics metadata [Construct OData queries for Analytics, URL components to query the metadata](../analytics/analytics-query-parts.md#query-metadata). ### Query guidelines, query performance and latency -Analytics is not a real-time time store. It is a curated copy of data stored in Azure DevOps. The data copy helps optimize read and aggregation performance, and reduces the effect reporting scenarios have on Azure DevOps. Copying the data introduces up to a 30-second delay before the data associated with any one change shows up in Analytics. To learn more, see [OData Analytics query guidelines](../extend-analytics/odata-query-guidelines.md). - +Analytics is not a real-time time store. It is a curated copy of data stored in Azure DevOps. The data copy helps optimize read and aggregation performance, and reduces the effect reporting scenarios have on Azure DevOps. Copying the data introduces up to a 30-second delay before the data associated with any one change shows up in Analytics. For more information, see [OData Analytics query guidelines](../extend-analytics/odata-query-guidelines.md). ### Analytics permissions @@ -79,7 +71,7 @@ Access to data from the Analytics service requires the following project-level p - **Delete Shared Analytics views** - **Edit Shared Analytics views** -In addition, users can set permissions for individual shared Analytics views they create. To learn more, see [Set permissions to access Analytics and Analytics views](../powerbi/analytics-security.md). +In addition, users can set permissions for individual shared Analytics views they create. For more information, see [Set permissions to access Analytics and Analytics views](../powerbi/analytics-security.md). ## Recommended resources @@ -89,7 +81,3 @@ In addition, users can set permissions for individual shared Analytics views the **Learn resources**: - [Run quality tests in your build pipeline by using Azure Pipelines](/training/modules/run-quality-tests-build-pipeline) - [Run functional tests in Azure DevOps](/training/modules/run-functional-tests-azure-pipelines) - -## Next steps -> [!div class="nextstepaction"] -> [Get Analytics insights comparable to those provided by SQL Reporting Services reports](analytics-insights-comparable-sql-reports.md) diff --git a/docs/report/sql-reports/toc.yml b/docs/report/sql-reports/toc.yml index aa401faabea..2f12d0f2c6c 100644 --- a/docs/report/sql-reports/toc.yml +++ b/docs/report/sql-reports/toc.yml @@ -1,7 +1,5 @@ - name: Migrate to Analytics from SQL Reporting Services - href: migration-guide.md -- name: Get Analytics insights comparable to SQL Reporting Services - href: analytics-insights-comparable-sql-reports.md + href: migration-guide.md - name: Reporting Services Reports href: /previous-versions/azure/devops/report/sql-reports/reporting-services-reports - name: Create status and trend reports from a work item query @@ -50,7 +48,7 @@ href: /previous-versions/azure/devops/report/sql-reports/create-aggregate-report-report-designer-analysis-services-cube - name: View, organize, & configure reports href: /previous-versions/azure/devops/report/admin/view-organize-configure-reports-using-report-manager - - name: View, upload, & organize reports + - name: View, upload, & organize reports href: /previous-versions/azure/devops/report/admin/view-upload-organize-reporting-services-reports - name: Report descriptions items: @@ -104,12 +102,12 @@ items: - name: Reportable fields items: - - name: Add or modify work item fields - href: /previous-versions/azure/devops/reference/xml/add-or-modify-work-item-fields-to-support-reporting - - name: Reportable fields reference - href: /previous-versions/azure/devops/reference/xml/reportable-fields-reference + - name: Add or modify work item fields + href: /previous-versions/azure/devops/reference/xml/add-or-modify-work-item-fields-to-support-reporting + - name: Reportable fields reference + href: /previous-versions/azure/devops/reference/xml/reportable-fields-reference - name: Change reporting attributes - href: /previous-versions/azure/devops/reference/xml/add-or-modify-work-item-fields-to-support-reporting + href: /previous-versions/azure/devops/reference/xml/add-or-modify-work-item-fields-to-support-reporting - name: Data warehouse tables items: - name: Data warehouse tables @@ -154,5 +152,3 @@ href: /previous-versions/azure/devops/report/sql-reports/perspective-test-analyze-report-test-results - name: Work items and test case data href: /previous-versions/azure/devops/report/sql-reports/perspective-test-analyze-report-work - - diff --git a/docs/report/toc.yml b/docs/report/toc.yml index 5e4c335ec5a..d60c2b9d983 100644 --- a/docs/report/toc.yml +++ b/docs/report/toc.yml @@ -40,12 +40,12 @@ - name: Create work tracking charts href: dashboards/charts.md displayname: progress, trend, work tracking, stacked bar, pie, bar, column, pivot table, stacked area, area, line, flat, query - - name: Configure charts for work items + - name: Configure charts for work items href: dashboards/configure-chart-work-items-widget.md displayname: tags, flat, query - name: Example query charts href: ../boards/queries/example-query-charts.md - displayname: status, monitor, trend, widgets + displayname: status, monitor, trend, widgets - name: View/configure CFD href: dashboards/cumulative-flow.md displayname: cumulative flow diagram, in-context report, team, analytics @@ -57,7 +57,7 @@ displayname: sprint backlog, current, past - name: Configure a burndown or burnup widget href: dashboards/configure-burndown-burnup-widgets.md - displayname: release burndown, burndown widget, burndown metrics, burnup metrics, scope, date range, main metric, % completed, average burndown, items not estimated, total scope increase, projected completion, orginal scope, total scope, calculate burndown, time period, plotting interval + displayname: release burndown, burndown widget, burndown metrics, burnup metrics, scope, date range, main metric, % completed, average burndown, items not estimated, total scope increase, projected completion, original scope, total scope, calculate burndown, time period, plotting interval - name: Configure Lead/Cycle time widget href: dashboards/cycle-time-and-lead-time.md displayname: lead time, cycle time, rolling period, scatter-plot, control chart, moving average, standard deviation @@ -90,21 +90,21 @@ - name: Work item field index href: ../boards/work-items/guidance/work-item-field.md?toc=/azure/devops/report/toc.json - name: Rollup of work & other fields - href: ../reference/xml/support-rollup-of-work-and-other-fields.md?toc=/azure/devops/report/toc.json + href: ../reference/xml/support-rollup-of-work-and-other-fields.md?toc=/azure/devops/report/toc.json - name: Reference items: - name: Markdown guidance href: ../project/wiki/markdown-guidance.md?toc=/azure/devops/report/toc.json - name: Configure or add a project portal href: ../project/configure-or-add-a-project-portal.md?toc=/azure/devops/report/toc.json -- name: Extension samples +- name: Extension samples items: - name: Add a dashboard widget href: ../extend/develop/add-dashboard-widget.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Add a chart widget href: ../extend/develop/add-chart.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Add an Analytics widget - href: extend-analytics/example-analytics-widget.md + href: extend-analytics/example-analytics-widget.md - name: REST API Reference items: - name: Dashboards @@ -136,4 +136,4 @@ - name: Power BI documentation >> href: /power-bi/ - name: Developer Community, Power BI support forum >> - href: https://developercommunity.visualstudio.com/search.html?f=&type=question+OR+problem&type=question+OR+problem&c=&redirect=search%2Fsearch&sort=relevance&q=PowerBI + href: https://developercommunity.visualstudio.com/search.html?f=&type=question+OR+problem&type=question+OR+problem&c=&redirect=search%2Fsearch&sort=relevance&q=PowerBI diff --git a/docs/repos/get-started/index.md b/docs/repos/get-started/index.md index a9af29bf186..7a00417c54f 100644 --- a/docs/repos/get-started/index.md +++ b/docs/repos/get-started/index.md @@ -1,29 +1,31 @@ --- -title: Guide for getting started with Azure Repos -titleSuffix: Azure Repos -description: Sign up and get started using Azure Repos +title: Guide for getting started with Azure Repos +titleSuffix: Azure Repos +description: Sign up and get started using Azure Repos ms.subservice: azure-devops-new-user -ms.custom: seo-javascript-september2019 monikerRange: '<= azure-devops' -ms.date: 03/18/2021 +ms.date: 01/02/2024 --- # Start using Azure Repos [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Use this guide to sign up and start using Azure Repos. If you're new to Azure Repos, see [What is Azure Repos?](what-is-repos.md) +Azure Repos offers free unlimited private Git repositories, making it easy to try. Git is the most commonly used version control system today and is quickly becoming the standard for version control. It is a distributed version control system, meaning that your local copy of code is a complete version control repository. These fully functional local repositories make it easy to work offline or remotely. You can commit your work locally, and then sync your copy of the repository with the copy on the server. -Azure Repos includes free unlimited private Git repos, so Azure Repos is easy to try out. Git is the most commonly used version control system today and is quickly becoming the standard for version control. Git is a distributed version control system, meaning that your local copy of code is a complete version control repository. These fully functional local repositories make it easy to work offline or remotely. You commit your work locally, and then sync your copy of the repository with the copy on the server. +To get started, see [Sign up for Azure Repos](sign-up-invite-teammates.md), [Code with Git](../../user-guide/code-with-git.md?view=azure-devops&preserve-view=true), and [What is Azure Repos?](what-is-repos.md). -Git in Azure Repos is standard Git. You can use the clients and tools of your choice, such as Git for Windows, Mac, partners' Git services, and tools such as Visual Studio and Visual Studio Code. +**Key concepts** -Start with [Sign up and invite some teammates](sign-up-invite-teammates.md). +- [Branches & branch policies](../git/branch-policies-overview.md) +- [Branch organization](../git/git-branching-guidance.md) +- [Forks](../git/forks.md) +- [History](../git/history.md) +- [Pull requests](../git/pull-requests.md) -After you sign up, learn how to [code with Git](../../user-guide/code-with-git.md?view=azure-devops&preserve-view=true). Whether your code is in Azure Repos, in a GitHub repo, or on your local computer, this guide shows you how to get started. +**More resources** -Other resources to get you up and running: - -- [Web portal navigation](../../project/navigation/index.md) +- [Navigate the web portal](../../project/navigation/index.md) - [Get started with permissions, access, and security groups](../../organizations/security/about-permissions.md) -- [About projects and scaling your organization](../../organizations/projects/about-projects.md) \ No newline at end of file +- [About projects and scaling your organization](../../organizations/projects/about-projects.md) +- [Compare Git and TFVC](../tfvc/comparison-git-tfvc.md) diff --git a/docs/repos/get-started/key-concepts-repos.md b/docs/repos/get-started/key-concepts-repos.md deleted file mode 100644 index 87669d99d55..00000000000 --- a/docs/repos/get-started/key-concepts-repos.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Key concepts and terminology used for Azure Repos -titleSuffix: Azure Repos -description: Key definitions for objects and items used to code with Azure Repos -ms.subservice: azure-devops-new-user -ms.topic: reference -monikerRange: '<= azure-devops' -ms.date: 09/10/2018 ---- - -# Key concepts - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -Here you'll find definitions of key concepts and artifacts used in Azure Repos. - -## Branch - -Branches are lightweight references that keep a history of commits and provide a way to isolate changes for a feature or a bug fix from your main branch and other work. Committing changes to a branch doesn't affect other branches. You can push and share branches with other people on your team without having to merge the changes into main. - -Switching between branches is quick and easy. Git doesn't create multiple copies of your source code when you're working with branches - it uses the history information stored in commits to re-create the files in a branch when you start working on it. - -Learn more: [branches](../git/create-branch.md), [branch organization](../git/git-branching-guidance.md), and [how we use branches at Microsoft](/devops/develop/how-microsoft-develops-devops#git-branch-structure-and-policies). - -## Branch policies - -Branch policies are an important part of the Git workflow. You use them to help protect the important branches in your development, like `main`. Branch policies enable you to: - -* Isolate work in progress from the completed work in your main branch. -* Guarantee that changes build before they get to main. -* Limit who can contribute to specific branches. -* Enforce who can create branches and the naming guidelines for the branches. -* Automatically include the right reviewers for every code change. -* Enforce best practices with required code reviewers. - -Learn more: [branch policies](../git/branch-policies-overview.md). - -## Clone - -Create a complete local copy of an existing Git repo by cloning it. -Cloning a repo downloads all [commits](#commit) and [branches](#branch) in the repo and sets up a named relationship with the existing repo that you cloned. Use this relationship to interact with the existing repo, [pushing](#push) and [pulling](#pull) changes to share code with your team. - -Learn more: [cloning](../git/clone.md). - -## Commit - -A commit is a group of changes saved to your local repository. You can share these changes to the remote repository by [pushing](#push). - -Learn more: [commits](../git/commits.md). - -## Fork - -A fork is a complete copy of a repository, including all files, commits, and (optionally) branches. The new fork acts as if someone cloned the original repository and then pushed to a new, empty repository. After a fork has been created, new files, folders, and branches are not shared between the repositories unless a pull request carries them along. When you're ready to share those changes, it's easy to use pull requests to push the changes back to the original repository. - -Learn more: [forks](../git/forks.md) - -## Git - -Git is the most commonly used version control system today and is quickly becoming the standard for version control. Git is a distributed version control system, so your local copy of code is a complete version control repository. These fully functional local repositories make it is easy to work offline or remotely. You commit your work locally, and then sync your copy of the repository with the copy on the server. - -Git in Azure Repos is standard Git. You can use the clients and tools of your choice, such as Git for Windows, Mac, partners' Git services, and tools such as Visual Studio and Visual Studio Code. - -Learn more: [Git and Azure Repos](../git/index.yml). - -## Git workflow - -Version control has a general workflow that most developers use when writing code and sharing it with the team. These steps are: - -1. Get a local copy of code if they don't have one yet. -1. Make changes to code to fix bugs or add new features. -1. When the code is ready, make it available for your team to review. -1. After the code is reviewed, merge it into the team's shared codebase. - -Git has a version of this workflow that uses terminology and commands such as repositories, branches, commits, and pull requests. These terms might sound familiar if you've used a version control system like Team Foundation Version Control (TFVC) or Subversion, but they behave differently in Git. - -1. [Create a branch](#branch) for the changes you plan to make and give it a name, such as `users/jamal/fix-bug-3214` or `features/cool-feature`. -1. [Commit changes](#commit) to your branch. People often have multiple commits for a bug fix or feature. -1. [Push your branch](#push) to the remote repository. -1. [Create a pull request](#pull-request) so other people can review your changes. To incorporate feedback, you might need to make more commits and push more changes. When the code is ready, complete the pull request and merge your code into the target branch, such as `main`. - -Use this workflow if you're new to Git. As your team gets more experienced and confident with Git, extend it to suit your team's needs. - -Learn more: [how we use Git at Microsoft](/devops/develop/how-microsoft-develops-devops). - -[!INCLUDE [glossary-terms-notifications](../../includes/glossary-terms/notifications.md)] - -[!INCLUDE [glossary-terms-projects](../../includes/glossary-terms/projects.md)] - -[!INCLUDE [glossary-terms-public-projects](../../includes/glossary-terms/public-projects.md)] - -## Pull request - -Create pull requests to review and merge code in a [Git project](../../organizations/projects/create-project.md). -Pull requests let your team review code and give feedback on changes before -you merge it into the main branch. Pull requests can come from either -topic branches within the same repository or a branch in a -[fork](../git/forks.md) of the original repository. -Reviewers can step through the proposed changes, leave comments, and vote to approve or reject the code. - -Learn more: [pull requests](../git/pull-requests.md). - -## Pull - -A `pull` command updates the code in your local repository with the changes from other members of your team that are in the remote repository. - -Learn more: [pull](../git/pulling.md). - -## Push - -Share changes made in commits and branches by using the `push` command. - -When you push, Git uploads the saved commits in your checked branch to the remote repository. If the branch exists on the remote repository, Git takes the [commits](#commit) and adds them to that branch on the remote repository. If that branch doesn't exist, Git creates a new branch with the same commits as your local branch. - -Learn more: [push](../git/pushing.md). - -## Repository - -A repository is a location for your code managed by version control. Azure Repos supports both [Git](#git) and [TFVC](#team-foundation-version-control-tfvc). - -[!INCLUDE [glossary-terms-teams](../../includes/glossary-terms/teams.md)] - -[!INCLUDE [glossary-terms-tfvc](../../includes/glossary-terms/tfvc-repo.md)] \ No newline at end of file diff --git a/docs/repos/get-started/sign-up-invite-teammates.md b/docs/repos/get-started/sign-up-invite-teammates.md index d14e6a821ab..150d0c9aab6 100644 --- a/docs/repos/get-started/sign-up-invite-teammates.md +++ b/docs/repos/get-started/sign-up-invite-teammates.md @@ -1,47 +1,40 @@ --- -title: Sign up and invite teammates +title: Sign up for Azure Repos titleSuffix: Azure DevOps -description: Quickstart guide to signing up and inviting others to join a team project in Azure DevOps Services +description: How to sign up for Azure Repos. ms.subservice: azure-devops-new-user -ms.topic: quickstart -ms.date: 03/18/2021 +ms.topic: how-to +ms.date: 03/13/2025 monikerRange: 'azure-devops' --- -# Sign up for free and invite others to collaborate on your project +# Sign up for free for Azure Repos [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - - -[!INCLUDE [sign-up-msft-account](../../includes/sign-up-msft-account.md)] - - - -[!INCLUDE [sign-in-github-account](../../includes/sign-in-github-account.md)] +Sign up for Azure Repos. For more information, see [What is Azure Repos?](what-is-repos.md) +## Prerequisites - +| Category | Requirements | +|--------------|-------------| +|**Browser**| Latest version of one of the following web browsers: Microsoft Edge, Internet Explorer, Safari (Mac), Firefox, or Chrome.| -## Create a project +## Sign up -If you signed up for Azure DevOps with an existing MSA or GitHub identity, you're automatically prompted to create a project. You can create either a public or private project. To learn more about public projects, see [What is a public project?](../../organizations/projects/about-projects.md). +Sign up for Azure Repos with either a Microsoft account or GitHub account. -1. Enter a name for your project, select the visibility, and optionally provide a description. Then choose **Create project**. +# [Microsoft account](#tab/microsoft-account) - > [!div class="mx-imgBorder"] - > ![Create a project.](../../boards/get-started/media/sign-up/nf-create-project.png) - - The name can't contain special characters (such as `/ : \ ~ & % ; @ ' " ? < > | # $ * } { , + = [ ]`), can't begin with an underscore, can't begin or end with a period, and must be 64 characters or less. - - Any one can view public projects. With private projects, only people who you give access to the project can view it. +[!INCLUDE [sign-up-msft-account](../../includes/sign-up-msft-account.md)] +# [GitHub account](#tab/github-account) - +[!INCLUDE [sign-in-github-account](../../includes/sign-in-github-account.md)] -[!INCLUDE [invite-teammates](../../includes/invite-teammates.md)] +--- -## Try this next +## Next steps > [!div class="nextstepaction"] -> [Code with Git](../../user-guide/code-with-git.md?view=azure-devops&preserve-view=true) or [Develop and share your code in TFVC](../tfvc/share-your-code-in-tfvc-vs.md) \ No newline at end of file +> [Code with Git](../../user-guide/code-with-git.md?view=azure-devops&preserve-view=true) diff --git a/docs/repos/get-started/toc.yml b/docs/repos/get-started/toc.yml index 441a0aa8a01..2a70ec044aa 100644 --- a/docs/repos/get-started/toc.yml +++ b/docs/repos/get-started/toc.yml @@ -1,14 +1,12 @@ -- name: Start using Azure Repos +- name: Use Azure Repos href: index.md -- name: Compare Git and TFVC - href: ../tfvc/comparison-git-tfvc.md -- name: Sign up and invite some teammates +- name: Sign up for Azure Repos href: sign-up-invite-teammates.md - name: Code with Git href: ../../user-guide/code-with-git.md?toc=/azure/devops/repos/toc.json - name: Use Git and TFVC href: ../git/team-projects.md -- name: Key concepts - href: key-concepts-repos.md +- name: Compare Git and TFVC + href: ../tfvc/comparison-git-tfvc.md - name: Search code repositories - href: ../../project/search/functional-code-search.md?toc=/azure/devops/repos/toc.json + href: ../../project/search/functional-code-search.md diff --git a/docs/repos/get-started/what-is-repos.md b/docs/repos/get-started/what-is-repos.md index e288f5a3e0f..82a832e5318 100644 --- a/docs/repos/get-started/what-is-repos.md +++ b/docs/repos/get-started/what-is-repos.md @@ -3,7 +3,7 @@ title: Collaborate on code titleSuffix: Azure Repos description: What do you get with Azure Repos ms.subservice: azure-devops-new-user -ms.date: 06/01/2020 +ms.date: 01/02/2024 ms.topic: overview monikerRange: '<= azure-devops' --- @@ -15,9 +15,9 @@ monikerRange: '<= azure-devops' Azure Repos is a set of version control tools that you can use to manage your code. Whether your software project is large or small, using version control as soon as possible is a good idea. -Version control systems are software that help you track changes you make in your code over time. As you edit your code, you tell the version control system to take a snapshot of your files. The version control system saves that snapshot permanently so you can recall it later if you need it. Use version control to save your work and coordinate code changes across your team. +Version control systems are software that helps you track changes you make in your code over time. As you edit your code, you tell the version control system to take a snapshot of your files. The version control system saves that snapshot permanently so you can recall it later if you need it. Use version control to save your work and coordinate code changes across your team. -Even if you're just a single developer, version control helps you stay organized as you fix bugs and develop new features. Version control keeps a history of your development so that you can review and even roll back to any version of your code with ease. +Even if you're a single developer, version control helps you stay organized as you fix bugs and develop new features. Version control keeps a history of your development so that you can review and even roll back to any version of your code with ease. Azure Repos provides two types of version control: @@ -26,7 +26,7 @@ Azure Repos provides two types of version control: ## Git -Git is the most commonly used version control system today and is quickly becoming the standard for version control. Git is a distributed version control system, meaning that your local copy of code is a complete version control repository. These fully functional local repositories make it is easy to work offline or remotely. You commit your work locally, and then sync your copy of the repository with the copy on the server. +Git is the most commonly used version control system today and is quickly becoming the standard for version control. Git is a distributed version control system, meaning that your local copy of code is a complete version control repository. These fully functional local repositories make it easy to work offline or remotely. You commit your work locally, and then sync your copy of the repository with the copy on the server. Git in Azure Repos is standard Git. You can use the clients and tools of your choice, such as Git for Windows, Mac, partners' Git services, and tools such as Visual Studio and Visual Studio Code. @@ -49,21 +49,20 @@ Connect your favorite development environment to Azure Repos to access your repo ### Review code with pull requests -Review code with your team and make sure that changes build and pass tests before it's merged. +Review code with your team and make sure that changes build and pass tests before it gets merged. - [Create a pull request](../git/pull-requests.md) - [Link work items to pull requests](../git/pull-requests.md#link-work-items) - [Set up branch policies](../git/branch-policies.md#build-validation) - [Squash merge pull requests](../git/merging-with-squash.md) - [Git branch and pull request workflows](../git/git-branching-guidance.md) -- [Leave comments](../git/review-pull-requests.md#make-comments) -- [Vote on the changes](../git/review-pull-requests.md#vote-on-changes) +- [Leave comments or vote on changes](../git/review-pull-requests.md) ### Protect branches with policies There are a few critical branches in your repo that the team relies on to always be in good shape, such as your `master` branch. [Require pull requests](../git/branch-policies.md) to make any changes on these branches. -Developers who push changes directly to the protected branches will have their pushes rejected. +Developers who push changes directly to the protected branches have their pushes rejected. Add conditions to your pull requests to enforce a higher level of code quality in your key branches. A clean build of the merged code and approval from multiple reviewers are extra requirements that you can set to help protect your key branches. @@ -74,7 +73,7 @@ A clean build of the merged code and approval from multiple reviewers are extra ### Extend pull request workflows with pull request status -Pull requests and branch policies enable teams to enforce many best practices related to reviewing code and running automated builds. But many teams have additional requirements and validations to perform on code. To cover these individual and custom needs, Azure Repos offers pull request statuses. +Pull requests and branch policies enable teams to enforce many best practices related to reviewing code and running automated builds. But many teams have other requirements and validations to perform on code. To cover these individual and custom needs, Azure Repos offers pull request statuses. Pull request statuses integrate into the PR workflow. They allow external services to programmatically sign off on a code change by associating simple success/failure information with a pull request. @@ -87,7 +86,7 @@ Pull request statuses integrate into the PR workflow. They allow external servic Forks are a great way to isolate experimental, risky, or confidential changes from the original codebase. A fork is a complete copy of a repository, including all files, commits, and (optionally) branches. The new fork acts as if someone cloned the original repository and then pushed to a new, empty repository. -After a fork has been created, new files, folders, and branches are not shared between the repositories unless a pull request carries them along. After you're ready to share those changes, it's easy to use [pull requests](../git/pull-requests.md) to push the changes back to the original repository. +After a fork gets created, new files, folders, and branches aren't shared between the repositories unless a pull request carries them along. After you're ready to share those changes, it's easy to use [pull requests](../git/pull-requests.md) to push the changes back to the original repository. - [Learn more about forks](../git/forks.md) diff --git a/docs/repos/git/about-pull-requests.md b/docs/repos/git/about-pull-requests.md index f7c557c5820..8f00ea93521 100644 --- a/docs/repos/git/about-pull-requests.md +++ b/docs/repos/git/about-pull-requests.md @@ -25,38 +25,36 @@ This article describes pull request guidelines and management considerations. Fo - [Review pull requests](review-pull-requests.md) - [Complete pull requests](complete-pull-requests.md) +::: moniker range=">= azure-devops-2022" +> [!NOTE] +> For performance and stability reasons, the number of reviewers that can be added to a pull request must be 1000 or less. New pull requests will not be created when adding more than 1000 reviewers, and existing pull requests won't allow you to add more than 1000 reviewers. +::: moniker-end + ## Permissions and prerequisites ::: moniker range="azure-devops" - **Repos** must be enabled on your project. If the **Repos** hub and associated pages don't display, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md) to reenable Repos. -- To view or review PRs, you must be a member of an Azure DevOps project with **Basic** access or higher. +- To view or review PRs, be a member of an Azure DevOps project with at least **Basic** access. - If you don't have a project, create one or [sign up for free](../../user-guide/sign-up-invite-teammates.md). - If you aren't a project member, [get added](../../organizations/accounts/add-organization-users.md). -- To contribute to a PR, you must be a member of the **Readers** security group or have the corresponding permissions. +- To contribute to a PR, be a member of the **Readers** security group or have the corresponding permissions. -- To create and complete a PR, you must be a member of the **Contributors** security group or have the corresponding permissions. +- To create and complete a PR, be a member of the **Contributors** security group or have the corresponding permissions. > [!NOTE] > For public projects, users granted **Stakeholder** access have full access to Azure Repos. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" ## Quality feedback for pull requests @@ -78,15 +76,14 @@ PR owners should: - Reply to comments, accepting the suggestion or explaining why the suggested change isn't ideal. - For good suggestions outside the scope of the PR, create new work items, branches, and PRs to make those changes. -Reviewers should: +Reviewers should do the following tasks. -- Provide feedback on changes they don't agree with. -- Identify issues and give specific suggestions on what to do differently. -- Make sure the feedback has clear intent and is easy to understand. -- [Leave comments](review-pull-requests.md#make-comments). -- [Vote on the changes](review-pull-requests.md#vote-on-changes). +- Provide feedback on changes they don't agree with +- Identify issues and give specific suggestions on what to do differently +- Make sure the feedback has clear intent and is easy to understand +- [Leave comments or vote on changes](review-pull-requests.md) -Learn more about how to [get feedback with Git pull requests](/devops/develop/git/git-pull-requests). +For more information, see [Get feedback with Git pull requests](/devops/develop/git/git-pull-requests). ## Branch policies and pull requests @@ -136,7 +133,6 @@ The following table summarizes the policies you can define to customize a branch :::column-end::: :::row-end::: - :::row::: :::column span="2"::: [**Check for comment resolution**](branch-policies.md#check-comment-resolution) diff --git a/docs/repos/git/auth-overview.md b/docs/repos/git/auth-overview.md index f489125b281..2c0ae6d69bc 100644 --- a/docs/repos/git/auth-overview.md +++ b/docs/repos/git/auth-overview.md @@ -5,57 +5,72 @@ description: Choose between HTTPS, SSH, and personal access tokens to securely s ms.assetid: 138f12d0-e3fd-4fde-a727-1b39d45c05c4 ms.service: azure-devops-repos ms.topic: conceptual -ms.date: 11/13/2020 +ms.date: 07/11/2024 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- -# Authentication overview +# Authentication with Azure Repos [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Choose a method to securely access the code in Azure Repos, Azure DevOps Server 2019, or Team Foundation Server (TFS) Git repositories. -Use these credentials with Git at a command prompt. These credentials also work with any Git client that supports HTTPS or SSH authentication. -Limit the scope of access and revoke these credentials when they're no longer needed. +Selecting the right authentication method is crucial for secure access to your Azure Repos and Azure DevOps Server Git repositories. Whether you're working from a command prompt or using a Git client that supports HTTPS or SSH, it's important to choose credentials that not only provide the necessary access but also limit the scope to what's needed for your tasks. -[!INCLUDE [alt-creds-deprecation-notice](../../includes/alt-creds-deprecation-notice.md)] +Always revoke credentials when they're no longer required to maintain the security of your repositories. This approach ensures that you have the flexibility to work with your code securely and efficiently, while also safeguarding it against unauthorized access. -Azure DevOps Server was formerly named Visual Studio Team Foundation Server. +## Authentication mechanisms -> [!TIP] -> Using Visual Studio? Team Explorer handles authentication with Azure Repos for you. +### Microsoft Entra OAuth tokens -[!INCLUDE [temp](includes/note-new-git-tool.md)] +Use [Microsoft Entra](../../integrate/get-started/authentication/entra.md) to generate tokens for accessing [REST APIs](/rest/api/azure/devops/). Microsoft Entra tokens can be used wherever personal access tokens are used. Here's a helpful tip on how to get a one-time access token from the Azure CLI to call git fetch: -## Authentication comparison +```powershell +$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv +git -c http.extraheader="AUTHORIZATION: bearer $accessToken" clone https://dev.azure.com/{yourOrgName}/{yourProjectName}/_git/{yourRepoName} +``` -| Authentication Type | When to use | Secure? | Ease of setup | Additional tools | -|---------------------|:-------------:|:------------:|:---------------------|-------------| -| Personal access tokens | You need an easy to configure credential or need configurable access controls | Very secure (when using HTTPS) | Easy | Optional ([Git credential managers](set-up-credential-managers.md)) | -| SSH | You already have SSH keys set up, or are on macOS or Linux | Very secure | Intermediate | Windows users will need the SSH tools included with [Git for Windows](https://git-for-windows.github.io/) | +>[!TIP] +> Look into the [Git Credential Manager (GCM)](set-up-credential-managers.md) instead to avoid entering your credentials everytime. Use GCM with default credential type as `Oauth` to generate Microsoft Entra tokens. -## Personal access tokens +### Personal access tokens -Personal access tokens (PATs) give you access to Azure DevOps and Team Foundation Server (TFS), without using your username and password directly. -These tokens have an expiration date from when they're created. You can restrict the scope of the data they can access. -Use PATs to authenticate if you don't already have SSH keys set up on your system or if you need to restrict the permissions that are granted by the credential. +[Personal access tokens (PATs)](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) provide access to Azure DevOps without using your username and password directly. These tokens expire and allow you to restrict the scope of the data they can access. -* [Learn more about personal access tokens and how to create one](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) +Use PATs to authenticate if you don't have SSH keys set up on your system or need to limit the permissions granted by the credential. -### Use Git Credential Manager to generate tokens +Git interactions require a username, which can be anything except an empty string. To use a PAT with HTTP basic authentication, `Base64-encode` your `$MyPat` as shown in the following code block. -The [Git Credential Manager](set-up-credential-managers.md) is an optional tool that makes it easy to create PATs when you're working with Azure Repos. -Sign in to the web portal, generate a token, and then use the token as your password when you're connecting to Azure Repos. +#### [Windows](#tab/Windows/) -PATs are generated on demand when you have the credential manager installed. -The credential manager creates the token in Azure DevOps and saves it locally for use with the Git command line or other client. +In PowerShell, enter the following code. ->[!NOTE] ->Current versions of [Git for Windows](https://git-for-windows.github.io/) include the Git credential manager as an optional feature during installation. -> ->![Select Enable Git Credential Manager during Git for Windows install](media/install-git-with-git-credential-manager.png) +```powershell +$MyPat = 'yourPat' +$headerValue = "Authorization: Basic " + [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(":" + $MyPat)) +$env:GIT_AUTH_HEADER = $headerValue -## SSH key authentication +git --config-env=http.extraheader=GIT_AUTH_HEADER clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName +``` + +#### [Linux/macOS](#tab/Linux/) + +In Bash, enter the following code. + +```bash +MY_PAT=yourPAT # replace "yourPAT" with "PatStringFromWebUI" +export HEADER_VALUE=$(echo -n "Authorization: Basic "$(printf ":%s" "$MY_PAT" | base64)) + +git --config-env=http.extraheader=HEADER_VALUE clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName +``` + +--- + + +>[!TIP] +> If you are using PATs regularly, look into the [Git Credential Manager (GCM)](set-up-credential-managers.md) instead to avoid entering your credentials everytime. Even better, explore using GCM with default credential type as `Oauth` to generate Microsoft Entra tokens instead of PATs whenever possible. + + +### SSH keys Key authentication with SSH works through a public and private key pair that you create on your computer. You associate the public key with your username from the web. Azure DevOps will encrypt the data sent to you with that key when you work with Git. @@ -63,21 +78,37 @@ You decrypt the data on your computer with the private key, which is never share ![Animated GIF showing adding of a SSH public key to Azure DevOps](media/ssh_add_public_key.gif) -SSH is a great option if you've already got it set up on your system—just add a public key to Azure DevOps and clone your repos using SSH. -If you don't have SSH set up on your computer, you should use PATs and HTTPS instead - it's secure and easier to set up. +SSH is a great option if you've already got it set up on your system—just add a public key to Azure DevOps and clone your repos using SSH. SSH might be preferred for those on Linux, macOS, or Windows running [Git for Windows](https://www.git-scm.com/download/win) who can't use [Git credential managers](../../repos/git/set-up-credential-managers.md) or [personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) for HTTPS authentication. + +For more information, see [Set up SSH with Azure DevOps](use-ssh-keys-to-authenticate.md). + +## Use Git Credential Manager to generate tokens + + + +Use the [Git Credential Manager (GCM)](set-up-credential-managers.md) to avoid entering your credentials every time and keep your token more secure when accessing Azure Repos. Sign in to the web portal, generate a token, and then use the token as your password when you're connecting to Azure Repos. Microsoft Entra tokens or PATs are generated on demand when you have the credential manager installed and saved locally for use with the Git command line or other client. + +## Existing repositories + +- **Remove existing origin:** If you previously added the origin using a username, remove it by running the following command: + + ``git remote remove origin`` + +- **Authenticate with a PAT:** If you encounter issues with standard authentication, run the following command to authenticate via the command line: + + ``git remote add origin https://dev.azure.com/@://_git/`` + + ``git push -u origin --all`` + + The `path to git repo = /_git/do` refers to the URL path structure used in Azure DevOps for Git repositories. The `/_git/` segment indicates that you're accessing a Git repository, and you should replace `do` with the actual name of your repository. For example, if your repository is named `my-repo`, the path would be '`/_git/my-repo`'. -Learn more about [setting up SSH with Azure DevOps](use-ssh-keys-to-authenticate.md) +- **Clone repository:** If you're using Git and need to authenticate, run the following command: -## OAuth + ``git clone https://{organization}@dev.azure.com/{organization}/_git/{repository}`` -Use [OAuth](../../integrate/get-started/authentication/oauth.md) -to generate tokens for accessing [REST APIs](/rest/api/azure/devops/). The [Accounts](/rest/api/azure/devops/account) -and [Profiles](/rest/api/azure/devops/profile) -APIs support only OAuth. + Replace `{organization}` with your Azure DevOps organization name and `{repository}` with the name of your repository. -- [SSH authentication](../../repos/git/use-ssh-keys-to-authenticate.md) -to generate encryption keys when you use Linux, macOS, -or Windows running [Git for Windows](https://www.git-scm.com/download/win) -and can't use -[Git credential managers](../../repos/git/set-up-credential-managers.md) -or [personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) for HTTPS authentication. +## Related articles +- [Use Git Credential Manager to authenticate to Azure Repos](set-up-credential-managers.md) +- [About security, authentication, and authorization in Azure DevOps](../../organizations/security/about-security-identity.md) +- [About permissions and security groups in Azure DevOps](../../organizations/security/about-permissions.md) diff --git a/docs/repos/git/branch-permissions.md b/docs/repos/git/branch-permissions.md index fb3c5142513..8dd7f4686d1 100644 --- a/docs/repos/git/branch-permissions.md +++ b/docs/repos/git/branch-permissions.md @@ -1,11 +1,11 @@ --- title: Set Git branch security and permissions titleSuffix: Azure Repos -description: Set permissions for Git branches in Azure DevOps Services/TFS. +description: Set permissions for Git branches in Azure DevOps. ms.assetid: 0dacda14-c251-4a89-8141-ae60a47dab52 ms.service: azure-devops-repos -ms.topic: conceptual -ms.date: 10/25/2021 +ms.topic: how-to +ms.date: 02/17/2025 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- @@ -14,158 +14,69 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - Set up permissions to control who can read and update the code in a branch on your Git repo. You can set permissions for individual users and groups, and inherit and override permissions as needed from your [repo permissions](set-git-repository-permissions.md#git-repository). -[!INCLUDE [version-selector-minimize](../../includes/version-selector-minimize.md)] - -## Use the branches view to configure security - -::: moniker range=">= azure-devops-2019" - -1. Open the **Branches** page by navigating to your project in the web portal and selecting **Repos**, **Branches**. +## Prerequisites - ![Open up the Branches page on the web](media/branches/branches_nav-new-nav.png) +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] -::: moniker-end - -::: moniker range="< azure-devops-2019" - -1. Open the **Branches** page by navigating to your project in the web portal and selecting **Code**, **Branches**. +## Use the branches view to configure security - ![Open up the Branches page on the web](media/branches/branches_nav.png) +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). +2. Select **Repos** > **Branches**. -::: moniker-end + ![Screenshot shows opening the Branches page on the web.](media/branches/branches_nav-new-nav.png) -2. Locate your branch in the page. You can browse the list or you can search for your branch using the **Search all branches** box in the upper right. +3. Locate your branch in the page. You can browse the list or you can search for your branch using the **Search** box in the upper right. - ![Branches page](media/branches/branches-page.png) + ![Screenshot shows Branches page.](media/branches/branches-page.png) -3. Open the context menu by selecting the **...** icon next to the branch name. Select **Branch security** from the menu. +4. To open the context menu, select **...** **More actions** next to the branch name. Select **Branch security** from the menu. - ![Open the branch permissions page from the branches context menu](media/branches/branches_context_menu_permissions.png) + ![Screenshot shows Open the branch permissions page from the branches context menu.](media/branches/branches_context_menu_permissions.png) ## Add users or groups > [!TIP] -> You can only add permissions for users and groups already in your Project. [Add new users and groups to your Project](../../organizations/security/add-users-team-project.md) before setting branch permissions. +> You can only add permissions for users and groups already in your project. [Add new users and groups to your project](../../organizations/security/add-users-team-project.md) before you set branch permissions. -Add users or groups to your branch permissions by selecting **Add**. -Enter the sign-in address or group alias, then select **Save Changes**. +1.To add users or groups to your branch permissions, select**Add**. +2.Enter the sign-in address or group alias, then select **Save**. ## Remove users or groups -Remove permissions for a user or group by selecting the user or Azure DevOps group, then selecting **Remove**. -The user or group will still exist in your Project and this change will not affect other permissions for the user or group. +To remove permissions for a user or group, select the user or group, and then select **Remove**. This change doesn't affect other permissions for the user or group in your project. -![Remove branch permissions for a user in Azure DevOps Services or TFS](media/branches/remove_permissions.png) +![Screenshot shows Remove branch permissions for a user in Azure DevOps.](media/branches/remove_permissions.png) ## Set permissions -Control branch permission settings from the branch permission view. Users and groups with permissions set at the repository level will -[inherit those permissions](../../organizations/security/about-permissions.md#inheritance) by default. To learn more about how permissions work, see [Permission settings](../../organizations/security/about-permissions.md#permission-settings). +Users and groups with permissions set at the repository level [inherit those permissions](../../organizations/security/about-permissions.md#permission-inheritance) by default. +Branch creators automatically receive the following permissions: -::: moniker range=">= azure-devops-2019" -The following permissions are automatically assigned to branch creators: **Contribute**, **Force push**, **Manage permissions** (when allowed through the repository setting **Permissions management**), and **Remove others' locks**. - +- **Contribute** +- **Force push** +- **Manage permissions** (when allowed through the repository setting **Permissions management**) +- **Remove others' locks** > [!NOTE] -> The **Exempt from policy enforcement** permission was removed for Azure DevOps Server 2019 and later versions. It's functionalilty is now supported with the following two permissions: +> The **Exempt from policy enforcement** permission is replaced by the following two permissions: > ->- **Bypass policies when completing pull requests** ->- **Bypass policies when pushing** +> - **Bypass policies when completing pull requests** +> - **Bypass policies when pushing** > -> Users that previously had **Exempt from policy enforcement** enabled now have the two new permissions enabled instead. See the following table for more details on these two new permissions. -::: moniker-end - -:::row::: - :::column span=""::: - **Permission** - :::column-end::: - :::column span=""::: - **Description** - :::column-end::: -:::row-end::: ---- -::: moniker range=">= azure-devops-2019" -:::row::: - :::column span=""::: - **Bypass policies when completing pull requests** - :::column-end::: - :::column span=""::: - Users with this permission are exempt from the [branch policy](branch-policies.md) set for the branch when completing pull requests and can opt-in to override the policies by checking **Override branch policies and enable merge** when completing a PR. - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range=">= azure-devops-2019" -:::row::: - :::column span=""::: - **Bypass policies when pushing** - :::column-end::: - :::column span=""::: - Users with this permission can push to a branch that has branch policies enabled. Note that when a user with this permission makes a push that would override branch policy, the push automatically bypasses branch policy with no opt-in step or warning. - :::column-end::: -:::row-end::: +> Users who previously had **Exempt from policy enforcement** enabled have these permissions enabled instead. The following table shows more details on these permissions. ::: moniker-end - -:::row::: - :::column span=""::: - **Contribute** - :::column-end::: - :::column span=""::: - Can push new commits to the branch and lock the branch. Can't rewrite existing commits on the branch. - :::column-end::: -:::row-end::: - -:::row::: - :::column span=""::: - **Edit policies** - :::column-end::: - :::column span=""::: - Can edit [branch policies](branch-policies.md). - :::column-end::: -:::row-end::: - -::: moniker range="tfs-2018" -:::row::: - :::column span=""::: - **Exempt from policy enforcement** - :::column-end::: - :::column span=""::: - Are exempt from [branch policies](branch-policies.md) when completing pull requests and can override the policies by checking **Override branch policies and enable merge** when completing a PR. Can also push to a branch that has branch policies enabled. - :::column-end::: -:::row-end::: -::: moniker-end - -:::row::: - :::column span=""::: - **Force push (rewrite history, delete branches and tags)** - :::column-end::: - :::column span=""::: - Can force push to a branch, which can rewrite history. This permission is also required to delete a branch. - :::column-end::: -:::row-end::: - -:::row::: - :::column span=""::: - **Manage permissions** - :::column-end::: - :::column span=""::: - Can set permissions for the branch. - - :::column-end::: -:::row-end::: - -:::row::: - :::column span=""::: - **Remove others' locks** - :::column-end::: - :::column span=""::: - Can remove [locks](lock-branches.md) set on branches by other users. - - :::column-end::: -:::row-end::: +| **Permission** | **Description** | +|----------------|-----------------| +| **Bypass policies when completing pull requests** | Users with this permission are exempt from the [branch policy](branch-policies.md) set for the branch when completing pull requests and can opt in to override the policies by checking **Override branch policies and enable merge** when completing a PR. | +| **Bypass policies when pushing** | Users with this permission can push to a branch that has branch policies enabled. When a user with this permission makes a push that would override branch policy, the push automatically bypasses branch policy with no opt-in step or warning. | +| **Contribute** | Can push new commits to the branch and lock the branch. Can't rewrite existing commits on the branch. | +| **Edit policies** | Can edit [branch policies](branch-policies.md). | +| **Force push (rewrite history, delete branches and tags)** | Can force push to a branch, which can rewrite history. This permission is also required to delete a branch. | +| **Manage permissions** | Can set permissions for the branch. | +| **Remove others' locks** | Can remove [locks](lock-branches.md) set on branches by other users. | diff --git a/docs/repos/git/branch-policies.md b/docs/repos/git/branch-policies.md index 588684a0388..eebf8e6f9bd 100644 --- a/docs/repos/git/branch-policies.md +++ b/docs/repos/git/branch-policies.md @@ -17,19 +17,19 @@ ms.subservice: azure-devops-repos-git Branch policies help teams protect their important [branches](./create-branch.md) of development. Policies enforce your team's code quality and change management standards. This article describes how to set and manage branch policies. For an overview of all repository and branch policies and settings, see [Git repository settings and policies](repository-settings.md). -A branch that has required policies configured can't be deleted, and requires pull requests (PRs) for all changes. +A branch with required policies configured can't be deleted, and requires pull requests (PRs) for all changes. ## Prerequisites ::: moniker range="azure-devops" -- To set branch policies, you must be a member of the Project Administrators security group or have repository-level **Edit policies** permissions. For more information, see [Set Git repository permissions](set-git-repository-permissions.md). +- To set branch policies, be a member of the Project Administrators security group or have repository-level **Edit policies** permissions. For more information, see [Set Git repository permissions](set-git-repository-permissions.md). - If you want to use Azure DevOps CLI [az repos policy](/cli/azure/repos/policy) commands to manage branch policies, follow the steps in [Get started with Azure DevOps CLI](../../cli/index.md). ::: moniker-end ::: moniker range="< azure-devops" -- To set branch policies, you must be a member of the Project Administrators security group or have repository-level **Edit policies** permissions. For more information, see [Set Git repository permissions](set-git-repository-permissions.md). +- To set branch policies, be a member of the Project Administrators security group or have repository-level **Edit policies** permissions. For more information, see [Set Git repository permissions](set-git-repository-permissions.md). ::: moniker-end ## Configure branch policies @@ -54,32 +54,12 @@ Select the **More options** icon next to the branch, and then select **Branch po ::: moniker-end -::: moniker range="< azure-devops-2020" - -Locate your branch in the page. You can browse the list or you can search for your branch using the **Search all branches** box in the upper right. - -![Screenshot that shows the Branches page.](media/branch-policies/branches-page.png) - -Select the **...** button. Select **Branch policies** from the context menu. - -![Screenshot that shows Open the branch policies from the context menu.](media/branch-policies/branches-context-menu-policy.png) - -::: moniker-end - ::: moniker range=">= azure-devops-2020" Configure policies on the branch's settings page. See the following sections for descriptions and instructions for each policy type. ::: moniker-end -::: moniker range="< azure-devops-2020" - -Configure your policies in the **Policies** page. See the following sections for descriptions of each policy type. Select **Save changes** to apply your new policy configuration. - -![Screenshot that shows the Policies tab.](media/branch-policies/save-policy-changes.png) - -::: moniker-end - # [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" @@ -157,10 +137,8 @@ az repos policy show --id [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - *** - ## Require a minimum number of reviewers @@ -175,27 +153,30 @@ To set the policy, under **Branch Policies**, set **Require a minimum number of :::image type="content" source="media/branch-policies/require-minimum-reviewers-2020.png" alt-text="Screenshot that shows the Enable the Require Code Reviews policy."::: -- Select **Allow requestors to approve their own changes** to allow a PR's creator to vote on its approval. Otherwise, the creator can still vote **Approve** on the PR, but their vote won't count toward the minimum number of reviewers. +- Select **Allow requestors to approve their own changes** to allow a PR's creator to vote on its approval. Otherwise, the creator can still vote **Approve** on the PR, but their vote does't count toward the minimum number of reviewers. - Select **Prohibit the most recent pusher from approving their own changes** to enforce segregation of duties. By default, anyone with push permission on the source branch can both add commits and vote on PR approval. Selecting this option means the most recent pusher's vote doesn't count, even if they can ordinarily approve their own changes. - Select **Allow completion even if some reviewers vote to wait or reject** to allow PR completion even if some reviewers vote against approval. The minimum number of reviewers must still approve. -- Under **When new changes are pushed**: +::: moniker-end +::: moniker range=">= azure-devops-2020 < azure-devops-2022" + +- Under **When new changes are pushed**: - Select **Require at least one approval on the last iteration** to require at least one approval vote for the last source branch change. - - Select **Reset all approval votes (does not reset votes to reject or wait)** to remove all approval votes, but keep votes to reject or wait, whenever the source branch changes, + - Select **Reset all approval votes (does not reset votes to reject or wait)** to remove all approval votes, but keep votes to reject or wait, whenever the source branch changes. - Select **Reset all code reviewer votes** to remove all reviewer votes whenever the source branch changes, including votes to approve, reject, or wait. ::: moniker-end -::: moniker range="< azure-devops-2020" +::: moniker range=">= azure-devops-2022" -![Check the Require Code Reviews box](media/branch-policies/require-minimum-number-of-pr-reviews-2018.png) - -- If **Requestors can approve their own changes** isn't selected, the creator of the pull request can still vote **Approve** on their pull request, but their vote won't count toward the **Minimum number of reviewers**. -- If any reviewer rejects the changes, the pull request can't complete unless you select **Allow completion even if some reviewers vote to wait or reject**. -- You can reset code reviewer votes when new changes are pushed to the source branch. Select **Reset code reviewer votes when there are new changes**. +- Under **When new changes are pushed**: + - Select **Require at least one approval on every iteration** to require at least one approval vote for the last source branch change. The user's approval isn't counted against any previous unapproved iteration pushed by that user. As a result, another approval on the last iteration is required to be done by another user. **Require at least one approval on every iteration** is available in Azure DevOps Server 2022.1 and higher. + - Select **Require at least one approval on the last iteration** to require at least one approval vote for the last source branch change. + - Select **Reset all approval votes (does not reset votes to reject or wait)** to remove all approval votes, but keep votes to reject or wait, whenever the source branch changes. + - Select **Reset all code reviewer votes** to remove all reviewer votes whenever the source branch changes, including votes to approve, reject, or wait. ::: moniker-end @@ -304,11 +285,9 @@ az repos policy approver-count update --id [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - *** - - + ## Check for linked work items @@ -324,11 +303,6 @@ To set the policy, under **Branch Policies**, set **Check for linked work items* ::: moniker-end -::: moniker range="< azure-devops-2020" - -![Require linked work items in your pull requests](media/branch-policies/work-item-linking-2018.png) - -::: moniker-end # [Azure DevOps CLI](#tab/azure-devops-cli) @@ -337,7 +311,7 @@ To set the policy, under **Branch Policies**, set **Check for linked work items* You can use Azure CLI [az repos policy work-item-linking](/cli/azure/repos/policy/work-item-linking#az-repos-policy-work-item-linking) to create and update work item linking policies for a branch or repository. - + ### Create work item linking policy @@ -369,7 +343,7 @@ az repos policy work-item-linking create --blocking {false, true} |`project`, `p`|Name or ID of the project. You can configure the default project using `az devops configure -d project=`. **Required** if not configured as default or picked up via git config.| |`subscription`|Name or ID of subscription. You can configure the default subscription using `az account set -s `.| - + ### Update work item linking policy @@ -411,7 +385,6 @@ The following example updates the policy ID `3` for the `main` branch of the Fab ```azurecli >az repos policy work-item-linking update --id 3 --blocking false --branch main --enabled true --repository-id d28cd374-e7f0-4b1f-ad60-f349f155d47c --output table - ID Name Is Blocking Is Enabled Repository Id Branch ---- ----------------- ------------- ------------ ------------------------------------ --------------- 3 Work item linking False True d28cd374-e7f0-4b1f-ad60-f349f155d47c refs/heads/main @@ -421,11 +394,8 @@ ID Name Is Blocking Is Enabled Repository Id [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - *** - - ## Check for comment resolution @@ -438,19 +408,9 @@ The **Check for comment resolution** policy checks whether all PR comments are r Configure a comment resolution policy for your branch by setting **Check for comment resolution** to **On**. Then select whether to make the policy **Required** or **Optional**. -:::image type="content" source="media/branch-policies/check-comment-resolution-2020.png" alt-text="Check for comment resolution"::: - -For more information on working with pull request comments, see [Review pull requests](review-pull-requests.md#make-comments). - -::: moniker-end - -::: moniker range="< azure-devops-2020" +:::image type="content" source="media/branch-policies/check-comment-resolution-2020.png" alt-text="Screenshot of Check for comment resolution."::: -Configure a comment resolution policy for your branch by selecting **Check for comment resolution**. - -![Check for comment resolution](media/branch-policies/comment-resolution-2018.png) - -For more information on working with pull request comments, see [Review pull requests](review-pull-requests.md#make-comments). +For more information on working with pull request comments, see [Review pull requests](review-pull-requests.md). ::: moniker-end @@ -536,14 +496,10 @@ ID Name Is Blocking Is Enabled Repository Id ::: moniker-end - - [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - *** - ::: moniker range=">= azure-devops-2020" @@ -560,22 +516,17 @@ Azure Repos has several merge strategies, and by default, all of them are allowe Set **Limit merge types** to **On** to limit which merge types to allow in your repo. -:::image type="content" source="media/branch-policies/limit-merge-types-2020.png" alt-text="Limit merge types"::: +:::image type="content" source="media/branch-policies/limit-merge-types-2020.png" alt-text="Screenshot of Limit merge types."::: - **Basic merge (no fast-forward)** creates a merge commit in the target whose parents are the target and source branches. - **Squash merge** creates a linear history with a single commit in the target branch with the changes from the source branch. [Learn more about squash merging](merging-with-squash.md) and how it affects branch history. - **Rebase and fast-forward** creates a linear history by replaying source commits onto the target branch with no merge commit. - **Rebase with merge commit** replays the source commits onto the target and also creates a merge commit. -::: moniker-end -::: moniker range="< azure-devops-2020" -> [!NOTE] -> This feature is available for Azure DevOps Server 2020 and later versions. ::: moniker-end # [Azure DevOps CLI](#tab/azure-devops-cli) - ::: moniker range="azure-devops" You can use Azure DevOps CLI [az repos policy merge-strategy](/cli/azure/repos/policy/merge-strategy) to set and update merge strategy policy. @@ -676,27 +627,13 @@ az repos policy merge-strategy update --id ::: moniker-end - [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] *** -::: moniker range="< azure-devops-2020" - -## Enforce a merge strategy - -Maintain a consistent branch history by enforcing a merge strategy when a pull request completes. -Select **Enforce a merge strategy** and pick an option to require that pull requests merge using that strategy. - -![Set merge requirements](media/branch-policies/merge-requirements-2018.png) - -- **No fast-forward merge** - This option merges the commit history of the source branch when the pull request closes and creates a merge commit in the target branch. -- **Squash merge** - Complete all pull requests with a squash merge, creating a single commit in the target branch with the changes from the source branch. [Learn more about squash merging](merging-with-squash.md) and how it affects your branch history. - -::: moniker-end - + @@ -712,7 +649,7 @@ Build policies reduce breaks and keep your test results passing. Build policies A build validation policy queues a new build when a new PR is created or changes are pushed to an existing PR that targets the branch. The build policy evaluates the build results to determine whether the PR can be completed. > [!IMPORTANT] -> Before specifying a build validation policy, you must have a build pipeline. If you don't have a pipeline, see [Create a build pipeline](../../pipelines/create-first-pipeline.md). Choose the type of build that matches your project type. +> Before specifying a build validation policy, have a build pipeline. If you don't have a pipeline, see [Create a build pipeline](../../pipelines/create-first-pipeline.md). Choose the type of build that matches your project type. ::: moniker-end @@ -728,7 +665,7 @@ To add a build validation policy 1. Fill out the **Set build policy** form: - :::image type="content" source="media/branch-policies/add-build-policy-menu-2020.png" alt-text="Build policy settings"::: + :::image type="content" source="media/branch-policies/add-build-policy-menu-2020.png" alt-text="Screenshot of Build policy settings."::: - Select the **Build pipeline**. @@ -742,11 +679,11 @@ To add a build validation policy - **Immediately when \ is updated**: This option sets PR build policy status to *failed* whenever the branch is updated, and requeues a build. This setting ensures that the PR changes build successfully even if the protected branch changes. - This option is best for teams whose important branches have few changes. Teams working in busy development branches may find it disruptive to wait for a build every time the branch updates. + This option is best for teams whose important branches have few changes. Teams working in busy development branches might find it disruptive to wait for a build every time the branch updates. - **After \ hours if \ has been updated**: This option expires the current policy status when the protected branch updates if the passing build is older than the threshold you enter. This option is a compromise between always or never requiring a build when the protected branch updates. This choice reduces the number of builds when your protected branch has frequent updates. - - **Never**: Updates to the protected branch don't change the policy status. This value reduces the number of builds, but can cause problems when completing PRs that haven't updated recently. + - **Never**: Updates to the protected branch don't change the policy status. This value reduces the number of builds, but can cause problems when completing PRs that weren't updated recently. - Enter an optional **Display name** for this build policy. This name identifies the policy on the **Branch policies** page. If you don't specify a display name, the policy uses the build pipeline name. @@ -758,11 +695,6 @@ If you have an **Immediately when \ is updated** or **After \ ho ::: moniker-end -::: moniker range="< azure-devops-2020" -> [!NOTE] -> This feature is available for Azure DevOps Server 2020 and later versions. -::: moniker-end - # [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" @@ -807,7 +739,7 @@ az repos policy build create --blocking {false, true} |`branch-match-type`|Use the `branch` argument to apply the policy. If the value is `exact`, the policy applies on a branch that exactly matches the `--branch` argument. If the value is `prefix`, the policy applies across all branch folders that match the prefix in the `--branch` argument. Accepted values: `exact`, `prefix`. Default value: `exact`.| |`detect`|Automatically detect organization. Accepted values: `false`, `true`.| |`org`|Azure DevOps organization URL. You can configure the default organization by using `az devops configure -d organization=`. **Required** if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`.| -|`path-filter`|Path(s) on which to apply the policy is applied. Supports absolute paths, wildcards, and multiple paths separated by `;`. Examples: `/WebApp/Models/Data.cs`, `/WebApp/*`, or `*.cs,` or `/WebApp/Models/Data.cs;ClientApp/Models/Data.cs`.| +|`path-filter`|Path on which to apply the policy is applied. Supports absolute paths, wildcards, and multiple paths separated by `;`. Examples: `/WebApp/Models/Data.cs`, `/WebApp/*`, or `*.cs,` or `/WebApp/Models/Data.cs;ClientApp/Models/Data.cs`.| |`project`, `p`|Name or ID of the project. You can configure the default project using `az devops configure -d project=`. **Required** if not configured as default or picked up via git config.| |`subscription`|Name or ID of subscription. You can configure the default subscription using `az account set -s `.| @@ -823,7 +755,6 @@ ID Name Is Blocking Is Enabled Repository Id 31 build-policy True True d28cd374-e7f0-4b1f-ad60-f349f155d47c refs/heads/main ``` - ### Update a build validation policy Use [az repos policy build update](/cli/azure/repos/policy/build#az-repos-policy-build-update) to update a build validation policy. @@ -861,7 +792,7 @@ az repos policy build update --id |`enabled`|Enable the policy. Accepted values: `false`, `true`.| |`manual-queue-only`|Whether to allow only manual queue of builds. Accepted values: `false`, `true`.| |`org`|Azure DevOps organization URL. You can configure the default organization by using `az devops configure -d organization=`. **Required** if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`.| -|`path-filter`|Path(s) on which to apply the policy is applied. Supports absolute paths, wildcards, and multiple paths separated by `;`. Examples: `/WebApp/Models/Data.cs`, `/WebApp/*`, or `*.cs,` or `/WebApp/Models/Data.cs;ClientApp/Models/Data.cs`.| +|`path-filter`|Paths on which to apply the policy is applied. Supports absolute paths, wildcards, and multiple paths separated by `;`. Examples: `/WebApp/Models/Data.cs`, `/WebApp/*`, or `*.cs,` or `/WebApp/Models/Data.cs;ClientApp/Models/Data.cs`.| |`project`, `p`|Name or ID of the project. You can configure the default project using `az devops configure -d project=`. **Required** if not configured as default or picked up via git config.| |`queue-on-source-update-only`|Whether to queue builds only when source updates. Accepted values: `false`, `true`.| |`repository-id`|ID of the repository to filter results by exact match. For example, `--repository-ID e556f204-53c9-4153-9cd9-ef41a11e3345`.| @@ -870,79 +801,32 @@ az repos policy build update --id ::: moniker-end - [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] *** -::: moniker range="< azure-devops-2020" - -Set a policy requiring changes in a pull request to build successfully with the protected branch before the pull request can be completed. -Build policies reduce breaks and keep your test results passing. Build policies help even if you're using [continuous integration](/devops/develop/what-is-continuous-integration) (CI) on your development branches to catch problems early. - -If a build validation policy is enabled, a new build is queued when either a new pull request is created, or if changes are pushed to an existing pull request targeting the branch. The build policy then evaluates the results of the build to determine whether the pull request can be completed. - -> [!IMPORTANT] -> Before specifying a build validation policy, you must have a build definition. If you don't have one, see [Create a build definition](/previous-versions/azure/devops/pipelines/apps/) and choose the type of build that matches your project type. - -![Add build policy](media/branch-policies/add-build-policy-2018.png) - -Choose **Add build policy** and configure your options in **Add build policy**. - -![Build policy settings](media/branch-policies/build-policy-settings-2018.png) - -1. Select the **Build definition**. -1. Choose the type of **Trigger**. Select **Automatic (whenever the source branch is updated)** or **Manual**. -1. Select the **Policy requirement**. If you choose **Required**, builds must complete successfully to complete pull requests. Choose **Optional** to provide a notification of the build failure but still allow pull requests to complete. -1. Set a build expiration to make sure that updates to your protected branch don't break changes for open pull requests. - - - **Immediately when `branch name` is updated**: This option sets the build policy status in a pull request to *failed* when the protected branch is updated. Requeue a build to refresh the build status. This setting ensures that the changes in pull requests build successfully even as the protected branch changes. This option is best for teams that have important branches with a lower volume of changes. Teams working in busy development branches may find it disruptive to wait for a build to complete every time the protected branch is updated. - - **After `n` hours if `branch name` has been updated**: This option expires the current policy status when the protected branch updates if the passing build is older than the threshold entered. This option is a compromise between always requiring a build when the protected branch updates and never requiring one. This choice is excellent for reducing the number of builds when your protected branch has frequent updates. - - **Never**: Updates to the protected branch don't change the policy status. This value reduces the number of builds for your branch. It can cause problems when closing pull requests that haven't updated recently. - -1. Enter an optional **Display name** for this build policy. This name identifies the policy on the **Branch policies** page. If you don't specify a display name, the policy uses the build definition name. -1. Select **Save**. - -When the owner pushes changes that build successfully, the policy status is updated. If you have an **Immediately when `branch name` is updated** or **After `n` hours if `branch name` has been updated** build policy chosen, the policy status updates when the protected branch is updated if the most recent build is no longer valid. - -::: moniker-end - ::: moniker range=">= azure-devops-2020" ## Status checks -External services can use the PR [Status API](/rest/api/azure/devops/git/pull%20request%20statuses) to post detailed status to your PRs. The branch policy for additional services enables those third-party services to participate in the PR workflow and establish policy requirements. +External services can use the PR [Status API](/rest/api/azure/devops/git/pull%20request%20statuses) to post detailed status to your PRs. The branch policy for additional services enables those external services to participate in the PR workflow and establish policy requirements. -:::image type="content" source="media/branch-policies/status-checks-2020.png" alt-text="Require external services to approve"::: +:::image type="content" source="media/branch-policies/status-checks-2020.png" alt-text="Screenshot of Require external services to approve."::: For instructions on configuring this policy, see [Configure a branch policy for an external service](pr-status-policy.md). ::: moniker-end -::: moniker range=">= tfs-2018 < azure-devops-2020" - - - -## Require approval from external services - -External services can use the PR [Status API](/rest/api/azure/devops/git/pull%20request%20statuses) to post detailed status to your PRs. The branch policy for additional services brings the ability for those third-party services to participate in the PR workflow and establish policy requirements. - -![Require external services to approve](media/branch-policies/require-approval-from-additional-services-2018.png) - -For instructions on configuring this policy, see [Configure a branch policy for an external service](pr-status-policy.md). - -::: moniker-end + - ::: moniker range=">=azure-devops-2020" ## Automatically include code reviewers - You can automatically add reviewers to pull requests that change files in specific directories and files, or to all pull requests in a repo. ::: moniker-end @@ -976,11 +860,6 @@ You can automatically add reviewers to pull requests that change files in specif 1. Select **Save**. ::: moniker-end -::: moniker range="< azure-devops-2020" -> [!NOTE] -> This feature is available for Azure DevOps Server 2020 and later versions. -::: moniker-end - # [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" @@ -1019,7 +898,7 @@ az repos policy required-reviewer create --blocking {false, true} |`branch-match-type`|Use the `branch` argument to apply the policy. If the value is `exact`, the policy applies on a branch that exactly matches the `--branch` argument. If the value is `prefix`, the policy applies across all branch folders that match the prefix in the `--branch` argument. Accepted values: `exact`, `prefix`. Default value: `exact`.| |`detect`|Automatically detect organization. Accepted values: `false`, `true`.| |`org`|Azure DevOps organization URL. You can configure the default organization by using `az devops configure -d organization=`. **Required** if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`.| -|`path-filter`|Path(s) on which to apply the policy is applied. Supports absolute paths, wildcards, and multiple paths separated by `;`. Examples: `/WebApp/Models/Data.cs`, `/WebApp/*`, or `*.cs,` or `/WebApp/Models/Data.cs;ClientApp/Models/Data.cs`.| +|`path-filter`|Paths on which to apply the policy is applied. Supports absolute paths, wildcards, and multiple paths separated by `;`. Examples: `/WebApp/Models/Data.cs`, `/WebApp/*`, or `*.cs,` or `/WebApp/Models/Data.cs;ClientApp/Models/Data.cs`.| |`project`, `p`|Name or ID of the project. You can configure the default project using `az devops configure -d project=`. **Required** if not configured as default or picked up via git config.| |`subscription`|Name or ID of subscription. You can configure the default subscription using `az account set -s `.| @@ -1068,7 +947,7 @@ az repos policy required-reviewer update --id |`enabled`|Enable the policy. Accepted values: `false`, `true`.| |`message`|Activity feed message that appears in the pull request.| |`org`|Azure DevOps organization URL. You can configure the default organization by using `az devops configure -d organization=`. **Required** if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`.| -|`path-filter`|Path(s) on which to apply the policy is applied. Supports absolute paths, wildcards, and multiple paths separated by `;`. Examples: `/WebApp/Models/Data.cs`, `/WebApp/*`, or `*.cs,` or `/WebApp/Models/Data.cs;ClientApp/Models/Data.cs`.| +|`path-filter`|Paths on which to apply the policy is applied. Supports absolute paths, wildcards, and multiple paths separated by `;`. Examples: `/WebApp/Models/Data.cs`, `/WebApp/*`, or `*.cs,` or `/WebApp/Models/Data.cs;ClientApp/Models/Data.cs`.| |`project`, `p`|Name or ID of the project. You can configure the default project using `az devops configure -d project=`. **Required** if not configured as default or picked up via git config.| |`repository-id`|ID of the repository to filter results by exact match. For example, `--repository-ID e556f204-53c9-4153-9cd9-ef41a11e3345`.| |`required-reviewer-ids`|Reviewer email addresses separated by `;`. For example: `john@contoso.com;alice@contoso.com`.| @@ -1076,47 +955,17 @@ az repos policy required-reviewer update --id ::: moniker-end - [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] *** -::: moniker range="<= azure-devops-2019" - -Select reviewers for specific directories and files in your repo. - -![Enter the path and required reviewers](media/branch-policies/require-specific-reviewers-2018.png) - -These reviewers are automatically added to pull requests that change files along those paths. You can also specify an **Activity feed message**. - -![Add automatic reviewers](media/branch-policies/automatically-include-reviewers-for-pull-requests-2018.png) - -If you select **Required**, then the pull request can't be completed until: - -- Every user added as a reviewer for the path approves the changes. -- At least one person in every group added to the path approves the changes. -- The number of reviewers specified for every group added to the path approves the changes. - -![Required reviewers are automatically added](media/branch-policies/required-reviewer-added.png) - -Select **Optional** if you want to add reviewers automatically, but not require their approval to complete the pull request. - -You can select **Requestors can approve their own changes**. - -When all required reviewers approve the code, you can complete the pull request. - -![Pull request status shows that reviewers have approved](media/branch-policies/required-reviewer-approved.png) - - -::: moniker-end - ## Bypass branch policies In some cases, you might need to bypass policy requirements. Bypass permissions let you push changes to a branch directly, or complete pull requests that don't satisfy branch policies. You can grant bypass permissions to a user or group. You can scope bypass permissions to an entire project, a repo, or a single branch. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Two permissions allow users to bypass branch policy in different ways: - **Bypass policies when completing pull requests** applies only to pull request completion. Users with this permission can complete pull requests even if the pull requests don't satisfy policies. @@ -1125,23 +974,14 @@ Two permissions allow users to bypass branch policy in different ways: ![Screenshot showing bypass policy enforcement permissions.](media/branch-policies/policy-exempt-permission.png) -For more information about managing these permissions, see [Git permissions](../../organizations/security/permissions.md#git-repository-permissions-object-level). - -::: moniker-end - -::: moniker range="<=azure-devops-2019" - -In TFS 2015 through TFS 2018 Update 2, the **Exempt from policy enforcement** permission allows users with this permission to perform the following actions: - -- When completing a pull request, opt-in to override policies and complete a pull request even if the current set of branch policies is not satisfied. -- Push directly to a branch even if that branch has branch policies set. Note that when a user with this permission makes a push that would override branch policy, the push automatically bypasses branch policy with no opt-in step or warning. +For more information about managing these permissions, see [Git permissions](../../organizations/security/about-permissions.md#permission-inheritance). ::: moniker-end > [!IMPORTANT] > Use caution when granting the ability to bypass policies, especially at the repo and project levels. Policies are a cornerstone of secure and compliant source code management. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Path filters @@ -1178,12 +1018,11 @@ The order of filters is significant. Filters are applied left-to-right. - [How can I configure multiple users as required reviewers, but require only one of them to approve?](#how-can-i-configure-multiple-users-as-required-reviewers-but-require-only-one-of-them-to-approve) - [I have bypass policy permissions. Why do I still see policy failures in the pull request status?](#i-have-bypass-policy-permissions-why-do-i-still-see-policy-failures-in-the-pull-request-status) - [Why can't I complete my own pull requests when "Allow requestors to approve their own changes" is set?](#why-cant-i-complete-my-own-pull-requests-when-allow-requestors-to-approve-their-own-changes-is-set) -- [What happens when path in path filters start neither with `/` nor with wildcard?](#what-happens-when-path-in-path-filters-start-neither-with--nor-with-wildcard) - +- [What happens when path in path filters doesn't start with `/` or with a wildcard?](#what-happens-when-path-in-path-filters-doesnt-start-with--or-with-a-wildcard) #### Can I push changes directly to branches that have branch policies? -You can't push changes directly to branches that have *required* branch policies unless you have permissions to [bypass branch policies](#bypass-branch-policies). Changes to these branches can be made only through [pull requests](pull-requests.md). You can push changes directly to branches that have *optional* branch policies, if they have no required branch policies. +You can't push changes directly to branches with *required* branch policies unless you have permissions to [bypass branch policies](#bypass-branch-policies). Changes to these branches can be made only through [pull requests](pull-requests.md). You can push changes directly to branches that have *optional* branch policies, if they have no required branch policies. #### What is autocomplete? @@ -1207,7 +1046,7 @@ Examples: - `*.sql` matches all files with the *.sql* extension. - `/ConsoleApplication/*` matches all files under the folder named *ConsoleApplication*. -- `/.gitattributes` matches the *.gitattributes* file in the root of the repo. +- `/.gitattributes` matches the.gitattributes* file in the root of the repo. - `*/.gitignore` matches any *.gitignore* file in the repo. #### Are the required code reviewer paths case-sensitive? @@ -1216,7 +1055,7 @@ No, branch policies aren't case-sensitive. #### How can I configure multiple users as required reviewers, but require only one of them to approve? -You can [add the users to a group](../../organizations/security/add-users-team-project.md), and then add the group as a reviewer. Any member of the group can then approve to meet the policy requirement. +You can [add the users to a group](../../organizations/security/add-users-team-project.md), and then add the group as a reviewer. Any member of the group can then approve to meet the policy requirement. #### I have bypass policy permissions. Why do I still see policy failures in the pull request status? @@ -1237,11 +1076,9 @@ In this case, your approval satisfies **Automatically included reviewers**, but There might also be other policies, such as **Prohibit the most recent pusher from approving their own changes**, that prevent you from approving your own changes even if **Allow requestors to approve their own changes** is set. -#### What happens when path in path filters start neither with `/` nor with wildcard? - - -The path in path filters that start neither with `/` nor with a wildcard will have no effect, and the path filter will evaluate as if that path wasn't specified. That's because such a path can't match the `/` the absolute file path starts with. +#### What happens when path in path filters doesn't start with `/` or with a wildcard? +The path in path filters that doesn't start with `/` or with a wildcard has no effect, and the path filter evaluates as if that path wasn't specified. Such a path can't match the `/` the absolute file path starts with. ## Related articles @@ -1250,3 +1087,4 @@ The path in path filters that start neither with `/` nor with a wildcard will ha - [Default Git permissions (Security)](../../organizations/security/default-git-permissions.md?toc=/azure/devops/repos/toc.json&bc=/azure/devops/repos/breadcrumb/toc.json) - [Set permissions (Security)](set-git-repository-permissions.md?toc=/azure/devops/repos/toc.json&bc=/azure/devops/repos/breadcrumb/toc.json) - [Cross-service integration overview](../../cross-service/cross-service-overview.md?toc=/azure/devops/repos/toc.json&bc=/azure/devops/repos/breadcrumb/toc.json) +- [Azure DevOps REST API: Policy](/rest/api/azure/devops/policy) \ No newline at end of file diff --git a/docs/repos/git/change-default-branch.md b/docs/repos/git/change-default-branch.md index f0875e698d1..5831952230d 100644 --- a/docs/repos/git/change-default-branch.md +++ b/docs/repos/git/change-default-branch.md @@ -20,6 +20,10 @@ We'll walk through the process of changing the default branch. We'll also cover other things you must consider and update when making this change. Finally, we'll look at a tool for easing the transition. +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## Set a new default branch [!INCLUDE [](includes/change-default-branch-instructions.md)] @@ -101,7 +105,7 @@ trigger: branches: include: - main - - main + - master pool: { vmImage: ubuntu-latest } steps: diff --git a/docs/repos/git/cherry-pick.md b/docs/repos/git/cherry-pick.md index f785c27ab27..ce1494e306e 100644 --- a/docs/repos/git/cherry-pick.md +++ b/docs/repos/git/cherry-pick.md @@ -25,6 +25,10 @@ You can cherry-pick to tackle these common tasks: For an overview of the Git workflow, see [Azure Repos Git tutorial](gitworkflow.md). +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## Cherry-pick a commit #### [Browser](#tab/browser/) diff --git a/docs/repos/git/clone.md b/docs/repos/git/clone.md index 7bac35befee..11066441c49 100644 --- a/docs/repos/git/clone.md +++ b/docs/repos/git/clone.md @@ -29,7 +29,7 @@ This article provides procedures for the following tasks: For an overview of the Git workflow, see [Azure Repos Git tutorial](gitworkflow.md). -## Prerequisites for access to Azure Repos +## Prerequisites [!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] @@ -71,6 +71,9 @@ Typically, you need to know the clone URL of the remote repo that you want to cl :::image type="content" source="media/clone/visual-studio-2019/common/github-clone-repo.png" border="true" alt-text="Screenshot of the Clone popup on the page on the GitHub site." lightbox="media/clone/visual-studio-2019/common/github-clone-repo-lrg.png"::: +> [!IMPORTANT] +> The "Generate Git Credentials" button will be removed in January 2025, to reduce creation of unnecessary and underutilized personal access tokens. Review the Git Authentication docs for all authentication methods available to you for git clone operations. + ## Clone an Azure Repos Git repo By signing in as a member of an Azure DevOps project, you can clone private repos that are accessible to you, and public repos. Visual Studio supports search, clone, and sync operations on repos that are accessible through authentication. diff --git a/docs/repos/git/command-prompt.md b/docs/repos/git/command-prompt.md index 430c27c4803..1155032cb59 100644 --- a/docs/repos/git/command-prompt.md +++ b/docs/repos/git/command-prompt.md @@ -309,7 +309,7 @@ For more information, see the following resources: `git branch -d` *branchname* :::column-end::: :::column span="1"::: - Open the **Branches** view in Team Explorer, then right-click the branch and select **Delete**. You must be checked out to a different branch than the one you want to delete. + Open the **Branches** view in Team Explorer, then right-click the branch and select **Delete**. Be checked out to a different branch than the one you want to delete. :::column-end::: :::column span="1"::: From the **Git** menu on the menu bar, select **Manage Branches**, then right-click a branch and select **Delete** @@ -514,7 +514,7 @@ For more information, see the following resources: :::row-end::: --- -To learn more, see [Save your work with commits](commits.md). +For more information, see [Save your work with commits](commits.md). ## Compare files and versions @@ -575,7 +575,7 @@ To learn more, see [Save your work with commits](commits.md). :::row-end::: --- -To learn more, see [Compare versions and review history](review-history.md). +For more information, see [Compare versions and review history](review-history.md). ## Sync changes diff --git a/docs/repos/git/commit-details.md b/docs/repos/git/commit-details.md index 0642910f5ea..0598939fb95 100644 --- a/docs/repos/git/commit-details.md +++ b/docs/repos/git/commit-details.md @@ -11,10 +11,8 @@ monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- - # Commit details - [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -23,10 +21,6 @@ The commit details view provides information regarding all the changes made as p ::: moniker range=">= azure-devops-2020" :::image type="content" source="media/commit-details/git-repo-file-history.png" alt-text="Files, Commits page example"::: ::: moniker-end -::: moniker range="<= azure-devops-2019" -![Commit details page](media/commit-details/1Commitdetails.png) -::: moniker-end - ## What information do you see on the commit details page? @@ -87,4 +81,3 @@ The source explorer allows you to select a file or a folder to view changes asso ![Diff view](media/commit-details/11SidebySide.png) - diff --git a/docs/repos/git/commit-history.md b/docs/repos/git/commit-history.md index e2e28d60c22..abd708ae2d4 100644 --- a/docs/repos/git/commit-history.md +++ b/docs/repos/git/commit-history.md @@ -43,7 +43,7 @@ For each commit, you can view the following key elements: * Build and PR information - You can view the pull request that brought this commit to the branch selected on the page, and view the build status of the current commit. ![Build and PR details on commit history](media/commit-history/5-BuildandPRInfo.png) - + * You can select a repository from the repository picker to view the history of a particular repository. ![repository picker](media/commit-history/6-RepoPicker.png) @@ -65,9 +65,12 @@ For each commit, you can view the following key elements: You can filter the results using the following advanced filtering modes: **simple history**, **first parent**, **full history**, and **full history with simplified merges**. For more information, see [advanced git history options](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). +> [!NOTE] +> The **full history** filter reveals the complete history of changes to the selected file, as well as all PR merges that occurred before and after the changes in the current branch (even those that contain no changes to the file). This is different from the behavior of the Git client when executing the "git log --full-history \" command. +> ![Advanced filters for git log](media/commit-history/10-AdvancedFilter.png) -You can also filter commits by authors. You will see authors of most recent commits in the author filter drop down. In case you are not able to find an author in the drop down, then you can type the author name or email address and search for all commits by that author. +You can also filter commits by authors. You'll see authors of most recent commits in the author filter drop down. In case you aren't able to find an author in the drop down, then you can type the author name or email address and search for all commits by that author. ![Author filter](media/commit-history/11-AuthorFilter.png) @@ -77,13 +80,13 @@ In case you want to view commits that were authored between any two dates, you c ## Commit search -You can also search for a commit using its Commit ID. You can search for all commits starting with a commit ID. If you enter the 40 character Commit ID then you will be redirected directly to the commit details page. +You can also search for a commit using its Commit ID. You can search for all commits starting with a commit ID. If you enter the 40 character Commit ID then you'll be redirected directly to the commit details page. ![Commit search page](media/commit-history/13-SearchCommit.png) ## Commit for file renames -In case a file or folder is renamed, you will see all commits until the file or folder got renamed. You will also see a link suggesting **Show rename history**. +In case a file or folder is renamed, you'll see all commits until the file or folder got renamed. You'll also see a link suggesting **Show rename history**. ![Show rename files or folder history](media/commit-history/renamefiles.png) diff --git a/docs/repos/git/commits.md b/docs/repos/git/commits.md index e9fd6cb6118..15281717afb 100644 --- a/docs/repos/git/commits.md +++ b/docs/repos/git/commits.md @@ -28,6 +28,10 @@ This article provides procedures for the following tasks: For an overview of the Git workflow, see [Azure Repos Git tutorial](gitworkflow.md). +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## How Git tracks changes As you work in your repo, Git tracks changes to all _tracked_ files. Tracked files are files that are currently staged or are included in the previous commit. Git separates tracked files into three categories: diff --git a/docs/repos/git/complete-pull-requests.md b/docs/repos/git/complete-pull-requests.md index 7783f96ef0b..cfce2584f5c 100644 --- a/docs/repos/git/complete-pull-requests.md +++ b/docs/repos/git/complete-pull-requests.md @@ -10,6 +10,7 @@ author: vijayma ms.date: 03/31/2022 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git +ms.custom: devx-track-azurecli --- # Complete, abandon, or revert pull requests @@ -23,39 +24,12 @@ To address reviewers' changes, and respond to and resolve review comments, see [ ## Prerequisites -::: moniker range="azure-devops" -- **Repos** must be enabled on your project. If the **Repos** hub and associated pages don't display, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md) to reenable Repos. - -- To complete your PR, you must be a member of the **Contributors** security group, or have the corresponding permissions, in the project the PR is in. - -- To contribute to a PR, you must be a member of the **Readers** security group or have the corresponding permissions. +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] -- To view or review PRs, you must have **Basic** or higher access to the Azure DevOps project. - -- If you aren't a member of the project you want to contribute to, [get added](../../organizations/accounts/add-organization-users.md). - - > [!NOTE] - > For public projects, users granted **Stakeholder** access have full access to Azure Repos. -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" -- **Repos** must be enabled on your project. If the **Repos** hub and associated pages don't display, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md) to reenable Repos. -- To complete a PR, you must be a member of the **Contributors** security group, or have the corresponding permissions, in the project you want to change. -- To contribute to a PR, you must be a member of the **Readers** security group or have the corresponding permissions. -- To view or review PRs, you must be a member of the Azure DevOps project with **Basic** access or higher. If you aren't a project member, [get added](../../organizations/security/add-users-team-project.md). -::: moniker-end - -::: moniker range="< azure-devops-2019" -- To complete a PR, you must be a member of the **Contributors** security group for the Azure DevOps project, or have the corresponding permissions. -- To view or review PRs, you must be a member of the Azure DevOps project with **Basic** access or higher. If you aren't a project member, [get added](../../organizations/security/add-users-team-project.md). -- To contribute to a PR, you must be a member of the **Readers** security group for the Azure DevOps project or have the corresponding permissions. - -::: moniker-end - -- To learn more about permissions and access, see [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) and [About access levels](../../organizations/security/access-levels.md). +For more information about permissions and access, see [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) and [About access levels](../../organizations/security/access-levels.md). ::: moniker range="azure-devops" -- In Azure DevOps Services, you can manage PRs and other resources from the [Azure command-line interface (CLI)](/cli/azure/) with the `azure-devops` extension. To learn how to work with the Azure DevOps Services CLI, see [Get started with Azure DevOps CLI](../../cli/index.md). Azure Repos CLI commands for PRs use [az repos pr](/cli/azure/repos/pr). +In Azure DevOps Services, you can manage PRs and other resources from the [Azure command-line interface (CLI)](/cli/azure/) with the `azure-devops` extension. To learn how to work with the Azure DevOps Services CLI, see [Get started with Azure DevOps CLI](../../cli/index.md). Azure Repos CLI commands for PRs use [az repos pr](/cli/azure/repos/pr). ::: moniker-end ## Check merge changes @@ -143,10 +117,8 @@ a6e4380e-9f38-4aa5-863c-0fc496027362 Work item linking [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - *** - ## Complete a pull request @@ -189,7 +161,7 @@ After you resolve any merge conflicts, and the PR meets all branch policies and ::: moniker-end -::: moniker range=">= azure-devops-2019 <= azure-devops-2020" +::: moniker range="=azure-devops-2020" 1. Select **Complete** at upper right to complete the PR. Or, select the dropdown arrow next to the **Complete** button, and select one of the following options: @@ -217,42 +189,13 @@ After you resolve any merge conflicts, and the PR meets all branch policies and ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" When you complete the merge, any [linked work items](pull-requests.md#link-work-items) automatically update to show the PR completion. ![Screenshot of linked work items showing completed P Rs.](./media/complete-pull-requests/pr-workitem-complete.png) ::: moniker-end -::: moniker range="tfs-2018" - -1. Select **Complete** in the upper right of the PR view to complete your PR after the reviewers approve of the changes. - - ![Complete button for the PR with its drop-down options](./media/complete-pull-requests/old-complete-pr-options.png) - - - **Complete**: Complete the PR now and merge the changes to the target branch. - - **Set auto-complete**: If you have branch policies, you can choose **Set auto-complete** to configure the PR to close once it meets all branch policies. - - **Abandon**: Close the PR without merging the changes. - -2. In **Complete pull request**, enter the message for the [merge commit](merging.md) and update the PR description. - - ![Complete PR dialog](./media/complete-pull-requests/complete-pr-dialog.png) - -3. Select any of the following post-completion options: - - - **Complete linked work items after merging** to complete any linked work items. - - **Delete `` after merging** to delete the source branch from the PR. - - **Squash changes when merging** to [squash merge](merging-with-squash.md) your PR. Be aware that a new commit will be created for the target branch without keeping the commit history from the source branch. - - **Override branch policies and enable merge** to force a branch to merge even if it doesn't satisfy all branch policies. This option is only available if you have [Exempt from policy enforcement](branch-policies.md#bypass-branch-policies) permissions. - -4. Select **Complete merge**. - -Linked work items are also updated showing the PR completion. - -![Linked Work Items showing completed PRs](./media/complete-pull-requests/pr-workitem-complete.png) - -::: moniker-end - # [Visual Studio](#tab/visual-studio) To complete a PR, open the PR in the browser, and on the **Overview** page, select **Complete** or set other options. @@ -281,7 +224,7 @@ For example, to complete PR #21, use: az repos pr update --id 21 --status completed ``` - + ### Set completion options @@ -350,8 +293,7 @@ az repos pr update --id 21 --status completed --delete-source-branch true --tran *** - -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### Rebase during PR completion @@ -369,24 +311,18 @@ In all these cases, you can still rebase your branch locally and then push upstr In some cases, a PR has more than one true merge base, and this situation can cause security issues. If the files in the PR have different versions between the merge bases, a multiple merge base warning happens. For more information and remediation, see [Multiple merge bases](about-pull-requests.md#multiple-merge-bases). - - - ## Resolve merge conflicts File changes in your branch can conflict with changes in another branch. When it isn't clear how to merge changes, Git shows the files that conflict on the PR's **Overview** page. You must resolve any *merge conflicts* between the PR branch and the target branch before you can merge a PR or set the PR to autocomplete. For instructions on resolving merge conflicts, see [Resolve merge conflicts](merging.md). ![Screenshot that shows merge conflicts on the Overview tab of a P R.](./media/complete-pull-requests/merge-conflict.png) - - ## Set a pull request to autocomplete # [Browser](#tab/browser) - Select **Set auto-complete** from the **Complete** dropdown list to complete and merge the PR changes as soon as conditions satisfy all [branch policies](branch-policies.md). When the PR is completed, you receive an email notification. If a conflict or error prevents PR completion, email notifies you of the issue. >[!NOTE] @@ -441,10 +377,8 @@ Set autocomplete to complete a PR automatically when it passes all required appr [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - *** - @@ -497,7 +431,6 @@ To undo the changes from a PR, follow these steps. For more information, see [Un > [!NOTE] > The branch created during this revert has a single commit that reverts all the file changes from the original PR. The branch doesn't contain a reverted commit for each of the commits in the original PR. - ## Next steps > [!div class="nextstepaction"] diff --git a/docs/repos/git/configure-repos-work-tracking.md b/docs/repos/git/configure-repos-work-tracking.md deleted file mode 100644 index 9b9035fa28c..00000000000 --- a/docs/repos/git/configure-repos-work-tracking.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Configure repos and branches to integrate with work tracking -titleSuffix: Azure DevOps -description: Learn how to configure Azure Repos to support integration with Azure Boards and work tracking -ms.service: azure-devops-boards -ms.topic: overview -ms.author: vijayma -author: vijayma -monikerRange: '<= azure-devops' -ms.date: 08/02/2021 ---- - -# Configure repositories and branches to integrate with work tracking - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -To support traceability of your Git code with work tracking, you can exercise one or more features and configure several options. - - -The following table summarizes the integration points between Azure Boards and Azure Repos, Git. Through various link types, you can track code changes—commits and pull requests for Git—that support development of user stories and features. The link types used to construct these links include *Branch , Commit, Pull Request*, and *Tag*. - -:::image type="content" source="media/work-tracking/concept-link-types-repos.png" alt-text="Conceptual image of link types that link work items to Azure Repos Git objects."::: - - -:::row::: - :::column span="1"::: - **Feature** - :::column-end::: - :::column span="2"::: - **Description** - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Manually link work items to Git branches, commits, pull requests, and tags - :::column-end::: - :::column span="2"::: - You can link from a work item or from a Git object. For details, see [Link to work items from other objects, View list of linked objects](../../organizations/notifications/add-links-to-work-items.md#view-list-links). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Drive Git development from work item(s) - :::column-end::: - :::column span="2"::: - You can initiate a Git branch or link to Git commits or pull requests and drive your Git development cycle for a work item from within the work item form. - :::image type="content" source="media/work-tracking/development-control-git.png" alt-text="Screenshot of Development control for Git repositories."::: - For details, see [Drive Git development from a work item](../../boards/backlogs/connect-work-items-to-git-dev-ops.md?toc=/azure/devops/repos/toc.json&bc=/azure/devops/repos/breadcrumb/toc.json). - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Automatically link and transition work items with Git commits - :::column-end::: - :::column span="2"::: - Enable or disable the following options for a single Git repository. To learn how, see [Configure Git repositories to support work tracking](#configure-git-repos). - - Automatically create links for work items mentioned in a commit comment - - Allow mentions in commit comments to close work items - - Remember user preferences for completing work items with pull requests. - :::column-end::: -:::row-end::: ---- -:::row::: - :::column span="1"::: - Check for linked work items in a Git branch - :::column-end::: - :::column span="2"::: - Encourage traceability by checking for linked work items on pull requests. For details, see [Configure branch policies to support work tracking](#configure-branch-policies). - :::column-end::: -:::row-end::: ---- -::: moniker range=">= tfs-2018" -:::row::: - :::column span="1"::: - Auto complete work items with pull requests - :::column-end::: - :::column span="2"::: - When you link a work item to a pull request (PR), you have the option to automatically complete those work items when you successfully complete the PR. The system defaults to your selection for future PRs. For details, see [Auto complete of work items with pull requests](../../boards/work-items/auto-complete-work-items-pull-requests.md). - :::column-end::: -:::row-end::: ---- -::: moniker-end -:::row::: - :::column span="1"::: - Query for external links - :::column-end::: - :::column span="2"::: - You can query for work items that contain links to branches, commits, pull requests or tags. To learn more, see [Query by link or attachment count](../../boards/queries/linking-attachments.md). - :::column-end::: -:::row-end::: ---- - - - -## Configure Git repositories to support work tracking - -You can enable several options to automate linking of work items from commits or pull requests. - -To configure the repository, open **Project Settings>Repositories**, choose a repository, and then view the **Settings** tab. - -:::image type="content" source="media/work-tracking/repo-settings-work-tracking.png" alt-text="Screenshot of Project Settings>Repositories>Settings showing work tracking options."::: - -Enable the following options: - -- **Commit mention linking** - When enabled, commit messages containing `#` followed by a valid work item ID will automatically link the commit to the mentioned work item. Disable this option when pushing a repository previously contained by a different account or service. If you [import a repository](import-git-repository.md), we automatically turn this option off. -- **Commit mention work item resolution** - Enable this option to support closing work items mentioned in commits with the `Fixes` prefix, for example `Fixes #*WorkItemID*`. -- **Work item transition preferences** - When enabled, the default option, the system remembers each user's last choice to complete linked work items during pull request completion. Depending on your team's preference, you may choose to disable this option to discourage users from completing work items with their pull requests. When disabled, users must opt-in to completing work items for each pull request. - - - - -## Configure branch policies to support work tracking - -To ensure that changes to a branch have links to work items, you configure the branch policy for a Git repository. - - -To configure the branch, open **Project Settings>Repositories**, choose a Git repository, and then view the **Policies** tab. Scroll down and choose a branch under the **Branch policies** section. Linking work items provides additional context for your changes and ensures that updates go through your work item tracking process. - -Turn on the **Check for linked work items** option. -- Choose **Required** to mandate all pull requests have at least one linked work item in order to be completed. -- Choose **Optional** to allow pull requests to be completed without linked work items, but issue a warning that there are no linked work items. - - - -::: moniker range=">= azure-devops-2020" - -:::image type="content" source="media/work-tracking/branch-policies-check-linked-work-items.png" alt-text="Screenshot of Project Settings>Repositories>Branch Policies showing check for linked work items option."::: - -::: moniker-end - -::: moniker range="< azure-devops-2020" - -![Require linked work items in your pull requests](media/branch-policies/work-item-linking-2018.png) - -::: moniker-end - -## Related articles - -- [Link to work items from other objects](../../organizations/notifications/add-links-to-work-items.md#view-list-links) -- [Link type reference](../../boards/queries/link-type-reference.md) -- [Drive Git development from a work item](../../boards/backlogs/connect-work-items-to-git-dev-ops.md?toc=/azure/devops/repos/toc.json&bc=/azure/devops/repos/breadcrumb/toc.json) -- [End-to-end traceability](../../cross-service/end-to-end-traceability.md) diff --git a/docs/repos/git/create-a-readme.md b/docs/repos/git/create-a-readme.md index f14eb14fc72..72c768f3caa 100644 --- a/docs/repos/git/create-a-readme.md +++ b/docs/repos/git/create-a-readme.md @@ -32,6 +32,10 @@ Here are some great readmes that use this format and speak to all three audience - [Visual Studio Code](https://github.com/Microsoft/vscode) - [Chakra Core](https://github.com/Microsoft/ChakraCore) +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## Create an intro Start off your readme with a short explanation describing your project. Add a screenshot or animated GIF in your intro if your project has a user interface. diff --git a/docs/repos/git/create-branch.md b/docs/repos/git/create-branch.md index 3bd53f4e8a5..69555ada421 100644 --- a/docs/repos/git/create-branch.md +++ b/docs/repos/git/create-branch.md @@ -19,6 +19,10 @@ The first commit in a new Git repo is the start of the `main` branch. As you wor For an overview of the Git workflow, see [Azure Repos Git tutorial](gitworkflow.md). +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## Create a new branch > [!NOTE] @@ -60,42 +64,6 @@ The main page of your repo now shows the files in your new branch. ::: moniker-end -::: moniker range="< azure-devops-2020 >= azure-devops-2019" - -1. View your repo's branches by selecting **Repos** > **Branches** while viewing your repo on the web. - - ![View your branches](media/repos-navigation/repos-branches.png) - -1. Select **New branch** in the upper-right corner of the page. - - ![Create branch button](media/branches/create-branch.png) - -1. In the **Create a branch** dialog box, enter a name for your new branch, select a branch to base the work off of, and associate any work items. - - :::image type="content" source="media/branches/create-branch-web-2020.png" alt-text="Screenshot that shows the creation of a branch with the new branch dialog."::: - -1. Select **Create branch**. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. View your repo's branches by selecting **Branches** while viewing your repo on the web. - - :::image type="content" source="media/create-branch/branches-nav.png" border="false" alt-text="Branches page."::: - -1. Select **New branch** in the upper-right corner of the page. - - :::image type="content" source="media/create-branch/create-branch.png" border="false" alt-text="Create branch button."::: - -1. In the **Create a branch** dialog box, enter a name for your new branch, select a branch to base the work off of, and associate any work items. - - :::image type="content" source="media/create-branch/newbranch-dialog.png" border="false" alt-text="Create a branch with the new branch dialog."::: - -1. Select **Create branch**. - -::: moniker-end - > [!TIP] > After you've created a remote branch, you can [fetch](pulling.md) it into your local Git repo. At the command prompt, run:
      > `git fetch`
      diff --git a/docs/repos/git/create-new-repo.md b/docs/repos/git/create-new-repo.md index 7b66a201ed9..8bb1c764a02 100644 --- a/docs/repos/git/create-new-repo.md +++ b/docs/repos/git/create-new-repo.md @@ -1,7 +1,7 @@ --- title: Create a new Git repo in your project titleSuffix: Azure Repos -description: Create a new Git repo in an Azure DevOps Services or Team Foundation Server Project +description: Create a new Git repo in an Azure DevOps project via the web portal. ms.assetid: 9c6fabfa-ae17-4e65-93a2-9e476f9f88ba ms.service: azure-devops-repos ms.topic: quickstart @@ -14,22 +14,21 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Azure DevOps Services and TFS projects contain Git repositories, work items, builds, and releases. You can use Git repos in your projects to manage your source code as your project grows. This guide shows you how to create a Git repo using the web portal for either Azure DevOps Services (hosted on Azure) or Team Foundation Server (TFS - on-premises). +Azure DevOps projects contain Git repositories, work items, builds, and releases. You can use Git repos in your projects to manage your source code as your project grows. This guide shows you how to create a Git repo using the web portal. ## Prerequisites -* An organization in Azure DevOps. If you don't have one, you can [sign up](../../organizations/accounts/create-organization.md) for one for free. Each organization includes free, unlimited private Git repositories. -* You must have the **Create repository** permission, which is granted by default to project administrators. For more information, see [Set Git repository permissions](set-git-repository-permissions.md). -* Git command-line tools: - * [Install Git for Windows](https://git-scm.com/download/win), which includes [Git Credential Manager](set-up-credential-managers.md#windows) - * [Install Git for macOS and Linux](https://git-scm.com/downloads). - * For macOS and Linux, we recommend [configuring SSH authentication](../git/use-ssh-keys-to-authenticate.md) +| Category | Requirements | +|-------------|-------------| +| **Organization** | An [organization in Azure DevOps](../../organizations/accounts/create-organization.md) with a Git repository. | +| **Permissions** | **Create repository** permissions, granted by default to project administrators. For more information, see [Set Git repository permissions](set-git-repository-permissions.md).| +| **Tools** | - [Git for Windows](https://git-scm.com/download/win), which includes [Git Credential Manager](set-up-credential-managers.md#windows), or [Git for macOS and Linux](https://git-scm.com/downloads). For macOS and Linux, we recommend [configuring SSH authentication](../git/use-ssh-keys-to-authenticate.md). | ## Create a repo using the web portal -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -1. Open the **Repos** page in your project by browsing to `https://dev.azure.com/OrganizationName`, hover your mouse over the name of your project, and select the **Repos** icon. You can select it from the **All** projects list, or from the **Recent** projects list if you've accessed it recently. +1. Open the **Repos** page in your project by browsing to `https://dev.azure.com/OrganizationName`, hover your mouse over the name of your project, and select the **Repos** icon. You can select it from the **All** projects list, or from the **Recent** projects list if you accessed it recently. ![Screenshot of organization or collection page that lists projects.](media/repo-mgmt/select-project-repos.png) @@ -37,7 +36,7 @@ Azure DevOps Services and TFS projects contain Git repositories, work items, bui ![Screenshot of repository menu, select New repository.](media/repo-mgmt/new-repository.png) -3. In the **Create a new repository** dialog, verify that Git is the repository type and enter a name for your new repository. For naming restrictions, see [Naming restrictions, Azure Repos (git)](../../organizations/settings/naming-restrictions.md#repos-git). +3. In the **Create a new repository** dialog, verify that Git is the repository type and enter a name for your new repository. For naming restrictions, see [Naming restrictions, Azure Repos (git)](../../organizations/settings/naming-restrictions.md). ![Screenshot of Create a new repository dialog.](media/repo-mgmt/create-a-new-repository.png) @@ -47,33 +46,8 @@ Azure DevOps Services and TFS projects contain Git repositories, work items, bui A new empty Git repo is now created in your project. - - If you created an empty repo with no README or .gitignore files, you'll see instructions on how to [clone](clone.md) the repo to your computer. You'll also see instructions on how to [push](pushing.md) code in an existing repo into the newly created one. - - In this example, you created a README and a .gitignore. You'll now see an overview of the files in your repo. You can [clone](clone.md) the repo using the **Clone** link on the upper right of the page to get working with a local copy of the repo immediately. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Navigate to your project by browsing to `https://dev.azure.com/` and selecting the name of your project. You can select it from the **All projects** list, or from the **Recent** projects list at the top if you've accessed it recently. - - ![Screenshot of collection page that lists projects, TFS 2018 version.](media/repo-mgmt/select-vsts-project.png) - -2. In the **Project** area in the web portal, select **Code**, then select the drop-down next to the current repo name and choose **New Repository**. - - ![Screenshot of Code page, Repository menu selection, Choose new repository, TFS 2018 version.](media/repo-mgmt/create-vsts-repo.png) - -3. In the **Create a new repository** dialog, verify that Git is the repo type and enter a name for your new repo. For naming restrictions, see [Naming restrictions, Azure Repos (git)](../../organizations/settings/naming-restrictions.md#repos-git). - - ![Screenshot of Create a new repoistory dialog, TFS 2018 version.](media/repo-mgmt/create-a-new-repository.png) - - You can also add a README and create a .gitignore for the type of code you plan to manage in the repo. A [README](create-a-readme.md) contains information about the code in your repo. The [.gitignore](ignore-files.md) file tells Git which types of files to ignore, such as temporary build files from your development environment. - -4. When you're happy with the repo name and choices, select **Create**. - - A new empty Git repo is now created in your project. - - - If you created an empty repo with no README or .gitignore files, you'll see instructions on how to [clone](clone.md) the repo to your computer. You'll also see instructions on how to [push](pushing.md) code in an existing repo into the newly created one. - - In this example. you created a README and a .gitignore. You'll now see an overview of the files in your repo. You can [clone](clone.md) the repo using the **Clone** link on the upper right of the page to get working with a local copy of the repo immediately. + - If you created an empty repo with no README or .gitignore files, there are instructions on how to [clone](clone.md) the repo to your computer. There are also instructions on how to [push](pushing.md) code in an existing repo into the newly created one. + - In this example, you created a README and a .gitignore. There's an overview of the files in your repo. You can [clone](clone.md) the repo using the **Clone** link on the upper right of the page to get working with a local copy of the repo immediately. ::: moniker-end @@ -81,7 +55,7 @@ Azure DevOps Services and TFS projects contain Git repositories, work items, bui To work with a Git repo, you clone it to your computer. Cloning a repo creates a complete local copy of the repo for you to work with. Cloning also downloads all [commits](commits.md) and [branches](./create-branch.md) in the repo and sets up a named relationship with the repo on the server. Use this relationship to interact with the existing repo, pushing and pulling changes to share code with your team. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. From your web browser, open the team project for your organization in Azure DevOps and select **Repos** > **Files**. If you don't have a team project, [create one now](../get-started/sign-up-invite-teammates.md). @@ -89,7 +63,7 @@ To work with a Git repo, you clone it to your computer. Cloning a repo creates a 2. Select **Clone** in the upper-right corner of the **Files** window and copy the clone URL. - ![Clone respository dialog.](./media/clone-repo/clone-repo.png) + ![Clone repository dialog.](./media/clone-repo/clone-repo.png) 3. Open the Git command window (Git Bash on Git for Windows). Then, browse to the folder where you want the code from the repo stored on your computer. Run `git clone` followed by the path copied from the **Clone URL** in the previous section, as shown in the following example. @@ -105,31 +79,13 @@ To work with a Git repo, you clone it to your computer. Cloning a repo creates a cd fabrikam-fiber ``` - Keep this command window open, because you'll use it in the following steps. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Select **Clone** in the upper-right corner of the **Code** window and copy the **Clone URL**. - - ![Screenshot of Clone repo dialog, TFS 2018 version.](media/repo-mgmt/clone-git-repo.png) - -2. Open the Git command window (Git Bash on Git for Windows), navigate to the folder where you want the code from the repo stored on your computer, and run `git clone` followed by the path copied from the **Clone URL** in the previous step, as shown in the following example. - - ``` - git clone https://fabrikam-fiber.visualstudio.com/DefaultCollection/MyFirstProject/_git/ - ``` - - After running the previous command, Git downloads a copy of the code into a new folder for you to work with. This download includes all [commits](commits.md) and [branches](./create-branch.md) from the repo. - - Keep this command window open, as you'll use it in the following steps. + Keep this command window open, because you use it in the following steps. ::: moniker-end ## Work with the code -In this step, we'll make a change to the files on your computer, commit the changes locally, push the commit up to the repo on the server, and view the changes there. +In this step, we make a change to the files on your computer, commit the changes locally, push the commit up to the repo on the server, and view the changes there. 1. Browse to the folder on your computer where you cloned the repo and open the `README.md` file in your editor of choice. @@ -147,7 +103,7 @@ In this step, we'll make a change to the files on your computer, commit the chan git commit -a -m "My first commit" ``` - When using `git commit`, `-a` means to commit all changed files, and `-m` specifies a commit message. + When you use `git commit`, `-a` means to commit all changed files, and `-m` specifies a commit message. 5. Push your changes up to the Git repo by entering the following command into the Git command window: diff --git a/docs/repos/git/create-pr-status-server-with-azure-functions.md b/docs/repos/git/create-pr-status-server-with-azure-functions.md index 13b2de47800..1eff8bd08cd 100644 --- a/docs/repos/git/create-pr-status-server-with-azure-functions.md +++ b/docs/repos/git/create-pr-status-server-with-azure-functions.md @@ -1,11 +1,11 @@ --- title: Use Azure Functions to create custom branch policy titleSuffix: Azure Repos -description: Create a serverless function to listen to pull request events and post status on the pull request status API. +description: Create a serverless function to listen to pull request events and post status on the PR status API. ms.assetid: ms.service: azure-devops-repos ms.topic: conceptual -ms.date: 10/31/2018 +ms.date: 02/14/2025 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- @@ -14,15 +14,22 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The pull request (PR) workflow provides developers with an opportunity to get feedback on their code from peers as well as from automated tools. 3rd party tools and services can participate in the PR workflow by using the PR [Status API](/rest/api/azure/devops/git/pull%20request%20statuses). This article guides you through the process of creating a custom branch policy using [Azure Functions](https://azure.microsoft.com/services/functions/) to validate PRs in an Azure DevOps Services Git repository. With Azure Functions you don't have to worry about provisioning and maintaining servers, especially when your workload grows. Azure Functions provide a fully managed compute platform with high reliability and security. +The pull request (PR) workflow allows developers to receive feedback on their code from peers and automated tools. Non-Microsoft tools and services can also participate in the PR workflow by using the PR [Status API](/rest/api/azure/devops/git/pull%20request%20statuses). This article guides you through creating a custom branch policy using [Azure Functions](https://azure.microsoft.com/services/functions/) to validate PRs in an Azure DevOps Git repository. Azure Functions eliminate the need to provision and maintain servers, even as your workload grows. They provide a fully managed compute platform with high reliability and security. For more information about PR status, see [Customize and extend pull request workflows with pull request status](pull-request-status.md). ## Prerequisites -An organization in Azure DevOps with a Git repo. If you don't have an organization, [sign up](../../organizations/accounts/create-organization.md) to upload and share code in free unlimited private Git repositories. -## Create a basic Azure function to listen to Azure Repos events -Follow the [create your first Azure function](/azure/azure-functions/functions-create-first-azure-function) documentation to create a simple function. Modify the code in the sample to look like this: +| Category | Requirements | +|-------------|-------------| +| **Organization** | An [organization in Azure DevOps](../../organizations/accounts/create-organization.md) with a Git repository. | +| **Azure Function** | An [Azure Function](#create-a-basic-azure-function-to-listen-to-azure-repos-events), which implements a serverless, event-driven solution that integrates with Azure DevOps to create custom branch policies and automate PR validation.| +| **Service Hooks** | [Configure service hooks](#configure-a-service-hook-for-pr-events) for PR events to notify your Azure function when a pull request changes. | +| **Personal Access Token (PAT)** | Create a PAT with the **Code (status)** scope to have permission to change PR status. For more information, see [Use PATs to authenticate](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). | + +### Create a basic Azure Function to listen to Azure Repos events + +[Create your first Azure function](/azure/azure-functions/functions-create-first-azure-function). Then, modify the code in the sample to look like the following code: ```cs using System; @@ -68,10 +75,11 @@ public static async Task Run(HttpRequestMessage req, TraceW } ``` -## Configure a service hook for PR events -Service hooks are an Azure DevOps Services feature that can alert external services when certain events occur. For this sample, you'll want to set up a service hook for PR events, your Azure function will be notified when a pull request changes. In order to receive `POST` requests when pull requests change, you will need to provide the service hook with the Azure function URL. +### Configure a service hook for PR events -For this sample you will need to configure 2 service hooks. The first will be for the **Pull request created** event and the second will be for the **Pull request updated** event. +Service hooks are an Azure DevOps feature that can alert external services when certain events occur. For this sample, set up a service hook for PR events, your Azure function is notified when a pull request changes. In order to receive `POST` requests when pull requests change, provide the service hook with the Azure function URL. + +For this sample, configure two service hooks. The first is for the **Pull request created** event and the second is for the **Pull request updated** event. 1. Get the function URL from the Azure portal by clicking the **Get function URL** in your Azure function view and copy the URL. @@ -79,13 +87,13 @@ For this sample you will need to configure 2 service hooks. The first will be fo ![Copy function url](media/create-pr-status-server-with-azure-functions/copy-function-url.png) -2. Browse to your project in Azure DevOps, e.g. `https://dev.azure.com//` +2. Browse to your project in Azure DevOps, for example, `https://dev.azure.com//` 3. From the navigation menu, hover over the **gear** and select **Service Hooks**. ![Choose Service hooks from the admin menu](media/create-pr-status-server/service-hooks-menu.png) -4. If this is your first service hook, select **+ Create subscription**. +4. If it's your first service hook, select **+ Create subscription**. ![Select Create a new subscription from the toolbar](media/create-pr-status-server/service-hooks-create-first-service-hook.png) @@ -105,7 +113,7 @@ For this sample you will need to configure 2 service hooks. The first will be fo ![Enter the URL and select Test to test the service hook](media/create-pr-status-server-with-azure-functions/service-hooks-action.png) - In the Azure function log window, you'll see an incoming `POST` that returned a `200 OK`, indicating your function received the service hook event. + In the Azure function log window, you see an incoming `POST` that returned a `200 OK`, indicating your function received the service hook event. ``` HTTP Requests @@ -130,15 +138,15 @@ Create a pull request to verify your Azure function is receiving notifications. ## Post status to PRs Now that your server can receive service hook events when new PRs are created, update it to post back status to the PR. You can use the JSON payload posted by the service hook in order to determine what status to set on your PR. -Update the code of your Azure function to look like the following example. +Update the code of your Azure function, similar to the following example. -Make sure to update the code with your organization name, project name, repository name and [PAT token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). In order to have permission to change PR status, the PAT requires [vso.code_status](../../integrate/get-started/authentication/oauth.md#scopes) scope, which you can grant by selecting the **Code (status)** scope on the **Create a personal access token** page. +Make sure to update the code with your organization name, project name, repository name, and [PAT token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). In order to have permission to change PR status, the PAT requires [vso.code_status](../../integrate/get-started/authentication/oauth.md#scopes) scope, which you can grant by selecting the **Code (status)** scope on the **Create a personal access token** page. >[!Important] ->This sample code stores the PAT in code to simplify the sample. It is recommended to store secrets in KeyVault and retrieve them from there. +>This sample code stores the PAT in code, simplifying the sample. It is recommended to store secrets in KeyVault and retrieve them from there. -This sample inspects the PR title to see if the user has indicated if the PR is a work in progress by adding **WIP** to the title. If so, the sample code changes the status posted back to the PR. Replace the code in your Azure function with the following code to implement updating the status posted back to the PR. +This sample inspects the PR title to see if the user indicated if the PR is a work in progress by adding **WIP** to the title. If so, the sample code changes the status posted back to the PR. Replace the code in your Azure function with the following code which updates the status posted back to the PR. ```cs using System; @@ -251,7 +259,7 @@ private static string ComputeStatus(string pullRequestTitle) } ``` -## Create a new PR to test the status server +## Create a new PR and test the status server Now that your server is running and listening for service hook notifications, create a pull request to test it out. 1. Start in the files view. Edit the readme.md file in your repo (or any other file if you don't have a readme.md). @@ -274,12 +282,13 @@ Now that your server is running and listening for service hook notifications, cr ![Add WIP to the default PR title](media/create-pr-status-server/new-pr-wip.png) -6. Once the PR has been created, you will see the status section, with the **Work in progress** entry which links to the URL specified in the payload. +6. Once the PR gets created, the status section displays, with the **Work in progress** entry that links to the URL specified in the payload. ![Status section with Work in progress entry.](media/create-pr-status-server/pr-with-status.png) 7. Update the PR title and remove the **WIP** text and note that the status changes from **Work in progress** to **Ready for review**. -## Next Steps -* In this article, you learned the basics of how to create a serverless Azure function that listens for PR events via service hooks and can post status messages using the status API. For more information about the pull request status API see the [REST API documentation](/rest/api/azure/devops/git/pull%20request%20statuses). -* [Configure a branch policy for an external service](./pr-status-policy.md). +## Next steps + +> [!div class="nextstepaction"] +> [Configure a branch policy for an external service](./pr-status-policy.md). diff --git a/docs/repos/git/create-pr-status-server.md b/docs/repos/git/create-pr-status-server.md index 9ec79d9b165..bda6ebf7d10 100644 --- a/docs/repos/git/create-pr-status-server.md +++ b/docs/repos/git/create-pr-status-server.md @@ -1,7 +1,7 @@ --- title: Create a pull request status server with Node.js titleSuffix: Azure Repos -description: Create a web server to listen to pull request events and post status on the pull request status API. +description: Create a web server to listen to pull request events and post status on pull request status API. ms.assetid: 2653589c-d15e-4dab-b8b0-4f8236c4a67b ms.service: azure-devops-repos ms.topic: conceptual @@ -16,17 +16,17 @@ ms.custom: devx-track-js [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The pull request (PR) workflow provides developers with an opportunity to get feedback on their code from peers as well as from automated tools. 3rd party tools and services can participate in the PR workflow by using the PR [Status API](/rest/api/azure/devops/git/pull%20request%20statuses). This article guides you through the process of creating a status server to validate PRs in an Azure DevOps Services Git repository. For more information about PR status, see [Customize and extend pull request workflows with pull request status](pull-request-status.md). +The pull request (PR) workflow provides developers with an opportunity to get feedback on their code from peers and from automated tools. Non-Microsoft tools and services can participate in the PR workflow by using the PR [Status API](/rest/api/azure/devops/git/pull%20request%20statuses). This article guides you through the process of creating a status server to validate PRs in an Azure DevOps Services Git repository. For more information about PR status, see [Customize and extend pull request workflows with pull request status](pull-request-status.md). ## Prerequisites -* An organization in Azure DevOps with a Git repo. If you don't have an organization, [sign up](../../organizations/accounts/create-organization.md) to upload and share code in free unlimited private Git repositories. -* Install [VS Code](https://code.visualstudio.com/Docs/setup) or other code editor of your choice. The instructions in this guide use VS Code but the steps in other code editors are similar. -## Install Node.js -To install Node.js, [download](https://nodejs.org/en/download/) the LTS release appropriate for your platform. The download contains an installer, which you can run to install the Node.js runtime on your local machine. When installing Node.js, be sure to keep the [npm package manager](https://www.npmjs.com/) portion of the install, which is selected by default. +| Category | Requirements | +|-------------|-------------| +| **Organization** | An [organization in Azure DevOps](../../organizations/accounts/create-organization.md) with a Git repository. | +|**Tools**| - [Visual Studio Code](https://code.visualstudio.com/Docs/setup) or other code editor of your choice.
      - [Node.js](https://nodejs.org/en/download/). The download contains an installer, which you can run to install the Node.js runtime on your local machine. When installing Node.js, be sure to keep the [npm package manager](https://www.npmjs.com/) portion of the install, which is selected by default.| ## Create a basic web server using Express -The steps in this section use [Express](https://expressjs.com/), which is a lightweight web framework for Node.js that provides a number of HTTP utility methods that simplify creating a web server. This framework provides you with the basic functions needed to listen to PR events. +The steps in this section use [Express](https://expressjs.com/), which is a lightweight web framework for Node.js that provides many HTTP utility methods that simplify creating a web server. This framework provides you with the basic functions needed to listen to PR events. 1. From the command line, create a new project folder for your web server. @@ -41,19 +41,19 @@ The steps in this section use [Express](https://expressjs.com/), which is a ligh npm init ``` - Press Enter to accept the defaults for all of the options except the entry point. Change it to `app.js` + Select **Enter** to accept the defaults for all of the options except the entry point. Change it to `app.js` ``` entry point: (index.js) app.js ``` -3. Install Express in the pr-server directory using the following command. This installs Express and saves it to the dependencies list. +3. Install Express in the `pr-server` directory using the following command. This installs Express and saves it to the dependencies list. ``` npm install express ``` -4. Create a simple Express app to build upon for the PR status server. The following steps are based on the Express [Hello world example](https://expressjs.com/en/starter/hello-world.html). Open the project folder in VS Code by running the following command from the `pr-server` folder. +4. Create an Express app to build upon for the PR status server. The following steps are based on the Express [Hello world example](https://expressjs.com/en/starter/hello-world.html). Open the project folder in VS Code by running the following command from the `pr-server` folder. ``` code . @@ -95,18 +95,18 @@ The web server is going to receive `POST` requests from Azure DevOps Services, s }) ``` -2. Re-run your web server using the following command: +2. Rerun your web server using the following command: ``` node app.js ``` ## Configure a service hook for PR events -Service hooks are an Azure DevOps Services feature that can alert external services when certain events occur. For this sample, you'll want to set up two service hooks for PR events, so the status server can be notified. The first will be for the **Pull request created** event and the second will be for the **Pull request updated** event. +Service hooks are an Azure DevOps Services feature that can alert external services when certain events occur. For this sample, set up two service hooks for PR events, so the status server can be notified. The first is for the **Pull request created** event and the second is for the **Pull request updated** event. -In order to receive the service hook notifications, you'll need to expose a port to the public internet. The [ngrok](https://ngrok.com/) utility is very useful for doing this in a development environment. +To receive the service hook notifications, expose a port to the public internet. The ngrok utility is useful for doing so in a development environment. -1. [Download](https://ngrok.com/download) and unzip the appropriate ngrok release for your platform. +1. Download and unzip the appropriate ngrok release for your platform. 2. Use ngrok to start listening on the same port as your sample server - port 3000. Run the following command in a new command window. @@ -114,39 +114,39 @@ In order to receive the service hook notifications, you'll need to expose a port ngrok http 3000 ``` - Ngrok will create a public URL that forwards to `localhost:3000`. Note that URL as you will need it in the next step. It will look something like this: + Ngrok creates a public URL that forwards to `localhost:3000`. Make a note of the URL, as you need it in the next step. It looks like the following example: ``` http://c3c1bffa.ngrok.io ``` -3. Browse to your project in Azure DevOps, e.g. `https://dev.azure.com//` +3. Browse to your project in Azure DevOps, for example, `https://dev.azure.com//` 4. From the navigation menu, hover over the **gear** and select **Service Hooks**. - ![Choose Service hooks from the admin menu](media/create-pr-status-server/service-hooks-menu.png) + ![Screenshot shows Choose Service hooks from the admin menu.](media/create-pr-status-server/service-hooks-menu.png) -5. If this is your first service hook, select **+ Create subscription**. +5. If it's your first service hook, select **+ Create subscription**. - ![Select Create a new subscription from the toolbar](media/create-pr-status-server/service-hooks-create-first-service-hook.png) + ![Screenshot shows selected Create a new subscription from the toolbar.](media/create-pr-status-server/service-hooks-create-first-service-hook.png) - If you already have other service hooks configured, select the green plus `(+)` to create a new service hook subscription. + If you already have other service hooks configured, select the plus `(+)` to create a new service hook subscription. - ![Select the green plus to create a new service hook subscription.](media/create-pr-status-server/service-hooks-create.png) + ![Screenshot shows selected the plus to create a new service hook subscription.](media/create-pr-status-server/service-hooks-create.png) 6. On the New Service Hooks Subscription dialog, select **Web Hooks** from the list of services, then select **Next**. - ![Select web hooks from the list of services](media/create-pr-status-server/service-hooks-web-hook.png) + ![Screenshot shows selected web hooks from the list of services.](media/create-pr-status-server/service-hooks-web-hook.png) 7. Select **Pull request created** from the list of event triggers, then select **Next**. - ![Select pull request created from the list of event triggers](media/create-pr-status-server/service-hooks-trigger.png) + ![Screenshot shows selected pull request created from the list of event triggers.](media/create-pr-status-server/service-hooks-trigger.png) 8. In the Action page, enter the URL from ngrok in the **URL** box. Select **Test** to send a test event to your server. - ![Enter the URL and select Test to test the service hook](media/create-pr-status-server/service-hooks-action.png) + ![Screenshot shows entered URL and selected test to test the service hook.](media/create-pr-status-server/service-hooks-action.png) - In the ngrok console window, you'll see an incoming `POST` that returned a `200 OK`, indicating your server received the service hook event. + In the ngrok console window, an incoming `POST` returns a `200 OK`, indicating your server received the service hook event. ``` HTTP Requests @@ -155,9 +155,9 @@ In order to receive the service hook notifications, you'll need to expose a port POST / 200 OK ``` - In the Test Notification window, select the Response tab to see the details of the response from your server. You should see a content length of 17 that matches the length of the string from your POST handler (i.e. "Received the POST"). + In the Test Notification window, select the Response tab to see the details of the response from your server. You should see a content length of 17 that matches the length of the string from your POST handler (for example, "Received the POST"). - ![Select the response tab to see the results of the test](media/create-pr-status-server/test-notification.png) + ![Screenshot shows selected response tab for results of the test.](media/create-pr-status-server/test-notification.png) 9. Close the Test Notification window, and select **Finish** to create the service hook. @@ -230,7 +230,7 @@ Now that your server can receive service hook events when new PRs are created, u setx TOKEN "yourtokengoeshere" ``` -8. Update the `post()` function to read the PR details from the service hook payload. You'll need these values in order to post back status. +8. Update the `post()` function to read the PR details from the service hook payload. You need these values to post back status. ``` javascript var repoId = req.body.resource.repository.id @@ -240,11 +240,11 @@ Now that your server can receive service hook events when new PRs are created, u 9. Build the status object to post on the PR. - `State` is an enum of type [GitStatusState](/rest/api/azure/devops/git/pull-request-statuses/get#gitstatusstate). Use `succeeded` to indicate that the PR has passed the status check and is ready to merge. + `State` is an enum of type [GitStatusState](/rest/api/azure/devops/git/pull-request-statuses/get#gitstatusstate). Use `succeeded` to indicate that the PR passed the status check and is ready to merge. - The `description` is a string value that will be displayed to the user in the Status section and activity feed in the PR details view. + The `description` is a string value that displays to the user in the Status section and activity feed in the PR details view. - The `targetUrl` is a URL that will be used to create a link for the description text in the Status section and activity feed. This is the place where users can go to get more information about the status, for example, a build report or test run. If no URL is specified, the description will appear as text with no link. + The `targetUrl` is a URL that's used to create a link for the description text in the Status section and activity feed, which is where users can go to get more information about the status, for example, a build report or test run. If no URL is specified, the description appears as text with no link. The context `name` and `genre` are used to categorize the status and distinguish it from other services posting status. @@ -260,7 +260,7 @@ Now that your server can receive service hook events when new PRs are created, u } ``` -10. Instead of just blindly posting the `succeeded` status, inspect the PR title to see if the user has indicated if the PR is a work in progress by adding **WIP** to the title. If so, change the status posted back to the PR. +10. Instead of posting the `succeeded` status right away, inspect the PR title to see if the user indicated if the PR is a work in progress by adding **WIP** to the title. If so, change the status posted back to the PR. ``` javascript if (title.includes("WIP")) { @@ -322,35 +322,36 @@ Now that your server can receive service hook events when new PRs are created, u node app.js ``` -## Create a new PR to test the status server +## Create a new PR for testing the status server Now that your server is running and listening for service hook notifications, create a pull request to test it out. 1. Start in the files view. Edit the readme.md file in your repo (or any other file if you don't have a readme.md). - ![Select Edit from the context menu](media/create-pr-status-server/edit-readme.png) + ![Screenshot shows selected Edit button from the context menu.](media/create-pr-status-server/edit-readme.png) 2. Make an edit and commit the changes to the repo. - ![Edit the file and select Commit from the toolbar](media/create-pr-status-server/commit-changes.png) + ![Screenshot shows editing the file and selected Commit button from the toolbar.](media/create-pr-status-server/commit-changes.png) 3. Be sure to commit the changes to a new branch so you can create a PR in the next step. - ![Enter a new branch name and select Commit](media/create-pr-status-server/commit-to-branch.png) + ![Screenshot shows entered new branch name and selected Commit button.](media/create-pr-status-server/commit-to-branch.png) 4. Select the **Create a pull request** link. - ![Select Create a pull request from the suggestion bar](media/create-pr-status-server/create-pr.png) + ![Screenshot shows selected Create a pull request from the suggestion bar.](media/create-pr-status-server/create-pr.png) 5. Add **WIP** in the title to test the functionality of the app. Select **Create** to create the PR. - ![Add WIP to the default PR title](media/create-pr-status-server/new-pr-wip.png) + ![Screenshot shows added WIP to the default PR title.](media/create-pr-status-server/new-pr-wip.png) -6. Once the PR has been created, you will see the status section, with the **Work in progress** entry which links to the URL specified in the payload. +6. Once the PR is create, the status section shows with the **Work in progress** entry that links to the URL specified in the payload. - ![Status section with the Work in progress entry.](media/create-pr-status-server/pr-with-status.png) + ![Screenshot shows status section with the Work in progress entry.](media/create-pr-status-server/pr-with-status.png) 7. Update the PR title and remove the **WIP** text and note that the status changes from **Work in progress** to **Ready for review**. -## Next Steps -* In this article, you learned the basics of how to create a service that listens for PR events via service hooks and can post status messages using the status API. For more information about the pull request status API see the [REST API documentation](/rest/api/azure/devops/git/pull%20request%20statuses). -* [Configure a branch policy for an external service](./pr-status-policy.md). +## Related articles + +- [REST API documentation](/rest/api/azure/devops/git/pull%20request%20statuses) +- [Configure a branch policy for an external service](./pr-status-policy.md) diff --git a/docs/repos/git/create-repo-intellij.md b/docs/repos/git/create-repo-intellij.md index d5f80a31b6d..0b057b7b102 100644 --- a/docs/repos/git/create-repo-intellij.md +++ b/docs/repos/git/create-repo-intellij.md @@ -1,56 +1,51 @@ --- title: Azure DevOps Plugin for IntelliJ, IDEA, Android Studio titleSuffix: Azure Repos -description: Intro to the IntelliJ plugin available for Azure DevOps. +description: Tutorial for the IntelliJ plugin available for Azure DevOps. ms.assetid: ms.service: azure-devops-repos -ms.topic: conceptual -ms.date: 11/13/2020 +ms.topic: tutorial +ms.date: 02/18/2025 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- -# Azure DevOps Plugin for IntelliJ IDEA and Android Studio +# Use the Azure DevOps plugin for IntelliJ IDEA and Android Studio [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] IntelliJ IDEA is an IDE produced by JetBrains. You can find out more about it at [https://www.jetbrains.com/idea/](https://www.jetbrains.com/idea/). -The [Azure DevOps Plugin for IntelliJ](https://plugins.jetbrains.com/plugin/7981-azure-devops) allows you to connect to your Git repositories on Azure DevOps Services and Team Foundation Server (TFS) in a seamless and intuitive way. -You can also use this plugin to import projects into Azure Repos or create pull requests in your Azure DevOps Services/TFS Git repository. - -In this guide, we show you how to create a Git repo using the Azure DevOps Services web portal, add some sample code, and then clone the repo and create pull requests all from within IntelliJ IDEA. +The [Azure DevOps Plugin for IntelliJ](https://plugins.jetbrains.com/plugin/7981-azure-devops) allows you to connect to your Git repositories to Azure DevOps in a seamless and intuitive way. +You can also use this plugin to import projects into Azure Repos or create pull requests in your Azure DevOps Git repository. ## Prerequisites -To complete the steps in this guide you need: -* An organization in Azure DevOps. If you don't have an organization, you can [sign up](../../organizations/accounts/create-organization.md) for one for free. Each organization includes free, unlimited private Git repositories. -* IntelliJ IDEA installed on your machine. If you don't have it, [get IntelliJ IDEA](https://www.jetbrains.com/idea). -* The Azure DevOps plugin for IntelliJ. See [IntelliJ Plugin download page](https://plugins.jetbrains.com/plugin/7981-azure-devops) for installation instructions. This plugin is compatible with IntelliJ IDEA Ultimate and Community editions, Android Studio, RubyMine, WebStorm, PhpStorm, PyCharm, AppCode, MPS, 0xDBE, and CLion. -* Git command line tools. - * To install Git for Windows, including Git Credential Manager, see [Install the Git Credential Manager](set-up-credential-managers.md). - * To install Git for macOS and Linux, see [git-scm.com](https://git-scm.com/downloads). +| Category | Requirements | +|-------------|-------------| +| **Organization** | An [organization in Azure DevOps](../../organizations/accounts/create-organization.md) with a Git repository. | +|**Tools**| - [IntelliJ IDEA](https://www.jetbrains.com/idea).
      - [IntelliJ Plugin](https://plugins.jetbrains.com/plugin/7981-azure-devops).
      - [Git Credential Manager](set-up-credential-managers.md) for Windows or [Git SCM](https://git-scm.com/downloads) for macOS and Linux.| ## Create a repo -1. Navigate to your project in Azure DevOps by browsing to `https://dev.azure.com/{your organization}` and selecting the name of your project. You can select it from the **All** projects list, or from the **Recent** projects list if you have accessed it recently. +1. Navigate to your project in Azure DevOps by browsing to `https://dev.azure.com/{your organization}` and selecting the name of your project. You can select it from the **All** projects list, or from the **Recent** projects list if you accessed it recently. - ![Select project](media/create-repo-intellij/select-vsts-project.png) + ![Screenshot shows Selected project.](media/create-repo-intellij/select-vsts-project.png) [!INCLUDE [project-urls](../../includes/project-urls.md)] 2. In the **Project** area in the web portal, select **Code**, then select the drop-down next to the current repo name and choose **New Repository**. - ![Choose new repository from the web portal](media/create-repo-intellij/create-vsts-repo.png) + ![Screenshot shows Choose new repository from the web portal.](media/create-repo-intellij/create-vsts-repo.png) -3. In the **Create a new repository** dialog, verify that Git is the repo type, enter **DeepSpace** for your new repo name, and click **Create**. +3. In the **Create a new repository** dialog, verify that Git is the repo type, enter **DeepSpace** for your new repo name, and select **Create**. - ![Set options for your new repo in the Create a Git repo dialog](media/create-repo-intellij/create-a-new-repository.png) + ![Screenshot shows Set options for your new repo in the Create a Git repo dialog.](media/create-repo-intellij/create-a-new-repository.png) ## Add sample code to your repo 1. Select **Clone** in the upper-right corner of the **Code** window and copy the **Clone URL**. - ![Retrieve the clone URL](media/create-repo-intellij/clone-git-repo.png) + ![Screenshot shows Retrieve the clone URL.](media/create-repo-intellij/clone-git-repo.png) 2. Open the Git command window (Git Bash on Git for Windows), navigate to the folder where you want the code from the repo stored on your computer, and run `git clone` followed by the path copied from the **Clone URL** in the previous step, as shown in the following example. @@ -64,7 +59,7 @@ To complete the steps in this guide you need: cd DeepSpace ``` - Keep this window open as you'll use it for subsequent steps. + Keep this window open for use in subsequent steps. 4. Download the [DeepSpace sample code](https://github.com/microsoft/deep-space) and extract it to the local directory on your computer where you cloned the DeepSpace repo. @@ -74,7 +69,7 @@ To complete the steps in this guide you need: git add --all ``` - You may see some warnings stating the line feeds will be replaced with carriage return line feeds (i.e. Warning: LF will be replaced by CRLF). These warnings can be ignored. + You might see some warnings stating the line feeds get replaced with carriage return line feeds. You can ignore these warnings. 6. Commit the files to the local repo by running the following command. @@ -88,115 +83,101 @@ To complete the steps in this guide you need: git push ``` -8. Switch back to the Azure DevOps Services web portal and refresh, and you can see the files that were added. - - ![DeepSpace files](media/create-repo-intellij/deep-space-files.png) - +8. Switch back to the Azure DevOps web portal and refresh. The files were added. + ![Screenshot shows DeepSpace files.](media/create-repo-intellij/deep-space-files.png) ## Clone your repo in IntelliJ -Now that we've got a Git repo with some sample code, let's take a look at how we can work with the code from IntelliJ IDEA. To clone your VSTS repo in IntelliJ is extremely simple. You don't even need to know the URL for the repo. +Now that we have a Git repo with some sample code, let's look at how we can work with the code from IntelliJ IDEA. You don't even need to know the URL for the repo to clone it. 1. Open IntelliJ IDEA and select **Check out from Version Control** and then choose **VSTS Git**. - ![Clone repo](media/create-repo-intellij/clone-context-menu.png) + ![Screenshot shows Clone repo action.](media/create-repo-intellij/clone-context-menu.png) -2. Next just sign in to Azure DevOps Services... +2. Sign in to Azure DevOps. - ![Azure DevOps Services Sign-in](media/create-repo-intellij/vsts-sign-in.png) + ![Screenshot shows Azure DevOps sign-in.](media/create-repo-intellij/vsts-sign-in.png) -3. When you click **Sign in**, you will be presented with the standard Azure DevOps Services sign in UI. - Once signed in, you should see the list of all repositories you have access to on Azure DevOps Services. - Choose the correct repo, **DeepSpace**, and click the **Clone** button. - (You may also want to choose where on your hard drive the repo is cloned to by changing the Parent Directory.) +3. When you select **Sign in**, you're presented with the standard Azure DevOps sign-in UI. + Once signed in, you should see the list of all repositories you have access to on Azure DevOps. + Choose the correct repo, **DeepSpace**, and select the **Clone** button. Also change the parent directory, where your repo gets cloned to your hard drive. - ![Screenshot that shows cloning a repo.](media/create-repo-intellij/clone.png) + ![Screenshot shows cloning a repo.](media/create-repo-intellij/clone.png) 4. After the clone finishes, IntelliJ will ask you if you want to open the project. - Click **Yes** and you should end up with the **DeepSpace** project opened in IntelliJ IDEA. - - ![DeepSpace project](media/create-repo-intellij/deep-space-project.png) - + Select **Yes** and you should end up with the **DeepSpace** project opened in IntelliJ IDEA. + ![Screenshot showing DeepSpace project.](media/create-repo-intellij/deep-space-project.png) ## Make some changes in IntelliJ -1. Start by making sure the project builds using **Build** > **Make project**. If you are prompted to add an SDK for the project, - simply add the latest Java JDK installed on your machine. - If you want to run the project now to see what it does, - you can do the following: - 1. From the DeepSpace root folder in your git repo, run the command `mvn jetty:run` (this requires maven to be installed) - 2. From a browser, go to http://localhost:3030/ +1. Ensure that the project builds using **Build** > **Make project**. If you're prompted to add an SDK for the project, add the latest Java JDK installed on your machine. + + To run the project now to see what it does, do the following steps: + 1. From the DeepSpace root folder in your git repo, run the command `mvn jetty:run`, which requires Maven installation. + 2. From a browser, go to http://localhost:3030/. - You should see stars and planets flying by! If you look closely, you may notice that Earth does not fly by. + Stars and planets should be flying by! If you look closely, you might notice that Earth doesn't fly by. -2. In our **DeepSpace** example, there are some code sections that have been commented out. +1. In our **DeepSpace** example, there are some code sections that are commented out. If you open the `src/main/java/com.microsoft.tfs.demo/ImageService.java` file in IntelliJ, you can see one of the sections. - ![Earth commented out](media/create-repo-intellij/earth-commented-out.png) + ![Screenshot shows Earth commented out.](media/create-repo-intellij/earth-commented-out.png) - Let's fix this section of code locally. Typically, when working in a Git repo, you should create a branch for your work and commit to that branch. Create a branch through IntelliJ using the built-in **VCS** > **Git** > **Branches** window. When prompted, use the branch name **fixBugs**. Once we have a branch to make our changes in, we can uncomment the code and rebuild the project. If you follow the instructions above to run the program again, you should see the Earth fly by. + Let's fix this section of code locally. Typically, when working in a Git repo, you should create a branch for your work and commit to that branch. Create a branch through IntelliJ using the built-in **VCS** > **Git** > **Branches** window. When prompted, use the branch name **fixBugs**. Once we have a branch to make our changes in, we can uncomment the code and rebuild the project. If you follow the previous instructions to run the program again, you should see the Earth fly by. -3. Now that our changes are built and tested, we can commit them locally using the **VCS** > **Commit Changes** menu. In the commit dialog, you will see a VSTS button above the commit message text box. Click on that button to view your list of work items - assigned to you. Select the **Add Missing Earth** work item and click **OK**. You will see the commit message text box populate with the work item's type, number, and title. This will associate the work item to this commit for traceability in the future. +2. Now that our changes are built and tested, we can commit them locally using the **VCS** > **Commit Changes** menu. In the commit dialog, you see a VSTS button above the commit message text box. Select on that button to view your list of work items + assigned to you. Select the **Add Missing Earth** work item and select **OK**. A commit message displays the text box populated with the work item's type, number, and title, which associates the work item to this commit for traceability in the future. - ![Commit Earth](media/create-repo-intellij/commit-earth.png) + ![Screenshot shows Commit Earth.](media/create-repo-intellij/commit-earth.png) - Note that this change is only done locally; it hasn't been changed in our Azure DevOps Services repo yet. + This change is only done locally; it isn't changed in our Azure DevOps repo yet. ## Create a pull request + You can push your local branch to the server and create a pull request for your team to review. Our plugin helps you create the pull request based on your current context within IntelliJ. -This saves you several steps and eliminates the need for you to switch to your browser to create the pull request. +This action saves you several steps and eliminates the need for you to switch to your browser to create the pull request. -To accomplish this, simply select **VCS** > **Git** > **Create Pull Request**. This opens up the **Create Pull Request** dialog. -This dialog provides a lot of information including the files that have changed and the commits that will be pushed. +Select **VCS** > **Git** > **Create Pull Request**. This action opens up the **Create Pull Request** dialog. +This dialog provides much information including the files that changed and the commits to be pushed. You can give the pull request a title and a description. -![Create pull request](media/create-repo-intellij/create-pull-request.png) +![Screenshot shows Created pull request.](media/create-repo-intellij/create-pull-request.png) -After you click **Create Pull Request**, you should receive a notification that the pull request was created. +After you select **Create Pull Request**, you should receive a notification that the pull request was created. It also contains a link to the pull request in case you want to add specific reviewers or comments. Once the code reviews are done, you can merge the pull request into your main branch. ## Check build status -After you have merged your changes into your main branch, you can check if your CI build has succeeded from within IntelliJ. In the bottom right corner, -there is an icon that displays your build status to you. If you see a green checkmark, that means your build has succeeded. If you see a red X, -then your build failed. If you see a gray question mark, your build was not found or your credentials may have expired. - -![Build status icons](media/create-repo-intellij/build-status-icons.png) +After you merge your changes into your main branch, you can check if your CI build succeeded from within IntelliJ. In the bottom right corner, +there's an icon that displays your build status to you. If you see a green checkmark, that means your build succeeded. If you see a red X, +then your build failed. If you see a gray question mark, your build wasn't found or your credentials might be expired. +![Screenshot shows Build status icons.](media/create-repo-intellij/build-status-icons.png) -You can click on the icon for more options such as viewing build details, queuing a new build, and updating the status manually. -![Build status menu](media/create-repo-intellij/build-status-menu.png) +You can select on the icon for more options such as viewing build details, queuing a new build, and updating the status manually. +![Screenshot shows Build status menu.](media/create-repo-intellij/build-status-menu.png) +## View pull requests and work items -## View Pull Requests and Work Items -Under the **Version Control** menu, a **Pull Request** tab and **Work Items** tab exist to allow you to easily view the information you need without leaving -the IDE. The **Pull Request** tab shows you the current pull requests created by you and assigned to you along with their status. The tab also -gives you the ability to create and/or abandon pull requests. +Under the **Version Control** menu, the **Pull Request** and **Work Items** tabs let you view the information you need without leaving the IDE. The **Pull Request** tab shows you the current pull requests created by you and assigned to you along with their status. The tab also gives you the ability to create and/or abandon pull requests. -![Pull request menu](media/create-repo-intellij/build-status-menu.png) +![Screenshot shows Pull request menu.](media/create-repo-intellij/build-status-menu.png) +Under the **Work Items** tab, you can view the work items based on queries that you created or use the default query to see work items assigned to you. You can also create a branch based off of a work item so that you can associate a work item with branch for future traceability purposes. +![Screenshot shows Work items menu.](media/create-repo-intellij/work-items-menu.png) -Under the **Work Items** tab, you can view the work items based on queries that you have created or use the default query to see work items -that are assigned to you. You can also create a branch based off of a work item so that you can associate a work item with branch for -future traceability purposes. - -![Work items menu](media/create-repo-intellij/work-items-menu.png) - - - - -## Next Steps +## Next steps > [!div class="nextstepaction"] -> [Check out the entire DeepSpace IntelliJ tutorial](/azure/devops/java/labs/e2eintellij) +> [Use the DeepSpace IntelliJ tutorial](/azure/devops/java/labs/e2eintellij) -> [!div class="nextstepaction"] -> [View the IntelliJ plugin FAQ](/previous-versions/azure/devops/all/java/intellij-faq) +## Related articles + +- [View the IntelliJ plugin FAQ](/previous-versions/azure/devops/all/java/intellij-faq) diff --git a/docs/repos/git/creatingrepo.md b/docs/repos/git/creatingrepo.md index 4e689b0725e..0364e2dedba 100644 --- a/docs/repos/git/creatingrepo.md +++ b/docs/repos/git/creatingrepo.md @@ -30,12 +30,10 @@ This article provides procedures for the following tasks: For an overview of the Git workflow, see [Azure Repos Git tutorial](gitworkflow.md). - -## Prerequisites for access to Azure Repos +## Prerequisites [!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] - ## Create a local Git repo from a new solution Visual Studio doesn't support creating a local Git repo when you create a new solution. Instead, create your Visual Studio solution, then follow the steps in [Create a local Git repo from an existing solution](#create-a-local-git-repo-from-an-existing-solution). @@ -247,16 +245,13 @@ You can share your code with others by connecting your local Git repo to an **Az :::image type="content" source="media/creatingrepo/visual-studio-2019/common/azure-clone-repo-popup.png" border="true" alt-text="Screenshot of the 'Clone Repository' popup from the Azure DevOps project site."::: -1. To publish your local commit to **Azure repos**, run the following commands at the command prompt in your local git repo folder, using the clone URL from the previous step. +1. To publish your existing local git repository to **Azure repos**, run the following commands in the folder containing the local git repository using the clone URL from the previous step. If you don't have a local git repository yet, create one using the previous steps in this article. > [!div class="tabbedCodeSnippets"] ```console - > git init - > git remote add origin - > git add . - > git status - > git commit -m "initial commit" - > git push -u origin main + > git remote add origin + > git status + > git push -u origin main ``` Your code is now published to the `main` branch of then **Azure Repos** Git repo. diff --git a/docs/repos/git/delete-branch.md b/docs/repos/git/delete-branch.md index b5808a602ad..ef12ff660ff 100644 --- a/docs/repos/git/delete-branch.md +++ b/docs/repos/git/delete-branch.md @@ -15,13 +15,19 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] >[!IMPORTANT] -> This topic covers deleting a Git branch via the web in Azure DevOps Services and TFS. If you need to delete a Git branch in your own repo from Visual Studio or the command line, +> This article covers deleting a Git branch via the web in Azure DevOps. To delete a Git branch in your own repo from Visual Studio or the command line, > follow [these steps](./delete-git-branch.md) in the [Azure Repos Git tutorial](gitworkflow.md). +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + +## Delete Git branch + 1. Open your repo on the web and [select the **Branches** view](manage-your-branches.md). -2. Locate your branch on the branches page. If you don't see it, select **All** to view all branches and filter the branches using the **Search all branches** box in the upper right. +2. Locate your branch on the branches page. If you don't see it, select **All** to view all branches and filter the branches using the **Search all branches** box. 3. Select the trashcan icon next to the branch you want to delete. - ![Delete your branch in the Azure DevOps Services/TFS web portal](media/branches/delete_branch.png) + ![Screenshot shows delete your branch in the Azure DevOps web portal.](media/branches/delete_branch.png) diff --git a/docs/repos/git/delete-existing-repo.md b/docs/repos/git/delete-existing-repo.md index 00268bfccdf..c137ff76f62 100644 --- a/docs/repos/git/delete-existing-repo.md +++ b/docs/repos/git/delete-existing-repo.md @@ -19,18 +19,18 @@ Remove unused Git repos from your project when they are no longer needed. The st > [!IMPORTANT] > You cannot remove a repo if it is the only Git repo in the Azure DevOps project. If you need to delete the only Git repo in a project, [create a new Git repo](create-new-repo.md) first, then delete the repo. - ## Prerequisites -- You must have [Delete Repository permissions](set-git-repository-permissions.md) to delete a repo from a project. +| Category | Requirements | +|-------------|-------------| +| **Permissions** | [**Delete Repository** permission](set-git-repository-permissions.md). | ::: moniker range="azure-devops" > [!NOTE] -> If you want to use the Azure DevOps CLI **az repos delete** command, follow the steps in [Get started with Azure DevOps CLI](../../cli/index.md). +> To use the Azure DevOps CLI **az repos delete** command, see [Get started with Azure DevOps CLI](../../cli/index.md). ::: moniker-end - ## Delete a Git repo from the web > [!TIP] @@ -39,7 +39,7 @@ Remove unused Git repos from your project when they are no longer needed. The st # [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Select **Repos**, **Files**. @@ -59,34 +59,12 @@ Remove unused Git repos from your project when they are no longer needed. The st ::: moniker-end -::: moniker range="tfs-2018" - -1. Select the settings icon in the web to bring up the project administration page and choose **Version Control**. - - ![Version control settings](media/repo-mgmt/version-control-settings.png) - -2. Select the Git repository to remove from the list shown and select the **...** next to the name. Choose **Delete Repository**. - - ![remove the Azure DevOps Services repo using the ellipses link next to the repo name](media/repo-mgmt/remove-repo.png) - - >[!NOTE] - >If the **Repositories** pane is not expanded, select **>** to expand it and display the list of repositories. - > - >![Repositories pane](media/repo-mgmt/expand-repositories-pane.png) - -3. Confirm the deletion of the repository by typing the repo's name and selecting **Delete**. - - ![Delete repository confirm](media/repo-mgmt/delete-repository-confirm.png) - -::: moniker-end - # [Azure DevOps CLI](#tab/azure-devops-cli) -::: moniker range=">= azure-devops-2020" +::: moniker range="azure-devops" You can use Azure DevOps CLI to delete an Azure DevOps Git repository. - ```azurecli az repos delete --id [--detect {false, true}] @@ -107,12 +85,10 @@ az repos delete --id |`subscription`|Name or ID of subscription. You can configure the default subscription using `az account set -s `.| |`yes`|Don't prompt for confirmation.| - **Example** The following command deletes the Fabrikam repository, ID `0d58f562-4a10-495d-94d7-7ac61a22d7cc`. This example uses the following default configuration: `az devops configure --defaults organization=https://dev.azure.com/fabrikamprime project="Fabrikam Fiber"`. - ```azurecli az repos delete --id 0d58f562-4a10-495d-94d7-7ac61a22d7cc Are you sure you want to delete this repository? (y/n): y @@ -121,9 +97,8 @@ Are you sure you want to delete this repository? (y/n): y ::: moniker-end -::: moniker range="< azure-devops-2020" +::: moniker range="< azure-devops" [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] ::: moniker-end - *** \ No newline at end of file diff --git a/docs/repos/git/delete-git-branch.md b/docs/repos/git/delete-git-branch.md index 752ea250848..b38f9951fa8 100644 --- a/docs/repos/git/delete-git-branch.md +++ b/docs/repos/git/delete-git-branch.md @@ -21,6 +21,12 @@ This article describes how to delete a Git branch by using two different methods > [!NOTE] > Deleting a branch in your local repo doesn't remove the branch on the remote. +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + +## Delete branch + #### [Browser](#tab/Browser/) 1. View your repo's branches by selecting **Repos** > **Branches** while viewing your repo on the web. @@ -68,7 +74,7 @@ git push origin --delete * * * -## Next Steps +## Next steps > [!div class="nextstepaction"] -> [Restore a deleted branch](./restore-deleted-branch.md) \ No newline at end of file +> [Restore a deleted branch](./restore-deleted-branch.md) diff --git a/docs/repos/git/find-a-file.md b/docs/repos/git/find-a-file.md index e996aabe085..bf9ed80d884 100644 --- a/docs/repos/git/find-a-file.md +++ b/docs/repos/git/find-a-file.md @@ -26,16 +26,9 @@ While browsing your Git repository, start typing in the path control box to sear ### Hotkey navigation -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Launch the Find a File experience from the keyboard with the `t` shortcut from the **Files** or **Commits** pages in the **Repos** view. Use the up and down arrows to cycle through the results, and click or press Enter to open a result. Press `Esc` to close the Find a File experience. ::: moniker-end -::: moniker range="tfs-2018" - -Launch the Find a File experience from the keyboard with the `t` shortcut from the **Files** or **History** tabs in the **Files** page. Use the up and down arrows to cycle through the results, and click or press Enter to open a result. Press `Esc` to close the Find a File experience. - -::: moniker-end - - diff --git a/docs/repos/git/forks.md b/docs/repos/git/forks.md index 7d17b164dc3..1ab3198a9e5 100644 --- a/docs/repos/git/forks.md +++ b/docs/repos/git/forks.md @@ -15,9 +15,9 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-eq-2019](../../includes/version-vs-gt-eq-2019.md)] -Git repo forks are useful when people want to make experimental, risky, or confidential changes to a codebase, but those changes need to be isolated from the codebase in the original repo. A new fork is basically a clone of the original repo pushed to a new remote repo. The fork is independent of the original repo, and is a complete copy unless you specify a single branch. +Git repo forks are useful when people want to make experimental, risky, or concealed changes to a codebase, but those changes need to be isolated from the codebase in the original repo. A new fork is basically a new remote repo that shares the source code of the original repo. -As an independent copy, changes you make to your fork, such as adding commits or branches, aren't shared with the original repo. If you want to merge your codebase changes into the original repo, you must create a [pull request](pull-requests.md) (PR) to request review and approval of those changes. +As an independent version, changes you make to your fork, such as adding commits or branches, are hidden from the original repo. If you want to merge your codebase changes into the original repo, you must create a [pull request](pull-requests.md) (PR) to request review and approval of those changes. The forking process doesn't transfer any permissions, policies, or build pipelines from the original repo to your fork. @@ -35,7 +35,7 @@ In this article you learn how to: >* Create and complete a PR >* Sync your fork -## Prerequisites for access to Azure Repos +## Prerequisites [!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] @@ -70,7 +70,7 @@ The forking workflow consists of five steps that are described in the following The following steps describe how to fork an Azure Repos Git repo. >[!NOTE] ->To fork a repo in a Azure DevOps project, you must have the [Create Repository](../../organizations/security/permissions.md#git-repository-object-level) permission for that project. Repo owners should consider creating a dedicated project for forks and assigning the Create Repository permission to all contributors. For more information about setting permissions, see [Set Git repository permissions](set-git-repository-permissions.md). +>To fork a repo in an Azure DevOps project, have the [Create Repository](../../organizations/security/permissions.md#git-repository-object-level) permission for that project. Repo owners should consider creating a dedicated project for forks and assigning the Create Repository permission to all contributors. For more information about setting permissions, see [Set Git repository permissions](set-git-repository-permissions.md). 1. From your web browser, navigate to the Azure Repos Git repo that you want to fork. Select **Repo > Files** and then choose **Fork** from the ellipsis menu to open the **Fork** dialog. @@ -123,7 +123,7 @@ git remote set-url upstream ## Push local changes to your fork -When you fork, you create a personal and independent copy of the remote repo. So, there's nothing to prevent you from working directly in the `main` branch of the local clone and then pushing that work to the `main` branch of your fork. However, it's generally better to use [feature branches](git-branching-guidance.md#use-feature-branches-for-your-work) for your work. By using feature branches: +When you fork, you create a personal version of the original repository (original repository is referred as "upstream"). Fork is independent from the upstream, but fork shares the code and retains a link to the upstream, allowing for future synchronization. So, there's nothing to prevent you from working directly in the `main` branch of the local clone and then pushing that work to the `main` branch of your fork. However, it's generally better to use [feature branches](git-branching-guidance.md#use-feature-branches-for-your-work) for your work. By using feature branches: - You can maintain multiple, independent workstreams simultaneously. @@ -152,7 +152,7 @@ In Azure Repos, to merge into the original repo the changes that you pushed to y For more information about how to create a PR using your browser, Visual Studio, or the Azure DevOps CLI, see [Create a PR](pull-requests.md#create-a-pull-request). >[!IMPORTANT] - >Anyone with the [Read](../../organizations/security/permissions.md#git-repository-object-level) permission on the upstream repo can open a PR to it. If the upstream repo has a PR build [pipeline](../../pipelines/repos/azure-repos-git.md) that's configured to run on PR creation, a build will run on the changes introduced by your PR. + >Anyone in Project Valid Users and with the [Read](../../organizations/security/permissions.md#git-repository-object-level) permission on the upstream repo can open a PR to it. If the upstream repo has a PR build [pipeline](../../pipelines/repos/azure-repos-git.md) that's configured to run on PR creation, a build will run on the changes introduced by your PR. 1. For your PR to complete, all required reviewers must approve the PR changes and all target branch policies must be met. On PR approval and [completion](complete-pull-requests.md#complete-a-pull-request), the changes in the PR source branch will merge into the PR target branch. diff --git a/docs/repos/git/git-branching-guidance.md b/docs/repos/git/git-branching-guidance.md index 0694cc038fd..ef9e1f12269 100644 --- a/docs/repos/git/git-branching-guidance.md +++ b/docs/repos/git/git-branching-guidance.md @@ -56,7 +56,7 @@ Some suggestions for naming your feature branches: * feature/feature-area/feature-name * hotfix/description -::: moniker range=">= tfs-2018" +::: moniker range="<=azure-devops" >[!NOTE] >For information on setting policies to enforce a branch naming strategy, see [Require branch folders](require-branch-folders.md). diff --git a/docs/repos/git/git-config.md b/docs/repos/git/git-config.md index 351d5d42c5a..ba71c8a6be9 100644 --- a/docs/repos/git/git-config.md +++ b/docs/repos/git/git-config.md @@ -42,6 +42,10 @@ In this article you learn how to: >* Modify Git configuration file settings >* Modify Visual Studio Git-related settings +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## Explore Git settings #### [Visual Studio 2022](#tab/visual-studio-2022) diff --git a/docs/repos/git/git-dates.md b/docs/repos/git/git-dates.md index 8e1baba860f..cbcda3a42ad 100644 --- a/docs/repos/git/git-dates.md +++ b/docs/repos/git/git-dates.md @@ -1,7 +1,7 @@ --- title: Dates in Git titleSuffix: Azure Repos -description: How dates work in Git +description: Learn how dates work in Git. ms.assetid: c5e233e2-cc84-4ca6-8ca3-8eb6d686533a ms.service: azure-devops-repos ms.topic: conceptual @@ -16,16 +16,16 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] Git tracks two dates in commits: author date and commit date. -In addition, Azure DevOps Services and TFS track when a commit was first pushed to the server. +In addition, Azure DevOps Services and Azure DevOps Server track when a commit was first pushed to the server. -* **Author date**: when a commit was originally authored. Typically, when someone first ran `git commit`. -* **Commit date**: when a commit was applied to the branch. In many cases it is the same as the author date. Sometimes it differs: if a commit was amended, rebased, or applied by someone other than the author as part of a patch. In those cases, the date will be when the rebase happened or the patch was applied. -* **Push date**: when a commit was pushed to the remote repository in question. This date is specific to the remote version control system you are using, and won't be available in your local repository. +* **Author date**: When a commit was originally authored. Typically, this date is when someone first ran `git commit`. +* **Commit date**: When a commit was applied to the branch. In many cases, it's the same as the author date. It can differ if a commit was amended, rebased, or applied by someone other than the author as part of a patch. In those cases, the date is when the rebase happened or the patch was applied. +* **Push date**: When a commit was pushed to the remote repository in question. This date is specific to the remote version control system that you're using and isn't available in your local repository. -When you run `git log`, by default you will see the *author date*. -If you want to see commit date, you can use one of the many command line options, such as `--pretty=fuller`. +When you run `git log`, the author date appears by default. +If you want the commit date to appear, you can use one of the many command-line options, such as `--pretty=fuller`. -Let's look at a brief example to see these concepts in practice. First we will create a normal commit: +Let's look at a brief example to see these concepts in practice. First, create a normal commit: ``` git init @@ -34,7 +34,7 @@ git add * git commit -m "A normal commit message" ``` -Now let's amend our commit with a different message: +Now, amend that commit with a different message: ``` echo again > file.txt @@ -42,7 +42,7 @@ git add * git commit --amend -m "An amended commit" ``` -If we look at our regular log history we would see something like the following: +If you check the regular log history, information like the following example appears: ``` git log @@ -53,7 +53,7 @@ Date: Thu Feb 25 19:38:54 2016 -0500 An amended commit ``` -Now let's view the same commit with the author date: +Now, view the same commit with the author date: ``` git log --pretty=fuller @@ -66,21 +66,21 @@ CommitDate: Thu Feb 25 19:39:36 2016 -0500 An amended commit ``` -Note the (slight) difference between the author date and commit date above. -The author date is my original, unedited, commit time. The commit date is the time at which I ran the `--amend` command. +Note the slight difference between the author date and commit date in the examples. +The author date is the original, unedited commit time. The commit date is the time at which you ran the `--amend` command. -In fact, there are a lot of `git log` options to help you understand dates better. -For example, passing the `--date` flag will allow you to determine how dates are displayed. -This can be useful for normalizing time zones (git displays dates in their original time zone, by default) or changing the date display string. +Many `git log` options can help you understand dates better. +For example, if you pass the `--date` flag, you can determine how dates are displayed. +This flag can be useful for normalizing time zones, because Git displays dates in their original time zone by default. It can also be useful for changing the date display string. -To learn more about the various formatting options, see the [git log man page](https://git-scm.com/docs/git-log). +For more information about the formatting options, see the [git-log man page](https://git-scm.com/docs/git-log). -## Changing Git Dates +## Change Git dates -When you're getting ready to commit your code, note that you have the ability to set both the author and commit dates. This isn't something you should do often. +When you're getting ready to commit your code, you have the ability to set both the author and commit dates. This ability isn't something you should use often. -You can change the author date of a given commit by passing the `--date` flag to `git commit`. -There are various articles regarding the formatting of this flag, but the gist is that it isn't well-documented. [This StackOverflow question](https://stackoverflow.com/questions/19742345/what-is-the-format-for-date-parameter-of-git-commit) does a great job of explaining the acceptable date formats. +You can change the author date of a commit by passing the `--date` flag to `git commit`. +Various articles discuss the formatting of this flag, but it isn't well documented. [This Stack Overflow question](https://stackoverflow.com/questions/19742345/what-is-the-format-for-date-parameter-of-git-commit) does a great job of explaining the acceptable date formats. -You can also use the environment variables `GIT_COMMITTER_DATE` and `GIT_AUTHOR_DATE` to set the corresponding dates, as documented in the [man page](https://git-scm.com/docs/git-commit). -If you need to go this route, use [this Stack Overflow question](https://stackoverflow.com/questions/454734/how-can-one-change-the-timestamp-of-an-old-commit-in-git) as a starting point. +You can also use the environment variables `GIT_COMMITTER_DATE` and `GIT_AUTHOR_DATE` to set the corresponding dates, as documented on the [git-commit man page](https://git-scm.com/docs/git-commit). +If you need to take this approach, use [this Stack Overflow question](https://stackoverflow.com/questions/454734/how-can-one-change-the-timestamp-of-an-old-commit-in-git) as a starting point. diff --git a/docs/repos/git/git-names.md b/docs/repos/git/git-names.md index 0e4c7d58fbe..0dc9497aaa4 100644 --- a/docs/repos/git/git-names.md +++ b/docs/repos/git/git-names.md @@ -1,7 +1,7 @@ --- title: Author names in Git titleSuffix: Azure Repos -description: How Git stores author names +description: Learn how Git stores author names. ms.assetid: 09e60acb-fa48-4843-9f5d-5dfed981f467 ms.service: azure-devops-repos ms.topic: conceptual @@ -12,54 +12,57 @@ ms.subservice: azure-devops-repos-git # How names work in Git + [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] When you commit to your local repo, Git includes your name and email address as part of the commit. -This can sometimes lead to confusion. -The name and email on your commits may not match the identity you log in with on a Git host like Azure Repos. -Further, you may have commits under several different names and email addresses even though you were the author for each of them. +This behavior can sometimes cause confusion. +The name and email on your commits might not match the identity that you use to sign in to a Git host like Azure Repos. +You might have commits under several names and email addresses, even though you were the author for each of them. + +## Why does your repo show multiple names for you? -## Why are there multiple names for me in my repo? +Have you searched for your name on the [History](commit-history.md) page and found multiple, slightly different entries for yourself? +You probably wondered how it happened. -Have you searched your name in the [History](commit-history.md) page and been surprised to see multiple, slightly different entries for yourself? -You were probably left wondering how this happened and what you can do about it. -The answer is simple: in different commits, your name was recorded differently. -Maybe you have two different computers, one configured with your full name (e.g. Frances) and the other with the nickname you go by (e.g. Frank). -Or maybe you have a home computer connected to your Microsoft Account (e.g. frances@outlook.com) and a work computer connected to your employer's Azure Active Directory (e.g. frances_t@fabrikam.com). -It's even possible you changed your settings over time, so older commits have one name and newer commits have another. +The answer is simple: your name was recorded differently across commits. +Maybe you have two computers, one configured with your full name (for example, Frances) and the other configured with a nickname (for example, Frank). +Or maybe you have a home computer that's connected to your Microsoft account (for example, `frances@outlook.com`) and a work computer that's connected to your employer's Microsoft Entra ID instance (for example, `frances_t@fabrikam.com`). +It's even possible that you changed your settings over time, so older commits have one name and newer commits have another. ## Where does Git get your name and email? -Git stores your name and email address in its [config file](https://git-scm.com/docs/git-config). +Git stores your name and email address in its [configuration file](https://git-scm.com/docs/git-config). This file can be at the system level, global to your account on your computer, or local to a repository. -If a name and email aren't found in any of these places, Git will do its best to get this information from your operating system. -Your details are included in the commit, marking you as the author of that commit. +If Git can't find a name and email in any of these places, it tries to get this information from your operating system. +Git includes your details in the commit to mark you as the author of that commit. -When you set up Git for the first time on a new machine, you may create a commit using Git's "best effort" information. -Git will prompt you to set an explicit name and email address, and the new settings will be used for subsequent commits. -This is a frequent source of one author having multiple names. +When you set up Git for the first time on a new machine, you might create a commit by using Git's "best effort" information. +Git prompts you to set an explicit name and email address, and it uses the new settings for subsequent commits. +This change is often the reason why one author has multiple names. ## Where does Azure DevOps Services get your name and email? Your details in Azure DevOps Services come from your [profile](https://app.vssps.visualstudio.com/profile/view). -Your profile was originally populated from details in your Microsoft Account or Azure Active Directory account, but you may change these details yourself. -When you edit a file in the web or complete a PR, Azure Repos supplies your profile details as the author of the commit. +Your profile was originally populated from details in your Microsoft account or Microsoft Entra account, but you can change these details yourself. + +When you edit a file on the web or complete a pull request, Azure Repos supplies your profile details as the author of the commit. This is another opportunity for your name or email address to be specified differently. -## How do I change my information in Git and Azure DevOps Services? +## How do you change your information in Git and Azure DevOps Services? -In Git, you can run two commands to change your name and email address: +In Git, you can run the following commands to change your name and email address. Replace the example values with your information. ``` git config --global user.name "Frances Totten" git config --global user.email "frances_t@fabrikam.com" ``` -In Azure DevOps Services, you can update your profile by clicking your picture in the upper right corner and choosing [My profile](../../organizations/settings/set-your-preferences.md). +In Azure DevOps Services, you can [update your profile](../../organizations/settings/set-your-preferences.md) by selecting your picture in the upper-right corner and then selecting **My profile**. -## How do I change the author displayed for past commits? +## How do you change the author displayed for past commits? -If you've made a single change locally and it has the wrong author, you can amend that commit with new author information. Be sure to format it like this: `Name `. +If you made a single change locally and it has the wrong author, you can amend that commit with new author information. Be sure to format it as `Name `, as shown in the following example. ``` git commit --amend --author="Frances L. Totten " diff --git a/docs/repos/git/git-tags.md b/docs/repos/git/git-tags.md index 9c4109f9c47..0ecb9947839 100644 --- a/docs/repos/git/git-tags.md +++ b/docs/repos/git/git-tags.md @@ -26,7 +26,6 @@ This article provides an overview of working with Git tags in Azure DevOps and V #### [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" You can view tags in the **Tags** view and in the **Commits** view in the web portal. @@ -36,47 +35,19 @@ You can view tags in the **Tags** view and in the **Commits** view in the web po 1. To view the tags in your repo, navigate to your project in the web portal, choose **Repos**, **Tags**, and select the desired repo. - ![View tags in Tags view.](media/git-tags/view-tags-new-nav.png) + :::image type="content" source="media/git-tags/view-tags-new-nav.png" alt-text="Screenshot of tags navigation in the web portal."::: Annotated tags are displayed with a tag name, message, commit, tagger, and creation date. Lightweight tags are displayed with a tag name and commit. 2. To filter the list of tags, type a search term into the **Search tag name** box and press **Enter**. - ![Filter tags](media/git-tags/filter-tags.png) + :::image source="media/git-tags/filter-tags.png" alt-text="Screenshot of filter tags in the web portal." ::: ### View tags in the Commits view To view tags for a specific branch in the **Commits** view, navigate to your repo in the web portal, choose **Repos**, **Commits**, and select your branch. -![View tags in Commits view.](media/git-tags/view-tags-from-commits-new-nav.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -You can view tags in the **Tags** view and in the **Commits** view in the web portal. - -[!INCLUDE [project-urls](../../includes/project-urls.md)] - -### View tags in the Tags view - -1. To view the tags in your repo, navigate to your project in the web portal, choose **Code**, select the desired repo, and choose **Tags**. - - ![View tags in Tags view.](media/git-tags/view-tags.png) - - Annotated tags are displayed with a tag name, message, commit, tagger, and creation date. Lightweight tags are displayed with a tag name and commit. - -2. To filter the list of tags, type a search term into the **Search tag name** box and press **Enter**. - - ![Filter tags](media/git-tags/filter-tags.png) - -### View tags in the Commits view - -To view tags for a specific branch in the **Commits** view, navigate to your repo in the web portal, choose **Code**, **Commits**, and select your branch. - -![View tags in Commits view.](media/git-tags/view-tags-from-commits.png) - -::: moniker-end +:::image type="content" source="media/git-tags/view-tags-from-commits-new-nav.png" alt-text="Screenshot of tags in the Commits view in the web portal." ::: #### [Visual Studio](#tab/visual-studio) @@ -86,9 +57,9 @@ You can view tags in the **History** view. 1. From the **Git** menu in the menu bar, select **Manage Branches**. -1. Select a branch to view history. +1. To view history, select a branch. - ![View tags in the History view.](media/git-tags/view-tags-from-commits-vs.png) + :::image type="content" source="media/git-tags/view-tags-from-commits-vs.png" alt-text="Screenshot of Visual Studio view tags in the History view."::: The red shapes are branches, and the green shapes are tags. @@ -98,23 +69,23 @@ You can view tags in the **History** view. 1. To view all tags in a repo, select **Tags** from the **Home** view. - ![Tags button](media/git-tags/navigate-tags-pane-vs.png) + :::image type="content" source="media/git-tags/navigate-tags-pane-vs.png" alt-text="Screenshot of the Visual Studio tags button." ::: 2. Tags are displayed under the currently connected repo name. - ![View tags under the currently connected repo name.](media/git-tags/view-tags-vs.png) + :::image type="content" source="media/git-tags/view-tags-vs.png" alt-text="Screenshot of Visual Studio tags view." ::: Annotated tags display a tooltip that contains the tag name, tagger, tag date, and message. Lightweight tags have only the tag name in the tooltip. - ![View annotated tags.](media/git-tags/tag-style-vs.png) + :::image type="content" source="media/git-tags/tag-style-vs.png" alt-text="Screenshot of Visual Studio annotated tags view." ::: For more information about the tagged commit, right-click the tag and select **View Commit Details**. - ![Commit details](media/git-tags/view-commit-details-vs.png) + :::image type="content" source="media/git-tags/view-commit-details-vs.png" alt-text="Screenshot of Visual Studio view commit details." ::: 3. To filter the list of tags, type a search term into the **Type here to filter the list** box. - ![Filter tags in the Tags view.](media/git-tags/filter-tags-vs.png) + :::image type="content" source="media/git-tags/filter-tags-vs.png" alt-text="Screenshot of Visual Studio filter tags in the tags view." ::: To retrieve the current list of tags from the source repo, perform a [fetch](pulling.md?tabs=visual-studio#download-changes-with-fetch) operation. @@ -122,15 +93,13 @@ To retrieve the current list of tags from the source repo, perform a [fetch](pul ## Create tag -To create a tag, you must have the [Create Tag](../../organizations/security/permissions.md#git-repository-object-level) permission, which is included [by default](../../organizations/security/default-git-permissions.md) in the [Contributors](../../organizations/security/permissions.md#project-level-groups) group and higher. +To create a tag, have the [Create tag](../../organizations/security/permissions.md#git-repository-object-level) permission, which is included [by default](../../organizations/security/default-git-permissions.md) in the [Contributors](../../organizations/security/permissions.md#project-level-groups) group and higher. > [!NOTE] > Tag names can't contain ASCII control characters, such as spaces, tildes, and colons. It's common practice to use lowercase characters and to separate words with a hyphen. Tag name length shouldn't exceed 250 ASCII characters. To avoid ambiguity between tag names and commit hashes, don't use tag names that consist of 40 hexadecimal characters. For more information on tag naming, see [git-check-ref-format](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-check-ref-format.html). #### [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" - You can create annotated tags using the web portal from both the **Tags** view and the **Commits** view. >[!IMPORTANT] @@ -138,54 +107,23 @@ You can create annotated tags using the web portal from both the **Tags** view a ### Create tags from the Tags view -1. Select **Create Tag** from the **Tags** view in the web portal to create a new annotated tag. +1. Select **Create tag** from the **Tags** view in the web portal to create a new annotated tag. - ![Create tag](media/git-tags/create-tag-button.png) + :::image type="content" source="media/git-tags/create-tag-button.png" alt-text="Screenshot of create tag button in the web portal." ::: -2. Specify a **Name**, select the branch to **Tag from**, enter a **Description** (required since you are creating an annotated tag), and select **Create**. +2. Specify a **Name**, select the branch to **Tag from**, enter a **Description** (required since you're creating an annotated tag), and select **Create**. - ![Select Create.](media/git-tags/create-tag.png) + :::image type="content" source="media/git-tags/create-tag.png" alt-text="Screenshot of create tag dialog in the web portal." ::: 3. The new tag is displayed in the tag list. - ![View new tag](media/git-tags/tag-created.png) + :::image type="content" source="media/git-tags/tag-created.png" alt-text="Screenshot of new tag in the web portal." ::: ### Create tags from the Commits view To create a tag directly from the commits view, right-click the desired tag and choose **Create tag**. -![Create tag from the Commits view.](media/git-tags/create-tag-from-commit.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -You can create annotated tags using the web portal from both the **Tags** view and the **Commits** view. - ->[!IMPORTANT] -> You can only create annotated tags in the web portal or [Visual Studio](git-tags.md?tabs=visual-studio#create-tag). To create a lightweight tag, you can use [Git command line](https://git-scm.com/book/en/v2/Git-Basics-Tagging). - -### Create tags from the Tags view - -1. Select **Create Tag** from the **Tags** view in the web portal to create a new annotated tag. - - ![Create tag from the Tags view.](media/git-tags/create-tag-button.png) - -2. Specify a **Name**, select the branch to **Tag from**, enter a **Description** (required since you are creating an annotated tag), and select **Create**. - - ![Select Create.](media/git-tags/create-tag.png) - -3. The new tag is displayed in the tag list. - - ![View new tag](media/git-tags/tag-created.png) - -### Create tags from the Commits view - -To create a tag directly from the commits view, right-click the desired tag and choose **Create tag**. - -![Create tag from the Commits view.](media/git-tags/create-tag-from-commit.png) - -::: moniker-end +:::image type="content" source="media/git-tags/create-tag-from-commit.png" alt-text="Screenshot of create tag from commits view in the web portal." ::: #### [Visual Studio](#tab/visual-studio) @@ -199,7 +137,7 @@ You can view tags in the **History** view. 1. Select a branch to view history, right-click a commit, and select **New Tag**. - ![Create tag from the History view, Visual Studio.](media/git-tags/create-tag-from-commit-vs.png) + :::image type="content" source="media/git-tags/create-tag-from-commit-vs.png" alt-text="Screenshot of create tag from history view in Visual Studio." ::: 1. In the **Create a new tag** dialog, enter a **Tag name** only for a lightweight tag or a **Tag name** and **Tag message** for an annotated tag. Select **Create**. @@ -209,70 +147,49 @@ You can view tags in the **History** view. 1. Select **New Tag** in the **Tags** view to create a new tag. - ![Create tag in Visual Studio.](media/git-tags/create-tag-button-vs.png) + :::image type="content" source="media/git-tags/create-tag-button-vs.png" alt-text="Screenshot of create tag button in Visual Studio." ::: -2. To create a tag against the tip of the current branch, specify a name in the **Enter a tag name** box, optionally provide a tag message, and select **Create Tag**. +2. To create a tag against the tip of the current branch, specify a name in the **Enter a tag name** box, optionally provide a tag message, and select **Create tag**. - ![Select Create Tag in Visual Studio.](media/git-tags/create-tag-current-branch-vs.png) + :::image type="content" source="media\git-tags\create-tag-current-branch-vs.png" alt-text="Screenshot of create tag dialog in Visual Studio." ::: To select the branch to create the tag from, clear the **Create tag against tip of current branch** check box, and select a branch from the **Select a branch** drop-down. - ![Select a branch.](media/git-tags/create-tag-select-branch-vs.png) + :::image type="content" source="media/git-tags/create-tag-select-branch-vs.png" alt-text="Screenshot of select a branch dialog in Visual Studio." ::: 3. The new tag is created locally. Right-click the new tag and choose **Push** to push it to the remote repo. Select **Push All** to push all new local tags to the remote repo. - ![Push new tag](media/git-tags/tag-created-vs.png) + :::image type="content" source="media/git-tags/tag-created-vs.png" alt-text="Screenshot of push new tag in Visual Studio." ::: --- + You can programmatically create annotated tags via the Azure DevOps [REST API](/rest/api/azure/devops/git/annotated-tags/create). To create tags via an Azure pipeline using the `git tag` command. For more information, see [git tag](https://git-scm.com/docs/git-tag). + + ## Delete tag >[!IMPORTANT] >Use caution when deleting tags from your repo. If the repo has been pulled, forked, or cloned by another user, the tag will still exist in their copy of the repo. You should only delete local tags, or if you are sure that the repo hasn't been pulled, cloned, or forked since you created your tag. -To delete a tag, you must have the [Force Push](../../organizations/security/permissions.md#git-repository-object-level) permission at the **Repository** level or the **All tags** level (which inherits its permissions from the repository level if not explicitly set). Force push permissions for a tag are also automatically inherited by the tag creator. +To delete a tag, have the [Force push](../../organizations/security/permissions.md#git-repository-object-level) permission at the **Repository** level or the **All tags** level (which inherits its permissions from the repository level if not explicitly set). The creator also inherits **Force push** permissions for a tag. #### [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" - -### Delete a tag in the remote repo - -The steps in this procedure show you how to delete a tag in the remote repo using the Azure DevOps Services web portal. - -1. To delete a tag, select the ellipsis to the right of the tag name and choose **Delete tag**. - - ![Delete tag](media/git-tags/delete-tag.png) - -2. Select **Delete** to confirm. - - ![Select Delete.](media/git-tags/delete-tag-confirm.png) - -3. The tag is deleted, and won't be displayed the next time you navigate to the **Tags** view. - - ![Tag deleted](media/git-tags/tag-deleted.png) - -::: moniker-end - -::: moniker range="tfs-2018" - ### Delete a tag in the remote repo The steps in this procedure show you how to delete a tag in the remote repo using the Azure DevOps Services web portal. 1. To delete a tag, select the ellipsis to the right of the tag name and choose **Delete tag**. - ![Delete tag](media/git-tags/delete-tag.png) + :::image type="content" source="media/git-tags/delete-tag.png" alt-text="Screenshot of delete tag in the web portal." ::: 2. Select **Delete** to confirm. - ![Select Delete.](media/git-tags/delete-tag-confirm.png) + :::image type="content" source="media/git-tags/delete-tag-confirm.png" alt-text="Screenshot of delete tag confirmation in the web portal." ::: 3. The tag is deleted, and won't be displayed the next time you navigate to the **Tags** view. - ![Tag deleted](media/git-tags/tag-deleted.png) - -::: moniker-end + :::image type="content" source="media/git-tags/tag-deleted.png" alt-text="Screenshot of tag deleted in the web portal." ::: #### [Visual Studio](#tab/visual-studio) @@ -282,7 +199,7 @@ The steps in this procedure show you how to delete a tag in the local repo using Right-click the tag to delete and choose **Delete Locally** -![Delete tag using Visual Studio 2017 Update 6.](media/git-tags/delete-tag-vs.png) +:::image type="content" source="media/git-tags/delete-tag-vs.png" alt-text="Screenshot of delete tag in Visual Studio 2017." ::: >[!IMPORTANT] >If your tag has already been pushed to the remote repo, you should not delete it. If the repo has been pulled, forked, or cloned by another user, the tag will still exist in their copy of the repo. You should only delete local tags. @@ -293,37 +210,17 @@ Right-click the tag to delete and choose **Delete Locally** #### [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" - -1. To create a branch from a tag, select the ellipsis to the right of the tag name and choose **New branch**. - - ![New branch from tag](media/git-tags/branch-from-tag.png) - -2. Specify a **Name**, optionally select any **Work items to link**, and choose **Create branch**. - - ![Choose Create branch.](media/git-tags/branch-from-tag-create.png) - -3. The branch is created and you are taken to the new branch in the web portal. - - ![Branch created.](media/git-tags/branch-from-tag-created.png) - -::: moniker-end - -::: moniker range="tfs-2018" - 1. To create a branch from a tag, select the ellipsis to the right of the tag name and choose **New branch**. - ![New branch from tag](media/git-tags/branch-from-tag.png) + :::image type="content" source="media/git-tags/branch-from-tag.png" alt-text="Screenshot of create branch from tag selection in the web portal." ::: 2. Specify a **Name**, optionally select any **Work items to link**, and choose **Create branch**. - ![Choose Create branch.](media/git-tags/branch-from-tag-create.png) - -3. The branch is created and you are taken to the new branch in the web portal. + :::image type="content" source="media/git-tags/branch-from-tag-create.png" alt-text="Screenshot of create branch from tag dialog in the web portal." ::: - ![Branch created.](media/git-tags/branch-from-tag-created.png) +3. The branch is created and you're taken to the new branch in the web portal. -::: moniker-end + :::image type="content" source="media/git-tags/branch-from-tag-created.png" alt-text="Screenshot of branch created from tag in the web portal." ::: #### [Visual Studio](#tab/visual-studio) @@ -333,19 +230,19 @@ The steps in this procedure show you how to create a branch from a tag using Vis 1. To create a branch from a tag, right-click the tag and choose **New Local Branch From**. You can also choose **Create Branch From Tag**. - ![New branch from tag, Visual Studio.](media/git-tags/branch-from-tag-vs.png) + :::image type="content" source="media/git-tags/branch-from-tag-vs.png" alt-text="Screenshot of create branch from tag selection in Visual Studio." ::: -2. Specify a branch name, verify the desired tag, and choose **Create Branch**. To check out the new branch after it is created, choose **Checkout branch**. +2. Specify a branch name, verify the desired tag, and choose **Create Branch**. To check out the new branch, choose **Checkout branch**. - ![Choose Create Branch, Visual Studio.](media/git-tags/branch-from-tag-create-vs.png) + :::image type="content" source="media/git-tags/branch-from-tag-create-vs.png" alt-text="Screenshot of create branch from tag dialog in Visual Studio." ::: 3. To view your newly created branch, select **Branches** from the **Home** view. - ![View newly created branch.](media/git-tags/navigate-branches-pane.png) + :::image type="content" source="media/git-tags/navigate-branches-pane.png" alt-text="Screenshot of new branch pane in Visual Studio." ::: -4. Note that your new branch is created locally. To push the branch, right-click it and choose **Push Branch**. +4. Your new branch is created locally. To push the branch, right-click it and choose **Push Branch**. - ![Push new branch from tag in Visual Studio.](media/git-tags/branch-from-tag-created.vs.png) + :::image type="content" source="media\git-tags\branch-from-tag-created.vs.png" alt-text="Screenshot of push branch in Visual Studio." ::: --- @@ -353,29 +250,15 @@ The steps in this procedure show you how to create a branch from a tag using Vis #### [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" - -1. To view the history for a tag, select the ellipsis to the right of the tag name and choose **View history**. - - ![View tag history](media/git-tags/view-history.png) - -2. You are taken to the commits view for the tag. - - ![Tag history](media/git-tags/commits-new-nav.png) - -::: moniker-end - -::: moniker range="tfs-2018" 1. To view the history for a tag, select the ellipsis to the right of the tag name and choose **View history**. - ![View tag history](media/git-tags/view-history.png) + :::image type="content" source="media/git-tags/view-history.png" alt-text="Screenshot of view tag history in the web portal." ::: -2. You are taken to the commits view for the tag. +2. You're taken to the commits view for the tag. - ![Tag history](media/git-tags/commits.png) + :::image type="content" source="media/git-tags/commits.png" alt-text="Screenshot of tag history in the web portal." ::: -::: moniker-end #### [Visual Studio](#tab/visual-studio) @@ -385,10 +268,10 @@ The steps in this procedure show you how to view tag history using Visual Studio 1. To view the history for a tag, right-click the tag and choose **View History**. - ![View tag history in Visual Studio.](media/git-tags/view-history-vs.png) + :::image type="content" source="media/git-tags/view-history-vs.png" alt-text="Screenshot of view tag history selection in Visual Studio." ::: 2. The history is displayed in the **History** view. - ![Tag history in Visual Studio.](media/git-tags/commits-vs.png) + :::image type="content" source="media/git-tags/commits-vs.png" alt-text="Screenshot of tag history in Visual Studio." ::: --- diff --git a/docs/repos/git/gitquickstart.md b/docs/repos/git/gitquickstart.md index 9900e28f5a3..7adf20eef69 100644 --- a/docs/repos/git/gitquickstart.md +++ b/docs/repos/git/gitquickstart.md @@ -30,7 +30,7 @@ For an overview of the Git workflow, see [Azure Repos Git tutorial](gitworkflow. [!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] -To learn more about permissions and access, see [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) and [About access levels](../../organizations/security/access-levels.md). +For more information about permissions and access, see [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) and [About access levels](../../organizations/security/access-levels.md).       diff --git a/docs/repos/git/gitworkflow.md b/docs/repos/git/gitworkflow.md index 72a7e008818..d61115ced44 100644 --- a/docs/repos/git/gitworkflow.md +++ b/docs/repos/git/gitworkflow.md @@ -1,52 +1,45 @@ --- -title: Azure Repos Git tutorial +title: Version control titleSuffix: Azure Repos -description: Learn Git with the Azure DevOps Services/TFS Git tutorial. +description: Learn about version control in Git with Azure DevOps. ms.assetid: 0270b0fa-461b-4079-9703-cdcf53bdf39f ms.service: azure-devops-repos -ms.topic: tutorial -ms.date: 09/28/2021 +ms.topic: conceptual +ms.date: 02/14/2025 +ai-usage: ai-assisted monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- -# Azure Repos Git tutorial +# Git workflow [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Use version control to save your work and coordinate code changes across your team. Even if you're just a single developer, version control helps you stay organized as you fix bugs and develop new features. Version control keeps a history of your development so that you can review and even roll back to any version of your code with ease. +Use version control to save your work and coordinate code changes across your team. Even if you're a single developer, version control helps you stay organized as you fix bugs and develop new features. It maintains a history of your development, allowing you to review and roll back to any version of your code with ease. -The steps in the following tutorials show how to perform common version controls tasks using the following version control workflow. +The following tutorials demonstrate how to perform common version control tasks using the [version control workflow](#version-control-workflow). ## Version control workflow -Version control has a general workflow that most developers use when writing code and sharing it with the team. +Version control follows a general workflow, similar to the following example, that most developers use when writing code and sharing it with the team. -These steps are: - ---- -1. Get a local copy of code if they don't have one yet. -2. Make changes to code to fix bugs or add new features. +1. Get a local copy of the code if you don't have one. +2. Make changes to the code to fix bugs or add new features. 3. Once the code is ready, make it available for review by your team. -4. Once the code is reviewed, merge it into the team's shared codebase. +4. After the code is reviewed, merge it into the team's shared codebase. ---- +> [!div class="mx-imgBorder"] +> ![Screenshot shows the Git feature branch workflow.](media/gitworkflow.png) -![The Git feature branch workflow](media/gitworkflow.png) +Git has a version of this workflow using terminology and commands unique to Git. Some terms in our documentation might sound familiar if you've used a version control system like Team Foundation Version Control or Subversion, but they behave differently in Git. -Git has a version of this workflow using terminology and commands unique to Git. Throughout this tutorial you'll learn about repositories, branches, commits, and pull requests. -These terms might sound familiar if you've used a version control system like Team Foundation Version Control or Subversion, but they behave differently in Git. - -## Git workflow +## Git workflow ---- -1. [Create a branch](./create-branch.md) for the changes you plan to make and give it a name, such as `users/jamal/fix-bug-3214` or `cool-feature-x`. For more branching guidance, see [Adopt a Git branching strategy](git-branching-guidance.md) +1. [Create a branch](./create-branch.md) for the changes you plan to make and give it a name, such as `users/jamal/fix-bug-3214` or `cool-feature-x`. For more branching guidance, see [Adopt a Git branching strategy](git-branching-guidance.md). 2. [Commit changes](commits.md) to your branch. People often have multiple commits for a bug fix or feature. -3. [Push your branch](pushing.md) to the remote repository. +3. [Push your branch](pushing.md) to the remote repository. 4. [Create a pull request](pull-requests.md#create-a-pull-request) so other people can review your changes. To incorporate feedback, you might need to make more commits and push more changes. -5. [Complete your pull request](complete-pull-requests.md) and resolve any merge conflicts from changes other people made after you created your branch. - ---- +5. [Complete your pull request](complete-pull-requests.md), resolve any [merge conflicts](merging.md#resolve-merge-conflicts-1), and complete your pull request. Use this workflow if you're new to Git. As your team gets more experienced and confident with Git, extend it to suit your team's needs. @@ -56,4 +49,4 @@ Use this workflow if you're new to Git. As your team gets more experienced and c > [Create a new Git repository](creatingrepo.md) > [!div class="nextstepaction"] -> [Clone an existing Git repository](clone.md) \ No newline at end of file +> [Clone an existing Git repository](clone.md) diff --git a/docs/repos/git/go-get.md b/docs/repos/git/go-get.md deleted file mode 100644 index 83f24abe0fa..00000000000 --- a/docs/repos/git/go-get.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Go get support -titleSuffix: Azure Repos -description: Learn how to use Go get command with Azure Repos Git -ms.service: azure-devops-repos -ms.topic: conceptual -ms.date: 10/15/2021 -monikerRange: '>= azure-devops-2019' -ms.subservice: azure-devops-repos-git ---- - -# Go get command support in Azure Repos Git - -[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] - -Go is an open-source programming language, also referred to as Golang. -In Go, you can use the `get` command to download and install packages and dependencies. -Azure Repos Git provides support for `go get` within an Azure Repos Git repository. -With `go get`, you will be able to download packages with their dependencies named by the import paths. -You can also use the `import` key word inside a go file to specify the import path, using the -same syntax described in the following sections. - -> [!NOTE] -> The feature documented in this article requires Azure DevOps Server 2019 Update 1 or later version. - -## Go get with public projects - -If your Azure Repos Git repo is in a [public project](../../organizations/projects/about-projects.md) -you can use `go get` using the web repo url in the following format, -and Azure Repos returns the appropriate meta tags so that `go get` knows -the type and location of the repo to retrieve it. - -``` -go get dev.azure.com///_git/ -``` - -You can also import/get a Go package in a subfolder of a repo by appending -the subfolder names, as shown in the following examples. - -``` -go get dev.azure.com////subfolder1 - -go get dev.azure.com////subfolder1/subfolder2 -``` - -## Go get with private projects - -If your Azure DevOps Git repo is private, you can either use SSH or authenticate with a Personal Access Token (PAT) for HTTPS. - -> [!IMPORTANT] -> To access private Azure Repos Git repositories using go get, you must first set the environment variable `GOPRIVATE=dev.azure.com`. You can set this environment variable locally before building or running. - -### SSH - -To use SSH with `go get`, you must have SSH keys set up for Azure DevOps as described in [Use SSH Key authentication](use-ssh-keys-to-authenticate.md). - -When you have SSH keys set up, add this entry to your .gitconfig file: - -``` -[url "git@ssh.dev.azure.com:v3//"] - insteadOf = https://dev.azure.com// -``` - -With this entry and a specific URL format, you can now use `go get`. - -> [!NOTE] -> The `.git` that follows the repo name and `_git` are not included because you're using the SSH URL. - -``` -go get dev.azure.com///.git -``` - -### HTTPS - -To use HTTPS with `go get`, you must create a PAT as described in [Authenticate access with personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). This PAT requires only the **Code (read)** [scope](../../integrate/get-started/authentication/oauth.md#scopes). - -After you create the PAT, add this entry to your .gitconfig file: - -``` -[url "https://:@dev.azure.com///"] - insteadOf = https://dev.azure.com/// -``` - -The `` part can be any non-empty string; we suggest the word `pat`. - -With this entry and a specific URL format, you can now use `go get`. - -> [!NOTE] -> Be sure to use `.git` after the repo name. - -``` -go get dev.azure.com///.git -``` - -You can also import/get a Go package in a subfolder of a repo by appending the subfolder -names, as shown in the following examples. - -``` -go get dev.azure.com///.git/subfolder1 - -go get dev.azure.com///.git/subfolder1/subfolder2 -``` - diff --git a/docs/repos/git/go-install.md b/docs/repos/git/go-install.md new file mode 100644 index 00000000000..3bdec76113e --- /dev/null +++ b/docs/repos/git/go-install.md @@ -0,0 +1,100 @@ +--- +title: Go install support +titleSuffix: Azure Repos +description: Learn how to use Go install command with Azure Repos Git +ms.service: azure-devops-repos +ms.topic: conceptual +ms.date: 02/26/2025 +monikerRange: '>= azure-devops-2020' +ms.subservice: azure-devops-repos-git +--- + +# Go install command support in Azure Repos Git + +[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] + +Go is an open-source programming language, also referred to as Golang. +In Go, you can use the `install` command to download and install packages and dependencies. +Azure Repos Git provides support for `go install` within an Azure Repos Git repository. +With `go install`, you're able to download packages with their dependencies named by the import paths. +You can also use the `import` key word inside a go file to specify the import path, using the +same syntax described in the following sections. + +> [!NOTE] +> The feature documented in this article requires Azure DevOps Server 2019 Update 1 or later version. + +## Go install with public projects + +If your Azure Repos Git repo is in a [public project](../../organizations/projects/about-projects.md), you can use `go install` using the web repo url in the following format. For version, you can use `latest` or a specific version. + +``` +go install dev.azure.com///_git/.git@ +``` + +You can also install a Go package in a subfolder of a repo by appending +the subfolder names, as shown in the following examples. + +``` +go install dev.azure.com///_git/.git/subfolder1@ + +go install dev.azure.com///_git/.git/subfolder1/subfolder2@ +``` + +## Go install with private projects + +If your Azure DevOps Git repo is private, you can either use SSH or authenticate with a Personal Access Token (PAT) for HTTPS. + +> [!IMPORTANT] +> To access private Azure Repos Git repositories using go install, you must first set the environment variable `GOPRIVATE=dev.azure.com`. You can set this environment variable locally before building or running. + +### SSH + +To use SSH with `go install`, have SSH keys set up for Azure DevOps as described in [Use SSH Key authentication](use-ssh-keys-to-authenticate.md). + +When you have SSH keys set up, add this entry to your.gitconfig file: + +``` +[url "git@ssh.dev.azure.com:v3///"] + insteadOf = https://dev.azure.com/// +``` + +With this entry and a specific URL format, you can now use `go install`. + +> [!NOTE] +> Be sure to use `.git` after the repo name. +> Also, `_git` isn't included in the package URL that you're passing to `go install` because you're using the SSH URL. + +``` +go install dev.azure.com///.git +``` + +### HTTPS + +To use HTTPS with `go install`, you must create a PAT as described in [Authenticate access with personal access tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). This PAT requires only the **Code (read)** [scope](../../integrate/get-started/authentication/oauth.md#scopes). + +After you create the PAT, add this entry to your.gitconfig file: + +``` +[url "https://:@dev.azure.com///_git/"] + insteadOf = https://dev.azure.com///_git/ +``` + +The `` part can be any nonempty string; we suggest the word `pat`. + +With this entry and a specific URL format, you can now use `go install`. + +> [!NOTE] +> Be sure to use `.git` after the repo name. + +``` +go install dev.azure.com///_git/.git@ +``` + +You can also install a Go package in a subfolder of a repo by appending the subfolder +names, as shown in the following examples. + +``` +go install dev.azure.com///_git/.git/subfolder1@ + +go install dev.azure.com///_git/.git/subfolder1/subfolder2@ +``` diff --git a/docs/repos/git/howto.yml b/docs/repos/git/howto.yml index 4335a786acc..3b338426f73 100644 --- a/docs/repos/git/howto.yml +++ b/docs/repos/git/howto.yml @@ -6,39 +6,36 @@ metadata: ms.assetid: b1262306-214c-4422-8eda-d03d05825241 ms.service: azure-devops-repos ms.topic: faq - ms.date: 09/28/2021 + ms.date: 08/22/2024 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git -title: Frequently Asked Git Questions +title: Git FAQs summary: | [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + In this article, find answers to frequently asked questions about Git, specifically tailored for Azure Repos. Whether you're looking to manage remote branches, identify your current branch, or handle other less-common Git tasks, this guide provides helpful tips and solutions. Dive into the following sections to enhance your Git workflow and resolve common issues. sections: - name: Ignored questions: - question: | - How can I easily get a remote branch downloaded to my local repository? + How can I easily download a remote branch to my local repository? answer: | - First, make sure you have an `origin` repository configured. You should have such a repository if you cloned [`git clone`](clone.md)) your repo. When you check out a branch that doesn't exist locally, Git determines if there's a remote branch with the same name. If there is, Git creates a local branch with a reference to the remote branch of that name. Use `git pull` to download the commits and have Git catch up on the branch history locally. - + First, ensure you have an `origin` repository configured. You should have this if you cloned your repo using [`git clone`](clone.md). When you check out a branch that doesn't exist locally, Git checks if there's a remote branch with the same name. If there is, Git creates a local branch that references the remote branch. Use `git pull` to download the commits and update the branch history locally. + - question: | How can I find out which branch I'm working in? answer: | - `git branch` with no arguments shows the local branches and highlights the ones you've checked out. In Visual Studio, the status bar also displays the current branch when you're working with a project stored in a local Git repository. - + Run `git branch` with no arguments to show the local branches and highlight the one you've checked out. In Visual Studio, the status bar also displays the current branch when you're working with a project stored in a local Git repository. + - question: | When should I make Git commits? answer: | - Accepted practice is to make separate commits for logically separate changes. Think of commits as entries in a logbook. Whenever you make a change that's worth noting, record it in a commit. - A popular option is to allow everyone to commit locally as much as they want, but before they push the local commits, they squash them first through [rebasing](rebase.md). This option provides users with flexibility to make frequent commits, while keeping the commit history streamlined. - + It's best practice to make separate commits for logically distinct changes. Think of commits as entries in a logbook. Whenever you make a change worth noting, record it in a commit. A popular approach is to allow frequent local commits, but squash them through [rebasing](rebase.md) before pushing. This provides flexibility while keeping the commit history streamlined. + - question: | If every branch retains its full commit history, doesn't that make the commit history of *main* hard to follow over time? answer: | - Large projects with many commits and a range of contributors can result in commit histories for the `main` branch that represents - the development history of the topic branches merged into `main` more than the development history of the overall project. - Git provides a facility for condensing commits on branches through [squashing commits and rebasing](rebase.md). When you squash commits, the commit history on a branch becomes less verbose, which makes for a simpler commit history on the main branch once merged. - + Large projects with many commits and contributors can result in a `main` branch history that reflects the development of topic branches more than the overall project. Git allows you to condense commits on branches through [squashing commits and rebasing](rebase.md). Squashing commits makes the branch history less verbose, simplifying the commit history on the main branch once merged. - question: | How can I find out who made a specific change to a file? answer: | @@ -46,50 +43,54 @@ sections: > [!div class="tabbedCodeSnippets"] ```Git CLI - > git blame foo.js -L 20,+40 # show the blame output for the next 40 lines starting at line 20 + > git blame Example_repo -L 20,+40 # show the blame output for the next 40 lines starting at line 20 - 215d1108 (Francis Totten 2015-11-21 09:54:23 -0800 20) line 20 of the code - 215d1108 (Francis Totten 2015-11-21 09:54:23 -0800 21) line 21 of the code - 215d1108 (Francis Totten 2015-11-21 09:54:23 -0800 22) line 22 of the code + 215d1108 (Example User 2015-11-21 09:54:23 -0800 20) line 20 of the code + 215d1108 (Example User 2015-11-21 09:54:23 -0800 21) line 21 of the code + 215d1108 (Example User 2015-11-21 09:54:23 -0800 22) line 22 of the code ``` `Blame` searches the commit history for you. You can also review a file's history in the web portal to determine - who made a change and when. Open Code Explorer for your repository and branch, then select the file of interest. Azure Repos will show a complete + who made a change and when. Open Code Explorer for your repository and branch, then select the file of interest. Azure Repos shows a complete commit history for that file on the current branch. - question: | - I've made changes to some files and now I can't check out to a different branch or rebase my work. + I made changes to some files and now I can't check out to a different branch or rebase my work. answer: | - Checking out to a different branch in Git will affect the state of files on your file system. Git uses the commit history to make sure you're working with the files that represent the state of your branch. If you try to change branches while you have uncommitted changes, those changes would be overwritten during checkout. Because Git doesn't want you to accidentally lose your changes, it prevents the checkout from happening. You have two options: + Checking out to a different branch in Git affects the state of files on your file system. Git uses the commit history to make sure you're working with the files that represent the state of your branch. If you try to change branches while you have uncommitted changes, those changes would be overwritten during checkout. Because Git doesn't want you to accidentally lose your changes, it prevents the checkout from happening. You have two options: - Abandon the changes and return to the most recent commit. See [undoing changes in Git](undo.md) for instructions on how to roll back to the most recent commit. - Commit the changes. See [saving your work in Git with commits](commits.md). - - [Stashing](howto.yml#faq) your current work, saving the changes for later and cleaning up the workspace to the last commit. + - [Stashing](howto.yml#i-did-some-work-but-need-to-switch-to-something-else--how-can-i-save-my-work-for-later-without-committing-the-changes-) your current work, saving the changes for later and cleaning up the workspace to the last commit. - - question: | - I've done some work but need to switch to something else. How can I save my work for later without committing the changes? + - question: | + Pull request is unable to merge with this message: 'Unable to merge automatically: One of internal git objects (blob, tree, commit or tag) is too large which caused TF401022 exception. You can try to use LFS, split your merge or big commit into several small.' answer: | - Sometimes you want to keep the changes, but not commit them because they aren't at a point where you're comfortable doing so. Use Git `stash`. Stash takes the current staged and unstaged changes in your branch and saves the work, then returns your branch back to the state of the last commit. You can change to the other branch, do your work, then when you return to this branch run `stash apply` to restore your changes. - - - > [!div class="tabbedCodeSnippets"] + This issue is related to merge conflicts in large binary files. The current limit for files is 100MB. The workaround is to resolve merge conflicts locally by merging the target into the source locally, resolving conflicts, and pushing the changes. + + Git LFS (Large File Storage) is recommended for storing large binary files, not only to avoid conflicts but also to manage overall repository size, which affects clone and push times. + + - question: | + I did some work but need to switch to something else. How can I save my work for later without committing the changes? + answer: | + If you want to save your changes without committing them, use Git `stash`. Stash saves the current staged and unstaged changes in your branch and reverts your branch to the state of the last commit. You can then switch to another branch, do your work, and later run `stash apply` to restore your changes. + ```Git CLI - > git stash + git stash Saved working directory and index state WIP on feature1: be26067 updated endpoint docs HEAD is now at be26067 ``` - - When you run `git stash apply`, the most recently stashed changes will be applied to your current branch. If there's a conflict applying the stashed changes, `stash` will restore the changes for the files that don't conflict and create conflict markers in the files that do conflict for you to resolve. You should [merge](merging.md) the changes manually in this case. - - Once you're done with the stash, delete it with `git stash drop` This command removes the last set of stashed changes. - - You can have multiple stashes, but doing so requires more manual manipulation as you have to explicitly apply and drop stashes. Learn more from [Git Stash documentation](https://git-scm.com/book/en/v1/Git-Tools-Stashing). - + + When you run [`git stash apply`], the most recently stashed changes get applied to your current branch. If there's a conflict, [`stash`] restores the changes for the files that don't conflict and creates conflict markers in the files that do. You should merge the changes manually in this case. + + Once you're done with the stash, delete it with [`git stash drop`]. This command removes the last set of stashed changes. + + You can have multiple stashes, but managing them requires more manual manipulation as you have to explicitly apply and drop stashes. Learn more from the [Git Stash documentation](https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning). - question: | How can I change the default editor for Git command-line tools? answer: | - By default, command-line Git will use a command-line editor when asking for commit messages, performing rebases, and other work that requires additional information to + By default, command-line Git uses a command-line editor when asking for commit messages, performing rebases, and other work that requires additional information to complete. The default editor is configured using `git config`: > [!div class="tabbedCodeSnippets"] @@ -121,11 +122,11 @@ sections: > [!div class="tabbedCodeSnippets"] ```Git CLI - > git config --global user.email "frank@fabrikam.com" - > git config --global user.name "Francis Totten" + > git config --global user.email "example-user@example-site.com" + > git config --global user.name "Example User" ``` - The `--global` option will set the email and name included in commits for all Git repositories on this system. If you want to change the settings for a single + The `--global` option sets the email and name included in commits for all Git repositories on this system. If you want to change the settings for a single repository, you must change to the directory where the Git repository is located and run the above commands without the `--global` flag. You can also change the name and email settings from Visual Studio. From the **Git** menu, select **Settings** In the **Options** dialog, select **Git Global Settings** or **Git Repository Settings** > **General**. diff --git a/docs/repos/git/ignore-files.md b/docs/repos/git/ignore-files.md index 69ee3ac3070..2559926899a 100644 --- a/docs/repos/git/ignore-files.md +++ b/docs/repos/git/ignore-files.md @@ -1,11 +1,11 @@ --- title: Ignore files in your Git repo titleSuffix: Azure Repos -description: Learn how to exclude files from Git version control by using gitignore and exclude files, the git update-index command, and repo management. +description: Learn how to exclude files from Git version control by using files, commands, and repo management. ms.assetid: 60982d10-67f1-416f-94ec-eba8d655f601 ms.service: azure-devops-repos ms.topic: how-to -ms.date: 10/19/2022 +ms.date: 02/14/2025 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- @@ -15,61 +15,66 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-eq-2019](../../includes/version-vs-gt-eq-2019.md)] -Not every file in your project should be tracked by Git. Temporary files from your development environment, test outputs, and logs, are all examples of files that probably don't need to be tracked. You can use different mechanisms to let Git know which files in your project shouldn't be tracked, and to ensure Git won't report changes to those files. For files that aren't tracked by Git, you can use a `.gitignore` or `exclude` file. For files that are tracked by Git, you can tell Git to stop tracking them and to ignore changes. +Not every file in your project needs tracking by Git. Examples of files that typically don't need tracking include temporary files from your development environment, test outputs, and logs. -In this article you learn how to: +You can use several mechanisms to inform Git which files in your project shouldn't be tracked and to ensure that Git doesn't report changes to those files. For files that Git doesn't track, you can use a `.gitignore` or `exclude` file. For files that Git already tracks, you can instruct Git to stop tracking them and ignore any changes. -> [!div class="checklist"] -> * Ignore changes to untracked files by using a `.gitignore` file -> * Ignore changes to untracked files by using an `exclude` file -> * Stop tracking a file and ignore changes using `git update-index` -> * Stop tracking a file and ignore changes using `git rm` +## Prerequisites +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] -## Use a gitignore file +## Use a .gitignore file -You can tell Git not to track certain files in your project by adding and configuring a [`.gitignore`](https://git-scm.com/docs/gitignore) file. Entries in a `.gitignore` file only apply to untracked files, and won't prevent Git from reporting changes to tracked files. Tracked files are files that were committed and exist in the last Git snapshot. +You can tell Git not to track certain files in your project by adding and configuring a [.gitignore](https://git-scm.com/docs/gitignore) file. Review the following key points: -Each line in a `.gitignore` file specifies a file search pattern relative to the `.gitignore` file path. The [`.gitignore` syntax](https://git-scm.com/docs/gitignore) is flexible and supports the use of wildcards to specify individual or multiple files by name, extension, and path. Git matches `.gitignore` search patterns to the files in your project to determine which files to ignore. - -Typically, you'll just add a `.gitignore` file to the root folder of your project. However, you can add a `.gitignore` file to any project folder to let Git know which files to ignore within that folder and its subfolders at any nested depth. For multiple `.gitignore` files, the file search patterns specified by a `.gitignore` file within a folder take precedence over the patterns specified by a `.gitignore` file within a parent folder. - -You can manually create a `.gitignore` file and add file pattern entries to it, or save time by downloading a `.gitignore` template for your development environment from the GitHub [`gitignore`](https://github.com/github/gitignore) repo. One of the benefits of using a `.gitignore` file is that you can [commit](commits.md) changes and share it with others. +- **Untracked files**: Entries in a `.gitignore` file apply only to untracked files. They don't prevent Git from reporting changes to tracked files. Tracked files are files that were committed and exist in the last Git snapshot. +- **File search patterns**: Each line in a `.gitignore` file specifies a file search pattern relative to the `.gitignore` file path. The [.gitignore syntax](https://git-scm.com/docs/gitignore) is flexible and supports the use of wildcards to specify individual or multiple files by name, extension, and path. Git matches `.gitignore` search patterns to the files in your project to determine which files to ignore. +- **Location**: Typically, you add a `.gitignore` file to the root folder of your project. However, you can add a `.gitignore` file to any project folder to let Git know which files to ignore within that folder and its subfolders at any nested depth. For multiple `.gitignore` files, the file search patterns that a `.gitignore` file specifies within a folder take precedence over the patterns that a `.gitignore` file specifies within a parent folder. +- **Creation**: You can manually create a `.gitignore` file and add file pattern entries to it. Or you can save time by downloading a `.gitignore` template for your development environment from the GitHub [gitignore repo](https://github.com/github/gitignore). +- **Benefits**: One of the benefits of using a `.gitignore` file is that you can [commit](commits.md) changes and share it with others. > [!NOTE] -> Visual Studio automatically creates a `.gitignore` file for the Visual Studio development environment when you [create a new Git repo](creatingrepo.md#create-a-local-git-repo-from-an-existing-solution). +> Visual Studio automatically creates a `.gitignore` file for the Visual Studio development environment when you [create a Git repo](creatingrepo.md#create-a-local-git-repo-from-an-existing-solution). #### [Visual Studio 2022](#tab/visual-studio-2022) -Visual Studio 2022 provides a Git version control experience by using the **Git** menu, **Git Changes**, and through context menus in **Solution Explorer**. Visual Studio 2019 version 16.8 also offers the **Team Explorer** Git user interface. For more information, see the **Visual Studio 2019 - Team Explorer** tab. +Visual Studio 2022 provides a Git version control experience through the **Git** menu, **Git Changes**, and shortcut menus in **Solution Explorer**. Visual Studio 2019 version 16.8 also offers the **Team Explorer** Git user interface. For more information, see the **Visual Studio 2019 - Team Explorer** tab. [!INCLUDE [Use a gitignore file](includes/ignore-files-gitignore.md)] -#### [Visual Studio 2019 - Git menu](#tab/visual-studio-2019-git-menu) +#### [Visual Studio 2019: Git menu](#tab/visual-studio-2019-git-menu) -Visual Studio 2019 provides a Git version control experience by using the **Git** menu, **Git Changes**, and through context menus in **Solution Explorer**. +Visual Studio 2019 provides a Git version control experience through the **Git** menu, **Git Changes**, and shortcut menus in **Solution Explorer**. [!INCLUDE [Use a gitignore file](includes/ignore-files-gitignore.md)] -#### [Visual Studio 2019 - Team Explorer](#tab/visual-studio-2019-team-explorer) +#### [Visual Studio 2019: Team Explorer](#tab/visual-studio-2019-team-explorer) + +Visual Studio 2019 version 16.8 and later versions provide a Git version control experience while maintaining the **Team Explorer** Git user interface. Follow these steps to use **Team Explorer**: + +1. Go to the menu bar and select **Tools** > **Options** > **Preview Features**. +2. Clear the **New Git user experience** checkbox to enable **Team Explorer**. + +You can use Git features from either interface interchangeably. + +To ignore files using **Team Explorer**: -Visual Studio 2019 version 16.8 and later versions provides a Git version control experience while maintaining the **Team Explorer** Git user interface. To use **Team Explorer**, uncheck **Tools** > **Options** > **Preview Features** > **New Git user experience** from the menu bar. You can use Git features from either interface interchangeably. +1. In the **Changes** view of **Team Explorer**, right-click any changed file that you want Git to ignore. +2. Select **Ignore this local item** or **Ignore this extension**. These menu options don't exist for tracked files. -In the **Changes** view of **Team Explorer**, right-click any changed file that you want Git to ignore and choose **Ignore this local item** or **Ignore this extension**. Those menu options don't exist for tracked files. - -:::image type="content" source="media/ignore-files/visual-studio-2019/team-explorer/git-ignore.png" border="true" alt-text="Screenshot of the context menu options for changed files in Team Explorer in Visual Studio 2019." lightbox="media/ignore-files/visual-studio-2019/team-explorer/git-ignore-lrg.png"::: +:::image type="content" source="media/ignore-files/visual-studio-2019/team-explorer/git-ignore.png" border="true" alt-text="Screenshot of the shortcut menu options for changed files in Team Explorer in Visual Studio 2019." lightbox="media/ignore-files/visual-studio-2019/team-explorer/git-ignore-lrg.png"::: --- -The **Ignore this local item** option adds a new entry to the `.gitignore` file, and removes the selected file from the list of changed files. +- The **Ignore this local item** option adds a new entry to the `.gitignore` file and removes the selected file from the list of changed files. +- The **Ignore this extension** option adds a new entry to the `.gitignore` file and removes all files with the same extension as the selected file from the list of changed files. -The **Ignore this extension** option adds a new entry to the `.gitignore` file, and removes all files with the same extension as the selected file from the list of changed files. +Either option creates a `.gitignore` file if it doesn't already exist in the root folder of your repo and adds an entry to it. -Either option creates a `.gitignore` file if it doesn't already exist in the root folder of your repo, and adds an entry to it. ### Edit a gitignore file -Each entry in the `.gitignore` file is either: a file search pattern that specifies which files to ignore, a comment that begins with `#`, or a blank line (for readability). The [`.gitignore` syntax](https://git-scm.com/docs/gitignore) is flexible and supports the use of wildcards to specify individual or multiple files by name, extension, and path. All file search pattern paths are relative to the `.gitignore` file. +Each entry in the `.gitignore` file is either: a file search pattern that specifies which files to ignore, a comment that begins with a number sign (`#`), or a blank line (for readability). The [`.gitignore` syntax](https://git-scm.com/docs/gitignore) is flexible and supports the use of wildcards to specify individual or multiple files by name, extension, and path. All paths for file search patterns are relative to the `.gitignore` file. Here are some examples of common file search patterns: @@ -82,7 +87,7 @@ config.json # Scope is all repo folders. *.json -# Add an exception so as to not ignore a file with the specified name. +# Add an exception to prevent ignoring a file with the specified name. # Scope is all repo folders. !package.json @@ -101,10 +106,9 @@ config.json As soon as you modify a `.gitignore` file, Git updates the list of files that it ignores. > [!NOTE] -> Windows users must use a forward slash path separator in a `.gitignore` file instead of a backslash. All users must add a trailing `/` when specifying a folder. +> Windows users must use a slash (`/`) as a path separator in a `.gitignore` file, instead of using a backslash (`\`). All users must add a trailing slash when specifying a folder. - -### Use a global gitignore file +### Use a global .gitignore file You can designate a `.gitignore` file as a global ignore file that applies to all local Git repos. To do so, use the `git config` command as follows: @@ -112,21 +116,19 @@ You can designate a `.gitignore` file as a global ignore file that applies to al git config core.excludesfile ``` -A global `.gitignore` file helps ensure that Git doesn't commits certain file types, such as compiled binaries, in any local repo. File search patterns in a repo-specific `.gitignore` file have precedence over patterns in a global `.gitignore` file. - +A global `.gitignore` file helps ensure that Git doesn't commit certain file types, such as compiled binaries, in any local repo. File search patterns in a repo-specific `.gitignore` file have precedence over patterns in a global `.gitignore` file. ## Use an exclude file -You can also add file search pattern entries to the `exclude` file in the `.git/info/` folder of your local repo. The `exclude` file lets Git know which untracked files to ignore and uses the same file search pattern syntax as a `.gitignore` file. - -Entries in an `exclude` file only apply to untracked files, and won't prevent Git from reporting changes to committed files that it already tracks. Only one `exclude` file exists per repo. +You can also add entries for file search patterns to the `exclude` file in the `.git/info/` folder of your local repo. The `exclude` file lets Git know which untracked files to ignore. It uses the same syntax for file search patterns as a `.gitignore` file. -Since Git doesn't commit or push the `exclude` file, you can safely use it to ignore files on your local system without affecting anyone else. +Entries in an `exclude` file apply only to untracked files. They don't prevent Git from reporting changes to committed files that it already tracks. Only one `exclude` file exists per repo. +Because Git doesn't commit or push the `exclude` file, you can safely use it to ignore files on your local system without affecting anyone else. -## Use Git update-index to ignore changes +## Use git update-index to ignore changes -Sometimes it's convenient to temporarily stop tracking a local repo file and have Git ignore changes to the file. For example, you might want to customize a settings file for your development environment without the risk of committing your changes. To do so, you can run the `git update-index` command with the `skip-worktree`flag: +Sometimes it's convenient to temporarily stop tracking a local repo file and have Git ignore changes to the file. For example, you might want to customize a settings file for your development environment without the risk of committing your changes. To do so, you can run the `git update-index` command with the `skip-worktree` flag: ```console git update-index --skip-worktree @@ -134,7 +136,7 @@ git update-index --skip-worktree To resume tracking, run the `git update-index` command with the `--no-skip-worktree` flag. -Or, you can temporarily stop tracking a file and have Git ignore changes to the file by using the `git update-index` command with the `assume-unchanged` flag. This option is less effective than the `skip-worktree`flag, because the `assume-unchanged` flag can be reverted by a Git `pull` operation that changes file content. +Or, you can temporarily stop tracking a file and have Git ignore changes to the file by using the `git update-index` command with the `assume-unchanged` flag. This option is less effective than the `skip-worktree` flag, because a Git `pull` operation that changes file content can revert the `assume-unchanged` flag. ```console git update-index --assume-unchanged @@ -142,10 +144,9 @@ git update-index --assume-unchanged To resume tracking, run the `git update-index` command with the `--no-assume-unchanged` flag. +## Use git rm to ignore changes -## Use Git rm to ignore changes - -Entries in a `.gitignore` or `exclude` file have no effect on files that Git already tracks. Git tracks files that you've previously committed. To permanently remove a file from the Git snapshot so that Git no longer tracks it, but without deleting it from the filesystem, run the following commands: +Entries in a `.gitignore` or `exclude` file have no effect on files that Git already tracks. Git tracks files that you previously committed. To permanently remove a file from the Git snapshot so that Git no longer tracks it, but without deleting it from the file system, run the following commands: ```console git rm --cached @@ -154,14 +155,12 @@ git commit Then, use a `.gitignore` or `exclude` file entry to prevent Git from reporting changes to the file. - ## Next steps > [!div class="nextstepaction"] > [Review history](review-history.md) - ## Related articles -- [New to Git repos? Learn more](/devops/develop/git/set-up-a-git-repository) -- [Save your work with commits](commits.md) +* [Set up a Git repository](/devops/develop/git/set-up-a-git-repository) +* [Save your work with commits](commits.md) diff --git a/docs/repos/git/import-from-TFVC.md b/docs/repos/git/import-from-TFVC.md index 2d0f28134f9..8ad28390730 100644 --- a/docs/repos/git/import-from-TFVC.md +++ b/docs/repos/git/import-from-TFVC.md @@ -1,40 +1,37 @@ --- -title: Import repositories from TFVC to Git +title: Import and migrate repositories from TFVC to Git titleSuffix: Azure Repos -description: Search your Git repo in Azure DevOps Services or TFS for a specific file or folderImport your repositories from TFVC to Git repositories within the same account. +description: Import and migrate your repositories from TFVC to Git repositories within the same account. ms.assetid: cf1a4dc8-7143-4b0e-8a43-1680533fb3cb ms.service: azure-devops-repos ms.topic: conceptual -ms.date: 10/11/2018 +ms.date: 02/14/2025 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- -# Import repositories from TFVC to Git +# Import and migrate repositories from TFVC to Git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can migrate code from an existing TFVC repository to a new Git repository within the same organization. Migrating to Git is an involved process for large TFVC repositories and teams. Centralized version control systems, like TFVC, behave differently from Git in fundamental ways. The switch involves a lot more than learning new commands. It is a disruptive change that requires careful planning. You need to think about: +You can migrate code from an existing Team Foundation Version Control (TFVC) repository to a new Git repository within the same organization. Migrating to Git is an involved process for large TFVC repositories and teams. Centralized version control systems, like TFVC, behave differently from Git in fundamental ways. The switch involves a lot more than learning new commands. It's a disruptive change that requires careful planning. You need to think about: * Revising tools and processes * Removing binaries and executables * Training your team +## Prerequisites -> [!NOTE] -> The feature documented in this article requires TFS 2017 Update 2 or later version. +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] +We strongly recommend reading [Centralized version control to Git](/devops/develop/git/centralized-to-git) and the [Migrate from TFVC to Git](#migrate-from-tfvc-to-git) section before starting the migration. -We strongly recommend reading our whitepapers - [Centralized version control to Git](/devops/develop/git/centralized-to-git) and [TFVC to Git](/devops/develop/git/migrate-from-tfvc-to-git) before starting the migration. +The import experience is ideal for small, simple TFVC repositories. It's also suitable for repositories that are already clean, as outlined in [Centralized version control to Git](/devops/develop/git/centralized-to-git) and the [Migrate from TFVC to Git](#migrate-from-tfvc-to-git) section. These sections also recommend other tools for more advanced TFVC repository configurations. -The import experience is great for small simple TFVC repositories. It's also good for repositories that have already been "cleaned up" as outlined in the previous whitepapers. Those whitepapers also recommend other tools for more advanced TFVC repository configurations. +> [!IMPORTANT] +> Due to the differences in how TFVC and Git store version control history, we recommend not migrating your history, which is the approach that Microsoft took when it migrated Windows and other products from centralized version control to Git. -> [!IMPORTANT] -> Due to the differences in how TFVC and Git store version control history, we [recommend](/devops/develop/git/migrate-from-tfvc-to-git) that you don't migrate your history. This is the approach that Microsoft took when it migrated Windows and other products from centralized version control to Git. - -## Importing the repository - -::: moniker range=">= azure-devops-2019" +## Import the repository 1. Select **Repos**, **Files**. @@ -48,44 +45,153 @@ The import experience is great for small simple TFVC repositories. It's also goo 4. Type the path to the repository / branch / folder that you want to import to the Git repository. For example, `$/Fabrikam/FabrikamWebsite` -5. If you want to migrate history from the TFVC repository, click **Migrate history** and select the number of days. You can migrate up to 180 days of history starting from the most recent changeset. - A link to the TFVC repository is added in the commit message of the 1st changeset that is migrated to Git. This makes it easy to find older history when needed. +5. If you want to migrate history from the TFVC repository, select **Migrate history** and select the number of days. You can migrate up to 180 days of history starting from the most recent changeset. + A link to the TFVC repository is added in the commit message of the first changeset that is migrated to Git, which makes it easy to find older history when needed. -6. Give a name to the new Git repository and click **Import**. Depending on the size of the import, your Git repository would be ready in a few minutes. +6. Give a name to the new Git repository and select **Import**. Depending on the size of the import, your Git repository would be ready in a few minutes. ![Import Repository Dialog](media/Import-Repo/ImportRepoDialog-TFVC.png) -::: moniker-end +### Troubleshooting -::: moniker range="tfs-2018" +This experience is optimized for small, simple TFVC repositories, or repositories that prepared for a migration. This means it has a few limitations. -1. From the repo drop-down, select **Import repository**. +1. It only migrates the contents of root or a branch. For example, if you have a TFVC project at `$/Fabrikam` which has one branch and one folder under it, a path to import `$/Fabrikam` would import the folder +while `$/Fabrikam/` would only import the branch. +1. The imported repository and associated history (if imported) can't exceed 1 GB in size. +2. You can import up to 180 days of history. -![Import Repository Option](media/Import-Repo/ImportRepository.png) +If any of the previously listed information is a blocker for your import, we recommend trying external tools like [Git-TFS](https://github.com/git-tfs/git-tfs) for importing and reading our whitepapers - [Centralized version control to Git](/devops/develop/git/centralized-to-git) and the following [Migrate from TFVC to Git](#migrate-from-tfvc-to-git) section. -1. Select TFVC from the **Source type** dropdown -2. Type the path to the repository / branch / folder that you want to import to the Git repository. For example, `$/Fabrikam/FabrikamWebsite` +> [!IMPORTANT] +> The usage of external tools like [Git-TFS](https://github.com/git-tfs/git-tfs) with Microsoft products, services, or platforms is entirely the responsibility of the user. Microsoft doesn't endorse, support, or guarantee the functionality, reliability, or security of such non-Microsoft extensions. -3. If you want to migrate history from the TFVC repository, click **Migrate history** and select the number of days. You can migrate up to 180 days of history starting from the most recent changeset. -A link to the TFVC repository is added in the commit message of the 1st changeset that is migrated to Git. This makes it easy to find older history when needed. +## Migrate from TFVC to Git -4. Give a name to the new Git repository and click **Import**. Depending on the size of the import, your Git repository would be ready in a few minutes. +Before you migrate source code from a centralized version control system to Git, understand the +differences between the two and [prepare for the migration](/devops/develop/git/centralized-to-git). -![Import Repository Dialog](media/Import-Repo/ImportRepoDialog-TFVC.png) +* [Requirements](#requirements) +* [Steps to migrate](#migrate) + * [Check out the latest version](#check-out-the-latest-version) + * [Remove binaries and build tools](#remove-binaries-and-build-tools) + * [Convert version control-specific configuration](#convert-version-control-specific-configuration) + * [Check in changes and perform the migration](#check-in-changes-and-perform-the-migration) + * [Advanced migrations](#advanced-migrations) +* [Update the workflow](#update-the-workflow) -> [!IMPORTANT] -> Due to the differences in how TFVC and Git store version control history, we [recommend](/devops/develop/git/migrate-from-tfvc-to-git) that you don't migrate your history. This is the approach that Microsoft took when it migrated Windows and other products from centralized version control to Git. +### Requirements -::: moniker-end +To make migrations easier, there are many requirements before following the [importing the repository](#import-the-repository) procedure in the previous section of this article. -### Troubleshooting +* Migrate only a single branch. When [planning the migration](/devops/develop/git/centralized-to-git), choose a new + branching strategy for Git. Migrating only the main branch supports a topic-branch based workflow like + [Gitflow](http://nvie.com/posts/a-successful-git-branching-model/) + or [GitHub Flow](https://docs.github.com/get-started/using-github/github-flow). +* Do a tip migration, as in, import only the latest version of the source code. If TFVC history is simple, + you can opt to migrate some history, up to 180 days, so that the team can work only out of Git. + For more information, see [Plan your migration to Git](/devops/develop/git/centralized-to-git). +* Exclude binary assets like images, scientific data sets, or game models from the repository. These assets + should use the Git LFS (Large File Storage) extension, which the import tool doesn't configure. +* Keep the imported repository below 1GB in size. -This experience is optimized for small, simple TFVC repositories or repositories that have been prepared for a migration. This means it has a few limitations. +If the repository doesn't meet these requirements, use the [Git-TFS tool](https://github.com/git-tfs/git-tfs) +to do your migration instead. -1. It only migrates the contents of root or a branch. For example, if you have a TFVC project at `$/Fabrikam` which has 1 branch and 1 folder under it, a path to import `$/Fabrikam` would import the folder -while `$/Fabrikam/` would only import the branch. -2. The imported repository and associated history (if imported) cannot exceed 1GB in size. -3. You can import up to 180 days of history. +> [!IMPORTANT] +> The usage of external tools like [Git-TFS](https://github.com/git-tfs/git-tfs) with Microsoft products, services, or platforms is entirely the responsibility of the user. Microsoft doesn't endorse, support, or guarantee the functionality, reliability, or security of such non-Microsoft extensions. + +### Migrate + +The process to migrate from TFVC is straightforward: + +1. [Check out the latest version](#check-out-the-latest-version) of the branch from TFVC on your local disk. +2. [Remove binaries and build tools](#remove-binaries-and-build-tools) from the repository and set up a package management system like NuGet. +3. [Convert version control-specific configuration](#convert-version-control-specific-configuration) directives. For example, convert `.tfignore` files to + [`.gitignore`](https://git-scm.com/docs/gitignore), and convert `.tpattributes` files to + [`.gitattributes`](https://git-scm.com/docs/gitattributes). +4. [Check in changes and perform the migration](#check-in-changes-and-perform-the-migration) to Git. + +Steps 1-3 are optional. If there aren't binaries in the repository and there's no need to set up a +`.gitignore` or a `.gitattributes`, you can proceed directly to the [Check in changes and perform the migration](#check-in-changes-and-perform-the-migration) step. + +#### Check out the latest version + +Create a new workspace and map a working folder for the server directory being migrated to Git. This action +doesn't require a full working folder mapping. Only map folders that contain binaries to be removed +from the repository and folders that contain version control system-specific configuration files like +`.tfignore`. + +Once mappings are set up, get the folder locally: + +```prettyprint +tf get /version:T /recursive +``` + +#### Remove binaries and build tools + +Because Git stores the history of changed files by providing a copy of every file in history to every developer, checking in binary files directly to the repository can cause the repository to grow quickly and lead to performance issues. + +For build tools and dependencies like libraries, adopt a [packaging solution](../../artifacts/start-using-azure-artifacts.md) +with versioning support, such as NuGet. Many open source tools and libraries are already available on the +[NuGet Gallery](https://www.nuget.org/), but for proprietary dependencies, create new NuGet packages. + +Once dependencies get moved into NuGet, be sure that they aren't included in the Git repository +by adding them to [`.gitignore`](./ignore-files.md). + +#### Convert version control-specific configuration + +Team Foundation Version Control provides a `.tfignore` file, which ensures that certain files aren't +added to the TFVC repository. You can use the `.tfignore` file for automatically generated files like build +output so that they aren't accidentally checked in. + +If the project relies on this behavior, convert the `.tfignore` file to a +[`.gitignore`](./ignore-files.md) file. + +Cross-platform TFVC clients also provide support for a `.tpattributes` file that controls how files +are placed on the local disk or checked into the repository. If a `.tpattributes` file is in use, +convert it to a [`.gitattributes`](https://git-scm.com/docs/gitattributes) file. + +#### Check in changes and perform the migration + +Check in any changes that remove binaries, migrate to package management, or convert version +control-specific configuration. Once you make this final change in TFVC, you can [do the import](#import-the-repository). + +#### Advanced migrations + +The [Git-TFS tool](https://github.com/git-tfs/git-tfs) is a two-way bridge between TFVS and Git, and you can use it to perform a migration. Git-TFS is appropriate for a +migration with full history, more than the 180 days that the Import tool supports. Or you can use +Git-TFS to attempt a migration that includes multiple branches and merge relationships. + +Before you attempt a migration with Git-TFS, be aware of the following fundamental differences between the way TFVC and Git store history: + +- Git stores history as a snapshot of the repository in time, while TFVC records the discrete + operations that occurred on a file. Change types in TFVC like rename, undelete, and rollback can't + be expressed in Git. Instead of seeing that file `A` was renamed to file `B`, it only tracks + that file `A` was deleted and file `B` was added in the same commit. +- Git doesn't have a direct analog of a TFVC label. Labels can contain any number of files at any + specific version and can reflect files at different versions. Although conceptually similar, the Git tags + point to a snapshot of the whole repository at a point in time. If the project relies on TFVC labels + to know what was delivered, Git tags might not provide this information. +- Merges in TFVC occur at the file level, not at the entire repository. Only a subset of changed files + can be merged from one branch to another. Remaining changed files might then be merged in a subsequent + changeset. In Git, a merge affects the entire repository, and both sets of individual changes + can't be seen as a merge. + +Because of these differences, we recommend that you do a tip migration and keep your TFVC repository online, but read-only, in order to view history. + +To attempt an advanced migration with Git-TFS, see +[clone a single branch with history](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/manage_tfs_branches.md#clone-just-the-trunk) +or [clone all branches with merge history](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/manage_tfs_branches.md#clone-all-history). + +> [!IMPORTANT] +> The usage of external tools like [Git-TFS](https://github.com/git-tfs/git-tfs) with Microsoft products, services, or platforms is entirely the responsibility of the user. Microsoft doesn't endorse, support, or guarantee the functionality, reliability, or security of such non-Microsoft extensions. + +### Update the workflow + +Moving from a centralized version control system to Git is more than just migrating code. The team needs +training to understand how Git is different from the existing version control system and how these +differences affect day-to-day work. -If any of the above is a blocker for your import, we recommend you try external tools like [Git-TFS](https://github.com/git-tfs/git-tfs) for importing and reading our whitepapers - [Centralized version control to Git](/devops/develop/git/centralized-to-git) and [TFVC to Git](/devops/develop/git/migrate-from-tfvc-to-git) +Learn more about how to [migrate from centralized version control to Git](/devops/develop/git/centralized-to-git). diff --git a/docs/repos/git/import-git-repository.md b/docs/repos/git/import-git-repository.md index 396e078010b..1b46e2aa909 100644 --- a/docs/repos/git/import-git-repository.md +++ b/docs/repos/git/import-git-repository.md @@ -1,12 +1,12 @@ --- title: Import a Git repo into your project titleSuffix: Azure Repos -description: Import a repo from GitHub, GitLab, or Bitbucket into your Azure DevOps Services/TFS Project +description: Import a repo from GitHub, GitLab, or Bitbucket into your project in Azure DevOps. ms.assetid: 5439629e-23fd-44f1-a345-f00a435f1430 ms.service: azure-devops-repos ms.topic: quickstart monikerRange: '<= azure-devops' -ms.date: 02/23/2022 +ms.date: 02/14/2025 ms.subservice: azure-devops-repos-git --- @@ -16,47 +16,14 @@ ms.subservice: azure-devops-repos-git This article shows you how to import an existing Git repo from GitHub, Bitbucket, GitLab, or other location into a new or empty existing repo in your Azure DevOps project. -::: moniker range="tfs-2018" - ->[!IMPORTANT] ->The **Import repository** feature is currently not working if you are importing a GitHub repo using TFS 2017.1 to TFS 2018.1. For more information about this issue, see [Weak cryptographic standards removal notice](https://githubengineering.com/crypto-removal-notice/) and [Unable to connect to GitHub due to TLS 1.2 only change](https://developercommunity.visualstudio.com/content/problem/201457/unable-to-connect-to-github-due-to-tls-12-only-cha.html) - -There are several workarounds to this issue: -* You can import a GitHub repo into Azure Devops using the steps provided later in this article, [Manually import a repo using git CLI](#manual-import-git-cli). -* You can set a machine-wide .NET registry key on your Application Tier servers to enable them to use all available TLS protocol versions. After setting these registry keys, you will need to recycle the TFS application pools (or restart the servers) for the settings to be activated. Open an elevated command prompt and run the following commands to set the registry keys. - - ``` - reg add HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319 /v SystemDefaultTlsVersions /t REG_DWORD /d 1 /f /reg:64 - reg add HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319 /v SystemDefaultTlsVersions /t REG_DWORD /d 1 /f /reg:32 - ``` - -* On your Application Tier servers, you can modify the web.config file to change the targetFramework from ` [!NOTE] +> When the import of the repository is completed, Azure DevOps sets the **Default** branch for that imported repository. If the imported repository contains a branch named `main`, it gets set as the default branch, otherwise the first branch (in alphabetical order) of the imported repository gets set as **Default**. ## Import into a new repo - - -::: moniker range=">= azure-devops-2019" 1. Select **Repos**, **Files**. @@ -68,38 +35,22 @@ This issue is resolved starting with [Team Foundation Server 2018 Update 2 RC1 a 3. If the source repo is publicly available, just [enter the clone URL](clone.md#clone_url) of the source repository and a name for your new Git repository. - If the source repository is private but can be accessed using basic authentication (username-password, personal access token, etc.), select **Requires authorization** and enter your credentials. SSH authentication is not supported, but you can manually import a repository that uses SSH authentication by following the steps in [Manually import a repo using git CLI](#manual-import-git-cli). + If the source repository is private but can be accessed using basic authentication (username-password, personal access token, etc.), select **Requires authorization** and enter your credentials. SSH authentication isn't supported, but you can manually import a repository that uses SSH authentication by following the steps in [Manually import a repo using git CLI](#manual-import-git-cli). ![Import Repository Dialog](media/Import-Repo/ImportRepoDialog.png) ::: moniker-end -::: moniker range="tfs-2018" - -From the repo drop-down, select **Import repository**. - -![Import Repository Option](media/Import-Repo/ImportRepository.png) - -If the source repo is publicly available, just [enter the clone URL](clone.md#clone_url) of the source repository and a name for your new Git repository. - -If the source repository is private but can be accessed using basic authentication (username-password, personal access token, etc.), select **Requires authorization** and enter your credentials. SSH authentication is not supported, but you can manually import a repository that uses SSH authentication by following the steps in [Manually import a repo using git CLI](#manual-import-git-cli). - -![Import Repository Dialog](media/Import-Repo/ImportRepoDialog.png) - -::: moniker-end - - ## Import into an existing empty repo -On the **Files** page of the empty Git repository, select **Import** and [enter the clone URL](clone.md#clone_url). You will need to provide credentials if the source repository requires authentication. +On the **Files** page of the empty Git repository, select **Import** and [enter the clone URL](clone.md#clone_url). Provide credentials if the source repository requires authentication. ![Import Repository into an existing repository](media/Import-Repo/ImportRepofromEmptyRepo.png) > [!NOTE] > The import feature disables automated linking for work items mentioned in a commit comment since the work item IDs in the destination project might not be the same as ones in the source project. Automatic linking for work items mentioned in a commit can be re-enabled by navigating to **Settings**, **Version Control**, selecting your repository, and choosing **Options**. For more information on linking commits with work items, see [Link work items to commits](share-your-code-in-git-vs.md#link-work-items) - -::: moniker range="azure-devops" +::: moniker range=" azure-devops" ## Manually import a repo using az repos CLI @@ -126,15 +77,13 @@ az repos import create --git-source-url |---------|-----------| |`git-source-url`| Required. URL of the source git repository to import. | |`detect`| Optional. Automatically detect organization. Accepted values: `false`, `true`.| -|`git-service-endpoint-id`| Optional. Service Endpoint for connection to external endpoint. | +|`git-service-endpoint-id`| Optional. Service Endpoint for connection to external endpoint. | |`org`, `organization`| Azure DevOps organization URL. You can configure the default organization by using `az devops configure -d organization=`. **Required** if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`.| |`project`, `p`|Name or ID of the project. You can configure the default project using `az devops configure -d project=`. **Required** if not configured as default or picked up via git config. |`repository`| Name or ID of the repository to create the import request in. | -|`requires-authorization`| Flag to indicate if the source git repository is private. If you require authentication, then generate an authentication token on the source repo and set the environment variable `AZURE_DEVOPS_EXT_GIT_SOURCE_PASSWORD_OR_PAT` to the value of the token. Then the import request will include authentication. | +|`requires-authorization`| Flag to indicate if the source git repository is private. If you require authentication, then generate an authentication token on the source repo and set the environment variable `AZURE_DEVOPS_EXT_GIT_SOURCE_PASSWORD_OR_PAT` to the value of the token. Then the import request includes authentication. | |`subscription`| Name or ID of subscription. You can configure the default subscription using `az account set -s `.| |`user-name`| User name to specify when the git repository is private.| - - **Example** @@ -199,11 +148,11 @@ az repos import create --git-source-url https://github.com/fabrikamprime/fabrika ::: moniker-end - + ## Manually import a repo using git CLI -The import repo feature was introduced in TFS 2017 Update 1. If you are using TFS 2017 RTM or earlier, you can use the following steps to manually import a repo into TFS. You can also follow these steps to manually import a repo into an Azure DevOps Services repo by replacing TFS with Azure Repos in the following steps. +The import repo feature was introduced in the 2017 Update 1. You can also follow these steps to manually import a repo into an Azure DevOps Services repo by replacing "TFS" with Azure Repos in the following steps. 1. Clone the source repo to a temporary folder on your computer using the `bare` option, as shown in the following command line example, and then navigate to the repo's folder. When cloning using the `bare` option, the folder name includes the `.git` suffix. In this example, `https://github.com/contoso/old-contoso-repo.git` is the source repo to be manually imported. @@ -212,7 +161,7 @@ The import repo feature was introduced in TFS 2017 Update 1. If you are using TF cd old-contoso-repo.git ``` -2. [Create a target repo](create-new-repo.md#create-a-repo-using-the-web-portal) using TFS 2017 RTM, and make a note of the clone URL. In this example, `https://dev.azure.com/contoso-ltd/MyFirstProject/_git/new-contoso-repo` is the URL for the new target repo. +2. [Create a target repo](create-new-repo.md#create-a-repo-using-the-web-portal) and make a note of the clone URL. In this example, `https://dev.azure.com/contoso-ltd/MyFirstProject/_git/new-contoso-repo` is the URL for the new target repo. 3. Run the following command to copy the source repo to the target repo. @@ -221,9 +170,9 @@ The import repo feature was introduced in TFS 2017 Update 1. If you are using TF ``` > [!WARNING] - > Using `--mirror` will overwrite all branches in the target repo which includes deleting any branches not in the source repo. + > Using `--mirror` overwrites all branches in the target repo which includes deleting any branches not in the source repo. -4. If the source repository has LFS objects then fetch them, and copy them from the source repo to the target repo. +4. If the source repository has LFS objects, then fetch them, and copy them from the source repo to the target repo. ``` git lfs fetch origin --all @@ -235,96 +184,85 @@ The import repo feature was introduced in TFS 2017 Update 1. If you are using TF cd .. rm -rf old-contoso-repo.git ``` - -## Frequently asked questions +## Frequently asked questions (FAQs) +Although imports are most often successful, the following conditions might cause issues. -Although most of the time the import is successful, the following conditions can cause problems. +* [What if my Source repository is behind two-factor authentication?](#q-what-if-my-source-repository-is-behind-two-factor-authentication) +* [What if my source repository doesn't support multi_ack?](#multiack) +* [Can I import from previous versions of Team Foundation Server?](#q-can-i-import-from-previous-versions) +* [Can I use MSA-based credentials?](#q-can-i-use-msa-based-credentials) +* [Can I import from TFVC?](#q-can-i-import-from-tfvc) +* [What if my source repository contains Git LFS objects?](#q-what-if-my-source-repository-contains-git-lfs-objects) -* [What if my Source repository is behind two-factor authentication?](#what-if-my-source-repository-is-behind-two-factor-authentication) -* [What if my source repository does not support multi_ack?](#multiack) -* [Can I import from previous versions of Team Foundation Server?](#can-i-import-from-previous-versions-of-team-foundation-server) -* [Can I use MSA-based credentials?](#can-i-use-msa-based-credentials) -* [Can I import from TFVC?](#can-i-import-from-tfvc) -* [What if my source repository contains Git LFS objects?](#what-if-my-source-repository-contains-git-lfs-objects) +### Q: What if my source repository is behind two-factor authentication? -### What if my source repository is behind two-factor authentication? - -The import service uses REST APIs to validate and trigger import and cannot work directly with repositories that require two-factor authentication. +A: The import service uses REST APIs to validate and trigger import and can't work directly with repositories that require two-factor authentication. Most Git hosting providers like [GitHub](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) and [Azure DevOps Services](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) support personal tokens which can be supplied to the import service. - + -### What if my source repository does not support multi_ack? +### Q: What if my source repository doesn't support multi_ack? -The import service uses the [multi_ack](https://git-scm.com/book/en/v2/Git-Internals-Transfer-Protocols) capability of the Git protocol during the import. -If the source repository does not provide this capability, the import service can fail to import from the given source. +A: The import service uses the [multi_ack](https://git-scm.com/book/en/v2/Git-Internals-Transfer-Protocols) capability of the Git protocol during the import. +If the source repository doesn't provide this capability, the import service can fail to import from the given source. This failure can happen when creating import request or while import is in progress. +### Q: Can I import from previous versions? - - -### Can I import from previous versions of Team Foundation Server? - -If the source Git repository is in a TFS version earlier than TFS 2017 RTM, then import will fail. -This happens because of a contract mismatch between the latest Azure DevOps Services/TFS and pre-2017 RTM versions of TFS. +A: If the source Git repository is in a TFS version earlier than TFS 2017 RTM, then import fails. +This happens because of a contract mismatch between the latest Azure DevOps and previous versions. +### Q: Can I use MSA-based credentials? - - -### Can I use MSA-based credentials? - -Unfortunately, MSA (Microsoft Account, formerly Live ID) based credentials will not work. Import service relies on basic authentication to communicate with the source repository. If the username / password you are using are not basic auth then authentication will fail and import will fail. -One way to check if the username / password you are using are basic auth or not is to try using Git to clone your repository using the below format +A: Unfortunately, MSA (Microsoft Account, formerly Live ID) based credentials don't work. Import service relies on basic authentication to communicate with the source repository. If the username / password you're using aren't basic auth then authentication and import fail. +One way to check if the username / password you're using are basic auth or not is to try using Git to clone your repository using the following format ``` git clone https://<>:<>@<> ``` -### Can I import from TFVC? +### Q: Can I import from TFVC? -You can migrate code from an existing TFVC repository to a new Git repository within the same account. While migrating to Git has many benefits, it is an involved process for large TFVC repositories and teams. Centralized version control systems, like TFVC, behave different than Git in fundamental ways. The switch involves a lot more than learning new commands. It is a disruptive change that requires careful planning. For more information, see [Import from TFVC to Git](import-from-tfvc.md). +A: You can migrate code from an existing TFVC repository to a new Git repository within the same account. While migrating to Git has many benefits, it's an involved process for large TFVC repositories and teams. Centralized version control systems, like TFVC, behave different than Git in fundamental ways. The switch involves a lot more than learning new commands. It's a disruptive change that requires careful planning. For more information, see [Import from TFVC to Git](import-from-tfvc.md). -### What if my source repository contains Git LFS objects? +### Q: What if my source repository contains Git LFS objects? -Git import will not import Git LFS objects. +A: Git import doesn't import Git LFS objects. LFS objects can be moved using the following steps: - Import the repository using import repository feature into Azure DevOps. - This will copy over all the Git objects from source to Azure DevOps (this will also import the LFS pointers which are Git objects but not the LFS files) + This action copies over all the Git objects from source to Azure DevOps, which also imports the LFS pointers that are Git objects, but not the LFS files -To move over the LFS files (you will need both Git.exe and LFS client in the same box and access to both source repository and destination repository) -- Clone the imported repository from Azure DevOps to local system, clone will work but it will fail while performing checkout of LFS files -- Add the source repository as remote (say ‘source’) -- Perform `git lfs fetch source --all` (this will bring over all LFS files from source to your local repository) -- Assuming the destination VSTS repository is your ‘target’ remote +To move over the LFS files, you need both Git.exe and LFS client in the same box and access to both source repository and destination repository +- Clone the imported repository from Azure DevOps to local system. Clone works, but it fails while performing checkout of LFS files +- Add the source repository as remote, for example, "source" +- Perform `git lfs fetch source --all`, which brings over all LFS files from source to your local repository +- Assuming the destination VSTS repository is your "target" remote - Perform `git lfs push target --all` -### Can I import updates if the source changes later? +### Q: Can I import updates if the source changes later? -The import service is for initially importing a entire repository. -To mirror later changes, you'll need a local clone of the repository with remotes set to both source and destination. +A: The import service is for initially importing an entire repository. +To mirror later changes, you need a local clone of the repository with remotes set to both source and destination. You can sync changes using the following commands. -We'll treat the Azure Repos import as `origin` and the original repo as `upstream`. +We treat the Azure Repos import as `origin` and the original repo as `upstream`. ```shell -git clone --bare +git clone --bare .git cd git remote add --mirror=fetch upstream git fetch upstream --tags git push origin --all ``` - - ## Next steps > [!div class="nextstepaction"] > [New to Git repos? Learn more](/devops/develop/git/set-up-a-git-repository) ## Related articles -- [Learn more about Git in the Git tutorial](gitworkflow.md) - +- [Learn more about Git workflow](gitworkflow.md) diff --git a/docs/repos/git/includes/alternate-credentials.md b/docs/repos/git/includes/alternate-credentials.md index 4d265a56543..cfeefd7381c 100644 --- a/docs/repos/git/includes/alternate-credentials.md +++ b/docs/repos/git/includes/alternate-credentials.md @@ -2,19 +2,22 @@ ms.topic: include --- -1. Sign in to your organization (```http://[youraccount].visualstudio.com```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```) -2. From your home page, open your profile. Go to your security details. +2. From your home page, select :::image type="icon" source="../../../media/icons/user-settings-gear.png" border="false"::: **User settings** > **Profile**. - **Azure DevOps Services** +:::moniker range=" azure-devops" + + :::image type="content" source="../media/my-profile-team-services-preview.png" alt-text="Screenshot shows highlighted Profile button in User settings."::: - TFS home page, open your profile, go to Security +:::moniker-end - **Azure DevOps Server and TFS (TFS 2017 and later versions)** +:::moniker range=" < azure-devops" - Go to organization home, open your profile, go to Security + :::image type="content" source="../media/my-profile-team-services.png" alt-text="Screenshot shows highlighted profile button, User settings."::: -3. Enable alternate authentication credentials for this account. Then provide a secondary username and password. +:::moniker-end + +3. Enable alternate authentication credentials and then provide secondary credentials. - ![Enable alternate authentication credentials link on the user profile page](/azure/devops/repos/git/media/enable-alternate-credentials.png) diff --git a/docs/repos/git/includes/azure-repos-prerequisites.md b/docs/repos/git/includes/azure-repos-prerequisites.md index 6058cef640d..3801facf509 100644 --- a/docs/repos/git/includes/azure-repos-prerequisites.md +++ b/docs/repos/git/includes/azure-repos-prerequisites.md @@ -1,41 +1,32 @@ --- ms.service: azure-devops-repos ms.topic: include -ms.date: 02/03/2022 +ms.date: 02/14/2025 ms.subservice: azure-devops-repos-git --- ::: moniker range="azure-devops" -- **Repos** must be enabled in your Azure DevOps project settings. If the **Repos** hub and associated pages don't display, see [Turn an Azure DevOps service on or off](../../../organizations/settings/set-services.md) to reenable **Repos**. +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of a [project](../../../organizations/projects/create-project.md). | +| **Permissions** | - View code in private projects: At least **Basic** access.
      - Clone or contribute to code in private projects: Member of the **Contributors** security group or corresponding permissions in the project.
      - Set branch or repository permissions: **Manage permissions** permissions for the branch or repository.
      - Change default branch: **Edit policies** permissions for the repository.
      - Import a repository: Member of the **Project Administrators** security group or Git project-level **Create repository** permission set to **Allow**. For more information, see [Set Git repository permissions](../set-git-repository-permissions.md). | +| **Services** | [Repos enabled](../../../organizations/settings/set-services.md). | +| **Tools** | Optional. Use **az repos** commands: [Azure DevOps CLI](../../../cli/index.md).| -- To view code in private projects, you must be a member of an Azure DevOps project with **Basic** access level or higher. For public projects, everyone can view the code. - - - If you don't have a project, create one or [sign up for free](../../../user-guide/sign-up-invite-teammates.md). - - - If you aren't a project member, [get added](../../../organizations/accounts/add-organization-users.md). - -- To clone or contribute to code for a private project, you must be a member of the **Contributors** security group or have the corresponding permissions set. For public projects, anyone can clone and contribute code. To learn more, see [What is a public project?](/azure/devops/organizations/projects/about-projects) - - > [!NOTE] - > For public projects, users granted **Stakeholder** access have full access to **Azure Repos**. +> [!NOTE] +> In public projects, users with **Stakeholder** access have full access to Azure Repos, including viewing, cloning, and contributing to code. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" - -- **Repos** must be enabled in your Azure DevOps project settings. If the **Repos** hub and associated pages don't display, see [Turn an Azure DevOps service on or off](../../../organizations/settings/set-services.md) to reenable **Repos**. +::: moniker range=" < azure-devops" -- To view code, you must be a member of the Azure DevOps project with **Basic** access or higher. If you aren't a project member, [get added](../../../organizations/security/add-users-team-project.md). - -- To clone or contribute to code, you must be a member of the **Contributors** security group, or have the corresponding permissions, in the project you want to change. +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of a [project](../../../organizations/projects/create-project.md). | +| **Permissions** | - View code: At least **Basic** access.
      - Clone or contribute to code: Member of the **Contributors** security group or corresponding permissions in the project. | +| **Services** | [Repos enabled](../../../organizations/settings/set-services.md). | ::: moniker-end -::: moniker range="< azure-devops-2019" - -- To view code, you must be a member of an Azure DevOps project with **Basic** access or higher. If you aren't a project member, [get added](../../../organizations/security/add-users-team-project.md). -- To clone or contribute to code, you must be a member of the **Contributors** security group or have the corresponding permissions. - -::: moniker-end diff --git a/docs/repos/git/includes/change-default-branch-instructions.md b/docs/repos/git/includes/change-default-branch-instructions.md index 961ada96849..2ce27057c34 100644 --- a/docs/repos/git/includes/change-default-branch-instructions.md +++ b/docs/repos/git/includes/change-default-branch-instructions.md @@ -21,38 +21,3 @@ To change your repo's default branch for merging new pull requests, you need at ::: moniker-end -::: moniker range="azure-devops-2019" - -1. Select the settings button in your project bottom-left corner to open the project administration page. - - ![Open the administrative area of the web portal for your project](/azure/devops/repos/git/media/pull-requests/gear-icon-settings-2019.png) - -1. Select **Repositories**. - -1. Select your Git repository. Your branches are displayed under your repo. - -1. Select the **...** next to the branch you want to set as default, then select **Set as default branch**. - - ![Set a default branch for a Git repo](/azure/devops/repos/git/media/pull-requests/set-default-branch-2019.png) - -1. Once you've set the new default branch, you may delete the previous one if you want. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. Select the settings button in your project to open the project administration page. - - ![Open the administrative area of the web portal for your project](/azure/devops/repos/git/media/pull-requests/gear_icon_settings.png) - -1. Select **Version Control**. - -1. Select your Git repository. Your branches are displayed under your repo. - -1. Select the **...** next to the branch you want to set as default, then select **Set as default branch**. - - ![Set a default branch for a Git repo](/azure/devops/repos/git/media/pull-requests/set_default_branch.png) - -1. Once you've set the new default branch, you may delete the previous one if you want. - -::: moniker-end diff --git a/docs/repos/git/includes/ignore-files-gitignore.md b/docs/repos/git/includes/ignore-files-gitignore.md index e5e517aac15..35ad1fff4bc 100644 --- a/docs/repos/git/includes/ignore-files-gitignore.md +++ b/docs/repos/git/includes/ignore-files-gitignore.md @@ -7,6 +7,6 @@ msservice: azure-devops-repos ms.subservice: azure-devops-repos-git --- -In the **Git Changes** window, right-click any changed file that you want Git to ignore and choose **Ignore this local item** or **Ignore this extension**. Those menu options don't exist for tracked files. +In the **Git Changes** window, right-click any changed file that you want Git to ignore, and then select **Ignore this local item** or **Ignore this extension**. Those menu options don't exist for tracked files. :::image type="content" source="../media/ignore-files/visual-studio-2019/git-experience/git-ignore.png" border="true" alt-text="Screenshot of the context menu options for changed files in the Git Changes window in Visual Studio." lightbox="../media/ignore-files/visual-studio-2019/git-experience/git-ignore-lrg.png"::: diff --git a/docs/repos/git/includes/note-new-git-tool.md b/docs/repos/git/includes/note-new-git-tool.md index f059420bfe6..d7a97412d71 100644 --- a/docs/repos/git/includes/note-new-git-tool.md +++ b/docs/repos/git/includes/note-new-git-tool.md @@ -9,4 +9,4 @@ ms.subservice: azure-devops-repos-git --- > [!NOTE] -> Visual Studio 2019 version 16.8 and later versions provide a new Git menu for managing the Git workflow with less context switching than Team Explorer. Procedures provided in this article under the Visual Studio tab provide information for using the Git experience as well as Team Explorer. To learn more, see [Side-by-side comparison of Git and Team Explorer](/visualstudio/version-control/git-team-explorer-feature-comparison). +> Visual Studio 2019 version 16.8 and later versions provide a new Git menu for managing the Git workflow with less context switching than Team Explorer. Procedures provided in this article under the Visual Studio tab provide information for using the Git experience as well as Team Explorer. For more information, see [Side-by-side comparison of Git and Team Explorer](/visualstudio/version-control/git-team-explorer-feature-comparison). diff --git a/docs/repos/git/includes/note-tfs-2018.2-update.md b/docs/repos/git/includes/note-tfs-2018.2-update.md index 160efddc42a..4fe9a9a7578 100644 --- a/docs/repos/git/includes/note-tfs-2018.2-update.md +++ b/docs/repos/git/includes/note-tfs-2018.2-update.md @@ -8,7 +8,4 @@ ms.date: 10/15/2021 ms.subservice: azure-devops-repos-git --- -::: moniker range="tfs-2018" -> [!NOTE] -> The feature documented in this article requires TFS 2018 Update 2 or later version. -::: moniker-end \ No newline at end of file + \ No newline at end of file diff --git a/docs/repos/git/includes/open-team-project-in-vs-qa.md b/docs/repos/git/includes/open-team-project-in-vs-qa.md index 4d53758e889..0158ff85e60 100644 --- a/docs/repos/git/includes/open-team-project-in-vs-qa.md +++ b/docs/repos/git/includes/open-team-project-in-vs-qa.md @@ -5,4 +5,4 @@ ms.topic: include #### Q: Why does the sign-in page differ between the web portal and Visual Studio? -**A:** Your sign-in page depends on whether you used a Microsoft account or a work account with Azure DevOps. Always sign in with the username and password that you use for Azure DevOps. +**A:** Your sign-in page depends on whether you used a Microsoft account or a work account with Azure DevOps. Always sign in with the credentials that you use for Azure DevOps. diff --git a/docs/repos/git/includes/personal-access-tokens.md b/docs/repos/git/includes/personal-access-tokens.md index 9d11f5b0234..7cc7df8deee 100644 --- a/docs/repos/git/includes/personal-access-tokens.md +++ b/docs/repos/git/includes/personal-access-tokens.md @@ -4,11 +4,11 @@ ms.topic: include ## Create a PAT -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 2. From your home page, open user settings :::image type="icon" source="../../../media/icons/user-settings-gear.png" border="false"::: and select **Personal access tokens**. - :::image type="content" source="../media/select-personal-access-tokens.jpg" alt-text="Screenshot showing selection, Personal Access Tokens."::: + :::image type="content" source="../media/select-personal-access-tokens.png" alt-text="Screenshot showing selection, Personal Access Tokens."::: 3. Select **+ New Token**. @@ -21,60 +21,29 @@ ms.topic: include 5. Select the [scopes](../../../integrate/get-started/authentication/oauth.md#scopes) for this token to authorize for *your specific tasks*. - For example, to create a token to enable a [build and release agent](/azure/devops/pipelines/agents/agents) to authenticate to Azure DevOps Services, limit your token's scope to **Agent Pools (Read & manage)**. To read audit log events, and manage and delete streams, select **Read Audit Log**, and then select **Create**. + For example, to create a token for a [build and release agent](/azure/devops/pipelines/agents/agents) to authenticate to Azure DevOps, set the token's scope to **Agent Pools (Read & manage)**. To read audit log events and manage or delete streams, select **Read Audit Log**, and then select **Create**. :::image type="content" source="../media/select-pat-scopes-preview.png" alt-text="Screenshot showing selected scopes for a PAT."::: > [!NOTE] - > You may be restricted from creating full-scoped PATs. If so, your Azure DevOps Administrator in Azure AD has enabled a policy which limits you to a specific custom defined set of scopes. For more information, see [Manage PATs with policies/Restrict creation of full-scoped PATs](../../../organizations/accounts/manage-pats-with-policies-for-administrators.md#restrict-creation-of-full-scoped-pats). - > For a custom defined PAT, the required scope for accessing the Component Governance API, `vso.governance`, isn't selectable in the UI. + > You might be restricted from creating full-scoped PATs. If so, your Azure DevOps Administrator in Microsoft Entra ID enabled a policy that limits you to a specific custom-defined set of scopes. For more information, see [Manage PATs with policies/Restrict creation of full-scoped PATs](../../../organizations/accounts/manage-pats-with-policies-for-administrators.md#restrict-creation-of-full-scoped-pats). + > For a custom-defined PAT, the required scope for accessing the Component Governance API, `vso.governance`, isn't selectable in the UI. 6. When you're done, copy the token and store it in a secure location. For your security, it doesn't display again. :::image type="content" source="../media/copy-token-to-clipboard.png" alt-text="Screenshot showing how to copy the token to your clipboard."::: -> [!WARNING] -> Treat and use a PAT like your password and keep it a secret. - -::: moniker range=" < azure-devops-2019" - -1. Sign in to your web portal (```https://{server}:8080/tfs/```). - -2. From your home page, open your profile. Go to your security details. - - :::image type="content" source="../media/my-profile-team-services.png" alt-text="Screenshot showing home page, opening your profile, and the Security button."::: - -3. Create a personal access token. - - :::image type="content" source="../media/add-personal-access-token.png" alt-text="Screenshot showing adding a personal access token."::: - -4. Name your token. Select a lifespan for your token. - - If you have more than one organization, you can also select the organization where you want to use the token. - - :::image type="content" source="../media/setup-personal-access-token.png" alt-text="Screenshot showing information entry, including token name and lifespan."::: - -5. Select the [scopes](../../../integrate/get-started/authentication/oauth.md#scopes) - for this token to authorize for *your specific tasks*. - - For example, to create a token to enable a [build and release agent](/azure/devops/pipelines/agents/agents) to authenticate, limit your token's scope to **Agent Pools (read, manage)**. - -6. When you're done, make sure to *copy the token*. For your security, it doesn't display again. Use this token as your password. Select **Close**. - - :::image type="content" source="../../tfvc/media/create-personal-access-token.png" alt-text="Screenshot showing created token."::: - -::: moniker-end - Use your PAT anywhere your user credentials are required for authentication in Azure DevOps. > [!IMPORTANT] -> For organizations backed by Azure Active Directory, you have 90 days to sign in with your new PAT, otherwise it's considered inactive. For more information, see [User sign-in frequency for Conditional Access](/azure/active-directory/conditional-access/howto-conditional-access-session-lifetime). +> - Treat a PAT with the same caution as your password and keep it confidential. +> - Sign in with your new PAT within 90 days for organizations backed by Microsoft Entra ID; otherwise, the PAT becomes inactive. For more information, see [User sign-in frequency for Conditional Access](/azure/active-directory/conditional-access/howto-conditional-access-session-lifetime). ### Notifications -Users receive two notifications during the lifetime of a PAT - one upon creation and the other seven days before the expiration. +During the lifespan of a PAT, users receive two notifications: the first at the time of creation and the second seven days before its expiration. -After you create a PAT, you receive a notification similar to the following example. This notification confirms that your PAT was added to your organization. +After you create a PAT, you receive a notification similar to the following example. This notification serves as confirmation that your PAT was successfully added to your organization. :::image type="content" source="/azure/devops/organizations/accounts/media/use-personal-access-tokens-to-authenticate/pat-creation.png" alt-text="Screenshot showing PAT created notification."::: @@ -90,72 +59,30 @@ For more information, see [Configure an SMTP server and customize email for aler #### Unexpected notification -If you receive an unexpected PAT notification, an administrator or tool might have created a PAT on your behalf. See the following examples. +If you receive an unexpected PAT notification, it might mean that an administrator or tool created a PAT for you. Here are some examples: -- When you connect to an Azure DevOps Git repo through git.exe. it creates a token with a display name like "git: `https://MyOrganization.visualstudio.com/` on MyMachine." -- When you or an administrator sets up an Azure App Service web app deployment, it creates a token with a display name like "Service Hooks: : Azure App Service: : Deploy web app." -- When you or an administrator sets up web load testing as part of a pipeline, it creates a token with a display name like "WebAppLoadTestCDIntToken." -- When a Microsoft Teams Integration Messaging Extension is set up, it creates a token with a display name like "Microsoft Teams Integration." +- A token named "git: `https://dev.azure.com/{Your_Organization}` on YourMachine" gets created when you connect to an Azure DevOps Git repo via git.exe. +- A token named "Service Hooks: Azure App Service: Deploy web app" gets created when you or an administrator sets up an Azure App Service web app deployment. +- A token named "WebAppLoadTestCDIntToken" gets created when web load testing gets set up as part of a pipeline by you or an administrator. +- A token named "Microsoft Teams Integration" gets created when a Microsoft Teams Integration Messaging Extension gets set up. > [!WARNING] -> If you believe that a PAT exists in error, we suggest you [revoke the PAT](../../../organizations/accounts/admin-revoke-user-pats.md). Then, change your password. As an Azure AD user, check with your administrator to see if your organization was used from an unknown source or location. See also the FAQ about [accidentally checking in a PAT to a public GitHub repository](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#q-what-happens-if-i-accidentally-check-my-pat-into-a-public-repository-on-github). +> - [Revoke the PAT](../../../organizations/accounts/admin-revoke-user-pats.md) (and change your password) if you suspect it exists in error. +> - Check with your administrator if you're a Microsoft Entra user to see if an unknown source or location accessed your organization. +> - Review the FAQ on [accidental PAT check-ins to public GitHub repositories](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#q-what-happens-if-i-accidentally-check-my-pat-into-a-public-repository-on-github). ## Use a PAT -Your PAT is your identity and represents you when you use it, just like a password. - -**Git** - -Git interactions require a username, which can be anything except the empty string. -To use a PAT with HTTP basic authentication, use `Base64-encode` for and `$MyPat`, which is included in the following code block. - -#### [Windows](#tab/Windows/) - -In PowerShell, enter the following code. - -```powershell -$MyPat = 'yourPAT' - -$B64Pat = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("`:$MyPat")) - -git -c http.extraHeader="Authorization: Basic $B64Pat" clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName +Your PAT serves as your digital identity, much like a password. You can use PATs as a quick way to do one-off requests or prototype an application locally. +> [!IMPORTANT] +> When your code is working, it's a good time to switch from basic auth to [Microsoft Entra OAuth](../../../integrate/get-started/authentication/entra-oauth.md). You can use Microsoft Entra ID tokens anywhere a PAT gets used, unless specified further in this article. -``` - -To keep your token more secure, use credential managers so you don't have to enter your credentials every time. We recommend [Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager). [Git for Windows](https://www.git-scm.com/download/win) is required. - -#### [Linux/macOS](#tab/Linux/) - -In Bash, enter the following code. - -```bash -MY_PAT=yourPAT # replace "yourPAT" with "PatStringFromWebUI" -B64_PAT=$(printf ":%s" "$MY_PAT" | base64) -git -c http.extraHeader="Authorization: Basic ${B64_PAT}" clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName -``` - -To keep your token more secure, use credential managers so you don't have to enter your credentials every time. We recommend [Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager). - -*** - -**Existing repos** - -For existing repositories, if you already added the origin using the username, run the following command first. - -``git remote remove origin`` - -Otherwise, run the following command. - -``git remote add origin https://@.visualstudio.com:/ path to git repo = /_git/ git push -u origin --all`` - -### Use a PAT in your code - -You can use a PAT in your code. +You can use a PAT in your code to authenticate [REST APIs](/rest/api/azure/devops) requests and automate workflows. To do so, include the PAT in the authorization header of your HTTP requests. #### [Windows](#tab/Windows/) -If you wish to provide the PAT through an HTTP header, first convert it to a Base64 string. The following example shows how to convert to Base64 using C#. +To provide the PAT through an HTTP header, first convert it to a `Base64` string. The following example shows how to convert to `Base64` using C#. ```cs @@ -247,27 +174,23 @@ curl -u :{PAT} https://dev.azure.com/{organization}/_apis/build-release/builds *** -When your code is working, it's a good time to switch from basic auth to [OAuth](../../../integrate/get-started/authentication/oauth.md). - -For more information and examples of how to use PATs, see the following articles: - -- [Git credential managers](../set-up-credential-managers.md) -- [REST APIs](/rest/api/azure/devops) -- [NuGet on a Mac](../../../artifacts/nuget/consume.md#mac-os) -- [Reporting clients](../../../report/powerbi/client-authentication-options.md#enter-credentials-within-a-client) -- [Get started with Azure DevOps CLI](../../../cli/index.md). +Some more examples of how to use PATs can be found in the following articles: -::: moniker range="< azure-devops-2019" - -If you enable IIS Basic Authentication, PATs aren't valid. For more information, see [Using IIS Basic Authentication on-premises](../../../integrate/get-started/authentication/iis-basic-auth.md). - -::: moniker-end +- [Authenticate with your Git repos](../auth-overview.md) +- [Set up Git credential managers (GCM) to connect with Git repositories](../set-up-credential-managers.md) +- [Use NuGet on a Mac](../../../artifacts/nuget/consume.md) +- [Authenticate reporting clients](../../../report/powerbi/client-authentication-options.md#enter-credentials-within-a-client) +- [Get started with Azure DevOps CLI](../../../cli/index.md) ::: moniker range="azure-devops" ## Modify a PAT -You can regenerate or extend a PAT, and modify its [scope](../../../integrate/get-started/authentication/oauth.md#scopes). After regeneration, the previous PAT is no longer authorized. +Do the following steps to: + +- Regenerate a PAT to create a new token, which invalidates the previous one. +- Extend a PAT to increase its validity period. +- Alter the [scope](../../../integrate/get-started/authentication/oauth.md#scopes) of a PAT to change its permissions. 1. From your home page, open your user settings, and then select **Profile**. @@ -275,15 +198,19 @@ You can regenerate or extend a PAT, and modify its [scope](../../../integrate/ge 2. Under Security, select **Personal access tokens**. Select the token you want to modify, and then **Edit**. - :::image type="content" source="/azure/devops/repos/git/media/select-edit-pat-current-view.png" alt-text="Screenshot showing highlighted Edit button to modify PAT."::: + :::image type="content" source="../media/select-edit-pat-current-view.png" alt-text="Screenshot showing highlighted Edit button to modify PAT."::: -3. Edit the token name, token expiration, or the scope of access that's associated with the token, and then select **Save**. +3. Edit the token name, token expiration, or the scope of access associated with the token, and then select **Save**. :::image type="content" source="../media/modify-pat.png" alt-text="Screenshot showing modified PAT."::: ## Revoke a PAT -You can revoke a PAT at any time, for various reasons. +You can revoke a PAT at any time for these and other reasons: + +- Revoke a PAT if you suspect it's compromised. +- Revoke a PAT when it's no longer needed. +- Revoke a PAT to enforce security policies or compliance requirements. 1. From your home page, open your user settings, and then select **Profile**. @@ -297,4 +224,6 @@ You can revoke a PAT at any time, for various reasons. :::image type="content" source="../media/revoke-token-confirmation-dialog-preview.png" alt-text="Screenshot showing confirmation screen to revoke PAT."::: +For more information, see [Revoke user PATs for admins](../../../organizations/accounts/admin-revoke-user-pats.md). + ::: moniker-end diff --git a/docs/repos/git/index.yml b/docs/repos/git/index.yml index a4256ab6b5c..c26c26b5215 100644 --- a/docs/repos/git/index.yml +++ b/docs/repos/git/index.yml @@ -10,7 +10,7 @@ metadata: ms.topic: landing-page ms.author: sdanie author: steved0x - ms.date: 01/18/2023 + ms.date: 08/01/2023 ms.subservice: azure-devops-repos-git # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new diff --git a/docs/repos/git/limits.md b/docs/repos/git/limits.md index e352b03c1f4..c3144bd6bbc 100644 --- a/docs/repos/git/limits.md +++ b/docs/repos/git/limits.md @@ -5,8 +5,9 @@ description: Resource limits applied to Git operations ms.assetid: ms.service: azure-devops-repos ms.topic: reference -ms.date: 05/26/2021 +ms.date: 08/22/2024 monikerRange: 'azure-devops' +ai-usage: ai-assisted ms.subservice: azure-devops-repos-git --- @@ -15,17 +16,13 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -We impose a few resource limits on Git repositories in Azure Repos. -Our goal is to ensure reliability and availability for all customers. -Also, by keeping the amount of data and number of pushes reasonable, you can expect to have a better overall experience with Git. +We impose resource limits on Git repositories in Azure Repos to ensure reliability and availability for all customers. By keeping data sizes and the number of pushes reasonable, you can expect a better overall experience with Git. -Git participates in [rate limiting](../../integrate/concepts/rate-limits.md) along with the rest of Azure DevOps. -In addition, we impose limits on the total size of repositories and pushes. +Git participates in [rate limiting](../../integrate/concepts/rate-limits.md) along with the rest of Azure DevOps Services. Additionally, we impose limits on the total size of repositories, pushes, and the length of file and directory paths. ## Repository size -Repositories should be no larger than 250GB. -To retrieve the size of your repository, execute "git count-objects -vH" in a command prompt, and look for the entry called "size-pack": +Repositories should be no larger than 250 GB. To retrieve the size of your repository, execute `git count-objects -vH` in a command prompt, and look for the entry called "size-pack": ``` D:\my-repo>git count-objects -vH @@ -40,25 +37,32 @@ garbage: 0 size-garbage: 0 bytes ``` -We recommend keeping your repository below 10GB for optimal operation. -If your repository exceeds this size consider using [Git-LFS](manage-large-files.md), [Scalar](https://github.com/microsoft/Scalar), or [Azure Artifacts](../../artifacts/index.yml) to refactor your development artifacts. +We recommend keeping your repository below 10 GB for optimal performance. If your repository exceeds this size, consider using [Git-LFS](manage-large-files.md), [Scalar](https://github.com/microsoft/Scalar), or [Azure Artifacts](../../artifacts/index.yml) to manage your development artifacts. -Azure DevOps continuously reduces the overall size and increases the efficiency of Git repositories by consolidating similar files into packs. -For repositories nearing 250 GB, the internal limit on pack files can be reached before the optimization process completes. -Any user attempting to write to the repository will see the following error message: “The Git pack file limit has been reached, write operations are temporarily unavailable while the repository is updated.“ -Write operations will be restored immediately after the job completes. +Azure Repos continuously reduces the overall size and increases the efficiency of Git repositories by consolidating similar files into packs. For repositories nearing 250 GB, the internal limit on pack files can be reached before the optimization process completes. When this limit is reached, users attempting to write to the repository see the following error message: "The Git pack file limit has been reached, write operations are temporarily unavailable while the repository is updated." Write operations get restored immediately after the optimization job completes. + +Files should be no larger than 100 MB. This limit helps ensure optimal performance and reliability of the Git repository. Large files can significantly slow down repository operations, such as cloning, fetching, and pushing changes. If you need to store large files, consider using [Git LFS (Large File Storage)](https://git-lfs.github.com/), which is designed to handle large files efficiently by storing them outside the main repository and only keeping references to them within the repository. This approach helps maintain the performance and manageability of your Git repository. ## Push size -Very large pushes use up a lot of resources, blocking or slowing other parts of the service. -Such pushes often don't map to normal software development activities. -Someone may have inadvertently checked in build outputs or a VM image, for example. -For these reasons and more, pushes are limited to 5GB at a time. +Large pushes consume significant resources, blocking or slowing other parts of the service. These pushes often don't align with typical software development activities and might include items like build outputs or VM images. Therefore, pushes are limited to 5 GB at a time. -There's one exception where large pushes are normal. -When you migrate a repository from another service into Azure Repos, it comes in as a single push. -We don't intend to block imports, even of very large repositories. -If the repository is more than 5GB, then you must use the web to [Import the repository](import-git-repository.md) instead of the command line. +There's one exception where large pushes are normal: migrating a repository from another service into Azure Repos. Such migrations come in as a single push, and we don't intend to block imports, even for large repositories. If the repository exceeds 5 GB, you must use the web to [import the repository](import-git-repository.md) instead of the command line. ### Push size for LFS objects -[Git LFS](https://git-lfs.github.com/) doesn't count towards the 5GB repo limit. The 5GB limit is only for files in the actual repo, not blobs stored as part of LFS. If you get failing pushes on the 5GB limit verify your ````.gitattributes```` file includes the extensions of the files you mean to track using LFS and that this file was saved and staged before you staged the large files to be tracked. + +[Git LFS](https://git-lfs.github.com/) doesn't count towards the 5-GB repository limit. The 5-GB limit applies only to files in the actual repository, not to blobs stored with LFS. If you encounter failing pushes due to the 5-GB limit, ensure your `.gitattributes` file includes the extensions of the files you intend to track with LFS. Ensure this file is saved and staged before you stage the large files to be tracked. + +## Path length + +Azure Repos enforces a push policy that limits the length of paths in a Git repository by rejecting pushes that introduce excessively long paths. Unlike the [Maximum path length policy](repository-settings.md#maximum-path-length-policy), you can't disable or override it, as it enforces the maximum values supported by our platform. + +The following limits are enforced: +- Total path length: 32,766 characters +- Path component length (folder or file name): 4,096 characters + +This policy only affects newly introduced paths in a push. It doesn't apply if you change an existing file, but it does apply if you create a new file, rename, or move an existing one. + +If any commits being pushed introduce paths that exceed these limits, the push is rejected with one of the following error messages: +- `VS403729: The push was rejected because commit '6fbe8dc700fdb33ef512e2b9e35436faf555de76' contains a path, which exceeds the maximum length of 32766 characters.` +- `VS403729: The push was rejected because commit 'd23277abfe2d8dcbb88456da880de631994dabb4' contains a path component, which exceeds the maximum length of 4096 characters.` diff --git a/docs/repos/git/lock-branches.md b/docs/repos/git/lock-branches.md index 09e8dc08710..e1640568d24 100644 --- a/docs/repos/git/lock-branches.md +++ b/docs/repos/git/lock-branches.md @@ -22,12 +22,17 @@ Locking also blocks any new commits from being added to the branch by others. ## Locking limitations Locking is ideal for preventing new changes that might conflict with an important merge or to place a branch into a read-only state. -Use [branch policies](branch-policies.md) and [pull requests](pull-requests.md) with locking if you want to ensure that changes in a branch are reviewed before they are merged and prevent changes in the locked branch. +Use [branch policies](branch-policies.md) and [pull requests](pull-requests.md) with locking to ensure that changes in a branch get reviewed before they get merged and prevent changes in the locked branch. -Locking does not prevent cloning of a repo or fetching updates made in the branch into your local repo. -Share with your team the reason for the locking of the branch and make sure your team knows what to do to work with the branch after it is unlocked. +Locking doesn't prevent cloning of a repo or fetching updates made in the branch into your local repo. +Share with your team the reason for the locking of the branch and make sure your team knows what to +do to work with the branch after it is unlocked. -> Only the user who locked the branch or a user with [Remove Others' Locks permissions](set-git-repository-permissions.md#git-repository) for the branch can remove the lock. +## Prerequisites + +| Category | Requirements | +|-------------|-------------| +|**Permissions**|User who locked the branch or [**Remove Others' Locks** permissions](set-git-repository-permissions.md#git-repository) for the branch.| ## Lock a branch using the Branches view diff --git a/docs/repos/git/manage-large-files.md b/docs/repos/git/manage-large-files.md index 45e10a8a3f7..e95d78dbb85 100644 --- a/docs/repos/git/manage-large-files.md +++ b/docs/repos/git/manage-large-files.md @@ -1,7 +1,7 @@ --- title: Work with large files in your Git repo titleSuffix: Azure Repos -description: Recommendations on how to manage large binary files in Git, Visual Studio, and Team Foundation Server. +description: Get recommendations on how to manage large binary files in Git, Visual Studio, and Azure DevOps Server. ms.assetid: 57ad13a3-9178-4f31-b776-79f32b1afa58 ms.service: azure-devops-repos ms.topic: conceptual @@ -15,90 +15,92 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Git is great at keeping the footprint of your source code small because the differences between versions are easily picked out and code is easily compressed. -Large files that don't compress well and change entirely between versions (such as binaries) present problems when stored in your Git repos. -Git's fast performance comes from its ability to address and switch to all versions of a file from its local storage. +Git helps keep the footprint of your source code small because the differences between versions are easily picked out and code is easily compressed. +Large files that don't compress well and that change entirely between versions (such as binaries) present problems when they're stored in your Git repos. +Git's fast performance comes from its ability to address and switch to all versions of a file from its local storage. -If you have large, undiffable files in your repo such as binaries, you will keep a full copy of that file in your repo every time you commit a change to the file. -If many versions of these files exist in your repo, they will dramatically increase the time to checkout, branch, fetch, and clone your code. +If you have large, undiffable files in your repo (such as binaries), you keep a full copy of those files in your repo every time you commit a change to them. +If many versions of these files exist in your repo, they dramatically increase the time to check out, branch, fetch, and clone your code. -## What kind of files should you store in Git? +## What kinds of files should you store in Git? -### Source code-not dependencies +### Commit source code, not dependencies As your team works with editors and tools to create and update files, you should put these files into Git so your team can enjoy the benefits of Git's workflow. -Don't commit other types of files, such as DLLs, library files, and other dependencies that aren't created by your team but your code depends on into your repo. Deliver these files -through [package management](../../artifacts/start-using-azure-artifacts.md) to your systems. +Don't commit other types of files into your repo: for example, DLLs, library files, and other dependencies that your team doesn't create but your code depends on. Deliver these files +through [package management](../../artifacts/start-using-azure-artifacts.md) to your systems. -Package management bundles your dependencies and installs the files on your system when you deploy the package. -Packages are versioned to ensure that code tested in one environment runs the same in another environment as long as they have the same installed packages. +Package management bundles your dependencies and installs the files on your system when you deploy the package. +Packages are versioned to ensure that code tested in one environment runs the same in another environment, as long as the environments have the same installed packages. ### Don't commit outputs -Don't commit the binaries, logs, tracing output or diagnostic data from your builds and tests. These are outputs from your code, not the source code itself. Share logs and trace information +Don't commit the binaries, logs, tracing output, or diagnostic data from your builds and tests. These are outputs from your code, not the source code itself. Share logs and trace information with your team through [work item tracking](../../boards/backlogs/add-work-items.md) tools or through team file sharing. ### Store small, infrequently updated binary sources in Git -Binary source files that are infrequently updated will have relatively few versions committed, and will not take up very much space provided that their file size is small. -Images for the web, icons, and other smaller art assets can fall into this category. It's better to store these files in Git with the rest of your source so your team can use -consistent workflow. +Binary source files that are infrequently updated have relatively few versions committed. They don't take up much space if their file size is small. +Images for the web, icons, and other smaller art assets can fall into this category. It's better to store these files in Git with the rest of your source so your team can use a +consistent workflow. -> [!IMPORTANT] -> Even small binaries can cause problems if updated often. One hundred changes to a 100KB binary file uses up as much storage as 10 changes to a 1MB binary, and due to the frequency of updates to the smaller binary will take slow down branching performance more often than the large binary. +> [!IMPORTANT] +> Even small binaries can cause problems if they're updated often. For example, 100 changes to a 100-KB binary file use as much storage as 10 changes to a 1-MB binary. Due to the frequency of updates, the smaller binary will slow down branching performance more often than the large binary. ### Don't commit large, frequently updated binary assets -Git will manage one main version of a file and then store only the differences from that version in a process known as deltification. -Deltification and file compression allow Git to store your entire code history in your local repo. -Large binaries usually change entirely between versions and are often already compressed, making these files difficult for Git to manage since the difference between versions is very large. -Git must store the entire contents of each version of the file and has difficulty saving space through deltification and compression. -Storing the full file versions of these files causes repo size to increase over time, reducing branching performance, increasing the clone times, and expanding storage requirements. +Git manages one main version of a file and then stores only the differences from that version, in a process known as *deltification*. +Deltification and file compression allow Git to store your entire code history in your local repo. +Large binaries usually change entirely between versions and are often already compressed. These files are difficult for Git to manage because the differences between versions are large. + +Git must store the entire contents of each version of the file and has difficulty saving space through deltification and compression. +Storing the full versions of these files causes the repo size to increase over time. The increased repo size reduces branching performance, increases the clone times, and expands storage requirements. ## Strategies for working with large binary source files -- Don't commit compressed archives of data. It's better to uncompress the files and commit the diffable sources, letting Git handle compressing the data in your repo. -- Avoid committing compiled code and other binary dependencies. Commit the source and build the dependencies, or use a package management solution to version and supply these files +- Don't commit compressed archives of data. It's better to uncompress the files and commit the diffable sources. Let Git handle compressing the data in your repo. +- Avoid committing compiled code and other binary dependencies. Commit the source and build the dependencies, or use a package management solution to version and supply these files to your system. -- Store configuration and other structured data in diffable plain text formats, such as JSON. +- Store configuration and other structured data in diffable plain-text formats, such as JSON. + +## What is Git LFS? -## Use Git Large File Storage (LFS) +When you have source files with large differences between versions and frequent updates, you can use [Git Large File Storage (LFS)](https://git-lfs.github.com/) to manage these file types. +Git LFS is an extension to Git that provides data that describes the large files in a commit to your repo. It stores the binary file contents into separate remote storage. -When you have source files with large differences between versions and frequent updates, you can use [Git LFS](https://git-lfs.github.com/) to manage these file types. -Git LFS is an extension to Git which commits data describing the large files in a commit to your repo, and stores the binary file contents into separate remote storage. -When you clone and switch branches in your repo, Git LFS downloads the correct version from that remote storage. -Your local development tools will transparently work with the files as if they were committed directly to your repo. +When you clone and switch branches in your repo, Git LFS downloads the correct version from that remote storage. +Your local development tools transparently work with the files as if they were committed directly to your repo. -### Benefits +### Benefits -The benefit of Git LFS is that your team can use the familiar end to end Git workflow no matter what files your team creates. -LFS files can be as big as you need them to be. +A benefit of Git LFS is that your team can use the familiar end-to-end Git workflow no matter what files your team creates. +LFS handles large files to prevent them from adversely affecting the overall repository. Additionally, as of version 2.0, Git LFS supports [file locking](https://github.com/git-lfs/git-lfs/wiki/File-Locking) to help your team work on large, undiffable assets like videos, sounds, and game maps. Git LFS is [is fully supported and free in Azure DevOps Services](https://devblogs.microsoft.com/devops/announcing-git-lfs-on-all-vso-git-repos/). -To use LFS with Visual Studio, you need at least [Visual Studio 2015 Update 2](/visualstudio/releasenotes/vs2017-relnotes). +To use LFS with Visual Studio, you need [Visual Studio 2015 Update 2](/visualstudio/releasenotes/vs2017-relnotes) or later. Just follow the [instructions to install the client](https://git-lfs.github.com/), set up LFS tracking for files on your local repo, and then push your changes to Azure Repos. ### Limitations -Git LFS has some drawbacks that you should consider before adopting: +Git LFS has some drawbacks that you should consider before adopting it: -1. Every Git client used by your team must install the Git LFS client and understand its [tracking configuration](https://github.com/github/git-lfs/tree/main/docs). -2. If the Git LFS client is not installed and configured correctly, you will not see the binary files committed through Git LFS when you clone your repo. - Git will download the data describing the large file (which is what Git LFS commits to the repo) and not the actual binary file itself. +- Every Git client that your team uses must install the Git LFS client and understand its [tracking configuration](https://github.com/github/git-lfs/tree/main/docs). +- If the Git LFS client is not installed and configured correctly, you won't see the binary files committed through Git LFS when you clone your repo. + Git will download the data that describes the large file (which is what Git LFS commits to the repo) and not the binary file. Committing large binaries without the Git LFS client installed will push the binary to your repo. -3. Git cannot merge the changes from two different versions of a binary file even if both versions have a common parent. +- Git can't merge the changes from two different versions of a binary file, even if both versions have a common parent. If two people are working on the same file at the same time, they must work together to reconcile their changes to avoid overwriting the other's work. Git LFS provides [file locking](https://github.com/git-lfs/git-lfs/wiki/File-Locking) to help. Users must still take care to always pull the latest copy of a binary asset before beginning work. -4. Azure Repos currently does not support using SSH in repos with Git LFS tracked files. -5. If a user drags and drops a binary file via the web interface into a repo which is configured for Git LFS, the binary will be committed to the repo and not the pointers that would be committed via the Git LFS client. -6. File size limit is 50 GB. -7. One file upload time limit is 1 hour. +- Azure Repos currently doesn't support using Secure Shell (SSH) in repos with Git LFS tracked files. +- If a user drags a binary file via the web interface into a repo that's configured for Git LFS, the binary is committed to the repo--not the pointers that would be committed via the Git LFS client. +- Although there isn't a strict file-size restriction, the server's available free space and current workload could constrain the performance and functionality. +- The time limit for one file upload is one hour. ### File format -The file written into your repo for a Git LFS tracked file will have a few lines with a key and value pair on each line: +The file written into your repo for a Git LFS tracked file has a few lines with a key/value pair on each line: ``` version https://git-lfs.github.com/spec/v1 @@ -106,10 +108,10 @@ oid a747cfbbef63fc0a3f5ffca332ae486ee7bf77c1d1b9b2de02e261ef97d085fe size 4923023 ``` -> [!NOTE] -> The GitHub URL included for the version value only defines the LFS pointer file type, and is not a link to your binary file. +> [!NOTE] +> The GitHub URL included for the version value only defines the LFS pointer file type. It's not a link to your binary file. ### Known issues -If you use a version of LFS below 2.4.0 with Azure DevOps Server or TFS, there's an extra setup step required to [authenticate using NTLM instead of Kerberos](lfs-kerberos.md). -This step is no longer necessary as of LFS 2.4.0, and we highly recommend you upgrade. +If you use a version of LFS earlier than 2.4.0 with Azure DevOps Server, an extra setup step is required to [authenticate via NTLM instead of Kerberos](lfs-kerberos.md). +This step is no longer necessary as of LFS 2.4.0, and we highly recommend that you upgrade. diff --git a/docs/repos/git/manage-your-branches.md b/docs/repos/git/manage-your-branches.md index 97081f3db5a..f434c2da425 100644 --- a/docs/repos/git/manage-your-branches.md +++ b/docs/repos/git/manage-your-branches.md @@ -1,12 +1,12 @@ --- title: Manage branches in your Git repo titleSuffix: Azure Repos -description: Find your work and search for branches using the branches page in Azure DevOps Services/TFS +description: Find your work and search for branches using the branches page in Azure DevOps. ms.assetid: 17722c33-e156-49f1-acad-5fcf4bc3c4fc ms.service: azure-devops-repos -ms.topic: conceptual +ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 02/23/2022 +ms.date: 02/18/2025 ms.subservice: azure-devops-repos-git --- @@ -17,37 +17,32 @@ ms.subservice: azure-devops-repos-git Manage the work in your team's Git repo from the **Branches** view on the web. Customize the view to track the branches you care most about so you can stay on top of changes made by your team. -::: moniker range=">= azure-devops-2019" - View your repo's branches by selecting **Repos**, **Branches** while viewing your repo on the web. -![View your branches](media/repos-navigation/repos-branches.png) +![Screenshot shows View of branches.](media/repos-navigation/repos-branches.png) ::: moniker-end -::: moniker range="tfs-2018" - -View your repo's branches by selecting **Branches** while viewing your repo on the web. +## Prerequisites -![Access the branches view from your Git repo in Team Explorer](media/branches/branches_nav.png) - -::: moniker-end +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] ## Organize your branches -The default **Mine** tab on the branches page shows branches you've created, pushed changes to, or set as a favorite, along with the default branch for the repo, such as `main`. The **All** tab lists all branches in the repo, and the **Stale** tab lists branches in the repo that haven't had any commits in three months or longer. +The default **Mine** tab on the branches page shows branches you created, pushed changes to, or set as a favorite, along with the default branch for the repo, such as `main`. The **All** tab lists all branches in the repo, and the **Stale** tab lists branches in the repo that don't have any commits for the past three months or longer. -![My branches](media/branches/my-branches.png) +![Screenshot shows My branches.](media/branches/my-branches.png) -If you don't see the branch you're looking for and you think it might have been deleted, see [Restore a deleted branch](restore-deleted-branch.md). +If you don't see the branch you're looking for and you think it might be deleted, see [Restore a deleted branch](restore-deleted-branch.md). Filter the listed branches in any of the branch views by entering a specific name or pattern in the **Search all branches** box in the upper right. -![Search and filter branches viewed using the search all branches field](media/branches/search_branches.png) -If your team uses a forward slash separator in your branch names, you'll see a collapsible tree view for those branches. +![Screenshot shows search and filter branches viewed using the search all branches field.](media/branches/search_branches.png) + +If your team uses a forward slash separator in your branch names, a collapsible tree view displays for those branches. >[!TIP] -> Using a naming convention for your branches is highly recommended. For suggestions on how to name your branches, see [Adopt a Git branching strategy](git-branching-guidance.md). +> Use a naming convention for your branches. For suggestions, see [Adopt a Git branching strategy](git-branching-guidance.md). @@ -57,28 +52,27 @@ Add branches from the **All** view to the **Mine** view by selecting the star ic Mark multiple branches as favorites by selecting the star icon on the tree view next to a folder on the tree. Remove favorites by toggling the star off or by selecting the **...** to the right of the star to open the branch context menu, then selecting **Remove from my favorites**. -![Set favorites in your branches to show them in the Mine view](media/branches/branches_favorites.png) +![Screenshot shows Set favorites in your branches to show them in the Mine view.](media/branches/branches_favorites.png) ## Review updates to your branches Each branch name has the name of the last contributor to the branch and a link to the latest commit on the branch. Select the date or time of the last commit to review the updates to the branch. -The branch view also shows the number of commits the branch is ahead of and behind the branch labeled **Compare**. Use this information to quickly check how far a branch has diverged from another. +The branch view also shows the number of commits the branch is ahead of and behind the branch labeled **Compare**. Use this information to quickly check how far a branch diverged from another. -If the branch has a pull request open, you can see its pull request ID. Select the pull request to open it up so you can review the details. +If the branch has a pull request open, you can see its pull request ID. Select the pull request to open it, so you can review the details. -![See how far a branch is ahead of and behind the compare branch](media/branches/branches_ahead_behind.png) +![Screenshot shows example of how far a branch is ahead of and behind the compare branch.](media/branches/branches_ahead_behind.png) ### Change the compare branch -The ahead and behind numbers listed for each branch are in comparison with the branch currently labeled **Compare** on the Branches page. Update your compare branch to see how far ahead or behind -your branches shown on the page are to another branch in your repo: +The "ahead" and "behind" numbers listed for each branch get compared with the branch currently labeled **Compare** on the Branches page. Update your compare branch to see how far ahead or behind your branches are compared to another branch in your repo: -1. Select the **...** next to the branch you want to set as the baseline for comparison. +1. Select **...** **More actions** for the branch you want to set as the baseline for comparison. 2. Select **Set as compare branch**. -The **Compare** label will move to this branch and the other branches on the page will have the number of commits ahead/behind updated to reflect the new comparison. + The **Compare** label moves to this branch, and the other branches on the page have the number of commits ahead/behind updated to reflect the new comparison. ## View branch history @@ -91,5 +85,4 @@ browse the files based on the most recent commit on the branch. **View history** [!INCLUDE [](includes/change-default-branch-instructions.md)] -There are other aspects you should consider before making this change. -Learn about them in this article on [changing your default branch](change-default-branch.md). +There are other aspects you should consider before you make this change. For more information, see [Change your default branch](change-default-branch.md). diff --git a/docs/repos/git/mapping-my-tfvc-actions-to-git.md b/docs/repos/git/mapping-my-tfvc-actions-to-git.md index 33e952063b4..6d554104dfa 100644 --- a/docs/repos/git/mapping-my-tfvc-actions-to-git.md +++ b/docs/repos/git/mapping-my-tfvc-actions-to-git.md @@ -18,7 +18,7 @@ ms.subservice: azure-devops-repos-git Do you plan to adopt Git, are familiar with [TFVC](../tfvc/index.yml) actions, and wondering how they map to [Git](index.yml)? Both are powerful and mature source control systems. However, mapping common actions you have grown accustomed to in the one to the other can be a confusing experience. -This article doesn't delve deep into the [Git commands](https://git-scm.com/book/commands), as they are well documented in the product documentation, but show examples to help you make the right decisions, while moving through a typical create -> clone -> branch -> change -> commit -> push [workflow](https://www.git-scm.com/book/en/v2/Git-Branching-Branching-Workflows). +This article doesn't delve deep into the [Git commands](https://git-scm.com/docs/git#_git_commands), as they are well documented in the product documentation, but show examples to help you make the right decisions, while moving through a typical create -> clone -> branch -> change -> commit -> push [workflow](https://www.git-scm.com/book/en/v2/Git-Branching-Branching-Workflows). ## Start at the beginning by creating a new repo @@ -318,7 +318,7 @@ Alternatively you can manually delete your local repo—after making a valid There are a lot more actions and options available to Git users. Here are some useful reference sites for further reading: -* Git commands covered herein, refer to [git documentation](https://git-scm.com/documentation) +* Git commands covered herein, refer to [git documentation](https://git-scm.com/docs) * [Think like (a) Git](http://think-like-a-git.net), a Guide for the Perplexed. * [How to undo (almost) anything with Git](https://github.com/blog/2019-how-to-undo-almost-anything-with-git), by Joshua Wehner diff --git a/docs/repos/git/media/commit-history/13-SearchCommit.png b/docs/repos/git/media/commit-history/13-SearchCommit.png index 5cb3404c52c..321da8c7187 100644 Binary files a/docs/repos/git/media/commit-history/13-SearchCommit.png and b/docs/repos/git/media/commit-history/13-SearchCommit.png differ diff --git a/docs/repos/git/media/copy-token-to-clipboard.png b/docs/repos/git/media/copy-token-to-clipboard.png index 0cee2b133dc..f635f0ddd5e 100644 Binary files a/docs/repos/git/media/copy-token-to-clipboard.png and b/docs/repos/git/media/copy-token-to-clipboard.png differ diff --git a/docs/repos/git/media/create-new-pat.png b/docs/repos/git/media/create-new-pat.png index 9755e8281df..1a0dc71990a 100644 Binary files a/docs/repos/git/media/create-new-pat.png and b/docs/repos/git/media/create-new-pat.png differ diff --git a/docs/repos/git/media/create-pr-status-server-with-azure-functions/service-hooks-action.png b/docs/repos/git/media/create-pr-status-server-with-azure-functions/service-hooks-action.png index 7446d69dfd9..94ea05d965f 100644 Binary files a/docs/repos/git/media/create-pr-status-server-with-azure-functions/service-hooks-action.png and b/docs/repos/git/media/create-pr-status-server-with-azure-functions/service-hooks-action.png differ diff --git a/docs/repos/git/media/create-pr-status-server/service-hooks-action.png b/docs/repos/git/media/create-pr-status-server/service-hooks-action.png index 340a75d1a95..12f8300a29d 100644 Binary files a/docs/repos/git/media/create-pr-status-server/service-hooks-action.png and b/docs/repos/git/media/create-pr-status-server/service-hooks-action.png differ diff --git a/docs/repos/git/media/git-config/visual-studio-2019/git-experience/git-global-settings.png b/docs/repos/git/media/git-config/visual-studio-2019/git-experience/git-global-settings.png index 58a2eb0a6d5..24d2ea4e62b 100644 Binary files a/docs/repos/git/media/git-config/visual-studio-2019/git-experience/git-global-settings.png and b/docs/repos/git/media/git-config/visual-studio-2019/git-experience/git-global-settings.png differ diff --git a/docs/repos/git/media/git-config/visual-studio-2019/git-experience/git-repo-settings.png b/docs/repos/git/media/git-config/visual-studio-2019/git-experience/git-repo-settings.png index f8ce4795142..ac63620c41e 100644 Binary files a/docs/repos/git/media/git-config/visual-studio-2019/git-experience/git-repo-settings.png and b/docs/repos/git/media/git-config/visual-studio-2019/git-experience/git-repo-settings.png differ diff --git a/docs/repos/git/media/git-config/visual-studio-2019/git-experience/name-email-setting.png b/docs/repos/git/media/git-config/visual-studio-2019/git-experience/name-email-setting.png index c76d90f14f8..73354336f57 100644 Binary files a/docs/repos/git/media/git-config/visual-studio-2019/git-experience/name-email-setting.png and b/docs/repos/git/media/git-config/visual-studio-2019/git-experience/name-email-setting.png differ diff --git a/docs/repos/git/media/git-config/visual-studio-2019/team-explorer/name-email-setting.png b/docs/repos/git/media/git-config/visual-studio-2019/team-explorer/name-email-setting.png index 5a36b128b7c..d273025c2a3 100644 Binary files a/docs/repos/git/media/git-config/visual-studio-2019/team-explorer/name-email-setting.png and b/docs/repos/git/media/git-config/visual-studio-2019/team-explorer/name-email-setting.png differ diff --git a/docs/repos/git/media/install-git-with-git-credential-manager.png b/docs/repos/git/media/install-git-with-git-credential-manager.png index 8ff219305ad..9606ad9cb07 100644 Binary files a/docs/repos/git/media/install-git-with-git-credential-manager.png and b/docs/repos/git/media/install-git-with-git-credential-manager.png differ diff --git a/docs/repos/git/media/manage-large-files/choose-remove.png b/docs/repos/git/media/manage-large-files/choose-remove.png index df3cde10791..3b3b54cf743 100644 Binary files a/docs/repos/git/media/manage-large-files/choose-remove.png and b/docs/repos/git/media/manage-large-files/choose-remove.png differ diff --git a/docs/repos/git/media/mapping-my-tfvc-actions-to-git/actionmap-history2.png b/docs/repos/git/media/mapping-my-tfvc-actions-to-git/actionmap-history2.png index ecf44050dba..d881b4e4d9a 100644 Binary files a/docs/repos/git/media/mapping-my-tfvc-actions-to-git/actionmap-history2.png and b/docs/repos/git/media/mapping-my-tfvc-actions-to-git/actionmap-history2.png differ diff --git a/docs/repos/git/media/modify-pat.png b/docs/repos/git/media/modify-pat.png index ff217366013..37e80c2f3e6 100644 Binary files a/docs/repos/git/media/modify-pat.png and b/docs/repos/git/media/modify-pat.png differ diff --git a/docs/repos/git/media/my-profile-team-services-preview.png b/docs/repos/git/media/my-profile-team-services-preview.png index 6dddbcd5738..16d9b382842 100644 Binary files a/docs/repos/git/media/my-profile-team-services-preview.png and b/docs/repos/git/media/my-profile-team-services-preview.png differ diff --git a/docs/repos/git/media/repo-health/azure-devops-repo-health-lrg.png b/docs/repos/git/media/repo-health/azure-devops-repo-health-lrg.png new file mode 100644 index 00000000000..3412c481a4a Binary files /dev/null and b/docs/repos/git/media/repo-health/azure-devops-repo-health-lrg.png differ diff --git a/docs/repos/git/media/repo-health/azure-devops-repo-health.png b/docs/repos/git/media/repo-health/azure-devops-repo-health.png new file mode 100644 index 00000000000..c828b34d8ba Binary files /dev/null and b/docs/repos/git/media/repo-health/azure-devops-repo-health.png differ diff --git a/docs/repos/git/media/repo-health/repo-health-panel-lrg.png b/docs/repos/git/media/repo-health/repo-health-panel-lrg.png new file mode 100644 index 00000000000..bf2bbe02540 Binary files /dev/null and b/docs/repos/git/media/repo-health/repo-health-panel-lrg.png differ diff --git a/docs/repos/git/media/repo-health/repo-health-panel.png b/docs/repos/git/media/repo-health/repo-health-panel.png new file mode 100644 index 00000000000..030bb49fafd Binary files /dev/null and b/docs/repos/git/media/repo-health/repo-health-panel.png differ diff --git a/docs/repos/git/media/repository-settings/organization-settings-change-default-branch-name.png b/docs/repos/git/media/repository-settings/organization-settings-change-default-branch-name.png index 122d839ebcd..24b30c10372 100644 Binary files a/docs/repos/git/media/repository-settings/organization-settings-change-default-branch-name.png and b/docs/repos/git/media/repository-settings/organization-settings-change-default-branch-name.png differ diff --git a/docs/repos/git/media/repository-settings/organization-settings-gravatar.png b/docs/repos/git/media/repository-settings/organization-settings-gravatar.png index 5f820f17f9a..cb23031d8fb 100644 Binary files a/docs/repos/git/media/repository-settings/organization-settings-gravatar.png and b/docs/repos/git/media/repository-settings/organization-settings-gravatar.png differ diff --git a/docs/repos/git/media/revoke-pat-current-view.png b/docs/repos/git/media/revoke-pat-current-view.png deleted file mode 100644 index 1ec45ae5a41..00000000000 Binary files a/docs/repos/git/media/revoke-pat-current-view.png and /dev/null differ diff --git a/docs/repos/git/media/revoke-personal-access-tokens-preview.png b/docs/repos/git/media/revoke-personal-access-tokens-preview.png index 41829b9cc6c..6082767afa4 100644 Binary files a/docs/repos/git/media/revoke-personal-access-tokens-preview.png and b/docs/repos/git/media/revoke-personal-access-tokens-preview.png differ diff --git a/docs/repos/git/media/revoke-token-confirmation-dialog-preview.png b/docs/repos/git/media/revoke-token-confirmation-dialog-preview.png index a780b6e7661..4c70f6dccca 100644 Binary files a/docs/repos/git/media/revoke-token-confirmation-dialog-preview.png and b/docs/repos/git/media/revoke-token-confirmation-dialog-preview.png differ diff --git a/docs/repos/git/media/select-edit-pat-current-view.png b/docs/repos/git/media/select-edit-pat-current-view.png index 8e523936db6..0e18df56256 100644 Binary files a/docs/repos/git/media/select-edit-pat-current-view.png and b/docs/repos/git/media/select-edit-pat-current-view.png differ diff --git a/docs/repos/git/media/select-new-token.png b/docs/repos/git/media/select-new-token.png index 13a6f1c2062..c05f510d938 100644 Binary files a/docs/repos/git/media/select-new-token.png and b/docs/repos/git/media/select-new-token.png differ diff --git a/docs/repos/git/media/select-pat-scopes-preview.png b/docs/repos/git/media/select-pat-scopes-preview.png index 0c0e7ac4b05..18d24b92826 100644 Binary files a/docs/repos/git/media/select-pat-scopes-preview.png and b/docs/repos/git/media/select-pat-scopes-preview.png differ diff --git a/docs/repos/git/media/select-personal-access-tokens.jpg b/docs/repos/git/media/select-personal-access-tokens.jpg deleted file mode 100644 index 334649db078..00000000000 Binary files a/docs/repos/git/media/select-personal-access-tokens.jpg and /dev/null differ diff --git a/docs/repos/git/media/select-personal-access-tokens.png b/docs/repos/git/media/select-personal-access-tokens.png new file mode 100644 index 00000000000..f207e98d7ce Binary files /dev/null and b/docs/repos/git/media/select-personal-access-tokens.png differ diff --git a/docs/repos/git/media/share-your-code-in-git-eclipse/push_commits_to_team_services.png b/docs/repos/git/media/share-your-code-in-git-eclipse/push_commits_to_team_services.png index a2d67355644..bf7765d7ec1 100644 Binary files a/docs/repos/git/media/share-your-code-in-git-eclipse/push_commits_to_team_services.png and b/docs/repos/git/media/share-your-code-in-git-eclipse/push_commits_to_team_services.png differ diff --git a/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/git-experience/git-details-window-lrg.png b/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/git-experience/git-details-window-lrg.png index a2cbebd45cc..540234f5967 100644 Binary files a/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/git-experience/git-details-window-lrg.png and b/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/git-experience/git-details-window-lrg.png differ diff --git a/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/git-experience/git-details-window.png b/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/git-experience/git-details-window.png index 22f305ca28a..4715bb417df 100644 Binary files a/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/git-experience/git-details-window.png and b/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/git-experience/git-details-window.png differ diff --git a/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/team-explorer/git-details-window.png b/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/team-explorer/git-details-window.png index 3bb7bb552e3..13ac4e63441 100644 Binary files a/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/team-explorer/git-details-window.png and b/docs/repos/git/media/share-your-code-in-git-vs/visual-studio-2019/team-explorer/git-details-window.png differ diff --git a/docs/repos/git/media/share-your-code-in-git-xcode/xcodeauthentication.png b/docs/repos/git/media/share-your-code-in-git-xcode/xcodeauthentication.png index c57c7ca0c7d..ca37dc04252 100644 Binary files a/docs/repos/git/media/share-your-code-in-git-xcode/xcodeauthentication.png and b/docs/repos/git/media/share-your-code-in-git-xcode/xcodeauthentication.png differ diff --git a/docs/repos/git/media/use-ssh-authentication/ssh_accessing_security_key-preview.png b/docs/repos/git/media/use-ssh-authentication/ssh_accessing_security_key-preview.png deleted file mode 100644 index 3034cc72929..00000000000 Binary files a/docs/repos/git/media/use-ssh-authentication/ssh_accessing_security_key-preview.png and /dev/null differ diff --git a/docs/repos/git/media/use-ssh-authentication/ssh_accessing_security_key.png b/docs/repos/git/media/use-ssh-authentication/ssh_accessing_security_key.png index c97e9202fc8..c8c995d529b 100644 Binary files a/docs/repos/git/media/use-ssh-authentication/ssh_accessing_security_key.png and b/docs/repos/git/media/use-ssh-authentication/ssh_accessing_security_key.png differ diff --git a/docs/repos/git/media/use-ssh-authentication/ssh_notification.png b/docs/repos/git/media/use-ssh-authentication/ssh_notification.png index b5ab4bedccb..74e68eaba1e 100644 Binary files a/docs/repos/git/media/use-ssh-authentication/ssh_notification.png and b/docs/repos/git/media/use-ssh-authentication/ssh_notification.png differ diff --git a/docs/repos/git/merging-with-squash.md b/docs/repos/git/merging-with-squash.md index df8ddbece20..d0becf572c8 100644 --- a/docs/repos/git/merging-with-squash.md +++ b/docs/repos/git/merging-with-squash.md @@ -5,7 +5,7 @@ description: Squash merge pull requests to keep a linear Git history. Learn abou ms.assetid: 2ec21de7-92fc-4d60-a5e1-7e179627b2bb ms.service: azure-devops-repos ms.topic: conceptual -ms.date: 11/05/2021 +ms.date: 09/08/2023 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- @@ -14,7 +14,7 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -When you complete a [pull request](pull-requests.md), you merge the topic branch into your default branch, usually `main`. This merge adds the commits of the topic branch to your main branch and creates a merge commit to reconcile any conflicts between the default and topic branch. The comments and discussion in the pull request give additional context for the changes made in the topic branch. +When you complete a [pull request](pull-requests.md), you merge the topic branch into your default branch, usually `main`. This merge adds the commits of the topic branch to your main branch and creates a merge commit to reconcile any conflicts between the default and topic branch. The comments and discussion in the pull request give more context for the changes made in the topic branch. ![Example of a regular merge from a pull request.](media/merging-with-squash/regular-branch-merge.png) @@ -22,9 +22,13 @@ The [commit](commits.md) history on your `main` branch (or other default branch) The default branch is an accurate representation of the history of each topic branch, but it's difficult to use to answer broader questions about your project's development. +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## Squash merge -Squash merging is a merge option that allows you to condense the Git history of topic branches when you complete a pull request. Instead of each commit on the topic branch being added to the history of the default branch, a squash merge adds all the file changes to a single new commit on the default branch. Squash merge commit doesn't have a reference to the topic branch, it will produce a **new commit**, that contains all changes from the topic branch. Furthermore it is recommended to delete the topic branch to prevent any confusion. +Squash merging is a merge option that allows you to condense the Git history of topic branches when you complete a pull request. Instead of adding each commit on the topic branch to the history of the default branch, a squash merge adds all the file changes to a single new commit on the default branch. Squash merge commit doesn't have a reference to the topic branch. It produces a **new commit** that contains all changes from the topic branch. We recommend that you delete the topic branch to prevent any confusion. ![Diagram of squash merging in pull requests in Azure Repos.](media/merging-with-squash/squash-branch-merge.png) @@ -32,13 +36,13 @@ A simple way to think about this is that squash merge gives you just the file ch ### How is a squash merge helpful? -Squash merging keeps your default branch histories clean and easy to follow without demanding any workflow changes on your team. Contributors to the topic branch work how they want in the topic branch, and the default branches keep a linear history through the use of squash merges. The commit history of a `main` branch updated with squash merges has one commit for each merged branch. You can step through this history to find out exactly when work was done. +Squash merging keeps your default branch histories clean and easy to follow without demanding any workflow changes on your team. Contributors to the topic branch work how they want in the topic branch, and the default branches keep a linear history by using squash merges. The commit history of a `main` branch updated with squash merges has one commit for each merged branch. You can step through this history to find out exactly when work was done. ### Considerations when squash merging -Squash merging condenses the history of changes in your default branch, so it's important to work with your team to decide when you should squash merge or when you want to keep the full commit history of a topic branch. When squash merging, it's a good practice to delete the source branch. Deleting the source branch prevents confusion as the topic branch itself doesn't have a commit merging it into the default branch. +Squash merging condenses the history of changes in your default branch, so it's important to work with your team to decide when to squash merge versus keeping the full commit history of a topic branch. When squash merging, it's a good practice to delete the source branch. Deleting the source branch prevents confusion as the topic branch itself doesn't have a commit merging it into the default branch. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### Complete pull requests with squash merge You can choose to squash merge when completing a pull request in Azure Repos. @@ -49,27 +53,16 @@ Choose **Squash commit** under **Merge type** in the **Complete pull request** d ::: moniker-end -::: moniker range="tfs-2018" -### Complete pull requests with squash merge - -You can choose to squash merge when completing a pull request in Azure Repos. - -Choose **Squash changes when merging** on the **Complete pull request** dialog to squash merge the topic branch. - -![Screenshot of closing a pull request with a squash merge in Azure Repos.](media/merging-with-squash/squash-merge-pr.png) - -::: moniker-end - ## Multiple merge bases -The **Files** tab in a pull request detects diffs by a three-side comparison. The algorithm takes into account the last commit in the target branch, the last commit in the source branch, and their [common merge base](https://git-scm.com/docs/git-merge-base) (i.e. the best common ancestor). The algorithm is a fast, cost-efficient, and reliable method of detecting changes. Unfortunately, in some cases, there's more than one true base. In most repositories this situation is rare, but in large repositories with many active users, it can be common. You can check your branches for a multiple merge bases manually with ```git merge-base --all feature master``` command. Also there is an automatic detection for such a cases that will notify you with message "Multiple merge bases detected. The list of commits displayed might be incomplete". +The **Files** tab in a pull request detects diffs by a three-side comparison. The algorithm takes into account the last commit in the target branch, the last commit in the source branch, and their [common merge base](https://git-scm.com/docs/git-merge-base), for example, the best common ancestor. The algorithm is a fast, cost-efficient, and reliable method of detecting changes. Unfortunately, in some cases, there's more than one true base. In most repositories this situation is rare, but in large repositories with many active users, it can be common. You can check manually if multiple merge bases between the branches exist. To do so, run ```git merge-base --all feature master``` command. Azure DevOps detects existence of multiple merge bases for every PR. When these are detected, Azure DevOps displays the message "Multiple merge bases detected. The list of commits displayed might be incomplete" for the PR. While Azure DevOps is running the detection of multiple merge bases, it doesn't check if potential merge base was already merged or not. Such check is done by ```git merge-base```. This is why Azure DevOps might display the message even when ```git merge-base``` reports only one merge base. > [!NOTE] -> In case you have lost changes during a PR review, please ensure that multiple merge bases is not the root cause. +> In case you have lost changes during a PR review, ensure that multiple merge bases aren't the root cause. -The following scenarios can cause multiple bases: +The following example scenarios get detected by Azure DevOps as multiple bases, with the merge bases indicated by numbers one and two: -- Cross-merges (also known as a criss-cross) between different branches +- Cross-merges (also known as a criss-cross) between different branches (reported by Azure DevOps and ```git merge-base```) ``` ---1---o---A \ / @@ -77,7 +70,15 @@ The following scenarios can cause multiple bases: / \ ---2---o---o---B ``` -- Handling aftermaths of main branch reverts, e.g. ammend the merge commit +- Merge of one branch to other two (reported by Azure DevOps, but not by ```git merge-base``` that eliminates the merge base 2) +``` +---1---o---o---o---A + \ / + \-------2 + \ \ + \---o---o---o---B +``` +- Handling aftermaths of main branch reverts, for example, amend the merge commit ``` * 42bb2d2 (HEAD, A) Amended merge commit |\ @@ -92,12 +93,11 @@ The following scenarios can cause multiple bases: * 6a52130 add init ``` - Active reuse of feature branches -- Other non-intuitive and convoluted manipulations with reverts, cherry picks, and merges - +- Other nonintuitive and convoluted manipulations with reverts, cherry picks, and merges Multiple merge base detection is part of security awareness. If there are multiple merge bases, the file-diff algorithm for the user interface might not properly detect file changes, depending on which merge base it chooses. If the files in the pull request have different versions between the merge bases, a multiple merge base warning occurs. -Please review [the official git documentation](https://git-scm.com/docs/git-merge-base) for more details. +Review [the official git documentation](https://git-scm.com/docs/git-merge-base) for more details. ### Potential security risks of merging from multiple bases diff --git a/docs/repos/git/merging.md b/docs/repos/git/merging.md index 2a1d5bfeb5a..a8c916660b1 100644 --- a/docs/repos/git/merging.md +++ b/docs/repos/git/merging.md @@ -21,11 +21,9 @@ You can resolve merge conflicts in Visual Studio, or by using the command line a For an overview of the Git workflow, see [Azure Repos Git tutorial](gitworkflow.md). -This article provides procedures for the following tasks: +## Prerequisites -> [!div class="checklist"] -> * Understand merge conflicts -> * Resolve merge conflicts +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] ## Understand merge conflicts diff --git a/docs/repos/git/move-git-repos-between-team-projects.md b/docs/repos/git/move-git-repos-between-team-projects.md index f816bcccd7e..5ab8d5ced3c 100644 --- a/docs/repos/git/move-git-repos-between-team-projects.md +++ b/docs/repos/git/move-git-repos-between-team-projects.md @@ -20,7 +20,9 @@ If you're planning to consolidate multiple Azure DevOps projects into one, you'r * Move or merge them? * Keep history or just the tip of the iceberg? -In this article you will learn how to move your Git repositories to another project, with full-fidelity history. +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] ## What's the scenario? diff --git a/docs/repos/git/os-compatibility.md b/docs/repos/git/os-compatibility.md index f2dd2f7796a..d6bfdadc4c5 100644 --- a/docs/repos/git/os-compatibility.md +++ b/docs/repos/git/os-compatibility.md @@ -1,7 +1,7 @@ --- -title: Cross-Platform Compatibility +title: Cross-platform compatibility titleSuffix: Azure Repos -description: How Git interacts with multiple platform filesystems +description: Learn how Git interacts with multiple platform file systems. ms.assetid: 7e02f9e9-ebb1-4d7a-aeb2-37445a6cf8c7 ms.service: azure-devops-repos ms.topic: conceptual @@ -10,111 +10,102 @@ monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- -# Git Cross-Platform Compatibility +# Git cross-platform compatibility [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The Windows, macOS, and Linux file systems each have limitations and behaviors that are not always supported by one or more of the other platforms. Since Git is a cross-platform technology, it is possible for a developer on one platform to make a commit containing files or folders that have incompatible names with another platform's file system. Protecting your repo from this is important because developers on other platforms may unknowingly checkout a commit that corrupts their working directory due to unsupported file or paths names. +The Windows, macOS, and Linux file systems have limitations and behaviors that one or more of the other platforms don't always support. Because Git is a cross-platform technology, it's possible for a developer on one platform to make a commit that contains files or folders that have incompatible names with another platform's file system. Protecting your repo from this incompatibility is important because developers on other platforms might unknowingly check out a commit that corrupts their working directories because of unsupported file or path names. -Azure Repos offers [three cross-platform compatibility settings](repository-settings.md) that help protect your repo from people pushing commits that are incompatible with one or more platforms. The three file system limitations these settings are related to are: +Azure Repos offers [three cross-platform compatibility settings](repository-settings.md) that help protect your repo from people pushing commits that are incompatible with one or more platforms. These settings are related to the following limitations with file systems: -- Case Sensitivity -- Restricted File and Folder Names -- Path Length Restrictions +- Case sensitivity +- Restrictions on file and folder names +- Path length restrictions -## Case Sensitivity +## Case sensitivity -The Windows and macOS file systems are case-insensitive (but case-preserving) by default. -Most Linux filesystems are case-sensitive. -Git was built originally to be the Linux kernel's version control system, so unsurprisingly, it's case-sensitive. +The Windows and macOS file systems are case insensitive (but case preserving) by default. +Most Linux file systems are case sensitive. +Git was built originally to be the Linux kernel's version control system, so it's case sensitive. -While many of the issues with a case-insensitive OS have been addressed in [Git for Windows](https://gitforwindows.org/), a few quirks remain. +Although [Git for Windows](https://gitforwindows.org/) addresses many of the problems with a case-insensitive operating system, a few quirks remain. ### File and folder names -On Linux, checking out a Git repo which contains both "File.txt" and "file.txt" is no problem. -Those are distinct filenames. -On Windows and macOS, checking out both files will result in the second one overwriting the first one. -If two folders differ only by case, their contents will end up mixed together on case-insensitive filesystems. +On Linux, checking out a Git repo that contains both *File.txt* and *file.txt* is no problem. +Those are distinct file names. +On Windows and macOS, checking out both files causes the second one to overwrite the first one. +If two folders differ only by case, their contents are mixed together in case-insensitive file systems. -### Fixing case conflicts +There are two ways to fix a repository that has case conflicts: -One way to fix a repository with this problem is to check it out in a case-sensitive environment. -Rename files and folders so they no longer conflict, then push those changes to the repository. +- Check out the repository in a case-sensitive environment. +Rename files and folders so they no longer conflict, and then push those changes to the repository. [Windows Subsystem for Linux](/windows/wsl/about) is one such environment. -Another approach is to use the command `git mv -f ` for each conflict, being careful to use exact capitalization on both file names. +- Use the command `git mv -f ` for each conflict. Be careful to use exact capitalization on both file names. -### Avoiding case conflicts - -It's good to avoid creating this situation in the first place. -Azure Repos offers a [case-enforcement setting](repository-settings.md) to prevent pushes which would lead to this situation. -For developers, adopting the habit of using tab-completion to commit files will also help. -Since both Windows and macOS are case-preserving, this will ensure that Git's internals see the exact same casing that the filesystem uses. +It's good to avoid creating case conflicts in the first place. +Azure Repos offers a [case-enforcement setting](repository-settings.md) to prevent pushes that would lead to this situation. +For developers, adopting the habit of using tab completion to commit files will also help. +Because both Windows and macOS are case preserving, these approaches ensure that Git's internals see exactly the same casing that the file system uses. ### Branch and tag names -You can create two branches or tags (known as 'refs') that differ only in casing. -Git's internals, as well as Azure DevOps Services/TFS, will treat them as two separate refs. -On a user's machine, Git uses the filesystem to store refs. +You can create two branches or tags (known as *refs*) that differ only in casing. +Git's internals, along with Azure DevOps Services and Azure DevOps Server, treat them as two separate refs. +On a user's machine, Git uses the file system to store refs. Fetches and other operations begin to fail because of the ambiguity. -Each ref is represented by a small file, and if a ref name contains `/` characters, the parts before the final `/` are represented by folders. -One simple way to avoid issues is to always use all-lowercase branch and tag names. -If you have already created two branches or tags with this problem, you can fix it in the Azure Repos web UI. +A small file represents each ref. If a ref name contains slash (`/`) characters, folders represent the parts before the final slash. + +One simple way to avoid problems is to always use all-lowercase branch and tag names. +If you already created two branches or tags that have this problem, you can fix them in the Azure Repos web UI. -### Fixing branch names +To fix branch names: -From the branches page, navigate to the related commit. -In the context menu, choose "New branch". -Give the branch a new name that doesn't have a case conflict. -Return to the branches page and delete the conflicting branch. +1. On the page for branches, go to the related commit. +1. On the shortcut menu, select **New branch**. +1. Give the branch a new name that doesn't have a case conflict. +1. Return to the page for branches and delete the conflicting branch. -### Fixing tag names +To fix tag names: -The steps for fixing a tag name are similar to branches. -From the tags page, navigate to the tagged commit. -In the context menu, choose "Create tag". -Give the tag a new name that doesn't have a case conflict. -Return to the tags page and delete the conflicting tag. +1. On the page for tags, go to the tagged commit. +1. On the shortcut menu, select **Create tag**. +1. Give the tag a new name that doesn't have a case conflict. +1. Return to the page for tags and delete the conflicting tag. -## Path and File Name Restrictions +## Path and file name restrictions -The Windows, macOS, and Linux operating systems each have various naming limitations and max path limits. These restrict what you can name files or folders. This can create problem situations for teams using Git across multiple platforms. +The Windows, macOS, and Linux operating systems have various limitations for file names and paths. These limitations restrict what you can name files or folders, which can create problems for teams that use Git across multiple platforms. -For example, let's say a developer on one platform commits a change to the shared repository that contains a file name or path length that is invalid on another platform. Later, another developer attempts to checkout that commit on a platform where the contents are invalid. This results in a corrupted working directory creating the potential to damage your repo with corrupted data. +For example, imagine that a developer on one platform commits a change to the shared repository that contains a file name or path length that's invalid on another platform. Later, another developer tries to check out that commit on a platform where the contents are invalid. This situation results in a corrupted working directory that has the potential to damage your repo with corrupted data. ::: moniker range="azure-devops" -Azure Repos offers file name and max path [repository settings](repository-settings.md) that block pushes containing commits that violate one or more of the below limitations. +Azure Repos offers [repository settings](repository-settings.md) that block pushes containing commits that violate one or more of the following limitations. ::: moniker-end -### File Name & Path Length Reference Table +### Reference table for file names and paths -| Restrictions / Platforms | Windows | macOS | Linux | +| Restrictions/Platforms | Windows | macOS | Linux | |--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:-----------------------------------------------------------------:| -| File Name Restrictions | [Reserved File Names](/windows/desktop/FileIO/naming-a-file): CON, PRN, AUX, NUL, COM1 - COM9, LPT1 - LPT9

      Reserved File Names followed by `.`

      Reserved Characters: `\ / : * ? " < >`

      Filenames ending in `.` or whitespace | Filenames ending in `/` | Filenames ending in `/` | -| Path Length Restrictions | [Paths in Windows](/windows/desktop/FileIO/naming-a-file#paths) have a maximum length of 260 characters (incl. a null terminator).

      For directories with .NET the fully qualified file name must be less than 260 characters, and the directory name must be less than 248 characters. | File names are limited to 255 characters

      Path max in HFS+ are documented as unlimited, though some macOS versions cap it at 1016 characters. Some file systems support 1016 as max path | File names are limited to 255 characters

      Path max is 4096 | +| File name restrictions | [Reserved file names](/windows/desktop/FileIO/naming-a-file): CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9

      Reserved file names followed by `.`

      Reserved characters: `\ / : * ? " < >`

      File names that end in `.` or whitespace | File names that end in `/` | File names that end in `/` | +| Path length restrictions | [Paths in Windows](/windows/desktop/FileIO/naming-a-file#paths) have a maximum length of 260 characters (including a null terminator).

      For directories with .NET, the fully qualified file name must be fewer than 260 characters, and the directory name must be fewer than 248 characters. | File names are limited to 255 characters.

      Path maximums in HFS+ are documented as unlimited, though some macOS versions cap paths at 1,016 characters. Some file systems support 1,016 as the path maximum. | File names are limited to 255 characters.

      Path maximum is 4096. | -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" ## Encoding support ::: moniker-end -::: moniker range="azure-devops-2019" - -> [!NOTE] -> The encoding support described in this section is supported in Azure DevOps Server 2019.1 and higher. - -::: moniker-end - -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" -Microsoft has added support for UTF-16 and UTF-32 encoding via the web pushes endpoint. This means that we will preserve the encoding type so you don't have to rewrite your files as UTF-8. You will also see a warning when you try to save a file that is not UTF encoded via the web (which only supports UTF encoding). +Microsoft added support for UTF-16 and UTF-32 encoding via the web push endpoint. This support means that we preserve the encoding type, so you don't have to rewrite your files as UTF-8. You also see a warning when you try to save a file that's not UTF encoded via the web (which supports only UTF encoding). -The following screenshot shows an example of the dialog that you see when you introduce encoding changes by a web push. +The following screenshot shows an example of the dialog that appears when you introduce encoding changes by using a web push. -:::image type="content" source="media/os-compatibility/web-push-encoding-dialog.png" alt-text="{Screenshot that shows the dialog when you introduce encoding changes by a web push.}"::: +:::image type="content" source="media/os-compatibility/web-push-encoding-dialog.png" alt-text="Screenshot that shows the dialog about introducing encoding changes through a web push."::: ::: moniker-end diff --git a/docs/repos/git/perform-migration-from-svn-to-git.md b/docs/repos/git/perform-migration-from-svn-to-git.md index 8b6d9a5e080..f59fbd674b6 100644 --- a/docs/repos/git/perform-migration-from-svn-to-git.md +++ b/docs/repos/git/perform-migration-from-svn-to-git.md @@ -27,8 +27,11 @@ It's likely going to be complex if: There are several ways to migrate from SVN to Git. The approach outlined in this article is based on using [git-svn](https://git-scm.com/docs/git-svn), a Git extension, which can be used to check out a Subversion repository to a local Git repository and then push changes from the local Git repository back to the Subversion repository. These steps give a detailed overview of the process for migrating from SVN to Git in a Windows environment, without synchronizing back to the original SVN repository. The result will be a bare Git repository for sharing with the rest of your team. +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + > [!NOTE] -> > Before you try to migrate your source code from a centralized version control system to Git, be sure that you familiarize yourself with the differences between centralized and distributed version control systems, and [plan your team's migration](/devops/develop/git/centralized-to-git). After you've prepared, you can begin the migration. The high-level workflow for migrating from SVN to Git is as follows: @@ -48,12 +51,12 @@ Configure a migration environment on a local workstation and install the followi * [Subversion](https://subversion.apache.org/packages.html) * [git-svn utility](https://www.kernel.org/pub/software/scm/git/docs/git-svn.html) (already part of Git) -You will also need to create a Git repository for your organization to host the converted SVN repository, you may follow [Create a new Git repo in your project +You'll also need to create a Git repository for your organization to host the converted SVN repository, you may follow [Create a new Git repo in your project ](./create-new-repo.md) ## Convert the source SVN repository to a local Git repository -The goal of this step is to convert the source Subversion repository to a local *bare* Git repository. A *bare* Git repository does not have a local working checkout of files that can be changed, instead it only contains the repository's history and the metadata about the repository itself. This is the recommended format for sharing a Git repository via a remote repository hosted on a service like Azure Repos. +The goal of this step is to convert the source Subversion repository to a local *bare* Git repository. A *bare* Git repository doesn't have a local working checkout of files that can be changed, instead it only contains the repository's history and the metadata about the repository itself. This is the recommended format for sharing a Git repository via a remote repository hosted on a service like Azure Repos. > [!TIP] > @@ -75,11 +78,19 @@ Subversion just uses the username for each commit, while Git stores both a real To extract a list of all SVN users from the root of your local Subversion checkout, run this PowerShell command: +For results in `utf8NoBOM` encoding, run the following command: + +```powershell +svn.exe log --quiet | ? { $_ -notlike '-*' } | % { "{0} = {0} " -f ($_ -split ' | ')[1] } | Select-Object -Unique | Sort-Object | Out-File 'authors-transform.txt' -Encoding utf8NoBOM ``` -svn.exe log --quiet | ? { $_ -notlike '-*' } | % { "{0} = {0} <{0}>" -f ($_ -split ' \| ')[1] } | Select-Object -Unique | Sort-Object | Out-File 'authors-transform.txt' -Encoding utf8 + +For results in `ASCII` encoding, run the following command: + +```powershell +svn.exe log --quiet | ? { $_ -notlike '-*' } | % { "{0} = {0} " -f ($_ -split ' | ')[1] } | Select-Object -Unique | Sort-Object | Out-File 'authors-transform.txt' -Encoding ASCII ``` -This command will retrieve all the log messages, extract the usernames, eliminate any duplicate usernames, sort the usernames, and place them into an **authors-transform.txt** file in UTF-8 format. You can then edit each line in the file to create a mapping of SVN users to well-formatted Git users. For example, you can map `jamal = jamal ` to `jamal = Jamal Hartnett `. +This command will retrieve all the log messages, extract the usernames, eliminate any duplicate usernames, sort the usernames, and place them into an **authors-transform.txt** file in UTF-8 format (or ASCII format, depending on which encoding you specified). You can then edit each line in the file to create a mapping of SVN users to well-formatted Git users. For example, you can map `jamal = jamal ` to `jamal = Jamal Hartnett `. ### Clone the Subversion repository using git-svn @@ -95,7 +106,7 @@ git svn clone ["SVN repo URL"] --prefix=svn/ --no-metadata --authors-file "autho > > Setting a prefix is also useful if you wish to track multiple projects that share a common repository. By default, the prefix is set to `origin/`. -If you are using the standard trunk, branches, tags layout you'll just put `--stdlayout`. However, if you have something different you may have to pass the `--trunk`, `--branches`, and `--tags` to find what is what. For example, if your repository structure was `trunk/companydir` and you branched that instead of trunk, you would probably want `--trunk=trunk/companydir --branches=branches`. +If you're using the standard trunk, branches, tags layout you'll just put `--stdlayout`. However, if you have something different you may have to pass the `--trunk`, `--branches`, and `--tags` to find what is what. For example, if your repository structure was `trunk/companydir` and you branched that instead of trunk, you would probably want `--trunk=trunk/companydir --branches=branches`. ``` git svn clone ["SVN repo URL"] --prefix=svn/ --no-metadata --trunk=/trunk --branches=/branches --tags=/tags --authors-file "authors-transform.txt" c:\mytempdir @@ -103,7 +114,7 @@ git svn clone ["SVN repo URL"] --prefix=svn/ --no-metadata --trunk=/trunk --bran > [!NOTE] > -> This command can take a few minutes to several hours depending on the size of the SVN repository. Upon completion, you will have a Git checkout of your repository. +> This command can take a few minutes to several hours depending on the size of the SVN repository. Upon completion, you'll have a Git checkout of your repository. ### Convert version control-specific configurations @@ -120,7 +131,7 @@ git commit -m 'Convert svn:ignore properties to .gitignore.' ### Push repository to a bare git repository -In this step, you will create a bare repository and make its default branch match SVN's trunk branch name. +In this step, you'll create a bare repository and make its default branch match SVN's trunk branch name. 1. Create a bare Git repository @@ -173,7 +184,7 @@ git for-each-ref --format='%(refname)' refs/remotes | % { $_.Replace('refs/remot ``` > [!NOTE] > -> This command can take a few minutes to several hours depending on the size of the SVN repository. Upon completion, you will have a Git checkout of your repository. +> This command can take a few minutes to several hours depending on the size of the SVN repository. Upon completion, you'll have a Git checkout of your repository. ### Migrate only specific revisions @@ -203,6 +214,6 @@ provided "as-is." Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.* -*This document does not provide you with any legal rights to any +*This document doesn't provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.* diff --git a/docs/repos/git/pr-status-policy.md b/docs/repos/git/pr-status-policy.md index 99ec60f9d48..a68c73d3128 100644 --- a/docs/repos/git/pr-status-policy.md +++ b/docs/repos/git/pr-status-policy.md @@ -21,8 +21,7 @@ Branch policies are a powerful feature to ensure high quality code in your repo ## Prerequisites -* An organization in Azure DevOps with a Git repo. If you don't have an organization, [sign up](../../organizations/accounts/create-organization.md) to upload and share code in free unlimited private Git repositories. -* A service that posts status to PRs. See [Create a pull request status server](./create-pr-status-server.md). +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] ## Configure the branch policy diff --git a/docs/repos/git/pull-request-notifications.md b/docs/repos/git/pull-request-notifications.md index 82ac7bf07dd..ba694e9598a 100644 --- a/docs/repos/git/pull-request-notifications.md +++ b/docs/repos/git/pull-request-notifications.md @@ -19,7 +19,7 @@ You can subscribe to email alerts to be notified of changes in pull requests (PR To view or set your personal notifications, see [Manage your personal notifications](../../organizations/notifications/manage-your-personal-notifications.md). -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" - To view project notification settings, [go to the project](../../project/navigation/go-to-project-repo.md) and select **Project settings** > **Notifications**. @@ -39,23 +39,3 @@ To view or set your personal notifications, see [Manage your personal notificati ::: moniker-end -::: moniker range="tfs-2018" - -Select the settings button while you have your project open to bring up the project administration page. - -![Screenshot that shows Open up the administrative area of the web portal for your project.](media/pull-requests/gear_icon_settings.png) - -- Select the **Notifications** tab to view your notification settings, and choose **New subscription** to subscribe to more notifications. - - ![Screenshot that shows Subscribe to emails.](media/pull-request-notifications/pr-notifications.png) - -- To edit a notification, select **...** for the notification and choose **View** to edit the subscription. - - ![Screenshot that shows Change subscription.](media/pull-request-notifications/view-pr-notifications.png) - -- To opt-out of a notification, set the **State** to **Off**. - - ![Screenshot that shows Opt out of emails.](media/pull-request-notifications/opt-out-notifications.png) - -::: moniker-end - diff --git a/docs/repos/git/pull-request-status.md b/docs/repos/git/pull-request-status.md index 7bd03af7198..66ec9ea5c72 100644 --- a/docs/repos/git/pull-request-status.md +++ b/docs/repos/git/pull-request-status.md @@ -10,7 +10,6 @@ monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- - # Customize and extend pull request workflows with pull request status [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -19,7 +18,9 @@ ms.subservice: azure-devops-repos-git [Branch policies](branch-policies.md) enforce code quality during the pull request process by establishing requirements that must be performed for every code change. These policies enable teams to enforce many best practices related to reviewing code and running automated builds, but many teams have additional requirements and validations to perform on code. To cover these individual and custom needs, Azure Repos offers pull request statuses. Pull request statuses integrate into the PR workflow and allow external services to programmatically sign off on a code change by associating simple success/failure type information with a pull request. Optionally, pull requests can be blocked until the external service approves the change. -[!INCLUDE [note-tfs-2018.2-update](includes/note-tfs-2018.2-update.md)] +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] Integrating into the PR workflow involves a few different concepts: @@ -86,10 +87,15 @@ When the source branch in a PR changes, a new "iteration" is created to track th Services that evaluate code changes will want to post new status on each iteration of a PR. Posting status to a specific iteration of a PR guarantees that status applies only to the code that was evaluated and none of the future updates. +::: moniker range="<=azure-devops" +> [!NOTE] +> If the PR being created contains more than 100,000 modified files, then, for performance and stability reasons, that PR won't support iterations. This means any additional change to such PR will be included but no new iteration will be created for that change. In addition any attempt to create a status for a non-existent iteration will return an error. +::: moniker-end + Conversely, if the status posted applies to the entire PR, independent of the code, posting to the iteration may be unnecessary. For example, checking that the author (an immutable PR property) belongs to a specific group would only need to be evaluated once, and iteration status would not be needed. When configuring the status policy, if iteration status is being used, the **Reset conditions** should be set to **Reset status whenever there are new changes**. -This further guarantees that the PR will not be able to be merged until the latest iteration has a status of `succeeded`. +This further guarantees that the PR won't be able to be merged until the latest iteration has a status of `succeeded`. ![Status policy reset conditions](media/pull-request-status/pull-request-status-policy-reset-conditions.png) @@ -99,10 +105,10 @@ See the REST API examples for posting status [on an iteration](/rest/api/azure/d Using status alone, details from an external service can be provided to users within the PR experience. Sometimes, sharing information about a PR is all that is necessary, but in other cases PRs should be blocked from merging until requirements are met. -Like the in-box policies, the **Status policy** provides a way for external services to block PR completion until requirements are met. If the policy is required, it must pass in order to complete the pull request. If the policy is optional, it is informational only, and a status of `succeeded` is not required in order to complete the pull request. +Like the in-box policies, the **Status policy** provides a way for external services to block PR completion until requirements are met. If the policy is required, it must pass in order to complete the pull request. If the policy is optional, it's informational only, and a status of `succeeded` isn't required in order to complete the pull request. Status policies are configured just like other [branch policies](branch-policies.md). -When adding a new status policy, the **name** and **genre** of the status policy must be entered. If the status has been posted previously you can pick it from the list; if it is a new policy you can type in the name of the policy in the format **genre**/**name**. +When adding a new status policy, the **name** and **genre** of the status policy must be entered. If the status has been posted previously you can pick it from the list; if it's a new policy you can type in the name of the policy in the format **genre**/**name**. ![Status policy](media/pull-request-status/pull-request-status-policy.png) @@ -116,7 +122,7 @@ The **Policy applicability** options determine whether this policy applies as so ![Policy applicability](media/pull-request-status/policy-applicability.png) -1. **Apply by default** - The policy applies as soon as the pull request is created. With this option, the policy does not pass after pull request creation until a `succeeded` status is posted. +1. **Apply by default** - The policy applies as soon as the pull request is created. With this option, the policy doesn't pass after pull request creation until a `succeeded` status is posted. A PR can be marked exempt from the policy by posting a status of `notApplicable`, which will remove the policy requirement. 2. **Conditional** - The policy doesn't apply until the first status is posted to the pull request. @@ -124,11 +130,11 @@ A PR can be marked exempt from the policy by posting a status of `notApplicable` Together, these options can be used to create a suite of dynamic policies. A top-level "orchestration" policy could be set to apply by default while the PR is being evaluated for applicable policies. Then, as additional conditional policies are determined to apply (perhaps based on specific build output), status can be posted to make them required. -This orchestration policy could be marked `succeeded` when it is finished evaluating or could be marked `notApplicable` to indicate to the PR that the policy doesn't apply. +This orchestration policy could be marked `succeeded` when it's finished evaluating or could be marked `notApplicable` to indicate to the PR that the policy doesn't apply. ## Custom actions -In addition to predefined service hook events that can trigger the service to update PR status, it is possible to extend the status menu by using [Azure DevOps Services extensions](../../extend/overview.md) to give trigger actions to the end user. For example, if status corresponds to a test run that can be restarted by the end user, it is possible to have a **Restart** menu item to the status menu that would trigger tests to run. To add a status menu, you'll need to use the [contribution model](../../extend/develop/contributions-overview.md). For more information, see the [Azure DevOps extension sample](https://github.com/Microsoft/azure-devops-extension-sample). +In addition to predefined service hook events that can trigger the service to update PR status, it's possible to extend the status menu by using [Azure DevOps Services extensions](../../extend/overview.md) to give trigger actions to the end user. For example, if status corresponds to a test run that can be restarted by the end user, it's possible to have a **Restart** menu item to the status menu that would trigger tests to run. To add a status menu, you'll need to use the [contribution model](../../extend/develop/contributions-overview.md). For more information, see the [Azure DevOps extension sample](https://github.com/Microsoft/azure-devops-extension-sample). ![Status menu](media/pull-request-status/custom-status-menu-entries.png) diff --git a/docs/repos/git/pull-request-targets.md b/docs/repos/git/pull-request-targets.md new file mode 100644 index 00000000000..e738654877f --- /dev/null +++ b/docs/repos/git/pull-request-targets.md @@ -0,0 +1,251 @@ +--- +title: Configure custom target branches for pull requests +titleSuffix: Azure Repos +description: Learn how to specify a list of branches as potential pull request targets. +ms.assetid: 1D70C33E-FFBB-44B2-82A6-CE9BF8169BE7 +ms.service: azure-devops-repos +ms.topic: conceptual +ms.author: dstolee +author: dstolee +ms.date: 08/19/2024 +monikerRange: '<= azure-devops' +ms.subservice: azure-devops-repos-git +ms.custom: devx-track-azurecli +--- + +# Configure target branches for pull requests + +[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] + +By default, Azure DevOps suggests the creation of new pull requests against +the default branch. In a repository with multiple branches used for pull +requests, repository owners may configure the list of pull request target +branches so these suggestions select the proper target branch. + +To enable this feature, create a file with name +`.azuredevops/pull_request_targets.yml` in the repository's default branch. +This YAML file should contain a single list, titled `pull_request_targets`, +containing the branch names or prefixes that match the candidate branches. + +For example, consider these contents: + +``` +pull_request_targets: + - main + - release/* + - feature/* +``` + +This list of potential targets specifies `main` as the target branch to +select first, but if a branch starting with `release/` or `feature/` is a +better choice, then that branch is chosen instead. + +For more pull request guidelines and management considerations, see +[About pull requests](about-pull-requests.md). + +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + +## When is this configuration used? + +There are multiple entry points to using a dynamic target branch. + +- **Pull Request Suggestions.** When a user pushes a branch to Azure + DevOps, their next visit to the Repos page may suggest creating a pull + request from that branch. This "Create New Pull Request" button chooses + the target branch dynamically. + +- **Pull Request URL.** When a user navigates directly to the pull + request creation page using a `sourceRef` parameter but omitting the + `targetRef` parameter, Azure DevOps selects a target branch based on + this dynamic choice. + +There's a capability for client tools to create pull requests using this +dynamic choice, but those clients need to add an optional signal that the +user didn't specify a target branch. Check your client tool of choice to +see if the option is enabled. + +## What are good candidates for branch targets? + +We recommend that the configured list of candidate branches includes only +branches that are protected by pull request policies. Such branches are +likely only changed by completing pull requests, which guarantees that the +previous branch position is in the first-parent history of the tip commit. +If a merge strategy is used, then the second parent represents the commits +being introduced to the target branch by completing a pull request and the +first parent is the previous tip. + +## How does Azure DevOps pick a branch? + +Git doesn't track metadata around the creation of a branch. There's no +exact way to determine what branch was used when creating a topic branch. +Instead, Azure DevOps uses a heuristic based on the first-parent history of the +branches. + +Among the possible target branches, Azure DevOps selects the branch whose +first-parent history intersects with the source branch's first-parent history +the most. + +### Example: No merge commits + +Consider the following branch structure, which is simplified more than normal as +there are no merge commits. In this example, the entire history is represented by +the first-parent history. + +``` + ,-E---F <-- release/2024-September + / +A---B---C---D <--- main + \ + `-G---H <--- feature/targets + \ + `-I <--- topic +``` + +With this history and the sample `pull_request_targets` list used +previously, we have three candidate target branches, in order of priority: + +* `main` +* `release/2024-September` +* `feature/targets` + +The source branch, `topic`, is then compared to these branches. + +* `main` intersects with `topic` at `B`, leaving `G,I` in `topic` and not in + `main`. +* `release/2024-September` intersects with `topic` at `A` leaving `B,G,I` in + `topic` and not in `release/2024-September`. +* `feature/targets` intersects with `topic` at `G`, leaving `I` in `topic` and + not in `feature/targets`. + +Therefore, in this example, the `feature/targets` branch is chosen as the target +branch for a pull request with `topic` as the source branch. + +### Example: Merge commits + +In a more complicated example, where the `feature/targets` branch was merged +into `main` and merged `main` into itself, the commit history has more cases to +consider: + +``` + ,-E---F <-- release/2024-September + / +A---B---C---D---J---K <--- main + \ _/ \ + \ / \ + `G---H---L--\--M <--- feature/targets + \ \/ + \ + `I <--- topic +``` + +Here, the commit `D` in `main` represents a time where `feature/targets` was +merged into `main`. Commit `M` represents a time where `main` was merged into +`feature/targets`. The link between commits `M` and `J` is drawn in a way to +emphasize that `J` is the second parent of `M` while `L` is the first parent. + +In this case, when you consider the full commit history, `main` and +`feature/targets` both intersect the history of `topic` at `G`. However, the +first parent history still demonstrates a preference for `feature/targets`. + +### Breaking Ties + +If two branches have the same first-parent history intersection, then +Azure Devops selects the branch that appears earlier in the +`pull_request_targets` list. If multiple branches are still tied based on +the `pull_request_targets` list due to a prefix match, then the earliest +in alphabetical order wins. + +These kinds of ties are most often present when new candidate branches are +created, such as the start of a new feature branch or the fork of a release +branch. + +``` + ,-E---F <-- release/2024-October + / +A---B---C---D <--- main + \ + \ + `G <--- topic +``` + +In this example, the `release/2024-October` branch was created off of the +`main` branch after `topic` was branched off of `main`. While this is intuitive +to a human reader, the order of the `main` and `release/*` categories in the +`pull_request_targets` list indicates the preferred order to Azure DevOps. + +## What if Azure DevOps chooses the wrong target branch? + +The pull request creation page has a selector for adjusting the target +branch if the dynamic choice does not match expectations. The target +branch can also be adjusted after the pull request is created. + +More importantly, it may be valuable to understand why the heuristic may be +selecting the "wrong" target branch. + +This heuristic relies on some assumptions about how the target branches and the +source branch were created. Here are some potential reasons why the heuristic +does not work: + +- The target branches are not protected by pull request policies. If the target + branches can be pushed arbitrarily, then the first-parent history is not a + reliable indicator of the previous location of that branch. + +- The source branch was created from a previous tip of a candidate branch. If + the source branch chose an arbitrary commit in the history, then there's no + guarantee about the first parent history it depended upon. + +- The source branch was advanced using `git commit` and `git merge` commands. + Commands such as `git reset --hard` or `git rebase` may change the history of + the branch in unpredictable ways. + +If you disagree with the target branch chosen by this heuristic, then +consider updating the choice using +`git rebase --onto `. The `git rebase` command +rewrites the first-parent history to make the heuristic choose the new +target. + +One common mistake that users make when realizing that they're based on the +wrong branch is to use `git merge` to bring the right branch into their history. +Merging doesn't change the first-parent history, and thus doesn't change the +choice for target branch. + +## How can I test this decision locally? + +The heuristic used by Azure DevOps was contributed to the core Git client and is +available in Git versions 2.47.0 and later. + +To test this logic in your own repository, first run `git fetch origin` to make +sure you have the latest version of the target branches. Then, run the following +`git for-each-ref` command, adjusted to match your list of candidate branches: + +``` +$ git for-each-ref --format="%(is-base:HEAD) %(refname)" \ + refs/remotes/origin/main \ + "refs/remotes/origin/release/*" \ + "refs/remotes/origin/feature/*" + refs/remotes/origin/main + refs/remotes/origin/release/2024-September +(HEAD) refs/remotes/origin/feature/targets +``` + +In this command, the `HEAD` commit is used as the source and compares the +first-parent history of the target branches in the same way. While each +candidate branch is listed in the output, the string `(HEAD)` indicates which of +the branches should be used as the target branch. + +## Next steps + +> [!div class="nextstepaction"] +> [Create a pull request](pull-requests.md) +> [Review pull requests](review-pull-requests.md) + +## Related articles + +- [Change the default branch](change-default-branch.md) +- [Create pull requests](pull-requests.md) +- [View pull requests](view-pull-requests.md) +- [Review pull requests](review-pull-requests.md) +- [Complete pull requests](complete-pull-requests.md) +- [Multiple merge bases](merging-with-squash.md#multiple-merge-bases) diff --git a/docs/repos/git/pull-request-templates.md b/docs/repos/git/pull-request-templates.md index bb9886f3ba8..80c0188527e 100644 --- a/docs/repos/git/pull-request-templates.md +++ b/docs/repos/git/pull-request-templates.md @@ -8,7 +8,7 @@ ms.topic: conceptual ms.author: vijayma author: vijayma ms.date: 12/10/2018 -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.subservice: azure-devops-repos-git --- @@ -23,6 +23,10 @@ This article shows you how to get started with pull request templates. >[!NOTE] >Pull request templates can provide guidance, but are advisory only. Use branch policies to enforce best practices such as requiring pull requests for key branches like main, requiring a successful build, and enforcing required reviewers. For more information, see [branch policies](branch-policies-overview.md). +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## What is a pull request template? A pull request template is a file containing [Markdown](../../project/wiki/markdown-guidance.md) text that is added to your pull request description when the pull request is created. diff --git a/docs/repos/git/pull-requests.md b/docs/repos/git/pull-requests.md index 0c12ce0f45d..714a5dc9858 100644 --- a/docs/repos/git/pull-requests.md +++ b/docs/repos/git/pull-requests.md @@ -7,9 +7,10 @@ ms.service: azure-devops-repos ms.topic: conceptual ms.author: vijayma author: vijayma -ms.date: 03/31/2022 +ms.date: 02/15/2025 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git +ms.custom: devx-track-azurecli --- # Create pull requests @@ -24,38 +25,28 @@ For PR guidelines and management considerations, see [About pull requests](about ## Prerequisites ::: moniker range="azure-devops" -- **Repos** must be enabled on your project. If the **Repos** hub and associated pages don't display, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md) to reenable Repos. -- To view or review PRs, you must be a member of an Azure DevOps project with **Basic** access or higher. - - If you don't have a project, create one or [sign up for free](../../user-guide/sign-up-invite-teammates.md). - - If you aren't a project member, [get added](../../organizations/accounts/add-organization-users.md). -- To contribute to a PR, you must be a member of the **Readers** security group or have the corresponding permissions. -- To create and complete a PR, you must be a member of the **Contributors** security group or have the corresponding permissions. - - > [!NOTE] - > For public projects, users granted **Stakeholder** access have full access to Azure Repos. -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" -- **Repos** must be enabled on your project. If the **Repos** hub and associated pages don't display, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md) to reenable Repos. -- To view or review PRs, you must be a member of the Azure DevOps project with **Basic** access or higher. If you aren't a project member, [get added](../../organizations/security/add-users-team-project.md). -- To create and complete a PR, you must be a member of the **Contributors** security group, or have the corresponding permissions, in the project you want to change. -- To contribute to a PR, you must be a member of the **Readers** security group or have the corresponding permissions. -::: moniker-end -::: moniker range="< azure-devops-2019" -- To create and complete a PR, you must be a member of the **Contributors** security group or have the corresponding permissions. -- To view or review PRs, you must be a member of an Azure DevOps project with **Basic** access or higher. If you aren't a project member, [get added](../../organizations/security/add-users-team-project.md). -- To contribute to a PR, you must be a member of the **Readers** security group or have the corresponding permissions. +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - View or review PRs: At least **Basic access**. For public projects, users **Stakeholder access** have full access to Azure Repos. | +| **Permissions** | - Contribute to a PR: Member of the **Readers** security group or corresponding permissions.
      - Create and complete a PR: Member of the **Contributors** security group or corresponding permissions. | +| **Services** |[Repos enabled](../../organizations/settings/set-services.md). | +| **Tools** | [Azure DevOps CLI](../../cli/index.md). | ::: moniker-end -- To learn more about permissions and access, see [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) and [About access levels](../../organizations/security/access-levels.md). +::: moniker range="- Create and complete a PR: Member of the **Contributors** security group or corresponding permissions. | +| **Services** |[Repos enabled](../../organizations/settings/set-services.md). | ::: moniker-end +For more information about permissions and access, see [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) and [About access levels](../../organizations/security/access-levels.md). + ## Create a pull request @@ -91,7 +82,7 @@ You can create PRs for any branch from your project's **Pull requests** page on ### Create a PR from a pushed branch -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" After you push or update a feature branch, Azure Repos displays a prompt to create a PR. @@ -107,26 +98,14 @@ Select **Create a pull request** to go to a page where you can [enter your PR de ::: moniker-end -::: moniker range="tfs-2018" - -After you push or update a feature branch, Azure Repos prompts you to create a PR in the **Code** view on the web. This prompt is displayed on **Pull Requests** and **Files**. - -![Screenshot that shows the prompt to create a P R on the Pull Requests tab in Azure Repos.](media/pull-requests/create-pr-from-push.png) - -![Screenshot that shows the prompt to create a P R on the Files tab in Azure Repos.](media/pull-requests/create-pr-from-push-files-tab.png) - -Select **Create a pull request** to go to a page where you can [enter your PR details](pull-requests.md#finish) and create the PR. - -::: moniker-end - ### Create a PR from a linked work item You can create a PR directly from an Azure Boards work item linked to the branch. -1. In Azure Boards, from **Backlogs** or **Queries** in the **Work** view, open a work item that's linked to the branch. -1. In the **Development** area of the work item, select **Create a pull request**. +1. In Azure Boards, from **Backlogs** or **Queries** in the **Work** view, open a work item linked to the branch. +2. In the **Development** area of the work item, select **Create a pull request**. ![Screenshot of creating a PR from the Development area of a work item with a linked branch.](media/pull-requests/create-pr-from-work-item.png) @@ -166,10 +145,9 @@ You can also create PRs from the **Branches** view in Team Explorer by right-cli ![Screenshot of initiating a P R from the Branches view.](media/pull-requests/new-pr-from-branch.png) - # [Azure DevOps CLI](#tab/azure-devops-cli) - + ::: moniker range="azure-devops" To create a new PR in your project, use [az repos pr create](/cli/azure/repos/pr#az-repos-pr-create). To open the PR in your browser after creation, use the `--open` parameter. @@ -213,7 +191,7 @@ az repos pr create [--auto-complete {false, true}] |`--org --organization`|Azure DevOps organization URL. You can configure the default organization using `az devops configure -d organization=ORG_URL`. Required if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`.| |`--project -p`|Name or ID of the project. You can configure the default project using `az devops configure -d project=NAME_OR_ID`. Required if not configured as default or picked up via git config.| |`--repository -r`|Name or ID of the repository to create the pull request in. Required parameter.| -|`--reviewers`|Additional users or groups to include as reviewers on the new pull request. Space separated.| +|`--reviewers`|Other users or groups to include as reviewers on the new pull request. Space separated.| |`--source-branch -s`|Name of the source branch. Example: `"dev"`.| |`--squash`|Squash the commits in the source branch when merging into the target branch. Accepted values: `false`, `true`.| |`--subscription`|Name or ID of the Azure subscription. You can configure the default subscription by using `az account set -s NAME_OR_ID`.| @@ -242,7 +220,6 @@ You can add many other PR details at or after PR creation. To add details, revie *** - ## Add updates with cherry-pick You can copy commits from one branch to another by using cherry-pick. Unlike a merge or rebase, cherry-pick only brings the changes from the commits you select, instead of all the changes in a branch. @@ -255,7 +232,7 @@ Before the first time you save a PR, you can switch the source and target branch ![Screenshot of the switch source and target branches icon.](media/pull-requests/switch-branches.png) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Use pull request templates @@ -269,7 +246,7 @@ If your repo has a default template, all PRs in the repo have the default templa -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ## Create draft PRs @@ -286,23 +263,17 @@ Draft PRs have the following differences from published PRs: ::: moniker-end -::: moniker range="azure-devops-2019" -> [!NOTE] -> Creating draft PRs requires Azure DevOps Server 2019.1 update or later version. -::: moniker-end - - # [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -To create a draft PR, select the arrow next to **Create** and select **Create as draft** when creating the PR. You don't have to use title prefixes such as WIP or DO NOT MERGE. +To create a draft PR, select the arrow next to **Create** and select **Create as draft** when creating the PR. You don't have to use title prefixes such as `WIP` or `DO NOT MERGE`. -![Screenshot showing Create as draft P R.](media/pull-requests/create-draft-pr.png) +![Screenshot showing Create as draft PR.](media/pull-requests/create-draft-pr.png) When you're ready to have the PR reviewed and completed, select **Publish** at upper right in the PR. Publishing a PR assigns required reviewers, evaluates policies, and kicks off voting. -![Screenshot showing Publish for a P R.](media/pull-requests/publish-pr.png) +![Screenshot showing Publish for a PR.](media/pull-requests/publish-pr.png) To change an existing published PR to a draft, choose **Mark as draft**. Marking a PR as draft removes all existing votes. @@ -310,18 +281,12 @@ To change an existing published PR to a draft, choose **Mark as draft**. Marking ::: moniker-end -::: moniker range="< azure-devops-2019" -> [!NOTE] -> This feature requires Azure DevOps Server 2019.1 update or later version. -::: moniker-end - - # [Visual Studio](#tab/visual-studio) To set a PR to draft, open the PR and select **Mark as draft**. - To open a pull request from Visual Studio, in the **Git** menu, select **\** > **View Pull Requests**, and select a pull request to open it. -- To open a pull request from Visual Studio Team Explorer, from the **Pull Requests** view, right-click the PR and select **Open in browser**. +- To open a pull request from Visual Studio Team Explorer, from the **Pull Requests** view, right-click on the PR and select **Open in browser**. # [Azure DevOps CLI](#tab/azure-devops-cli) @@ -345,7 +310,6 @@ To remove draft status from a PR, set `--draft` to `false`. *** - @@ -363,7 +327,7 @@ When you're ready to have your changes reviewed, select **Create** to create the :::moniker-end -:::moniker range="<= azure-devops-2020" +:::moniker range="=azure-devops-2020" :::image type="content" source="media/pull-requests/add-detail-to-pr.png" alt-text="Adding details to a new P R."::: @@ -381,7 +345,6 @@ Edit the PR description by selecting the **Edit** icon in the **Description** se :::image type="content" source="media/pull-requests/pull-request-edit-title-description-2020.png" alt-text="Screenshot that shows editing the P R title and selecting the description Edit button."::: - # [Visual Studio](#tab/visual-studio) When you create a PR in Visual Studio, enter a title and detailed description of your changes so others can see what problems the changes solve. Keep these fields up to date so reviewers can understand the changes in the PR. @@ -391,7 +354,7 @@ To edit the title, description, or any other details in an existing PR, open the # [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" - + You can add details during PR creation with [az repos pr create](/cli/azure/repos/pr#az-repos-pr-create), or update details in existing PRs with [az repos pr update](/cli/azure/repos/pr#az-repos-pr-update). @@ -411,42 +374,39 @@ For example, to update the title and description for PR #21, use: az repos pr update --id 21 --description "These updates are *no longer new*." --title "Old updates" ``` - ::: moniker-end [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] *** - - ## Add reviewers to a pull request # [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -You can add reviewers in the **Reviewers** section of a new or existing PR. You can also make existing optional reviewers required, or change required reviewers to optional or remove them, unless they're required by policy. +You can add reviewers in the **Reviewers** section of a new or existing PR. You can also change optional reviewers to required, change required reviewers to optional, or remove them, unless they're required by policy. -Branch policies can [require a minimum number of reviewers](branch-policies.md#require-a-minimum-number-of-reviewers), or automatically include certain optional or required reviewers in PRs. You can't remove reviewers that are required by branch policy. You can change branch policy optional reviewers to be required, or remove them. +Branch policies can [require a minimum number of reviewers](branch-policies.md#require-a-minimum-number-of-reviewers) or automatically include certain optional or required reviewers in PRs. You can't remove reviewers required by branch policy, but you can change optional reviewers to required or remove them. -To see the branch policy that automatically added a reviewer, in the **Reviewers** section of the PR **Overview** page, right-click **More options** next to the reviewer. +To see the branch policy that automatically added a reviewer, right-select **More options** next to the reviewer in the **Reviewers** section of the PR **Overview** page. ![Screenshot that shows View policy on a reviewer that's automatically included by branch policy.](media/pull-requests/view-policy.png) -If the user or group you want to review your PR isn't a member of your project, you need to [add them to the project](../../organizations/security/add-users-team-project.md) before you can add them as reviewers. +If the user or group you want to review your PR isn't a member of your project, [add them to the project](../../organizations/security/add-users-team-project.md) before you can add them as reviewers. -To add reviewers to a new PR: +To add reviewers to a new PR, do the following steps: 1. On the **New pull request** page, under **Reviewers**, select **Search users and groups to add as reviewers**. -1. As you enter a name or email address, a dropdown list shows a list of matching users and groups. Select names from the list to add as optional reviewers. -1. To add required reviewers, select **Add required reviewers**, and then select **Search to add required reviewers** to search for and select the names. +2. As you enter a name or email address, a dropdown list shows a list of matching users and groups. Select names from the list to add as optional reviewers. +3. To add required reviewers, select **Add required reviewers**, and then select **Search to add required reviewers** to search for and select the names. ![Screenshot of adding a reviewer to a new P R.](media/pull-requests/add-reviewer.png) -To add reviewers to an existing PR: +To add reviewers to an existing PR, do the following steps: 1. In the **Reviewers** section of the **Overview** page, select **Add**, and then select **Required reviewer** or **Optional reviewer**. @@ -456,7 +416,7 @@ To add reviewers to an existing PR: :::image type="content" source="media/pull-requests/pull-request-add-reviewer.png" alt-text="Add P R reviewer."::: -To change a reviewer between required and optional, or remove a reviewer, select **More options** to the right of the reviewer name. To see the membership of a group or team designated as a reviewer, select the group's icon. +To change a reviewer between required and optional, or to remove a reviewer, select **More options** (⋮) to the right of the reviewer's name. To view the membership of a group or team designated as a reviewer, select the group's icon. ::: moniker-end @@ -478,24 +438,6 @@ To add reviewers to your PR: --> -::: moniker range="tfs-2018" - -To add reviewers to your PR: - -1. Select the **Overview** tab in the PR. - - ![PR overview](media/pull-requests/pull-request-overview-reviewers.png) - -1. Select the add button in the **Reviewers** area. :::image type="icon" source="media/pull-requests/pull-request-add-button.png"::: - -1. Enter the name of the user or group to add to the reviewer list for the PR. If the user isn't a member of your project, you'll need to [add them](../../organizations/security/add-users-team-project.md). - -1. As you enter a name or email address, a list of matching users or groups appears. Select the user or group from the list to add them as a reviewer. - - ![Add PR reviewer](media/pull-requests/add-pr-reviewer.png) - -::: moniker-end - # [Visual Studio](#tab/visual-studio) To add reviewers, open the PR in your browser, and then make your updates on the PR's **Overview** page. @@ -537,15 +479,12 @@ az repos pr reviewer add --id |`--org` `--organization`|Azure DevOps organization URL. You can configure the default organization by using `az devops configure -d organization=`. **Required** if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`.| |`--subscription`|Name or ID of Azure subscription. You can configure the default subscription by using `az account set -s `.| - ::: moniker-end [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] *** - - @@ -556,57 +495,25 @@ az repos pr reviewer add --id ::: moniker range=">= azure-devops-2020" -To link work items to a new PR: +To link work items to a new PR, do the following steps: - 1. On the **New pull request** page, under **Work items to link**, select **Search work items by ID or title**. - 1. Start to enter a work item ID or title, and select the work item to link from the dropdown list that appears. Search by title returns work items filtered by state; all work items with states having state categories **Completed** and **Removed** are excluded. These work items are also filtered by date and user, with only items created or updated in the last 30 days shown, and they should be created by, assigned to, or authorized as the current user. +1. On the **New pull request** page, under **Work items to link**, select **Search work items by ID or title**. +1. Start entering a work item ID or title, and select the work item to link from the dropdown list that appears. + - Search by title returns work items filtered by state; all work items with states categorized as **Completed** and **Removed** are excluded. + - These work items also get filtered by date and user, showing only items created or updated in the last 30 days. They should be created by, assigned to, or authorized as the current user. -To link work items to an existing PR: +To link work items to an existing PR, do the following steps: - 1. On the PR **Overview** tab, in the **Work items** area, select **+**. +1. On the PR **Overview** tab, in the **Work items** area, select **+**. - :::image type="content" source="media/pull-requests/pull-request-link-work-items-2020.png" alt-text="Screenshot that shows selecting the Overview tab and the work items section."::: + :::image type="content" source="media/pull-requests/pull-request-link-work-items-2020.png" alt-text="Screenshot that shows selecting the Overview tab and the work items section."::: - 1. Enter the ID of the work item or search for the work item title. Select the work item from the list that appears. +2. Enter the ID of the work item or search for the work item title. Select the work item from the list that appears. Remove a work item link by selecting the **x** icon next to the work item. Removing a link only removes the link between the work item and the PR. Links created in the branch or from commits remain in the work item. ::: moniker-end -:::moniker range="azure-devops-2019" - -To link work items to your PR: - -1. Select the **Overview** tab in the PR. - - :::image type="content" source="media/pull-requests/pull-request-overview-work-items-new-nav.png" alt-text="Screenshot that shows selecting the Overview tab and the link items button."::: - -2. Select the add button in the **Work Items** area. ![Add icon in PRs](media/pull-requests/pr_add_icon.png) - -3. Enter the ID of the work item or search for work items with titles that match your text. Select the work item from the list that appears. Search by title returns work items filtered by state; all work items with states having state categories **Completed** and **Removed** are excluded. These work items are also filtered by date and user, with only items created or updated in the last 30 days shown, and they should be created by, assigned to, or authorized as the current user. - -Remove work item links by selecting the remove button that appears when you hover over the work item. ![remove button](media/pull-requests/pr_remove_icon.png) -Removing a link only removes the link between a work item to a PR. Links created in the branch or from commits stay in the work item. - -:::moniker-end - -::: moniker range="tfs-2018" - -To link work items to your PR: - -1. Select **Overview** in the PR. - - ![Select Overview in the PR.](media/pull-requests/pull-request-overview-work-items.png) - -2. Select the add button in the **Work Items** area. :::image type="icon" source="media/pull-requests/pull-request-add-button.png"::: - -3. Enter the ID of the work item or search for work items with titles that match your text. Select the work item from the list that appears. Search by title returns work items filtered by state; all work items with states having state categories **Completed** and **Removed** are excluded. These work items are also filtered by date and user, with only items created or updated in the last 30 days shown, and they should be created by, assigned to, or authorized as the current user. - -Remove work item links by selecting the remove button that appears when you hover over the work item. ![remove icon](media/pull-requests/pr_remove_icon.png) -Removing a link only removes the link between the work item and the PR. Links created in the branch or from commits stay in the work item. - -::: moniker-end - # [Visual Studio](#tab/visual-studio) To link work items, open the PR in your browser, and then make your updates on the PR's **Overview** page. @@ -614,7 +521,7 @@ To link work items, open the PR in your browser, and then make your updates on t # [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" - + You can link Azure Boards work items to PRs at PR creation with `az repos pr create --work-items `, where \ is the work item's ID. @@ -649,7 +556,6 @@ az repos pr work-item add --id |`--org` `--organization`|Azure DevOps organization URL. You can configure the default organization by using `az devops configure -d organization=`. **Required** if not configured as default or picked up via git config. Example: `https://dev.azure.com/MyOrganizationName/`.| |`--subscription`|Name or ID of Azure subscription. You can configure the default subscription by using `az account set -s `.| - ::: moniker-end [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] @@ -658,7 +564,7 @@ az repos pr work-item add --id -::: moniker range="> tfs-2018" +::: moniker range="<=azure-devops" ## Add tags to a pull request @@ -672,27 +578,6 @@ To add a tag when creating a PR, type a tag name in the **Tags** section. After ::: moniker-end -::: moniker range="tfs-2018" - -## Add labels to a pull request - -You can communicate extra information about a PR to the reviewers by using labels. Maybe the PR is still a work in progress, or it's a hotfix for an upcoming release. Use labels to communicate important details and help organize PRs. -::: moniker-end -::: moniker range="tfs-2018" - -> [!NOTE] -> Using PR labels requires TFS 2018.2 or later version. -::: moniker-end - -::: moniker range="tfs-2018" -![Screenshot showing P Rs with labels.](media/pull-requests/pull-request-labels.png) - -To add a label when creating a PR, choose **Add label**. After you create a PR, you can manage its labels in the **Labels** section. - -![Add P R label](media/pull-requests/add-pull-request-label.png) - -::: moniker-end - ::: moniker range=">= azure-devops-2020" ## Add attachments to pull requests @@ -703,7 +588,7 @@ You can attach files, including images, to your PR during or after creation. Sel ::: moniker-end -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" ## Change the target branch of an active pull request @@ -714,10 +599,9 @@ For most teams, nearly all PRs target a default branch, such as `main` or `devel ::: moniker-end +::: moniker range="<=azure-devops" -::: moniker range=">= tfs-2018" - -## Email pull request notifications to stakeholders +## Send email pull request notifications to stakeholders You can share a pull request by email to notify reviewers and communicate with team members. To share a PR: @@ -729,12 +613,12 @@ You can share a pull request by email to notify reviewers and communicate with t 1. Add an optional message in the **Note (Optional)** field, and then select **Send**. Recipients receive an email requesting their attention and linking to the PR. ->[!NOTE] ->If you use the built-in email feature, you can only send the email to project members' individual addresses. Adding a team group or security group to the **To:** line isn't supported. If you add an email account that the system doesn't recognize, you receive a message that one or more recipients of your email don't have permissions to read the mailed pull request. +> [!NOTE] +> When using the built-in email feature, you can only send emails to individual project members' addresses. Adding a team group or security group to the **To:** line isn't supported. If you add an unrecognized email address, you receive a message indicating that one or more recipients don't have permissions to read the mailed pull request. ::: moniker-end ::: moniker range="< azure-devops" -For the email feature to work, your administrator for Azure DevOps Server must [configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts?view=azure-devops-2020&preserve-view=true). +For the email feature to work, your administrator must [configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts?view=azure-devops-2020&preserve-view=true). ::: moniker-end @@ -750,5 +634,4 @@ For the email feature to work, your administrator for Azure DevOps Server must [ - [Complete pull requests](complete-pull-requests.md) - [Change the default branch](change-default-branch.md) - [Copy changes with cherry-pick](cherry-pick.md) -- [About pull requests and permissions](about-pull-requests.md) -- [Multiple merge bases](merging-with-squash.md#multiple-merge-bases) +- [Learn about pull requests and permissions](about-pull-requests.md) diff --git a/docs/repos/git/pulling.md b/docs/repos/git/pulling.md index c0f67e80862..e3e09c7c7dc 100644 --- a/docs/repos/git/pulling.md +++ b/docs/repos/git/pulling.md @@ -33,6 +33,8 @@ This article provides procedures for the following tasks: > * Update branches with _merge_ or _rebase_ > * Download changes and update branches with _pull_ + + ## Download changes with fetch Git fetch downloads remote branch commits and referenced file objects that don't exist in your local repo and updates the [remote-tracking](https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches) branches in local repo cache. Remote-tracking branches are locally cached read-only copies of remote branches and aren't your local branches. Git fetch doesn't update your local branches. For example, if a remote repo designated by `origin` has a `bugfix3` branch, Git fetch will update the remote-tracking branch named `origin/bugfix3` and not your local `bugfix3` branch. You can use remote-tracking branches to: diff --git a/docs/repos/git/pushing.md b/docs/repos/git/pushing.md index a2a32891fc2..6c3b653f497 100644 --- a/docs/repos/git/pushing.md +++ b/docs/repos/git/pushing.md @@ -20,6 +20,10 @@ You can share your work on a local Git repo [branch](create-branch.md) by upload For an overview of the Git workflow, see [Azure Repos Git tutorial](gitworkflow.md). +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## Push your code diff --git a/docs/repos/git/rebase.md b/docs/repos/git/rebase.md index a52eed362d7..8bf249088d3 100644 --- a/docs/repos/git/rebase.md +++ b/docs/repos/git/rebase.md @@ -26,6 +26,10 @@ This article discusses when to use a rebase instead of a no-fast-forward merge, For an overview of the Git workflow, see [Azure Repos Git tutorial](gitworkflow.md). +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## Rebase your local branch Git [rebase](https://git-scm.com/docs/git-rebase) integrates commits from a source branch into your current local branch (target branch). The source branch remains unchanged. For comparison, Git rebase and other merge types are shown in the following diagram. diff --git a/docs/repos/git/repo-health.md b/docs/repos/git/repo-health.md new file mode 100644 index 00000000000..e3b28340066 --- /dev/null +++ b/docs/repos/git/repo-health.md @@ -0,0 +1,115 @@ +--- +title: Repository health +titleSuffix: Azure Repos +description: How to keep git repositories healthy +ms.assetid: +ms.service: azure-devops-repos +ms.topic: reference +ms.date: 07/15/2024 +monikerRange: 'azure-devops' +ms.subservice: azure-devops-repos-git +--- + +# Repository health + +At Azure DevOps, our goal is to provide an excellent quality of service for all our customers. Maintaining optimal repository health is crucial in ensuring performance and reliability. + +To promote this goal, we actively monitor various factors that contribute to the health of a repository. These factors include size, commit frequency, contents, structure, and more. If your repository excessively impacts our infrastructure, you might receive an email from our support team asking you to take corrective action. By effectively managing your repository’s size and overall health, you can prevent it from negatively impacting our infrastructure and performance. + +To keep optimal repository health you can use "Repository health and usage" panel. + +From your web browser, navigate to the Azure Repos Git repo. Select Repo > Files and then choose "Health and usage" from the ellipsis menu to open the "Repository health and usage" panel. + + :::image type="content" source="media/repo-health/azure-devops-repo-health.png" border="true" alt-text="Screenshot of the Health and usage menu item in the More actions menu on the Repo Files page in Azure Repos." lightbox="media/repo-health/azure-devops-repo-health-lrg.png"::: + +The "Repository health and usage" panel shows you factors that contribute to the health of a repository + + :::image type="content" source="media/repo-health/repo-health-panel.png" border="true" alt-text="Screenshot of the Repository health and usage." lightbox="media/repo-health/repo-health-panel-lrg.png"::: + +Factors that are considered unhealthy will be highlighted in red, while factors that are close to being unhealthy will be highlighted in amber. + +On this page are descriptions and advice for some of the common metrics. + +## Overall reachable repository size + +This parameter shows how much space the repository consumes on the disk. + +We recommend keeping your repository size under 100 GB for optimal performance. Smaller repositories are quicker to clone and easier to manage and maintain. If your repository exceeds this size, consider using [Git-LFS](https://git-lfs.com/), [Scalar](https://git-scm.com/docs/scalar), or [Azure Artifacts](https://azure.microsoft.com/products/devops/artifacts) to refactor your development artifacts. + +## Number of reachable objects + +This parameter indicates the number of objects in the repository, which are accessible from any reference or tag. Objects include not only files (blobs), but also directories, commits, and tags. More details [Git-Internals-Git-Objects](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects). + +The greater the number of objects, the longer Git takes to traverse the repository’s history affecting time to display the history of commits, and other objects. Additionally ADO's implementation has a hard limit object limit. Azure Repos can't contain more than 100 million objects in a single repository. + +## Number of refs + +"Number of refs" displays the total number of references in the repository. + +If your Git repository contains more than 10,000 refs, you should consider enabling [Limited Refs](/previous-versions/azure/devops/all/git/limited-refs). As the number of refs increases, so does the data that needs to be negotiated between the client and server. The more data that has to be negotiated the heavier the load on the server and the more data that potentially is transferred to the client causing a degraded user experience. + +## Number of reachable blobs + +"Number of reachable blobs" displays the total number of reachable [blob](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects) files in the repository. + +We recommend maintaining a reasonable number of blob files, as mentioned in the `Number of reachable objects`. It’s also important to reserve some space for objects of other types. + +## Number of reachable trees + +"Number of reachable trees" shows the total number of reachable [tree](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects#_tree_objects) objects in the repository. + +A large number of tree files can make traversing through history expensive and may slow down several git features, such as `git blame`. + +Tree objects grow as the number of directories and files increases. Git needs to create a copy of every tree that leads to a file whenever the file is changed. Therefore, changing only one file multiple times can result in a large number of tree files. + +>[!NOTE] +>Distributing files across multiple directories and subdirectories is preferable to having a single directory with numerous direct entries. + +We recommend maintaining a reasonable number of tree objects, as suggested in the section on `Number of reachable objects`. It’s also crucial to allocate some space for objects of other types. + +## Number of reachable commits + +"Number of reachable commits" parameter represents the total number of reachable [commit](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects#_git_commit_objects) objects in the repository. + +We recommend keeping a reasonable number of commit objects, as advised in the `Number of reachable objects` section. It’s also essential to reserve some space for objects of other types. + +## Number of reachable tags + +"Number of reachable tags" displays the total number of reachable [tag](https://git-scm.com/book/en/v2/Git-Internals-Git-References#_tags) objects in the repository. + +Tags need to be transferred to the client for every fetch, even if your clone is up-to-date. Therefore, it’s advisable to limit them to a few tens of thousands at most. + +We recommend keeping a reasonable number of tag objects, as advised in the `Number of reachable objects` section. It’s also essential to reserve some space for objects of other types. + +## Number of non-diffable files + +Display the count of binary files or media assets for which we were unable to calculate a diff. + +Storing such files in Git isn't advised. Different versions of such files don’t delta well against each other, meaning Git can’t store them efficiently. Consider using [Git-LFS](https://git-lfs.com/), [Scalar](https://git-scm.com/docs/scalar), or [Azure Artifacts](https://azure.microsoft.com/products/devops/artifacts), which allow you to store such files and keep your repository healthy and maintainable. For more information, see [Manage and store large files in Git](manage-large-files.md). + +>[!NOTE] +>If you use the [REST Pushes](/rest/api/azure/devops/git/pushes/create) API, your files are not diffed and this is very inefficient for pushing objects that are normally diffable. + +## Size of reachable blobs + +"Size of reachable blobs" parameter displays the total size of blobs on a disk in gigabytes. + +As per the "Overall reachable repository size" section, it’s advisable to keep it less than 100 GB and leave some space for objects of other types. + +## Size of reachable trees + +"Size of reachable trees" parameter shows total size of tree objects on a disk in gigabytes. + +As per the "Overall reachable repository size" section, it’s advisable to keep it less than 100 GB and leave some space for objects of other types. + +## Size of reachable commits + +"Size of reachable commits" parameter shows total size of commit objects on a disk in megabytes. + +As per the "Overall reachable repository size" section, it’s advisable to keep it less than 100 GB and leave some space for objects of other types. + +## Size of reachable tags + +"Size of reachable tags" parameter shows total size of tag objects on a disk in megabytes. + +As per the "Overall reachable repository size" section, it’s advisable to keep it less than 100 GB and leave some space for objects of other types. diff --git a/docs/repos/git/repo-rename.md b/docs/repos/git/repo-rename.md index d065f92db28..6de70edfb17 100644 --- a/docs/repos/git/repo-rename.md +++ b/docs/repos/git/repo-rename.md @@ -10,7 +10,6 @@ ms.date: 02/23/2022 ms.subservice: azure-devops-repos-git --- - # Rename a Git repository in your project [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] @@ -20,17 +19,13 @@ You can rename a Git repository in a project from your web browser. After you re ## Prerequisites -- To rename a repository, you must have [Rename Repository permissions](set-git-repository-permissions.md#git-repository) on your Git repo. -::: moniker range=">= azure-devops-2020" -- If you want to use **az repos update** command to rename a repository, be sure to follow the steps in [Get started with Azure DevOps CLI](../../cli/index.md). -::: moniker-end +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] ## Rename the repository - #### [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. From the web portal, select **Repos**, **Files**. @@ -50,36 +45,13 @@ You can rename a Git repository in a project from your web browser. After you re ::: moniker-end -::: moniker range="tfs-2018" - -1. 1. From the web portal, open the project administration page for your project and select **Version Control**. - - ![Version control settings](media/repo-mgmt/version-control-settings.png) - -2. Select the repo you want to rename under **Git repositories** on the left and select **...**. Select **Rename repository...** from the menu. - - ![Rename a repository](media/repo-mgmt/rename-repo-2107.png) - - > [!NOTE] - > If the **Repositories** pane is not expanded, select **>** to expand it and display the list of repositories. - > - >![Repositories pane](media/repo-mgmt/expand-repositories-pane.png) - -3. Enter a new repo name in the **Repository name** field in the dialog, then select **Rename**. - - ![Rename repository confirm](media/repo-mgmt/rename-repository-confirm.png) - -::: moniker-end - - - + #### [Azure DevOps CLI](#tab/azure-devops-cli/) ::: moniker range="azure-devops" [!INCLUDE [az-repos-update](./includes/azure-repos-update.md)] - ::: moniker-end [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] @@ -96,7 +68,7 @@ Each member of your team must update their local Git repos to continue connectin ### Get the new URL for the repo -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Select **Repos**, **Files**. @@ -108,15 +80,6 @@ Each member of your team must update their local Git repos to continue connectin ::: moniker-end -::: moniker range="tfs-2018" - -- Select **Clone** in the upper-right corner of the **Code** window and copy the **Clone URL**. - - ![Retrieve the clone URL](media/repo-mgmt/clone-git-repo.png) - -::: moniker-end - - ### Update your remote in Visual Studio To update your remote: @@ -161,7 +124,6 @@ A: Yes - ## Related articles -- [Set Git repository settings and policies](repository-settings.md) \ No newline at end of file +- [Set Git repository settings and policies](repository-settings.md) diff --git a/docs/repos/git/repository-settings.md b/docs/repos/git/repository-settings.md index e96d9fc10a3..ae94b52f822 100644 --- a/docs/repos/git/repository-settings.md +++ b/docs/repos/git/repository-settings.md @@ -89,7 +89,6 @@ The following table summarizes the settings you can enable and configure for all The following table summarizes the settings you can enable or configure for each individual Git repository. - :::row::: :::column span="2"::: **Setting** @@ -102,20 +101,8 @@ The following table summarizes the settings you can enable or configure for each :::column-end::: :::row-end::: --- -::: moniker range="tfs-2018" -:::row::: - :::column span="2"::: - [Gravatar images](#gravatar-images) - :::column-end::: - :::column span="1"::: - On - :::column-end::: - :::column span="3"::: - Enables or disables the use of [Gravatar images](https://go.microsoft.com/fwlink/?LinkId=313945) for users outside of your enterprise. This setting applies to all repositories in the project. - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range=">= tfs-2018" + +::: moniker range="<=azure-devops" :::row::: :::column span="2"::: [Forks](#forks) @@ -128,7 +115,7 @@ The following table summarizes the settings you can enable or configure for each :::column-end::: :::row-end::: ::: moniker-end -::: moniker range=">= tfs-2018" +::: moniker range="<=azure-devops" :::row::: :::column span="2"::: [Commit mention linking](#work-item-linking) @@ -217,7 +204,7 @@ The following table summarizes the settings you can enable or configure for each :::row-end::: ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ### Repository policies or options @@ -225,7 +212,7 @@ The following table summarizes the policies or options you can set for either al ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="2"::: **Policy** or **Option** @@ -263,7 +250,7 @@ The following table summarizes the policies or options you can set for either al :::column-end::: :::row-end::: ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="2"::: [Case enforcement](#case-enforcement) @@ -317,6 +304,9 @@ The following table summarizes the policies you can define to customize a branch - Pull requests are required to update the branch. - The branch can't be deleted. +> [!NOTE] +> Branch policies are applied to Pull Requests based on the target branch of the Pull Request. Branch policies should not be set on temporary branches that will be deleted after a pull request. Adding branch policies to temporary branches will cause automatic branch deletion to fail. + :::row::: :::column span="2"::: **Policy** @@ -374,7 +364,7 @@ The following table summarizes the policies you can define to customize a branch Control branch history by limiting the available types of merge when pull requests are completed. :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="2"::: [Build Validation](branch-policies.md#build-validation) @@ -411,18 +401,9 @@ The following table summarizes the policies you can define to customize a branch :::row-end::: ::: moniker-end -## Prerequisites - - -::: moniker range=">= azure-devops-2020" -- To configure policies, you must be a member of the Project Administrators security group, or have repository-level **Edit policies** permissions. To learn more, see [Set Git repository permissions](set-git-repository-permissions.md). -- If you want to use **az repos** commands, be sure to follow the steps in [Get started with Azure DevOps CLI](../../cli/index.md). -::: moniker-end - -::: moniker range="< azure-devops-2020" -- To configure policies, you must be a member of the Project Administrators security group, or have repository-level **Edit policies** permissions. To learn more, see [Set Git repository permissions](set-git-repository-permissions.md). -::: moniker-end +## Prerequisites +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] @@ -435,7 +416,7 @@ You can configure *settings* for all repositories across an organization or proj #### [Browser](#tab/browser) -::: moniker range="> azure-devops-2019" +::: moniker range="<=azure-devops" To configure repository settings and policies through the web portal, open **Project settings**> **Repositories** from your web browser. @@ -457,51 +438,18 @@ To configure repository settings and policies through the web portal, open **Pro ::: moniker-end -::: moniker range="azure-devops-2019" - -1. From your web browser, open the project and choose **Project settings**, **Repositories**, and select your repository. - - ![Screenshot of the 'Project Settings' for your repository.](media/repository-settings/project-repository-settings.png) - -2. To view and configure repository settings, select **Options** or **Policies**. - - The following screenshot shows **Options** for all repositories: - - ![Screenshot of the Options for all repositories.](media/repository-settings/options-all-repos.png) - - The following screenshot shows **Options** for the Fabrikam repositories: - - ![Screenshot of Options for the Fabrikam repository.](media/repository-settings/options-fabrikam.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -1. From your web browser, open the project and choose the gear icon, **Version Control**, and select your repository. - - ![Screenshot that shows the 'Version Control' options for your repository.](media/repository-settings/project-repository-settings-prev-nav.png) - -2. Select **Options** to view and configure your repository settings. - - ![The options UI](media/repository-settings/repository-settings-tfs2018.2.png) - -::: moniker-end - - - #### [Azure DevOps CLI](#tab/azure-devops-cli/) ::: moniker range="azure-devops" -You can use Azure DevOps CLI to list respositories or show or update a repository. Also, you can list, show or update policy details for a branch or repository. +You can use Azure DevOps CLI to list repositories or show or update a repository. Also, you can list, show or update policy details for a branch or repository. [List repositories](#repos-list) | [List repository details](#repos-show) | [Update or rename a repository](#repos-update) -[List repository policies](#repos-policy-list) | [List policy details](#show-policy) | [Update respository policy](#update-policy) - +[List repository policies](#repos-policy-list) | [List policy details](#show-policy) | [Update repository policy](#update-policy) You can use Azure CLI to list, show, and update policies for a branch or repository, or for all repositories in a project. - + ### List repositories @@ -523,12 +471,10 @@ az repos list [--detect {false, true}] |`project`, `p`|Name or ID of the project. You can configure the default project using `az devops configure -d project=`. **Required** if not configured as default or picked up via git config.| |`subscription`|Name or ID of subscription. You can configure the default subscription using `az account set -s `.| - **Example** The following command returns all Git repositories for the default configuration `az devops configure --defaults organization=https://dev.azure.com/fabrikamprime project="Fabrikam Fiber"`. - ```azurecli az repos list --output table ID Name Default Branch Project @@ -539,8 +485,7 @@ ac228555-ea89-4881-9ace-dfa065baf7d3 Test 1-2-3 main Fabrikam 30954ce5-417b-4930-b8d2-8b6cac934a34 contosoREPO main Fabrikam Fiber ``` - - + ### List repository details @@ -566,7 +511,6 @@ az repos show --repository |`project`, `p`|Name or ID of the project. You can configure the default project using `az devops configure -d project=`. **Required** if not configured as default or picked up via git config.| |`subscription`|Name or ID of subscription. You can configure the default subscription using `az account set -s `.| - **Example** The following command lists the details of the *contosoREPO* for the default configuration `az devops configure --defaults organization=https://dev.azure.com/fabrikamprime project="Fabrikam Fiber"`. @@ -609,7 +553,7 @@ az repos show --repository contosoREPO } ``` - + ### Update a repository @@ -703,8 +647,7 @@ ID Name Is Blocking Is Enabled Repository Id ``` - - + ### Update policies @@ -765,16 +708,12 @@ ID Name Is Blocking Is Enabled Branch 7 Minimum number of reviewers False True refs/heads/main ``` - ::: moniker-end - [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - *** - ::: moniker range=">= azure-devops-2020" @@ -853,20 +792,9 @@ This setting enables or disables the use of [Gravatar images](https://go.microso 1. On the **Settings** tab of the **All Repositories** page, set **Gravatar images** to **On** or **Off**. ::: moniker-end -::: moniker range="azure-devops-2019" -**Gravatar images** is a project-level setting for **All Repositories**. - -1. On your Azure DevOps project page, select **Project settings** at lower left, and then select **Repositories** in the left navigation. -1. On the **Settings** tab of the **All Repositories** page, set **Gravatar images** to **On** or **Off**. -::: moniker-end - -::: moniker range="tfs-2018" -**Gravatar images** is an individual repository setting. -::: moniker-end - -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" @@ -902,12 +830,6 @@ When enabled, commit messages containing `#` followed by a valid work item ID au Enable this setting to automatically complete work items when linked pull requests complete. This setting also allows specifying other work item transition states in pull request commit messages. For more information, see [Auto-complete work items with pull requests](../../boards/work-items/auto-complete-work-items-pull-requests.md). -::: moniker-end -::: moniker range=">= tfs-2018 <= azure-devops-2019" - -### Commit mention work item resolution - -Enable this setting to automatically complete those work items when you successfully complete the PR. To learn more, see [Auto-complete work items with pull requests](../../boards/work-items/auto-complete-work-items-pull-requests.md). ::: moniker-end ### Work item transition preferences @@ -969,7 +891,7 @@ To set policies to protect specific or default branch names across a project: 1. Select the plus sign **+** in **Branch Policies** at the bottom of the page. 1. On the **Add branch protection** screen, select **Protect the default branch of each repository**, or **Protect current and future branches matching a specified pattern**. - If you select the second option, enter the branch name to protect. An informational message lets you know how many current branches are affected. The branch doesn't have to exist yet to protect the branch name. + If you select the second option, enter the branch name to protect. An informational message lets you know how many current branches are affected. Keep in mind that branch name (or the pattern you entered) is **case-sensitive**. The branch doesn't have to exist yet to protect the branch name. 1. Select **Create**. @@ -1008,12 +930,11 @@ You can set a policy that prevents commits to a repository from file paths that :::image type="content" source="media/repository-settings/add-policy-to-block-files-patterns.png" alt-text="Screenshot that shows the File path validation policy setting."::: - ## Case enforcement policy -::: moniker range=">= tfs-2018" +::: moniker range="<=azure-devops" Git is case-sensitive, meaning that a file called *Foo.txt* is different from a file called *foo.txt*. However, Windows and macOS default to case-insensitive file systems, meaning that *Foo.txt* and *foo.txt* are the same name. This discrepancy can cause problems if someone on a case-insensitive system pushes files, folders, branches, or tags that differ only by letter case. For more information, see [Git Cross-Platform Compatibility](os-compatibility.md). If most of your contributors are on Windows or macOS, it's best to enable the **Case enforcement** policy. Case enforcement switches the server from its default case-sensitive mode, where *File.txt* and *file.txt* are distinct, to a Windows and macOS-friendly mode where *File.txt* and *file.txt* are considered the same file. This setting affects files, folders, branches, and tags. @@ -1026,7 +947,7 @@ This setting won't fix a repository that already contains objects that differ on #### [Browser](#tab/browser) -::: moniker range=">= tfs-2018" +::: moniker range="<=azure-devops" To set case enforcement policy: @@ -1036,10 +957,7 @@ To set case enforcement policy: :::image type="content" source="media/repository-settings/case-enforcement.png" alt-text="Screenshot that shows the Case enforcement policy setting."::: ::: moniker-end -::: moniker range="tfs-2018" -> [!NOTE] -> The **Case enforcement** policy requires TFS 2018.2 or later version. -::: moniker-end + #### [Azure DevOps CLI](#tab/azure-devops-cli/) @@ -1161,14 +1079,13 @@ To set the maximum path length policy: :::image type="content" source="media/repository-settings/maximum-path-length.png" alt-text="Screenshot that shows the Maximum path length policy setting."::: - ## Maximum file size policy Large files checked into Git remain in the repository indefinitely, increasing clone times and disk usage. For guidance on managing large files, see [Manage and store large files in Git](manage-large-files.md). -::: moniker range=">= tfs-2018" +::: moniker range="<=azure-devops" The **Maximum file size** policy setting blocks files over a certain size from entering the repository. If a push contains a new or updated file larger than the limit configured in this setting, the push is blocked. The user must rewrite their unpushed history to remove the large file and try the push again. ::: moniker-end @@ -1183,10 +1100,7 @@ To configure **Maximum file size** policy: :::image type="content" source="media/repository-settings/maximum-file-size.png" alt-text="Screenshot that shows the Maximum file size policy setting."::: -::: moniker range="tfs-2018" -> [!NOTE] -> The **Maximum file size** policy requires TFS 2018.2 or later. -::: moniker-end + #### [Azure DevOps CLI](#tab/azure-devops-cli/) diff --git a/docs/repos/git/restore-deleted-branch.md b/docs/repos/git/restore-deleted-branch.md index 655da86d05a..be42cec6588 100644 --- a/docs/repos/git/restore-deleted-branch.md +++ b/docs/repos/git/restore-deleted-branch.md @@ -1,11 +1,11 @@ --- title: Restore a deleted branch in your Git repo titleSuffix: Azure Repos -description: Use the branches page to restore a deleted Git branch in Azure DevOps Services or Team Foundation Server +description: Use the branches page to restore a deleted Git branch in Azure DevOps. ms.assetid: ms.service: azure-devops-repos ms.topic: conceptual -ms.date: 10/10/2018 +ms.date: 02/17/2025 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- @@ -18,49 +18,39 @@ This article addresses how to restore a deleted Git branch using the web portal If you need to restore a Git branch in your own repo from Visual Studio or the command line, [push](pushing.md) your branch from your local repo to Azure Repos to restore it. +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + > [!NOTE] -> There is no retention policy on deleted branches. A deleted Git branch can be restored at any time, regardless of when it was deleted. +> There's no retention policy on deleted branches. You can restore a deleted Git branch at any time, regardless of when it was deleted. + +## Restore branch 1. Open your repo on the web and [select the **Branches** view](manage-your-branches.md). 2. Search for the exact branch name using the **Search all branches** box in the upper right. -3. Click the link to **Search for exact match in deleted branches**. - If there is a deleted branch that matches your search, you will be able to see which commit it pointed to when it was deleted, - who deleted it, and when it was deleted. +3. Select the link to **Search for exact match in deleted branches**. + If there's a deleted branch that matches your search, you can find which commit it pointed to when upon deletion, who deleted it, and when. ![Search for exact match in deleted branches in the Azure DevOps Services/TFS web portal](media/branches/search_deleted_branches.png) 4. To restore the branch, select the **...** icon next to the branch name and then select **Restore branch** from the menu. - The branch will be recreated at the last commit to which it pointed. - Note that branch policies and permissions will **not** be restored. + The branch gets recreated at the last commit to which it pointed. + Branch policies and permissions do **not** get restored. ![Restore your deleted branch in the Azure DevOps Services/TFS web portal](media/branches/restore_deleted_branch.png) -If you've re-used the same branch name for different commits, you may not see all the commits you're expecting when you restore the deleted branch. In that case, navigate to the **Pushes** page of the restored branch to see the entire history of the branch. +If you reused the same branch name for different commits, you might not see all the commits you're expecting when you restore the deleted branch. In that case, go to the **Pushes** page of the restored branch to see the entire history of the branch. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" ![View all pushes for your restored branch](media/branches/restore_deleted_branch_pushes-new-nav.png) -You can navigate to a specific commit, then select **New branch** from the **...** icon. +You can go to a specific commit, then select **New branch** from the **...** icon. From there, you can use a pull request, cherry-pick, or merge to get the commits back into the desired branch. ![New branch from commit](media/branches/deleted_branch_new_branch_from_commit.png) ::: moniker-end - -::: moniker range="tfs-2018" - -![View all pushes for your restored branch](media/branches/restore_deleted_branch_pushes.png) - -You can navigate to a specific commit, then select **New branch** from the **...** icon. -From there, you can use a pull request, cherry-pick, or merge to get the commits back into the desired branch. - -![New branch from commit](media/branches/deleted_branch_new_branch_from_commit.png) - -::: moniker-end - - - - diff --git a/docs/repos/git/review-history.md b/docs/repos/git/review-history.md index ba042bbc938..150fe3cf408 100644 --- a/docs/repos/git/review-history.md +++ b/docs/repos/git/review-history.md @@ -19,14 +19,11 @@ Git uses [commit metadata](commits.md#whats-in-a-commit) like parent links, auth When people create and merge feature [branches](./create-branch.md) into a target branch using [pull requests](pull-requests.md), the development history of the target branch might not be a straight chronological line. So, when you review the history of changes to a file on the target branch, keep in mind that the order of commits is influenced by [merge strategy](pulling.md#update-branches-with-merge-or-rebase) and merge date, not just the original date of the changes. For example, the most recent commit on the `main` branch may introduce a change that was made weeks ago in a feature branch that was only just merged into the `main` branch using a three-way merge. -In this article you learn how to: +To learn how to use Visual Studio 2022 with Git, see [How Visual Studio makes version control easy with Git](/visualstudio/version-control/git-with-visual-studio). ->[!div class="checklist"] ->* Compare file versions ->* Restore files ->* Compare branches +## Prerequisites -To learn how to use Visual Studio 2022 with Git, see [How Visual Studio makes version control easy with Git](/visualstudio/version-control/git-with-visual-studio). +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] ## Compare file versions diff --git a/docs/repos/git/review-pull-requests.md b/docs/repos/git/review-pull-requests.md index 25534f8072a..e03d1ec6f91 100644 --- a/docs/repos/git/review-pull-requests.md +++ b/docs/repos/git/review-pull-requests.md @@ -47,14 +47,13 @@ In this article you learn how to: ::: moniker-end - ## Prerequisites ::: moniker range="azure-devops" - **Repos** must be enabled in your Azure DevOps project settings. If the **Repos** hub and associated pages don't display, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md) to reenable **Repos**. -- To review PRs, you must be a member of the Azure DevOps project the PR is in, with **Basic** access level or higher. +- To review PRs, be a member of the Azure DevOps project the PR is in, with at least **Basic** access. - If you don't have a project, create one or [sign up for free](../../user-guide/sign-up-invite-teammates.md). @@ -65,21 +64,15 @@ In this article you learn how to: ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" ## Vote on PR changes @@ -521,10 +503,8 @@ Jamal Hartnett jamalh@fabrikam.com 00000000-0000-0000-0000-000000000000 ::: moniker-end - *** - ::: moniker range=">= azure-devops-2022" ## Complete a PR @@ -545,7 +525,6 @@ For more information on completing a PR, see [Complete the pull request](complet ::: moniker-end - ## Next steps >[!div class="nextstepaction"] diff --git a/docs/repos/git/set-git-repository-permissions.md b/docs/repos/git/set-git-repository-permissions.md index a5b77edf4a2..7ae9f9d8cd6 100644 --- a/docs/repos/git/set-git-repository-permissions.md +++ b/docs/repos/git/set-git-repository-permissions.md @@ -1,7 +1,7 @@ --- title: Set Git repository permissions titleSuffix: Azure Repos -description: Steps for how to grant or restrict access to a Git repository feature +description: Steps for how to grant or restrict access to a Git repository feature. ms.service: azure-devops-repos ms.topic: quickstart ms.author: vijayma @@ -11,46 +11,45 @@ ms.date: 04/14/2021 ms.subservice: azure-devops-repos-git --- - # Set Git repository permissions - [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You grant or restrict access to repositories to lock down who can contribute to your source code and manage other features. You can set permissions across all Git repositories by making changes to the top-level **Git repositories** entry. Individual repositories inherit permissions from the top-level **Git Repositories** entry. +Manage access to repositories to lock down who can contribute to your source code and manage other features. You can set permissions across all Git repositories by making changes to the top-level **Git repositories** entry. Individual repositories inherit permissions from the top-level **Git Repositories** entry. > [!NOTE] > Branches inherit a subset of permissions from assignments made at the repository level. For branch permissions and policies, see [Set branch permissions](branch-permissions.md) and [Improve code quality with branch policies](branch-policies.md). -For guidance on who to provide greater permission levels, see [Grant or restrict access using permissions](../../organizations/security/restrict-access.md). - +For guidance on who to provide greater permission levels, see [Manage access using permissions](../../organizations/security/restrict-access.md). ## Prerequisites -- You must have a project. If you don't have a project yet, create one in [Azure DevOps](../../user-guide/sign-up-invite-teammates.md) or set one up in an [on-premises Azure DevOps](../../organizations/projects/create-project.md). -- You must be a member of the [**Project Administrators** Group](../../organizations/security/change-project-level-permissions.md) or have your **Manage permissions** set to **Allow** for Git repositories. +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] ::: moniker range="azure-devops" -To contribute to the source code, you must be granted **Basic** access level or greater. Users granted **Stakeholder** access for private projects have no access to source code. Users granted **Stakeholder** access for public projects have the same access as Contributors and those granted **Basic** access. To learn more, see [About access levels](../../organizations/security/access-levels.md). +To contribute to the source code, have **Basic** access level or greater. Users granted **Stakeholder** access for private projects have no access to source code. Users granted **Stakeholder** access for public projects have the same access as Contributors and those granted **Basic** access. For more information, see [About access levels](../../organizations/security/access-levels.md). ::: moniker-end ::: moniker range="< azure-devops" -To contribute to the source code, you must be granted **Basic** access level or greater. Users granted **Stakeholder** access have no access to source code. To learn more, see [About access levels](../../organizations/security/access-levels.md). +To contribute to the source code, have **Basic** access level or greater. Users granted **Stakeholder** access have no access to source code. For more information, see [About access levels](../../organizations/security/access-levels.md). ::: moniker-end - ## Default repository permissions By default, members of the project Contributors group have permissions to contribute to a repository. This includes the ability to create branches, create tags, and manage notes. For a description of each security group and permission level, see [Permissions and group reference](../../organizations/security/permissions.md). [!INCLUDE [temp](../../organizations/security/includes/code-git.md)] +:::moniker range=">= azure-devops-2022" - +Starting with [Azure DevOps sprint 224](/azure/devops/release-notes/2023/sprint-224-update) (Azure DevOps Services and Azure DevOps Server 2022.1 and higher), [Edit policies permission is no longer granted automatically to branch creators](/azure/devops/release-notes/2023/sprint-224-update#removing-edit-policies-permission-to-branch-creator). Previously, when you created a new branch, you were granted permission to edit policies on that branch. With this update, we are changing the default behavior to not grant this permission even if the **Permission management** setting is switched on for the repository. You will need the **Edit policies** permission granted explicitly (either manually or through REST API) by security permission inheritance or through a group membership. + +:::moniker-end + ::: moniker range="azure-devops" @@ -58,7 +57,6 @@ By default, members of the project Contributors group have permissions to contri You set Git repository permissions from **Project Settings>Repositories**. - 1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). 2. Open **Project settings>Repositories**. @@ -79,11 +77,11 @@ You set Git repository permissions from **Project Settings>Repositories**. ## Set permissions for a repository -You can grant or restrict access to a repository by setting the permission state to **Allow** or **Deny** for a single user or a security group. +You can manage access to a repository by setting the permission state to **Allow** or **Deny** for a single user or a security group. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" [!div class="mx-imgBorder"] - > ![Open Project Settings, horizontal nav](../../media/settings/open-project-settings-horz.png) - -2. Choose **Version Control**. - -3. To set the set the permissions for all Git repositories for a project, (1) choose **Git Repositories** and then (2) choose the security group whose permissions you want to manage. - - [!INCLUDE [temp](../../includes/ability-to-find-user-once-added.md)] - - Otherwise, choose a specific repository and choose the security group whose permissions you want to manage. - -4. Choose the setting for the permission you want to change. - - Here we grant permissions to the Contributors group to (3) **Create repository**. - - ![Security dialog for all Git repositories, Contributors group](media/git-permissions/set-repo-git-permissions.png) - -5. When done, choose **Save changes**. - -::: moniker-end - - ::: moniker range="azure-devops" ## Change permissions for a security group -To set permissions for a custom security group, you must have defined that group previously. See [Set permissions at the project-level](../../organizations/security/change-project-level-permissions.md). +To set permissions for a custom security group, have defined that group previously. See [Set permissions at the project-level](../../organizations/security/change-project-level-permissions.md). 1. To set permissions for a specific group, choose the group. For example, here we choose the Contributors group. @@ -152,7 +120,6 @@ To set permissions for a custom security group, you must have defined that group 1. When done, navigate away from the page. The permission changes are automatically saved for the selected group. - ## Set permissions for a specific user 1. To set permissions for a specific user, enter the name of the user into the search filter and select from the identities that appear. @@ -177,13 +144,10 @@ To set permissions for a custom security group, you must have defined that group > [!div class="mx-imgBorder"] > ![Enable or disable inheritance for a specific repository.](media/git-permissions/disable-inheritance-specific-repo.png) - To learn about inheritance, see [About permissions and groups, Inheritance and security groups](../../organizations/security/about-permissions.md#inheritance). + To learn about inheritance, see [About permissions and groups, Inheritance and security groups](../../organizations/security/about-permissions.md#permission-inheritance). ::: moniker-end - - - ## Exempt from policy enforcement and bypass policy permissions There are many scenarios where you have the occasional need to bypass a branch policy. For example, when reverting a change that caused a build break or applying a hotfix in the middle of the night. Previously, the **Exempt from policy enforcement** permission helped teams manage which users were granted the ability to bypass branch policies when completing a pull request. However, that permission also granted the ability to push directly to the branch, bypassing the PR process entirely. @@ -198,10 +162,9 @@ By granting the first permission and denying the second, a user can use the bypa > [!NOTE] > This change does not introduce any behavior changes. Users that were formerly granted **Allow** for **Exempt from policy enforcement** are granted **Allow** for both new permissions, so they'll be able to both override completion on PRs and push directly to branches with policies. - ## Related articles -- [Grant or restrict access using permissions](../../organizations/security/restrict-access.md) +- [Manage access using permissions](../../organizations/security/restrict-access.md) - [Default permissions and access](../../organizations/security/permissions-access.md) - [Permissions and groups reference](../../organizations/security/permissions.md) - [Tf git permission command-line tool](../tfvc/git-permission-command.md) diff --git a/docs/repos/git/set-up-credential-managers.md b/docs/repos/git/set-up-credential-managers.md index 3df83b5b44c..3f55e4d66ad 100644 --- a/docs/repos/git/set-up-credential-managers.md +++ b/docs/repos/git/set-up-credential-managers.md @@ -7,7 +7,7 @@ ms.service: azure-devops-repos ms.topic: conceptual monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git -ms.date: 11/13/2020 +ms.date: 12/26/2024 --- # Use Git Credential Manager to authenticate to Azure Repos @@ -15,22 +15,28 @@ ms.date: 11/13/2020 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-eq-2019](../../includes/version-vs-gt-eq-2019.md)] -Git Credential Manager simplifies authentication with your Azure Repos Git repositories. Credential managers let you use the same credentials that you use for the Azure DevOps Services web portal. Credential managers support multi-factor authentication through Microsoft account or Azure Active Directory (Azure AD). Besides supporting multi-factor authentication with Azure Repos, credential managers also support [two-factor authentication](https://help.github.com/articles/about-two-factor-authentication/) with GitHub repositories. +Git Credential Manager simplifies authentication with your Azure Repos Git repositories. Credential managers let you use the same credentials that you use for the Azure DevOps Services web portal. Credential managers support multifactor authentication through Microsoft account or Microsoft Entra ID. Besides supporting multifactor authentication with Azure Repos, credential managers also support [two-factor authentication](https://help.github.com/articles/about-two-factor-authentication/) with GitHub repositories. -Azure Repos provides IDE support for Microsoft account and Azure AD authentication through the following clients: +Azure Repos provides IDE support for Microsoft account and Microsoft Entra authentication through the following clients: - [Team Explorer in Visual Studio](../../organizations/projects/connect-to-projects.md) - [IntelliJ and Android Studio with the Azure Repos Plugin for IntelliJ](/previous-versions/azure/devops/all/java/download-intellij-plug-in) If your environment doesn't have an integration available, configure your IDE with a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) or [SSH](use-ssh-keys-to-authenticate.md) to connect to your repositories. +> [!IMPORTANT] +> Over the next year, we’ll be making moves towards strengthening Microsoft and our customers’ security posture in regards to the usage and creation of personal access tokens (PATs). +> If you’ve been following this blog, you may have noticed we’ve been distancing away from PATs as the recommended authentication method for Azure DevOps APIs by offering restrictive policies and more secure alternatives. PATs can be an enticing vector for unauthorized access, especially when insecurely stored, over-scoped, or set for long durations. +> +> Learn more about our efforts in [reducing personal access token (PAT) usage across Azure DevOps](https://devblogs.microsoft.com/devops/reducing-pat-usage-across-azure-devops/) + ## Install Git Credential Manager ### Windows Download and run the latest [Git for Windows installer](https://git-scm.com/download/win), which includes Git Credential Manager. Make sure to enable the Git Credential Manager installation option. - ![Select Enable Git Credential Manager during Git for Windows install](media/install-git-with-git-credential-manager.png) + ![Screenshot shows selection, Enable Git Credential Manager during Git for Windows install.](media/install-git-with-git-credential-manager.png) ### macOS and Linux @@ -42,11 +48,26 @@ On Linux, you can install from a [.deb](https://github.com/GitCredentialManager/ ## Using the Git Credential Manager -When you connect to a Git repository from your Git client for the first time, the credential manager prompts for credentials. Provide your Microsoft account or Azure AD credentials. If your account has multi-factor authentication enabled, the credential manager prompts you to go through that process as well. +When you connect to a Git repository from your Git client for the first time, the credential manager prompts for credentials. Provide your Microsoft account or Microsoft Entra credentials. If your account has multi-factor authentication enabled, the credential manager prompts you to go through that process as well. ![Git Credential Manager prompting during Git pull](media/gcm_login_prompt.gif) -Once authenticated, the credential manager creates and caches a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) for future connections to the repo. Git commands that connect to this account won't prompt for user credentials until the token expires. A token can be revoked through Azure Repos. +Once authenticated, the credential manager creates and caches a token for future connections to the repo. Git commands that connect to this account won't prompt for user credentials until the token expires. A token can be revoked through Azure Repos. + +### Set default credential type as OAuth +By default, GCM will request a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) from Azure Repos. However, you can change the default token type to a [Microsoft Entra token](../../integrate/get-started/authentication/entra.md) for Git authentication instead. We recommend this approach since the latter token has a one-hour expiration compared to the 7-day PATs minted by GCM. All PATs created by GCM can be [revoked in the User Settings page](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#revoke-a-pat). + +To [set your default credential type to Microsoft Entra tokens](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/configuration.md#credentialazreposcredentialtype), set the `credential.azreposCredentialType` configuration entry (or `GCM_AZREPOS_CREDENTIALTYPE` environment variable) to `oauth`. Learn more about [using GCM with Azure Repos](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/azrepos-users-and-tokens.md#set-default-credential-type). + +### Use service principal as authentication +You can also provide a [service principal](../../integrate/get-started/authentication/service-principal-managed-identity.md) for [authentication with GCM](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/configuration.md#credentialazreposserviceprincipal). Specify the client and tenant IDs of a service principal in this format: `{tenantId}/{clientId}`. + +```git config --global credential.azreposServicePrincipal "11111111-1111-1111-1111-111111111111/22222222-2222-2222-2222-222222222222"``` + +You must also set at least one authentication mechanism if you set this value: +* [credential.azreposServicePrincipalSecret](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/configuration.md#credentialazreposserviceprincipalsecret) +* [credential.azreposServicePrincipalCertificateThumbprint](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/configuration.md#credentialazreposserviceprincipalcertificatethumbprint) +* [credential.azreposServicePrincipalCertificateSendX5C](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/configuration.md#credentialazreposserviceprincipalcertificatesendx5c) ### Getting help diff --git a/docs/repos/git/share-your-code-in-git-cmdline.md b/docs/repos/git/share-your-code-in-git-cmdline.md index 5887a9ce128..3f27788a040 100644 --- a/docs/repos/git/share-your-code-in-git-cmdline.md +++ b/docs/repos/git/share-your-code-in-git-cmdline.md @@ -6,7 +6,7 @@ ms.assetid: 4b299dbf-3ca9-47af-bd6d-8c40bafac447 ms.service: azure-devops-repos ms.topic: quickstart ms.custom: devx-track-azurecli -monikerRange: '>= azure-devops-2020' +monikerRange: 'azure-devops' ms.date: 03/31/2022 ms.subservice: azure-devops-repos-git --- @@ -17,22 +17,29 @@ ms.subservice: azure-devops-repos-git This guide shows you how to share your code in a Git repo in Azure Repos using the command line. -The instructions below use the default bash shell used on Linux and macOS, but the Git commands will work in any shell, including Git Bash from Git for Windows. +The instructions in this article use the default bash shell used on Linux and macOS, but the Git commands work in any shell, including Git Bash from Git for Windows. ## Prerequisites -* An organization in Azure DevOps. If you don't have an organization, you can [sign up](../../organizations/accounts/create-organization.md) for one for free. Each organization includes free, unlimited private Git repositories. +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of a [project](../../organizations/projects/create-project.md). | +| **Permissions** | - View code in private projects: At least **Basic** access.
      - Clone or contribute to code in private projects: Member of the **Contributors** security group or corresponding permissions in the project.
      - Set branch or repository permissions: **Manage permissions** permissions for the branch or repository.
      - Change default branch: **Edit policies** permissions for the repository.
      - Import a repository: Member of the **Project Administrators** security group or Git project-level **Create repository** permission set to **Allow**. For more information, see [Set Git repository permissions](set-git-repository-permissions.md). | +| **Services** | [Repos enabled](../../organizations/settings/set-services.md). | +| **Tools** | Optional. Use **az repos** commands: [Azure DevOps CLI](../../cli/index.md).| + +> [!NOTE] +> In public projects, users with **Stakeholder** access have full access to Azure Repos, including viewing, cloning, and contributing to code. ## Download and install Azure CLI and add Azure DevOps extension -1. [Install the Azure CLI](/cli/azure/install-azure-cli). You must have at least `v2.0.49`, which you can verify with `az --version` command. +1. [Install the Azure CLI](/cli/azure/install-azure-cli). At least `v2.0.49`, which you can verify with `az --version` command. 2. Add the Azure DevOps Extension `az extension add --name azure-devops` 3. Run the `az login` command. - If the CLI can open your default browser, it will do so and load a sign-in page. Otherwise, you need to open a - browser page and follow the instructions on the command line to enter an authorization code after navigating to + If the CLI can open your default browser, it does so and loads a sign-in page. Otherwise, you need to open a browser page and follow the instructions on the command line to enter an authorization code after navigating to [https://aka.ms/devicelogin](https://aka.ms/devicelogin) in your browser. For more information, see the [Azure CLI login page](/cli/azure/authenticate-azure-cli?preserve-view=true&view=azure-cli-latest). @@ -51,6 +58,12 @@ The instructions below use the default bash shell used on Linux and macOS, but t Download and install [Git for Windows](https://git-scm.com/download/win) , which includes the [Git Credential Manager](set-up-credential-managers.md) to easily connect to Azure Repos. +To use [WinGet](/windows/package-manager/winget), the Windows package manager, run the following in a command line environment such as PowerShell. + +```powershell +winget install --id Git.Git -e --source winget +``` + ### macOS Use [Homebrew](https://brew.sh/) to install and set up Git. @@ -61,13 +74,13 @@ brew install git ### Linux and Unix -Use your distribution's package management system to download and install Git. For example, on Ubuntu: +To download and install Git, use your distribution's package management system. For example, on Ubuntu: ```bash sudo apt-get install git ``` -Refer to the [list of install commands](https://git-scm.com/download/linux) for the most up to date instructions for your Linux distribution. +Refer to the [list of install commands](https://git-scm.com/download/linux) for the most up-to-date instructions for your Linux distribution. ## Create your local repo @@ -79,7 +92,7 @@ Create a local Git repo for your code. If your code is already in a local Git re cd /home/fabrikam/fiber ``` -2. Create a Git repo on your machine to store your code. You will connect this repo to Azure Repos in the next section. +2. Create a Git repo on your machine to store your code. You'll connect this repo to Azure Repos in the next section. ```bash git init . diff --git a/docs/repos/git/share-your-code-in-git-eclipse.md b/docs/repos/git/share-your-code-in-git-eclipse.md index 00f2f64d816..cd3e01b3690 100644 --- a/docs/repos/git/share-your-code-in-git-eclipse.md +++ b/docs/repos/git/share-your-code-in-git-eclipse.md @@ -20,8 +20,7 @@ Share your Eclipse project with your team in an Azure DevOps Services/TFS Git re ## Prerequisites -* An Azure DevOps organization. If you don't have one, you can [sign up](../../organizations/accounts/create-organization.md) for one for free. Each organization includes free, unlimited private Git repositories. -* A local Eclipse project. If your code is already in version control in Azure Repos or TFS and you want to clone it, see [Clone an Azure DevOps Services Git repo using Eclipse](/previous-versions/azure/devops/all/java/labs/eclipsegit/). +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] diff --git a/docs/repos/git/share-your-code-in-git-vs.md b/docs/repos/git/share-your-code-in-git-vs.md index 7555fdb6d19..19b3577ab79 100644 --- a/docs/repos/git/share-your-code-in-git-vs.md +++ b/docs/repos/git/share-your-code-in-git-vs.md @@ -34,7 +34,7 @@ For an overview of the Git workflow, see [Azure Repos Git tutorial](gitworkflow. [!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] -To learn more about permissions and access, see [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) and [About access levels](../../organizations/security/access-levels.md). +For more information about permissions and access, see [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) and [About access levels](../../organizations/security/access-levels.md). [!INCLUDE [temp](includes/note-new-git-tool.md)] @@ -229,7 +229,7 @@ To show a diff view of the last commit in your current branch, run the following --- - + ## Link work items to your commits diff --git a/docs/repos/git/share-your-code-in-git-xcode.md b/docs/repos/git/share-your-code-in-git-xcode.md index f1307568552..6bb9303708f 100644 --- a/docs/repos/git/share-your-code-in-git-xcode.md +++ b/docs/repos/git/share-your-code-in-git-xcode.md @@ -19,7 +19,7 @@ This guide shows you how to share your Xcode projects using Azure Repos. ## Prerequisites -* An organization in Azure DevOps. If you don't have an organization, you can [sign up](../../organizations/accounts/create-organization.md) for one for free. Each organization includes free, unlimited private Git repositories. +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] ## Create a local Git repo for your Xcode project diff --git a/docs/repos/git/team-projects.md b/docs/repos/git/team-projects.md index c3d4c4b5efa..0cda5c985ae 100644 --- a/docs/repos/git/team-projects.md +++ b/docs/repos/git/team-projects.md @@ -18,6 +18,10 @@ ms.date: 09/10/2018 In Team Foundation Server 2015 Update 1, a project administrator can add a Git repo to a project created with Team Foundation Version Control (TFVC). You can also add a TFVC repo to a project created with Git. This allows you to adopt a new version control system while preserving all the data in your project. +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## Enable access to the new repo type Because permissions are applied at project creation time by a process template, there will be a small amount of work to correct permissions for a new repo type. diff --git a/docs/repos/git/toc.yml b/docs/repos/git/toc.yml index 3a6a985e94d..58e1c9041da 100644 --- a/docs/repos/git/toc.yml +++ b/docs/repos/git/toc.yml @@ -14,7 +14,7 @@ href: clone.md - name: Import repo href: import-git-repository.md - - name: Import a repo from TFVC + - name: Import and migrate from TFVC href: import-from-TFVC.md - name: Use Visual Studio with Git href: ../tfvc/use-visual-studio-git.md @@ -22,7 +22,7 @@ items: - name: Connect to a project or repo href: ../../organizations/projects/connect-to-projects.md?toc=/azure/devops/repos/toc.json - - name: Authentication + - name: Git Authentication Overview href: auth-overview.md - name: Authenticate with SSH href: use-ssh-keys-to-authenticate.md @@ -147,6 +147,8 @@ href: pull-request-templates.md - name: Extend pull request workflows with pull request status href: pull-request-status.md + - name: Configure custom target branches for pull requests + href: pull-request-targets.md - name: History items: - name: Review history @@ -157,8 +159,8 @@ href: git-log-history-simplification.md - name: Cross-service operations items: - - name: Configure repos to link to work items - href: configure-repos-work-tracking.md + - name: Cross-service overview + href: ../../cross-service/cross-service-overview.md - name: Auto complete work items with pull requests href: ../../boards/work-items/auto-complete-work-items-pull-requests.md?toc=/azure/devops/repos/toc.json - name: Drive Git development from a work item @@ -187,8 +189,8 @@ href: ../tfvc/git-permission-command.md - name: tf git view href: ../tfvc/git-view-command.md - - name: Go get using Azure Repos - href: go-get.md + - name: Go install using Azure Repos + href: go-install.md - name: Reference items: - name: Default Git permissions (Security) @@ -199,6 +201,8 @@ href: howto.yml - name: Git limits href: limits.md + - name: Repository health + href: repo-health.md - name: Map TFVC actions to Git href: mapping-my-tfvc-actions-to-git.md - name: RPC failures & http.postBuffer diff --git a/docs/repos/git/undo.md b/docs/repos/git/undo.md index 5701aac0864..84b79c65e10 100644 --- a/docs/repos/git/undo.md +++ b/docs/repos/git/undo.md @@ -29,6 +29,10 @@ In this article you learn how to: > * Revert a branch to a prior state > * Undo the changes made by a shared commit +## Prerequisites + +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] + ## Discard uncommitted changes to a file If you've made changes to a file but haven't committed those changes, you can use Git [checkout](https://git-scm.com/docs/git-checkout) to quickly discard the changes and revert the file to its last committed version. @@ -36,7 +40,7 @@ If you've made changes to a file but haven't committed those changes, you can us Git `checkout` can also revert a file to any committed version, when you specify the commit ID. > [!WARNING] -> If there's a chance you might want to reapply the changes that Git `checkout` would discard, consider [stashing](howto.yml#i-ve-done-some-work-but-need-to-switch-to-something-else--how-can-i-save-my-work-for-later-without-committing-the-changes-) those changes instead. +> If there's a chance you might want to reapply the changes that Git `checkout` would discard, consider [stashing](howto.yml#i-did-some-work-but-need-to-switch-to-something-else--how-can-i-save-my-work-for-later-without-committing-the-changes-) those changes instead. #### [Visual Studio 2022](#tab/visual-studio-2022) diff --git a/docs/repos/git/use-ssh-keys-to-authenticate.md b/docs/repos/git/use-ssh-keys-to-authenticate.md index 5d6c68f020e..6e37097d6e1 100644 --- a/docs/repos/git/use-ssh-keys-to-authenticate.md +++ b/docs/repos/git/use-ssh-keys-to-authenticate.md @@ -5,7 +5,8 @@ description: Learn how to authenticate to Azure Repos Git repositories with SSH ms.assetid: 2f89b7e9-3d10-4293-a277-30e26cae54c5 ms.service: azure-devops-repos ms.topic: conceptual -ms.date: 06/21/2023 +ms.date: 08/20/2024 +ms.author: sdanie monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git --- @@ -14,7 +15,7 @@ ms.subservice: azure-devops-repos-git [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can connect to your Git repos through SSH on macOS, Linux, or Windows to securely connect with HTTPS authentication. +You can connect to your Git repos through SSH on macOS, Linux, or Windows to securely connect with Azure DevOps. > [!IMPORTANT] > SSH URLs have changed, but old SSH URLs continue to work. If you've already set up SSH, update your remote URLs to the new format: @@ -38,11 +39,8 @@ The following steps cover configuration of SSH key authentication on the followi - macOS - Windows systems running [Git for Windows](https://www.git-scm.com/download/win) ->[!NOTE] -> As of Visual Studio 2017, SSH can be used to connect to Azure DevOps Git repositories. - > [!TIP] -> On Windows, we recommended the use of [Git Credential Manager](set-up-credential-managers.md) or [Personal Access Tokens](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). +> On Windows, we recommend the use of [Git Credential Manager](set-up-credential-managers.md) instead of SSH. ### Step 1: Create your SSH keys @@ -50,18 +48,25 @@ The following steps cover configuration of SSH key authentication on the followi > If you've already created RSA SSH keys on your system, skip this step and [configure your SSH keys](use-ssh-keys-to-authenticate.md#configuration). > To verify this go to your home directory and look into the `.ssh` folder (`%UserProfile%\.ssh\` on Windows or `~/.ssh/` on Linux, macOS, and Windows with Git Bash). If you see two files named `id_rsa` and `id_rsa.pub` respectively continue with [configuring your SSH keys](use-ssh-keys-to-authenticate.md#configuration). -To use key-based authentication, you first need to generate public/private key pairs for your client. **ssh-keygen.exe** is used to generate key files and the algorithms DSA, RSA, ECDSA, or Ed25519 can be specified. If no algorithm is specified, RSA is used. +To use key-based authentication, you first need to generate public/private key pairs for your client. **ssh-keygen.exe** is used to generate key files and the algorithms DSA, RSA, ECDSA, or Ed25519 can be specified. If no algorithm is specified, Ed25519 is used. >[!NOTE] > The only SSH key type supported by Azure DevOps is _RSA_. -To generate key files using the RSA algorithm, run the following command from a PowerShell or another shell such as `bash` on your client: +To generate key files using the RSA algorithm supported by Azure DevOps (either RSA-SHA2-256 or RSA-SHA2-512), run one of the following commands from a PowerShell or another shell such as `bash` on your client: ```powershell -ssh-keygen +ssh-keygen -t rsa-sha2-256 ``` -The output from the command should display the following output (where `username` is replaced by your username): +Or + +```powershell +ssh-keygen -t rsa-sha2-512 +``` + + +The output from the command should display the following output (where `username` is your username): ```Output Generating public/private rsa key pair. @@ -69,7 +74,7 @@ Enter file in which to save the key (C:\Users\username/.ssh/id_rsa): ``` You can press Enter to accept the default, or specify a path and/or filename where you would like your keys to be generated. -At this point, you'll be prompted to use a passphrase to encrypt your private key files. The passphrase can be empty but it's not recommended. +At this point, you're prompted to use a passphrase to encrypt your private key files. The passphrase can be empty but not recommended. The passphrase works with the key file to provide two-factor authentication. ```Output @@ -93,7 +98,7 @@ The key's randomart image is: +----[SHA256]-----+ ``` -Now you have a public/private rsa key pair in the location specified. The .pub files are public keys, and files without an extension are private keys: +Now you have a public/private RSA key pair in the location specified. The .pub files are public keys, and files without an extension are private keys: ```Output Mode LastWriteTime Length Name @@ -107,45 +112,43 @@ Mode LastWriteTime Length Name -::: moniker range=">= azure-devops-2019" ### Step 2: Add the public key to Azure DevOps Associate the public key generated in the previous step with your user ID. >[!NOTE] -> You have to repeat this operation for each organisation you have access to and want to use SSH with. +> You have to repeat this operation for each organization you have access to and want to use SSH with. -1. Open your security settings by browsing to the web portal and selecting the icon next to the avatar in the upper right of the - user interface. Select **SSH public keys** in the menu that appears. +1. Open your security settings by browsing to the web portal and selecting the icon next to the avatar in the upper right of the user interface. Select **SSH public keys** in the menu that appears. ![Screenshot that shows the SSH public keys menu item and the user avatar selected in Azure DevOps.](media/use-ssh-authentication/select-ssh-public-keys.png) -2. Select **+ New Key**. +1. Select **+ New Key**. ![Screenshot showing access to Security Configuration in Azure DevOps.](media/use-ssh-authentication/ssh_accessing_security_key.png) -3. Copy the contents of the public key (for example, `id_rsa.pub`) that you generated into the **Public Key Data** field. +1. Copy the contents of the public key (for example, `id_rsa.pub`) that you generated into the **Public Key Data** field. > [!IMPORTANT] > Avoid adding whitespace or new lines into the **Key Data** field, as they can cause Azure DevOps to use an invalid public key. When pasting in the key, a newline often is added at the end. Be sure to remove this newline if it occurs. ![Screenshot showing configuring a Public Key in Azure DevOps.](media/use-ssh-authentication/ssh_key_input.png) -4. Give the key a useful description (this description is displayed on the **SSH public keys** page for your profile) so that you can remember it later. Select **Save** to store the public key. +1. Give the key a useful description (this description is displayed on the **SSH public keys** page for your profile) so that you can remember it later. Select **Save** to store the public key. Once saved, you can't change the key. You can delete the key or create a new entry for another key. There are no restrictions on how many keys you can add to your user profile. Also note that SSH keys stored in Azure DevOps expire after one year. If your key expires, you may upload a new key or the same one to continue accessing Azure DevOps via SSH. -5. On the overview page a note is displayed at the top containing the server fingerprints. Make note of them because they will be required when you first connect to Azure DevOps via SSH. +1. On the **SSH Public Keys** overview page, the server fingerprints are displayed. Make note of the SHA256 fingerprint to use when you first connect to Azure DevOps via SSH. ![Screenshot of accessing security configuration in Azure DevOps Services.](media/use-ssh-authentication/ssh_accessing_security_key.png) -6. Test the connection by running the following command: +1. Test the connection by running the following command: ```powershell ssh -T git@ssh.dev.azure.com ``` - If this was the first time connecting you should receive the following output: + If you're connecting for the first time, you should receive the following output: ```Output The authenticity of host 'ssh.dev.azure.com ()' can't be established. @@ -154,84 +157,19 @@ Associate the public key generated in the previous step with your user ID. Are you sure you want to continue connecting (yes/no/[fingerprint])? ``` - Compare the given fingerprint with the fingerprints offered on the aforementioned settings page. Proceed only if they match! + Compare the fingerprint with the SHA256 fingerprint displayed on the previously mentions **SSH Public Keys** page. +Proceed only if they match! - If everything is configured correctly the output should look like this: +1. Enter `yes` to continue. If everything is configured correctly, the output should look like this: ```Output - remote: Shell access is not supported. + Warning: Permanently added 'ssh.dev.azure.com' (RSA) to the list of known hosts. + remote: Shell access is not supported. + shell request failed on channel 0 ``` If not, see the section on [Questions and troubleshooting](#questions-and-troubleshooting). - - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -### Step 2: Add the public key to Azure DevOps - -Associate the public key generated in the previous step with your user ID. - ->[!NOTE] -> You have to repeat this operation for each organisation you have access to and want to use SSH for. - -1. Open your security settings by browsing to the web portal and selecting your avatar in the upper right of the - user interface. Select **Security** in the menu that appears. - - ![Screenshot showing User Profile access in Azure DevOps.](media/use-ssh-authentication/ssh_profile_access.png) - -2. Select **+ New Key**. - - ![Screenshot showing Security Configuration in Azure DevOps.](media/use-ssh-authentication/ssh_accessing_security_key.png) - -3. Copy the contents of the public key (for example, `id_rsa.pub`) that you generated into the **Public Key Data** field. - - >[!NOTE] - > You can use the command `$ cat ~/.ssh/id_rsa.pub` to print the contents of the id_rsa.pub file in the terminal, then copy this to your clipboard. - > If your SSH public key file has a different name than the example code, modify the filename to match your current setup. When you copy your key, don't add any new lines or whitespace. - > Alternatively, you can locate the hidden .ssh folder, open the file in your favorite text editor, and copy it to your clipboard. - - ![Screenshot showing configuration of a Public Key in Azure DevOps.](media/use-ssh-authentication/ssh_key_input.png) - - >[!IMPORTANT] - > Don't add whitespace or new lines into the **Key Data** field, as they can cause Azure DevOps to use an invalid public key. When you paste in the key, a new line often gets added at the end. Be sure to remove this new line if it occurs. - -4. Give the key a useful description (this description is displayed on the **SSH public keys** page for your profile) so that you can remember it later. Select **Save** to store the public key. Once saved, you can't change the key. You can delete the key or create a new entry for another key. There are no restrictions on how many keys you can add to your user profile. - -5. On the overview page a note is displayed at the top containing the server fingerprints. Make note of them because they will be required when you first connect to Azure DevOps with SSH. - - ![Screenshot showing where to locate server fingerprints in Azure DevOps Services.](media/use-ssh-authentication/ssh_accessing_security_key.png) - -6. Test the connection by running the following command: - - ```powershell - ssh -T git@ssh.dev.azure.com - ``` - - If this was the first time connecting you should receive the following output: - - ```Output - The authenticity of host 'ssh.dev.azure.com ()' can't be established. - RSA key fingerprint is SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og. - This key is not known by any other names - Are you sure you want to continue connecting (yes/no/[fingerprint])? - ``` - - Compare the given fingerprint with the fingerprints offered on the aforementioned settings page. Proceed only if they match! - - If everything is configured correctly the output should look like this: - - ```Output - remote: Shell access is not supported. - ``` - - If not, see the section on [Questions and troubleshooting](use-ssh-keys-to-authenticate.md#questions-and-troubleshooting). - - - -::: moniker-end ### Step 3: Clone the Git repository with SSH @@ -244,13 +182,13 @@ Associate the public key generated in the previous step with your user ID. [!INCLUDE [project-urls](../../includes/project-urls.md)] -2. Run `git clone` from the command prompt. +1. Run `git clone` from the command prompt. ```bash git clone git@ssh.dev.azure.com:v3/fabrikam-fiber/FabrikamFiber/FabrikamFiber ``` - You should now be prompted to enter your passphrase for your SSH key before you can continue unless it is managed by an SSH Agent: + If you aren't using an SSH Agent, you're prompted to enter your passphrase: ```Output Cloning into 'FabrikamFiber'... @@ -261,94 +199,148 @@ Associate the public key generated in the previous step with your user ID. Resolving deltas: 100% (15/15), done. ``` - If you are instead prompted to verify a fingerprint, please read [Step 2: Add the public key to Azure DevOps](use-ssh-keys-to-authenticate.md#step-2-add-the-public-key-to-azure-devops) again. For other problems read the section on [Questions and troubleshooting](use-ssh-keys-to-authenticate.md#questions-and-troubleshooting). + If you're instead prompted to verify a fingerprint, read [Step 2: Add the public key to Azure DevOps](use-ssh-keys-to-authenticate.md#step-2-add-the-public-key-to-azure-devops) again. For other problems, read the section on [Questions and troubleshooting](use-ssh-keys-to-authenticate.md#questions-and-troubleshooting). > [!TIP] > To make the most of SSH it is common to use an SSH Agent to manage your SSH key(s). Setting up an agent is beyond the scope of this article, though. ## Questions and troubleshooting -### Q: SSH cannot establish a connection. What should I do? +### Q: I see ssh-rsa related warnings. What should I do? -**A:** There are multiple different problems that you may experience: +**A:** There are two different warning messages could see: -```Output -Unable to negotiate with port 22: no matching host key type found. Their offer: ssh-rsa +```output +ssh-rsa is about to be deprecated and your request has been throttled. Please use rsa-sha2-256 or rsa-sha2-512 instead. Your session will continue automatically. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation. ``` -Modify your SSH config to downgrade your security settings for Azure DevOps by adding the following to your `~/.ssh/config` (`%UserProfile%\.ssh\config` on Windows) file: +Or + +```output +You’re using ssh-rsa that is about to be deprecated and your request has been blocked intentionally. Any SSH session using ssh-rsa is subject to brown out (failure during random time periods). Please use rsa-sha2-256 or rsa-sha2-512 instead. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation. +``` + +If you modified your SSH config to downgrade your security settings for Azure DevOps by adding the following to your `~/.ssh/config` (`%UserProfile%\.ssh\config` on Windows) file: ``` Host ssh.dev.azure.com vs-ssh.visualstudio.com HostkeyAlgorithms +ssh-rsa ``` -> [!IMPORTANT] -> OpenSSH deprecated the `ssh-rsa` public key signature algorithm in [version 8.2](https://www.openssh.com/txt/release-8.2) and disabled it by default in [version 8.8](https://www.openssh.com/txt/release-8.8). +Remove these lines now and make sure `rsa-sha2-256` and/or `rsa-sha2-512` are allowed. -```Output -Unable to negotiate with port 22: no matching MAC found. Their offer: hmac-sha2-256,hmac-sha2-512 -``` +For more information, see the [blog post](https://devblogs.microsoft.com/devops/ssh-rsa-deprecation/). -Modify your SSH config to downgrade your security settings for Azure DevOps by adding the following to your `~/.ssh/config` (`%UserProfile%\.ssh\config` on Windows) file: +### Q: SSH can't establish a connection. What should I do? -``` -Host ssh.dev.azure.com vs-ssh.visualstudio.com - MACs +hmac-sha2-512,+hmac-sha2-256 -``` +**A:** There are multiple different problems that you could experience: -```Output -Unable to negotiate with 22: no matching key exchange method found. Their offer: diffie-hellman-group1-sha1,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha256 -``` +- **Use of unsupported ssh-rsa** -Modify your SSH config to downgrade your security settings for Azure DevOps by adding the following to your `~/.ssh/config` (`%UserProfile%\.ssh\config` on Windows) file: + ```output + You’re using ssh-rsa that is unsupported. Please use rsa-sha2-256 or rsa-sha2-512 instead. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation. + ``` -``` -Host ssh.dev.azure.com vs-ssh.visualstudio.com - KexAlgorithms +diffie-hellman-group-exchange-sha256,+diffie-hellman-group14-sha1,+diffie-hellman-group1-sha1 -``` + If you modified your SSH config to downgrade your security settings for Azure DevOps by adding the following to your `~/.ssh/config` (`%UserProfile%\.ssh\config` on Windows) file: -> [!IMPORTANT] -> The key exchange algorithm `diffie-hellman-group1-sha1` has been disabled by default in [version 6.9](https://www.openssh.com/txt/release-6.9) of OpenSSH and `diffie-hellman-group14-sha1` in [version 8.2](https://www.openssh.com/txt/release-8.2). + ``` + Host ssh.dev.azure.com vs-ssh.visualstudio.com + HostkeyAlgorithms +ssh-rsa + ``` + + Remove these lines now and make sure `rsa-sha2-256` and/or `rsa-sha2-512` are allowed. + + For more information, see the [blog post](https://devblogs.microsoft.com/devops/ssh-rsa-deprecation/). + +- **No matching host key** + + This problem shouldn't happen on Azure DevOps Service or on more recent Azure DevOps Server versions as mentioned in the [blog post](https://devblogs.microsoft.com/devops/ssh-rsa-deprecation/). + + ```Output + Unable to negotiate with port 22: no matching host key type found. Their offer: ssh-rsa + ``` + + Modify your SSH config to downgrade your security settings for Azure DevOps by adding the following to your `~/.ssh/config` (`%UserProfile%\.ssh\config` on Windows) file: + + ``` + Host ssh.dev.azure.com vs-ssh.visualstudio.com + HostkeyAlgorithms +ssh-rsa + ``` + + > [!IMPORTANT] + > OpenSSH deprecated the `ssh-rsa` public key signature algorithm in [version 8.2](https://www.openssh.com/txt/release-8.2) and disabled it by default in [version 8.8](https://www.openssh.com/txt/release-8.8). + +- **No matching MAC** + + ```Output + Unable to negotiate with port 22: no matching MAC found. Their offer: hmac-sha2-256,hmac-sha2-512 + ``` + + Modify your SSH config to downgrade your security settings for Azure DevOps by adding the following to your `~/.ssh/config` (`%UserProfile%\.ssh\config` on Windows) file: + + ``` + Host ssh.dev.azure.com vs-ssh.visualstudio.com + MACs +hmac-sha2-512,+hmac-sha2-256 + ``` + +- **No matching key exchange method** + + ```Output + Unable to negotiate with 22: no matching key exchange method found. Their offer: diffie-hellman-group1-sha1,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha256 + ``` + + Modify your SSH config to downgrade your security settings for Azure DevOps by adding the following to your `~/.ssh/config` (`%UserProfile%\.ssh\config` on Windows) file: + + ``` + Host ssh.dev.azure.com vs-ssh.visualstudio.com + KexAlgorithms +diffie-hellman-group-exchange-sha256,+diffie-hellman-group14-sha1,+diffie-hellman-group1-sha1 + ``` + + > [!IMPORTANT] + > The key exchange algorithm `diffie-hellman-group1-sha1` has been disabled by default in [version 6.9](https://www.openssh.com/txt/release-6.9) of OpenSSH and `diffie-hellman-group14-sha1` in [version 8.2](https://www.openssh.com/txt/release-8.2). > [!TIP] > For self-hosted instances of Azure DevOps Server and TFS use the appropriate hostname in the `Host` line instead of `ssh.dev.azure.com vs-ssh.visualstudio.com`. ### Q: How can I have Git remember the passphrase for my key? -**A:** You can use an SSH Agent for that. Linux, macOS, and Windows (starting with [Windows 10 (build 1809)](/windows-server/administration/openssh/openssh_overview) or by using Git for Windows with Git Bash) all ship with an SSH Agent. The SSH Agent can be used to cache your SSH keys for repeated use. Please consult your SSH vendor's manual for details on how to use it. +**A:** You can use an SSH Agent. Linux, macOS, and Windows (starting with [Windows 10 (build 1809)](/windows-server/administration/openssh/openssh_overview) or by using Git for Windows with Git Bash) all ship with an SSH Agent. The SSH Agent can be used to cache your SSH keys for repeated use. Consult your SSH vendor's manual for details on how to use it. ### Q: I use [PuTTY](https://www.putty.org/) as my SSH client and generated my keys with PuTTYgen. Can I use these keys with Azure DevOps Services? -**A:** Yes. Load the private key with PuTTYgen, go to **Conversions** menu and select **Export OpenSSH key**. -Save the private key file and then follow the steps to [set up non-default keys](use-ssh-keys-to-authenticate.md#newkeys). +**A:** Yes. Load the private key with PuTTYgen, go to **Conversions** menu, and select **Export OpenSSH key**. +Save the private key file and then follow the steps to [set up nondefault keys](use-ssh-keys-to-authenticate.md#newkeys). Copy your public key directly from the PuTTYgen window and paste into the **Key Data** field in your security settings. ### Q: How can I verify that the public key I uploaded is the same key as my local key? **A:** You can verify the fingerprint of the public key uploaded with the one displayed in your profile through the following `ssh-keygen` command run against your public key using - the command line. You'll need to change the path and the public key filename if you aren't using the defaults. + the command line. You need to change the path and the public key filename if you aren't using the defaults. + +>[!NOTE] +> As of August/September 2024, we are migrating from MD5 to SHA-256 hashes. You may need to choose the correct function during the transition period. ```powershell -ssh-keygen -l -E md5 -f ~/.ssh/id_rsa.pub +ssh-keygen -l -E md5 -f -- use this for MD5 fingerprints +ssh-keygen -l -E sha256 -f -- use this for SHA-256 fingerprints ``` -You can then compare the MD5 signature to the one in your profile. This check is useful if you have connection problems or have concerns about incorrectly +You can then compare the signature to the one in your profile. This check is useful if you have connection problems or have concerns about incorrectly pasting in the public key into the **Key Data** field when adding the key to Azure DevOps. ### Q: How can I start using SSH in a repository where I'm currently using HTTPS? -**A:** You'll need to update the `origin` remote in Git to change over from an HTTPS to SSH URL. Once you have the [SSH clone URL](#step-3-clone-the-git-repository-with-ssh), run the following command: +**A:** You need to update the `origin` remote in Git to change over from an HTTPS to SSH URL. Once you have the [SSH clone URL](#step-3-clone-the-git-repository-with-ssh), run the following command: ``` git remote set-url origin ``` -Git commands accessing the remote called `origin` will now use SSH. +Git commands accessing the remote called `origin` uses SSH. - + ### Q: I'm using Git LFS with Azure DevOps Services and I get errors when pulling files tracked by Git LFS. @@ -356,12 +348,12 @@ Git commands accessing the remote called `origin` will now use SSH. -### Q: How can I use a non-default key location, that is, not ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub? +### Q: How can I use a nondefault key location, that is, not ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub? **A:** To use a key stored in a different place than the default, perform these two tasks: -1. The keys must be in a folder that only you can read or edit. If the folder has wider permissions, SSH won't use the keys. -2. You must let SSH know the location of the key, e.g. by specifying it as an "Identity" in the SSH config: +1. The keys must be in a folder that only you can read or edit. If the folder has wider permissions, SSH doesn't use the keys. +2. You must let SSH know the location of the key, for example, by specifying it as an "Identity" in the SSH config: ``` Host ssh.dev.azure.com @@ -369,31 +361,31 @@ Git commands accessing the remote called `origin` will now use SSH. IdentitiesOnly yes ``` -The `IdentitiesOnly yes` setting ensures that SSH will not use any other available identity to authenticate. This is particular important if more than one identity is available. +The `IdentitiesOnly yes` setting ensures that SSH doesn't use any other available identity to authenticate. This setting is particular important if more than one identity is available. ### Q: I have multiple SSH keys. How do I use the correct SSH key for Azure DevOps? -**A:** Generally, if you configure multiple keys for an SSH client and connect to an SSH server, the client can try the keys one at a time until the server accepts one. +**A:** Generally, when you configure multiple keys for an SSH client, the client attempts to authenticate with each key sequentially until the SSH server accepts one. -However, this doesn't work with Azure DevOps for technical reasons related to the SSH protocol and how our Git SSH URLs are structured. Azure DevOps will blindly accept the first key that the client provides during authentication. If that key is invalid for the requested repository, the request will fail without attempting other available keys due to the following error: +However, this approach doesn't work with Azure DevOps due to technical constraints related to the SSH protocol and the structure of our Git SSH URLs. Azure DevOps accepts the first key provided by the client during authentication. If this key is invalid for the requested repository, the request fails without attempting any other available keys, resulting in the following error: ``` remote: Public key authentication failed. fatal: Could not read from remote repository. ``` -For Azure DevOps, you'll need to configure SSH to explicitly use a specific key file. The procedure is the same as when using a key stored in a [non-default location](use-ssh-keys-to-authenticate.md#non-default-keys). Simply tell SSH to use the correct SSH key for the Azure DevOps host. +For Azure DevOps, you need to configure SSH to explicitly use a specific key file. The procedure is the same as when using a key stored in a [nondefault location](use-ssh-keys-to-authenticate.md#non-default-keys). Tell SSH to use the correct SSH key for the Azure DevOps host. ### Q: How do I use different SSH keys for different organizations on Azure DevOps? -**A:** Azure DevOps will blindly accept the first key that the client provides during authentication. If that key is invalid for the requested repository, the request will fail with the following error: +**A:** Azure DevOps blindly accepts the first key that the client provides during authentication. If that key is invalid for the requested repository, the request fails with the following error: ``` remote: Public key authentication failed. fatal: Could not read from remote repository. ``` -However, you can modify your SSH config to differentiate between different organizations and provide different keys for each. To do this you will need to use host aliases to create separate `Host` sections in your SSH configuration. This is because all hosted Azure DevOps URLs have the same hostname (`ssh.dev.azure.com`), so SSH has no way to distinguish them by default. +This failure is because all Azure DevOps URLs share the same hostname (`ssh.dev.azure.com`), making it impossible for SSH to distinguish between them by default. However, you can modify your SSH configuration to differentiate between different organizations by providing distinct keys for each. Use host aliases to create separate `Host` sections in your SSH configuration file. ``` # The settings in each Host section are applied to any Git SSH remote URL with a @@ -427,19 +419,19 @@ Host devops_contoso IdentitiesOnly yes ``` -Afterwards, instead of using the real URLs, tell Git you want to use these URLs for each repository as remote by replacing the hostname in the existing remotes with `devops_fabrikam` and `devops_contoso` respectively. For example `git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo` would become `git@devops_fabrikam:v3/Fabrikam/Project1/fab_repo`. +Afterwards, instead of using the real URLs, tell Git you want to use these URLs for each repository as remote by replacing the hostname in the existing remotes with `devops_fabrikam` and `devops_contoso` respectively. For example, `git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo` would become `git@devops_fabrikam:v3/Fabrikam/Project1/fab_repo`. ### Q: What notifications may I receive about my SSH keys? -**A:** Whenever you register a new SSH Key with Azure DevOps Services, you receive an email notification informing you that a new SSH key has been added to your account. +**A:** Whenever you register a new SSH Key with Azure DevOps Services, you receive an email notification informing you when a new SSH key is added to your account. ![SSH notification example](media/use-ssh-authentication/ssh_notification.png) ### Q: What do I do if I believe that someone other than me is adding SSH keys on my account? -**A:** If you receive a notification of an SSH key being registered and you didn't manually upload it to the service, your credentials may have been compromised. +**A:** If you receive an SSH key registration notification you didn't initiate, your credentials could be compromised. -The next step would be to investigate whether or not your password has been compromised. Changing your password is always a good first step to defend against this attack vector. If you're an Azure Active Directory user, talk with your administrator to check if your account was used from an unknown source/location. +The next step would be to investigate whether or not your password is compromised. Changing your password is always a good first step to defend against this attack vector. If you're a Microsoft Entra user, talk with your administrator to check if your account was used from an unknown source/location. ### Q: What do I do if I'm still prompted for my password and `GIT_SSH_COMMAND="ssh -v" git fetch` shows `no mutual signature algorithm` or `corresponding algo not in PubkeyAcceptedAlgorithms`? diff --git a/docs/repos/git/view-pull-requests.md b/docs/repos/git/view-pull-requests.md index 4e75a447a83..8a3098a7a48 100644 --- a/docs/repos/git/view-pull-requests.md +++ b/docs/repos/git/view-pull-requests.md @@ -10,6 +10,7 @@ author: vijayma ms.date: 03/31/2022 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-git +ms.custom: devx-track-azurecli --- # View, filter, and open pull requests @@ -25,32 +26,7 @@ There are several ways to list, filter, view, and open PRs for a project. ## Prerequisites -::: moniker range="azure-devops" -- **Repos** must be enabled on your project. If the **Repos** hub and associated pages don't display, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md) to reenable Repos. - -- To view PRs, you must be a member of the Azure DevOps project the PR is in, with **Basic** access or higher. If you aren't a project member, [get added](../../organizations/accounts/add-organization-users.md). - - > [!NOTE] - > For public projects, users granted **Stakeholder** access have full access to Azure Repos. -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" -- **Repos** must be enabled on your project. If the **Repos** hub and associated pages don't display, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md) to reenable Repos. -- To view PRs, you must be a member of the Azure DevOps project with **Basic** access or higher. If you aren't a project member, [get added](../../organizations/security/add-users-team-project.md). -::: moniker-end - -::: moniker range="< azure-devops-2019" -- To view or review PRs, you must be a member of the Azure DevOps project with **Basic** access or higher. If you aren't a project member, [get added](../../organizations/security/add-users-team-project.md). - -::: moniker-end - -- To learn more about permissions and access, see [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) and [About access levels](../../organizations/security/access-levels.md). - -::: moniker range=">= azure-devops-2020" - -- In Azure DevOps Services, you can manage PRs and other resources from the [Azure command-line interface (CLI)](/cli/azure/) with the `azure-devops` extension. To learn how to work with the Azure DevOps Services CLI, see [Get started with Azure DevOps CLI](../../cli/index.md). Azure Repos CLI commands for PRs use [az repos pr](/cli/azure/repos/pr). - -::: moniker-end +[!INCLUDE [azure-repos-prerequisites](includes/azure-repos-prerequisites.md)] ## List pull requests @@ -58,7 +34,7 @@ You can list PRs by using the Azure DevOps project website, Visual Studio, or th # [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. To list PRs in a specific repository in a project, [go to that project](../../project/navigation/go-to-project-repo.md) in the web portal and select **Repos** > **Pull requests**. @@ -80,22 +56,9 @@ You can list PRs by using the Azure DevOps project website, Visual Studio, or th ::: moniker-end -::: moniker range="tfs-2018" - -Manage PRs you own or are assigned to with the **Pull Requests** tab in the **Code** page on the web. - -![Screenshot of viewing completed and abandoned PRs in Azure Repos.](media/view-pull-requests/repos-code-pull-requests.png) - -::: moniker-end - - -::: moniker range="tfs-2018" - -You can view all of your PRs in your organization, across all projects, by choosing **My pull requests** from the **Projects** page. - -![View all my pull requests](media/view-pull-requests/view-all-pull-requests.png) + -::: moniker-end + # [Visual Studio](#tab/visual-studio) @@ -161,7 +124,6 @@ az repos pr list [--creator] The following command lists all PRs in the repository, regardless of status, and shows the output in a table. The example uses the default configuration `az devops configure --defaults organization=https://dev.azure.com/fabrikamprime project="Fabrikam Fiber"`. - ```azurecli az repos pr list --status all --output table @@ -186,7 +148,7 @@ ID Created Creator Title *** - + ## Define a custom pull request view @@ -194,7 +156,7 @@ Filtering the PR list helps you find and organize PRs to prioritize the most imp # [Browser](#tab/browser) -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" To filter the PR list, on the **Pull requests** page, select the **Filter** icon at upper right. Then select **Target branch** or other column header, and select the branch or other value you want to filter on. @@ -264,10 +226,9 @@ az repos pr list --creator "My Name" --status all --top 1 [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] - *** - + ## Open a pull request @@ -293,10 +254,8 @@ In Visual Studio 2019, you can check out a PR's source branch directly from the ![Screenshot that shows Checkout source branch.](./media/view-pull-requests/checkout-pr-source-branch.png) - [!INCLUDE [temp](includes/note-new-git-tool.md)] - # [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" @@ -367,9 +326,6 @@ az repos pr checkout --id 21 *** - - - To review changes, make comments or suggestions, or approve or vote on the PR, see [Review pull requests](review-pull-requests.md). ## View and update pull requests from a mobile device diff --git a/docs/repos/index.yml b/docs/repos/index.yml index 331a5dfde0c..ce8137bc240 100644 --- a/docs/repos/index.yml +++ b/docs/repos/index.yml @@ -112,6 +112,8 @@ landingContent: url: ./tfvc/create-work-workspaces.md - text: Branch folders and files url: ./tfvc/branch-folders-files.md + - text: Migration of custom check-in policies + url: ./tfvc/tfvc-check-in-policy-migrate-guide.md - linkListType: reference links: - text: TFVC command reference diff --git a/docs/repos/integrations/media/integrations-slack/add-to-slack.png b/docs/repos/integrations/media/integrations-slack/add-to-slack.png new file mode 100644 index 00000000000..d4e1974ebd7 Binary files /dev/null and b/docs/repos/integrations/media/integrations-slack/add-to-slack.png differ diff --git a/docs/repos/integrations/media/integrations-slack/complete-authentication.png b/docs/repos/integrations/media/integrations-slack/complete-authentication.png new file mode 100644 index 00000000000..f083ca71e20 Binary files /dev/null and b/docs/repos/integrations/media/integrations-slack/complete-authentication.png differ diff --git a/docs/repos/integrations/media/integrations-slack/signed-in-confirmation.png b/docs/repos/integrations/media/integrations-slack/signed-in-confirmation.png new file mode 100644 index 00000000000..8c59ca4b601 Binary files /dev/null and b/docs/repos/integrations/media/integrations-slack/signed-in-confirmation.png differ diff --git a/docs/repos/integrations/media/integrations-slack/slack-integration-accept.png b/docs/repos/integrations/media/integrations-slack/slack-integration-accept.png new file mode 100644 index 00000000000..6e82d055a6f Binary files /dev/null and b/docs/repos/integrations/media/integrations-slack/slack-integration-accept.png differ diff --git a/docs/repos/integrations/media/integrations-slack/url-unfurling.png b/docs/repos/integrations/media/integrations-slack/url-unfurling.png index 638e8fe33e0..39b555ea7e8 100644 Binary files a/docs/repos/integrations/media/integrations-slack/url-unfurling.png and b/docs/repos/integrations/media/integrations-slack/url-unfurling.png differ diff --git a/docs/repos/integrations/media/integrations-slack/verification-code-enter-in-chat.png b/docs/repos/integrations/media/integrations-slack/verification-code-enter-in-chat.png new file mode 100644 index 00000000000..b89bfdf9e9b Binary files /dev/null and b/docs/repos/integrations/media/integrations-slack/verification-code-enter-in-chat.png differ diff --git a/docs/repos/integrations/media/troubleshooting/third-party-app-consent.png b/docs/repos/integrations/media/troubleshooting/third-party-app-consent.png index 4e8adf078d6..51e398186fe 100644 Binary files a/docs/repos/integrations/media/troubleshooting/third-party-app-consent.png and b/docs/repos/integrations/media/troubleshooting/third-party-app-consent.png differ diff --git a/docs/repos/integrations/repos-slack.md b/docs/repos/integrations/repos-slack.md index 11e67c2a6be..14183850d39 100644 --- a/docs/repos/integrations/repos-slack.md +++ b/docs/repos/integrations/repos-slack.md @@ -1,7 +1,7 @@ --- title: Azure Repos with Slack titleSuffix: Azure Repos -description: Monitor Azure Repos from Slack +description: Monitor Azure Repos from Slack. ms.service: azure-devops ms.subservice: azure-devops-integration ms.topic: how-to @@ -10,169 +10,171 @@ ms.manager: bijuv ms.author: Divais author: Divais monikerRange: 'azure-devops' -ms.date: 10/21/2019 +ms.date: 04/30/2024 --- # Azure Repos with Slack [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -If you use [Slack](https://slack.com), you can use the [Azure Repos app for Slack](https://azchatopprodcus1.azchatops.visualstudio.com/_slack/installreposapp) to easily monitor your Azure Repos repositories. You -can set up and manage subscriptions to receive notifications in your channel whenever code is pushed/checked -in and whenever a pull request (PR) is created, updated or a merge is attempted. This app supports both Git and -Team Foundation Version Control (TFVC) events. - -> [!div class="mx-imgBorder"] -> ![Notifications image](media/integrations-slack/notifications.png) - -Read this article to learn how to: - -> [!div class="checklist"] -> * Add the Azure Repos app to your Slack workspace -> * Connect Azure Repos app to your repositories -> * Manage subscriptions to repository related events in your Slack channel -> * Using filters effectively to customize subscriptions -> * Get notifications in private Slack channels - +If you use [Slack](https://slack.com), you can use the [Azure Repos app for Slack](https://azchatopprodcus1.azchatops.visualstudio.com/_slack/installreposapp) to easily monitor your Azure Repos repositories. Set up and manage subscriptions to receive notifications in your channel whenever code is pushed or checked in and whenever a pull request (PR) gets created, updated, or merged. This app supports both Git and Team Foundation Version Control (TFVC) events. ## Prerequisites -- To create subscriptions in a Slack channel for repository-related events, you must be a member of the **Project Administrators** group, or a team administrator. To get added, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) or [Add a team administrator](../../organizations/settings/add-team-administrator.md). -- To receive notifications, the **Third-party application access via OAuth** setting must be enabled for the organization. See [Change application -access policies for your organization](../../organizations/accounts/change-application-access-policies.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To create subscriptions in a Slack channel for repository-related events: Member of the **Project Administrators** group or team administrator. For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) or [Add a team administrator](../../organizations/settings/add-team-administrator.md).
      - To receive notifications: **Third-party application access via OAuth** setting enabled for the organization. For more information, see [Change application access policies for your organization](../../organizations/accounts/change-application-access-policies.md).| > [!NOTE] -> * Notifications are currently not supported inside direct messages. -> * You can only link the Azure Repos app for Slack to a project hosted on Azure DevOps Services at this time. +> * You can only link the Azure Repos app for Slack to a project hosted on Azure DevOps Services. +> * Notifications aren't supported inside direct messages. ## Add the Azure Repos app to your Slack workspace -1. Navigate to the [Azure Repos Slack app](https://azchatopprodcus1.azchatops.visualstudio.com/_slack/installreposapp) to install the Azure Repos app to your Slack workspace. - -2. Once added, you'll see a welcome message from the app as shown in the following image. +1. Go to the [Azure Repos Slack app](https://azchatopprodcus1.azchatops.visualstudio.com/_slack/installreposapp) and select **Add to Slack**. + + > [!div class="mx-imgBorder"] + > ![Screenshot of Slack app directory, Azure Repos and button, Add to Slack.](./media/integrations-slack/add-to-slack.png) + + Once added, you receive something like the following welcome message. > [!div class="mx-imgBorder"] - > ![Welcome message](./media/integrations-slack/welcome-message.png) + > ![Screenshot of Welcome message from Slack.](./media/integrations-slack/welcome-message.png) 3. Use the `/azrepos` Slack handle to interact with the app. A full list of commands is provided in the [Command reference](#command-reference) section of this article. - ## Connect the Azure Repos app to your repositories -1. Once the app has been installed in your Slack workspace, connect and authenticate yourself to Azure Repos using `/azrepos signin` command. +1. Connect and authenticate yourself to Azure Repos using `/azrepos signin` command. > [!div class="mx-imgBorder"] - > ![Sign in prompt image ](./media/integrations-slack/sign-in.png) + > ![Screenshot of Sign in prompt for Slack.](./media/integrations-slack/sign-in.png) -2. To start monitoring all Git repositories in a project, use the following slash command inside a channel: +2. Select **Sign in**. +3. **Accept** the Azure Repos Slack Integration. + + > [!div class="mx-imgBorder"] + > ![Screenshot of Accept button in resulting sign-in screen.](./media/integrations-slack/slack-integration-accept.png) - ``` - /azrepos subscribe [project url] - ``` - The project URL can be to any page within your project (except URLs to repositories). + A verification code displays for use in your chat app to complete authentication. - For example: +4. Copy the authentication code. - ``` - /azrepos subscribe https://dev.azure.com/myorg/myproject/ - ``` + > [!div class="mx-imgBorder"] + > ![Screenshot of verification code provided by Azure Repos.](./media/integrations-slack/verification-code-enter-in-chat.png) - You can also monitor a specific repository using the following command: +5. Select **Enter code**, paste the code, and then select **Submit**. - ``` - /azrepos subscribe [repository url] - ``` + > [!div class="mx-imgBorder"] + > ![Screenshot of final authentication screen when verification code is pasted and then submit button is selected.](./media/integrations-slack/complete-authentication.png) - The repository URL can be to any page within your repository that has your repository name. + Confirmation of sign-in displays within the chat. - For example, for Git repositories, use: + :::image type="content" source="media/integrations-slack/signed-in-confirmation.png" alt-text="Screenshot sign-in confirmation in chat."::: - ``` - /azrepos subscribe https://dev.azure.com/myorg/myproject/_git/myrepository - ``` +To start monitoring all Git repositories in a project, use the following slash command inside a channel: - For TFVC repositories, use: +```slash command +/azrepos subscribe [project url] +``` - ``` - /azrepos subscribe https://dev.azure.com/myorg/myproject/_versionControl - ``` - - > [!NOTE] - > You can subscribe only to public repositories. +The project URL can be to any page within your project (except URLs to repositories). For example: -3. The subscribe command gets you started with a default subscription. For Git repositories, the channel is subscribed to the **Pull request created** event (with target branch = master), and for TFVC repositories, the channel is subscribed to the **Code checked in** event. +```slash command +/azrepos subscribe https://dev.azure.com/myorg/myproject/ +``` - > [!div class="mx-imgBorder"] - > ![Default subscriptions creation message](./media/integrations-slack/subscriptions-added-confirmation.png) +You can also monitor a specific repository using the following command: +```slash command +/azrepos subscribe [repository url] +``` -## Manage subscriptions +The repository URL can be to any page within your repository that has your repository name. For example, for Git repositories, use: -To view, add and remove subscriptions for a channel, use the `subscriptions` command: +```slash command +/azrepos subscribe https://dev.azure.com/myorg/myproject/_git/myrepository +``` +For TFVC repositories, use: + +```slash command +/azrepos subscribe https://dev.azure.com/myorg/myproject/_versionControl ``` -/azrepos subscriptions + +> [!NOTE] +> You can only subscribe to public repositories. + +The subscribe command gets you started with a default subscription. For Git repositories, the channel is subscribed to the **Pull request created** event (with target branch = main), and for TFVC repositories, the channel is subscribed to the **Code checked in** event. + +> [!div class="mx-imgBorder"] +> ![Screenshot shows Default subscriptions creation message.](./media/integrations-slack/subscriptions-added-confirmation.png) + +## Manage subscriptions + +To view, add, or remove subscriptions for a channel, use the following `subscriptions` command: + +```slash command +/azrepos subscriptions ``` This command lists all the current subscriptions for the channel and allows you to add new subscriptions or remove existing ones. When adding subscriptions, you can customize the notifications you get by using various filters, as described in the following section. -[!NOTE] -Team administrators aren't able to remove or modify subscriptions created by Project administrators. +>[!NOTE] +>Team administrators can't remove or modify subscriptions created by Project administrators. > [!div class="mx-imgBorder"] -> ![View subscriptions](./media/integrations-slack/subscriptions-list.png) +> ![Screenshot showing View of subscriptions list.](./media/integrations-slack/subscriptions-list.png) -## Using filters effectively to customize subscriptions +## Use filters to customize subscriptions -When a user subscribes to a repository using `/azrepos subscribe` command, a default subscription is created. Often, users have the need -to customize these subscriptions. For example, users may want to get notified only when PRs have a specific reviewer. +When a user subscribes to a repository using the `/azrepos subscribe` command, a default subscription gets created. Often, users need to customize these subscriptions. For example, users might want to get notified only when PRs have a specific reviewer. The following steps demonstrate how to customize subscriptions. 1. Run the `/azrepos subscriptions` command. -2. In the list of subscriptions, if there is a subscription that is unwanted or must be modified (Example: creating noise in the channel), select the **Remove** button. +2. In the list of subscriptions, if there's a subscription that is unwanted or must be modified (Example: creating noise in the channel), select the **Remove** button. 3. Select the **Add subscription** button. 4. Select the required repository and the desired event. -5. Select the appropriate filters to customize your subscription. +5. Select the appropriate filters. ### Example: Get notifications only when my team is in the reviewer list for a PR > [!div class="mx-imgBorder"] -> ![Reviewer has my team](./media/integrations-slack/reviewer-filters.png) +> ![Screenshot shows Reviewer has my team.](./media/integrations-slack/reviewer-filters.png) ### Example: Tell me when merge attempts fail due to a policy violation > [!div class="mx-imgBorder"] -> ![Merge attempt unsuccessful – due to policy violation](./media/integrations-slack/merge-filters.png) +> ![Screenshot show Merge attempt unsuccessful – due to policy violation.](./media/integrations-slack/merge-filters.png) > [!NOTE] ->* All the filters are typically drop-downs. However if the drop-down were to have greater than 100 items, then users are asked to enter the values manually. +>* All the filters are typically drop-downs. But if the drop-down has greater than 100 items, then users must enter the values manually. >* For the TFVC **Code Checked in** event, the filter **Under path** must be of the format `$/myproject/path`. -## Previews of pull request URLs +## Preview pull request URLs -When a user pastes the URL of a PR, a preview is shown like the one in the following image. This helps to keep PR-related conversations contextual and accurate. +When a user pastes the URL of a PR, a preview display like the following image, which helps to keep PR-related conversations contextual and accurate. > [!div class="mx-imgBorder"] -> ![URL unfurling](./media/integrations-slack/url-unfurling.png) +> ![Screenshot shows URL unfurling.](./media/integrations-slack/url-unfurling.png) -For this feature to work, users have to be signed-in. Once they are signed in, this feature will work for all channels in a workspace. +Once users sign in, this feature works for all channels in a workspace. ## Remove subscriptions and repositories from a channel -- Many a time, users want to clean up their channel by removing repositories and subscriptions. Use the below command to achieve the same. +Use the following command to clean up your channel by removing repositories and subscriptions. - ``` - /azrepos unsubscribe all [project url] - ``` +```slash command +/azrepos unsubscribe all [project url] +``` - For example: +For example, the following command deletes all the subscriptions related to any repository in the project and removes the repositories from the channel. Only project admins can run this command. - ``` - /azrepos unsubscribe all https://dev.azure.com/myorg/myproject - ``` -This command will delete all the subscriptions related to any repository in the project and removes the repositories from the channel. Only project admins can run this command. +```slash command +/azrepos unsubscribe all https://dev.azure.com/myorg/myproject +``` ## Command reference @@ -180,37 +182,34 @@ The following table lists all the `/azrepos commands` you can use in your Slack |Slash command | Functionality | | -------------------- |----------------| -| /azrepos subscribe [repository url/ project url] | Subscribe to a repository or all repositories in a project to receive notifications | +| /azrepos subscribe [repository url/ project url] | Subscribe to a repository or all repositories in a project for notifications | | /azrepos subscriptions | Add or remove subscriptions for this channel | | /azrepos signin | Sign in to your Azure Repos organization | | /azrepos signout | Sign out from your Azure Repos organization | | /azrepos feedback | Report a problem or suggest a feature | | /azrepos unsubscribe all [project url] | Remove all repositories (belonging to a project) and their associated subscriptions from a channel | +### Notifications in private channels -### Notifications in Private channels - -The Azure Repos app can help you monitor the repository events in your private channels as well. You will need to invite the bot to your private channel by -using `/invite @azrepos`. Post that, you can set up and manage your notifications the same way as you would for a public channel. - +The Azure Repos app can help you monitor the repository events in your private channels, too. Invite the bot to your private channel by using `/invite @azrepos`. Then, you can manage your notifications the same way you would for a public channel. -## Troubleshooting +## Troubleshoot -If you are experiencing the following errors when using the [Azure Repos App for Slack](https://azchatopprodcus1.azchatops.visualstudio.com/_slack/installreposapp), follow the procedures in this section. +If you're experiencing the following errors when using the [Azure Repos App for Slack](https://azchatopprodcus1.azchatops.visualstudio.com/_slack/installreposapp), follow the procedures in this section. [!INCLUDE [troubleshooting](./includes/repos-troubleshoot-authentication.md)] In the **same browser**, start a new tab, navigate to `https://slack.com`, and sign in to your work space (**use web client**). Run the `/azrepos signout` command followed by the `/azrepos signin` command. -Select the `Sign in` button and you'll be redirected to a consent page like the one in the following example. Ensure that the directory shown beside the email is same as what was chosen in the previous step. Accept and complete the sign in process. +Select the `Sign in` button and you're redirected to a consent page like the one in the following example. Ensure that the directory shown beside the email is same as what was chosen in the previous step. Accept and complete the sign in process. > [!div class="mx-imgBorder"] -> ![Consent to the requested app permissions](media/troubleshooting/repos-consent-page-slack.png) +> ![Screenshot shows Consent to the requested app permissions.](media/troubleshooting/repos-consent-page-slack.png) If these steps don't resolve your authentication issue, reach out to us at [Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). ## Related articles -- [Azure Boards with Slack](../../boards/integrations/boards-slack.md) -- [Azure Pipelines with Slack](../../pipelines/integrations/slack.md) -- [Create a service hook for Azure DevOps with Slack](../../service-hooks/services/slack.md) \ No newline at end of file +- [Integrate Azure Boards with Slack](../../boards/integrations/boards-slack.md) +- [Integrate Azure Pipelines with Slack](../../pipelines/integrations/slack.md) +- [Create a service hook with Slack](../../service-hooks/services/slack.md) diff --git a/docs/repos/integrations/repos-teams.md b/docs/repos/integrations/repos-teams.md index 66b59d8792d..2535443ae44 100644 --- a/docs/repos/integrations/repos-teams.md +++ b/docs/repos/integrations/repos-teams.md @@ -31,12 +31,13 @@ In this article, learn how to do the following tasks: ## Prerequisites -- Manage your subscription, so you receive notifications in your channel whenever code gets pushed or checked in, or when a pull request (PR) gets created, updated, or merged. To create subscriptions for repo-related events, you must be a member of the **Project Administrators** group, or a team administrator. To get added, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) or [Add a team administrator](../../organizations/settings/add-team-administrator.md). -- To receive notifications, enable the **Third-party application access via OAuth** setting for the Azure DevOps organization. See [Change application access policies for your organization](../../organizations/accounts/change-application-access-policies.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To create subscriptions for repo-related events: Member of the **Project Administrators** group or team administrator. For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) or [Add a team administrator](../../organizations/settings/add-team-administrator.md).
      - To receive notifications: **Third-party application access via OAuth** setting enabled for the Azure DevOps organization. For more information, see [Change application access policies for your organization](../../organizations/accounts/change-application-access-policies.md).| > [!NOTE] -> * Notifications are currently not supported inside direct messages. > * You can only link the Azure Repos app for Microsoft Teams to a project hosted on Azure DevOps Services. +> * Notifications aren't supported inside direct messages. ## Add the Azure Repos app to a team in Microsoft Teams @@ -113,7 +114,7 @@ To help users search and share information about pull requests, Azure Repos app ## Preview pull request URLs -When you paste the URL of a PR, a preview shows like the one in the following image, which helps to keep PR-related conversations contextual and accurate. You must be signed in, and then you can preview PRs for URLs in all channels in a Team. +When you paste the URL of a PR, a preview shows like the one in the following image, which helps to keep PR-related conversations contextual and accurate. Be signed in, and then you can preview PRs for URLs in all channels in a Team. :::image type="content" source="media/integrations-slack/URL-Preview.png" alt-text="Screenshot showing URL unfurling."::: diff --git a/docs/repos/security/configure-github-advanced-security-features.md b/docs/repos/security/configure-github-advanced-security-features.md index ba9eaccd2b3..3fde198cab3 100644 --- a/docs/repos/security/configure-github-advanced-security-features.md +++ b/docs/repos/security/configure-github-advanced-security-features.md @@ -6,91 +6,103 @@ ms.service: azure-devops ms.subservice: azure-devops-integration ms.topic: how-to ms.custom: cross-service -ms.author: jukullam -author: juliakm +ms.author: laurajiang +author: laurajjiang monikerRange: 'azure-devops' -ms.date: 05/09/2023 +ms.date: 02/20/2025 --- # Configure GitHub Advanced Security for Azure DevOps -GitHub Advanced Security for Azure DevOps adds GitHub Advanced Security's suite of security features to Azure Repos. +GitHub Advanced Security for Azure DevOps adds GitHub Advanced Security's suite of security features to Azure Repos and includes the following features: -GitHub Advanced Security for Azure includes: * Secret Scanning push protection: check if code pushes include commits that expose secrets such as credentials * Secret Scanning repo scanning: scan your repository and look for exposed secrets that were committed accidentally * Dependency Scanning – search for known vulnerabilities in open source dependencies (direct and transitive) * Code Scanning – use CodeQL static analysis engine to identify code-level application vulnerabilities such as SQL injection and authentication bypass -At this time, GitHub Advanced Security for Azure DevOps is only available for Azure DevOps service and there are no plans to bring this product to Azure DevOps Server. +GitHub Advanced Security for Azure DevOps is only available for Azure DevOps Services and specifically for code Git repositories. [!INCLUDE [GitHub Advanced Security for Azure DevOps is different from GitHub Advanced Security.](includes/github-advanced-security.md)] ## Prerequisites -You have permissions allocated as a member of the Project Collection Administrators group. To add members to the Project Collection Administrators group or change a project collection-level permission see [Change project collection-level permissions](../../organizations/security/change-organization-collection-level-permissions.md). +[!INCLUDE [github-advanced-security-prerequisites](includes/github-advanced-security-prerequisites.md)] ### Extra prerequisites for self-hosted agents -If your organization uses self-hosted agents, there are more requirements: - -* Add these URLs to your Allowlist to allow for the dependency scanning task to fetch vulnerability advisory data. Learn more about [Allowed IP addresses and domain URLs](../../organizations/security/allow-list-ip-url.md). +If your organization uses self-hosted agents, add the following URLs to your Allowlist so the dependency scanning task can fetch vulnerability advisory data. For more information, see [Allowed IP addresses and domain URLs](../../organizations/security/allow-list-ip-url.md). | Domain URL  | Description | | ----------- | ----------- | -| `https://governance.dev.azure.com/{organization_name}` | For organizations using the dev.azure.com domain to access their DevOps instance  | -| `https://dev.azure.com/{organization_name}` | For organizations using the dev.azure.com domain to access their DevOps instance | -| `https://{organization_name}.governance.visualstudio.com/` | For organizations using the {organization_name}.visualstudio.com domain to access their DevOps instance   | +| `https://governance.dev.azure.com` | For organizations using the dev.azure.com domain to access their DevOps instance  | +| `https://dev.azure.com` | For organizations using the dev.azure.com domain to access their DevOps instance | +| `https://advsec.dev.azure.com` | For organizations using the dev.azure.com domain to access their DevOps instance | +| `https://{organization_name}.governance.visualstudio.com` | For organizations using the {organization_name}.visualstudio.com domain to access their DevOps instance   | | `https://{organization_name}.visualstudio.com`  | For organizations using the {organization_name}.visualstudio.com domain to access their DevOps instance | +| `https://{organization_name}.advsec.visualstudio.com` | For organizations using the {organization_name}.visualstudio.com domain to access their DevOps instance -* Run a compatible version of the .NET runtime (currently .NET 6.0.x). If a compatible version isn't present on the agent, the dependency scanning build task downloads [.NET](https://visualstudio.microsoft.com/downloads/). - -* Install the CodeQL bundle to the agent tool cache: - 1. Pick the latest CodeQL release bundle from [GitHub](https://github.com/github/codeql-action/releases). - 2. Download and unzip the bundle to the following directory inside the agent tools directory, typically located under `_work/_tools`: `./CodeQL/0.0.0-[codeql-release-bundle-tag (i.e. codeql-bundle-20221105)]/x64/`. Learn more about the [agent tools directory](https://github.com/microsoft/azure-pipelines-tool-lib/blob/master/docs/overview.md#tool-cache). - 3. Create an empty file at `./CodeQL/0.0.0-[codeql-release-bundle-tag (i.e. codeql-bundle-20221105)]/x64.complete` - +* Run a compatible version of the .NET runtime (currently .NET 8.x). If a compatible version isn't present on the agent, the dependency scanning build task downloads [.NET](https://visualstudio.microsoft.com/downloads/). +* Ensure the CodeQL bundle is installed to the agent tool cache on your agent. You might utilize the `enableAutomaticCodeQLInstall: true` variable with the `AdvancedSecurity-Codeql-Init@1` pipeline task for YAML pipelines or select the `Enable automatic CodeQL detection and installation` checkbox for classic pipelines. Alternatively, for manual installation instructions, see [Code scanning for GitHub Advanced Security for Azure DevOps](github-advanced-security-code-scanning-troubleshoot.md#manual-installation-of-codeql-bundle-to-self-hosted-agent). + ## Enable GitHub Advanced Security -To access each of the scanning tools and results, you need to first enable Advanced Security for your repository. Once you enable Advanced Security, any future pushes containing secrets to a repository with this policy enabled are blocked, and repository secret scanning happens in the background. +You can enable Advanced Security at the organization, project, or repository level. To access each of the scanning tools and results, you need to first enable Advanced Security. Once you enable Advanced Security, any future pushes containing secrets to a repository with this policy enabled are blocked, and repository secret scanning happens in the background. +#### Repository-level onboarding 1. Go to your **Project settings** for your Azure DevOps project. 1. Select **Repos** > **Repositories**. 1. Select the repository you want to enable Advanced Security for. 1. Select **Enable** and **Begin billing to activate Advanced Security**. A shield icon now appears in the repository view for any repository with Advanced Security enabled. -![Screenshot of enabling GitHub Advanced Security](media/enable-github-advanced-security.png) +:::image type="content" source="media/enable-github-advanced-security.png" lightbox="media/enable-github-advanced-security.png" alt-text="Screenshot of enabling GitHub Advanced Security."::: + +#### Project-level onboarding +1. Go to your **Project settings** for your Azure DevOps project. +1. Select **Repos**. +1. Select the **Settings** tab. +1. Select **Enable all** and see an estimate for the number of active committers for your project appear. +1. Select **Begin billing** to activate Advanced Security for every existing repository in your project. +1. Optionally, select **Automatically enable Advanced Security for new repositories** so that any newly created repositories have Advanced Security enabled upon creation. + +:::image type="content" source="media/enable-github-advanced-security-project.png" lightbox="media/enable-github-advanced-security-project.png" alt-text="Screenshot of project-level enablement for Advanced Security."::: + +#### Organization-level onboarding +1. Go to your **Organization settings** for your Azure DevOps organization. +1. Select **Repositories**. +1. Select **Enable all** and see an estimate for the number of active committers for your organization appear. +1. Select **Begin billing** to activate Advanced Security for every existing repository in each project in your organization. +1. Optionally, select **Automatically enable Advanced Security for new repositories** so that any newly created projects have Advanced Security enabled upon creation. + +:::image type="content" source="media/enable-github-advanced-security-organization.png" lightbox="media/enable-github-advanced-security-organization.png" alt-text="Screenshot of org-level enablement for Advanced Security."::: ## Set up secret scanning Secret scanning push protection and repository scanning are automatically enabled when you turn on Advanced Security. You can enable or disable secret push protection from the repository settings page. -![Screenshot of enabling push protection](media/secret-scanning-push-protection.png) - +:::image type="content" source="media/secret-scanning-push-protection.png" lightbox="media/secret-scanning-push-protection.png" alt-text="Screenshot of enabling push protection."::: As mentioned, secret scanning repository scanning is automatically kicked off upon enabling Advanced Security for a selected repository. -## Set up dependency scanning -Dependency scanning is a pipeline-based scanning tool. Results are aggregated per repository. It's recommended that you add the dependency scanning task to all the pipelines you'd like to be scanned. +## Set up dependency scanning +Dependency scanning is a pipeline-based scanning tool. Results are aggregated per repository. We recommend that you add the dependency scanning task to all the pipelines that you want scanned. >[!TIP] -> For the most accurate scanning results, be sure to add the dependency scanning task following the build steps of a pipeline that builds the code you wish to scan. +> For the most accurate scanning results, add the dependency scanning task after the build steps or package restore step in a pipeline that builds the code you wish to scan. #### [YAML](#tab/yaml) -Add the task Advanced Security Dependency Scanning (`AdvancedSecurity-Dependency-Scanning@1`) directly to your YAML pipeline file or select the Advanced Security Dependency Scanning task from the Tasks assistant. - -![Screenshot of dependency scanning pipeline setup for YAML](media/dependency-scanning-config-yaml.png) +Add the task Advanced Security Dependency Scanning task ([AdvancedSecurity-Dependency-Scanning@1](/azure/devops/pipelines/tasks/reference/advanced-security-dependency-scanning-v1)) directly to your YAML pipeline file or select the **Advanced Security Dependency Scanning** task from the [task assistant](../../pipelines/get-started/yaml-pipeline-editor.md#use-task-assistant). +:::image type="content" source="media/dependency-scanning-config-yaml.png" lightbox="media/dependency-scanning-config-yaml.png" alt-text="Screenshot of dependency scanning pipeline setup for YAML."::: #### [Classic](#tab/classic) Add the `Advanced Security Dependency Scanning` task to your pipeline. -![Screenshot of dependency scanning pipeline setup for classic pipelines](media/dependency-scanning-config-classic.png) - +:::image type="content" source="media/dependency-scanning-config-classic.png" lightbox="media/dependency-scanning-config-classic.png" alt-text="Screenshot of dependency scanning pipeline setup for classic pipelines."::: To generate alerts, run your first scan with a pipeline with the dependency scanning task included. @@ -102,59 +114,102 @@ To generate alerts, run your first scan with a pipeline with the dependency scan Code scanning is also a pipeline-based scanning tool where results are aggregated per repository. >[!TIP] -> It's recommended to add the code scanning task to a separate, cloned pipeline of your main production pipeline or create a new pipeline. This is because code scanning can be a more time-intensive build task. +> Code scanning can be a more time-intensive build task, so we recommend that you add the code scanning task to a separate, cloned pipeline of your main production pipeline or create a new pipeline. #### [YAML](#tab/yaml) Add the tasks in the following order: -1. Advanced Security Initialize CodeQL (`AdvancedSecurity-Codeql-Init@1`) -1. Advanced Security AutoBuild (language-dependent) (`AdvancedSecurity-Codeql-Autobuild@1`) -1. Advanced Security Perform CodeQL Analysis (`AdvancedSecurity-Codeql-Analyze@1`) -1. Advanced Security Publish Results (`AdvancedSecurity-Publish@1`) +1. Advanced Security Initialize CodeQL ([AdvancedSecurity-Codeql-Init@1](/azure/devops/pipelines/tasks/reference/advanced-security-codeql-init-v1)) +1. Your custom build steps +1. Advanced Security Perform CodeQL Analysis ([AdvancedSecurity-Codeql-Analyze@1](/azure/devops/pipelines/tasks/reference/advanced-security-codeql-analyze-v1)) + +:::image type="content" source="media/code-scanning-config-yaml-tasks.png" lightbox="media/code-scanning-config-yaml-tasks.png" alt-text="Screenshot of code scanning pipeline setup for YAML."::: -![Screenshot of code scanning variables setup for YAML](media/code-scanning-config-yaml-variable.png) +Also, specify which language you're analyzing in the `Initialize CodeQL` task. You can use a comma separated list to analyze multiple languages at once. The supported languages are `csharp, cpp, go, java, javascript, python, ruby, swift`. If you're utilizing self-hosted agents, you might also add the `enableAutomaticCodeQLInstall: true` variable to automatically install the latest CodeQL bits for your agent. -Additionally, add two build variables: -1. `advancedsecurity.codeql.language` and set it for the languages you wish to analyze. A comma separated list can be used to analyze multiple languages at once. The supported languages are `csharp, cpp, go, java, javascript, python, ruby`. +Here's an example starter pipeline: - > [!TIP] - > CodeQL analysis for Kotlin is currently in beta. During the beta, analysis of Kotlin will be less comprehensive than CodeQL analysis of other languages. - > Use `java` to analyze code written in Java, Kotlin or both. - > Use `javascript` to analyze code written in JavaScript, TypeScript or both. +>[!div class="tabbedCodeSnippets"] +```yaml +trigger: + - main -1. `advancedsecurity.submittoadvancedsecurity: true` to submit the results to Advanced Security +pool: + # Additional hosted image options are available: https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/hosted#software + vmImage: ubuntu-latest -If the language specified is `cpp, java,` or `csharp` either custom or `AutoBuild` build steps are required. For other languages, if AutoBuild is included the step completes successfully without performing any action. +steps: -![Screenshot of code scanning pipeline setup for YAML](media/code-scanning-config-yaml-tasks.png) + - task: AdvancedSecurity-Codeql-Init@1 + inputs: + languages: "java" + # Supported languages: csharp, cpp, go, java, javascript, python, ruby, swift + # You can customize the initialize task: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/advanced-security-codeql-init-v1?view=azure-pipelines + # If you're using a self-hosted agent to run CodeQL, use `enableAutomaticCodeQLInstall` to automatically use the latest CodeQL bits on your agent: + enableAutomaticCodeQLInstall: true + +# Add your custom build steps here +# - Ensure that all code to be scanned is compiled (often using a `clean` command to ensure you're building from a clean state). +# - Disable the use of any build caching mechanisms as this can interfere with CodeQL's ability to capture all the necessary data during the build. +# - Disable the use of any distributed/multithreaded/incremental builds as CodeQL needs to monitor executions of the compiler to construct an accurate representation of the application. +# - For dependency scanning, ensure you have a package restore step for more accurate results. + +# If you had a Maven app: +# - task: Maven@4 +# inputs: +# mavenPomFile: 'pom.xml' +# goals: 'clean package' +# publishJUnitResults: true +# testResultsFiles: '**/TEST-*.xml' +# javaHomeOption: 'JDKVersion' +# jdkVersionOption: '1.17' +# mavenVersionOption: 'Default' + +# Or a general script: +# - script: | +# echo "Run, Build Application using script" +# ./location_of_script_within_repo/buildscript.sh + + - task: AdvancedSecurity-Dependency-Scanning@1 # More details on this task: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/advanced-security-dependency-scanning-v1?view=azure-pipelines + + - task: AdvancedSecurity-Codeql-Analyze@1 # More details on this task: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/advanced-security-codeql-analyze-v1?view=azure-pipelines + +``` + +> [!TIP] +> CodeQL analysis for Kotlin/Swift is currently in beta. During the beta, analysis of these languages is less comprehensive than CodeQL analysis of others. +> - Use `java` to analyze code written in Java, Kotlin or both. +> - Use `javascript` to analyze code written in JavaScript, TypeScript, or both. + +If the language specified is `cpp, java, csharp` or `swift`, custom build steps are required. #### [Classic](#tab/classic) Add the tasks in the following order: 1. `Advanced Security Initialize CodeQL` -1. `Advanced Security AutoBuild` (language-dependent) +1. Add your own custom build steps 1. `Advanced Security Perform CodeQL Analysis` -1. `Advanced Security Publish Results` - -![Screenshot of code scanning variables setup for YAML](media/code-scanning-config-classic-variable.png) - -Additionally, add two build variables: -1. `advancedsecurity.codeql.language` and set it for the languages you wish to analyze. A comma separated list can be used to analyze multiple languages at once. The supported languages are `csharp, cpp, go, java, javascript, python, ruby`. -1. `advancedsecurity.submittoadvancedsecurity: true` to submit the results to Advanced Security -If the language specified is `cpp, java,` or `csharp,` either custom or `AutoBuild` build steps are required. For other languages, if AutoBuild is included the step completes successfully without performing any action. +:::image type="content" source="media/code-scanning-config-classic-tasks.png" alt-text="Screenshot of code scanning pipeline setup for YAML." lightbox="media/code-scanning-config-classic-tasks.png" ::: -![Screenshot of code scanning pipeline setup for YAML](media/code-scanning-config-classic-tasks.png) +Also, specify which language you're analyzing in the `Initialize CodeQL` task. If the language specified is `cpp, java, csharp` or `swift`, custom build steps are required. +If you're running on a self-hosted agent, select the `Enable automatic CodeQL detection and installation` to automatically use the latest CodeQL bits on your agent if you didn't manually install the latest CodeQL bundle to your agent tool cache. To generate alerts, run your first scan with a pipeline with the code scanning tasks included. --- -If, for whatever reason, you need to disable Advanced Security, any alerts and state of alerts will be retained for the next time you re-enable Advanced Security for your repository. +## Set up pull request annotations + +For both dependency scanning and code scanning, annotations automatically configure for pull requests where a build validation policy applies with dependency scanning and/or code scanning tasks included in your pipeline. For more information on configuring build validation policies, see [Build validation](../git/branch-policies.md#build-validation). + +Pull request annotations also require an Advanced Security scan on your default branch and target branch before then scanning your source (pull request) branch. For more information on resolving alerts for pull request branches, see [Managing dependency scanning alerts on pull requests](github-advanced-security-dependency-scanning.md#managing-dependency-scanning-alerts-on-pull-requests) and [Managing code scanning alerts on pull requests](github-advanced-security-code-scanning.md#managing-code-scanning-alerts-on-pull-requests). + +To disable Advanced Security, any alerts and state of alerts get retained in the Advanced Security tab for the next time you re-enable Advanced Security for your repository. -## Next steps +## Related articles * [Code scanning alerts for GitHub Advanced Security for Azure DevOps](github-advanced-security-code-scanning.md) * [Dependency scanning alerts for GitHub Advanced Security for Azure DevOps](github-advanced-security-dependency-scanning.md) diff --git a/docs/repos/security/github-advanced-security-billing.md b/docs/repos/security/github-advanced-security-billing.md index 490b51e209a..9c95a8d3e63 100644 --- a/docs/repos/security/github-advanced-security-billing.md +++ b/docs/repos/security/github-advanced-security-billing.md @@ -4,42 +4,53 @@ titleSuffix: Azure Repos description: Configure billing for GitHub Advanced Security for Azure DevOps ms.service: azure-devops ms.subservice: azure-devops-integration -ms.topic: how-to +ms.topic: conceptual ms.custom: cross-service -ms.author: jukullam -author: juliakm +ms.author: laurajiang +author: laurajjiang monikerRange: 'azure-devops' -ms.date: 05/09/2023 +ms.date: 02/20/2025 --- # Advanced Security billing -To access results and use [GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md) features, you need a license. Each active committer to at least one repository with Advanced Security enabled consumes one license. A committer is considered active if they have committed code to the repository within the last 90 days. +To access results and use [GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md) features, you need a license. Each active committer to at least one repository with Advanced Security enabled consumes one license and [costs $49 per month per active committer](https://azure.microsoft.com/products/devops/github-advanced-security#pricing). A committer is considered active if they're present in a push made within the last 90 days, regardless of when they originally committed. -Advanced Security is billed directly to the Azure subscription associated with your Azure DevOps organization. The bill is metered monthly. Daily charges emit to your Azure subscription based off of the total number of active committers per day across your organizations. +Advanced Security gets billed monthly and directly to the Azure subscription associated with your Azure DevOps organization. Daily charges emit to your Azure subscription based off of the total number of active committers per day across your organizations. -Active committers are deduplicated across an Azure subscription. Users can contribute to multiple repositories or organizations, as long as those organizations are associated with the same Azure subscription. +Active committers are deduplicated across an Azure subscription. Users can contribute to multiple repositories or organizations and only get counted once, as long as those organizations are associated with the same Azure subscription. [!INCLUDE [GitHub Advanced Security for Azure DevOps is different from GitHub Advanced Security.](includes/github-advanced-security.md)] ### Active committer count for Advanced Security -You can find the number of consumed licenses (active committer count in Advanced Security-enabled repositories) for Advanced Security under **Organization Settings > Billing**. This is the number of active committers as measured for the previous day. +Total active committers are the number of committers who contributed to at least one repository with Advanced Security enabled. For each pushed change, any valid identity that contributed to that change is considered an active committer, even if the commit was made before the 90-day span. Regardless of their Azure DevOps access level, they must be a member of your Azure DevOps organization. -![Screenshot of organization billing settings showing active committer count](./media/billing-active-committer-count.png) +Before you enable Advanced Security for your organization, project, or repository, you can see an estimate of the number of active committers you might get charged for. -Total active committers are the number of committers who contributed to at least one repository with Advanced Security enabled. Regardless of their Azure DevOps access level, they must be a member of your Azure DevOps organization. +> [!div class="mx-imgBorder"] +> [![Screenshot of Advanced Security pop up with an estimated committee count.](media/enable-github-advanced-security-project-committers.png)](media/enable-github-advanced-security-project-committers.png#lightbox) + +You can find the exact number of consumed licenses (active committer count in Advanced Security-enabled repositories) for Advanced Security under **Organization settings > Billing**. This number represents active committers as measured for the previous day. + +> [!div class="mx-imgBorder"] +> [![Screenshot of organization billing settings showing active committer count.](./media/billing-active-committer-count.png)](./media/billing-active-committer-count.png#lightbox) If you disable Advanced Security for all repositories in your organization, the active committer estimate disappears but you can watch your billing on your Azure subscription in the Azure portal. ### Understanding active committer count - -Use the following table for an example of how active committers and your potential bill may change over time. +Use the following table for an example of how active committers and your potential bill might change over time. | Date | Events during the month | Total active committers | | ---------- | ----------- | ------ | -| March 1 | A project collection admin enables Advanced Security for the Fabrikam repository. Fabrikam has 30 active committers over the past 90 days. | **30** | -| April 1 | A PCA disables Advanced Security for the Fabrikam repository. Moving forward, the active committers from Fabrikam are no longer charged for. | 30 - 30 = **0** | -| July 15 | A PCA re-enables Advanced Security for Fabrikam. Fabrikam has 20 active committers over the past 90 days now. | **20** | -| August 1 | A PCA enables Advanced Security for a second repository, AdventureWorks. In the last 90 days, 30 developers committed to that repository. Ten of those developers also committed to Fabrikam and don't consume more licenses. | 20 + 20 = **40** | +| March 1 | A project collection administrator (PCA) enables Advanced Security for the Fabrikam repository. Fabrikam has 30 active committers over the past 90 days. | **30** | +| March 19 | A PCA disables Advanced Security for the Fabrikam repository. The active committers from Fabrikam don't get counted.| 30 - 30 = **0** | +| July 15 | A PCA re-enables Advanced Security for Fabrikam. Fabrikam has 20 active committers over the past 90 days. | **20** | +| August 1 | A PCA enables Advanced Security for a second repository, AdventureWorks. In the last 90 days, 30 developers committed to that repository. 10 of those developers also committed to Fabrikam and don't consume more licenses. | 20 + 20 = **40** | + +## Related articles +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Learn about GitHub Advanced Security for Azure DevOps](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-code-scanning-queries.md b/docs/repos/security/github-advanced-security-code-scanning-queries.md new file mode 100644 index 00000000000..be1dc70880a --- /dev/null +++ b/docs/repos/security/github-advanced-security-code-scanning-queries.md @@ -0,0 +1,141 @@ +--- +title: Use custom queries with GitHub Advanced Security for Azure DevOps +titleSuffix: Azure Repos +description: Using custom queries with GitHub Advanced Security for Azure DevOps. +ms.service: azure-devops +ms.subservice: azure-devops-integration +ms.topic: how-to +ms.custom: cross-service +ms.author: laurajiang +author: laurajjiang +monikerRange: 'azure-devops' +ms.date: 02/20/2025 +--- + +# Use custom queries with CodeQL + +By default, if you don't have a custom configuration file specified in your pipeline setup, CodeQL runs the [`security-extended`](https://docs.github.com/en/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites#security-extended-query-suite) query pack to analyze your code. You can utilize custom CodeQL queries to write your own queries to find specific vulnerabilities and errors. You also need to create a custom configuration file to modify CodeQL's default analysis. + +To find existing custom queries or to contribute your own custom query, see [Contributing to CodeQL](https://github.com/github/codeql/blob/main/CONTRIBUTING.md). + +## Prerequisites + +[!INCLUDE [github-advanced-security-prerequisites](includes/github-advanced-security-prerequisites.md)] + +### Analysis with custom queries + +The quickest way to start with a custom query is to write a query and save it in your local Azure DevOps repository. You can customize the details of a custom query according to your need, but it must have at least a rule ID. For more information about how to write your own CodeQL query, see [Writing CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/). You can also bundle multiple queries together into a query suite, or utilize packs published by other people. For more information, see [Publishing and using CodeQL packs](https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs). + +### Use a custom configuration file + +A custom configuration file is a way to manage what queries are run during CodeQL's analysis against your code. You can specify more queries or query packs to be run, and change or disable the default CodeQL queries. + +To include a specific query you want to include, specify the query with a name and path to the location of the query file `.ql` in your repository. + +To include a specific pack you want to include, specify the pack name. You can specify any number of CodeQL query packs to run in your configuration file. + +The next step is to create a `qlpack.yml` file. This file declares the CodeQL pack and information about it. Any `*.ql` files in the same directory, or subdirectory, as a `qlpack.yml` are considered part of the package. + +> [!TIP] +> The `packs` filter from the configuration file supports downloading packs from repositories hosted in GitHub, although the `queries` filter doesn't. +> If the pack is private in GitHub, then you need to provide a GitHub access token via the `AdvancedSecurity-Codeql-Init@1` task as an environment variable and variable name as `GITHUB_TOKEN`, with the scope of the token being `read:packages`. + +The following code shows an example configuration file: + +>[!div class="tabbedCodeSnippets"] +```yaml +name: "Run custom queries" + +# When using a configuration file, if you do not disable default queries, +# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis. +disable-default-queries: true + +# To reference local queries saved to your repository, +# the path must start with `./` followed by the path to the custom query or queries. +# Names for each query referenced is optional. +queries: + - name: Use security-extended query suite + uses: security-extended + - name: Use local custom query (single query) + uses: ./customQueries/javascript/FindTestFunctions.ql + - name: Use local custom query (directory of queries) + uses: ./customQueries/javascript/MemoryLeakQueries + +packs: + - mygithuborg/mypackname + +paths: + - src + +paths-ignore: + - src/node_modules + - '**/*.test.js' + +query-filters: + - include: + kind: problem + - include: + precision: medium + - exclude: + id: + - js/angular/disabling-sce + - js/angular/insecure-url-allowlist + +``` + +> [!TIP] +> Configuration file specifications ignore and take precedence over pipeline-level configurations for the `AdvancedSecurity-Codeql-Init@1` task. +> `includepaths` / `ignorepaths` is ignored or, if `paths`/`paths-ignore` are present, overwritten with values from `paths`/`paths-ignore`. +> `querysuite` is overwritten with values specified in `queries` or `packs` in the configuration file. + +If you're using any custom query, the following code shows an example `qlpack.yml` placed in the directory of your custom queries: + +``` +version: 1.0.1 +dependencies: + codeql/javascript-all: "*" + codeql/javascript-queries: "*" +``` +The `dependencies` variable contains all of the dependencies of this package and their compatible version ranges. Each dependency is referenced as the `scope/name` of a CodeQL library pack. When you define `dependencies`, your `qlpack.yml` depends on exactly one of the core language packs (for example, JavaScript, C#, Ruby, etc.), which determines the language your query can analyze. + +For more specific advice and configuration options with your configuration file, see [Customizing your advanced setup for code scanning](https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#specifying-codeql-query-packs) or for `qlpack.yml` setup, see [CodeQL pack structure](https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#codeql-pack-structure). + + +Once you have your configuration file, you then need to customize your pipeline running CodeQL analysis to utilize your new file. The following code shows an example pipeline pointing to a configuration file: + +>[!div class="tabbedCodeSnippets"] +```yaml +trigger: none + +pool: + vmImage: windows-latest + +# You can either specify your CodeQL variables in a variable block... +variables: +# `configfilepath` must be an absolute file path relative to the repository root + advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' + +# Or you can specify variables as variables for the task. You do not need both definitions. +steps: +- task: AdvancedSecurity-Codeql-Init@1 + displayName: Initialize CodeQL + inputs: + languages: 'javascript' + loglevel: '2' + configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' +# If downloading a pack from GitHub, +# you must include a GitHub access token with the scope of `read:packages`. + env: + GITHUB_TOKEN: $(githubtoken) + +- task: AdvancedSecurity-Codeql-Analyze@1 + displayName: Perform CodeQL Analysis + ``` + +## Related articles + +- [Troubleshoot code scanning](github-advanced-security-code-scanning-troubleshoot.md) +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Learn about GitHub Advanced Security for Azure DevOps](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-code-scanning-third-party.md b/docs/repos/security/github-advanced-security-code-scanning-third-party.md new file mode 100644 index 00000000000..734f9d64815 --- /dev/null +++ b/docs/repos/security/github-advanced-security-code-scanning-third-party.md @@ -0,0 +1,63 @@ +--- +title: Integrate non-Microsoft scanning tools with GitHub Advanced Security for Azure DevOps +titleSuffix: Azure Repos +description: Integrate non-Microsoft scanning tools with GitHub Advanced Security for Azure DevOps. +ms.service: azure-devops +ms.subservice: azure-devops-integration +ms.topic: how-to +ms.custom: cross-service +ms.author: laurajiang +author: laurajjiang +monikerRange: 'azure-devops' +ms.date: 02/20/2025 +--- + +# Integrate non-Microsoft scanning tools + +[GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md) creates code scanning alerts in a repository using information from Static Analysis Results Interchange Format (SARIF) files. The SARIF file properties are used to populate alert information, such as the alert title, location, and description text. + +You can generate SARIF files using many static analysis security testing tools, including CodeQL. The results must use SARIF version 2.1.0. For more information on SARIF, see [SASRIF tutorials](https://github.com/microsoft/sarif-tutorials). + +## Prerequisites + +[!INCLUDE [github-advanced-security-prerequisites](includes/github-advanced-security-prerequisites.md)] + +## Upload a code scanning analysis with Azure Pipelines +To use Azure Pipelines to upload a non-Microsoft SARIF file to a repository, your pipeline needs to use the [`AdvancedSecurity-Publish`](/azure/devops/pipelines/tasks/reference/advanced-security-publish-v1) task, which is part of the tasks bundled with GitHub Advanced Security for Azure DevOps. The main input parameters to use are: +- `SarifsInputDirectory`: Configures the directory of SARIF files to be uploaded. The expected directory path is absolute. +- `Category`: Optionally assigns a category for results in the SARIF file. This parameter enables you to analyze the same commit in multiple ways and review the results using the code scanning views in GitHub. For example, you can analyze using multiple tools, and in mono-repos, you can analyze different slices of the repository based on the subset of changed files. + +The following code shows an example of an integration with the [Microsoft Security DevOps task](/azure/defender-for-cloud/azure-devops-extension) owned by the Microsoft Defender for Cloud team: + +>[!div class="tabbedCodeSnippets"] +```yaml +trigger: +- main + +pool: + vmImage: ubuntu-latest + +steps: +- task: MicrosoftSecurityDevOps@1 + inputs: + command: 'run' + categories: 'IaC' +- task: AdvancedSecurity-Publish@1 + inputs: + SarifsInputDirectory: '$(Build.ArtifactStagingDirectory)/.gdn/' +``` + +## Result fingerprint generation + +If your SARIF file doesn't include `partialFingerprints`, the `AdvancedSecurity-Publish` task calculates the `partialFingerprints` field for you and attempt to prevent duplicate alerts. Advanced Security can only create `partialFingerprints` when the repository contains both the SARIF file and the source code used in the static analysis. For more information about preventing duplicate alerts, see [Providing data to track code scanning alerts across runs](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#providing-data-to-track-code-scanning-alerts-across-runs). + +## Validate tool results + +You can check that the SARIF properties have the supported size for upload and that the file is compatible with code scanning. For more information, see [Validating your SARIF file](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#validating-your-sarif-file). To validate if a SARIF file conforms specifically to Advanced Security's requirements, see [SARIF validator](https://sarifweb.azurewebsites.net/Validation) and select `Azure DevOps ingestion rules`. + +## Related articles + +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Learn about GitHub Advanced Security for Azure DevOps](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-code-scanning-troubleshoot.md b/docs/repos/security/github-advanced-security-code-scanning-troubleshoot.md new file mode 100644 index 00000000000..047cad71107 --- /dev/null +++ b/docs/repos/security/github-advanced-security-code-scanning-troubleshoot.md @@ -0,0 +1,151 @@ +--- +title: Troubleshoot code scanning for GitHub Advanced Security for Azure DevOps +titleSuffix: Azure Repos +description: Troubleshoot code scanning with GitHub Advanced Security for Azure DevOps. +ms.service: azure-devops +ms.subservice: azure-devops-integration +ms.topic: how-to +ms.custom: cross-service +ms.author: laurajiang +author: laurajjiang +monikerRange: 'azure-devops' +ms.date: 02/20/2025 +--- + +# Troubleshoot code scanning + +Generally, if you're encountering errors with CodeQL execution, the CodeQL CLI reports the status of each command it runs as an exit code. The exit code provides information for subsequent commands or for other tools that rely on the CodeQL CLI. For more information on exit code details, see [Exit codes](https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/exit-codes). + +## Prerequisites + +[!INCLUDE [github-advanced-security-prerequisites](includes/github-advanced-security-prerequisites.md)] + +## Error: 'database finalize' CodeQL command (32) +This error indicates a problem with finalizing the CodeQL database creation, potentially due to extraction errors or missing build steps. + +Troubleshooting steps: +1. Verify code exists and is compiled + * For compiled languages, verify that the build process is compiling code and is happening between the `AdvancedSecurity-Codeql-Init` and the `AdvancedSecurity-Codeql-Analyze` tasks. Common build commands and required flags (such as clean no-cache/no-daemon) can be found here at [Specifying build commands](https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis#specifying-build-commands). + * For interpreted languages, confirm that there's some source code for the specified language in the project. +1. Check extraction errors + * Verify if extraction errors affect the CodeQL database's health. + * Review the log file for extraction errors and warnings to assess overall database health. +1. Investigate overwhelming errors + * If most files encounter extractor errors, investigate further to understand the root cause of improper extraction. + +## Error: autobuild script (1) +This error describes an automatic build failure, suggesting an issue with code scanning setup or configuration. + +Troubleshooting steps: +* Configure build steps + * Remove the AutoBuild step and instead configure specific build steps for compiled languages in your pipelines. + * Refer to setup guidelines provided in [Configure GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md#set-up-code-scanning). + +## Error: CodeQL directories not found in agent tool cache +This error indicates an issue with installing CodeQL for self-hosted agents. + +Troubleshooting steps: + +* Refer to setup guidelines or configuration scripts provided in [Configure GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md#extra-prerequisites-for-self-hosted-agents). + +## Error: language pipeline variable not set +This error occurs when attempting to run CodeQL without setting the pipeline variable specifying which languages to scan. + +Troubleshooting steps: + +* Set language pipeline variable + * Ensure the language pipeline variable is correctly configured. Refer to setup guidelines provided in [Configure GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md#set-up-code-scanning). + * Supported languages include `csharp`, `cpp`, `go`, `java`, `javascript`, `python`, `ruby`, and `swift`. + +## CodeQL returning no results +This section provides guidance for situations where CodeQL analysis yields no results. + +Troubleshooting steps: +1. Check for detected vulnerabilities + * Consider the possibility that your code might not have any vulnerabilities. If vulnerabilities are expected but not detected, proceed to verify further. +1. Review query suite configuration + * Confirm the query suite that's being used and consider switching to a more comprehensive suite if necessary. + * Alternatively, [custom query suites](github-advanced-security-code-scanning-queries.md#use-custom-queries-with-codeql) can be created for tailored analysis. +1. Adjust permissions for viewing results + * Ensure proper permissions, at least at the contributor level, are granted to access analysis results. For more information, see [Advanced Security permissions](./github-advanced-security-permissions.md). + +## CodeQL timing out +If the `AdvancedSecurity-Codeql-Analyze@1` task is displaying `This job was abandoned ... we lost contact with the agent` and you're using a hosted Microsoft agent, the task is hitting the built-in six-hour time-out for paid hosted agents. You might attempt to run analysis on a self-hosted agent instead. + +## Code scanning task permissions +The code scanning build task uses the pipeline identity to call the Advanced Security REST APIs. By default, pipelines in the same project have access to upload the SARIF file generated by running CodeQL analysis. If these permissions get removed from the build service account or if you have a custom setup, for example, a pipeline hosted in a different project than the repository, grant these permissions manually. + +Troubleshooting steps: + +* Grant `Advanced Security: View alerts` and `Advanced Security: Manage and dismiss alerts` permission to the build service account used in your pipeline, which for project-scoped pipelines is `[Project Name] Build Service ([Organization Name])`, and for collection-scoped pipelines is `Project Collection Build Service ([Organization Name])`. + +## Code scanning publishing results to the incorrect repository + +If you have a pipeline definition housed in one repository and the source code to be scanned by GitHub Advanced Security was in another, results may be processed and submitted to the incorrect repository, publishing to the repository containing the pipeline definition rather than the source code repository. + +To enable proper result routing, set the pipeline environment variable `advancedsecurity.publish.repository.infer: true` to infer the repository to publish from the repository in the working directory. + +Alternatively, if you don't explicitly check out a repository or use an alias to check out your repository, utilize the variable `advancedsecurity.publish.repository: $[ convertToJson(resources.repositories['YourRepositoryAlias']) ]` instead. + +>[!div class="tabbedCodeSnippets"] +```yaml +trigger: + - main + +resources: + repositories: + - repository: BicepGoat + type: git + name: BicepGoat + ref: refs/heads/main + trigger: + - main + +jobs: + # Explicit - `advancedsecurity.publish.repository` explicitly defines the repository to submit SARIF to. + - job: "AdvancedSecurityCodeScanningExplicit" + displayName: "🛡 Infrastructure-as-Code Scanning (Explicit)" + variables: + advancedsecurity.publish.repository: $[ convertToJson(resources.repositories['BicepGoat']) ] + steps: + - checkout: BicepGoat + - task: TemplateAnalyzerSarif@1 + displayName: Scan with Template Analyzer + - task: AdvancedSecurity-Publish@1 + displayName: Publish to IaC Scanning Results to Advanced Security + + + # Infer - `advancedsecurity.publish.repository.infer` specifies that the `AdvancedSecurity-Publish` must + # infer repository to submit SARIF to from the working directory on the build agent. + - job: "AdvancedSecurityCodeScanningInfer" + displayName: "🛡 Infrastructure-as-Code Scanning (Infer)" + variables: + advancedsecurity.publish.repository.infer: true + steps: + - checkout: BicepGoat + - task: TemplateAnalyzerSarif@1 + displayName: Scan with Template Analyzer + - task: AdvancedSecurity-Publish@1 + displayName: Publish to IaC Scanning Results to Advanced Security +``` + +## Manual installation of CodeQL bundle to self-hosted agent +Install the CodeQL bundle to the agent tool cache by utilizing the setup script for your architecture, available on [GitHub](https://github.com/microsoft/GHAzDO-Resources/tree/main/src/agent-setup). These scripts require the +`$AGENT_TOOLSDIRECTORY` environment variable to be set to the location of the agent tools directory on the agent, for example, `C:/agent/_work/_tool`. Alternatively, you might manually implement the following steps: +1. Pick the latest CodeQL release bundle from [GitHub](https://github.com/github/codeql-action/releases). +1. Download and unzip the bundle to the following directory inside the agent tool directory, typically located under `_work/_tool`: `./CodeQL/0.0.0-[codeql-release-bundle-tag]/x64/`. Using the current release of `v2.16.0`, the folder name would be titled `./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64/`. Learn more about the [agent tool directory](https://github.com/microsoft/azure-pipelines-tool-lib/blob/master/docs/overview.md#tool-cache). +1. Create an empty file titled `x64.complete` within the `./CodeQL/0.0.0-[codeql-release-bundle-tag]` folder. Using the previous example, the end file path to your `x64.complete` file should be `./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64.complete`. + +## How can I explicitly define the repository to publish code scanning alerts to? +- Use the pipeline environment variable `advancedsecurity.publish.repository.infer: true` to infer the repository to publish from the repository in the working directory. +- As another option, if you don't explicitly check out a repository or use an alias to check out your repository, utilize the variable `advancedsecurity.publish.repository: $[ convertToJson(resources.repositories['YourRepositoryAlias']) ]` + +For more information, check the [release notes](https://learn.microsoft.com/azure/devops/release-notes/2025/ghazdo/sprint-253-update#multi-repository-publishing-scenarios-supported-for-github-advanced-security-for-azure-devops). + + +## Related articles + +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Manage GitHub Advanced Security for Azure DevOps](github-advanced-security-permissions.md) diff --git a/docs/repos/security/github-advanced-security-code-scanning.md b/docs/repos/security/github-advanced-security-code-scanning.md index 2eeaad167fe..c6f55eeec5b 100644 --- a/docs/repos/security/github-advanced-security-code-scanning.md +++ b/docs/repos/security/github-advanced-security-code-scanning.md @@ -1,50 +1,113 @@ --- -title: Code scanning alerts for GitHub Advanced Security for Azure DevOps +title: Set up code scanning for GitHub Advanced Security for Azure DevOps titleSuffix: Azure Repos description: Set up code scanning with GitHub Advanced Security for Azure DevOps ms.service: azure-devops ms.subservice: azure-devops-integration ms.topic: how-to ms.custom: cross-service -ms.author: jukullam -author: juliakm +ms.author: laurajiang +author: laurajjiang monikerRange: 'azure-devops' -ms.date: 05/09/2023 +ms.date: 02/20/2025 --- +# Set up code scanning -# Code scanning +Code scanning in GitHub Advanced Security for Azure DevOps lets you analyze the code in an Azure DevOps repository to find security vulnerabilities and coding errors. Any problems identified by the analysis are raised as an alert. Code scanning uses CodeQL to identify vulnerabilities. -Code scanning in [GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md) let's you analyze the code in an Azure DevOps repository to find security vulnerabilities and coding errors. Any problems identified by the analysis are raised as an alert. Code scanning uses CodeQL to identify vulnerabilities. - -CodeQL is the code analysis engine developed by GitHub to automate security checks. You can analyze your code using CodeQL and display the results as code scanning alerts. +CodeQL is the code analysis engine developed by GitHub to automate security checks. You can analyze your code using CodeQL and display the results as code scanning alerts. For more specific documentation about CodeQL, see [CodeQL documentation](https://codeql.github.com/docs/). [!INCLUDE [GitHub Advanced Security for Azure DevOps is different from GitHub Advanced Security.](includes/github-advanced-security.md)] +## Prerequisites -## CodeQL alerts - -GitHub experts, security researchers, and community contributors write and maintain the default CodeQL queries used for code scanning. The queries are regularly updated to improve analysis and reduce any false positive results. The queries are open source, so you can view and contribute to the queries in the [github/codeql](https://github.com/github/codeql) repository. - -For more specific documentation about CodeQL, visit the [CodeQL documentation on GitHub](https://codeql.github.com/docs/). - -CodeQL supports both compiled and interpreted languages and can find vulnerabilities and errors in code that's written in the supported languages. +[!INCLUDE [github-advanced-security-prerequisites](includes/github-advanced-security-prerequisites.md)] -* C/C++ -* C# -* Go -* Java -* JavaScript/TypeScript -* Kotlin (beta) -* Python -* Ruby +## More configurations for code scanning -For more information, see the documentation on the CodeQL website on [Supported languages and frameworks](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/). +### Language and query support -You can view the specific queries and task details used by CodeQL by looking through the build log, similar to dependency scanning. - -![Screenshot of code scanning publish results task](./media/code-scanning-build-log.png) +GitHub experts, security researchers, and community contributors write and maintain the default CodeQL queries used for code scanning. The queries are regularly updated to improve analysis and reduce any false positive results. The queries are open source, so you can view and contribute to the queries in the [github/codeql](https://github.com/github/codeql) repository. +CodeQL supports and uses the following language identifiers: + +| Language | Identifier | Optional alternative identifiers (if any) | +|------------------------|-----------------------|-------------------------------------------| +| C/C++ | `c-cpp` | `c` or `cpp` | +| C# | `csharp` | | +| Go | `go` | | +| Java/Kotlin | `java-kotlin` | | +| JavaScript/TypeScript | `javascript` | | +| Python | `python` | | +| Ruby | `ruby` | | +| Swift | `swift` | | + +> [!TIP] +> * Use `c-cpp` to analyze code written in C, C++ or both. +> * Use `java-kotlin` to analyze code written in Java, Kotlin or both. +> * Use `javascript` to analyze code written in JavaScript, TypeScript or both. + +For more information, see [Supported languages and frameworks](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/). + +You can view the specific queries and task details executed by CodeQL in the build log. + +[![Screenshot of code scanning publish results task.](./media/code-scanning-build-log.png)](./media/code-scanning-build-log.png#lightbox) + +### Code scanning build mode customization +Code scanning supports two build modes when setting up a pipeline for scanning: +* `none` - the CodeQL database is created directly from the codebase without building the codebase (supported for all interpreted languages, and additionally supported for C# and Java). +* `manual` - you define the build steps to use for the codebase in the workflow (supported for all compiled languages). + +For more information on the different build modes including a comparison on the benefits of each build mode, see [CodeQL code scanning for compiled languages](https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#about-the-codeql-analysis-workflow-and-compiled-languages). + +> [!TIP] +> Build mode `none` is useable with other interpreted languages, for example, JavaScript, Python, Ruby. +> If build mode `none` is specified for C# or Java with other compiled languages that don't support build mode `none`, the pipeline task fails. + +The following code shows an example of a valid configuration with multiple languages and `none` build mode: + +>[!div class="tabbedCodeSnippets"] +```yaml +trigger: none + +pool: + vmImage: windows-latest + +steps: +- task: AdvancedSecurity-Codeql-Init@1 + displayName: Initialize CodeQL + inputs: +# build mode `none` is supported for C# and Java, and JavaScript is an interpreted language +# and build mode `none` has no impact on JavaScript analysis + languages: 'csharp, java, javascript' + buildtype: 'none' + +- task: AdvancedSecurity-Codeql-Analyze@1 + displayName: Perform CodeQL Analysis + ``` + +The following code shows an example of an invalid configuration with multiple languages and `none` build mode: + +>[!div class="tabbedCodeSnippets"] +```yaml +trigger: none + +pool: + vmImage: windows-latest + +steps: +- task: AdvancedSecurity-Codeql-Init@1 + displayName: Initialize CodeQL + inputs: +# build mode `none` is supported for C# but build mode `none` is NOT supported for Swift +# so this pipeline definition will result in a failed run + languages: 'csharp, swift' + buildtype: 'none' + +- task: AdvancedSecurity-Codeql-Analyze@1 + displayName: Perform CodeQL Analysis + ``` ## Code scanning alerts @@ -52,33 +115,31 @@ You can view the specific queries and task details used by CodeQL by looking thr To use code scanning, you need to first configure [GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md). -The Advanced Security tab under Repos in Azure DevOps is the hub to view your code scanning alerts. -Select the **Code scanning** tab to view scanning alerts. You can filter by branch, state, pipeline, rule type, and severity. +The Advanced Security tab under Repos in Azure DevOps is the hub to view your code scanning alerts. Select the **Code scanning** tab to view scanning alerts. You can filter by branch, state, pipeline, rule type, and severity. At this time, the alerts hub doesn't display alerts for scanning completed on PR branches. -There's no effect to results if pipelines or branches are renamed - it may take up to 24 hours before the new name is displayed. +There's no effect to results if pipelines or branches are renamed - it may take up to 24 hours before the new name is displayed. -![Screenshot of code scanning alerts for a repository](./media/code-scanning-alerts.png) +If you choose to run custom CodeQL queries, there isn't by default a separate filter for alerts generated from different query packs. You can filter by rule, which is distinct for each query. -If for whatever reason, you turn off Advanced Security for your repository, you'll lose access to the results in the Advanced Security tab and build task. The build task won't fail, but any results from builds run with the task while Advanced Security is disabled are hidden and unretained. +[![Screenshot of code scanning alerts for a repository.](./media/code-scanning-alerts.png)](./media/code-scanning-alerts.png#lightbox) + +If you turn off Advanced Security for your repository, you lose access to the results in the Advanced Security tab and build task. The build task doesn't fail, but any results from builds run with the task while Advanced Security is disabled are hidden and not retained. ### Alert details Select an alert for more details, including remediation guidance. Each alert includes a location, description, example, and severity. -![Screenshot of code scanning alert detail](./media/code-scanning-detail.png) +[![Screenshot of code scanning alert detail.](./media/code-scanning-detail.png)](./media/code-scanning-detail.png#lightbox) | Section | Explanation | |---|---| -| Location | The **Locations** section details a specific instance where CodeQL has detected a vulnerability. If there are multiple instances of your code violating the same rule, a new alert is generated for each distinct location. The Locations card contains a direct link to the affected code snippet so you can select the snippet to be directed to the Azure DevOps web UI for editing. | +| Location | The **Locations** section details a specific instance where CodeQL detected a vulnerability. If there are multiple instances of your code violating the same rule, a new alert is generated for each distinct location. The Locations card contains a direct link to the affected code snippet so you can select the snippet to be directed to the Azure DevOps web UI for editing. | | Description | The description is provided by the CodeQL tool based off of the problem. | | Recommendation | The recommendation is the suggested fix for a given code scanning alert. | | Example | The example section shows a simplified example of the identified weakness in your code. | | Severity | Severity levels can be low, medium, high, or critical. The severity score is based off of the given Common Vulnerability Scoring System (CVSS) score for the identified Common Weakness Enumeration (CWE). Learn more about how severity is scored at this [GitHub blog post](https://github.blog/changelog/2021-07-19-codeql-code-scanning-new-severity-levels-for-security-alerts/). | - -## Manage code scanning alerts - ### Viewing alerts for a repository Anyone with contributor permissions for a repository can view a summary of all alerts for a repository in the Advanced Security tab under Repos. Select the **Code scanning** tab to view all secret scanning alerts. @@ -102,8 +163,30 @@ To dismiss an alert: 1. Select **Close** to submit and close the alert. 1. The alert state changes from **Open** to **Closed** and your dismissal reason displays. +[![Screenshot of how to dismiss a code scanning alert.](./media/code-scanning-dismiss-alert.png)](./media/code-scanning-dismiss-alert.png#lightbox) + +This action dismisses the alert across all branches. Other branches that contain the same vulnerability will also be dismissed. Any alert previously dismissed can be manually reopened. + +### Managing code scanning alerts on pull requests + +If alerts are created for new code changes in a pull request, the alert is reported as an annotation in the Overview tab's comment section of the pull request and as an alert in the Advanced Security repository tab. There is a new branch picker entry for the pull request branch. + +You can review the affected lines of code, see a summary of the finding, and resolve the annotation in the Overview section. + +[![Screenshot of active code pull request annotation.](./media/pull-request-annotation-code-scanning.png)](./media/pull-request-annotation-code-scanning.png#lightbox) + +To dismiss pull request alerts, you must navigate to the alert detail view to close both the alert and resolve the annotation. Otherwise, simply changing the comment status (1) resolves the annotation but doesn't close or fix the underlying alert. + +[![Screenshot of closed code pull request annotation.](./media/pull-request-annotation-code-scanning-closed.png)](./media/pull-request-annotation-code-scanning-closed.png#lightbox) + +To see the entire set of results for your pull request branch, navigate to **Repos** > **Advanced Security** and select your pull request branch. Selecting **Show more details** (2) on the annotation directs you to the alert detail view in the Advanced Security tab. -![Screenshot of how to dismiss a code scanning alert](./media/code-scanning-dismiss-alert.png) +> [!TIP] +> Annotations only get created when the affected lines of code are entirely unique to the pull request difference compared to the target branch of the pull request. -This only dismisses the alert for your selected branch. Other branches that contain the same vulnerability stay active until dismissed. Any alert that has been previously dismissed can be manually reopened. +## Related articles +- [Troubleshoot code scanning](github-advanced-security-code-scanning-troubleshoot.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Learn about GitHub Advanced Security for Azure DevOps](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-dependency-scanning-ecosystems.md b/docs/repos/security/github-advanced-security-dependency-scanning-ecosystems.md new file mode 100644 index 00000000000..3902b994556 --- /dev/null +++ b/docs/repos/security/github-advanced-security-dependency-scanning-ecosystems.md @@ -0,0 +1,68 @@ +--- +title: Supported package ecosystems for dependency scanning for GitHub Advanced Security for Azure DevOps +titleSuffix: Azure Repos +description: Supported package ecosystems for dependency scanning for GitHub Advanced Security for Azure DevOps. +ms.service: azure-devops +ms.subservice: azure-devops-integration +ms.topic: reference +ms.custom: cross-service +ms.author: laurajiang +author: laurajjiang +monikerRange: 'azure-devops' +ms.date: 10/24/2024 +--- + +# Supported package ecosystems + +Dependency scanning supports both direct and transitive dependencies for all supported package ecosystems. Dependency scanning is unable to detect vendored dependencies in your repository. + +Due to how detection is run for dependency scanning, ensure you have a package restore step in your build pipeline so that the correct package version is determined, otherwise results may be missing or incomplete. + +## Ecosystems and versions + +| Package manager | Languages | Supported formats | Supported versions | +|---|---|---|---| +| [Cargo](#cargo) | Rust | `Cargo.toml`, `Cargo.lock` | v1 | +| CocoaPods | Swift | `Podfile.lock` | n/a | +| [Go modules](#go-modules) | Go | `go.mod`, `go.sum` | n/a | +| Gradle | Java | `*.lockfile` | n/a | +| Maven | Java | `pom.xml` | n/a | +| [npm](#npm) | JavaScript | `package-lock.json`, `package.json`, `npm-shrinkwrap.json`, `lerna.json` | v6, v7 & lockfile <= v3 | +| [NuGet](#nuget) | C# | `*.packages.config`, `*.project.assets`, `*.csproj` | n/a | +| [pip](#pip) | Python | `setup.py`, `requirements.txt` | n/a | +| pnpm | JavaScript | `package.json` | v7, v8 | +| RubyGems | Ruby | `Gemfile.lock` | n/a | +| Yarn | JavaScript | `package.json` | v1, v2 | + +## Cargo + +If `Cargo` cli installed with v1.77 or higher, `cargo metadata` is used, which is more accurate. + +## Go modules + +If using Go v1.17 or higher, `go.mod` is used directly, along with the `go cli` if it's present on the agent. Otherwise the `go.sum` file is scanned. + +## Maven + +Detection requires the `maven` CLI to be installed on the agent. + +## npm + +Dependency scanning detects any root `package.json` files but doesn't resolve specific package versions without a package restore at build time even if dependencies in the `package.json` aren't semantically versioned. + +## NuGet + +Without a package restore, dependency scanning doesn't resolve any specific package versions even if dependencies in the `*.csproj` aren't semantically versioned. + +## pip + +Use `pip v22.2.0` or higher to enable use of `pip report` scanning, which provides more accurate detection. + +The environment variable `PIP_INDEX_URL` is used to determine what package feed should be used for `pip install --report detection`. The default value uses the PyPi index unless pip defaults are configured globally. + +## Related articles + +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Learn about GitHub Advanced Security for Azure DevOps](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-dependency-scanning-troubleshoot.md b/docs/repos/security/github-advanced-security-dependency-scanning-troubleshoot.md new file mode 100644 index 00000000000..8bc80474a0e --- /dev/null +++ b/docs/repos/security/github-advanced-security-dependency-scanning-troubleshoot.md @@ -0,0 +1,151 @@ +--- +title: Troubleshooting dependency scanning for GitHub Advanced Security for Azure DevOps +titleSuffix: Azure Repos +description: Troubleshooting dependency scanning for GitHub Advanced Security for Azure DevOps +ms.service: azure-devops +ms.subservice: azure-devops-integration +ms.topic: how-to +ms.custom: cross-service +ms.author: laurajiang +author: laurajjiang +monikerRange: 'azure-devops' +ms.date: 04/16/2025 +--- + +# Troubleshoot dependency scanning + +Learn how to troubleshoot dependency scanning issues in GitHub Advanced Security for Azure DevOps. + +## Prerequisites + +[!INCLUDE [github-advanced-security-prerequisites](includes/github-advanced-security-prerequisites.md)] + +## Dependency scanning not identifying any components +If the dependency scanning task is completing without flagging any components and failing to generate alerts for components with known vulnerabilities, ensure that you at have a package restore step before the `AdvancedSecurity-Dependency-Scanning@1` task. + +For example, for a C# (.NET Core) project, here's a sample YAML snippet: + +>[!div class="tabbedCodeSnippets"] +```yaml +- task: DotNetCoreCLI@2 + displayName: 'Restore NuGet packages' + inputs: + command: 'restore' + projects: '**/*.csproj' + + # If you are using a private package feed such as Azure Artifacts, you will need additional variables. + # For more information, see https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2?view=azure-pipelines + feedsToUse: 'select' + ... + +- task: AdvancedSecurity-Dependency-Scanning@1 +``` + +For a JavaScript project, here's a sample YAML snippet: +>[!div class="tabbedCodeSnippets"] +```yaml +- task: Npm@1 + displayName: 'npm install' + inputs: + command: 'install' + workingDir: '$(System.DefaultWorkingDirectory)' + +- task: AdvancedSecurity-Dependency-Scanning@1 +``` + +## Dependency scanning task time-out + +The default time that the dependency scanning task runs before timing out is 300 seconds, or 5 minutes. If the task is timing out before completion, you can set a pipeline variable `DependencyScanning.Timeout`, which expects an integer representing seconds, such as `DependencyScanning.Timeout: 600`. Anything under the default time-out of 300 seconds has no effect. + +To use this variable, add `DependencyScanning.Timeout` as a pipeline variable: + +>[!div class="tabbedCodeSnippets"] +```yaml +- task: AdvancedSecurity-Dependency-Scanning@1 + env: + DependencyScanning.Timeout: 600 +``` + +## Adjusting your scanning directory + +By default, the dependency scanning task will process the `Agent.BuildDirectory` directory. If you want to scope your scan to a specific folder, you can set a pipeline variable `DependencyScanning.SourcePath` to any directory file path in the build agent that you want to analyze. Multiple dependency scanning task executions in the same pipeline job are not supported. If the scan path is scoped to subdirectory, you cannot re-add the task to scan a different directory. + + >[!div class="tabbedCodeSnippets"] +```yaml +- task: AdvancedSecurity-Dependency-Scanning@1 + env: + DependencyScanning.SourcePath: scan/code/path +``` + +## Dependency scanning publishing results to the incorrect repository + +If you have a pipeline definition housed in one repository and the source code to be scanned by GitHub Advanced Security was in another, results may be processed and submitted to the incorrect repository, publishing to the repository containing the pipeline definition rather than the source code repository. + +To enable proper result routing, set the pipeline environment variable `advancedsecurity.publish.repository.infer: true` to infer the repository to publish from the repository in the working directory. + +Alternatively, if you don't explicitly check out a repository or use an alias to check out your repository, utilize the variable `advancedsecurity.publish.repository: $[ convertToJson(resources.repositories['YourRepositoryAlias']) ]` instead. + +>[!div class="tabbedCodeSnippets"] +```yaml +trigger: + - main + +resources: + repositories: + - repository: BicepGoat + type: git + name: BicepGoat + ref: refs/heads/main + trigger: + - main + +jobs: + # Explicit - `advancedsecurity.publish.repository` explicitly defines the repository to submit SARIF to. + - job: "AdvancedSecurityDependencyScanningExplicit" + displayName: "🛡 Dependency scanning (Explicit)" + variables: + advancedsecurity.publish.repository: $[ convertToJson(resources.repositories['BicepGoat']) ] + steps: + - checkout: BicepGoat + - task: AdvancedSecurity-Dependency-Scanning@1 + displayName: Dependency Scanning + + # Infer - `advancedsecurity.publish.repository.infer` specifies that the `AdvancedSecurity-Publish` must + # infer repository to submit SARIF to from the working directory on the build agent. + - job: "AdvancedSecurityDependencyScanningInfer" + displayName: "🛡 Dependency scanning (Infer)" + variables: + advancedsecurity.publish.repository.infer: true + steps: + - checkout: BicepGoat + - task: AdvancedSecurity-Dependency-Scanning@1 + displayName: Dependency Scanning +``` + +## Missing dependency scanning pull request annotations when adjusting where results are published + +If you are using either the `advancedsecurity.publish.repository.infer` or defining an alternative `advancedsecurity.publish.repository`, you may need to set `DependencyScanning.SourcePath: $(System.DefaultWorkingDirectory)` so that file paths are determined accurately for the pull request annotation to appear as expected. + + >[!div class="tabbedCodeSnippets"] +```yaml +- task: AdvancedSecurity-Dependency-Scanning@1 + env: + DependencyScanning.SourcePath: $(System.DefaultWorkingDirectory) +``` + +## Break-glass scenario for build task + +If the dependency scanning build task is blocking a successful execution of your pipeline and you need to urgently skip the build task, you can set a pipeline variable `DependencyScanning.Skip: true`. + +## Dependency scanning task permissions + +The dependency scanning build task uses the pipeline identity to call the Advanced Security REST APIs. By default, pipelines in the same project have access to fetch alerts. If you remove those permissions from the build service account or if you have a custom setup, for example, a pipeline hosted in a different project than the repository, grant these permissions manually. + +Grant `Advanced Security: View Alerts` permission to the build service account used in your pipeline, which for project-scoped pipelines is `[Project Name] Build Service ([Organization Name])`, and for collection-scoped pipelines is `Project Collection Build Service ([Organization Name])`. + +## Related articles + +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Learn about GitHub Advanced Security for Azure DevOps](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-dependency-scanning.md b/docs/repos/security/github-advanced-security-dependency-scanning.md index f44a0dfd964..284dec48c67 100644 --- a/docs/repos/security/github-advanced-security-dependency-scanning.md +++ b/docs/repos/security/github-advanced-security-dependency-scanning.md @@ -1,44 +1,50 @@ --- -title: Dependency Scanning for GitHub Advanced Security for Azure DevOps +title: Set up dependency scanning for GitHub Advanced Security titleSuffix: Azure Repos description: Set up dependency scanning for GitHub Advanced Security for Azure DevOps ms.service: azure-devops ms.subservice: azure-devops-integration ms.topic: how-to ms.custom: cross-service -ms.author: jukullam -author: juliakm +ms.author: laurajiang +author: laurajjiang monikerRange: 'azure-devops' -ms.date: 04/21/2023 +ms.date: 02/20/2025 --- -# Dependency scanning +# Set up dependency scanning Dependency scanning in [GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md) detects the open source components used in your source code and detects if there are any associated vulnerabilities. Any found vulnerabilities from open source components get flagged as an alert. [!INCLUDE [GitHub Advanced Security for Azure DevOps is different from GitHub Advanced Security.](includes/github-advanced-security.md)] +## Prerequisites + +[!INCLUDE [github-advanced-security-prerequisites](includes/github-advanced-security-prerequisites.md)] + ## About dependency scanning Dependency scanning generates an alert for any open-source component, direct or transitive, found to be vulnerable that your code depends upon. Direct vulnerabilities are the libraries your code directly uses. Transitive dependencies are the libraries or other software that direct dependencies use. -### About dependency scanning detection +### Learn about dependency scanning detection -A new snapshot of your components is stored whenever the dependency graph for a repository changes and after, a pipeline that contains the dependency scanning task building new code is executed. Dependency scanning generates security alerts for Go, Maven, npm (including Yarn and pnpm), NuGet, Pip, Ruby, and Rust. +A new snapshot of your components is stored whenever the dependency graph for a repository changes, and after a pipeline that contains the dependency scanning task is executed. For every vulnerable component detected in use, the component and vulnerability are listed in the build log and displayed as an alert in the Advanced Security tab. Only advisories that reviewed by GitHub and added to the [GitHub Advisory Database](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/browsing-security-advisories-in-the-github-advisory-database) create a dependency scanning alert. The build log includes a link to the individual alert for further investigation. For more information on the alert detail, view Fixing dependency scanning alerts. The build log also contains basic information about each detected vulnerability. These details include the severity, the affected component, the title of the vulnerability, and the associated CVE. -![Screenshot of a dependency scanning build output](./media/dependency-scanning-build-log.png) +![Screenshot of a dependency scanning build output](./media/dependency-scanning-build-log.png) -### About dependency scanning alerts +For a list of supported component ecosystems and versions, see [Supported package ecosystems](./github-advanced-security-dependency-scanning-ecosystems.md). -The Advanced Security tab in Repos in Azure DevOps is the hub to view your security alerts, which by default shows dependency scanning alerts. You can filter by branch, pipeline, package, and severity. You can select into an alert for more details, including remediation guidance. +### Learn about dependency scanning alerts + +The Advanced Security tab in Repos in Azure DevOps is the hub to view your security alerts, which by default shows dependency scanning alerts. You can filter by branch, pipeline, package, and severity. You can select into an alert for more details, including remediation guidance. At this time, the alerts hub doesn't display alerts for scanning completed on PR branches. When a vulnerable package is detected in your repository, fixing dependency scanning alerts typically involves upgrading to a higher package version or removing an offending package. This advice holds true for both direct and transitive (or indirect) dependencies. The default view in your Advanced Security tab is active alerts for the default branch for your repository. -There's no effect to results if pipelines or branches are renamed - it may take up to 24 hours before the new name is displayed. +There's no effect to results if pipelines or branches are renamed - it might take up to 24 hours before the new name is displayed. ![Screenshot of dependency scanning alert view for a repository](./media/dependency-scanning-alerts.png) @@ -47,7 +53,7 @@ An alert’s state is automatically updated to `Closed` when the vulnerable comp ![Screenshot of viewing closed dependency scanning alerts](./media/dependency-scanning-alerts-closed.png) -If for whatever reason, you turn off Advanced Security for your repository, you'll lose access to the results in the Advanced Security tab and build task. The build task won't fail, but any results from builds run with the task while Advanced Security is disabled are hidden and unretained. +If you turn off Advanced Security for your repository, you lose access to the results in the Advanced Security tab and build task. The build task doesn't fail, but any results from builds run with the task while Advanced Security is disabled are hidden and not retained. ### Alert details @@ -58,23 +64,20 @@ You can also drill into details about an alert by clicking into a specific alert | Section | Explanation | |---|---| | Recommendation | The recommendation text comes directly from our vulnerability data provider, the GitHub Advisory Database. Typically, the guidance suggests upgrading the identified component to a nonvulnerable version. | -| Location | The **Locations** section details the path(s) where the dependency scanning task has discovered the vulnerable component in use. If the file can be resolved from the underlying build scan to a committed file in source, the Locations card appears as a clickable link. If a file was produced as part of a build (for example, a build artifact), the link isn't clickable. Review the build logs to better understand how the component was brought into the build. | +| Location | The **Locations** section details the paths where the dependency scanning task discovers the vulnerable component in use. If the file can be resolved from the underlying build scan to a committed file in source, the Locations card appears as a clickable link. If a file was produced as part of a build (for example, a build artifact), the link isn't clickable. Review the build logs to better understand how the component was brought into the build. | | Description | The description is provided by the GitHub Advisory description. | #### Detections -The pipelines listed under the **Detections** tab are the pipelines where the vulnerable component was found. Each row details the latest build of the affected pipeline and the date when the package was first introduced. If the vulnerable package has been fixed in some pipelines but not all, you see partially fixed rows. +The pipelines listed under the **Detections** tab are the pipelines where the vulnerable component was found. Each row details the latest build of the affected pipeline and the date when the package was first introduced. If the vulnerable package is fixed in some pipelines but not all, you see partially fixed rows. ![Screenshot of dependency scanning detections view for an alert without a fix](./media/dependency-scanning-detections-no-fix.png) -Once an alert has been resolved, the alert automatically moves to the `Closed` state and the latest run pipeline under the Detections tab displays a green checkmark, meaning that code containing the updated component was run in that pipeline: +Once an alert gets resolved, the alert automatically moves to the `Closed` state and the latest run pipeline under the Detections tab displays a green checkmark, meaning that code containing the updated component was run in that pipeline: ![Screenshot of dependency scanning detections view for an alert](./media/dependency-scanning-detections.png) - - - #### Severity The GitHub Advisory Database provides a CVSS score, which is then translated into a low, medium, high, or critical severity for an alert through the following guidelines: @@ -91,31 +94,25 @@ The GitHub Advisory Database provides a CVSS score, which is then translated int Two sections are commonly found under **Finding details**: vulnerable package and root dependency. The vulnerable package is the potentially vulnerable component. The root dependency section contains top level components that are responsible for the dependency chain that lead to a vulnerability. -If the vulnerable package is only referenced as a direct dependency, you only see the ”vulnerable package” section. +If the vulnerable package is only referenced as a direct dependency, you only see the "vulnerable package" section. -If the vulnerable package is referenced both as a direct and transitive dependency, the package is shown in both the “vulnerable package” and “root dependency” section. +If the vulnerable package is referenced both as a direct and transitive dependency, the package is shown in both the "vulnerable package" and "root dependency" section. -If the vulnerable package is only referenced as a transitive dependency, the package is shown in the “vulnerable package” section, and the root dependencies referencing the vulnerable package are shown in the “root dependency” section. +If the vulnerable package is only referenced as a transitive dependency, the package is shown in the "vulnerable package" section, and the root dependencies referencing the vulnerable package are shown in the "root dependency" section. ## Manage dependency scanning alerts ### Viewing alerts for a repository -Anyone with contributor permissions for a repository can view a summary of all alerts for a repository in **Repos** > **Advanced Security**. - By default, the alerts page shows dependency scanning results for the default branch of the repository. The status of an alert reflects the state for the default branch and latest run pipeline, even if the alert exists on other branches and pipelines. ### Fixing dependency scanning alerts -A direct dependency is a component that you have explicitly included in your repository. A transitive or indirect dependency is a component that utilized by a direct dependency. Regardless of whether the vulnerability is found in a direct or transitive dependency, your project is still vulnerable. - A direct dependency is a component that you have in your repository. A transitive or indirect dependency is a component that gets used by a direct dependency. Your project is still vulnerable regardless of whether the vulnerability is found in a direct or transitive dependency. -Fixing a vulnerable transitive dependency usually takes the form of explicitly overriding the version of the vulnerable component used for each identified direct dependency. Once the root dependencies have upgraded their use of the vulnerable component to a safe version, you can upgrade each root dependency rather than multiple individual overrides. - -To fix a vulnerable transitive dependency, override the version of the vulnerable component used for each identified direct dependency. Once the root dependencies upgrade their use of the vulnerable component to a safe version, you can upgrade each root dependency rather than have multiple individual overrides. +Fixing a vulnerable transitive dependency usually takes the form of explicitly overriding the version of the vulnerable component used for each identified direct dependency. Once the root dependencies upgrade their use of the vulnerable component to a safe version, you can upgrade each root dependency rather than multiple individual overrides. #### Updating dependencies for Yarn/Npm @@ -147,7 +144,7 @@ The current version of `axios` has a [denial of service (DoS) vulnerability](htt } ``` -Now, the version of `eslint` in the `package.json` shown depends on a version of `acorn` that is a regular expression denial of service (ReDoS) vulnerability with a recommendation to update to version `5.7.4, 6.4.1, 7.1.1` or higher. If you get an alert from the dependency scanning tool, it should tell you the root dependency that requires the vulnerable dependency. +Now, the version of `eslint` in the `package.json` shown depends on a version of `acorn` that is a regular expression denial of service, "Re-DoS," vulnerability with a recommendation to update to version `5.7.4, 6.4.1, 7.1.1` or higher. If you get an alert from the dependency scanning tool, it should tell you the root dependency that requires the vulnerable dependency. #### Yarn @@ -197,7 +194,7 @@ Use the resolutions field in `package.json` to define a version override. Three } ``` -Using the`**/acorn` pattern overrides all usages of the acorn package across all dependencies. It's dangerous, and break at runtime. As a result, it has been removed in Yarn v2. +Using the`**/acorn` pattern overrides all usages of the acorn package across all dependencies. It's dangerous, and breaks at runtime, so we removed it in Yarn v2. Using the `eslint/**/acorn` pattern overrides all usages of the acorn package under the eslint package, and in any packages it depends on. It's safer than overriding the package for all dependencies, but it still has some risks if the dependency graph for a package is large. This pattern is recommended when there are many subpackages that use a vulnerable package and defining overrides for individual subpackages would be impractical. @@ -207,7 +204,7 @@ Using the pattern `eslint/espree/acorn` overrides only the usage of `acorn` in t If you’re using npm 8.3 or higher, you can use the [**overrides**](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides) field in your package.json -Add an override if you need to make specific changes to transitive dependencies. For example, you may need to add an override to replace the version of a dependency with a known security issue, replace an existing dependency with a fork, or make sure that the same version of a package is used everywhere. +Add an override if you need to make specific changes to transitive dependencies. For example, you might need to override the version of a dependency with a known security issue, replace an existing dependency with a fork, or ensure that the same version of a package gets used everywhere. >[!div class="tabbedCodeSnippets"] ```javascript @@ -233,7 +230,7 @@ The override example shown demonstrates npm's way of saying “override only the After setting your overrides, you must delete your `package-lock.json` and `node_modules` and run `npm install` again. -You may not set an override for a package that you directly depend on unless both the dependency and the override itself share the exact same spec. For example, let’s say `axios: "0.18.0"` is vulnerable and we're looking to upgrade to `axios: "0.19.2"`. Directly change the dependency version instead of using override. +You might not set an override for a package that you directly depend on unless both the dependency and the override itself share the exact same spec. For example, let’s say `axios: "0.18.0"` is vulnerable and we're looking to upgrade to `axios: "0.19.2"`. Directly change the dependency version instead of using override. >[!div class="tabbedCodeSnippets"] ```javascript @@ -267,7 +264,7 @@ Update the dependency's version without setting an override: #### Updating dependencies for Maven -The dependency resolution mechanism isn't as sophisticated as the one used in Yarn. As a result, you can only have a single version of a dependency in a project. In order to resolve this issue, Maven uses a “nearest wins” algorithm. That is, it uses the version of the closest dependency to your project in the tree of dependencies. +The dependency resolution mechanism isn't as sophisticated as the one used in Yarn. As a result, you can only have a single version of a dependency in a project. In order to resolve this issue, Maven uses a "nearest wins" algorithm. That is, it uses the version of the closest dependency to your project in the tree of dependencies. For example, you have the following dependency graph: @@ -278,9 +275,9 @@ your-project --- A:1.0.0 --- B:2.0.0 \__ B:1.0.0 ``` -`your-project` depends on `A:1.0.0`, which in turn depends on `B:2.0.0` but your project also has a direct dependency on `B:1.0.0`. So, you have two different versions of dependency B in your dependency graph, but version 1.0.0 of dependency B wins as it is ‘nearest’ to your project. +`your-project` depends on `A:1.0.0`, which in turn depends on `B:2.0.0` but your project also has a direct dependency on `B:1.0.0`. So, you have two different versions of dependency B in your dependency graph, but version 1.0.0 of dependency B wins as it is "nearest" to your project. -In some cases, this scenario might work if the versions are compatible. However, if `A:1.0.0` depends on some feature of B that is only available in version `2.0.0` then this behavior doesn't work. In a worst case scenario, this project may still compile but fails at runtime. +In some cases, this scenario might work if the versions are compatible. However, if `A:1.0.0` depends on some feature of B that is only available in version `2.0.0` then this behavior doesn't work. In a worst case scenario, this project might still compile but fails at runtime. Let’s take a look at a real world example. @@ -331,7 +328,7 @@ You can verify this dependency by using the [Maven dependency plugin](https://ma First, check if there's a new version of `com.fasterxml.jackson.jaxrs:jackson-jaxrs-json-provider` that doesn’t depend on a vulnerable version of `com.fasterxml.jackson.core:jackson-databind`. If so, you can upgrade `com.fasterxml.jackson.jaxrs:jackson-jaxrs-json-provider` and stop there. If not, override the version of `com.fasterxml.jackson.core:jackson-databind`. -As shown in the code snippet, when using Maven the “nearest wins”, so the resolution is to add a direct dependency to `com.fasterxml.jackson.core:jackson-databind` that fixes the vulnerability. +As shown in the code snippet, when using Maven the "nearest wins", so the resolution is to add a direct dependency to `com.fasterxml.jackson.core:jackson-databind` that fixes the vulnerability. >[!div class="tabbedCodeSnippets"] ```java @@ -382,7 +379,7 @@ $ mvn dependency:tree -Dincludes=com.fasterxml.jackson.core:jackson-databind [INFO] ------------------------------------------------------------------------ ``` -It's recommended to add a comment near the dependency resolution, so that anyone coming later knows why the dependency is there. It can be removed once the root dependency uses the new version; otherwise, you accumulate dependencies. +We recommend you add a comment near the dependency resolution, so that anyone coming later knows why the dependency is there. It can be removed once the root dependency uses the new version; otherwise, you accumulate dependencies. In a real project, add the dependency as high up the chain as possible. For example, you could add the resolution in the parent POM file, instead of individually in every project POM file. @@ -435,34 +432,50 @@ The RCE vulnerability in `Microsoft.AspNetCore.Http.Connections` was fixed in ve       ``` -It's recommended to add a comment near the dependency resolution so that anyone coming later knows why the dependency is there. It can be removed once the root dependency uses the new version. Otherwise, you accumulate dependencies. +We recommend you add a comment near the dependency resolution so that anyone coming later knows why the dependency is there. It can be removed once the root dependency uses the new version. Otherwise, you accumulate dependencies. ### What if there's no fix available? When no known fix is available, the following options are available as other methods of remediation until an upgraded component is available: -* Stop using the component and remove it from your code - this removal will be detected upon your next build with the dependency scanning task installed +* Stop using the component and remove it from your code - this removal is detected upon your next build with the dependency scanning task installed * Contribute a fix to the component itself. If your organization has specific guidelines around open-source contributions, follow those guidelines. * Dismissing the alert. However, alerts with no known fix still can pose a security threat to your organization. We recommend that you don't dismiss an alert just because there's no known fix. ### Dismiss dependency scanning alerts -To dismiss alerts in Advanced Security, you need the appropriate permissions. By default, only project administrators are provided with the ability to dismiss Advanced Security alerts. +To dismiss an alert, do the following steps: + +1. Go to the alert you wish to close and select on the alert. +2. Select the **Close alert** drop-down. +3. If not already selected, select either **Risk accepted** or **False positive** as the closure reason. +4. Add an optional comment into the **Comment** text box. +5. Select **Close** to submit and close the alert. +6. The alert state changes from **Open** to **Closed** and displays your dismissal reason. + + ![Screenshot showing how to dismiss a dependency scanning alert](./media/dependency-scanning-dismiss-alert.png) + +This action dismisses the alert across all branches. Other branches that contain the same vulnerability will also be dismissed. Any alert previously dismissed can be manually reopened. + +### Managing dependency scanning alerts on pull requests + +If alerts are created for new code changes in a pull request, the alert is reported as an annotation in the **Overview** tab's comment section of the pull request and as an alert in the **Advanced Security** repository tab. A new branch picker entry is available for the pull request branch. + +You can see the affected package manifest, see a summary of the finding, and resolve the annotation in the Overview section. -To dismiss an alert: +[![Screenshot of active dependency pull request annotation.](./media/pull-request-annotation-dependency-scanning.png)](./media/pull-request-annotation-dependency-scanning.png#lightbox) -1. Go to the alert you wish to close and select on the alert -1. Select the **Close alert** drop-down -1. If not already selected, select either **Risk accepted** or **False positive** as the closure reason -1. Add an optional comment into the **Comment** text box -1. Select **Close** to submit and close the alert -1. The alert state changes from **Open** to **Closed** and displays your dismissal reason +To dismiss pull request alerts, you must navigate to the alert detail view to close both the alert and resolve the annotation. Otherwise, simply changing the comment status (1) resolves the annotation but doesn't close or fix the underlying alert. -![Screenshot showing how to dismiss a dependency scanning alert](./media/dependency-scanning-dismiss-alert.png) +[![Screenshot of closed dependency pull request annotation.](./media/pull-request-annotation-dependency-scanning-closed.png)](./media/pull-request-annotation-dependency-scanning-closed.png#lightbox) -This action only dismisses the alert for your selected branch. Other branches that may contain the same vulnerability stays active until otherwise acted upon. Any alert that has been previously dismissed can be manually re-opened. +To see the entire set of results for your pull request branch, navigate to **Repos** > **Advanced Security** and select your pull request branch. Selecting **Show more details** (2) on the annotation directs you to the alert detail view in the Advanced Security tab. -## Troubleshooting dependency scanning +> [!TIP] +> Annotations only get created when the affected lines of code are entirely unique to the pull request difference compared to the target branch of the pull request. -### Break-glass scenario for build task +## Related articles -If the dependency scanning build task is blocking a successful execution of your pipeline and you need to urgently skip the build task, you can set a pipeline variable `DependencyScanning.Skip: false`. \ No newline at end of file +- [Learn about supported package ecosystems](github-advanced-security-dependency-scanning-ecosystems.md) +- [Troubleshoot dependency scanning](github-advanced-security-dependency-scanning-troubleshoot.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Learn about Advanced Security](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-permissions.md b/docs/repos/security/github-advanced-security-permissions.md index f9d737706dd..e9a85439675 100644 --- a/docs/repos/security/github-advanced-security-permissions.md +++ b/docs/repos/security/github-advanced-security-permissions.md @@ -1,53 +1,68 @@ --- -title: Permissions for GitHub Advanced Security for Azure DevOps +title: Manage permissions for GitHub Advanced Security for Azure DevOps titleSuffix: Azure Repos description: Configure permissions for GitHub Advanced Security for Azure DevOps ms.service: azure-devops ms.subservice: azure-devops-integration ms.topic: how-to ms.custom: cross-service -ms.author: jukullam -author: juliakm +ms.author: laurajiang +author: laurajjiang monikerRange: 'azure-devops' -ms.date: 05/09/2023 +ms.date: 02/20/2025 --- -# Advanced Security permissions +# Manage Advanced Security permissions -[GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md) includes extra permissions for more levels of control around Advanced Security results and management. There are three new permissions added through Advanced Security: read alerts, dismiss and manage alerts, and manage settings. +GitHub Advanced Security for Azure DevOps includes extra permissions for more levels of control around Advanced Security results and management. There are three new permissions added through Advanced Security: read alerts, dismiss and manage alerts, and manage settings. [!INCLUDE [GitHub Advanced Security for Azure DevOps is different from GitHub Advanced Security.](includes/github-advanced-security.md)] +## Prerequisites + +[!INCLUDE [github-advanced-security-prerequisites](includes/github-advanced-security-prerequisites.md)] ### Default permissions and access levels +* Advanced Security: Read alerts grants permission to view security alerts for the repository. +* Advanced Security: Manage and dismiss alerts grants permission to dismiss alerts for the repository. +* Advanced Security: Manage settings grants permission to enable Advanced Security, which is a billable action. + | Azure DevOps group  | Default permissions | | ----------- | ----------- | -| Contributors | Advanced Security: read alerts | -| Project administrator | Advanced Security: read alerts, manage and dismiss alerts | -| Project collection administrator | Advanced Security: read alerts, manage and dismiss alerts, manage settings | +| Contributors | Advanced Security: Read alerts | +| Project administrator | Advanced Security: Read alerts, manage and dismiss alerts | +| Project collection administrator | Advanced Security: Read alerts, manage and dismiss alerts, manage settings | ## Manage Advanced Security permissions If you're running into an error when viewing Advanced Security alerts, you can adjust individual permissions for your repository. If the dropdowns are disabled, contact your administrator for the necessary permissions. + +To adjust permissions for a specific repository, do the following steps: -To adjust permissions for a specific repository: - -1. Go to **Project Settings** > **Repositories**. +1. Select **Project settings** > **Repositories**. 1. Select the specific repository you wish to adjust permissions for. 1. Select **Security**. 1. Select the security group you wish to adjust permissions for. -1. Select the permission bit to change. If successful, a green checkmark appears next to the selected permission. +2. Change a permission. When successful, a checkmark displays next to the selected permission. -![Screenshot of adjusting permissions for a specific repository](media/permissions-select-repo.png) + ![Screenshot of adjusting permissions for a specific repository.](media/permissions-select-repo.png) ### Use personal access tokens (PATs) -You can use a personal access token to use the Advanced Security APIs. To learn more about PATs on Azure DevOps and how to create them, refer to [About PATs](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). +[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] + +You can use a personal access token to use the Advanced Security APIs. For more information about PATs on Azure DevOps and how to create them, see [About PATs](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). Advanced Security offers three extra scopes for a PAT: `read`, `read and write`, and `read, write, and manage`. -![Screenshot of Advanced Security PAT scopes](media/pats-api.png) +![Screenshot of Advanced Security PAT scopes.](media/pats-api.png) + +## Related articles +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Learn about GitHub Advanced Security for Azure DevOps](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-secret-scan-patterns.md b/docs/repos/security/github-advanced-security-secret-scan-patterns.md new file mode 100644 index 00000000000..0daf3ab9ce4 --- /dev/null +++ b/docs/repos/security/github-advanced-security-secret-scan-patterns.md @@ -0,0 +1,53 @@ +--- +title: Secret scanning patterns for GitHub Advanced Security for Azure DevOps +titleSuffix: Azure Repos +description: Patterns for GitHub Advanced Security for Azure DevOps. +ms.service: azure-devops +ms.subservice: azure-devops-integration +ms.topic: conceptual +ms.custom: cross-service +ms.author: laurajiang +author: laurajjiang +monikerRange: 'azure-devops' +ms.date: 10/18/2024 +--- + +# Secret scanning patterns + +Advanced Security maintains multiple sets of default secret scanning patterns: + +* **Push protection patterns** - used to detect potential secrets at push time in repositories with secret scanning push protection enabled. +* **User alert patterns** - used to detect potential secrets in repositories with secret scanning alerts enabled. +* **Non-provider patterns** - used to detect common occurrences of structured secrets in repositories with secret scanning alerts enabled. + +## Supported secrets + +| Section | Explanation | +|---|---| +| Provider | The name of the token provider. | +| Token name | The type of token discovered by Advanced Security secret scanning. | +| User | A token for which leaks are reported to users post-push. Applies to all repositories where Advanced Security is enabled | +| Push protection | A token for which leaks are reported to users on push. Applies to all repositories where secret push protection enabled. | +| Validity | Tokens for which Advanced Security attempts to perform a validity check. | + +## Partner provider patterns + +The following table lists the partner provider patterns supported by secret scanning. + +[!INCLUDE [provider-table](includes/provider-table.md)] + +## Non-provider patterns + +The following table lists the non-provider generated secrets detected by secret scanning. Non-provider secrets are viewable by selecting "Other" from the confidence dropdown on the secret scanning tab. For more information, see [Manage secret scanning alerts](github-advanced-security-secret-scanning.md#manage-secret-scanning-alerts). + +> [!TIP] +> The detection of non-provider patterns is currently in beta and subject to change. + +[!INCLUDE [non-provider-table](includes/non-provider-table.md)] + +## Related articles + +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Learn about GitHub Advanced Security for Azure DevOps](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-secret-scanning-troubleshoot.md b/docs/repos/security/github-advanced-security-secret-scanning-troubleshoot.md new file mode 100644 index 00000000000..d673a4d2640 --- /dev/null +++ b/docs/repos/security/github-advanced-security-secret-scanning-troubleshoot.md @@ -0,0 +1,43 @@ +--- +title: Troubleshoot secret scanning for GitHub Advanced Security for Azure DevOps +titleSuffix: Azure Repos +description: Troubleshoot secret scanning for GitHub Advanced Security for Azure DevOps. +ms.service: azure-devops +ms.subservice: azure-devops-integration +ms.topic: how-to +ms.custom: cross-service +ms.author: laurajiang +author: laurajjiang +monikerRange: 'azure-devops' +ms.date: 02/20/2025 +--- + +# Troubleshoot secret scanning + +Learn how to troubleshoot common issues with GitHub Advanced Security for Azure DevOps' secret scanning feature. + +## Prerequisites + +[!INCLUDE [github-advanced-security-prerequisites](includes/github-advanced-security-prerequisites.md)] + +## Secret scanning repository scanning doesn't complete +If the repository-level secret scanning upon first enabling Advanced Security appears to be stuck after some time, attempt to disable then re-enable Advanced Security to reset the scanning operation. If re-enabling Advanced Security doesn't result in a successful operation after some time, push a new commit to your repository to reset the scan evaluation. If both of these suggestions don't result in a successful initial scan after a day, file a support ticket. + +## Push protection not blocking a secret +Ensure that the secret you're attempting to block is supported for push protection in [Supported secrets](github-advanced-security-secret-scan-patterns.md#supported-secrets). If the secret is modified in some way, the token might not match the original specification by the token provider. + +## No user alerts created for password +Ensure that the secret you're attempting to block is supported as a user alert in [Supported secrets](github-advanced-security-secret-scan-patterns.md#supported-secrets). If you're attempting to push a generically named secret, such as `password: password123` or `secret: password123`, secret scanning doesn't support this scenario and no alert is created nor does push protection apply. + +## No user alerts created for supported pattern +Some patterns might be looking for paired credentials, so only including one part of the pattern might not trigger an alert. For more information on paired credentials, see [About secret scanning alerts](./github-advanced-security-secret-scanning.md#about-secret-scanning-alerts). + +## Security overview reporting more critical alerts than shown at the repository-level +Security overview reports all secret alerts, including the `high confidence` provider patterns and the `other confidence` nonprovider patterns. In the repository-level Advanced Security view, select the `Confidence` filter dropdown to view `Confidence: other` findings. For more information on provider versus nonprovider patterns, see [Secret scanning patterns](./github-advanced-security-secret-scan-patterns.md#non-provider-patterns). + +## Related articles + +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Learn about GitHub Advanced Security for Azure DevOps](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-secret-scanning.md b/docs/repos/security/github-advanced-security-secret-scanning.md index 03e2d57f251..625345e5e38 100644 --- a/docs/repos/security/github-advanced-security-secret-scanning.md +++ b/docs/repos/security/github-advanced-security-secret-scanning.md @@ -1,37 +1,40 @@ --- -title: Secret Scanning for GitHub Advanced Security for Azure DevOps +title: Set up secret scanning for GitHub Advanced Security titleSuffix: Azure Repos -description: Set up secret scanning for GitHub Advanced Security for Azure DevOps +description: Set up secret scanning for GitHub Advanced Security for Azure DevOps. ms.service: azure-devops ms.subservice: azure-devops-integration ms.topic: how-to ms.custom: cross-service -ms.author: jukullam -author: juliakm +ms.author: laurajiang +author: laurajjiang monikerRange: 'azure-devops' -ms.date: 05/09/2023 +ms.date: 02/20/2025 --- -# Secret scanning +# Set up secret scanning -Exposed credentials in engineering systems provide easily exploitable opportunities for attackers. To defend against this threat, [GitHub Advanced Security for Azure DevOps](configure-github-advanced-security-features.md)'s secret scanning tool scans for credentials and other sensitive content in your source code. Push protection also prevents any credentials from being leaked in the first place. +Exposed credentials in engineering systems provide easily exploitable opportunities for attackers. To defend against this threat, GitHub Advanced Security for Azure DevOps scans for credentials and other sensitive content in your source code. Push protection also prevents any credentials from being leaked in the first place. -Secret scanning for your repository scans for any secrets that may already exist in your source code across history and push protection prevents any new secrets from being exposed in source code. +Secret scanning for your repository scans for any secrets that might already exist in your source code across history and push protection prevents any new secrets from being exposed in source code. [!INCLUDE [GitHub Advanced Security for Azure DevOps is different from GitHub Advanced Security.](includes/github-advanced-security.md)] +## Prerequisites + +[!INCLUDE [github-advanced-security-prerequisites](includes/github-advanced-security-prerequisites.md)] ## About secret scanning alerts -When Advanced Security is enabled, it scans repositories for secrets issued by a large variety of service providers and generates secret scanning alerts. +When you enable Advanced Security, it scans repositories for secrets issued by various service providers and generates secret scanning alerts. -If access to a resource requires paired credentials, then secret scanning may create an alert only when both parts of the pair are detected in the same file. Pairing ensures that the most critical leaks aren't hidden behind information about partial leaks. Pair matching also helps reduce false positives since both elements of a pair must be used together to access the provider's resource.​​​​​​ +If access to a resource requires paired credentials, secret scanning creates an alert only when both parts of the pair are detected in the same file. Pairing ensures that the most critical leaks aren't hidden behind information about partial leaks. Pair matching also helps reduce false positives since both elements of a pair must be used together to access the provider's resource. -The Advanced Security tab at **Repos** > **Advanced Security** in Azure DevOps is the hub to view your security alerts. Select the **Secrets** tab to view secret scanning alerts. You can filter by state and secret type. You can navigate into an alert for more details, including remediation guidance. Once you've enabled Advanced Security, a scan kicks off for the selected repository. Over time, alerts will start to appear as the scan progresses. +The Advanced Security tab at **Repos** > **Advanced Security** in Azure DevOps is the hub to view your security alerts. Select the **Secrets** tab to view secret scanning alerts. You can filter by state and secret type. Navigate into an alert for more details, including remediation guidance. After you enable Advanced Security, a scan kicks off for the selected repository, including all historical commits. Over time, alerts will start to appear as the scan progresses. -There's no impact to results if branches are renamed - it may take up to 24 hours before the new name is displayed. +Renaming branches doesn't affect the results. However, it might take up to 24 hours for the new name to display. -![Screenshot showing active secret scanning alerts](./media/secret-scanning-alerts.png) +![Screenshot showing active secret scanning alerts.](./media/secret-scanning-alerts.png) To remediate exposed secrets, invalidate the exposed credential and create a new one in its place. The newly created secret should then be stored securely in a way that doesn't directly push it back into the code. For example, the secret could be stored in Azure Key Vault. Most resources have both a primary and secondary credential. The method to roll a primary credential over versus a secondary credential are identical, unless otherwise noted. @@ -39,14 +42,17 @@ To remediate exposed secrets, invalidate the exposed credential and create a new ### Viewing alerts for a repository -Anyone with contributor permissions for a repository can view a summary of all alerts for a repository in the Advanced Security tab under Repos. Select on the **Secrets** tab to view all secret scanning alerts. +Select the **Secrets** tab to view all secret scanning alerts. -If Advanced Security was recently enabled for your repository, you may see a card indicating that Advanced Security is still scanning your repository. +If Advanced Security was recently enabled for your repository, you might see a card indicating that Advanced Security is still scanning your repository. -![Screenshot showing scanning for secrets](./media/secret-scanning-kickoff.png) +![Screenshot showing scanning for secrets.](./media/secret-scanning-kickoff.png) Once the scan is complete, any results are displayed. A single alert gets generated for each detected unique credential, across all branches and history of your repository. There are no branch filters as they're rolled up into one alert. +Nonprovider secrets are viewable by selecting "Other" from the confidence dropdown on the secret scanning tab. + +:::image type="content" source="media/secret-scanning-confidence-filter.png" lightbox="media/secret-scanning-confidence-filter.png" alt-text="Screenshot of GitHub Advanced Security secret scanning confidence filter."::: ### Alert details @@ -56,18 +62,21 @@ When you navigate into an alert, a detailed alert view appears and reveals more | Section | Explanation | |---|---| -| Location | The **Locations** section details the path(s) where secret scanning has discovered the leaked credential. There may be multiple locations or multiple commits in history that contain the leaked credential. All of these locations and commits are displayed under the **Locations** with a direct link to the code snippet and commit it was identified in. | -| Recommendation | The recommendation section contains remediation guidance or link to third-party documentation remediation guidance for the identified credential. | -| Close alert | There's no autofix behavior for secret scanning alerts. All secret scanning alerts must be manually attested as fixed through the alert detail page. Select the **Close** button to verify that the secret has been revoked. | +| Location | The **Locations** section details the paths where secret scanning discovered the leaked credential. There might be multiple locations or multiple commits in history that contain the leaked credential. All of these locations and commits are displayed under the **Locations** with a direct link to the code snippet and commit it was identified in. | +| Recommendation | The recommendation section contains remediation guidance or link to non-Microsoft documentation remediation guidance for the identified credential. | +| Close alert | There's no autofix behavior for secret scanning alerts. All secret scanning alerts must be manually attested as fixed through the alert detail page. Select the **Close** button to verify that the secret is revoked. | | Severity | All secret scanning alerts are set as critical. Any exposed credential is potentially an opportunity for a malicious actor. | | Finding details | The type of credential and rule used to find the credential are listed under the **Finding details** on the sidebar of the alert details page. | +With nonprovider secrets, the **Confidence: other** tag also appears by the severity badge in the alert detail view. + +:::image type="content" source="media/secret-scanning-detail-confidence-other.png" lightbox="media/secret-scanning-detail-confidence-other.png" alt-text="Screenshot of GitHub Advanced Security secret scanning generic alert detail."::: ### Fixing secret scanning alerts Each secret has unique remediation steps to guide you through how to revoke and regenerate a new secret in its place. The alert detail shares specific steps or documentation for each alert. -A secret scanning alert stays open until closed. To attest that a secret scanning alert has been fixed: +A secret scanning alert stays open until closed. To attest that a secret scanning alert is fixed: 1. Navigate to the alert you wish to close and select the alert. 1. Select the **Close alert** drop-down. @@ -76,12 +85,9 @@ A secret scanning alert stays open until closed. To attest that a secret scannin ![Screenshot showing how to close a secret scanning alert](./media/secret-scanning-close-alert.png) - ### Dismissing secret scanning alerts -To dismiss alerts in Advanced Security, you need the appropriate permissions. By default, only project administrators can dismiss Advanced Security alerts. For more about Advanced Security permissions, see [Manage Advanced Security permissions](github-advanced-security-permissions.md). - -To dismiss an alert: +To dismiss an alert, do the following steps: 1. Navigate to the alert you wish to close and select on the alert. 1. Select the **Close alert** drop-down. @@ -90,20 +96,21 @@ To dismiss an alert: 1. Select **Close** to submit and close the alert. 1. The alert state changes from **Open** to **Closed** and displays your dismissal reason. - ![Screenshot showing dismissal details for a secret scanning alert](./media/secret-scanning-dismiss-alert.png) -Any alert that has been previously dismissed can be manually reopened. +You can manually open any previously dismissed alert. -### Securing compromised secrets +### Make compromised secrets secure -Once a secret has been committed to a repository, the secret is compromised. Microsoft recommends the following actions for compromised secrets: +Once a secret gets committed to a repository, the secret is compromised. Microsoft recommends the following actions for compromised secrets: + +[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] * For a compromised Azure DevOps personal access token, delete the compromised token, create a new token, and update any services that use the old token. * For all other secrets, first verify that the secret committed to Azure Repos is valid. If so, create a new secret, update any services that use the old secret, and then delete the old secret. -* identify any actions taken by the compromised token on your enterprise's resources. +* Identify any actions taken by the compromised token on your enterprise's resources. -When updating a secret, be sure to store the new secret securely, and ensure that it's always accessed and never stored as plaintext. This can be through Azure Keyvault or other secret management solutions. +When you update a secret, store the new secret securely and ensure that it never gets stored as plaintext. One option is to use Azure Key Vault or other secret management solutions. ## Secret push protection @@ -113,20 +120,19 @@ Push protection checks any incoming pushes for high-confidence secrets and preve Push protection alerts are user alerts that reported by push protection. Secret scanning as a push protection currently scans repositories for secrets issued by some service providers. -If access to a resource requires paired credentials, then secret scanning may create an alert only when both parts of the pair are detected in the same file. The pairing ensures that the most critical leaks aren't hidden behind information about partial leaks. Pair matching also helps reduce false positives since both elements of a pair must be used together to access the provider's resource. - -Push protection may not block older versions of certain tokens as these tokens may generate a higher number of false positives than their most recent version. Push protection may also not block legacy tokens. For tokens such as Azure Storage Keys, Advanced Security only supports recently created tokens, not tokens that match the legacy patterns. +If access to a resource requires paired credentials, then secret scanning might create an alert only when both parts of the pair are detected in the same file. The pairing ensures that the most critical leaks aren't hidden behind information about partial leaks. Pair matching also helps reduce false positives since both elements of a pair must be used together to access the provider's resource. +Push protection might not block older versions of certain tokens as these tokens might generate a higher number of false positives than their most recent version. Push protection might also not block legacy tokens. For tokens such as Azure Storage Keys, Advanced Security only supports recently created tokens, not tokens that match the legacy patterns. ### Push protection from the command line -Push protection is built natively into Azure DevOps Git. If your commits contain an identified secret, you see an error that your push was rejected. +Push protection is built natively into Azure DevOps Git. If your commits contain an identified secret, the following error displays that your push was rejected. ![Screenshot showing a git push being blocked from VS Code](./media/secret-scanning-push-protection-block.png) ### Push protection from the web interface -Push protection also works from the web interface. If a secret is identified in a commit, you see the following error block that stops you from pushing your changes: +Push protection also works from the web interface. If a secret is identified in a commit, the following error block displays, which stops you from pushing your changes: ![Screenshot showing a git push being blocked from AzDO web UI](./media/secret-scanning-push-protection-block-web.png) @@ -134,12 +140,12 @@ Push protection also works from the web interface. If a secret is identified in Push protection blocks secrets found in plain text files that are usually (but not limited to) text files such as source code or JSON configuration files. These secrets are stored in plaintext. If a bad actor gains access to the files and they get published to a public repository, the secrets are usable by anyone. -It's recommended to remove the secret from the flagged file then remove the secret from the commit history. If the flagged secret is a placeholder or example secret, it's recommended that you update the fake secret to prepend the string `Placeholder` in front of the fake secret. +Remove the secret from the flagged file, and then remove the secret from the commit history. If the flagged secret is a placeholder or example secret, update the fake secret to prepend the string `Placeholder` in front of the fake secret. If the secret was added in your immediate previous commit, amend the commit and create a new commit: 1. Remove the secret from your code. -1. Commit the changes by using `git commit --amend` -1. Push your changes again. +2. Commit the changes by using `git commit --amend` +3. Push your changes again. If the secret was added further back in history, edit your commits using an interactive rebase: 1. Use `git log` to determine which commit you first committed the secret. @@ -148,130 +154,18 @@ If the secret was added further back in history, edit your commits using an inte 1. Identify your commit to edit by changing `pick` to `edit` on the first line of the text that appears in the editor. 1. Remove the secret from your code. 1. Commit the change with `git commit --amend`. -1. Run `git rebase --continue` to finish the rebase. +1. Finish the rebase by running `git rebase --continue`. ### Push a blocked secret -Bypassing flagged secrets isn't recommended because bypassing can put your company’s security at risk. If you confirm that an identified secret isn't a false positive, you should remove the secret from your entire branch history before attempting to push your changes again. - -If you believe a blocked secret is a false positive or safe to push, you can bypass push protection. Include the string `skip-secret-scanning:true` in your commit message. Even if you bypass push protection, a secret scanning alert is generated in the alert UX once the secret has been pushed. - - -## Secret scanning patterns - -GitHub Advanced Security maintains multiple sets of default secret scanning patterns: - -1. **Push protection patterns** - used to detect potential secrets at push time in repositories with secret scanning push protection enabled. -1. **Alert patterns** - used to detect potential secrets in repositories with secret scanning alerts enabled. - -### Supported secrets - -This table lists the secrets supported by secret scanning. You can see the types of alert that get generated for each token. - -- Provider—name of the token provider. -- User—token for which leaks are reported to users post-push. Applies to repositories where GitHub Advanced Security is enabled. -- Push protection—token for which leaks are reported to users on push. Applies to repositories with secret scanning and push protection enabled. - -| Provider | Supported secret | User | Push Protection | -| ------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------- | -| Adafruit IO | Adafruit IO Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Alibaba Cloud | Alibaba Cloud Access Key ID with Alibaba Cloud Access Key Secret | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Amazon | Amazon OAuth Client ID with Amazon OAuth Client Secret | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Amazon Web Services (AWS) | Amazon AWS Access Key ID with Amazon AWS Secret Access Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Amazon Web Services (AWS) | Amazon AWS Session Token with Amazon AWS Temporary Access Key ID and Amazon AWS Secret Access Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Asana | Asana Personal Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Atlassian | Bitbucket Server Personal Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Chief Tools | Chief Tools Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Clojars | Clojars Deploy Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Databricks | Databricks Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| DevCycle | DevCycle Client API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| DevCycle | DevCycle Mobile API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| DevCycle | DevCycle Server API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| DigitalOcean | DigitalOcean OAuth Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| DigitalOcean | DigitalOcean Personal Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| DigitalOcean | DigitalOcean Refresh Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| DigitalOcean | DigitalOcean System Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Discord | Discord Bot Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Doppler | Doppler Audit Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Doppler | Doppler CLI Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Doppler | Doppler Personal Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Doppler | Doppler SCIM Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Doppler | Doppler Service Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Dropbox | Dropbox Short Lived Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Duffel | Duffel Live Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| EasyPost | EasyPost Production API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Figma | Figma Personal Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Flutterwave | Flutterwave Live API Secret Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| FullStory | FullStory API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| GitHub | GitHub Personal Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| GitHub | GitHub App Installation Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| GitHub | GitHub OAuth Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| GitHub | GitHub Refresh Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Google | Google OAuth Client ID with Google OAuth Client Secret | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Google | Google Cloud Storage Service Account Access Key ID with Google Cloud Storage Access Key Secret | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Google | Google Cloud Storage User Access Key ID with Google Cloud Storage Access Key Secret | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Grafana | Grafana API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| HashiCorp | HashiCorp Vault Batch Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| HashiCorp | HashiCorp Vault Root Service Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| HashiCorp | HashiCorp Vault Service Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Highnote | Highnote RK Live Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Highnote | Highnote RK Test Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Highnote | Highnote SK Live Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Highnote | Highnote SK Test Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Hubspot | Hubspot API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Hubspot | Hubspot API Personal Access Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Intercom | Intercom Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Ionic | Ionic Personal Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Ionic | Ionic Refresh Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| JFrog | JFrog Platform API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| JFrog | JFrog Platform Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Linear | Linear API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Linear | Linear OAuth Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| LogicMonitor | LogicMonitor Bearer Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| LogicMonitor | LogicMonitor LMV1 Access Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Azure DevOps Personal Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Office/Teams Inbound Webhook | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Azure Storage Key Identifiable | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Azure Cache for Redis Access Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Azure Active Directory Application Secret | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Azure Functions V4+ KEY | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Azure Cosmos DB Key Identifiable | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Azure Batch Key Identifiable | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Azure Search Query Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Azure Search Admin Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Microsoft | Azure Machine Learning studio (classic) web service key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Midtrans | Midtrans Production Server Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| New Relic | New Relic Insights Query Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| New Relic | New Relic Personal API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| New Relic | New Relic REST API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| npm | npm Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| NuGet | NuGet API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Onfido | Onfido Live API Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| OpenAI | OpenAI API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| PlanetScale | PlanetScale Database Password | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| PlanetScale | PlanetScale OAuth Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| PlanetScale | PlanetScale Service Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Postman | Postman API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Prefect | Prefect Server API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Prefect | Prefect User API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Proctorio | Proctorio Secret Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| ReadMe | ReadMe API Access Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| redirect.pizza | redirect.pizza API Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Samsara | Samsara API Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Samsara | Samsara OAuth Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| SendGrid | SendGrid API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Sendinblue | Sendinblue API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Sendinblue | Sendinblue SMTP Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Shippo | Shippo Live API Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Shopify | Shopify Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Shopify | Shopify App Shared Secret | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Slack | Slack API Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Stripe | Stripe API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Tencent Cloud | Tencent Cloud Secret ID | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Typeform | Typeform Personal Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Uniwise | WISEflow API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| WakaTime | WakaTime App Secret | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| WakaTime | WakaTime OAuth Access Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| WakaTime | WakaTime OAuth Refresh Token | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| WorkOS | WorkOS Production API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | -| Zuplo | Zuplo Consumer API Key | ![Green Checkmark](../../media/icons/checkmark.png) | ![Green Checkmark](../../media/icons/checkmark.png) | \ No newline at end of file +Don't bypass flagged secrets because doing so can put your company’s security at risk. If you confirm that an identified secret isn't a false positive, remove the secret from your entire branch history before you attempt to push your changes again. + +If you believe a blocked secret is a false positive or safe to push, you can bypass push protection. Include the string `skip-secret-scanning:true` in your commit message. Even if you bypass push protection, a secret scanning alert is generated in the alert UX once the secret gets pushed. + +## Related articles + +- [Troubleshoot secret scanning](github-advanced-security-secret-scanning-troubleshoot.md) +- [Learn about secret scanning patterns](github-advanced-security-secret-scan-patterns.md) +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Learn about GitHub Advanced Security for Azure DevOps](github-advanced-security-security-overview.md) diff --git a/docs/repos/security/github-advanced-security-security-overview.md b/docs/repos/security/github-advanced-security-security-overview.md new file mode 100644 index 00000000000..f9a55672949 --- /dev/null +++ b/docs/repos/security/github-advanced-security-security-overview.md @@ -0,0 +1,47 @@ +--- +title: Security overview on GitHub Advanced Security for Azure DevOps +titleSuffix: Azure Repos +description: Utilize security overview for GitHub Advanced Security for Azure DevOps +ms.service: azure-devops +ms.subservice: azure-devops-integration +ms.topic: conceptual +ms.custom: cross-service +ms.author: laurajiang +author: laurajjiang +monikerRange: 'azure-devops' +ms.date: 03/28/2024 +--- + +# Security overview +Security overview provides a single pane of glass to view a summary of your organization's security risk and Advanced Security enablement status. + +All organizations, regardless of if they have an Advanced Security-enabled repository or not, are able to see the security overview tab in their organization settings. + +[!INCLUDE [GitHub Advanced Security for Azure DevOps is different from GitHub Advanced Security.](includes/github-advanced-security.md)] + +## About security overview +Security overview is available to view for all members of the organization who have access to view organization settings. Under the **Risk** tab, security overview shows you the distribution of total alerts and of alerts by severity across all projects and repositories with Advanced Security enabled under your selected organization. Under the **Coverage** tab, security overview shows the enablement status and navigation to repository settings to quickly enable Advanced Security for any repository. + +## Viewing security insights +To access the security overview for your organization, navigate to **Organization settings > Security overview**. The default view is of the **Risk** tab, which shows a summary of security alerts across your organization. In the **Risk** view, only repositories with Advanced Security enabled appear. The reported alert counts are only for alerts discovered on the default branch for each repository. + +You can sort by each of the column headers in the table (`Open`, `New`, `Dismissed`, `Fixed`) and modify your query using the search bar for keywords or drop-down filters for project, tool, and time-bound. The time-bound will default to showing results from the past seven days. Any filters applied will also be pushed as a URL parameter to facilitate sharability of your query. + +:::image type="content" source="media/security-overview-risk.png" lightbox="media/security-overview-risk.png" alt-text="Screenshot of Risk tab in security overview for an organization."::: + +Under the **Coverage** tab, security overview shows all repositories in your enterprise, regardless of their enablement status. For any repositories that have Advanced Security enabled, a breakdown of each tool is also included: + +:::image type="content" source="media/security-overview-coverage.png" lightbox="media/security-overview-coverage.png" alt-text="Screenshot of Coverage tab in security overview for an organization."::: + +Dependency scanning, code scanning, and secret scanning alerts are enabled once a SARIF result file gets successfully submitted to Advanced Security. In other words, a successful scan regardless of alert discovery on any branch for a repository lights up coverage for that particular tool and repository. The enablement status doesn't consider recency of the scan. There may be up to a 24-hour delay for recent enablement events after selecting `Enable all` at the organization or project level. + +Hovering on a specific repository and selecting the cog icon directs you to that repository's settings pane where you can enable Advanced Security. For more information about configuring Advanced Security features, see [Configure GitHub Advanced Security](configure-github-advanced-security-features.md). + +:::image type="content" source="media/enable-github-advanced-security.png" lightbox="media/enable-github-advanced-security.png" alt-text="Screenshot of enabling GitHub Advanced Security."::: + +## Related articles + +- [Set up code scanning](github-advanced-security-code-scanning.md) +- [Set up dependency scanning](github-advanced-security-dependency-scanning.md) +- [Set up secret scanning](github-advanced-security-secret-scanning.md) +- [Manage GitHub Advanced Security for Azure DevOps](github-advanced-security-permissions.md) diff --git a/docs/repos/security/includes/github-advanced-security-prerequisites.md b/docs/repos/security/includes/github-advanced-security-prerequisites.md new file mode 100644 index 00000000000..07538824698 --- /dev/null +++ b/docs/repos/security/includes/github-advanced-security-prerequisites.md @@ -0,0 +1,14 @@ +--- +ms.topic: include +ms.service: azure-devops-repos +ms.author: chcomley +author: chcomley +ms.date: 02/20/2025 +--- + + +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To view a summary of all alerts for a repository: **Contributor** permissions for the repository.
      - To dismiss alerts in Advanced Security: **Project administrator** permissions.
      - To manage permissions in Advanced Security: Member of the [**Project Collection Administrators**](../../../organizations/security/change-organization-collection-level-permissions.md) group or **Advanced Security: manage settings** permission set to *Allow*.| + +For more information about Advanced Security permissions, see [Manage Advanced Security permissions](../github-advanced-security-permissions.md). diff --git a/docs/repos/security/includes/github-advanced-security-preview.md b/docs/repos/security/includes/github-advanced-security-preview.md new file mode 100644 index 00000000000..cda454d676d --- /dev/null +++ b/docs/repos/security/includes/github-advanced-security-preview.md @@ -0,0 +1,12 @@ +--- +ms.topic: include +ms.service: azure-devops-repos +ms.manager: mijacobs +ms.author: jukullam +author: juliakm +ms.date: 08/07/2023 +--- + +> [!IMPORTANT] +> GitHub Advanced Security for Azure DevOps is currently in public preview. +> See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability. diff --git a/docs/repos/security/includes/github-advanced-security.md b/docs/repos/security/includes/github-advanced-security.md index dc366db4d7e..6b2b4c0fda3 100644 --- a/docs/repos/security/includes/github-advanced-security.md +++ b/docs/repos/security/includes/github-advanced-security.md @@ -8,5 +8,4 @@ ms.date: 05/04/2023 --- -> [!NOTE] -> GitHub Advanced Security for Azure DevOps works with Azure Repos. If you want to use GitHub Advanced Security with GitHub repositories, see [GitHub Advanced Security](https://docs.github.com/get-started/learning-about-github/about-github-advanced-security). \ No newline at end of file +GitHub Advanced Security for Azure DevOps works with Azure Repos. To use GitHub Advanced Security with GitHub repositories, see [GitHub Advanced Security](https://docs.github.com/get-started/learning-about-github/about-github-advanced-security). diff --git a/docs/repos/security/includes/non-provider-table.md b/docs/repos/security/includes/non-provider-table.md new file mode 100644 index 00000000000..15bf84a252d --- /dev/null +++ b/docs/repos/security/includes/non-provider-table.md @@ -0,0 +1,28 @@ +--- +ms.topic: include +ms.service: azure-devops-repos +ms.author: nicour +author: ncouraud +ms.date: 02/27/2025 +--- + +| Rule ID | Token Name | User Alerts | Validity Checking | +| --- | --- | --- | --- | +| SEC101/122 | AspNetMachineKey | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/042 | DynatraceToken | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/528 | GenericJwt | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/032 | GpgCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/009 | LinkedInCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/033 | MongoDbCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/036 | MySqlCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/056 | OpenSshPrivateKey | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/013 | PemPrivateKey | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/058 | PgpPrivateKey | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/055 | Pkcs12CertificatePrivateKeyBundle | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/054 | PkcsPrivateKey | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/038 | PostgreSqlCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/057 | PuttyPrivateKey | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/041 | RabbitMQCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/059 | RsaPrivateKey | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/037 | SqlLegacyCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/127 | UrlCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | | \ No newline at end of file diff --git a/docs/repos/security/includes/provider-table.md b/docs/repos/security/includes/provider-table.md new file mode 100644 index 00000000000..1ae3c0b5a4f --- /dev/null +++ b/docs/repos/security/includes/provider-table.md @@ -0,0 +1,322 @@ +--- +ms.topic: include +ms.service: azure-devops-repos +ms.author: nicour +author: ncouraud +ms.date: 02/27/2025 +--- + +| Rule ID | Token Name | Push Protection | User Alerts | Validity Checking | +| --- | --- | --- | --- | --- | +| SEC101/156 | AadClientAppIdentifiableCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/501 | AdafruitIOKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/201 | AdoIdentifiablePat | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/102 | AdoLegacyPat | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/600 | AdobeDeviceToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/601 | AdobeServiceToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/602 | AdobeShortLivedAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/015 | AkamaiCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/029 | AlibabaCloudCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/023 | AmazonMwsAuthToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/503 | AmazonOAuthCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/701 | AnthropicApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/504 | AsanaPat | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/605 | AtlassianJwt | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/604 | AtlassianLegacyApiToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/008 | AwsCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/505 | AwsTemporaryCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/157 | AzureApimDirectManagementSas | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/186 | AzureApimGatewaySas | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/181 | AzureApimIdentifiableDirectManagementKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/183 | AzureApimIdentifiableGatewayKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/184 | AzureApimIdentifiableRepositoryKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/182 | AzureApimIdentifiableSubscriptionKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/132 | AzureApimLegacyDirectManagementKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/187 | AzureApimLegacyGatewayKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/188 | AzureApimLegacyRepositoryKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/133 | AzureApimLegacySubscriptionKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/185 | AzureApimRepositorySas | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/197 | AzureAppConfigurationIdentifiableCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/131 | AzureAppConfigurationLegacyCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/138 | AzureApplicationInsightsCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/194 | AzureAutomationAccountKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/163 | AzureBatchIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/113 | AzureBatchLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/118 | AzureBlockchainCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/154 | AzureCacheForRedisIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/155 | AzureCacheForRedisIdentifiablePrivateServiceKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/103 | AzureCacheForRedisLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/151 | AzureCdnSas | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/125 | AzureCognitiveServicesLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/134 | AzureCognitiveServicesTranslatorLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/204 | AzureCommunicationServicesIdentifiableKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/137 | AzureCommunicationServicesLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/176 | AzureContainerRegistryIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/109 | AzureContainerRegistryLegacyKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/160 | AzureCosmosDBIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/161 | AzureCosmosDBIdentifiablePrivateServiceKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/104 | AzureCosmosDBLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/250 | AzureCosmosDBSas | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/110 | AzureDatabricksPat | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/256 | AzureDatabricksPrivateServiceKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/148 | AzureDevOpsOAuthToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/199 | AzureEventGridIdentifiableKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/119 | AzureEventGridLegacyKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/172 | AzureEventHubIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/175 | AzureEventHubIdentifiablePrivateServiceSystemKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/198 | AzureFluidRelayIdentifiableKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/190 | AzureFluidRelayLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/158 | AzureFunctionIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/112 | AzureFunctionLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/140 | AzureGenomicsKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/141 | AzureHDInsightCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/180 | AzureIotDeviceIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/146 | AzureIotDeviceLegacyCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/179 | AzureIotDeviceProvisioningIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/115 | AzureIotDeviceProvisioningLegacyCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/178 | AzureIotHubIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/114 | AzureIotHubLegacyCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/150 | AzureLogicAppSas | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/169 | AzureMLIdentifiablePrivateServicePrincipalCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/170 | AzureMLWebServiceClassicIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/123 | AzureMLWebServiceKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/129 | AzureManagementCertificate | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/203 | AzureMapsIdentifiableKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/116 | AzureMapsLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/105 | AzureMessagingLegacyCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/202 | AzureMixedRealityIdentifiableCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/136 | AzureMixedRealityLegacyCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/189 | AzureOpenAILegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/246 | AzureRateCardSas | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/173 | AzureRelayIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/167 | AzureSearchIdentifiableAdminKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/168 | AzureSearchIdentifiablePrivateServiceAdminKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/166 | AzureSearchIdentifiableQueryKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/111 | AzureSearchLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/171 | AzureServiceBusIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/174 | AzureServiceBusIdentifiablePrivateServiceSystemKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/121 | AzureServiceDeploymentCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/253 | AzureSignalRIdentifiableKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/254 | AzureSignalRIdentifiableTemporaryKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/117 | AzureSignalRLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/258 | AzureSpringAppTestEndpointKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/152 | AzureStorageAccountIdentifiableCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/106 | AzureStorageAccountLegacyCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/251 | AzureStorageIdentifiablePrivateServiceKerberosKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/153 | AzureStorageIdentifiablePrivateServiceKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/120 | AzureWebAppBotCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/257 | AzureWebAppBotIdentifiableKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/142 | AzureWebAppBotLegacyKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/248 | AzureWebPubSubIdentifiableCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/249 | AzureWebPubSubIdentifiableTemporaryCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/144 | AzureWebPubSubLegacyCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/606 | BeamerApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/143 | BingApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/128 | BingMapsKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/135 | BingSearchKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/566 | BrevoApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/567 | BrevoSmtpKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/692 | BrowserStackCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/594 | CdsCanadaNotifyApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/507 | CheckoutApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/579 | ChiefToolsToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/145 | CiscoLocalAccountCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/508 | ClojarsDeployToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/035 | CloudantCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/697 | CohereApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/200 | CommonAnnotatedSecurityKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/609 | ContentfulPersonalAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/034 | CredentialObject | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/509 | DevCycleClientApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/557 | DevCycleManagementApiToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/510 | DevCycleMobileApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/511 | DevCycleServerApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/512 | DigitalOceanOAuthToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/513 | DigitalOceanPat | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/514 | DigitalOceanRefreshToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/515 | DigitalOceanSystemToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/046 | DiscordApiCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/516 | DiscordApiToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/517 | DopplerAuditToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/518 | DopplerCliToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/519 | DopplerPersonalToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/520 | DopplerScimToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/521 | DopplerServiceToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/020 | DropboxAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/021 | DropboxAppCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/522 | DropboxOAuth2ShortLivedAccessToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/523 | DuffelAccessToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/611 | DynatraceInternalToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/613 | EBayProductionClientCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/614 | EBaySandboxClientCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/524 | EasyPostApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/682 | ElasticCloudApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/681 | ElasticStackApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/196 | EntraToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/014 | FacebookAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/525 | FigmaPat | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/618 | FinicityAppKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/625 | FirebaseCloudMessagingServerKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/687 | FlickrApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/526 | FlutterwaveLiveApiSecretKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/619 | FlutterwaveTestApiSecretKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/621 | FrameIODeveloperToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/620 | FrameIOJwt | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/527 | FullStoryApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/007 | GitHubAppCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/529 | GitHubAppToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/530 | GitHubOAuthAccessToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/690 | GitHubOauth2Credentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/534 | GitHubPat | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/531 | GitHubRefreshToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/532 | GitHubServerToServerToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/535 | GitHubUserToServerToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/622 | GitLabAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/623 | GoCardlessLiveAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/624 | GoCardlessSandboxAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/003 | GoogleApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/626 | GoogleCloudPrivateKeyId | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/536 | GoogleCloudStorageServiceAccountAccessKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/537 | GoogleCloudStorageUserAccessKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/627 | GoogleOAuthAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/002 | GoogleOAuthCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/628 | GoogleOAuthRefreshToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/030 | GoogleServiceAccountKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/538 | GrafanaCloudApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/629 | GrafanaCloudApiToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/630 | GrafanaProjectApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/631 | GrafanaProjectServiceAccountToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/581 | HashiCorpVaultBatchLegacyToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/582 | HashiCorpVaultBatchToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/580 | HashiCorpVaultRootServiceToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/583 | HashiCorpVaultServiceLegacyToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/584 | HashiCorpVaultServiceToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/732 | HereApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/585 | HighnoteRkKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/586 | HighnoteSkKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/589 | HubSpotApiPersonalAccessKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/539 | HubspotApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/686 | HuggingFaceAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/693 | InfuraApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/540 | IntercomAccessToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/541 | IonicPat | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/542 | IonicRefreshToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/590 | JFrogPlatformAccessToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/543 | JFrogPlatformApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/632 | JdCloudAccessKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/696 | KaggleApiToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/700 | LangChainApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/691 | LaunchDarklyApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/544 | LinearApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/545 | LinearOAuthAccessToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/633 | LobLiveApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/634 | LobTestApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/635 | LocalStackApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/546 | LogicMonitorBearerToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/547 | LogicMonitorLmv1AccessKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/027 | MailChimpApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/026 | MailgunApiCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/636 | MapboxSecretAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/548 | MidtransServerKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/699 | MistralApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/549 | NewRelicInsightsQueryKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/639 | NewRelicLicenseKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/550 | NewRelicPersonalApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/551 | NewRelicRestApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/694 | NitroApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/640 | NotionIntegrationToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/641 | NotionOAuthClientCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/050 | NpmAuthorToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/044 | NpmCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/031 | NuGetApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/043 | NuGetCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/642 | OctopusDeployApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/643 | OculusAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/147 | OfficeIncomingWebhook | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/552 | OnfidoApiToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/553 | OpenAIApiKeyV2 | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/695 | OpenWeatherApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/645 | PalantirJwt | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/022 | PayPalBraintreeAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/698 | PerplexityApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/646 | PersonaProductionApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/647 | PersonaSandboxApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/019 | PicaticApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/680 | PineconeApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/554 | PlanetScaleDatabasePassword | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/555 | PlanetScaleOAuthToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/556 | PlanetScaleServiceToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/648 | PlivoCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/045 | PostmanApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/558 | PrefectServerApiToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/559 | PrefectUserApiToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/650 | ProctorioConsumerKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/651 | ProctorioLinkageKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/652 | ProctorioRegistrationKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/560 | ProctorioSecretKeyV2 | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/653 | PulumiAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/654 | PyPiApiToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/561 | ReadMeApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/562 | RedirectPizzaApiToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/655 | RubyGemsApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/664 | SSLMateApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/665 | SSLMateClusterSecret | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/563 | SamsaraApiAccessToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/564 | SamsaraOAuth2AccessToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/656 | SegmentPublicApiToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/025 | SendGridApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/568 | ShippoLiveApiToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/657 | ShippoTestApiToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/039 | ShopifyAccessToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/658 | ShopifyAppClientCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/659 | ShopifyAppClientSecret | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/608 | ShopifyAppOAuthAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/603 | ShopifyCustomAppAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/661 | ShopifyMarketplaceToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/660 | ShopifyMerchantToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/662 | ShopifyPartnerApiToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/666 | ShopifyPrivateAppPassword | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/040 | ShopifySharedSecret | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/005 | SlackApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/571 | SlackAppLevelToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/012 | SlackWebhook | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/048 | SlackWorkflowKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/683 | SplunkHecApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/684 | SplunkJwtToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/685 | SplunkSessionKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/177 | SqlIdentifiableCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/663 | SquareApplicationSecret | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/011 | SquareCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/010 | SquarePat | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/016 | StripeLiveApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/052 | StripeLiveRestrictedApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/051 | StripeTestApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/053 | StripeTestRestrictedApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/667 | StripeWebhookSigningSecret | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/668 | SupabaseServiceKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/669 | TableauPersonalAccessToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/049 | TelegramBotToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/670 | TelnyxApiV2Key | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/572 | TencentCloudCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/573 | TerraformCloudEnterpriseToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/024 | TwilioApiKeyCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/018 | TwilioCredentials | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/574 | TypeformPat | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/124 | VisualStudioAppCenterKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/575 | WISEFlowApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/591 | WakaTimeAppCredentials | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/592 | WakaTimeOAuthAccessToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/593 | WakaTimeOAuthRefreshToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/688 | WeatherstackApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/576 | WorkOSProductionApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/671 | WorkOSStagingApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/255 | XboxLiveSas | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/672 | YandexCloudApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/676 | YandexCloudIamAccessSecret | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/673 | YandexCloudIamCookie | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/674 | YandexCloudIamToken | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/675 | YandexDictionaryApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/577 | YandexPassportOAuthToken | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/677 | YandexPredictorApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/678 | YandexTranslateApiKey | | ![Green Checkmark](../../../media/icons/checkmark.png) | | +| SEC101/578 | ZuploConsumerApiKey | ![Green Checkmark](../../../media/icons/checkmark.png) | ![Green Checkmark](../../../media/icons/checkmark.png) | | \ No newline at end of file diff --git a/docs/repos/security/media/billing-active-committer-count.png b/docs/repos/security/media/billing-active-committer-count.png index 4adc604a749..fef4b602ea9 100644 Binary files a/docs/repos/security/media/billing-active-committer-count.png and b/docs/repos/security/media/billing-active-committer-count.png differ diff --git a/docs/repos/security/media/classic-pipeline-sample.png b/docs/repos/security/media/classic-pipeline-sample.png index 51d178f9f43..7da35b303b3 100644 Binary files a/docs/repos/security/media/classic-pipeline-sample.png and b/docs/repos/security/media/classic-pipeline-sample.png differ diff --git a/docs/repos/security/media/code-scanning-config-classic-tasks.png b/docs/repos/security/media/code-scanning-config-classic-tasks.png index 02ba2e835de..06ebc7dead5 100644 Binary files a/docs/repos/security/media/code-scanning-config-classic-tasks.png and b/docs/repos/security/media/code-scanning-config-classic-tasks.png differ diff --git a/docs/repos/security/media/code-scanning-config-yaml-tasks.png b/docs/repos/security/media/code-scanning-config-yaml-tasks.png index 5aa233af91f..2014c90d1c6 100644 Binary files a/docs/repos/security/media/code-scanning-config-yaml-tasks.png and b/docs/repos/security/media/code-scanning-config-yaml-tasks.png differ diff --git a/docs/repos/security/media/code-scanning-config-yaml-variable.png b/docs/repos/security/media/code-scanning-config-yaml-variable.png deleted file mode 100644 index a386915bbfa..00000000000 Binary files a/docs/repos/security/media/code-scanning-config-yaml-variable.png and /dev/null differ diff --git a/docs/repos/security/media/code-scanning-detail.png b/docs/repos/security/media/code-scanning-detail.png index 03871547973..8bb10d3c8fa 100644 Binary files a/docs/repos/security/media/code-scanning-detail.png and b/docs/repos/security/media/code-scanning-detail.png differ diff --git a/docs/repos/security/media/code-scanning-dismiss-alert.png b/docs/repos/security/media/code-scanning-dismiss-alert.png index 932ee8f3d3f..71e9025b36e 100644 Binary files a/docs/repos/security/media/code-scanning-dismiss-alert.png and b/docs/repos/security/media/code-scanning-dismiss-alert.png differ diff --git a/docs/repos/security/media/dependency-scanning-config-classic.png b/docs/repos/security/media/dependency-scanning-config-classic.png index ed5232ec7c0..caf8df47a2e 100644 Binary files a/docs/repos/security/media/dependency-scanning-config-classic.png and b/docs/repos/security/media/dependency-scanning-config-classic.png differ diff --git a/docs/repos/security/media/dependency-scanning-config-yaml.png b/docs/repos/security/media/dependency-scanning-config-yaml.png index bbf713a4682..1de983d56af 100644 Binary files a/docs/repos/security/media/dependency-scanning-config-yaml.png and b/docs/repos/security/media/dependency-scanning-config-yaml.png differ diff --git a/docs/repos/security/media/enable-github-advanced-security-organization.png b/docs/repos/security/media/enable-github-advanced-security-organization.png new file mode 100644 index 00000000000..203b6600da7 Binary files /dev/null and b/docs/repos/security/media/enable-github-advanced-security-organization.png differ diff --git a/docs/repos/security/media/enable-github-advanced-security-project-committers.png b/docs/repos/security/media/enable-github-advanced-security-project-committers.png new file mode 100644 index 00000000000..6a2ed77e5a6 Binary files /dev/null and b/docs/repos/security/media/enable-github-advanced-security-project-committers.png differ diff --git a/docs/repos/security/media/enable-github-advanced-security-project.png b/docs/repos/security/media/enable-github-advanced-security-project.png new file mode 100644 index 00000000000..4ab0b50fa9b Binary files /dev/null and b/docs/repos/security/media/enable-github-advanced-security-project.png differ diff --git a/docs/repos/security/media/pats-api.png b/docs/repos/security/media/pats-api.png index 771d67bcbd5..61a8ff842e4 100644 Binary files a/docs/repos/security/media/pats-api.png and b/docs/repos/security/media/pats-api.png differ diff --git a/docs/repos/security/media/pull-request-annotation-code-scanning-closed.png b/docs/repos/security/media/pull-request-annotation-code-scanning-closed.png new file mode 100644 index 00000000000..dd43746418a Binary files /dev/null and b/docs/repos/security/media/pull-request-annotation-code-scanning-closed.png differ diff --git a/docs/repos/security/media/pull-request-annotation-code-scanning.png b/docs/repos/security/media/pull-request-annotation-code-scanning.png new file mode 100644 index 00000000000..83a92295cc1 Binary files /dev/null and b/docs/repos/security/media/pull-request-annotation-code-scanning.png differ diff --git a/docs/repos/security/media/pull-request-annotation-dependency-scanning-closed.png b/docs/repos/security/media/pull-request-annotation-dependency-scanning-closed.png new file mode 100644 index 00000000000..de424dbefcd Binary files /dev/null and b/docs/repos/security/media/pull-request-annotation-dependency-scanning-closed.png differ diff --git a/docs/repos/security/media/pull-request-annotation-dependency-scanning.png b/docs/repos/security/media/pull-request-annotation-dependency-scanning.png new file mode 100644 index 00000000000..4bb39e041c9 Binary files /dev/null and b/docs/repos/security/media/pull-request-annotation-dependency-scanning.png differ diff --git a/docs/repos/security/media/secret-scanning-alerts.png b/docs/repos/security/media/secret-scanning-alerts.png index c4cc454cdd4..b6821401295 100644 Binary files a/docs/repos/security/media/secret-scanning-alerts.png and b/docs/repos/security/media/secret-scanning-alerts.png differ diff --git a/docs/repos/security/media/secret-scanning-close-alert.png b/docs/repos/security/media/secret-scanning-close-alert.png index ca858efee67..8acf7b078bd 100644 Binary files a/docs/repos/security/media/secret-scanning-close-alert.png and b/docs/repos/security/media/secret-scanning-close-alert.png differ diff --git a/docs/repos/security/media/secret-scanning-confidence-filter.png b/docs/repos/security/media/secret-scanning-confidence-filter.png new file mode 100644 index 00000000000..4f5f3d79ec1 Binary files /dev/null and b/docs/repos/security/media/secret-scanning-confidence-filter.png differ diff --git a/docs/repos/security/media/secret-scanning-detail-confidence-other.png b/docs/repos/security/media/secret-scanning-detail-confidence-other.png new file mode 100644 index 00000000000..b9622190c31 Binary files /dev/null and b/docs/repos/security/media/secret-scanning-detail-confidence-other.png differ diff --git a/docs/repos/security/media/secret-scanning-detail.png b/docs/repos/security/media/secret-scanning-detail.png index cd8f6e3d1b1..7ff7637a4aa 100644 Binary files a/docs/repos/security/media/secret-scanning-detail.png and b/docs/repos/security/media/secret-scanning-detail.png differ diff --git a/docs/repos/security/media/secret-scanning-dismiss-alert.png b/docs/repos/security/media/secret-scanning-dismiss-alert.png index 797c95bf3ee..e1653916137 100644 Binary files a/docs/repos/security/media/secret-scanning-dismiss-alert.png and b/docs/repos/security/media/secret-scanning-dismiss-alert.png differ diff --git a/docs/repos/security/media/security-overview-coverage.png b/docs/repos/security/media/security-overview-coverage.png new file mode 100644 index 00000000000..4e80c71bf44 Binary files /dev/null and b/docs/repos/security/media/security-overview-coverage.png differ diff --git a/docs/repos/security/media/security-overview-risk.png b/docs/repos/security/media/security-overview-risk.png new file mode 100644 index 00000000000..64c2b36571c Binary files /dev/null and b/docs/repos/security/media/security-overview-risk.png differ diff --git a/docs/repos/security/media/yaml-pipeline-setup.png b/docs/repos/security/media/yaml-pipeline-setup.png index 6b75efa079f..e1953f8773e 100644 Binary files a/docs/repos/security/media/yaml-pipeline-setup.png and b/docs/repos/security/media/yaml-pipeline-setup.png differ diff --git a/docs/repos/tfvc/add-command.md b/docs/repos/tfvc/add-command.md index 207fa88f9aa..e4cd23d36a3 100644 --- a/docs/repos/tfvc/add-command.md +++ b/docs/repos/tfvc/add-command.md @@ -21,8 +21,7 @@ The Team Foundation Version Control `add` command adds files and folders to a TF ## Prerequisites - [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). - -- The TFVC workspace set up on the dev machine. See [Workspace command](workspace-command.md) or [Set up Team Foundation Version Control on your dev machine](set-up-team-foundation-version-control-your-dev-machine.md). +- TFVC workspace set up on the dev machine. See [Workspace command](workspace-command.md) or [Set up Team Foundation Version Control on your dev machine](set-up-team-foundation-version-control-your-dev-machine.md). ## Syntax diff --git a/docs/repos/tfvc/add-files-server.md b/docs/repos/tfvc/add-files-server.md index 5a610516a88..d0bdfa9c01b 100644 --- a/docs/repos/tfvc/add-files-server.md +++ b/docs/repos/tfvc/add-files-server.md @@ -4,7 +4,7 @@ titleSuffix: Azure Repos description: See how to use Visual Studio to add files to Team Foundation Version Control. ms.assetid: 9b457eb0-9cdf-438d-935d-ceac7ce2201a ms.service: azure-devops-repos -ms.topic: conceptual +ms.topic: how-to ms.date: 10/06/2022 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-tfvc @@ -17,9 +17,9 @@ ms.subservice: azure-devops-repos-tfvc Adding files to version control is often automatic when you use Visual Studio **Solution Explorer** and your project is under version control. However, in some cases, you have to take extra steps to add files and projects to version control. -## Prerequisite +## Prerequisites -Before you can add files to version control in Visual Studio, [set up the workspace on your dev machine](set-up-team-foundation-version-control-your-dev-machine.md). +[!INCLUDE [contributor-only-prerequisites](includes/contributor-only-prerequisites.md)] > [!IMPORTANT] > These procedures apply only when you use a [local workspace](decide-between-using-local-server-workspace.md). When you use a local workspace, new files are automatically detected as pending changes. Conversely, files you save in a server workspace add and check in without showing as pending changes. diff --git a/docs/repos/tfvc/associate-file-type-file-comparison-tool.md b/docs/repos/tfvc/associate-file-type-file-comparison-tool.md index 3dc535c4ece..52b7bef9786 100644 --- a/docs/repos/tfvc/associate-file-type-file-comparison-tool.md +++ b/docs/repos/tfvc/associate-file-type-file-comparison-tool.md @@ -20,7 +20,11 @@ You can compare text files by using the [Diff window](compare-files.md), the def ## Prerequisites -You must be a member of the **Administrators** or **Users** security group on the computer where Visual Studio is installed. For more information, see [Permissions and groups reference](../../organizations/security/permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|Member of the **Administrators** or **Users** security group on the computer where Visual Studio is installed. | + +For more information, see [Permissions and groups reference](../../organizations/security/permissions.md). ## Associate a file type with a file-comparison tool diff --git a/docs/repos/tfvc/associate-file-type-merge-tool.md b/docs/repos/tfvc/associate-file-type-merge-tool.md index 52165ed8cfc..15c7325227f 100644 --- a/docs/repos/tfvc/associate-file-type-merge-tool.md +++ b/docs/repos/tfvc/associate-file-type-merge-tool.md @@ -22,7 +22,11 @@ The tool is compatible with text and XML based files, but to associate a specifi ## Prerequisites -You must be a member of the **Administrators** or **Users** security group on the computer where Visual Studio is installed. For more information, see [Permissions and groups reference](../../organizations/security/permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the **Administrators** or **Users** security group on the computer where Visual Studio is installed. | + +For more information, see [Permissions and groups reference](../../organizations/security/permissions.md). ## Associate a file type with a merge tool diff --git a/docs/repos/tfvc/branch-command.md b/docs/repos/tfvc/branch-command.md index 1af55221f6a..c258666f8b0 100644 --- a/docs/repos/tfvc/branch-command.md +++ b/docs/repos/tfvc/branch-command.md @@ -25,7 +25,11 @@ The TFVC `branch` command copies an item or set of items, including metadata and ## Prerequisites -To use the `branch` command, you must have the **Read** permission for the source item, and the **Check out** and **Merge** permissions for the target folder set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission for the source item and **Check out** and **Merge** permissions for the target folder set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/branch-folders-files.md b/docs/repos/tfvc/branch-folders-files.md index ac8dcfb3550..474b04e49ea 100644 --- a/docs/repos/tfvc/branch-folders-files.md +++ b/docs/repos/tfvc/branch-folders-files.md @@ -38,9 +38,9 @@ You can perform a branching operation by using either Visual Studio **Source Con ## Prerequisites -- To convert a folder to a branch, your **Manage branch** permission must be set to **Allow**. -- To branch a branch, your **Manage branch** permission must be set to **Allow** for the paths to the source and target branches. Your **Merge** permission for the path of target branch must set to **Allow**. -- To branch a folder or file, your **Check out** permission and your **Merge** permission for the target path must be set to **Allow**. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To convert a folder to a branch: **Manage branch** permission set to **Allow**.
      - To branch a branch: **Manage branch** permission set to **Allow** for the paths to the source and target branches.
      - **Merge** permission for the path of target branch set to **Allow**.
      - To branch a folder or file: **Check out** permission and **Merge** permission for the target path set to **Allow**.| For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). diff --git a/docs/repos/tfvc/branches-command.md b/docs/repos/tfvc/branches-command.md index 85f21260a6b..af65a44fa04 100644 --- a/docs/repos/tfvc/branches-command.md +++ b/docs/repos/tfvc/branches-command.md @@ -21,7 +21,11 @@ Displays the history of a branch for a specified file or folder. ## Prerequisites -To use the `branches` command, your **Read** permission must be set to **Allow** for the item and any branches to view their history. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission set to **Allow** for the item and any branches to view their history. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/changeset-command.md b/docs/repos/tfvc/changeset-command.md index 316d6493ed3..e8e1a92a3bd 100644 --- a/docs/repos/tfvc/changeset-command.md +++ b/docs/repos/tfvc/changeset-command.md @@ -21,7 +21,9 @@ Displays information about and lets you change the attributes, such as comments ## Prerequisites -To use the `changeset` command, you must have the **Read** permission set to **Allow** for any files or folders in the changeset for which you wish to display full information. The only users who can modify the notes and comments that are associated with a changeset are the users who created the changeset or a user who has the **Revise other user's changes** global permission. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission set to **Allow** for any files or folders in the changeset for which you wish to display full information. The only users who can modify the notes and comments that are associated with a changeset are the users who created the changeset or a user who has the **Revise other user's changes** global permission set to **Allow**. | For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). diff --git a/docs/repos/tfvc/check-folder-controlled-by-gated-check-build-process.md b/docs/repos/tfvc/check-folder-controlled-by-gated-check-build-process.md index f33906e4e5c..b20990e3f70 100644 --- a/docs/repos/tfvc/check-folder-controlled-by-gated-check-build-process.md +++ b/docs/repos/tfvc/check-folder-controlled-by-gated-check-build-process.md @@ -23,7 +23,7 @@ When you check in files to a version control folder that's controlled by a [gate ## Prerequisites -- You must be a **Contributor** for your project. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +- Be a **Contributor** for your project. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). - You can't have [Limit job authorization scope to current project for non-release pipelines](../../pipelines/process/access-tokens.md#job-authorization-scope) set. If you receive an error such as **The shelveset _Build_95;Build\\6bc8a077-3f27-4936-82e6-415fbd53ba07 could not be found for check-in**, check this setting and make sure it's not enabled. diff --git a/docs/repos/tfvc/check-out-edit-files.md b/docs/repos/tfvc/check-out-edit-files.md index 7d18b15a638..13ce6fd52ed 100644 --- a/docs/repos/tfvc/check-out-edit-files.md +++ b/docs/repos/tfvc/check-out-edit-files.md @@ -25,7 +25,11 @@ In rare situations, for example if you want to check out and lock the file to ma ## Prerequisites -You must be one of the **Contributors** for your project. To learn more, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Contributor** for your project. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Check out items manually diff --git a/docs/repos/tfvc/check-your-work-team-codebase.md b/docs/repos/tfvc/check-your-work-team-codebase.md index 643bd0934e7..8c4bab31e17 100644 --- a/docs/repos/tfvc/check-your-work-team-codebase.md +++ b/docs/repos/tfvc/check-your-work-team-codebase.md @@ -42,7 +42,7 @@ If you don't see pending changes for an item you want to check in, make sure tha When you check in changes, you should associate work items with the changes. This practice offers the following benefits: -- A team member who looks at the work item can [link directly to the changeset](../../boards/queries/link-work-items-support-traceability.md) to see the work that you did. +- A team member who looks at the work item can [link directly to the changeset](../../boards/backlogs/add-link.md) to see the work that you did. - A team member who [reviews the history of a file](view-manage-past-versions.md) you changed can view the changeset and see the work items that were the justification for the change. - You might build your changes in your automated build system, for example with a [CI Build](../../pipelines/build/triggers.md), or a [Gated Check-in Build](../../pipelines/repos/index.md). Your team members can see in which completed build the task was completed or the bug was fixed. @@ -109,7 +109,7 @@ If you want to be notified when someone checks in code in your TFVC project, you - Changes are checked in atomically. The operation either succeeds completely or fails completely. If any one of the changes can't be submitted, none of the changes are committed and a changeset isn't created. For example, if you lose network connectivity in the middle of a check-in operation, the whole operation fails. - There is one exception, which is the association of work items with the changeset. If work item association fails but all other aspects of the check-in operation succeed, then the changeset is created. You can manually associate a work item with a changeset. See [Manage dependencies, link work items to support traceability](../../boards/queries/link-work-items-support-traceability.md). + There is one exception, which is the association of work items with the changeset. If work item association fails but all other aspects of the check-in operation succeed, then the changeset is created. You can [manually associate a work item with a changeset](../../boards/backlogs/add-link.md). ## Next steps diff --git a/docs/repos/tfvc/clean-up-files-when-users-leave.md b/docs/repos/tfvc/clean-up-files-when-users-leave.md index 0c1dfdce04c..53ab20985d3 100644 --- a/docs/repos/tfvc/clean-up-files-when-users-leave.md +++ b/docs/repos/tfvc/clean-up-files-when-users-leave.md @@ -19,7 +19,11 @@ When a member leaves a team, version control administrators must correctly dispo ## Prerequisites -To perform these procedures, you must be a member of the **Azure DevOps Administrators** or **Team Foundation Administrators** security group. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|Member of the **Azure DevOps Administrators** or **Team Foundation Administrators** security group. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Clean up version-controlled files after a team member leaves @@ -34,4 +38,4 @@ To perform these procedures, you must be a member of the **Azure DevOps Administ ## Related articles -- [Remove user accounts](../../organizations/security/remove-users-prohibit-access.md) \ No newline at end of file +- [Remove user accounts](/azure/active-directory/add-users-azure-active-directory#delete-a-user?toc=/azure/devops/organizations/security/toc.json) diff --git a/docs/repos/tfvc/compare-files.md b/docs/repos/tfvc/compare-files.md index 11ca61ebe33..bebdcdbc4d6 100644 --- a/docs/repos/tfvc/compare-files.md +++ b/docs/repos/tfvc/compare-files.md @@ -16,7 +16,7 @@ ms.subservice: azure-devops-repos-tfvc [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-eq-2019](../../includes/version-vs-gt-eq-2019.md)] -This article provides a guide for comparing files when using Team Foundation Version Control (TFVC). If you're using Git for version control, see [Compare files](../../repos/git/review-history.md#compare-files). +This article provides a guide for comparing files when using Team Foundation Version Control (TFVC). If you're using Git for version control, see [Compare files](../../repos/git/review-history.md#compare-file-versions). You can compare server folders and local folders to each other, and view the differences between the contents of each folder. You can compare two server files, two local files, or a server file against a local file, and view the differences between the files. diff --git a/docs/repos/tfvc/compare-folders.md b/docs/repos/tfvc/compare-folders.md index c4a8c06e60e..c402a9011d0 100644 --- a/docs/repos/tfvc/compare-folders.md +++ b/docs/repos/tfvc/compare-folders.md @@ -20,7 +20,11 @@ You can compare the differences between two server folders, two local folders, o ## Prerequisites -To do these procedures, you must have the **Read** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| **Read** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). > [!NOTE] > To compare two local folders, you don't need any Azure DevOps permissions. diff --git a/docs/repos/tfvc/comparison-git-tfvc.md b/docs/repos/tfvc/comparison-git-tfvc.md index 6c46a264745..dcf3c6d3ef0 100644 --- a/docs/repos/tfvc/comparison-git-tfvc.md +++ b/docs/repos/tfvc/comparison-git-tfvc.md @@ -35,7 +35,7 @@ Git is a distributed version control system. Each developer has a copy of the so >[!NOTE] >Git in Visual Studio, Azure DevOps Services, and Azure DevOps Server is standard Git. You can use Visual Studio with third-party Git services, and you can also use third-party Git clients with Azure DevOps Server. -To learn more, see [Git and Azure Repos](../../repos/git/index.yml). +For more information, see [Git and Azure Repos](../../repos/git/index.yml). ### TFVC (centralized) @@ -47,7 +47,7 @@ TFVC has two [workflow models](decide-between-using-local-server-workspace.md): - **Local workspaces** - Each team member takes a copy of the latest version of the codebase with them and works offline as needed. Developers check in their changes and resolve conflicts as necessary. Another system that works this way is Subversion. -To learn more, see [What is Team Foundation Version Control?](./what-is-tfvc.md) +For more information, see [What is Team Foundation Version Control?](./what-is-tfvc.md) @@ -170,7 +170,7 @@ The following table provides a summary of how TFVC and Git support the main capa Scale :::column-end::: :::column span="2"::: - You can work on small or very large scale projects using [local workspaces](decide-between-using-local-server-workspace.md#local). Support massive scale (millions of files per branch and large binary files) projects using [server workspaces](decide-between-using-local-server-workspace.md#when-might-i-need-to-use-a-server-workspace). + You can work on small or very large scale projects using [local workspaces](decide-between-using-local-server-workspace.md#use-a-local-workspace). Support massive scale (millions of files per branch and large binary files) projects using [server workspaces](decide-between-using-local-server-workspace.md#use-a-server-workspace). :::column-end::: :::column span="2"::: You can quickly begin small projects. You can scale up to very large projects, but you have to plan ahead to modularize your codebase. You can create multiple repositories in a project. @@ -323,7 +323,7 @@ The following table summarizes the client supported features available depending Manage work on your dev machine :::column-end::: :::column span="2"::: - [Pending Changes](develop-code-manage-pending-changes.md#use-the-pending-changes-page-to-manage-your-work) and [My Work](develop-code-manage-pending-changes.md#use-the-my-work-page-to-manage-your-work) pages in Visual Studio **Team Explorer**. + [Pending Changes](develop-code-manage-pending-changes.md#use-the-pending-changes-page-to-manage-work) and [My Work](develop-code-manage-pending-changes.md#use-the-my-work-page-to-manage-work) pages in Visual Studio **Team Explorer**. :::column-end::: :::column span="2"::: Changes, commits, and branches pages. diff --git a/docs/repos/tfvc/configure-check-notes.md b/docs/repos/tfvc/configure-check-notes.md index d6426752363..e5fa39867d4 100644 --- a/docs/repos/tfvc/configure-check-notes.md +++ b/docs/repos/tfvc/configure-check-notes.md @@ -20,7 +20,11 @@ Team Foundation Version Control administrators can add, configure, and remove ch ## Prerequisites -You must have the **Edit project-level information** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Edit project-level information** permission set to **Allow**.| + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ### To add check-in notes diff --git a/docs/repos/tfvc/configure-check-out-settings.md b/docs/repos/tfvc/configure-check-out-settings.md index eaceb2455b9..073561b1a87 100644 --- a/docs/repos/tfvc/configure-check-out-settings.md +++ b/docs/repos/tfvc/configure-check-out-settings.md @@ -20,7 +20,11 @@ Team Foundation Version Control (TFVC) administrators can configure source contr ## Prerequisites -To configure check-out settings, you must have the **Edit project-level information** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Edit project-level information** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ### Configure checkout settings diff --git a/docs/repos/tfvc/configure-command.md b/docs/repos/tfvc/configure-command.md index be3d6f73029..5bd8602f8d0 100644 --- a/docs/repos/tfvc/configure-command.md +++ b/docs/repos/tfvc/configure-command.md @@ -25,7 +25,11 @@ Enables an administrator to view and change the following configuration settings ## Prerequisites -To use the `configure` command, you must have the **Edit server-level information** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Edit server-level information** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/control-access-team-foundation-version-control.md b/docs/repos/tfvc/control-access-team-foundation-version-control.md index d4cc3bca99d..0ecf46cc333 100644 --- a/docs/repos/tfvc/control-access-team-foundation-version-control.md +++ b/docs/repos/tfvc/control-access-team-foundation-version-control.md @@ -23,7 +23,11 @@ Permission settings are in the form of either **Allow** or **Deny**. **Deny** al ## Prerequisites -To complete this task, you must have your **Manage permissions** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Manage permissions** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ### To set permissions for users or groups diff --git a/docs/repos/tfvc/decide-between-using-local-server-workspace.md b/docs/repos/tfvc/decide-between-using-local-server-workspace.md index 412997d9899..ee2e29d8b03 100644 --- a/docs/repos/tfvc/decide-between-using-local-server-workspace.md +++ b/docs/repos/tfvc/decide-between-using-local-server-workspace.md @@ -66,7 +66,7 @@ Visual Studio doesn't put a solution back online automatically. You must do that The changes that you made offline are added to TFVC as pending changes. - + ## Manage project collection workspace settings for your team diff --git a/docs/repos/tfvc/delete-command-team-foundation-version-control.md b/docs/repos/tfvc/delete-command-team-foundation-version-control.md index ee956894103..92657ac4a4e 100644 --- a/docs/repos/tfvc/delete-command-team-foundation-version-control.md +++ b/docs/repos/tfvc/delete-command-team-foundation-version-control.md @@ -24,7 +24,11 @@ The `delete` command removes files and folders from the Azure DevOps server and ## Prerequisites -To use the `delete` command, you must have the **Check out** permission set to **Allow**. If you include the `/lock` option with a value other than `none`, you must have the **Lock** permission set to **Allow**. You must also own the workspace or have the global **Administer workspaces** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- **Check out** permission set to **Allow**.
      - If you include the `/lock` option with a value other than `none`: **Lock** permission set to **Allow**.
      - Owner of the workspace or **Administer workspaces** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax ``` diff --git a/docs/repos/tfvc/destroy-command-team-foundation-version-control.md b/docs/repos/tfvc/destroy-command-team-foundation-version-control.md index 93fe0b15704..f35a1ad4d2d 100644 --- a/docs/repos/tfvc/destroy-command-team-foundation-version-control.md +++ b/docs/repos/tfvc/destroy-command-team-foundation-version-control.md @@ -17,6 +17,8 @@ ms.subservice: azure-devops-repos-tfvc [!INCLUDE [version-vs-gt-eq-2019](../../includes/version-vs-gt-eq-2019.md)] Use the `tf destroy` command to destroy, or permanently delete, version-controlled files from Team Foundation Version Control (TFVC). +> [!NOTE] +> Deleting a TFVC repository inside Azure Devops is not allowed once it has been created. The command `tf destroy` will only destroy, or permanently delete, version-controlled files or folders but will not delete the TFVC repository. It will still appear in the list of options with the message deleted. Sometimes you have to clean up version control systems. For example, if some files are infected with a computer virus, you have to remove them permanently from version control. Don't destroy files that are still needed. The destroy action can't be reversed. @@ -26,7 +28,11 @@ After you delete the files, you can synchronize the TFVC warehouse. Otherwise, t ## Prerequisites -To use the `destroy` command, you must belong to the **Team Foundation Administrators** security group. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|Member of the **Team Foundation Administrators** security group. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax ``` diff --git a/docs/repos/tfvc/destroy-version-controlled-files.md b/docs/repos/tfvc/destroy-version-controlled-files.md index b0ad6b3feb0..1356d212bee 100644 --- a/docs/repos/tfvc/destroy-version-controlled-files.md +++ b/docs/repos/tfvc/destroy-version-controlled-files.md @@ -25,11 +25,10 @@ The following procedure shows you how to destroy files and folders by using the ## Prerequisites -- To use the `destroy` command, you must be a member of the **Team Foundation Administrators** security group. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). - -- Before you run `tf destroy` without the `/keephistory` option, first delete the files you want to destroy. For more information, see [Delete files and folders from version control](delete-restore-files-folders.md). After you delete a file, its file name now includes a deletion ID. For example, if a file name is *aFile.cs*, after deletion the file name is *aFile.cs;x123*, where x123 is the deletion ID. - - After you delete the files, you can synchronize the TFVC warehouse. Otherwise the warehouse won't be synchronized with the destroyed items. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To use the `destroy` command: Member of the **Team Foundation Administrators** security group. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md).| +|**Tasks** |- Before you run `tf destroy` without the `/keephistory` option, first delete the files you want to destroy. For more information, see [Delete files and folders from version control](delete-restore-files-folders.md).
      - After you delete a file, its file name includes a deletion ID. For example, if a file name is *aFile.cs*, after deletion the file name is *aFile.cs;x123*, where x123 is the deletion ID.
      - After you delete the files, you can synchronize the TFVC warehouse. Otherwise the warehouse won't synchronize with the destroyed items.| ### To permanently destroy version-controlled files diff --git a/docs/repos/tfvc/develop-code-manage-pending-changes.md b/docs/repos/tfvc/develop-code-manage-pending-changes.md index 8ecbe1f8713..837c0189adf 100644 --- a/docs/repos/tfvc/develop-code-manage-pending-changes.md +++ b/docs/repos/tfvc/develop-code-manage-pending-changes.md @@ -50,7 +50,7 @@ You can open the **My Work** page in **Team Explorer** or press Ctrl+0, M to man You can use **My Work** to: - Assign work to yourself. -- Track your work against [work items](../../boards/queries/link-work-items-support-traceability.md). +- Track your work against [work items](../../boards/backlogs/add-link.md). - Suspend and later resume your work, including file changes, associated work items, and Visual Studio state such as window positions and breakpoints. - Request a code review. @@ -102,7 +102,7 @@ To exclude changes, see [Choose the files you want to check in](check-your-work- ### Associate work items -It's a best practice to associate [work items](../../boards/queries/link-work-items-support-traceability.md), such as tasks or bugs, with your changes. Under **Related Work Items**, drag work items from a [query](../../boards/queries/using-queries.md) or add a work item by ID. +It's a best practice to associate [work items](../../boards/backlogs/add-link.md), such as tasks or bugs, with your changes. Under **Related Work Items**, drag work items from a [query](../../boards/queries/using-queries.md) or add a work item by ID. ## See what you changed diff --git a/docs/repos/tfvc/difference-command.md b/docs/repos/tfvc/difference-command.md index ef22a01e8bb..e445a9807da 100644 --- a/docs/repos/tfvc/difference-command.md +++ b/docs/repos/tfvc/difference-command.md @@ -20,7 +20,11 @@ The Team Foundation Version Control (TFVC) `difference` command compares, and if ## Prerequisites -To use the `difference` command, you must have the **Read** permission for all specified items set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission for all specified items set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/dir-command.md b/docs/repos/tfvc/dir-command.md index 7947714d639..dd6cced4d0e 100644 --- a/docs/repos/tfvc/dir-command.md +++ b/docs/repos/tfvc/dir-command.md @@ -19,7 +19,11 @@ The `dir` command displays all or some of the contents of the server for Team Fo ## Prerequisites -To use the `dir` command, you must have **Read** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/download-get-files-from-server.md b/docs/repos/tfvc/download-get-files-from-server.md index f25f1d9c00a..07046f7571f 100644 --- a/docs/repos/tfvc/download-get-files-from-server.md +++ b/docs/repos/tfvc/download-get-files-from-server.md @@ -20,7 +20,7 @@ In general, you should get the latest files from the server on a regular basis s ## Prerequisites -You must be one of the **Contributors** for your project. To learn more, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +[!INCLUDE [contributor-only-prerequisites](includes/contributor-only-prerequisites.md)] ## Get the latest version of files diff --git a/docs/repos/tfvc/edit-check-policies.md b/docs/repos/tfvc/edit-check-policies.md index 25d95b5db37..837f02ecd22 100644 --- a/docs/repos/tfvc/edit-check-policies.md +++ b/docs/repos/tfvc/edit-check-policies.md @@ -33,7 +33,11 @@ Before editing a check-in policy, you must first create one. For more informatio ## Prerequisites -To complete this procedure, you must have the **Edit project-level information** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Edit project-level information** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Edit a check-in policy diff --git a/docs/repos/tfvc/effective-feature-isolation-on-tfvc.md b/docs/repos/tfvc/effective-feature-isolation-on-tfvc.md index 068971580bc..5b571fdbff4 100644 --- a/docs/repos/tfvc/effective-feature-isolation-on-tfvc.md +++ b/docs/repos/tfvc/effective-feature-isolation-on-tfvc.md @@ -104,7 +104,7 @@ Or, toggle the **Show/Hide Deleted Items** icon in the **Source Control Explorer ![Screenshot showing the Show/Hide Deleted Items icon in the Source Control Explorer menu bar.](./media/effective-feature-isolation-on-tfvc/show-hide.png) -If needed, you can also [restore](delete-restore-files-folders.md#restore-items-deleted-from-visual-studio) deleted branches and associated items. +If needed, you can also [restore](delete-restore-files-folders.md#recover-or-restore-deleted-items) deleted branches and associated items. ![Screenshot that shows deleted feature branches and their changesets.](./media/effective-feature-isolation-on-tfvc/feature-isolation-delete-branches-show.png) @@ -121,7 +121,6 @@ Now that you're using feature isolation, you should explore continuous integrati ## Related resources * [Branching strategies with TFVC](./effective-tfvc-branching-strategies-for-devops.md) -* [Classic branching and merging guidance (PDF)](https://vsardata.blob.core.windows.net/projects/TFS%20Version%20Control%20Part%201%20-%20Branching%20Strategies.pdf) * [Continuous integration](/devops/develop/what-is-continuous-integration) * [Feature toggles](/archive/msdn-magazine/2014/may/alm-rangers-software-development-with-feature-toggles) * [Team Foundation Version Control (TFVC)](./what-is-tfvc.md) diff --git a/docs/repos/tfvc/enable-disable-check-policies.md b/docs/repos/tfvc/enable-disable-check-policies.md index 1279a6b0829..8d938fc2db6 100644 --- a/docs/repos/tfvc/enable-disable-check-policies.md +++ b/docs/repos/tfvc/enable-disable-check-policies.md @@ -22,7 +22,11 @@ Prior to enabling or disabling check-in policies, you must first create the chec ## Prerequisites -To complete this procedure, you must have the **Edit project-level information** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Edit project-level information** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Enable or disable a check-in policy diff --git a/docs/repos/tfvc/find-view-changesets.md b/docs/repos/tfvc/find-view-changesets.md index e43abb4f31a..add8a295ab6 100644 --- a/docs/repos/tfvc/find-view-changesets.md +++ b/docs/repos/tfvc/find-view-changesets.md @@ -23,7 +23,7 @@ You can view a changeset to see what the exact file changes were, discover the o ## Prerequisites -You must be one of the **Contributors** for your project. To learn more, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +[!INCLUDE [contributor-only-prerequisites](includes/contributor-only-prerequisites.md)] ## Find a changeset by ID @@ -106,4 +106,4 @@ To find a changeset from the [command prompt](use-team-foundation-version-contro - To download the version of a file in a changeset, see [Download (get) files from the server](download-get-files-from-server.md). -- To add a link between a changeset and one or more work items, see [Use links to view dependencies and track related work](../../boards/queries/link-work-items-support-traceability.md). +- [Link work items to other objects](../../boards/backlogs/add-link.md). diff --git a/docs/repos/tfvc/folderdiff-command.md b/docs/repos/tfvc/folderdiff-command.md index 878bbe6885d..c2a57c61819 100644 --- a/docs/repos/tfvc/folderdiff-command.md +++ b/docs/repos/tfvc/folderdiff-command.md @@ -21,7 +21,11 @@ Use the TFVC `folderdiff` command to display and compare a visual representation ## Prerequisites -To use the `folderdiff` command, you must have the **Read** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/get-history-item.md b/docs/repos/tfvc/get-history-item.md index e770b67bfbd..9c66fc7739a 100644 --- a/docs/repos/tfvc/get-history-item.md +++ b/docs/repos/tfvc/get-history-item.md @@ -34,7 +34,7 @@ Use the Visual Studio **History** window to get detailed historical data about a ## Prerequisites -You must be one of the **Contributors** for your project. To learn more, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +[!INCLUDE [contributor-only-prerequisites](includes/contributor-only-prerequisites.md)] ## Open the History window @@ -51,7 +51,7 @@ The **History** window displays the historical data about the item in two tabs: - The [Labels tab](get-history-item.md#labels_tab) lists every label that has been applied to the item. - + ## Changesets tab @@ -185,7 +185,7 @@ By using the **Changesets** tab, you can do the following tasks: :::column-end::: :::row-end::: - + ## Labels tab diff --git a/docs/repos/tfvc/git-permission-command.md b/docs/repos/tfvc/git-permission-command.md index 090551f2faf..7dc440fa889 100644 --- a/docs/repos/tfvc/git-permission-command.md +++ b/docs/repos/tfvc/git-permission-command.md @@ -19,9 +19,9 @@ The `tf git permission` command modifies the user access control list (ACL) and ## Prerequisites -- To view permissions, you must be able to view the artifact for the type of information you're requesting: **View collection-level information** for project collections, **View project-level information** for projects, and **Read** for repository and branch if you're viewing branch permissions. - -- To manage permissions, you must have **Manage permissions** for the desired artifact. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - To view project collection permissions: **View collection-level information** permissions set to **Allow**.
      - To view project permissions: **View project-level information** set to **Allow**.
      - To view repository and branch permissions: **Read** permissions set to **Allow**.
      - To manage permissions: **Manage permissions** for the desired artifact set to **Allow**.| For more information, see [Default Git permissions](../../organizations/security/default-git-permissions.md). @@ -46,7 +46,7 @@ tf git permission [/allow:(* |perm1[,perm2,...]] |---------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `/allow:(* |[,,...])` | The permissions to allow. | | `/deny:(* |[,,...])` | The permissions to deny. | -| `/remove:(* |[,,...])` | The permissions to remove, sometimes referred to as not set. You can use all three of `/allow`, `/deny`, and `/remove` in the same invocation. For more information on how the allow, deny, and remove settings interact, see [Permission settings](../../organizations/security/about-permissions.md#permission-settings). | +| `/remove:(* |[,,...])` | The permissions to remove, sometimes referred to as not set. You can use all three of `/allow`, `/deny`, and `/remove` in the same invocation. For more information on how the allow, deny, and remove settings interact, see [Permission settings](../../organizations/security/about-permissions.md#permission-states). | | `/user:[,,...]` | The user or users for which to allow, deny, or remove permissions. You must specify at least one user or group. | | `/group:[,,...]` | The groups or groups for which to allow, deny, or remove permissions. You must specify at least one user or group. Groups and individuals can be used together. | | `/collection:` | Specifies the URL of the project collection that contains the permissions to view or modify. For example: `http://myserver:8080/tfs/DefaultCollection` or `https://fabrikam-fiber.visualstudio.com`. This parameter is required. | diff --git a/docs/repos/tfvc/git-view-command.md b/docs/repos/tfvc/git-view-command.md index a2d8446cb90..b468bcc4bfe 100644 --- a/docs/repos/tfvc/git-view-command.md +++ b/docs/repos/tfvc/git-view-command.md @@ -22,7 +22,7 @@ The `tf git view` command retrieves a file from a Git repository to a temporary - For requirements, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). -- You must be able to view the artifact for the type of information you are requesting: **View collection-level information** for project collections, **View project-level information** for projects, and **Read** for repository and branch if you're viewing branch information. For more information, see [Default Git permissions](../../organizations/security/default-git-permissions.md). +- Be able to view the artifact for the type of information you are requesting: **View collection-level information** for project collections, **View project-level information** for projects, and **Read** for repository and branch if you're viewing branch information. For more information, see [Default Git permissions](../../organizations/security/default-git-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/help-command-team-foundation-version-control.md b/docs/repos/tfvc/help-command-team-foundation-version-control.md index aa543e43662..4f92542566f 100644 --- a/docs/repos/tfvc/help-command-team-foundation-version-control.md +++ b/docs/repos/tfvc/help-command-team-foundation-version-control.md @@ -20,7 +20,7 @@ The `tf help` command displays information about syntax for `tf` command-line ut ## Prerequisites -- [Visual Studio](https://visualstudio.microsoft.com/downloads) installed on your local computer. +[Visual Studio](https://visualstudio.microsoft.com/downloads) installed on your local computer. ## Syntax diff --git a/docs/repos/tfvc/includes/contributor-only-prerequisites.md b/docs/repos/tfvc/includes/contributor-only-prerequisites.md new file mode 100644 index 00000000000..c2308a3e872 --- /dev/null +++ b/docs/repos/tfvc/includes/contributor-only-prerequisites.md @@ -0,0 +1,13 @@ +--- +ms.topic: include +ms.service: azure-devops-repos +ms.author: chcomley +author: chcomley +ms.date: 02/20/2025 +--- + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| Member of the **Contributors** group for your project. | + +For more information, see [Default TFVC permissions](../../../organizations/security/default-tfvc-permissions.md). diff --git a/docs/repos/tfvc/index.yml b/docs/repos/tfvc/index.yml index fc9db53fa18..c72f34f5d2e 100644 --- a/docs/repos/tfvc/index.yml +++ b/docs/repos/tfvc/index.yml @@ -45,6 +45,8 @@ landingContent: url: ./create-work-workspaces.md - text: Branch folders and files url: ./branch-folders-files.md + - text: Migration of custom check-in policies + url: ./tfvc-check-in-policy-migrate-guide.md - title: Reference linkLists: - linkListType: reference diff --git a/docs/repos/tfvc/label-command-team-foundation-version-control.md b/docs/repos/tfvc/label-command-team-foundation-version-control.md index b213a4c3449..458e9dc6168 100644 --- a/docs/repos/tfvc/label-command-team-foundation-version-control.md +++ b/docs/repos/tfvc/label-command-team-foundation-version-control.md @@ -20,7 +20,11 @@ The Team Foundation Version Control (TFVC) `tf label` command attaches a label t ## Prerequisites -To use the `label` command, you must have the **Label** permission set to **Allow**. To modify or delete labels created by other users, you must have the **Administer labels** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| **Label** permission set to **Allow**. To modify or delete labels created by other users, have the **Administer labels** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/labels-command.md b/docs/repos/tfvc/labels-command.md index 709cc1e6ad8..98d159e7fd8 100644 --- a/docs/repos/tfvc/labels-command.md +++ b/docs/repos/tfvc/labels-command.md @@ -20,7 +20,11 @@ The Team Foundation Version Control (TFVC) `tf labels` command displays the list ## Prerequisites -To use the `labels` command, you must have the **Read** permission set to **Allow** for all files or folders to which the specified label is attached. If you have permission to some, but not all the files referenced in the label, partial results are displayed. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| **Read** permission set to **Allow** for all files or folders to which the specified label is attached. If you have permission to some, but not all the files referenced in the label, only partial results display.| + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/localversions-command.md b/docs/repos/tfvc/localversions-command.md index 42574e7123a..33ded1da52b 100644 --- a/docs/repos/tfvc/localversions-command.md +++ b/docs/repos/tfvc/localversions-command.md @@ -20,7 +20,11 @@ The Team Foundation Version Control (TFVC) `localversions` command displays the ## Prerequisites -To use the `localversions` command, you must have the **Use** permission to the workspace. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Use** permission for the workspace set to **Allow**.| + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/lock-command.md b/docs/repos/tfvc/lock-command.md index d70b500daa2..96375edebc8 100644 --- a/docs/repos/tfvc/lock-command.md +++ b/docs/repos/tfvc/lock-command.md @@ -20,7 +20,11 @@ The Team Foundation Version Control (TFVC) `lock` command locks or unlocks a fil ## Prerequisites -To use the `lock` command, you must have the **Lock** permission set to **Allow**. You need the **Unlock other user's changes** permission set to **Allow** to remove a lock held by another user if you don't have **Write** permission for that user's workspace. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- **Lock** permission set to **Allow**.
      - **Unlock other user's changes** permission set to **Allow** if you don't have **Write** permission for a user's workspace that's locked. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/merge-command.md b/docs/repos/tfvc/merge-command.md index f0f497d7e95..60986fb6740 100644 --- a/docs/repos/tfvc/merge-command.md +++ b/docs/repos/tfvc/merge-command.md @@ -23,7 +23,11 @@ The `tf merge` command applies changes from one branch into another in Team Foun ## Prerequisites -To use the `merge` command, you must have the **Check out** permission set to **Allow** for the workspace folder that contains the `destination`, and you must have the **Read** permission set to **Allow** for the workspace folder that contains the `source`. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- **Check out** permission set to **Allow** for the workspace folder that contains the `destination`.
      - **Read** permission set to **Allow** for the workspace folder that contains the `source`. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/merge-folders-files.md b/docs/repos/tfvc/merge-folders-files.md index 6f0cad88c2a..2b1aa9b603b 100644 --- a/docs/repos/tfvc/merge-folders-files.md +++ b/docs/repos/tfvc/merge-folders-files.md @@ -22,12 +22,9 @@ The procedures in this article explain how you can use the Visual Studio graphic ## Prerequisites -To do these procedures, you must have the following permissions set: - -- You must have the **Read** permission for the item in the source tree and your **Check out** permission for the item in the target tree set to **Allow**. -- You must have the **Merge** permission set for the target path. -- If the item in the target tree is being renamed, you must have the **Check out** permission for both the source tree and the target tree set to **Allow**. -- If any files affected by the operation are locked, you must have the **Lock** permission set to **Allow**. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- **Read** permission for the item in the source tree and your **Check out** permission for the item in the target tree set to **Allow**.
      - **Merge** permission set for the target path.
      - If the item in the target tree is being renamed: **Check out** permission for both the source tree and the target tree set to **Allow**.
      - If any files affected by the operation are locked: **Lock** permission set to **Allow**.| For more information about permissions, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). diff --git a/docs/repos/tfvc/merges-command.md b/docs/repos/tfvc/merges-command.md index 19b3d72e84a..5a32882daf4 100644 --- a/docs/repos/tfvc/merges-command.md +++ b/docs/repos/tfvc/merges-command.md @@ -20,7 +20,11 @@ The `tf merges` command displays detailed information about past merges between ## Prerequisites -To use the `merges` command, you must have the **Read** permission set to **Allow** for both source and destination branches. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission set to **Allow** for both source and destination branches. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/permission-command.md b/docs/repos/tfvc/permission-command.md index 98a4108e7d5..80b76f63255 100644 --- a/docs/repos/tfvc/permission-command.md +++ b/docs/repos/tfvc/permission-command.md @@ -19,7 +19,10 @@ The `tf permission` command modifies the user access control list (ACL) and disp ## Prerequisites -To use the `permission` command, you must have the **Manipulate security settings** permission set to **Allow** for the folders being modified, be a member of the **Azure DevOps Administrators** security group, or be a system administrator on the local computer (Windows Administrator security group). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Manipulate security settings** permission set to **Allow** for the folders being modified, member of the **Azure DevOps Administrators** security group, or system administrator on the local computer (Windows Administrator security group). | + For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax @@ -240,7 +243,7 @@ The following example allows the `testers` group to change their local copies of c:\projects>tf permission /allow:PendChange /group:testers$/testproject ``` -The following example allows user `somealias` to make pending changes to their local copy of *$/testtproject/314.cs* in their workspace: +The following example allows user `somealias` to make pending changes to their local copy of *$/testproject/314.cs* in their workspace: ``` c:\projects>tf permission /allow:PendChange /user:somealias $/testproject/314.cs. diff --git a/docs/repos/tfvc/properties-or-info-command.md b/docs/repos/tfvc/properties-or-info-command.md index b19bdbdb2ac..2b32278e5cf 100644 --- a/docs/repos/tfvc/properties-or-info-command.md +++ b/docs/repos/tfvc/properties-or-info-command.md @@ -20,7 +20,11 @@ The `tf info` command displays information about items that are under Team Found ## Prerequisites -To use the `info` command, you must have the **Read** permission set to **Allow** for all specified files and folders. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission set to **Allow** for all specified files and folders.| + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/proxy-command.md b/docs/repos/tfvc/proxy-command.md index f5d41281b5e..dec79cf5293 100644 --- a/docs/repos/tfvc/proxy-command.md +++ b/docs/repos/tfvc/proxy-command.md @@ -19,7 +19,10 @@ The Team Foundation Version Control (TFVC) `tf proxy` command configures your cl ## Prerequisites -To use the `proxy` command to configure a client computer, you must be a member of the **User** security group on the local computer. To use the `proxy` command to work with proxy records, you must have the **AdminConfiguration** permission. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To use the `proxy` command to configure a client computer: Member of the **User** security group on the local computer.
      - To use the `proxy` command to work with proxy records: **AdminConfiguration** permission. | + For more information, see [Security namespace and permission reference](../../organizations/security/namespace-reference.md). ## Syntax diff --git a/docs/repos/tfvc/reconcile-differences-between-two-folders.md b/docs/repos/tfvc/reconcile-differences-between-two-folders.md index f05f0801177..f4446eb18c7 100644 --- a/docs/repos/tfvc/reconcile-differences-between-two-folders.md +++ b/docs/repos/tfvc/reconcile-differences-between-two-folders.md @@ -4,7 +4,7 @@ titleSuffix: Azure Repos description: Reconcile differences between two folders in Team Foundation Version Control (TFVC). ms.assetid: 8776e3dd-fc70-422c-a191-81b22a989403 ms.service: azure-devops-repos -ms.topic: conceptual +ms.topic: how-to ms.date: 11/29/2022 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-tfvc @@ -20,7 +20,11 @@ After you compare a server folder and a local folder in Team Foundation Version ## Prerequisites -To do these procedures, you must have the **Read** and **Check out** permissions set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** and **Check out** permissions set to **Allow**.| + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). > [!NOTE] > To reconcile two local folders or files, you don't need Azure DevOps permissions. diff --git a/docs/repos/tfvc/remove-access-version-control-files.md b/docs/repos/tfvc/remove-access-version-control-files.md index bea20b8bea3..baa7f669220 100644 --- a/docs/repos/tfvc/remove-access-version-control-files.md +++ b/docs/repos/tfvc/remove-access-version-control-files.md @@ -24,7 +24,11 @@ As a Team Foundation Version Control (TFVC) administrator, you might have to rem ## Prerequisites -To remove access to Team Foundation version control files, you must belong to the **Azure DevOps Administrators** group. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|Member of the **Azure DevOps Administrators** group. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Remove access to a file under version control @@ -89,7 +93,7 @@ The following procedures provide details for removing a file by using the Visual ``` tf permission /inherit:no myfile.cs - tf permission /deny:read myfile.cs /group:ADATAUM\Group1 ADATAUM\Group2 myfile.cs + tf permission /deny:read myfile.cs /group:ADATUM\Group1 ADATUM\Group2 myfile.cs ``` ## Related articles diff --git a/docs/repos/tfvc/remove-check-policies.md b/docs/repos/tfvc/remove-check-policies.md index 5fd98801990..4fd509fd857 100644 --- a/docs/repos/tfvc/remove-check-policies.md +++ b/docs/repos/tfvc/remove-check-policies.md @@ -4,7 +4,7 @@ titleSuffix: Azure Repos description: Remove check-in policies from your Team Foundation Version Control (TFVC) project. ms.assetid: fb4b62ef-e413-4f03-81fe-ae560c9f60ff ms.service: azure-devops-repos -ms.topic: conceptual +ms.topic: how-to ms.date: 11/29/2022 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-tfvc @@ -21,7 +21,11 @@ Team Foundation Version Control (TFVC) administrators can add check-in policies ## Prerequisites -To complete this procedure, you must have the **Edit project-level information** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Edit project-level information** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Remove a check-in policy diff --git a/docs/repos/tfvc/rename-command-team-foundation-version-control.md b/docs/repos/tfvc/rename-command-team-foundation-version-control.md index f61582de571..0ad424949aa 100644 --- a/docs/repos/tfvc/rename-command-team-foundation-version-control.md +++ b/docs/repos/tfvc/rename-command-team-foundation-version-control.md @@ -22,7 +22,11 @@ The Team Foundation Version Control (TFVC) `rename` command changes the name or ## Prerequisites -To use the `rename` command, you must have the **Check out** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Check out** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/rename-move-files-folders.md b/docs/repos/tfvc/rename-move-files-folders.md index f7c0199977f..234f780e088 100644 --- a/docs/repos/tfvc/rename-move-files-folders.md +++ b/docs/repos/tfvc/rename-move-files-folders.md @@ -27,7 +27,7 @@ You can also use the `tf` command-line utility to move or rename files or folder ## Prerequisites -You must be one of the **Contributors** for your project. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +[!INCLUDE [contributor-only-prerequisites](includes/contributor-only-prerequisites.md)] ## Move an item diff --git a/docs/repos/tfvc/resolve-command.md b/docs/repos/tfvc/resolve-command.md index 722836131ef..48e43f180a3 100644 --- a/docs/repos/tfvc/resolve-command.md +++ b/docs/repos/tfvc/resolve-command.md @@ -19,7 +19,11 @@ The Team Foundation Version Control (TFVC) `tf resolve` command lets you resolve ## Prerequisites -To use the `resolve` command, you must be either the workspace owner or have the global **Administer workspaces** permission set to **Allow**. You must also have the **Read** and **Check out** permissions for the items involved in a resolve operation set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +| **Permissions** | - Owner of the workspace or **Administer workspaces** permission set to **Allow**.
      - **Read** and **Check out** permissions for the items involved in a resolve operation set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/roll-back-changesets.md b/docs/repos/tfvc/roll-back-changesets.md index f70d547911a..d5f46ecf296 100644 --- a/docs/repos/tfvc/roll-back-changesets.md +++ b/docs/repos/tfvc/roll-back-changesets.md @@ -4,7 +4,7 @@ titleSuffix: Azure Repos description: Understand how to roll back changesets by using Visual Studio with Team Foundation Version Control (TFVC). ms.assetid: 11864092-7a1d-4810-ae01-148afbaa7852 ms.service: azure-devops-repos -ms.topic: conceptual +ms.topic: how-to ms.date: 11/23/2022 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-tfvc @@ -23,7 +23,7 @@ You can also use the `tf` command-line utility to roll back changes. For more in ## Prerequisites -You must be one of the **Contributors** for your project. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +[!INCLUDE [contributor-only-prerequisites](includes/contributor-only-prerequisites.md)] ## Roll back changes from a single changeset diff --git a/docs/repos/tfvc/rollback-command-team-foundation-version-control.md b/docs/repos/tfvc/rollback-command-team-foundation-version-control.md index c684a5201b3..e1af37714a8 100644 --- a/docs/repos/tfvc/rollback-command-team-foundation-version-control.md +++ b/docs/repos/tfvc/rollback-command-team-foundation-version-control.md @@ -20,7 +20,11 @@ You can use the Team Foundation Version Control (TFVC) `tf rollback` command to ## Prerequisites -To use this command, you must have the **Read**, **Check Out**, and **Check In** permissions set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +| **Permissions** | **Read**, **Check Out**, and **Check In** permissions set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/set-tfvc-repository-permissions.md b/docs/repos/tfvc/set-tfvc-repository-permissions.md index 2f9e3ba3f02..e2d53d7d79b 100644 --- a/docs/repos/tfvc/set-tfvc-repository-permissions.md +++ b/docs/repos/tfvc/set-tfvc-repository-permissions.md @@ -1,7 +1,7 @@ --- title: Set TFVC repository permissions titleSuffix: Azure Repos -description: Follow steps to grant or restrict access to a Team Foundation Version Control (TFVC) repository feature or function. +description: Follow steps to manage access to a Team Foundation Version Control (TFVC) repository feature or function. ms.assetid: ms.service: azure-devops-repos ms.topic: quickstart @@ -12,29 +12,33 @@ ms.date: 11/30/2022 ms.subservice: azure-devops-repos-git --- - # Set TFVC repository permissions [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-eq-2019](../../includes/version-vs-gt-eq-2019.md)] -You can grant or restrict access to a Team Foundation Version Control (TFVC) repository to lock down who can contribute to your source code. There's only one TFVC repository per project. For guidance on who to give greater permission levels, see [Grant or restrict access using permissions](../../organizations/security/restrict-access.md). +You can manage access to a Team Foundation Version Control (TFVC) repository to lock down who can contribute to your source code. There's only one TFVC repository per project. For guidance on who to give greater permission levels, see [Manage access using permissions](../../organizations/security/restrict-access.md). ## Prerequisites -- You must have a TFVC project. If you don't have a project yet, create one in [Azure DevOps Services](../../user-guide/sign-up-invite-teammates.md) or set one up in [on-premises Azure DevOps Server](../../organizations/projects/create-project.md). - -- You must be a member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md) or have **Manage permissions** set to **Allow** for the TFVC repository. - ::: moniker range="azure-devops" -- To contribute to the source code, you must be granted **Basic** access level or greater. Users granted **Stakeholder** access for private projects have no access to source code. Users granted **Stakeholder** access for public projects have the same access as **Contributors** and those granted **Basic** access. To learn more, see [About access levels](../../organizations/security/access-levels.md). +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of the Azure DevOps project where the TFVC repository is located. | +| **Permissions** | Member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md) or **Manage permissions** set to **Allow** for the TFVC repository.| +|**Access levels**| To contribute to source code: At least **Basic** access. **Stakeholder** access for private projects provides no access to source code. **Stakeholder** access for public projects provides the same access as **Contributors** and **Basic**. For more information, see [About access levels](../../organizations/security/access-levels.md).| ::: moniker-end ::: moniker range="< azure-devops" -- To contribute to the source code, you must be granted **Basic** access level or greater. Users granted **Stakeholder** access have no access to source code. To learn more, see [About access levels](../../organizations/security/access-levels.md). +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of the Azure DevOps project where the TFVC repository is located. | +| **Permissions** | Member of the [Project Administrators group](../../organizations/security/change-project-level-permissions.md) or **Manage permissions** set to **Allow** for the TFVC repository.| +|**Access levels**| To contribute to source code: At least **Basic** access. **Stakeholder** access for private projects provides no access to source code. For more information, see [About access levels](../../organizations/security/access-levels.md).| + ::: moniker-end ## Default repository permissions @@ -44,31 +48,31 @@ By default, members of the project **Contributors** group have permissions to co [!INCLUDE [temp](../../organizations/security/includes/code-tfvc.md)] -## Set TFVC repository security permissions -To set permissions for a custom security group, you must have defined that group previously. See [Change project-level permissions](../../organizations/security/change-project-level-permissions.md). +## Set TFVC repository security permissions +To set permissions for a custom security group, ensure that the group is already defined. For more information, see [Change project-level permissions](../../organizations/security/change-project-level-permissions.md) for more information. ::: moniker range="azure-devops" 1. In the Azure DevOps web portal for the project where you want to set permissions, select **Project settings**. To choose another project, see [Switch project, repository, team](../../project/navigation/go-to-project-repo.md). -1. Select **Repositories**. +2. Select **Repositories**. -1. Select the TFVC repository labeled with the name of the project. +3. Select the TFVC repository labeled with the name of the project. ![Image that shows choosing a TFVC repository.](media/tfvc-permissions/open-tfvc-repositories-security-s185.png) -1. Choose the user or security group you want to change permissions for. +4. Choose the user or security group you want to change permissions for. To set permissions for a specific user or group, enter their name in the identity box and select their identity. ![Image that shows adding a user or group.](media/tfvc-permissions/add-user-group.png) -1. Make the changes to the permission set. +5. Make the changes to the permission set. ![Image that shows setting the permissions for a user or group.](media/tfvc-permissions/set-tfvc-permissions.png) -1. When you're done, navigate away from the page. The permission changes are automatically saved for the selected user or group. +6. When you're done, navigate away from the page. The permission changes are automatically saved for the selected user or group. If you add a user or group and don't change any of their permissions, the user or group you added no longer appears after you refresh the permissions page. @@ -76,8 +80,7 @@ To set permissions for a custom security group, you must have defined that group ::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range="- **Check In**: To check in changes to the repository.
      - **Check Out**: To check out files for editing.
      - **Manage Workspaces**: To create and manage workspaces. | + ## Share using TFVC 1. If you haven't yet, [Connect to Azure DevOps Services using Eclipse](../../organizations/projects/connect-to-projects.md). diff --git a/docs/repos/tfvc/share-your-code-in-tfvc-vs.md b/docs/repos/tfvc/share-your-code-in-tfvc-vs.md index 22f3d21d1fd..31e4b68ea62 100644 --- a/docs/repos/tfvc/share-your-code-in-tfvc-vs.md +++ b/docs/repos/tfvc/share-your-code-in-tfvc-vs.md @@ -21,13 +21,15 @@ Whether your software project is large, small, or brand new, it's best to use ve - If you want to work in a distributed version control system, you can instead use [Git with Azure Repos](../../repos/git/share-your-code-in-git-vs.md). -- If you have code you want to migrate into Azure DevOps Services, see [Migration options](../../migrate/migrate-from-tfs.md). +- If you have code you want to migrate into Azure DevOps Services, see the [Migration overview](../../migrate/migration-overview.md). ## Prerequisites -- [Sign up for Azure DevOps and create a project](../../organizations/accounts/create-organization.md). - -- Install [Visual Studio](https://visualstudio.microsoft.com/downloads). +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of the Azure DevOps project where the TFVC repository is located. | +| **Permissions** | - **Read**: To view the repository and its contents.
      - **Check In**: To check in changes to the repository.
      - **Check Out**: To check out files for editing.
      - **Manage Workspaces**: To create and manage workspaces. | +| **Tools** | [Visual Studio](https://visualstudio.microsoft.com/downloads). | ## Connect to your project @@ -141,4 +143,4 @@ Your whole team can work on the code now. All changes are tracked in version con ## Next steps - [Get your code reviewed](get-code-reviewed-vs.md) -- [Migrate from Azure DevOps Server into Azure DevOps Services](../../migrate/migrate-from-tfs.md) \ No newline at end of file +- [Learn about migrating from Azure DevOps Server to Azure DevOps Services](../../migrate/migration-overview.md) diff --git a/docs/repos/tfvc/share-your-code-in-tfvc-xcode.md b/docs/repos/tfvc/share-your-code-in-tfvc-xcode.md index 37f3b74030c..8356b13c7df 100644 --- a/docs/repos/tfvc/share-your-code-in-tfvc-xcode.md +++ b/docs/repos/tfvc/share-your-code-in-tfvc-xcode.md @@ -15,9 +15,15 @@ ms.subservice: azure-devops-repos-tfvc [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - Share your Xcode projects using a TFVC repository by using the Git-tf command line tool to push your changes from the local Git repository to TFVC. +## Prerequisites + +| Category | Requirements | +|--------------|-------------| +| **Project access** | Member of the Azure DevOps project where the TFVC repository is located. | +| **Permissions** | - **Read**: To view the repository and its contents.
      - **Check In**: To check in changes to the repository.
      - **Check Out**: To check out files for editing.
      - **Manage Workspaces**: To create and manage workspaces. | + ## Download and configure Git-tf 1. Download and extract [Git-tf](https://www.microsoft.com/download/details.aspx?id=30474). diff --git a/docs/repos/tfvc/shelve-command.md b/docs/repos/tfvc/shelve-command.md index 52ef604cef6..8aba252a368 100644 --- a/docs/repos/tfvc/shelve-command.md +++ b/docs/repos/tfvc/shelve-command.md @@ -21,7 +21,11 @@ The Team Foundation Version Control (TFVC) `shelve` command stores a set of pend ## Prerequisites -If you want to use the `shelve` command to delete a shelveset, you must be a shelveset owner, or your **Administer shelved changes** permission must be set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|Owner of the shelveset or **Administer shelved changes** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/shelvesets-command.md b/docs/repos/tfvc/shelvesets-command.md index 911bfc0802b..069213937fa 100644 --- a/docs/repos/tfvc/shelvesets-command.md +++ b/docs/repos/tfvc/shelvesets-command.md @@ -21,7 +21,11 @@ The Team Foundation Version Control (TFVC) `shelvesets` command displays informa ## Prerequisites -To use the `shelvesets` command, you must have the **Read** permission and the **Check out** permission set to **Allow** for the items in the shelvesets. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission and the **Check out** permission set to **Allow** for the items in the shelvesets.| + + For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/status-command.md b/docs/repos/tfvc/status-command.md index 3c4d281d8b5..96626699d5a 100644 --- a/docs/repos/tfvc/status-command.md +++ b/docs/repos/tfvc/status-command.md @@ -22,10 +22,13 @@ The Team Foundation Version Control (TFVC) `status` command, or its alias `stat` > [!NOTE] > A pending change candidate is a file in the workspace's folder or subfolder that isn't added to version control. To view all pending changes candidates in Visual Studio, go to **Team Explorer** > **Pending Changes** > **Excluded Changes**, and then select **Detected**. - ## Prerequisites -To use the `status` command, you must have the **Read** permission for the source item and the **Check out** and **Merge** permissions for the target folder set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission for the source item and the **Check out** and **Merge** permissions for the target folder set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/suspend-your-work-manage-your-shelvesets.md b/docs/repos/tfvc/suspend-your-work-manage-your-shelvesets.md index 69bd8ce411e..b79d452133c 100644 --- a/docs/repos/tfvc/suspend-your-work-manage-your-shelvesets.md +++ b/docs/repos/tfvc/suspend-your-work-manage-your-shelvesets.md @@ -19,7 +19,7 @@ For various reasons, sometimes you need to set aside some or all of your work th - **Interruption:** You have pending changes that aren't ready to check in, but you need to work on a different task. - **Collaboration:** You have pending changes that aren't ready to check in, but you need to share them with another team member. -- **Code review:** You want another team member to review your pending changes. To learn more about code reviews, see [Day in the life of a devops developer: Write new code for a user story](day-life-alm-developer-write-new-code-user-story.md). +- **Code review:** You want another team member to review your pending changes. For more information about code reviews, see [Day in the life of a devops developer: Write new code for a user story](day-life-alm-developer-write-new-code-user-story.md). - **Private build:** Before you check in your changes, you want to use your automated build system to build and test your code. - **Backup:** You have work in progress that you can't finish but want to make a backup copy of. You want the backup copy to be stored on your server and available to other team members. - **Handoff:** You have work in progress that you want to hand off to another team member. @@ -28,7 +28,7 @@ In these scenarios and others, you can move your [pending changes](develop-code- ## Prerequisites -You must be one of the **Contributors** for your project. To learn more, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +[!INCLUDE [contributor-only-prerequisites](includes/contributor-only-prerequisites.md)] [!INCLUDE [Visual Studio versions with My Work and Code Review features](includes/note-my-work-code-review-support.md)] diff --git a/docs/repos/tfvc/tfvc-check-in-policy-migrate-guide.md b/docs/repos/tfvc/tfvc-check-in-policy-migrate-guide.md new file mode 100644 index 00000000000..92e1ec0bba2 --- /dev/null +++ b/docs/repos/tfvc/tfvc-check-in-policy-migrate-guide.md @@ -0,0 +1,96 @@ +--- +title: Migrate custom obsolete check-in policy +titleSuffix: Azure Repos +description: How to migrate custom obsolete check-in policy +ms.assetid: +ms.service: azure-devops-repos +ms.topic: conceptual +ms.date: 03/27/2025 +monikerRange: 'azure-devops' +ms.subservice: azure-devops-repos-tfvc +--- +# Migrate custom check-in policy +> [!WARNING] +> To use the provided migration method you must not remove the old implementations of the policies prior to following this guide. + +1. To migrate your custom policies, you should first create a new class with the same methods but inheriting `CheckinPolicyBase` class (`IPolicyCompatibilityJson` for `IPolicyCompatibility`) instead of `PolicyBase`. + Examples: + +Obsolete +``` + [Serializable] + public class Simple : PolicyBase + { + public override string Description => "SimplePolicyDescription"; + ... + } +``` + +Updated +``` + [Serializable] + public class SimpleNew : CheckinPolicyBase + { + public override string Description => "SimplePolicyDescription"; + ... + } +``` +2. If `GetBinaryFormatter` was overridden, then also implement `GetJsonSerializerSettings` with same logic for serialization. + Example: + +Obsolete +``` + [Serializable] + public class Simple : PolicyBase + { + public override BinaryFormatter GetBinaryFormatter() + { + BinaryFormatter formatter = new BinaryFormatter(); + formatter.Binder = new SimpleBinder(); + return formatter; + } + ... + } +``` +Updated +``` + [Serializable] + public class SimpleNew : CheckinPolicyBase + { + public override JsonSerializerSettings GetJsonSerializerSettings() + { + return new JsonSerializerSettings() + { + SerializationBinder = new SimpleNewSerializationBinder(), + TypeNameHandling = TypeNameHandling.Objects + }; + } + ... + } +``` +3. Instead of the old methods like `GetCheckinPoliciesForServerPaths`/`GetCheckinPolicies`/`SetCheckinPolicies` new ones were introduced: `GetCheckinClientPoliciesForServerPaths`/`GetCheckinClientPolicies`/`SetCheckinClientPolicies` accordingly. +For example, default behavior right now for the `LoadPolicies` method in the package is to use new policies if they are created/available and obsolete ones in case they are absent. +> [!NOTE] +> If you are not planning to use the migration method provided by NuGet package, further instructions can be omitted and obsolete policies can be removed, you are done, congratulations! + +4. For your obsolete policy add `IPolicyMigration` (This interface marked as deprecated only to show that it will be removed as unnecessary together with `PolicyBase` and `IPolicyCompatibility`). +> [!WARNING] +> Obsolete policies that don’t inherit this interface will be **skipped** during migration and **not** saved as new policies. + +5. Implement `ToNewPolicyType` from the mentioned interface. It should return the instance of the newly created policy class that is based on currently modified policy. + Example: +``` + [Serializable] + public class Simple : PolicyBase, IPolicyMigration + { + ... + public CheckinPolicyBase ToNewPolicyType() + { + return new SimpleNew(); + } + } +``` +6. Call `MigrateFromOldPolicies` method. + + +You are done, congratulations! diff --git a/docs/repos/tfvc/toc.yml b/docs/repos/tfvc/toc.yml index 344c417dc2a..018b13d36d1 100644 --- a/docs/repos/tfvc/toc.yml +++ b/docs/repos/tfvc/toc.yml @@ -12,7 +12,7 @@ href: share-your-code-in-tfvc-xcode.md - name: Develop an app href: develop-your-app-team-foundation-version-control.md - - name: Write new code + - name: Write new code href: day-life-alm-developer-write-new-code-user-story.md - name: Suspend work using My Work href: day-life-alm-developer-suspend-work-fix-bug-conduct-code-review.md @@ -56,6 +56,8 @@ href: enable-disable-check-policies.md - name: Remove check-in policies href: remove-check-policies.md + - name: Migrate custom check-in policy + href: tfvc-check-in-policy-migrate-guide.md - name: Configure check-in notes href: configure-check-notes.md - name: Test impact for partially mapped repositories diff --git a/docs/repos/tfvc/undelete-command.md b/docs/repos/tfvc/undelete-command.md index 29554f73e35..df59454c322 100644 --- a/docs/repos/tfvc/undelete-command.md +++ b/docs/repos/tfvc/undelete-command.md @@ -23,11 +23,9 @@ The Team Foundation Version Control (TFVC) `undelete` command restores items tha ## Prerequisites -To use the `undelete` command: - -- You must have the **Check out** permission set to **Allow**. -- If you include the `/lock` option with a value other than `None`, you must have the **Lock** permission set to **Allow**. -- You must own the workspace or have the global **Administer workspaces** permission set to **Allow**. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- **Check out** permission set to **Allow**.
      - If you include the `/lock` option with a value other than `None`: **Lock** permission set to **Allow**.
      - Owner of the workspace or **Administer workspaces** permission set to **Allow**.| For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). diff --git a/docs/repos/tfvc/undo-changes-another-user-workspace.md b/docs/repos/tfvc/undo-changes-another-user-workspace.md index a16c69dc607..aeb31d9710f 100644 --- a/docs/repos/tfvc/undo-changes-another-user-workspace.md +++ b/docs/repos/tfvc/undo-changes-another-user-workspace.md @@ -24,7 +24,11 @@ Occasionally a team member is blocked from checking in a file that someone else ## Prerequisites -To undo pending changes in another user's workspace, you must have the **Administer workspaces** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Administer workspaces** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Undo the changes in another user's workspace diff --git a/docs/repos/tfvc/undo-command.md b/docs/repos/tfvc/undo-command.md index 54c55282fdc..6427a943247 100644 --- a/docs/repos/tfvc/undo-command.md +++ b/docs/repos/tfvc/undo-command.md @@ -19,7 +19,11 @@ The Team Foundation Version Control (TFVC) `undo` command discards one or more p ## Prerequisites -By default, members of the project **Contributors** group have permissions to contribute to a repository and use the `undo` command in their own workspaces. To undo pending changes in another user's workspace, you must have the **Administer workspaces** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To use the `undo` command in your own workspaces: Member of the **Contributors** group.
      - To undo pending changes in another user's workspace: **Administer workspaces** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax @@ -88,7 +92,7 @@ tf undo [/workspace:[;]] :::column span="3"::: Specifies the name of the workspace to undo pending changes in. If not specified, the workspace that maps the current directory is used. - You can specify `` to undo a pending change in a workspace that belongs to a specific user. If you don't provide this argument, the workspace that's owned by the current user is used by default. But if you provide the `/login` argument with a username, the workspace that's owned by that user is used. You must have the **UndoOther** permission set to **Allow** to undo changes in another user's workspace. + You can specify `` to undo a pending change in a workspace that belongs to a specific user. If you don't provide this argument, the workspace that's owned by the current user is used by default. But if you provide the `/login` argument with a username, the workspace that's owned by that user is used. Have the **UndoOther** permission set to **Allow** to undo changes in another user's workspace. > [!Note] > You can use the `undo` command to undo a pending change in a remote workspace that's still in use. Before continuing work in that workspace, a user must sign in to the machine that hosts the workspace and get the items that are affected by the undo operation. For more information about the `get` command and its `/all` argument, see [Get command](get-command.md). diff --git a/docs/repos/tfvc/unlabel-command.md b/docs/repos/tfvc/unlabel-command.md index 8fc42c64f12..2acb1e6c834 100644 --- a/docs/repos/tfvc/unlabel-command.md +++ b/docs/repos/tfvc/unlabel-command.md @@ -21,7 +21,11 @@ The Team Foundation Version Control (TFVC) `unlabel` command removes an item fro ## Prerequisites -To use the `unlabel` command, you must either own the label, or have the **Administer labels** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|To use the `unlabel` command: Owner of the label or **Administer labels** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax @@ -100,7 +104,7 @@ The following sections describe arguments and options of the `unlabel` command. The `unlabel` command of the `tf` command-line utility removes an item from an existing label in the Azure DevOps server. For an introduction to labels, see [Use labels to take a snapshot of your files](use-labels-take-snapshot-your-files.md). For information about how to assign a label to a set of files and folders, see [Label command (Team Foundation Version Control)](label-command-team-foundation-version-control.md). -If you remove all items from a label in the Azure DevOps server, that label is deleted. You can also delete a label by using the `tf label /delete` command. To learn more about the existing labels in the system, see [Labels command](labels-command.md). +If you remove all items from a label in the Azure DevOps server, that label is deleted. You can also delete a label by using the `tf label /delete` command. For more information about the existing labels in the system, see [Labels command](labels-command.md). For more information about how to use the `tf` command-line utility, see [Use Team Foundation version control commands](use-team-foundation-version-control-commands.md). diff --git a/docs/repos/tfvc/unshelve-command.md b/docs/repos/tfvc/unshelve-command.md index b554e41f97f..36accb7bd1f 100644 --- a/docs/repos/tfvc/unshelve-command.md +++ b/docs/repos/tfvc/unshelve-command.md @@ -19,10 +19,9 @@ The Team Foundation Version Control (TFVC) `unshelve` command restores shelved f ## Prerequisites -- To use the `unshelve` command: - - You must have the **Read** permission set to **Allow**. - - You must have the **Check out** permission for the items in the shelveset set to **Allow**. -- To delete a shelveset, you must be its owner or have the **Administer shelved changes** global permission set to **Allow**. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To use the `unshelve` command: **Read** permission set to **Allow** and **Check out** permission for the items in the shelveset set to **Allow**.
      - To delete a shelveset: Owner or **Administer shelved changes** permission set to **Allow**.| For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). diff --git a/docs/repos/tfvc/use-labels-take-snapshot-your-files.md b/docs/repos/tfvc/use-labels-take-snapshot-your-files.md index 64c4d522ec7..5d8724d14d8 100644 --- a/docs/repos/tfvc/use-labels-take-snapshot-your-files.md +++ b/docs/repos/tfvc/use-labels-take-snapshot-your-files.md @@ -20,9 +20,11 @@ Team Foundation Version Control (TFVC) labels provide a way for you to take a sn ## Prerequisites -- To apply a label, you must have the **Label** permission set to **Allow**. -- To find, list, or view labels, you must have the **Read** permission set to **Allow**. -- To modify or delete a label, you must own the label or have the **Administer Labels** permission set to **Allow**. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To apply a label: **Label** permission set to **Allow**.
      - To find, list, or view labels: **Read** permission set to **Allow**.
      - To modify or delete a label: Owner of the label or **Administer Labels** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Use labels diff --git a/docs/repos/tfvc/view-branch-hierarchy-team-project.md b/docs/repos/tfvc/view-branch-hierarchy-team-project.md index 612302168b0..2663a9098f5 100644 --- a/docs/repos/tfvc/view-branch-hierarchy-team-project.md +++ b/docs/repos/tfvc/view-branch-hierarchy-team-project.md @@ -25,6 +25,14 @@ As a project grows, its branch structure typically also grows and becomes more c The following procedures explain how to use Team Foundation Version Control (TFVC) to answer these types of questions. +## Prerequisites + +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). + ## View and work with your branches You can use the **Hierarchy** window to perform the following tasks: diff --git a/docs/repos/tfvc/view-command.md b/docs/repos/tfvc/view-command.md index 0533204e6ed..0dd7e0f5eab 100644 --- a/docs/repos/tfvc/view-command.md +++ b/docs/repos/tfvc/view-command.md @@ -21,7 +21,11 @@ The Team Foundation Version Control (TFVC) `view` command retrieves a specific v ## Prerequisites -To use the `view` command, you must have the **Read** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|To use the `view` command: **Read** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/view-file-changes-using-annotate.md b/docs/repos/tfvc/view-file-changes-using-annotate.md index 8dd599d5d6f..c4845f37dca 100644 --- a/docs/repos/tfvc/view-file-changes-using-annotate.md +++ b/docs/repos/tfvc/view-file-changes-using-annotate.md @@ -1,32 +1,38 @@ --- -title: View file changes using annotate +title: View file changes using annotate in Visual Studio titleSuffix: Azure Repos -description: Annotate a file in Team Foundation Version Control to see who made changes and what changes they made in all earlier versions of the file. +description: Use annotate to a see changes in earlier versions of a file in Team Foundation Version Control using Visual Studio. ms.assetid: 34e29de4-0972-4e32-9d3d-26dc09f00713 ms.service: azure-devops-repos ms.topic: conceptual -ms.date: 11/22/2022 +ms.date: 05/30/2024 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-tfvc --- -# View file changes using annotate +# View file changes using annotate in Visual Studio [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-eq-2019.md](../../includes/version-vs-gt-eq-2019.md)] -In Team Foundation Version Control (TFVC), you can annotate a file to learn who made changes and what changes they made in all earlier versions of the file. +In Team Foundation Version Control (TFVC), you can use annotate in Visual Studio to view the changes in earlier versions of file. You can see information about the change, view the changeset details, compare with previous versions, and more. ## Prerequisites -To perform these procedures, you must have the **Read** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission set to **Allow** for the repository. | +|**Project** |An Azure DevOps [project with a TFVC repository](./share-your-code-in-tfvc-vs.md#connect-to-your-project). | +| **Tools** |[Visual Studio](https://visualstudio.microsoft.com/downloads).| + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ### To annotate a file -1. On the Visual Studio menu bar, select **View** > **Other Windows** > **Source Control Explorer**. +1. On the Visual Studio menu bar, select **View** > **Solution Explorer**. -1. In **Source Control Explorer**, right-click the version of the file that you want to annotate, and then select **Annotate**. +1. In **Solution Explorer**, right-click the version of the file that you want to annotate, select **Source Control**, and select **Annotate**. The **Annotated** window displays the annotated file. @@ -66,7 +72,7 @@ To perform these procedures, you must have the **Read** permission set to **Allo - **Annotate This Version** to view annotation information for the selected version and all earlier versions of the file. This information appears in an **Annotate** window. - - **Track Changeset** to see to which branches the changeset has been merged into. For more information, see [View where and when changesets have been merged](view-where-when-changesets-have-been-merged.md). + - **Track Changeset** to see to which branches the changeset was merged into. For more information, see [View where and when changesets have been merged](view-where-when-changesets-have-been-merged.md). - **Get This Version** to download the selected version of the file to your local workspace. diff --git a/docs/repos/tfvc/view-where-when-changesets-have-been-merged.md b/docs/repos/tfvc/view-where-when-changesets-have-been-merged.md index f6915534d96..f291676585b 100644 --- a/docs/repos/tfvc/view-where-when-changesets-have-been-merged.md +++ b/docs/repos/tfvc/view-where-when-changesets-have-been-merged.md @@ -4,7 +4,7 @@ titleSuffix: Azure Repos description: Use the Team Foundation Version Control Tracking Changeset window to see which code branches received which changes and to see when the changes were merged. ms.assetid: 457567ff-7da3-4098-b047-bd169bad5a38 ms.service: azure-devops-repos -ms.topic: conceptual +ms.topic: how-to ms.date: 11/22/2022 monikerRange: '<= azure-devops' ms.subservice: azure-devops-repos-tfvc @@ -26,8 +26,9 @@ In Team Foundation Version Control (TFVC), you can use the **Tracking Changeset* ## Prerequisites -- To view changesets, your **Read** permission must be set to **Allow** for the branches that you're working with. -- To display the timeline view of a changeset, your **Manage branch object** permission must be set to **Allow**. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To view changesets: **Read** permission set to **Allow** for the branches that you're working with.
      - To display the timeline view of a changeset: **Manage branch object** permission must be set to **Allow**. | For more information about permissions, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). diff --git a/docs/repos/tfvc/work-version-control-locks.md b/docs/repos/tfvc/work-version-control-locks.md index 7db04c789df..e529771cfbf 100644 --- a/docs/repos/tfvc/work-version-control-locks.md +++ b/docs/repos/tfvc/work-version-control-locks.md @@ -18,7 +18,7 @@ ms.subservice: azure-devops-repos-tfvc When you use Team Foundation Version Control (TFVC) to manage files, you can lock a file or folder to prevent it from being checked out and altered. -To learn more, see any of the following articles: +For more information, see any of the following articles: - [Understand lock types](understand-lock-types.md): Explains the various types of TFVC locks that you can apply against the source control server, and shows how to use them. - [Lock and unlock folders or files](lock-unlock-folders-files.md): Explains the steps that you can use to lock and unlock source control items. diff --git a/docs/repos/tfvc/workfold-command.md b/docs/repos/tfvc/workfold-command.md index dbb63debe4d..a3a00d7b897 100644 --- a/docs/repos/tfvc/workfold-command.md +++ b/docs/repos/tfvc/workfold-command.md @@ -20,8 +20,11 @@ The Team Foundation Version Control (TFVC) `workfold` command creates, modifies, ## Prerequisites -To use the `workfold` command, you must be the owner of the specified or implied workspace or have the global **Administer workspaces** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). - +| Category | Requirements | +|--------------|-------------| +|**Permissions**|To use the `workfold` command: Owner of the specified or implied workspace or **Administer workspaces** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/tfvc/workspace-command.md b/docs/repos/tfvc/workspace-command.md index c783f70ed5b..328a5fe0cf2 100644 --- a/docs/repos/tfvc/workspace-command.md +++ b/docs/repos/tfvc/workspace-command.md @@ -20,9 +20,9 @@ The Team Foundation Version Control (TFVC) `workspace` command provides a way fo ## Prerequisites -- To modify or delete an existing workspace, you must be the owner or have the global **Administer workspaces** permission set to **Allow**. -- To create a workspace, you must have the global **Create a workspace** permission set to **Allow**. -- To create workspaces for other users, you must have the **Administer workspaces** permission set to **Allow**. +| Category | Requirements | +|--------------|-------------| +|**Permissions**|- To modify or delete an existing workspace: Owner or **Administer workspaces** permission set to **Allow**.
      - To create a workspace: **Create a workspace** permission set to **Allow**.
      - To create workspaces for other users: **Administer workspaces** permission set to **Allow**.| For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). @@ -76,8 +76,8 @@ The following sections describe arguments and options of the `workspace` command |`/newname`|Renames an existing workspace.| |`/noprompt`|Performs the specified workspace command without displaying a dialog box.| |`/collection`|Specifies the project collection.| -|`/permission`|Specifies the options for workspace permissions:

      • `Private`: Only the owners can use, check in files to, or administer the workspace.

      • `Public Limited`: Any valid user can use the workspace. But only the owners can check in files to or administer the workspace.

      • `Public`: Any valid user can use, check in files to, or administer the workspace.

      | -|`/location`|Specifies where the workspace is created:

      • `local`: On the client machine. This value is the default.

      • `server`: On the Azure DevOps server.

      | +|`/permission`|Specifies the options for workspace permissions:

        - `Private`: Only the owners can use, check in files to, or administer the workspace.


        - `Public Limited`: Any valid user can use the workspace. But only the owners can check in files to or administer the workspace.


        - `Public`: Any valid user can use, check in files to, or administer the workspace.


      | +|`/location`|Specifies where the workspace is created:

        - `local`: On the client machine. This value is the default.


        - `server`: On the Azure DevOps server.


      | |`/login`|Specifies the username and password to authenticate the user with Azure DevOps.| |`/newowner`|Specifies the username for the new owner of the workspace.| @@ -114,6 +114,29 @@ If you delete a workspace that contains pending changes, TFVC cancels the pendin > [!NOTE] > Commands that run manually require the `/noprompt` option to bypass user acknowledgement. Be careful if you use the PowerShell `Start()` method to run commands. The `/noprompt` option can be automatically set in PowerShell. + +When deleting a workspace you need to provide the `` and `` + +You can use the `workspace` command to retrieve those values. For more information, see [workspaces command](workspaces-command.md). +To find the `` value, run the following command: + +``` +c:\projects>tf workspaces /computer:* /owner:* /collection:`` /format:xml +``` + +To find the `` value, use the `` value from the previous command's output as the `` value. That value has the format of an Azure Active Directory (Azure AD) object ID followed by a backslash and a user principal name. Use the entire value. Then run the following command: + +``` +c:\projects>tf workspaces /owner: /computer:* /collection:`` +``` + +To delete the workspace, run the following command: + +``` +c:\projects>tf workspace /delete ; /collection:` +``` + + ### Edit a workspace You can change the following workspace attributes: @@ -132,7 +155,7 @@ The following example opens the **Add Workspace** dialog box and creates a new w c:\projects>tf workspace /new /collection:https://myserver:8080/tfs/DefaultCollection ``` -The following example creates a new workspace called **Beta1** and assigns **jenh** as the workspace owner. You must have the **AdminWorkspaces** permission to assign ownership of a new workspace to another user. For more information about security permissions, See [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +The following example creates a new workspace called **Beta1** and assigns **jenh** as the workspace owner. Have the **AdminWorkspaces** permission to assign ownership of a new workspace to another user. For more information about security permissions, See [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ``` c:\projects>tf workspace /new Beta1;jenh diff --git a/docs/repos/tfvc/workspaces-command.md b/docs/repos/tfvc/workspaces-command.md index 60fec3b9190..1b1cc249f81 100644 --- a/docs/repos/tfvc/workspaces-command.md +++ b/docs/repos/tfvc/workspaces-command.md @@ -19,7 +19,11 @@ The Team Foundation Version Control (TFVC) `workspaces` command displays informa ## Prerequisites -To use the `workspaces` command, you must have the **Read** permission set to **Allow**. For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). +| Category | Requirements | +|--------------|-------------| +|**Permissions**|**Read** permission set to **Allow**. | + +For more information, see [Default TFVC permissions](../../organizations/security/default-tfvc-permissions.md). ## Syntax diff --git a/docs/repos/toc.yml b/docs/repos/toc.yml index 382d85541d3..71ca68d507a 100644 --- a/docs/repos/toc.yml +++ b/docs/repos/toc.yml @@ -2,44 +2,33 @@ href: index.yml - name: What is Azure Repos? href: get-started/what-is-repos.md -- name: Compare Git and TFVC - href: tfvc/comparison-git-tfvc.md -- name: Use Git and TFVC - href: git/team-projects.md -- name: Key concepts - href: get-started/key-concepts-repos.md -- name: Search code repositories - href: ../project/search/functional-code-search.md?toc=/azure/devops/repos/toc.json - name: Get started href: get-started/toc.yml - name: Cross-service integration items: - name: Cross-service integration overview - href: ../cross-service/cross-service-overview.md?toc=/azure/devops/repos/toc.json + href: ../cross-service/cross-service-overview.md?toc=/azure/devops/repos/toc.json - name: End-to-end traceability - href: ../cross-service/end-to-end-traceability.md?toc=/azure/devops/repos/toc.json + href: ../cross-service/end-to-end-traceability.md?toc=/azure/devops/repos/toc.json displayname: pull requests, commits, comments, build - name: 'Use #ID to link to work items' - href: ../organizations/notifications/add-links-to-work-items.md?toc=/azure/devops/repos/toc.json + href: ../organizations/notifications/add-links-to-work-items.md?toc=/azure/devops/repos/toc.json displayname: pull requests, commits, comments, build, wiki - - name: Configure Git repositories to integrate with work tracking - href: git/configure-repos-work-tracking.md?toc=/azure/devops/repos/toc.json - displayname: auto link, transition, check for linked work items, auto complete, external links - name: Configure pipelines to support work tracking - href: ../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/repos/toc.json + href: ../pipelines/integrations/configure-pipelines-work-tracking.md?toc=/azure/devops/repos/toc.json displayname: auto link, create work item on build failure, report deployment status, - name: Drive Git development displayName: create branch, new branch, build - href: ../boards/backlogs/connect-work-items-to-git-dev-ops.md?toc=/azure/devops/repos/toc.json + href: ../boards/backlogs/connect-work-items-to-git-dev-ops.md?toc=/azure/devops/repos/toc.json - name: View deployment stages on work item form - href: ../boards/work-items/work-item-deployments-control.md?toc=/azure/devops/repos/toc.json + href: ../boards/backlogs/add-link.md?toc=/azure/devops/repos/toc.json displayname: release - name: Auto complete work items with pull requests - href: ../boards/work-items/auto-complete-work-items-pull-requests.md?toc=/azure/devops/repos/toc.json + href: ../boards/work-items/auto-complete-work-items-pull-requests.md?toc=/azure/devops/repos/toc.json - name: GitHub integration - href: ../cross-service/github-integration.md?toc=/azure/devops/repos/toc.json + href: ../cross-service/github-integration.md?toc=/azure/devops/repos/toc.json - name: Deploy to Azure - href: ../pipelines/overview-azure.md?toc=/azure/devops/repos/toc.json + href: ../pipelines/overview-azure.md?toc=/azure/devops/repos/toc.json - name: Git href: git/toc.yml - name: Team Foundation version control @@ -52,12 +41,34 @@ href: security/github-advanced-security-permissions.md - name: Billing for GitHub Advanced Security href: security/github-advanced-security-billing.md + - name: Security Overview for GitHub Advanced Security + href: security/github-advanced-security-security-overview.md - name: Secret Scanning for GitHub Advanced Security - href: security/github-advanced-security-secret-scanning.md + items: + - name: Configure secret scanning + href: security/github-advanced-security-secret-scanning.md + - name: Secret scanning patterns + href: security/github-advanced-security-secret-scan-patterns.md + - name: Troubleshoot secret scanning + href: security/github-advanced-security-secret-scanning-troubleshoot.md - name: Dependency Scanning for GitHub Advanced Security - href: security/github-advanced-security-dependency-scanning.md + items: + - name: Configure dependency scanning + href: security/github-advanced-security-dependency-scanning.md + - name: Supported ecosystems and build configurations + href: security/github-advanced-security-dependency-scanning-ecosystems.md + - name: Troubleshoot dependency scanning + href: security/github-advanced-security-dependency-scanning-troubleshoot.md - name: Code Scanning for GitHub Advanced Security - href: security/github-advanced-security-code-scanning.md + items: + - name: Configure code scanning + href: security/github-advanced-security-code-scanning.md + - name: Using custom queries and query packs + href: security/github-advanced-security-code-scanning-queries.md + - name: Integrate third-party code scanning tools + href: security/github-advanced-security-code-scanning-third-party.md + - name: Troubleshoot code scanning + href: security/github-advanced-security-code-scanning-troubleshoot.md - name: Integrations items: - name: Azure Repos with Slack @@ -67,7 +78,7 @@ - name: REST API Reference items: - name: Git - href: /rest/api/vsts/git/?view=azure-devops-rest-5.0&preserve-view=true + href: /rest/api/vsts/git/?view=azure-devops-rest-5.0&preserve-view=true - name: TFVC href: /rest/api/vsts/tfvc/?view=azure-devops-rest-5.0&preserve-view=true - name: IDE Client Resources diff --git a/docs/service-hooks/authorize.md b/docs/service-hooks/authorize.md index 387b53c754a..e84559b1d8b 100644 --- a/docs/service-hooks/authorize.md +++ b/docs/service-hooks/authorize.md @@ -23,6 +23,14 @@ With OAuth, you grant a service the authorization to access your Azure DevOps re - The service that you authorize never has access to your Azure DevOps credentials. - Revoke any authorizations that you've granted to other services. +## Prerequisites + +| Category | Requirement | +|--------------|-------------| +| **Project access** | [Project member](../organizations/security/add-users-team-project.md). | +| **Access levels** | At least **Basic** access. | +|**Permissions**| Member of the [Project Collection Administrators group](../organizations/security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| + ## Authorize a service A typical authorization flow might go like this: diff --git a/docs/service-hooks/consumers.md b/docs/service-hooks/consumers.md index dcf1a85271b..93549692685 100644 --- a/docs/service-hooks/consumers.md +++ b/docs/service-hooks/consumers.md @@ -21,9 +21,7 @@ Select the consumer that you want to use in your subscription from the following - [Azure Service Bus](#azure-service-bus) - [Azure Storage](#azure-storage) -- [Campfire](#campfire) - [Jenkins](#jenkins) -- [Kato](#kato) - [Trello](#trello) - [Web Hooks](#webhooks) - [Zendesk](#zendesk) @@ -148,7 +146,7 @@ This action inserts a JSON string representation of the event to the specified A * Required: **Yes** * **queueName** * Queue name - * The lowercase-only name of the queue to be used within Azure storage. A queue by this name gets created if it doesn't already exist. + * The lowercase-only name of the queue to be used within Azure storage. A queue by this name gets created if it doesn't already exist. * Data type: **string** * Required: **Yes** * **visiTimeout** @@ -177,41 +175,6 @@ This action inserts a JSON string representation of the event to the specified A * Data type: **string** * Required: **No** - - -## Campfire - -Campfire is similar to instant messaging, but designed exclusively for groups. - -### Post a message to a room - -Post a message about the event to a room in Campfire. - -* Consumer ID: **campfire** -* Action ID: **postMessageToRoom** -* Supported events: **build.complete, git.push, tfvc.checkin, workitem.created, workitem.commented, workitem.updated** -* Settings: - * **accountName** - * Account name - * Account name like ```https://{account name}.campfirenow.com``` - * Data type: **string** - * Required: **Yes** - * **authToken** - * API authentication token - * API authentication token for the user that messages are posted from. You can get this token visiting the user profile page at Campfire. - * Data type: **string** - * Required: **Yes** - * **roomId** - * Room - * Room to post the message to. - * Data type: **number** - * Required: **Yes** - * **showDetails** - * Send a detailed message - * Post a short or detailed message about the event. - * Data type: **boolean** - * Required: **No** - ## Jenkins Jenkins is a continuous integration server, which allows building and testing software projects continuously. @@ -229,14 +192,9 @@ Triggers a build configured to use a Git repository using the [Jenkins Git Plugi * The base URL that hosts the Jenkins server * Data type: **uri** * Required: **Yes** - * **username** - * User name - * The Jenkins user name of a user who is allowed to trigger the build - * Data type: **string** - * Required: **Yes** - * **password** - * User API token (or password) - * The user's API token, which is available in the Jenkins user configuration page. The API token is new since version 1.426. For earlier versions of Jenkins the real user password must be specified. + * **basicAuthCredentials** [We recommend using service principals and managed identities in Azure DevOps](../integrate/get-started/authentication/service-principal-managed-identity.md). + * Basic authentication credentials + * Enter standard HTTP authentication credentials. Basic HTTP authentication send credentials in plain text (unencrypted) which means you should use a URL beginning with "https" to enable encryption of these credentials via secure transport layer (SSL) * Data type: **string** * Required: **Yes** @@ -253,16 +211,11 @@ Triggers a generic Jenkins build, invoking the Jenkins build URL. * The base URL that hosts the Jenkins server * Data type: **uri** * Required: **Yes** - * **username** - * User name - * The Jenkins user name of a user who is allowed to trigger the build - * Data type: **string** - * Required: **Yes** - * **password** - * User API token (or password) - * The user's API token, which is available in the Jenkins user configuration page. The API token is new since version 1.426. For earlier versions of Jenkins the real user password must be specified. + * **basicAuthCredentials** [We recommend using service principals and managed identities in Azure DevOps](../integrate/get-started/authentication/service-principal-managed-identity.md). + * Basic authentication credentials + * Enter credentials for standard HTTP authentication. Basic HTTP authentication sends credentials in plain text (unencrypted) which means you should use a URL beginning with "https" to enable encryption of these credentials via secure transport layer (SSL). * Data type: **string** - * Required: **Yes** + * Required: **No** * **buildName** * Build * The build name to trigger @@ -284,28 +237,6 @@ Triggers a generic Jenkins build, invoking the Jenkins build URL. * Data type: **string** * Required: **No** -## Kato - -Kato provides a messaging service for modern organizations. - -### Post event to room - -Posts an event to a Kato room - -* Consumer ID: **kato** -* Action ID: **postEventToRoom** -* Supported events: **build.complete, git.push, tfvc.checkin, workitem.created, workitem.commented, workitem.updated** -* Settings: - * **roomToken** - * Room token - * The token for interacting with a room using the Kato API - * Data type: **string** - * Required: **Yes** - * **roomName** - * Room name - * Room name as seen in Kato - * Data type: **string** - * Required: **No** ## Trello Provides integration with Trello. @@ -320,7 +251,7 @@ This action creates a card on an existing list in Trello. A card can represent a * Settings: * **userToken** * User token (Need one? [Get it now](https://go.microsoft.com/fwlink/?LinkID=390580).) - * Your user token provided by Trello. Select the link in the previously described action description to learn how to obtain this token. + * Your user token provided by Trello. To learn how to obtain this token, select the link in the previously described action description. * Data type: **string** * Required: **Yes** * **boardId** @@ -354,7 +285,7 @@ This action creates a list on an existing board in Trello. A list is used to org * Settings: * **userToken** * User token (need one? [Get it now](https://go.microsoft.com/fwlink/?LinkID=390580).) - * Your user token provided by Trello. Select the link in the previously described action description to learn how to obtain this token. + * Your user token provided by Trello. To learn how to obtain this token, select the link in the previously described action description. * Data type: **string** * Required: **Yes** * **boardId** @@ -382,24 +313,19 @@ This action posts a JSON object representation of the event to the specified URL * Settings: * **url** * URL - * The URL to which an HTTP POST gets sent. + * The URL to which an HTTP POST is sent. * Data type: **uri** * Required: **Yes** * **httpHeaders** * HTTP headers - * HTTP header keys and values separated by a colon(for example "Key1:value1") with each key-value-pair appearing on its own line of text. + * HTTP header keys and values separated by a colon (for example "Key1:value1") with each key-value-pair appearing on its own line of text. * Data type: **string** * Required: **No** - * **basicAuthUsername** - * Basic authentication username - * Enter a username for standard HTTP authentication. Basic HTTP authentication sends credentials in plain text (unencrypted) which means you should use a URL beginning with "https" to enable encryption of these credentials via secure transport layer (SSL). + * **basicAuthCredentials** [We recommend using service principals and managed identities in Azure DevOps](../integrate/get-started/authentication/service-principal-managed-identity.md). + * Basic authentication credentials + * Enter credentials for standard HTTP authentication. Basic HTTP authentication sends credentials in plain text (unencrypted) which means you should use a URL beginning with "https" to enable encryption of these credentials via secure transport layer (SSL). * Data type: **string** - * Required: **No** - * **basicAuthPassword** - * Basic authentication password - * Enter a password for standard HTTP authentication. Basic HTTP authentication sends credentials in plain text (unencrypted) which means you should use a URL beginning with "https" to enable encryption of these credentials via SSL. - * Data type: **string** - * Required: **No** + * Required: **Yes** * **resourceDetailsToSend** * Resource details to send * Control the resource fields to send @@ -415,7 +341,6 @@ This action posts a JSON object representation of the event to the specified URL * Control the detailed messages to send * Data type: **string** * Required: **No** - ## Zendesk Zendesk is a SaaS suite that offers help desk ticketing, issue tracking, and customer service support. diff --git a/docs/service-hooks/create-subscription.md b/docs/service-hooks/create-subscription.md index aef09014a24..07e752ff4b2 100644 --- a/docs/service-hooks/create-subscription.md +++ b/docs/service-hooks/create-subscription.md @@ -29,14 +29,12 @@ You can configure filters on your subscriptions to control which events trigger For a complete set of supported consumer services and actions, see the [Consumer reference](./consumers.md). - ## Prerequisites -To create a subscription, the following data is required: - -- Project ID. Use the [Project REST API](/rest/api/azure/devops/core/projects) to get the project ID. -- Event ID and settings. See the [Event reference](./events.md). -- Consumer and action IDs and settings. See the [Consumer reference](./consumers.md). +| Category | Requirements | +|--------------|-------------| +|**Project access**| [Project member](../organizations/security/add-users-team-project.md). | +|**Data**|- Project ID. Use the [Project REST API](/rest/api/azure/devops/core/projects) to get the project ID.
      - Event ID and settings. See the [Event reference](./events.md).
      - Consumer and action IDs and settings. See the [Consumer reference](./consumers.md).| ## Create the request @@ -70,8 +68,8 @@ See the following response to the request to create the subscription: ```js { - "id": "74aeeed0-bf5d-48dc-893f-f862b80987e9", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/hooks/subscriptions/74aeeed0-bf5d-48dc-893f-f862b80987e9", + "id": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/hooks/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e", "publisherId": "tfs", "eventType": "build.complete", "resourceVersion": "1.0", diff --git a/docs/service-hooks/events.md b/docs/service-hooks/events.md index ca078c77113..086c692f586 100644 --- a/docs/service-hooks/events.md +++ b/docs/service-hooks/events.md @@ -1,15 +1,16 @@ --- title: Service hooks events titleSuffix: Azure DevOps -description: Reference for service hook events. +description: Reference article for service hook events. ms.assetid: 1DC15791-5614-405E-8372-79A5ED6E66EE ms.custom: engagement-fy23 ms.subservice: azure-devops-service-hooks ms.topic: conceptual ms.author: chcomley author: chcomley +ai-usage: ai-assisted monikerRange: '<= azure-devops' -ms.date: 06/12/2023 +ms.date: 09/18/2024 --- # Service hooks events @@ -20,14 +21,12 @@ ms.date: 06/12/2023 * **Build and release** * [Build completed](#build.complete) - * [Release created](#ms.vss-release.release-created-event) - * [Release abandoned](#ms.vss-release.release-abandoned-event) - * [Release deployment approval completed](#ms.vss-release.deployment-approval-completed-event) - * [Release deployment approval pending](#ms.vss-release.deployment-approval-pending-event) - * [Release deployment completed](#ms.vss-release.deployment-completed-event) - * [Release deployment started](#ms.vss-release.deployment-started-event) - - + * [Release created](#ms.azure-devops-release.release-created-event) + * [Release abandoned](#ms.azure-devops-release.release-abandoned-event) + * [Release deployment approval completed](#ms.azure-devops-release.deployment-approval-completed-event) + * [Release deployment approval pending](#ms.azure-devops-release.deployment-approval-pending-event) + * [Release deployment completed](#ms.azure-devops-release.deployment-completed-event) + * [Release deployment started](#ms.azure-devops-release.deployment-started-event) ::: moniker range=">= azure-devops-2020 < azure-devops" @@ -42,7 +41,11 @@ ms.date: 06/12/2023 ::: moniker range="=azure-devops" * **Pipelines** - * [Job state changed](#job.statechanged) + * [Check updated](#check-updated) + * [Elastic agent pool resized](#elastic-agent-pool-resized) + * [Manual intervention pending](#manual-intervention-pending) + * [Project-level agent pool created](#project-level-agent-pool-created) + * [Project-level agent pool updated](#project-level-agent-pool-updated) * [Run state changed](#run.statechanged) * [Run stage state changed](#run.stagestatechanged) * [Run stage waiting for approval](#run.stageapprovalpending) @@ -55,8 +58,18 @@ ms.date: 06/12/2023 * [Code checked in](#tfvc.checkin) * [Code pushed](#git.push) * [Pull request created](#git.pullrequest.created) - * [Pull request merge commit created](#git.pullrequest.merged) + * [Pull request merge attempted](#git.pullrequest.merge.attempted) * [Pull request updated](#git.pullrequest.updated) + * [Pull request commented on](#git.pullrequest.commented-on) + * [Repository created](#repository-created) + * [Repository deleted](#repository-deleted) + * [Repository forked](#repository-forked) + * [Repository renamed](#repository-renamed) + * [Repository status changed](#repository-status-changed) + +* **Service Connections** + * [Service connection created](#service-connection-created) + * [Service connection updated](#service-connection-updated) * **Work items** * [Work item commented on](#workitem.commented) @@ -76,7 +89,7 @@ ms.date: 06/12/2023 Event: A build completes. -* Publisher ID: `tfs` +* Publisher ID: `azure-devops` * Event ID: `build.complete` * Resource Name: `build` @@ -93,37 +106,69 @@ Event: A build completes. #### Sample payload ```json { - "subscriptionId": "4f6e6328-0251-4814-a009-c01dfa368e3f", + "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e", "notificationId": 1, - "id": "33433986-7f56-4969-bfd4-3e59774c75ad", + "id": "00000000-0000-0000-0000-000000000000", "eventType": "build.complete", - "publisherId": "tfs", + "publisherId": "azure-devops", "message": { - "text": "Build 20221202.1 succeeded", - "html": "Build 20221202.1 succeeded", - "markdown": "Build [20221202.1](https://dev.azure.com/FabrikamFiber/web/build.aspx?pcguid=54d02617-2ebd-42b0-b1e2-257059c4c03d&builduri=vstfs%3a%2f%2f%2fBuild%2fBuild%2f2727068) succeeded" + "text": "Build 20241202.1 succeeded", + "html": "Build 20241202.1 succeeded", + "markdown": "Build [20241202.1](https://dev.azure.com/FabrikamFiber/web/build.aspx?pcguid=54d02617-2ebd-42b0-b1e2-257059c4c03d&builduri=azure-devops%3a%2f%2f%2fBuild%2fBuild%2f2727068) succeeded" }, "detailedMessage": { - "text": "Build 20221202.1 succeeded", - "html": "Build 20221202.1 succeeded", - "markdown": "Build [20221202.1](https://dev.azure.com/FabrikamFiber/web/build.aspx?pcguid=54d02617-2ebd-42b0-b1e2-257059c4c03d&builduri=vstfs%3a%2f%2f%2fBuild%2fBuild%2f2727068) succeeded" + "text": "Build 20241202.1 succeeded", + "html": "Build 20241202.1 succeeded", + "markdown": "Build [20241202.1](https://dev.azure.com/FabrikamFiber/web/build.aspx?pcguid=54d02617-2ebd-42b0-b1e2-257059c4c03d&builduri=azure-devops%3a%2f%2f%2fBuild%2fBuild%2f2727068) succeeded" + }, + "resource": { + "id": 2727068, + "buildNumber": "20241202.1", + "status": "completed", + "result": "succeeded", + "url": "https://dev.azure.com/FabrikamFiber/web/build.aspx?pcguid=54d02617-2ebd-42b0-b1e2-257059c4c03d&builduri=azure-devops%3a%2f%2f%2fBuild%2fBuild%2f2727068", + "definition": { + "id": 1, + "name": "FabrikamFiber CI" + }, + "project": { + "id": "54d02617-2ebd-42b0-b1e2-257059c4c03d", + "name": "FabrikamFiber" + } + }, + "createdDate": "2024-12-02T12:21:13.8866607Z" +}{ + "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e", + "notificationId": 1, + "id": "00000000-0000-0000-0000-000000000000", + "eventType": "build.complete", + "publisherId": "azure-devops", + "message": { + "text": "Build 20241202.1 succeeded", + "html": "Build 20241202.1 succeeded", + "markdown": "Build [20241202.1](https://dev.azure.com/FabrikamFiber/web/build.aspx?pcguid=54d02617-2ebd-42b0-b1e2-257059c4c03d&builduri=azure-devops%3a%2f%2f%2fBuild%2fBuild%2f2727068) succeeded" + }, + "detailedMessage": { + "text": "Build 20241202.1 succeeded", + "html": "Build 20241202.1 succeeded", + "markdown": "Build [20241202.1](https://dev.azure.com/FabrikamFiber/web/build.aspx?pcguid=54d02617-2ebd-42b0-b1e2-257059c4c03d&builduri=azure-devops%3a%2f%2f%2fBuild%2fBuild%2f2727068) succeeded" }, "resource": { "_links": { "self": { - "href": "https://dev.azure.com/FabrikamFiber/16dcfeeb-d8fd-495c-917b-fec46cb44fbb/_apis/build/Builds/2727068" + "href": "https://dev.azure.com/FabrikamFiber/00000000-0000-0000-0000-000000000000/_apis/build/Builds/2727068" }, "web": { - "href": "https://dev.azure.com/FabrikamFiber/16dcfeeb-d8fd-495c-917b-fec46cb44fbb/_build/results?buildId=2727068" + "href": "https://dev.azure.com/FabrikamFiber/00000000-0000-0000-0000-000000000000/_build/results?buildId=2727068" }, "sourceVersionDisplayUri": { - "href": "https://dev.azure.com/FabrikamFiber/16dcfeeb-d8fd-495c-917b-fec46cb44fbb/_apis/build/builds/2727068/sources" + "href": "https://dev.azure.com/FabrikamFiber/00000000-0000-0000-0000-000000000000/_apis/build/builds/2727068/sources" }, "timeline": { - "href": "https://dev.azure.com/FabrikamFiber/16dcfeeb-d8fd-495c-917b-fec46cb44fbb/_apis/build/builds/2727068/Timeline" + "href": "https://dev.azure.com/FabrikamFiber/00000000-0000-0000-0000-000000000000/_apis/build/builds/2727068/Timeline" }, "badge": { - "href": "https://dev.azure.com/FabrikamFiber/16dcfeeb-d8fd-495c-917b-fec46cb44fbb/_apis/build/status/4658" + "href": "https://dev.azure.com/FabrikamFiber/00000000-0000-0000-0000-000000000000/_apis/build/status/4658" } }, "properties": {}, @@ -136,46 +181,46 @@ Event: A build completes. ], "triggerInfo": {}, "id": 2727068, - "buildNumber": "20221202.1", + "buildNumber": "20241202.1", "status": "completed", "result": "succeeded", - "queueTime": "2022-12-02T12:18:45.7367977Z", - "startTime": "2022-12-02T12:18:56.6205723Z", - "finishTime": "2022-12-02T12:21:08.520904Z", - "url": "https://dev.azure.com/FabrikamFiber/16dcfeeb-d8fd-495c-917b-fec46cb44fbb/_apis/build/Builds/2727068", + "queueTime": "2024-12-02T12:18:45.7367977Z", + "startTime": "2024-12-02T12:18:56.6205723Z", + "finishTime": "2024-12-02T12:21:08.520904Z", + "url": "https://dev.azure.com/FabrikamFiber/00000000-0000-0000-0000-000000000000/_apis/build/Builds/2727068", "definition": { "drafts": [], "id": 4658, "name": "MainRepo (1)", - "url": "https://dev.azure.com/FabrikamFiber/16dcfeeb-d8fd-495c-917b-fec46cb44fbb/_apis/build/Definitions/4658?revision=1", - "uri": "vstfs:///Build/Definition/4658", + "url": "https://dev.azure.com/FabrikamFiber/00000000-0000-0000-0000-000000000000/_apis/build/Definitions/4658?revision=1", + "uri": "azure-devops:///Build/Definition/4658", "path": "\\", "type": "build", "queueStatus": "enabled", "revision": 1, "project": { - "id": "16dcfeeb-d8fd-495c-917b-fec46cb44fbb", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", "name": "FabrikamFiberChat", - "url": "https://dev.azure.com/FabrikamFiber/_apis/projects/16dcfeeb-d8fd-495c-917b-fec46cb44fbb", + "url": "https://dev.azure.com/FabrikamFiber/_apis/projects/00000000-0000-0000-0000-000000000000", "state": "wellFormed", "revision": 876, "visibility": "organization", - "lastUpdateTime": "2022-04-06T14:51:16.337Z" + "lastUpdateTime": "2024-04-06T14:51:16.337Z" } }, "buildNumberRevision": 1, "project": { - "id": "16dcfeeb-d8fd-495c-917b-fec46cb44fbb", + "id": "00000000-0000-0000-0000-000000000000", "name": "FabrikamFiberChat", - "url": "https://dev.azure.com/FabrikamFiber/_apis/projects/16dcfeeb-d8fd-495c-917b-fec46cb44fbb", + "url": "https://dev.azure.com/FabrikamFiber/_apis/projects/00000000-0000-0000-0000-000000000000", "state": "wellFormed", "revision": 876, "visibility": "organization", - "lastUpdateTime": "2022-04-06T14:51:16.337Z" + "lastUpdateTime": "2024-04-06T14:51:16.337Z" }, - "uri": "vstfs:///Build/Build/2727068", + "uri": "azure-devops:///Build/Build/2727068", "sourceBranch": "refs/heads/main", - "sourceVersion": "6e12f6141917f66a2964af55952ee33914d2d91f", + "sourceVersion": "00000000-0000-0000-0000-000000000000", "queue": { "id": 4799, "name": "Azure Pipelines", @@ -188,55 +233,55 @@ Event: A build completes. "priority": "normal", "reason": "manual", "requestedFor": { - "displayName": "Jack Fabrikam", + "displayName": "Fabrikam Fiber", "url": "https://spsprodwus22.vssps.visualstudio.com/A9985ce4a-0206-43df-a8ea-076ae68596a9/_apis/Identities/57a5d794-9773-6c32-bbb6-550585695119", "_links": { "avatar": { "href": "https://dev.azure.com/FabrikamFiber/_apis/GraphProfile/MemberAvatars/aad.NTdhNWQ3OTQtOTc3My03YzMyLQJiYjYtNTUwNTg1Njk1MTE5" } }, - "id": "57a5d794-9473-6c32-bbb6-550585695119", - "uniqueName": "jack@FabrikamFiber.com", + "id": "00000000-0000-0000-0000-000000000000", + "uniqueName": "chuck@FabrikamFiber.com", "imageUrl": "https://dev.azure.com/FabrikamFiber/_apis/GraphProfile/MemberAvatars/aad.NTdhNWQ3OTQtOTc1My03YzMyLWJiYjYtNTUwNTg1Njk1MTE5", "descriptor": "aad.NTdhNWQ3OTQtOTc6My03YzMyLWJiYjYtNTUwNTg1Njk1MTE5" }, "requestedBy": { - "displayName": "Jack Fabrikam", + "displayName": "Chuck Reinhart", "url": "https://spsprodwus22.vssps.visualstudio.com/A9985ce4a-0206-43df-a8ea-076ae68596a9/_apis/Identities/57a5d794-9773-6c32-bbb6-550585695119", "_links": { "avatar": { "href": "https://dev.azure.com/FabrikamFiber/_apis/GraphProfile/MemberAvatars/aad.NTdhNWQ3OTQtOTc3My03YzMyLQJiYjYtNTUwNTg1Njk1MTE5" } }, - "id": "57a5d794-9473-6c32-bbb6-550585695119", - "uniqueName": "jack@FabrikamFiber.com", + "id": "00000000-0000-0000-0000-000000000000", + "uniqueName": "chuck@FabrikamFiber.com", "imageUrl": "https://dev.azure.com/FabrikamFiber/_apis/GraphProfile/MemberAvatars/aad.NTdhNWQ3OTQtOTc1My03YzMyLWJiYjYtNTUwNTg1Njk1MTE5", "descriptor": "aad.NTdhNWQ3OTQtOTc6My03YzMyLWJiYjYtNTUwNTg1Njk1MTE5" }, - "lastChangedDate": "2022-12-02T12:21:08.96Z", + "lastChangedDate": "2024-12-02T12:21:08.96Z", "lastChangedBy": { "displayName": "Microsoft.VisualStudio.Services.TFS", - "url": "https://spsprodwus22.vssps.visualstudio.com/A9982ce4a-0206-43df-a8ea-076ae68596a9/_apis/Identities/00000002-0000-8888-8000-000000000000", + "url": "https://spsprodwus22.vssps.visualstudio.com/A9982ce4a-0206-43df-a8ea-076ae68596a9/_apis/Identities/00000000-0000-0000-0000-000000000000", "_links": { "avatar": { "href": "https://dev.azure.com/FabrikamFiber/_apis/GraphProfile/MemberAvatars/s2s.MDAwMDAwMDItMDAwMC02ODg4LTgwMDAtMDAwMDAwMDAwMDAwQDJjODk1OTA4LTA0ZTAtNDk1Mi04OWZkLTU0YjAwNDZkNjI4OA" } }, - "id": "00000002-0000-8888-8000-000000000000", - "uniqueName": "00000002-0000-8888-8000-000000000000@2c895908-04e0-4952-89fd-54b0046d6288", + "id": "00000000-0000-0000-0000-0000000000000-0000-0000-0000-000000000000", + "uniqueName": "00000000-0000-0000-0000-000000000000@00000000-0000-0000-0000-000000000000", "imageUrl": "https://dev.azure.com/FabrikamFiber/_apis/GraphProfile/MemberAvatars/s2s.MDAwMDAwMDItMDAwMC04ODg4LTgwMDAtMDAwMDAwMDAwMDAwQDJjODk1OTA4LTA2ZTAtNDk1Mi04OWZkLTU0YjAwNDZkNjI4OA", "descriptor": "s2s.MDAwMDAwMDItMDAwMC04ODg4LTgwMDAtMDAwMDAwMDAwMDAwQDJjODk1OTA4LTA2ZTAtNDk1Mi04OWZkLTU0YjAwNDZkNjI4OA" }, "orchestrationPlan": { - "planId": "cd96240e-881a-42e9-8135-89a4ad458a6d" + "planId": "00000000-0000-0000-0000-000000000000" }, "logs": { "id": 0, "type": "Container", - "url": "https://dev.azure.com/FabrikamFiber/16dcfeeb-d2fd-495c-917b-fec46cb44fbb/_apis/build/builds/2727068/logs" + "url": "https://dev.azure.com/FabrikamFiber//_apis/build/builds/00000000-0000-0000-0000-000000000000/logs" }, "repository": { - "id": "e5994ecb-b917-4d23-aa75-d52205c3c19b", + "id": "00000000-0000-0000-0000-000000000000", "type": "TfsGit", "name": "MainRepo", "url": "https://dev.azure.com/FabrikamFiber/FabrikamFiberChat/_git/FabrikamFiberChat", @@ -250,194 +295,71 @@ Event: A build completes. "resourceVersion": "2.0", "resourceContainers": { "collection": { - "id": "54d02617-2e2d-42b0-b1e2-257059c4c03d", + "id": "00000000-0000-0000-0000-000000000000", "baseUrl": "https://dev.azure.com/FabrikamFiber/" }, "account": { - "id": "998ace4a-0206-432f-a8ea-076ae68596a9", + "id": "00000000-0000-0000-0000-000000000000", "baseUrl": "https://dev.azure.com/FabrikamFiber/" }, "project": { - "id": "16dc2eeb-d8fd-495c-917b-fec46cb44fbb", + "id": "00000000-0000-0000-0000-000000000000", "baseUrl": "https://dev.azure.com/FabrikamFiber/" } }, - "createdDate": "2022-12-02T12:21:13.8866607Z" + "createdDate": "2024-12-02T12:21:13.8866607Z" } ``` - + ### Release abandoned -Event: A release was abandoned. +Event: A release is abandoned. * Publisher ID: `rm` -* Event ID: `ms.vss-release.release-abandoned-event` +* Event ID: `ms.azure-devops-release.release-abandoned-event` * Resource Name: `resource` #### Settings - * `releaseDefinitionId`: Filter events to include only completed deployments for the specified pipeline +* `releaseDefinitionId`: Filter events to include only completed deployments for the specified pipeline #### Sample payload ```json { - "id": "b0497ad3-50c9-4722-96da-a8fa5b80d77f", - "eventType": "ms.vss-release.release-abandoned-event", + "id": "00000000-0000-0000-0000-000000000000", + "eventType": "ms.azure-devops-release.release-abandoned-event", "publisherId": "rm", "scope": "all", - "message": { - "text": "Release Release-1 abandoned.", - "html": "Release Release-1 abandoned.", - "markdown": "Release [Release-1](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/5) abandoned." - }, - "detailedMessage": { - "text": "Release Release-1 from release pipeline Fabrikam.CD abandoned.\\r\\nRelease description: QFE release for fixing title\\r\\nContinuousIntegration Requested for Chuck Reinhart\\r\\n
    • Build: fabrikam.Bd.2016.04.10 & 2 more<\\li>", - "html": "Release Release-1 from Fabrikam.CD release pipeline abandoned.\\r\\n
    • Release description: QFE release for fixing title
      • \\r\\n
    • ContinuousIntegration Requested for Chuck Reinhart
      • \\r\\n
    • Build: fabrikam.Bd.2016.04.10 & 2 more <\\li>", - "markdown": "Release [Release-1](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/5) from release pipeline [Fabrikam.CD](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releasedefinitions/1) abandoned.\\r\\n
    • Release description: QFE release for fixing title
      • \\r\\n
    • ContinuousIntegration Requested for Chuck Reinhart
      • \\r\\n
    • Build: fabrikam.Bd.2016.04.10 & 2 more<\\li>" - }, "resource": { "release": { - "id": 4, - "name": "Release-1", + "id": "release-id", + "name": "release-name", "status": "abandoned", - "createdOn": "2016-01-21T08:19:17.26Z", - "modifiedOn": "2016-01-21T08:19:17.26Z", - "modifiedBy": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", - "displayName": "Chuck Reinhart" - }, - "createdBy": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", - "displayName": "Chuck Reinhart" - }, - "environments": [ - { - "id": 5, - "releaseId": 0, - "name": "Dev", - "status": "succeeded", - "variables": {}, - "preDeployApprovals": [], - "postDeployApprovals": [], - "preApprovalsSnapshot": { - "approvals": [], - "approvalOptions": { - "requiredApproverCount": 0, - "releaseCreatorCanBeApprover": true - } - }, - "postApprovalsSnapshot": { - "approvals": [] - }, - "deploySteps": [], - "rank": 1, - "definitionEnvironmentId": 1, - "queueId": 1, - "environmentOptions": { - "emailNotificationType": "OnlyOnFailure", - "emailRecipients": "release.environment.owner;release.creator", - "skipArtifactsDownload": false, - "timeoutInMinutes": 0, - "enableAccessToken": false - }, - "demands": [], - "conditions": [], - "modifiedOn": "2016-01-21T08:19:17.26Z", - "workflowTasks": [ - { - "taskId": "00000000-0000-0000-0000-000000000000", - "version": "*", - "name": "Deploy Website to Azure", - "enabled": true, - "alwaysRun": false, - "continueOnError": false, - "timeoutInMinutes": 0, - "definitionType": null, - "inputs": { - "ConnectedServiceName": "b460b0f8-fe23-4dc2-a99c-fd8b0633fe1c", - "WebSiteName": "$(webAppName)", - "WebSiteLocation": "Southeast Asia", - "Slot": "", - "Package": "$(System.DefaultWorkingDirectory)\\**\\*.zip" - } - } - ], - "deployPhasesSnapshot": [], - "owner": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", - "displayName": "Chuck Reinhart" - }, - "scheduledDeploymentTime": "2016-01-21T08:19:17.26Z", - "schedules": [], - "release": { - "id": 5, - "name": "Release-1", - "url": "http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/5" - } - } - ], - "variables": {}, - "artifacts": [ - { - "sourceId": "31419848-1780-4137-b7e3-62092e986fd6:1", - "type": "Build", - "alias": "Fabrikam.CI", - "definitionReference": { - "Definition": { - "id": "1", - "name": "Fabrikam.CI" - }, - "Project": { - "id": "31419848-1780-4137-b7e3-62092e986fd6", - "name": "Fabrikam" - } - }, - "isPrimary": true - } - ], "releaseDefinition": { - "id": 1, - "name": "Fabrikam.CD", - "url": "http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1" + "id": "release-definition-id", + "name": "release-definition-name" }, - "description": "QFE release for fixing title", - "reason": "continuousIntegration", - "releaseNameFormat": "Release-$(rev:r)", - "keepForever": false, - "definitionSnapshotRevision": 0, - "comment": "", - "logsContainerUrl": null, - "_links": {} - }, - "project": { - "id": "00000000-0000-0000-0000-000000000000", - "name": "Fabrikam" - } - }, - "resourceVersion": "3.0-preview.1", - "resourceContainers": { - "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" - }, - "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "project": { + "id": "project-id", + "name": "project-name" + } } }, - "createdDate": "2016-09-19T13:03:27.784654Z" + "createdDate": "2024-12-02T12:21:13.8866607Z" } ``` - + ### Release created -Event: A release was created. +Event: A release is created. * Publisher ID: `rm` -* Event ID: `ms.vss-release.release-created-event` +* Event ID: `ms.azure-devops-release.release-created-event` * Resource Name: `resource` #### Settings @@ -448,19 +370,19 @@ Event: A release was created. ```json { - "id": "d4d69db4-18d4-413e-bc43-07f56b531160", - "eventType": "ms.vss-release.release-created-event", + "id": "00000000-0000-0000-0000-000000000000d4d69db4-18d4-413e-bc43-07f56b531160", + "eventType": "ms.azure-devops-release.release-created-event", "publisherId": "rm", "scope": "all", "message": { "text": "Release Release-1 created.", - "html": "Release-1 created.", - "markdown": "Release [Release-1](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/5) created." + "html": "Release-1 created.", + "markdown": "Release [Release-1](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/5) created." }, "detailedMessage": { - "text": "Release Release-1 created from release pipeline Fabrikam.CD.\\r\\nRelease description: QFE release for fixing title\\r\\nContinuousIntegration Requested for Chuck Reinhart\\r\\n
    • Build: fabrikam.Bd.2016.04.10 & 2 more<\\li>", - "html": "Release Release-1 created from release pipeline Fabrikam.CD.\\r\\n
    • Release description: QFE release for fixing title
      • \\r\\n
    • ContinuousIntegration Requested for Chuck Reinhart
      • \\r\\n
    • Build: fabrikam.Bd.2016.04.10 & 2 more<\\li>", - "markdown": "Release [Release-1](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/5) created from release pipeline [Fabrikam.CD](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releasedefinitions/1).\\r\\n
    • Release description: QFE release for fixing title
      • \\r\\n
    • ContinuousIntegrationRequested for Chuck Reinhart
      • \\r\\n
    • Build: fabrikam.Bd.2016.04.10 & 2 more<\\li>" + "text": "Release Release-1 created from release pipeline Fabrikam.CD.\\r\\nRelease description: QFE release for fixing title\\r\\nContinuousIntegration Requested for Chuck Reinhart\\r\\n- Build: fabrikam.Bd.2016.04.10 & 2 more<\\li>", + "html": "Release Release-1 created from release pipeline Fabrikam.CD.\\r\\n- Release description: QFE release for fixing title
      \\r\\n- ContinuousIntegration Requested for Chuck Reinhart
      \\r\\n- Build: fabrikam.Bd.2016.04.10 & 2 more<\\li>", + "markdown": "Release [Release-1](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/5) created from release pipeline [Fabrikam.CD](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releasedefinitions/1).\\r\\n- Release description: QFE release for fixing title
      \\r\\n- ContinuousIntegrationRequested for Chuck Reinhart
      \\r\\n- Build: fabrikam.Bd.2016.04.10 & 2 more<\\li>" }, "resource": { "release": { @@ -470,11 +392,11 @@ Event: A release was created. "createdOn": "2016-01-21T08:19:17.26Z", "modifiedOn": "2016-01-21T08:19:17.26Z", "modifiedBy": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "Chuck Reinhart" }, "createdBy": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "Chuck Reinhart" }, "environments": [ @@ -531,7 +453,7 @@ Event: A release was created. ], "deployPhasesSnapshot": [], "owner": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "Chuck Reinhart" }, "scheduledDeploymentTime": "2016-01-21T08:19:17.26Z", @@ -539,7 +461,7 @@ Event: A release was created. "release": { "id": 5, "name": "Release-1", - "url": "http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/5" + "url": "http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/5" } } ], @@ -551,11 +473,11 @@ Event: A release was created. "alias": "Fabrikam.CI", "definitionReference": { "Definition": { - "id": "1", + "id": "00000000-0000-0000-0000-0000000000001", "name": "Fabrikam.CI" }, "Project": { - "id": "31419848-1780-4137-b7e3-62092e986fd6", + "id": "00000000-0000-0000-0000-00000000000031419848-1780-4137-b7e3-62092e986fd6", "name": "Fabrikam" } }, @@ -565,7 +487,7 @@ Event: A release was created. "releaseDefinition": { "id": 1, "name": "Fabrikam.CD", - "url": "http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1" + "url": "http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1" }, "description": "QFE release for fixing title", "reason": "continuousIntegration", @@ -577,31 +499,31 @@ Event: A release was created. "_links": {} }, "project": { - "id": "00000000-0000-0000-0000-000000000000", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", "name": "Fabrikam" } }, "resourceVersion": "3.0-preview.1", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:27.6570261Z" + "createdDate": "2024-09-19T13:03:27.6570261Z" } ``` - + ### Release deployment approval completed Event: A deployment approval is completed. * Publisher ID: `rm` -* Event ID: `ms.vss-release.deployment-approval-completed-event` +* Event ID: `ms.azure-devops-release.deployment-approval-completed-event` * Resource Name: `resource` #### Settings @@ -612,7 +534,7 @@ Event: A deployment approval is completed. * `4` - Rejected * `releaseApprovalType`: Filter events to include only deployments requesting an approval of the specified type * Valid values: - * `1` - Pre-deployment + * `1` - Predeployment * `2` - Post-deployment * `releaseEnvironmentId`: Filter events to include only completed deployments for the specified environment * `releaseDefinitionId`: Filter events to include only completed deployments for the specified definition @@ -621,202 +543,74 @@ Event: A deployment approval is completed. ```json { - "id": "106acb39-c61e-4efd-995e-a9f5e71ba3cd", - "eventType": "ms.vss-release.deployment-approval-completed-event", + "id": "00000000-0000-0000-0000-000000000000106acb39-c61e-4efd-995e-a9f5e71ba3cd", + "eventType": "ms.azure-devops-release.deployment-approval-completed-event", "publisherId": "rm", "scope": "all", "message": { "text": "Pre Deployment approval for deployment of release Release-1 on environment Dev Succeeded.", - "html": "Pre Deployment approval for release Release-1 on environment Dev Succeeded.", - "markdown": "Pre Deployment approval for deployment of release [Release-1](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1) on environment [Dev](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1) Succeeded." + "html": "Pre Deployment approval for release Release-1 on environment Dev Succeeded.", + "markdown": "Pre Deployment approval for deployment of release [Release-1](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1) on environment [Dev](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1) Succeeded." }, "detailedMessage": { - "text": "Pre Deployment approval for release Release-1 on environment Dev Succeeded.\\r\\nApprover: Chuck Reinhart\\r\\nComment: Approving", - "html": "Pre Deployment approval for release Release-1 on environment Dev Succeeded.\\r\\nApprover: Chuck Reinhart\\r\\nComment: Approving", - "markdown": "Pre Deployment approval for release [Release-1](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1) on environment [Dev](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1) Succeeded.\\r\\nApprover: Chuck Reinhart\\r\\nComment: Approving" + "text": "Pre Deployment approval for release Release-1 on environment Dev Succeeded.\r\nApprover: Chuck Reinhart\r\nComment: Approving", + "html": "Pre Deployment approval for release Release-1 on environment Dev Succeeded.
      Approver: Chuck Reinhart
      Comment: Approving", + "markdown": "Pre Deployment approval for release [Release-1](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1) on environment [Dev](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1) Succeeded.\r\nApprover: Chuck Reinhart\r\nComment: Approving" }, "resource": { "approval": { - "id": 0, - "revision": 0, - "approver": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", - "displayName": "Chuck Reinhart" - }, - "approvedBy": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", - "displayName": "Chuck Reinhart" - }, + "id": 1, + "revision": 1, "approvalType": "preDeploy", - "createdOn": "2016-01-21T08:19:17.26Z", - "modifiedOn": "2016-01-21T08:19:17.26Z", "status": "approved", - "comments": "", + "createdOn": "2024-12-02T12:21:13.8866607Z", + "modifiedOn": "2024-12-02T12:21:13.8866607Z", + "comments": "Approving", "isAutomated": false, - "isNotificationOn": true, + "isNotificationOn": false, "trialNumber": 1, - "attempt": 0, - "rank": 1, - "release": { - "id": 1, - "name": "Release-1" - }, - "releaseDefinition": { - "id": 1, - "name": "Fabrikam.CD", - "url": "http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1" - }, - "releaseEnvironment": { - "id": 8, - "name": "Dev" + "attempt": 1, + "approver": { + "displayName": "Chuck Reinhart", + "id": "00000000-0000-0000-0000-000000000000" } }, + "environment": { + "id": 1, + "name": "Dev" + }, "release": { "id": 1, "name": "Release-1", - "status": "active", - "createdOn": "2016-01-21T08:19:17.26Z", - "modifiedOn": "2016-01-21T08:19:17.26Z", - "modifiedBy": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", - "displayName": "Chuck Reinhart" - }, - "createdBy": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", - "displayName": "Chuck Reinhart" - }, - "environments": [ - { - "id": 1, - "releaseId": 0, - "name": "Dev", - "status": "succeeded", - "variables": {}, - "preDeployApprovals": [], - "postDeployApprovals": [], - "preApprovalsSnapshot": { - "approvals": [], - "approvalOptions": { - "requiredApproverCount": 0, - "releaseCreatorCanBeApprover": true - } - }, - "postApprovalsSnapshot": { - "approvals": [] - }, - "deploySteps": [], - "rank": 1, - "definitionEnvironmentId": 1, - "queueId": 1, - "environmentOptions": { - "emailNotificationType": "OnlyOnFailure", - "emailRecipients": "release.environment.owner;release.creator", - "skipArtifactsDownload": false, - "timeoutInMinutes": 0, - "enableAccessToken": false - }, - "demands": [], - "conditions": [], - "modifiedOn": "2016-01-21T08:19:17.26Z", - "workflowTasks": [ - { - "taskId": "00000000-0000-0000-0000-000000000000", - "version": "*", - "name": "Deploy Website to Azure", - "enabled": true, - "alwaysRun": false, - "continueOnError": false, - "timeoutInMinutes": 0, - "definitionType": null, - "inputs": { - "ConnectedServiceName": "b460b0f8-fe23-4dc2-a99c-fd8b0633fe1c", - "WebSiteName": "$(webAppName)", - "WebSiteLocation": "Southeast Asia", - "Slot": "", - "Package": "$(System.DefaultWorkingDirectory)\\**\\*.zip" - } - } - ], - "deployPhasesSnapshot": [], - "owner": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", - "displayName": "Chuck Reinhart" - }, - "scheduledDeploymentTime": "2016-01-21T08:19:17.26Z", - "schedules": [], - "release": { - "id": 1, - "name": "Release-1", - "url": "http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1" - } - } - ], - "variables": {}, - "artifacts": [ - { - "sourceId": "31419848-1780-4137-b7e3-62092e986fd6:1", - "type": "Build", - "alias": "Fabrikam.CI", - "definitionReference": { - "Definition": { - "id": "1", - "name": "Fabrikam.CI" - }, - "Project": { - "id": "31419848-1780-4137-b7e3-62092e986fd6", - "name": "Fabrikam" - } - }, - "isPrimary": true - } - ], "releaseDefinition": { "id": 1, - "name": "Fabrikam.CD", - "url": "http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1" + "name": "Release Definition" }, - "description": "QFE release for fixing title", - "reason": "continuousIntegration", - "releaseNameFormat": "Release-$(rev:r)", - "keepForever": false, - "definitionSnapshotRevision": 0, - "comment": "", - "logsContainerUrl": null, - "_links": {} - }, - "project": { - "id": "00000000-0000-0000-0000-000000000000", - "name": "Fabrikam" - } - }, - "resourceVersion": "3.0-preview.1", - "resourceContainers": { - "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" - }, - "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "project": { + "id": "project-id", + "name": "project-name" + } } }, - "createdDate": "2016-09-19T13:03:28.1594606Z" + "createdDate": "2024-12-02T12:21:13.8866607Z" } ``` - + ### Release deployment approval pending Event: A deployment approval is requested. * Publisher ID: `rm` -* Event ID: `ms.vss-release.deployment-approval-pending-event` +* Event ID: `ms.azure-devops-release.deployment-approval-pending-event` * Resource Name: `resource` #### Settings * `releaseApprovalType`: Filter events to include only deployments requesting an approval of the specified type * Valid values: - * `1` - Pre-deployment + * `1` - Predeployment * `2` - Post-deployment * `releaseEnvironmentId`: Filter events to include only completed deployments for the specified environment * `releaseDefinitionId`: Filter events to include only completed deployments for the specified pipeline @@ -825,26 +619,76 @@ Event: A deployment approval is requested. ```json { - "id": "a73e7272-e96d-4249-93ac-7404eacd6801", - "eventType": "ms.vss-release.deployment-approval-pending-event", + "id": "00000000-0000-0000-0000-000000000000a73e7272-e96d-4249-93ac-7404eacd6801", + "eventType": "ms.azure-devops-release.deployment-approval-pending-event", + "publisherId": "rm", + "scope": "all", + "message": { + "text": "Pre deployment approval pending for release Release-1 on environment Dev.", + "html": "Pre deployment approval pending for release Release-1 on environment Dev.", + "markdown": "Pre deployment approval pending for release [Release-1](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1) on environment [Dev](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apps/hub/ms.azure-devops-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=8&definitionId=1)." + }, + "detailedMessage": { + "text": "Pre deployment approval pending for release Release-1 on environment Dev.\r\nPending on: Chuck Reinhart\r\nPending since: 09 May 2016 12:09:29 (UTC)", + "html": "Pre deployment approval pending for release Release-1 on environment Dev.
      Pending on: Chuck Reinhart
      Pending since: 09 May 2016 12:09:29 (UTC)", + "markdown": "Pre deployment approval pending for release [Release-1](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1) on environment [Dev](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apps/hub/ms.azure-devops-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=8&definitionId=1).\r\nPending on: Chuck Reinhart\r\nPending since: 09 May 2016 12:09:29 (UTC)" + }, + "resource": { + "approval": { + "id": 1, + "revision": 1, + "approvalType": "preDeploy", + "status": "pending", + "createdOn": "2016-05-09T12:09:29Z", + "modifiedOn": "2016-05-09T12:09:29Z", + "isAutomated": false, + "isNotificationOn": false, + "trialNumber": 1, + "attempt": 1, + "approver": { + "displayName": "Chuck Reinhart", + "id": "00000000-0000-0000-0000-000000000000" + } + }, + "environment": { + "id": 8, + "name": "Dev" + }, + "release": { + "id": 1, + "name": "Release-1", + "releaseDefinition": { + "id": 1, + "name": "Release Definition" + }, + "project": { + "id": "project-id", + "name": "project-name" + } + } + }, + "createdDate": "2016-05-09T12:09:29Z" +}{ + "id": "00000000-0000-0000-0000-000000000000a73e7272-e96d-4249-93ac-7404eacd6801", + "eventType": "ms.azure-devops-release.deployment-approval-pending-event", "publisherId": "rm", "scope": "all", "message": { "text": "Pre deployment approval pending for release Release-1 on environment Dev.", - "html": "Pre deployment approval pending for release Release-1 on environment Dev.", - "markdown": "Pre deployment approval pending for release [Release-1](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1) on environment [Dev](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apps/hub/ms.vss-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=8&definitionId=1)." + "html": "Pre deployment approval pending for release Release-1 on environment Dev.", + "markdown": "Pre deployment approval pending for release [Release-1](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1) on environment [Dev](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apps/hub/ms.azure-devops-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=8&definitionId=1)." }, "detailedMessage": { "text": "Pre deployment approval pending for release Release-1 on environment Dev.\\r\\nPending on: Chuck Reinhart\\r\\nPending since: 09 May 2016 12:09:29 (UTC)", - "html": "Pre deployment approval pending of release Release-1 on environment Dev.\\r\\nPending on: Chuck Reinhart\\r\\nPending since: 09 May 2016 12:09:29 (UTC)", - "markdown": "Pre deployment approval pending for release [Release-1](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1) on environment [Dev](http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apps/hub/ms.vss-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=8&definitionId=1).\\r\\nPending on: Chuck Reinhart\\r\\nPending since: 09 May 2016 12:09:29 (UTC)" + "html": "Pre deployment approval pending of release Release-1 on environment Dev.\\r\\nPending on: Chuck Reinhart\\r\\nPending since: 09 May 2016 12:09:29 (UTC)", + "markdown": "Pre deployment approval pending for release [Release-1](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1) on environment [Dev](http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apps/hub/ms.azure-devops-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=8&definitionId=1).\\r\\nPending on: Chuck Reinhart\\r\\nPending since: 09 May 2016 12:09:29 (UTC)" }, "resource": { "approval": { "id": 0, "revision": 0, "approver": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "Chuck Reinhart" }, "approvalType": "preDeploy", @@ -864,7 +708,7 @@ Event: A deployment approval is requested. "releaseDefinition": { "id": 1, "name": "Fabrikam.CD", - "url": "http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1" + "url": "http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1" }, "releaseEnvironment": { "id": 8, @@ -878,11 +722,11 @@ Event: A deployment approval is requested. "createdOn": "2016-01-21T08:19:17.26Z", "modifiedOn": "2016-01-21T08:19:17.26Z", "modifiedBy": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "Chuck Reinhart" }, "createdBy": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "Chuck Reinhart" }, "environments": [ @@ -939,7 +783,7 @@ Event: A deployment approval is requested. ], "deployPhasesSnapshot": [], "owner": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "Chuck Reinhart" }, "scheduledDeploymentTime": "2016-01-21T08:19:17.26Z", @@ -947,7 +791,7 @@ Event: A deployment approval is requested. "release": { "id": 1, "name": "Release-1", - "url": "http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1" + "url": "http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1" } } ], @@ -959,11 +803,11 @@ Event: A deployment approval is requested. "alias": "Fabrikam.CI", "definitionReference": { "Definition": { - "id": "1", + "id": "00000000-0000-0000-0000-0000000000001", "name": "Fabrikam.CI" }, "Project": { - "id": "31419848-1780-4137-b7e3-62092e986fd6", + "id": "00000000-0000-0000-0000-00000000000031419848-1780-4137-b7e3-62092e986fd6", "name": "Fabrikam" } }, @@ -973,7 +817,7 @@ Event: A deployment approval is requested. "releaseDefinition": { "id": 1, "name": "Fabrikam.CD", - "url": "http://vsrm.dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1" + "url": "http://dev.azure.com/fabfiber/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/definitions/1" }, "description": "QFE release for fixing title", "reason": "continuousIntegration", @@ -985,31 +829,31 @@ Event: A deployment approval is requested. "_links": {} }, "project": { - "id": "00000000-0000-0000-0000-000000000000", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", "name": "Fabrikam" } }, "resourceVersion": "3.0-preview.1", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:28.0320509Z" + "createdDate": "2024-09-19T13:03:28.0320509Z" } ``` - + ### Release deployment completed Event: A deployment completed. * Publisher ID: `rm` -* Event ID: `ms.vss-release.deployment-completed-event` +* Event ID: `ms.azure-devops-release.deployment-completed-event` * Resource Name: `resource` #### Settings @@ -1027,111 +871,54 @@ Event: A deployment completed. ```json { - "id": "c3e52c57-187a-45c4-abe2-184a48291bad", - "eventType": "ms.vss-release.deployment-completed-event", + "id": "00000000-0000-0000-0000-000000000000c3e52c57-187a-45c4-abe2-184a48291bad", + "eventType": "ms.azure-devops-release.deployment-completed-event", "publisherId": "rm", "scope": "all", "message": { "text": "Deployment of release Release-1 on environment Dev Succeeded.", - "html": "Deployment on environment Dev Succeeded.", - "markdown": "Deployment on environment [Dev](http://fabfiber.vsrm.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apps/hub/ms.vss-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=8&definitionId=1) Succeeded." + "html": "Deployment on environment Dev Succeeded.", + "markdown": "Deployment on environment [Dev](http://fabfiber.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apps/hub/ms.azure-devops-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=8&definitionId=1) Succeeded." }, "detailedMessage": { "text": "Deployment of release Release-1 on environment Dev Succeeded. Time to deploy: 0.11 minutes.", - "html": "Deployment on environment Dev Succeeded. Time to deploy: 0.11 minutes.", - "markdown": "Deployment on environment [Dev](http://fabfiber.vsrm.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apps/hub/ms.vss-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=8&definitionId=1) Succeeded. Time to deploy: 0.11 minutes." + "html": "Deployment on environment Dev Succeeded. Time to deploy: 0.11 minutes.", + "markdown": "Deployment on environment [Dev](http://fabfiber.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apps/hub/ms.azure-devops-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=8&definitionId=1) Succeeded. Time to deploy: 0.11 minutes." }, "resource": { - "environment": { - "id": 5, - "releaseId": 0, - "name": "Dev", + "deployment": { + "id": 1, "status": "succeeded", - "variables": {}, - "preDeployApprovals": [], - "postDeployApprovals": [], - "preApprovalsSnapshot": { - "approvals": [], - "approvalOptions": { - "requiredApproverCount": 0, - "releaseCreatorCanBeApprover": true - } - }, - "postApprovalsSnapshot": { - "approvals": [] - }, - "deploySteps": [], - "rank": 1, - "definitionEnvironmentId": 1, - "queueId": 1, - "environmentOptions": { - "emailNotificationType": "OnlyOnFailure", - "emailRecipients": "release.environment.owner;release.creator", - "skipArtifactsDownload": false, - "timeoutInMinutes": 0, - "enableAccessToken": false - }, - "demands": [], - "conditions": [], - "modifiedOn": "2016-01-21T08:19:17.26Z", - "workflowTasks": [ - { - "taskId": "00000000-0000-0000-0000-000000000000", - "version": "*", - "name": "Deploy Website to Azure", - "enabled": true, - "alwaysRun": false, - "continueOnError": false, - "timeoutInMinutes": 0, - "definitionType": null, - "inputs": { - "ConnectedServiceName": "b460b0f8-fe23-4dc2-a99c-fd8b0633fe1c", - "WebSiteName": "$(webAppName)", - "WebSiteLocation": "Southeast Asia", - "Slot": "", - "Package": "$(System.DefaultWorkingDirectory)\\**\\*.zip" - } - } - ], - "deployPhasesSnapshot": [], - "owner": { - "id": "4247c988-4060-4712-abca-ff44681dd78a", - "displayName": "Chuck Reinhart" - }, - "scheduledDeploymentTime": "2016-01-21T08:19:17.26Z", - "schedules": [], "release": { "id": 1, "name": "Release-1", - "url": "http://fabfiber.vsrm.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/Release/releases/1" + "releaseDefinition": { + "id": 1, + "name": "Release Definition" + }, + "project": { + "id": "project-id", + "name": "project-name" + } + }, + "environment": { + "id": 8, + "name": "Dev" } - }, - "project": { - "id": "00000000-0000-0000-0000-000000000000", - "name": "Fabrikam" - } - }, - "resourceVersion": "3.0-preview.1", - "resourceContainers": { - "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" - }, - "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" } }, - "createdDate": "2016-09-19T13:03:28.5345098Z" + "createdDate": "2024-12-02T12:21:13.8866607Z" } ``` - + ### Release deployment started Event: A deployment started. * Publisher ID: `rm` -* Event ID: `ms.vss-release.deployment-started-event` +* Event ID: `ms.azure-devops-release.deployment-started-event` * Resource Name: `resource` #### Settings @@ -1143,18 +930,18 @@ Event: A deployment started. ```json { - "id": "1f04688d-98bb-4206-850f-43389f4c8cb4", - "eventType": "ms.vss-release.deployment-started-event", + "id": "00000000-0000-0000-0000-0000000000001f04688d-98bb-4206-850f-43389f4c8cb4", + "eventType": "ms.azure-devops-release.deployment-started-event", "publisherId": "rm", "message": { "text": "Deployment of release Release-5 to stage Dev started.", - "html": "Deployment on stage Dev started.", - "markdown": "Deployment on stage [Dev](https://fabfiber.visualstudio.com/Fabrikam-Fiber-Git/_apps/hub/ms.vss-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=1&definitionId=4) started." + "html": "Deployment on stage Dev started.", + "markdown": "Deployment on stage [Dev](https://fabfiber.visualstudio.com/Fabrikam-Fiber-Git/_apps/hub/ms.azure-devops-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=1&definitionId=4) started." }, "detailedMessage": { "text": "Deployment of release Release-5 on stage Dev started.\r\nTrigger: Manual", - "html": "Deployment on stage http://fabfiber.visualstudio.com/Fabrikam-Fiber-Git/_apps/hub/ms.vss-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=1&definitionId=4 started.
      Trigger: Manual", - "markdown": "Deployment on stage [Release-1](https://fabfiber.visualstudio.com/Fabrikam-Fiber-Git/_apps/hub/ms.vss-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=1&definitionId=4) started.\r\nTrigger: Dev" + "html": "Deployment on stage http://fabfiber.visualstudio.com/Fabrikam-Fiber-Git/_apps/hub/ms.azure-devops-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=1&definitionId=4 started.
      Trigger: Manual", + "markdown": "Deployment on stage [Release-1](https://fabfiber.visualstudio.com/Fabrikam-Fiber-Git/_apps/hub/ms.azure-devops-releaseManagement-web.hub-explorer?_a=environment-summary&definitionEnvironmentId=1&definitionId=4) started.\r\nTrigger: Dev" }, "resource": { "environment": { @@ -1202,7 +989,7 @@ Event: A deployment started. "deployPhasesSnapshot": [], "owner": { "displayName": "Chuck Reinhart", - "id": "4247c988-4060-4712-abca-ff44681dd78a" + "id": "00000000-0000-0000-0000-000000000000" }, "scheduledDeploymentTime": "2016-01-21T08:19:17.26Z", "schedules": [], @@ -1256,107 +1043,218 @@ Event: A deployment started. "projectReference": null }, "project": { - "id": "00000000-0000-0000-0000-000000000000", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", "name": "Fabrikam" } }, "resourceVersion": "3.0-preview.1", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, "createdDate": "2019-10-10T17:49:39.157Z" } ``` -::: moniker range="=azure-devops" -## Pipelines +::: moniker range=">= azure-devops-2020" - +## Pipeline -### Job state changed + -Event: Overall statuses of a job changed. A job within a run has transitioned to skipped, running or completed. +### Check updated -* Publisher ID: `pipelines` -* Event ID: `ms.vss-pipelines.job-state-changed-event` -* Resource Name: `resource` +Event: A check is updated. + +* Publisher ID: `azure-devops` +* Event ID: `check.updated` +* Resource Name: `check` #### Settings - * `PipelineId`: Filter to include only events for the specified pipeline - * `state`: Filter events based on the new state of the job - * Valid values: - * `Skipped` - * `Running` - * `Completed` + +* `project`: Filter events to include only checks updated within the specified project. +* `checkType`: Filter events to include only checks of the specified type. +* `status`: Filter events to include only checks with the specified status. #### Sample payload + ```json { - "subscriptionId": "8d91ad83-1db5-4d43-8c5a-9bb2239644b1", - "notificationId": 29, - "id": "fcad4962-f3a6-4fbf-9653-2058c304503f", - "eventType": "ms.vss-pipelines.job-state-changed-event", - "publisherId": "pipelines", - "message": - { - "text": "Run 20221121.5 stage Build job Compile succeeded.", - "html": "Run 20221121.5 stage Build job Compile succeeded.", - "markdown": "Run 20221121.5 stage Build job [Compile](https://dev.azure.com/fabrikamfiber/fabrikamfiber-viva/_build/results?buildId=2710088) succeeded." - }, - "detailedMessage": - { - "text": "Run 20221121.5 stage Build job Compile succeeded.", - "html": "Run 20221121.5 stage Build job Compile succeeded.", - "markdown": "Run 20221121.5 stage Build job [Compile](https://dev.azure.com/fabrikamfiber/fabrikamfiber-viva/_build/results?buildId=2710088) succeeded." - }, - "resource": - { - "job": - { - "_links": - { - "web": - { - "href": "https://dev.azure.com/fabrikamfiber/fabrikamfiber-viva/_build/results?buildId=2710088" - }, - "pipeline.web": - { - "href": "https://dev.azure.com/fabrikamfiber/fabrikamfiber-viva/_build/definition?definitionId=4647" - } - }, - "id": "e87e3d16-29b0-5003-7d86-82b704b96244", - "name": "Compile", - "state": "completed", - "result": "succeeded", - "startTime": "2022-11-21T16:10:28.49Z", - "finishTime": "2022-11-21T16:10:53.66Z" - }, - "stage": { ... }, - "run": { ... }, - "pipeline": { ... }, - "repositories": [ ... ] - }, - "resourceVersion": "5.1-preview.1", - "createdDate": "2022-11-21T16:11:02.9207334Z" + "publisherId": "azure-devops", + "eventId": "check.updated", + "resource": { + "check": { + "id": "00000000-0000-0000-0000-000000000000check-id", + "type": "check-type", + "status": "check-status", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + } + } + }, + "updatedDate": "2024-07-17T21:34:22.338Z" +} +``` + + + +### Elastic agent pool resized + +Event: An elastic agent pool is resized. + +* Publisher ID: `azure-devops` +* Event ID: `elasticagentpool.resized` +* Resource Name: `elasticagentpool` + +#### Settings + +* `project`: Filter events to include only elastic agent pools resized within the specified project. +* `poolName`: Filter events to include only elastic agent pools with the specified name pattern. +* `oldSize`: Filter events to include only elastic agent pools with the specified old size. +* `newSize`: Filter events to include only elastic agent pools with the specified new size. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "elasticagentpool.resized", + "resource": { + "elasticAgentPool": { + "id": "00000000-0000-0000-0000-000000000000pool-id", + "name": "pool-name", + "oldSize": "old-size", + "newSize": "new-size", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + } + } + }, + "resizedDate": "2024-07-17T21:34:22.338Z" +} +``` + + + +### Manual intervention pending + +Event: A manual intervention is pending. + +* Publisher ID: `azure-devops` +* Event ID: `manualintervention.pending` +* Resource Name: `manualintervention` + +#### Settings + +* `project`: Filter events to include only manual interventions pending within the specified project. +* `interventionName`: Filter events to include only manual interventions with the specified name pattern. +* `status`: Filter events to include only manual interventions with the specified status. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "manualintervention.pending", + "resource": { + "manualIntervention": { + "id": "00000000-0000-0000-0000-000000000000intervention-id", + "name": "intervention-name", + "status": "pending", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + } + } + }, + "createdDate": "2024-07-17T21:34:22.338Z" +} +``` + + + +### Project-level agent pool created + +Event: A project-level agent pool is created. + +* Publisher ID: `azure-devops` +* Event ID: `projectlevelagentpool.created` +* Resource Name: `projectlevelagentpool` + +#### Settings + +* `project`: Filter events to include only project-level agent pools created within the specified project. +* `poolName`: Filter events to include only project-level agent pools with the specified name pattern. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "projectlevelagentpool.created", + "resource": { + "projectLevelAgentPool": { + "id": "00000000-0000-0000-0000-000000000000pool-id", + "name": "pool-name", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + } + } + }, + "createdDate": "2024-07-17T21:34:22.338Z" } ``` -::: moniker-end + + +### Project-level agent pool updated + +Event: A project-level agent pool is updated. + +* Publisher ID: `azure-devops` +* Event ID: `projectlevelagentpool.updated` +* Resource Name: `projectlevelagentpool` + +#### Settings + +* `project`: Filter events to include only project-level agent pools updated within the specified project. +* `poolName`: Filter events to include only project-level agent pools with the specified name pattern. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "projectlevelagentpool.updated", + "resource": { + "projectLevelAgentPool": { + "id": "00000000-0000-0000-0000-000000000000pool-id", + "name": "pool-name", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + } + } + }, + "updatedDate": "2024-07-17T21:34:22.338Z" +} +``` -::: moniker range=">= azure-devops-2020" ### Run state changed -Event: Overall statuses of a pipeline run changed. A new run has started, or a run has transitioned to canceling, canceled, failed, partially succeeded or succeeded state. +Event: Overall statuses of a pipeline run changed. A new run started, or a run transitioned to canceling, canceled, failed, partially succeeded or succeeded state. * Publisher ID: `pipelines` * Event ID: `ms.vss-pipelines.run-state-changed-event` @@ -1373,93 +1271,41 @@ Event: Overall statuses of a pipeline run changed. A new run has started, or a r #### Sample payload ```json { - "id": "62e4351f-1c24-40f9-8510-7af03692ab45", + "id": "00000000-0000-0000-0000-000000000000000", "eventType": "ms.vss-pipelines.run-state-changed-event", "publisherId": "pipelines", "message": { "text": "Run 11 succeeded.", - "html": "Run 11 succeeded.", - "markdown": "Run [11](https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_build/results?buildId=11) succeeded." + "html": "Run 11 succeeded.", + "markdown": "Run [11](https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_build/results?buildId=11) succeeded." }, "detailedMessage": { "text": "Run 11 succeeded.", - "html": "Run 11 succeeded.", - "markdown": "Run [11](https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_build/results?buildId=11) succeeded." + "html": "Run 11 succeeded.", + "markdown": "Run [11](https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_build/results?buildId=11) succeeded." }, "resource": { "run": { "_links": { "self": { - "href": "https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_apis/Pipelines/1/runs/11" + "href": "https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_apis/Pipelines/1/runs/11" }, "web": { - "href": "https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_build/results?buildId=11" - }, - "pipeline.web": { - "href": "https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_build/definition?definitionId=1" - }, - "pipeline": { - "href": "https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_apis/Pipelines/1?revision=1" + "href": "https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_build/results?buildId=11" } }, "pipeline": { - "url": "https://codedev.ms/org/091d79ee-dc21-465e-86a2-b4006b9d0921/_apis/Pipelines/1?revision=1", - "id": 11, - "revision": 1, - "name": "TEST-CI", - "folder": "\\" + "id": 1, + "name": "Pipeline-Name" }, "state": "completed", "result": "succeeded", - "createdDate": "2019-12-13T04:46:13.613Z", - "finishedDate": "2019-12-13T04:46:13.613Z", - "url": "https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_apis/Pipelines/1/runs/11", - "id": 11, - "name": "11" - }, - "pipeline": { - "url": "https://codedev.ms/org/091d79ee-dc21-465e-86a2-b4006b9d0921/_apis/Pipelines/1?revision=1", - "id": 11, - "revision": 1, - "name": "TEST-CI", - "folder": "\\" - }, - "repositories": [ - { - "type": "Git", - "change": - { - "author": - { - "name": "Fabrikam John", - "email": "john@fabrikamfiber.com", - "date": "2022-11-11T15:09:21Z" - }, - "committer": - { - "name": "Fabrikam John", - "email": "john@fabrikamfiber.com", - "date": "2022-11-11T15:09:21Z" - }, - "message": "Added Viva support" - }, - "url": "https://fabrikamfiber@dev.azure.com/fabrikamfiber/fabrikamfiber-viva/_git/fabrikamfiber" - } - ] - }, - "resourceVersion": "5.1-preview.1", - "resourceContainers": { - "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" - }, - "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" - }, - "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "createdDate": "2024-07-17T21:34:22.338Z", + "finishedDate": "2024-07-17T21:45:22.338Z", + "url": "https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_apis/Pipelines/1/runs/11" } }, - "createdDate": "2019-12-13T04:46:13.683Z" + "createdDate": "2024-07-17T21:34:22.338Z" } ``` @@ -1467,7 +1313,7 @@ Event: Overall statuses of a pipeline run changed. A new run has started, or a r ### Run stage state changed -Event: A new stage has started, or a stage has transitioned to canceling, canceled, failed, partially succeeded, or succeeded. +Event: A new stage started, or a stage transitioned to canceling, canceled, failed, partially succeeded, or succeeded. * Publisher ID: `pipelines` * Event ID: `ms.vss-pipelines.stage-state-changed-event` @@ -1488,30 +1334,30 @@ Event: A new stage has started, or a stage has transitioned to canceling, cancel ```json { - "id": "ac1dd6da-af30-43cb-8434-e1005864b0a3", + "id": "00000000-0000-0000-0000-000000000000ac1dd6da-af30-43cb-8434-e1005864b0a3", "eventType": "ms.vss-pipelines.stage-state-changed-event", "publisherId": "pipelines", "message": { "text": "Run 2 stage __default succeeded.", - "html": "Run 2 stage __default succeeded.", - "markdown": "Run 2 stage [__default](https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_build/results?buildId=2) succeeded." + "html": "Run 2 stage __default succeeded.", + "markdown": "Run 2 stage [__default](https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_build/results?buildId=2) succeeded." }, "detailedMessage": { "text": "Run 2 stage __default succeeded.", - "html": "Run 2 stage __default succeeded.", - "markdown": "Run 2 stage [__default](https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_build/results?buildId=2) succeeded." + "html": "Run 2 stage __default succeeded.", + "markdown": "Run 2 stage [__default](https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_build/results?buildId=2) succeeded." }, "resource": { "stage": { "_links": { "web": { - "href": "https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_build/results?buildId=2" + "href": "https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_build/results?buildId=2" }, "pipeline.web": { - "href": "https://codedev.ms/org/863d0a5b-3c91-4bf3-8ad7-7f33736b7f4c/_build/definition?definitionId=2" + "href": "https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_build/definition?definitionId=2" } }, - "id": "00000000-0000-0000-0000-000000000000", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", "name": "__default", "displayName": null, "state": "completed", @@ -1519,7 +1365,7 @@ Event: A new stage has started, or a stage has transitioned to canceling, cancel }, "run": { "pipeline": { - "url": "https://codedev.ms/org/091d79ee-dc21-465e-86a2-b4006b9d0921/_apis/Pipelines/2?revision=2", + "url": "https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_apis/Pipelines/2?revision=2", "id": 2, "revision": 2, "name": "TEST-CI", @@ -1533,7 +1379,7 @@ Event: A new stage has started, or a stage has transitioned to canceling, cancel "name": "2" }, "pipeline": { - "url": "https://codedev.ms/org/091d79ee-dc21-465e-86a2-b4006b9d0921/_apis/Pipelines/2?revision=2", + "url": "https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_apis/Pipelines/2?revision=2", "id": 2, "revision": 2, "name": "TEST-CI", @@ -1548,13 +1394,13 @@ Event: A new stage has started, or a stage has transitioned to canceling, cancel { "name": "Fabrikam John", "email": "john@fabrikamfiber.com", - "date": "2022-11-11T15:09:21Z" + "date": "2024-11-11T15:09:21Z" }, "committer": { "name": "Fabrikam John", "email": "john@fabrikamfiber.com", - "date": "2022-11-11T15:09:21Z" + "date": "2024-11-11T15:09:21Z" }, "message": "Added Viva support" }, @@ -1565,13 +1411,13 @@ Event: A new stage has started, or a stage has transitioned to canceling, cancel "resourceVersion": "5.1-preview.1", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, "createdDate": "2019-12-13T06:10:10.186Z" @@ -1598,7 +1444,7 @@ Event: An approval is created for a run stage. ```json { - "id": "55382df7-24fa-453c-9173-3369b2417a5b", + "id": "00000000-0000-0000-0000-00000000000055382df7-24fa-453c-9173-3369b2417a5b", "eventType": "ms.vss-pipelinechecks-events.approval-pending", "publisherId": "pipelines", "message": { @@ -1613,12 +1459,12 @@ Event: An approval is created for a run stage. }, "resource": { "approval": { - "id": "0f027b05-0942-4a35-9218-26fa07d8760a", + "id": "00000000-0000-0000-0000-0000000000000f027b05-0942-4a35-9218-26fa07d8760a", "steps": [ { "assignedApprover": { "displayName": null, - "id": "743f73b7-cdeb-4de7-80b7-00cee17476b8" + "id": "00000000-0000-0000-0000-000000000000743f73b7-cdeb-4de7-80b7-00cee17476b8" }, "status": "pending", "comment": "Sample comment", @@ -1633,7 +1479,7 @@ Event: An approval is created for a run stage. "blockedApprovers": [ { "displayName": null, - "id": "d651e716-a205-4b37-a803-e373df09fea6" + "id": "00000000-0000-0000-0000-000000000000d651e716-a205-4b37-a803-e373df09fea6" } ], "_links": {} @@ -1651,13 +1497,13 @@ Event: An approval is created for a run stage. "resourceVersion": "5.1-preview.1", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, "createdDate": "2019-12-13T06:14:11.671Z" @@ -1684,7 +1530,7 @@ Event: An approval completed for a run stage. ```json { - "id": "5810cce3-55e9-46dc-ad4f-681c57cf620e", + "id": "00000000-0000-0000-0000-0000000000005810cce3-55e9-46dc-ad4f-681c57cf620e", "eventType": "ms.vss-pipelinechecks-events.approval-completed", "publisherId": "pipelines", "message": { @@ -1699,12 +1545,12 @@ Event: An approval completed for a run stage. }, "resource": { "approval": { - "id": "0f027b05-0942-4a35-9218-26fa07d8760a", + "id": "00000000-0000-0000-0000-0000000000000f027b05-0942-4a35-9218-26fa07d8760a", "steps": [ { "assignedApprover": { "displayName": null, - "id": "f8482ec0-3e2f-489b-ba62-ea01cf84afa8" + "id": "00000000-0000-0000-0000-000000000000f8482ec0-3e2f-489b-ba62-ea01cf84afa8" }, "status": "approved", "comment": "Sample comment", @@ -1719,7 +1565,7 @@ Event: An approval completed for a run stage. "blockedApprovers": [ { "displayName": null, - "id": "23241e2e-59af-4b58-842e-5604d508c6b5" + "id": "00000000-0000-0000-0000-00000000000023241e2e-59af-4b58-842e-5604d508c6b5" } ], "_links": {} @@ -1737,13 +1583,13 @@ Event: An approval completed for a run stage. "resourceVersion": "5.1-preview.1", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, "createdDate": "2019-12-13T06:18:22.487Z" @@ -1756,7 +1602,7 @@ Event: An approval completed for a run stage. ### Run job state changed -Event: A new job is running, or it has completed, or is waiting for an agent. +Event: A new job is running, or it completed, or is waiting for an agent. * Publisher ID: `pipelines` * Event ID: `ms.vss-pipelines.job-state-changed-event` @@ -1784,22 +1630,22 @@ Event: A new job is running, or it has completed, or is waiting for an agent. ```json { - "subscriptionId": "00000000-0000-0000-0000-000000000000", + "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e", "notificationId": 3, - "id": "ac1dd6da-af30-43cb-8434-e1005864b0a3", + "id": "00000000-0000-0000-0000-000000000000ac1dd6da-af30-43cb-8434-e1005864b0a3", "eventType": "ms.vss-pipelines.job-state-changed-event", "publisherId": "pipelines", "message": { - "text": "Run 20221121.5 stage Build job Compile succeeded.", - "html": "Run 20221121.5 stage Build job Compile succeeded.", - "markdown": "Run 20221121.5 stage Build job [Compile](https://dev.azure.com/fabrikamfiber/fabrikamfiber-viva/_build/results?buildId=2710088) succeeded." + "text": "Run 20241121.5 stage Build job Compile succeeded.", + "html": "Run 20241121.5 stage Build job Compile succeeded.", + "markdown": "Run 20241121.5 stage Build job [Compile](https://dev.azure.com/fabrikamfiber/fabrikamfiber-viva/_build/results?buildId=2710088) succeeded." }, "detailedMessage": { - "text": "Run 20221121.5 stage Build job Compile succeeded.", - "html": "Run 20221121.5 stage Build job Compile succeeded.", - "markdown": "Run 20221121.5 stage Build job [Compile](https://dev.azure.com/fabrikamfiber/fabrikamfiber-viva/_build/results?buildId=2710088) succeeded." + "text": "Run 20241121.5 stage Build job Compile succeeded.", + "html": "Run 20241121.5 stage Build job Compile succeeded.", + "markdown": "Run 20241121.5 stage Build job [Compile](https://dev.azure.com/fabrikamfiber/fabrikamfiber-viva/_build/results?buildId=2710088) succeeded." }, "resource": { @@ -1816,16 +1662,16 @@ Event: A new job is running, or it has completed, or is waiting for an agent. "href": "https://dev.azure.com/fabrikamfiber/fabrikamfiber-viva/_build/definition?definitionId=2" } }, - "id": "00000000-0000-0000-0000-000000000000", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", "name": "__default", "state": "completed", "result": "succeeded", - "startTime": "2022-11-21T16:42:52.7761408Z", - "finishTime": "2022-11-21T16:42:52.7761408Z" + "startTime": "2024-11-21T16:42:52.7761408Z", + "finishTime": "2024-11-21T16:42:52.7761408Z" }, "stage": { - "id": "00000000-0000-0000-0000-000000000000", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", "name": "__default", "displayName": null, "state": "completed", @@ -1837,7 +1683,7 @@ Event: A new job is running, or it has completed, or is waiting for an agent. { "pipeline": { - "url": "https://codedev.ms/org/091d79ee-dc21-465e-86a2-b4006b9d0921/_apis/Pipelines/2?revision=2", + "url": "https://codedev.ms/org/1234/_apis/Pipelines/2?revision=2", "id": 2, "revision": 2, "name": "TEST-CI", @@ -1845,14 +1691,14 @@ Event: A new job is running, or it has completed, or is waiting for an agent. }, "state": "completed", "result": "succeeded", - "createdDate": "2022-11-21T16:42:52.7761408Z", - "finishedDate": "2022-11-21T16:42:52.7761408Z", + "createdDate": "2024-11-21T16:42:52.7761408Z", + "finishedDate": "2024-11-21T16:42:52.7761408Z", "id": 2, "name": "2" }, "pipeline": { - "url": "https://codedev.ms/org/091d79ee-dc21-465e-86a2-b4006b9d0921/_apis/Pipelines/2?revision=2", + "url": "https://codedev.ms/org/00000000-0000-0000-0000-000000000000/_apis/Pipelines/2?revision=2", "id": 2, "revision": 2, "name": "TEST-CI", @@ -1868,13 +1714,13 @@ Event: A new job is running, or it has completed, or is waiting for an agent. { "name": "Fabrikam John", "email": "john@fabrikamfiber.com", - "date": "2022-11-11T15:09:21Z" + "date": "2024-11-11T15:09:21Z" }, "committer": { "name": "Fabrikam John", "email": "john@fabrikamfiber.com", - "date": "2022-11-11T15:09:21Z" + "date": "2024-11-11T15:09:21Z" }, "message": "Added Viva support" }, @@ -1888,13 +1734,13 @@ Event: A new job is running, or it has completed, or is waiting for an agent. { "name": "Fabrikam John", "email": "john@github.com", - "date": "2022-08-11T15:05:20Z" + "date": "2024-08-11T15:05:20Z" }, "committer": { "name": "Fabrikam John", "email": "john@github.com", - "date": "2022-08-11T15:05:20Z" + "date": "2024-08-11T15:05:20Z" }, "message": "Added Viva open source REST API library" }, @@ -1907,18 +1753,18 @@ Event: A new job is running, or it has completed, or is waiting for an agent. { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2022-11-21T16:42:53.5254422Z" + "createdDate": "2024-11-21T16:42:53.5254422Z" } ``` @@ -1930,9 +1776,9 @@ Event: A new job is running, or it has completed, or is waiting for an agent. ### Code checked in -Event: A changeset is checked into TFVC. +Event: A changeset is checked into Team Foundation Version Control (TFVC). -* Publisher ID: `tfs` +* Publisher ID: `azure-devops` * Event ID: `tfvc.checkin` * Resource Name: `changeset` @@ -1945,31 +1791,31 @@ Event: A changeset is checked into TFVC. ```json { - "id": "f9b4c23e-88dd-4516-b04d-849787304e32", + "id": "00000000-0000-0000-0000-000000000000", "eventType": "tfvc.checkin", - "publisherId": "tfs", + "publisherId": "azure-devops", "scope": "all", "message": { "text": "Normal Paulk checked in changeset 18: Dropping in new Java sample", - "html": "Normal Paulk checked in changeset 18: Dropping in new Java sample", - "markdown": "Normal Paulk checked in changeset [18](https://dev.azure.com/fabrikam-fiber-inc/web/cs.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&cs=18): Dropping in new Java sample" + "html": "Normal Paulk checked in changeset 18: Dropping in new Java sample", + "markdown": "Chuck Reinhart checked in changeset [18](https://dev.azure.com/fabrikam-fiber-inc/web/cs.aspx?pcguid=000-0000-0000): Dropping in new Java sample" }, "detailedMessage": { - "text": "Normal Paulk checked in changeset 18: Dropping in new Java sample", - "html": "Normal Paulk checked in changeset 18: Dropping in new Java sample", - "markdown": "Normal Paulk checked in changeset [18](https://dev.azure.com/fabrikam-fiber-inc/web/cs.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&cs=18): Dropping in new Java sample" + "text": "Chuck Reinhart checked in changeset 18: Dropping in new Java sample", + "html": "Chuck Reinhart checked in changeset 18: Dropping in new Java sample", + "markdown": "Chuck Reinhart checked in changeset [18](https://dev.azure.com/fabrikam-fiber-inc/web/cs.aspx?pcguid=000-0000-0000): Dropping in new Java sample" }, "resource": { "changesetId": 18, "url": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/tfvc/changesets/18", "author": { - "id": "d6245f20-2af8-44f4-9451-8107cb2767db", - "displayName": "Normal Paulk", + "id": "00000000-0000-0000-0000-000000000000", + "displayName": "Chuck Reinhart", "uniqueName": "fabrikamfiber16@hotmail.com" }, "checkedInBy": { - "id": "d6245f20-2af8-44f4-9451-8107cb2767db", - "displayName": "Normal Paulk", + "id": "00000000-0000-0000-0000-000000000000", + "displayName": "Chuck Reinhart", "uniqueName": "fabrikamfiber16@hotmail.com" }, "createdDate": "2014-05-12T22:41:16Z", @@ -1978,13 +1824,13 @@ Event: A changeset is checked into TFVC. "resourceVersion": "1.0", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:26.2056408Z" + "createdDate": "2024-09-19T13:03:26.2056408Z" } ``` @@ -1992,26 +1838,26 @@ Event: A changeset is checked into TFVC. ### Code pushed -Event: Code was pushed to a Git repository. +Event: Code is pushed to a Git repository. -* Publisher ID: `tfs` +* Publisher ID: `azure-devops` * Event ID: `git.push` * Resource Name: `push` #### Settings - * `branch`: The branch that code was pushed into + * `branch`: The branch that code is pushed into * `pushedBy`: A group that has the pusher as its member - * `repository`: The repository that code was pushed to + * `repository`: The repository that code is pushed to * Data type: `guid` #### Sample payload ```json { - "id": "03c164c2-8912-4d5e-8009-3707d5f83734", + "id": "00000000-0000-0000-0000-0000000000000", "eventType": "git.push", - "publisherId": "tfs", + "publisherId": "azure-devops", "scope": "all", "message": { "text": "Jamal Hartnett pushed updates to branch master of repository Fabrikam-Fiber-Git.", @@ -2020,69 +1866,69 @@ Event: Code was pushed to a Git repository. }, "detailedMessage": { "text": "Jamal Hartnett pushed 1 commit to branch master of repository Fabrikam-Fiber-Git.\n - Fixed bug in web.config file 33b55f7c", - "html": "Jamal Hartnett pushed 1 commit to branch master of repository Fabrikam-Fiber-Git.\n
        \n
      • Fixed bug in web.config file 33b55f7c\n
      ", - "markdown": "Jamal Hartnett pushed 1 commit to branch [master](https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_git/Fabrikam-Fiber-Git/#version=GBmaster) of repository [Fabrikam-Fiber-Git](https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_git/Fabrikam-Fiber-Git/).\n* Fixed bug in web.config file [33b55f7c](https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_git/Fabrikam-Fiber-Git/commit/33b55f7cb7e7e245323987634f960cf4a6e6bc74)" + "html": "Jamal Hartnett pushed 1 commit to branch master of repository Fabrikam-Fiber-Git.\n
        \n- Fixed bug in web.config file 33b55f7c\n
      ", + "markdown": "Jamal Hartnett pushed 1 commit to branch [master](https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_git/Fabrikam-Fiber-Git/#version=GBmaster) of repository [Fabrikam-Fiber-Git](https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_git/Fabrikam-Fiber-Git/).\n* Fixed bug in web.config file [33b55f7c](https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_git/Fabrikam-Fiber-Git/commit/00000000-0000-0000-0000-000000000000)" }, "resource": { "commits": [ { - "commitId": "33b55f7cb7e7e245323987634f960cf4a6e6bc74", + "commitId": "00000000-0000-0000-0000-000000000000", "author": { "name": "Jamal Hartnett", "email": "fabrikamfiber4@hotmail.com", - "date": "2015-02-25T19:01:00Z" + "date": "2024-02-25T19:01:00Z" }, "committer": { "name": "Jamal Hartnett", "email": "fabrikamfiber4@hotmail.com", - "date": "2015-02-25T19:01:00Z" + "date": "2024-02-25T19:01:00Z" }, "comment": "Fixed bug in web.config file", - "url": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_git/Fabrikam-Fiber-Git/commit/33b55f7cb7e7e245323987634f960cf4a6e6bc74" + "url": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_git/Fabrikam-Fiber-Git/commit/00000000-0000-0000-0000-000000000000" } ], "refUpdates": [ { "name": "refs/heads/main", "oldObjectId": "aad331d8d3b131fa9ae03cf5e53965b51942618a", - "newObjectId": "33b55f7cb7e7e245323987634f960cf4a6e6bc74" + "newObjectId": "00000000-0000-0000-0000-000000000000" } ], "repository": { - "id": "278d5cd2-584d-4b63-824a-2ba458937249", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam-Fiber-Git", - "url": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/repos/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249", + "url": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/repos/git/repositories/abcd-1234-efgh-5678", "project": { - "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam-Fiber-Git", - "url": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", + "url": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/projects/abcd-1234-efgh-5678", "state": "wellFormed" }, "defaultBranch": "refs/heads/main", "remoteUrl": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_git/Fabrikam-Fiber-Git" }, "pushedBy": { - "id": "00067FFED5C7AF52@Live.com", + "id": "00000000-0000-0000-0000-000000000000@Live.com", "displayName": "Jamal Hartnett", "uniqueName": "Windows Live ID\\fabrikamfiber4@hotmail.com" }, "pushId": 14, "date": "2014-05-02T19:17:13.3309587Z", - "url": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/repos/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/pushes/14" + "url": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/repos/git/repositories/abcd-1234-efgh-5678/pushes/14" }, "resourceVersion": "1.0", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:27.0379153Z" + "createdDate": "2024-09-19T13:03:27.0379153Z" } ``` @@ -2092,13 +1938,13 @@ Event: Code was pushed to a Git repository. Event: A pull request is created in a Git repository. -* Publisher ID: `tfs` +* Publisher ID: `azure-devops` * Event ID: `git.pullrequest.created` * Resource Name: `pullrequest` #### Settings - * `repository`: The repository that code was pushed to + * `repository`: The repository that code is pushed to * Data type: `guid` * `pullrequestCreatedBy`: A group that has the requester as a member * `pullrequestReviewersContains`: A group included in the reviewers list @@ -2108,9 +1954,9 @@ Event: A pull request is created in a Git repository. ```json { - "id": "2ab4e3d3-b7a6-425e-92b1-5a9982c1269e", + "id": "00000000-0000-0000-0000-000000000000", "eventType": "git.pullrequest.created", - "publisherId": "tfs", + "publisherId": "azure-devops", "scope": "all", "message": { "text": "Jamal Hartnett created a new pull request", @@ -2118,19 +1964,19 @@ Event: A pull request is created in a Git repository. "markdown": "Jamal Hartnett created a new pull request" }, "detailedMessage": { - "text": "Jamal Hartnett created a new pull request\r\n\r\n- Merge status: Succeeded\r\n- Merge commit: eef717(https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/eef717f69257a6333f221566c1c987dc94cc0d72)\r\n", - "html": "Jamal Hartnett created a new pull request\r\n
        \r\n
      • Merge status: Succeeded
        • \r\n
      • Merge commit: eef717
        • \r\n
      ", - "markdown": "Jamal Hartnett created a new pull request\r\n\r\n+ Merge status: Succeeded\r\n+ Merge commit: [eef717](https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/eef717f69257a6333f221566c1c987dc94cc0d72)\r\n" + "text": "Jamal Hartnett created a new pull request\r\n\r\n- Merge status: Succeeded\r\n- Merge commit: eef717(https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000)\r\n", + "html": "Jamal Hartnett created a new pull request\r\n
        \r\n- Merge status: Succeeded
        \r\n- Merge commit: eef717
        \r\n
      ", + "markdown": "Jamal Hartnett created a new pull request\r\n\r\n+ Merge status: Succeeded\r\n+ Merge commit: [eef717](https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000)\r\n" }, "resource": { "repository": { - "id": "4bc14d40-c903-45e2-872e-0462c7748079", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000", "project": { - "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/projects/abcd-1234-efgh-5678", "state": "wellFormed" }, "defaultBranch": "refs/heads/main", @@ -2139,177 +1985,178 @@ Event: A pull request is created in a Git repository. "pullRequestId": 1, "status": "active", "createdBy": { - "id": "54d125f7-69f7-4191-904f-c5b96b6261c8", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "Jamal Hartnett", "uniqueName": "fabrikamfiber4@hotmail.com", - "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/54d125f7-69f7-4191-904f-c5b96b6261c8", - "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=54d125f7-69f7-4191-904f-c5b96b6261c8" + "url": "https://dev.azure.com/fabrikam/_apis/Identities/00000000-0000-0000-0000-000000000000", + "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=00000000-0000-0000-0000-000000000000" }, - "creationDate": "2014-06-17T16:55:46.589889Z", + "creationDate": "2024-06-17T11:22:33.456789Z", "title": "my first pull request", "description": " - test2\r\n", "sourceRefName": "refs/heads/mytopic", "targetRefName": "refs/heads/main", "mergeStatus": "succeeded", - "mergeId": "a10bb228-6ba6-4362-abd7-49ea21333dbd", + "mergeId": "a1234567-abcde-1234-abc", "lastMergeSourceCommit": { - "commitId": "53d54ac915144006c2c9e90d2c7d3880920db49c", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/53d54ac915144006c2c9e90d2c7d3880920db49c" + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" }, "lastMergeTargetCommit": { - "commitId": "a511f535b1ea495ee0c903badb68fbc83772c882", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/a511f535b1ea495ee0c903badb68fbc83772c882" + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" }, "lastMergeCommit": { - "commitId": "eef717f69257a6333f221566c1c987dc94cc0d72", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/eef717f69257a6333f221566c1c987dc94cc0d72" + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" }, "reviewers": [ { "reviewerUrl": null, "vote": 0, - "id": "2ea2d095-48f9-4cd6-9966-62f6f574096c", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "[Mobile]\\Mobile Team", - "uniqueName": "vstfs:///Classification/TeamProject/f0811a3b-8c8a-4e43-a3bf-9a049b4835bd\\Mobile Team", - "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/2ea2d095-48f9-4cd6-9966-62f6f574096c", - "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=2ea2d095-48f9-4cd6-9966-62f6f574096c", + "uniqueName": "azure-devops:///Classification/TeamProject/00000000-0000-0000-0000-000000000000\\Mobile Team", + "url": "https://dev.azure.com/fabrikam/_apis/Identities/00000000-0000-0000-0000-000000000000", + "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=00000000-0000-0000-0000-000000000000", "isContainer": true } ], - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/pullRequests/1" + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/pullRequests/1" }, "resourceVersion": "1.0", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:27.2879096Z" + "createdDate": "2024-09-19T13:03:27.2879096Z" } ``` - + -### Pull request merge commit created +### Pull request merge attempted -Event: A merge commit was created on a pull request. +Event: A pull request merge is attempted in a Git repository. -* Publisher ID: `tfs` -* Event ID: `git.pullrequest.merged` +* Publisher ID: `azure-devops` +* Event ID: `git.pullrequest.merge.attempted` * Resource Name: `pullrequest` #### Settings - * `repository`: The repository that code was pushed to + * `repository`: The repository that code is pushed to * Data type: `guid` * `pullrequestCreatedBy`: A group that has the requester as a member * `pullrequestReviewersContains`: A group included in the reviewers list * `branch`: The target branch of the pull request + #### Sample payload ```json { - "id": "6872ee8c-b333-4eff-bfb9-0d5274943566", - "eventType": "git.pullrequest.merged", - "publisherId": "tfs", + "id": "00000000-0000-0000-0000-000000000000", + "eventType": "git.pullrequest.merge.attempted", + "publisherId": "azure-devops", "scope": "all", "message": { - "text": "Jamal Hartnett has created a pull request merge commit", - "html": "Jamal Hartnett has created a pull request merge commit", - "markdown": "Jamal Hartnett has created a pull request merge commit" + "text": "Jamal Hartnett attempted to merge a pull request", + "html": "Jamal Hartnett attempted to merge a pull request", + "markdown": "Jamal Hartnett attempted to merge a pull request" }, "detailedMessage": { - "text": "Jamal Hartnett has created a pull request merge commit\r\n\r\n- Merge status: Succeeded\r\n- Merge commit: eef717(https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/eef717f69257a6333f221566c1c987dc94cc0d72)\r\n", - "html": "Jamal Hartnett has created a pull request merge commit\r\n
        \r\n
      • Merge status: Succeeded
        • \r\n
      • Merge commit: eef717
        • \r\n
      ", - "markdown": "Jamal Hartnett has created a pull request merge commit\r\n\r\n+ Merge status: Succeeded\r\n+ Merge commit: [eef717](https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/eef717f69257a6333f221566c1c987dc94cc0d72)\r\n" + "text": "Jamal Hartnett attempted to merge a pull request\r\n\r\n- Merge status: Attempted\r\n- Merge commit: eef717(https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000)\r\n", + "html": "Jamal Hartnett created a new pull request\r\n
        \r\n- Merge status: Attempted
        \r\n- Merge commit: eef717
        \r\n
      ", + "markdown": "Jamal Hartnett created a new pull request\r\n\r\n+ Merge status: Attempted\r\n+ Merge commit: [eef717](https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000)\r\n" }, "resource": { "repository": { - "id": "4bc14d40-c903-45e2-872e-0462c7748079", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000", "project": { - "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", + "id": "00000000-0000-0000-0000-000000000000abcd-1234-efgh-5678", "name": "Fabrikam", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/projects/00000000-0000-0000-0000-000000000000", "state": "wellFormed" }, "defaultBranch": "refs/heads/main", "remoteUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_git/Fabrikam" }, "pullRequestId": 1, - "status": "completed", + "status": "active", "createdBy": { - "id": "54d125f7-69f7-4191-904f-c5b96b6261c8", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "Jamal Hartnett", "uniqueName": "fabrikamfiber4@hotmail.com", - "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/54d125f7-69f7-4191-904f-c5b96b6261c8", - "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=54d125f7-69f7-4191-904f-c5b96b6261c8" + "url": "https://dev.azure.com/fabrikam/_apis/Identities/00000000-0000-0000-0000-000000000000", + "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=00000000-0000-0000-0000-000000000000" }, - "creationDate": "2014-06-17T16:55:46.589889Z", - "closedDate": "2014-06-30T18:59:12.3660573Z", + "creationDate": "2024-06-17T11:22:33.456789Z", "title": "my first pull request", "description": " - test2\r\n", "sourceRefName": "refs/heads/mytopic", "targetRefName": "refs/heads/main", - "mergeStatus": "succeeded", - "mergeId": "a10bb228-6ba6-4362-abd7-49ea21333dbd", + "mergeStatus": "attempted", + "mergeId": "00000000-0000-0000-0000-000000000000", "lastMergeSourceCommit": { - "commitId": "53d54ac915144006c2c9e90d2c7d3880920db49c", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/53d54ac915144006c2c9e90d2c7d3880920db49c" + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" }, "lastMergeTargetCommit": { - "commitId": "a511f535b1ea495ee0c903badb68fbc83772c882", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/a511f535b1ea495ee0c903badb68fbc83772c882" + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" }, "lastMergeCommit": { - "commitId": "eef717f69257a6333f221566c1c987dc94cc0d72", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/eef717f69257a6333f221566c1c987dc94cc0d72" + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" }, "reviewers": [ { "reviewerUrl": null, "vote": 0, - "id": "2ea2d095-48f9-4cd6-9966-62f6f574096c", + "id": "00000000-0000-0000-0000-000000000000", "displayName": "[Mobile]\\Mobile Team", - "uniqueName": "vstfs:///Classification/TeamProject/f0811a3b-8c8a-4e43-a3bf-9a049b4835bd\\Mobile Team", - "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/2ea2d095-48f9-4cd6-9966-62f6f574096c", - "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=2ea2d095-48f9-4cd6-9966-62f6f574096c", + "uniqueName": "azure-devops:///Classification/TeamProject/00000000-0000-0000-0000-000000000000\\Mobile Team", + "url": "https://dev.azure.com/fabrikam/_apis/Identities/00000000-0000-0000-0000-000000000000", + "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=00000000-0000-0000-0000-000000000000", "isContainer": true } ], - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/pullRequests/1" + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/pullRequests/1" }, "resourceVersion": "1.0", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:27.3156388Z" + "createdDate": "2024-09-19T13:03:27.2879096Z" } ``` + ### Pull request updated Event: A pull request is updated; status, review list, reviewer vote changed, or the source branch is updated with a push. -* Publisher ID: `tfs` +* Publisher ID: `azure-devops` * Event ID: `git.pullrequest.updated` * Resource Name: `pullrequest` @@ -2321,7 +2168,7 @@ Event: A pull request is updated; status, review list, reviewer vote changed, or * `ReviewersUpdateNotification` - Reviewers changed * `StatusUpdateNotification` - Status changed * `ReviewerVoteNotification` - Votes score changed - * `repository`: The repository that code was pushed to + * `repository`: The repository that code is pushed to * Data type: `guid` * `pullrequestCreatedBy`: A group that has the requester as a member * `pullrequestReviewersContains`: A group included in the reviewers list @@ -2331,9 +2178,9 @@ Event: A pull request is updated; status, review list, reviewer vote changed, or ```json { - "id": "af07be1b-f3ad-44c8-a7f1-c4835f2df06b", + "id": "00000000-0000-0000-0000-000000000000", "eventType": "git.pullrequest.updated", - "publisherId": "tfs", + "publisherId": "azure-devops", "scope": "all", "message": { "text": "Jamal Hartnett marked the pull request as completed", @@ -2341,19 +2188,19 @@ Event: A pull request is updated; status, review list, reviewer vote changed, or "markdown": "Jamal Hartnett marked the pull request as completed" }, "detailedMessage": { - "text": "Jamal Hartnett marked the pull request as completed\r\n\r\n- Merge status: Succeeded\r\n- Merge commit: eef717(https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/eef717f69257a6333f221566c1c987dc94cc0d72)\r\n", - "html": "Jamal Hartnett marked the pull request as completed\r\n
        \r\n
      • Merge status: Succeeded
        • \r\n
      • Merge commit: eef717
        • \r\n
      ", - "markdown": "Jamal Hartnett marked the pull request as completed\r\n\r\n+ Merge status: Succeeded\r\n+ Merge commit: [eef717](https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/eef717f69257a6333f221566c1c987dc94cc0d72)\r\n" + "text": "Jamal Hartnett marked the pull request as completed\r\n\r\n- Merge status: Succeeded\r\n- Merge commit: eef717(https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000)\r\n", + "html": "Jamal Hartnett marked the pull request as completed\r\n
        \r\n- Merge status: Succeeded
        \r\n- Merge commit: eef717
        \r\n
      ", + "markdown": "Jamal Hartnett marked the pull request as completed\r\n\r\n+ Merge status: Succeeded\r\n+ Merge commit: [eef717](https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000)\r\n" }, "resource": { "repository": { - "id": "4bc14d40-c903-45e2-872e-0462c7748079", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000", "project": { - "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", + "id": "00000000-0000-0000-0000-000000000000", "name": "Fabrikam", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/projects/00000000-0000-0000-0000-000000000000", "state": "wellFormed" }, "defaultBranch": "refs/heads/main", @@ -2362,65 +2209,467 @@ Event: A pull request is updated; status, review list, reviewer vote changed, or "pullRequestId": 1, "status": "completed", "createdBy": { - "id": "54d125f7-69f7-4191-904f-c5b96b6261c8", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", "displayName": "Jamal Hartnett", "uniqueName": "fabrikamfiber4@hotmail.com", - "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/54d125f7-69f7-4191-904f-c5b96b6261c8", - "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=54d125f7-69f7-4191-904f-c5b96b6261c8" + "url": "https://dev.azure.com/fabrikam/_apis/Identities/00000000-0000-0000-0000-000000000000", + "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=00000000-0000-0000-0000-000000000000" }, - "creationDate": "2014-06-17T16:55:46.589889Z", - "closedDate": "2014-06-30T18:59:12.3660573Z", + "creationDate": "2024-06-17T16:55:46.589889Z", + "closedDate": "2024-06-30T18:59:12.3660573Z", "title": "my first pull request", "description": " - test2\r\n", "sourceRefName": "refs/heads/mytopic", "targetRefName": "refs/heads/main", "mergeStatus": "succeeded", - "mergeId": "a10bb228-6ba6-4362-abd7-49ea21333dbd", + "mergeId": "00000000-0000-0000-0000-000000000000", "lastMergeSourceCommit": { - "commitId": "53d54ac915144006c2c9e90d2c7d3880920db49c", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/53d54ac915144006c2c9e90d2c7d3880920db49c" + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/abc-defg-123-4567/commits/00000000-0000-0000-0000-000000000000" }, "lastMergeTargetCommit": { - "commitId": "a511f535b1ea495ee0c903badb68fbc83772c882", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/a511f535b1ea495ee0c903badb68fbc83772c882" + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/abc-defg-123-4567/commits/00000000-0000-0000-0000-000000000000" }, "lastMergeCommit": { - "commitId": "eef717f69257a6333f221566c1c987dc94cc0d72", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/eef717f69257a6333f221566c1c987dc94cc0d72" + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/abc-defg-123-4567/commits/00000000-0000-0000-0000-000000000000" }, "reviewers": [ { "reviewerUrl": null, "vote": 0, - "id": "2ea2d095-48f9-4cd6-9966-62f6f574096c", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", "displayName": "[Mobile]\\Mobile Team", - "uniqueName": "vstfs:///Classification/TeamProject/f0811a3b-8c8a-4e43-a3bf-9a049b4835bd\\Mobile Team", - "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/2ea2d095-48f9-4cd6-9966-62f6f574096c", - "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=2ea2d095-48f9-4cd6-9966-62f6f574096c", + "uniqueName": "azure-devops:///Classification/TeamProject/00000000-0000-0000-0000-000000000000\\Mobile Team", + "url": "https://dev.azure.com/fabrikam/_apis/Identities/abcdefg1234567", + "imageUrl": "https://dev.azure.com/fabrikam/DefaultCollection/_api/_common/identityImage?id=abcdefg1234567", "isContainer": true } ], "commits": [ { - "commitId": "53d54ac915144006c2c9e90d2c7d3880920db49c", - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/commits/53d54ac915144006c2c9e90d2c7d3880920db49c" + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" } ], - "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/4bc14d40-c903-45e2-872e-0462c7748079/pullRequests/1" + "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/repos/git/repositories/00000000-0000-0000-0000-000000000000/pullRequests/1" }, "resourceVersion": "1.0", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:27.2813828Z" + "createdDate": "2024-09-19T13:03:27.2813828Z" +} +``` + + + +### Pull request commented on + +Event: A pull request is commented on. + +* Publisher ID: `azure-devops` +* Event ID: `ms.vss-code.git-pullrequest-comment-event` +* Resource Name: `pullrequest` + +#### Settings + + * `repository`: The repository that pull request is commented on + * Data type: `guid` + * `branch`: The target branch of the pull request + +#### Sample payload + +```json +{ + "id": "00000000-0000-0000-0000-000000000000af07be1b-f3ad-44c8-a7f1-c4835f2df06b", + "eventType": "ms.vss-code.git-pullrequest-comment-event", + "publisherId": "azure-devops", + "message": { + "text": "Jamal Hartnett has edited a pull request comment", + "html": "Jamal Hartnett has edited a pull request comment", + "markdown": "Jamal Hartnett has [edited](https://fabrikam.visualstudio.com/DefaultCollection/_git/Fabrikam/pullrequest/1?discussionId=5) a pull request comment" + }, + "detailedMessage": { + "text": "Jamal Hartnett has edited a pull request comment\r\nThis is my comment.\r\n", + "html": "Jamal Hartnett has edited a pull request comment

      This is my comment.

      ", + "markdown": "Jamal Hartnett has [edited](https://fabrikam.visualstudio.com/DefaultCollection/_git/Fabrikam/pullrequest/1?discussionId=5) a pull request comment\r\nThis is my comment.\r\n" + }, + "resource": { + "comment": { + "id": 2, + "parentCommentId": 1, + "author": { + "displayName": "Jamal Hartnett", + "url": "https://fabrikam.vssps.visualstudio.com/_apis/Identities/00000000-0000-0000-0000-000000000000", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", + "uniqueName": "fabrikamfiber4@hotmail.com", + "imageUrl": "https://fabrikam.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=00000000-0000-0000-0000-000000000000" + }, + "content": "This is my comment.", + "publishedDate": "2024-06-17T11:22:33.456789Z", + "lastUpdatedDate": "2024-06-17T16:58:33.123889Z", + "lastContentUpdatedDate": "2024-06-17T16:58:33.123889Z", + "commentType": "text", + "_links": { + "self": { + "href": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/git/repositories/00000000-0000-0000-0000-000000000000/pullRequests/1/threads/5/comments/2" + }, + "repository": { + "href": "http://joscol2/DefaultCollection/ebed510c-62eb-474b-965f-fd151ebb82e4/_apis/git/repositories/00000000-0000-0000-0000-000000000000" + }, + "threads": { + "href": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/git/repositories/00000000-0000-0000-0000-000000000000/pullRequests/1/threads/5" + } + } + }, + "pullRequest": { + "repository": { + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", + "name": "Fabrikam", + "url": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/git/repositories/00000000-0000-0000-0000-000000000000", + "project": { + "id": "00000000-0000-0000-0000-000000000000abcd-1234-efgh-5678", + "name": "Fabrikam", + "url": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/projects/abcd-1234-efgh-5678", + "state": "wellFormed", + "visibility": "unchanged", + "lastUpdateTime": "0001-01-01T00:00:00" + }, + "defaultBranch": "refs/heads/master", + "remoteUrl": "https://fabrikam.visualstudio.com/DefaultCollection/_git/Fabrikam" + }, + "pullRequestId": 1, + "status": "active", + "createdBy": { + "displayName": "Jamal Hartnett", + "url": "https://fabrikam.vssps.visualstudio.com/_apis/Identities/00000000-0000-0000-0000-000000000000", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", + "uniqueName": "fabrikamfiber4@hotmail.com", + "imageUrl": "https://fabrikam.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=00000000-0000-0000-0000-000000000000" + }, + "creationDate": "2024-06-17T11:22:33.456789Z", + "title": "my first pull request", + "description": " - test2\r\n", + "sourceRefName": "refs/heads/mytopic", + "targetRefName": "refs/heads/master", + "mergeStatus": "succeeded", + "mergeId": "a1234567-abcde-1234-abc", + "lastMergeSourceCommit": { + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" + }, + "lastMergeTargetCommit": { + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" + }, + "lastMergeCommit": { + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" + }, + "reviewers": [ + { + "reviewerUrl": null, + "vote": 0, + "displayName": "[Mobile]\\Mobile Team", + "url": "https://fabrikam.vssps.visualstudio.com/_apis/Identities/00000000-0000-0000-0000-000000000000", + "id": "00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000", + "uniqueName": "azure-devops:///Classification/TeamProject/00000000-0000-0000-0000-000000000000\\Mobile Team", + "imageUrl": "https://fabrikam.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=00000000-0000-0000-0000-000000000000", + "isContainer": true + } + ], + "commits": [ + { + "commitId": "00000000-0000-0000-0000-000000000000", + "url": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/git/repositories/00000000-0000-0000-0000-000000000000/commits/00000000-0000-0000-0000-000000000000" + } + ], + "url": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/git/repositories/00000000-0000-0000-0000-000000000000/pullRequests/1", + "_links": { + "web": { + "href": "https://fabrikam.visualstudio.com/DefaultCollection/_git/Fabrikam/pullrequest/1#view=discussion" + }, + "statuses": { + "href": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/git/repositories/00000000-0000-0000-0000-000000000000/pullRequests/1/statuses" + } + } + } + }, + "resourceVersion": "2.0", + "resourceContainers": { + "collection": { + "id": "00000000-0000-0000-0000-000000000000" + }, + "account": { + "id": "00000000-0000-0000-0000-000000000000" + }, + "project": { + "id": "00000000-0000-0000-0000-000000000000" + } + }, + "createdDate": "2024-07-17T21:34:22.338Z" +} +``` + +### Repository created + +Event: A new repository is created. + +* Publisher ID: `azure-devops` +* Event ID: `git.repository.created` +* Resource Name: `repository` + +#### Settings + +* `project`: Filter events to include only repositories created within the specified project. +* `repositoryName`: Filter events to include only repositories with the specified name pattern. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "git.repository.created", + "resource": { + "repository": { + "id": "00000000-0000-0000-0000-000000000000repository-id", + "name": "repository-name", + "url": "repository-url", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + } + } + }, + "createdDate": "2024-07-17T21:34:22.338Z" +} +``` + +### Repository deleted + +Event: A repository is deleted. + +* Publisher ID: `azure-devops` +* Event ID: `git.repository.deleted` +* Resource Name: `repository` + +#### Settings + +* `project`: Filter events to include only repositories deleted within the specified project. +* `repositoryName`: Filter events to include only repositories with the specified name pattern. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "git.repository.deleted", + "resource": { + "repository": { + "id": "00000000-0000-0000-0000-000000000000repository-id", + "name": "repository-name", + "url": "repository-url", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + } + } + }, + "createdDate": "2024-07-17T21:34:22.338Z" +} +``` + +### Repository forked + +Event: A repository is forked. + +* Publisher ID: `azure-devops` +* Event ID: `git.repository.forked` +* Resource Name: `repository` + +#### Settings + +* `project`: Filter events to include only repositories forked within the specified project. +* `sourceRepositoryName`: Filter events to include only forks of repositories with the specified source repository name pattern. +* `forkedRepositoryName`: Filter events to include only repositories with the specified forked repository name pattern. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "git.repository.forked", + "resource": { + "repository": { + "id": "00000000-0000-0000-0000-000000000000forked-repository-id", + "name": "forked-repository-name", + "url": "forked-repository-url", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + }, + "sourceRepository": { + "id": "00000000-0000-0000-0000-000000000000source-repository-id", + "name": "source-repository-name", + "url": "source-repository-url" + } + } + }, + "createdDate": "2024-07-17T21:34:22.338Z" +} +``` + +### Repository renamed + +Filter events to include only renamed repositories. + +* Publisher ID: `azure-devops` +* Event ID: `git.repository.renamed` +* Resource Name: `repository` + +#### Settings + +* `project`: Filter events to include only repositories renamed within the specified project. +* `oldRepositoryName`: Filter events to include only repositories with the specified old name pattern. +* `newRepositoryName`: Filter events to include only repositories with the specified new name pattern. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "git.repository.renamed", + "resource": { + "repository": { + "id": "00000000-0000-0000-0000-000000000000repository-id", + "oldName": "old-repository-name", + "newName": "new-repository-name", + "url": "repository-url", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + } + } + }, + "createdDate": "2024-07-17T21:34:22.338Z" +} +``` + +### Repository status changed + +Event: A repository status is changed. + +* Publisher ID: `azure-devops` +* Event ID: `git.repository.statusChanged` +* Resource Name: `repository` + +#### Settings + +* `project`: Filter events to include only repositories within the specified project. +* `repositoryName`: Filter events to include only repositories with the specified name pattern. +* `oldStatus`: Filter events to include only repositories with the specified old status. +* `newStatus`: Filter events to include only repositories with the specified new status. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "git.repository.statusChanged", + "resource": { + "repository": { + "id": "00000000-0000-0000-0000-000000000000repository-id", + "name": "repository-name", + "url": "repository-url", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + }, + "oldStatus": "old-status", + "newStatus": "new-status" + } + }, + "createdDate": "2024-07-17T21:34:22.338Z" +} +``` + +### Service connection created + +Event: A new service connection is created. + +* Publisher ID: `azure-devops` +* Event ID: `serviceendpoint.created` +* Resource Name: `serviceendpoint` + +#### Settings + +* `project`: Filter events to include only service connections created within the specified project. +* `serviceConnectionType`: Filter events to include only service connections of the specified type. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "serviceendpoint.created", + "resource": { + "serviceEndpoint": { + "id": "00000000-0000-0000-0000-000000000000service-connection-id", + "name": "service-connection-name", + "type": "service-connection-type", + "url": "service-connection-url", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + } + } + }, + "createdDate": "2024-07-17T21:34:22.338Z" +} +``` + +### Service connection updated + +Event: A service connection is updated. + +* Publisher ID: `azure-devops` +* Event ID: `serviceendpoint.updated` +* Resource Name: `serviceendpoint` + +#### Settings + +* `project`: Filter events to include only service connections updated within the specified project. +* `serviceConnectionType`: Filter events to include only service connections of the specified type. + +#### Sample payload + +```json +{ + "publisherId": "azure-devops", + "eventId": "serviceendpoint.updated", + "resource": { + "serviceEndpoint": { + "id": "00000000-0000-0000-0000-000000000000service-connection-id", + "name": "service-connection-name", + "type": "service-connection-type", + "url": "service-connection-url", + "project": { + "id": "00000000-0000-0000-0000-000000000000project-id", + "name": "project-name" + } + } + }, + "updatedDate": "2024-07-17T21:34:22.338Z" } ``` @@ -2430,9 +2679,9 @@ Event: A pull request is updated; status, review list, reviewer vote changed, or ### Work item created -Filter events to include only newly created work items. +Event: A new work item is created. -* Publisher ID: `tfs` +* Publisher ID: `azure-devops` * Event ID: `workitem.created` * Resource Name: `workitem` @@ -2445,19 +2694,19 @@ Filter events to include only newly created work items. ```json { - "id": "d2d46fb1-dba5-403c-9373-427583f19e8c", + "id": "00000000-0000-0000-0000-000000000000", "eventType": "workitem.created", - "publisherId": "tfs", + "publisherId": "azure-devops", "scope": "all", "message": { - "text": "Bug #5 (Some great new idea!) created by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5)", + "text": "Bug #5 (Some great new idea!) created by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000)", "html": "Bug #5 (Some great new idea!) created by Jamal Hartnett.", - "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5) (Some great new idea!) created by Jamal Hartnett." + "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000) (Some great new idea!) created by Jamal Hartnett." }, "detailedMessage": { - "text": "Bug #5 (Some great new idea!) created by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5)\r\n\r\n- Area: FabrikamCloud\r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n- State: New\r\n- Assigned to: \r\n- Comment: \r\n- Severity: 3 - Medium\r\n", - "html": "Bug #5 (Some great new idea!) created by Jamal Hartnett.
        \r\n
      • Area: FabrikamCloud
        • \r\n
      • Iteration: FabrikamCloud\\Release 1\\Sprint 1
        • \r\n
      • State: New
        • \r\n
      • Assigned to:
        • \r\n
      • Comment:
        • \r\n
      • Severity: 3 - Medium
      ", - "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5) (Some great new idea!) created by Jamal Hartnett.\r\n\r\n* Area: FabrikamCloud\r\n* Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n* State: New\r\n* Assigned to: \r\n* Comment: \r\n* Severity: 3 - Medium\r\n" + "text": "Bug #5 (Some great new idea!) created by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000)\r\n\r\n- Area: FabrikamCloud\r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n- State: New\r\n- Assigned to: \r\n- Comment: \r\n- Severity: 3 - Medium\r\n", + "html": "Bug #5 (Some great new idea!) created by Jamal Hartnett.
        \r\n- Area: FabrikamCloud
        \r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1
        \r\n- State: New
        \r\n- Assigned to:
        \r\n- Comment:
        \r\n- Severity: 3 - Medium
      ", + "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000) (Some great new idea!) created by Jamal Hartnett.\r\n\r\n* Area: FabrikamCloud\r\n* Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n* State: New\r\n* Assigned to: \r\n* Comment: \r\n* Severity: 3 - Medium\r\n" }, "resource": { "id": 5, @@ -2499,16 +2748,16 @@ Filter events to include only newly created work items. "resourceVersion": "1.0", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:29.7688022Z" + "createdDate": "2024-09-19T13:03:29.7688022Z" } ``` @@ -2516,9 +2765,9 @@ Filter events to include only newly created work items. ### Work item deleted -Filter events to include only newly deleted work items. +Event: A work item is deleted. -* Publisher ID: `tfs` +* Publisher ID: `azure-devops` * Event ID: `workitem.deleted` * Resource Name: `resource` @@ -2531,9 +2780,9 @@ Filter events to include only newly deleted work items. ```json { - "id": "72da0ade-0709-40ee-beb7-104287bf7e84", + "id": "00000000-0000-0000-0000-00000000000072da0ade-0709-40ee-beb7-104287bf7e84", "eventType": "workitem.deleted", - "publisherId": "tfs", + "publisherId": "azure-devops", "scope": "all", "message": { "text": "Bug #5 (Some great new idea!) deleted by Jamal Hartnett.", @@ -2542,7 +2791,7 @@ Filter events to include only newly deleted work items. }, "detailedMessage": { "text": "Bug #5 (Some great new idea!) deleted by Jamal Hartnett.\r\n\r\n- Area: FabrikamCloud\r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n- State: New\r\n", - "html": "Bug #5 (Some great new idea!) deleted by Jamal Hartnett.
        \r\n
      • Area: FabrikamCloud
        • \r\n
      • Iteration: FabrikamCloud\\Release 1\\Sprint 1
        • \r\n
      • State: New
      ", + "html": "Bug #5 (Some great new idea!) deleted by Jamal Hartnett.
        \r\n- Area: FabrikamCloud
        \r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1
        \r\n- State: New
      ", "markdown": "[Bug #5](Some great new idea!) deleted by Jamal Hartnett.\r\n\r\n* Area: FabrikamCloud\r\n* Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n* State: New\r\n" }, "resource": { @@ -2579,16 +2828,16 @@ Filter events to include only newly deleted work items. "resourceVersion": "1.0", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:30.0657064Z" + "createdDate": "2024-09-19T13:03:30.0657064Z" } ``` @@ -2596,9 +2845,9 @@ Filter events to include only newly deleted work items. ### Work item restored -Filter events to include only newly restored work items. +Event: A work item is newly restored. -* Publisher ID: `tfs` +* Publisher ID: `azure-devops` * Event ID: `workitem.restored` * Resource Name: `resource` @@ -2611,19 +2860,19 @@ Filter events to include only newly restored work items. ```json { - "id": "1ca023d6-6cff-49dd-b3d1-302b69311810", + "id": "00000000-0000-0000-0000-0000000000001ca023d6-6cff-49dd-b3d1-302b69311810", "eventType": "workitem.restored", - "publisherId": "tfs", + "publisherId": "azure-devops", "scope": "all", "message": { - "text": "Bug #5 (Some great new idea!) restored by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5)", + "text": "Bug #5 (Some great new idea!) restored by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000)", "html": "Bug #5 (Some great new idea!) restored by Jamal Hartnett.", - "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5) (Some great new idea!) restored by Jamal Hartnett." + "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000) (Some great new idea!) restored by Jamal Hartnett." }, "detailedMessage": { - "text": "Bug #5 (Some great new idea!) restored by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5)\r\n\r\n- Area: FabrikamCloud\r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n- State: New\r\n- Severity: 3 - Medium\r\n", - "html": "Bug #5 (Some great new idea!) restored by Jamal Hartnett.
        \r\n
      • Area: FabrikamCloud
        • \r\n
      • Iteration: FabrikamCloud\\Release 1\\Sprint 1
        • \r\n
      • State: New
        • Severity: 3 - Medium
      ", - "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5) (Some great new idea!) restored by Jamal Hartnett.\r\n\r\n* Area: FabrikamCloud\r\n* Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n* State: New\r\n* Severity: 3 - Medium\r\n" + "text": "Bug #5 (Some great new idea!) restored by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000)\r\n\r\n- Area: FabrikamCloud\r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n- State: New\r\n- Severity: 3 - Medium\r\n", + "html": "Bug #5 (Some great new idea!) restored by Jamal Hartnett.
        \r\n- Area: FabrikamCloud
        \r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1
        \r\n- State: New
        Severity: 3 - Medium
      ", + "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000) (Some great new idea!) restored by Jamal Hartnett.\r\n\r\n* Area: FabrikamCloud\r\n* Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n* State: New\r\n* Severity: 3 - Medium\r\n" }, "resource": { "id": 5, @@ -2671,16 +2920,16 @@ Filter events to include only newly restored work items. "resourceVersion": "1.0", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:30.1456784Z" + "createdDate": "2024-09-19T13:03:30.1456784Z" } ``` @@ -2688,38 +2937,40 @@ Filter events to include only newly restored work items. ### Work item updated -Filter events to include only changed work items. +Event: A work item is changed. -* Publisher ID: `tfs` +* Publisher ID: `azure-devops` * Event ID: `workitem.updated` * Resource Name: `workitem` > [!NOTE] -> Creating a Service Hooks subscription with multiple fields is not supported through the UI, but you can achieve this by either [creating a custom payload through the API](/rest/api/azure/devops/hooks/subscriptions/create), or by creating separate Service Hooks subscriptions for each field. +> You can't create a Service Hooks subscription with multiple fields through the UI. But, you can do so in the following ways: +> - [Create a custom payload through the API](/rest/api/azure/devops/hooks/subscriptions/create) +> - [Create separate Service Hooks subscriptions for each field](#create-a-service-hooks-subscription) #### Settings * `areaPath`: Filter events to include only work items under the specified area path. - * `changedFields`: Filter events to include only work items with the specified field(s) changed. + * `changedFields`: Filter events to include only work items with the specified field changed. * `workItemType`: Filter events to include only work items of the specified type. #### Sample payload ```json { - "id": "1ca023d6-6cff-49dd-b3d1-302b69311810", + "id": "00000000-0000-0000-0000-0000000000001ca023d6-6cff-49dd-b3d1-302b69311810", "eventType": "workitem.updated", - "publisherId": "tfs", + "publisherId": "azure-devops", "scope": "all", "message": { - "text": "Bug #5 (Some great new idea!) updated by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5)", + "text": "Bug #5 (Some great new idea!) updated by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000)", "html": "Bug #5 (Some great new idea!) updated by Jamal Hartnett.", - "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5) (Some great new idea!) updated by Jamal Hartnett." + "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000) (Some great new idea!) updated by Jamal Hartnett." }, "detailedMessage": { - "text": "Bug #5 (Some great new idea!) updated by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5)\r\n\r\n- Area: FabrikamCloud\r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n- State: New\r\n- Severity: 3 - Medium\r\n", - "html": "Bug #5 (Some great new idea!) updated by Jamal Hartnett.
        \r\n
      • Area: FabrikamCloud
        • \r\n
      • Iteration: FabrikamCloud\\Release 1\\Sprint 1
        • \r\n
      • State: New
        • Severity: 3 - Medium
      ", - "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5) (Some great new idea!) updated by Jamal Hartnett.\r\n\r\n* Area: FabrikamCloud\r\n* Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n* State: New\r\n* Severity: 3 - Medium\r\n" + "text": "Bug #5 (Some great new idea!) updated by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000)\r\n\r\n- Area: FabrikamCloud\r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n- State: New\r\n- Severity: 3 - Medium\r\n", + "html": "Bug #5 (Some great new idea!) updated by Jamal Hartnett.
        \r\n- Area: FabrikamCloud
        \r\n- Iteration: FabrikamCloud\\Release 1\\Sprint 1
        \r\n- State: New
        Severity: 3 - Medium
      ", + "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000) (Some great new idea!) updated by Jamal Hartnett.\r\n\r\n* Area: FabrikamCloud\r\n* Iteration: FabrikamCloud\\Release 1\\Sprint 1\r\n* State: New\r\n* Severity: 3 - Medium\r\n" }, "resource": { "id": 5, @@ -2767,27 +3018,37 @@ Filter events to include only changed work items. "resourceVersion": "1.0", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:30.1456784Z" + "createdDate": "2024-09-19T13:03:30.1456784Z" } ``` +#### Create a service hooks subscription + +Do the following steps to create a service hooks subscription for each work item field. +1. Go to your **Project settings**. +2. Select **Service Hooks** > + **Create subscription**. +3. Choose **Web Hooks** as the type of event > **Next**. +4. Select **Work item updated** as the type of trigger event. +5. Specify the field you want to monitor for changes in the subscription configuration dialog. For example, if you want to track changes in the **State** field, set the filter to **Field: State**. You can also filter events to include only items under a specified area path, only specified work item types, and only work items containing a specified tag. +6. Select **Next**. +7. Continue in the SETTINGS dialog, and then **Test** or **Finish** creating your subscription. ### Work item commented on -Filter events to include only work items commented on. +Event: A work item is commented on. -* Publisher ID: `tfs` +* Publisher ID: `azure-devops` * Event ID: `workitem.commented` * Resource Name: `workitem` @@ -2801,19 +3062,19 @@ Filter events to include only work items commented on. ```json { - "id": "fb2617ed-60df-4518-81fa-749faa6c5cd6", + "id": "00000000-0000-0000-0000-000000000000fb2617ed-60df-4518-81fa-749faa6c5cd6", "eventType": "workitem.commented", - "publisherId": "tfs", + "publisherId": "azure-devops", "scope": "all", "message": { - "text": "Bug #5 (Some great new idea!) commented on by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5)", + "text": "Bug #5 (Some great new idea!) commented on by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000)", "html": "Bug #5 (Some great new idea!) commented on by Jamal Hartnett.", - "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5) (Some great new idea!) commented on by Jamal Hartnett." + "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000) (Some great new idea!) commented on by Jamal Hartnett." }, "detailedMessage": { - "text": "Bug #5 (Some great new idea!) commented on by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5)\r\nThis is a great new idea", + "text": "Bug #5 (Some great new idea!) commented on by Jamal Hartnett.\r\n(https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000)\r\nThis is a great new idea", "html": "Bug #5 (Some great new idea!) commented on by Jamal Hartnett.
      This is a great new idea", - "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=74e918bf-3376-436d-bd20-8e8c1287f465&id=5) (Some great new idea!) commented on by Jamal Hartnett.\r\nThis is a great new idea" + "markdown": "[Bug #5](https://dev.azure.com/fabrikam-fiber-inc/web/wi.aspx?pcguid=00000000-0000-0000-0000-000000000000) (Some great new idea!) commented on by Jamal Hartnett.\r\nThis is a great new idea" }, "resource": { "id": 5, @@ -2845,7 +3106,7 @@ Filter events to include only work items commented on. "href": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/wit/workItems/5/revisions" }, "workItemType": { - "href": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/wit/ea830882-2a3c-4095-a53f-972f9a376f6e/workItemTypes/Bug" + "href": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/wit/00-00-00/workItemTypes/Bug" }, "fields": { "href": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection/_apis/wit/fields" @@ -2856,16 +3117,16 @@ Filter events to include only work items commented on. "resourceVersion": "1.0", "resourceContainers": { "collection": { - "id": "c12d0eb8-e382-443b-9f9c-c52cba5014c2" + "id": "00000000-0000-0000-0000-000000000000" }, "account": { - "id": "f844ec47-a9db-4511-8281-8b63f4eaf94e" + "id": "00000000-0000-0000-0000-000000000000" }, "project": { - "id": "be9b3917-87e6-42a4-a549-2bc06a7a878f" + "id": "00000000-0000-0000-0000-000000000000" } }, - "createdDate": "2016-09-19T13:03:28.9695265Z" + "createdDate": "2024-09-19T13:03:28.9695265Z" } ``` ## Resource containers @@ -2873,3 +3134,9 @@ Filter events to include only work items commented on. The event payload contains a `resourceContainers` dictionary that includes the IDs of the project, collection/account, or server that the event initiated from. Some products/environments also include a `baseUrl` field with each entry that provides the full URL to the container. You can use this URL to create a connection to the container to make REST API calls. + +## Related articles + +- [Integrate with service hooks](overview.md) +- [Create a service hook subscription programmatically](create-subscription.md) +- [Service hook consumers](consumers.md) \ No newline at end of file diff --git a/docs/service-hooks/media/Authorizations.png b/docs/service-hooks/media/Authorizations.png index e1547a07908..fafba954e85 100644 Binary files a/docs/service-hooks/media/Authorizations.png and b/docs/service-hooks/media/Authorizations.png differ diff --git a/docs/service-hooks/media/Profile-manage-applications.png b/docs/service-hooks/media/Profile-manage-applications.png index 18432786a9f..5159e33993e 100644 Binary files a/docs/service-hooks/media/Profile-manage-applications.png and b/docs/service-hooks/media/Profile-manage-applications.png differ diff --git a/docs/service-hooks/media/permissions/no-permission-service-hooks.png b/docs/service-hooks/media/permissions/no-permission-service-hooks.png new file mode 100644 index 00000000000..bbbc5f9042f Binary files /dev/null and b/docs/service-hooks/media/permissions/no-permission-service-hooks.png differ diff --git a/docs/service-hooks/media/permissions/service-hooks-subscriptions-with-permission.png b/docs/service-hooks/media/permissions/service-hooks-subscriptions-with-permission.png new file mode 100644 index 00000000000..be610254fd0 Binary files /dev/null and b/docs/service-hooks/media/permissions/service-hooks-subscriptions-with-permission.png differ diff --git a/docs/service-hooks/overview.md b/docs/service-hooks/overview.md index 90c6b29a5e3..891559d8413 100644 --- a/docs/service-hooks/overview.md +++ b/docs/service-hooks/overview.md @@ -7,14 +7,14 @@ ms.topic: conceptual ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 11/21/2022 +ms.date: 07/19/2024 --- # Integrate with service hooks [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Service hooks let you run tasks on other services when events happen in your project in Azure DevOps. +Service Hooks let you run tasks on other services when events happen in your project in Azure DevOps. For example, you can create a card in Trello when a work item gets created or send a push notification to your team's mobile devices when a build fails. You can also use service hooks in custom apps and services as a more efficient way to drive activities when events happen in your projects. @@ -35,44 +35,62 @@ when events occur. ::: moniker-end - ## Available services The following services are available as the target of service hooks. For more information about other apps and services that integrate with Azure DevOps, go to the [Visual Studio Marketplace](https://marketplace.visualstudio.com/#AzureDevOpsServices). +::: moniker range="= azure-devops" |Service |Supported events | Supported actions | |---------|---------|-------| -|[App Center](/appcenter/dashboard/bugtracker/) |Work item updated | Send notification | -|[AppVeyor](https://www.appveyor.com/docs/) | Code pushed |Trigger an AppVeyor build | -|[Azuqua](https://go.microsoft.com/fwlink/?LinkID=521778) | All | Post event to FLO | -|[Azure App Service](https://go.microsoft.com/fwlink/?LinkId=613645) | Code pushed | Deploy web app | -|[Azure Service Bus](/azure/devops/pipelines/tasks/reference/publish-to-azure-service-bus-v1) | All | Send a message to a Notification Hub, Service Bus Queue, or Service Bus Topic | -|[Azure Storage](/azure/azure-functions/functions-integrate-storage-queue-output-binding) | All | Insert a message in a Storage Queue | -|[Bamboo](https://confluence.atlassian.com/bamboo/using-webhooks-1018270680.html) | Build completed, Code pushed | Queue a build | -|[Campfire](https://go.microsoft.com/fwlink/?LinkID=393613) | All | Post a message to a room | -|[Datadog](./services/datadog.md) | All | Post an event in Datadog | -|[Grafana](./services/grafana.md) | Release deployment completed | Add annotation to Grafana database | -|HipChat | (No longer supported) | | -|[HockeyApp](https://aka.ms/vsts-hockeyapp-integration) | Work item updated| Send notification | -|[Jenkins](./services/jenkins.md) | Build completed, code pushed, PR merge attempted, release deployment completed | Trigger generic or Git build | -|[Microsoft Teams](./services/teams.md) | All | Post a message to a channel | -|[MyGet](https://docs.myget.org/docs/reference/webhooks) | Build completed, code pushed | Publish NuGet package to MyGet, trigger a MyGet build | -|[Office 365](/office/office-365-management-api/office-365-management-activity-api-reference#start-a-subscription) | All | Post a message to a group | -|[Slack](./services/slack.md) | All | Post a message to a channel | -|[Trello](./services/trello.md) | All | Create a card or list | -|[UserVoice](https://feedback.uservoice.com/knowledgebase/articles/363410-vsts-azure-devops-integration) | Work item created or updated | Send linked work item event | -|[Web Hooks](./services/webhooks.md) | All | Post via HTTP | -|[Workplace Message Apps](https://aka.ms/WorkplaceMessagingApps-Integration) | All | Send notifications | -|[Zapier](https://zapier.com/apps/webhook/integrations) | All | Send notification | -| [Zendesk](https://support.zendesk.com/hc/articles/204890268-Creating-webhooks-with-the-HTTP-target) | Work item commented on | Create a private comment in a ticket | +|[App Center](/appcenter/dashboard/bugtracker/) | Work item updated | Send notification. Subscriptions are managed through App Center. | +|[AppVeyor](https://www.appveyor.com/docs/) | Code pushed |Trigger an AppVeyor build. Subscriptions are managed through AppVeyor. | +|[Azuqua](https://go.microsoft.com/fwlink/?LinkID=521778) | All | Post event to FLO. Subscriptions are managed through Azuqua. | +|[Azure App Service](https://go.microsoft.com/fwlink/?LinkId=613645) | Code pushed | Deploy web app. Subscriptions are managed through Azure App Service. | +|[Azure Service Bus](/azure/devops/pipelines/tasks/reference/publish-to-azure-service-bus-v1) | All | Send a message to a Notification Hub, Service Bus Queue, or Service Bus Topic. Subscription is managed through Azure App Service. | +|[Azure Storage](/azure/azure-functions/functions-integrate-storage-queue-output-binding) | All | Insert a message in a Storage Queue. | +|[Bamboo](https://confluence.atlassian.com/bamboo/using-webhooks-1018270680.html) | Build completed, Code pushed | Queue a build. | +|[Datadog](./services/datadog.md) | All | Post an event in Datadog. | +|[Grafana](./services/grafana.md) | Release deployment completed | Add annotation to Grafana database.| +|[Jenkins](./services/jenkins.md) | Build completed, code pushed, PR merge attempted, release deployment completed | Trigger generic or Git build. | +|[Microsoft Teams](./services/teams.md) | All | Post a message to a channel. Subscriptions are managed in Microsoft Teams. | +|[MyGet](https://docs.myget.org/docs/reference/webhooks) | Build completed, code pushed | Publish NuGet package to MyGet. Trigger a MyGet build. Subscriptions are managed by MyGet. | +|[Office 365](/office/office-365-management-api/office-365-management-activity-api-reference#start-a-subscription) | All | Post a message to a group. | +|[Slack](./services/slack.md) | All | Post a message to a channel. | +|[Trello](./services/trello.md) | All | Create a card or list. | +|[UserVoice](https://www.uservoice.com) | Work item created, work item updated | Send linked work item event. Subscriptions are managed through UserVoice. | +|[Web Hooks](./services/webhooks.md) | All | Post via HTTP. | +|[Workplace Message Apps](https://aka.ms/WorkplaceMessagingApps-Integration) | All | Send notifications. Subscriptions are managed through Workplace Message Apps.| +|[Zapier](https://zapier.com/apps/webhook/integrations) | All | Send notification. Subscriptions are managed through Zapier. | +| [Zendesk](https://support.zendesk.com/hc/articles/204890268-Creating-webhooks-with-the-HTTP-target) | Work item commented on | Create a private comment in a ticket. | + +::: moniker-end + +::: moniker range="<= azure-devops-2022" + +|Service |Supported events | Supported actions | +|---------|---------|-------| +|[Azure Service Bus](/azure/devops/pipelines/tasks/reference/publish-to-azure-service-bus-v1) | All | Send a message to a Notification Hub, Service Bus Queue, or Service Bus Topic. Subscription is managed through Azure App Service. | +|[Azure Storage](/azure/azure-functions/functions-integrate-storage-queue-output-binding) | All | Insert a message in a Storage Queue. | +|[Bamboo](https://confluence.atlassian.com/bamboo/using-webhooks-1018270680.html) | Build completed, Code pushed | Queue a build. | +|[Datadog](./services/datadog.md) | All | Post an event in Datadog. | +|[Grafana](./services/grafana.md) | Release deployment completed | Add annotation to Grafana database.| +|[Jenkins](./services/jenkins.md) | Build completed, code pushed, PR merge attempted, release deployment completed | Trigger generic or Git build. | +|[Microsoft Teams](./services/teams.md) | All | Post a message to a channel. Subscriptions are managed in Microsoft Teams. | +|[Office 365](/office/office-365-management-api/office-365-management-activity-api-reference#start-a-subscription) | All | Post a message to a group. | +|[Slack](./services/slack.md) | All | Post a message to a channel. | +|[Trello](./services/trello.md) | All | Create a card or list. | +|[UserVoice]((https://www.uservoice.com) | Work item created, work item updated | Send linked work item event. Subscriptions are managed through UserVoice. | +|[Web Hooks](./services/webhooks.md) | All | Post via HTTP. | +| [Zendesk](https://support.zendesk.com/hc/articles/204890268-Creating-webhooks-with-the-HTTP-target) | Work item commented on | Create a private comment in a ticket. | + +::: moniker-end ## Create a subscription -When you integrate one of these services with Azure DevOps, you must create a new subscription. In many cases, you need to do some work in the other service, too. For specific details, -check out the information on the service that you're interested in. +When you integrate one of these services with Azure DevOps, you must create a new subscription. In many cases, you need to do some configuration in the other service, too. For specific details, check out the information for the service that you're interested in. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Open the admin page for a project in web access. @@ -105,62 +123,25 @@ check out the information on the service that you're interested in. ::: moniker-end -::: moniker range="tfs-2018" - -1. Open the admin page for a project in web access. - - :::image type="content" source="./media/openadmin.png" alt-text="Screenshot of the admin page."::: - -1. Create a subscription by running the wizard. - - :::image type="content" source="./media/createfirst.png" alt-text="Screenshot of highlighted box, Create subscription, to select to run the subscription wizard."::: - -1. Select the service you want to integrate with. - - :::image type="content" source="./media/select-service.png" alt-text="Screenshot showing services selection to integrate."::: - -1. Select the event to trigger on and any filters (if applicable). - - :::image type="content" source="./media/trello-wizard-event.png" alt-text="Screenshot showing selection of the event to trigger on."::: - -1. Select an action to run on the target service. - - > [!NOTE] - > The list of available actions may be limited based on the event type you selected. - - :::image type="content" source="./media/trello-wizard-action.png" alt-text="Screenshot showing selected action to perform on the target service."::: - -1. To confirm the settings are correct, test the subscription and then finish the wizard. - - :::image type="content" source="./media/test1.png" alt-text="Screenshot showing test notification 1."::: - - :::image type="content" source="./media/test2.png" alt-text="Screenshot showing test notification 2."::: - -::: moniker-end - ## FAQs - + ### Q: What permissions do I need to set up a subscription? A: *Edit subscriptions* and *View subscriptions*. By default, only project administrators have these permissions. To grant them to other users directly, you can use the [command line tool](../organizations/security/manage-tokens-namespaces.md) or the [Security](/rest/api/azure/devops/security/) REST API. +To grant *View* permission for a group, see [Set *View* permission for a group in Service Hooks](view-permission.md) page. + ### Q: What are the security implications of granting *Edit subscriptions* and *View subscriptions* permissions? A: The user with these permissions can see all subscriptions created in the project and the notification history for those subscriptions. That user can then -create any type of service hook subscription in that project. If the user sets up a -subscription for a resource that they don't otherwise have permission to access, the -subscription won't get triggered. +create any type of service hook subscription in that project. If the user sets up a subscription for a resource that they don't otherwise have permission to access, the subscription won't be triggered. -**For example:** If you don't have access to work items in area path XYZ, and you set up a -subscription to the work item update events, you don't get notifications for updates -to work items in area path XYZ. But, if another user, who does have access to the work -items in area path XYZ, receives those "work item update" events, then you could see the -notification history of the other user's events, which includes work item data that you -don't otherwise have access to. +**For example:** +Subscriptions you create for work item update events in area path XYZ won't send notifications if you lack access to those work items. However, you can see the notification history of other users who do have access to those work items. ### Q: Can I create service hook subscriptions for a project programmatically? @@ -182,11 +163,11 @@ A: Yes. You can revoke authorizations from your profile. 3. Revoke any authorizations you no longer want to allow. - :::image type="content" source="media/Authorizations.png" alt-text="Screenshot showing Revoke option for authorizations."::: + :::image type="content" source="media/authorizations.png" alt-text="Screenshot showing Revoke option for authorizations."::: ### Q: Why can't we set up service hooks for HipChat anymore? -A: Atlassian officially dropped support for HipChat. See more on that announcement [here](https://www.atlassian.com/partnerships/slack/faq#faq-3ccc5a61-711b-4ef2-9ca2-3a34b2ec143b). +A: Atlassian officially dropped support for HipChat. For more information, see [the announcement](https://www.atlassian.com/partnerships/slack/faq#faq-3ccc5a61-711b-4ef2-9ca2-3a34b2ec143b). ## Related articles diff --git a/docs/service-hooks/services/datadog.md b/docs/service-hooks/services/datadog.md index 25111d958b1..6685f626f65 100644 --- a/docs/service-hooks/services/datadog.md +++ b/docs/service-hooks/services/datadog.md @@ -6,7 +6,7 @@ description: Use Datadog with your Azure DevOps Services organization ms.assetid: 7472f06c-11f3-4603-953c-9a0de5abe29d ms.author: chcomley author: chcomley -monikerRange: '>= azure-devops-2019' +monikerRange: "<=azure-devops" ms.date: 11/03/2020 --- # Create a service hook for Azure DevOps with Datadog @@ -16,15 +16,15 @@ ms.date: 11/03/2020 Learn how to create events and metrics in Datadog in response to events from Azure DevOps. Use these metrics and events in Datadog to create dashboards, troubleshoot issues, and create monitors to alert you of critical issues. Datadog accepts all Azure DevOps event types. > [!IMPORTANT] -> The Datadog feature may not be turned on by default for Azure DevOps Server 2019 and 2020. This is a known issue. Until it's resolved, you can use the following SQL command in your config database to turn on the feature: +> The Datadog feature might not be turned on by default for Azure DevOps Server 2019 and 2020, which is a known issue. Until it resolves, you can use the following SQL command in your config database to turn on the feature: `exec prc_SetRegistryValue 1, '#\FeatureAvailability\Entries\ServiceHooks.Consumers.datadog\AvailabilityState\', 1` ## Prerequisites -1. You must have *Edit subscriptions* and *View subscriptions* permissions. By default, only project administrators have these permissions. To grant the permissions to other users, you can use the command-line tool or the [Security](/rest/api/azure/devops/security/?view=azure-devops-rest-6.0&preserve-view=true) REST API. -2. If you don't have a Datadog account, [get started with Datadog](https://aka.ms/AzureDevOpsDataDog). - a. In the Datadog application, go to [Integrations > API](https://aka.ms/AzureDevOpsDataDogAPI). - b. Create a new key or select an existing one, and then copy the key to your clipboard. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - Member of the [Project Collection Administrators group](../../organizations/security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.
      - **Edit subscriptions** and **View subscriptions** permissions set to **Allow**. By default, only project administrators have these permissions. To grant the permissions to other users, you can use the command-line tool or the [Security](/rest/api/azure/devops/security/?view=azure-devops-rest-6.0&preserve-view=true) REST API.| +|**Tools**|[Datadog](https://aka.ms/AzureDevOpsDataDog). In the Datadog application, go to [Integrations > API](https://aka.ms/AzureDevOpsDataDogAPI), create a new key or select an existing one, and then copy the key to your clipboard. | ## Start sending Azure DevOps events to Datadog @@ -64,11 +64,13 @@ A: Yes. For more information, see [Create a service hooks subscription programma - **US:** `https://app.datadoghq.com/intake/webhook/azuredevops?api_key=` - **EU:** `https://app.datadoghq.eu/intake/webhook/azuredevops?api_key=` - **US3:** `https://us3.datadoghq.com/intake/webhook/azuredevops?api_key=` +- **US5:** `https://us5.datadoghq.com/intake/webhook/azuredevops?api_key=` +- **AP1:** `https://ap1.datadoghq.com/intake/webhook/azuredevops?api_key=` - **Gov:** `https://app.ddog-gov.com/intake/webhook/azuredevops?api_key=` ### Q: How can I use these events in Datadog? -A: Azure DevOps events that are sent to Datadog are useful for creating dashboards, setting up monitors, and finding correlations during troubleshooting. You can also use them to get insights into how your developer operations processes impact application performance. +A: Azure DevOps events that are sent to Datadog are useful for creating dashboards, setting up monitors, and finding correlations during troubleshooting. You can also use them to get insights into how your developer operations processes affect application performance. ### Q: What event types can I send to Datadog? @@ -76,4 +78,4 @@ A: Datadog accepts all event types. ### Q: Can I get more general information about Datadog? -A: Yes, see [datadoghq.com](https://datadoghq.com). \ No newline at end of file +A: Yes, see [datadoghq.com](https://datadoghq.com). diff --git a/docs/service-hooks/services/grafana.md b/docs/service-hooks/services/grafana.md index dee94c8752a..67bb30683a9 100644 --- a/docs/service-hooks/services/grafana.md +++ b/docs/service-hooks/services/grafana.md @@ -4,9 +4,9 @@ ms.topic: conceptual title: Create a service hook for Grafana description: Annotate Grafana dashboards upon completion of deployments in Azure Pipelines ms.assetid: d588f4a0-8081-4684-b87e-64d3140b8b1c -ms.author: atulmal -author: azooinmyluggage -monikerRange: '>= azure-devops-2019' +ms.author: vijayma +author: vijayma +monikerRange: "<=azure-devops" ms.date: 07/27/2020 --- @@ -14,17 +14,16 @@ ms.date: 07/27/2020 [!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] -Grafana is an open source, feature-rich metrics dashboard and graph editor. It supports Graphite, Elasticsearch, OpenTSDB, Prometheus, and InfluxDB analytics services. Use the Grafana service hook to annotate Grafana dashboards upon completion of Azure Pipelines deployments. +Grafana is an open source, feature-rich metrics dashboard, and graph editor. It supports Graphite, Elasticsearch, OpenTSDB, Prometheus, and InfluxDB analytics services. Use the Grafana service hook to annotate Grafana dashboards upon completion of Azure Pipelines deployments. ![Grafana dashboard with annotations](./media/grafana/dashboard-with-annotations.png) +## Prerequisites -::: moniker range="azure-devops-2019" - -> [!NOTE] -> The service hook for Grafana is supported for Azure DevOps Server 2019.1 and later versions. - -::: moniker-end +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - Member of the [Project Collection Administrators group](../../organizations/security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.
      - **Edit subscriptions** and **View subscriptions** permissions set to **Allow**. By default, only project administrators have these permissions. To grant the permissions to other users, you can use the command-line tool or the [Security](/rest/api/azure/devops/security/?view=azure-devops-rest-6.0&preserve-view=true) REST API.| +|**Tools**|Grafana | ## Create a service hook subscription diff --git a/docs/service-hooks/services/jenkins.md b/docs/service-hooks/services/jenkins.md index 69035be432e..608d650450a 100644 --- a/docs/service-hooks/services/jenkins.md +++ b/docs/service-hooks/services/jenkins.md @@ -2,116 +2,77 @@ ms.subservice: azure-devops-service-hooks ms.custom: devx-track-jenkins ms.topic: conceptual -title: Create a service hook with Jenkins -description: Use Jenkins with your Azure DevOps organization +title: Create a service hook for Jenkins +description: See how to set up a service hook subscription to trigger a Jenkins build for your Azure DevOps project. ms.assetid: 3e9cf797-092f-48da-a515-e4d0cc93c4a1 monikerRange: '<= azure-devops' -ms.date: 10/01/2020 +ms.date: 08/13/2024 --- -# Create a service hook for Azure DevOps with Jenkins +# Create a service hook for Jenkins [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -If you use Jenkins to build your apps, you can store your code in Azure DevOps and continue to use Jenkins for your continuous integration builds. -You can trigger a Jenkins build when you push code to your project's -Git repository or when you check in code to Team Foundation version control. +This article describes how to set up a service hook for your Azure DevOps project to trigger a Jenkins build. If you use Jenkins to build your apps, you can store your code in a Git repository and use Jenkins for your continuous integration builds. You can trigger a Jenkins build when you push code to your Git repository or when you check in code to a [Team Foundation Version Control (TFVC)](../../repos/tfvc/what-is-tfvc.md) repository. -[!INCLUDE [alt-creds-deprecation-notice](../../includes/alt-creds-deprecation-notice.md)] +You can build part of your app in Azure Pipelines and part in Jenkins. You can trigger a Jenkins build when your Azure Pipelines build is completed so that you use both systems to build your app. -## Configure Jenkins +Azure DevOps doesn't charge for setting up service hooks or integrating with external services, and Jenkins is fully open-source and free to use. -1. If you haven't already, set up a [Jenkins](https://jenkins-ci.org/) server. +## Prerequisites -2. If you're setting up Jenkins on-premises, [enable HTTPS](https://jenkins.io/doc/book/installing/#configuring-http). +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - Member of the [Project Collection Administrators group](../../organizations/security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.
      - **Edit subscriptions** and **View subscriptions** permissions set to **Allow**. By default, only project administrators have these permissions. To grant the permissions to other users, you can use the command-line tool or the [Security](/rest/api/azure/devops/security/?view=azure-devops-rest-6.0&preserve-view=true) REST API.| +|**Tools**|[Jenkins](https://jenkins-ci.org/) server. If you set up Jenkins on-premises, [enable HTTPS](https://jenkins.io/doc/book/installing/#configuring-http). In your *jenkins.xml* configuration file, set the [hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL system property](https://plugins.jenkins.io/git/#plugin-content-push-notification-from-repository) to `disabled` by adding or updating the following line in the `` tag, before the `-jar` parameter:

      `-Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled`. | -3. Add or change `hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL` [system property](https://plugins.jenkins.io/git/#plugin-content-push-notification-from-repository) as **disabled** before -jar parameter inside of `` tag in _jenkins.xml_ configuration file. +## Create a Jenkins service hook - ` - -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled - ` +Do the following steps to create a Jenkins service hook. -## Set up a Jenkins build +### Set up a Jenkins build 1. In Jenkins, create a new item. - New item link in Jenkins + :::image type="content" source="./media/jenkins/new-item.png" alt-text="Screenshot showing New item link in Jenkins."::: -2. Create the type of build that's appropriate for your project. +1. Select the type of build that's appropriate for your project. - Build name and type in Jenkins + :::image type="content" source="./media/jenkins/my-build.png" alt-text="Screenshot showing Build name and type in Jenkins."::: -3. Set the URL for your Git repository in Azure DevOps Services. -The URL is in the form ```https://dev.azure.com/{orgName}/DefaultCollection/_git/{projectName}```. +1. Enter the URL for your Git repository. - Source code management settings with Git selected + :::image type="content" source="./media/jenkins/source-code-management-settings.png" alt-text="Screenshot showing Source code management settings in Jenkins with Git selected."::: -## Trigger Jenkins +### Set up the Jenkins service hook -::: moniker range=">= azure-devops-2019" +1. In your Azure DevOps project, go to **Project settings** > **Service hooks** at `https:////_settings/serviceHooks`. -1. Go to your project Service Hooks page: + :::image type="content" source="./media/add-devops-service-hook-new-name.png" alt-text="Screenshot of the Service hooks choice in Project settings."::: - `https://{orgName}/{project_name}/_settings/serviceHooks` +1. On the **Service Hooks** page, select the **+** icon or **Create subscription**. - ![Screenshot of project administration page, Azure DevOps Server 2019 and on.](./media/add-devops-service-hook.png) + :::image type="content" source="./media/add-service-hook.png" alt-text="Screenshot of selecting Create subscription on the Service Hooks page."::: - Select **Create Subscription**. +1. On the **Service** screen, select **Jenkins**, and then select **Next**. -2. Add Jenkins. + :::image type="content" source="./media/jenkins/target-service.png" alt-text="Screenshot of selecting Jenkins on the Service page."::: - Select target service dialog box, Jenkins selected +1. On the **Trigger** screen, select and configure the Azure DevOps event you want to trigger a Jenkins build, and then select **Next**. -3. Pick the event from Azure DevOps Services that you want to trigger a Jenkins build. + :::image type="content" source="./media/jenkins/configure-event.png" alt-text="Screenshot of selecting and configuring the trigger event."::: - Configure event dialog box +1. On the **Action** screen, configure the Jenkins action to take when the event occurs. -4. Configure the action to take in Jenkins. +1. Select **Test** to test the service hook, and **Finish** to finish the configuration. - New service hook subscription dialog box +Now when the event occurs in the Git repository, it triggers a Jenkins build. -::: moniker-end +> [!TIP] +> You can also create a service hook subscription programmatically with REST APIs. For more information, see [Create a service hook subscription programmatically](../create-subscription.md). -::: moniker range="tfs-2018" +## Related content -1. Go to your project Service Hooks page: - - `https://dev.azure.com/{orgName}/{project_name}/_apps/hub/ms.vss-servicehooks-web.manageServiceHooks-project` - - ![Screenshot of project administration page, TFS.](./media/add-service-hook.png) - - Select **Create Subscription**. - -2. Add Jenkins. - - Select target service dialog box, Jenkins selected - -3. Pick the event from Azure DevOps Services that you want to trigger a Jenkins build. - - Configure event dialog box - -4. Configure the action to take in Jenkins. - - New service hook subscription dialog box - -::: moniker-end - -Now, when that event occurs in Azure DevOps Services, your Jenkins build gets triggered. - -## Pricing -Azure DevOps Services doesn't charge for the framework for integrating with external services. Check out the specific service's site -for pricing related to their services. - -## Q & A - - - -#### Q: Can I build part of my app in Azure DevOps Services and part in Jenkins? - -A: Yes. You can trigger a Jenkins build when your Azure DevOps Services build is completed so that you use both systems to build your app. - -#### Q: Can I programmatically create subscriptions? - -A: Yes, use [REST APIs](../create-subscription.md). - - +- [Integrate with service hooks](../overview.md) +- [Service hooks events](../events.md) +- [Create a service hook subscription programmatically](../create-subscription.md) diff --git a/docs/service-hooks/services/media/add-devops-service-hook-new-name.png b/docs/service-hooks/services/media/add-devops-service-hook-new-name.png new file mode 100644 index 00000000000..f544ae5c0f8 Binary files /dev/null and b/docs/service-hooks/services/media/add-devops-service-hook-new-name.png differ diff --git a/docs/service-hooks/services/media/add-devops-service-hook.PNG b/docs/service-hooks/services/media/add-devops-service-hook.PNG index 3e4911cca92..f544ae5c0f8 100644 Binary files a/docs/service-hooks/services/media/add-devops-service-hook.PNG and b/docs/service-hooks/services/media/add-devops-service-hook.PNG differ diff --git a/docs/service-hooks/services/media/add-service-hook.png b/docs/service-hooks/services/media/add-service-hook.png index 6623d79ab36..7e2b4535dc4 100644 Binary files a/docs/service-hooks/services/media/add-service-hook.png and b/docs/service-hooks/services/media/add-service-hook.png differ diff --git a/docs/service-hooks/services/media/jenkins/alternate-credentials.png b/docs/service-hooks/services/media/jenkins/alternate-credentials.png deleted file mode 100644 index 02263128791..00000000000 Binary files a/docs/service-hooks/services/media/jenkins/alternate-credentials.png and /dev/null differ diff --git a/docs/service-hooks/services/media/jenkins/configure-event.png b/docs/service-hooks/services/media/jenkins/configure-event.png index 8b5c6bfaa59..022a8469d74 100644 Binary files a/docs/service-hooks/services/media/jenkins/configure-event.png and b/docs/service-hooks/services/media/jenkins/configure-event.png differ diff --git a/docs/service-hooks/services/media/jenkins/my-build.png b/docs/service-hooks/services/media/jenkins/my-build.png index e04ce228cef..8f8cdedd7c5 100644 Binary files a/docs/service-hooks/services/media/jenkins/my-build.png and b/docs/service-hooks/services/media/jenkins/my-build.png differ diff --git a/docs/service-hooks/services/media/jenkins/new-item.png b/docs/service-hooks/services/media/jenkins/new-item.png index f2bdc7a3e64..480c35f87cb 100644 Binary files a/docs/service-hooks/services/media/jenkins/new-item.png and b/docs/service-hooks/services/media/jenkins/new-item.png differ diff --git a/docs/service-hooks/services/media/jenkins/source-code-management-settings.png b/docs/service-hooks/services/media/jenkins/source-code-management-settings.png index 052fba5cbda..f4887167516 100644 Binary files a/docs/service-hooks/services/media/jenkins/source-code-management-settings.png and b/docs/service-hooks/services/media/jenkins/source-code-management-settings.png differ diff --git a/docs/service-hooks/services/media/jenkins/subscription.png b/docs/service-hooks/services/media/jenkins/subscription.png deleted file mode 100644 index f4844cbb70d..00000000000 Binary files a/docs/service-hooks/services/media/jenkins/subscription.png and /dev/null differ diff --git a/docs/service-hooks/services/media/jenkins/target-service.png b/docs/service-hooks/services/media/jenkins/target-service.png index f2e969dcc90..8e97cb1e82d 100644 Binary files a/docs/service-hooks/services/media/jenkins/target-service.png and b/docs/service-hooks/services/media/jenkins/target-service.png differ diff --git a/docs/service-hooks/services/media/slack/action.png b/docs/service-hooks/services/media/slack/action.png index ac9a2e1a917..6226e318299 100644 Binary files a/docs/service-hooks/services/media/slack/action.png and b/docs/service-hooks/services/media/slack/action.png differ diff --git a/docs/service-hooks/services/media/slack/copy-webhook.png b/docs/service-hooks/services/media/slack/copy-webhook.png deleted file mode 100644 index 642124641eb..00000000000 Binary files a/docs/service-hooks/services/media/slack/copy-webhook.png and /dev/null differ diff --git a/docs/service-hooks/services/media/slack/notifications.png b/docs/service-hooks/services/media/slack/notifications.png deleted file mode 100644 index b56b8ac20f7..00000000000 Binary files a/docs/service-hooks/services/media/slack/notifications.png and /dev/null differ diff --git a/docs/service-hooks/services/media/teams/Teams connector config 1.png b/docs/service-hooks/services/media/teams/Teams connector config 1.png deleted file mode 100644 index bcdc791955c..00000000000 Binary files a/docs/service-hooks/services/media/teams/Teams connector config 1.png and /dev/null differ diff --git a/docs/service-hooks/services/media/teams/Teams connector config tfs 1.png b/docs/service-hooks/services/media/teams/Teams connector config tfs 1.png deleted file mode 100644 index 77b3bd2474d..00000000000 Binary files a/docs/service-hooks/services/media/teams/Teams connector config tfs 1.png and /dev/null differ diff --git a/docs/service-hooks/services/media/teams/Teams connector config tfs 2.png b/docs/service-hooks/services/media/teams/Teams connector config tfs 2.png deleted file mode 100644 index bbf64102045..00000000000 Binary files a/docs/service-hooks/services/media/teams/Teams connector config tfs 2.png and /dev/null differ diff --git a/docs/service-hooks/services/media/teams/add-dashboard.png b/docs/service-hooks/services/media/teams/add-dashboard.png new file mode 100644 index 00000000000..cfe57f6cf01 Binary files /dev/null and b/docs/service-hooks/services/media/teams/add-dashboard.png differ diff --git a/docs/service-hooks/services/media/teams/choose-devops-organization.png b/docs/service-hooks/services/media/teams/choose-devops-organization.png new file mode 100644 index 00000000000..1898c34f826 Binary files /dev/null and b/docs/service-hooks/services/media/teams/choose-devops-organization.png differ diff --git a/docs/service-hooks/services/media/teams/connectors-list-s172.png b/docs/service-hooks/services/media/teams/connectors-list-s172.png deleted file mode 100644 index cb8e5a24875..00000000000 Binary files a/docs/service-hooks/services/media/teams/connectors-list-s172.png and /dev/null differ diff --git a/docs/service-hooks/services/media/teams/create-server.png b/docs/service-hooks/services/media/teams/create-server.png new file mode 100644 index 00000000000..24d72385c12 Binary files /dev/null and b/docs/service-hooks/services/media/teams/create-server.png differ diff --git a/docs/service-hooks/services/media/teams/open-teams-menu-s172.png b/docs/service-hooks/services/media/teams/open-teams-menu-s172.png deleted file mode 100644 index 5bba67027d7..00000000000 Binary files a/docs/service-hooks/services/media/teams/open-teams-menu-s172.png and /dev/null differ diff --git a/docs/service-hooks/services/media/teams/save-devops-config.png b/docs/service-hooks/services/media/teams/save-devops-config.png new file mode 100644 index 00000000000..988da41b6e6 Binary files /dev/null and b/docs/service-hooks/services/media/teams/save-devops-config.png differ diff --git a/docs/service-hooks/services/media/teams/search-azure-devops-server.png b/docs/service-hooks/services/media/teams/search-azure-devops-server.png new file mode 100644 index 00000000000..677d1914584 Binary files /dev/null and b/docs/service-hooks/services/media/teams/search-azure-devops-server.png differ diff --git a/docs/service-hooks/services/media/teams/search-azure-devops.png b/docs/service-hooks/services/media/teams/search-azure-devops.png new file mode 100644 index 00000000000..6eca505dab7 Binary files /dev/null and b/docs/service-hooks/services/media/teams/search-azure-devops.png differ diff --git a/docs/service-hooks/services/media/teams/set-up-a-connector.png b/docs/service-hooks/services/media/teams/set-up-a-connector.png new file mode 100644 index 00000000000..fe070d2efd6 Binary files /dev/null and b/docs/service-hooks/services/media/teams/set-up-a-connector.png differ diff --git a/docs/service-hooks/services/media/teams/set-up-connector-server.png b/docs/service-hooks/services/media/teams/set-up-connector-server.png new file mode 100644 index 00000000000..b0a3382a8eb Binary files /dev/null and b/docs/service-hooks/services/media/teams/set-up-connector-server.png differ diff --git a/docs/service-hooks/services/media/teams/set-up.png b/docs/service-hooks/services/media/teams/set-up.png new file mode 100644 index 00000000000..a02d1e336f4 Binary files /dev/null and b/docs/service-hooks/services/media/teams/set-up.png differ diff --git a/docs/service-hooks/services/media/teams/team-dashboard.png b/docs/service-hooks/services/media/teams/team-dashboard.png new file mode 100644 index 00000000000..d5104429ab4 Binary files /dev/null and b/docs/service-hooks/services/media/teams/team-dashboard.png differ diff --git a/docs/service-hooks/services/media/teams/teams-as-website.png b/docs/service-hooks/services/media/teams/teams-as-website.png deleted file mode 100644 index c4bf37538b5..00000000000 Binary files a/docs/service-hooks/services/media/teams/teams-as-website.png and /dev/null differ diff --git a/docs/service-hooks/services/media/webhooks/configure-action.png b/docs/service-hooks/services/media/webhooks/configure-action.png index c2d4a585d8d..74dc575e298 100644 Binary files a/docs/service-hooks/services/media/webhooks/configure-action.png and b/docs/service-hooks/services/media/webhooks/configure-action.png differ diff --git a/docs/service-hooks/services/media/webhooks/configure-event.png b/docs/service-hooks/services/media/webhooks/configure-event.png index e5762c8257b..d890abc7285 100644 Binary files a/docs/service-hooks/services/media/webhooks/configure-event.png and b/docs/service-hooks/services/media/webhooks/configure-event.png differ diff --git a/docs/service-hooks/services/media/webhooks/configure-service.png b/docs/service-hooks/services/media/webhooks/configure-service.png new file mode 100644 index 00000000000..1b8905e732d Binary files /dev/null and b/docs/service-hooks/services/media/webhooks/configure-service.png differ diff --git a/docs/service-hooks/services/media/webhooks/request-bin.png b/docs/service-hooks/services/media/webhooks/request-bin.png index a9e196bdc2f..3409204ebe6 100644 Binary files a/docs/service-hooks/services/media/webhooks/request-bin.png and b/docs/service-hooks/services/media/webhooks/request-bin.png differ diff --git a/docs/service-hooks/services/media/webhooks/test.png b/docs/service-hooks/services/media/webhooks/test.png index 2a7a9e781b8..47a4a6522cd 100644 Binary files a/docs/service-hooks/services/media/webhooks/test.png and b/docs/service-hooks/services/media/webhooks/test.png differ diff --git a/docs/service-hooks/services/slack.md b/docs/service-hooks/services/slack.md index 8546e19f215..1d1c421ae8d 100644 --- a/docs/service-hooks/services/slack.md +++ b/docs/service-hooks/services/slack.md @@ -1,62 +1,61 @@ --- ms.subservice: azure-devops-service-hooks -ms.topic: conceptual +ms.topic: how-to title: Create a service hook with Slack -description: Use Slack with your Azure DevOps Services organization +description: Use Slack with your Azure DevOps organization to create a service hook. ms.assetid: ea948249-1053-4971-99b9-ffa820c03803 monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 11/21/2023 --- # Create a service hook for Azure DevOps with Slack [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Post messages to [Slack](https://slack.com/) in response to events in your Azure DevOps organization, -such as completed builds, code changes, pull requests, releases, work items changes, and more. +In this article, learn how to post messages to [Slack](https://slack.com/) in response to events in your Azure DevOps organization, such as completed builds, code changes, pull requests, releases, work items changes, and more. ::: moniker range="azure-devops" > [!NOTE] -> For Azure DevOps Services, we recommend you use the following suite of apps which offer rich features, to integrate with Slack. +> For Azure DevOps Services, we recommend you use the following suite of apps which offer features to integrate with Slack. ### Azure Boards app for Slack [Azure Boards app for Slack](../../boards/integrations/boards-slack.md) helps to easily create and monitor work items from your Slack channels. -Users can create work items using a slash command, or use message actions to convert conversations in the channel into work items. -Users can also set up and manage subscriptions to get notifications in their channel whenever work items are created or updated. +You can create work items using a slash command, or use message actions to convert conversations in the channel into work items. +You can also set up and manage subscriptions to get notifications in their channel whenever work items are created or updated. ### Azure Pipelines app for Slack -[Azure Pipelines app for Slack](../../pipelines/integrations/slack.md) helps to easily monitor the events in your pipelines. Users can set up and manage -subscriptions for completed builds, releases, pending approvals and more from the app and get notifications for these events in their channels. Users can also approve release deployments from their channels. +The [Azure Pipelines app for Slack](../../pipelines/integrations/slack.md) helps to easily monitor the events in your pipelines. You can set up and manage +subscriptions for completed builds, releases, pending approvals and more from the app and get notifications for these events in their channels. You can also approve release deployments from your channels. ### Azure Repos app for Slack -[Azure Repos app for Slack](../../repos/integrations/repos-slack.md) helps to easily monitor the events in your repositories. Users can set up and manage subscriptions for code commits, PR creation and PR updates and more from the app and get notifications for these events in their channels. +The [Azure Repos app for Slack](../../repos/integrations/repos-slack.md) helps to easily monitor the events in your repositories. You can set up and manage subscriptions for code commits, PR creation and updates, and more, and get notifications for these events in their channels. ::: moniker-end ::: moniker range="<= azure-devops" -## Create a custom app in Slack +## Prerequisites -1. Refer to the [Slack documentation, Sending messages using Incoming Webhooks](https://api.slack.com/messaging/webhooks) to understand the process of using Web Hooks to push information to a Slack channel. +Refer to the [Slack documentation, Sending messages using Incoming Webhooks](https://api.slack.com/messaging/webhooks) to understand the process of using Web Hooks to push information to a Slack channel. -2. Create a new [Slack app](https://api.slack.com/apps/new) - ![Create slack app](./media/slack/create-slack-app.png) +## Create a custom app in Slack -3. Activate incoming Web Hook and add a new Web Hook to the desired workspace - ![incoming Web Hook](./media/slack/incoming-webhook.png) +1. Create a new [Slack app](https://api.slack.com/apps/new) + ![Create slack app](./media/slack/create-slack-app.png) - ![toggle Web Hook](./media/slack/toggle-webhook.png) +2. Activate incoming Web Hook and add a new Web Hook to the desired workspace + ![Screenshot of incoming Web Hook.](./media/slack/incoming-webhook.png) -4. Select the channel for which Web Hook must be created + ![Screenshot of Toggle Web Hook.](./media/slack/toggle-webhook.png) - ![create-Web Hook](./media/slack/create-webhook.png) +3. Select the channel for which Web Hook must be created. -5. Copy the Web Hook URL and go to Azure DevOps + ![Screenshot of Create Web Hook.](./media/slack/create-webhook.png) - ![copy Web Hook](./media/slack/copy-webhook.png) +4. Copy the Web Hook URL and go to Azure DevOps. ::: moniker-end @@ -65,71 +64,41 @@ subscriptions for completed builds, releases, pending approvals and more from th ## Create a service hook subscription in your organization ::: moniker-end -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -1. Go to your project **Service Hooks** page: +1. Go to your project **Service Hooks** page. `https://{orgName}/{project_name}/_settings/serviceHooks` - ![Project administration page](./media/add-devops-service-hook.png) + ![Screenshot of the Project administration page.](./media/add-devops-service-hook.png) Select **Create Subscription**. 2. Choose the types of events you want to appear in your Slack channel. - > You can filter each of the triggers in specific ways. - > For example, the *pull request created* trigger can be filtered on the repository in which the pull request occurs, - > the target branch it applies to, and the team members that are required or invited to review the request. + + You can filter each of the triggers in specific ways. + For example, filter the *pull request created* trigger on the repository in which the pull request occurs, the target branch it applies to, and the team members required or invited to review the request. 3. Paste the Web Hook URL from the Slack integration that you created and select **Finish**. - :::image type="content" source="./media/slack/action.png" alt-text="Action dialog box with the Web Hook URL."::: - -4. Now, when the event you configured occurs in your project, a notification appears in your team's Slack channel. + :::image type="content" source="./media/slack/action.png" alt-text="Screenshot of the Action dialog box with the Web Hook URL."::: - ![Screenshot showing a notification in a Slack channel.](./media/slack/notifications.png) + When the event occurs in your project, a notification appears in your team's Slack channel. ::: moniker-end -::: moniker range="tfs-2018" - -1. Go to your project Service Hooks page: - - `https://dev.azure.com/{orgName}/{project_name}/_apps/hub/ms.vss-servicehooks-web.manageServiceHooks-project` - - ![Project administration page](./media/add-service-hook.png) - - Select **Create Subscription**. - -2. Choose the types of events you want to appear in your Slack channel. - > You can filter each of the triggers in specific ways. - > For example, the *pull request created* trigger can be filtered on the repository in which the pull request occurs, - > the target branch it applies to, and the team members that are required or invited to review the request. - -3. Paste the Web Hook URL from the Slack integration that you created and select **Finish**. - - ![Action dialog box with the Web Hook URL]./media/slack/action.png) - -4. Now, when the event you configured occurs in your project, a notification appears in your team's Slack channel. - - ![Screenshot that shows a notification in a Slack channel.](./media/slack/notifications.png) - -::: moniker-end - -## Q & A +## FAQs -#### Q: Why don't I have the pull request events as an option when I configure my trigger? +### Q: Why don't I have the pull request events as an option when I configure my trigger? A: Pull requests are only available with projects that use Git. If your project uses TFVC, pull event triggers aren't available, -and your code event is called "Code checked in" instead of "Code pushed". +and your code event is called "Code checked in" instead of "Code pushed." -#### Q: How can I get multiple events to show up in my Slack channel? +### Q: How can I get multiple events to show up in my Slack channel? A: Create a new subscription for each type of event you want. For example, if you want to see build failures and new work items in your Slack channel, -create two additional subscriptions. - - - \ No newline at end of file +create two more subscriptions. diff --git a/docs/service-hooks/services/teams.md b/docs/service-hooks/services/teams.md index fb3661b10bb..2b9f9aaeed7 100644 --- a/docs/service-hooks/services/teams.md +++ b/docs/service-hooks/services/teams.md @@ -1,115 +1,123 @@ --- ms.subservice: azure-devops-service-hooks ms.topic: conceptual -title: Create a service hook Microsoft Teams -titleSuffix: Azure DevOps Server -description: Use Microsoft Teams with your Azure DevOps organization +title: Azure DevOps integration with Microsoft Teams +description: See how to set up Azure DevOps notifications and approvals in your Microsoft Teams channels. monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 08/13/2024 --- -# Create a service hook for Azure DevOps with Microsoft Teams +# Azure DevOps integration with Microsoft Teams [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -See activity about your Azure DevOps Server (2017.2 and later) projects directly in your Microsoft Teams channel, for example: -* Work item updates -* Pull requests -* Code commits -* Builds -* Release deployments and approvals +This article describes how you can integrate your Azure DevOps project activities directly into your Microsoft Teams channels. For example, you can see the following Azure DevOps events in your Teams channels: +- Work item updates +- Pull requests +- Code commits +- Builds +- Release deployments and approvals + +## Requirements and limitations + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - To create Azure DevOps subscriptions in Teams: Member of the **Project Administrators** group.
      - To receive Azure DevOps notifications in Teams: **Third party application access via OAuth** enabled in your Azure DevOps organization settings.| +|**Microsoft Entra**|Only Azure DevOps organizations in the same Microsoft Entra tenant as your Microsoft Teams account can be connected. Even if your email addresses are the same for Azure DevOps and Microsoft Teams, they can't be linked if they're backed by different tenants. For more information, see [Access via Microsoft Entra FAQs](../../organizations/accounts/faq-azure-access.yml#AlreadyConnected). | -::: moniker range="azure-devops" > [!NOTE] -> For Azure DevOps Services, we recommend you use the following suite of apps which offer rich features, to integrate with Microsoft Teams. +> Office 365 Connectors within Teams are retired. For more information, see [Retirement of Office 365 connectors within Microsoft Teams](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/). Features that provide similar functionality to Office 365 Connectors with better scalability and security include [Workflows](/power-automate/teams/install-teams-app) or the Azure DevOps Services apps for Teams. -### Azure Boards app for Teams +## Azure DevOps Services apps for Teams -[Azure Boards app for Microsoft Teams](../../boards/integrations/boards-teams.md) helps to easily create and monitor work items from your Teams channels. Users can create work items using a command, or use message actions to convert conversations in the channel into work items. Users can also set up and manage subscriptions to get notifications in their channel whenever work items are created or updated. +[!INCLUDE [temp](../../includes/feature-support-cloud-only.md)] -### Azure Pipelines app for Teams +::: moniker range="azure-devops" -[Azure Pipelines app for Microsoft Teams](../../pipelines/integrations/microsoft-teams.md) helps to easily monitor the events in your pipelines. Users can set up and manage subscriptions for completed builds, releases, pending approvals and more from the app and get notifications for these events in their channels. Users can also approve release deployments from their channels. +You can use the following apps that offer rich features to integrate with Microsoft Teams. -### Azure Repos app for Teams +### Azure Boards app for Teams -[Azure Repos app for Microsoft Teams](../../repos/integrations/repos-teams.md) helps to easily monitor the events in your repositories. Users can set up and manage subscriptions for code commits, PR creation and PR updates and more from the app and get notifications for these events in their channels. +The Azure Boards app for Teams helps you easily create and monitor work items from your Teams channels. You can create work items by using a command, or use message actions to convert conversations in the channel into work items. You can also set up and manage subscriptions to get notifications in your channel whenever work items are created or updated. For more information, see [Use the Azure Boards app in Microsoft Teams](../../boards/integrations/boards-teams.md). -::: moniker-end +### Azure Pipelines app for Teams -::: moniker range="<= azure-devops" +The Azure Pipelines app for Teams helps you easily monitor events in your pipelines from your Teams channels. You can set up and manage subscriptions for completed builds, releases, and pending approvals, and get notifications for these events in your channels. You can also approve builds and release deployments from your channels. For more information, see [Integrate Azure Pipelines with Microsoft Teams](../../pipelines/integrations/microsoft-teams.md). -## Configure a new connector for Azure DevOps Server +### Azure Repos app for Teams -Configuring integration between Azure DevOps Server and Teams is a two-step process. First set up a connector in Teams, then set up one or more service hook subscriptions in your Azure DevOps Server project. +The Azure Repos app for Teams helps you easily monitor events in your repositories from your Teams channels. You can set up and manage subscriptions for code commits, pull request (PR) creation, and PR updates, and get notifications for these events in your channels. For more information, see [Use Azure Repos with Microsoft Teams](../../repos/integrations/repos-teams.md). -> [!NOTE] -> Project administrator permissions are required to create service hook subscriptions. -> Events for YAML pipelines are not supported. +## Add and configure the Azure DevOps tab in Teams +To bring your project dashboard or Kanban board into Teams, you can install the Azure DevOps app in a tab in your Teams channel. The Azure DevOps app lets you insert content from the app in messages, and get notifications from the app in your channels. -### From Teams +1. In Teams, select **Apps** from the left menu and then search for *Azure DevOps*. -1. To bring events from Azure DevOps into Microsoft Teams, select '...', the ellipsis, or at the upper navigation of your team channel, select **Connectors**. + :::image type="content" source="media/teams/search-azure-devops.png" alt-text="Screenshot that shows searching for Azure DevOps in Teams."::: - ![Open the Teams actions menu](./media/teams/open-teams-menu-s172.png) +1. Select **Azure DevOps**, and then select **Add to a team**. -2. Select **Azure DevOps** from the list. +1. Select the Teams channel to add to the app to, and then select **Set up**. - :::image type="content" source="./media/teams/connectors-list-s172.png" alt-text="Connectors list"::: + :::image type="content" source="media/teams/set-up.png" alt-text="Screenshot that shows selecting Set up for Azure DevOps in Teams."::: -3. Choose **Add**. +1. Select **Select organization**, select your organization, and then select **Continue**. -4. Configure the connector. + :::image type="content" source="media/teams/choose-devops-organization.png" alt-text="Screenshot that shows choosing the DevOps organization for Teams integration."::: -5. Copy the generated webhook URL. Provide this URL when you're setting up service hook subscriptions in your Azure DevOps project. +1. On the **Azure DevOps** screen, select a **Project**, and whether to add a **Dashboard** or a **Kanban board** to the tab. Select other configurations depending on your choice, and select whether you want to post to the channel about adding the tab. -### From Azure DevOps Server + :::image type="content" source="media/teams/add-dashboard.png" alt-text="Screenshot that shows adding a Dashboard for Azure DevOps in Teams."::: -1. From your project page (`https://mycompany/tfs/[collection]/[project]`), go to **Service Hooks** in the settings: +1. Select **Save**. The new tab and board appear in your channel. - ![Azure DevOps Services, Service Hook Settings](media/slack/vsts-service-hooks.png) + :::image type="content" source="media/teams/team-dashboard.png" alt-text="Screenshot that shows a Dashboard for an Azure DevOps project in Teams."::: -1. Click **Create subscription** and select the **Teams** service. +::: moniker-end -1. Choose the type of activity you want to appear in your Teams channel. You can filter each of the triggers in specific ways. +::: moniker range=" < azure-devops" - For example, the *pull request created* trigger can be filtered on the repository in which the pull request occurs, - the target branch it applies to, and the team members that are required or invited to review the request. +## Add the Azure DevOps Server app to a team -1. Paste the webhook URL from the Teams connector configuration step and select **Finish**. +The Azure DevOps Server connector sends notifications about activities in your projects. -Activity from your project begins appearing in your Teams channel. +>[!NOTE] +>Office 365 Connectors within Teams are being retired, and new Office 365 Connector creation might be blocked. For more information, see [Retirement of Office 365 connectors within Microsoft Teams](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/). If you can't access the **Connectors** page from within the Teams desktop client, try using the Teams web client. The [Workflows](/power-automate/teams/install-teams-app) app in Teams provides similar functionality with better scalability and security. +1. In Teams, select **Apps** from the left menu and then search for *Azure DevOps Server*. -## Configure Azure DevOps tabs in Microsoft Teams + :::image type="content" source="media/teams/search-azure-devops-server.png" alt-text="Screenshot that shows searching for Azure DevOps Server in Teams."::: -1. To bring your Kanban board or dashboard into Microsoft Teams, select **+ Add new tab** on the upper portion of your team channel. Find the Website icon and add the link to your Azure DevOps board or dashboard. +1. Select **Azure DevOps Server**, and then select **Add to a team**. - ![Add a new tab to Teams channel](./media/teams/teams-as-website.png) +1. Select the channel to add to the app to, and then select **Set up a connector**. -2. Once you've authenticated, your Kanban board or dashboard appears. - + :::image type="content" source="media/teams/set-up-connector-server.png" alt-text="Screenshot that shows selecting Set up a connector for Azure DevOps Server in Teams."::: -::: moniker-end +1. On the **Azure DevOps Server** page, enter a name for the new Azure DevOps Server connection, and then select **Create**. -## Frequently asked questions (FAQs) + :::image type="content" source="media/teams/create-server.png" alt-text="Screenshot that shows creating the Azure DevOps Server connection in Teams."::: - +::: moniker-end -### Q: How can I get multiple events from my Azure DevOps Server project to show up in my Teams channel? +To manage your Teams apps and tabs, select **Apps** in the Teams menu and then select **Manage your apps** at the bottom of the **Apps** panel. -A: Create a new subscription for each type of event you want. -For example, if you want to see build failures and new work items in your Teams channel, -create two additional subscriptions. +## Related content -### Q: Why don't I see my organization when trying to connect Microsoft Teams? +::: moniker range=" azure-devops" -A: Only organizations in the same Azure Active Directory tenant as your Microsoft Teams account can be connected. Even if your email address is the same for Azure DevOps Services and Microsoft Teams, they may be backed by different tenants, so they can't be linked. +- [Use the Azure Boards app in Microsoft Teams](../../boards/integrations/boards-teams.md) +- [Integrate Azure Pipelines with Microsoft Teams](../../pipelines/integrations/microsoft-teams.md) +- [Use Azure Repos with Microsoft Teams](../../repos/integrations/repos-teams.md) +- [Install the Workflows app in Microsoft Teams](/power-automate/teams/install-teams-app) -Create a new Team in the same Azure Active Directory (Azure AD) as Azure DevOps Services, or move your Azure DevOps Services to the same Azure AD as Teams, see [Access via Azure AD FAQs, Why is my organization already connected to a directory?](../../organizations/accounts/faq-azure-access.yml#AlreadyConnected). +::: moniker-end - +::: moniker range=" < azure-devops" +- [Retirement of Office 365 connectors within Microsoft Teams](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/) +- [Install the Workflows app in Microsoft Teams](/power-automate/teams/install-teams-app) +::: moniker-end diff --git a/docs/service-hooks/services/trello.md b/docs/service-hooks/services/trello.md index 7074b41460f..8e6b26e3e13 100644 --- a/docs/service-hooks/services/trello.md +++ b/docs/service-hooks/services/trello.md @@ -15,6 +15,13 @@ ms.date: 07/27/2020 Create cards and lists in Trello in response to events from Azure DevOps. For example, when code is pushed, or a build occurs. +## Prerequisites + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - Member of the [Project Collection Administrators group](../../organizations/security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.
      - **Edit subscriptions** and **View subscriptions** permissions set to **Allow**. By default, only project administrators have these permissions. To grant the permissions to other users, you can use the command-line tool or the [Security](/rest/api/azure/devops/security/?view=azure-devops-rest-6.0&preserve-view=true) REST API.| +|**Tools**|Trello | + ## Get a Trello authorization token 1. If you don't have a Trello account, sign up at [Trello](https://trello.com/signup). @@ -31,7 +38,7 @@ For example, when code is pushed, or a build occurs. Create a Trello card or list from an Azure DevOps Services event. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. Go to your project Service Hooks page: @@ -50,7 +57,6 @@ we're going to have the subscription respond when a work item is created. ![Trigger configuration page](./media/trello/trigger.png) - 1. Set up the action that Trello will take in response to the trigger - either create a card or a list. @@ -68,43 +74,6 @@ either create a card or a list. ::: moniker-end -::: moniker range="tfs-2018" - -1. Go to your project Service Hooks page: - - `https://dev.azure.com/{orgName}/{project_name}/_apps/hub/ms.vss-servicehooks-web.manageServiceHooks-project` - - ![Project administration page](./media/add-service-hook.png) - - Select **Create Subscription**. - -1. Pick the Trello service. - - ![Service page, Trello selected](./media/trello/service.png) - -1. Configure the triggering Visual Studio event. In this case, -we're going to have the subscription respond when a work item is created. - - ![Trigger configuration page](./media/trello/trigger.png) - - -1. Set up the action that Trello will take in response to the trigger - -either create a card or a list. - - ![Action configuration page](./media/trello/action.png) - - You can use placeholders to insert content from the event into the - name and description of the cards or lists that the subscription creates. - For example, when we run the test notification, the card that gets created is named - "Bug #5: Some great new idea!" because the test work item is a bug (ID=5) - with the title "Some great new idea!". - -1. Test the service hook subscription and finish the wizard. - - ![Test notification](./media/trello/test.png) - -::: moniker-end - Now it's set up. Go to Trello and see the cards appear. ![Welcome board with a card for Bug #5](./media/trello/welcome-board.png) diff --git a/docs/service-hooks/services/webhooks.md b/docs/service-hooks/services/webhooks.md index a488d8fd62f..c081b327083 100644 --- a/docs/service-hooks/services/webhooks.md +++ b/docs/service-hooks/services/webhooks.md @@ -2,143 +2,103 @@ ms.subservice: azure-devops-service-hooks ms.topic: conceptual title: Webhooks with Azure DevOps -description: Use webhooks with your Azure DevOps organization +description: Set up a webhook subscription that sends JSON representations of Azure DevOps events to any service that has a public endpoint. ms.assetid: 6c7dfe37-800d-47b8-b9db-9f73878eeb77 monikerRange: '<= azure-devops' -ms.date: 07/27/2020 +ms.date: 08/13/2024 --- # Webhooks [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Webhooks provide a way to send a JSON representation of an event to any service. All that is required is a public endpoint (HTTP or HTTPS). +This article describes webhooks and how to set them up for your Azure DevOps project. Webhooks provide a way to send a JSON representation of an Azure DevOps event to any service that has a public endpoint. -For more information about the JSON payloads posted by this consumer, see [events](../events.md). +>[!NOTE] +>Azure DevOps doesn't charge for setting up service hooks or integrating with external services. Refer to the specific service's site for pricing related to their services. ## Prerequisites -Only organization Owners or Project Collection Administrators can manage webhooks for an organization. +| Category | Requirements | +|--------------|-------------| +|**Permissions**| - Member of the [Project Collection Administrators group](../../organizations/security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.| +|**Project and service**|- A project in the organization
      - A service with a public HTTPS endpoint to which you want to send Azure DevOps events.| + > [!IMPORTANT] + > - Use only HTTPS endpoints. HTTP has the potential to send private data, including authentication headers, unencrypted in the event payload. You must use HTTPS for basic authentication on a webhook. + > - If you're connecting to a service behind a virtual private network, ensure that Azure DevOps IP addresses are allowed for inbound connections. See [Inbound Connections](../../organizations/security/allow-list-ip-url.md). + ## Send JSON representation to a service -::: moniker range=">= azure-devops-2019" +1. In your Azure DevOps project, go to **Project settings** > **Service hooks** at `https:////_settings/serviceHooks`. -1. Go to your project **Service hooks** page: + ![Screenshot of the Service hooks choice in Project settings.](./media/add-devops-service-hook-new-name.png) - `https://{orgName}/{project_name}/_settings/serviceHooks` +1. On the **Service Hooks** page, select the **+** icon or **Create subscription**. - ![Screenshot of the most recent version of the Project administration page](./media/add-devops-service-hook.png) + ![Screenshot of selecting Create subscription on the Service Hooks page.](./media/add-service-hook.png) - Select **Create subscription**. +1. On the **Service** screen, select **Web Hooks** and then select **Next**. -1. Select and configure the Azure DevOps Services event: + ![Screenshot of selecting Web Hooks on the Service page.](./media/webhooks/configure-service.png) - ![Configure the event dialog box](./media/webhooks/configure-event.png) +1. On the **Trigger** screen, select and configure the Azure DevOps event you want to trigger the webhook on, and then select **Next**. For more information about the JSON payloads posted by the Azure DevOps consumer, see [Service hooks events](../events.md). -1. Configure what to do when the event occurs: + ![Screenshot of selecting and configuring the trigger event.](./media/webhooks/configure-event.png) - See the following [Q & A](#q--a) for information on the **Resource details to send**, **Messages to send**, and **Detailed messages to send** settings. +1. On the **Action** screen, configure the target **URL** and what to do when the event occurs. For more information about what to enter in **Resource details to send**, **Messages to send**, and **Detailed messages to send**, see [Resource details to send](#resource-details-to-send). - ![Configure the action dialog box](./media/webhooks/configure-action.png) + >[!NOTE] + >Webhooks can't target localhost (loopback) or special range [IPv4](https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml)/[IPv6](https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml) addresses. -2. Test the service hook subscription and finish the wizard: +1. Select **Test** to test the service hook subscription. - ![Test it](./media/webhooks/test.png) + ![Screenshot of configuring the Action dialog box.](./media/webhooks/configure-action.png) -::: moniker-end +1. When the test completes successfully, close the notification screen, and then select **Finish** on the **Action** screen. -::: moniker range="tfs-2018" + ![Screenshot of test results for the service hook subscription](./media/webhooks/test.png) -1. Go to your project Service Hooks page: +1. Now the webhook is set up. Go to the target service to view the JSON representation. - `https://dev.azure.com/{orgName}/{project_name}/_apps/hub/ms.vss-servicehooks-web.manageServiceHooks-project` + ![Screenshot of viewing the JSON representation.](./media/webhooks/request-bin.png) - ![Screenshot of the Project administration page](./media/add-service-hook.png) +>[!TIP] +>You can also create a webhook programmatically. For more information, see [Create a service hook subscription programmatically](../create-subscription.md). - Select **Create Subscription**. +### Resource details to send -1. Select and configure the Azure DevOps Services event: +The **Resource details to send**, **Messages to send**, and **Detailed messages to send** settings in the **Action** pane control the size of the JSON payload to send. **Resource details to send** controls how much of the resource to send. The default is **All**, but you can also choose to send **Minimal**, which sends only key fields like URL and ID, or **None**. - ![Configure the event dialog box](./media/webhooks/configure-event.png) +**None** and **Minimal** are useful in scenarios where the caller doesn't need much or any information about the resource, because it relies on the message or detailed message itself. **None** and **Minimal** are also useful for security reasons. The caller must call back into Azure DevOps Services and go through normal security and permission checks to get more details about the resource. -1. Configure what to do when the event occurs: - - See the following [Q & A](#q--a) for information on the **Resource details to send**, **Messages to send**, and **Detailed messages to send** settings. - - ![Configure the action dialog box](./media/webhooks/configure-action.png) - -2. Test the service hook subscription and finish the wizard: - - ![Test it](./media/webhooks/test.png) - -::: moniker-end - -Now the webhook is set up. Go to the target service to view the JSON representation: - -![View the JSON representation](./media/webhooks/request-bin.png) - - -## Pricing - -Azure DevOps doesn't charge for the framework for integrating with external services. Check out the specific service's site -for pricing related to their services. - -## Q & A - - - -#### Q: What are the Resource details to send, Messages to send, and Detailed messages to send settings for? - -A: They control the size of the JSON payload that is sent. - -The **Resource details to send** setting controls how much of the resource is sent. -The default is **All**, but you can also choose to send **Minimal** (only sends key fields like URL and ID), or **None**. - -**None** and **Minimal** are useful in scenarios where the caller doesn't actually need much, -if anything, about the resource because it's relying on the message or detailed message. -**None** and **Minimal** are also useful for security reasons, for example, -the caller needs to call back into Azure DevOps Services and go through normal security/permission checks to get more details about the resource. - -Sample JSON: +The following sample JSON shows minimal details about the resource: ```json - { - "eventType": "git.push", - ... - "messages": { - "text": "...", - "html": "...", - "markdown": "..." - }, - "detailedMessage": { - "text": "...", - "html": "...", - "markdown": "..." - }, - "resource": { - "id": "...", - "url": "https://...", - "name": "...", - "field1:": "..." - } - } + { + "eventType": "git.push", + ... + "messages": { + "text": "...", + "html": "...", + "markdown": "..." + }, + "detailedMessage": { + "text": "...", + "html": "...", + "markdown": "..." + }, + "resource": { + "id": "...", + "url": "https://...", + "name": "...", + "field1:": "..." + } + } ``` -#### Q: Can I programmatically create subscriptions? - -**A:** Yes, see details [here](../create-subscription.md). - -#### Q: Can I send webhooks to non HTTPS endpoints? - -**A:** Yes. However, it's recommended that you only use HTTPS endpoints for your webhooks. Using HTTP means there is a the potential for private data being sent unencrypted. This includes any authentication headers in your webhook. - -#### Q: Can I use basic authentication when setting up a webhook that isn't HTTPS? - -**A:** No. You must use HTTPS when utilizing basic authentication on a webhook. - -#### Q: Can we use localhost or special range IPs as webhook targets? - -A: No. Webhooks can't target localhost (loopback) or special range [IPv4](https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml)/[IPv6](https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml) addresses. +## Related content - \ No newline at end of file +- [Integrate with service hooks](../overview.md) +- [Service hooks events](../events.md) +- [Create a service hook subscription programmatically](../create-subscription.md) diff --git a/docs/service-hooks/troubleshoot.md b/docs/service-hooks/troubleshoot.md index da030e0d9bd..aff4ff97636 100644 --- a/docs/service-hooks/troubleshoot.md +++ b/docs/service-hooks/troubleshoot.md @@ -24,7 +24,7 @@ for each subscription, and whether a subscription is enabled, disabled, or restr You can access detailed history about a subscription including detailed request/response data, which is useful for debugging a problematic service or subscription. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. To view the activity and status of your subscriptions, go to the **Service Hooks** page. @@ -36,20 +36,6 @@ You can access detailed history about a subscription including detailed request/ ::: moniker-end -::: moniker range="tfs-2018" - -1. To view the activity and status of your subscriptions, -go to the Service Hooks page. - - :::image type="content" source="media/troubleshoot/service-hooks.png" alt-text="Screenshot showing view of subscription status."::: - -1. To view detailed activity for a subscription, including full request, response, -and event payload data, select a subscription in the table and select **History**. - - :::image type="content" source="media/troubleshoot/detailed-activity.png" alt-text="Screenshot showing view of detailed activity for subscription."::: - -::: moniker-end - ## Subscription failures and probation (restricted) ### Failure types @@ -120,7 +106,6 @@ After seven retries, the subscription status gets set to _DisabledBySystem_ if n **A:** The payload limit is 2 MB. Larger payloads cause degradation in performance and reliability. As a best practice, service-hooks should limit the payload to 2 MB or less. - ### Q: What does the status Enabled (restricted) mean? **A:** A subscription becomes restricted if too many failures occur. Enabled (restricted) is the same as being on probation. @@ -136,7 +121,6 @@ A: A subscription is automatically disabled after a series of consecutive failur **A:** The user who created the subscription is no longer a member of the team. - ### Q: What should I try if a service hook isn't working? **A:** Check the following items: diff --git a/docs/service-hooks/view-permission.md b/docs/service-hooks/view-permission.md new file mode 100644 index 00000000000..4cb205a4a22 --- /dev/null +++ b/docs/service-hooks/view-permission.md @@ -0,0 +1,174 @@ +--- +title: How to define view permission for a group in Service Hooks +titleSuffix: Azure DevOps ServiceHooks +description: Learn the steps for defining the *View* permission for a group in Service Hooks. +ms.service: azure-devops +ms.subservice: azure-devops-service-hooks +ms.topic: how-to +ms.custom: cross-service +ms.author: rgundogmus +author: rgundogmusm +monikerRange: 'azure-devops' +ms.date: 06/28/2024 +--- + +# Set View permission for a group in Service Hooks +[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] + +By default, only Project Administrators have _View_ or _Edit_ permissions. To grant these permissions to other users directly, you can use the [command line tool](../organizations/security/manage-tokens-namespaces.md) or the [Security](/rest/api/azure/devops/security/) REST API. + +![Screenshot showing ServiceHooks page without permissions.](./media/permissions/no-permission-service-hooks.png) + +The `ServiceHooks` security namespace ID is defined under [List Security Namespaces](../organizations/security/manage-tokens-namespaces.md#list-security-namespaces) as `cb594ebe-87dd-4fc9-ac2c-6a10a4c92046` + +## Prerequisites + +| Category | Requirements | +|--------------|-------------| +|**Project access**| [Project member](../organizations/security/add-users-team-project.md). | +|**Permissions**| - Member of the [Project Collection Administrators group](../organizations/security/look-up-project-collection-administrators.md). Organization owners are automatically members of this group.
      - [Personal access token (PAT)](../organizations/accounts/use-personal-access-tokens-to-authenticate.md) for your Azure DevOps profile. | +|**Tools**|[Azure CLI](/cli/azure/install-azure-cli).
      1. Sign in with `az devops login`.
      2. You can define your organization as default organization. Otherwise, define `--org "https://dev.azure.com/{organization}"` for each command. ```az devops configure --defaults organization="https://dev.azure.com/{organization}"```
      3. Check if you can see list of permissions for your organization: ```az devops security permission namespace list --org "https://dev.azure.com/{organization}"```. | + +## Read group identity and permission token + +1. Find your group identity descriptor. + ``` + > az devops security group list --project ac515e82-560c-4af8-845b-9f7f968d8e7b --output table + + Name Descriptor + ----------------------------------------------- -------------------------------------------------------------------------------------------------------------------------------------------------- + [TEAM FOUNDATION]\EntraServiceHooksRead aadgp.Uy0xLTktMTU1MTM3NDI0NS0xMjA0NDAwOTY5LTI0MDI5ODY0MTMtMjE3OTQwODYxNi0zLTM5NTQxNzM3ODYtMTUyMTA4MTkyNS0yNTQwNTA4MjYzLTMzNDgxNjQxNjg + ``` + If you want to filter by group name, you can use `findstr` or `grep` command depends on your command prompt. + +2. Get permission token. + ``` + > az devops security permission list --id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 --subject --output table + + Token Effective Allow Effective Deny + ------------------------------------------------------ ----------------- ---------------- + PublisherSecurity 0 0 + PublisherSecurity/ac515e82-560c-4af8-845b-9f7f968d8e7b 0 0 + ``` + +## Update read permission for service hooks + +1. List of possible permissions that you can define for `--allow-bit`. + - View Subscriptions + - Edit Subscription + - Delete Subscriptions + - Publish Events + + ``` + > az devops security permission namespace show --id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 + + [ + { + "actions": [ + { + "bit": 1, + "displayName": "View Subscriptions", + "name": "ViewSubscriptions", + "namespaceId": "cb594ebe-87dd-4fc9-ac2c-6a10a4c92046" + }, + { + "bit": 2, + "displayName": "Edit Subscription", + "name": "EditSubscriptions", + "namespaceId": "cb594ebe-87dd-4fc9-ac2c-6a10a4c92046" + }, + { + "bit": 4, + "displayName": "Delete Subscriptions", + "name": "DeleteSubscriptions", + "namespaceId": "cb594ebe-87dd-4fc9-ac2c-6a10a4c92046" + }, + { + "bit": 8, + "displayName": "Publish Events", + "name": "PublishEvents", + "namespaceId": "cb594ebe-87dd-4fc9-ac2c-6a10a4c92046" + } + ], + "dataspaceCategory": "Default", + "displayName": "ServiceHooks", + "elementLength": -1, + "extensionType": null, + "isRemotable": true, + "name": "ServiceHooks", + "namespaceId": "cb594ebe-87dd-4fc9-ac2c-6a10a4c92046", + "readPermission": 1, + "separatorValue": "/", + "structureValue": 1, + "systemBitMask": 0, + "useTokenTranslator": true, + "writePermission": 7 + } + ``` + +2. Set _View_ access for the group. View ServiceHooks Subscriptions equals 1 for `--allow-bit`. + ``` + > az devops security permission update --namespace-id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 --subject --token PublisherSecurity/ac515e82-560c-4af8-845b-9f7f968d8e7b --allow-bit 1 + + [ + { + "acesDictionary": { + "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-3-3954173786-1521081925-2540508263-3348164168": { + "allow": 1, + "deny": 0, + "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-3-3954173786-1521081925-2540508263-3348164168", + "extendedInfo": { + "effectiveAllow": 1 + }, + "resolvedPermissions": [ + { + "bit": 1, + "displayName": "View Subscriptions", + "effectivePermission": "Allow", + "name": "ViewSubscriptions" + } + ] + } + }, + "includeExtendedInfo": true, + "inheritPermissions": true, + "token": "PublisherSecurity/ac515e82-560c-4af8-845b-9f7f968d8e7b" + } + ] + ``` + +3. Get permission token to see your changes. + ``` + > az devops security permission list --id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 --subject --output table + + Token Effective Allow Effective Deny + ------------------------------------------------------ ----------------- ---------------- + PublisherSecurity 0 0 + PublisherSecurity/ac515e82-560c-4af8-845b-9f7f968d8e7b 1 0 + ``` + +The following example shows that the user can see the service hooks subscriptions. + +![Screenshot showing the ServiceHooks page with permission.](./media/permissions/service-hooks-subscriptions-with-permission.png) + +## Reset all Service Hooks permissions of a group + +- If you need to reset all Service Hooks permissions of a group or user, you can call `reset-all`. + + ``` + > az devops security permission reset-all --id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 --subject --token PublisherSecurity/ac515e82-560c-4af8-845b-9f7f968d8e7b + + Are you sure you want to reset all explicit permissions for this user/group and token? (y/n): Y + true + + > az devops security permission list --id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 --subject --output table + Token Effective Allow Effective Deny + ------------------------------------------------------ ----------------- ---------------- + PublisherSecurity 0 0 + PublisherSecurity/ac515e82-560c-4af8-845b-9f7f968d8e7b 0 0 + ``` + +- The following example shows that the user can't view to service hooks subscriptions after the permission gets reset. + + ![Screenshot showing the ServiceHooks page without permission.](./media/permissions/no-permission-service-hooks.png) + diff --git a/docs/test/add-to-bugs-exploratory-testing.md b/docs/test/add-to-bugs-exploratory-testing.md index 683ddfb37f2..d13830572ea 100644 --- a/docs/test/add-to-bugs-exploratory-testing.md +++ b/docs/test/add-to-bugs-exploratory-testing.md @@ -1,12 +1,12 @@ --- title: Add findings to existing bugs -description: Manual and exploratory testing - add findings to existing bugs existing bugs when using the Test & Feedback extension +description: Manual and exploratory testing - add findings to existing bugs when using the Test & Feedback extension ms.assetid: 0C61F157-452E-4DE5-8998-8DDBD9D44969 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 -ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.topic: how-to +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' ms.date: 09/14/2021 --- @@ -16,55 +16,52 @@ ms.date: 09/14/2021 [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] To help avoid duplication, the Test & Feedback extension automatically -searches for and displays existing bugs, based on the keywords in the title, -as you file a new bug. You can choose to continue creating a new bug or add -your findings to an existing bug. +searches for and displays existing bugs, based on the keywords in the title as you file a new bug. You can choose to continue creating a new bug or add your findings to an existing bug. -[!INCLUDE [prerequisites-define](includes/prerequisites-stakeholder.md)] +## Prerequisites -1. As you type the title for a new bug, in the background the extension - searches for similar bugs that might be related to the issue you've found - and displays a link to the results. Choose this link to see the results that have - similar title keywords. +[!INCLUDE [prerequisites](includes/prerequisites.md)] - ![The link to view similar bugs](media/add-to-bugs-exploratory-testing/add-to-existing-bugs-01.png) +## Add your findings to a bug + +1. Enter the title for a bug. + + In the background, the extension searches for similar bugs that might be related to the issue you found and displays a link to the results. + +2. Select the link to see the results that have similar title keywords. + + ![Screenshot showing the link to view similar bugs.](media/add-to-bugs-exploratory-testing/add-to-existing-bugs-01.png) - The form displays **0 Similar** if it does not find any matching bugs. - In this case, or if you don't see a "similar" link, you can create a - new bug containing your screenshots, notes, and videos - as described in [this topic](connected-mode-exploratory-testing.md). + The form displays **0 Similar** if it doesn't find any matching bugs. In this case, or if you don't see a "similar" link, you can create a new bug that contains your screenshots, notes, and videos, as described in [Connected mode exploratory testing](connected-mode-exploratory-testing.md). -1. If you see a bug you want to update, instead of creating a new one: +3. To update a bug, do the following tasks, rather than create a new one. - - Select it in the list and choose **Edit**. + - Choose it from the list and select **Edit**. - ![Editing a similar bug](media/add-to-bugs-exploratory-testing/add-to-existing-bugs-02.png) + ![Screenshot showing Editing a similar bug.](media/add-to-bugs-exploratory-testing/add-to-existing-bugs-02.png) - - The extension appends all your screenshots, notes, and videos to + The extension appends all your screenshots, notes, and videos to the existing bug. - Save the updated bug. - ![Saving the updated bug](media/add-to-bugs-exploratory-testing/add-to-existing-bugs-03.png) - -1. If, instead, you decide not to update an existing bug, ignore the "similar" link and: + ![Screenshot showing Saving the updated bug.](media/add-to-bugs-exploratory-testing/add-to-existing-bugs-03.png) - - Choose the **New bug** link to return to the bug details form. +4. OR, if you decide not to update an existing bug, ignore the "similar" link and select **New bug** to return to the bug details form. - ![Returning to the bug details form](media/add-to-bugs-exploratory-testing/add-to-existing-bugs-04.png) + ![Screenshot showing Returning to the bug details form.](media/add-to-bugs-exploratory-testing/add-to-existing-bugs-04.png) - - Enter the details for the new bug and save it - as described in [this topic](connected-mode-exploratory-testing.md).

      + - Enter the details for the new bug and save it, as described in [Connected mode exploratory testing](connected-mode-exploratory-testing.md). -1. Continue exploring your app, filing bugs and tasks, and creating test cases. +5. Continue to explore your app, file bugs and tasks, and create test cases. ## See your exploratory session results -After you file bugs, create tasks, or create test cases, all these show up in the "Recent exploratory sessions" page in Azure Test Plans. +After you file bugs, create tasks, or create test cases, they show up in the "Recent exploratory sessions" page in Azure Test Plans. -* See how you can [view your sessions and get insights](insights-exploratory-testing.md). +See how you can [view your sessions and get insights](insights-exploratory-testing.md). -## See Also +## Related articles * [Use the Test & Feedback extension in Connected mode](connected-mode-exploratory-testing.md) * [Explore work items with exploratory testing](explore-workitems-exploratory-testing.md) diff --git a/docs/test/associate-automated-test-with-test-case.md b/docs/test/associate-automated-test-with-test-case.md index 4fc3e67c30d..9a3ac1bcafe 100644 --- a/docs/test/associate-automated-test-with-test-case.md +++ b/docs/test/associate-automated-test-with-test-case.md @@ -4,10 +4,10 @@ description: Continuous testing. Associate an automated test with a test case us ms.assetid: 606679F2-1604-40EA-A720-63CDDA93DD76 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 -ms.topic: conceptual -ms.author: sdanie -author: steved0x -ms.date: 12/07/2018 +ms.topic: how-to +ms.author: jeom +author: rohit-batra +ms.date: 01/28/2025 monikerRange: '<= azure-devops' --- @@ -16,121 +16,131 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [version-vs-gt-2015](../includes/version-vs-gt-2015.md)] -Consider using Visual Studio to associate automated tests with a test case when: +Associating automated tests with test cases can enhance your testing process by providing better traceability and integration with your CI/CD pipeline. This article guides you through the scenarios where associating automated tests with test cases is beneficial and how to do it effectively. -* You created a manual test case that you later decide is a good test - to automate, but you still want to be able to run that test as part of a test plan. - Tests can be run in the CI/CD pipeline by choosing the test plan or test suite - in the settings of the [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) task. - Automated tests can also be run from the **Test Plans** web portal. - If you are using XAML builds you can also - [run these automated tests by using Microsoft Test Manager](/previous-versions/azure/devops/test/mtm/run-automated-tests-with-microsoft-test-manager). +## Prerequisites -* You want to enable end-to-end traceability of requirements. - If your test cases are linked to requirements or user stories, - the results of the test execution can be used to establish the quality of those requirements. +[!INCLUDE [prerequisites](includes/prerequisites.md)] -The process to associate an automated test with a test case is: +## Create a test project and build pipeline -1. Create a test project containing your automated test. - [What types of tests are supported?](#test-types) +Do the following steps to create a test project and build pipeline. -1. Check your test project into an Azure DevOps or Team - Foundation Server (TFS) repository. +1. Create a test project containing your automated test. For more information, see [what types of tests are supported](#test-types). +1. Check your test project into an Azure DevOps. +2. Create a build pipeline for your project and ensure that it contains the automated test. For more information, see [what the differences are if you're still using a XAML build](#xaml-build). -1. Create a build pipeline for your project, ensuring that it - contains the automated test. - [What are the differences if I am still using a XAML build?](#xaml-build) + -1. Use Visual Studio Enterprise or Professional 2017 or a later version to associate the automated - test with a test case as shown [below](#add-test). The test case must have - been added to a test plan that uses the build you just defined. +## Associate your automated test in Visual Studio -If you are using the build and release services in -Azure DevOps (not a [XAML build](#xaml-build)), you can run associated tests in the -build and release pipelines by using the -[Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) task. -You _cannot_ run tests on-demand using Microsoft Test Manager unless you are using a XAML build. +Consider using Visual Studio to associate automated tests with a test case in the following scenarios: -The parameters in a test case are not used by any automated test that -you associate with a test case. Iterations of a test case that use these -parameters are for manual tests only. +- **Automating manual test cases**: If you created a manual test case that you later decide is a good candidate for automation, but you still want to run it as part of a test plan. You can run these tests in the CI/CD pipeline by selecting the test plan or test suite in the settings of the [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) task. You can also run automated tests from the **Test Plans** web portal. If you're using XAML builds, you can [run these automated tests using Microsoft Test Manager](/previous-versions/azure/devops/test/mtm/run-automated-tests-with-microsoft-test-manager). -> For more information about checking in your test project and team build, see -[Add files to the server](../repos/tfvc/add-files-server.md) -and [Continuous integration on any platform](../pipelines/get-started/what-is-azure-pipelines.md). -For more information about action recordings and coded UI tests, see -[Recording and Playing Back Manual Tests](/previous-versions/azure/devops/test/mtm/record-play-back-manual-tests) -and [Use UI Automation To Test Your Code](/visualstudio/test/use-ui-automation-to-test-your-code). +- **Enabling end-to-end traceability**: If your test cases are linked to requirements or user stories, you can use the results of the test execution to establish the quality of those requirements. - -## Associate your test +Do the following steps to associate your automated test with a test case in Visual Studio. 1. Open your solution in Visual Studio Enterprise or Professional 2017 or a later version. - 2. If you don't know the identifier of the work item for the test case, locate the test case in **Azure Test Plans** , or [query for the work item](../boards/queries/using-queries.md) in the **Work** hub. - 3. When you know the identifier of the work item for the test case: - **If you are using Visual Studio 2017 or later version**, follow these steps to associate your tests. - - - If the **Test Explorer** window is not displayed, open it from the **Test | Windows** menu. - - - If your tests are not displayed in **Test Explorer**, build the solution. + **If you're using Visual Studio 2017 or later version**, do the following steps to associate your tests. + - If the **Test Explorer** window isn't displayed, open it from the **Test | Windows** menu. + - If your tests aren't displayed in **Test Explorer**, build the solution. - In **Test Explorer**, select the test method you want to associate and choose **Associate to Test Case**. - - In the dialog that opens, type the test case identifier and choose **Add Association**, then choose **Save**. + > [!div class="mx-imgBorder"] + > ![Screenshot showing associating automation with test case.](media/associate-automated-test-with-test-case/test-explorer-associate.png) + + The dialog shows a list of test cases currently associated with the selected test method. + You can't associate more than one test method with a test case, but you can associate a + test method with more than one test case. - ![Associate Automation With Test Case](media/associate-automated-test-with-test-case/test-explorer-associate.png) + If you're using the build and release services in Azure DevOps, not a [XAML build](#xaml-build), you can run associated tests in the build and release pipelines by using the [Visual Studio Test](/azure/devops/pipelines/tasks/reference/vstest-v2) task. You _can't_ run tests on-demand using Microsoft Test Manager unless you're using a XAML build. - > The dialog shows a list of test cases currently associated with the selected test method. - You cannot associate more than one test method with a test case, but you can associate a - test method with more than one test case. + The parameters in a test case aren't used by any automated test that you associate with a test case. Iterations of a test case that use these parameters are for manual tests only. + +For more information, see the following articles: +- [Add files to the server](../repos/tfvc/add-files-server.md) +- [Continuous integration on any platform](../pipelines/get-started/what-is-azure-pipelines.md) +- [Recording and Playing Back Manual Tests](/previous-versions/azure/devops/test/mtm/record-play-back-manual-tests) +- [Use UI Automation To Test Your Code](/visualstudio/test/use-ui-automation-to-test-your-code) -## FAQ +## Associate your automated test in Azure DevOps +### Associate your test from a build pipeline + +1. Navigate to **Pipelines** and choose a pipeline where the automated tests ran. +2. Choose the build in which your tests were executed. +3. In the **Tests** tab, look for the automated test you wish to link with a manual test case. +4. Select the test and then click on **Associate Test Case**. +5. Locate the manual test case you want to associate to the automated test and click **Associate**. + + > [!div class="mx-imgBorder"] + > ![Screenshot showing the process of associating an automated test to a test case within a CI/CD pipeline interface.](media/associate-automated-test-with-test-case/associate-automated-test-to-test-case-pipelines.png) + +After you associate your automated tests with their corresponding test cases, you can utilize the [Azure Test Plan task](/azure/devops/pipelines/tasks/reference/azure-test-plan-v0) to execute them as part of a pipeline. + +## FAQs about associating automated tests + +See the following frequently asked questions (FAQs). + ### Q: What types of tests are supported? -**A**: These are the limitations for each type of test: - -* Coded UI test, Selenium tests, and unit tests written using - Version 1 of the MSTest framework **can** be associated with a test case. -* Tests that use MSTest v2, NUnit, and xUnit frameworks **can** be associated - with a test case workitem when using Visual Studio 15.9 Preview 2 or later. - However, these tests cannot be run using Microsoft Test Manager and XAML builds. -* Tests that use the .NET core framework **can** be associated with a test case - workitem when using Visual Studio 15.9 Preview 2 or later. - To run the .NET core tests the appropriate target framework must be specified - in a [runsettings file](/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file). - However, these tests cannot be run using Microsoft Test Manager and XAML builds. -* Tests that use other test frameworks such as Chutzpah (for JavaScript tests - such as Mocha or QUnit), or Jest **cannot** be associated with a test case. -* Associating generic tests **may** work, but running these tests is not supported. +**A**: The following capabilities and limitations exist for each test type: + +|Framework |*Association in Visual Studio|Association in Azure DevOps| +|----------|-----------|------------| +|Coded UI tests|Supported |Supported| +|Selenium|Supported |Supported| +|MSTest v1/v2|Supported |Supported| +|NUnit|Supported|Supported| +|xUnit|Supported|Supported| +|Python (PyTest)|Not Supported|Supported| +|Java (Maven and Gradle)|Not Supported|Supported| + +\* Supported in Visual Studio 15.9 Preview 2 or later. + +Tests that use the .NET core framework **can** be associated with a test case + work item when using Visual Studio 15.9 Preview 2 or later. + Run the .NET core tests. The appropriate target framework must be specified + in a [.runsettings file](/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file?). -### Q: What are the differences if I am still using a XAML build? -**A**: If you are using a XAML build in Azure Pipelines, you can run tests -that you have associated in a Build-Deploy-Test workflow using a +### Q: Can I associate my tests from my GitHub repo? + +**A**: As long as you run your automated tests in Azure Pipelines with the VSTest task, or you report the test results with the PublishTestResults task, the automated tests will be available for association to test cases. +Please keep in mind that the test must run at least once before it becomes available for association. + + + +### Q: What are the differences if I'm still using a XAML build? + +**A**: If you're using a XAML build in Azure Pipelines, you can run tests +that you associated in a Build-Deploy-Test workflow using a [Lab environment](/visualstudio/test/lab-management/using-a-lab-environment-for-your-application-lifecycle). You can also run tests using Microsoft Test Manager and a [Lab environment](/visualstudio/test/lab-management/using-a-lab-environment-for-your-application-lifecycle). + ### Q: Can I configure work items to open in Visual Studio? -**A**: Yes, if you want test work items to open inside Visual Studio +**A**: Yes. If you want test work items to open inside Visual Studio instead of the default Azure Pipelines UI in your web browser, change the **Work Items | General** setting from the **Tools | Options** menu in Visual Studio. -![Change work item display mode](media/work-item-compatibility.png) +![Screenshot of Change work item display mode.](media/work-item-compatibility.png) -## See Also +## Related articles * [Associate automated test results with requirements](../pipelines/test/requirements-traceability.md) * [Run automated tests from test plans](run-automated-tests-from-test-hub.md) diff --git a/docs/test/bulk-import-export-test-cases.md b/docs/test/bulk-import-export-test-cases.md new file mode 100644 index 00000000000..10d164852af --- /dev/null +++ b/docs/test/bulk-import-export-test-cases.md @@ -0,0 +1,156 @@ +--- +title: Bulk import or export of test cases +titleSuffix: Azure Test Plans +description: Learn how to bulk import or export test cases in Azure Test Plans. +ms.service: azure-devops-test-plans +ms.custom: cross-project, UpdateFrequency3 +ms.author: jeom +author: wisdeom +ms.topic: how-to +monikerRange: '= azure-devops' +ms.date: 12/04/2023 +--- + + +# Bulk import or export of test cases + +[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] + +Azure Test Plans users can bulk import or export test cases using CSV or Microsoft Excel file formats. The import operation supports creation of new test cases into a given test suite or update existing test cases by providing the test case ID. The export operation allows users to export test cases into CSV or Microsoft Excel file (XLSX). While you can continue to use bulk import and updates, you can use the native web-portal based functionality to copy, clone and update the test cases. For more information, see [Copy or clone test plans, test suites, and test cases](copy-clone-test-items.md). + +For an overview of test objects and terminology, see [Test objects and terms](test-objects-overview.md). + +## Prerequisites + +[!INCLUDE [prerequisites-stakeholder](includes/prerequisites-stakeholder.md)] + +## Export test cases + +1. From the **Test Plans** > **Test plans** page, choose the test plan with the test suite containing the test cases you want to export. + +2. (Optional) Select :::image type="icon" source="media/icons/column-options.png"::: **Column options** to add fields to include in the download file. + +3. To export all test cases for the test suite, select either **Export test cases to CSV** or **Export test cases to XLSX**. + + :::image type="content" source="media/bulk-import-test-case/export-test-cases-test-suite.png" alt-text="Screenshot of Export test cases from the selected test suite."::: + +4. To export a subset of test cases for the test suite, select the test cases to export, choose :::image type="icon" source="../media/icons/more-actions.png"::: **More options**, and select **Export test case(s) to CSV** or **Export test case(s) to XLSX**. + + :::image type="content" source="media/bulk-import-test-case/export-select-test-cases-test-suite.png" alt-text="Screenshot of selected test cases, export test cases to CSV."::: + +5. The exported CSV file appears in your **Downloads** folder. + +## Import test cases + +1. From **Test Plans>Test plans** page, choose the test plan with the test suite into which you want to import test cases. + + :::image type="content" source="media/bulk-import-test-case/choose-import-test-cases.png" alt-text="Screenshot of Import test cases to the selected test suite."::: + +2. Choose the file to import from the dialog that opens, and then choose **Import**. + + :::image type="content" source="media/bulk-import-test-case/import-test-cases-dialog.png" alt-text="Screenshot of Import Test Cases dialog."::: + +3. Choose **Confirm** in the **Confirm import** dialog that displays. If you specify test cases that are already defined in the test suite, some elements might get over written during import. + + + +## Update existing test cases + +1. To update work items, create a column view that contains all the columns you want to export and possibly edit. Post applying relevant columns to your view, it's time to export the test cases into a CSV or XLSX file. Select **Export to CSV** or **Export to XLSX** to save the file to your local machine. + + :::image type="content" source="media/bulk-import-test-case/export-test-cases-test-suite.png" alt-text="Screenshot of Export test cases from the selected test suite."::: + +2. Make the edits to your test cases. You must not change the **ID** and **Work Item Type** fields. Any other fields you want to include are optional. + +3. Save the file and import it back to the test suite (see [import section](#import-test-cases).) + +## Import automated test cases (TCM) + +To import automated test cases to a test suite, use `tcm testcase /import`. You must specify a .dll file for the test assembly that contains your tests. + +```tcm +tcm testcase /import /collection:teamprojectcollectionurl /teamproject:project + /storage:path + [/maxpriority:priority] + [/minpriority:priority] + [/category:filter] + [/syncsuite:id [/include]] + [/login:username,[password]] +``` + + +| Parameter | Description | +|----------|------------| +|**/storage**:`path`|Specifies the path and name of the test assembly that contains your automated tests that you want to import.| +|**/maxpriority**:`priority`|Optional. Specifies which tests to import based on the maximum priority of the test method. For example, if the parameter is `/maxpriority:1`, only tests with a priority attribute for the test method less than or equal to 1 are imported as test cases from the assembly.| +|**/minpriority**:`priority`|Optional. Specifies which tests to import based on the minimum priority of the test method. For example, if the parameter is `/minpriority:2`, only tests with a priority attribute for the test method equal or greater than 2 are imported as test cases from the assembly.| +|**/category**:`filter`|Optional. Specifies which tests to import based on the category of each test method in the test assembly. You can use this parameter together with `/syncsuite` to import tests with a certain category into a specific test suite.
      For more information about test categories, see [Run unit tests with Test Explorer](/visualstudio/test/run-unit-tests-with-test-explorer).| +|**/syncsuite**:`id`|Optional. Specifies the suite ID for the test suite in your test plan to which you want to add the test cases that you import. This suite can't be a dynamic suite or a query-based suite. If you specify a test suite to synchronize to update tests, the unsupported tests get removed from the test suite but not from the test plan itself. | + +## FAQs + +### Q: Can I import new test cases and update existing cases in the same CSV/XLSX file? + +A: Absolutely! Leave the Test case ID field empty for any new work items. For existing test cases you want to update, provide the respective 'Test case ID' and 'Work item type' values. + +### Q: How do I know if my imported file has errors? + +A: Any problems with the formatting of your CSV/XLSX file appear in the import view in the web-portal. You can't import the work items until the formatting and syntax is correct. + +:::image type="content" source="media/bulk-import-test-case/import-errors.png" alt-text="Screenshot of Import Test Cases error dialog."::: + +### Q: Does import operation support all work item types? + +A: No, all work items aren't supported. The Test case import only supports the following work item types: + +- Test Case + +Important for referencing shared steps in test case using import functionality: + +- A shared steps work item must already exist, and its ID can be referenced in the CSV. The CSV or XLSX import functionality does not support creating a new shared steps work item if it is referenced without an ID, and the import will fail with an "invalid column" error. + +- You can create new shared steps work item from a test case work item UI and **using create shared steps option** in it. + +- Once the shared steps work item is created, you can refer the ID of the shared step in CSV. + +:::image type="content" source="media/bulk-import-test-case/shared-steps-reference-in-csv.png" alt-text="Screenshot of shared step reference in CSV."::: + +- Note that if the shared steps work item reference is provided along with steps in the CSV or XLSX, it will update the shared steps work item. Therefore, if you only want to provide a reference to the shared steps, do not add steps to it in the CSV or XLSX. + +Azure Boards has a separate bulk import functionality using CSV files. For more information, see [Bulk import or update (CSV)](../boards/queries/import-work-items-from-csv.md). + +### Q: What are the mandatory headers to include in Import CSV/XLSX file? + +A: Ensure every import file has the following headers (with the exact spelling): +* **ID**: The ID of the work item you're trying to import. For new test case creation, leave this field blank. +* **Work Item Type:** Test case import method only supports 'Test case' and 'Shared Steps.' Use these exact keywords when providing work item type information. +* **Title:** The title of the test case you want to create or update, which can be an alpha-numeric value. +* **Test Step:** Steps defined in a test case are in an ordered list. You need to provide the order number of each test step. +* **Step Action:** Defines the actions a manual tester needs to undertake while executing the test step. +* **Step Expected:** The expected outcome of a given action. + + +### Q: What are the limitations to import or export operations? + +A: Ensure to follow the below limitations: +* The test case state column must be in Design state. +* The test case title length must not exceed 128 characters. +* There's a limit of 20 MB on JSON objects created during import and export. If the import fails, try the operation with small subset of the test cases. +* The user performing the import must have permissions on the area and iteration paths for test plan and test suite they're planning to import or export. +* Copy and Import operations fail if the related link count exceeds 1000 for the test case. + +## Next steps + +> [!div class="nextstepaction"] +> [Run manual tests](run-manual-tests.md) + +## Related articles + +- [Create test plans and test suites](create-a-test-plan.md) +- [Create test cases](create-test-cases.md) +- [Share steps between test cases](share-steps-between-test-cases.md) +- [Test different configurations](test-different-configurations.md) +- [Repeat a test with different data](repeat-test-with-different-data.md) +- [Test objects and terms](test-objects-overview.md) +- [Create a query based on build and test integration fields](../boards/queries/build-test-integration.md) +- [Customize and manage the test experience](/previous-versions/azure/devops/reference/witadmin/tcm-customize-manage-test-experience) diff --git a/docs/test/collect-diagnostic-data.md b/docs/test/collect-diagnostic-data.md index 6857195d0c0..64e1e2a042e 100644 --- a/docs/test/collect-diagnostic-data.md +++ b/docs/test/collect-diagnostic-data.md @@ -5,8 +5,8 @@ ms.assetid: F536C364-BEFC-48A8-B977-19233941EF6A ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' ms.date: 12/06/2021 --- @@ -15,13 +15,12 @@ ms.date: 12/06/2021 [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Collect diagnostic data while testing your apps. -This data will be included in the bugs you file -during the test. You can collect diagnostic data from -web apps and from desktop apps, -and view it in Azure Test Plans. +Collect diagnostic data while you test your apps. This data is included in the bugs you file +during the test. You can collect diagnostic data from web apps and from desktop apps, and view it in Azure Test Plans. -[!INCLUDE [prerequisites-define](includes/prerequisites-stakeholder.md)] +## Prerequisites + +[!INCLUDE [prerequisites-stakeholder](includes/prerequisites-stakeholder.md)] @@ -34,83 +33,80 @@ For desktop apps, download and install the [Test Runner desktop client](https:// - [Image action log](#web-log) - [Screen recordings](#web-recording) -> See [Exploratory test and submit feedback directly from your browser](perform-exploratory-tests.md). +For more information, see [Exploratory test and submit feedback directly from your browser](perform-exploratory-tests.md). -## Screen capture -Capture annotated screenshots from your app: +## Capture your screen + +Do the following steps to capture annotated screenshots from your app. 1. Open Test Runner and choose the **Capture screenshot** icon. Ensure that the app from which you want to capture data is selected. - ![Capturing a screenshot from the app](media/shared/collect-diagnostic-data-01.png) + ![Screenshot showing capturing a screenshot from the app.](media/shared/collect-diagnostic-data-01.png) -1. Drag to select the area of the screen you want to - capture, or just capture the full screen. +1. Drag to select the area of the screen you want to capture, or just capture the full screen. - ![Selecting the area of the screen to capture](media/collect-diagnostic-data/collect-diagnostic-data-03.png) + ![Screenshot showing selecting the area of the screen to capture.](media/collect-diagnostic-data/collect-diagnostic-data-03.png) -1. If required, edit the title of the screenshot and add - annotations and text to it using the icons in the toolbar. +1. If necessary, edit the title of the screenshot and add annotations and text to it using the icons in the toolbar. - ![Annotating the screenshot](media/collect-diagnostic-data/collect-diagnostic-data-04.png) + ![Screenshot showing annotating the screenshot.](media/collect-diagnostic-data/collect-diagnostic-data-04.png) 1. Save your screenshot. - ![Saving the screenshot](media/collect-diagnostic-data/collect-diagnostic-data-05.png) + ![Screenshot showing saving the screenshot.](media/collect-diagnostic-data/collect-diagnostic-data-05.png) -## Image action log -Capture your interactions with the web or desktop app as an image action log that provides context: +## Capture interactions as an image action log + +Do the following steps to capture your interactions with the web or desktop app as an image action log that provides context. 1. Open or switch to the Test Runner and choose the **Capture user actions...** icon. Ensure that the app from which you want to capture data is selected. - ![Capturing an image action log from the app](media/shared/collect-diagnostic-data-06.png) + ![Screenshot showing capturing an image action log from the app.](media/shared/collect-diagnostic-data-06.png) -1. The Test Runner will now record all the actions you take +2. The Test Runner records all the actions you take on the app's browser tab or in the desktop app. - ![Recording in progress for a web app](media/collect-diagnostic-data/collect-diagnostic-data-08.png) + ![Screenshot showing recording in progress for a web app.](media/collect-diagnostic-data/collect-diagnostic-data-08.png) If you create a bug while recording your actions, all the - data collected up to that point will be included in the bug. + data collected up to that point is included in the bug. -1. Finish capturing your actions by choosing - the **Stop** button. The action log is added to the test results +3. Select **Stop** to finish capturing your actions, The action log is added to the test results as an attachment. - ![Stopping a recording for a web app](media/collect-diagnostic-data/collect-diagnostic-data-08a.png) + ![Screenshot showing stopping a recording for a web app.](media/collect-diagnostic-data/collect-diagnostic-data-08a.png) -1. Choose the **ActionLog...** link at the bottom of the window - to view the data captured in the action log. +4. Select the **ActionLog...** link to view the data captured in the action log. - ![Opening the image action log](media/collect-diagnostic-data/collect-diagnostic-data-09.png) + ![Screenshot showing opening the image action log.](media/collect-diagnostic-data/collect-diagnostic-data-09.png) The log opens in your web browser. - ![Viewing the data captured in the image action log](media/collect-diagnostic-data/collect-diagnostic-data-10.png) + ![Screenshot showing viewing the data captured in the image action log.](media/collect-diagnostic-data/collect-diagnostic-data-10.png) -## Screen recording -Capture screen recordings from your apps: +## Record your screen + +Do the following steps to capture screen recordings from your apps. 1. Open or switch to the Test Runner and choose the **Record screen** icon. - ![Capturing a screen recording from the app](media/shared/collect-diagnostic-data-11.png) + ![Screenshot showing capturing a screen recording from the app.](media/shared/collect-diagnostic-data-11.png) 1. Choose the entire screen, or choose an app to start recording. ::: moniker range=">=azure-devops-2020" - ![Select the screen or app to share](media/collect-diagnostic-data/choose-test-feedback-share.png) - ::: moniker-end - ::: moniker range="<=azure-devops-2019" - ![Choosing the screen or app to record](media/collect-diagnostic-data/collect-diagnostic-data-12.png) + ![Screenshot showing selection of the screen or app to share.](media/collect-diagnostic-data/choose-test-feedback-share.png) ::: moniker-end + If you create a bug while recording your screen, the recording automatically stops and is added to the bug. @@ -119,36 +115,30 @@ Capture screen recordings from your apps: the **Stop** button. The recording is added to the test results as an attachment. - ![Stopping a screen recording](media/collect-diagnostic-data/collect-diagnostic-data-13.png) + ![Screenshot showing stopping a screen recording.](media/collect-diagnostic-data/collect-diagnostic-data-13.png) - If you do not stop the recording after 10 minutes, it stops + If you don't stop the recording after 10 minutes, it stops automatically and is saved as an attachment to your test results. - Restart the recording the **Record screen** icon if required. + Restart the recording the **Record screen** icon if necessary. 1. Choose the **ScreenRecording...** link at the bottom of the window to view the captured recording. - ![Viewing the screen recording](media/collect-diagnostic-data/collect-diagnostic-data-14.png) + ![Screenshot showing viewing the screen recording.](media/collect-diagnostic-data/collect-diagnostic-data-14.png) ## View the diagnostic data When you create a bug while capturing diagnostic data, all the data captured -up to that point is included in the bug that is created. You can -view it before you save the bug. +up to that point gets included in the bug that you create. You can view it before you save the bug. -![Viewing the diagnostic data in the bug you are creating](media/collect-diagnostic-data/collect-diagnostic-data-15.png) +![Screenshot showing viewing the diagnostic data in the bug you are creating.](media/collect-diagnostic-data/collect-diagnostic-data-15.png) [How do I play the video recordings I created with the extension?](reference-qa.yml#recording-playback) -If you want to collect advanced diagnostic data such as code coverage, -IntelliTrace, and Test Impact data in addition to the data items listed above, -you must [configure the data collectors](/previous-versions/azure/devops/test/mtm/collect-more-diagnostic-data-in-manual-tests) -and other run settings in Microsoft Test Manager and run your -tests using Microsoft Test Manager. For more information, see +To collect advanced diagnostic data such as code coverage, IntelliTrace, and Test Impact data (in addition to the previously listed data items), you must [configure the data collectors](/previous-versions/azure/devops/test/mtm/collect-more-diagnostic-data-in-manual-tests) and other run settings in Microsoft Test Manager and run your tests using Microsoft Test Manager. For more information, see [Run manual tests with Microsoft Test Manager](/previous-versions/azure/devops/test/mtm/plan-manual-tests-with-microsoft-test-manager). -

      > [!NOTE] > If you have an older version of Microsoft Test Manager, we recommend you upgrade to the latest version. diff --git a/docs/test/connected-mode-exploratory-testing.md b/docs/test/connected-mode-exploratory-testing.md index 0dabe463ee3..c06b7bfb7fc 100644 --- a/docs/test/connected-mode-exploratory-testing.md +++ b/docs/test/connected-mode-exploratory-testing.md @@ -5,73 +5,61 @@ ms.assetid: 0F52826C-218D-437A-B6FF-EB8E8292CE3C ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: quickstart -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' -ms.date: 09/14/2021 +ms.date: 09/16/2024 --- -# Exploratory testing with the Test & Feedback extension in Connected mode +# Exploratory testing with the Test & Feedback extension in Connected mode [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -To use the Test & Feedback extension in **Connected** mode you must connect -to an Azure DevOps project. -This automatically configures the extension based on your access level: +To use the Test & Feedback extension in Connected mode, connect to an Azure DevOps project, which automatically configures the extension based on your access level. * Users with **Basic** access can use the extension to perform exploratory - testing, as described below. + testing, as described in this article. +* Users with **Stakeholder** access can use the extension to respond to feedback requests or to [provide feedback](provide-stakeholder-feedback.md#direct) voluntarily. +* Users with **Basic** or **Stakeholder** access can use extension to respond to feedback requests sent by the team by choosing the **Provide feedback** link in the email. for more information, see [Provide stakeholder feedback](provide-stakeholder-feedback.md#email). -* Users with **Stakeholder** access can use the extension to respond to - feedback requests or to provide feedback voluntarily. - [More details](provide-stakeholder-feedback.md#direct). - -* Users with **Basic** or **Stakeholder** access can use extension to respond to feedback requests sent - by the team by choosing the **Provide feedback** link in the email. - [More details](provide-stakeholder-feedback.md#email). +## Prerequisites -[!INCLUDE [prerequisites-define](includes/prerequisites-stakeholder.md)] +[!INCLUDE [prerequisites-stakeholder](includes/prerequisites-stakeholder.md)] ## Connect to Azure DevOps -1. If you want to use Azure DevOps, and you haven't already done so, - [sign up for a subscription](https://visualstudio.microsoft.com/products/visual-studio-team-services-vs) - now. Make sure you create a project when you create your subscription. +1. If you don't have a subscription, [sign up for a subscription](https://visualstudio.microsoft.com/products/visual-studio-team-services-vs). Make sure you create a project when you create your subscription. -1. If you haven't already, [install the Test & Feedback extension](perform-exploratory-tests.md). +2. [Install the Test & Feedback extension](perform-exploratory-tests.md). -1. Open the extension in your web browser and select **Connected** mode. +3. Open the extension in your web browser and select **Connected** mode. - ![Start the extension in Connected mode](media/shared/connectedmode-01.png) + ![Screenshot showing starting the extension in Connected mode.](media/perform-exploratory-tests/getstarted-06.png) -1. Enter the Azure DevOps URL you want to connect to and choose **Next**. +4. Enter the Azure DevOps URL you want to connect to and select **Next**. - ![Enter the Azure DevOps URL you want to connect to](media/shared/connectedmode-02.png) + ![Screenshot showing entering the Azure DevOps URL you want to connect to.](media/shared/connectedmode-02.png) - If you are connecting for the first time, you may be prompted to sign in. + If you're connecting for the first time, you might be prompted to sign in. -1. After connecting to the server, the extension shows - all the collections, projects and teams in that server. Select the - project or team you want to connect to and choose **Save**. + After you connect to the server, the extension shows all the collections, projects, and teams in that server. +5. Select the project or team you want to connect to and select **Save**. - ![Select your project or team](media/connected-mode-exploratory-testing/connectedmode-03.png) + ![Screenshot showing project or team selection.](media/connected-mode-exploratory-testing/connected-mode-03.png) - If there are many projects or teams, use the search textbox - to find the one you need. + If there are many projects or teams, use the search textbox to find the one you need. The extension is now ready to be used in **Connected** mode. -Depending on your access level (Basic or Stakeholder) -you will see the appropriate UI for either [exploratory testing](#create-bugs) -or [providing feedback](provide-stakeholder-feedback.md#provide). -The extension remembers your selection and remains connected until -the session cookies expire or you explicitly disconnect from the server. +Depending on your access level (Basic or Stakeholder), you see the appropriate UI for either [exploratory testing](#create-bugs) or [providing feedback](provide-stakeholder-feedback.md#provide). +The extension remembers your selection and remains connected until the session cookies expire or you explicitly disconnect from the server. + ## Create bugs or tasks -After you have connected, you are ready to begin testing your app. +Do the following steps to start your exploratory testing session and create bugs or tasks. 1. Start your exploratory testing session. @@ -87,14 +75,14 @@ After you have connected, you are ready to begin testing your app. >Some browsers may not provide all of the capture capabilities. See [Supported web browsers for the extension](perform-exploratory-tests.md#browser-support). -1. When you are done exploring and capturing information, create a bug or a task. +1. When you're done exploring and capturing information, create a bug or a task. ![Create a bug or a task from the captured information](media/connected-mode-exploratory-testing/create-bugs-02.png) 1. The bug or task form contains all your captured information. It also contains an image action log describing your interactions with the page - (such as mouse clicks, keyboard typing events, touch gestures, and more) and - page load data. Uncheck these options if you do not want to include this + (such as mouse select, keyboard typing events, touch gestures, and more) and + page load data. Uncheck these options if you don't want to include this data in the bug or task. ![Decide whether to include the image action log and page load data](media/connected-mode-exploratory-testing/create-bugs-03.png) @@ -104,77 +92,71 @@ After you have connected, you are ready to begin testing your app. Page load data provides preliminary information about the time it takes to load the pages, such as the resource timings and navigation timelines. -1. Enter a title for the bug or task and add any additional notes +1. Enter a title for the bug or task and add any other notes you require to the description. Then save the bug or task. ![Save the bug or task](media/connected-mode-exploratory-testing/create-bugs-04.png) - > You can also [add your findings to an existing similar bug](reference-qa.yml#addsimilar). + You can also [add your findings to an existing similar bug](reference-qa.yml#addsimilar). 1. View a list of all your activities in reverse chronological order - in the **Session timeline** page. It shows all the screenshots, videos, and notes - you've captured, the work items such as bugs, tasks, and test cases you've already - filed, and the work items you've explored. + in the **Session timeline** page. The timeline shows all the screenshots, videos, notes, the work items such as bugs, tasks, and test cases you already + filed, and the work items you explored. - ![Review your captured information](media/connected-mode-exploratory-testing/create-bugs-08.png) + ![Screenshot of captured information for review.](media/connected-mode-exploratory-testing/create-bugs-08.png) - > You can use the extension to [explore work items](explore-workitems-exploratory-testing.md) + You can use the extension to [explore work items](explore-workitems-exploratory-testing.md) in Azure DevOps. 1. To view a bug or task in Azure DevOps, choose the link in the session timeline. - ![View a bug or task](media/connected-mode-exploratory-testing/create-bugs-09.png) + ![Screenshot of view a bug or task.](media/connected-mode-exploratory-testing/create-bugs-09.png) - This opens the work item form in Azure DevOps. + The work item form opens in Azure DevOps. - ![The bug or task in TS](media/connected-mode-exploratory-testing/create-bugs-10.png) + ![Screenshot of the bug or task.](media/connected-mode-exploratory-testing/create-bugs-10.png) [How do I play the video recordings I created with the extension?](reference-qa.yml#recording-playback) + ## Create test cases The extension lets you create test cases as you explore your application. -1. When you find a scenario where you want to create a test case, - choose **Create test case**. +1. When you find a scenario where you want to create a test case, select **Create test case**. - ![Creating a test case](media/connected-mode-exploratory-testing/create-testcase-01.png) + ![Screenshot showing creating a test case.](media/connected-mode-exploratory-testing/create-testcase-01.png) -1. The test case form contains a list of all your actions up to this point - while exploring the app (it reads them from the image action log). +2. The test case form lists all your actions while exploring the app, as recorded in the image action log. - ![The actions for the new test case](media/connected-mode-exploratory-testing/create-testcase-02.png) + ![Screenshot showing the actions for the new test case.](media/connected-mode-exploratory-testing/create-testcase-02.png) -1. Enter a title for the test case and then edit it as required. For example, - uncheck the action steps you don't want to include in the test case, edit the captured - text, and add the expected result. Then save the test case. +3. Enter a title for the test case and then edit it as required. For example, uncheck the action steps you don't want to include in the test case, edit the captured text, and add the expected result. Then save the test case. - ![Editing new test case](media/connected-mode-exploratory-testing/create-testcase-03.png) - -1. Continue exploring the application. Create more bugs, tasks, or test cases as required. + ![Screenshot showing editing a new test case.](media/connected-mode-exploratory-testing/create-testcase-03.png) + ## End your testing session 1. When you're done, stop your session. - ![Stop the exploratory testing session](media/connected-mode-exploratory-testing/create-bugs-05.png) + ![Screenshot of stopping the exploratory testing session.](media/connected-mode-exploratory-testing/create-bugs-05.png) -2. If you are using Azure DevOps, TFS 2017, or later version, open the **Session timeline** page and choose the "view" icon to see your completed exploratory +2. Open the **Session timeline** page and select the "view" icon to see your completed exploratory sessions in Azure DevOps. - ![View the exploratory testing session](media/connected-mode-exploratory-testing/create-bugs-06.png) + ![Screenshot of View the exploratory testing session.](media/connected-mode-exploratory-testing/create-bugs-06.png) Alternatively, open the **Recent exploratory sessions** list directly in the **Runs** page of the **Test Plans** web portal. - ![View exploratory testing sessions on the server](media/connected-mode-exploratory-testing/create-bugs-07.png) + ![Screenshot of the view of the exploratory testing sessions on the server.](media/connected-mode-exploratory-testing/create-bugs-07.png) ## See your exploratory session results -After you file bugs, create tasks, or create test cases, all these show up in the "Recent exploratory sessions" page in Azure Test Plans. +After you file bugs, create tasks, or create test cases, they show up in the "Recent exploratory sessions" page in Azure Test Plans. -* See how you can [view your sessions and get insights](insights-exploratory-testing.md). +See how you can [view your sessions and get insights](insights-exploratory-testing.md). [How do I play the video recordings I created with the extension?](reference-qa.yml#recording-playback) - diff --git a/docs/test/copy-clone-test-items.md b/docs/test/copy-clone-test-items.md index ac83fad07a0..ac7a488cd06 100644 --- a/docs/test/copy-clone-test-items.md +++ b/docs/test/copy-clone-test-items.md @@ -1,34 +1,39 @@ --- title: Copy or clone test plans, test suites, test cases, or other test items titleSuffix: Azure Test Plans -description: Learn how to copy or clone test plans, test suites, test cases in Azure Test Plans. +description: Learn how to copy or clone test plans, test suites, and test cases in Azure Test Plans. ms.service: azure-devops-test-plans ms.custom: cross-project, UpdateFrequency3 -ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 11/11/2021 +ms.date: 03/12/2024 --- - # Copy or clone test plans, test suites, and test cases [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Several tools support copy, clone, or import operations of test items—such as, test plans, test suites, and test cases. Test cases describe the steps to take to run a test and validate a feature implementation or bug fix. Test suites group test cases, and optionally other test suites, into a particular order. Test plans define a collection of test suites to run for a particular iteration or release. +Several tools support copy, clone, or import operations of test items such as test plans, test suites, and test cases. Test cases describe the steps to take to run a test and validate a feature implementation or bug fix. Test suites group test cases, and optionally other test suites, into a particular order. Test plans define a collection of test suites to run for a particular iteration or release. -Each test case is designed to confirm a specific behavior. Test cases may belong to one or more test suites, however test suites can belong to one and only one test plan. +Each test case is designed to confirm a specific behavior. Test cases might belong to one or more test suites, however test suites can belong to one and only one test plan. -In general, you should create a test plan for every major project milestone. Copy, clone, or import operations of test items support the following scenarios: +In general, you should create a test plan for every major project milestone. Copy, clone, or import operations of test items support the following scenarios. - Define a test plan for a new sprint or release based on an existing test plan - Import test suites from one test plan to another test plan within the same or different project - Copy test cases for use in different test suites and test plans - Share test objects across projects -- Move test objects from one project to another, possibly to support consolidating projects into a single project. +- Move test objects from one project to another, possibly to support consolidating projects into a single project -For an overview of test objects and terminology, see [Test objects and terms](test-objects-overview.md). +For more information, see [Overview of test objects and terms](test-objects-overview.md). + +## Prerequisites + +[!INCLUDE [prerequisites-define](includes/prerequisites-define.md)] +[!INCLUDE [prerequisites-tcm](includes/prerequisites-tcm.md)] + ## Supported copy, clone, and import tools Depending on the Azure DevOps version you use, you can use the clients or tools listed in the following table to copy, clone, or import test plans, test suites, or test cases. @@ -54,14 +59,14 @@ Depending on the Azure DevOps version you use, you can use the clients or tools **Web portal** 1 :::column-end::: :::column span="1"::: - ✔️ ([Copy](#copy-test-plans-portal)) + ✔️ [Copy](#copy-test-plans-portal) :::column-end::: :::column span="1"::: - ✔️ ([Import](#import-test-suites-portal)) + ✔️ [Import](#import-test-suites-portal) :::column-end::: :::column span="1"::: - ✔️ ([Copy](#copy-test-case)) - ✔️ ([Bulk export/import](#bulk-import-export)) + ✔️ [Copy](#copy-test-case) + ✔️ [Bulk export/import](#bulk-import-export) :::column-end::: :::row-end::: ::: moniker-end @@ -77,26 +82,11 @@ Depending on the Azure DevOps version you use, you can use the clients or tools :::column-end::: :::column span="1"::: - ✔️ ([Copy and paste](#copy-paste)) - :::column-end::: -:::row-end::: -::: moniker-end -::: moniker range="< azure-devops-2020" -:::row::: - :::column span="1"::: - **Web portal (Grid)** - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - - :::column-end::: - :::column span="1"::: - ✔️ ([Copy and paste](#copy-paste)) + ✔️ [Copy and paste](#copy-paste) :::column-end::: :::row-end::: ::: moniker-end + :::row::: :::column span="1"::: **Work item form** @@ -108,50 +98,34 @@ Depending on the Azure DevOps version you use, you can use the clients or tools :::column-end::: :::column span="1"::: - ✔️ ([Copy](../boards/backlogs/copy-clone-work-items.md)) + ✔️ [Copy](../boards/backlogs/copy-clone-work-items.md) :::column-end::: :::row-end::: -::: moniker range="<= azure-devops-2019" -:::row::: - :::column span="1"::: - **Microsoft Test Manager**1 - (deprecated) - :::column-end::: - :::column span="1"::: - ✔️ ([Clone plan](/previous-versions/azure/devops/test/mtm/copying-and-cloning-test-suites-and-test-cases)) - :::column-end::: - :::column span="1"::: - ✔️ ([Copy a test suite](/previous-versions/azure/devops/test/mtm/copying-and-cloning-test-suites-and-test-cases)) - :::column-end::: - :::column span="1"::: - ✔️ ([Create copy](/previous-versions/azure/devops/test/mtm/copying-and-cloning-test-suites-and-test-cases)) - :::column-end::: -:::row-end::: -::: moniker-end + :::row::: :::column span="1"::: **TCM CLI** 2 :::column-end::: :::column span="1"::: - ✔️ ([Clone](#clone-test-plan)) + ✔️ [Clone](#clone-test-plan) :::column-end::: :::column span="1"::: - ✔️ ([Clone](#clone-test-suite)) + ✔️ [Clone](#clone-test-suite) :::column-end::: :::column span="1"::: - ✔️ ([Import automated](#import-test-cases)) + ✔️ [Import automated](#import-test-cases) :::column-end::: :::row-end::: -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" :::row::: :::column span="1"::: **REST API** 3 :::column-end::: :::column span="1"::: - ✔️ ([Clone](/rest/api/azure/devops/testplan/test-plan-clone/clone-test-plan)) + ✔️ [Clone](/rest/api/azure/devops/testplan/test-plan-clone/clone-test-plan) :::column-end::: :::column span="1"::: - ✔️ ([Clone](/rest/api/azure/devops/testplan/test-suite-clone/clone-test-suite)) + ✔️ [Clone](/rest/api/azure/devops/testplan/test-suite-clone/clone-test-suite) :::column-end::: :::column span="1"::: @@ -165,47 +139,40 @@ Depending on the Azure DevOps version you use, you can use the clients or tools > 1. The Test Case Management (TCM) command-line tool is installed when you install Visual Studio 2017 or earlier versions. Examples provided in this article reflect the options available with the Visual Studio 2017 version. Earlier versions may support fewer options. For details, see [Work with the TCM command-line tool](#work-tcm-cli). > 1. REST API commands to support cloning of test plans and test suites were added with version 5.0, corresponding with Azure DevOps 2019. > ::: moniker-end -> ::: moniker range="< azure-devops-2020" -> 1. [Microsoft Test Manager (MTM)](/previous-versions/azure/devops/test/mtm/guidance-mtm-usage) was deprecated for use with Azure DevOps Services in January 2020, and isn't supported for Azure DevOps Server 2020 and later versions. The current version of Azure Test Plans supports all features that MTM supported and more. -> 1. The Test Case Management (TCM) command-line tool is installed when you install Visual Studio 2017 or earlier versions. Examples provided in this article reflect the options available with the Visual Studio 2017 version. Earlier versions may support fewer options. For details, see [Work with the TCM command-line tool](#work-tcm-cli). -> ::: moniker-end - - -[!INCLUDE [prerequisites-define](includes/prerequisites-define.md)] - -[!INCLUDE [prerequisites-define](includes/prerequisites-tcm.md)] - +> ## List test plans or test suites -You often need to know the ID assigned to a test plan or test suite to support copy, clone, or import operations. +When you perform copy, clone, or import operations related to test plans or test suites, it’s essential to have access to their unique ID. This identifier allows you to precisely target the specific plan or suite you want to work with. By knowing the assigned ID, you can streamline your testing processes and ensure accurate replication or transfer of test-related data. # [Browser](#tab/browser) - + + +Do the following steps to generate a list of test plans, test suites, or other test objects. -You can generate a list of test plans, test suites, or other test objects from the **Boards>Queries** page. For example, by setting the **Work Item Type=Test Plan**, you can list all test plans defined for the team project. If you choose the **Query across all projects** checkbox, the query will list all test plans defined for all projects. To learn more about defining queries, see [Define a work item query](../boards/queries/using-queries.md). +1. Select **Boards** > **Queries**, from your project. +2. Enter the parameter, `Work Item Type=Test Plan` in your query Editor. You can list all test plans defined for the team project. +3. Enter a check in the **Query across projects** checkbox. + The query lists all test plans defined for all projects. For more information, see [Define a work item query](../boards/queries/using-queries.md). +4. **Run** the query. > [!TIP] -> While test plans, test suites, and test cases are related to each other, you can't view the relationships through a work item query. Link types aren't used to link test plans, test suites, and test cases. Only shared steps and shared parameters are linked to test cases. Also, test cases are linked to user stories or other work items that they test. - -:::image type="content" source="media/copy-clone/query-test-plans.png" alt-text="Screenshot of Query Editor, Query test plans."::: +> While test plans, test suites, and test cases are related to each other, you can't view the relationships through a work item query. Link types don't link test plans, test suites, and test cases. Only shared steps and shared parameters link to test cases. Also, test cases link to user stories or other work items that they test. +:::image type="content" source="media/copy-clone/query-test-plans.png" alt-text="Screenshot of Query Editor."::: + + # [TCM CLI](#tab/tcm-cli) TCM supports listing of test plans and test suites. Lists specify the work ID for each test plan or test suite. This ID is the same as a plan ID or suite ID. - - -[List test plans](#list-test-plans) | [List test suites](#list-test-suites) - - +[List test plans](#list-test-plans) | [List test suites](#list-test-suites) ### List test plans -Use `tcm plans /list` to determine the **ID** for a test plan. The **ID** corresponds to the work item ID defined when the test plan was created. - +Use `tcm plans /list` to determine the **ID** for a test plan. The **ID** corresponds to the work item ID defined when the test plan was created. ```tcm tcm plans /list [/planid:id | /querytext:query] /collection:teamprojectcollectionurl @@ -216,11 +183,8 @@ tcm plans /list [/planid:id | /querytext:query] /collection:teamprojectcollect |----------|------------| |**/querytext**:`query`| Optional. Specifies the query to use to list a subset of test plans. | - [!INCLUDE [prerequisites-define](includes/common-tcm-parameters.md)] - - **Example** The following command lists the test plans defined for the *Fabrikam Fiber* project hosted in the *fabrikamprime* organization. The **ID** and **Name** corresponds to the work item ID and **Title** defined for the test plan. For example, test plan *86* is titled *Hello World Test*. @@ -229,45 +193,38 @@ The following command lists the test plans defined for the *Fabrikam Fiber* proj tcm plans /list /collection:https://dev.azure.com/fabrikamprime /teamproject:"Fabrikam Fiber" Id Name ---------- ---------------------------------------------------------------- +------***---------------------------------------------------------------- 66 Sprint 1 72 All sprints 77 Sprint 2 86 Hello World Test ``` - - - ### List test suites -Use `tcm suites /list` to list the test suites with their work item IDs. When no optional parameters are specified, all test suites are listed for the team project. - +Use `tcm suites /list` to list the test suites with their work item IDs. When no optional parameters are specified, all test suites are listed for the team project. ```tcm tcm suites /list [/planid:id | /querytext:query] /collection:teamprojectcollectionurl /teamproject:project [/login:username,[password]] ``` - | Parameter | Description | |----------|------------| |**/planid**:`id` | Optional. Specifies the ID of the plan to reference the test suites to list. | |**/querytext**:`query`| Optional. Specifies the query to use to list a subset of test suites. | - [!INCLUDE [prerequisites-define](includes/common-tcm-parameters.md)] - **Example** -The following command lists the test suites defined for the *Fabrikam Fiber* project hosted in the *fabrikamprime* organization. The **ID** corresponds to the work item ID defined for the test suite. Under the **Name** column, the first entry indicates the test plan that the test suite is defined under. Following the -> (arrow) is the **Title** of the test suite or the **Title** of a parent test suite. For example, test suite *75*, *Sub Suite 01*, is a sub-test suite of *Suite 01* defined for the *All sprints* test plan. +The following command lists the test suites defined for the *Fabrikam Fiber* project hosted in the *fabrikamprime* organization. The **ID** corresponds to the work item ID defined for the test suite. Under the **Name** column, the first entry indicates the test plan that the test suite is defined under. Following the -> (arrow) is the **Title** of the test suite or the **Title** of a parent test suite. For example, test suite *75*, *Sub Suite 01*, is a subtest suite of *Suite 01* defined for the *All sprints* test plan. ```tcm tcm suites /list /collection:https://dev.azure.com/fabrikamprime /teamproject:"Fabrikam Fiber" Id Name ---------- ---------------------------------------------------------------- +------***---------------------------------------------------------------- 67 Sprint 1 68 Sprint 1 -> 33 : Change initial view 69 Sprint 1 -> 34 : Welcome back page @@ -279,17 +236,16 @@ Id Name 87 Hello World Test ``` -*** - - - +*** + + ## Copy or clone test plans -We recommend creating a new test plan per sprint or release. When doing so, generally you can clone the test plan for the prior cycle and, with few changes, the copied test plan is ready for the new cycle. +When you create a new test plan per sprint or release, a helpful approach is to clone the test plan from the prior cycle. With minimal adjustments, the copied test plan becomes well-suited for the new cycle. This practice streamlines the planning process and ensures consistency across iterations. -Cloning is useful when you want to branch your application into two versions. After cloning, tests for the two versions can be changed without affecting each other. +Cloning proves especially useful when you need to branch your application into two versions. After cloning, you can modify tests independently for each version without impacting the other. It’s an efficient way to manage testing efforts while maintaining separation between different application variants. :::image type="content" source="media/copy-clone/clone-test-plan-conceptual.png" alt-text="Conceptual image, clone test plan."::: @@ -297,56 +253,45 @@ Cloning is useful when you want to branch your application into two versions. Af ::: moniker range=">= azure-devops-2020" -> [!NOTE] -> If you're new to using Azure Test Plans, review [Navigate Test Plans](navigate-test-plans.md) to understand how to use the user interface to access select functions. - -1. Open **Test Plans>Test plans**, and choose the test plan you want to copy from the **Mine** or **All** page. Select :::image type="icon" source="../media/icons/more-actions.png" border="false"::: **More actions**, and choose the **Copy test plan** menu option. This option lets you copy or clone test plans within a project. - - :::image type="content" source="media/copy-clone/copy-test-plan-menu-selection.png" alt-text="Test Plan More Actions menu, copy test plan option."::: +1. Select **Test Plans** > **Test plans**, from your project. +2. Choose the test plan you want to copy from the **Mine** or **All** page. +3. Select :::image type="icon" source="../media/icons/more-actions.png" border="false"::: **More actions** > **Copy test plan**. This option lets you copy or clone test plans within a project. -2. Specify the name of the new test plan, and select an **Area Path** and **Iteration Path** for the plan. + :::image type="content" source="media/copy-clone/copy-test-plan-menu-selection.png" alt-text="Screenshot showing Test Plan More Actions menu, copy test plan option."::: - :::image type="content" source="media/copy-clone/copy-test-plan-dialog.png" alt-text="Copy test plan dialog"::: +4. Specify the name of the new test plan, and select an **Area Path** and **Iteration Path** for the plan. - Choose one or the other radio-buttons based on the following guidance: - - **Reference existing test cases**: Choose this option when you plan to merge the two branches eventually. In this case, you'll want to keep the same requirements for functionality that has already been implemented and tested. - - **Duplicate existing test cases**: Choose this option when you want to make new user stories or requirements that you will maintain separately. If you plan to diverge into two similar but separate applications, you might want to change the user stories of one without changing the stories of the other. Choosing this option creates an independent set of requirements for the new test cases. + :::image type="content" source="media/copy-clone/copy-test-plan-dialog.png" alt-text="Screenshot showing Copy test plan dialog."::: - If you duplicate existing test cases, the copied test cases will be assigned the **Area Path** and **Iteration Path** specified for the cloned test plan. + - Choose one or the other radio-buttons based on the following guidance: + - **Reference existing test cases**: Choose this option when you plan to merge the two branches eventually. In this case, keep the same requirements for functionality that is already implemented and tested. + - **Duplicate existing test cases**: Choose this option when you want to make new test cases maintained separately, note that new test cases will be linked to existing requirements. - To learn more about area and iteration paths, see [About area and iteration (sprint) paths](..//organizations/settings/about-areas-iterations.md). + If you duplicate existing test cases, the copied test cases get assigned the **Area Path** and **Iteration Path** specified for the cloned test plan. -3. The page refreshes to display the newly copied test plan. + For more information, see [About area and iteration (sprint) paths](..//organizations/settings/about-areas-iterations.md). - :::image type="content" source="media/copy-clone/copied-test-plan.png" alt-text="Copied test plan, browser view"::: + The page refreshes to display the newly copied test plan. -4. Update any [query-based suites](create-a-test-plan.md) that you copied to use the new area and iteration paths. - -5. Specify a build in the destination test plan if you have cloned automated test cases. + :::image type="content" source="media/copy-clone/copied-test-plan.png" alt-text="Screenshot showing Copied test plan, browser view."::: +5. Update any [query-based suites](create-a-test-plan.md) that you copied to use the new area and iteration paths. +6. Specify a build in the destination test plan if you cloned automated test cases. ::: moniker-end -::: moniker range="< azure-devops-2020" - -> [!NOTE] -> This feature isn't supported through the web portal for Azure DevOps Server 2019 and earlier versions. The feature to copy test plans requires Azure DevOps Server 2020 or later version. - -::: moniker-end - # [TCM CLI](#tab/tcm-cli) You can use the TCM command-line tool to clone a test plan to the same or different project, and to track the status of the clone operation. [List test plans](#list-test-plans) | [Clone a test plan](#clone-test-plan) | [Track test plan clone status](#track-test-plan-clone-status) - ### Clone a test plan -Use `tcm plans /clone` to initiate a cloning operation of all test cases from one test suite to a different destination suite within the same project. The destination suite must be defined and exist in a different plan. All contained suites and test cases are cloned. The command may return an operation ID that you can use to track the status and completion of the clone operation. When the clone operation completes quickly, no operation ID is returned. +Use `tcm plans /clone` to initiate a cloning operation of all test cases from one test suite to a different destination suite within the same project. The destination suite must be defined and exist in a different plan. All contained suites and test cases are cloned. The command might return an operation ID that you can use to track the status and completion of the clone operation. When the clone operation completes quickly, no operation ID is returned. ```tcm tcm plans /clone /sourceplanid:id /destinationplanname:name @@ -361,8 +306,8 @@ The `/clone /sourceplanid /destinationplanname` creates a new plan. If you speci | Parameter | Description | |----------|------------| -|**/sourceplanid**:`id` | Required. Specifies the ID of the plan to be copied, and the ID of the suite into which the new copy will be added. If you want to copy a whole test plan, use the ID of the suite at the root of the test plan.The ID of a suite is displayed in the details pane when you select it in the test plan. You can also get a list of suites by using `tcm suites /list`. | -|**/destinationplanname**:`name`|Specifies the name of the plan into which the cloned test plan will be copied. | +|**/sourceplanid**:`id` | Required. Specifies the ID of the plan to be copied, and the ID of the suite into which the new copy gets added. If you want to copy a whole test plan, use the ID of the suite at the root of the test plan. The ID of a suite is displayed in the details pane when you select it in the test plan. You can also get a list of suites by using `tcm suites /list`. | +|**/destinationplanname**:`name`|Specifies the name of the plan into which the cloned test plan gets copied. | |**/overridefield**:`name=value`
      **/overridefield**:`name=value`| Optional. Specify to change the value of a field in each cloned work item. Specify multiple occurrences of this parameter to change as many fields as you want. This option is required when you clone a test suite to a different project. | |**/sourcesuiteids**:`suiteid1,[suiteid2,...`|Optional. Specifies source test suites within the test plan to copy. | |**/clonerequirements** |Optional. Specifies to clone requirements category work items that are attached to requirements-based test suites. If you omit this parameter, requirements-based test suites are converted to static suites. | @@ -383,14 +328,12 @@ Clone operation is complete. ``` - - + ### Track the status of the test plan clone operation Use `tcm plans /clone /status` to retrieve the status of the clone operation made with `tcm suites /clone`. Test suites that contain a large number of test cases can take a considerable time to clone. - ```tcm tcm plans /clone /status:cloneoperationid @@ -400,15 +343,14 @@ tcm plans /clone | Parameter | Description | |----------|------------| -|**/status**:`cloneoperationid`|Required. Specifies the ID of the clone operation returned when `tcm plans /clone` executes. +|**/status**:`cloneoperationid`|Required. Specifies the ID of the clone operation returned when `tcm plans /clone` executes. | [!INCLUDE [prerequisites-define](includes/common-tcm-parameters.md)] - -*** +*** - - + + ## Import or clone test suites @@ -416,54 +358,47 @@ When you're creating the test plan for a new sprint, you often want to repeat so :::image type="content" source="media/copy-clone/copy-test-suite-conceptual.png" alt-text="Conceptual image, copy test suites."::: -Note the following: - -- When you import (Web) or clone (TCM) a test suite to a new project, the new suite will contain copies of all test cases in the source suite. However, it won't retain any historical data like the previous test runs, related bugs, old results. -- Shared steps referenced by the test cases are also cloned and created in the destination project. -- You can't clone test cases from and to the same test plan, even into a different suite. To accomplish this scenario, you must first move the test cases to a different, temporary test plan. Then, use the temporary test plan as the source plan and clone the test cases back to the source test plan by putting the ID into the destination test plan place. Shared steps present in the test cases will also be duplicated in this process. - +> [!NOTE] +> - When you import (Web) or clone (TCM) a test suite to a new project, the new suite contains copies of all test cases in the source suite. However, it doesn't retain any historical data like the previous test runs, related bugs, old results. +>- Shared steps referenced by the test cases are also cloned and created in the destination project. +>- You can't clone test cases from and to the same test plan, even into a different suite. To accomplish this scenario, you must first move the test cases to a different, temporary test plan. Then, use the temporary test plan as the source plan and clone the test cases back to the source test plan by putting the ID into the destination test plan place. Shared steps present in the test cases are also duplicated in this process. ::: moniker range=">= azure-devops-2020" -You can use the user interface to import a test suite from one test plan, within the same or different project, to another test plan in the current project. This action essentially copies or clones the test suite, creating a new test suite and duplicating any sub-test suites. The test cases referenced by the test suites are not duplicated, but referenced by the cloned test suites. +When you're working with Azure Test Plans, you can import a test suite from one test plan into another test plan within the current project. It doesn't matter whether the test plans are within the same project. This process involves copying or cloning the test suite, resulting in the creation of a new test suite. Additionally, any subtest suites also get duplicated. The test cases referenced by the test suites don't duplicate; instead, they get referenced by the cloned test suites. ::: moniker-end You can use [`tcm suites /list`](#list-test-suites) to list all test suites defined for a project. -In order to use the same test cases in different suites and plans, copy and paste test cases using the **Grid** view. To learn more, see (XLink to be provided) +To use the same test cases in different suites and plans, copy and paste test cases using the **Grid** view. # [Browser](#tab/browser) ::: moniker range=">= azure-devops-2020" -1. Open **Test Plans>Test plans**, and choose the test plan where you want to import a test suite from the **Mine** or **All** page. Select :::image type="icon" source="../media/icons/more-actions.png" border="false"::: **More actions**, and choose the **Copy test plan** menu option. This option lets you copy or clone test plans within a project. +1. Select **Test Plans** > **Test plans**. +2. Choose the test plan where you want to import a test suite from the **Mine** or **All** page. +3. Select :::image type="icon" source="../media/icons/more-actions.png" border="false"::: **More actions** > **Copy test plan**. This option lets you copy or clone test plans within a project. - :::image type="content" source="media/copy-clone/import-test-suites.png" alt-text="Test Suite More Actions menu, Import test suites option."::: + :::image type="content" source="media/copy-clone/import-test-suites.png" alt-text="Screenshot showing Test Suite More Actions menu, Import test suites option."::: -2. In the dialog that opens, choose the project if the test plan resides in a different project. Otherwise, select the test plan and test suite and then choose **Create**. You can only import one suite from a test plan at a time. +4. In the opened dialog, select the project if the test plan resides within a different project. Otherwise, enter the Test Plan Name or ID and Test Suite Name or ID. You can also select the name or ID from the dropdown menus. +5. **Create** the import. You can only import one suite from a test plan at a time. - :::image type="content" source="media/copy-clone/import-suites-from-test-plan-dialog.png" alt-text="Import suites from a Test Plan dialog"::: + :::image type="content" source="media/copy-clone/import-suites-from-test-plan-dialog.png" alt-text="Screenshot showing Import suites from a Test Plan dialog."::: -3. The following message displays: + The following message displays: - :::image type="content" source="media/copy-clone/import-suites-message-1.png" alt-text="Import suites initiated message."::: + :::image type="content" source="media/copy-clone/import-suites-message-1.png" alt-text="Screenshot showing Import suites initiated message."::: -4. When the import operation completes, you'll see the following message. Choose **Refresh** to refresh your browser. +6. When the import operation completes, the following message displays. Select **Refresh** to refresh your browser. - :::image type="content" source="media/copy-clone/import-suites-message-2.png" alt-text="Import suites completed message."::: + :::image type="content" source="media/copy-clone/import-suites-message-2.png" alt-text="Screenshot showing Import suites completed message."::: The newly added test suite then displays. - :::image type="content" source="media/copy-clone/imported-test-suite-displayed.png" alt-text="Imported test suite displayed."::: + :::image type="content" source="media/copy-clone/imported-test-suite-displayed.png" alt-text="Screenshot showing Imported test suite displayed."::: - -::: moniker-end - -::: moniker range="< azure-devops-2020" - -> [!NOTE] -> This feature isn't supported through the web portal for Azure DevOps Server 2019 and earlier versions. The feature to import test suites requires Azure DevOps Server 2020 or later version. - ::: moniker-end # [TCM CLI](#tab/tcm-cli) @@ -472,7 +407,6 @@ You can use the TCM command-line tool to clone a test plan to the same or differ [List test suites](#list-test-suites) | [Clone a test suite](#clone-test-suite) | [Track test suite clone status](#track-test-suite-clone-status) - ### Clone a test suite Use `tcm suites /clone` to initiate a cloning operation of all test cases from one test suite to a different destination suite within the same project by default. The destination suite must be defined and exist in a different plan. All contained suites and test cases are cloned. The command returns an operation ID that you can use to track the status and completion of the clone operation. @@ -481,7 +415,7 @@ The following options provide support for optional clone operations: - `/destinationteamproject`: Clone a suite to a different project. - `/destinationworkitemtype`: Specify the work item type to use when cloning the test cases. Specify this option when cloning test cases to a custom work item type. -- `/overridefield`: Override the values for select fields, such as the **Area Path** and **Iteration Path** fields, which is required when cloning to a different project. Or override the value of other fields to distinguish cloned test cases from the original. +- `/overridefield`: Override the values for select fields, such as the **Area Path** and **Iteration Path** fields, which is required when cloning to a different project. Or override the value of other fields to distinguish cloned test cases from the original. - `/clonerequirements`: Specify this switch to clone a requirement-based suite to a destination requirement-based suite. @@ -497,46 +431,43 @@ tcm suites /clone | Parameter | Description | |----------|------------| -|**/suiteid**:`id`|Specifies the ID of the suite to be copied, and the ID of the suite into which the new copy will be added. If you want to copy a whole test plan, use the ID of the suite at the root of the test plan. The ID of a suite is displayed in the details pane when you select it in the test plan. You can also get a list of suites by using `tcm suites /list`. | +|**/suiteid**:`id`|Specifies the ID of the suite to be copied, and the ID of the suite into which the new copy gets added. If you want to copy a whole test plan, use the ID of the suite at the root of the test plan. The ID of a suite is displayed in the details pane when you select it in the test plan. You can also get a list of suites by using `tcm suites /list`. | |**/overridefield**:`name=value`
      **/overridefield**:`name=value`| Optional. Specify to change the value of a field in each cloned work item. Specify multiple occurrences of this parameter to change as many fields as you want. This option is required when you clone a test suite to a different project. | -|**/destinationsuiteid**:`id`|Specifies the ID of the suite into which the new copy will be added. If you want to copy a whole test plan, use the ID of the suite at the root of the test plan. The ID of a suite is displayed in the details pane when you select it in the test plan. You can also get a list of suites by using `tcm suites /list`.| +|**/destinationsuiteid**:`id`|Specifies the ID of the suite into which the new copy gets added. If you want to copy a whole test plan, use the ID of the suite at the root of the test plan. The ID of a suite is displayed in the details pane when you select it in the test plan. You can also get a list of suites by using `tcm suites /list`.| |**/destinationteamproject**:`projectname`|Optional. Specify when you want to clone the test suite to a different project but in the same organization or project collection. When specified, you must specify override field values for the **Area Path** and **Iteration Path** fields.| |**/destinationworkitemtype**:`workitemtype`|Optional. Specify when you want to clone the test suite to a different work item type in the destination project. | |**/clonerequirements** | Optional. Specify this switch to clone a requirement-based suite to a destination requirement-based suite. By default, a requirement-based test suite is cloned to a destination static test suite. | [!INCLUDE [prerequisites-define](includes/common-tcm-parameters.md)] - **Understand what gets cloned** When you clone a test suite, the following objects are copied from the source test plan to the destination test plan. |Test plan object| Notes| |----------------------|------------| -|Test case| Each new test case retains its shared steps. A link is defined between the source and new test cases. The new test cases do not have test runs, bugs, test results, or build information.| +|Test case| Each new test case retains its shared steps. A link is defined between the source and new test cases. The new test cases don't have test runs, bugs, test results, or build information.| |Shared steps | Shared steps referenced by cloned test cases are copied. | -|Test suite| Test suites that are copied retain the following data:

      - Names and hierarchical structure of the test suites
      - Order of the test cases
      - Assigned testers
      - Configurations| -|Recordings | Action recordings linked from a cloned test case are copied. -|Links and Attachments|All links and attachments are copied for all copied test items. +|Test suite| Test suites that are copied retain the following data: - Names and hierarchical structure of the test suites- Order of the test cases- Assigned testers- Configurations| +|Recordings | Action recordings linked from a cloned test case are copied.| +|Links and Attachments|All links and attachments get copied for all test items that are copied. | |Test configuration|The test configuration defined for the source test plan is copied over and applied to the destination test plan.| -The following test information is not copied: +The following test information isn't copied: -- **Test settings**: The test setting for the source test plan isn't copied. Instead, the test settings for the destination test plan is applied. -- **Test results and test runs**: No test results are copied. Because test runs are applicable only to the source test plan, they are not copied. +- **Test settings**: The test setting for the source test plan isn't copied. Instead, the test settings for the destination test plan are applied. +- **Test results and test runs**: No test results are copied. Because test runs are applicable only to the source test plan, they aren't copied. When `/clonerequirements` is specified and Requirements-based test suites are copied: -- The Requirements-based test suites are copied and linked to a new copy of the requirement work item. -- Requirements work items (product backlog items or user stories) that are associated with a cloned requirements-based suite are cloned. -- Bug work items are cloned in a project that uses the Scrum process template, or any project in which the Bug work item type is in the Requirements work item category. Otherwise, bugs aren't cloned. +- The Requirements-based test suites get copied and linked to a new copy of the requirement work item. +- Requirements work items (product backlog items or user stories) that are associated with a cloned requirements-based suite get cloned. +- Bug work items get cloned in a project that uses the Scrum process template, or any project in which the Bug work item type is in the Requirements work item category. Otherwise, bugs aren't cloned. -When `/clonerequirements` in't specified and Requirements-based test suites are copied: -- Requirements-based test suites are converted to static test suites in the destination test plan. +When `/clonerequirements` in't specified and Requirements-based test suites get copied: +- Requirements-based test suites convert to static test suites in the destination test plan. - Cloned test cases are referenced under the static test suite. - Cloned test cases don't include links to their original requirements work items. - - **Example** The following example illustrates cloning test suite *97* defined for the *Fabrikam Fiber* project to the *Fabrikam Git* project. Because the test suite contained a query-based suite, a warning message is listed to review and revise the respective query in the source and destination test suites. @@ -549,16 +480,13 @@ Use /status:4 to get progress and completion information of the operation. Warning: You have cloned the following query based suites as part of this clone operation. You are advised to fix their respective queries in the source and destination suites, after the clone operation completes. 1. Sprint 3 -> Sprint 3 query-based suite ``` - - - + ### Track the status of the test suite clone operation Use `tcm suites /clone /status` to retrieve the status of the clone operation made with `tcm suites /clone`. Test suites that contain a large number of test cases can take a considerable time to clone. - ```tcm tcm suites /clone /status:cloneoperationid @@ -568,7 +496,7 @@ tcm suites /clone | Parameter | Description | |----------|------------| -|**/status**:`cloneoperationid`|Required. Specifies the ID of the clone operation returned when `tcm suites /clone` executes. +|**/status**:`cloneoperationid`|Required. Specifies the ID of the clone operation returned when `tcm suites /clone` executes. | [!INCLUDE [prerequisites-define](includes/common-tcm-parameters.md)] @@ -588,67 +516,69 @@ Requirements cloned: 0 Completed on: 10-Nov-21 5:00:30 PM ``` -*** - +*** ::: moniker range=">= azure-devops-2020" - + -## Copy test case(s) +## Copy test case From the web portal, you can copy test cases from within a project or another project to a test suite, or you can use the **Grid** view to [copy and paste test cases](#copy-paste) from one suite to another. Optionally, you can [bulk import and export test cases](#bulk-import-export). > [!TIP] -> Don't copy test cases when what you really want to do is test with [different configurations](test-different-configurations.md) or [different data](repeat-test-with-different-data.md). +> Don't copy test cases when you want to test with [different configurations](test-different-configurations.md) or [different data](repeat-test-with-different-data.md). -You can copy test cases from within a project or another project in the organization or collection to a designated test plan and test suite. At the same time, you can optionally copy all links and attachments. +You have the flexibility to copy test cases from either within a project or from another project within the organization or collection. Additionally, you can choose to include all links and attachments during the copying process. -1. Open **Test Plans>Test plans**, choose the Test Plan that contains the test case(s) you want to copy from the **Mine** or **All** page. Next, choose the Test Suite that contains the test case(s) you want to copy. From the **Define** page, select the check box for all test cases you want to copy. +1. Select **Test Plans** > **Test plans**. +2. Choose the Test Plan that contains one or more test cases you want to copy from the **Mine** or **All** page. +3. Select the Test Suite that contains one or more test cases you want to copy. +4. From the **Define** page, select the check box for all test cases you want to copy. -2. Choose :::image type="icon" source="../media/icons/more-actions.png" border="false"::: **More actions**, and choose the **Copy test case** menu option. +5. Select :::image type="icon" source="../media/icons/more-actions.png" border="false"::: **More actions** > **Copy test case**. - :::image type="content" source="media/copy-clone/copy-test-cases-menu-selection.png" alt-text="Test Cases More Actions menu, copy test cases option."::: + :::image type="content" source="media/copy-clone/copy-test-cases-menu-selection.png" alt-text="Screenshot showing Test Cases More Actions menu, copy test cases option."::: -2. From the **Copy test case(s)** dialog, choose the Project if copying test cases from a different project. Next, select the test plan and test suite to copy the test cases to. +6. Choose the Project from the dropdown menu, and then enter the Test Plan Name or ID and Test Suite Name or ID. You can also select the name or ID from the dropdown menus. - :::image type="content" source="media/copy-clone/copy-test-cases-dialog.png" alt-text="Copy test cases dialog"::: + :::image type="content" source="media/copy-clone/copy-test-cases-dialog.png" alt-text="Screenshot showing Copy test cases dialog."::: - Optionally select the check boxes for **Include existing links** and **Include existing attachments**. When done, choose **Create**. +7. (Optional) Select the check boxes for **Include existing links** and **Include existing attachments**. +8. **Create** the copy. - Depending on the number and complexity of the test cases selected, the copy operation will be performed in the background. Once completed, you'll receive a message that the operation has completed and a link to the test suite where the test cases have been copied to. + The background copy operation depends on the quantity and complexity of the selected test cases. After completion, a notification gets sent to you confirming the operation’s success and a link to the test suite where the copied test cases reside. ::: moniker-end - + -## Copy and paste test case(s) (Grid view) +## Copy and paste test case (Grid view) -You copy and paste test cases in order to use the same tests in different suites and plans. For example, you could have a test suite that uses a subset of the tests defined in a more exhaustive test suite. The **Define>Grid** view supports editing test cases as well as copy and pasting test cases to different test suites. For editing test cases, see [Create test cases, Use the Grid view to edit test cases](create-test-cases.md#use-the-grid-view-to-edit-test-cases). +When you're managing test cases, copying and pasting serve as a valuable technique to reuse the same tests across various suites and plans. For instance, consider a scenario where you have a comprehensive test suite, and you want to create a more focused subset of tests within another suite. The **Define** > **Grid** view provides support for both editing test cases and copying them to different test suites. For more information, see [Create test cases, Use the Grid view to edit test cases](create-test-cases.md#use-the-grid-view-to-edit-test-cases). > [!TIP] -> Don't copy test cases when what you really want to do is test with [different configurations](test-different-configurations.md) or [different data](repeat-test-with-different-data.md). +> Don't copy test cases when you want to test with [different configurations](test-different-configurations.md) or [different data](repeat-test-with-different-data.md). -From the Internet Explorer, Edge, or Chrome browsers, you can copy test cases from the **Grid** view for one test plan and test suite to another test plan and test suite. +From the Internet Explorer, Microsoft Edge, or Chrome browsers, you can copy test cases from the **Grid** view for one test plan and test suite to another test plan and test suite. -1. From the **Test Plans>Test plans** page, choose the test suite containing the test case(s) you want to copy. Within the **Define** tab, Choose the **Grid** view. +1. From the **Test Plans** > **Test plans** page, choose the test suite containing one or more test cases you want to copy. Within the **Define** tab, select :::image type="icon" source="../extend/media/use-a-control/grid.png" border="false"::: **Grid View**. -1. Highlight the rows you want to copy, and then enter **CTRL+C**. +2. Highlight the rows you want to copy, and then enter **CTRL+C**. - :::image type="content" source="media/copy-clone/copy-paste-test-cases.png" alt-text="Copy test cases from Grid view."::: + :::image type="content" source="media/copy-clone/copy-paste-test-cases.png" alt-text="Screenshot showing Copy test cases from Grid view."::: -1. Select a different test suite from the same or different plan and paste with **CTRL+V**. If you don't select a different suite, nothing happens when you paste, because each suite can only have one reference to any test case. +3. Select a different test suite from the same or different plan and paste with **CTRL+V**. If you don't select a different suite, nothing happens when you paste, because each suite can only have one reference to any test case. -1. Choose :::image type="icon" source="media/icons/save-test-cases.png" border="false"::: **Save test cases**. +4. Choose :::image type="icon" source="media/icons/save-test-cases.png" border="false"::: **Save test cases**. - The new test cases are saved with new IDs assigned. + The new test cases save with new IDs assigned. - :::image type="content" source="media/copy-clone/copy-paste-test-cases-saved.png" alt-text="Saved test cases pasted into Grid view."::: + :::image type="content" source="media/copy-clone/copy-paste-test-cases-saved.png" alt-text="Screenshot showing saved test cases pasted into Grid view."::: - - + ::: moniker range=">= azure-devops-2020" @@ -658,7 +588,7 @@ From the web portal, you can perform a bulk import or export of test cases from/ ### Export test cases -1. From the **Test Plans>Test plans** page, choose the test plan with the test suite containing the test cases you want to export. +1. From the **Test Plans** > **Test plans** page, choose the test plan with the test suite containing the test cases you want to export. 1. Optional. Choose :::image type="icon" source="media/icons/column-options.png" border="false"::: **Column options** to add fields to include in the download file. @@ -674,20 +604,19 @@ From the web portal, you can perform a bulk import or export of test cases from/ ### Import test cases -1. From **Test Plans>Test plans** page, choose the test plan with the test suite into which you want to import test cases. +1. From **Test Plans** > **Test plans**, choose the test plan with the test suite into which you want to import test cases. :::image type="content" source="media/copy-clone/choose-import-test-cases.png" alt-text="Screenshot of Import test cases to the selected test suite."::: -1. Choose the file to import from the dialog that opens, and then choose **Import**. +2. Choose the file to import from the opened dialog, and then select **Import**. - :::image type="content" source="media/copy-clone/import-test-cases-dialog.png" alt-text="Import Test Cases dialog."::: - -1. Choose **Confirm** in the **Confirm import** dialog that displays. If you specify test cases that are already defined in the test suite, some elements may get over written during import. + :::image type="content" source="media/copy-clone/import-test-cases-dialog.png" alt-text="Screenshot showing Import Test Cases dialog."::: +3. Select **Confirm**. If you specify test cases that are already defined in the test suite, some elements might get over written during import. ::: moniker-end - + ## Import automated test cases (TCM) @@ -703,24 +632,34 @@ tcm testcase /import /collection:teamprojectcollectionurl /teamproject:project [/login:username,[password]] ``` - | Parameter | Description | |----------|------------| |**/storage**:`path`|Specifies the path and name of the test assembly that contains your automated tests that you want to import.| |**/maxpriority**:`priority`|Optional. Specifies which tests to import based on the maximum priority of the test method. For example, if the parameter is `/maxpriority:1`, only tests with a priority attribute for the test method less than or equal to 1 are imported as test cases from the assembly.| |**/minpriority**:`priority`|Optional. Specifies which tests to import based on the minimum priority of the test method. For example, if the parameter is `/minpriority:2`, only tests with a priority attribute for the test method equal or greater than 2 are imported as test cases from the assembly.| |**/category**:`filter`|Optional. Specifies which tests to import based on the category of each test method in the test assembly. You can use this parameter together with `/syncsuite` to import tests with a certain category into a specific test suite.
      For more information about test categories, see [Run unit tests with Test Explorer](/visualstudio/test/run-unit-tests-with-test-explorer).| -|**/syncsuite**:`id`|Optional. Specifies the suite ID for the test suite in your test plan to which you want to add the test cases that you import. This suite cannot be a dynamic suite or a query-based suite. If you specify a test suite to synchronize to update tests that have already been added, the tests that aren't imported are removed from the test suite but not from the test plan itself. | +|**/syncsuite**:`id`|Optional. Specifies the suite ID for the test suite in your test plan to which you want to add the test cases that you import. This suite can't be a dynamic suite or a query-based suite. If you specify a test suite to synchronize to update added tests, the tests that aren't imported are removed from the test suite but not from the test plan itself. | [!INCLUDE [prerequisites-define](includes/common-tcm-parameters.md)] + +[!INCLUDE [limitations-import](includes/limitations-import.md)] + -## Next step +::: moniker range="<=azure-devops" + +### REST APIs + +You can copy and clone test plans and test suites using the following REST APIs. +- [Test Plan Clone - Clone Test Plan](/rest/api/azure/devops/testplan/test-plan-clone/clone-test-plan) +- [Test Suite Clone - Clone Test Suite](/rest/api/azure/devops/testplan/test-suite-clone/clone-test-suite) +::: moniker-end + +## Next steps > [!div class="nextstepaction"] > [Run manual tests](run-manual-tests.md) - ## Related articles - [Create test plans and test suites](create-a-test-plan.md) @@ -731,21 +670,3 @@ tcm testcase /import /collection:teamprojectcollectionurl /teamproject:project - [Test objects and terms](test-objects-overview.md) - [Create a query based on build and test integration fields](../boards/queries/build-test-integration.md) - [Customize and manage the test experience](/previous-versions/azure/devops/reference/witadmin/tcm-customize-manage-test-experience) - - -::: moniker range="<= azure-devops-2019" - -### Microsoft Test Manager (deprecated) - -- [Guidance on Microsoft Test Manager usage](/previous-versions/azure/devops/test/mtm/guidance-mtm-usage) -- [Copying and cloning test suites and test cases](/previous-versions/azure/devops/test/mtm/copying-and-cloning-test-suites-and-test-cases) -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -### REST APIs - -You can copy and clone test plans and test suites using the following REST APIs. -- [Test Plan Clone - Clone Test Plan](/rest/api/azure/devops/testplan/test-plan-clone/clone-test-plan) -- [Test Suite Clone - Clone Test Suite](/rest/api/azure/devops/testplan/test-suite-clone/clone-test-suite) -::: moniker-end \ No newline at end of file diff --git a/docs/test/create-a-test-plan.md b/docs/test/create-a-test-plan.md index 0257ad92f52..13d96f16779 100644 --- a/docs/test/create-a-test-plan.md +++ b/docs/test/create-a-test-plan.md @@ -1,12 +1,12 @@ --- title: Create test plans and suites -description: Learn about Test tools. Create test plans in Azure Test Plans and Azure DevOps Server to make sure each of the deliverables meets your needs. +description: Learn about Test tools and how to create test plans in Azure DevOps. ms.assetid: 99FD819E-A861-4F28-A486-FD452DB65D69 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: quickstart -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' ms.date: 11/02/2021 --- @@ -21,108 +21,70 @@ For more information about manual testing, see [What is Azure Test Plans?](overv ## Share work items across your test experience -For example, you're building version 1.* of your product and you might create several test cases for that version. -Each of these test cases can be updated, and more added, at any time. -For each development cycle and release of your product, you create a test plan and import the existing test cases into that plan. -You can also, if you wish, divide the test cases into separate test suites within the plan to enable easier management and monitoring of these separate sets of test cases. +For example, you're building version 1.* of your product and you might create several test cases for that version. Each of these test cases can be updated, and more added, at any time. +For each development cycle and release of your product, you create a test plan and import the existing test cases into that plan. You can also, if you wish, divide the test cases into separate test suites within the plan to enable easier management and monitoring of these separate sets of test cases. After you create your test plan, you [assign test configurations](test-different-configurations.md) and [assign testers](create-test-cases.md#assign-testers) to cover the required test matrix. These testers [run the tests](run-manual-tests.md) and gauge the quality of the product. Testers continue testing until the product meets exit criteria. For the next development cycle and release, you can create a new test plan and reuse the same test cases. -You repeat this development-test-release cycle by importing the same test cases into each new test plan. +Repeat this development-test-release cycle by importing the same test cases into each new test plan. -The great thing is that, because test plans refer to test cases, updates to a test case automatically reflect in all the test plans and test suites that use it. +Because test plans refer to test cases, updates to a test case automatically reflect in all the test plans and test suites that use it. -In the next version of the product, you can reuse the existing test cases. -However, a better option may be to [copy or clone the test cases](reference-qa.yml#create-manual-test-cases). A copy creates a new baseline. Changes to these new test cases don't affect your previous test plans. +In the next version of the product, you can reuse the existing test cases. However, a better option might be to [copy or clone the test cases](reference-qa.yml#create-manual-test-cases). A copy creates a new baseline. Changes to these new test cases don't affect your previous test plans. > [!TIP] > For more information about the ways you can work with test plans, test suites, and test cases, see the [FAQs for manual testing](reference-qa.yml#testplans). - +## Prerequisites [!INCLUDE [prerequisites-define](includes/prerequisites-define.md)] -[!INCLUDE [note-new-ui](includes/note-new-ui.md)] - ## Create a test plan ::: moniker range=">=azure-devops-2020" -In general, you create test plans to test requirements. Before creating a test plan, you may want to [define your backlog of requirements](../boards/backlogs/create-your-backlog.md). +In general, you create test plans to test requirements. Before you create a test plan, [define your backlog of requirements](../boards/backlogs/create-your-backlog.md). -1. From the web portal, open your project and go to **Test Plans**. - If you already have a test plan, select **Test Plans** to go to the page that lists all test plans. +1. Sign in to your Azure DevOps project and select **Test Plans** > **Test Plans**. ![Screenshot of opening the list of test plans page for Azure DevOps Server 2020 and Azure DevOps Services.](media/create-a-test-plan/open-test-plans.png) -1. In the **Test Plans** page, select **New Test Plan** to create a test plan for your current sprint. +2. Select **+ New Test Plan**. ![Screenshot of creating a new test plan for Azure DevOps Server 2020 and Azure DevOps Services.](media/create-a-test-plan/new-test-plan.png) -1. In **New Test Plan**, enter a name for the test plan. - Verify that the area path and iteration are set correctly, then select **Create**. +3. Enter a name for the test plan, verify that the area path and iteration are set correctly, and then select **Create**. ![Screenshot of adding test plan details for Azure DevOps Server 2020 and Azure DevOps Services.](media/create-a-test-plan/test-plan-name-path-iteration.png) ### Rename a test plan -To rename a test plan, use this procedure: +To rename a test plan, do the following steps. -1. Select **Test Plans** to view test plans. +1. Select **Test Plans**. -1. Next to the test plan name, select **More Actions** > **Edit**. +2. Next to the test plan name, select **More Actions** > **Edit**. ![Screenshot shows option to edit a test plan.](media/create-a-test-plan/rename-edit-test-plan.png) -1. Change the name and then select **Save & Close**. +3. Change the name and then select **Save & Close**. You can make other changes to the test plan here. ### Delete a test plan -To delete a test plan, use this procedure: +To delete a test plan, do the following steps. -1. Select **Test Plans** to view test plans. +1. Select **Test Plans**. -1. Next to the test plan name, select **More Actions** > **Delete**. +2. Next to the test plan name, select **More Actions** > **Delete**. -1. The **Permanently delete test artifacts** dialog box explains exactly what will be deleted. Type the test plan ID to confirm that you want to delete, and then select **Permanently delete**. +3. The **Permanently delete test artifacts** dialog box explains exactly what gets deleted. Enter the test plan ID to confirm that you want to delete, and then select **Permanently delete**. - ![Screenshot shows Permanently delete test artifacts dialog box.](media/create-a-test-plan/permanently-delete-test-artifacts.png) - -::: moniker-end - -::: moniker range="<=azure-devops-2019" -In general, you create test plans to test requirements. Prior to creating a test plan, therefore, you may want to [define your backlog of requirements](../boards/backlogs/create-your-backlog.md). - -1. From the web portal, open your project and go to **Test Plans**. - If you already have a test plan, choose **Test Plans** to go to the page that lists all test plans. - - ![Opening the list of test plans page](media/create-a-test-plan/goto-test-plans-page.png) - -1. In the **Test Plans** page, choose **New Test Plan** to create a test plan for your current sprint. - - ![Creating a new test plan](media/create-a-test-plan/CreateATestPlan1a.png) - -1. In **New Test Plan**, enter a name for the test plan. - Verify that the area path and iteration are set correctly, then choose **Create**. - - ![Adding test plan details](media/create-a-test-plan/CreateATestPlan2.png) - -### Rename a test plan - -To rename a test plan, open it from the shortcut menu and rename it. - -![Rename a test plan](media/create-a-test-plan/rename-test-plan.png) - -### Delete a test plan - -To delete a test plan, use the shortcut menu for the test plan. - -![Delete a test plan](media/create-a-test-plan/delete-test-plan.png) + ![Screenshot shows permanently delete test artifacts dialog box.](media/create-a-test-plan/permanently-delete-test-artifacts.png) ::: moniker-end @@ -156,32 +118,6 @@ Now add test suites for the backlog items that need manual tests. These tests co ::: moniker-end -::: moniker range="<=azure-devops-2019" -Now add test suites for the backlog items that need manual tests. These tests could be user stories, requirements, or other work items based your project. - -> [!NOTE] -> Requirement tracking is supported only for test cases linked through a **Requirement-based test suite**. The association between a requirement work item—User Story ([Agile](../boards/work-items/guidance/agile-process.md)), Product Backlog Item ([Scrum](../boards/work-items/guidance/scrum-process.md)), Requirement ([CMMI](../boards/work-items/guidance/cmmi-process.md)), or Issue ([Basic](../boards/get-started/plan-track-work.md)) and manual test execution is only formed when the test case is linked via a **Requirement-based test suite**. - -1. To add a suite to a test plan, select the **+** new drop-down list and choose a type of test suite. - - ![Creating a requirement-based test suite](media/create-a-test-plan/AddRequirementSuitesToTestPlan.png) - - You use requirement-based suites to group your test cases together. - That way, you can track the testing status of a backlog item. - Each test case that you add to a requirement-based test suite is automatically linked to the backlog item. - -1. In **Create requirement-based suites**, add one or more clauses to filter your work items by the iteration path for the sprint. - Run the query to view the matching backlog items. - - ![Adding clauses to filter by iteration and running the query to view results](media/create-a-test-plan/AddRequirementSuitesToTestPlan2.png) - -1. In the list of work items returned by the query, select the backlog items you want to test in this sprint. - Choose **Create suites** to create a requirement-based suite for each one. - - ![Adding requirement-based suites for your backlog items](media/create-a-test-plan/AddRequirementSuitesToTestPlan3.png) - -::: moniker-end - ## Work with test suites You can create a static test suite that can contain any type of test suites. Use these test suites like folders. Drag test suites to group them in a static test plan. Drag and drop tests to reorder them. @@ -191,32 +127,22 @@ You can create a static test suite that can contain any type of test suites. Use ::: moniker-end -::: moniker range="<=azure-devops-2019" -![Screenshot shows using drag and drop to reorder tests.](media/create-a-test-plan/AddRequirementSuitesToTestPlan4.png) -::: moniker-end - You can track changes to test plans and test suites. Open the work item for the test plan or test suite, then view the work item history. For test suites, other actions are tracked in the **Test Suite Audit** field. For example, adding and removing test cases from a test suite are tracked in this field. -You can export test plans, test suites, and test cases. +Export test plans, test suites, and test cases. ::: moniker range=">=azure-devops-2020" Select **Export test cases to CSV**. ![Screenshot shows a test plan selected and the Export test cases to CSV option.](media/create-a-test-plan/export-test-cases.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -Select the details that you want in the report. -Then email or print this report for review. - -![Right-click a test suite, and choose Export.](media/create-a-test-plan/ExportTestPlanHTML.png) -::: moniker-end Change the test case fields in the report by adding or removing columns from the list view of the test suite. > [!IMPORTANT] -> You cannot export more than 75 Test Suites in a single operation. +> You can't' export more than 75 Test Suites in a single operation. > The email supports up to 1MB of data. @@ -229,17 +155,6 @@ In **Test Plans** for your test plan, use the :::image type="icon" source="media ![Screenshot shows finding a test plan for Azure DevOps Server 2020 and Azure DevOps Services.](media/create-a-test-plan/filter-select-test-plan.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" - -In **Test Plans** for your test plan, use the :::image type="icon" source="media/create-a-test-plan/filter-icon.png" border="false"::: filter icon (**1**) to show the search and filter lists (**2**) that help you find the tests you want to work with. -Or filter the list of tests using **Outcome**, **Tester**, and **Configuration** (**3**). - - ![Finding a test plan](media/create-a-test-plan/select-test-plan.png) - -::: moniker-end - - - ## Next steps > [!div class="nextstepaction"] diff --git a/docs/test/create-test-cases.md b/docs/test/create-test-cases.md index 5c35fa82d0a..f6df70ecb03 100644 --- a/docs/test/create-test-cases.md +++ b/docs/test/create-test-cases.md @@ -6,231 +6,141 @@ ms.assetid: C3C10A82-C7F2-4AB6-9CED-B43DAF722800 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: quickstart -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' ms.date: 11/04/2021 --- - # Create manual test cases [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Create manual test cases to check that each deliverable meets your users' needs. Manual test cases define individual steps testers perform, including steps that are shared across test cases. To test different data, you specify parameters for the test steps. To learn more, see [Share steps between test cases](share-steps-between-test-cases.md) and [Repeat a test with different data](repeat-test-with-different-data.md). For an overview of test artifacts, see [Test objects and terms](test-objects-overview.md). - -Organize your test cases by adding them to test plans and test suites. Then assign testers to run the tests. +Create manual test cases to check that each deliverable meets your users' needs. Manual test cases define individual steps testers perform, including steps that are shared across test cases. To test different data, you specify parameters for the test steps. For more information, see [Share steps between test cases](share-steps-between-test-cases.md) and [Repeat a test with different data](repeat-test-with-different-data.md). For an overview of test artifacts, see [Test objects and terms](test-objects-overview.md). -For an overview of test artifacts, see [Test objects and terms](test-objects-overview.md). +Organize your test cases by adding them to test plans and test suites, and then assign testers to run the tests. For more information, see [Test objects and terms](test-objects-overview.md). > [!NOTE] > Test iterations are designed to support data-driven scenarios, not workflow-driven scenarios. From a best practice perspective, if you have two test scenarios where the workflows are different, consider creating separate test cases. Also see [FAQs for manual testing](reference-qa.yml#testcases). -[!INCLUDE [prerequisites-define](includes/prerequisites-define.md)] +## Prerequisites -[!INCLUDE [note-new-ui](includes/note-new-ui.md)] +[!INCLUDE [prerequisites-define](includes/prerequisites-define.md)] ## Create test cases + ::: moniker range=">=azure-devops-2020" 1. If you haven't already, [create a test plan and requirement-based test suites](create-a-test-plan.md). -1. Select a requirement-based test suite. - To the right, select the **New Test Case** button. +2. Select a requirement-based test suite and select **New Test Case**. - ![Screenshot shows test cases with New Test Case button highlighted.](media/create-test-cases/new-test-case-button.png) - - If you have no existing test cases, the button appears in the lower right. + ![Screenshot showing test cases with New Test Case button highlighted.](media/create-test-cases/new-test-case-button.png) > [!NOTE] - > The [test suite](create-a-test-plan.md) shown here was created from a User Story work item in the team's backlog board. - > When you add a test case to this kind of suite, the test case is automatically linked to the backlog item. - > To create test cases this way, open the context menu for the work item and choose **Add test**. - -1. In the new work item, enter a title. Select the **Click or type here to add a step** option. + > The [test suite](create-a-test-plan.md) shown here was created from a User Story work item in the team's backlog board. When you add a test case to this kind of suite, the test case automatically links to the backlog item. To create test cases this way, open the context menu for the work item and choose **Add test**. - ![Screenshot shows the steps entered for a test case.](media/create-test-cases/test-case-steps.png) +3. In the new work item, enter a title and select **Click or type here to add a step**. - Add test steps with a description of the action required to carry out the test and the expected results so that any team member can run the test. - You can add attachments to a step if you want. - Repeat until you have added all the steps for the test. + ![Screenshot showing the steps entered for a test case.](media/create-test-cases/test-case-steps.png) - > [!NOTE] - > You can share steps between test cases. For more information, see [Share steps](share-steps-between-test-cases.md). +4. Add test steps with a description of the action required to carry out the test and the expected results so that any team member can run the test. You can add attachments to a step if you want. Repeat until you add all the steps for the test. - Now you've created a test case that you can run. - -You can also copy test cases. For more information, see [Copy or clone stories, issues and other work items](../boards/backlogs/copy-clone-work-items.md). + A test case that you can run gets created. + + For more information, see [Share steps](share-steps-between-test-cases.md) and [Copy or clone stories, issues and other work items](../boards/backlogs/copy-clone-work-items.md). ## Assign configurations to test cases You can specify configurations, such as different operating systems, web browsers, and other variations for your tests. -To assign test configurations to all test cases in a test suite, select the test suite, select **More options** or right-click to open the context menu, and then select **Assign configurations**. +- Select the test suite > **More options** > **Assign configurations**, and in the dialog box, select your configurations. -In the **Assign configurations to test suite** dialog box, select the configurations you want. +![Screenshot showing the Assign configurations to test suite dialog box with some options selected.](media/create-test-cases/assign-configurations-test-suite.png) -![Screenshot shows the Assign configurations to test suite dialog box with some options selected.](media/create-test-cases/assign-configurations-test-suite.png) - -You can also assign configurations to individual test cases. Select one or more test cases, select **More options** or right-click to open the context menu, and then select **Assign configuration**. - -The **Assign configurations to selected test cases** dialog box opens. Make and save your changes. + You can also assign configurations to individual test cases. Select one or more test cases, select **More options** > **Assign configuration**. + +- Make your changes and then **Save**. -For more information about configurations, see [Test different configurations](test-different-configurations.md). +For more information, see [Test different configurations](test-different-configurations.md). ## Reorder test cases You can reorder manual test cases in static suites, requirement-based suites, and query-based suites. -Open a test case, then use the up and down arrows to change the order. -![Screenshot showing the arrows used to move test steps up or down.](media/create-test-cases/change-step-order.png) +Open a test case, and then use the up and down arrows to change the order. -There are also options to change order in the step context menu. +![Screenshot showing the arrows used to move test steps up or down.](media/create-test-cases/change-step-order.png) ## Add existing test cases to a test suite -You can add existing test cases to a test suite. +Add existing test cases to a test suite with the following actions. -1. Select a test suite. From the **New Test Case** menu, select **Add existing test case**. +1. Select a test suite. From the **New Test Case** menu, select **Add existing test cases**. - ![Screenshot shows the Add existing test cases option to select.](media/create-test-cases/add-existing-test-cases.png) + ![Screenshot showing the Add existing test cases option to select.](media/create-test-cases/add-existing-test-cases.png) -1. In the **Add test cases to suite** dialog box, add search clauses, as needed, and then select **Run query**. +1. Add search clauses, as needed, and then select **Run query**. - ![Screenshot shows the Add test cases to suite dialog box with the Run query button highlighted.](media/create-test-cases/add-test-case-suite.png) + ![Screenshot showing the Add test cases to suite dialog box with the Run query button highlighted.](media/create-test-cases/add-test-case-suite.png) -1. After you find the test cases you want, select **Add test cases**. - -::: moniker-end - -::: moniker range="<=azure-devops-2019" -1. If you haven't already, [create a test plan and requirement-based test suites](create-a-test-plan.md). - -1. Select a requirement-based test suite. In the right-hand pane, choose **+** (New) - and then choose **New test case**. - - ![Select the test suite for a backlog item and adding a new test case](media/create-test-cases/CreateTest_1.png) - - > The [test suite](create-a-test-plan.md) shown here was created from a User Story work item in the team's backlog board. - > When you add a test case to this kind of suite, the test case is automatically linked to the backlog item. - > To create test cases this way, open the shortcut menu for the work item and choose **Add test**. - -1. Choose the **Click or type here to add a step** link and add test steps - with a description of the action required to carry out the test and the - expected results so that any team member can run the test. - You can add attachments to a step if you want. Repeat until you have added - all the steps for the test. Now you've created a test case that you can run. - - ![Creating the steps for a new manual test case](media/create-test-cases/CreateTest_3.png) - - You can share steps between test cases. For more information, see [Share steps](share-steps-between-test-cases.md). - - [How can I find an existing test case within a test plan?](create-a-test-plan.md#findplan) - -You can reorder manual test cases in static suites, requirement-based suites, and query-based suites. -Choose **Order tests** on the tool bar, then drag and drop one or more tests. -Or open the shortcut menu for a test to move it to the top or to another position. -After reordering the tests, you can sort them by the **Order** field and then run them in that order with the web runner. - -![Order test cases](media/create-test-cases/OrderTestCases.png) +2. When you find the test cases you want, highlight them and select **Add test cases**. ::: moniker-end > [!TIP] -> You can create a test case that automatically links to a requirement—User Story ([Agile](../boards/work-items/guidance/agile-process.md)), Product Backlog Item ([Scrum](../boards/work-items/guidance/scrum-process.md)), Requirement ([CMMI](../boards/work-items/guidance/cmmi-process.md)), or Issue ([Basic](../boards/get-started/plan-track-work.md))—when you create a test from the Kanban board. To learn more, see [Add, run, and update inline tests](../boards/boards/add-run-update-tests.md). -> +> You can create a test case that automatically links to a requirement—User Story ([Agile](../boards/work-items/guidance/agile-process.md)), Product Backlog Item ([Scrum](../boards/work-items/guidance/scrum-process.md)), Requirement ([CMMI](../boards/work-items/guidance/cmmi-process.md)), or Issue ([Basic](../boards/get-started/plan-track-work.md))—when you create a test from the board. For more information, see [Add, run, and update inline tests](../boards/boards/add-run-update-tests.md). ## Use the Grid view to edit test cases ::: moniker range=">=azure-devops-2020" -You can copy and paste test cases into the **Grid** view. - -To open the **Grid** view, select the **Grid View** icon at the right. +Do the following steps to copy and paste test cases into the **Grid** view. -![Screenshot shows the Grid View button used to open the Grid view.](media/create-test-cases/grid-view-button.png) +1. Select the **Grid View** icon. -Instead, you can select several test cases and open them for editing in the **Grid** view. In the context menu, select **Edit test case(s) in grid**. + ![Screenshot showing the Grid View button used to open the Grid view.](media/create-test-cases/grid-view-button.png) -![Screenshot shows several test cases selected with the context menu open and Edit test case(s) in grid selected.](media/create-test-cases/edit-multiple-test-cases-grid.png) +2. Select one to several test cases, and then select **Edit test case(s) in grid**. -On the **Grid** context menu, you can add, delete, or clear rows. + ![Screenshot showing several test cases selected with the context menu open and Edit test case(s) in grid selected.](media/create-test-cases/edit-multiple-test-cases-grid.png) -![Screenshot shows the Grid context menu to insert, delete, or clear rows.](media/create-test-cases/grid-context-menu.png) +3. Add, delete, or clear rows. -You can use the **Grid** view when you add multiple test cases to the test suite: + ![Screenshot showing the Grid context menu to insert, delete, or clear rows.](media/create-test-cases/grid-context-menu.png) -![Screenshot shows option to add test cases using the Grid view.](media/create-test-cases/add-test-cases-grid.png) +4. Optional. To add multiple test cases to the test suite, select **Add test cases using grid**. -You can edit other fields in the **Grid** view. -In the **List** view, use the column options to select the fields in the test case work item. + ![Screenshot showing option to add test cases using the Grid view.](media/create-test-cases/add-test-cases-grid.png) + - In the **List** view, use the column options to select the fields in the test case work item. -![Screenshot shows the Column Options button.](media/create-test-cases/column-options.png) + ![Screenshot showing the Column Options button.](media/create-test-cases/column-options.png) -You can then view and edit these fields when you switch to the **Grid** view. + View and edit these fields when you switch to the **Grid** view. ::: moniker-end -::: moniker range="<=azure-devops-2019" -Switch between **Grid** and **List** views using the **View** menu at the right of the window. - -![Use the View menu to switch between List and Grid views.](media/create-test-cases/GridViewSwitch.png) - -On the grid shortcut menu, you can add, delete, or clear rows. - -![Use the grid's shortcut menu to insert, delete, or clear rows.](media/create-test-cases/GridContextMenu.png) - -You can use the **Grid View** when you add multiple test cases to the test suite: - -![Create new test cases using the grid.](media/create-test-cases/NewTestCasesUsingGrid.png) -> [!NOTE] -> Do not use the Teams plugin for Excel to add or update test case work items. -> Excel cannot parse the format used to store test steps, and in some cases -> this may affect the formatting of the test case work items. - -You can edit other fields in the **Grid** view. -In the **List** view, use the column options to select the fields in the test case work item. - -![Use column options to select fields to edit](media/create-test-cases/UseColumnOptions.png) - -You can then view and edit these fields when you switch to the Grid view. -::: moniker-end - -### Use Excel to copy test case information into a Grid view +### Use Excel to copy information into a Grid view ::: moniker range=">=azure-devops-2020" You can copy test cases and test steps from an existing Excel worksheet. Copy the columns from Excel that you want to use for the title, action, and expected results fields. -Copying does not copy column formatting, other than multiline, from the worksheet. +Copying doesn't copy column formatting, other than multiline, from the worksheet. Paste these columns into the **Grid** view, edit if necessary, and save them. -![Screenshot shows the save option for steps copied from Excel to the Grid view.](media/create-test-cases/save-test-cases-grid.png) +![Screenshot showing the save option for steps copied from Excel to the Grid view.](media/create-test-cases/save-test-cases-grid.png) You can copy the data from the **Grid** view and paste it into your Excel worksheet. -Copying does not copy test step formatting, other than multiline, into the worksheet. +Copying doesn't copy test step formatting, other than multiline, into the worksheet. > [!NOTE] -> Do not use the Teams plugin for Excel to add or update test case work items. -> Excel cannot parse the format used to store test steps, and in some cases this may affect the formatting of the test case work items. +> Don't use the Teams plugin for Excel to add or update test case work items. +> Excel can't parse the format used to store test steps, and in some cases this may affect the formatting of the test case work items. ::: moniker-end -::: moniker range="<=azure-devops-2019" -You can copy test cases and test steps from an existing Excel worksheet. -This is supported only with Internet Explorer and Chrome browsers. - -Copy the columns from Excel that you want to use for the title, action, and expected results fields. -Copying does not copy column formatting, other than multiline, from the worksheet. -Paste these columns into the **Grid** view, edit if necessary, and save them. - -![Save copied test cases in grid view](media/create-test-cases/SaveTestCasesInGrid.png) - -You can copy the data from the **Grid** view and paste it into your Excel worksheet. -Copying does not copy test step formatting, other than multiline, into the worksheet. -::: moniker-end - ## Assign testers @@ -243,14 +153,14 @@ Testers need [Basic access](../organizations/security/access-levels.md) to run t 1. In the context menu for a test suite, select **Assign testers to run all tests**. - ![Screenshot shows the Assign testers to run all tests option in a test suite context menu.](media/create-test-cases/assign-testers-all-tests.png) + ![Screenshot showing the Assign testers to run all tests option in a test suite context menu.](media/create-test-cases/assign-testers-all-tests.png) The **Select testers to run all the tests in suite** dialog box opens. 1. Add or remove testers from the list. After you select the testers, select **Send email** and edit the message as required so they know that tests are ready for them to run. - ![Screenshot shows Assigning testers to run all tests dialog box with Search users and Send email called out.](media/create-test-cases/select-testers-dialog-box.png) + ![Screenshot showing Assigning testers to run all tests dialog box with Search users and Send email called out.](media/create-test-cases/select-testers-dialog-box.png) The email contains a link that testers can open to see the list of assigned tests. @@ -258,50 +168,26 @@ You can assign an individual test case to a tester. 1. In the **Execute** tab for a test suite, select a test, and then open the context menu. - ![Screenshot shows the context menu for a test case with the Assign tester option selected.](media/create-test-cases/assign-tester-test-case.png) + ![Screenshot showing the context menu for a test case with the Assign tester option selected.](media/create-test-cases/assign-tester-test-case.png) 1. Select **Assign tester**. Search for and select a tester. ::: moniker-end -::: moniker range="<=azure-devops-2019" -1. You can reassign test cases so that another tester can - run them. Select the tests that you want to reassign. Then - open the shortcut menu (choose the "..." ellipses or right-click) - and select the tester you want to run the tests. - - ![Reassigning tests to a different tester](media/create-test-cases/AssignTester.png) - - Or, you can assign all the test cases in a test suite to multiple testers. - This is useful for acceptance testing. Open the shortcut menu for the test plan - and choose **Assign testers to run all tests**. - - ![Assigning testers to run all tests](media/create-test-cases/AssignMultipleTesters.png) - -1. Add or remove testers from the list. After you select the testers, tick the **Send email** - checkbox and edit the message as required so they know that tests are ready for them to run. - - ![Send emails to testers](media/create-test-cases/AssignMultipleTestersEmail.png) - - The email contains a link that testers can open to see the list of assigned tests. - Testers need just [Basic access](../organizations/security/access-levels.md) - to run tests from Azure Test Plans. - -::: moniker-end - ## Manage test cases ::: moniker range=">=azure-devops-2020" You can open a test case to view it or edit it. -To open a test case in a test suite, in the **Define** tab, double-select the name of the test case to open. -In the **Execute** tab, select a test case, open its context menu, and select **Edit test case**. -![Screenshot show the Edit test case option for a test case in the context menu](media/create-test-cases/open-test-case-edit.png) +1. To open a test case in a test suite, in the **Define** tab, double-select the name of the test case to open. +2. In the **Execute** tab, select a test case, open its context menu, and select **Edit test case**. + +![Screenshot showing the Edit test case option for a test case in the context menu.](media/create-test-cases/open-test-case-edit.png) A test case can be linked to test suites, requirements, and bugs. To see linked items, in the **Define** tab, open the context menu for a test case, and select **View Linked Items**. -![Screenshot shows the Linked Items dialog box for a test case with options to view Test Suites, Requirements, and Bugs.](media/create-test-cases/view-linked-items.png) +![Screenshot showing the Linked Items dialog box for a test case with options to view Test Suites, Requirements, and Bugs.](media/create-test-cases/view-linked-items.png) In the **Linked Items** dialog box, you can view **Test Suites**, **Requirements**, and **Bugs**. @@ -309,7 +195,7 @@ In the **Linked Items** dialog box, you can view **Test Suites**, **Requirements You can edit more than one test case at a time. Select several test cases in a test suite and select **Edit test case(s)**. -![Screenshot shows the Edit work items dialog box where you can select fields and values for several test cases.](media/create-test-cases/bulk-edit-work-items.png) +![Screenshot showing the Edit work items dialog box where you can select fields and values for several test cases.](media/create-test-cases/bulk-edit-work-items.png) Select a **Field** and enter a **Value**. Select **Add new field** to add another field-value pair. @@ -319,61 +205,31 @@ You can tag test cases and view only the ones with specific tags. For example, tag all the tests related to signing in so that you can rerun these tests if a bug is fixed for that page. You can filter on that tag from the **Test Plans** web portal. -To add new tags to add to work items, you must have **Basic** access or higher and have the project-level **Create new tag definition permissions** set to **Allow**. for more information, see [Add work item tags](../boards/queries/add-tags-to-work-items.md). +To add new tags to add to work items, have at least **Basic** access and have the project-level **Create new tag definition permissions** set to **Allow**. for more information, see [Add work item tags](../boards/queries/add-tags-to-work-items.md). You can add and edit tags when you edit a test case, or bulk edit tags in the **Grid** view. You can also create suites based on queries when you use tags. -![Screenshot shows tags for a test case.](media/create-test-cases/test-case-tags.png) +![Screenshot showing tags for a test case.](media/create-test-cases/test-case-tags.png) ## Rename or remove test cases You can rename or remove test cases. Open the test case from its context menu. -![Screenshot shows a test case with its context menu with Open test case selected.](media/create-test-cases/open-test-case-option.png) +![Screenshot showing a test case with its context menu with Open test case selected.](media/create-test-cases/open-test-case-option.png) Here you can rename the test case. -![Screenshot shows a test case with its name selected to edit.](media/create-test-cases/change-test-case-name.png) +![Screenshot showing a test case with its name selected to edit.](media/create-test-cases/change-test-case-name.png) Or you can remove the test case from the test suite. From the context menu for the test case, select **Remove**. -![Remove a test case.](media/create-test-cases/remove-test-case.png) - -To permanently delete test plans and test suites, you must be a member of the Project Administrators group or have the Area Path node-level [**Manage test plans** or **Manage test suites**](../organizations/security/set-permissions-access-work-tracking.md#manage-test-artifacts) permission set to **Allow**. To manage or delete test artifacts, you must also have your [access level](../organizations/security/access-levels.md) set to **Basic + Test Plans** or **Visual Studio Enterprise**. For more information, see [Delete test artifacts in Azure Boards](../boards/backlogs/delete-test-artifacts.md). -::: moniker-end - -::: moniker range="<=azure-devops-2019" -You can tag test cases and view test cases only with specific tags. -For example, tag all the tests related to signing in so that you can rerun these tests if a bug is fixed for that page. -Then you can filter on that tag from the **Test Plans** web portal. - -To add new tags to add to work items, you must have **Basic** access or higher and have the project-level **Create new tag definition permissions** set to **Allow**. for more information, see [Add work item tags](../boards/queries/add-tags-to-work-items.md). - -You can add and edit tags when you edit a test case, or bulk edit tags in the grid view. -You can also create suites based on queries when you use tags. - -![In the **Test Plans** web portal, on the Test Plans page, choose or add tags from the test case pane](media/create-test-cases/TestHubTags.png) - -You can rename or delete test cases. Open the test case from its shortcut menu. - -![Open a test case for editing](media/create-test-cases/open-test-case.png) - -Here you can rename the test case. - -![Rename a test case](media/create-test-cases/rename-test-case.png) - -Or you can permanently delete the test case. - -![Delete a test case](media/create-test-cases/delete-test-case.png) - -To delete test plans and test suites, you must be a member of the Project Administrators group or have the Area Path node-level Manage test plans or Manage test suites permission set to Allow. -To manage or delete test artifacts, you must also have your access level set to Basic + Test Plans or Visual Studio Enterprise. +![Screenshot showing removed test case.](media/create-test-cases/remove-test-case.png) -To delete test plans and test suites, you must be a member of the Project Administrators group or have the Area Path node-level [**Manage test plans** or **Manage test suites**](../organizations/security/set-permissions-access-work-tracking.md#manage-test-artifacts) permission set to **Allow**. To manage or delete test artifacts, you must also have your [access level](../organizations/security/access-levels.md) set to **Basic + Test Plans** or **Visual Studio Enterprise**. For more information, see [Delete test artifacts in Azure Boards](../boards/backlogs/delete-test-artifacts.md). +To permanently delete test plans and test suites, be a member of the Project Administrators group or have the Area Path node-level [**Manage test plans** or **Manage test suites**](../organizations/security/set-permissions-access-work-tracking.md#manage-test-artifacts) permission set to **Allow**. To manage or delete test artifacts, you must also have your [access level](../organizations/security/access-levels.md) set to **Basic + Test Plans** or **Visual Studio Enterprise**. For more information, see [Delete test artifacts in Azure Boards](../boards/backlogs/delete-test-artifacts.md). ::: moniker-end -## Next step +## Next steps > [!div class="nextstepaction"] > [Run manual tests](run-manual-tests.md) diff --git a/docs/test/custom-fields.md b/docs/test/custom-fields.md new file mode 100644 index 00000000000..7a586823dae --- /dev/null +++ b/docs/test/custom-fields.md @@ -0,0 +1,80 @@ +--- +title: Custom fields for test runs and test results +description: Store custom data against the test runs and test results. +ms.assetid: 606679F2-1604-40EA-A720-63CDDA93DD76 +ms.service: azure-devops-test-plans +ms.custom: UpdateFrequency3 +ms.topic: how-to +ms.author: vijayma +author: vijayma +ms.date: 06/26/2024 +monikerRange: '= azure-devops' +--- + +# Custom fields + +[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] + +Using the custom fields allows [storing the custom data](#store-custom-data) against the test run and/or test result. +There can be up to 100 custom fields defined for a single Azure DevOps project. +Project administrator can [manage (add/delete) the set of the custom fields](#managing-custom-fields). + +## Prerequisites + +[!INCLUDE [prerequisites-define](includes/prerequisites-define.md)] + + + +## Manage the custom fields + +There are two ways to manage the custom fields - either via [REST API](/rest/api/azure/devops/testresults/extensionfields) +or project administrator can do that through the **Project settings** while choosing **Test management** under **Pipelines**. +On that page new custom field can be added by clicking on the **+ Add new** button. + +:::image type="content" source="./media/custom-fields/test-management-settings.png" alt-text="Screenshot of project settings with the test management settings selected and the button to add a new custom field marked by red rectangle."::: + +Choose **+ Add new** to add a new custom field. Each custom field must have a name, type configured, and indicate what type of artifact it applies to. + +:::image type="content" source="./media/custom-fields/add-custom-field.png" alt-text="Screenshot of a dialog used to add a new custom field."::: + +The name of custom field cannot be longer than 50 characters (spaces, numbers, and special characters are not allowed) and must be unique in the project. +The names are case insensitive, so you cannot have one custom field named "Test" and the other one named "test". +Type can be one of the following: +- Bit +- DateTime +- Int +- Float +- String +- Guid + +The existing custom fields can either be edited (only name can be changed) or removed. + +> [!NOTE] +> After removing the custom field, you cannot use its name for about a day. +> The background process that is removing the deleted custom fields permanently is run ones a day. + + + +## Store custom data into custom fields + +You can store your custom data into the configured custom fields either as part of the test run/result creation or after the test run/result was created. +Both can be done using REST API for now. In the future we will allow the custom data to be picked up from the test results file. +To get the values stored in your custom fields for the existing test run/result, you must use the REST API. +For the moment we do not display the custom fields and values stored in these on the Azure DevOps UI (we will be adding that ability in the future). + +When you’re creating test run and/or result via REST API and want to store custom data to existing custom field, then the best option for you is to send the custom data as part of the test run and/or result creation. +To create a test run call [REST API Runs - Create](/rest/api/azure/devops/test/runs/create) and to create test result call [REST API Results - Add](/rest/api/azure/devops/test/results/add). + +When the test run and/or result is not created via REST API, but by other means, then you must first find the identification of the test run or result for which you want to set (or update) +the custom data in the custom fields and then call [REST API Runs - Update](/rest/api/azure/devops/test/runs/update) for the test run +and [REST API Results - Update](/rest/api/azure/devops/test/results/update) for the test result. + +To retrieve the custom data from the custom fields stored previously against the test run and/or result, you must first find the identification of the test run or result. +Then you can call [REST API Runs - Query](/rest/api/azure/devops/test/runs/query) for the test run +and [REST API Results - Get](/rest/api/azure/devops/test/results/get) for the test result. + +The custom data for the custom fields are sent or received in an array. +Each item of that array contains two properties "fieldname" and "value" and you can see an example of that [here](/rest/api/azure/devops/test/results/get#customtestfield). +The value is object of the type that matches the type configured for the custom field. +To understand the type of the custom field you may want to use [REST API](/rest/api/azure/devops/testresults/extensionfields/query) that provides array of the custom fields. +For each field you can find there its ID, name, type and scope. You may also hardcode the type if you know what the type of the custom field of given name is. diff --git a/docs/test/explore-workitems-exploratory-testing.md b/docs/test/explore-workitems-exploratory-testing.md index 0921b7f5346..cb8b6585e86 100644 --- a/docs/test/explore-workitems-exploratory-testing.md +++ b/docs/test/explore-workitems-exploratory-testing.md @@ -1,112 +1,106 @@ --- title: Explore work items when exploratory testing -description: Test tools - Manual and exploratory testing - explore work items from the Kanban board or by using the Microsoft Test & Feedback extension +description: Test tools - Manual and exploratory testing - explore work items from the board or by using the Microsoft Test & Feedback extension ms.assetid: AFD66FBF-5DEC-4457-8867-A47FFB8EF407 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' -ms.date: 09/14/2021 +ms.date: 02/13/2025 --- # Explore work items with the Test & Feedback extension [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Use the Test & Feedback extension to explore existing work items and -associate them with a new or an in-progress exploratory session. -After a work item is associated with a session, all new bugs, tasks and test cases created -in the current session are automatically linked to that work item. -This enables end-to-end traceability, and simplifies tracking -and management of issues. +Use the Test & Feedback extension to explore existing work items and associate them with a new or ongoing exploratory session. Once a work item is associated with a session, all new bugs, tasks, and test cases created in that session are automatically linked to the work item. This extension enables end-to-end traceability and simplifies the tracking and management of issues. -You can explore: +Explore the following items: +- Work items in the requirement, feature, or epic categories, and requirements-based test suites and test cases +- A work item from the [board](#kanban) or the [extension](#extension) +- [Multiple work items in the same session](#multipleitems) -* Work items belonging to a requirement category, a feature category, or an epic category -* Requirements-based test suites and test cases. +## Prerequisites -You can explore a work item from the [Kanban board](#kanban) or from the [extension](#extension). -You can also explore [multiple work items in the same session](#multipleitems). - -[!INCLUDE [prerequisites-define](includes/prerequisites-stakeholder.md)] +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - At least **Basic** access, with permissions to view work items under the corresponding Area Path.
      - To add test plans and test suites, delete test artifacts, and define test configurations: [Basic + Test Plans](https://marketplace.visualstudio.com/items?itemName=ms.vss-testmanager-web) access.
      Or, one of the following **Visual Studio subscriptions**:
      - [Enterprise](https://visualstudio.microsoft.com/vs/enterprise/)
      - [Test Professional](https://visualstudio.microsoft.com/vs/test-professional/)
      - [MSDN Platforms](https://visualstudio.microsoft.com/msdn-platforms/) | +| **Permissions** | - To add or modify test plans, test suites, test cases, or other test-based work item types: **Edit work items in this node** permission set to **Allow** under the corresponding **Area Path**.
      - To modify test plan properties such as build and test settings: **Manage test plans** permission set to **Allow** under the corresponding **Area Path**.
      - to create and delete test suites, add and remove test cases from test suites, change test configurations associated with test suites, and modify a test suite hierarchy (move a test suite): **Manage test suites** permission set to **Allow** under the corresponding **Area Path**. | +|**Extensions**| [Test & Feedback](https://marketplace.visualstudio.com/items?itemName=ms.vss-exploratorytesting-web) extension. If the extension isn't installed, the option to explore work items from the board isn't visible.| -## Explore work items from the Kanban board +## Explore work items from the board -1. In the Kanban board, open the shortcut menu of the work item - you want to explore, and choose **Do exploratory testing**. +1. On the board, open the shortcut menu for the work item you want to explore and select **Do exploratory testing**. - ![Opening the Do exploratory testing menu item](media/explore-workitems-exploratory-testing/explore-workitems-01.png) + ![Screenshot showing opening the Do exploratory testing menu item.](media/explore-workitems-exploratory-testing/explore-workitems-01.png) -1. A banner in the Work hub shows which work item is associated with your session. + A banner in the Work hub displays the work item associated with your session. - ![The banner shows the work item for your session](media/explore-workitems-exploratory-testing/explore-workitems-02.png) + ![Screenshot showing the banner with the work item for your session.](media/explore-workitems-exploratory-testing/explore-workitems-02.png) -1. Launch the Test & Feedback extension. - If there are acceptance criteria for the work item, these are shown. +2. Launch the Test & Feedback extension. Any acceptance criteria for the work item are shown. - ![Launching the Test & Feedback extension](media/explore-workitems-exploratory-testing/explore-workitems-03.png) + ![Screenshot showing launching the Test - Feedback extension.](media/explore-workitems-exploratory-testing/explore-workitems-03.png) - If you have not already started a session, start one now. - The work item is automatically associated with the current or new session. + If you didn't start a session yet, start one now. The work item automatically associates with the current or new session. -1. All bugs, tasks, and test cases you create will automatically be - linked to the current work item. +3. All bugs, tasks, and test cases you create automatically link to the current work item. - ![Viewing the current work item](media/explore-workitems-exploratory-testing/explore-workitems-04.png) + ![Screenshot showing view of the current work item.](media/explore-workitems-exploratory-testing/explore-workitems-04.png) -## Explore work items from the Test & Feedback extension -1. Open the **Explore work item** page in the extension and search for - the work item you want to explore. - - ![Searching for a workitem](media/explore-workitems-exploratory-testing/explore-workitems-05.png) +## Explore work items from the Test & Feedback extension + +1. Open the **Explore work item** page in the extension and search for the work item you want to explore. + + ![Screenshot showing search for a work item.](media/explore-workitems-exploratory-testing/explore-workitems-05.png) - You can search using the work item identifier or keywords in the work item title. + You can search using the work item identifier or keywords in the work item title. The work item types available for search in the extension are: Epic, Feature, Test Case, and Requirement. For more information, see [About work items and work item types](../boards/work-items/about-work-items.md). + + > [!IMPORTANT] + > The Test & Feedback extension only searches and returns results for work items created in the past 180 days if you search using work item title. If you search using work item ID, there is no 180 day limitation. -1. Select the work item in the search results and choose **Explore selected work item**. +2. In the search results, select the work item and choose **Explore selected work item**. - ![Selecting the work item in the search results](media/explore-workitems-exploratory-testing/explore-workitems-06.png) + ![Screenshot showing selecting the work item in the search results.](media/explore-workitems-exploratory-testing/explore-workitems-06.png) -1. The work item is now associated with the in-progress session. - If there are acceptance criteria, these are shown. + The work item is now associated with the in-progress session, and the acceptance criteria are shown. - ![Viewing any acceptance criteria](media/explore-workitems-exploratory-testing/explore-workitems-07.png) + ![Screenshot showing view of acceptance criteria.](media/explore-workitems-exploratory-testing/explore-workitems-07.png) -1. All bugs, tasks, and test cases you create will automatically be - linked to the current work item. + All bugs, tasks, and test cases you create automatically link to the current work item. - ![Viewing the current work item](media/explore-workitems-exploratory-testing/explore-workitems-04.png) + ![Screenshot showing view of the current work item.](media/explore-workitems-exploratory-testing/explore-workitems-04.png) + ## Explore multiple work items in the same session -To explore another work item, you must first dissociate the current work item from the in-progress session. +To explore another work item, first dissociate the current work item from the in-progress session. -1. Open the **Explore work item** page and choose **Change**. +1. Open the **Explore work item** page and select **Change**. - ![Changing the work item you are exploring](media/explore-workitems-exploratory-testing/explore-workitems-09.png) + ![Screenshot showing changing the work item you're exploring.](media/explore-workitems-exploratory-testing/explore-workitems-09.png) -2. Associate the new work item with the in-progress session as [described above](#extension). +2. Associate the new work item with the in-progress session as [previously described](#extension). -## See your exploratory session results +## View your exploratory session results -After you file bugs, create tasks, or create test cases, all these show up in the "Recent exploratory sessions" page in Azure Test Plans. +After you file bugs, create tasks, or create test cases, they appear on the "Recent exploratory sessions" page in Azure Test Plans. -* See how you can [view your sessions and get insights](insights-exploratory-testing.md). +For more information, see [View your sessions and gain insights](insights-exploratory-testing.md). -## See Also +## Related articles -* [FAQs for manual testing](reference-qa.yml#tandfext) -* [Use the Test & Feedback extension in Connected mode](connected-mode-exploratory-testing.md) +* [Find answers to FAQs for manual testing](reference-qa.yml#tandfext) +* [Use the Test & Feedback extension in Connected mode](connected-mode-exploratory-testing.md) * [Add findings to existing bugs with exploratory testing](add-to-bugs-exploratory-testing.md) -* [Get insights across your exploratory testing sessions](insights-exploratory-testing.md) -* [Use the Test & Feedback extension in Standalone mode](standalone-mode-exploratory-testing.md) -* [Exploratory testing with Microsoft Test Manager](/previous-versions/azure/devops/test/mtm/exploratory-testing-using-microsoft-test-manager) -* [Overview of manual and exploratory testing](index.yml) - - +* [Gain insights across your exploratory testing sessions](insights-exploratory-testing.md) +* [Use the Test & Feedback extension in Standalone mode](standalone-mode-exploratory-testing.md) +* [Perform exploratory testing with Microsoft Test Manager](/previous-versions/azure/devops/test/mtm/exploratory-testing-using-microsoft-test-manager) +* [Explore an overview of manual and exploratory testing](index.yml) \ No newline at end of file diff --git a/docs/test/how-long-to-keep-test-results.md b/docs/test/how-long-to-keep-test-results.md index a25dca810d8..e74848b43bc 100644 --- a/docs/test/how-long-to-keep-test-results.md +++ b/docs/test/how-long-to-keep-test-results.md @@ -1,12 +1,12 @@ --- title: Set test retention policies -description: Manage how long Azure DevOps keeps your manual test results by clearing test results that you do not need anymore or when you delete your builds +description: Manage how long Azure DevOps keeps your manual test results by clearing test results that you don't need anymore or when you delete your builds. ms.assetid: 7a9e6fbe-bdd0-4cb5-8e57-f4d8d2126218 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' ms.date: 4/04/2022 --- @@ -23,9 +23,10 @@ You can keep manual test results while you're still reviewing them, for example, up to a year. ## Prerequisites - -- To manage project-level test-related policies, you must be a member of the [**Project Administrators** group](../organizations/security/change-project-level-permissions.md). -- To manage build pipeline object-level test retention policies, you must have the **Edit build pipeline** permissions set to **Allow**. + +| Category | Requirements | +|--------------|-------------| +|**Permissions** |- To manage project-level test-related policies: Member of the [**Project Administrators** group](../organizations/security/change-project-level-permissions.md).
      - To manage build pipeline object-level test retention policies: **Edit build pipeline** permissions set to **Allow**. | @@ -37,13 +38,13 @@ Azure DevOps keeps manual test results related to builds, even after you delete those builds. That way, build policies don't delete your test results before you can analyze the data. -1. Sign into Azure DevOps. You'll need at least project administrator permissions. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). -1. Go to your project and then open the [project settings page](../project/navigation/go-to-service-page.md#open-project-settings). +2. Select **Project settings**. -1. In the **Test>Retention** page, select a limit for how long you want to keep manual test data. +3. In the **Test** > **Retention** page, select a limit for how long you want to keep manual test data. - ![Select test data retention limits](media/how-long-to-keep-test-results/team-project-test-data-retention-limits.png) + ![Screenshot showing select test data retention limits.](media/how-long-to-keep-test-results/team-project-test-data-retention-limits.png) ## Set retention policy for automated test results associated with builds @@ -52,30 +53,23 @@ only as long as you keep those builds. To keep test results after you delete you edit the build retention policy. If you use Git for version control, you can specify how long to keep automated test results based on the branch. -1. Sign into Azure DevOps. You'll need at least build level permissions to edit build pipelines. +1. Sign in to your project (```https://dev.azure.com/{Your_Organization}/{Your_Project}```). -1. Go to your project. Find and edit your build pipeline. +2. Find and edit your build pipeline. ![Build pipeline](media/how-long-to-keep-test-results/edit-build-def.png) -1. Open the **Retention** page. Modify the default policies as required, or add new policies. +3. Open the **Retention** page. Modify the default policies as required, or add new policies. ![Delete test results by branch](media/how-long-to-keep-test-results/vso-git-keep-test-data-builds.png) - If you use Git, and have more than one branch, - set the branch filter to delete test results and builds - in specific branches as required. You can keep test results in other branches, - even though you delete the builds in these branches. + If you use Git, and have more than one branch, set the branch filter to delete test results and builds in specific branches as required. You can keep test results in other branches, even though you delete the builds in these branches. ## Set retention policy for automated test results not associated with builds -To clean up automated test results that are left over from deleted -builds or test results that aren't related to builds, -for example, results published from external test systems, -set the retention limits at the project level as described in [Set retention period for test results](#manual-test-results-limits) earlier in this article. + +Clean up automated test results left over from deleted builds or test results that aren't related to builds. For example, results published from external test systems. Set the retention limits at the project level as described in [Set retention period for test results](#manual-test-results-limits) earlier in this article. ## Related articles - [Delete test artifacts](../boards/backlogs/delete-test-artifacts.md) - [FAQs for manual testing](reference-qa.yml#manageresults) - - diff --git a/docs/test/includes/common-tcm-parameters.md b/docs/test/includes/common-tcm-parameters.md index 4349d255c06..27c6b843d96 100644 --- a/docs/test/includes/common-tcm-parameters.md +++ b/docs/test/includes/common-tcm-parameters.md @@ -1,9 +1,9 @@ --- ms.service: azure-devops-test-plans -ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr ms.topic: include ms.date: 11/10/2021 --- -For descriptions of `/collection`, `/teamproject` and `/login` parameters, see [Work with the TCM command-line tool](#work-tcm-cli). \ No newline at end of file +For descriptions of `/collection`, `/teamproject` and `/login` parameters, see [Work with the TCM command-line tool](#work-tcm-cli). diff --git a/docs/test/includes/important-note-request-feedback-unavailable.md b/docs/test/includes/important-note-request-feedback-unavailable.md new file mode 100644 index 00000000000..be9bdd57c4c --- /dev/null +++ b/docs/test/includes/important-note-request-feedback-unavailable.md @@ -0,0 +1,6 @@ +--- +ms.topic: include +--- + +> [!IMPORTANT] +> The **Request feedback** shortcut menu is no longer available in the Azure DevOps Service. However, you can request feedback through alternative methods such as through email, chat, and the [Test & Feedback extension](../voluntary-stakeholder-feedback.md). diff --git a/docs/test/includes/limitations-import.md b/docs/test/includes/limitations-import.md new file mode 100644 index 00000000000..3154b0231ac --- /dev/null +++ b/docs/test/includes/limitations-import.md @@ -0,0 +1,10 @@ +--- +ms.topic: include +--- +## Limitations + +- The test case state column must be in **Design** state. +- The test case title **length** must not exceed **128** characters. +- There's a **limit of 20 MB** on JSON objects created during import and export. If the import fails, try the operation with small subset of the test cases. +- The user performing the import must have permissions on the area and iteration paths for test plan and test suite they're planning to import or export. +- **Copy** and **Import** operations fail if the related link count exceeds 1000 for the test case. diff --git a/docs/test/includes/loadtest-deprecated-include.md b/docs/test/includes/loadtest-deprecated-include.md index efd82cd0918..67459a02d5a 100644 --- a/docs/test/includes/loadtest-deprecated-include.md +++ b/docs/test/includes/loadtest-deprecated-include.md @@ -3,4 +3,4 @@ ms.topic: include --- > [!NOTE] -> While Azure DevOps cloud-based load testing service is deprecated, **Azure Load Testing** is available. Azure Load Testing is a fully managed load testing service that enables you to use existing Apache JMeter scripts to generate high-scale load. To learn more, see [What is Azure Load Testing?](/azure/load-testing/overview-what-is-azure-load-testing). To learn more about the deprecation of Azure DevOps load testing and other, alternative services see [Changes to load test functionality in Visual Studio and cloud load testing in Azure DevOps](/azure/load-testing/overview-what-is-azure-load-testing). +> The Azure DevOps cloud-based load testing service is deprecated, but **Azure Load Testing** remains available. This fully managed load testing service allows you to generate high-scale load using your existing Apache JMeter scripts. For more information, see [What is Azure Load Testing?](/azure/load-testing/overview-what-is-azure-load-testing) and [Changes to load test functionality in Visual Studio and cloud load testing in Azure DevOps](/azure/load-testing/overview-what-is-azure-load-testing). diff --git a/docs/test/includes/note-new-ui.md b/docs/test/includes/note-new-ui.md deleted file mode 100644 index 38e4b19d3fa..00000000000 --- a/docs/test/includes/note-new-ui.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -ms.service: azure-devops-test-plans -ms.author: chcomley -author: chcomley -ms.topic: include -ms.date: 07/13/2021 ---- - -::: moniker range=">= azure-devops-2020" - -> [!NOTE] -> If you're new to using Azure Test Plans, review [Navigate Test Plans](../navigate-test-plans.md) to understand how to use the user interface to access select functions. - -::: moniker-end \ No newline at end of file diff --git a/docs/test/includes/prerequisites-define.md b/docs/test/includes/prerequisites-define.md index 3e87a7d4bf8..88fdf671f40 100644 --- a/docs/test/includes/prerequisites-define.md +++ b/docs/test/includes/prerequisites-define.md @@ -1,28 +1,15 @@ --- ms.service: azure-devops-test-plans -ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr ms.topic: include -ms.date: 07/13/2021 +ms.date: 01/13/2025 --- -## Prerequisites - -- You must connect to a project. If you don't have a project yet, [create one](../../user-guide/sign-up-invite-teammates.md). -- You must be added to a project. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -- To view test-related work items, you must have **Basic** access or higher and permissions to view work items under the corresponding Area Path. -- To [add test plans and test suites](../create-a-test-plan.md), [manual test cases](../create-test-cases.md), [delete test artifacts](../../boards/backlogs/delete-test-artifacts.md), and [define test configurations](../test-different-configurations.md) you must have [Basic + Test Plans](https://marketplace.visualstudio.com/items?itemName=ms.vss-testmanager-web) access level or have one of the following **Visual Studio subscriptions**: - - - [Enterprise](https://visualstudio.microsoft.com/vs/enterprise/) - - [Test Professional](https://visualstudio.microsoft.com/vs/test-professional/) - - [MSDN Platforms](https://visualstudio.microsoft.com/msdn-platforms/) - -- To add or edit test-related artifacts, you must have the following permissions: - - To add or modify test plans, test suites, test cases, or other test-based work item types, you must have **Edit work items in this node** permission set to **Allow** under the corresponding **Area Path**. - - To modify test plan properties such as build and test settings, you must have **Manage test plans** permission set to **Allow** under the corresponding **Area Path**. - - To create and delete test suites, add, and remove test cases from test suites, change test configurations associated with test suites, and modify a test suite hierarchy (move a test suite), you must have **Manage test suites** permission set to **Allow** under the corresponding **Area Path**. - -To learn more, see [Manual test access and permissions](../manual-test-permissions.md). - +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - At least **Basic** access, with permissions to view work items under the corresponding Area Path.
      - To add test plans and test suites, delete test artifacts, and define test configurations: [Basic + Test Plans](https://marketplace.visualstudio.com/items?itemName=ms.vss-testmanager-web) access.
      Or, one of the following **Visual Studio subscriptions**:
      - [Enterprise](https://visualstudio.microsoft.com/vs/enterprise/)
      - [Test Professional](https://visualstudio.microsoft.com/vs/test-professional/)
      - [MSDN Platforms](https://visualstudio.microsoft.com/msdn-platforms/) | +| **Permissions** | - To add or modify test plans, test suites, test cases, or other test-based work item types: **Edit work items in this node** permission set to **Allow** under the corresponding **Area Path**.
      - To modify test plan properties such as build and test settings: **Manage test plans** permission set to **Allow** under the corresponding **Area Path**.
      - to create and delete test suites, add and remove test cases from test suites, change test configurations associated with test suites, and modify a test suite hierarchy (move a test suite): **Manage test suites** permission set to **Allow** under the corresponding **Area Path**. | +For more information, see [Manual test access and permissions](../manual-test-permissions.md). diff --git a/docs/test/includes/prerequisites-run.md b/docs/test/includes/prerequisites-run.md index 8f0d183c3a3..8abf4f6dbdd 100644 --- a/docs/test/includes/prerequisites-run.md +++ b/docs/test/includes/prerequisites-run.md @@ -1,18 +1,13 @@ --- ms.service: azure-devops-test-plans -ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr ms.topic: include -ms.date: 07/13/2021 +ms.date: 01/13/2025 --- -## Prerequisites - -- You must connect to a project. If you don't have a project yet, [create one](../../user-guide/sign-up-invite-teammates.md). -- You must be added to a project. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -- To view or run manual or automated tests, you must have **Basic** access or higher. - -To learn more, see [Manual test access and permissions](../manual-test-permissions.md). - - +| Category | Requirements | +|--------------|-------------| +|**Project access**| [Project member](../../organizations/security/add-users-team-project.md). | +|**Access levels**| At least **Basic** access. For more information, see [Manual test access and permissions](../manual-test-permissions.md). | diff --git a/docs/test/includes/prerequisites-stakeholder.md b/docs/test/includes/prerequisites-stakeholder.md index 6ace40da5fb..1c5ef6f9cbc 100644 --- a/docs/test/includes/prerequisites-stakeholder.md +++ b/docs/test/includes/prerequisites-stakeholder.md @@ -1,20 +1,14 @@ --- ms.service: azure-devops-test-plans -ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr ms.topic: include -ms.date: 07/13/2021 +ms.date: 01/13/2025 --- -## Prerequisites - -- You must connect to a project. If you don't have a project yet, [create one](../../user-guide/sign-up-invite-teammates.md). -- You must be added to a project. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -- To request or provide feedback, you must have **Stakeholder** access or higher. -- To add or modify bugs or other work item types, you must have the **Edit work items in this node** permission set to **Allow** under the corresponding **Area Path**. -- To add new tags, you must have the **Create tag definition** permission set to **Allow**. - -To learn more, see [Set permissions and access for testing](../../organizations/security/set-permissions-access-test.md). - - +| Category | Requirement | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Access levels** | To request or provide feedback: At least **Stakeholder** access. | +| **Permissions** | - To add or modify bugs or other work item types: **Edit work items in this node** permission set to **Allow** under the corresponding **Area Path**.
      - To add new tags: **Create tag definition** permission set to **Allow**.
      For more information, see [Set permissions and access for testing](../../organizations/security/set-permissions-access-test.md). | diff --git a/docs/test/includes/prerequisites-tcm.md b/docs/test/includes/prerequisites-tcm.md index d4f4316dfd4..416dbf0062c 100644 --- a/docs/test/includes/prerequisites-tcm.md +++ b/docs/test/includes/prerequisites-tcm.md @@ -1,31 +1,23 @@ --- ms.service: azure-devops-test-plans ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr ms.topic: include -ms.date: 11/09/2021 +ms.date: 01/13/2025 --- - + -## Work with the TCM command-line tool +### Prerequisites for TCM command-line tool -To exercise the TCM command-line tool, you must have the following in place: - -- Installed Visual Studio 2017 Professional or earlier version. You access TCM from the command prompt and the following directories: - `%programfiles(x86)%\Microsoft Visual Studio\2017\Professional\Common7\IDE` - `%programfiles(x86)%\Microsoft Visual Studio\2017\Enterprise\Common7\IDE` - `%programfiles(x86)%\Microsoft Visual Studio 14.0\Common7\IDE` - -- To run a TCM command, specify the `/collection` and `/teamproject` parameters, and `/login` as needed. - - | Parameter | Description | - |----------|------------| - |**/collection**`:CollectionURL`|Required. Specifies the URI of the team project collection.The format for the URI is as follows:
      - For Azure DevOps Services: `http://dev.azure.com/OrganizationName`
      - For Azure DevOps Server: `http://ServerName:Port/VirtualDirectoryName/CollectionName`. If no virtual directory is used, then the format for the URI is as follows:`http://ServerName:Port/CollectionName`| - |**/teamproject**:`project`|Required. The name of the project that contains the test objects you want to clone or import automated tests into.| - |**/login**:`username,[password]`|Optional. Specifies the name and password of a valid Azure DevOps user and who has permissions to run the command. Use this option if your Windows credentials don't have the appropriate permissions, or you're using basic authentication, or you're not connected to a domain.| - -- You must be a valid member of the project(s) you want to access and have the required permissions based on the commands you run. To learn more, see [Manual test access and permissions](../manual-test-permissions.md). - -- To clone or import test objects, you must have been granted the same access levels required to add test plans and test suites as described in [Prerequisites](#prerequisites). +| Category | Requirements | +|--------------|-------------| +|**Tools** |Visual Studio 2017 Professional or earlier version. Access TCM from the command prompt and the following directories:
      - `%programfiles(x86)%\Microsoft Visual Studio\2017\Professional\Common7\IDE`
      - `%programfiles(x86)%\Microsoft Visual Studio\2017\Enterprise\Common7\IDE`
      - `%programfiles(x86)%\Microsoft Visual Studio 14.0\Common7\IDE`
      - To run a TCM command, specify the `/collection` and `/teamproject` parameters, and `/login` as needed. Also see the following table of required and optional parameters.| +|**Access levels**|- Valid project membership to one or more projects that you want to access and the required permissions based on the commands you run. For more information, see [Manual test access and permissions](../manual-test-permissions.md).
      - Same access levels for adding test plans and test suites to clone or import test objects.| +| Parameter | Description | +|----------|------------| +|**/collection**`:CollectionURL`|Required. Specifies the URI of the team project collection. The format for the URI is as follows:
      - For Azure DevOps Services: `http://dev.azure.com/OrganizationName`
      - For Azure DevOps Server: `http://ServerName:Port/VirtualDirectoryName/CollectionName`. If no virtual directory is used, then the format for the URI is as follows:`http://ServerName:Port/CollectionName`.| +|**/teamproject**:`project`|Required. The name of the project that contains the test objects you want to clone or import automated tests into.| +|**/login**:`username,[password]`|Optional. Specifies the name and password of a valid Azure DevOps user and who has permissions to run the command. Use this option if your Windows credentials don't have the appropriate permissions, or you're using basic authentication, or you're not connected to a domain.| diff --git a/docs/test/includes/prerequisites.md b/docs/test/includes/prerequisites.md index adacd4ca666..78f401c2157 100644 --- a/docs/test/includes/prerequisites.md +++ b/docs/test/includes/prerequisites.md @@ -1,33 +1,18 @@ --- ms.service: azure-devops-test-plans -ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr ms.topic: include -ms.date: 07/13/2021 +ms.date: 01/13/2025 --- -## Prerequisites +| Category | Requirement | +|--------------|-------------| +| **Project access** | [Project member](../../organizations/security/add-users-team-project.md). | +| **Access levels** | - To view test-related work items or run test cases: At least **Basic** access. Users with **Stakeholder** access have no access to Test Plans.
      - To exercise the full range of test-related features: [Basic + Test Plans](../../organizations/billing/buy-access-tfs-test-hub.md) access level or one of the following subscriptions:
      - [Enterprise](https://visualstudio.microsoft.com/vs/enterprise/)
      - [Test Professional](https://visualstudio.microsoft.com/vs/test-professional/)
      - [MSDN Platforms](https://visualstudio.microsoft.com/msdn-platforms/) | +| **Permissions** | - To add or modify test plans, test suites, test cases, or other test-based work item types: **Edit work items in this node** permission set to **Allow** under the corresponding **Area Path**.
      - To modify test plan properties such as build and test settings: **Manage test plans** permission set to **Allow** under the corresponding **Area Path**.
      - To create and delete test suites, add and remove test cases from test suites, or change test configurations associated with test suites: **Manage test suites** permission set to **Allow** under the corresponding **Area Path**.
      - Project-level permissions that you might need include:
      - To view, create, or delete test runs: **View test runs**, **Create test runs**, and **Delete test runs** permission set to **Allow**.
      - To manage test configurations or test environments: **Manage test configurations** and **Manage test environments**.
      - To add new tags to test-based work items: **Create tag definition** permission set to **Allow**.
      - To move test-based work items out of a project: **Move work items out of this project** permission set to **Allow**.
      - To delete or restore test-based work items: **Delete and restore work items** permission set to **Allow**.
      - To permanently delete test-based work items: **Permanently delete work items** permission set to **Allow**. | -- You must connect to a project. If you don't have a project yet, [create one](../../user-guide/sign-up-invite-teammates.md). -- You must be added to a project. To get added, [Add users to a project or team](../../organizations/security/add-users-team-project.md). -- To view test-related work items or run test cases, you must have **Basic** access or higher. Users with **Stakeholder** access have no access to Test Plans. -- To exercise the full range of test-related features, you must have been granted [Basic + Test Plans](../../organizations/billing/buy-access-tfs-test-hub.md) access level or have one of the following subscriptions: - - [Enterprise](https://visualstudio.microsoft.com/vs/enterprise/) - - [Test Professional](https://visualstudio.microsoft.com/vs/test-professional/) - - [MSDN Platforms](https://visualstudio.microsoft.com/msdn-platforms/) -- To add or edit test-related artifacts, you must have the following permissions: - - To add or modify test plans, test suites, test cases, or other test-based work item types, you must have **Edit work items in this node** permission set to **Allow** under the corresponding **Area Path**. - - To modify test plan properties such as build and test settings, you must have **Manage test plans** permission set to **Allow** under the corresponding **Area Path**. - - To create and delete test suites; add, and remove test cases from test suites; change test configurations associated with test suites—you must have **Manage test suites** permission set to **Allow** under the corresponding **Area Path**. -- Project-level permissions that you may need include: - - To view, create, or delete test runs, you must be granted the corresponding permissions: **View test runs**, **Create test runs**, and **Delete test runs**. - - To manage test configurations or test environments, you must be granted the corresponding permissions: **Manage test configurations** and **Manage test environments**. - - To add new tags to test-based work items, you must have the **Create tag definition** permission set to **Allow**. - - To move test-based work items out of a project, you must have the **Move work items out of this project** permission set to **Allow**. - - To delete or restore test-based work items, you must have the **Delete and restore work items** permission set to **Allow**. - - To permanently delete test-based work items, you must have the **Permanently delete work items** permission set to **Allow**. - -To learn more, see [Manual test access and permissions](../manual-test-permissions.md). +For more information, see [Manual test access and permissions](../manual-test-permissions.md). diff --git a/docs/test/index.yml b/docs/test/index.yml index 6d38d1e215f..0978f0b7c49 100644 --- a/docs/test/index.yml +++ b/docs/test/index.yml @@ -11,9 +11,9 @@ metadata: ms.custom: UpdateFrequency3 ms.assetid: 00f4ed452-fbb8-45f9-8f0a-343702aac5b8 ms.topic: landing-page - author: chcomley - ms.author: chcomley - ms.date: 09/30/2019 + ms.author: jeom + author: raviLiftr + ms.date: 06/26/2024 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -29,6 +29,8 @@ landingContent: url: ../test/overview.md - text: Navigate Test Plans url: ../test/navigate-test-plans.md + - text: Store custom data in test plan and/or test result + url: ../test/custom-fields.md - title: Run manual tests linkLists: - linkListType: quickstart diff --git a/docs/test/insights-exploratory-testing.md b/docs/test/insights-exploratory-testing.md index eb93c71aeb2..dbdbbe6555d 100644 --- a/docs/test/insights-exploratory-testing.md +++ b/docs/test/insights-exploratory-testing.md @@ -1,12 +1,12 @@ --- title: Get insights across exploratory test sessions -description: Manual and exploratory testing - get insights with exploratory testing across your test sessions by using the Microsoft Test & Feedback extension +description: Manual and exploratory testing - get insights with exploratory testing across your test sessions by using the Microsoft Test & Feedback extension. ms.assetid: 4A7DE54F-FE15-49AA-B88B-B3B848EC68F9 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra ms.date: 12/07/2018 monikerRange: '<= azure-devops' --- @@ -18,34 +18,35 @@ monikerRange: '<= azure-devops' View completed exploratory testing sessions and derive meaningful insights at team or individual level, and for a specific period. -[!INCLUDE [prerequisites-define](includes/prerequisites-run.md)] +## Prerequisites -1. Open the **Recent exploratory sessions** page. You can do this: +[!INCLUDE [prerequisites-run](includes/prerequisites-run.md)] - - From the Test & Feedback extension by choosing the "view" icon on - the **Session timeline** page. +## Open recent exploratory sessions + +1. Open the **Recent exploratory sessions** page, with either of the following actions: + + - From the Test - Feedback extension, select the "view" icon on the **Session timeline** page. - ![Opening the insights page from the extension](media/insights-exploratory-testing/insights-exploratory-testing-01.png) + ![Screenshot showing opening the insights page from the extension.](media/insights-exploratory-testing/insights-exploratory-testing-01.png) - - From the **Test Plans** web portal. by opening the **Runs** page and choosing **Recent exploratory sessions**. + - From **Test Plans**, select **Runs** > **Recent exploratory sessions**. - ![Opening the insights page](media/insights-exploratory-testing/insights-exploratory-testing-02.png) + ![Screenshot showing opening the insights page.](media/insights-exploratory-testing/insights-exploratory-testing-02.png) -2. Explore the **Recent exploratory sessions** page. It contains three main sections: +2. Explore the **Recent exploratory sessions** page. It contains the following three main sections: - **Summary view** - shows a graphical breakdown of the work items explored, work items - created, session owners, and the total time for these sessions. + - **Summary view** - shows a graphical breakdown of the work items explored, work items created, session owners, and the total time for these sessions. - ![Summary view](media/insights-exploratory-testing/insights-exploratory-testing-03.png) + ![Screenshot of Summary view.](media/insights-exploratory-testing/insights-exploratory-testing-03.png) - **Pivot view** - shows a collapsible nested and sortable list of items grouped in different ways. + - **Pivot view** - shows a collapsible nested and sortable list of items grouped in different ways. - ![Pivot view](media/insights-exploratory-testing/insights-exploratory-testing-03a.png) + ![Screenshot of Pivot view.](media/insights-exploratory-testing/insights-exploratory-testing-03a.png) - **Details view** - shows the work item selected in the Pivot - view or a summary of information about a selection of items. + - **Details view** - shows the work item selected in the Pivot view or a summary of information about a selection of items. - ![Details view](media/insights-exploratory-testing/insights-exploratory-testing-03b.png) + ![Screenshot of Details view.](media/insights-exploratory-testing/insights-exploratory-testing-03b.png) ## Get insights from your exploratory testing sessions: @@ -60,77 +61,58 @@ app from the information collected during your exploratory testing sessions. - Use the **View** filter to scope the summary view to all sessions or just your own sessions. - Use the **Period** filter to scope the summary view to sessions in the period from the last 7 to the last 90 days. - ![Set the scope for the data](media/insights-exploratory-testing/insights-exploratory-testing-04.png) + ![Screenshot showing set scope for the data.](media/insights-exploratory-testing/insights-exploratory-testing-04.png) -1. **Pivot the data on the type of work item**. - Pivot view lets you to focus on all the work items you created +2. **Pivot the data on the type of work item**. + Pivot view lets you focus on all the work items you created in your exploratory testing sessions, or just on bugs, tasks, or test cases; and group the results in different ways. - - Use the **Pivot** filter to group the work items as a - nested list based on those that have been explored, - those that have not been explored (requires a [query](#not-explored)), - by the session in which they were created, or by session owner. - - Use the **Show** filter to show all items; or just bugs, tasks, or test cases.

      + - Use the **Pivot** filter to group the work items as a nested list based on explored and unexplored (requires a [query](#not-explored)), by the session in which they were created, or by session owner. + - Use the **Show** filter to show all items, or only bugs, tasks, or test cases. - ![Pivot the data on the type of work item](media/insights-exploratory-testing/insights-exploratory-testing-06.png) + ![Screenshot showing pivoting the data on the type of work item.](media/insights-exploratory-testing/insights-exploratory-testing-06.png) -1. **Get deep insights from Details view**. - Details view gives insights into the items selected - in Pivot view. Depending on the type of item you select, - you see the work item as an editable form, or a series of charts. +3. **Get deep insights from Details view**. + The Details view gives insights into the items selected in Pivot view. Depending on the type of item you select, you see the work item as an editable form, or a series of charts. - - Select a row in Pivot view to see a summary of - all the related information in Details view. For example, if you have pivoted the - list based on sessions, select a session to see a - summary of all the information from the work items in just that session. - - Select a child row in Pivot view to display the work item - form for that individual item. For example, if you have pivoted - the list based on explored work items, expand a work - item and select a child bug, task, or test case to see - the work item form for just that item.

      - - ![Get deep insights from Details view](media/insights-exploratory-testing/insights-exploratory-testing-07.png) + - Select a row in Pivot view to see a summary of all the related information in Details view. For example, if you pivoted the list based on sessions, select a session to see a summary of all the information from the work items in just that session. + - Select a child row in Pivot view to display the work item form for that individual item. For example, if you pivoted the list based on explored work items, expand a work item and select a child bug, task, or test case to see the work item form for just that item.

      + + ![Screenshot showing deep insights from the Details view.](media/insights-exploratory-testing/insights-exploratory-testing-07.png) + ## Discover work items not yet explored -Use a query to explore the work items that users have not yet explored. +Use a query to discover unexplored work items. -1. Create a shared query in Azure DevOps that selects work items - that can be explored using the Test & Feedback extension, such as - work items in the epic category, feature category, requirement category, - requirement-based suites, or test cases. +1. Create a shared query that selects work items using the Test - Feedback extension, such as work items in the epic category, feature category, requirement category, requirement-based suites, or test cases. - >You must use a **shared** query. If this query returns a mix of supported - and unsupported work items, only those in supported categories will be displayed. + You must use a **shared** query. If this query returns a mix of supported and unsupported work items, only supported categories display. -1. Use the **View** and **Period** filters to scope the view to - the type of session (all sessions or just your own sessions) - and the time span (from the last 7 to the last 90 days). - Then open the **Query** list and choose **Select query**. +2. Use the **View** and **Period** filters to scope the view to the type of session (all sessions or just your own sessions) and the time span (from the last 7 to the last 90 days). + Open the **Query** list and select **Select query**. - ![Set the View and Period filters](media/insights-exploratory-testing/insights-exploratory-testing-08.png) + ![Screenshot of the View and Period filters.](media/insights-exploratory-testing/insights-exploratory-testing-08.png) -1. In the **Query selector** dialog, choose the shared query you created earlier. +3. In the **Query selector** dialog, select the shared query you created earlier. - ![Selecting the shared Query](media/insights-exploratory-testing/insights-exploratory-testing-10.png) + ![Screenshot showing selecting the shared Query.](media/insights-exploratory-testing/insights-exploratory-testing-10.png) -1. View all the work items returned by the query in Summary view. You see - a breakdown of explored and unexplored work items, work items filed, sessions, - and total session duration. +4. View all the work items returned by the query in the **Summary** view. You see a breakdown of explored and unexplored work items, work items filed, sessions, and total session duration. - ![Viewing the results in Summary view](media/insights-exploratory-testing/insights-exploratory-testing-11.png) + ![Screenshot showing results in the Summary view.](media/insights-exploratory-testing/insights-exploratory-testing-11.png) -1. Open the **Pivot** list and choose **Unexplored Work Item**. +5. Open the **Pivot** list and choose **Unexplored Work Item**. - ![Choosing the Unexplored Work Item option](media/insights-exploratory-testing/insights-exploratory-testing-12.png) + ![Screenshot showing the Unexplored Work Item option selected.](media/insights-exploratory-testing/insights-exploratory-testing-12.png) - The view now shows only the unexplored work items. + The view shows only the unexplored work items. - ![Viewing the unexplored work items](media/insights-exploratory-testing/insights-exploratory-testing-13.png) + ![Screenshot showing view of the unexplored work items.](media/insights-exploratory-testing/insights-exploratory-testing-13.png) -## See Also +## Related articles * [Use the Test & Feedback extension in Connected mode](connected-mode-exploratory-testing.md) * [Add findings to existing bugs with exploratory testing](add-to-bugs-exploratory-testing.md) @@ -138,5 +120,3 @@ Use a query to explore the work items that users have not yet explored. * [Use the Test & Feedback extension in Standalone mode](standalone-mode-exploratory-testing.md) * [Exploratory testing with Microsoft Test Manager](/previous-versions/azure/devops/test/mtm/exploratory-testing-using-microsoft-test-manager) * [Overview of manual and exploratory testing](index.yml) - - diff --git a/docs/test/manage-test-failure-type.md b/docs/test/manage-test-failure-type.md new file mode 100644 index 00000000000..645b2f9317c --- /dev/null +++ b/docs/test/manage-test-failure-type.md @@ -0,0 +1,59 @@ +--- +title: Manage test failure type +description: Learn about managing failure type in Azure Test Plans. You can add, remove or edit the default test failure types. +ms.assetid: +ms.service: azure-devops-test-plans +ms.custom: UpdateFrequency3 +ms.topic: conceptual +ms.author: jeom +author: raviLiftr +monikerRange: 'azure-devops' +ms.date: 08/25/2023 +--- + +# Manage test failure type + +[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] + +Azure Test Plans provides the functionality to customize the failure types of any test case beyond the default values. A **failure type** is an artifact that helps to mark test case failures into defined categories such as **regression issue** or **known issue**. While this categorization of failure types is helpful, users might want to add their own custom failure type beyond the default values, which creates a more customized experience for specific user needs in the Azure DevOps project. This article walks through the steps of defining a custom failure type using the new REST API provided. + +## Prerequisites + +[!INCLUDE [prerequisites](includes/prerequisites.md)] + +## How to view the default failure types + +Failure type categorization is part of the post-test run experience in Azure Test Plans. This feature is only applicable to test cases marked as **Failed**. To mark a test failure using the default failure type, follow the below steps: + +1. Navigate to Azure Test Plans from your Azure DevOps project. Open a Test suite containing test cases or create a new test case inside a suite. + + :::image type="content" source="media/manage-test-failure-type/azure-test-plan-navigation.png" alt-text="Screenshot of navigating to the Azure Test plans from the navigation menu."::: + +2. Navigate to Execute tab of the given test suite. + + :::image type="content" source="media/manage-test-failure-type/execute-tab-with-active-test-cases.png" alt-text="Screenshot of execute tab view with active test cases."::: + +3. Mark a test case as **Failed**, which creates a new test run for against the test case. + + :::image type="content" source="media/manage-test-failure-type/execute-tab-in-test-suite.png" alt-text="Screenshot of execute tab view inside a test suite."::: + +4. Select **Runs** from the Test Plans menu. Select the respective test run from the list shown. + + :::image type="content" source="media/manage-test-failure-type/list-of-all-test-runs.png" alt-text="Screenshot of list of all test runs."::: + +5. **Run Summary** tab is shown by default. Select on **Test results** tab. + + :::image type="content" source="media/manage-test-failure-type/run-summary-tab-test-run.png" alt-text="Screenshot of run summary tab test run."::: + +6. Select on **Update Analysis** and a dialog box appears. Users can choose the failure type for the test case from the dropdown menu. Refer to the screenshot for the failure type values shown by default. + + :::image type="content" source="media/manage-test-failure-type/view-default-failure-types.png" alt-text="Screenshot of view default failure types."::: + +## Add custom values for Failure Type + +A new set of REST APIs is provided for seamless management of failure types in Azure Test Plans. Users can add new failure types, delete existing ones and view the list of failure types for a given project. +Follow the instructions provided in the following links to explore the various APIs. + +* [Create a new test failure type](/rest/api/azure/devops/testresults/testfailuretype/create) +* [Delete a test failure type with specified failureTypeId](/rest/api/azure/devops/testresults/testfailuretype/delete) +* [Get the list of test failure types](/rest/api/azure/devops/testresults/testfailuretype/list) diff --git a/docs/test/manual-test-permissions.md b/docs/test/manual-test-permissions.md index 60f21f9ae79..33b74bb41cf 100644 --- a/docs/test/manual-test-permissions.md +++ b/docs/test/manual-test-permissions.md @@ -1,12 +1,12 @@ --- title: Permissions, licensing, and access for manual testing -description: Default permissions and access levels in Azure DevOps and TFS for manual and exploratory testing topics and problems +description: Default permissions and access levels in Azure DevOps for manual and exploratory testing and problems. ms.assetid: 91146CFD-A4CE-4CC5-973D-1633419CAFDE ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: reference -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' ms.date: 09/15/2021 --- @@ -15,27 +15,31 @@ ms.date: 09/15/2021 [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] +Access levels and permissions control access to Azure Test Plans features. -Access to Azure Test Plans features are controlled by access level and permissions. To access the Test Plans web portal, you must have a **Basic** access level or greater. To define and manage test plans, test suites, and test cases, you need **Basic + Test Plans**, which is available from Azure DevOps. - -> [!NOTE] -> Users granted **Stakeholder** access have no access to features or functions supported through the Test Plans or Test web portal. However, they are able to provide feedback through the **Test & Feedback** extension. To learn more, see [Stakeholder access quick reference](../organizations/security/stakeholder-access.md). +## Prerequisites +| Category | Requirement | +|--------------|-------------| +| **Project access** | [Project member](../organizations/security/add-users-team-project.md). | +| **Access levels** |- To access the Test Plans web portal: At least **Basic** access.
      - To define and manage test plans, test suites, and test cases: **Basic + Test Plans** access.| + +> [!NOTE] +> Users granted **Stakeholder** access have no access to features or functions supported through the Test Plans or Test web portal. However, they can provide feedback through the **Test & Feedback** extension. For more information, see [Stakeholder access quick reference](../organizations/security/stakeholder-access.md). ## Access and licensing -To exercise the full range of test-related features, you must have been granted [Basic + Test Plans](../organizations/billing/buy-access-tfs-test-hub.md) access level or have one of the following subscriptions: +To exercise the full range of test-related features, have [Basic + Test Plans](../organizations/billing/buy-access-tfs-test-hub.md) access level or have one of the following subscriptions: - [Visual Studio Enterprise](https://visualstudio.microsoft.com/vs/enterprise/) - [Visual Studio Test Professional](https://visualstudio.microsoft.com/vs/test-professional/) - [MSDN Platform](https://visualstudio.microsoft.com/msdn-platforms/) -Users who have one of the above subscriptions can exercise all Test Plans features for no additional charge. For more information, see [Compare Visual Studio subscriptions](https://www.visualstudio.com/vs/pricing). +Users who have one of the above subscriptions can exercise all Test Plans features for no extra charge. For more information, see [Compare Visual Studio subscriptions](https://www.visualstudio.com/vs/pricing). -Non-subscribers must purchase **Basic + Test Plans** to use Test Plans. This can be for any specified number of users. +Nonsubscribers must purchase **Basic + Test Plans** to use Test Plans, which can be for any specified number of users. > [!IMPORTANT] -> - Manual testers can execute tests with **Basic** access. -> -Licenses for this extension also give users rights to use [Microsoft Test Manager](/previous-versions/azure/devops/test/mtm/guidance-mtm-usage) (a deprecated on-premises client). +> Manual testers can execute tests with **Basic** access. Licenses for this extension also give users rights to use [Microsoft Test Manager](/previous-versions/azure/devops/test/mtm/guidance-mtm-usage) (a deprecated on-premises client). The following table summarizes the license requirements required to exercise select tasks. @@ -50,11 +54,11 @@ The following table summarizes the license requirements required to exercise sel | Prepare for execution such as assigning configurations or testers | Basic + Test Plans | | Prepare User Acceptance Testing | Basic + Test Plans | - + ## Permissions -In addition to having the necessary access level, you also need the necessary permissions to exercise select tasks. Because manual testing is managed through [test-specific work item types](test-objects-overview.md), they are subject to some of the same permissions that manage work items. +In addition to having the necessary access level, you also need the necessary permissions to exercise select tasks. Because manual testing is managed through [test-specific work item types](test-objects-overview.md), they're subject to some of the same permissions that manage work items. The following table provides the default permissions assigned to the built-in security groups: **Readers**, **Contributors**, and **Project Administrators**. Permissions are assigned for Area Paths and at the project-level. To learn how, see [Set permissions and access for testing](../organizations/security/set-permissions-access-test.md). @@ -63,10 +67,9 @@ The following table provides the default permissions assigned to the built-in se For a simplified view of all default permissions assigned to built-in groups, see [Default permissions and access](../organizations/security/permissions-access.md). - ## Related articles - [Test objects and terms](test-objects-overview.md) - [Set permissions and access for manual testing](../organizations/security/set-permissions-access-test.md) - [Default permissions and access](../organizations/security/permissions-access.md) -- [Security groups, service accounts, and permissions in Azure DevOps](../organizations/security/permissions.md) \ No newline at end of file +- [Security groups, service accounts, and permissions in Azure DevOps](../organizations/security/permissions.md) diff --git a/docs/test/media/associate-automated-test-with-test-case/associate-automated-test-to-test-case-pipelines.png b/docs/test/media/associate-automated-test-with-test-case/associate-automated-test-to-test-case-pipelines.png new file mode 100644 index 00000000000..25370178fb5 Binary files /dev/null and b/docs/test/media/associate-automated-test-with-test-case/associate-automated-test-to-test-case-pipelines.png differ diff --git a/docs/test/media/associate-automated-test-with-test-case/associate-automated-test-to-test-case.png b/docs/test/media/associate-automated-test-with-test-case/associate-automated-test-to-test-case.png new file mode 100644 index 00000000000..2ba53610cba Binary files /dev/null and b/docs/test/media/associate-automated-test-with-test-case/associate-automated-test-to-test-case.png differ diff --git a/docs/test/media/bulk-import-test-case/choose-import-test-cases.png b/docs/test/media/bulk-import-test-case/choose-import-test-cases.png new file mode 100644 index 00000000000..672e50246f9 Binary files /dev/null and b/docs/test/media/bulk-import-test-case/choose-import-test-cases.png differ diff --git a/docs/test/media/bulk-import-test-case/export-select-test-cases-test-suite.png b/docs/test/media/bulk-import-test-case/export-select-test-cases-test-suite.png new file mode 100644 index 00000000000..fe1cc985205 Binary files /dev/null and b/docs/test/media/bulk-import-test-case/export-select-test-cases-test-suite.png differ diff --git a/docs/test/media/bulk-import-test-case/export-test-cases-test-suite.png b/docs/test/media/bulk-import-test-case/export-test-cases-test-suite.png new file mode 100644 index 00000000000..e2a3d2323cf Binary files /dev/null and b/docs/test/media/bulk-import-test-case/export-test-cases-test-suite.png differ diff --git a/docs/test/media/bulk-import-test-case/import-errors.png b/docs/test/media/bulk-import-test-case/import-errors.png new file mode 100644 index 00000000000..de1b097edda Binary files /dev/null and b/docs/test/media/bulk-import-test-case/import-errors.png differ diff --git a/docs/test/media/bulk-import-test-case/import-test-cases-dialog.png b/docs/test/media/bulk-import-test-case/import-test-cases-dialog.png new file mode 100644 index 00000000000..0e53e13fdbf Binary files /dev/null and b/docs/test/media/bulk-import-test-case/import-test-cases-dialog.png differ diff --git a/docs/test/media/bulk-import-test-case/shared-steps-reference-in-csv.png b/docs/test/media/bulk-import-test-case/shared-steps-reference-in-csv.png new file mode 100644 index 00000000000..0c710513371 Binary files /dev/null and b/docs/test/media/bulk-import-test-case/shared-steps-reference-in-csv.png differ diff --git a/docs/test/media/connected-mode-exploratory-testing/connected-mode-03.png b/docs/test/media/connected-mode-exploratory-testing/connected-mode-03.png new file mode 100644 index 00000000000..0e4026f7099 Binary files /dev/null and b/docs/test/media/connected-mode-exploratory-testing/connected-mode-03.png differ diff --git a/docs/test/media/copy-clone/copy-test-cases-dialog.png b/docs/test/media/copy-clone/copy-test-cases-dialog.png index 5be8910551d..effb6ec9d75 100644 Binary files a/docs/test/media/copy-clone/copy-test-cases-dialog.png and b/docs/test/media/copy-clone/copy-test-cases-dialog.png differ diff --git a/docs/test/media/copy-clone/grid-view-icon.png b/docs/test/media/copy-clone/grid-view-icon.png new file mode 100644 index 00000000000..0af09b54c50 Binary files /dev/null and b/docs/test/media/copy-clone/grid-view-icon.png differ diff --git a/docs/test/media/create-a-test-plan/open-test-plans.png b/docs/test/media/create-a-test-plan/open-test-plans.png index 601f3fca234..670d1992cfc 100644 Binary files a/docs/test/media/create-a-test-plan/open-test-plans.png and b/docs/test/media/create-a-test-plan/open-test-plans.png differ diff --git a/docs/test/media/create-test-cases/ConvertSharedParameters.png b/docs/test/media/create-test-cases/ConvertSharedParameters.png deleted file mode 100644 index 252cadff680..00000000000 Binary files a/docs/test/media/create-test-cases/ConvertSharedParameters.png and /dev/null differ diff --git a/docs/test/media/custom-fields/add-custom-field.png b/docs/test/media/custom-fields/add-custom-field.png new file mode 100644 index 00000000000..dc435301961 Binary files /dev/null and b/docs/test/media/custom-fields/add-custom-field.png differ diff --git a/docs/test/media/custom-fields/test-management-settings.png b/docs/test/media/custom-fields/test-management-settings.png new file mode 100644 index 00000000000..cdae413792c Binary files /dev/null and b/docs/test/media/custom-fields/test-management-settings.png differ diff --git a/docs/test/media/manage-test-failure-type/azure-test-plan-navigation.png b/docs/test/media/manage-test-failure-type/azure-test-plan-navigation.png new file mode 100644 index 00000000000..b22f594a152 Binary files /dev/null and b/docs/test/media/manage-test-failure-type/azure-test-plan-navigation.png differ diff --git a/docs/test/media/manage-test-failure-type/execute-tab-in-test-suite.png b/docs/test/media/manage-test-failure-type/execute-tab-in-test-suite.png new file mode 100644 index 00000000000..2a7da35e310 Binary files /dev/null and b/docs/test/media/manage-test-failure-type/execute-tab-in-test-suite.png differ diff --git a/docs/test/media/manage-test-failure-type/execute-tab-with-active-test-cases.png b/docs/test/media/manage-test-failure-type/execute-tab-with-active-test-cases.png new file mode 100644 index 00000000000..3434f8c6b3b Binary files /dev/null and b/docs/test/media/manage-test-failure-type/execute-tab-with-active-test-cases.png differ diff --git a/docs/test/media/manage-test-failure-type/list-of-all-test-runs.png b/docs/test/media/manage-test-failure-type/list-of-all-test-runs.png new file mode 100644 index 00000000000..be3700f84a3 Binary files /dev/null and b/docs/test/media/manage-test-failure-type/list-of-all-test-runs.png differ diff --git a/docs/test/media/manage-test-failure-type/run-summary-tab-test-run.png b/docs/test/media/manage-test-failure-type/run-summary-tab-test-run.png new file mode 100644 index 00000000000..737b3d7c7e5 Binary files /dev/null and b/docs/test/media/manage-test-failure-type/run-summary-tab-test-run.png differ diff --git a/docs/test/media/manage-test-failure-type/view-default-failure-types.png b/docs/test/media/manage-test-failure-type/view-default-failure-types.png new file mode 100644 index 00000000000..5bda50b4626 Binary files /dev/null and b/docs/test/media/manage-test-failure-type/view-default-failure-types.png differ diff --git a/docs/test/media/perform-exploratory-tests/get-started-01.png b/docs/test/media/perform-exploratory-tests/get-started-01.png new file mode 100644 index 00000000000..d553865958e Binary files /dev/null and b/docs/test/media/perform-exploratory-tests/get-started-01.png differ diff --git a/docs/test/media/perform-exploratory-tests/getstarted-01.png b/docs/test/media/perform-exploratory-tests/getstarted-01.png deleted file mode 100644 index 8ae48398cd7..00000000000 Binary files a/docs/test/media/perform-exploratory-tests/getstarted-01.png and /dev/null differ diff --git a/docs/test/media/perform-exploratory-tests/getstarted-06.png b/docs/test/media/perform-exploratory-tests/getstarted-06.png index 1b84f22aa2d..62aa1d5f50c 100644 Binary files a/docs/test/media/perform-exploratory-tests/getstarted-06.png and b/docs/test/media/perform-exploratory-tests/getstarted-06.png differ diff --git a/docs/test/media/repeat-test-with-different-data/repeat-test-with-different-data-04.png b/docs/test/media/repeat-test-with-different-data/repeat-test-with-different-data-04.png index 4c3a40618f6..2296da93de9 100644 Binary files a/docs/test/media/repeat-test-with-different-data/repeat-test-with-different-data-04.png and b/docs/test/media/repeat-test-with-different-data/repeat-test-with-different-data-04.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/VSTest-configuration.png b/docs/test/media/run-automated-tests-from-test-hub/VSTest-configuration.png new file mode 100644 index 00000000000..165521e9480 Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/VSTest-configuration.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/executing-automated-tests.png b/docs/test/media/run-automated-tests-from-test-hub/executing-automated-tests.png new file mode 100644 index 00000000000..c15805a5acd Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/executing-automated-tests.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/run-summary.png b/docs/test/media/run-automated-tests-from-test-hub/run-summary.png new file mode 100644 index 00000000000..9534dced669 Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/run-summary.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/run-with-options-configuration-modal.png b/docs/test/media/run-automated-tests-from-test-hub/run-with-options-configuration-modal.png new file mode 100644 index 00000000000..09fae7dfd0c Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/run-with-options-configuration-modal.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/run-with-options.png b/docs/test/media/run-automated-tests-from-test-hub/run-with-options.png new file mode 100644 index 00000000000..6daa68fc0bf Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/run-with-options.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/test-plan-settings-modal-build-new-release-pipeline.png b/docs/test/media/run-automated-tests-from-test-hub/test-plan-settings-modal-build-new-release-pipeline.png new file mode 100644 index 00000000000..fd946db2059 Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/test-plan-settings-modal-build-new-release-pipeline.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/test-plan-settings-modal-build-selection.png b/docs/test/media/run-automated-tests-from-test-hub/test-plan-settings-modal-build-selection.png new file mode 100644 index 00000000000..8a648c2281f Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/test-plan-settings-modal-build-selection.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/test-plan-settings.png b/docs/test/media/run-automated-tests-from-test-hub/test-plan-settings.png new file mode 100644 index 00000000000..b2c7698803d Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/test-plan-settings.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/test-results-overview.png b/docs/test/media/run-automated-tests-from-test-hub/test-results-overview.png new file mode 100644 index 00000000000..d1d03601f15 Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/test-results-overview.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/test-results.png b/docs/test/media/run-automated-tests-from-test-hub/test-results.png new file mode 100644 index 00000000000..371c0ca4d5c Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/test-results.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/test-run-results.png b/docs/test/media/run-automated-tests-from-test-hub/test-run-results.png new file mode 100644 index 00000000000..680cb2a0c5f Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/test-run-results.png differ diff --git a/docs/test/media/run-automated-tests-from-test-hub/vstest-configuration.png b/docs/test/media/run-automated-tests-from-test-hub/vstest-configuration.png new file mode 100644 index 00000000000..165521e9480 Binary files /dev/null and b/docs/test/media/run-automated-tests-from-test-hub/vstest-configuration.png differ diff --git a/docs/test/media/shared/connectedmode-02.png b/docs/test/media/shared/connectedmode-02.png index 44ecd43c4e8..b1afda74e21 100644 Binary files a/docs/test/media/shared/connectedmode-02.png and b/docs/test/media/shared/connectedmode-02.png differ diff --git a/docs/test/navigate-test-plans.md b/docs/test/navigate-test-plans.md index 06da78f866f..b9d1a6a82f0 100644 --- a/docs/test/navigate-test-plans.md +++ b/docs/test/navigate-test-plans.md @@ -4,8 +4,8 @@ description: Learn how to navigate Test Plans. ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr monikerRange: '>=azure-devops-2020' ms.date: 09/14/2021 --- @@ -15,34 +15,32 @@ ms.date: 09/14/2021 [!INCLUDE [version-gt-eq-2020](../includes/version-gt-eq-2020.md)] -Learn how to navigate Test Plans to support your test goals and operations. Use the following sections of the Test Plans page to accomplish the corresponding tasks. - +Learn how to navigate Test Plans to support your test goals and operations. Use the following sections of the Test Plans page to accomplish the corresponding tasks. - **Mine**: View list of test plans that you created or are of interest to you. -- **All**: View a list of all test plans defined for the project. +- **All**: View a list of all the test plans defined for the project. - **Test plan header**: Locate, favorite, edit, copy or clone a test plan. -- **Test suites tree**: Add, manage, export, or order test suites. Leverage this to also assign configurations and perform user acceptance testing. +- **Test suites tree**: Add, manage, export, or order test suites. Also use to assign configurations and perform user acceptance testing. - **Define tab**: Collate, add, and manage test cases in a test suite of choice via this tab. This tab doesn't appear for users with **Basic** access. - **Execute tab**: Assign and execute tests via this tab or locate a test result to drill into. - **Chart tab**: Track test execution and status via charts, which can also be copied to dashboards. :::image type="content" source="media/navigate/test-plan-overview-2.png" alt-text="Test plans page, navigation elements."::: -To learn about specific test artifacts, see the following articles: +For more information, see the following articles: - [Create test plans and test suites](create-a-test-plan.md) - [Create manual test cases](create-test-cases.md) - [Test settings](./test-different-configurations.md) +## Prerequisites [!INCLUDE [prerequisites](includes/prerequisites.md)] > [!NOTE] > Most operations under the **Define** tab are only available to users with [Basic + Test Plans](https://marketplace.visualstudio.com/items?itemName=ms.vss-testmanager-web) access level or equivalent. Most operations under the **Execute** tab can be exercised by users granted a **Basic** access level. - ## The "Mine" page -The **Mine** page shows a list of test plans that are of interest to you. -This includes plans for teams you are a member of, and test plans you have marked as favorites. +The **Mine** page shows a list of test plans that are of interest to you, which includes plans for teams you're a member of and test plans marked as favorites. You can expand and hide the plans for each team to make it easier to locate or review specific team plans. Use the shortcut menu to edit or delete the selected plan. :::image type="content" source="media/navigate/mine-page-more-options-menu.png" alt-text="Mine page, menu options to edit or delete a test plan."::: @@ -59,11 +57,10 @@ Filter test plans, and edit and delete plans using the shortcut menu, in the sam :::image type="content" source="media/navigate/all-page-favorite-test-plan.png" alt-text="The All list of test plans, favorite a test plan."::: -You can also add a plan to your favorites list while you are viewing it. +You can also add a plan to your favorites list while you view it. :::image type="content" source="media/navigate/test-plan-favorite.png" alt-text="Add a plan to your favorites list."::: - ## Test plan header @@ -129,25 +126,21 @@ Choose the :::image type="icon" source="../media/icons/more-actions.png" border= - Choose **Requirement-based suite** to directly link to the requirements/user stories for seamless traceability. - Choose **Query-based suite** to dynamically organize test cases that meet a query criteria. - **Assign configurations**: Assign configurations for the suite. For example, assign *Chrome*, *Firefox*, *EdgeChromium*, which then become applicable to all existing or new test cases that you add later to the suite. -- **Export**: Export the test plan properties, test suite properties along with details of the test cases and test points as either an email or print to pdf. +- **Export**: Export the test plan and test suite properties and details as either an email or print to pdf. - **Open test suite work item**: This option allows you to edit the Test suite work item form to manage the work item fields. -- **Assign testers to run all tests**: This option is very useful for User Acceptance testing (UAT) scenarios where the same test needs to be run/executed by multiple testers, generally belonging to different departments. +- **Assign testers to run all tests**: This option is useful for User Acceptance testing (UAT) scenarios where the same test gets executed by multiple testers, generally belonging to different departments. - **Rename/Delete**: These options allow you to manage the suite name or remove the suite and its content from the test plan. -- **Import test suites**: Use this option to import test cases present in other suites from other test plans in the same project or even across projects. More details below. - +- **Import test suites**: Use this option to import test cases present in other suites from other test plans in the same project or even across projects. **Export test suite dialog** :::image type="content" source="media/navigate/export-dialog.png" alt-text="Define tab, Export test suite dialog."::: **Import test suites** -Reuse the suites you have created and import them into the current suite/plan. You can select the **Project**, **Test Plan**, and **Test Suite** from which you want to import the tests. Depending upon the suite you select, the entire hierarchy of that suite and corresponding test cases are imported into the current plan. Note that the test cases are added as a reference and not a clone or copy. Also note that we cannot import test suites from the same test plan. +Reuse the suites you created and import them into the current suite/plan. You can select the **Project**, **Test Plan**, and **Test Suite** from which you want to import the tests. Depending upon the suite you select, the entire hierarchy of that suite and corresponding test cases is imported into the current plan. The test cases are added as a reference and not a clone or copy. Also note that we can't import test suites from the same test plan. :::image type="content" source="media/navigate/import-test-suites-dialog.png" alt-text="Test suites tree import overview."::: - - - ## Define and organize test cases @@ -159,7 +152,7 @@ From the **Define** tab, you can collate, add, and manage test cases for a test ### Define test case tasks -From the **Define** tab you can exercise the following tasks: +From the **Define** tab, you can do the following tasks. - **New Test Case**: - **Add Test Case**: Create a new test case using the work item form and automatically add it to the suite. @@ -196,10 +189,10 @@ From the **Define** tab, toolbar, you can exercise the following options: The context menu on the Test case node within the **Define** tab provides the following options: - **Open/edit test case work item form**: This option allows you to edit a Test case using the work item form wherein you edit the work item fields including test steps. -- **Edit test cases**: This option allows you to bulk edit Test case work item fields. However, you cannot use this option to bulk edit test steps. +- **Edit test cases**: This option allows you to bulk edit Test case work item fields. However, you can't use this option to bulk edit test steps. - **Edit test cases in grid**: This option allows you to bulk edit the selected test cases including test steps using the grid view. - **Assign configurations**: This option allows you to override the suite level configurations with test case level configurations. -- **Remove test cases**: This option allows you to remove the test cases from the given suite. It does not change the underlying test case work item though. +- **Remove test cases**: This option allows you to remove the test cases from the given suite. It doesn't change the underlying test case work item though. - **Create a copy/clone of test cases**: Create a copy or clone selected test cases. - **View linked items**: Review items linked to a test case. @@ -215,10 +208,9 @@ Choose **Copy test case** to copy or clone a test case. Specify the destination Use **View linked items** option, to review objects linked to the test case. Choose each tab to view the links listed under the linked object type: - **Test Suites** - **Requirements**: Includes any work item that belongs to the Requirements Category, such as User Stories (Agile), Product Backlog Items (Scrum), Requirements (CMMI), or a custom work item type. -- **Bugs**: Includes bugs that have been filed as part of test execution and any work items that belong to the Bug Category that have been linked to the test case. +- **Bugs**: Includes bugs filed as part of test execution and any work items that belong to the bug Category that links to the test case. :::image type="content" source="media/navigate/view-linked-items.png" alt-text="Define tab, View linked items dialog."::: - ### Bulk update using the Grid view @@ -226,7 +218,7 @@ Choose the :::image type="icon" source="media/navigate/grid-icon.png" border="fa :::image type="content" source="media/navigate/grid-view.png" alt-text="Define tab, grid view."::: -Click within a cell to edit the text in that cell. Right-click within a cell to choose an option to **Insert row**, **Delete row**, or **Clear row**. Choose :::image type="icon" source="media/navigate/bulk-save-icon.png" border="false"::: **Save test cases** to perform a bulk save of your changes. Or, choose :::image type="icon" source="media/navigate/grid-refresh.png" border="false"::: **Refresh** to clear your changes. When complete, choose **Close Grid**. +Select within a cell to edit the text in that cell. Right-click within a cell to choose an option to **Insert row**, **Delete row**, or **Clear row**. Choose :::image type="icon" source="media/navigate/bulk-save-icon.png" border="false"::: **Save test cases** to perform a bulk save of your changes. Or, choose :::image type="icon" source="media/navigate/grid-refresh.png" border="false"::: **Refresh** to clear your changes. When complete, choose **Close Grid**. :::image type="content" source="media/navigate/grid-view-cell-options.png" alt-text="Define tab, grid view, cell options."::: @@ -238,18 +230,18 @@ Use the **Execute** tab to assign test points or run tests. :::image type="content" source="media/navigate/execute-tab-test-points-overview.png" alt-text="Execute tab overview."::: -**What is a test point?** Test cases by themselves are not executable. When you add a test case to a test suite then test point(s) are generated. A test point is a unique combination of test case, test suite, configuration, and tester. -For example, if you have a test case named *Test login functionality* and you add two configurations for the Edge and Chrome browsers, you have two test points. You can execute or run each of these test points. On execution, test results are generated. Through the test results view, or execution history, you can see all executions of a test point. The latest execution for the test point is what you see in the **Execute** tab. +**What is a test point?** Test cases by themselves aren't executable. Add a test case to a test suite, and then test point(s) generate. A test point is a unique combination of test case, test suite, configuration, and tester. +For example, if you have a test case named *Test sign in functionality* and you add two configurations for the Microsoft Edge and Google Chrome browsers, you have two test points. You can execute or run each of these test points. On execution, test results are generated. Through the test results view, or execution history, you can see all executions of a test point. The latest execution for the test point is what you see in the **Execute** tab. Test cases are reusable entities. By including them in a test plan or suite, test points are generated. By executing test points, you determine the quality of the product or service under development. ### Execute tasks -From the **Execute** tab you can do one of the following tasks: +From the **Execute** tab, you can do the following tasks. - **Bulk mark test points**: Quickly mark the outcome of or more test points—**Passed**, **Failed**, **Blocked** or **Not Applicable**—without having to run the test case via the Test runner. -- **Run test points**:Run the test cases by individually going through each test step and marking them pass/fail using a Test runner. Depending upon the application you are testing, you can use the **Web Runner** for testing a "web application" or the **Desktop Runner** for testing desktop or web applications. Invoke **Run with options** to specify a **Build** against which the testing you want to perform. +- **Run test points**:Run the test cases by individually going through each test step and marking them pass/fail using a Test runner. Depending upon the application you're testing, you can use the **Web Runner** for testing a "web application" or the **Desktop Runner** for testing desktop or web applications. Invoke **Run with options** to specify a **Build** against which the testing you want to perform. - **Column options**: Add or remove columns. The list of columns available for selection are associated with test points, such as Run by, Assigned Tester, Configuration, etc. - **Toggle Full screen view**: View the contents of the page in a full screen mode. - **Filter**: Filter the list of test points using the fields of a test case **Title**, **ID**, **Outcome**, **Tester**, **Configuration**, **Assigned To**, or **State**. You can also sort the list by choosing a column header. @@ -275,19 +267,18 @@ Choose the :::image type="icon" source="../media/icons/more-actions.png" border= - **Edit test case**: Open the work item form, optionally edit work item fields including test steps. - **Assign tester**: Assign the test points to a tester for test execution. -To learn more about executing tests, see [Run manual tests](run-manual-tests.md) and [Run automated tests from test plans](run-automated-tests-from-test-hub.md). +For more information about executing tests, see [Run manual tests](run-manual-tests.md) and [Run automated tests from test plans](run-automated-tests-from-test-hub.md). ## Chart test cases and test results -From the chart tab you can create various test case or test result charts. To learn how, see [Track test status, Charts](track-test-status.md). +From the **Chart** tab, you can create various test case or test result charts. For more information, see [Track test status, Charts](track-test-status.md). ## Next steps > [!div class="nextstepaction"] > [Create test plans and test suites](create-a-test-plan.md) - ## Related articles - [Run manual tests](run-manual-tests.md) @@ -297,7 +288,6 @@ From the chart tab you can create various test case or test result charts. To le - [What are extensions?](../extend/overview.md) - [Test Planning and Management Guide](/archive/blogs/visualstudioalmrangers/test-planning-and-management-guide-updated). - ### REST APIs - [Test Management REST API](/rest/api/azure/devops/test) diff --git a/docs/test/overview.md b/docs/test/overview.md index 758f72eefb9..cddb5e0cd04 100644 --- a/docs/test/overview.md +++ b/docs/test/overview.md @@ -5,51 +5,41 @@ ms.assetid: E9D8D614-A09A-4327-81B6-39F880D685E6 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: overview -ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr monikerRange: '<= azure-devops' -ms.date: 12/13/2021 +ms.date: 09/06/2024 --- # What is Azure Test Plans? [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Azure Test Plans provides rich and powerful -tools everyone in the team can use to drive quality and collaboration -throughout the development process. The easy-to-use, browser-based -test management solution provides all the capabilities required for -planned manual testing, user acceptance testing, exploratory testing, -and gathering feedback from stakeholders. +Azure Test Plans offers powerful tools for driving quality and collaboration throughout the development process. This browser-based test management solution supports planned manual testing, user acceptance testing, exploratory testing, and stakeholder feedback. :::image type="content" source="media/overview/intro-test-plans.png" alt-text="Screenshot of Azure Test Plans, Test Plans, All"::: - - > [!NOTE] > This article applies to Azure DevOps Services and Azure DevOps Server 2020 and later versions. Most of the information is valid for earlier on-premises versions, however, images show only examples for the latest version. Also, the user interface changed significantly with the release of Azure DevOps Server 2020. For an overview of the new interface and supported capabilities, see [Navigate Test Plans](navigate-test-plans.md). - ## How does Azure Test Plans work? Through a combination of browser-based tools—[**Test plans**](#test-plans), [**Progress report**](#progress-report), [**Parameters**](#parameters), [**Configurations**](#configurations), [**Runs**](#runs), and [Test tools](#test-tools)—and DevOps integration features, Azure Test Plans supports the following test objectives: -- [**Manual and exploratory testing**](#manual): Manual and exploratory testing which includes the following test activities: - - **[Planned manual testing](#test-plans)**. Manual testing by organizing tests into test plans and test suites by designated testers and test leads. - - **[User acceptance testing](#user-acceptance)**. Testing carried out by designated user acceptance testers to verify the value delivered meets customer requirements, while reusing the test artifacts created by engineering teams. - - **[Exploratory testing](#exploratory-testing)**. Testing carried out by development teams, including developers, testers, UX teams, product owners and more, by exploring the software systems without using test plans or test suites. - - **[Stakeholder feedback](#stakeholder-feedback)**. Testing carried out by stakeholders outside the development team, such as users from marketing and sales divisions. +- [**Perform manual and exploratory testing**](#manual): + - **[Organize planned manual testing](#test-plans)**: Designate testers and test leads to organize tests into test plans and test suites. + - **[Conduct user acceptance testing](#user-acceptance)**: Designate user acceptance testers to verify that the delivered value meets customer requirements, reusing test artifacts created by engineering teams. + - **[Execute exploratory testing](#exploratory-testing)**: Have developers, testers, UX teams, product owners, and others explore the software systems without using test plans or test suites. + - **[Gather stakeholder feedback](#stakeholder-feedback)**: Engage stakeholders outside the development team, such as users from marketing and sales divisions, to carry out testing. -- [**Automated testing**](#automated): Azure Test Plans is fully integrated with Azure Pipelines to support testing within continuous integration/continuous deployment (CI/CD). Test plans and test cases can be associated with build or release pipelines. Pipeline tasks can be added to pipeline definitions to capture and publish test results. Test results can be reviewed via built in progress reports and pipeline test reports. +- [**Automate testing**](#automated): Integrate Azure Test Plans with Azure Pipelines to support testing within CI/CD. Associate test plans and test cases with build or release pipelines. Add pipeline tasks to capture and publish test results. Review test results via built-in progress reports and pipeline test reports. -- [**Traceability**](#traceability): Test cases and test suites linked to user stories, features, or requirements supports end-to-end traceability. Tests and defects are automatically linked to the requirements and builds being tested, which also helps tracking the quality of requirements. Users can add and run tests from the Kanban board, or for larger teams, use the Test plans hub to define test plans and test suites. Pipeline results and the Requirements widget provide a means to track testing of requirements. - -- [**Reporting and analysis**](#reporting): Test result tracking and progress monitoring is supported through configurable tracking charts, test-specific widgets that you can add to dashboards, and built-in reports, such as Progress report, pipeline test result reports, and the Analytics service. +- [**Ensure traceability**](#traceability): Link test cases and test suites to user stories, features, or requirements for end-to-end traceability. Automatically link tests and defects to the requirements and builds being tested. Add and run tests from the board or use the Test plans hub for larger teams. Track testing of requirements with pipeline results and the Requirements widget. +- [**Track reporting and analysis**](#reporting): Monitor test results and progress with configurable tracking charts, test-specific widgets for dashboards, and built-in reports such as Progress reports, pipeline test result reports, and the Analytics service. > [!NOTE] -> **Load and performance testing**: While Azure DevOps cloud-based load testing service is deprecated, Azure Load Testing is available. Azure Load Testing is a fully managed load testing service that enables you to use existing Apache JMeter scripts to generate high-scale load. To learn more, see [What is Azure Load Testing?](/azure/load-testing/overview-what-is-azure-load-testing). For more information about the deprecation of Azure DevOps load testing, see [Changes to load test functionality in Visual Studio and cloud load testing in Azure DevOps](/previous-versions/azure/devops/all/load-test/overview). - +> **Load and performance testing**: While Azure DevOps cloud-based load testing service is deprecated, Azure Load Testing is available. Azure Load Testing is a fully managed load testing service that enables you to use existing Apache JMeter scripts to generate high-scale load. For more information, see [What is Azure Load Testing?](/azure/load-testing/overview-what-is-azure-load-testing). For more information about the deprecation of Azure DevOps load testing, see [Changes to load test functionality in Visual Studio and cloud load testing in Azure DevOps](/previous-versions/azure/devops/all/load-test/overview). ### Key benefits @@ -57,19 +47,17 @@ Azure Test Plans provides software development teams the following benefits. - **Test on any platform**: With the **Test Plans** web portal, you can use any supported browser to access all the manual testing capabilities. It enables you to [create](create-test-cases.md) and [run manual tests](run-manual-tests.md) through an easy-to-use, browser-based interface that users can access from all major browsers on any platform. -- **Rich diagnostic data collection**: Using the web-based Test Runner and Test Runner client you can [collect rich diagnostic data](collect-diagnostic-data.md) during your manual tests. This includes screenshots, an image action log, screen recordings, code coverage, IntelliTrace traces, and test impact data for your apps under test. This data is automatically included in all the bugs you create during test, making it easy for developers to reproduce the issues. +- **Rich diagnostic data collection**: Using the web-based Test Runner and Test Runner client you can [collect rich diagnostic data](collect-diagnostic-data.md) during your manual tests. This data includes screenshots, an image action log, screen recordings, code coverage, IntelliTrace traces, and test impact data for your apps under test. This data is automatically included in all the bugs you create during test, making it easy for developers to reproduce the issues. -- **End to End traceability**: Azure DevOps provides [end-to-end traceability of your requirements, builds, tests and bugs](../boards/queries/link-work-items-support-traceability.md?toc=/azure/devops/test/toc.json&bc=/azure/devops/test/breadcrumb/toc.json). Users can track their requirement quality from cards on the Kanban board. Bugs created while testing are automatically linked to the requirements and builds being tested, which helps you track the quality of the requirements or builds. +- **End to End traceability**: Azure DevOps provides end-to-end traceability of your requirements, builds, tests, and bugs with [linking work items to other objects](../boards/backlogs/add-link.md?toc=/azure/devops/test/toc.json&bc=/azure/devops/test/breadcrumb/toc.json). Users can track their requirement quality from cards on the board. Bugs created while testing are automatically linked to the requirements and builds being tested, which helps you track the quality of the requirements or builds. - **Integrated analytics**: The Analytics service provides data that feeds into built-in reports, configurable dashboard widgets, and customizable reports using Power BI. Data tracks test plan progress and trends for both manual and automated tests. Test analytics provides near real-time visibility into test data for builds and releases. Teams can act on this data to improve test collateral to help maintain healthy pipelines. - **Extensible platform**. You can combine the tools and technologies you already know with the development tools that work best for you to integrate with and [extend Azure DevOps](../integrate/index.md). Use the REST APIs and contribution model available for the Test platform to create extensions that provide the experience you need for your test management lifecycle. - ### Supported scenarios and access requirements -Access to Azure DevOps web portal features are managed through access levels assigned to users. The three main access levels are **Stakeholder**, **Basic**, and **Basic+Test** plans as described in [About access levels](../organizations/security/access-levels.md). The following table indicates the access-level required to exercise the associated tasks with Azure Test Plans. In addition to access levels, select features require permissions to execute. To learn more, see [Manual test access and permissions](manual-test-permissions.md). - +Access to Azure DevOps web portal features are managed through access levels assigned to users. The three main access levels are **Stakeholder**, **Basic**, and **Basic+Test** plans as described in [About access levels](../organizations/security/access-levels.md). The following table indicates the access-level required to exercise the associated tasks with Azure Test Plans. In addition to access levels, select features require permissions to execute. For more information, see [Manual test access and permissions](manual-test-permissions.md). :::row::: :::column span="3"::: @@ -151,10 +139,7 @@ Access to Azure DevOps web portal features are managed through access levels ass :::column-end::: :::row-end::: - - - - + ## Manual and exploratory testing @@ -166,11 +151,16 @@ The work item types—**Test Plans**, **Test Suites**, **Test Cases**, **Sha ![Test management work item types](../boards/work-items/guidance/media/ALM_PT_WITS_TestExperience.png) +In Azure DevOps, the relationship between a test result, test run, and a test case can be understood as follows: + +- **Test case:** A specific scenario or set of steps designed to validate a particular feature or functionality. +- **Test run:** An instance where one or more test cases are executed. Each test run can include multiple test cases. +- **Test result:** The outcome of a test run. Each test case within a test run has its own test result, indicating whether it passed or failed. + > [!NOTE] > With Azure DevOps Server 2020 and later versions, you can perform automated tests by adding test tasks to pipelines. Defining test plans, test cases, and test suites isn't required when test tasks are used. - - + ### Define test plans and test suites @@ -186,21 +176,19 @@ You define manual test cases by defining the test steps and optionally the test :::image type="content" source="media/overview/test-authoring.png" alt-text="Screenshot of Azure Test Plans, Test plans, test suites, Define tab"::: - Within each test case, you specify a set of test steps with their expected outcomes. Optionally, you can add [shared steps](share-steps-between-test-cases.md) or [shared parameters](repeat-test-with-different-data.md). For traceability, link test cases to the user stories, features, or bugs that they test. :::image type="content" source="media/overview/test-case-form.png" alt-text="Screenshot of test case work item form."::: - - + ### Manage shared parameters -Teams use the [Parameters](repeat-test-with-different-data.md) hub, to define and manage parameters shared across test cases. Shared parameters provide support for repeating manual tests several times with different test data. For example, if your users can add different quantities of a product to a shopping cart, then you want to check that a quantity of 200 works just as well as a quantity of 1. +Use the [Parameters](repeat-test-with-different-data.md) hub, to define and manage parameters shared across test cases. Shared parameters provide support for repeating manual tests several times with different test data. For example, if your users can add different quantities of a product to a shopping cart, then you want to check that a quantity of 200 works and a quantity of 1. :::image type="content" source="media/overview/parameters.png" alt-text="Screenshot of Azure Test Plans, Parameters hub"::: - + ### Manage test configurations and variables @@ -208,14 +196,14 @@ With the [Configurations](test-different-configurations.md) hub, teams can defin :::image type="content" source="media/overview/configurations.png" alt-text="Screenshot of Azure Test Plans, Configurations hub"::: - + ## Test execution and test tools With the following tools, developers, testers, and stakeholders can initiate tests and capture rich data as they execute tests and automatically log code defects linked to the tests. Test your application by executing tests across desktop or web apps. - [**Test Runner**](#test-runner): A browser-based tool for testing web applications and a desktop client version for testing desktop applications that you launch from the **Test plans** hub to run manual tests. Test Runner supports rich data collection while performing tests, such as image action log, video recording, code coverage, etc. It also allows users to create bugs and mark the status of tests. -- [**Test & Feedback extension**](#exploratory-testing): A free extension to support exploratory testing that you access from Chrome, Edge, or Firefox browsers. The extension captures interactions with the application being explored through images or video and entering verbal or type-written comments. Information is captured in the Feedback Response work item type to help track response data. +- [**Test & Feedback extension**](#exploratory-testing): A free extension to support exploratory testing that you access from Chrome, Microsoft Edge, or Firefox browsers. The extension captures interactions with the application being explored through images or video and entering verbal or type-written comments. Information is captured in the Feedback Response work item type to help track response data. ### Test execution capability @@ -238,7 +226,7 @@ You can perform the following tasks using the indicated tools. ### Execute tests -From the **Test plans** hub, **Execute** tab, team members can initiate test execution for one or more test cases defined for a test suite. Choices include running **Test Runner** for a web or desktop application. Optionally, team members can select **Run with options** to choose other supported clients for manual testing, or to select a build for automated testing. To learn more, see [Run manual tests](run-manual-tests.md). +From the **Test plans** hub, **Execute** tab, team members can initiate test execution for one or more test cases defined for a test suite. Choices include running **Test Runner** for a web or desktop application. Optionally, team members can select **Run with options** to choose other supported clients for manual testing, or to select a build for automated testing. For more information, see [Run manual tests](run-manual-tests.md). :::image type="content" source="media/overview/execute-tests.png" alt-text="Screenshot of execution of multiple test cases."::: @@ -246,17 +234,15 @@ From the **Test plans** hub, **Execute** tab, team members can initiate test exe **Test Runner** runs tests for your web and desktop applications. Mark test steps and test outcomes as pass or fail, and collect diagnostic data such as system information, image action logs, screen recordings, and screen captures as you test. Bugs filed during the tests automatically include all captured diagnostic data -to help your developers reproduce the issues. To learn more, see [Run tests for web apps](run-manual-tests.md#run-web) and [Run tests for desktop apps](run-manual-tests.md#run-desktop). +to help your developers reproduce the issues. For more information, see [Run tests for web apps](run-manual-tests.md#run-web) and [Run tests for desktop apps](run-manual-tests.md#run-desktop). -! :::image type="content" source="media/overview/test-runner.png" alt-text="Screenshot of Test Runner with annotations."::: - ### User acceptance testing -User acceptance testing (UAT) helps ensure teams deliver the the value requested by customers. You can create UAT test plans and suites, invite several testers to execute these tests, and monitor test progress and results using lightweight charts. To learn how, see [User acceptance testing](user-acceptance-testing.md). +User acceptance testing (UAT) helps ensure teams deliver the value requested by customers. You can create UAT test plans and suites, invite several testers to execute these tests, and monitor test progress and results using lightweight charts. To learn how, see [User acceptance testing](user-acceptance-testing.md). ![Assigning testers to run all tests](media/overview/assign-testers.png) @@ -272,13 +258,12 @@ finding issues, and less time filing them. ![Exploratory testing your web apps](media/manual-testing/exploratory-testing-01.png) - ### Stakeholder feedback -Seeking feedback from stakeholders outside the development team, such -as marketing and sales teams, is vital to develop good quality software. +You should seek feedback from stakeholders outside the development team, such +as marketing and sales teams, which is vital for developing good quality software. Developers can request feedback on their user stories and features. Stakeholders can respond to feedback requests using the browser-based Test & Feedback extension - not just to rate and send comments, but also by capturing rich diagnostic @@ -288,8 +273,7 @@ and [Provide stakeholder feedback](provide-stakeholder-feedback.md). ![Requesting and providing stakeholder feedback](media/manual-testing/stakeholder-feedback-01.png) - - + ## Automated testing @@ -298,32 +282,30 @@ Automated testing is facilitated by running tests within Azure Pipelines. Test a Azure Test Plans supports automated testing in the following ways: - Associate test plans or test cases with build or release pipelines -- Specify test-enable tasks within a pipeline definition. Azure Pipelines provides several tasks, including those listed below, that support a comprehensive test reporting and analytics experience. +- Specify test-enable tasks within a pipeline definition. Azure Pipelines provides several tasks, including the following tasks that support a comprehensive test reporting and analytics experience. - [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2): Use to publish test results to Azure Pipelines. - [Visual Studio Test task](/azure/devops/pipelines/tasks/reference/vstest-v2): Use to run unit and functional tests (Selenium, Appium, Coded UI test, and more) using the Visual Studio Test Runner. - [.NET Core CLI task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2): Use to build, test, package, or publish a dotnet application. - For additional tasks, see [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) + For more tasks, see [Publish Test Results task](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) - Provide built-in reports and configurable dashboard widgets to display results of pipeline testing. - Collect test results and associated test data into the Analytics service. - + ## Traceability Azure Test Plans supports linking bugs and requirements to test cases and test suites. In addition, the following web portal, test-related tools support traceability: - [**View items linked to a test case**](#review-linking): View the test plans, test suites, requirements, and bugs that a test case links to. -- [**Add and run tests from the Kanban board**](#kanban): An Azure Boards feature that supports defining test cases from the user stories, features, or bugs from the Kanban board. Also, you can launch the Test Runner or the Test & Feedback extension to run tests or perform exploratory testing. +- [**Add and run tests from the board**](#kanban): An Azure Boards feature that supports defining test cases from the user stories, features, or bugs from the board. Also, you can launch the Test Runner or the Test & Feedback extension to run tests or perform exploratory testing. - [**Requirements quality widget**](#requirements-quality): Configurable widget used to track quality continuously from a build or release pipeline. The widget shows the mapping between a requirement and latest test results executed against that requirement. It provides insights into requirements traceability. For example, requirements not meeting the quality, requirements not tested, and so on. - - - + ### View items linked to a test case -From the **Test plans** hub, you can view and open the test suites, requirements, and bugs linked to a test case. The **Test Suites** tab also indicates the test plans and projects that reference the test case. The **Requirements** tab lists work items linked to the test case that belong to the requirements category. In addition, you can create a direct-links query that lists items that link to test cases via the **Tests/Tested by** link type. To learn more, see [Create test cases](create-test-cases.md) and [Use direct links to view dependencies](../boards/queries/using-queries.md#use-direct-links-to-view-dependencies). +From the **Test plans** hub, you can view and open the test suites, requirements, and bugs linked to a test case. The **Test Suites** tab also indicates the test plans and projects that reference the test case. The **Requirements** tab lists work items linked to the test case that belong to the requirements category. In addition, you can create a direct-links query that lists items that link to test cases via the **Tests/Tested by** link type. For more information, see [Create test cases](create-test-cases.md) and [Use direct links to view dependencies](../boards/queries/using-queries.md#use-direct-links-to-view-dependencies). :::row::: :::column span=""::: @@ -335,23 +317,23 @@ From the **Test plans** hub, you can view and open the test suites, requirements :::row-end::: - + -### Add and run tests from the Kanban board +### Add and run tests from the board -From the Azure Boards Kanban boards, you can add tests from a user story or feature, automatically linking the test case to the user story or feature. You can view, run, and interact with test cases directly from the Kanban board, and progressively monitor status directly from the card. Learn more at [Add, run, and update inline tests](../boards/boards/add-run-update-tests.md?toc=/azure/devops/test/toc.json&bc=/azure/devops/test/breadcrumb/toc.json). +From the Azure Boards boards, you can add tests from a user story or feature, automatically linking the test case to the user story or feature. You can view, run, and interact with test cases directly from the board, and progressively monitor status directly from the card. Learn more at [Add, run, and update inline tests](../boards/boards/add-run-update-tests.md?toc=/azure/devops/test/toc.json&bc=/azure/devops/test/breadcrumb/toc.json). -:::image type="content" source="media/overview/kanban-board-inline-testing.png" alt-text="Screenshot of Kanban board showing inline tests added to work items."::: +:::image type="content" source="media/overview/kanban-board-inline-testing.png" alt-text="Screenshot of board showing inline tests added to work items."::: - + ### Requirements quality widget -The Requirements quality widget displays a list of all the requirements in scope, along with the **Pass Rate** for the tests and count of **Failed** tests. Selecting a Failed test count opens the **Tests** tab for the selected build or release. The widget also helps to track the requirements without any associated test(s). To learn more, see [Requirements traceability](../pipelines/test/requirements-traceability.md). +The Requirements quality widget displays a list of all the requirements in scope, along with the **Pass Rate** for the tests and count of **Failed** tests. Selecting a Failed test count opens the **Tests** tab for the selected build or release. The widget also helps to track the requirements without any associated tests. For more information, see [Requirements traceability](../pipelines/test/requirements-traceability.md). :::image type="content" source="../pipelines/test/media/requirements-traceability/requirements-quality-widget.png" alt-text="Screenshot of Requirements traceability widget added to dashboard."::: - + ## Reporting and analysis @@ -363,7 +345,7 @@ To support reporting and analysis, Azure Test Plans supports test tracking chart - Dashboard widgets: Configurable widgets that display test results based on selected builds or releases. Widgets include the [Deployment status](#deployment-status) widget and the [Test Results Trend (Advanced)](#test-results-trend) widget. - [Test Analytics](#test-analytics-service): Gain detailed insights from built-in pipeline reports or create custom reports by querying the Analytics service. - + ### Configurable test charts @@ -375,29 +357,28 @@ See more at [Track test status](track-test-status.md). ![Test status tracking](media/manual-testing/track-test-status-01.png) - + ### Progress reports With the [Progress report](progress-report.md) hub, teams can track progress of more than one test plan or test suite. This report helps answer the following questions: - *How much testing is complete?* -- *How many tests have passed, failed or are blocked?* +- *How many tests passed, failed, or are blocked?* - *Is testing likely to complete in time?* - *What is the daily rate of execution?* - *Which test areas need attention?* :::image type="content" source="media/overview/progress-report.png" alt-text="Screenshot of Azure Test Plans, Progress Report hub"::: - - + ### Test runs -The [Runs](insights-exploratory-testing.md) hub displays the results of test runs. This includes all test runs, both manual and automated. +The [Runs](insights-exploratory-testing.md) hub displays the results of test runs, which include all test runs, both manual and automated. > [!NOTE] -> The **Runs** hub is available with Azure DevOps Server 2020 and later versions. It requires enabling the Analytics service which is used to store and manage test run data. To learn more about the service, see [What is the Analytics service?](../report/powerbi/what-is-analytics.md) +> The **Runs** hub is available with Azure DevOps Server 2020 and later versions. It requires enabling the Analytics service which is used to store and manage test run data. For more information about the service, see [What is the Analytics service?](../report/powerbi/what-is-analytics.md) :::image type="content" source="media/overview/recent-test-runs.png" alt-text="Screenshot of Recent test runs"::: @@ -405,9 +386,7 @@ Choose any specific run to view a summary of the test run. :::image type="content" source="media/overview/example-run-summary.png" alt-text="Screenshot of selected Test Runs summary"::: - - - + #### Deployment status @@ -419,167 +398,23 @@ Hover over any build summary, and you can view more details, specifically the nu :::image type="content" source="media/overview/deployment-status-details-hover-over.png" alt-text="Screenshot of Deployment Status widget, details displayed by hover over a build instance."::: - - - + ### Test results trend (Advanced) -The Test Results Trend (Advanced) widget provides near real-time visibility into test data for multiple builds and releases. The widget shows a trend of your test results for selected pipelines. You can use it to track the daily count of test, pass rate, and test duration. Tracking test quality over time and improving test collateral is key to maintaining a healthy DevOps pipeline. The widget supports tracking advanced metrics for one or more build pipelines or release pipelines. The widget also allows filtering of test results by outcome, stacking metrics, and more. To learn more, see [Configure the Test Results Trend (Advanced) widget](../report/dashboards/configure-test-results-trend.md). +The Test Results Trend (Advanced) widget provides near real-time visibility into test data for multiple builds and releases. The widget shows a trend of your test results for selected pipelines. You can use it to track the daily count of test, pass rate, and test duration. Tracking test quality over time and improving test collateral is key to maintaining a healthy DevOps pipeline. The widget supports tracking advanced metrics for one or more build pipelines or release pipelines. The widget also allows filtering of test results by outcome, stacking metrics, and more. For more information, see [Configure the Test Results Trend (Advanced) widget](../report/dashboards/configure-test-results-trend.md). :::image type="content" source="../report/dashboards/media/test-results-trend-widget/passed-bypriority-pass.png" alt-text="Screenshot of Test results trend widget, Advanced version based on Analytics service."::: - - + ### Test Analytics -The built-in tests and test-supported widgets derive their data from the Analytics service. The Analytics service is the reporting platform for Azure DevOps. Test Analytics data is available for Azure DevOps Server 2019 and later versions. It supports the **Analytics** and **Tests** tab and drill-down reports available from the **Pipelines** hub. The **Test failure** drill down report provides a summary of passed and failing tests. To learn more, see [Test Analytics](../pipelines/test/test-analytics.md). +The built-in tests and test-supported widgets derive their data from the Analytics service. The Analytics service is the reporting platform for Azure DevOps and supports the **Analytics** and **Tests** tab and drill-down reports available from the **Pipelines** hub. The **Test failure** drill-down report provides a summary of passed and failing tests. For more information, see [Test Analytics](../pipelines/test/test-analytics.md). :::image type="content" source="media/overview/pipeline-analytics.png" alt-text="Screenshot of Pipelines Analytics summary page."::: -In addition, you can create custom reports by querying the Analytics service. To learn more, see [Overview of sample reports using OData queries](../report/powerbi/sample-odata-overview.md). - - - - +In addition, you can create custom reports by querying the Analytics service. For more information, see [Overview of sample reports using OData queries](../report/powerbi/sample-odata-overview.md). ## Next steps > [!div class="nextstepaction"] @@ -592,71 +427,11 @@ tcm run /execute - [Associate automated tests with test cases](associate-automated-test-with-test-case.md) - [About requesting and providing feedback](../project/feedback/index.md) - [Cross-service integration and collaboration overview](../cross-service/cross-service-overview.md) -- [Manage a virtual machine in Azure DevTest Labs](../pipelines/apps/cd/azure/deploy-provision-devtest-lab.md) - [About pipeline tests](../pipelines/test/test-glossary.md) -## Additional resources +## More resources - [Unit testing](/visualstudio/test/developer-testing-scenarios) - [Unit test basics](/visualstudio/test/unit-test-basics) - [Durable Functions unit testing](/azure/azure-functions/durable/durable-functions-unit-testing) - [What is Azure Load Testing?](/azure/load-testing/overview-what-is-azure-load-testing) - - diff --git a/docs/test/perform-exploratory-tests.md b/docs/test/perform-exploratory-tests.md index c0442623c96..5d459c7df4b 100644 --- a/docs/test/perform-exploratory-tests.md +++ b/docs/test/perform-exploratory-tests.md @@ -1,35 +1,34 @@ --- title: Exploratory test your web app -description: Test tools - Exploratory test your web app in Azure DevOps from your web browser with the Microsoft Test & Feedback extension +description: Test tools - Exploratory test your web app in Azure DevOps from your web browser with the Microsoft Test & Feedback extension. ms.assetid: 1426e139-c7d4-4270-8db7-af7d6da80574 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: quickstart -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' -ms.date: 09/14/2021 +ms.date: 09/16/2024 --- -# Install the Test & Feedback extension +# Install the Test & Feedback extension [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -The **Test & Feedback extension** helps teams perform exploratory testing and provide feedback. -Everyone in the team, such as developers, product owners, managers, UX or UI engineers, -marketing teams, early adopters, and other stakeholders can use the -extension to submit bugs or provide feedback and contribute to the -quality of your product. +The **Test & Feedback extension** helps teams perform exploratory testing and provide feedback. +Everyone on your team can use the Test & Feedback extension to submit bugs or provide feedback and contribute to the quality of your product. -[!INCLUDE [prerequisites-define](includes/prerequisites-run.md)] +## Prerequisites + +[!INCLUDE [prerequisites-run](includes/prerequisites-run.md)] ## Supported web browsers for the extension -The Test & Feedback extension is currently available for [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge (Chromium Only)](https://www.microsoft.com/edge/), and [Mozilla Firefox version 50.0 and higher](https://www.mozilla.org/). +The Test & Feedback extension is currently available for [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge (Chromium Only)](https://www.microsoft.com/edge/), and [Mozilla Firefox version 50.0 and higher](https://www.mozilla.org/). -Some browser versions do not currently support all the features of the Test & Feedback extension. +Some browser versions don't support all the features of the Test & Feedback extension. | Feature | Chrome | Microsoft Edge | Firefox | | --- | --- | --- | --- | @@ -44,93 +43,63 @@ Some browser versions do not currently support all the features of the Test & | Create feedback requests |   **Yes** |   **Yes** |   **Yes** | | Export session report for sharing |   **Yes** |   **Yes** |   **Yes** | | End-to-end traceability for work items |   **Yes** |   **Yes** |   **Yes** | -| Simplified bug and task tracking and triaging |   **Yes** |   **Yes** |   **Yes** | +| Simplified bug and task tracking and triage |   **Yes** |   **Yes** |   **Yes** | | View and get insights from sessions |   **Yes** |   **Yes** |   **Yes** | | View similar existing bugs |   **Yes** |   **Yes** |   **Yes** | | Test app on devices using cloud providers such as Perfecto |   **Yes** |   **Yes** |   **No** | | Manage feedback requests |   **Yes** |   **Yes** |   **Yes** | -

      -For more information, see Visual Studio Marketplace, Azure DevOps tab. + +For more information, see [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms.vss-exploratorytesting-web). + ## Install the extension 1. Check the list of [supported browsers](#browser-support) and decide which you want to use. -1. Download and install your chosen browser, if you haven't already, then open it. - -1. Go to [Visual Studio Marketplace > Test & Feedback](https://marketplace.visualstudio.com/items?itemName=ms.vss-exploratorytesting-web) - and choose **Install**. - - ![Visual Studio Marketplace, Test & Feedback extension, Install](media/perform-exploratory-tests/getstarted-01.png) - - ![Visual Studio Marketplace, Test & Feedback extension, Supported Browsers](media/perform-exploratory-tests/get-started-11.png) - -1. Follow the instructions shown to install the Test & Feedback extension in your browser: - - - If you are using Google Chrome, choose the **Install** link for Chrome from the above image to open the - Google Chrome web store and follow the instructions to install the extension. - - ![Add extension to Chrome](media/perform-exploratory-tests/get-started-chrome01.png) - - ![Follow instructions to install the extension on Chrome.](media/perform-exploratory-tests/get-started-chrome02.png) - - - If you are using Microsoft Edge (Chromium), choose the **Install** link for Edge from the above image to open the - Microsoft Edge Add-ons page and follow the instructions to install the extension. +2. Download and install your chosen browser, if you haven't already, and then open it. - ![Add extension to Edge](media/perform-exploratory-tests/get-started-edge01.png) +3. Go to [Visual Studio Marketplace > Test & Feedback](https://marketplace.visualstudio.com/items?itemName=ms.vss-exploratorytesting-web) + and select **Install**. - ![Follow instructions to install the extension on Edge.](media/perform-exploratory-tests/get-started-edge02.png) - - - If you are using Mozilla Firefox 50.0 and higher, choose the **Install** link for Firefox from the above image to open the - Firefox Browser Add-ons page and follow the instructions to install the extension. + ![Screenshot showing Visual Studio Marketplace, Test & Feedback extension, Install.](media/perform-exploratory-tests/get-started-01.png) - ![Add extension to Firefox](media/perform-exploratory-tests/get-started-firefox01.png) +4. Follow the instructions shown to install the Test & Feedback extension in your browser. - ![Follow instructions to install the extension on Firefox.](media/perform-exploratory-tests/get-started-firefox02.png) - ->You need to install the extension or add-on only once. Afterwards your browser will -update it automatically. + You only need to install the extension or add-on once. Afterwards your browser updates the extension automatically. + ## Select an exploratory testing mode 1. Open the extension you installed in your browser by choosing the ![Test and Feedback](media/shared/exp-test-icon.png) icon. - ![Open extension](media/perform-exploratory-tests/open-extension.png) + ![Screenshot showing opening the extension.](media/perform-exploratory-tests/open-extension.png) 1. Decide if you want to use the extension in Connected or Standalone mode. - ![Choose connection mode](media/perform-exploratory-tests/getstarted-06.png) + ![Screenshot showing choosing connected mode.](media/perform-exploratory-tests/getstarted-06.png) **[Connected mode](connected-mode-exploratory-testing.md)** - Available to all users of Azure DevOps and TFS 2015 or later: - - - Users with **Basic** access or higher: Full capture and create capabilities - to submit bugs, tasks, and test cases. Includes collaboration - capabilities such as end-to-end traceability, rich insights - across completed exploratory sessions, simplified tracking - and triaging for bugs and tasks, and more. - - Users with **Stakeholder** access: Full capture and create capabilities, - except for test cases, to submit feedback and respond to feedback - requests from the team. - - Feedback experience is available only in Azure DevOps and TFS 2017 or later.

      + Available to all users of Azure DevOps: + + - Users with at least **Basic** access: Full capture and create capabilities + to submit bugs, tasks, and test cases. Includes collaboration capabilities, such as end-to-end traceability, rich insights across completed exploratory sessions, simplified tracking, and triage for bugs and tasks, and more. + - Users with **Stakeholder** access: Full capture and create capabilities, except for test cases, to submit feedback and respond to feedback requests from the team. + - Feedback experience is available only in Azure DevOps.

      **[Standalone mode](standalone-mode-exploratory-testing.md)** - Available to everyone. No connection to Azure DevOps is required. Take notes and screenshots with - inline annotations to capture issues. Create bugs and export - a session report to share findings. + Available to everyone. No connection to Azure DevOps is required. Take notes and screenshots with inline annotations and capture issues. Create bugs and export a session report to share findings. -If you have problems connecting to Azure DevOps, you may find -the topic [TF31002: Unable to connect](../organizations/projects/tf31002-unable-connect-tfs.md) useful. +If you have any issues connecting to Azure DevOps, see [Troubleshoot connection](../user-guide/troubleshoot-connection.md). -## Related articles +## Next steps -* [FAQs for manual testing](reference-qa.yml#tandfext) +> [!div class="nextstepaction"] +> [Use the Test & Feedback extension in Connected mode](connected-mode-exploratory-testing.md) -## Next step +## Related articles -> [!div class="nextstepaction"] -> [Use the Test & Feedback extension in Connected mode](connected-mode-exploratory-testing.md) +* [FAQs for manual testing](reference-qa.yml#tandfext) diff --git a/docs/test/progress-report.md b/docs/test/progress-report.md index 3e0cddd6fdf..0671c07d29d 100644 --- a/docs/test/progress-report.md +++ b/docs/test/progress-report.md @@ -5,8 +5,8 @@ ms.assetid: cd74abc1-44c0-4390-8d5d-4d1afbd4606c ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '>= azure-devops-2020' ms.date: 09/14/2021 --- @@ -15,16 +15,9 @@ ms.date: 09/14/2021 [!INCLUDE [version-gt-eq-2020](../includes/version-gt-eq-2020.md)] -To track the progress of more than one test plan or test suite, use the Progress Report. It helps you track the team's progress with respect to planned testing of your product or service by answering the following questions: -- How much testing is complete? -- What is the current status how many tests have passed, failed or are blocked? -- Is the testing likely to complete in time? -- What is the rate of execution on a daily basis? -- Get a breakdown by test plan and suite to understand where execution is going slow or has many failed or blocked tests. -- View the progress each suite has made within a test plan and identify the areas that need attention. - -> [!NOTE] -> - The Progress Report lets you view data for one or more Test Plans in a single project. To view data across projects, use the [OData APIs](../report/extend-analytics/data-model-analytics-service.md). This report is also rendered using the same OData APIs. +To track the progress of more than one test plan or test suite, use the Progress Report. The Progress Reports helps you track status of passed, failed, or blocked tests, estimations, rate of execution, progress, and more for your team. + +- The Progress Report lets you view data for one or more Test Plans in a single project. To view data across projects, use the [OData APIs](../report/extend-analytics/data-model-analytics-service.md). This report is also rendered using the same OData APIs. > - The report, always shows you the data for the test plan you last accessed. Filter selections aren't stored. > - Report data corresponds to the the current test suite hierarchy in the selected test plans. Hierarchy history isn't stored. > - Report data is updated approximately every 15 minutes. Do not use this report for real-time analysis or reporting. Expect ~15 mins of duration between a test execution and the same to show up in the report. @@ -32,49 +25,55 @@ To track the progress of more than one test plan or test suite, use the Progress > - Percentage Data will not display the decimal values in this report. > - Some Outcomes are not identified on the Details section even though they contribute to the "Run%" column. Test Cases with Outcome "Blocked", "Not Applicable", and in the paused state are not reflected on the "Passed%" or "Failed%". If you have Test Cases with these Outcomes there will be a difference between the "Run%" and the "Passed%" + "Failed%" sum. The "Not Run" column only counts Test Cases that are showing as "Active" in the current Outcome. You can use the report filters to fine tune the results. - ## Prerequisites ::: moniker range="azure-devops" -- You must be a member of a project with Basic access or higher. If you don't have a project yet, create one. For more information, see [Sign up for free](../user-guide/sign-up-invite-teammates.md). -- If you haven't been added as a project member, [get added now](../organizations/accounts/add-organization-users.md). Anyone with access to the project, except stakeholders, can view Analytics views. -- **Test Plans** must be enabled. If it is disabled, the **Test Plans>Progress Report** page won't display. To re-enable **Test Plans**, see [Turn an Azure DevOps service on or off](../organizations/settings/set-services.md) -- Have the **View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../report/powerbi/analytics-security.md). + +| Category | Requirements | +|--------------|-------------| +|**Project access**| [Project member](../organizations/security/add-users-team-project.md). | +|**Access levels**| At least **Basic** access. For more information, see [Manual test access and permissions](manual-test-permissions.md). | +| **Permissions** |**View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../report/powerbi/analytics-security.md).| +|**Services** |**Test Plans** enabled. If it's disabled, the **Test Plans** > **Progress Report** page doesn't display. To re-enable **Test Plans**, see [Turn an Azure DevOps service on or off](../organizations/settings/set-services.md)| + ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" -- You must be a member of a project with Basic access or higher. If you haven't been added as a project member, [get added now](../organizations/security/add-users-team-project.md). Anyone with access to the project, except Stakeholders, can view Analytics views. -- [Verify that Analytics](../report/dashboards/analytics-extension.md)] is installed, and if not, then enable it. You must be the **Organization owner** or a member of the [**Project Collection Administrators** group](../organizations/security/change-organization-collection-level-permissions.md) to add extensions or enable the service. -- **Test Plans** must be enabled. If it is disabled, the **Test Plans>Progress Report** page won't display. To re-enable **Test Plans**, see [Turn an Azure DevOps service on or off](../organizations/settings/set-services.md) -- Have the **View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../report/powerbi/analytics-security.md). +| Category | Requirements | +|--------------|-------------| +|**Project access**| [Project member](../organizations/security/add-users-team-project.md). | +|**Access levels**| At least **Basic** access. For more information, see [Manual test access and permissions](manual-test-permissions.md). | +| **Permissions** |**View Analytics** permission set to *Allow*. For more information, see [Grant permissions to access the Analytics service](../report/powerbi/analytics-security.md).| +| **Extensions** |[Analytics extension](../report/dashboards/analytics-extension.md) installed and enabled. | +|**Services** |**Test Plans** enabled. If it's disabled, the **Test Plans** > **Progress Report** page doesn't display. To re-enable **Test Plans**, see [Turn an Azure DevOps service on or off](../organizations/settings/set-services.md)| ::: moniker-end ## Configure the report -Open the report from the web portal by going to **Test Plans>Progress Report**. The report shows you the status of the test plan you last accessed. However, using the filter bar, you can select one or more test plans in the project. +Open the report from the web portal by going to **Test Plans** > **Progress Report**. The report shows you the status of the test plan you last accessed. However, using the filter bar, you can select one or more test plans in the project. ## Understand the report -The progress report consists of three sections: -1. **Summary**: This section provides you with a consolidated view for the selected test plans. To understand what test points are, see [Navigate Test Plans](navigate-test-plans.md). -2. **Outcome trend**: This graph renders a daily snapshot to give you an execution and status trendline. It can show data for 14 days (default), 30 days, or a custom range of your choice. Data for today may or may not appear in this chart based on the time of the day you are looking at the report. -3. **Details**: This section lets you drill down by each test plan and gives you summary of each test suite in it. The section also lets you navigate to a test plan or suite of choice by double-clicking on it. +The progress report consists of the following sections. +- **Summary**: This section provides you with a consolidated view for the selected test plans. To understand what test points are, see [Navigate Test Plans](navigate-test-plans.md). +- **Outcome trend**: This graph renders a daily snapshot to give you an execution and status trendline. It can show data for 14 days (default), 30 days, or a custom range of your choice. Data for today might not appear in this chart based on the time of the day you're looking at the report. +- **Details**: This section lets you drill down by each test plan and gives you a summary of each test suite. The section also lets you navigate to a test plan or suite of choice by double-clicking on it. -![Progress report](media/progress-report/snippet.PNG) +![Screenshot of a Progress Report.](media/progress-report/snippet.PNG) -An example of a healthy outcome trend is as follows because as time is progressing, the number of not run tests are decreasing (because tests are being executed) and the number of passed tests are on the rise. +An example of a healthy outcome trend would be as time progresses, the number of unrun tests decreases and the number of passed tests rises. -![good trend](media/progress-report/goodtrend.PNG) +![Screenshot showing example of good trend.](media/progress-report/goodtrend.PNG) -An example of an unhealthy outcome trend is as follows because as time is progressing, there is no significant execution occurring and the # of passed and failed tests are continuing to remain flat. In such situations, use the details card to drill down and take suitable actions. +An example of an unhealthy outcome trend would be as time progresses, no significant execution occurs and the number of passed and failed tests remains flat. In such situations, use the details card to drill down and take suitable actions. -![bad trend](media/progress-report/badtrend.png) +![Screenshot showing example of bad trend.](media/progress-report/badtrend.png) ## Filter -Use the filter barto filter by **Test Suites**, **Configuration**, **Tester**, Test Case **Priority**, and Test Case **Assigned To**. For example, you can filter by configuration 'Chrome' and then 'Edge' to understand where the execution and pass % are higher. Note: Tester is the person to whom the test point is assigned for execution whereas Assigned to is the person who is responsible for the reusable test case. +Filter by **Test Suites**, **Configuration**, **Tester**, Test Case **Priority**, and Test Case **Assigned To**. For example, you can filter by configuration 'Chrome' and then 'Microsoft Edge' to understand where the execution and pass % are higher. **Tester** is the user to whom the test point is assigned for execution whereas **Assigned To** is the user responsible for the reusable test case. > [!NOTE] > The test plan is considered Level 1. Its child suites are considered level 2. Their child suites in turn are considered level 3. The Test Suites filter shows only the Level 3 test suites inside the selected test plans. To select a Level 2 test suite select all the Level 3 test suites underneath it. This assumes the Level 2 test suites itself does not have any test points. diff --git a/docs/test/provide-stakeholder-feedback.md b/docs/test/provide-stakeholder-feedback.md index 884943d4bbd..9537a3c053e 100644 --- a/docs/test/provide-stakeholder-feedback.md +++ b/docs/test/provide-stakeholder-feedback.md @@ -5,157 +5,130 @@ ms.assetid: 41CCD562-C071-4C33-A178-71DDAE83912E ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra ms.date: 12/07/2018 monikerRange: '<= azure-devops' --- -# Provide feedback using the Test & Feedback extension +# Provide feedback using the Test & Feedback extension [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Stakeholders and other users can respond to feedback requests using the -Test & Feedback extension in two ways: +Stakeholders and other users can respond to feedback requests using the Test & Feedback extension in the following ways: -* [From the link in a feedback request email](#email) -* [Directly from the Test & Feedback extension](#direct) +* [Respond from the link in a feedback request email](#email) +* [Respond directly from the Test & Feedback extension](#direct) -Before you start, ensure you have installed the -[Test & Feedback extension](perform-exploratory-tests.md). -This is required in order to respond to feedback requests. +[!INCLUDE [important-note-request-feedback-unavailable](includes/important-note-request-feedback-unavailable.md)] -> [!NOTE] -> Any user with a Stakeholder access can use the -Test & Feedback extension in **Stakeholder** mode. This -mode is designed to allow the widest possible range of users -to assist test teams by providing feedback. +## Prerequisites + +| Category | Requirement | +|--------------|-------------| +| **Project access** | [Project member](../organizations/security/add-users-team-project.md). | +| **Access levels** | To request or provide feedback: At least **Stakeholder** access. | +| **Extensions** |[Test & Feedback extension](perform-exploratory-tests.md).| ## Provide feedback directly from a feedback request email -1. Open the feedback request email and choose the - **Provide feedback** link. +1. In the feedback request email, select **Provide feedback**. - ![Choosing the Provide feedback link in the request email](media/provide-stakeholder-feedback/provide-stakeholder-feedback-04.png) + ![Screenshot shows choosing the Provide feedback link in the request email.](media/provide-stakeholder-feedback/provide-stakeholder-feedback-04.png) -1. The Azure DevOps landing page opens to confirm - that the extension has been automatically configured with - the feedback request. Choose the ![launch extension](media/shared/exp-test-icon.png) - icon in the toolbar to launch the extension. + The Azure DevOps landing page opens to confirm that the extension is automatically configured with the feedback request. + +2. Choose the ![launch extension](media/shared/exp-test-icon.png) icon in the toolbar to launch the extension. - ![Confirmation that the extension has been automatically configured](media/provide-stakeholder-feedback/provide-stakeholder-feedback-05.png) + ![Screenshot shows confirmation that the extension has been automatically configured.](media/provide-stakeholder-feedback/provide-stakeholder-feedback-05.png) - If you are a **Stakeholder**, you see the **Feedback requests** page. - Read the instructions (if any) in the feedback form to - understand how to give the feedback and what the requestor - requires. + If you're a **Stakeholder**, the **Feedback requests** page is visible. + Read the instructions (if any) in the feedback form to understand how to give the feedback and what the requestor requires. - ![The feedback form containing the instructions](media/provide-stakeholder-feedback/provide-stakeholder-feedback-06.png) + ![Screenshot shows the feedback form containing the instructions.](media/provide-stakeholder-feedback/provide-stakeholder-feedback-06.png) - If you are a **Basic** user, you see the **Explore work item** traceability - page showing details of the user story on which feedback was requested, - and the user acceptance criteria (if any). + If you're a **Basic** user, the **Explore work item** traceability page shows details of the user story on which feedback was requested, and the user acceptance criteria (if any). - ![The traceability page showing the user story and user acceptance criteria](media/provide-stakeholder-feedback/provide-stakeholder-feedback-18.png) + ![Screenshot shows the traceability page showing the user story and user acceptance criteria.](media/provide-stakeholder-feedback/provide-stakeholder-feedback-18.png) -1. Read any instructions in the email and this page - to understand how to give the feedback, and on what feature. +3. Read any instructions in the email and this page to understand how to give the feedback, and on which feature. - -1. Open the application you need to provide feedback on - and begin your feedback. For example, choose - **Capture screenshot** to take a screenshot. + +4. Open the application you need to provide feedback on and begin your feedback. For example, select **Capture screenshot** to take a screenshot. - ![Capturing a screenshot](media/shared/provide-stakeholder-feedback-07.png) - - You can use all the capabilities of the extension - such as capturing screenshots, notes, and screen recordings. - For more details, see [this topic](connected-mode-exploratory-testing.md). + ![Screenshot shows capturing a screenshot.](media/shared/provide-stakeholder-feedback-07.png) - >Some browsers may not provide all the capture capabilities. - See [Supported web browsers for the extension](perform-exploratory-tests.md#browser-support). + You can use all the capabilities of the extension such as capturing screenshots, notes, and screen recordings. For more information, see [Exploratory testing in connected mode](connected-mode-exploratory-testing.md). -1. When you are done capturing feedback: +5. When you're done capturing feedback, do the following actions: - * If you are a **Stakeholder**, choose **Provide feedback**. - You can optionally choose to create bugs and tasks when you - submit your feedback. The process is the same as described in - [this topic](connected-mode-exploratory-testing.md#create-bugs). + * If you're a **Stakeholder**, select **Provide feedback**. You can optionally choose to create bugs and tasks when you submit your feedback. The process is the same as described in [Exploratory testing in connected mode](connected-mode-exploratory-testing.md#create-bugs). - ![Submitting your feedback](media/shared/provide-stakeholder-feedback-08.png) + ![Screenshot shows submitting your feedback.](media/shared/provide-stakeholder-feedback-08.png) - - * If you are a **Basic** user, create a bug or a task. + + * If you're a **Basic** user, create a bug or a task. - ![Create a bug or a task from the captured information](media/connected-mode-exploratory-testing/create-bugs-02.png) + ![Screenshot shows creating a bug or a task from the captured information.](media/connected-mode-exploratory-testing/create-bugs-02.png) -1. All your feedback captured is shown in the response form, bug, or task. - Type a suitable title and, optionally, select a star rating for - the feature you've been testing. +6. All your feedback shows in the response form, bug, or task. Enter a suitable title and optionally select a star rating for the feature you've been testing. - ![Entering a title and star rating](media/shared/provide-stakeholder-feedback-09.png) + ![Screenshot shows entering a title and star rating.](media/shared/provide-stakeholder-feedback-09.png) -1. Save your feedback. This create a work item in Azure DevOps containing all your feedback. +7. Save your feedback, which creates a work item in Azure DevOps containing all your feedback. -1. Continue to capture more feedback if required. You can submit - multiple feedback responses, bugs, and tasks for the same feedback request. +8. Continue to capture more feedback if necessary. You can submit multiple feedback responses, bugs, and tasks for the same feedback request. -1. If you are a **Stakeholder**: +9. If you're a **Stakeholder**: - * When you are done providing feedback, go to the **Feedback + * When you're done providing feedback, go to the **Feedback requests** page and choose **Feedback requests**. - ![Opening the pending feedback requests page](media/shared/provide-stakeholder-feedback-10.png) + ![Screenshot shows opening the pending feedback requests page.](media/shared/provide-stakeholder-feedback-10.png) * In the pending feedback requests page, mark the feedback request as **Completed**. - ![Completing your feedback session](media/shared/provide-stakeholder-feedback-11.png) + ![Screenshot shows completing your feedback session.](media/shared/provide-stakeholder-feedback-11.png) -1. Choose the **Stop** icon to end your feedback session. +10. **Stop** your feedback session. - ![Ending your feedback session](media/shared/provide-stakeholder-feedback-12.png) + ![Screenshot shows ending your feedback session.](media/shared/provide-stakeholder-feedback-12.png) -## Provide feedback directly from the Test & Feedback extension -1. Open the Test & Feedback extension in your browser using the - ![launch exploratory testing](media/shared/exp-test-icon.png) - icon in the toolbar. +## Provide feedback directly from the Test & Feedback extension -1. In the **Connection settings** page, choose **Connected** mode. +1. Open the Test & Feedback extension in your browser using the ![launch exploratory testing](media/shared/exp-test-icon.png) icon in the toolbar. + +2. From the **Connection settings** page, select **Connected** mode. - ![Choosing Connected mode](media/shared/connectedmode-01.png) + ![Screenshot shows choosing Connected mode.](media/shared/connectedmode-01.png) -1. Connect to the server and the project or team that is requesting feedback. +3. Connect to the server and the project or team that is requesting feedback. - ![Entering connection details](media/shared/connectedmode-02.png) + ![Screenshot shows entering connection details.](media/shared/connectedmode-02.png) -1. Open the **Feedback requests** page to see all your feedback requests +4. Open the **Feedback requests** page to see all your feedback requests from the project or team you connected to. - ![Viewing the list of feedback requests](media/provide-stakeholder-feedback/provide-stakeholder-feedback-15.png) + ![Screenshot shows viewing the list of feedback requests.](media/provide-stakeholder-feedback/provide-stakeholder-feedback-15.png) -1. Select the feedback request you want to respond to and choose +5. Select the feedback request you want to respond to and choose **View feedback**. - ![Selecting a feedback request to view](media/provide-stakeholder-feedback/provide-stakeholder-feedback-16.png) + ![Screenshot shows selecting a feedback request to view.](media/provide-stakeholder-feedback/provide-stakeholder-feedback-16.png) -1. Read the instructions in the feedback request details page, then +6. Read the instructions in the feedback request details page, then choose **Provide feedback**. - ![Starting to provide feedback for a request](media/provide-stakeholder-feedback/provide-stakeholder-feedback-17.png) + ![Screenshot shows starting to provide feedback for a request.](media/provide-stakeholder-feedback/provide-stakeholder-feedback-17.png) -1. Capture and submit your feedback as [shown above](#capture-feedback). +7. Capture and submit your feedback as [previously shown](#capture-feedback). ## Related articles -* [Request stakeholder feedback using the Test & Feedback extension](request-stakeholder-feedback.md#request) -* [Voluntary stakeholder feedback using the Test & Feedback extension](voluntary-stakeholder-feedback.md#voluntary) -* [Track stakeholder feedback using the Test & Feedback extension](track-stakeholder-feedback.md#track) * [Exploratory test and submit feedback directly from your browser](perform-exploratory-tests.md) * [Overview of manual and exploratory testing](index.yml) - - diff --git a/docs/test/reference-qa.yml b/docs/test/reference-qa.yml index 80545aaa764..588ea4ba446 100644 --- a/docs/test/reference-qa.yml +++ b/docs/test/reference-qa.yml @@ -5,8 +5,8 @@ metadata: titleSuffix: Azure Test Plans ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 - ms.author: chcomley - author: chcomley + ms.author: jeom + author: raviLiftr ms.topic: FAQ monikerRange: '<= azure-devops' ms.date: 02/16/2022 @@ -36,13 +36,13 @@ sections: - question: What are query-based test suites? answer: | - Query-based test suites use a query to group together test cases that have a particular characteristic, for example, all tests that have Priority=1. The test suite automatically includes every test case that is returned by the query. + Query-based test suites use a query to group together test cases that have a particular characteristic, for example, all tests that have Priority=1. The test suite automatically includes every test case returned by the query. - question: Can I copy or clone test plans and test suites? answer: | - **Yes**. Depending on the action you want to take, you can copy or clone test plans and import or clone test suites. To learn how, see [Copy or clone test plans, test suites, and test cases](copy-clone-test-items.md). + **Yes**. Depending on your desired action, you can copy or clone test plans and import or clone test suites. To learn how, see [Copy or clone test plans, test suites, and test cases](copy-clone-test-items.md). > [!NOTE] > - You can export a maximum of 75 test suites in a single operation. The email supports up to 1 MB of data. @@ -50,7 +50,7 @@ sections: - question: Can I just view test plan data I export, or copy it to a Word document? answer: | - *Yes** Choose **Print** in the **Export** dialog box, then choose **Cancel** in the **Print** dialog box. + **Yes**. Select **Print** in the **Export** dialog box, then choose **Cancel** in the **Print** dialog box. This option displays the data in the report. Select all the text, then copy and paste it into a Word document, if you want. All the formatting in the report is retained. @@ -76,7 +76,7 @@ sections: - question: Can I copy test cases from one project to another? answer: | - **Yes**. See [Copy test cases](copy-clone-test-items.md#copy-test-cases). For Azure DevOps Server 2020 and later versions, you can copy test cases from within a project or another project to a test suite, or you can use the [Grid view to copy and paste test cases](copy-clone-test-items.md#copy-paste) from one suite to another. Optionally, you can [bulk import and export test cases](copy-clone-test-items.md#bulk-import-export). + **Yes**. See [Copy test cases](copy-clone-test-items.md#copy-test-case). For Azure DevOps Server 2020 and later versions, you can copy test cases from a project to a test suite, or you can use the [Grid view to copy and paste test cases](copy-clone-test-items.md#copy-paste) from one suite to another. Optionally, you can [bulk import and export test cases](copy-clone-test-items.md#bulk-import-export). - question: Can I add an extra line to a test step? answer: | @@ -98,17 +98,7 @@ sections: In the **Linked Items** dialog box, select **Test Suites** to see the test suites linked to the test case. Double-click a test suite to open it. ::: moniker-end - ::: moniker range="<=azure-devops-2019" - Select a test case, then view the test suites details. - The Associated test suites pane shows you any test suite for any test plan that contains this test case. - This view includes all projects. - - Select the associated test suite to view it. - To view the project and the test plan for that test suite, move your pointer over the test suite. - - ![On Test Plans page, select details pane. Select test suites in the test details pane.](media/create-test-cases/TestSuites.png) - - ::: moniker-end + - question: How do I delete a test case or other test artifacts? answer: | @@ -124,12 +114,12 @@ sections: - question: How is data shown in the charts for test cases that are in multiple test suites? answer: | - For test case charts, if a test case has been added to multiple test suites in a plan then it's only counted once. + For test case charts, if a test case gets added to multiple test suites in a plan, then the test only gets counted once. For test result charts, each instance of a test that is run is counted for each of the test suites separately. - question: Who can create charts? answer: | - To create charts, you need to be assigned Basic access or higher. + To create charts, you need to be assigned at least Basic access. - question: How can I edit or delete a chart? answer: | @@ -191,7 +181,7 @@ sections: - question: How do I play the video recordings I created with the extension? answer: | - YOu can view the video recordings created by the Test & Feedback extension in [Google Chrome](https://www.google.com/chrome/) browser and in the [VLC Video Player](https://www.videolan.org/vlc/download-windows.html). + You can view the video recordings created by the Test & Feedback extension in [Google Chrome](https://www.google.com/chrome/) browser and in the [VLC Video Player](https://www.videolan.org/vlc/download-windows.html). - question: Does the extension support Team Foundation Server? answer: | @@ -203,15 +193,15 @@ sections: - question: Can I edit an existing bug instead of creating a new bug when using the Test & Feedback extension? answer: | - Yes, the extension automatically shows bugs that may be related to the one you're creating + Yes, the extension automatically shows bugs that might be related to the one you're creating and allows you to add your screenshots, notes, and videos to this existing bug. For more information, see [Add findings to existing bugs with exploratory testing](add-to-bugs-exploratory-testing.md). - question: On Google Chrome, the mouse offset towards the left makes it difficult to use. Do you have a workaround? answer: | - Follow this procedure: + Do the following steps as a workaround. 1. Navigate to **chrome://flags/#enable-use-zoom-for-dsf**. - 1. Search for 'Use Blink's zoom for device scale factor'. + 1. Search for 'Use Blink's zoom for device scale factor.' 1. Change it to **Disabled**. additionalContent: | diff --git a/docs/test/repeat-test-with-different-data.md b/docs/test/repeat-test-with-different-data.md index 61636037034..77da6441957 100644 --- a/docs/test/repeat-test-with-different-data.md +++ b/docs/test/repeat-test-with-different-data.md @@ -1,12 +1,12 @@ --- title: Repeat a test with different data -description: Learn about manual and exploratory testing. Repeat a test with different data in Azure Test Plans and Team Foundation Server. +description: Learn about manual and exploratory testing. Repeat a test with different data in Azure Test Plans. ms.assetid: C9953A56-9BD6-408B-899B-FAD816B9FC0C ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' ms.date: 09/14/2021 --- @@ -15,24 +15,23 @@ ms.date: 09/14/2021 [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -You add parameters to your [manual test](create-test-cases.md) to repeat the test with different test data. -For example, you can test adding different quantities to a shopping cart from quantities of 1, 5, 10, or 200. +Add parameters to your [manual test](create-test-cases.md) to repeat the test with different test data. For example, you can test adding different quantities to a shopping cart from quantities of 1, 5, 10, or 200. -You insert parameters within your test steps for a manual test case. Then, you provide a table of parameter values. -You can add shared parameters to test cases or convert parameters you've recently inserted into shared parameters. -Shared steps and shared parameters are different work item types that can be shared across multiple test cases. -They're linked to test cases through the **Test Cases-Shared Steps** and **Referenced By-References** link types as shown in the following illustration. +Insert parameters within your test steps for a manual test case. Then, provide a table of parameter values. You can add shared parameters to test cases or convert parameters you recently inserted into shared parameters. Shared steps and shared parameters are different work item types that can be shared across multiple test cases. They're linked to test cases through the **Test Cases-Shared Steps** and **Referenced By-References** link types as shown in the following illustration. ![Diagram shows Shared Steps connected to Test Case, which is also connected to Shared Parameters.](media/repeat-test-with-different-data/shared-steps-shared-parameters.png) With shared steps and shared parameters, you can run multiple test cases with the same data. +## Prerequisites + [!INCLUDE [prerequisites-define](includes/prerequisites-define.md)] ## Add parameters to a test case + ::: moniker range=">=azure-devops-2020" -You can add parameters to your tests. +Do the following steps to add parameters to your tests. 1. Create a parameter by typing a name preceded by "**@**" in the actions and expected results of your test steps. @@ -42,97 +41,40 @@ You can add parameters to your tests. You might need to scroll down to see them. ::: moniker-end -::: moniker range="<=azure-devops-2019" - -1. Create a parameter by typing a name preceded by "**@**" in the - actions and expected results of your test steps. - - ![Creating a parameter](media/repeat-test-with-different-data/repeat-test-with-different-data-01.png) - -1. Underneath the list of steps, add combinations of parameter values. - You might need to scroll down to see them. -::: moniker-end - ## Share parameters between test cases ::: moniker range=">=azure-devops-2020" -You can convert existing parameters to shared parameters so that you can use them and the associated data in other test cases. +Do the following steps to convert existing parameters to shared parameters, so you can use them and the associated data in other test cases. 1. In an open test case, select **Convert to shared parameters**. ![Screenshot shows converting existing parameters to shared parameters.](media/repeat-test-with-different-data/convert-shared-parameters.png) -1. After you've created a shared parameter set, open another test case and add the shared parameter set to that test case. +2. After you create a shared parameter set, open another test case and add the shared parameter set to that test case. ![Screenshot shows adding the shared parameter set to a test case.](media/repeat-test-with-different-data/add-shared-parameter-set.png) You can search for the shared parameter set by name. - The shared parameter set is displayed in the **Parameter values** section after you add it. + The shared parameter set displays in the **Parameter values** section after you add it. You can now use these parameters in your test case steps. -1. If the test case has different parameter names for these shared parameters, map the shared parameters to the local parameters to use the shared parameter data. +3. If the test case has different parameter names for these shared parameters, map the shared parameters to the local parameters to use the shared parameter data. ![Screenshot shows mapping a shared parameter to a local parameter.](media/repeat-test-with-different-data/map-shared-local-parameter.png) When they're correctly mapped, the data associated with the shared parameter is displayed. -1. Add, edit, and rename your shared parameter sets in the **Parameters** page. +4. Add, edit, and rename your shared parameter sets in the **Parameters** page. View the test cases that reference them in the **Test cases** pane. ![Screenshot shows options to add, edit, view, and rename a shared parameter.](media/repeat-test-with-different-data/shared-parameter-sets.png) -1. Each shared parameter set is a work item. Open the **Properties** page to view or make changes to this work item. +5. Each shared parameter set is a work item. Open the **Properties** page to view or make changes to this work item. For example, you can assign owners and track changes. You can't add more than one shared parameter set to a single test case. -If two test cases share similar data, for example, one test case needs customer ID, name, email, and phone, and the second needs customer ID, name and address, you might consider creating a single shared parameter set containing all of the parameters - even though a few of the columns in the set will remain unused in each test case. - -You can import parameter values from an Excel spreadsheet to your shared parameter sets. -Paste the values into your shared parameters grid. -You can also copy the data from your grid back into Excel. - -::: moniker-end - -::: moniker range="<=azure-devops-2019" - -1. Convert existing parameters to shared parameters so that you - can use them and the associated data in other test cases. - - ![Converting existing parameters to shared parameters](media/repeat-test-with-different-data/repeat-test-with-different-data-02.png) - -1. After you've created a shared parameter set, open another - test case and add the shared parameter set to that test case. - You can search for the shared parameter set by name. - - ![Adding the shared parameter set to a test case](media/repeat-test-with-different-data/repeat-test-with-different-data-03.png) - - The shared parameter set is displayed in the **Parameter values** - section after you add it. You can now use these parameters in - your test case steps. - -1. If the test case has different parameter names for - these shared parameters, map the shared parameters to - the local parameters to use the shared parameter data. - - ![Mapping a shared parameter to a local parameter](media/repeat-test-with-different-data/repeat-test-with-different-data-04.png) - - When they are correctly mapped, the data associated with the - shared parameter is displayed. - -1. Add, edit, and rename your shared parameter sets in the - **Parameters** page. View the test cases that reference - them in the **Test cases** pane. - - ![Adding, editing, viewing, and renaming a shared parameter](media/repeat-test-with-different-data/repeat-test-with-different-data-05.png) - -1. Each shared parameter set is a work item. Open the **Properties** - page to view or make changes to this work item. For example, - you can assign owners and track changes. - -You can't add more than one shared parameter set to a single test case. If two test cases share similar data, for example, one test case needs -customer ID, name, email, and phone, and the second needs customer ID, name and address, you might consider creating a single shared parameter set -containing all of the parameters - even though a few of the columns in the set will remain unused in each test case. +If two test cases share similar data, you might consider creating a single shared parameter set, which contains all of the parameters, even though a few of the columns in the set remain unused in each test case. For example, one test case needs customer ID, name, email, and phone, and the second needs customer ID, name and address. You can import parameter values from an Excel spreadsheet to your shared parameter sets. Paste the values into your shared parameters grid. @@ -142,15 +84,14 @@ You can also copy the data from your grid back into Excel. ## Run a test case with parameters ::: moniker range=">=azure-devops-2020" -You can run a test case that uses parameters. +Do the following steps to run a test case that uses parameters. 1. Select a test case with parameters and start running it. The Test Runner shows the first row of parameter values. ![Screenshot shows Test Runner displaying the first row of parameter values.](media/repeat-test-with-different-data/run-test-case-parameters.png) -1. When you've completed the steps, mark the test passed or failed. - Then go on to the next iteration of the test, which uses the next row of parameter values. +1. When you complete the steps, mark the test passed or failed. Go on to the next iteration of the test, which uses the next row of parameter values. ![Screenshot shows going on to the next iteration of the test.](media/repeat-test-with-different-data/next-iteration.png) @@ -161,32 +102,10 @@ You can run a test case that uses parameters. 1. If any of the parameter values are incorrect, fix them without canceling the test by choosing **Edit** from step's shortcut menu. ::: moniker-end -::: moniker range="<=azure-devops-2019" - -1. Select a test case with parameters and start running it. - The Test Runner shows the first row of parameter values. - - ![Test Runner showing the first row of parameter values](media/repeat-test-with-different-data/repeat-test-with-different-data-06.png) - -1. When you've completed the steps, mark the test passed or failed. - Then go on to the next iteration of the test, which uses the next - row of parameter values. - - ![Going on to the next iteration of the test](media/repeat-test-with-different-data/repeat-test-with-different-data-07.png) - -1. Use the drop-down to navigate to other iterations. - - ![Navigating to other iterations](media/repeat-test-with-different-data/repeat-test-with-different-data-08.png) - -1. If any of the parameter values are incorrect, fix them - without canceling the test by choosing **Edit** from step's - shortcut menu. -::: moniker-end - ## Review the test results ::: moniker range=">=azure-devops-2020" -The outcome of the test is based on a precedence hierarchy of all the iteration outcomes. The hierarchy order is Paused, Failed, Blocked, Passed, Not Applicable, and Unspecified (Active). For example, if you marked any iteration as failed and all the rest as passed, the outcome of the entire test is shown as failed. This result is different from test cases that don't have parameters, where the outcome displays the status of the last run. +The outcome of the test is based on a precedence hierarchy of all the iteration outcomes. The hierarchy order is Paused, Failed, Blocked, Passed, Not Applicable, and Unspecified (Active). For example, if you marked any iteration as *failed* and all the rest as *passed*, the outcome of the entire test shows as *failed*. This result is different from test cases that don't have parameters, where the outcome displays the status of the last run. To review test results, from the **Execute** tab, select a test point. Select **More options** or right-click to open the context menu. Select **View test results**. @@ -197,43 +116,6 @@ You can view the results in the **Test Case Results** dialog box. ![Screenshot shows test results for a test point.](media/repeat-test-with-different-data/view-test-results.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" - -The outcome of the test is based on a precedence hierarchy of all the iteration outcomes. The hierarchy order is Paused, Failed, Blocked, Passed, Not Applicable, and Unspecified (Active). For example, if you marked any iteration as failed and all the rest as passed, the outcome of the entire test is shown as failed. This is different from test cases that do not have parameters, where the outcome displays the status of the last run. - -1. Check the test result by opening the details pane. - - ![Checking the test result in the details pane](media/repeat-test-with-different-data/repeat-test-with-different-data-09.png) - -1. Double-click a test result to view the test run details, - and the test results for each iteration. - - ![Viewing the test run details](media/repeat-test-with-different-data/repeat-test-with-different-data-10.png) -::: moniker-end - -## Speed up test iterations by using record and playback - -It can be error-prone and tedious to work through a long table of -parameter combinations. To speed up things, create an action -recording when you run the test with the first set of parameter -values, and then play it back for the other sets. - -1. Use Azure Test Plans to [run the test](run-manual-tests.md). - -1. Select **Create action recording** before you choose **Start**. - -1. Complete the first test iteration and then move on to the next one. - -1. Mark each step as passed or failed as you work. Enter parameter - values in the application exactly as displayed in the test script. - -1. Choose **Play** to run the test with the next set of parameter values. - Your actions will be played back automatically, but you must still - verify the results. - -Record and playback doesn't work with all applications. -For details, see [Supported configurations and platforms for coded UI tests and action recordings](/visualstudio/test/supported-configurations-and-platforms-for-coded-ui-tests-and-action-recordings). - ## Related articles * [FAQs for manual testing](reference-qa.yml#repeatdifferent) diff --git a/docs/test/request-stakeholder-feedback.md b/docs/test/request-stakeholder-feedback.md index 057b68f4b49..0e2c7c805c4 100644 --- a/docs/test/request-stakeholder-feedback.md +++ b/docs/test/request-stakeholder-feedback.md @@ -5,46 +5,48 @@ ms.assetid: 6AE1D62D-43EE-4C0B-92CD-F11BC10A9CA8 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra ms.date: 12/07/2018 monikerRange: '<= azure-devops' --- -# Request stakeholder feedback using the Test & Feedback extension +# Request stakeholder feedback using the Test & Feedback extension [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [feedback-header-text](includes/feedback-header-text.md)] +## Prerequisites + +| Category | Requirement | +|--------------|-------------| +| **Project access** | [Project member](../organizations/security/add-users-team-project.md). | +| **Access levels** | To request or provide feedback: At least **Stakeholder** access. | +| **Extensions** |[Test & Feedback extension](perform-exploratory-tests.md).| + ## Request feedback from stakeholders +[!INCLUDE [important-note-request-feedback-unavailable](includes/important-note-request-feedback-unavailable.md)] + Request feedback from stakeholders directly from an Azure DevOps work item. 1. Open the work item form for the user story or feature for which you want to request feedback. -1. Open the shortcut menu from the ellipses (**...**) and choose **Request feedback**. +2. Open the shortcut menu from the ellipses (**...**) and select **Request feedback**. - ![Choosing the Request feedback option](media/request-stakeholder-feedback/request-stakeholder-feedback-01.png) + ![Screenshot shows choosing the Request feedback option.](media/request-stakeholder-feedback/request-stakeholder-feedback-01.png) -1. Type or select the names of the stakeholder(s) you want to send - the request to, and optionally add any instructions or notes that - will help them provide meaningful feedback. +3. Enter or select the names of the stakeholder(s) you want to send the request to, and optionally add any instructions or notes that help them provide meaningful feedback. - ![Selecting users and entering instructions](media/request-stakeholder-feedback/request-stakeholder-feedback-02.png) - -1. Choose **Send** to generate emails to all the selected stakeholders. + ![Screenshot shows selecting users and entering instructions.](media/request-stakeholder-feedback/request-stakeholder-feedback-02.png) -> [!IMPORTANT] -> The **Request feedback** shortcut menu is unavailable in [New Boards Hub](https://aka.ms/newboardshub). However, there are alternative ways to request feedback, such as through email and chat, in addition to utilizing the [Test & Feedback extension](./voluntary-stakeholder-feedback.md). +4. Select **Send** to generate emails to the selected stakeholders. -> [!NOTE] -> Teams can request feedback from other team members, such as users having Basic access. -> Just add their names in the feedback request form so that a **Request feedback** email is sent to them. -> Also see [Can users with Basic access respond to feedback requests](provide-stakeholder-feedback.md#non-stakeholder-feedback). +Teams can request feedback from other team members, such as users having Basic access. Just add their names in the feedback request form so that a **Request feedback** email gets sent to them. Also see [Can users with Basic access respond to feedback requests](provide-stakeholder-feedback.md#non-stakeholder-feedback). ## Related articles @@ -52,7 +54,4 @@ Request feedback from stakeholders directly from an Azure DevOps work item. * [Voluntary stakeholder feedback using the Test & Feedback extension](voluntary-stakeholder-feedback.md#voluntary) * [Track stakeholder feedback using the Test & Feedback extension](track-stakeholder-feedback.md#track) * [Exploratory test and submit feedback directly from your browser](perform-exploratory-tests.md) -* [Overview of manual and exploratory testing](index.yml) - - - +* [Overview of manual and exploratory testing](index.yml) \ No newline at end of file diff --git a/docs/test/run-automated-tests-from-test-hub.md b/docs/test/run-automated-tests-from-test-hub.md index 9a577b52003..9e8ed2a2851 100644 --- a/docs/test/run-automated-tests-from-test-hub.md +++ b/docs/test/run-automated-tests-from-test-hub.md @@ -1,12 +1,12 @@ --- title: Run automated tests from test plans -description: Run automated tests on-demand against Team Foundation builds from test plans in the Test Manager with a build or release pipeline +description: Run automated tests on-demand against Team Foundation builds from test plans in the Test Manager with a build or release pipeline. ms.assetid: 2886C58B-0F4B-4C0C-A248-3980CA629FD8 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: wisdeom monikerRange: '<= azure-devops' ms.date: 09/14/2021 --- @@ -15,270 +15,176 @@ ms.date: 09/14/2021 [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Automate test cases in your test plans and run them directly from **Azure Test Plans** . Automated tests provide you with the following benefits: +Automate test cases in your test plans and run them directly from **Azure Test Plans**. Automated tests provide you with the following benefits: -* A user-friendly process for testers who may not be well - versed with running tests in Build or Release workflows. -* The flexibility to run selected tests on demand, - rather than scheduled testing in Build or Release workflows - where all tests meeting the filter criteria are run. -* The ability to rerun a few tests that failed due - to test infrastructure issues, or you have a new build that - includes fixes for failed tests. +* A user-friendly process for testers who might not be well versed with running tests in Build or Release workflows. +* The flexibility to run selected tests on demand, rather than scheduled testing in Build or Release workflows where all tests meeting the filter criteria are run. +* The ability to rerun a few tests that failed due to test infrastructure issues, or you have a new build that includes fixes for failed tests. -[!INCLUDE [prerequisites-define](includes/prerequisites-run.md)] +## Prerequisites -In addition, you'll need: +| Category | Requirements | +|--------------|-------------| +| **Access levels** | - At least **Basic** access, with permissions to view work items under the corresponding Area Path.
      - To add test plans and test suites, delete test artifacts, and define test configurations: [Basic + Test Plans](https://marketplace.visualstudio.com/items?itemName=ms.vss-testmanager-web) access.
      Or, one of the following **Visual Studio subscriptions**:
      - [Enterprise](https://visualstudio.microsoft.com/vs/enterprise/)
      - [Test Professional](https://visualstudio.microsoft.com/vs/test-professional/)
      - [MSDN Platforms](https://visualstudio.microsoft.com/msdn-platforms/) | +| **Permissions** | - To add or modify test plans, test suites, test cases, or other test-based work item types: **Edit work items in this node** permission set to **Allow** under the corresponding **Area Path**.
      - To modify test plan properties such as build and test settings: **Manage test plans** permission set to **Allow** under the corresponding **Area Path**.
      - to create and delete test suites, add and remove test cases from test suites, change test configurations associated with test suites, and modify a test suite hierarchy (move a test suite): **Manage test suites** permission set to **Allow** under the corresponding **Area Path**.
      - Permissions to create and manage releases, edit a release environment, and manage deployment. For more information, see [Release permissions](../pipelines/policies/permissions.md#release-pipeline-permissions) | +|**Tools and configurations** |- A [test plan](create-a-test-plan.md) that contains your automated tests associated with automated test methods using [Visual Studio 2017](associate-automated-test-with-test-case.md) or [Visual Studio 2015 or earlier](/previous-versions/visualstudio/visual-studio-2013/dd380741(v=vs.120)).
      - A [build pipeline](../pipelines/apps/aspnet/build-aspnet-4.md) that generates builds containing the test binaries.
      - An app to test. You can deploy the app as part of the [build and release workflow](../pipelines/get-started/what-is-azure-pipelines.md) and also use it for on-demand testing.| -- A [test plan](create-a-test-plan.md) - containing your automated tests, which you have associated with automated test methods using - [Visual Studio 2017](associate-automated-test-with-test-case.md), - or [Visual Studio 2015 or earlier](/previous-versions/visualstudio/visual-studio-2013/dd380741(v=vs.120)). -- A [build pipeline](../pipelines/apps/aspnet/build-aspnet-4.md) - that generates builds containing the test binaries. -- An app to test. You can deploy the app as part of the - [build and release workflow](../pipelines/get-started/what-is-azure-pipelines.md) and also use it for on-demand testing. -- Permissions to create and manage releases, edit a release environment, and manage deployment. For more information, see [Set permissions for release pipelines](../pipelines/policies/set-permissions.md) and [Release permissions](../pipelines/policies/permissions.md#set-release-permissions). ## Set up your environment -1. In the **Test Plans** page, choose your test plan, - open the shortcut menu, and choose **Test plan settings**. +1. In the **Test Plans** page, choose your test plan, open the shortcut menu, and then select **Test plan settings**. - ![Choosing Test plan settings](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-101.png) + ![Screenshot shows choosing Test plan settings.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-101.png) -2. In the Test plan settings dialog, select the build pipeline that generates builds which +2. In the Test plan settings dialog, select the build pipeline that generates builds that contain the test binaries. You can then select a specific build number to test, or let the system automatically use the latest build when tests are run. - ![Selecting the build and build number](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-102.png) + ![Screenshot shows selecting the build and build number.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-102.png) -3. You will need a release pipeline that was created from the - **Run automated tests from Test Manager** template to run tests from test plans - in **Azure Test Plans** . If you have an existing release pipeline that was created - using this template, select it and then select the existing stage in the - release pipeline where the tests will be executed. - Otherwise, choose the **Create new** link in the - dialog to create a new release pipeline containing a single stage - with the **Visual Studio Test** task already added. +3. You need a release pipeline that was created from the **Run automated tests from Test Manager** template to run tests from test plans in **Azure Test Plans**. If you have an existing release pipeline created using this template, select it and then select the existing stage in the release pipeline for the test execution. Otherwise, select **Create new** in the dialog to create a new release pipeline that contains a single stage with the **Visual Studio Test** task already added. - ![Selecting a release pipeline or creating a new one](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-102a.png) + ![Screenshot shows selecting a release pipeline or creating a new one.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-102a.png) [How do I pass parameters to my test code from a build or release pipeline?](#pass-params) 4. Assign meaningful names to the release pipeline and stage as required. -5. You need the Visual Studio Test Platform to be installed on the agent computer. - If Visual Studio is already installed on the agent computer, you can skip this step. - If not, you must add the [Visual Studio Test Platform Installer task](/azure/devops/pipelines/tasks/reference/deploy-visual-studio-test-agent-v2) +5. If Visual Studio is already installed on the agent computer, skip this step. + If not, add the [Visual Studio Test Platform Installer task](/azure/devops/pipelines/tasks/reference/deploy-visual-studio-test-agent-v2) to the pipeline definition. 6. Add the [Visual Studio Test task](/azure/devops/pipelines/tasks/reference/vstest-v2) to the release pipeline and configure it as follows: - * Verify that version 2 of the Visual Studio Test task is selected. - The version number is shown in the drop-down list at the top left - of the task settings panel. + * Verify that version 2 of the Visual Studio Test task is selected. The version number is shown in the drop-down list of the task settings panel. - ![Checking the task version number setting](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-03.png) + ![Screenshot shows checking the task version number setting.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-03.png) * Verify that **Select tests using** is set to **Test run**. [What does this setting mean?](#faq-ondemandruns) - ![Checking the test selection method setting](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-02.png) + ![Screenshot shows checking the test selection method setting.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-02.png) * For the **Test platform version** setting, select **Installed by Tools Installer**. - ![Setting the installer option](media/run-automated-tests-from-test-hub/set-installer.png) + ![Screenshot shows setting the installer option.](media/run-automated-tests-from-test-hub/set-installer.png) - * If you have UI tests that run on **physical browsers** or **thick clients**, - ensure that the agent is set to run as an interactive process with - auto-logon enabled. Setting up an agent to run interactively must be - done before queueing the build or release (setting the **Test mix - contains UI tests** checkbox does not configure the agent in interactive - mode automatically - it is used only as a reminder to configure - the agent appropriately to avoid failures). + * If you have UI tests that run on **physical browsers** or **thick clients**, ensure that the agent is set to run as an interactive process with autologon enabled. You must set up an agent to run interactively before you queue the build or release. The **Test mix contains UI tests** checkbox doesn't configure the agent in interactive mode automatically - used only as a reminder to configure the agent appropriately to avoid failures. + * If you're running UI tests on a **headless browser**, the interactive process configuration isn't required. + * Select how the test platform gets provisioned, and the version of Visual Studio or the location of the test platform that is installed on the test machines. + * If your tests need **input parameters** such as app URLs or database connection strings, select the relevant settings file from the build artifacts. You can use the **Publish build artifacts** tasks in your build pipeline to publish the settings file in a drop location if this file isn't included in the artifacts. In the following example, the application URL is exposed in the run settings file, and is overridden to set it to a staging URL using the **Override test run parameters** setting. - * If you are running UI tests on a **headless browser**, the interactive process - configuration is not required. - - * Select how is the test platform is provisioned, and the version of - Visual Studio or the location of the test platform that is installed - on the test machines - - * If your tests need **input parameters** such as app URLs or database - connection strings, select the relevant settings file from the - build artifacts. You can use the **Publish build artifacts** tasks - in your build pipeline to publish the settings file in a drop - location if this file is not included in the artifacts. - In the example shown below, the application URL is exposed in the - run settings file, and is overridden to set it to a staging URL - using the **Override test run parameters** setting. - - ![Specifying the properties for the Visual Studio Test task](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-06.png) + ![Screenshot shows specifying the properties for the Visual Studio Test task.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-06.png) For information about the option settings of the Visual Studio Test task, see [Visual Studio Test task](/azure/devops/pipelines/tasks/reference/vstest-v2). -7. Choose the **Agent job** item and verify that the deployment queue - is set to the one containing the machines where you want to run the - tests. If your tests require special machines from the agent pool, - you can add demands that will select these at runtime. +7. Choose the **Agent job** item and verify that the deployment queue is set to the one containing the machines where you want to run the tests. If your tests require special machines from the agent pool, you can add demands that select at runtime. - ![Specifying the properties for the Agent job](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-04.png) + ![Screenshot shows specifying the properties for the Agent job.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-04.png) - You may be able to minimize test times by distributing tests across multiple - agents by setting **Parallelism** to **Multiple executions** and specifying the number of agents. + You might be able to minimize test times by distributing tests across multiple agents by setting **Parallelism** to **Multiple executions** and specifying the number of agents. > [!NOTE] - > If you are running UI tests such as CodeUI or Selenium - > on physical browsers such as IE, Firefox, or Chrome, the agent - > on the machines must be running in interactive mode and not - > as a service. [More details](#faq-agentmode). + > If you're running UI tests such as CodeUI or Selenium on physical browsers such as IE, Firefox, or Chrome, the agent on the machines must be running in interactive mode and not as a service. [More details](#faq-agentmode). -8. In the **Pipeline** page of the release pipeline, verify - that the build pipeline containing the test binaries is linked - to this release pipeline as an artifact source. +8. In the **Pipeline** page of the release pipeline, verify that the build pipeline containing the test binaries links to this release pipeline as an artifact source. - ![Verifying the linked build artifacts](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-106.png) + ![Screenshot shows verifying the linked build artifacts.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-106.png) -9. Save the release pipeline. +9. **Save** the release pipeline. -10. If you chose **Create new** in the Test plan settings dialog in step 2 - of this example, return to the browser page containing your test plan - settings. In the Test plan settings dialog, select the release pipeline - and stage you just saved. +10. If you chose **Create new** in the Test plan settings dialog in step 2 of this example, return to the browser page that contains your test plan settings. In the Test plan settings dialog, select the release pipeline and stage you saved. - ![Selecting the release pipeline and stage](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-107.png) + ![Screenshot shows selecting the release pipeline and stage.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-107.png) ## Run the automated tests 1. In the **Test Plans** web portal, open the test plan and select a test suite that contains the automated tests. -2. Select the test(s) you want to run, open the **Run** menu, - and choose **Run test**. +2. Select the test(s) you want to run, open the **Run** menu, and then select **Run test**. - ![Selecting Run test](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-108.png) + ![Screenshot shows selecting Run test.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-108.png) - The test binaries for these tests must be available - in the build artifacts generated by your build pipeline. + The test binaries for these tests must be available in the build artifacts generated by your build pipeline. -3. Choose **OK** to start the testing process. The system checks that only - automated tests are selected (any manual tests are ignored), - validates the stage to ensure the Visual Studio Test - task is present and has valid settings, checks the user's - permission to create a release for the selected release - pipeline, creates a test run, and then triggers the creation - of a release to the selected stage. +3. Select **OK** to start the testing process. The system checks that only automated tests get selected (any manual tests are ignored), validates the stage to ensure the Visual Studio Test task is present and has valid settings, checks the user's permission to create a release for the selected release pipeline, creates a test run, and then triggers the creation of a release to the selected stage. - ![Starting the test execution](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-109.png) + ![Screenshot shows starting the test execution.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-109.png) -4. Choose **View test run** to view the test progress and analyze - the failed tests. Test results have the relevant information - for debugging failed tests such as the error message, stack trace, - console logs, and attachments. +4. Select **View test run** to view the test progress and analyze the failed tests. Test results have the relevant information for debugging failed tests such as the error message, stack trace, console logs, and attachments. -5. After test execution is complete, the **Runs** page of the - **Azure Test Plans** shows the test results. The **Run summary** page - shows an overview of the run. +5. After test execution is complete, the **Runs** page of the **Azure Test Plans** shows the test results. The **Run summary** page shows an overview of the run. - ![Viewing the test run summary](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-110.png) + ![Screenshot shows the test run summary.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-110.png) - There is a link to the **Release** used to run the tests, which - makes it easy to find the release that ran the tests if you need - to come back later and analyze the results. Also use this link if you - want to open the release to view the release logs. + There's a link to the **Release** used to run the tests, which makes it easy to find the release that ran the tests if you need to come back later and analyze the results. Also use this link if you want to open the release to view the release logs. - **Note** : Manually attaching of files is not supported for automated test results. + > [!NOTE] + > Manually attachment of files isn't supported for automated test results. [What are the typical error scenarios or issues I should look out for if my tests don't run?](#faq-errors) -6. The **Test results** page lists the results for each test in the - test run. Select a test to see debugging information for failed - tests such as the error message, stack trace, console logs, and attachments. +6. The **Test results** page lists the results for each test in the test run. Select a test to see debugging information for failed tests such as the error message, stack trace, console logs, and attachments. - ![Viewing the test results details](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-111.png) + ![Screenshot shows viewing the test results details.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-111.png) 7. Open the **Test Plans** page and select the test plan to see the status of your tests if tests are updated after test execution is complete. Select a test to see the recent test results. - ![Viewing the test plan](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-112.png) + ![Screenshot shows viewing the test plan.](media/run-automated-tests-from-test-hub/run-auto-tests-from-hub-112.png) ## FAQ +See the following frequently asked questions (FAQs) about Azure Test Plans. + ### Q: What permissions do I need to run automated tests from Azure Test Plans? -You must be a Project Contributor, or have the following permissions: +**A:** Be a Project Contributor, or have the following permissions: * Create releases * Manage releases * Edit release stage * Manage deployment -For more information, see [Set permissions for release pipelines](../pipelines/policies/set-permissions.md) and -[Release permissions](../pipelines/policies/permissions.md#set-release-permissions). +For more information, see [Release permissions](../pipelines/policies/permissions.md#release-pipeline-permissions). ### Q: Can I override the build or stage set at the test plan level for a specific instance of test run? **A:** Yes, you can do this using the **Run with options** command. -Open the shortcut menu for the test suite in the left column and choose -**Run with options**. +Open the shortcut menu for the test suite in the left column and select **Run with options**. -![Configuring the Run with options dialog](media/run-auto-tests-from-hub-08.png) +![Screenshot shows configuring the Run with options dialog.](media/run-auto-tests-from-hub-08.png) -Enter the following values in the Run with options dialog and then choose **OK**: +Enter the following values in the Run with options dialog and then select **OK**: * **Test type and runner**: Select **Automated tests using Release Stage**. - -* **Build**: Select the build that has the test binaries. The test results will be associated this build. - -* **Release Pipeline**: Select a pipeline from the list of release pipelines that can consume the selected build artifact. - +* **Build**: Select the build that has the test binaries. The test results are associated with this build. +* **Release Pipeline**: Select a pipeline from the list of release pipelines that can consume the selected build artifact. * **Release Stage**: Select the name of the stage configured in your release pipeline.

      -![Configured Run with options dialog.](media/run-auto-tests-from-hub-09a.png) +![Screenshot shows configured Run with options dialog.](media/run-auto-tests-from-hub-09a.png) ### Q: Why use release stages to run tests? -**A:** Azure Pipelines offers a compelling orchestration workflow -to obtain test binaries as artifacts and run tests. This workflow shares -the same concepts used in the scheduled testing workflow, meaning users -running tests in scheduled workflow will find it easy to adapt; for -example, by cloning an existing scheduled testing release pipeline. +**A:** Azure Pipelines offers a compelling orchestration workflow to obtain test binaries as artifacts and run tests. This workflow shares the same concepts used in the scheduled testing workflow, meaning users running tests in scheduled workflow find it easy to adapt; for example, by cloning an existing scheduled testing release pipeline. -Another major benefit is the availability of a rich set of tasks in -the task catalog that enable a range of activities to be performed before -and after running tests. Examples include preparing and cleaning test data, -creating and cleaning configuration files, and more. +Another major benefit is the availability of a rich set of tasks in the task catalog that enable a range of activities to be performed before and after running tests. Examples include preparing and cleaning test data, creating and cleaning configuration files, and more. + ### Q: How does selecting "Test run" in the Visual Studio Test task version 2 work? -**A:** The Test management sub-system uses the test run object to -pass the list of tests selected for execution. The test task looks -up the test run identifier, extracts the test execution information -such as the container and test method names, runs the tests, updates -the test run results, and sets the test points associated with the -test results in the test run. From an auditing perspective, the -Visual Studio task provides a trace from the historical releases -and the test run identifiers to the tests that were submitted for -on-demand test execution. +**A:** The Test management subsystem uses the test run object to pass the list of tests selected for execution. The test task looks up the test run identifier, extracts the test execution information such as the container and test method names, runs the tests, updates the test run results, and sets the test points associated with the test results in the test run. From an auditing perspective, the Visual Studio task provides a trace from the historical releases and the test run identifiers to the tests that were submitted for on-demand test execution. + ### Q: Should the agent run in interactive mode or as a service? -**A:** If you are running UI tests such as -[coded UI](/visualstudio/test/use-ui-automation-to-test-your-code) -or [Selenium](../pipelines/test/continuous-test-selenium.md) tests, -the agent on the test machines must be running in interactive mode with auto-logon enabled, -not as a service, to allow the agent to launch a web browser. -If you are using a headless browser such as [PhantomJS](https://phantomjs.org/), -the agent can be run as a service or in interactive mode. See -[Build and release agents](../pipelines/agents/agents.md), -[Deploy an agent on Windows](../pipelines/agents/windows-agent.md), -and [Agent pools](../pipelines/agents/pools-queues.md). +**A:** If you run UI tests such as [coded UI](/visualstudio/test/use-ui-automation-to-test-your-code) or [Selenium](../pipelines/test/continuous-test-selenium.md) tests, the agent on the test machines must be running in interactive mode with autologon enabled, not as a service, to allow the agent to launch a web browser. If you're using a headless browser such as [PhantomJS](https://phantomjs.org/), the agent can be run as a service or in interactive mode. For more information, see [Build and release agents](../pipelines/agents/agents.md), [Deploy an agent on Windows](../pipelines/agents/windows-agent.md), and [Agent pools](../pipelines/agents/pools-queues.md). ### Q: Where can I find detailed documentation on how to run Selenium tests? @@ -286,38 +192,30 @@ and [Agent pools](../pipelines/agents/pools-queues.md). ### Q: What happens if I select multiple configurations for the same test? -**A:** Currently, the on-demand workflow is not configuration-aware. +**A:** Currently, the on-demand workflow isn't configuration-aware. ### Q: What if I need to download product binaries and test binaries from different builds? Or if I need to obtain artifacts from a source such as Jenkins? **A:** The current capability is optimized for a single team build to be tested on-demand using an Azure Pipelines workflow. -We will evaluate support for multi-artifact releases, including +We evaluate support for multi-artifact releases, including non-Azure Pipelines artifacts such as Jenkins, based on user feedback. -### Q: I already have a scheduled testing release pipeline. Can I reuse the same pipeline to run test on-demand, or should I create a new pipeline as shown above? +### Q: I already have a scheduled testing release pipeline. Can I reuse the same pipeline to run test on-demand, or should I create a new pipeline? **A:** We recommend you use a separate release pipeline and stage for on-demand automated testing from Azure Test Plans because: -* You may not want to deploy the app every time you want to run a few on-demand tests. +* You might not want to deploy the app every time you want to run a few on-demand tests. Scheduled testing stages are typically set up to deploy the product and then run tests. -* New releases are triggered for every on-demand run. If you have many -testers executing a few on-demand test runs every day, your scheduled -testing release pipeline could be overloaded with releases for these -runs, making it difficult to find releases that were triggered for the -pipeline that contains scheduled testing and deployment to production. +* New releases are triggered for every on-demand run. If you have many testers who execute a few on-demand test runs every day, your scheduled testing release pipeline could be overloaded with releases for these runs, making it difficult to find releases that trigger for the pipeline that contains scheduled testing and deployment to production. -* You may want to configure the Visual Studio Test task with a Test run -identifier as an input so that you can trace what triggered the release. -See [How does selecting "Test run (for on-demand runs)" in the Visual Studio Test task work?](#faq-ondemandruns). +* You might want to configure the Visual Studio Test task with a Test run identifier as an input so that you can trace what triggered the release. For more information, see [How does selecting "Test run (for on-demand runs)" in the Visual Studio Test task work?](#faq-ondemandruns). ### Q: Can I trigger these runs and view the results in Microsoft Test Manager? -**A:** No. Microsoft Test Manager will not support running automated tests against Team Foundation -builds. It only works in the web-based interface for Azure Pipelines and TFS. -All new manual and automated testing product development investments will be -in the web-based interface. No further development is planned for Microsoft Test Manager. See +**A:** No. Microsoft Test Manager doesn't support running automated tests against Team Foundation +builds. It only works in the web-based interface for Azure Pipelines. All new manual and automated testing product development investments are in the web-based interface. No further development is planned for Microsoft Test Manager. See [Guidance on Microsoft Test Manager usage](/previous-versions/azure/devops/test/mtm/guidance-mtm-usage). ### Q: I have multiple testers in my team. Can they run tests from different test suites or test plans in parallel using the same release pipeline? @@ -325,75 +223,57 @@ in the web-based interface. No further development is planned for Microsoft Test **A:** They can use the same release pipeline to trigger multiple test runs in parallel if: -* The agent pool associated with the stage has sufficient agents -to cater for parallel requests. If sufficient agents are not available, -runs can still be triggered but releases will be queued for processing -until agents are available. +* The agent pool associated with the stage has sufficient agents to cater for parallel requests. If sufficient agents aren't available, runs can still be triggered but releases queue for processing until agents become available. -* You have sufficient jobs to enable parallel jobs. -See [Parallel jobs in Azure Pipelines](../pipelines/licensing/concurrent-jobs.md) -or [Parallel jobs in TFS](../pipelines/licensing/concurrent-pipelines-tfs.md) for more information. +* You have sufficient jobs to enable parallel jobs. For more information, see [Parallel jobs in Azure Pipelines](../pipelines/licensing/concurrent-jobs.md) or [Parallel jobs in TFS](../pipelines/licensing/concurrent-pipelines-tfs.md). -* Testers do not run the same tests in parallel. Doing so may cause -results to be overwritten depending on the order of execution. +* Testers don't run the same tests in parallel. Doing so might cause results to be overwritten depending on the order of execution. -To enable multiple different test runs to execute in parallel, set the Azure Pipelines stage trigger option for -[behavior when multiple releases are waiting to be deployed](../pipelines/release/triggers.md#env-triggers) -as follows: +To enable multiple different test runs to execute in parallel, set the Azure Pipelines stage trigger option for [behavior when multiple releases are waiting to be deployed](../pipelines/release/triggers.md) as follows: -* If your application supports tests running in parallel from different -sources, set this option to -**Allow multiple releases to be deployed at the same time**. +* If your application supports tests running in parallel from different sources, set this option to **Allow multiple releases to be deployed at the same time**. -* If your application does not support tests running in parallel -from different sources, set this option to -**Allow only one active deployment at a time**. +* If your application doesn't support tests running in parallel from different sources, set this option to **Allow only one active deployment at a time**. + ### Q: How do I pass parameters to my test code from a build or release pipeline? -A: Use a [runsettings](/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file) -file to pass values as parameters to your test code. For example, in a release that contains several stages, -you can pass the appropriate app URL to each the test tasks in each one. The runsettings file and matching parameters -must be specified in the [Visual Studio Test task](/azure/devops/pipelines/tasks/reference/vstest-v2). +**A:** Use a [runsettings](/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file) +file to pass values as parameters to your test code. For example, in a release that contains several stages, you can pass the appropriate app URL to each the test tasks in each one. The runsettings file and matching parameters must be specified in the [Visual Studio Test task](/azure/devops/pipelines/tasks/reference/vstest-v2). -![Pass parameters to test code from a build or release pipeline](media/pass-params-to-test-code.png) +![Screenshot shows passing parameters to test code from a build or release pipeline.](media/pass-params-to-test-code.png) + ### Q: What are the typical error scenarios or issues I should look out for if my tests don't run? **A:** Check and resolve issues as follows: * The release pipeline and stage in which I want to run tests - are not shown after I select the build. + aren't shown after I select the build. - Make sure the build pipeline that is generating the build is linked as the primary artifact in the **Artifacts** tab of the release pipeline.

      * I get an error that I don't have sufficient permission to trigger a release. - Configure **Create releases** and **Manage deployments** permissions for the user in the **Security** menu of the release pipeline. - See [Release permissions](../pipelines/policies/permissions.md#set-release-permissions).

      + See [Release permissions](../pipelines/policies/permissions.md#release-pipeline-permissions).

      * I get an error that no automated tests were found. - - Check the automation status of the selected tests. Do this in the work item - for the test case, or use the **Column options** link in **Azure Test Plans** - to add the **Automation status** column to the list - of tests. See the [pre-requisites section](run-automated-tests-from-test-hub.md#prerequisites) for information - about automating manual tests.

      + - Check the automation status of the selected tests. Do so in the work item for the test case, or use the **Column options** link in **Azure Test Plans** to add the **Automation status** column to the list of tests. For more information, see the [prerequisites section](run-automated-tests-from-test-hub.md#prerequisites). * My tests didn't execute, and I suspect the release pipeline is incorrect. - - Use the link in the **Run summary** page to access the release instance - used to run the tests, and view the release logs.

      + - Use the link in the **Run summary** page to access the release instance used to run the tests, and view the release logs.

      * My tests go into the error state, or remain "in-progress" even after release to the stage is triggered. - Check if the release stage that you selected has the correct task and version selected. You must use version 2 or higher of the **Visual Studio Test** task. Version 1 of the task, and the **Run Functional Tests** task, - are not supported.

      + aren't supported.

      -## See Also +## Related articles * [Associate automated tests with test cases](associate-automated-test-with-test-case.md) * [Associate automated test results with requirements](../pipelines/test/requirements-traceability.md) * [Continuous testing scenarios and capabilities](index.yml) - diff --git a/docs/test/run-manual-tests.md b/docs/test/run-manual-tests.md index e505540f5ba..1a097136bb7 100644 --- a/docs/test/run-manual-tests.md +++ b/docs/test/run-manual-tests.md @@ -5,10 +5,10 @@ ms.assetid: 616919f3-7339-4813-9dcf-82ead3476b1a ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: quickstart -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' -ms.date: 01/11/2022 +ms.date: 09/11/2024 --- # Run manual tests @@ -65,9 +65,11 @@ The Test Center in the Microsoft Test Manager client is a desktop-based manual t Testers can use it for manual testing needs. For more information, see [Guidance on Microsoft Test Manager usage](/previous-versions/azure/devops/test/mtm/guidance-mtm-usage). To get Microsoft Test Manager, install [Visual Studio Enterprise](https://visualstudio.microsoft.com/downloads/) or [Visual Studio Test Professional](https://visualstudio.microsoft.com/vs/test-professional/). +## Prerequisites + [!INCLUDE [prerequisites-define](includes/prerequisites-run.md)] -[!INCLUDE [prerequisites-define](includes/prerequisites-tcm.md)] +[!INCLUDE [prerequisites-tcm](includes/prerequisites-tcm.md)] @@ -107,29 +109,7 @@ Follow these steps to run tests for web applications. You can also [Create or add to a bug](#create-or-add-to-a-bug). ::: moniker-end -::: moniker range="<=azure-devops-2019" -1. If you haven't already, [create your manual tests](create-test-cases.md#test-cases). - -1. Select a test from a test suite and run it. - - ![Select and run a specific test](media/run-manual-tests/RunTest_2.png) - - Microsoft Test Runner opens and runs in a new browser. - -1. Start the app that you want to test. Your app doesn't have to run on - the same computer as Test Runner. You just use Test Runner to record which - test steps pass or fail while you manually run a test. For example, you - might run Test Runner on a desktop computer and run your Windows 8 store - app that you are testing on a Windows 8 tablet. - - ![Use Microsoft Test Runner to record your test results](media/run-manual-tests/RunTestsStartApp.png) - -1. Mark each test step as either passed or failed based on the expected results. If a test step fails, you can enter a comment on why it failed or - [collect diagnostic data for the test](collect-diagnostic-data.md). You can also [Create or add to a bug](#create-or-add-to-a-bug). - ![Mark test steps](media/run-manual-tests/RunTest_3.png) - -::: moniker-end > [!IMPORTANT] > Any test step that has expected result is called a *validation test step*. Testers must mark a test step with a status if it is a validation test step. The overall result for a test case reflects the status of all the test steps that the tester marked. Therefore, the test case will have a status of failed if the tester marked any test step as failed or not marked. @@ -144,6 +124,19 @@ You can also update an existing bug with information about the failure. ![Screenshot shows Test Runner with a failed test and Create bug highlighted.](media/run-manual-tests/create-bug-button.png) + > [!NOTE] + > + > If the create bug button does not launch bug workitem, then verify if the teams settings are correct at Area and Iteration level as below: + > + > Go to the project settings and Team, check if the correct Team is set as default. + > + > From that Team, click on the Iterations and Area paths hyperlink near to Team name. It will take you to Team configuration page. + > + > In the Team configuration page, select Iterations, Default and Backlog iteration must match the Team for which the test case is running. + > + > In the Team configuration page, select Areas, Default area must match the Team for which the test case is running. + + 1. In the **New bug** dialog box, enter a name for the bug. ![Screenshot shows Test Runner with Create bug selected and the new bug dialog box open.](media/run-manual-tests/create-bug-test-fail.png) @@ -163,26 +156,6 @@ Instead of creating a bug, you can update an existing bug with information about ![Screenshot shows Test Runner with Add to existing bug selected](media/run-manual-tests/find-existing-bug.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -1. In the Test Runner window, select **Create bug**. - - ![Submit a bug.](media/run-manual-tests/RunTest_4.png) - - The steps and your comments are automatically added to the bug. - If Test Runner is running in a web browser window, you can copy a screenshot from the clipboard directly into the bug. - -1. You can assign the bug, enter comments, or link to other issues. Select **Save & Close** when done. - The test case is linked to the bug you created. - -You can see any bugs that you reported during your test session. - -![Bugs logged](media/run-manual-tests/RunTest_5.png) - -Instead of creating a bug, you can update an existing bug with information about this step. -Select the **+** icon for **Create bug**, then **Add to existing bug**. -Find and update an existing bug. -::: moniker-end - ## Save results, close the session, and review results After you complete testing, save your results, close the session, and review test results. @@ -196,9 +169,7 @@ After you complete testing, save your results, close the session, and review tes ::: moniker range=">=azure-devops-2020" ![Screenshot shows the result of running test cases, with outcomes of Active, Failed, and Passed displayed.](media/run-manual-tests/test-case-outcome.png) ::: moniker-end - ::: moniker range="<=azure-devops-2019" - ![Screenshot shows View test results.](media/run-manual-tests/RunTest_8.png) - ::: moniker-end + If you haven't run a test yet, its state is active. Reset the state of a test to active if you want to rerun it. @@ -209,9 +180,7 @@ After you complete testing, save your results, close the session, and review tes ::: moniker range=">=azure-devops-2020" ![Screenshot shows the Related Work section of a work item to view bugs filed for that test.](media/run-manual-tests/related-work-shows-bugs.png) ::: moniker-end - ::: moniker range="<=azure-devops-2019" - ![View bugs filed](media/run-manual-tests/view-bugs.png) - ::: moniker-end + You can run tests offline and then import the results. For more information, see the [Offline Test Execution extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.OfflineTestExecution). @@ -237,31 +206,13 @@ If you want to collect more diagnostic data for your desktop application, run yo ![Screenshot shows the Run for desktop application dialog box with options to download and launch Test Runner.](media/run-manual-tests/tr-atp-launch.png) > [!NOTE] - > Check that the Test Runner client is available for your platform. Currently, the Test Runner client is available only for x64. + > - Check that the Test Runner client is available for your platform. Currently, the Test Runner client is available only for x64. + > - Azure Test Runner might not work if your organization uses a conditional access policy via Microsoft Entra. For more information, see [Conditional access common decisions](/entra/identity/conditional-access/overview#common-decisions) 1. Select **Launch** and start testing as described in the previous section. For more information about data collection, see [Collect diagnostic data while testing](collect-diagnostic-data.md). ::: moniker-end -::: moniker range="<=azure-devops-2019" - -If you want to collect more diagnostic data for your desktop application, run your tests using Test Runner client: - -1. Launch the test runner client from Azure Test Plans by choosing **Run for desktop application** from the **Run** menu. - - ![Launching the test runner client](media/shared/collect-diagnostic-data-16.png) - -1. **Download** and install the [Test Runner desktop client](https://aka.ms/ATPTestRunnerDownload) if you haven't already set it up: - - ![Download and launch Test runner](media/run-manual-tests/tr-atp-launch.png) - - > [!NOTE] - > Check that the Test Runner client is available for your platform. Currently, the Test Runner client is available only for x64. - -1. Choose **Launch** and start testing the same way as [described above](#run-web) for web apps. For more information about data collection, see [Collect diagnostic data while testing](collect-diagnostic-data.md). - -::: moniker-end - ## Run all tests You can run all the tests in a test suite at once. @@ -271,11 +222,6 @@ Select a test suite and select **Run for web application** or **Run for desktop ![Screenshot shows how to select and run all active tests in a test suite.](media/run-manual-tests/run-test-test-suite.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -Select a test suite and select **Run** to run all the active tests. - -![Screenshot shows how to run all active tests in a test suite.](media/run-manual-tests/RunTestsRunSuite.png) -::: moniker-end ## Run tests for a build @@ -290,15 +236,6 @@ Choose a build to run tests against. ![Screenshot shows the Run with options dialog box with a build selected.](media/run-manual-tests/run-test-select-build.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -1. Choose **Run** and then select **Run with options**. - - ![Screenshot shows Run selected and Run with options available.](media/shared/collect-diagnostic-data-16.png) - -1. Select the build you want. - - ![Screenshot shows the Run with options dialog box with a build.](media/run-manual-tests/select-build-for-webrunner.png) -::: moniker-end > [!NOTE] > The selected build must be from the project in which the tests are defined. @@ -323,9 +260,6 @@ Select the **Edit test step** icon. ::: moniker range=">=azure-devops-2020" ![Screenshot shows how to select the edit icon to edit test steps.](media/run-manual-tests/edit-icon-test-run.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -![Screenshot shows how to select the edit icon to modify test steps.](media/run-manual-tests/RunTest_11.png) -::: moniker-end You can insert, reorder, or delete steps. You can also edit the text itself. @@ -333,9 +267,6 @@ You can also edit the text itself. ::: moniker range=">=azure-devops-2020" ![Screenshot shows the tool to edit test steps when you run a test.](media/run-manual-tests/edit-test-step.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -![Screenshot shows the tool to modify test steps when you run a test.](media/run-manual-tests/RunTest_9.png) -::: moniker-end ## Capture rich diagnostic data @@ -351,9 +282,6 @@ For Microsoft Internet Explorer or Microsoft Edge browsers, or for desktop app t ::: moniker range=">=azure-devops-2020" ![Screenshot shows the button for capturing a screenshot during a test.](media/run-manual-tests/test-capture-screen.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -![Screenshot shows the button for capturing a screenshot.](media/shared/collect-diagnostic-data-01.png) -::: moniker-end For more information, see [Collect diagnostic data](collect-diagnostic-data.md#web-screenshot). @@ -367,9 +295,6 @@ For Microsoft Internet Explorer or Microsoft Edge browsers, or for desktop app t ::: moniker range=">=azure-devops-2020" ![Screenshot shows the button for capturing an image action log from the app.](media/run-manual-tests/test-capture-action.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -![Screenshot shows the button to capture an image action log from the app.](media/shared/collect-diagnostic-data-06.png) -::: moniker-end For more information, see [Collect diagnostic data](collect-diagnostic-data.md#web-log). @@ -383,9 +308,6 @@ For Microsoft Internet Explorer or Microsoft Edge browsers, or for desktop app t ::: moniker range=">=azure-devops-2020" ![Screenshot show the button for capturing a screen recording from the app.](media/run-manual-tests/test-capture-screen-recording.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -![Screenshot show the button to capture a screen recording from the app.](media/shared/collect-diagnostic-data-11.png) -::: moniker-end For more information, see [Collect diagnostic data](collect-diagnostic-data.md#web-recording). @@ -395,13 +317,12 @@ You can run tests that are part of a test plan using the TCM command-line tool. [List test runs](#list-test-runs) | [Create test runs](#create-test-runs) | [Execute test runs](#execute-test-runs) | [Abort test runs](#abort-test-runs) | [Delete test runs](#delete-test-runs) | [Export test runs](#export-test-runs) | [Publish test runs](#publish-test-runs) - + ### List test runs Use `tcm run /list` to list the runs available in a test plan and to show their **ID**. The **ID** corresponds to the work item ID defined when the run was created. - ```tcm tcm run /list /collection:teamprojectcollectionurl /teamproject:project [/planid:id | /querytext:query] [/login:username,[password]] @@ -412,11 +333,8 @@ tcm run /list /collection:teamprojectcollectionurl /teamproject:project |**/planid**:`id`| Optional. Indicates that only those test runs associated with the specified test plan are returned in the list. | |**/querytext**:`query`| Optional. Specifies the query to use to list a subset of test runs. | - [!INCLUDE [prerequisites-define](includes/common-tcm-parameters.md)] - - **Example** The following command lists the test runs defined for the *Fabrikam Fiber* project hosted in the *fabrikamprime* organization. The **ID** and **Title** correspond to the work item ID and title defined for the test run. For example, test run *1000052* is titled *Test Plan for Cycle 1 (Manual)*. @@ -435,7 +353,7 @@ Id Title Owner Date Completed 1000060 Game Shopping (Manual) Bukhosi Bhengu 12/6/2021 ``` - + ### Create test runs @@ -477,7 +395,7 @@ Run created with ID: 1000082. ``` - + ### Execute test runs @@ -510,7 +428,7 @@ Failed: 1 Inconclusive: 0 ``` - + ### Abort test runs @@ -524,7 +442,6 @@ tcm run /abort /id:id /collection:teamprojectcollectionurl /teamproject:project |----------|------------| |**/id**:`id`| Specifies the **ID** for the test run that you want to cancel. | - [!INCLUDE [prerequisites-define](includes/common-tcm-parameters.md)] **Example** @@ -537,7 +454,7 @@ tcm run /abort /id:1000082 /collection:https://fabrikamprime.visualstudio.com /t Run with ID [1000082] and title [MyTestRun] has been aborted. ``` - + ### Delete test runs @@ -566,7 +483,7 @@ Are you sure you want to delete run [MyTestRun]? (Yes/No) y Run [MyTestRun] has been deleted. ``` - + ### Export test runs @@ -591,7 +508,7 @@ The following command specifies that the test run with the **ID** *1000082* for tcm run /export /id:1000082 /resultsfile:"c:\temp\ResultsForDeveloper.trx" /collection:https://fabrikamprime.visualstudio.com /teamproject:"Fabrikam Fiber" ``` - + ### Publish test runs @@ -703,6 +620,10 @@ For Microsoft Internet Explorer or Microsoft Edge browsers, or for desktop app t For more information, see [Collect diagnostic data](collect-diagnostic-data.md#web-recording). +### Q: Some of the attachments for the test run are not showing the preview option? + +**A:** You can only preview files with txt and log extensions. Click on the preview option for txt or log extension files, and another UI will open up with the drop down field showing all the attachments for the test run. If you select a file with an extension type other than txt or log, the following message is shown: "You can only preview files with txt and log extensions, click here to download the attachment" + ### Q: How do I control how long I keep my test data? **A:** For more information, see [Set test retention policies](how-long-to-keep-test-results.md). @@ -713,7 +634,15 @@ For more information, see [Collect diagnostic data](collect-diagnostic-data.md#w ### Q: What are the supported operating systems for the Test Runner client? -**A:** The Test Runner desktop client is currently supported only on Windows. +**A:** The Test Runner desktop client is currently supported only on Windows x64 platform. + +### Q: I am observing test run failures when using the Azure Test Runner desktop client. + +**A:** Make sure you are using latest version of Test Runner desktop client. Download the [Test Runner desktop client](https://aka.ms/ATPTestRunnerDownload) + +### Q: Does the Azure Test Runner desktop client work on devices with Microsoft Entra Conditional Access enabled? + +**A:** Azure Test Runner might not work if your organization uses a conditional access policy via Microsoft Entra. For more information, see [Conditional access common decisions](/entra/identity/conditional-access/overview#common-decisions). This is a known limitation and our recommendation is to use web runner in this scenario. ### Q: Can I opt out of telemetry for the Test Runner client? diff --git a/docs/test/share-steps-between-test-cases.md b/docs/test/share-steps-between-test-cases.md index 9a37dc75561..b1f356e1217 100644 --- a/docs/test/share-steps-between-test-cases.md +++ b/docs/test/share-steps-between-test-cases.md @@ -5,8 +5,8 @@ description: Learn how to share steps between test cases when you want to test w ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: how-to -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' ms.date: 12/06/2021 --- @@ -21,20 +21,20 @@ Many manual tests require performing an identical sequence of steps and test dat This article describes how to define and use **Shared Steps**. To learn how to define and reference **Shared Parameters**, see [Repeat a test with different data](repeat-test-with-different-data.md). -[!INCLUDE [prerequisites-define](includes/prerequisites-define.md)] +## Prerequisites -[!INCLUDE [note-new-ui](includes/note-new-ui.md)] - +[!INCLUDE [prerequisites-define](includes/prerequisites-define.md)] + ## Create shared steps ::: moniker range=">=azure-devops-2020" -To create shared steps, follow these steps: +Do the following steps to create shared steps. 1. Select **Test Plans** to view your test plans. Select **Mine** or **All** or **Filter by title** to find a particular test plan. Select the plan to see test cases. -1. Double click a test case to edit it. Under **Steps**, select several steps and then select the **Create shared steps** icon. +1. Double select a test case to edit it. Under **Steps**, select several steps and then select the **Create shared steps** icon. -1. In the **Create shared steps** dialog box, type a name for these shared step, and then select **Create**. +1. In the **Create shared steps** dialog box, enter a name for these shared step, and then select **Create**. ![Screenshot shows the Create Shared Steps dialog box with a name entered.](media/shared-steps/create-shared-steps-name.png) @@ -49,27 +49,12 @@ If you reopen the work item, you can select the shared step to open a new shared ![Screenshot shows the new work item with the shared steps.](media/shared-steps/shared-steps-work-item.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" +You can edit shared steps at any time. Any changes you make appear in every test case where you use the shared steps. -While you're editing a test case, select a sequence of steps that you want to share: - -![Create shared steps](media/shared-steps/create-shared-steps.png) - -The steps you selected are replaced with a link to the new shared steps work item: - -![Resulting test case with a shared step.](media/shared-steps/create-shared-result.png) -::: moniker-end - -You can edit shared steps at any time. -Any changes you make appear in every test case where you use the shared steps. - -You can use parameters in shared steps. -For more information about parameters, see [parameters](repeat-test-with-different-data.md). +You can use parameters in shared steps. For more information about parameters, see [parameters](repeat-test-with-different-data.md). -You provide values for the parameters in the test cases that use the shared steps. -You don't have to provide values in the shared steps definition. -However, you can provide one default row of values. -These values are used when you create an action recording of a standalone shared step. +Provide values for the parameters in the test cases that use the shared steps. You don't have to provide values in the shared steps definition. But, you can provide one default row of values. +These values get used when you create an action recording of a standalone shared step. ## Insert shared steps into other test cases ::: moniker range=">=azure-devops-2020" @@ -88,18 +73,7 @@ You can add shared steps to other test cases. ::: moniker-end -::: moniker range="<=azure-devops-2019" - -Now you can use the shared steps in another test case: - -![Use shared steps in test cases.](media/shared-steps/use-shared-steps.png) - -A query opens. Run it to find the steps you want to insert: - -![Run the query to find shared steps](media/shared-steps/shared-step-query.png) -::: moniker-end - -## Mark shared steps when running a test +## Mark shared steps when you run a test ::: moniker range=">=azure-devops-2020" When you [run a test](run-manual-tests.md), you can either mark the whole shared sequence as passed or failed, or mark each step separately: @@ -108,14 +82,6 @@ When you [run a test](run-manual-tests.md), you can either mark the whole shared ::: moniker-end -::: moniker range="<=azure-devops-2019" - -When you [run a test](run-manual-tests.md), you can either mark the whole shared sequence as passed or failed, or mark each step separately: - -![Shared steps in Test Runner.](media/shared-steps/run-shared-steps.png) - -::: moniker-end - ## Related articles - [Test objects and terms](test-objects-overview.md) diff --git a/docs/test/standalone-mode-exploratory-testing.md b/docs/test/standalone-mode-exploratory-testing.md index 771d52756ca..abe7f225e61 100644 --- a/docs/test/standalone-mode-exploratory-testing.md +++ b/docs/test/standalone-mode-exploratory-testing.md @@ -5,8 +5,8 @@ ms.assetid: 762A75FB-0B6D-47C3-9232-371348D8D529 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: quickstart -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra ms.date: 12/07/2018 monikerRange: '<= azure-devops' --- @@ -15,77 +15,79 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -All teams can use the Test & Feedback extension in **Standalone** mode. -Users don't need an Azure DevOps subscription -or Team Foundation Server connection to use this mode. +All teams can use the Test & Feedback extension in **Standalone** mode. +Users don't need an Azure DevOps subscription to use this mode. + +## Prerequisites + +| Category | Requirement | +|--------------|-------------| +| **Project access** | [Project member](../organizations/security/add-users-team-project.md). | +| **Access levels** | To request or provide feedback: At least **Stakeholder** access. | +| **Extensions** |[Test & Feedback extension](perform-exploratory-tests.md).| + ## Start testing in Standalone mode -1. If you haven't already, [install the Test & Feedback extension](perform-exploratory-tests.md). +1. If you haven't already, [install the Test & Feedback extension](perform-exploratory-tests.md). -1. Open the extension in your web browser and select **Standalone** mode. +2. Open the extension in your web browser and select **Standalone** mode. - ![Start the extension in Standalone mode](media/standalone-mode-exploratory-testing/standalonemode-01.png) + ![Screenshot shows starting the extension in Standalone mode.](media/standalone-mode-exploratory-testing/standalonemode-01.png) -1. Open the web application you want to explore and +3. Open the web application you want to explore and start the testing session. - ![Start recording in Standalone mode](media/standalone-mode-exploratory-testing/standalonemode-02.png) + ![Screenshot shows starting recording in Standalone mode.](media/standalone-mode-exploratory-testing/standalonemode-02.png) -1. When you find an area that has a bug, take a screenshot of the entire screen or any part of it. +4. When you find an area that has a bug, take a screenshot of the entire screen or any part of it. ![Take a screenshot of the application issue](media/standalone-mode-exploratory-testing/standalonemode-03.png) -1. You can annotate the screenshot using the tools available in the inline annotation toolbar. +5. You can annotate the screenshot using the tools available in the inline annotation toolbar. - ![Annotate your screenshot if required](media/standalone-mode-exploratory-testing/standalonemode-04.png) + ![Screenshot show annotating a screenshot.](media/standalone-mode-exploratory-testing/standalonemode-04.png) -1. Make notes about the issue to share with your team, and then save the note. +6. Make notes about the issue to share with your team, and then **Save** the note. - ![Add notes about the issue if required](media/standalone-mode-exploratory-testing/standalonemode-05.png) + ![Screenshot show adding notes about the issue.](media/standalone-mode-exploratory-testing/standalonemode-05.png) + ## Create a bug -1. When you have finished capturing information for an issue, choose **Create bug**. +1. When you finish capturing information for an issue, select **Create bug**. - ![Create a bug from the captured information](media/standalone-mode-exploratory-testing/standalonemode-06.png) + ![Screenshot shows creating a bug from the captured information.](media/standalone-mode-exploratory-testing/standalonemode-06.png) -1. The bug form contains all your captured information. - Enter a title for the bug and add any additional notes - you require to the description. Then save the bug. +2. The bug form contains all your captured information. Enter a title for the bug and add any other notes you require to the description. Then **Save** the bug. - ![Enter a title and description, then save the bug](media/standalone-mode-exploratory-testing/standalonemode-07.png) + ![Screenshot shows entering a title and description to the bug.](media/standalone-mode-exploratory-testing/standalonemode-07.png) -1. View a list of all your activities in reverse chronological - order in the **Session timeline** page. It shows all the - screenshots and notes you've captured and the bugs you've already created. +3. View a list of all your activities in reverse chronological order in the **Session timeline** page. This page shows all the screenshots and notes you captured and the bugs you already created. - ![Review your captured information](media/standalone-mode-exploratory-testing/standalonemode-07a.png) + ![Screenshot shows review of captured information.](media/standalone-mode-exploratory-testing/standalonemode-07a.png) + ## End your testing session -1. Continue exploring the application. Create more bugs as you encounter - issues with the app. +1. Continue to explore the application. Create more bugs as you encounter issues with the app. -1. When you're done, stop your session. +2. When you're done, stop your session. - ![Stop the exploratory testing session](media/standalone-mode-exploratory-testing/standalonemode-08.png) + ![Screenshot shows stopping the exploratory testing session.](media/standalone-mode-exploratory-testing/standalonemode-08.png) - The extension automatically creates a session report that contains - details of all the bugs created during the session, and any attachments. + The extension automatically creates a session report that contains details of all the bugs created during the session, and any attachments. - ![The exploratory testing report](media/standalone-mode-exploratory-testing/standalonemode-09.png) + ![Screenshot show the exploratory testing report.](media/standalone-mode-exploratory-testing/standalonemode-09.png) -1. The report is saved in the default Downloads folder of your web browser. - Share it with the rest of your team as an email attachment, or - copy it to OneNote, Word, or in any other format you prefer. +3. The report saves in the default **Downloads** folder of your web browser. Share it with the rest of your team as an email attachment, or copy it to OneNote, Word, or in any other format you prefer. -[How do I play the video recordings I created with the extension?](reference-qa.yml#recording-playback) + [How do I play the video recordings I created with the extension?](reference-qa.yml#recording-playback) -## Next step +## Next steps > [!div class="nextstepaction"] > [Use the extension in Connected mode](connected-mode-exploratory-testing.md) diff --git a/docs/test/test-case-managment-reference.md b/docs/test/test-case-managment-reference.md index 1717fc5e971..d2b31ccecdf 100644 --- a/docs/test/test-case-managment-reference.md +++ b/docs/test/test-case-managment-reference.md @@ -5,8 +5,8 @@ description: Learn which commands you can use to manage Azure Test Plans ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: reference -ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr monikerRange: '<= azure-devops' ms.date: 01/18/2022 --- @@ -21,7 +21,7 @@ You can perform several tasks to list, view, copy/clone or run tests using the * ## Work with the TCM command-line tool -To exercise the TCM command-line tool, you must have the following in place: +To exercise the TCM command-line tool, have the following in place: - Installed Visual Studio 2017 Professional or earlier version. You access **tcm.exe** from the command prompt and the following directories: `%programfiles(x86)%\Microsoft Visual Studio\2017\Professional\Common7\IDE` @@ -36,7 +36,7 @@ To exercise the TCM command-line tool, you must have the following in place: |**/teamproject**:`project`|Required. The name of the project that contains the test objects you want to clone or import automated tests into.| |**/login**:`username,[password]`|Optional. Specifies the name and password of a valid Azure DevOps user and who has permissions to run the command. Use this option if you're using basic authentication, you're not connected to a domain, or your Windows credentials don't have the appropriate permissions. | -- You must be a valid member of the project you want to access and have the required permissions based on the commands you run. To learn more, see [Manual test access and permissions](manual-test-permissions.md). +- Be a valid member of the project you want to access and have the required permissions based on the commands you run. For more information, see [Manual test access and permissions](manual-test-permissions.md). ## TCM commands diff --git a/docs/test/test-different-configurations.md b/docs/test/test-different-configurations.md index e5858641260..6dbae04525d 100644 --- a/docs/test/test-different-configurations.md +++ b/docs/test/test-different-configurations.md @@ -5,8 +5,8 @@ ms.assetid: 750F033E-A39E-4C85-BF85-012629C33DE6 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' ms.date: 12/20/2021 --- @@ -40,14 +40,14 @@ Then you can: ## Prerequisites -- You must connect to a project. If you don't have a project yet, [create one](/azure/devops/user-guide/sign-up-invite-teammates). -- You must be added to a project. To get added, [Add users to a project or team](/azure/devops/organizations/security/add-users-team-project). -- To view or add test configurations, you must have **Basic** access or higher. -- To add test configurations, you must have the project-level **Manage test configurations** permission set to **Allow**. By default, this permission is granted to members of the Contributors and Project Administrator groups. +| Category | Requirement | +|--------------|-------------| +| **Project access** | [Project member](../organizations/security/add-users-team-project.md). | +| **Access levels** | To add test configurations: Project-level **Manage test configurations** permission set to **Allow**. By default, this permission is granted to members of the Contributors and Project Administrator groups.| -To learn more, see [Manual test access and permissions](/azure/devops/test/manual-test-permissions). +For more information, see [Manual test access and permissions](manual-test-permissions.md). -[!INCLUDE [prerequisites-define](includes/prerequisites-tcm.md)] +[!INCLUDE [prerequisites-tcm](includes/prerequisites-tcm.md)] @@ -137,49 +137,6 @@ Then combine multiple variable values to create a configuration. 1. Save your new test configuration. ::: moniker-end -::: moniker range="<=azure-devops-2019" - -A test configuration is a combination of configuration variable -values. Your configuration variables could be, for example, -operating system, browser, CPU type, database. A configuration -might be "Windows 8 + 32-bit CPU" or "Windows 10 + 64-bit CPU." - -You must create the configuration variables first. Then combine -multiple variable values to create a configuration. - -1. Open the **Configurations** page in the **Test Plans** web portal, choose - the ![new](media/plus-and-arrow-icon.png) icon, and select - **New configuration variable**. - - ![Adding a new configuration variable](media/testing-configurations/testing-configurations-01.png) - -2. Type a name for the variable, such as **Browser**, and type a value. - Add as many values as you wish to the configuration variable, and then save it. - - ![Setting the values for a new configuration variable](media/testing-configurations/testing-configurations-01b.png) - -3. Repeat the steps to create any other configuration variables - you need. For example, create a configuration variable named **Operating system** - with the names of each operating system on which you want to test. - - ![Setting the values for an Operating Systems configuration variable](media/testing-configurations/testing-configurations-01c.png) - -4. Choose the ![new](media/plus-and-arrow-icon.png) icon and select - **New test configuration**. - - ![Adding a new test configuration](media/testing-configurations/testing-configurations-01a.png) - -5. Type a name for the test configuration and add the configuration - variables you created. Choose a value for each variable for this configuration. - - ![Adding variables to the new test configuration](media/testing-configurations/testing-configurations-02.png) - - Ensure **Assign to new test plans** is checked to make this the default - configuration for all the new test plans you create. - -6. Save your new test configuration. -::: moniker-end - ## Assign configurations to test plans and suites @@ -206,38 +163,6 @@ Configurations assigned to a test suite apply to all tests or suites within it. ![Screenshot shows setting configurations for a test case.](media/testing-configurations/select-configuration-test-case.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" - -You can assign configurations to a test plan, a test suite, -or an individual test case. Configurations assigned to a test plan -or test suite apply to all tests or suites within it. - -1. To assign a configuration to a test plan, in the **Test plans** page, open the shortcut - menu for the plan and choose **Assign configuration to test plan**. - - ![Assigning a configuration to a test plan](media/testing-configurations/testing-configurations-03.png) - -1. To assign a configuration to a test suite, open the shortcut - menu for the suite and choose **Assign configuration to test suite**. - - ![Assigning a configuration to a test suite](media/testing-configurations/testing-configurations-04.png) - - If you add multiple configurations to a test plan or suite, - the tests cases are repeated in the plan or suite with - each of the configurations you have assigned. - - ![Multiple configuration assignment to a test suite](media/testing-configurations/testing-configurations-05.png) - -1. If necessary, override the default configuration assigned to a test case - and assign the configuration you need. Select one or more - test cases, open the shortcut menu, and choose **Assign configurations**. - - ![Overriding the default configuration assigned to a test case](media/testing-configurations/testing-configurations-06.png) - -1. Search for and select the configurations to assign to these test case(s). - - ![Setting the required configurations for a test case](media/testing-configurations/testing-configurations-07.png) -::: moniker-end @@ -255,21 +180,6 @@ Set up a testing platform for a particular configuration, such as testing the ap ![Screenshot shows the configuration for this test in the status bar.](media/testing-configurations/configuration-status-bar.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" - -1. Set up a testing platform for a particular configuration, such - as testing the app using Google Chrome on Windows 10. - -1. Select and run a test that has this configuration assigned. - - ![Running the test with the configuration assigned](media/testing-configurations/testing-configurations-07a.png) - - As you run the test, a reminder of the required configuration - in shown in the status bar of the Test Runner window. - - ![The required configuration appears in the Test Runner window](media/testing-configurations/testing-configurations-08.png) -::: moniker-end - ## Track test results for each configuration @@ -292,27 +202,6 @@ If you have a test case that appears in several test suites, you can set the dif The same test case can have different configuration settings in different test suites and test plans. ::: moniker-end -::: moniker range="<=azure-devops-2019" - -1. Open the **Charts** page for your test plan or test suite, choose - **New**, and select **New test result chart**. - - ![Creating a new test result chart](media/testing-configurations/testing-configurations-09.png) - -1. Choose the type of chart you require, select **Configuration** - in the **Group by** list, and choose **OK**. - - ![Choosing the type of chart you require](media/testing-configurations/testing-configurations-10.png) - - A chart is created that can help you track your tests based on configurations. - You can pin this chart to your dashboard. - - ![The configuration test result chart](media/testing-configurations/testing-configurations-11.png) - -> If you have a test case that appears in several test plans and test suites, you can set the different configurations for each of these. -The same test case can have different configuration settings in different test suites and test plans. -::: moniker-end - ## Related articles * [Overview of manual and exploratory testing](index.yml) diff --git a/docs/test/test-objects-overview.md b/docs/test/test-objects-overview.md index e707abc29c1..e8d18e90d33 100644 --- a/docs/test/test-objects-overview.md +++ b/docs/test/test-objects-overview.md @@ -5,19 +5,21 @@ description: Understand the different test objects and terms that support manual ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: overview -ms.author: chcomley -author: chcomley +ms.author: jeom +author: raviLiftr monikerRange: '<= azure-devops' ms.date: 09/15/2021 --- - # Test objects and terms [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] Read this article to gain an understanding of the objects and terms used in manual and exploratory testing. +## Prerequisites + +[!INCLUDE [prerequisites-run](includes/prerequisites-run.md)] @@ -25,7 +27,6 @@ Read this article to gain an understanding of the objects and terms used in manu To support manual and automated testing, you add and group three main types of test-specific work item types: **Test Plans**, **Test Suites**, and **Test Cases**. To support sharing of various test steps and test parameters, you define **Shared Steps** and **Shared Parameters**. These objects are stored in the work tracking data store as specific types of work items. - ![Test management work item types](../boards/work-items/guidance/media/ALM_PT_WITS_TestExperience.png) The following table describes the work item types used to support the Azure DevOps test experience. Test-specific work items link together using the link types shown in the previous image. @@ -70,7 +71,7 @@ The following table describes the work item types used to support the Azure DevO - [**Manual**](create-test-cases.md): Test cases that define different steps that you run using Test Runner or other supported client. - [**Automated**](run-automated-tests-from-test-hub.md): Test cases that are designed to run within an Azure Pipeline. > [!TIP] - > You can create a test case that automatically links to a requirement—User Story ([Agile](../boards/work-items/guidance/agile-process.md)), Product Backlog Item ([Scrum](../boards/work-items/guidance/scrum-process.md)), Requirement ([CMMI](../boards/work-items/guidance/cmmi-process.md)), or Issue ([Basic](../boards/get-started/plan-track-work.md))—when you create a test from the Kanban board. To learn more, see [Add, run, and update inline tests](../boards/boards/add-run-update-tests.md). + > You can create a test case that automatically links to a requirement—User Story ([Agile](../boards/work-items/guidance/agile-process.md)), Product Backlog Item ([Scrum](../boards/work-items/guidance/scrum-process.md)), Requirement ([CMMI](../boards/work-items/guidance/cmmi-process.md)), or Issue ([Basic](../boards/get-started/plan-track-work.md))—when you create a test from the board. For more information, see [Add, run, and update inline tests](../boards/boards/add-run-update-tests.md). :::column-end::: :::row-end::: :::row::: @@ -168,7 +169,6 @@ The only required field for all work item types is **Title**. When the work item :::row-end::: --- - ## Common controls to all test-specific work item types Several controls appear in several test-specific work items as described in the following table. If these controls are not of interest, you can hide them from the work item form layout as described in [Add and manage fields (Inheritance process)](../organizations/settings/work/customize-process-field.md#hide-a-field-or-custom-control). @@ -221,18 +221,17 @@ Several controls appear in several test-specific work items as described in the ## Customize test-specific work item types -For the Inherited process, you can customize test plans, test suites, and test cases. For the On-premises XML process, you can customize all test-specific work item types. To learn more, see [Customize work tracking objects to support your team's processes](../reference/customize-work.md). +For the Inherited process, you can customize test plans, test suites, and test cases. For the On-premises XML process, you can customize all test-specific work item types. For more information, see [Customize work tracking objects to support your team's processes](../reference/customize-work.md). ## Permissions required to modify work items There are a number of permissions that control select features for viewing, modifying, or deleting work items. These include those listed in the following table. -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" > [!NOTE] > The **Change work item type** permission doesn't apply to test-specific work items. Even if you choose this feature from the work item form, changing the work item type is disallowed. ::: moniker-end - :::row::: :::column span="2"::: **Permission** @@ -254,7 +253,7 @@ There are a number of permissions that control select features for viewing, modi Project-level :::column-end::: :::column span="2"::: - To view, create, or delete test runs, you must be granted the corresponding permission. + To view, create, or delete test runs, have the corresponding permission. :::column-end::: :::row-end::: :::row::: @@ -266,7 +265,7 @@ There are a number of permissions that control select features for viewing, modi Project-level :::column-end::: :::column span="2"::: - Manage test configurations or test environments, you must be granted the corresponding permission. + Manage test configurations or test environments, have the corresponding permission. :::column-end::: :::row-end::: :::row::: @@ -337,23 +336,17 @@ There are a number of permissions that control select features for viewing, modi :::column-end::: :::row-end::: - -To learn more about setting these permissions, see [Set permissions and access for testing](../organizations/security/set-permissions-access-test.md) and [Change project-level permissions](../organizations/security/change-project-level-permissions.md). +For more information about setting these permissions, see [Set permissions and access for testing](../organizations/security/set-permissions-access-test.md) and [Change project-level permissions](../organizations/security/change-project-level-permissions.md). ## Export, import, and bulk update of test-specific work items -As with other work items, you can bulk edit test-specific work items. To learn more, see the following articles: +As with other work items, you can bulk edit test-specific work items. For more information, see the following articles: ::: moniker range=">= azure-devops-2020" - [Bulk modify work items](../boards/backlogs/bulk-modify-work-items.md). - [Navigate Test Plans, Test suites context menu options](navigate-test-plans.md#test-suites-context-menu-options) ::: moniker-end -::: moniker range="< azure-devops-2020" -- [Bulk modify work items](../boards/backlogs/bulk-modify-work-items.md). -- [Can I export the test plan to share or review offline](create-a-test-plan.md#work-with-test-suites) -::: moniker-end - ## Test terms The following table describes several terms used in manual and exploratory testing. @@ -396,7 +389,7 @@ The following table describes several terms used in manual and exploratory testi - **Block Test** - **Not Applicable** --- - To learn more, see [Repeat a test with different data](repeat-test-with-different-data.md). Note that pipeline test outcomes differ as described in [About pipeline tests](../pipelines/test/test-glossary.md). + For more information, see [Repeat a test with different data](repeat-test-with-different-data.md). Note that pipeline test outcomes differ as described in [About pipeline tests](../pipelines/test/test-glossary.md). :::column-end::: :::row-end::: :::row::: diff --git a/docs/test/toc.yml b/docs/test/toc.yml index 328ef906fdc..353d3db95f5 100644 --- a/docs/test/toc.yml +++ b/docs/test/toc.yml @@ -23,11 +23,17 @@ - name: Copy/clone test plans, suites, cases displayName: copy, clone, import, export, test plans, test suites, test cases href: copy-clone-test-items.md + - name: Bulk Import and Export Test cases (CSV/XLSX) + displayName: copy, clone, import, export, test plans, test suites, test cases + href: bulk-import-export-test-cases.md - name: Run manual tests displayName: manual test, run, test runs href: run-manual-tests.md - name: Default permissions (Security) href: manual-test-permissions.md + - name: Store custom data in test plan and/or test result + displayName: manual test, automated, run, test runs, result, test results, custom data, custom fields + href: custom-fields.md expanded: true - name: Manual tests items: @@ -37,7 +43,7 @@ - name: Repeat a test with different data displayName: data, testing, shared steps, shared parameters href: repeat-test-with-different-data.md - - name: Test from the Kanban board + - name: Test from your board displayName: inline testing href: ../boards/boards/add-run-update-tests.md?toc=/azure/devops/test/toc.json - name: Perform user acceptance testing @@ -55,6 +61,8 @@ - name: Set test retention policies displayName: results, logs href: how-long-to-keep-test-results.md + - name: Manage test failure type + href: manage-test-failure-type.md - name: Automated tests items: - name: Associate automated tests with test cases diff --git a/docs/test/track-stakeholder-feedback.md b/docs/test/track-stakeholder-feedback.md index 613dddd3162..edbd8f930a4 100644 --- a/docs/test/track-stakeholder-feedback.md +++ b/docs/test/track-stakeholder-feedback.md @@ -5,8 +5,8 @@ ms.assetid: DADC6608-1830-4FDA-9007-6539859F4866 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra ms.date: 11/30/2021 monikerRange: '<= azure-devops' --- @@ -15,27 +15,29 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -All feedback is captured in a *Feedback Response* work item. -You can track feedback, whether captured by the [Test & Feedback extension](provide-stakeholder-feedback.md) or the [Microsoft Feedback client](/previous-versions/azure/devops/project/feedback/give-feedback), through a work item query. +All feedback gets captured in a *Feedback Response* work item. You can track feedback, whether captured by the [Test & Feedback extension](provide-stakeholder-feedback.md) or the [Microsoft Feedback client](/previous-versions/azure/devops/project/feedback/give-feedback), through a work item query. + +## Prerequisites [!INCLUDE [prerequisites-queries](../boards/includes/prerequisites-queries.md)] ## Track feedback requests -::: moniker range=">=azure-devops-2019" +::: moniker range="<=azure-devops" + +1. To view feedback, use the **Feedback** shared query. +2. Select your project and open **Boards** > **Queries**. +3. Under **Queries**, select **All**. +4. In the Shared Queries, select **Feedback**. -To view feedback, use the **Feedback** shared query. -Select your project and open **Boards** > **Queries**. -Under **Queries**, select **All**. -In the Shared Queries, select **Feedback**. + ![Screenshot shows Boards with Queries selected and the Feedback query selected.](media/track-stakeholder-feedback/open-feedback-query.png) -![Screenshot shows Boards with Queries selected and the Feedback query selected.](media/track-stakeholder-feedback/open-feedback-query.png) +The query displays a list of all the feedback responses received. For more information, see [Web portal navigation](../project/navigation/index.md). -This query displays a list of all the feedback responses received. -To learn more, see [Web portal navigation](../project/navigation/index.md). +## Create a feedback query -To create a feedback query, follow these steps: +To create a feedback query, do the following steps. 1. Select **Boards** > **Queries** and then select **New query**. @@ -43,40 +45,20 @@ To create a feedback query, follow these steps: ![Screenshot shows editor with values entered.](media/track-stakeholder-feedback/editor-feedback-values.png) - - Team Project = @Project - - Work Item Type In Group Microsoft.FeedbackRequestCategory - - State = Active + - `Team Project` `=` `@Project` + - `Work Item Type` `In Group` `Microsoft.FeedbackRequestCategory` + - `State` `=` `Active` 1. Select **Save query** and enter a name. 1. Select **Run query** to see a list of active feedback responses for your team project. - ![Screenshot shows Results view of Feedback request work items.](media/track-stakeholder-feedback/feedback-request-work-items.png) + ![Screenshot shows results view of Feedback request work items.](media/track-stakeholder-feedback/feedback-request-work-items.png) 1. Select a response work item to see the details of the feedback. ::: moniker-end -::: moniker range="Queries** or **Work>Queries**. To learn how, see [Web portal navigation](../project/navigation/index.md). - -1. In the list of shared queries, select **Feedback**. - This query displays a list of all the feedback responses received. - - ![Viewing the feedback responses](media/track-stakeholder-feedback/track-stakeholder-feedback-31.png) - - Or, create a feedback query with the parameters, as shown. - - ![Editor view for flat-list feedback query](../project/feedback/media/ALM_GF_FeedbackQueryEditor.png) - -1. You should see a list of all active feedback responses for your team project. - - ![Results view of feedback responses](../project/feedback/media/ALM_GF_FeedbackQueryResults.png) - -1. Open the response work item to see the details of the feedback. - -::: moniker-end - ## Related articles - [What is Azure Test Plans?](overview.md) diff --git a/docs/test/track-test-status.md b/docs/test/track-test-status.md index 11e32ce65f9..8c31f6a4882 100644 --- a/docs/test/track-test-status.md +++ b/docs/test/track-test-status.md @@ -5,8 +5,8 @@ description: Learn how to view the status of your planned testing using an out-o ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra monikerRange: '<= azure-devops' ms.date: 12/08/2021 --- @@ -15,65 +15,49 @@ ms.date: 12/08/2021 [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -View the status of planned tests or monitor testing progress by defining test case or test result charts. To learn more about test planning, see [Create test plans and test suites](create-a-test-plan.md). For information about test result terms, see [Test objects and terms](test-objects-overview.md#test-terms). +View the status of planned tests or monitor testing progress by defining test case or test result charts. For more information about test planning, see [Create test plans and test suites](create-a-test-plan.md). For information about test result terms, see [Test objects and terms](test-objects-overview.md#test-terms). ::: moniker range=">= azure-devops-2020" To track the progress of more than one test plan or test suite, open the [Progress Report](progress-report.md). ::: moniker-end - +## Prerequisites + +[!INCLUDE [prerequisites-run](includes/prerequisites-run.md)] + + ## Track testing progress Use test results charts to track how your testing is going. -Choose from a fixed set of pre-populated fields related to results. +Choose from a fixed set of prepopulated fields related to results. Add your own charts for test results to visualize what's important for your team. -If you already know how to add a chart, jump to the [examples](#TestResultsExamples) below of charts that you can create. +If you already know how to add a chart, jump to the [examples](#TestResultsExamples) that you can create. ::: moniker range=">=azure-devops-2020" To add a chart, follow these steps: -1. Select **Test Plans** to open the **Test Plans** page. Select a test plan to open it, then select the **Charts** tab. +1. Select **Test Plans** to open the **Test Plans** page. Open a test plan and then select the **Charts** tab. -1. Under **Charts**, select **New** > **New test result chart**. +2. Under **Charts**, select **New** > **New test result chart**. ![Screenshot shows the Charts page with New, then New test result chart selected.](media/track-test-status/new-test-result-chart.png) -1. Select the chart type, in this example, a pie chart. +3. Select the chart type, in this example, a pie chart. Based on the chart, configure the fields that you want to use to group by, or for the rows and columns. ![Screenshot of the Configure Chart dialog box where you can enter chart type, name, and other settings.](media/track-test-status/configure-pie-chart.png) All charts roll up the information for any child test suites of the test plan or test suite that you selected. -1. Select **OK** to save the chart. - The chart is displayed in the **Charts** page for your test plan or test suite. +4. Select **OK** to save the chart. + The chart displays in the **Charts** page for your test plan or test suite. ![Screenshot shows the Charts page with the new chart displayed.](media/track-test-status/display-pie-chart.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -By default, a pie chart is created for each test plan. This chart is grouped by the outcome field to show the latest results -for all the tests in the test plan. View this default chart from the **Charts** page. - -![Select test plan. Go to Charts page to view default chart](media/track-test-status/DefaultChart.png) - -To add a chart, follow these steps: - -1. Select the test plan or test suite for your chart in the **Test Plans** page. Then create a new chart. - - ![On the Charts page; click New. Select New Test Result Chart](media/track-test-status/NewTestResultChart.png) - -1. Select the chart type. Based on the chart, configure the fields that you want to use to group by, or for the rows and columns. - - ![Name your chart. Select the field values. To save, click OK](media/track-test-status/ConfigureChart.png) - - All charts roll up the information for any child test suites of the test plan or test suite that you selected. - -1. Save the chart. Now it will be displayed in the **Charts** page for the test plan or test suite that you selected. -::: moniker-end ## Test results examples @@ -82,49 +66,39 @@ This section includes examples of useful charts. ### Check test status for a test suite -You can check the test status for a specific test suite. +Do the following steps to check the test status for a specific test suite. -Select **Test Plans** to open the **Test Plans** page, and then select a plan to view a test suite. -Select **New** > **New test result chart** to create a test results pie chart. -Group by **Outcome**. +1. Select **Test Plans** to open the **Test Plans** page, and then select a plan to view a test suite. +2. Select **New** > **New test result chart** to create a test results pie chart. +3. Group by **Outcome**. ::: moniker range=">=azure-devops-2020" ![Screenshot shows the Configure chart dialog box with Pie and Outcome selected.](media/track-test-status/configure-pie-chart.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -![On the chart page, choose New test result chart; choose Pie chart. In Group By, select Outcome](media/track-test-status/ExampleOutcome.png) -::: moniker-end ### Check status for user stories per sprint If you created requirement-based test suites in your test plan for your user stories, you can create a chart to review status for user stories that your team is testing in the current sprint. -Create a static test suite that groups your requirement-based test suites together. -Select that static test suite in the **Test Plans** page. -Add a test results stacked bar chart. - -Select **Suite** as the **Y-axis** and **Outcome** as **Group by**. +1. Create a static test suite that groups your requirement-based test suites together. +2. Select that static test suite in the **Test Plans** page. +3. Add a test results stacked bar chart. +4. Select **Suite** as the **Y-axis** and **Outcome** as **Group by**. ::: moniker range=">=azure-devops-2020" ![Screenshot shows a stacked bar chart for a user story with Suite and Outcome selected.](media/track-test-status/user-story-stacked-bar-chart.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" - ![For Rows, select Suite. For Columns, select Outcome. To save, click OK](media/track-test-status/ExampleUserStories.png) -::: moniker-end ### Check tests for each tester You can check how many tests that each tester left to run. -Select your test plan in the **Test Plans** page and add a test results pivot table chart. -Choose **Tester** as **Rows** and **Outcome** as **Columns** pivot. +1. Select your test plan in the **Test Plans** page and add a test results pivot table chart. +2. Choose **Tester** as **Rows** and **Outcome** as **Columns** pivot. ::: moniker range=">=azure-devops-2020" ![Screenshot shows a pivot table with Tester and Outcome selected.](media/track-test-status/tester-tests-left.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -![For Rows, select Tester. For Columns, select Outcome. To save, click OK](media/track-test-status/ExampleTesterTestsLeft.png) -::: moniker-end ### Check quality based on the configuration @@ -157,55 +131,29 @@ Use test case charts to find out the progress of your test case authoring. The charts for test cases give you the flexibility to report on columns that you add to the tests page. By default, test case fields aren't added to the view in the tests page. -If you already know how to add a chart, jump to the [examples](#ExamplesTestCase) below of charts that you can create for test cases. +If you already know how to add a chart, jump to the [examples](#ExamplesTestCase) that you can create for test cases. ::: moniker range=">=azure-devops-2020" 1. From the **Define** or **Execute** tabs, add any fields you want to use for your test case chart by using **Column Options**. Those fields appear as choices in the lists for grouping for your test case charts. -1. Select the test plan or test suite for your chart in the **Test Plans** page. +2. Select the test plan or test suite for your chart in the **Test Plans** page. Under **Charts**, select **New** > **New test case chart**. ![Screenshot shows the Charts page with New, then New test case chart selected.](media/track-test-status/new-test-case-chart.png) All charts roll up the information for any child test suites of the test plan or test suite that you selected. -1. Select the chart type. +3. Select the chart type. Based on the chart, configure the fields that you want to use to group by, for rows and columns, or the range for trend charts. ![Screenshot shows the Configure chart dialog box where you can select a chart type and other values.](media/track-test-status/configure-chart-values.png) You can't group by test suite for the test case charts. -1. Select **OK** to save the chart. - The chart is displayed in the **Charts** page for your test plan or test suite. -::: moniker-end - -::: moniker range="<=azure-devops-2019" -1. Add any fields you want to use for your test case chart - from the tests page with Column options. Then the fields will - appear as choices in the drop-down lists for grouping for - your test case charts. - -1. Select the test plan or test suite for your chart in - the Test Plans page. Then add a test case chart. - - ![Select test suite; Charts page; New test case chart](media/track-test-status/NewTestCaseChart.png) - - All charts roll up the information for any child test suites - of the test plan or test suite that you selected. - -1. Select the chart type. Based on the chart, configure the - fields that you want to use to group by, for rows and columns, - or the range (trend charts only). - - ![Choose the chart type; choose the fields for the chart](media/track-test-status/ConfigureChart2.png) - - You can't group by test suite for the test case charts. - -1. Save the chart. Now it will be displayed in the charts - page for the test plan or test suite that you selected. +4. Select **OK** to save the chart. + The chart displays in the **Charts** page for your test plan or test suite. ::: moniker-end @@ -219,49 +167,41 @@ These examples show common ways to interact with test case results. You can view the recent test results for an individual test case. ::: moniker range=">=azure-devops-2020" -Select the **Execute** tab in a test suite and then select a test case. Select **More options** or right-click to open the context menu. Select **View test result**. +1. Select the **Execute** tab in a test suite and then select a test case. +2. Select **More options** or right-select to open the context menu. +3. Select **View test result**. ![Screenshot shows the context menu for a test case, with the View test result option selected.](media/track-test-status/view-test-result-option.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -Select the test case within a test suite and then choose to view the test details pane. -![From test suite, select test case. On toolbar, click test details icon to view the test details pane](media/track-test-status/ShowDetailsPane.png) -::: moniker-end +1. View the recent test results for this test case. -View the recent test results for this test case. ::: moniker range=">=azure-devops-2020" ![Screenshot shows the Test Runs pane with information about individual test run.](media/track-test-status/test-case-results.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -![In test details pane, open the Pane list, choose Test Results](media/track-test-status/TestResultsPane.png) -::: moniker-end ### Track burn down by using a stacked area chart You can track burn down for test case creation. -Create a stacked area trend chart to view the burn down for how many test cases are ready to be run. -Select **State** for the stack by field and **Ascending** for the sort field. +1. Create a stacked area trend chart to view the burn down for how many test cases are ready to be run. +2. Select **State** for the stack by field and **Ascending** for the sort field. ::: moniker range=">=azure-devops-2020" ![Screenshot shows a stacked area chart with State and ascending value selected.](media/track-test-status/burn-down-stacked-area-chart.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -![Create a stacked area chart: For Stack By, choose State, then sort by ascending value.](media/track-test-status/ExampleBurndownReadiness.png) -::: moniker-end You can track burn down for automation status. -Use a stacked area trend chart to view the burn down for how many test cases have been automated. +Use a stacked area trend chart to view the burn down for automated test cases. Select **Automation status** for the **Stack by** field and **Ascending** for the **Sort** field. ### See test ownership and priorities If multiple teams own test cases in your test plan, you can see how many test cases each team owns and the priorities of the tests. -If your teams are organized by area path, use a test case pie chart. +If your teams organize by area path, use a test case pie chart. Select **Area path** for **Group by**. If you want to know the priorities of these tests, create a stacked bar chart. @@ -270,9 +210,9 @@ Select **Area path** for the **Y-axis** and **Priority** for **Group by**. ### Track test creation status You can track test creation status for team members by creating a chart that includes the **Assigned to** value. -Use a stacked bar chart or a pivot table chart. -Select **Assigned to** for **Y-axis** or **Rows**. -Select **State** for **Group by** or **Columns**. +1. Use a stacked bar chart or a pivot table chart. +2. Select **Assigned to** for **Y-axis** or **Rows**. +3. Select **State** for **Group by** or **Columns**. @@ -284,13 +224,11 @@ Use the chart's context menu. ::: moniker range=">=azure-devops-2020" ![Screenshot shows the chart context menu with Add to dashboard selected.](media/track-test-status/add-dashboard-chart.png) ::: moniker-end -::: moniker range="<=azure-devops-2019" -![Open the chart](media/track-test-status/EditDeletePinChart.png) -::: moniker-end + You can [configure the dashboard widget](../report/dashboards/widget-catalog.md) to show a range of chart types. > [!NOTE] -> You must be a team administrator to configure the dashboard widget, but team members with Stakeholder access can view the charts on the dashboard. +> Be a team administrator to configure the dashboard widget, but team members with Stakeholder access can view the charts on the dashboard. ## Related articles @@ -298,6 +236,4 @@ You can [configure the dashboard widget](../report/dashboards/widget-catalog.md) - [Control how long to keep test results](how-long-to-keep-test-results.md) - [FAQs for manual testing](reference-qa.yml#trackstatus) - [Widget catalog](../report/dashboards/widget-catalog.md) -- [Team administration](../organizations/settings/manage-teams.md) - - +- [Team administration](../organizations/settings/manage-teams.md) diff --git a/docs/test/user-acceptance-testing.md b/docs/test/user-acceptance-testing.md index dcbce1c7bdf..1553aa084fa 100644 --- a/docs/test/user-acceptance-testing.md +++ b/docs/test/user-acceptance-testing.md @@ -5,8 +5,8 @@ ms.assetid: C52CDC6D-1B01-4A63-A265-B68C4E3DDE7D ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra ms.date: 12/06/2021 monikerRange: '<= azure-devops' --- @@ -15,37 +15,32 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Today's faster development pace requires tools that -enable test teams to more easily verify value based -on business requirements, and the high quality -software demanded by customers. -This type of testing is often referred to as -_user acceptance testing_. +Today's faster development pace requires tools that let test teams more easily verify value based +on business requirements, and the high quality software demanded by customers. This type of testing is often referred to as _user acceptance testing_. -Typically you create a Test Suite using a formal -requirement work item type. However, today's -agile teams often prefer to work from User Stories -or Product Backlog items as their requirements. +Typically you create a Test Suite using a formal requirement work item type. However, today's +agile teams often prefer to work from User Stories or Product Backlog items as their requirements. -[!INCLUDE [prerequisites-define](includes/prerequisites-stakeholder.md)] +## Prerequisites -In addition, you must have already created work items and -a test plan. If not, follow the steps provided in the following articles: - -- [Create your backlog](../boards/backlogs/create-your-backlog.md) -- [Create a test plan](create-a-test-plan.md) +| Category | Requirement | +|--------------|-------------| +| **Project access** | [Project member](../organizations/security/add-users-team-project.md). | +| **Access levels** | To request or provide feedback: At least **Stakeholder** access. | +| **Permissions** | - To add or modify bugs or other work item types: **Edit work items in this node** permission set to **Allow** under the corresponding **Area Path**.
      - To add new tags: **Create tag definition** permission set to **Allow**.
      For more information, see [Set permissions and access for testing](../organizations/security/set-permissions-access-test.md). | +|**Configuration** |Work items and a test plan. If you don't have these, [create your backlog](../boards/backlogs/create-your-backlog.md) and [create a test plan](create-a-test-plan.md).| ## Assign and invite testers -For user acceptance testing, you can assign multiple testers to a set of tests. You can even assign the stakeholders who created the business requirements as testers. +For user acceptance testing, you can assign multiple testers to a set of tests. You can even assign the stakeholders, who created the business requirements, as testers. -1. Select **Test plans** to see your test suites. You can select **Mine** to see your favorites or **All** to see all test plans. Select a test plan to open it. +1. Go to **Test plans**. You can select **Mine** to see your favorites or **All** to see all test plans. Open a test plan. -1. Select a test suite and then select **More options** or right-click to view the context menu. Select **Assign testers to run all tests**. +2. Select a test suite and then select **More options** or right-select to view the context menu and **Assign testers to run all tests**. -1. In **Search users**, enter a name or partial name to find the testers you want. You can select multiple testers. +3. In **Search users**, enter a name or partial name to find the testers you want. You can select multiple testers. ![Screenshot shows the option to search for users with two users already selected.](media/user-acceptance-testing/search-select-testers.png) @@ -53,47 +48,36 @@ For user acceptance testing, you can assign multiple testers to a set of tests. > You can select individual users who are a members of the Project Valid Users group. > You can't select user groups. -1. To notify testers, select **Send email**. +4. To notify testers, select **Send email**. ![Screenshot shows the option to send email selected and text boxes for subject and notes.](media/user-acceptance-testing/send-messages-testers.png) -1. Enter a message subject and note, as needed, and select **Ok**. -::: moniker range=" [!NOTE] - > For on-premises Azure DevOps, you must have an SMTP server configured for your deployment. + > For on-premises Azure DevOps, have an SMTP server configured for your deployment. > For more information, see [Configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts) ::: moniker-end -If you have a large pool of potential testers, you might need to search for testers, as described above. +If you have a large pool of potential testers, you might need to search for testers, as previously described. -If you're assigning a tester to an individual test case, the search option appears in the context menu. -Select the **Execute** tab, then select a test case, and select **More options** or right-click to open the context menu. +To assign a tester to an individual test case, the search option appears in the context menu. +Select the **Execute** tab, select a test case, and then select **More options** or right-select to open the context menu. ![Screenshot shows a test case selected with the Assign tester menu option selected and Search users highlighted.](media/user-acceptance-testing/test-case-search-testers.png) When you select **Assign tester**, use the search option to find a tester. -## Easily track results +## Track results -A key principle of good user acceptance testing practice -is to minimize the effort required to determine whether a -requirement has been achieved. -There are two ways you can do this: you can focus on -individual test runs and tests to see which failed, or -you can use the chart views that make it much easier to -track your test results. These views are accessible by all -members of your team. +A key principle of good user acceptance testing practice is to minimize the effort required to determine whether a requirement is achieved. There are two ways you can do so: Focus on individual test runs and tests to see what failed, or use the chart views, which make it easier to track your test results. All members of your team can access these views. -![Exploring test results](media/user-acceptance-testing/uat8.png) +![Screenshot showing test results.](media/user-acceptance-testing/uat8.png) -> Note: The dashboard display shown here is also used -for other types of testing such as continuous testing. +The example dashboard is also used for other types of testing, such as continuous testing. -If you don't see the data or information you expect in -the dashboard charts, verify that the columns in your -data have been added to the Tests view. -For details see [this blog post](https://devblogs.microsoft.com/devops/visual-studio-team-services-manual-testing-tips-charts-iterations-and-runs/). +If you don't see the data or information you expect in the dashboard charts, verify that the columns in your data are added to the Tests view. For more information, see [this blog post](https://devblogs.microsoft.com/devops/visual-studio-team-services-manual-testing-tips-charts-iterations-and-runs/). ## Related articles diff --git a/docs/test/voluntary-stakeholder-feedback.md b/docs/test/voluntary-stakeholder-feedback.md index bf42aa94508..84b021dde33 100644 --- a/docs/test/voluntary-stakeholder-feedback.md +++ b/docs/test/voluntary-stakeholder-feedback.md @@ -5,75 +5,75 @@ ms.assetid: 4E467527-62C6-4321-BA56-FF82F0FFFD69 ms.service: azure-devops-test-plans ms.custom: UpdateFrequency3 ms.topic: conceptual -ms.author: sdanie -author: steved0x +ms.author: jeom +author: rohit-batra ms.date: 12/07/2018 monikerRange: '<= azure-devops' --- -# Voluntarily provide stakeholder feedback using the Test & Feedback extension +# Provide stakeholder feedback with the Test & Feedback extension [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [feedback-header-text](includes/feedback-header-text.md)] +## Prerequisites + +| Category | Requirement | +|--------------|-------------| +| **Project access** | [Project member](../organizations/security/add-users-team-project.md). | +| **Access levels** | To request or provide feedback: At least **Stakeholder** access. | +| **Extensions** |[Test & Feedback extension](perform-exploratory-tests.md).| + + ## Provide voluntary feedback -You can use the Test & Feedback extension to provide feedback -voluntarily, even if you haven't received a specific -[feedback request](request-stakeholder-feedback.md#request). +Use the Test & Feedback extension to provide voluntary feedback, even if you don't receive a [feedback request](request-stakeholder-feedback.md#request). -1. Open the Test & Feedback extension in your browser using the - ![launch exploratory testing](media/shared/exp-test-icon.png) - icon in the toolbar. +[!INCLUDE [important-note-request-feedback-unavailable](includes/important-note-request-feedback-unavailable.md)] -1. In the **Connection settings** page, choose **Connected** mode. +1. Open the Test & Feedback extension in your browser using the ![launch exploratory testing](media/shared/exp-test-icon.png) icon in the toolbar. + +2. In the **Connection settings** page, select **Connected**. - ![Choosing Connected mode](media/shared/connectedmode-01.png) + ![Screenshot of choosing Connected mode.](media/shared/connectedmode-01.png) -1. Connect to the server and the project or team that is requesting feedback. +3. Connect to the server and appropriate project or team. - ![Entering connection details](media/shared/connectedmode-02.png) + ![Screenshot showing entering connection details.](media/shared/connectedmode-02.png) -1. Start the exploratory testing session. +4. Start the exploratory testing session. ![Starting the exploratory testing session](media/voluntary-stakeholder-feedback/voluntary-stakeholder-feedback-26.png) -1. Open the application you want to provide feedback on - and begin your feedback. For example, choose - **Capture screenshot** to take a screenshot. +5. Open the application you want to provide feedback on and begin your feedback. For example, select **Capture screenshot**. - ![Capturing a screenshot](media/voluntary-stakeholder-feedback/voluntary-stakeholder-feedback-27.png) + ![Screenshot of capturing a screenshot.](media/voluntary-stakeholder-feedback/voluntary-stakeholder-feedback-27.png) - You can use all the capabilities of the extension - such as capturing screenshots, notes, and screen recordings. + You can use all the capabilities of the extension such as capturing screenshots, notes, and screen recordings. - >Some browsers may not provide all of the capture capabilities. - See [Supported web browsers for the extension](perform-exploratory-tests.md#browser-support). + Some browsers might not provide all of the capture capabilities. See [Supported web browsers for the extension](perform-exploratory-tests.md#browser-support). -1. When you are done capturing feedback, Choose **Provide feedback**. +6. When you're done capturing feedback, Choose **Provide feedback**. - ![Submitting your feedback](media/shared/provide-stakeholder-feedback-08.png) + ![Screenshot showing submitting feedback.](media/shared/provide-stakeholder-feedback-08.png) You can optionally choose to create bugs and tasks when you submit your feedback. The process is the same as described [here](connected-mode-exploratory-testing.md#create-bugs). -1. All your feedback captured is shown in the response form. - Type a suitable title and, optionally, select a star rating for - the feature you've been testing. +7. All your feedback captured is shown in the response form. Enter a suitable title and, optionally, select a star rating for the feature you're testing. - ![Entering a title and star rating](media/shared/provide-stakeholder-feedback-09.png) + ![Screenshot showing Entering a title and star rating.](media/shared/provide-stakeholder-feedback-09.png) -1. Save your feedback. This create a work item in Azure DevOps containing all your feedback. +8. **Save** your feedback, which creates a work item in Azure DevOps containing all your feedback. -1. Continue to capture more feedback if required. You can submit - multiple feedback responses, bugs, and tasks for the same feedback request. +9. Continue to capture more feedback if necessary. You can submit multiple feedback responses, bugs, and tasks for the same feedback request. -1. Choose the **Stop** icon to end your feedback session. +10. Select the **Stop** icon to end your feedback session. - ![Ending your feedback session](media/shared/provide-stakeholder-feedback-12.png) + ![Screenshot showing highlighted square icon to stop your feedback session.](media/shared/provide-stakeholder-feedback-12.png) ## Related articles @@ -82,5 +82,3 @@ voluntarily, even if you haven't received a specific * [Track stakeholder feedback using the Test & Feedback extension](track-stakeholder-feedback.md#track) * [Exploratory test and submit feedback directly from your browser](perform-exploratory-tests.md) * [Overview of manual and exploratory testing](index.yml) - - diff --git a/docs/toc.yml b/docs/toc.yml index d7bd5485c82..ad6edd71f3e 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -1,5 +1,5 @@ -- name: Azure DevOps - href: index.yml +- name: Azure DevOps + href: index.yml - name: Get started >> href: get-started/index.yml - name: Azure Artifacts >> @@ -37,22 +37,29 @@ - name: Manage extension permissions displayName: grant, publish, update, settings, admin href: ./marketplace/grant-permissions.md?toc=/azure/devops/marketplace-extensibility/toc.json + - name: Manage high privilege extensions + displayName: permission, Marketplace, scope, privilege, decorator, unpublished + href: ./marketplace/manage-high-privilege-extensions.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Authenticate items: - name: Guide to authentication href: ./integrate/get-started/authentication/authentication-guidance.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Authenticate extensions and security - href: ./extend/develop/auth.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Authenticate with service principals or managed identities + - name: Use Microsoft Entra + href: ./integrate/get-started/authentication/entra.md?toc=/azure/devops/marketplace-extensibility/toc.json + - name: Use service principals or managed identities href: ./integrate/get-started/authentication/service-principal-managed-identity.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Authenticate with PATs + - name: Use PATs href: ./organizations/accounts/use-personal-access-tokens-to-authenticate.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Authenticate with OAuth 2.0 + - name: Use OAuth 2.0 href: ./integrate/get-started/authentication/oauth.md?toc=/azure/devops/marketplace-extensibility/toc.json + - name: Use Microsoft Entra OAuth with Azure DevOps Services + href: ./integrate/get-started/authentication/entra-oauth.md?toc=/azure/devops/marketplace-extensibility/toc.json + - name: Use Azure DevOps OAuth 2.0 to create a web app + href: ./integrate/get-started/authentication/azure-devops-oauth.md?toc=/azure/devops/marketplace-extensibility/toc.json' + - name: Authenticate extensions and security + href: ./extend/develop/auth.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Cross-platform CLI for Azure DevOps using PATs href: ./integrate/get-started/auth/tfs-basic-auth.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: IIS Basic Authentication and PATs - href: ./integrate/get-started/authentication/iis-basic-auth.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Develop extensions items: - name: Get started @@ -65,7 +72,7 @@ - name: Contribution model displayName: plug, hub, action, build, task, type, target href: ./extend/develop/contributions-overview.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Create a custom pipelines task + - name: Add a custom pipeline task extension displayName: extension, manifest, package, publish, install, Marketplace href: ./extend/develop/add-build-task.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Author a pipeline decorator @@ -162,7 +169,7 @@ - name: Manifest reference displayName: JSON, extend, enhance, required, attributes, targets, demands, contributions, example href: ./extend/develop/manifest.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Integrate a Pipelines task into an extension + - name: Integrate a pipeline task into an extension displayName: JSON, build, release, custom href: ./extend/develop/integrate-build-task.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Pipeline decorator context @@ -221,7 +228,7 @@ displayName: oauth, secure, resources, access, credentials, account, approve href: ./service-hooks/authorize.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Service hook consumers - displayName: subscription, event, consumer, action, storage, webhooks, bus, campfire, hipchat, jenkins, kato, trello, zendesk + displayName: subscription, event, consumer, action, storage, webhooks, bus, jenkins, trello, zendesk href: ./service-hooks/consumers.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Service hook events displayName: build, release, deployment, created, updated, deleted, restored, commented, changed, approval @@ -231,7 +238,7 @@ href: ./service-hooks/troubleshoot.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Integrate applications items: - - name: Integrate applications overview + - name: Integrate applications overview href: ./integrate/index.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Get started items: @@ -295,8 +302,8 @@ href: ./pipelines/integrations/microsoft-teams.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Reference items: - - name: REST API reference overview - href: ./integrate/rest-api-overview.md + - name: REST API overview + href: /rest/api/azure/devops/?view=azure-devops-rest-7.2&preserve-view=true - name: Rate limits href: ./integrate/concepts/rate-limits.md - name: Deprecation of WIT & Test client OM @@ -320,7 +327,7 @@ - name: How to buy Azure DevOps CALs >> href: https://visualstudio.microsoft.com/team-services/tfs-pricing/ - name: Billing - href: ./organizations/billing/overview.md + href: organizations/index.yml - name: Build Visual Studio extensions >> href: /visualstudio/extensibility/shipping-visual-studio-extensions - name: Build apps for Windows >> diff --git a/docs/user-guide/about-azure-devops-services-tfs.md b/docs/user-guide/about-azure-devops-services-tfs.md index 4b9c433f105..c8e05b49666 100644 --- a/docs/user-guide/about-azure-devops-services-tfs.md +++ b/docs/user-guide/about-azure-devops-services-tfs.md @@ -1,172 +1,164 @@ --- -title: Compare Azure DevOps Services with Azure DevOps Server +title: Compare Azure DevOps Services with Azure DevOps Server titleSuffix: Azure DevOps -ms.custom: seodec18, engagement-fy23 +ms.custom: engagement-fy23 description: Understand the differences between Azure DevOps Services and Azure DevOps Server. ms.subservice: azure-devops-new-user ms.assetid: 458FAFD1-98B0-4B74-B8E7-F2C73D4EED6B ms.author: chcomley author: chcomley -ms.topic: conceptual -monikerRange: '<= azure-devops' -ms.date: 10/07/2022 +ms.topic: conceptual +ai-usage: ai-assisted +monikerRange: '<= azure-devops' +ms.date: 09/17/2024 --- # Compare Azure DevOps Services with Azure DevOps Server [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -The **cloud offering**, Azure DevOps Services, provides a scalable, reliable, and globally available hosted service. It's backed by a 99.9% SLA, monitored by our 24/7 operations team, and available in local data centers around the world. +The **cloud offering**, Azure DevOps Services, provides a scalable, reliable, and globally available hosted service. Our 24/7 operations team monitors the cloud offering, which is backed by a 99.9% service level agreement (SLA) and available in local data centers around the world. The **on-premises offering**, Azure DevOps Server, is built on a SQL Server back end. Customers usually choose the on-premises version when they need their data to stay within their network. Or, when they want access to SQL Server reporting services that integrate with Azure DevOps Server data and tools. -Both offerings provide the same [essential features and services](services.md), but Azure DevOps Services offers the following added benefits: +Both offerings provide the same [essential features and services](services.md), but Azure DevOps Services offers more benefits: -- Simplified server management -- Immediate access to the latest and greatest features -- Improved connectivity with remote sites -- A transition from capital expenditures (servers and the like) to operational expenditures (subscriptions) +- Simplifies server management +- Provides immediate access to the latest features +- Enhances connectivity with remote sites +- Transitions from capital expenditures (servers and hardware) to operational expenditures (subscriptions) -To determine which offering—cloud or on-premises—meets your needs, consider the following key differences. +To decide whether the cloud or on-premises offering best meets your needs, consider the following key differences. ## Key differences between Azure DevOps Services and Azure DevOps Server -When you're choosing which platform you want, or if you're considering a move from on-premises to the cloud, consider the following areas: +Azure DevOps Services and Azure DevOps Server offer similar core functionalities, but the following list shows key differences in specific feature areas: -- [Data scope and scalability](#scope-and-scale-data) -- [Authentication](#authentication) -- [Users and groups](#manage-users-and-groups) -- [User access management](#manage-user-access) -- [Security and data protection](#security-and-data-protection) +- **Deployment:** + Azure DevOps Services: Cloud-based, hosted, and managed by Microsoft. + Azure DevOps Server: On-premises solution, managed by your organization. +- **[Scalability:](#scalability)** + Azure DevOps Services: Highly scalable, accessible from anywhere with an internet connection. + Azure DevOps Server: Scalability is limited to your organizational infrastructure and server capacity. +- **[Authentication:](#authentication)** + Azure DevOps Services: Uses Microsoft accounts or Microsoft Entra ID. + Azure DevOps Server: Uses Windows Authentication and Active Directory (AD) domain credentials. +- **[Data control](#data-control):** + Azure DevOps Services: Data is stored in secure Azure data centers. + Azure DevOps Server: Organizations have complete control over their data and infrastructure. +- **[User management:](#user-management)** + Azure DevOps Services: Supports adding Microsoft Entra groups to Azure DevOps Services groups. + Azure DevOps Server: Access is granted through adding AD groups to various Azure DevOps groups. +- **[Process customization:](#process-customization)** + Azure DevOps Services: Inheritance process model with web UI and REST endpoint customization options. + Azure DevOps Server: Offers both Inheritance and On-premises XML process models for customization. +- **[Analytics and reporting](#analytics-and-reporting):** + Azure DevOps Services: Provides dashboards, Analytics service, Power BI integration, and OData support. + Azure DevOps Server: Offers dashboards, SSRS reports, and configurable lightweight charts. +- **Integration with SQL Server:** + Azure DevOps Services: Doesn't support integration with SQL Server Analysis Services for reporting. + Azure DevOps Server: Supports integration with SQL Server Analysis Services. -**Differences in specific feature areas** +These differences can help you decide which platform best suits your organization’s needs. If you're using Azure DevOps Server and considering a move to Azure DevOps Services, see the [Migration overview](../migrate/migration-overview.md). -Although Azure DevOps Services is a hosted version of Azure DevOps Server, there are some differences between features. Some Azure DevOps Server features aren't supported in Azure DevOps Services. For example, Azure DevOps Services doesn't support integration with SQL Server Analysis Services to support reporting. +## Scalability -**Differences in support** -- [Process customization](#process-customization) -- [Reporting](#reporting) +As your business grows, you might need to scale up your Azure DevOps instance. This scaling can involve adding more users, increasing storage capacity, or enhancing performance to handle larger workloads. You might also need to integrate other tools and services to support more complex workflows and ensure seamless collaboration across larger teams. Azure DevOps provides various options and configurations to help you scale efficiently, whether you're using Azure DevOps Services in the cloud or Azure DevOps Server on-premises. - -If you're using Azure DevOps Server and considering a move to Azure DevOps Services, understand your [migration options](../migrate/migrate-from-tfs.md). +### Azure DevOps Services -## Scope and scale data +Azure DevOps Services offers two options for scoping and scaling data: organizations and projects. Organizations in Azure DevOps Services get their own URLs (for example, ```https://dev.azure.com/fabrikamfiber```), and they always have exactly one project collection. Organizations can have many projects within a collection. -As your business grows, you may need to scale up your Azure DevOps instance. +Create organizations in Azure DevOps Services wherever you would create collections in Azure DevOps Server. Consider the following scenarios: -**Azure DevOps Services** - -Azure DevOps Services offer two options for scoping and scaling data: organizations and projects. Organizations in Azure DevOps Services get their own URLs (for example, ```https://dev.azure.com/fabrikamfiber```), and they always have exactly one project collection. Organizations can have many projects within a collection. - - -We recommend that you create organizations in Azure DevOps Services wherever you would create collections in Azure DevOps Server. The following scenarios apply: - -- You can purchase Azure DevOps Services users per organization - Paid users can access only the organization in which the payment is made. If you have users who need access to many organizations, Visual Studio subscriptions can be an attractive option. Visual Studio subscribers can be added to any number of organizations at no charge. We're also considering other ways to make access available to many organizations that are grouped into a single organization. -- You currently have to administer organizations one at a time. This process can be cumbersome when you have many organizations. +- **Purchase users per organization:** Paid users can access only the organization where the payment is made. For users needing access to multiple organizations, Visual Studio subscriptions are an attractive option. Visual Studio subscribers can be added to any number of organizations at no charge. We're also exploring other ways to provide access to multiple organizations grouped into a single entity. +- **Administer organizations individually:** Currently, you must administer organizations one at a time, which can be cumbersome if you have many organizations. For more information, see [Plan your organizational structure in Azure DevOps](plan-your-azure-devops-org-structure.md). -**Azure DevOps Server** +### Azure DevOps Server -Azure DevOps Server offers the following three options for scoping and scaling data: deployments, -project collections, and projects. In the simplest case, deployments are just servers. +Azure DevOps Server provides three options for scoping and scaling data: deployments, project collections, and projects. -Deployments can be more complicated, however, which could include: -* Two-server deployment where SQL is split out on a separate machine -* High-availability farms with lots of servers +- **Deployments:** In the simplest case, deployments are servers. However, they can be more complex, such as: + - Two-server deployments where SQL is on a separate machine + - High-availability farms with multiple servers -Project collections serve as containers for security and administration, and physical database boundaries. They're also used to group related projects. +- **Project collections:** Serve as containers for security, administration, and physical database boundaries. They're also used to group related projects. -Finally, projects are used to encapsulate the assets of individual software projects, including source code, work items, and so on. For more information, see [Plan your organizational structure in Azure DevOps](plan-your-azure-devops-org-structure.md). +- **Projects:** Encapsulate the assets of individual software projects, including source code, work items, and more. -## Authentication +For more information, see [Plan your organizational structure in Azure DevOps](plan-your-azure-devops-org-structure.md). -**Azure DevOps Services** +## Authentication -With Azure DevOps Services, you connect over the public internet (for example, ```https://contoso.visualstudio.com```). You either authenticate with [Microsoft account](https://www.microsoft.com/account) credentials or with -[Azure AD](/azure/active-directory/active-directory-whatis) -credentials, depending on your organization setup. You can also set up Azure AD to require features such as multi-factor-authentication, IP address restrictions, and so on. +When you compare Azure DevOps Services and Azure DevOps Server, it's important to understand the differences in how authentication is handled for each platform. -We recommend that you configure your organizations to use Azure AD rather than -Microsoft accounts. This method provides a better experience in many scenarios and more options for enhanced security. +### Azure DevOps Services -For more information, see [About accessing Azure DevOps Services with Azure AD](../organizations/accounts/access-with-azure-ad.md). +With Azure DevOps Services, you connect over the public internet (for example, ```https://contoso.visualstudio.com```). You can authenticate using either [Microsoft account](https://www.microsoft.com/account) credentials or [Microsoft Entra ID](/azure/active-directory/active-directory-whatis) +credentials, depending on your organization setup. Microsoft Entra ID also allows you to enable features such as multifactor authentication, IP address restrictions, and more. -**Azure DevOps Server** +We recommend configuring your organizations to use Microsoft Entra rather than Microsoft accounts. This approach provides a better experience in many scenarios and offers more options for enhanced security. -With Azure DevOps Server, you connect to an intranet server (for example, ```https://tfs.corp.contoso.com:8080/tfs```). You authenticate with Windows Authentication and your Active Directory (AD) domain credentials. This process is transparent and you never see any kind of sign-in experience. +For more information, see [About accessing Azure DevOps Services with Microsoft Entra ID](../organizations/accounts/access-with-azure-ad.md). -## Manage users and groups +### Azure DevOps Server -**Azure DevOps Services** +With Azure DevOps Server, you connect to an intranet server (for example, ```https://tfs.corp.contoso.com:8080/tfs```). Authenticate using Windows Authentication and your Active Directory (AD) domain credentials. This process is seamless, and you never encounter a sign-in experience. -In Azure DevOps Services, you can use a similar mechanism to -[provide access to groups of users](../organizations/accounts/manage-azure-active-directory-groups.md). You can add Azure AD groups to Azure DevOps Services groups. If you use Microsoft Accounts instead of Azure AD, you have to -[add users](../organizations/accounts/add-organization-users.md) one at a time. +## Data control -**Azure DevOps Server** +Many entities seek information about data protection when considering a move to the cloud. We're committed to keeping Azure DevOps Services projects safe and secure. We have technical features and business processes in place to uphold this commitment. You can also take steps to secure your data. For more information, see the [Data protection overview](../organizations/security/data-protection.md). -In Azure DevOps Server, you provide users access to deployments by adding Active Directory (AD) groups to various Azure DevOps groups -(for example, the Contributors group for an individual project). The AD group memberships are kept in sync. -As users are added and removed in AD, they also gain and lose access to Azure DevOps Server. -## Manage user access +## User management -In both Azure DevOps Services and Azure DevOps Server, you manage access to features by assigning users to an [access level](../organizations/security/access-levels.md). All users must be assigned to a single access level. In both the cloud and on-premises offerings, you can give free access to work item features to an unlimited number of Stakeholders. Also, an unlimited number of Visual Studio subscribers can have access to all Basic features at no extra charge. You pay only for other users who need access. +When you manage users and groups in Azure DevOps Services and Azure DevOps Server, there are distinct methods and tools available for each platform to ensure proper access and organization. -**Azure DevOps Services** +### Azure DevOps Services -In Azure DevOps Services, you must [assign an access level](../organizations/accounts/add-organization-users.md) -to each user in your organization. Azure DevOps Services validates Visual Studio subscribers as they sign in. You can assign Basic access for free to five users without Visual Studio subscriptions. +In Azure DevOps Services, you can [provide access to groups of users](../organizations/accounts/manage-azure-active-directory-groups.md) by adding Microsoft Entra groups to Azure DevOps Services groups. If you use Microsoft Accounts instead of Microsoft Entra ID, you must [add users](../organizations/accounts/add-organization-users.md) individually. -To give Basic access or higher to more users, [set up billing](../organizations/billing/set-up-billing-for-your-organization-vs.md) for your organization and [pay for more users](../organizations/billing/buy-basic-access-add-users.md). -Otherwise, all other users get Stakeholder access. +You must also [assign an access level](../organizations/accounts/add-organization-users.md) to each user in your organization. Azure DevOps Services validates Visual Studio subscribers as they sign in. You can assign Basic access for free to five users without Visual Studio subscriptions. -Azure AD groups give access to groups of users. Access levels are automatically assigned at first sign-in. For organizations that are configured to use Microsoft accounts for signing in, you must assign access levels to each user explicitly. +To give at least Basic access to more users, [set up billing](../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing) and [pay for more users](../organizations/billing/buy-basic-access-add-users.md). Otherwise, all other users receive Stakeholder access. -**Azure DevOps Server** +Microsoft Entra groups provide access to groups of users, with access levels automatically assigned at first sign-in. For organizations using Microsoft accounts for signing in, you must explicitly assign access levels to each user. -In Azure DevOps Server, all use is on the honor system. To set access levels for users based on their licenses, specify their -[access levels](../organizations/security/change-access-levels.md) on the administration page. For example, assign unlicensed users Stakeholder access only. +### Azure DevOps Server -Users with an Azure DevOps Server Client Access License (CAL) can have Basic access. Visual Studio subscribers can have either Basic or Advanced access, depending on their subscriptions. Azure DevOps Server doesn't attempt to verify these licenses or enforce compliance. +In Azure DevOps Server, you grant users access to deployments by adding Active Directory (AD) groups to various Azure DevOps groups, such as the Contributors group for an individual project. AD group memberships stay in sync, so as users get added or removed in AD, they automatically gain or lose access to Azure DevOps Server. -## Security and data protection +All use is on the honor system. To set access levels for users based on their licenses, specify their [access levels](../organizations/security/change-access-levels.md) on the administration page. For example, assign unlicensed users Stakeholder access only. -Many entities want to know more about data protection when they consider moving to the cloud. We're committed to ensuring that Azure DevOps Services projects stay safe and secure. We have technical features and business processes in place to deliver on this commitment. You can also take steps to secure your data. Learn more in our [Data Protection overview](../organizations/security/data-protection.md). +Users with an Azure DevOps Server Client Access License (CAL) can have Basic access. Visual Studio subscribers can have either Basic or Advanced access, depending on their subscriptions. Azure DevOps Server doesn't verify these licenses or enforce compliance. - +In both Azure DevOps Services and Azure DevOps Server, you manage access to features by assigning users to an [access level](../organizations/security/access-levels.md). All users must be assigned to a single access level. In both the cloud and on-premises offerings, you can give free access to work item features to an unlimited number of Stakeholders. Also, an unlimited number of Visual Studio subscribers can have access to all Basic features at no extra charge. You pay only for other users who need access. ## Process customization You can customize the work-tracking experience in different ways, depending on the supported process model: -**Azure DevOps Services** +### Azure DevOps Services -Azure DevOps Services uses the **Inheritance** process model, which supports WYSIWYG customization. +Azure DevOps Services uses the **Inheritance** process model, which supports WYSIWYG (What You See Is What You Get) customization. This model allows you to easily customize work item types, states, and fields directly through the user interface without needing to edit XML files. You can create and modify processes to fit your team's workflow, ensuring that the tools align with your specific project requirements. This flexibility makes it easier to manage and adapt to changes in your development process. -**Azure DevOps Server** +### Azure DevOps Server -With Azure DevOps Server, you can choose the **Inheritance** process model or the **On-premises XML** process model, which supports customization through import or export of XML definition files for work-tracking objects. -Azure DevOps Server 2018 and earlier versions only has access to the **On-premises XML** process model. -Although the **On-premises XML** process model option is powerful, it can cause various issues. The main issue is that processes for existing projects aren't automatically updated. - +With Azure DevOps Server, you can choose between the **Inheritance** process model and the **On-premises XML** process model. -To help you avoid these issues in Azure DevOps Services, custom process templates and the **witadmin.exe** tool have always been disabled. This approach has enabled us to automatically update all projects with each Azure DevOps Services upgrade. Meanwhile, the product team is working hard to make customizing processes possible in ways that we can support easily and continuously. We recently introduced the first of these changes and more changes are on the way. +- **Inheritance process model:** This model supports WYSIWYG (What You See Is What You Get) customization, allowing you to easily customize work item types, states, and fields directly through the user interface. This approach simplifies the customization process and ensures that changes are immediately reflected in your projects. -With the new process-customization capability, you can make changes directly within the web user interface (UI). If you want to customize your processes programmatically, you can do so through REST endpoints. When you customize projects this way, they're automatically updated when we release new versions of their base processes with Azure DevOps Services upgrades. +- **On-premises XML process model:** This model supports customization through the import or export of XML definition files for work-tracking objects. It provides a powerful and flexible way to define and manage your processes. However, it can cause various issues, such as: + - Processes for existing projects aren't automatically updated, requiring manual intervention to apply changes. + - The complexity of managing XML files can lead to errors and inconsistencies. + - It might be challenging to maintain and troubleshoot customizations, especially in large or complex environments. + +To help you avoid issues, custom process templates and the **witadmin.exe** tool are always disabled. This approach ensures that all projects are automatically updated with each Azure DevOps Services upgrade. The product team is working to make process customization easier and more sustainable. + +With the process customization capability, you can make changes directly within the web user interface (UI). If you prefer to customize your processes programmatically, you can use REST endpoints. Customizing projects this way ensures they're automatically updated when new versions of their base processes are released with Azure DevOps Services upgrades. For more information, see [Customize your work-tracking experience](../reference/customize-work.md). @@ -174,46 +166,22 @@ For more information, see [Customize your work-tracking experience](../reference ## Analytics and reporting -Azure DevOps Services and Azure DevOps Server offer the following tools that give you insight into the progress and quality of your software projects: - -**Azure DevOps Server 2019 to Azure DevOps Services** - -- [Dashboards](../report/dashboards/dashboards.md) and lightweight [charts](../report/dashboards/charts.md) that are available in both the cloud and on-premises platforms. These tools are easy to set up and use. -- [The Analytics service](../report/powerbi/what-is-analytics.md) and [Analytics widgets](../report/dashboards/analytics-widgets.md). The Analytics service is optimized for fast read-access and server-based aggregations. -- [Microsoft Power BI integration](../report/powerbi/overview.md), which supports getting Analytics data into Power BI reports and provides a combination of simplicity and power. -- [OData support](../report/extend-analytics/quick-ref.md), which allows you to directly query the Analytics service from a supported browser, and then use the returned JSON data as you want. You can generate queries that span many projects or your entire organization. To learn more about the Analytics service, see our [Reporting roadmap](../report/powerbi/reporting-roadmap.md). - -**Azure DevOps Server 2018** - -- [Dashboards](../report/dashboards/dashboards.md) and lightweight [charts](../report/dashboards/charts.md) that are available in both the cloud and on-premises platforms. These tools are easy to set up and use. -- [SQL Server Reporting Services (SSRS) reports](/previous-versions/azure/devops/report/sql-reports/reporting-services-reports) are available when Azure DevOps Server is configured with SQL Server Analysis Services. - - - -## Visual Studio Team Services is now Azure DevOps Services +Azure DevOps Services and Azure DevOps Server offer various tools to provide insight into the progress and quality of your software projects. These tools include: -Many of the featured services in VSTS are now offered as standalone services in both Azure DevOps Services and Azure DevOps Server 2019 and up. You can get services separately or all together as Azure DevOps Services. If you're an Azure DevOps subscriber, you have access to all of the services already. +- **Dashboards and lightweight charts:** Available on both cloud and on-premises platforms, these tools are easy to set up and use. Dashboards provide a customizable overview of your project's status, while charts offer visual representations of key metrics and trends. -| VSTS feature name | Azure DevOps service name | Description | -|----------------------|----------------------|-------------| -| Build & release | Azure Pipelines | Continuous integration and continuous delivery (CI/CD) that works with any language, platform, and cloud. | -| Code | Azure Repos | Unlimited cloud-hosted private Git and Team Foundation Version Control (TFVC) repositories for your project. | -| Work | Azure Boards | Work tracking with Kanban boards, backlogs, team dashboards, and custom reporting. | -| Test | Azure Test Plans | All-in-one planned and exploratory testing solution. | -| Packages (extension) | Azure Artifacts | Maven, npm, Python, Universal Package, and NuGet package feeds from public and private sources. | +- **[The Analytics service](../report/powerbi/what-is-analytics.md) and [Analytics widgets](../report/dashboards/analytics-widgets.md):** Optimized for fast read-access and server-based aggregations, the Analytics service helps you gain deeper insights into your project's data. Analytics widgets can be added to your dashboards to display real-time data and trends. -Azure DevOps Services and Azure DevOps Server 2019 and up use the new navigation user interface, with a vertical sidebar to go to the main service areas: **Boards**, **Repos**, **Pipelines**, **Artifacts**, **Test Plans**, and more. For more information, see [Web portal navigation in Azure DevOps](../project/navigation/index.md). +- **[Microsoft Power BI integration](../report/powerbi/overview.md):** This integration allows you to bring Analytics data into Power BI reports, combining simplicity and power. With Power BI, you can create interactive and visually appealing reports that provide a comprehensive view of your project's performance. -> [!NOTE] -> You can disable select services from the user interface. For more information, see [Turn a service on or off](../organizations/settings/set-services.md). +- **[OData support](../report/extend-analytics/quick-ref.md):** OData support enables you to directly query the Analytics service from a supported browser and use the returned JSON data as needed. You can generate queries that span multiple projects or your entire organization, providing flexibility in how you analyze and utilize your data. For more information about the Analytics service, see our [Reporting roadmap](../report/powerbi/reporting-roadmap.md). -You can still use `visualstudio.com` to access Azure DevOps Services. We've moved to the new `dev.azure.com` domain name as the primary URL for new organizations. That URL is `https://dev.azure.com/{your organization}/{your project}`. If you want to change your URL to be based on `dev.azure.com` as the primary, an organization administrator can do so from the organization settings page. +These tools offer robust capabilities for monitoring, analyzing, and reporting on the progress and quality of your software projects, helping you make informed decisions and drive continuous improvement. ## Related articles -- [Essential services](services.md) -- [Client-server tools](tools.md) -- [Software development roles](roles.md) -- [Pricing for Azure DevOps Services](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) -- [Pricing for Azure DevOps Server](https://azure.microsoft.com/pricing/details/devops/server/) - \ No newline at end of file +- Explore [essential services](services.md) +- Discover [client-server tools](tools.md) +- Understand [software development roles](roles.md) +- Check [pricing for Azure DevOps Services](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) +- Check [pricing for Azure DevOps Server](https://azure.microsoft.com/pricing/details/devops/server/) diff --git a/docs/user-guide/add-run-manual-tests.md b/docs/user-guide/add-run-manual-tests.md index a7d6b4789f7..3ad11da16f1 100644 --- a/docs/user-guide/add-run-manual-tests.md +++ b/docs/user-guide/add-run-manual-tests.md @@ -1,10 +1,8 @@ --- title: Add, run, update inline tests titleSuffix: Azure DevOps -ms.custom: seodec18 description: Learn how to add, run, and quickly update manual test cases ms.subservice: azure-devops-new-user -ms.assetid: ms.author: chcomley author: chcomley ms.date: 04/23/2019 @@ -18,13 +16,13 @@ monikerRange: '<= azure-devops' Learn how to add, run, update, and expand and collapse inline tests in Azure DevOps. -To start manual testing, add the test to the user story or bug that you want to test. From the Kanban board, you can define inline tests or a set of manual tests for a backlog item. You also can run these tests and update their status. If you're new to working with the Kanban board, see the [Kanban quickstart](../boards/boards/kanban-quickstart.md). +To start manual testing, add the test to the user story or bug that you want to test. From the board, you can define inline tests or a set of manual tests for a backlog item. You also can run these tests and update their status. If you're new to working with the board, see the [Board quickstart](../boards/boards/kanban-quickstart.md). -Tests you create from the Kanban board are automatically linked to the user story or backlog item. +Tests you create from the board are automatically linked to the user story or backlog item. -## Open your Kanban board +## Open your board -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. From your web browser, open the project for your organization and select **Azure Boards**. If you don't have a project, [create one now](../organizations/projects/create-project.md). If you haven't been added as a team member, [get invited now](../organizations/security/add-users-team-project.md). @@ -32,29 +30,15 @@ Tests you create from the Kanban board are automatically linked to the user stor If you don't see the team or project you want, select ![Azure DevOps icon](../media/icons/project-icon.png) **Azure DevOps** to [browse all projects and teams](../project/navigation/work-across-projects.md). -2. Select **Boards** to open the Kanban board. +2. Select **Boards** to open the board. ![Azure Boards](media/azure-devops-boards-board.png) ::: moniker-end -::: moniker range="tfs-2018" - -1. From your web browser, open the project for your organization and select **Azure Boards**. If you don't have a project, [create one now](../organizations/projects/create-project.md). If you haven't been added as a team member, [get invited now](../organizations/security/add-users-team-project.md). - - The URL follows this pattern: ```https://dev.azure.com/fabrikamfiber/_backlogs/board``` - - If you don't see the team or project you want, select ![Azure DevOps icon](../media/icons/project-icon.png) **Azure DevOps** to [browse all projects and teams](../project/navigation/work-across-projects.md). - -2. Select **Board** to open the Kanban board. - - ![Azure DevOps backlogs board](media/azure-devops-backlogs-board.png) - -::: moniker-end - ## Add tests -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" 1. To add tests, open the menu for a work item. @@ -72,37 +56,9 @@ Tests you create from the Kanban board are automatically linked to the user stor To add details to the test case, open it. You can select the title, double-select the inline item, or open the context menu and choose **Open**. - ![Open test case from Kanban board](media/open-test-case-form-from-kanban-board.png) + ![Open test case from board](media/open-test-case-form-from-kanban-board.png) -To learn more about how to define tests, see [Create manual tests](../test/create-test-cases.md). - -Before you run the test, you must add details. - -::: moniker-end - -::: moniker range="tfs-2018" - -1. To add tests, open the menu for the work item. - - Open the context menu of a backlog item to add inline test case - - Inline tests are the same as test cases in a test suite. A default test plan and test suite automatically get created under which the manual test cases are grouped. - - For example, a test suite gets created for each user story, and all inline tests are added to that suite. The following user story 152 is highlighted. It has three manual tests defined with the IDs 153, 155, and 161. - - Inline test cases get added to test suites and test plans - - To learn more about test plans and test suites, see [Plan your tests](../test/create-a-test-plan.md). - -2. If you have a number of tests to add, enter each title and select **Enter**. - - Work item with several test cases added - - To add details to the test case, open it. You can select the title, double-select the inline item, or open the context menu and choose **Open**. - - Open test case form from Kanban board - -To learn more about how to define tests, see [Create manual tests](../test/create-test-cases.md). +For more information about how to define tests, see [Create manual tests](../test/create-test-cases.md). Before you run the test, you must add details. @@ -112,7 +68,7 @@ Before you run the test, you must add details. ## Run a test -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" Run the test by selecting ![Run icon](../boards/media/icons/run_query.png) **Run test** from the ![Actions icon](../boards/media/icons/actions-icon.png) actions menu for the inline test. @@ -121,18 +77,9 @@ Run the test by selecting ![Run icon](../boards/media/icons/run_query.png) **Run Microsoft Test Runner starts in a new browser instance. For information on how to run a test, see [Run manual tests](../test/run-manual-tests.md). ::: moniker-end -::: moniker range="tfs-2018" - -Run the test by selecting ![Run icon](../boards/media/icons/run_query.png) **Run test** from the ![Actions icon](../boards/media/icons/actions-icon.png) actions menu for the inline test. - -Run a test - -Microsoft Test Runner starts in a new browser instance. For information on how to run a test, see [Run manual tests](../test/run-manual-tests.md). -::: moniker-end - ## Update the status of a test -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" You can update the status of the test from the ![Actions icon](../boards/media/icons/actions-icon.png) actions menu. @@ -142,21 +89,11 @@ When you update the status of tests, you can [track test results](../test/track- ::: moniker-end -::: moniker range="tfs-2018" - -You can update the status of the test from the ![Actions icon](../boards/media/icons/actions-icon.png) actions menu. - - ![Pass test](media/pass-test.png) - -When you update the status of tests, you can [track test results](../test/track-test-status.md). - -::: moniker-end - ## Expand or collapse inline tests -::: moniker range=">= azure-devops-2019" +::: moniker range="<=azure-devops" -When you first open the Kanban board, you'll see an unexpanded view of checklists and tests. +When you first open the board, you'll see an unexpanded view of checklists and tests. ![Inline tests collapsed](media/azure-devops-boards-board.png) @@ -166,22 +103,10 @@ Select the inline test summary to expand a collapsed set of tests. Select the sa ::: moniker-end -::: moniker range="tfs-2018" - -When you first open the Kanban board, you'll see an unexpanded view of checklists. - - ![Inline tests collapsed](../boards/boards/media/i-test-open-board-collapsed-tests.png) - -Select the inline test summary to expand a collapsed set of tests. Select the same summary to collapse an expanded list. - - ![Inline tests expanded](../boards/boards/media/i-test-expanded-test-list.png) - -::: moniker-end - ## Next steps > [!div class="nextstepaction"] -> [Kanban quickstart](../boards/boards/kanban-quickstart.md) +> [Board quickstart](../boards/boards/kanban-quickstart.md) ## Related articles - [Learn more about test case management](../test/create-test-cases.md) @@ -189,5 +114,3 @@ Select the inline test summary to expand a collapsed set of tests. Select the sa - [Essential services](services.md) - [Client-server tools](tools.md) - [Software development roles](roles.md) - - diff --git a/docs/user-guide/capture-browser-trace.md b/docs/user-guide/capture-browser-trace.md new file mode 100644 index 00000000000..bb103367c7a --- /dev/null +++ b/docs/user-guide/capture-browser-trace.md @@ -0,0 +1,99 @@ +--- +title: Capture a browser trace for troubleshooting +titleSuffix: Azure DevOps +description: Capture network information from a browser trace to help troubleshoot issues with Azure DevOps. +ms.assetid: +ms.author: chcomley +author: chcomley +ms.topic: how-to +ms.date: 01/27/2025 +monikerRange: '<= azure-devops' +--- + +# Capture a browser trace for troubleshooting + +If you're troubleshooting an issue with Azure DevOps and need to contact [Microsoft Support](provide-feedback.md), capture additional information such as a browser trace, step recording, and console output. This data provides important details about what is happening in Azure DevOps when the issue occurs. + +A HAR (HTTP Archive) file tracks information between a web browser and a website. It contains detailed performance data about web pages, including resources loaded, time taken for each resource, and any errors encountered. Sharing a HAR file with Microsoft Support can help diagnose and resolve issues more effectively. + +> [!WARNING] +> Browser traces often contain sensitive information and might include authentication tokens linked to your identity. Remove any passwords before sharing traces with others. Handle these HAR files with care to ensure the security and privacy of the contained information. Microsoft support uses these traces for troubleshooting purposes only. + +## Prerequisites + +[!INCLUDE [prerequisites-project-member-only](../includes/prerequisites-project-member-only.md)] + +## Generate HAR file and record browser activity + +You can capture this information from Microsoft Edge or Google Chrome. Steps for each browser are shown as follows. + +# [Microsoft Edge](#tab/microsoft-edge) + +The following steps show how to use the developer tools in Microsoft Edge. For more information, see [Microsoft Edge DevTools](/microsoft-edge/devtools-guide-chromium). + +> [!NOTE] +> The screenshots in this article show the DevTools in Focus Mode with a vertical **Activity Bar**. Depending on your settings, your configuration might look different. For more information, see [Simplify DevTools using Focus Mode](/microsoft-edge/devtools-guide-chromium/experimental-features/focus-mode). + +1. In your browser, select **F12** > **Open DevTools**. +2. Select :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: **more actions**. + + :::image type="content" source="media/capture-browser-trace/microsoft-edge-select-more-actions.png" alt-text="Screenshot shows three dots highlighted for selection, more actions."::: + +3. Select **Settings**. + + :::image type="content" source="media/capture-browser-trace/microsoft-edge-settings.png" alt-text="Screenshot shows highlighted Settings selection."::: + +4. Under **Preferences**, scroll to the **Network** section and enter a check in the box next to **Allow to generate HAR with sensitive data**. + + :::image type="content" source="media/capture-browser-trace/microsoft-edge-network-preferences.png" alt-text="Screenshot shows checkmark next to Microsoft Edge network preference, Allow to generate HAR with sensitive data."::: + +5. Close the settings menu. +6. Ensure the **Network** tab is set to **Preserve log** and is capturing traffic. + + :::image type="content" source="media/capture-browser-trace/microsoft-edge-network-tab-check-preserve-log.png" alt-text="Screenshot shows check next to Preserve log in Network tab in Microsoft Edge."::: + +7. Go to the step before where the issue occurs. +8. Record the steps you take in Azure DevOps using [Steps Recorder](https://support.microsoft.com/windows/record-steps-to-reproduce-a-problem-46582a9b-620f-2e36-00c9-04e25d784e47). Steps Recorder doesn't automatically start recording HAR traces in DevTools, so make sure to start the recording in DevTools, too. +9. When you're done recording, stop recording in Step Recorder. In DevTools, stop recording and long press **Export** so that it shows a menu. If you only do a short press, a sanitized version of the HAR gets exported, which is missing information needed for troubleshooting. + +10. Select **Export HAR (with sensitive data)**. + + :::image type="content" source="media/capture-browser-trace/microsoft-edge-export-har-with-sensitive-data.png" alt-text="Screenshot shows highlighted selection Export HAR with sensitive data in Microsoft Edge."::: + +11. (Optional) Uncheck the "Allow to generate HAR with sensitive data" box when you're done. + +# [Google Chrome](#tab/google-chrome) + +The following steps show how to use the developer tools in Google Chrome. For more information, see [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools). + +1. In your browser, select **F12**. +2. Select :::image type="icon" source="../media/icons/gear-icon.png" border="false"::: **Settings**. + + :::image type="content" source="media/capture-browser-trace/google-chrome-gear.png" alt-text="Screenshot shows a gear highlighted for selection, more actions."::: + +3. Under Preferences, scroll to the Network section, and enter a check in the box next to **Allow to generate HAR with sensitive data**. + + :::image type="content" source="media/capture-browser-trace/google-chrome-network-preferences.png" alt-text="Screenshot shows checkmark next to Google Chrome network preference, Allow to generate HAR with sensitive data."::: + +4. Close the settings menu. +5. Ensure the **Network** tab is set to **Preserve log** and is capturing traffic. + + :::image type="content" source="media/capture-browser-trace/google-chrome-network-tab-check-preserve-log.png" alt-text="Screenshot shows check next to Preserve log in Network tab in Google Chrome."::: + +6. Go to the step before where the issue occurs. +7. Start recording the steps you take in Azure DevOps, using [Steps Recorder](https://support.microsoft.com/windows/record-steps-to-reproduce-a-problem-46582a9b-620f-2e36-00c9-04e25d784e47). +8. When you're done recording, long press the export button so that it shows a menu. If you only do a short press, a sanitized version of the HAR gets exported, which is missing information needed for troubleshooting. +9. Select **Export HAR (with sensitive data)**. + + :::image type="content" source="media/capture-browser-trace/google-chrome-export-har-with-sensitive-data.png" alt-text="Screenshot shows highlighted selection, Export HAR (with sensitive data), in Google Chrome."::: + +10. (Optional) Uncheck the "Allow to generate HAR with sensitive data" box when you're done. + +--- + +You have a complete HAR file with the necessary data for troubleshooting. + +## Related articles + +- [Access Azure DevOps troubleshooting documentation](/troubleshoot/azure/devops/welcome-azure-devops) +- [Get support and provide feedback](provide-feedback.md) diff --git a/docs/user-guide/code-with-git.md b/docs/user-guide/code-with-git.md index 09d3259f815..429f1fdc4e5 100644 --- a/docs/user-guide/code-with-git.md +++ b/docs/user-guide/code-with-git.md @@ -1,39 +1,32 @@ --- title: Code with Git titleSuffix: Azure DevOps -ms.custom: seodec18, engagement-fy23 -description: Learn how to share code within a Git repo and project. -ms.assetid: +ms.custom: engagement-fy23 +description: Follow these steps to share code within a Git repo and project in Azure DevOps. ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley -ms.date: 10/07/2022 -ms.topic: quickstart +ms.date: 10/18/2024 +ms.topic: how-to monikerRange: '<= azure-devops' --- -# Code with Git +# Share your code with Git [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Learn how to share your code with others when you use a Git repository. +Share your code with others in Azure DevOps when you use a Git repository. ## Prerequisites -You must have an [organization](../organizations/accounts/create-organization.md) and [project](../organizations/projects/create-project.md) in Azure DevOps. When you create a project, Azure DevOps automatically creates an empty repository in Repos. +| Category | Requirements | +|--------------|-------------| +| **Project access** | [Project member](../organizations/security/add-users-team-project.md). | +|Git command-line tool | One of the following Git command-line tools:
      - [Git for Windows and Git Credential Manager](../repos/git/set-up-credential-managers.md).
      - [Git for macOS or Linux](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). For macOS and Linux, we recommend that you [configure SSH authentication](../repos/git/use-ssh-keys-to-authenticate.md).| -## 1. Install Git command-line tools +## 1. Clone the repo to your computer -Install one of the following Git command-line tools: - - - To install Git for Windows, including Git Credential Manager, see [Install the Git Credential Manager](../repos/git/set-up-credential-managers.md). - - To install on macOS or Linux, check out the [Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) chapter in the open-source _Pro Git_ book. For macOS and Linux, we recommend that you [configure SSH authentication](../repos/git/use-ssh-keys-to-authenticate.md). - -## 2. Clone the repo to your computer - -To work with a Git repo, you clone it to your computer, which creates a complete local copy of the repo for you to work with. Your code might be in one of several places. - -::: moniker range=">= azure-devops-2019" +To work with a Git repo, clone it to your computer, which creates a complete local copy of the repo. Your code might be in one of several places. 1. Complete the following step that's applicable to your scenario: @@ -45,11 +38,15 @@ To work with a Git repo, you clone it to your computer, which creates a complete ![Screenshot of project with Repos and Files highlighted.](media/clone-repo/repos-files.png) -3. Select **Clone** in the upper-right corner of the **Code** window and copy the URL. - - ![Screenshot of project with Copy icon highlighted.](media/code-with-git-clone-repo.png) +3. Select **Clone**. + + :::image type="content" source="media/clone-repo/repos-files-clone-button.png" alt-text="Screenshot shows highlighted clone button in repos files."::: + +4. **Copy** the URL. + + :::image type="content" source="media/clone-repo/copy-url-clone-action.png" alt-text="Screenshot shows highlighted copy icon for copying URL."::: -4. Open the Git command window (Git Bash on Git for Windows). Go to the folder where you want the code from the repo stored on your computer, and run `git clone`, followed by the path copied from **Clone URL** in the previous step. See the following example: +5. Open the Git command window (Git Bash on Git for Windows). Go to the folder where you want the code from the repo stored on your computer, and run `git clone`, followed by the path copied from **Clone URL** in the previous step. See the following example: ``` git clone https://FabrikamFiber01@dev.azure.com/FabrikamFiber01/FabrikamFiber01-01/_git/FabrikamFiber01-01 @@ -57,7 +54,7 @@ To work with a Git repo, you clone it to your computer, which creates a complete Git downloads a copy of the code, including all [commits](../repos/git/commits.md), and [branches](../repos/git/branch-policies-overview.md) from the repo, into a new folder for you to work with. -5. Switch your directory to the repository that you cloned. +6. Switch your directory to the repository that you cloned. ``` cd fabrikam-web @@ -65,41 +62,7 @@ To work with a Git repo, you clone it to your computer, which creates a complete Keep this command window open to work in a branch. -::: moniker-end - -::: moniker range="tfs-2018" - -1. Complete the following step that's applicable to your scenario: - - - If **You don't have any code yet**, first [Create a new Git repo in your project](../repos/git/create-new-repo.md#create-a-repo-using-the-web-portal), and then complete the next step. - - If **the code is in another Git repo**, such as a GitHub repo or a different Azure Repo instance, [import it into a new or existing empty Git repo](../repos/git/import-git-repository.md), and then complete the next step. - - If **the code is on your local computer and not yet in version control**, either [create a new Git repo in your project](../repos/git/create-new-repo.md#create-a-repo-using-the-web-portal) or add your code to an existing repository. - -2. From your web browser, open the project for your organization, and select **Code**. - -3. Select **Clone** in the upper-right corner of the Code window, and copy the URL. - - ![Screenshot of project in web browser, with Copy icon highlighted.](media/code-with-git-clone-repo-prev.png) - -4. Open the Git command window (Git Bash on Git for Windows). Go to the folder where you want the code from the repo stored on your computer, and run `git clone`, followed by the path copied from **Clone URL** in the previous step. See the following example: - - ``` - git clone https://contoso-ltd.visualstudio.com/MyFirstProject/_git/contoso-demo - ``` - - Git downloads a copy of the code in a new folder for you to work with. The download includes all [commits](../repos/git/commits.md) and [branches](../repos/git/branch-policies-overview.md) from the repo. - -5. Switch your directory to the repository that you cloned. - - ``` - cd contoso-demo - ``` - - Keep the command window open to work in a branch. - -::: moniker-end - -## 3. Work in a branch +## 2. Work in a branch Git [branches](../repos/git/branch-policies-overview.md) isolate your changes from other work being done in the project. We recommend using the [Git workflow](../repos/git/gitworkflow.md), which uses a new branch for every feature or fix that you work on. For our examples, we use the branch, `users/jamal/feature1`. @@ -110,8 +73,7 @@ Git [branches](../repos/git/branch-policies-overview.md) isolate your changes fr ``` This command creates a reference in Git for the new branch. It also creates a pointer back to the parent commit so Git can keep a history of changes as you add commits to the branch. - > [!TIP] - > If you're working with a previously cloned repository, ensure that you've checked out the right branch (`git checkout main`) and that it's up to date (`git pull origin main`) before you create your new branch. + If you're working with a previously cloned repository, ensure you checked out the right branch (`git checkout main`) and that it's up to date (`git pull origin main`) before you create your new branch. 2. Use `checkout` to switch to that branch. @@ -140,7 +102,7 @@ Git [branches](../repos/git/branch-policies-overview.md) isolate your changes fr > git checkout feature1 > ``` -## 4. Work with the code +## 3. Work with the code In the following steps, we make a change to the files on your computer, commit the changes locally, and then push the commit to the repo stored on the server. @@ -161,10 +123,9 @@ In the following steps, we make a change to the files on your computer, commit t The `git add .` command stages any new or changed files, and `git commit -m` creates a commit with the specified commit message. - > [!TIP] - > Check what branch you're working on before you commit, so that you don't commit changes to the wrong branch. Git always adds new commits to the current local branch. + Check which branch you're working on before you commit, so that you don't commit changes to the wrong branch. Git always adds new commits to the current local branch. -4. Push your changes to the Git repo on the server. Enter the following command into the Git command window: +1. Push your changes to the Git repo on the server. Enter the following command into the Git command window: ``` git push origin users/jamal/feature1 @@ -172,23 +133,19 @@ In the following steps, we make a change to the files on your computer, commit t Your code is now shared to the remote repository, in a branch named `users/jamal/feature1`. To merge the code from your working branch into the `main` branch, use a pull request. -## 5. Merge your changes with a pull request +## 4. Merge your changes with a pull request Pull requests combine the review and merge of your code into a single collaborative process. After you’re done fixing a bug or new feature in a branch, create a new pull request. Add the members of the team to the pull request so they can review and vote on your changes. Use pull requests to review works in progress and get early feedback on changes. There’s no commitment to merge the changes because you can abandon the pull request at any time. The following example shows the basic steps of creating and completing a pull request. -::: moniker range=">= azure-devops-2019" - 1. Open the team project for your organization in your web browser and select **Repos** > **Files**. If you kept your browser open after getting the clone URL, you can just switch back to it. - ![Repos files](media/clone-repo/repos-files.png) - 2. Select **Create a pull request** in the upper-right corner of the **Files** window. If you don't see a message like **You updated users/jamal/feature1 just now**, refresh your browser. ![Create a pull request](../repos/get-started/media/updated-file-create-pull-request.png) - New pull requests are configured to merge your branch into the default branch, which in this example is `main`. The title and description are pre-populated with your commit message. + New pull requests are configured to merge your branch into the default branch, which in this example is `main`. The title and description are prepopulated with your commit message. ![New pull request](../repos/get-started/media/create-pull-request.png) @@ -213,42 +170,10 @@ The following example shows the basic steps of creating and completing a pull re >[!NOTE] >This example shows the basic steps of creating and completing a pull request. For more information, see [Create, view, and manage pull requests](../repos/git/pull-requests.md). -::: moniker-end - -::: moniker range="tfs-2018" - -1. Open the team project for your organization from your web browser and select the **Code** page. - -2. Select **Clone** in the upper-right corner of the **Code** page and copy the **Clone URL**. - - ![Retrieve the clone URL](media/code-with-git-clone-repo.png) - -3. Open the Git command window, for example Git Bash on Git for Windows, and browse to the folder where the repo is stored on your computer. - - Run `git clone` followed by the path copied from the **Clone URL** in the previous section, as shown in the following example. - - ``` - git clone https://dev.azure.com/contoso-ltd/MyFirstProject/_git/contoso-demo - ``` - - Git downloads a copy of the code into a new folder for you to work with. The download includes all [commits](../repos/git/commits.md) and [branches](../repos/git/branch-policies-overview.md) from the repo. - -4. Switch your directory to the repository that you cloned. - - ``` - cd fabrikam-web - ``` - - Keep this command window open, because you'll use it in the following steps. - -::: moniker-end - Your changes are now merged into the `main` branch, and your `users/jamal/feature1` branch is deleted on the remote repository. ## View history -::: moniker range=">= azure-devops-2019" - 1. Switch back to the web portal and select **History** from the **Code** page to view your new commit. ![Screenshot of web portal, with History highlighted](media/code-history-vert.png) @@ -257,23 +182,9 @@ Your changes are now merged into the `main` branch, and your `users/jamal/featur ![Screenshot of README file](media/first-edit-readme-file.png) -::: moniker-end - -::: moniker range="tfs-2018" - -1. Switch back to the web portal, and select **History** from the **Code** tab to view your new commit. Two commits appear: the first commit, where the README and .gitignore were added upon repo creation, and the commit you just made. - - ![View commit history](../repos/git/media/repo-mgmt/commit-push.png) - -2. Switch to the **Files** tab, and select the README file to view your changes. - - ![View changed file](../repos/git/media/repo-mgmt/readme-changed-file.png) - -::: moniker-end - ## Clean up -Switch back to your Git Bash command prompt and run the following command to delete your local copy of the branch. +To delete your local copy of the branch, switch back to your Git Bash command prompt and run the following command: ``` git checkout main @@ -293,7 +204,7 @@ This action completes the following tasks: > ## Related articles -- [Key concepts for new users to Azure Pipelines](../pipelines/get-started/key-pipelines-concepts.md) -- [What is Azure Repos?](../repos/get-started/what-is-repos.md) -- [Learn more about working with a Git repo](../repos/git/index.yml) -- [What is source control?](source-control.md) +- [Understand key concepts for new users to Azure Pipelines](../pipelines/get-started/key-pipelines-concepts.md) +- [Discover what Azure Repos is](../repos/get-started/what-is-repos.md) +- [Learn how to work with a Git repo](../repos/git/index.yml) +- [Explore what source control is](source-control.md) diff --git a/docs/user-guide/devops-alm-overview.md b/docs/user-guide/devops-alm-overview.md index 34df57d98ad..101981b27d5 100644 --- a/docs/user-guide/devops-alm-overview.md +++ b/docs/user-guide/devops-alm-overview.md @@ -1,13 +1,12 @@ --- -title: DevOps tools overview for Azure DevOps +title: DevOps tools overview for Azure DevOps titleSuffix: Azure DevOps -ms.custom: seodec18 description: Guide to getting started using DevOps and Agile tools provided by Azure DevOps Services and Azure DevOps Server ms.subservice: azure-devops-new-user -ms.assetid: 0C0261DC-57B7-4520-82A4-2C2AB7AB0F4A +ms.assetid: 0C0261DC-57B7-4520-82A4-2C2AB7AB0F4A ms.author: chcomley -author: chcomley -ms.date: 01/31/2022 +author: chcomley +ms.date: 01/31/2022 monikerRange: '<= azure-devops' --- @@ -55,10 +54,9 @@ You can develop your code in Android Studio, Eclipse, IntelliJ, Visual Studio, V Git is a distributed version control system. Each developer has a copy of the source repository on their dev machine. Developers can commit each set of changes on their dev machine and perform version control operations such as history and compare without a network connection. Branches are lightweight. -[![Android Studio](media/overview/code-git-android-studio-1.png)](/previous-versions/azure/devops/all/java/download-android-studio-plug-in)      [![Eclipse](media/overview/code-git-eclipse-2.png)](../repos/git/share-your-code-in-git-eclipse.md)      [![IntelliJ](media/overview/code-git-intellij-3.png)](/previous-versions/azure/devops/all/java/download-intellij-plug-in) +[![Android Studio](media/overview/code-git-android-studio-1.png)](/previous-versions/azure/devops/all/java/download-android-studio-plug-in)     [![Eclipse](media/overview/code-git-eclipse-2.png)](../repos/git/share-your-code-in-git-eclipse.md)     [![IntelliJ](media/overview/code-git-intellij-3.png)](/previous-versions/azure/devops/all/java/download-intellij-plug-in) -
      -      Visual Studio      Visual Studio Code      Xcode +[![Visual Studio](media/overview/code-git-visual-studio.png)](../repos/git/share-your-code-in-git-vs.md)     [![Visual Studio Code](media/overview/code-git-visual-studio-code.png)](https://code.visualstudio.com/docs/editor/versioncontrol) [![Xcode](media/overview/code-git-xcode.png)](../repos/git/share-your-code-in-git-xcode.md) ### TFVC @@ -126,11 +124,11 @@ Once you've signed up for Azure DevOps Services or installed Azure DevOps Server ### Azure DevOps Server updates - [What's new](/azure/devops/server/whats-new) -- [Migrate data from TFS to Azure DevOps Services](../migrate/migrate-from-tfs.md) +- [Migrate data from Azure DevOps Server to Azure DevOps Services overview](../migrate/migration-overview.md) ### Pricing, costs, and licenses -[Azure DevOps Services Pricing](https://visualstudio.microsoft.com/team-services/pricing/) provides per user costs. Small teams (5 users or fewer) can start for free. Unlimited Visual Studio subscribers are free. +[Azure DevOps Services Pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) provides per user costs. Small teams (5 users or fewer) can start for free. Unlimited Visual Studio subscribers are free. On-premises Azure DevOps Server provides three access levels: [Stakeholder, Basic, and Basic + Test Plans](../organizations/security/change-access-levels.md). You don't need to buy additional licenses for Visual Studio subscribers. Use the [Team Foundation Server pricing page](https://visualstudio.microsoft.com/team-services/tfs-pricing) to plan your licensing requirements. @@ -142,7 +140,7 @@ Our extensibility framework enables you to build integrations directly within Az With Marketplace extensions, you can create first-class integration experiences, such as a simple context menu or toolbar action. Or, you can create a complex, powerful full UI experience that seamlessly lights up within the Azure DevOps Services web portal. - [Find marketplace extensions](../marketplace/overview.md) -- [Get extensions](../marketplace/install-extension.md)

      • +- [Get extensions](../marketplace/install-extension.md)
      - [Using service hooks](../service-hooks/overview.md) - [Get started with REST APIs](/rest/api/azure/devops/) diff --git a/docs/user-guide/lookup-platform-version.md b/docs/user-guide/lookup-platform-version.md index 6bf3249b165..abaac78f560 100644 --- a/docs/user-guide/lookup-platform-version.md +++ b/docs/user-guide/lookup-platform-version.md @@ -1,13 +1,12 @@ --- title: Look up your Azure DevOps platform and version titleSuffix: Azure DevOps -ms.custom: seodec18 -description: Learn how to find the Azure DevOps platform and version you're using. +description: Learn how to find the Azure DevOps platform and version you're using. ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley ms.topic: troubleshooting -ms.date: 09/30/2022 +ms.date: 03/06/2024 monikerRange: '<= azure-devops' --- @@ -15,10 +14,9 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - + -You can tell what platform you use by opening the **About** page for Azure DevOps Services or Azure DevOps Server. - +You can tell which platform you use by opening the **About** page for Azure DevOps Services or Azure DevOps Server. ## Azure DevOps Services @@ -30,12 +28,11 @@ A page similar to the following example opens showing the version number. :::image type="content" source="media/provide-feedback/version-azure-devops.png" alt-text="Screenshot of About page for Azure DevOps Services."::: - ## Azure DevOps Server Open the **About** page from the profile menu as shown in the following image. -:::image type="content" source="media/provide-feedback/about-menu-selection-on-premises.png" alt-text="Screenshot of profile menu"::: +:::image type="content" source="media/provide-feedback/about-menu-selection-on-premises.png" alt-text="Screenshot of profile menu."::: The corresponding browser URL is: @@ -44,18 +41,26 @@ The corresponding browser URL is: A page similar to the following image opens showing the version number. :::image type="content" source="media/provide-feedback/version-azure-devops-on-premises.png" alt-text="Screenshot of About page for Azure DevOps Server on-premises."::: - -## Version numbers +For the most recent version details, refer to the following RTW Release Notes. You can also find Update 1 Release Notes and Secure Hash Algorithm (SHA) information in the table of contents from these links. +- [Azure DevOps Server 2022 Release Notes](/azure/devops/server/release-notes/azuredevops2022?view=azure-devops&preserve-view=true) + - [Update 1 Release Notes, Azure DevOps Server 2022](/azure/devops/server/release-notes/azuredevops2022u1?view=azure-devops&tabs=yaml&preserve-view=true) + - [SHA-256 Values](/azure/devops/server/release-notes/azuredevops2022-sha?view=azure-devops&preserve-view=true) +- [Azure DevOps Server 2020 Release Notes](/azure/devops/server/release-notes/azuredevops2020?view=azure-devops&preserve-view=true) + - [Update 1 Release Notes, Azure DevOps Server 2020](/azure/devops/server/release-notes/azuredevops2020u1?view=azure-devops&preserve-view=true) + - [SHA-1 Values](/azure/devops/server/release-notes/azuredevops2020-sha?view=azure-devops&preserve-view=true) +- [Azure DevOps Server 2019 Release Notes](/azure/devops/server/release-notes/azuredevops2019?view=azure-devops&preserve-view=true) + - [Update 1 Release Notes, Azure DevOps Server 2019](/azure/devops/server/release-notes/azuredevops2019u1?view=azure-devops&preserve-view=true) + - [SHA-1 Values](/azure/devops/server/release-notes/azuredevops2019-sha?view=azure-devops&preserve-view=true) + + \ No newline at end of file diff --git a/docs/user-guide/roles.md b/docs/user-guide/roles.md index d8a8e08c372..aeceba6ca3d 100644 --- a/docs/user-guide/roles.md +++ b/docs/user-guide/roles.md @@ -1,7 +1,6 @@ --- title: Supported roles for software development titleSuffix: Azure DevOps -ms.custom: seodec18 description: Understand how Azure DevOps tools support various software development roles ms.subservice: azure-devops-new-user ms.assetid: 4600B0D9-3799-4902-814B-F6EC9098C4CE @@ -58,7 +57,7 @@ Product owners typically plan the feature set to deliver, set priorities, and tr - Use the product backlog to quickly define and prioritize user stories, features, and other work items - Use the sprint backlog and task board to implement Scrum practices -- Use the Kanban board to work with Kanban methods +- Use your board to work with Kanban methods - Use queries to list and update work items, create status and trend charts, and post charts to dashboards - Use dashboards to share information, status, and trends with your team or organization @@ -86,7 +85,7 @@ To get started, see the overviews in [Azure Pipelines](../pipelines/get-started/ With Stakeholder access, anyone in your organization can check project status and provide feedback. Stakeholders can track project priorities and provide direction, feature ideas, and business alignment to a team. Stakeholders also contribute to plans by adding and modifying work items. They can't, however, contribute to the code base or exercise test tools. -Stakeholder access essentially provides free access to a limited set of feature to project sponsors and supporters. To learn more, see [Work as a Stakeholder](../organizations/security/get-started-stakeholder.md). +Stakeholder access essentially provides free access to a limited set of feature to project sponsors and supporters. For more information, see [Work as a Stakeholder](../organizations/security/get-started-stakeholder.md). @@ -121,14 +120,7 @@ Responsible for configuring project-level resources, including: - [Test](../test/how-long-to-keep-test-results.md) and [release](../pipelines/policies/retention.md) retention policies ::: moniker-end -::: moniker range="tfs-2018" - -- [Area paths](../organizations/settings/set-area-paths.md) and [iteration paths](../organizations/settings/set-iteration-paths-sprints.md) -- [Project permissions and repository security](../organizations/security/permissions.md) -- [Customizing work tracking objects](../reference/customize-work.md) -- [Build agents, pools, and service connections](../pipelines/get-started/what-is-azure-pipelines.md) -- [Test](../test/how-long-to-keep-test-results.md) and [release](../pipelines/policies/retention.md) retention policies -::: moniker-end + ::: moniker range="azure-devops" @@ -146,32 +138,7 @@ Responsible for configuring organization-level resources, including the followin To get started, see [Manage organizations](../organizations/accounts/organization-management.md) and [Settings](../organizations/settings/about-settings.md#project-administrator-role-and-managing-projects). ::: moniker-end -::: moniker range="tfs-2018" - -### Project Collection Administrators - -Responsible for configuring collection-level resources. These tasks include: - -- Add and manage projects -- Manage collection-level permissions -- Install and manage extensions - -To get started, see [Settings](../organizations/settings/about-settings.md#project-administrator-role-and-managing-projects). - -### Azure DevOps Server administrators -Responsible for installing, upgrading, and maintaining an on-premises Azure DevOps Server deployment, including the: - -- Install Azure DevOps Server -- Update servers running Azure DevOps Server -- Manage database backups -- Manage server administrative settings and permissions -- Build retention policies -- Add and manage project collections - -To get started, see [Server Administration (Azure DevOps Server)](/azure/devops/server/index). - -::: moniker-end ## Related articles diff --git a/docs/user-guide/service-limits.md b/docs/user-guide/service-limits.md deleted file mode 100644 index 14fddc2da16..00000000000 --- a/docs/user-guide/service-limits.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Service and rate limits -titleSuffix: Azure DevOps Services -description: Description of limits and rate limits on the Azure DevOps Service -ms.topic: conceptual -ms.subservice: azure-devops-new-user -ms.author: chcomley -author: chcomley -monikerRange: 'azure-devops' -ms.date: 01/03/2023 ---- - -# Service and rate limits for Azure DevOps Services - -[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] - -Azure DevOps Services, like many Software-as-a-Service solutions, uses multi-tenancy to reduce costs and to enhance scalability and performance. This leaves users vulnerable to performance issues and even outages when other users of their shared resources have spikes in their consumption. To combat these problems, Azure DevOps Services limits the resources individuals can consume and the number of requests they can make to certain commands. When these limits are exceeded, subsequent requests may be either delayed or blocked. - -This article specifies certain limits placed on the use and configuration of Azure DevOps services. For more information, see -[Rate limits](../integrate/concepts/rate-limits.md) and [Work tracking, process, and project limits](../organizations/settings/work/object-limits.md). - - -## Work items - -- A long text field can contain 1M characters. -- You can't assign more than 100 tags to a work item. -- You can't add more than 1,000 links to a work item. -- You can't add more than 100 attachments to a work item. -- You can't add an attachment size larger than 60 MB to a work item. -- You can have up to 1,000 tasks on a task board -- You can have up to 10,000 work items on a backlog -- You are limited to 5,000 teams in a project -- You can't create more than 150,000 tag definitions per project - - -## Area and iteration paths - -| Configuration object | Limit | -|--------|-------| -| Projects | 1000 per organization for Azure DevOps Services
      No prescribed limit for on-premises
      (See also [Work tracking, process, and project limits](../organizations/settings/work/object-limits.md#projects) | -| Teams | 5,000 per project | -| Work item tags | 150,000 tag definitions per organization | -| Area Paths | 10,000 per organization | -| Area Path Depth | 14 | -| Area Paths per team | 300 | -| Iteration Paths | 10,000 per organization | -| Iteration Path Depth | 14 | -| Iteration Paths per team | 300 | - - -## Queries - -- The execution time limit for queries is 30 seconds. See [Optimization best practices](../integrate/concepts/integration-bestpractices.md#optimize-queries) to improve query performance. -- Query results are limited to 20,000 -- Queries are limited in length to 32,000 characters - -## Process customization - -When customizing the work item types (WITs) defined in the Inheritance or Hosted XML process models, be aware of the limits placed on objects defined in [Work tracking, process, and project limits](../organizations/settings/work/object-limits.md). - -## Dashboards - -A limit is placed on 500 dashboards per project. - -## Wiki - -In addition to the usual repository limits (see the [Repository Size Limits](../repos/git/limits.md#repository-size)), Wikis defined for a project are limited to 25 MB per single file. - -## Data import -- Limited to 300 projects per organization -- See [data import documentation](../migrate/migration-overview.md) for details - -## Service connections - -There are no per-project limits placed on creating service connections. However, there may be limits which are imposed through Azure Active Directory. For additional information, review the following articles: - -- [Azure AD service limits and restrictions](/azure/active-directory/enterprise-users/directory-service-limits-restrictions) -- [Azure subscription and service limits, quotas, and constraints](/azure/azure-resource-manager/management/azure-subscription-service-limits) - - -## Related articles - -- [Rate limits](../integrate/concepts/rate-limits.md) -- [Work tracking, process, and project limits](../organizations/settings/work/object-limits.md) -- [Configure and customize Azure Boards](../boards/configure-customize.md) -- [Usage monitoring](../organizations/accounts/usage-monitoring.md) diff --git a/docs/user-guide/service-status-info.md b/docs/user-guide/service-status-info.md index a1f0030401b..0ad8b8f557b 100644 --- a/docs/user-guide/service-status-info.md +++ b/docs/user-guide/service-status-info.md @@ -8,83 +8,52 @@ ms.assetid: 3F3BD90B-1D08-4C8F-9CDC-D4B806F65448 ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 03/02/2022 +ms.date: 07/24/2024 --- # Azure DevOps Services status [!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] -We have a team of engineers around the world who look after the -health of Azure DevOps 24 hours a day. Their primary goal is to ensure -that our customers are always productive and successful with our service. -From time to time, like any online service, our service experiences performance -slowdowns and stability issues. In these cases, we aim to respond quickly to -restore the service. It's our top priority to communicate the incident -status and our next steps to mitigate the issue. We do so through the -[Azure DevOps Services status portal](https://status.dev.azure.com). +Our team of engineers around the world work 24/7 to ensure that our customers are always productive and successful with our service. We respond quickly during performance slowdowns and stability issues. Our top priority is to communicate the incident status and our next steps to mitigate the issue. Check the status of our services through the [Azure DevOps Services status portal](https://status.dev.azure.com). -If you're experiencing a problem with any of our Azure DevOps Services, you can check the -service health to determine if we're already working on the issue. Many of the events we post are based on our -Customer Impact Assessment (CIA). The CIA is modeled after our availability model -that measures real customer experiences representing both reliability and performance. +Our Customer Impact Assessment (CIA) is modeled after our availability model, which measures real customer experiences representing both reliability and performance. Many of the events we post are based on the CIA. -## Services within the product suite +## Services health matrix -[Azure DevOps](https://azure.microsoft.com/services/devops/) is a product suite of service offerings. The [geographic region](https://azure.microsoft.com/global-infrastructure/geographies/) indicates where an organization is hosted in the cloud. The data residency, sovereignty, compliance, -and resilience requirements are honored within the geographical boundaries. +[Azure DevOps](https://azure.microsoft.com/services/devops/) is a product suite of service offerings. The [geography](https://azure.microsoft.com/global-infrastructure/geographies/) indicates where an organization is hosted in the cloud. The data residency, sovereignty, compliance, +and resilience requirements are honored within the geographical boundaries. To help clarify which specific aspects of the service are affected, we communicate impact of each of these services by geography in the service matrix. -In addition to the specific Azure DevOps Services, the matrix also displays two other -categories: **Core** and **Other**. The **Core** category encompasses the set of features that are fundamental to all five services, such as authentication or the web portal. The **Other** category corresponds to features that complement the suite, such as extensions. - -For more information about pricing and acquisition, see the [pricing and acquisition page](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). - -## Service health matrix - -The service status portal provides a two-dimensional matrix view of active events mapped to a -given service and geography. To help clarify which specific aspects of the service are affected, -we communicate impact of each of these services by geographic region in the service matrix. +The [status portal](https://status.dev.azure.com) provides a two-dimensional matrix view of active events mapped to a given service and geography. In addition to the suite of **Azure DevOps Services**, it displays the following items: +- **Core services**: Encompass the set of features that are fundamental to all five services, such as authentication or the web portal +- **Other services**: Correspond to features that complement the suite, such as extensions ## Service health indicators -The Azure DevOps Services status portal indicates the status of Azure DevOps Services according to the following indicators. These indicators reflect the severity of a service health event based on the number of customers affected by the issue. Typically, the highest severity events impact a large percentage of our customers and render some parts of the product unusable. +The Azure DevOps Services status portal displays indicators that reflect the severity of a service health event, based on the number of customers affected by the issue. The highest severity events affect a large percentage of our customers and render some parts of the product unusable. :::image type="content" source="media/services-status/status-indicators.png" alt-text="Service status indicators"::: -- **Healthy**: Indicates the service is broadly available. -- **Degraded**: Indicates a lower-severity event that affects the performance of a service feature, but doesn't impact broad service availability. -- **Unhealthy**: Indicates a high-severity event that affects the performance of a service and its broad availability. -- **Advisory**: Indicates that a service is under investigation to determine the performance and availability impact. - +The Azure DevOps Services status portal displays four indicators that reflect the severity of a service health event: Healthy, Degraded, Unhealthy, and Advisory. The highest severity events affect a large percentage of our customers and render some parts of the product unusable. ## Service status and event logs -You can access more information on active events from the [Status history page](https://status.dev.azure.com/_history). This page provides a view into current active events and past events. Eave event under investigation or previously investigate is logged in the form of an event log. Each log has other associated information such as the impacted service, -geography, and event duration. Choose the provided hyperlink to view the event log, which provides detailed information on the event under investigation. - -You can also filter the logs to adjust the scope of your search into past events. -In addition, you can use the REST API build automated alerting solutions to help you stay on top of events. +Access detailed information on active and past events from the [Status history page](https://status.dev.azure.com/_history). Each event log contains associated information such as the impacted service, geography, and event duration. You can filter the logs to adjust the scope of your search into past events. Additionally, you can use the REST API to build automated alerting solutions to stay on top of events. ## When and how to report availability issues -If you're experiencing an issue with Azure DevOps and see a corresponding event that's communicated on the service health portal, we're already working to restore normal operations of the service. You don't need to do anything else to notify us. - -However, if you don't see your issue reported on the Azure DevOps Services health page, you can ask a question through the [Azure DevOps Services virtual support agent](https://azure.microsoft.com/support/devops/). - -For issues not related to availability, refer to our [Developer Community portal](https://developercommunity.visualstudio.com/report?space=21&entry=problem). +If you see an issue reported on the Azure DevOps Services health page, we’re already working to restore normal operations. If your issue isn't reported, you can ask a question through the [Azure DevOps Services virtual support agent](https://azure.microsoft.com/support/devops/). For issues not related to availability, refer to our [Developer Community portal](https://developercommunity.visualstudio.com/report?space=21&entry=problem). ## RSS feed -You can use [the RSS feed](https://status.dev.azure.com/_rss) to subscribe and receive information in your feed reader. +Subscribe to [the RSS feed](https://status.dev.azure.com/_rss) to receive updates in your feed reader. ## Use REST APIs to build automated solutions -The [Azure Resource health REST API](/rest/api/resourcehealth/) can retrieve the current health status of each of the Azure DevOps Services. You can use it to build an automated solution to [monitor the infrastructure incidents](/azure/service-health/service-health-overview). +The [Azure Resource health REST API](/rest/api/azure/devops/status) can retrieve the current health status of each of the Azure DevOps Services. You can use it to build an automated solution to monitor the infrastructure incidents. [!INCLUDE [rest-api-docs-rollout](../includes/rest-api-docs-rollout.md)] - ## Related articles -- [Azure Service Health overview](/azure/service-health/service-health-overview) - [Blog post: How do you measure quality of a service?](https://devblogs.microsoft.com/bharry/how-do-you-measure-quality-of-a-service/) diff --git a/docs/user-guide/services.md b/docs/user-guide/services.md index be8cc1bda68..c7b0daf6687 100644 --- a/docs/user-guide/services.md +++ b/docs/user-guide/services.md @@ -1,273 +1,219 @@ --- -title: Overview of services +title: Overview of Services titleSuffix: Azure DevOps -ms.custom: seodec18, engagement-fy23 -description: Understand the services provided in Azure DevOps. +ms.custom: engagement-fy23 +description: Understand the services provided in Azure DevOps, including Dashboards, Wiki, Boards, Repos, Pipelines, Test Plans, and Artifacts. ms.subservice: azure-devops-new-user ms.topic: overview ms.assetid: D861983F-CC66-4314-A3C6-E2F30A37923D ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 10/10/2022 +ai-usage: ai-assisted +ms.date: 04/22/2025 +#customer intent: As a developer, I want to understand the services provided in Azure DevOps so I can make the best use of the features for my projects. --- -# Overview of services +# What are the services in Azure DevOps? [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Azure DevOps provides an integrated set of services and tools to manage your software projects, from planning and development through testing and deployment. +Azure DevOps offers a spectrum of service models to accommodate the unique needs of every team. The free access version helps small teams get started quickly, while the versatile subscription and pay-per-use plans support comprehensive project management. -Azure DevOps delivers services through a client/server model. You can use most of the services via the web interface, which you can access from all major browsers. Some services, such as source control, build pipelines, and work tracking, can also be managed through a client. +- **End-to-end project management**: Azure DevOps stands as a cohesive suite of services designed to support the complete lifecycle of your software projects. It encompasses everything from initial planning and development, through rigorous testing, to final deployment. -::: moniker range=">= azure-devops-2019" +- **Client/server model delivery**: Azure DevOps operates on a client/server model, offering flexibility in how you interact with its services. The web interface provides a convenient way to utilize most services and is compatible with all major browsers. Additionally, certain services like source control, build pipelines, and work tracking offer client-based management options for enhanced control. -Access Azure DevOps through the left navigational bar, as shown in the following image. -For more information, see the following associated articles. +- **Flexible and scalable service options**: + - Azure DevOps caters to teams of all sizes by offering a range of service options. For small teams, many services are complimentary, ensuring that you have access to robust project management tools without any initial investment. + - For larger teams or more advanced needs, services are accessible through a subscription model or on a pay-per-use basis. This flexibility allows you to scale your usage according to project demands and budget constraints. + - Azure DevOps offers a hybrid model, so you can make the best use of the benefits you need. Manage your code and tasks by using an on-premises deployment for maximum control and security. When you need more resources, tap into cloud-based build or testing services. This approach ensures you only pay for what you use, optimizing your operational efficiency. -:::row::: - :::column span="2"::: - :::image type="content" source="../organizations/projects/media/about-projects/services-hubs-vert.png" alt-text="Screenshot of services on the left navigational menu."::: - :::column-end::: - :::column span="1"::: -- [Dashboards](../report/dashboards/overview.md) -- [Wiki](../project/wiki/about-readme-wiki.md) -- [Boards](../boards/get-started/what-is-azure-boards.md) -- [Repos](..//repos/get-started/what-is-repos.md) -- [Pipelines](../pipelines/get-started/pipelines-get-started.md) -- [Test Plans](../test/overview.md) -- [Artifacts](../artifacts/start-using-azure-artifacts.md) -:::column-end::: -:::row-end::: - -::: moniker-end - -::: moniker range="tfs-2018" -Access Azure DevOps through the top navigational bar, as shown in the following image. See the associated articles to jump to information for each major service. - -![Azure DevOps Services, main](../media/services-hubs.png) - -- [Dashboards](../report/dashboards/overview.md) -- [Repos](../repos/get-started/what-is-repos.md) -- [Boards](../boards/get-started/what-is-azure-boards.md) -- [Pipelines](../pipelines/get-started/pipelines-get-started.md) -- [Test Plans](../test/overview.md) -- [Wiki](../project/wiki/about-readme-wiki.md) -::: moniker-end - -Many of our services are either free for small teams or available through a subscription model or per-use model. You can do a hybrid approach where you use an on-premises deployment to manage your code and work. Then, purchase cloud build or testing services on an as-needed basis. - -For more information about client tools, see [Tools and clients that connect to Azure DevOps](tools.md). -## Dashboards - -Gain access to user-configurable dashboards from **Dashboards**. - -::: moniker range=">= azure-devops-2019" -![Azure DevOps Services, Dashboards.](media/dashboard-overview.png) -::: moniker-end - -::: moniker range="tfs-2018" -:::image type="content" source="../report/dashboards/media/dashboard-view-with-widgets.png" alt-text="Screenshot of Dashboard overview."::: -::: moniker-end - -You can do the following tasks in **Dashboards**: -- Add, configure, and manage dashboards -- Configure widgets that you add to dashboards -- Go to different areas of your project quickly - -For more information, see [Dashboards](../report/dashboards/dashboards.md). +- **Azure DevOps navigation**: The left navigation menu in Azure DevOps is your gateway to its extensive features. It allows for intuitive access and management of the various services provided. -## Repos + :::row::: + :::column span="1"::: -Source or version control systems allow developers to collaborate on code and track changes made to the code base. Source control is an essential tool for multi-developer projects. + :::image type="content" source="media/left-navigation.png" alt-text="Screenshot of services listed on the left navigation menu in Azure DevOps."::: -Our systems support two types of source control: [Git](../repos/git/index.yml) or [Team Foundation Version Control (TFVC)](../repos/tfvc/index.yml). You can check in files and organize files within folders, branches, and repositories in both systems. - -### Git repos + :::column-end::: + :::column span="2"::: -With Git, each developer has a copy on their dev machine of the source repository, including all branch and history information. Each developer works directly with their own local repository and changes are shared between repositories as a separate step. + [**Dashboards**](../report/dashboards/overview.md): Create a personalized view of project data and workflows.

      + [**Wiki**](../project/wiki/about-readme-wiki.md): Document projects in a centralized and accessible team location.

      + [**Boards**](../boards/get-started/what-is-azure-boards.md): Access Agile tools for streamline planning and tracking projects.

      + [**Repos**](../repos/get-started/what-is-repos.md): Apply source control for project collaboration and maintenance.

      + [**Pipelines**](../pipelines/get-started/pipelines-get-started.md): Automate project build and test, and the release processes.

      + [**Test Plans**](../test/overview.md): Create, manage, and run manual and automated project testing.

      + [**Artifacts**](../artifacts/start-using-azure-artifacts.md): Share packages and integrate package sharing into pipelines. -Developers commit each set of changes and do version control operations like history and compare without a network connection. When developers need to switch contexts, they create a private local branch, and can switch from one branch to another to pivot among different variations of the codebase. Later, they merge, publish, or dispose of the branch. + :::column-end::: + :::row-end::: -> [!NOTE] -> Git in Azure DevOps is standard Git. You can use Visual Studio with third-party Git services. You can also use third-party Git clients with Azure DevOps Server. +For more information, see [Tools and clients that connect to Azure DevOps](tools.md). -### TFVC +## Dashboards -With TFVC, developers have only one version of each file on their dev machines. Historical data is maintained only on the server. Branches are path-based and created on the server. +Azure DevOps provides a powerful dashboard interface that allows you to create a personalized view of your project data and workflows. Here's how you can make the most of the Dashboards feature: -### Access Git and TFVC +- **Add, configure, and manage dashboards**: Create multiple dashboards to reflect different aspects of your project. You can customize each dashboard by adding and arranging various widgets that display project data in real time. +- **Configure widgets**: Enhance your dashboards with widgets that provide insights into your project. Choose from a wide range of widgets to display information such as build status, test results, and work item queries. +- **Navigate quickly**: Use dashboards as a central hub for navigating to various areas of your project. Set up links and shortcuts that allow you to access important sections of Azure DevOps with just a selection. +- **Use extensibility points**: Use Azure DevOps extensibility points to further customize your dashboards. You can add new capabilities by integrating non-Microsoft services or creating your own extensions. -::: moniker range=">= azure-devops-2019" +For more information, see the [Dashboards documentation](../report/dashboards/dashboards.md). -From **Repos**, you gain access to your source control Git-based or Team Foundation Version Control (TFVC) repositories to support version control of your software projects. These repositories are private. +:::image type="content" source="media/dashboard-overview.png" alt-text="Screenshot of the Dashboards landing page showing Agile Lead Time, Future Spring, New Work Item, Work in Progress, and Team Velocity." lightbox="media/dashboard-overview.png"::: -![Azure Repos, Git files page](media/repos-git-hub.png) +## Azure Boards -::: moniker-end +In the dynamic world of software development, efficient information sharing and meticulous tracking of work, tasks, issues, and code defects are essential. Developers commonly work with tools like Microsoft Excel, Microsoft Project, and various bug tracking systems. The recent adoption of Agile methodologies revolutionizes planning and development processes. -::: moniker range="tfs-2018" +Azure Boards provides several Agile tools designed to help streamline planning and tracking across your projects: -From **Code**, you gain access to your source control Git-based or TFVC repositories to support version control of your software projects. These repositories are private. +- **Work item management**: Seamlessly add and update various work items to keep your project organized and on track. +- **Queries and charts**: Define custom queries for work items and generate insightful status and trend charts to visualize progress. +- **Backlog handling**: Efficiently manage your product backlog and ensure priorities are clear and actionable. +- **Sprint planning**: Utilize sprint backlogs to plan and execute sprints with precision and align your team's efforts with project goals. +- **Task board utilization**: Review and update sprint tasks through interactive task boards that reflect real-time changes. +- **Workflow visualization**: Monitor your project workflow and update statuses by using intuitive boards that provide a clear view of the development pipeline. +- **Portfolio management**: Organize your work hierarchically, group user stories under features and features under epics, and maintain a structured overview. +- **Scrum meetings**: Use task boards during daily Scrum meetings to assess completed, remaining, or blocked work, and foster a collaborative and responsive team environment. -:::image type="content" source="media/code-git-hub.png" alt-text="Screenshot of the Code, Git, files page."::: +Azure Boards supports various work item types, where each is associated with a specific set of fields that can be updated as progress is made. These work types give you a tailored approach to tracking different aspects of your project. -::: moniker-end +**Agile support**: Whether you're practicing Scrum, Kanban, or Scrumban, Azure Boards offers backlogs and boards to facilitate these methodologies, empowering your team to deliver results effectively. -From Azure Repos for Git, you can do the following tasks: +Project managers and developers can share information and track progress by using the comprehensive backlogs and boards. Azure Boards provides a complete picture of your project status, which enables teams to monitor trends and make informed decisions. -- Review, download, and edit files, and review the change history for a file -- Review and manage commits that have been pushed -- Review, create, approve, comment on, and complete pull requests -- Add and manage Git tags +For an in-depth understanding of how backlogs, boards, and plans can transform your project management experience, see [What is Azure Boards?](../boards/get-started/what-is-azure-boards.md) -## Boards +:::image type="content" source="media/boards-backlogs.png" alt-text="Screenshot of the Azure Boards backlogs page showing many cards, including New Items, Active Items, and Items to Analyze." lightbox="media/boards-backlogs.png"::: -Software development projects require ways to easily share information and track the status of work, tasks, issues, or code defects. In the past, you might have used Microsoft Excel, Microsoft Project, a bug tracking system, or a combination of tools. Now, many teams have adopted Agile methods and practices to support planning and development. +## Azure Repos -::: moniker range=">= azure-devops-2019" +Source or version control systems are pivotal for developers who need to collaborate seamlessly on codebases and maintain a comprehensive history of changes. These systems are indispensable for projects that involve multiple developers and ensure consistency and coordination throughout the development process. -From **Boards**, you gain access to Agile tools to support planning and tracking work. +:::image type="content" source="media/repos-github.png" alt-text="Screenshot of the Azure Repos landing page showing the 'main' branch in the repo with folders and a README file." lightbox="media/repos-github.png"::: -![Azure Boards backlogs](media/boards-backlogs.png) +Azure DevOps supports two primary types of source control to suit diverse project needs: [Git](../repos/git/index.yml) and [Team Foundation Version Control (TFVC)](../repos/tfvc/index.yml). -::: moniker-end +### Git -::: moniker range="tfs-2018" +Git is a version control system where each developer has a local copy of the entire repository. This approach allows for offline work and easy branching and merging. Git is the default choice for new projects and is recommended for its flexibility and robustness. -From **Work**, you gain access to Agile tools to support planning and tracking work. +> [!NOTE] +> Git in Azure DevOps is standard Git. You can use Visual Studio with third-party Git services. You can also use third-party Git clients with Azure DevOps Server. -Work, Backlogs page +You can do the following tasks with Azure Repos for Git: -::: moniker-end +- **Review files**: Examine the details and history of changes made to each file within your repository. +- **Download and edit files**: Obtain a local copy of files from the repository and make necessary modifications. +- **Manage commits**: Keep track of commits pushed to the repository and ensure a clear history of code changes. +- **Use pull requests**: Participate in the collaborative code review process by creating, approving, commenting on, and completing pull requests. +- **Use Git tags**: Organize and mark specific points in your repository's history by using Git tags for easy reference. -You can do the following tasks with boards. +### TFVC -- Add and update work items -- Define work item queries, and create status and trend charts based on those queries -- Manage your product backlog -- Plan sprints by using sprint backlogs -- Review sprint tasks and update tasks through the task boards -- Visualize the workflow and update the status by using Kanban boards -- Manage portfolios by grouping stories under features and grouping features under epics -- Use task boards during daily Scrum meetings to review work that's completed, remaining, or blocked +Team Foundation Version Control (TFVC) is a centralized version control system that simplifies code management. Developers work with a single version of each file on their local machines, while the server retains the full history of changes, providing a single source of truth. -Our systems provide several types of work items that you use to track features, requirements, user stories, tasks, bugs, and issues. Each work item is associated with a work item type and a set of fields that can be updated, as progress is made. +TFVC includes the following key features: -For planning purposes, you have access to several types of backlogs and boards to support the main Agile methods—Scrum, Kanban, or Scrumban. +- **Single version workflow**: Each developer's machine holds the current version of files. This approach reduces complexity and ensures consistency across the team. +- **Server-side history**: All historical data including changes and versions are securely stored on the server, which preserves the integrity of your project's evolution. +- **Path-based branching**: Branches are created and managed on the server by using a path-based approach. This approach allows for clear organization and straightforward merging processes. -Project managers and developers share information by tracking work items on the backlogs and boards. Useful charts and dashboards complete the picture and help teams monitor progress and trends. +## Azure Pipelines -See [Backlogs, boards, and plans](../boards/backlogs/backlogs-boards-plans.md) for an overview of each. +Achieving rapid and reliable software releases is a hallmark of modern development practices. Azure Pipelines stands at the forefront of this endeavor by automating the build, test, and release processes. -## Pipelines +- **Automated builds**: Set up your Azure Pipelines to trigger automated builds upon code check-ins and ensure every change is promptly integrated and verified. +- **Test integration**: Incorporate test runs post-build to validate changes, maintain high code quality, and detect issues early. +- **Release pipelines**: Manage the deployment of your software builds across various environments, from staging to production, with Azure Pipelines' robust release management capabilities. -The rapid and reliable release of software comes from automating as many processes as possible. Our systems support build, test, and release automation. +Azure Pipelines includes the following features: -- You can define builds to automatically run whenever a team member checks in code changes. -- Your build pipelines can include instructions to run tests after the build runs. -- Release pipelines support managing deployment of your software builds to staging or production environments. +- **Continuous integration (CI)**: Implement CI to automatically merge code changes into a central repository, followed by automated builds and tests. +- **Continuous delivery (CD)**: Ensure that your software can be reliably released at any time with CD practices, streamlining the path from development to production. +- **Build automation**: Customize your build process with defined steps and triggers, creating a consistent and repeatable build environment. +- **Release management**: Oversee simultaneous releases with configurable release pipelines that mirror your development lifecycle, from development environments to production. +- **Deployment automation**: Automate the deployment process, reducing manual efforts and the potential for errors. +- **Approval workflows**: Integrate approval workflows to validate successful deployments, adding a layer of verification before promoting builds. +- **Release tracking**: Monitor your releases as they progress through different environments, gaining visibility into the deployment pipeline. -::: moniker range=">= azure-devops-2019" -**Azure Pipelines** provides an integrated set of features to support building and deploying your applications. +For a detailed guide on implementing continuous integration and delivery with Azure Pipelines, see [What is Azure Pipelines?](../pipelines/get-started/what-is-azure-pipelines.md) -> [!div class="mx-imgBorder"] -> ![Azure Pipelines landing page](media/pipelines-landing-page.png) -> -::: moniker-end +:::image type="content" source="media/pipelines-landing-page.png" alt-text="Screenshot of the Azure Pipelines landing page showing the list of recently run pipelines." lightbox="media/pipelines-landing-page.png"::: -::: moniker range="tfs-2018" -**Azure Pipelines** provides an integrated set of features to support building and deploying your applications. +## Azure Test Plans -:::image type="content" source="media/services/build-release-hub.png" alt-text="Screenshot of build pipelines page."::: -::: moniker-end +Azure Test Plans is a comprehensive service designed to facilitate the creation, management, and execution of various testing methodologies, including manual, exploratory, and automated tests. -Use pipelines to implement continuous integration and continuous delivery. -- **Build automation**: Define the steps to take during build and the triggers that start a build. -- **Release management**: Manage simultaneous releases. You can also do the following tasks: - - Configure release pipelines that represent your environments from development to production - - Run automation to deploy your app to each environment - - Add approvers to confirm that the app has been successfully deployed in an environment - - Create your release manually or automatically from a build - - Track your releases as they're deployed to various environments +Azure Test Plans includes the following key features: -For more information, see [Continuous integration on any platform](../pipelines/get-started/what-is-azure-pipelines.md). +- **Workflow customization**: Tailor your testing workflow with customizable test plans, suites, and cases, and help ensure alignment with your project's needs. +- **Traceability**: Achieve end-to-end traceability and link requirements directly to test cases and bugs with requirement-based test suites. +- **Test selection**: Utilize query-based test suites for criteria-based test selection and streamline the testing process. +- **User-friendly interface**: Benefit from an Excel-like grid interface and simplify the creation and management of test cases. +- **Reusable elements**: Enhance efficiency with reusable test steps and shared parameters, and promote consistency across tests. +- **Collaboration**: Share test plans, suites, and cases with stakeholders for review and feedback, and foster a collaborative testing environment. +- **Cross-platform execution**: Execute tests directly from your browser on any platform, which offers flexibility and convenience. +- **Activity monitoring**: Monitor testing activities with real-time charts, and gain visibility into test progress and outcomes. -## Test Plans +For a detailed exploration of how Azure Test Plans can streamline your testing processes, see the [Azure Test Plans documentation](../test/index.yml). -::: moniker range=">= azure-devops-2019" +:::image type="content" source="media/test-plans-vert.png" alt-text="Screenshot of the Test Plans landing page showing a vertical layout of test suites and test cases in the test plan." lightbox="media/test-plans-vert.png"::: -**Test Plans** supports creating and managing manual, exploratory, and continuous tests. +## Collaboration services -![Test Plans](media/test-plans-vert.png) -::: moniker-end +Azure DevOps enhances team collaboration through the following services designed to streamline communication and project tracking: -::: moniker range="tfs-2018" -**Test** supports creating and managing manual tests. +- [**Team dashboards**](../report/dashboards/dashboards.md): Create and customize dashboards to provide your team with real-time visibility into project metrics and progress. +- [**Project wiki**](../project/wiki/manage-wikis.md): Document your project details, guidelines, and knowledge base in a centralized, easily accessible wiki. +- [**Work item discussions**](../boards/work-items/work-item-fields.md): Facilitate conversations directly within work item forms and enable contextual and timely communication. +- **Traceability links**: Establish links between [work items](../boards/backlogs/add-link.md), [commits](../repos/git/commits.md), [pull requests](../repos/git/pull-requests.md), and more, and help ensure comprehensive traceability across your project. +- [**Alerts and notifications**](../organizations/notifications/about-notifications.md): Set up personalized alerts and change notifications to keep team members informed about project updates and changes. +- **Feedback management**: Streamline the process of [requesting](../test/request-stakeholder-feedback.md), [providing](provide-feedback.md), and managing feedback to continuously improve project outcomes. +- [**Analytics**](../report/powerbi/analytics-security.md) and [**Reporting**](../report/powerbi/access-analytics-power-bi.md): Use the analytics service and Power BI reporting for insights into project performance and make data-driven decisions. -:::image type="content" source="media/services/test-hub.png" alt-text="Screenshot of Test hub."::: -::: moniker-end +These collaboration services are integral to maintaining a cohesive and informed team capable of responding swiftly to project demands and opportunities. -With test features, you gain access to the following features: +## Service hooks -- Customization of workflows with test plan, test suite, and test case work items -- End-to-end traceability from requirements to test cases and bugs with requirement-based test suites -- Criteria-based test selection with query-based test suites -- Excel-like interface with the grid for easy creation of test cases -- Reusable test steps and test data with shared steps and shared parameters -- Sharable test plans, test suites, and test cases for reviewing with Stakeholders -- Browser-based test execution on any platform -- Real-time charts for tracking test activity +Service hooks in Azure DevOps empower you to automate and streamline interactions with other services, and respond swiftly to events within your projects. For instance, you can configure service hooks to send immediate push notifications to your team's devices if a build process encounters an error. -For more information, see [Azure Test Plans documentation](../test/index.yml). +Utilize service hooks in the following ways: -## Collaboration services +- **Custom apps integration**: Integrate service hooks with your custom applications to initiate actions automatically, enhance efficiency, and improve project responsiveness. +- **Service targets**: Designate various services as targets for your service hooks and allow for a wide range of automated responses to project events. -Azure DevOps also provides the following collaboration services. - -::: moniker range=">= azure-devops-2019" -- [Team dashboards](../report/dashboards/dashboards.md) -- [Project wiki](../project/wiki/manage-wikis.md) -- [Discussion within work item forms](../boards/work-items/work-item-fields.md) -- Linking of [work items](../boards/queries/link-work-items-support-traceability.md), [commits](../repos/git/commits.md), [pull requests](../repos/git/pull-requests.md), and other artifacts to support traceability -- [Alerts and change notifications](../organizations/notifications/about-notifications.md) managed per user, team, project, or organization -- Ability to [request](../test/request-stakeholder-feedback.md), [provide](provide-feedback.md), and manage feedback -- [Analytics service](../report/powerbi/analytics-security.md), [analytics views](../report/powerbi/analytics-views-manage.md), and [Power BI reporting](../report/powerbi/access-analytics-power-bi.md) -::: moniker-end - -::: moniker range="tfs-2018" -- [Dashboards](../report/dashboards/dashboards.md) -- [Project wiki](../project/wiki/manage-wikis.md) -- [Discussion within work item forms](../boards/work-items/work-item-fields.md) -- Linking of [work items](../boards/queries/link-work-items-support-traceability.md), [commits](../repos/git/commits.md), [pull requests](../repos/git/pull-requests.md), and other artifacts to support traceability -- [Alerts and change notifications](../organizations/notifications/about-notifications.md) managed per user, team, project, or collection -- Ability to [request](../test/request-stakeholder-feedback.md), [provide](provide-feedback.md), and manage feedback -- [SQL Server Reporting](../report/sql-reports/analytics-insights-comparable-sql-reports.md) -::: moniker-end +For a comprehensive list of services that can be integrated with Azure DevOps by using service hooks, and to explore other apps and services that complement Azure DevOps, see the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops). To stay updated on the newest services supported by service hooks, see the [Integrate with service hooks](../service-hooks/overview.md) documentation. -## Service hooks +## Azure cloud-hosted services -With service hooks, you can complete tasks on other services when events happen within your project hosted on Azure DevOps. For example, you can send a push notification to your team's mobile devices when a build fails. You can also use service hooks in custom apps and services as a more efficient way to drive activities in your projects. +Azure offers a robust array of cloud-hosted services that are essential for the development and deployment of applications. These services can be utilized independently or with Azure DevOps to create a seamless workflow. -The following services are available as the target of service hooks. For more information about other apps and services that integrate with Azure DevOps, visit the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops). +Key benefits of Azure cloud-hosted services include: -For the latest set of supported services, see [Integrate with service hooks](../service-hooks/overview.md). +- **Comprehensive support**: Azure services provide the infrastructure and platform support necessary for the entire application lifecycle. +- **Integration with Azure DevOps**: You can combine these services with Azure DevOps for an integrated experience that covers source control, CI/CD, and more. -## Azure cloud-hosted services +To explore the full range of services, features, and suites that integrate seamlessly with your development process, see the [Azure products](https://azure.microsoft.com/products/) directory. -Azure provides cloud-hosted services to support application development and deployment. You can make use of these services solely or in combination with Azure DevOps. +## Administrative services -To browse the directory of integrated services, features, and bundled suites, see [Azure products](https://azure.microsoft.com/services/). +Managing a collaborative software development environment is a streamlined process with Azure DevOps. You can access various features and tasks that are tailored for administration. These tools are designed to facilitate the oversight of your projects and teams effectively. -For continuous delivery to Azure from Azure DevOps, see [Automatically build and deploy to Azure web apps or cloud services](/azure/cloud-services/cloud-services-choose-me). +Accessible administration is provided in the following ways: -## Administrative services +- **Web portal management**: Perform most administrative tasks conveniently through the Azure DevOps web portal and ensure you have control at your fingertips. +- **Comprehensive settings**: Access detailed settings for users, teams, projects, and organizations. This approach allows for granular management of your development environment. -There are features and tasks associated with administering a collaborative software development environment. You can complete most of these tasks through the web portal. For more information, see [About user, team, project, and organization-level settings](../organizations/settings/about-settings.md). +For a deeper understanding of the administrative capabilities available to you, including how to configure and manage various levels of settings, see [About user, team, project, and organization-level settings](../organizations/settings/about-settings.md). -## Related articles +## Related content -- [Azure DevOps Services **vs.** Azure DevOps Server](about-azure-devops-services-tfs.md) -- [Client-server tools](tools.md) -- [Software development roles](roles.md) -- [Azure DevOps pricing](https://visualstudio.microsoft.com/team-services/pricing/) +- [Compare Azure DevOps Services and Azure DevOps Server](about-azure-devops-services-tfs.md) +- [Review client-server tools](tools.md) +- [Examine Software development roles](roles.md) +- [Review Azure DevOps pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) diff --git a/docs/user-guide/sign-up-invite-teammates.md b/docs/user-guide/sign-up-invite-teammates.md index 684c33ae8b7..fd81cbb64aa 100644 --- a/docs/user-guide/sign-up-invite-teammates.md +++ b/docs/user-guide/sign-up-invite-teammates.md @@ -1,13 +1,13 @@ --- title: Sign up for Azure DevOps titleSuffix: Azure DevOps Services -ms.custom: seodec18, contperf-fy22q3, peer-review-fy23 , content-perf-fy23q2 +ms.custom: peer-review-fy23, content-perf-fy23q2 description: Sign up for Azure DevOps with a Microsoft or GitHub account. ms.subservice: azure-devops-new-user -ms.topic: how-to +ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 09/06/2022 +ms.date: 03/13/2025 monikerRange: 'azure-devops' --- @@ -15,50 +15,37 @@ monikerRange: 'azure-devops' [!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] -When you sign up for Azure DevOps, you get the following tier of free services: +Sign up for Azure DevOps and get the [free tier of services](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/). For more information, see [What is Azure DevOps?](what-is-azure-devops.md) -[!INCLUDE [free-tier](../includes/free-tier.md)] +## Prerequisites -You can sign up for Azure DevOps with either a [Microsoft](#sign-up-with-a-microsoft-account) or [GitHub](#sign-up-with-a-github-account) account. For more information, see What is [Azure DevOps?](what-is-azure-devops.md) -## Sign up with a Microsoft account +| Category | Requirements | +|--------------|-------------| +|**Browser**| Latest version of one of the following web browsers: Microsoft Edge, Internet Explorer, Safari (Mac), Firefox, or Chrome.| -1. If you don't have one, [create a Microsoft account now](https://azure.microsoft.com/services/devops/). -2. Go to [Azure DevOps](https://azure.microsoft.com/services/devops/) and select **Start free**. -3. Enter your account credentials and go through the sign-up process. +## Sign up -Azure DevOps does the following tasks: -- Creates an organization. -- Creates a project named after your *newly created* Microsoft account. - - If you signed up with an existing Microsoft account, you need to [create a project](../organizations/projects/create-project.md) next. +Sign up for Azure DevOps with either a Microsoft account or GitHub account. -Sign in to your organization at any time `https://dev.azure.com/{Your_Organization}`. +# [Microsoft account](#tab/microsoft-account) -## Sign up with a GitHub account +[!INCLUDE [sign-up-msft-account](../includes/sign-up-msft-account.md)] -> [!NOTE] -> If your GitHub email address is already associated with an organization in Azure DevOps that's [connected to Azure Active Directory (Azure AD)](../organizations/accounts/connect-organization-to-azure-ad.md), you can't sign in with your GitHub account. You must sign in with your Azure AD account. +# [GitHub account](#tab/github-account) -1. If you don't have one, [create a GitHub account now](https://github.com/join). -2. Go to [Azure DevOps](https://azure.microsoft.com/services/devops/) and select **Start free with GitHub**. -3. Enter your account credentials and go through the sign-up process. You're asked to **Authorize Microsoft-corp**. +[!INCLUDE [sign-in-github-account](../includes/sign-in-github-account.md)] -Azure DevOps does the following tasks: -- Creates an organization. Sign in to your organization at any time `https://dev.azure.com/{Your_Organization}`. -- Turns on the *Invite GitHub users* policy by default. - ![Invite GitHub users policy ](../media/invite-github-users-policy.png) - Before you can invite users, you must create a project, as shown in **Next steps**. For more information about GitHub authentication, see [FAQs](../organizations/security/faq-github-authentication.yml). +--- ## Next steps > [!div class="nextstepaction"] > [Create a project](../organizations/projects/create-project.md) -> or -> [!div class="nextstepaction"] -> [Add users or groups to a team or project](../organizations/security/add-users-team-project.md) ## Related articles - [Plan your organizational structure in Azure DevOps](plan-your-azure-devops-org-structure.md) - [Change the location of your organization](../organizations/accounts/change-organization-location.md) - [Add users to your organization](../organizations/accounts/add-organization-users.md) -- [GitHub authentication FAQs](../organizations/security/faq-github-authentication.yml) +- [Add users or groups to a team or project](../organizations/security/add-users-team-project.md) +- [Connect to GitHub, FAQs](../boards/github/connect-to-github.md#faqs) diff --git a/docs/user-guide/source-control.md b/docs/user-guide/source-control.md index 42404977480..7ff49244a46 100644 --- a/docs/user-guide/source-control.md +++ b/docs/user-guide/source-control.md @@ -1,8 +1,7 @@ --- title: Understand source control titleSuffix: Azure DevOps -ms.custom: seodec18 -description: What is source control or version control in Azure DevOps? +description: What is source control or version control in Azure DevOps? ms.subservice: azure-devops-new-user ms.assetid: 7E769466-2165-4223-96FA-80A687287EFC ms.author: chcomley diff --git a/docs/user-guide/toc.yml b/docs/user-guide/toc.yml index fdb5d5023d6..bdead49604d 100644 --- a/docs/user-guide/toc.yml +++ b/docs/user-guide/toc.yml @@ -5,7 +5,6 @@ - name: Compare Azure DevOps hosted vs. on-premises href: about-azure-devops-services-tfs.md?toc=/azure/devops/get-started/toc.json - name: Get started for end users - expanded: true items: - name: Sign in to the web or a client href: ../organizations/projects/connect-to-projects.md?toc=/azure/devops/get-started/toc.json @@ -23,27 +22,28 @@ href: ../organizations/security/get-started-stakeholder.md?toc=/azure/devops/get-started/toc.json - name: View permissions href: ../organizations/security/view-permissions.md?toc=/azure/devops/get-started/toc.json -- name: Get started for administrators expanded: true +- name: Get started for administrators items: - name: Sign up for Azure DevOps href: sign-up-invite-teammates.md?toc=/azure/devops/get-started/toc.json - name: Create an organization or project collection href: ../organizations/accounts/create-organization.md?toc=/azure/devops/get-started/toc.json - name: Manage your project - href: project-admin-tutorial.md?toc=/azure/devops/get-started/toc.json + href: project-admin-tutorial.md?toc=/azure/devops/get-started/toc.json - name: Manage your organization or collection href: manage-organization-collection.md?toc=/azure/devops/get-started/toc.json - name: Add users to a project or team - href: ../organizations/security/add-users-team-project.md?toc=/azure/devops/get-started/toc.json + href: ../organizations/security/add-users-team-project.md?toc=/azure/devops/get-started/toc.json - name: Manage teams and configure team tools href: ../organizations/settings/manage-teams.md?toc=/azure/devops/get-started/toc.json - name: Change individual permissions href: ../organizations/security/request-changes-permissions.md?toc=/azure/devops/get-started/toc.json - name: Grant or restrict permissions to select tasks href: ../organizations/security/restrict-access.md?toc=/azure/devops/get-started/toc.json - - name: Security best practices - href: ../organizations/security/security-best-practices.md?toc=/azure/devops/get-started/toc.json + - name: Security overview + href: ../organizations/security/security-overview.md?toc=/azure/devops/get-started/toc.json + expanded: true - name: Key concepts items: - name: Plan your organizational structure @@ -51,13 +51,15 @@ - name: Source control href: source-control.md?toc=/azure/devops/get-started/toc.json - name: Clients and tools - href: tools.md?toc=/azure/devops/get-started/toc.json + href: tools.md?toc=/azure/devops/get-started/toc.json - name: Software development roles href: roles.md?toc=/azure/devops/get-started/toc.json - name: Troubleshooting items: - name: Troubleshoot connection href: troubleshoot-connection.md?toc=/azure/devops/get-started/toc.json + - name: Capture browser trace + href: capture-browser-trace.md?toc=/azure/devops/get-started/toc.json - name: 'TF31002: Unable to connect' href: ../organizations/projects/tf31002-unable-connect-tfs.md?toc=/azure/devops/get-started/toc.json - name: Troubleshoot access and permissions @@ -65,17 +67,15 @@ - name: Allowed address lists and network connections href: ../organizations/security/allow-list-ip-url.md?toc=/azure/devops/get-started/toc.json - name: Get support or provide feedback - href: provide-feedback.md?toc=/azure/devops/get-started/toc.json + href: provide-feedback.md?toc=/azure/devops/get-started/toc.json - name: Look up platform and version - href: lookup-platform-version.md?toc=/azure/devops/get-started/toc.json + href: lookup-platform-version.md?toc=/azure/devops/get-started/toc.json - name: Reference items: - name: Navigate in Team Explorer href: work-team-explorer.md?toc=/azure/devops/get-started/toc.json - - name: FAQs - href: user-guide-faqs.yml?toc=/azure/devops/get-started/toc.json - name: Service limits - href: service-limits.md?toc=/azure/devops/get-started/toc.json + href: ../integrate/concepts/rate-limits.md?toc=/azure/devops/get-started/toc.json - name: Resources items: - name: Azure CLI diff --git a/docs/user-guide/tools.md b/docs/user-guide/tools.md index cd3c6e3fb90..0c5b77f0d68 100644 --- a/docs/user-guide/tools.md +++ b/docs/user-guide/tools.md @@ -1,8 +1,7 @@ --- title: Tools and clients that connect to Azure DevOps titleSuffix: Azure DevOps -ms.custom: seodec18 -description: Understand the tools that support connecting to Azure DevOps. +description: Understand the tools that support connecting to Azure DevOps. ms.subservice: azure-devops-new-user ms.assetid: 3836C81D-6E0A-46B5-8D1D-20E973E4F373 ms.author: chcomley @@ -12,7 +11,6 @@ monikerRange: '<= azure-devops' ms.date: 12/16/2022 --- - # Tools and clients that connect to Azure DevOps [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] @@ -32,57 +30,33 @@ Developers have access to many tools through these versions of Visual Studio and - **[Android Studio with the Azure DevOps Services Plug-in for Android Studio](/previous-versions/azure/devops/all/java/download-android-studio-plug-in)**: Free plug in to support Android developers and connect to Git repositories on Azure DevOps. - **[IntelliJ with the Azure DevOps Services Plugin for IntelliJ](/previous-versions/azure/devops/all/java/download-intellij-plug-in)**: Free plug in to support developers who use IntelliJ IDEA or Android Studio to connect to Git repositories on Azure DevOps. - To get started with client libraries, see [Client library samples](../integrate/get-started/client-libraries/samples.md). **Team Explorer plug-in** -Team Explorer, a plug-in to all Visual Studio versions, connects Visual Studio to projects defined in Azure DevOps. You can manage source code, work items, and builds. To learn more, see [Work in Team Explorer](work-team-explorer.md). +Team Explorer, a plug-in to all Visual Studio versions, connects Visual Studio to projects defined in Azure DevOps. You can manage source code, work items, and builds. For more information, see [Work in Team Explorer](work-team-explorer.md). > [!div class="mx-tdBreakAll"] > |Home page with Git |Home page with TFVC | > |-------------|----------| > |Team Explorer home page with Git as source control | Team Explorer home page with Team Foundation Version Control (TFVC) as source control | - **Visual Studio Git experience** -Visual Studio 2019 and later versions provide a new Git experience through the **Git** menu as shown below. To learn more, see [Git experience in Visual Studio](/visualstudio/version-control/git-with-visual-studio) and [Side-by-side comparison of Git and Team Explorer](/visualstudio/version-control/git-team-explorer-feature-comparison). +Visual Studio 2019 and later versions provide a new Git experience through the **Git** menu as shown in the following image. For more information, see [Git experience in Visual Studio](/visualstudio/version-control/git-with-visual-studio) and [Side-by-side comparison of Git and Team Explorer](/visualstudio/version-control/git-team-explorer-feature-comparison). :::image type="content" source="media/tools/visual-studio-git-menu.png" alt-text="Screenshot of Visual Studio 2019 Git menu."::: - ## Office integration tools ::: moniker range="= azure-devops" You can integrate the following Microsoft Office tools with Azure DevOps. -- [Excel](../boards/backlogs/office/bulk-add-modify-work-items-excel.md): Use Excel to add and bulk modify work items. +- [Excel](../boards/backlogs/office/bulk-add-modify-work-items-excel.md): Use Excel to add and bulk modify work items. Requires the [Azure DevOps Office Integration 2019](https://visualstudio.microsoft.com/downloads/#other-family) add-in to be installed. > [!IMPORTANT] -> Starting with Visual Studio 2019, the Team Foundation plug-in for Office is deprecating support for Microsoft Project. Project integration and the TFSFieldMapping command is not supported for Azure DevOps Server 2019 nor for Azure DevOps Services. However, you can continue to use Microsoft Excel. - -::: moniker-end - -::: moniker range="= azure-devops-2019" - -- [Excel](../boards/backlogs/office/bulk-add-modify-work-items-excel.md): Use Excel to add and bulk modify work items. - - -> [!TIP] -> Check to make sure the Azure DevOps Office Integration component is selected in the Visual Studio Installer, per the following example. -> ![Check Azure DevOps Office Integration](media/check-azure-devops-office-integration-code-tools.png) - -::: moniker-end - -::: moniker range="tfs-2018" - -When you install any edition of Visual Studio or [Team Foundation Server Standalone Office Integration 2015 (free)](https://go.microsoft.com/fwlink/?LinkId=691127), the Team Foundation plug-in integrates work item tracking with select Office clients. The Team Foundation plug-in installs to your existing Office client. The plug-in supports Office 2007, Office 2010, or Office 2013 versions. - -- [Excel](../boards/backlogs/office/bulk-add-modify-work-items-excel.md): Use Excel to add and bulk modify work items. -- [Project](/previous-versions/azure/devops/boards/backlogs/office/create-your-backlog-tasks-using-project): By using Project, you can plan projects, schedule tasks, assign resources, and track changes. You have access to features that TFS doesn't support, such as a project calendar, Gantt charts, and resource views. -- [PowerPoint Storyboarding](/previous-versions/azure/devops/boards/backlogs/office/storyboard-your-ideas-using-powerpoint): Illustrate user stories and requirements by using PowerPoint. The Team Foundation plug-in installs to your existing PowerPoint client. +> Starting with Visual Studio 2019, the Azure DevOps Office Integration 2019 add-in for Office deprecated support for Microsoft Project. Project integration and the TFSFieldMapping command aren't supported for Azure DevOps Server 2019 nor for Azure DevOps Services. However, you can continue to use Microsoft Excel. ::: moniker-end @@ -116,7 +90,7 @@ For more information, see [Web portal navigation](../project/navigation/index.md ### Browser-based extensions -Several extensions are built and maintained by the Azure DevOps Services product team: +Extensions built and maintained by the Azure DevOps Services product team: - [Code search](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search): Increase cross-team collaboration and code sharing. Enables developers to quickly locate relevant information within the code base of all projects that are hosted within an organization or collection. You can discover implementation examples, browsing definitions, and error text. - [Work item search](https://marketplace.visualstudio.com/items?itemName=ms.vss-workitem-search): To quickly find relevant work items, search across all work item fields over all projects in an organization. Do full-text searches across all fields to efficiently locate relevant work items. Use inline search filters, on any work item field, to quickly narrow down a list of work items. @@ -149,7 +123,6 @@ You can do many code development and administrative tasks by using the following - [TFSSecurity](/azure/devops/server/command-line/tfssecurity-cmd) - [TFSServiceControl](/azure/devops/server/command-line/tfsservicecontrol-cmd) - ::: moniker-end ## Integrated tool support for third-party applications @@ -178,17 +151,17 @@ Extensions are simple add-ons that you can use to customize and extend your DevO You build extensions by using our RESTful API library. Publish your extensions to the Azure DevOps Marketplace. You can privately maintain or share them with millions of developers who use Visual Studio and Azure DevOps. -To learn more, visit the [Azure DevOps Marketplace](https://marketplace.visualstudio.com) and see [Overview of extensions](../extend/overview.md). +For more information, see the [Azure DevOps Marketplace](https://marketplace.visualstudio.com) and [Overview of extensions](../extend/overview.md). ## REST APIs The Azure DevOps APIs are based on REST, OAuth, JSON, and service hooks—all standard web technologies broadly supported in the industry. -REST APIs are provided to support building extensions to Azure DevOps. To learn more, see [REST API overview](/rest/api/azure/devops). +REST APIs are provided to support building extensions to Azure DevOps. For more information, see [REST API overview](/rest/api/azure/devops). ## Related articles - [A tour of services](services.md) - [Software development roles](roles.md) -- [Pricing](https://visualstudio.microsoft.com/team-services/pricing/) +- [Azure DevOps Pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) - [Azure DevOps data protection overview](../organizations/security/data-protection.md) diff --git a/docs/user-guide/troubleshoot-connection.md b/docs/user-guide/troubleshoot-connection.md index a100617d75f..a89bf7df86b 100644 --- a/docs/user-guide/troubleshoot-connection.md +++ b/docs/user-guide/troubleshoot-connection.md @@ -1,14 +1,12 @@ --- title: Troubleshoot connecting project titleSuffix: Azure DevOps -ms.custom: seodec18 -description: Follow these steps to resolve connection issues with Azure DevOps. +description: Resolve connection issues with Azure DevOps. ms.subservice: azure-devops-new-user -ms.assetid: ms.author: chcomley author: chcomley ms.topic: troubleshooting -ms.date: 11/05/2020 +ms.date: 09/05/2024 monikerRange: '<= azure-devops' --- @@ -16,28 +14,32 @@ monikerRange: '<= azure-devops' [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -::: moniker range="azure-devops" +If you're experiencing issues connecting to a project in Azure DevOps, follow these troubleshooting steps to resolve common connectivity problems. -## Troubleshoot connectivity +## Prerequisites -As a first step in resolving connectivity issues with Azure DevOps, complete the following steps: +[!INCLUDE [prerequisites-project-member-only](../includes/prerequisites-project-member-only.md)] -1. Sign out of your browser. To do so, select the [Visual Studio sign out](https://aka.ms/VsSignout) link. +::: moniker range=" azure-devops" -2. Delete the cookies in your browser. To delete cookies in most browsers, select Ctrl+Shift+Del. +## Troubleshoot connectivity -3. Open Internet Explorer and delete the browser cookies. The Visual Studio IDE uses Internet Explorer cookies. +To resolve connectivity issues, complete the following steps: +1. Sign out of your browser. To do so, select the [Visual Studio sign out](https://aka.ms/VsSignout) link. +2. Delete the cookies in your browser. To delete cookies in most browsers, select **Ctrl**+**Shift**+**Delete**. +3. Open Microsoft Edge and delete the browser cookies. The Visual Studio IDE uses Microsoft Edge cookies. 4. Close all browsers and close the Visual Studio IDE. +5. Use a private browser session to retry the connection. If the issue is with the Visual Studio IDE, remove the connection and then readd it in Team Explorer. -5. Use a private browser session to retry the connection. If the issue is with the Visual Studio IDE, remove the connection, and then readd it. +For more troubleshooting options, see [Switch organizations](#switch-organizations), further in this article. -## Troubleshoot signing in +## Troubleshoot sign in -Two types of identities can sign in: Microsoft accounts and Azure Active Directory (Azure AD) accounts. Depending on your account, you might experience one of the following errors. +Two types of identities can sign in: Microsoft accounts and Microsoft Entra accounts. Depending on your account, you might experience the following error. + +### 401 - Not Authorized -> 401 - Not Authorized -> > [!div class="mx-imgBorder"] > ![Troubleshoot Azure DevOps connection 401 error 1](media/troubleshoot-connection/401_notauthorized.png) @@ -46,45 +48,54 @@ The most common error page is the *401 Not Authorized* error, which occurs when * Your identity isn't a member of the organization. * Your identity has an invalid or missing license assignment. * Your identity doesn't have enough memberships to access the resource. For example, membership to the Reader/Contributors group. -* Your identity is a B2B guest in the tenant, and the invitation hasn't been accepted. +* Your identity is a B2B guest in the tenant, and the invitation isn't accepted. -If you think you're a member of the organization, but are blocked by this error page, [contact Support](https://developercommunity.visualstudio.com/spaces/21/index.html). +If you think you're a member of the organization, but get this error page, [contact Support](https://developercommunity.visualstudio.com/spaces/21/index.html). -### Scenario 1 +#### Scenario 1 -Your work or school Azure AD account doesn't have access, but your personal Microsoft account does. +Your work or school Microsoft Entra account doesn't have access, but your personal Microsoft account does. > 401 - Work or school, or Personal account > > [!div class="mx-imgBorder"] > ![troubleshoot Azure DevOps connection 401 error 2](media/troubleshoot-connection/401_AAD.png) - A highly specific 401 error case. In this case, both a personal Microsoft account and a work or school account (Azure AD) that have the same sign-in address exist. You've signed in with your work or school account, but your personal account is the identity with access to the organization. + A highly specific 401 error case. In this case, both a personal Microsoft account and a work or school account (Microsoft Entra ID) that have the same sign-in address exist. You signed in with your work or school account, but your personal account is the identity with access to the organization. -### Mitigation +#### Mitigation -In some cases, you might not know you have two identities with the same sign-in address. The work or school Azure AD account might have been created by an administrator when you were added to Office365 or Azure AD. +In some cases, you might not know you have two identities with the same sign-in address. It's possible that an administrator created the work or school Microsoft Entra account when you were added to Office 365 or Microsoft Entra ID. -To sign out of your current work or school Azure AD account, select **Sign in with your personal MSA account**, and then sign in by using your personal Microsoft account. After authentication, you should have access to the organization. +To sign out of your current work or school Microsoft Entra account, select **Sign in with your personal MSA account**, and then sign in by using your personal Microsoft account. After authentication, you should have access to the organization. -* If you can´t access to the organization, make sure that your Azure Active Directory still exists and that your work or school account is in the Azure AD tenant. +* If you can't access to the organization, make sure that your Microsoft Entra ID still exists and that your work or school account is in the Microsoft Entra tenant. > [!TIP] -> To avoid seeing this prompt, you can rename your Microsoft account. Then, only one identity, your work or school account, or Azure AD account, uses your sign-in address. +> To avoid seeing this prompt, you can rename your Microsoft account. Then, only one identity, your work or school account, or Microsoft Entra account, uses your sign-in address. -### Scenario 2 +#### Scenario 2 -Your personal Microsoft account doesn't have access, but your Azure AD account does. This scenario is an opposite version of the 401 error page. In this case, the personal account (Microsoft account identity) doesn't have access to the organization and the work or school account (Azure AD identity) does. The same guidance from Scenario 1 applies, but in reverse. +Your personal Microsoft account doesn't have access, but your Microsoft Entra account does. This scenario is an opposite version of the 401 error page. In this case, the personal account (Microsoft account identity) doesn't have access to the organization and the work or school account (Microsoft Entra identity) does. The same guidance from Scenario 1 applies, but in reverse. > 401 - Work or school, or Personal account > > [!div class="mx-imgBorder"] > ![troubleshoot Azure DevOps connection 401 error 3](media/troubleshoot-connection/401_MSA.png) -### Mitigation +#### Mitigation When you get redirected back to the original sign-in page, we recommend that you clear all cookies, and then reattempt to sign in. If that doesn't fix the issue, [contact Support](https://developercommunity.visualstudio.com/spaces/21/index.html). +## Unable to connect to Azure DevOps Services + +|Problem|Resolution| +|-------------|----------------| +|You don't have an active account or license.|Check with your administrator that you're a member of the account and have an active, valid license. For more information, see [Assign licenses to users](../organizations/accounts/add-organization-users.md).| +|Your Azure DevOps Services organization is connected to the Microsoft Entra ID.|When your Azure DevOps Services organization is connected to a directory that is associated with a Microsoft 365 or Microsoft Azure subscription, only members in the directory can access the account.

      Check with your directory administrator to have them [create an organizational account for you or add your account to the directory as external member](/azure/active-directory/active-directory-create-users).| +|You can't switch between different organizational accounts.|If you work with several organizations that connect to different directories, such as accounts created from the Microsoft Azure portal, the sign out function might not work as expected. For example, you can't switch between different organizational accounts to connect to multiple accounts that are linked to directory tenants.

      When this problem occurs, there's a flashing blank sign in dialog box. Then, you receive either TF31002 or TF31003 error after you connect to or add a new connection in the dialog box.

      To resolve this problem, apply the most recent [Visual Studio update](https://visualstudio.microsoft.com/downloads) .

      For more information, see [You can't switch between different organizational accounts in Visual Studio Codespace](/troubleshoot/visualstudio/general/cannot-switch-accounts).| +|You want to sign in to Azure DevOps Services from Visual Studio using different credentials.|See [Connect to projects, Sign in with different credentials](../organizations/projects/connect-to-projects.md).| + ::: moniker-end ::: moniker range="< azure-devops" @@ -94,16 +105,42 @@ When you get redirected back to the original sign-in page, we recommend that you Here's a list of the most frequently reported connection problems and what to do about them. Complete the list in the order indicated. 1. Verify that you have the required permissions. - If the errors that you receive indicate read-only or blocked actions, you might not have permissions to act on the data. - 2. Verify that your computer is connected to the network and that it can access network resources. - -3. Verify that Azure DevOps Server hasn't been taken offline. Talk with your Azure DevOps Server administrator. - -4. Check whether your project has been moved to another project collection in Azure DevOps Server. If it has been moved, you must create a connection to the new server name. - -For additional troubleshooting tips, see [TF31002: Unable to connect to this Azure DevOps Server](../organizations/projects/tf31002-unable-connect-tfs.md). +3. Verify that Azure DevOps Server isn't offline. Check with your Azure DevOps Server administrator. +4. Check whether your project was moved to another project collection in Azure DevOps Server. If it was moved, you must create a connection to the new server name. +5. Verify you're using a [supported version of Azure DevOps Server](/azure/devops/server/requirements). + +## TF31002: Unable to connect + +If you get this error from one computer but not others, or others aren't receiving this error, then check the following resolutions. + +|Problem|Resolution| +|-------------|----------------| +|Your password expired.|Verify that you entered your user ID and password correctly, and that your password didn't expire.| +|You entered an incorrect server URL.|Verify that you entered the server URL correctly including the server name, port number, and protocol (http/https). For more information, see [Connect to projects](../organizations/projects/connect-to-projects.md).| +|The configuration changed.|If the configuration for the on-premises Azure DevOps Server changed, you must create a new connection. You might also need to [clear the client cache](../organizations/projects/connect-to-projects.md).| +|You work remotely and need to connect to an Azure DevOps Proxy server to check in files to Azure DevOps Server version control.| [Configure Visual Studio to connect to Azure DevOps Proxy](../organizations/projects/connect-to-projects.md).| +|You're connecting to a later version of Azure DevOps Server than your Visual Studio client version.|Your version of Visual Studio or Team Explorer might be incompatible with Azure DevOps Server. You might need to install one or more General Distribution Release (GDR) packs. For more information, see [Requirements and compatibility](/azure/devops/server/requirements).| +|Your firewall is blocking Azure DevOps.|See [Allow a program to communicate through Windows Firewall](/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc766312(v=ws.10)).| +|Visual Studio stops responding when you run a query in Visual Studio.|Your computer might be configured to bypass the proxy server. Verify the configuration of the BypassProxyOnLocal setting on your computer. For more information, see [BypassProxyOnLocal Configuration](/previous-versions/visualstudio/visual-studio-2008/ee248646(v=vs.90)).| + +### Several users can't connect to Azure DevOps Server + +If the problem occurs on more than one computer, contact your administrator to confirm whether the server is operational and available on the network. + +As an administrator, check the event logs for the application-tier server to try to pinpoint the problem. Also, you can use the following table to determine whether the server is misconfigured. In the table, problems that are more likely to occur appear first. Try the resolutions in the order in which they appear, which increases the chance that you can solve the problem quickly. + +|Problem|Resolution| +|-------------|----------------| +|The *TFSService* account password is expired or incorrect.|Many services for Azure DevOps Server stop running when the service account expires. For more information, see [Change the service account or password for Azure DevOps Server](/azure/devops/server/admin/change-service-account-password).| +|The application-tier server for Azure DevOps Server is unavailable.|Verify whether each required service is running. If a required service isn't running, you must restart it. If necessary, set it to start automatically. For more information, see [Stop and start services, application pools, and websites](/azure/devops/server/admin/stop-start-services-pools).| +|The network is unavailable.|Verify whether your network is operational.| +|A website identity for Azure DevOps Server is configured incorrectly.|Verify or correct the server binding assignments that are made to websites for Azure DevOps Server. | +|Access to a website for Azure DevOps Server is restricted.|Verify or correct restrictions that are made to those websites that are based on IP addresses and domain names. | +|The firewall or ports are configured incorrectly.|Verify or correct port binding assignments for websites and port assignments for the firewall. First, you should open the administration console for Azure DevOps Server, display the Application Tier page, and review the URL assignments. If necessary, select **Change URL** to modify the URL of a website. Next, you should verify the port assignments for Internet Information Services (IIS) and the ports that are allowed through the firewall. For more information, see [Review Server Status and Settings](/azure/devops/server/admin/stop-start-services-pools) and [Verify or Correct Port Assignments](/azure/devops/server/architecture/required-ports).| +|Trust relationships between domains aren't configured correctly.|If a group of users can't access Azure DevOps Server, you might have trust issues between domains.| +|When users connect to different versions of Azure DevOps Server from Visual Studio, they can get the TF31002 error.|This error can occur because the GUIDs for one version are the same as another version of Azure DevOps Server. The local client cache gets confused because it tries to maintain the same GUID-based local cache for both versions.

      To fix, run the **TFSConfig ChangeServerID** command. See [TFSConfig ChangeServerID command](/azure/devops/server/command-line/tfsconfig-cmd#changeserverid).| ::: moniker-end @@ -111,7 +148,7 @@ For additional troubleshooting tips, see [TF31002: Unable to connect to this Azu ## Switch organizations -When you use two or more organizations that are linked to Azure AD, the sign-out function might not work as expected. For example, you can't switch between different organizations to connect to multiple organizations that are linked to directory tenants. +When you use two or more organizations that are linked to Microsoft Entra ID, the sign out function might not work as expected. For example, you can't switch between different organizations to connect to multiple organizations that are linked to directory tenants. When this problem occurs, a blank screen flashes several times. Then, one of the following error messages appears after you connect to or add a new connection in the **Connect to Azure DevOps Server** dialog box: @@ -129,7 +166,7 @@ Another solution is to delete your browser cookies. For more information, see th ## Connect to Azure DevOps Server with Secure Sockets Layer -If you connect to an Azure DevOps Server instance that has Secure Sockets Layer (SSL) configured, install a certificate and clear the client cache. For details, see [Set up HTTPS with Secure Sockets Layer (SSL) for Azure DevOps Server - Configuring client computers](/azure/devops/server/admin/setup-secure-sockets-layer#config-client-computers). +If you connect to an Azure DevOps Server instance that has Secure Sockets Layer (SSL) configured, install a certificate and clear the client cache. For more information, see [Set up HTTPS with Secure Sockets Layer (SSL) for Azure DevOps Server - Configuring client computers](/azure/devops/server/admin/setup-secure-sockets-layer#config-client-computers). ## Clear the cache on client computers diff --git a/docs/user-guide/user-guide-faqs.yml b/docs/user-guide/user-guide-faqs.yml deleted file mode 100644 index f24b237d75f..00000000000 --- a/docs/user-guide/user-guide-faqs.yml +++ /dev/null @@ -1,118 +0,0 @@ -### YamlMime:FAQ -metadata: - title: Questions and answers to support getting started - titleSuffix: Azure DevOps - ms.topic: faq - ms.custom: seodec18 - description: FAQs to support getting started using the hosted cloud offering and on-premises offering of Azure DevOps - ms.subservice: azure-devops-new-user - ms.assetid: 50CA182B-D305-41A9-8C8F-9EA80A89ED3C - ms.author: chcomley - author: chcomley - ms.date: 02/08/2022 - monikerRange: '<= azure-devops' - -title: FAQs about signing up and getting started -summary: | - [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] - - Signing up for Azure DevOps is now easier than ever - it's a two-minute process. See the following frequently asked questions (FAQs), which contain links for getting started. - -sections: - - name: Ignored - questions: - - question: How do I sign up for the cloud? - answer: | - - [Sign up and get started in Azure DevOps Services - a two-minute process](../organizations/accounts/create-organization.md). - - You can also sign up and get started with only a single service in Azure DevOps: - - [Azure Pipelines](../pipelines/get-started/pipelines-sign-up.md) - - [Azure Repos](../repos/get-started/sign-up-invite-teammates.md) - - [Azure Boards](../boards/get-started/sign-up-invite-teammates.md) - - - question: How do I get started on-premises? - answer: | - ::: moniker range=">= azure-devops-2019" - - - Download and install [Azure DevOps Server](https://azure.microsoft.com/services/devops/server/) - - ::: moniker-end - - ::: moniker range="tfs-2018" - - - To get started with an on-premises instance, download and install the [latest version of TFS](https://visualstudio.microsoft.com/downloads/). - - [Configure the installation](/azure/devops/server/install/get-started), which creates a default collection. - - If you need to create a project, [create one on-premises](../organizations/projects/create-project.md). - - If you don't have access to the project, [get invited to the team](../organizations/security/add-users-team-project.md). - - If it's your first time connecting to a project, see [Connect to a project](../organizations/projects/connect-to-projects.md). - ::: moniker-end - - - question: How do I connect with a client tool? - answer: | - Go to one of the following pages to download a version of Visual Studio or client tool plug-in that supports connecting to a project: - - - [Visual Studio](https://visualstudio.microsoft.com/downloads/) - - [Eclipse/Team Explorer Everywhere](/previous-versions/azure/devops/all/java/download-eclipse-plug-in) - - [Android Studio with the Azure DevOps Services Plugin for Android Studio](/previous-versions/azure/devops/all/java/download-android-studio-plug-in) - - [IntelliJ with the Azure DevOps Services Plugin for IntelliJ](/previous-versions/azure/devops/all/java/download-intellij-plug-in) - - [Visual Studio Code](/previous-versions/azure/devops/all/java/vscode-extension) - - - question: How much does Azure DevOps cost? - answer: | - See the following links for pricing: - - - [Azure DevOps Services pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) - - [Azure DevOps on-premises pricing](https://azure.microsoft.com/pricing/details/devops/on-premises/) - - [Azure Pipelines only pricing](https://azure.microsoft.com/pricing/details/devops/azure-pipelines/) - - - question: How do I share code? - answer: | - See about [sharing code](roles.md#software-developers). - - - question: How do I track work? - answer: | - See [Plan and track work](../boards/get-started/plan-track-work.md). - - - question: What do I do as an admin? - answer: | - See [Administrator roles](roles.md#administrator-roles). - - - question: What client-server compatibility issue are there? - answer: | - See [Requirements and compatibility](/azure/devops/server/requirements). - - - question: Can stakeholders who don't use Visual Studio participate on our team? - answer: | - Yes. You can provide access to Stakeholders who have no client access license for the following activities: - - - **Stakeholder access**: This view allows anyone on your team to check project status and provide feedback. Stakeholders can [track project priorities and provide direction, feature ideas, and business alignment to a team](../organizations/security/get-started-stakeholder.md). - - To grant Stakeholders access, add them to the [Stakeholder access group](../organizations/security/change-access-levels.md). - - - **Provide feedback**: To allow your Stakeholders to provide feedback, you must [grant them specific permissions](../project/feedback/give-permissions-feedback.md). - - - question: Are there other clients that connect to Azure DevOps? - answer: | - Yes. You can connect to a project from one of the following clients: - - - [Excel](../boards/backlogs/office/bulk-add-modify-work-items-excel.md) (requires Azure DevOps Office Integration add-in) - - [Project Professional](/previous-versions/azure/devops/reference/tfs-ps-sync/synchronize-tfs-project-server) - - [Azure Test Plans](/previous-versions/jj635157(v=vs.140)) - - [Test & Feedback extension (previously called the Exploratory Testing extension)](../test/provide-stakeholder-feedback.md) - - [Microsoft Feedback Client](../project/feedback/give-feedback.md) - - For TFS 2017 and later versions, you can [install the TFS Process Template editor from the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KarthikBalasubramanianMSFT.TFSProcessTemplateEditor). You can use this version of the Process Editor to modify the old-style work item forms. You can't use it to edit forms associated with the [new web forms](/previous-versions/azure/devops/reference/process/new-work-item-experience). - - For TFS 2015 and earlier versions, you can install [TFS Power Tools](https://marketplace.visualstudio.com/items?itemName=TFSPowerToolsTeam.MicrosoftVisualStudioTeamFoundationServer2015Power). TFS Power Tools provide enhancements, tools, and command-line utilities that support increased productivity. - - > [!NOTE] - > Team Foundation Server Power Tools is deprecated for TFS 2017 and later versions. - - - question: Why can't I connect to a project? - answer: | - See [Troubleshoot connection](troubleshoot-connection.md). - - - question: Related articles - answer: | - - [Essential services](services.md) - - [Client-server tools](tools.md) - - [Software development roles](roles.md) - - [Azure DevOps Support](https://developercommunity.visualstudio.com/spaces/21/index.html) - - [Live chat](https://visualstudio.microsoft.com/vs/support/#talktous) (English only) diff --git a/docs/user-guide/what-is-azure-devops.md b/docs/user-guide/what-is-azure-devops.md index 8f11fb6b6b4..71b9b0a12a8 100644 --- a/docs/user-guide/what-is-azure-devops.md +++ b/docs/user-guide/what-is-azure-devops.md @@ -1,35 +1,40 @@ --- -title: What is Azure DevOps? -titleSuffix: Azure DevOps -ms.custom: seodec18, contperf-fy21q3, engagement-fy23 +title: What is Azure DevOps +titleSuffix: Azure DevOps +ms.custom: engagement-fy23, UpdateFrequency3 ms.topic: overview -description: Get an integrated set of features to help you plan, code, collaborate, and ship your applications faster. +description: Get an overview of the integrated set of features in Azure DevOps so you can plan, code, collaborate, and ship your applications faster. ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 10/10/2022 +ms.date: 04/22/2025 +#customer intent: As a developer, I want to understand the features in Azure DevOps so I can plan, code, collaborate, and ship my applications faster. --- # What is Azure DevOps? [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -Azure DevOps supports a collaborative culture and set of processes that bring together developers, project managers, and contributors to develop software. It allows organizations to create and improve products at a faster pace than they can with traditional software development approaches. +Azure DevOps supports a collaborative culture and set of processes that bring together developers, project managers, and contributors to build software. It allows organizations to create and improve products at a faster pace than they can with traditional software development approaches. -You can work in the cloud using [Azure DevOps Services](services.md) or on-premises using Azure DevOps Server. For more information, see [Differences between Azure DevOps Services and Azure DevOps Server](about-azure-devops-services-tfs.md). +You can work in the cloud with [Azure DevOps Services](services.md) or on-premises with Azure DevOps Server. For more information, see [Differences between Azure DevOps Services and Azure DevOps Server](about-azure-devops-services-tfs.md). -Azure DevOps provides integrated features that you can access through your web browser or IDE client. You can use all the services included with Azure DevOps, or choose just what you need to complement your existing workflows. +Azure DevOps provides integrated features that you can access through your web browser or IDE client. You can use all the services included with Azure DevOps or choose just what you need to complement your existing workflows. -|Standalone service |Description | -|---------------------|-------------| -|[Azure Boards](https://azure.microsoft.com/services/devops/boards/)| Delivers a suite of Agile tools to support planning and tracking work, code defects, and issues using Kanban and Scrum methods. For more information about Azure Boards, see [What is Azure Boards?](../boards/get-started/what-is-azure-boards.md). | -|[Azure Repos](https://azure.microsoft.com/services/devops/repos/)| Provides Git repositories or Team Foundation Version Control (TFVC) for source control of your code. For more information about Azure Repos, see [What is Azure Repos?](../repos/get-started/what-is-repos.md). | -|[Azure Pipelines](https://azure.microsoft.com/services/devops/pipelines/)| Provides build and release services to support continuous integration and delivery of your applications. For more information about Azure Pipelines, see [What is Azure Pipelines?](../pipelines/get-started/what-is-azure-pipelines.md). | -|[Azure Test Plans](https://azure.microsoft.com/products/devops/test-plans/) | Provides several tools to test your apps, including manual/exploratory testing and continuous testing. For more information about Azure Test Plans, see [Overview of Azure Test Plans](../test/overview.md). | -|[Azure Artifacts](https://azure.microsoft.com/products/devops/artifacts/) | Allows teams to share packages such as Maven, npm, NuGet, and more from public and private sources and integrate package sharing into your pipelines. For more information about Azure Artifacts, see [Overview of Azure Artifacts](../pipelines/artifacts/artifacts-overview.md). | +## Explore standalone services -Azure DevOps supports adding extensions and integrating with other popular services, such as: Campfire, Slack, Trello, UserVoice, and more, and developing your own custom extensions. +The following table describes the standalone services available with Azure DevOps: + +|Standalone service |Description | +|-------------------|------------| +|[Azure Boards](https://azure.microsoft.com/products/devops/boards/) | Delivers a suite of Agile tools to support planning and tracking work, code defects, and issues by using Kanban and Scrum methods. For more information about Azure Boards, see [What is Azure Boards?](../boards/get-started/what-is-azure-boards.md) | +|[Azure Repos](https://azure.microsoft.com/products/devops/repos/) | Provides Git repositories or Team Foundation Version Control (TFVC) for source control of your code. For more information about Azure Repos, see [What is Azure Repos?](../repos/get-started/what-is-repos.md) | +|[Azure Pipelines](https://azure.microsoft.com/products/devops/pipelines/) | Provides build and release services to support continuous integration and delivery of your applications. For more information about Azure Pipelines, see [What is Azure Pipelines?](../pipelines/get-started/what-is-azure-pipelines.md) | +|[Azure Test Plans](https://azure.microsoft.com/products/devops/test-plans/) | Provides several tools to test your applications, including manual/exploratory testing and continuous testing. For more information about Azure Test Plans, see [Overview of Azure Test Plans](../test/overview.md). | +|[Azure Artifacts](https://azure.microsoft.com/products/devops/artifacts/) | Allows teams to share packages such as Maven, npm, NuGet, and more from public and private sources and integrate package sharing into your pipelines. For more information about Azure Artifacts, see [Overview of Azure Artifacts](../pipelines/artifacts/artifacts-overview.md). | + +Azure DevOps supports adding extensions and integrating with other popular services, such as Slack, Trello, UserVoice, and more. You can also develop your own custom extensions for use with Azure DevOps. ## Choose Azure DevOps Services @@ -41,37 +46,35 @@ Azure DevOps *Services* supports integration with GitHub.com and GitHub Enterpri - Elastic scale - Rock-solid security -Azure DevOps Services also gives you access to cloud build and deployment servers, and application insights. -[Start for free](sign-up-invite-teammates.md) and create an organization. Then, either upload your code to share or source control. Begin tracking your work using Scrum, Kanban, or a combination of methods. +Azure DevOps Services also gives you access to cloud build and deployment servers, and application insights. [Start for free](sign-up-invite-teammates.md) and create an organization. Then, either upload your code to share or source control. Begin tracking your work by using Scrum, Kanban, or a combination of methods. For more information, see the [Azure DevOps and GitHub integration overview](../cross-service/github-integration.md). ## Choose Azure DevOps Server -Azure DevOps *Server* supports integration with GitHub Enterprise Server repositories. Choose on-premises Azure DevOps Server when: - -- You need your data to stay within your network. -- Your work tracking customization requirements are met better with the on-premises XML process model over the inheritance process model. The on-premises model supports modification of XML definition files. +Azure DevOps *Server* supports integration with GitHub Enterprise Server repositories. Choose on-premises Azure DevOps Server if you need your data to stay within your network. The on-premises XML process model can also better support your work tracking customization requirements over the inheritance process model. The on-premises model supports modification of XML definition files. When you deploy Azure DevOps Server, you can also configure the following servers or integration points: -- **Build server** supports on-premises and cloud-hosted builds. -- **SQL Server and SQL Analysis Server** support SQL Server Reports and the ability to create Excel pivot charts based on the cube. +- **Build server**: Support on-premises and cloud-hosted builds. +- **SQL Server and SQL Analysis Server**: Support SQL Server Reports and the ability to create Excel pivot charts based on the cube. -Start for free by downloading [Azure DevOps Server Express](https://go.microsoft.com/fwlink/?LinkId=2041269&clcid=0x409). Then, either upload your code to share or source control. Or, begin tracking your work using Scrum, Kanban, or a combination of methods. +Start for free by downloading [Azure DevOps Server Express](https://go.microsoft.com/fwlink/?LinkId=2041269&clcid=0x409). Then, either upload your code to share or source control. Or, begin tracking your work by using Scrum, Kanban, or a combination of methods. For more information about managing Azure DevOps Server, see the [Administrative tasks quick reference](/azure/devops/server/admin/admin-quick-ref). -## Next steps +## Get started with Azure DevOps + +Get started working with Azure DevOps now: -> [!div class="nextstepaction"] -> [Sign up for Azure DevOps Services](sign-up-invite-teammates.md) or [Install Azure DevOps Server](/azure/devops/server/install/single-server) +- [Review pricing models for Azure DevOps](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) +- [Sign up for Azure DevOps Services](sign-up-invite-teammates.md) +- [Install Azure DevOps Server](/azure/devops/server/install/single-server) +- [Tour an overview of the services](services.md) -## Related articles +## Related content -- [A tour of services](services.md) - [Data protection overview](../organizations/security/data-protection.md) - [Client-server tools](tools.md) - [Software development roles](roles.md) -- [Azure DevOps pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) -- [Azure DevOps and GitHub integration overview](../cross-service/github-integration.md) +- [Azure DevOps and GitHub integration overview](../cross-service/github-integration.md) \ No newline at end of file diff --git a/docs/user-guide/work-team-explorer.md b/docs/user-guide/work-team-explorer.md index ef23cb5e3e7..f0843514300 100644 --- a/docs/user-guide/work-team-explorer.md +++ b/docs/user-guide/work-team-explorer.md @@ -33,12 +33,11 @@ If you don't need Visual Studio, but want to connect to a project in Azure DevOp ## Prerequisites -- You must have a project in Azure DevOps. If you need to add a project, see [Create a project](../organizations/projects/create-project.md). -- You must be a member of the project you connect to. To get added, see [Add users to a project or team](../organizations/security/add-users-team-project.md). +[!INCLUDE [prerequisites-project-member-only](../includes/prerequisites-project-member-only.md)] ## Connect to a project or repository -Team Explorer connects Visual Studio to projects in Azure DevOps. You can manage source code, work items, and builds. The operations available to you depend on which source control option—Git or Team Foundation version control (TFVC) —was selected to manage source code when the project was created. +Team Explorer connects Visual Studio to projects in Azure DevOps. You can manage source code, work items, and builds. The operations available to you depend on which source control option—Git or Team Foundation version control (TFVC)—was selected to manage source code when the project was created. > [!TIP] > If you open Visual Studio and the Team Explorer pane doesn't appear, choose the **View>Team Explorer** menu option from the tool bar. @@ -58,7 +57,7 @@ The following image shows the pages available when you connect to a Git reposito ![Screenshot of Visual studio 2019, Team Explorer Home page with Git as source control.](media/vs-2019-te/te-git-full.png) -To learn more about each page, see the following articles. +For more information about each page, see the following articles. :::row::: @@ -106,7 +105,7 @@ To learn more about each page, see the following articles. - [Query folders](../boards/queries/organize-queries.md) - [Query permissions](../boards/queries/set-query-permissions.md) - [Open query in Excel](../boards/backlogs/office/bulk-add-modify-work-items-excel.md) - - [Email query results using Outlook](../boards/queries/share-plans.md) + - [Send email with work item or print](../boards/work-items/email-work-items.md) - [Create reports from query in Excel](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports) :::column-end::: :::row-end::: @@ -118,7 +117,7 @@ The following image shows the pages available when you connect to a TFVC reposit ![Screenshot of Visual Studio 2019, Team Explorer Home page with TFVC as source control.](media/vs-2019-te/te-tfvc.png) -To learn more about each page, see the following articles. +For more information about each page, see the following articles. :::row::: @@ -163,7 +162,7 @@ To learn more about each page, see the following articles. - [Query folders](../boards/queries/organize-queries.md) - [Query permissions](../boards/queries/set-query-permissions.md) - [Open query in Excel](../boards/backlogs/office/bulk-add-modify-work-items-excel.md) - - [Email query results using Outlook](../boards/queries/share-plans.md) + - [Send email with work item or print](../boards/work-items/email-work-items.md) - [Create reports from query in Excel](/previous-versions/azure/devops/report/admin/create-status-and-trend-excel-reports) :::column-end::: :::row-end::: @@ -178,15 +177,15 @@ To learn more about each page, see the following articles. > [!NOTE] > Some pages, such as **Reports**, only appear when an on-premises TFS is configured with the required resources, such as SQL Server Reporting Services. -The **Reports** page opens the [Reporting Services report site](/previous-versions/azure/devops/report/sql-reports/reporting-services-reports). This page appears only when your project has been configured with SQL Server Analysis Services and Reporting Services. Also, the option to **Create Report in Microsoft Excel** appears only when reporting has been configured for the project. +The **Reports** page opens the [Reporting Services report site](/previous-versions/azure/devops/report/sql-reports/reporting-services-reports). This page appears only when your project is configured with SQL Server Analysis Services and Reporting Services. Also, the option to **Create Report in Microsoft Excel** appears only when reporting is configured for the project. -If your project is missing one or more pages, you may be able to [add functionality to your on premises TFS deployment](/azure/devops/server/admin/admin-quick-ref). +If your project is missing one or more pages, try to [add functionality to your on-premises TFS deployment](/azure/devops/server/admin/admin-quick-ref). ::: moniker-end ## Settings -From the **Settings** page, you can configure administrative features for either a project or project collection. To learn more about each page, see the following articles. Most of the links open to a web portal administration page. Not all settings are available from the Team Explorer plug-in for Eclipse. +From the **Settings** page, you can configure administrative features for either a project or project collection. For more information about each page, see the following articles. Most of the links open to a web portal administration page. Not all settings are available from the Team Explorer plug-in for Eclipse. :::row::: :::column span=""::: @@ -212,16 +211,16 @@ From the **Settings** page, you can configure administrative features for either :::row-end::: -To learn more about settings, see [About team, project, and organizational-level settings](../organizations/settings/about-settings.md). +For more information, see [About team, project, and organizational-level settings](../organizations/settings/about-settings.md). ## Refresh Team Explorer If data doesn't appear as expected, the first thing to try is to refresh your client. Refreshing your client updates the local cache with changes that were made in another client or in Azure DevOps. To refresh Team Explorer, do one of the following actions: -- To refresh a page that you are currently viewing, choose :::image type="icon" source="../boards/media/icons/te-refresh-query-icon.png" border="false"::: **Refresh** in the menu bar (or choose **F5**). -- To refresh the project you currently have selected, choose :::image type="icon" source="media/work-team-explorer/IC547418.png" border="false"::: **Home**, and then choose ![Refresh icon](../boards/media/icons/te-refresh-query-icon.png) **Refresh** (or choose **F5**). -- To refresh the set of teams defined for the project that you currently have selected, choose **Connect**, and then choose :::image type="icon" source="../boards/media/icons/te-refresh-query-icon.png" border="false"::: **Refresh** (or enter **F5**). +- To refresh a page that you're currently viewing, choose :::image type="icon" source="../boards/media/icons/te-refresh-query-icon.png" border="false"::: **Refresh** in the menu bar (or choose **F5**). +- To refresh the project you selected, choose :::image type="icon" source="media/work-team-explorer/IC547418.png" border="false"::: **Home**, and then choose ![Refresh icon](../boards/media/icons/te-refresh-query-icon.png) **Refresh** (or choose **F5**). +- To refresh the set of teams defined for the project that you selected, choose **Connect**, and then choose :::image type="icon" source="../boards/media/icons/te-refresh-query-icon.png" border="false"::: **Refresh** (or enter **F5**). [!INCLUDE [temp](includes/when-to-refresh-client.md)] diff --git a/docs/zone-pivot-groups.yml b/docs/zone-pivot-groups.yml index 6270508849d..099c73807c5 100644 --- a/docs/zone-pivot-groups.yml +++ b/docs/zone-pivot-groups.yml @@ -15,4 +15,36 @@ groups: - id: templates-includes title: Includes templates - id: templates-extends - title: Extends templates \ No newline at end of file + title: Extends templates +- id: key-vault-access-path + title: Private Key Vault access + prompt: Select a method to access a private Azure Key Vault + pivots: + - id: access-from-azure-devops + title: Access from Azure DevOps + - id: access-from-self-hosted-agent + title: Access from a self-hosted agent +- id: powershell-versions + title: PSResourceGet and PowerShellGet + prompt: Choose a version + pivots: + - id: psresourceget + title: PSResourceGet + - id: powershelget + title: PowerShellGet +- id: github-actions-auth + title: Authentication version + prompt: Choose an authentication method + pivots: + - id: pat + title: PAT + - id: managed-identity + title: Managed identity +- id: pipelines-docker-acr + title: Docker and ACR registries + prompt: Choose a container registry + pivots: + - id: acr-registry + title: ACR registry + - id: docker-registry + title: Docker registry \ No newline at end of file diff --git a/release-notes/.DS_Store b/release-notes/.DS_Store deleted file mode 100644 index 6eed0997fc4..00000000000 Binary files a/release-notes/.DS_Store and /dev/null differ diff --git a/release-notes/.openpublishing.redirection.release-notes.json b/release-notes/.openpublishing.redirection.release-notes.json index f58eb00be06..378f77c07b0 100644 --- a/release-notes/.openpublishing.redirection.release-notes.json +++ b/release-notes/.openpublishing.redirection.release-notes.json @@ -534,6 +534,98 @@ "source_path_from_root": "/release-notes/index.md", "redirect_url": "/azure/devops/release-notes/features-timeline" }, + { + "source_path_from_root": "/release-notes/roadmap/support-flexible-orchestration-mode.md", + "redirect_url": "/azure/devops/pipelines/agents/scale-set-agents#orchestration-modes" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-12.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-11.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-10.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-09.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-08.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-07.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-06.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-05.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-04.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-03.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-02.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2024-01.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-12.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-11.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-10.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-09.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-08.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-07.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-06.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-05.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-04.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-03.md", + "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, { "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2023-02.md", "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" @@ -685,6 +777,10 @@ { "source_path_from_root": "/release-notes/docswhatsnew/azure-devops-docs-2020-01.md", "redirect_url": "/azure/devops/release-notes/docswhatsnew/azure-devops-docs-whats-new" + }, + { + "source_path_from_root": "/release-notes/roadmap/2022/resume-test-execution.md", + "redirect_url": "/azure/devops/test/" } ] } diff --git a/release-notes/2018/apr-03-vsts.md b/release-notes/2018/apr-03-vsts.md index 5a9568100dc..04950eadf83 100644 --- a/release-notes/2018/apr-03-vsts.md +++ b/release-notes/2018/apr-03-vsts.md @@ -1,7 +1,5 @@ --- title: Deployment Groups and Build completion trigger – VSTS Sprint 132 Update -author: alexcnichols -ms.author: alexn ms.date: 4/3/2018 description: The Sprint 132 Update of Visual Studio Team Services (VSTS) brings a few key features to help you scale your build and release pipeline. --- diff --git a/release-notes/2018/apr-16-vsts.md b/release-notes/2018/apr-16-vsts.md index f8d0f8448bb..69ad574a982 100644 --- a/release-notes/2018/apr-16-vsts.md +++ b/release-notes/2018/apr-16-vsts.md @@ -1,7 +1,5 @@ --- title: Deployment for Azure Database for MySQL, Kubernetes with Helm, and Ruby on Rails – VSTS Sprint 133 Update -author: alexcnichols -ms.author: alexn ms.date: 4/16/2018 description: In the **Sprint 133 Update** of Visual Studio Team Services (VSTS), we continue to expand on the languages and platforms we support for build and release. --- @@ -71,7 +69,7 @@ However, with this Update, the full phrase is returned and highlighted. ## Work - + ### Query work in the Area Paths of a Team with the new @TeamAreas macro diff --git a/release-notes/2018/aug-03-vsts.md b/release-notes/2018/aug-03-vsts.md index 5f9c44420f7..0af54fe56c8 100644 --- a/release-notes/2018/aug-03-vsts.md +++ b/release-notes/2018/aug-03-vsts.md @@ -1,7 +1,5 @@ --- title: Review summarized test results – VSTS Sprint 138 Update -author: alexcnichols -ms.author: alexn ms.date: 08/03/2018 description: In the Sprint 138 Update of Visual Studio Team Services (VSTS), the results pages for Build and release pipelines has been enhanced with a summarized view of test results that organizes related outcomes into a hierarchy. --- diff --git a/release-notes/2018/aug-21-vsts.md b/release-notes/2018/aug-21-vsts.md index 516cdafb089..f451d99c33b 100644 --- a/release-notes/2018/aug-21-vsts.md +++ b/release-notes/2018/aug-21-vsts.md @@ -1,7 +1,5 @@ --- title: Ease customization by migrating projects to the Inheritance process model – VSTS Sprint 139 Update -author: alexcnichols -ms.author: alexn ms.date: 8/21/2018 description: In the Sprint 139 Update of Visual Studio Team Services (VSTS), you can now migrate Hosted XML projects to the Inheritance process model to ease customization. --- diff --git a/release-notes/2018/feb-14-vsts.md b/release-notes/2018/feb-14-vsts.md index ab6f00e279a..f1b4c745fea 100644 --- a/release-notes/2018/feb-14-vsts.md +++ b/release-notes/2018/feb-14-vsts.md @@ -1,7 +1,5 @@ --- title: Package upstream sources and symbol server generally available – VSTS Sprint 130 Update -author: alexcnichols -ms.author: alexn ms.date: 2/14/2018 ms.topic: article ms.manager: jillfra diff --git a/release-notes/2018/jan-24-vsts.md b/release-notes/2018/jan-24-vsts.md index ee85daa4a5e..e9867cc8678 100644 --- a/release-notes/2018/jan-24-vsts.md +++ b/release-notes/2018/jan-24-vsts.md @@ -1,7 +1,5 @@ --- title: Improved GitHub builds and suggested work item paths – VSTS Sprint 129 Update -author: alexcnichols -ms.author: alexn ms.date: 1/24/2018 ms.topic: article ms.manager: jillfra @@ -31,7 +29,7 @@ Other feature highlights include: Installing the [Analytics extension](https://marketplace.visualstudio.com/items?itemName=ms.vss-analytics) adds 6 powerful widgets to your widget catalog: Cumulative Flow Diagram, Lead Time, Cycle Time, Velocity, Burndown, and Burnup. Now, those with the free [Stakeholder license](/azure/devops/organizations/security/get-started-stakeholder#related-articles) can view all the Analytics widgets too! -To use the [Analytics OData endpoint](/azure/devops/report/extend-analytics/index) or [Power BI to connect to Analytics](/azure/devops/report/powerbi/index), a [Basic license](https://visualstudio.microsoft.com/team-services/compare-features/) is still required. +To use the [Analytics OData endpoint](/azure/devops/report/extend-analytics/index) or [Power BI to connect to Analytics](/azure/devops/report/powerbi/index), a [Basic license](https://visualstudio.microsoft.com/vs/compare/) is still required. ### Integrate Power BI with VSTS Analytics using new views diff --git a/release-notes/2018/jul-10-vsts.md b/release-notes/2018/jul-10-vsts.md index 361a21fdca6..c9110bf0e36 100644 --- a/release-notes/2018/jul-10-vsts.md +++ b/release-notes/2018/jul-10-vsts.md @@ -1,7 +1,5 @@ --- title: Microsoft-hosted Linux and macOS agents generally available – VSTS Sprint 137 Update -author: alexcnichols -ms.author: alexn ms.date: 7/10/2018 description: In the Sprint 137 Update of Visual Studio Team Services (VSTS), we remove the "Preview" moniker from our Linux and macOS Microsoft-hosted CI/CD agents and make them generally available. --- diff --git a/release-notes/2018/jun-19-vsts.md b/release-notes/2018/jun-19-vsts.md index bb7ee406b3f..fffbf4b89d0 100644 --- a/release-notes/2018/jun-19-vsts.md +++ b/release-notes/2018/jun-19-vsts.md @@ -1,7 +1,5 @@ --- title: Modernizing the UI – VSTS Sprint 136 Update -author: alexcnichols -ms.author: alexn ms.date: 6/22/2018 description: In the Sprint 136 Update of Visual Studio Team Services (VSTS), we introduce a more modern UI. --- @@ -273,9 +271,6 @@ See all dashboards in the project. When a Personal Access Token (PAT) is nearing expiration, you’ll get an email notification giving you the ability to immediately take action and extend the lifetime of the PAT so that your tools and processes will go on uninterrupted. -> [!div class="mx-imgBorder"] -> ![PAT expiration](media/136_08.png) - ## How to provide feedback We would love to hear what you think about these features. Use the feedback menu to report a problem or provide a suggestion. diff --git a/release-notes/2018/mar-05-vsts.md b/release-notes/2018/mar-05-vsts.md index 236e7a86c80..28396794b0c 100644 --- a/release-notes/2018/mar-05-vsts.md +++ b/release-notes/2018/mar-05-vsts.md @@ -1,7 +1,5 @@ --- title: Work Items hub and VM-based Azure DevOps Project – VSTS Sprint 131 Update -author: alexcnichols -ms.author: alexn ms.date: 3/5/2018 ms.topic: article ms.manager: jillfra @@ -57,7 +55,7 @@ Any project pivot can now be sorted based on a variety of options, including tit > ![Work Items sorting options](media/131_02.png) - + ### Query work across the iteration schedule with +/- @CurrentIteration diff --git a/release-notes/2018/may-07-vsts.md b/release-notes/2018/may-07-vsts.md index 58e55f0a8a2..8edcad51da0 100644 --- a/release-notes/2018/may-07-vsts.md +++ b/release-notes/2018/may-07-vsts.md @@ -1,7 +1,5 @@ --- title: Deploy to Azure Kubernetes Service (AKS) using DevOps Projects – VSTS Sprint 134 Update -author: alexcnichols -ms.author: alexn ms.date: 5/7/2018 ms.custom: devx-track-extended-java, devx-track-python description: The Sprint 134 Update of Visual Studio Team Services (VSTS) brings better support for Ruby, Python, and Java languages in Build and even more deployment options to Release. diff --git a/release-notes/2018/may-30-vsts.md b/release-notes/2018/may-30-vsts.md index b5f8498e570..f23bb5643d0 100644 --- a/release-notes/2018/may-30-vsts.md +++ b/release-notes/2018/may-30-vsts.md @@ -1,7 +1,5 @@ --- title: Visualize release progress – VSTS Sprint 135 Update -author: alexcnichols -ms.author: alexn ms.date: 5/30/2018 description: In the Sprint 135 Update of Visual Studio Team Services (VSTS), we bring a new way to visualize all your release activity. --- @@ -137,7 +135,7 @@ A new [Python Script](/azure/devops/pipelines/tasks#utility) task simplifies run ### Use Anaconda tools for data science in your pipeline -Miniconda is now available on Microsoft-hosted agents. The [conda](https://www.anaconda.com/distribution/) package and virtual environment manager makes it easy to install, run, and upgrade complex data science and machine learning environments like the SciPy stack, scikit-learn, CNTK, and TensorFlow. It will also install the version of Python that is needed by your pipeline. +Miniconda is now available on Microsoft-hosted agents. The [conda](https://www.anaconda.com/download) package and virtual environment manager makes it easy to install, run, and upgrade complex data science and machine learning environments like the SciPy stack, scikit-learn, CNTK, and TensorFlow. It will also install the version of Python that is needed by your pipeline. The new, built-in [Conda Environment](/azure/devops/pipelines/tasks/reference/conda-environment-v1) task also helps you create a conda environment. It activates the environment for subsequent pipeline steps, installs package dependencies, adds conda to the path, and optionally upgrades the agent to the latest version of conda. diff --git a/release-notes/2018/media/129_03.png b/release-notes/2018/media/129_03.png index f3baa464303..184b7127b44 100644 Binary files a/release-notes/2018/media/129_03.png and b/release-notes/2018/media/129_03.png differ diff --git a/release-notes/2018/media/136_08.png b/release-notes/2018/media/136_08.png deleted file mode 100644 index 7efb5b7c2fa..00000000000 Binary files a/release-notes/2018/media/136_08.png and /dev/null differ diff --git a/release-notes/2018/media/136_14.png b/release-notes/2018/media/136_14.png index eec35c6309d..7fc56633eae 100644 Binary files a/release-notes/2018/media/136_14.png and b/release-notes/2018/media/136_14.png differ diff --git a/release-notes/2018/media/140_01.png b/release-notes/2018/media/140_01.png index cad497e114b..3c03881011c 100644 Binary files a/release-notes/2018/media/140_01.png and b/release-notes/2018/media/140_01.png differ diff --git a/release-notes/2018/media/141_02.png b/release-notes/2018/media/141_02.png index b9b0dafba3d..72f43a59d0d 100644 Binary files a/release-notes/2018/media/141_02.png and b/release-notes/2018/media/141_02.png differ diff --git a/release-notes/2018/sep-10-azure-devops-launch.md b/release-notes/2018/sep-10-azure-devops-launch.md index b18e7274812..062e80dcdb0 100644 --- a/release-notes/2018/sep-10-azure-devops-launch.md +++ b/release-notes/2018/sep-10-azure-devops-launch.md @@ -1,7 +1,5 @@ --- title: Introducing Azure DevOps -author: alexcnichols -ms.author: alexn ms.date: 9/10/2018 description: The single service that was Visual Studio Team Services (VSTS) is now becoming our new set of Azure DevOps Services. Throughout our documentation, websites, and in-product you'll start to notice new icons and names for Azure DevOps all up and each of our services within Azure DevOps. --- diff --git a/release-notes/2018/sprint-140-update.md b/release-notes/2018/sprint-140-update.md index 53cf93b0ec2..3ff7b1f184b 100644 --- a/release-notes/2018/sprint-140-update.md +++ b/release-notes/2018/sprint-140-update.md @@ -1,7 +1,5 @@ --- title: Pipeline container jobs - Sprint 140 Update -author: alexcnichols -ms.author: alexn ms.date: 9/20/2018 description: In the Sprint 140 Update of Azure DevOps Services, you'll find a new way to customize build dependencies to your specific requirements with the introduction of container jobs in Azure Pipelines. --- @@ -104,7 +102,7 @@ Now you can embed videos in a wiki page from online services such as Microsoft S ```markdown ::: video - +> [!VIDEO https://www.youtube.com/embed/7DbslbKsQSk] ::: ``` diff --git a/release-notes/2019/includes/general/sprint-146-update.md b/release-notes/2019/includes/general/sprint-146-update.md index 087667bad26..c0c3db0b089 100644 --- a/release-notes/2019/includes/general/sprint-146-update.md +++ b/release-notes/2019/includes/general/sprint-146-update.md @@ -4,4 +4,4 @@ ms.topic: include ### Restore deleted projects -In this update, we added the ability to restore deleted projects from the Azure DevOps portal. If you have “delete project” permission you can also restore a deleted project from the **Organization Settings > Overview Page**. For step by step guidance, view the documentation [here](/azure/devops/organizations/projects/restore-project?view=azure-devops&preserve-view=true). \ No newline at end of file +In this update, we added the ability to restore deleted projects from the Azure DevOps portal. If you have “delete project” permission you can also restore a deleted project from the **Organization Settings > Overview Page**. \ No newline at end of file diff --git a/release-notes/2019/includes/general/sprint-153-update.md b/release-notes/2019/includes/general/sprint-153-update.md index 095b7ac0aed..91293f9cdec 100644 --- a/release-notes/2019/includes/general/sprint-153-update.md +++ b/release-notes/2019/includes/general/sprint-153-update.md @@ -32,9 +32,6 @@ The audit events will have information such as IP, who caused the event to be lo By default, only the project collection administrators can access the audit log. An administrator can grant separate permission to team members to access the audit logs. The auditing feature can be found under the Organizations settings. For more information, see our [documentation](/azure/devops/organizations/audit/azure-devops-auditing?view=azure-devops&preserve-view=true). -> [!div class="mx-imgBorder"] -> ![Azure auditing feature can be found under organizations settings.](../../media/153_01.png "Azure auditing feature can be found under organizations settings") - ### Manage security groups and permissions from the command line You can now manage security groups and permissions from the command line by using the **az devops security permission** commands. By using the commands, you can create scripts to manage permissions and standardize the process of creating security groups. In addition, you can use the commands to run reports to view a list of security groups and corresponding permissions. diff --git a/release-notes/2019/includes/general/sprint-156-update.md b/release-notes/2019/includes/general/sprint-156-update.md index e2720396e06..2d29474272a 100644 --- a/release-notes/2019/includes/general/sprint-156-update.md +++ b/release-notes/2019/includes/general/sprint-156-update.md @@ -5,6 +5,3 @@ ms.topic: include ### New UI to request access to an organization You can now request access to an organization with the new **request access UI**. If you belong to the same tenant as the Azure DevOps organization that you need access to, the new request access UI will let you notify the administrators of the organization with a justification for why you need access. The administrator(s) will receive an email notification from Azure DevOps with the details of the request. Details will include: email ID of the requestor, target organization name and justification. - -> [!div class="mx-imgBorder"] -> ![Request access to an organization.](../../media/156_21.png) diff --git a/release-notes/2019/includes/pipelines/sprint-149-update.md b/release-notes/2019/includes/pipelines/sprint-149-update.md index 35b80aa6b58..f84ce894984 100644 --- a/release-notes/2019/includes/pipelines/sprint-149-update.md +++ b/release-notes/2019/includes/pipelines/sprint-149-update.md @@ -6,7 +6,7 @@ ms.topic: include Previously, we checked out repos to the `s` directory under $(Agent.BuildDirectory). Now you can choose the directory where your Git repo will be checked out for use with YAML pipelines. -Use the `path` keyword on `checkout` and you will be in control of the folder structure. Below is an example of the YAML code that you can use to specify a directory. +Use the `path` keyword on `checkout` and you'll be in control of the folder structure. Below is an example of the YAML code that you can use to specify a directory. ```yaml steps: @@ -18,9 +18,9 @@ In this example, your code will be checked out to the `my-great-repo` directory ### Private projects now get 60 minutes of run time per pipeline job -Until now, a free account (that is, one which had not purchased parallel jobs) would run a job for up to 30 minutes at a time, up to 1,800 minutes per month. With this update, we have increased the limit from 30 to 60 minutes for free accounts. +Until now, a free account (that is, one which hadn't purchased parallel jobs) would run a job for up to 30 minutes at a time, up to 1,800 minutes per month. With this update, we have increased the limit from 30 to 60 minutes for free accounts. -If you need to run your pipeline for more than 60 minutes, you can pay for additional capacity per parallel job or run in a self-hosted agent. Self-hosted agents don't have a job length restrictions. +If you need to run your pipeline for more than 60 minutes, you can pay for additional capacity per parallel job or run in a self-hosted agent. Self-hosted agents don't have job length restrictions. ### Updates to hosted pipeline images @@ -39,7 +39,7 @@ In this update, we added a new task for build and release pipelines that allows ### Approve Azure Pipelines deployments from Slack -Until now, Slack users have had limited capabilities to manage release deployments from within a channel. The Azure Pipelines app for Slack lets you approve or reject a release deployment from the channel. This will make the approval process easier since you are not forced to navigate to the Azure Pipelines portal. In addition, you can approve deployments on the go by using the Slack mobile app. +Until now, Slack users have had limited capabilities to manage release deployments from within a channel. The Azure Pipelines app for Slack lets you approve or reject a release deployment from the channel. This will make the approval process easier since you aren't forced to navigate to the Azure Pipelines portal. In addition, you can approve deployments on the go by using the Slack mobile app. > [!div class="mx-imgBorder"] > ![Approve Azure Pipelines deployments from Slack.](../../media/149_03.png) @@ -67,4 +67,4 @@ With this update, we’ve added support to publish test results from a [CTest]( > [!div class="mx-imgBorder"] > ![Publish CTest and PHPUnit test results.](../../media/149_11.png) -In addition, we included publishing for [PHPUnit](https://phpunit.readthedocs.io/en/9.5/configuration.html) test runs. While JUnit results format has always been supported, you can now leverage the specific constructs of PHPUnit. For more details on publishing test results see the documentation [here](/azure/devops/pipelines/tasks/reference/publish-test-results-v2?view=azure-devops&preserve-view=true&tabs=yaml). \ No newline at end of file +In addition, we included publishing for [PHPUnit](https://docs.phpunit.de/en/11.4/organizing-tests.html) test runs. While JUnit results format has always been supported, you can now leverage the specific constructs of PHPUnit. For more details on publishing test results, see the documentation [here](/azure/devops/pipelines/tasks/reference/publish-test-results-v2?view=azure-devops&preserve-view=true&tabs=yaml). diff --git a/release-notes/2019/includes/pipelines/sprint-160-update.md b/release-notes/2019/includes/pipelines/sprint-160-update.md index 88c4a4505e3..9f4212bcd05 100644 --- a/release-notes/2019/includes/pipelines/sprint-160-update.md +++ b/release-notes/2019/includes/pipelines/sprint-160-update.md @@ -50,7 +50,7 @@ jobs: strategy: $(strategy.name) percentage: $(strategy.increment) manifests: 'manifest.yml' - postRouteTaffic: + postRouteTraffic: pool: server steps: - script: echo monitor application health... @@ -63,9 +63,8 @@ jobs: - script: echo checks passed, notify... ``` -The canary strategy for Kuberenetes will first deploy the changes with 10% pods followed by 20% while monitoring the health during *postRouteTraffic*. If all goes well, it will promote to 100%. +The canary strategy for Kubernetes will first deploy the changes with 10% pods followed by 20% while monitoring the health during *postRouteTraffic*. If all goes well, it will promote to 100%. -We are looking for early feedback on support for VM resource in environments and performing rolling deployment strategy across multiple machines. [Contact us](mailto:rm_customer_queries@microsoft.com?subject=VMResourcePrivateBeta) to enroll. ### Approval policies for YAML pipelines @@ -284,5 +283,5 @@ jobs: runOnce: pre-deploy: steps: - - reviewApp: MasterNamespace -``` \ No newline at end of file + - reviewApp: MainNamespace +``` diff --git a/release-notes/2019/includes/pipelines/sprint-161-update.md b/release-notes/2019/includes/pipelines/sprint-161-update.md index 9ba38aed4a5..60066385d7d 100644 --- a/release-notes/2019/includes/pipelines/sprint-161-update.md +++ b/release-notes/2019/includes/pipelines/sprint-161-update.md @@ -29,7 +29,7 @@ Azure Repos Git, GitHub, and Bitbucket Cloud repositories are supported. For mor We now have GitHub Actions for [Azure Pipelines (Azure/pipelines)](https://github.com/Azure/pipelines). You can use Azure/pipelines to trigger a run in Azure Pipelines as part of your GitHub Actions workflow. -[GitHub Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/about-github-actions) makes it easy to build, test, and deploy your code right from GitHub. You can also use it to trigger external CI/CD tools and services. For example, you can use GitHub Actions for continuous integration, and [Azure Pipelines](https://azure.microsoft.com/services/devops/pipelines/?nav=min) for continuous delivery to leverage features like Approvals, Environments and deep integration with Kubernetes. +GitHub Actions makes it easy to build, test, and deploy your code right from GitHub. You can also use it to trigger external CI/CD tools and services. For example, you can use GitHub Actions for continuous integration, and [Azure Pipelines](https://azure.microsoft.com/services/devops/pipelines/?nav=min) for continuous delivery to leverage features like Approvals, Environments and deep integration with Kubernetes. You can use this action to trigger a specific pipeline (YAML or classic release pipeline) in Azure DevOps. GitHub Actions will take the Project URL, pipeline name, and a [Personal Access Token (PAT)](/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?tabs=preview-page&view=azure-devops&preserve-view=true) for your Azure DevOps organization as inputs. diff --git a/release-notes/2019/includes/pipelines/sprint-162-update.md b/release-notes/2019/includes/pipelines/sprint-162-update.md index 4aa4b262dd3..e3728d7b314 100644 --- a/release-notes/2019/includes/pipelines/sprint-162-update.md +++ b/release-notes/2019/includes/pipelines/sprint-162-update.md @@ -112,7 +112,7 @@ jobs: routeTraffic: steps: - script: echo routing traffic... - postRouteTaffic: + postRouteTraffic: steps: - script: echo health check post routing traffic... on: diff --git a/release-notes/2019/includes/repos/sprint-150-update.md b/release-notes/2019/includes/repos/sprint-150-update.md index 727166bb05c..8a31158d816 100644 --- a/release-notes/2019/includes/repos/sprint-150-update.md +++ b/release-notes/2019/includes/repos/sprint-150-update.md @@ -22,6 +22,6 @@ The updated policy administration page allows administrators to control which me There are a few situations when rebasing during pull request completion is not possible: * If a policy on the target branch prohibits using rebase strategies, you will need “Override branch policies” permission. * If the source branch of the pull request has policies, you won’t be able to rebase it. Rebasing will modify the source branch without going through the policy approval process. -* If you’ve used the [Merge Conflict Extension](https://nam06.safelinks.protection.outlook.com/?url=https://marketplace.visualstudio.com/items?itemName%3Dms-devlabs.conflicts-tab&data=02%7c01%7cJoe.Bourne%40microsoft.com%7cb19b5f47678043aadffc08d6b126cda9%7c72f988bf86f141af91ab2d7cd011db47%7c1%7c0%7c636891177544782502&sdata=FaoKHy%2BZ5W/YI4rmT7E%2Bn22Kato/wrE18%2B3lWXPq778%3D&reserved=0) to resolve merge conflicts. Conflict resolutions applied to a three-way merge are seldom successful (or even valid) when rebasing all the commits in a pull request one at a time. +* If you’ve used the [Merge Conflict Extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.conflicts-tab) to resolve merge conflicts. Conflict resolutions applied to a three-way merge are seldom successful (or even valid) when rebasing all the commits in a pull request one at a time. In all these cases, you still have the option of rebasing your branch locally and pushing to the server, or squash-merging your changes when completing the pull request. diff --git a/release-notes/2019/includes/repos/sprint-152-update.md b/release-notes/2019/includes/repos/sprint-152-update.md index 178f261bee4..ec2ba4b400f 100644 --- a/release-notes/2019/includes/repos/sprint-152-update.md +++ b/release-notes/2019/includes/repos/sprint-152-update.md @@ -22,8 +22,6 @@ Currently, we publish syntax highlighting for a subset of languages supported by With this update, we added an extensibility point that allows extensions to add syntax highlighting and autocomplete to the file explorer and pull requests views. -You can find an example of an extension demonstrating this feature [here](https://github.com/Microsoft/azure-devops-extension-sample/tree/master/src/Samples/CodeEditorContribution). - In addition, we added support for [Kusto language](/azure/kusto/query/) syntax highlighting. ### Manage git references from the command line diff --git a/release-notes/2019/includes/wiki/sprint-148-update.md b/release-notes/2019/includes/wiki/sprint-148-update.md index a592e1d50b3..fb92502f1bc 100644 --- a/release-notes/2019/includes/wiki/sprint-148-update.md +++ b/release-notes/2019/includes/wiki/sprint-148-update.md @@ -2,7 +2,7 @@ ms.topic: include --- - + ### @mention users and groups diff --git a/release-notes/2019/includes/wiki/sprint-154-update.md b/release-notes/2019/includes/wiki/sprint-154-update.md index 7a0b658490c..d1c2a431011 100644 --- a/release-notes/2019/includes/wiki/sprint-154-update.md +++ b/release-notes/2019/includes/wiki/sprint-154-update.md @@ -20,4 +20,4 @@ To create a work item select the text in the wiki page where you want to embed t > [!div class="mx-imgBorder"] > ![Create and embed work items from wiki content.](../../media/154_07.gif "Create and embed work items from wiki content") -To learn more about creating and embeding a work item from wiki, see our documentation [here](/azure/devops/project/wiki/create-embed-wit-from-wiki?view=azure-devops&preserve-view=true). \ No newline at end of file +To learn more about creating and embedding a work item from wiki, see our documentation [here](/azure/devops/project/wiki/create-embed-wit-from-wiki?view=azure-devops&preserve-view=true). \ No newline at end of file diff --git a/release-notes/2019/media/150_09.png b/release-notes/2019/media/150_09.png index fffb7edb3da..c516fb238ea 100644 Binary files a/release-notes/2019/media/150_09.png and b/release-notes/2019/media/150_09.png differ diff --git a/release-notes/2019/media/150_25.PNG b/release-notes/2019/media/150_25.PNG deleted file mode 100644 index 4c0228a2e45..00000000000 Binary files a/release-notes/2019/media/150_25.PNG and /dev/null differ diff --git a/release-notes/2019/media/153_01.png b/release-notes/2019/media/153_01.png deleted file mode 100644 index 4dc62de32dd..00000000000 Binary files a/release-notes/2019/media/153_01.png and /dev/null differ diff --git a/release-notes/2019/media/154_09.png b/release-notes/2019/media/154_09.png index 52ec777c01a..b46aa93989d 100644 Binary files a/release-notes/2019/media/154_09.png and b/release-notes/2019/media/154_09.png differ diff --git a/release-notes/2019/media/155_27.png b/release-notes/2019/media/155_27.png index 7ca759bb99a..13526b0562c 100644 Binary files a/release-notes/2019/media/155_27.png and b/release-notes/2019/media/155_27.png differ diff --git a/release-notes/2019/media/156_21.png b/release-notes/2019/media/156_21.png deleted file mode 100644 index d8a666cbaa7..00000000000 Binary files a/release-notes/2019/media/156_21.png and /dev/null differ diff --git a/release-notes/2019/media/158_11.png b/release-notes/2019/media/158_11.png index 245cb184853..6b9b4846bb1 100644 Binary files a/release-notes/2019/media/158_11.png and b/release-notes/2019/media/158_11.png differ diff --git a/release-notes/2019/media/160_03.png b/release-notes/2019/media/160_03.png index 962f153a370..bf1491b92d7 100644 Binary files a/release-notes/2019/media/160_03.png and b/release-notes/2019/media/160_03.png differ diff --git a/release-notes/2019/media/162_03.png b/release-notes/2019/media/162_03.png index 962f153a370..8b51a8785ed 100644 Binary files a/release-notes/2019/media/162_03.png and b/release-notes/2019/media/162_03.png differ diff --git a/release-notes/2020/includes/pipelines/sprint-170-update.md b/release-notes/2020/includes/pipelines/sprint-170-update.md index 1604453b948..fad7ddcc9d7 100644 --- a/release-notes/2020/includes/pipelines/sprint-170-update.md +++ b/release-notes/2020/includes/pipelines/sprint-170-update.md @@ -21,7 +21,7 @@ To use scale set agents, you will first create a VM scale set in your Azure subs The Ubuntu 20.04 image is now available in preview for Azure Pipelines hosted pools. To use this image, update your YAML file to include vmImage: 'ubuntu-20.04' . Please note, the ubuntu-latest image label will continue to point to ubuntu-18.04 until ubuntu-20.04 comes out of preview later this year. -Please note, since the ubuntu 20.04 image is in preview, it currently doesn't support all of the tooling available in ubuntu-18.04 . [Learn more](https://github.com/actions/virtual-environments/tree/main/images/linux) +Please note, since the ubuntu 20.04 image is in preview, it currently doesn't support all of the tooling available in ubuntu-18.04 . [Learn more](https://github.com/actions/runner-images/tree/main/images/ubuntu) ### Support for GitHub packages in YAML pipelines @@ -47,4 +47,4 @@ By default, packages are not automatically downloaded in your jobs, hence why we pool: default steps: - getPackage: myPackageAlias # Alias of the package resource -``` \ No newline at end of file +``` diff --git a/release-notes/2020/includes/pipelines/sprint-172-update.md b/release-notes/2020/includes/pipelines/sprint-172-update.md index fd8db1bf7c8..8356fe8b6b8 100644 --- a/release-notes/2020/includes/pipelines/sprint-172-update.md +++ b/release-notes/2020/includes/pipelines/sprint-172-update.md @@ -32,7 +32,7 @@ When the stages provided in the trigger filter are successfully completed in you ### Generic webhook based triggers for YAML pipelines -Today, we have various resources (such as pipelines, containers, build, and packages) through which you can consume artifacts and enable automated triggers. Until now, however, you could not automate your deployment process based on other external events or services. In this release, we are introducing webhook trigger support in YAML pipelines to enable integration of pipeline automation with any external service. You can subscribe to any external events through its webhooks (GitHub, GitHub Enterprise, Nexus, Aritfactory, etc.) and trigger your pipelines. +Today, we have various resources (such as pipelines, containers, build, and packages) through which you can consume artifacts and enable automated triggers. Until now, however, you could not automate your deployment process based on other external events or services. In this release, we are introducing webhook trigger support in YAML pipelines to enable integration of pipeline automation with any external service. You can subscribe to any external events through its webhooks (GitHub, GitHub Enterprise, Nexus, Artifactory, etc.) and trigger your pipelines. Here are the steps to configure the webhook triggers: 1. Setup a webhook on your external service. When creating your webhook, you need to provide the following info: diff --git a/release-notes/2020/includes/pipelines/sprint-177-update.md b/release-notes/2020/includes/pipelines/sprint-177-update.md index 128a2bdef26..9d6716eb491 100644 --- a/release-notes/2020/includes/pipelines/sprint-177-update.md +++ b/release-notes/2020/includes/pipelines/sprint-177-update.md @@ -18,8 +18,6 @@ If you use any of the Node 10-enabled tasks, your self-hosted agents will update When you use scale set agents, Azure Pipelines manages the scaling up and down of agent instances. When Azure Pipelines detects an unhealthy VM in the scale set, it will log the issue to the Pool Diagnostics UI and attempt to delete the VM. There are many reasons why a VM can be unhealthy: the scale set's network configuration may have prevented the Azure Pipelines extension from downloading the latest agent, your custom script extension may have failed, or the scale set VM image may have a pending reboot or pending Windows Updates. -
      check agent -
      By deleting unhealthy VMs, Azure Pipelines keeps your agent pool optimized to run CI/CD jobs. In some cases, you may be able to use the Azure Pipelines diagnostics page (shown above) or the Azure diagnostics page to debug this problem. However, in many cases, the best way to diagnose the problem is to log into the VM and review the agent logs and event viewer logs. At present, this is not easy to do since the unhealthy VM is deleted automatically. With this release, we enhanced the diagnosability of unhealthy VMs by giving you the ability to save an unhealthy agent for investigation. diff --git a/release-notes/2020/includes/repos/sprint-179-update.md b/release-notes/2020/includes/repos/sprint-179-update.md index a9e8158ece6..d98ed7cc16d 100644 --- a/release-notes/2020/includes/repos/sprint-179-update.md +++ b/release-notes/2020/includes/repos/sprint-179-update.md @@ -41,8 +41,6 @@ When resizing the side-by-side diff pane in the PR files tab, the user’s scrol ### Search for a commit on a mobile device When viewing the Commits page on a mobile device, the search box is missing in the new experience. As a result, it is hard for you to find a commit by its hash and open it. This has been fixed now. - -
      Search for a commit on a mobile device ### Improved usage of space for new PR file diff mobile view diff --git a/release-notes/2020/media/165_03.png b/release-notes/2020/media/165_03.png index 8160dfeb9e0..5b1f5252dbf 100644 Binary files a/release-notes/2020/media/165_03.png and b/release-notes/2020/media/165_03.png differ diff --git a/release-notes/2020/media/171-general-0-0.png b/release-notes/2020/media/171-general-0-0.png index 48e6fe564ad..0094731c98e 100644 Binary files a/release-notes/2020/media/171-general-0-0.png and b/release-notes/2020/media/171-general-0-0.png differ diff --git a/release-notes/2020/media/177-boards-3-0.png b/release-notes/2020/media/177-boards-3-0.png deleted file mode 100644 index be7e54bc5c1..00000000000 Binary files a/release-notes/2020/media/177-boards-3-0.png and /dev/null differ diff --git a/release-notes/2020/media/177-pipelines-3-0.png b/release-notes/2020/media/177-pipelines-3-0.png deleted file mode 100644 index 28e7bab0dee..00000000000 Binary files a/release-notes/2020/media/177-pipelines-3-0.png and /dev/null differ diff --git a/release-notes/2020/media/179-repos-0-6.gif b/release-notes/2020/media/179-repos-0-6.gif deleted file mode 100644 index e5f74cf0150..00000000000 Binary files a/release-notes/2020/media/179-repos-0-6.gif and /dev/null differ diff --git a/release-notes/2021/.DS_Store b/release-notes/2021/.DS_Store deleted file mode 100644 index de0a5cd2a55..00000000000 Binary files a/release-notes/2021/.DS_Store and /dev/null differ diff --git a/release-notes/2021/includes/pipelines/sprint-184-update.md b/release-notes/2021/includes/pipelines/sprint-184-update.md index 99dc11159db..ee3830bbea0 100644 --- a/release-notes/2021/includes/pipelines/sprint-184-update.md +++ b/release-notes/2021/includes/pipelines/sprint-184-update.md @@ -12,10 +12,10 @@ Azure Pipelines has been offering free CI/CD to public and private projects for To address this situation, we've added an extra step for new organizations in Azure DevOps to get their free grant. The following changes are effective immediately: * By default, new organizations created in Azure DevOps will no longer get a free grant of concurrent pipelines. This applies to both public as well as private projects in new organizations. -* To request your free grant, send an email to azpipelines-freetier@microsoft.com and provide the following details clearly: +* To request your free grant, [submit a request](https://aka.ms/azpipelines-parallelism-request) and provide the following details clearly: * Your name * Azure DevOps organization for which you are requesting the free grant - * Whether you need the free grant for public projects, private projects, or both + * Whether you need the free grant for public projects or private projects * Links to the repositories that you plan to build (public projects only) * Brief description of your project (public projects only) diff --git a/release-notes/2021/includes/pipelines/sprint-192-update.md b/release-notes/2021/includes/pipelines/sprint-192-update.md index 8a050aee375..9b117c24367 100644 --- a/release-notes/2021/includes/pipelines/sprint-192-update.md +++ b/release-notes/2021/includes/pipelines/sprint-192-update.md @@ -72,7 +72,7 @@ steps: When you reference windows-latest pool in your YAML pipelines, it will still mean windows-2019 and not windows-2022, while the latter is in preview. -The Windows Server 2022 pipeline image has different tools and tool versions when compared to Windows Server 2019. You can see the details in the software [announcement issue](https://github.com/actions/virtual-environments/issues/3949) and in the documentation [virtual-environments repository](https://github.com/actions/virtual-environments/blob/main/images/win/Windows2022-Readme.md). +The Windows Server 2022 pipeline image has different tools and tool versions when compared to Windows Server 2019. You can see the details in the software [announcement issue](https://github.com/actions/virtual-environments/issues/3949) and in the documentation [virtual-environments repository](https://github.com/actions/runner-images/blob/main/images/windows/Windows2022-Readme.md). ### General availability of macOS 11 on Microsoft-hosted agents @@ -83,8 +83,6 @@ pool: vmImage: macos-11 ``` -The macOS 11 pipeline image has different tools and tool, to learn more about this version you can see the full documentation [here](https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11-Readme.md). - ### Removal of Ubuntu 16.04 image on Microsoft-hosted agents As announced [earlier](/azure/devops/release-notes/2021/pipelines/sprint-187-update#ubuntu-1604-will-be-removed-from-microsoft-hosted-pools-in-september-2021), we'll be removing Ubuntu 16.04 image from Microsoft-hosted agents on September 20, 2021. Traditional 5-years support of Ubuntu 16.04 by Canonical ended in April, 2021. You'll need to migrate ubuntu-16.04 pipelines to ubuntu-18.04 or ubuntu-latest which will run on Ubuntu 20.04 LTS. diff --git a/release-notes/2022/includes/boards/sprint-204-update.md b/release-notes/2022/includes/boards/sprint-204-update.md index 6b509260103..379181753f8 100644 --- a/release-notes/2022/includes/boards/sprint-204-update.md +++ b/release-notes/2022/includes/boards/sprint-204-update.md @@ -19,7 +19,7 @@ Previously, the Kanban board **Show more items** feature fetched the next 200 wo ### General availability of Copy Dashboard -Copy Dashboard is now generally available. Copy Dashobard lets you copy a dashboard to the same or a new project. To copy a dashboard: +Copy Dashboard is now generally available. Copy Dashboard lets you copy a dashboard to the same or a new project. To copy a dashboard: 1. Go to the dashboard you want to copy. From there click the menu to bring up **Copy Dashboard** and then click on it. diff --git a/release-notes/2022/includes/pipelines/sprint-198-update.md b/release-notes/2022/includes/pipelines/sprint-198-update.md index 463676fda81..314e5f9e104 100644 --- a/release-notes/2022/includes/pipelines/sprint-198-update.md +++ b/release-notes/2022/includes/pipelines/sprint-198-update.md @@ -11,7 +11,7 @@ The `windows-2022` image is ready to be the default version for the `windows-lat Azure Pipelines has supported `windows-2022` since September 2021. We have monitored your feedback to improve the `windows-2022` image stability and now we are ready to set it as the latest. -The `windows-2022` image includes Visual Studio 2022. For a full list of differences between `windows-2022` and `windows-2019`, visit the [GitHub issue](https://github.com/actions/virtual-environments/issues/4856). For a full list of software installed on the image, check [here](https://github.com/actions/virtual-environments/blob/main/images/win/Windows2022-Readme.md). +The `windows-2022` image includes Visual Studio 2022. For a full list of differences between `windows-2022` and `windows-2019`, visit the [GitHub issue](https://github.com/actions/virtual-environments/issues/4856). For a full list of software installed on the image, check [here](https://github.com/actions/runner-images/blob/main/images/windows/Windows2022-Readme.md). ### Pipeline folder rename validates permissions diff --git a/release-notes/2022/includes/pipelines/sprint-204-update.md b/release-notes/2022/includes/pipelines/sprint-204-update.md index 70b104d76c3..8165fbb7d84 100644 --- a/release-notes/2022/includes/pipelines/sprint-204-update.md +++ b/release-notes/2022/includes/pipelines/sprint-204-update.md @@ -18,7 +18,7 @@ The Ubuntu 22.04 image is now available in preview for Azure Pipelines hosted ag echo Hello from Ubuntu 22.04 Preview lsb_release -d ``` -The ubuntu-latest image label will continue to point to ubuntu-20.04 until ubuntu-22.04 comes out of preview later this year. While the Ubuntu 22.04 image is in preview, it currently doesn't support all of the tooling available in ubuntu-20.04 and you may experience longer queue times than other images. For more information, check the [virtual-environments repository](https://github.com/actions/virtual-environments) and [Ubuntu image configurations](https://github.com/actions/virtual-environments/tree/main/images/linux). +The ubuntu-latest image label will continue to point to ubuntu-20.04 until ubuntu-22.04 comes out of preview later this year. While the Ubuntu 22.04 image is in preview, it currently doesn't support all of the tooling available in ubuntu-20.04 and you may experience longer queue times than other images. For more information, check the [virtual-environments repository](https://github.com/actions/virtual-environments) and [Ubuntu image configurations](https://github.com/actions/runner-images/tree/main/images/ubuntu). ### Preview of macOS 12 Monterey for Azure Pipeline hosted pools diff --git a/release-notes/2022/includes/pipelines/sprint-212-update.md b/release-notes/2022/includes/pipelines/sprint-212-update.md index addfd77b3d6..f0a1b1dda22 100644 --- a/release-notes/2022/includes/pipelines/sprint-212-update.md +++ b/release-notes/2022/includes/pipelines/sprint-212-update.md @@ -139,9 +139,6 @@ You can use `parameters.` and `variables.` in your template expressions. For var When a user is asked to approve a pipeline to deploy to a particular stage, that user can choose to reassign the approval to someone else. -> [!div class="mx-imgBorder"] -> ![Audit Events for Changes to Approvals](../../media/212-pipelines-01.png) - Up until now, such actions were not logged in the Audit logs. This issue is fixed now. The Audit logs will contain an entry similar to the following. @@ -149,7 +146,7 @@ The Audit logs will contain an entry similar to the following. [ { "Id": "2517368925862632546;00000264-0000-8888-8000-000000000000;839ad1ba-f72b-4258-bc3f-88be7a4553b5", - "CorrelationId": "8392d1ba-f76b-4258-bc3f-88be7a4553b5", + "CorrelationId": "aaaa0000-bb11-2222-33cc-444444dddddd", "ActivityId": "a298a06c-965f-4e60-9643-2593f2066e37", "ActorCUID": "fe950802-bf07-755b-826d-e8dcc066252c", "ActorUserId": "fe950802-bf07-755b-826d-e8dcc066252c", @@ -184,9 +181,6 @@ The Audit logs will contain an entry similar to the following. In addition, it will show up in the Audit UI. -> [!div class="mx-imgBorder"] -> ![Log entry in Audit UI](../../media/212-pipelines-02.png) - ### Task library exposes Agent hosting model Task Authors that want to determine whether an agent is running in Microsoft-hosted pools or not can now use Task Library function `getAgentMode()` to determine the hosting model. This is beneficial in scenarios where a task wants to influence behavior based on having access to a customer's network or not. A task may try to reach an Azure service over a private endpoint if it is executed from a self-hosted agent or scale-set agents that reside in a customer's network. diff --git a/release-notes/2022/includes/pipelines/sprint-213-update.md b/release-notes/2022/includes/pipelines/sprint-213-update.md index a362253dfbb..d32b722ed9a 100644 --- a/release-notes/2022/includes/pipelines/sprint-213-update.md +++ b/release-notes/2022/includes/pipelines/sprint-213-update.md @@ -21,9 +21,6 @@ When you restrict pipeline permissions of a protected resource, such as a servic > [!div class="mx-imgBorder"] > ![Pipeline Permissions for Changes to Approvals](../../media/213-pipelines-01.png) -> [!div class="mx-imgBorder"] -> ![Successfully Authorized for Changes to Approvals](../../media/213-pipelines-02.png) - ### Ensure your organization only uses YAML pipelines Azure DevOps now lets you ensure your organization only uses YAML pipelines, by disabling the creation of classic build pipelines, classic release pipelines, task groups, and deployment groups. Your existing classic pipelines will continue to run, and you'll be able to edit them, but you won't be able to create new ones. @@ -78,10 +75,10 @@ To prevent PRs from forked GitHub repositories from making undesired changes to The macos-12 Monterey image is ready to be the default version for the “macos-latest" label in Azure Pipelines Microsoft-hosted agents. Until now, this label pointed to macos-11 Big Sur agents. -For a full list of differences between macos-12 and macos-11, visit the [GitHub issue](https://github.com/actions/runner-images/issues/6384). For a full list of software installed on the image, check [here](https://github.com/actions/runner-images/blob/main/images/macos/macos-12-Readme.md). +For a full list of differences between macos-12 and macos-11, visit the [GitHub issue](https://github.com/actions/runner-images/issues/6384). For a full list of software installed on the image, check [here](https://github.com/actions/runner-images/blob/main/images/macos/). ### Ubuntu-latest label will point to ubuntu-22.04 image The ubuntu-22.04 image is ready to be the default version for the **ubuntu-latest** label in Azure Pipelines Microsoft-hosted agents. Until now, this label pointed to ubuntu-20.04 agents. -For a full list of differences between ubuntu-22.04 and ubuntu-20.04, visit the [GitHub issue](https://github.com/actions/runner-images/issues/6399). For a full list of software installed on the image, check [here](https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md). +For a full list of differences between ubuntu-22.04 and ubuntu-20.04, visit the [GitHub issue](https://github.com/actions/runner-images/issues/6399). For a full list of software installed on the image, check [here](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md). diff --git a/release-notes/2022/media/202-general-01.png b/release-notes/2022/media/202-general-01.png index 0385b0ebf1d..083c7c3687f 100644 Binary files a/release-notes/2022/media/202-general-01.png and b/release-notes/2022/media/202-general-01.png differ diff --git a/release-notes/2022/media/212-pipelines-01.png b/release-notes/2022/media/212-pipelines-01.png deleted file mode 100644 index 66219917f57..00000000000 Binary files a/release-notes/2022/media/212-pipelines-01.png and /dev/null differ diff --git a/release-notes/2022/media/212-pipelines-02.png b/release-notes/2022/media/212-pipelines-02.png deleted file mode 100644 index 0f66a74ec72..00000000000 Binary files a/release-notes/2022/media/212-pipelines-02.png and /dev/null differ diff --git a/release-notes/2022/media/213-pipelines-02.png b/release-notes/2022/media/213-pipelines-02.png deleted file mode 100644 index 1f0c71b26dd..00000000000 Binary files a/release-notes/2022/media/213-pipelines-02.png and /dev/null differ diff --git a/release-notes/2023/artifacts/sprint-226-update.md b/release-notes/2023/artifacts/sprint-226-update.md new file mode 100644 index 00000000000..3d4343bdf45 --- /dev/null +++ b/release-notes/2023/artifacts/sprint-226-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Artifacts Sprint 226 Update +description: See the Sprint 226 feature updates for Azure Artifacts, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 8/23/2023 +--- + +# Azure Artifacts - Sprint 226 Update + +## Features + +[!INCLUDE [sprint-226-update-links](../includes/artifacts/sprint-226-update-links.md)] + +[!INCLUDE [sprint-226-update](../includes/artifacts/sprint-226-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/artifacts/sprint-229-update.md b/release-notes/2023/artifacts/sprint-229-update.md new file mode 100644 index 00000000000..a5ece8b5e28 --- /dev/null +++ b/release-notes/2023/artifacts/sprint-229-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Artifacts Sprint 229 update +description: See the Sprint 229 feature updates for Azure Artifacts, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +--- + +# Azure Artifacts - Sprint 229 Update + +## Features + +[!INCLUDE [sprint-229-update-links](../includes/artifacts/sprint-229-update-links.md)] + +[!INCLUDE [sprint-229-update](../includes/artifacts/sprint-229-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/boards/sprint-224-update.md b/release-notes/2023/boards/sprint-224-update.md new file mode 100644 index 00000000000..36148f74600 --- /dev/null +++ b/release-notes/2023/boards/sprint-224-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 224 Update +description: See the Sprint 224 feature updates for Azure Boards, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +--- + +# Azure Boards - Sprint 224 Update + +## Features + +[!INCLUDE [sprint-224-update-links](../includes/boards/sprint-224-update-links.md)] + +[!INCLUDE [sprint-224-update](../includes/boards/sprint-224-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/boards/sprint-225-update.md b/release-notes/2023/boards/sprint-225-update.md new file mode 100644 index 00000000000..53fa6d3768d --- /dev/null +++ b/release-notes/2023/boards/sprint-225-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 225 Update +description: See the Sprint 225 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 8/2/2023 +--- + +# Azure Boards - Sprint 225 Update + +## Features + +[!INCLUDE [sprint-225-update-links](../includes/boards/sprint-225-update-links.md)] + +[!INCLUDE [sprint-225-update](../includes/boards/sprint-225-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/boards/sprint-227-update.md b/release-notes/2023/boards/sprint-227-update.md new file mode 100644 index 00000000000..829fbed2efa --- /dev/null +++ b/release-notes/2023/boards/sprint-227-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 227 Update +description: See the Sprint 227 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/14/2023 +--- + +# Azure Boards - Sprint 227 Update + +## Features + +[!INCLUDE [sprint-227-update-links](../includes/boards/sprint-227-update-links.md)] + +[!INCLUDE [sprint-227-update](../includes/boards/sprint-227-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/boards/sprint-228-update.md b/release-notes/2023/boards/sprint-228-update.md new file mode 100644 index 00000000000..046fab71ce9 --- /dev/null +++ b/release-notes/2023/boards/sprint-228-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 228 Update +description: See the Sprint 228 feature updates for Azure Boards, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +--- + +# Azure Boards - Sprint 228 Update + +## Features + +[!INCLUDE [sprint-228-update-links](../includes/boards/sprint-228-update-links.md)] + +[!INCLUDE [sprint-228-update](../includes/boards/sprint-228-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/boards/sprint-230-update.md b/release-notes/2023/boards/sprint-230-update.md new file mode 100644 index 00000000000..0ec50e6614f --- /dev/null +++ b/release-notes/2023/boards/sprint-230-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 230 Update +description: See the Sprint 230 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +--- + +# Azure Boards - Sprint 230 Update + +## Features + +[!INCLUDE [sprint-230-update-links](../includes/boards/sprint-230-update-links.md)] + +[!INCLUDE [sprint-230-update](../includes/boards/sprint-230-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/boards/sprint-231-update.md b/release-notes/2023/boards/sprint-231-update.md new file mode 100644 index 00000000000..52c8c901d80 --- /dev/null +++ b/release-notes/2023/boards/sprint-231-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 231 Update +description: See the Sprint 231 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 12/5/2023 +--- + +# Azure Boards - Sprint 231 Update + +## Features + +[!INCLUDE [sprint-231-update-links](../includes/boards/sprint-231-update-links.md)] + +[!INCLUDE [sprint-231-update](../includes/boards/sprint-231-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/general/sprint-224-update.md b/release-notes/2023/general/sprint-224-update.md new file mode 100644 index 00000000000..9b36b7ab277 --- /dev/null +++ b/release-notes/2023/general/sprint-224-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure DevOps Sprint 224 Update +description: See the Sprint 224 feature updates for Azure DevOps, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +--- + +# Azure DevOps - Sprint 224 Update + +## Features + +[!INCLUDE [sprint-224-update-links](../includes/general/sprint-224-update-links.md)] + +[!INCLUDE [sprint-224-update](../includes/general/sprint-224-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/general/sprint-226-update.md b/release-notes/2023/general/sprint-226-update.md new file mode 100644 index 00000000000..54f9a68f0bb --- /dev/null +++ b/release-notes/2023/general/sprint-226-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure DevOps Sprint 226 Update +description: See the Sprint 226 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 8/23/2023 +--- + +# Azure DevOps - Sprint 226 Update + +## Features + +[!INCLUDE [sprint-226-update-links](../includes/general/sprint-226-update-links.md)] + +[!INCLUDE [sprint-226-update](../includes/general/sprint-226-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/general/sprint-228-update.md b/release-notes/2023/general/sprint-228-update.md new file mode 100644 index 00000000000..cb1f4093a80 --- /dev/null +++ b/release-notes/2023/general/sprint-228-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure DevOps Sprint 228 Update +description: See the Sprint 228 feature updates for Azure DevOps, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +--- + +# Azure DevOps - Sprint 228 Update + +## Features + +[!INCLUDE [sprint-228-update-links](../includes/general/sprint-228-update-links.md)] + +[!INCLUDE [sprint-228-update](../includes/general/sprint-228-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/general/sprint-229-update.md b/release-notes/2023/general/sprint-229-update.md new file mode 100644 index 00000000000..89ccfde168a --- /dev/null +++ b/release-notes/2023/general/sprint-229-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 229 update +description: See the Sprint 229 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +--- + +# Azure DevOps - Sprint 229 Update + +## Features + +[!INCLUDE [sprint-229-update-links](../includes/general/sprint-229-update-links.md)] + +[!INCLUDE [sprint-229-update](../includes/general/sprint-229-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/general/sprint-230-update.md b/release-notes/2023/general/sprint-230-update.md new file mode 100644 index 00000000000..8315d0df534 --- /dev/null +++ b/release-notes/2023/general/sprint-230-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 230 update +description: See the Sprint 230 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +--- + +# Azure DevOps - Sprint 230 Update + +## Features + +[!INCLUDE [sprint-230-update-links](../includes/general/sprint-230-update-links.md)] + +[!INCLUDE [sprint-230-update](../includes/general/sprint-230-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/ghazdo/sprint-222-update.md b/release-notes/2023/ghazdo/sprint-222-update.md new file mode 100644 index 00000000000..1b2d14c949e --- /dev/null +++ b/release-notes/2023/ghazdo/sprint-222-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - GitHub Advanced Security for Azure DevOps Sprint 222 Update +description: See the Sprint 222 feature updates for Azure DevOps, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 6/6/2023 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 222 Update + +## Features + +[!INCLUDE [sprint-222-update-links](../includes/ghazdo/sprint-222-update-links.md)] + +[!INCLUDE [sprint-222-update](../includes/ghazdo/sprint-222-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/ghazdo/sprint-224-update.md b/release-notes/2023/ghazdo/sprint-224-update.md new file mode 100644 index 00000000000..3debf0b2d5e --- /dev/null +++ b/release-notes/2023/ghazdo/sprint-224-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - GitHub Advanced Security for Azure DevOps Sprint 224 Update +description: See the Sprint 224 feature updates for Azure DevOps, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 224 Update + +## Features + +[!INCLUDE [sprint-224-update-links](../includes/ghazdo/sprint-224-update-links.md)] + +[!INCLUDE [sprint-224-update](../includes/ghazdo/sprint-224-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/ghazdo/sprint-228-update.md b/release-notes/2023/ghazdo/sprint-228-update.md new file mode 100644 index 00000000000..94f363e2c5b --- /dev/null +++ b/release-notes/2023/ghazdo/sprint-228-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - GitHub Advanced Security for Azure DevOps Sprint 228 Update +description: See the Sprint 228 feature updates for Azure DevOps, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 228 Update + +## Features + +[!INCLUDE [sprint-228-update-links](../includes/ghazdo/sprint-228-update-links.md)] + +[!INCLUDE [sprint-228-update](../includes/ghazdo/sprint-228-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/ghazdo/sprint-229-update.md b/release-notes/2023/ghazdo/sprint-229-update.md new file mode 100644 index 00000000000..c8a9e080a22 --- /dev/null +++ b/release-notes/2023/ghazdo/sprint-229-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps Sprint 229 update +description: See the Sprint 229 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 229 Update + +## Features + +[!INCLUDE [sprint-229-update-links](../includes/ghazdo/sprint-229-update-links.md)] + +[!INCLUDE [sprint-229-update](../includes/ghazdo/sprint-229-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/includes/artifacts/sprint-226-update-links.md b/release-notes/2023/includes/artifacts/sprint-226-update-links.md new file mode 100644 index 00000000000..df251908cdd --- /dev/null +++ b/release-notes/2023/includes/artifacts/sprint-226-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/22/2023 +ms.topic: include +--- + +- [Introducing Azure Artifacts support for Cargo Crates (public preview) ](#introducing-azure-artifacts-support-for-cargo-crates-public-preview) diff --git a/release-notes/2023/includes/artifacts/sprint-226-update.md b/release-notes/2023/includes/artifacts/sprint-226-update.md new file mode 100644 index 00000000000..92deb047790 --- /dev/null +++ b/release-notes/2023/includes/artifacts/sprint-226-update.md @@ -0,0 +1,13 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/23/2023 +ms.topic: include +--- + +### Introducing Azure Artifacts support for Cargo Crates (public preview) + +We're excited to announce that Azure Artifacts now offer native support for Cargo crates. +This support includes feature parity with respect to our existing protocols, in addition to crates.io being available as an upstream source. Rust developers and teams can now consume, publish, manage, and share their Cargo crates seamlessly, all while using Azure's robust infrastructure and staying in the familiar Azure DevOps environment. + +No sign-up is needed for the preview; you can get started by navigating to your Azure DevOps project, selecting Artifacts, and following the instructions to connect your Rust project to your Azure Artifacts feed. \ No newline at end of file diff --git a/release-notes/2023/includes/artifacts/sprint-229-update-links.md b/release-notes/2023/includes/artifacts/sprint-229-update-links.md new file mode 100644 index 00000000000..9b3a7d0f243 --- /dev/null +++ b/release-notes/2023/includes/artifacts/sprint-229-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +ms.topic: include +--- + +- [Deprecation announcement for NuGet Restore v1 and NuGet Installer v0 pipeline tasks ](#deprecation-announcement-for-nuget-restore-v1-and-nuget-installer-v0-pipeline-tasks) diff --git a/release-notes/2023/includes/artifacts/sprint-229-update.md b/release-notes/2023/includes/artifacts/sprint-229-update.md new file mode 100644 index 00000000000..b8ee2ae2398 --- /dev/null +++ b/release-notes/2023/includes/artifacts/sprint-229-update.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +ms.topic: include +--- + +### Deprecation announcement for NuGet Restore v1 and NuGet Installer v0 pipeline tasks + +If you're using the NuGet Restore v1 and NuGet Installer v0 pipeline tasks, promptly transition to the [NuGetCommand@2](/azure/devops/pipelines/tasks/reference/nuget-command-v2) pipeline task. You'll begin receiving alerts in your pipelines soon if the transition hasn't been made. If no action is taken, starting November 27, 2023, your builds will result in failure. For more information, see [Migrate from NuGetInstaller@0 or NuGetRestore@1](/azure/devops/pipelines/tasks/reference/nuget-command-v2#migrate-from-nugetinstaller0-or-nugetrestore1). \ No newline at end of file diff --git a/release-notes/2023/includes/boards/sprint-219-update.md b/release-notes/2023/includes/boards/sprint-219-update.md index 428224e062d..8e9e8989335 100644 --- a/release-notes/2023/includes/boards/sprint-219-update.md +++ b/release-notes/2023/includes/boards/sprint-219-update.md @@ -21,7 +21,7 @@ We will provide all the documentation and code samples to help you on-board into ### Swimlane rules (private preview) > [!IMPORTANT] -> Due to heavy volumne, we have stopped taking new requests into the priviate preview. We expect to release this feature into GA in the next couple of sprints. +> Due to heavy volume, we have stopped taking new requests into the private preview. We expect to release this feature into GA in the next couple of sprints. Swimlane rules are similar to style rules, but instead, they allow you to setup conditions on your Kanban board to automatically move work items into specific lanes. For example, you might want to setup a lane for each person on your team. When you assign the work item, it will be placed into that lane. diff --git a/release-notes/2023/includes/boards/sprint-224-update-links.md b/release-notes/2023/includes/boards/sprint-224-update-links.md new file mode 100644 index 00000000000..ee5bef02286 --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-224-update-links.md @@ -0,0 +1,8 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +ms.topic: include +--- + +- [Copy link to work item](#copy-link-to-work-item) \ No newline at end of file diff --git a/release-notes/2023/includes/boards/sprint-224-update.md b/release-notes/2023/includes/boards/sprint-224-update.md new file mode 100644 index 00000000000..74629d2fe96 --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-224-update.md @@ -0,0 +1,18 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +ms.topic: include +--- + +### Copy link to work item + +We made a small improvement to copy the work item url from several areas in Azure Boards. Making it easier to get the direct link to a specific work item. + +> [!div class="mx-imgBorder"] +> ![Image for copy link context menu item on backlog](../../media/224-boards-01.png "image to show copy link context menu on backlog") + +**Copy link** has been added to the context menus on the work item form, backlog, and task backlog. + +> [!NOTE] +> This feature will only be available with the [**New Boards Hubs** preview](https://devblogs.microsoft.com/devops/new-boards-hub-public-preview/). \ No newline at end of file diff --git a/release-notes/2023/includes/boards/sprint-225-update-links.md b/release-notes/2023/includes/boards/sprint-225-update-links.md new file mode 100644 index 00000000000..60d23015a5d --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-225-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/2/2023 +ms.topic: include +--- + +- [New Boards Hub on by default](#new-boards-hub-on-by-default) \ No newline at end of file diff --git a/release-notes/2023/includes/boards/sprint-225-update.md b/release-notes/2023/includes/boards/sprint-225-update.md new file mode 100644 index 00000000000..a8d37a8adef --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-225-update.md @@ -0,0 +1,17 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/2/2023 +ms.topic: include +--- + +### New Boards Hub on by default + +In March 2022, we announced the preview of the New Boards Hub. Since then, we have been collecting feedback, [adding features](../../../features-timeline.md#all-features), and fixing bugs. + + Now, after a long journey, we are ready to take the next step by making New Boards Hub the default experience. The rollout process will take a couple of months as we carefully deploy it to all organizations. You will see the following banner when you open Boards for the first time after your organization has been updated. + +> [!div class="mx-imgBorder"] +> ![Animation to demo New banner when you open Boards.](../../media/225-boards-01.gif "Animation to demo New banner when you open Boards") + +For more information about New Boards Hub and the rollout, please see this [blog post](https://devblogs.microsoft.com/devops/new-boards-hub-path-to-ga/) on the topic. diff --git a/release-notes/2023/includes/boards/sprint-227-update-links.md b/release-notes/2023/includes/boards/sprint-227-update-links.md new file mode 100644 index 00000000000..16f855fb70d --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-227-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/14/2023 +ms.topic: include +--- + +- [Limits for area and iteration paths](#limits-for-area-and-iteration-paths) \ No newline at end of file diff --git a/release-notes/2023/includes/boards/sprint-227-update.md b/release-notes/2023/includes/boards/sprint-227-update.md new file mode 100644 index 00000000000..6c0779010fd --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-227-update.md @@ -0,0 +1,15 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/14/2023 +ms.topic: include +--- + +### Limits for area and iteration paths + +Limits play an important part in maintaining the health and efficiency of a large, global service. In this sprint, we are introducing hard limits of 10,000 per project for both area and iteration paths. Visit the [Work tracking, process, and project limits](/azure/devops/organizations/settings/work/object-limits?view=azure-devops&preserve-view=true) page to learn more about different limits in the service. + +> [!div class="mx-imgBorder"] +> ![Screenshots of Area and Iteration Paths.](../../media/227-boards-01.png "Screenshots of Area and Iteration Paths.") + + diff --git a/release-notes/2023/includes/boards/sprint-228-update-links.md b/release-notes/2023/includes/boards/sprint-228-update-links.md new file mode 100644 index 00000000000..d003e78171d --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-228-update-links.md @@ -0,0 +1,8 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +ms.topic: include +--- + +- [Team Automation Rules (private preview)](#team-automation-rules-private-preview) \ No newline at end of file diff --git a/release-notes/2023/includes/boards/sprint-228-update.md b/release-notes/2023/includes/boards/sprint-228-update.md new file mode 100644 index 00000000000..a828ca59962 --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-228-update.md @@ -0,0 +1,35 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +ms.topic: include +--- + +### Team Automation Rules (private preview) + +> [!IMPORTANT] +> As of 11/9/2023, we are not taking any new organizations into the private preview. We have had great feedback with just a couple of minor bugs to resolve. We are working on those bugs and will be releasing the feature to everyone in the next few sprints. + +You can now configure each backlog level to automate the opening and closing/resolving of work items based on the state(s) of their children. There are two main scenarios we are attempting to solve. + +1. When a single child item is activated, then activate the parent. + +2. When all child items are closed, then close the parent (or resolve it). + +To enable these settings, you click on the backlog level configuration for your team. Then go to the *Automation > Rules* tab to see the two different rules you can apply to your backlog. Each backlog level (requirements, features, epics) can be configured for how your team wants to work. + +> [!div class="mx-imgBorder"] +> ![Screenshots of Team Settings.](../../media/228-boards-01.png "Screenshots of Team Settings.") + + +For example, when any child Task is set to Active, make the parent User Story active. Then, when all Tasks are completed, set the User Story to Closed. + +> [!div class="mx-imgBorder"] +> ![Gif to demo Team automation rules.](../../media/228-boards-01.gif "gif to demo Team automation rules") + +If you are interested in enrolling in the private preview, please [send us an email](mailto:dahellem@microsoft.com) with your organization name (dev.azure.com/{organization name}). Please understand that we will be limiting the number of organizations into the preview. Our hope is to get a few organizations to provide feedback and then release to everyone within 2-3 sprints. + +The features was prioritized based on [this Developer Community suggestion ticket](https://developercommunity.visualstudio.com/t/update-automatically-user-story-state-according-to/376465). + +> [!NOTE] +> This feature will only be available with the [**New Boards Hubs** preview](https://devblogs.microsoft.com/devops/new-boards-hub-public-preview/). \ No newline at end of file diff --git a/release-notes/2023/includes/boards/sprint-230-update-links.md b/release-notes/2023/includes/boards/sprint-230-update-links.md new file mode 100644 index 00000000000..d13ee394c12 --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-230-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +ms.topic: include +--- + +- [GitHub Integration - Improved AB# validation (private preview)](#github-integration---improved-ab-validation-private-preview) \ No newline at end of file diff --git a/release-notes/2023/includes/boards/sprint-230-update.md b/release-notes/2023/includes/boards/sprint-230-update.md new file mode 100644 index 00000000000..3966374802e --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-230-update.md @@ -0,0 +1,22 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +ms.topic: include +--- + +### GitHub Integration - Improved AB# validation (private preview) + +> [!IMPORTANT] +> As of 8/6/2024, the Azure Boards App in GitHub will no longer validate AB# links. You can still use the `AB#` syntax to link work items in your GitHub pull requests, commits, and issues as you could prior to this change. + +We're starting our journey of Boards + GitHub integration improvements by addressing the bot responses when linking to work items using the AB# syntax. When you link to a Pull Request using the ``AB#{ID}`` syntax, the only way to know if the link was successful is by looking at the work item or noticing the ``AB#{ID}`` turn into a link. + +Today, we're launching a private preview featuring several enhancements to the Azure Boards GitHub app to better inform you when a link to a work item is valid or invalid. This helps identify bad links and fix them before the Pull Request is merged. + +> [!div class="mx-imgBorder"] +> ![Screenshots of Team Settings.](../../media/230-boards-01.png "Screenshots of Team Settings.") + +If you're interested in participating in the private preview, reach out to us directly [via email](mailto:dahellem@microsoft.com). Be sure to include your organization name (dev.azure.com/{organization}) + +Check out the public roadmap to learn more about upcoming [Azure Boards + GitHub integration features](/azure/devops/release-notes/features-timeline#improved-boards--github-integration). \ No newline at end of file diff --git a/release-notes/2023/includes/boards/sprint-231-update-links.md b/release-notes/2023/includes/boards/sprint-231-update-links.md new file mode 100644 index 00000000000..0fe94748b71 --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-231-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 12/5/2023 +ms.topic: include +--- + +- [Switch between HTML or Markdown on comments](#switch-between-html-or-markdown-on-comments) \ No newline at end of file diff --git a/release-notes/2023/includes/boards/sprint-231-update.md b/release-notes/2023/includes/boards/sprint-231-update.md new file mode 100644 index 00000000000..93e1c22b776 --- /dev/null +++ b/release-notes/2023/includes/boards/sprint-231-update.md @@ -0,0 +1,26 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 12/5/2023 +ms.topic: include +--- + +### Switch between HTML or Markdown on comments + +A few months ago, we [introduced a private preview](/azure/devops/release-notes/2023/sprint-222-update#azure-boards-1) to enable Markdown for comments on work items, aiming to replace the existing HTML editor entirely. We've received your feedback, expressing a preference for the HTML editor and we adjusted our approach. You now have the flexibility to switch between the HTML and Markdown editor at the comment level. + + + +> [!div class="mx-imgBorder"] +> ![Gif to demo switch between the HTML and markdown editor.](../../media/231-boards-01.gif "gif to demo work switch between the html and Markdown editor") + +Here's what you should expect: + +* The default editor is sticky from the last comment you created. +* You can convert existing HTML comments to Markdown. +* Once a Markdown comment is created or updated, it can't be converted to HTML. + +This update is implemented across all pre-enrolled organizations and those with the New Boards Hub enabled by default. Additionally, we're extending the preview period for a few more weeks to gather more feedback. If you're interested in enrolling in the private preview, feel free to reach out directly [via email](mailto:dahellem@microsoft.com), and kindly include your organization name (dev.azure.com/{organization}). + +> [!TIP] +> Consider enrolling in the preview only if your organization is fully committed to utilizing the [New Boards Hub](/azure/devops/release-notes/2022/sprint-202-update) for all users. The experience with Markdown comments in the Old Boards may not be optimal. diff --git a/release-notes/2023/includes/general/sprint-219-update-links.md b/release-notes/2023/includes/general/sprint-219-update-links.md index 91538a60f33..7df1fd735d3 100644 --- a/release-notes/2023/includes/general/sprint-219-update-links.md +++ b/release-notes/2023/includes/general/sprint-219-update-links.md @@ -5,4 +5,4 @@ ms.date: 3/31/2023 ms.topic: include --- -- [Service principal and managed identity support in Azure DevOps](#service-principal-and-managed-identity-support-in-azure-devops) +- [Service principal and managed identity support in Azure DevOps (public preview)](#service-principal-and-managed-identity-support-in-azure-devops-public-preview) diff --git a/release-notes/2023/includes/general/sprint-219-update.md b/release-notes/2023/includes/general/sprint-219-update.md index f6f26dbf278..986eeca8b01 100644 --- a/release-notes/2023/includes/general/sprint-219-update.md +++ b/release-notes/2023/includes/general/sprint-219-update.md @@ -5,7 +5,7 @@ ms.date: 3/31/2023 ms.topic: include --- -### Service principal and managed identity support in Azure DevOps +### Service principal and managed identity support in Azure DevOps (public preview) You can now add Azure Active Directory (Azure AD) service principals and managed identities, to your Azure DevOps organizations to grant access to your organization’s resources. For many teams, this feature can be a viable alternative to personal access tokens (PATs) when safely authenticating applications that power automation tooling. diff --git a/release-notes/2023/includes/general/sprint-222-update-links.md b/release-notes/2023/includes/general/sprint-222-update-links.md index a0a7a6f29a9..58162e4f190 100644 --- a/release-notes/2023/includes/general/sprint-222-update-links.md +++ b/release-notes/2023/includes/general/sprint-222-update-links.md @@ -5,5 +5,4 @@ ms.date: 6/6/2023 ms.topic: include --- -- [GitHub Advanced Security for Azure DevOps (public preview)](#github-advanced-security-for-azure-devops-public-preview) - [Resolved issue that allowed users to bypass restrict global personal access token (PAT) creation](#resolved-issue-that-allowed-users-to-bypass-restrict-global-personal-access-token-pat-creation) diff --git a/release-notes/2023/includes/general/sprint-222-update.md b/release-notes/2023/includes/general/sprint-222-update.md index 890f55af095..b262280150f 100644 --- a/release-notes/2023/includes/general/sprint-222-update.md +++ b/release-notes/2023/includes/general/sprint-222-update.md @@ -5,14 +5,10 @@ ms.date: 6/6/2023 ms.topic: include --- -### GitHub Advanced Security for Azure DevOps (public preview) - -GitHub Advanced Security for Azure DevOps is now in public preview! Through Advanced Security, secret scanning, dependency scanning, and code scanning abilities are integrated directly into Azure DevOps. To sign up for the public preview, visit [https://aka.ms/advancedsecurity-signup](https://aka.ms/advancedsecurity-signup). You can learn more about Advanced Security features at [https://aka.ms/advanced-security](https://aka.ms/advanced-security). - ### Resolved issue that allowed users to bypass restrict global personal access token (PAT) creation -Resolved an issue that allowed users to bypass the ["Restrict global personal access token creation" organization policy](/azure/devops/organizations/accounts/manage-pats-with-policies-for-administrators?view=azure-devops#restrict-creation-of-global-pats) by using the Visual Studio client. +Resolved an issue that allowed users to bypass the ["Restrict global personal access token creation" organization policy](/azure/devops/organizations/accounts/manage-pats-with-policies-for-administrators#restrict-creation-of-global-pats) by using the Visual Studio client. -Any global PATs, i.e. PATs that can access multiple organizations, that have been created using this API will remain active after this gap has been closed. If you are a tenant admin (an Azure DevOps Administrator in Azure AD), you can deactivate these PATs using the [Token Administration APIs](https://learn.microsoft.com/rest/api/azure/devops/tokenadmin/?view=azure-devops-rest-7.0). +Any global PATs, i.e. PATs that can access multiple organizations, that have been created using this API will remain active after this gap has been closed. If you are a tenant admin (an Azure DevOps Administrator in Azure AD), you can deactivate these PATs using the Token Administration APIs. -To ensure that you can continue creating global PATs, make sure to reach out to your tenant admin that manages organization policies to add you to the allow list for this policy. If you are not on the allow list moving forward, you will not be able to continue creating global PATs. \ No newline at end of file +To ensure that you can continue creating global PATs, make sure to reach out to your tenant admin that manages organization policies to add you to the allow list for this policy. If you are not on the allow list moving forward, you will not be able to continue creating global PATs. diff --git a/release-notes/2023/includes/general/sprint-223-update.md b/release-notes/2023/includes/general/sprint-223-update.md index e2b7d8bf13e..9a44f4af1ca 100644 --- a/release-notes/2023/includes/general/sprint-223-update.md +++ b/release-notes/2023/includes/general/sprint-223-update.md @@ -9,4 +9,4 @@ ms.topic: include We’re excited to announce that you can change the profile image for your organization and replace the automatically generated image based on your organization name. This has been a top requested feature in the [developer community](https://developercommunity.visualstudio.com/t/Can-Not-update-Organization-Settings-Ove/1329561) and one which gives large customers more control over how their organizations are represented within their company. -Check out our [documentation](/azure/devops/organizations/accounts/change-organization-image?view=azure-devops) to learn how to change your organization profile image. +Check out our [documentation](/azure/devops/organizations/accounts/change-organization-image) to learn how to change your organization profile image. diff --git a/release-notes/2023/includes/general/sprint-224-update-links.md b/release-notes/2023/includes/general/sprint-224-update-links.md new file mode 100644 index 00000000000..9971b4dccc2 --- /dev/null +++ b/release-notes/2023/includes/general/sprint-224-update-links.md @@ -0,0 +1,8 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 8/9/2023 +ms.topic: include +--- + +- [Alert dismissals for dependency scanning alerts in Advanced Security](#alert-dismissals-for-dependency-scanning-alerts-in-advanced-security) \ No newline at end of file diff --git a/release-notes/2023/includes/general/sprint-224-update.md b/release-notes/2023/includes/general/sprint-224-update.md new file mode 100644 index 00000000000..4907abadfed --- /dev/null +++ b/release-notes/2023/includes/general/sprint-224-update.md @@ -0,0 +1,18 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 8/9/2023 +ms.topic: include +--- + + +### Alert dismissals for dependency scanning alerts in Advanced Security + +You can now dismiss any dependency scanning alerts you believe to be a false positive or acceptable risk. These are the same dismissal options for secret scanning and code scanning alerts in Advanced Security that you can currently use. + +> [!div class="mx-imgBorder"] +> ![Dismiss a dependency scanning alert](../../media/224-general-01.png "image showing how to dismiss a dependency scanning alert") + +Note that you may need to re-run detection pipeline with the dependency scanning task as well as ensure you have the `Advanced Security: dismiss alerts` permissions in order to dismiss these alerts. + +To learn more about alert dismissals, see [Dismiss dependency scanning alerts](/azure/devops/repos/security/github-advanced-security-dependency-scanning#dismiss-dependency-scanning-alerts). \ No newline at end of file diff --git a/release-notes/2023/includes/general/sprint-226-update-links.md b/release-notes/2023/includes/general/sprint-226-update-links.md new file mode 100644 index 00000000000..b89a17be955 --- /dev/null +++ b/release-notes/2023/includes/general/sprint-226-update-links.md @@ -0,0 +1,11 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/23/2023 +ms.topic: include +--- + +- [Project and organization-level enablement for Advanced Security ](#project-and-organization-level-enablement-for-advanced-security ) + +- [Estimated committer count during Advanced Security enablement ](#estimated-committer-count-during-advanced-security-enablement ) + diff --git a/release-notes/2023/includes/general/sprint-226-update.md b/release-notes/2023/includes/general/sprint-226-update.md new file mode 100644 index 00000000000..d89c9e2291f --- /dev/null +++ b/release-notes/2023/includes/general/sprint-226-update.md @@ -0,0 +1,28 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/23/2023 +ms.topic: include +--- + + +### Project and organization-level enablement for Advanced Security + +You can now enable or disable **Advanced Security** for your entire project or organization. In conjunction with the new addition of displaying committer count prior to enablement, selecting **"Enable all"** at the project or organization-level will provide you with an estimate of how many new active committers you may be billed for. You can also opt to automatically enable **Advanced Security** for any newly created repositories or projects under your respective project or organization. Any repositories enabled through this setting will have secret repository scanning and push protection active. + +**Project-level enablement:** + +> [!div class="mx-imgBorder"] +> ![Screenshot of Project-level enablement.](../../media/226-general-02.png "Screenshot of Project-level enablement") + +**Organization-level enablement:** + +> [!div class="mx-imgBorder"] +> ![Screenshot of Organization-level enablement.](../../media/226-general-03.png "Screenshot of Organization-level enablement") + +### Estimated committer count during Advanced Security enablement + +As a part of your **Advanced Security** onboarding experience, you can now see an estimate of how many active committers may have been added as a result of enabling **Advanced Security** for a particular repository, project, or organization. This count is an approximation and you may see slight discrepancies between the provided estimate and what is reported for billing after enablement. This estimate can also be obtained via API with additional documentation explaining this process coming soon. + +> [!div class="mx-imgBorder"] +> ![Screenshot of Advanced Security enablement.](../../media/226-general-01.png "Screenshot of Advanced Security enablement") diff --git a/release-notes/2023/includes/general/sprint-228-update-links.md b/release-notes/2023/includes/general/sprint-228-update-links.md new file mode 100644 index 00000000000..e413b06678e --- /dev/null +++ b/release-notes/2023/includes/general/sprint-228-update-links.md @@ -0,0 +1,9 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +ms.topic: include +--- + +- [Managed identity and service principal support for Azure DevOps now in general availability (GA)](#managed-identity-and-service-principal-support-for-azure-devops-now-in-general-availability-ga) +- [New Azure DevOps scopes available for Microsoft Identity OAuth delegated flow apps](#new-azure-devops-scopes-available-for-microsoft-identity-oauth-delegated-flow-apps) \ No newline at end of file diff --git a/release-notes/2023/includes/general/sprint-228-update.md b/release-notes/2023/includes/general/sprint-228-update.md new file mode 100644 index 00000000000..18d235e66ac --- /dev/null +++ b/release-notes/2023/includes/general/sprint-228-update.md @@ -0,0 +1,26 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +ms.topic: include +--- + + +### Managed identity and service principal support for Azure DevOps now in general availability (GA) + +Support for Microsoft Entra ID managed identities and service principals in Azure DevOps has now reached general availability (GA). + +Today, many application integration scenarios rely on Personal Access Tokens (PATs) to integrate with Azure DevOps. While simple to use, PATs can easily be leaked, potentially enabling malicious actors to authenticate as powerful users. To prevent unwanted access, PATs often also require time-consuming maintenance through regular credential rotations. + +You can now enable applications to instead use Managed Identities and Service Principals to integrate with Azure DevOps through REST APIs and client libraries. This highly requested feature offers Azure DevOps customers a more secure alternative to PATs. Managed Identities offer the ability for applications running on Azure resources to obtain Azure AD tokens without needing to manage any credentials at all. + +Managed Identities and Service Principals can be setup in Azure DevOps and given permissions to specific assets (projects, repos, pipelines), just like regular users. This allows applications that use Managed Identities or Service Principals to connect to Azure DevOps and perform actions on behalf of themselves, instead of on behalf of a user, as PAT do. Teams can now better manage their services collectively, instead of relying on any one individual to provide a token for authentication. Learn more about the GA release in our public [blog post announcement](https://devblogs.microsoft.com/devops/?p=67669) and our [feature documentation](/azure/devops/integrate/get-started/authentication/service-principal-managed-identity). + +### New Azure DevOps scopes available for Microsoft Identity OAuth delegated flow apps + +We have added new [Azure DevOps scopes](/azure/devops/integrate/get-started/authentication/oauth#scopes) for delegated OAuth apps on the Microsoft Identity platform, also colloquially known as [Microsoft Entra ID OAuth apps](/azure/devops/integrate/get-started/authentication/oauth#azure-ad-oauth). These new scopes will enable app developers to announce specifically which permissions they are hoping to request from the user in order to perform app duties. This highly requested feature allows app developers to request from their users solely the permissions they need for their app. + +Previously, user_impersonation was the only scope available for app developers to choose from. This scope gives the app full access to all Azure DevOps APIs, which means it will be able to do anything that the user is able to do across all organizations that the user belongs to. +Now with more granular scopes available, you can rest easy that apps can only request and access solely those APIs that the requested scopes have granted them permission to access. + +Learn more about these new scopes in our [public blog post announcement](https://devblogs.microsoft.com/devops/?p=67699) and [feature documentation](/azure/devops/integrate/get-started/authentication/oauth). \ No newline at end of file diff --git a/release-notes/2023/includes/general/sprint-229-update-links.md b/release-notes/2023/includes/general/sprint-229-update-links.md new file mode 100644 index 00000000000..aacfa487ca2 --- /dev/null +++ b/release-notes/2023/includes/general/sprint-229-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +ms.topic: include +--- + +- [Publish Test Results Task](#publish-test-results-task) \ No newline at end of file diff --git a/release-notes/2023/includes/general/sprint-229-update.md b/release-notes/2023/includes/general/sprint-229-update.md new file mode 100644 index 00000000000..54a97e59955 --- /dev/null +++ b/release-notes/2023/includes/general/sprint-229-update.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +ms.topic: include +--- + +### Publish Test Results task + +The Publish Test Results task now supports test run attachments for the JUnit report format. diff --git a/release-notes/2023/includes/general/sprint-230-update-links.md b/release-notes/2023/includes/general/sprint-230-update-links.md new file mode 100644 index 00000000000..2e62f6e4e9c --- /dev/null +++ b/release-notes/2023/includes/general/sprint-230-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +ms.topic: include +--- + +- [New version of the Azure DevOps Web Extension SDK ](#new-version-of-the-azure-devops-web-extension-sdk) \ No newline at end of file diff --git a/release-notes/2023/includes/general/sprint-230-update.md b/release-notes/2023/includes/general/sprint-230-update.md new file mode 100644 index 00000000000..7f6ce5297bd --- /dev/null +++ b/release-notes/2023/includes/general/sprint-230-update.md @@ -0,0 +1,40 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +ms.topic: include +--- + + +### New version of the Azure DevOps Web Extension SDK + +With this update we are releasing a new version of the Azure DevOps Web Extension SDK. The client SDK enables web extensions to communicate to the host frame. It can be used to: +* Notify the host that the extension is loaded or has errors +* Get basic contextual information about the current page (current user, host and extension information) +* Get theme information +* Obtain an authorization token to use in REST calls back to Azure DevOps +* Get remote services offered by the host frame + +You can find a full API reference in the [azure-devops-extension-sdk package documentation](/javascript/api/azure-devops-extension-sdk/). +This new version provides support for the following modules: +- **ES Module Support:** + SDK now supports ES (ECMAScript) modules in addition to the existing AMD (Asynchronous Module Definition) modules. You can now import SDK using the ES module syntax, which provides performance improvements and reduces the application size. + +- **Backward Compatibility for AMD Modules:** Existing support for AMD modules remains intact. If your project is using AMD modules, you can continue to use them as before without any changes. + +**How to use:** + +For ES modules, you can import our modules using the import statement: + +``` +import * as SDK from 'azure-devops-extension-sdk'; +// Use the module here +``` + +If you're using AMD modules, you can continue to import SDK using the `require` function: +``` +require(['azure-devops-extension-sdk'], function(SDK) { + + // Use the module here +}); +``` diff --git a/release-notes/2023/includes/ghazdo/sprint-222-update-links.md b/release-notes/2023/includes/ghazdo/sprint-222-update-links.md new file mode 100644 index 00000000000..1bfd1a21bbb --- /dev/null +++ b/release-notes/2023/includes/ghazdo/sprint-222-update-links.md @@ -0,0 +1,8 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 6/6/2023 +ms.topic: include +--- + +- [GitHub Advanced Security for Azure DevOps (public preview)](#github-advanced-security-for-azure-devops-public-preview) \ No newline at end of file diff --git a/release-notes/2023/includes/ghazdo/sprint-222-update.md b/release-notes/2023/includes/ghazdo/sprint-222-update.md new file mode 100644 index 00000000000..6aa2c96c5d1 --- /dev/null +++ b/release-notes/2023/includes/ghazdo/sprint-222-update.md @@ -0,0 +1,10 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 6/6/2023 +ms.topic: include +--- + +### GitHub Advanced Security for Azure DevOps (public preview) + +GitHub Advanced Security for Azure DevOps is now in public preview! Through Advanced Security, secret scanning, dependency scanning, and code scanning abilities are integrated directly into Azure DevOps. You can learn more about Advanced Security features at [https://aka.ms/advanced-security](https://aka.ms/advanced-security). \ No newline at end of file diff --git a/release-notes/2023/includes/ghazdo/sprint-224-update-links.md b/release-notes/2023/includes/ghazdo/sprint-224-update-links.md new file mode 100644 index 00000000000..9971b4dccc2 --- /dev/null +++ b/release-notes/2023/includes/ghazdo/sprint-224-update-links.md @@ -0,0 +1,8 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 8/9/2023 +ms.topic: include +--- + +- [Alert dismissals for dependency scanning alerts in Advanced Security](#alert-dismissals-for-dependency-scanning-alerts-in-advanced-security) \ No newline at end of file diff --git a/release-notes/2023/includes/ghazdo/sprint-224-update.md b/release-notes/2023/includes/ghazdo/sprint-224-update.md new file mode 100644 index 00000000000..4907abadfed --- /dev/null +++ b/release-notes/2023/includes/ghazdo/sprint-224-update.md @@ -0,0 +1,18 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 8/9/2023 +ms.topic: include +--- + + +### Alert dismissals for dependency scanning alerts in Advanced Security + +You can now dismiss any dependency scanning alerts you believe to be a false positive or acceptable risk. These are the same dismissal options for secret scanning and code scanning alerts in Advanced Security that you can currently use. + +> [!div class="mx-imgBorder"] +> ![Dismiss a dependency scanning alert](../../media/224-general-01.png "image showing how to dismiss a dependency scanning alert") + +Note that you may need to re-run detection pipeline with the dependency scanning task as well as ensure you have the `Advanced Security: dismiss alerts` permissions in order to dismiss these alerts. + +To learn more about alert dismissals, see [Dismiss dependency scanning alerts](/azure/devops/repos/security/github-advanced-security-dependency-scanning#dismiss-dependency-scanning-alerts). \ No newline at end of file diff --git a/release-notes/2023/includes/ghazdo/sprint-228-update-links.md b/release-notes/2023/includes/ghazdo/sprint-228-update-links.md new file mode 100644 index 00000000000..37ea1b32ca2 --- /dev/null +++ b/release-notes/2023/includes/ghazdo/sprint-228-update-links.md @@ -0,0 +1,10 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +ms.topic: include +--- + +- [Changes to Code Scanning (CodeQL) user input task and variables](#changes-to-code-scanning-codeql-user-input-task-and-variables) +- [Publish task is no longer required for Setting up code Scanning](#publish-task-is-no-longer-required-for-setting-up-code-scanning) +- [CodeQL code scanning now supports Swift](#codeql-code-scanning-now-supports-swift) \ No newline at end of file diff --git a/release-notes/2023/includes/ghazdo/sprint-228-update.md b/release-notes/2023/includes/ghazdo/sprint-228-update.md new file mode 100644 index 00000000000..06760ac8565 --- /dev/null +++ b/release-notes/2023/includes/ghazdo/sprint-228-update.md @@ -0,0 +1,33 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +ms.topic: include +--- + +### Changes to Code Scanning (CodeQL) user input task and variables + +All user-provided inputs are now specified in the CodeQL Initialize task, which is responsible for configuring the CodeQL analysis environment used for code analysis with CodeQL `AdvancedSecurity-Codeql-Init@1``. See the [configure GitHub Advanced Security for Azure DevOps features documentation](/azure/devops/repos/security/configure-github-advanced-security-features?view=azure-devops&tabs=yaml) for more information on configuring GitHub Advanced Security for Azure DevOps. + +In addition, user inputs take precedence over any values set by variables. For instance, if you establish the language variable as `advancedsecurity.codeql.language: Java` and subsequently, during the CodeQL initialization phase, you specify the language as an input with `Language: cpp,` the input `cpp` will override the variable `Java` for the language. Please ensure that your inputs are configured accurately. + +### Publish task is no longer required for Setting up code Scanning + +Previously, when configuring code scanning, you were required to include the publish task (AdvancedSecurity-Publish@1) in either the YAML pipeline or classic pipeline. With this update, we've eliminated the need for the publish task, and the results are now directly posted to the advanced security service within the analyze task (AdvancedSecurity-Codeql-Analyze@1). + +Below are the require task for code scanning. + +> [!div class="mx-imgBorder"] +> ![Screenshot of required code scanning tasks.](../../media/228-general-01.png "Screenshot of required code scanning tasks") + + +For more information, please refer to the set up code scanning [documentation](/azure/devops/repos/security/configure-github-advanced-security-features?view=azure-devops&tabs=yaml#set-up-code-scanning). + +### CodeQL code scanning now supports Swift + +We're expanding our support for CodeQL code scanning to include Swift! This means that developers working on Swift libraries and applications for Apple platforms can now take advantage of our top-notch code security analysis. Our current capabilities include the detection of issues such as path injection, risky web view fetches, various cryptographic misuses, and other forms of unsafe handling or processing of unfiltered user data. + +Swift is now part of our roster of supported programming languages, which includes C/C++, Java/Kotlin, JavaScript/TypeScript, Python, Ruby, C#, and Go. Altogether, these languages enable us to perform nearly 400 comprehensive checks on your code, all while maintaining a low rate of false positives and ensuring high precision. + +See the [configure GitHub Advanced Security for Azure DevOps features documentation](/azure/devops/repos/security/configure-github-advanced-security-features?view=azure-devops&tabs=yaml) for more information on configuring GitHub Advanced Security for Azure DevOps for your repositories. + diff --git a/release-notes/2023/includes/ghazdo/sprint-229-update-links.md b/release-notes/2023/includes/ghazdo/sprint-229-update-links.md new file mode 100644 index 00000000000..31a965de4fe --- /dev/null +++ b/release-notes/2023/includes/ghazdo/sprint-229-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +ms.topic: include +--- + +- [REST API documentation now available for Advanced Security ](#rest-api-documentation-now-available-for-advanced-security ) \ No newline at end of file diff --git a/release-notes/2023/includes/ghazdo/sprint-229-update.md b/release-notes/2023/includes/ghazdo/sprint-229-update.md new file mode 100644 index 00000000000..54f32c2c290 --- /dev/null +++ b/release-notes/2023/includes/ghazdo/sprint-229-update.md @@ -0,0 +1,14 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +ms.topic: include +--- + + +### REST API documentation now available for Advanced Security + +Documentation for the Advanced Security REST APIs is now available through the [Azure DevOps Services REST API Reference](/azure/devops/?view=azure-devops-rest-7.2&preserve-view=true) under the Advanced Security section. There are a range of APIs available for use, from security alert finding details, enablement and meter usage estimates. + +> [!div class="mx-imgBorder"] +> ![Screenshot of advanced security section.](../../media/229-general-01.png "Screenshot of advanced security section") \ No newline at end of file diff --git a/release-notes/2023/includes/pipelines/sprint-215-update.md b/release-notes/2023/includes/pipelines/sprint-215-update.md index acf05302307..0140cf00408 100644 --- a/release-notes/2023/includes/pipelines/sprint-215-update.md +++ b/release-notes/2023/includes/pipelines/sprint-215-update.md @@ -6,18 +6,18 @@ ms.topic: include --- ### New PAT Scope for managing pipeline authorization and approvals and checks -To limit damage done by leaking a PAT token, we've added a new PAT scope, named `Pipeline Resources`. You can use this PAT scope when managing pipeline authorization using a [protected resource](https://learn.microsoft.com/azure/devops/pipelines/security/resources?view=azure-devops#protected-resources), such as a service connection, or to manage [approvals and checks](https://learn.microsoft.com/azure/devops/pipelines/process/approvals) for that resource. +To limit damage done by leaking a PAT token, we've added a new PAT scope, named `Pipeline Resources`. You can use this PAT scope when managing pipeline authorization using a [protected resource](/azure/devops/pipelines/security/resources#protected-resources), such as a service connection, or to manage [approvals and checks](/azure/devops/pipelines/process/approvals) for that resource. > [!div class="mx-imgBorder"] > ![Pipelines REST API Updates](../../media/215-pipelines-01.png) The following REST API calls support the new PAT scope as follows: -* [Update an Approval](https://learn.microsoft.com/rest/api/azure/devops/approvalsandchecks/approvals/update) supports scope `Pipeline Resources Use` -* [Manage Checks](https://learn.microsoft.com/rest/api/azure/devops/approvalsandchecks/check-configurations) supports scope `Pipeline Resources Use and Manage` -* [Update Pipeline Permissions For Resources](https://learn.microsoft.com/rest/api/azure/devops/approvalsandchecks/pipeline-permissions/update-pipeline-permisions-for-resources) supports scope `Pipeline Resources Use and Manage` -* [Authorize Definition Resources](https://learn.microsoft.com/rest/api/azure/devops/build/resources/authorize-definition-resources) supports scope `Pipeline Resources Use and Manage` -* [Authorize Project Resources](https://learn.microsoft.com/rest/api/azure/devops/build/authorizedresources/authorize-project-resources) supports scope `Pipeline Resources Use and Manage` +* [Update an Approval](/rest/api/azure/devops/approvalsandchecks/approvals/update) supports scope `Pipeline Resources Use` +* [Manage Checks](/rest/api/azure/devops/approvalsandchecks/check-configurations) supports scope `Pipeline Resources Use and Manage` +* [Update Pipeline Permissions For Resources](/rest/api/azure/devops/approvalsandchecks/pipeline-permissions/update-pipeline-permisions-for-resources) supports scope `Pipeline Resources Use and Manage` +* [Authorize Definition Resources](/rest/api/azure/devops/build/resources/authorize-definition-resources) supports scope `Pipeline Resources Use and Manage` +* [Authorize Project Resources](/rest/api/azure/devops/build/authorizedresources/authorize-project-resources) supports scope `Pipeline Resources Use and Manage` ### Experience improvements to pipeline permissions @@ -26,9 +26,9 @@ We've improved the experience around managing pipeline permissions to make the p In the past, if you checked off "Grant access permission to all pipelines" when you created a protected resource, but then you restricted access to the resource, your pipeline needed a new authorization to use the resource. This behavior was inconsistent with subsequent opening and closing access to the resource, where a new authorization wasn't required. This is now fixed. ### Variables as inputs in checks -[Approvals and checks](https://learn.microsoft.com/azure/devops/pipelines/process/approvals) are a runtime security mechanism that allows resource owners to control which pipeline _runs_ can use their resource. +[Approvals and checks](/azure/devops/pipelines/process/approvals) are a runtime security mechanism that allows resource owners to control which pipeline _runs_ can use their resource. -Two popular checks are _Invoke Azure Function_ and _Invoke REST API_. In the past, when configuring them, one could only use [predefined system variables](https://learn.microsoft.com/azure/devops/pipelines/build/variables) or [variable groups](https://learn.microsoft.com/azure/devops/pipelines/library/variable-groups). +Two popular checks are _Invoke Azure Function_ and _Invoke REST API_. In the past, when configuring them, one could only use [predefined system variables](/azure/devops/pipelines/build/variables) or [variable groups](/azure/devops/pipelines/library/variable-groups). In this sprint, we've added support for pipeline-defined variables. This works when specifying `Function key`, `Headers`, `Body`, and `Query` parameters for such checks. @@ -65,7 +65,7 @@ You can configure an Invoke Azure Function check on the Production environment a The syntax for using runtime-defined variables is `StageId.JobId.StepOrTaskName.Variable`. -Learn more about [the recommended way to use Invoke Azure Function & REST API checks](https://learn.microsoft.com/azure/devops/pipelines/process/invoke-checks). +Learn more about [the recommended way to use Invoke Azure Function & REST API checks](/azure/devops/pipelines/process/invoke-checks). ### Ability to disable masking for short secrets Azure Pipelines masks secrets in logs. Secrets can be variables marked as secret, variables from variable groups that are linked to Azure Key Vault or elements of a Service Connection marked as secret by the Service Connection provider. diff --git a/release-notes/2023/includes/pipelines/sprint-218-update.md b/release-notes/2023/includes/pipelines/sprint-218-update.md index 50e953ff0b0..3eeb2baf85b 100644 --- a/release-notes/2023/includes/pipelines/sprint-218-update.md +++ b/release-notes/2023/includes/pipelines/sprint-218-update.md @@ -36,7 +36,7 @@ Starting now, you can configure service hooks that fire when the state of a job ```json { - "subscriptionId": "8d91ad83-1db5-4d43-8c5a-9bb2239644b1", + "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e", "notificationId": 29, "id": "fcad4962-f3a6-4fbf-9653-2058c304503f", "eventType": "ms.vss-pipelines.job-state-changed-event", diff --git a/release-notes/2023/includes/pipelines/sprint-221-update-links.md b/release-notes/2023/includes/pipelines/sprint-221-update-links.md index e1c9503153e..14ce5ed9336 100644 --- a/release-notes/2023/includes/pipelines/sprint-221-update-links.md +++ b/release-notes/2023/includes/pipelines/sprint-221-update-links.md @@ -5,5 +5,4 @@ ms.date: 5/9/2023 ms.topic: include --- -- [Pipeline agents can be registered using a Service Principal](#pipeline-agents-can-be-registered-using-a-service-principal) - [Pipeline settings audit improvements](#pipeline-settings-audit-improvements) diff --git a/release-notes/2023/includes/pipelines/sprint-221-update.md b/release-notes/2023/includes/pipelines/sprint-221-update.md index cc1360399e1..f8053581f26 100644 --- a/release-notes/2023/includes/pipelines/sprint-221-update.md +++ b/release-notes/2023/includes/pipelines/sprint-221-update.md @@ -5,14 +5,6 @@ ms.date: 5/9/2023 ms.topic: include --- -### Pipeline agents can be registered using a Service Principal - -As Azure DevOps Service Principals support in preview, we have added the capability to use a Service Principal to register a Pipelines agent with Azure DevOps Service: -``` - --auth 'SP' --client-id 12345678-1234-1234-abcd-1234567890ab --client-secret --tenant-id 12345678-1234-1234-abcd-1234567890ab -``` -This removes the need to use a Personal Access Token (PAT) - ### Pipeline settings audit improvements To further increase the security of Azure Pipelines, we've added support for auditing changes to Pipelines settings at the organization-level. We've added a new type of audit log event with `"ActionId": "Pipelines.OrganizationSettings"`. For example, toggling off *Limit variables that can be set at queue time* will generate an audit event with `"ActionId": "Pipelines.OrganizationSettings"` and `"Details": "Pipelines setting "EnforcesettableVar" changed from "True" to "False" at organization level."` diff --git a/release-notes/2023/includes/pipelines/sprint-222-update-links.md b/release-notes/2023/includes/pipelines/sprint-222-update-links.md index 6401209a400..8f01daa8136 100644 --- a/release-notes/2023/includes/pipelines/sprint-222-update-links.md +++ b/release-notes/2023/includes/pipelines/sprint-222-update-links.md @@ -8,4 +8,3 @@ ms.topic: include - [Improvements to YAML pipeline traceability](#improvements-to-yaml-pipeline-traceability) - [Automatic tokens created for Kubernetes Service Connection](#automatic-tokens-created-for-kubernetes-service-connection) - [Preview of macOS 13 Ventura for Azure Pipeline hosted pools](#preview-of-macos-13-ventura-for-azure-pipeline-hosted-pools) -- [Pipeline agents can be registered using a Service Principal](#pipeline-agents-can-be-registered-using-a-service-principal) \ No newline at end of file diff --git a/release-notes/2023/includes/pipelines/sprint-222-update.md b/release-notes/2023/includes/pipelines/sprint-222-update.md index 6e6f10e98c8..fe699dfef92 100644 --- a/release-notes/2023/includes/pipelines/sprint-222-update.md +++ b/release-notes/2023/includes/pipelines/sprint-222-update.md @@ -36,10 +36,3 @@ Please note, the macos-latest image label will continue to point to macos-12 unt For more information, check the [runner-images repository](https://github.com/actions/runner-images/issues/6426) and [macOS image configurations](https://github.com/actions/runner-images/tree/main/images/macos). -## Pipeline agents can be registered using a Service Principal - -With Azure DevOps Service Service Principals support is in [preview](https://devblogs.microsoft.com/devops/introducing-service-principal-and-managed-identity-support-on-azure-devops/), we are adding the capability to use a Service Principal to register a Pipelines agent with Azure DevOps Service: -``` ---auth 'SP' --clientid 12345678-1234-1234-abcd-1234567890ab --clientsecret --tenantid 12345678-1234-1234-abcd-1234567890ab -``` -You can grant the Service Principal access on the security settings of an agent pool. This removes the need to use a Personal Access Token (PAT). diff --git a/release-notes/2023/includes/pipelines/sprint-223-update.md b/release-notes/2023/includes/pipelines/sprint-223-update.md index 070c0507d0c..eb643603d05 100644 --- a/release-notes/2023/includes/pipelines/sprint-223-update.md +++ b/release-notes/2023/includes/pipelines/sprint-223-update.md @@ -9,7 +9,7 @@ ms.topic: include We are making reading checks logs easier. Checks logs provide information critical for your deployment's success. They can tell you if you forgot to close a work item ticket, or that you need to update a ticket in ServiceNow. Previously, knowing that a check provided such critical information was hard. -Now, the pipeline run details page shows the latest check log. This is _only_ for checks that follow our [recommended usage](https://learn.microsoft.com/azure/devops/pipelines/process/invoke-checks). +Now, the pipeline run details page shows the latest check log. This is _only_ for checks that follow our [recommended usage](/azure/devops/pipelines/process/invoke-checks). > [!div class="mx-imgBorder"] > ![Image showing latest check log.](../../media/223-pipelines-01.png "showing latest check log") @@ -22,29 +22,29 @@ To prevent mistakenly approved _Approvals_, Azure DevOps shows the _Instructions ### Scalable Invoke Azure Function and REST API checks changes -[Approvals and Checks](https://learn.microsoft.com/azure/devops/pipelines/process/approvals) allow you to control if a pipeline run is allowed to access a resource. This is a runtime check that provides increased security to your YAML pipelines. +[Approvals and Checks](/azure/devops/pipelines/process/approvals) allow you to control if a pipeline run is allowed to access a resource. This is a runtime check that provides increased security to your YAML pipelines. We noticed that when an organization makes extensive use of the Invoke Azure Function & REST API checks, they do not scale. That is, a modest increase in the number of running checks leads to abnormally large delays in checks execution time, negatively impacting deployment experience. -Our solution to scale Invoke Azure Function and REST API checks is to enforce checks' functionality to match [recommended usage](https://learn.microsoft.com/azure/devops/pipelines/process/invoke-checks). If you followed our guidelines, your checks are compliant and need no further changes. +Our solution to scale Invoke Azure Function and REST API checks is to enforce checks' functionality to match [recommended usage](/azure/devops/pipelines/process/invoke-checks). If you followed our guidelines, your checks are compliant and need no further changes. [Read more about the upcoming changes](https://devblogs.microsoft.com/devops/updates-to-approvals-and-checks/). ### Instructions for manual pre-installation of Node 6 on Pipeline agents -If you use the [`pipeline-` agent feed](https://github.com/microsoft/azure-pipelines-agent/blob/master/docs/node6.md), you do not have Node 6 included in the agent. In some cases, where a Marketplace task is still dependent on Node 6 and the agent is not able to use the [NodeTaskRunnerInstaller task](https://learn.microsoft.com/azure/devops/release-notes/2023/pipelines/sprint-218-update#node-runner-download-task) (e.g. due to connectivity restrictions), you will need to pre-install Node 6 independently. To accomplish this, check out the [instructions](https://github.com/microsoft/azure-pipelines-agent/blob/master/docs/noderunner.md) on how install Node 6 runner manually. +If you use the [`pipeline-` agent feed](https://github.com/microsoft/azure-pipelines-agent/blob/master/docs/node6.md), you do not have Node 6 included in the agent. In some cases, where a Marketplace task is still dependent on Node 6 and the agent is not able to use the [NodeTaskRunnerInstaller task](/azure/devops/release-notes/2023/pipelines/sprint-218-update#node-runner-download-task) (e.g. due to connectivity restrictions), you will need to pre-install Node 6 independently. To accomplish this, check out the [instructions](https://github.com/microsoft/azure-pipelines-agent/blob/master/docs/noderunner.md) on how install Node 6 runner manually. ### Pipeline task changelog -We now publish changes to Pipeline tasks to this [changelog](https://github.com/microsoft/azure-pipelines-tasks/releases). This contains the complete list of changes made to [built-in Pipeline tasks](https://learn.microsoft.com/azure/devops/pipelines/tasks/reference/?view=azure-pipelines). We have retroactively published prior changes, so the changelog provides a historical record of task updates. +We now publish changes to Pipeline tasks to this [changelog](https://github.com/microsoft/azure-pipelines-tasks/releases). This contains the complete list of changes made to [built-in Pipeline tasks](/azure/devops/pipelines/tasks/reference/). We have retroactively published prior changes, so the changelog provides a historical record of task updates. ### Release tasks use Microsoft Graph API -We have updated our [release tasks](https://learn.microsoft.com/azure/devops/pipelines/tasks/reference/?view=azure-pipelines#deploy-tasks) to use the Microsoft Graph API. This removes the usage of the [AAD Graph API](https://techcommunity.microsoft.com/t5/microsoft-entra-azure-ad-blog/azure-ad-change-management-simplified/ba-p/2967456) from our tasks. +We have updated our [release tasks](/azure/devops/pipelines/tasks/reference/#deploy-tasks) to use the Microsoft Graph API. This removes the usage of the [AAD Graph API](https://techcommunity.microsoft.com/t5/microsoft-entra-azure-ad-blog/azure-ad-change-management-simplified/ba-p/2967456) from our tasks. ### Specify agent version in Agent VM extension -Azure VM's can be included in Deployment Groups using a [VM Extension](https://learn.microsoft.com/azure/devops/pipelines/release/deployment-groups/howto-provision-deployment-group-agents?view=azure-devops#install-the-azure-pipelines-agent-azure-vm-extension-using-an-arm-template). The VM extension has been updated to optionally specify the desired agent version to be installed: +Azure VM's can be included in Deployment Groups using a [VM Extension](/azure/devops/pipelines/release/deployment-groups/howto-provision-deployment-group-agents#install-the-azure-pipelines-agent-azure-vm-extension-using-an-arm-template). The VM extension has been updated to optionally specify the desired agent version to be installed: ``` "properties": { ... diff --git a/release-notes/2023/includes/pipelines/sprint-224-update-links.md b/release-notes/2023/includes/pipelines/sprint-224-update-links.md new file mode 100644 index 00000000000..ba47edcd02c --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-224-update-links.md @@ -0,0 +1,13 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +ms.topic: include +--- + +- [Kubernetes tasks now support kubelogin](#kubernetes-tasks-now-support-kubelogin) +- [Updates to YAML cron schedules](#updates-to-yaml-cron-schedules) +- [Disable a check](#disable-a-check) +- [Improvements to Approvals REST API](#improvements-to-approvals-rest-api) +- [New toggles to control creation of classic pipelines](#new-toggles-to-control-creation-of-classic-pipelines) + diff --git a/release-notes/2023/includes/pipelines/sprint-224-update.md b/release-notes/2023/includes/pipelines/sprint-224-update.md new file mode 100644 index 00000000000..e1724cbdd0b --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-224-update.md @@ -0,0 +1,118 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +ms.topic: include +--- + +### Kubernetes tasks now support kubelogin + +We have updated the [KubernetesManifest@1](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v1), [HelmDeploy@0](/azure/devops/pipelines/tasks/reference/helm-deploy-v0), [Kubernetes@1](/azure/devops/pipelines/tasks/reference/kubernetes-v1) and [AzureFunctionOnKubernetes@1](/azure/devops/pipelines/tasks/reference/azure-function-on-kubernetes-v1) tasks to support [kubelogin](/azure/aks/managed-azure-ad#non-interactive-sign-in-with-kubelogin). This allows you to target Azure Kubernetes Service (AKS) configured with [Azure Active Directory integration](/azure/aks/managed-azure-ad). + +Kubelogin isn't pre-installed on [Hosted images](/azure/devops/pipelines/agents/hosted). To make sure above mentioned tasks use kubelogin, install it by inserting the [KubeloginInstaller@0](/azure/devops/pipelines/tasks/reference/kubelogin-installer-v0) task before the task that depends on it: + +```yaml + - task: KubeloginInstaller@0 + + - task: HelmDeploy@0 + # arguments do not need to be modified to use kubelogin + +``` + +### Improvements to Approvals REST API + +[Approvals](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass&preserve-view=true#approvals) increase your YAML pipeline's security by giving you the possibility to manually review a deployment to production. We updated the [Approvals Query REST API](/rest/api/azure/devops/approvalsandchecks/approvals/query) to make it more powerful. Now, you: +- Don't need to specify a list of `approvalId`s. All parameters are now optional. +- Can specify a list of `userId`s to retrieve the list of approvals pending on these users. Currently, the REST API returns the list of approvals for which the users are explicitly assigned as approvers. +- Can specify the `state` of the approvals to be returned, for example, `pending`. + +Here's an example: +`GET https://dev.azure.com/fabrikamfiber/fabrikam-chat/_apis/pipelines/approvals?api-version=7.1-preview.1&userId=00aa00aa-bb11-cc22-dd33-44ee44ee44ee&state=pending` returns +```json +{ + "count": 2, + "value": + [ + { + "id": "87436c03-69a3-42c7-b5c2-6abfe049ee4c", + "steps": [], + "status": "pending", + "createdOn": "2023-06-27T13:58:07.417Z", + "lastModifiedOn": "2023-06-27T13:58:07.4164237Z", + "executionOrder": "anyOrder", + "minRequiredApprovers": 1, + "blockedApprovers": [], + "_links": + { + "self": + { + "href": "https://dev.azure.com/fabrikamfiber/fabricam-chat/_apis/pipelines/approvals/87436c03-69a3-42c7-b5c2-6abfe049ee4c" + } + } + }, + { + "id": "2549baca-104c-4a6f-b05f-bdc4065a53b7", + "steps": [], + "status": "pending", + "createdOn": "2023-06-27T13:58:07.417Z", + "lastModifiedOn": "2023-06-27T13:58:07.4164237Z", + "executionOrder": "anyOrder", + "minRequiredApprovers": 1, + "blockedApprovers": [], + "_links": + { + "self": + { + "href": "https://dev.azure.com/fabrikamfiber/fabricam-chat/_apis/pipelines/approvals/2549baca-104c-4a6f-b05f-bdc4065a53b7" + } + } + } + ] +} +``` + +### Disable a check + +We made debugging checks less tedious. Sometimes, an Invoke Azure Function or Invoke REST API check doesn't work correctly, and you need to fix it. Previously, you had to delete such checks, to prevent them from erroneously blocking a deployment. Once you fixed the check, you had to add it back and configure it correctly, making sure all the required headers are set or the query parameters are correct. This is tedious. + +Now, you can just disable a check. The disabled check won't run in subsequent check suite evaluations. + +> [!div class="mx-imgBorder"] +> ![Disable a check image.](../../media/224-pipelines-01.png "image showing how to disable a check for a pipeline") + +Once you fix the erroneous check, you can just enable it. + +> [!div class="mx-imgBorder"] +> ![Enable a check image.](../../media/224-pipelines-02.png "image showing how to enable a check for a pipeline") + +### Updates to YAML cron schedules + +In YAML pipelines, you can define [scheduled triggers](/azure/devops/pipelines/process/scheduled-triggers?view=azure-devops&preserve-view=true&tabs=yaml#scheduled-triggers) using the `cron` YAML property. + +We updated how the `batch` property works. In a nutshell, if you set `batch` to `true`, the cron schedule will _not_ run if another scheduled pipeline run is in progress. This is regardless of the version of the pipeline repository. + +The following table describes how `always` and `batch` interact. + +|Always|Batch| Behavior| +|-|-|-| +| `false` | `false` | Pipeline runs only if there's a change with respect to the last successful scheduled pipeline run| +| `false` | `true` | Pipeline runs only if there's a change with respect to the last successful scheduled pipeline run *and* there's no in-progress scheduled pipeline run| +| `true`| `false` | Pipeline runs according to the cron schedule| +| `true`| `true` | Pipeline runs according to the cron schedule| + +For example, assume `always: false` and `batch: true`. Assume there's a cron schedule that specifies the pipeline should run every 5 minutes. Imagine there's a new commit. Within 5 minutes, the pipeline starts its scheduled run. Imagine a pipeline run takes 30 minutes to complete. Within these 30 minutes, no scheduled run takes place, regardless of the number of commits. The next scheduled run happens only _after_ the current scheduled run finishes. + +Your YAML pipeline may contain multiple cron schedules, and you may want your pipeline to run different stages / jobs based on which cron schedule runs. For example, you have a nightly build and a weekly build, and you wish that during the weekly build your pipeline collect more statistics. + +We make this possible by introducing a new predefined system variable named `Build.CronSchedule.DisplayName` that contains the `displayName` property of a cron schedule. + +### New toggles to control creation of classic pipelines + +Last year, we launched a Pipelines configuration setting to [disable creation of classic build and release pipelines](/azure/devops/release-notes/2022/sprint-213-update#ensure-your-organization-only-uses-yaml-pipelines). + +In response to your feedback, we have split the initial toggle into two: one for classic _build_ pipelines and one for classic _release_ pipelines, deployment groups, and task groups. + +> [!div class="mx-imgBorder"] +> ![Disable creation](../../media/224-pipelines-03.png) + +If your organization has the `Disable creation of classic build and release pipelines` toggle on, both of the new toggles are on. If the original toggle is off, both new toggles are off. diff --git a/release-notes/2023/includes/pipelines/sprint-225-update-links.md b/release-notes/2023/includes/pipelines/sprint-225-update-links.md new file mode 100644 index 00000000000..929f4a39ff7 --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-225-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/2/2023 +ms.topic: include +--- + +- [Disable creation of classic pipelines for new organizations (_pre-announcement_)](#disable-creation-of-classic-pipelines-for-new-organizations-pre-announcement) + +- [Increased Azure Pipeline limits to align with the 4 MB maximum Azure Resource Manager (ARM) template size](#increased-azure-pipeline-limits-to-align-with-the-4-mb-maximum-azure-resource-manager-arm-template-size) diff --git a/release-notes/2023/includes/pipelines/sprint-225-update.md b/release-notes/2023/includes/pipelines/sprint-225-update.md new file mode 100644 index 00000000000..b6482909d59 --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-225-update.md @@ -0,0 +1,16 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/2/2023 +ms.topic: include +--- + +### Disable creation of classic pipelines for new organizations (pre-announcement) + +To improve the security of newly created organizations, we will disable creating _classic build and release pipelines_ for new organizations, beginning next sprint. By default, you'll be able to create only YAML pipelines. In contrast to the classic build and release pipelines, YAML pipelines can undergo code review, provide resource access management and support runtime parameters, enhancing overall security with an extra layer of protection. You can enable creation of classic build and release pipelines in your organization's and projects' settings, using the [toggles](/azure/devops/release-notes/2023/sprint-224-update?#new-toggles-to-control-creation-of-classic-pipelines) introduced last sprint. + +The changes will not impact existing projects and organizations. + +### Increased Azure Pipeline limits to align with the 4 MB maximum Azure Resource Manager (ARM) template size. + +You can use the [Azure Resource Manager Template Deployment](/azure/devops/pipelines/tasks/reference/azure-resource-manager-template-deployment-v3?view=azure-pipelines&preserve-view=true) task to create Azure infrastructure. In response to your feedback, we have increased the Azure Pipelines integration limit of 2 MB to 4 MB. This will align with the ARM Templates [maximum size of 4 MB](/azure/azure-resource-manager/templates/best-practices#template-limits) resolving size constraints during integration of large templates. diff --git a/release-notes/2023/includes/pipelines/sprint-226-update-links.md b/release-notes/2023/includes/pipelines/sprint-226-update-links.md new file mode 100644 index 00000000000..f84ded6364e --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-226-update-links.md @@ -0,0 +1,12 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/23/2023 +ms.topic: include +--- + +- [Retry a stage when approvals and checks time out](#retry-a-stage-when-approvals-and-checks-time-out) + +- [Administrator role for all Environments](#administrator-role-for-all-environments) + +- [Centralized control for building PRs from forked GitHub repos](#centralized-control-for-building-prs-from-forked-github-repos) \ No newline at end of file diff --git a/release-notes/2023/includes/pipelines/sprint-226-update.md b/release-notes/2023/includes/pipelines/sprint-226-update.md new file mode 100644 index 00000000000..7d4b2016df4 --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-226-update.md @@ -0,0 +1,62 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/23/2023 +ms.topic: include +--- + + +### Retry a stage when approvals and checks time out + +When approvals and checks time out, the stage they belong to is skipped. Stages that have a dependency on the skipped stage are also skipped. + +Now you can retry a stage when approvals and checks time-out. Previously, this was possible only when an approval timed out. + +> [!div class="mx-imgBorder"] +> ![Screenshot of stage retry.](../../media/226-pipelines-01.png "Screenshot of stage retry") + +### Administrator role for all Environments + +[Environments](/azure/devops/pipelines/process/environments) in YAML pipelines represent a compute resource to which you deploy your application, for example an AKS cluster or a set of VMs. They provide you with security controls and traceability for your deployments. + +Managing environments can be quite challenging. This is because, when an environment is created, the person creating it automatically becomes the sole administrator. For example, if you want to manage the approvals and checks of all environments in a centralized fashion, you had to ask every environment administrator to add a specific user or group as administrator, and then use REST API to configure the checks. This approach is tedious, error-prone, and doesn't scale when new environments are added. + +With this sprint, we added an [Administrator role](/azure/devops/pipelines/policies/permissions#set-environment-permissions) at the environments-hub level. This brings environments up to par with service connections or agent pools. To assign the Administrator role to a user or group, you need to already be an environments-hub administrator or organization-owner. + +> [!div class="mx-imgBorder"] +> ![Screenshot of Administrator role.](../../media/226-pipelines-02.png "Screenshot of Administrator role") + +A user with this Administrator role can administer permissions, manage, view and use any environment. This includes opening up environments to all pipelines. + +When you grant a user Administrator role at environments-hub level, they become administrators for all existing environments and for any future environments. + +### Centralized control for building PRs from forked GitHub repos + +If you build public repositories from GitHub, you must consider your stance on fork builds. Forks are especially dangerous since they come from outside your organization. + +You can improve the security of pipelines that build GitHub public repositories by reviewing our recommendations on how to [Build GitHub repositories](/azure/devops/pipelines/repos/github?view=azure-devops&tabs=yaml#important-security-considerations&preserve-view=true) and [Repository protection](/azure/devops/pipelines/security/repos?view=azure-devops#forks&preserve-view=true). Unfortunately, managing numerous pipelines and ensuring their adherence to best practices can require a substantial amount of effort. + +To enhance the security of your pipelines, we added an organization-level control for defining how pipelines build PRs from forked GitHub repos. The new setting is named _Limit building pull requests from forked GitHub repositories_ and works at organization and project level. + +The organization-level setting restricts the settings projects can have, and the project-level setting restricts the settings pipelines can have. + +Let's look at how the toggle works at organization level. The new control is off by default, so no settings are universally enforced. + + +> [!div class="mx-imgBorder"] +> ![Screenshot of toggle organization level.](../../media/226-pipelines-03.png "Screenshot of toggle organization level") + +When you turn on the toggle, you can choose to disable building PRs from forked GitHub repos. This means, no pipeline will run when such a PR is created. + +> [!div class="mx-imgBorder"] +> ![Screenshot of showing toggle on.](../../media/226-pipelines-04.png "Screenshot of toggle on") + +When you choose the _Securely build pull requests from forked repositories_ option, all pipelines, organization-wide, *cannot* make secrets available to builds of PRs from forked repositories, *cannot* make these builds have the same permissions as normal builds, and *must* be triggered by a PR comment. Projects can still decide to *not* allow pipelines to build such PRs. + +> [!div class="mx-imgBorder"] +> ![Screenshot of Securely build PR.](../../media/226-pipelines-05.png " Screenshot of Securely build PR") + +When you choose the _Customize_ option, you can define how to restrict pipeline settings. For example, you can ensure that all pipelines require a comment in order to build a PR from a forked GitHub repo, when the PR belongs to non-team members and non-contributors. But, you can choose to allow them to make secrets available to such builds. Projects can decide to *not* allow pipelines to build such PRs, or to build them securely, or have even more restrictive settings that what is specified at the organization level. + +> [!div class="mx-imgBorder"] +> ![Screenshot of Customize.](../../media/226-pipelines-06.png " Screenshot of Customize") diff --git a/release-notes/2023/includes/pipelines/sprint-227-update-links.md b/release-notes/2023/includes/pipelines/sprint-227-update-links.md new file mode 100644 index 00000000000..06768f6da51 --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-227-update-links.md @@ -0,0 +1,18 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/14/2023 +ms.topic: include +--- + +- [Workload identity federation in Azure Pipelines (public preview)](#workload-identity-federation-in-azure-pipelines-public-preview) + +- [Pipeline agents can be registered using Microsoft Entra ID instead of a PAT](#pipeline-agents-can-be-registered-using-microsoft-entra-id-instead-of-a-pat) + +- [REST APIs for Environments](#rest-apis-for-environments) + +- [Prevent Unintended Pipeline Runs](#prevent-unintended-pipeline-runs) + +- [Build GitHub Repositories Securely by Default](#build-github-repositories-securely-by-default) + +- [Disabled override of code coverage policy status to Failed when build is failing](#disabled-override-of-code-coverage-policy-status-to-failed-when-build-is-failing) diff --git a/release-notes/2023/includes/pipelines/sprint-227-update.md b/release-notes/2023/includes/pipelines/sprint-227-update.md new file mode 100644 index 00000000000..43447efe2d1 --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-227-update.md @@ -0,0 +1,103 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/14/2023 +ms.topic: include +--- + + +### Workload identity federation in Azure Pipelines (public preview) + +Do you want to stop storing secrets and certificates in Azure service connections? Want to stop worrying about rotating these secrets whenever they expire? We are now announcing a public preview of Workload Identity Federation for Azure service connections.[Workload identity federation](/azure/active-directory/workload-identities/workload-identity-federation) uses an industry-standard technology, Open ID Connect (OIDC), to simplify the authentication between Azure Pipelines and Azure. Instead of secrets, a federation subject is used to facilitate this authentication. + +As part of this feature, the Azure (ARM) service connection has been updated with another scheme to support Workload identity federation. This allows Pipeline tasks that use the Azure service connection to authenticate using a federation subject (`sc:////`). The main benefits of using this scheme over existing authentication schemes are as follows: + +- Simplified management: You don't to generate, copy, and store secrets from service principals in Azure AD to Azure DevOps anymore. Secrets that are used in other authentication schemes of Azure service connections (e.g., service principal) expire after a certain period (two years currently). When they expire, pipelines fail. You have to regenerate a new secret and update the service connection. Switching to workload identity federation eliminates the need to manage these secrets and improves the overall experience of creating and managing service connections. +- Improved security: With workload identity federation, there's no persistent secret involved in the communication between Azure Pipelines and Azure. As a result, tasks running in pipeline jobs can't leak or exfiltrate secrets that have access to your production environments. This has often been a concern for our customers. + +You can take advantage of these features in two ways: + +- Use the [new workload identity federation scheme](https://aka.ms/azdo-rm-workload-identity) whenever you create a new Azure service connection. Moving forward, this will be the recommended mechanism. +- [Convert](https://aka.ms/azdo-rm-workload-identity-conversion) your existing Azure service connections (which are based on secrets) to the new scheme. You can perform this conversion one connection at a time. Best of all, you don't have to modify any of the pipelines that use those service connections. They'll automatically apply the new scheme once you complete the conversion. + +To create a new Azure service connection using workload identity federation, simply select Workload identity federation (automatic) or ([manual](https://aka.ms/azdo-rm-workload-identity-manual)) in the Azure service connection creation experience: + +> [!div class="mx-imgBorder"] +> ![ Screenshot of resource.](../../media/227-pipelines-05.png "Screenshot of resource manager.") + +> [!div class="mx-imgBorder"] +> ![Screenshot of identify federation.](../../media/227-pipelines-06.png "Screenshot of identify federation") + +To convert a previously created Azure service connection, select the "Convert" action after selecting the connection: + +> [!div class="mx-imgBorder"] +> ![ Screenshot of convert.](../../media/227-pipelines-07.png " Screenshot of convert") + +All of the Azure tasks that are included with Azure Pipelines now support this new scheme. However, if you're using a task from the Marketplace or a home-grown custom task to deploy to Azure, then it may not support workload identity federation yet. In these cases, we ask that you update your task to support workload identity federation to improve security. A complete list of supported tasks can be found [here](https://aka.ms/azdo-rm-workload-identity-troubleshooting). + +For this preview, we support workload identity federation only for Azure service connections. This scheme doesn't work with any other types of service connections. See our docs for more details. + +[This blog post](https://devblogs.microsoft.com/devops/public-preview-of-workload-identity-federation-for-azure-pipelines/) contains more details. + +### Pipeline agents can be registered using Microsoft Entra ID instead of a PAT + +The Pipeline agent now supports more arguments to use either a Service Principal or a user to register an agent. You should grant the identity used access to the agent pool in its security settings. This removes the need to use a Personal Access Token (PAT) for one-time setup of agents. + +#### Register an agent using a Service Principal + +To use a Service Principal to register a Pipelines agent with Azure DevOps Services, provide the following arguments: +``` +--auth 'SP' --clientid 00001111-aaaa-2222-bbbb-3333cccc4444 --clientsecret --tenantid aaaabbbb-0000-cccc-1111-dddd2222eeee +``` +#### Use a Service Principal in the Agent VM extension + +Azure VMs can be included in Deployment Groups using a [VM Extension](/azure/devops/pipelines/release/deployment-groups/howto-provision-deployment-group-agents?view=azure-devops#install-the-azure-pipelines-agent-azure-vm-extension-using-an-arm-template&preserve-view=true). The VM extension has been updated to use a Service Principal instead of a PAT to register the agent: +``` +"settings": { + "userServicePrincipal": true +} +"protectedSettings": { + "clientId": "[parameters('clientId')]" + "clientSecret": "[parameters('clientSecret')]" + "tenantId": "[parameters('tenantId')]" +} +``` +#### Register an agent interactively using device code flow + +You can use a web browser to easily complete setup. When you run the agent configuration script, enter **"AAD"** for authentication type. The script will guide you through the next steps, including where to go on the web and what code to enter. After you enter your code on the web, return to the console to finish setting up the agent. + +> [!div class="mx-imgBorder"] +> ![ Screenshot of authentication flow.](../../media/227-pipelines-04.png " Screenshot of authentication flow") + + +### REST APIs for Environments + +An [Environment](/azure/devops/pipelines/process/environments?view=azure-devops&preserve-view=true) is a collection of resources that you can target with deployments from a pipeline. Environments provide you with deployment history, traceability for work items and commits, and access control mechanisms. + +We know you want to create environments [programmatically](https://developercommunity.visualstudio.com/t/rest-api-to-manage-environments-yaml-pipelines/859033), so we published documentation for their [REST API](/rest/api/azure/devops/environments/environments/add). + +### Prevent unintended pipeline runs + +Today, if your YAML pipeline doesn't specify a `trigger` section, it runs for any changes pushed to its repository. This can create confusion as to why a pipeline ran and lead to many unintended runs. + +We added an organization- and project-level Pipelines setting named _Disable implied YAML CI trigger_ that lets you change this behavior. You can choose to not trigger pipelines if their trigger section is missing. + +> [!div class="mx-imgBorder"] +> ![ Screenshot of YAML CI trigger.](../../media/227-pipelines-01.png " Screenshot of YAML CI trigger") + +### Build GitHub repositories securely by default + +Last sprint, we introduced a [centralized control for building PRs from forked GitHub repos](/azure/devops/release-notes/2023/sprint-226-update#centralized-control-for-building-prs-from-forked-github-repos). + +With this sprint, we are enabling the `Securely build pull requests from forked repositories` option at the organization level, for new organizations. Existing organizations are unaffected. + +### Disabled override of code coverage policy status to Failed when build is failing + +Previously in, the code coverage policy status was overridden to 'Failed' if your build in PR was failing. This was a blocker for some of you who had the build as an optional check and the code coverage policy as a required check for PRs resulting in PRs being blocked. + +:::image type="content" source="../../media/227-pipelines-02.png" alt-text="Screenshot of PRs blocked." lightbox="../../media/227-pipelines-02.png"::: + +With this sprint, the code coverage policy won't be overridden to 'Failed' if the build fails. +This feature will be enabled for all customers. + +:::image type="content" source="../../media/227-pipelines-03.png" alt-text="Screenshot of results after change." lightbox="../../media/227-pipelines-03.png"::: diff --git a/release-notes/2023/includes/pipelines/sprint-228-update-links.md b/release-notes/2023/includes/pipelines/sprint-228-update-links.md new file mode 100644 index 00000000000..a3965320c24 --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-228-update-links.md @@ -0,0 +1,9 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +ms.topic: include +--- + +- [Pipeline logs now contain resource utilization](#pipeline-logs-now-contain-resource-utilization) +- [Azure Pipelines agent now supports Alpine Linux](#azure-pipelines-agent-now-supports-alpine-linux) \ No newline at end of file diff --git a/release-notes/2023/includes/pipelines/sprint-228-update.md b/release-notes/2023/includes/pipelines/sprint-228-update.md new file mode 100644 index 00000000000..d30cdf8d04a --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-228-update.md @@ -0,0 +1,18 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +ms.topic: include +--- +### Pipeline logs now contain resource utilization + +Azure pipeline logs can now capture resource utilization metrics such as memory, CPU usage and available disk space. The logs also include resources used by the pipeline agent and child processes including tasks run in a job. + +> [!div class="mx-imgBorder"] +> ![Screenshot of logs including resources used by the pipeline.](../../media/228-pipelines-01.png " Screenshot of logs including resources used by the pipeline.") + +If you suspect your pipeline job may run into resource constraints, enable [verbose logs](/azure/devops/pipelines/troubleshooting/review-logs#configure-verbose-logs) to have resource utilization information injected into pipeline logs. This works on any agent, independent from hosting model. + +## Azure Pipelines agent now supports Alpine Linux + +The Pipeline agent v3.227 now supports [Alpine Linux](https://alpinelinux.org/) versions 3.13 and above. Alpine Linux is a popular for container (base) image. You can find the agent on the [releases](https://github.com/microsoft/azure-pipelines-agent/releases) page. Alpine Linux versions of the agent have a prefix `vsts-agent-linux-musl` e.g. `vsts-agent-linux-musl-x64-3.227.1.tar.gz`. \ No newline at end of file diff --git a/release-notes/2023/includes/pipelines/sprint-229-update-links.md b/release-notes/2023/includes/pipelines/sprint-229-update-links.md new file mode 100644 index 00000000000..83525d90aaa --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-229-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +ms.topic: include +--- + +- [Building PRs from forked GitHub repositories](#building-prs-from-forked-github-repositories) diff --git a/release-notes/2023/includes/pipelines/sprint-229-update.md b/release-notes/2023/includes/pipelines/sprint-229-update.md new file mode 100644 index 00000000000..af9d3ab5b0f --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-229-update.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +ms.topic: include +--- + +### Building PRs from forked GitHub repositories + +To improve the security of your pipelines, Azure Pipelines no longer automatically builds pull requests from forked GitHub repositories for new projects and organizations. Now, the default value of the _Limit building pull requests from forked GitHub repositories_ setting is _Disable building pull requests from forked repositories_ for new projects and organizations. diff --git a/release-notes/2023/includes/pipelines/sprint-230-update-links.md b/release-notes/2023/includes/pipelines/sprint-230-update-links.md new file mode 100644 index 00000000000..fa130b3f80a --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-230-update-links.md @@ -0,0 +1,14 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +ms.topic: include +--- + +- [Azure Pipelines tasks use Node 16](#azure-pipelines-tasks-use-node-16) +- [Announcing retirement of deprecated tasks](#announcing-retirement-of-deprecated-tasks) +- [AzureRmWebAppDeployment task supports Microsoft Entra ID authentication](#azurermwebappdeployment-task-supports-microsoft-entra-id-authentication) +- [Improvements to Approvals REST API](#improvements-to-approvals-rest-api) +- [Support for GitHub Enterprise Server in Required template check](#support-for-github-enterprise-server-in-required-template-check) +- [Bypass Approvals and Checks](#bypass-approvals-and-checks) +- [Rerun Invoke Azure Function checks](#rerun-invoke-azure-function-checks) diff --git a/release-notes/2023/includes/pipelines/sprint-230-update.md b/release-notes/2023/includes/pipelines/sprint-230-update.md new file mode 100644 index 00000000000..681ef29107d --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-230-update.md @@ -0,0 +1,154 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +ms.topic: include +--- + +### Azure Pipelines tasks use Node 16 + +Tasks in the pipeline are executed using a runner, with Node.js used in most cases. Azure Pipelines tasks that utilize a Node as a runner now all use Node 16. As Node 16 is the first Node version to natively support Apple silicon, this also completes full task support for macOS on Apple silicon. Agents running on Apple silicon do not need Rosetta to run. + +As the Node 16 end-of-life date has [moved forward](https://nodejs.org/en/blog/announcements/nodejs16-eol), we have started the work to run tasks with Node 20. + +### Announcing retirement of deprecated tasks + +Azure Pipelines has many deprecated tasks. Deprecated tasks will be retired January 31, 2024. To help you identify pipelines that are using deprecated tasks, pipelines will show warnings if such a task is used. We updated the [Task Reference](/azure/devops/pipelines/tasks/reference/?view=azure-pipelines&preserve-view=true) to clearly convey deprecation status and retirement date. + +The following tasks have been deprecated and will start emitting warnings: +* AppCenterDistributeV1, +* AppCenterDistributeV2 +* AzureMonitorV0 +* ChefKnifeV1 +* ChefV1 +* CondaEnvironmentV1 +* DeployVisualStudioTestAgentV2 +* DotNetCoreInstallerV1 +* IISWebAppDeployment +* QuickPerfTestV1 +* RunJMeterLoadTestV1 +* RunLoadTestV1 +* SqlServerDacpacDeploymentV1 +* XamarinTestCloudV1 + +Update your pipelines to use a newer task version or an alternative before January 31, 2024. + +### AzureRmWebAppDeployment task supports Microsoft Entra ID authentication + +The AzureRmWebAppDeploymentV3 and [AzureRmWebAppDeployment@4](/azure/devops/pipelines/tasks/reference/azure-rm-web-app-deployment-v4?view=azure-pipelines&preserve-view=true) tasks have been updated to support App Service with [basic authentication disabled](/azure/app-service/configure-basic-auth-disable?tabs=portal&preserve-view=true). If basic authentication is disabled on the App Service, the AzureRmWebAppDeploymentV3/4 tasks use Microsoft Entra ID authentication to perform deployments to the App Service Kudu endpoint. This requires a recent version of msdeploy.exe installed on the agent, which is the case on the windows-2022/windows-latest [Hosted agents](/azure/devops/pipelines/agents/hosted?view=azure-devops&tabs=yaml#software&preserve-view=true) (see [task reference](/azure/devops/pipelines/tasks/reference/azure-rm-web-app-deployment-v4?view=azure-pipelines#i-cant-web-deploy-to-my-azure-app-service-using-microsoft-entra-id-authentication-from-my-windows-agent&preserve-view=true)). + + +### Improvements to Approvals REST API + +We improved locating approvals assigned to a user by including the groups the user belongs to in the search results. + +Approvals now contain information about the pipeline run they belong to. + + +For example, the following GET REST API call `https://dev.azure.com/fabrikam/FabrikamFiber/_apis/pipelines/approvals?api-version=7.2-preview.2&top=1&assignedTo=john@fabrikam.com&state=pending` returns + +```json +{ + "count": 1, + "value": + [ + { + "id": "7e90b9f7-f3f8-4548-a108-8b80c0fa80e7", + "steps": + [], + "status": "pending", + "createdOn": "2023-11-09T10:54:37.977Z", + "lastModifiedOn": "2023-11-09T10:54:37.9775685Z", + "executionOrder": "anyOrder", + "minRequiredApprovers": 1, + "blockedApprovers": + [], + "_links": + { + "self": + { + "href": "https://dev.azure.com/fabrikam/26dcfaeb-d8fe-495c-91cb-fec4acb44fbb/_apis/pipelines/approvals/7e80b987-f3fe-4578-a108-8a80c0fb80e7" + } + }, + "pipeline": + { + "owner": + { + "_links": + { + "web": + { + "href": "https://dev.azure.com/buildcanary/26dcfaeb-d8fe-495c-91cb-fec4acb44fbb/_build/results?buildId=73222930" + }, + "self": + { + "href": "https://dev.azure.com/buildcanary/26dcfaeb-d8fe-495c-91cb-fec4acb44fbb/_apis/build/Builds/73222930" + } + }, + "id": 73222930, + "name": "20231109.1" + }, + "id": "4597", + "name": "FabrikamFiber" + } + } + ] +} +``` + + +### Bypass Approvals and Checks + +[Approvals and checks](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass&preserve-view=true ) help protect access to important resources, such as service connections, repos, or agent pools. A common use case is to use Approvals and Checks when deploying to production, and you wish to protect the ARM service connection. + +Say you added the following checks on the service connection: an Approval, a Business Hours check, and an Invoke Azure Function check (to enforce a delay between different regions). + +Now, imagine you have to do a hotfix deployment. You start a pipeline run, but it doesn't proceed,it waits for most of the checks to complete. You cannot afford to wait for the approvals and checks to complete. + +In this sprint we've made it possible to bypass running approvals and checks, so you can complete your hotfix. + +You can bypass running Approvals, Business Hours, Invoke Azure Function, and Invoke REST API checks. + +Bypass an Approval. +> [!div class="mx-imgBorder"] +> ![Screenshot of Bypass an Approval.](../../media/230-pipelines-01.png " Screenshot of Bypass an Approval.") + +Bypass Business Hours check. +> [!div class="mx-imgBorder"] +> ![Screenshot of Bypass Business Hours check.](../../media/230-pipelines-02.png " Screenshot of Bypass Business Hours check.") + +Bypass Invoke Azure Function check. +Bypass Business Hours check. +> [!div class="mx-imgBorder"] +> ![Screenshot of Bypass Invoke Azure Function check.](../../media/230-pipelines-03.png " Screenshot of Bypass Invoke Azure Function check.") + +When a check is bypassed, you can see it in the checks panel. +> [!div class="mx-imgBorder"] +> ![Screenshot of check bypassed.](../../media/230-pipelines-04.png " Screenshot of check bypassed.") + +You can bypass a check only if you're an Administrator of the resource on which the checks were defined. + +### Support for GitHub enterprise server in required template check + +[Templates](/azure/devops/pipelines/security/templates) are a security mechanism that enables you to control the stages, jobs, and steps of pipelines in your organization. + +The [Require template check](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass#required-template&preserve-view=true) enables you to enforce that a pipeline extends from a set of approved templates before accessing a protected resource, such as an agent pool or service connection. + +Starting with this sprint, you can specify templates located in GitHub Enterprise Server repos. + +> [!div class="mx-imgBorder"] +> ![Screenshot of required YAML template.](../../media/230-pipelines-06.png " Screenshot of required YAML template.") + +### Rerun invoke Azure function checks + +Imagine that you deploy your system in multiple stages. Before deploying the second stage, there's an Approval and an Invoke Azure Function check that runs a sanity check on the already-deployed part of the system. + +When reviewing the Approval request, you notice the sanity check ran two days earlier. In this scenario, you may be aware of another deployment that affected the result of the sanity check. + +With this update, you can rerun Invoke Azure Function and Invoke REST API checks. This functionality is available only for checks that succeeded and have no retries. + +> [!div class="mx-imgBorder"] +> ![Screenshot of dynamic check.](../../media/230-pipelines-05.png " Screenshot of dynamic check.") + +> [!NOTE] +> You can rerun a check only if you are an Administrator of the resource on which the checks were defined. \ No newline at end of file diff --git a/release-notes/2023/includes/pipelines/sprint-231-update-links.md b/release-notes/2023/includes/pipelines/sprint-231-update-links.md new file mode 100644 index 00000000000..45648f792da --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-231-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 12/5/2023 +ms.topic: include +--- + +- [Improved YAML validation](#improved-yaml-validation) +- [Checks scalability Phase 3](#checks-scalability-phase-3) \ No newline at end of file diff --git a/release-notes/2023/includes/pipelines/sprint-231-update.md b/release-notes/2023/includes/pipelines/sprint-231-update.md new file mode 100644 index 00000000000..563caf2f558 --- /dev/null +++ b/release-notes/2023/includes/pipelines/sprint-231-update.md @@ -0,0 +1,65 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 12/5/2023 +ms.topic: include +--- + +### Improved YAML validation + +To verify your YAML syntax is correct, you can use the Azure Pipelines web editor's _Validate_ functionality. Thus, it's important that this functionality catch as many YAML issues as possible. + +> [!div class="mx-imgBorder"] +> ![Screenshot of YAML validation.](../../media/231-pipelines-01.png " Screenshot of YAML validation.") + +With this sprint, YAML validation is more thorough when it comes to expressions. + +When writing YAML pipelines, you can use [functions](/azure/devops/pipelines/process/expressions#functions) to define variable values. + +Imagine you define the following variables: +```yaml +variables: + Major: '1' + Minor: '0' + Patch: $[counter(format('{0}.{1}', variables.Major, variables.Minor ), 0)] +``` + +The `Patch` variable is defined using the `counter` function and the other two variables. In the YAML code above, the word `format` is misspelt. Previously, this error went undetected. Now, the _Validate_ functionality will detect this and surface an error message. + +> [!div class="mx-imgBorder"] +> ![Screenshot of incorrect variable definitions detected .](../../media/231-pipelines-02.png " Screenshot of incorrect variable definitions detected .") + +Azure Pipelines will detect incorrect variable definitions at pipeline / stage / job level. + +In YAML pipelines, you can skip the execution of stage using [conditions](/azure/devops/pipelines/process/conditions). Typos can show up here as well, like in the following example. + +```yml +steps: +- task: NuGetCommand@2 + condition: eq(variable.Patch, 0) + inputs: + command: pack + versioningScheme: byPrereleaseNumber + majorVersion: '$(Major)' + minorVersion: '$(Minor)' + patchVersion: '$(Patch)' +``` + +The `NuGetCommand` task executes only if the value of the `Patch` variable is 0. Again, there's a typo in the condition, and the _Validate_ functionality will display it. + +> [!div class="mx-imgBorder"] +> ![Screenshot of Patch variable.](../../media/231-pipelines-03.png " Screenshot of Patch variable.") + +Azure Pipelines will detect incorrect YAML conditions defined at pipeline / stage / job level. + +### Checks scalability Phase 3 + +As mentioned in our [Updates to Approvals and Checks blog post](https://devblogs.microsoft.com/devops/updates-to-approvals-and-checks/), we're working toward improving our Approvals & Checks's scalability. + +Advancing into Phase 3, we'll carry out weekly, day-long brownouts, during which all pipeline runs that use non-compliant checks will fail. + +The scheduled brownout dates are: +* January 9, 2024, 08:00 UTC to January 10, 2024, 08:00 UTC +* January 16, 2024, 08:00 UTC to January 17, 2024, 08:00 UTC +* January 23, 2024, 08:00 UTC to January 24, 2024, 08:00 UTC +* January 30, 2024, 08:00 UTC to January 31, 2024, 08:00 UTC diff --git a/release-notes/2023/includes/reporting/sprint-229-update-links.md b/release-notes/2023/includes/reporting/sprint-229-update-links.md new file mode 100644 index 00000000000..149743f7914 --- /dev/null +++ b/release-notes/2023/includes/reporting/sprint-229-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +ms.topic: include +--- + +- [New Dashboard directory experience](#new-dashboard-directory-experience) diff --git a/release-notes/2023/includes/reporting/sprint-229-update.md b/release-notes/2023/includes/reporting/sprint-229-update.md new file mode 100644 index 00000000000..9f865464d47 --- /dev/null +++ b/release-notes/2023/includes/reporting/sprint-229-update.md @@ -0,0 +1,16 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +ms.topic: include +--- + +### New Dashboard directory experience + +We've listened to your feedback and are thrilled to introduce the new Dashboard directory experience. It not only features a modern UI design but also enables you to sort by each column, with the addition of the ***Last Configured*** column. This column will provide you with better insights into overall dashboard usage within your organization. Additionally, you can now filter by team or project-level dashboards, allowing you to access only the list of what you need to see while hiding the dashboards you don’t want to view. + +> [!div class="mx-imgBorder"] +> ![Gif to demo new Dashboard directory.](../../media/229-reporting-01.gif "gif to demo new Dashboard directory") + + Try it now and let us know what you think in our [Azure DevOps community ](https://developercommunity.visualstudio.com/AzureDevOps) + diff --git a/release-notes/2023/includes/reporting/sprint-230-update-links.md b/release-notes/2023/includes/reporting/sprint-230-update-links.md new file mode 100644 index 00000000000..b560e428f59 --- /dev/null +++ b/release-notes/2023/includes/reporting/sprint-230-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +ms.topic: include +--- + +- [Work item filtering](#work-item-filtering) \ No newline at end of file diff --git a/release-notes/2023/includes/reporting/sprint-230-update.md b/release-notes/2023/includes/reporting/sprint-230-update.md new file mode 100644 index 00000000000..bf5afff853d --- /dev/null +++ b/release-notes/2023/includes/reporting/sprint-230-update.md @@ -0,0 +1,15 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +ms.topic: include +--- + +### Work item filtering + +We are happy to announce **work item chart filtering.** This feature will let you hover over your work item chart for a quick overview and drill down into specific chart segments for detailed insights. You no longer need to create custom queries to access the exact piece of data you need. You can now dive into your work items in work item charts in a few clicks. + + > [!div class="mx-imgBorder"] +> ![Gif to demo work item filtering.](../../media/230-reporting-01.gif "gif to demo work item filtering") + +Your feedback is invaluable in shaping the future of this feature. Try it now and let us know what you think in our [Azure DevOps community](https://developercommunity.visualstudio.com/AzureDevOps). \ No newline at end of file diff --git a/release-notes/2023/includes/repos/sprint-224-update-links.md b/release-notes/2023/includes/repos/sprint-224-update-links.md new file mode 100644 index 00000000000..04d78aab2f7 --- /dev/null +++ b/release-notes/2023/includes/repos/sprint-224-update-links.md @@ -0,0 +1,8 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +ms.topic: include +--- + +- [Removing "Edit policies" permission to branch creator](#removing-edit-policies-permission-to-branch-creator) \ No newline at end of file diff --git a/release-notes/2023/includes/repos/sprint-224-update.md b/release-notes/2023/includes/repos/sprint-224-update.md new file mode 100644 index 00000000000..4bcad027d49 --- /dev/null +++ b/release-notes/2023/includes/repos/sprint-224-update.md @@ -0,0 +1,14 @@ +--- +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +ms.topic: include +--- +### Removing "Edit policies" permission to branch creator + +Previously, when you created a new branch, you we're granted permission to edit policies on that branch. With this update, we are changing the default behavior to not grant this permission even if the "Permission management" setting is switched on for the repository. + +> [!div class="mx-imgBorder"] +> ![Permission management image.](../../media/224-repos-01.png "image showing permission management toggle is off for a repo") + +You will need the "Edit policies" permission granted explicitly (either manually or through REST API) by security permission inheritance or through a group membership. \ No newline at end of file diff --git a/release-notes/2023/includes/repos/sprint-226-update-links.md b/release-notes/2023/includes/repos/sprint-226-update-links.md new file mode 100644 index 00000000000..1992a82585e --- /dev/null +++ b/release-notes/2023/includes/repos/sprint-226-update-links.md @@ -0,0 +1,8 @@ +--- +author: bjanousek +ms.author: bjanousek +ms.date: 8/23/2023 +ms.topic: include +--- + +- [New "Branch policy" preventing users to approve their own changes](#new-branch-policy-preventing-users-to-approve-their-own-changes) diff --git a/release-notes/2023/includes/repos/sprint-226-update.md b/release-notes/2023/includes/repos/sprint-226-update.md new file mode 100644 index 00000000000..2b1a9c67534 --- /dev/null +++ b/release-notes/2023/includes/repos/sprint-226-update.md @@ -0,0 +1,24 @@ +--- +author: bjanousek +ms.author: bjanousek +ms.date: 8/23/2023 +ms.topic: include +--- +### New "Branch policy" preventing users to approve their own changes + +To improve the control around what changes user approves and match stricter regulatory/compliance requirements, we do provide an option to prevent user approving his own changes unless explicitly allowed. + +User with ability to manage the branch policies can now switch newly added option "Require at least one approval on every iteration" under the "When new changes are pushed". +When this option is selected, then at least one approval vote for the last source branch change is required. +The user's approval is not counted against any previous unapproved iteration pushed by that user. +As a result, additional approval on the last iteration is required to be done by another user. + +Following image shows pull request created by user A and additional 4 commits (iterations) made to that pull request by users B, C, A again and C. +After the second iteration (commit done by user B) was done, user C approved that. +At that time, it implied approval of first commit of user A (when the pull request was created) and the newly introduced policy will succeed. +After the fifth iteration (last commit of user C), the approval was done by user A. +This implied approval for earlier commit done by user C, but was not implying approval for the second commit done by user A in the fourth iteration. +To make the newly introduced policy to succeed, the unapproved iteration four must be approved either by approval from user B, C or any other user who has not made any change to the pull request. + +> [!div class="mx-imgBorder"] +> ![Permission management image.](../../media/226-repos-01.png "image showing sequence of commits done by three users together with approval votes") diff --git a/release-notes/2023/includes/repos/sprint-227-update-links.md b/release-notes/2023/includes/repos/sprint-227-update-links.md new file mode 100644 index 00000000000..f9e4bf4594b --- /dev/null +++ b/release-notes/2023/includes/repos/sprint-227-update-links.md @@ -0,0 +1,8 @@ +--- +author: bjanousek +ms.author: bjanousek +ms.date: 9/14/2023 +ms.topic: include +--- + +- [Blobless and treeless filter support](#blobless-and-treeless-filter-support) diff --git a/release-notes/2023/includes/repos/sprint-227-update.md b/release-notes/2023/includes/repos/sprint-227-update.md new file mode 100644 index 00000000000..f002e4d9435 --- /dev/null +++ b/release-notes/2023/includes/repos/sprint-227-update.md @@ -0,0 +1,14 @@ +--- +author: bjanousek +ms.author: bjanousek +ms.date: 9/14/2023 +ms.topic: include +--- + +### Blobless and treeless filter support + +Azure DevOps now supports two additional filtering while cloning/fetching. These are: +`--filter=blob:none` +and +`--filter=tree:0` +The first option (blobless clone) is best used for regular development while the second option (treeless clone) fits better for those cases where you discard of the clone after, for example running a build. diff --git a/release-notes/2023/media/224-boards-01.png b/release-notes/2023/media/224-boards-01.png new file mode 100644 index 00000000000..0ac9625f52d Binary files /dev/null and b/release-notes/2023/media/224-boards-01.png differ diff --git a/release-notes/2023/media/224-general-01.png b/release-notes/2023/media/224-general-01.png new file mode 100644 index 00000000000..eaf87feb227 Binary files /dev/null and b/release-notes/2023/media/224-general-01.png differ diff --git a/release-notes/2023/media/224-pipelines-01.png b/release-notes/2023/media/224-pipelines-01.png new file mode 100644 index 00000000000..c84eb018ea5 Binary files /dev/null and b/release-notes/2023/media/224-pipelines-01.png differ diff --git a/release-notes/2023/media/224-pipelines-02.png b/release-notes/2023/media/224-pipelines-02.png new file mode 100644 index 00000000000..3a904625cb6 Binary files /dev/null and b/release-notes/2023/media/224-pipelines-02.png differ diff --git a/release-notes/2023/media/224-pipelines-03.png b/release-notes/2023/media/224-pipelines-03.png new file mode 100644 index 00000000000..7042cf4994d Binary files /dev/null and b/release-notes/2023/media/224-pipelines-03.png differ diff --git a/release-notes/2023/media/224-repos-01.png b/release-notes/2023/media/224-repos-01.png new file mode 100644 index 00000000000..eb3b2901d61 Binary files /dev/null and b/release-notes/2023/media/224-repos-01.png differ diff --git a/release-notes/2023/media/225-boards-01.gif b/release-notes/2023/media/225-boards-01.gif new file mode 100644 index 00000000000..2ee13d496ac Binary files /dev/null and b/release-notes/2023/media/225-boards-01.gif differ diff --git a/release-notes/2023/media/225-pipelines-01.png b/release-notes/2023/media/225-pipelines-01.png new file mode 100644 index 00000000000..475fd19ac99 Binary files /dev/null and b/release-notes/2023/media/225-pipelines-01.png differ diff --git a/release-notes/2023/media/225-pipelines-02.png b/release-notes/2023/media/225-pipelines-02.png new file mode 100644 index 00000000000..7737bd06746 Binary files /dev/null and b/release-notes/2023/media/225-pipelines-02.png differ diff --git a/release-notes/2023/media/226-general-01.png b/release-notes/2023/media/226-general-01.png new file mode 100644 index 00000000000..72eaf949f5a Binary files /dev/null and b/release-notes/2023/media/226-general-01.png differ diff --git a/release-notes/2023/media/226-general-02.png b/release-notes/2023/media/226-general-02.png new file mode 100644 index 00000000000..c0bafc306ea Binary files /dev/null and b/release-notes/2023/media/226-general-02.png differ diff --git a/release-notes/2023/media/226-general-03.png b/release-notes/2023/media/226-general-03.png new file mode 100644 index 00000000000..2d0306731ff Binary files /dev/null and b/release-notes/2023/media/226-general-03.png differ diff --git a/release-notes/2023/media/226-pipelines-01.png b/release-notes/2023/media/226-pipelines-01.png new file mode 100644 index 00000000000..bd01819b4e2 Binary files /dev/null and b/release-notes/2023/media/226-pipelines-01.png differ diff --git a/release-notes/2023/media/226-pipelines-02.png b/release-notes/2023/media/226-pipelines-02.png new file mode 100644 index 00000000000..8036122b7c5 Binary files /dev/null and b/release-notes/2023/media/226-pipelines-02.png differ diff --git a/release-notes/2023/media/226-pipelines-03.png b/release-notes/2023/media/226-pipelines-03.png new file mode 100644 index 00000000000..1595680cbce Binary files /dev/null and b/release-notes/2023/media/226-pipelines-03.png differ diff --git a/release-notes/2023/media/226-pipelines-04.png b/release-notes/2023/media/226-pipelines-04.png new file mode 100644 index 00000000000..c0ddc5704ef Binary files /dev/null and b/release-notes/2023/media/226-pipelines-04.png differ diff --git a/release-notes/2023/media/226-pipelines-05.png b/release-notes/2023/media/226-pipelines-05.png new file mode 100644 index 00000000000..7af9fa9a574 Binary files /dev/null and b/release-notes/2023/media/226-pipelines-05.png differ diff --git a/release-notes/2023/media/226-pipelines-06.png b/release-notes/2023/media/226-pipelines-06.png new file mode 100644 index 00000000000..89b909f3b4c Binary files /dev/null and b/release-notes/2023/media/226-pipelines-06.png differ diff --git a/release-notes/2023/media/226-repos-01.png b/release-notes/2023/media/226-repos-01.png new file mode 100644 index 00000000000..f6e44097abe Binary files /dev/null and b/release-notes/2023/media/226-repos-01.png differ diff --git a/release-notes/2023/media/227-boards-01.png b/release-notes/2023/media/227-boards-01.png new file mode 100644 index 00000000000..1e02bcce7d4 Binary files /dev/null and b/release-notes/2023/media/227-boards-01.png differ diff --git a/release-notes/2023/media/227-pipelines-01.png b/release-notes/2023/media/227-pipelines-01.png new file mode 100644 index 00000000000..926d81d934c Binary files /dev/null and b/release-notes/2023/media/227-pipelines-01.png differ diff --git a/release-notes/2023/media/227-pipelines-02.png b/release-notes/2023/media/227-pipelines-02.png new file mode 100644 index 00000000000..ea0da08e3e9 Binary files /dev/null and b/release-notes/2023/media/227-pipelines-02.png differ diff --git a/release-notes/2023/media/227-pipelines-03.png b/release-notes/2023/media/227-pipelines-03.png new file mode 100644 index 00000000000..4c2e96875a8 Binary files /dev/null and b/release-notes/2023/media/227-pipelines-03.png differ diff --git a/release-notes/2023/media/227-pipelines-04.png b/release-notes/2023/media/227-pipelines-04.png new file mode 100644 index 00000000000..5c885a2d340 Binary files /dev/null and b/release-notes/2023/media/227-pipelines-04.png differ diff --git a/release-notes/2023/media/227-pipelines-05.png b/release-notes/2023/media/227-pipelines-05.png new file mode 100644 index 00000000000..2c63fcbdfbb Binary files /dev/null and b/release-notes/2023/media/227-pipelines-05.png differ diff --git a/release-notes/2023/media/227-pipelines-06.png b/release-notes/2023/media/227-pipelines-06.png new file mode 100644 index 00000000000..a077e478977 Binary files /dev/null and b/release-notes/2023/media/227-pipelines-06.png differ diff --git a/release-notes/2023/media/227-pipelines-07.png b/release-notes/2023/media/227-pipelines-07.png new file mode 100644 index 00000000000..ab5a9146d9e Binary files /dev/null and b/release-notes/2023/media/227-pipelines-07.png differ diff --git a/release-notes/2023/media/228-boards-01.gif b/release-notes/2023/media/228-boards-01.gif new file mode 100644 index 00000000000..d44a31e15c8 Binary files /dev/null and b/release-notes/2023/media/228-boards-01.gif differ diff --git a/release-notes/2023/media/228-boards-01.png b/release-notes/2023/media/228-boards-01.png new file mode 100644 index 00000000000..95744fa3de5 Binary files /dev/null and b/release-notes/2023/media/228-boards-01.png differ diff --git a/release-notes/2023/media/228-general-01.png b/release-notes/2023/media/228-general-01.png new file mode 100644 index 00000000000..46999063408 Binary files /dev/null and b/release-notes/2023/media/228-general-01.png differ diff --git a/release-notes/2023/media/228-pipelines-01.png b/release-notes/2023/media/228-pipelines-01.png new file mode 100644 index 00000000000..3f5a54f998d Binary files /dev/null and b/release-notes/2023/media/228-pipelines-01.png differ diff --git a/release-notes/2023/media/229-general-01.png b/release-notes/2023/media/229-general-01.png new file mode 100644 index 00000000000..32d6c3388ac Binary files /dev/null and b/release-notes/2023/media/229-general-01.png differ diff --git a/release-notes/2023/media/229-reporting-01.gif b/release-notes/2023/media/229-reporting-01.gif new file mode 100644 index 00000000000..8c17b9ea6ec Binary files /dev/null and b/release-notes/2023/media/229-reporting-01.gif differ diff --git a/release-notes/2023/media/230-boards-01.png b/release-notes/2023/media/230-boards-01.png new file mode 100644 index 00000000000..d33905221b1 Binary files /dev/null and b/release-notes/2023/media/230-boards-01.png differ diff --git a/release-notes/2023/media/230-pipelines-01.png b/release-notes/2023/media/230-pipelines-01.png new file mode 100644 index 00000000000..ba4e681831e Binary files /dev/null and b/release-notes/2023/media/230-pipelines-01.png differ diff --git a/release-notes/2023/media/230-pipelines-02.png b/release-notes/2023/media/230-pipelines-02.png new file mode 100644 index 00000000000..01530177f1d Binary files /dev/null and b/release-notes/2023/media/230-pipelines-02.png differ diff --git a/release-notes/2023/media/230-pipelines-03.png b/release-notes/2023/media/230-pipelines-03.png new file mode 100644 index 00000000000..b7a5f4e6cce Binary files /dev/null and b/release-notes/2023/media/230-pipelines-03.png differ diff --git a/release-notes/2023/media/230-pipelines-04.png b/release-notes/2023/media/230-pipelines-04.png new file mode 100644 index 00000000000..528f01b19e7 Binary files /dev/null and b/release-notes/2023/media/230-pipelines-04.png differ diff --git a/release-notes/2023/media/230-pipelines-05.png b/release-notes/2023/media/230-pipelines-05.png new file mode 100644 index 00000000000..89e5b086770 Binary files /dev/null and b/release-notes/2023/media/230-pipelines-05.png differ diff --git a/release-notes/2023/media/230-pipelines-06.png b/release-notes/2023/media/230-pipelines-06.png new file mode 100644 index 00000000000..48121598b22 Binary files /dev/null and b/release-notes/2023/media/230-pipelines-06.png differ diff --git a/release-notes/2023/media/230-reporting-01.gif b/release-notes/2023/media/230-reporting-01.gif new file mode 100644 index 00000000000..9f784e8609e Binary files /dev/null and b/release-notes/2023/media/230-reporting-01.gif differ diff --git a/release-notes/2023/media/231-boards-01.gif b/release-notes/2023/media/231-boards-01.gif new file mode 100644 index 00000000000..d651c34d664 Binary files /dev/null and b/release-notes/2023/media/231-boards-01.gif differ diff --git a/release-notes/2023/media/231-pipelines-01.png b/release-notes/2023/media/231-pipelines-01.png new file mode 100644 index 00000000000..3be713fc70c Binary files /dev/null and b/release-notes/2023/media/231-pipelines-01.png differ diff --git a/release-notes/2023/media/231-pipelines-02.png b/release-notes/2023/media/231-pipelines-02.png new file mode 100644 index 00000000000..c3de2b42da6 Binary files /dev/null and b/release-notes/2023/media/231-pipelines-02.png differ diff --git a/release-notes/2023/media/231-pipelines-03.png b/release-notes/2023/media/231-pipelines-03.png new file mode 100644 index 00000000000..f3433a22a37 Binary files /dev/null and b/release-notes/2023/media/231-pipelines-03.png differ diff --git a/release-notes/2023/pipelines/sprint-224-update.md b/release-notes/2023/pipelines/sprint-224-update.md new file mode 100644 index 00000000000..6763eb81e9b --- /dev/null +++ b/release-notes/2023/pipelines/sprint-224-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Pipelines Sprint 224 Update +description: See the Sprint 224 feature updates for Azure Pipelines, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +--- + +# Azure Pipelines - Sprint 224 Update + +## Features + +[!INCLUDE [sprint-224-update-links](../includes/pipelines/sprint-224-update-links.md)] + +[!INCLUDE [sprint-224-update](../includes/pipelines/sprint-224-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/pipelines/sprint-225-update.md b/release-notes/2023/pipelines/sprint-225-update.md new file mode 100644 index 00000000000..ef5b53fe6e8 --- /dev/null +++ b/release-notes/2023/pipelines/sprint-225-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Pipelines Sprint 225 Update +description: See the Sprint 225 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 8/2/2023 +--- + +# Azure Pipelines - Sprint 225 Update + +## Features + +[!INCLUDE [sprint-225-update-links](../includes/pipelines/sprint-225-update-links.md)] + +[!INCLUDE [sprint-225-update](../includes/pipelines/sprint-225-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/pipelines/sprint-226-update.md b/release-notes/2023/pipelines/sprint-226-update.md new file mode 100644 index 00000000000..e18f5745dd6 --- /dev/null +++ b/release-notes/2023/pipelines/sprint-226-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Pipelines Sprint 226 Update +description: See the Sprint 226 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 8/23/2023 +--- + +# Azure Pipelines - Sprint 226 Update + +## Features + +[!INCLUDE [sprint-226-update-links](../includes/pipelines/sprint-226-update-links.md)] + +[!INCLUDE [sprint-226-update](../includes/pipelines/sprint-226-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/pipelines/sprint-227-update.md b/release-notes/2023/pipelines/sprint-227-update.md new file mode 100644 index 00000000000..40d76a4ff3c --- /dev/null +++ b/release-notes/2023/pipelines/sprint-227-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Pipelines Sprint 227 Update +description: See the Sprint 227 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/14/2023 +--- + +# Azure Pipelines - Sprint 227 Update + +## Features + +[!INCLUDE [sprint-227-update-links](../includes/pipelines/sprint-227-update-links.md)] + +[!INCLUDE [sprint-227-update](../includes/pipelines/sprint-227-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/pipelines/sprint-228-update.md b/release-notes/2023/pipelines/sprint-228-update.md new file mode 100644 index 00000000000..adaa7a4df85 --- /dev/null +++ b/release-notes/2023/pipelines/sprint-228-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Pipelines Sprint 228 Update +description: See the Sprint 228 feature updates for Azure Pipelines, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +--- + +# Azure Pipelines - Sprint 228 Update + +## Features + +[!INCLUDE [sprint-228-update-links](../includes/pipelines/sprint-228-update-links.md)] + +[!INCLUDE [sprint-228-update](../includes/pipelines/sprint-228-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/pipelines/sprint-229-update.md b/release-notes/2023/pipelines/sprint-229-update.md new file mode 100644 index 00000000000..d37632944a7 --- /dev/null +++ b/release-notes/2023/pipelines/sprint-229-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 229 update +description: See the Sprint 229 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +--- + +# Azure Pipelines - Sprint 229 Update + +## Features + +[!INCLUDE [sprint-229-update-links](../includes/pipelines/sprint-229-update-links.md)] + +[!INCLUDE [sprint-229-update](../includes/pipelines/sprint-229-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/pipelines/sprint-230-update.md b/release-notes/2023/pipelines/sprint-230-update.md new file mode 100644 index 00000000000..1af4abdb8f4 --- /dev/null +++ b/release-notes/2023/pipelines/sprint-230-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 230 update +description: See the Sprint 230 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +--- + +# Azure Pipelines - Sprint 230 Update + +## Features + +[!INCLUDE [sprint-230-update-links](../includes/pipelines/sprint-230-update-links.md)] + +[!INCLUDE [sprint-230-update](../includes/pipelines/sprint-230-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/pipelines/sprint-231-update.md b/release-notes/2023/pipelines/sprint-231-update.md new file mode 100644 index 00000000000..fd35f48dd9b --- /dev/null +++ b/release-notes/2023/pipelines/sprint-231-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 231 update +description: See the Sprint 231 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 12/5/2023 +--- + +# Azure Pipelines - Sprint 231 Update + +## Features + +[!INCLUDE [sprint-231-update-links](../includes/pipelines/sprint-231-update-links.md)] + +[!INCLUDE [sprint-231-update](../includes/pipelines/sprint-231-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2023/reporting/sprint-229-update.md b/release-notes/2023/reporting/sprint-229-update.md new file mode 100644 index 00000000000..f57309b679c --- /dev/null +++ b/release-notes/2023/reporting/sprint-229-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Reporting Sprint 229 Update +description: See the Sprint 229 feature updates for Reporting, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +--- + +# Reporting - Sprint 229 Update + +## Features + +[!INCLUDE [sprint-229-update-links](../includes/reporting/sprint-229-update-links.md)] + +[!INCLUDE [sprint-229-update](../includes/reporting/sprint-229-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/reporting/sprint-230-update.md b/release-notes/2023/reporting/sprint-230-update.md new file mode 100644 index 00000000000..cf143152ee0 --- /dev/null +++ b/release-notes/2023/reporting/sprint-230-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Reporting Sprint 230 Update +description: See the Sprint 230 feature updates for Reporting, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +--- + +# Reporting - Sprint 230 Update + +## Features + +[!INCLUDE [sprint-230-update-links](../includes/reporting/sprint-230-update-links.md)] + +[!INCLUDE [sprint-230-update](../includes/reporting/sprint-230-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/repos/sprint-224-update.md b/release-notes/2023/repos/sprint-224-update.md new file mode 100644 index 00000000000..7d37eafd62e --- /dev/null +++ b/release-notes/2023/repos/sprint-224-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 224 Update +description: See the Sprint 224 feature updates for Azure Repos, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +--- + +# Azure Repos - Sprint 224 Update + +## Features + +[!INCLUDE [sprint-224-update-links](../includes/repos/sprint-224-update-links.md)] + +[!INCLUDE [sprint-224-update](../includes/repos/sprint-224-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/repos/sprint-226-update.md b/release-notes/2023/repos/sprint-226-update.md new file mode 100644 index 00000000000..a1c4f4a3309 --- /dev/null +++ b/release-notes/2023/repos/sprint-226-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 226 Update +description: See the Sprint 226 feature updates for Azure Repos, including next steps. +author: vijayma +ms.author: vijayma +ms.date: 8/23/2023 +--- + +# Azure Repos - Sprint 226 Update + +## Features + +[!INCLUDE [sprint-226-update-links](../includes/repos/sprint-226-update-links.md)] + +[!INCLUDE [sprint-226-update](../includes/repos/sprint-226-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/repos/sprint-227-update.md b/release-notes/2023/repos/sprint-227-update.md new file mode 100644 index 00000000000..54bf46cb8d4 --- /dev/null +++ b/release-notes/2023/repos/sprint-227-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 227 Update +description: See the Sprint 227 feature updates for Azure Repos, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/14/2023 +--- + +# Azure Repos - Sprint 227 Update + +## Features + +[!INCLUDE [sprint-227-update-links](../includes/repos/sprint-227-update-links.md)] + +[!INCLUDE [sprint-227-update](../includes/repos/sprint-227-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2023/sprint-222-update.md b/release-notes/2023/sprint-222-update.md index 002c91bbe21..8efb58cb722 100644 --- a/release-notes/2023/sprint-222-update.md +++ b/release-notes/2023/sprint-222-update.md @@ -15,6 +15,10 @@ Check out the release notes to learn how you can sign up for the public preview. [!INCLUDE [sprint-222-update-links](includes/general/sprint-222-update-links.md)] +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-222-update-links](includes/ghazdo/sprint-222-update-links.md)] + ### Azure Boards [!INCLUDE [sprint-222-update-links](includes/boards/sprint-222-update-links.md)] @@ -27,6 +31,9 @@ Check out the release notes to learn how you can sign up for the public preview. ## General [!INCLUDE [sprint-222-update](includes/general/sprint-222-update.md)] +## GitHub Advanced Security for Azure DevOps +[!INCLUDE [sprint-222-update](includes/ghazdo/sprint-222-update.md)] + ## Azure Boards [!INCLUDE [sprint-222-update](includes/boards/sprint-222-update.md)] diff --git a/release-notes/2023/sprint-224-update.md b/release-notes/2023/sprint-224-update.md new file mode 100644 index 00000000000..56d9d297786 --- /dev/null +++ b/release-notes/2023/sprint-224-update.md @@ -0,0 +1,70 @@ +--- +title: Dismiss dependency scanning alerts in Advanced Security +author: gloridelmorales +ms.author: glmorale +ms.date: 7/11/2023 +description: Dismiss dependency scanning alerts in Advanced Security. +--- +# Dismiss dependency scanning alerts in Advanced Security + +Dependency scanning in Advanced Security detects the open source components used in your source code and identifies if there are any associated vulnerabilities. Any found vulnerabilities from open source components get flagged as an alert. With this update, you can dismiss dependency scanning alerts in Advanced Security that you believe to be a false positive or acceptable risk. + +In Azure Repos, we changed the default behavior to remove "Edit policies" permission when creating a new branch. + +Check out the release notes to learn more about these features. + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-224-update-links](includes/ghazdo/sprint-224-update-links.md)] + +### Azure Boards + +[!INCLUDE [sprint-224-update-links](includes/boards/sprint-224-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-224-update-links](includes/pipelines/sprint-224-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-224-update-links](includes/repos/sprint-224-update-links.md)] + +## General + +[!INCLUDE [sprint-224-update](includes/general/sprint-224-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-224-update](includes/boards/sprint-224-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-224-update](includes/pipelines/sprint-224-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-224-update](includes/repos/sprint-224-update.md)] + + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2023/sprint-225-update.md b/release-notes/2023/sprint-225-update.md new file mode 100644 index 00000000000..95cca093f9b --- /dev/null +++ b/release-notes/2023/sprint-225-update.md @@ -0,0 +1,55 @@ +--- +title: Increased Azure Pipelines limits for Azure Resource Manager (ARM) integration. +author: ckanyika +ms.author: ckanyika +ms.date: 8/2/2023 +ms.custom: devx-track-arm-template +description: Increased Azure Pipelines limits for Azure Resource Manager (ARM) integration. +--- +# Increased Azure Pipelines limits for Azure Resource Manager (ARM) integration + +In this sprint, we have increased Azure Pipelines size limits to align with the Azure Resource Manager (ARM) maximum limit of 4 MB. We've also included a pre-announcement, for changes coming to the classic build pipelines for new projects and organizations. + +In addition, we're excited to update you on the progress we've made towards making New Boards Hub the default experience for all users. + +Check out the release notes to learn more about these features. + +### Azure Boards + +[!INCLUDE [sprint-225-update-links](includes/boards/sprint-225-update-links.md)] + + +### Azure Pipelines + +[!INCLUDE [sprint-225-update-links](includes/pipelines/sprint-225-update-links.md)] + +## Azure Boards + +[!INCLUDE [sprint-225-update](includes/boards/sprint-225-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-225-update](includes/pipelines/sprint-225-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Screenshot Make a suggestion.](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2023/sprint-226-update.md b/release-notes/2023/sprint-226-update.md new file mode 100644 index 00000000000..ec6d1a73aba --- /dev/null +++ b/release-notes/2023/sprint-226-update.md @@ -0,0 +1,69 @@ +--- +title: Enhanced security management +author: ckanyika +ms.author: ckanyika +ms.date: 8/23/2023 +description: Enhanced security management +--- +# Enhanced security management + +With this update, you now have the option to enable or disable Advanced Security for your entire project or organization. You can also automatically enable Advanced Security for any newly created repositories or projects. + +In Azure Pipelines, we added a centralized control to improve the security of pull requests built from forked GitHub repositories. + +Check out the release notes to learn more about these features. + +### General + +[!INCLUDE [sprint-226-update-links](includes/general/sprint-226-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-226-update-links](includes/pipelines/sprint-226-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-226-update-links](includes/repos/sprint-226-update-links.md)] + +### Azure Artifacts + +[!INCLUDE [sprint-226-update-links](includes/artifacts/sprint-226-update-links.md)] + +## General + +[!INCLUDE [sprint-226-update](includes/general/sprint-226-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-226-update](includes/pipelines/sprint-226-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-226-update](includes/repos/sprint-226-update.md)] + +## Azure Artifacts + +[!INCLUDE [sprint-226-update](includes/artifacts/sprint-226-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Screenshot Make a suggestion.](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2023/sprint-227-update.md b/release-notes/2023/sprint-227-update.md new file mode 100644 index 00000000000..893fd8e8922 --- /dev/null +++ b/release-notes/2023/sprint-227-update.md @@ -0,0 +1,59 @@ +--- +title: Workload identity federation for Azure Pipelines public preview (public preview) +author: ckanyika +ms.author: ckanyika +ms.date: 9/14/2023 +description: Workload identity federation for Azure Pipelines is now in public preview +--- +# Workload identity federation for Azure Pipelines public preview + +We are excited to announce that Workload identity federation for Azure Pipelines is now in public preview! Azure (ARM) service connections have been updated with an additional scheme to support workload identity federation. + +Check out the release notes to learn how you can sign up for the public preview. + +### Azure Boards + +[!INCLUDE [sprint-227-update-links](includes/boards/sprint-227-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-227-update-links](includes/pipelines/sprint-227-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-227-update-links](includes/repos/sprint-227-update-links.md)] + +## Azure Boards + +[!INCLUDE [sprint-227-update](includes/boards/sprint-227-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-227-update](includes/pipelines/sprint-227-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-227-update](includes/repos/sprint-227-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Screenshot Make a suggestion.](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2023/sprint-228-update.md b/release-notes/2023/sprint-228-update.md new file mode 100644 index 00000000000..4aae4c3aa8b --- /dev/null +++ b/release-notes/2023/sprint-228-update.md @@ -0,0 +1,71 @@ +--- +title: GitHub Advanced Security and Managed identity and service principal support for Azure DevOps are now generally available +author: gloridelmorales +ms.author: glmorale +ms.date: 10/4/2023 +description: GitHub Advanced Security and Managed identity and service principal support for Azure DevOps are now generally available. +--- +# GitHub Advanced Security and Managed identity and service principal support for Azure DevOps are now generally available + +We are excited to announce that [GitHub Advanced Security](https://devblogs.microsoft.com/devops/now-generally-available-github-advanced-security-for-azure-devops-is-ready-for-you-to-use/) and Managed identity and service principal support for Azure DevOps are now generally available! + +On GitHub Advanced Security, we've also improved code scanning to include all user-provided inputs in the CodeQL Initialize task. In addition, we expanded CodeQL support to include Swift. + +In Boards, we are releasing Team Automation Rules in private preview. Now, you can configure each backlog level to automate the opening and closing/resolving of work items based on the state(s) of their children. Check out the release notes if you are interested in enrolling in the private preview. + +Head over to the feature list below to learn move about these features. + +### General + +[!INCLUDE [sprint-228-update-links](includes/general/sprint-228-update-links.md)] + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-228-update-links](includes/ghazdo/sprint-228-update-links.md)] + +### Azure Boards + +[!INCLUDE [sprint-228-update-links](includes/boards/sprint-228-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-228-update-links](includes/pipelines/sprint-228-update-links.md)] + +## General + +[!INCLUDE [sprint-228-update](includes/general/sprint-228-update.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-228-update](includes/ghazdo/sprint-228-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-228-update](includes/boards/sprint-228-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-228-update](includes/pipelines/sprint-228-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Screenshot Make a suggestion.](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Rajesh Ramamurthy \ No newline at end of file diff --git a/release-notes/2023/sprint-229-update.md b/release-notes/2023/sprint-229-update.md new file mode 100644 index 00000000000..e4b853f060b --- /dev/null +++ b/release-notes/2023/sprint-229-update.md @@ -0,0 +1,77 @@ +--- +title: Deprecation announcement for NuGet Restore v1 and NuGet Installer v0 pipeline tasks +author: ckanyika +ms.author: ckanyika +ms.date: 10/26/2023 +description: Deprecation announcement for NuGet Restore v1 and NuGet Installer v0 pipeline tasks +--- +# Deprecation announcement for NuGet Restore v1 and NuGet Installer v0 pipeline tasks + +With this update, we are announcing the upcoming deprecation of NuGet Restore v1 and NuGet Installer v0 pipeline tasks. Promptly transition to the NuGetCommand@2 pipeline task to avoid build failure starting on November 27, 2023. + +In Azure Pipelines, we also introduce security improvements for the process of building pull requests from forked GitHub repositories. + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-229-update-links](includes/general/sprint-229-update-links.md)] + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-229-update-links](includes/ghazdo/sprint-229-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-229-update-links](includes/pipelines/sprint-229-update-links.md)] + +### Azure Artifacts + +[!INCLUDE [sprint-229-update-links](includes/artifacts/sprint-229-update-links.md)] + +### Reporting + +[!INCLUDE [sprint-229-update-links](includes/reporting/sprint-229-update-links.md)] + +## General + +[!INCLUDE [sprint-229-update](includes/general/sprint-229-update.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-229-update](includes/ghazdo/sprint-229-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-229-update](includes/pipelines/sprint-229-update.md)] + +## Azure Artifacts + +[!INCLUDE [sprint-229-update](includes/artifacts/sprint-229-update.md)] + +## Reporting + +[!INCLUDE [sprint-229-update](includes/reporting/sprint-229-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Screenshot Make a suggestion.](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica \ No newline at end of file diff --git a/release-notes/2023/sprint-230-update.md b/release-notes/2023/sprint-230-update.md new file mode 100644 index 00000000000..9a1b32b07d1 --- /dev/null +++ b/release-notes/2023/sprint-230-update.md @@ -0,0 +1,69 @@ +--- +title: GitHub Integration - Improved AB# validation +author: ckanyika +ms.author: ckanyika +ms.date: 11/16/2023 +description: GitHub Integration - Improved AB# validation +--- +# GitHub Integration - Improved AB# validation + +With this update, we're excited to offer a private preview of the newest improvements in our Azure Boards + GitHub integration! + +In addition, it is now possible for administrators to bypass running approvals and checks to complete a hotfix in Azure Pipelines. + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-230-update-links](includes/general/sprint-230-update-links.md)] + +### Azure Boards + +[!INCLUDE [sprint-230-update-links](includes/boards/sprint-230-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-230-update-links](includes/pipelines/sprint-230-update-links.md)] + +### Reporting + +[!INCLUDE [sprint-230-update-links](includes/reporting/sprint-230-update-links.md)] + +## General + +[!INCLUDE [sprint-230-update](includes/general/sprint-230-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-230-update](includes/boards/sprint-230-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-230-update](includes/pipelines/sprint-230-update.md)] + +## Reporting + +[!INCLUDE [sprint-230-update](includes/reporting/sprint-230-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Screenshot Make a suggestion.](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica \ No newline at end of file diff --git a/release-notes/2023/sprint-231-update.md b/release-notes/2023/sprint-231-update.md new file mode 100644 index 00000000000..8796c04e112 --- /dev/null +++ b/release-notes/2023/sprint-231-update.md @@ -0,0 +1,52 @@ +--- +title: Switch between HTML and Markdown editor in Azure Boards comments private preview +author: ckanyika +ms.author: ckanyika +ms.date: 12/5/2023 +description: Switch between HTML and Markdown editor in Azure Boards comments private preview +--- +# Switch between HTML and Markdown editor in Azure Boards comments private preview + +With this update, you can now switch between HTML and Markdown editor in Azure Boards comments. + +Check out the release notes to learn more about enrolling in the private preview for this feature. + +### Azure Boards + +[!INCLUDE [sprint-231-update-links](includes/boards/sprint-231-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-231-update-links](includes/pipelines/sprint-231-update-links.md)] + +## Azure Boards + +[!INCLUDE [sprint-231-update](includes/boards/sprint-231-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-231-update](includes/pipelines/sprint-231-update.md)] + + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Screenshot Make a suggestion.](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Dan Hellem diff --git a/release-notes/2024/artifacts/sprint-234-update.md b/release-notes/2024/artifacts/sprint-234-update.md new file mode 100644 index 00000000000..07c938fe686 --- /dev/null +++ b/release-notes/2024/artifacts/sprint-234-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Artifacts Sprint 234 Update +description: See the Sprint 234 feature updates for Azure Artifacts, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +--- + +# Azure Artifacts - Sprint 234 Update + +## Features + +[!INCLUDE [sprint-234-update-links](../includes/artifacts/sprint-234-update-links.md)] + +[!INCLUDE [sprint-234-update](../includes/artifacts/sprint-234-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/artifacts/sprint-246-update.md b/release-notes/2024/artifacts/sprint-246-update.md new file mode 100644 index 00000000000..3e6c2fe6de8 --- /dev/null +++ b/release-notes/2024/artifacts/sprint-246-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Artifacts Sprint 246 Update +description: See the Sprint 246 feature updates for Azure Artifacts, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +--- + +# Azure Artifacts - Sprint 246 Update + +## Features + +[!INCLUDE [sprint-246-update-links](../includes/artifacts/sprint-246-update-links.md)] + +[!INCLUDE [sprint-246-update](../includes/artifacts/sprint-246-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/boards/sprint-233-update.md b/release-notes/2024/boards/sprint-233-update.md new file mode 100644 index 00000000000..580ed7a8625 --- /dev/null +++ b/release-notes/2024/boards/sprint-233-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 233 Update +description: See the Sprint 233 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +--- + +# Azure Boards - Sprint 233 Update + +## Features + +[!INCLUDE [sprint-233-update-links](../includes/boards/sprint-233-update-links.md)] + +[!INCLUDE [sprint-233-update](../includes/boards/sprint-233-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/boards/sprint-234-update.md b/release-notes/2024/boards/sprint-234-update.md new file mode 100644 index 00000000000..b41defc77b8 --- /dev/null +++ b/release-notes/2024/boards/sprint-234-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 234 Update +description: See the Sprint 234 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +--- + +# Azure Boards - Sprint 234 Update + +## Features + +[!INCLUDE [sprint-234-update-links](../includes/boards/sprint-234-update-links.md)] + +[!INCLUDE [sprint-234-update](../includes/boards/sprint-234-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/boards/sprint-235-update.md b/release-notes/2024/boards/sprint-235-update.md new file mode 100644 index 00000000000..d3a991c57ad --- /dev/null +++ b/release-notes/2024/boards/sprint-235-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 235 Update +description: See the Sprint 235 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +--- + +# Azure Boards - Sprint 235 Update + +## Features + +[!INCLUDE [sprint-235-update-links](../includes/boards/sprint-235-update-links.md)] + +[!INCLUDE [sprint-235-update](../includes/boards/sprint-235-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/boards/sprint-237-update.md b/release-notes/2024/boards/sprint-237-update.md new file mode 100644 index 00000000000..24b554f7bdc --- /dev/null +++ b/release-notes/2024/boards/sprint-237-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 237 Update +description: See the Sprint 237 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 4/10/2024 +--- + +# Azure Boards - Sprint 237 Update + +## Features + +[!INCLUDE [sprint-237-update-links](../includes/boards/sprint-237-update-links.md)] + +[!INCLUDE [sprint-237-update](../includes/boards/sprint-237-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/boards/sprint-240-update.md b/release-notes/2024/boards/sprint-240-update.md new file mode 100644 index 00000000000..144416c746f --- /dev/null +++ b/release-notes/2024/boards/sprint-240-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 240 Update +description: See the Sprint 240 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +--- + +# Azure Boards - Sprint 240 Update + +## Features + +[!INCLUDE [sprint-240-update-links](../includes/boards/sprint-240-update-links.md)] + +[!INCLUDE [sprint-240-update](../includes/boards/sprint-240-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/boards/sprint-242-update.md b/release-notes/2024/boards/sprint-242-update.md new file mode 100644 index 00000000000..f3441b200d5 --- /dev/null +++ b/release-notes/2024/boards/sprint-242-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 242 Update +description: See the Sprint 242 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 7/25/2024 +--- + +# Azure Boards - Sprint 242 Update + +## Features + +[!INCLUDE [sprint-242-update-links](../includes/boards/sprint-242-update-links.md)] + +[!INCLUDE [sprint-242-update](../includes/boards/sprint-242-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/boards/sprint-244-update.md b/release-notes/2024/boards/sprint-244-update.md new file mode 100644 index 00000000000..6227e2513fa --- /dev/null +++ b/release-notes/2024/boards/sprint-244-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 244 Update +description: See the Sprint 244 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +--- + +# Azure Boards - Sprint 244 Update + +## Features + +[!INCLUDE [sprint-244-update-links](../includes/boards/sprint-244-update-links.md)] + +[!INCLUDE [sprint-244-update](../includes/boards/sprint-244-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/boards/sprint-245-update.md b/release-notes/2024/boards/sprint-245-update.md new file mode 100644 index 00000000000..362686c6bbe --- /dev/null +++ b/release-notes/2024/boards/sprint-245-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 245 Update +description: See the Sprint 245 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +--- + +# Azure Boards - Sprint 245 Update + +## Features + +[!INCLUDE [sprint-245-update-links](../includes/boards/sprint-245-update-links.md)] + +[!INCLUDE [sprint-245-update](../includes/boards/sprint-245-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/boards/sprint-246-update.md b/release-notes/2024/boards/sprint-246-update.md new file mode 100644 index 00000000000..530bcaf69c8 --- /dev/null +++ b/release-notes/2024/boards/sprint-246-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 246 Update +description: See the Sprint 246 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +--- + +# Azure Boards - Sprint 246 Update + +## Features + +[!INCLUDE [sprint-246-update-links](../includes/boards/sprint-246-update-links.md)] + +[!INCLUDE [sprint-246-update](../includes/boards/sprint-246-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/boards/sprint-247-update.md b/release-notes/2024/boards/sprint-247-update.md new file mode 100644 index 00000000000..3f452b6ad02 --- /dev/null +++ b/release-notes/2024/boards/sprint-247-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 247 Update +description: See the Sprint 247 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +--- + +# Azure Boards - Sprint 247 Update + +## Features + +[!INCLUDE [sprint-247-update-links](../includes/boards/sprint-247-update-links.md)] + +[!INCLUDE [sprint-247-update](../includes/boards/sprint-247-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/general/sprint-232-update.md b/release-notes/2024/general/sprint-232-update.md new file mode 100644 index 00000000000..177300963d0 --- /dev/null +++ b/release-notes/2024/general/sprint-232-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 232 Update +description: See the Sprint 232 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 1/11/2024 +--- + +# Azure DevOps - Sprint 232 Update + +## Features + +[!INCLUDE [sprint-232-update-links](../includes/general/sprint-232-update-links.md)] + +[!INCLUDE [sprint-232-update](../includes/general/sprint-232-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/general/sprint-233-update.md b/release-notes/2024/general/sprint-233-update.md new file mode 100644 index 00000000000..beb48bffd22 --- /dev/null +++ b/release-notes/2024/general/sprint-233-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 233 Update +description: See the Sprint 233 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +--- + +# Azure DevOps - Sprint 233 Update + +## Features + +[!INCLUDE [sprint-233-update-links](../includes/general/sprint-233-update-links.md)] + +[!INCLUDE [sprint-233-update](../includes/general/sprint-233-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/general/sprint-234-update.md b/release-notes/2024/general/sprint-234-update.md new file mode 100644 index 00000000000..bf5dd2dd194 --- /dev/null +++ b/release-notes/2024/general/sprint-234-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 234 update +description: See the Sprint 234 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +--- + +# Azure DevOps - Sprint 234 Update + +## Features + +[!INCLUDE [sprint-234-update-links](../includes/general/sprint-234-update-links.md)] + +[!INCLUDE [sprint-234-update](../includes/general/sprint-234-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/general/sprint-236-update.md b/release-notes/2024/general/sprint-236-update.md new file mode 100644 index 00000000000..1c288bd8182 --- /dev/null +++ b/release-notes/2024/general/sprint-236-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 236 update +description: See the Sprint 236 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 3/26/2024 +--- + +# Azure DevOps - Sprint 236 Update + +## Features + +[!INCLUDE [sprint-236-update-links](../includes/general/sprint-236-update-links.md)] + +[!INCLUDE [sprint-236-update](../includes/general/sprint-236-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/general/sprint-238-update.md b/release-notes/2024/general/sprint-238-update.md new file mode 100644 index 00000000000..a222dc3fcd5 --- /dev/null +++ b/release-notes/2024/general/sprint-238-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 238 Update +description: See the Sprint 238 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 5/2/2024 +--- + +# Azure DevOps - Sprint 238 Update + +## Features + +[!INCLUDE [sprint-238-update-links](../includes/general/sprint-238-update-links.md)] + +[!INCLUDE [sprint-238-update](../includes/general/sprint-238-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/general/sprint-241-update.md b/release-notes/2024/general/sprint-241-update.md new file mode 100644 index 00000000000..98fef3ccff2 --- /dev/null +++ b/release-notes/2024/general/sprint-241-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 241 Update +description: See the Sprint 241 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 7/3/2024 +--- + +# Azure DevOps - Sprint 241 Update + +## Features + +[!INCLUDE [sprint-241-update-links](../includes/general/sprint-241-update-links.md)] + +[!INCLUDE [sprint-241-update](../includes/general/sprint-241-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/general/sprint-246-update.md b/release-notes/2024/general/sprint-246-update.md new file mode 100644 index 00000000000..b3ec61adbae --- /dev/null +++ b/release-notes/2024/general/sprint-246-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 246 Update +description: See the Sprint 246 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +--- + +# Azure DevOps - Sprint 246 Update + +## Features + +[!INCLUDE [sprint-246-update-links](../includes/general/sprint-246-update-links.md)] + +[!INCLUDE [sprint-246-update](../includes/general/sprint-246-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-233-update.md b/release-notes/2024/ghazdo/sprint-233-update.md new file mode 100644 index 00000000000..0963b298d09 --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-233-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 233 Update +description: See the Sprint 233 feature updates for Azure DevOps, including next steps. +author: gloridelmorales +ms.author: glmorale +ms.date: 1/19/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 233 Update + +## Features + +[!INCLUDE [sprint-233-update-links](../includes/ghazdo/sprint-233-update-links.md)] + +[!INCLUDE [sprint-233-update](../includes/ghazdo/sprint-233-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-234-update.md b/release-notes/2024/ghazdo/sprint-234-update.md new file mode 100644 index 00000000000..60db2755362 --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-234-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 234 Update +description: See the Sprint 234 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: laurajiang +ms.author: laurajiang +ms.date: 2/9/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 234 Update + +## Features + +[!INCLUDE [sprint-234-update-links](../includes/ghazdo/sprint-234-update-links.md)] + +[!INCLUDE [sprint-234-update](../includes/ghazdo/sprint-234-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-237-update.md b/release-notes/2024/ghazdo/sprint-237-update.md new file mode 100644 index 00000000000..72523dbfa4b --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-237-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 237 Update +description: See the Sprint 237 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 4/10/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 237 Update + +## Features + +[!INCLUDE [sprint-237-update-links](../includes/ghazdo/sprint-237-update-links.md)] + +[!INCLUDE [sprint-237-update](../includes/ghazdo/sprint-237-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-238-update.md b/release-notes/2024/ghazdo/sprint-238-update.md new file mode 100644 index 00000000000..af1f28003cb --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-238-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 238 Update +description: See the Sprint 238 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 5/2/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 238 Update + +## Features + +[!INCLUDE [sprint-238-update-links](../includes/ghazdo/sprint-238-update-links.md)] + +[!INCLUDE [sprint-238-update](../includes/ghazdo/sprint-238-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-240-update.md b/release-notes/2024/ghazdo/sprint-240-update.md new file mode 100644 index 00000000000..366066778e7 --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-240-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 240 Update +description: See the Sprint 240 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 240 Update + +## Features + +[!INCLUDE [sprint-240-update-links](../includes/ghazdo/sprint-240-update-links.md)] + +[!INCLUDE [sprint-240-update](../includes/ghazdo/sprint-240-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-241-update.md b/release-notes/2024/ghazdo/sprint-241-update.md new file mode 100644 index 00000000000..ba76751d81c --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-241-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 241 Update +description: See the Sprint 241 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 7/3/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 241 Update + +## Features + +[!INCLUDE [sprint-241-update-links](../includes/ghazdo/sprint-241-update-links.md)] + +[!INCLUDE [sprint-241-update](../includes/ghazdo/sprint-241-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-243-update.md b/release-notes/2024/ghazdo/sprint-243-update.md new file mode 100644 index 00000000000..986bc8fce40 --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-243-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 243 Update +description: See the Sprint 243 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 8/13/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 243 Update + +## Features + +[!INCLUDE [sprint-243-update-links](../includes/ghazdo/sprint-243-update-links.md)] + +[!INCLUDE [sprint-243-update](../includes/ghazdo/sprint-243-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-244-update.md b/release-notes/2024/ghazdo/sprint-244-update.md new file mode 100644 index 00000000000..da62215f7b6 --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-244-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 244 Update +description: See the Sprint 244 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 244 Update + +## Features + +[!INCLUDE [sprint-244-update-links](../includes/ghazdo/sprint-244-update-links.md)] + +[!INCLUDE [sprint-244-update](../includes/ghazdo/sprint-244-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-245-update.md b/release-notes/2024/ghazdo/sprint-245-update.md new file mode 100644 index 00000000000..dc1279fb295 --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-245-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 245 Update +description: See the Sprint 245 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 245 Update + +## Features + +[!INCLUDE [sprint-245-update-links](../includes/ghazdo/sprint-245-update-links.md)] + +[!INCLUDE [sprint-245-update](../includes/ghazdo/sprint-245-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-246-update.md b/release-notes/2024/ghazdo/sprint-246-update.md new file mode 100644 index 00000000000..1735d662024 --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-246-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 246 Update +description: See the Sprint 246 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 246 Update + +## Features + +[!INCLUDE [sprint-246-update-links](../includes/ghazdo/sprint-246-update-links.md)] + +[!INCLUDE [sprint-246-update](../includes/ghazdo/sprint-246-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/ghazdo/sprint-247-update.md b/release-notes/2024/ghazdo/sprint-247-update.md new file mode 100644 index 00000000000..c57ab6e1855 --- /dev/null +++ b/release-notes/2024/ghazdo/sprint-247-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 247 Update +description: See the Sprint 247 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 247 Update + +## Features + +[!INCLUDE [sprint-247-update-links](../includes/ghazdo/sprint-247-update-links.md)] + +[!INCLUDE [sprint-247-update](../includes/ghazdo/sprint-247-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/includes/artifacts/sprint-234-update-links.md b/release-notes/2024/includes/artifacts/sprint-234-update-links.md new file mode 100644 index 00000000000..411f309f463 --- /dev/null +++ b/release-notes/2024/includes/artifacts/sprint-234-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +ms.topic: include +--- + +- [Support for Rust Crates is generally available](#support-for-rust-crates-is-generally-available) +- [Azure Artifacts support for npm audit ](#azure-artifacts-support-for-npm-audit) \ No newline at end of file diff --git a/release-notes/2024/includes/artifacts/sprint-234-update.md b/release-notes/2024/includes/artifacts/sprint-234-update.md new file mode 100644 index 00000000000..e99852efd09 --- /dev/null +++ b/release-notes/2024/includes/artifacts/sprint-234-update.md @@ -0,0 +1,14 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +ms.topic: include +--- + +### Support for Rust Crates is generally available + +Beginning February 16, 2024, Rust Crates support will become a generally available feature for Azure Artifacts. Billing meters will be activated, using the same pricing model that applies to the other supported protocols. + +### Azure Artifacts support for npm audit + +Azure Artifacts now supports `npm audit` and `npm audit fix` commands. This feature enables users to analyze and fix their project's vulnerabilities by automatically updating insecure package versions. To learn more visit, [Use npm audit to detect and fix package vulnerabilities](/azure/devops/artifacts/npm/npm-audit?view=azure-devops&tabs=classic&preserve-view=true). \ No newline at end of file diff --git a/release-notes/2024/includes/artifacts/sprint-246-update-links.md b/release-notes/2024/includes/artifacts/sprint-246-update-links.md new file mode 100644 index 00000000000..15b72059e7e --- /dev/null +++ b/release-notes/2024/includes/artifacts/sprint-246-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +- [Authentication to Azure Artifacts using a public feed and Cargo](#authentication-to-azure-artifacts-using-a-public-feed-and-cargo) diff --git a/release-notes/2024/includes/artifacts/sprint-246-update.md b/release-notes/2024/includes/artifacts/sprint-246-update.md new file mode 100644 index 00000000000..ac6ac2b7617 --- /dev/null +++ b/release-notes/2024/includes/artifacts/sprint-246-update.md @@ -0,0 +1,15 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +### Authentication to Azure Artifacts using a public feed and Cargo + +Due to a limitation with the Cargo client, authentication was all-or-nothing. For private feeds, authentication would be sent, but for [public feeds](/azure/devops/artifacts/tutorials/share-packages-publicly?view=azure-devops&tabs=nuget), which need to allow for anonymous users, no authentication would be sent, even if it was available or needed. + +Now, authenticated users can connect to a public Azure Artifacts feed, just as they would a private feed. If you or your pipeline agent have [permission to save packages from upstream sources](/azure/devops/artifacts/feeds/feed-permissions?view=azure-devops#permissions-table), you can access packages from crates.io through the feed. This change gives control of what packages can come into a feed back in the hands of feed administrators. Once packages are brought into the feed from an upstream source, anonymous users will have access to them. + +To ensure authentication, append `~force-auth` to the feed name in your registry URL. You can find out more details through [our public documentation](/azure/devops/artifacts/cargo/cargo-upstream-source?view=azure-devops&tabs=publicfeed%2CWindows%2CPowerShell#connect-to-your-feed). + diff --git a/release-notes/2024/includes/boards/sprint-233-update-links.md b/release-notes/2024/includes/boards/sprint-233-update-links.md new file mode 100644 index 00000000000..ca680f3e6e3 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-233-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +ms.topic: include +--- + +- [GitHub Integration - Improved AB# validation is generally available](#github-integration---improved-ab-validation-is-generally-available) +- [Team Automation rules is generally available](#team-automation-rules-is-generally-available) \ No newline at end of file diff --git a/release-notes/2024/includes/boards/sprint-233-update.md b/release-notes/2024/includes/boards/sprint-233-update.md new file mode 100644 index 00000000000..0bafb33222f --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-233-update.md @@ -0,0 +1,46 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +ms.topic: include +--- + +### GitHub Integration - Improved AB# validation is generally available + +A few sprints ago we announced the preview for [improved AB# validation](/azure/devops/release-notes/2023/sprint-230-update#github-integration---improved-ab-validation-private-preview&preserve-view=true) by the Azure Boards App in GitHub. We've enhanced the app to better notify users about the validity of work item links, helping them spot and fix any issues before merging a Pull Request. + +After several weeks of testing and feedback, this feature is now available to all users using the GitHub + Azure Boards integration. + +> [!div class="mx-imgBorder"] +> ![Screenshots of improved validation.](../../media/233-boards-01.png "Screenshots of improved validation.") + +This is the first of several features we're making to improve the current integration. Be sure to check out the other [Azure Boards + GitHub integration features](/azure/devops/release-notes/features-timeline#improved-boards--github-integration&preserve-view=true) we have planned on the public roadmap. + +> [!IMPORTANT] +> As of 8/6/2024, the Azure Boards App in GitHub will no longer validate AB# links. You can still use the `AB#` syntax to link work items in your GitHub pull requests, commits, and issues as you could prior to this change. + +### Team Automation Rules is generally available + +We're happy to announce the release of this feature to all customers of Azure DevOps Service. + +> [!NOTE] +> This feature will roll out over the next two to three weeks. It may not be available to your organization until early February 2024. + +You can now configure each backlog level to automate the opening and closing (or resolving) of work items based on the state of the child items. There are two main scenarios we're attempting to solve. + +- When a single child item is activated, then activate the parent. +- When all child items are closed, then close the parent (or resolve it). + +To enable these settings, click on the backlog level configuration for your team. Then go to the **Automation > Rules tab** to see the two different rules you can apply to your backlog. Each backlog level (requirements, features, epics) can be configured differently depending on how your team wants to work. + +> [!div class="mx-imgBorder"] +> ![Screenshots of team settings.](../../media/233-boards-02.png "Screenshots of team settings.") + +For example, when any child Task is set to Active, make the parent User Story active. Then, when all Tasks are completed, set the User Story to Closed. + +> [!div class="mx-imgBorder"] +> ![Gif to demo closing user story.](../../media/233-boards-01.gif "gif to demo closing user story") + +You can learn more about this feature by reviewing [the documentation](/azure/devops/boards/backlogs/automate-work-item-state-transitions?view=azure-devops&preserve-view=true) and [this blog post](https://devblogs.microsoft.com/devops/team-backlog-automation-rules-private-preview/). + +This feature was prioritized based on [this Developer Community suggestion ticket](https://developercommunity.visualstudio.com/t/update-automatically-user-story-state-according-to/376465). diff --git a/release-notes/2024/includes/boards/sprint-234-update-links.md b/release-notes/2024/includes/boards/sprint-234-update-links.md new file mode 100644 index 00000000000..2d8c5f51086 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-234-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +ms.topic: include +--- + +- [Add link to GitHub commit or pull request (preview)](#add-link-to-github-commit-or-pull-request-preview) +- [New Boards Hub improvements](#new-boards-hub-improvements) +- [Development and Deployment controls](#development-and-deployment-controls) diff --git a/release-notes/2024/includes/boards/sprint-234-update.md b/release-notes/2024/includes/boards/sprint-234-update.md new file mode 100644 index 00000000000..776bbd90fac --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-234-update.md @@ -0,0 +1,48 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +ms.topic: include +--- + +### Add link to GitHub commit or pull request (preview) + +You have two options to connect your work item with a GitHub pull request or commit. You can either use the AB# syntax in the pull request, or you can link it directly from the work item. Today, the process involves copying the URL of the GitHub pull request and pasting it when adding a link. This requires opening multiple windows and switching between GitHub and Azure DevOps. + +In this sprint, we're excited to announce an enhanced experience by enabling search functionality when linking to a GitHub pull request or commit. Search and select the desired repository and drill down to find and link to the specific pull request or commit. No more need for multiple window changes and copy/paste (although you still have that option). + +> [!div class="mx-imgBorder"] +> ![Gif to demo add link.](../../media/234-boards-02.gif "gif to demo add link") + +> [!NOTE] +>This feature is only available in the [New Boards Hub preview](/azure/devops/release-notes/2022/sprint-202-update#new-boards-hubs-now-available-in-public-preview). + +If you're interested in getting access to this feature, send us an [email directly](mailto:dahellem@microsoft.com) along with your organization name ***(dev.azure.com/{organization name})***. + +### New Boards Hub Improvements + +With this release, we have introduce a range of enhancements to the New Boards Hub preview, focusing on accessibility and page reflow. + +Here's an example of the page reflow changes that are adaptive up to 400% zoom. + +> [!div class="mx-imgBorder"] +> ![Gif to demo new boards hub improvements.](../../media/234-boards-01.gif "gif to demo new boards hub improvements") + +Furthermore, we have rolled out performance enhancements across the work item form, boards, and backlogs pages. With these changes, you can expect New Boards to match the performance standards set with Old Boards. + +### Development and Deployment Controls + +We now remove the Development and/or Deployment controls from the work item, depending on how your project is configured. For example, you might configure your project settings to turn off Repos and/or Pipelines. + +> [!div class="mx-imgBorder"] +> ![Screenshots of DevOps services.](../../media/234-boards-01.png "Screenshots of DevOps services.") + +When you go to the work item, the corresponding Development and Deployment controls will be hidden from the form. + +> [!div class="mx-imgBorder"] +> ![Screenshots of related work.](../../media/234-boards-02.png "Screenshots of related work.") + +If you decide to [connect a GitHub repo to Azure Boards](/azure/devops/boards/github/?view=azure-devops&preserve-view=true ), the Development control for GitHub repos will be displayed. + +> [!div class="mx-imgBorder"] +> ![Screenshots of development control .](../../media/234-boards-03.png "Screenshots of development control .") diff --git a/release-notes/2024/includes/boards/sprint-235-update-links.md b/release-notes/2024/includes/boards/sprint-235-update-links.md new file mode 100644 index 00000000000..703b7829066 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-235-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +ms.topic: include +--- + +- [Show GitHub pull request details (preview)](#show-github-pull-request-details-preview) diff --git a/release-notes/2024/includes/boards/sprint-235-update.md b/release-notes/2024/includes/boards/sprint-235-update.md new file mode 100644 index 00000000000..ec3db274a43 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-235-update.md @@ -0,0 +1,15 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +ms.topic: include +--- + +### Show GitHub pull request details (preview) + +In the existing integration, we only show the open and closed status of a GitHub pull request on the work item. To capture more details of the activities that happen between these states, we have designed a new experience that provides more information. We now display if the pull request is in draft mode, needs a review, or has status checks running. All this, without having to open the pull request directly. + +> [!div class="mx-imgBorder"] +> ![Gif to demo GitHub pull request details.](../../media/235-boards-01.gif "gif to GitHub pull request details") + +If you're interested in enrolling in the private preview, reach out directly [via email](mailto:dahellem@microsoft.com), and kindly include your organization name (dev.azure.com/{organization}). \ No newline at end of file diff --git a/release-notes/2024/includes/boards/sprint-237-update-links.md b/release-notes/2024/includes/boards/sprint-237-update-links.md new file mode 100644 index 00000000000..0df198988d5 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-237-update-links.md @@ -0,0 +1,11 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/10/2024 +ms.topic: include +--- + +- [New Boards Hub on by default](#new-boards-hub-on-by-default) +- [Add link to GitHub commit or pull request is generally available](#add-link-to-github-commit-or-pull-request-is-generally-available) +- [AB# links on GitHub pull requests (preview) ](#ab-links-on-github-pull-requests-preview) +- [Connect to GitHub repository search improvements (preview)](#connect-to-github-repository-search-improvements-preview) \ No newline at end of file diff --git a/release-notes/2024/includes/boards/sprint-237-update.md b/release-notes/2024/includes/boards/sprint-237-update.md new file mode 100644 index 00000000000..c691c92684d --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-237-update.md @@ -0,0 +1,43 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/10/2024 +ms.topic: include +--- + +### New Boards Hub on by default + +If you’ve been keeping up with the progress of New Boards Hub, you’re probably aware that the preview has been active for quite some time now. In fact, we officially [announced the preview](https://devblogs.microsoft.com/devops/new-boards-hub-public-preview/) of New Boards Hub a little over two years ago. + +Today, we’re happy to announce the final stage of our journey. We're beginning the process of making New Boards Hub the default experience for all of our customers. This happens in two waves, with the first starting in the middle of April. The rollout process for each wave spans several weeks, as we gradually roll out to a different set of customers every other day. + +For more information, please see our [latest blog post here](https://devblogs.microsoft.com/devops/new-boards-hub-on-as-default/). + +### Add link to GitHub commit or pull request is generally available + +After several weeks [in preview](/azure/devops/release-notes/2024/sprint-234-update#azure-boards-1), we're excited to announce an enhanced experience for linking work items to GitHub. Search and select the desired repository and drill down to find and link to the specific pull request or commit. No more need for multiple window changes and copy/paste (although you still have that option). + +> [!div class="mx-imgBorder"] +> ![Gif to demo Add link improvements.](../../media/237-boards-01.gif "gif to Add link improvements") + +> [!NOTE] +> This feature is only available in the [New Boards Hub preview](/azure/devops/release-notes/2022/sprint-202-update#new-boards-hubs-now-available-in-public-preview). + + +### AB# links on GitHub pull requests (preview) + +As part of our ongoing enhancements to the Azure Boards + GitHub integration, we're previewing a feature that improves experience with AB# links. With this update, your AB# links will now appear directly in the Development section of the GitHub pull request. This means you can view the linked work items without the need to navigate through description or comments, resulting in easier access to those AB# links. + +> [!div class="mx-imgBorder"] +> ![Screenshots of AB# links.](../../media/237-boards-01.png "Screenshots of AB# links.") + +These links will only be available when you use AB# in the pull the request description. They won't show up if you link directly from the pull request from the work item. Removing the AB# link from the description will also remove it from the Development control. + +If you're interested in participating in the preview, please reach out to us directly [via email](mailto:dahellem@microsoft.com). Make sure to include your GitHub organization name (github.com/{organization name}). + + +### Connect to GitHub repository search improvements (preview) + +Previously, [connecting](/azure/devops/boards/github/connect-to-github) an Azure DevOps project to a GitHub organization with thousands of repositories was challenging. Customers with that many GitHub repositories can encounter timeout errors or long wait times. Today we're announcing a preview that unblocks large GitHub organizations. You can now search and select across thousands of repositories without the risk of timeout issues. + +We're happy to enable to this feature upon request. If you're interested, please [send us](mailto:dahellem@microsoft.com) your Azure DevOps organization name (dev.azure.com/{organization}). \ No newline at end of file diff --git a/release-notes/2024/includes/boards/sprint-240-update-links.md b/release-notes/2024/includes/boards/sprint-240-update-links.md new file mode 100644 index 00000000000..edf9c5ad6c2 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-240-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +ms.topic: include +--- + +- [Change for deleting area and iteration paths](#change-for-deleting-area-and-iteration-paths) \ No newline at end of file diff --git a/release-notes/2024/includes/boards/sprint-240-update.md b/release-notes/2024/includes/boards/sprint-240-update.md new file mode 100644 index 00000000000..32e6b6992b3 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-240-update.md @@ -0,0 +1,13 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +ms.topic: include +--- + +### Change for deleting area and iteration paths + +Deleting an area or iteration path can be disruptive. It can move work items to a new path and may cause teams to lose access to their boards and backlogs. Despite warnings and prompts, paths are sometimes deleted without fully understanding the consequences. To address this, we changed the behavior: Area and Iteration paths can now only be deleted if they are no longer used by any work items. + +> [!div class="mx-imgBorder"] +> ![Screenshots of delete area.](../../media/240-boards-02.png "Screenshot of delete area path.") \ No newline at end of file diff --git a/release-notes/2024/includes/boards/sprint-242-update-links.md b/release-notes/2024/includes/boards/sprint-242-update-links.md new file mode 100644 index 00000000000..bca5a2f9485 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-242-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 7/25/2024 +ms.topic: include +--- + +- [Connect to GitHub repository search improvements](#connect-to-github-repository-search-improvements) +- [Create GitHub branch from work item](#create-github-branch-from-work-item) \ No newline at end of file diff --git a/release-notes/2024/includes/boards/sprint-242-update.md b/release-notes/2024/includes/boards/sprint-242-update.md new file mode 100644 index 00000000000..505b7fb1360 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-242-update.md @@ -0,0 +1,24 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 7/25/2024 +ms.topic: include +--- + +### Connect to GitHub repository search improvements + +We're excited to announce an improved process for connecting an Azure DevOps project to a GitHub organization, especially beneficial for those with thousands of repositories. Previously, you might have faced challenges like timeout errors and long wait times. Our latest update optimizes the search and selection experience, eliminating the risk of timeout errors and making the connection process smoother and more efficient. + +> [!div class="mx-imgBorder"] +> ![Screenshot of add GitHub repositories.](../../media/242-boards-01.png "Screenshot of add github repositories.") + +### Create GitHub branch from work item + +Now, you can create a GitHub branch directly from a work item within Azure DevOps. The "New GitHub Branch" link is available whenever a [GitHub connection is configured](/azure/devops/boards/github/connect-to-github) for your project. This link is available in all work item context menus, including the work item form, card, backlog, and queries. +To create a new branch, enter the branch name and select the desired repository and base branch. + +> [!div class="mx-imgBorder"] +> ![Gif to demo create GitHub branch from work item.](../../media/242-boards-01.gif "gif to create GitHub branch from work item") + +> [!NOTE] +>This feature is only available in the [New Boards Hub preview](/azure/devops/release-notes/2022/sprint-202-update#new-boards-hubs-now-available-in-public-preview). diff --git a/release-notes/2024/includes/boards/sprint-244-update-links.md b/release-notes/2024/includes/boards/sprint-244-update-links.md new file mode 100644 index 00000000000..36e95081c22 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-244-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +ms.topic: include +--- + +- [Area and iteration level fields](#area-and-iteration-level-fields) diff --git a/release-notes/2024/includes/boards/sprint-244-update.md b/release-notes/2024/includes/boards/sprint-244-update.md new file mode 100644 index 00000000000..c9c6e8e4355 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-244-update.md @@ -0,0 +1,16 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +ms.topic: include +--- + +### Area and iteration level fields + +Area and iteration level fields have long been a valuable part of the product, allowing users to query or display results based on the specific levels at which they are defined: + +*(Root) Level 1 / Level 2 / Level 3 / etc.* + +Previously, these fields were only accessible to a select few organizations. We are pleased to announce that area and iteration level fields will now be available to all Azure DevOps organizations. These fields can be used in queries and displayed as backlog columns. However, please note that they are not supported in settings such as style rules, swim lane rules, card fields, and delivery plan fields. + +This feature is only available in the [New Boards Hub preview](/azure/devops/release-notes/2022/sprint-202-update#new-boards-hubs-now-available-in-public-preview). diff --git a/release-notes/2024/includes/boards/sprint-245-update-links.md b/release-notes/2024/includes/boards/sprint-245-update-links.md new file mode 100644 index 00000000000..d6f71198ea7 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-245-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +ms.topic: include +--- + +- [AB# links on GitHub pull requests](#ab-links-on-github-pull-requests) +- [REST API support for connecting GitHub repositories](#rest-api-support-for-connecting-github-repositories) +- [Permanently delete attachments](#permanently-delete-attachments) diff --git a/release-notes/2024/includes/boards/sprint-245-update.md b/release-notes/2024/includes/boards/sprint-245-update.md new file mode 100644 index 00000000000..db9293c7fdb --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-245-update.md @@ -0,0 +1,41 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +ms.topic: include +--- + +### AB# links on GitHub pull requests + +As part of our ongoing enhancements to the Azure Boards + GitHub integration, we’re excited to introduce a new feature that streamlines how AB# links are displayed. With this update, AB# links now appear directly in the Development section of GitHub pull requests, making it easier to access linked work items without searching through descriptions or comments. + +> [!div class="mx-imgBorder"] +> ![Screenshot of GitHub pull requests.](../../media/245-boards-01.png "Screenshot of GitHub pull requests.") + +These links will only appear when AB# is included in the pull request description. If you link directly from a work item, they won’t be displayed in the Development section. Additionally, removing the AB# link from the description removes it from the Development control. + +### REST API support for connecting GitHub repositories + +We're introducing new REST API endpoints that enable you to automate the addition and removal of GitHub repositories in your Azure DevOps Projects. Additionally, we increased the repository limit per connection from 500 to 2,000 when using these endpoints. + +These endpoints include: + +* [Listing current connections](/rest/api/azure/devops/wit/github-connections/get-github-connections) +* [Listing connected repositories](/rest/api/azure/devops/wit/github-connections/get-github-connection-repositories) +* [Adding and removing repositories](/rest/api/azure/devops/wit/github-connections/update) + +We have also [provided sample code](https://github.com/danhellem/github-boards-connection-sample) to help you get started. + +### Permanently delete attachments + +In some cases, simply removing an attachment from a work item may not fully resolve security risks, especially if the file is flagged as malicious. Shared links to the attachment could still be accessible across other work items, comments, or external channels. To address this, we added a feature that allows users with "Permanently delete work items" permissions to permanently remove attachments. + +> [!div class="mx-imgBorder"] +> [![SScreenshot of permanently delete work item attachments.](../../media/245-boards-02.png "Screenshot of permanently delete work item attachments")](../../media/245-boards-02.png#lightbox) + +This action can be performed from the **Attachments** tab on the work item form, under a new section called **"Deleted Attachments"**. This section is visible only to users with the necessary permissions to permanently delete work items. + +Once an attachment is permanently deleted, all associated links return a "File attachment does not exist" error. + +> [!NOTE] +> This feature is only available in the New Boards Hub. diff --git a/release-notes/2024/includes/boards/sprint-246-update-links.md b/release-notes/2024/includes/boards/sprint-246-update-links.md new file mode 100644 index 00000000000..b380ef1b4f4 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-246-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +- [Enhanced tag management on work item form](#enhanced-tag-management-on-work-item-form) +- [Improved image support in work item comments](#improved-image-support-in-work-item-comments) +- [GitHub pull request insights](#github-pull-request-insights) diff --git a/release-notes/2024/includes/boards/sprint-246-update.md b/release-notes/2024/includes/boards/sprint-246-update.md new file mode 100644 index 00000000000..4188a062f79 --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-246-update.md @@ -0,0 +1,26 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +### Enhanced tag management on work item form + +Tag management in Azure Boards has been enhanced to provide a more streamlined experience. Deleted tags no longer appear in the suggested list on work item forms, ensuring that only active tags are displayed. + +### Improved image support in work item comments + +We’ve improved our support for pasting images into work item comments. You can now paste images directly from sources like Microsoft Teams, emails, and Word documents into the discussion section of a work item + +### GitHub pull request insights + +We've enhanced the integration between GitHub pull requests and Azure Boards. In addition to showing open and closed statuses, you can now see if a pull request is in draft mode, needs review, and Checks status. All without needing to open the pull request. + +> [!div class="mx-imgBorder"] +> ![Gif to demo enhanced GitHub pull request insights.](../../media/246-boards-01.gif "gif to enhanced GitHub pull request insights") + +To enable this feature, make sure you go the Boards App in GitHub to accept the requested updated permissions for read and write access to Checks. + +> [!div class="mx-imgBorder"] +> [![SScreenshot of updated permissions.](../../media/246-boards-01.png "Screenshot of updated permissions")](../../media/246-boards-01.png#lightbox) diff --git a/release-notes/2024/includes/boards/sprint-247-update-links.md b/release-notes/2024/includes/boards/sprint-247-update-links.md new file mode 100644 index 00000000000..1abe125a9ae --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-247-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +ms.topic: include +--- + +- [New REST API limit on work item comments](#new-rest-api-limit-on-work-item-comments) diff --git a/release-notes/2024/includes/boards/sprint-247-update.md b/release-notes/2024/includes/boards/sprint-247-update.md new file mode 100644 index 00000000000..88bd2aeb40a --- /dev/null +++ b/release-notes/2024/includes/boards/sprint-247-update.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +ms.topic: include +--- + +### New REST API limit on work item comments + +To enhance security, a new limit has been set on the number of comments that can be added to work items through the REST API. Each work item now supports a maximum of 1,000 comments via the API. This restriction applies solely to the REST API, and users can still manually add comments through the web interface, even beyond the 1,000-comment threshold. \ No newline at end of file diff --git a/release-notes/2024/includes/general/sprint-232-update-links.md b/release-notes/2024/includes/general/sprint-232-update-links.md new file mode 100644 index 00000000000..890ed76328e --- /dev/null +++ b/release-notes/2024/includes/general/sprint-232-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/11/2024 +ms.topic: include +--- + +- [Select a geography when creating a new Azure DevOps organization](#select-a-geography-when-creating-a-new-azure-devops-organization) +- [Removed Visual Studio Subscriber option from group rules](#removed-visual-studio-subscriber-option-from-group-rules) \ No newline at end of file diff --git a/release-notes/2024/includes/general/sprint-232-update.md b/release-notes/2024/includes/general/sprint-232-update.md new file mode 100644 index 00000000000..3a327de8b8b --- /dev/null +++ b/release-notes/2024/includes/general/sprint-232-update.md @@ -0,0 +1,23 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/11/2024 +ms.topic: include +--- + + +### Select a geography when creating a new Azure DevOps organization + +When creating a new organization in Azure DevOps, you can now select a geography, instead of a region. By default, the system selects your nearest geography, but you can opt for a different one based on your team's location or due to specific data sovereignty requirements. You can view your geography in the overview section of organization settings. + +> [!div class="mx-imgBorder"] +> ![Screenshot of Select a geography.](../../media/232-general-01.png "Screenshot of Select a geography") + +For more information, see [Find or change your organization geography](/azure/devops/organizations/accounts/change-organization-location?view=azure-devops&preserve-view=true). + +### Removed Visual Studio Subscriber option from group rules + +Visual Studio subscriptions that a user has assigned to them have always taken precedence over group rules when the user logs in. To avoid confusion we removed the Visual Studio Subscriber option from group rules. To learn more visit, [How do Visual Studio Subscriptions work with group rules ?](/azure/devops/organizations/accounts/assign-access-levels-by-group-membership#q-how-do-visual-studio-subscriptions-work-with-group-rules) + +> [!div class="mx-imgBorder"] +> ![Screenshot of Removed Visual Studio Subscriber option.](../../media/232-general-03.png "Screenshot of Removed Visual Studio Subscriber option") diff --git a/release-notes/2024/includes/general/sprint-233-update-links.md b/release-notes/2024/includes/general/sprint-233-update-links.md new file mode 100644 index 00000000000..8de9ef028d8 --- /dev/null +++ b/release-notes/2024/includes/general/sprint-233-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +ms.topic: include +--- + +- [Custom CodeQL queries now supported in GitHub Advanced Security for Azure DevOps](#custom-codeql-queries-now-supported-in-github-advanced-security-for-azure-devops) \ No newline at end of file diff --git a/release-notes/2024/includes/general/sprint-233-update.md b/release-notes/2024/includes/general/sprint-233-update.md new file mode 100644 index 00000000000..c17fd7fe69b --- /dev/null +++ b/release-notes/2024/includes/general/sprint-233-update.md @@ -0,0 +1,14 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +ms.topic: include +--- + +### Custom CodeQL queries now supported in GitHub Advanced Security for Azure DevOps + +We're thrilled to announce the introduction of support for custom CodeQL queries in Code scanning! This enables you to craft your own queries tailored to identify issues specific to your codebase. Now, you can create and publish packs containing custom queries, execute these queries in your pipelines, and customize the detection of vulnerabilities that are pertinent to your organization. + +For more information on utilizing custom queries for code scanning in GitHub Advanced Security for Azure DevOps, see to [Code scanning alerts for GitHub Advanced Security for Azure DevOps](/azure/devops/repos/security/github-advanced-security-code-scanning?view=azure-devops&branch=main#code-scanning-alerts&preserve-view=true). + +We value your input. If you have any questions or feedback, we encourage you to engage with our community at [Developer Community](https://developercommunity.visualstudio.com/home). diff --git a/release-notes/2024/includes/general/sprint-234-update-links.md b/release-notes/2024/includes/general/sprint-234-update-links.md new file mode 100644 index 00000000000..8096aa29902 --- /dev/null +++ b/release-notes/2024/includes/general/sprint-234-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +ms.topic: include +--- + +- [Final notice of alternate credentials deprecation](#final-notice-of-alternate-credentials-deprecation) +- [Azure Devops OAuth self-service secret rotation](#azure-devops-oauth-self-service-secret-rotation) diff --git a/release-notes/2024/includes/general/sprint-234-update.md b/release-notes/2024/includes/general/sprint-234-update.md new file mode 100644 index 00000000000..bb7d3f8a259 --- /dev/null +++ b/release-notes/2024/includes/general/sprint-234-update.md @@ -0,0 +1,19 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +ms.topic: include +--- + +### Final notice of alternate credentials deprecation + +Alternate credentials were [formally deprecated in March 2020](https://devblogs.microsoft.com/devops/azure-devops-will-no-longer-support-alternate-credentials-authentication/), but some existing users were grandfathered in with ongoing usage of their existing alternate credentials. As of January 2024 we've fully deprecating all alternate credentials.To avoid any potential disruptions, switch to one of the [available authentication mechanisms](/azure/devops/integrate/get-started/authentication/authentication-guidance?view=azure-devopsthe&preserve-view=true) we provide, such as personal access tokens or managed identities. + +### Azure Devops OAuth self-service secret rotation + +Every five years, it's essential to update the **Client Secret** for your Azure DevOps OAuth app, to ensure continuous generation of access and refresh tokens necessary for utilizing Azure DevOps APIs. As your **Client Secret** approaches expiration, you can now independently generate a new one, providing your team the freedom to manage it without relying on customer support. This flexibility in scheduling secret rotation minimizes potential outage time for your customers waiting for a replacement due to an expired secret. + +> [!div class="mx-imgBorder"] +> ![Screenshot of Select a geography.](../../media/234-general-01.png "Screenshot of Select a geography") + +Look for this new functionality in each of your Azure DevOps app pages that can be accessible through [your profile here](https://app.vssps.visualstudio.com/_signin?realm=app.vssps.visualstudio.com&reply_to=https%3A%2F%2Fapp.vssps.visualstudio.com%2Fprofile%2Fview&redirect=1&context=eyJodCI6MywiaGlkIjoiYTVjYTM1ZWItMTQ4ZS00Y2NkLWJiYjMtZDMxNTc2ZDc1OTU4IiwicXMiOnt9LCJyciI6IiIsInZoIjoiIiwiY3YiOiIiLCJjcyI6IiJ90#ctx=eyJTaWduSW5Db29raWVEb21haW5zIjpbImh0dHBzOi8vbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbSIsImh0dHBzOi8vbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbSJdfQ2). Learn more about this new step in our [Azure DevOps OAuth guide](/azure/devops/integrate/get-started/authentication/azure-devops-oauth?view=azure-devops&preserve-view=tru). diff --git a/release-notes/2024/includes/general/sprint-236-update-links.md b/release-notes/2024/includes/general/sprint-236-update-links.md new file mode 100644 index 00000000000..6570b38193e --- /dev/null +++ b/release-notes/2024/includes/general/sprint-236-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 3/26/2024 +ms.topic: include +--- + +- [Personal access token (PAT) APIs to return maximum allowed lifespan](#personal-access-token-pat-apis-to-return-maximum-allowed-lifespan) + diff --git a/release-notes/2024/includes/general/sprint-236-update.md b/release-notes/2024/includes/general/sprint-236-update.md new file mode 100644 index 00000000000..19e1893a8e1 --- /dev/null +++ b/release-notes/2024/includes/general/sprint-236-update.md @@ -0,0 +1,12 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 3/26/2024 +ms.topic: include +--- + +### Personal access token (PAT) APIs to return maximum allowed lifespan + +When managing personal access tokens (PATs) through the PAT management APIs, a ***validTo*** expiration date can be specified for newly created or updated PATs. If the ["Enforce maximum personal access token lifespan"](/azure/devops/organizations/accounts/manage-pats-with-policies-for-administrators#set-maximum-lifespan-for-new-pats) policy is enabled and the specified ***validTo*** date exceeds the policy's maximum lifespan limit, the system now automatically adjusts and issues a PAT with the maximum permitted lifespan, rather than producing an error. + +Previously, going over the maximum allowed lifespan would cause a _PatLifespanPolicyViolation_ error. This change helps apps and tools that use these APIs handle PAT creation and update errors better when the "maximum personal access token lifespan" policy is enabled. \ No newline at end of file diff --git a/release-notes/2024/includes/general/sprint-238-update-links.md b/release-notes/2024/includes/general/sprint-238-update-links.md new file mode 100644 index 00000000000..cf0c6e585b0 --- /dev/null +++ b/release-notes/2024/includes/general/sprint-238-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 5/2/2024 +ms.topic: include +--- + +- [Improve search results with wildcard prefixes and substrings](#improve-search-results-with-wildcard-prefixes-and-substrings) diff --git a/release-notes/2024/includes/general/sprint-238-update.md b/release-notes/2024/includes/general/sprint-238-update.md new file mode 100644 index 00000000000..294d33a8a4b --- /dev/null +++ b/release-notes/2024/includes/general/sprint-238-update.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 5/2/2024 +ms.topic: include +--- + +### Improve search results with wildcard prefixes and substrings + +We’re excited to announce our new search feature, which now supports wildcard as prefix and substring searches across code, work items, wiki, and packages. By adding a wildcard at the beginning and end of your search term, you can find all relevant strings that contain your term. For instance, entering "Test" in the search box yields results like "mytestclass","improvecodewithtest", and "test_wikiarticle". This feature rolls out over the next few weeks. \ No newline at end of file diff --git a/release-notes/2024/includes/general/sprint-241-update-links.md b/release-notes/2024/includes/general/sprint-241-update-links.md new file mode 100644 index 00000000000..088b76fd7e7 --- /dev/null +++ b/release-notes/2024/includes/general/sprint-241-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 7/3/2024 +ms.topic: include +--- + +- [New authentication format for Azure DevOps personal access tokens available](#new-authentication-format-for-azure-devops-personal-access-tokens-available) diff --git a/release-notes/2024/includes/general/sprint-241-update.md b/release-notes/2024/includes/general/sprint-241-update.md new file mode 100644 index 00000000000..b5bc79253d3 --- /dev/null +++ b/release-notes/2024/includes/general/sprint-241-update.md @@ -0,0 +1,15 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 7/3/2024 +ms.topic: include +--- + +### New authentication format for Azure DevOps personal access tokens available + +We have made updates to the format of personal access tokens (PATs) issued by Azure DevOps. These changes provide additional security benefits and improve secret detection tooling available through our partner offerings, like [GitHub Advanced Security for Azure DevOps](https://devblogs.microsoft.com/devops/github-advanced-security-for-azure-devops-public-preview-starts-now/). This change in PAT format follows the new format recommended across all Microsoft products. We anticipate that the inclusion of more identifiable bits will improve the false positive detection rate of these secret detection tools and enable us to better mitigate any detected leaks faster. + +Notably, the length of our tokens increase from 52 characters to 84 characters, 52 of which will be randomized data. This improves overall entropy of the token generation, enabling us to be more resistant to potential brute forcing attacks. + +You're advised to regenerate all PATs currently in use immediately to benefit from these changes. This can be done on the [Personal access tokens](/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows#modify-a-pat&preserve-view=true) page of your User Profile or by using the [Personal Access Token lifecycle management APIs](/azure/devops/organizations/accounts/manage-personal-access-tokens-via-api?view=azure-devops&preserve-view=true). Integrators are also recommended to support both this new token length and the current token length, while you adapt to this new format. diff --git a/release-notes/2024/includes/general/sprint-246-update-links.md b/release-notes/2024/includes/general/sprint-246-update-links.md new file mode 100644 index 00000000000..fe73717d152 --- /dev/null +++ b/release-notes/2024/includes/general/sprint-246-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 10/16/2024 +ms.topic: include +--- + +- [Copy code block to clipboard](#copy-code-block-to-clipboard) +- [Microsoft Entra profile information (preview)](#microsoft-entra-profile-information-preview) \ No newline at end of file diff --git a/release-notes/2024/includes/general/sprint-246-update.md b/release-notes/2024/includes/general/sprint-246-update.md new file mode 100644 index 00000000000..1babf1b0c0e --- /dev/null +++ b/release-notes/2024/includes/general/sprint-246-update.md @@ -0,0 +1,22 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 10/16/2024 +ms.topic: include +--- + +### Copy code block to clipboard + +In response to your feedback in the [developer community](https://developercommunity.visualstudio.com/t/azure-devops-vsts-wiki-copy-code-button/421282), we’ve introduced a "Copy to clipboard" button for all code blocks in rendered markdown. This enhancement is available across Wiki pages, markdown file previews in Repos, pull request discussions and descriptions, and work item discussions. +> [!div class="mx-imgBorder"] +> ![Screenshot of copy to clipboard.](../../media/246-general-01.png "Screenshot of copy to clipboard") + +### Microsoft Entra profile information (preview) + +We’re excited to introduce the integration of Microsoft Entra profile information in Azure DevOps, removing the need for separate profile updates. To try the preview, enable Microsoft Entra profile information in [Preview Features](/azure/devops/project/navigation/preview-features?view=azure-devops). + +> [!div class="mx-imgBorder"] +> ![Screenshot of turn on Microsoft Entra Profile Information.](../../media/246-general-02.png "Screenshot of turn on Microsoft Entra Profile Information") + +Once enabled, your [profile settings](/azure/devops/organizations/settings/set-your-preferences?view=azure-devops#set-preferences) are read-only and automatically populated from Microsoft Entra. To revert to your previous settings or provide feedback, turn off the preview and share your comments. diff --git a/release-notes/2024/includes/ghazdo/sprint-233-update-links.md b/release-notes/2024/includes/ghazdo/sprint-233-update-links.md new file mode 100644 index 00000000000..8de9ef028d8 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-233-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +ms.topic: include +--- + +- [Custom CodeQL queries now supported in GitHub Advanced Security for Azure DevOps](#custom-codeql-queries-now-supported-in-github-advanced-security-for-azure-devops) \ No newline at end of file diff --git a/release-notes/2024/includes/ghazdo/sprint-233-update.md b/release-notes/2024/includes/ghazdo/sprint-233-update.md new file mode 100644 index 00000000000..c17fd7fe69b --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-233-update.md @@ -0,0 +1,14 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +ms.topic: include +--- + +### Custom CodeQL queries now supported in GitHub Advanced Security for Azure DevOps + +We're thrilled to announce the introduction of support for custom CodeQL queries in Code scanning! This enables you to craft your own queries tailored to identify issues specific to your codebase. Now, you can create and publish packs containing custom queries, execute these queries in your pipelines, and customize the detection of vulnerabilities that are pertinent to your organization. + +For more information on utilizing custom queries for code scanning in GitHub Advanced Security for Azure DevOps, see to [Code scanning alerts for GitHub Advanced Security for Azure DevOps](/azure/devops/repos/security/github-advanced-security-code-scanning?view=azure-devops&branch=main#code-scanning-alerts&preserve-view=true). + +We value your input. If you have any questions or feedback, we encourage you to engage with our community at [Developer Community](https://developercommunity.visualstudio.com/home). diff --git a/release-notes/2024/includes/ghazdo/sprint-234-update-links.md b/release-notes/2024/includes/ghazdo/sprint-234-update-links.md new file mode 100644 index 00000000000..543c2382089 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-234-update-links.md @@ -0,0 +1,13 @@ +--- +author: laurajiang +ms.author: laurajiang +ms.date: 2/9/2024 +ms.topic: include +--- + +- [Code snippets now available in alert details view](#code-snippets-now-available-in-alert-details-view) +- [Truncated secrets displayed in alert overview](#truncated-secrets-displayed-in-alert-overview) +- [More alert severities added for code scanning alerts](#more-alert-severities-added-for-code-scanning-alerts) +- [Linked Azure subscription required for GitHub Advanced Security for Azure DevOps enablement](#linked-azure-subscription-required-for-github-advanced-security-for-azure-devops-enablement) +- [Advanced Security API updates](#advanced-security-api-updates) +- [Advanced Security permissions are now permanently displayed](#advanced-security-permissions-are-now-permanently-displayed) diff --git a/release-notes/2024/includes/ghazdo/sprint-234-update.md b/release-notes/2024/includes/ghazdo/sprint-234-update.md new file mode 100644 index 00000000000..6dcb2e5f88e --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-234-update.md @@ -0,0 +1,46 @@ +--- +author: laurajiang +ms.author: laurajiang +ms.date: 2/9/2024 +ms.topic: include +--- + +### Code snippets now available in alert details view + +The alert detail page for code scanning and secret scanning alerts now shows code snippets that mark the one or more lines of code where the alert occurred. To go to the original file in your Azure DevOps repository, click on the file name above the code snippet. + +> [!div class="mx-imgBorder"] +> [![Screenshot of case-sensitive middleware path.](../../media/234-general-02.png "Screenshot of case-sensitive middleware path")](../../media/234-general-02.png#lightbox) + +### Truncated secrets displayed in alert overview + +The truncated, last six characters of any detected secrets are now displayed in the secrets alert overview screen. This feature is helpful if you have multiple secret exposures of the same secret type, allowing you to quickly identify where particular secrets live. + +> [!div class="mx-imgBorder"] +> [![Screenshot of secret alerts list.](../../media/234-ghazdo-03.png "Screenshot of secret alerts list")](../../media/234-ghazdo-03.png#lightbox) + +### More alert severities added for code scanning alerts + +New alert severities now exist for alert results from the CodeQL `quality` queries as `Error`, `Warning`, and `Note` severities. Each quality alert severity has its own badge and color to denote scaling severities. You can also filter for each of these severities, similar to the `low` to `critical` severity scale for security alerts. + +> [!div class="mx-imgBorder"] +> [![Screenshot of code scanning alerts list and severity filter.](../../media/234-ghazdo-05.png "Screenshot of code scanning alerts list and severity filter")](../../media/234-ghazdo-05.png#lightbox) + + +### Linked Azure subscription required for GitHub Advanced Security for Azure DevOps enablement + +If you previously enabled Advanced Security for repositories in an Azure DevOps organization without a linked Azure subscription, you may notice Advanced Security automatically disabled itself on those repositories. To re-enable Advanced Security, add an associated Azure subscription to the organization. For more information on how to add or change your subscription, see [Change Azure subscription](/azure/devops/organizations/billing/change-azure-subscription?view=azure-devopsthe&preserve-view=true). + +### Advanced Security API updates + +Various updates to the Advanced Security APIs recently shipped: +* The GET Alerts API now supports a new parameter, `ModifiedSince`, to return an incremental list of alerts and only return alerts that were modified since this date. For more information, see [Alerts - List](/rest/api/azure/devops/advancedsecurity/alerts/list). +* There are two new endpoints to fetch or update an organization or project's Advanced Security enablement status. Both endpoints return a list of repositories with Advanced Security enabled. For more information, see [Org - Enablement](/rest/api/azure/devops/advancedsecurity/org-enablement) or [Project - Enablement](/rest/api/azure/devops/advancedsecurity/project-enablement). +* There are two new endpoints to fetch an estimate of your active committer count for an organization or project to reflect what your estimated Advanced Security meter usage may cost. For more information, see [Org Meter Usage Estimate](/rest/api/azure/devops/advancedsecurity/org-meter-usage-estimate) or [Project Meter Usage Estimate](/rest/api/azure/devops/advancedsecurity/project-meter-usage-estimate). + +### Advanced Security permissions are now permanently displayed + +In the past, the three Advanced Security permission bits would only be present as per-repository assignable permissions if Advanced Security was enabled. Now, these permissions are available by default at the **Repositories > Security** permissions pane and can be assigned without having Advanced Security to be enabled. + +> [!div class="mx-imgBorder"] +> [![Screenshot of Advanced Security permissions.](../../media/234-ghazdo-02.png "Screenshot of Advanced Security permissions")](../../media/234-ghazdo-02.png#lightbox) diff --git a/release-notes/2024/includes/ghazdo/sprint-237-update-links.md b/release-notes/2024/includes/ghazdo/sprint-237-update-links.md new file mode 100644 index 00000000000..445b1234acb --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-237-update-links.md @@ -0,0 +1,10 @@ +--- +author: ncouraud +ms.author: ncouraud +ms.date: 4/10/2024 +ms.topic: include +--- + +- [Security overview risk and coverage views](#security-overview-risk-and-coverage-views) +- [Expanded set of Secret Scanning detections](#expanded-set-of-secret-scanning-detections) +- [Secret Scanning now detects non-provider patterns](#secret-scanning-now-detects-non-provider-patterns) diff --git a/release-notes/2024/includes/ghazdo/sprint-237-update.md b/release-notes/2024/includes/ghazdo/sprint-237-update.md new file mode 100644 index 00000000000..106208166b9 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-237-update.md @@ -0,0 +1,34 @@ +--- +author: ncouraud +ms.author: ncouraud +ms.date: 4/10/2024 +ms.topic: include +--- + +### Security overview risk and coverage views + +You can now see an organization-wide view of your repositories and their Advanced Security alerts and Advanced Security enablement status of all repositories in your organization. + +The security overview feature for Advanced Security can be found by navigating to **Organization settings > Security overview**. For more information, see [Security overview on GitHub Advanced Security for Azure DevOps](/azure/devops/repos/security/github-advanced-security-security-overview). + +### Expanded set of Secret Scanning detections + +We're expanding the set of partner patterns that can be detected with Secret Scanning. This expansion brings in many high confidence patterns for new token types. These new patterns include a large number of Azure resource providers, and other SaaS providers through the GitHub Advanced Security secret scanning partner program. + +For more information on the types of partner patterns that GitHub Advanced Security Secret Scanning detects, see [Secret scanning alerts for GitHub Advanced Security for Azure DevOps](/azure/devops/repos/security/github-advanced-security-secret-scanning?view=azure-devops&branch=main#secret-scanning-patterns&preserve-view=true). + +### Secret Scanning now detects non-provider patterns + +Secret scanning now detects many non-provider patterns, including: +- HTTP authentication headers +- MongoDB connection strings +- MySQL/Postgres/SQL Server connection strings +- OpenSSH private keys +- RSA private keys + +> [!NOTE] +> The detection of non-provider patterns is currently in preview and subject to change. + +Detection of these patterns is enabled for all GitHub Advanced Security enabled repositories in Azure DevOps. Resulting secrets appear in a new, separate filter on the secret scanning alert list called "Confidence.” + +For more information on the types of patterns that GitHub Advanced Security Secret Scanning detects, see [Secret scanning alerts for GitHub Advanced Security for Azure DevOps](/azure/devops/repos/security/github-advanced-security-secret-scanning?view=azure-devops&branch=main#secret-scanning-patterns&preserve-view=true). diff --git a/release-notes/2024/includes/ghazdo/sprint-238-update-links.md b/release-notes/2024/includes/ghazdo/sprint-238-update-links.md new file mode 100644 index 00000000000..c159aace9d5 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-238-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 5/2/2024 +ms.topic: include +--- + +- [Security overview risk view links to repository alerts](#security-overview-risk-view-links-to-repository-alerts) +- [Publish task for integrating with third-party providers](#publish-task-for-integrating-with-third-party-providers) \ No newline at end of file diff --git a/release-notes/2024/includes/ghazdo/sprint-238-update.md b/release-notes/2024/includes/ghazdo/sprint-238-update.md new file mode 100644 index 00000000000..082f2395d54 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-238-update.md @@ -0,0 +1,19 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 5/2/2024 +ms.topic: include +--- + +### Security overview risk view links to repository alerts + +The security overview risk page now links directly to each repository's individual Advanced Security alerts page. Similar to the coverage page, for a particular repository, hover over the row and click on the icon on the right side of the row to navigate directly to the alerts page. + +> [!div class="mx-imgBorder"] +> [![Screenshot of links to repository alerts.](../../media/238-ghazdo-01.png "Screenshot of links to repository alerts")](../../media/238-ghazdo-01.png#lightbox) + +### Publish task for integrating with third-party providers + +The **AdvancedSecurity-Publish@1** task allows you to easily retrieve results from third-party providers, enhancing the integration with GitHub advanced security for AzureDevOps. These providers can include both open-source and commercial security analysis pipeline tasks that generate results in the conforming SARIF format. By leveraging this, you can now view the results within the Advanced Security Code Scanning alerts hub, providing a unified view of code security alerts from currently supported analysis tools directly within Azure DevOps. This integration supports SARIF 2.1, offering you a comprehensive overview of their security posture. + +For detailed instructions on configuring code scanning in GitHub Advanced Security with Azure DevOps, see [Set up code scanning](/azure/devops/repos/security/configure-github-advanced-security-features?view=azure-devops&tabs=yaml#set-up-code-scanning). diff --git a/release-notes/2024/includes/ghazdo/sprint-240-update-links.md b/release-notes/2024/includes/ghazdo/sprint-240-update-links.md new file mode 100644 index 00000000000..c8684787b81 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-240-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +ms.topic: include +--- + +- [Security overview API documentation now available ](#security-overview-api-documentation-now-available) \ No newline at end of file diff --git a/release-notes/2024/includes/ghazdo/sprint-240-update.md b/release-notes/2024/includes/ghazdo/sprint-240-update.md new file mode 100644 index 00000000000..4c574899d28 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-240-update.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +ms.topic: include +--- + +### Security overview API documentation now available + +Documentation for the API powering the Advanced Security overview risk tab is now available. Use the endpoint `/{organization}/_apis/reporting/summary/alerts` to view a summary of alert criticality across all Advanced Security-enabled repositories. Ensure your ADO PAT has the `vso.advsec` permission, which grants the ability to read alerts, result instances, and analysis result instances. \ No newline at end of file diff --git a/release-notes/2024/includes/ghazdo/sprint-241-update-links.md b/release-notes/2024/includes/ghazdo/sprint-241-update-links.md new file mode 100644 index 00000000000..e48ddbee36c --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-241-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 7/3/2024 +ms.topic: include +--- + +- [Automated self-hosted agent install for code scanning bits in Advanced Security ](#automated-self-hosted-agent-install-for-code-scanning-bits-in-advanced-security) \ No newline at end of file diff --git a/release-notes/2024/includes/ghazdo/sprint-241-update.md b/release-notes/2024/includes/ghazdo/sprint-241-update.md new file mode 100644 index 00000000000..b54ce7a6ef3 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-241-update.md @@ -0,0 +1,13 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 7/3/2024 +ms.topic: include +--- + +### Automated self-hosted agent install for code scanning bits in Advanced Security + +To simplify using self-hosted agents for code scanning in Advanced Security, the latest CodeQL bits can now be automatically installed. The `Advanced-Security-Codeql-Init` task includes a new variable, `enableAutomaticCodeQLInstall: true`, for existing pipelines or a checkbox for new tasks. Previously, you had to manually install the CodeQL bundle in the agent tool directory. + +> [!div class="mx-imgBorder"] +> [![Screenshot of Automated self-hosted agent install.](../../media/241-ghazdo-01.png "Screenshot of Automated self-hosted agent install")](../../media/241-ghazdo-01.png#lightbox) \ No newline at end of file diff --git a/release-notes/2024/includes/ghazdo/sprint-243-update-links.md b/release-notes/2024/includes/ghazdo/sprint-243-update-links.md new file mode 100644 index 00000000000..79b7162d8f6 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-243-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/13/2024 +ms.topic: include +--- + +- [Advanced Security meter usage API now returns user identities](#advanced-security-meter-usage-api-now-returns-user-identities) +- [GitHub Advanced Security code scanning for C# and Java projects without builds](#github-advanced-security-code-scanning-for-c-and-java-projects-without-builds) + diff --git a/release-notes/2024/includes/ghazdo/sprint-243-update.md b/release-notes/2024/includes/ghazdo/sprint-243-update.md new file mode 100644 index 00000000000..255b67add3d --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-243-update.md @@ -0,0 +1,34 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/13/2024 +ms.topic: include +--- + +### Advanced Security meter usage API now returns user identities + +To help you identify your Advanced Security users, the Meter Usage Estimate APIs now return each user’s Azure DevOps identity, including their display name, CUID, email identifier, and identity descriptor. This feature is available at the organization, project, and repository levels. To use this new endpoint, the syntax is similar to the existing meter usage API endpoints, appending `/details` to the endpoint: + +- At the organization level: GET `https://advsec.dev.azure.com/{organization}/_apis/management/meterUsageEstimate/details?api-version=7.2-preview.1` +- At the project level: GET `https://advsec.dev.azure.com/{organization}/{project}/_apis/management/meterUsageEstimate/details?api-version=7.2-preview.1` +- At the repository level: GET `https://advsec.dev.azure.com/{organization}/{project}/_apis/management/repositories/{repository}/meterUsageEstimate/details?api-version=7.2-preview.1` + +### GitHub Advanced Security code scanning for C# and Java projects without builds + +Code scanning with CodeQL involves running queries on databases that represent the code in your repository for a single language. For compiled languages like C/C++, C#, Go, Java, and Swift, this typically requires building the code first. + +However, CodeQL, the static analysis engine behind GitHub Advanced Security for Azure DevOps, can now scan C# and Java projects without needing a build. When the build mode is set to **"none,"** the CodeQL database is generated directly from the codebase, bypassing the build step. + +For all compiled languages, the default build mode is **"manual."** However, for C# and Java, you can change the build mode to **"none."** + +You can configure the build mode during the AdvancedSecurity-Codeql-Init@1 setup. For detailed instructions on configuring code scanning in GitHub Advanced Security with Azure DevOps, see Set up [code scanning](/azure/devops/repos/security/configure-github-advanced-security-features?view=azure-devops&tabs=yaml#set-up-code-scanning) + +Consideration: +- If **"none"** is selected and a language other than supported complied languages C# or Java, the pipeline task may not work as expected. + - Build mode **"none"** currently works in conjunction with other interpreted languages (e.g., JavaScript, Python, Ruby). + +- Valid Example: C# and JavaScript with build mode set to **"none."** (JavaScript in an interpreted language) +- Invalid Example: C#, JavaScript, and Swift with build mode set to **"none"** (Swift is not supported in build mode **"none"**). + +> [!div class="mx-imgBorder"] +> [![Screenshot of AdvancedSecurity-Codeql.](../../media/243-ghazdo-01.png "Screenshot of AdvancedSecurity-Codeql")](../../media/243-ghazdo-01.png#lightbox) diff --git a/release-notes/2024/includes/ghazdo/sprint-244-update-links.md b/release-notes/2024/includes/ghazdo/sprint-244-update-links.md new file mode 100644 index 00000000000..55b1009b2c8 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-244-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +ms.topic: include +--- + +- [New Advanced Security API endpoint to retrieve all branches with successful Advanced Security analyses](#new-advanced-security-api-endpoint-to-retrieve-all-branches-with-successful-advanced-security-analyses) +- [Advanced Security List Alerts API return all alerts across all branches](#advanced-security-list-alerts-api-return-all-alerts-across-all-branches) + diff --git a/release-notes/2024/includes/ghazdo/sprint-244-update.md b/release-notes/2024/includes/ghazdo/sprint-244-update.md new file mode 100644 index 00000000000..a7bcb972f01 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-244-update.md @@ -0,0 +1,14 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +ms.topic: include +--- + +### New Advanced Security API endpoint to retrieve all branches with successful Advanced Security analyses + +To retrieve a list of all branches for a particular repository where Advanced Security analysis has been performed, you can use a new API endpoint: `https://advsec.dev.azure.com/{organization}/{project}/_apis/alert/repositories/{repository}/filters/branches?api-version=7.2-preview.1`. To use this endpoint, it requires the `vso.advsec` token scope, or "Advanced Security: read alerts" permissions. + +### Advanced Security List Alerts API return all alerts across all branches + +Using the List Alerts API for Advanced Security, you can retrieve a list of all alerts across all branches with Advanced Security results present. Set the parameter `criteria.onlyDefaultBranch=false` to retrieve all alerts: `https://advsec.dev.azure.com/{organization}/{project}/_apis/alert/repositories/{repository}/alerts?api-version=7.2-preview.1&criteria.onlyDefaultBranch=false`. For more details on the List Alerts API, see [List Alerts - Advanced Security](/rest/api/azure/devops/advancedsecurity/alerts/list). \ No newline at end of file diff --git a/release-notes/2024/includes/ghazdo/sprint-245-update-links.md b/release-notes/2024/includes/ghazdo/sprint-245-update-links.md new file mode 100644 index 00000000000..2c72c9634a7 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-245-update-links.md @@ -0,0 +1,12 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +ms.topic: include +--- + +- [Pull request branches now visible in Advanced Security branch picker](#pull-request-branches-now-visible-in-advanced-security-branch-picker) +- [Automatic updates for default branch changes in Advanced Security](#automatic-updates-for-default-branch-changes-in-advanced-security) +- [Generic third-party SARIF support for Advanced Security](#generic-third-party-sarif-support-for-advanced-security) +- [Alert rule IDs now integrated into result fingerprints ](#alert-rule-ids-now-integrated-into-result-fingerprints) +- [Expanded set of Secret Scanning detections](#expanded-set-of-secret-scanning-detections) diff --git a/release-notes/2024/includes/ghazdo/sprint-245-update.md b/release-notes/2024/includes/ghazdo/sprint-245-update.md new file mode 100644 index 00000000000..39f89c2a9c3 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-245-update.md @@ -0,0 +1,41 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +ms.topic: include +--- + +### Pull request branches now visible in Advanced Security branch picker + +Pull request branches were previously hidden in the branch picker, even though scanning on pull request branches was possible. Now, these branches are visible in the Advanced Security branch picker and can be searched. + +> [!div class="mx-imgBorder"] +> [![Screenshot of Pull request branches.](../../media/245-ghazdo-01.png "Screenshot of Pull request branches")](../../media/245-ghazdo-01.png#lightbox) + + +### Automatic updates for default branch changes in Advanced Security + +In the past, the Advanced Security repository tab did not automatically update when the default branch changed, requiring manual selection of the new branch in the branch picker. Now, the tab automatically detects and displays alerts for the newly designated default branch upon visiting the page. + +Additionally, the Security Overview updates to reflect default branch changes, although there may be a slight delay before the updated alert results are processed. + +### Generic third-party SARIF support for Advanced Security + +You can now upload results from your third-party scanning tool to show in the Advanced Security code scanning tab. + +Using a scanning tool that publishes a SARIF file to the `$(Agent.TempDirectory)/.advsec` directory, conforms to the SARIF 2.1 standard, and runs the [AdvancedSecurity-Publish@1](/azure/devops/pipelines/tasks/reference/advanced-security-publish-v1?view=azure-pipelines) after the task will upload results to the code scanning tab. + +> [!NOTE] +> The file path associated with a result in the SARIF file must be accessible to the `AdvancedSecurity-Publish@1` task running in the build agent. + +### Alert rule IDs now integrated into result fingerprints + +Previously, third-party tool results with the same fingerprint, hash, tool, and rule name were grouped into one alert, even if they had different rule IDs. + +With this update, rule IDs are now included in the fingerprint, creating separate alerts for results with different rule IDs, even if other data points are the same. Existing alerts will be updated and split accordingly. + +### Expanded set of Secret Scanning detections + +We're expanding the set of partner patterns that can be detected with Secret Scanning. This expansion brings in several high confidence patterns for new token types. + +For more information on the types of partner patterns that GitHub Advanced Security Secret Scanning detects, see [Secret scanning alerts for GitHub Advanced Security for Azure DevOps](/azure/devops/repos/security/github-advanced-security-secret-scanning?view=azure-devops&branch=main#secret-scanning-patterns&preserve-view=true). diff --git a/release-notes/2024/includes/ghazdo/sprint-246-update-links.md b/release-notes/2024/includes/ghazdo/sprint-246-update-links.md new file mode 100644 index 00000000000..5e7a9615748 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-246-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +- [Pull request annotations for dependency and code scanning](#pull-request-annotations-for-dependency-and-code-scanning) +- [New pip detection strategy for dependency scanning ](#new-pip-detection-strategy-for-dependency-scanning) diff --git a/release-notes/2024/includes/ghazdo/sprint-246-update.md b/release-notes/2024/includes/ghazdo/sprint-246-update.md new file mode 100644 index 00000000000..f19b54fc6a2 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-246-update.md @@ -0,0 +1,25 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +### Pull request annotations for dependency and code scanning + +As part of the Advanced Security roadmap, [pull-request annotations](/azure/devops/release-notes/roadmap/2024/ghazdo/pull-request-annotation) are now available. You'll receive in-line annotations on any pull requests that use a pipeline associated with your build validation policy, which includes dependency and/or code scanning tasks. + +No additional opt-in is required beyond creating a build validation policy for the relevant branches. + +Clicking on `Show more details` in the annotation brings you to the alert detail view for the alert in question. + +> [!div class="mx-imgBorder"] +> [![Screenshot of Clicking on Show more details.](../../media/246-ghazdo-01.png "Screenshot of Clicking on Show more details")](../../media/246-ghazdo-01.png#lightbox) + +For more information, please see our [latest blog post here](https://devblogs.microsoft.com/devops/introducing-pull-request-annotation-for-codeql-and-dependency-scanning-in-github-advanced-security-for-azure-devops/) + +### New pip detection strategy for dependency scanning + +Dependency scanning now uses a new detection strategy for Python: PipReport, based on the [pip installation report](https://pip.pypa.io/en/stable/reference/installation-report/) functionality. This update improves accuracy by respecting environment specifiers to determine the exact versions that a real `pip install` run would retrieve. By default, the detector uses `pypi.org` to build the dependency graph. Optionally, you can set a pipeline environment variable, `PIP_INDEX_URL` to construct the dependency graph instead. If there are authentication issues accessing your feed, you may need the `PipAuthenticate@1` pipeline task set up so that your feed can be accessed. + +For more information on detection strategy, see [Pip Detection](https://github.com/microsoft/component-detection/blob/main/docs/detectors/pip.md#installation-report-pipreportdetector) documentation. diff --git a/release-notes/2024/includes/ghazdo/sprint-247-update-links.md b/release-notes/2024/includes/ghazdo/sprint-247-update-links.md new file mode 100644 index 00000000000..febfa2c2f96 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-247-update-links.md @@ -0,0 +1,12 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +ms.topic: include +--- + +- [Commit-less builds supported for dependency scanning ](#commit-less-builds-supported-for-dependency-scanning ) +- [File previews and annotations for CodeQL scans using sourcesFolder](#file-previews-and-annotations-for-codeql-scans-using-sourcesfolder) + + + diff --git a/release-notes/2024/includes/ghazdo/sprint-247-update.md b/release-notes/2024/includes/ghazdo/sprint-247-update.md new file mode 100644 index 00000000000..1c0b80501a7 --- /dev/null +++ b/release-notes/2024/includes/ghazdo/sprint-247-update.md @@ -0,0 +1,14 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +ms.topic: include +--- + +### Commit-less builds supported for dependency scanning + +Dependency scanning no longer requires a new commit to trigger a results submission. With this update, all builds will submit detected components for vulnerability analysis, whether or not they include commit changes. This enhancement streamlines security workflows and broadens scan coverage. + +### File previews and annotations for CodeQL scans using sourcesFolder + +Now, when using the `sourcesFolder` variable in CodeQL builds, file previews and annotations display accurately in alerts and pull requests, giving you consistent, reliable visibility into scan results. \ No newline at end of file diff --git a/release-notes/2024/includes/nextsteps.md b/release-notes/2024/includes/nextsteps.md new file mode 100644 index 00000000000..445ee955b94 --- /dev/null +++ b/release-notes/2024/includes/nextsteps.md @@ -0,0 +1,18 @@ +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). \ No newline at end of file diff --git a/release-notes/2024/includes/pipelines/sprint-233-update-links.md b/release-notes/2024/includes/pipelines/sprint-233-update-links.md new file mode 100644 index 00000000000..4c3a102e6b2 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-233-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +ms.topic: include +--- + +- [Update deprecated tasks before January 31](#update-deprecated-tasks-before-january-31) +- [Microsoft hosted agents use PowerShell 7.4](#microsoft-hosted-agents-use-powershell-74) +- [New Azure service connection secrets expire in three months](#new-azure-service-connection-secrets-expire-in-three-months) diff --git a/release-notes/2024/includes/pipelines/sprint-233-update.md b/release-notes/2024/includes/pipelines/sprint-233-update.md new file mode 100644 index 00000000000..f962b005140 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-233-update.md @@ -0,0 +1,120 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +ms.topic: include +--- + +### Update deprecated tasks before January 31 + +We are retiring deprecated tasks on January 31, 2024. To help you identify the pipelines that are using these tasks, we have included a warning message with a suggested alternative. We encourage you to update your pipelines to use a newer task version or an alternative before January 31, 2024. + +> [!div class="mx-imgBorder"] +> ![Screenshot of task-specific deprecation warnings.](../../media/233-pipelines-01.png "Screenshot of task-specific deprecation warnings") + +See earlier announcements related to deprecated tasks: + +- [Announcing retirement of deprecated tasks](/azure/devops/release-notes/2023/pipelines/sprint-230-update?branch=pr-en-us-6451#announcing-retirement-of-deprecated-tasks) +- [Announcement for NuGet Restore v1 and NuGet Installer v0 pipeline tasks](/azure/devops/release-notes/2023/artifacts/sprint-229-update?branch=pr-en-us-6451#deprecation-announcement-for-nuget-restore-v1-and-nuget-installer-v0-pipeline-tasks) + +### Microsoft hosted agents use PowerShell 7.4 + +All [Microsoft hosted agents](/azure/devops/pipelines/agents/hosted?view=azure-devops&tabs=yaml#software&preserve-view=true) will start using PowerShell 7.2 LTS to PowerShell 7.4 LTS from January 28. See [What's New in PowerShell 7.4](/powershell/scripting/whats-new/what-s-new-in-powershell-74?view=powershell-7.4&preserve-view=true) and [PowerShell 7.4 General Availability](https://devblogs.microsoft.com/powershell/powershell-7-4-general-availability/). + +Take note of breaking changes and update your scripts accordingly: + +- [Breaking changes](/powershell/scripting/whats-new/what-s-new-in-powershell-74?view=powershell-7.4#breaking-changes&preserve-view=true) between PowerShell 7.3 & 7.4 LTS +- [Breaking changes](/powershell/scripting/whats-new/what-s-new-in-powershell-73?view=powershell-7.4#breaking-changes-and-improvements&preserve-view=true) between PowerShell 7.2 LTS & 7.3 +- Updated argument parsing behavior controlled via +[`$PSNativeCommandArgumentPassing`](/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#psnativecommandargumentpassing&preserve-view=true). The sample script [below](#new-azure-service-connection-secrets-expire-in-three-months) enforces the same behavior across Linux, macOS & Windows by setting `$PSNativeCommandArgumentPassing` explicitly. + +### New Azure service connection secrets expire in three months + +Azure Service Connections where Azure DevOps creates the [secret](/azure/devops/pipelines/library/connect-to-azure?view=azure-devops#create-an-azure-resource-manager-service-connection-using-a-service-principal-secret&preserve-view=true), will have a secret expiration of three months instead of two years. + +To eliminate the need to rotate secrets, [convert](/azure/devops/pipelines/library/connect-to-azure?view=azure-devops#convert-an-existing-arm-service-connection-to-use-workload-identity-federation&preserve-view=true) your service connection to use [Workload identity federation](/azure/devops/pipelines/library/connect-to-azure?view=azure-devops#create-an-azure-resource-manager-service-connection-using-workload-identity-federation&preserve-view=true) instead. You can use the below sample script to quickly convert multiple Azure service connections to Workload identity federation: + +```powershell +#!/usr/bin/env pwsh +<# +.SYNOPSIS + Convert multiple Azure Resource Manager service connection(s) to use Workload identity federation + +.LINK + https://aka.ms/azdo-rm-workload-identity-conversion + +.EXAMPLE + ./convert_azurerm_service_connection_to_oidc_simple.ps1 -Project -OrganizationUrl https://dev.azure.com/ +#> +#Requires -Version 7.3 + +param ( + [parameter(Mandatory=$true,HelpMessage="Name of the Azure DevOps Project")] + [string] + [ValidateNotNullOrEmpty()] + $Project, + + [parameter(Mandatory=$true,HelpMessage="Url of the Azure DevOps Organization")] + [uri] + [ValidateNotNullOrEmpty()] + $OrganizationUrl +) +$apiVersion = "7.1" +$PSNativeCommandArgumentPassing = "Standard" + +#----------------------------------------------------------- +# Log in to Azure +$azdoResource = "499b84ac-1321-427f-aa17-267ca6975798" +az login --allow-no-subscriptions --scope ${azdoResource}/.default +$OrganizationUrl = $OrganizationUrl.ToString().Trim('/') + +#----------------------------------------------------------- +# Retrieve the service connection +$getApiUrl = "${OrganizationUrl}/${Project}/_apis/serviceendpoint/endpoints?authSchemes=ServicePrincipal&type=azurerm&includeFailed=false&includeDetails=true&api-version=${apiVersion}" +az rest --resource $azdoResource -u "${getApiUrl} " -m GET --query "sort_by(value[?authorization.scheme=='ServicePrincipal' && data.creationMode=='Automatic' && !(isShared && serviceEndpointProjectReferences[0].projectReference.name!='${Project}')],&name)" -o json ` + | Tee-Object -Variable rawResponse | ConvertFrom-Json | Tee-Object -Variable serviceEndpoints | Format-List | Out-String | Write-Debug +if (!$serviceEndpoints -or ($serviceEndpoints.count-eq 0)) { + Write-Warning "No convertible service connections found" + exit 1 +} + +foreach ($serviceEndpoint in $serviceEndpoints) { + # Prompt user to confirm conversion + $choices = @( + [System.Management.Automation.Host.ChoiceDescription]::new("&Convert", "Converting service connection '$($serviceEndpoint.name)'...") + [System.Management.Automation.Host.ChoiceDescription]::new("&Skip", "Skipping service connection '$($serviceEndpoint.name)'...") + [System.Management.Automation.Host.ChoiceDescription]::new("&Exit", "Exit script") + ) + $prompt = $serviceEndpoint.isShared ? "Convert shared service connection '$($serviceEndpoint.name)'?" : "Convert service connection '$($serviceEndpoint.name)'?" + $decision = $Host.UI.PromptForChoice([string]::Empty, $prompt, $choices, $serviceEndpoint.isShared ? 1 : 0) + + if ($decision -eq 0) { + + Write-Host "$($choices[$decision].HelpMessage)" + } elseif ($decision -eq 1) { + Write-Host "$($PSStyle.Formatting.Warning)$($choices[$decision].HelpMessage)$($PSStyle.Reset)" + continue + } elseif ($decision -ge 2) { + Write-Host "$($PSStyle.Formatting.Warning)$($choices[$decision].HelpMessage)$($PSStyle.Reset)" + exit + } + + # Prepare request body + $serviceEndpoint.authorization.scheme = "WorkloadIdentityFederation" + $serviceEndpoint.data.PSObject.Properties.Remove('revertSchemeDeadline') + $serviceEndpoint | ConvertTo-Json -Depth 4 | Write-Debug + $serviceEndpoint | ConvertTo-Json -Depth 4 -Compress | Set-Variable serviceEndpointRequest + $putApiUrl = "${OrganizationUrl}/${Project}/_apis/serviceendpoint/endpoints/$($serviceEndpoint.id)?operation=ConvertAuthenticationScheme&api-version=${apiVersion}" + # Convert service connection + az rest -u "${putApiUrl} " -m PUT -b $serviceEndpointRequest --headers content-type=application/json --resource $azdoResource -o json ` + | ConvertFrom-Json | Set-Variable updatedServiceEndpoint + + $updatedServiceEndpoint | ConvertTo-Json -Depth 4 | Write-Debug + if (!$updatedServiceEndpoint) { + Write-Debug "Empty response" + Write-Error "Failed to convert service connection '$($serviceEndpoint.name)'" + exit 1 + } + Write-Host "Successfully converted service connection '$($serviceEndpoint.name)'" +} +``` \ No newline at end of file diff --git a/release-notes/2024/includes/pipelines/sprint-234-update-links.md b/release-notes/2024/includes/pipelines/sprint-234-update-links.md new file mode 100644 index 00000000000..e140d3898b9 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-234-update-links.md @@ -0,0 +1,12 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +ms.topic: include +--- + +- [Workload identity federation for Azure Resource Manager service connections is now generally available](#workload-identity-federation-for-azure-resource-manager-service-connections-is-now-generally-available) +- [Out-of-band installation of Node 6 task runner](#out-of-band-installation-of-node-6-task-runner) +- [Deferred approval](#deferred-approval) +- [Sequencing approvals and checks](#sequencing-approvals-and-checks) +- [Validate and Save by default when editing YAML pipelines](#validate-and-save-by-default-when-editing-yaml-pipelines) \ No newline at end of file diff --git a/release-notes/2024/includes/pipelines/sprint-234-update.md b/release-notes/2024/includes/pipelines/sprint-234-update.md new file mode 100644 index 00000000000..aeb804f7d32 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-234-update.md @@ -0,0 +1,224 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +ms.topic: include +--- + +### Workload identity federation for Azure Resource Manager service connections is now generally available + +In September, we [announced](https://devblogs.microsoft.com/devops/public-preview-of-workload-identity-federation-for-azure-pipelines/) the ability to configure Azure service connections without using a secret. Since then, many customers have adopted this feature and we're excited to announce this capability is now generally available. + +If you aren't using Workload identity federation yet, you can take advantage of worry-free Azure service connections that don't have expiring secrets in the following ways: + +To create a new Azure service connection using workload identity federation, select Workload identity federation (automatic) in the Azure service connection creation experience: + +> [!div class="mx-imgBorder"] +> ![Screenshot of Workload identity federation (automatic).](../../media/234-pipelines-19.png "Screenshot of Workload identity federation (automatic)") + + +To convert a previously created Azure service connection, select the "Convert" action after selecting the connection: + +> [!div class="mx-imgBorder"] +> ![Screenshot of Convert action.](../../media/234-pipelines-20.png "Screenshot of Convert action") + + +To convert multiple service connections, you can use automation for example, this PowerShell script: + +```powershell +#!/usr/bin/env pwsh +<# +.SYNOPSIS + Convert multiple Azure Resource Manager service connection(s) to use Workload identity federation + +.LINK + https://aka.ms/azdo-rm-workload-identity-conversion + +.EXAMPLE + ./convert_azurerm_service_connection_to_oidc_simple.ps1 -Project -OrganizationUrl https://dev.azure.com/ +#> +#Requires -Version 7.3 + +param ( + [parameter(Mandatory=$true,HelpMessage="Name of the Azure DevOps Project")] + [string] + [ValidateNotNullOrEmpty()] + $Project, + + [parameter(Mandatory=$true,HelpMessage="Url of the Azure DevOps Organization")] + [uri] + [ValidateNotNullOrEmpty()] + $OrganizationUrl +) +$apiVersion = "7.1" +$PSNativeCommandArgumentPassing = "Standard" + +#----------------------------------------------------------- +# Log in to Azure +$azdoResource = "499b84ac-1321-427f-aa17-267ca6975798" +az login --allow-no-subscriptions --scope ${azdoResource}/.default +$OrganizationUrl = $OrganizationUrl.ToString().Trim('/') + +#----------------------------------------------------------- +# Retrieve the service connection +$getApiUrl = "${OrganizationUrl}/${Project}/_apis/serviceendpoint/endpoints?authSchemes=ServicePrincipal&type=azurerm&includeFailed=false&includeDetails=true&api-version=${apiVersion}" +az rest --resource $azdoResource -u "${getApiUrl} " -m GET --query "sort_by(value[?authorization.scheme=='ServicePrincipal' && data.creationMode=='Automatic' && !(isShared && serviceEndpointProjectReferences[0].projectReference.name!='${Project}')],&name)" -o json ` + | Tee-Object -Variable rawResponse | ConvertFrom-Json | Tee-Object -Variable serviceEndpoints | Format-List | Out-String | Write-Debug +if (!$serviceEndpoints -or ($serviceEndpoints.count-eq 0)) { + Write-Warning "No convertible service connections found" + exit 1 +} + +foreach ($serviceEndpoint in $serviceEndpoints) { + # Prompt user to confirm conversion + $choices = @( + [System.Management.Automation.Host.ChoiceDescription]::new("&Convert", "Converting service connection '$($serviceEndpoint.name)'...") + [System.Management.Automation.Host.ChoiceDescription]::new("&Skip", "Skipping service connection '$($serviceEndpoint.name)'...") + [System.Management.Automation.Host.ChoiceDescription]::new("&Exit", "Exit script") + ) + $prompt = $serviceEndpoint.isShared ? "Convert shared service connection '$($serviceEndpoint.name)'?" : "Convert service connection '$($serviceEndpoint.name)'?" + $decision = $Host.UI.PromptForChoice([string]::Empty, $prompt, $choices, $serviceEndpoint.isShared ? 1 : 0) + + if ($decision -eq 0) { + + Write-Host "$($choices[$decision].HelpMessage)" + } elseif ($decision -eq 1) { + Write-Host "$($PSStyle.Formatting.Warning)$($choices[$decision].HelpMessage)$($PSStyle.Reset)" + continue + } elseif ($decision -ge 2) { + Write-Host "$($PSStyle.Formatting.Warning)$($choices[$decision].HelpMessage)$($PSStyle.Reset)" + exit + } + + # Prepare request body + $serviceEndpoint.authorization.scheme = "WorkloadIdentityFederation" + $serviceEndpoint.data.PSObject.Properties.Remove('revertSchemeDeadline') + $serviceEndpoint | ConvertTo-Json -Depth 4 | Write-Debug + $serviceEndpoint | ConvertTo-Json -Depth 4 -Compress | Set-Variable serviceEndpointRequest + $putApiUrl = "${OrganizationUrl}/${Project}/_apis/serviceendpoint/endpoints/$($serviceEndpoint.id)?operation=ConvertAuthenticationScheme&api-version=${apiVersion}" + # Convert service connection + az rest -u "${putApiUrl} " -m PUT -b $serviceEndpointRequest --headers content-type=application/json --resource $azdoResource -o json ` + | ConvertFrom-Json | Set-Variable updatedServiceEndpoint + + $updatedServiceEndpoint | ConvertTo-Json -Depth 4 | Write-Debug + if (!$updatedServiceEndpoint) { + Write-Debug "Empty response" + Write-Error "Failed to convert service connection '$($serviceEndpoint.name)'" + exit 1 + } + Write-Host "Successfully converted service connection '$($serviceEndpoint.name)'" +} +``` + +For more information, visit our [documentation](https://aka.ms/azdo-rm-workload-identity). + +### The Pipelines agent shows resource utilization issues more prominently + +[Last October](/azure/devops/release-notes/2023/pipelines/sprint-228-update#pipeline-logs-now-contain-resource-utilization) we added the ability to track memory & disk space usage by the Pipelines agent. + +To make customers aware, they may have resource constraints such as memory or disk space limitations on their agent, we made resource constraints more visible: + +> [!div class="mx-imgBorder"] +> ![Screenshot of Limited memory and disk space warning.](../../media/234-pipelines-18.png "Screenshot of Limited memory and disk space warning") + +If you see any of the above messages, this may be caused by a task using more resources than the agent is dimensioned for which may result in the agent not being responsive and failing a pipeline job: + +> "We stopped hearing from the agent" + +In such cases, enable [verbose logs](/azure/devops/pipelines/troubleshooting/review-logs?view=azure-devops#configure-verbose-logs&preserve-view=true) to get more finer grained resource utilization messages and track where your agent ran out of resources. If you're using a Self-hosted agent, make sure your agent has adequate resources. + +### Out-of-band installation of Node 6 task runner + +Azure Pipelines provides two versions of agent packages: + +- __vsts-agent-*__ packages support tasks using Node 6 to run. +- __pipelines-agent-*__ packages do not support tasks that require Node 6 to run. + +Customers that create Self-hosted agents can download these from the Pipeline agent [releases page](https://github.com/microsoft/azure-pipelines-agent/releases). The Node versions included with the agent are used to execute tasks. See [Node runner versions](/azure/devops/pipelines/agents/agents?view=azure-devops&tabs=yaml%2Cbrowser#node-runner-versions&preserve-view=true). + +After agent registration, agents installed from __pipelines-agent-*__ packages will now download Node versions that are not included with the agent and not blocked under 'Task restrictions' in organization settings. This allows customers to use __pipelines-agent-*__ agent packages and control the installation of Node 6 with 'Task restrictions' in organization settings. + +### Deferred approval + +Approvals can be used to sign off on a deployment. However, there are situations when the time when the approval is given and the time the deployment should start don't match. For example, for the particular deployment you review, you know it's an out-of-bounds one. Imagine it can't proceed immediately, rather it should take place during the night. + +To cover such scenarios, we've added the option to defer approvals for YAML pipelines. Now, you can approve a pipeline run and specify when should the approval be effective. + +> [!div class="mx-imgBorder"] +> ![Screenshot of approve a pipeline run.](../../media/234-pipelines-14.png "Screenshot of approve a pipeline run") + +When you select _Defer approval_, you can configure the time when the approval becomes effective. + +> [!div class="mx-imgBorder"] +> ![Screenshot of Defer approval.](../../media/234-pipelines-15.png "Screenshot of Defer approval") + +> [!div class="mx-imgBorder"] +> ![Screenshot of after_approval_deferred.](../../media/234-pipelines-16.png "Screenshot of after_approval_deferred") + +The approval shows up as deferred in the checks panel. After the deferred-to time, the approval is effective. + +> [!div class="mx-imgBorder"] +> ![Screenshot of approval is effective.](../../media/234-pipelines-17.png "Screenshot of approval is effective") + + +### Sequencing approvals and checks + +With this sprint, you're able to specify the order in which approvals and checks run. + +[Approvals and checks](/azure/devops/pipelines/process/approvals) allow you to control deployments to production. For example, you can specify that only pipelines that run on the `main` branch of a repository are allowed to use a production ARM service connection. Furthermore, you can require human approval and that the system passes a performance check. + +Up until today, all approvals, and checks ran in parallel, except for exclusive lock. This meant that if your deployment process required performance checks to pass before manual approval is given, you couldn't enforce this in Azure Pipelines. You had to rely on approval instructions and internal process documentation. + +With this sprint, we're introducing sequencing in Approvals and Checks. There are now five categories of Approvals and Checks: + +1. Static checks: Branch control, Required template, and Evaluate artifact +2. Pre-dynamic checks Approval +3. Dynamic checks: Approval, Invoke Azure Function, Invoke REST API, Business Hours, Query Azure Monitor alerts +4. Post-dynamic checks Approval +5. Exclusive lock + +> [!div class="mx-imgBorder"] +> ![Screenshot of add check.](../../media/234-pipelines-10.png "Screenshot of add check") + +The order is shown also in the Approvals and checks tab. + +> [!div class="mx-imgBorder"] +> ![Screenshot of approvals and checks tab.](../../media/234-pipelines-11.png "Screenshot of approvals and checks tab") + +Within each category, the checks run in parallel. That is, if you have an Invoke Azure Function check and a Business hours check, they run at the same time. + +> [!div class="mx-imgBorder"] +> ![Screenshot of checks for deploy.](../../media/234-pipelines-12.png "Screenshot of checks for deploy") + +Check categories run one by one and if one fails, the rest of the checks aren't executed. This means that if you have a Branch control check and an Approval, if the Branch control fails, the Approval will fail, too. So no needless emails will be sent. + +> [!div class="mx-imgBorder"] +> ![Screenshot of checks for deploy fail.](../../media/234-pipelines-13.png "Screenshot of checks for deploy fail") + +You can sign off on a deployment after all dynamic checks ran, using a post-dynamic checks Approval, or do a manual validation before proceeding with dynamic checks, using a pre-dynamic checks Approval. + +### Validate and Save by default when editing YAML pipelines + +An incorrect YAML pipeline can lead to wasted time and effort. To improve your pipeline editing productivity, we're changing the _Save_ button in the editor to also do YAML validation. + +> [!div class="mx-imgBorder"] +> ![Screenshot of new button.](../../media/234-pipelines-05.png "Screenshot of new button") + +> [!div class="mx-imgBorder"] +> ![Screenshot of validate and save.](../../media/234-pipelines-06.png "Screenshot of validate and save") + +If your pipeline has errors, you'll still be able to save it. + +> [!div class="mx-imgBorder"] +> ![Screenshot of pipeline is valid.](../../media/234-pipelines-07.png "Screenshot of save anyway") + +> [!div class="mx-imgBorder"] +> ![Screenshot of errors detected.](../../media/234-pipelines-08.png "Screenshot of errors detected") + + +We also improved the _Validate_ experience, so you can see the errors in a list that's easier to understand. + +> [!div class="mx-imgBorder"] +> ![Screenshot of errors list.](../../media/234-pipelines-09.png "Screenshot of errors list") + + diff --git a/release-notes/2024/includes/pipelines/sprint-235-update-links.md b/release-notes/2024/includes/pipelines/sprint-235-update-links.md new file mode 100644 index 00000000000..7888090b00d --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-235-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +ms.topic: include +--- + +- [Rerun a single stage](#rerun-a-single-stage) diff --git a/release-notes/2024/includes/pipelines/sprint-235-update.md b/release-notes/2024/includes/pipelines/sprint-235-update.md new file mode 100644 index 00000000000..c1686287530 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-235-update.md @@ -0,0 +1,21 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +ms.topic: include +--- + +### Rerun a single stage + +You can perform a rollback in YAML pipelines by rerunning a stage from a previous pipeline run that succeeded. + +With this sprint, you can rerun a single stage, without having to rerun its dependent stages. + +> [!div class="mx-imgBorder"] +> ![Screenshot of rerun this stage.](../../media/235-pipelines-01.png "Screenshot of rerun this stage") + +As before, you can still rerun a stage _and_ its dependent stages (if any). + +> [!div class="mx-imgBorder"] +> ![Screenshot of rerun stage and dependents.](../../media/235-pipelines-02.png "Screenshot of rerun stage and dependents") + diff --git a/release-notes/2024/includes/pipelines/sprint-236-update-links.md b/release-notes/2024/includes/pipelines/sprint-236-update-links.md new file mode 100644 index 00000000000..b974ced7a5e --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-236-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 3/26/2024 +ms.topic: include +--- + +- [Azure service connections indicate when a secret has expired](#azure-service-connections-indicate-when-a-secret-has-expired) +- [New AzureFileCopy@6 task supports secret-less configurations](#new-azurefilecopy6-task-supports-secret-less-configurations) +- [Resource utilization alerts for Azure Pipeline agents](#resource-utilization-alerts-for-azure-pipeline-agents) diff --git a/release-notes/2024/includes/pipelines/sprint-236-update.md b/release-notes/2024/includes/pipelines/sprint-236-update.md new file mode 100644 index 00000000000..272eca4f9ac --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-236-update.md @@ -0,0 +1,38 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 3/26/2024 +ms.topic: include +--- + +### Azure service connections indicate when a secret has expired + +With this sprint, you can now see the expiration status of secrets in Azure service connections. If your tasks show an error due to an expired secret, such as messages with "AADSTS7000222," go to the service connection details page. If you see this message,the service connection's secret has expired: + +> [!div class="mx-imgBorder"] +> ![Screenshot of secret has expired.](../../media/236-pipelines-02.png "Screenshot of secret has expired") + +To fix the service connection, you can [convert](https://aka.ms/azdo-rm-workload-identity-conversion) it to use workload identity federation. This approach removes the necessity for rotating secrets, offering a more streamlined and secure management process. + +### New AzureFileCopy@6 task supports secret-less configurations + +You might [block](/azure/storage/common/shared-key-authorization-prevent?tabs=portal) the use of storage account keys and SAS tokens on your storage accounts. In these situations the AzureFileCopy@5 task, which relies on SAS tokens, can't be used. + +The new [AzureFileCopy@6](/azure/devops/pipelines/tasks/reference/azure-file-copy-v6) task uses Azure RBAC to access blob storage instead. This requires the identity of the service connection used to have the appropriate RBAC role e.g. [Storage Blob Data Contributor](/azure/role-based-access-control/built-in-roles/storage#storage-blob-data-contributor). See [Assign an Azure role for access to blob data](/azure/storage/blobs/assign-azure-role-data-access?tabs=portal). + +The [AzureFileCopy@6](/azure/devops/pipelines/tasks/reference/azure-file-copy-v6) task also supports service connections that use [workload identity federation](https://aka.ms/azdo-rm-workload-identity). + +### Resource utilization alerts for Azure Pipeline agents + +[Last October](/azure/devops/release-notes/2023/pipelines/sprint-228-update#pipeline-logs-now-contain-resource-utilization), we introduced the ability to monitor memory and disk space utilization by the Pipelines agent. + +To inform you about these constraints, we've improved the visibility of resource constraint alerts: + +> [!div class="mx-imgBorder"] +> ![Screenshot of Limited memory and disk space warning.](../../media/236-pipelines-01.png "Screenshot of Limited memory and disk space warning") + +Should you encounter messages indicating a lack of responsiveness from the agent, it could signify that a task is exceeding the resource capabilities allocated to the agent, potentially causing pipeline job failures. + +> "We stopped hearing from the agent" + +To address this, enable [verbose logs](/azure/devops/pipelines/troubleshooting/review-logs#configure-verbose-logs) for more detailed tracking of resource utilization, helping to pinpoint where resources are being exhausted. For those utilizing a self-hosted agent, ensure your agent has sufficient resources. diff --git a/release-notes/2024/includes/pipelines/sprint-237-update-links.md b/release-notes/2024/includes/pipelines/sprint-237-update-links.md new file mode 100644 index 00000000000..99f9a9f8b61 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-237-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/10/2024 +ms.topic: include +--- + +- [Edit queue build configuration permission](#edit-queue-build-configuration-permission) +- [TFX validates whether a task is using an End of Life Node runner](#tfx-validates-whether-a-task-is-using-an-end-of-life-node-runner) + diff --git a/release-notes/2024/includes/pipelines/sprint-237-update.md b/release-notes/2024/includes/pipelines/sprint-237-update.md new file mode 100644 index 00000000000..8ea93ce864f --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-237-update.md @@ -0,0 +1,62 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/10/2024 +ms.topic: include +--- + +### Edit queue build configuration permission + +To help you improve the security posture of your pipelines, we're adding a new pipeline permission named _Edit queue build configuration_ that controls who can define the values of variables set at queue time and of free-text runtime parameters. + +> [!div class="mx-imgBorder"] +> ![Screenshot of permissions.](../../media/237-pipelines-02.png "Screenshot of permissions") + +Variables set at queue time and parameters allow you to write configurable YAML pipelines. Unfortunately, they also introduce the possibility of user input to be executed. The new permission mitigates this risk. + +Users who have only _Queue build_ permission are able to queue builds and edit the values of runtime parameters that have a predefined set of values. That is, they're able to choose values for parameters that are of type `boolean`, `number` or they have the `values` property set. + +If a parameter can contain free text, for example, is of type `object`, then only those users who have the _Edit queue build configuration_ permission are able to set it. + +Consider a pipeline with the following parameters defined: +```yaml +parameters: +- name: Configuration + type: string + values: + - release + - debug + default: debug +- name: UseNewDeploymentMethod + type: boolean + default: false +- name: AzureSKU + type: object + default: + WUS1: Standard D2lds v5 + WUS2: Standard D2lds v5 + WUS3: Standard D2lds v5 +``` + +If a user queueing a run has only the _Queue build_ permission. When they queue the pipeline, they'll be able to only specify the values of the `Configuration` and `UseNewDeploymentMethod` parameters. They won't be able to specify the value for the `AzureSKU` parameter. + +> [!div class="mx-imgBorder"] +> ![Screenshot of run pipeline.](../../media/237-pipelines-03.png "Screenshot of run pipeline") + +Changing variables marked as settable at queue time also requires the _Edit queue build configuration_ permission. Otherwise, one can't change the variable value. + +> [!div class="mx-imgBorder"] +> ![Screenshot of variables.](../../media/237-pipelines-04.png "Screenshot of variables") + +To make sure the new permission doesn't interfere with your day-to-day workloads, everyone who has _Queue build_ permission receives the _Edit queue build configuration_ permission. Afterward, you can remove this permission as needed. + +### TFX validates whether a task is using an End of Life Node runner + +Task authors use [TFX](/azure/devops/extend/publish/command-line#prerequisites) to publish extensions. TFX has been updated to perform validations on other Node runner versions. + +Extensions that contain tasks using a Node runner version that is end of life (EOL) (up to and including Node 16) will see this warning: + + +*Task < TaskName > is dependent on a task runner that is end-of-life and are removed in the future. Authors should review Node upgrade guidance: https://aka.ms/node-runner-guidance* + + diff --git a/release-notes/2024/includes/pipelines/sprint-238-update-links.md b/release-notes/2024/includes/pipelines/sprint-238-update-links.md new file mode 100644 index 00000000000..4cec298b5aa --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-238-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 5/2/2024 +ms.topic: include +--- + +- [macOS-14 Sonoma preview and macOS-11 retirement ](#macos-14-sonoma-preview-and-macos-11-retirement ) +- [Node 10 removed from pipelines-* Agent packages ](#node-10-removed-from-pipelines--agent-packages) + diff --git a/release-notes/2024/includes/pipelines/sprint-238-update.md b/release-notes/2024/includes/pipelines/sprint-238-update.md new file mode 100644 index 00000000000..de545ee5730 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-238-update.md @@ -0,0 +1,51 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 5/2/2024 +ms.topic: include +--- + +### macOS-14 Sonoma preview and macOS-11 retirement + +The `macOS-14` image is now available in preview for Azure Pipelines hosted agents. To use this image, update your YAML file to include `vmImage:'macos-14'`: + +```yaml +- job: macOS14 + pool: + vmImage: 'macOS-14' + steps: + - bash: | + echo Hello from macOS Sonoma Preview + sw_vers +``` + +For macOS-14 installed software, see [image configuration](https://github.com/actions/runner-images/blob/main/images/macos/macos-14-Readme.md). + +The `macOS-12` image will still be used when specifying `macOS-latest`. Once `macOS-14` is generally available, `macOS-latest` will migrate directly to `macOS-14`. The `macOS-latest` label will skip macOS-13. + +The `macOS-11` image is deprecated and will be retired June 2024. + + +### Node 10 removed from pipelines-* Agent packages + +Our agents support tasks implemented in PowerShell or Node. The agent ships with multiple versions of Node accommodating different task requirements. + +As new versions of Node are released, [tasks](https://github.com/microsoft/azure-pipelines-tasks) are updated to utilize these newer Node versions. The required runtimes are included with the agent. + +However, as older Nodes exit their maintenance window, some Pipelines tasks might still depend on them. Azure DevOps updates supported tasks to a Node version that's still supported, although third-party tasks might require older versions to run. + +To manage this, we have two Pipeline agents [packages](https://github.com/microsoft/azure-pipelines-agent/releases): + +| Packages | Node versions | Description | +|----------------------|---------------|----------------------------| +| `vsts-agent-*` | 6, 10, 16, 20 | Includes all Node versions that can be used as task execution handler | +| `pipelines-agents-*` | 16, 20 | Includes only recent Node versions. The goal for these packages is to not include any end-of-life version of Node. | + +If you want to run a task that requires the Node 10 execution handler on an agent that doesn't have Node 10 bundled, you can install the execution handler by inserting the [NodeTaskRunnerInstaller@0](/azure/devops/pipelines/tasks/reference/node-task-runner-installer-v0) task in your pipeline: + +```yaml + steps: + - task: NodeTaskRunnerInstaller@0 + inputs: + runnerVersion: 10 +``` diff --git a/release-notes/2024/includes/pipelines/sprint-240-update-links.md b/release-notes/2024/includes/pipelines/sprint-240-update-links.md new file mode 100644 index 00000000000..1d4d1b0b1f8 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-240-update-links.md @@ -0,0 +1,12 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +ms.topic: include +--- + +- [Access Azure Service Bus from Pipelines using Microsoft Entra ID authentication](#access-azure-service-bus-from-pipelines-using-microsoft-entra-id-authentication) +- [Pipelines and tasks populate variables to customize Workload identity federation authentication](#pipelines-and-tasks-populate-variables-to-customize-workload-identity-federation-authentication) +- [Retries for server tasks](#retries-for-server-tasks) +- [Tasks that use an end-of-life Node runner version to execute emit warnings](#tasks-that-use-an-end-of-life-node-runner-version-to-execute-emit-warnings) +- [DockerCompose0 uses Docker Compose v2 in v1 compatibility mode](#dockercompose0-uses-docker-compose-v2-in-v1-compatibility-mode) diff --git a/release-notes/2024/includes/pipelines/sprint-240-update.md b/release-notes/2024/includes/pipelines/sprint-240-update.md new file mode 100644 index 00000000000..4da65c27fe6 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-240-update.md @@ -0,0 +1,199 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +ms.topic: include +--- + +### Access Azure Service Bus from Pipelines using Microsoft Entra ID authentication + +You can now use [Microsoft Entra ID authentication](/azure/service-bus-messaging/service-bus-authentication-and-authorization#microsoft-entra-id) to access Azure Service Bus from Azure Pipelines. This allows you to take advantage of Workload identity federation to remove secrets management and Azure RBAC for fine grained access control. + +Identities accessing Azure Service Bus need to be granted one of the [Azure built-in roles for Azure Service Bus](/azure/service-bus-messaging/authenticate-application#azure-built-in-roles-for-azure-service-bus) on the Service Bus accessed. + + +##### PublishToAzureServiceBus@2 task + +The new PublishToAzureServiceBus@2 tasks can be configured using an Azure service connection. Create an [Azure service connection](/azure/devops/pipelines/library/connect-to-azure?view=azure-devops&preserve-view=true) and populate the `serviceBusQueueName` and `serviceBusNamespace` properties of the new task: + +```yaml +- task: PublishToAzureServiceBus@2 + inputs: + azureSubscription: my-azure-service-connection + serviceBusQueueName: my-service-bus-queue + serviceBusNamespace: my-service-bus-namespace + useDataContractSerializer: false + messageBody: | + { + "foo": "bar" + } +``` + +##### Server tasks + +Custom server (agent-less) tasks that use `ServiceBus` execution can specify an Azure Service Connection as `EndpointId` and omit `ConnectionString`. See [Server task authoring](https://github.com/microsoft/azure-pipelines-tasks/blob/master/docs/authoring/servertaskauthoring.md#server-task-authoring). + +### Pipelines and tasks populate variables to customize Workload identity federation authentication + +The REST API endpoint for requesting OIDC tokens is now available in the `System.OidcRequestUri` pipeline variable. Task developers can leverage this variable to generate an idToken for authentication with Entra ID. + +If you are using Marketplace tasks or custom tasks to deploy to Azure, please be aware that these tasks may not support workload identity federation yet. We recommend task developers to enable workload identity federation to improve security measures. + +> [!div class="mx-imgBorder"] +> ![Screenshot of oidc collaboration.](../../media/240-pipelines-01.png "Screenshot of oidc collaboration") + + +Tasks that take a `connectedService:AzureRM` input in [task.json](/azure/devops/extend/develop/integrate-build-task#custom-build-task-json) can be updated to support workload identity federation by following these steps: + +* Utilize the [Oidctoken REST API](/rest/api/azure/devops/distributedtask/oidctoken/create?view=azure-devops-rest-7.2&preserve-view=true) to request an idToken (arrow 1 in above diagram). +* Exchange the idToken for an access token using the federated credential flow of the [OAuth API](/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#third-case-access-token-request-with-a-federated-credential), specifying the idToken as `client_assertion` (arrows 2 & 4 in above diagram); + or: +* For tasks that act as a wrapper around a tool that performs authentication itself, use the tools' authentication method to specify the federated token. + +Node tasks can use the [azure-pipelines-tasks-artifacts-common](https://www.npmjs.com/package/azure-pipelines-tasks-artifacts-common?activeTab=explore) npm package to obtain the idToken. Refer to the [code example](https://github.com/microsoft/azure-pipelines-terraform/blob/main/Tasks/TerraformTask/TerraformTaskV4/src/id-token-generator.ts) for implementation details. + + +##### Requesting a fresh idToken + +The `System.OidcRequestUri` pipeline variable and `AZURESUBSCRIPTION_SERVICE_CONNECTION_ID` environment variable exposed in the `AzureCLI@2` and `AzurePowerShell@5` tasks allow pipeline authors to authenticate from their own script: + +##### PowerShell Az + +```powershell +- task: AzurePowerShell@5 + inputs: + azureSubscription: 'my-azure-subscription' + scriptType: inlineScript + inline: | + # Request fresh idToken + Invoke-RestMethod -Headers @{ + Authorization = "Bearer $(System.AccessToken)" + 'Content-Type' = 'application/json' + } ` + -Uri "${env:SYSTEM_OIDCREQUESTURI}?api-version=7.1&serviceConnectionId=${env:AZURESUBSCRIPTION_SERVICE_CONNECTION_ID}" ` + -Method Post ` + | Select-Object -ExpandProperty oidcToken + | Set-Variable idToken + + # Fetch current context + $azContext = Get-AzContext + + # Start new Az session + Connect-AzAccount -ApplicationId $azContext.Account.Id ` + -TenantId $azContext.Tenant.Id ` + -SubscriptionId $azContext.Subscription.Id ` + -FederatedToken $idToken +``` + +##### Azure CLI + +```bash +- task: AzureCLI@2 + inputs: + addSpnToEnvironment: true + azureSubscription: 'my-azure-subscription' + scriptType: bash + scriptLocation: inlineScript + inlineScript: | + # Request fresh idToken + OIDC_REQUEST_URL="${SYSTEM_OIDCREQUESTURI}?api-version=7.1&serviceConnectionId=${AZURESUBSCRIPTION_SERVICE_CONNECTION_ID}" + ARM_OIDC_TOKEN=$(curl -s -H "Content-Length: 0" -H "Content-Type: application/json" -H "Authorization: Bearer $(System.AccessToken)" -X POST $OIDC_REQUEST_URL | jq -r '.oidcToken') + + # Save subscription context + ARM_SUBSCRIPTION_ID=$(az account show --query id -o tsv) + + # New az-cli session + az login --service-principal -u $servicePrincipalId --tenant $tenantId --allow-no-subscriptions --federated-token $ARM_OIDC_TOKEN + az account set --subscription $ARM_SUBSCRIPTION_ID +``` + +### Retries for server tasks + +Server tasks that call external systems, such as `AzureFunction` or `InvokeRESTAPI`, can occasionally fail due to transient errors like compute resource exhaustion. Previously, such failures would cause the entire job, and potentially the pipeline, to fail. + +To improve resilience against transient errors, we have introduced support for the `retryCountOnTaskFailure` property in server tasks. Assume you have the following YAML code in your pipeline: + +```yml +- stage: deploy + jobs: + - job: + pool: server + steps: + - task: AzureFunction@1 + retryCountOnTaskFailure: 2 + inputs: + function: 'https://api.fabrikamfiber.com' + key: $(functionKey) + method: 'POST' + waitForCompletion: 'false' +``` + +If `https://api.fabrikamfiber.com` experiences a transient error, Azure Pipelines will retry the request up to three times (the initial attempt plus two retries specified by `retryCountOnTaskFailure`). Each retry includes an increasing wait period. The maximum number of retries allowed is 10. + +The `retryCountOnTaskFailure` isn't available for the `ManualValidation` task and other tasks that don't involve external system calls. + +### Tasks that use an end-of-life Node runner version to execute emit warnings + +Pipeline tasks that rely on a Node version no longer [maintained](https://nodejs.org/en/about/previous-releases) will start receiving warnings: + +> Task `TaskName` version `` is dependent on a Node version (10) that is end-of-life. Contact the extension owner for an updated version of the task. Task maintainers should review Node upgrade guidance: https://aka.ms/node-runner-guidance + +To suppress these warnings, you can set an environment or pipeline variable at either the pipeline (job) or task level. For example: + +```yaml +variables: + AZP_AGENT_CHECK_IF_TASK_NODE_RUNNER_IS_DEPRECATED: false +``` + +### DockerCompose@0 uses Docker Compose v2 in v1 compatibility mode + +Docker Compose v1 will reach its end-of-life and will be removed from Hosted Agents July 24 2024. We have updated the [DockerCompose@0](/azure/devops/pipelines/tasks/reference/docker-compose-v0) task to use Docker Compose v2 in v1 compatibility mode if Docker Compose v1 is not available on the agent. + +However, compatibility mode does not address all compatibility issues. See [Migrate to Compose V2](https://docs.docker.com/compose/migrate/). Some users will need more time to update their Docker Compose projects for Docker Compose v2 compatibility. In those cases, follow these instructions to use the **DockerComposeV0** task with **docker-compose v1**. + +> **_NOTE_**: This guide is based on [Install Compose standalone](https://docs.docker.com/compose/install/standalone) documentation + +#### Use docker-compose v1 on Windows +Add the powershell step to your pipeline to download the **docker-Compose v1.29.2** and use it with the **DockerComposeV0** task on **Windows**: + +```yaml +variables: + dockerComposePath: C:\docker-compose + +steps: +- powershell: | + mkdir -f $(dockerComposePath) + # GitHub now requires TLS1.2. In PowerShell, run the following + [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 + Start-BitsTransfer -Source "https://github.com/docker/compose/releases/download/1.29.1/docker-compose-windows-x86_64.exe" -Destination $(dockerComposePath)\docker-compose.exe + displayName: Download docker-compose +- task: DockerCompose@0 + inputs: + containerregistrytype: 'Azure Container Registry' + dockerComposeFile: '**/docker-compose.yml' + action: 'Run a Docker Compose command' + dockerComposeCommand: 'run' + dockerComposePath: $(dockerComposePath)\docker-compose.exe +``` + +#### Use docker-compose v1 on Linux +Add the bash step to your pipeline to download **Docker-Compose v1.29.2** and use it with the **DockerComposeV0** task on **Linux**: + +```yaml +variables: + dockerComposePath: /tmp/docker-compose + +steps: +- bash: | + sudo mkdir $(dockerComposePath) + sudo curl -SL https://github.com/docker/compose/releases/download/1.29.2/docker-compose-linux-x86_64 -o $(dockerComposePath)/docker-compose + sudo chmod 755 $(dockerComposePath)/docker-compose + displayName: Download docker-compose +- task: DockerCompose@0 + inputs: + containerregistrytype: 'Azure Container Registry' + dockerComposeFile: $(Build.SourcesDirectory)/DockerComposeV0/docker-compose.yml + action: 'Run a Docker Compose command' + dockerComposeCommand: 'run' + dockerComposePath: $(dockerComposePath)/docker-compose +``` diff --git a/release-notes/2024/includes/pipelines/sprint-241-update-links.md b/release-notes/2024/includes/pipelines/sprint-241-update-links.md new file mode 100644 index 00000000000..ebff20bfff0 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-241-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 7/3/2024 +ms.topic: include +--- + +- [AzureFileCopy, AzurePowerShell, and SqlAzureDacpacDeployment tasks use Az modules only](#azurefilecopy-azurepowershell-and-sqlazuredacpacdeployment-tasks-use-az-modules-only) +- [Use Workload identity federation for container jobs, resources, and tasks](#use-workload-identity-federation-for-container-jobs-resources-and-tasks) diff --git a/release-notes/2024/includes/pipelines/sprint-241-update.md b/release-notes/2024/includes/pipelines/sprint-241-update.md new file mode 100644 index 00000000000..6b5916e0813 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-241-update.md @@ -0,0 +1,17 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 7/3/2024 +ms.topic: include +--- + +### AzureFileCopy, AzurePowerShell, and SqlAzureDacpacDeployment tasks use Az modules only + +The AzureFileCopy, AzurePowerShell, and SqlAzureDacpacDeployment tasks can no longer use AzureRM modules. As of February 2024, the [AzureRM PowerShell module was deprecated](/powershell/azure/migrate-from-azurerm-to-az) and is no longer supported. While the AzureRM module may still function, it’s no longer maintained, placing any continued use at your discretion. Tasks that previously could use both AzureRmM or Az modules now only use Az modules. If you use tasks on self-hosted agents ensure the [Az module](/powershell/azure/install-azure-powershell) is pre-installed on your images. + +### Use Workload identity federation for container jobs, resources, and tasks + +Docker service connections targeting Azure Container Registry can now use Workload Identity Federation, eliminating the need for secrets. For an updated list of tasks supporting Workload Identity Federation, please refer to [our documentation](https://aka.ms/azdo-rm-workload-identity-tasks). + +> [!div class="mx-imgBorder"] +> ![Screenshot of oidc collaboration.](../../media/241-pipelines-01.png "Screenshot of oidc collaboration") diff --git a/release-notes/2024/includes/pipelines/sprint-242-update-links.md b/release-notes/2024/includes/pipelines/sprint-242-update-links.md new file mode 100644 index 00000000000..44bcd835ae7 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-242-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 7/25/2024 +ms.topic: include +--- + +- [Unskippable stages](#unskippable-stages) \ No newline at end of file diff --git a/release-notes/2024/includes/pipelines/sprint-242-update.md b/release-notes/2024/includes/pipelines/sprint-242-update.md new file mode 100644 index 00000000000..425fc2ffb79 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-242-update.md @@ -0,0 +1,25 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 7/25/2024 +ms.topic: include +--- + +### Unskippable stages + +You can use [YAML templates](/azure/devops/pipelines/security/templates) as a security mechanism, for example, to inject a stage that performs malware detection in all pipelines. However, Pipeline end users can choose which stages to run, potentially skipping the malware detection stage. + +With this sprint, you can mark a YAML stage as unskippable using the new `isSkippable` property. By default, the value of this property is `true`. To prevent skipping a stage, set it to `false`, as shown in the example below: +``` yaml +- stage: sdl_check_stage + displayName: SDL Stage + isSkippable: false + jobs: + - job: sdl_check_job + ... +``` + +These stages will always execute and can't be deselected in the _Stages to run_ configuration panel. + +> [!div class="mx-imgBorder"] +> ![Screenshot of stages to run.](../../media/242-pipelines-01.png "Screenshot of stages to run") diff --git a/release-notes/2024/includes/pipelines/sprint-243-update-links.md b/release-notes/2024/includes/pipelines/sprint-243-update-links.md new file mode 100644 index 00000000000..f9a34d74806 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-243-update-links.md @@ -0,0 +1,13 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/13/2024 +ms.topic: include +--- + +- [Managed DevOps Pools (Preview)](#managed-devops-pools-preview) +- [Azure Pipelines tasks use Node 20](#azure-pipelines-tasks-use-node-20) +- [Create build pipeline permission](#create-build-pipeline-permission) +- [Exclusive lock check at stage level](#exclusive-lock-check-at-stage-level) +- [Template information in pipeline runs](#template-information-in-pipeline-runs) +- [Manually triggered YAML pipeline stages](#manually-triggered-yaml-pipeline-stages) diff --git a/release-notes/2024/includes/pipelines/sprint-243-update.md b/release-notes/2024/includes/pipelines/sprint-243-update.md new file mode 100644 index 00000000000..a641c487529 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-243-update.md @@ -0,0 +1,147 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 8/13/2024 +ms.topic: include +--- + +### Managed DevOps Pools (preview) + +Engineering teams excel when they can focus on writing code to develop applications and services for their users. However, in practice, a substantial amount of time is often spent managing other tasks, such as maintaining DevOps infrastructure. + +We're excited to announce the public preview of [Managed DevOps Pools (MDP)](https://aka.ms/mdp-docs), a new Azure DevOps feature designed to help development and platform engineering teams deploy custom DevOps pools tailored to their unique needs. MDP combines the flexibility of Scale Set agents with the ease of maintenance associated with Microsoft-hosted agents, enabling teams to establish consistency and best practices while optimizing performance, security, compliance, and cost-efficiency. + +Key benefits of Managed DevOps Pools include: + +* **Hosted on your behalf:** MDP is hosted and managed by Microsoft, with the virtual machines powering the agents created and maintained within Microsoft-owned Azure subscriptions. +* **Time spent in Management:** MDP significantly reduces the time spent managing agents, particularly those based on on-premises infrastructure or manually maintained systems. +* **Specific Pools:** Due to the ease with which new pools can be created, organizations can easily create multiple team-specific or workload-specific pools. +* **DevOps Billing:** MDP helps optimize a team’s DevOps bill through many features. It makes it easy for teams to find an optimal balance between a pool’s QoS/performance and cost. +* **Scalable:** MDP scales to 1000s of agents in a single pool. + +Teams can create pools with [quick-starter images](/azure/devops/managed-devops-pools/configure-images#azure-pipelines-images) that contain the same software present in Microsoft hosted agents or with images the team has created with prerequisites that are unique to their scenario. + +Learn more about Managed DevOps Pools by reading our [blog post](https://devblogs.microsoft.com/devops/managed-devops-pools/) or its [documentation](https://aka.ms/mdp-docs). + + +### Azure pipelines tasks use Node 20 + +Most pipeline tasks use Node as a runner. Azure pipelines task that use NodeJS as a runner now all use NodeJS 20. Authors of task extensions should update their tasks to use Node 20. For guidance on how to upgrade see, [How can I upgrade my custom task to the latest Node?](https://aka.ms/node-runner-guidance). + +### Create build pipeline permission + +To increase pipeline security, we're introducing a new permission, `Create build pipeline`, at pipelines level. + +> [!div class="mx-imgBorder"] +> [![Screenshot of create build pipeline permission.](../../media/243-pipelines-01.png "Screenshot of create build pipeline permission")](../../media/243-pipelines-01.png#lightbox) + +Previously, the `Edit build pipeline` permission was required to create or edit a pipeline. This posed a security risk, as it allowed all users with the ability to create pipelines to also edit pipelines they didn't create. Preventing this was time-consuming. + +To enhance your pipeline experience without compromising security, all users and groups with the `Edit build pipeline` permission will now also receive the `Create build pipeline` permission. + +When a pipeline is created, its creator is granted the `Edit build pipeline` permission. + +For improved pipeline security, you may choose to remove the `Edit build pipeline` permission from user groups such as **Contributors** and **Readers**. This ensures that, by default, only the pipeline's creator can edit it. + +> [!NOTE] +> The **Edit build pipeline** permission does not prevent others from editing a YAML pipeline; it only protects the pipeline's properties from being edited. + +For new projects, users and groups with the `Edit build pipeline` permission will also have the *`Create build pipeline`* permission. This is subject to change in the future. + +### Exclusive lock check at stage level + +Some use cases require a pipeline to access a specific resource only once at any given time. To support this case, we have the [Exclusive lock](/azure/devops/pipelines/process/approvals#exclusive-lock) check. + +A similar situation arises when only one pipeline run should access a stage at any point in time. For instance, if you have a stage that deploys to an Azure resource group, you may want to prevent multiple pipeline runs from simultaneously updating the same resource group. Currently, achieving this requires using a proxy resource, such as an environment, and placing the Exclusive lock check on that environment. This approach can be time-consuming, add complexity, and increase maintenance efforts. + +In this sprint, we’re introducing support for specifying the exclusive lock at the stage level. If you have a stage with an ID and specify its `lockBehavior` property, a lock is automatically created for that stage. The `sequential` behavior remains consistent for both resource-level and stage-level locks. However, the `runLatest` behavior differs, as it only cancels `runLatest` builds for the same branch, not for all branches of the pipeline. + + +### Template information in pipeline runs + +We updated the [Pipelines Runs - Get](/rest/api/azure/devops/pipelines/runs/get#run) REST API with information about the templates extended and included in a pipeline run. + +For example, consider you have the following YAML pipeline code: +```yml +extends: + template: template-stages.yml@templates + parameters: + stages: + - stage: deploy + jobs: + - job: + steps: + - template: template-step.yml +``` + +The new REST API has the following new properties: +```yml +"yamlDetails": + { + "extendedTemplates": + [ + { + "yamlFile": "template-stages.yml", + "repoAlias": "templates" + } + ], + "includedTemplates": + [ + { + "yamlFile": "template-step.yml", + "repoAlias": "templates" + } + ], + "rootYamlFile": + { + "ref": "refs/heads/main", + "yamlFile": "azure-pipelines.yml", + "repoAlias": "self" + }, + "expandedYamlUrl": "https://dev.azure.com/fabrikamfiber/161cfeeb-d9fd-395c-917b-fec46db44fbb/_apis/build/builds/39224/logs/1" + } +``` + +### Manually triggered YAML pipeline stages + +We frequently receive requests about manually triggered YAML pipeline stages. These are helpful when you want a unified pipeline but don’t always want it to run to completion. + +For instance, your pipeline might include stages for building, testing, deploying to a staging environment, and deploying to production. You might want all stages to run automatically except for the production deployment, which you prefer to trigger manually when ready. + +With this sprint, we're adding support for manually triggered YAML pipeline stages. To use this feature, you need to add the `trigger: manual` property to a stage. + +Consider the following YAML pipeline example: +```yaml +stages: +- stage: stage_WUS1 + displayName: Deploy WUS1 + trigger: manual + jobs: + - job: DeployJob + steps: + - task: AzureCLI@2 + inputs: + azureSubscription: 'AzureWIF' + scriptType: 'ps' + scriptLocation: 'inlineScript' + inlineScript: 'Write-host ''hello, world''' +- stage: stage_WUS2 + displayName: Deploy WUS2 + trigger: manual + jobs: + - job: DeployJob + steps: + - task: AzureCLI@2 + inputs: + azureSubscription: 'AzureWIF' + scriptType: 'ps' + scriptLocation: 'inlineScript' + inlineScript: 'Write-host ''hello, world''' +``` + +When you run this pipeline, the experience is as follows: + +> [!div class="mx-imgBorder"] +> ![Screenshot of manually triggered YAML pipeline stages.](../../media/243-pipelines-02.png "Screenshot of manually triggered YAML pipeline stages") + +Manually triggered stages have no dependencies and can be run at any time. The pipeline run completes when there are only manually triggered stages left to execute. \ No newline at end of file diff --git a/release-notes/2024/includes/pipelines/sprint-244-update-links.md b/release-notes/2024/includes/pipelines/sprint-244-update-links.md new file mode 100644 index 00000000000..45dd0184687 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-244-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +ms.topic: include +--- + +- [Announcing deprecation of Pipeline Tasks](#announcing-deprecation-of-pipeline-tasks) +- [The Pipelines agent will show warnings for agents running Operating Systems not supported by .NET 8](#the-pipelines-agent-will-show-warnings-for-agents-running-operating-systems-not-supported-by-net-8) \ No newline at end of file diff --git a/release-notes/2024/includes/pipelines/sprint-244-update.md b/release-notes/2024/includes/pipelines/sprint-244-update.md new file mode 100644 index 00000000000..e547a820544 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-244-update.md @@ -0,0 +1,60 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +ms.topic: include +--- + +### Announcing deprecation of Pipeline Tasks + +Azure Pipelines has around 200 tasks [included in the product](/azure/devops/pipelines/tasks/reference). Many of those are versions of the same task e.g. AzurePowerShell@2 and AzurePowerShell@5. Our AzureFileCopy task even has 6 versions. Whenever we change the behavior of a task or the task is wrapping a new major version of a tool, we introduce a new task version. Recent examples are the [PublishToAzureServiceBus@2](/azure/devops/release-notes/2024/pipelines/sprint-240-update#publishtoazureservicebus2-task), [AzureFileCopy@6](/azure/devops/release-notes/2024/pipelines/sprint-236-update#new-azurefilecopy6-task-supports-secret-less-configurations) and [PublishCodeCoverageResults@1](https://devblogs.microsoft.com/devops/new-pccr-task) tasks. + +To inform users they are using an older version of a task and may not be taking advantage of the latest functionality, we are deprecating some of the older tasks. Deprecated tasks will emit a warning and guidance on alternatives, their behavior is unchanged. +Deprecated tasks will ultimately get removed. However, we have no planned date for retirement for the tasks in the below list. Retirement of tasks will be communicated separately at a later time. + +Here is the list of tasks deprecated and guidance on alternatives: + +| Task | Guidance | +|----------------------------------|--------------------| +| AndroidSigning@2 | Use the AndroidSigning@3 task | +| AzureCloudPowerShellDeployment@1 | Azure Cloud Services is being [retired](https://aka.ms/cloudservicesretirement), this task will stop working once the service is retired | +| AzureCloudPowerShellDeployment@2 | Azure Cloud Services is being [retired](https://aka.ms/cloudservicesretirement), this task will stop working once the service is retired | +| AzureFileCopy@1 | This task is deprecated as this version of the AzureFileCopy task uses a retired version of AzCopy. Use AzCopy V10 with AzureFileCopy@4 or newer, see [migration guidance](https://github.com/Azure/azure-storage-azcopy/blob/main/MigrationGuideV8toV10.md) | +| AzureFileCopy@2 | This task is deprecated as this version of the AzureFileCopy task uses a retired version of AzCopy. Use AzCopy V10 with AzureFileCopy@4 or newer, see [migration guidance](https://github.com/Azure/azure-storage-azcopy/blob/main/MigrationGuideV8toV10.md) | +| AzureFileCopy@3 | This task is deprecated as this version of the AzureFileCopy task uses a retired version of AzCopy. Use AzCopy V10 with AzureFileCopy@4 or newer, see [migration guidance](https://github.com/Azure/azure-storage-azcopy/blob/main/MigrationGuideV8toV10.md) | +| AzureFunctionOnKubernetes@0 | Use the AzureFunctionOnKubernetes@1 task to take advantage of latest features e.g. [Workload identity federation](https://aka.ms/azdo-rm-workload-identity-tasks) +| AzureKeyVault@1 | Use the AzureKeyVault@2 task | +| AzureNLBManagement@1 | Use the AzureCLI@2 task and the `az network lb` Azure CLI command | +| AzurePowerShell@2 | Use the AzurePowerShell@5 task | +| AzurePowerShell@3 | Use the AzurePowerShell@5 task | +| AzureRmWebAppDeployment@3 | Use the AzureRmWebAppDeployment@4 task to take advantage of latest features e.g. [Workload identity federation](https://aka.ms/azdo-rm-workload-identity-tasks) | +| CacheBeta@0 | Use the CacheBeta@1 or Cache@2 task | +| Docker@0 | Use the Docker@2 task | +| DotNetCoreInstaller@0 | Use the UseDotNet@2 task | +| DownloadPipelineArtifact@0 | Use the DownloadPipelineArtifact@1 or DownloadPipelineArtifact@2 task | +| DuffleInstaller@0 | This task is deprecated as the [Duffle project](https://github.com/cnabio/duffle) has been archived and is no longer maintained | +| FileTransform@1 | Use the FileTransform@2 task | +| FtpUpload@1 | Use the FtpUpload@2 task | +| GitHubRelease@0 | Use the GitHubRelease@1 task | +| Gradle@2 | Use the Gradle@3 task | +| HelmInstaller@0 | Use the HelmInstaller@1 task | +| IISWebAppDeployment@1 | Use the [IIS Web App Deployment extension](https://marketplace.visualstudio.com/items?itemName=ms-vscs-rm.iiswebapp) | +| Kubernetes@0 | Use the Kubernetes@1 task to take advantage of latest features e.g. [Workload identity federation](https://aka.ms/azdo-rm-workload-identity-tasks) | +| KubernetesManifest@0 | Use the KubernetesManifest@1 task to take advantage of latest features e.g. [Workload identity federation](https://aka.ms/azdo-rm-workload-identity-tasks) | +| Maven@2 | Use the Maven@4 task | +| Maven@3 | Use the Maven@4 task | +| MysqlDeploymentOnMachineGroup@1 | Consider Azure Database for MySQL and the AzureMysqlDeployment@1 task | +| PackerBuild@0 | Use the PackerBuild@0 task to take advantage of latest features e.g. [Workload identity federation](https://aka.ms/azdo-rm-workload-identity-tasks) | +| PowerShellOnTargetMachines@1 | Use the PowerShellOnTargetMachines@3 task | +| PowerShellOnTargetMachines@2 | Use the PowerShellOnTargetMachines@3 task | +| PublishCodeCoverageResults@1 | Use the PublishCodeCoverageResults@1 task, see [blog post](https://devblogs.microsoft.com/devops/new-pccr-task) | +| ServiceFabricComposeDeploy@0 | The ServiceFabricComposeDeploy@0 task is deprecated | +| SqlServerDacpacDeployment@1 | Use the [IIS Web App Deployment extension](https://marketplace.visualstudio.com/items?itemName=ms-vscs-rm.iiswebapp) which includes an updated version of this task | +| VSTest@1 | Use the VSTest@2 task | +| XamarinAndroid@1 | [Xamarin support ended on May 1, 2024](https://dotnet.microsoft.com/en-us/platform/support/policy/xamarin) | +| XamarinTestCloud@1 | [Xamarin support ended on May 1, 2024](https://dotnet.microsoft.com/en-us/platform/support/policy/xamarin) | +| XamariniOS@2 | [Xamarin support ended on May 1, 2024](https://dotnet.microsoft.com/en-us/platform/support/policy/xamarin) | + +### The Pipelines agent will show warnings for agents running Operating Systems not supported by .NET 8 + +We will upgrade the Pipelines agent to be built with .NET 8 instead of .NET 6. To prepare customers who may be using older Operating Systems, we are showing pipeline warnings for agents running on an Operating System that is not compatible with .NET 8. \ No newline at end of file diff --git a/release-notes/2024/includes/pipelines/sprint-245-update-links.md b/release-notes/2024/includes/pipelines/sprint-245-update-links.md new file mode 100644 index 00000000000..c194808753f --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-245-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +ms.topic: include +--- + +- [Azure Pipeline agent v4 runs on .NET 8](#azure-pipeline-agent-v4-runs-on-net-8) +- [Preview mode for shell tasks arguments validation](#preview-mode-for-shell-tasks-arguments-validation) diff --git a/release-notes/2024/includes/pipelines/sprint-245-update.md b/release-notes/2024/includes/pipelines/sprint-245-update.md new file mode 100644 index 00000000000..8a7b599e3fd --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-245-update.md @@ -0,0 +1,39 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +ms.topic: include +--- + +### Azure Pipeline agent v4 runs on .NET 8 + + +The Azure Pipeline agent v3 currently uses .NET 6, but with the end-of-life for .NET 6 approaching, we're upgrading the agent to .NET 8. This update will be rolled out over the coming weeks. + +If you're using self-hosted agents on an operating system that isn't supported by .NET 8, your agent won’t be upgraded to v4. Instead, pipelines running on unsupported operating systems display warnings in the pipeline logs. You can use the [QueryAgentPoolsForCompatibleOS.ps1 script](https://github.com/microsoft/azure-pipelines-agent/tree/master/tools/FindAgentsNotCompatibleWithAgent) to identify any pipeline agents running on outdated operating systems proactively. + +The following operating system versions won't be supported by the updated v4 agent: + +- Alpine Linux 3.13 - 3.16 +- Debian 10 +- Fedora 36 - 38 +- macOS 10 & 11 +- openSUSE 15.0 - 15.4 +- Oracle Linux 7 +- Red Hat Enterprise Linux 7 +- SUSE Enterprise Linux 12 +- Ubuntu, 16.04, 18.04 +- Windows 7, 8 & 10 up to 21H2 + +### Preview mode for shell tasks arguments validation + +Shell tasks such as [Bash@3](/azure/devops/pipelines/tasks/reference/bash-v3), [BatchScript@1](/azure/devops/pipelines/tasks/reference/batch-script-v1), [CmdLine@2](/azure/devops/pipelines/tasks/reference/cmd-line-v2) and [PowerShell@2](/azure/devops/pipelines/tasks/reference/powershell-v2) can be protected from command injection by enabling [shell tasks arguments validation](/azure/devops/pipelines/security/inputs#enable-shell-tasks-arguments-parameter-validation) in organization or project settings. + +Enabling shell tasks arguments validation can break existing scripts as input is rejected by input validation. For example, some characters are considered a command separator and rejected when this setting is enabled. + +To make this transition smoother, we added a preview mode. With preview mode enabled, you receive warnings in your pipeline and audit logs, giving you visibility into potential issues without interrupting your tasks or workflows. + +Go to Organization Settings > Pipelines > Settings > Task restrictions > Audit On: + +> [!div class="mx-imgBorder"] +> ![Screenshot of general to enable auditing.](../../media/245-pipelines-01.png "Screenshot of general to enable auditing") diff --git a/release-notes/2024/includes/pipelines/sprint-246-update-links.md b/release-notes/2024/includes/pipelines/sprint-246-update-links.md new file mode 100644 index 00000000000..0c5e53a60a1 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-246-update-links.md @@ -0,0 +1,11 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +- [Ubuntu 24.04 on Azure Pipelines hosted agents](#ubuntu-2404-on-azure-pipelines-hosted-agents) +- [Use Workload identity federation in Azure integration tests](#use-workload-identity-federation-in-azure-integration-tests) +- [New Azure service connection creation experience with improved Managed identity support](#new-azure-service-connection-creation-experience-with-improved-managed-identity-support) +- [Run children stages when parent stage fails](#run-children-stages-when-parent-stage-fails) \ No newline at end of file diff --git a/release-notes/2024/includes/pipelines/sprint-246-update.md b/release-notes/2024/includes/pipelines/sprint-246-update.md new file mode 100644 index 00000000000..56f19717999 --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-246-update.md @@ -0,0 +1,104 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +### Ubuntu 24.04 on Azure Pipelines hosted agents + +The Ubuntu 24.04 image is now available for Azure Pipelines hosted agents. To use this image, update your YAML file to include `vmImage:'ubuntu-24.04'`: + +```yaml +- job: ubuntu2404 + pool: + vmImage: 'ubuntu-24.04' + steps: + - bash: | + echo Hello from Ubuntu 24.04 + lsb_release -d +``` + +> [!NOTE] +> The `ubuntu-latest` image label will continue to point to ubuntu-22.04 until later this year. + +See the [Ubuntu 24.04 image readme](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md) for installed software. + + +### Use Workload identity federation in Azure integration tests + +In June, the Azure Identity libraries for.NET, C++, Go, Java, JavaScript, and Python [added support for workload identity federation](https://devblogs.microsoft.com/azure-sdk/improve-security-posture-in-azure-service-connections-with-azurepipelinescredential/). This added the ability for code executed from the [AzureCLI@2](/azure/devops/pipelines/tasks/reference/azure-cli-v2) and [AzurePowerShell@5](/azure/devops/pipelines/tasks/reference/azure-powershell-v5) tasks to authenticate with Microsoft Entra (for example, to access Azure) with the `AzurePipelinesCredential` class. + +Many customers are using the Azure Identity libraries in integration tests invoked from other tasks. We've now added support for `AzurePipelinesCredential` to the [DotNetCoreCLI@2](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2), [Maven@4](/azure/devops/pipelines/tasks/reference/maven-v4) and [VSTest@3](/azure/devops/pipelines/tasks/reference/vstest-v3) tasks. + +You can set the `connectedService` property to an Azure service connection configured with workload identity federation. The `AzurePipelinesCredential` requires `SYSTEM_ACCESSTOKEN` to be set. + +```yaml +- task: DotNetCoreCLI@2 + inputs: + command: 'run' + connectedService: + env: + SYSTEM_ACCESSTOKEN: $(System.AccessToken) +``` + +For more information on `AzurePipelinesCredential`, see this [blog post](https://devblogs.microsoft.com/azure-sdk/improve-security-posture-in-azure-service-connections-with-azurepipelinescredential/). + +### New Azure service connection creation experience with improved Managed identity support + +The new Azure service connection creation experience provides increased flexibility and secure defaults. It also aligns terminology with Microsoft Entra ID, so that users who create Microsoft Entra ID objects manually have a better understanding when navigating different portals. + +When creating a new Azure Resource Manager service connection, the various options to configure identity are now available in a single unified dialog that replaces the distinct top level items used previously: + +> [!div class="mx-imgBorder"] +> ![Screenshot of Azure service connection top level options.](../../media/246-pipelines-01.png "Screenshot of Azure service connection top level options") + +__Identity type__ lists all authentication schemes the Azure service connection supports: + +> [!div class="mx-imgBorder"] +> ![Screenshot of Identity Type.](../../media/246-pipelines-02.png "Screenshot of Identity Type") + +For app registrations, you can independently select __Credential__ to be [workload identity federation](https://devblogs.microsoft.com/devops/workload-identity-federation-for-azure-deployments-is-now-generally-available/) or a secret. + +#### Azure Service Connection Managed Identity support + +You can now select a pre-existing managed identity and use it to configure a service connection that uses workload identity federation. First, [create a User-assigned Managed Identity](/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp#create-a-user-assigned-managed-identity). + +Then, create an Azure service connection and select the _Managed identity_ Identity Type. This configures federated identity credentials on the managed identity. + +> [!div class="mx-imgBorder"] +> ![Screenshot of Managed Identity support.](../../media/246-pipelines-03.png "Screenshot of Managed Identity support") + +The option to use a managed identity assigned to an agent (pool) has been renamed _Managed identity (agent-assigned)_. To prevent sharing over-privileged managed identities, it's recommended to use a managed identity with workload identity federation instead of managed identities assigned to agent pools. + +Managed identity is also the recommended option for users who can't create an App registration if that is [disabled in Microsoft Entra ID](/entra/identity/role-based-access-control/delegate-app-roles#to-disable-the-default-ability-to-create-application-registrations-or-consent-to-applications). + +To use a managed identity with workload identity federation, first select the subscription and resource group that holds your managed identity. This can be different from the subscription the service connection accesses in pipeline jobs. Pick the managed identity that is configured for workload identity federation. The user needs the [Managed Identity Contributor](/azure/role-based-access-control/built-in-roles/identity#managed-identity-contributor) role or equivalent permissions on the managed identity to create federated identity credentials on it. + +Continue to select the subscription that will be used as the deployment scope for the service connection. + +> [!div class="mx-imgBorder"] +> ![Screenshot of Managed Identity selection.](../../media/246-pipelines-04.png "Screenshot of Managed Identity selection") + +#### Service Management Reference field + +Some organizations require the [Service Management Reference](/graph/api/resources/application#properties) of an App registration to be populated with relevant context information from an ITSM database. If necessary to do so, users can specify this reference at service connection creation time. + +#### More information + +The new Azure service connection creation experience is rolling out over the next month. For more information, see: + +- [Azure service connection documentation](/azure/devops/pipelines/library/connect-to-azure) +- [Workload identity federation](https://devblogs.microsoft.com/devops/workload-identity-federation-for-azure-deployments-is-now-generally-available/) +- [Troubleshooting](https://aka.ms/azdo-rm-workload-identity-troubleshooting) + +### Run children stages when parent stage fails + +We made it easier to continue deployments using Azure Pipelines. This is useful, for example, when you use Pipelines to deploy new versions of your application across multiple Azure regions. + +Say you need to deploy to five consecutive Azure regions. Assume your pipeline has a stage for each region, and each stage has a job that runs an `AzureResourceManagerTemplateDeployment` task, and then it logs some telemetry. The latter is nice to have, but not critical. Imagine there's an issue logging the telemetry. Now, the stage fails and the deployment stops. + +Starting with this sprint, when a stage fails, you can resume running its children stages. + +> [!div class="mx-imgBorder"] +> ![Screenshot of running child stages if parent stage fails.](../../media/246-pipelines-05.png "Screenshot of running child stages if parent stage fails") \ No newline at end of file diff --git a/release-notes/2024/includes/pipelines/sprint-247-update-links.md b/release-notes/2024/includes/pipelines/sprint-247-update-links.md new file mode 100644 index 00000000000..7d03bf85ead --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-247-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +ms.topic: include +--- + +- [macOS-15 Sequoia is available in preview](#macos-15-sequoia-is-available-in-preview) +- [Improvements to service connection App registration attribution](#improvements-to-service-connection-app-registration-attribution) diff --git a/release-notes/2024/includes/pipelines/sprint-247-update.md b/release-notes/2024/includes/pipelines/sprint-247-update.md new file mode 100644 index 00000000000..14a60b64dad --- /dev/null +++ b/release-notes/2024/includes/pipelines/sprint-247-update.md @@ -0,0 +1,56 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +ms.topic: include +--- + +### macOS-15 Sequoia is available in preview + +The `macOS-15` image is now available in preview for Azure Pipelines hosted agents. To use this image, update your YAML file to include `vmImage: 'macOS-15'`: + +```yaml +- job: macOS15 + pool: + vmImage: 'macOS-15' + steps: + - bash: | + echo Hello from macOS Sequoia Preview + sw_vers +``` + +For macOS-15 installed software, see [image configuration](https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md). + +The `macOS-14` image will still be used when specifying `macOS-latest`. Once `macOS-15` is generally available, `macOS-latest` migrates directly to `macOS-15`. + +### Improvements to service connection App registration attribution + +When a service connection targets Azure, it automatically creates an App registration. +To find the identity associated with a service connection, you can use the 'Manage App registration' link on the service connection details page. We received feedback that, when browsing App registrations directly in Microsoft Entra ID, it isn't always clear what an App registration is used for. + + +To improve the attribution experience, we made the following changes: +##### App registration notes and service management reference + +Newly created Azure service connections can now include a service management reference in addition to a description: + +> [!div class="mx-imgBorder"] +> ![Screenshot of service connection creation page.](../../media/247-pipelines-02.png "Screenshot of service connection creation details") + +This information is used to populate App registration metadata that can be found on the Branding & properties blade: + +> [!div class="mx-imgBorder"] +> ![Screenshot of app registration properties.](../../media/247-pipelines-03.png "Screenshot of app registration properties") + +If a description wasn’t provided during service connection creation, a default note will be added to the App registration. + +##### New naming convention for App registrations in Azure service connections + +Previously, service connections were named using the format `--`, making it challenging to distinguish between App registrations linked to the same Azure subscription. To improve clarity, App registration names will now include the service connection ID, following this format: `--`. + +You can find the service connection ID on the service connection details page: + +> [!div class="mx-imgBorder"] +> ![Screenshot of service connection details page.](../../media/247-pipelines-01.png "Screenshot of service connection details page") + +You can also follow or share the 'Manage App registration' link or 'Manage identity' if a [Managed Identity](/azure/devops/release-notes/2024/pipelines/sprint-246-update#azure-service-connection-managed-identity-support) is used. diff --git a/release-notes/2024/includes/reporting/sprint-244-update-links.md b/release-notes/2024/includes/reporting/sprint-244-update-links.md new file mode 100644 index 00000000000..0d77417d0fd --- /dev/null +++ b/release-notes/2024/includes/reporting/sprint-244-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +ms.topic: include +--- + +- [Enhanced Visibility for Usage Limits in Azure DevOps ](#enhanced-visibility-for-usage-limits-in-azure-devops) \ No newline at end of file diff --git a/release-notes/2024/includes/reporting/sprint-244-update.md b/release-notes/2024/includes/reporting/sprint-244-update.md new file mode 100644 index 00000000000..deb14cbe099 --- /dev/null +++ b/release-notes/2024/includes/reporting/sprint-244-update.md @@ -0,0 +1,13 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +ms.topic: include +--- + +### Enhanced Visibility for Usage Limits in Azure DevOps + +We're excited to introduce the Object Limit Tracker in Azure DevOps. This new feature provides real-time visibility into resource usage for each organization and project directly within Azure DevOps, helping you manage limits proactively and avoid unexpected disruptions. Check out this new feature today to ensure uninterrupted productivity! + +> ![Analytics view in boards navigation.](../../media/244-reporting-01.png) + diff --git a/release-notes/2024/includes/repos/sprint-234-update-links.md b/release-notes/2024/includes/repos/sprint-234-update-links.md new file mode 100644 index 00000000000..11f1f4f56db --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-234-update-links.md @@ -0,0 +1,8 @@ +--- +author: bjanousek +ms.author: bjanousek +ms.date: 2/9/2024 +ms.topic: include +--- + +- [Prevention for unauthorized users to configure pipeline as a Build Policy](#prevention-for-unauthorized-users-to-configure-pipeline-as-a-build-policy) diff --git a/release-notes/2024/includes/repos/sprint-234-update.md b/release-notes/2024/includes/repos/sprint-234-update.md new file mode 100644 index 00000000000..9448092d36d --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-234-update.md @@ -0,0 +1,40 @@ +--- +author: bjanousek +ms.author: bjanousek +ms.date: 2/9/2024 +ms.topic: include +--- + +### Prevention for unauthorized users to configure pipeline as a Build Policy + +Prevention for unauthorized users to configure pipeline as a Build Policy + +Previously, when you've been adding a new build policy, you could configure to run any pipeline from the drop-down list (including the pipelines you had no **Queue builds** permission for). Similarly, you could edit the existing build policy even if that was configured to run the pipeline you had no **Queue builds** permission for. + +Now we're preventing users from doing so. If a user is denied to **Queue builds** permission for given pipeline, then that pipeline will be shown as disabled (greyed out) in the drop-down when adding new build policy. + +See the image below showing the pipeline named "Sandbox" with **Queue builds** permission being denied. + + +> [!div class="mx-imgBorder"] +> ![Screenshot of permissions for Sandbox.](../../media/234-repos-01.png "Screenshot of permissions for Sandbox") + +See the image below showing the pipeline named "Sandbox" disabled (greyed out) in the drop-down when user with denied **Queue builds** permission is trying to add new build policy. + +> [!div class="mx-imgBorder"] +> ![Screenshot of add build policy.](../../media/234-repos-02.png "Screenshot of add build policy") + +When the build policy configured to run the pipeline named "Sandbox" already exists, then the user with no **Queue builds** permission won't be able to edit or view the build policy. This case is shown on the following image. + + +> [!div class="mx-imgBorder"] +> ![Screenshot of build validation.](../../media/234-repos-03.png "Screenshot of build validation") + +When you try to delete this policy the pop-up dialog asking for deletion confirmation will be shown. + +> [!div class="mx-imgBorder"] +> ![Screenshot of confirm deletion.](../../media/234-repos-04.png "Screenshot of confirm deletion") + +These changes also apply to any API calls that result in either creation or editing of the build policy. When any of these actions is run using a user identity with no **Queue builds** permission, then the call will fail returning back the appropriate error code and the error message saying `“TFS.WebApi.Exception: TF401027:` You need the QueueBuild permission on this pipeline to perform this action.”. + +Deletion of a build policy done via API using a `user identity` with no **Queue builds** permission will succeed and there will be no warning or prevention done (no changes in how the deletion via API works). \ No newline at end of file diff --git a/release-notes/2024/includes/repos/sprint-235-update-links.md b/release-notes/2024/includes/repos/sprint-235-update-links.md new file mode 100644 index 00000000000..385fda44e0c --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-235-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +ms.topic: include +--- + +- [SSH-RSA deprecation](#ssh-rsa-deprecation) diff --git a/release-notes/2024/includes/repos/sprint-235-update.md b/release-notes/2024/includes/repos/sprint-235-update.md new file mode 100644 index 00000000000..82cc304c757 --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-235-update.md @@ -0,0 +1,13 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +ms.topic: include +--- + +### SSH-RSA deprecation + +Azure Repos provides two methods for users to access a git repository in Azure Repos – HTTPS and SSH. To use SSH, you need to create a key pair using one of the supported encryption methods. In the past, we’ve been supporting only SSH-RSA and we’ve asked users to enable the SSH-RSA [here](/azure/devops/repos/git/use-ssh-keys-to-authenticate#q-ssh-cannot-establish-a-connection-what-should-i-do). + +With this update, we're announcing the deprecation of SSH-RSA as a supported encryption method for connecting to Azure Repos using SSH. You can see more details in the [End of SSH-RSA support for Azure Repos](https://devblogs.microsoft.com/devops/ssh-rsa-deprecation/) blog post. + diff --git a/release-notes/2024/includes/repos/sprint-240-update-links.md b/release-notes/2024/includes/repos/sprint-240-update-links.md new file mode 100644 index 00000000000..8ca6bab3b8c --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-240-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +ms.topic: include +--- + +- [New setting to disable creation of TFVC repositories](#new-setting-to-disable-creation-of-tfvc-repositories) diff --git a/release-notes/2024/includes/repos/sprint-240-update.md b/release-notes/2024/includes/repos/sprint-240-update.md new file mode 100644 index 00000000000..631e4c0832d --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-240-update.md @@ -0,0 +1,16 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +ms.topic: include +--- + +### New setting to disable creation of TFVC repositories + +In recent years, no new features were added to Team Foundation Version Control (TFVC) because Git has become the preferred version control system in Azure Repos. All recent improvements in security, performance, and accessibility have been made exclusively to Git repositories, leading to a continuous decline in TFVC usage. While some still rely on TFVC and we don't intend to remove this feature set, we plan to phase out TFVC gradually for new projects and organizations, as well as for projects that currently don't use TFVC. + +As part of this transition, we're introducing a new setting to "Disable creation of TFVC repositories," which will only affect the creation of new TFVC repositories and won't impact existing ones. + + +> [!div class="mx-imgBorder"] +> ![Gif to demo Disable creation of TFVC repositories.](../../media/240-repos-01.gif "gif to Disable creation of TFVC repositories") \ No newline at end of file diff --git a/release-notes/2024/includes/repos/sprint-244-update-links.md b/release-notes/2024/includes/repos/sprint-244-update-links.md new file mode 100644 index 00000000000..3295bce6c23 --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-244-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +ms.topic: include +--- + +- [UI support of Git Submodules](#ui-support-of-git-submodules) diff --git a/release-notes/2024/includes/repos/sprint-244-update.md b/release-notes/2024/includes/repos/sprint-244-update.md new file mode 100644 index 00000000000..003940f488a --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-244-update.md @@ -0,0 +1,15 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/7/2024 +ms.topic: include +--- + +### UI support of Git submodules + +Many teams actively use Git submodules to organize their codebase. We're excited to share that we've added support of Git submodules in the Files hub. Now you can instantly navigate to a submodule repository with just a single click, exactly to the specific commit referenced from your superproject. When used as a submodule, the following Git services are supported: Azure Repos, GitHub, GitLab and Bitbucket. Multiple URL formats specified in .gitmodules file are supported as well, including absolute HTTPS, SSH, and relative URLs. + +This addresses a feature request from Developer Community: [[Azure DevOps Repos] Git submodule preview in UI](https://developercommunity.visualstudio.com/t/azure-devops-repos-git-submodule-preview-in-ui/1033995) + +> [!div class="mx-imgBorder"] +> ![Gif to demo navigate to a submodule repository.](../../media/244-repos-01.gif "gif to navigate to a submodule repository") diff --git a/release-notes/2024/includes/repos/sprint-245-update-links.md b/release-notes/2024/includes/repos/sprint-245-update-links.md new file mode 100644 index 00000000000..ac0612a0cb8 --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-245-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +ms.topic: include +--- + +- [New "Health and usage" panel in repo file hub ](#new-health-and-usage-panel-in-repo-file-hub) diff --git a/release-notes/2024/includes/repos/sprint-245-update.md b/release-notes/2024/includes/repos/sprint-245-update.md new file mode 100644 index 00000000000..ef9d0972107 --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-245-update.md @@ -0,0 +1,17 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +ms.topic: include +--- + +### New "Health and usage" panel in repo file hub + +As Git repositories grow, they accumulate commits, blobs, and other data, which can increase the load on Azure DevOps infrastructure, impacting performance and user experience. Maintaining a healthy repository is key to ensuring consistent performance and reliability. + +To support this, we now monitor several factors like repository size, commit frequency, contents, and structure. If your repository begins to strain the infrastructure, you may receive a notification with recommendations for corrective action. By managing your repository’s health, you can prevent disruptions and ensure smooth operations. + +To check your repository’s health, go to Azure Repos, > Files and choose “Health and usage” from the ellipsis menu to access the Repository health and usage panel. + +> [!div class="mx-imgBorder"] +> [![Screenshot of Health and usage.](../../media/245-repos-01.png "Screenshot of Health and usage")](../../media/245-repos-01.png#lightbox) \ No newline at end of file diff --git a/release-notes/2024/includes/repos/sprint-246-update-links.md b/release-notes/2024/includes/repos/sprint-246-update-links.md new file mode 100644 index 00000000000..f13e8495ee8 --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-246-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +- [Configure target branches for pull requests](#configure-target-branches-for-pull-requests) +- [Support mermaid diagrams in markdown file preview](#support-mermaid-diagrams-in-markdown-file-preview) \ No newline at end of file diff --git a/release-notes/2024/includes/repos/sprint-246-update.md b/release-notes/2024/includes/repos/sprint-246-update.md new file mode 100644 index 00000000000..8813aaa7ee2 --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-246-update.md @@ -0,0 +1,31 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +### Configure target branches for pull requests + +Managing multiple branches in a repository can be challenging, especially when creating new pull requests. With the new Configure Target Branches for Pull Requests feature, you can now specify a list of preferred target branches, ensuring that pull request suggestions are more accurate and relevant. This helps streamline your workflow and reduces the chances of targeting the wrong branch. +To use this feature, create a `.azuredevops/pull_request_targets.yml` file in your repository's default branch. This YAML file should contain a list titled `pull_request_targets` with the branch names or prefixes that match the candidate branches. For example: +```yaml +pull_request_targets: + - main + - release/* + - feature/* +``` + +In this configuration, the main branch is prioritized, but branches starting with `release/` or `feature/` will also be considered when appropriate. The configuration is applied in the following scenarios: + +- **Pull Request Suggestions:** After pushing a branch to Azure DevOps, the Repos page may suggest creating a pull request from that branch, dynamically choosing the target branch. +- **Pull Request URL:** When navigating directly to the pull request creation page using a sourceRef parameter but omitting the targetRef parameter, Azure DevOps selects a target branch based on this dynamic choice. + +It’s recommended to include only branches protected by pull request policies to ensure consistency in the first-parent history of the tip commit. + +### Support mermaid diagrams in markdown file preview + +Markdown files containing mermaid syntax will now render as diagrams inside file previews in repos file browser and in pull requests. This can help you add richer documentation to your repositories. + +> [!div class="mx-imgBorder"] +> [![Screenshot of mermaid diagrams in markdown file preview.](../../media/246-repos-01.png "Screenshot of mermaid diagrams in markdown file preview")](../../media/246-repos-01.png#lightbox) \ No newline at end of file diff --git a/release-notes/2024/includes/repos/sprint-247-update-links.md b/release-notes/2024/includes/repos/sprint-247-update-links.md new file mode 100644 index 00000000000..f33658544f5 --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-247-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +ms.topic: include +--- + +- [Search pull requests by title on PR listing page](#search-pull-requests-by-title-on-pr-listing-page) diff --git a/release-notes/2024/includes/repos/sprint-247-update.md b/release-notes/2024/includes/repos/sprint-247-update.md new file mode 100644 index 00000000000..44a707a4f73 --- /dev/null +++ b/release-notes/2024/includes/repos/sprint-247-update.md @@ -0,0 +1,14 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +ms.topic: include +--- + +### Search pull requests by title on PR listing page + +The pull requests listing page now includes a filter by PR title, making it easier to locate specific pull requests. + +> [!div class="mx-imgBorder"] +> [![Screenshot of filtering by PR title.](../../media/247-repos-01.png "Screenshot of filtering by PR title")](../../media/247-repos-01.png#lightbox) + diff --git a/release-notes/2024/includes/testplans/sprint-232-update-links.md b/release-notes/2024/includes/testplans/sprint-232-update-links.md new file mode 100644 index 00000000000..bf93369bb51 --- /dev/null +++ b/release-notes/2024/includes/testplans/sprint-232-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/11/2024 +ms.topic: include +--- + +- [Code Coverage results for folders](#code-coverage-results-for-folders) \ No newline at end of file diff --git a/release-notes/2024/includes/testplans/sprint-232-update.md b/release-notes/2024/includes/testplans/sprint-232-update.md new file mode 100644 index 00000000000..ff4c8b78afd --- /dev/null +++ b/release-notes/2024/includes/testplans/sprint-232-update.md @@ -0,0 +1,14 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/11/2024 +ms.topic: include +--- + +### Code Coverage results for folders + +Results for code coverage are now available for every individual file and folder rather than only as a top-level number. The code coverage view appears when the ***Folder view mode*** button is toggled. In this mode you can drill down and see the code coverage for that selected subtree. Use the toggle button to switch between the new and old views. + +> [!div class="mx-imgBorder"] +> ![Screenshots of Multiple repository widget to GA.](../../media/232-test-plans-01.png "Screenshots of Multiple repository widget to GA.") + diff --git a/release-notes/2024/includes/testplans/sprint-235-update-links.md b/release-notes/2024/includes/testplans/sprint-235-update-links.md new file mode 100644 index 00000000000..93338450578 --- /dev/null +++ b/release-notes/2024/includes/testplans/sprint-235-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +ms.topic: include +--- + +- [Quick Copy and Import with Test Plan or Suite ID](#quick-copy-and-import-with-test-plan-or-suite-id) +- [Update for Azure Test Runner](#update-for-azure-test-runner) \ No newline at end of file diff --git a/release-notes/2024/includes/testplans/sprint-235-update.md b/release-notes/2024/includes/testplans/sprint-235-update.md new file mode 100644 index 00000000000..da104500a5a --- /dev/null +++ b/release-notes/2024/includes/testplans/sprint-235-update.md @@ -0,0 +1,29 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +ms.topic: include +--- + +### Quick Copy and Import with Test Plan or Suite ID + +You can now handle multiple test plans in Azure Test Plans with ease! Recognizing the challenges previously faced with long dropdown menus for importing, copying, or cloning test cases—especially for extensive plans or suites—we've taken steps to streamline your workflow. + +We're excited to announce the Test Plan and Suite ID Search feature. Enter your Test Plan or Suite ID for swift importing or copying of Test Cases without any delays. This update is part of our ongoing commitment to improve your test management experience, making it more intuitive and less time-consuming. + +> [!div class="mx-imgBorder"] +> ![Gif to demo Test Plan, Suite ID search details.](../../media/235-testplans-01.gif "gif to GitHub Test Plan, Suite ID search details") + +### Update for Azure Test Runner + +We're excited to share that Azure Test Runner has been updated to a newer version. This update improves stability and performance, allowing you to run your tests without interruptions or delays. The older version of Azure Test Runner is no longer supported. For the best performance and dependability of your testing operations, we recommend that you update to the newest version as soon as possible. + +**What's New?** + +* **Enhanced Stability and Performance:** +We've made significant improvements to the Test Runner, addressing issues some users experienced. This upgrade ensures a more reliable testing process, minimizing disruptions to your work. +* **Upgrade Prompt:** +To make the transition to the new version seamless, you'll encounter a prompt to upgrade. This ensures everyone can easily move to the improved version at your convenience, enhancing compatibility and performance. + +> [!div class="mx-imgBorder"] +> ![Screenshots of upgrade prompt.](../../media/235-testplans-01.png "Screenshots of upgrade prompt.") \ No newline at end of file diff --git a/release-notes/2024/includes/testplans/sprint-240-update-links.md b/release-notes/2024/includes/testplans/sprint-240-update-links.md new file mode 100644 index 00000000000..ce5cfb7ccbb --- /dev/null +++ b/release-notes/2024/includes/testplans/sprint-240-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +ms.topic: include +--- + +- [Test and Feedback extension in Manifest V3](#test-and-feedback-extension-in-manifest-v3) diff --git a/release-notes/2024/includes/testplans/sprint-240-update.md b/release-notes/2024/includes/testplans/sprint-240-update.md new file mode 100644 index 00000000000..dc332f1a61a --- /dev/null +++ b/release-notes/2024/includes/testplans/sprint-240-update.md @@ -0,0 +1,15 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +ms.topic: include +--- + +### Test and Feedback extension in Manifest V3 + +We're excited to announce a new update to the Azure DevOps Test and Feedback extension! This upgrade transitions our implementation from Manifest Version 2 to Version 3, aligning with Google's deprecation schedule for Manifest V2. + +While the extension's core features remain unchanged, this update improves security and performance. The updated extension will roll out gradually to both Chrome and Edge browsers over the coming weeks. We will monitor performance and feedback to ensure a smooth transition before expanding the rollout based on the results. + +For more details, check out our recent blog post about this update. [Test & Feedback Extension in Manifest V3](https://devblogs.microsoft.com/devops/test-feedback-extension-v3/) + diff --git a/release-notes/2024/includes/testplans/sprint-245-update-links.md b/release-notes/2024/includes/testplans/sprint-245-update-links.md new file mode 100644 index 00000000000..7affb9dc099 --- /dev/null +++ b/release-notes/2024/includes/testplans/sprint-245-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +ms.topic: include +--- + +- [Seamless build Pipeline integration for test case execution](#seamless-build-pipeline-integration-for-test-case-execution) +- [Test and feedback extension in Manifest V3 (Edge release)](#test-and-feedback-extension-in-manifest-v3-edge-release) \ No newline at end of file diff --git a/release-notes/2024/includes/testplans/sprint-245-update.md b/release-notes/2024/includes/testplans/sprint-245-update.md new file mode 100644 index 00000000000..b5e92e8bb93 --- /dev/null +++ b/release-notes/2024/includes/testplans/sprint-245-update.md @@ -0,0 +1,21 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +ms.topic: include +--- + +### Seamless build Pipeline integration for test case execution + +We’ve simplified the test case execution process by seamlessly integrating build pipeline configurations. Build definitions and IDs set at the test plan level now automatically propagate to the Web Runner, eliminating the need for manual configuration each time. This improvement saves time and enhances efficiency, allowing you to focus on more critical tasks. + +> [!div class="mx-imgBorder"] +> ![Gif to demo Pipeline Integration for Test Case Execution.](../../media/245-testplans-01.gif "gif to Pipeline Integration for Test Case Execution") + +### Test and feedback extension in Manifest V3 (Edge release) + +We’ve been gradually releasing this upgrade in Chrome, and now we’re expanding the rollout to Edge. + +This update transitions our implementation from Manifest V2 to V3, in line with Google's deprecation schedule for Manifest V2. While the core features of the extension remain unchanged, the update enhances both security and performance. + +For more details, check out our recent blog post about this update. [Test & Feedback Extension in Manifest V3](https://devblogs.microsoft.com/devops/test-feedback-extension-v3/) \ No newline at end of file diff --git a/release-notes/2024/includes/testplans/sprint-247-update-links.md b/release-notes/2024/includes/testplans/sprint-247-update-links.md new file mode 100644 index 00000000000..07c007068ca --- /dev/null +++ b/release-notes/2024/includes/testplans/sprint-247-update-links.md @@ -0,0 +1,11 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +ms.topic: include +--- + +- [Azure Test Runner Version 1.2.2](#azure-test-runner-version-122) +- [New sorting capabilities in Test Plans directory](#new-sorting-capabilities-in-test-plans-directory) +- [Auto Pause for Test Case Run preview](#auto-pause-for-test-case-run-preview) +- [New release version for Test and Feedback Extensions (TFE)](#new-release-version-for-test-and-feedback-extensions-tfe) \ No newline at end of file diff --git a/release-notes/2024/includes/testplans/sprint-247-update.md b/release-notes/2024/includes/testplans/sprint-247-update.md new file mode 100644 index 00000000000..b952e4c3acc --- /dev/null +++ b/release-notes/2024/includes/testplans/sprint-247-update.md @@ -0,0 +1,29 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +ms.topic: include +--- + +### Azure Test Runner version 1.2.2 + +Azure Test Plans released a fix in 1.2.2 for a recent issue in Test Plans where Azure Test Runner(ATR) experienced launch failures in Chrome version 130. This issue arose due to Chrome’s [added support for non-special scheme URLs](https://docs.google.com/document/d/1LjxHl32fE4tCKugrK_PIso7mfXQVEeoD1wSnX2y0ZU8/edit?resourcekey=0-d1gP4X2sG7GPl9mlTeptIA&tab=t.0#heading=h.voahsyj6c2dh), which impacted the ATR user flow. With this update, the regression bug is resolved, and ATR functionality is restored. For more details about this regression bug, visit [this issue tracker](https://issues.chromium.org/issues/375228139) in Chromium. + +We encourage you to use web application for enhanced features. If you find any missing features in web application, we would love to hear from you. [Share your feedback](mailto:adocustomerfeedback@service.microsoft.com) with us! + + +### New sorting capabilities in Test Plans directory + +The Test Plans directory now offers enhanced sorting options! With this update, you can quickly organize each column alphanumerically, providing a streamlined way to find and access your data. + +> [!div class="mx-imgBorder"] +> ![Gif to demo Sorting in Test Plans Directory.](../../media/247-testplans-01.gif "gif to Sorting in Test Plans Directory") + + +### Auto Pause for Test Case Run preview + +Manual testers often encounter challenges with losing progress on test cases if an incomplete run isn’t marked as “Paused” before selecting “Save and Close.” This can result in lost work on complex or lengthy cases, requiring testers to start over. To solve this, we’re introducing Auto Pause for Test Case Run. This feature automatically pauses a test case if there’s a break or interruption, ensuring all data is saved without needing a manual pause. With Auto Pause, testers can easily resume right where they left off, simplifying the testing process and making it more efficient. A preview will be available in the coming weeks—[email us](mailto:adocustomerfeedback@service.microsoft.com) if you’d like to join! + +### New release version for Test and Feedback Extensions (TFE) + +We’re thrilled to announce the release of TFE version 1.0.247.0, now available on both Chrome and Edge. [Install the latest version](https://microsoftedge.microsoft.com/addons/detail/test-feedback/leeakgkdanfdoebeohldonigkalooaej) for improved functionality, with a fix for Stakeholder Mode, addressing and resolving previous disruptions. Enjoy a smoother, more reliable experience with this latest version! \ No newline at end of file diff --git a/release-notes/2024/includes/wiki/sprint-246-update-links.md b/release-notes/2024/includes/wiki/sprint-246-update-links.md new file mode 100644 index 00000000000..85ccc9a05b3 --- /dev/null +++ b/release-notes/2024/includes/wiki/sprint-246-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- + +- [Improve pasting of HTML based content into Wikis](#improve-pasting-of-html-based-content-into-wikis) \ No newline at end of file diff --git a/release-notes/2024/includes/wiki/sprint-246-update.md b/release-notes/2024/includes/wiki/sprint-246-update.md new file mode 100644 index 00000000000..764ba13dcf2 --- /dev/null +++ b/release-notes/2024/includes/wiki/sprint-246-update.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +ms.topic: include +--- +### Improve pasting of HTML based content into Wikis + +We’ve made it easier to paste HTML-based content into Wikis. Now, HTML elements like links, lists, tables, images, Excel sheets, Microsoft Teams messages, emails, and Azure Data Explorer queries are automatically converted to Markdown syntax for smoother editing. \ No newline at end of file diff --git a/release-notes/2024/media/232-general-01.png b/release-notes/2024/media/232-general-01.png new file mode 100644 index 00000000000..9ca5d490ba9 Binary files /dev/null and b/release-notes/2024/media/232-general-01.png differ diff --git a/release-notes/2024/media/232-general-02.png b/release-notes/2024/media/232-general-02.png new file mode 100644 index 00000000000..22f18f23706 Binary files /dev/null and b/release-notes/2024/media/232-general-02.png differ diff --git a/release-notes/2024/media/232-general-03.png b/release-notes/2024/media/232-general-03.png new file mode 100644 index 00000000000..77cb3b18a2a Binary files /dev/null and b/release-notes/2024/media/232-general-03.png differ diff --git a/release-notes/2024/media/232-test-plans-01.png b/release-notes/2024/media/232-test-plans-01.png new file mode 100644 index 00000000000..c7638a050ff Binary files /dev/null and b/release-notes/2024/media/232-test-plans-01.png differ diff --git a/release-notes/2024/media/233-boards-01.gif b/release-notes/2024/media/233-boards-01.gif new file mode 100644 index 00000000000..d44a31e15c8 Binary files /dev/null and b/release-notes/2024/media/233-boards-01.gif differ diff --git a/release-notes/2024/media/233-boards-01.png b/release-notes/2024/media/233-boards-01.png new file mode 100644 index 00000000000..5c540c92856 Binary files /dev/null and b/release-notes/2024/media/233-boards-01.png differ diff --git a/release-notes/2024/media/233-boards-02.png b/release-notes/2024/media/233-boards-02.png new file mode 100644 index 00000000000..95744fa3de5 Binary files /dev/null and b/release-notes/2024/media/233-boards-02.png differ diff --git a/release-notes/2024/media/233-general-01.png b/release-notes/2024/media/233-general-01.png new file mode 100644 index 00000000000..22f18f23706 Binary files /dev/null and b/release-notes/2024/media/233-general-01.png differ diff --git a/release-notes/2024/media/233-pipelines-01.png b/release-notes/2024/media/233-pipelines-01.png new file mode 100644 index 00000000000..8a265ddd5ff Binary files /dev/null and b/release-notes/2024/media/233-pipelines-01.png differ diff --git a/release-notes/2024/media/234-boards-01.gif b/release-notes/2024/media/234-boards-01.gif new file mode 100644 index 00000000000..8ca87c80780 Binary files /dev/null and b/release-notes/2024/media/234-boards-01.gif differ diff --git a/release-notes/2024/media/234-boards-01.png b/release-notes/2024/media/234-boards-01.png new file mode 100644 index 00000000000..6c830d8b209 Binary files /dev/null and b/release-notes/2024/media/234-boards-01.png differ diff --git a/release-notes/2024/media/234-boards-02.gif b/release-notes/2024/media/234-boards-02.gif new file mode 100644 index 00000000000..1716b920f9c Binary files /dev/null and b/release-notes/2024/media/234-boards-02.gif differ diff --git a/release-notes/2024/media/234-boards-02.png b/release-notes/2024/media/234-boards-02.png new file mode 100644 index 00000000000..5e213503347 Binary files /dev/null and b/release-notes/2024/media/234-boards-02.png differ diff --git a/release-notes/2024/media/234-boards-03.png b/release-notes/2024/media/234-boards-03.png new file mode 100644 index 00000000000..2a3a216e3b4 Binary files /dev/null and b/release-notes/2024/media/234-boards-03.png differ diff --git a/release-notes/2024/media/234-general-01.png b/release-notes/2024/media/234-general-01.png new file mode 100644 index 00000000000..27064c5204a Binary files /dev/null and b/release-notes/2024/media/234-general-01.png differ diff --git a/release-notes/2024/media/234-general-02.png b/release-notes/2024/media/234-general-02.png new file mode 100644 index 00000000000..255df3d0575 Binary files /dev/null and b/release-notes/2024/media/234-general-02.png differ diff --git a/release-notes/2024/media/234-ghazdo-02.png b/release-notes/2024/media/234-ghazdo-02.png new file mode 100644 index 00000000000..2e59e7189d0 Binary files /dev/null and b/release-notes/2024/media/234-ghazdo-02.png differ diff --git a/release-notes/2024/media/234-ghazdo-03.png b/release-notes/2024/media/234-ghazdo-03.png new file mode 100644 index 00000000000..6ebafb02504 Binary files /dev/null and b/release-notes/2024/media/234-ghazdo-03.png differ diff --git a/release-notes/2024/media/234-ghazdo-04.png b/release-notes/2024/media/234-ghazdo-04.png new file mode 100644 index 00000000000..9093f4ef6f9 Binary files /dev/null and b/release-notes/2024/media/234-ghazdo-04.png differ diff --git a/release-notes/2024/media/234-ghazdo-05.png b/release-notes/2024/media/234-ghazdo-05.png new file mode 100644 index 00000000000..2736db0ac98 Binary files /dev/null and b/release-notes/2024/media/234-ghazdo-05.png differ diff --git a/release-notes/2024/media/234-pipelines-05.png b/release-notes/2024/media/234-pipelines-05.png new file mode 100644 index 00000000000..31caa93c87d Binary files /dev/null and b/release-notes/2024/media/234-pipelines-05.png differ diff --git a/release-notes/2024/media/234-pipelines-06.png b/release-notes/2024/media/234-pipelines-06.png new file mode 100644 index 00000000000..7bc65eedfa8 Binary files /dev/null and b/release-notes/2024/media/234-pipelines-06.png differ diff --git a/release-notes/2024/media/234-pipelines-07.png b/release-notes/2024/media/234-pipelines-07.png new file mode 100644 index 00000000000..a231d109773 Binary files /dev/null and b/release-notes/2024/media/234-pipelines-07.png differ diff --git a/release-notes/2024/media/234-pipelines-08.png b/release-notes/2024/media/234-pipelines-08.png new file mode 100644 index 00000000000..365b711183d Binary files /dev/null and b/release-notes/2024/media/234-pipelines-08.png differ diff --git a/release-notes/2024/media/234-pipelines-09.png b/release-notes/2024/media/234-pipelines-09.png new file mode 100644 index 00000000000..58d23d43cff Binary files /dev/null and b/release-notes/2024/media/234-pipelines-09.png differ diff --git a/release-notes/2024/media/234-pipelines-10.png b/release-notes/2024/media/234-pipelines-10.png new file mode 100644 index 00000000000..62ab28dc3dc Binary files /dev/null and b/release-notes/2024/media/234-pipelines-10.png differ diff --git a/release-notes/2024/media/234-pipelines-11.png b/release-notes/2024/media/234-pipelines-11.png new file mode 100644 index 00000000000..371508efaa6 Binary files /dev/null and b/release-notes/2024/media/234-pipelines-11.png differ diff --git a/release-notes/2024/media/234-pipelines-12.png b/release-notes/2024/media/234-pipelines-12.png new file mode 100644 index 00000000000..222dac7ebbc Binary files /dev/null and b/release-notes/2024/media/234-pipelines-12.png differ diff --git a/release-notes/2024/media/234-pipelines-13.png b/release-notes/2024/media/234-pipelines-13.png new file mode 100644 index 00000000000..5f213920496 Binary files /dev/null and b/release-notes/2024/media/234-pipelines-13.png differ diff --git a/release-notes/2024/media/234-pipelines-14.png b/release-notes/2024/media/234-pipelines-14.png new file mode 100644 index 00000000000..d7316e45161 Binary files /dev/null and b/release-notes/2024/media/234-pipelines-14.png differ diff --git a/release-notes/2024/media/234-pipelines-15.png b/release-notes/2024/media/234-pipelines-15.png new file mode 100644 index 00000000000..167f1d2f14e Binary files /dev/null and b/release-notes/2024/media/234-pipelines-15.png differ diff --git a/release-notes/2024/media/234-pipelines-16.png b/release-notes/2024/media/234-pipelines-16.png new file mode 100644 index 00000000000..f7026caa623 Binary files /dev/null and b/release-notes/2024/media/234-pipelines-16.png differ diff --git a/release-notes/2024/media/234-pipelines-17.png b/release-notes/2024/media/234-pipelines-17.png new file mode 100644 index 00000000000..153251b3073 Binary files /dev/null and b/release-notes/2024/media/234-pipelines-17.png differ diff --git a/release-notes/2024/media/234-pipelines-18.png b/release-notes/2024/media/234-pipelines-18.png new file mode 100644 index 00000000000..61e2ed01dfb Binary files /dev/null and b/release-notes/2024/media/234-pipelines-18.png differ diff --git a/release-notes/2024/media/234-pipelines-19.png b/release-notes/2024/media/234-pipelines-19.png new file mode 100644 index 00000000000..a077e478977 Binary files /dev/null and b/release-notes/2024/media/234-pipelines-19.png differ diff --git a/release-notes/2024/media/234-pipelines-20.png b/release-notes/2024/media/234-pipelines-20.png new file mode 100644 index 00000000000..ab5a9146d9e Binary files /dev/null and b/release-notes/2024/media/234-pipelines-20.png differ diff --git a/release-notes/2024/media/234-repos-01.png b/release-notes/2024/media/234-repos-01.png new file mode 100644 index 00000000000..5b7f451bf5e Binary files /dev/null and b/release-notes/2024/media/234-repos-01.png differ diff --git a/release-notes/2024/media/234-repos-02.png b/release-notes/2024/media/234-repos-02.png new file mode 100644 index 00000000000..39a4a7bd517 Binary files /dev/null and b/release-notes/2024/media/234-repos-02.png differ diff --git a/release-notes/2024/media/234-repos-03.png b/release-notes/2024/media/234-repos-03.png new file mode 100644 index 00000000000..70b2e64122a Binary files /dev/null and b/release-notes/2024/media/234-repos-03.png differ diff --git a/release-notes/2024/media/234-repos-04.png b/release-notes/2024/media/234-repos-04.png new file mode 100644 index 00000000000..65c9755761e Binary files /dev/null and b/release-notes/2024/media/234-repos-04.png differ diff --git a/release-notes/2024/media/235-boards-01.gif b/release-notes/2024/media/235-boards-01.gif new file mode 100644 index 00000000000..b279d888111 Binary files /dev/null and b/release-notes/2024/media/235-boards-01.gif differ diff --git a/release-notes/2024/media/235-pipelines-01.png b/release-notes/2024/media/235-pipelines-01.png new file mode 100644 index 00000000000..39950b7b212 Binary files /dev/null and b/release-notes/2024/media/235-pipelines-01.png differ diff --git a/release-notes/2024/media/235-pipelines-02.png b/release-notes/2024/media/235-pipelines-02.png new file mode 100644 index 00000000000..adb230cd37c Binary files /dev/null and b/release-notes/2024/media/235-pipelines-02.png differ diff --git a/release-notes/2024/media/235-testplans-01.gif b/release-notes/2024/media/235-testplans-01.gif new file mode 100644 index 00000000000..a687cfd2266 Binary files /dev/null and b/release-notes/2024/media/235-testplans-01.gif differ diff --git a/release-notes/2024/media/235-testplans-01.png b/release-notes/2024/media/235-testplans-01.png new file mode 100644 index 00000000000..39c4af62256 Binary files /dev/null and b/release-notes/2024/media/235-testplans-01.png differ diff --git a/release-notes/2024/media/236-pipelines-01.png b/release-notes/2024/media/236-pipelines-01.png new file mode 100644 index 00000000000..0ded356cfd2 Binary files /dev/null and b/release-notes/2024/media/236-pipelines-01.png differ diff --git a/release-notes/2024/media/236-pipelines-02.png b/release-notes/2024/media/236-pipelines-02.png new file mode 100644 index 00000000000..07058bf5015 Binary files /dev/null and b/release-notes/2024/media/236-pipelines-02.png differ diff --git a/release-notes/2024/media/237-boards-01.gif b/release-notes/2024/media/237-boards-01.gif new file mode 100644 index 00000000000..1716b920f9c Binary files /dev/null and b/release-notes/2024/media/237-boards-01.gif differ diff --git a/release-notes/2024/media/237-boards-01.png b/release-notes/2024/media/237-boards-01.png new file mode 100644 index 00000000000..9593c14505d Binary files /dev/null and b/release-notes/2024/media/237-boards-01.png differ diff --git a/release-notes/2024/media/237-pipelines-01.png b/release-notes/2024/media/237-pipelines-01.png new file mode 100644 index 00000000000..fc5327cd5a7 Binary files /dev/null and b/release-notes/2024/media/237-pipelines-01.png differ diff --git a/release-notes/2024/media/237-pipelines-02.png b/release-notes/2024/media/237-pipelines-02.png new file mode 100644 index 00000000000..94f045e1360 Binary files /dev/null and b/release-notes/2024/media/237-pipelines-02.png differ diff --git a/release-notes/2024/media/237-pipelines-03.png b/release-notes/2024/media/237-pipelines-03.png new file mode 100644 index 00000000000..4a61d616278 Binary files /dev/null and b/release-notes/2024/media/237-pipelines-03.png differ diff --git a/release-notes/2024/media/237-pipelines-04.png b/release-notes/2024/media/237-pipelines-04.png new file mode 100644 index 00000000000..fc7a872f8b8 Binary files /dev/null and b/release-notes/2024/media/237-pipelines-04.png differ diff --git a/release-notes/2024/media/238-ghazdo-01.png b/release-notes/2024/media/238-ghazdo-01.png new file mode 100644 index 00000000000..193394794d5 Binary files /dev/null and b/release-notes/2024/media/238-ghazdo-01.png differ diff --git a/release-notes/2024/media/240-boards-02.png b/release-notes/2024/media/240-boards-02.png new file mode 100644 index 00000000000..6c7a4cacf4d Binary files /dev/null and b/release-notes/2024/media/240-boards-02.png differ diff --git a/release-notes/2024/media/240-pipelines-01.png b/release-notes/2024/media/240-pipelines-01.png new file mode 100644 index 00000000000..2e0668d3136 Binary files /dev/null and b/release-notes/2024/media/240-pipelines-01.png differ diff --git a/release-notes/2024/media/240-repos-01.gif b/release-notes/2024/media/240-repos-01.gif new file mode 100644 index 00000000000..0a9e8d92236 Binary files /dev/null and b/release-notes/2024/media/240-repos-01.gif differ diff --git a/release-notes/2024/media/241-ghazdo-01.png b/release-notes/2024/media/241-ghazdo-01.png new file mode 100644 index 00000000000..7bcc33d4d77 Binary files /dev/null and b/release-notes/2024/media/241-ghazdo-01.png differ diff --git a/release-notes/2024/media/241-pipelines-01.png b/release-notes/2024/media/241-pipelines-01.png new file mode 100644 index 00000000000..a39fdeaa770 Binary files /dev/null and b/release-notes/2024/media/241-pipelines-01.png differ diff --git a/release-notes/2024/media/242-boards-01.gif b/release-notes/2024/media/242-boards-01.gif new file mode 100644 index 00000000000..42d0f7f9699 Binary files /dev/null and b/release-notes/2024/media/242-boards-01.gif differ diff --git a/release-notes/2024/media/242-boards-01.png b/release-notes/2024/media/242-boards-01.png new file mode 100644 index 00000000000..35298e0316a Binary files /dev/null and b/release-notes/2024/media/242-boards-01.png differ diff --git a/release-notes/2024/media/242-pipelines-01.png b/release-notes/2024/media/242-pipelines-01.png new file mode 100644 index 00000000000..3d496532c2d Binary files /dev/null and b/release-notes/2024/media/242-pipelines-01.png differ diff --git a/release-notes/2024/media/243-ghazdo-01.png b/release-notes/2024/media/243-ghazdo-01.png new file mode 100644 index 00000000000..685ebebc4f6 Binary files /dev/null and b/release-notes/2024/media/243-ghazdo-01.png differ diff --git a/release-notes/2024/media/243-pipelines-01.png b/release-notes/2024/media/243-pipelines-01.png new file mode 100644 index 00000000000..acf563310d2 Binary files /dev/null and b/release-notes/2024/media/243-pipelines-01.png differ diff --git a/release-notes/2024/media/243-pipelines-02.png b/release-notes/2024/media/243-pipelines-02.png new file mode 100644 index 00000000000..030a5c831b7 Binary files /dev/null and b/release-notes/2024/media/243-pipelines-02.png differ diff --git a/release-notes/2024/media/244-reporting-01.png b/release-notes/2024/media/244-reporting-01.png new file mode 100644 index 00000000000..ee133e3ee97 Binary files /dev/null and b/release-notes/2024/media/244-reporting-01.png differ diff --git a/release-notes/2024/media/244-repos-01.gif b/release-notes/2024/media/244-repos-01.gif new file mode 100644 index 00000000000..642db736be5 Binary files /dev/null and b/release-notes/2024/media/244-repos-01.gif differ diff --git a/release-notes/2024/media/245-boards-01.png b/release-notes/2024/media/245-boards-01.png new file mode 100644 index 00000000000..86f73af0cf3 Binary files /dev/null and b/release-notes/2024/media/245-boards-01.png differ diff --git a/release-notes/2024/media/245-boards-02.png b/release-notes/2024/media/245-boards-02.png new file mode 100644 index 00000000000..cbaad6bb392 Binary files /dev/null and b/release-notes/2024/media/245-boards-02.png differ diff --git a/release-notes/2024/media/245-ghazdo-01.png b/release-notes/2024/media/245-ghazdo-01.png new file mode 100644 index 00000000000..03e39661873 Binary files /dev/null and b/release-notes/2024/media/245-ghazdo-01.png differ diff --git a/release-notes/2024/media/245-pipelines-01.png b/release-notes/2024/media/245-pipelines-01.png new file mode 100644 index 00000000000..fc5327cd5a7 Binary files /dev/null and b/release-notes/2024/media/245-pipelines-01.png differ diff --git a/release-notes/2024/media/245-repos-01.png b/release-notes/2024/media/245-repos-01.png new file mode 100644 index 00000000000..ca9b0038f42 Binary files /dev/null and b/release-notes/2024/media/245-repos-01.png differ diff --git a/release-notes/2024/media/245-testplans-01.gif b/release-notes/2024/media/245-testplans-01.gif new file mode 100644 index 00000000000..6c5c762454e Binary files /dev/null and b/release-notes/2024/media/245-testplans-01.gif differ diff --git a/release-notes/2024/media/246-boards-01.gif b/release-notes/2024/media/246-boards-01.gif new file mode 100644 index 00000000000..b279d888111 Binary files /dev/null and b/release-notes/2024/media/246-boards-01.gif differ diff --git a/release-notes/2024/media/246-boards-01.png b/release-notes/2024/media/246-boards-01.png new file mode 100644 index 00000000000..c826407e1dd Binary files /dev/null and b/release-notes/2024/media/246-boards-01.png differ diff --git a/release-notes/2024/media/246-general-01.png b/release-notes/2024/media/246-general-01.png new file mode 100644 index 00000000000..f2350791cfe Binary files /dev/null and b/release-notes/2024/media/246-general-01.png differ diff --git a/release-notes/2024/media/246-general-02.png b/release-notes/2024/media/246-general-02.png new file mode 100644 index 00000000000..d8ae161f701 Binary files /dev/null and b/release-notes/2024/media/246-general-02.png differ diff --git a/release-notes/2024/media/246-ghazdo-01.png b/release-notes/2024/media/246-ghazdo-01.png new file mode 100644 index 00000000000..e9897d69fdc Binary files /dev/null and b/release-notes/2024/media/246-ghazdo-01.png differ diff --git a/release-notes/2024/media/246-pipelines-01.png b/release-notes/2024/media/246-pipelines-01.png new file mode 100644 index 00000000000..4c8bb942782 Binary files /dev/null and b/release-notes/2024/media/246-pipelines-01.png differ diff --git a/release-notes/2024/media/246-pipelines-02.png b/release-notes/2024/media/246-pipelines-02.png new file mode 100644 index 00000000000..781cefe7e13 Binary files /dev/null and b/release-notes/2024/media/246-pipelines-02.png differ diff --git a/release-notes/2024/media/246-pipelines-03.png b/release-notes/2024/media/246-pipelines-03.png new file mode 100644 index 00000000000..4a387aeaccf Binary files /dev/null and b/release-notes/2024/media/246-pipelines-03.png differ diff --git a/release-notes/2024/media/246-pipelines-04.png b/release-notes/2024/media/246-pipelines-04.png new file mode 100644 index 00000000000..0809d4fdeed Binary files /dev/null and b/release-notes/2024/media/246-pipelines-04.png differ diff --git a/release-notes/2024/media/246-pipelines-05.png b/release-notes/2024/media/246-pipelines-05.png new file mode 100644 index 00000000000..18c1346ff47 Binary files /dev/null and b/release-notes/2024/media/246-pipelines-05.png differ diff --git a/release-notes/2024/media/246-repos-01.png b/release-notes/2024/media/246-repos-01.png new file mode 100644 index 00000000000..1b3f6e874f1 Binary files /dev/null and b/release-notes/2024/media/246-repos-01.png differ diff --git a/release-notes/2024/media/246-testplans-01.gif b/release-notes/2024/media/246-testplans-01.gif new file mode 100644 index 00000000000..c6099c73184 Binary files /dev/null and b/release-notes/2024/media/246-testplans-01.gif differ diff --git a/release-notes/2024/media/247-pipelines-01.png b/release-notes/2024/media/247-pipelines-01.png new file mode 100644 index 00000000000..12b916f1f6a Binary files /dev/null and b/release-notes/2024/media/247-pipelines-01.png differ diff --git a/release-notes/2024/media/247-pipelines-02.png b/release-notes/2024/media/247-pipelines-02.png new file mode 100644 index 00000000000..3a7ff5d7ad8 Binary files /dev/null and b/release-notes/2024/media/247-pipelines-02.png differ diff --git a/release-notes/2024/media/247-pipelines-03.png b/release-notes/2024/media/247-pipelines-03.png new file mode 100644 index 00000000000..5610e873992 Binary files /dev/null and b/release-notes/2024/media/247-pipelines-03.png differ diff --git a/release-notes/2024/media/247-repos-01.png b/release-notes/2024/media/247-repos-01.png new file mode 100644 index 00000000000..d5e81b8b0fd Binary files /dev/null and b/release-notes/2024/media/247-repos-01.png differ diff --git a/release-notes/2024/media/247-testplans-01.gif b/release-notes/2024/media/247-testplans-01.gif new file mode 100644 index 00000000000..00e3f30b1bc Binary files /dev/null and b/release-notes/2024/media/247-testplans-01.gif differ diff --git a/release-notes/2024/media/248-general-01.png b/release-notes/2024/media/248-general-01.png new file mode 100644 index 00000000000..0eb6c3af3c0 Binary files /dev/null and b/release-notes/2024/media/248-general-01.png differ diff --git a/release-notes/2024/media/248-repos-01.png b/release-notes/2024/media/248-repos-01.png new file mode 100644 index 00000000000..226dedef85e Binary files /dev/null and b/release-notes/2024/media/248-repos-01.png differ diff --git a/release-notes/2024/media/248-repos-02.png b/release-notes/2024/media/248-repos-02.png new file mode 100644 index 00000000000..f775b9d964d Binary files /dev/null and b/release-notes/2024/media/248-repos-02.png differ diff --git a/release-notes/2024/pipelines/sprint-233-update.md b/release-notes/2024/pipelines/sprint-233-update.md new file mode 100644 index 00000000000..7ca7d354980 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-233-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 233 update +description: See the Sprint 233 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2023 +--- + +# Azure Pipelines - Sprint 233 Update + +## Features + +[!INCLUDE [sprint-233-update-links](../includes/pipelines/sprint-233-update-links.md)] + +[!INCLUDE [sprint-233-update](../includes/pipelines/sprint-233-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-234-update.md b/release-notes/2024/pipelines/sprint-234-update.md new file mode 100644 index 00000000000..f9daeafe523 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-234-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 234 update +description: See the Sprint 234 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +--- + +# Azure Pipelines - Sprint 234 Update + +## Features + +[!INCLUDE [sprint-234-update-links](../includes/pipelines/sprint-234-update-links.md)] + +[!INCLUDE [sprint-234-update](../includes/pipelines/sprint-234-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-235-update.md b/release-notes/2024/pipelines/sprint-235-update.md new file mode 100644 index 00000000000..2441f6fcad6 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-235-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 235 update +description: See the Sprint 235 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +--- + +# Azure Pipelines - Sprint 235 Update + +## Features + +[!INCLUDE [sprint-235-update-links](../includes/pipelines/sprint-235-update-links.md)] + +[!INCLUDE [sprint-235-update](../includes/pipelines/sprint-235-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-236-update.md b/release-notes/2024/pipelines/sprint-236-update.md new file mode 100644 index 00000000000..d0c35ac87a3 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-236-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 236 update +description: See the Sprint 236 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 3/21/2024 +--- + +# Azure Pipelines - Sprint 236 Update + +## Features + +[!INCLUDE [sprint-236-update-links](../includes/pipelines/sprint-236-update-links.md)] + +[!INCLUDE [sprint-236-update](../includes/pipelines/sprint-236-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-237-update.md b/release-notes/2024/pipelines/sprint-237-update.md new file mode 100644 index 00000000000..af22e9b1525 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-237-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 237 update +description: See the Sprint 237 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 4/10/2024 +--- + +# Azure Pipelines - Sprint 237 Update + +## Features + +[!INCLUDE [sprint-237-update-links](../includes/pipelines/sprint-237-update-links.md)] + +[!INCLUDE [sprint-237-update](../includes/pipelines/sprint-237-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-238-update.md b/release-notes/2024/pipelines/sprint-238-update.md new file mode 100644 index 00000000000..d55e766f283 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-238-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 238 update +description: See the Sprint 238 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 5/2/2024 +--- + +# Azure Pipelines - Sprint 238 Update + +## Features + +[!INCLUDE [sprint-238-update-links](../includes/pipelines/sprint-238-update-links.md)] + +[!INCLUDE [sprint-238-update](../includes/pipelines/sprint-238-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-240-update.md b/release-notes/2024/pipelines/sprint-240-update.md new file mode 100644 index 00000000000..688a73883f2 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-240-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 240 update +description: See the Sprint 240 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +--- + +# Azure Pipelines - Sprint 240 Update + +## Features + +[!INCLUDE [sprint-240-update-links](../includes/pipelines/sprint-240-update-links.md)] + +[!INCLUDE [sprint-240-update](../includes/pipelines/sprint-240-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-241-update.md b/release-notes/2024/pipelines/sprint-241-update.md new file mode 100644 index 00000000000..f2877c92cf7 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-241-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 241 update +description: See the Sprint 241 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 7/3/2024 +--- + +# Azure Pipelines - Sprint 241 Update + +## Features + +[!INCLUDE [sprint-241-update-links](../includes/pipelines/sprint-241-update-links.md)] + +[!INCLUDE [sprint-241-update](../includes/pipelines/sprint-241-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-242-update.md b/release-notes/2024/pipelines/sprint-242-update.md new file mode 100644 index 00000000000..960ee8cc5f5 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-242-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 242 update +description: See the Sprint 242 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 7/25/2024 +--- + +# Azure Pipelines - Sprint 242 Update + +## Features + +[!INCLUDE [sprint-242-update-links](../includes/pipelines/sprint-242-update-links.md)] + +[!INCLUDE [sprint-242-update](../includes/pipelines/sprint-242-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-243-update.md b/release-notes/2024/pipelines/sprint-243-update.md new file mode 100644 index 00000000000..491cf29c783 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-243-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 243 update +description: See the Sprint 243 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 8/13/2024 +--- + +# Azure Pipelines - Sprint 243 Update + +## Features + +[!INCLUDE [sprint-243-update-links](../includes/pipelines/sprint-243-update-links.md)] + +[!INCLUDE [sprint-243-update](../includes/pipelines/sprint-243-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-244-update.md b/release-notes/2024/pipelines/sprint-244-update.md new file mode 100644 index 00000000000..36bbaa5c625 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-244-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 244 update +description: See the Sprint 244 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +--- + +# Azure Pipelines - Sprint 244 Update + +## Features + +[!INCLUDE [sprint-244-update-links](../includes/pipelines/sprint-244-update-links.md)] + +[!INCLUDE [sprint-244-update](../includes/pipelines/sprint-244-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-245-update.md b/release-notes/2024/pipelines/sprint-245-update.md new file mode 100644 index 00000000000..f83d03e5a10 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-245-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 245 update +description: See the Sprint 245 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +--- + +# Azure Pipelines - Sprint 245 Update + +## Features + +[!INCLUDE [sprint-245-update-links](../includes/pipelines/sprint-245-update-links.md)] + +[!INCLUDE [sprint-245-update](../includes/pipelines/sprint-245-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-246-update.md b/release-notes/2024/pipelines/sprint-246-update.md new file mode 100644 index 00000000000..f5182e313bf --- /dev/null +++ b/release-notes/2024/pipelines/sprint-246-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 246 update +description: See the Sprint 246 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/15/2024 +--- + +# Azure Pipelines - Sprint 246 Update + +## Features + +[!INCLUDE [sprint-246-update-links](../includes/pipelines/sprint-246-update-links.md)] + +[!INCLUDE [sprint-246-update](../includes/pipelines/sprint-246-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/pipelines/sprint-247-update.md b/release-notes/2024/pipelines/sprint-247-update.md new file mode 100644 index 00000000000..77eaed32025 --- /dev/null +++ b/release-notes/2024/pipelines/sprint-247-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 247 update +description: See the Sprint 247 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +--- + +# Azure Pipelines - Sprint 247 Update + +## Features + +[!INCLUDE [sprint-247-update-links](../includes/pipelines/sprint-247-update-links.md)] + +[!INCLUDE [sprint-247-update](../includes/pipelines/sprint-247-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/reporting/sprint-244-update.md b/release-notes/2024/reporting/sprint-244-update.md new file mode 100644 index 00000000000..1ba050d8384 --- /dev/null +++ b/release-notes/2024/reporting/sprint-244-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Reporting Sprint 244 Update +description: See the Sprint 244 feature updates for Reporting, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +--- + +# Reporting - Sprint 244 Update + +## Features + +[!INCLUDE [sprint-244-update-links](../includes/reporting/sprint-244-update-links.md)] + +[!INCLUDE [sprint-244-update](../includes/reporting/sprint-244-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/repos/sprint-234-update.md b/release-notes/2024/repos/sprint-234-update.md new file mode 100644 index 00000000000..8c56c409207 --- /dev/null +++ b/release-notes/2024/repos/sprint-234-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 234 Update +description: See the Sprint 234 feature updates for Azure Repos, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +--- + +# Azure Repos - Sprint 234 Update + +## Features + +[!INCLUDE [sprint-234-update-links](../includes/repos/sprint-234-update-links.md)] + +[!INCLUDE [sprint-234-update](../includes/repos/sprint-234-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/repos/sprint-235-update.md b/release-notes/2024/repos/sprint-235-update.md new file mode 100644 index 00000000000..3f93e82988b --- /dev/null +++ b/release-notes/2024/repos/sprint-235-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 235 Update +description: See the Sprint 235 feature updates for Azure Repos, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +--- + +# Azure Repos - Sprint 235 Update + +## Features + +[!INCLUDE [sprint-235-update-links](../includes/repos/sprint-235-update-links.md)] + +[!INCLUDE [sprint-235-update](../includes/repos/sprint-235-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/repos/sprint-240-update.md b/release-notes/2024/repos/sprint-240-update.md new file mode 100644 index 00000000000..daf4032e941 --- /dev/null +++ b/release-notes/2024/repos/sprint-240-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 240 Update +description: See the Sprint 240 feature updates for Azure Repos, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 6/13/2024 +--- + +# Azure Repos - Sprint 240 Update + +## Features + +[!INCLUDE [sprint-240-update-links](../includes/repos/sprint-240-update-links.md)] + +[!INCLUDE [sprint-240-update](../includes/repos/sprint-240-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/repos/sprint-244-update.md b/release-notes/2024/repos/sprint-244-update.md new file mode 100644 index 00000000000..8dea66a8763 --- /dev/null +++ b/release-notes/2024/repos/sprint-244-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 244 Update +description: See the Sprint 244 feature updates for Azure Repos, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +--- + +# Azure Repos - Sprint 244 Update + +## Features + +[!INCLUDE [sprint-244-update-links](../includes/repos/sprint-244-update-links.md)] + +[!INCLUDE [sprint-244-update](../includes/repos/sprint-244-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/repos/sprint-245-update.md b/release-notes/2024/repos/sprint-245-update.md new file mode 100644 index 00000000000..6396c7ebcb3 --- /dev/null +++ b/release-notes/2024/repos/sprint-245-update.md @@ -0,0 +1,33 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 245 Update +description: See the Sprint 245 feature updates for Azure Repos, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +--- + +# Azure Repos - Sprint 245 Update + +## Features +> [!NOTE] +> We are rolling out the feature. Receiving it in your organization depends on various factors, and it may arrive later if you don't have it yet. + +[!INCLUDE [sprint-245-update-links](../includes/repos/sprint-245-update-links.md)] + +[!INCLUDE [sprint-245-update](../includes/repos/sprint-245-update.md)] + +## Next steps + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). diff --git a/release-notes/2024/repos/sprint-246-update.md b/release-notes/2024/repos/sprint-246-update.md new file mode 100644 index 00000000000..862abfe129d --- /dev/null +++ b/release-notes/2024/repos/sprint-246-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 246 Update +description: See the Sprint 246 feature updates for Azure Repos, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/15/2024 +--- + +# Azure Repos - Sprint 246 Update + +## Features + +[!INCLUDE [sprint-246-update-links](../includes/repos/sprint-246-update-links.md)] + +[!INCLUDE [sprint-246-update](../includes/repos/sprint-246-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/repos/sprint-247-update.md b/release-notes/2024/repos/sprint-247-update.md new file mode 100644 index 00000000000..b3a2530973b --- /dev/null +++ b/release-notes/2024/repos/sprint-247-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 247 Update +description: See the Sprint 247 feature updates for Azure Repos, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 11/4/2024 +--- + +# Azure Repos - Sprint 247 Update + +## Features + +[!INCLUDE [sprint-247-update-links](../includes/repos/sprint-247-update-links.md)] + +[!INCLUDE [sprint-247-update](../includes/repos/sprint-247-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2024/sprint-232-update.md b/release-notes/2024/sprint-232-update.md new file mode 100644 index 00000000000..f27166c14ee --- /dev/null +++ b/release-notes/2024/sprint-232-update.md @@ -0,0 +1,53 @@ +--- +title: Select a geography when creating a new Azure DevOps organization +author: ckanyika +ms.author: ckanyika +ms.date: 1/11/2024 +description: Select a geography when creating a new Azure DevOps organization +--- +# Select a geography when creating a new Azure DevOps organization + +With this update, you can select a geography instead of a region, when creating a new Azure DevOps organization. + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-232-update-links](includes/general/sprint-232-update-links.md)] + +### Azure Test Plans + + +[!INCLUDE [sprint-232-update-links](includes/testplans/sprint-232-update-links.md)] + +## General + +[!INCLUDE [sprint-232-update](includes/general/sprint-232-update.md)] + +## Azure Test Plans + +[!INCLUDE [sprint-232-update](includes/testplans/sprint-232-update.md)] + + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Screenshot Make a suggestion.](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Rajesh Ramamurthy diff --git a/release-notes/2024/sprint-233-update.md b/release-notes/2024/sprint-233-update.md new file mode 100644 index 00000000000..160c7e6c5df --- /dev/null +++ b/release-notes/2024/sprint-233-update.md @@ -0,0 +1,60 @@ +--- +title: General availability of Team automation rules and improved AB#ID validation +author: ckanyika +ms.author: ckanyika +ms.date: 1/19/2024 +description: General availability of Team automation rules and improved AB# validation +--- +# General availability of Team automation rules and improved AB# validation + +We're excited to announce that improved AB# validation by the Azure Boards App in GitHub and Team Automation rules are generally available! We improved AB# validation so that you can get notified when a link to a work item is not valid. In Team Automation Rules, you can now configure each backlog level to automate the opening and closing/resolving of work items based on the state(s) of the child item. + +With this update, we also introduce support for custom CodeQL queries in Code scanning! This will let you craft your own queries tailored to identify issues specific to your codebase. + +Check out the release notes for details. + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-233-update-links](includes/ghazdo/sprint-233-update-links.md)] + +### Azure Boards + +[!INCLUDE [sprint-233-update-links](includes/boards/sprint-233-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-233-update-links](includes/pipelines/sprint-233-update-links.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-233-update](includes/ghazdo/sprint-233-update.md)] +## Azure Boards + +[!INCLUDE [sprint-233-update](includes/boards/sprint-233-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-233-update](includes/pipelines/sprint-233-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Dan Hellem diff --git a/release-notes/2024/sprint-234-update.md b/release-notes/2024/sprint-234-update.md new file mode 100644 index 00000000000..45049a41aba --- /dev/null +++ b/release-notes/2024/sprint-234-update.md @@ -0,0 +1,87 @@ +--- +title: General availability of Workload identity federation for Azure Resource Manager service connections +author: ckanyika +ms.author: ckanyika +ms.date: 2/9/2024 +description: General availability of Workload identity federation for Azure Resource Manager service connections +--- +# General availability of Workload identity federation for Azure Resource Manager service connections + +We’re excited to announce that Workload identity federation is now generally available in Azure Pipelines! +You can enjoy a streamlined experience without the need to manage secrets and certificates in Azure service connections. + +With this update, we are also previewing a new feature as part of our enhanced GitHub integration with Azure Boards. You can now link directly to GitHub pull requests or commits. No more switching between windows or copy/pasting. Simply select the repository you want, find the pull request or commit you need, and link it! + +Check out the release notes to learn more about these features. + +### General + +[!INCLUDE [sprint-234-update-links](includes/general/sprint-234-update-links.md)] + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-234-update-links](includes/ghazdo/sprint-234-update-links.md)] + +### Azure Boards + +[!INCLUDE [sprint-234-update-links](includes/boards/sprint-234-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-234-update-links](includes/pipelines/sprint-234-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-234-update-links](includes/repos/sprint-234-update-links.md)] + +### Azure Artifacts + +[!INCLUDE [sprint-234-update-links](includes/artifacts/sprint-234-update-links.md)] + +## General + +[!INCLUDE [sprint-234-update](includes/general/sprint-234-update.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-234-update](includes/ghazdo/sprint-234-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-234-update](includes/boards/sprint-234-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-234-update](includes/pipelines/sprint-234-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-234-update](includes/repos/sprint-234-update.md)] + +## Azure Artifacts + +[!INCLUDE [sprint-234-update](includes/artifacts/sprint-234-update.md)] + + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Dan Hellem diff --git a/release-notes/2024/sprint-235-update.md b/release-notes/2024/sprint-235-update.md new file mode 100644 index 00000000000..8a04bb91d93 --- /dev/null +++ b/release-notes/2024/sprint-235-update.md @@ -0,0 +1,69 @@ +--- +title: Show GitHub pull request details on linked work item (preview) +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +description: Show GitHub pull request details on linked work item (preview) +--- +# Show GitHub pull request details on linked work item (preview) + +With this update, we've enhanced the way you can view GitHub pull request statuses within the Azure Boards work item. Now, you can quickly check if a pull request is in draft mode, pending review, or undergoing status checks. This enhancement lets you see beyond the simple open or closed statuses—without having to open the pull request. + +Additionally, we are excited to announce the Test Plan and Suite ID Search feature in Azure Test Plans! This update is part of our ongoing effort to improve your test management experience. + +Check out the release notes for details. + +### Azure Boards: + +[!INCLUDE [sprint-235-update-links](includes/boards/sprint-235-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-235-update-links](includes/repos/sprint-235-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-235-update-links](includes/pipelines/sprint-235-update-links.md)] + +### Azure Test Plans: + +[!INCLUDE [sprint-235-update-links](includes/testplans/sprint-235-update-links.md)] + +## Azure Boards + +[!INCLUDE [sprint-235-update](includes/boards/sprint-235-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-235-update](includes/repos/sprint-235-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-235-update](includes/pipelines/sprint-235-update.md)] + +## Azure Test Plans + +[!INCLUDE [sprint-235-update](includes/testplans/sprint-235-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Dan Hellem diff --git a/release-notes/2024/sprint-236-update.md b/release-notes/2024/sprint-236-update.md new file mode 100644 index 00000000000..d7ea5d1f3d5 --- /dev/null +++ b/release-notes/2024/sprint-236-update.md @@ -0,0 +1,51 @@ +--- +title: Resource utilization notifications in Azure Pipelines agent +author: ckanyika +ms.author: ckanyika +ms.date: 3/26/2024 +description: Resource utilization notifications in Azure Pipelines agent +--- +# Resource utilization notifications in Azure Pipelines agent + +With this update, the Azure Pipelines agent now displays a notification if you encounter resource constraints, such as limitations on memory or disk space. + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-236-update-links](includes/general/sprint-236-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-236-update-links](includes/pipelines/sprint-236-update-links.md)] + +## General + +[!INCLUDE [sprint-236-update](includes/general/sprint-236-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-236-update](includes/pipelines/sprint-236-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2024/sprint-237-update.md b/release-notes/2024/sprint-237-update.md new file mode 100644 index 00000000000..bb68aa72731 --- /dev/null +++ b/release-notes/2024/sprint-237-update.md @@ -0,0 +1,61 @@ +--- +title: Improvements to secret scanning capabilities and New Board Hub on by default +author: ckanyika +ms.author: ckanyika +ms.date: 4/10/2024 +description: Improvements to secret scanning capabilities and New Board Hub on by default +--- +# Improvements to secret scanning capabilities and New Board Hub on by default + +We're excited to announce we're rolling out a security overview, a single pane of glass view for your Advanced Security alerts and enablement, and we've also improved our secret scanning capabilities by adding more partner patterns in GitHub Advanced Security! This will significantly increase the detection abilities of our secret scanning feature, providing a more secure environment for your projects. + +With this update, we're close to making New Boards Hub your default experience! It will introduce an updated design, better performance, and enhanced accessibility. In addition, we're previewing two new features within Boards: AB# Links on GitHub pull requests and a more reliable GitHub repository search, removing the risk of timeouts. + +Check out the release notes for details. + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-237-update-links](includes/ghazdo/sprint-237-update-links.md)] + +### Azure Boards + +[!INCLUDE [sprint-237-update-links](includes/boards/sprint-237-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-237-update-links](includes/pipelines/sprint-237-update-links.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-237-update](includes/ghazdo/sprint-237-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-237-update](includes/boards/sprint-237-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-237-update](includes/pipelines/sprint-237-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Dan Hellem diff --git a/release-notes/2024/sprint-238-update.md b/release-notes/2024/sprint-238-update.md new file mode 100644 index 00000000000..02c84ec838e --- /dev/null +++ b/release-notes/2024/sprint-238-update.md @@ -0,0 +1,59 @@ +--- +title: View third-party providers code scan results in Azure DevOps +author: ckanyika +ms.author: ckanyika +ms.date: 5/2/2024 +description: View third-party providers code scan results in Azure DevOps +--- +# View third-party providers code scan results in Azure DevOps + +As we continue our integration with GitHub Advanced Security, we are excited to announce that you can now leverage the publish task (AdvancedSecurity-Publish@1) to import security results from third-party providers into the Advanced Security Code Scanning alerts hub! + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-238-update-links](includes/general/sprint-238-update-links.md)] + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-238-update-links](includes/ghazdo/sprint-238-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-238-update-links](includes/pipelines/sprint-238-update-links.md)] + +## General + +[!INCLUDE [sprint-238-update](includes/general/sprint-238-update.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-238-update](includes/ghazdo/sprint-238-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-238-update](includes/pipelines/sprint-238-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2024/sprint-240-update.md b/release-notes/2024/sprint-240-update.md new file mode 100644 index 00000000000..1faba1ecef0 --- /dev/null +++ b/release-notes/2024/sprint-240-update.md @@ -0,0 +1,81 @@ +--- +title: Setting to disable creation of TFVC repositories +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +description: Setting to disable creation of TFVC repositories +--- +# Setting to disable creation of TFVC repositories + +With this update, we're introducing a new setting to disable creation of TFVC repositories. This change focuses on new projects while ensuring that your existing TFVC repositories remain unaffected. + +In addition, we're excited to announce that in Azure Pipelines, a new REST API endpoint is available for requesting OIDC tokens! This allows task developers to generate idTokens for Entra ID authentication, enhancing security and ease of use. + +Lastly, in Azure Boards, area and iteration paths can now only be deleted if they are no longer associated with any work items. This improvement prevents disruptions and ensures teams retain access to their boards and backlogs. + +Check out the release notes for details. + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-240-update-links](includes/ghazdo/sprint-240-update-links.md)] + +### Azure Boards: + +[!INCLUDE [sprint-240-update-links](includes/boards/sprint-240-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-240-update-links](includes/repos/sprint-240-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-240-update-links](includes/pipelines/sprint-240-update-links.md)] + +### Azure Test Plans: + +[!INCLUDE [sprint-240-update-links](includes/testplans/sprint-240-update-links.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-240-update](includes/ghazdo/sprint-240-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-240-update](includes/boards/sprint-240-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-240-update](includes/repos/sprint-240-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-240-update](includes/pipelines/sprint-240-update.md)] + +## Azure Test Plans + +[!INCLUDE [sprint-240-update](includes/testplans/sprint-240-update.md)] + + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica + diff --git a/release-notes/2024/sprint-241-update.md b/release-notes/2024/sprint-241-update.md new file mode 100644 index 00000000000..71909eb55c5 --- /dev/null +++ b/release-notes/2024/sprint-241-update.md @@ -0,0 +1,59 @@ +--- +title: Improved security with new personal access token format +author: ckanyika +ms.author: ckanyika +ms.date: 7/3/2024 +description: Improved security with new personal access token format +--- +# Improved security with new personal access token format + + We are excited to announce improvements to the format of personal access tokens (PATs), aimed at enhancing security and boosting secret detection capabilities! + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-241-update-links](includes/general/sprint-241-update-links.md)] + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-241-update-links](includes/ghazdo/sprint-241-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-241-update-links](includes/pipelines/sprint-241-update-links.md)] + +## General + +[!INCLUDE [sprint-241-update](includes/general/sprint-241-update.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-241-update](includes/ghazdo/sprint-241-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-241-update](includes/pipelines/sprint-241-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2024/sprint-242-update.md b/release-notes/2024/sprint-242-update.md new file mode 100644 index 00000000000..a74d4524aa2 --- /dev/null +++ b/release-notes/2024/sprint-242-update.md @@ -0,0 +1,53 @@ +--- +title: Enhanced GitHub integration and Azure Pipelines security +author: ckanyika +ms.author: ckanyika +ms.date: 7/25/2024 +description: Enhanced GitHub integration and Azure Pipelines security +--- +# Enhanced GitHub integration and Azure Pipelines security + +With this update, we have two new GitHub integration improvements to share. First, you can now create a new GitHub branch directly from a work item. Secondly, we have improved the connection experience to GitHub Repositories, reducing the risk of timeout errors and long wait times for customers with thousands of repositories. + +In addition, we’re excited to announce that in Azure Pipelines, you can enhance pipeline security by making any YAML stage unskippable using a new property setting. + +Check out the release notes for details. + +### Azure Boards + +[!INCLUDE [sprint-242-update-links](includes/boards/sprint-242-update-links.md)] + + +### Azure Pipelines + +[!INCLUDE [sprint-242-update-links](includes/pipelines/sprint-242-update-links.md)] + +## Azure Boards + +[!INCLUDE [sprint-242-update](includes/boards/sprint-242-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-242-update](includes/pipelines/sprint-242-update.md)] + + + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + diff --git a/release-notes/2024/sprint-243-update.md b/release-notes/2024/sprint-243-update.md new file mode 100644 index 00000000000..128e85b681b --- /dev/null +++ b/release-notes/2024/sprint-243-update.md @@ -0,0 +1,55 @@ +--- +title: Managed DevOps Pools for Azure DevOps (preview) +author: ckanyika +ms.author: ckanyika +ms.date: 8/13/2024 +description: Managed DevOps Pools for Azure DevOps (preview) +--- +# Managed DevOps Pools for Azure DevOps (preview) + +We’re excited to announce the preview of Managed DevOps Pools, designed to help development and platform engineering teams quickly set up and manage custom DevOps pools. + +Additionally, we've enhanced the Meter Usage estimate APIs for GitHub Advanced Security, providing new capabilities that help you identify users. + +Check out the release notes for details. + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-243-update-links](includes/ghazdo/sprint-243-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-243-update-links](includes/pipelines/sprint-243-update-links.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-243-update](includes/ghazdo/sprint-243-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-243-update](includes/pipelines/sprint-243-update.md)] + + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica + diff --git a/release-notes/2024/sprint-244-update.md b/release-notes/2024/sprint-244-update.md new file mode 100644 index 00000000000..bf3c7f8425f --- /dev/null +++ b/release-notes/2024/sprint-244-update.md @@ -0,0 +1,77 @@ +--- +title: Retrieve all branches with successful Advanced Security analyses + +author: ckanyika +ms.author: ckanyika +ms.date: 9/4/2024 +description: Retrieve all branches with successful Advanced Security analyses +--- +# Retrieve all branches with successful Advanced Security analyses + +You can now retrieve a list of branches in a particular repository where Advanced Security analysis has been performed. In addition, you can use the List Alerts API to retrieve a list of all alerts across all branches with Advanced Security results. + +Check out the release notes for details. + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-244-update-links](includes/ghazdo/sprint-244-update-links.md)] + +### Azure Boards + +[!INCLUDE [sprint-244-update-links](includes/boards/sprint-244-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-244-update-links](includes/repos/sprint-244-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-244-update-links](includes/pipelines/sprint-244-update-links.md)] + +### Reporting + +[!INCLUDE [sprint-244-update-links](includes/reporting/sprint-244-update-links.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-244-update](includes/ghazdo/sprint-244-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-244-update](includes/boards/sprint-244-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-244-update](includes/repos/sprint-244-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-244-update](includes/pipelines/sprint-244-update.md)] + +## Reporting + +[!INCLUDE [sprint-244-update](includes/reporting/sprint-244-update.md)] + + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Screenshot Make a suggestion.](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2024/sprint-245-update.md b/release-notes/2024/sprint-245-update.md new file mode 100644 index 00000000000..1da2a0e6c32 --- /dev/null +++ b/release-notes/2024/sprint-245-update.md @@ -0,0 +1,77 @@ +--- +title: Enhanced AB# link tracking in GitHub pull requests +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +description: Enhanced AB# link tracking in GitHub pull requests +--- +# Enhanced AB# link tracking in GitHub pull requests + +With this update, AB# links now appear directly in the Development section of GitHub pull requests, as long as they are included in the pull request description. This enhancement simplifies access to linked work items through the Azure Boards and GitHub integration. + +We’re also excited to introduce enhanced monitoring tools, offering greater visibility into your repository’s health and helping you maintain its performance more efficiently! + +Check out the release notes for details. + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-245-update-links](includes/ghazdo/sprint-245-update-links.md)] + +### Azure Boards: + +[!INCLUDE [sprint-245-update-links](includes/boards/sprint-245-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-245-update-links](includes/repos/sprint-245-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-245-update-links](includes/pipelines/sprint-245-update-links.md)] + +### Azure Test Plans: + +[!INCLUDE [sprint-245-update-links](includes/testplans/sprint-245-update-links.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-245-update](includes/ghazdo/sprint-245-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-245-update](includes/boards/sprint-245-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-245-update](includes/repos/sprint-245-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-245-update](includes/pipelines/sprint-245-update.md)] + +## Azure Test Plans + +[!INCLUDE [sprint-245-update](includes/testplans/sprint-245-update.md)] + +## Next steps + +> [!NOTE] +>We are rolling out the feature. Receiving it in your organization depends on various factors, and it may arrive later if you don't have it yet. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Dan Hellem diff --git a/release-notes/2024/sprint-246-update.md b/release-notes/2024/sprint-246-update.md new file mode 100644 index 00000000000..a026c00746f --- /dev/null +++ b/release-notes/2024/sprint-246-update.md @@ -0,0 +1,95 @@ +--- +title: Enhanced security and workflow efficiency +author: ckanyika +ms.author: ckanyika +ms.date: 10/16/2024 +description: Enhanced security and workflow efficiency +--- +# Enhanced security and workflow efficiency + +This sprint brings various improvements focused on boosting security and streamlining workflow efficiency. Among these improvements, the Service Connection Creation Experience in Azure Pipelines. This enables teams to set up service connections utilizing existing managed identities with workload identity federation. It also simplifies configuration and reduces the risk of over-privileged identities. + +Additionally, we're excited to announce that in Azure Repos, markdown files with mermaid syntax will now render as diagrams in file previews and pull requests, providing clearer visuals for your documentation. + +Lastly, in GitHub Advanced Security, pull request annotations now deliver in-line notifications for dependency and code scanning, simplifying the process for teams to detect and address potential problems during code reviews. + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-246-update-links](includes/general/sprint-246-update-links.md)] + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-246-update-links](includes/ghazdo/sprint-246-update-links.md)] + +### Azure Boards: + +[!INCLUDE [sprint-246-update-links](includes/boards/sprint-246-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-246-update-links](includes/repos/sprint-246-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-246-update-links](includes/pipelines/sprint-246-update-links.md)] + +### Azure Artifacts + +[!INCLUDE [sprint-246-update-links](includes/artifacts/sprint-246-update-links.md)] + +### Wiki + +[!INCLUDE [sprint-246-update-links](includes/wiki/sprint-246-update-links.md)] + +## General + +[!INCLUDE [sprint-246-update](includes/general/sprint-246-update.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-246-update](includes/ghazdo/sprint-246-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-246-update](includes/boards/sprint-246-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-246-update](includes/repos/sprint-246-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-246-update](includes/pipelines/sprint-246-update.md)] + +## Azure Artifacts + +[!INCLUDE [sprint-246-update](includes/artifacts/sprint-246-update.md)] + +## Wiki + +[!INCLUDE [sprint-246-update](includes/wiki/sprint-246-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Dan Hellem diff --git a/release-notes/2024/sprint-247-update.md b/release-notes/2024/sprint-247-update.md new file mode 100644 index 00000000000..f7ebe8ca66f --- /dev/null +++ b/release-notes/2024/sprint-247-update.md @@ -0,0 +1,76 @@ +--- +title: Improved GitHub Advanced Security Scanning +author: ckanyika +ms.author: ckanyika +ms.date: 11/13/2024 +description: Improved GitHub Advanced Security Scanning +--- +# Improved GitHub Advanced Security Scanning + +We're excited to introduce new updates in GitHub Advanced Security for Azure DevOps, featuring commit-less builds for expanded dependency scanning and improved file previews with annotations for CodeQL scans. + + +Check out the release notes for details. + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-247-update-links](includes/ghazdo/sprint-247-update-links.md)] + +### Azure Boards: + +[!INCLUDE [sprint-247-update-links](includes/boards/sprint-247-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-247-update-links](includes/repos/sprint-247-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-247-update-links](includes/pipelines/sprint-247-update-links.md)] + +### Test Plans + +[!INCLUDE [sprint-247-update-links](includes/testplans/sprint-247-update-links.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-247-update](includes/ghazdo/sprint-247-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-247-update](includes/boards/sprint-247-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-247-update](includes/repos/sprint-247-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-247-update](includes/pipelines/sprint-247-update.md)] + +## Test Plans + +[!INCLUDE [sprint-247-update](includes/testplans/sprint-247-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Dan Hellem diff --git a/release-notes/2024/testplans/sprint-232-update.md b/release-notes/2024/testplans/sprint-232-update.md new file mode 100644 index 00000000000..d7077d9155c --- /dev/null +++ b/release-notes/2024/testplans/sprint-232-update.md @@ -0,0 +1,20 @@ +--- +title: Azure DevOps Release Notes - Azure Test Plans Sprint 232 Update + +description: See the Sprint 232 feature updates for Azure Test Plans, including next steps. + +author: ckanyika +ms.author: ckanyika +ms.date: 1/11/2024 +--- + +# Azure Test Plans - Sprint 232 Update + +## Features + +[!INCLUDE [sprint-232-update-links](../includes/testplans/sprint-232-update-links.md)] + +[!INCLUDE [sprint-232-update](../includes/testplans/sprint-232-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] + diff --git a/release-notes/2024/testplans/sprint-235-update.md b/release-notes/2024/testplans/sprint-235-update.md new file mode 100644 index 00000000000..ec86d06f54f --- /dev/null +++ b/release-notes/2024/testplans/sprint-235-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Test Plans Sprint 235 Update +description: See the Sprint 235 feature updates for Azure Test Plans, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/29/2024 +--- + +# Azure Test Plans - Sprint 235 Update + +## Features + +[!INCLUDE [sprint-235-update-links](../includes/testplans/sprint-235-update-links.md)] + +[!INCLUDE [sprint-235-update](../includes/testplans/sprint-235-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/testplans/sprint-240-update.md b/release-notes/2024/testplans/sprint-240-update.md new file mode 100644 index 00000000000..bd6e0289a96 --- /dev/null +++ b/release-notes/2024/testplans/sprint-240-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Test Plans Sprint 240 Update +description: See the Sprint 240 feature updates for Azure Test Plans, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 6/14/2024 +--- + +# Azure Test Plans - Sprint 240 Update + +## Features + +[!INCLUDE [sprint-240-update-links](../includes/testplans/sprint-240-update-links.md)] + +[!INCLUDE [sprint-240-update](../includes/testplans/sprint-240-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/testplans/sprint-245-update.md b/release-notes/2024/testplans/sprint-245-update.md new file mode 100644 index 00000000000..6dd6ed2e16f --- /dev/null +++ b/release-notes/2024/testplans/sprint-245-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Test Plans Sprint 245 Update +description: See the Sprint 245 feature updates for Azure Test Plans, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 9/26/2024 +--- + +# Azure Test Plans - Sprint 245 Update + +## Features + +[!INCLUDE [sprint-245-update-links](../includes/testplans/sprint-245-update-links.md)] + +[!INCLUDE [sprint-245-update](../includes/testplans/sprint-245-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/testplans/sprint-247-update.md b/release-notes/2024/testplans/sprint-247-update.md new file mode 100644 index 00000000000..782fbbf7ceb --- /dev/null +++ b/release-notes/2024/testplans/sprint-247-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Test Plans Sprint 247 Update +description: See the Sprint 247 feature updates for Azure Test Plans, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 11/4/2024 +--- + +# Azure Test Plans - Sprint 247 Update + +## Features + +[!INCLUDE [sprint-247-update-links](../includes/testplans/sprint-247-update-links.md)] + +[!INCLUDE [sprint-247-update](../includes/testplans/sprint-247-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2024/wiki/sprint-246-update.md b/release-notes/2024/wiki/sprint-246-update.md new file mode 100644 index 00000000000..286c5421694 --- /dev/null +++ b/release-notes/2024/wiki/sprint-246-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Wiki Sprint 246 Update +description: See the Sprint 246 feature updates for Wiki, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 10/15/2024 +--- + +# Wiki - Sprint 246 Update + +## Features + +[!INCLUDE [sprint-246-update-links](../includes/wiki/sprint-246-update-links.md)] + +[!INCLUDE [sprint-246-update](../includes/wiki/sprint-246-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/boards/sprint-248-update.md b/release-notes/2025/boards/sprint-248-update.md new file mode 100644 index 00000000000..e753de6f551 --- /dev/null +++ b/release-notes/2025/boards/sprint-248-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 248 Update +description: See the Sprint 248 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +--- + +# Azure Boards - Sprint 248 Update + +## Features + +[!INCLUDE [sprint-248-update-links](../includes/boards/sprint-248-update-links.md)] + +[!INCLUDE [sprint-248-update](../includes/boards/sprint-248-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/boards/sprint-252-update.md b/release-notes/2025/boards/sprint-252-update.md new file mode 100644 index 00000000000..c39ed79c413 --- /dev/null +++ b/release-notes/2025/boards/sprint-252-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 252 Update +description: See the Sprint 252 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +--- + +# Azure Boards - Sprint 252 Update + +## Features + +[!INCLUDE [sprint-252-update-links](../includes/boards/sprint-252-update-links.md)] + +[!INCLUDE [sprint-252-update](../includes/boards/sprint-252-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/boards/sprint-254-update.md b/release-notes/2025/boards/sprint-254-update.md new file mode 100644 index 00000000000..aea0960f346 --- /dev/null +++ b/release-notes/2025/boards/sprint-254-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Boards Sprint 254 Update +description: See the Sprint 254 feature updates for Azure Boards, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +--- + +# Azure Boards - Sprint 254 Update + +## Features + +[!INCLUDE [sprint-254-update-links](../includes/boards/sprint-254-update-links.md)] + +[!INCLUDE [sprint-254-update](../includes/boards/sprint-254-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/general/sprint-251-update.md b/release-notes/2025/general/sprint-251-update.md new file mode 100644 index 00000000000..31d0ab20f75 --- /dev/null +++ b/release-notes/2025/general/sprint-251-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 251 Update +description: See the Sprint 251 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/12/2025 +--- + +# Azure DevOps - Sprint 251 Update + +## Features + +[!INCLUDE [sprint-251-update-links](../includes/general/sprint-251-update-links.md)] + +[!INCLUDE [sprint-251-update](../includes/general/sprint-251-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2025/general/sprint-252-update.md b/release-notes/2025/general/sprint-252-update.md new file mode 100644 index 00000000000..9b6c2d85560 --- /dev/null +++ b/release-notes/2025/general/sprint-252-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 252 Update +description: See the Sprint 252 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +--- + +# Azure DevOps - Sprint 252 Update + +## Features + +[!INCLUDE [sprint-252-update-links](../includes/general/sprint-252-update-links.md)] + +[!INCLUDE [sprint-252-update](../includes/general/sprint-252-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2025/general/sprint-253-update.md b/release-notes/2025/general/sprint-253-update.md new file mode 100644 index 00000000000..09505529e78 --- /dev/null +++ b/release-notes/2025/general/sprint-253-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 253 Update +description: See the Sprint 253 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 3/20/2025 +--- + +# Azure DevOps - Sprint 253 Update + +## Features + +[!INCLUDE [sprint-253-update-links](../includes/general/sprint-253-update-links.md)] + +[!INCLUDE [sprint-253-update](../includes/general/sprint-253-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2025/general/sprint-254-update.md b/release-notes/2025/general/sprint-254-update.md new file mode 100644 index 00000000000..db6eb04440e --- /dev/null +++ b/release-notes/2025/general/sprint-254-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure DevOps Sprint 254 Update +description: See the Sprint 254 feature updates for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +--- + +# Azure DevOps - Sprint 254 Update + +## Features + +[!INCLUDE [sprint-254-update-links](../includes/general/sprint-254-update-links.md)] + +[!INCLUDE [sprint-254-update](../includes/general/sprint-254-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2025/ghazdo/sprint-248-update.md b/release-notes/2025/ghazdo/sprint-248-update.md new file mode 100644 index 00000000000..4b17827be3d --- /dev/null +++ b/release-notes/2025/ghazdo/sprint-248-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 248 Update +description: See the Sprint 248 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 248 Update + +## Features + +[!INCLUDE [sprint-248-update-links](../includes/ghazdo/sprint-248-update-links.md)] + +[!INCLUDE [sprint-248-update](../includes/ghazdo/sprint-248-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2025/ghazdo/sprint-251-update.md b/release-notes/2025/ghazdo/sprint-251-update.md new file mode 100644 index 00000000000..9ae8bf687a9 --- /dev/null +++ b/release-notes/2025/ghazdo/sprint-251-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 251 Update +description: See the Sprint 251 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/12/2025 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 251 Update + +## Features + +[!INCLUDE [sprint-251-update-links](../includes/ghazdo/sprint-251-update-links.md)] + +[!INCLUDE [sprint-251-update](../includes/ghazdo/sprint-251-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2025/ghazdo/sprint-252-update.md b/release-notes/2025/ghazdo/sprint-252-update.md new file mode 100644 index 00000000000..a480935092f --- /dev/null +++ b/release-notes/2025/ghazdo/sprint-252-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 252 Update +description: See the Sprint 252 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 252 Update + +## Features + +[!INCLUDE [sprint-252-update-links](../includes/ghazdo/sprint-252-update-links.md)] + +[!INCLUDE [sprint-252-update](../includes/ghazdo/sprint-252-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2025/ghazdo/sprint-253-update.md b/release-notes/2025/ghazdo/sprint-253-update.md new file mode 100644 index 00000000000..31e2358efa3 --- /dev/null +++ b/release-notes/2025/ghazdo/sprint-253-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - GitHub Advanced Security for Azure DevOps 253 Update +description: See the Sprint 253 feature updates for GitHub Advanced Security for Azure DevOps, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 3/20/2025 +--- + +# GitHub Advanced Security for Azure DevOps - Sprint 253 Update + +## Features + +[!INCLUDE [sprint-253-update-links](../includes/ghazdo/sprint-253-update-links.md)] + +[!INCLUDE [sprint-253-update](../includes/ghazdo/sprint-253-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2025/includes/boards/sprint-248-update-links.md b/release-notes/2025/includes/boards/sprint-248-update-links.md new file mode 100644 index 00000000000..b58f2545288 --- /dev/null +++ b/release-notes/2025/includes/boards/sprint-248-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +ms.topic: include +--- + +- [Azure Boards Integration with GitHub Enterprise Cloud with Data Residency](#azure-boards-integration-with-github-enterprise-cloud-with-data-residency-preview) diff --git a/release-notes/2025/includes/boards/sprint-248-update.md b/release-notes/2025/includes/boards/sprint-248-update.md new file mode 100644 index 00000000000..8f7fc9b7c41 --- /dev/null +++ b/release-notes/2025/includes/boards/sprint-248-update.md @@ -0,0 +1,28 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +ms.topic: include +--- + +### Azure Boards Integration with GitHub Enterprise Cloud with Data Residency (Preview) + +> [!NOTE] +> This feature is currently in preview. Please [email us](mailto:dahellem@microsoft.com) if you are interested in trying the Boards integration with GitHub Enterprise Cloud with Data Residency. + +Azure Boards now supports integration with GitHub Enterprise Cloud organizations that have data residency enabled. This update aligns with [GitHub’s September 2024 announcement](https://github.blog/engineering/engineering-principles/github-enterprise-cloud-with-data-residency/) introducing data residency for Enterprise Cloud customers, starting with those in the European Union (EU). + +To connect an Azure Boards project to your GitHub Enterprise Cloud organization with data residency: + + 1. Create a new connection in Azure Boards. + + +> [!div class="mx-imgBorder"] +> [![Screenshot of connect github with boards.](../../media/248-boards-01.png "Screenshot of connect github with boards")](../../media/248-boards-01.png#lightbox) + + +2. Select the **GitHub Enterprise Cloud with data residency** option. + +> [!div class="mx-imgBorder"] +> [![Screenshot of new github connection.](../../media/248-boards-02.png "Screenshot of new github connection")](../../media/248-boards-02.png#lightbox) + diff --git a/release-notes/2025/includes/boards/sprint-252-update-links.md b/release-notes/2025/includes/boards/sprint-252-update-links.md new file mode 100644 index 00000000000..75cd7edeea5 --- /dev/null +++ b/release-notes/2025/includes/boards/sprint-252-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +ms.topic: include +--- + +- [GitHub Integration: Linking the Merge Commit](#github-integration-linking-the-merge-commit) +- [Increase Limit of Connected GitHub Repositories](#increase-limit-of-connected-github-repositories) +- [Update on New Boards Hub Rollout](#update-on-new-boards-hub-rollout) \ No newline at end of file diff --git a/release-notes/2025/includes/boards/sprint-252-update.md b/release-notes/2025/includes/boards/sprint-252-update.md new file mode 100644 index 00000000000..8aa1311b425 --- /dev/null +++ b/release-notes/2025/includes/boards/sprint-252-update.md @@ -0,0 +1,20 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +ms.topic: include +--- + +### GitHub Integration: Linking the Merge Commit + +We now automatically link the merge commit to its corresponding work item when a pull request is completed. + +### Increase limit of connected GitHub repositories + +Over the past several months, we've enhanced both the user experience and scalability of connecting your GitHub repositories to an Azure DevOps project. In this sprint, we're raising the maximum limit from 500 to 1,000 repositories, giving you even greater capacity to manage your projects. + +### Update on New Boards Hub rollout + +By early March, New Boards Hub will become the default experience for all organizations using the Azure DevOps service. This means every user will have at least tried New Boards, and our telemetry shows that about 98% of users are continuing to stay with it. Since we aim to maintain a single version of the product, our next step is to disable the option to revert back to Old Boards. + +For some organizations, this change has already been implemented. For others, we plan to begin rolling it out in March and complete the process for all organizations by the end of May. As always, if you encounter any issues, [please report them via the Developer Community](https://developercommunity.visualstudio.com/AzureDevOps). \ No newline at end of file diff --git a/release-notes/2025/includes/boards/sprint-254-update-links.md b/release-notes/2025/includes/boards/sprint-254-update-links.md new file mode 100644 index 00000000000..b5ea53308c0 --- /dev/null +++ b/release-notes/2025/includes/boards/sprint-254-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +ms.topic: include +--- + +- [GitHub Integration: Improvements linking to commits, branches and pull requests](#github-integration-improvements-linking-to-commits-branches-and-pull-requests) +- [GitHub Integration: Show build status for YAML pipelines](#github-integration-show-build-status-for-yaml-pipelines) +- [Delivery Plans limit increased ](#delivery-plans-limit-increased ) diff --git a/release-notes/2025/includes/boards/sprint-254-update.md b/release-notes/2025/includes/boards/sprint-254-update.md new file mode 100644 index 00000000000..1762c523f66 --- /dev/null +++ b/release-notes/2025/includes/boards/sprint-254-update.md @@ -0,0 +1,40 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +ms.topic: include +--- + +### GitHub Integration: Improvements linking to commits, branches and pull requests + +We're continuously improving the Boards + GitHub integration to close usability gaps and align with the experience you're familiar with in Azure Repos. + +With this update, we've introduced several improvements to streamline how branches, pull requests, and commits are linked to work items: + +* When a GitHub branch is linked to a work item, any associated pull requests will now be automatically linked. No need to manually use AB#. + +* Once a pull request is merged, the merge commit will be automatically linked to the work item. + +* If the branch is deleted after the pull request is merged, the branch link will be automatically removed from the work item. + +These improvements make it easier to track your development progress and maintain clean, up-to-date work item associations. + + +> [!div class="mx-imgBorder"] +> ![Gif to github boards integration improvements.](../../media/254-boards-01b.gif "gif to github boards integration improvements") + +### GitHub Integration: Show build status for YAML pipelines + +We're committed to achieving feature parity between YAML and Classic Pipelines. One key missing feature was the ability to provide an "Integrated in build" link when your repository is hosted in GitHub. With our latest release, we've addressed this gap by adding an option in YAML pipeline settings for you to check: + +> [!div class="mx-imgBorder"] +> [![Screenshot of automatically link work items.](../../media/254-boards-01.png "Screenshot of automatically link work items")](../../media/254-boards-01.png#lightbox) + +Once the build is complete, the corresponding link will automatically appear on the associated work items, improving the overall traceability story. + +> [!div class="mx-imgBorder"] +> [![Screenshot of integrated in build.](../../media/254-boards-02.png "Screenshot of integrated in build")](../../media/254-boards-02.png#lightbox) + +### Delivery Plans limit increased + +Previously, we limited the Delivery Plans per project to 1,000. With this update, we have increased the maximum Delivery Plans per project to 1,500. You can learn more about adding and editing Delivery Plans in the documentation [here](https://learn.microsoft.com/azure/devops/boards/plans/add-edit-delivery-plan?view=azure-devops). diff --git a/release-notes/2025/includes/general/sprint-251-update-links.md b/release-notes/2025/includes/general/sprint-251-update-links.md new file mode 100644 index 00000000000..2e14ac2d6f4 --- /dev/null +++ b/release-notes/2025/includes/general/sprint-251-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 2/12/2025 +ms.topic: include +--- + +- [Removal of Generate Git Credentials Button in Repos and Wiki](#removal-of-generate-git-credentials-button-in-repos-and-wiki) +- [Update to Azure DevOps Allowed IP addresses](#update-to-azure-devops-allowed-ip-addresses) \ No newline at end of file diff --git a/release-notes/2025/includes/general/sprint-251-update.md b/release-notes/2025/includes/general/sprint-251-update.md new file mode 100644 index 00000000000..a234a7201ce --- /dev/null +++ b/release-notes/2025/includes/general/sprint-251-update.md @@ -0,0 +1,39 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 2/12/2025 +ms.topic: include +--- + +### Removal of Generate Git Credentials button in Repos and Wiki + +The **Generate Git Credentials** button has been removed from the **Clone Repository** dialogs in the Repos and Wiki UI to support the transition to Microsoft Entra tokens for authentication in Git operations. Previously, selecting this button generated a new Personal Access Token (PAT) with the `vso.code` scope, active for seven days. Each use created a new PAT, often resulting in unnecessary credentials. + +> [!div class="mx-imgBorder"] +> [![Screenshot of deactivated generate git credentials button.](../../media/251-general-01.png "Screenshot of deactivated generate git credentials button")](../../media/251-general-01.png#lightbox) + + +To enhance security and streamline authentication, consider using Entra tokens for ad-hoc Git clone operations in Repos and Wiki. Documentation is available to help you configure authentication via the [command line](/azure/devops/repos/git/auth-overview?view=azure-devops&tabs=Windows) or within the [Git Credential Manager](/azure/devops/repos/git/set-up-credential-managers?view=azure-devops) (GCM). + +While PATs remain available for Git operations, they must now be manually created with the appropriate `vso.code` scope from the Personal Access Token page. Ensure that PATs are only active as long as needed and revoked when no longer in use. As a best practice, store PATs securely in a secret management service such as Azure Key Vault (AKV) and rotate them regularly. + +### Update to Azure DevOps Allowed IP addresses + + +We’re thrilled to announce ongoing improvements to our networking infrastructure to enhance performance and reliability. As part of this effort, new IP addresses are being introduced. To ensure uninterrupted access, please add the new IP addresses to your firewall allow list as soon as possible. + +**IP V4 Ranges:** +* 150.171.22.0/24 +* 150.171.23.0/24 +* 150.171.73.0/24 +* 150.171.74.0/24 +* 150.171.75.0/24 +* 150.171.76.0/24 + +**IP V6 Ranges:** +* 2620:1ec:50::/48 +* 2620:1ec:51::/48 +* 2603:1061:10::/48 + +For more details, visit our blog: [Update to Azure DevOps Allowed IP addresses](https://devblogs.microsoft.com/devops/update-to-ado-allowed-ip-addresses/). diff --git a/release-notes/2025/includes/general/sprint-252-update-links.md b/release-notes/2025/includes/general/sprint-252-update-links.md new file mode 100644 index 00000000000..8c0411e872f --- /dev/null +++ b/release-notes/2025/includes/general/sprint-252-update-links.md @@ -0,0 +1,11 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 2/24/2025 +ms.topic: include +--- + +- [Microsoft Entra profile information (preview)](#microsoft-entra-profile-information-preview) +- [Basic access included with GitHub Enterprise](#basic-access-included-with-github-enterprise) +- [Azure DevOps Allowed IP addresses](#azure-devops-allowed-ip-addresses) \ No newline at end of file diff --git a/release-notes/2025/includes/general/sprint-252-update.md b/release-notes/2025/includes/general/sprint-252-update.md new file mode 100644 index 00000000000..fd108f86067 --- /dev/null +++ b/release-notes/2025/includes/general/sprint-252-update.md @@ -0,0 +1,89 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 2/24/2025 +ms.topic: include +--- + +### Microsoft Entra profile information (preview) + +Last fall, we introduced [Microsoft Entra profile information](/azure/devops/organizations/settings/set-your-preferences?view=azure-devops&tabs=preview-page&preserve-view=true) integration in Azure DevOps, so you no longer need to update your profile separately. Over the next few weeks, this will become the default experience. + +> [!div class="mx-imgBorder"] +> [![Screenshot of Entra profile information toggle.](../../media/252-general-01c.png "Screenshot of Entra profile information toggle")](../../media/252-general-01c.png#lightbox) + +The preview will run for a month or two, and after that this will be the way profile information works for Entra users in Azure DevOps. If you need to opt out during the preview, please share feedback so we can address any issues during the preview. + +> [!div class="mx-imgBorder"] +> [![Screenshot of feedback box.](../../media/252-general-02.png "Screenshot of feedback box")](../../media/252-general-01.png#lightbox) + +### Basic access included with GitHub Enterprise + +Starting this week, we're including Azure DevOps Basic usage rights with GitHub Enterprise licenses and automating the experience for Azure DevOps users. + +If you're using GitHub Enterprise Cloud with Microsoft Entra, you'll be automatically recognized in Azure DevOps. Your access level will be set to 'GitHub Enterprise,' and you won't accrue additional charges in Azure DevOps [Learn more about access for GitHub Enterprise users](/azure/devops/organizations/accounts/faq-user-and-permissions-management#github-enterprise). + +Initially this capability is limited to GitHub Enterprise Cloud users, but we’ll be adding GitHub Enterprise Cloud with Data Residency users soon. + +### Azure DevOps Allowed IP addresses + +We're thrilled to announce significant upgrades to our networking infrastructure, aimed at enhancing the performance and reliability of our service. Add the new IP addresses below, to your firewall allowlist as soon as possible to ensure continuous service during our infrastructure upgrade. + +**IP V4 Ranges:** +* 150.171.22.0/24 +* 150.171.23.0/24 +* 150.171.73.0/24 +* 150.171.74.0/24 +* 150.171.75.0/24 +* 150.171.76.0/24 + +**IP V6 Ranges:** +* 2620:1ec:50::/48 +* 2620:1ec:51::/48 +* 2603:1061:10::/48 + +**ExpressRoute IP V4 Ranges:** +* 150.171.73.14/32 +* 150.171.73.15/32 +* 150.171.73.16/32 +* 150.171.74.14/32 +* 150.171.74.15/32 +* 150.171.74.16/32 +* 150.171.75.14/32 +* 150.171.75.15/32 +* 150.171.75.16/32 +* 150.171.76.14/32 +* 150.171.76.15/32 +* 150.171.76.16/32 +* 150.171.22.17/32 +* 150.171.22.18/32 +* 150.171.22.19/32 +* 150.171.23.17/32 +* 150.171.23.18/32 +* 150.171.23.19/32 + +**ExpressRoute IP V6 Ranges:** +* 2603:1061:10::14/128 +* 2603:1061:10::15/128 +* 2603:1061:10::16/128 +* 2603:1061:10:1::14/128 +* 2603:1061:10:1::15/128 +* 2603:1061:10:1::16/128 +* 2603:1061:10:2::14/128 +* 2603:1061:10:2::15/128 +* 2603:1061:10:2::16/128 +* 2603:1061:10:3::14/128 +* 2603:1061:10:3::15/128 +* 2603:1061:10:3::16/128 +* 2620:1ec:50::17/128 +* 2620:1ec:50::18/128 +* 2620:1ec:50::19/128 +* 2620:1ec:51::17/128 +* 2620:1ec:51::18/128 +* 2620:1ec:51::19/128 + +Be advised that these new ExpressRoute IP ranges will be added to ExpressRoute’s 'Azure Global Services' BGP community in March. +For more details please visit our blog, [Update to Azure DevOps Allowed IP addresses](https://devblogs.microsoft.com/devops/update-to-ado-allowed-ip-addresses/). + + \ No newline at end of file diff --git a/release-notes/2025/includes/general/sprint-253-update-links.md b/release-notes/2025/includes/general/sprint-253-update-links.md new file mode 100644 index 00000000000..7ae04aaa589 --- /dev/null +++ b/release-notes/2025/includes/general/sprint-253-update-links.md @@ -0,0 +1,11 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 3/20/2025 +ms.topic: include +--- + +- [Overlapping secrets for Azure DevOps OAuth](#overlapping-secrets-for-azure-devops-oauth) +- [Deprecation of Languages statistics tags from the Project Summary Page](#deprecation-of-languages-statistics-tags-from-the-project-summary-page) +- [Delivery Plans permission added](#delivery-plans-permission-added) diff --git a/release-notes/2025/includes/general/sprint-253-update.md b/release-notes/2025/includes/general/sprint-253-update.md new file mode 100644 index 00000000000..6e8b847ee24 --- /dev/null +++ b/release-notes/2025/includes/general/sprint-253-update.md @@ -0,0 +1,30 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 3/20/2025 +ms.topic: include +--- + +### Overlapping secrets for Azure DevOps OAuth + +We're excited to introduce the new overlapping secrets feature in Azure DevOps OAuth, designed to enhance security, and streamline secret rotations. This feature lets you add a new secret to your OAuth client while the previous one remains active, ensuring continuous operation of your applications. You can manage these secrets programmatically via API or through the Visual Studio App page UI. + +As part of ongoing security improvements, Azure DevOps OAuth is scheduled for deprecation in 2026. We encourage you to migrate to [Microsoft Entra ID OAuth](/azure/devops/integrate/get-started/authentication/entra-oauth?view=azure-devops&preserve-view=true) for improved security features and longer-term investment. In the interim, we recommend regularly rotating your secrets using our new overlapping secrets feature. + +### Deprecation of Languages statistics tags from the Project Summary page + +In the coming weeks, we'll be deprecating the Languages statistics tags from the Project Summary page. Removing these tags will help optimize performance, resulting in faster load times and a more responsive interface. + +The update will occur automatically, with no action required on your part. + +> [!div class="mx-imgBorder"] +> [![Screenshot of tags being removed.](../../media/253-general-01.png "Screenshot of tags being removed")](../../media/253-general-01.png#lightbox) + +### Delivery Plans permission added + +As part of our ongoing security enhancements, we’ve introduced a new **Manage Delivery Plans** project-level permission. This change was implemented to prevent unintentional read/write access for users in the Readers group. + +> [!div class="mx-imgBorder"] +> [![Screenshot of manage delivery plans.](../../media/253-general-02.png "Screenshot of manage delivery plans")](../../media/253-general-02.png#lightbox) + diff --git a/release-notes/2025/includes/general/sprint-254-update-links.md b/release-notes/2025/includes/general/sprint-254-update-links.md new file mode 100644 index 00000000000..7e9b430698d --- /dev/null +++ b/release-notes/2025/includes/general/sprint-254-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 4/3/2025 +ms.topic: include +--- + +- [No new Azure DevOps OAuth apps beginning April 2025](#no-new-azure-devops-oauth-apps-beginning-april-2025) +- [Server Name Indication (SNI) now mandatory for Azure DevOps Services](#server-name-indication-sni-now-mandatory-for-azure-devops-services) \ No newline at end of file diff --git a/release-notes/2025/includes/general/sprint-254-update.md b/release-notes/2025/includes/general/sprint-254-update.md new file mode 100644 index 00000000000..3368de6edaf --- /dev/null +++ b/release-notes/2025/includes/general/sprint-254-update.md @@ -0,0 +1,39 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.service: azure-devops +ms.date: 4/3/2025 +ms.topic: include +--- + +### No new Azure DevOps OAuth apps beginning April 2025 + +Starting in April 2025, we're no longer supporting new registrations of Azure DevOps OAuth apps. This is a first step towards our longer-term vision of retiring the Azure DevOps OAuth platform. We reccomend that all developers building applications on top of Azure DevOps REST APIs explore the [Microsoft identity platform](https://learn.microsoft.com/entra/identity-platform/v2-overview) and registering a [new Entra application](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app?tabs=certificate%2Cexpose-a-web-api) instead. + +All existing Azure DevOps OAuth apps will continue working until the platform’s official retirement in 2026. Learn more in [our blog post here](https://devblogs.microsoft.com/devops/no-new-azure-devops-oauth-apps-beginning-february-2025/). + +### Server Name Indication (SNI) now mandatory for Azure DevOps Services + +Beginning April 23, 2025, we'll require Server Name Indication (SNI) on all incoming HTTPS connections to Azure DevOps Services. + +SNI is an extension to the TLS protocol that allows clients to specify the hostname they're connecting to. All modern browsers and client software support SNI and use it by default, ensuring a seamless transition for most users. In fact, more than 99.995% of the customer traffic reaching our servers is SNI-ready. + +However, some client software may be incompatible with SNI due to various factors, such as being outdated, misconfigured networking libraries, runtimes, or operating systems. Issues may also arise from proxies or NGFW firewalls. The following tools used with Azure DevOps may be impacted by SNI issues: + +* Git clients +* IDE plugins and extensions (Team Explorer Everywhere) +* Software running on older Java versions which don't support SNI (Java 6 and earlier) or don't have SNI enabled by default (some versions of Java 7 and 8) +* Old browser versions (see https://caniuse.com/sni) + +SNI issues usually manifest by connection errors, such as: + +* ERR_SSL_PROTOCOL_ERROR , ERR_CERT_COMMON_NAME_INVALID +* javax.net.ssl.SSLHandshakeException, javax.net.ssl.SSLException +* Couldn't establish trust relationship for the SSL/TLS secure channel + +You can validate the SNI-compatibility of your system by calling the status endpoint of Azure DevOps, which we have configured to require SNI. If this call is successful, it indicates that the host, including its operating system and networking environment, is SNI-compatible. For detailed instructions on how to test, visit our [blog post](https://devblogs.microsoft.com/devops/sni-mandatory-for-azdo-services/). + + + + + diff --git a/release-notes/2025/includes/ghazdo/sprint-248-update-links.md b/release-notes/2025/includes/ghazdo/sprint-248-update-links.md new file mode 100644 index 00000000000..ddc5fb3cad5 --- /dev/null +++ b/release-notes/2025/includes/ghazdo/sprint-248-update-links.md @@ -0,0 +1,11 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/6/2025 +ms.topic: include +--- + +- [Tool specific security overview coverage](#tool-specific-security-overview-coverage) + + + diff --git a/release-notes/2025/includes/ghazdo/sprint-248-update.md b/release-notes/2025/includes/ghazdo/sprint-248-update.md new file mode 100644 index 00000000000..eefeef640cf --- /dev/null +++ b/release-notes/2025/includes/ghazdo/sprint-248-update.md @@ -0,0 +1,16 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +ms.topic: include +--- +### Tool specific security overview coverage + +The security overview in GitHub Advanced Security for Azure DevOps now provides a detailed breakdown of enablement status for each scan tool, including **dependency scanning**, **code scanning**, and **secret scanning**. This enhancement allows you to view fine-grained enablement statuses across all repositories in your organization. + +> [!div class="mx-imgBorder"] +> [![Screenshot of security overview.](../../media/248-ghazdo-01.png "Screenshot of security overview")](../../media/248-ghazdo-01.png#lightbox) + +For more information, see [Security overview for Advanced Security](/azure/devops/repos/security/github-advanced-security-security-overview?view=azure-devops#viewing-security-insights). + + diff --git a/release-notes/2025/includes/ghazdo/sprint-251-update-links.md b/release-notes/2025/includes/ghazdo/sprint-251-update-links.md new file mode 100644 index 00000000000..da53613d60c --- /dev/null +++ b/release-notes/2025/includes/ghazdo/sprint-251-update-links.md @@ -0,0 +1,12 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/12/2025 +ms.topic: include +--- + +- [GitHub Advanced Security updates for default branch changes](#github-advanced-security-updates-for-default-branch-changes ) +- [CodeQL installation for self-hosted agents supports proxy configurations](#codeql-installation-for-self-hosted-agents-supports-proxy-configurations) +- [Alerts branch picker now displays all branches with a successful scan ](#alerts-branch-picker-now-displays-all-branches-with-a-successful-scan) +- [Enhanced pull request annotations in GitHub Advanced Security](#enhanced-pull-request-annotations-in-github-advanced-security) +- [Improvements for Get alerts API ](#improvements-for-get-alerts-api) diff --git a/release-notes/2025/includes/ghazdo/sprint-251-update.md b/release-notes/2025/includes/ghazdo/sprint-251-update.md new file mode 100644 index 00000000000..cee361d300f --- /dev/null +++ b/release-notes/2025/includes/ghazdo/sprint-251-update.md @@ -0,0 +1,45 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/12/2025 +ms.topic: include +--- +### GitHub Advanced Security updates for default branch changes + +Within GitHub Advanced Security, navigating to the advanced security tab shows the alert state for your default branch first, while the Security Overview view pulls alert information for your default branch only. + +Now, Advanced Security detects changes to your default branch and updates both the Security Overview and repository-level alert view shortly after the default branch assignment is changed. + + +### CodeQL installation for self-hosted agents supports proxy configurations + +If you have a network proxy configured and used the `enableAutomaticCodeQLInstall` variable in the `AdvancedSecurity-CodeQL-Init` task, the task may have previously encountered the error message `[warning] Maximum number of redirects exceeded` when downloading the CodeQL tool cache to your self-hosted agent. With this update, we introduce handling for network proxies so that automatic installation runs successfully. + +### Alerts branch picker now displays all branches with a successful scan + +The branch picker in GitHub Advanced Security has been updated to display all branches with a successful scan, even if no vulnerabilities are detected. Previously, only branches with alerts were shown, making it difficult to confirm whether a scan completed successfully. + +Both the repository-level alerts UX and the [Analysis - List API](/rest/api/azure/devops/advancedsecurity/analysis/list?view=azure-devops-rest-7.2&preserve-view=true) now return branches with a successful SARIF submission for dependency and code scanning, improving scan visibility. + +### Enhanced pull request annotations in GitHub Advanced Security + +With this release, we've improved the pull request annotation experience in GitHub Advanced Security through: + +* **Increased dependency scanning annotations:** Advanced Security displays pull request annotations even when Advanced Security can't determine physical file location. + +* **Auto-closure:** pull request comments will be automatically resolved if the associated alert is dismissed. +We've also introduced performance improvements and batch handling for pull request events for a smoother experience. + +### Improvements for Get Alerts API + +With this update we introduce new improvements for the Advanced Security Get alerts API: + +* Minimal API expand option: fetch a minimal version of the Alerts API using the parameter `expand=minimal` in your payload. E.g.: `https://advsec.dev.azure.com/{organization}/{project}/_apis/Alert/repositories/{repository}/Alerts?expand=minimal`. + +> [!div class="mx-imgBorder"] +> [![Screenshot of security overview.](../../media/251-ghazdo-01.png "Screenshot of security overview")](../../media/251-ghazdo-01.png#lightbox) + + +* New metadata for alerts: the Alerts API now returns specific `AdditionalProperties` such as CVE ID or advisory ID for dependency alerts and tags for code scanning alerts. + +* Batched Alert API calls: use `criteria.alertIds={alertId1},{alertId2}` with the Alerts API to receive details for a comma separated list of alert IDs. E.g.: `https://advsec.dev.azure.com/{organization}/{project}/_apis/Alert/repositories/{repository}/Alerts?criteria.alertIds=100,200,130`. diff --git a/release-notes/2025/includes/ghazdo/sprint-252-update-links.md b/release-notes/2025/includes/ghazdo/sprint-252-update-links.md new file mode 100644 index 00000000000..73d1a03e95b --- /dev/null +++ b/release-notes/2025/includes/ghazdo/sprint-252-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +ms.topic: include +--- + +- [One click enablement for dependency scanning preview](#one-click-enablement-for-dependency-scanning-preview) +- [Deleted branches removed from Advanced Security branch picker](#deleted-branches-removed-from-advanced-security-branch-picker) diff --git a/release-notes/2025/includes/ghazdo/sprint-252-update.md b/release-notes/2025/includes/ghazdo/sprint-252-update.md new file mode 100644 index 00000000000..d6240b110db --- /dev/null +++ b/release-notes/2025/includes/ghazdo/sprint-252-update.md @@ -0,0 +1,26 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +ms.topic: include +--- + +### One click enablement for dependency scanning preview + +From your repository settings, you can now enable the Advanced Security dependency scanning task without needing to edit your pipeline definition. + +By opting in to "Scan default branch for vulnerable dependencies," the dependency task will automatically run in any pipeline targeting your default branch or pull requests targeting your default branch if the task is not already present in your pipeline. If the task is already present in your pipeline, the task will not run again. + +To participate in the preview, send us an [email](mailto:ghazdopreview@microsoft.com)! + +> [!div class="mx-imgBorder"] +> [![Screenshot of security overview.](../../media/252-ghazdo-01.png "Screenshot of repository settings")](../../media/252-ghazdo-01.png#lightbox) + +### Deleted branches removed from Advanced Security branch picker + +Within GitHub Advanced Security, the repository-level branch picker showed all branches for your repository once they had any security alerts discovered on those branches, even if the branch was later deleted. + +Now, any branches that are deleted will be appropriately removed from the Advanced Security branch picker and any associated alerts will no longer be retrievable. + + + diff --git a/release-notes/2025/includes/ghazdo/sprint-253-update-links.md b/release-notes/2025/includes/ghazdo/sprint-253-update-links.md new file mode 100644 index 00000000000..bac8cd55c38 --- /dev/null +++ b/release-notes/2025/includes/ghazdo/sprint-253-update-links.md @@ -0,0 +1,13 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 3/20/2025 +ms.topic: include +--- + +- [Security overview risk page enhanced with new columns and filtering options](#security-overview-risk-page-enhanced-with-new-columns-and-filtering-options) +- [Multi-repository publishing scenarios supported for GitHub Advanced Security for Azure DevOps](#multi-repository-publishing-scenarios-supported-for-github-advanced-security-for-azure-devops) +- [Service hooks for GitHub Advanced Security for Azure DevOps alerts (preview)](#service-hooks-for-github-advanced-security-for-azure-devops-alerts-preview) +- [pnpm v9 support comes to GitHub Advanced Security for Azure DevOps dependency scanning](#pnpm-v9-support-comes-to-github-advanced-security-for-azure-devops-dependency-scanning) + + diff --git a/release-notes/2025/includes/ghazdo/sprint-253-update.md b/release-notes/2025/includes/ghazdo/sprint-253-update.md new file mode 100644 index 00000000000..f3ad9935a0b --- /dev/null +++ b/release-notes/2025/includes/ghazdo/sprint-253-update.md @@ -0,0 +1,90 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 3/20/2025 +ms.topic: include +--- + +### Security overview risk page enhanced with new columns and filtering options + +Under the **Risk** tab, you'll find newly added columns displaying new, fixed, and dismissed security alerts across your organization. We’ve added filtering options to refine results by project, tool (secrets, dependencies, or code scanning results), and a time-based filter to define search boundaries. + +Additionally, applying a filter adds a URL query parameter, enabling you to share the pre-filtered view with others in your organization. + +> [!div class="mx-imgBorder"] +> [![Screenshot of Security overview risk page.](../../media/253-ghazdo-01.png "Screenshot of Security overview risk page")](../../media/253-ghazdo-01.png#lightbox) + + +### Multi-repository publishing scenarios supported for GitHub Advanced Security for Azure DevOps + +Previously, when a pipeline definition was housed in one repository and the source code to be scanned by GitHub Advanced Security was in another, results were processed and submitted to the wrong repository. Instead of publishing alerts to the repository with the source code, they appeared in the repository where the pipeline was defined. + +Now, both dependency scanning and code scanning correctly route alerts to the repository containing the scanned source code in multi-repository scenarios. + +To enable this feature, set the pipeline environment variable `advancedsecurity.publish.repository.infer: true` to infer the repository to publish from the repository in the working directory. + +Alternatively, if you don't explicitly check out a repository or use an alias to check out your repository, utilize the variable `advancedsecurity.publish.repository: $[ convertToJson(resources.repositories['YourRepositoryAlias']) ]` instead. + +YAML code snippet: + + +```yaml + trigger: + - main + +resources: + repositories: + - repository: BicepGoat + type: git + name: BicepGoat + ref: refs/heads/main + trigger: + - main + +jobs: + # Explicit - `advancedsecurity.publish.repository` explicitly defines the repository to submit SARIF to. + - job: "AdvancedSecurityCodeScanningExplicit" + displayName: "🛡 Infrastructure-as-Code Scanning (Explicit)" + variables: + advancedsecurity.publish.repository: $[ convertToJson(resources.repositories['BicepGoat']) ] + steps: + - checkout: BicepGoat + - task: TemplateAnalyzerSarif@1 + displayName: Scan with Template Analyzer + - task: AdvancedSecurity-Publish@1 + displayName: Publish to IaC Scanning Results to Advanced Security + + + # Infer - `advancedsecurity.publish.repository.infer` specifies that the `AdvancedSecurity-Publish` must + # infer repository to submit SARIF to from the working directory on the build agent. + - job: "AdvancedSecurityCodeScanningInfer" + displayName: "🛡 Infrastructure-as-Code Scanning (Infer)" + variables: + advancedsecurity.publish.repository.infer: true + steps: + - checkout: BicepGoat + - task: TemplateAnalyzerSarif@1 + displayName: Scan with Template Analyzer + - task: AdvancedSecurity-Publish@1 + displayName: Publish to IaC Scanning Results to Advanced Security +``` + +### Service hooks for GitHub Advanced Security for Azure DevOps alerts (preview) + +You can now configure service hooks for GitHub Advanced Security alert events, including: + +* New alert created +* Alert data changed +* Alert state changed + +Just like other repository events, you can filter by repository and branch. For alerts specifically, you can filter by alert type (dependencies, code scanning, or secrets) and alert severity. + +> [!div class="mx-imgBorder"] +> [![Screenshot of filter by alert type .](../../media/253-ghazdo-02.png "Screenshot of S filter by alert type ")](../../media/253-ghazdo-02.png#lightbox) + +To participate in the preview, fill out the [preview interest form](https://aka.ms/ghazdo-service-hooks-preview) or send us an [email](mailto:ghazdopreview@microsoft.com)! + +### pnpm v9 support comes to GitHub Advanced Security for Azure DevOps dependency scanning + +With pnpm v8 reaching end-of-life at the end of April, the next dependency scanning update will include support for pnpm v9. This update is in response to your [Developer Community](https://developercommunity.visualstudio.com/t/AdvancedSecurity-Dependency-Scanning1-T/10743452) request for pnpm v9 support. + diff --git a/release-notes/2025/includes/nextsteps.md b/release-notes/2025/includes/nextsteps.md new file mode 100644 index 00000000000..445ee955b94 --- /dev/null +++ b/release-notes/2025/includes/nextsteps.md @@ -0,0 +1,18 @@ +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). \ No newline at end of file diff --git a/release-notes/2025/includes/pipelines/sprint-248-update-links.md b/release-notes/2025/includes/pipelines/sprint-248-update-links.md new file mode 100644 index 00000000000..46be30f48ca --- /dev/null +++ b/release-notes/2025/includes/pipelines/sprint-248-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +ms.topic: include +--- + +- [New pipeline expression function](#new-pipeline-expression-functions) +- [Enhancements to ManualValidation task](#enhancements-to-manualvalidation-task) \ No newline at end of file diff --git a/release-notes/2025/includes/pipelines/sprint-248-update.md b/release-notes/2025/includes/pipelines/sprint-248-update.md new file mode 100644 index 00000000000..abe95ba30e7 --- /dev/null +++ b/release-notes/2025/includes/pipelines/sprint-248-update.md @@ -0,0 +1,75 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +ms.topic: include +--- + +### New pipeline expression functions + +Pipeline expression functions allow you to write powerful YAML pipelines. In this sprint, we've introduced two new functions: + +* `iif(condition, value_when_true, value_when_false)` that returns `value_when_true` when `condition` evaluates to `true` or `value_when_false`, otherwise + +* `trim(string)` that returns a new string in which whitespaces at the beginning and end of the string are removed + +For example, you can use the `iif` function to dynamically select a pool for running your pipeline. If you want to build pull requests using the Azure Pipelines pool, but all other runs should use a Managed DevOps pool, you can write the following pipeline. +```yaml +variables: + poolToUse: ${{ iif(eq(variables['Build.Reason'], 'PullRequest'), 'Azure Pipelines', 'ManagedDevOpsPool')}} + +stages: +- stage: build + pool: ${{variables.poolToUse}} + jobs: + - job: + steps: + - task: DotNetCoreCLI@2 + inputs: + command: 'build' +``` + +You can use the `trim` function to make your YAML more resilient to user input. For example, in the following pipeline, we use the `trim` function to ensure the stage name doesn't start with white spaces. +```yaml +parameters: +- name: regions + type: string + default: ' wus1, wus2, wus3,wus4' + +stages: +- ${{ each region in split(parameters.regions, ',')}}: + - stage: stage_${{trim(region)}} + displayName: Deploy to ${{trim(region)}} + jobs: + - job: deploy + steps: + - script: ./deploy.sh ${{trim(region)}} +``` + +### Enhancements to ManualValidation task + +The [ManualValidation](/azure/devops/pipelines/tasks/reference/manual-validation-v1) task enables you to pause a pipeline run and wait for manual intervention. One scenario for using this task is manual testing. + +To increase security of your pipeline, you may wish to restrict who can complete the task and resume the pipeline run. To this end, we're introducing a new version of the task that provides two additional parameters: + +* `approvers`: restrict who can complete the task to a predefined set of users / security groups / teams + +* `allowApproversToApproveTheirOwnRuns`: restrict the user who queued the pipeline run from resuming it + +For example, the following YAML snippet restricts the set of people who can resume the pipeline run to members of the Release Approvers group, but not by the user who triggered the pipeline run. + +```yaml +- task: ManualValidation@1 + inputs: + notifyUsers: 'Release Approvers' + approvers: 'Release Approvers' + allowApproversToApproveTheirOwnRuns: false +``` + +In the `approvers` property, you can use the following values (comma separated) : +* Email address, +* Permission-Group, +* Project-Team, +* [ProjectName]\\[Permission Group], +* [Org]\\[Permission Group], +* [ProjectName]\\[Project Team] diff --git a/release-notes/2025/includes/pipelines/sprint-251-update-links.md b/release-notes/2025/includes/pipelines/sprint-251-update-links.md new file mode 100644 index 00000000000..5a595d504c8 --- /dev/null +++ b/release-notes/2025/includes/pipelines/sprint-251-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/12/2025 +ms.topic: include +--- + +- [Azure Classic Service Connections are being retired](#azure-classic-service-connections-are-being-retired) +- [Managed DevOps Pools is generally available](#managed-devops-pools-is-generally-available) +- [New tasks to implement secret-less access to Azure storage accounts](#new-tasks-to-implement-secret-less-access-to-azure-storage-accounts) \ No newline at end of file diff --git a/release-notes/2025/includes/pipelines/sprint-251-update.md b/release-notes/2025/includes/pipelines/sprint-251-update.md new file mode 100644 index 00000000000..b9be8c30aa9 --- /dev/null +++ b/release-notes/2025/includes/pipelines/sprint-251-update.md @@ -0,0 +1,56 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/12/2025 +ms.topic: include +--- + + +### Azure Classic Service Connections are being retired + +Cloud Services, also known as Azure Service Manager (ASM), was the original deployment model for Azure. Since its replacement by Azure Resource Manager (ARM) in 2014, it has now been [retired](https://azure.microsoft.com/updates?id=cloud-services-retirement-announcement). Consequently, we are discontinuing the ability to create new Azure Classic service connections. However, existing Azure Classic service connections will remain unaffected. + +### Managed DevOps Pools is generally available + +Managed DevOps Pools is an evolution of Azure DevOps Virtual Machine Scale Set agent pools. It provides better pool scalability and reliability, simplifies pool management, and allows you to use the VM images from Microsoft-hosted agents on custom Azure VMs. + +Managed DevOps Pools is now generally available. You can read about Managed DevOps Pools features and the features newly added for GA [here](https://devblogs.microsoft.com/devops/managed-devops-pools-ga/) and [here](https://aka.ms/mdp-docs). + + +### New tasks to implement secret-less access to Azure storage accounts + +The AzureVmssDeployment, JavaToolInstaller, JenkinsDownloadArtifacts tasks can be configured to use Azure Storage: + +```yaml +- task: AzureVmssDeployment@1 + inputs: + (required properties) + azureSubscription: + customScriptsStorageAccount: +- task: JavaToolInstaller@2 + inputs: + (required properties) + jdkSourceOption: 'AzureStorage' + azureResourceManagerEndpoint: + azureStorageAccountName: +- task: JenkinsDownloadArtifacts@2 + inputs: + (required properties) + artifactProvider: 'azureStorage' + ConnectedServiceNameARM: + storageAccountName: +``` + +New task versions have been created that now use Azure RBAC instead of storage account key/sas. The new tasks require the [Storage Blob Data Contributor](/azure/role-based-access-control/built-in-roles/storage#storage-blob-data-contributor) role to be assigned to the identity of the service connection configured. + +You will need to assign the appropriate Azure RBAC role for service connection used in the task to be able to access the Azure Storage Account. See [Assign an Azure role for access to blob data](/azure/storage/blobs/assign-azure-role-data-access?tabs=portal). + +The AzureVmssDeployment@1 task needs additional RBAC roles configured to access the storage account configured in `customScriptsStorageAccount`: + +> [!div class="mx-imgBorder"] +> [![Screenshot of AzureVmssDeployment@1 RBAC.](../../media/251-pipelines-01.png "Screenshot of AzureVmssDeployment@1 RBAC")](../../media/251-ghazdo-01.png#lightbox) + +1. The `azureSubscription` Service Connection: [Contributor](/azure/role-based-access-control/built-in-roles/privileged#contributor) or [Virtual Machine Contributor](/azure/role-based-access-control/built-in-roles/compute#virtual-machine-contributor) role on the Virtual Machine Scale Set +2. The `azureSubscription` Service Connection: [Storage Blob Data Contributor](/azure/role-based-access-control/built-in-roles/storage#storage-blob-data-contributor) role on the storage account that holds the custom script +3. The Virtual Machine Scale Set System-assigned Managed Identity: [Storage Blob Data Reader](/azure/role-based-access-control/built-in-roles/storage#storage-blob-data-reader) role on the storage account that holds the custom script + diff --git a/release-notes/2025/includes/pipelines/sprint-252-update-links.md b/release-notes/2025/includes/pipelines/sprint-252-update-links.md new file mode 100644 index 00000000000..7f015a03a5d --- /dev/null +++ b/release-notes/2025/includes/pipelines/sprint-252-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +ms.topic: include +--- + +- [Pipelines using Ubuntu 24.04 will show warnings for certain tasks](#pipelines-using-ubuntu-2404-will-show-warnings-for-certain-tasks) +- [Informational runs](#informational-runs) diff --git a/release-notes/2025/includes/pipelines/sprint-252-update.md b/release-notes/2025/includes/pipelines/sprint-252-update.md new file mode 100644 index 00000000000..604cf249cb3 --- /dev/null +++ b/release-notes/2025/includes/pipelines/sprint-252-update.md @@ -0,0 +1,38 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/26/2025 +ms.topic: include +--- + + +### Pipelines using Ubuntu 24.04 will show warnings for certain tasks + +The [Ubuntu 24.04](/azure/devops/release-notes/2024/pipelines/sprint-246-update#ubuntu-2404-on-azure-pipelines-hosted-agents) Pipelines image has been in preview since October last year. We plan to update the `ubuntu-latest` image to map to `ubuntu-24.04` in March. + +Some tools are no longer available on the Ubuntu 24.04 image: + +| Task/Tool | Description | +|---------------------------------------|-----------------------------------| +| `MSBuild@1` | Task doesn't work as Mono and MSBuild aren't available for Ubuntu 24. Use native [.NET on Ubuntu](/dotnet/core/install/linux-ubuntu) instead. | +| `NuGetCommand@2` | Task has reduced functionality as Mono and NuGet aren't available for Ubuntu 24, see instructions on [Migrating to .NET CLI on Ubuntu](/azure/devops/pipelines/tasks/reference/nuget-command-v2#support-for-newer-ubuntu-hosted-images). | +| Terraform | Terraform isn't available on the `ubuntu-24.04` image. You can use the [Terraform extension](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.custom-terraform-tasks) and `TerraformInstaller@1` task to make Terraform available in your pipeline. | + +For more information on software differences with the Ubuntu 22.02 image, see [Ubuntu-24.04 image](https://github.com/actions/runner-images/issues/10636). + +In preparation of the mapping of `ubuntu-latest` and `ubuntu-24.04`, pipelines using these image labels will show warnings over the coming weeks. + +> [!div class="mx-imgBorder"] +> [![Screenshot of warnings for Ubuntu-24.04 jobs.](../../media/252-pipelines-02.png "Screenshot of warnings for Ubuntu-24.04 jobs")](../../media/252-pipelines-02.png#lightbox) + + +### Informational runs + +Informational runs tell you Azure Pipelines failed to determine if a pipeline should run or not, because it couldn't process the pipeline's YAML file. Examples of such failures are failures to retrieve the YAML source code or errors in it. + +With this sprint, we're adding support for informational runs for pipelines hosted in Azure Repos. You can see an example below. + +> [!div class="mx-imgBorder"] +> [![Screenshot of informational runs.](../../media/252-pipelines-01.png "Screenshot of informational runs")](../../media/252-pipelines-01.png#lightbox) + +The pipeline run error tells you the YAML file is incorrect, and this prevents Azure Pipelines from evaluating its trigger conditions. \ No newline at end of file diff --git a/release-notes/2025/includes/pipelines/sprint-253-update-links.md b/release-notes/2025/includes/pipelines/sprint-253-update-links.md new file mode 100644 index 00000000000..057cd01ceca --- /dev/null +++ b/release-notes/2025/includes/pipelines/sprint-253-update-links.md @@ -0,0 +1,14 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 3/20/2025 +ms.topic: include +--- + +- [Hosted image updates](#hosted-image-updates) +- [Workload identity federation uses Entra issuer](#workload-identity-federation-uses-entra-issuer) +- [Gradle@4 task](#gradle4-task) +- [stringList parameter type](#stringlist-parameter-type) +- [Identity of user who requested a stage to run](#identity-of-user-who-requested-a-stage-to-run) + + diff --git a/release-notes/2025/includes/pipelines/sprint-253-update.md b/release-notes/2025/includes/pipelines/sprint-253-update.md new file mode 100644 index 00000000000..d29aa21727b --- /dev/null +++ b/release-notes/2025/includes/pipelines/sprint-253-update.md @@ -0,0 +1,160 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 3/20/2025 +ms.topic: include +--- + +### Hosted image updates + +We’re rolling out updates to keep Azure Pipelines’ hosted agents secure and current. These updates include adding support for Ubuntu-24.04, Windows 2025 images, and macOS-15 Sequoia, while deprecating older images like Ubuntu-20.04 and Windows Server 2019. + +For more details, please visit our [blog post](https://devblogs.microsoft.com/devops/upcoming-updates-for-azure-pipelines-agents-images/). + +#### macOS-15 Sequoia is generally available + +The `macOS-15` image will be available on Azure Pipelines hosted agents starting April 1. To use this image, update your YAML file to include `vmImage:'macos-15'`: + +```yaml +- job: macOS15 + pool: + vmImage: 'macOS-15' + steps: + - bash: | + echo Hello from macOS Sequoia + sw_vers +``` + +For macOS-15 installed software, see [image configuration](https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md). + +The `macOS-14` image will still be used when specifying `macOS-latest`. We'll update `macOS-latest` to use `macOS-15` in April. + +#### Windows-2025 image is available in preview + +The `windows-2025` image is now available in preview for Azure Pipelines hosted agents. To use this image, update your YAML file to include `vmImage:'windows-2025'`: + +```yaml +- job: win2025 + pool: + vmImage: 'windows-2025' + steps: + - pwsh: | + Write-Host "(Get-ComputerInfo).WindowsProductName" + Get-ComputerInfo | Select-Object WindowsProductName + Write-Host "`$PSVersionTable.OS" + $PSVersionTable.OS +``` + +For Window Server 2025 installed software, see [image configuration](https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md). + + +#### The ubuntu-latest pipeline image will start using ubuntu-24.04 + +In the coming weeks, pipeline jobs specifying `ubuntu-latest` will start using `ubuntu-24.04` instead of `ubuntu-22.04`. + +For guidance on tasks that use tools that are no longer on the `ubuntu-24.04` image, see our [blog post](https://devblogs.microsoft.com/devops/upcoming-updates-for-azure-pipelines-agents-images/). To keep using Ubuntu 22.04, use the `ubuntu-22.04` image label: + +```yaml +- job: ubuntu2404 + pool: + vmImage: 'ubuntu-24.04' + steps: + - bash: | + echo Hello from Ubuntu 24.04 + lsb_release -d + - pwsh: | + Write-Host "`$PSVersionTable.OS" + $PSVersionTable.OS +``` + + +#### The ubuntu-20.04 pipeline image is deprecated and will be retired April 1 + +We're deprecating support for the Ubuntu 20.04 image in Azure Pipelines because it will reach its end of support soon. Find the deprecation plan with brownout schedule in our [blog post](https://devblogs.microsoft.com/devops/upcoming-updates-for-azure-pipelines-agents-images/#ubuntu). + + +### Workload identity federation uses Entra issuer + +Just over a year ago, we made [Workload identity federation generally available](https://devblogs.microsoft.com/devops/workload-identity-federation-for-azure-deployments-is-now-generally-available/). Workload identity federation allows you to configure a service connection without a secret. The identity (App registration, Managed Identity) underpinning the service connection can only be used for the intended purpose: the service connection configured in the identity's federated credential. + +We're now changing the format of the federated credential for new Azure and Docker service connections. Existing service connections will work as before. + +|   | Azure DevOps issuer | Entra issuer (new service connections) | +|---------|---------------------------------------------------------------------|---------------------------------------------------------------| +| Issuer | `https://vstoken.dev.azure.com/` | `https://login.microsoftonline.com//v2.0` | +| Subject | `sc:////` | `/sc//` | + +There's no change in configuration and the way tokens are obtained stays the same. Pipeline tasks don't need to be updated and work as before. + +The steps to create a service connection aren't changing and in most cases, the new issuer isn't visible. When [configuring an Azure service connection manually](/azure/devops/pipelines/release/configure-workload-identity), you'll see the new federated credentials displayed: + +> [!div class="mx-imgBorder"] +> [![Screenshot of FIC example.](../../media/253-pipelines-01.png "Screenshot of FIC example")](../../media/253-pipelines-01.png#lightbox) + +Copy these values as before when creating a federated credential for an App registration or Managed Identity. + +#### Automation + +When creating a service connection in automation with the [REST API](/rest/api/azure/devops/serviceendpoint/endpoints/create), use the federated credential returned by the API: + +```json +authorization.parameters.workloadIdentityFederationIssuer +authorization.parameters.workloadIdentityFederationSubject +``` + +Likewise, when creating a service connection with the Terraform azuredevops provider, the [azuredevops_serviceendpoint_azurerm](https://registry.terraform.io/providers/microsoft/azuredevops/latest/docs/resources/serviceendpoint_azurerm#attributes-reference) resource returns `workload_identity_federation_issuer` and `workload_identity_federation_subject` attributes. + +#### More information + +- [Connect to Azure with an Azure Resource Manager service connection](/azure/devops/pipelines/library/connect-to-azure) +- [Troubleshoot an Azure Resource Manager workload identity service connection](/azure/devops/pipelines/release/troubleshoot-workload-identity) + +### Gradle@4 task + +A new [Gradle@4](/azure/devops/pipelines/tasks/reference/gradle-v4) task has been created with support for [Gradle 8.0](https://docs.gradle.org/8.0/userguide/upgrading_version_7.html). The built-in code coverage option is removed from the `Gradle` task starting with `Gradle@4`. To use code coverage with Gradle in your pipeline: + +- Specify code coverage plugins in your build.gradle file. For more information, see [Gradle code analysis options](https://docs.gradle.org/current/userguide/plugin_reference.html#code_analysis). +- Use the [PublishCodeCoverageResults@2](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v2) task in your pipeline after the `Gradle@4` task. + +Configuration of the SonarQube analysis was moved to the [SonarQube](https://marketplace.visualstudio.com/items?itemName=SonarSource.sonarqube) or [SonarCloud](https://marketplace.visualstudio.com/items?itemName=SonarSource.sonarcloud) extensions in the task `Prepare Analysis Configuration`. + + +### stringList parameter type + +One of the top requested YAML pipelines features is to [define parameters that contain a list of items](https://developercommunity.visualstudio.com/t/parameters-that-support-multiselect/1224839). + +With this sprint, we've added a new parameter type, named `stringList`, that provides this capability. + +Say you want to allow those who queue pipeline runs to choose which regions they want to deploy a payload to. Now you can do this as shown in the example below. + +```yaml +parameters: +- name: regions + type: stringList + displayName: Regions + values: + - WUS + - CUS + - EUS + +stages: +- ${{ each stage in parameters.regions}}: + - stage: ${{stage}} + displayName: Deploy to ${{stage}} + jobs: + - job: + steps: + - script: ./deploy ${{stage}} +``` + +When queuing this pipeline, you'll now have the option of choosing multiple regions to deploy to, as shown in the following screenshot: + +> [!div class="mx-imgBorder"] +> [![Screenshot of choosing multiple regions.](../../media/253-pipelines-02.png "Screenshot of choosing multiple regions")](../../media/253-pipelines-02.png#lightbox) + +### Identity of user who requested a stage to run + +To improve security of your YAML pipelines, you may wish to know who requested a stage to run. To address this need, were adding two new predefined variables, `Build.StageRequestedBy` and `Build.StageRequestedById`. These variables are similar to the `Build.RequestedFor` and `Build.RequestedForId` variables, but for a stage, not a run. + +When a user explicitly triggers a user, for example, in case of a manually triggered stage or rerunning a stage, their identity is used to fill in the two variables. + diff --git a/release-notes/2025/includes/pipelines/sprint-254-update-links.md b/release-notes/2025/includes/pipelines/sprint-254-update-links.md new file mode 100644 index 00000000000..df1d4dd9ea1 --- /dev/null +++ b/release-notes/2025/includes/pipelines/sprint-254-update-links.md @@ -0,0 +1,11 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +ms.topic: include +--- + +- [Improved visibility into YAML pipeline stage dependencies](#improved-visibility-into-yaml-pipeline-stage-dependencies) +- [New Agent CDN](#new-agent-cdn) +- [Node 16 will be removed from pipelines-* Pipeline agent packages](#node-16-will-be-removed-from-pipelines--pipeline-agent-packages) + diff --git a/release-notes/2025/includes/pipelines/sprint-254-update.md b/release-notes/2025/includes/pipelines/sprint-254-update.md new file mode 100644 index 00000000000..e54f3294d6a --- /dev/null +++ b/release-notes/2025/includes/pipelines/sprint-254-update.md @@ -0,0 +1,50 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +ms.topic: include +--- + +### Improved visibility into YAML pipeline stage dependencies + +YAML pipelines provide flexibility for managing complex workflows, but visualizing stage dependencies has been a challenge—especially in multi-region deployments. + +> [!div class="mx-imgBorder"] +> [![Screenshot of pipeline that deploys to multiple Azure region.](../../media/254-pipelines-01.png "Screenshot of pipeline that deploys to multiple Azure region")](../../media/254-pipelines-01.png#lightbox) + + +It hasn't always been clear how stages are connected. For example, determining whether CUS3 depends on WUS1 in addition to WUS2 and WUS3 has required reviewing the YAML directly. + +With this sprint, stage dependencies are now displayed when a stage is expanded, providing immediate insight into execution order and upstream requirements. + +> [!div class="mx-imgBorder"] +> [![Screenshot of stage dependencies when you expand them.](../../media/254-pipelines-02.png "Screenshot of stage dependencies when you expand them")](../../media/254-pipelines-02.png#lightbox) + +### New Agent CDN + +As Edgio CDN is being retired, the domain URL owned by Edgio `https://vstsagentpackage.azureedge.net` will also be retired. We're adding a new domain URL `https://download.agent.dev.azure.com`  supported by the new CDN. Be sure to add this new domain URL to your firewall allowlist. Agent package downloads for self-hosted agents will fail once the old domain URL is removed. Refer to the [post](https://devblogs.microsoft.com/devops/cdn-domain-url-change-for-agents-in-pipelines/) for more details. + + +### Node 16 will be removed from pipelines-* Pipeline agent packages + +Agent tasks can be implemented in PowerShell or Node. The agent ships with multiple versions of Node that tasks can target. + +As new Node versions are released, [tasks](https://github.com/microsoft/azure-pipelines-tasks) are updated to use new Node versions. The runtimes are included with the agent. + +As Node versions exit out of the upstream maintenance window, some Pipelines tasks still depend on it. Azure DevOps updates supported tasks to a supported Node version. Third party tasks may still need older Node versions to run. + +To accommodate this, we have two types of Pipeline agent [packages](https://github.com/microsoft/azure-pipelines-agent/releases): + +| Packages | Node versions | Description | +|----------------------|---------------|----------------------------| +| `vsts-agent-*` | 6, 10, 16, 20 | Includes all Node versions that can be used as task execution handler | +| `pipelines-agents-*` | 20 | Includes only recent Node versions. The goal for these packages is to not include any end-of-life version of Node. | + +If you want to run a task that requires the Node 16 execution handler on an agent that doesn't have Node 16 bundled, you can install the execution handler by inserting the [NodeTaskRunnerInstaller@0](https://learn.microsoft.com/azure/devops/pipelines/tasks/reference/node-task-runner-installer-v0?view=azure-pipelines) task in your pipeline: + +```yaml + steps: + - task: NodeTaskRunnerInstaller@0 + inputs: + runnerVersion: 16 +``` diff --git a/release-notes/2025/includes/repos/sprint-248-update-links.md b/release-notes/2025/includes/repos/sprint-248-update-links.md new file mode 100644 index 00000000000..4aa07854470 --- /dev/null +++ b/release-notes/2025/includes/repos/sprint-248-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +ms.topic: include +--- + +- [Sparse checkout for Azure Repos](#sparse-checkout-for-azure-repos) +- [Make cross-repo policies case-sensitive](#make-cross-repo-policies-case-sensitive) \ No newline at end of file diff --git a/release-notes/2025/includes/repos/sprint-248-update.md b/release-notes/2025/includes/repos/sprint-248-update.md new file mode 100644 index 00000000000..2ad24ffb60f --- /dev/null +++ b/release-notes/2025/includes/repos/sprint-248-update.md @@ -0,0 +1,50 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +ms.topic: include +--- + + +### Sparse checkout for Azure Repos + +The [git sparse-checkout](https://github.blog/open-source/git/bring-your-monorepo-down-to-size-with-sparse-checkout/) command is now supported in the YAML checkout task, alongside the [partial clone filter](/azure/devops/pipelines/yaml-schema/steps-checkout?view=azure-pipelines), to improve repository checkout performance. You can use the properties `sparseCheckoutDirectories` and `sparseCheckoutPatterns`. + +Setting `sparseCheckoutDirectories` enables cone mode, where the checkout process uses directory matching. Alternatively, you can set `sparseCheckoutPatterns` which triggers non-cone mode, allowing more complex pattern matching. + +If both properties are set, the agent initializes cone mode with directory matching. If neither property is specified in the checkout task, the sparse checkout process is disabled. Any issues encountered during command execution results in the checkout task failing. + +YAML example for sparse checkout cone mode: +```yaml + - checkout: repo + sparseCheckoutDirectories: src +``` + +YAML example for sparse checkout non-cone mode: +```yaml + + - checkout: repo + sparseCheckoutPatterns: /* !/img + +``` +> [!IMPORTANT] +> The sparse checkout feature requires agent **v3.248.0 (v4.248.0 for .NET 8)** or later versions. + +You can find the agent on the **[releases page](https://github.com/microsoft/azure-pipelines-agent/releases)**. + + +### Make cross-repo policies case-sensitive + +Previously, the branch candidate preview for cross-repo policies displayed results in a case-insensitive manner, despite branch matching being case-sensitive. This inconsistency created potential misalignment, as it could appear that certain branches were protected when they weren't. +To resolve this issue, we have updated the branch pattern preview to align with the case-sensitive behavior of policy application. + +Previously: +> [!div class="mx-imgBorder"] +> [![Screenshot of before fix](../../media/248-repos-01.png "Screenshot of before fix")](../../media/248-repos-01.png#lightbox) + + + +After: + +> [!div class="mx-imgBorder"] +> [![Screenshot of after fix.](../../media/248-repos-02.png "Screenshot of after fix")](../../media/248-repos-02.png#lightbox) diff --git a/release-notes/2025/includes/repos/sprint-254-update-links.md b/release-notes/2025/includes/repos/sprint-254-update-links.md new file mode 100644 index 00000000000..735d756c0fe --- /dev/null +++ b/release-notes/2025/includes/repos/sprint-254-update-links.md @@ -0,0 +1,10 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +ms.topic: include +--- + +- [TFVC check-in policies changes](#tfvc-check-in-policies-changes) +- [Enhancement to GetRepository API](#enhancement-to-getrepository-api) +- [Enhancement to Pull Requests Query API](#enhancement-to-pull-requests-query-api) diff --git a/release-notes/2025/includes/repos/sprint-254-update.md b/release-notes/2025/includes/repos/sprint-254-update.md new file mode 100644 index 00000000000..a31a1792eb4 --- /dev/null +++ b/release-notes/2025/includes/repos/sprint-254-update.md @@ -0,0 +1,72 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +ms.topic: include +--- + +### TFVC check-in policies changes + +#### New version (19.254) of Microsoft.TeamFoundationServer.ExtendedClient NuGet package +NuGet `Microsoft.TeamFoundationServer.ExtendedClient` package was updated with new TFVC policy classes and methods. + + +#### Policy changes + +We're making changes to how TFVC check-in policies are stored in Azure DevOps, which also means updates to how the NuGet Microsoft.TeamFoundationServer.ExtendedClient communicates with the service. + + +If your TFVC project uses check-in policies, migrate those policies to the new format. There are two ways to do this: + +1. Using Visual Studio. + +> [!WARNING] +> Dangerous certain consequences of an action.: Ensure you updated Visual Studio to the latest version before proceeding (VS 2022, VS 2019, and VS 2017 with minimal versions `17.14 Preview 3`, `17.13.6`, `17.12.7`, `17.10.13`, `17.8.20`, `16.11.46`, `15.9.72` are supporting the new policies). + +To create new policies using Visual Studio project administrator should open **Settings** -> Team Project -> Source Control -> Check-in Policy and add new policy (without "Obsolete" mark) with the same parameters as old one: + +> [!div class="mx-imgBorder"] +> [![Screenshot of before fix](../../media/254-repos-01.png "Screenshot of before fix")](../../media/254-repos-01.png#lightbox) + +2. If you're using custom implementation of `Microsoft.TeamFoundationServer.ExtendedClient` to communicate with server, please follow the [migration guide](https://learn.microsoft.com/azure/devops/repos/tfvc/tfvc-check-in-policy-migrate-guide?view=azure-devops). + + + +The migration is required for keeping TFVC check-in compatible with the future Azure DevOps versions. For the time being, both old (Obsolete) and new policies remain valid and functional. +For information on the Future Plans, see our [blog post](https://devblogs.microsoft.com/devops/?p=70556&preview=true). + + +### Enhancement to GetRepository API + +We have added `creationDate` property to the response of Repositories - Get Repository API returning repository creation date. The property is available on the API versions `7.2-preview` and higher. + +### Enhancement to Pull Requests Query API + +We have introduced a new `Label` property in the response of Pull Request Query - Get API. You can now specify whether to include labels (tags) for related pull requests in every query. +A new `Include` property is available - if set to Labels, the response includes labels for the specified PRs. +If left as `null`, labels won't be included. +To prevent unintended errors, ensure that `NotSet` isn't explicitly assigned - this will result in `Bad Request`. + +> [!NOTE] +> Label enrichment resource utilization depends on the number of assigned labels and their length. Requesting labels can impact throttling and increase network load. To optimize the performance, we recommend avoiding unnecessary label requests. + +**Request payload example :** +```json +{ + "queries": [ + { + "type": "lastMergeCommit", + "include": "Labels", + "items": [ + "0d6c9b2b524113113fced41aecbf8631a4649dec" + ] + }, + { + "type": "lastMergeCommit", + "items": [ + "b524113113f0dd41aecbf8631a4649dec6c9b2ce" + ] + } + ] +} +``` \ No newline at end of file diff --git a/release-notes/2025/includes/testplans/sprint-248-update-links.md b/release-notes/2025/includes/testplans/sprint-248-update-links.md new file mode 100644 index 00000000000..60df2b0118b --- /dev/null +++ b/release-notes/2025/includes/testplans/sprint-248-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +ms.topic: include +--- + +- [Azure Test Plans bug fixes](#azure-test-plans-bug-fixes) diff --git a/release-notes/2025/includes/testplans/sprint-248-update.md b/release-notes/2025/includes/testplans/sprint-248-update.md new file mode 100644 index 00000000000..b213cdadb03 --- /dev/null +++ b/release-notes/2025/includes/testplans/sprint-248-update.md @@ -0,0 +1,18 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2025 +ms.topic: include +--- + +### Azure Test Plans bug fixes + +With this sprint, we’ve made updates to Azure Test Plans to resolve several bugs and improve usability. Here’s what’s been fixed: + +* **Shared step results vow visible:** + Fixed a bug where shared step results wouldn’t appear in the query editor when accessing test cases in the New Boards Hub. + +* **Improved stakeholder mode sessions:** + Resolved an issue in the test and feedback extension that blocked users with stakeholder access from starting sessions. +* **Cleaner test plan copying:** + Fixed a problem where requirements were duplicated when copying a Test Plan using the “Reference Existing Test Cases” option. diff --git a/release-notes/2025/includes/testplans/sprint-251-update-links.md b/release-notes/2025/includes/testplans/sprint-251-update-links.md new file mode 100644 index 00000000000..677208d64bd --- /dev/null +++ b/release-notes/2025/includes/testplans/sprint-251-update-links.md @@ -0,0 +1,11 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/12/2025 +ms.topic: include +--- + +- [Direct link from Test Plan work item to Test Plans page](#direct-link-from-test-plan-work-item-to-test-plans-page) +- [Azure Test Plans bug fixes](#azure-test-plans-bug-fixes) +- [Export test cases with custom columns in XLSX](#export-test-cases-with-custom-columns-in-xlsx) +- [Auto-pause manual test case run](#export-test-cases-with-custom-columns-in-xlsx) \ No newline at end of file diff --git a/release-notes/2025/includes/testplans/sprint-251-update.md b/release-notes/2025/includes/testplans/sprint-251-update.md new file mode 100644 index 00000000000..3f9e8b22191 --- /dev/null +++ b/release-notes/2025/includes/testplans/sprint-251-update.md @@ -0,0 +1,37 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/12/2025 +ms.topic: include +--- + +### Direct Link from Test plan work item to Test plans page + +You can now easily access the Test plans page directly from the Test plans work item. We're adding a clear, direct entry point to help you quickly navigate to the corresponding test plan without extra steps. This improvement makes it faster and more intuitive to trace your test plans, ensuring a smoother experience when managing your test workflow. + +> [!div class="mx-imgBorder"] +> ![Gif to demo Test Plan, Suite ID search details.](../../media/251-testplans-01.gif "gif to GitHub Test Plan, Suite ID search details") + + Give it a try and let us know via [email](mailto:adocustomerfeedback@service.microsoft.com) what you think! + +### Azure Test Plans bug fixes + +With this sprint, we made updates to Azure Test Plans to resolve several bugs and improve usability. Here's what's been fixed: + +* Fixed an issue where Test Suites didn't update correctly when switching between Test Plans. For details on the initial bug, see [this DevComm post](https://developercommunity.visualstudio.com/t/Changing-between-Test-Plans-does-not-alw/10753235). + +* Fixed an issue in the Test & Feedback Extension where session reports failed to download and redirected users to a blank page. + +* Fixed an issue in the new Boards hub where Shared Steps opened in the old work item form and users couldn't delete comments in the discussion section. [this DevComm post](https://developercommunity.visualstudio.com/t/Delete-comment-in-discussion-section-in-/10775737). + +* Fixed an issue where filtering test results by the Owner clause didn't work, causing queries to return an error instead of results. [this DevComm post](https://developercommunity.visualstudio.com/t/Filter-test-results-using-the-Owner-clau/10785774). + +### Export test cases with custom columns in XLSX + +You can now export custom columns in XLSX. We've heard your feedback requesting Test Plans supports exporting test cases with custom columns. This feature gives you greater flexibility and control over the data you share and analyze. In addition, it helps you tailor exports to your needs, ensuring the information you export is relevant and actionable. + +### Auto-pause manual test case run + +Never lose progress on your test runs with auto-pause test case run. This new feature automatically pauses your test case run if your work is interrupted, ensuring that partial progress is saved without needing a manual pause. Whether you step away or close the session, you can easily resume your test case right where you left off, reducing the risk of data loss and improving your workflow. By simplifying the pause and resume process, auto-pause helps you stay focused on testing without worrying about losing your progress. + +Give it a try, and let us know via [email](mailto:adocustomerfeedback@service.microsoft.com) what you think! \ No newline at end of file diff --git a/release-notes/2025/includes/testplans/sprint-252-update-links.md b/release-notes/2025/includes/testplans/sprint-252-update-links.md new file mode 100644 index 00000000000..3e1f86a3184 --- /dev/null +++ b/release-notes/2025/includes/testplans/sprint-252-update-links.md @@ -0,0 +1,8 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +ms.topic: include +--- + +- [Undo test step in web and desktop runner](#undo-test-step-in-web-and-desktop-runner) diff --git a/release-notes/2025/includes/testplans/sprint-252-update.md b/release-notes/2025/includes/testplans/sprint-252-update.md new file mode 100644 index 00000000000..b5fffc0c3bd --- /dev/null +++ b/release-notes/2025/includes/testplans/sprint-252-update.md @@ -0,0 +1,16 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +ms.topic: include +--- + +### Undo test step in web and desktop runner + +Take control of your test case run with the new "Undo" option. You can easily revert test step statuses with a simple double-click, giving you more flexibility and control during test runs. No more restarting test cases to fix accidental clicks—just undo and continue your workflow without interruption. + +We're also introducing keyboard-friendly navigation and accessibility improvements to ensure this feature works seamlessly for all users, including those who rely on assistive technologies. This enhancement helps you save time, reduce frustration, and stay focused on running tests efficiently. Give it a try and let us know via [email](mailto:adocustomerfeedback@service.microsoft.com) what you think! + + +> [!div class="mx-imgBorder"] +> ![Gif to demo Undo test step in web and desktop runner.](../../media/252-testplans-01.gif "gif to demo Undo test step in web and desktop runner") diff --git a/release-notes/2025/includes/testplans/sprint-253-update-links.md b/release-notes/2025/includes/testplans/sprint-253-update-links.md new file mode 100644 index 00000000000..41bc1894516 --- /dev/null +++ b/release-notes/2025/includes/testplans/sprint-253-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 3/20/2025 +ms.topic: include +--- + +- [Publish code coverage results v2 task improvements](#publish-code-coverage-results-v2-task-improvements) +- [Export test cases with custom columns in XLSX](#export-test-cases-with-custom-columns-in-xlsx) \ No newline at end of file diff --git a/release-notes/2025/includes/testplans/sprint-253-update.md b/release-notes/2025/includes/testplans/sprint-253-update.md new file mode 100644 index 00000000000..f5fa474bb2b --- /dev/null +++ b/release-notes/2025/includes/testplans/sprint-253-update.md @@ -0,0 +1,22 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 3/20/2025 +ms.topic: include +--- + +### Publish code coverage results v2 task improvements + +With this release we're including several improvements to the v2 task: +* Expanded support for various code coverage formats, including: .coverage,.covx,.covb,.cjson,.xml,.lcov, and pycov1. +* Generation of a comprehensive cjson file (and a Code Coverage report) that contains detailed code coverage information such as file names, lines covered/not covered, etc. + +> [!div class="mx-imgBorder"] +> [![Screenshot of code coverage.](../../media/253-testplans-01.png "Screenshot of code coverage")](../../media/253-testplans-01.png#lightbox) + +* Support for diff coverage (PR coverage): v2 can generate diff coverage PR comments for multiple languages within the same pipeline. +* v2 task now supports the Build Quality Check task, which wasn't supported in v1 task. + +### Export test cases with custom columns in XLSX + +You can now export test cases with custom columns in XLSX. Based on your feedback, Test Plans supports exporting test cases with custom columns, giving you greater flexibility and control over the data you share and analyze. This enhancement helps you tailor exports to your needs, ensuring the information you export is relevant and actionable. diff --git a/release-notes/2025/includes/testplans/sprint-254-update-links.md b/release-notes/2025/includes/testplans/sprint-254-update-links.md new file mode 100644 index 00000000000..ef2286beb42 --- /dev/null +++ b/release-notes/2025/includes/testplans/sprint-254-update-links.md @@ -0,0 +1,9 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +ms.topic: include +--- + +- [Retirement of action logging and switch to screen recording](#retirement-of-action-logging-and-switch-to-screen-recording) +- [Auto-pause manual test run ](#auto-pause-manual-test-run) diff --git a/release-notes/2025/includes/testplans/sprint-254-update.md b/release-notes/2025/includes/testplans/sprint-254-update.md new file mode 100644 index 00000000000..6b6ed2df991 --- /dev/null +++ b/release-notes/2025/includes/testplans/sprint-254-update.md @@ -0,0 +1,19 @@ +--- +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +ms.topic: include +--- + +### Retirement of action logging and switch to screen recording + +Our desktop Azure Test Runner client relies on [Problem Steps Recorder](https://support.microsoft.com/windows/record-steps-to-reproduce-a-problem-46582a9b-620f-2e36-00c9-04e25d784e47) (PSR), a tool introduced in Windows 7 that is now [being deprecated](https://support.microsoft.com/windows/steps-recorder-deprecation-a64888d7-8482-4965-8ce3-25fb004e975f) in newer Windows versions. As a result, the action log functionality in our desktop test runner may no longer work in future updates. + +To ensure uninterrupted test tracking, we recommend switching to screen recording in our web runner, [Test & Feedback Extension](https://marketplace.visualstudio.com/items?itemName=ms.vss-exploratorytesting-web), which provides a modern, reliable way to capture and manage test steps. If you need assistance transitioning to the Test & Feedback Extension, please reach out to our support team. + +### Auto-pause manual test run + +Never lose progress on your test runs with auto-pause test case run. This new feature automatically pauses your test case run if your work is interrupted, ensuring that partial progress is saved without needing a manual pause. Whether you step away or close the session, you can easily resume your test case right where you left off, reducing the risk of data loss and improving your workflow. By simplifying the pause and resume process, auto-pause helps you stay focused on testing without worrying about losing your progress. Give it a try, and let us know via [email](mailto:adocustomerfeedback@service.microsoft.com) what you think! + +> [!div class="mx-imgBorder"] +> ![Gif to demo Undo test step in web and desktop runner.](../../media/254-testplans-01.gif "gif to demo Undo test step in web and desktop runner") \ No newline at end of file diff --git a/release-notes/2025/media/248-boards-01.png b/release-notes/2025/media/248-boards-01.png new file mode 100644 index 00000000000..4769b2ee5d6 Binary files /dev/null and b/release-notes/2025/media/248-boards-01.png differ diff --git a/release-notes/2025/media/248-boards-02.png b/release-notes/2025/media/248-boards-02.png new file mode 100644 index 00000000000..7ba2794cae9 Binary files /dev/null and b/release-notes/2025/media/248-boards-02.png differ diff --git a/release-notes/2025/media/248-ghazdo-01.png b/release-notes/2025/media/248-ghazdo-01.png new file mode 100644 index 00000000000..d5dbbc94a55 Binary files /dev/null and b/release-notes/2025/media/248-ghazdo-01.png differ diff --git a/release-notes/2025/media/248-repos-01.png b/release-notes/2025/media/248-repos-01.png new file mode 100644 index 00000000000..226dedef85e Binary files /dev/null and b/release-notes/2025/media/248-repos-01.png differ diff --git a/release-notes/2025/media/248-repos-02.png b/release-notes/2025/media/248-repos-02.png new file mode 100644 index 00000000000..f775b9d964d Binary files /dev/null and b/release-notes/2025/media/248-repos-02.png differ diff --git a/release-notes/2025/media/251-boards-01.png b/release-notes/2025/media/251-boards-01.png new file mode 100644 index 00000000000..db55b0493cd Binary files /dev/null and b/release-notes/2025/media/251-boards-01.png differ diff --git a/release-notes/2025/media/251-general-01.png b/release-notes/2025/media/251-general-01.png new file mode 100644 index 00000000000..22af82d7435 Binary files /dev/null and b/release-notes/2025/media/251-general-01.png differ diff --git a/release-notes/2025/media/251-ghazdo-01.png b/release-notes/2025/media/251-ghazdo-01.png new file mode 100644 index 00000000000..c01438928b5 Binary files /dev/null and b/release-notes/2025/media/251-ghazdo-01.png differ diff --git a/release-notes/2025/media/251-pipelines-01.png b/release-notes/2025/media/251-pipelines-01.png new file mode 100644 index 00000000000..0dbee220b85 Binary files /dev/null and b/release-notes/2025/media/251-pipelines-01.png differ diff --git a/release-notes/2025/media/251-testplans-01.gif b/release-notes/2025/media/251-testplans-01.gif new file mode 100644 index 00000000000..fce6f600705 Binary files /dev/null and b/release-notes/2025/media/251-testplans-01.gif differ diff --git a/release-notes/2025/media/252-boards-01.png b/release-notes/2025/media/252-boards-01.png new file mode 100644 index 00000000000..2d180e009b6 Binary files /dev/null and b/release-notes/2025/media/252-boards-01.png differ diff --git a/release-notes/2025/media/252-boards-02.png b/release-notes/2025/media/252-boards-02.png new file mode 100644 index 00000000000..92ba299a56c Binary files /dev/null and b/release-notes/2025/media/252-boards-02.png differ diff --git a/release-notes/2025/media/252-general-01.png b/release-notes/2025/media/252-general-01.png new file mode 100644 index 00000000000..d8ae161f701 Binary files /dev/null and b/release-notes/2025/media/252-general-01.png differ diff --git a/release-notes/2025/media/252-general-01b b/release-notes/2025/media/252-general-01b new file mode 100644 index 00000000000..f5dbf4544ee Binary files /dev/null and b/release-notes/2025/media/252-general-01b differ diff --git a/release-notes/2025/media/252-general-01b.png b/release-notes/2025/media/252-general-01b.png new file mode 100644 index 00000000000..06f4a5f910a Binary files /dev/null and b/release-notes/2025/media/252-general-01b.png differ diff --git a/release-notes/2025/media/252-general-01c.png b/release-notes/2025/media/252-general-01c.png new file mode 100644 index 00000000000..fec3035c8f7 Binary files /dev/null and b/release-notes/2025/media/252-general-01c.png differ diff --git a/release-notes/2025/media/252-general-02.png b/release-notes/2025/media/252-general-02.png new file mode 100644 index 00000000000..263291a15fc Binary files /dev/null and b/release-notes/2025/media/252-general-02.png differ diff --git a/release-notes/2025/media/252-ghazdo-01.png b/release-notes/2025/media/252-ghazdo-01.png new file mode 100644 index 00000000000..6900e2c233c Binary files /dev/null and b/release-notes/2025/media/252-ghazdo-01.png differ diff --git a/release-notes/2025/media/252-pipelines-01.png b/release-notes/2025/media/252-pipelines-01.png new file mode 100644 index 00000000000..afe120947af Binary files /dev/null and b/release-notes/2025/media/252-pipelines-01.png differ diff --git a/release-notes/2025/media/252-pipelines-02.png b/release-notes/2025/media/252-pipelines-02.png new file mode 100644 index 00000000000..9a6b618224d Binary files /dev/null and b/release-notes/2025/media/252-pipelines-02.png differ diff --git a/release-notes/2025/media/252-testplans-01.gif b/release-notes/2025/media/252-testplans-01.gif new file mode 100644 index 00000000000..9d7307d63b6 Binary files /dev/null and b/release-notes/2025/media/252-testplans-01.gif differ diff --git a/release-notes/2025/media/253-general-01.png b/release-notes/2025/media/253-general-01.png new file mode 100644 index 00000000000..a2d8e3a5b27 Binary files /dev/null and b/release-notes/2025/media/253-general-01.png differ diff --git a/release-notes/2025/media/253-general-02.png b/release-notes/2025/media/253-general-02.png new file mode 100644 index 00000000000..c0db2345340 Binary files /dev/null and b/release-notes/2025/media/253-general-02.png differ diff --git a/release-notes/2025/media/253-ghazdo-01.png b/release-notes/2025/media/253-ghazdo-01.png new file mode 100644 index 00000000000..6c8ac17661a Binary files /dev/null and b/release-notes/2025/media/253-ghazdo-01.png differ diff --git a/release-notes/2025/media/253-ghazdo-02.png b/release-notes/2025/media/253-ghazdo-02.png new file mode 100644 index 00000000000..87ef9f5a74e Binary files /dev/null and b/release-notes/2025/media/253-ghazdo-02.png differ diff --git a/release-notes/2025/media/253-pipelines-01.png b/release-notes/2025/media/253-pipelines-01.png new file mode 100644 index 00000000000..82c87bbb36f Binary files /dev/null and b/release-notes/2025/media/253-pipelines-01.png differ diff --git a/release-notes/2025/media/253-pipelines-02.png b/release-notes/2025/media/253-pipelines-02.png new file mode 100644 index 00000000000..b1eb5c2228a Binary files /dev/null and b/release-notes/2025/media/253-pipelines-02.png differ diff --git a/release-notes/2025/media/253-testplans-01.png b/release-notes/2025/media/253-testplans-01.png new file mode 100644 index 00000000000..05fb74866bd Binary files /dev/null and b/release-notes/2025/media/253-testplans-01.png differ diff --git a/release-notes/2025/media/254-boards-01.gif b/release-notes/2025/media/254-boards-01.gif new file mode 100644 index 00000000000..ae7e6924a6e Binary files /dev/null and b/release-notes/2025/media/254-boards-01.gif differ diff --git a/release-notes/2025/media/254-boards-01.png b/release-notes/2025/media/254-boards-01.png new file mode 100644 index 00000000000..2b6e4c96be6 Binary files /dev/null and b/release-notes/2025/media/254-boards-01.png differ diff --git a/release-notes/2025/media/254-boards-01b.gif b/release-notes/2025/media/254-boards-01b.gif new file mode 100644 index 00000000000..63991994053 Binary files /dev/null and b/release-notes/2025/media/254-boards-01b.gif differ diff --git a/release-notes/2025/media/254-boards-02.png b/release-notes/2025/media/254-boards-02.png new file mode 100644 index 00000000000..e45b4cc0d79 Binary files /dev/null and b/release-notes/2025/media/254-boards-02.png differ diff --git a/release-notes/2025/media/254-pipelines-01.png b/release-notes/2025/media/254-pipelines-01.png new file mode 100644 index 00000000000..82c3187d6ed Binary files /dev/null and b/release-notes/2025/media/254-pipelines-01.png differ diff --git a/release-notes/2025/media/254-pipelines-02.png b/release-notes/2025/media/254-pipelines-02.png new file mode 100644 index 00000000000..2d7e7797114 Binary files /dev/null and b/release-notes/2025/media/254-pipelines-02.png differ diff --git a/release-notes/2025/media/254-repos-01.png b/release-notes/2025/media/254-repos-01.png new file mode 100644 index 00000000000..094977ebd8f Binary files /dev/null and b/release-notes/2025/media/254-repos-01.png differ diff --git a/release-notes/2025/media/254-testplans-01.gif b/release-notes/2025/media/254-testplans-01.gif new file mode 100644 index 00000000000..10bd09d35e3 Binary files /dev/null and b/release-notes/2025/media/254-testplans-01.gif differ diff --git a/release-notes/2025/media/254-testplans-01.png b/release-notes/2025/media/254-testplans-01.png new file mode 100644 index 00000000000..3032b24e575 Binary files /dev/null and b/release-notes/2025/media/254-testplans-01.png differ diff --git a/release-notes/2025/media/254-testplans-02.png b/release-notes/2025/media/254-testplans-02.png new file mode 100644 index 00000000000..dbbcba64a85 Binary files /dev/null and b/release-notes/2025/media/254-testplans-02.png differ diff --git a/release-notes/2025/media/github-boards-integration-improvements-1.mp4 b/release-notes/2025/media/github-boards-integration-improvements-1.mp4 new file mode 100644 index 00000000000..a545cd49c38 Binary files /dev/null and b/release-notes/2025/media/github-boards-integration-improvements-1.mp4 differ diff --git a/release-notes/2025/pipelines/AzureVmssDeployment-rbac.png b/release-notes/2025/pipelines/AzureVmssDeployment-rbac.png new file mode 100644 index 00000000000..b82e85682bd Binary files /dev/null and b/release-notes/2025/pipelines/AzureVmssDeployment-rbac.png differ diff --git a/release-notes/2025/pipelines/sprint-248-update.md b/release-notes/2025/pipelines/sprint-248-update.md new file mode 100644 index 00000000000..cb3e43614d8 --- /dev/null +++ b/release-notes/2025/pipelines/sprint-248-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 248 update +description: See the Sprint 248 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 11/26/2024 +--- + +# Azure Pipelines - Sprint 248 Update + +## Features + +[!INCLUDE [sprint-248-update-links](../includes/pipelines/sprint-248-update-links.md)] + +[!INCLUDE [sprint-248-update](../includes/pipelines/sprint-248-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/pipelines/sprint-251-update.md b/release-notes/2025/pipelines/sprint-251-update.md new file mode 100644 index 00000000000..46e38cb6242 --- /dev/null +++ b/release-notes/2025/pipelines/sprint-251-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 251 update +description: See the Sprint 251 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/10/2024 +--- + +# Azure Pipelines - Sprint 251 Update + +## Features + +[!INCLUDE [sprint-251-update-links](../includes/pipelines/sprint-251-update-links.md)] + +[!INCLUDE [sprint-251-update](../includes/pipelines/sprint-251-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/pipelines/sprint-252-update.md b/release-notes/2025/pipelines/sprint-252-update.md new file mode 100644 index 00000000000..350f8952604 --- /dev/null +++ b/release-notes/2025/pipelines/sprint-252-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 252 update +description: See the Sprint 252 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2024 +--- + +# Azure Pipelines - Sprint 252 Update + +## Features + +[!INCLUDE [sprint-252-update-links](../includes/pipelines/sprint-252-update-links.md)] + +[!INCLUDE [sprint-252-update](../includes/pipelines/sprint-252-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/pipelines/sprint-253-update.md b/release-notes/2025/pipelines/sprint-253-update.md new file mode 100644 index 00000000000..bef3ccdb03d --- /dev/null +++ b/release-notes/2025/pipelines/sprint-253-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 253 update +description: See the Sprint 253 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 3/12/2024 +--- + +# Azure Pipelines - Sprint 253 Update + +## Features + +[!INCLUDE [sprint-253-update-links](../includes/pipelines/sprint-253-update-links.md)] + +[!INCLUDE [sprint-253-update](../includes/pipelines/sprint-253-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/pipelines/sprint-254-update.md b/release-notes/2025/pipelines/sprint-254-update.md new file mode 100644 index 00000000000..f710334c903 --- /dev/null +++ b/release-notes/2025/pipelines/sprint-254-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps release notes - Azure Pipelines Sprint 254 update +description: See the Sprint 254 feature updates for Azure Pipelines, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2024 +--- + +# Azure Pipelines - Sprint 254 Update + +## Features + +[!INCLUDE [sprint-254-update-links](../includes/pipelines/sprint-254-update-links.md)] + +[!INCLUDE [sprint-254-update](../includes/pipelines/sprint-254-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/repos/sprint-248-update.md b/release-notes/2025/repos/sprint-248-update.md new file mode 100644 index 00000000000..b7808b8abf5 --- /dev/null +++ b/release-notes/2025/repos/sprint-248-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 248 Update +description: See the Sprint 248 feature updates for Azure Repos, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 1/15/2025 +--- + +# Azure Repos - Sprint 248 Update + +## Features + +[!INCLUDE [sprint-248-update-links](../includes/repos/sprint-248-update-links.md)] + +[!INCLUDE [sprint-248-update](../includes/repos/sprint-248-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2025/repos/sprint-254-update.md b/release-notes/2025/repos/sprint-254-update.md new file mode 100644 index 00000000000..ee938f90057 --- /dev/null +++ b/release-notes/2025/repos/sprint-254-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Repos Sprint 254 Update +description: See the Sprint 254 feature updates for Azure Repos, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +--- + +# Azure Repos - Sprint 254 Update + +## Features + +[!INCLUDE [sprint-254-update-links](../includes/repos/sprint-254-update-links.md)] + +[!INCLUDE [sprint-254-update](../includes/repos/sprint-254-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] diff --git a/release-notes/2025/sprint-248-update.md b/release-notes/2025/sprint-248-update.md new file mode 100644 index 00000000000..9f1590e3faf --- /dev/null +++ b/release-notes/2025/sprint-248-update.md @@ -0,0 +1,77 @@ +--- +title: Security and Pipeline workflows +author: ckanyika +ms.author: ckanyika +ms.date: 1/17/2024 +description: Security and Pipeline workflows +--- +# Enhanced security and Pipeline workflows + +With this sprint, we’re enhancing your DevOps workflow with greater security visibility and streamlined pipeline workflows. GitHub Advanced Security now includes detailed enablement tracking for **dependency scanning**, **code scanning**, and **secret scanning**, offering deeper insights into your organization’s security coverage. + +In addition, we're excited to introduce pipeline-focused enhancements, including new YAML expression functions and expanded controls for manual validation tasks, enabling you to create more efficient and secure workflows. + +Check out the release notes for details. + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-248-update-links](includes/ghazdo/sprint-248-update-links.md)] + +### Azure Boards: + +[!INCLUDE [sprint-248-update-links](includes/boards/sprint-248-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-248-update-links](includes/repos/sprint-248-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-248-update-links](includes/pipelines/sprint-248-update-links.md)] + +### Test Plans + +[!INCLUDE [sprint-248-update-links](includes/testplans/sprint-248-update-links.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-248-update](includes/ghazdo/sprint-248-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-248-update](includes/boards/sprint-248-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-248-update](includes/repos/sprint-248-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-248-update](includes/pipelines/sprint-248-update.md)] + +## Test Plans + +[!INCLUDE [sprint-248-update](includes/testplans/sprint-248-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2025/sprint-251-update.md b/release-notes/2025/sprint-251-update.md new file mode 100644 index 00000000000..a2bb1d80241 --- /dev/null +++ b/release-notes/2025/sprint-251-update.md @@ -0,0 +1,69 @@ +--- +title: Git authentication and improved pipeline scalability +author: ckanyika +ms.author: ckanyika +ms.date: 2/12/2025 +description: Git authentication and improved pipeline scalability +--- +# Secure Git authentication and improved Pipeline scalability + +We’re excited to announce new enhancements in Azure DevOps that improve security and simplify workflows. The Generate Git Credentials button has been removed from the Clone Repository dialogs in Repos and Wiki, aligning with our move to Microsoft Entra tokens for authentication—helping teams adopt a more secure and efficient Git workflow. + +Additionally, we are pleased to announce that in Azure Pipelines, managed DevOps pools is now generally available. This feature enhances scalability, reliability, and streamlined management for Azure DevOps Virtual Machine Scale Set agent pools. + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-251-update-links](includes/general/sprint-251-update-links.md)] + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-251-update-links](includes/ghazdo/sprint-251-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-251-update-links](includes/pipelines/sprint-251-update-links.md)] + +### Test Plans + +[!INCLUDE [sprint-251-update-links](includes/testplans/sprint-251-update-links.md)] + +## General + +[!INCLUDE [sprint-251-update](includes/general/sprint-251-update.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-251-update](includes/ghazdo/sprint-251-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-251-update](includes/pipelines/sprint-251-update.md)] + +## Test Plans + +[!INCLUDE [sprint-251-update](includes/testplans/sprint-251-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2025/sprint-252-update.md b/release-notes/2025/sprint-252-update.md new file mode 100644 index 00000000000..b1a13ab4220 --- /dev/null +++ b/release-notes/2025/sprint-252-update.md @@ -0,0 +1,77 @@ +--- +title: Basic access included with GitHub Enterprise plus Boards/GitHub integration improvements +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +description: Basic access included with GitHub Enterprise plus Boards/GitHub integration improvements +--- +# Basic access included with GitHub Enterprise plus Boards/GitHub integration improvements + +We're excited to announce that Azure DevOps Basic access is now included with GitHub Enterprise. Sign in using your Entra ID to get started. + +We're also releasing several improvements to our Boards + GitHub integration. + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-252-update-links](includes/general/sprint-252-update-links.md)] + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-252-update-links](includes/ghazdo/sprint-252-update-links.md)] + +### Azure Boards: + +[!INCLUDE [sprint-252-update-links](includes/boards/sprint-252-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-252-update-links](includes/pipelines/sprint-252-update-links.md)] + +### Test Plans + +[!INCLUDE [sprint-252-update-links](includes/testplans/sprint-252-update-links.md)] + +## General + +[!INCLUDE [sprint-252-update](includes/general/sprint-252-update.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-252-update](includes/ghazdo/sprint-252-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-252-update](includes/boards/sprint-252-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-252-update](includes/pipelines/sprint-252-update.md)] + +## Test Plans + +[!INCLUDE [sprint-252-update](includes/testplans/sprint-252-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Dan Hellem diff --git a/release-notes/2025/sprint-253-update.md b/release-notes/2025/sprint-253-update.md new file mode 100644 index 00000000000..9565805fcd2 --- /dev/null +++ b/release-notes/2025/sprint-253-update.md @@ -0,0 +1,70 @@ +--- +title: Strengthening Security and Multi-Repository Integration in Azure DevOps +author: ckanyika +ms.author: ckanyika +ms.date: 3/20/2025 +description: Strengthening Security and Multi-Repository Integration in Azure DevOps +--- +# Strengthening security and repository integration + +With this update, we’re improving security and authentication across Azure DevOps. Overlapping secrets for Azure DevOps OAuth make secret rotation seamless, while GitHub Advanced Security brings better filtering to the security overview page while ensuring multi-repository publishing correctly routes dependency and code scanning alerts. + +Hosted image updates in Azure Pipelines, include Ubuntu-24.04, Windows 2025, and mac-OS 15 Sequoia, ensuring a more secure and reliable experience. + + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-253-update-links](includes/general/sprint-253-update-links.md)] + +### GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-253-update-links](includes/ghazdo/sprint-253-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-253-update-links](includes/pipelines/sprint-253-update-links.md)] + +### Test Plans + +[!INCLUDE [sprint-253-update-links](includes/testplans/sprint-253-update-links.md)] + +## General + +[!INCLUDE [sprint-253-update](includes/general/sprint-253-update.md)] + +## GitHub Advanced Security for Azure DevOps + +[!INCLUDE [sprint-253-update](includes/ghazdo/sprint-253-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-253-update](includes/pipelines/sprint-253-update.md)] + +## Test Plans + +[!INCLUDE [sprint-253-update](includes/testplans/sprint-253-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2025/sprint-254-update.md b/release-notes/2025/sprint-254-update.md new file mode 100644 index 00000000000..406579539c1 --- /dev/null +++ b/release-notes/2025/sprint-254-update.md @@ -0,0 +1,77 @@ +--- +title: Azure DevOps service updates and integration improvements +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +description: Azure DevOps service updates and integration improvements +--- +# Azure DevOps service updates and integration improvements + +To help ensure your Azure DevOps environment remains secure, we're making key service updates. This includes ending support for new OAuth app registrations starting April 2025, though existing apps will continue working until full retirement in 2026. Additionally, Server Name Indication (SNI) will be required for all HTTPS connections beginning April 23, 2025, along with updates to TFVC check-in policies in Azure Repos. + +Alongside these updates, we’re excited to announce the latest improvements in our Azure Boards + GitHub integration, making it easier to link branches, pull requests, and commits to work items. In addition, Pipelines now provides greater visibility into YAML stage dependencies, helping teams manage more complex workflows with improved efficiency. + +Check out the release notes for details. + +### General + +[!INCLUDE [sprint-254-update-links](includes/general/sprint-254-update-links.md)] + +### Azure Boards: + +[!INCLUDE [sprint-254-update-links](includes/boards/sprint-254-update-links.md)] + +### Azure Repos + +[!INCLUDE [sprint-254-update-links](includes/repos/sprint-254-update-links.md)] + +### Azure Pipelines + +[!INCLUDE [sprint-254-update-links](includes/pipelines/sprint-254-update-links.md)] + +### Azure Test Plans: + +[!INCLUDE [sprint-254-update-links](includes/testplans/sprint-254-update-links.md)] + +## General + +[!INCLUDE [sprint-254-update](includes/general/sprint-254-update.md)] + +## Azure Boards + +[!INCLUDE [sprint-254-update](includes/boards/sprint-254-update.md)] + +## Azure Repos + +[!INCLUDE [sprint-254-update](includes/repos/sprint-254-update.md)] + +## Azure Pipelines + +[!INCLUDE [sprint-254-update](includes/pipelines/sprint-254-update.md)] + +## Azure Test Plans + +[!INCLUDE [sprint-254-update](includes/testplans/sprint-254-update.md)] + +## Next steps + +> [!NOTE] +> These features will roll out over the next two to three weeks. + +Head over to Azure DevOps and take a look. + +> [!div class="nextstepaction"] +> [Go to Azure DevOps](https://go.microsoft.com/fwlink/?LinkId=307137&campaign=o~msft~docs~product-vsts~release-notes) + +## How to provide feedback + +We would love to hear what you think about these features. Use the help menu to report a problem or provide a suggestion. + +> [!div class="mx-imgBorder"] +> ![Make a suggestion](../media/make-a-suggestion.png) + +You can also get advice and your questions answered by the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-devops). + +Thanks, + +Silviu Andrica diff --git a/release-notes/2025/testplans/sprint-248-update.md b/release-notes/2025/testplans/sprint-248-update.md new file mode 100644 index 00000000000..1c0402d429c --- /dev/null +++ b/release-notes/2025/testplans/sprint-248-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Test Plans Sprint 248 Update +description: See the Sprint 248 feature updates for Azure Test Plans, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 1/15/2025 +--- + +# Azure Test Plans - Sprint 248 Update + +## Features + +[!INCLUDE [sprint-248-update-links](../includes/testplans/sprint-248-update-links.md)] + +[!INCLUDE [sprint-248-update](../includes/testplans/sprint-248-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/testplans/sprint-251-update.md b/release-notes/2025/testplans/sprint-251-update.md new file mode 100644 index 00000000000..d1dd7fcdaa8 --- /dev/null +++ b/release-notes/2025/testplans/sprint-251-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Test Plans Sprint 251 Update +description: See the Sprint 251 feature updates for Azure Test Plans, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/12/2025 +--- + +# Azure Test Plans - Sprint 251 Update + +## Features + +[!INCLUDE [sprint-251-update-links](../includes/testplans/sprint-251-update-links.md)] + +[!INCLUDE [sprint-251-update](../includes/testplans/sprint-251-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/testplans/sprint-252-update.md b/release-notes/2025/testplans/sprint-252-update.md new file mode 100644 index 00000000000..4841e969bb1 --- /dev/null +++ b/release-notes/2025/testplans/sprint-252-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Test Plans Sprint 252 Update +description: See the Sprint 252 feature updates for Azure Test Plans, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 2/24/2025 +--- + +# Azure Test Plans - Sprint 252 Update + +## Features + +[!INCLUDE [sprint-252-update-links](../includes/testplans/sprint-252-update-links.md)] + +[!INCLUDE [sprint-252-update](../includes/testplans/sprint-252-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/testplans/sprint-253-update.md b/release-notes/2025/testplans/sprint-253-update.md new file mode 100644 index 00000000000..7f97e4c9d9d --- /dev/null +++ b/release-notes/2025/testplans/sprint-253-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Test Plans Sprint 253 Update +description: See the Sprint 253 feature updates for Azure Test Plans, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 3/20/2025 +--- + +# Azure Test Plans - Sprint 253 Update + +## Features + +[!INCLUDE [sprint-253-update-links](../includes/testplans/sprint-253-update-links.md)] + +[!INCLUDE [sprint-253-update](../includes/testplans/sprint-253-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/2025/testplans/sprint-254-update.md b/release-notes/2025/testplans/sprint-254-update.md new file mode 100644 index 00000000000..ff05262d761 --- /dev/null +++ b/release-notes/2025/testplans/sprint-254-update.md @@ -0,0 +1,17 @@ +--- +title: Azure DevOps Release Notes - Azure Test Plans Sprint 254 Update +description: See the Sprint 254 feature updates for Azure Test Plans, including next steps. +author: ckanyika +ms.author: ckanyika +ms.date: 4/3/2025 +--- + +# Azure Test Plans - Sprint 254 Update + +## Features + +[!INCLUDE [sprint-254-update-links](../includes/testplans/sprint-254-update-links.md)] + +[!INCLUDE [sprint-254-update](../includes/testplans/sprint-254-update.md)] + +[!INCLUDE [nextsteps](../includes/nextsteps.md)] \ No newline at end of file diff --git a/release-notes/TOC.yml b/release-notes/TOC.yml index fe760877660..337adc3598c 100644 --- a/release-notes/TOC.yml +++ b/release-notes/TOC.yml @@ -8,8 +8,70 @@ items: - name: By release date items: + - name: "2025" + items: + - name: April 3 + href: 2025/sprint-254-update.md + - name: March 20 + href: 2025/sprint-253-update.md + - name: February 24 + href: 2025/sprint-252-update.md + - name: February 12 + href: 2025/sprint-251-update.md + - name: January 17 + href: 2025/sprint-248-update.md + expanded: true + - name: "2024" + items: + - name: November 13 + href: 2024/sprint-247-update.md + - name: October 16 + href: 2024/sprint-246-update.md + - name: September 26 + href: 2024/sprint-245-update.md + - name: September 4 + href: 2024/sprint-244-update.md + - name: August 13 + href: 2024/sprint-243-update.md + - name: July 25 + href: 2024/sprint-242-update.md + - name: July 3 + href: 2024/sprint-241-update.md + - name: June 14 + href: 2024/sprint-240-update.md + - name: May 2 + href: 2024/sprint-238-update.md + - name: April 10 + href: 2024/sprint-237-update.md + - name: March 26 + href: 2024/sprint-236-update.md + - name: February 29 + href: 2024/sprint-235-update.md + - name: February 9 + href: 2024/sprint-234-update.md + - name: January 18 + href: 2024/sprint-233-update.md + - name: January 11 + href: 2024/sprint-232-update.md + expanded: false - name: "2023" items: + - name: December 5 + href: 2023/sprint-231-update.md + - name: November 16 + href: 2023/sprint-230-update.md + - name: October 26 + href: 2023/sprint-229-update.md + - name: October 4 + href: 2023/sprint-228-update.md + - name: September 14 + href: 2023/sprint-227-update.md + - name: August 23 + href: 2023/sprint-226-update.md + - name: August 2 + href: 2023/sprint-225-update.md + - name: July 11 + href: 2023/sprint-224-update.md - name: June 21 href: 2023/sprint-223-update.md - name: June 6 @@ -30,7 +92,7 @@ href: 2023/sprint-215-update.md - name: January 12 href: 2023/sprint-214-update.md - expanded: true + expanded: false - name: "2022" items: - name: December 8 @@ -220,8 +282,52 @@ items: - name: Azure Boards items: + - name: "2025" + items: + - name: April 3 + href: 2025/boards/sprint-254-update.md + - name: February 24 + href: 2025/boards/sprint-252-update.md + - name: January 17 + href: 2025/boards/sprint-248-update.md + expanded: false + - name: "2024" + items: + - name: November 13 + href: 2024/boards/sprint-247-update.md + - name: October 16 + href: 2024/boards/sprint-246-update.md + - name: September 26 + href: 2024/boards/sprint-245-update.md + - name: September 4 + href: 2024/boards/sprint-244-update.md + - name: July 25 + href: 2024/boards/sprint-242-update.md + - name: June 14 + href: 2024/boards/sprint-240-update.md + - name: April 10 + href: 2024/boards/sprint-237-update.md + - name: February 29 + href: 2024/boards/sprint-235-update.md + - name: February 9 + href: 2024/boards/sprint-234-update.md + - name: January 18 + href: 2024/boards/sprint-233-update.md + expanded: false - name: "2023" items: + - name: December 5 + href: 2023/boards/sprint-231-update.md + - name: November 16 + href: 2023/boards/sprint-230-update.md + - name: October 4 + href: 2023/boards/sprint-228-update.md + - name: September 14 + href: 2023/boards/sprint-227-update.md + - name: August 2 + href: 2023/boards/sprint-225-update.md + - name: July 11 + href: 2023/boards/sprint-224-update.md - name: June 6 href: 2023/boards/sprint-222-update.md - name: May 9 @@ -238,7 +344,7 @@ href: 2023/boards/sprint-215-update.md - name: January 12 href: 2023/boards/sprint-214-update.md - expanded: true + expanded: false - name: "2022" items: - name: December 8 @@ -336,6 +442,39 @@ href: 2019/boards/sprint-146-update.md - name: Azure Repos items: + - name: "2025" + items: + - name: April 3 + href: 2025/repos/sprint-254-update.md + - name: January 17 + href: 2025/repos/sprint-248-update.md + expanded: false + - name: "2024" + items: + - name: November 13 + href: 2024/repos/sprint-247-update.md + - name: October 16 + href: 2024/repos/sprint-246-update.md + - name: September 26 + href: 2024/repos/sprint-245-update.md + - name: September 4 + href: 2024/repos/sprint-244-update.md + - name: June 14 + href: 2024/repos/sprint-240-update.md + - name: February 29 + href: 2024/repos/sprint-235-update.md + - name: February 9 + href: 2024/repos/sprint-234-update.md + expanded: false + - name: "2023" + items: + - name: September 14 + href: 2023/repos/sprint-227-update.md + - name: August 23 + href: 2023/repos/sprint-226-update.md + - name: July 11 + href: 2023/repos/sprint-224-update.md + expanded: false - name: "2021" items: - name: September 8 @@ -393,8 +532,68 @@ expanded: false - name: Azure Pipelines items: + - name: "2025" + items: + - name: April 3 + href: 2025/pipelines/sprint-254-update.md + - name: March 20 + href: 2025/pipelines/sprint-253-update.md + - name: February 24 + href: 2025/pipelines/sprint-252-update.md + - name: February 12 + href: 2025/pipelines/sprint-251-update.md + - name: January 17 + href: 2025/pipelines/sprint-248-update.md + expanded: false + - name: "2024" + items: + - name: November 13 + href: 2024/pipelines/sprint-247-update.md + - name: October 16 + href: 2024/pipelines/sprint-246-update.md + - name: September 26 + href: 2024/pipelines/sprint-245-update.md + - name: September 4 + href: 2024/pipelines/sprint-244-update.md + - name: August 13 + href: 2024/pipelines/sprint-243-update.md + - name: July 25 + href: 2024/pipelines/sprint-242-update.md + - name: July 3 + href: 2024/pipelines/sprint-241-update.md + - name: June 14 + href: 2024/pipelines/sprint-240-update.md + - name: May 2 + href: 2024/pipelines/sprint-238-update.md + - name: April 10 + href: 2024/pipelines/sprint-237-update.md + - name: March 26 + href: 2024/pipelines/sprint-236-update.md + - name: February 29 + href: 2024/pipelines/sprint-235-update.md + - name: February 9 + href: 2024/pipelines/sprint-234-update.md + - name: January 18 + href: 2024/pipelines/sprint-233-update.md + expanded: false - name: "2023" items: + - name: December 5 + href: 2023/pipelines/sprint-231-update.md + - name: November 16 + href: 2023/pipelines/sprint-230-update.md + - name: October 26 + href: 2023/pipelines/sprint-229-update.md + - name: October 4 + href: 2023/pipelines/sprint-228-update.md + - name: September 14 + href: 2023/pipelines/sprint-227-update.md + - name: August 23 + href: 2023/pipelines/sprint-226-update.md + - name: August 2 + href: 2023/pipelines/sprint-225-update.md + - name: July 11 + href: 2023/pipelines/sprint-224-update.md - name: June 21 href: 2023/pipelines/sprint-223-update.md - name: June 6 @@ -559,6 +758,32 @@ expanded: false - name: Azure Test Plans items: + - name: "2025" + items: + - name: April 3 + href: 2025/testplans/sprint-254-update.md + - name: March 20 + href: 2025/testplans/sprint-253-update.md + - name: February 24 + href: 2025/testplans/sprint-252-update.md + - name: February 12 + href: 2025/testplans/sprint-251-update.md + - name: January 17 + href: 2025/testplans/sprint-248-update.md + expanded: false + - name: "2024" + items: + - name: November 13 + href: 2024/testplans/sprint-247-update.md + - name: September 26 + href: 2024/testplans/sprint-245-update.md + - name: June 14 + href: 2024/testplans/sprint-240-update.md + - name: February 29 + href: 2024/testplans/sprint-235-update.md + - name: January 11 + href: 2024/testplans/sprint-232-update.md + expanded: false - name: "2020" items: - name: November 12 @@ -578,6 +803,20 @@ expanded: false - name: Azure Artifacts items: + - name: "2024" + items: + - name: October 16 + href: 2024/artifacts/sprint-246-update.md + - name: February 9 + href: 2024/artifacts/sprint-234-update.md + expanded: false + - name: "2023" + items: + - name: October 26 + href: 2023/artifacts/sprint-229-update.md + - name: August 23 + href: 2023/artifacts/sprint-226-update.md + expanded: false - name: "2022" items: - name: October 4 @@ -635,10 +874,95 @@ href: 2019/artifacts/sprint-146-update.md expanded: false expanded: false + - name: GitHub Advanced Security for Azure DevOps + items: + - name: "2025" + items: + - name: March 20 + href: 2025/ghazdo/sprint-253-update.md + - name: February 24 + href: 2025/ghazdo/sprint-252-update.md + - name: February 12 + href: 2025/ghazdo/sprint-251-update.md + - name: January 17 + href: 2025/ghazdo/sprint-248-update.md + expanded: false + - name: "2024" + items: + - name: November 13 + href: 2024/ghazdo/sprint-247-update.md + - name: October 15 + href: 2024/ghazdo/sprint-246-update.md + - name: September 26 + href: 2024/ghazdo/sprint-245-update.md + - name: September 4 + href: 2024/ghazdo/sprint-244-update.md + - name: August 13 + href: 2024/ghazdo/sprint-243-update.md + - name: July 3 + href: 2024/ghazdo/sprint-241-update.md + - name: June 14 + href: 2024/ghazdo/sprint-240-update.md + - name: May 2 + href: 2024/ghazdo/sprint-238-update.md + - name: April 10 + href: 2024/ghazdo/sprint-237-update.md + - name: February 9 + href: 2024/ghazdo/sprint-234-update.md + - name: January 18 + href: 2024/ghazdo/sprint-233-update.md + expanded: false + - name: "2023" + items: + - name: October 26 + href: 2023/ghazdo/sprint-229-update.md + - name: October 4 + href: 2023/ghazdo/sprint-228-update.md + - name: July 11 + href: 2023/ghazdo/sprint-224-update.md + - name: June 6 + href: 2023/ghazdo/sprint-222-update.md + expanded: false - name: General items: + - name: "2025" + items: + - name: April 3 + href: 2025/general/sprint-254-update.md + - name: March 20 + href: 2025/general/sprint-253-update.md + - name: February 24 + href: 2025/general/sprint-252-update.md + - name: February 12 + href: 2025/general/sprint-251-update.md + expanded: true + - name: "2024" + items: + - name: October 16 + href: 2024/general/sprint-246-update.md + - name: July 3 + href: 2024/general/sprint-241-update.md + - name: May 2 + href: 2024/general/sprint-238-update.md + - name: March 26 + href: 2024/general/sprint-236-update.md + - name: February 9 + href: 2024/general/sprint-234-update.md + - name: January 18 + href: 2024/general/sprint-233-update.md + - name: January 11 + href: 2024/general/sprint-232-update.md + expanded: false - name: "2023" items: + - name: November 16 + href: 2023/general/sprint-230-update.md + - name: October 26 + href: 2023/general/sprint-229-update.md + - name: October 4 + href: 2023/general/sprint-228-update.md + - name: August 23 + href: 2023/general/sprint-226-update.md - name: June 21 href: 2023/general/sprint-223-update.md - name: June 6 @@ -649,7 +973,7 @@ href: 2023/general/sprint-217-update.md - name: January 12 href: 2023/general/sprint-214-update.md - expanded: true + expanded: false - name: "2022" items: - name: October 11 @@ -731,8 +1055,20 @@ expanded: false - name: Reporting items: + - name: "2025" + items: + expanded: true + - name: "2024" + items: + - name: September 4 + href: 2024/reporting/sprint-244-update.md + expanded: false - name: "2023" items: + - name: November 16 + href: 2023/reporting/sprint-230-update.md + - name: October 26 + href: 2023/reporting/sprint-229-update.md - name: June 21 href: 2023/reporting/sprint-223-update.md - name: May 9 @@ -745,7 +1081,7 @@ href: 2023/reporting/sprint-217-update.md - name: February 7 href: 2023/reporting/sprint-216-update.md - expanded: true + expanded: false - name: "2022" items: - name: October 11 @@ -782,6 +1118,14 @@ expanded: false - name: Wiki items: + - name: "2025" + items: + expanded: false + - name: "2024" + items: + - name: October 16 + href: 2024/wiki/sprint-246-update.md + expanded: false - name: "2023" items: - name: January 23 @@ -821,14 +1165,4 @@ - name: Azure DevOps Server href: /azure/devops/server/release-notes/azuredevops2020 - name: Documentation updates - items: - - name: What's new - href: docswhatsnew/index.yml - - name: May 2023 - href: docswhatsnew/azure-devops-docs-whats-new.md - - name: April 2023 - href: docswhatsnew/azure-devops-docs-2023-04.md - - name: March 2023 - href: docswhatsnew/azure-devops-docs-2023-03.md -- name: Subscribe to updates - href: https://azure.microsoft.com/updates/?product=azure-devops + href: ./docswhatsnew/toc.yml diff --git a/release-notes/breadcrumb/toc.yml b/release-notes/breadcrumb/toc.yml index c9a4e7ec7e9..dca942c9464 100644 --- a/release-notes/breadcrumb/toc.yml +++ b/release-notes/breadcrumb/toc.yml @@ -1,7 +1,7 @@ -- name: Azure DevOps - tocHref: /azure/devops/ - topicHref: /azure/devops/index - items: - - name: Release Notes - tocHref: /azure/devops/release-notes/ - topicHref: https://aka.ms/azuredevops/releasenotes \ No newline at end of file +- name: Azure + tocHref: /azure/ + topicHref: /azure/index + items: + - name: Azure DevOps + tocHref: /azure/devops/ + topicHref: /azure/devops/index diff --git a/release-notes/docfx.json b/release-notes/docfx.json index 628245447db..f98e28084b8 100644 --- a/release-notes/docfx.json +++ b/release-notes/docfx.json @@ -34,11 +34,11 @@ "overwrite": [], "externalReference": [], "globalMetadata": { + "feedback_system": "Standard", "ms.subservice": "azure-devops-release-notes", "uhfHeaderId": "MSDocsHeader-AzureDevOps", "ms.topic": "article", "breadcrumb_path": "~/breadcrumb/toc.yml", - "extendBreadcrumb": true, "author": "gloridelmorales", "ms.author": "glmorale", "ms.manager": "mijacobs", diff --git a/release-notes/docswhatsnew/azure-devops-docs-2023-03.md b/release-notes/docswhatsnew/azure-devops-docs-2023-03.md deleted file mode 100644 index 6ff6ea2da17..00000000000 --- a/release-notes/docswhatsnew/azure-devops-docs-2023-03.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Azure DevOps docs: What's new for March 1, 2023 - March 31, 2023" -description: "What's new in the Azure DevOps docs for March 1, 2023 - March 31, 2023." -ms.date: 04/04/2023 ---- - -# Azure DevOps docs: What's new for March 1, 2023 - March 31, 2023 - -Welcome to what's new in the Azure DevOps docs from March 1, 2023 through March 31, 2023. This article lists some of the major changes to docs during this period. - -## Artifacts - -### Updated articles - -- [Share packages publicly](/azure/devops/artifacts/tutorials/share-packages-publicly) - -## Boards - -### Updated articles - -- [Best practices for Agile project management](/azure/devops/boards/best-practices-agile-project-management) -- [Manage columns on your Kanban board](/azure/devops/boards/boards/add-columns) -- [Customize cards on a Kanban board](/azure/devops/boards/boards/customize-cards) -- [Configure and customize Azure Boards](/azure/devops/boards/configure-customize) -- [Azure Boards FAQs](/azure/devops/boards/faqs) -- [Plan and track work in Azure Boards](/azure/devops/boards/get-started/plan-track-work) -- [Sign up for Azure Boards](/azure/devops/boards/get-started/sign-up-invite-teammates) -- [What is Azure Boards?](/azure/devops/boards/get-started/what-is-azure-boards) -- [Customize Azure Boards to support SAFe® practices](/azure/devops/boards/plans/safe-customize) - -## Integrate - -### New articles - -- [Use Azure AD service principals & managed identities](/azure/devops/integrate/get-started/authentication/service-principal-managed-identity) - -## Organizations - -### Updated articles - -- [Get started with permissions, access, and security groups](/azure/devops/organizations/security/about-permissions) -- [About security, authentication, and authorization](/azure/devops/organizations/security/about-security-identity) -- [Allowed IP addresses and domain URLs](/azure/devops/organizations/security/allow-list-ip-url) -- [Security best practices](/azure/devops/organizations/security/security-best-practices) -- [Naming restrictions and conventions](/azure/devops/organizations/settings/naming-restrictions) - -## Pipelines - -### New articles - -- [Set up MLOps with Azure DevOps](/azure/machine-learning/how-to-setup-mlops-azureml) - -### Updated articles - -- [Use Azure Pipelines with Slack](/azure/devops/pipelines/integrations/slack) -- [Migrate from Travis to Azure Pipelines](/azure/devops/pipelines/migrate/from-travis) -- [Restore NuGet packages with Azure Pipelines](/azure/devops/pipelines/packages/nuget-restore) -- [Set variables in scripts](/azure/devops/pipelines/process/set-variables-scripts) - - -## User guide - -### Updated articles - -- [Get started managing your organization or project collection](/azure/devops/user-guide/manage-organization-collection) - -## GitHub issue content updates - -Thank you for your feedback on our documentation. This month we made updates to our content to address [these GitHub issues](https://github.com/MicrosoftDocs/azure-devops-docs/issues?q=linked%3Apr+is%3Aissue+is%3Aclosed+closed%3A2023-03-01..2023-03-31). - -## Community contributors - -The following people contributed to the Azure DevOps docs during this period. Thank you! Learn how to contribute by following the links under "Get involved" in the [what's new landing page](index.yml). - -- [AdrianSanguineti](https://github.com/AdrianSanguineti) - Adrian Sanguineti (1) -- [akanieski](https://github.com/akanieski) - Andrew Kanieski (1) -- [beniaju2](https://github.com/beniaju2) (1) -- [bjompen](https://github.com/bjompen) - Björn Sundling (1) -- [derek-wade](https://github.com/derek-wade) - Derek (1) -- [ethanknights](https://github.com/ethanknights) - Ethan Knights (1) -- [fajterini](https://github.com/fajterini) - Michal F (1) -- [incarnate](https://github.com/incarnate) - John C (1) -- [JMCARY](https://github.com/JMCARY) - John Cary (1) -- [kek-Sec](https://github.com/kek-Sec) - G. Petrakis (1) -- [Michael-Coetzee](https://github.com/Michael-Coetzee) - Michael Coetzee (1) diff --git a/release-notes/docswhatsnew/azure-devops-docs-2023-04.md b/release-notes/docswhatsnew/azure-devops-docs-2023-04.md deleted file mode 100644 index e5f1d540889..00000000000 --- a/release-notes/docswhatsnew/azure-devops-docs-2023-04.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "Azure DevOps docs: What's new for April 1, 2023 - April 30, 2023" -description: "What's new in the Azure DevOps docs for April 1, 2023 - April 30, 2023." -ms.date: 05/16/2023 ---- - -# Azure DevOps docs: What's new for April 1, 2023 - April 30, 2023 - -Welcome to what's new in the Azure DevOps docs from April 1, 2023 through April 30, 2023. This article lists some of the major changes to docs during this period. - -## Administration - -### Updated articles - -- [Manage notifications for a team, project, or organization](/azure/devops/organizations/notifications/manage-team-group-global-organization-notifications) -- [Get started as a Stakeholder](/azure/devops/organizations/security/get-started-stakeholder) -- [Select backlog navigation levels for your team](/azure/devops/organizations/settings/select-backlog-navigation-levels) - -## Artifacts - -### Updated articles - -- [Publish and consume Python packages using the command line](/azure/devops/artifacts/quickstarts/python-cli) -- [Artifacts storage consumption](/azure/devops/artifacts/artifact-storage) -- [Azure Artifacts: best practices](/azure/devops/artifacts/concepts/best-practices) -- [Set up your project and connect to Azure Artifacts](/azure/devops/artifacts/npm/npmrc) - -## Azure Boards - -### Updated articles - -- [Import or update work items in bulk with CSV files](/azure/devops/boards/queries/import-work-items-from-csv) -- [About work items and work item types](/azure/devops/boards/work-items/about-work-items) - -## Azure Pipelines - -### Updated articles - -- [Logging commands](/azure/devops/pipelines/scripts/logging-commands) -- [Azure SQL database deployment](/azure/devops/pipelines/targets/azure-sqldb) -- [Quickstart - Use Azure Pipelines to build and publish a Node.js package](/azure/devops/pipelines/ecosystems/javascript) -- [Define resources in YAML](/azure/devops/pipelines/process/resources) -- [Create and target an environment](/azure/devops/pipelines/process/environments) -- [Self-hosted Windows agents](/azure/devops/pipelines/agents/v2-windows-agent) - -## Integrate - -### Updated articles - -- [Use Azure Active Directory service principals & managed identities](/azure/devops/integrate/get-started/authentication/service-principal-managed-identity) - -## GitHub issue content updates - -Thank you for your feedback on our documentation. This month we made updates to our content to address [these GitHub issues](https://github.com/MicrosoftDocs/azure-devops-docs/issues?q=linked%3Apr+is%3Aissue+is%3Aclosed+closed%3A2023-04-01..2023-04-30). - -## Community contributors - -The following people contributed to the Azure DevOps docs during this period. Thank you! Learn how to contribute by following the links under "Get involved" in the [what's new landing page](index.yml). - -- [ethanknights](https://github.com/ethanknights) - Ethan Knights (2) -- [bjompen](https://github.com/bjompen) - Björn Sundling (1) -- [brunomartinspro](https://github.com/brunomartinspro) - Bruno Martins (1) -- [fimmicon](https://github.com/fimmicon) - Efim (1) -- [frodera](https://github.com/frodera) - frodera (1) -- [michha](https://github.com/michha) - Michael (1) -- [SebastianSchuetze](https://github.com/SebastianSchuetze) - Sebastian Schütze (1) -- [synelnykova](https://github.com/synelnykova) - Olga Synelnykova (1) -- [teesana](https://github.com/teesana) (1) -- [thomash0815](https://github.com/thomash0815) (1) diff --git a/release-notes/docswhatsnew/azure-devops-docs-2025-01.md b/release-notes/docswhatsnew/azure-devops-docs-2025-01.md new file mode 100644 index 00000000000..071837ce02d --- /dev/null +++ b/release-notes/docswhatsnew/azure-devops-docs-2025-01.md @@ -0,0 +1,135 @@ +--- +title: "Azure DevOps docs: What's new for January 1, 2025 - January 31, 2025" +description: "What's new in the Azure DevOps docs for January 1, 2025 - January 31, 2025." +ms.date: 02/04/2025 +--- + +# Azure DevOps docs: What's new for January 1, 2025 - January 31, 2025 + +Welcome to what's new in the Azure DevOps docs from January 1, 2025 through January 31, 2025. This article lists some of the major changes to docs during this period. + +## Administration + +### Updated articles + +- [Allowed IP addresses and domain URLs](/azure/devops/organizations/security/allow-list-ip-url) +- [Rename or remove a team](/azure/devops/organizations/settings/rename-remove-team) +- [User and permissions management FAQs](/azure/devops/organizations/accounts/faq-user-and-permissions-management) +- [Organization FAQs](/azure/devops/organizations/accounts/faq-configure-customize-organization) +- [Work tracking, process, and project limits](/azure/devops/organizations/settings/work/object-limits) +- [Use personal access tokens](/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) +- [Security best practices](/azure/devops/organizations/security/security-best-practices) + +## Artifacts + +### New articles + +- [Connect your Python project to an Azure Artifacts feed](/azure/devops/artifacts/python/project-setup-python) +- [Connect to an Azure Artifacts feed - Universal Packages](/azure/devops/artifacts/universal-packages/project-setup-universal-packages) +- [Connect your Cargo project to an Azure Artifacts feed](/azure/devops/artifacts/cargo/project-setup-cargo) +- [Download Universal Packages from Azure Artifacts feeds](/azure/devops/artifacts/quickstarts/download-universal-packages) +- [Install Python packages (CLI)](/azure/devops/artifacts/quickstarts/install-python-packages) +- [Restore NuGet packages from the command line (NuGet.exe)](/azure/devops/artifacts/nuget/restore-nuget-packages-nuget-exe) +- [Restore NuGet packages from the command line (dotnet)](/azure/devops/artifacts/nuget/restore-nuget-packages-dotnet) + +### Updated articles + +- [Publish Universal Packages from Azure Artifacts feeds](/azure/devops/artifacts/quickstarts/universal-packages) +- [Publish Python packages (CLI)](/azure/devops/artifacts/quickstarts/python-cli) +- [Publish NuGet packages from the command line (NuGet.exe)](/azure/devops/artifacts/nuget/publish) +- [Publish NuGet packages from the command line (dotnet)](/azure/devops/artifacts/nuget/dotnet-exe) +- [What is Azure Artifacts?](/azure/devops/artifacts/start-using-azure-artifacts) + +## Azure Boards + +### Updated articles + +- [Link work items to objects](/azure/devops/boards/backlogs/add-link) +- [Drive Git development from a work item in Azure Boards](/azure/devops/boards/backlogs/connect-work-items-to-git-dev-ops) +- [Display rollup progress or totals in Azure Boards](/azure/devops/boards/backlogs/display-rollup) +- [Add or modify work items in bulk with Microsoft Excel](/azure/devops/boards/backlogs/office/bulk-add-modify-work-items-excel) +- [Add, run, and update inline tests](/azure/devops/boards/boards/add-run-update-tests) +- [Customize cards on a board](/azure/devops/boards/boards/customize-cards) +- [Plan and track work in Azure Boards](/azure/devops/boards/get-started/plan-track-work) +- [Move work items from one team to another team](/azure/devops/boards/work-items/move-work-items) +- [Connect Azure DevOps Server to GitHub (on-premises)](/azure/devops/boards/github/connect-on-premises-to-github) +- [About migrating and integrating work tracking data](/azure/devops/boards/extensions/migrate-integrate) + +## Azure DevOps Reporting and Analytics service + +### Updated articles + +- [Add Markdown to a dashboard](/azure/devops/report/dashboards/add-markdown-to-dashboard) + +## Azure Pipelines + +### New articles + +- [Build a pipeline with stages](/azure/devops/pipelines/process/run-stages) + +### Updated articles + +- [CI/CD baseline architecture with Azure Pipelines](/azure/devops/pipelines/architectures/devops-pipelines-baseline-architecture) +- [Deployment jobs](/azure/devops/pipelines/process/deployment-jobs) +- [Azure Pipelines agents](/azure/devops/pipelines/agents/agents) +- [Quickstart: Use an ARM template to deploy a Linux web app to Azure](/azure/devops/pipelines/apps/cd/azure/deploy-arm-template) +- [Tutorial: Create a multistage pipeline with Azure DevOps](/azure/devops/pipelines/process/create-multistage-pipeline) +- [Expressions](/azure/devops/pipelines/process/expressions) +- [Microsoft-hosted agents](/azure/devops/pipelines/agents/hosted) +- [Clone or import a pipeline](/azure/devops/pipelines/get-started/clone-import-pipeline) +- [Set variables in scripts](/azure/devops/pipelines/process/set-variables-scripts) +- [Specify jobs in your pipeline](/azure/devops/pipelines/process/phases) +- [Pipeline caching](/azure/devops/pipelines/release/caching) +- [Troubleshoot Azure Resource Manager service connections](/azure/devops/pipelines/release/azure-rm-endpoint) +- [Template usage reference](/azure/devops/pipelines/process/templates) +- [Check out multiple repositories in your pipeline](/azure/devops/pipelines/repos/multi-repo-checkout) +- [Run a self-hosted agent in Docker](/azure/devops/pipelines/agents/docker) +- [Use Azure Pipelines to build and push container images to registries](/azure/devops/pipelines/ecosystems/containers/push-image) + +## CLI + +### Updated articles + +- [Azure DevOps CLI service endpoint](/azure/devops/cli/service-endpoint) + +## Integrate + +### Updated articles + +- [Authenticate to Azure DevOps with Microsoft Entra](/azure/devops/integrate/get-started/authentication/entra) +- [Build Azure DevOps integrations with Microsoft Entra OAuth apps](/azure/devops/integrate/get-started/authentication/entra-oauth) +- [Use service principals & managed identities in Azure DevOps](/azure/devops/integrate/get-started/authentication/service-principal-managed-identity) +- [Choose the right authentication mechanism](/azure/devops/integrate/get-started/authentication/authentication-guidance) +- [Integrate applications](/azure/devops/integrate/index) + +## Migrate + +### Updated articles + +- [Do test run migration](/azure/devops/migrate/migration-test-run) +- [Migration overview](/azure/devops/migrate/migration-overview) + +## Project + +### Updated articles + +- [Filter lists, boards, and directories](/azure/devops/project/navigation/filter-basics) +- [Open a service, page, or settings](/azure/devops/project/navigation/go-to-service-page) +- [View and update work items via mobile browser](/azure/devops/project/navigation/mobile-work) +- [Set personal or team favorites](/azure/devops/project/navigation/set-favorites) +- [Work across projects](/azure/devops/project/navigation/work-across-projects) +- [Functional code search](/azure/devops/project/search/functional-code-search) +- [Publish a Git repo to a wiki](/azure/devops/project/wiki/publish-repo-to-wiki) + +## Service-hooks + +### Updated articles + +- [Service hook consumers](/azure/devops/service-hooks/consumers) + +## User guide + +### New articles + +- [Capture a browser trace for troubleshooting](/azure/devops/user-guide/capture-browser-trace) + diff --git a/release-notes/docswhatsnew/azure-devops-docs-2025-02.md b/release-notes/docswhatsnew/azure-devops-docs-2025-02.md new file mode 100644 index 00000000000..c2f69f25887 --- /dev/null +++ b/release-notes/docswhatsnew/azure-devops-docs-2025-02.md @@ -0,0 +1,141 @@ +--- +title: "Azure DevOps docs: What's new for February 1, 2025 - February 28, 2025" +description: "What's new in the Azure DevOps docs for February 1, 2025 - February 28, 2025." +ms.date: 03/24/2025 +--- + +# Azure DevOps docs: What's new for February 1, 2025 - February 28, 2025 + +Welcome to what's new in the Azure DevOps docs from February 1, 2025 through February 28, 2025. This article lists some of the major changes to docs during this period. + +## Administration + +### Updated articles + +- [Secure your Azure DevOps](/azure/devops/organizations/security/security-overview) +- [Rename a project in Azure DevOps](/azure/devops/organizations/projects/rename-project) +- [Allowed IP addresses and domain URLs](/azure/devops/organizations/security/allow-list-ip-url) +- [Resolve validation errors for process import](/azure/devops/organizations/settings/work/import-process/resolve-errors) +- [User and permissions management FAQs](/azure/devops/organizations/accounts/faq-user-and-permissions-management) +- [Manage paid access for users](/azure/devops/organizations/billing/buy-basic-access-add-users) +- [Get started as a Stakeholder](/azure/devops/organizations/security/get-started-stakeholder) +- [Set permissions and access for testing](/azure/devops/organizations/security/set-permissions-access-test) +- [Set work tracking permissions](/azure/devops/organizations/security/set-permissions-access-work-tracking) +- [Create or add a team](/azure/devops/organizations/settings/add-teams) +- [Add and manage information banners in Azure Devops](/azure/devops/organizations/settings/manage-banners) +- [Manage and configure team tools](/azure/devops/organizations/settings/manage-teams) +- [Rename or remove a team](/azure/devops/organizations/settings/rename-remove-team) +- [Manage access to specific features](/azure/devops/organizations/security/restrict-access) +- [Exclude yourself from notification emails of events you started](/azure/devops/organizations/notifications/exclude-self-from-email) +- [Not getting emails from subscriptions or notifications](/azure/devops/organizations/notifications/troubleshoot-not-getting-email) +- [Analyze organization-level notifications statistics](/azure/devops/organizations/notifications/view-organization-notification-statistics) + +## Artifacts + +### New articles + +- [Restore npm packages from the command line](/azure/devops/artifacts/npm/restore-npm-packages) + +### Updated articles + +- [Publish npm packages from the command line](/azure/devops/artifacts/npm/publish) +- [Promote packages and manage feed views](/azure/devops/artifacts/feeds/views) +- [Manage permissions](/azure/devops/artifacts/feeds/feed-permissions) +- [Azure Artifacts key concepts](/azure/devops/artifacts/artifacts-key-concepts) +- [Azure Artifacts documentation](/azure/devops/artifacts/index) + +## Azure Boards + +### Updated articles + +- [Manage work item attachments](/azure/devops/boards/work-items/manage-attachments) +- [About migrating and integrating work tracking data](/azure/devops/boards/extensions/migrate-integrate) +- [Connect Azure Boards to GitHub (cloud)](/azure/devops/boards/github/connect-to-github) +- [Resolve Azure DevOps and Office integration issues](/azure/devops/boards/backlogs/office/tfs-office-integration-issues) + +## Azure DevOps Reporting and Analytics service + +### Updated articles + +- [Add charts to a dashboard](/azure/devops/report/dashboards/add-charts-to-dashboard) +- [Install or enable the Analytics service](/azure/devops/report/dashboards/analytics-extension) +- [Widgets based on Analytics data](/azure/devops/report/dashboards/analytics-widgets) +- [Track progress with status and trend query-based charts](/azure/devops/report/dashboards/charts) +- [Configure a chart for work items widget](/azure/devops/report/dashboards/configure-chart-work-items-widget) +- [Configure the Test Results Trend (Advanced) widget](/azure/devops/report/dashboards/configure-test-results-trend) +- [Out Of Box widget catalog](/azure/devops/report/dashboards/widget-catalog) +- [Project and organization-scoped queries](/azure/devops/report/extend-analytics/account-scoped-queries) +- [Query trend data](/azure/devops/report/extend-analytics/querying-for-trend-data) +- [Create a Power BI report with an OData Query](/azure/devops/report/powerbi/create-quick-report-odataq) +- [Create a Power BI report with a default Analytics view](/azure/devops/report/powerbi/create-quick-report) +- [Connect Analytics with Power BI Data Connector](/azure/devops/report/powerbi/data-connector-connect) + +## Azure Pipelines + +### New articles + +- [Build and publish pipeline artifacts with Gradle and Azure Pipelines](/azure/devops/pipelines/artifacts/build-publish-artifacts-gradle) +- [Restore Maven packages with Azure Pipelines (YAML/Classic)](/azure/devops/pipelines/packages/maven-restore) + +### Updated articles + +- [Deploy pull request Artifacts with classic release pipelines](/azure/devops/pipelines/release/deploy-pull-request-builds) +- [Publish and download Universal Packages with Azure Pipelines](/azure/devops/pipelines/artifacts/universal-packages) +- [Configure schedules for pipelines](/azure/devops/pipelines/process/scheduled-triggers) +- [Use YAML templates in pipelines for reusable and secure processes](/azure/devops/pipelines/process/templates) +- [Build a YAML pipeline with stages](/azure/devops/pipelines/process/run-stages) +- [Logging commands](/azure/devops/pipelines/scripts/logging-commands) +- [Build, test, and deploy Android apps](/azure/devops/pipelines/ecosystems/android) +- [Expressions](/azure/devops/pipelines/process/expressions) + +## Azure Repos + +### New articles + +- [Go install command support in Azure Repos Git](/azure/devops/repos/git/go-install) + +### Updated articles + +- [Set branch permissions](/azure/devops/repos/git/branch-permissions) +- [Create a new Git repo in your project](/azure/devops/repos/git/create-new-repo) +- [Use Azure Functions to create custom branch policies](/azure/devops/repos/git/create-pr-status-server-with-azure-functions) +- [Use the Azure DevOps plugin for IntelliJ IDEA and Android Studio](/azure/devops/repos/git/create-repo-intellij) +- [Git workflow](/azure/devops/repos/git/gitworkflow) +- [Ignore file changes with Git](/azure/devops/repos/git/ignore-files) +- [Import and migrate repositories from TFVC to Git](/azure/devops/repos/git/import-from-tfvc) +- [Import a Git repo](/azure/devops/repos/git/import-git-repository) +- [Manage branches](/azure/devops/repos/git/manage-your-branches) +- [Merge strategies and squash merge](/azure/devops/repos/git/merging-with-squash) +- [Create pull requests](/azure/devops/repos/git/pull-requests) +- [Restore a deleted Git branch from the web portal](/azure/devops/repos/git/restore-deleted-branch) +- [Configure GitHub Advanced Security for Azure DevOps](/azure/devops/repos/security/configure-github-advanced-security-features) +- [Set up secret scanning](/azure/devops/repos/security/github-advanced-security-secret-scanning) +- [Create a pull request status server with Node.js](/azure/devops/repos/git/create-pr-status-server) + +## Azure Test Plans + +### Updated articles + +- [Manual test access and permissions](/azure/devops/test/manual-test-permissions) +- [Progress Report](/azure/devops/test/progress-report) + +## Managed DevOps Pools + +### Updated articles + +- [Configure Managed DevOps Pools images](/azure/devops/managed-devops-pools/configure-images) +- [Troubleshoot Managed DevOps Pools issues](/azure/devops/managed-devops-pools/troubleshooting) + +## Service-hooks + +### Updated articles + +- [Azure DevOps integration with Microsoft Teams](/azure/devops/service-hooks/services/teams) + +## User guide + +### Updated articles + +- [Get support and provide feedback](/azure/devops/user-guide/provide-feedback) +- [Manage your organization or collection](/azure/devops/user-guide/manage-organization-collection) + diff --git a/release-notes/docswhatsnew/azure-devops-docs-whats-new.md b/release-notes/docswhatsnew/azure-devops-docs-whats-new.md index 5d76cbb29ef..b4136a1e933 100644 --- a/release-notes/docswhatsnew/azure-devops-docs-whats-new.md +++ b/release-notes/docswhatsnew/azure-devops-docs-whats-new.md @@ -1,123 +1,127 @@ --- -title: "Azure DevOps docs: What's new for May 1, 2023 - May 31, 2023" -description: "What's new in the Azure DevOps docs for May 1, 2023 - May 31, 2023." -ms.date: 06/01/2023 +title: "Azure DevOps docs: What's new for March 2025" +description: "What's new in the Azure DevOps docs for March 2025." +ms.custom: March-2025 +ms.date: 04/11/2025 --- -# Azure DevOps docs: What's new for May 1, 2023 - May 31, 2023 +# Azure DevOps docs: What's new for March 2025 -Welcome to what's new in the Azure DevOps docs from May 1, 2023 through May 31, 2023. This article lists some of the major changes to docs during this period. - -## Administration - -### Updated articles - -- [Default permissions quick reference for Azure DevOps](/azure/devops/organizations/security/permissions-access) -- [Set work tracking permissions](/azure/devops/organizations/security/set-permissions-access-work-tracking) +Welcome to what's new in the Azure DevOps docs for March 2025. This article lists some of the major changes to docs during this period. ## Artifacts ### New articles -- [Publish Maven artifacts using Gradle](/azure/devops/artifacts/maven/publish-with-gradle) +- [Install NuGet packages with Visual Studio](/azure/devops/artifacts/nuget/install-nuget-packages-with-visual-studio) +- [Publish Cargo packages from the command line](/azure/devops/artifacts/cargo/cargo-publish) ### Updated articles -- [Accelerate collaboration and Agile development with componentization](/azure/devops/artifacts/collaborate-with-packages) -- [Publish and download universal packages in Azure Artifacts](/azure/devops/artifacts/quickstarts/universal-packages) -- [Migrate your packages from file shares](/azure/devops/artifacts/nuget/move-from-fileshares) +- [Azure Artifacts best practices](/azure/devops/artifacts/concepts/best-practices) +- [Connect your npm project to Azure Artifacts](/azure/devops/artifacts/npm/npmrc) +- [Delete and recover packages](/azure/devops/artifacts/how-to/delete-and-recover-packages) +- [Get started with Cargo packages in Azure Artifacts](/azure/devops/artifacts/get-started-cargo) +- [What are upstream sources?](/azure/devops/artifacts/concepts/upstream-sources) ## Azure Boards ### Updated articles -- [About Kanban boards](/azure/devops/boards/boards/kanban-overview) -- [Use your Kanban board](/azure/devops/boards/boards/kanban-quickstart) -- [Manage columns on your Kanban board](/azure/devops/boards/boards/add-columns) -- [Customize cards on a Kanban board](/azure/devops/boards/boards/customize-cards) -- [Work in Excel connected to Azure Boards FAQs](/azure/devops/boards/backlogs/office/faqs) -- [Import or update work items in bulk with CSV files](/azure/devops/boards/queries/import-work-items-from-csv) -- [Expedite work using swimlanes](/azure/devops/boards/boards/expedite-work) -- [About default processes and process templates](/azure/devops/boards/work-items/guidance/choose-process) +- [About migrating and integrating work tracking data](/azure/devops/boards/extensions/migrate-integrate) +- [FAQs about working in Excel connected to Azure Boards](/azure/devops/boards/backlogs/office/faqs) +- [Install the Azure Boards app for GitHub](/azure/devops/boards/github/install-github-app) +- [Resolve Azure DevOps and Office integration issues](/azure/devops/boards/backlogs/office/tfs-office-integration-issues) +- [Sign up for Azure Boards](/azure/devops/boards/get-started/sign-up-invite-teammates) -## Azure DevOps Reporting and Analytics service +## Demo-gen + +### New articles + +- [Overview of Demo Generator](/azure/devops/demo-gen/configure) ### Updated articles -- [View and configure team velocity](/azure/devops/report/dashboards/team-velocity) +- [Get started creating and populating demo Azure DevOps Services projects](/azure/devops/demo-gen/use-demo-generator-v2) -## Azure Pipelines +## Extend -### New articles +### Updated articles -- [Publish NuGet packages to NuGet.org with Azure Pipelines](/azure/devops/pipelines/artifacts/publish-public-registry) -- [Self-hosted Linux agents](/azure/devops/pipelines/agents/linux-agent) -- [Self-hosted macOS agents](/azure/devops/pipelines/agents/osx-agent) -- [Self-hosted Windows agents](/azure/devops/pipelines/agents/windows-agent) -- [Azure Pipelines architecture for Azure Web Apps](/azure/devops/pipelines/architectures/devops-pipelines-azure-web-apps-architecture) -- [CI/CD baseline architecture with Azure Pipelines](/azure/devops/pipelines/architectures/devops-pipelines-baseline-architecture) -- [Azure Pipelines architecture with DevTest Labs](/azure/devops/pipelines/architectures/devops-pipelines-devtest-iaas-architecture) -- [Azure Pipelines architecture for IaaS](/azure/devops/pipelines/architectures/devops-pipelines-iaas-vms-architecture) +- [Add a custom pipelines task extension](/azure/devops/extend/develop/add-build-task) +- [Develop a web extension](/azure/devops/extend/get-started/node) +- [Extension manifest reference](/azure/devops/extend/develop/manifest) +- [Extensions overview](/azure/devops/extend/overview) +- [Package and publish extensions](/azure/devops/extend/publish/overview) + +## Integrate ### Updated articles -- [Use predefined variables](/azure/devops/pipelines/build/variables) -- [Logging commands](/azure/devops/pipelines/scripts/logging-commands) -- [Runtime parameters](/azure/devops/pipelines/process/runtime-parameters) -- [Template types & usage](/azure/devops/pipelines/process/templates) -- [Pipeline options for Git repositories](/azure/devops/pipelines/repos/pipeline-options-for-git) -- [Set variables in scripts](/azure/devops/pipelines/process/set-variables-scripts) -- [Publish and download Universal Packages with Azure Pipelines](/azure/devops/pipelines/artifacts/universal-packages) -- [Self-hosted Linux agents (2.x)](/azure/devops/pipelines/agents/v2-linux-agent) -- [Self-hosted macOS agents (2.x)](/azure/devops/pipelines/agents/v2-osx-agent) -- [Self-hosted Windows agents (2.x)](/azure/devops/pipelines/agents/v2-windows-agent) -- [Set retention policies for builds, releases, and tests](/azure/devops/pipelines/policies/retention) -- [Agent software version 3](/azure/devops/pipelines/agents/v3-agent) - -## Azure Repos +- [.NET client libraries](/azure/devops/integrate/concepts/dotnet-client-libraries) +- [Get started with the REST APIs](/azure/devops/integrate/how-to/call-rest-api) +- [Rate and usage limits](/azure/devops/integrate/concepts/rate-limits) +- [Use Azure DevOps OAuth 2.0 to create a web app](/azure/devops/integrate/get-started/authentication/azure-devops-oauth) -### New articles +## Marketplace + +### Updated articles -- [Configure GitHub Advanced Security for Azure DevOps](/azure/devops/repos/security/configure-github-advanced-security-features) - New feature -- [Advanced Security billing](/azure/devops/repos/security/github-advanced-security-billing) -- [Code scanning](/azure/devops/repos/security/github-advanced-security-code-scanning) -- [Dependency scanning](/azure/devops/repos/security/github-advanced-security-dependency-scanning) -- [Advanced Security permissions](/azure/devops/repos/security/github-advanced-security-permissions) -- [Secret scanning](/azure/devops/repos/security/github-advanced-security-secret-scanning) +- [Install extensions](/azure/devops/marketplace/install-extension) +- [Manage extension permissions](/azure/devops/marketplace/grant-permissions) +- [Request and approve extensions](/azure/devops/marketplace/request-extensions) + +## Administration ### Updated articles -- [Use Azure Repos with Microsoft Teams](/azure/devops/repos/integrations/repos-teams) -- [Branch policies and settings](/azure/devops/repos/git/branch-policies) +- [About projects and scaling your organization](/azure/devops/organizations/projects/about-projects) +- [Add organization users and manage access](/azure/devops/organizations/accounts/add-organization-users) +- [Billing FAQs](/azure/devops/organizations/billing/billing-faq) +- [Billing overview](/azure/devops/organizations/billing/overview) +- [Manage access with Microsoft Entra groups](/azure/devops/organizations/accounts/manage-azure-active-directory-groups) +- [Manage billing](/azure/devops/organizations/billing/set-up-billing-for-your-organization-vs) +- [Use personal access tokens](/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) -## Demo-gen +## Azure Pipelines ### Updated articles -- [Build a custom template](/azure/devops/demo-gen/build-your-own-template) +- [Build and test Go projects](/azure/devops/pipelines/ecosystems/go) +- [Build, test, and deploy .NET Core apps](/azure/devops/pipelines/ecosystems/dotnet-core) +- [Cache NuGet packages](/azure/devops/pipelines/artifacts/caching-nuget) +- [Configure and pay for parallel jobs](/azure/devops/pipelines/licensing/concurrent-jobs) +- [Expressions](/azure/devops/pipelines/process/expressions) +- [Secure Azure Pipelines](/azure/devops/pipelines/security/overview) +- [Securely use variables and parameters in your pipeline](/azure/devops/pipelines/security/inputs) +- [Sign up for Azure Pipelines](/azure/devops/pipelines/get-started/pipelines-sign-up) +- [Troubleshoot pipeline runs](/azure/devops/pipelines/troubleshooting/troubleshooting) -## Extend +## Project ### Updated articles -- [Extend the work item form](/azure/devops/extend/develop/add-workitem-extension) -- [Data storage](/azure/devops/extend/develop/data-storage) -- [Extension samples](/azure/devops/extend/develop/samples-overview) -- [Vertical navigation guidance](/azure/devops/extend/develop/web-navigation) +- [About requesting and providing feedback](/azure/devops/project/feedback/index) +- [Filter lists, boards, and directories](/azure/devops/project/navigation/filter-basics) +- [Keyboard shortcuts for Azure DevOps and Team Explorer](/azure/devops/project/navigation/keyboard-shortcuts) +- [Migrate pages from the wiki extension to a team project wiki](/azure/devops/project/wiki/migrate-extension-wiki-pages) +- [Navigate the Azure DevOps web portal](/azure/devops/project/navigation/index) -## GitHub issue content updates +## Azure DevOps Reporting and Analytics service -Thank you for your feedback on our documentation. This month we made updates to our content to address [these GitHub issues](https://github.com/MicrosoftDocs/azure-devops-docs/issues?q=linked%3Apr+is%3Aissue+is%3Aclosed+closed%3A2023-05-01..2023-05-31). +### Updated articles -## Community contributors +- [About Power BI integration](/azure/devops/report/powerbi/overview) +- [Create an Analytics view in Azure DevOps](/azure/devops/report/powerbi/analytics-views-create) +- [Lead Time and Cycle Time widgets](/azure/devops/report/dashboards/cycle-time-and-lead-time) +- [Out Of Box widget catalog](/azure/devops/report/dashboards/widget-catalog) +- [Show last refresh date to Power BI report](/azure/devops/report/powerbi/add-last-refresh-time) +- [Track progress with status and trend query-based charts](/azure/devops/report/dashboards/charts) +- [View and configure team velocity](/azure/devops/report/dashboards/team-velocity) + +## Azure Test Plans + +### Updated articles -The following people contributed to the Azure DevOps docs during this period. Thank you! Learn how to contribute by following the links under "Get involved" in the [what's new landing page](index.yml). +- [Associate automated tests with test cases](/azure/devops/test/associate-automated-test-with-test-case) -- [hyoshioka0128](https://github.com/hyoshioka0128) - Hiroshi Yoshioka (2) -- [jennings](https://github.com/jennings) - Stephen Jennings (1) -- [JynLeazy](https://github.com/JynLeazy) (1) -- [ronwarner](https://github.com/ronwarner) - Ron (1) -- [SampathDilhan](https://github.com/SampathDilhan) - Sampath Dilhan (1) -- [stefkiourk](https://github.com/stefkiourk) - Stef Ki (1) -- [TheJohnH](https://github.com/TheJohnH) - John H (1) -- [yagnyaPatel](https://github.com/yagnyaPatel) - Yagnya Patel (1) diff --git a/release-notes/docswhatsnew/index.yml b/release-notes/docswhatsnew/index.yml index 5ae85c75ab3..0f81398843e 100644 --- a/release-notes/docswhatsnew/index.yml +++ b/release-notes/docswhatsnew/index.yml @@ -16,12 +16,12 @@ landingContent: linkLists: - linkListType: whats-new links: - - text: May 2023 + - text: March 2025 url: azure-devops-docs-whats-new.md - - text: April 2023 - url: azure-devops-docs-2023-03.md - - text: March 2023 - url: azure-devops-docs-2023-03.md + - text: February 2025 + url: azure-devops-docs-2025-02.md + - text: January 2025 + url: azure-devops-docs-2025-01.md - title: "Get involved - contribute to Azure DevOps docs" linkLists: diff --git a/release-notes/docswhatsnew/toc.yml b/release-notes/docswhatsnew/toc.yml new file mode 100644 index 00000000000..bf08aa8212f --- /dev/null +++ b/release-notes/docswhatsnew/toc.yml @@ -0,0 +1,12 @@ +- name: What's new + href: ./index.yml +- name: March 2025 + href: ./azure-devops-docs-whats-new.md +- name: February 2025 + href: ./azure-devops-docs-2025-02.md +- name: January 2025 + href: ./azure-devops-docs-2025-01.md + + + + diff --git a/release-notes/features-timeline-released.md b/release-notes/features-timeline-released.md index c8c6741dd23..7d40368c992 100644 --- a/release-notes/features-timeline-released.md +++ b/release-notes/features-timeline-released.md @@ -2,8 +2,7 @@ title: Azure DevOps Released Features author: gloridelmorales ms.author: glmorale -ms.date: 6/21/2023 - +ms.date: 9/4/2024 ms.topic: article ms.service: azure-devops ms.subservice: azure-devops-release-notes @@ -22,6 +21,7 @@ hide_comments: true --- ## Released features +## Azure DevOps Services The released features timeline lists significant features delivered to Azure DevOps Services and the corresponding version of Azure DevOps Server. Versions in the "Server" column are linked to the appropriate download location. @@ -37,100 +37,398 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Server + + 3 April 2025 + No new Azure DevOps OAuth apps beginning April 2025 GeneralFuture + Server Name Indication (SNI) now mandatory for Azure DevOps Services GeneralFuture + GitHub Integration: Improvements linking to commits, branches and pull requestsBoardsFuture + GitHub Integration: Show build status for YAML pipelinesBoardsFuture + Delivery Plans limit increasedBoardsFuture + TFVC check-in policies changes ReposFuture + Enhancement to GetRepository APIReposFuture + Enhancement to Pull Requests Query APIReposFuture + Improved visibility into YAML pipeline stage dependenciesPipelinesFuture + New Agent CDNPipelinesFuture + Node 16 will be removed from pipelines-* Pipeline agent packagesPipelinesFuture + Retirement of action logging and switch to screen recordingTest PlansFuture + Auto-pause manual test runTest PlansFuture + + 20 March 2025 + Overlapping secrets for Azure DevOps OAuth GeneralFuture + Deprecation of Languages statistics tags from the Project Summary Page GeneralFuture + Delivery Plans permission added GeneralFuture + Security overview risk page enhanced with new columns and filtering optionsGitHub Advanced Security for Azure DevOpsN/A + Multi-repository publishing scenarios supported for GitHub Advanced Security for Azure DevOpsGitHub Advanced Security for Azure DevOpsN/A + Service hooks for GitHub Advanced Security alerts for Azure DevOps (preview)GitHub Advanced Security for Azure DevOpsN/A + pnpm 9 support comes to GitHub Advanced Security for Azure DevOps dependency scanning GitHub Advanced Security for Azure DevOpsN/A + Hosted image updatesPipelinesFuture + Workload identity federation uses Entra issuerPipelinesFuture + Gradle@4 taskPipelinesFuture + stringList parameter typePipelinesFuture + Identity of user who requested a stage to runPipelinesFuture + Improvements on the Publish code coverage results v2 taskTest PlansFuture + Export test cases with custom columns in XLSXTest PlansFuture + + 24 February 2025 + Microsoft Entra profile information (preview) GeneralFuture + Basic access included with GitHub Enterprise GeneralFuture + Azure DevOps Allowed IP addressesGeneralFuture + One click enablement for dependency scanning previewGitHub Advanced Security for Azure DevOpsN/A + Deleted branches removed from Advanced Security branch pickerGitHub Advanced Security for Azure DevOpsN/A + GitHub Integration: Linking the Merge Commit BoardsFuture + Increase Limit of Connected GitHub RepositoriesBoardsFuture + Update on New Boards Hub RolloutBoardsFuture + Pipelines using Ubuntu 24.04 will show warnings for certain tasksPipelinesFuture + Informational runsPipelinesFuture + Undo test step in web and desktop runnerTest PlansFuture + + 12 February 2025 + Removal of Generate Git Credentials Button in Repos and Wiki GeneralFuture + Update to Azure DevOps Allowed IP addresses GeneralFuture + GitHub Advanced Security updates for default branch changesGitHub Advanced Security for Azure DevOpsN/A + CodeQL installation for self-hosted agents supports proxy configurationsGitHub Advanced Security for Azure DevOpsN/A + Alerts branch picker now displays all branches with a successful scanGitHub Advanced Security for Azure DevOpsN/A + Enhanced pull request annotations in GitHub Advanced Security GitHub Advanced Security for Azure DevOpsN/A + Improvements for Get alerts APIGitHub Advanced Security for Azure DevOpsN/A + Azure Classic Service Connections are being retiredPipelinesFuture + Managed DevOps Pools is generally availablePipelinesFuture + New tasks to implement secret-less access to Azure storage accountsPipelinesFuture + Direct link from Test Plan work item to Test Plans pageTest PlansFuture + Azure Test Plans bug fixesTest PlansFuture + Export test cases with custom columns in XLSXTest PlansN/A + Auto-pause manual test case runTest PlansFuture + + 17 January 2025 + Tool specific security overview coverageGitHub Advanced Security for Azure DevOpsN/A + Azure Boards Integration with GitHub Enterprise Cloud with Data Residency BoardsFuture + Sparse checkout for Azure ReposReposFuture + Make cross-repo policies case-sensitiveReposFuture + New pipeline expression functionPipelinesN/A + Enhancements to ManualValidation taskPipelinesN/A + Azure Test Plans bug fixesTest PlansFuture + + 13 November 2024 + Commit-less builds supported for dependency scanningGitHub Advanced Security for Azure DevOpsN/A + File previews and annotations for CodeQL scans using sourcesFolderGitHub Advanced Security for Azure DevOpsN/A + New REST API limit on work item comments BoardsFuture + Search pull requests by title on PR listing pageReposFuture + macOS-15 Sequoia is available in previewPipelinesN/A + Improvements to service connection App registration attributionPipelinesN/A + Azure Test Runner version 1.2.2Test PlansFuture + New sorting capabilities in Test Plans directoryTest PlansFuture + Auto Pause for Test Case Run previewTest PlansFuture + New release version for Test and Feedback Extensions (TFE)Test PlansFuture + + + 16 October 2024 + Copy code block to clipboard GeneralFuture + Entra Profile information GeneralFuture + Pull request annotations for dependency and code scanningGitHub Advanced Security for Azure DevOpsN/A + New pip detection strategy for dependency scanningGitHub Advanced Security for Azure DevOpsN/A + Alert rule IDs now integrated into result fingerprints GitHub Advanced Security for Azure DevOpsN/A + Enhanced tag management on work item form BoardsN/A + Improved image support in work item commentsBoardsN/A + GitHub pull request insightsBoardsN/A + Configure target branches for pull requestsReposFuture + Support mermaid diagrams in markdown file previewReposFuture + Ubuntu 24.04 on Azure Pipelines hosted agentsPipelinesFuture + Use Workload identity federation in Azure integration testsPipelinesFuture + New Azure service connection creation experience with improved Managed identity supportPipelinesFuture + Run children stages when parent stage failsPipelinesFuture + Authentication to Azure Artifacts using a public feed and CargoArtifactsN/A + Improve pasting of HTML based content into WikisWikiFuture + + + 26 September 2024 + Pull request branches now visible in Advanced Security branch picker GitHub Advanced Security for Azure DevOpsN/A + Automatic updates for default branch changes in Advanced SecurityGitHub Advanced Security for Azure DevOpsN/A + Generic third-party SARIF support for Advanced SecurityGitHub Advanced Security for Azure DevOpsN/A + Alert rule IDs now integrated into result fingerprints GitHub Advanced Security for Azure DevOpsN/A + Pull request annotations feature in public preview GitHub Advanced Security for Azure DevOpsN/A + AB# links on GitHub pull requestsBoardsN/A + REST API support for connecting GitHub repositoriesBoardsN/A + Permanently delete attachmentsBoardsFuture + New Health and usage panel in repo file hub ReposFuture + Azure Pipeline agent v4 runs on .NET 8PipelinesFuture + Preview mode for shell tasks arguments validationPipelinesFuture + Seamless build Pipeline integration for test case executionTest PlansFuture + Test and feedback extension in Manifest V3 (Edge release)Test PlansFuture + + + 4 September 2024 + New Advanced Security API endpoint to retrieve all branches with successful Advanced Security analysesGitHub Advanced Security for Azure DevOpsN/A + Advanced Security List Alerts API return all alerts across all branchesGitHub Advanced Security for Azure DevOpsN/A + Area and iteration level fieldsBoardsFuture + UI support of Git SubmodulesReposFuture + Announcing deprecation of Pipeline TasksPipelinesFuture + The Pipelines agent will show warnings for agents running Operating Systems not supported by .NET 8PipelinesFuture + Enhanced Visibility for Usage Limits in Azure DevOpsReportingFuture + + + 13 August 2024 + Advanced Security meter usage API now returns user identitiesGitHub Advanced Security for Azure DevOpsN/A + Advanced Security code scanning for C# and Java projects without buildsGitHub Advanced Security for Azure DevOpsN/A + Managed DevOps Pools (Preview)PipelinesFuture + Azure Pipelines tasks use Node 20PipelinesFuture + Create build pipeline permissionPipelinesFuture + Exclusive lock check at stage levelPipelinesFuture + Template information in pipeline runsPipelinesFuture + Manually triggered YAML pipeline stagesPipelinesFuture + + 25 July 2024 + Connect to GitHub repository search improvementsBoardsFuture + Create GitHub branch from work itemBoardsFuture + Unskippable stagesPipelinesFuture + + 3 July 2024 + New authentication format for Azure DevOps personal access tokens availableGeneralFuture + Automated self-hosted agent install for code scanning bits in Advanced SecurityGitHub Advanced Security for Azure DevOpsN/A + AzureFileCopy, AzurePowerShell, and SqlAzureDacpacDeployment tasks use Az modules onlyPipelinesFuture + Use Workload identity federation for container jobs, resources, and tasksPipelinesFuture + + 14 June 2024 + Security overview API documentation now availableGitHub Advanced Security for Azure DevOpsN/A + Change for deleting area and iteration pathsBoardsFuture + Access Azure Bus from Pipelines using Microsoft Entra ID authenticationPipelinesFuture + Pipelines and tasks populate variables to customize Workload identity federation authenticationPipelinesN/A + Retries for server tasks PipelinesFuture + Tasks that use an end-of-life Node runner version to execute emit warningsPipelinesFuture + DockerCompose@0 uses Docker Compose v2 in v1 compatibility modePipelinesFuture + New setting to disable creation of TFVC repositoriesReposFuture + Test and Feedback Extension in Manifest V3 Test PlansFuture + + 2 May 2024 + Improve Search Results with wildcard prefixes and substringsGeneralFuture + Security overview risk view links to repository alertsGitHub Advanced Security for Azure DevOpsN/A + Publish task for integrating with third-party providersGitHub Advanced Security for Azure DevOpsN/A + macOS-14 Sonoma preview and macOS-11 retirement PipelinesFuture + Node 10 removed from pipelines-* Pipeline agent packagesPipelinesFuture + + + 10 April 2024 + Expanded set of Secret Scanning detectionsGitHub Advanced Security for Azure DevOpsN/A + Secret Scanning now detects non-provider patternsGitHub Advanced Security for Azure DevOpsN/A + Add link to GitHub commit or pull requestBoardsFuture + AB# links on GitHub pull requests (preview)BoardsFuture + Connect to GitHub repository search improvementsBoardsFuture + Edit queue build configuration permissionPipelinesFuture + TFX validates whether a task is using an End or Life Node runnerPipelinesFuture + + + 26 March 2024 + Personal access token (PAT) APIs to return maximum allowed lifespanGeneralN/A + Azure service connections indicate when a secret has expiredPipelinesFuture + New AzureFileCopy@6 task supports secret-less configurationsPipelinesFuture + Resource utilization alerts for Azure Pipeline agentsPipelinesFuture + + + 29 February 2024 + Show GitHub pull request details (preview)BoardsFuture + Preparation for SSH-RSA deprecation in future Server versionRepos2022.2 + Rerun a single stagePipelinesFuture + Quick Copy and Import with Test Plan or Suite IDTest Plans2022.2 + Update for Azure Test RunnerTest Plans2022.2 + + + 9 February 2024 + Code snippets now available in alert details viewGeneralFuture + Final notice of alternate credentials deprecationGeneralN/A + Azure Devops OAuth self-service secret rotationGeneralN/A + Linked Azure subscription required for GitHub Advanced Security for Azure DevOps enablementGitHub Advanced Security for Azure DevOpsN/A + New Boards Hub ImprovementsBoardsFuture + Development and Deployment ControlsBoards2022.2 + Workload identity federation for Azure Resource Manager service connections is now generally availablePipelinesFuture + Out-of-band installation of Node 6 task runnerPipelinesN/A + Deferred approvalPipelinesFuture + Sequencing approvals and checksPipelinesFuture + Validate and Save by default when editing YAML pipelinesPipelinesFuture + Prevention for unauthorized users to configure pipeline as a Build PolicyRepos2022.2 + Support for Rust Crates is generally availableArtifactsN/A + Azure Artifacts support for npm auditArtifacts2022.2 + + + 19 January 2024 + Custom CodeQL queries now supported in GitHub Advanced Security for Azure DevOpsGitHub Advanced Security for Azure DevOpsN/A + Team Automation RulesBoardsFuture + Update deprecated tasks before January 31PipelinesN/A + Microsoft hosted agents use PowerShell 7.4PipelinesN/A + New Azure service connection secrets expire in three monthsPipelinesN/A + + + 11 January 2024 + Select a geography when creating a new Azure DevOps organizationGeneralN/A + Removed Visual Studio Subscriber option from group rulesGeneralN/A + Code Coverage results for foldersTest Plans2022.2 + + + 5 December 2023 + Switch between HTML or Markdown on commentsBoardsFuture + Improved YAML validationPipelines2022.2 + Checks scalability Phase 3PipelinesN/A + + + 16 November 2023 + New version of the Azure DevOps Web Extension SDK General2022.2 + Azure Pipelines tasks use Node 16PipelinesN/A + Announcing retirement of deprecated tasksPipelinesN/A + AzureRmWebAppDeployment task supports Microsoft Entra ID authenticationPipelinesN/A + Improvements to Approvals REST APIPipelines2022.2 + Bypass Approvals and ChecksPipelines2022.2 + Support for GitHub enterprise server in required template checkPipelines2022.2 + Rerun invoke Azure function checksPipelines2022.2 + Work item filteringReporting2022.2 + + + 26 October 2023 + REST API documentation now available for Advanced Security GitHub Advanced Security for Azure DevOpsN/A + Publish Test Results TaskGeneral2022.2 + Building PRs from forked GitHub repositoriesPipelinesN/A + Deprecation announcement for NuGet Restore v1 and NuGet Installer v0 pipeline tasksArtifactsN/A + New Dashboard directory experienceReporting2022.2 + + + 4 October 2023 + Managed identity and service principal support for Azure DevOps now in general availability (GA)GeneralN/A + New Azure DevOps scopes available for Microsoft Identity OAuth delegated flow appsGeneralN/A + Changes to Code Scanning (CodeQL) user input task and variablesGitHub Advanced Security for Azure DevOpsN/A + Publish task is no longer required for Setting up code ScanningGitHub Advanced Security for Azure DevOpsN/A + CodeQL code scanning now supports SwiftGitHub Advanced Security for Azure DevOpsN/A + Pipeline logs now contain resource utilizationPipelines2022.2 + Azure Pipelines agent now supports Alpine LinuxPipelinesN/A + + + 14 September 2023 + Limits for area and iteration pathsBoards2022.2 + Pipeline agents can be registered using Azure Active Directory instead of a PATPipelinesFuture + Workload identity federation for Azure Pipelines (public preview)PipelinesFuture + REST APIs for EnvironmentsPipelinesFuture + Prevent Unintended Pipeline RunsPipelines2022.2 + Build GitHub Repositories Securely by DefaultPipelinesFuture + Disabled override of code coverage policy status to Failed when build is failing Pipelines2022.2 + Blobless and treeless filter supportRepos2022.2 + + + 23 August 2023 + Project and organization-level enablement for Advanced Security GeneralN/A + Estimated committer count during Advanced Security enablement GeneralN/A + Retry a stage when approvals and checks time outPipelines2022.2 + Administrator role for all EnvironmentsPipelines2022.2 + Centralized control for building PRs from forked GitHub reposPipelinesFuture + Azure Artifacts support for Cargo Crates (public preview) Artifacts2022.2 + + + 2 August 2023 + Disable creation of classic pipelines for new organizations (pre-announcement)Pipelines2022.1 + Increased Azure Pipeline limits to align with the 4 MB maximum Azure Resource Manager (ARM) template sizePipelines2022.1 + + + 11 July 2023 + Alert dismissals for dependency scanning alerts in Advanced SecurityGitHub Advanced Security for Azure DevOpsN/A + Copy link to work itemBoardsFuture + Kubernetes tasks now support kubeloginPipelines2022.1 + Updates to YAML cron schedulesPipelinesN/A + Disable a checkPipelines2022.1 + Improvements to Approvals REST APIPipelinesFuture + New toggles to control creation of classic pipelinesPipelines2022.1 + Removing "Edit policies" permission to branch creatorRepos2022.1 + 21 June 2023 Organization profile imageGeneralFuture - Checks user experience improvementsPipelinesFuture + Checks user experience improvementsPipelines2022.1 Scalable Invoke Azure Function and REST API checks changesPipelinesFuture - Instructions for manual pre-installation of Node 6 on Pipeline agentsPipelinesFuture - Pipeline task changelogPipelinesFuture - Release tasks use Microsoft Graph APIPipelinesFuture - Specify agent version in Agent VM extensionPipelinesN/A - Introducing resolved as completed in burndown and burnup chartsReportingFuture + Instructions for manual pre-installation of Node 6 on Pipeline agentsPipelinesN/A + Pipeline task changelogPipelines2022.1 + Release tasks use Microsoft Graph APIPipelines2022.1 + Specify agent version in Agent VM extensionPipelines2022.1 + Introducing resolved as completed in burndown and burnup chartsReporting2022.1 - 6 June 2023 - GitHub Advanced Security for Azure DevOps (public preview)GeneralN/A + 6 June 2023 + GitHub Advanced Security for Azure DevOps (public preview)GitHub Advanced Security for Azure DevOpsN/A Fixed a bug that allowed users to bypass restrict global personal access token (PAT) creationGeneralFuture Markdown support for comments (private preview)BoardsFuture Improvements to YAML pipeline traceabilityPipelinesFuture - Automatic tokens created for Kubernetes Service ConnectionPipelinesFuture - Pipeline agents can be registered using a Service PrincipalPipelinesFuture + Automatic tokens created for Kubernetes Service ConnectionPipelines2022.1 Preview of macOS 13 Ventura for Azure Pipeline hosted poolsPipelinesN/A + + 9 May 2023 + Swimlane rulesBoardsFuture + Pipeline settings audit improvementsPipelinesFuture + Pull Request widget for multiple repos is now generally availableReporting2022.1 + 20 April 2023 Sticky "Save" and "Save and Close" button BoardsFuture - Stage quick actionsPipelinesFuture - Analytics Views are now generally availableReportingFuture + Stage quick actionsPipelines2022.1 + Analytics Views are now generally availableReporting2022.1 - 31 March 2023 - Service principal and managed identity support in Azure DevOps GeneralFuture - REST API support for connecting GitHub repositories (private preview)BoardsFuture - Swimlane rules (private preview) BoardsFuture - Pipeline Agent end of support for Debian 9, Fedora 32, macOS 10.14 and othersPipelinesFuture + 31 March 2023 + Service principal and managed identity support in Azure DevOps (public preview) GeneralN/A + REST API support for connecting GitHub repositories (preview)BoardsFuture + Pipeline Agent end of support for Debian 9, Fedora 32, macOS 10.14 and othersPipelinesN/A 8 March 2023 - Node runner download taskPipelinesFuture - Updated TFX Node runner validationPipelinesFuture + Node runner download taskPipelines2022.1 + Updated TFX Node runner validationPipelines2022.1 Service hook for job state changePipelinesFuture Improved security when creating GitHub Enterprise Server (hosted Pipelines)PipelinesFuture - Dashboards last accessed date and modified ByReportingFuture + Dashboards last accessed date and modified ByReporting2022.1 17 February 2023 License source column in user list exportGeneralFuture - Interactive boards reportsBoardsFuture + Interactive boards reportsBoards2022.1 Search for filter stages in side panelPipelinesFuture - Pipeline agent v3 (.NET 6) rolling outPipelinesFuture - Pull request widget for multiple repos (private preview)ReportingFuture + Pipeline agent v3 (.NET 6) rolling outPipelinesN/A + Pull request widget for multiple repos (private preview)Reporting2022.1 7 February 2023 - New save comments permissionBoardsFuture + New save comments permissionBoards2022.1 Red Hat 6 will no longer receive Pipeline agent updatesPipelinesFuture - Pipeline stages side panelPipelinesFuture - Restrict opening protected resources to resource administratorsPipelinesFuture + Pipeline stages side panelPipelines2022.1 + Restrict opening protected resources to resource administratorsPipelines2022.1 Copy DashboardReportingFuture 25 January 2023 - Prevent editing of shareable picklists fieldsBoardsFuture + Prevent editing of shareable picklists fieldsBoards2022.1 Swimlane colorsBoardsFuture - Experience improvements to pipeline permissionsPipelinesFuture - Ability to disable masking for short secretsPipelinesFuture - New PAT Scope for managing pipeline authorization and approvals and checksPipelinesFuture + Experience improvements to pipeline permissionsPipelines2022.1 + Ability to disable masking for short secretsPipelines2022.1 + New PAT Scope for managing pipeline authorization and approvals and checksPipelines2022.1 Variables as inputs in checksPipelinesFuture Script to self-validate pipeline agent versionPipelinesFuture - Pipeline run status overview iconPipelinesFuture + Pipeline run status overview iconPipelines2022.1 Support for subpages tableWikiFuture 12 January 2023 - Extensions should display their ScopesGeneralFuture - Card resize logic in Delivery PlansBoardsFuture - Batch update improvementsBoardsFuture - Batch delete API (GA)BoardsFuture - Support for Tokyo version of ServiceNowPipelinesFuture - New predefined system variablePipelinesFuture + Extensions should display their ScopesGeneral2022.1 + Card resize logic in Delivery PlansBoards2022.1 + Batch update improvementsBoards2022.1 + Batch delete APIBoards2022.1 + Support for Tokyo version of ServiceNowPipelines2022.1 + New predefined system variablePipelines2022.1 General Availability of templates support in YAML editorPipelinesFuture 8 December 2022 Copy comment linksBoardsFuture - Container Registry service connections can now use Azure Managed IdentitiesPipelinesFuture - Audit log events related to pipeline permissionsPipelinesFuture - Ensure your organization only uses YAML pipelinesPipelinesFuture + Container Registry service connections can now use Azure Managed IdentitiesPipelines2022.1 + Audit log events related to pipeline permissionsPipelinesN/A + Ensure your organization only uses YAML pipelinesPipelines2022.1 Service hook for job state changePipelinesFuture New PAT scope required to update pipeline General SettingsPipelinesFuture - Fine-grained access management for agent poolsPipelinesFuture - Prevent granting all pipelines access to protected resourcesPipelinesFuture + Fine-grained access management for agent poolsPipelines2022.1 + Prevent granting all pipelines access to protected resourcesPipelines2022.1 Improved security when building pull requests from forked GitHub repositoriesPipelinesFuture Macos-latest label will point to macos-12 imagePipelinesN/A Ubuntu-latest label will point to ubuntu-22.04 imagePipelinesN/A 2 November 2022 Edit work item link typesBoardsFuture - Create temporary query REST endpointBoardsFuture - Batch delete API (private preview)BoardsFuture - @CurrentIteration macro in Delivery PlansBoardsFuture - Template Expressions in Repository Resource DefinitionPipelinesFuture - Template Expressions in Container Resource DefinitionPipelinesFuture + Create temporary query REST endpointBoards2022.1 + @CurrentIteration macro in Delivery PlansBoards2022.1 + Template Expressions in Repository Resource DefinitionPipelines2022.1 + Template Expressions in Container Resource DefinitionPipelines2022.1 Audit Events for Changes to ApprovalsPipelinesFuture Task library exposes Agent hosting modelPipelinesFuture @@ -139,54 +437,54 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Option to maintain hierarchy with filtersBoardsFuture Copy work item attachment URLBoardsFuture Pipeline Agent supports Group Managed Service Accounts as service accountPipelinesFuture - Show Parent in Query Results WidgetReportingFuture + Show Parent in Query Results WidgetReporting2022.1 4 October 2022 - All Public REST APIs support granular PAT scopesGeneralFuture + All Public REST APIs support granular PAT scopesGeneral2022.1 Move to column and move to swimlaneBoardsFuture Windows PowerShell task performance improvementPipelinesFuture Pipelines Agent on .NET 6 pre-announcementPipelinesFuture Node 16 task runner in pipeline agentPipelinesFuture - New user interface for upstream package searchArtifactsFuture + New user interface for upstream package searchArtifacts2022.1 12 September 2022 - Increase Delivery Plans team limit from 15 to 20BoardsFuture - Fixed bug in Reporting Work Item Links Get APIBoardsFuture - New Boards Hub bug fixesBoardsFuture - Disable showing the last commit message for a pipeline runPipelinesFuture - Consumed resources and template parameters in Pipelines Runs Rest APIPipelinesFuture - Add support for string split function in YAML expressionPipelinesFuture - Do not sync tags when fetching a Git repositoryPipelinesFuture + Increase Delivery Plans team limit from 15 to 20Boards2022.1 + Fixed bug in Reporting Work Item Links Get APIBoards2022.1 + New Boards Hub bug fixesBoards2022.1 + Disable showing the last commit message for a pipeline runPipelines2022.1 + Consumed resources and template parameters in Pipelines Runs Rest APIPipelines2022.1 + Add support for string split function in YAML expressionPipelines2022.1 + Do not sync tags when fetching a Git repositoryPipelines2022.1 Updated brownout schedule for Ubuntu 18.04 imagesPipelinesN/A 12 August 2022 - Improved error message when failing to load pipelinesPipelinesFuture + Improved error message when failing to load pipelinesPipelines2022.1 General availability of Ubuntu 22.04 for Azure Pipelines hosted poolsPipelinesN/A Announcing deprecation of Ubuntu 18.04 imagesPipelinesN/A 28 July 2022 - Pipelines REST API Security ImprovementsPipelinesFuture - Use proxy URLs for GitHub Enterprise integrationPipelinesFuture - Scheduled builds improvementsPipelinesFuture - Updates to "Run stage state changed" service hook eventPipelinesFuture - Change in the default scope of access tokens in classic build pipelinesPipelinesFuture - Azure Pipelines support for San Diego release of ServiceNowPipelinesN/A + Pipelines REST API Security ImprovementsPipelines2022.1 + Use proxy URLs for GitHub Enterprise integrationPipelines2022.1 + Scheduled builds improvementsPipelines2022.1 + Updates to "Run stage state changed" service hook eventPipelines2022.1 + Change in the default scope of access tokens in classic build pipelinesPipelines2022.1 + Azure Pipelines support for San Diego release of ServiceNowPipelines2022.1 Announcing retirement of Windows 2016 imagePipelinesN/A Announcing deprecation of macOS 10.15 Catalina imagesPipelinesN/A - Updated default feed permissionsArtifactsFuture + Updated default feed permissionsArtifacts2022.1 14 July 2022 Filter on work item historyBoardsFuture - Last Accessed column on Delivery Plans pageBoardFuture - Visualize all dependencies on Delivery PlansBoardsFuture - New work item revision limitsBoardsFuture - Current project set as default scope for build access token in classic pipelinesPipelinesFuture + Last Accessed column on Delivery Plans pageBoard2022.1 + Visualize all dependencies on Delivery PlansBoards2022.1 + New work item revision limitsBoards2022.1 + Current project set as default scope for build access token in classic pipelinesPipelines2022.1 27 June 2022 - Project Collection Administrators can opt-in for notifications related to personal access tokens found in a GitHub public repositoryGeneralN/A + Project Collection Administrators can opt in for notifications related to personal access tokens found in a GitHub public repositoryGeneralN/A Enforcing security validation for all Azure DevOps requestsGeneralN/A Assigned To children in Kanban cardsBoards2022 - General availability of Query by Parent IdBoardsFuture + General availability of Query by Parent IDBoardsFuture Support Group Managed Service Accounts as agent service accountPipelines2022 Informational runsPipelines2022 Build Definition REST API retentionRules property is obsoletePipelines2022 @@ -197,8 +495,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Ubuntu 22.04 in preview for Azure Pipelines hosted poolsPipelinesN/A Preview of macOS 12 Monterey for Azure Pipeline hosted poolsPipelinesN/A - 4 May 2022 - Query by Parent Id (private preview)BoardsFuture + 4 May 2022 Move to column position on Kanban BoardBoards2022 Added "Will not Fix" value to Bug reason fieldBoards2022 Upstream cross-organization packagesArtifactsN/A @@ -251,7 +548,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Improved tenant switch requests reliabilityGeneralN/A Emphasize tags in Delivery Plans using colorsBoards2022 Filter cards based on boolean field types in Delivery PlansBoards2022 - Work item title are always visible in Delivery Plan cardsBoards2022 + Work item titles are always visible in Delivery Plan cardsBoards2022 Show light green colored dependency icon for work items that have dependencies with no issuesBoards2022 macOS-latest label will soon point to macOS-11 imagePipelinesN/A Updated schedule for removal of Ubuntu 16.04 image on Microsoft-hosted agentsPipelinesN/A @@ -408,7 +705,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Allow stakeholders to drag and drop work itemsBoardsFuture Default branch name preferenceReposFuture - Updates to Mac OS 10.14 (Mojave) image PipelinesFuture + Updates to macOS 10.14 (Mojave) image PipelinesFuture [Feedback] Git Draft Pull Requests should not trigger the pipelinePipelinesFuture Multi-repo triggers for Azure ReposPipelinesFuture @@ -469,7 +766,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil 13 April 2020 Support for Team Admins to create subscriptions for messaging apps in Slack and TeamsGeneral2020 - Multi tenant support for Azure Boards, Repos and Pipelines app in Microsoft TeamsGeneral2020 + Multitenant support for Azure Boards, Repos and Pipelines app in Microsoft TeamsGeneral2020 Sync GitHub Issues to Azure DevOps Work ItemsBoards2019 Improved PR actionabilityRepos2020.1 Improved comment-related filtering within pull requestsRepos2020.1 @@ -534,7 +831,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Checkout multiple repositories in Azure PipelinesPipelinesFuture Use GitHub Actions to trigger a run in Azure PipelinesPipelinesFuture Updated ServiceNow integration with Azure PipelinesPipelines2020 - Set VSTest tasks to fail if a minimum number of test are not runPipelinesFuture + Set VSTest tasks to fail if a minimum number of tests are not runPipelinesFuture UCS-4 support for Python 2.7PipelinesN/A Create bulk subscriptions in Azure Pipelines app for Slack and Microsoft TeamsPipelinesN/A Create bulk subscriptions in Azure Repos app for Slack and Microsoft TeamsReposN/A @@ -620,7 +917,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Granularity for automatic reviewersRepos2020 Get latest Universal Package with Semantic Versioning (SemVer) wildcardArtifacts2020 Azure Artifacts feeds in the Visual Studio Package ManagerArtifacts2020 - Create Azure Pipelines from VSCodePipelines2020 + Create Azure Pipelines from VS CodePipelines2020 New task for configuring Azure App Service app settingsPipelines2020 Azure App Service now supports Swap with previewPipelines2020 YAML templates for Python and .NET Functions appsPipelines2020 @@ -642,7 +939,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Reactions on discussion commentsBoards2020 Pin Azure Boards reports to the dashboardBoards2020 Azure Repos app for SlackReposN/A - Configure upstreams in different organizations within an AAD tenantArtifacts2020 + Configure upstreams in different organizations within an Azure AD tenantArtifacts2020 Use Python Credential Provider to authenticate pip and twine with Azure Artifacts feedsArtifacts2020 Pipelines caching improvementsPipelines2020 Increase in gates timeout limit and frequencyPipelines2020 @@ -788,7 +1085,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Dark theme general availabilityGeneral2019.1 Query work based on Azure Active Directory groupsBoardsFuture - Share you team's board using a badgeBoards2019.1 + Share your team's board using a badgeBoards2019.1 Query for work relative to the start of the day, week, month, or yearBoards2019.1 Export query results to a CSV fileBoards2019.1 New merge types for completing pull requestsRepos2019.1 @@ -843,7 +1140,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Skip continuous integration (CI) for a commitPipelines2019.1 Updates to hosted pipelines imagesPipelinesN/A Contribution point for variables in the create release dialogPipelines2019.1 - Support for Python Function Apps in DevOps projectsPipelinesN/A + Support for Python Function Apps in DevOps ProjectsPipelinesN/A Schedule releases on source or pipeline changePipelines2019.1 Build and release log viewer enhancementsPipelinesFuture Publish to Azure Service Bus session queuesPipelines2019.1 @@ -895,7 +1192,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Change build numbers, upload, and download artifacts in forked repository buildsPipelinesFuture New option in 'Publish Test Results' task to fail build on failed testsPipelinesFuture Updates to the Azure portal for creating an Azure DevOps projectPipelinesFuture - Use the Azure portal to set up and deploy to a CosmosDB databasePipelinesFuture + Use the Azure portal to set up and deploy to a Cosmos DB databasePipelinesFuture Setup builds and release pipelines for Functions in Azure portalPipelinesFuture Package usage statsArtifacts2019.1 Monospaced font for Wiki markdown editorWiki2019.1 @@ -971,7 +1268,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil Change the target branch of a pull requestRepos2019 Protect Git repos with cross platform compatibility settingsReposN/A Expanded search boxGeneral2019 - Support AAD users in MSA accountsAdministrationN/A + Support Azure AD users in MSA accountsAdministrationN/A 20 September 2018 Control-specific build dependencies using container jobsPipelinesFuture @@ -3032,7 +3329,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil 2017 - Test – Automated testing for SCVMM and VMWare + Test – Automated testing for SCVMM and VMware 2017 @@ -3280,7 +3577,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil 2017 - Release Management – Provision VMs or run a PS script using SCVMM extension + Release Management – Provision VMs or run a PowerShell script using SCVMM extension 2017 @@ -3529,7 +3826,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil 2015.2 - On-Premises support for Exploratory Testing extension: + On-premises support for Exploratory Testing extension: N/A @@ -4595,6 +4892,9 @@ You can also [view the build numbers for each version](#azure-devops-server-buil +## Azure DevOps Server + + ## Azure DevOps Server Build Numbers @@ -4611,7 +4911,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil - 2022 RTW + 2022 RTW December 6, 2022 19.205.33122.1 @@ -4841,6 +5141,7 @@ You can also [view the build numbers for each version](#azure-devops-server-buil + ## How to provide feedback We would love to hear what you think about these features. Report any problems or suggest a feature through [Developer Community](https://developercommunity.visualstudio.com/spaces/21/index.html). diff --git a/release-notes/features-timeline.md b/release-notes/features-timeline.md index ecf5df5ce56..2823a751d44 100644 --- a/release-notes/features-timeline.md +++ b/release-notes/features-timeline.md @@ -2,7 +2,7 @@ title: Azure DevOps Roadmap author: gloridelmorales ms.author: glmorale -ms.date: 5/23/2023 +ms.date: 4/22/2025 ms.topic: article ms.service: azure-devops ms.subservice: azure-devops-release-notes @@ -24,35 +24,74 @@ hide_comments: true This feature list is a peek into our roadmap. It identifies some of the significant features we are currently working on and a rough timeframe for when you can expect to see them. It is not comprehensive but is intended to provide some visibility into key investments. At the top you will find a list of our large multi-quarter initiatives and the features that they break down into. Further down you will find the full list of significant features we have planned. -Each feature is linked to an article where you can learn more about a particular item. These features and dates are the current plans and are subject to change. The Timeframe columns reflect when we expect the feature to be available on Azure DevOps Services; the Server columns reflect when we expect the feature to ship in Azure DevOps Server. +Each feature is linked to an article where you can learn more about a particular item. These features and dates are the current plans and are subject to change. The Timeframe columns reflect when we expect the feature to be available. ## Initiatives ### GitHub Advanced Security for Azure DevOps -GitHub Advanced Security (GHAS) for Azure DevOps, now in public preview, is a suite of developer security analysis tools integrated directly into Azure DevOps to protect your Azure Repos and Pipelines. It includes: -- Secret Scanning to detect credentials and other secrets that may have already been committed to your Azure Repos, as well as push protection to prevent developers from accidentally pushing new secrets. -- Dependency Scanning to identify any known vulnerable open-source packages you may be using, and offer straightforward guidance on how to upgrade those packages to fix the vulnerabilities. -- Code Scanning with CodeQL, a powerful static analysis engine that identifies deep application security vulnerabilities in your source code. +GitHub Advanced Security for Azure DevOps (GHAzDO) brings additional security features to Azure DevOps under an additional license. Any project collection administrator can now enable Advanced Security for their organization, projects and repos from the Project Settings or Organization Settings. + +The main capabilities of GitHub Advanced Security for Azure DevOps are: + +- *Secret Scanning:* Detect and remediate plaintext secrets in your git repositories. If push protection is enabled, it also detects and blocks secrets before they are pushed to your repositories. +- *Code Scanning:* Search for potential security vulnerabilities and coding errors in your code using CodeQL or a third-party tool. +- *Dependency Scanning:* Detect and alert when your code depends on a package that is insecure and receive straightforward remediation guidance. + +You can learn more about how to configure GitHub Advanced Security for Azure DevOps in our [documentation](/azure/devops/repos/security/configure-github-advanced-security-features). + +Upcoming capabilities we expect to deliver include: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureAreaQuarter
      Determine detected partner secrets validityGitHub Advanced Security for Azure DevOps2025 Q2
      Link Boards items to Advanced Security AlertsGitHub Advanced Security for Azure DevOps2025 Q3
      Automatically fix detected dependency scanning vulnerabilities with Dependabot security updatesGitHub Advanced Security for Azure DevOpsFuture
      CodeQL default setup (one-click enablement)GitHub Advanced Security for Azure DevOpsFuture
      + ### Minimizing the risks associated with credential theft -Azure DevOps supports many different authentication mechanisms, including basic authentication, personal access tokens (PATs), SSH, and Azure Active Directory access tokens. These mechanisms are not created equal from a security perspective, especially when it comes to the potential for credential theft. For example, unintended leakage of credentials like PATs can let malicious actors into Azure DevOps organizations where they can gain access to critical assets like source code, pivot toward supply chain attacks, or even pivot toward compromising production infrastructure. +Azure DevOps supports many different authentication mechanisms, including basic authentication, personal access tokens (PATs), SSH, and Microsoft Entra ID (formerly Azure Active Directory) access tokens. These mechanisms are not created equally from a security perspective, especially when it comes to the potential for credential theft. For example, unintended leakage of credentials like PATs can let malicious actors into Azure DevOps organizations where they can gain access to critical assets like source code, pivot toward supply chain attacks, or even pivot toward compromising production infrastructure. To minimize the risks of credential theft, we will focus our efforts in the upcoming quarters in the following areas: + +* Enable administrators to improve authentication security through control plane policies. + +* Reducing the need for PATs and other stealable secrets by adding support for more secure alternatives. -To minimize the risks of credential theft, we have work in flight covering four distinct areas: -- Enable administrators to improve authentication security through control plane policies. -- Reducing the need for PATs and other stealable secrets by adding support for more secure alternatives. -- Deepening Azure DevOps' integration with Azure Active Directory to better support its various security features. -- Avoiding the need to store production secrets in Azure Pipelines service connections. +* Deepening Azure DevOps' integration with Microsoft Entra ID to better support its various security features. + +* Avoiding the need to store production secrets in Azure Pipelines service connections. -We expect this work to be a major focus of our efforts for multiple quarters. - - + @@ -60,236 +99,213 @@ We expect this work to be a major focus of our efforts for multiple quarters. - - - - + - - + - - + - - + + + + + + + + + + + + + + + + + + + + + - + - - + + + + + + - + - - + - - +
      Feature AreaServiceServerQuarter
      PAT lifecycle APIs General Done2022 Q42022.1
      Control plane for personal access tokens (PAT) General Done2022 Q42022.1
      Managed Identity and Service Principal support (preview) General Done2023 Q1N/A
      Secret-free deployments from Azure Pipelines (preview)Workload identity federation for Azure Deployments (preview) Pipelines2023 Q2N/ADone2023 Q3
      Granular scopes for Azure Active Directory OAuth General2023 Q2N/ADone2023 Q3
      Managed Identity and Service Principal support (GA) General2023 H2N/ADone2023 Q3
      Workload identity federation for Azure service connection (GA)PipelinesDone2024 Q1
      Workload identity federation for Docker service connectionPipelinesDone2024 H2
      Full web support for Conditional Access PoliciesGeneralDone2024 Q4
      Policies to disable the use of personal access tokens (PAT)General2025 Q2
      Secret-free deployments from Azure Pipelines (GA)Workload identity federation using Entra-issued tokens Pipelines2023 H2N/A2025 Q2
      PAT-less authentication from pipeline tasks to Azure DevOps APIsPipelines2025 Q3
      Policies to disable alternate authentication credentialsContinuous access evaluation General FutureN/A
      Full support for Conditional Access PoliciesUsing device bound Entra tokens in Azure DevOps General FutureN/A
      -### Updated Boards experience - -The Azure Boards user experience is being updated from the ground up. While the functionality remains the same, you can expect a more modern design, responsive reflows, improved performance, and improved accessibility. +### Improved Boards + GitHub Integration -[Learn more](/azure/devops/release-notes/2022/sprint-202-update#new-boards-hubs-now-available-in-public-preview) about how to enable the New Boards Hub and provide us with feedback. +The existing Azure Boards + GitHub integration has been in place for several years now. The integration is a great starting point, but it does not offer the level of traceability that our customers have grown accustomed to. Based on customer feedback, we have put together set of investments to enhance this integration. Our goal is to improve upon it so that Azure Boards customers who choose to use GitHub repositories can maintain an equivalent level of traceability to having repositories in Azure DevOps. -Note that most new features we are shipping in Boards are only available in the New Boards Hub. These investments include: +These investments include: - - - + + - - - - - - - + - + - - - - - + + + + - - - + + - + - - + - + - - - + + - + - - - + + - + - - - + + - - - - - + + + + - + - - - + + - + - - - + + - + - - - + + - + - - + - + - - - + +
      Feature AreaServiceServer
      Quarter
      Move to positionBoardsDone2022 Q2Future
      Adding Assigned To avatar to child items on cardsAdd link to GitHub commit or pull request from work item BoardsDone2022 Q2Future
      Move to Column and Move to SwimlaneDone2024 Q1
      Show more details about a GitHub pull request BoardsDone2022 Q1Future
      Done2024 Q1
      Filter to work item historyImprove scalability when searching and linking GitHub
      repos to an Azure DevOps project      		 BoardsDone2022 Q3FutureDone2024 Q2
      Copy work item attachment URLAB# links on GitHub pull request BoardsDone2022 Q4Future
      Done2024 Q2
      Maintain backlog hierarchy when filters are appliedCreate branch on GitHub repository from work item BoardsDone2022 Q4Future
      Done2024 Q3
      Ability to change link type from Web UI + Auto link the merge commit + BoardsDone2022 Q4Future
      Done2025 Q1
      Swimlane colors on Kanban boardBoardsDone2023 Q1Future
      + Automatically link pull requests when linked to a GitHub branch + BoardsDone2025 Q1
      Swimlane rules on Kanban board + Automatically remove branch links when their corresponding
      GitHub branches are deleted       +       		BoardsDone2023 Q2Future
      Done2025 Q1
      Markdown editor for work item comments (preview) + Show build status when using a YAML build pipeline with
      GitHub repository       +       		BoardsDone2023 Q2Future
      Done2025 Q1
      Markdown editor for work item comments (general availability) + ! mentions support for GitHub pull requests + Boards2023 Q3Future
      2025 Q2
      Automated team work item rules + Support state transitions when merging a GitHub pull request + Boards2023 Q3Future2025 Q2
      Include additional fields on page filtersSupport for GitHub Enterprise Cloud with data residency Boards2023 Q3Future
      2025 Q2
      -### Pipelines agent Node lifecycle +### Migrate to Managed DevOps Pools -Azure Pipelines tasks can be authored either in Node or PowerShell, and they use the corresponding runner in the Azure Pipelines agent. Node has a [regular cadence of releases](https://github.com/nodejs/release#release-schedule), with Node 16 being the LTS and Node 18 the Current version as of October, 2022. The original design of the Node task runner did not make Node version upgrades straightforward for task authors, and as a result has not kept up with the latest Node releases. We've heard feedback from customers on this, and are now making a number of changes to enable Azure Pipelines agents to keep installed Node versions in sync with the Node release cadence and support lifecycle while minimizing impacts on task and pipeline authors. +Managed DevOps Pools is an evolution of Azure DevOps Virtual Machine Scale Set agent pools. It provides better pool scalability and reliability, simplifies pool management, and allows you to use the VM images from Microsoft-hosted agents on custom Azure VMs. You can read more about Managed DevOps Pools [here](https://aka.ms/mdp-docs). Managed DevOps Pools is generally available, so you can migrate your Virtual machine Scale Set pools to Managed DevOps Pools and use them for production workflows, wherever possible. -As a first step, we recently released a new [Node 16 task runner](/azure/devops/release-notes/2022/sprint-210-update#node-16-task-runner-in-pipeline-agent) for the agent. Over the next few months, we plan to provide improved guidance for task authors to keep up with Node updates. Because not all tasks in the [Marketplace](https://marketplace.visualstudio.com/search?target=AzureDevOps&category=Azure%20Pipelines&sortBy=Installs) will be continuously updated to run on the latest versions of Node, we will also provide pipeline authors the ability to continue using non-upgraded tasks. Once all these features are available, we'll remove end-of-life versions of Node from Microsoft hosted agents and self-hosted agent images. +Below, you will find several investments we plan to deliver as part of this initiative: - - + - - - - - - - - - - - - - - - - - - - + - - + - + - - + - - + + - - - - - - - - + - + - - + - +
      Feature AreaServiceServerQuarter
      Node 16 runner along with other runnersPipelinesDone2022 Q3Future
      Tasks can express compatibility with multiple Node runnersPipelinesDone2022 Q3Future
      All in-the-box tasks run on Node 16Pipelines2023 Q2Future
      Ability to run tasks on next available Node version, if targeted version is not availablePool creation at the Azure DevOps project level using project level permissions Pipelines2023 Q2Future2025 Q2
      Removal of Node 6 and 10 from Microsoft hosted poolsSpot Virtual Machines instance Pipelines2023 Q2Future2025 Q2
      Ship a Node 16 only agent in addition to the one that has all three versions (6, 10, 16)
      Add trusted root certificates Pipelines2023 Q2Future
      Ability to download and install old runners on self-hosted agentsPipelines2023 Q2Future2025 Q2
      Stop shipping Node 6 and Node 10 runners with the agentContainer based agents Pipelines2023 Q2Future2025 Q4
      -### Pipelines checks +### YAML and release pipelines feature parity -Customers prefer YAML pipelines over classic for builds (CI). However, for releases (CD), many customers have continued to use classic release management pipelines over YAML. The primary reason for this is the lack of parity in various CD features between the two solutions. Over the next year, we will invest in bridging these gaps. As a first step, we will focus on **checks**. Checks are the primary mechanism in YAML pipelines to gate promotion of a build from one stage to another. +For the past several years, all our pipelines investments have been in the area of YAML pipelines. Furthermore, all our security improvements have been for YAML pipelines. For example, with YAML pipelines, the control over [protected resources](/azure/devops/pipelines/security/resources) (e.g., repositories, service connections, etc.) is in the hands of the resource owners as opposed to pipeline authors. The [job access tokens](/azure/devops/pipelines/process/access-tokens#scoped-build-identities) that are used in YAML pipelines are scoped to specific repositories that are specified in the YAML file. These are just two examples of security features that are available for YAML pipelines. For these reasons, we recommend using YAML pipelines over classic. Adoption of YAML over classic has been significant for builds (CI). However, many customers have continued to use classic release management pipelines over YAML for releases (CD). The primary reason for this is the lack of parity in various CD features between the two solutions. Over the past year, we addressed several gaps in this area, notably in **Checks**. Checks are the primary mechanism in YAML pipelines to gate promotion of a build from one stage to another. We will continue to address gaps in other areas over the next year. Our focus will be on user experiences, traceability, and environments. - - + @@ -297,264 +313,626 @@ Customers prefer YAML pipelines over classic for builds (CI). However, for relea - - + - - + - - + + + + + + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - -
      Feature AreaServiceServerQuarter
      Auditing for checks Pipelines Done2022 Q4Future
      Custom variables in checksCustom variables in checks Pipelines Done2023 Q1Future
      Checks scalabilityChecks scalability Pipelines2023 Q2FutureDone2023 Q2
      Bypass approvals and checksPipelinesDone2023 Q4
      Sequencing approvals and other checks Pipelines2023 Q3FutureDone2024 Q1
      Deferred approvalsPipelinesDone2024 Q1
      Rerun single stagePipelinesDone2024 Q1
      Manual queuing of stagesPipelinesDone2024 H2
      Stage-level concurrencyPipelinesDone2024 Q3
      Stage-level traceabilityPipelines2025 Q2
      On-demand out of order execution of stagesPipelines2025 Q2
      Service connections in checks Pipelines2023 Q4 Future
      Checks extensibility Pipelines FutureFuture
      -## All features +### Azure Test Plans improvements + +Azure DevOps provides a variety of testing tools and integrations to support different testing needs. These include manual testing, automated testing, and exploratory testing. The platform allows for the creation and management of test plans and test suites, which can be used to track manual testing for sprints or milestones. Additionally, Azure DevOps integrates with CI/CD pipelines, enabling automated test execution and reporting. + +We are ramping up our investments in this area in response to feedback from our most active customer base. Our focus will be on the following aspects of test management: improving end-to-end test traceability; extending support for various programming languages and frameworks for automated testing in Test Plans; redesigning workflows and experiences for consuming test runs and test results. + +Below, you will find several investments that we plan to deliver as part of this initiative: + - - + + + + + - - - - + + + - - - - + + + + - - - + + + - - - + + + - - - + + + - - - + + + - - - - + + + + - - - + + + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + + +
      Timeframe Feature AreaServerQuarter
      Restore deleted test plans and test suites using REST APITest PlansDone2025 Q1
      2023 Q2GitHub Advanced Security for Azure DevOps (public preview)Pipelines and ReposN/AAuto-pause manual test case runTest PlansDone2025 Q1
      Swimlane rules (general availability)BoardsN/A
      Support YAML pipelines in Azure Test PlansTest Plans2025 Q2
      Markdown editor for work item comments (preview)BoardsFutureSupport for Java (JUnit) in Azure Test PlansTest Plans2025 Q2
      Analytics views (general availability)ReportingFutureSupport for Python (PyTest) in Azure Test PlansTest Plans2025 Q2
      Pull request widget for multiple repos (general availability)ReportingFutureSupport for JavaScript (Jest) in Azure Test PlansTest Plans2025 Q2
      Option on Burnup, Burndown, and Velocity charts to included resolved as completedReportingFutureResume paused test cases on by defaultTest Plans2025 Q2
      Track repo cloningReposFuture
      Quick access to Test Results in Test CaseTest Plans2025 Q2
      In-product recommendations for secure settingsPipelinesFutureAdvanced Test Case result historyTest Plans2025 Q2
      Latest Test Outcome in RequirementsTest Plans2025 Q2
      Checks scalabilityView Test Case State in Execute TabTest Plans2025 Q2
      New Test Plans directoryTest Plans2025 Q2
      New Test Run experience - Public PreviewTest Plans2025 Q3
      Enhanced Test Point Result PanelTest Plans2025 Q3
      Support for JavaScript (Playwright) in Azure Test PlansTest Plans2025 Q3
      + +## All features + +## Azure DevOps Services + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + - - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + - - - - + + + - - - + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + - - - - + + - - - + + - - - + + - - - + + - + + + + + + + + + + + + + - - - - + + - - - + + + + + + + +
      TimeframeFeatureArea
      2025 Q2Commits searchGeneral
      Manage high privilege scopes, pipeline decorators, and unpublished extensions + General
      Support state transitions when merging a GitHub pull request + Boards
      Automatically link pull requests when linked to a GitHub branch + Boards
      Auto link the merge commit + Boards
      + Automatically remove branch links when their corresponding GitHub branches are deleted + Boards
      Show build status when using a YAML build pipeline with GitHub repository + Boards
      + ! mentions support for GitHub pull requestsBoards
      Markdown editor for work item multi-line fieldsBoards
      + Report YAML stage status in deployment control on work items + Boards
      Support for GitHub Enterprise Cloud with data residencyBoards & Pipelines
      Stage-level traceability PipelinesFuture
      .NET 6 agent to replace .NET Core 3.1 agentHosted macOS agents on Apple Silicon PipelinesFuture
      Ability to run tasks on next available Node version, if targeted version is not availableOn-demand out of order execution of stages PipelinesFuture
      Support YAML pipelines in Azure Test PlansTest Plans
      Support for Java (JUnit) in Azure Test PlansTest Plans
      Support for Python (PyTest) in Azure Test PlansTest Plans
      Support for JavaScript (Jest) in Azure Test PlansTest Plans
      Resume paused test cases on by defaultTest Plans
      Quick access to Test Results in Test CaseTest Plans
      Advanced Test Case result historyTest Plans
      Latest Test Outcome in RequirementsTest Plans
      View Test Case State in Execute TabTest Plans
      New Test Plans directoryTest Plans
      All in-the-box tasks run on Node 16PipelinesFutureSecret Protection and Code Security plans for Advanced Security GitHub Advanced Security for Azure DevOps
      Removal of Node 6 and 10 from Microsoft hosted poolsPipelinesFuture
      Secret Validity CheckingGitHub Advanced Security for Azure DevOps
      Secret-free deployments from Azure Pipelines (Preview)PipelinesFutureAdvanced Security alert events added to Azure DevOps service hooks frameworkGitHub Advanced Security for Azure DevOps
      Ability to download and install old runners on self-hosted agentsAdding additional metadata for dependency alerts to improve remediationGitHub Advanced Security for Azure DevOps
      2025 Q3New Test Run experience - Public PreviewTest Plans
      Enhanced Test Point Result PanelTest Plans
      Support for JavaScript (Playwright) in Azure Test PlansTest Plans
      Advanced Security events streamed to Azure DevOps audit logGitHub Advanced Security for Azure DevOps
      Link Boards items to Advanced Security AlertsGitHub Advanced Security for Azure DevOps
      FutureAuditing GAGeneral
      Policies to disable authentication methodsGeneral
      PR searchGeneral
      Track repo cloningRepos
      Ability to run tasks on next available Node version, if targeted
      version is not available      		 PipelinesFuture
      Ship a Node 16 only agent in addition to the one that has all three versions (6, 10, 16)Support Pipelines App with GitHub Enterprise PipelinesFuture
      Stop shipping Node 6 and Node 10 runners with the agentPipelinesFutureService connections in checksPipelines
      Sort test plans by any columnTest Plans2022.1Checks extensibilityPipelines
      Improved support for code coverage publishing within Azure PipelinesTest PlansFutureSeamless build pipeline integration for Test Case RunTest Plans
      Pause and resume manual test executionTest Plans2022.1Support for Java (Playwright) in Azure Test PlanTest Plans
      Support for Cargo package manager for RustSupport for Python (UnitTest & Robot) in Azure Test PlansTest Plans
      Support for PHP (PHPUnit & Pest) in Azure Test PlansTest Plans
      Customizable flaky test detection logicTest Plans
      Package promote task in Azure Pipelines ArtifactsN/A
      Granular scopes for Azure Active Directory OAuthGeneralN/ADeprecate old Azure Artifacts tasks in Azure Pipelines and default to new, auth-only tasksArtifacts
      Increased transparency into the progress of an Azure DevOps Server to Azure DevOps Services data migrationGeneralN/ADependabot Security Update SupportGitHub Advanced Security for Azure DevOps
      CodeQL default setup (one-click enablement)GitHub Advanced Security for Azure DevOps
      + +## Azure DevOps Server + + + + + + + + + + - - - - + + + - + + + + + + + + + - + + + + + + + - - - + + - - - - + + + - - - + + + + + + - - - + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + - - - - + + + - + + + + + - - + + + + - - - - + - - - + + - - - + + - - - + + - - - + + - - - + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TimeframeFeatureArea
      2023 Q3GitHub Advanced Security for Azure DevOps (general availability)Pipelines and ReposN/A2025 H2Automated team work item rulesBoards
      Markdown editor for work item comments (general availability)Add link to GitHub commit or pull request from work itemBoards
      Show more details about a GitHub pull requestBoards
      Markdown editor for work item comments BoardsFuture
      New Boards Hub on by defaultBoards
      Create branch on GitHub repository from work itemBoards
      Additional fields on page filtersBoardsFutureImprove scalability when searching and linking GitHub
      repos to an Azure DevOps project      		Boards
      Automated team work item rulesBoardsFuture
      Create branch on GitHub repository from work itemBoards
      Chart click thru to results by sectionReportingFutureImprove scalability when searching and linking GitHub
      repos to an Azure DevOps project      		Boards
      All in-the-box tasks run on Node 16Pipelines
      Rollup columns for query resultsReportingFutureAbility to download and install old runners on self-hosted agentsPipelines
      FutureAbility to run tasks on next available Node version, if targeted version is not availablePipelines
      Removal of Node 6 and 10 from Microsoft hosted poolsPipelines
      Sequencing approvals and other checksPipelines
      In-product recommendations for secure settingsPipelines
      Manual queuing of stagesPipelines
      Rerun single stagePipelines
      Stage-level concurrencyPipelines
      Stage-level traceabilityPipelines
      FuturePolicies to disable authentication methodsGeneral
      Substring searchGeneral
      Commits searchGeneral
      PR searchGeneral
      + New Boards Hub + Boards
      Markdown editor for work item multi-line fields BoardsFuture
      Delivery plans improvements to filtering by parentBoardsFuture
      Track repo cloningRepos
      Support Flexible Orchestration mode in scale set agent poolsStop shipping Node 6 and Node 10 runners with the agentPipelines
      Ship a Node 16 only agent in addition to the one that has all three versions (6, 10, 16) PipelinesFuture
      Support Pipelines App with GitHub Enterprise PipelinesFuture
      Service connections in checksPipelines
      Checks extensibility PipelinesFuture
      Package promote task in Azure Pipelines ArtifactsFuture
      Deprecate old Azure Artifacts tasks in Azure Pipelines and default to new, auth-only tasks ArtifactsFuture
      Auditing GAGeneralN/ADashboard Global ParameterReporting
      Policies to disable alternate authentication credentialsGeneralN/ADashboard TemplateReporting
      Full support for Conditional Access PoliciesGeneralFutureSeamless build pipeline integration for Test Case RunTest Plans
      Access events for PAT, SSH will be available in the Auditing LogGeneralFutureAdvanced Test Case result historyTest Plans
      Support Azure Managed Identities and Service Principals (GA)GeneralN/ALatest Test Outcome in RequirementsTest Plans
      Direct link from Test Plan work item to Test Plans pageTest Plans
      Auto-pause manual test case runTest Plans
      Resume paused test cases on by defaultTest Plans
      Undo test step in web and desktop runnerTest Plans
      Export test cases with custom columns in XLSXTest Plans
      Restore deleted test plans and test suites using REST APITest Plans
      View Test Case State in Execute TabTest Plans
      New Test Plans directoryTest Plans
      New Test Run experienceTest Plans
      Enhanced Test Point Result PanelTest Plans
      Support for Java (JUnit) in Azure Test PlansTest Plans
      Support for JavaScript (Jest) in Azure Test PlansTest Plans
      Support for Python (UnitTest & Robot) in Azure Test PlansTest Plans
      Support for JavaScript (Playwright) in Azure Test PlansTest Plans
      Support for PHP (PHPUnit & Pest) in Azure Test PlansTest Plans
      Support for Java (Playwright) in Azure Test PlanTest Plans
      Customizable flaky test detection logicTest Plans
      - --- ## How to provide feedback diff --git a/release-notes/media/make-a-suggestion.png b/release-notes/media/make-a-suggestion.png index be0fa449789..1ae1e8802bb 100644 Binary files a/release-notes/media/make-a-suggestion.png and b/release-notes/media/make-a-suggestion.png differ diff --git a/release-notes/roadmap/2022/checks-scalability.md b/release-notes/roadmap/2022/checks-scalability.md index 4f222bb8b21..70c9d169167 100644 --- a/release-notes/roadmap/2022/checks-scalability.md +++ b/release-notes/roadmap/2022/checks-scalability.md @@ -12,9 +12,9 @@ hide_comments: true # Checks scalability -As customers shifted their release pipelines to YAML from classic release management, the first challenge we encountered was handling checks at high scale. Two of the most commonly used checks are the [Azure functions](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass#invoke-azure-function&preserve-view=true) and [REST API](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass#invoke-rest-api&preserve-view=true) checks. The default experience in Azure Pipelines results in creating sychronous calls from Azure Pipelines into Azure functions or your REST server. On top of that, these calls are retried frequently until the check passes. This design is simple and works well for small workloads. However, it does not scale when there are a large number of checks, when the function or REST server takes more time to respond, or when there are a large number of retries. +As customers shifted their release pipelines to YAML from classic release management, the first challenge we encountered was handling checks at high scale. Two of the most commonly used checks are the [Azure functions](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass#invoke-azure-function&preserve-view=true) and [REST API](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass#invoke-rest-api&preserve-view=true) checks. The default experience in Azure Pipelines results in creating synchronous calls from Azure Pipelines into Azure functions or your REST server. On top of that, these calls are retried frequently until the check passes. This design is simple and works well for small workloads. However, it does not scale when there are a large number of checks, when the function or REST server takes more time to respond, or when there are a large number of retries. -We will streamline our asynchrononous checks implementation, also known as the [callback model](/azure/devops/pipelines/tasks/utility/azure-function?view=azure-devops#is-there-an-example-of-an-azure-function-that-uses-the-callback-completion-mode&preserve-view=true), and change the experience in the product to recommend that over the synchronous model. Using the callback model, the Azure function or REST server can decide to fail or pass the check at any time before a timeout is reached, thereby eliminating the need for retries altogether. This model also allows the Azure function or REST server to take as much time as it needs to evaluate the check without consuming compute resources in Azure Pipelines. +We will streamline our asynchronous checks implementation, also known as the [callback model](/azure/devops/pipelines/tasks/utility/azure-function?view=azure-devops#is-there-an-example-of-an-azure-function-that-uses-the-callback-completion-mode&preserve-view=true), and change the experience in the product to recommend that over the synchronous model. Using the callback model, the Azure function or REST server can decide to fail or pass the check at any time before a timeout is reached, thereby eliminating the need for retries altogether. This model also allows the Azure function or REST server to take as much time as it needs to evaluate the check without consuming compute resources in Azure Pipelines. diff --git a/release-notes/roadmap/2022/node-20-agent.md b/release-notes/roadmap/2022/node-20-agent.md new file mode 100644 index 00000000000..5a7d38b4e3b --- /dev/null +++ b/release-notes/roadmap/2022/node-20-agent.md @@ -0,0 +1,17 @@ +--- +title: Ship a Node 20 only agent that does not include end-of-life Node versions +author: gloridelmorales +ms.author: glmorale +ms.date: 10/12/2022 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Ship a Node 20 only agent that does not include end-of-life Node versions +hide_comments: true +--- + +# Ship a Node 20 only agent that does not include end-of-life Node versions + +Once we have all built-in Node tasks converted to work on the Node 20 runner, we will ship an agent with only the Node 20 runner (no end-of-life versions) for our security-conscious customers. Various customers have asked us to ship such an agent sooner since their security scans flag the Azure Pipelines agent as using an unsupported or end-of-life version of Node. Using the Node 20 only agent will also protect you from any vulnerabilities that are found in older versions of Node. + +We will be shipping this agent package *in addition* to the one that has all three Node runners. If you wish to set up a self-hosted agent pool, you will then have a choice of using either the Node 20 only agent or the one with all Node runners. In general, you will choose the Node 20 agent only if you are sure that all your custom tasks and those that you use from Marketplace will run on the new Node 20 task runner. \ No newline at end of file diff --git a/release-notes/roadmap/2022/resume-test-execution.md b/release-notes/roadmap/2022/resume-test-execution.md deleted file mode 100644 index a96b353a41e..00000000000 --- a/release-notes/roadmap/2022/resume-test-execution.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Pause and resume manual test execution. -author: aaronhallberg -ms.author: aaronha -ms.date: 10/10/2022 -ms.topic: article -ms.service: azure-devops -ms.subservice: azure-devops-release-notes -description: Pause and resume manual test execution in Azure Test Plans -hide_comments: true ---- - -# Pause and resume manual test execution in Azure Test Plans - -When manual testers are executing the steps of a particularly complicated or long-running test case, they may from -time to time wish to *pause* their work and then resume it later. Today this is more complicated and less intuitive -than it should be. And some scenarios, such as resuming the execution of the test case in the desktop test runner, -are not supported at all. This feature will focus on improving the experience of pausing and resuming test execution, -including adding support for resuming execution in either the web or desktop test runners. diff --git a/release-notes/roadmap/2022/secret-free-acr-deployments.md b/release-notes/roadmap/2022/secret-free-acr-deployments.md new file mode 100644 index 00000000000..4e19a05b543 --- /dev/null +++ b/release-notes/roadmap/2022/secret-free-acr-deployments.md @@ -0,0 +1,15 @@ +--- +title: Workload identity federation for Docker service connection +author: gloridelmorales +ms.author: glmorale +ms.date: 10/11/2022 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Workload identity federation for Docker service connection +hide_comments: true +--- + +# Workload identity federation for Docker service connection + +Workload identity federation for the Azure service connection is now [generally available](/azure/devops/release-notes/roadmap/2022/secret-free-azurerm-deployments). We will work on supporting Workload identity federation for Azure-based Docker service connections next. This will help you eliminate secrets in the following use cases: (a) Run on a container job using a container from a private registry (b) Use a container from a private registry as a resource in the pipeline (c) Build and publish container images to a private Docker registry. diff --git a/release-notes/roadmap/2022/secret-free-azurerm-deployments.md b/release-notes/roadmap/2022/secret-free-azurerm-deployments.md new file mode 100644 index 00000000000..c7a4a93cc6c --- /dev/null +++ b/release-notes/roadmap/2022/secret-free-azurerm-deployments.md @@ -0,0 +1,17 @@ +--- +title: Workload identity federation for Azure service connection +author: gloridelmorales +ms.author: glmorale +ms.date: 10/11/2022 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Workload identity federation for Azure service connection +hide_comments: true +--- + +# Workload identity federation for Azure service connection + +Pipelines often depend on service connections that store secrets. A common use case for Pipelines is to deploy applications to Azure using an ARM service connection. Each connection stores either the Azure Service Principal's password or certificate in Azure DevOps. The main drawbacks of storing these credentials in Azure DevOps are (a) the service connections have to be updated in Azure DevOps every time you update them in Azure, and (b) Tasks in pipelines that consume these service connections will have access to these secrets. Many customers would like to avoid storing secrets in Azure DevOps. They do not want the trouble of rotating these secrets on a regular basis, and they want to reduce the risk of these secrets getting exposed and stolen. + +Workload identity federation for the Azure service connection is [generally available](https://devblogs.microsoft.com/devops/workload-identity-federation-for-azure-deployments-is-now-generally-available/). diff --git a/release-notes/roadmap/2022/secret-free-deployments.md b/release-notes/roadmap/2022/secret-free-deployments.md deleted file mode 100644 index 8d910f78f3d..00000000000 --- a/release-notes/roadmap/2022/secret-free-deployments.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Secret-free deployments from Azure Pipelines -author: gloridelmorales -ms.author: glmorale -ms.date: 10/11/2022 -ms.topic: article -ms.service: azure-devops -ms.subservice: azure-devops-release-notes -description: Secret-free deployments from Azure Pipelines -hide_comments: true ---- - -# Secret-free deployments from Azure Pipelines - -Pipelines often depend on service connections that store secrets. A common use case for Pipelines is to deploy applications to Azure using an ARM service connection. Each connection stores either the Azure Service Principal's password or certificate in Azure DevOps. The main drawbacks of storing these credentials in Azure DevOps are (a) the service connections have to be updated in Azure DevOps every time you update them in Azure, and (b) Tasks in pipelines that consume these service connections will have access to these secrets. Many customers would like to avoid storing secrets in Azure DevOps. They do not want the trouble of rotating these secrets on a regular basis, and they want to reduce the risk of these secrets getting exposed and stolen. - -Azure now supports [workload identity federation](/azure/active-directory/develop/workload-identity-federation) using the Open ID Connect protocol. This allows us to create secret-free service connections in Azure Pipelines that are backed by service principals with federated credentials in Azure Active Directory. As part of its execution, a pipeline can exchange its own internal token with an AAD token, thereby gaining access to Azure resources. Once implemented, this mechanism will be recommended in the product over [other types of Azure service connections](/azure/devops/pipelines/library/connect-to-azure?view=azure-devops&preserve-view=true) that exist today. This mechanism can also be used to set up secret-free deployments with any other OIDC compliant service provider. - -When we are ready with this feature, we will first invite a few customers for private preview, followed by a public preview in 2023 Q2. \ No newline at end of file diff --git a/release-notes/roadmap/2022/service-connections-in-checks.md b/release-notes/roadmap/2022/service-connections-in-checks.md index 5f9ffa710f2..7ab187d7c34 100644 --- a/release-notes/roadmap/2022/service-connections-in-checks.md +++ b/release-notes/roadmap/2022/service-connections-in-checks.md @@ -12,4 +12,4 @@ hide_comments: true # Service connections in checks -[Azure functions](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass#invoke-azure-function&preserve-view=true) and [REST API](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass#invoke-rest-api&preserve-view=true) checks require Azure or REST server credentials (app key) to be stored in Azure Pipelines. As we invest in mechanisms to reduce the storage of secrets in Azure DevOps, we would like your experience with checks to also benefit from those investments. For instance, if you create a [secret-free service connection](./secret-free-deployments.md) to Azure, you should be able to use that in order to interact with the Azure function. We will use the same service connections to connect to external services from checks as we do from tasks running on an agent. +[Azure functions](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass#invoke-azure-function&preserve-view=true) and [REST API](/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass#invoke-rest-api&preserve-view=true) checks require Azure or REST server credentials (app key) to be stored in Azure Pipelines. As we invest in mechanisms to reduce the storage of secrets in Azure DevOps, we would like your experience with checks to also benefit from those investments. For instance, if you create a [secret-free service connection](./secret-free-azurerm-deployments.md) to Azure, you should be able to use that in order to interact with the Azure function. We will use the same service connections to connect to external services from checks as we do from tasks running on an agent. diff --git a/release-notes/roadmap/2023/alphabetical-sort.md b/release-notes/roadmap/2023/alphabetical-sort.md new file mode 100644 index 00000000000..2312a743fab --- /dev/null +++ b/release-notes/roadmap/2023/alphabetical-sort.md @@ -0,0 +1,15 @@ +--- +title: Sort test suites in alphabetical order +author: gloridelmorales +ms.author: glmorale +ms.date: 10/16/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Sort test suites in alphabetical order +hide_comments: true +--- + +# Sort test suites in alphabetical order + +We’re providing additional capability to sort test suites in alphabetical order. Users can further choose to implement the sorting in ascending (A-Z) or descending (Z-A) order. Currently, test suites are sorted by creation date (newest on top) by default. \ No newline at end of file diff --git a/release-notes/roadmap/2023/boards-bot-better-ab-validation.md b/release-notes/roadmap/2023/boards-bot-better-ab-validation.md new file mode 100644 index 00000000000..e62f91848a2 --- /dev/null +++ b/release-notes/roadmap/2023/boards-bot-better-ab-validation.md @@ -0,0 +1,20 @@ +--- +title: Improved AB# validation +author: danhellem +ms.author: dahellem +ms.date: 10/30/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Improved AB# validation +hide_comments: true +--- + +# Improved AB# validation + +Improve the Azure Boards GitHub app to inform users when a link to a work item is invalid. This will help users to identify and fix before the Pull Request is merged. + +Example: + +> [!div class="mx-imgBorder"] +> ![screen shot example AB# validation from bot](media\boards-github-ab-validation.png) \ No newline at end of file diff --git a/release-notes/roadmap/2023/bypass-checks.md b/release-notes/roadmap/2023/bypass-checks.md new file mode 100644 index 00000000000..e0b4a124df5 --- /dev/null +++ b/release-notes/roadmap/2023/bypass-checks.md @@ -0,0 +1,18 @@ +--- +title: Bypassing approvals and checks +author: silviuandrica +ms.author: sandrica +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Bypassing approvals and checks +hide_comments: true +--- + +# Bypassing approvals and checks + +In YAML pipelines, a stage can't run before all approvals and checks pass. +This requirement makes it difficult to do hotfix deployments, because one or more checks aren't passing. +For example, a Business Hours check forces you to do deployments during the night, but your hotfix deployment must happen during business hours. +We plan to give you the ability to bypass running checks and approvals, to cover some common scenarios such as the previous one. diff --git a/release-notes/roadmap/2023/chart-click-thru-to-results-by-section.md b/release-notes/roadmap/2023/chart-click-thru-to-results-by-section.md index 183803310e0..1c34ae7a5e0 100644 --- a/release-notes/roadmap/2023/chart-click-thru-to-results-by-section.md +++ b/release-notes/roadmap/2023/chart-click-thru-to-results-by-section.md @@ -1,20 +1,20 @@ --- -title: Chart click thru to results by section +title: Work Item Chart Filtering author: danhellem ms.author: dahellem -ms.date: 04/13/2023 +ms.date: 11/13/2023 ms.topic: article ms.service: azure-devops ms.subservice: azure-devops-release-notes -description: Chart click thru to results by section +description: Work Item Chart Filtering hide_comments: true --- -# Chart click thru to results by section +# Work Item Chart Filtering As a user, when I click on a section of a work item chart, I want to see the query results just for that section. For example: When looking at the **Bugs by State** chart, when I click on the New section, that would load a query to display just the New work items. > [!div class="mx-imgBorder"] > ![screen showing chart click thru](media/reporting-chart-click-thru-1.png) -[Community suggestion ticket](https://developercommunity.visualstudio.com/t/clicking-a-graph-or-chart-section-should-display-s-1/526855) \ No newline at end of file +[Community suggestion ticket](https://developercommunity.visualstudio.com/t/clicking-a-graph-or-chart-section-should-display-s-1/526855) diff --git a/release-notes/roadmap/2023/charts-option-for-resolved-as-closed.md b/release-notes/roadmap/2023/charts-option-for-resolved-as-closed.md index 15084ab2db2..ecc97817fba 100644 --- a/release-notes/roadmap/2023/charts-option-for-resolved-as-closed.md +++ b/release-notes/roadmap/2023/charts-option-for-resolved-as-closed.md @@ -26,4 +26,4 @@ Charts affected are: - Velocity chart on Analytics tab > [!div class="mx-imgBorder"] -> ![Screen showing otpion to make resolved items track as completed.](media/reporting-resolved-category-as-completed-check.gif) \ No newline at end of file +> ![Screen showing option to make resolved items track as completed.](media/reporting-resolved-category-as-completed-check.gif) diff --git a/release-notes/roadmap/2023/code-coverage-policy.md b/release-notes/roadmap/2023/code-coverage-policy.md new file mode 100644 index 00000000000..93ef7842f47 --- /dev/null +++ b/release-notes/roadmap/2023/code-coverage-policy.md @@ -0,0 +1,15 @@ +--- +title: Code coverage policy at a folder level +author: gloridelmorales +ms.author: glmorale +ms.date: 10/6/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Code coverage policy at a folder level +hide_comments: true +--- + +# Code coverage policy at a folder level + +We’ve introduced “Folder view” for code coverage recently. Now we want to take a next step and allow our users to enforce code coverage policy for the pull requests on a folder level. \ No newline at end of file diff --git a/release-notes/roadmap/2023/commits-search.md b/release-notes/roadmap/2023/commits-search.md new file mode 100644 index 00000000000..a84c1d5a2a9 --- /dev/null +++ b/release-notes/roadmap/2023/commits-search.md @@ -0,0 +1,14 @@ +--- +title: Commits search +author: gloridelmorales +ms.author: glmorale +ms.date: 10/6/2022 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Commits search +hide_comments: true +--- +# Commits search + +Easily look for commits by their title and description right from Azure DevOps global search. \ No newline at end of file diff --git a/release-notes/roadmap/2023/dataimport-progresspage.md b/release-notes/roadmap/2023/dataimport-progresspage.md index d3403cec187..605eeaa65f3 100644 --- a/release-notes/roadmap/2023/dataimport-progresspage.md +++ b/release-notes/roadmap/2023/dataimport-progresspage.md @@ -1,7 +1,7 @@ --- title: Increased transparency into the progress of an Azure DevOps Server to Azure DevOps Services data migration -author: bawolfso -ms.author: bawolfso +author: gloridelmorales +ms.author: glmorale ms.date: 03/14/2023 ms.topic: article ms.service: azure-devops diff --git a/release-notes/roadmap/2023/export-test-plan.md b/release-notes/roadmap/2023/export-test-plan.md new file mode 100644 index 00000000000..0547fa13679 --- /dev/null +++ b/release-notes/roadmap/2023/export-test-plan.md @@ -0,0 +1,17 @@ +--- +title: Export Test Plan in XLSX format +author: gloridelmorales +ms.author: glmorale +ms.date: 10/16/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Export Test Plan in XLSX format +hide_comments: true +--- + +# Export Test Plan in XLSX format + +Customers of Azure Test plans need to export data for a wide variety of use-cases. Currently, users can only export Test plan data (with all nested suites and latest test outcome) into PDF and HTML formats. We’re improving our export capability by adding support for Microsoft Excel supported format (i.e. XLSX) as well. + +This will allow customers to easily edit/modify the exported data as per their needs. \ No newline at end of file diff --git a/release-notes/roadmap/2023/generate-code-coverage-results.md b/release-notes/roadmap/2023/generate-code-coverage-results.md new file mode 100644 index 00000000000..f8c48e8b566 --- /dev/null +++ b/release-notes/roadmap/2023/generate-code-coverage-results.md @@ -0,0 +1,15 @@ +--- +title: Generate code coverage results in source /folder level view +author: gloridelmorales +ms.author: glmorale +ms.date: 6/21/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Generate code coverage results in source /folder level view. +hide_comments: true +--- + +# Generate code coverage results in source /folder level view + +Customers can view their code coverage results in ‘Project’ view today. This informs them of the code coverage percentage of the various DLL files being tested. However, in the case of monolith repositories, customers can have multiple microservices under the same repository. Hence, customers are unable to quantify the code coverage of their individual microservices. Automated testing is solving this problem by showcasing code coverage insights at a source level. This will allow developers to better quantify the code coverage results of their microservices and take mitigation steps accordingly. \ No newline at end of file diff --git a/release-notes/roadmap/2023/improve-traceability.md b/release-notes/roadmap/2023/improve-traceability.md new file mode 100644 index 00000000000..98c660e9eeb --- /dev/null +++ b/release-notes/roadmap/2023/improve-traceability.md @@ -0,0 +1,15 @@ +--- +title: Improve traceability of in-progress test executions +author: gloridelmorales +ms.author: glmorale +ms.date: 10/16/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Improve traceability of in-progress test executions +hide_comments: true +--- + +# Improve traceability of in-progress test executions + +Manual testers often start working on a test case but cannot immediately mark it as pass, fail etc. They might need to do offline consultations before arriving at the outcome. Hence, sometime there is a delay between starting the work on a test-point vs completing the test run. We’re improving the experience to capture these transient in-progress test executions better. \ No newline at end of file diff --git a/release-notes/roadmap/2023/improved-visibility.md b/release-notes/roadmap/2023/improved-visibility.md new file mode 100644 index 00000000000..ab35678c104 --- /dev/null +++ b/release-notes/roadmap/2023/improved-visibility.md @@ -0,0 +1,15 @@ +--- +title: New Test Runs experience +author: gloridelmorales +ms.author: glmorale +ms.date: 10/16/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: New Test Runs experience +hide_comments: true +--- + +# New Test Runs experience + +We're are redesigning the Test Runs experience to let users work with test runs and test results in a much simpler way. The new design will also make it easier to understand the co-relation between test results and the version of a test case definition used to execute that particular run. Test Runs is an important part of Azure Test Plans product and these improvements will address long-standing user needs around post execution analysis. \ No newline at end of file diff --git a/release-notes/roadmap/2023/improvements-to-code-coverage.md b/release-notes/roadmap/2023/improvements-to-code-coverage.md new file mode 100644 index 00000000000..8b3d2cd3ab5 --- /dev/null +++ b/release-notes/roadmap/2023/improvements-to-code-coverage.md @@ -0,0 +1,15 @@ +--- +title: Improvements to code coverage user experience in Pipeline results page +author: gloridelmorales +ms.author: glmorale +ms.date: 6/21/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Improvements to code coverage user experience in Pipeline results page. +hide_comments: true +--- + +# Improvements to code coverage user experience in Pipeline results page + +Customers can view code coverage information of their pipeline builds from the pipeline results page. This experience is surfaced to customers through a dedicated Code coverage tab within the results page. We are planning some major updates to the code coverage tab to help our customers drive more value. We are adding a new layer of experience to better inform customers of the various stages as their code coverage results get generated. We are also surfacing error messages more proactively to help customers debug issues in case of results generation failure. \ No newline at end of file diff --git a/release-notes/roadmap/2023/junit-java-support.md b/release-notes/roadmap/2023/junit-java-support.md new file mode 100644 index 00000000000..b15fc78d450 --- /dev/null +++ b/release-notes/roadmap/2023/junit-java-support.md @@ -0,0 +1,15 @@ +--- +title: JUnit / Java support in Test Plans +author: gloridelmorales +ms.author: glmorale +ms.date: 10/6/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: JUnit / Java support in Test Plans +hide_comments: true +--- + +# JUnit / Java support in Test Plans + +Currently it is possible to link VSTest automated tests to test cases which are part of Test Plans. We are going to expand the list of supported frameworks here and allow linking and executing automated tests written with JUnit / Java. \ No newline at end of file diff --git a/release-notes/roadmap/2023/media/boards-github-ab-validation.png b/release-notes/roadmap/2023/media/boards-github-ab-validation.png new file mode 100644 index 00000000000..5c540c92856 Binary files /dev/null and b/release-notes/roadmap/2023/media/boards-github-ab-validation.png differ diff --git a/release-notes/roadmap/2023/media/boards-new-boards-on-by-default-1.gif b/release-notes/roadmap/2023/media/boards-new-boards-on-by-default-1.gif new file mode 100644 index 00000000000..2ee13d496ac Binary files /dev/null and b/release-notes/roadmap/2023/media/boards-new-boards-on-by-default-1.gif differ diff --git a/release-notes/roadmap/2023/media/boards-team-rules-1.png b/release-notes/roadmap/2023/media/boards-team-rules-1.png index 43fc937a9c8..818e1a4c146 100644 Binary files a/release-notes/roadmap/2023/media/boards-team-rules-1.png and b/release-notes/roadmap/2023/media/boards-team-rules-1.png differ diff --git a/release-notes/roadmap/2023/new-boards-hub-on-by-default.md b/release-notes/roadmap/2023/new-boards-hub-on-by-default.md new file mode 100644 index 00000000000..855aec839f1 --- /dev/null +++ b/release-notes/roadmap/2023/new-boards-hub-on-by-default.md @@ -0,0 +1,18 @@ +--- +title: New Boards Hub on by default +author: danhellem +ms.author: dahellem +ms.date: 06/23/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: New Boards Hub on by default +hide_comments: true +--- + +# New Boards Hub on by default + +The [New Boards Hub preview](https://devblogs.microsoft.com/devops/new-boards-hub-public-preview/) will now be the default experience for all users. You'll have the ability to revert back to the old boards hub, for a short period of time, while we continue to collect and address feedback on New Boards Hub. + +> [!div class="mx-imgBorder"] +> ![image of new boards hub on by default banner](media/boards-new-boards-on-by-default-1.gif) \ No newline at end of file diff --git a/release-notes/roadmap/2023/recycle-bin-improvements.md b/release-notes/roadmap/2023/recycle-bin-improvements.md index b0ac3e205ef..6f4ad3bc7f8 100644 --- a/release-notes/roadmap/2023/recycle-bin-improvements.md +++ b/release-notes/roadmap/2023/recycle-bin-improvements.md @@ -19,4 +19,4 @@ As a user with permanently delete work item permissions, I need to be able to: - Recycle bin actions and response times need to be fast > [!NOTE] -> We have decided to forego implemention of this feature. Initially, we planned to revamp the recycle bin functionality in order to address performance concerns at scale with New Boards Hub. However, we were able to resolve these issues without the need for major changes. We will reassess the status of the recycle bin feature once the [New Boards Hub](https://devblogs.microsoft.com/devops/new-boards-hub-public-preview/) is no longer in preview. \ No newline at end of file +> We have decided to forego implementation of this feature. Initially, we planned to revamp the recycle bin functionality in order to address performance concerns at scale with New Boards Hub. However, we were able to resolve these issues without the need for major changes. We will reassess the status of the recycle bin feature once the [New Boards Hub](https://devblogs.microsoft.com/devops/new-boards-hub-public-preview/) is no longer in preview. \ No newline at end of file diff --git a/release-notes/roadmap/2023/reduce-time-to-filter.md b/release-notes/roadmap/2023/reduce-time-to-filter.md new file mode 100644 index 00000000000..b64ea8fd847 --- /dev/null +++ b/release-notes/roadmap/2023/reduce-time-to-filter.md @@ -0,0 +1,15 @@ +--- +title: Reduce time to filter test plans and test suites in copy & import operations +author: gloridelmorales +ms.author: glmorale +ms.date: 10/16/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Reduce time to filter test plans and test suites in copy & import operations +hide_comments: true +--- + +# Reduce time to filter test plans and test suites in copy and import operations + +Copy and import operations in Azure Test Plans require an entire list of test plans and test suites to load first into the browser. This can become time consuming for organizations with large volume of test plans and test suites. Hence, we’re introducing an additional search capability where you can directly enter the Test Plan ID or Suite ID and quickly search for their relevant test plan or test suite. \ No newline at end of file diff --git a/release-notes/roadmap/2023/substring-search.md b/release-notes/roadmap/2023/substring-search.md new file mode 100644 index 00000000000..071f461c426 --- /dev/null +++ b/release-notes/roadmap/2023/substring-search.md @@ -0,0 +1,14 @@ +--- +title: Substring search +author: gloridelmorales +ms.author: glmorale +ms.date: 10/6/2022 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Substring search +hide_comments: true +--- +# Substring search + +Wrap your search term into wildcard operators to get those search results which contain the term as a substring. For example: if you use *test* as a search term, you will get mytestclass, test_wikiarticle as search results. You can use wildcard as a prefix or suffix or both at the same time, and that will work across all searchable entities of Azure DevOps: Code, Work items, Wiki and Packages. \ No newline at end of file diff --git a/release-notes/roadmap/2023/swimlane-rules.md b/release-notes/roadmap/2023/swimlane-rules.md index e5f20cf9be8..16152a54f01 100644 --- a/release-notes/roadmap/2023/swimlane-rules.md +++ b/release-notes/roadmap/2023/swimlane-rules.md @@ -6,8 +6,7 @@ ms.date: 10/11/2022 ms.topic: article ms.service: azure-devops ms.subservice: azure-devops-release-notes -description: Swimlane rule on Kanban board -hide_comments: true +description: Swimlane rule on Kanban boa --- # Swimlane rules diff --git a/release-notes/roadmap/2023/test-plan-task-in-pipelines.md b/release-notes/roadmap/2023/test-plan-task-in-pipelines.md new file mode 100644 index 00000000000..edc3fab9d95 --- /dev/null +++ b/release-notes/roadmap/2023/test-plan-task-in-pipelines.md @@ -0,0 +1,15 @@ +--- +title: Test Plan task in Pipelines +author: gloridelmorales +ms.author: glmorale +ms.date: 10/6/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Test Plan task in Pipelines +hide_comments: true +--- + +# Test Plan task in Pipelines + +Make Test Plan run part of your Pipeline run. New task will allow you to trigger Test Plan execution (even if it contains only manual test cases) from your Build or Release Pipeline run. This new task will help you to make sure that nothing gets released without proper testing. \ No newline at end of file diff --git a/release-notes/roadmap/2023/work-item-support-for-markdown.md b/release-notes/roadmap/2023/work-item-support-for-markdown.md index 764a627b973..effd9f02174 100644 --- a/release-notes/roadmap/2023/work-item-support-for-markdown.md +++ b/release-notes/roadmap/2023/work-item-support-for-markdown.md @@ -14,4 +14,4 @@ hide_comments: true As a user, I want to be able to use markdown when editing long text fields (Description, Repo Steps, etc.) and the Work Item discussion. -[Community Suggestion Ticket](https://developercommunity.visualstudio.com/t/add-markdown-support-in-discussions/365826) \ No newline at end of file +[Community Suggestion Ticket](https://developercommunity.visualstudio.com/t/support-markdown-as-an-alternative-to-html-for-wor/365464) diff --git a/release-notes/roadmap/2024/add-link-to-github-from-work-item.md b/release-notes/roadmap/2024/add-link-to-github-from-work-item.md new file mode 100644 index 00000000000..1dd814db9c9 --- /dev/null +++ b/release-notes/roadmap/2024/add-link-to-github-from-work-item.md @@ -0,0 +1,23 @@ +--- +title: Add link to GitHub Commit or Pull Request from work item +author: danhellem +ms.author: dahellem +ms.date: 10/30/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Add link to GitHub Commit or Pull Request from work item +hide_comments: true +--- + +# Add link to GitHub Commit or Pull Request from work item + +Improve the experience of adding a link to a GitHub commit or pull request from a work item. The new experience will allow you to search for the commit or pull request and select it from a list of repositories. This will make it easier to link to the correct commit or pull request. + +Example: + +> [!div class="mx-imgBorder"] +> ![screen shot example adding link to Github](media\add-link-to-github.png) + +> [!NOTE] +> This feature will only be available with the [**New Boards Hubs** preview](https://devblogs.microsoft.com/devops/new-boards-hub-public-preview/). \ No newline at end of file diff --git a/release-notes/roadmap/2024/agent-uses-dotnet-8.md b/release-notes/roadmap/2024/agent-uses-dotnet-8.md new file mode 100644 index 00000000000..a46520d6362 --- /dev/null +++ b/release-notes/roadmap/2024/agent-uses-dotnet-8.md @@ -0,0 +1,15 @@ +--- +title: Pipeline Agent uses .NET 8 +author: gloridelmorales +ms.author: glmorale +ms.date: 4/24/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Pipeline Agent uses .NET 8 +hide_comments: true +--- + +# Pipeline Agent uses .NET 8 + +As .NET 6 reaches its end-of-life in November 2024, we will upgrade the pipeline agent to run on .NET 8. This update will be seamless to most customers. However, it will impact you if you are running the agent on an older operating system that is no longer supported by .NET 6. \ No newline at end of file diff --git a/release-notes/roadmap/2024/boards-ab-links-github-pr.md b/release-notes/roadmap/2024/boards-ab-links-github-pr.md new file mode 100644 index 00000000000..b9214fbce01 --- /dev/null +++ b/release-notes/roadmap/2024/boards-ab-links-github-pr.md @@ -0,0 +1,18 @@ +--- +title: AB# links to appear in Development control of the GitHub pull request +author: danhellem +ms.author: dahellem +ms.date: 04/09/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: AB# links to appear in Development control of the GitHub pull request +hide_comments: true +--- + +# AB# links to appear in Development control of the GitHub pull request + +When you add AB# links to a GitHub pull request, show those links in the Development control of the pull request. This will provide a better experience for users who are using Azure Boards and GitHub together. + +> [!div class="mx-imgBorder"] +> ![screen shot example ab links on github pull request page](media\boards-ab-links-github-pr.png) diff --git a/release-notes/roadmap/2024/boards-area-iteration-level-fields.md b/release-notes/roadmap/2024/boards-area-iteration-level-fields.md new file mode 100644 index 00000000000..cfa4eeb39d0 --- /dev/null +++ b/release-notes/roadmap/2024/boards-area-iteration-level-fields.md @@ -0,0 +1,22 @@ +--- +title: Area and iteration level fields +author: danhellem +ms.author: dahellem +ms.date: 09/4/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Area level and iteration level fields +hide_comments: true +--- + +# Enable area and iteration level fields + +Area and iteration level fields have long been a valuable part of the product, allowing users to query or display results based on the specific levels at which they are defined: + +(Root) Level 1 / Level 2 / Level 3 / etc. + +Historically these fields have only been available on a few select organizations. Lets change that by enabling the Area level and Iteration level fields for all organizations. + +> [!NOTE] +> This feature will only be available in the New Boards Hub preview. diff --git a/release-notes/roadmap/2024/boards-auto-link-github-branch.md b/release-notes/roadmap/2024/boards-auto-link-github-branch.md new file mode 100644 index 00000000000..f75464b6066 --- /dev/null +++ b/release-notes/roadmap/2024/boards-auto-link-github-branch.md @@ -0,0 +1,15 @@ +--- +title: Automatically link pull requests when linked to a GitHub branch +author: danhellem +ms.author: dahellem +ms.date: 11/27/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Automatically link pull requests when linked to a GitHub branch +hide_comments: true +--- + +# Automatically link pull requests + +When linking a work item to a GitHub branch, I want all pull requests on that branch to automatically link to the same work item. This would streamline the process of tracking development efforts, ensuring that all related pull requests are consistently associated with the correct work item. It would also reduce manual effort and minimize the risk of missing links between work items and pull requests, improving traceability and collaboration. \ No newline at end of file diff --git a/release-notes/roadmap/2024/boards-auto-link-merge-commit.md b/release-notes/roadmap/2024/boards-auto-link-merge-commit.md new file mode 100644 index 00000000000..2c1b949feb8 --- /dev/null +++ b/release-notes/roadmap/2024/boards-auto-link-merge-commit.md @@ -0,0 +1,15 @@ +--- +title: Auto link the merge commit +author: danhellem +ms.author: dahellem +ms.date: 02/4/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Auto link the merge commit +hide_comments: true +--- + +# Auto link the merge commit + +When a pull request is merged, the merge commit will now be automatically linked to the associated work item. This feature ensures that the work item reflects the changes made in the pull request, providing better traceability and easier navigation between work items and code changes. \ No newline at end of file diff --git a/release-notes/roadmap/2024/boards-cut-paste-images-into-comments.md b/release-notes/roadmap/2024/boards-cut-paste-images-into-comments.md new file mode 100644 index 00000000000..3c92ccff478 --- /dev/null +++ b/release-notes/roadmap/2024/boards-cut-paste-images-into-comments.md @@ -0,0 +1,18 @@ +--- +title: Improve the experience of adding images to comments +author: danhellem +ms.author: dahellem +ms.date: 09/4/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Improve the experience of adding images to comments +hide_comments: true +--- + +# Improve the experience of adding images to comments + +Improve the experience of cutting and pasting images to work item comments from sources like email, word documents, and Teams conversations. + +> [!NOTE] +> This feature will only be available in the New Boards Hub preview. diff --git a/release-notes/roadmap/2024/boards-delete-area-path.md b/release-notes/roadmap/2024/boards-delete-area-path.md new file mode 100644 index 00000000000..4320595c4c9 --- /dev/null +++ b/release-notes/roadmap/2024/boards-delete-area-path.md @@ -0,0 +1,15 @@ +--- +title: Prevent the deletion of an active area or iteration path +author: danhellem +ms.author: dahellem +ms.date: 04/26/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Prevent the deletion of an active area or iteration path +hide_comments: true +--- + +# Prevent the deletion of an active area or iteration path + +Prevent the deletion an active area or iteration path where that path is being used by at least one work item. This will help prevent accidental deletion of paths that could result is loss of data and manual restoration of the path. \ No newline at end of file diff --git a/release-notes/roadmap/2024/boards-delete-branch-link.md b/release-notes/roadmap/2024/boards-delete-branch-link.md new file mode 100644 index 00000000000..1328f453433 --- /dev/null +++ b/release-notes/roadmap/2024/boards-delete-branch-link.md @@ -0,0 +1,15 @@ +--- +title: Automatically Remove Branch Links from Work Items When GitHub Branches Are Deleted +author: danhellem +ms.author: dahellem +ms.date: 2/4/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Automatically remove branch links when their corresponding GitHub branches are deleted +hide_comments: true +--- + +# Automatically Remove Branch Links on GitHub Branch Deletion + +When a GitHub branch linked to an Azure DevOps work item is deleted, the branch link will now be automatically removed from the work item. This feature helps keep your work items clean and up-to-date by ensuring that obsolete branch links do not clutter the work item details. This automation reduces manual effort and minimizes the risk of confusion caused by outdated branch references. \ No newline at end of file diff --git a/release-notes/roadmap/2024/boards-gh-pr-mentions.md b/release-notes/roadmap/2024/boards-gh-pr-mentions.md new file mode 100644 index 00000000000..3a16494a95c --- /dev/null +++ b/release-notes/roadmap/2024/boards-gh-pr-mentions.md @@ -0,0 +1,15 @@ +--- +title: Mentions support for GitHub pull requests +author: danhellem +ms.author: dahellem +ms.date: 09/17/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Mentions support for GitHub pull requests +hide_comments: true +--- + +# Mentions support for GitHub pull requests + +As a user of GitHub and Azure DevOps, I want to be able to mention (!) GitHub Pull Requests in Azure DevOps work items and comments so that I can easily reference the PRs that are related to the work item. \ No newline at end of file diff --git a/release-notes/roadmap/2024/boards-ghec-data-residency-support.md b/release-notes/roadmap/2024/boards-ghec-data-residency-support.md new file mode 100644 index 00000000000..3921c856482 --- /dev/null +++ b/release-notes/roadmap/2024/boards-ghec-data-residency-support.md @@ -0,0 +1,20 @@ +--- +title: Support for GitHub Enterprise Cloud with data residency +author: danhellem +ms.author: dahellem +ms.date: 10/22/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support for GitHub Enterprise Cloud with data residency +hide_comments: true +--- + +# Support for GitHub Enterprise Cloud with data residency + +Support GitHub integration with Azure Boards and Azure Pipelines for customers who are using GitHub Enterprise Cloud with data residency. + +> [!div class="mx-imgBorder"] +> ![screen shot example of creating a connection to example.ghe.com](media\boards-ghec-connection.png) + +[Learn more](https://aka.ms/ghec) about GitHub Enterprise Cloud with data residency. diff --git a/release-notes/roadmap/2024/boards-markdown-in-work-items.md b/release-notes/roadmap/2024/boards-markdown-in-work-items.md new file mode 100644 index 00000000000..480a0bc062b --- /dev/null +++ b/release-notes/roadmap/2024/boards-markdown-in-work-items.md @@ -0,0 +1,19 @@ +--- +title: Markdown support in work items +author: danhellem +ms.author: dahellem +ms.date: 09/17/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Markdown support in work items +hide_comments: true +--- + +# Markdown support in work items + +As a user, like in work item comments, I want to be able to use markdown syntax in the description (or any large text field) of work item form. + +[Suggestion ticket](https://developercommunity.visualstudio.com/t/support-markdown-as-an-alternative-to-html-for-wor/365464) + +[Related suggestion ticket](https://developercommunity.visualstudio.com/t/make-it-easy-to-insert-tables-into-a-work-item-des/1108159) \ No newline at end of file diff --git a/release-notes/roadmap/2024/boards-permanently-delete-attachment.md b/release-notes/roadmap/2024/boards-permanently-delete-attachment.md new file mode 100644 index 00000000000..e7a5ea458c7 --- /dev/null +++ b/release-notes/roadmap/2024/boards-permanently-delete-attachment.md @@ -0,0 +1,24 @@ +--- +title: Permanently delete work item attachments +author: danhellem +ms.author: dahellem +ms.date: 6/5/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Permanently delete work item attachments +hide_comments: true +--- + +# Permanently delete work item attachments + +The ability to permanently delete work item attachments so they cannot be accessed from a work item link, history, direct link, or any other means. + +We will initially release a delete REST API endpoint. Then adding the feature to the UI in a later sprint. + +### Scenario + +User uploads a malicious attachment to a work item. The link to that attachment is shared via email, chat, or work item discussion. The attachment is deleted from the work item, but the link is still accessible. That attachment needs to be permanently deleted so it cannot be accessed from any means. + +> [!NOTE] +> This feature will only be available in the New Boards Hub preview. diff --git a/release-notes/roadmap/2024/boards-state-transitions-with-github-repos.md b/release-notes/roadmap/2024/boards-state-transitions-with-github-repos.md new file mode 100644 index 00000000000..047113a6fca --- /dev/null +++ b/release-notes/roadmap/2024/boards-state-transitions-with-github-repos.md @@ -0,0 +1,18 @@ +--- +title: Support state transitions when merging a GitHub pull request +author: danhellem +ms.author: dahellem +ms.date: 11/27/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support state transitions when merging a GitHub pull request +hide_comments: true +--- + +# Support state transitions when merging a GitHub pull request + +When merging a GitHub pull request using AB#{Id}, only the Fixes keyword is supported to close the linked work item. However, as a user, I would like the ability to set the linked work item to a specific state, such as **Resolved**, without necessarily closing it. Ideally, I should be able to select any state supported by the work item type during the merge process. + +> [!div class="mx-imgBorder"] +> ![screen shot example resolved state transition.](media\github-state-transition-for-work-item.png) diff --git a/release-notes/roadmap/2024/boards-yaml-pipeline-show-build-status.md b/release-notes/roadmap/2024/boards-yaml-pipeline-show-build-status.md new file mode 100644 index 00000000000..897b6308c41 --- /dev/null +++ b/release-notes/roadmap/2024/boards-yaml-pipeline-show-build-status.md @@ -0,0 +1,18 @@ +--- +title: Show build status when using a YAML build pipeline with GitHub repository +author: danhellem +ms.author: dahellem +ms.date: 10/30/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Show build status when using a YAML build pipeline with GitHub repository +hide_comments: true +--- + +# Build status when using a YAML build pipeline with GitHub repository + +Similar to how classic release pipelines report deployment status, we’re adding support for YAML pipelines to display stage status on the **Deployments** control within the work item form. This enhancement will improve the experience for users utilizing Azure Boards alongside YAML pipelines. + +> [!div class="mx-imgBorder"] +> ![screen shot example of github build status on work item form](media\boards-build-status-on-yaml-gh-repo.png) \ No newline at end of file diff --git a/release-notes/roadmap/2024/boards-yaml-stage-status-on-work-item-github-repo.md b/release-notes/roadmap/2024/boards-yaml-stage-status-on-work-item-github-repo.md new file mode 100644 index 00000000000..0b0e9505ae1 --- /dev/null +++ b/release-notes/roadmap/2024/boards-yaml-stage-status-on-work-item-github-repo.md @@ -0,0 +1,17 @@ +--- +title: Report stage status to work item when using a YAML release pipeline with GitHub repository +author: danhellem +ms.author: dahellem +ms.date: 10/31/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Report stage status to work item when using a YAML release pipeline with GitHub repository +hide_comments: true +--- + +# Report stage status to work item when using a YAML release pipeline with GitHub repository + +Similar to how classic release pipelines report deployment status, extend support for YAML pipelines to display stage status on the **Deployments** control within the work item form when your code resides in a GitHub repository. + +Depends on [**Report YAML stage status in deployment control on work items**](boards-yaml-stage-status-on-work-item.md). \ No newline at end of file diff --git a/release-notes/roadmap/2024/boards-yaml-stage-status-on-work-item.md b/release-notes/roadmap/2024/boards-yaml-stage-status-on-work-item.md new file mode 100644 index 00000000000..7245a7826ae --- /dev/null +++ b/release-notes/roadmap/2024/boards-yaml-stage-status-on-work-item.md @@ -0,0 +1,20 @@ +--- +title: Report YAML stage status in deployment control on work items +author: danhellem +ms.author: dahellem +ms.date: 10/31/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Report YAML stage status in deployment control on work items +hide_comments: true +--- + +# Report YAML stage status in deployment control on work items + +Similar to how classic release pipelines report deployment status, we are adding support for YAML pipelines to display stage status in the Deployment control of the work item form. This enhancement will provide a better experience for users working with Azure Boards and YAML pipelines together. + +> [!div class="mx-imgBorder"] +> ![screen shot example of YAML stage status on deployment control in work item form](media\boards-yaml-stage-status-on-work-item.png) + +[Suggestion ticket](https://developercommunity.visualstudio.com/t/yaml-multistage-pipelines-link-workitems-to-deploy/1060361) \ No newline at end of file diff --git a/release-notes/roadmap/2024/dashboard-global-parameter.md b/release-notes/roadmap/2024/dashboard-global-parameter.md new file mode 100644 index 00000000000..ee6b6cb7257 --- /dev/null +++ b/release-notes/roadmap/2024/dashboard-global-parameter.md @@ -0,0 +1,15 @@ +--- +title: Dashboard Global Parameter +author: jeom +ms.author: jeom +ms.date: 11/13/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Dashboard Global Parameter +hide_comments: true +--- + +# Dashboard Global Parameter + +The new Global Parameters feature for Azure DevOps dashboards simplifies widget configuration by allowing a single, unified setting of common parameters across multiple widgets. This eliminates repetitive manual adjustments, drastically cuts setup time, and ensures consistency across the dashboard. Tailor and copy dashboards with ease, enhancing productivity. diff --git a/release-notes/roadmap/2024/dashboard-template.md b/release-notes/roadmap/2024/dashboard-template.md new file mode 100644 index 00000000000..8e811ff6a39 --- /dev/null +++ b/release-notes/roadmap/2024/dashboard-template.md @@ -0,0 +1,15 @@ +--- +title: Dashboard Template +author: jeom +ms.author: jeom +ms.date: 11/13/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Dashboard Template +hide_comments: true +--- + +# Dashboard Template + +To tackle the challenge of time-consuming dashboard setup, Azure DevOps now offers Dashboard Templates. This feature enables users to bypass the blank slate and jumpstart their dashboard creation using a selection of pre-designed widget templates, or to create a custom template to reuse. It streamlines the dashboard creation process, offering a time-saving solution without compromising the option for customization. Users can swiftly construct a dashboard that meets their specific needs or opt for the original empty dashboard to start from the ground up. With Dashboard Templates, users of all skill levels can more efficiently realize a functional and tailored dashboard experience. diff --git a/release-notes/roadmap/2024/deferred-approvals.md b/release-notes/roadmap/2024/deferred-approvals.md new file mode 100644 index 00000000000..07b00521202 --- /dev/null +++ b/release-notes/roadmap/2024/deferred-approvals.md @@ -0,0 +1,19 @@ +--- +title: Deferred approvals +author: silviuandrica +ms.author: sandrica +ms.date: 01/15/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Deferred approvals +hide_comments: true +--- + +# Deferred approvals + +In YAML pipelines, you can rerun a successful stage, but it triggers all stages that depend on it to rerun as well. +One use case for rerunning a stage is to roll back to a previous version of your system. +That is, you can choose an older version of the pipeline and wish to rerun a particular stage, and only that one. +Today, you can achieve simulate rerunning a single stage by making use of environments and approvals or the `ManualValidation` task, but doing so is tedious. +We plan to give you the ability to rerun a single stage, without causing following stages to rerun too. diff --git a/release-notes/roadmap/2024/ghazdo-3p-sarif.md b/release-notes/roadmap/2024/ghazdo-3p-sarif.md new file mode 100644 index 00000000000..0bedb4118fb --- /dev/null +++ b/release-notes/roadmap/2024/ghazdo-3p-sarif.md @@ -0,0 +1,15 @@ +--- +title: Third-party SARIF support +author: sull8000 +ms.author: bryans +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Advanced Security displays Code Scanning alerts for third-party tools that produce SARIF +hide_comments: true +--- + +# Advanced Security displays Code Scanning alerts for third-party tools that produce SARIF + +Code Scanning results from arbitrary third-party scanning tools that produce conforming SARIF will appear in the Advanced Security Code Scanning alert hub. diff --git a/release-notes/roadmap/2024/ghazdo-custom-codeql.md b/release-notes/roadmap/2024/ghazdo-custom-codeql.md new file mode 100644 index 00000000000..eef1ccf35b4 --- /dev/null +++ b/release-notes/roadmap/2024/ghazdo-custom-codeql.md @@ -0,0 +1,15 @@ +--- +title: Custom CodeQL Support +author: sull8000 +ms.author: bryans +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Custom CodeQL query support +hide_comments: true +--- + +# Custom CodeQL query support + +You will be able to write your own CodeQL queries to be executed in your CodeQL scans. diff --git a/release-notes/roadmap/2024/ghazdo-improved-generic-secrets.md b/release-notes/roadmap/2024/ghazdo-improved-generic-secrets.md new file mode 100644 index 00000000000..35548ff0b84 --- /dev/null +++ b/release-notes/roadmap/2024/ghazdo-improved-generic-secrets.md @@ -0,0 +1,15 @@ +--- +title: Improved secret detection +author: sull8000 +ms.author: bryans +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Improved detection of generic secrets +hide_comments: true +--- + +# Improved detection of generic secrets + +Advanced Security will detect and alert on more kinds of secrets beyond "highly-identifiable" kinds. diff --git a/release-notes/roadmap/2024/ghazdo-security-overview.md b/release-notes/roadmap/2024/ghazdo-security-overview.md new file mode 100644 index 00000000000..587b28f8277 --- /dev/null +++ b/release-notes/roadmap/2024/ghazdo-security-overview.md @@ -0,0 +1,15 @@ +--- +title: Security Overview +author: sull8000 +ms.author: bryans +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Provide a Security Overview dashboard for Advanced Security +hide_comments: true +--- + +# Provide a Security Overview dashboard for Advanced Security + +Provide a dashboard to view all Advanced Security alerts for the current Azure DevOps organization in a "single pane of glass". diff --git a/release-notes/roadmap/2024/ghazdo/3p-sarif.md b/release-notes/roadmap/2024/ghazdo/3p-sarif.md new file mode 100644 index 00000000000..b9ed39ecd8d --- /dev/null +++ b/release-notes/roadmap/2024/ghazdo/3p-sarif.md @@ -0,0 +1,15 @@ +--- +title: Third party SARIF support +author: sull8000 +ms.author: bryans +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Advanced Security displays Code Scanning alerts for third party tools that produce SARIF +hide_comments: true +--- + +# Advanced Security displays Code Scanning alerts for third party tools that produce SARIF + +Code Scanning results from arbitrary third-party scanning tools that produce conforming SARIF will appear in the Advanced Security Code Scanning alert hub. diff --git a/release-notes/roadmap/2024/ghazdo/dependabot.md b/release-notes/roadmap/2024/ghazdo/dependabot.md new file mode 100644 index 00000000000..a9d7dd64de8 --- /dev/null +++ b/release-notes/roadmap/2024/ghazdo/dependabot.md @@ -0,0 +1,19 @@ +--- +title: Dependabot on Azure DevOps +author: ncouraud +ms.author: nicour +ms.date: 04/22/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Dependabot Security Updates are available on Azure DevOps as a part of Advanced Security +hide_comments: true +--- + +# Bringing Dependabot security updates to Advanced Security dependency alerts + +We are bringing the power of Dependabot security updates to GitHub Advanced Security in Azure DevOps. This will allow Advanced Security users to enable the automatic creation of pull requests for dependency vulnerability detections. + +Dependabot security updates will make it easier for you to fix vulnerable dependencies in your repository. Once you enable this feature, when a Dependabot alert is raised for a vulnerable dependency in your repository, Dependabot automatically tries to fix it. + +Dependabot will check whether it's possible to upgrade the vulnerable dependency to a fixed version without disrupting the dependency graph for the repository. Then Dependabot will raise a pull request to update the dependency to the minimum version that includes the patch and links the pull request to the Dependency Scanning alert. diff --git a/release-notes/roadmap/2024/ghazdo/dependency-pr.md b/release-notes/roadmap/2024/ghazdo/dependency-pr.md new file mode 100644 index 00000000000..f80a46916bf --- /dev/null +++ b/release-notes/roadmap/2024/ghazdo/dependency-pr.md @@ -0,0 +1,15 @@ +--- +title: Dependency pull request annotations +author: ncouraud +ms.author: nicour +ms.date: 07/11/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Advanced Security displays newly introduced dependencies inline in Pull Requests +hide_comments: true +--- + +# Advanced Security displays newly introduced dependencies inline in Pull Requests + +When a pipeline containing the Advanced Security Dependency Scanning task runs against a PR branch, Advanced Security will begin to add contextual comments to the PR containing all newly introduced dependencies in the PR. diff --git a/release-notes/roadmap/2024/ghazdo/pull-request-annotation.md b/release-notes/roadmap/2024/ghazdo/pull-request-annotation.md new file mode 100644 index 00000000000..9734197bccc --- /dev/null +++ b/release-notes/roadmap/2024/ghazdo/pull-request-annotation.md @@ -0,0 +1,15 @@ +--- +title: Pull request annotations +author: ncouraud +ms.author: nicour +ms.date: 04/22/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Advanced Security displays newly introduced vulnerabilities inline in Pull Requests +hide_comments: true +--- + +# Advanced Security displays newly introduced vulnerabilities inline in Pull Requests + +When a pipeline containing the Advanced Security tasks runs against a PR branch, Advanced Security will begin to add contextual comments to the source containing all newly introduced vulnerabilities in the PR. diff --git a/release-notes/roadmap/2024/ghazdo/secret-validity.md b/release-notes/roadmap/2024/ghazdo/secret-validity.md new file mode 100644 index 00000000000..5683d00c23e --- /dev/null +++ b/release-notes/roadmap/2024/ghazdo/secret-validity.md @@ -0,0 +1,17 @@ +--- +title: Secret validity checking +author: ncouraud +ms.author: nicour +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Advanced Security shows the results of validity checking for supported secret types +hide_comments: true +--- + +# Advanced Security shows the results of validity checking for supported secret types + +As with on GitHub, Advanced Security will be able to produce validity data for selected partner tokens. + +Validity checks determine whether a token is still active and, when possible, whether it was ever active. This is useful when you’re deciding how to remediate an exposure. For example, you might prioritize remediating active secrets before checking your security logs for unauthorized access via API keys that have already been revoked. diff --git a/release-notes/roadmap/2024/github-branch.md b/release-notes/roadmap/2024/github-branch.md new file mode 100644 index 00000000000..774a7956410 --- /dev/null +++ b/release-notes/roadmap/2024/github-branch.md @@ -0,0 +1,21 @@ +--- +title: Create branch on GitHub repository from work item +author: danhellem +ms.author: dahellem +ms.date: 10/30/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Create branch on GitHub repository from work item +hide_comments: true +--- + +# Create branch on GitHub repository from work item + +Be able to create a new GitHub branch from a work item. + +> [!div class="mx-imgBorder"] +> ![screen shot example adding link to Github](media\create-github-branch-from-work-item.png) + +> [!NOTE] +> This feature will only be available with the [**New Boards Hubs** preview](https://devblogs.microsoft.com/devops/new-boards-hub-public-preview/). \ No newline at end of file diff --git a/release-notes/roadmap/2024/github-pr-details-on-work-item.md b/release-notes/roadmap/2024/github-pr-details-on-work-item.md new file mode 100644 index 00000000000..84924fd19f3 --- /dev/null +++ b/release-notes/roadmap/2024/github-pr-details-on-work-item.md @@ -0,0 +1,28 @@ +--- +title: Show more details about a GitHub pull request +author: danhellem +ms.author: dahellem +ms.date: 10/30/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Show more details about a GitHub pull request +hide_comments: true +--- + +# Show more details about a GitHub pull request + +Today the GitHub integration shows if a pull request is either open or closed. We want to improve that to match how GitHub displays the status of a pull request from the Pull Requests list. This will include the following: + +- Pull request ID +- Date the pull request was created +- Show the status of the pull request (draft, review required, approved, merged) +- Status of checks (completed, partially completed, failed) + +Example: + +> [!div class="mx-imgBorder"] +> ![screen shot example adding link to Github](media\github-pr-details-on-work-item.png) + +> [!NOTE] +> This feature will only be available with the [**New Boards Hubs** preview](https://devblogs.microsoft.com/devops/new-boards-hub-public-preview/). diff --git a/release-notes/roadmap/2024/manual-queuing-of-stages.md b/release-notes/roadmap/2024/manual-queuing-of-stages.md new file mode 100644 index 00000000000..09c62b90f38 --- /dev/null +++ b/release-notes/roadmap/2024/manual-queuing-of-stages.md @@ -0,0 +1,19 @@ +--- +title: Manual queuing of stages +author: silviuandrica +ms.author: sandrica +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Manual queuing of stages +hide_comments: true +--- + +# Manual queuing of stages + +In YAML pipelines, a stage starts running as soon as its dependencies are satisfied. +When you deploy to Production, this execution strategy isn't always the right choice. +For example, you don't want that _every_ pipeline run deploys to Production. +Today, you can simulate manual queuing of stages by making use of environments and approvals & checks or the `ManualValidation` task, but doing so is tedious. +We plan to give you the ability to define which stages run manually and to trigger such stages on demand. diff --git a/release-notes/roadmap/2024/media/add-link-to-github.png b/release-notes/roadmap/2024/media/add-link-to-github.png new file mode 100644 index 00000000000..4802da0c055 Binary files /dev/null and b/release-notes/roadmap/2024/media/add-link-to-github.png differ diff --git a/release-notes/roadmap/2024/media/boards-ab-links-github-pr.png b/release-notes/roadmap/2024/media/boards-ab-links-github-pr.png new file mode 100644 index 00000000000..9593c14505d Binary files /dev/null and b/release-notes/roadmap/2024/media/boards-ab-links-github-pr.png differ diff --git a/release-notes/roadmap/2024/media/boards-build-status-on-yaml-gh-repo.png b/release-notes/roadmap/2024/media/boards-build-status-on-yaml-gh-repo.png new file mode 100644 index 00000000000..12f21e3f8fe Binary files /dev/null and b/release-notes/roadmap/2024/media/boards-build-status-on-yaml-gh-repo.png differ diff --git a/release-notes/roadmap/2024/media/boards-ghec-connection.png b/release-notes/roadmap/2024/media/boards-ghec-connection.png new file mode 100644 index 00000000000..9f5abc1f025 Binary files /dev/null and b/release-notes/roadmap/2024/media/boards-ghec-connection.png differ diff --git a/release-notes/roadmap/2024/media/boards-show-github-actions-status-1.png b/release-notes/roadmap/2024/media/boards-show-github-actions-status-1.png new file mode 100644 index 00000000000..10ce768de72 Binary files /dev/null and b/release-notes/roadmap/2024/media/boards-show-github-actions-status-1.png differ diff --git a/release-notes/roadmap/2024/media/boards-yaml-stage-status-on-work-item.png b/release-notes/roadmap/2024/media/boards-yaml-stage-status-on-work-item.png new file mode 100644 index 00000000000..0c6e69a68ae Binary files /dev/null and b/release-notes/roadmap/2024/media/boards-yaml-stage-status-on-work-item.png differ diff --git a/release-notes/roadmap/2024/media/create-github-branch-from-work-item.png b/release-notes/roadmap/2024/media/create-github-branch-from-work-item.png new file mode 100644 index 00000000000..41397c2a811 Binary files /dev/null and b/release-notes/roadmap/2024/media/create-github-branch-from-work-item.png differ diff --git a/release-notes/roadmap/2024/media/github-pr-details-on-work-item.png b/release-notes/roadmap/2024/media/github-pr-details-on-work-item.png new file mode 100644 index 00000000000..bf6e429995b Binary files /dev/null and b/release-notes/roadmap/2024/media/github-pr-details-on-work-item.png differ diff --git a/release-notes/roadmap/2024/media/github-state-transition-for-work-item.png b/release-notes/roadmap/2024/media/github-state-transition-for-work-item.png new file mode 100644 index 00000000000..7532066d1bb Binary files /dev/null and b/release-notes/roadmap/2024/media/github-state-transition-for-work-item.png differ diff --git a/release-notes/roadmap/2024/no-tfvc-in-new-projects.md b/release-notes/roadmap/2024/no-tfvc-in-new-projects.md new file mode 100644 index 00000000000..9f8ce1184c3 --- /dev/null +++ b/release-notes/roadmap/2024/no-tfvc-in-new-projects.md @@ -0,0 +1,17 @@ +--- +title: Removal of TFVC in new projects +author: vijayma +ms.author: vijayma +ms.date: 06/04/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Removal of TFVC in new projects +hide_comments: true +--- + +# Removal of TFVC in new projects + +Over the past several years, we added no new features to Team Foundation Version Control (TFVC). Git is the preferred version control system in Azure Repos. Furthermore, all the improvements we made in the past few years in terms of security, performance, and accessibility were only made to Git repositories. We have seen a continuous decline in the usage of TFVC over these years. A few customers still use TFVC, and we do not plan to remove this feature set for those customers. However, we gradually plan to phase out TFVC in all new projects and organizations, or in projects that do not have any current usage of TFVC. + +As a step in that direction, we will introduce a setting to "Disable creation of TFVC repositories." It only changes the creation of new TFVC repositories; there is no impact on existing ones. The setting is available at organization and project levels, organization setting has a priority over project level. By default, the toggle will be enabled. This means that you cannot create TFVC repositories anymore in these new projects. But, if you have a strong reason to do so, you can have your administrator disable the toggle. In the future, we will not allow you to disable the toggle. \ No newline at end of file diff --git a/release-notes/roadmap/2024/pr-search.md b/release-notes/roadmap/2024/pr-search.md new file mode 100644 index 00000000000..03dc767e6ce --- /dev/null +++ b/release-notes/roadmap/2024/pr-search.md @@ -0,0 +1,15 @@ +--- +title: PR Search +author: gloridelmorales +ms.author: glmorale +ms.date: 4/24/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: PR Search +hide_comments: true +--- + +# PR Search + +Easily look for PRs by their title, description, comments and code right from Azure DevOps global search. \ No newline at end of file diff --git a/release-notes/roadmap/2024/private-dashboard.md b/release-notes/roadmap/2024/private-dashboard.md new file mode 100644 index 00000000000..b9857b13742 --- /dev/null +++ b/release-notes/roadmap/2024/private-dashboard.md @@ -0,0 +1,15 @@ +--- +title: Private Dashboard +author: jeom +ms.author: jeom +ms.date: 11/13/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Private Dashboard +hide_comments: true +--- + +# Private Dashboard + +Private Dashboards in Azure DevOps introduce a tailored level of confidentiality for your dashboard. Unlike the current project and team-level dashboards, which are publicly visible, Private Dashboards offer controlled access, visible only to a select group of individuals. Unlinked to any team, these dashboards provide a secure space for users to create and manage data without broader visibility. With Private Dashboards, you can build more customized dashboards incorporating private queries and share your dashboards with a select group, ensuring the privacy and exclusivity of your data. diff --git a/release-notes/roadmap/2024/rerun-single-stage.md b/release-notes/roadmap/2024/rerun-single-stage.md new file mode 100644 index 00000000000..fccae85963f --- /dev/null +++ b/release-notes/roadmap/2024/rerun-single-stage.md @@ -0,0 +1,19 @@ +--- +title: Rerun single stage +author: silviuandrica +ms.author: sandrica +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Rerun single stage +hide_comments: true +--- + +# Rerun single stage + +In YAML pipelines, you can rerun a successful stage, but it triggers all stages that depend on it to rerun as well. +One use case for rerunning a stage is to roll back to a previous version of your system. +That is, you can choose an older version of the pipeline and wish to rerun a particular stage, and only that one. +Today, you can achieve simulate rerunning a single stage by making use of environments and approvals or the `ManualValidation` task, but doing so is tedious. +We plan to give you the ability to rerun a single stage, without causing following stages to rerun too. diff --git a/release-notes/roadmap/2024/scale-github-repos.md b/release-notes/roadmap/2024/scale-github-repos.md new file mode 100644 index 00000000000..8e8096b0639 --- /dev/null +++ b/release-notes/roadmap/2024/scale-github-repos.md @@ -0,0 +1,17 @@ +--- +title: Improve scalability when searching and linking GitHub repos to a Azure DevOps project +author: danhellem +ms.author: dahellem +ms.date: 10/30/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Improve scalability when searching and linking GitHub repos to a Azure DevOps project +hide_comments: true +--- + +# Improve scalability + +1. Today, you can only link up to 500 GitHub repositories to a single Azure DevOps project. We want to improve the user experience to scale up and allow more than 500 repositories to be connected. + +2. Improve the experience to prevent page timeouts when searching for GitHub repositories to link to your Azure DevOps project. \ No newline at end of file diff --git a/release-notes/roadmap/2024/stage-concurrency.md b/release-notes/roadmap/2024/stage-concurrency.md new file mode 100644 index 00000000000..4744c6e9b41 --- /dev/null +++ b/release-notes/roadmap/2024/stage-concurrency.md @@ -0,0 +1,21 @@ +--- +title: Stage concurrency +author: silviuandrica +ms.author: sandrica +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Stage concurrency +hide_comments: true +--- + +# Stage concurrency + +In YAML pipelines, runs of the same pipeline execute in parallel. +The same is true of stages as well. +There are usage scenarios in which the parallel execution of the same stage isn't allowed. +For example, each stage of your pipeline kicks off an external deployment orchestration for a particular resource, +and you must ensure that no two pipeline runs execute the same stage at the same time. +Today, you can achieve mutual exclusion by making use of environments and the exclusive lock check, but doing so is tedious. +We plan to give you the ability to define stage-level locks, to ensure mutual exclusion of stages. diff --git a/release-notes/roadmap/2024/stage-traceability.md b/release-notes/roadmap/2024/stage-traceability.md new file mode 100644 index 00000000000..24d718e554e --- /dev/null +++ b/release-notes/roadmap/2024/stage-traceability.md @@ -0,0 +1,19 @@ +--- +title: Stage traceability +author: silviuandrica +ms.author: sandrica +ms.date: 11/8/2023 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Stage traceability +hide_comments: true +--- + +# Stage traceability + +In YAML pipelines, it's hard to tell what is the state of your system. +For example, you can't easily see what is the latest pipeline run that executed a particular stage. +This limitation makes debugging the system more difficult. +In YAML pipelines, it's also difficult to reason what changes are going to be deployed in a particular stage. +We plan to give you the ability to see a stage-focused view of all the runs of a pipeline, so you can say that pipeline run `#123` was the last one to run in stage `Deploy WUS1`. diff --git a/release-notes/roadmap/2025/continuous-access-evaluation.md b/release-notes/roadmap/2025/continuous-access-evaluation.md new file mode 100644 index 00000000000..a7102182634 --- /dev/null +++ b/release-notes/roadmap/2025/continuous-access-evaluation.md @@ -0,0 +1,17 @@ +--- +title: Continuous access evaluation +author: ramrajesh +ms.author: rajr +ms.date: 04/07/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Continuous access evaluation in Azure DevOps +hide_comments: true +--- + +# Continuous access evaluation + +Token expiration and refresh mechanisms are commonly employed within the industry. Upon successful user login to Azure DevOps, the web client acquires an OAuth 2.0 access token from Entra, provided that all requisite conditional access policies are met. These tokens generally remain valid for one hour. After expiration, the web client will automatically refresh the token from Microsoft Entra, allowing for a reassessment of access policies, such as Conditional Access or account status. However, this process does not operate in near real-time; for instance, a security event like the deletion of a user account may take up to an hour for Azure DevOps to detect and respond to, as it waits for the existing access token to expire. Such delays in policy enforcement could hinder timely responses to security incidents. + +In contrast, [Continuous Access Evaluation (CAE)](/entra/identity/conditional-access/concept-continuous-access-evaluation) facilitates near real-time enforcement. It establishes a bidirectional communication channel between Microsoft Entra and Azure DevOps services, enabling Azure DevOps to locally synchronize and verify conditional access policies for client changes, such as change in IP address. Additionally, the token issuer (Entra) can alert Azure DevOps to stop accepting tokens for a specific user due to issues like account compromise, disablement, or other concerns, and Azure DevOps is able to act accordingly. diff --git a/release-notes/roadmap/2025/ghazdo/audit-logging.md b/release-notes/roadmap/2025/ghazdo/audit-logging.md new file mode 100644 index 00000000000..54df0990a05 --- /dev/null +++ b/release-notes/roadmap/2025/ghazdo/audit-logging.md @@ -0,0 +1,15 @@ +--- +title: Advanced Security events streamed to Azure DevOps audit log +author: laurajjiang +ms.author: laurajiang +ms.date: 02/06/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Advanced Security events streamed to Azure DevOps audit log +hide_comments: true +--- + +# Advanced Security events streamed to Azure DevOps audit log + +Similar to adding alert-specific events into the service hooks experience, we’re introducing additional visibility into important events to the Azure DevOps audit log. In the audit log, you’ll find information about Advanced Security enablement and disablement at repository, project, and organization levels as well as instances of developers bypassing secret push protection. \ No newline at end of file diff --git a/release-notes/roadmap/2025/ghazdo/boards-linking.md b/release-notes/roadmap/2025/ghazdo/boards-linking.md new file mode 100644 index 00000000000..9fe70818626 --- /dev/null +++ b/release-notes/roadmap/2025/ghazdo/boards-linking.md @@ -0,0 +1,17 @@ +--- +title: Link Boards items to Advanced Security Alerts +author: ncouraud +ms.author: nicour +ms.date: 01/16/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Link Boards items to Advanced Security Alerts +hide_comments: true +--- + +# Link Boards items to Advanced Security Alerts + +To assist in the remediation experience for Advanced Security findings, we’re introducing the ability to link an existing work item to alerts. These links will be bi-directional, so you can create the relationship from a work item or Advanced Security alert. You can link multiple alerts per work item or multiple work items per alert. + +This will allow customers to retain their existing work management and tracking capabilities in boards, while providing visibility into any security impact to all Boards users and stakeholders. diff --git a/release-notes/roadmap/2025/ghazdo/default-setup.md b/release-notes/roadmap/2025/ghazdo/default-setup.md new file mode 100644 index 00000000000..3cdb48c263f --- /dev/null +++ b/release-notes/roadmap/2025/ghazdo/default-setup.md @@ -0,0 +1,15 @@ +--- +title: CodeQL default setup (one-click enablement) +author: ncouraud +ms.author: nicour +ms.date: 02/06/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: CodeQL default setup (one-click enablement) +hide_comments: true +--- + +# CodeQL default setup (one-click enablement) + +To help you streamline enablement and quickly onboard to Advanced Security tools, we’re adding a one-click enablement option to get started with CodeQL scanning. This feature will look similar to the CodeQL default setup experience available on GitHub. \ No newline at end of file diff --git a/release-notes/roadmap/2025/ghazdo/dependency-metadata.md b/release-notes/roadmap/2025/ghazdo/dependency-metadata.md new file mode 100644 index 00000000000..68b15d42a90 --- /dev/null +++ b/release-notes/roadmap/2025/ghazdo/dependency-metadata.md @@ -0,0 +1,15 @@ +--- +title: Adding additional metadata for dependency alerts to improve remediation +author: laurajjiang +ms.author: laurajiang +ms.date: 02/06/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Adding additional metadata for dependency alerts to improve remediation +hide_comments: true +--- + +# Adding additional metadata for dependency alerts to improve remediation + +Any additional pieces of information about an alert can help you better triage and understand the priority of an alert, especially if you have multiple alerts of the same severity. We’ll be introducing detection of development dependencies for select supported ecosystems as well as surfacing information about the EPSS (Exploit Prediction Scoring System) score for dependency alerts. diff --git a/release-notes/roadmap/2025/ghazdo/multi-repo.md b/release-notes/roadmap/2025/ghazdo/multi-repo.md new file mode 100644 index 00000000000..547c97e2934 --- /dev/null +++ b/release-notes/roadmap/2025/ghazdo/multi-repo.md @@ -0,0 +1,15 @@ +--- +title: Support for multi-repository result publishing +author: laurajjiang +ms.author: laurajiang +ms.date: 02/06/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support for multi-repository result publishing +hide_comments: true +--- + +# Support for multi-repository result publishing + +For customers who have their pipeline definition in one repository and the code being scanned by Advanced Security in another repository, the findings are always published to the repository with their pipeline definition. We’ll be making enhancements to our publishing logic for both dependencies and code scanning such that the alerts are published to the repository whose code is being scanned, also enabling proper file preview for each alert. diff --git a/release-notes/roadmap/2025/ghazdo/secret-protection.md b/release-notes/roadmap/2025/ghazdo/secret-protection.md new file mode 100644 index 00000000000..2d4e5696dd2 --- /dev/null +++ b/release-notes/roadmap/2025/ghazdo/secret-protection.md @@ -0,0 +1,17 @@ +--- +title: Secret Protection and Code Security plans for Advanced Security +author: laurajjiang +ms.author: laurajiang +ms.date: 04/21/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Secret Protection and Code Security plans for Advanced Security +hide_comments: true +--- + +# Secret Protection and Code Security plans for Advanced Security + +Following the [GitHub announcement](https://github.blog/changelog/2025-03-04-introducing-github-secret-protection-and-github-code-security/) introducing the GitHub Secret Protection and GitHub Code Security products, we will also be bringing the individual Secret Protection and Code Security products to GitHub Advanced Security on Azure DevOps. + +Any existing customers will not experience any changes to their Advanced Security cost or experiences. New customers after the launch of the individual products will automatically be able to purchase the individual products. \ No newline at end of file diff --git a/release-notes/roadmap/2025/ghazdo/security-overview-v2.md b/release-notes/roadmap/2025/ghazdo/security-overview-v2.md new file mode 100644 index 00000000000..c4bf06668be --- /dev/null +++ b/release-notes/roadmap/2025/ghazdo/security-overview-v2.md @@ -0,0 +1,15 @@ +--- +title: New security overview alert details and reporting capabilities +author: laurajjiang +ms.author: laurajiang +ms.date: 02/06/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: New security overview alert details and reporting capabilities +hide_comments: true +--- + +# New security overview alert details and reporting capabilities + +To better empower application security teams and security champions, we’re adding new columns into the security overview risk page and filtering options to give you more insight into the security posture of your repositories. These include new, dismissed, and fixed alerts as well as filtering options by repository, toolset, and a time-bound. diff --git a/release-notes/roadmap/2025/ghazdo/service-hooks.md b/release-notes/roadmap/2025/ghazdo/service-hooks.md new file mode 100644 index 00000000000..bc89e94b550 --- /dev/null +++ b/release-notes/roadmap/2025/ghazdo/service-hooks.md @@ -0,0 +1,15 @@ +--- +title: Advanced Security alert events added to Azure DevOps service hooks framework +author: laurajjiang +ms.author: laurajiang +ms.date: 02/06/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Advanced Security alert events added to Azure DevOps service hooks framework +hide_comments: true +--- + +# Advanced Security alert events added to Azure DevOps service hooks framework + +A few alert-oriented events will be integrated with Azure DevOps service hooks, enabling you to customize notifications and create integrations with external platforms. Just like other events, you’ll be able to filter by repository and branch, as well as alert type and severity for Advanced Security. diff --git a/release-notes/roadmap/2025/manage-high-privilege-scopes.md b/release-notes/roadmap/2025/manage-high-privilege-scopes.md new file mode 100644 index 00000000000..7ee97f5de18 --- /dev/null +++ b/release-notes/roadmap/2025/manage-high-privilege-scopes.md @@ -0,0 +1,17 @@ +--- +title: Manage high privilege scopes, pipeline decorators, and unpublished extensions +author: alexpysanets +ms.author: alexpysanets +ms.date: 04/22/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Manage high privilege scopes, pipeline decorators, and unpublished extensions +hide_comments: true +--- + +# Manage high privilege scopes, pipeline decorators, and unpublished extensions + +Azure DevOps extensions improve product functionality and workflows, but those with high privilege scopes may pose various risks. + +A new feature flags these scopes on each organization's admin page and the Visual Studio Marketplace installation page, helping administrators make informed decisions. Unpublished extensions and pipeline decorators are also flagged for administrator awareness and appropriate actions. diff --git a/release-notes/roadmap/2025/mdp/container-agents.md b/release-notes/roadmap/2025/mdp/container-agents.md new file mode 100644 index 00000000000..5df8ea8c618 --- /dev/null +++ b/release-notes/roadmap/2025/mdp/container-agents.md @@ -0,0 +1,15 @@ +--- +title: Container based agents +author: gloridelmorales +ms.author: glmorale +ms.date: 04/21/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Container based agents +hide_comments: true +--- + +# Container based agents + +We're adding support for provisioning a container and starting the agent inside the container. \ No newline at end of file diff --git a/release-notes/roadmap/2025/mdp/pool-creation.md b/release-notes/roadmap/2025/mdp/pool-creation.md new file mode 100644 index 00000000000..3bb4befdc8d --- /dev/null +++ b/release-notes/roadmap/2025/mdp/pool-creation.md @@ -0,0 +1,15 @@ +--- +title: Pool creation at the Azure DevOps project level using project level permissions +author: gloridelmorales +ms.author: glmorale +ms.date: 04/21/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Pool creation at the Azure DevOps project level using project level permissions +hide_comments: true +--- + +# Pool creation at the Azure DevOps project level using project level permissions + +To create a Managed DevOps Pool, you must currently be an [Organization-level Agent pools administrator or a Project Collection Administrator in Azure DevOps](/azure/devops/managed-devops-pools/prerequisites?view=azure-devops#verify-azure-devops-permissions). We're enabling a new mode of Managed DevOps Pools creation, requiring only Project-level Agent pools administrator. Managed DevOps Pools created using Project-level Agent pools administrator will be created and enabled only for use in the designated Azure DevOps Project. \ No newline at end of file diff --git a/release-notes/roadmap/2025/mdp/spot-vms.md b/release-notes/roadmap/2025/mdp/spot-vms.md new file mode 100644 index 00000000000..079f2385459 --- /dev/null +++ b/release-notes/roadmap/2025/mdp/spot-vms.md @@ -0,0 +1,15 @@ +--- +title: Spot Virtual Machines instances +author: gloridelmorales +ms.author: glmorale +ms.date: 04/21/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Spot Virtual Machines instances +hide_comments: true +--- + +# Spot Virtual Machines instances + +Reduce your Azure cost [by up to 90%](/azure/architecture/guide/spot/spot-eviction#understand-spot-vm-pricing) by switching your non-time-critical pipelines to Spot Virtual Machines. CI/CD workloads make ideal candidates to use Spot Virtual Machines due to the ephemeral nature of CI/CD agents. For more information on Spot Virtual Machines, see Spot [Virtual Machines overview](https://azure.microsoft.com/products/virtual-machines/spot). \ No newline at end of file diff --git a/release-notes/roadmap/2025/mdp/trusted-certificates.md b/release-notes/roadmap/2025/mdp/trusted-certificates.md new file mode 100644 index 00000000000..d73cbe106ac --- /dev/null +++ b/release-notes/roadmap/2025/mdp/trusted-certificates.md @@ -0,0 +1,15 @@ +--- +title: Add trusted root certificates +author: gloridelmorales +ms.author: glmorale +ms.date: 04/21/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Add trusted root certificates +hide_comments: true +--- + +# Add trusted root certificates + +Managed DevOps Pools is adding support so you can configure your pool to add certificates from your Key Vault as a trusted root certificate to your agents, so you don’t have to add a task for it to all the pipelines that use the pool. For more information, see [Key Vault configuration](/azure/devops/managed-devops-pools/configure-security?view=azure-devops#key-vault-configuration). \ No newline at end of file diff --git a/release-notes/roadmap/2025/new-service-connection.md b/release-notes/roadmap/2025/new-service-connection.md new file mode 100644 index 00000000000..3353363caf8 --- /dev/null +++ b/release-notes/roadmap/2025/new-service-connection.md @@ -0,0 +1,20 @@ +--- +title: PAT-less authentication from pipeline tasks to Azure DevOps APIs +author: gloridelmorales +ms.author: glmorale +ms.date: 04/21/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: PAT-less authentication from pipeline tasks to Azure DevOps APIs +hide_comments: true +--- + +# PAT-less authentication from pipeline tasks to Azure DevOps APIs + +Tasks in a pipeline use either a [job access token](/azure/devops/pipelines/process/access-tokens?view=azure-devops&tabs=yaml), available via the built-in variable [System.AccessToken](/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken), or a PAT to access Azure DevOps resources. For instance, a “checkout” task uses this token to authenticate to the repository. Similarly, a PowerShell script can use this token to access Azure DevOps REST APIs. However, the permissions of this token are based on the Project Build Service identity, meaning all job access tokens in a project have identical permissions. This grants excessive access across all pipelines within the project. + +Using PATs to access Azure DevOps resources is common, particularly when a task needs to access those resources across organization boundaries. For instance, a Nuget Authenticate task uses a PAT token to authenticate to a feed in another organization. PATs are an anti-pattern for security as they tend to be created with broad permissions and are held for a long time thereby increasing the risk of exfiltration. + +To improve the security in these scenarios, a new service connection type called “Azure DevOps Service Connection” is being introduced. It uses an Azure service principal that can be added as a user in Azure DevOps with specific permissions. This allows you to authenticate to resources from a pipeline task using this service connection and restrict access to specific pipelines. +We will first introduce the new connection type and a few tasks that work with it. We will gradually expand the list of tasks that can use the connection type over time. \ No newline at end of file diff --git a/release-notes/roadmap/2025/on-demand-execution.md b/release-notes/roadmap/2025/on-demand-execution.md new file mode 100644 index 00000000000..61e36cbdf4a --- /dev/null +++ b/release-notes/roadmap/2025/on-demand-execution.md @@ -0,0 +1,15 @@ +--- +title: On-demand out of order execution of stages +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: On-demand out of order execution of stages +hide_comments: true +--- + +# On-demand out of order execution of stages + +Stages in a pipeline have dependencies and some stages are [un-skippable](/azure/devops/pipelines/process/stages?view=azure-devops&tabs=yaml#mark-a-stage-as-unskippable). However, there are scenarios where one would want to start a future stage more quickly than wait for all its dependencies. Examples of such scenarios are (a) fast-track a hot fix and (b) ramp up the traffic to a service faster than the pipeline normally allows (in this case, each stage models a certain amount of ramp-up traffic). We will allow this provided (a) the stage you want to start does not have any un-skippable stages in its dependency chain and (b) you have the permission to start a stage out of order. \ No newline at end of file diff --git a/release-notes/roadmap/2025/proof-of-possession.md b/release-notes/roadmap/2025/proof-of-possession.md new file mode 100644 index 00000000000..ef5d4acd697 --- /dev/null +++ b/release-notes/roadmap/2025/proof-of-possession.md @@ -0,0 +1,21 @@ +--- +title: Using device bound Entra tokens in Azure DevOps +author: ramrajesh +ms.author: rajr +ms.date: 04/07/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Using device bound Entra tokens in Azure DevOps +hide_comments: true +--- + +# Using device bound Entra tokens in Azure DevOps + +Bearer tokens are common in modern identity flows. When a user logs into Azure DevOps, the web client acquires an OAuth 2.0 access token, a type of bearer token from Entra using Microsoft Authentication Library (MSAL). This token is stored in the user's browser cache. However, they are vulnerable to being stolen from token caches. [Proof-of-Possession (PoP)](/entra/msal/dotnet/advanced/proof-of-possession-tokens) or device bound tokens help reduce this risk by tying this token to the client device using a public/private key pair. Microsoft Entra adds the public key to the token, and the client signs it with the private key—resulting in two digital signatures: one from Entra and one from the client. This offers two key protections: + +**Token cache safety**. The local browser cache doesn’t store fully signed [PoP tokens.](/entra/msal/dotnet/advanced/proof-of-possession-tokens) Tokens are signed only when needed, so stolen cache tokens can’t be used without the private key which are hardware-protected in most cases. + +**Man-in-the-middle protection**. The protocol also prevents replay or interception attacks from man-in-the-middle attacks. + +Azure DevOps will upgrade the access tokens used in the web client to device bound tokens to protect users against token theft. diff --git a/release-notes/roadmap/2025/testplans/advanced-test-result.md b/release-notes/roadmap/2025/testplans/advanced-test-result.md new file mode 100644 index 00000000000..872956e8619 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/advanced-test-result.md @@ -0,0 +1,15 @@ +--- +title: Advanced Test Case result history +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Advanced Test Case result history +hide_comments: true +--- + +# Advanced Test Case result history + +Easily track key test run details with new enhancements to the test case result page. You’ll see critical information like Run ID, Pipeline ID, Owner, Iteration Path, and Area Path displayed right on the page, providing a complete view of each test run at a glance. We are adding horizontal scrolling for longer values and customizable columns, allowing you to personalize your layout and keep your preferences saved at the user level. To help you move faster, Run IDs and rows are clickable, giving you quick access to the Test Run view for deeper insights. These updates aim to improve visibility, save time, and streamline your workflow, making it easier to track and manage your test runs efficiently. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/auto-pause-manual-test.md b/release-notes/roadmap/2025/testplans/auto-pause-manual-test.md new file mode 100644 index 00000000000..604d5e63438 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/auto-pause-manual-test.md @@ -0,0 +1,15 @@ +--- +title: Auto-pause manual test case run +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Auto-pause manual test case run +hide_comments: true +--- + +# Auto-pause manual test case run + +Never lose progress on your test runs with auto-pause test case run. This new feature automatically pauses your test case run if your work is interrupted, ensuring that partial progress is saved without needing a manual pause. Whether you step away or close the session, you can easily resume your test case right where you left off, reducing the risk of data loss and improving your workflow. By simplifying the pause and resume process, auto-pause helps you stay focused on testing without worrying about losing your progress. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/customizable-flaky-test.md b/release-notes/roadmap/2025/testplans/customizable-flaky-test.md new file mode 100644 index 00000000000..b4f58826b6b --- /dev/null +++ b/release-notes/roadmap/2025/testplans/customizable-flaky-test.md @@ -0,0 +1,15 @@ +--- +title: Customizable flaky test detection logic +author: gloridelmorales +ms.author: glmorale +ms.date: 04/18/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Customizable flaky test detection logic +hide_comments: true +--- + +# Customizable flaky test detection logic + +Azure DevOps will offer enhanced flaky test detection logic, customizable to your organization's needs. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/direct-link-from-test-plan.md b/release-notes/roadmap/2025/testplans/direct-link-from-test-plan.md new file mode 100644 index 00000000000..86d7049d799 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/direct-link-from-test-plan.md @@ -0,0 +1,15 @@ +--- +title: Direct link from Test Plan work item to Test Plans page +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Direct link from Test Plan work item to Test Plans page +hide_comments: true +--- + +# Direct link from Test Plan work item to Test Plans page + +You can now easily access the Test Plans page directly from the Test Plans work item. We are adding a clear, direct entry point to help you quickly navigate to the corresponding test plan without extra steps. This improvement makes it faster and more intuitive to trace your test plans, ensuring a smoother experience when managing your test workflow. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/enhanced-test-point.md b/release-notes/roadmap/2025/testplans/enhanced-test-point.md new file mode 100644 index 00000000000..0bf1c50eb14 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/enhanced-test-point.md @@ -0,0 +1,23 @@ +--- +title: Enhanced Test Point Result Panel +author: gloridelmorales +ms.author: glmorale +ms.date: 04/17/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Enhanced Test Point Result Panel +hide_comments: true +--- + +# Enhanced Test Point Result Panel + +This update makes it easier to review test point history by improving the layout, visibility, and interactivity of the test result history panel—so you can find the information you need faster. Here’s what’s new: + +* **Navigation Bar**: A new bar at the top of the panel shows the configuration filter applied to the test case, giving you clear context for the results displayed. + +* **Improved Column Visibility**: We've streamlined the columns to prevent truncation, ensuring important details like configuration and test suite are visible at a glance. + +* **Clickable Rows and Run IDs**: Each row and Run ID is now clickable, letting you jump directly to the full run details in a new tab. + +These enhancements provide a more seamless and informative experience when reviewing test history, helping you track progress and access details with confidence. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/export-test-cases.md b/release-notes/roadmap/2025/testplans/export-test-cases.md new file mode 100644 index 00000000000..70ab9a59fdc --- /dev/null +++ b/release-notes/roadmap/2025/testplans/export-test-cases.md @@ -0,0 +1,15 @@ +--- +title: Export test cases with custom columns in XLSX +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Export test cases with custom columns in XLSX +hide_comments: true +--- + +# Export test cases with custom columns in XLSX + +Based on your feedback, Test Plans supports exporting test cases with custom columns, giving you greater flexibility and control over the data you share and analyze. With this feature you will be able to export test cases with custom columns in XLSX. This enhancement helps you tailor exports to your needs, ensuring the information you export is relevant and actionable. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/improve-flaky-test.md b/release-notes/roadmap/2025/testplans/improve-flaky-test.md new file mode 100644 index 00000000000..c2199bb0d21 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/improve-flaky-test.md @@ -0,0 +1,15 @@ +--- +title: Improve flaky test detection +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Improve flaky test detection +hide_comments: true +--- + +# Improve flaky test detection + +This feature will improve the flaky test detection logic and it will be user configurable so that each organization can define what is important to them. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/new-test-plans-directory.md b/release-notes/roadmap/2025/testplans/new-test-plans-directory.md new file mode 100644 index 00000000000..636804feb3f --- /dev/null +++ b/release-notes/roadmap/2025/testplans/new-test-plans-directory.md @@ -0,0 +1,24 @@ +--- +title: New Test Plans directory +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: New Test Plans directory +hide_comments: true +--- + +# New Test Plans directory + +Stay organized and save time with the New Test Plans Directory. We will introduce several enhancements to help you manage test plans more efficiently, giving you greater control over your workspace and reducing repetitive tasks. + +Here’s what’s will be included: + +* Cleaner UI Design: Navigate your test plans with ease using a modern interface that improves readability and reduces clutter, allowing you to focus on your tasks without distractions. +* Column Sorting: Find what you need faster by sorting columns based on name, status, or other key attributes. This feature helps you quickly organize and prioritize your test plans for better productivity. +* Team Filter in the "All" Tab: Focus on what matters by filtering test plans by team, ensuring you only see relevant plans that align with your work and goals. +* Persistent Filters: Save time with persistent filters that remember your settings. When you return to the page, your previously applied filters will stay intact, providing an organized view without needing to reapply filters every time. + +These updates are designed to streamline your workflow, reduce repetitive tasks, and make it easier to track and manage your test plans. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/new-test-run-experience.md b/release-notes/roadmap/2025/testplans/new-test-run-experience.md new file mode 100644 index 00000000000..85881d24115 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/new-test-run-experience.md @@ -0,0 +1,15 @@ +--- +title: New Test Run experience +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: New Test Run experience +hide_comments: true +--- + +# New Test Run experience + +Easily track test results across iterations with the revamped Test Run tab. We’re simplifying workflows and providing a more test run-centric view to help you track results more intuitively and improve traceability across test cycles. With this update, you’ll benefit from pipeline-based filtering, making it easier to connect test results to specific builds and artifacts. The new design ensures faster navigation, giving you quick access to key metrics without the need for tedious queries. These enhancements aim to make your test tracking process more seamless, allowing you to focus on your testing outcomes rather than navigating through complex workflows. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/quick-access-to-test-results.md b/release-notes/roadmap/2025/testplans/quick-access-to-test-results.md new file mode 100644 index 00000000000..3edea3d784d --- /dev/null +++ b/release-notes/roadmap/2025/testplans/quick-access-to-test-results.md @@ -0,0 +1,17 @@ +--- +title: Quick access to Test Results in Test Case +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Quick access to Test Results in Test Case +hide_comments: true +--- + +# Quick access to Test Results in Test Case + +Quickly access recent test case results directly from the test case work item. We’ve introduced a new "Recent test results" section that provides direct visibility into the latest test results, eliminating the need to navigate through test plans or suites. + +With this update, you can review key test details at a glance and track recent test results more efficiently. For deeper insights, we’ve also added a direct link to view the complete result history of the test case, giving you quick access to all past runs in one place. These enhancements aim to streamline your workflow, making it easier to track progress and explore test history without interruptions. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/quick-access.md b/release-notes/roadmap/2025/testplans/quick-access.md new file mode 100644 index 00000000000..b50f2f3e046 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/quick-access.md @@ -0,0 +1,15 @@ +--- +title: Quick access to test results and Run ID in web runner +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Quick access to test results and Run ID in web runner +hide_comments: true +--- + +# Quick access to test results and Run ID in web runner + +This feature simplifies tracking and reviewing test run results by displaying the Run ID upfront and providing a direct path to your results. The Run ID now appears automatically when a test run starts in web runner, making it easier to reference and track. After completion, a dialog guides you straight to the results page, reducing the need to navigate through test plans or suites. These updates enhance traceability and efficiency, ensuring quick, seamless access to your test run information. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/recent-test-result.md b/release-notes/roadmap/2025/testplans/recent-test-result.md new file mode 100644 index 00000000000..b04f872d227 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/recent-test-result.md @@ -0,0 +1,15 @@ +--- +title: Latest Test Outcome in Requirements +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Latest Test Outcome in Requirements +hide_comments: true +--- + +# Latest Test Outcome in Requirements + +Get real-time updates on test progress directly within the user story work item. You can now see a snippet of the most recent test case result in the Related Work section, showing key details like the outcome and completion time without needing extra navigation. This update brings consistency between the Boards view and user stories, making it faster and easier to track test progress at a glance. These improvements aim to enhance traceability and streamline your workflow, helping you stay focused on what matters most. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/restore-deleted-test-plans.md b/release-notes/roadmap/2025/testplans/restore-deleted-test-plans.md new file mode 100644 index 00000000000..ab227ea3c5f --- /dev/null +++ b/release-notes/roadmap/2025/testplans/restore-deleted-test-plans.md @@ -0,0 +1,15 @@ +--- +title: Restore deleted test plans and test suites using REST API +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Restore deleted test plans and test suites using REST API +hide_comments: true +--- + +# Restore deleted test plans and test suites using REST API + +Easily restore deleted test plans and test suites with new self-service APIs. We are introducing GET and PATCH APIs that allow you to look up deleted test plans or suites and restore them along with their child items—all without needing customer support. With these APIs, you can quickly recover accidentally deleted test work items, reducing downtime and improving productivity. While run artifacts won’t be restored, all related test plans, suites, and test cases can be brought back to your workspace with ease. This self-service feature gives you greater control over test management and streamlines the restoration process, making it faster and more efficient to recover critical test assets. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/resume-paused-test-cases.md b/release-notes/roadmap/2025/testplans/resume-paused-test-cases.md new file mode 100644 index 00000000000..1a6574d6d69 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/resume-paused-test-cases.md @@ -0,0 +1,15 @@ +--- +title: Resume paused test cases on by default +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Resume paused test cases on by default +hide_comments: true +--- + +# Resume paused test cases on by default + +Quickly resume your paused test cases with a single click. We've made "Resume" the default action for paused test cases, allowing you to pick up right where you left off without extra navigation. This update makes it faster and easier to continue your work without interruption. To further protect your progress, we're introducing a confirmation prompt to prevent accidental overwrites of paused test progress. This safeguard ensures your partially saved work stays intact, giving you peace of mind while managing your test runs. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/seamless-build-pipelines.md b/release-notes/roadmap/2025/testplans/seamless-build-pipelines.md new file mode 100644 index 00000000000..57dc8bfb13f --- /dev/null +++ b/release-notes/roadmap/2025/testplans/seamless-build-pipelines.md @@ -0,0 +1,15 @@ +--- +title: Seamless build pipeline integration for Test Case Run +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Seamless build pipeline integration for Test Case Run +hide_comments: true +--- + +# Seamless build pipeline integration for Test Case Run + +Save time with automatic build pipeline configurations in the test web runner. With this new feature, build definitions and IDs set at the test plan level now automatically carry over to the test web runner, eliminating the need to manually configure them each time you run tests. This enhancement helps you streamline your test case run, ensuring that relevant build pipelines are ready to go and allowing you to focus on what matters most—executing tests efficiently. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/support-for-java-playwright.md b/release-notes/roadmap/2025/testplans/support-for-java-playwright.md new file mode 100644 index 00000000000..945c23d709a --- /dev/null +++ b/release-notes/roadmap/2025/testplans/support-for-java-playwright.md @@ -0,0 +1,15 @@ +--- +title: Support for Java (Playwright) in Azure Test Plans +author: alexpysanets +ms.author: alexpysanets +ms.date: 04/22/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support for Java (Playwright) in Azure Test Plans +hide_comments: true +--- + +# Support for Java (Playwright) in Azure Test Plans + +Currently it is possible to [associate](/azure/devops/test/associate-automated-test-with-test-case?view=azure-devops) VSTest automated tests to test cases which are part of Test Plans. We are going to expand the list of supported frameworks and allow linking and executing automated tests written in Java (Playwright). The association can be performed directly in Azure DevOps. diff --git a/release-notes/roadmap/2025/testplans/support-for-javascript.md b/release-notes/roadmap/2025/testplans/support-for-javascript.md new file mode 100644 index 00000000000..b0b649374f1 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/support-for-javascript.md @@ -0,0 +1,15 @@ +--- +title: Support for JavaScript in Azure Test Plans +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support for JavaScript in Azure Test Plans +hide_comments: true +--- + +# Support for JavaScript in Azure Test Plans + +Currently it is possible to link VSTest, Junit / Java and Python / PyTest automated tests to test cases which are part of Test Plans. We are going to expand the list of supported frameworks and allow linking and executing automated tests written with JavaScript. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/support-for-jest.md b/release-notes/roadmap/2025/testplans/support-for-jest.md new file mode 100644 index 00000000000..f7091376fd6 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/support-for-jest.md @@ -0,0 +1,15 @@ +--- +title: Support for JavaScript (Jest) in Azure Test Plans +author: gloridelmorales +ms.author: glmorale +ms.date: 04/18/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support for JavaScript (Jest) in Azure Test Plans +hide_comments: true +--- + +# Support for JavaScript (Jest) in Azure Test Plans + +Currently it is possible to [associate](/azure/devops/test/associate-automated-test-with-test-case?view=azure-devops) VSTest automated tests to test cases which are part of Test Plans. We are going to expand the list of supported frameworks and allow linking and executing automated tests written in JavaScript (Jest). The association can be performed directly in Azure DevOps. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/support-for-junit.md b/release-notes/roadmap/2025/testplans/support-for-junit.md new file mode 100644 index 00000000000..b98a2881704 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/support-for-junit.md @@ -0,0 +1,15 @@ +--- +title: Support for JUnit/Java in Azure Test Plans +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support for JUnit/Java in Azure Test Plans +hide_comments: true +--- + +# Support for JUnit/Java in Azure Test Plans + +Currently it is possible to link VSTest automated tests to test cases which are part of Test Plans. We are going to expand the list of supported frameworks and allow linking and executing automated tests written with JUnit / Java. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/support-for-phpunit-pest.md b/release-notes/roadmap/2025/testplans/support-for-phpunit-pest.md new file mode 100644 index 00000000000..d8cce8e45e0 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/support-for-phpunit-pest.md @@ -0,0 +1,15 @@ +--- +title: Support for PHP (PHPUnit & Pest) in Azure Test Plans +author: gloridelmorales +ms.author: glmorale +ms.date: 04/18/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support for PHP (PHPUnit & Pest) in Azure Test Plans +hide_comments: true +--- + +# Support for PHP (PHPUnit & Pest) in Azure Test Plans + +Currently it is possible to associate VSTest automated tests to test cases which are part of Test Plans. We are going to expand the list of supported frameworks and allow linking and executing automated tests written in PHP (PHPUnit & Pest). The association can be performed directly in Azure DevOps. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/support-for-playwright.md b/release-notes/roadmap/2025/testplans/support-for-playwright.md new file mode 100644 index 00000000000..4347b5c50cb --- /dev/null +++ b/release-notes/roadmap/2025/testplans/support-for-playwright.md @@ -0,0 +1,15 @@ +--- +title: Support for JavaScript (Playwright) in Azure Test Plans +author: gloridelmorales +ms.author: glmorale +ms.date: 04/17/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support for JavaScript (Playwright) in Azure Test Plans +hide_comments: true +--- + +# Support for JavaScript (Playwright) in Azure Test Plans + +Currently it is possible to [associate](/azure/devops/test/associate-automated-test-with-test-case?view=azure-devops) VSTest automated tests to test cases which are part of Test Plans. We are going to expand the list of supported frameworks and allow linking and executing automated tests written in JavaScript (Playwright). The association can be performed directly in Azure DevOps. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/support-for-pytest.md b/release-notes/roadmap/2025/testplans/support-for-pytest.md new file mode 100644 index 00000000000..19fc1011165 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/support-for-pytest.md @@ -0,0 +1,15 @@ +--- +title: Support for Pytest/Python in Azure Test Plans +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support for Pytest/Python in Azure Test Plans +hide_comments: true +--- + +# Support for Pytest/Python in Azure Test Plans + +Currently it is possible to link VSTest automated tests to test cases which are part of Test Plans. We are going to expand the list of supported frameworks and allow linking and executing automated tests written in Pytest / Python. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/support-unittest-robot.md b/release-notes/roadmap/2025/testplans/support-unittest-robot.md new file mode 100644 index 00000000000..faf9a41e07b --- /dev/null +++ b/release-notes/roadmap/2025/testplans/support-unittest-robot.md @@ -0,0 +1,15 @@ +--- +title: Support for Python (UnitTest & Robot) in Azure Test Plans +author: gloridelmorales +ms.author: glmorale +ms.date: 04/18/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support for Python (UnitTest & Robot) in Azure Test Plans +hide_comments: true +--- + +# Support for Python (UnitTest & Robot) in Azure Test Plans + +Currently it is possible to [associate](/azure/devops/test/associate-automated-test-with-test-case?view=azure-devops) VSTest automated tests to test cases which are part of Test Plans. We are going to expand the list of supported frameworks and allow linking and executing automated tests written in Python (UnitTest & Robot). The association can be performed directly in Azure DevOps. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/support-yaml-pipelines.md b/release-notes/roadmap/2025/testplans/support-yaml-pipelines.md new file mode 100644 index 00000000000..9a15e73fbf7 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/support-yaml-pipelines.md @@ -0,0 +1,15 @@ +--- +title: Support YAML pipelines in Azure Test Plans +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Support YAML pipelines in Azure Test Plans +hide_comments: true +--- + +# Support YAML pipelines in Azure Test Plans + +Currently, it is possible to link automated tests to test cases and execute them from the Test Plans interface. Users need to select a build/release pipeline for execution. With the upcoming update, we will support the selection of YAML pipelines, in addition to the existing support for classic pipelines. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/undo-test-step.md b/release-notes/roadmap/2025/testplans/undo-test-step.md new file mode 100644 index 00000000000..79f796d67e8 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/undo-test-step.md @@ -0,0 +1,15 @@ +--- +title: Undo test step in web and desktop runner +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Undo test step in web and desktop runner +hide_comments: true +--- + +# Undo test step in web and desktop runner + +Take control of your test case run with the new "Undo" option. You can easily revert test step statuses with a simple double-click, giving you more flexibility and control during test runs. No more restarting test cases to fix accidental clicks—just undo and continue your workflow without interruption. We are also introducing keyboard-friendly navigation and accessibility improvements to ensure this feature works seamlessly for all users, including those who rely on assistive technologies. This enhancement will help you save time, reduce frustration, and stay focused on running tests efficiently. \ No newline at end of file diff --git a/release-notes/roadmap/2025/testplans/view-state-execute-tab.md b/release-notes/roadmap/2025/testplans/view-state-execute-tab.md new file mode 100644 index 00000000000..25f393d7c26 --- /dev/null +++ b/release-notes/roadmap/2025/testplans/view-state-execute-tab.md @@ -0,0 +1,17 @@ +--- +title: View Test Case State in Execute Tab +author: gloridelmorales +ms.author: glmorale +ms.date: 04/18/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: View Test Case State in Execute Tab +hide_comments: true +--- + +# View Test Case State in Execute Tab + +You can now add the "Test Case State" column to the Execute tab to quickly see the status of each test case. Whether it’s Approved, In Progress, or any other state, this update gives you clearer visibility into test readiness—without switching browser tabs or running complex queries. + +The column is optional and can be enabled via the column picker. It also aligns with the existing “State” filter, allowing you to filter and view test case states side by side, all in one place. This enhancement helps ensure testers begin execution with test cases that are truly Ready or Approved, reducing the risk of running incomplete or draft items—and making your test runs more efficient from the start. \ No newline at end of file diff --git a/release-notes/roadmap/2025/workload-identity-federation.md b/release-notes/roadmap/2025/workload-identity-federation.md new file mode 100644 index 00000000000..8df5535696b --- /dev/null +++ b/release-notes/roadmap/2025/workload-identity-federation.md @@ -0,0 +1,15 @@ +--- +title: Workload identity federation using Entra-issued tokens +author: gloridelmorales +ms.author: glmorale +ms.date: 01/20/2025 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Workload identity federation using Entra-issued tokens +hide_comments: true +--- + +# Workload identity federation using Entra-issued tokens + +[Workload identity federation (WIF)](https://devblogs.microsoft.com/devops/workload-identity-federation-for-azure-deployments-is-now-generally-available/) enables deployment from Azure Pipelines to Azure without using secrets. The current implementation of WIF relies on an ID token issued by Azure DevOps, which is then exchanged for an Entra-issued access token. In the next revision, the ID token will also be issued by Entra instead of Azure DevOps. This change will enhance security by leveraging all the mechanisms available in Entra to protect the ID tokens. Once this feature is rolled out, all newly created service connections will use Entra-issued ID tokens. Additionally, you will have the option to convert your existing service connections to use the new scheme. diff --git a/release-notes/roadmap/access-events-for-pat.md b/release-notes/roadmap/access-events-for-pat.md deleted file mode 100644 index fe81d5a14ee..00000000000 --- a/release-notes/roadmap/access-events-for-pat.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Access events for PAT, SSH will be available in the Auditing Log -author: gloridelmorales -ms.author: glmorale -ms.date: 10/11/2022 -ms.topic: article -ms.service: azure-devops -ms.subservice: azure-devops-release-notes -description: Access events for PAT, SSH will be available in the Auditing Log -hide_comments: true ---- - -# Access events for PAT, SSH will be available in the Auditing Log - -Usage of (Personal Access Tokens) PATs, SSH keys, or OAuth for signing in to the service for an API call will be added to the Auditing log. \ No newline at end of file diff --git a/release-notes/roadmap/conditional-access-policy.md b/release-notes/roadmap/conditional-access-policy.md index 30220f64855..1dead782461 100644 --- a/release-notes/roadmap/conditional-access-policy.md +++ b/release-notes/roadmap/conditional-access-policy.md @@ -1,18 +1,20 @@ --- -title: Full support for Conditional Access Policies +title: Full web support for Conditional Access Policies author: gloridelmorales ms.author: glmorale ms.date: 10/11/2022 ms.topic: article ms.service: azure-devops ms.subservice: azure-devops-release-notes -description: Full support for Conditional Access Policies +description: Full web support for Conditional Access Policies hide_comments: true --- -# Full support for Conditional Access Policies +# Full web support for Conditional Access Policies -Today, Azure DevOps supports all [conditional access policies](/azure/active-directory/conditional-access/overview) set on the Azure Active Directory tenant for web and interactive flows during initial signin. Once a user has signed in, however, only IP-fencing policies are supported on an ongoing basis. We will invest in deepening Azure DevOps' integration with Azure Active Directory such that *all* conditional acess policies are continuously evaluated - typically on an hourly basis. This will improve support for policies like [device compliance](/azure/active-directory/conditional-access/howto-conditional-access-policy-compliant-device), which can be used to prevent usage from devices that fail to meet a variety of compliance requirements. +Today, Azure DevOps supports all [conditional access policies](/azure/active-directory/conditional-access/overview) set on the Azure Active Directory tenant for web and interactive flows during initial signin. Once a user has signed in, however, only IP-fencing policies are supported on an ongoing basis. We will invest in deepening Azure DevOps' integration with Azure Active Directory such that *all* conditional access policies are continuously evaluated - typically on an hourly basis. This will improve support for policies like [device compliance](/azure/active-directory/conditional-access/howto-conditional-access-policy-compliant-device), which can be used to prevent usage from devices that fail to meet a variety of compliance requirements. > [!NOTE] > Non-interactive flows - for example, requests made programmatically using Personal Access Tokens - will continue to only support IP-fencing conditional access policies. + +Updated web session authentication is now available on all Azure DevOps Services web pages for most modern browsers. diff --git a/release-notes/roadmap/deprecate-old-azure-artifacts.md b/release-notes/roadmap/deprecate-old-azure-artifacts.md index e70ecbac648..444cf9c19cd 100644 --- a/release-notes/roadmap/deprecate-old-azure-artifacts.md +++ b/release-notes/roadmap/deprecate-old-azure-artifacts.md @@ -21,4 +21,9 @@ We now have the following lightweight, auth-only tasks in GA that we recommend c 1. Maven Authenticate 2. NuGet Authenticate 3. Python Pip Authenticate -4. Python Twine Upload Authenticate \ No newline at end of file +4. Python Twine Upload Authenticate + +> [!Important] +> Migration Notice: +> For those using the NuGetRestoreV1 and NuGetInstallerV0 pipeline tasks, it's imperative to transition to the NuGetCommand@2 pipeline task as soon as possible. Warnings will be issued in your pipelines soon. If no action is taken, starting November 27th, 2023, your builds will fail. + diff --git a/release-notes/roadmap/disable-alternate-auth-policy.md b/release-notes/roadmap/disable-alternate-auth-policy.md index 9395d41089a..1174dfc398d 100644 --- a/release-notes/roadmap/disable-alternate-auth-policy.md +++ b/release-notes/roadmap/disable-alternate-auth-policy.md @@ -1,16 +1,17 @@ --- -title: Policies to disable alternate authentication credentials +title: Policies to disable personal access token creation author: gloridelmorales ms.author: glmorale ms.date: 10/11/2022 ms.topic: article ms.service: azure-devops ms.subservice: azure-devops-release-notes -description: Policies to disable alternate authentication credentials +description: Policies to disable personal access token creation hide_comments: true --- -# Policies to disable alternate authentication credentials +# Policies to disable the creation of personal access tokens (PAT) -As we add support for more secure alternatives such as [Managed Identities and Service Principals](./support-azure-managed-identities.md) that reduce the need for PATs and other stealable secrets, administrators need new control plane policies to improve authentication security by reducing and even blocking the usage of less secure authentication methods. We will introduce new control plane policies that administrators can use to reduce or turn off use of less secure authentication methods like basic auth (plain text user name and password), Personal Access Tokens (PATs) and SSH keys. These policies will come with an exception list that allows admins to gradually reduce the use of these less secure methods without disrupting their critical business processes. +As we add support for secure alternatives such as Managed Identities and Service Principals that reduce the need for personal access tokens (PATs) and other stealable secrets, administrators need new control plane policies to improve authentication security by reducing and even blocking the creation of less secure authentication methods. While basic authentication (plain text user name and password) has been deprecated in Azure DevOps and there is an existing organization policy to turn off using SSH keys already, the ability to turn off PATs was not previously available. Current control plane policies seek to limit the power and longevity of PATs. +To that effect, we will be introducing a new control plane policy that administrators can use to reduce or turn off the creation of personal access tokens (PATs). This organizational policies will come with an exception list that allows admins to gradually reduce the creation and usage of personal access tokens (PAT) among their organization without disrupting critical business processes. \ No newline at end of file diff --git a/release-notes/roadmap/future.md b/release-notes/roadmap/future.md index af661e60d53..4c07a419bd4 100644 --- a/release-notes/roadmap/future.md +++ b/release-notes/roadmap/future.md @@ -45,11 +45,7 @@ Auditing service available in all geographies and to all customers. ### Conditional Access Policy support for device state -Azure DevOps to honor any conditional access policies that include [devihttps://docs.microsoft.com/azure/active-directory/conditional-access/concept-conditional-access-conditions#device-state-previewce state]conditions. - -### Access events for PAT, SSH will be available in the Auditing Log - -Usage of (Personal Access Tokens) PATs, SSH keys, or OAuth for signing in to the service for an API call will be added to the Auditing log. +Azure DevOps to honor any conditional access policies that include [device state conditions](/azure/active-directory/conditional-access/concept-conditional-access-conditions#device-state-preview). ## Artifacts diff --git a/release-notes/roadmap/granular-scopes.md b/release-notes/roadmap/granular-scopes.md index 09622384e80..b9effcf8ff1 100644 --- a/release-notes/roadmap/granular-scopes.md +++ b/release-notes/roadmap/granular-scopes.md @@ -14,7 +14,7 @@ hide_comments: true We are bringing support for granular Azure DevOps scopes that can be used to limit the behavior of the Azure Active Directory OAuth applications that integrate with Azure DevOps. -By setting scopes on an application, you can limit the operations (e.g. writing to work items, viewing source code, configuring pipelines, etc.) an application can do when connecting to Azure DevOps on behalf of the user. Apps that use a single broad user impersonation scope that allows the app to perform any operations that the underlying user is permitted to do can now use the granular scopes to limit its behavior. For example, an app that is only reading work items can be given only a workitem_read scope so that it can't do anything outside of this behavior intentionaly or otherwise. +By setting scopes on an application, you can limit the operations (e.g. writing to work items, viewing source code, configuring pipelines, etc.) an application can do when connecting to Azure DevOps on behalf of the user. Apps that use a single broad user impersonation scope that allows the app to perform any operations that the underlying user is permitted to do can now use the granular scopes to limit its behavior. For example, an app that is only reading work items can be given only a workitem_read scope so that it can't do anything outside of this behavior intentionally or otherwise. Adding scopes to an application will require that any applications you integrate with must first declare what they are attempting to do for you by defining these scopes ahead of time. These scopes will be available for you to review before consenting to authorizing this app to perform actions on your behalf. This ensures you have more visibility on what an application is doing with resources you have access to. diff --git a/release-notes/roadmap/macos-agents-apple-silicon.md b/release-notes/roadmap/macos-agents-apple-silicon.md new file mode 100644 index 00000000000..f316d5fb3e3 --- /dev/null +++ b/release-notes/roadmap/macos-agents-apple-silicon.md @@ -0,0 +1,15 @@ +--- +title: Hosted macOS agents on Apple Silicon +author: geekzter +ms.author: ericvan +ms.date: 11/22/2024 +ms.topic: article +ms.service: azure-devops +ms.subservice: azure-devops-release-notes +description: Hosted macOS agents on Apple Silicon +hide_comments: true +--- + +# Hosted macOS agents on Apple Silicon + +Customers have been waiting for Apple Silicon (Arm64) support on Microsoft-hosted macOS agents in Azure Pipelines. We can't support this, or provide larger SKUs of macOS agents, because our current uniform billing model across Linux, Windows, and macOS-hosted agents is unable to support them. We are working on a solution. diff --git a/release-notes/roadmap/support-flexible-orchestration-mode.md b/release-notes/roadmap/support-flexible-orchestration-mode.md deleted file mode 100644 index 0c3fa8a43db..00000000000 --- a/release-notes/roadmap/support-flexible-orchestration-mode.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Support Flexible Orchestration mode in scale set agent pools -author: gloridelmorales -ms.author: glmorale -ms.date: 10/11/2022 -ms.topic: article -ms.service: azure-devops -ms.subservice: azure-devops-release-notes -description: Support Flexible Orchestration mode in scale set agent pools -hide_comments: true ---- - -# Support Flexible Orchestration mode in scale set agent pools - -A common complaint with scale set agent pools is that the time it takes to initiate scaling events is too long. In fact, Azure Pipelines checks if it needs to scale out a pool every few minutes. However, it cannot perform that task if there is a prior operation already in progress on the VM scale set. As an example, if the VM scale set is deleting VMs from an earlier request to scale in, then Azure Pipelines cannot issue a new request to scale out unless that previous operation is complete. - -To address this problem, Azure Pipelines needs to rely on a new preview feature of VM scale sets called [Flexible Orchestration](/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-orchestration-modes). As this feature comes out of preview in VM scale sets, Azure Pipelines will start making use of it and speed up its operations. \ No newline at end of file